@quickback-dev/cli 0.18.0 → 0.31.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 (72) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +17 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +23 -58
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/api-client.d.ts +17 -0
  9. package/dist/lib/api-client.d.ts.map +1 -1
  10. package/dist/lib/api-client.js.map +1 -1
  11. package/dist/lib/file-loader.d.ts +24 -0
  12. package/dist/lib/file-loader.d.ts.map +1 -1
  13. package/dist/lib/file-loader.js +46 -0
  14. package/dist/lib/file-loader.js.map +1 -1
  15. package/dist/skill/docs/changelog.md +423 -1
  16. package/dist/skill/docs/compiler/config/domains.md +44 -10
  17. package/dist/skill/docs/compiler/config/output.md +1 -1
  18. package/dist/skill/docs/compiler/config/providers.md +6 -12
  19. package/dist/skill/docs/compiler/config/variables.md +0 -30
  20. package/dist/skill/docs/compiler/definitions/access.md +203 -1
  21. package/dist/skill/docs/compiler/definitions/actions.md +40 -7
  22. package/dist/skill/docs/compiler/definitions/schema.md +6 -10
  23. package/dist/skill/docs/compiler/index.md +15 -34
  24. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  25. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  26. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  27. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  28. package/dist/skill/docs/compiler/targets/index.md +6 -34
  29. package/dist/skill/docs/index.md +2 -5
  30. package/dist/skill/docs/stack/account-ui/customization.md +2 -14
  31. package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
  32. package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
  33. package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
  34. package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
  35. package/dist/skill/docs/stack/account-ui/index.md +5 -43
  36. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
  37. package/dist/skill/docs/stack/auth/plugins/index.md +74 -0
  38. package/package.json +1 -1
  39. package/src/skill/docs/changelog.md +362 -0
  40. package/src/skill/docs/compiler/config/providers.md +6 -12
  41. package/src/skill/docs/compiler/config/variables.md +0 -30
  42. package/src/skill/docs/compiler/definitions/access.md +203 -1
  43. package/src/skill/docs/compiler/definitions/actions.md +40 -7
  44. package/src/skill/docs/compiler/definitions/schema.md +6 -10
  45. package/src/skill/docs/compiler/index.md +15 -34
  46. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  47. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  48. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  49. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  50. package/src/skill/docs/compiler/targets/index.md +6 -34
  51. package/src/skill/docs/index.md +2 -5
  52. package/src/skill/docs/stack/account-ui/customization.md +2 -14
  53. package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
  54. package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
  55. package/src/skill/docs/stack/account-ui/features/index.md +1 -1
  56. package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
  57. package/src/skill/docs/stack/account-ui/index.md +5 -43
  58. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
  59. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  60. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  61. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  62. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  63. package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
  64. package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
  65. package/dist/skill/docs/stack/account-ui/worker.md +0 -362
  66. package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  67. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  68. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  69. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  70. package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
  71. package/src/skill/docs/stack/account-ui/standalone.md +0 -149
  72. package/src/skill/docs/stack/account-ui/worker.md +0 -362
@@ -107,36 +107,6 @@ For running remote migrations with `drizzle-kit`, set these in `.env`:
107
107
  | `CLOUDFLARE_AUDIT_DATABASE_ID` | Security audit D1 database ID (unsafe cross-tenant actions) |
108
108
  | `CLOUDFLARE_DATABASE_ID` | Database ID (single DB mode) |
109
109
 
110
- ## Bun Variables
111
-
112
- Set these in a `.env` file in your project root:
113
-
114
- | Variable | Description | Default |
115
- |----------|-------------|---------|
116
- | `NODE_ENV` | Runtime environment | `development` |
117
- | `PORT` | Server port | `3000` |
118
- | `BETTER_AUTH_SECRET` | Auth encryption secret | — (required) |
119
- | `BETTER_AUTH_URL` | Public URL of your server | `http://localhost:3000` |
120
- | `DATABASE_PATH` | Path to SQLite file | `./data/app.db` |
121
-
122
- ## Turso (LibSQL) Variables
123
-
124
- In addition to the Bun variables above:
125
-
126
- | Variable | Description | Default |
127
- |----------|-------------|---------|
128
- | `DATABASE_URL` | LibSQL connection URL | `file:./data/app.db` |
129
- | `DATABASE_AUTH_TOKEN` | Turso auth token (required for remote) | — |
130
-
131
- ```bash
132
- # Local development
133
- DATABASE_URL=file:./data/app.db
134
-
135
- # Production (Turso cloud)
136
- DATABASE_URL=libsql://your-db-slug.turso.io
137
- DATABASE_AUTH_TOKEN=eyJhbGciOi...
138
- ```
139
-
140
110
  ## Social Login Providers
141
111
 
142
112
  When social login is configured in your auth provider:
@@ -321,10 +321,118 @@ Resource definitions reference declared roles by name in `roles: [...]` arrays e
321
321
  | `crud.*.access` `roles: ['guest']` | ✓ Supported | Inline async lookup per request |
322
322
  | `read.access` / `read.views.*.access` `roles: ['guest']` | ✓ Supported | Same inline path |
323
323
  | `masking.<field>.show` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — async/batched mask functions deferred |
324
- | `actions.<name>.access` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — explicit `relationshipBindings` deferred |
324
+ | **Standalone** `actions.<name>.access` `roles: ['guest']` | ✓ Supported (v0.19+) | Inline gate; surface must expose `resource.column` as path param or input field |
325
+ | **Record-based** `actions.<name>.access` `roles: ['guest']` | ⚠ Fail-closed at runtime | Runtime helper denies; inline emission is a planned follow-up. Use `firewall: { exception: true }` or move the check into `execute()` until then |
325
326
 
326
327
  For the surfaces that are not yet supported, the compiler refuses at build time with a clear error pointing to a workaround. The runtime evaluator fails closed on relationship arms regardless, so silent grants are impossible.
327
328
 
329
+ ### Standalone actions: surface keys and `loads` / `exposeAs` (v0.19+)
330
+
331
+ When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the compiler:
332
+
333
+ - **v0.19** — emits a `[quickback:authz]` warning and skips resolver emission. The action's own hand-rolled gate (if any) keeps the route working at runtime.
334
+ - **v0.20** — hard compile error. Set `firewall: { exception: true }` to opt out (cross-tenant/admin routes only).
335
+
336
+ Pair the relationship with `loads` + `exposeAs` to hydrate the loaded resource onto `ctx`:
337
+
338
+ ```typescript
339
+ authz: {
340
+ relationships: {
341
+ attendeeOf: {
342
+ from: 'guests',
343
+ subject: { column: 'userId', equals: 'ctx.userId' },
344
+ resource: { column: 'eventId' },
345
+ where: { status: 'confirmed' },
346
+ loads: 'events', // ← v0.19+: load matching event row
347
+ exposeAs: 'event', // ← onto ctx.event for the action body
348
+ },
349
+ },
350
+ roles: {
351
+ attendee: { via: 'attendeeOf' },
352
+ },
353
+ }
354
+ ```
355
+
356
+ The resolver (v0.20):
357
+
358
+ 1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
359
+ 2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
360
+ 3. **Tenant stamping from the matched row** — for any tenant column the `from` table carries (`organizationId`, `teamId`), the resolver stamps `ctx.activeOrgId ??= matchedRow.organizationId` (and similar for team). This is **in-memory mutation of the request-scoped ctx only** — no JWT remint, no session-record write, no persistent grant.
361
+ 4. **Firewall-gated load of the loaded resource** — `SELECT * FROM events WHERE id = :eventId AND buildEventsFirewallConditions(ctx, db)`. The events firewall is applied as normal; it succeeds for attendees because tenant was just stamped from the relationship row.
362
+ 5. Assigns the loaded row to `ctx.event` for the action body.
363
+
364
+ **No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
365
+
366
+ ### Conditional tenant preconditions (v0.20+)
367
+
368
+ Standalone actions in features with org/team-scoped tables previously emitted unconditional preconditions:
369
+
370
+ ```ts
371
+ if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
372
+ if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
373
+ ```
374
+
375
+ These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
376
+
377
+ v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / ADMIN / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before.
378
+
379
+ Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
380
+
381
+ ### Requirement on the relationship's `from` table
382
+
383
+ For the v0.20 tenant-stamping to work, the relationship's `from` table must carry tenant columns:
384
+
385
+ - For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
386
+ - For team stamping: a `teamId` column.
387
+
388
+ When the `from` table has **neither**, the compiler emits a `[quickback:authz]` warning at compile time:
389
+
390
+ ```
391
+ Relationship "X" at authz.relationships.X has no organization or team columns
392
+ on its `from` table ("guests"). Action "Y" will compile, but downstream
393
+ scoped-db queries inside execute() may 403 because ctx.activeOrgId /
394
+ activeTeamId cannot be stamped from the match row. Either add the tenant
395
+ column to "guests", or set firewall: { exception: true } on the action.
396
+ ```
397
+
398
+ The relationship match still works (existence check), but no tenant gets stamped — so the conventional precondition still fires and the action still 403s for callers without a session-resident tenant claim. Add the tenant column (or denormalize it onto the relationship table during writes) to enable the stamping path.
399
+
400
+ The body can then trust `ctx.event` and drop the hand-rolled `SELECT … FROM guests WHERE …` boilerplate:
401
+
402
+ ```ts
403
+ // features/chat/actions/getInbox.ts
404
+ export default defineAction({
405
+ path: '/chat/get-inbox',
406
+ input: z.object({ eventId: z.number().int().positive() }),
407
+ access: { roles: ['admin', 'member', 'attendee'] }, // attendee is a relationship-role
408
+ execute: async ({ db, ctx, input }) => {
409
+ // No hand-rolled attendance check needed — the resolver already ran.
410
+ // ctx.event is the loaded events row (typed as any in v0.19; cast as
411
+ // needed — narrow per-action types are a follow-up).
412
+ const event = ctx.event as typeof events.$inferSelect;
413
+ // … domain logic only.
414
+ },
415
+ });
416
+ ```
417
+
418
+ `loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
419
+
420
+ ### Action firewall escape hatch (v0.19+)
421
+
422
+ `defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
423
+
424
+ ```ts
425
+ defineAction({
426
+ path: '/admin/cross-tenant-report',
427
+ firewall: { exception: true },
428
+ unsafe: { reason: 'cross-tenant audit', adminOnly: true, targetScope: 'all' },
429
+ access: { roles: ['ADMIN'] },
430
+ execute: async ({ unsafeDb, ctx }) => { /* cross-org query */ },
431
+ });
432
+ ```
433
+
434
+ `firewall: { exception: true }` is the declarative twin of `unsafe: true` — they're conceptually distinct: `firewall.exception` opts out of the gate-emission pillars; `unsafe` signals audit/cross-tenant intent (and still applies for logging). Most cross-tenant actions set both.
435
+
328
436
  ### Recommended pattern: gate at the firewall layer
329
437
 
330
438
  Most of the time, relationship-based row visibility is what you want, and putting it at the **firewall** layer is the cleanest expression. The firewall is row-filter; the access layer is route/role-filter; let each do its job:
@@ -434,6 +542,100 @@ The validator and resolver reject:
434
542
  - `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
435
543
  - Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
436
544
 
545
+ ## Namespace mounts (hoisted relationship middleware)
546
+
547
+ When several standalone actions share a path prefix and the same relationship gate — `/event/:eventId/announce`, `/event/:eventId/cancel`, `/event/:eventId/respond` — declaring the gate per-action means writing the same `roles: ['attendee']` over and over AND paying the relationship-resolver cost N times per request (one subquery + one row-load, multiplied by the number of actions).
548
+
549
+ Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware and typed automatically inside the handlers.
550
+
551
+ Two declaration sites depending on whether the participating actions live in one feature or many:
552
+
553
+ ### Single feature: `defineTable({ namespace })` (v0.23+)
554
+
555
+ Use when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it — no addition to `quickback.config.ts` needed.
556
+
557
+ ```typescript
558
+ // features/events/events.ts
559
+ export default defineTable(events, {
560
+ firewall: [...],
561
+ crud: { ... },
562
+ namespace: {
563
+ prefix: '/event/:eventId', // absolute URL path
564
+ via: 'attendeeOf', // relationship gate (must exist in authz.relationships)
565
+ },
566
+ });
567
+
568
+ // features/events/actions/post-announcement.ts
569
+ export default defineAction({
570
+ path: '/event/:eventId/announcements',
571
+ method: 'POST',
572
+ // No gate boilerplate. ctx.event is typed inside execute().
573
+ });
574
+ ```
575
+
576
+ The compiler emits one `app.use(...)` on the events feature's Hono app. Every standalone action in `features/events/actions/` whose path starts with `/event/:eventId/` joins the namespace automatically.
577
+
578
+ ### Cross-feature: `authz.namespaces` (v0.24+)
579
+
580
+ Use when the namespace spans multiple features. The declaration sits next to your other authz config in `quickback.config.ts`.
581
+
582
+ ```typescript
583
+ // quickback.config.ts
584
+ authz: {
585
+ relationships: {
586
+ attendeeOf: {
587
+ from: 'guests',
588
+ subject: { column: 'userId', equals: 'ctx.userId' },
589
+ resource: { column: 'eventId' },
590
+ loads: 'events',
591
+ exposeAs: 'event',
592
+ },
593
+ },
594
+ namespaces: {
595
+ eventScope: { prefix: '/event/:eventId', via: 'attendeeOf' },
596
+ },
597
+ }
598
+
599
+ // features/feeds/actions/feed-moments.ts (in a different feature)
600
+ export default defineAction({
601
+ path: '/event/:eventId/feed-moments',
602
+ method: 'POST',
603
+ });
604
+
605
+ // features/rsvp/actions/respond.ts (and another)
606
+ export default defineAction({
607
+ path: '/event/:eventId/respond',
608
+ method: 'POST',
609
+ });
610
+ ```
611
+
612
+ The compiler emits one synthetic `src/routes/__namespace-event-scope.routes.ts` that imports each contributing feature's `actions` map under a distinct alias, mounts the resolver middleware once, and dispatches to the matching action. Worker-root mount order ensures the middleware fires before any per-feature route handler under the prefix.
613
+
614
+ ### Discovery is path-prefix-only
615
+
616
+ Actions opt in by matching `path:` against a declared namespace prefix. There's no `namespace: 'foo'` field on `defineAction` — the path string is the discoverable surface, consistent with how `path:` already determines an action's URL.
617
+
618
+ ### Requirements (enforced at compile time)
619
+
620
+ Both forms share the same shape checks:
621
+
622
+ - **`via:` must point at a declared `authz.relationships[*]` entry**, and that relationship must declare `loads + exposeAs`. Without `loads` there's nothing for the middleware to hydrate, and the namespace gate becomes indistinguishable from a per-action access rule.
623
+ - **`prefix:` must contain at least one `:param` segment** (e.g. `/event/:eventId`). The middleware reads the relationship key from `c.req.param()` because no request body has been parsed at middleware time.
624
+ - **One declaration per namespace name.** The same name in both `defineTable({ namespace })` and `authz.namespaces` is rejected. The project-level form is canonical for cross-feature; the table-level form is the single-feature shorthand.
625
+
626
+ Project-level only:
627
+
628
+ - **Ambiguous prefixes** like `/a/:x` and `/a/:y` (same shape, different `:param` names) are rejected. Strict super/sub-set relationships (`/event/:e` vs `/event/:e/admin`) are fine — the harvester routes each action to the longest matching prefix.
629
+ - **Unused namespace** emits a `[quickback:authz]` warning when no action's path matches the declared prefix. Not a hard error — the namespace may be staged ahead of the actions.
630
+
631
+ ### What namespace actions get for free
632
+
633
+ Inside a namespace action's `execute()`:
634
+
635
+ - `ctx.<exposeAs>` is populated by the middleware with the loaded resource row, typed as `typeof <loadsTable>.$inferSelect`.
636
+ - Tenant context (`ctx.activeOrgId` / `ctx.activeTeamId`) is stamped from the matched relationship row when its `from` table carries those columns. Downstream scoped queries work without further setup.
637
+ - The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
638
+
437
639
  ## Read & Write Configuration
438
640
 
439
641
  Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under top-level `create:`, `update:`, `delete:`, and `upsert:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.
@@ -304,9 +304,9 @@ land in `success[]` masked the same way the single-record response is.
304
304
 
305
305
  | Provider | failFast | transactional | Behavior |
306
306
  |---|---|---|---|
307
- | postgres / supabase / neon / libsql / sqlite drivers | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
307
+ | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the loop; any throw rolls back all writes |
308
308
  | (any) | `false` | `false` | Independent per-record outcomes, partial success |
309
- | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed |
309
+ | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — earlier records stay committed (D1 has no `db.transaction`) |
310
310
 
311
311
  **Constraints:**
312
312
 
@@ -502,13 +502,46 @@ access: async (ctx, record) => {
502
502
  }
503
503
  ```
504
504
 
505
- ### Relationship-roles in actions (v1 limitation)
505
+ ### Relationship-roles in actions
506
506
 
507
- Relationship-roles declared under `authz.roles` (e.g. `guest: { via: 'guestOf' }`) are **not yet supported in action access blocks**. The compiler refuses to build with a clear error message because the binding semantics — which input field or which loaded record's column to check the relationship against — differ between record-actions and standalone-actions and require explicit declaration not yet wired in v1.
507
+ **v0.19+** — standalone actions now support relationship-roles in `access.roles` directly. Declare the relationship under `authz.relationships` with optional `loads` / `exposeAs` for ctx hydration, and reference the role by name on the action:
508
508
 
509
- The runtime evaluator fails closed on unrecognized relationship arms, so silent grants are impossible.
509
+ ```ts
510
+ // quickback.config.ts
511
+ authz: {
512
+ relationships: {
513
+ attendeeOf: {
514
+ from: 'guests',
515
+ subject: { column: 'userId', equals: 'ctx.userId' },
516
+ resource: { column: 'eventId' },
517
+ where: { status: 'confirmed' },
518
+ loads: 'events',
519
+ exposeAs: 'event',
520
+ },
521
+ },
522
+ roles: { attendee: { via: 'attendeeOf' } },
523
+ }
524
+
525
+ // features/chat/actions/getInbox.ts
526
+ export default defineAction({
527
+ path: '/chat/get-inbox',
528
+ input: z.object({ eventId: z.number().int().positive() }),
529
+ access: { roles: ['admin', 'member', 'attendee'] },
530
+ execute: async ({ db, ctx, input }) => {
531
+ // The resolver already verified attendance and loaded ctx.event.
532
+ // No hand-rolled `SELECT … FROM guests WHERE …` needed.
533
+ },
534
+ });
535
+ ```
536
+
537
+ The action's surface (path params + input fields) must expose the relationship's `resource.column`. At v0.19 a missing key emits a `[quickback:authz]` warning and skips resolver emission; at v0.20 it becomes a compile error. See [Access — standalone actions](/compiler/definitions/access#standalone-actions-surface-keys-and-loads--exposeas-v019) for the full mechanism.
538
+
539
+ **Record-based actions** are NOT yet supported — the runtime evaluator fail-closes (403) on relationship arms reached without an inline gate. Until inline emission for record-based actions lands, either:
540
+
541
+ - Set `firewall: { exception: true }` on the action and gate manually in `execute()`, OR
542
+ - Apply the relationship at the resource's firewall layer (worked example below).
510
543
 
511
- **Workaround**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
544
+ **Resource-layer workaround for record-based actions**: gate the action on BA roles only and apply the relationship at the resource layer via a firewall `via:` predicate:
512
545
 
513
546
  ```typescript
514
547
  // quickback.config.ts
@@ -543,7 +576,7 @@ actions: {
543
576
 
544
577
  This pattern composes cleanly: the firewall guarantees the caller has the relationship to the record being acted on; the action's access list keeps the role surface obvious.
545
578
 
546
- A future `actions.<name>.relationshipBindings` declaration is on the roadmap to remove this limitation. See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture.
579
+ See [Access — relationship authorization](/compiler/definitions/access#relationship-based-authorization) for the full picture, including `loads` / `exposeAs` and the `firewall: { exception: true }` escape hatch.
547
580
 
548
581
  ## Scoped Database
549
582
 
@@ -95,7 +95,7 @@ A few mechanics to know:
95
95
 
96
96
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
97
 
98
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, cuid for libsql/bun-sqlite, `crypto.randomUUID()` for supabase, etc. This keeps q's output decoupled from any specific ID library.
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, `crypto.randomUUID()` for Neon, etc. This keeps q's output decoupled from any specific ID library.
99
99
 
100
100
  ### q.scope() — tenant scope columns
101
101
 
@@ -123,10 +123,7 @@ ownerId: q.scope('owner', { source: 'ctx.userId' }),
123
123
 
124
124
  ### Naming Convention
125
125
 
126
- By default, `q` picks the SQL column name from the JS key using the target database's conventional casing:
127
-
128
- - **Postgres family (Supabase, Neon, D1)** → `snake_case` (`organizationId` → `organization_id`)
129
- - **SQLite family (bun-sqlite, better-sqlite3, libsql)** → `camelCase` (`organizationId` → `organizationId`)
126
+ By default, `q` picks the SQL column name from the JS key using the target database's conventional casing. Both `cloudflare-d1` and `neon` default to **`snake_case`** (`organizationId` → `organization_id`).
130
127
 
131
128
  You can override for any project by setting `namingConvention` on the database provider config:
132
129
 
@@ -135,10 +132,9 @@ You can override for any project by setting `namingConvention` on the database p
135
132
  export default {
136
133
  providers: {
137
134
  database: {
138
- name: 'bun-sqlite',
135
+ name: 'cloudflare-d1',
139
136
  config: {
140
- path: './data/app.db',
141
- namingConvention: 'snake_case', // force snake_case everywhere
137
+ namingConvention: 'camelCase', // keep JS-style names in the SQL
142
138
  },
143
139
  },
144
140
  },
@@ -661,7 +657,7 @@ export default defineConfig({
661
657
 
662
658
  Use the Drizzle dialect that matches your database provider:
663
659
 
664
- ### SQLite (D1, Turso, better-sqlite3)
660
+ ### SQLite (Cloudflare D1)
665
661
 
666
662
  ```typescript
667
663
  import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
@@ -675,7 +671,7 @@ export const jobs = sqliteTable('jobs', {
675
671
  });
676
672
  ```
677
673
 
678
- ### PostgreSQL (Supabase, Neon)
674
+ ### PostgreSQL (Neon)
679
675
 
680
676
  ```typescript
681
677
  import { pgTable, text, serial, jsonb, boolean } from 'drizzle-orm/pg-core';
@@ -1,62 +1,44 @@
1
1
  # Quickback Compiler
2
2
 
3
- The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits production-ready output for your chosen target.
3
+ The **Quickback Compiler** is the build tool at the center of Quickback. You write declarative definitions in TypeScript — schema, security rules, validation, custom actions — and the compiler emits a production Hono application for the **Quickback Stack** on Cloudflare.
4
4
 
5
5
  ```
6
- defineTable() ─┐ ┌─► Hono API (Cloudflare D1 / Neon)
7
- ├─► quickback compile┤
8
- defineActions()─┘ └─► RLS policies (Supabase)
6
+ defineTable() ─┐
7
+ ├─► quickback compile ─► Hono API on Cloudflare
8
+ defineActions()─┘ (D1 or Neon)
9
9
  ```
10
10
 
11
- The same definitions, the same DSL — pick the target that fits where you're deploying.
12
-
13
11
  ## What the compiler does
14
12
 
15
13
  When you run `quickback compile`, it:
16
14
 
17
15
  1. **Reads your definitions** — every `defineTable()`, `defineActions()`, and `defineConfig()` in your project
18
16
  2. **Validates security** — firewall, access, guards, and masking are checked for consistency
19
- 3. **Generates target output** — Hono routes + middleware + types + OpenAPI + MCP, or RLS migrations + helper functions
17
+ 3. **Generates output** — Hono routes + middleware + types + OpenAPI spec + MCP server + security artifacts
20
18
  4. **Emits database migrations** — runs `drizzle-kit generate` for schema changes
21
19
 
22
20
  ```
23
21
  quickback/
24
- ├── quickback.config.ts # Compiler configuration (target + providers)
22
+ ├── quickback.config.ts # Compiler configuration (providers, options)
25
23
  └── features/
26
24
  └── jobs/
27
25
  ├── jobs.ts # defineTable(...)
28
26
  └── actions.ts # defineActions(...)
29
27
  ```
30
28
 
31
- ## Two compile targets
32
-
33
- ### [Quickback for Hono API](/compiler/targets/hono-api)
29
+ ## The target: Hono on Cloudflare
34
30
 
35
- Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
31
+ [Quickback for Hono API](/compiler/targets/hono-api) generates a complete Hono application bundled into a Cloudflare Worker. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL via Hyperdrive.
36
32
 
37
33
  ```typescript
38
34
  providers: {
39
35
  runtime: defineRuntime('cloudflare'),
40
- database: defineDatabase('cloudflare-d1'),
36
+ database: defineDatabase('cloudflare-d1'), // or 'neon'
41
37
  auth: defineAuth('better-auth'),
42
38
  }
43
39
  ```
44
40
 
45
- ### [Quickback for Supabase](/compiler/targets/supabase-rls)
46
-
47
- Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your existing app code.
48
-
49
- ```typescript
50
- providers: {
51
- runtime: defineRuntime('supabase'),
52
- database: defineDatabase('supabase'),
53
- auth: defineAuth('supabase-auth'),
54
- }
55
- ```
56
-
57
- ## The shared core
58
-
59
- Whichever target you pick, the **input language is the same**:
41
+ ## The DSL
60
42
 
61
43
  - **[Definitions](/compiler/definitions)** — Schema, Firewall, Access, Guards, Masking, Views, Actions
62
44
  - **[Configuration](/compiler/config)** — `quickback.config.ts`, providers, domains, bindings
@@ -73,13 +55,12 @@ You don't run the compiler binary locally — it runs as a hosted service:
73
55
 
74
56
  1. **Define resources** in `quickback/features/`
75
57
  2. **Compile** with `quickback compile`
76
- 3. **Apply migrations** for your provider
77
- 4. **Test locally** with `npm run dev`
78
- 5. **Deploy** with `npm run deploy` (Hono target) or `supabase db push` (Supabase target)
58
+ 3. **Apply migrations** with `wrangler d1 migrations apply`
59
+ 4. **Test locally** with `wrangler dev`
60
+ 5. **Deploy** with `wrangler deploy`
79
61
 
80
62
  ## Next steps
81
63
 
82
64
  - [Getting Started](/compiler/getting-started) — Create your first project
83
- - [Definitions](/compiler/definitions) — The shared DSL
84
- - [Quickback for Hono API](/compiler/targets/hono-api) — Compile to a Hono app
85
- - [Quickback for Supabase](/compiler/targets/supabase-rls) — Compile to RLS policies
65
+ - [Definitions](/compiler/definitions) — The DSL
66
+ - [Quickback for Hono API](/compiler/targets/hono-api) — Generated output reference
@@ -90,5 +90,4 @@ Your `wrangler.toml` needs these bindings:
90
90
 
91
91
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Step-by-step setup guide with full wrangler.toml configuration
92
92
  - [D1 Database](/compiler/targets/hono-api/database/d1) — D1 setup, multi-database pattern, and security architecture
93
- - [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL with RLS
94
- - [Supabase Integration](/compiler/targets/supabase-rls) — Alternative: Supabase with RLS
93
+ - [Neon Integration](/compiler/targets/hono-api/database/neon) — Alternative: PostgreSQL via Hyperdrive
@@ -141,4 +141,3 @@ src/
141
141
 
142
142
  - [D1](/compiler/targets/hono-api/database/d1) — SQLite at the edge
143
143
  - [Providers](/compiler/config/providers) — All database provider options
144
- - [Quickback for Supabase](/compiler/targets/supabase-rls) — A different Postgres+RLS path that uses Supabase Auth instead of Better Auth
@@ -99,6 +99,25 @@ All actions (both standalone and record-based) receive a **scoped `db`** instanc
99
99
  - Tables with `deletedAt` — soft delete filter (`WHERE deletedAt IS NULL`)
100
100
  - `INSERT` operations auto-inject `organizationId` and `ownerId` from context
101
101
 
102
+ #### `userId` vs `ownerId` on feature tables
103
+
104
+ Use `ownerId` (not `userId`) for the row-owner column on a feature table. The compiler:
105
+
106
+ - Auto-firewalls reads on `ownerId` (`WHERE ownerId = ctx.userId`).
107
+ - Auto-stamps `ownerId` on insert from `ctx.userId`.
108
+ - Treats a `userId` column on a feature table as **informational** — almost always "a user this row references" (member, contact, invitee), not "the row owner."
109
+
110
+ A `userId` column on a feature table emits a compile-time warning. To resolve it:
111
+
112
+ - **Rename to `ownerId`** if the column controls access (most common case).
113
+ - **Rename to `linkedUserId`** (or similar) if the column is informational — explicit naming prevents future confusion.
114
+ - **Declare explicit firewall** if `userId` really is the access column on that table:
115
+ ```ts
116
+ firewall: [{ field: 'userId', equals: 'ctx.userId' }]
117
+ ```
118
+
119
+ Better Auth's own internal tables (`session`, `account`, `member`, `passkey`, `subscriptions`) use `userId` by convention. Those are not feature tables and don't pass through the auto-firewall — the warning only fires on resources you define in your `quickback/` folder.
120
+
102
121
  ```typescript
103
122
  // Your handler receives a scoped db — no manual filtering needed
104
123
  execute: async ({ db, ctx, input }) => {
@@ -264,7 +264,7 @@ rollback.
264
264
 
265
265
  | Endpoint | Provider | `failFast` | `meta.transactional` | Behavior |
266
266
  |----------|----------|-----------|----------------------|----------|
267
- | `PATCH /batch` (update) | postgres / supabase / neon / libsql / better-sqlite3 / bun-sqlite | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
267
+ | `PATCH /batch` (update) | neon (Postgres via Hyperdrive) | `true` | `true` | `db.transaction()` wraps the per-record loop. Any failure rolls back ALL writes in the batch. |
268
268
  | `PATCH /batch` (update) | (any) | `false` | `false` | Per-record loop, partial success. Each record commits independently. |
269
269
  | `PATCH /batch` (update) | cloudflare-d1 | `true` | `false` | Fail-fast loop without rollback — D1 has no `db.transaction`. Records before the failure stay committed. |
270
270
  | `PUT /batch` (upsert) | tx-supporting | `true` | `true` | Bulk insert + per-record update share one transaction. Any failure rolls back both. |
@@ -1,47 +1,19 @@
1
1
  # Compile Targets
2
2
 
3
- The Quickback Compiler reads a single set of definitions — schema, firewall, access, guards, masking, views, actions — and emits production output for the target you choose.
3
+ The Quickback Compiler reads a single set of definitions — schema, firewall, access, guards, masking, views, actions — and emits a production Hono application for the **Quickback Stack** on Cloudflare.
4
4
 
5
- ## The two targets
5
+ ## [Quickback for Hono API](/compiler/targets/hono-api)
6
6
 
7
- ### [Quickback for Hono API](/compiler/targets/hono-api)
8
-
9
- Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server. Pair with **Cloudflare D1** for SQLite-at-the-edge or **Neon** for full PostgreSQL with database-level RLS.
7
+ Generates a complete Hono application: routes, middleware, types, OpenAPI spec, MCP server, security artifacts. Pair with **Cloudflare D1** for SQLite at the edge or **Neon** for full PostgreSQL via Hyperdrive.
10
8
 
11
9
  ```typescript
12
10
  providers: {
13
11
  runtime: defineRuntime('cloudflare'),
14
- database: defineDatabase('cloudflare-d1'),
12
+ database: defineDatabase('cloudflare-d1'), // or 'neon'
15
13
  auth: defineAuth('better-auth'),
16
14
  }
17
15
  ```
18
16
 
19
- Use this target when you want Quickback to generate the entire API surface, not just security policies.
20
-
21
- ### [Quickback for Supabase](/compiler/targets/supabase-rls)
22
-
23
- Generates PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime — Quickback adds the security layer beneath your application code.
24
-
25
- ```typescript
26
- providers: {
27
- runtime: defineRuntime('supabase'),
28
- database: defineDatabase('supabase'),
29
- auth: defineAuth('supabase-auth'),
30
- }
31
- ```
32
-
33
- Use this target when you're already on Supabase and want a typed DSL for RLS.
34
-
35
- ## At a glance
36
-
37
- | | Hono API | Supabase RLS |
38
- |---|----------|--------------|
39
- | What's generated | Routes, middleware, types, OpenAPI, MCP, RLS (Neon only) | RLS policies + helper functions only |
40
- | Database | Cloudflare D1 or Neon Postgres | Supabase Postgres |
41
- | Auth | Better Auth | Supabase Auth |
42
- | Application code | Compiler-generated | You write your own |
43
- | Deployment | `wrangler deploy` (or any Hono runtime) | `supabase db push` |
44
-
45
- ## The shared core
17
+ ## The DSL
46
18
 
47
- Whichever target you pick, the input is the same. See [Definitions](/compiler/definitions) for the DSL that powers both.
19
+ See [Definitions](/compiler/definitions) for the schema + security DSL — the same input drives every output the compiler emits.
@@ -1,6 +1,6 @@
1
1
  # Quickback Documentation
2
2
 
3
- Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript — Quickback compiles them into a Hono API or PostgreSQL Row Level Security policies. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
3
+ Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript — Quickback compiles them into a Hono API running on Cloudflare Workers, plus the Account UI and CMS that ride alongside it. The Quickback Stack is the Supabase alternative on Cloudflare.
4
4
 
5
5
  ## Quick start
6
6
 
@@ -49,12 +49,9 @@ Request → Firewall → Access → Guards → Masking → Response
49
49
 
50
50
  ### Quickback Compiler
51
51
 
52
- [**Quickback Compiler**](/compiler) — the build tool. Define your schema and security rules in TypeScript and compile to one of two targets:
52
+ [**Quickback Compiler**](/compiler) — the build tool. Define your schema and security rules in TypeScript and compile to a complete Hono application on Cloudflare:
53
53
 
54
54
  - **[Quickback for Hono API](/compiler/targets/hono-api)** — A complete Hono application on Cloudflare D1 or Neon, with CRUD, batch endpoints, OpenAPI, and an MCP server.
55
- - **[Quickback for Supabase](/compiler/targets/supabase-rls)** — PostgreSQL Row Level Security policies for Supabase. Keep Supabase Auth, Storage, and Realtime; Quickback adds the security layer.
56
-
57
- The same `defineTable()` definitions work for both targets.
58
55
 
59
56
  **Start here:**
60
57
  - **[Getting Started](/compiler/getting-started)** — Create your first project
@@ -1,18 +1,6 @@
1
1
  # Customization
2
2
 
3
- Customize the Account UI to match your brand and messaging.
4
-
5
- **Standalone (template):** Configure via environment variables, edit `src/config/app.ts` directly, or use `setAppConfig()` for runtime overrides.
6
-
7
- **Library (npm):** Configure entirely via `setAppConfig()`. Import it from `quickback-better-auth-account-ui` instead of `@/config/app`.
8
-
9
- > **Library imports**
10
- >
11
- > All `setAppConfig` examples below use the standalone import path (`@/config/app`). If you're using library mode, replace with:
12
- > ```ts
13
- > import { setAppConfig } from 'quickback-better-auth-account-ui';
14
- > ```
15
-
3
+ Customize the Account UI to match your brand and messaging. Branding is driven by the `account` block in `quickback.config.ts` and the environment variables the compiler bakes in at build time.
16
4
 
17
5
  ## Branding
18
6
 
@@ -373,6 +361,6 @@ import './custom-styles.css'; // Your overrides
373
361
 
374
362
  ## Next Steps
375
363
 
376
- - **[Worker Setup](/stack/account-ui/worker)** - Deploy your customized UI
364
+ - **[With Quickback](/stack/account-ui/with-quickback)** - How the compiler builds and bundles your customized UI
377
365
  - **[Environment Variables](/stack/account-ui/environment-variables)** - Complete configuration reference
378
366
  - **[Feature Flags](/stack/account-ui/features)** - Enable/disable features