Phase 9A0: make local and Docker startup reliable

[Artsen]

Summary

• Adds a combined local npm run dev launcher that builds shared packages once, starts API and web together, prints local URLs, handles sibling failure, and uses Windows-aware process termination.
• Preserves the existing two-console commands: npm run dev:api and npm run dev:web.
• Keeps ordinary local API and web development loopback-oriented while documenting Docker's required container binding.
• Adds a redacted GET /ready readiness endpoint with shared contract coverage and required/optional check semantics.
• Improves frontend bootstrap behavior so complete API outage shows an actionable startup panel, partial bootstrap failures show a degraded warning, retry re-runs bootstrap, and history deletion failures surface to the user.
• Repairs Docker workspace builds so local packages are copied, installed with npm ci, and built before the apps start.
• Adds Docker Compose health checks and a GitHub Actions docker-smoke job.
• Corrects setup, configuration, API, and architecture docs discovered during the operational review.

Local launcher behavior

npm run dev now:

• runs npm run build:packages once before starting services
• starts npm run dev --workspace apps/api
• starts npm run dev --workspace apps/web
• prints:
  • Web: http://localhost:5173
  • API: http://localhost:4000
  • Health: http://localhost:4000/health
  • Readiness: http://localhost:4000/ready
• forwards normal termination to both children
• stops the sibling process if API or web exits unexpectedly
• uses npm.cmd on Windows, with a Node/npm-cli fallback when inherited stdio is unavailable from hidden/background Windows parents

The separate commands remain supported:

• npm run dev:api
• npm run dev:web

Readiness endpoint

Path: GET /ready

Semantics:

• ready with HTTP 200 when required core checks pass
• degraded with HTTP 200 when core checks pass but storage pressure or optional tooling is degraded
• not_ready with HTTP 503 when required checks fail

Required checks include runtime initialization, storage availability, manifest load state, FFmpeg, FFprobe, H.264 capability, WebM/AV1 capability, and storage pressure. Optional checks include yt-dlp and whisper.cpp status. Responses are intentionally redacted and do not expose filesystem paths, command strings, model paths, filenames, manifests, stack traces, or user media details.

Docker notes

• Dockerfiles now copy root and workspace manifests, install deterministically with npm ci, copy shared package source, and build shared packages before app startup.
• Docker Compose keeps runtime media in the video_data named volume.
• Docker API uses HOST=0.0.0.0 and ALLOW_LAN_ACCESS=true so the published host port can reach the container. Ordinary local Node development remains loopback-oriented.
• Web container runs Vite with Docker-specific --host 0.0.0.0.
• API and web services now have health checks, with web waiting for a healthy API.

Frontend startup behavior

• Complete API outage renders an accessible Cannot reach the local API startup panel with the expected API URL and retry action.
• Partial bootstrap failures render a degraded warning without unnecessarily blocking usable functionality.
• Retry re-runs history, capabilities, and storage bootstrap requests.
• Raw stack traces and private paths are not rendered.
• History deletion failures now surface through the existing application error path.

Tests added

• Launcher process-plan tests, including Windows command selection, build-before-start, sibling termination, parent shutdown, exit status, and Windows fallback behavior.
• Shared readiness contract test.
• API readiness route and service tests, including privacy/redaction and cached expensive checks.
• Frontend bootstrap outage, partial failure, retry, accessibility, privacy, and deletion-failure tests.
• Mocked Playwright startup outage and retry scenario.

Local validation

• npm ci: passed
• npm run format: passed
• npm run format:check: passed
• npm run lint: passed
• npm run typecheck: passed
• npm run test:run: passed
• npm run build: passed
• npm run check: passed
• npm run test:coverage: passed
• npm audit --omit=dev: passed, 0 vulnerabilities
• npm run test:e2e: passed, 10 tests
• npm run test:integration:media: passed, 5 tests
• git diff --check: passed

Unit/component counts from npm run test:run:

• Scripts: 7
• Contracts: 26
• Video core: 39
• API: 230 passed, 1 skipped
• Web: 85
• Total: 387 passed, 1 skipped

Coverage headline:

• API workspace statement coverage: 81.96%
• Web workspace statement coverage: 83.86%
• Script launcher coverage ran successfully; root aggregate output is noisy because it sees built artifacts.

Local smoke

• npm run dev started both services on Windows.
• http://127.0.0.1:4000/health returned HTTP 200.
• http://127.0.0.1:5173 returned HTTP 200.
• After cleanup, ports 4000 and 5173 were no longer served.
• Note: the hidden/background smoke needed elevated cleanup because non-elevated taskkill returned Access denied; interactive Ctrl+C behavior is covered by launcher tests.

Docker validation

Docker was not available on the owner's Windows machine in this environment (docker command not found), so Docker was not tested locally and was not installed. The new GitHub Actions docker-smoke job is the authoritative Docker validation for this phase.

GitHub Actions Docker smoke result: passed.

Scope exclusions

No UI-B, new media features, batch processing, projects, presets, retention policies, desktop packaging, CLI, MCP, authentication, authorization, rate limiting, cloud services, dependency major upgrades, or Dependabot changes are included.