@quickback-dev/cli 0.70.31 → 0.70.40

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 (127) hide show
  1. package/dist/commands/build.d.ts +12 -0
  2. package/dist/commands/build.d.ts.map +1 -1
  3. package/dist/commands/build.js +69 -1
  4. package/dist/commands/build.js.map +1 -1
  5. package/dist/commands/deploy.d.ts +9 -0
  6. package/dist/commands/deploy.d.ts.map +1 -1
  7. package/dist/commands/deploy.js +20 -2
  8. package/dist/commands/deploy.js.map +1 -1
  9. package/dist/commands/migrate-data.d.ts +12 -0
  10. package/dist/commands/migrate-data.d.ts.map +1 -0
  11. package/dist/commands/migrate-data.js +134 -0
  12. package/dist/commands/migrate-data.js.map +1 -0
  13. package/dist/commands/migrate.d.ts.map +1 -1
  14. package/dist/commands/migrate.js +11 -0
  15. package/dist/commands/migrate.js.map +1 -1
  16. package/dist/commands/secrets.d.ts +27 -0
  17. package/dist/commands/secrets.d.ts.map +1 -0
  18. package/dist/commands/secrets.js +186 -0
  19. package/dist/commands/secrets.js.map +1 -0
  20. package/dist/index.js +23 -3
  21. package/dist/index.js.map +1 -1
  22. package/dist/lib/access-manifest-diff.d.ts +87 -0
  23. package/dist/lib/access-manifest-diff.d.ts.map +1 -0
  24. package/dist/lib/access-manifest-diff.js +331 -0
  25. package/dist/lib/access-manifest-diff.js.map +1 -0
  26. package/dist/lib/artifact-routing.d.ts.map +1 -1
  27. package/dist/lib/artifact-routing.js +3 -0
  28. package/dist/lib/artifact-routing.js.map +1 -1
  29. package/dist/lib/compiler-stubs.d.ts +2 -0
  30. package/dist/lib/compiler-stubs.d.ts.map +1 -1
  31. package/dist/lib/compiler-stubs.js +2 -0
  32. package/dist/lib/compiler-stubs.js.map +1 -1
  33. package/dist/lib/file-loader.d.ts +6 -0
  34. package/dist/lib/file-loader.d.ts.map +1 -1
  35. package/dist/lib/file-loader.js +17 -0
  36. package/dist/lib/file-loader.js.map +1 -1
  37. package/dist/lib/ops-manifest.d.ts +76 -0
  38. package/dist/lib/ops-manifest.d.ts.map +1 -0
  39. package/dist/lib/ops-manifest.js +94 -0
  40. package/dist/lib/ops-manifest.js.map +1 -0
  41. package/dist/lib/release-and-pin.d.ts +34 -0
  42. package/dist/lib/release-and-pin.d.ts.map +1 -0
  43. package/dist/lib/release-and-pin.js +71 -0
  44. package/dist/lib/release-and-pin.js.map +1 -0
  45. package/dist/lib/shell.d.ts +4 -1
  46. package/dist/lib/shell.d.ts.map +1 -1
  47. package/dist/lib/shell.js +8 -3
  48. package/dist/lib/shell.js.map +1 -1
  49. package/dist/skill/docs/api/actions.md +2 -0
  50. package/dist/skill/docs/api/batch-operations.md +18 -4
  51. package/dist/skill/docs/api/crud.md +62 -0
  52. package/dist/skill/docs/api/errors.md +17 -2
  53. package/dist/skill/docs/configure/auth.md +49 -2
  54. package/dist/skill/docs/configure/bindings.md +15 -0
  55. package/dist/skill/docs/configure/domains.md +4 -0
  56. package/dist/skill/docs/configure/index.md +29 -11
  57. package/dist/skill/docs/configure/tenancy.md +117 -0
  58. package/dist/skill/docs/define/access.md +19 -0
  59. package/dist/skill/docs/define/actions/access.md +76 -0
  60. package/dist/skill/docs/define/actions/defining.md +156 -1
  61. package/dist/skill/docs/define/actions/scoped-db.md +236 -9
  62. package/dist/skill/docs/define/areas.md +46 -0
  63. package/dist/skill/docs/define/authz-roles.md +10 -0
  64. package/dist/skill/docs/define/diagnostics.md +263 -0
  65. package/dist/skill/docs/define/encryption.md +32 -0
  66. package/dist/skill/docs/define/guards.md +13 -0
  67. package/dist/skill/docs/define/masking.md +77 -3
  68. package/dist/skill/docs/define/rate-limit.md +3 -3
  69. package/dist/skill/docs/define/schema.md +148 -7
  70. package/dist/skill/docs/define/scopes.md +79 -0
  71. package/dist/skill/docs/define/transitions.md +39 -0
  72. package/dist/skill/docs/define/views.md +77 -3
  73. package/dist/skill/docs/platform/api-contract/index.md +4 -0
  74. package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -0
  75. package/dist/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
  76. package/dist/skill/docs/platform/auth/using-auth.md +6 -0
  77. package/dist/skill/docs/platform/database/d1.md +47 -0
  78. package/dist/skill/docs/platform/database/data-migrations.md +109 -0
  79. package/dist/skill/docs/platform/database/read-replication.md +142 -7
  80. package/dist/skill/docs/platform/payments/one-off-checkout.md +6 -1
  81. package/dist/skill/docs/platform/push/index.md +2 -0
  82. package/dist/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
  83. package/dist/skill/docs/platform/storage/using-r2.md +135 -19
  84. package/dist/skill/docs/start/deploy.md +38 -0
  85. package/dist/skill/docs/tooling/cli.md +120 -0
  86. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
  87. package/dist/skill/docs/tooling/output.md +70 -2
  88. package/package.json +1 -1
  89. package/src/skill/docs/api/actions.md +2 -0
  90. package/src/skill/docs/api/batch-operations.md +18 -4
  91. package/src/skill/docs/api/crud.md +62 -0
  92. package/src/skill/docs/api/errors.md +17 -2
  93. package/src/skill/docs/configure/auth.md +49 -2
  94. package/src/skill/docs/configure/bindings.md +15 -0
  95. package/src/skill/docs/configure/domains.md +4 -0
  96. package/src/skill/docs/configure/index.md +29 -11
  97. package/src/skill/docs/configure/tenancy.md +117 -0
  98. package/src/skill/docs/define/access.md +19 -0
  99. package/src/skill/docs/define/actions/access.md +76 -0
  100. package/src/skill/docs/define/actions/defining.md +156 -1
  101. package/src/skill/docs/define/actions/scoped-db.md +236 -9
  102. package/src/skill/docs/define/areas.md +46 -0
  103. package/src/skill/docs/define/authz-roles.md +10 -0
  104. package/src/skill/docs/define/diagnostics.md +263 -0
  105. package/src/skill/docs/define/encryption.md +32 -0
  106. package/src/skill/docs/define/guards.md +13 -0
  107. package/src/skill/docs/define/masking.md +77 -3
  108. package/src/skill/docs/define/rate-limit.md +3 -3
  109. package/src/skill/docs/define/schema.md +148 -7
  110. package/src/skill/docs/define/scopes.md +79 -0
  111. package/src/skill/docs/define/transitions.md +39 -0
  112. package/src/skill/docs/define/views.md +77 -3
  113. package/src/skill/docs/platform/api-contract/index.md +4 -0
  114. package/src/skill/docs/platform/auth/jwt-optimization.md +2 -0
  115. package/src/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
  116. package/src/skill/docs/platform/auth/using-auth.md +6 -0
  117. package/src/skill/docs/platform/database/d1.md +47 -0
  118. package/src/skill/docs/platform/database/data-migrations.md +109 -0
  119. package/src/skill/docs/platform/database/read-replication.md +142 -7
  120. package/src/skill/docs/platform/payments/one-off-checkout.md +6 -1
  121. package/src/skill/docs/platform/push/index.md +2 -0
  122. package/src/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
  123. package/src/skill/docs/platform/storage/using-r2.md +135 -19
  124. package/src/skill/docs/start/deploy.md +38 -0
  125. package/src/skill/docs/tooling/cli.md +120 -0
  126. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
  127. package/src/skill/docs/tooling/output.md +70 -2
@@ -81,41 +81,157 @@ https://files.yourdomain.com/public/org_abc/listings/3f2a9c…-hero.jpg
81
81
 
82
82
  ## Signed upload (large or confidential files)
83
83
 
84
- Write a `defineAction` that signs a presigned URL and stores the key in
85
- **your own table**. Bytes go directly to R2 — the Worker only signs.
84
+ Declare the key column as `q.storageKey(...)` and let `db.allocateUpload`
85
+ write it. Bytes go directly to R2 — the Worker only signs. The client never
86
+ names the key, so it can't point a row at another tenant's object.
87
+
88
+ ```ts title="quickback/quickback.config.ts"
89
+ import { defineConfig, defineRuntime, defineDatabase, defineAuth, defineFileStorage } from "@quickback/compiler";
90
+
91
+ export default defineConfig({
92
+ name: "events-app",
93
+ template: "hono",
94
+ features: { organizations: true },
95
+ providers: {
96
+ runtime: defineRuntime("cloudflare"),
97
+ database: defineDatabase("cloudflare-d1"),
98
+ auth: defineAuth("better-auth", { plugins: { organization: true } }),
99
+ fileStorage: defineFileStorage("cloudflare-r2", { bucketName: "events-app-media" }),
100
+ },
101
+ bindings: {
102
+ r2Buckets: [{ binding: "MEDIA", bucketName: "events-app-media" }],
103
+ },
104
+ });
105
+ ```
106
+
107
+ ```ts
108
+ // quickback/features/media/media.ts
109
+ import { feature, q } from "@quickback/compiler";
110
+
111
+ export default feature("media", {
112
+ columns: {
113
+ id: q.id(),
114
+ eventId: q.text().required(),
115
+ title: q.text({ maxLength: 200 }).required(),
116
+ r2Key: q.storageKey({
117
+ bucket: "MEDIA",
118
+ key: "media/{organizationId}/{eventId}/{uuid}.{ext}",
119
+ mime: ["image/*", "application/pdf"],
120
+ maxBytes: 10_000_000,
121
+ }),
122
+ organizationId: q.scope("organization"),
123
+ ...q.audit(),
124
+ },
125
+ read: { access: { roles: ["member"] } },
126
+ update: { access: { roles: ["member"] } },
127
+ delete: { access: { roles: ["admin"] }, mode: "hard" },
128
+ guards: { updatable: ["title"] },
129
+ });
86
130
 
87
- ```ts title="quickback/features/media/actions/signUpload.ts"
131
+ // quickback/features/media/actions/upload.ts
88
132
  import { z } from "zod";
89
133
  import { defineAction, media } from "../.quickback/define-action";
90
134
 
91
135
  export default defineAction({
92
- description: "Sign a direct-to-R2 upload URL and record the object key on the media row.",
93
- path: "/media/sign-upload",
136
+ description: "Create a media row and sign its direct-to-R2 upload.",
137
+ path: "/media/upload",
94
138
  method: "POST",
95
- input: z.object({ filename: z.string(), contentType: z.string(), size: z.number().int().nonnegative() }),
139
+ input: z.object({ eventId: z.string(), title: z.string(), ext: z.string(), mime: z.string(), size: z.number().int() }),
96
140
  access: { roles: ["member"] },
97
- async execute({ input, ctx, db, storage }) {
98
- const key = `org/${ctx.activeOrgId}/${crypto.randomUUID()}-${input.filename}`;
99
- const upload = await storage.signPutUrl(key, {
100
- contentType: input.contentType, // bound into the signature
101
- contentLength: input.size, // required — bound into the signature, checked against maxFileSize
102
- expiresIn: 600,
103
- });
104
- await db.insert(media).values({ key /* … */ });
105
- return { uploadUrl: upload.url, key, headers: upload.headers };
141
+ async execute({ db, input }) {
142
+ const { row, putUrl, headers } = await db.allocateUpload(media, input);
143
+ return { id: row.id, putUrl, headers };
106
144
  },
107
145
  });
108
146
  ```
109
147
 
110
148
  ```bash
111
149
  # 1. Ask your action for a signed URL (your auth/roles run here)
112
- curl -X POST https://api.example.com/api/v1/media/sign-upload \
150
+ curl -X POST https://api.example.com/api/v1/media/upload \
113
151
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
114
- -d '{ "filename": "report.pdf", "contentType": "application/pdf", "size": 48213 }'
115
- # → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Length": "48213", "Content-Type": "application/pdf" } }
152
+ -d '{ "eventId": "evt_1", "title": "Floor plan", "ext": "pdf", "mime": "application/pdf", "size": 48213 }'
153
+ # → { "id": "…", "putUrl": "https://<account>.r2.cloudflarestorage.com/events-app-media/media/org_abc/evt_1/<uuid>.pdf?…X-Amz-Signature=…", "headers": { "Content-Length": "48213", "Content-Type": "application/pdf" } }
116
154
 
117
155
  # 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
118
- curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
156
+ curl -X PUT "<putUrl>" -H "Content-Type: application/pdf" -H "Content-Length: 48213" --data-binary @plan.pdf
157
+ ```
158
+
159
+ `db.allocateUpload(table, { ...rowValues, ext, mime, size }, { id?, expiresIn? })`:
160
+
161
+ 1. Checks `mime` against the column's `mime` list (`415 STORAGE_UPLOAD_TYPE_REFUSED`),
162
+ `size` against `maxBytes` (`413 STORAGE_UPLOAD_TOO_LARGE`), and `ext`
163
+ (1–16 letters or digits, lower-cased).
164
+ 2. Stamps the row exactly as the scoped `db.insert` would (`organizationId`
165
+ from the caller's active org), then renders the key from the template:
166
+ `{column}` from the row, a fresh `{uuid}`, `{ext}` from the call. A value
167
+ that cannot fill a whole path segment (`/`, `..`, anything outside
168
+ `A–Z a–z 0–9 _ -`) is a `400 STORAGE_KEY_SEGMENT_INVALID`.
169
+ 3. Signs a PUT with `ctx.storage.signPutUrl` underneath. The `mime` and `size`
170
+ are bound into the signature as `Content-Type` / `Content-Length`. When the
171
+ project also declares `fileStorage.allowedTypes`, the type must be on that
172
+ list too.
173
+ 4. Inserts the row (or, with `{ id }`, re-keys that row and deletes its
174
+ previous object) and returns `{ row, key, putUrl, headers, expiresAt }`.
175
+
176
+ If the table also has columns named `mime`, `size`, or `ext`, the upload's
177
+ values fill them.
178
+
179
+ **Reads.** `db.signDownload(table, id, { expiresIn?, downloadFilename? })` loads
180
+ the row through the firewall and signs a GET for its key. It refuses with
181
+ `403 STORAGE_KEY_OUTSIDE_PREFIX` when the stored key is not under the row's
182
+ own prefix.
183
+
184
+ **The prefix** is the template up to `{uuid}` with the row's values
185
+ substituted: `media/org_abc/evt_1/`. Every column placeholder fills a whole
186
+ `/`-separated segment, so "starts with the row's prefix" can't match a
187
+ neighbouring tenant. Reads, deletes, and [tenant purge](/configure/tenancy) all
188
+ refuse a key outside its row's prefix — a row whose key was tampered to name
189
+ another tenant's object never reaches that object.
190
+
191
+ **Deletes.** Deleting a row deletes its object:
192
+
193
+ - The generated hard `DELETE /:id` and `DELETE /batch` delete the objects of
194
+ the rows they erased.
195
+ - In an action, `db.delete(table)` on a storage-key table deletes the objects
196
+ of the rows it removed — from a full `.returning()`, or else by selecting
197
+ the matching rows through the same scoped `db` first. Inside
198
+ `db.transaction(...)` the objects are deleted after the outermost commit.
199
+ `db.batch([...])` refuses a storage-key delete, because a batch skips this
200
+ step.
201
+ - Soft deletes keep the object, because the row still exists.
202
+ - `unsafeDb`, schedules, and queue handlers bypass the scoped `db`. After a
203
+ hard delete there, call `deleteStorageObjects(env, table, deletedRows)` from
204
+ `src/lib/storage-keys`. It runs the same prefix check.
205
+
206
+ **What the compiler refuses** (each is a compile error):
207
+
208
+ | Code | Cause |
209
+ |---|---|
210
+ | `STORAGE_KEY_GUARDED` | The column is listed in `guards.createable` / `updatable` / `immutable` / `protected`. It is never client-writable, and no generated write body carries it. |
211
+ | `STORAGE_KEY_TENANT_PREFIX` | A tenant column of the table's firewall (`organizationId`, `ownerId`, a scope column) is not a placeholder before `{uuid}`. |
212
+ | `STORAGE_KEY_TEMPLATE` | No `{uuid}`, `{uuid}` not starting its own segment, a placeholder that isn't a column, a column after `{uuid}` (only `{ext}` may follow), `..`, or characters outside `A–Z a–z 0–9 . _ - /`. |
213
+ | `STORAGE_KEY_BUCKET` | `bucket` is not a `bindings.r2Buckets` binding (or the managed `fileStorage` binding), or an environment maps that binding to a different bucket name. |
214
+ | `STORAGE_KEY_PRESIGN` | No `providers.fileStorage: defineFileStorage("cloudflare-r2", …)` — the presigner signs the PUT. |
215
+ | `STORAGE_KEY_MIME` / `STORAGE_KEY_MAX_BYTES` | A malformed MIME pattern, or `maxBytes` that isn't a positive integer or exceeds `fileStorage.maxFileSize`. |
216
+ | `STORAGE_KEY_REQUIRED_WITH_CREATE` | The column is `.required()` and the table has a generic create route, which could never supply the key. |
217
+ | `STORAGE_KEY_CASCADE` | The table declares `onDelete: 'cascade'`. A cascaded delete removes rows without deleting their objects. |
218
+ | `STORAGE_KEY_MULTIPLE` / `STORAGE_KEY_NO_RESOURCE` | More than one storage key on a table, or a storage key on a table with no resource (no firewall to check the row against). |
219
+
220
+ In action code, writing the column directly (`db.insert(...).values({ r2Key })`,
221
+ `db.update(...).set({ r2Key })`, an upsert's `set`) throws
222
+ `STORAGE_KEY_NOT_WRITABLE`.
223
+
224
+ ### Lower level: `storage.signPutUrl`
225
+
226
+ When the key does not belong to a row (a one-off export, an import staging
227
+ area), sign it yourself. You own the key's tenancy in that case.
228
+
229
+ ```ts no-compile
230
+ const upload = await storage.signPutUrl(`exports/${ctx.activeOrgId}/${crypto.randomUUID()}.csv`, {
231
+ contentType: "text/csv",
232
+ contentLength: input.size, // required — bound into the signature
233
+ expiresIn: 600,
234
+ });
119
235
  ```
120
236
 
121
237
  `storage.signPutUrl(key, { contentLength, contentType?, expiresIn?, bucket? })`
@@ -93,6 +93,44 @@ verify that the Hyperdrive origin matches the intended Neon branch, inspect
93
93
  remote query caching, or apply Postgres migrations. Configure Hyperdrive with
94
94
  query caching disabled and migrate the intended branch before deployment.
95
95
 
96
+ ## Release stamps
97
+
98
+ {/* doc-compile: skip — excerpt of the top-level `release` key. */}
99
+ ```ts title="quickback/quickback.config.ts"
100
+ release: { stampVars: true }, // optional: version: "1.4.0"
101
+ ```
102
+
103
+ With `stampVars` on, `quickback build` reads the release identity from your
104
+ repository: the version (`release.version`, else the project `package.json`
105
+ version), the git commit (`git rev-parse HEAD`, suffixed `-dirty` when the
106
+ tree has uncommitted changes), and the build time. The compiler cannot see your
107
+ repository, so the CLI supplies these values and the compiler validates them.
108
+ They are stamped as `QUICKBACK_RELEASE_VERSION`, `QUICKBACK_RELEASE_SHA` and
109
+ `QUICKBACK_RELEASE_AT` into `[vars]` and into every `[env.*.vars]` block.
110
+ Then:
111
+
112
+ - `GET /health` includes `release: { version, sha, at }`;
113
+ - handlers read the same values as `ctx.release`;
114
+ - `quickback deploy` passes `--tag <version> --message <version>@<sha>@<at>`
115
+ to `wrangler deploy`, so each Worker version in the Cloudflare dashboard
116
+ names the build it came from. It refuses to deploy if the built output
117
+ carries no stamp.
118
+
119
+ The three names are compiler-owned. Declaring a var with one of these names is
120
+ a compile error, whether or not stamping is on. The build fails if the project
121
+ is not a git checkout or has no version. `QUICKBACK_RELEASE_AT` changes on
122
+ every build, so `wrangler.toml` changes on every build too.
123
+
124
+ ## Before you ship a target
125
+
126
+ ```bash
127
+ quickback secrets check --env production # every required secret set, nothing undeclared
128
+ quickback migrate data --env production # dry-run pending data migrations
129
+ ```
130
+
131
+ See [Check and Push Secrets](/tooling/cli#check-and-push-secrets) and
132
+ [Data Migrations](/platform/database/data-migrations).
133
+
96
134
  ## Conflicting ids
97
135
 
98
136
  If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops:
@@ -69,6 +69,9 @@ quickback build
69
69
  > the name used throughout the docs.
70
70
 
71
71
 
72
+ Use `quickback build --accept-compiler` to accept a compiler other than the
73
+ one `compiler.pin` names (see [Pin the Compiler](#pin-the-compiler)).
74
+
72
75
  Use `quickback build --verbose` when a remote build fails and you need the
73
76
  underlying command, exit code, stderr/stdout tail, and suggested fixes.
74
77
 
@@ -96,6 +99,40 @@ explicit `wrangler ... --env <target>` deploy commands. It does not suggest a
96
99
  bare deploy or the unnamed `.env.neon` / `.dev.vars` workflow for named
97
100
  Hyperdrive environments.
98
101
 
102
+ #### Diff the access manifest
103
+
104
+ ```bash
105
+ quickback build --diff quickback/reports/access-manifest.json
106
+ ```
107
+
108
+ `--diff <baseline.json>` compares a committed
109
+ [access manifest](/tooling/output#access-manifest) with the one this build
110
+ produces, prints a readable diff, and **exits 1 on any widening**:
111
+
112
+ - a new route or Durable Object room, or a new room kind;
113
+ - a weaker `auth` requirement (`session` → `public`) or room gate
114
+ (`resource-gated` → `authenticated`);
115
+ - an access tree that admits a principal the baseline did not — wider roles,
116
+ a new `or` arm, a dropped `and` arm, a removed gate, a new `fga` arm;
117
+ - wider room `roles` or effective `writeRoles`, including removal of a write
118
+ restriction or a change to inherited table access;
119
+ - a firewall arm removed from an AND, added to an `any:` group, or that lost
120
+ its `tenantBound` flag; a firewall that went from `scoped` to `exception`;
121
+ - an `unsafe` action that became `crossTenant`, `targetScope: 'all'`, or not
122
+ `adminOnly`;
123
+ - a new trusted origin, in the bundle or for any named environment.
124
+
125
+ Narrowings (removed routes, tighter roles, new AND arms) print but never fail.
126
+ When the comparison cannot prove a change narrows, it reports a widening.
127
+ Older room baselines without `connectAccess` and `writeAccess` cannot establish
128
+ what the room admitted: regenerate and review them before accepting a new baseline.
129
+
130
+ The baseline is read **before** the build, so `--diff` may point at the very
131
+ file the build overwrites — the usual setup is to commit
132
+ `quickback/reports/access-manifest.json` and run the line above in CI. After
133
+ reviewing an intended widening, commit the freshly written manifest as the new
134
+ baseline.
135
+
99
136
  #### Generated `src/` is hermetic
100
137
 
101
138
  Every file under `src/` carries a `Generated by quickback.dev` header and is owned by the compiler. Before each compile writes its output, the CLI:
@@ -261,6 +298,88 @@ cross-feature imports are left untouched, and unusual shapes (aliases,
261
298
  multi-line imports, `import type`) are reported for manual attention instead
262
299
  of guessed at.
263
300
 
301
+ ### Pin the Compiler
302
+
303
+ ```bash
304
+ quickback build --accept-compiler # accept a different compiler and rewrite the pin
305
+ ```
306
+
307
+ Set `compiler.pin` to the exact compiler build a project may be built by, as
308
+ `<version>@<gitSha>`:
309
+
310
+ {/* doc-compile: skip — excerpt of the `compiler` block; the rest of `defineConfig` is unchanged. */}
311
+ ```ts title="quickback/quickback.config.ts"
312
+ compiler: {
313
+ pin: "0.70.36@3f9c2ab",
314
+ },
315
+ ```
316
+
317
+ The compiler compares the pin against its own version and image sha
318
+ (the same values `/health` reports) **before generating anything**. Any other
319
+ build fails the compile and nothing is written. The sha matches by prefix, so a
320
+ 7-character short sha is enough; the version must match exactly.
321
+
322
+ `--accept-compiler` lets the mismatch through and rewrites `compiler.pin` to
323
+ the compiler that answered, so the upgrade shows up as a one-line diff in
324
+ review. A compiler that cannot report its build sha (a local build without
325
+ build metadata) can neither satisfy a pin nor be accepted into one. A compiler
326
+ too old to know about pins is refused by the CLI.
327
+
328
+ ### Check and Push Secrets
329
+
330
+ ```bash
331
+ quickback secrets check --env staging
332
+ quickback secrets push --env staging # reads .env.staging
333
+ quickback secrets push --env staging --from ./secrets/staging.env
334
+ ```
335
+
336
+ Every build writes the declared secrets contract to
337
+ `reports/ops.manifest.json`: every secret the generated Worker reads
338
+ ([`bindings.secrets`](/configure/bindings#secrets) plus those your providers
339
+ imply, such as `BETTER_AUTH_SECRET`, social-login credentials, R2 presign keys,
340
+ `ENCRYPTION_KEK`, Neon's `DATABASE_URL`), and which ones the boot guard refuses
341
+ to serve without.
342
+
343
+ - `check` runs `wrangler secret list` for the target and exits `1` when a
344
+ required secret is **missing** or a secret is set but **not declared**.
345
+ Code that reads an undeclared secret is code the compiler cannot see, so
346
+ that state counts as a failure.
347
+ - `push` sets secrets from a dotenv file with `wrangler secret put`. Values go
348
+ over stdin, not argv, and are never printed. If the file names an
349
+ undeclared secret or has an empty value, nothing is pushed. Without
350
+ `--from`, it reads `.env.<target>`, which the generated `.gitignore` ignores
351
+ (`.env.*`, keeping `*.example`).
352
+
353
+ Projects without named environments omit `--env` and pass `--from`. The build
354
+ also writes `.dev.vars.example` with every declared secret, for local
355
+ `wrangler dev`. Neon and PlanetScale keep their own template, and any declared
356
+ secret it lacks is appended to it.
357
+
358
+ ### Run Data Migrations
359
+
360
+ ```bash
361
+ quickback migrate data --env staging # dry run
362
+ quickback migrate data --env staging --apply
363
+ quickback migrate data --env production --apply --id 2026-10-21-backfill-slugs
364
+ ```
365
+
366
+ Runs [data migrations](/platform/database/data-migrations) inside the
367
+ deployed Worker for that target. By default it dry-runs every pending (or
368
+ previously failed) migration in id order. `--apply` writes the changes and
369
+ records each id in that environment's ledger, so it never runs there again.
370
+
371
+ | Flag | |
372
+ | --- | --- |
373
+ | `--env <target>` | Named target (required when the project has named environments). |
374
+ | `--apply` | Write and record. Without it, nothing is written. |
375
+ | `--id <id>` | Run one migration instead of every pending one. |
376
+ | `--token <bearer>` | Bearer for a user whose `user.role` is in `dataMigrations.access.userRole`. Also read from `QUICKBACK_ADMIN_TOKEN`. |
377
+ | `--url <origin>` | Override the target's API origin (required for workers.dev-only targets). |
378
+
379
+ The route path and each target's API hostname come from
380
+ `reports/ops.manifest.json`. The command needs no database credentials. The
381
+ first failure stops the run and exits `1`.
382
+
264
383
  ### View Documentation
265
384
 
266
385
  ```bash
@@ -420,6 +539,7 @@ quickback build
420
539
  |------|-------------|
421
540
  | `-v, --version` | Show version number |
422
541
  | `-h, --help` | Show help message |
542
+ | `build --diff <baseline>` | Fail the build on any access widening against a committed access manifest ([details](#diff-the-access-manifest)) |
423
543
 
424
544
  ## Environment Variables
425
545
 
@@ -149,23 +149,23 @@ and corrective import. If an older compiler or an already-generated project
149
149
  reaches Wrangler first, apply the same fix above and rebuild Generated Backend
150
150
  before Deploy.
151
151
 
152
- The compile sandbox has no network and bundles against the compiler image's
153
- own dependencies. A dependency declared in
154
- [`build.dependencies`](/configure#custom-dependencies) may not be available
155
- there. In that case, a hosted complete compile fails before the bundle check:
152
+ The bundle check resolves dependencies from the compiler image first. A
153
+ package declared in [`build.dependencies`](/configure#custom-dependencies) that
154
+ the image lacks is installed from the npm registry for that compile, with
155
+ install scripts disabled. If that install fails, the compile stops before the
156
+ bundle check and names the packages:
156
157
 
157
158
  ```
158
- Worker bundle check cannot run: build.dependencies not installed in the
159
- compiler image: fast-xml-parser
159
+ build.dependencies could not be installed for the Worker bundle check:
160
+ fast-xml-parser. npm: …
160
161
  ```
161
162
 
162
- The image preinstalls a set of [supported build
163
- dependencies](/configure#custom-dependencies) — PartyServer, Yjs,
164
- ProseMirror, `drizzle-zod`, and React Email among them. Type-only `@types/*`
165
- packages never block the check. For any other package, build locally with it
166
- installed or request that it be added to the compiler image. Validation
167
- compiles (`complete=false`) still generate output without running the Worker
168
- bundle check.
163
+ Check that the package name and range exist on npm. Only registry packages at
164
+ a semver range or dist-tag can be installed; `file:`, `git`, URL, `npm:` alias,
165
+ and `workspace:` specifiers fail with `build.dependencies must be npm registry
166
+ packages at a semver range or dist-tag`. Type-only `@types/*` packages never
167
+ block the check. Validation compiles (`complete=false`) still generate output
168
+ without running the Worker bundle check.
169
169
 
170
170
  Store the Better Auth id as plain text:
171
171
 
@@ -277,7 +277,7 @@ schema qualifier script:
277
277
 
278
278
  | Provider | Emitted |
279
279
  |----------|---------|
280
- | `cloudflare-d1` | `.env.cloudflare-d1.example`, `wrangler.d1.example`, `drizzle.auth.config.ts` (dual-database mode) |
280
+ | `cloudflare-d1` | `.env.cloudflare-d1.example`, `.dev.vars.example`, `wrangler.d1.example`, `drizzle.auth.config.ts` (dual-database mode) |
281
281
  | `neon` | `.env.neon.example`, `.dev.vars.example`, `docs/neon-setup.md`, `scripts/quickback-qualify-auth-schema.mjs` |
282
282
  | `planetscale-postgres` | `.env.planetscale.example`, `.dev.vars.example`, `docs/planetscale-postgres-setup.md`, `scripts/quickback-qualify-auth-schema.mjs` |
283
283
 
@@ -288,6 +288,39 @@ they emit a single `drizzle.config.ts` rather than the D1 dual-database pair.
288
288
  See [Neon](/platform/database/neon) and
289
289
  [PlanetScale Postgres](/platform/database/planetscale-postgres).
290
290
 
291
+ Every Cloudflare project gets a `.dev.vars.example` that lists every declared
292
+ secret (see below). The Postgres providers keep their own connection guidance
293
+ in that file, and any declared secret they do not mention is appended. The
294
+ generated `.gitignore` ignores `.dev.vars` and `.env.*` (keeping `*.example`),
295
+ so files that hold secret values are never committed.
296
+
297
+ ### Ops manifest
298
+
299
+ `reports/ops.manifest.json` is written on every Cloudflare build. It is the
300
+ one place the CLI reads operational facts from, so the CLI never re-derives a
301
+ compiler rule:
302
+
303
+ | Key | Contents | Read by |
304
+ | --- | --- | --- |
305
+ | `compiler` | `version` and `gitSha` of the build that produced the output | — |
306
+ | `targets` | each deploy target: logical name, Worker name, `wrangler --env`, API origin | every command below |
307
+ | `secrets` | `required`, `optional`, and `declared[]` (source, `bootGuarded`, description) | `quickback secrets check\|push` |
308
+ | `release` | the stamped `{ version, sha, at }` when `release.stampVars` is on | `quickback deploy` (`--tag` / `--message`) |
309
+ | `dataMigrations` | runner path, ledger table, allowed roles, declared ids | `quickback migrate data` |
310
+
311
+ Readers ignore unknown keys. New sections are added over time, and existing
312
+ ones are never restructured.
313
+
314
+ ### Data migrations
315
+
316
+ When `quickback/migrations/data/*.ts` exist, each file is emitted as a module
317
+ under `src/data-migrations/`, along with `src/lib/data-migration-define.ts`,
318
+ the gated runner `src/lib/data-migrations.ts` (mounted at
319
+ `/api/v1/system/data-migrations`), and the `_qb_data_migrations` ledger table
320
+ in the features database. On Postgres, that table lives in the `app` schema
321
+ behind a service-role-only RLS policy. See
322
+ [Data Migrations](/platform/database/data-migrations).
323
+
291
324
  ### Embeddings
292
325
 
293
326
  When any feature has `embeddings` configured:
@@ -384,7 +417,7 @@ quickback/drizzle/
384
417
 
385
418
  ### Security Audit Database (Unsafe Actions)
386
419
 
387
- When any action enables unsafe cross-tenant mode (`unsafe.crossTenant: true`):
420
+ When any action enables unsafe cross-tenant mode (`unsafe.crossTenant: true`), declares the [operator lane](/define/actions/scoped-db#operator-lane-operator) (`operator:`), is `PUBLIC`, or a resource hard-deletes:
388
421
 
389
422
  ```
390
423
  src/
@@ -422,6 +455,41 @@ Set `compiler.securityContracts.report.signature.required: true` to fail compila
422
455
 
423
456
  The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
424
457
 
458
+ ### Access Manifest
459
+
460
+ `reports/access-manifest.json` is emitted on every compile. The contract
461
+ report says how many invariants held; the manifest says **what the backend
462
+ admits**:
463
+
464
+ - **`routes`** — one entry per HTTP route (CRUD, batch, views, actions), keyed
465
+ `<METHOD> <path>`: the `auth` requirement (`public` / `session` /
466
+ `bearer-only`), the access tree, and the flattened principals that open it —
467
+ `roles`, `pseudoRoles`, `userRole`, `scopeLanes` (`scope:<kind>:<role>`) and
468
+ `relationships`. `firewall` lists the row arms (`mode` is `scoped`,
469
+ `exception` or `none`); each arm carries its boolean `path`
470
+ (`and`, `and > any`, …), a canonical `predicate`, and **`tenantBound`** —
471
+ true when every row the arm admits is bound to the caller's org (the org
472
+ equality itself, an arm under an AND with it, or a scope / relationship arm
473
+ the compiler wraps in `tenantBound(arm, orgEq)` inside an org-anchored
474
+ `any:` group). Actions with `unsafe` enabled carry `adminOnly`,
475
+ `crossTenant` and `targetScope`.
476
+ - **`realtimeRooms`** — each Durable Object mount with its `connectAuth` and,
477
+ for resource-gated rooms, the keyed table's read access and firewall arms.
478
+ Each gate also records `connectAccess` (the expanded room `roles`, or the
479
+ table read policy when inherited) and `writeAccess` (the additional expanded
480
+ `writeRoles` restriction, or `null` when every admitted connection may write).
481
+ The table firewall still applies when a room overrides its role policy.
482
+ - **`trustedOrigins`** — `bundle` is the `TRUSTED_ORIGINS` list baked into the
483
+ one shared Worker bundle; `environments` lists, per named environment, the
484
+ origins of the hostnames it claims.
485
+
486
+ The file is deterministic — no timestamps, no compiler version, sorted
487
+ arrays — so a committed copy is a baseline. The CLI writes it to
488
+ `quickback/reports/access-manifest.json` alongside the contract report.
489
+ `quickback build --diff <baseline>` compares the fresh manifest to it and
490
+ exits non-zero on any widening; see
491
+ [CLI → Diff the access manifest](/tooling/cli#diff-the-access-manifest).
492
+
425
493
  ### Data Remediation Report
426
494
 
427
495
  `reports/data-remediation.sql` is emitted when the project has something to check. It is **read-only as emitted** — every statement is a `SELECT`, and the compiler never runs it:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.70.31",
3
+ "version": "0.70.40",
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",
@@ -201,6 +201,8 @@ Cross-tenant unsafe actions are generated with:
201
201
 
202
202
  Without unsafe mode, `unsafeDb` is `undefined`.
203
203
 
204
+ An operator acting on one tenant named by the input does not need `unsafe`: declare [`operator: { target }`](/define/actions/scoped-db#operator-lane-operator) on a `userRole` action. The route loads the target (404 `OPERATOR_TARGET_NOT_FOUND` when absent or soft-deleted), scopes `db` to its organization, and audits the call against that tenant.
205
+
204
206
  On Postgres providers `unsafeDb` is the service-role handle for every unsafe action, so row-level security does not narrow it to the caller — the same reach as on D1. See the [provider note](/define/actions/scoped-db#unsafe-mode).
205
207
 
206
208
  Raw SQL in action code is blocked by default at compile time. If you need it for a specific action, set `allowRawSql: true` on that action explicitly.
@@ -83,7 +83,7 @@ server-minted ids as usual.
83
83
  - **201** — All records created successfully
84
84
  - **207** — Partial success (some errors, some successes)
85
85
 
86
- `POST /batch` uses a single bulk `INSERT`, so `meta.transactional` is `true` on every provider — the database guarantees the insert is atomic regardless of the `failFast` flag.
86
+ `POST /batch` uses one bulk `INSERT`, so `meta.transactional` is `true` on every provider — the database guarantees the insert is atomic regardless of the `failFast` flag. On D1 a wide batch is sliced to stay under the [bind limit](#database-bind-limits) and the slices run in one `db.batch()`, which D1 commits atomically.
87
87
 
88
88
  Fields applied automatically to each record:
89
89
  - ID generation (UUID, prefixed, etc.)
@@ -208,7 +208,7 @@ Note: Batch delete uses an `ids` array (not `records`).
208
208
  }
209
209
  ```
210
210
 
211
- `DELETE /batch` issues a single bulk `UPDATE … WHERE id IN (...)` (soft delete) or `DELETE … WHERE id IN (...)` (hard delete), so `meta.transactional` is `true` on every provider regardless of `failFast`.
211
+ `DELETE /batch` issues one bulk `UPDATE … WHERE id IN (...)` (soft delete) or `DELETE … WHERE id IN (...)` (hard delete), so `meta.transactional` is `true` on every provider regardless of `failFast`. On D1 the id list is sliced under the [bind limit](#database-bind-limits) and the slices run in one atomic `db.batch()`.
212
212
 
213
213
  **Hard delete**: Returns objects with only the `id` field (record data is deleted).
214
214
 
@@ -318,8 +318,8 @@ transport with Neon's hyperdrive mode.
318
318
  | `PATCH /batch` (update) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Fail-fast loop without rollback — the driver has no `db.transaction`. Records before the failure stay committed. |
319
319
  | `PUT /batch` (upsert) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
320
320
  | `PUT /batch` (upsert) | cloudflare-d1, neon over http (Cloudflare default) | `true` | `false` | Bulk insert commits; per-record update loop is fail-fast without rollback. |
321
- | `POST /batch` (create) | (any) | (any) | `true` | Single bulk `INSERT` — atomic at the DB level. |
322
- | `DELETE /batch` | (any) | (any) | `true` | Single bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. |
321
+ | `POST /batch` (create) | (any) | (any) | `true` | One bulk `INSERT` — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
322
+ | `DELETE /batch` | (any) | (any) | `true` | One bulk `UPDATE` (soft) or `DELETE` (hard) — atomic at the DB level. On D1, slices under the bind limit commit together via `db.batch()`. |
323
323
  | [Changeset](/define/changesets) (`application/vnd.quickback.changeset+json`) | tx-supporting (postgres, neon over websocket/hyperdrive, planetscale-postgres) | n/a | `true` | Root op + every child op share one transaction; any op failure rolls back the whole changeset. |
324
324
  | [Changeset](/define/changesets) | cloudflare-d1, neon over http (Cloudflare default) | n/a | `false` | Deterministic parent-first fail-fast — the first op failure stops the changeset; already-applied ops stay committed (a consistent, independently-authorized prefix). |
325
325
 
@@ -370,6 +370,20 @@ The default maximum batch size is **100 records**. Requests exceeding the limit
370
370
  }
371
371
  ```
372
372
 
373
+ ### Database bind limits
374
+
375
+ Every batch route builds statements whose size grows with the request — `WHERE id IN (...)` over the submitted ids, or a multi-row `INSERT` binding every column of every row. Drivers cap the bound parameters a single statement may carry:
376
+
377
+ | Provider | Bound parameters per statement |
378
+ |----------|-------------------------------|
379
+ | `cloudflare-d1` (and local Miniflare/workerd) | 100 |
380
+ | `neon`, `planetscale-postgres` | 65535 |
381
+ | other SQLite drivers | 32766 |
382
+
383
+ The generated handlers never exceed the cap. Id lists and insert rows are sliced to fit (ids in slices of 80, leaving room for the firewall's scope binds; insert rows by `floor(80 / columns)`), and on drivers that offer `db.batch()` — D1 included — the slices run in one atomic batch, so `meta.transactional` stays honest. A full `maxBatchSize` request on D1 therefore succeeds for any table width; on Postgres a 100-record batch is always a single statement. The runtime lives in the generated `src/lib/sql-binds.ts` (`selectInChunks`, `insertInChunks`), and the budget constant `MAX_SQL_BINDS` is the provider's cap — reuse it in hand-written actions that take id lists.
384
+
385
+ The body must carry its array under the documented key. A `POST`/`PATCH`/`PUT /batch` without a `records` array, or a `DELETE /batch` without `ids`, is rejected with 400 `VALIDATION_INVALID_INPUT` naming the missing field — never a 200 that wrote nothing.
386
+
373
387
  ## Configuration
374
388
 
375
389
  Batch operations inherit access control from their corresponding write operation. You can override per-batch settings:
@@ -289,6 +289,67 @@ where the id is **required** on `POST /`, `POST /batch` and a changeset
289
289
  the id. `PUT /:id` and `PATCH` are unchanged — the id still comes from the
290
290
  URL, never the body.
291
291
 
292
+ ### Row-token idempotency
293
+
294
+ An offline or flaky client retries creates. `allowClientIds` makes a retry
295
+ fail loudly (`409`); a **row token** makes it succeed with the row the first
296
+ attempt wrote. Declare the token column on the table:
297
+
298
+ {/* doc-compile: skip — needs `allowClientIds: true` on the database config, which the docs gate's fixed harness config does not set. Compiled by tests/output-matrix/fixtures/race-safe-writes. */}
299
+ ```typescript
300
+ // features/rsvps/rsvps.ts
301
+ import { feature, q } from "@quickback/compiler";
302
+
303
+ export default feature("rsvps", {
304
+ columns: {
305
+ id: q.id(),
306
+ clientMutationId: q.text({ maxLength: 64 }).optional().unique(),
307
+ eventId: q.text().required(),
308
+ guestName: q.text().required(),
309
+ organizationId: q.scope("organization"),
310
+ ...q.audit(),
311
+ ...q.softDelete(),
312
+ },
313
+ idempotency: { rowToken: "clientMutationId", clientId: { column: "id", pattern: "uuid" } },
314
+ read: { access: { roles: ["member"] } },
315
+ create: { access: { roles: ["member"] } },
316
+ });
317
+ ```
318
+
319
+ On `POST /` and `POST /batch`:
320
+
321
+ - A create whose `clientMutationId` is already stored on a row the caller can
322
+ see **replays that row**: `200`, header `Idempotent-Replayed: true`, the
323
+ stored (masked) record as the body. Nothing runs — no insert, no trigger
324
+ hooks, no realtime frame, no embedding job, no after-commit effect.
325
+ - A create that races its own retry is arbitrated by the database: the unique
326
+ constraint on the token (or the primary key, when the client mints the id)
327
+ refuses the second INSERT, and that request replays the winner instead of
328
+ answering `409`.
329
+ - The same client id under a **different** token, or the same token with a
330
+ different id, is `409 IDEMPOTENCY_ROW_CONFLICT`.
331
+ - `POST /batch` returns replayed rows in `success` next to the created ones,
332
+ and inserts only the new ones; a token repeated inside one batch is a
333
+ per-record `400 IDEMPOTENCY_TOKEN_REPEATED`.
334
+ - A create with no token is an ordinary create.
335
+
336
+ Compile-time rules (fail closed): the token column must exist, be a text
337
+ column the client may create (in `guards.createable` when guards are
338
+ declared), and be covered by a non-partial unique constraint — unless
339
+ `clientId` is declared, in which case the primary key arbitrates and the
340
+ client must resend the same id on retry. `clientId.column` must be the
341
+ primary key, `clientId.pattern` must name the project's `generateId` strategy
342
+ (`uuid`, `cuid` / `cuid2`, `nanoid`, `prefixed`, `short`), and the database
343
+ config must accept client ids (`allowClientIds: true`).
344
+
345
+ **Row token vs `Idempotency-Key`.** The
346
+ [`Idempotency-Key` header](/platform/api-contract#idempotency-key) is per
347
+ **request**: it caches one response for 24 hours, bound to the principal that
348
+ sent it, on any write endpoint. A row token is per **row**: it is stored in
349
+ the table, never expires, and replays across sessions, devices and
350
+ principals that can read the row. Use the header for "don't do this request
351
+ twice"; use a row token for "this client-side record exists exactly once".
352
+
292
353
  ### Response
293
354
 
294
355
  `201 Created`. The body is the **bare created record** — there is no `data`
@@ -314,6 +375,7 @@ wrapper:
314
375
  | `400` | Invalid field or missing required field |
315
376
  | `403` | User lacks permission to create records |
316
377
  | `409` | Client-supplied `id` (with `allowClientIds: true`) already exists |
378
+ | `409` | `IDEMPOTENCY_ROW_CONFLICT` — a [row token](#row-token-idempotency) or client id already belongs to a different record |
317
379
 
318
380
  ## Update Record
319
381