docs(quick-260610-czd): plan/summary + STATE quick-task row, resolve deployment.md dev-cmd todo

2026-06-10 09:25:24 -04:00
parent 39e2ee067e
commit 7369c9f1d1
3 changed files with 182 additions and 2 deletions
@@ -121,7 +121,7 @@ Recent decisions affecting current work:

 ### Pending Todos

- **Fix `docs/deployment.md` local-dev command** — the documented dev run is wrong: the API dev script (`node --watch dist/index.js`) does NOT load `.env`, and `DB_HOST` defaults to `localhost` with an empty password. Correct local-dev command is: `pnpm --filter @familysync/api build && set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev` (+ `pnpm --filter @familysync/pwa dev`). Consider adding `--env-file=.env` to the dev script so this is automatic. (Surfaced during Phase 2 UAT.)
+- ~~**Fix `docs/deployment.md` local-dev command**~~ DONE 2026-06-10 (quick 260610-czd) — added a "Running locally (host-side, no Docker)" subsection with the correct two-terminal command (`set -a; source .env; set +a && DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev` + `pnpm --filter @familysync/pwa dev`). `--env-file` deliberately NOT baked into the dev script (root `.env` sets `DB_HOST=mariadb`; auto-load would break host-side dev).
 - **REQUIREMENTS.md traceability gap** — phase.complete flagged 6 REQ-IDs in the body missing from the Traceability table: CAL-09, CAL-10, CAL-11, CAL-12, DISP-01, DISP-02. Add them to keep traceability in sync (likely Phase 4/5/display requirements).
 - **DST spring-forward spot-check (Phase 2)** — recurring/DST is implemented and code-verified (VTIMEZONE before expansion + local display TZ), and operator approved general times; navigating to March 2026 to eyeball the spring-forward transition is a recommended future spot-check.
 - **Gitea CI — regression on PR to main + Docker build/publish** — self-hosted Gitea runner exists but no CI yet. Add `.gitea/workflows/`: full regression (lint/typecheck/unit + API integration tests against a MariaDB service container + PWA build) gating PRs to `main`, plus build/publish the Docker image to the Gitea registry. Decide image matrix (API-only vs API+PWA — only `apps/api/Dockerfile` exists today) and tag policy. See pending todo `2026-06-10-gitea-ci-regression-and-docker-publish.md`.
@@ -142,6 +142,7 @@ Recent decisions affecting current work:
 | 260607-l6l | Batch-fix Phase 03 write-path bugs: events.ts edit/delete missing calendars innerJoin (503, BLOCKING) + handler-coupled regression test; shared deriveDisplayName helper (me.ts + resolveUserId, corrects blank rows); GET /api/events userId/isShared ownership filter | 2026-06-07 | 2870413 |  | [260607-l6l-fix-phase-03-write-path-correctness-bugs](./quick/260607-l6l-fix-phase-03-write-path-correctness-bugs/) |
 | 260607-u8o | Record SSE-over-Pangolin smoke test PASS (Phase 4 entry gate, D-14 / issue #1034) — updated 01-HUMAN-UAT item 4 + 03-GATE2-RESULTS Part C to PASS with live evidence | 2026-06-08 | 26655cf |  | [260607-u8o-record-sse-over-pangolin-smoke-test-pass](./quick/260607-u8o-record-sse-over-pangolin-smoke-test-pass/) |
 | 260610-cr8 | Adopt drizzle generate+migrate workflow, retire db:push on MariaDB — removed db:push script + repointed deployment.md to migrate with anti-push warning; dry-verified no destructive diff | 2026-06-10 | 1a95d81 | Verified | [260610-cr8-adopt-drizzle-generate-migrate-workflow-](./quick/260610-cr8-adopt-drizzle-generate-migrate-workflow-/) |
+| 260610-czd | Fix docs/deployment.md local-dev command — added "Running locally (host-side, no Docker)" subsection with correct env-sourced two-terminal run command (Phase 2 UAT gap) | 2026-06-10 | 39e2ee0 |  | [260610-czd-fix-docs-deployment-md-local-dev-command](./quick/260610-czd-fix-docs-deployment-md-local-dev-command/) |

 ## Deferred Items

@@ -157,5 +158,5 @@ Recent decisions affecting current work:
 ## Session Continuity

 Last session: 2026-06-10T13:11:05.428Z
-Stopped at: Completed quick task 260610-cr8 (retired db:push, adopted generate+migrate); next pending todos: deployment.md dev-command fix, REQUIREMENTS traceability gap. Phase 05 still awaiting device UAT.
+Stopped at: Completed quick tasks 260610-cr8 (drizzle generate+migrate) and 260610-czd (deployment.md local-dev command). Next pending todo: REQUIREMENTS.md traceability gap (CAL-09/10/11/12, DISP-01/02). Phase 05 still awaiting device UAT.
 Resume file: None
@@ -0,0 +1,115 @@
+---
+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>
@@ -0,0 +1,64 @@
+---
+phase: quick-260610-czd
+plan: "01"
+subsystem: docs
+tags: [docs, local-dev, deployment]
+dependency_graph:
+  requires: []
+  provides: [host-side-local-dev-instructions]
+  affects: [docs/deployment.md]
+tech_stack:
+  added: []
+  patterns: []
+key_files:
+  created: []
+  modified:
+    - docs/deployment.md
+decisions:
+  - "D: Sourcing .env manually with DB_HOST override is intentional — baking --env-file into the dev script would load DB_HOST=mariadb and break host-side dev."
+metrics:
+  duration: "~5 min"
+  completed: "2026-06-10"
+---
+
+# Phase quick-260610-czd Plan 01: Fix docs/deployment.md local-dev command — Summary
+
+**One-liner:** Added host-side local-dev subsection to deployment.md explaining DB_HOST override and exact two-terminal run commands.
+
+## Tasks Completed
+
+| # | Task | Commit | Files |
+|---|------|--------|-------|
+| 1 | Add "Running locally (host-side, no Docker)" subsection | 39e2ee0 | docs/deployment.md |
+
+## Verification Output
+
+```
+$ 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 && echo "ALL CHECKS PASSED"
+ALL CHECKS PASSED
+```
+
+```
+$ git diff --name-only
+docs/deployment.md
+```
+
+Only `docs/deployment.md` was changed. No code or package.json modifications.
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None.
+
+## Threat Flags
+
+None — docs-only change introduces no new security surface.
+
+## Self-Check: PASSED
+
+- `docs/deployment.md` exists and contains all required strings.
+- Commit `39e2ee0` exists on `gsd/v1.0-milestone`.
+- No other files modified.