@gusto/create-baerly-storage 0.2.0 → 0.3.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.
@@ -45,9 +45,15 @@ WORKDIR /app
45
45
  # Distroless's `nonroot` user is UID 65532. We run as that.
46
46
  USER nonroot:nonroot
47
47
 
48
- # Copy the TS source, the SPA build, the healthcheck, the manifest,
49
- # and the prune'd node_modules.
48
+ # Copy the TS source, the project-root config, the SPA build, the
49
+ # healthcheck, the manifest, and the prune'd node_modules.
50
+ #
51
+ # baerly.config.ts is load-bearing: the server entrypoint does
52
+ # `import config from "../../baerly.config.ts"`, which resolves to the
53
+ # project root. Omit it and the container crashes on boot with an
54
+ # unresolved import.
50
55
  COPY --from=build --chown=nonroot:nonroot /app/src src
56
+ COPY --from=build --chown=nonroot:nonroot /app/baerly.config.ts baerly.config.ts
51
57
  COPY --from=build --chown=nonroot:nonroot /app/dist/client dist/client
52
58
  COPY --from=build --chown=nonroot:nonroot /app/healthcheck.js healthcheck.js
53
59
  COPY --from=build --chown=nonroot:nonroot /app/package.json package.json
@@ -74,15 +74,15 @@ read it via your editor's TS LS or via the published types).
74
74
 
75
75
  ## Verification
76
76
 
77
- | Command | What it does | Runtime |
78
- | ---------------- | --------------------------------------------------------------------------------------- | ---------------- |
79
- | `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 |
80
- | `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 |
81
- | `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`) | seconds |
82
- | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load). The minimal template ships no SPA tests by default; `--passWithNoTests` keeps the gate green until you add one. | seconds |
83
- | `pnpm dev` | Run `vite` — the Cloudflare plugin runs the Worker inside `workerd` next to the SPA dev server; same origin on :5173 | seconds to start |
84
- | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
85
- | `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
77
+ | Command | What it does | Runtime |
78
+ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
79
+ | `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 |
80
+ | `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 |
81
+ | `pnpm typecheck` | TS typecheck across the worker + web project references (`tsc -b --noEmit`) | seconds |
82
+ | `pnpm test` | `vitest run --passWithNoTests` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load). The minimal template ships no SPA tests by default; `--passWithNoTests` keeps the gate green until you add one. | seconds |
83
+ | `pnpm dev` | Run `vite` — the Cloudflare plugin runs the Worker inside `workerd` next to the SPA dev server; same origin on :5173 | seconds to start |
84
+ | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
85
+ | `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
86
86
 
87
87
  **`pnpm verify` exercises typecheck + tests only.** The dev-auth
88
88
  middleware, the SPA bundle, and any custom `/api/*` route are NOT
@@ -94,44 +94,64 @@ http://localhost:5173/<path>`) before declaring the task complete.
94
94
 
95
95
  ## Where the code is
96
96
 
97
- | Path | What it is |
98
- | -------------------------- | ------------------------------------------------------------------------------------ |
99
- | `src/server/index.ts` | Worker entry — `baerlyWorker((env) => ({ verifier }))` |
100
- | `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, assets, vars, triggers, limits, observability |
101
- | `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.ts`. |
102
- | `src/web/main.ts` | SPA client entry — 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 or replace; `client.collection<Row>(name)` is the typed surface. Workers Assets serves the built bundle from `dist/client/`. |
103
- | `vite.config.ts` | Vite + `@cloudflare/vite-plugin` — runs the Worker inside `workerd` in dev |
104
- | `tsconfig.json` | Root project-references stub |
105
- | `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib) |
106
- | `tsconfig.worker.json` | Worker TS project (`src/server/`, workerd lib) |
107
- | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
108
- | `types.ts` | Shared types between the Worker (`src/server/`) and the SPA (`src/web/`). Both project tsconfigs include this file; put any row type or interface that crosses the boundary here. |
97
+ | Path | What it is |
98
+ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
+ | `src/server/index.ts` | Worker entry — `baerlyWorker((env) => ({ verifier }))` |
100
+ | `wrangler.jsonc` | Cloudflare Worker manifest — name, R2 binding, assets, vars |
101
+ | `index.html` | SPA shell — Vite's entry point at the project root; references `/src/web/main.ts`. |
102
+ | `src/web/main.ts` | SPA client entry — 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 or replace; the `config`-bound `client.collection("notes")` is the typed surface (the generic on `.collection()` is the collection **name**, not the row type). Workers Assets serves the built bundle from `dist/client/`. |
103
+ | `vite.config.ts` | Vite + `@cloudflare/vite-plugin` — runs the Worker inside `workerd` in dev |
104
+ | `tsconfig.json` | Root project-references stub |
105
+ | `tsconfig.app.json` | Client TS project (`src/web/`, DOM lib) |
106
+ | `tsconfig.worker.json` | Worker TS project (`src/server/`, workerd lib) |
107
+ | `baerly.config.ts` | App config — `app`, `tenant`, `target`, `domain`, `collections` (schemas live here). |
108
+ | `types.ts` | Shared types between the Worker (`src/server/`) and the SPA (`src/web/`). Both project tsconfigs include this file; put any row type or interface that crosses the boundary here. |
109
109
 
110
110
  > **`baerly.config.ts` and `types.ts` are dual-included** by both
111
111
  > `tsconfig.app.json` and `tsconfig.worker.json`. Both can only
112
112
  > import from `baerly-storage`, `zod`, and other dual-included root
113
113
  > files. Paths under `src/server/` are worker-only; importing them
114
- > here triggers `TS6307: File … is not listed within the file list
115
- > of project … tsconfig.app.json`. Cross-boundary interfaces belong
116
- > in `types.ts`; re-export from a server-only file if downstream code
117
- > wants a local name.
114
+ > here triggers a `TS6307` "not listed within the file list of
115
+ > project … tsconfig.app.json" error. Cross-boundary interfaces
116
+ > belong in `types.ts`; re-export from a server-only file if
117
+ > downstream code wants a local name.
118
118
 
119
119
  ## When editing X, read Y
120
120
 
121
- - **Typed collections** — three ways to get a typed row, in DX order:
122
- 1. **Bind the config.** Declare the collection (with an optional
123
- schema) in `baerly.config.ts`, pass `config` to
124
- `createBaerlyClient({ baseUrl, config })` (or `Db.create({
125
- storage, config })`), and `client.collection("tickets")` returns
126
- `ClientCollection<Row>` with `Row` derived from the schema. No
127
- generic needed.
128
- 2. **Explicit generic, kernel constraint.** Without a declared
129
- collection, the second overload requires the row to satisfy
130
- the kernel's `DocumentData` shape (`{ [k: string]: DocumentValue }`):
121
+ - **Typed collections** — two ways to get a typed row, in DX order.
122
+ The generic on `client.collection<N>(name)` is the collection
123
+ **name** (constrained to `CollectionNames<typeof config>`), not the
124
+ row type — so don't pass a row type to it.
125
+ 1. **Bind the config.** This template's `src/web/main.ts` already
126
+ passes `config` to `createBaerlyClient({ baseUrl, config })` (and
127
+ `src/notes.test.ts` passes `config` to `Db.create`), so
128
+ `client.collection("notes")` returns `ClientCollection<Row>` with
129
+ `Row` derived from the schema declared in `baerly.config.ts`. No
130
+ generic needed. When you need to name that row type elsewhere, use
131
+ `RowOf<typeof config, "notes">` (re-exported from
132
+ `@gusto/baerly-storage`) — not a generic on `.collection()`.
133
+ 2. **Cast the handle (undeclared collection).** This template's
134
+ `client` is bound to `config`, so its names narrow to the
135
+ declared collections. To reach a collection that isn't in
136
+ `config`, build an unbound client
137
+ (`createBaerlyClient({ baseUrl })` with no `config`) — its names
138
+ widen to `string` and its row defaults to `DocumentData`. Cast at
139
+ the construction site for a narrower shape that still satisfies
140
+ the kernel's `DocumentData` constraint
141
+ (`{ [k: string]: DocumentValue }`):
131
142
  ```ts
132
- import type { DocumentData } from "@gusto/baerly-storage";
133
- interface Bookmark extends DocumentData { _id: string; url: string }
134
- await client.collection<Bookmark>("bookmarks").all();
143
+ import {
144
+ createBaerlyClient,
145
+ type ClientCollection,
146
+ type DocumentData,
147
+ } from "@gusto/baerly-storage/client";
148
+ interface Bookmark extends DocumentData {
149
+ _id: string;
150
+ url: string;
151
+ }
152
+ const raw = createBaerlyClient({ baseUrl: "" });
153
+ const bookmarks = raw.collection("bookmarks") as ClientCollection<Bookmark>;
154
+ await bookmarks.all();
135
155
  ```
136
156
  A plain `interface Bookmark { _id: string; url: string }`
137
157
  (no index signature) will fail with TS2344 — the constraint
@@ -139,9 +159,10 @@ http://localhost:5173/<path>`) before declaring the task complete.
139
159
 
140
160
  - **Writing tests** — the kernel exports `MemoryStorage`, an
141
161
  in-memory `Storage` impl that's the canonical backend for unit
142
- tests. Don't roll your own — `Db.create({ storage, app, tenant,
143
- config })` is the same boilerplate prod uses; passing
144
- `new MemoryStorage()` swaps R2 for an in-process map.
162
+ tests. Don't roll your own: the same
163
+ `Db.create({ storage, app, tenant, config })` boilerplate prod uses
164
+ also accepts a `new MemoryStorage()` that swaps R2 for an
165
+ in-process map.
145
166
 
146
167
  ```ts
147
168
  // src/notes.test.ts
@@ -170,7 +191,6 @@ http://localhost:5173/<path>`) before declaring the task complete.
170
191
 
171
192
  - **Predicates** — `db.collection("tickets").where({...}).all()`. Two
172
193
  shapes:
173
-
174
194
  - **Object literal** — equality only (top-level, dotted-path, or
175
195
  nested literal sub-predicate). Multi-field is implicit AND.
176
196
  - **Callback DSL** — `q => q.eq(...).gt(...).gte(...).lt(...).lte(...).in(...)`
@@ -185,24 +205,25 @@ http://localhost:5173/<path>`) before declaring the task complete.
185
205
  await db.collection("tickets").where({ status: "open" }).all();
186
206
 
187
207
  // Dotted-path on a nested field
188
- await db.collection("tickets")
189
- .where({ "assignee.team": "platform" })
190
- .all();
208
+ await db.collection("tickets").where({ "assignee.team": "platform" }).all();
191
209
 
192
210
  // Operator on a single field — set membership (callback form)
193
- await db.collection("tickets")
194
- .where(q => q.in("status", ["open", "pending"]))
211
+ await db
212
+ .collection("tickets")
213
+ .where((q) => q.in("status", ["open", "pending"]))
195
214
  .all();
196
215
 
197
216
  // Range — also callback form
198
- await db.collection("tickets")
199
- .where(q => q.gte("priority", 5).lt("priority", 10))
217
+ await db
218
+ .collection("tickets")
219
+ .where((q) => q.gte("priority", 5).lt("priority", 10))
200
220
  .all();
201
221
 
202
222
  // AND-merge across two .where() calls (mix shapes freely)
203
- await db.collection("tickets")
223
+ await db
224
+ .collection("tickets")
204
225
  .where({ status: "open" })
205
- .where(q => q.gte("priority", 5))
226
+ .where((q) => q.gte("priority", 5))
206
227
  .all();
207
228
  ```
208
229
 
@@ -229,8 +250,9 @@ http://localhost:5173/<path>`) before declaring the task complete.
229
250
  });
230
251
  ```
231
252
 
232
- With that declared, `db.collection("tickets").where({ status: "open"
233
- }).all()` walks `by_status` automatically. Composite indexes
253
+ With that declared, a query like
254
+ `db.collection("tickets").where({ status: "open" }).all()` walks
255
+ `by_status` automatically. Composite indexes
234
256
  (`on: ["status", "priority"]`) match any leftmost prefix.
235
257
  Mismatches (predicate doesn't cover any index) fall back to a full
236
258
  table scan with a metric bump; correctness is preserved because the
@@ -261,7 +283,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
261
283
 
262
284
  On a validation failure the server throws
263
285
  `BaerlyError{ code: "SchemaError", issues: [{ path, message }] }`;
264
- HTTP clients see a 422 with the same envelope. Validation runs
286
+ HTTP clients see a 400 with the same envelope. Validation runs
265
287
  on the post-image so `update` and `replace` see the full doc, not
266
288
  just the patch.
267
289
 
@@ -269,12 +291,12 @@ http://localhost:5173/<path>`) before declaring the task complete.
269
291
  (`db.collection(name).insert(...)`) is the canonical path; reach for `curl`
270
292
  only when debugging the wire. Mutation bodies are wrapped:
271
293
 
272
- | Route | Body | Response |
273
- | --------------------------- | ------------------- | ----------------------------- |
274
- | `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
275
- | `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
276
- | `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
277
- | `DELETE /v1/c/:collection/:id` | — | `204` |
294
+ | Route | Body | Response |
295
+ | ------------------------------ | ----------------- | ---------------- |
296
+ | `POST /v1/c/:collection` | `{"doc":{...}}` | `201 {_id}` |
297
+ | `PATCH /v1/c/:collection/:id` | `{"patch":{...}}` | `200 {modified}` |
298
+ | `PUT /v1/c/:collection/:id` | `{"doc":{...}}` | `200 {modified}` |
299
+ | `DELETE /v1/c/:collection/:id` | — | `204` |
278
300
 
279
301
  Reads (`GET /v1/c/:collection[/:id]`, `GET /v1/count?collection=…`,
280
302
  `GET /v1/since?collection=…&cursor=…`) take no body and return
@@ -289,7 +311,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
289
311
  every request resolves to `tenant: "minimal-demo"` and `Authorization`
290
312
  is ignored. The adapter reads `config.auth` to pick its verifier;
291
313
  a `verifier:` on the factory overrides it. `baerly doctor
292
- --target=cloudflare` warns on `"none"` for deploy targets. See
314
+ --target=cloudflare` warns on `"none"` for deploy targets. See
293
315
  "Going to production" below for the two production-fit recipes.
294
316
 
295
317
  ### Going to production
@@ -299,6 +321,7 @@ zero env vars. Two patterns flip to a production-fit posture; pick the
299
321
  one matching your gate.
300
322
 
301
323
  <!-- pattern-a:start -->
324
+
302
325
  **Pattern A — env-aware verifier (recommended for CF Access).** Same
303
326
  artifact ships to dev and prod; the factory `verifier:` override
304
327
  engages only when prod env vars are present. `baerlyWorker` resolves
@@ -313,7 +336,7 @@ export default defineConfig({
313
336
  app: "minimal-cloudflare",
314
337
  tenant: "minimal-demo",
315
338
  target: "cloudflare",
316
- auth: "none", // dev default
339
+ auth: "none", // dev default
317
340
  collections: { notes: {} },
318
341
  });
319
342
  ```
@@ -336,6 +359,7 @@ export default baerlyWorker<AppEnv>((env) => ({
336
359
  verifier: cloudflareAccess({
337
360
  teamDomain: env.CF_ACCESS_TEAM_DOMAIN,
338
361
  audienceTag: env.CF_ACCESS_AUDIENCE_TAG,
362
+ tenantPrefix: config.tenant,
339
363
  }),
340
364
  }),
341
365
  }));
@@ -345,12 +369,15 @@ Set both `CF_ACCESS_TEAM_DOMAIN` and `CF_ACCESS_AUDIENCE_TAG` in
345
369
  `wrangler.jsonc:vars` for prod (they're public identifiers, not
346
370
  secrets). Dev `wrangler dev` sees them as `undefined`, the spread
347
371
  short-circuits, and `config.auth: "none"` runs. Prod sees them set
348
- and `cloudflareAccess` engages.
372
+ and `cloudflareAccess` engages. Every verified token is pinned to
373
+ `config.tenant`; pass `tenantClaim` instead only when your Access JWT
374
+ actually carries a tenant claim.
349
375
 
350
376
  <!-- pattern-a:end -->
351
377
  <!-- pattern-b:start -->
378
+
352
379
  **Pattern B — `auth: "shared-secret"`.** Single-tenant
353
- server-to-server callers (CI, cron, internal services). No factory
380
+ server-to-server callers (CI and internal services). No factory
354
381
  code changes; only `baerly.config.ts` flips:
355
382
 
356
383
  ```ts
@@ -391,11 +418,13 @@ if `auth: "shared-secret"` is set without `SHARED_SECRET` reachable
391
418
  from the runtime env.
392
419
 
393
420
  <!-- pattern-b:end -->
421
+
394
422
  - **Extending the Worker with a custom route** — `baerlyWorker(...)`
395
- owns `/v1/*` + `/healthz`. For server-side endpoints the SPA
423
+ owns `/v1/*`, including `/v1/healthz`. For server-side endpoints the SPA
396
424
  client can't run on its own (the canonical case: an endpoint that
397
- needs `db.transaction(...)`, since `createBaerlyClient` is
398
- reads + by-id mutations only), wrap the worker `fetch`:
425
+ fans a write across several documents server-side, since
426
+ `createBaerlyClient` is reads + by-id mutations only), wrap the
427
+ worker `fetch`:
399
428
 
400
429
  ```ts
401
430
  // src/server/index.ts
@@ -428,10 +457,10 @@ from the runtime env.
428
457
  tenant: config.tenant,
429
458
  config,
430
459
  });
431
- // …db.transaction(...), db.collection(...).get(id), etc.
460
+ // …db.collection(...).insert(doc), db.collection(...).get(id), etc.
432
461
  return new Response(null, { status: 204 });
433
462
  }
434
- // Fall through to the baerly cascade for /v1/* + /healthz.
463
+ // Fall through to the baerly cascade for /v1/*, including /v1/healthz.
435
464
  return baerly.fetch!(req, env, ctx);
436
465
  },
437
466
  } satisfies ExportedHandler<BaerlyEnv>;
@@ -452,7 +481,7 @@ from the runtime env.
452
481
  `SHARED_SECRET` (only required if you flip `auth` to
453
482
  `"shared-secret"`) live in `.dev.vars` for local `wrangler dev`
454
483
  and behind `wrangler secret put` in production. `baerly doctor
455
- --target=cloudflare` reads `CF_ACCESS_*` from `wrangler.jsonc:vars`
484
+ --target=cloudflare` reads `CF_ACCESS_*` from `wrangler.jsonc:vars`
456
485
  only, so setting them via `wrangler secret put` would silently
457
486
  defeat the doctor check.
458
487
 
@@ -479,12 +508,14 @@ from the runtime env.
479
508
  into the predicate so the index planner can prune
480
509
  (`db.collection("notes").where({ ... }).all()`), or maintain a
481
510
  side-projection (D1/KV/search index) populated incrementally from
482
- the `/v1/since` log feed or from a write hook — never re-scan per
511
+ the `/v1/since?collection=<name>&cursor=<opaque>` log feed or from
512
+ a write hook — never re-scan per
483
513
  request.
484
514
 
485
515
  ## Maintenance
486
516
 
487
517
  <!-- pattern-d:start -->
518
+
488
519
  Maintenance is automatic and write-triggered. No cron, no sidecar, no scheduler, no
489
520
  timer, no lock, no app-config knob — identical on every host. Every write runs a
490
521
  bounded GC slice inline plus a go/no-go compaction fold bounded by a fold-size ceiling
@@ -498,10 +529,11 @@ maintenance, so the published idle-reader cost bound holds.
498
529
  A bucket maintains itself as long as it takes writes. A bucket served read-only does
499
530
  not auto-compact and pays a small, bounded replay — fine at small scale, a signal to
500
531
  graduate once a collection is large. See docs/about/graduation.md for the per-tier
501
- envelope and the BAERLY_MAINTENANCE_* operator env vars (you almost never need them).
532
+ envelope and the `BAERLY_MAINTENANCE_*` operator env vars (you almost never need them).
502
533
 
503
534
  Operator opt-in: call runScheduledMaintenance from @gusto/baerly-storage/maintenance on
504
535
  your own schedule. Not required for steady-state operation.
536
+
505
537
  <!-- pattern-d:end -->
506
538
 
507
539
  ## When to graduate
@@ -513,21 +545,25 @@ model puts the soft ceiling at:
513
545
  - **~10 GB / tenant**
514
546
  - **~100 collections / tenant**
515
547
 
516
- Past those, S3 list-prefix latency, manifest fold cost, and per-class
548
+ Past those, S3 list-prefix latency, snapshot fold cost, and per-class
517
549
  op pricing start to dominate; you're better off on a real database.
518
550
  Pick your graduation target:
551
+
519
552
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
520
553
  - **Off-Workers or portability matters:** managed Postgres.
521
554
  - **Single-instance Node:** SQLite via Litestream.
522
555
 
523
556
  Either way, the export below is mechanical because log entries are
524
- Postgres-logical-replication-shaped — graduation is a Baerly win,
557
+ Debezium-style CDC change events — graduation is a Baerly win,
525
558
  not a churn event.
526
559
 
527
- **Estimate your current rate:** `baerly admin usage --target=...`
528
- lists recent log entries per collection and computes
529
- writes/min. Warning at 50% of the ceiling; export suggestion at
530
- 100%.
560
+ **Estimate your current rate:** for Node/self-hosted buckets,
561
+ `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
562
+ --tenant=<tenant>` lists recent log entries per collection and computes
563
+ writes/min. On Cloudflare, use canonical logs for trend history and
564
+ `baerly cost --bucket=<bucket-uri> --collection=<collection>` for the
565
+ current operation-cost projection until the usage scanner is wired to
566
+ R2 bindings.
531
567
 
532
568
  **Export when ready:** `baerly export --target=sqlite|postgres|d1
533
569
  --bucket=<...> --app=<...> --tenant=<...> --collection=<...>` writes a
@@ -542,6 +578,6 @@ The export is point-in-time and honours the active schema. Flags:
542
578
 
543
579
  - `baerly.config.ts` — app config.
544
580
  - `src/server/index.ts` — Worker entry.
545
- - `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars, cron, observability).
581
+ - `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars).
546
582
  - `vite.config.ts` — Vite + `@cloudflare/vite-plugin`.
547
583
  - `package.json` — root scripts + dependencies.
@@ -7,6 +7,8 @@ day-1 happy path works with zero env vars; flip to Cloudflare
7
7
  Access or a shared secret before deploy — see "Going to
8
8
  production" below.
9
9
 
10
+ **The only persistent component is your R2 bucket** — there is no Worker to keep warm, no database daemon to operate, no idle bill, and maintenance is automatic and write-triggered (no cron, no sidecar, no scheduler).
11
+
10
12
  ## What you got
11
13
 
12
14
  ```
@@ -16,7 +18,7 @@ minimal-cloudflare/
16
18
  ├── tsconfig.app.json # client TS project (src/web)
17
19
  ├── tsconfig.worker.json # Worker TS project (src/server)
18
20
  ├── vite.config.ts # Vite + @cloudflare/vite-plugin
19
- ├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars, triggers, limits, observability
21
+ ├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
20
22
  ├── index.html # SPA shell — Vite's entry point
21
23
  ├── baerly.config.ts # app, tenant, target, domain
22
24
  ├── AGENTS.md # deeper guide: predicates, schemas,
@@ -61,7 +63,7 @@ references.
61
63
  # `wrangler r2 bucket create` + `wrangler deploy`.
62
64
  baerly deploy
63
65
 
64
- # Verify the deployed config — bindings, secrets, cron triggers.
66
+ # Verify the deployed config — bindings, secrets, optional triggers.
65
67
  baerly doctor --target=cloudflare
66
68
  ```
67
69
 
@@ -91,23 +93,28 @@ needs no secrets. If you adopt a "Going to production" recipe:
91
93
  ## Next steps
92
94
 
93
95
  1. **Read `AGENTS.md`** for the agent-facing guide — predicates,
94
- indexes, schemas, auth recipes, the maintenance cron, and the
96
+ indexes, schemas, auth recipes, write-triggered maintenance, and the
95
97
  graduation criteria. Codex CLI reads `AGENTS.md`; Claude Code
96
98
  reads `CLAUDE.md`; both files are byte-identical so either
97
99
  surface lands you the same context.
98
100
  2. **Declare your first collection schema** in `baerly.config.ts`
99
101
  via `defineConfig({ collections: { ... } })` and pass it to
100
102
  `Db.create({ ..., collections })`. Schema validation is live;
101
- bad inserts return 422.
103
+ bad inserts return 400.
102
104
  3. **Set up production auth** — follow `AGENTS.md` → "Going to
103
105
  production". Pattern A wires CF Access via an env-aware factory
104
106
  `verifier:` override; Pattern B flips `auth: "shared-secret"`.
105
107
  `baerly doctor --target=cloudflare` reports any gaps.
106
- 4. **Check usage trends** — run `baerly doctor --target=cloudflare
107
- --usage` periodically. It estimates your current writes/minute
108
- per collection from recent log entries and warns when you're
109
- approaching the graduation ceiling described in the "When to
110
- graduate" section below.
108
+ 4. **Check usage trends** — run the current operation-cost
109
+ projection:
110
+
111
+ ```sh
112
+ baerly cost --bucket=<bucket-uri> --collection=<collection-name>
113
+ ```
114
+
115
+ Then pipe canonical logs to your observability system for 7-day /
116
+ 30-day write-rate trends. The graduation ceiling is described in
117
+ the "When to graduate" section below.
111
118
 
112
119
  ## When to graduate
113
120
 
@@ -120,8 +127,7 @@ start to dominate, and you're better off on a real database:
120
127
  - **~100 collections / tenant**
121
128
 
122
129
  When you cross the soft ceiling, graduation is mechanical:
123
- `baerly export --target=postgres` walks your log entries (already
124
- Postgres-logical-replication-shaped) into a real DB. If your
130
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
125
131
  deploy target is Cloudflare Workers and you'll accept Cloudflare
126
132
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
127
133
  per-write at M-size and is a natural next step. If you're on
@@ -134,7 +140,7 @@ not a churn event.
134
140
 
135
141
  ```sh
136
142
  baerly export --target=postgres \
137
- --bucket=minimal-cloudflare --app=minimal-cloudflare --tenant=<your-tenant> \
143
+ --bucket=s3://minimal-cloudflare --app=minimal-cloudflare --tenant=<your-tenant> \
138
144
  --collection=<collection-name> --output=./out.sql
139
145
  ```
140
146
 
@@ -155,7 +161,8 @@ Before deploy, follow `AGENTS.md` → "Going to production":
155
161
  `wrangler.jsonc:vars`. The `cloudflareAccess()` preset
156
162
  (re-exported from `@gusto/baerly-storage/auth`) reads the JWT off
157
163
  `Cf-Access-Jwt-Assertion`, validates it against your team's JWKS,
158
- and derives `tenantPrefix` from the email claim.
164
+ and pins `tenantPrefix` to `config.tenant` unless you pass an
165
+ explicit tenant claim.
159
166
  - **Pattern B — `auth: "shared-secret"`.** Single-tenant
160
167
  server-to-server callers. Flip `auth` in `baerly.config.ts` and
161
168
  set `SHARED_SECRET` via `wrangler secret put`.
@@ -163,7 +170,7 @@ Before deploy, follow `AGENTS.md` → "Going to production":
163
170
  ## Pointers
164
171
 
165
172
  - `baerly.config.ts` — app config (`app`, `tenant`, `target`, `domain`).
166
- - `src/server/index.ts` — Worker fetch + scheduled handler.
167
- - `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars, cron, observability).
173
+ - `src/server/index.ts` — Worker fetch entry.
174
+ - `wrangler.jsonc` — Cloudflare Worker manifest (R2 binding, `assets:`, vars).
168
175
  - `vite.config.ts` — Vite + `@cloudflare/vite-plugin`.
169
176
  - `AGENTS.md` / `CLAUDE.md` — agent-facing guide (byte-identical).
@@ -15,14 +15,14 @@
15
15
  "@gusto/baerly-storage": "workspace:*"
16
16
  },
17
17
  "devDependencies": {
18
- "@cloudflare/vite-plugin": "^1.39.0",
18
+ "@cloudflare/vite-plugin": "^1.40.1",
19
19
  "@cloudflare/workers-types": "^4",
20
- "@types/node": "^24.0.0",
21
- "happy-dom": "^20.9.0",
20
+ "@types/node": "^25.9.2",
21
+ "happy-dom": "^20.10.2",
22
22
  "typescript": "^6.0.3",
23
- "vite": "^8.0.14",
24
- "vitest": "^4.1.7",
25
- "wrangler": "^4.95.0"
23
+ "vite": "^8.0.16",
24
+ "vitest": "^4.1.8",
25
+ "wrangler": "^4.99.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",