feat: FastAPI server, supervised runtime, and self-serve web UI

[lan17]

Summary

Replaces the standalone health server with a full FastAPI API server and adds a React/TypeScript web UI, turning HomeSec into a self-serve application that can be managed entirely from the browser.

API server (src/homesec/api/)

• New FastAPI server with modular route registration (cameras, clips, config, health, media, runtime, stats)
• Canonical error envelope with consistent status mapping across all endpoints
• API-key authentication on all management endpoints; diagnostics endpoint protected
• Cursor-based pagination for clips with expression indexes for efficient filtering
• Tokenized media proxy endpoint for secure clip playback without exposing storage paths
• OpenAPI schema export for deterministic client code generation
• CORS middleware, SPA static-file serving with hardened fallback routing
• Retired the old standalone health server; health/readiness probes consolidated into FastAPI

Supervised runtime (src/homesec/runtime/)

• Runtime now runs in a supervised subprocess with structured reload semantics
• Reload control plane: hot-reload cameras/config without full process restart
• Worker logs routed through the shared Postgres log handler
• Dead in-process controller removed; clean separation between API and runtime lifecycle
• Worker test harness for isolated runtime testing

Web UI (ui/)

• React 19 + TypeScript SPA scaffolded with Vite, pnpm, React Router, TanStack Query
• Dashboard: system health, camera stats, runtime status with auth gate
• Clips: paginated list with camera/detected filters, detail view with analysis overlay, video playback with token-based media URLs and retry logic
• Cameras: full CRUD management — add, edit, delete cameras with form validation
• Deterministic OpenAPI client generation from the FastAPI schema (scripts/api_codegen.mjs)
• Dark/light theme support, responsive layout, CSS design tokens
• Served from FastAPI in Docker (multi-stage build with Node UI builder stage)

Infrastructure & hardening

• Multi-stage Dockerfile adds UI builder; serves built assets by default
• CI updated to install pnpm before Node cache step
• Root Makefile proxies for ui-* targets
• Config file loader enforces restrictive file permissions (0o600)
• Delete integrity guards in both runtime and UI
• Database migration for clip query expression indexes

Testing

• ~4,500 lines of new test code covering API routes, error handling, pagination, media tokens, runtime manager, subprocess controller, assembly, config manager, state store edge cases, and UI presentation/form logic

Test plan

• API route tests pass (pytest tests/)
• Runtime subprocess and reload tests pass
• UI unit tests pass (pnpm test in ui/)
• Docker build completes with UI assets served at /
• Manual: verify clip playback via media proxy on LAN
• Manual: verify camera CRUD from the cameras page

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 81.13849% with 444 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.91%. Comparing base (1e6beb9) to head (18f9dff).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/homesec/runtime/worker.py	25.74%	150 Missing ⚠️
src/homesec/runtime/test_worker_harness.py	0.00%	100 Missing ⚠️
src/homesec/runtime/subprocess_controller.py	85.76%	42 Missing ⚠️
src/homesec/state/postgres.py	68.42%	42 Missing ⚠️
src/homesec/repository/clip_repository.py	39.47%	23 Missing ⚠️
src/homesec/app.py	85.07%	20 Missing ⚠️
src/homesec/runtime/assembly.py	85.85%	14 Missing ⚠️
src/homesec/runtime/manager.py	91.13%	14 Missing ⚠️
src/homesec/models/config.py	86.66%	6 Missing ⚠️
src/homesec/sources/rtsp/utils.py	53.84%	6 Missing ⚠️
... and 12 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #24      +/-   ##
==========================================
+ Coverage   81.71%   81.91%   +0.19%     
==========================================
  Files          69       93      +24     
  Lines        5976     8104    +2128     
==========================================
+ Hits         4883     6638    +1755     
- Misses       1093     1466     +373     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.