t1224: Local development environment (localdev)

[marcusquinn]

Task ID: t1224 | Status: completed | Estimate: ~10h (ai:8h test:2h)
Assignee: @marcusquinn | Started: 2026-02-20T17:44:00Z | Completed: 2026-02-20
Tags: auto-dispatch feature localhost infrastructure

Description

Local development environment (localdev) — unified .local domain management for all local dev projects. Replaces manual /etc/hosts + dynamic.yml editing with a single localdev CLI. Inspired by Portless (vercel-labs/portless) but built on existing Traefik + mkcert + dnsmasq stack for production-like .local domains with HTTPS on port 443. Coexists with LocalWP (which manages its own .local domains via /etc/hosts #Local Site entries). Architecture: dnsmasq wildcard DNS -> Traefik conf.d directory -> mkcert wildcard certs -> port registry (JSON). Shared Postgres via single Docker container with per-project databases. Optional branch/worktree subdomains (feature-xyz.myapp.local). Stack-agnostic (Next.js, Vite, Rails, anything with a port).

Subtasks

• t1224.1 Create localdev shell script with init command — configure dnsmasq (address=/.local/127.0.0.1), create /etc/resolver/local, migrate Traefik from single dynamic.yml to conf.d/ directory provider, preserve existing project routes. Coexistence: dnsmasq only handles domains NOT already in /etc/hosts (LocalWP entries take precedence). One-time setup, requires sudo. #auto-dispatch ~2h model:sonnet blocked-by:t1224.6 ref:GH#1874 assignee:marcusquinn started:2026-02-19T03:26:08Z pr:t1224.1: Create localdev shell script with init command #1884 completed:2026-02-19
• t1224.2 Implement localdev add/rm — port registry (~/.local-dev-proxy/ports.json), auto-assign ports from 3100-3999 range, generate mkcert wildcard cert (*.myapp.local myapp.local), create Traefik conf.d/{name}.yml route file, add /etc/hosts entry as fallback. rm reverses all. Collision detection against LocalWP sites and other registered apps. #auto-dispatch ~3h model:sonnet blocked-by:t1224.1 ref:GH#1875 assignee:marcusquinn started:2026-02-19T03:57:08Z pr:t1224.2: Implement localdev add/rm commands #1908 completed:2026-02-19
• t1224.3 Implement localdev branch — subdomain routing for worktrees/branches. localdev branch myapp feature-xyz [port] creates feature-xyz.myapp.local route to specified or auto-assigned port. Wildcard cert from add already covers subdomains. Port registry tracks branch->port mappings per project. #auto-dispatch ~1h model:sonnet blocked-by:t1224.2 ref:GH#1876 assignee:marcusquinn started:2026-02-19T04:21:00Z pr:t1224.3: Implement localdev branch — subdomain routing for worktrees #1916 completed:2026-02-19
• t1224.4 Implement localdev db — shared Postgres management. localdev db start ensures shared local-postgres container running (configurable version, default postgres:17-alpine). localdev db create myapp creates database. localdev db create myapp-feature-xyz for branch isolation. localdev db list, localdev db drop, localdev db url myapp (outputs connection string). Projects can still use own docker-compose Postgres for version-specific testing. #auto-dispatch ~1.5h model:sonnet blocked-by:t1224.1 ref:GH#1877 assignee:marcusquinn started:2026-02-19T04:48:45Z pr:t1224.4: Add localdev db command for shared Postgres management #1920 completed:2026-02-19
• t1224.5 Implement localdev list/status — dashboard showing all registered projects with URLs, ports, cert status, process health (is something listening?). Include LocalWP sites (read-only, from LocalWP's sites.json). Unified view of entire local dev landscape. #auto-dispatch ~1h model:sonnet blocked-by:t1224.2,t1224.4 ref:GH#1878 assignee:marcusquinn@Marcus-MacBook-Pro started:2026-02-19T06:00:54Z pr:t1224.5: Add unified localdev dashboard with cert status, process health, and LocalWP sites.json #1934 completed:2026-02-19
• t1224.6 Create local-hosting agent (.agents/services/hosting/local-hosting.md) — comprehensive knowledge base for the localdev system. Covers: architecture (dnsmasq + Traefik + mkcert + port registry), all CLI commands, LocalWP coexistence rules, OrbStack/Docker integration, database management patterns, branch subdomain workflow, troubleshooting (DNS, certs, port conflicts), stack-specific guidance (Next.js PORT env, Vite --port, Rails -p, etc.). References localhost.md for legacy context. #auto-dispatch ~1.5h model:sonnet ref:GH#1879 assignee:marcusquinn started:2026-02-19T06:56:51Z pr:t1224.6: Add local-hosting.md agent — comprehensive localdev knowledge base #1939 completed:2026-02-19
• t1224.7 Migrate first project to new localdev setup — validate end-to-end: localdev add <project> <port>, verify https://<project>.local works, verify cert is trusted, verify Postgres connectivity. Remove manual /etc/hosts entry and old dynamic.yml config. Document any project-specific quirks. #auto-dispatch ~30m model:sonnet ref:GH#1880 assignee:marcusquinn started:2026-02-19T07:32:54Z pr:t1224.7: Migrate project to new localdev setup — validate end-to-end #1943 completed:2026-02-19
• t1224.8 Integrate localdev with aidevops worktree workflow — when wt switch -c feature/xyz creates a worktree for a localdev-registered project, auto-run localdev branch <project> <branch> and output the subdomain URL. Requires detecting project name from repo path. #auto-dispatch ~1h model:sonnet ref:GH#1881 assignee:marcusquinn started:2026-02-19T08:06:57Z pr:t1224.8: Integrate localdev with worktree workflow for auto branch subdomain routing #1948 completed:2026-02-19
• t1224.9 Update localhost.md and subagent-index.toon — reflect new architecture, point to local-hosting.md as primary agent, keep localhost.md as legacy reference. Add localdev to AGENTS.md progressive disclosure table (Localhost domain). Register in subagent-index.toon. #auto-dispatch ~30m model:sonnet ref:GH#1882 assignee:marcusquinn started:2026-02-19T09:28:49Z pr:t1224.9: Update localhost.md and subagent-index.toon — reflect localdev architecture #1953 completed:2026-02-19

---

Synced from TODO.md by issue-sync-helper.sh

[marcusquinn]

Verified: PR #1953 (state:MERGED merged:2026-02-19T09:52:30Z files:3). Task t1224: deploying -> deployed