diff --git a/.planning/STATE.md b/.planning/STATE.md index dbe9690..d401ed0 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -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 diff --git a/.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-PLAN.md b/.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-PLAN.md new file mode 100644 index 0000000..f8bede8 --- /dev/null +++ b/.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-PLAN.md @@ -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: [] +--- + + +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. + + + +@$HOME/.claude/gsd-core/workflows/execute-plan.md +@$HOME/.claude/gsd-core/templates/summary.md + + + +@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). + + + 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 + + + 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. + + + + + + +- `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). + + + +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. + + + +Create `.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md` when done + diff --git a/.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md b/.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md new file mode 100644 index 0000000..6e302e6 --- /dev/null +++ b/.planning/quick/260610-czd-fix-docs-deployment-md-local-dev-command/260610-czd-SUMMARY.md @@ -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.