@quickback-dev/cli 0.50.8 → 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 (88) 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 +22 -22
  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 +515 -0
  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 +28 -4
  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 +16 -5
  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/rate-limit.md +11 -9
  57. package/dist/skill/docs/compiler/definitions/schema.md +12 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +357 -20
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  60. package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
  61. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  62. package/dist/skill/docs/stack/cms/schema-format.md +4 -2
  63. package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
  64. package/dist/skill/docs/stack/realtime/durable-objects.md +12 -7
  65. package/dist/skill/docs/stack/realtime/index.md +37 -7
  66. package/package.json +1 -1
  67. package/src/skill/docs/changelog.md +515 -0
  68. package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  69. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  70. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  71. package/src/skill/docs/compiler/config/auth.md +28 -4
  72. package/src/skill/docs/compiler/config/index.md +271 -12
  73. package/src/skill/docs/compiler/config/output.md +49 -3
  74. package/src/skill/docs/compiler/config/providers.md +16 -5
  75. package/src/skill/docs/compiler/config/variables.md +5 -0
  76. package/src/skill/docs/compiler/definitions/access.md +7 -0
  77. package/src/skill/docs/compiler/definitions/actions.md +156 -9
  78. package/src/skill/docs/compiler/definitions/firewall.md +6 -1
  79. package/src/skill/docs/compiler/definitions/rate-limit.md +11 -9
  80. package/src/skill/docs/compiler/definitions/schema.md +12 -0
  81. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +357 -20
  82. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  83. package/src/skill/docs/stack/account-ui/hooks.md +104 -1
  84. package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  85. package/src/skill/docs/stack/cms/schema-format.md +4 -2
  86. package/src/skill/docs/stack/cms/schema-registry.md +4 -2
  87. package/src/skill/docs/stack/realtime/durable-objects.md +12 -7
  88. package/src/skill/docs/stack/realtime/index.md +37 -7
@@ -115,12 +115,43 @@ export default defineAction({
115
115
 
116
116
  > **`defineAction` import.** Import from `"../.quickback/define-action"` —
117
117
  > the `.quickback/` directory is generated alongside your feature with a
118
- > typed helper that infers `record` and `input` types from the rest of the
119
- > action config. Audit fields (`createdAt`, `createdBy`, `modifiedAt`,
118
+ > typed helper. It infers `record` and Zod `input`, exposes the generated
119
+ > `Services`, types `c` as a Hono request context, binds `whereRecord` and
120
+ > `whereTransition` to the feature table, and preserves the exact value
121
+ > returned by `execute` without imposing an action-output schema. Scoped
122
+ > `db` and interactive `tx` are schema-aware on D1 and Neon Hyperdrive;
123
+ > HTTP/WebSocket Neon keeps its dynamic database escape hatch. `AppContext`
124
+ > also retains its open index for namespace-hydrated fields. Audit fields
125
+ > (`createdAt`, `createdBy`, `modifiedAt`,
120
126
  > `modifiedBy`) are hard-stamped by the audit DB wrapper on every
121
127
  > `db.insert().values()` and `db.update().set()` — handlers don't pass
122
128
  > them and can't override them.
123
129
 
130
+ ### Local input-schema harvest
131
+
132
+ Before sending a compile request, the CLI loads each action in an isolated
133
+ local bundle and converts `action.input` with Zod 4's `z.toJSONSchema`. It does
134
+ not call `execute`; the hosted compiler never evaluates project code. Under
135
+ contract v2, every action must produce a schema. A failure names the exact
136
+ action, whether bundling or evaluation failed, and the underlying local error.
137
+ V1 can still fall back to the lower-fidelity static schema parser.
138
+
139
+ Bare imports are resolved from the generated runtime's configured
140
+ `build.outputDir/node_modules` first. If definitions live in `quickback/` and
141
+ the generated Worker lives in `src/`, install runtime dependencies in `src/`
142
+ as usual; no project-root dependency symlink is required. Shared schema or DTO
143
+ modules may also declare top-level Drizzle selection objects. Quickback
144
+ replaces authored table exports with inert proxies during this schema-only
145
+ evaluation, so reading `records.id` to build a projection does not execute
146
+ application or database logic.
147
+
148
+ Parameterized standalone paths use Hono's `:param` syntax in authored source,
149
+ for example `path: "/events/:eventId/check-in"`. The harvest planner converts
150
+ those segments to the OpenAPI `{param}` form before applying the schema, so
151
+ contract-v2 completeness uses the same route key as the emitted OpenAPI and MCP
152
+ surfaces. The same normalization applies when a record resource path contains
153
+ namespace parameters.
154
+
124
155
  ### Configuration Options
125
156
 
126
157
  | Option | Required | Description |
@@ -276,6 +307,14 @@ The `input` is shared across the batch — the action's Zod schema is
276
307
  validated once, not per id. For per-record input variation, use the
277
308
  single-record endpoint (`POST /:id/{action}`) or write a standalone action.
278
309
 
310
+ The generated OpenAPI document and MCP tools reuse that exact action schema
311
+ in both places: as the single-record request body and as the bulk wrapper's
312
+ nested `input` property. Under contract v2, Quickback considers the action's
313
+ schema harvest complete only after both operations are patched. This also
314
+ holds when the table filename and declared table name use different casing or
315
+ separators (for example, `event-guests.ts` exporting `event_guests`); the
316
+ operations follow the table's declared resource path.
317
+
279
318
  **Response (207 Multi-Status when any record fails, 200 when clean):**
280
319
 
281
320
  ```json
@@ -660,6 +699,108 @@ async execute({ db, ctx, input }) {
660
699
  - **Masking** — actions are backend code that may need raw data
661
700
  - **Access** — already checked before action execution
662
701
 
702
+ ### Delegated principals and `databaseAccess`
703
+
704
+ On a contract-v2 Cloudflare + Neon Hyperdrive project, an action can admit a
705
+ configured delegated principal with `access.principals`:
706
+
707
+ ```typescript
708
+ export default defineAction({
709
+ description: "Confirm attendance from an event session",
710
+ path: "/attendance/confirm",
711
+ input: z.object({ response: z.enum(["yes", "no"]) }),
712
+ access: { principals: ["event_delegate"] },
713
+ async execute({ ctx, db, input }) {
714
+ // ctx.principal is guaranteed and narrowed by the generated helper.
715
+ const { eventId, personId } = ctx.principal.claims;
716
+ return confirmAttendance(db, { eventId, personId, response: input.response });
717
+ },
718
+ });
719
+ ```
720
+
721
+ This is a separate authority lane, not an account impersonation. A delegated
722
+ action context has no `userId`, active organization/team, or membership roles.
723
+ If access has a `PUBLIC` sibling arm, the generated type includes the anonymous
724
+ lane and code must narrow `ctx.principal` before reading it.
725
+
726
+ For an organization- or team-scoped host feature, the standalone route does
727
+ not run the Better Auth `activeOrgId` / `activeTeamId` precondition before a
728
+ principal access tree. Authentication and `evaluateAccessPreRecord` still run;
729
+ the declared `principals` arm is the authority decision. This avoids turning an
730
+ account-session field into an accidental prerequisite for delegated callers.
731
+
732
+ The generated standalone route reuses that action-specific `execute` context
733
+ after its runtime access gates. Account, `event_pass`, and `event_delegate`
734
+ actions therefore keep distinct compile-time authority types all the way into
735
+ the handler. The route also reuses the action's schema-aware scoped `db` type,
736
+ including when an unsafe/service-role client is wrapped before the call. If a
737
+ relationship uses `loads` / `exposeAs`, the loaded row type is
738
+ intersected with the same authority context: a single or shared hydration
739
+ target is required, while targets selected by distinct relationship lanes are
740
+ optional and must be narrowed by the handler.
741
+
742
+ For tables queried by authored actions, `resource.databaseAccess` adds an
743
+ independent Postgres RLS policy without adding HTTP surface. It never mounts a
744
+ read/CRUD route and never adds an OpenAPI operation. The action remains the API
745
+ layer where validation, state transitions, side effects, and business logic
746
+ belong; `databaseAccess` is only the database's row-level upper bound.
747
+
748
+ ```typescript
749
+ export default defineTable(attendanceEvidence, {
750
+ // Ordinary account CRUD remains organization-scoped.
751
+ firewall: [
752
+ { field: "organizationId", equals: "ctx.activeOrgId" },
753
+ ],
754
+
755
+ // Authored actions can use their caller-scoped db under one of two exact
756
+ // row lanes. Sibling arms OR; fields in each arm AND.
757
+ databaseAccess: {
758
+ select: {
759
+ or: [
760
+ {
761
+ roles: ["AUTHENTICATED"],
762
+ record: {
763
+ organizationId: { equals: "$ctx.activeOrgId" },
764
+ },
765
+ },
766
+ {
767
+ principals: ["event_delegate"],
768
+ record: {
769
+ eventId: { equals: "$ctx.principal.claims.eventId" },
770
+ personId: { equals: "$ctx.principal.claims.personId" },
771
+ },
772
+ },
773
+ ],
774
+ },
775
+ },
776
+ });
777
+ ```
778
+
779
+ `databaseAccess` supports `select`, `insert`, `update`, and `delete`. Its rule
780
+ language is intentionally smaller than application access: `principals`,
781
+ `roles`, recursive `or`/`and`, and record `equals` against a DB-visible account
782
+ or principal context value. `userRole`, functions, request/body values, and
783
+ other predicate operators are compile errors.
784
+
785
+ Every authorization path must contain at least one nonempty record equality.
786
+ A principal-only or role-only leaf is rejected; every `or` arm must be bounded.
787
+ An `and` group is bounded when at least one child bounds every expansion (for
788
+ example, a principal child AND an event-id record child). A node cannot mix
789
+ leaf fields with `or`/`and`, because the boolean node is the complete rule.
790
+ This mandatory shape prevents an action declaration from accidentally granting
791
+ the delegated principal an entire table.
792
+
793
+ The supported equality sources are `ctx.userId`, `ctx.activeOrgId`,
794
+ `ctx.activeTeamId`, `ctx.principal.actor.id`, optional principal session/family
795
+ ids, and `ctx.principal.claims.<name>` (with or without a leading `$`). The
796
+ record keys are Drizzle/JavaScript table field names; Quickback resolves them
797
+ through the table metadata and quotes the exact physical PostgreSQL identifier,
798
+ so a field such as `eventId: text("event-id")` is safe. Unknown fields fail the
799
+ compile. `ADMIN` and the app-only `INTERNAL` marker are forbidden on this DB
800
+ surface, while `SYSADMIN` retains its explicit `cms.sysadmin` prerequisite. The
801
+ feature is rejected outside Cloudflare + Neon Hyperdrive because those targets
802
+ cannot guarantee request-scoped Postgres claims.
803
+
663
804
  ### Relational queries are blocked (fail-closed)
664
805
 
665
806
  Drizzle's relational query API — `db.query.<table>.findFirst()` /
@@ -720,13 +861,19 @@ Unsafe cross-tenant actions are generated with:
720
861
  - sysadmin gate (`ctx.userRole === "sysadmin"`)
721
862
  - mandatory audit logging on deny/success/error
722
863
 
723
- **Provider note (Neon):** on Neon the request-scoped db enforces Row Level
724
- Security with the *caller's* org claims, which would filter out exactly the
725
- cross-tenant rows unsafe actions exist to reach. Unsafe handlers therefore
726
- acquire a dedicated service-role handle (`createServiceDb`) that sets the
727
- `quickback.service_role` transaction marker instead of caller claims; the
728
- generated RLS grants that context an explicit per-table bypass policy. The
729
- audit-logging contract is identical to D1. Neon with
864
+ **Provider note (Neon):** `unsafe.enabled` controls app-layer scoped-query
865
+ bypass, while `unsafe.crossTenant` controls database-layer RLS bypass. An
866
+ unsafe action with `crossTenant: false` receives a raw Drizzle handle backed by
867
+ the request database, so the caller's organization or delegated-principal
868
+ claims remain active—including inside `db.transaction()`. Its code must still
869
+ provide every intended scope predicate explicitly.
870
+
871
+ Only an action with `crossTenant: true` acquires the dedicated service-role
872
+ handle (`createServiceDb`). That handle sets the `quickback.service_role`
873
+ transaction marker instead of caller claims, and generated RLS grants it an
874
+ explicit per-table bypass policy. The sysadmin guard and mandatory audit log
875
+ therefore protect the same boundary that receives the RLS bypass. The
876
+ audit-logging contract is otherwise identical to D1. Neon with
730
877
  `connectionMode: 'websocket'` does not support unsafe actions yet and fails
731
878
  the compile with a descriptive error.
732
879
 
@@ -61,7 +61,7 @@ When you omit the `firewall:` block entirely, the compiler scans the schema for
61
61
 
62
62
  ```typescript
63
63
  type FirewallPredicate =
64
- | { field: string; equals: string; optional?: boolean } // column = ctx.* (or literal)
64
+ | { field: string; equals: string; optional?: boolean; nullable?: true } // column = ctx.* (or literal)
65
65
  | { field: string; isNull: true } // column IS NULL
66
66
  | { field: string; in: string[] | string; optional?: boolean } // column IN (...)
67
67
  | { field: string; via: string } // column IN (relationship subquery)
@@ -97,6 +97,11 @@ Null-safe scope semantics make this safe (these apply **inside `all`/`any` group
97
97
  - Mark an arm `{ optional: true }` to **drop-instead-of-deny** when absent inside an `all` group (the teamless rest-of-org slice — `ctx.activeTeamId` is implicitly optional).
98
98
  - **Owner** (`ctx.userId`) and **soft-delete** (`isNull deletedAt`) are always present / always AND'd — never relaxed.
99
99
 
100
+ `nullable: true` is a separate database-schema opt-in, supported only on an
101
+ owner predicate whose source is exactly `ctx.userId`. It allows the persisted
102
+ owner column to be NULL; NULL rows still do not match the owner arm because SQL
103
+ equality never matches NULL. It does not make the request claim optional.
104
+
100
105
  ```typescript
101
106
  // (org OR event) AND owner AND not-deleted
102
107
  firewall: {
@@ -100,19 +100,19 @@ This means:
100
100
  The compiler walks every resource, collects unique `(limit, period)` tuples, and emits one Cloudflare binding per tuple to `wrangler.toml`:
101
101
 
102
102
  ```toml
103
- [[unsafe.bindings]]
103
+ [[ratelimits]]
104
104
  name = "RL_1000_60"
105
- type = "ratelimit"
106
- namespace_id = "60001000"
105
+ namespace_id = "60002000"
107
106
  simple = { limit = 1000, period = 60 }
108
107
 
109
- [[unsafe.bindings]]
108
+ [[ratelimits]]
110
109
  name = "RL_200_60"
111
- type = "ratelimit"
112
- namespace_id = "60000200"
110
+ namespace_id = "60001200"
113
111
  simple = { limit = 200, period = 60 }
114
112
  ```
115
113
 
114
+ `namespace_id` is a stable per-tuple integer (`1000 + period * 1_000_000 + limit`), so it survives resource reordering and never drifts across recompiles.
115
+
116
116
  Each generated CRUD handler invokes `c.env.RL_<L>_<P>.limit({ key })` between the auth gate and the access check. Hitting the limit returns:
117
117
 
118
118
  ```http
@@ -171,6 +171,8 @@ Set `rateLimit: false` to opt the action out of enforcement entirely.
171
171
 
172
172
  The `:action:` infix is what keeps `update` (resource bucket) and `approve` (action bucket) from sharing counters when they happen to land on the same binding name.
173
173
 
174
+ A record action's bulk variant (`POST /<resource>/batch/<action>`) shares its single-record sibling's key exactly, so a batch of N records consumes **one** token from the action's bucket per request — not N.
175
+
174
176
  ## Cardinality — how many bindings ship
175
177
 
176
178
  Cloudflare bindings are sized at compile time (limit + period are baked in), so the compiler emits one binding per **unique `(limit, period)` tuple**, not one per resource. A project of 50 resources that all use the defaults still ships exactly two rate-limit bindings.
@@ -191,11 +193,11 @@ Cloudflare bindings are sized at compile time (limit + period are baked in), so
191
193
  | Runtime | Rate limiting |
192
194
  |---------|---------------|
193
195
  | `cloudflare` | Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) |
194
- | `bun` | In-process fixed-window counter (`src/lib/rate-limit-memory.ts`). Same generated check code, same 429 response — single-instance only |
196
+ | non-Cloudflare (`bun`, `node`) | Degrades safely — the check no-ops when the binding is absent from `c.env` |
195
197
 
196
- On Bun, the compiler emits `src/lib/rate-limit-memory.ts` and wires up a per-binding shim in the server's fetch handler. Each `RL_<limit>_<period>` shim delegates to a process-memory token bucket, so the same `c.env.RL_*.limit({ key })` call site that targets the Cloudflare binding works unchanged.
198
+ Every generated rate-limit call site — CRUD middleware and custom actions alike — first looks up `c.env.RL_<limit>_<period>` and only calls `.limit({ key })` when the binding is present. On the Cloudflare runtime it always is. On other runtimes it isn't, so the check no-ops and the request proceeds — generated code never hard-depends on the binding.
197
199
 
198
- **Multi-instance Bun deployments** need either a load balancer with sticky sessions (so the same user keeps hitting the same instance and its bucket) or the Cloudflare runtime (which has cross-instance counters out of the box). The in-memory shim does not coordinate across processes.
200
+ **Roadmap — Bun in-process shim.** An in-memory fixed-window shim (`src/lib/rate-limit-memory.ts`) that backs the same `c.env.RL_*.limit({ key })` call site with a process-memory token bucket is planned but **not yet emitted**. Until it lands, non-Cloudflare deployments that need enforcement should sit behind a Cloudflare WAF rule or an upstream rate limiter. A multi-instance Bun shim would additionally need sticky sessions (same user → same instance → same bucket), since a process-memory counter can't coordinate across processes.
199
201
 
200
202
  ## Compile-time validation
201
203
 
@@ -642,6 +642,18 @@ export const jobsRelations = relations(jobs, ({ one, many }) => ({
642
642
  }));
643
643
  ```
644
644
 
645
+ Drizzle `relations(...)` describe application-side joins; they do not always
646
+ create a database foreign-key constraint. On Neon, use
647
+ [`compiler.migrations.foreignKeys`](/compiler/config#neon-foreign-key-migrations)
648
+ for fully qualified cross-schema or composite constraints that cannot be
649
+ declared alongside a table. The ordered source and target column tuples must
650
+ have equal arity, and the referenced target tuple must have a matching unique
651
+ or primary-key constraint before the foreign key migration runs.
652
+
653
+ Use these constraints for relational integrity only. Authorization, pass
654
+ consumption, state transitions, and other business logic belong in the API
655
+ action layer.
656
+
645
657
  ## Database Configuration
646
658
 
647
659
  Configure database options in your Quickback config: