Add managed local dev server helper

[lewtun]

Summary

• Add a managed local dev server helper that starts backend and frontend together with conflict-free ports.
• Configure Vite/backend local dev settings through environment variables so the helper can wire the proxy and CORS dynamically.
• Add stale server cleanup before startup plus an explicit cleanup command, and document teardown guidance for retired PR worktrees.

Validation

• uv run --frozen --extra dev ruff check .
• uv run --frozen --extra dev ruff format --check .
• uv run --frozen --extra dev pytest tests/unit/test_dev_server.py
• npm run lint (passes with existing warnings)
• npm run build
• Smoke-tested dev_server.py cleanup, up, active cleanup, and down.

[github-actions]

Claude finished @lewtun's task in 2m 1s —— View job

---

PR Review: Add managed local dev server helper

No blocking issues — 2 P1, 1 P2. This is local dev tooling; the only production-path file is backend/main.py, and its CORS change is operator-controlled (env-driven, not request-reflected), so no security regression there.

---

P1 — Stale-server cleanup silently no-ops when lsof is absent

The headline "cleans stale dev servers from the same worktree" feature depends entirely on resolving each candidate's working directory, and that resolution only uses lsof:

• process_cwd (scripts/dev_server.py:142-158) shells out to lsof; it returns None on FileNotFoundError or non-zero exit.
• classify_dev_server_process (scripts/dev_server.py:271-280) returns None whenever process.cwd is None.
• So discover_stale_dev_servers (scripts/dev_server.py:314-331) finds nothing, and cleanup/up quietly skip the cleanup they advertise.

lsof is commonly missing on Linux dev containers. On Linux a /proc/<pid>/cwd symlink (os.readlink) is a zero-dependency fallback that would make this robust. Worth at least a warning when lsof is unavailable so the no-op isn't silent.

Fix this →

P1 — New CORS-merging behavior has no test coverage

The custom review brief calls out test coverage for new behavior. The new security-adjacent logic is untested:

• _split_env_list / _cors_origins (backend/main.py:29-44) — parsing + default-merge.
• build_backend_env dedup + 127.0.0.1→localhost mirroring (scripts/dev_server.py:418-429).

tests/unit/test_dev_server.py covers host_url, find_free_port, classify_*, and managed_stack_active, but not the origin-merging path that decides who may send credentialed requests. A couple of cases (empty env, comma list with blanks, dedup ordering) would lock this down.

Fix this →

---

P2 — Vite proxy target is now a bracketed IPv6 literal

build_frontend_env sets VITE_BACKEND_PROXY_TARGET to host_url(args.backend_host, port) → http://[::1]:7860 by default (scripts/dev_server.py:432-436, 57-60), where the prior hardcoded target was http://localhost:7860. The up smoke test exercises the proxy health check, so this works in practice — just noting it as a deliberate behavior change (IPv6-literal target) in case a future contributor expects the old localhost target.

---

Nice touches: per-host find_free_port with SO_REUSEADDR, pgid-based group termination with SIGTERM→SIGKILL escalation, and the match_markers + cwd guard so cleanup won't kill unrelated uvicorn/vite processes. The managed_stack_active "all-or-nothing" check is a good way to avoid acting on a half-dead stack.

[lewtun]

Thanks for contributing to ML Intern. The project, including its CLI, has been retired and this repository is being archived. We will therefore not be able to review or merge this work. For continued AI assistance, please use HuggingChat.