@gusto/create-baerly-storage 0.3.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.
@@ -1,16 +1,17 @@
1
1
  ---
2
2
  title: AGENTS.md — agent guidance for minimal-cloudflare
3
3
  audience: agent
4
- summary: How to develop and deploy minimal-cloudflare, a baerly app.
5
- tags: [agent-entry, baerly]
4
+ summary: How to develop and deploy minimal-cloudflare, 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,30 +38,31 @@ 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-cloudflare` is a baerly app scaffolded with `create-baerly-storage`.
43
- The Worker-side server lives in `src/server/`; the optional client
44
- lives in `src/web/`. Configuration lives in `baerly.config.ts`.
44
+ `minimal-cloudflare` is a baerly-storage app scaffolded with
45
+ `create-baerly-storage`. The Worker-side server lives in `src/server/`;
46
+ the optional client lives in `src/web/`. Configuration lives in
47
+ `baerly.config.ts`.
45
48
 
46
49
  Single package, single `vite` process: `@cloudflare/vite-plugin` runs
47
50
  the Worker inside `workerd` alongside the SPA dev server, and
48
51
  `wrangler.jsonc:assets` ships the built `dist/client/` bundle next to
49
52
  the Worker on deploy. Same origin in dev and prod, one deploy.
50
53
 
51
- Public API docs: https://docs.baerly.dev/ (the JSDoc on
52
- `baerly-storage`'s `Db` and `Collection` is the canonical reference;
53
- read it via your editor's TS LS or via the published types).
54
+ Public API docs: the JSDoc on `baerly-storage`'s `Db` and `Collection`
55
+ is the canonical reference; read it via your editor's TS LS, the
56
+ published types, or `node_modules/@gusto/baerly-storage/dist/API.md`.
54
57
 
55
58
  ## Toolchain
56
59
 
57
60
  - **Package manager:** pnpm. The emitted repo pins
58
61
  `packageManager: pnpm@11.1.2`.
59
62
  - **Test runner:** vitest.
60
- - **Type checker:** TypeScript 5.6+. (The baerly-storage monorepo
61
- itself uses TypeScript 7 via `@typescript/native-preview`; this
62
- template tracks the broadly-compatible TS major so scaffolded
63
- apps work with the wider ecosystem.)
63
+ - **Type checker:** TypeScript 6.x, as pinned in `package.json`.
64
+ (The baerly-storage monorepo itself uses TypeScript 7 via
65
+ `@typescript/native-preview`.)
64
66
  - **`erasableSyntaxOnly`** is enabled in every `tsconfig*.json` so the
65
67
  code stays compatible with type-stripping runtimes (Node's
66
68
  `--experimental-strip-types`, esbuild's strip path). The flag bans
@@ -79,7 +81,7 @@ read it via your editor's TS LS or via the published types).
79
81
  | `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
82
  | `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
83
  | `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 |
84
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env, ignores `vite.config.ts` so the Cloudflare plugin doesn't load). The template ships `src/notes.test.ts` by default. | seconds |
83
85
  | `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
86
  | `pnpm build` | `tsc -b && vite build` — emits `dist/client/` for the Workers Assets binding | seconds |
85
87
  | `pnpm deploy` | `wrangler deploy` — ships Worker + assets in one shipment (auto-creates R2 on first run via `--x-provision`) | seconds |
@@ -304,7 +306,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
304
306
  (without the `doc` wrapper) returns
305
307
  `400 SchemaError "Request body must be { doc: object }"` — the
306
308
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
307
- reference: the `Routes` type and the JSDoc on `createRouter` in
309
+ reference: the JSDoc on `createRouter` in
308
310
  `baerly-storage`.
309
311
 
310
312
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
@@ -538,15 +540,16 @@ your own schedule. Not required for steady-state operation.
538
540
 
539
541
  ## When to graduate
540
542
 
541
- baerly is designed for the small-to-medium operating point. The cost
542
- model puts the soft ceiling at:
543
+ baerly-storage is designed for the small-to-medium operating point.
544
+ The cost model puts the soft ceiling at:
543
545
 
544
- - **~30 writes / minute / collection**
545
- - **~10 GB / tenant**
546
- - **~100 collections / tenant**
546
+ - **~30 writes / minute / collection** (throughput ceiling — model/estimate)
547
+ - **>10 GB / tenant stored** (R2 free-tier storage line — a cost signal, not a protocol ceiling)
548
+ - **~100 collections / tenant** (soft fan-out guideline — bench-grounded linear cost)
547
549
 
548
- Past those, S3 list-prefix latency, snapshot fold cost, and per-class
549
- op pricing start to dominate; you're better off on a real database.
550
+ At M-size (~30 writes/min) the projected cost is ~$18/mo on R2. Past
551
+ those, per-class op pricing and fan-out scan cost start to dominate;
552
+ you've outgrown the workload envelope — move to a database service (D1 / Postgres) suited to higher scale.
550
553
  Pick your graduation target:
551
554
 
552
555
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
@@ -554,8 +557,8 @@ Pick your graduation target:
554
557
  - **Single-instance Node:** SQLite via Litestream.
555
558
 
556
559
  Either way, the export below is mechanical because log entries are
557
- Debezium-style CDC change events — graduation is a Baerly win,
558
- not a churn event.
560
+ Debezium-style CDC change events — graduation is a baerly-storage
561
+ win, not a churn event.
559
562
 
560
563
  **Estimate your current rate:** for Node/self-hosted buckets,
561
564
  `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>
@@ -1,13 +1,16 @@
1
1
  # minimal-cloudflare
2
2
 
3
- A baerly app scaffolded with `@gusto/create-baerly-storage` for the **Cloudflare
4
- Workers** target. Single-bucket R2-backed deployment via the
5
- `@gusto/baerly-storage/cloudflare` adapter. Ships `auth: "none"` so the
6
- day-1 happy path works with zero env vars; flip to Cloudflare
7
- Access or a shared secret before deploy — see "Going to
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for
4
+ the **Cloudflare Workers** target. Single-bucket R2-backed deployment
5
+ via the `@gusto/baerly-storage/cloudflare` adapter. Ships
6
+ `auth: "none"` so the day-1 happy path works with zero env vars; flip
7
+ to Cloudflare 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).
10
+ **The R2 bucket is the durable state.** The Worker is trusted app code
11
+ with an R2 binding; it applies the baerly-storage protocol, but it is
12
+ not a database server. No daemon, lock table, scheduler, or idle
13
+ database bill; maintenance is automatic and write-triggered.
11
14
 
12
15
  ## What you got
13
16
 
@@ -86,9 +89,9 @@ needs no secrets. If you adopt a "Going to production" recipe:
86
89
  `CF_ACCESS_AUDIENCE_TAG` go in `wrangler.jsonc:vars` (they're
87
90
  public identifiers, not secrets).
88
91
  - **Pattern B (`auth: "shared-secret"`):** `SHARED_SECRET` is a
89
- secret — `.dev.vars` for `wrangler dev`, `wrangler secret put
90
- SHARED_SECRET` for production. Each secret is encrypted at rest
91
- and exposed on `env` at runtime.
92
+ secret — use `.dev.vars` for `wrangler dev` and
93
+ `wrangler secret put SHARED_SECRET` for production. Each secret is
94
+ encrypted at rest and exposed on `env` at runtime.
92
95
 
93
96
  ## Next steps
94
97
 
@@ -98,9 +101,9 @@ needs no secrets. If you adopt a "Going to production" recipe:
98
101
  reads `CLAUDE.md`; both files are byte-identical so either
99
102
  surface lands you the same context.
100
103
  2. **Declare your first collection schema** in `baerly.config.ts`
101
- via `defineConfig({ collections: { ... } })` and pass it to
102
- `Db.create({ ..., collections })`. Schema validation is live;
103
- bad inserts return 400.
104
+ via `defineConfig({ collections: { ... } })`. The Worker adapter
105
+ passes that config to `Db.create({ storage, app, tenant, config })`,
106
+ so schema validation is live and bad inserts return 400.
104
107
  3. **Set up production auth** — follow `AGENTS.md` → "Going to
105
108
  production". Pattern A wires CF Access via an env-aware factory
106
109
  `verifier:` override; Pattern B flips `auth: "shared-secret"`.
@@ -118,16 +121,16 @@ needs no secrets. If you adopt a "Going to production" recipe:
118
121
 
119
122
  ## When to graduate
120
123
 
121
- baerly is designed for the small-to-medium operating point. Past these
122
- thresholds, S3 list-prefix latency and per-class operation pricing
123
- start to dominate, and you're better off on a real database:
124
+ baerly-storage is designed for the small-to-medium operating point.
125
+ Past these thresholds, S3 list-prefix latency and per-class operation
126
+ pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
124
127
 
125
- - **~30 writes / minute / collection**
126
- - **~10 GB / tenant**
127
- - **~100 collections / tenant**
128
+ - **~30 writes / minute / collection** — per-collection throughput estimate (CAS-livelock model)
129
+ - **>10 GB / tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
130
+ - **~100 collections / tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
128
131
 
129
- When you cross the soft ceiling, graduation is mechanical:
130
- `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a real DB. If your
132
+ When you cross these signals, graduation is mechanical:
133
+ `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your
131
134
  deploy target is Cloudflare Workers and you'll accept Cloudflare
132
135
  lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
133
136
  per-write at M-size and is a natural next step. If you're on
@@ -135,7 +138,7 @@ AWS, on-prem, or want your data portable, managed Postgres is
135
138
  the typical destination. Either way — graduation is a Baerly win,
136
139
  not a churn event.
137
140
 
138
- **Export to a real database** (swap `--target=` for `sqlite`,
141
+ **Export to a database service** (swap `--target=` for `sqlite`,
139
142
  `postgres`, or `d1`):
140
143
 
141
144
  ```sh
@@ -15,14 +15,14 @@
15
15
  "@gusto/baerly-storage": "workspace:*"
16
16
  },
17
17
  "devDependencies": {
18
- "@cloudflare/vite-plugin": "^1.40.1",
19
- "@cloudflare/workers-types": "^4",
20
- "@types/node": "^25.9.2",
21
- "happy-dom": "^20.10.2",
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.16",
24
- "vitest": "^4.1.8",
25
- "wrangler": "^4.99.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
  }
@@ -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
@@ -90,10 +92,10 @@ read it via your editor's TS LS or via the published types).
90
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 |
91
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 |
92
94
  | `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 |
95
+ | `pnpm test` | `vitest run` — standalone `vitest.config.ts` (Node env). The template ships `src/notes.test.ts` by default. | seconds |
94
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 |
95
97
  | `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 |
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
@@ -107,7 +109,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
107
109
 
108
110
  | Path | What it is |
109
111
  | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
- | `src/server/index.ts` | Server entry — composes `s3Storage` / `r2Storage` + a verifier and calls `baerlyNode({ ... }).listen(PORT)` |
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)` |
111
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). |
112
114
  | `vite.config.ts` | Vite client build — `outDir: dist/client`; `baerlyDev()` mounts the Node listener as middleware so SPA + `/v1/*` share `:5173` in dev |
113
115
  | `tsconfig.{app,server}.json` | TS project references for the client and server projects |
@@ -273,7 +275,7 @@ http://localhost:5173/<path>`) before declaring the task complete.
273
275
  (without the `doc` wrapper) returns
274
276
  `400 SchemaError "Request body must be { doc: object }"` — the
275
277
  wording is locked by `assertJsonBodyField` in the kernel. Canonical
276
- reference: the `Routes` type and the JSDoc on `createRouter` in
278
+ reference: the JSDoc on `createRouter` in
277
279
  `baerly-storage`.
278
280
 
279
281
  - **Auth** — your scaffold ships `auth: "none"` in `baerly.config.ts`:
@@ -350,29 +352,35 @@ Dev sees `JWKS_URL` as `undefined`, spread short-circuits, and
350
352
  `config.auth: "none"` runs. Prod sets `JWKS_URL` + `JWT_ISSUER` +
351
353
  `JWT_AUDIENCE` and `bearerJwt` engages. Use `tenantClaim` when your
352
354
  IdP issues one tenant per token; use `tenantPrefix` for single-tenant
353
- apps or tenancy enforced outside Baerly.
355
+ apps or tenancy enforced outside baerly-storage.
354
356
 
355
357
  <!-- pattern-c:end -->
356
358
 
357
- - **Storage backend** — `src/server/index.ts` picks between
358
- `s3Storage` (AWS) and `r2Storage` (Cloudflare R2) based on whether
359
- `R2_ACCOUNT_ID` is set. To use **Minio** (self-hosted dev S3) or
360
- **GCS** (HMAC keys), swap the import to `minioStorage` /
361
- `gcsStorage` from `@gusto/baerly-storage/node`. All four factories take
362
- the same shape — a single bucket-name + credentials object — and
363
- hide `aws4fetch` / `@xmldom/xmldom` behind the package boundary.
364
- JSDoc `@example` blocks for each factory are visible in your
365
- editor's TS hover.
366
-
367
- - **Switching from static creds to EKS Pod Identity** — in
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
368
374
  `src/server/index.ts`, swap `credentials: { accessKeyId,
369
- secretAccessKey }` for `credentials: fromEksPodIdentity()` and add
370
- `fromEksPodIdentity` to your import:
371
- `import { s3Storage, fromEksPodIdentity } from "@gusto/baerly-storage/node"`.
372
- The agent reads `AWS_CONTAINER_CREDENTIALS_FULL_URI` +
373
- `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` (EKS injects both). For
374
- IRSA / ECS / EC2 / other AWS contexts, see
375
- `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
376
384
  `() => Promise<Credentials>` or an `@aws-sdk/credential-providers`
377
385
  factory through the seam.
378
386
 
@@ -438,15 +446,16 @@ your own schedule. Not required for steady-state operation.
438
446
 
439
447
  ## When to graduate
440
448
 
441
- baerly is designed for the small-to-medium operating point. The cost
442
- 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:
443
451
 
444
- - **~30 writes / minute / collection**
445
- - **~10 GB / tenant**
446
- - **~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)
447
455
 
448
- Past those, S3 list-prefix latency, snapshot fold cost, and per-class
449
- 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.
450
459
  Pick your graduation target:
451
460
 
452
461
  - **Cloudflare Workers + lock-in OK:** [D1](https://developers.cloudflare.com/d1/) — cheaper per-write at M-size.
@@ -454,8 +463,8 @@ Pick your graduation target:
454
463
  - **Single-instance Node:** SQLite via Litestream.
455
464
 
456
465
  Either way, the export below is mechanical because log entries are
457
- Debezium-style CDC change events — graduation is a Baerly win,
458
- not a churn event.
466
+ Debezium-style CDC change events — graduation is a baerly-storage
467
+ win, not a churn event.
459
468
 
460
469
  **Estimate your current rate:** for Node/self-hosted buckets,
461
470
  `baerly admin usage --target=node --bucket=<bucket-uri> --app=<app>