dckc
d0a9b899f2
- checklist: 1c (diigo-dump evolves into a bookmark cache) with its create-flow, id-wiring, and verification subgoals - notes: diigo-cache replaces diigo-dump in What-we-built - AGENTS: no worker secret since 1c; durable state — be LOUD and conservative about breaking changes to stored DB state; pointer to the workspace skills for commit trailers Generated-by: opencode (GLM) Generated-by: Claude Opus 5.5
50 lines
2.3 KiB
Markdown
50 lines
2.3 KiB
Markdown
# capsite working rules
|
|
|
|
Applies to AI agents working in `capsite/` (goal tree + how-to-run:
|
|
[capsite-checklist.md](capsite-checklist.md); background:
|
|
[the capsite notes](capsite-notes.md); workspace-wide policy:
|
|
[AGENTS.md](../AGENTS.md) — points to the workspace skills, incl. commit trailers).
|
|
|
|
## Dev servers are the user's job
|
|
|
|
The assistant never starts, stops, or restarts long-running dev servers
|
|
(`wrangler dev`, `pnpm dev`/`astro dev`). The user runs them and owns the
|
|
terminals; the assistant observes via `.tmp/capsite.script` (the `script`
|
|
capture; use `watchme`). One-shot codegen (`wrangler types`), linters,
|
|
typechecks, and tests are fine.
|
|
|
|
## Durable state: be LOUD and conservative about breaking changes
|
|
|
|
Persistence is a big deal here: DO ids (cache ids, webapp ids, public
|
|
ids) are headed toward representing real-world assets. A change that
|
|
leaves existing stored state unreadable, unreachable, or differently
|
|
interpreted is a **breaking change**, even in dev.
|
|
|
|
- **Before** making it, say so, prominently: what stored state breaks,
|
|
why, and the options (migrate, stay compatible, or reset). Get the
|
|
user's go-ahead; don't discover it after the fact.
|
|
- Prefer compatibility: read old shapes, add fields rather than repurpose
|
|
them, migrate in place (schema steps like `SCHEMA_V1` → `V2`).
|
|
- No silent resets. "Wipe `.wrangler/state`" is a last resort the user
|
|
chooses, never the default advice.
|
|
- Cover it with a test: old-shape state in, current code reads it.
|
|
|
|
(Prompted 2026-10-07: making `PublicCache` fetch through its own wiring
|
|
left public caches created by the earlier `ingest` code unwired — a 502,
|
|
and no way back through publish.)
|
|
|
|
## Secrets discipline
|
|
|
|
Worker secrets never in source or wrangler config. `.dev.vars` (gitignored)
|
|
locally; `wrangler secret put` deployed. Since the 1c cache evolution, no
|
|
worker secret is needed at all: the cookie lives only in the webapp DO's
|
|
storage; the webapp-instance id rides the cache DO's wiring; the cache id
|
|
is a user-held capability (password manager / per-POST paste). Error
|
|
messages must not contain header or param values (they cross RPC as
|
|
exceptions and land in logs); URLs appear query-stripped.
|
|
|
|
## Keep config types generated
|
|
|
|
Run `wrangler types` after any wrangler.jsonc change
|
|
(`worker-configuration.d.ts` is generated, gitignored; hand-rolled
|
|
`cloudflare:workers` shims drift and gave red squiggles). |