dvorakmortonxd/freezmo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
freezmo/AGENTS.md
Martin Dvorak 3f52ab47c2 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.
2026-10-11 19:25:29 +00:00

3.2 KiB
Raw Blame History

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).