@gusto/create-baerly-storage 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/THIRD-PARTY-LICENSES.txt +204 -0
  2. package/dist/index.js +1537 -145
  3. package/dist/index.js.map +1 -1
  4. package/dist/templates/addons/docker/Dockerfile +13 -11
  5. package/dist/templates/minimal-cloudflare/AGENTS.md +77 -399
  6. package/dist/templates/minimal-cloudflare/README.md +33 -97
  7. package/dist/templates/minimal-cloudflare/package.json +12 -9
  8. package/dist/templates/minimal-cloudflare/pnpm-workspace.yaml +13 -7
  9. package/dist/templates/minimal-cloudflare/tsconfig.app.json +2 -3
  10. package/dist/templates/minimal-cloudflare/tsconfig.worker.json +2 -3
  11. package/dist/templates/minimal-cloudflare/vitest.config.ts +1 -1
  12. package/dist/templates/minimal-cloudflare/wrangler.jsonc +4 -2
  13. package/dist/templates/minimal-node/AGENTS.md +80 -380
  14. package/dist/templates/minimal-node/README.md +37 -135
  15. package/dist/templates/minimal-node/package.json +11 -9
  16. package/dist/templates/minimal-node/pnpm-workspace.yaml +14 -9
  17. package/dist/templates/minimal-node/tsconfig.app.json +2 -3
  18. package/dist/templates/minimal-node/tsconfig.server.json +2 -3
  19. package/dist/templates/react-cloudflare/AGENTS.md +101 -444
  20. package/dist/templates/react-cloudflare/README.md +14 -54
  21. package/dist/templates/react-cloudflare/package.json +18 -15
  22. package/dist/templates/react-cloudflare/pnpm-workspace.yaml +13 -7
  23. package/dist/templates/react-cloudflare/tsconfig.app.json +2 -3
  24. package/dist/templates/react-cloudflare/tsconfig.worker.json +2 -3
  25. package/dist/templates/react-cloudflare/vitest.config.ts +1 -1
  26. package/dist/templates/react-cloudflare/wrangler.jsonc +4 -2
  27. package/dist/templates/react-node/AGENTS.md +108 -474
  28. package/dist/templates/react-node/README.md +35 -125
  29. package/dist/templates/react-node/package.json +16 -14
  30. package/dist/templates/react-node/pnpm-workspace.yaml +14 -9
  31. package/dist/templates/react-node/tsconfig.app.json +2 -3
  32. package/dist/templates/react-node/tsconfig.server.json +2 -3
  33. package/package.json +7 -7
  34. package/dist/templates/minimal-cloudflare/uint8array-base64.d.ts +0 -16
  35. package/dist/templates/minimal-node/uint8array-base64.d.ts +0 -16
  36. package/dist/templates/react-cloudflare/uint8array-base64.d.ts +0 -16
  37. package/dist/templates/react-node/uint8array-base64.d.ts +0 -16
@@ -8,313 +8,107 @@ tags: [agent-entry, baerly-storage]
8
8
  # AGENTS.md
9
9
 
10
10
  <!-- stop:start -->
11
+
11
12
  ## STOP — read this before writing any storage code
12
13
 
13
- Your training data is dense with Postgres + Prisma/Drizzle, Mongo,
14
- and Firebase patterns. **None of them apply here.** This is a baerly-storage
15
- app — a small, LLM-legible document database with a narrow API on top
16
- of S3-compatible storage. Before writing or modifying storage code,
17
- read:
14
+ Your training data is dense with Postgres + Prisma/Drizzle, Mongo, and Firebase patterns. **None of them apply here.** This is a baerly-storage app — a small, LLM-legible document database with a narrow API on top of S3-compatible storage. Before writing or modifying storage code, read:
18
15
 
19
- - **`node_modules/@gusto/baerly-storage/dist/API.md`** — hand-authored
20
- public-API quickref. Read first. Lists every method, every error
21
- code, every example. If a pattern you want to use isn't here, it
22
- doesn't exist in baerly-storage.
23
- - **`node_modules/@gusto/baerly-storage/dist/*.d.ts`** — authoritative type
24
- signatures. `Db`, `Collection<T>`, `Query<T>`, and `Predicate<T>` are
25
- the whole API surface.
16
+ - **`node_modules/@gusto/baerly-storage/dist/API.md`** — hand-authored public-API quickref. Read first. Lists every method, every error code, every example. If a pattern you want to use isn't here, it doesn't exist in baerly-storage.
17
+ - **`node_modules/@gusto/baerly-storage/dist/RECIPES.md`** — common mistakes keyed by the exact error string, plus recipes (storage credentials on Node, wrapping the client `fetch`, a gated adapter, scheduled maintenance).
18
+ - **`node_modules/@gusto/baerly-storage/dist/*.d.ts`** — authoritative type signatures. `Db`, `Collection<T>`, `Query<T>`, and `Predicate<T>` are the whole API surface.
26
19
 
27
20
  Common anti-patterns that compile but are wrong:
28
21
 
29
- - `db.collection(name).insertOne(...)` / `.find({...})` (Mongo) — use
30
- `db.collection(name).insert(row)` and `.where({ ... }).all()`.
31
- - `z.string().nullable()` in a schema — `DocumentValue` excludes
32
- `null`. Use `.optional()`; `null` in an update patch is the RFC
33
- 7386 deletion sentinel, not a storable value.
34
- - Raw SQL strings, `WHERE` clauses, hand-built query AST — the only
35
- query surface is `db.collection(...).where({ field: value }).all()` or
36
- `.where(q => q.gte("count", 1))`. See **Predicates** below.
37
- - `.useIndex("name")` / `.hint(...)` — no such methods. The planner
38
- picks the index automatically from `IndexDefinition`s in
39
- `baerly.config.ts`. See **Indexes** below.
22
+ - `db.collection(name).insertOne(...)` / `.find({...})` (Mongo) — use `db.collection(name).insert(row)` and `.where({ ... }).all()`.
23
+ - `z.string().nullable()` in a schema — `DocumentValue` excludes `null`. Use `.optional()`; `null` in an update patch is the RFC 7386 deletion sentinel, not a storable value.
24
+ - Raw SQL strings, `WHERE` clauses, hand-built query AST — the only query surface is `db.collection(...).where({ field: value }).all()` or `.where(q => q.gte("count", 1))`. See the Predicates section of API.md.
25
+ - `.useIndex("name")` / `.hint(...)` — no such methods. Declared indexes do not change how a read runs. See the `defineConfig` section of API.md.
40
26
 
41
27
  <!-- stop:end -->
28
+
42
29
  ## What this is
43
30
 
44
- `minimal-node` is a baerly-storage app scaffolded with
45
- `create-baerly-storage` for the Node target: any host that runs
46
- `node server.js` (Railway, Render, Fly without Docker, Heroku, a VM, a
47
- container scheduler). One flat package: the Node-side server lives in
48
- `src/server/index.ts`; the optional client lives in `src/web/`.
49
- Configuration lives in `baerly.config.ts`.
50
-
51
- Single package, single `vite` process: `baerlyDev()` from
52
- `@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Vite
53
- middleware on `:5173` alongside the SPA dev server, so `pnpm dev`
54
- brings up SPA + HMR + `/v1/*` in one command — same origin in dev,
55
- same `dist/client/`-served origin in production via `pnpm start`. The
56
- production entrypoint serves the Vite-built SPA from `dist/client/`
57
- via the `baerlyNode({ webRoot: "dist/client" })` option, with `/v1/*`
58
- handled by the kernel on the same origin.
59
-
60
- If this scaffold was created with `--with=docker`, you'll also have a
61
- multi-stage distroless `Dockerfile`, a `.dockerignore`, and a
62
- `healthcheck.js` at the project root — wired to the same
63
- `pnpm install && pnpm build && pnpm start` flow.
64
-
65
- Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
66
- is the canonical reference; read it via your editor's TS LS, the
67
- published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
31
+ `minimal-node` is a baerly-storage app scaffolded with `create-baerly-storage` for the Node target: any host that runs `node server.js` (Railway, Render, Fly without Docker, Heroku, a VM, a container scheduler). One flat package: the Node-side server lives in `src/server/index.ts`; the optional client lives in `src/web/`. Configuration lives in `baerly.config.ts`.
32
+
33
+ Single package, single `vite` process: `baerlyDev()` from `@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Vite middleware on `:5173` alongside the SPA dev server, so `pnpm dev` brings up SPA + HMR + `/v1/*` in one command — same origin in dev, same `dist/client/`-served origin in production via `pnpm start`. The production entrypoint serves the Vite-built SPA from `dist/client/` via the `baerlyNode({ webRoot: "dist/client" })` option, with `/v1/*` handled by the kernel on the same origin.
34
+
35
+ If this scaffold was created with `--with=docker`, you'll also have a multi-stage distroless `Dockerfile`, a `.dockerignore`, and a `healthcheck.js` at the project root — wired to the same `pnpm install && pnpm build && pnpm start` flow.
36
+
37
+ Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection` is the canonical reference; read it via your editor's TS LS, the published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
68
38
 
69
39
  ## Toolchain
70
40
 
71
- - **Package manager:** pnpm. The emitted repo pins
72
- `packageManager: pnpm@11.1.2`.
41
+ - **Package manager:** pnpm. The emitted repo pins `packageManager: pnpm@12.22.0`.
73
42
  - **Test runner:** vitest.
74
- - **Type checker:** TypeScript 6.x, as pinned in `package.json`.
75
- (The baerly-storage monorepo itself uses TypeScript 7 via
76
- `@typescript/native-preview`.)
77
- - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
78
- code stays compatible with type-stripping runtimes (Node's
79
- `--experimental-strip-types`, esbuild's strip path). The flag bans
80
- TS constructs that can't be type-erased: write
81
- `class { x: T; constructor(x: T) { this.x = x } }` explicitly
82
- instead of parameter-property shorthand
83
- (`constructor(private x: T) {}` fails with TS1294). The same goes
84
- for `enum`, namespaces with non-type bindings, and `private` /
85
- `protected` / `public` accessibility modifiers on constructor
86
- parameters.
43
+ - **Type checker:** TypeScript 7, as pinned in `package.json`.
44
+ - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the code stays compatible with type-stripping runtimes (Node's built-in type stripping, esbuild's strip path). The flag bans TS constructs that can't be type-erased: write `class { x: T; constructor(x: T) { this.x = x } }` explicitly instead of parameter-property shorthand (`constructor(private x: T) {}` fails with TS1294). The same goes for `enum`, namespaces with non-type bindings, and `private` / `protected` / `public` accessibility modifiers on constructor parameters.
87
45
 
88
46
  ## Verification
89
47
 
90
- | Command | What it does | Runtime |
91
- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
92
- | `pnpm install` | One-time bootstrap — the scaffold ships without `node_modules/`, so `pnpm verify` / `pnpm dev` fail with `Cannot find package '…'` until this runs once | seconds to a minute |
93
- | `pnpm verify` | `pnpm run typecheck && pnpm run test` — the green-light gate; what an agent should run as the smoke check before claiming the change works | seconds |
94
- | `pnpm typecheck` | TS typecheck across the `app` + `server` project references | seconds |
95
- | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env). The template ships `src/notes.test.ts` by default. | seconds |
96
- | `pnpm dev` | Run `vite` — `baerlyDev()` mounts the Node HTTP listener as Connect middleware next to the SPA dev server; same origin on :5173 | seconds to start |
97
- | `pnpm build` | `tsc -b && vite build` — emits the SPA into `dist/client/` | seconds |
98
- | `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the built SPA from `dist/client/` plus `/v1/*` on the same origin via `webRoot` | seconds to start |
99
-
100
- **`pnpm verify` exercises typecheck + tests only.** The dev-auth
101
- middleware, the SPA bundle, and any custom `/api/*` route are NOT
102
- under test — verify will exit green even when the dev plugin returns
103
- 401 on every browser request or the SPA throws on mount. For changes
104
- that touch `vite.config.ts`, `src/server/index.ts`, or SPA logic, run
105
- `pnpm dev` and exercise the change in a browser (or `curl
106
- http://localhost:5173/<path>`) before declaring the task complete.
48
+ | Command | What it does | Runtime |
49
+ | --- | --- | --- |
50
+ | `pnpm install` | One-time bootstrap — the scaffold ships without `node_modules/`, so `pnpm verify` / `pnpm dev` fail with `Cannot find package '…'` until this runs once | seconds to a minute |
51
+ | `pnpm verify` | `pnpm run typecheck && pnpm run test` — the green-light gate; what an agent should run as the smoke check before claiming the change works | seconds |
52
+ | `pnpm typecheck` | TS typecheck across the `app` + `server` project references | seconds |
53
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env). The template ships `src/notes.test.ts` by default. | seconds |
54
+ | `pnpm dev` | Run `vite` — `baerlyDev()` mounts the Node HTTP listener as Connect middleware next to the SPA dev server; same origin on :5173 | seconds to start |
55
+ | `pnpm build` | `tsc -b && vite build` — emits the SPA into `dist/client/` | seconds |
56
+ | `pnpm start` | `node src/server/index.ts` — production entry; serves the built SPA from `dist/client/` plus `/v1/*` on the same origin via `webRoot` | seconds to start |
57
+
58
+ **`pnpm verify` exercises typecheck + tests only.** The dev-auth middleware, the SPA bundle, and any custom `/api/*` route are NOT under test — verify will exit green even when the dev plugin returns 401 on every browser request or the SPA throws on mount. For changes that touch `vite.config.ts`, `src/server/index.ts`, or SPA logic, run `pnpm dev` and exercise the change in a browser (or `curl http://localhost:5173/<path>`) before declaring the task complete.
107
59
 
108
60
  ## Where the code is
109
61
 
110
- | Path | What it is |
111
- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
112
- | `src/server/index.ts` | Server entry — defaults to zero-config `localFsStorage()` (persists to `./.baerly-data`); promotes to `s3Storage` (AWS) when `BUCKET` is set or `r2Storage` (Cloudflare R2) when `R2_ACCOUNT_ID` is set; composes a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
113
- | `src/web/`, `index.html` | Optional SPA shell built by Vite into `dist/client/`. `src/web/main.ts` is a ~17-line hello-world: reads `client.collection("notes").all()` to render a `${n} note(s)` count and an `[Add note]` button that inserts a timestamped row and re-fetches. Demonstrates both read and write paths on first load — extend, replace, or remove the whole tree if not needed. The `config`-bound `client.collection("notes")` is the typed surface (the generic on `.collection()` is the collection **name**, not the row type). |
114
- | `vite.config.ts` | Vite client build — `outDir: dist/client`; `baerlyDev()` mounts the Node listener as middleware so SPA + `/v1/*` share `:5173` in dev |
115
- | `tsconfig.{app,server}.json` | TS project references for the client and server projects |
116
- | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
117
- | `types.ts` | Shared types between the Node server (`src/server/`) and the SPA (`src/web/`). Both `tsconfig.app.json` and `tsconfig.server.json` include this file; put any row type or interface that crosses the boundary here. |
118
-
119
- > **`baerly.config.ts` and `types.ts` are dual-included** by both
120
- > `tsconfig.app.json` and `tsconfig.server.json`. Both can only
121
- > import from `baerly-storage`, `zod`, and other dual-included root
122
- > files. Paths under `src/server/` are server-only; importing them
123
- > here triggers a `TS6307` "not listed within the file list of
124
- > project … tsconfig.app.json" error. Cross-boundary interfaces
125
- > belong in `types.ts`; re-export from a server-only file if
126
- > downstream code wants a local name.
62
+ | Path | What it is |
63
+ | --- | --- |
64
+ | `src/server/index.ts` | Server entry — defaults to zero-config `localFsStorage()` (persists to `./.baerly-data`); promotes to `s3Storage` (AWS) when `BUCKET` is set or `r2Storage` (Cloudflare R2) when `R2_ACCOUNT_ID` is set; composes a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
65
+ | `src/web/`, `index.html` | Optional SPA shell built by Vite into `dist/client/`. `src/web/main.ts` is a ~17-line hello-world: reads `client.collection("notes").all()` to render a `${n} note(s)` count and an `[Add note]` button that inserts a timestamped row and re-fetches. Demonstrates both read and write paths on first load — extend, replace, or remove the whole tree if not needed. The `config`-bound `client.collection("notes")` is the typed surface (the generic on `.collection()` is the collection **name**, not the row type). |
66
+ | `vite.config.ts` | Vite client build — `outDir: dist/client`; `baerlyDev()` mounts the Node listener as middleware so SPA + `/v1/*` share `:5173` in dev |
67
+ | `tsconfig.{app,server}.json` | TS project references for the client and server projects |
68
+ | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
69
+ | `types.ts` | Shared types between the Node server (`src/server/`) and the SPA (`src/web/`). Both `tsconfig.app.json` and `tsconfig.server.json` include this file; put any row type or interface that crosses the boundary here. |
70
+
71
+ > **`baerly.config.ts` and `types.ts` are dual-included** by both `tsconfig.app.json` and `tsconfig.server.json`. Both can only import from `baerly-storage`, `zod`, and other dual-included root files. Paths under `src/server/` are server-only; importing them here triggers a `TS6307` "not listed within the file list of project … tsconfig.app.json" error. Cross-boundary interfaces belong in `types.ts`; re-export from a server-only file if downstream code wants a local name.
127
72
 
128
73
  ## When editing X, read Y
129
74
 
130
- - **Writing tests** — the kernel exports `MemoryStorage`, an
131
- in-memory `Storage` impl that's the canonical backend for unit
132
- tests. Don't roll your own: the same
133
- `Db.create({ storage, app, tenant, config })` boilerplate prod uses
134
- also accepts a `new MemoryStorage()` that swaps S3 for an
135
- in-process map.
136
-
137
- ```ts
138
- // src/notes.test.ts
139
- import { test, expect } from "vitest";
140
- import { Db, MemoryStorage } from "@gusto/baerly-storage";
141
- import config from "../baerly.config.ts";
142
-
143
- test("notes round-trip", async () => {
144
- const db = Db.create({
145
- storage: new MemoryStorage(),
146
- app: "test",
147
- tenant: "t",
148
- config,
149
- });
150
- const { _id } = await db.collection("notes").insert({ body: "hello" });
151
- const row = await db.collection("notes").get(_id);
152
- expect(row?.body).toBe("hello");
153
- });
154
- ```
155
-
156
- Each `new MemoryStorage()` is a fresh bucket — no shared state
157
- across tests. For multi-writer scenarios (causal-consistency
158
- tests, etc.), construct one `MemoryStorage` and pass the same
159
- instance into multiple `Db.create` calls so they share the
160
- underlying bucket.
161
-
162
- - **Predicates** — `db.collection(name).where({...}).all()` (the row
163
- type is inferred from the schema declared for `name` in
164
- `baerly.config.ts`; the generic on `.collection()` is the collection
165
- **name**, not the row type). Two shapes:
166
- - **Object literal** — equality only (top-level, dotted-path, or
167
- nested literal sub-predicate). Multi-field is implicit AND.
168
- - **Callback DSL** — `q => q.eq(...).gt(...).gte(...).lt(...).lte(...).in(...)`
169
- for the operator vocabulary. The methods on `PredicateBuilder<T>`
170
- ARE the supported surface — `q.or` / `q.regex` / `q.ne` /
171
- `q.exists` are TS compile errors. Chained `.where(...).where(...)`
172
- AND-merges across shapes.
173
-
174
- ```ts
175
- // Top-level equality
176
- await db.collection("tickets").where({ status: "open" }).all();
177
-
178
- // Dotted-path on a nested field
179
- await db.collection("tickets").where({ "assignee.team": "platform" }).all();
180
-
181
- // Operator on a single field — set membership (callback form)
182
- await db
183
- .collection("tickets")
184
- .where((q) => q.in("status", ["open", "pending"]))
185
- .all();
186
-
187
- // Range — also callback form
188
- await db
189
- .collection("tickets")
190
- .where((q) => q.gte("priority", 5).lt("priority", 10))
191
- .all();
192
-
193
- // AND-merge across two .where() calls (mix shapes freely)
194
- await db
195
- .collection("tickets")
196
- .where({ status: "open" })
197
- .where((q) => q.gte("priority", 5))
198
- .all();
199
- ```
200
-
201
- The plain-equality value type is JSON-arrayless: string / number /
202
- boolean / nested object. Use `q.in("status", [...])` for
203
- set membership when you'd otherwise want
204
- `{ status: ["open","pending"] }`.
205
-
206
- - **Indexes** — declare them in `baerly.config.ts`; the read-path
207
- planner picks one automatically when the predicate's equality
208
- fields cover an index's keys. No call-site hint is needed (the
209
- earlier `.useIndex(name)` chain was removed when the planner
210
- shipped — `Query<T>` has no such method).
211
-
212
- ```ts
213
- import { defineConfig } from "@gusto/baerly-storage/config";
214
-
215
- export default defineConfig({
216
- collections: {
217
- tickets: {
218
- indexes: [{ name: "by_status", on: "status" }],
219
- },
220
- },
221
- });
222
- ```
223
-
224
- With that declared, a query like
225
- `db.collection("tickets").where({ status: "open" }).all()` walks
226
- `by_status` automatically. Composite indexes
227
- (`on: ["status", "priority"]`) match any leftmost prefix.
228
- Mismatches (predicate doesn't cover any index) fall back to a full
229
- table scan with a metric bump; correctness is preserved because the
230
- reader re-checks the predicate in memory regardless of how it got
231
- the row set.
232
-
233
- - **Schemas (live feature)** — schemas are validated on the server
234
- for every `insert` / `update` / `replace` when bound. Declare via
235
- `defineConfig` using any StandardSchema v1 validator (Zod 3.24+,
236
- Valibot 0.36+, ArkType 2.0+, or anything implementing the spec):
237
-
238
- ```ts
239
- import { z } from "zod";
240
- import { defineConfig } from "@gusto/baerly-storage/config";
241
-
242
- const Ticket = z.object({
243
- _id: z.string(),
244
- status: z.enum(["open", "closed"]),
245
- title: z.string().min(1),
246
- });
247
-
248
- export default defineConfig({
249
- collections: {
250
- tickets: { schema: Ticket },
251
- },
252
- });
253
- ```
254
-
255
- On a validation failure the server throws
256
- `BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
257
- HTTP clients see a 400 with the same envelope. Validation runs
258
- on the post-image so `update` and `replace` see the full doc, not
259
- just the patch.
260
-
261
- - **HTTP wire format (calling `/v1/*` directly)** — the JS SDK
262
- (`db.collection(name).insert(...)`) is the canonical path; reach for `curl`
263
- only when debugging the wire. Mutation bodies are wrapped:
264
-
265
- | Route | Body | Response |
266
- | ------------------------------ | ----------------- | ---------------- |
267
- | `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
268
- | `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
269
- | `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
270
- | `DELETE /v1/c/:collection/:id` | — | `204` |
271
-
272
- Reads (`GET /v1/c/:collection[/:id]`, `GET /v1/count?collection=…`,
273
- `GET /v1/since?collection=…&cursor=…`) take no body and return
274
- `{ data, _meta }` or a route-specific envelope. A flat `POST` body
275
- (without the `doc` wrapper) returns
276
- `400 SchemaError "Request body must be { doc: object }"` — the
277
- wording is locked by `assertJsonBodyField` in the kernel. Canonical
278
- reference: the JSDoc on `createRouter` in
279
- `baerly-storage`.
280
-
281
- - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
282
- every request resolves to `tenant: "minimal-demo"` and `Authorization`
283
- is ignored. The adapter reads `config.auth` to pick its verifier;
284
- a `verifier:` on `baerlyNode({ ... })` overrides it. There is no
285
- `baerly doctor --target=node` backend today; verify bucket CAS with
286
- `baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after
287
- deploy. See "Going to production" below for the two production-fit
288
- recipes.
75
+ <!-- library:start -->
76
+
77
+ - **Library reference** — the shared API guidance is installed with the package, in `node_modules/@gusto/baerly-storage/dist/`. Read the matching section before editing storage code:
78
+ - **Typed rows** (binding `config`, `RowOf`, casting an undeclared collection): `API.md#documentdata--row-shape-constraint`. A hand-written row type failing `DocumentData`: `RECIPES.md#type-bookmark-does-not-satisfy-the-constraint-documentdata-ts2344`.
79
+ - **Writing tests**: `API.md`, section `Db.create`. `new MemoryStorage()` is a fresh bucket per test; share one instance across `Db.create` calls for multi-writer tests. `src/notes.test.ts` is the working example.
80
+ - **Predicates** (object literal vs callback DSL, operators, by-`_id` verbs): `API.md#predicates`. Set membership is `q.in`, never an array in the object form: `RECIPES.md#baerlyerror-codeinvalidconfig--predicate-value-at--is-an-array`.
81
+ - **Indexes**: don't declare them; a read always folds the whole collection. `API.md`, section `defineConfig`.
82
+ - **Schemas** (StandardSchema validators, `SchemaError`): `API.md`, section `defineConfig`.
83
+ - **HTTP wire format** (calling `/v1/*` directly): `API.md#http-wire-format`.
84
+ - **Verifier presets** (`sharedSecret`, `bearerJwt`, `cloudflareAccess`, `tenantPrefix`): `API.md#verifier-presets`. Refreshing a client token on 401, logging, tracing: `RECIPES.md#recipe--wrapping-the-client-fetch`. Serving `/v1/*` behind your own gate: `RECIPES.md#recipe--authoring-a-gated-adapter`.
85
+ - **Errors by message** (`RECIPES.md`, one entry per error string) and the shared anti-patterns: `RECIPES.md#anti-patterns-compile-clean-but-wrong`.
86
+
87
+ <!-- library:end -->
88
+
89
+ - **This template** — `src/web/main.ts` passes `config` to `createBaerlyClient` and `src/notes.test.ts` passes it to `Db.create`, so rows are already typed: no generic. For a hot filtered read, maintain a side-projection (see Anti-patterns).
90
+
91
+ - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`: every request resolves to `tenant: "minimal-demo"` and `Authorization` is ignored. The adapter reads `config.auth` to pick its verifier; a `verifier:` on `baerlyNode({ ... })` overrides it. There is no `baerly doctor --target=node` backend today; verify bucket CAS with `baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after deploy. See "Going to production" below for the two production-fit recipes.
289
92
 
290
93
  ### Going to production
291
94
 
292
- The scaffold ships `auth: "none"` so the day-1 happy path works with
293
- zero env vars. Two patterns flip to a production-fit posture; pick
294
- the one matching your gate.
95
+ The scaffold ships `auth: "none"` so the day-1 happy path works with zero env vars. Two patterns flip to a production-fit posture; pick the one matching your gate.
295
96
 
296
97
  <!-- pattern-b:start -->
297
98
 
298
- **Pattern B — `auth: "shared-secret"`** (single-tenant
299
- server-to-server). No factory code changes; `baerly.config.ts` flips:
99
+ **Pattern B — `auth: "shared-secret"`** (single-tenant server-to-server). No factory code changes; `baerly.config.ts` flips:
300
100
 
301
101
  ```ts
302
102
  // baerly.config.ts
303
103
  auth: "shared-secret", // ← flip from "none"
304
104
  ```
305
105
 
306
- Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
307
- `SHARED_SECRET` in the process environment (your PaaS / secret
308
- manager). The Node process fails closed if `auth: "shared-secret"`
309
- is set without `SHARED_SECRET` reachable from `process.env`; verify
310
- the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
106
+ Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set `SHARED_SECRET` in the process environment (your PaaS / secret manager). The Node process fails closed if `auth: "shared-secret"` is set without `SHARED_SECRET` reachable from `process.env`; verify the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
311
107
 
312
108
  <!-- pattern-b:end -->
313
109
  <!-- pattern-c:start -->
314
110
 
315
- **Pattern C — JWKS-backed JWT** (multi-tenant; OIDC IdP). The factory
316
- `verifier:` overrides `config.auth`, so dev keeps `"none"` and prod
317
- gets `bearerJwt`:
111
+ **Pattern C — JWKS-backed JWT** (multi-tenant; OIDC IdP). The factory `verifier:` overrides `config.auth`, so dev keeps `"none"` and prod gets `bearerJwt`:
318
112
 
319
113
  ```ts
320
114
  // baerly.config.ts — unchanged
@@ -348,140 +142,46 @@ await baerlyNode({
348
142
  }).listen(Number(process.env["PORT"] ?? 8080));
349
143
  ```
350
144
 
351
- Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
352
- `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
353
- `JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
354
- IdP issues one tenant per token; use `tenantPrefix` for single-tenant
355
- apps or tenancy enforced outside baerly-storage.
145
+ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your IdP issues one tenant per token; use `tenantPrefix` for single-tenant apps or tenancy enforced outside baerly-storage.
356
146
 
357
147
  <!-- pattern-c:end -->
358
148
 
359
- - **Storage backend** — `src/server/index.ts` resolves storage by env:
360
- `R2_ACCOUNT_ID` → Cloudflare R2, else `BUCKET` → AWS S3, else
361
- zero-config `localFsStorage()` (persists to `./.baerly-data`, no
362
- credentials, local dev only). **In a detected deployment
363
- (`NODE_ENV=production` or a known PaaS) the server fails loud and
364
- requires a bucket** — local-fs is single-process with no cross-process
365
- CAS or crash durability, so it is never a production store (there is no
366
- opt-in). AWS S3 and Cloudflare R2 are the production-supported stores;
367
- self-hosting without a cloud bucket, run **MinIO** on the box (also the
368
- local/dev conformance target) or graduate to SQLite + Litestream. Other S3-compatible endpoints need a
369
- green `baerly doctor --bucket` plus owner validation; GCS S3-interop
370
- is not supported for database use today. JSDoc `@example` blocks for
371
- the factories are visible in your editor's TS hover.
372
-
373
- - **Switching from static creds to EKS** — in
374
- `src/server/index.ts`, swap `credentials: { accessKeyId,
375
- secretAccessKey }` for `credentials: fromEks()` and add `fromEks`
376
- to your import:
377
- `import { s3Storage, fromEks } from "@gusto/baerly-storage/node"`.
378
- `fromEks()` auto-detects the cluster's mechanism — EKS Pod Identity
379
- (`AWS_CONTAINER_CREDENTIALS_FULL_URI` +
380
- `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`) or IRSA (`AWS_ROLE_ARN` +
381
- `AWS_WEB_IDENTITY_TOKEN_FILE`), both EKS-injected; to pin one, use
382
- `fromEksPodIdentity()` or `fromWebIdentity()`. For ECS / EC2 / other
383
- AWS contexts, see `packages/adapter-node/AGENTS.md` — pass any
384
- `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
385
- factory through the seam.
386
-
387
- - **Deploy** — runs anywhere `node server.js` runs. The
388
- `package.json`'s `start` script is
389
- `node --experimental-strip-types src/server/index.ts`. Arrange the
390
- host to run `pnpm install && pnpm build` (populates
391
- `dist/client/` for the `webRoot` static-serve branch) before
392
- `pnpm start`. Set env vars from `.env.example` in the host's
393
- config.
394
-
395
- Shapes: **managed PaaS** (Railway, Render, DO App Platform, Fly
396
- without Docker, Heroku) auto-detects Node and runs the root
397
- scripts directly. **VM / bare-metal** uses your process manager
398
- of choice (systemd, pm2). **Container** (Docker, k8s, ECS, Fly
399
- Machines with a Dockerfile) — scaffold with `--with=docker` to
400
- add a production Dockerfile alongside this shape, or write your
401
- own.
149
+ - **Storage backend** — `src/server/resolve-storage.ts` resolves storage by env: `R2_ACCOUNT_ID` → Cloudflare R2, else `BUCKET` → AWS S3, else zero-config `localFsStorage()` (persists to `./.baerly-data`, no credentials, local dev only). **In a detected deployment (`NODE_ENV=production` or a known PaaS) the server fails loud and requires a bucket** — local-fs is single-process with no cross-process CAS or crash durability, so it is never a production store (there is no opt-in). AWS S3 and Cloudflare R2 are the production-supported stores; self-hosting without a cloud bucket, run **MinIO** on the box (also the local/dev conformance target) or graduate to SQLite + Litestream. Other S3-compatible endpoints need a green `baerly doctor --bucket` plus owner validation; GCS S3-interop is not supported for database use today. JSDoc `@example` blocks for the factories are visible in your editor's TS hover.
150
+
151
+ - **Storage credentials** — the default `resolveStorage()` (`src/server/resolve-storage.ts`) reads static keys from `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`. For EKS (`fromEks()`), expiring or vault-issued credentials, or an `@aws-sdk/credential-providers` provider, replace that re-export with your own `s3Storage({ ..., credentials })` call, following `node_modules/@gusto/baerly-storage/dist/RECIPES.md#recipe--storage-credentials-on-node`.
152
+
153
+ - **Deploy** — runs anywhere `node server.js` runs. The `package.json`'s `start` script is `node src/server/index.ts`. Arrange the host to run `pnpm install && pnpm build` (populates `dist/client/` for the `webRoot` static-serve branch) before `pnpm start`. Set env vars from `.env.example` in the host's config.
154
+
155
+ Shapes: **managed PaaS** (Railway, Render, DO App Platform, Fly without Docker, Heroku) auto-detects Node and runs the root scripts directly. **VM / bare-metal** uses your process manager of choice (systemd, pm2). **Container** (Docker, k8s, ECS, Fly Machines with a Dockerfile) — scaffold with `--with=docker` to add a production Dockerfile alongside this shape, or write your own.
402
156
 
403
157
  ## Anti-patterns
404
158
 
405
- - Widening branded types from `baerly-storage` (`UUID`,
406
- `ContentVersionId`). The types prevent confusion bugs.
407
- - Reaching into `node_modules/@gusto/baerly-storage/dist/` directly —
408
- consume the published exports.
409
- - Mutating `VerifierResult.tenantPrefix` between the verifier
410
- and `Db.create`. The dispatcher pins the tenant from the
411
- verifier's return value.
412
- - Calling `db.collection(...).all()` (or any unbounded read) inside a
413
- per-request handler. The call scans the entire collection on every
414
- request — fine for a fixture-sized table, catastrophic at any real
415
- size, and `pnpm verify` doesn't surface the cost. Push the filter
416
- into the predicate so the index planner can prune
417
- (`db.collection("notes").where({ ... }).all()`), or maintain a
418
- side-projection (Postgres/SQLite/search index) populated
419
- incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
420
- log feed or from a write hook —
421
- never re-scan per request.
159
+ - The shared anti-patterns (branded types, the verifier's tenant, secrets in the SPA bundle) are in `RECIPES.md#anti-patterns-compile-clean-but-wrong`.
160
+ - Calling `db.collection(...).all()` (or any unbounded read) inside a per-request handler. The call scans the entire collection on every request — fine for a fixture-sized table, catastrophic at any real size, and `pnpm verify` doesn't surface the cost. A predicate (`db.collection("notes").where({ ... }).all()`) trims the response but still folds the whole collection, so instead maintain a side-projection (Postgres/SQLite/search index) populated incrementally from the `/v1/since?collection=<name>&cursor=<opaque>` log feed or from a write hook — never re-scan per request.
422
161
 
423
162
  ## Maintenance
424
163
 
425
164
  <!-- pattern-d:start -->
426
165
 
427
- Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
428
- timer, no lock, no app-config knob — identical on every host. Every write runs a
429
- bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
430
- whose default is safe on every tier. A size-ratio threshold means idle buckets pay
431
- nothing. Concurrent folds are safe without coordination: the commit is a
432
- compare-and-swap, so a fold that loses to a concurrent write is simply discarded and
433
- its leftover swept by GC. On Cloudflare the fold is deferred past the response via
434
- ctx.waitUntil; everywhere else it runs inline. **Reads are pure** — they never run
435
- maintenance, so the published idle-reader cost bound holds.
436
-
437
- A bucket maintains itself as long as it takes writes. A bucket served read-only does
438
- not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
439
- graduate once a collection is large. See docs/about/graduation.md for the per-tier
440
- envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
441
-
442
- Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
443
- your own schedule. Not required for steady-state operation.
166
+ Maintenance is automatic and write-triggered: nothing to install or schedule, identically on every host, and reads never run it. A scheduled `runScheduledMaintenance` pass is an optional extra for a collection served mostly read-only. The behavior, the call, its per-tier limits and the Workers Free / Paid differences are in `node_modules/@gusto/baerly-storage/dist/RECIPES.md#recipe--scheduled-maintenance`.
444
167
 
445
168
  <!-- pattern-d:end -->
446
169
 
447
170
  ## When to graduate
448
171
 
449
- baerly-storage is designed for the small-to-medium operating point.
450
- The cost model puts the soft ceiling at:
451
-
452
- - **~30 writes / minute / collection** (throughput ceiling — model/estimate)
453
- - **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
454
- - **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
172
+ baerly-storage is designed for the small-to-medium operating point. The soft ceiling has three lines, none enforced by the protocol: writes per collection (a throughput estimate), collections per tenant (a soft fan-out guideline), and the R2 free-tier storage line (a cost signal). The figures live in one place: docs/spec/scale-ceilings.md § "The published envelope" in the baerly-storage repo.
455
173
 
456
- At M-size (~30 writes/min) the projected cost is ~$26/mo on S3 (~$18/mo on R2). Past
457
- those, per-class op pricing and fan-out scan cost start to dominate;
458
- you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
459
- Pick your graduation target:
174
+ At the M-size operating point, the projected cost is ~$12/mo on Cloudflare, including Workers Paid, and ~$19/mo on Node, excluding Node hosting. Past those, per-class op pricing and fan-out scan cost start to dominate; you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale. Pick your graduation target:
460
175
 
461
176
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
462
177
  - **Off-Workers or portability matters:** managed Postgres.
463
178
  - **Single-instance Node:** SQLite via Litestream.
464
179
 
465
- Either way, the export below is mechanical because log entries are
466
- Debezium-style CDC change events — graduation is a baerly-storage
467
- win, not a churn event.
468
-
469
- **Estimate your current rate:** for Node/self-hosted buckets,
470
- `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
471
- --tenant=<tenant>` lists recent log entries per collection and computes
472
- writes/min. On Cloudflare, use canonical logs for trend history and
473
- `baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
474
- current operation-cost projection until the usage scanner is wired to
475
- R2 bindings.
476
-
477
- **Export when ready:** `baerly export --target=sqlite|postgres|d1
478
- --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
479
- canonical SQL dump (and a `<output>.plan.json` sidecar carrying the
480
- inferred `ExportPlan`) that you load into your graduation target.
481
- The export is point-in-time and honours the active schema. Flags:
482
- `--where=<json-predicate>`, `--where-comment`, `--output`,
483
- `--no-sidecar`, `--json`. Exit codes: 0 success, 1 InvalidConfig,
484
- 2 Storage/Network, 3 Protocol invariant.
180
+ Either way, the export below is mechanical because log entries are Debezium-style CDC change events — graduation is a baerly-storage win, not a churn event.
181
+
182
+ **Estimate your current rate:** for Node/self-hosted buckets, `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app> --tenant=<tenant>` lists recent log entries per collection and computes writes/min. On Cloudflare, use canonical logs for trend history and `baerly cost --bucket=<bucket-uri> --collection=<collection>` for the current operation-cost projection until the usage scanner is wired to R2 bindings.
183
+
184
+ **Export when ready:** `baerly export --target=sqlite|postgres|d1 --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a canonical SQL dump (and a `<output>.plan.json` sidecar carrying the inferred `ExportPlan`) that you load into your graduation target. The export is point-in-time and honours the active schema. Flags: `--where=<json-predicate>`, `--where-comment`, `--output`, `--no-sidecar`, `--json`. Exit codes: 0 success, 1 InvalidConfig, 2 Storage/Network, 3 Protocol invariant.
485
185
 
486
186
  ## Pointers
487
187