feat(infra): add full-stack compose launcher

[parthrohit22]

Summary

Adds a cross-platform npm run partha workflow that builds and starts PARTHA's frontend, API, PostgreSQL, and Redis from the checkout, verifies host readiness, and shuts the stack down without deleting application data. This closes the implementation gap left after the incorrect predecessor PR #216 was reverted while preserving merged PR #214's host-isolated PostgreSQL/Redis posture.

Linked issue

Related to #222

The implementation is complete and verified on macOS. The issue remains open because the available in-app browser connector had no browser backend, and Linux/Windows runtime execution was not available in this environment; those acceptance claims are not being overstated.

Roadmap alignment

• Roadmap §23 workstream this advances: W7 / Platform — repeatable deployment and contributor onboarding.
• §28 market-fit criterion this moves toward: deployment repeatability for reference environments.
• Accepted evidence it is real (test/usage/repo state, not intent): source-built images, resolved Compose config, full backend/frontend/Playwright gates, isolated Compose migration/recovery/backup acceptance, live host readiness/auth requests, signal cleanup, and retained named data/storage volumes.

What changed

• Frontend/infra: Added a Node 22 Alpine development image using npm ci, a build-context .dockerignore, and a health-checked Compose frontend at host port 5173 with browser-facing VITE_API_URL=http://localhost:8000.
• Launcher: Added a dependency-free Node launcher that preflights Docker CLI, Compose, buildx, and daemon state; runs docker compose up --build --wait without a shell; verifies /ready and the frontend from the host; prints the exact ready URL; and performs one volume-preserving docker compose down on startup failure or SIGINT/SIGTERM.
• Docs: Documented the one-command workflow, prerequisites, persistent data behavior, standalone alternative, lower-level Compose commands, and explicitly destructive docker compose down -v reset.
• Contracts: No backend, OpenAPI, schema, migration, dependency, or product-surface changes.

Acceptance criteria completed

• Cross-platform implementation uses Node APIs and direct argument arrays with no shell or macOS-specific launcher behavior; verified on macOS with Node/npm and Docker Engine/Compose/buildx.
• npm run partha builds and starts frontend, API, PostgreSQL, and Redis from the checkout.
• Frontend and API are reachable at http://localhost:5173 and http://localhost:8000; real registration/login requests using the frontend Origin returned 201/200 with the expected CORS origin and an access token.
• Missing buildx produces the required Docker install message plus detected detail; Docker, Compose, buildx, and daemon each have an explicit preflight.
• SIGINT runs docker compose down once, exits 130, leaves no containers or launcher/up processes, and retains named PostgreSQL/repository-storage volumes.
• PostgreSQL and Redis have no host port bindings in resolved config or the live stack.
• README documents launcher, prerequisites, persistence, alternatives, and destructive reset.
• Compose, backend, frontend, prototype, and live host verification passed with recorded results.
• OpenAPI and product contracts are unchanged.
• Live click-through via the in-app browser connector was unavailable because the runtime reported no browser backend; Linux and Windows runtime execution also remains unverified here. The repository's Chromium Playwright acceptance passed separately.

Testing performed

npm run partha  # before buildx installation
# exit 1; printed the required Docker requirement message and:
# Detected problem: Docker buildx plugin is unavailable: docker: unknown command: docker buildx

brew install docker-buildx
# passed; installed Homebrew docker-buildx 0.35.0

docker buildx version
# github.com/docker/buildx v0.35.0 Homebrew

node --check scripts/partha.mjs
# passed

docker compose -f docker-compose.yml config --quiet
# passed

docker compose -f docker-compose.yml config --format json
# frontend URL localhost:8000; host port 5173; api service_healthy; data+egress networks;
# PostgreSQL ports []; Redis ports []; named postgres/storage/frontend dependency volumes

cd apps/backend && PYTHONPATH= .venv/bin/python -m pytest
# 701 passed, 4 skipped, 898 warnings in 44.83s

npm --prefix apps/frontend run test
# 33 files passed; 176 tests passed in 5.98s

npm run lint:frontend
# passed

npm run build:frontend
# passed; tsc -b and Vite production build completed

npm run test:prototype
# 16 Chromium tests passed in 23.2s

COMPOSE_PROJECT_NAME=partha-launcher-test npm run docker:validate
# passed on the final npm-ci image: migrations and downgrade/upgrade, owner isolation,
# analysis lifecycle, restart persistence, backup/restore, secret scan, and isolated down -v cleanup
# Earlier attempts exposed local Docker VM disk exhaustion (PostgreSQL pg_wal/image extraction);
# only rebuildable PARTHA images/cache and disposable dependency/cache volumes were reclaimed,
# while default PostgreSQL and repository-storage volumes were preserved.

npm run partha
# both images built from the checkout; frontend Docker build ran npm ci; all services healthy;
# printed exactly: PARTHA is ready at http://localhost:5173

curl -sS -o /dev/null -w 'api_ready_http=%{http_code}' http://localhost:8000/ready
# 200

curl -sS -o /dev/null -w 'frontend_http=%{http_code}' http://localhost:5173
# 200

# Real host-origin registration/login verification:
# register 201; Access-Control-Allow-Origin http://localhost:5173
# login 200; accessToken present
# repeated login after full stop/start: 200 with accessToken, proving PostgreSQL persistence

# SIGINT / Ctrl+C launcher verification:
# exit 130; docker compose ps -a empty; no launcher/compose-up process;
# partha_postgres_data, partha_partha_storage, and partha_frontend_node_modules retained

git diff --check
git diff --cached --check
# passed

git status --short --untracked-files=all
# clean after commit; commit contains exactly the six approved paths

Screenshots

Not applicable — no visible product UI change.

Security and data considerations

PostgreSQL and Redis remain reachable only on the internal data network and publish no host ports. The frontend joins data as required and also egress so its published host port works under Colima's internal-network behavior. Ordinary shutdown does not pass -v; PostgreSQL and repository storage persist. The README labels docker compose down -v as permanently destructive. No secrets, local env files, generated artifacts, auth behavior, owner scoping, logs, schemas, or migrations changed. The full backend contract/security suite and Compose secret scan passed.

Dependencies and blocked work

No repository dependency was added. Runtime prerequisite: Node/npm plus Docker Engine with Compose and buildx. Merged PR #214 established the host-isolated data tier this preserves. Closed PR #216 was the reverted incorrect predecessor. Remaining environment verification is tracked by #222 staying open.

Scope changes or remaining work

• The plan proposed an anonymous /app/node_modules volume. Live repeated shutdowns left roughly 300 MB anonymous dependency volumes behind and exhausted the Docker VM, so this uses a named frontend_node_modules volume that is reused across starts and removed by the documented down -v reset.
• The plan proposed only the internal data network. Live Colima verification showed that made published port 5173 unreachable; retaining data and adding egress made the host port reachable while database/cache host isolation remained intact.
• In-app browser live click-through and Linux/Windows runtime execution remain unverified in this environment. Direct live frontend-origin auth/CORS requests passed, and the separate Chromium Playwright prototype suite passed 16/16.

Contributor checklist

• This PR targets dev
• I claimed the issue and had it assigned or acknowledged before starting substantial work
• The branch was created from an up-to-date upstream/dev
• The branch is rebased on the latest upstream/dev
• This PR addresses one clearly scoped issue
• This PR advances a §23 workstream toward a §28 market-fit criterion (Roadmap alignment filled)
• Every acceptance criterion I claim as complete is actually complete
• Relevant tests pass
• Documentation is updated for any user-visible change
• No secrets, credentials, local env files, or generated artifacts are included
• No unrelated files were changed
• Closing syntax (Closes) is used only because the issue is fully resolved
• Dependencies and follow-up work are linked

[parthrohit22]

closes #222