luckberg/familysync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee4c71fa4688ddd8842499c63ed9e4498fb88f5c
familysync/.planning/phases/01-foundation-broker-spike/01-01-SUMMARY.md
T
Lucas Berger ee4c71fa46 docs(01-01): clear Task 3 checkpoint, mark plan complete 
Stack verified live (/health green, 4 tables pushed). Record Docker deviation in
SUMMARY, mark 01-01 complete in ROADMAP, clean up paused-setup handoff files.
2026-06-04 10:17:21 -04:00

12 KiB
Raw Blame History

phase: 01-foundation-broker-spike plan: "01" subsystem: infra tags: [hono, drizzle, mariadb, mysql2, vitest, docker, pnpm, react, vite, typescript]

Dependency graph

requires: [] provides:

  • pnpm monorepo workspace (apps/api + apps/pwa)
  • Hono API scaffold with /health route (unauthenticated, real DB round-trip)
  • Drizzle ORM schema: users, memberCredentials, calendars, calendarEvents
  • drizzle(mysql2 pool) db singleton
  • Docker Compose stack: api + mariadb:11 (healthcheck) + redis
  • Vitest harness with Wave 0 test stubs
  • React PWA shell fetching /health
  • drizzle.config.ts for drizzle-kit push/migrate affects:
  • 01-02 (OIDC auth — imports db, users schema)
  • 01-03 (broker — imports db, all schemas, crypto pattern)
  • 01-04 (spike — imports broker module)

Tech tracking

tech-stack: added: - hono@4.12.23 - "@hono/node-server@2.0.4" - "@hono/oidc-auth@1.8.3" - "@hono/zod-validator@0.8.0" - drizzle-orm@0.45.2 - drizzle-kit@0.31.10 - mysql2@3.22.4 - tsdav@2.2.2 - ical.js@2.2.1 - zod@^3.25.0 - node-cron@^4.2.1 - vitest@^4.1.8 - react@^19.0.0 - "@tanstack/react-query@5.101.0" - zustand@5.0.14 - vite@8.0.16 patterns: - Hono app exported from src/index.ts for testability (no server start on import) - db singleton pattern (drizzle mysql2 pool, connectionLimit 10) - vi.mock at module top level for test isolation (Vitest hoisting) - Wave 0 test stubs using it.todo to document future tests before implementation

key-files: created: - package.json (root workspace, pnpm@11.5.1) - pnpm-workspace.yaml (apps/*, allowBuilds.esbuild: true) - .gitignore (.env excluded — secrets never committed) - .env.example (all env var names documented) - docker-compose.yml (api + mariadb:11 + redis) - docker-compose.dev.yml (dev overrides) - apps/api/package.json (pinned deps) - apps/api/tsconfig.json (strict, NodeNext, ES2023) - apps/api/Dockerfile (node:22-alpine, multi-stage) - apps/api/vitest.config.ts (environment: node, globals: true) - apps/api/drizzle.config.ts (dialect: mysql) - apps/api/src/db/schema.ts (users/memberCredentials/calendars/calendarEvents) - apps/api/src/db/client.ts (db export) - apps/api/src/routes/health.ts (GET / with SELECT 1 round-trip) - apps/api/src/index.ts (Hono app, /health mounted before auth) - apps/api/tests/health.test.ts (2 tests pass) - apps/api/tests/helpers/db.ts (mock helpers + sample VEVENTs) - apps/api/tests/auth/user.test.ts (5 todos — Plan 02) - apps/api/tests/broker/crypto.test.ts (5 todos — Plan 03) - apps/api/tests/broker/sync.test.ts (6 todos — Plan 03) - apps/api/tests/broker/poller.test.ts (5 todos — Plan 03) - apps/pwa/package.json - apps/pwa/tsconfig.json - apps/pwa/vite.config.ts (proxy /health + /api to :3000) - apps/pwa/index.html - apps/pwa/src/main.tsx (QueryClientProvider) - apps/pwa/src/App.tsx (fetches /health, renders stack: up/down) modified: []

key-decisions:

  • "Export app from src/index.ts without auto-starting server: enables direct import in Vitest tests without binding a port"
  • "Use vi.mock at module top level (not inside test): Vitest hoists vi.mock — placing inside describe/it causes warnings"
  • "pnpm-workspace.yaml allowBuilds.esbuild: true: pnpm 11 uses allowBuilds syntax, not onlyBuiltDependencies"
  • "zod pinned at ^3.25.0 (not ^4): conservative per RESEARCH — @hono/zod-validator@0.8.0 accepts both but v3 avoids unknown v4 API differences"

patterns-established:

  • "Pattern: Hono testability — export app from index.ts, use import.meta.url guard to start server only when run directly"
  • "Pattern: db mock — vi.mock('../src/db/client.js') at module level; override per-test with vi.mocked().mockRejectedValueOnce"
  • "Pattern: Wave 0 stubs — it.todo with plan reference so future agents know which plan fills each test"

requirements-completed: [CAL-01]

Metrics

duration: 6min completed: "2026-06-04"

Phase 01 Plan 01: Walking Skeleton — Summary

pnpm monorepo with Hono API, Drizzle/MariaDB schema (4 tables), Docker Compose stack, and /health route with real DB round-trip — ALL 3 tasks complete. Task 3 checkpoint cleared by orchestrator: stack brought up, drizzle-kit push applied the 4 tables to live MariaDB, and /health returned {"ok":true,"db":"up"} end-to-end. Required fixing 3 Docker build defects (see Deviations).

Performance

  • Duration: ~6 min
  • Started: 2026-06-04T13:46:55Z
  • Completed: 2026-06-04T13:53:00Z (Tasks 1-2; Task 3 is a human-action checkpoint)
  • Tasks: 2 of 3 complete (Task 3 is a blocking checkpoint)
  • Files modified: 28

Accomplishments

  • Full pnpm monorepo scaffold: apps/api (Hono + Drizzle + all pinned deps) and apps/pwa (Vite/React 19 + TanStack Query)
  • Drizzle schema with all 4 tables (users, memberCredentials, calendars, calendarEvents) following D-10 (oidc_iss+oidc_sub composite key) and D-13 (separate dtstart_utc/dtstart_date for all-day events)
  • /health route with real DB round-trip (SELECT 1) — GREEN: 2 tests pass, 503 on DB error
  • Docker Compose stack with mariadb:11 healthcheck, api depends_on service_healthy, redis stub
  • Wave 0 test harness: 5 test files, 21 todos (auth/user, broker/crypto, broker/sync, broker/poller) + 2 passing health tests
  • React PWA shell fetching /health and rendering stack: up/down

Task Commits

Each task committed atomically:

  1. Task 1: Scaffold monorepo, Docker Compose stack, and Vitest harness — 3f59156 (chore)
  2. Task 2: RED gate (failing health test) — f31711a (test)
  3. Task 2: Drizzle schema + DB client + /health slice (GREEN) — 96cda58 (feat)

Files Created/Modified

Key files (full list in frontmatter key-files):

  • apps/api/src/db/schema.ts — 4 Drizzle mysqlTable definitions with all constraints
  • apps/api/src/db/client.ts — db singleton export (drizzle mysql2 pool)
  • apps/api/src/routes/health.ts — GET /health with SELECT 1 round-trip
  • apps/api/src/index.ts — Hono app, /health before auth, serveStatic
  • apps/api/drizzle.config.ts — drizzle-kit push/migrate config
  • apps/pwa/src/App.tsx — React shell fetching /health
  • docker-compose.yml — mariadb:11 + healthcheck + api depends_on service_healthy

Decisions Made

  • Exported app from src/index.ts without auto-starting server (import.meta.url guard) so Vitest tests can import it directly without a real HTTP port
  • pnpm 11 uses allowBuilds.esbuild: true in pnpm-workspace.yaml (not onlyBuiltDependencies) — pnpm rewrote this during install
  • zod pinned ^3.25.0 per RESEARCH recommendation (not v4)

Deviations from Plan

None — plan executed exactly as specified. One minor pnpm API difference (allowBuilds syntax) was auto-handled.

Auto-fixed Issues

1. [Rule 3 - Blocking] pnpm 11 allowBuilds syntax

  • Found during: Task 1 (pnpm install)
  • Issue: pnpm install failed with ERR_PNPM_IGNORED_BUILDS: esbuild@*. pnpm 11 uses allowBuilds map (not onlyBuiltDependencies list used in older versions)
  • Fix: Set allowBuilds.esbuild: true in pnpm-workspace.yaml
  • Files modified: pnpm-workspace.yaml
  • Verification: pnpm install succeeded; all deps installed
  • Committed in: 3f59156 (Task 1 commit)

2. [Rule 1 - Bug] vi.mock hoisting in health test

  • Found during: Task 2 (writing TDD RED test)
  • Issue: Placing vi.mock() inside describe() blocks caused Vitest hoisting warnings; tests used resetModules approach which conflicted with hoisting behavior
  • Fix: Moved vi.mock to module top level; used vi.mocked().mockRejectedValueOnce() for per-test override
  • Files modified: apps/api/tests/health.test.ts
  • Verification: Both health tests pass; no hoisting warnings
  • Committed in: 96cda58 (Task 2 feat commit)

3. [Checkpoint clearing - Blocking] Docker image build broken for pnpm workspace

  • Found during: Task 3 (orchestrator bringing up the stack to clear the checkpoint)
  • Issue: The original apps/api/Dockerfile built from a ./apps/api context and could not work in a pnpm workspace:
    1. COPY package.json pnpm-lock.yaml* ./ + pnpm install --frozen-lockfile failed (ERR_PNPM_NO_LOCKFILE) — the lockfile lives at the repo root, not in apps/api/.
    2. pnpm 11 refused to run esbuild's build script (ERR_PNPM_IGNORED_BUILDS) because the root pnpm-workspace.yaml (which carries allowBuilds.esbuild) was outside the build context. Neither package.json pnpm.onlyBuiltDependencies nor .npmrc dangerously-allow-all-builds resolved it in the isolated context.
    3. dev stage ran node --watch dist/index.js but never compiled src→dist; production stage had invalid Dockerfile syntax (COPY apps/pwa/dist/ ./public/ 2>/dev/null || true) referencing a path outside its context.
  • Fix: Switched to the correct monorepo pattern — build from the repo-root context (docker-compose.yml build.context: ., dockerfile: apps/api/Dockerfile), copy the root pnpm-workspace.yaml + pnpm-lock.yaml + both workspace package.jsons, and pnpm install --frozen-lockfile --filter @familysync/api.... Reordered stages so production is the default; dev now reuses the builder output; dropped the invalid PWA COPY. Updated docker-compose.dev.yml volume mount to ./apps/api/src:/app/apps/api/src.
  • Files modified: apps/api/Dockerfile, docker-compose.yml, docker-compose.dev.yml
  • Verification: docker compose up -d --build succeeds; drizzle-kit push applied 4 tables; curl /health → {"ok":true,"db":"up"}; pnpm test → 2 passed / 21 todo.
  • Committed in: fix(01-01): build Docker image from repo-root pnpm workspace context

Total deviations: 3 (2 auto-fixed during execution, 1 Docker-build fix while clearing the Task 3 checkpoint) Impact on plan: All fixes necessary for install/tests/stack to work. No scope creep — same walking-skeleton capability, corrected build topology.

Issues Encountered

  • pnpm 11 changed the onlyBuiltDependencies API to allowBuilds map syntax — resolved automatically

User Setup Required

Task 3 requires manual steps. See checkpoint details returned to orchestrator:

  1. Copy .env.example to .env and set DB_PASSWORD + DB_ROOT_PASSWORD
  2. docker compose up -d mariadb and wait for healthy
  3. DB_HOST=127.0.0.1 ... pnpm exec drizzle-kit push from apps/api
  4. Confirm SHOW TABLES lists 4 tables
  5. docker compose up -d and curl http://localhost:3000/health → {"ok":true,"db":"up"}

Known Stubs

None. The serveStatic warning for ./public in tests is expected (no built PWA in test env) and is not a stub — the route exists and will serve correctly when the PWA is built.

Threat Surface Scan

No new threat surface beyond what was planned in the threat model:

  • T-01-01: .env excluded from git via .gitignore ✓
  • T-01-02: familysync user (not root) in docker-compose.yml ✓
  • T-01-03: /health unauthenticated, returns only {ok, db} ✓

Next Phase Readiness

  • Task 3 checkpoint CLEARED — schema pushed, stack verified, /health green
  • Plan 02 (OIDC auth) can proceed — imports db, users schema
  • Plan 03 (broker) depends on this schema + crypto pattern

Self-Check: PASSED

  • apps/api/src/db/schema.ts exists: FOUND
  • apps/api/src/db/client.ts exists: FOUND
  • apps/api/src/routes/health.ts exists: FOUND
  • apps/api/src/index.ts exists: FOUND
  • docker-compose.yml exists with healthcheck: FOUND
  • apps/pwa/src/App.tsx fetches /health: FOUND
  • Commits 3f59156, f31711a, 96cda58: FOUND

Phase: 01-foundation-broker-spike Completed: 2026-06-04 (Tasks 1-2; Task 3 at checkpoint)

Reference in New Issue View Git Blame Copy Permalink