Files
kandev/docs/plans/go-dev-launcher/plan.md
T
2026-08-24 11:09:03 +00:00

154 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
status: implemented
created: 2026-08-07
spec: "../../specs/platform/requirements/go-dev-launcher.md"
---
# Plan: Go dev launcher and minimal Node surface
## Current state
`apps/backend/internal/launcher` already implements everything `dev` needs except the
dev-specific pieces. Reusable as-is:
| Concern | Location |
| --- | --- |
| Arg parsing, `ParseError`, port flags | `options.go` |
| Port selection, explicit-port preflight, `canBind` | `ports.go` |
| Health probe with launcher token, foreign-process detection | `health.go` |
| Process supervision, groups, Ctrl-C, force-kill, ring-buffered output | `process.go`, `process_group_{unix,windows}.go` |
| Restart control socket + launch manifest | `supervisor.go` |
| Backend env assembly | `env.go` |
| Startup banner, browser open, `waitForAppExit` | `start.go` |
Two details matter for the design:
- `supervisor.go:169` `allowedSupervisorEnv` already allowlists
`KANDEV_WEB_INTERNAL_URL` and `KANDEV_DEBUG_DEV_MODE`. No change needed there.
- `supervisor.go:41` `launchRestartableBackend` calls `resolveHomeDir()` internally,
reading the launcher's own environment. Dev needs a repo-local home, so this must
become an explicit parameter (task 05).
Gaps, all dev-only:
1. No `dev` command, no `--web-internal-port`, no `WebPort` in `portConfig`.
2. No repo-root discovery, `.kandev-dev` home, or task-workspace detection.
3. No production-DB backup.
4. No Vite child launch or token-less URL readiness probe.
## Approach
Port `dev` into the Go launcher in three waves: pure helpers first (independently
testable, no ordering constraints between them), then command wiring and orchestration,
then the Makefile cutover and the TypeScript deletion.
The deletion is deliberately last and in its own task. Until `make dev` is proven on the
Go path, `apps/cli/src/**` is the rollback.
### Design decisions
**Backend child stays `make -C apps/backend dev`.** Re-execing `self __backend` (what
`start` does) would be simpler but would silently drop rebuild-on-restart, which is the
point of the restart button in dev. Keeping `make` preserves it.
**`make dev` execs a copy of the binary.** Because launcher and backend are one binary,
the child `make` rebuilds `bin/kandev` underneath the running launcher. On Linux/macOS
`go build` unlinks before writing so the running process survives; on Windows the delete
fails and the rebuild errors. Exec'ing `bin/kandev-launcher` (a copy made after `build`)
removes the hazard on every platform for one `cp`.
**Vite readiness is a separate probe.** `waitForHealth` requires the launcher health
token by design (PR #2394 made a token mismatch a hard failure). Vite emits no such
token, so it needs its own probe that accepts any HTTP response. Do not weaken
`waitForHealth` to accommodate it.
## Dependency order
```text
wave 1 task-01 dev paths task-02 db backup task-03 web child
│ │ │
wave 2 └────────┬──────────────┴──────────────────────┘
├── task-04 dev command wiring
└── task-05 runDev orchestration (depends on 01–04)
│
wave 3 ┌─────────────────────┼─────────────────────┐
task-06 Makefile task-07 delete TS task-08 docs
(depends on 06)
```
Wave 1 tasks touch disjoint new files and are parallel-safe. Wave 3's task-07 must follow
task-06, because deleting `apps/cli/src` before the Makefile switches would break
`make dev` outright.
## Tasks
| ID | Title | Wave | Status |
| --- | --- | --- | --- |
| 01 | Dev paths, repo root, and dev backend env | 1 | done |
| 02 | Production database backup in Go | 1 | done |
| 03 | Vite dev-server child and URL readiness | 1 | done |
| 04 | `dev` command, web port, and dev env wiring | 2 | done |
| 05 | `runDev` orchestration | 2 | done |
| 06 | Makefile cutover to the Go dev launcher | 3 | done |
| 07 | Delete `apps/cli/src` and drop CLI devDependencies | 3 | done |
| 08 | Documentation and guidance updates | 3 | done |
## Likely files
New under `apps/backend/internal/launcher/`:
`devpaths.go`, `devpaths_test.go`, `backup.go`, `backup_test.go`, `webchild.go`,
`webchild_test.go`, `dev.go`, `dev_test.go`.
Modified: `options.go`, `options_test.go`, `ports.go`, `ports_test.go`, `env.go`,
`env_test.go`, `supervisor.go`, `supervisor_test.go`, `launcher.go`, `cli/help.go`,
`constants.go`.
Root: `Makefile`, `apps/backend/Makefile`, `apps/cli/package.json`,
`apps/cli/bin/native-shim.test.mjs`, `apps/package.json`,
`.github/workflows/frontend-tests.yml`, `CLAUDE.md`,
`docs/remote-cloud-environment.md`.
Deleted: `apps/cli/src/**`, `apps/cli/tsconfig.json`, `apps/cli/vitest.config.ts`.
## Risks
- **Windows dev has no CI coverage.** `make test-windows` runs a unit subset, not a real
`make dev`. The winjob removal and the `cmd.exe /c pnpm` shim need manual verification
on Windows before merge, or the winjob line in `make dev` should stay until someone
can test. Call this out in the PR.
- **`pnpm -r exec tsc` breaks** once `apps/cli/tsconfig.json` is gone (Makefile:650).
Task 07 must convert `make typecheck` to explicit `--filter` arguments.
- **`knip` dead-code detection** may flag the trimmed `apps/cli` differently. Run
`pnpm run dead-code` as part of task 07.
- **Release flow reads `apps/cli/package.json`** in three places
(`release.yml:224,251,381`, `publish-npm.sh:134,259`). Task 07 must not touch `name`,
`version`, `bin`, `files`, or `optionalDependencies`.
- **`.kandev-dev` vs. inherited `KANDEV_HOME_DIR`.** The launcher's own
`resolveHomeDir()` reads the ambient env; inside a Kandev task workspace that env is
the parent backend's. Task 05's explicit-homeDir refactor is what prevents the dev
supervisor directory from landing in the parent's home.
## Verification
Per-task commands are in the task files. Before opening the PR:
```bash
make -C apps/backend test
make -C apps/backend lint
cd apps && pnpm --filter kandev test
```
Manual, on the branch, since no automated test covers the real launch:
```bash
make dev # backend + Vite come up, browser opens, Ctrl-C leaves nothing
make dev PORT=38500 WEB_PORT=37500
make dev-prod-db # verify a dev-prod-db-*.db lands in ~/.kandev/data/backups/
```
Confirm no stray processes after Ctrl-C:
```bash
pgrep -af 'kandev|vite' || echo clean
```