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.
117 lines
5.7 KiB
Markdown
117 lines
5.7 KiB
Markdown
---
|
|
phase: quick-260610-czd
|
|
plan: 01
|
|
type: execute
|
|
wave: 1
|
|
depends_on: []
|
|
files_modified: [docs/deployment.md]
|
|
autonomous: true
|
|
requirements: [DOCS-FIX]
|
|
must_haves:
|
|
truths:
|
|
- 'docs/deployment.md tells a Phase 2+ developer the exact command to run the API + PWA host-side (no Docker)'
|
|
- 'The doc explains DB_HOST must be overridden to localhost because root .env sets DB_HOST=mariadb for the Docker network'
|
|
- 'The doc states the dev script does not auto-load .env'
|
|
artifacts:
|
|
- path: 'docs/deployment.md'
|
|
provides: 'Host-side (no-Docker) local-dev run instructions for Phase 2+'
|
|
contains: 'Running locally'
|
|
key_links: []
|
|
---
|
|
|
|
<objective>
|
|
Fix docs/deployment.md so a Phase 2+ developer can run FamilySync host-side (no Docker).
|
|
|
|
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.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.claude/gsd-core/workflows/execute-plan.md
|
|
@$HOME/.claude/gsd-core/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@docs/deployment.md
|
|
@apps/api/package.json
|
|
@apps/api/src/db/client.ts
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Add "Running locally (host-side, no Docker)" subsection to deployment.md</name>
|
|
<files>docs/deployment.md</files>
|
|
<action>
|
|
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).
|
|
|
|
</action>
|
|
<verify>
|
|
<automated>grep -q "Running locally (host-side, no Docker)" docs/deployment.md && grep -q "DB_HOST=localhost pnpm --filter @familysync/api dev" docs/deployment.md && grep -q "pnpm --filter @familysync/pwa dev" docs/deployment.md && grep -q "set -a; source .env; set +a" docs/deployment.md</automated>
|
|
</verify>
|
|
<done>
|
|
docs/deployment.md contains a "### Running locally (host-side, no Docker)" subsection after the dev-auth
|
|
bypass section that: names the dev-MariaDB prerequisite (host port 3306 via dev compose override); states
|
|
the dev script does not auto-load .env and DB_HOST defaults to localhost; gives the exact build → source-env
|
|
+ override → run-API command and the second-terminal PWA command; and explains why --env-file is not baked
|
|
into the dev script (would load DB_HOST=mariadb and break host-side dev). No code or package.json changes.
|
|
</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- `grep -q "Running locally (host-side, no Docker)" docs/deployment.md` passes.
|
|
- The exact API run command (`set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev`) is present.
|
|
- The PWA run command (`pnpm --filter @familysync/pwa dev`) is present.
|
|
- `git diff --name-only` shows only docs/deployment.md changed (no package.json, no source files).
|
|
</verification>
|
|
|
|
<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>
|
|
|
|
<output>
|
|
Create `.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md` when done
|
|
</output>
|