@quickback-dev/cli 0.60.4 → 0.60.5

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 (86) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +89 -13
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.js +52 -5
  5. package/dist/commands/compile.test.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/lib/api-client.d.ts +15 -0
  8. package/dist/lib/api-client.d.ts.map +1 -1
  9. package/dist/lib/api-client.js.map +1 -1
  10. package/dist/lib/migrations/commit.d.ts +38 -0
  11. package/dist/lib/migrations/commit.d.ts.map +1 -0
  12. package/dist/lib/migrations/commit.js +39 -0
  13. package/dist/lib/migrations/commit.js.map +1 -0
  14. package/dist/lib/migrations/drizzle-prompts.d.ts +97 -0
  15. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -0
  16. package/dist/lib/migrations/drizzle-prompts.js +190 -0
  17. package/dist/lib/migrations/drizzle-prompts.js.map +1 -0
  18. package/dist/lib/migrations/drizzle-prompts.test.d.ts +2 -0
  19. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +1 -0
  20. package/dist/lib/migrations/drizzle-prompts.test.js +135 -0
  21. package/dist/lib/migrations/drizzle-prompts.test.js.map +1 -0
  22. package/dist/lib/migrations/drizzle-wrapper.d.ts +28 -0
  23. package/dist/lib/migrations/drizzle-wrapper.d.ts.map +1 -0
  24. package/dist/lib/migrations/drizzle-wrapper.js +63 -0
  25. package/dist/lib/migrations/drizzle-wrapper.js.map +1 -0
  26. package/dist/lib/migrations/executor.d.ts +4 -1
  27. package/dist/lib/migrations/executor.d.ts.map +1 -1
  28. package/dist/lib/migrations/executor.js +0 -6
  29. package/dist/lib/migrations/executor.js.map +1 -1
  30. package/dist/lib/migrations/file-envelopes.d.ts +42 -0
  31. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -0
  32. package/dist/lib/migrations/file-envelopes.js +255 -0
  33. package/dist/lib/migrations/file-envelopes.js.map +1 -0
  34. package/dist/lib/migrations/postprocessors/audit-migration-hardening.d.ts +29 -0
  35. package/dist/lib/migrations/postprocessors/audit-migration-hardening.d.ts.map +1 -0
  36. package/dist/lib/migrations/postprocessors/audit-migration-hardening.js +67 -0
  37. package/dist/lib/migrations/postprocessors/audit-migration-hardening.js.map +1 -0
  38. package/dist/lib/migrations/postprocessors/index.d.ts +58 -0
  39. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -0
  40. package/dist/lib/migrations/postprocessors/index.js +344 -0
  41. package/dist/lib/migrations/postprocessors/index.js.map +1 -0
  42. package/dist/lib/migrations/postprocessors/index.test.d.ts +2 -0
  43. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +1 -0
  44. package/dist/lib/migrations/postprocessors/index.test.js +298 -0
  45. package/dist/lib/migrations/postprocessors/index.test.js.map +1 -0
  46. package/dist/lib/migrations/postprocessors/migration-reorder.d.ts +39 -0
  47. package/dist/lib/migrations/postprocessors/migration-reorder.d.ts.map +1 -0
  48. package/dist/lib/migrations/postprocessors/migration-reorder.js +185 -0
  49. package/dist/lib/migrations/postprocessors/migration-reorder.js.map +1 -0
  50. package/dist/lib/migrations/postprocessors/trigger-sql.d.ts +51 -0
  51. package/dist/lib/migrations/postprocessors/trigger-sql.d.ts.map +1 -0
  52. package/dist/lib/migrations/postprocessors/trigger-sql.js +62 -0
  53. package/dist/lib/migrations/postprocessors/trigger-sql.js.map +1 -0
  54. package/dist/lib/migrations/prior-state.d.ts +63 -0
  55. package/dist/lib/migrations/prior-state.d.ts.map +1 -0
  56. package/dist/lib/migrations/prior-state.js +141 -0
  57. package/dist/lib/migrations/prior-state.js.map +1 -0
  58. package/dist/lib/migrations/prompt-runner.d.ts +32 -0
  59. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -0
  60. package/dist/lib/migrations/prompt-runner.js +158 -0
  61. package/dist/lib/migrations/prompt-runner.js.map +1 -0
  62. package/dist/lib/migrations/prompt-runner.test.d.ts +2 -0
  63. package/dist/lib/migrations/prompt-runner.test.d.ts.map +1 -0
  64. package/dist/lib/migrations/prompt-runner.test.js +131 -0
  65. package/dist/lib/migrations/prompt-runner.test.js.map +1 -0
  66. package/dist/lib/migrations/schema-contract.d.ts +44 -0
  67. package/dist/lib/migrations/schema-contract.d.ts.map +1 -0
  68. package/dist/lib/migrations/schema-contract.js +51 -0
  69. package/dist/lib/migrations/schema-contract.js.map +1 -0
  70. package/dist/skill/docs/api/errors.md +1 -0
  71. package/dist/skill/docs/configure/domains.md +84 -0
  72. package/dist/skill/docs/define/firewall.md +1 -0
  73. package/dist/skill/docs/define/relationships.md +35 -0
  74. package/dist/skill/docs/platform/database/d1.md +14 -0
  75. package/dist/skill/docs/platform/database/neon.md +12 -5
  76. package/dist/skill/docs/start/deploy-browser.md +3 -0
  77. package/dist/skill/docs/tooling/output.md +28 -10
  78. package/package.json +1 -1
  79. package/src/skill/docs/api/errors.md +1 -0
  80. package/src/skill/docs/configure/domains.md +84 -0
  81. package/src/skill/docs/define/firewall.md +1 -0
  82. package/src/skill/docs/define/relationships.md +35 -0
  83. package/src/skill/docs/platform/database/d1.md +14 -0
  84. package/src/skill/docs/platform/database/neon.md +12 -5
  85. package/src/skill/docs/start/deploy-browser.md +3 -0
  86. package/src/skill/docs/tooling/output.md +28 -10
@@ -26,6 +26,8 @@ When you click **Deploy this app**, the pipeline runs four phases and reports ea
26
26
  3. **Package** — the project recompiles with the real resource ids folded in and is bundled into Worker modules (plus your CMS/Account SPA assets, when enabled). Every byte is hash-verified against the manifest before anything is uploaded.
27
27
  4. **Finalize** — migrations apply, the Worker uploads with its bindings, secrets are set, and the `workers.dev` route is enabled. Start probes the URL and only shows **Live** once it actually answers.
28
28
 
29
+ Provision hands back a one-time approval that finalize must present, so the upload can only ever be the one that was approved — being signed in is deliberately not enough on its own. The approval is good for an hour, which no normal deploy comes close to.
30
+
29
31
  A typical deploy takes one to two minutes, most of it compilation.
30
32
 
31
33
  ## What deploys
@@ -92,6 +94,7 @@ The deploy card is the whole connection UI: it reports the state of your Cloudfl
92
94
  | "Couldn't reach the deploy service…" | Transient failure talking to Quickback or Cloudflare | **Try again** |
93
95
  | "Browser deploys aren't fully configured on the server yet" | A deploy-service misconfiguration, not anything on your side | Use [`quickback deploy`](/start/deploy) for now |
94
96
  | "Too many deploys in a minute" | More than 5 provisions in a minute on one account | Wait for the `Retry-After` window and click Deploy again |
97
+ | "This deploy's approval was no longer valid…" | Provision approves one specific upload, for an hour. A deploy that outlives its approval is refused at the finalize step — nothing was uploaded | **Try again** — a fresh deploy re-provisions and re-approves |
95
98
 
96
99
  Deploy is disabled while a reconnect is pending, so a deploy never starts on a connection that can't finish it. If a connection dies *during* a deploy, the failure comes back as a reconnect prompt rather than a raw error — the deploy is safe to re-run after reconnecting, because provisioning adopts and migrations apply once.
97
100
 
@@ -361,7 +361,22 @@ Routes are mounted under `/api/v1/{feature}` for the default contract or
361
361
 
362
362
  ## Migrations
363
363
 
364
- The compiler runs the project-local `drizzle-kit generate` binary during compilation to produce SQL migration files. On subsequent compiles, it uses `existingFiles` (your current migration state) to generate only incremental changes.
364
+ The CLI runs the project-local `drizzle-kit generate` binary during compile to
365
+ produce SQL migration files. Generation happens **on your machine**, against
366
+ migration state that never leaves it — the compiler emits the schema that
367
+ drizzle diffs against, but never sees your migration history.
368
+
369
+ What the compile request carries instead of that history is two derived facts
370
+ about your prior state: the tables already deployed on a primary key that isn't
371
+ `id` (so a generated migration never proposes rewriting one), and whether the
372
+ Postgres audit schema was ever emitted (so a shrinking feature surface can't
373
+ generate a migration that drops the append-only forensic sink). Both are a few
374
+ hundred bytes, and neither grows with the age of your project.
375
+
376
+ Generation runs in a staging workspace and is committed only after it succeeds,
377
+ so a failed compile leaves your migration tree untouched. Already-applied files
378
+ are never rewritten: the run aborts if anything pre-existing would be modified
379
+ or removed.
365
380
 
366
381
  If a compiler response returns migration generation as a post-compile command,
367
382
  the command matches `build.packageManager`: `npm exec`, `pnpm exec`, `yarn exec`,
@@ -392,16 +407,19 @@ Migration and report artifacts are written to the `quickback/` state directory:
392
407
  Unlike `src/`, the `quickback/drizzle/` tree is **not** hermetic — it is history,
393
408
  and history is only ever appended to or superseded.
394
409
 
395
- To keep compile payloads small, the CLI uploads every migration `.sql` and
396
- `_journal.json` but only the **newest** `NNNN_snapshot.json` per meta directory.
397
- The compiler's response is therefore a partial view by construction, and a file
398
- missing from it carries no instruction. Compile removes a file only when the
399
- compiler was actually shown it and left it out; anything never uploaded — every
400
- historical snapshot — is preserved untouched.
410
+ Because generation is local, the compile response contains no migration files at
411
+ all and therefore carries no instruction to remove one. New migrations are
412
+ appended to the tree; nothing already there is rewritten.
401
413
 
402
- When something is removed, the previous tree is archived to
403
- `quickback/.archives/drizzle-<timestamp>/` (the three most recent are kept) and
404
- the compile prints what it removed and what it preserved.
414
+ That guarantee is enforced rather than assumed. The generator runs against a
415
+ staged copy and compares a checksum inventory of the tree before and after: if
416
+ any pre-existing `.sql`, snapshot, or journal tag changed or disappeared, the
417
+ compile fails with `MIGRATION_STATE_CHANGED` instead of committing. This matters
418
+ most on D1, which records applied migrations **by path** — a rewritten filename
419
+ is drift on a live database with no clean fix-forward.
420
+
421
+ Only `meta/_journal.json` is expected to change, because that is where a new
422
+ entry lands.
405
423
 
406
424
  > If `quickback migrations doctor` reports snapshot drift — more journal entries
407
425
  > than snapshot files — that drift came from your project's history, not from
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.60.4",
3
+ "version": "0.60.5",
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",
@@ -13,6 +13,7 @@ The generated API returns structured error responses with consistent fields acro
13
13
  | `401` | Unauthorized | Missing or expired authentication |
14
14
  | `403` | Forbidden | Access denied (wrong role, condition failed) or firewall blocked it |
15
15
  | `404` | Not Found | Firewall blocked the record on a resource that set `firewallErrorMode: 'hide'` (or the route doesn't exist) |
16
+ | `405` | Method Not Allowed | The path is a real route, but not for this verb — the response carries an `Allow` header listing the methods it does accept |
16
17
  | `409` | Conflict | Unique constraint hit, or a duplicate [`Idempotency-Key`](/platform/api-contract#idempotency-key) still in flight |
17
18
  | `412` | Precondition Failed | `If-Match` revision mismatch — [changesets](/define/changesets) and plain single-record `PATCH`/`PUT`/`DELETE` |
18
19
  | `422` | Unprocessable | `Idempotency-Key` reused with a different request or principal |
@@ -175,6 +175,90 @@ If you enable `cms` and `account` without custom domains, everything is served o
175
175
 
176
176
  This is the simplest setup — no DNS configuration needed, no cross-subdomain cookies. Auth cookies work naturally because everything is same-origin.
177
177
 
178
+ ## Named Environments
179
+
180
+ A project with [named environments](/platform/database/neon#named-cloudflare-deployment-environments) deploys the same bundle to several Workers (`wrangler deploy -e dev`, `-e prod`), and each target needs its own hostnames. Two rules make that safe:
181
+
182
+ 1. **The base config emits no `routes` block.** Wrangler treats `routes` as an *inheritable* key — a top-level block would be inherited by any `[env.*]` that declares none, and `deploy -e dev` would rebind the production hostname to the dev Worker.
183
+ 2. **Every environment claims every hostname the top level generates.** The top-level domain config still defines the *shape* — which roles exist and what the Worker bakes in for each — and `environments.<name>.domains` supplies the actual hostnames.
184
+
185
+ ```typescript
186
+ // quickback.config.ts — the worker block of each environment is omitted here;
187
+ // see Named deployment environments for the full target contract.
188
+ api: { domain: "api.attend.vip" }, // the SHAPE: this project has an API hostname
189
+ environments: {
190
+ dev: { domains: { api: "api-dev.attend.vip" }, worker: { /* … */ } },
191
+ prod: { domains: { api: "api.attend.vip" }, worker: { /* … */ } },
192
+ },
193
+ ```
194
+
195
+ ```toml title="wrangler.toml (generated)"
196
+ # no top-level routes — each target owns its own
197
+ [env.dev]
198
+ routes = [
199
+ { pattern = "api-dev.attend.vip", custom_domain = true },
200
+ ]
201
+
202
+ [env.prod]
203
+ routes = [
204
+ { pattern = "api.attend.vip", custom_domain = true },
205
+ ]
206
+ ```
207
+
208
+ Each `domains` key maps 1:1 to a top-level source:
209
+
210
+ | `domains` key | Claims |
211
+ |---------------|--------|
212
+ | `primary` | `domain` |
213
+ | `api` | `api.domain` |
214
+ | `auth` | `auth.domain` |
215
+ | `cms` | `cms.domain` |
216
+ | `account` | `account.domain` |
217
+ | `admin` | `account.adminDomain` |
218
+ | `webhook` | the derived `webhook.{baseDomain}` route |
219
+ | `apps.<name>[i]` | `apps.<name>.domain` (index `0`) and each `aliasDomains` entry (`1`+) |
220
+ | `routes[i]` | `providers.runtime.config.routes[i]` |
221
+
222
+ When the project generates exactly **one** hostname, `domain: "api-dev.attend.vip"` is accepted as shorthand for the single role.
223
+
224
+ `domains: 'none'` marks a workers.dev-only target. It emits `routes = []` rather than omitting the block, so inheritance cannot hand that target a sibling's custom domain.
225
+
226
+ The compile fails, naming the config path to fix, when an environment leaves a generated hostname unclaimed, claims a key the top level does not generate, or claims a hostname another target already owns.
227
+
228
+ ### The unified hostname per target
229
+
230
+ The auto-inferred `quickback.{baseDomain}` host — where every surface coexists and `/` redirects to `/cms/` — is inferred for named-environment projects too, once **per target**:
231
+
232
+ | Target | Claims | Inferred unified host |
233
+ |--------|--------|-----------------------|
234
+ | `dev` | `api-dev.attend.vip` | `quickback-dev.attend.vip` |
235
+ | `prod` | `api.attend.vip` | `quickback-prod.attend.vip` |
236
+
237
+ The single-target name can't carry over verbatim: every environment would infer the same `quickback.attend.vip` from a shared base domain, and one custom domain cannot belong to two Workers. The environment key is the only thing that makes the name unique by construction.
238
+
239
+ It's a hyphen rather than a new label (`quickback-dev.attend.vip`, not `quickback.dev.attend.vip`) because Cloudflare's Universal SSL covers exactly one level of subdomain — the extra label would deploy without a certificate.
240
+
241
+ Set `domains.primary` to override the name on any target. That's how one environment keeps the bare hostname a single-target project would have inferred:
242
+
243
+ ```typescript
244
+ prod: { domains: { api: "api.attend.vip", primary: "quickback.attend.vip" } },
245
+ ```
246
+
247
+ Inference is skipped when the project declares `domain` explicitly (that becomes a real `primary` source each target claims by hand), when the top level configures no domains at all, and for a `domains: 'none'` target.
248
+
249
+ > **These are real custom domains**
250
+ >
251
+ > Every inferred hostname is emitted as a `custom_domain` route, so Wrangler provisions the DNS record on deploy — same as the single-target `quickback.{baseDomain}` has always done. The zone has to be on the deploying Cloudflare account.
252
+
253
+
254
+ Each target's unified host joins `trustedOrigins` and the CSP origin list, but does **not** become the target's `BETTER_AUTH_URL` — that stays on the auth or API hostname, matching what a single-target project resolves.
255
+
256
+ ### One bundle, several hostnames
257
+
258
+ Every environment runs the *same* compiled Worker, so hostname-sensitive behavior is baked once, at compile time, against every environment's hostnames at once. `domains` is what makes that work: an environment's `cms` hostname gets the CMS domain's API-route block, its `api` hostname gets the `/v1/*` rewriter, its app hostnames serve the app SPA, and all of them join `trustedOrigins`, the CSP origin list, and cross-subdomain cookie inference.
259
+
260
+ Each target's `BETTER_AUTH_URL` also defaults to the hostname it claims (unified → auth → API → UI), so a dev deploy authenticates against its own origin instead of production's. Setting `worker.vars.BETTER_AUTH_URL` explicitly still wins.
261
+
178
262
  ## Preview Deploys
179
263
 
180
264
  The same compiled bundle can be deployed to additional hostnames — preview environments, staging, per-PR URLs — without recompiling. Set the `EXTRA_APP_HOSTS` env var on the deploy target (a comma-separated list of hostnames) and the worker treats each one like an entry in `apps[*].domain`:
@@ -223,6 +223,7 @@ Key properties:
223
223
  - **The relationship table's own firewall is AND'd into the subquery.** Soft-deleting a `event_guests` row revokes access immediately; cross-tenant relationship rows can't grant access.
224
224
  - **Anonymous callers fail closed.** `ctx.userId` is null-guarded; the subquery short-circuits to `WHERE 1 = 0` for unauthenticated requests.
225
225
  - **The relationship table must be tenant-scoped** (`firewall: { exception: true }` is rejected at compile time on relationship tables).
226
+ - **The relationship table needs its own `defineTable`.** That `<event_guests' own firewall>` line in the SQL above is the table's generated firewall helper — a bare Drizzle export has none, so a `from:` table with no `export default defineTable(...)` is a compile error naming the table.
226
227
 
227
228
  See [Access — relationships](/define/relationships#authzrelationships) for the full `authz.relationships` shape and role-binding patterns.
228
229
 
@@ -53,6 +53,41 @@ export default defineConfig({
53
53
  });
54
54
  ```
55
55
 
56
+ > **The `from:` table needs its own defineTable**
57
+ >
58
+ > A relationship resolves through the `from:` table's **generated resource module**
59
+ > (`<table>.resource.ts`) — that's what supplies the firewall the subquery AND's in. The
60
+ > compiler emits that module only for tables with an `export default defineTable(...)`, so a
61
+ > join table declared as a bare Drizzle export is a compile error naming the table:
62
+ >
63
+ > ```typescript
64
+ > // features/conversations/conversation_members.ts
65
+ > export const conversation_members = sqliteTable('conversation_members', {
66
+ > id: text('id').primaryKey(),
67
+ > userId: text('user_id').notNull(),
68
+ > conversationId: text('conversation_id').notNull(),
69
+ > organizationId: text('organization_id').notNull(),
70
+ > // ── quickback:audit (compiler-managed — edits are validated, not merged) ──
71
+ > // Raw Drizzle tables spell the managed columns out; `...q.audit()` is
72
+ > // q-DSL only. See [Escape hatches](/define/escape-hatches).
73
+ > createdAt: text('created_at').notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString()),
74
+ > modifiedAt: text('modified_at').notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString()).$onUpdate(() => new Date().toISOString()),
75
+ > createdBy: text('created_by'),
76
+ > modifiedBy: text('modified_by'),
77
+ > deletedAt: text('deleted_at'),
78
+ > deletedBy: text('deleted_by'),
79
+ > });
80
+ >
81
+ > // Required — without this, `from: 'conversation_members'` cannot compile.
82
+ > export default defineTable(conversation_members, {
83
+ > firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
84
+ > });
85
+ > ```
86
+ >
87
+ > Adding `defineTable` does not force a public API onto the join table — gate or omit its
88
+ > `read` / `crud` blocks as you would any other table. What it supplies is the firewall.
89
+
90
+
56
91
  ### Using relationship-roles in resources
57
92
 
58
93
  Resource definitions reference declared roles by name in `roles: [...]` arrays exactly like BA roles or pseudo-roles. The compiler rewrites the access tree at build time so the runtime route does an inline relationship lookup against the declared table.
@@ -92,6 +92,13 @@ wrangler d1 migrations apply DB --remote
92
92
 
93
93
  Migration files are generated in `quickback/drizzle/` and version-controlled with your code. You never need to manually generate migrations—just define your schema and compile.
94
94
 
95
+ Generation runs locally: `quickback compile` invokes your project's own
96
+ `drizzle-kit` against migration state that never leaves your machine. Note that
97
+ generating a migration is not the same as applying one — `_journal.json` records
98
+ which migration files *exist*, while D1's own `d1_migrations` table records which
99
+ have actually *run* against a given database. `wrangler d1 migrations apply` is
100
+ what moves a migration from the first list to the second.
101
+
95
102
  ## wrangler.toml Bindings
96
103
 
97
104
  The compiler generates D1 bindings in `wrangler.toml` automatically. To get production-ready IDs in the output, set them in your `quickback.config.ts`:
@@ -227,6 +234,13 @@ The contract fails closed:
227
234
  - `requiredSecrets` and `rateLimits` must match the generated runtime
228
235
  inventory exactly, so adding a feature tells you which override changed.
229
236
  - `workersDev: true` and `previewUrls: false` must be explicit on each target.
237
+ - Every custom domain the config generates must be claimed per target via
238
+ `domains` (`{ api: "api-dev.example.com" }`, or the bare `domain` shorthand
239
+ for a single-hostname project). Quickback emits no top-level `routes` block
240
+ here — Wrangler inherits that key, so a shared one would rebind production's
241
+ hostname on a dev deploy. The unified `quickback.{baseDomain}` host is
242
+ inferred per target as `quickback-<env>.{baseDomain}`. See
243
+ [Named Environments](/configure/domains#named-environments).
230
244
 
231
245
  Set secrets per target: `wrangler secret put BETTER_AUTH_SECRET --env dev`.
232
246
 
@@ -208,11 +208,18 @@ The environment contract is intentionally exact and fails closed:
208
208
  `wrangler secret put <NAME> --env dev` (and again for `prod`).
209
209
  - Include `sendEmail: { name: "EMAIL" }` when the generated runtime uses
210
210
  Cloudflare Email Service; omit it when email is not generated.
211
- - Every source of a generated top-level custom route is currently rejected for
212
- named targets: `providers.runtime.config.routes`, `domain`, CMS/Account/Admin
213
- domains, `auth.domain`, `api.domain`, and hostname-mounted app domains and
214
- aliases. Quickback will add explicit per-environment route overrides before
215
- opening that gate.
211
+ - Custom domains and routes are owned **per target**. Quickback emits no
212
+ top-level `routes` block for a named-environment project — Wrangler inherits
213
+ that key, so a shared block would let `deploy -e dev` rebind the production
214
+ hostname — and every generated source (`providers.runtime.config.routes`,
215
+ `domain`, CMS/Account/Admin domains, `auth.domain`, `api.domain`, app domains
216
+ and their aliases, and the derived `webhook.{baseDomain}` route) must be
217
+ claimed by each environment through `domains`. The unified
218
+ `quickback.{baseDomain}` host is inferred per target as
219
+ `quickback-<env>.{baseDomain}`, overridable with `domains.primary`. See
220
+ [Named Environments](/configure/domains#named-environments) for the key-by-key
221
+ mapping, the single-hostname `domain` shorthand, and the `domains: 'none'`
222
+ workers.dev-only opt-out.
216
223
 
217
224
  Generated `npm run dev` selects the `dev` target (`wrangler dev --env dev`).
218
225
  Quickback omits the bare `deploy` script for named-environment projects and
@@ -26,6 +26,8 @@ When you click **Deploy this app**, the pipeline runs four phases and reports ea
26
26
  3. **Package** — the project recompiles with the real resource ids folded in and is bundled into Worker modules (plus your CMS/Account SPA assets, when enabled). Every byte is hash-verified against the manifest before anything is uploaded.
27
27
  4. **Finalize** — migrations apply, the Worker uploads with its bindings, secrets are set, and the `workers.dev` route is enabled. Start probes the URL and only shows **Live** once it actually answers.
28
28
 
29
+ Provision hands back a one-time approval that finalize must present, so the upload can only ever be the one that was approved — being signed in is deliberately not enough on its own. The approval is good for an hour, which no normal deploy comes close to.
30
+
29
31
  A typical deploy takes one to two minutes, most of it compilation.
30
32
 
31
33
  ## What deploys
@@ -92,6 +94,7 @@ The deploy card is the whole connection UI: it reports the state of your Cloudfl
92
94
  | "Couldn't reach the deploy service…" | Transient failure talking to Quickback or Cloudflare | **Try again** |
93
95
  | "Browser deploys aren't fully configured on the server yet" | A deploy-service misconfiguration, not anything on your side | Use [`quickback deploy`](/start/deploy) for now |
94
96
  | "Too many deploys in a minute" | More than 5 provisions in a minute on one account | Wait for the `Retry-After` window and click Deploy again |
97
+ | "This deploy's approval was no longer valid…" | Provision approves one specific upload, for an hour. A deploy that outlives its approval is refused at the finalize step — nothing was uploaded | **Try again** — a fresh deploy re-provisions and re-approves |
95
98
 
96
99
  Deploy is disabled while a reconnect is pending, so a deploy never starts on a connection that can't finish it. If a connection dies *during* a deploy, the failure comes back as a reconnect prompt rather than a raw error — the deploy is safe to re-run after reconnecting, because provisioning adopts and migrations apply once.
97
100
 
@@ -361,7 +361,22 @@ Routes are mounted under `/api/v1/{feature}` for the default contract or
361
361
 
362
362
  ## Migrations
363
363
 
364
- The compiler runs the project-local `drizzle-kit generate` binary during compilation to produce SQL migration files. On subsequent compiles, it uses `existingFiles` (your current migration state) to generate only incremental changes.
364
+ The CLI runs the project-local `drizzle-kit generate` binary during compile to
365
+ produce SQL migration files. Generation happens **on your machine**, against
366
+ migration state that never leaves it — the compiler emits the schema that
367
+ drizzle diffs against, but never sees your migration history.
368
+
369
+ What the compile request carries instead of that history is two derived facts
370
+ about your prior state: the tables already deployed on a primary key that isn't
371
+ `id` (so a generated migration never proposes rewriting one), and whether the
372
+ Postgres audit schema was ever emitted (so a shrinking feature surface can't
373
+ generate a migration that drops the append-only forensic sink). Both are a few
374
+ hundred bytes, and neither grows with the age of your project.
375
+
376
+ Generation runs in a staging workspace and is committed only after it succeeds,
377
+ so a failed compile leaves your migration tree untouched. Already-applied files
378
+ are never rewritten: the run aborts if anything pre-existing would be modified
379
+ or removed.
365
380
 
366
381
  If a compiler response returns migration generation as a post-compile command,
367
382
  the command matches `build.packageManager`: `npm exec`, `pnpm exec`, `yarn exec`,
@@ -392,16 +407,19 @@ Migration and report artifacts are written to the `quickback/` state directory:
392
407
  Unlike `src/`, the `quickback/drizzle/` tree is **not** hermetic — it is history,
393
408
  and history is only ever appended to or superseded.
394
409
 
395
- To keep compile payloads small, the CLI uploads every migration `.sql` and
396
- `_journal.json` but only the **newest** `NNNN_snapshot.json` per meta directory.
397
- The compiler's response is therefore a partial view by construction, and a file
398
- missing from it carries no instruction. Compile removes a file only when the
399
- compiler was actually shown it and left it out; anything never uploaded — every
400
- historical snapshot — is preserved untouched.
410
+ Because generation is local, the compile response contains no migration files at
411
+ all and therefore carries no instruction to remove one. New migrations are
412
+ appended to the tree; nothing already there is rewritten.
401
413
 
402
- When something is removed, the previous tree is archived to
403
- `quickback/.archives/drizzle-<timestamp>/` (the three most recent are kept) and
404
- the compile prints what it removed and what it preserved.
414
+ That guarantee is enforced rather than assumed. The generator runs against a
415
+ staged copy and compares a checksum inventory of the tree before and after: if
416
+ any pre-existing `.sql`, snapshot, or journal tag changed or disappeared, the
417
+ compile fails with `MIGRATION_STATE_CHANGED` instead of committing. This matters
418
+ most on D1, which records applied migrations **by path** — a rewritten filename
419
+ is drift on a live database with no clean fix-forward.
420
+
421
+ Only `meta/_journal.json` is expected to change, because that is where a new
422
+ entry lands.
405
423
 
406
424
  > If `quickback migrations doctor` reports snapshot drift — more journal entries
407
425
  > than snapshot files — that drift came from your project's history, not from