Carlos Florêncio
68 lines
2.8 KiB
Markdown
68 lines
2.8 KiB
Markdown
---
|
||
id: "04-dev-command"
|
||
title: "dev command, web port, and dev env wiring"
|
||
status: done
|
||
wave: 2
|
||
depends_on: ["01-dev-paths"]
|
||
plan: "plan.md"
|
||
spec: "../../specs/platform/requirements/go-dev-launcher.md"
|
||
---
|
||
|
||
# Task 04: `dev` command, web port, and dev env wiring
|
||
|
||
Teach the launcher's arg parser, port picker, and env builder about dev mode.
|
||
|
||
## Acceptance
|
||
|
||
- `parseArgs` accepts `dev` and `--dev` (→ `CommandDev`), `--web-internal-port <n>` and
|
||
`--web-internal-port=<n>`, and rejects `--web-port` with the existing message
|
||
"`--web-port` has been removed; use `--web-internal-port` for dev mode" and
|
||
`--web-internal-port` outside dev mode with "only applies to dev mode". Port values
|
||
keep the 1–65535 validation and the existing `ParseError` exit code 2.
|
||
- `pickDevPorts` resolves the web port from the flag then `KANDEV_WEB_PORT`, defaults to
|
||
`37429`, and guarantees backend, web, and agentctl ports are mutually distinct. An
|
||
explicitly requested but occupied web port is a hard error naming the port and whether
|
||
it came from the flag or the env var, matching the backend-port preflight from
|
||
PR #2394.
|
||
- `backendEnv` sets `KANDEV_WEB_INTERNAL_URL=http://localhost:<webPort>` when a web port
|
||
is present and `KANDEV_DEBUG_DEV_MODE=true` in dev mode, and leaves `start`/`run`
|
||
output byte-identical to today when it is not.
|
||
- `cli.Help()` documents `dev` and `--web-internal-port`.
|
||
|
||
## Verification
|
||
|
||
Use TDD across the existing suites, then:
|
||
|
||
~~~bash
|
||
cd apps/backend && go test ./internal/launcher/ -race
|
||
~~~
|
||
|
||
## Files
|
||
|
||
- `apps/backend/internal/launcher/options.go`, `options_test.go`
|
||
- `apps/backend/internal/launcher/ports.go`, `ports_test.go`
|
||
- `apps/backend/internal/launcher/env.go`, `env_test.go`
|
||
- `apps/backend/internal/launcher/cli/help.go`
|
||
- `apps/backend/internal/launcher/launcher.go` — dispatch `CommandDev` to `runDev`
|
||
(a stub returning "not implemented" is acceptable here; task 05 fills it in).
|
||
|
||
## Inputs
|
||
|
||
- `apps/cli/src/args.ts:22-138` — the exact flag surface and error strings to preserve.
|
||
- `apps/cli/src/cli.ts:13-58` — the help text wording for `dev` and
|
||
`--web-internal-port`.
|
||
- `apps/backend/internal/launcher/ports.go:65-91` — `pickPorts` and the `used` map;
|
||
extend rather than fork it.
|
||
- `apps/backend/internal/launcher/supervisor.go:169-190` — `allowedSupervisorEnv`
|
||
already allowlists `KANDEV_WEB_INTERNAL_URL` and `KANDEV_DEBUG_DEV_MODE`; confirm, do
|
||
not duplicate.
|
||
|
||
## Risks
|
||
|
||
- `portConfig.WebPort` must be optional. `start` and `run` have no web port and
|
||
`backendEnv` must not emit an empty `KANDEV_WEB_INTERNAL_URL` for them — the
|
||
TypeScript version explicitly deletes the key in that case
|
||
(`apps/cli/src/shared.ts:85-87`).
|
||
- Watch the Go complexity limits in `apps/backend/.golangci.yml`; `parseArgAt` is
|
||
already a dispatch chain, so add a `parseWebPortArg` helper rather than growing it.
|