Lucas Berger
982438dc10
Mechanical reformat — no logic changes. 398 files changed, 19125 insertions(+), 16457 deletions(-). Prettier 3.8.4 with .prettierrc (singleQuote:true, semi:true, tabWidth:2, trailingComma:all, printWidth:100). Isolated per D-13-08 for reviewability.
5.7 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| quick-260610-czd | 01 | execute | 1 |
|
true |
|
|
The deployment runbook is Docker-only: it brings the app up via docker compose up -d --build and the
"## Dev-auth bypass (Phase 2+ local development)" section explains how to ACTIVATE the bypass but never gives
the command to actually run the API + PWA on the host. This adds a "Running locally (host-side, no Docker)"
subsection with the correct, tested command block.
Purpose: Eliminate the implicitly-wrong/missing local-dev run command. A naive pnpm --filter @familysync/api dev
fails because the dev script does not load .env and DB_HOST defaults to 'localhost' — but if env IS sourced from
root .env, DB_HOST=mariadb (the Docker service name) breaks host-side dev. The correct invocation sources .env
then overrides DB_HOST=localhost.
Output: Updated docs/deployment.md.
<execution_context> @$HOME/.claude/gsd-core/workflows/execute-plan.md @$HOME/.claude/gsd-core/templates/summary.md </execution_context>
@docs/deployment.md @apps/api/package.json @apps/api/src/db/client.ts Task 1: Add "Running locally (host-side, no Docker)" subsection to deployment.md docs/deployment.md Insert a new "### Running locally (host-side, no Docker)" subsection immediately after the "## Dev-auth bypass (Phase 2+ local development)" section (after the existing content ending at the "What the bypass does" paragraph, ~line 286). DOCS-ONLY — do NOT modify apps/api/package.json or any code.The subsection MUST cover, in order:
(a) Prerequisite: dev MariaDB must be running with host port 3306 exposed via the dev compose override.
Reference the existing command (already documented in Step 3): `docker compose -f docker-compose.yml
-f docker-compose.dev.yml up -d mariadb`.
(b) Why a plain `pnpm --filter @familysync/api dev` is not enough: the api `dev` script is
`node --watch dist/index.js` — it does NOT auto-load .env (no dotenv, no --env-file), and
db/client.ts defaults DB_HOST to 'localhost' when unset. So env must be sourced AND DB_HOST overridden
to localhost, because root .env sets DB_HOST=mariadb (the Docker service name) for the compose path.
(c) The exact command block. Terminal 1 (API) — build first, then run with env sourced and overrides applied:
pnpm --filter @familysync/api build
set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev
Terminal 2 (PWA):
pnpm --filter @familysync/pwa dev
Run `.env` from the repo root (the gitignored root .env). Transcribe the command block faithfully —
`set -a; source .env; set +a` exports every var from .env, and the trailing `DEV_AUTH_BYPASS=true
DB_HOST=localhost` overrides win for the host-side run.
(d) A short note explaining WHY `--env-file` is not baked into the dev script: auto-loading root .env would
load DB_HOST=mariadb and break host-side dev (that host is only reachable on the Docker network), which
is why env is sourced manually with DB_HOST overridden to localhost instead.
Use fenced ```bash blocks for the commands. Match the surrounding doc's tone and heading depth
(the parent section is `##`, so use `###` for this subsection).
<success_criteria> A Phase 2+ developer reading docs/deployment.md can start the API + PWA host-side (no Docker) using only the commands in the doc, understands the DB_HOST=localhost override and why it is needed, and the change touches only docs/deployment.md. </success_criteria>
Create `.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md` when done