@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
@@ -1,11 +1,17 @@
1
1
  # react-cloudflare
2
2
 
3
- A baerly app scaffolded with `@gusto/create-baerly-storage` for the **Cloudflare
4
- Workers** target, with a React + Vite SPA. Single-bucket R2-backed
5
- deployment via `@gusto/baerly-storage/cloudflare`. Ships `auth: "none"`
6
- so the day-1 happy path works with zero env vars, plus a
7
- one-collection `notes` schema you extend; flip to Cloudflare Access
8
- or a shared secret before deploy — see "Production auth" below.
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
4
+ the **Cloudflare Workers** target, with a React + Vite SPA.
5
+ Single-bucket R2-backed deployment via
6
+ `@gusto/baerly-storage/cloudflare`. Ships `auth: "none"` so the day-1
7
+ happy path works with zero env vars, plus a one-collection `notes`
8
+ schema you extend; flip to Cloudflare Access or a shared secret before
9
+ deploy — see "Production auth" below.
10
+
11
+ **The R2 bucket is the durable state.** The Worker is trusted app code
12
+ with an R2 binding; it applies the baerly-storage protocol, but it is
13
+ not a database server. No daemon, lock table, scheduler, or idle
14
+ database bill; maintenance is automatic and write-triggered.
9
15
 
10
16
  ## What you got
11
17
 
@@ -16,7 +22,7 @@ react-cloudflare/
16
22
  ├── tsconfig.app.json # client TS project (src/web)
17
23
  ├── tsconfig.worker.json # Worker TS project (src/server)
18
24
  ├── vite.config.ts # Vite + @vitejs/plugin-react + @cloudflare/vite-plugin
19
- ├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars, cron, observability
25
+ ├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
20
26
  ├── index.html # SPA shell — Vite's entry point
21
27
  ├── baerly.config.ts # app, tenant, target, NoteSchema, `Note` type
22
28
  ├── AGENTS.md # deeper guide: hooks, schema, auth, deploy
@@ -46,7 +52,7 @@ share an origin (`http://localhost:5173`). First run downloads the
46
52
 
47
53
  Open <http://localhost:5173>. Type a note, hit "Add note." Open a
48
54
  second tab — inserts, edits, and deletes in one tab appear in the
49
- other over the `/v1/since` long-poll.
55
+ other over the `/v1/since?collection=notes&cursor=...` long-poll.
50
56
 
51
57
  `pnpm build` runs `tsc -b && vite build`; the SPA lands in
52
58
  `dist/client/` for the `assets:` binding in `wrangler.jsonc` to
@@ -56,7 +62,7 @@ serve on deploy.
56
62
 
57
63
  ```sh
58
64
  baerly deploy # reads baerly.config.ts:target, runs wrangler deploy
59
- baerly doctor --target=cloudflare # verify bindings, secrets, cron
65
+ baerly doctor --target=cloudflare # verify bindings, secrets, optional triggers
60
66
  ```
61
67
 
62
68
  `baerly doctor --target=cloudflare` warns on `auth: "none"` for
@@ -91,7 +97,8 @@ follow `AGENTS.md` → "Going to production":
91
97
  `wrangler.jsonc:vars`. The `cloudflareAccess()` preset
92
98
  (re-exported from `@gusto/baerly-storage/auth`) reads the JWT off
93
99
  `Cf-Access-Jwt-Assertion`, validates it against your team's JWKS,
94
- and derives `tenantPrefix` from the email claim.
100
+ and pins `tenantPrefix` to `config.tenant` unless you pass an
101
+ explicit tenant claim.
95
102
  - **Pattern B — `auth: "shared-secret"`.** Single-tenant
96
103
  server-to-server callers. Flip `auth` in `baerly.config.ts`, set
97
104
  `SHARED_SECRET` via `wrangler secret put`, and re-enable
@@ -100,16 +107,18 @@ follow `AGENTS.md` → "Going to production":
100
107
 
101
108
  ## When to graduate
102
109
 
103
- baerly is sized for the small-to-medium operating point. Past
104
- ~30 writes/min/collection, ~10 GB/tenant, or ~100 collections/
105
- tenant, graduate to D1 or Postgres via `baerly export
106
- --target=postgres`. Your data was already in your bucket; the
107
- export is a mechanical translator, not a vendor migration.
110
+ baerly-storage is sized for the small-to-medium operating point. Past
111
+ ~30 writes/min/collection (throughput estimate), the R2 free-tier
112
+ storage cost line (>10 GB/tenant), or the soft fan-out guideline
113
+ (~100 collections/tenant — linear cost, nothing enforces it),
114
+ graduate to D1 or Postgres via `baerly export --target=postgres`.
115
+ Your data was already in your bucket; the export is a mechanical
116
+ translator, not a vendor migration.
108
117
 
109
118
  ## Pointers
110
119
 
111
120
  - `baerly.config.ts` — app config + Zod schema.
112
- - `src/server/index.ts` — Worker fetch + scheduled handler.
121
+ - `src/server/index.ts` — Worker fetch entry.
113
122
  - `src/web/NoteList.tsx` — `useQuery` reactive read.
114
123
  - `wrangler.jsonc` — Cloudflare Worker manifest.
115
124
  - `AGENTS.md` / `CLAUDE.md` — agent-facing guide (byte-identical).
@@ -1,4 +1,4 @@
1
- <!DOCTYPE html>
1
+ <!doctype html>
2
2
  <html lang="en">
3
3
  <head>
4
4
  <meta charset="UTF-8" />
@@ -13,22 +13,22 @@
13
13
  },
14
14
  "dependencies": {
15
15
  "@gusto/baerly-storage": "workspace:*",
16
- "react": "^19.0.0",
17
- "react-dom": "^19.0.0",
16
+ "react": "^19.2.7",
17
+ "react-dom": "^19.2.7",
18
18
  "zod": "^4.4.3"
19
19
  },
20
20
  "devDependencies": {
21
- "@cloudflare/vite-plugin": "^1.39.0",
22
- "@cloudflare/workers-types": "^4",
23
- "@types/node": "^24.0.0",
24
- "@types/react": "^19.2.15",
25
- "@types/react-dom": "^19.0.0",
26
- "@vitejs/plugin-react": "^6.0.2",
27
- "happy-dom": "^20.9.0",
21
+ "@cloudflare/vite-plugin": "^1.42.4",
22
+ "@cloudflare/workers-types": "^4.20260630.1",
23
+ "@types/node": "^26.0.1",
24
+ "@types/react": "^19.2.17",
25
+ "@types/react-dom": "^19.2.3",
26
+ "@vitejs/plugin-react": "^6.0.3",
27
+ "happy-dom": "^20.10.6",
28
28
  "typescript": "^6.0.3",
29
- "vite": "^8.0.14",
30
- "vitest": "^4.1.7",
31
- "wrangler": "^4.95.0"
29
+ "vite": "^8.1.2",
30
+ "vitest": "^4.1.9",
31
+ "wrangler": "^4.106.0"
32
32
  },
33
33
  "packageManager": "pnpm@11.1.2"
34
34
  }
@@ -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": "react-cloudflare",
@@ -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 react-node
3
3
  audience: agent
4
- summary: How to develop and deploy react-node, a baerly app.
5
- tags: [agent-entry, baerly]
4
+ summary: How to develop and deploy react-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,13 +38,15 @@ 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
- `react-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). The
45
- Node-side server lives in `src/server/`; the React client lives in
46
- `src/web/`. Configuration lives in `baerly.config.ts`.
44
+ `react-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). The Node-side server lives in `src/server/`; the
48
+ React client lives in `src/web/`. Configuration lives in
49
+ `baerly.config.ts`.
47
50
 
48
51
  Single package, single `vite` process: `baerlyDev()` from
49
52
  `@gusto/baerly-storage/dev/vite` mounts the Node HTTP listener as Connect
@@ -65,19 +68,18 @@ multi-stage distroless `Dockerfile`, a `.dockerignore`, and a
65
68
  `healthcheck.js` at the project root — wired to the same
66
69
  `pnpm install && pnpm build && pnpm start` flow.
67
70
 
68
- Public API docs: https://docs.baerly.dev/ (the JSDoc on
69
- `baerly-storage`'s `Db` and `Collection` is the canonical reference;
70
- read it via your editor's TS LS or via the published types).
71
+ Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
72
+ is the canonical reference; read it via your editor's TS LS, the
73
+ published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
71
74
 
72
75
  ## Toolchain
73
76
 
74
77
  - **Package manager:** pnpm. The emitted repo pins
75
78
  `packageManager: pnpm@11.1.2`.
76
79
  - **Test runner:** vitest.
77
- - **Type checker:** TypeScript 5.6+. (The baerly-storage monorepo
78
- itself uses TypeScript 7 via `@typescript/native-preview`; this
79
- template tracks the broadly-compatible TS major so scaffolded
80
- apps work with the wider ecosystem.)
80
+ - **Type checker:** TypeScript 6.x, as pinned in `package.json`.
81
+ (The baerly-storage monorepo itself uses TypeScript 7 via
82
+ `@typescript/native-preview`.)
81
83
  - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
82
84
  code stays compatible with type-stripping runtimes (Node's
83
85
  `--experimental-strip-types`, esbuild's strip path). The flag bans
@@ -96,7 +98,7 @@ read it via your editor's TS LS or via the published types).
96
98
  | `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 |
97
99
  | `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 |
98
100
  | `pnpm typecheck` | TS typecheck across the `app` + `server` project references (`tsc -b --noEmit`) | seconds |
99
- | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env) | seconds |
101
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env) | seconds |
100
102
  | `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 |
101
103
  | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the `baerlyNode({ webRoot })` static-serve branch | seconds |
102
104
  | `pnpm start` | `node --experimental-strip-types src/server/index.ts` — production entry; serves the SPA from `dist/client/` via `webRoot` | seconds to start |
@@ -113,7 +115,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
113
115
 
114
116
  | Path | What it is |
115
117
  | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
116
- | `src/server/index.ts` | Server entry — composes `s3Storage` / `r2Storage` + a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
118
+ | `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)` |
117
119
  | `src/web/` | React+Vite frontend. Served by the Node listener via `baerlyNode({ webRoot })` in production. |
118
120
  | `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.tsx`. |
119
121
  | `vite.config.ts` | Vite + `@vitejs/plugin-react` + `baerlyDev()` — mounts the Node HTTP listener as middleware so SPA + `/v1/*` share `:5173` in dev |
@@ -121,7 +123,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
121
123
  | `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib, `jsx: react-jsx`) |
122
124
  | `tsconfig.server.json` | Node server TS project (`src/server/`, Node lib) |
123
125
  | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `collections` (schemas live here). Also exports the inferred `Note` row type used by the web client. |
124
- | `.env.example` | Source of truth for env vars the Node entry reads (`BUCKET`, `AWS_*`, the optional `BAERLY_MAINTENANCE_*` ops-plane tuners, etc.; `SHARED_SECRET` / `JWKS_URL` only needed if you adopt the "Going to production" auth recipes) |
126
+ | `.env.example` | Source of truth for env vars the default Node entry reads (`BUCKET`, `AWS_*`, optional `R2_ACCOUNT_ID`, optional `PORT`) |
125
127
 
126
128
  > **`baerly.config.ts` is dual-included.** Both `tsconfig.app.json`
127
129
  > and `tsconfig.server.json` `include` this file, so it must only
@@ -135,22 +137,34 @@ http://localhost:5173/<path>`) before declaring the task complete.
135
137
 
136
138
  ## When editing X, read Y
137
139
 
138
- - **Typed collections** — three ways to get a typed row, in DX order:
140
+ - **Typed collections** — two ways to get a typed row, in DX order.
141
+ The generic on `client.collection<N>(name)` is the collection
142
+ **name** (constrained to `CollectionNames<typeof config>`), not the
143
+ row type — so don't pass a row type to it.
139
144
  1. **Bind the config.** This template's `src/web/client.ts`
140
145
  already passes `config` to `createBaerlyClient({ baseUrl,
141
146
  config })`, so `client.collection("notes")` returns
142
147
  `ClientCollection<Row>` with `Row` derived from the
143
148
  `NoteSchema` declared in `baerly.config.ts`. No generic
144
- needed. Use `client.collection<Note>("notes")` (with `Note`
145
- exported from `baerly.config.ts` next to the schema)
146
- only when you need the row type by name elsewhere.
147
- 2. **Explicit generic, kernel constraint.** Without a declared
148
- collection, the second overload requires the row to satisfy
149
- the kernel's `DocumentData` shape (`{ [k: string]: DocumentValue }`):
149
+ needed. When you need to name that row type elsewhere, use
150
+ `RowOf<typeof config, "notes">` (re-exported from
151
+ `@gusto/baerly-storage`) — not a generic on `.collection()`.
152
+ 2. **Cast the handle (undeclared collection).** This template's
153
+ `client` is bound to `config`, so its names narrow to the
154
+ declared collections. To reach a collection that isn't in
155
+ `config`, build an unbound client
156
+ (`createBaerlyClient({ baseUrl })` with no `config`) — its names
157
+ widen to `string` and its row defaults to `DocumentData`. Cast at
158
+ the construction site for a narrower shape that still satisfies
159
+ the kernel's `DocumentData` constraint
160
+ (`{ [k: string]: DocumentValue }`):
150
161
  ```ts
162
+ import { createBaerlyClient, type ClientCollection } from "@gusto/baerly-storage/client";
151
163
  import type { DocumentData } from "@gusto/baerly-storage";
152
164
  interface Bookmark extends DocumentData { _id: string; url: string }
153
- await client.collection<Bookmark>("bookmarks").all();
165
+ const raw = createBaerlyClient({ baseUrl: "" });
166
+ const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
167
+ await bookmarks.all();
154
168
  ```
155
169
  A plain `interface Bookmark { _id: string; url: string }`
156
170
  (no index signature) will fail with TS2344 — the constraint
@@ -246,9 +260,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
246
260
  });
247
261
  ```
248
262
 
249
- The adapter threads `collections` into `Db.create({ ... })` for
250
- you. Predicates the planner can't route fall back to the full
251
- scan with a metric bump — correctness is preserved.
263
+ The adapter passes your `config` into
264
+ `Db.create({ storage, app, tenant, config })` for you. Predicates the
265
+ planner can't route fall back to the full scan with a metric bump —
266
+ correctness is preserved.
252
267
 
253
268
  - **Schemas (live feature)** — schemas are validated on the server
254
269
  for every `insert` / `update` / `replace` when bound. Declare via
@@ -273,7 +288,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
273
288
 
274
289
  On a validation failure the server throws
275
290
  `BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
276
- HTTP clients see a 422 with the same envelope. Validation runs
291
+ HTTP clients see a 400 with the same envelope. Validation runs
277
292
  on the post-image so `update` and `replace` see the full doc, not
278
293
  just the patch.
279
294
 
@@ -294,7 +309,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
294
309
  (without the `doc` wrapper) returns
295
310
  `400 SchemaError "Request body must be { doc: object }"` — the
296
311
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
297
- reference: the `Routes` type and the JSDoc on `createRouter` in
312
+ reference: the JSDoc on `createRouter` in
298
313
  `baerly-storage`.
299
314
 
300
315
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
@@ -302,9 +317,11 @@ http://localhost:5173/<path>`) before declaring the task complete.
302
317
  is ignored. The adapter reads `config.auth` to pick its verifier;
303
318
  a `verifier:` on `baerlyNode({ ... })` overrides it. The schema-
304
319
  bound `notes` collection (`baerly.config.ts:NoteSchema`) runs
305
- server-side regardless of the auth posture. `baerly doctor
306
- --target=node` warns on `"none"` for deploy targets. See "Going to
307
- production" below for the two production-fit recipes.
320
+ server-side regardless of the auth posture. There is no `baerly
321
+ doctor --target=node` backend today; verify bucket CAS with
322
+ `baerly doctor --bucket=<s3-uri>` and probe `/v1/healthz` after
323
+ deploy. See "Going to production" below for the two production-fit
324
+ recipes.
308
325
 
309
326
  ### Going to production
310
327
 
@@ -324,9 +341,9 @@ auth: "shared-secret", // ← flip from "none"
324
341
 
325
342
  Dev: put `SHARED_SECRET=dev-shared-secret` in `.env`. Prod: set
326
343
  `SHARED_SECRET` in the process environment (your PaaS / secret
327
- manager). `baerly doctor --target=node` FAILs if
328
- `auth: "shared-secret"` is set without `SHARED_SECRET` reachable from
329
- `process.env`.
344
+ manager). The Node process fails closed if `auth: "shared-secret"`
345
+ is set without `SHARED_SECRET` reachable from `process.env`; verify
346
+ the live bucket separately with `baerly doctor --bucket=<s3-uri>`.
330
347
 
331
348
  <!-- pattern-b:end -->
332
349
  <!-- pattern-c:start -->
@@ -360,6 +377,7 @@ await baerlyNode({
360
377
  jwks: process.env["JWKS_URL"],
361
378
  issuer: process.env["JWT_ISSUER"]!,
362
379
  audience: process.env["JWT_AUDIENCE"]!,
380
+ tenantPrefix: config.tenant, // or tenantClaim: "tenant"
363
381
  }),
364
382
  }),
365
383
  }).listen(Number(process.env["PORT"] ?? 8080));
@@ -367,31 +385,38 @@ await baerlyNode({
367
385
 
368
386
  Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
369
387
  `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
370
- `JWT_AUDIENCE` and `bearerJwt` engages.
388
+ `JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
389
+ IdP issues one tenant per token; use `tenantPrefix` for single-tenant
390
+ apps or tenancy enforced outside baerly-storage.
371
391
 
372
392
  <!-- pattern-c:end -->
373
- - **Storage backend** — `src/server/index.ts` picks between
374
- `s3Storage` (AWS) and `r2Storage` (Cloudflare R2 via S3-compat)
375
- based on whether `R2_ACCOUNT_ID` is set. To use **Minio**
376
- (self-hosted dev S3) or **GCS** (HMAC keys), swap the import to
377
- `minioStorage` / `gcsStorage` from `@gusto/baerly-storage/node`. All
378
- four factories take the same shape — a single bucket-name +
379
- credentials object — and hide `aws4fetch` / `@xmldom/xmldom`
380
- behind the package boundary. JSDoc `@example` blocks for each
381
- factory are visible in your editor's TS hover. The bucket name
382
- comes from the `BUCKET` env var; AWS credentials are read from
393
+ - **Storage backend** — `src/server/index.ts` resolves storage by env:
394
+ `R2_ACCOUNT_ID` → Cloudflare R2, else `BUCKET` → AWS S3, else
395
+ zero-config `localFsStorage()` (persists to `./.baerly-data`, no
396
+ credentials, local dev only). **In a detected deployment
397
+ (`NODE_ENV=production` or a known PaaS) the server fails loud and
398
+ requires a bucket** — local-fs is single-process with no cross-process
399
+ CAS or crash durability, so it is never a production store (there is no
400
+ opt-in). AWS S3 and Cloudflare R2 are the production-supported stores;
401
+ self-hosting without a cloud bucket, run **MinIO** on the box (also the
402
+ local/dev conformance target) or graduate to SQLite + Litestream. Other S3-compatible endpoints need a
403
+ green `baerly doctor --bucket` plus owner validation; GCS S3-interop
404
+ is not supported for database use today. The bucket name comes from
405
+ the `BUCKET` env var; AWS credentials are read from
383
406
  `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (and optional
384
407
  `AWS_REGION`).
385
408
 
386
- - **Switching from static creds to EKS Pod Identity** — in
409
+ - **Switching from static creds to EKS** — in
387
410
  `src/server/index.ts`, swap `credentials: { accessKeyId,
388
- secretAccessKey }` for `credentials: fromEksPodIdentity()` and add
389
- `fromEksPodIdentity` to your import:
390
- `import { s3Storage, fromEksPodIdentity } from "@gusto/baerly-storage/node"`.
391
- The agent reads `AWS_CONTAINER_CREDENTIALS_FULL_URI` +
392
- `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` (EKS injects both). For
393
- IRSA / ECS / EC2 / other AWS contexts, see
394
- `packages/adapter-node/AGENTS.md` — pass any
411
+ secretAccessKey }` for `credentials: fromEks()` and add `fromEks`
412
+ to your import:
413
+ `import { s3Storage, fromEks } from "@gusto/baerly-storage/node"`.
414
+ `fromEks()` auto-detects the cluster's mechanism — EKS Pod Identity
415
+ (`AWS_CONTAINER_CREDENTIALS_FULL_URI` +
416
+ `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`) or IRSA (`AWS_ROLE_ARN` +
417
+ `AWS_WEB_IDENTITY_TOKEN_FILE`), both EKS-injected; to pin one, use
418
+ `fromEksPodIdentity()` or `fromWebIdentity()`. For ECS / EC2 / other
419
+ AWS contexts, see `packages/adapter-node/AGENTS.md` — pass any
395
420
  `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
396
421
  factory through the seam.
397
422
 
@@ -400,12 +425,16 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
400
425
  `node --experimental-strip-types src/server/index.ts`. Arrange the
401
426
  host to run `pnpm install && pnpm build` (populates
402
427
  `dist/client/` for the `webRoot` static-serve branch) before
403
- `pnpm start`. Set env vars from `.env.example` in the host's
404
- config — at minimum `BUCKET`, `AWS_ACCESS_KEY_ID`,
405
- `AWS_SECRET_ACCESS_KEY`. The default scaffold's `auth: "none"`
406
- needs no auth env vars; if you adopt Pattern B / C from "Going to
407
- production" above, also set `SHARED_SECRET` (Pattern B) or
408
- `JWKS_URL` + `JWT_ISSUER` + `JWT_AUDIENCE` (Pattern C).
428
+ `pnpm start`. A deployment **must** configure a durable bucket:
429
+ `BUCKET` + `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (S3) or
430
+ `R2_ACCOUNT_ID` + those creds (R2). With none set, the server fails
431
+ loud in a detected deployment (`NODE_ENV=production` or a known PaaS)
432
+ rather than running on local-fs, which is local-dev only. Self-hosting
433
+ without a cloud bucket, run MinIO on the box or use SQLite + Litestream.
434
+ The default scaffold's `auth: "none"` needs no
435
+ auth env vars; if you adopt Pattern B / C from "Going to production" above,
436
+ also set `SHARED_SECRET` (Pattern B) or `JWKS_URL` + `JWT_ISSUER` +
437
+ `JWT_AUDIENCE` (Pattern C).
409
438
 
410
439
  Shapes: **managed PaaS** (Railway, Render, DO App Platform, Fly
411
440
  without Docker, Heroku) auto-detects Node and runs the root
@@ -431,7 +460,8 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
431
460
  into the predicate so the index planner can prune
432
461
  (`db.collection("notes").where({ ... }).all()`), or maintain a
433
462
  side-projection (Postgres/SQLite/search index) populated
434
- incrementally from the `/v1/since` log feed or from a write hook —
463
+ incrementally from the `/v1/since?collection=<name>&cursor=<opaque>`
464
+ log feed or from a write hook —
435
465
  never re-scan per request.
436
466
 
437
467
  ## Maintenance
@@ -450,7 +480,7 @@ maintenance, so the published idle-reader cost bound holds.
450
480
  A bucket maintains itself as long as it takes writes. A bucket served read-only does
451
481
  not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
452
482
  graduate once a collection is large. See docs/about/graduation.md for the per-tier
453
- envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
483
+ envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
454
484
 
455
485
  Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
456
486
  your own schedule. Not required for steady-state operation.
@@ -458,28 +488,32 @@ your own schedule. Not required for steady-state operation.
458
488
 
459
489
  ## When to graduate
460
490
 
461
- baerly is designed for the small-to-medium operating point. The cost
462
- model puts the soft ceiling at:
491
+ baerly-storage is designed for the small-to-medium operating point.
492
+ The cost model puts the soft ceiling at:
463
493
 
464
- - **~30 writes / minute / collection**
465
- - **~10 GB / tenant**
466
- - **~100 collections / tenant**
494
+ - **~30 writes / minute / collection** (throughput ceiling — model/estimate)
495
+ - **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
496
+ - **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
467
497
 
468
- Past those, S3 list-prefix latency, manifest fold cost, and per-class
469
- op pricing start to dominate; you're better off on a real database.
498
+ At M-size (~30 writes/min) the projected cost is ~$26/mo on S3 (~$18/mo on R2). Past
499
+ those, per-class op pricing and fan-out scan cost start to dominate;
500
+ you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
470
501
  Pick your graduation target:
471
502
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
472
503
  - **Off-Workers or portability matters:** managed Postgres.
473
504
  - **Single-instance Node:** SQLite via Litestream.
474
505
 
475
506
  Either way, the export below is mechanical because log entries are
476
- Postgres-logical-replication-shaped — graduation is a Baerly win,
477
- not a churn event.
507
+ Debezium-style CDC change events — graduation is a baerly-storage
508
+ win, not a churn event.
478
509
 
479
- **Estimate your current rate:** `baerly admin usage --target=...`
480
- lists recent log entries per collection and computes
481
- writes/min. Warning at 50% of the ceiling; export suggestion at
482
- 100%.
510
+ **Estimate your current rate:** for Node/self-hosted buckets,
511
+ `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
512
+ --tenant=<tenant>` lists recent log entries per collection and computes
513
+ writes/min. On Cloudflare, use canonical logs for trend history and
514
+ `baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
515
+ current operation-cost projection until the usage scanner is wired to
516
+ R2 bindings.
483
517
 
484
518
  **Export when ready:** `baerly export --target=sqlite|postgres|d1
485
519
  --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
@@ -562,7 +596,8 @@ const result = useQuery(
562
596
  ```
563
597
 
564
598
  `useQuery` re-runs the callback when `deps` changes OR when the
565
- `/v1/since` long-poll batches a non-empty change for any subscribed
599
+ `/v1/since?collection=<name>&cursor=<opaque>` long-poll batches a
600
+ non-empty change for any subscribed
566
601
  collection. Idle long-poll cycles (empty batches) drop at the
567
602
  `subscription-pool` layer, so a steady-state collection costs zero list
568
603
  reads. Add a `<select>` bound to `setFilter` and the list narrows live.
@@ -630,8 +665,9 @@ JSON-merge-patch (RFC 7386) semantics apply on `update()`:
630
665
  omitting `tags` from an update preserves the existing value;
631
666
  passing `tags: null` deletes the field; passing `tags: []` sets
632
667
  it to an empty array. Note that `null` is the deletion sentinel,
633
- not a storable value — `DocumentValue` doesn't include `null`,
634
- so `find()` returns deleted fields as `undefined`, not `null`.
668
+ not a storable value — `DocumentValue` doesn't include `null`, so
669
+ subsequent `get()` / query results expose deleted optional fields as
670
+ `undefined`, not `null`.
635
671
  That's why this recipe uses `.optional()` and not `.nullable()`.
636
672
 
637
673
  ## Pointers