@gusto/create-baerly-storage 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/dist/THIRD-PARTY-LICENSES.txt +204 -0
  2. package/dist/index.js +1537 -145
  3. package/dist/index.js.map +1 -1
  4. package/dist/templates/addons/docker/Dockerfile +13 -11
  5. package/dist/templates/minimal-cloudflare/AGENTS.md +77 -399
  6. package/dist/templates/minimal-cloudflare/README.md +33 -97
  7. package/dist/templates/minimal-cloudflare/package.json +12 -9
  8. package/dist/templates/minimal-cloudflare/pnpm-workspace.yaml +13 -7
  9. package/dist/templates/minimal-cloudflare/tsconfig.app.json +2 -3
  10. package/dist/templates/minimal-cloudflare/tsconfig.worker.json +2 -3
  11. package/dist/templates/minimal-cloudflare/vitest.config.ts +1 -1
  12. package/dist/templates/minimal-cloudflare/wrangler.jsonc +4 -2
  13. package/dist/templates/minimal-node/AGENTS.md +80 -380
  14. package/dist/templates/minimal-node/README.md +37 -135
  15. package/dist/templates/minimal-node/package.json +11 -9
  16. package/dist/templates/minimal-node/pnpm-workspace.yaml +14 -9
  17. package/dist/templates/minimal-node/tsconfig.app.json +2 -3
  18. package/dist/templates/minimal-node/tsconfig.server.json +2 -3
  19. package/dist/templates/react-cloudflare/AGENTS.md +101 -444
  20. package/dist/templates/react-cloudflare/README.md +14 -54
  21. package/dist/templates/react-cloudflare/package.json +18 -15
  22. package/dist/templates/react-cloudflare/pnpm-workspace.yaml +13 -7
  23. package/dist/templates/react-cloudflare/tsconfig.app.json +2 -3
  24. package/dist/templates/react-cloudflare/tsconfig.worker.json +2 -3
  25. package/dist/templates/react-cloudflare/vitest.config.ts +1 -1
  26. package/dist/templates/react-cloudflare/wrangler.jsonc +4 -2
  27. package/dist/templates/react-node/AGENTS.md +108 -474
  28. package/dist/templates/react-node/README.md +35 -125
  29. package/dist/templates/react-node/package.json +16 -14
  30. package/dist/templates/react-node/pnpm-workspace.yaml +14 -9
  31. package/dist/templates/react-node/tsconfig.app.json +2 -3
  32. package/dist/templates/react-node/tsconfig.server.json +2 -3
  33. package/package.json +7 -7
  34. package/dist/templates/minimal-cloudflare/uint8array-base64.d.ts +0 -16
  35. package/dist/templates/minimal-node/uint8array-base64.d.ts +0 -16
  36. package/dist/templates/react-cloudflare/uint8array-base64.d.ts +0 -16
  37. package/dist/templates/react-node/uint8array-base64.d.ts +0 -16
@@ -1,20 +1,12 @@
1
1
  # minimal-cloudflare
2
2
 
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
- production" below.
9
-
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.
3
+ A baerly-storage app scaffolded with `@gusto/create-baerly-storage` for the **Cloudflare Workers** target. Single-bucket R2-backed deployment via the `@gusto/baerly-storage/cloudflare` adapter. Ships `auth: "none"` so the day-1 happy path works with zero env vars; flip to Cloudflare Access or a shared secret before deploy — see "Going to production" below.
4
+
5
+ **The R2 bucket is the durable state.** The Worker is trusted app code with an R2 binding; it applies the baerly-storage protocol, but it is not a database server. No daemon, lock table, scheduler, or idle database bill; maintenance is automatic and write-triggered.
14
6
 
15
7
  ## What you got
16
8
 
17
- ```
9
+ ```text
18
10
  minimal-cloudflare/
19
11
  ├── package.json # one package, all deps
20
12
  ├── tsconfig.json # project-references stub
@@ -24,7 +16,7 @@ minimal-cloudflare/
24
16
  ├── wrangler.jsonc # Worker manifest — R2 binding, assets, vars
25
17
  ├── index.html # SPA shell — Vite's entry point
26
18
  ├── baerly.config.ts # app, tenant, target, domain
27
- ├── AGENTS.md # deeper guide: predicates, schemas,
19
+ ├── AGENTS.md # deeper guide: where the API docs are,
28
20
  │ # auth recipes, graduation (Codex CLI)
29
21
  ├── CLAUDE.md # same content (Claude Code reads this)
30
22
  ├── src/
@@ -42,104 +34,62 @@ pnpm install
42
34
  pnpm dev
43
35
  ```
44
36
 
45
- `pnpm dev` runs `vite`. The `@cloudflare/vite-plugin` runs your Worker
46
- inside `workerd` next to the SPA dev server, so `GET /` hits the SPA
47
- on `http://localhost:5173/` and anything the Worker handles
48
- (e.g. `GET /v1/healthz`) is served on the same origin. First run
49
- downloads the `workerd` binary.
37
+ `pnpm dev` runs `vite`. The `@cloudflare/vite-plugin` runs your Worker inside `workerd` next to the SPA dev server, so `GET /` hits the SPA on `http://localhost:5173/` and anything the Worker handles (e.g. `GET /v1/healthz`) is served on the same origin. First run downloads the `workerd` binary.
50
38
 
51
- `pnpm build` runs `tsc -b && vite build`; the SPA lands in
52
- `dist/client/` for the `assets:` binding in `wrangler.jsonc` to ingest
53
- on deploy.
39
+ `pnpm build` runs `tsc -b && vite build`; the SPA lands in `dist/client/` for the `assets:` binding in `wrangler.jsonc` to ingest on deploy.
54
40
 
55
- `pnpm typecheck` runs `tsc -b --noEmit` across both TS project
56
- references.
41
+ `pnpm typecheck` runs `tsc -b --noEmit` across both TS project references.
57
42
 
58
43
  ## Deploy
59
44
 
60
45
  ```sh
61
46
  # One-command deploy. baerly reads `baerly.config.ts:target`, finds
62
47
  # `wrangler.jsonc`, and runs:
63
- # wrangler deploy --x-provision --x-auto-create
64
- # which auto-creates the declared R2 bucket(s) before the deploy.
65
- # When the experimental flag is unavailable, baerly falls back to
66
- # `wrangler r2 bucket create` + `wrangler deploy`.
48
+ # wrangler r2 bucket create (only for declared buckets that don't exist)
49
+ # wrangler deploy
67
50
  baerly deploy
68
51
 
69
52
  # Verify the deployed config — bindings, secrets, optional triggers.
70
53
  baerly doctor --target=cloudflare
71
54
  ```
72
55
 
73
- `baerly doctor --target=cloudflare` warns on `auth: "none"` for
74
- deploy targets — see "Going to production" below to flip the
75
- posture before shipping.
56
+ `baerly doctor --target=cloudflare` warns on `auth: "none"` for deploy targets — see "Going to production" below to flip the posture before shipping.
76
57
 
77
- If you'd rather run the steps by hand: `pnpm build` → `wrangler r2
78
- bucket create minimal-cloudflare` → `wrangler deploy` from this
79
- directory. The `assets:` binding in `wrangler.jsonc` picks up
80
- `dist/client/` automatically.
58
+ If you'd rather run the steps by hand: `pnpm build` → `wrangler r2 bucket create minimal-cloudflare` → `wrangler deploy` from this directory. The `assets:` binding in `wrangler.jsonc` picks up `dist/client/` automatically.
81
59
 
82
60
  ## Secrets
83
61
 
84
- Public configuration (`APP`, `TENANT`) lives in
85
- `wrangler.jsonc:vars`. The default `auth: "none"` posture
86
- needs no secrets. If you adopt a "Going to production" recipe:
62
+ Public configuration (`APP`, `TENANT`) lives in `wrangler.jsonc:vars`. The default `auth: "none"` posture needs no secrets. If you adopt a "Going to production" recipe:
87
63
 
88
- - **Pattern A (CF Access):** `CF_ACCESS_TEAM_DOMAIN` +
89
- `CF_ACCESS_AUDIENCE_TAG` go in `wrangler.jsonc:vars` (they're
90
- public identifiers, not secrets).
91
- - **Pattern B (`auth: "shared-secret"`):** `SHARED_SECRET` is a
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.
64
+ - **Pattern A (CF Access):** `CF_ACCESS_TEAM_DOMAIN` + `CF_ACCESS_AUDIENCE_TAG` go in `wrangler.jsonc:vars` (they're public identifiers, not secrets).
65
+ - **Pattern B (`auth: "shared-secret"`):** `SHARED_SECRET` is a secret — use `.dev.vars` for `wrangler dev` and `wrangler secret put SHARED_SECRET` for production. Each secret is encrypted at rest and exposed on `env` at runtime.
95
66
 
96
67
  ## Next steps
97
68
 
98
- 1. **Read `AGENTS.md`** for the agent-facing guide — predicates,
99
- indexes, schemas, auth recipes, write-triggered maintenance, and the
100
- graduation criteria. Codex CLI reads `AGENTS.md`; Claude Code
101
- reads `CLAUDE.md`; both files are byte-identical so either
102
- surface lands you the same context.
103
- 2. **Declare your first collection schema** in `baerly.config.ts`
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.
107
- 3. **Set up production auth** — follow `AGENTS.md` → "Going to
108
- production". Pattern A wires CF Access via an env-aware factory
109
- `verifier:` override; Pattern B flips `auth: "shared-secret"`.
110
- `baerly doctor --target=cloudflare` reports any gaps.
111
- 4. **Check usage trends** — run the current operation-cost
112
- projection:
69
+ 1. **Read `AGENTS.md`** for the agent-facing guide — pointers to the installed API docs (predicates, indexes, schemas), auth recipes, write-triggered maintenance, and the graduation criteria. Codex CLI reads `AGENTS.md`; Claude Code reads `CLAUDE.md`; both files are byte-identical so either surface lands you the same context.
70
+ 2. **Declare your first collection schema** in `baerly.config.ts` via `defineConfig({ collections: { ... } })`. The Worker adapter passes that config to `Db.create({ storage, app, tenant, config })`, so schema validation is live and bad inserts return 400.
71
+ 3. **Set up production auth** — follow `AGENTS.md` → "Going to production". Pattern A wires CF Access via an env-aware factory `verifier:` override; Pattern B flips `auth: "shared-secret"`. `baerly doctor --target=cloudflare` reports any gaps.
72
+ 4. **Check usage trends** — run the current operation-cost projection:
113
73
 
114
74
  ```sh
115
75
  baerly cost --bucket=<bucket-uri> --collection=<collection-name>
116
76
  ```
117
77
 
118
- Then pipe canonical logs to your observability system for 7-day /
119
- 30-day write-rate trends. The graduation ceiling is described in
120
- the "When to graduate" section below.
78
+ Then pipe canonical logs to your observability system for 7-day / 30-day write-rate trends. The graduation ceiling is described in the "When to graduate" section below.
121
79
 
122
80
  ## When to graduate
123
81
 
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:
82
+ baerly-storage is designed for the small-to-medium operating point. Past these thresholds, S3 list-prefix latency and per-class operation pricing starts to dominate, and you've outgrown the workload envelope — move to a database service:
127
83
 
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)
84
+ - **Writes per collection** — per-collection throughput estimate (CAS-livelock model)
85
+ - **Stored bytes per tenant** — R2 free-tier storage cost line (a billing signal, not a protocol ceiling)
86
+ - **Collections per tenant** — soft fan-out guideline (linear cost, bench-grounded; nothing enforces it)
131
87
 
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
134
- deploy target is Cloudflare Workers and you'll accept Cloudflare
135
- lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper
136
- per-write at M-size and is a natural next step. If you're on
137
- AWS, on-prem, or want your data portable, managed Postgres is
138
- the typical destination. Either way — graduation is a Baerly win,
139
- not a churn event.
88
+ The figures for each line live in docs/spec/scale-ceilings.md § "The published envelope" in the baerly-storage repo.
140
89
 
141
- **Export to a database service** (swap `--target=` for `sqlite`,
142
- `postgres`, or `d1`):
90
+ When you cross these signals, graduation is mechanical: `baerly export --target=postgres` walks your log entries (already Debezium-style CDC change events) into a database service. If your deploy target is Cloudflare Workers and you'll accept Cloudflare lock-in, [D1](https://developers.cloudflare.com/d1/) is cheaper per-write at M-size and is a natural next step. If you're on AWS, on-prem, or want your data portable, managed Postgres is the typical destination. Either way — graduation is a Baerly win, not a churn event.
91
+
92
+ **Export to a database service** (swap `--target=` for `sqlite`, `postgres`, or `d1`):
143
93
 
144
94
  ```sh
145
95
  baerly export --target=postgres \
@@ -147,28 +97,14 @@ baerly export --target=postgres \
147
97
  --collection=<collection-name> --output=./out.sql
148
98
  ```
149
99
 
150
- The export is a **point-in-time** snapshot and honors any active
151
- schema on the collection. Your data was already in your bucket and
152
- your code is a portable HTTP server, so the graduation doesn't
153
- require vendor cooperation.
100
+ The export is a **point-in-time** snapshot and honors any active schema on the collection. Your data was already in your bucket and your code is a portable HTTP server, so the graduation doesn't require vendor cooperation.
154
101
 
155
102
  ## Production auth
156
103
 
157
- The scaffold ships `auth: "none"` so the day-1 happy path works
158
- with zero env vars; every request resolves to `config.tenant`.
159
- Before deploy, follow `AGENTS.md` → "Going to production":
160
-
161
- - **Pattern A — CF Access (recommended).** Same artifact in dev and
162
- prod; the factory `verifier:` override engages when
163
- `CF_ACCESS_TEAM_DOMAIN` + `CF_ACCESS_AUDIENCE_TAG` are present in
164
- `wrangler.jsonc:vars`. The `cloudflareAccess()` preset
165
- (re-exported from `@gusto/baerly-storage/auth`) reads the JWT off
166
- `Cf-Access-Jwt-Assertion`, validates it against your team's JWKS,
167
- and pins `tenantPrefix` to `config.tenant` unless you pass an
168
- explicit tenant claim.
169
- - **Pattern B — `auth: "shared-secret"`.** Single-tenant
170
- server-to-server callers. Flip `auth` in `baerly.config.ts` and
171
- set `SHARED_SECRET` via `wrangler secret put`.
104
+ The scaffold ships `auth: "none"` so the day-1 happy path works with zero env vars; every request resolves to `config.tenant`. Before deploy, follow `AGENTS.md` → "Going to production":
105
+
106
+ - **Pattern A — CF Access (recommended).** Same artifact in dev and prod; the factory `verifier:` override engages when `CF_ACCESS_TEAM_DOMAIN` + `CF_ACCESS_AUDIENCE_TAG` are present in `wrangler.jsonc:vars`. The `cloudflareAccess()` preset (re-exported from `@gusto/baerly-storage/auth`) reads the JWT off `Cf-Access-Jwt-Assertion`, validates it against your team's JWKS, and pins `tenantPrefix` to `config.tenant` unless you pass an explicit tenant claim.
107
+ - **Pattern B — `auth: "shared-secret"`.** Single-tenant server-to-server callers. Flip `auth` in `baerly.config.ts` and set `SHARED_SECRET` via `wrangler secret put`.
172
108
 
173
109
  ## Pointers
174
110
 
@@ -15,14 +15,17 @@
15
15
  "@gusto/baerly-storage": "workspace:*"
16
16
  },
17
17
  "devDependencies": {
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
- "typescript": "^6.0.3",
23
- "vite": "^8.1.2",
24
- "vitest": "^4.1.9",
25
- "wrangler": "^4.106.0"
18
+ "@cloudflare/vite-plugin": "^1.69.1",
19
+ "@cloudflare/workers-types": "^5.20261116.1",
20
+ "@types/node": "^26.6.6",
21
+ "happy-dom": "^21.0.4",
22
+ "typescript": "^7.0.2",
23
+ "vite": "^8.3.8",
24
+ "vitest": "^5.1.0",
25
+ "wrangler": "^4.163.0"
26
26
  },
27
- "packageManager": "pnpm@11.1.2"
27
+ "engines": {
28
+ "node": ">=26"
29
+ },
30
+ "packageManager": "pnpm@12.22.0"
28
31
  }
@@ -3,13 +3,19 @@
3
3
  # map, `pnpm install` exits with `ERR_PNPM_IGNORED_BUILDS` for the
4
4
  # Cloudflare-stack deps below.
5
5
  #
6
- # - `esbuild` / `workerd` ship working install scripts we want to run.
7
- # - `sharp` is a transitive miniflare dep whose install script falls
8
- # back to a node-gyp build on Node 24 (no prebuilt for our
9
- # platform/runtime combo). Set to `false` to suppress cleanly —
10
- # sharp still loads from its prebuilt binary at require time, and
11
- # nothing in a scaffolded baerly app exercises its code path.
6
+ # `esbuild` and `workerd` ship working install scripts we want to run.
7
+ # Any other package that gains an install script fails the install
8
+ # until it is listed here.
12
9
  allowBuilds:
13
10
  esbuild: true
14
11
  workerd: true
15
- sharp: false
12
+
13
+ # Supply-chain guardrails, strict by default — loosen one deliberately:
14
+ # - minimumReleaseAge: don't resolve a version until it has been on
15
+ # the registry a day, closing the publish-then-yank window.
16
+ # - trustPolicy: fail if a package's publishing trust (provenance,
17
+ # trusted publisher) drops below what earlier versions had.
18
+ # - blockExoticSubdeps: only direct deps may come from git or tarballs.
19
+ minimumReleaseAge: 1440
20
+ trustPolicy: no-downgrade
21
+ blockExoticSubdeps: true
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "compilerOptions": {
3
3
  "target": "ES2024",
4
- "lib": ["ES2024", "DOM", "DOM.Iterable"],
4
+ "lib": ["ES2024", "ESNext.TypedArrays", "ESNext.Collection", "DOM"],
5
5
  "module": "ESNext",
6
6
  "moduleResolution": "bundler",
7
7
  "allowImportingTsExtensions": true,
@@ -19,10 +19,9 @@
19
19
  "isolatedModules": true,
20
20
  "erasableSyntaxOnly": true,
21
21
 
22
- "esModuleInterop": true,
23
22
  "skipLibCheck": true,
24
23
  "types": ["vite/client"],
25
24
  "composite": true
26
25
  },
27
- "include": ["src/web/**/*", "uint8array-base64.d.ts", "types.ts", "baerly.config.ts"]
26
+ "include": ["src/web/**/*", "types.ts", "baerly.config.ts"]
28
27
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "compilerOptions": {
3
3
  "target": "ES2024",
4
- "lib": ["ES2024", "DOM", "DOM.Iterable"],
4
+ "lib": ["ES2024", "ESNext.TypedArrays", "ESNext.Collection", "DOM"],
5
5
  "module": "ESNext",
6
6
  "moduleResolution": "bundler",
7
7
  "allowImportingTsExtensions": true,
@@ -19,10 +19,9 @@
19
19
  "isolatedModules": true,
20
20
  "erasableSyntaxOnly": true,
21
21
 
22
- "esModuleInterop": true,
23
22
  "skipLibCheck": true,
24
23
  "types": ["@cloudflare/workers-types", "node"],
25
24
  "composite": true
26
25
  },
27
- "include": ["src/server/**/*", "uint8array-base64.d.ts", "types.ts", "baerly.config.ts"]
26
+ "include": ["src/server/**/*", "types.ts", "baerly.config.ts"]
28
27
  }
@@ -1,7 +1,7 @@
1
1
  import { defineConfig } from "vitest/config";
2
2
 
3
3
  // Standalone — `vite.config.ts` loads `@cloudflare/vite-plugin`, which
4
- // rejects vitest's pool/environment combo. Add `@cloudflare/vitest-pool-workers`
4
+ // rejects vitest's pool/environment combo. Add `@cloudflare/vitest-plugin`
5
5
  // here if you want Worker-side integration tests.
6
6
  export default defineConfig({
7
7
  test: {
@@ -5,8 +5,10 @@
5
5
  "$schema": "node_modules/wrangler/config-schema.json",
6
6
  "name": "minimal-cloudflare",
7
7
  "main": "./src/server/index.ts",
8
- "compatibility_date": "2026-05-01",
9
- "compatibility_flags": ["nodejs_compat"],
8
+ "compatibility_date": "2026-10-23",
9
+ // `enable_request_signal` lets `/v1/since` see client disconnects. It is the
10
+ // default from compatibility_date 2026-11-17; drop it when the date moves past that.
11
+ "compatibility_flags": ["nodejs_compat", "enable_request_signal"],
10
12
 
11
13
  "r2_buckets": [
12
14
  {