feat(cli): make --port the user-facing port flag (#737)

* feat(cli): add --port flag as the user-facing port knob

Introduces --port (and KANDEV_PORT) as the primary, command-aware port
flag: in start/run it sets the Go backend port (the proxy front door
the browser actually hits), and in dev it sets the Next dev server port.
--backend-port and --web-port still work but emit a one-time stderr
deprecation note pointing at --port and --web-internal-port respectively.

* feat(cli): print labelled "open:" URL on startup

Replaces the ambiguous "[kandev] url:" / "ready at" lines with a
labelled block that always shows the user-facing URL first, plus the
backend (api) and web (internal) URLs when they differ. Each command
now declares its own publicUrl: backend in start/run (where the Go
server reverse-proxies Next.js), web in dev (browser hits Next direct).

* style(cli): apply prettier formatting to args.test.ts

* refactor(cli): tighten arg parsing per review feedback

- Validate value-taking flags (--port, --backend-port, --web-internal-port,
  --web-port, --version) and reject missing/non-numeric values with a clear
  ParseError instead of leaking NaN into the port validator.
- Drop the test-only _resetWarnedFlagsForTest export and the module-level
  warned-flag set; parseArgs now returns deduped deprecatedFlags and cli.ts
  emits warnings command-aware (e.g. --backend-port → KANDEV_BACKEND_PORT
  in dev, where --port maps to web).
- Stop double-printing the "open:" URL: logStartupInfo now lists labelled
  backend (api) / web (internal) URLs only, leaving the post-readiness
  open: line as the single source of truth.
- Fix help text: --web-internal-port works in dev too.
- Drop multi-line JSDoc blocks per CLAUDE.md style guide.

* fix(cli): validate env-var ports and collapse comment to one-liner

Catches non-numeric KANDEV_PORT / KANDEV_BACKEND_PORT / KANDEV_WEB_PORT in
envPort with a clear ParseError instead of letting NaN reach
ensureValidPort. Drops a multi-line comment per CLAUDE.md style.

* fix(cli): reject non-integer port values

Number.isFinite accepts floats like 3000.5 which then fail downstream
in ensureValidPort with a generic message. Tighten parsePort and
envPort to require integers and add float tests for both flag and
env-var paths.

* fix(cli): reject out-of-range port values with flag-named errors

Adds 1-65535 range checks to parsePort and envPort so values like 0,
-1, or 65536 fail with a flag/env-var-named ParseError instead of
reaching ensureValidPort with a generic 'backend port' label.

* test(cli): cover KANDEV_WEB_PORT happy path and range validation

* test(cli): cover KANDEV_WEB_PORT in run/start mode too

* fix(cli): explicit CLI flag wins over env var for port resolution

Previously KANDEV_BACKEND_PORT silently overrode --port because each
process port resolved its own env var before the generic --port
fallback. New precedence per process: explicit CLI flag > generic
--port flag > explicit env var > generic KANDEV_PORT. Also relabel
the startup info from "backend (api)" / "web (internal)" to plain
"backend" / "web" — "internal" was misleading in dev where the web
URL is what users open.

* style(cli): collapse resolvePorts comment to one line

* fix(cli): reject empty --version= and empty port env vars

- --version= (no value after =) now throws ParseError instead of
  silently storing the empty string as the version tag.
- envPort distinguishes unset (undefined) from empty (""); an empty
  KANDEV_PORT / KANDEV_BACKEND_PORT / KANDEV_WEB_PORT is now treated
  as misconfiguration and fails fast.

* refactor(cli): make --port a plain alias for --backend-port

Drops the command-aware split where --port mapped to web in dev and
backend in run/start. --port and --backend-port now both set
options.backendPort regardless of command, and KANDEV_PORT is a plain
fallback for KANDEV_BACKEND_PORT. The whole point of the original
fix was that the *backend port* is the URL users actually open in
run/start (because the Go server reverse-proxies Next.js); a single
flag that always means "the backend port" matches that mental model
without per-command surprises.

Removes deprecationReplacement and the command-aware warning logic
since the two flags are now interchangeable. --web-port → --web-internal-port
deprecation stays.

* test(cli): re-add KANDEV_WEB_PORT run-mode coverage dropped in refactor
This commit is contained in:
José Almeida
2026-04-29 22:25:10 +01:00
committed by GitHub
parent 3d93d9e93c
commit 47ff0804a5
7 changed files with 335 additions and 100 deletions
+142
View File
@@ -0,0 +1,142 @@
import { describe, expect, it } from "vitest";
import { parseArgs, ParseError, resolvePorts } from "./args";
describe("parseArgs", () => {
it("defaults to the run command with no args", () => {
const { options, showHelp, deprecatedFlags } = parseArgs([]);
expect(options.command).toBe("run");
expect(showHelp).toBe(false);
expect(deprecatedFlags).toEqual([]);
});
it("parses --port and --port=<n> as the backend port", () => {
expect(parseArgs(["--port", "3000"]).options.backendPort).toBe(3000);
expect(parseArgs(["--port=3000"]).options.backendPort).toBe(3000);
});
it("parses --backend-port the same as --port (no deprecation note)", () => {
expect(parseArgs(["--backend-port=3447"]).options.backendPort).toBe(3447);
expect(parseArgs(["--backend-port=3447"]).deprecatedFlags).toEqual([]);
});
it("parses --web-internal-port without a deprecation note", () => {
const r = parseArgs(["--web-internal-port", "12345"]);
expect(r.options.webPort).toBe(12345);
expect(r.deprecatedFlags).toEqual([]);
});
it("records --web-port as deprecated", () => {
const r = parseArgs(["--web-port=8080"]);
expect(r.options.webPort).toBe(8080);
expect(r.deprecatedFlags).toEqual(["--web-port"]);
});
it("dedupes deprecated flags across repeats", () => {
const r = parseArgs(["--web-port=1", "--web-port=2"]);
expect(r.deprecatedFlags).toEqual(["--web-port"]);
});
it("reports --help via showHelp without exiting", () => {
expect(parseArgs(["--help"]).showHelp).toBe(true);
});
it("throws ParseError when a value-taking flag has no value", () => {
expect(() => parseArgs(["--port"])).toThrow(ParseError);
expect(() => parseArgs(["--port"])).toThrow(/--port requires a value/);
});
it("throws ParseError when the next token is another flag", () => {
expect(() => parseArgs(["--port", "--debug"])).toThrow(/--port requires a value/);
});
it("throws ParseError on a non-numeric port value", () => {
expect(() => parseArgs(["--port=abc"])).toThrow(/--port value must be an integer/);
});
it("throws ParseError on a non-integer port value", () => {
expect(() => parseArgs(["--port=3000.5"])).toThrow(/--port value must be an integer/);
});
it.each(["0", "-1", "65536"])("throws ParseError on out-of-range port %s", (val) => {
expect(() => parseArgs([`--port=${val}`])).toThrow(/--port value must be an integer between/);
});
it("throws ParseError on empty --port=", () => {
expect(() => parseArgs(["--port="])).toThrow(/--port value must be an integer/);
});
it("throws ParseError on empty --version=", () => {
expect(() => parseArgs(["--version="])).toThrow(/--version requires a value/);
});
});
describe("resolvePorts", () => {
it("returns undefined for both ports when nothing is set", () => {
const r = resolvePorts({ command: "run" }, {} as NodeJS.ProcessEnv);
expect(r).toEqual({ backendPort: undefined, webPort: undefined });
});
it("CLI backendPort wins over env vars", () => {
const r = resolvePorts({ command: "start", backendPort: 3000 }, {
KANDEV_BACKEND_PORT: "4000",
KANDEV_PORT: "5000",
} as NodeJS.ProcessEnv);
expect(r.backendPort).toBe(3000);
});
it("KANDEV_BACKEND_PORT wins over KANDEV_PORT (more specific env wins)", () => {
const r = resolvePorts({ command: "run" }, {
KANDEV_PORT: "5555",
KANDEV_BACKEND_PORT: "6666",
} as NodeJS.ProcessEnv);
expect(r.backendPort).toBe(6666);
});
it("falls back to KANDEV_PORT when KANDEV_BACKEND_PORT is not set", () => {
const r = resolvePorts({ command: "run" }, { KANDEV_PORT: "5555" } as NodeJS.ProcessEnv);
expect(r.backendPort).toBe(5555);
});
it("KANDEV_WEB_PORT sets the internal web port in dev", () => {
const r = resolvePorts({ command: "dev" }, { KANDEV_WEB_PORT: "8080" } as NodeJS.ProcessEnv);
expect(r.webPort).toBe(8080);
});
it("KANDEV_WEB_PORT sets the internal web port in run/start (backend stays undefined)", () => {
const r = resolvePorts({ command: "run" }, { KANDEV_WEB_PORT: "8080" } as NodeJS.ProcessEnv);
expect(r).toEqual({ backendPort: undefined, webPort: 8080 });
});
it("--port maps to backend in every command (including dev)", () => {
const r = resolvePorts({ command: "dev", backendPort: 3447 }, {} as NodeJS.ProcessEnv);
expect(r).toEqual({ backendPort: 3447, webPort: undefined });
});
it("throws ParseError when KANDEV_PORT is not a number", () => {
expect(() =>
resolvePorts({ command: "run" }, { KANDEV_PORT: "abc" } as NodeJS.ProcessEnv),
).toThrow(ParseError);
});
it("throws ParseError when KANDEV_PORT is a float", () => {
expect(() =>
resolvePorts({ command: "run" }, { KANDEV_PORT: "3000.5" } as NodeJS.ProcessEnv),
).toThrow(/KANDEV_PORT must be an integer/);
});
it.each(["0", "-1", "65536"])("throws ParseError when KANDEV_PORT is out-of-range %s", (val) => {
expect(() =>
resolvePorts({ command: "run" }, { KANDEV_PORT: val } as NodeJS.ProcessEnv),
).toThrow(/KANDEV_PORT must be an integer between/);
});
it.each(["KANDEV_PORT", "KANDEV_BACKEND_PORT", "KANDEV_WEB_PORT"])(
"throws ParseError when %s is set to empty string",
(name) => {
expect(() => resolvePorts({ command: "run" }, { [name]: "" } as NodeJS.ProcessEnv)).toThrow(
new RegExp(`${name} must be an integer`),
);
},
);
});