@quickback-dev/cli 0.51.0 → 0.51.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 (82) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +34 -19
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +19 -19
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/lib/action-harvest.d.ts +35 -4
  8. package/dist/lib/action-harvest.d.ts.map +1 -1
  9. package/dist/lib/action-harvest.js +233 -50
  10. package/dist/lib/action-harvest.js.map +1 -1
  11. package/dist/lib/action-harvest.test.js +130 -2
  12. package/dist/lib/action-harvest.test.js.map +1 -1
  13. package/dist/lib/auth.d.ts +6 -0
  14. package/dist/lib/auth.d.ts.map +1 -1
  15. package/dist/lib/auth.js +18 -1
  16. package/dist/lib/auth.js.map +1 -1
  17. package/dist/lib/auth.test.d.ts +2 -0
  18. package/dist/lib/auth.test.d.ts.map +1 -0
  19. package/dist/lib/auth.test.js +19 -0
  20. package/dist/lib/auth.test.js.map +1 -0
  21. package/dist/lib/compile-next-steps.d.ts +4 -0
  22. package/dist/lib/compile-next-steps.d.ts.map +1 -0
  23. package/dist/lib/compile-next-steps.js +69 -0
  24. package/dist/lib/compile-next-steps.js.map +1 -0
  25. package/dist/lib/compile-next-steps.test.d.ts +2 -0
  26. package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
  27. package/dist/lib/compile-next-steps.test.js +76 -0
  28. package/dist/lib/compile-next-steps.test.js.map +1 -0
  29. package/dist/lib/file-loader.d.ts.map +1 -1
  30. package/dist/lib/file-loader.js +1 -0
  31. package/dist/lib/file-loader.js.map +1 -1
  32. package/dist/lib/file-writer.d.ts +1 -1
  33. package/dist/lib/file-writer.d.ts.map +1 -1
  34. package/dist/lib/file-writer.js +20 -5
  35. package/dist/lib/file-writer.js.map +1 -1
  36. package/dist/lib/file-writer.test.d.ts +2 -0
  37. package/dist/lib/file-writer.test.d.ts.map +1 -0
  38. package/dist/lib/file-writer.test.js +90 -0
  39. package/dist/lib/file-writer.test.js.map +1 -0
  40. package/dist/lib/shell.test.d.ts +2 -0
  41. package/dist/lib/shell.test.d.ts.map +1 -0
  42. package/dist/lib/shell.test.js +39 -0
  43. package/dist/lib/shell.test.js.map +1 -0
  44. package/dist/skill/docs/changelog.md +401 -1
  45. package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  46. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  47. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  48. package/dist/skill/docs/compiler/config/auth.md +17 -2
  49. package/dist/skill/docs/compiler/config/index.md +271 -12
  50. package/dist/skill/docs/compiler/config/output.md +49 -3
  51. package/dist/skill/docs/compiler/config/providers.md +12 -1
  52. package/dist/skill/docs/compiler/config/variables.md +5 -0
  53. package/dist/skill/docs/compiler/definitions/access.md +7 -0
  54. package/dist/skill/docs/compiler/definitions/actions.md +156 -9
  55. package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
  56. package/dist/skill/docs/compiler/definitions/schema.md +12 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  59. package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
  60. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  61. package/dist/skill/docs/stack/cms/schema-format.md +4 -2
  62. package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
  63. package/package.json +1 -1
  64. package/src/skill/docs/changelog.md +401 -1
  65. package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  66. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  67. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  68. package/src/skill/docs/compiler/config/auth.md +17 -2
  69. package/src/skill/docs/compiler/config/index.md +271 -12
  70. package/src/skill/docs/compiler/config/output.md +49 -3
  71. package/src/skill/docs/compiler/config/providers.md +12 -1
  72. package/src/skill/docs/compiler/config/variables.md +5 -0
  73. package/src/skill/docs/compiler/definitions/access.md +7 -0
  74. package/src/skill/docs/compiler/definitions/actions.md +156 -9
  75. package/src/skill/docs/compiler/definitions/firewall.md +6 -1
  76. package/src/skill/docs/compiler/definitions/schema.md +12 -0
  77. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  78. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  79. package/src/skill/docs/stack/account-ui/hooks.md +104 -1
  80. package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  81. package/src/skill/docs/stack/cms/schema-format.md +4 -2
  82. package/src/skill/docs/stack/cms/schema-registry.md +4 -2
@@ -2,6 +2,406 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Generated builds no longer rewrite the auth schema
6
+
7
+ Generated Better Auth projects now run `tsc` directly from `npm run build`.
8
+ `quickback compile` already generates, qualifies, and envelopes
9
+ `src/auth/schema.ts`; invoking `auth:schema` again during every build rewrote
10
+ that compiler-owned artifact and made an otherwise clean release worktree
11
+ dirty. The explicit `auth:schema` diagnostic command remains available, while
12
+ normal build, Wrangler, and deployment preflight paths are source-read-only.
13
+ When recompiling an existing project, compiler-owned `package.json` script
14
+ names now converge to their current generated commands while unrelated custom
15
+ scripts are preserved. This upgrades projects whose previous generated
16
+ `build` script still invoked `auth:schema`.
17
+
18
+ ### Non-cross-tenant unsafe actions preserve delegated RLS claims
19
+
20
+ Generated Neon handlers now reserve `createServiceDb` for actions that
21
+ explicitly enable `unsafe.crossTenant`. An action that enables raw database
22
+ access with `crossTenant: false` keeps the request database, so organization
23
+ and delegated-principal claims survive into Hyperdrive transactions instead of
24
+ being cleared by the service-role preamble. True cross-tenant sysadmin actions
25
+ retain their audited RLS bypass.
26
+
27
+ Neon Hyperdrive guidance now also calls out Postgres' `SELECT … FOR UPDATE`
28
+ authorization rule: a locked row must pass both `SELECT` and `UPDATE` policies.
29
+ Delegated actions should use ordinary selects for read-only eligibility tables
30
+ and lock only mutable rows they are authorized to update. A PGlite regression
31
+ proves that ordinary delegated reads remain visible while the generated
32
+ restrictive update fence blocks an unauthorized row lock.
33
+
34
+ ### Atomic email-OTP auth routing no longer recurses on ordinary requests
35
+
36
+ The generated atomic email-OTP wrapper now captures and binds Better Auth's
37
+ original request handler before replacing the public `handler` property.
38
+ Session reads and every other non-atomic auth route therefore forward to Better
39
+ Auth exactly once instead of re-entering the wrapper until the Worker exhausts
40
+ its call stack. The exact email-OTP sign-in route retains its transactional
41
+ admission and rollback behavior.
42
+
43
+ ### Generated Better Auth CLI dependencies no longer retain vulnerable Lodash
44
+
45
+ Better Auth projects now emit a root npm override for `lodash@4.18.1`. This
46
+ keeps the supported stable `auth@1.6.x` CLI and its `better-auth` executable,
47
+ while lifting the CLI's dev-only Prisma parser chain off Lodash releases
48
+ affected by the 2026 code-injection and prototype-pollution advisories. Runtime
49
+ Better Auth packages and generated authentication behavior are unchanged.
50
+
51
+ The CLI now merges generated npm overrides explicitly when recompiling an
52
+ existing project: unrelated user overrides remain, while compiler-owned
53
+ security pins win a conflict. Recompile and reinstall dependencies to refresh
54
+ the project lockfile. `npm audit --omit=dev` remains the production dependency
55
+ view; upstream development-server advisories may still appear separately.
56
+
57
+ ### Postgres constraint replacements apply in dependency-safe order
58
+
59
+ Neon migration post-processing now orders both halves of a Drizzle constraint
60
+ replacement. A dependent foreign key is dropped before its referenced unique
61
+ or primary-key constraint, then the replacement key is added before the
62
+ foreign key that consumes it. This prevents Postgres `2BP01` failures when
63
+ Drizzle emits the parent key drop first, while preserving byte-identical output
64
+ for already-correct migrations and the relative order of unrelated statements.
65
+
66
+ ### Schema registry output is byte-reproducible
67
+
68
+ `schema-registry.json` no longer includes the wall-clock `generatedAt` field.
69
+ Its remaining metadata and schema content are derived entirely from compiler
70
+ inputs, so consecutive compiles of identical logical input now produce the
71
+ same registry bytes. This makes artifact hashes, caches, and deployment diffs
72
+ stable without timestamp normalization.
73
+
74
+ ### Generated auth and discovery surfaces now remain truthful and type-safe
75
+
76
+ Atomic email-OTP generation now imports and invokes
77
+ `before-email-otp-activate.ts` exactly once and preserves the transaction's
78
+ real Drizzle `select` capability in the hook context. Strict generated
79
+ TypeScript therefore accepts both the base Neon service database and its
80
+ interactive transaction without erasing the hook's read contract.
81
+
82
+ Contract-v2 projects that omit `auth.jwt` no longer advertise the disabled
83
+ Quickback JWT fast path in `llms.txt` or RFC 8414 metadata. Bearer-JWT guidance,
84
+ the fallback `/api/v2/token` endpoint, and JWT scopes are emitted only when the
85
+ corresponding JWT surface exists; real Better Auth OAuth-provider discovery is
86
+ unchanged.
87
+
88
+ Cloudflare Email callbacks now all enter the shared credential-delivery
89
+ scheduler exactly once. The scheduler anchors the observed rejection with
90
+ `waitUntil`, emits the metadata-only `auth.credential_delivery_failed` event,
91
+ and never leaks the provider error. Generated CRUD routes also keep delegated
92
+ principal and account authority disjoint: `?organizationId=` is rejected for a
93
+ delegated principal instead of synthesizing `activeOrgId` on its context. This
94
+ closes both the authority ambiguity and the generated `AppContext` union type
95
+ errors.
96
+
97
+ ### Email-OTP activation can be admitted atomically in the API layer
98
+
99
+ Contract-v2 Cloudflare projects using one Neon Hyperdrive database can opt the
100
+ exact Better Auth `POST /sign-in/email-otp` handler into an interactive
101
+ transaction with `atomicAuthRoutes: ["emailOtpSignIn"]`. The paired recognized
102
+ hook, `quickback/hooks/before-email-otp-activate.ts`, receives a proven dormant
103
+ user `{ userId, email, user }` plus transaction-bound `db` / full `schema` and
104
+ `authDb` / `authSchema` handles. Quickback owns only identity proof and atomic
105
+ orchestration; application admission, status, event, pass, and eligibility
106
+ rules remain authored in the project API hook.
107
+
108
+ The hook executes after OTP validation but in Better Auth's
109
+ `databaseHooks.user.update.before`, before the user update lock. This preserves
110
+ application-first lock ordering and avoids the user-to-application inversion a
111
+ session-create hook would introduce. Unknown-email signup must be disabled;
112
+ already-verified users do not rerun dormant activation.
113
+
114
+ The generated handler rebuilds Better Auth over the transaction handle, so OTP
115
+ consumption, project hook writes, the `emailVerified` update, and session insert
116
+ commit together. Admission denial, a non-ok response after activation starts,
117
+ and any 5xx response throw a private rollback sentinel. Expected policy denial
118
+ returns a generic 403. Operational rollback emits the metadata-only
119
+ `auth.atomic_email_otp_operational_rollback` event and returns a generic 503,
120
+ without exposing raw errors. Ordinary invalid-OTP 4xx responses still commit
121
+ Better Auth's attempt accounting, and the OTP-send route remains outside the
122
+ transaction. Unsupported contracts, runtimes, database modes,
123
+ missing/duplicated config, enabled signup,
124
+ and a hook/config mismatch now fail at compile time.
125
+
126
+ ### Neon migrations can declare cross-schema foreign keys
127
+
128
+ Neon projects can now declare fully qualified, single-column or composite
129
+ foreign keys under `compiler.migrations.foreignKeys`. Each entry names the
130
+ constraint, source and target schema/table/column tuples, and explicit
131
+ `onDelete` / `onUpdate` actions. The compiler rejects unsafe identifiers,
132
+ mismatched tuple arity, duplicate or ambiguous declarations, unknown keys,
133
+ and non-Neon providers before generating SQL.
134
+
135
+ Declared constraints are sorted deterministically and folded into Quickback's
136
+ content-addressed Postgres journal after the Drizzle schema migration. A new
137
+ constraint is added `NOT VALID` and then validated, so existing orphan rows
138
+ fail the migration; replay verifies an exact catalog match and rejects a
139
+ same-named constraint with different semantics. This surface enforces
140
+ relational integrity only—business rules remain in generated or authored API
141
+ actions, not database triggers.
142
+
143
+ ### Compile completion steps honor the Neon connection mode
144
+
145
+ The CLI's successful-compile footer now distinguishes Neon HTTP from
146
+ Hyperdrive. HTTP projects retain the direct `DATABASE_URL` Worker setup.
147
+ Hyperdrive projects show `DATABASE_MIGRATION_URL` only as a local or CI
148
+ migration input, point local development at the configured Hyperdrive
149
+ `localConnectionString`, and never recommend deploying `DATABASE_URL` as a
150
+ Worker secret.
151
+
152
+ Named Hyperdrive environments also show their configured Neon branches,
153
+ required-secret inventories, and explicit Wrangler `--env` targets. The footer
154
+ no longer suggests the unnamed `.env.neon` / `.dev.vars` workflow or a bare
155
+ deploy for an isolated `dev` / `prod` setup.
156
+
157
+ ### Cloudflare email delivery and named Neon targets fail visibly and deploy explicitly
158
+
159
+ Generated Cloudflare email code now uses the native Workers `SendEmail`,
160
+ `EmailAddress`, attachment, and `EmailSendResult` contracts. The Workers
161
+ builder keeps its camel-case fields and `{ email, name }` address shape, while
162
+ the REST transport retains its separate snake-case fields and `{ address,
163
+ name }` shape. Generated projects move to `@cloudflare/workers-types` v5 with
164
+ Wrangler 4.110 so the binding and result types agree without `any` casts.
165
+
166
+ Every Better Auth email callback now creates an observed delivery promise. On
167
+ Workers, the callback hands that still-rejecting promise to
168
+ `executionCtx.waitUntil(...)` and returns after the task is accepted; outside a
169
+ request lifecycle it returns the promise for the caller to await. Failures emit
170
+ only a structured generic event, never provider error content, and remain
171
+ rejected instead of being detached or swallowed. SES and SNS background sends
172
+ use the same lifecycle rule.
173
+
174
+ Neon Hyperdrive's generated postgres.js client now caps each request-scoped
175
+ pool at five connections. Named environments gain explicit `deploy:dev` and
176
+ `deploy:prod` package scripts (mapped to their configured Wrangler environment
177
+ names), while the unsafe bare `deploy` script remains absent and migrations
178
+ remain a separate target-owned step.
179
+
180
+ ### Contract v2 auth and Neon authority boundaries are fail-closed
181
+
182
+ Contract-v2 projects no longer emit Quickback's generic JWT mint endpoint,
183
+ JWT helper, middleware verification/mint fast-path, or related imports unless
184
+ the project explicitly declares `auth.jwt`. Contract v1 retains its existing
185
+ default for compatibility. Adding `auth.jwt: {}` to a v2 config opts back into
186
+ the custom Quickback JWT with its normal default settings.
187
+
188
+ Configured delegated authenticators now produce closed TypeScript unions in
189
+ both generated `AppContext` and Neon RLS context. Request contexts contain only
190
+ resolved principal variants; the compiler-internal credential-lookup variants
191
+ exist only in the database context. Delegated standalone actions do not require
192
+ Better Auth `activeOrgId` / `activeTeamId` before their declared principal
193
+ access tree runs, and their context cannot acquire account, organization, team,
194
+ membership, or scope authority.
195
+
196
+ On Cloudflare + Neon, the API-key organization membership lookup now runs with
197
+ request-scoped user/org RLS claims before it stamps verified organization and
198
+ role authority into `AppContext`. Generated security migrations also converge
199
+ direct privilege drift: the audit schema/table revoke all direct grants from
200
+ `PUBLIC`, the runtime, and admin before restoring their exact write-only/admin
201
+ sets, while the Drizzle journal schema/table/sequences and database `CREATE`
202
+ capability explicitly revoke `PUBLIC` and runtime access before granting the
203
+ migration role.
204
+
205
+ ### Standalone action routes preserve their exact authority context
206
+
207
+ Generated standalone routes now pass each action the context and scoped
208
+ database types inferred from that action's own `execute` signature. Account actions therefore receive a
209
+ required account identity, while `event_pass`, `event_delegate`, and other
210
+ delegated-principal actions retain their exact principal literal at the route
211
+ boundary. Relationship `loads` / `exposeAs` hydration is intersected with that
212
+ authority context, including required shared targets and optional distinct
213
+ multi-lane targets, instead of replacing it with the broad application
214
+ context.
215
+
216
+ The same boundary keeps ordinary request databases and temporary
217
+ service-role-backed scoped databases assignable to the generated Hyperdrive
218
+ action helper without widening the handler's schema-aware `db` type.
219
+
220
+ Generated principal-auth identity guards also emit explicit strict TypeScript
221
+ parameter and return types. Contract-v2 Cloudflare + Neon output no longer
222
+ fails `tsc` on implicit-`any` guard parameters.
223
+
224
+ ### Parameterized actions keep complete v2 schema harvests
225
+
226
+ The action-input harvest plan now converts Hono-style `:param` segments to the
227
+ OpenAPI `{param}` form for standalone actions and parameterized resource paths.
228
+ Previously the CLI could harvest every schema successfully, but the compiler
229
+ could apply only parameter-free actions because it looked up parameterized
230
+ operations under the wrong OpenAPI key. Contract v2 now counts and patches the
231
+ same canonical path emitted by OpenAPI and MCP.
232
+
233
+ Generated standalone-action routes also remove template-only trailing spaces
234
+ when optional audit blocks are absent, keeping regenerated source diffs clean.
235
+
236
+ ### Action-schema harvest uses the generated runtime dependency tree
237
+
238
+ The CLI now resolves action-harvest dependencies from the configured
239
+ `build.outputDir/node_modules` before unrelated ancestor installs. This fixes
240
+ isolated projects that keep authored definitions under `quickback/` and the
241
+ generated runtime under a sibling directory such as `src/`: their actions can
242
+ use the runtime's Zod 4 and Drizzle installation without adding workspace-root
243
+ symlinks. An older user-level or monorepo-level Zod can no longer shadow the
244
+ runtime's declared version during schema evaluation.
245
+
246
+ Schema-only evaluation also emits inert named table proxies for authored
247
+ Drizzle exports. Shared input/DTO modules may therefore construct top-level
248
+ selection objects such as `{ id: records.id }` without executing a database
249
+ operation or losing the action's Zod schema.
250
+
251
+ Harvest failures now retain the exact action key, failing phase (`bundle` or
252
+ `evaluation`), and bounded underlying error. Contract v2 includes those
253
+ per-action diagnostics in its fail-closed compile error; v1 retains its
254
+ best-effort static-schema fallback.
255
+
256
+ ### Contract v2 delegated principals and RLS-only action tables
257
+
258
+ Cloudflare + Neon Hyperdrive projects on `contract.version: "v2"` can now
259
+ declare framework-generic delegated authenticators under `auth.principals`.
260
+ Each named principal owns an exact, non-`Bearer` Authorization scheme, a
261
+ project hook that proves the credential and returns only `{ digest }`, and one
262
+ compiler-owned indexed lookup that resolves the actor, optional session/family,
263
+ string claims, and active status. The hook receives no database handle. Proof
264
+ hooks authored under `quickback/lib` are staged into generated `src/lib`, even
265
+ when no action imports them directly.
266
+
267
+ Delegated authority is structurally disjoint from Better Auth accounts:
268
+ `ctx.principal` is populated while user, organization, team, and membership
269
+ fields remain absent. Access arms may use `principals: [...]`; fields inside an
270
+ arm are ANDed and sibling arms are ORed. Generated action helpers preserve
271
+ that boundary in TypeScript, including the anonymous possibility of a
272
+ `PUBLIC` sibling arm. Mixed credential transport rejects Authorization plus an
273
+ API key or an actual Better Auth session cookie, while unrelated analytics
274
+ cookies do not create a false conflict. `Bearer` remains reserved for account
275
+ authentication.
276
+
277
+ Resources can also declare operation-specific `databaseAccess` policies for
278
+ authored actions and support tables. This is an RLS-only surface: it emits no
279
+ generic route or OpenAPI operation and is accepted only on Cloudflare + Neon
280
+ Hyperdrive. Every authorization path must contain a nonempty SQL-lowerable
281
+ record equality; unbounded principal/role leaves, any unbounded OR arm, empty
282
+ records, ambiguous mixed boolean nodes, app-only predicates, and unsupported
283
+ providers fail compilation. This keeps business logic in authored API actions
284
+ while Postgres independently enforces the same event/person or account/org row
285
+ boundary.
286
+
287
+ Principal claims use the same transaction-local Hyperdrive preamble as account
288
+ claims, with query caching disabled. Restrictive per-operation principal
289
+ fences prevent a public, exception, or legacy permissive policy from admitting
290
+ the wrong principal type. Credential lookup indexes and RLS journal entries are
291
+ content-addressed and converge when a table, digest column, or definition
292
+ changes; generated Postgres identifiers include collision-resistant hashes and
293
+ stay within the 63-byte limit. Each security migration also drops the complete
294
+ compiler-owned `databaseAccess` policy family before recreating the current
295
+ operations, so removing or moving an operation revokes the old permissive
296
+ policy instead of leaving it active. Record fields resolve through authoritative
297
+ Drizzle metadata to exact quoted physical identifiers, unknown fields fail the
298
+ compile, and DB-only pseudo-roles follow the same ADMIN/SYSADMIN/INTERNAL
299
+ contract as the application surface.
300
+
301
+ ### Action execute helpers preserve their typed boundary
302
+
303
+ Generated per-feature `defineAction` helpers no longer erase `services`, the
304
+ Hono request context, record predicates, or the action's return value to
305
+ `any`. Zod input and record inference remain intact, `whereRecord` and
306
+ `whereTransition` accept only the helper's bound table, and the existing D1 /
307
+ Neon Hyperdrive scoped `db` and interactive `tx` types now flow through the
308
+ same execute boundary. The returned value is inferred exactly; this does not
309
+ add a response schema, invalid-return rule, or new output contract.
310
+
311
+ HTTP/WebSocket Neon retains its intentionally dynamic `db`, and `AppContext`
312
+ retains its open index signature for runtime-hydrated namespace fields.
313
+
314
+ ### Neon Hyperdrive is now the only Worker database lane, including Better Auth
315
+
316
+ For `connectionMode: "hyperdrive"`, generated Better Auth code now uses the
317
+ same HYPERDRIVE-backed, service-role-scoped database handle as the rest of the
318
+ generated API. `DATABASE_URL` is no longer emitted or required as a Worker
319
+ secret in Hyperdrive mode; migration credentials remain inputs to the compiler
320
+ or CI environment. HTTP-mode Neon retains its existing `DATABASE_URL` runtime
321
+ contract.
322
+
323
+ ### Public contract v2 now compiles as one coherent API/auth surface
324
+
325
+ Projects may set `contract: { version: "v2" }` to select `/api/v2/*` feature
326
+ routes and `/auth/v2/*` Better Auth routes. The compiler now threads that
327
+ selection through generated route mounts, Better Auth configuration and
328
+ middleware, OpenAPI paths and server metadata, MCP internal tool calls, OAuth
329
+ discovery, `llms.txt`, schema/embeddings/system routes, live views, namespace
330
+ actions, and dedicated-domain `/v2/*` shortcuts. The option is no longer
331
+ fail-closed. Omitting `contract` or selecting `v1` preserves the existing v1
332
+ output.
333
+
334
+ Bundled CMS and Account clients now receive the selected API and auth base
335
+ paths through both their Vite build environment and the Worker-injected runtime
336
+ config. CMS CRUD, schema, sysadmin, and live-view requests and Account auth,
337
+ data, and live-view requests therefore stay on `/api/v2` and `/auth/v2` for a
338
+ v2 project instead of falling back to client-side v1 literals. V1 SPA config
339
+ retains its historical byte shape.
340
+
341
+ V2 compiles also require a complete client-side action input-schema harvest.
342
+ The current CLI reports the exact action files that failed to produce a JSON
343
+ Schema, and the compiler independently rejects missing, invalid, or partial
344
+ maps at the shared parse boundary used by both complete and validation-only
345
+ compiles. `POST /compile?complete=false` can no longer bypass the v2 gate. For
346
+ record actions with `bulkVariant: true`, the harvested schema now patches both
347
+ the single-record request body and the bulk operation's nested `input`; the
348
+ action is counted complete only when both OpenAPI targets exist. Harvest
349
+ planning also normalizes filename-based action bindings to the table's declared
350
+ name and resource path, so kebab-case filenames exporting snake/camel-case
351
+ tables are not silently omitted. V1 remains best-effort for backward
352
+ compatibility.
353
+
354
+ ### Complete, isolated Wrangler targets for named Neon environments
355
+
356
+ `providers.database.environments` now defines deployable Neon Hyperdrive
357
+ targets instead of emitting empty `[env.*]` shells. Because Wrangler does not
358
+ inherit vars or bindings into named environments, each target must explicitly
359
+ own its generated vars, required-secret contract, Hyperdrive and KV IDs,
360
+ rate-limit namespace IDs, and Cloudflare Email binding. The compiler rejects
361
+ missing overrides, shared stateful IDs, optional secret declarations, invalid
362
+ target semantics, and unsupported binding families rather than generating a
363
+ Worker that starts without part of its runtime.
364
+
365
+ The required-secret inventory is now centralized and includes generated
366
+ credentials as well as custom declarations: `BETTER_AUTH_SECRET`, a configured
367
+ `auth.jwt.secretEnv`, `ENCRYPTION_KEK` when envelope encryption is present, and
368
+ every `bindings.secrets` entry marked `required`. Generated Better Auth SES/SNS
369
+ credentials, AWS-backed anonymous-upgrade credentials, enabled social-provider
370
+ client id/secret pairs, and R2 presign credential env names are included as
371
+ well. Cloudflare social auth now reads those credentials from the Worker `env`
372
+ binding instead of relying on `process.env` compatibility behavior. Named
373
+ targets also reject every generated top-level custom-domain source — including
374
+ runtime routes, the primary/CMS/Account/Admin/Auth/API domains, and app domains
375
+ or aliases — until routes can be declared with explicit per-environment
376
+ ownership; top-level routes can no longer produce an ambiguous deployment
377
+ target.
378
+
379
+ Named targets are currently limited to Neon Hyperdrive with Better Auth.
380
+ External auth remains fail-closed until its service binding can be declared
381
+ independently for every named environment.
382
+
383
+ For named-environment projects, the base Worker has no deployable stateful
384
+ bindings, local development selects a named target, and that selected target
385
+ is always the required logical `dev` environment, which must own an explicit
386
+ development-only Hyperdrive `localConnectionString`. Quickback emits it only
387
+ in the selected named binding, rejects a top-level
388
+ override when named environments exist, and rejects local URLs on staging or
389
+ production targets; deployed targets continue to resolve the remote
390
+ Hyperdrive configuration by ID. The generated package omits the unsafe bare
391
+ deploy script. Existing projects that omit
392
+ `environments` keep byte-identical Wrangler output and the existing dev/deploy
393
+ scripts. See [Neon → Named Cloudflare deployment environments](/compiler/targets/hono-api/database/neon#named-cloudflare-deployment-environments).
394
+
395
+ ### Local compiler trust boundary and deterministic Drizzle commands
396
+
397
+ The supported Docker launcher now opts into unauthenticated local compilation
398
+ explicitly and publishes the compiler only on `127.0.0.1`; missing or unknown
399
+ compiler modes retain hosted authentication. The CLI recognizes only exact
400
+ loopback hostnames as local. Migration post-commands now use the configured
401
+ package manager's local binary execution form, with npm forced offline and its
402
+ implicit install prompt disabled, so a missing `drizzle-kit` fails clearly
403
+ instead of fetching an unpinned package.
404
+
5
405
  ### Action rate limits now emit — documented since the rate-limit pillar, wired now
6
406
 
7
407
  The [rate-limit docs](/compiler/definitions/rate-limit#actions) have described
@@ -40,7 +440,7 @@ The generated `auth:schema` script runs `npx better-auth generate`, but the
40
440
  lives in the npm package `auth` (the official Better Auth CLI; the team took
41
441
  over that name at 1.5.0, superseding the frozen `@better-auth/cli`). Generated
42
442
  projects now declare `auth` as a devDependency pinned to the runtime's minor
43
- line, so `npm run build` resolves the CLI locally instead of requiring a
443
+ line, so `npm run auth:schema` resolves the CLI locally instead of requiring a
44
444
  global install. The compiler image's global CLI is pinned to the same version,
45
445
  eliminating silent skew between the CLI on `latest` and the pinned runtime.
46
446
 
@@ -75,6 +75,22 @@ Reads your definitions and generates:
75
75
 
76
76
  Run this after making changes to your definitions.
77
77
 
78
+ #### Configuration-aware completion steps
79
+
80
+ After a successful compile, the CLI derives its next steps from the configured
81
+ database connection mode. Neon HTTP projects receive the direct
82
+ `DATABASE_URL`, `.dev.vars`, migration, and deploy workflow. Hyperdrive
83
+ projects instead receive migration-only `DATABASE_MIGRATION_URL` guidance and
84
+ local development instructions for the configured Hyperdrive
85
+ `localConnectionString`; the CLI never recommends `DATABASE_URL` as a Worker
86
+ secret for that mode.
87
+
88
+ When `providers.database.environments` defines isolated targets, the footer
89
+ lists the configured Neon branches, each target's required Worker secrets, and
90
+ explicit `wrangler ... --env <target>` deploy commands. It does not suggest a
91
+ bare deploy or the unnamed `.env.neon` / `.dev.vars` workflow for named
92
+ Hyperdrive environments.
93
+
78
94
  #### Generated `src/` is hermetic
79
95
 
80
96
  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:
@@ -36,9 +36,11 @@ The map uses project-root-relative paths and follows the same layout `quickback
36
36
  Two constraints, both fail-closed:
37
37
 
38
38
  - **The config must be fully static.** The compiler parses `quickback.config.ts` with a literals-only evaluator — it never executes user code. Object/array/string/number/boolean literals, substitution-free template literals, and the `define*` helper calls all work; variables, computed values, and imports-as-values are rejected with a 400 that names the offending construct and line.
39
- - **Action input schemas are optional.** The CLI harvests `z.toJSONSchema` on your machine; raw-files requests may pass `actionInputSchemas` alongside `rawFiles`, otherwise the compiler's static parser supplies lower-fidelity input schemas.
39
+ - **Action input schemas are contract-sensitive.** For v1, raw-files requests may omit `actionInputSchemas` and use the compiler's lower-fidelity static parser. V2 requires one usable client-harvested `z.toJSONSchema(action.input)` entry for every authored action. The CLI reports each missing action with its local bundle or evaluation error; the API independently reports missing or invalid action keys.
40
40
 
41
- Works with both `?complete=true` and `?complete=false` (validation-only) compiles.
41
+ Raw-files requests work with both `?complete=true` and `?complete=false`
42
+ (validation-only) compiles. The v2 action-schema completeness gate applies to
43
+ both modes; `complete=false` is not an escape hatch for a partial harvest.
42
44
 
43
45
  ## Edge validation backend
44
46
 
@@ -6,7 +6,6 @@ Run the Quickback compiler locally using Docker. The local compiler uses the exa
6
6
 
7
7
  - Docker Desktop installed and running
8
8
  - Quickback monorepo cloned locally
9
- - Authenticated via `quickback login`
10
9
 
11
10
  ## Quick Start
12
11
 
@@ -20,7 +19,7 @@ This will:
20
19
  1. Ensure Docker Desktop is running
21
20
  2. Stop any existing compiler container
22
21
  3. Build the Docker image from `apps/compiler/Dockerfile`
23
- 4. Run it on port 3000
22
+ 4. Start it in explicit local mode, published only on `127.0.0.1:3000`
24
23
 
25
24
  ### Custom Port
26
25
 
@@ -43,7 +42,12 @@ export QUICKBACK_API_URL=http://localhost:3000
43
42
  quickback compile
44
43
  ```
45
44
 
46
- Authentication is always required. Run `quickback login` first if you haven't already.
45
+ The supported launcher does not require `quickback login`. It opts the compiler
46
+ into local mode and binds Docker's host port to loopback, so the unauthenticated
47
+ compile endpoint is not exposed to the LAN. The CLI skips its login prompt only
48
+ when `QUICKBACK_API_URL` has the exact hostname `localhost`, `127.0.0.1`, or
49
+ `::1`; longer hostnames and URLs that merely contain those strings still use
50
+ hosted authentication.
47
51
 
48
52
  ## Manual Build & Run
49
53
 
@@ -53,10 +57,18 @@ You can also build and run the Docker image directly from the monorepo root:
53
57
  # Build
54
58
  docker build -t quickback-compiler -f apps/compiler/Dockerfile .
55
59
 
56
- # Run
57
- docker run --rm -p 3000:3000 quickback-compiler
60
+ # Run with the same security boundary as the supported launcher
61
+ docker run --rm \
62
+ -e QUICKBACK_COMPILER_MODE=local \
63
+ -p 127.0.0.1:3000:3000 \
64
+ quickback-compiler
58
65
  ```
59
66
 
67
+ `QUICKBACK_COMPILER_MODE` is fail-closed: only the exact value `local` bypasses
68
+ compile authentication. If the variable is absent or misspelled, the compiler
69
+ uses hosted authentication. Never publish a local-mode container on
70
+ `0.0.0.0` or a non-loopback interface.
71
+
60
72
  ## Verify
61
73
 
62
74
  Check the compiler is running:
@@ -24,6 +24,20 @@ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to m
24
24
 
25
25
  Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
26
 
27
+ > **Contract v2 is opt-in**
28
+ >
29
+ > On `contract: { version: "v2" }`, Quickback emits this custom JWT surface only
30
+ > when `auth.jwt` is present. If it is omitted, generated output has no generic
31
+ > `/api/v2/token` endpoint, `src/lib/jwt.ts`, JWT middleware verify/mint fast-path,
32
+ > or Quickback JWT imports. Generated `llms.txt` and RFC 8414 discovery metadata
33
+ > also omit Bearer-JWT instructions, token endpoints, and JWT scopes that do not
34
+ > exist. Better Auth cookie and signed session-token bearer authentication remain
35
+ > available.
36
+ >
37
+ > Use `auth: { jwt: {} }` to opt a v2 project into the defaults documented below.
38
+ > Contract v1 keeps the historical always-emitted JWT surface for compatibility.
39
+
40
+
27
41
  ### Security posture at a glance
28
42
 
29
43
  The short version, before the knob-by-knob detail:
@@ -112,9 +126,10 @@ Semantics worth knowing:
112
126
  - **Eventual consistency:** KV propagates cross-PoP in ~60s. "Immediate" means seconds at the writing location, bounded-seconds globally — still far inside the 15-minute carry-forward cap that bounds revocation without this check.
113
127
  - **Coverage gap:** batch *hard* deletes don't return rows through the chokepoint; call `revokeScopeTokens` explicitly if you bulk-hard-delete conferring rows.
114
128
 
115
- ## Defaults preserve 0.10.13 behavior
129
+ ## Defaults when the JWT surface is enabled
116
130
 
117
- Adding the `auth.jwt` block without setting any field is a no-op vs. the 0.10.13 baseline. Each missing field falls back to its hardcoded value:
131
+ Adding `auth.jwt: {}` enables the surface with the historical defaults. Each
132
+ missing field falls back to its hardcoded value:
118
133
 
119
134
  | Field | Default |
120
135
  |---|---|