feat: add dev startup script, fix push notifications, and scope test sends to device

- pnpm dev:local/dev:reset: orchestrate DB container, migrations, seed, and Next.js dev server in one command; Caddy snippet + docs for HTTPS via dev.ginnoir.com - Fix dev login on HTTPS: set both authjs.session-token and __Secure-authjs.session-token so Auth.js finds the session regardless of cookie name resolution - Suppress hydration mismatch on <html> caused by pre-paint script changing data-nav before React hydrates - VAPID startup warning if keys not configured; remove dead NEXT_PUBLIC_VAPID_PUBLIC_KEY var - PushOptIn: hydrate subscription state on mount; reuse existing subscription on iOS to avoid redundant prompts - sendPushToEndpoint: new function to send to a single device endpoint - sendTestNotification: scoped to the calling device's endpoint (ownership-verified) instead of all user subscriptions
2026-06-01 17:45:20 -05:00
parent 9612a54e52
commit 19308be768
14 changed files with 334 additions and 26 deletions
@@ -34,20 +34,69 @@ This note tracks the development-only work added to make the app easy to run and

 ## Current Local Run Procedure

+One command starts the database, runs migrations, seeds, and launches the dev server:
+
 ```powershell
-docker compose -f docker-compose.dev.yaml up -d
-pnpm db:migrate
-pnpm db:seed
-pnpm dev
+pnpm dev:local
 ```

-Then open:
+The script prints three URLs at startup:

-```text
-http://127.0.0.1:3000/login
+| URL | Use for |
+|-----|---------|
+| `http://localhost:3000` | Browser on this machine |
+| `http://192.168.1.74:3000` | Phone on the same WiFi (general UI testing) |
+| `https://dev.ginnoir.com` | Push notifications + PWA install (needs Caddy — see below) |
+
+Then open `/login` and click **Dev login**.
+
+### HMR and restarts
+
+`next dev` has hot module replacement — most `.ts`/`.tsx` changes apply instantly without a restart.
+
+A full restart (`Ctrl+C` → `pnpm dev:local`) is needed for:
+- `.env` changes
+- `next.config.ts` changes
+
+### Clean slate
+
+To delete all local data and start fresh (e.g. after a destructive schema change):
+
+```powershell
+pnpm dev:reset
 ```

-Click **Dev login**.
+### HTTPS for push notification and PWA testing (one-time setup)
+
+Service workers and Web Push require HTTPS. The plain LAN address won't work for these.
+Route through the existing Caddy server on the home server instead — no extra tooling needed.
+
+**Step 1 — DHCP reservation**
+
+Set a reservation on the router so the dev machine always gets `192.168.1.74`.
+
+**Step 2 — DNS record**
+
+Add a `dev.ginnoir.com` A record pointing to the same public IP as `fam.ginnoir.com`.
+
+**Step 3 — Windows Firewall**
+
+Allow inbound TCP 3000 on the dev machine (run once in an elevated PowerShell):
+
+```powershell
+New-NetFirewallRule -DisplayName "famapp dev" -Direction Inbound `
+  -Protocol TCP -LocalPort 3000 -Action Allow
+```
+
+**Step 4 — Caddy snippet**
+
+Paste `deploy/Caddyfile.dev.snippet` into the home server Caddyfile and reload:
+
+```bash
+caddy reload --config /path/to/Caddyfile
+```
+
+After this, `https://dev.ginnoir.com` proxies to the dev machine with a real Let's Encrypt cert.

 ## Current Local E2E Procedure