@quickback-dev/cli 0.38.0 → 0.39.1

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 (109) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +36 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.d.ts +2 -0
  5. package/dist/commands/compile.test.d.ts.map +1 -0
  6. package/dist/commands/compile.test.js +83 -0
  7. package/dist/commands/compile.test.js.map +1 -0
  8. package/dist/commands/create.js +15 -11
  9. package/dist/commands/create.js.map +1 -1
  10. package/dist/commands/migrations.d.ts +33 -0
  11. package/dist/commands/migrations.d.ts.map +1 -1
  12. package/dist/commands/migrations.js +41 -2
  13. package/dist/commands/migrations.js.map +1 -1
  14. package/dist/commands/migrations.test.d.ts +2 -0
  15. package/dist/commands/migrations.test.d.ts.map +1 -0
  16. package/dist/commands/migrations.test.js +67 -0
  17. package/dist/commands/migrations.test.js.map +1 -0
  18. package/dist/docs/content.js +24 -24
  19. package/dist/docs/content.js.map +1 -1
  20. package/dist/examples/recruitment.tar.gz +0 -0
  21. package/dist/index.js +1 -1
  22. package/dist/lib/action-harvest.d.ts +48 -0
  23. package/dist/lib/action-harvest.d.ts.map +1 -0
  24. package/dist/lib/action-harvest.js +292 -0
  25. package/dist/lib/action-harvest.js.map +1 -0
  26. package/dist/lib/action-harvest.test.d.ts +2 -0
  27. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  28. package/dist/lib/action-harvest.test.js +112 -0
  29. package/dist/lib/action-harvest.test.js.map +1 -0
  30. package/dist/lib/api-client.d.ts +10 -0
  31. package/dist/lib/api-client.d.ts.map +1 -1
  32. package/dist/lib/api-client.js +17 -1
  33. package/dist/lib/api-client.js.map +1 -1
  34. package/dist/lib/api-client.test.js +19 -0
  35. package/dist/lib/api-client.test.js.map +1 -1
  36. package/dist/lib/artifact-routing.d.ts +1 -0
  37. package/dist/lib/artifact-routing.d.ts.map +1 -1
  38. package/dist/lib/artifact-routing.js +15 -3
  39. package/dist/lib/artifact-routing.js.map +1 -1
  40. package/dist/lib/artifact-routing.test.js +12 -1
  41. package/dist/lib/artifact-routing.test.js.map +1 -1
  42. package/dist/lib/file-loader.d.ts +1 -0
  43. package/dist/lib/file-loader.d.ts.map +1 -1
  44. package/dist/lib/file-loader.js +34 -1
  45. package/dist/lib/file-loader.js.map +1 -1
  46. package/dist/lib/file-loader.test.js +28 -4
  47. package/dist/lib/file-loader.test.js.map +1 -1
  48. package/dist/lib/prepare-state-output.d.ts +8 -0
  49. package/dist/lib/prepare-state-output.d.ts.map +1 -0
  50. package/dist/lib/prepare-state-output.js +17 -0
  51. package/dist/lib/prepare-state-output.js.map +1 -0
  52. package/dist/lib/prepare-state-output.test.d.ts +2 -0
  53. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  54. package/dist/lib/prepare-state-output.test.js +31 -0
  55. package/dist/lib/prepare-state-output.test.js.map +1 -0
  56. package/dist/skill/SKILL.md +1 -1
  57. package/dist/skill/docs/changelog.md +201 -0
  58. package/dist/skill/docs/compiler/config/agents.md +1 -1
  59. package/dist/skill/docs/compiler/config/auth.md +1 -1
  60. package/dist/skill/docs/compiler/config/index.md +8 -9
  61. package/dist/skill/docs/compiler/config/providers.md +3 -0
  62. package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
  63. package/dist/skill/docs/compiler/definitions/access.md +40 -33
  64. package/dist/skill/docs/compiler/definitions/actions.md +1 -1
  65. package/dist/skill/docs/compiler/definitions/firewall.md +1 -1
  66. package/dist/skill/docs/compiler/definitions/schema.md +8 -2
  67. package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
  68. package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
  69. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  70. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  71. package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
  72. package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
  73. package/dist/skill/docs/stack/cms/connecting.md +17 -16
  74. package/dist/skill/docs/stack/cms/index.md +7 -7
  75. package/dist/skill/docs/stack/cms/schema-format.md +0 -2
  76. package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
  77. package/dist/skill/docs/stack/cms/security.md +6 -6
  78. package/dist/skill/docs/stack/realtime/durable-objects.md +5 -7
  79. package/dist/skill/docs/stack/storage/r2.md +112 -3
  80. package/dist/skill/docs/stack/storage/using-r2.md +30 -10
  81. package/dist/templates/registry.js +2 -2
  82. package/dist/templates/registry.js.map +1 -1
  83. package/package.json +1 -1
  84. package/src/examples/recruitment.tar.gz +0 -0
  85. package/src/skill/SKILL.md +1 -1
  86. package/src/skill/docs/changelog.md +201 -0
  87. package/src/skill/docs/compiler/config/agents.md +1 -1
  88. package/src/skill/docs/compiler/config/auth.md +1 -1
  89. package/src/skill/docs/compiler/config/index.md +8 -9
  90. package/src/skill/docs/compiler/config/providers.md +3 -0
  91. package/src/skill/docs/compiler/config/single-tenant.md +65 -73
  92. package/src/skill/docs/compiler/definitions/access.md +40 -33
  93. package/src/skill/docs/compiler/definitions/actions.md +1 -1
  94. package/src/skill/docs/compiler/definitions/firewall.md +1 -1
  95. package/src/skill/docs/compiler/definitions/schema.md +8 -2
  96. package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
  97. package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
  98. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  99. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  100. package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
  101. package/src/skill/docs/stack/account-ui/features/index.md +2 -2
  102. package/src/skill/docs/stack/cms/connecting.md +17 -16
  103. package/src/skill/docs/stack/cms/index.md +7 -7
  104. package/src/skill/docs/stack/cms/schema-format.md +0 -2
  105. package/src/skill/docs/stack/cms/schema-registry.md +0 -6
  106. package/src/skill/docs/stack/cms/security.md +6 -6
  107. package/src/skill/docs/stack/realtime/durable-objects.md +5 -7
  108. package/src/skill/docs/stack/storage/r2.md +112 -3
  109. package/src/skill/docs/stack/storage/using-r2.md +30 -10
@@ -68,13 +68,21 @@ export default {
68
68
  | GET | `/bucket` | List buckets |
69
69
  | GET | `/bucket/:name` | Get bucket info |
70
70
  | DELETE | `/bucket/:name` | Delete bucket (must be empty) |
71
- | POST | `/object/:bucket/*path` | Upload file |
71
+ | POST | `/object/:bucket/*path` | Upload file (bytes through the Worker) |
72
+ | POST | `/presign/:bucket/*path` | **Presigned upload URL (bytes direct to R2)** |
73
+ | POST | `/confirm/:bucket/*path` | Confirm a presigned upload (reconcile size + etag) |
72
74
  | GET | `/object/:bucket/*path` | Download file |
73
75
  | HEAD | `/object/:bucket/*path` | Get file metadata |
74
76
  | DELETE | `/object/:bucket/*path` | Delete file (soft delete) |
75
77
  | GET | `/object` | List objects |
76
78
  | POST | `/url` | Get file URL for serving |
77
79
 
80
+ > For anything larger than a small image — video, audio, big PDFs — prefer the
81
+ > **presigned** path. The bytes go straight to R2, so you skip the Worker's
82
+ > request-body cap and don't burn Worker CPU streaming the upload. See
83
+ > [Presigned uploads](#presigned-uploads-recommended) below.
84
+
85
+
78
86
  ### Files Worker (files.yourdomain.com)
79
87
 
80
88
  | Method | Path | Auth Required |
@@ -145,6 +153,94 @@ Response:
145
153
  }
146
154
  ```
147
155
 
156
+ ## Presigned uploads (recommended)
157
+
158
+ Streaming bytes through the Worker (`POST /object`) is fine for small files, but
159
+ it puts every byte on the Worker's request path — subject to the body-size cap,
160
+ and billed as Worker CPU/duration. For media (video, audio, large PDFs), use a
161
+ **presigned URL**: the Worker runs all the access checks and hands back a
162
+ short-lived URL the client uploads to **directly**. The bytes never touch your
163
+ Worker.
164
+
165
+ ```bash
166
+ # 1. Ask the API to sign an upload URL (auth + bucket + role checks run here)
167
+ curl -X POST https://api.example.com/storage/v1/presign/videos/clip.mp4 \
168
+ -H "Authorization: Bearer <token>" \
169
+ -H "Content-Type: application/json" \
170
+ -d '{ "contentType": "video/mp4", "size": 73400320 }'
171
+
172
+ # Response:
173
+ # {
174
+ # "id": "obj_abc",
175
+ # "key": "org_abc/videos/clip.mp4",
176
+ # "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
177
+ # "method": "PUT",
178
+ # "headers": { "Content-Type": "video/mp4" },
179
+ # "expiresAt": "2026-06-02T12:10:00.000Z"
180
+ # }
181
+
182
+ # 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
183
+ curl -X PUT "<uploadUrl>" -H "Content-Type: video/mp4" --data-binary @clip.mp4
184
+
185
+ # 3. Confirm — reconciles the recorded size + etag against what actually landed
186
+ curl -X POST https://api.example.com/storage/v1/confirm/videos/clip.mp4 \
187
+ -H "Authorization: Bearer <token>"
188
+ ```
189
+
190
+ > If `contentType` is supplied at step 1 it is **bound into the signature** — the
191
+ > client MUST send exactly that `Content-Type` header on the PUT, or R2 rejects
192
+ > it. Omit it to let the client send any type.
193
+
194
+
195
+ ### Required secrets
196
+
197
+ Presigning uses R2's S3-compatible API, which needs an **R2 API token** — the
198
+ Workers bucket binding alone cannot presign. Create a token in the Cloudflare
199
+ dashboard (R2 → Manage API Tokens) and set:
200
+
201
+ ```bash
202
+ wrangler secret put R2_ACCOUNT_ID # your Cloudflare account id
203
+ wrangler secret put R2_ACCESS_KEY_ID # R2 API token access key id
204
+ wrangler secret put R2_SECRET_ACCESS_KEY # R2 API token secret
205
+ # Optional: wrangler secret put R2_S3_ENDPOINT # override the derived endpoint
206
+ ```
207
+
208
+ ### Signing from your own action
209
+
210
+ The same signer is exposed as `ctx.storage` inside any
211
+ [`defineAction`](/compiler/definitions/actions) — so you can author an upload endpoint that
212
+ runs your own access rules (org, team, relationship/scoped roles) and stores the
213
+ key in **your own table**, instead of the generic `buckets`/`objects` metadata:
214
+
215
+ ```typescript
216
+ export default defineAction({
217
+ path: '/event/:eventId/media/sign-upload',
218
+ method: 'POST',
219
+ input: z.object({ filename: z.string(), contentType: z.string() }),
220
+ access: { roles: ['admin', 'member', 'scope:event:attendee'] },
221
+ async execute({ input, ctx, db, storage }) {
222
+ // Tenant-scoped key — secure by construction
223
+ const key = `org/${ctx.activeOrgId}/event/${input.eventId}/${crypto.randomUUID()}-${input.filename}`;
224
+ const upload = await storage.signPutUrl(key, {
225
+ contentType: input.contentType,
226
+ expiresIn: 600,
227
+ });
228
+ await db.insert(images).values({ key, eventId: input.eventId /* … */ });
229
+ return { uploadUrl: upload.url, key, headers: upload.headers };
230
+ },
231
+ });
232
+ ```
233
+
234
+ `storage` exposes:
235
+
236
+ | Method | Returns | Use |
237
+ |--------|---------|-----|
238
+ | `signPutUrl(key, { contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 |
239
+ | `signGetUrl(key, { expiresIn?, downloadFilename? })` | `string` | Client downloads directly from R2 |
240
+
241
+ This is the supported replacement for streaming a raw binary body through an
242
+ action — the JSON body parser and its ~1 MiB cap stay on for every other route.
243
+
148
244
  ## Serving Files
149
245
 
150
246
  ### Public Files
@@ -177,11 +273,16 @@ When file storage is configured, the compiler generates:
177
273
 
178
274
  | File | Purpose |
179
275
  |------|---------|
180
- | `src/routes/storage.ts` | Storage API routes |
181
- | `src/files.ts` | Files database schema (buckets, objects) |
276
+ | `src/storage/routes.ts` | Storage API routes (upload, presign, confirm, download) |
277
+ | `src/storage/presign.ts` | R2 presigned-URL signer (`createPresigner`, backs `ctx.storage`) |
278
+ | `src/files/schema.ts` | Files database schema (buckets, objects) |
182
279
  | `cloudflare-workers/files/index.ts` | Files worker for serving |
183
280
  | `cloudflare-workers/files/wrangler.toml` | Files worker config |
184
281
 
282
+ The compiler also adds [`aws4fetch`](https://github.com/mhart/aws4fetch) to your
283
+ `package.json` (used by the presigner) and the R2 presign secrets to your
284
+ generated `CloudflareBindings` type.
285
+
185
286
  ## Deployment
186
287
 
187
288
  After compiling:
@@ -213,6 +314,14 @@ After compiling:
213
314
  wrangler deploy
214
315
  ```
215
316
 
317
+ 6. **Set the R2 presign secrets** (only if you use presigned uploads — see
318
+ [Presigned uploads](#presigned-uploads-recommended)):
319
+ ```bash
320
+ wrangler secret put R2_ACCOUNT_ID
321
+ wrangler secret put R2_ACCESS_KEY_ID
322
+ wrangler secret put R2_SECRET_ACCESS_KEY
323
+ ```
324
+
216
325
  ## Configuration Reference
217
326
 
218
327
  | Option | Type | Default | Description |
@@ -4,28 +4,48 @@ Cloudflare R2 provides S3-compatible object storage for file uploads in the Quic
4
4
 
5
5
  ## Upload Flow
6
6
 
7
- The generated API provides a two-step upload process:
7
+ The generated API provides a two-step **presigned** upload — the file bytes go
8
+ directly to R2 and never stream through your Worker:
8
9
 
9
- 1. **Request a presigned URL** — Client calls the upload endpoint to get a time-limited URL
10
- 2. **Upload directly to R2** — Client uploads the file directly to R2 (bypasses your Worker)
11
- 3. **Store the reference** — The API records the file metadata in D1
10
+ 1. **Request a presigned URL** — Client calls `/storage/v1/presign/...`; the
11
+ Worker runs auth + bucket + role checks and returns a time-limited URL
12
+ 2. **Upload directly to R2** — Client `PUT`s the bytes to R2 (bypasses your Worker)
13
+ 3. **Confirm** — `/storage/v1/confirm/...` reconciles the recorded size + etag
12
14
 
13
15
  ```bash
14
- # 1. Request presigned upload URL
15
- curl -X POST https://api.example.com/api/v1/files/upload \
16
+ # 1. Request a presigned upload URL
17
+ curl -X POST https://api.example.com/storage/v1/presign/documents/report.pdf \
16
18
  -H "Authorization: Bearer <token>" \
17
19
  -H "Content-Type: application/json" \
18
- -d '{"filename": "report.pdf", "contentType": "application/pdf"}'
20
+ -d '{ "contentType": "application/pdf", "size": 248000 }'
19
21
 
20
22
  # Response:
21
- # { "uploadUrl": "https://bucket.r2.cloudflarestorage.com/...", "fileId": "file_abc123" }
22
-
23
- # 2. Upload directly to R2 using the presigned URL
23
+ # {
24
+ # "id": "obj_abc123",
25
+ # "key": "org_abc/documents/report.pdf",
26
+ # "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
27
+ # "method": "PUT",
28
+ # "headers": { "Content-Type": "application/pdf" },
29
+ # "expiresAt": "2026-06-02T12:10:00.000Z"
30
+ # }
31
+
32
+ # 2. Upload directly to R2 using the presigned URL (replay the returned headers)
24
33
  curl -X PUT "<uploadUrl>" \
25
34
  -H "Content-Type: application/pdf" \
26
35
  --data-binary @report.pdf
36
+
37
+ # 3. Confirm the upload
38
+ curl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \
39
+ -H "Authorization: Bearer <token>"
27
40
  ```
28
41
 
42
+ Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
43
+ and `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).
44
+
45
+ For uploads that should land in **your own table** (with your own access rules),
46
+ sign the URL from inside a `defineAction` via `ctx.storage` — see
47
+ [Signing from your own action](/stack/storage/r2#signing-from-your-own-action).
48
+
29
49
  ## Download Flow
30
50
 
31
51
  Files are served through your Worker with security checks applied:
@@ -82,9 +82,9 @@ export const TEMPLATE_REGISTRY = {
82
82
  // api-minimal-bun also hidden alongside the other bun templates.
83
83
  "blog-cloudflare": {
84
84
  name: "Blog / CMS Starter",
85
- description: "Single-tenant blog with public pages, admin-only editing, deployed to Cloudflare Workers",
85
+ description: "Blog/CMS starter with a pinned organization id, public pages, and admin-only editing on Cloudflare Workers",
86
86
  category: "api",
87
- tags: ["blog", "cms", "single-tenant", "cloudflare", "d1"],
87
+ tags: ["blog", "cms", "pinned-organization", "cloudflare", "d1"],
88
88
  author: "quickback",
89
89
  version: "1.0.0",
90
90
  includes: ["betterauth", "d1", "hono", "drizzle"],
@@ -1 +1 @@
1
- {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.38.0",
3
+ "version": "0.39.1",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
Binary file
@@ -214,7 +214,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
214
214
  - `output` — `build.outputDir`, custom dependencies
215
215
  - `domains` — multi-domain hostname routing (CMS / account / admin)
216
216
  - `spa` — single-worker SPA mount (your product app at the apex)
217
- - `single-tenant` — disable organizations
217
+ - `single-tenant` — pinned organization mode and migration away from removed `organizations: false`
218
218
  - `agents` — robots.txt, llms.txt, MCP, OAuth discovery
219
219
 
220
220
  **Stack — runtime services** (`docs/stack/<topic>.md`)
@@ -1,5 +1,206 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.39.0 — June 2, 2026
4
+
5
+ Media and large-binary uploads are now first-class. Instead of streaming file
6
+ bytes through your Worker — which hits the request-body cap and burns Worker
7
+ CPU/duration — an action mints a short-lived **presigned URL** and the client
8
+ uploads the bytes **directly to R2**. The Worker only signs; it never sits in
9
+ the data path. This is the supported way to author image/video/document upload
10
+ endpoints, and it survives every `quickback compile` with no generated-file
11
+ patching.
12
+
13
+ Requires R2 file storage (`defineFileStorage("cloudflare-r2", …)`).
14
+
15
+ ### `ctx.storage` — sign uploads from any action
16
+
17
+ When R2 file storage is configured, every `defineAction` execute receives a
18
+ typed `storage` signer. Your action runs all the usual security layers (auth,
19
+ roles, org/relationship scope), computes a tenant-scoped key, hands the client
20
+ an upload URL, and stores the key in **your own table** — no separate metadata
21
+ system required:
22
+
23
+ ```ts
24
+ export default defineAction({
25
+ path: "/event/:eventId/media/upload-file-binary",
26
+ method: "POST",
27
+ input: z.object({ filename: z.string(), contentType: z.string() }),
28
+ access: { roles: ["admin", "member", "scope:event:attendee"] },
29
+ async execute({ input, ctx, c, db, storage }) {
30
+ const eventId = c.req.param("eventId");
31
+ const key = `org/${ctx.activeOrgId}/event/${eventId}/${crypto.randomUUID()}-${input.filename}`;
32
+ const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
33
+ await db.insert(images).values({ key, eventId });
34
+ return { uploadUrl: upload.url, key, headers: upload.headers, expiresAt: upload.expiresAt };
35
+ },
36
+ });
37
+ ```
38
+
39
+ `storage` exposes `signPutUrl(key, { contentType?, expiresIn? })` (returns
40
+ `{ url, method, headers, key, expiresAt }`) and
41
+ `signGetUrl(key, { expiresIn?, downloadFilename? })` (returns a presigned GET
42
+ URL). Construction is zero-cost — actions that never touch `storage` pay
43
+ nothing.
44
+
45
+ ### Managed presign + confirm endpoints
46
+
47
+ For the zero-config path, the built-in storage API now exposes a presigned
48
+ upload alongside the existing through-Worker upload:
49
+
50
+ - `POST /storage/v1/presign/:bucket/*path` — runs the bucket's auth/role/scope
51
+ checks, validates the declared `contentType` + `size` against bucket limits,
52
+ records a pending object row, and returns `{ id, key, uploadUrl, method,
53
+ headers, expiresAt }`
54
+ - `POST /storage/v1/confirm/:bucket/*path` — reconciles the recorded size and
55
+ etag against what actually landed in R2 (`HEAD`)
56
+
57
+ ### Setup: R2 API token
58
+
59
+ Presigning uses R2's S3 API, which needs an **R2 API token** — the Workers R2
60
+ binding cannot presign on its own. Set three secrets:
61
+
62
+ ```bash
63
+ wrangler secret put R2_ACCOUNT_ID
64
+ wrangler secret put R2_ACCESS_KEY_ID
65
+ wrangler secret put R2_SECRET_ACCESS_KEY
66
+ ```
67
+
68
+ `aws4fetch` is added to the generated `package.json` automatically, and the R2
69
+ presign secrets are added to the generated `Env` type. If you pass `contentType`
70
+ to `signPutUrl`, the client must replay exactly that `Content-Type` header on
71
+ the `PUT`.
72
+
73
+ ### No raw-body action flag
74
+
75
+ Streaming a raw binary request body through an action is intentionally **not**
76
+ supported. Presigning delivers the same result — large files, no body cap —
77
+ without poking a hole in the body-parsing layer, so JSON actions and the ~1 MiB
78
+ JSON cap stay intact for every other route.
79
+
80
+ ### Storage routes hardened
81
+
82
+ Enabling R2 file storage previously exposed several latent type errors in the
83
+ generated `/storage/v1/*` routes (dead references from an old multipart
84
+ refactor, JSON-string role columns treated as arrays, a few undefined
85
+ variables). The full storage surface now type-checks cleanly when file storage
86
+ is configured.
87
+
88
+ ## v0.38.1 — May 26, 2026
89
+
90
+ Custom action handlers get the same typed ergonomics as generated CRUD paths:
91
+ typed Cloudflare bindings on `env`, a first-class typed `realtime` helper when
92
+ realtime is enabled, and no more `createRealtime(...)` boilerplate inside every
93
+ action just to emit an explicit broadcast.
94
+
95
+ ### Neon compile output and local recompile state are now stable
96
+
97
+ The Neon + Cloudflare path now emits a correct runtime/output surface instead
98
+ of leaking SQLite-era state.
99
+
100
+ - `wrangler.toml` no longer emits a stray `[[d1_databases]]` block for Neon
101
+ projects
102
+ - repeated local Neon compiles now upload and sync the root PostgreSQL Drizzle
103
+ state correctly, so `drizzle-kit` can report "No schema changes" instead of
104
+ regenerating duplicate `0000_*.sql` files
105
+ - stale root Drizzle migrations from earlier bad compiles are pruned during the
106
+ compile/sync path
107
+
108
+ ### Shared-target namespace hydration now works for bulk-grant lanes
109
+
110
+ Bulk-grant namespace callers (`{ roles: [...] }`, `{ team: true }`) now inherit
111
+ the namespace's shared hydration target when every relationship lane points at
112
+ the same resource load shape.
113
+
114
+ That fixes the case where a namespace like:
115
+
116
+ ```ts
117
+ via: ['attendeeOf', 'organizerOf', { roles: ['admin', 'owner'] }]
118
+ ```
119
+
120
+ would authorize an org admin through the bulk lane but leave `ctx.event`
121
+ undefined, even though the sibling relationship lanes all hydrated the same
122
+ `events` row.
123
+
124
+ Runtime behavior is now split cleanly:
125
+
126
+ - **Shared target** — if all hydrating lanes share the same `loads`,
127
+ `exposeAs`, and resource key, hydration runs unconditionally after the gate
128
+ passes, so bulk callers get the same `ctx.<exposeAs>` as relationship callers
129
+ - **Distinct targets** — if lanes hydrate different tables / keys / ctx slots,
130
+ hydration stays per-matched-lane to avoid cross-table false 404s
131
+
132
+ Standalone action typing now matches that runtime behavior too: shared-target
133
+ hydration remains non-optional, while distinct-target multi-lane hydration stays
134
+ optional.
135
+
136
+ ### Platform role split: `appmanager` for control-plane, `sysadmin` for cross-tenant
137
+
138
+ Quickback no longer treats `user.role === "admin"` as the platform-wide role.
139
+ The control-plane role is now `user.role === "appmanager"` (CMS shell, Better
140
+ Auth admin endpoints, support tooling), while `user.role === "sysadmin"`
141
+ remains the only true cross-tenant data-plane tier.
142
+
143
+ This also retires the `ADMIN` pseudo-role. Any `roles: ["ADMIN"]` usage now
144
+ fails the compile with migration guidance:
145
+
146
+ - `userRole: ["appmanager"]` for platform control-plane access
147
+ - `roles: ["admin"]` for org-membership admin access
148
+ - `roles: ["SYSADMIN"]` for true cross-tenant access
149
+
150
+ Runtime behavior now matches that split end-to-end:
151
+
152
+ - Better Auth's admin plugin is generated with `adminRoles: ["appmanager", "sysadmin"]`
153
+ - CMS / OpenAPI / auth-admin surfaces gate on `appmanager` (and admit
154
+ `sysadmin` where appropriate)
155
+ - unsafe cross-tenant actions and tenant-bypass helpers require `sysadmin` only
156
+
157
+ ### Typed `env` + injected `realtime` in action handlers
158
+
159
+ The generated `<feature>/.quickback/define-action.ts` helper now types action
160
+ `env` from the project's runtime bindings surface instead of `any`, so custom
161
+ bindings like R2 buckets, queues, Durable Objects, auth env vars, and split DB
162
+ bindings no longer need `(env as any)` casts inside action handlers.
163
+
164
+ When realtime is enabled in config, action handlers also receive a typed
165
+ `realtime` helper directly in `execute(...)`. It exposes the same
166
+ `insert/update/delete/broadcast` methods as `createRealtime(env)`, but without
167
+ the extra import or hand-rolled factory call in every custom action.
168
+
169
+ This is a DX-only change. The auto-broadcast boundary is unchanged: generated
170
+ CRUD routes still broadcast automatically, while custom action writes still
171
+ broadcast explicitly.
172
+
173
+ ### `generateId: "cuid"` docs now reflect the split runtime/schema behavior
174
+
175
+ Quickback's `cuid` strategy is now documented as the split path it actually is:
176
+ compiler-managed schema auto-injection keeps the `createId()` call site but may
177
+ back it with a file-local `crypto.randomUUID()` polyfill, while import-capable
178
+ runtime paths still emit real `createId()` usage.
179
+
180
+ That matters most for `compiler.injectId` and other schema-emission paths that
181
+ run in sandboxes where project `node_modules` are not visible. The generated
182
+ schema can safely keep:
183
+
184
+ ```ts
185
+ id: text("id").primaryKey().$defaultFn(() => createId())
186
+ ```
187
+
188
+ while satisfying the reference via:
189
+
190
+ ```ts
191
+ const createId = () => crypto.randomUUID();
192
+ ```
193
+
194
+ instead of importing `@paralleldrive/cuid2` inside the schema-generation
195
+ environment.
196
+
197
+ **Important nuance:** this is not a guarantee that every generated id is a true
198
+ cuid2 string. Auto-injected schema paths may produce UUID-shaped strings
199
+ through the polyfill, while runtime paths that can import helpers may still use
200
+ real `createId()`. If you need strict cuid2 shape everywhere, explicitly import
201
+ `createId` from `@paralleldrive/cuid2` in the authored schema file; the
202
+ compiler preserves that import and skips the polyfill.
203
+
3
204
  ## v0.38.0 — May 26, 2026
4
205
 
5
206
  **Per-matched-lane authorization** for multi-lane namespaces — across both the
@@ -70,7 +70,7 @@ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool na
70
70
  `tools/list` only returns tools the calling identity could actually invoke. Each generated tool entry carries the operation's access metadata (`roles`, `userRole`, `or` / `and` combinators) and `tools/list` filters against `ctx` before responding:
71
71
 
72
72
  - **Unauthenticated callers** see only tools whose access declares the `PUBLIC` pseudo-role, or operations that have no security requirement at all (e.g. sign-in / sign-up).
73
- - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Admin-only endpoints don't appear for non-admins.
73
+ - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Platform-operator endpoints don't appear for callers outside the required user roles.
74
74
  - **Function-form access** (escape hatch) is opaque at list time — surfaced to any authenticated caller, then evaluated for real on `tools/call`.
75
75
  - **Record predicates** are dropped from the list-time check (no record yet) and applied normally on the actual call.
76
76
 
@@ -125,7 +125,7 @@ export default defineConfig({
125
125
  Both fields override compiler-emitted browser redirects in the CMS shell:
126
126
 
127
127
  - **Unauthenticated visitor hits a CMS route** → `302 → <loginUrl>?redirect=<original-url>`
128
- - **Authenticated user fails the `cms.access: 'admin'` role check** → `302 → <profileUrl>`
128
+ - **Authenticated user fails the `cms.access: 'admin'` platform-role check** → `302 → <profileUrl>`
129
129
 
130
130
  The `?redirect=…` query param is preserved unchanged so the central sign-in surface can bounce the user back after authentication.
131
131
 
@@ -8,7 +8,6 @@ import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickb
8
8
  export default defineConfig({
9
9
  name: "my-app",
10
10
  template: "hono",
11
- features: { organizations: true },
12
11
  providers: {
13
12
  runtime: defineRuntime("cloudflare"),
14
13
  database: defineDatabase("cloudflare-d1"),
@@ -87,7 +86,7 @@ quickback compile --no-sync-config
87
86
 
88
87
  | Field | Type | Description |
89
88
  |-------|------|-------------|
90
- | `features` | `object` | Feature flags — see [Single-Tenant Mode](/compiler/config/single-tenant) |
89
+ | `features` | `object` | Feature flags such as `pinnedOrganizationId` — see [Pinned Organization Mode](/compiler/config/single-tenant) |
91
90
  | `build` | `object` | Build options (`outputDir`, `packageManager`, `dependencies`) |
92
91
  | `compiler` | `object` | Compiler options — `features.auditFields: false` disables audit field injection project-wide; `migrations.renames` provides rename hints for headless CI; `securityContracts` tunes the route/SQL invariants checker |
93
92
  | `openapi` | `object` | OpenAPI spec generation (`generate`, `publish`, `docs: 'scalar' \| 'swagger'` for an in-browser API reference) — see [OpenAPI](/compiler/targets/hono-api/using-the-api/openapi) |
@@ -304,8 +303,8 @@ cms: { domain: "cms.example.com", sysadmin: true },
304
303
  | Option | Type | Default | Description |
305
304
  |--------|------|---------|-------------|
306
305
  | `domain` | `string` | — | Custom domain for CMS. Adds a `custom_domain` route to `wrangler.toml`. |
307
- | `access` | `"user" \| "admin"` | `"user"` | Controls who can access the CMS. When `"admin"`, only users with `user.role === "admin"` can enter — enforced at the Worker level (SPA shell, `/api/v1/schema`, and `custom_view` CRUD all return 403 to non-admins) and in the SPA. Also hides the CMS link in Account UI. See [CMS Connecting](/stack/cms/connecting) for the full enforcement model. |
308
- | `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"admin"`. Off by default. See [`SYSADMIN` pseudo-role](/compiler/definitions/access#sysadmin--cross-tenant-db-admin-tier). |
306
+ | `access` | `"user" \| "admin"` | `"admin"` | Controls who can access the CMS. When `"admin"`, platform control-plane users (`user.role === "appmanager"`) can enter; when `sysadmin` mode is also on, `user.role === "sysadmin"` is admitted too. The gate is enforced at the Worker level (SPA shell, `/api/v1/schema`, and `custom_view` CRUD all return 403 to callers outside those roles) and in the SPA. Also hides the CMS link in Account UI. See [CMS Connecting](/stack/cms/connecting) for the full enforcement model. |
307
+ | `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"appmanager"`. Off by default. See [`SYSADMIN` pseudo-role](/compiler/definitions/access#sysadmin--cross-tenant-db-admin-tier). |
309
308
 
310
309
  ### Sysadmin tier (`cms.sysadmin: true`)
311
310
 
@@ -313,11 +312,11 @@ Quickback's default model assumes every CMS user belongs to at least one organiz
313
312
 
314
313
  `cms: { sysadmin: true }` introduces a separate role tier:
315
314
 
316
- - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"admin"` — admins keep org-scoped CMS access via the membership switcher; sysadmins get cross-tenant. The two roles are independent at the pseudo-role evaluator level: `ADMIN` admits `'admin'` only, `SYSADMIN` admits `'sysadmin'` only. Routes that need both write `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly.
315
+ - **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"appmanager"` — appmanagers keep platform control-plane access (CMS shell, Better Auth admin surfaces, support tooling), while sysadmins get true cross-tenant data access. `ADMIN` is now a rejected legacy pseudo-role; use `userRole: ["appmanager"]` for control-plane gates and `roles: ["SYSADMIN"]` for cross-tenant access.
317
316
  - **Firewall**: every `buildFirewallConditions()` emits an `if (ctx.userRole === "sysadmin") return undefined` (or just the soft-delete predicate when present) at the top, so sysadmins see every tenant's rows. See [Firewall escape hatch](/compiler/definitions/firewall#sysadmin-escape-hatch).
318
317
  - **Org listing**: a `GET /auth/v1/admin/list-organizations` endpoint selects directly from the auth-schema `organization` table — every row, every tenant. Sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`) so the URL shape matches BA convention; the handler is Quickback-emitted and gated to `user.role === "sysadmin"` only. For the membership-bound caller's-orgs listing, use BA's own `/auth/v1/organization/list`.
319
318
  - **CMS SPA**: when the user is a sysadmin, the header switcher loads from the cross-tenant endpoint, defaults to "All organizations" (which omits `?organizationId=` and reaches the firewall escape), and pins selected tenants via `?organizationId=` on every API call. Org admins keep the existing membership-based switcher.
320
- - **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"admin"`. Org admins are not locked out — both roles can enter the CMS in `cms.access: "admin"` mode.
319
+ - **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"appmanager"`. Org admins are not locked out when you set `cms.access: "user"`; `cms.access: "admin"` is specifically the platform control-plane gate.
321
320
 
322
321
  Off by default. Projects that don't enable it get zero behavior change; setting `cms.sysadmin: true` and granting a user `user.role = "sysadmin"` is the only way to unlock the cross-tenant view.
323
322
 
@@ -369,8 +368,8 @@ Control which authentication features are exposed. Disabled features are exclude
369
368
  | `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
370
369
  | `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
371
370
  | `auth.signup` | `boolean` | `true` | `emailAndPassword.disableSignUp` (inverted) | Self-service account registration — false hides the UI **and** rejects the server endpoint with 403 |
372
- | `auth.organizations` | `boolean` | `false` | UI surface only — server gating lives under `features.organizations` | Multi-tenant organization management UI (dashboard, invitations, roles). The BA `organization` plugin is auto-added by `features.organizations` for server-side reasons (org tables) independent of this UI flag |
373
- | `auth.admin` | `boolean` | `false` | UI surface only — BA `admin` plugin is auto-added when `features.organizations` is on | Admin panel for user management in the Account SPA |
371
+ | `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (dashboard, invitations, roles). Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
372
+ | `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
374
373
  | `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
375
374
 
376
375
  ## Trusted Origins
@@ -506,5 +505,5 @@ See the sub-pages for detailed reference on each section:
506
505
  - [Providers](/compiler/config/providers) — Runtime, database, and auth options
507
506
  - [Variables](/compiler/config/variables) — Environment variables and flags
508
507
  - [Output](/compiler/config/output) — Generated file structure
509
- - [Single-Tenant Mode](/compiler/config/single-tenant) — Admin-only and public-facing apps without organizations
508
+ - [Pinned Organization Mode](/compiler/config/single-tenant) — Fixed-org deployments without org switching UI
510
509
  - [Multi-Domain Architecture](/compiler/config/domains) — Custom domains, hostname routing, and cross-subdomain auth
@@ -226,6 +226,9 @@ See [Realtime](/stack/realtime) for the client-side connection flow and helper e
226
226
  > `"short"` produces IDs with ~56.8 billion possible values (62^6). That's fine for small/scoped tables like rooms, invites, or share codes — but at roughly 238,000 rows you hit a 50% chance of collision (birthday bound). Don't use it for high-volume records. `"nanoid"` and `"short"` both require the `nanoid` package in your project.
227
227
 
228
228
 
229
+ > `generateId: "cuid"` is not byte-for-byte uniform across every compiler path. Import-capable runtime paths emit real `createId()` usage, but compiler-managed schema auto-injection may preserve the `createId()` call site with a file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes stay dependency-free. If you require true cuid2 strings everywhere, explicitly import `createId` from `@paralleldrive/cuid2` in the authored schema file.
230
+
231
+
229
232
  ## Auth Providers
230
233
 
231
234
  | Provider | Description |