✨ feat(dev): native local dev — infra in Docker, apps via pnpm dev

[cteyton]

Why

The legacy docker-compose.yml dev stack runs the watched Node apps (api, frontend, mcp-server) inside containers over a bind-mounted source tree. File-system events don't cross the container/VM boundary, so the setup forces polling everywhere (NX_WATCHER: polling, CHOKIDAR_USEPOLLING, …) — laggy HMR, CPU burn — plus a fragile shared Nx-daemon socket. A year of friction.

Insight: Docker is great for stateful infra, bad for hot-reloading Node. This PR splits them.

What

Hybrid setup — infra in Docker, apps native, toolchain pinned by mise:

mise install && pnpm install   # one-time
pnpm dev                        # infra up → migrations → serve api/frontend/mcp native

• docker-compose.dev.yml — Postgres + Redis only, isolated Compose project packmind-dev
• mise.toml — pins Node 24.15.0 + pnpm 11.5.0 (corepack)
• scripts/dev-serve.sh — bakes deterministic localhost wiring; .env overrides win
• scripts/prepare-local-dev.mjs — tsconfig select + JS-playground seed (idempotent)
• package.json — dev, dev:infra, dev:infra:down, dev:reset, dev:setup, migrate
• docs: CLAUDE.md + CONTRIBUTING.md

Result: real fs events, fast HMR, no daemon socket, no polling.

Validated locally

Native stack on Node 24: frontend=200 · api=200 · mcp up · frontend→api proxy=200 · 0 DB-connection failures · MCP "started successfully".

Scope / transition

• Legacy docker-compose.yml left intact as a fallback. Don't run both at once (ports 5432/6379).
• Removing the legacy app/daemon services (~250 lines) is a follow-up, gated on team validation of this flow (see LOCAL_DEV_REVAMP_PLAN.md, phase 4).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR replaces the all-in-container dev stack with a hybrid model: only Postgres and Redis run in Docker (docker-compose.dev.yml), while the three Node apps (api, frontend, mcp-server) run natively via pnpm dev. This eliminates the bind-mount fs-event problem that forced polling everywhere and caused slow HMR.

• docker-compose.dev.yml provides an isolated infra-only Compose project with healthchecks and pinned image versions; mise.toml pins the Node/pnpm toolchain; scripts/dev-serve.sh bakes deterministic localhost wiring with .env-override support.
• apps/api/project.json conditionally gates legacy-watch polling behind ${WATCH_POLLING:+...}, activated by the new WATCH_POLLING: '1' env var added to the legacy docker-compose.yml backend service, so both stacks work correctly.
• New root package.json scripts (dev, dev:infra, dev:reset, migrate, dev:setup) compose the full workflow; LOCAL_DEV_REVAMP_PLAN.md documents the phased rollout and rollback strategy.

Confidence Score: 5/5

Safe to merge. All changes are additive — new scripts and compose file — with the legacy docker-compose.yml left intact as a fallback.

The hybrid dev setup is well-structured: infra healthchecks gate migrations, WATCH_POLLING correctly activates legacy polling only in the old container stack, and the exec-replace pattern in dev-serve.sh cleanly hands off to nx. The only gap is that DATABASE_URL overrides in .env are not forwarded to the migration step, but this only affects the edge case documented in .env.example as optional.

package.json — the migrate script does not source .env, so DATABASE_URL overrides are not propagated to migrations.

Important Files Changed

Filename	Overview
scripts/dev-serve.sh	Correctly sources .env overrides before baking in deterministic localhost defaults, then exec-replaces itself with nx run-many. set -a/set +a pattern properly auto-exports all vars to child processes.
package.json	New dev scripts are clean. The migrate script runs against a hardcoded datasource.ts (localhost:5432), so a DATABASE_URL override in .env won't be honored at migration time — only at runtime.
docker-compose.dev.yml	Infra-only compose with proper healthchecks, pinned image versions for postgres/redis, and isolated project name. pgadmin (tools profile) uses unpinned latest tag — already flagged in a prior review.
apps/api/project.json	Correctly gates legacy-watch polling behind ${WATCH_POLLING:+...} in the sh -lc script; POSIX-compliant expansion works because sh evaluates it in the inner subshell. defaultConfiguration: "development" ensures nx run-many picks the right config.
mise.toml	Pins Node 24.15.0 and pnpm 11.5.0 via corepack postinstall; sets PACKMIND_EDITION=oss as a mise env default. Clean and minimal.
scripts/prepare-local-dev.mjs	Idempotent setup: runs tsconfig selection and seeds js-playground-local if absent. Uses Node 16.7+ fs.cpSync safely with Node 24.
apps/api/nodemon.json	Removes legacyWatch: true since polling is now controlled exclusively via the --legacy-watch CLI flag conditionally passed by project.json.
docker-compose.yml	Adds WATCH_POLLING: '1' to the backend service so the legacy in-container stack still activates polling for nodemon, preserving backward compatibility.
.env.example	Documents the DATABASE_URL/REDIS_URI override pattern. Since datasource.ts is hardcoded to localhost:5432, a DATABASE_URL override only affects app runtime, not migrations.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Dev as Developer
    participant PJ as package.json (pnpm dev)
    participant DC as docker-compose.dev.yml
    participant DS as dev-serve.sh
    participant NX as nx run-many

    Dev->>PJ: pnpm dev
    PJ->>DC: docker compose up -d --wait (dev:infra)
    DC-->>PJ: postgres + redis healthy ✓
    PJ->>PJ: node scripts/prepare-local-dev.mjs (dev:setup)
    Note over PJ: tsconfig select + js-playground seed
    PJ->>PJ: pnpm typeorm migration:run (migrate)
    Note over PJ: datasource.ts hardcoded → localhost:5432
    PJ->>DS: bash scripts/dev-serve.sh
    DS->>DS: source .env (overrides)
    DS->>DS: "apply localhost defaults (:= syntax)"
    DS->>NX: exec nx run-many -t serve -p api mcp-server frontend
    NX-->>Dev: api :3000 · mcp-server :3001 · frontend :4200

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Dev as Developer
    participant PJ as package.json (pnpm dev)
    participant DC as docker-compose.dev.yml
    participant DS as dev-serve.sh
    participant NX as nx run-many

    Dev->>PJ: pnpm dev
    PJ->>DC: docker compose up -d --wait (dev:infra)
    DC-->>PJ: postgres + redis healthy ✓
    PJ->>PJ: node scripts/prepare-local-dev.mjs (dev:setup)
    Note over PJ: tsconfig select + js-playground seed
    PJ->>PJ: pnpm typeorm migration:run (migrate)
    Note over PJ: datasource.ts hardcoded → localhost:5432
    PJ->>DS: bash scripts/dev-serve.sh
    DS->>DS: source .env (overrides)
    DS->>DS: "apply localhost defaults (:= syntax)"
    DS->>NX: exec nx run-many -t serve -p api mcp-server frontend
    NX-->>Dev: api :3000 · mcp-server :3001 · frontend :4200

Loading

_{Reviews (2): Last reviewed commit: "⚡️ perf(api): use native file watching f..." | Re-trigger Greptile}

[greptile-apps]

The pgadmin service uses the unpinned latest tag while postgres and redis are both version-pinned. On a fresh pull, different developers could get different pgAdmin versions, breaking the consistency goal this PR sets out to achieve. Pinning to a specific version avoids unexpected breakage when pgAdmin ships a breaking UI or config-schema change.

Suggested change

	image: dpage/pgadmin4:latest
	image: dpage/pgadmin4:9.4

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud