@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
@@ -94,8 +94,9 @@ Every optional top-level key the config accepts is listed below. You never have
94
94
  | Field | Type | Description |
95
95
  |-------|------|-------------|
96
96
  | `domain` | `string` | Primary custom domain (auto-inferred from `cms`/`account`/`api` domains if unset) — see [Domains](/compiler/config/domains) |
97
- | `api` | `object` | Dedicated hostname for the feature API surface (`/api/v1/*`); additive alias — see [Domains](/compiler/config/domains) |
98
- | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/compiler/definitions/access#role-hierarchy) |
97
+ | `contract` | `{ version?: "v1" \| "v2" }` | Public API/auth contract version. Omit for the backward-compatible v1 default; select v2 for `/api/v2/*` and `/auth/v2/*` across generated routes, Better Auth, OpenAPI, MCP, and discovery. |
98
+ | `api` | `object` | Dedicated hostname for the selected feature API contract (`/api/v1/*` or `/api/v2/*`); additive alias — see [Domains](/compiler/config/domains) |
99
+ | `auth` | `object` | App-level auth settings (`roleHierarchy`, `jwt`, delegated `principals`, `loginUrl`/`profileUrl`, `domain`) — see [Access](/compiler/definitions/access#role-hierarchy) and [Delegated principals](#delegated-principals-contract-v2) |
99
100
  | `authz` | `object` | Relationship-based authorization (`relationships`, `roles`, `permissions`, `arrows`) — see [Permissions](/compiler/definitions/permissions) |
100
101
  | `trustedOrigins` | `string[]` | CORS trusted origins for cross-domain auth |
101
102
  | `features` | `object` | Feature flags such as `organizations` / `pinnedOrganizationId` — see [Pinned Organization Mode](/compiler/config/single-tenant) |
@@ -109,11 +110,177 @@ Every optional top-level key the config accepts is listed below. You never have
109
110
  | `etag` | `object` | ETag caching for GET responses (`{ enabled: false }` to disable) — see [Caching & ETags](/compiler/targets/hono-api/using-the-api/caching) |
110
111
  | `email` | `object` | Email delivery config (`provider`, `from`, `fromName`, `region`) — see [Email Configuration](#email-configuration) |
111
112
  | `bindings` | `object` | Extra Cloudflare bindings (durable objects, queues, R2, services, `vars`, AI) — see [Bindings](/compiler/config/bindings) |
112
- | `compiler` | `object` | Compiler internals — `features.auditFields: false`, `migrations.renames` (headless CI), `securityContracts`, `injectId`, `routes` |
113
+ | `compiler` | `object` | Compiler internals — `features.auditFields: false`, `migrations.renames` (headless CI), Neon `migrations.foreignKeys`, `securityContracts`, `injectId`, `routes` |
113
114
  | `build` | `object` | Build options (`outputDir`, `packageManager`, `dependencies`) — see [Custom Dependencies](#custom-dependencies) |
114
115
  | `dev` | `object` | Local development settings (`port`, `api`, `cms`, `account`, `hostnames`) — see [Variables](/compiler/config/variables) |
115
116
  | `preset` | `string` | Inherit defaults from a named preset |
116
117
 
118
+ ## Public contract version
119
+
120
+ Quickback defaults to the existing v1 HTTP contract. New applications can opt
121
+ into v2 explicitly:
122
+
123
+ ```typescript
124
+ export default defineConfig({
125
+ name: "my-app",
126
+ template: "hono",
127
+ contract: { version: "v2" },
128
+ providers: cloudflare({}),
129
+ });
130
+ ```
131
+
132
+ The selection is atomic: feature routes move to `/api/v2/*`, Better Auth moves
133
+ to `/auth/v2/*`, and generated OpenAPI, MCP tool calls, OAuth discovery,
134
+ `llms.txt`, schema/embeddings routes, and dedicated-domain `/v2/*` shortcuts
135
+ use the same version. When CMS or Account is enabled, Quickback also bakes
136
+ those paths into the SPA build and injects them at runtime, so CRUD, schema,
137
+ live-view, and authentication requests use the selected contract. Quickback
138
+ does not expose a mixed v1/v2 surface from one compiled Worker. Omitting
139
+ `contract` remains byte-compatible with v1 projects.
140
+
141
+ V2 also makes action input-schema fidelity a compile gate. The CLI must
142
+ successfully harvest `z.toJSONSchema(action.input)` for every authored action;
143
+ partial or missing harvests fail with the exact action file keys, bundle or
144
+ evaluation phase, and underlying local error. Dependencies are resolved from
145
+ the generated runtime's `build.outputDir/node_modules` before unrelated
146
+ ancestor installs, so an isolated `quickback/` definition tree can use a
147
+ sibling `src/` runtime without a workspace-root symlink. The compiler enforces
148
+ the same invariant at its shared input boundary, including
149
+ `POST /compile?complete=false`, so validation-only or raw API calls cannot
150
+ bypass it. V1 retains the historical best-effort static-schema fallback.
151
+
152
+ ## Delegated principals (contract v2)
153
+
154
+ `auth.principals` defines non-account authority such as an event pass or a
155
+ short-lived event session. It is available only with all three of:
156
+
157
+ - `contract: { version: "v2" }`
158
+ - the Cloudflare runtime
159
+ - Neon with `connectionMode: "hyperdrive"`
160
+
161
+ Each principal type owns an exact Authorization scheme. `Bearer` is reserved
162
+ for Quickback account authentication, including case variants, and two
163
+ principal types cannot share a scheme.
164
+
165
+ ```typescript
166
+ export default defineConfig({
167
+ name: "attend-v2",
168
+ template: "hono",
169
+ contract: { version: "v2" },
170
+ auth: {
171
+ principals: {
172
+ event_pass: {
173
+ scheme: "EventPass",
174
+ authenticate: {
175
+ module: "./event-pass-proof",
176
+ export: "authenticateEventPass",
177
+ },
178
+ lookup: {
179
+ table: {
180
+ module: "../features/event-access/event-access",
181
+ export: "eventAccess",
182
+ sqlName: "event_access",
183
+ },
184
+ digest: { field: "digest", column: "digest" },
185
+ actorId: { field: "personId", column: "person_id" },
186
+ claims: {
187
+ eventId: { field: "eventId", column: "event_id" },
188
+ personId: { field: "personId", column: "person_id" },
189
+ },
190
+ status: { field: "status", column: "status", allow: ["active"] },
191
+ },
192
+ },
193
+ event_delegate: {
194
+ scheme: "EventSession",
195
+ authenticate: {
196
+ module: "./event-session-proof",
197
+ export: "authenticateEventSession",
198
+ },
199
+ lookup: {
200
+ table: {
201
+ module: "../features/event-sessions/event-sessions",
202
+ export: "eventSessions",
203
+ sqlName: "event_sessions",
204
+ },
205
+ digest: { field: "digest", column: "digest" },
206
+ actorId: { field: "personId", column: "person_id" },
207
+ sessionId: { field: "id", column: "id" },
208
+ familyId: { field: "familyId", column: "family_id" },
209
+ claims: {
210
+ eventId: { field: "eventId", column: "event_id" },
211
+ personId: { field: "personId", column: "person_id" },
212
+ },
213
+ status: { field: "status", column: "status", allow: ["active"] },
214
+ },
215
+ },
216
+ },
217
+ },
218
+ providers: {
219
+ runtime: defineRuntime("cloudflare"),
220
+ database: defineDatabase("neon", {
221
+ connectionMode: "hyperdrive",
222
+ hyperdrive: { id: "<32-character-hyperdrive-id>" },
223
+ }),
224
+ auth: defineAuth("better-auth"),
225
+ },
226
+ });
227
+ ```
228
+
229
+ The `authenticate.module` path is relative to generated
230
+ `src/lib/principal-auth.ts`. Put project proof hooks under `quickback/lib`; the
231
+ compiler stages them into `src/lib` even if no action imports them. A hook has
232
+ one job: prove the presented credential and return its stable digest.
233
+
234
+ ```typescript
235
+ // quickback/lib/event-session-proof.ts
236
+ export async function authenticateEventSession({ credential, env, request }: {
237
+ credential: string;
238
+ env: Env;
239
+ request: Request;
240
+ }): Promise<{ digest: string } | null> {
241
+ const valid = await verifySignedEventSession(credential, env, request);
242
+ return valid ? { digest: await sha256(credential) } : null;
243
+ }
244
+ ```
245
+
246
+ The hook receives no `db`, and it must not implement row authorization or
247
+ business behavior. Quickback performs exactly one narrow, unique digest lookup
248
+ under a lookup-only RLS principal. A digest must be 16–512 non-whitespace
249
+ characters; resolved identity strings must be 1–512 characters and serialized
250
+ claims are limited to 4096 characters. A lookup must resolve exactly one active
251
+ row or authentication fails.
252
+
253
+ On success, actions receive `ctx.principal`:
254
+
255
+ ```typescript
256
+ {
257
+ type: "event_delegate",
258
+ actor: { type: "event_delegate", id: "person_123" },
259
+ session: { id: "session_123", familyId: "family_123" },
260
+ claims: { eventId: "event_123", personId: "person_123" },
261
+ }
262
+ ```
263
+
264
+ Quickback never synthesizes `userId`, `activeOrgId`, `activeTeamId`, or
265
+ membership roles from a delegated credential. Use `principals` in an access
266
+ arm to admit it. Values inside one arm are ANDed; sibling `or` arms are ORed:
267
+
268
+ ```typescript
269
+ access: {
270
+ or: [
271
+ { roles: ["AUTHENTICATED"] },
272
+ { principals: ["event_delegate"], record: {
273
+ eventId: { equals: "$ctx.principal.claims.eventId" },
274
+ } },
275
+ ],
276
+ }
277
+ ```
278
+
279
+ An Authorization header cannot be combined with `x-api-key` or a Better Auth
280
+ session cookie. Quickback recognizes only Better Auth's exact session cookie
281
+ names for this conflict check, so analytics and preference cookies remain
282
+ harmless.
283
+
117
284
  ## Custom Dependencies
118
285
 
119
286
  Add third-party npm packages to the generated `package.json` using `build.dependencies`. This is useful when your action handlers import external libraries.
@@ -171,6 +338,87 @@ Rules:
171
338
  - Keys must match the names in your current schema (the new names)
172
339
  - Validation fails fast for malformed rename config, unsupported keys, or conflicting legacy/new rename paths.
173
340
 
341
+ ## Neon Foreign Key Migrations
342
+
343
+ Use `compiler.migrations.foreignKeys` when a Neon relationship cannot be
344
+ expressed in one generated Drizzle schema file—for example, a feature table
345
+ that references a Better Auth table, or a composite integrity relationship
346
+ between independently authored feature modules.
347
+
348
+ ```typescript
349
+ export default defineConfig({
350
+ // ...
351
+ providers: {
352
+ runtime: defineRuntime("cloudflare"),
353
+ database: defineDatabase("neon", { connectionMode: "hyperdrive" }),
354
+ auth: defineAuth("better-auth"),
355
+ },
356
+ compiler: {
357
+ migrations: {
358
+ foreignKeys: [
359
+ {
360
+ name: "person_account_links_user_fk",
361
+ source: {
362
+ schema: "app",
363
+ table: "person_account_links",
364
+ columns: ["user_id"],
365
+ },
366
+ target: {
367
+ schema: "auth",
368
+ table: "users",
369
+ columns: ["id"],
370
+ },
371
+ onDelete: "restrict",
372
+ onUpdate: "restrict",
373
+ },
374
+ {
375
+ name: "event_access_grants_consumed_family_fk",
376
+ source: {
377
+ schema: "app",
378
+ table: "event_access_grants",
379
+ columns: [
380
+ "consumed_by_family_id",
381
+ "id",
382
+ "organization_id",
383
+ "event_id",
384
+ "event_person_id",
385
+ ],
386
+ },
387
+ target: {
388
+ schema: "app",
389
+ table: "event_session_families",
390
+ columns: [
391
+ "id",
392
+ "source_grant_id",
393
+ "organization_id",
394
+ "event_id",
395
+ "event_person_id",
396
+ ],
397
+ },
398
+ onDelete: "restrict",
399
+ onUpdate: "restrict",
400
+ },
401
+ ],
402
+ },
403
+ },
404
+ });
405
+ ```
406
+
407
+ All identifiers must be lowercase Postgres identifiers of at most 63
408
+ characters. Source and target tuples must be nonempty and have equal arity;
409
+ column order is significant. Supported actions are `"no action"`,
410
+ `"restrict"`, `"cascade"`, `"set null"`, and `"set default"`.
411
+
412
+ Constraint names and source tuples must be unique in the config. On replay,
413
+ Quickback verifies that an existing same-named constraint has the exact target,
414
+ ordered columns, and referential actions. It fails instead of silently
415
+ accepting an ambiguous definition. Existing rows are validated during
416
+ migration, so clean up orphans before deploying.
417
+
418
+ This API is for database integrity, not business behavior. Keep authorization,
419
+ state transitions, event-pass consumption, and other business rules in the API
420
+ action layer.
421
+
174
422
  ## Disable Audit Field Injection
175
423
 
176
424
  By default, Quickback auto-injects four **audit fields** (`createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`) into every feature table, plus two **soft-delete fields** (`deletedAt`, `deletedBy`) into tables that use soft delete (the default delete mode). The audit fields drive record-provenance queries and the CMS audit panel; the soft-delete pair drives soft-delete filtering.
@@ -233,8 +481,8 @@ A modern Quickback project runs on **one Cloudflare Worker** that serves multipl
233
481
 
234
482
  When any subdomain is configured (`account.domain`, `cms.domain`, `auth.domain`, `api.domain`, `apps.<n>.domain`), the compiler always emits a unified backend host where **every compiler-emitted backend route** is reachable:
235
483
 
236
- - `/api/v1/*` — feature routes
237
- - `/auth/v1/*` — Better Auth
484
+ - `/api/v1/*` and `/auth/v1/*` for the default contract, or `/api/v2/*` and
485
+ `/auth/v2/*` when `contract.version` is `"v2"`
238
486
  - `/storage/*` — R2 file storage
239
487
  - `/health`, `/openapi.json` — monitoring/discovery
240
488
  - `/account/*`, `/cms/*` — bundled SPAs (when enabled)
@@ -269,19 +517,19 @@ On a dedicated hostname, **the hostname IS the namespace** — the path drops th
269
517
 
270
518
  | URL on dedicated host | Internally rewritten to | Notes |
271
519
  |---|---|---|
272
- | `https://api.example.com/v1/users` | `/api/v1/users` | Worker-entry rewriter prepends `/api` |
273
- | `https://auth.example.com/v1/sign-in/email` | `/auth/v1/sign-in/email` | Same shape with `/auth` |
274
- | `https://api.example.com/api/v1/users` | (unchanged) | Long form also accepted |
275
- | `https://api.example.com/auth/v1/sign-in` | **404** | Auth doesn't live on the API hostname |
520
+ | `https://api.example.com/{version}/users` | `/api/{version}/users` | `{version}` is the selected `v1` or `v2`; the rewriter prepends `/api` |
521
+ | `https://auth.example.com/{version}/sign-in/email` | `/auth/{version}/sign-in/email` | Same selected version with `/auth` |
522
+ | `https://api.example.com/api/{version}/users` | (unchanged) | Long form also accepted |
523
+ | `https://api.example.com/auth/{version}/sign-in` | **404** | Auth doesn't live on the API hostname |
276
524
  | `https://api.example.com/health` | (unchanged) | Explicit exception — monitoring agents expect `/health` everywhere |
277
525
 
278
526
  Dual-reach is preserved on the unified host:
279
527
 
280
528
  | URL on unified host | Handler | Notes |
281
529
  |---|---|---|
282
- | `https://quickback.example.com/api/v1/users` | feature route | Works whether `api.domain` is set or not |
283
- | `https://quickback.example.com/auth/v1/sign-in/email` | Better Auth | Works whether `auth.domain` is set or not |
284
- | `https://quickback.example.com/v1/users` | **404** | Shortcut only applies on dedicated hostnames |
530
+ | `https://quickback.example.com/api/{version}/users` | feature route | Works for the selected version whether `api.domain` is set or not |
531
+ | `https://quickback.example.com/auth/{version}/sign-in/email` | Better Auth | Works for the selected version whether `auth.domain` is set or not |
532
+ | `https://quickback.example.com/{version}/users` | **404** | Shortcut only applies on dedicated hostnames |
285
533
 
286
534
  Each dedicated hostname also:
287
535
 
@@ -464,6 +712,17 @@ For the Cloudflare provider (the default), the compiler automatically:
464
712
  - Emits `[[send_email]] EMAIL` into `wrangler.toml`
465
713
  - Generates `src/lib/cloudflare-email.ts`
466
714
  - Wires `sendResetPassword`, `sendVerificationEmail`, `sendInvitationEmail`, etc. into Better Auth
715
+ - Types the binding with Cloudflare's native `SendEmail` / `EmailSendResult`
716
+ contract (`{ email, name }`, `replyTo`, and `contentId` on Workers). The REST
717
+ helper remains a separate `{ address, name }` / `reply_to` / `content_id`
718
+ contract.
719
+ - Anchors each authentication delivery to `executionCtx.waitUntil(...)`. The
720
+ background promise records a structured generic failure and stays rejected;
721
+ outside a Worker request, the callback returns the observed promise for the
722
+ caller to await. Every Cloudflare Email callback is wired through that shared
723
+ scheduler exactly once, so no auth action can bypass failure observation or
724
+ double-schedule the send. Provider error bodies are never written to
725
+ generated logs.
467
726
 
468
727
  …whenever any auth surface needs to send mail — `emailAndPassword.enabled`, the `emailOtp` / `magicLink` / `organization` plugins — or you set the top-level `email: {…}` config. You don't need to add `bindings.sendEmail` by hand for the standard cases.
469
728
 
@@ -108,6 +108,43 @@ data/ # SQLite database files
108
108
  | Migrations | `quickback/drizzle/auth/` + `quickback/drizzle/features/` | `quickback/drizzle/` |
109
109
  | Drizzle configs | 2 configs (auth + features) | 1 config |
110
110
 
111
+ ## Generated Package Dependency Security
112
+
113
+ For projects using Better Auth, the generated `package.json` keeps the stable
114
+ `auth@1.6.x` development dependency that provides the `better-auth` executable
115
+ used by `auth:schema`. It also emits this npm override:
116
+
117
+ ```json
118
+ {
119
+ "overrides": {
120
+ "lodash": "4.18.1"
121
+ }
122
+ }
123
+ ```
124
+
125
+ The override lifts the CLI's dev-only Prisma schema-parser chain off Lodash
126
+ versions affected by the 2026 code-injection and prototype-pollution
127
+ advisories. It does not change the Better Auth runtime package or generated
128
+ authentication behavior. Quickback preserves unrelated overrides already in
129
+ your package manifest, but the compiler-owned Lodash security pin wins if an
130
+ existing override conflicts.
131
+
132
+ After recompiling, run your package manager's install command so its lockfile
133
+ records the patched transitive version. Use `npm audit --omit=dev` when
134
+ evaluating the production dependency tree; development-tool advisories are a
135
+ separate review surface.
136
+
137
+ For Better Auth projects, `quickback compile` owns auth-schema generation.
138
+ The generated `build` script runs TypeScript only and never rewrites
139
+ `src/auth/schema.ts`, so build and deployment preflight checks preserve a clean
140
+ generated worktree. `auth:schema` remains an explicit diagnostic command; run
141
+ `quickback compile` afterward to restore canonical generated bytes.
142
+
143
+ On recompilation, Quickback replaces commands for script names it generates,
144
+ including `build`, with the current compiler output. Scripts with other names
145
+ are treated as project customizations and preserved. This lets existing
146
+ projects acquire build and deployment fixes without losing unrelated tooling.
147
+
111
148
  ## Optional Output Files
112
149
 
113
150
  These files are generated only when the corresponding features are configured:
@@ -121,7 +158,7 @@ src/
121
158
  ├── lib/
122
159
  │ └── embeddings.ts # Embedding helpers
123
160
  ├── routes/
124
- │ └── embeddings.ts # POST /api/v1/embeddings endpoint
161
+ │ └── embeddings.ts # POST /api/{v1|v2}/embeddings endpoint
125
162
  └── queue-consumer.ts # Queue handler for async embedding jobs
126
163
  ```
127
164
 
@@ -264,11 +301,20 @@ For each feature, the compiler generates a routes file at `src/features/{name}/r
264
301
  | `POST /:id/{action}` | Record-based actions defined |
265
302
  | `POST /{action}` | Standalone actions defined |
266
303
 
267
- All routes are mounted under `/api/v1/{feature}` in the main app.
304
+ Routes are mounted under `/api/v1/{feature}` for the default contract or
305
+ `/api/v2/{feature}` when `contract: { version: "v2" }` is selected.
268
306
 
269
307
  ## Migrations
270
308
 
271
- The compiler runs `drizzle-kit generate` during compilation to produce SQL migration files. On subsequent compiles, it uses `existingFiles` (your current migration state) to generate only incremental changes.
309
+ 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.
310
+
311
+ If a compiler response returns migration generation as a post-compile command,
312
+ the command matches `build.packageManager`: `npm exec`, `pnpm exec`, `yarn exec`,
313
+ or `bun run`. These forms resolve the binary from the generated project's
314
+ dependencies. The npm form runs offline and declines npm's missing package
315
+ install prompt, so Quickback never downloads an unpinned Drizzle CLI as a
316
+ fallback. If the local binary is missing, install the generated project's
317
+ dependencies and compile again.
272
318
 
273
319
  The CLI loads migration meta JSON from one location only — `<project>/quickback/drizzle/`:
274
320
 
@@ -114,7 +114,9 @@ single Postgres database with no bindings or split mode (see
114
114
 
115
115
  | Option | Type | Default | Description |
116
116
  |--------|------|---------|-------------|
117
- | `connectionMode` | `"auto" \| "http" \| "websocket"` | `"auto"` | How the generated runtime connects (`auto` detects the runtime) |
117
+ | `connectionMode` | `"auto" \| "http" \| "websocket" \| "hyperdrive"` | `"auto"` | How the generated runtime connects (`hyperdrive` enables interactive Postgres transactions on Workers) |
118
+ | `hyperdrive.id` | `string` | — | Required Cloudflare Hyperdrive configuration ID when `connectionMode: "hyperdrive"` |
119
+ | `hyperdrive.localConnectionString` | `string` | — | Optional local-only Postgres connection used by Wrangler dev |
118
120
  | `pooled` | `boolean` | `true` | Use the pooled Neon connection string (recommended for Workers) |
119
121
 
120
122
  The Worker connects through a single `DATABASE_URL` secret — auth and feature
@@ -284,6 +286,7 @@ providers: {
284
286
  | `rateLimit.enabled` | `boolean` | Enable rate limiting |
285
287
  | `rateLimit.window` | `number` | Rate limit window in seconds |
286
288
  | `rateLimit.max` | `number` | Max requests per window |
289
+ | `atomicAuthRoutes` | `("emailOtpSignIn")[]` | Runs the exact email-OTP sign-in handler and `before-email-otp-activate.ts` admission hook in one Neon Hyperdrive transaction. Contract v2 only. |
287
290
  | `socialProviders` | `object` | Social login providers (`google`, `github`, `discord`) |
288
291
  | `debugLogs` | `boolean` | Enable auth debug logging |
289
292
 
@@ -310,6 +313,14 @@ When `features: ["organizations"]` is set in your config, the compiler automatic
310
313
  | `jwt` | JWT token support |
311
314
  | `openAPI` | OpenAPI spec generation |
312
315
 
316
+ `emailOtp` also accepts an options object. Set `expiresIn` to a positive integer
317
+ number of seconds to override Better Auth's OTP lifetime. The setting is
318
+ transport-neutral and is emitted identically for Cloudflare Email and AWS SES:
319
+
320
+ ```typescript
321
+ plugins: { emailOtp: { expiresIn: 1200 } }
322
+ ```
323
+
313
324
  ## Storage Providers
314
325
 
315
326
  ```typescript
@@ -73,6 +73,11 @@ Set these in `wrangler.toml` under `[vars]` or in the Cloudflare dashboard:
73
73
 
74
74
  Uses the Cloudflare `send_email` binding. No API keys needed — the binding is configured automatically in `wrangler.toml`.
75
75
 
76
+ Generated TypeScript uses the native Workers `SendEmail` binding and its
77
+ `EmailSendResult`; do not replace it with a hand-written `send(any)` interface.
78
+ Worker address objects use `{ email, name }`. The HTTP REST API is a different
79
+ contract and uses `{ address, name }`.
80
+
76
81
  | Variable | Description | Where |
77
82
  |----------|-------------|-------|
78
83
  | `EMAIL_FROM` | Sender email address | `[vars]` |
@@ -178,6 +178,13 @@ GET /api/v1/listings?organizationId=org_abc123
178
178
 
179
179
  The firewall WHERE clause is always enforced. If no `organizationId` is provided, the API returns a `403` with code `ORG_REQUIRED`.
180
180
 
181
+ `?organizationId=` is an account/public addressing surface. A request using a
182
+ configured delegated principal cannot use it to acquire account organization
183
+ authority: the generated route returns `403 CROSS_TENANT_FORBIDDEN` and never
184
+ adds `activeOrgId` or account roles to the delegated `AppContext`. Delegated
185
+ scope continues to come only from the verified principal claims and database
186
+ RLS policy.
187
+
181
188
  ```typescript
182
189
  // Public listing page — anyone can browse, but scoped to an org
183
190
  export default defineTable(listings, {