Infra: split dev and production (releases, services, deploy script)

- Production now runs from ~/freezmo-prod/current (release symlink) as a
  standalone server on :3207; releases are exported by scripts/deploy.sh,
  built and e2e-verified on a temp port, switched atomically, health-
  checked via the new /api/healthz (commit + build time) and rolled back
  automatically on failure. Last 5 releases kept; scripts/rollback.sh for
  manual rollback. Shared env + data live in ~/freezmo-prod/shared/ and
  are symlinked into every release (existing sync/push data migrated and
  verified identical).
- Dev runs from ~/freezmo via freezmo-dev.service: next dev on :3217
  (LAN only), its own build folder (.next-dev via NEXT_DIST_DIR), its own
  data (~/freezmo/.freezmo-dev), DEV badge, dev favicon/theme colour,
  "Freezmo Dev" PWA identity and never the production service worker.
- /api/healthz + the Settings Details version row (short commit + build
  time). output: standalone in next.config (next start still works).
- AGENTS.md documents the workflow rules: only dev updates during a task,
  temporary dirs/ports for test builds, and deploy-at-the-end as the only
  production path. README gains an Environments and deploy section.
- Fix found by the rehearsal: lib/dev-mode.ts must not be a client module
  (a server component importing a constant from a "use client" module
  gets a truthy proxy, which baked dev metadata into production builds).
- SW -> freezmo-v34.
This commit is contained in:
Martin Dvořák 2026-10-11 19:25:29 +00:00
commit 3f52ab47c2
22 changed files with 665 additions and 35 deletions

56
AGENTS.md Normal file
View file

@ -0,0 +1,56 @@
# AGENTS.md — working rules for this repo
Freezmo has two environments. Every session — human or agent — follows these
rules. They are not optional: production is the app the user actually uses.
## Environments
| | Dev (this working tree) | Production |
| --- | --- | --- |
| Path | `~/freezmo` (where you edit) | `~/freezmo-prod/current` (release symlink) |
| Service | `freezmo-dev.service` | `freezmo.service` |
| Port | **3217** (`http://<lan-ip>:3217`, LAN only) | **3207** + the public URL |
| Build folder | `.next-dev` (hot reload) | `.next/standalone` inside the release |
| Data | `~/freezmo/.freezmo-dev/` | `~/freezmo-prod/shared/freezmo/` |
| Env | `~/freezmo/.env.local` | `~/freezmo-prod/shared/env.local` |
| Identity | DEV badge, dev favicon/theme, "Freezmo Dev" PWA | normal |
Dev runs `next dev` with hot reload; **all live, real-time changes go there**.
Production only ever runs a pushed, verified commit deployed by
`scripts/deploy.sh` (releases under `~/freezmo-prod/releases/`, last 5 kept,
`scripts/rollback.sh` to go back).
## Rules
1. **During a task, only the dev instance updates.** Never restart or rebuild
production mid-task; production changes only through `scripts/deploy.sh` at
the very end.
2. **Never build into a running instance's folder.** The dev service owns
`.next-dev`; `npm run build` (used by the test suites' spawned instances)
owns `.next`; a release build owns its own release directory. Any build or
test that needs a production build uses a temporary directory and port.
3. **At the end of a task**: run `npm run lint`, `npm run test:e2e` and
`npm run build`, bump the service-worker cache (`public/sw.js`), update the
README, commit, push to `main`, then run `scripts/deploy.sh`. Production
only ever runs a pushed, verified commit.
4. **`scripts/deploy.sh` is the only deploy path.** It refuses a dirty tree,
refuses commits that aren't on `origin/main`, runs lint + build + the full
e2e suite against the new release on a temporary port, switches the
`current` symlink atomically, health-checks `/api/healthz` for the new
commit and rolls back automatically on failure.
5. **The Ollama API key never leaves the browser.** It must never appear in
exports, sync payloads, share links, logs, URLs, `.env` files committed to
the repo, or release directories. Server data (sync blobs, push
subscriptions) lives only under `shared/`.
6. **Both languages, always.** Every user-facing string goes into
`lib/i18n-dict.ts` in **en and cs** (the i18n test enforces key parity).
7. **Phones are first-class**: ≤639px layouts, 44px touch targets, 16px
inputs, safe-area padding; verify at 360px and 390px as well as desktop.
8. **Versioned storage, never lose data.** Deck/homework/chat schemas are
validated with zod on read; backups and sync share the same payload schema.
9. **The test suites live in `tests/`** (`npm run test:e2e`, filterable:
`npm run test:e2e -- chat`). Add or extend a suite for every feature; a
green suite set is part of "done". Diagnostics that are not gates:
`tests/bubble-perf.mjs`, `tests/model-compare.mjs`.
10. **Keep the service worker honest**: bump `CACHE_VERSION` in `public/sw.js`
for every user-visible deploy (the deploy itself does not do this).