@gusto/create-baerly-storage 0.2.0 → 0.4.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 (29) hide show
  1. package/LICENSE +202 -0
  2. package/dist/index.js +54 -28
  3. package/dist/index.js.map +1 -1
  4. package/dist/templates/addons/docker/Dockerfile +8 -2
  5. package/dist/templates/minimal-cloudflare/AGENTS.md +140 -101
  6. package/dist/templates/minimal-cloudflare/README.md +43 -33
  7. package/dist/templates/minimal-cloudflare/package.json +7 -7
  8. package/dist/templates/minimal-cloudflare/wrangler.jsonc +1 -1
  9. package/dist/templates/minimal-node/.baerly/scaffold.json +1 -1
  10. package/dist/templates/minimal-node/.env.example +12 -5
  11. package/dist/templates/minimal-node/AGENTS.md +135 -107
  12. package/dist/templates/minimal-node/README.md +77 -44
  13. package/dist/templates/minimal-node/package.json +5 -5
  14. package/dist/templates/minimal-node/src/server/index.ts +22 -30
  15. package/dist/templates/minimal-node/src/server/resolve-storage.ts +18 -0
  16. package/dist/templates/minimal-node/vite.config.ts +0 -2
  17. package/dist/templates/react-cloudflare/AGENTS.md +77 -52
  18. package/dist/templates/react-cloudflare/README.md +25 -16
  19. package/dist/templates/react-cloudflare/index.html +1 -1
  20. package/dist/templates/react-cloudflare/package.json +12 -12
  21. package/dist/templates/react-cloudflare/wrangler.jsonc +1 -1
  22. package/dist/templates/react-node/.env.example +12 -5
  23. package/dist/templates/react-node/AGENTS.md +117 -81
  24. package/dist/templates/react-node/README.md +67 -37
  25. package/dist/templates/react-node/package.json +10 -10
  26. package/dist/templates/react-node/src/server/index.ts +18 -29
  27. package/dist/templates/react-node/src/server/resolve-storage.ts +18 -0
  28. package/dist/templates/react-node/vite.config.ts +0 -2
  29. package/package.json +16 -11
@@ -15,14 +15,14 @@
15
15
  "@gusto/baerly-storage": "workspace:*"
16
16
  },
17
17
  "devDependencies": {
18
- "@cloudflare/vite-plugin": "^1.39.0",
19
- "@cloudflare/workers-types": "^4",
20
- "@types/node": "^24.0.0",
21
- "happy-dom": "^20.9.0",
18
+ "@cloudflare/vite-plugin": "^1.42.4",
19
+ "@cloudflare/workers-types": "^4.20260630.1",
20
+ "@types/node": "^26.0.1",
21
+ "happy-dom": "^20.10.6",
22
22
  "typescript": "^6.0.3",
23
- "vite": "^8.0.14",
24
- "vitest": "^4.1.7",
25
- "wrangler": "^4.95.0"
23
+ "vite": "^8.1.2",
24
+ "vitest": "^4.1.9",
25
+ "wrangler": "^4.106.0"
26
26
  },
27
27
  "packageManager": "pnpm@11.1.2"
28
28
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  // Cloudflare Worker manifest. See `AGENTS.md` for what each field
3
- // drives (R2 binding, assets, vars, cron, observability) and how
3
+ // drives (R2 binding, assets, vars) and how
4
4
  // the verifier consumes the vars.
5
5
  "$schema": "node_modules/wrangler/config-schema.json",
6
6
  "name": "minimal-cloudflare",
@@ -4,7 +4,7 @@
4
4
  { "from": "minimal-demo", "fromKey": "tenant" }
5
5
  ],
6
6
  "excludePaths": [".baerly/scaffold.json"],
7
- "excludeNames": ["node_modules", "dist", ".DS_Store", "*.tsbuildinfo"],
7
+ "excludeNames": ["node_modules", "dist", ".baerly-data", ".DS_Store", "*.tsbuildinfo"],
8
8
  "dropDevDeps": [],
9
9
  "copies": [
10
10
  { "from": "AGENTS.md", "to": "CLAUDE.md" },
@@ -1,13 +1,20 @@
1
- # Storage credentials (AWS S3 default; R2 when R2_ACCOUNT_ID is set).
2
- # For Minio / GCS, edit `src/server/index.ts` to use the matching
3
- # factory from `baerly-storage/node` (`minioStorage` / `gcsStorage`).
1
+ # Storage selection. Defaults to local filesystem storage
2
+ # (./.baerly-data, zero credentials) for local dev. A deployment
3
+ # (NODE_ENV=production or a known PaaS) requires a bucket below — the
4
+ # server fails loud rather than running on local-fs, which is local-dev
5
+ # only. Self-hosting without a cloud bucket? Run MinIO on the box, or use
6
+ # SQLite + Litestream.
7
+ # MinIO is for local conformance. Other S3-compatible endpoints require
8
+ # `baerly doctor --bucket` plus owner validation; GCS S3-interop is not
9
+ # supported for database use today.
10
+ # AWS S3: set BUCKET + AWS creds (AWS_REGION optional).
4
11
  AWS_ACCESS_KEY_ID=
5
12
  AWS_SECRET_ACCESS_KEY=
6
13
  AWS_REGION=us-east-1
7
14
  BUCKET=
8
15
  # Set to your Cloudflare R2 account ID (left half of the
9
- # https://<account>.r2.cloudflarestorage.com endpoint) to switch
10
- # storage from AWS S3 to R2. Leave unset for AWS S3.
16
+ # https://<account>.r2.cloudflarestorage.com endpoint) to use R2
17
+ # instead of AWS S3 (still set BUCKET + AWS_* creds). Leave unset for S3.
11
18
  # R2_ACCOUNT_ID=
12
19
 
13
20
  # Server
@@ -1,16 +1,17 @@
1
1
  ---
2
2
  title: AGENTS.md — agent guidance for minimal-node
3
3
  audience: agent
4
- summary: How to develop and deploy minimal-node, a baerly app.
5
- tags: [agent-entry, baerly]
4
+ summary: How to develop and deploy minimal-node, a baerly-storage app.
5
+ tags: [agent-entry, baerly-storage]
6
6
  ---
7
7
 
8
8
  # AGENTS.md
9
9
 
10
+ <!-- stop:start -->
10
11
  ## STOP — read this before writing any storage code
11
12
 
12
13
  Your training data is dense with Postgres + Prisma/Drizzle, Mongo,
13
- and Firebase patterns. **None of them apply here.** This is a baerly
14
+ and Firebase patterns. **None of them apply here.** This is a baerly-storage
14
15
  app — a small, LLM-legible document database with a narrow API on top
15
16
  of S3-compatible storage. Before writing or modifying storage code,
16
17
  read:
@@ -18,7 +19,7 @@ read:
18
19
  - **`node_modules/@gusto/baerly-storage/dist/API.md`** — hand-authored
19
20
  public-API quickref. Read first. Lists every method, every error
20
21
  code, every example. If a pattern you want to use isn't here, it
21
- doesn't exist in baerly.
22
+ doesn't exist in baerly-storage.
22
23
  - **`node_modules/@gusto/baerly-storage/dist/*.d.ts`** — authoritative type
23
24
  signatures. `Db`, `Collection<T>`, `Query<T>`, and `Predicate<T>` are
24
25
  the whole API surface.
@@ -37,41 +38,42 @@ Common anti-patterns that compile but are wrong:
37
38
  picks the index automatically from `IndexDefinition`s in
38
39
  `baerly.config.ts`. See **Indexes** below.
39
40
 
41
+ <!-- stop:end -->
40
42
  ## What this is
41
43
 
42
- `minimal-node` is a baerly app scaffolded with `create-baerly-storage` for the
43
- Node target — any host that runs `node server.js` (Railway, Render,
44
- Fly without Docker, Heroku, a VM, a container scheduler). One flat
45
- package: the Node-side server lives in `src/server/index.ts`; the
46
- optional client lives in `src/web/`. Configuration lives in
47
- `baerly.config.ts`.
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`.
48
50
 
49
51
  Single package, single `vite` process: `baerlyDev()` from
50
52
  `@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Vite
51
53
  middleware on `:5173` alongside the SPA dev server, so `pnpm dev`
52
54
  brings up SPA + HMR + `/v1/*` in one command — same origin in dev,
53
- same `dist/client/`-served origin in production via `pnpm start`
54
- (the listener serves the built SPA via the `baerlyNode({ webRoot })`
55
- option).
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.
56
59
 
57
60
  If this scaffold was created with `--with=docker`, you'll also have a
58
61
  multi-stage distroless `Dockerfile`, a `.dockerignore`, and a
59
62
  `healthcheck.js` at the project root — wired to the same
60
63
  `pnpm install && pnpm build && pnpm start` flow.
61
64
 
62
- Public API docs: https://docs.baerly.dev/ (the JSDoc on
63
- `baerly-storage`'s `Db` and `Collection` is the canonical reference;
64
- read it via your editor's TS LS or via the published types).
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`.
65
68
 
66
69
  ## Toolchain
67
70
 
68
71
  - **Package manager:** pnpm. The emitted repo pins
69
72
  `packageManager: pnpm@11.1.2`.
70
73
  - **Test runner:** vitest.
71
- - **Type checker:** TypeScript 5.6+. (The baerly-storage monorepo
72
- itself uses TypeScript 7 via `@typescript/native-preview`; this
73
- template tracks the broadly-compatible TS major so scaffolded
74
- apps work with the wider ecosystem.)
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`.)
75
77
  - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
76
78
  code stays compatible with type-stripping runtimes (Node's
77
79
  `--experimental-strip-types`, esbuild's strip path). The flag bans
@@ -85,15 +87,15 @@ read it via your editor's TS LS or via the published types).
85
87
 
86
88
  ## Verification
87
89
 
88
- | Command | What it does | Runtime |
89
- | ------------------ | -------------------------------------------------- | ---------------- |
90
- | `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 |
91
- | `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 |
92
- | `pnpm typecheck` | TS typecheck across the `app` + `server` project references | seconds |
93
- | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env). The minimal template ships no SPA tests by default; `--passWithNoTests` keeps the gate green until you add one. | seconds |
94
- | `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 |
95
- | `pnpm build` | `tsc -b && vite build` — emits the SPA into `dist/client/` | seconds |
96
- | `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the SPA from `dist/client/` via `webRoot` | seconds to start |
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 |
97
99
 
98
100
  **`pnpm verify` exercises typecheck + tests only.** The dev-auth
99
101
  middleware, the SPA bundle, and any custom `/api/*` route are NOT
@@ -105,31 +107,32 @@ http://localhost:5173/<path>`) before declaring the task complete.
105
107
 
106
108
  ## Where the code is
107
109
 
108
- | Path | What it is |
109
- | --------------------------- | --------------------------------------------------- |
110
- | `src/server/index.ts` | Server entry — composes `s3Storage` / `r2Storage` + a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
111
- | `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<Note>("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. |
112
- | `vite.config.ts` | Vite client build — `outDir: dist/client`; `baerlyDev()` mounts the Node listener as middleware so SPA + `/v1/*` share `:5173` in dev |
113
- | `tsconfig.{app,server}.json` | TS project references for the client and server projects |
114
- | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
115
- | `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. |
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. |
116
118
 
117
119
  > **`baerly.config.ts` and `types.ts` are dual-included** by both
118
120
  > `tsconfig.app.json` and `tsconfig.server.json`. Both can only
119
121
  > import from `baerly-storage`, `zod`, and other dual-included root
120
122
  > files. Paths under `src/server/` are server-only; importing them
121
- > here triggers `TS6307: File … is not listed within the file list
122
- > of project … tsconfig.app.json`. Cross-boundary interfaces belong
123
- > in `types.ts`; re-export from a server-only file if downstream code
124
- > wants a local name.
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.
125
127
 
126
128
  ## When editing X, read Y
127
129
 
128
130
  - **Writing tests** — the kernel exports `MemoryStorage`, an
129
131
  in-memory `Storage` impl that's the canonical backend for unit
130
- tests. Don't roll your own — `Db.create({ storage, app, tenant,
131
- config })` is the same boilerplate prod uses; passing
132
- `new MemoryStorage()` swaps S3 for an in-process map.
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.
133
136
 
134
137
  ```ts
135
138
  // src/notes.test.ts
@@ -156,9 +159,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
156
159
  instance into multiple `Db.create` calls so they share the
157
160
  underlying bucket.
158
161
 
159
- - **Predicates** — `db.collection<Doc>(name).where({...}).all()`. Two
160
- shapes:
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:
162
166
  - **Object literal** — equality only (top-level, dotted-path, or
163
167
  nested literal sub-predicate). Multi-field is implicit AND.
164
168
  - **Callback DSL** — `q => q.eq(...).gt(...).gte(...).lt(...).lte(...).in(...)`
@@ -172,24 +176,25 @@ http://localhost:5173/<path>`) before declaring the task complete.
172
176
  await db.collection("tickets").where({ status: "open" }).all();
173
177
 
174
178
  // Dotted-path on a nested field
175
- await db.collection("tickets")
176
- .where({ "assignee.team": "platform" })
177
- .all();
179
+ await db.collection("tickets").where({ "assignee.team": "platform" }).all();
178
180
 
179
181
  // Operator on a single field — set membership (callback form)
180
- await db.collection("tickets")
181
- .where(q => q.in("status", ["open", "pending"]))
182
+ await db
183
+ .collection("tickets")
184
+ .where((q) => q.in("status", ["open", "pending"]))
182
185
  .all();
183
186
 
184
187
  // Range — also callback form
185
- await db.collection("tickets")
186
- .where(q => q.gte("priority", 5).lt("priority", 10))
188
+ await db
189
+ .collection("tickets")
190
+ .where((q) => q.gte("priority", 5).lt("priority", 10))
187
191
  .all();
188
192
 
189
193
  // AND-merge across two .where() calls (mix shapes freely)
190
- await db.collection("tickets")
194
+ await db
195
+ .collection("tickets")
191
196
  .where({ status: "open" })
192
- .where(q => q.gte("priority", 5))
197
+ .where((q) => q.gte("priority", 5))
193
198
  .all();
194
199
  ```
195
200
 
@@ -216,8 +221,9 @@ http://localhost:5173/<path>`) before declaring the task complete.
216
221
  });
217
222
  ```
218
223
 
219
- With that declared, `db.collection("tickets").where({ status: "open"
220
- }).all()` walks `by_status` automatically. Composite indexes
224
+ With that declared, a query like
225
+ `db.collection("tickets").where({ status: "open" }).all()` walks
226
+ `by_status` automatically. Composite indexes
221
227
  (`on: ["status", "priority"]`) match any leftmost prefix.
222
228
  Mismatches (predicate doesn't cover any index) fall back to a full
223
229
  table scan with a metric bump; correctness is preserved because the
@@ -248,7 +254,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
248
254
 
249
255
  On a validation failure the server throws
250
256
  `BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
251
- HTTP clients see a 422 with the same envelope. Validation runs
257
+ HTTP clients see a 400 with the same envelope. Validation runs
252
258
  on the post-image so `update` and `replace` see the full doc, not
253
259
  just the patch.
254
260
 
@@ -256,12 +262,12 @@ http://localhost:5173/<path>`) before declaring the task complete.
256
262
  (`db.collection(name).insert(...)`) is the canonical path; reach for `curl`
257
263
  only when debugging the wire. Mutation bodies are wrapped:
258
264
 
259
- | Route | Body | Response |
260
- | --------------------------- | ------------------- | ----------------------------- |
261
- | `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
262
- | `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
263
- | `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
264
- | `DELETE /v1/c/:collection/:id` | — | `204` |
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` |
265
271
 
266
272
  Reads (`GET /v1/c/:collection[/:id]`, `GET /v1/count?collection=…`,
267
273
  `GET /v1/since?collection=…&cursor=…`) take no body and return
@@ -269,15 +275,17 @@ http://localhost:5173/<path>`) before declaring the task complete.
269
275
  (without the `doc` wrapper) returns
270
276
  `400 SchemaError "Request body must be { doc: object }"` — the
271
277
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
272
- reference: the `Routes` type and the JSDoc on `createRouter` in
278
+ reference: the JSDoc on `createRouter` in
273
279
  `baerly-storage`.
274
280
 
275
281
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
276
282
  every request resolves to `tenant: "minimal-demo"` and `Authorization`
277
283
  is ignored. The adapter reads `config.auth` to pick its verifier;
278
- a `verifier:` on `baerlyNode({ ... })` overrides it. `baerly
279
- doctor --target=node` warns on `"none"` for deploy targets. See
280
- "Going to production" below for the two production-fit recipes.
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.
281
289
 
282
290
  ### Going to production
283
291
 
@@ -286,6 +294,7 @@ zero env vars. Two patterns flip to a production-fit posture; pick
286
294
  the one matching your gate.
287
295
 
288
296
  <!-- pattern-b:start -->
297
+
289
298
  **Pattern B — `auth: "shared-secret"`** (single-tenant
290
299
  server-to-server). No factory code changes; `baerly.config.ts` flips:
291
300
 
@@ -296,12 +305,13 @@ auth: "shared-secret", // ← flip from "none"
296
305
 
297
306
  Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
298
307
  `SHARED_SECRET` in the process environment (your PaaS / secret
299
- manager). `baerly doctor --target=node` FAILs if
300
- `auth: "shared-secret"` is set without `SHARED_SECRET` reachable from
301
- `process.env`.
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>`.
302
311
 
303
312
  <!-- pattern-b:end -->
304
313
  <!-- pattern-c:start -->
314
+
305
315
  **Pattern C — JWKS-backed JWT** (multi-tenant; OIDC IdP). The factory
306
316
  `verifier:` overrides `config.auth`, so dev keeps `"none"` and prod
307
317
  gets `bearerJwt`:
@@ -332,6 +342,7 @@ await baerlyNode({
332
342
  jwks: process.env["JWKS_URL"],
333
343
  issuer: process.env["JWT_ISSUER"]!,
334
344
  audience: process.env["JWT_AUDIENCE"]!,
345
+ tenantPrefix: config.tenant, // or tenantClaim: "tenant"
335
346
  }),
336
347
  }),
337
348
  }).listen(Number(process.env["PORT"] ?? 8080));
@@ -339,28 +350,37 @@ await baerlyNode({
339
350
 
340
351
  Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
341
352
  `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
342
- `JWT_AUDIENCE` and `bearerJwt` engages.
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.
343
356
 
344
357
  <!-- pattern-c:end -->
345
- - **Storage backend** — `src/server/index.ts` picks between
346
- `s3Storage` (AWS) and `r2Storage` (Cloudflare R2) based on whether
347
- `R2_ACCOUNT_ID` is set. To use **Minio** (self-hosted dev S3) or
348
- **GCS** (HMAC keys), swap the import to `minioStorage` /
349
- `gcsStorage` from `@gusto/baerly-storage/node`. All four factories take
350
- the same shape — a single bucket-name + credentials object — and
351
- hide `aws4fetch` / `@xmldom/xmldom` behind the package boundary.
352
- JSDoc `@example` blocks for each factory are visible in your
353
- editor's TS hover.
354
-
355
- - **Switching from static creds to EKS Pod Identity** — in
358
+
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
356
374
  `src/server/index.ts`, swap `credentials: { accessKeyId,
357
- secretAccessKey }` for `credentials: fromEksPodIdentity()` and add
358
- `fromEksPodIdentity` to your import:
359
- `import { s3Storage, fromEksPodIdentity } from "@gusto/baerly-storage/node"`.
360
- The agent reads `AWS_CONTAINER_CREDENTIALS_FULL_URI` +
361
- `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` (EKS injects both). For
362
- IRSA / ECS / EC2 / other AWS contexts, see
363
- `packages/adapter-node/AGENTS.md` — pass any
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
364
384
  `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
365
385
  factory through the seam.
366
386
 
@@ -396,12 +416,14 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
396
416
  into the predicate so the index planner can prune
397
417
  (`db.collection("notes").where({ ... }).all()`), or maintain a
398
418
  side-projection (Postgres/SQLite/search index) populated
399
- incrementally from the `/v1/since` log feed or from a write hook —
419
+ incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
420
+ log feed or from a write hook —
400
421
  never re-scan per request.
401
422
 
402
423
  ## Maintenance
403
424
 
404
425
  <!-- pattern-d:start -->
426
+
405
427
  Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
406
428
  timer, no lock, no app-config knob — identical on every host. Every write runs a
407
429
  bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
@@ -415,36 +437,42 @@ maintenance, so the published idle-reader cost bound holds.
415
437
  A bucket maintains itself as long as it takes writes. A bucket served read-only does
416
438
  not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
417
439
  graduate once a collection is large. See docs/about/graduation.md for the per-tier
418
- envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
440
+ envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
419
441
 
420
442
  Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
421
443
  your own schedule. Not required for steady-state operation.
444
+
422
445
  <!-- pattern-d:end -->
423
446
 
424
447
  ## When to graduate
425
448
 
426
- baerly is designed for the small-to-medium operating point. The cost
427
- model puts the soft ceiling at:
449
+ baerly-storage is designed for the small-to-medium operating point.
450
+ The cost model puts the soft ceiling at:
428
451
 
429
- - **~30 writes / minute / collection**
430
- - **~10 GB / tenant**
431
- - **~100 collections / tenant**
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)
432
455
 
433
- Past those, S3 list-prefix latency, manifest fold cost, and per-class
434
- op pricing start to dominate; you're better off on a real database.
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.
435
459
  Pick your graduation target:
460
+
436
461
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
437
462
  - **Off-Workers or portability matters:** managed Postgres.
438
463
  - **Single-instance Node:** SQLite via Litestream.
439
464
 
440
465
  Either way, the export below is mechanical because log entries are
441
- Postgres-logical-replication-shaped — graduation is a Baerly win,
442
- not a churn event.
443
-
444
- **Estimate your current rate:** `baerly admin usage --target=...`
445
- lists recent log entries per collection and computes
446
- writes/min. Warning at 50% of the ceiling; export suggestion at
447
- 100%.
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.
448
476
 
449
477
  **Export when ready:** `baerly export --target=sqlite|postgres|d1
450
478
  --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a