JCEEE
365 lines
58 KiB
Markdown
365 lines
58 KiB
Markdown
# FamDone v2 — Development Memory
|
||
|
||
## 2026-08-17 — Schema collapse to single source of truth (Option 1)
|
||
|
||
- **Decision**: abandoned incremental migration history. `SCHEMA_PLAN` (`shared/pb/schema.ts`) is now the true, current schema; `migrate.ts` collapsed from 2096 → 183 lines to a **fresh-only bootstrap** (`ensureSchema()` skips if `fams` exists — no incremental steps). The app isn't live and data is disposable, so there's nothing to preserve; a schema change = update `SCHEMA_PLAN` + wipe PB + reboot.
|
||
- **Folded the net effect of ~40 hand-written steps into `SCHEMA_PLAN`** (verified against the live PB): `fams.{payday,lastIssued,paydayTime,timezone}` (dropped stale `seasons`), `settings.simulateEow`, `messages.clientId`, `assigned_chores.{isTodo,startDate,completeBy}`. `bonus_configs.memberId`, `weekly_history/rewards/assigned_chores/completions.memberId` → `users`.
|
||
- **Out of `SCHEMA_PLAN`** (handled in `migrate.ts`): the native `users` auth collection (custom `famId`/`role`/`username`/`color` fields + `username` unique index + password-auth identity + famId-scoped rules, via `ensureUsers`) and the superuser-only `otp` collection (null rules — `col()` can't express `null`, via `ensureOtp`).
|
||
- **Gotcha**: `col()` coerces `rules.listRule ?? ""` → can't emit `null` rules, so `otp` stays out of the plan. `ensureSchema` needs the live PB to confirm the true schema (SCHEMA_PLAN was stale before this).
|
||
- Verify path: wipe dev PB + restart frontend (needs user OK) so `migrateOnBoot` rebuilds from `SCHEMA_PLAN`.
|
||
|
||
## 2026-08-17 — Hono proxy removed: everything runs in SvelteKit services
|
||
|
||
- **Decision**: deleted the `proxy/` Hono service entirely. All business logic (admin CRUD, member kanban, weekly summary/EOW, bonus evaluation/trigger/progress, rewards claim/issue, chat, payday settlement, debug data-gen) now lives in `frontend/src/lib/server/services/`, grouped **by app area** (not by role): `fam.ts`, `chores.ts`, `completions.ts`, `rewards.ts`, `bonuses.ts`, `chat.ts`, `settings.ts`, `crud.ts`, `debug.ts`, plus a generic per-resource `crud.ts`. `createServices(pb, user)` returns a per-feature binder; `servicesFor(event)` is the shorthand for loads/form actions. **No role guard** — PB collection rules on the acting user's token are the security boundary (the `admin`/`member` split no longer exists as separate files).
|
||
- **Wiring**: `hono.admin.*` (form actions/loads) and `memberApi.*`/chat are now direct service calls or SvelteKit `/api/*` routes (`completions/toggle`, `members/rewards/[id]/claim`, `members`, `fam/[famId]/payday`, `chat`, `admin/[famId]/assigned-chores`). Browser admin calls (chores grid) hit SvelteKit `/api/admin/*`. The `/api/*` routes read auth straight from `event.locals` (`locals.user` + `createPbClient(locals.pbToken)`) — a separate `actingClient` helper was dropped as redundant since `hooks.server.ts` already resolves the session. No Authorization header; the httpOnly `pb_token` cookie is the auth for same-origin calls.
|
||
- **Migration relocated**: `proxy/src/migrate.ts` → `frontend/src/lib/server/migrate.ts` (env now via `$app/env/private` + `PB_ENDPOINT` from `pocketbase.ts`), run once per process by `migrate-boot.ts`, kicked off in `hooks.server.ts` (`void migrateOnBoot()`). Schema source of truth remains `shared/pb/schema.ts`.
|
||
- **Infra**: `pnpm-workspace.yaml` (only `frontend`), root `package.json` (`dev` = `pnpm --filter frontend dev`), `docker/Dockerfile` (no proxy build/deploy), `docker/entrypoint.sh` (no proxy start; app runs schema migration on boot), `docker/nginx.conf` (`/api/` block removed → falls through to `location /` → SvelteKit `:3000`; `/pb/api/` unchanged). Removed `PROXY_URL` env + `PROXY_PORT` from `shared/config.ts` and `frontend/src/env.ts`. Dead `memberApi.myChores`/`requestAll` removed.
|
||
- **Typecheck**: frontend `svelte-check` = 12 pre-existing canary errors (`.svelte` implicit-any, qrcode decl, RewardType/Frequency casts, signup `string|undefined`); **zero errors in the migration's files**. `pnpm build` (adapter-node) succeeds.
|
||
- **Note**: dev servers were left running; the now-deleted proxy `tsx watch` (`:3456`) will error and the frontend dev server needs a restart to drop `PROXY_URL`/load `migrateOnBoot` + the removed `/api` Vite proxy.
|
||
|
||
## UI Component Architecture (Jul 2026)
|
||
|
||
### Layout Hierarchy
|
||
```
|
||
+layout.svelte ← global styles, meta, favicon
|
||
├── /login, /signup, /join/* ← auth pages (no shell)
|
||
└── [fam]/+layout.svelte ← Shell: Sidebar + TopNav + Footer + claim toast
|
||
├── [fam]/+page.svelte ← fam dashboard
|
||
├── [fam]/{username}/+page.svelte ← parent=admin overview, child=kanban
|
||
├── [fam]/{username}/chores/+page.svelte ← parent only
|
||
├── [fam]/{username}/ledger/+page.svelte ← parent only (rewards/chores/todos)
|
||
├── [fam]/{username}/bonuses/+page.svelte ← parent only
|
||
├── [fam]/{username}/settings/+page.svelte ← parent only
|
||
└── [fam]/{username}/preferences/+page.svelte ← both roles
|
||
```
|
||
|
||
### Sidebar (collapsible to mini-mode)
|
||
- Header: app name (FamDone)
|
||
- Admin CTAs: Dashboard, Chores, Rewards (badge count), Bonuses
|
||
- Member CTAs: Dashboard, Preferences
|
||
- Footer: family name, Settings (admin only), Log out
|
||
- Role-aware: items differ based on admin vs member route
|
||
|
||
### TopNav
|
||
- Slot `announcement` (center) — system/family messages
|
||
- Slot `actions` (right) — user status, claim/message
|
||
|
||
### Page Content
|
||
- `ViewHeader` — title + subtitle + tool bar (tabs, weeknav, sort)
|
||
- `CardGrid` — 3-column grid, Cards span columns via `cols` prop
|
||
- `Card` — 1/2/3 col span, micro-layout per page
|
||
- `Accordion` — for settings / log sections
|
||
- `Button` — consistent CTAs with `variant` (primary/secondary/ghost/danger) and `size` (sm/md/lg)
|
||
|
||
### Components (frontend/src/lib/components/)
|
||
- `Sidebar.svelte`, `TopNav.svelte`, `Footer.svelte`
|
||
- `ViewHeader.svelte`, `Card.svelte`, `CardGrid.svelte`
|
||
- `Button.svelte`, `Accordion.svelte`
|
||
- `icons.ts` — SVG icon strings (no icon library dep)
|
||
|
||
### Role-Based Auth (Jul 2026)
|
||
|
||
- Members have `role` field (`'parent' | 'child'`, added to `members` collection)
|
||
- Parents authenticate via email/password (PB session JWT), children via device token
|
||
- `/api/admin/signup` now creates a member record for the parent with `role: 'parent'`
|
||
- `/api/admin/login` returns `memberName`, `memberColor`, `role` alongside session info
|
||
- `/api/members/verify-token` returns `role` for the frontend
|
||
- `requireAdmin` middleware checks `users` (`role='parent' && id = userId`, scoped by `famId`)
|
||
- **Removed `fam_admins` collection (Aug 2026):** parent identity fully lives on the `users` record (`famId`, `role`, `name`, `color`, `email`). `requireAdmin`, `authorizeFamReq`, `resolveChatActor`, admin `/profile` get/patch, and the legacy proxy `/signup`/`/login` now read/write `users` instead. Signup no longer creates a `fam_admins` row; superadmin stats derive `parentEmail` from `users role='parent'`. Migrate step 34 drops the collection.
|
||
- **Removed `fams.inviteCode` (Aug 2026):** join flow is OTP-based (`user_configs.otp`), so the stored/displayed/regenerated invite code was never consumed. Removed `randomCode()` at signup, the `/regen-invite` endpoint + `hono.admin.regenInvite` action, the `inviteCode` type/field, and added migrate step 34 to drop the field.
|
||
- Frontend sidebar is role-aware: `isParent = session !== null`
|
||
- **No more `/admin` prefix** — admin pages live under `/{fam}/{parent-username}/chores` etc.
|
||
|
||
### Routes (Jul 2026)
|
||
|
||
```
|
||
/ Landing (SaaS marketing)
|
||
/signup Signup (creates parent user + member)
|
||
/login Login (returns member info, redirects to /{fam}/{memberName})
|
||
/join/:code Member invite (child)
|
||
/join/:code/:member Member invite with pre-selected name
|
||
/admin Super admin dashboard (unchanged)
|
||
/{fam} Fam dashboard
|
||
/{fam}/{username} Parent → admin overview, Child → kanban
|
||
/{fam}/{username}/chores Parent: chore management
|
||
/{fam}/{username}/ledger Parent: rewards / chores / todos ledger
|
||
/{fam}/{username}/bonuses Parent: bonus configs
|
||
/{fam}/{username}/settings Parent: family settings
|
||
/{fam}/{username}/preferences Both: edit name/color
|
||
/api/* Hono proxy
|
||
```
|
||
|
||
### Architecture Decisions
|
||
|
||
### 2026-06-23 — Monorepo & Docker Setup
|
||
|
||
- **Ports**: Frontend = `2080`, Proxy = `3456`, Container ext = `3001`. Port `3000` reserved/conflict.
|
||
- **Shared config**: `config.ts` at root for dev/build-time values (e.g. `PROXY_PORT`). Runtime config via env vars. `.env` tracks ports, `.env.example` committed.
|
||
- **Docker**: 2 Dockerfiles — `Dockerfile` (prod, multi-stage with nginx) and `Dockerfile.dev` (PocketBase for dev).
|
||
- **Nginx**: Prod container uses nginx to route `/api/*` → Hono (`:3456`), `/*` → SvelteKit (`:2080`).
|
||
- **Dev workflow**: `pnpm dev` at root runs SvelteKit + Hono in parallel. PocketBase via `Dockerfile.dev`.
|
||
- **Proxy runtime**: Uses `process.env.PROXY_PORT` instead of importing `config.ts` (avoids `rootDir` issues in `tsc`).
|
||
|
||
### 2026-06-23 — Hono Proxy for All Data; Svelte Reactivity Only
|
||
|
||
- **All data operations** (reads and writes) go through the Hono proxy, never directly to PB SDK.
|
||
- **UI reactivity** is purely Svelte `$state` / `$derived` / `$effect` — no PB SDK `.subscribe()` / SSE.
|
||
- The `/debug` page's PB SDK `subscribe()` was experimental only; final apps fetch via Hono proxy and update Svelte state reactively.
|
||
|
||
### 2026-07-28 — Auth Bug: Join Flow Set Session Cookie for Children
|
||
|
||
- **Bug**: Both `join/[code]/+page.server.ts` and `join/[code]/[member]/+page.server.ts` called `setSessionCookie()` with `userId: memberId` (the child's PB record ID). This made `event.locals.session` truthy for children, causing `[username]/+page.server.ts` to enter the admin branch and call `hono.admin.*` endpoints. The proxy's `requireAdmin` checked `fam_admins` for the child's member ID (which doesn't exist) and returned 401.
|
||
- **Fix**: Removed `setSessionCookie()` from both join pages. Children only get a `device_token` cookie. The session cookie is only for email/password-authenticated parents, set by `/login` and `/signup`.
|
||
- **Lesson**: Children must never get a session cookie. The auth table in AGENTS.md says "Member → device token, no expiry" — the code must match.
|
||
|
||
### 2026-08-03 — Family Timezone Setting + Tz-Aware Week Math
|
||
|
||
- **Feature**: `fams.timezone` (IANA name or `"auto"`) added via `migrate.ts` 5d/5e (field + backfill `"auto"`). Exposed in settings Payday card (dropdown from `COMMON_TIMEZONES`, ~40 entries, + "Auto (detected)"). Set via `PATCH /api/admin/:famId/fam` alongside payday/paydayTime.
|
||
- **Shared module** `timezone.ts` (root, imported by both proxy and frontend): `resolveTz`, `dateStrInTz`, `weekdayInTz`, `todayInTz`, `addDaysStr` (pure UTC), `weekStart(payday, tz)`, `wallClockToUtc` (iterative 4-pass Intl, DST-safe), `COMMON_TIMEZONES`.
|
||
- **Bug fixed** ("5 days left on Monday"): old `mondayOf`/`addDays`/`daysLeft` used local `setDate` + `toISOString()`. On BST Sunday Aug 9 local midnight → UTC Aug 8, so Monday showed 5 days left instead of 6. Now the child page computes `weekStart`/`todayIso`/`daysLeft` via `weekStart(1, famTz)` + `addDaysStr` + `todayInTz`, giving 6. Verified: Mon Aug 3 → weekStart 2026-08-03, weekEnd 2026-08-09, daysLeft 6.
|
||
- **releaseWeek time gate**: now tz-aware. `weekStart(payday, tz)` for idempotency check; `target = new Date(wallClockToUtc(weekStartToday, paydayTime, tz))`. Verified: payday Mon 20:00 Europe/London (BST) → target `2026-08-03T19:00:00Z`; `auto` resolves to server tz. Returns `{settled:false, notYet:true, weekStart, target}` before the time.
|
||
- **Proxy threads `tz`** through weekly-summary, eow-preview, bonus-configs/progress, `evaluateFam`, tallies, manual trigger, complete-week, `releaseWeek`. `my-chores` returns `timezone`; child `+page.server.ts` passes it to `data.timezone`; parent passes `data.fam.timezone`.
|
||
- **Frontend child page**: `rawFamTz = data.timezone || data.fam?.timezone || 'auto'`, `famTz = resolveTz(rawFamTz)`. `todayChild`, `todayIso`, `mondayOf`, `addDays`, `isPaydayToday` (via `weekdayInTz`), `paydayTarget` (via `wallClockToUtc`), `today` all tz-aware. `mondayOf` now delegates to `tzWeekStart(1, famTz)`.
|
||
- **Smoke-tested live** (fam `v56f0f8o147kj1x`): GET fam returns timezone, PATCH sets Europe/London, time-gate returns correct target, `auto` resolves to server tz, settings page SSR shows the dropdown, child page 200. Fam restored to payday=0, paydayTime=18:00, timezone=auto, lastIssued=2026-08-02.
|
||
- **Typecheck**: proxy `tsc --noEmit` 28 errors (all pre-existing rootDir/`.ts`-import/`key: never`/implicit-any baseline); frontend `svelte-check` 9 errors (baseline; no new errors in edited files).
|
||
|
||
### 2026-08-04 — Terminology: "Payday" + Countdown to Settlement Day
|
||
|
||
- **Decision**: Standardize the user-facing term on **"payday"** for the weekly settlement event/day. "EOW" is ambiguous (window-close vs settlement day) and is now dropped from user-facing strings. Keep "week" for the Sun→Sat earning window. Internal identifiers (`eow*`, `simulateEow`, `eowPreview`, CSS `eow-*`) left as-is.
|
||
- **daysLeft now counts to settlement day**: `daysLeft` on the child dashboard counts to `weekStart + 7` (the next payday day) instead of `weekEnd = weekStart + 6`. So Tue Aug 4 with payday=Sun shows 5 days until payday. Hero label updated to "days until payday".
|
||
- **User-facing renames**: hero `days left` → `days until payday`; debug card `Simulate End-of-Week` → `Simulate Payday`; error `Failed to preview EOW` → `Failed to preview payday`; settings hint reworded to lead with "Payday:".
|
||
|
||
### 2026-08-04 — DDMMYY Date Rule + Debug Payday Preview Fix
|
||
|
||
- **Rule added (AGENTS.md)**: all user-facing dates are DDMMYY (compact, e.g. `040826` for 4 Aug 2026). Shared helper `formatDDMMYY()` in `frontend/src/lib/format.ts` (extracted from the local copy in `chores/+page.svelte`). Never render raw `YYYY-MM-DD` to users.
|
||
- **Bug**: the admin "Preview payday" card showed all-time totals (e.g. "280 pts £288.00 14 chores" for zooney) because the proxy's `eow-preview` reward queries (`rewardPointsList`/`rewardCashList`) had NO date filter, summing every claimed reward ever. `complete-week` (the real settlement snapshot) scopes with `date >= ws`.
|
||
- **Fix**: added `&& date >= '${ws}'` to both reward queries in `eow-preview` (`proxy/src/index.ts`) so the preview matches what the rollover actually records. Verified live: zooney now shows this-week `220 pts / £16.00 / 14 chores / bonus 10`.
|
||
- **UI**: removed the no-op **Simulation ON/OFF** toggle (settings.simulateEow flag drives no behavior) — it was the source of "simulation on/off vs preview rollover" confusion. Card is now just "Debug: Preview payday" → "Preview payday" button. Debug card dates now render via `formatDDMMYY`.
|
||
- **Typecheck**: frontend `svelte-check` still at 12 baseline errors (no new); proxy `tsc` unchanged pre-existing baseline.
|
||
|
||
### 2026-08-04 — Preview Payday Extends to Child Dashboard
|
||
|
||
- **Feature**: "Preview payday" now enables a family-wide preview mode that the child dashboard reacts to. `?/previewEow` action calls `eowPreview` then `hono.admin.updateSettings({ simulateEow: true })`, returning `{ preview, simulateEow: true }`. A "Turn off preview" button (`?/setEow`, `on=false`) clears it.
|
||
- **Child notice**: `my-chores` (`proxy/src/index.ts`) now returns `simulateEow: !!settings.simulateEow`; child `+page.server.ts` passes it as `data.simulateEow`. Child kanban renders a `.preview-notice` banner ("Payday preview — your parent is checking this week's payday. Nothing is paid out yet.") when the flag is set. Admin card shows a `.eow-mode-on` note + "Turn off preview" when active.
|
||
- **Note**: `simulateEow` (settings.simulateEow) was previously a no-op debug flag; it now meaningfully drives preview mode across admin + child views.
|
||
- **Verified live**: POST `?/previewEow` sets `settings.simulateEow=true` (GET settings confirms); child SSR page data carries `simulateEow:true`; control case (flag off) renders no notice. Test data restored afterwards (zooney deviceToken + flag reset to false).
|
||
|
||
### 2026-08-04 — Payday-Gated Bonus Payouts
|
||
|
||
- **Feature**: weekly/monthly period bonus rewards are now **claimable only on payday** (not the moment they're met). Rewards gain `claimable: 'immediate' | 'payday'` + `settleDate` (YYYY-MM-DD, server-side). The bonus-met notice stays exciting on the child dash — the reward line shows a locked "🔒 pays out {DDMMYY}" badge and skips the request button pre-payday.
|
||
- **Stamp logic**: `claimableStamp()` in `proxy/src/index.ts` — periods `weekly`/`monthly` → `{ claimable: 'payday', settleDate: nextPaydayAfter(periodEnd) }`; else `immediate`. Manual bonus triggers (`/bonus-configs/:id/trigger`) stamp `immediate` (parent-initiated, not a scheduled payout). All 3 `evaluateFam` create sites (individual/collaborative/competitive) use `claimableStamp`. `nextPaydayAfter()` helper added to `timezone.ts`.
|
||
- **Enforcement**: member `claim` endpoint checks `assertPaydayUnlocked()` (throws `"This bonus pays out on payday (…settleDate) — hang tight!"`, returned as HTTP 400); `request-all` skips payday-gated rewards not yet settled. Admin `Issue`/`Issue All` are parent discretion and unaffected.
|
||
- **UI**: child wallet renders locked badge for pre-settle payday rewards; admin "Claims → Outstanding" shows a `🔒 {DDMMYY}` hint. Both reuse `formatDDMMYY()`. (Later: switched both to `formatShortDate()` → "🔒 pays out 9 Aug"; child `owedCash` banner excludes payday-locked rewards so "You've earned £X — go get it!" no longer shows for rewards that aren't claimable yet.)
|
||
- **Schema**: `rewards.claimable` (select, required) + `rewards.settleDate` (text) added in `proxy/src/migrate.ts` + `proxy/scripts/seed.ts`. PB's `required` select rejects empty on write; legacy null-claimable rewards are treated as `immediate` by both proxy and frontend, so no data backfill was needed.
|
||
- **Verified live**: `complete-week` → `evaluateFam` recreated the weekly Pocket Money reward with `claimable=payday, settleDate=2026-08-09` (Sunday payday after Sun→Sat week); member claim pre-payday → 400 with friendly message + status stays `unclaimed`; `request-all` returns `{count:0}`; claim succeeds after settleDate.
|
||
- **Ops note**: the dev proxy's `tsx watch` had silently frozen (file edits at 09:49 weren't picked up by a child started 09:47). Fixed by killing the watcher tree with explicit PIDs and relaunching `pnpm dev` (nohup → `/tmp/proxy_dev.log`). `pkill -f "tsx watch src/index.ts"` hangs the shell — use `kill <pid>` instead.
|
||
|
||
### 2026-08-04 — Dev Servers: Always Reuse Existing 2080/3456
|
||
|
||
- **Rule**: NEVER start our own dev servers. Always use the already-running ones: proxy `192.168.1.225:3456` (tsx watch, reloads on edit) and frontend `localhost:2080` (vite HMR). Don't spawn `nohup pnpm dev`, `tsx watch`, or extra vite instances — it wastes time/tokens. Only kill/restart when the user explicitly asks (or a watcher is demonstrably stale, and then only after asking). Prefer short targeted curls and reuse one auth `TOKEN` across commands in the persistent shell.
|
||
|
||
### 2026-08-04 — Chores Page Accordion Quick Fixes
|
||
|
||
- **Add actions moved into sections**: removed the blue round `+` from the member swimlane header and the Templates column header. Both replaced by a shared full-width dashed `＋ Add a todo` / `＋ New template` button (`.add-inline`) at the top of the Todos accordion content and the Templates list respectively.
|
||
- **Accordions default open**: `accordionState` lookup defaults to `{ chores: true, todos: true }` (`?? true` in the template + toggle), so both sections load expanded on page load; still toggleable. Redundant empty-state "+ Add a todo" button and `.add-todo-btn`/`.empty-cta` CSS removed.
|
||
- **Check**: frontend `svelte-check` stays at 12 baseline errors.
|
||
|
||
### 2026-08-04 — Human Dates for Todo "Due" (Not DDMMYY)
|
||
|
||
- **Problem**: the chores todo card rendered `due 050826` (DDMMYY code) — ambiguous/terrible for a due date.
|
||
- **Fix**: added `formatShortDate()` to `frontend/src/lib/format.ts` — renders `5 Aug` (adds ` 26` when the year isn't the current one). Chores todo card now shows `due 5 Aug`. AGENTS.md date rule updated: DDMMYY for dense/range contexts, `formatShortDate()` for single human-readable dates like due dates.
|
||
|
||
### 2026-08-04 — Child-Dashboard Design Lead Applied to All Pages
|
||
|
||
- **Design principal** (from `[fam]/[username]` child dash): gradient hero lead (`linear-gradient(135deg, #6366f1, #8b5cf6 55%, #a855f7)`, radius 16px, glow shadow, white text), gradient stat tiles, rounded white cards.
|
||
- **`ViewHeader` hero variant**: added `hero` prop to `frontend/src/lib/components/ViewHeader.svelte` — renders the title/subtitle/tools on the gradient hero (tabs/nav/sort get tinted-on-white styling). Off by default, so no behavior change elsewhere.
|
||
- **Applied `hero` to**: admin dashboard (fam name), chores, bonuses, rewards, settings, preferences, platform admin `/admin`.
|
||
- **Admin dashboard stat tiles**: added 4 gradient tiles (members / points / cash / chores done) reusing the child `.tiles`/`.tile` pattern + new `.tile-members`/`.tile-chores` colors, from a new `adminTiles` derived summing `summary.summaries`. Also fixed admin subtitle `Week of {YYYY-MM-DD}` → `Week of {DDMMYY}`.
|
||
- **Check**: frontend `svelte-check` stays at 12 baseline errors. Note: frontend dev server on :2080 was not running when verified (proxy :3456 up).
|
||
|
||
|
||
|
||
### 2026-08-06 — Env Consolidation: `SERVER_IP`, `PROXY_URL`, and SvelteKit env only
|
||
|
||
- **`config.ts` is proxy-only.** It now holds just the three ports (`FRONTEND_PORT`/`PROXY_PORT`/`PB_PORT` = `2080`/`3456`/`8090`). SvelteKit **never imports `config.ts`** — SvelteKit env vars are declared in `frontend/src/env.ts` and read via `$app/env/*`. Deleted the stale `config.js/.d.ts/.map` artifacts.
|
||
- **`frontend/src/env.ts`** declares: `PROXY_URL` (public, default `http://127.0.0.1:3456`), `SERVER_IP` (public, default `192.168.1.225`), `PB_EMAIL`/`PB_PASSWORD` (private, defaults). `PUBLIC_PB_URL` removed (was the source of a startup crash when unset).
|
||
- **Deleted `frontend/src/lib/server/env.ts`** (untracked). All server modules now `import { PROXY_URL } from '$app/env/public'` (`hono.ts`, `auth.ts`, `+layout.server.ts`, `+page.server.ts`, `preferences`, `join/[code]/[member]`). `admin/+page.server.ts` imports creds from `$app/env/private`.
|
||
- **`frontend/src/lib/pocketbase.ts` (browser) + `pb-admin.ts`**: `PB_ENDPOINT = import.meta.env.PROD ? '/pb' : \`http://${SERVER_IP}:8090\``. (Fixed a bug where `pocketbase.ts` used `import.meta.env.SERVER_IP` → undefined.)
|
||
- **`proxy/src/env.ts`** (new): `PB_ENDPOINT = SERVER_IP ? \`http://${SERVER_IP}:8090\` : \`http://127.0.0.1:8090\``. Dev env is loaded by the proxy's `dev`/`seed` scripts via `tsx --env-file-if-exists=../.env` (pnpm has no `--env-file`; `NODE_OPTIONS='--env-file=…'` is rejected by Node). No `loadEnvFile` hack in code.
|
||
- **Docker**: removed dead `ENV PB_ENDPOINT` from `Dockerfile`; `EXPOSE 3001` (was `3005 8090`); compose public port is `${PORT:-3001}:3001`, creds default to the code fallback, redundant `FRONTEND_PORT`/`PROXY_PORT` passthrough dropped; `entrypoint.sh` simplified (`PB_DATA=/app/pb_data`, `PORT=$FRONTEND_PORT`, no `:-` fallbacks).
|
||
- **Frontend deps added** (were missing imports): `chart.js`, `qrcode`, `@hiseb/confetti`.
|
||
- **Build checks**: proxy + frontend `pnpm build` clean.
|
||
|
||
### 2026-08-06 — Dev PB data incident (pb-dev) — see RULES.md "Dev vs Prod PocketBase data"
|
||
|
||
- **Symptom**: `pnpm dev` proxy migrate failed; PB superuser auth returned `HTTP 500 "Something went wrong"`; could not log into the PB admin UI.
|
||
- **Root cause**: the permanent dev PB container **`pb-dev`** (publishes `:8090`, data in host `./pb_data`) had a **broken bind mount** — it was serving an empty throwaway store, so the `debug@famchamp.dev` superuser didn't exist. The real `data.db` was on the host but the container wasn't seeing it.
|
||
- **Fix**: recreated `pb-dev` with the mount correctly attached (`-v "$PWD/pb_data:/pb_data"`, `pocketbase serve --http=0.0.0.0:8090 --dir=/pb_data`). Superuser auth then returned 200 on both `127.0.0.1:8090` and the Tailscale `SERVER_IP:8090`.
|
||
- **Watch-out**: a careless `docker run` with a **fresh volume** (my first attempt, aborted in time) would have wiped the permanent PB data. Restore command is in RULES.md. Two containers (`pb-dev` :8090 and the docker app's internal PB :8091) currently **share the same host `./pb_data`** — be careful with both.
|
||
|
||
### 2026-08-06 — Added root `shared/` for cross-package code
|
||
- Created `shared/timezone.ts` (moved from root `timezone.ts`). Imported by `frontend/src/routes/[fam]/[username]/+page.svelte`, `.../settings/+page.svelte`, and `proxy/src/index.ts`. Deleted the root `timezone.ts`.
|
||
- Created `shared/pb/schema.ts` — single source of truth for the PocketBase schema + field builders (`SCHEMA_PLAN` ordered collection plan + `text/select/rel/...` helpers). Both `proxy/src/migrate.ts` (`ensureSchema`) and `proxy/scripts/seed.ts` now iterate `SCHEMA_PLAN`; kills the previous duplicated schema/field-helper definitions in both files.
|
||
- Reason: `timezone.ts` and the PB schema are consumed by more than one package; `shared/` is the root location both can reach. Rule added to RULES.md: shared code lives in `shared/`, never inside `frontend/` or `proxy/`.
|
||
- Note: proxy `tsc --noEmit` already errors on `.ts`-extension imports (`allowImportingTsExtensions` unset) — pre-existing, not from this change. Runtime uses esbuild (build) + tsx (dev), both of which bundle the `shared/` imports correctly. Verified `pnpm build` clean for both packages.
|
||
|
||
### 2026-08-07 — `@shared/*` import alias (path alias, not a pnpm package)
|
||
- Moved `config.ts` → `shared/config.ts`. All `shared/` code is now imported as `@shared/*` instead of relative `../../shared/...`.
|
||
- This is a **path alias**, not a pnpm workspace package (`@shared` alone isn't a valid npm package name; a real package would need `@scope/name`).
|
||
- Proxy: `tsconfig.json` sets `paths: { "@shared/*": ["../shared/*"] }`; esbuild build adds `--alias:@shared=../shared`; tsx resolves via tsconfig paths. Proxy keeps `.ts` extensions (`@shared/config.ts`).
|
||
- Frontend: uses `kit.alias` in `vite.config.ts` (NOT `paths` in `frontend/tsconfig.json`, which SvelteKit warns against). Frontend imports shared files **without** the `.ts` extension (`@shared/timezone`) because `rewriteRelativeImportExtensions` only rewrites relative paths.
|
||
- Verified: proxy build + frontend build + `svelte-check` all clean for `@shared/*` (svelte-check still reports pre-existing `qrcode` types + CSS warnings).
|
||
- Docker note: runtime image only copies `frontend/build` + `proxy/dist` (both already bundle `shared/`), so `shared/` needn't be copied into the image.
|
||
|
||
### 2026-08-10 — Dev runtime cleanup (PB instances / containers)
|
||
- **Removed** test container `31e74178b3f0` (`famdone-service-app-1`, host :3010 + :8092). It ran **PB 0.39.10** and bound the **same host `pb_data`** as pb-dev → two PBs (v0.25 + v0.39) writing one SQLite DB = corruption/lock risk (likely source of dev instability/login lag).
|
||
- **Killed** 7 stale host `tsx watch` dev-proxy processes (Jul 28–Aug 5) + my throwaway 0.39 PBs.
|
||
- **Reset pb_data**: stopped pb-dev, wiped `/home/threejjjs/development/famchamp/pb_data`, **recreated** pb-dev container (fresh v0.25 store) with `--automigrate=false`, recreated dev superuser `debug@famchamp.dev`/`debug123`.
|
||
- **Why recreate pb-dev**: v0.25 automigrate had baked stale `pb_migrations` into the old container's writable layer; on a fresh store they failed (`Failed to apply migration ...: no rows in result set`).
|
||
- **Desired end state (confirmed)**: `8090` = pb-dev (v0.25, single instance, automigrate off); `3001`+`8091` = PROD app `cffd636cc772` (kept, not live); PROD pb_data at `/data/coolify/.../pb_data` (separate from dev).
|
||
|
||
### 2026-08-10 — PB 0.25 → 0.39 migration (branch `feature/migrate-pocketbase`)
|
||
- **Decision**: keep our own `migrate.ts` schema-as-code (API-driven, does data migrations + rule locking), NOT PocketBase's built-in automigrate (schema-only, generates version-specific migration files, and generates conflicting snapshots on upgraded stores). Disable PB automigrate in the runtime.
|
||
- **Verified against 0.39.10** (throwaway binaries on `127.0.0.1:8098/8099`, temp data dirs):
|
||
1. Fresh store: `migrate()` bootstraps all 14 `SCHEMA_PLAN` collections + every field migration cleanly (schema field builders are 0.39-compatible).
|
||
2. Existing 0.25 `pb_data` → 0.39: opens & serves with **`--automigrate=false`** and no stale `pb_migrations` dir. (Without this, automigrate writes a snapshot to `./pb_migrations` relative to CWD that conflicts with existing collections → "Collection name must be unique".)
|
||
3. JS SDK `pocketbase@^0.27.0`: `authWithPassword` + public reads OK; realtime SSE endpoint serves `PB_CONNECT`.
|
||
- **Code changes on branch**:
|
||
- `docker/Dockerfile` `POCKETBASE_VERSION` → `0.39.10`.
|
||
- `docker/Dockerfile.dev` → `0.39.10` + `CMD ... --automigrate=false`.
|
||
- `docker/entrypoint.sh` → `pocketbase serve ... --automigrate=false`.
|
||
- `proxy/src/env.ts` → added non-breaking `PB_ENDPOINT` env override (used to point migrate at a throwaway PB on another port; default dev/prod split unchanged).
|
||
- **⚠️ 0.39 schema breaking change**: PB 0.39 does **NOT** auto-add `createdAt`/`updatedAt` to **API-created** collections (0.25 did). The chat store filters/sorts on a custom `messages.createdAt`, so a fresh 0.39 store is missing it → raw PB 400. Fixed two ways:
|
||
- `shared/pb/schema.ts`: `messages` now declares `date("createdAt")` explicitly (source of truth → `ensureSchema`).
|
||
- `proxy/src/migrate.ts`: the "messages already exists" branch now adds `createdAt` if missing (idempotent hardening for drifted/upgraded stores).
|
||
- **Dev now on 0.39.10**: pb-dev rebuilt from branch `Dockerfile.dev` (0.39.10 + `--automigrate=false`), fresh store on :8090, superuser `debug@famchamp.dev` re-verified, `migrate()` bootstraps schema + applies `messages.createdAt` fix cleanly.
|
||
- **Prod upgrade steps**: backup `pb_data` → run the 0.39 image (automigrate off) → run `migrate()` → verify no drift (`messages.createdAt`, `id.autogeneratePattern`).
|
||
|
||
### 2026-08-10 — Revert PB to 0.25.8 (backtrack from 0.39)
|
||
- **Decision**: backtrack off the PocketBase 0.39 bump (introduced in commit `3725c54` via `ARG POCKETBASE_VERSION=0.39.10`) and work from a **0.25.8 baseline** in BOTH dev and prod, then migrate to 0.39 deliberately later.
|
||
- Reverted `docker/Dockerfile` `POCKETBASE_VERSION` back to `0.25.8` (matches `docker/Dockerfile.dev`). Dev `pb-dev` and the docker app internal PB `:8091` share host `./pb_data`.
|
||
- **Migration schema scripts (DO NOT FORGET)**: the schema single source of truth is `shared/pb/schema.ts` (`SCHEMA_PLAN`), iterated by `proxy/src/migrate.ts` (`ensureSchema`) and `proxy/scripts/seed.ts`. The chat `messages` / `chat_typing` collections are defined there **without** an explicit `createdAt` — they rely on PB auto-adding it on first create.
|
||
- The 0.39 prod `messages` drift (missing `createdAt`, then `id` "Cannot be blank" after a raw field PATCH) came from schema mismatch during the bump. When migrating 0.25→0.39, reconcile the schema scripts against 0.39's field semantics (incl. system `id` `autogeneratePattern`) instead of patching collections by hand.
|
||
|
||
### 2026-08-15 — Members→users migration, OTP child login, cookie httpOnly, slugify
|
||
|
||
- **Migration (members → users, run live + verified):** deleted the `members` collection and repointed the 5 `memberId` relations (`assigned_chores`, `completions`, `rewards`, `weekly_history`, `bonus_configs`) → `users`. Added `users.name` + `users.color`, backfilled child name/color; backfilled parent `role` (`''` → `'parent'`). Scoped `users` rules: list/view = `famId = @request.auth.famId`, update/delete = `famId = @request.auth.famId && @request.auth.role = 'parent'`. Re-runs are idempotent.
|
||
- **PB relation quirk:** PB forbids changing a relation's target collection in place (`validation_field_relation_change`) — you must **drop the field and re-add it** targeting the new collection in two separate collection updates.
|
||
- **Child (member) auth:** children are `users` records with `role='child'`, PB `username = {famSlug}:{handle}` (composite, globally unique), `name` = raw display name. Server derives the PB password = `MEMBER_SECRET + famSlug + handle`; the join gate is a 20-min OTP in `user_configs`, then `authWithPassword`. Children now hold a `pb_token` cookie (previously a `device_token` cookie with no session). `SessionUser` gained `username` (set in `hooks.server.ts`, stores `handleOf(record.username)`); the kanban child redirect compares `session.username`, not `session.name`.
|
||
- **Cookie httpOnly:** `pb_token` is now `httpOnly:true`. The browser PB SDK is seeded from `page.data.pbToken` via `initPb(token)` (layout onMount) — **not** from `document.cookie` (the client can no longer read it). Logout is server-side only. Note: the JWT is still shipped to the client in SSR HTML via the `pbToken` prop.
|
||
- **Typecheck baselines:** frontend `svelte-check` = 20 pre-existing canary errors (chat `json(status)` ResponseInit, `$types` Action/SubmitFunction, qrcode decl, vite.config, RewardType/Frequency casts, implicitly-any); proxy `tsc --noEmit` = pre-existing record-typing + implicit-any errors. No new errors in edited files.
|
||
- **`crypto.randomUUID()` unavailable over plain HTTP** (non-secure context) → added `genClientId()` fallback (randomUUID if available, else `Date.now().toString(36)+random`) in `chat.svelte.ts`.
|
||
- **Shared slugify util:** `shared/slugify.ts` (`@shared/slugify` alias) — used by proxy signup + fam rename, frontend signup + settings `renameFam`, and `member-otp.createChild` (child username + password gen). Removed the 3 local duplicate `slugify` helpers.
|
||
- **Settings UI:** CardGrid/Card are now responsive (media queries + `--grid-cols`/`--card-cols`; Cards use `container-type: inline-size`). Members card split into two columns: add-child form | member list (space-between rows, larger 22px colour circle, "Preview" CTA → `/{famSlug}/{m.username}`, Remove). Family Name card gained an explainer + mono `/{fam.slug}` slug line.
|
||
- **Hono audit:** the proxy is the live data layer — admin CRUD/reads via `hono.admin.*` (kanban load, bonuses ~17 calls, ledger 6, preferences 2, fam dash 4, settings `complete-week`/`debug/generate-data`), member actions via `memberApi.*` (toggleCompletion/claimReward/payday) + direct `/api` fetches (chores assigned-chores, kanban `/api/members/me`). **Not implemented:** `/api/weekly-cron` CRON, Stripe (`create-checkout` + webhook), WhatsApp — weekly settlement is manual via `complete-week`/`simulateEow`. Chat endpoints exist in the proxy but the frontend talks to PB directly.
|
||
|
||
### 2026-08-15 — Signup: multi-step flow restored + family-creation bug fixed
|
||
|
||
- **Bug (blocker):** new family creation failed with PB `{"username":{"code":"validation_required","message":"Cannot be blank."}}` — the `users.create` in `/signup` omitted the auth `username` field (PB 0.39 requires it). Reproduced directly against PB: create WITHOUT `username` → `validation_required`; WITH `username` → succeeds.
|
||
- **Fix:** `signup/+page.server.ts` now includes `username` on the parent `users` create.
|
||
- **Username convention (composite + handle):** PB `users.username` is the composite `{famSlug}:{handle}` for BOTH parents and children — globally unique (PB auth-identity needs a single-column unique index) even though the URL segment is per-family. `handle(name)` = lowercase, strips all non-`[a-z0-9]` (`"Jakey Boy"` → `jakeyboy`); `slugify()` (hyphenated) is kept only for fam slugs. URL segment = `handleOf(username)` (part after the last `:`) → `/{famSlug}/{handle}`. `name` keeps the raw display name, read from DB via `authRefresh` (not plucked into the cookie). Parent's handle captured at signup step 1 (`yourName`) → `username = famUsername(famSlug, handle(yourName))`; parents authenticate email+password and land on the fam dashboard `/{famSlug}` (not username-routed). Children authenticate via OTP → `authWithPassword(famUsername(...), derivePassword(famSlug, handle))`. Redirects in `login/+page.server.ts`, `[fam]/[username]/+page.server.ts` (parent + child branches) and `preferences/+page.server.ts` use `session.username` (the handle). Member-list URLs in `settings`, `[fam]/+page.svelte`, `[fam]/[username]/+page.svelte` build `/{famSlug}/{handleOf(m.username)}`. `handle`/`handleOf`/`famUsername` live in `shared/slugify.ts` (`@shared/slugify`).
|
||
- **Restored intended multi-step signup** (from the guide, adapted to current OTP model): `/signup` steps — (1) `?/signup` familyName/yourName/email/password → create fam + parent (name=yourName, username=famUsername(famSlug, handle(yourName))) + settings, set `pb_token`; (2) `?/child` optional child → `issueAccess` returns `{ code, joinUrl }`; (3) show OTP join code + "Go to dashboard" link. Uses named actions + `use:enhance` (callback typed `any` to avoid the pre-existing canary `$types` SubmitFunction error).
|
||
- **Typecheck:** frontend `svelte-check` stays at 20 pre-existing errors (no new in edited files).
|
||
|
||
### 2026-08-21 — Stripe embedded checkout live + access-code gating (`fams.paymentMode`)
|
||
|
||
- **Embedded Checkout fixes** (`frontend/src/lib/server/stripe.ts`): `ui_mode: 'embedded'` → `'embedded_page'` (Stripe deprecated `'embedded'`); removed `customer_creation: 'always'` — only valid in `payment` mode; subscription mode auto-creates the customer from `customer_email`. Client side already used `createEmbeddedCheckoutPage({ clientSecret })`.
|
||
- **Secure-context gotcha:** embedded Checkout requires HTTPS or localhost. Dev host is reached over Tailscale IP via plain HTTP → checkout hangs silently (the `muid/guid/sid` JSON from `m.stripe.com` is Radar device fingerprinting, not an error; Stripe CLI websocket errors are benign). Fix: SSH port-forward `ssh -L 2080:localhost:2080` and use `http://localhost:2080`. Webhook listener is now a root script: `pnpm stripe:listen` (= `stripe listen -e customer.subscription.updated,customer.subscription.deleted,checkout.session.completed --forward-to http://127.0.0.1:2080/account/webhook`).
|
||
- **Gating model:** the platform is gated. `fams.paymentMode` = `none | code | sub | canceled`; `fams.active` (bool) is the derived "usable now" flag, re-persisted by `ensureFamAccess()` when it drifts. New superuser-only `accesscodes` collection (all rules null like `otp`, so it lives in `migrate.ts` not `SCHEMA_PLAN`): `value` (unique, required), `name`, `duration` (months from entry date; 0=continuous), `expiry` (months after the code's own `createdAt`; 0=never), `active` failsafe, `createdAt`. Idempotently seeded with `dev123` / developer / 0 / 0.
|
||
- **Core module** `frontend/src/lib/server/access.ts`: `addMonthsUTC`, `codeIsValid`, `computeFamAccess` (mode → `{disabled, reason}`; reasons `no_access|code_expired|code_disabled|subscription_inactive|canceled`), `ensureFamAccess(famId)` (reads fam+code, persists drifted `active`, returns `{fam, access}`), `applyAccessCode(famId, value)` (sets mode=code + accessCodeId + accessCodeEnteredAt). Wired into `[fam]/+layout.server.ts` load → `data.famAccess` (both roles).
|
||
- **UI gating:** `[fam]/+layout.svelte` blurs `.page-content.locked` behind a non-blocking overlay card + admin TopNav announcement (sidebar/chat stay usable). Member kanban gate is **frontend-only by decision**: `[fam]/[username]/+page.svelte` derives `accessDisabled` from `page.data.famAccess?.disabled`, early-returns in `toggle()`, and renders three empty locked columns instead of the board. Signup takes an optional code (blank → gated fam; invalid → 400); settings has an Access card (`?/applyCode`). Webhooks maintain `paymentMode`: checkout completed / subscription sync → `sub`; subscription deleted → `canceled`.
|
||
- **Bug found while verifying:** the live `fams` collection was missing the `active` bool entirely (schema.ts declared it; this PB predated it) → `active` writes were silently dropped. Fixed by adding it to `ensureFamFields()` (idempotent; runs outside `ensureSchema`'s early-return alongside `ensureAccessCodes`) and patching the live collection. Verified end-to-end against PB: fam with valid `dev123` → `active=true`; fam with empty mode → `active=false` (gated).
|
||
- **PB curl gotcha:** single-record endpoints are `/api/collections/{name}/records/{id}` — omitting `/records/` returns PB's `"File not found."` 404 which masquerades as a missing record. The JS SDK always builds the correct path (an earlier "fams by-id 404" scare was a bad curl URL, not an app bug).
|
||
|
||
### 2026-08-22 — Routes reshuffle: `[famSlug]`→`[fam]` merge, `/pricing` public, signup wizard with inline checkout
|
||
|
||
- **Join route merged:** `[famSlug]/join/{username}` → `[fam]/join/{username}` (same URL shape, single `fam` param). Fixed `params.famSlug`→`params.fam` in join page files.
|
||
- **Public pricing page:** `/subscriptions` → `/pricing` (untracked dir renamed). New `PricingPlans.svelte` component (reusable tier cards; props: `action`, `hideTrial`, `selected`, `error`, `onsubmit` handler). `/pricing` is public: logged-out "Choose monthly" → redirect `/signup?plan=monthly`; logged-in → existing embedded checkout.
|
||
- **Signup wizard rewritten** as state machine (`fam → child → code → plan → done`):
|
||
- Step 1 (fam): family + parent creation (access code field REMOVED from here)
|
||
- Step 2 (child): add child or skip (unchanged)
|
||
- Step 3 (code): "Have an access code?" Apply (→ done) or Skip (→ plan)
|
||
- Step 4 (plan): `PricingPlans` embedded (`hideTrial=true`); selecting mounts embedded checkout INLINE (user authenticated); `?plan=X` from /pricing pre-highlights tier
|
||
- Step 5 (done): "Go to dashboard" — webhook flips `paymentMode=sub`, overlay lifts
|
||
- Server actions: `signup` (no code), `child` (unchanged), `access` (reuses `applyAccessCode`), `choose` (embedded checkout session)
|
||
- **Webhook moved** to `/api/webhooks/stripe` (machine-to-machine endpoint belongs in `/api/*` namespace). `pnpm stripe:listen` forward URL updated.
|
||
- **Links updated:** account "Change plan", settings "Plans", `stripe.ts` cancel_url → `/pricing`.
|
||
- **Docs updated:** AGENTS.md routes, ARCHITECTURE.md (routes, Stripe flow, architecture diagram, project structure), MEMORY.md this entry.
|
||
|
||
### 2026-08-21 — Platform feature flags (`platform` collection) + debug-gated revoke CTA
|
||
|
||
- **`fams.featureFlags` deprecated** (removed from SCHEMA_PLAN, `Fam` type, live PB; field dropped). Replaced by a global **`platform`** collection: single record `label='global'`, json `flags`. Rules: list/view = `""` (public read — the one rule shape `col()` CAN express), create/update/delete = null (superuser-only) → created in `migrate.ts` (`ensurePlatform` + idempotent `seedPlatform`, like otp/accesscodes).
|
||
- **Public load:** new root `frontend/src/routes/+layout.server.ts` exposes `page.data.platformFlags` on every page via `getPlatformFlags()` (`lib/server/platform.ts`, 10s TTL cache; `setPlatformFlag` for superuser writes).
|
||
- **`debug` flag gates dev-only UI**: settings "Revoke code" CTA (`?/revokeCode`) — clears an applied code (paymentMode→none, accessCodeId/EnteredAt→'', active=false, fam re-gates). Server action checks the flag itself (hidden CTA is not the boundary). Settings' old per-fam `featureFlags.debugMode` Debug Tools card now keys off `page.data.platformFlags.debug`.
|
||
- **`/admin` Platform Flags card** replaces the per-fam Debug column: `?/togglePlatformFlag` toggles any flag on the global record. Dev PB seeded with `debug: true`.
|
||
- Also: `[fam]/+layout.svelte` exempts `/settings` from the paused blur overlay (admins can apply a code while gated) and `disabled`/`accessReason` are `$derived` so applying/revoking updates the overlay without a refresh.
|
||
|
||
### 2026-08-22 — Settings reorg: Accordion groups, paymentMode-only billing, notices system
|
||
|
||
- **Settings grouped into 4 Accordions** (Family / App / Invites / Billing). `Accordion.svelte` rewritten as a styled snippet wrapper + new self-contained `AccordionItem` (own open state, `$bindable`, `{@render children()}`) — no items-array API.
|
||
- **Gating model simplified (user decision):** `fams.paymentMode` alone drives the FE (`none` = gated/paused; `code` valid = active; `sub` follows webhooks; `canceled` = gated). No `paused` field added; the local pause toggle was removed entirely. `fams.active` remains an internal derived flag maintained by `ensureFamAccess`/webhooks only.
|
||
- **Access card:** shows countdown from `accessCodeEnteredAt` + code `duration` months (days when <1 month, "never expires" when duration=0) — settings load now fetches the `accesscodes` record (`data.accessCode`). Once a code is applied the input/Apply are hidden and **Revoke is always visible** (debug-flag requirement dropped); revoke just sets `paymentMode:'none'` + clears code fields (fam-scoped only — global code management is a platform-admin concern).
|
||
- **Billing card** replaces `/account` (route deleted): sub → Change plan (/pricing) + Open billing portal (Stripe Customer Portal; dummy mode opens returned URL); code → Switch to subscription; none/canceled → Choose plan. Portal + checkout both return to `/{fam}?checkout=return`.
|
||
- **Checkout-return welcome notice:** `[fam]/+page.svelte` `$effect` watches `?checkout=return` → fires a success notice via the new **notices store** (`lib/stores/notices.ts`: typed add/success/info/warning/error + auto-dismiss helper) rendered by global `<NoticeDialog />` in the root layout; query param scrubbed via `history.replaceState` so refresh doesn't re-fire.
|
||
- Gotchas fixed along the way: duplicate NoticeDialog export; Svelte 5 forbids `class:` directives on components unless declared (Card got `selected` prop instead); second `<script>` block in a component is invalid.
|
||
|
||
### 2026-08-22 — famSlug single source of truth + notices store to runes
|
||
|
||
- **famSlug convention:** the URL param surfaced by `[fam]/+layout.server.ts` as top-level `data.famSlug` is canonical. Client code reads `page.data.famSlug` (fallback `?? page.params.fam` acceptable); server loads/actions under `[fam]` read `event.params.fam`. **Never copy it into local `$state`** — settings had a frozen-snapshot bug doing exactly that (now `$derived(page.data.famSlug ...)`). Nested `session.famSlug` removed (no consumers). Only exception with no URL param: signup `child` action resolves via DB (`fam?.slug || famId`) with a comment.
|
||
- Sweep results: removed dead/mislabeled `const famId = $derived(page.params.fam)` in bonuses page; zero `params.famSlug` references remain post `[famSlug]→[fam]` merge.
|
||
- **Notices store converted to Svelte 5 runes**: `lib/stores/notices.svelte.ts` (class with `$state<Notice[]>` list, add/remove/clear/success/info/warning/error + `addAutoDismissNotice`). Consumers: `notices.list` in `NoticeDialog.svelte`; no more svelte-store `writable`/`$notices` auto-subscription.
|
||
|
||
### 2026-08-22 — famSlug single source of truth + docs Hono purge
|
||
|
||
- **famSlug convention:** `[fam]/+layout.server.ts` returns top-level `data.famSlug` (from the URL param) — canonical. Client: `page.data.famSlug`; server under `[fam]`: `event.params.fam`. Never copy into local `$state` (settings had that frozen-snapshot bug). Nested `session.famSlug` removed; signup `child` action is the only DB-fallback case. Fixed platform-admin links pointing at nonexistent `/[slug]/admin`.
|
||
- **Docs:** purged all stale Hono-proxy references from AGENTS.md + ARCHITECTURE.md (proxy deleted 2026-08-17); data-flow sections now describe SvelteKit services/`/api/*` routes. Remaining "Hono" mentions are struck-through historical build phases.
|
||
|
||
### 2026-08-22 — Trial codes in PB, pause=cancel decision, settings reorder
|
||
|
||
- **"Pause" = cancel (decision):** no separate pause concept. Pausing a plan means cancelling the card subscription via the billing portal; data is kept, resubscribing restores access (`paymentMode` webhook-driven). Copy lives in settings Account card.
|
||
- **Trial codes now PB-backed:** `accesscodes.trialDays` (number). `resolveTrialDays()` (`stripe.ts`) is async — queries `accesscodes` for an active record with `value` match and `trialDays > 0`; static `TRIAL_CODES` map deleted. Seeded: `FAM3MONTHS` = 90 days. `ensureAccessCodeFields()` hardens existing installs; seeds unified in `seedAccessCodes()`.
|
||
- **Settings accordion order:** Family (name/payday/**seasons**, opens by default via `<AccordionItem open>`) → Invites → **Account** (Access + Subscription) → App last.
|
||
- **`clearLegacyCookies(cookies)`** added to `$lib/server/session.ts`; auth/join/logout use it instead of inline `device_token` deletes.
|
||
|
||
### 2026-08-31 — All-time earnings + weekly trend chart (family root), lifetime wallet (member)
|
||
|
||
- **New server stats service** `frontend/src/lib/server/services/stats.ts` (`familyStats(pb, famId)`, exposed as `s.stats.family(famId)`): scans full-history `completions` + `rewards` once, filtered/summed **on the server**, returns fixed-size `{ allTimePts, allTimeCash, allTimeChores, series }` (per-member weekly buckets `{weekStart, points, cash, chores}`). Server-side aggregation keeps the client payload constant-size regardless of history depth — this is the chosen scaling win for all-time totals + the retrospective graph.
|
||
- **Totals definition (matches the app's own accounting, no double count):** lifetime points = points-type completions' chore values + **claimed** points rewards; lifetime cash = money-type completions' chore values + **claimed** cash rewards; chores = count of all completions. Unclaimed/requested rewards stay out of totals (they're the "to chase" list).
|
||
- **Reading `weekly_history` NOT needed** — totals derive from live `completions`+`rewards` (both have `listRule: ""` in SCHEMA_PLAN = open to any authenticated session, which is why parent/child token reads already work today).
|
||
- **Member wallet** (`[fam]/[username]/+page.svelte`): the existing `allTimeCash`/`allTimePoints` deriveds now include chore completion earnings (previously claimed-rewards only). Wallet UI restyled: big lifetime cells (cash "earned all time" + points "accrued") on top, then a "To collect from parent" divider + the existing pendingRewards list (unclaimed/requested/payday-locked) so members still see what to chase.
|
||
- **Family root** (`[fam]/+page.svelte` + `+page.server.ts`): load now fetches `familyStats` (+ drops the removed templates). ViewHeader gained an optional default slot (`children?: Snippet`); the fam hero renders large all-time points | cash inside the header. Chores card shows "this week | total all-time" with `justify-content: space-between`. Templates card removed. Chart.js line graph "Over time" plots per-member lines with a Points/Cash/Chores tab; window starts at the current month and expands a month at a time up to 3 months based on data span (≤31d→1, ≤62d→2, else 3).
|
||
- **Typecheck/build:** still 6 pre-existing canary errors only (none in edited files); `pnpm build` (adapter-node) clean. New code is picked up by HMR; no schema/migration change so no restart required.
|
||
|
||
### 2026-08-31 — Bonus progress window: `completeBy` + `startDate` implemented
|
||
|
||
- **Problem**: a standalone cash bonus (core reward with a points threshold) displayed progress differently on the child dashboard (current week → "0/500") vs the admin dashboard (cumulative since records began). Both were "correct" because `bonus_configs` had no way to scope tracking — with no `period` set, progress()/evaluateFam totalled *all* completions, and the child dashboard forced `cfg.period || 'weekly'`.
|
||
- **Fix**: added to `bonus_configs` (schema + `ensureBonusFields` idempotent field-add in migrate.ts, so existing installs upgrade without wiping): `completeBy` (select `unlimited|week|custom`), `startDate` (text), `completeByDate` (text). New shared helpers in `shared/timezone.ts`: `bonusWindow(cfg, payday, tz)` + `completionInWindow(c, {from,to})` ('' = unbounded side).
|
||
- **Window semantics** (unified across server `progress()`/`evaluateFam()` and the child `thresholdGoals`): recurring configs (period set) keep their period window; standalone configs use `completeBy`:
|
||
- `unlimited` (default) → `[startDate, ∞]` cumulative
|
||
- `week` → current week `[weekStart, weekEnd]`
|
||
- `custom` → `[startDate, completeByDate]`
|
||
- No `startDate`/`completeBy` (legacy) → unbounded both sides (== the pre-fix admin behaviour, so existing cash bonuses stay correct).
|
||
- **UI**: rewards modal gained a "Progress counts" group (shown when no period / not manual): `completeBy` radios (Unlimited | Until a date) + optional `completeByDate` date input + "Progress starts on" `startDate` date input. Creating from a template's `startMode` (Today/Next week) now sets `startDate` (Today = fam-tz today; Next week = +7 days). `openEditConfig`/`openCreateFromTemplate` default `startDate` to today, so saving an existing cash bonus re-scopes it to count from today (progress since the reward begins), not since records started.
|
||
- **Server actions** (`rewards/+page.server.ts`): `createConfig`/`updateConfig`/`createFromTemplate` now persist `completeBy`/`startDate`/`completeByDate`.
|
||
- **Typecheck/build**: `svelte-check` still at the 6 pre-existing canary errors (chores RewardType/Frequency, qrcode decl, settings unknown→string) — none in edited files; `pnpm build` (adapter-node) clean.
|
||
- **Ops note**: the schema fields are added to live PB by `ensureBonusFields()` on next `migrateOnBoot` (dev server restart). A restart of the dev frontend is needed to apply the migration + load the new code.
|
||
|
||
### 2026-08-22 — Graceful post-checkout activation (webhook-lag UX)
|
||
|
||
- `[fam]/+layout.svelte` owns the `?checkout=return` flow (moved out of the fam page). On landing: if unlocked → welcome notice. If still gated (webhook lag) → `activating` state: paused overlay swaps to a spinner card ("Activating your subscription…"), TopNav paused announcement suppressed, and `invalidateAll()` revalidates every 1.5s (max 12 tries). The `$effect` watching `activating && !disabled` cancels polling and fires "Subscription active!" the instant the gate lifts; exhaustion degrades to a refresh-hint warning.
|
||
- Mechanics: `pollToken` guards against stale loops; `history.replaceState` scrubs the query cosmetically + `returnHandled` flag prevents double-handling. Webhook remains the sole source of truth for `paymentMode`/`active`.
|
||
- **Upgrade (same day): activation is event-driven, not polled.** `startActivating` subscribes the browser PB client to its own `fams` record (`pb.collection('fams').subscribe(famId)` — allowed by viewRule `id = @request.auth.famId`). Webhook (superuser) writes → PB SSE push → single `invalidateAll()`; unlock `$effect` stops the subscription + fires success. 20s timer kept purely as a degrade-gracefully fallback. Rejected: onComplete-as-source-of-truth (untrusted); optional future hardening = server-side session verification on return.
|
||
|
||
### 2026-08-22 — Platform admin: access-code management + richer stats
|
||
|
||
- `/admin` extended (same route/embedded login — env-var check + `platform_session` cookie, no PB auth or hooks involved):
|
||
- **Access Codes card**: issue codes via `?/createCode` — blank value auto-generates `XXXX-XXXX` (unambiguous charset); fields name/duration/expiry/trialDays (`trialDays > 0` = Stripe trial code). Table shows type badge, active/disabled, **used-by count** (from fams.accessCodeId map), copy-to-clipboard. `?/toggleCode` flips active; `?/deleteCode` **blocked while in use** (must disable).
|
||
- **Overview**: added chores completed (completions length), active subs (`paymentMode='sub'`), paused/gated (`!active || none/canceled`), active codes. Families table gained plan+paused badges.
|
||
- All actions guarded by `requirePlatform(cookies)`; data still via `pbAdmin` superuser facade.
|
||
- Note: `svelte-kit sync` needed after changing load return shapes or `$types` staleness doubles the error count.
|
||
- **/admin login pattern:** action sets `platform_session` cookie + returns `{success:true}`; the form's `use:enhance` callback flips a local `authed` view state — no redirect, no reliance on inline invalidation or fetch-time Set-Cookie behavior (which proved flaky in-browser despite curl proving both response paths carried it). Cookie still covers subsequent loads; load errors surface as `data.loadError` on the login card instead of silently masquerading as logged-out.
|
||
- **Platform-admin auth via hooks:** `hooks.server.ts` resolves `locals.platformAdmin` from the `platform_session` cookie (=== 'authenticated') on every request; `/admin` load/actions consume `event.locals.platformAdmin` (`requirePlatform(event)`) instead of raw cookie reads. Same central pattern as `pb_token` → `locals.user`.
|
||
- **`isDummyStripe` removed:** real test keys made every dummy branch dead code — and the webhook's `|| !signature` fallback accepted UNSIGNED events (forgeable access grants). Signature is now mandatory (400 without it); settings' simulated endSubscription/portal branches deleted. Dev verification stays via stripe-cli signed events (`pnpm stripe:listen`).
|
||
- **Platform-admin auth hardened (supersedes the constant-cookie version):** `/admin` login now does a real `_superusers.authWithPassword` via PB; the minted superuser JWT goes in `platform_session` (`setPlatformSession` in session.ts). `hooks.server.ts` deviates on `/admin`: verifies the token with `_superusers.authRefresh` → `locals.platformAdmin` (forged values fail authRefresh and get cleared); fam-user pb_token flow skipped on that route. FINAL login shape (user-amended, working): action returns `{success:true}` (no redirect); form's enhance callback does `goto('/admin', { invalidateAll: true })` on success — forcing the load re-run with the fresh cookie; view branches on `data.authenticated`. Verified: real token renders dashboard, forged cookie gets login.
|
||
- **use:enhance redirect gotcha (session-wide lesson):** action-thrown redirects surface as `result.type === 'redirect'` in the RESOLVE callback — handlers checking only `'success'` silently drop them (bit /admin login, pricing choose, and settings billingPortal). Shared fix: `lib/forms.ts` → `handleResult(handler?)` factory follows redirects via `goto`, delegates the rest to the handler or default `update()`. Use it for any form whose action can throw a redirect. Also: enhance is two-stage — `{result}` only exists in the resolve fn, not the submit params (was mis-handled in pricing/signup handlers).
|