@quickback-dev/cli 0.66.23 → 0.66.25

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 (34) hide show
  1. package/dist/cursor/quickback.mdc +6 -0
  2. package/dist/index.js +1 -1
  3. package/dist/lib/action-harvest.d.ts +2 -0
  4. package/dist/lib/action-harvest.d.ts.map +1 -1
  5. package/dist/lib/action-harvest.js +237 -180
  6. package/dist/lib/action-harvest.js.map +1 -1
  7. package/dist/skill/SKILL.md +6 -0
  8. package/dist/skill/docs/api/batch-operations.md +12 -3
  9. package/dist/skill/docs/api/crud.md +5 -1
  10. package/dist/skill/docs/api/errors.md +19 -0
  11. package/dist/skill/docs/api/typescript.md +5 -0
  12. package/dist/skill/docs/configure/bindings.md +15 -0
  13. package/dist/skill/docs/define/actions/defining.md +45 -2
  14. package/dist/skill/docs/define/authz-roles.md +2 -1
  15. package/dist/skill/docs/define/schema.md +9 -6
  16. package/dist/skill/docs/platform/auth/plugins/subscriptions.md +4 -2
  17. package/dist/skill/docs/start/deploy-browser.md +13 -0
  18. package/dist/skill/docs/tooling/cli.md +32 -1
  19. package/dist/skill/docs/tooling/output.md +20 -1
  20. package/package.json +1 -1
  21. package/src/cursor/quickback.mdc +6 -0
  22. package/src/skill/SKILL.md +6 -0
  23. package/src/skill/docs/api/batch-operations.md +12 -3
  24. package/src/skill/docs/api/crud.md +5 -1
  25. package/src/skill/docs/api/errors.md +19 -0
  26. package/src/skill/docs/api/typescript.md +5 -0
  27. package/src/skill/docs/configure/bindings.md +15 -0
  28. package/src/skill/docs/define/actions/defining.md +45 -2
  29. package/src/skill/docs/define/authz-roles.md +2 -1
  30. package/src/skill/docs/define/schema.md +9 -6
  31. package/src/skill/docs/platform/auth/plugins/subscriptions.md +4 -2
  32. package/src/skill/docs/start/deploy-browser.md +13 -0
  33. package/src/skill/docs/tooling/cli.md +32 -1
  34. package/src/skill/docs/tooling/output.md +20 -1
@@ -172,6 +172,11 @@ output: row(applications)
172
172
  output: z.object({ application: row(applications), created: z.boolean() })
173
173
  ```
174
174
 
175
+ The table can also come from its own table module, a sibling's, or another
176
+ feature's — `row(payments)` from `payments/payments` types as
177
+ `Api.payments.Row` and references the `Payments` component. See
178
+ [Declaring action outputs](/define/actions/defining#declaring-action-outputs).
179
+
175
180
  For any other shape, write the schema out:
176
181
 
177
182
  {/* doc-compile: skip — project-config prerequisite: the `recruiter+` gate needs `recruiter` in `auth.roleHierarchy`, and the gate compiles every fence against one fixed harness config whose roles are member/admin/owner. The file is otherwise whole. */}
@@ -31,6 +31,21 @@ export default defineConfig({
31
31
 
32
32
  camelCase field names map 1:1 to the snake_case TOML blocks in `wrangler.toml`. Every compile regenerates `wrangler.toml` from your config, so these entries are the source of truth — no more post-compile patch scripts.
33
33
 
34
+ Every binding declared here is also typed on `env` — the generated `CloudflareBindings` in `src/env.d.ts`, which actions, service handlers and [`quickback check`](/tooling/cli#typecheck-the-authored-tree) all read — so `env.MAIL_RAW.put(...)` type-checks without a cast:
35
+
36
+ | Field | `env` type |
37
+ |-------|------------|
38
+ | `sendEmail` | `SendEmail` |
39
+ | `r2Buckets` | `R2Bucket` |
40
+ | `queueProducers` | `Queue` |
41
+ | `services` | `Fetcher` |
42
+ | `durableObjects` | `DurableObjectNamespace` |
43
+ | `ai` | `Ai` |
44
+ | `vars` | `string` / `number` / `boolean`, from the value |
45
+ | `secrets` | `string`, optional (`?:`) — the value is set out-of-band |
46
+
47
+ `queueConsumers` bind nothing on `env`. A name the compiler already types (for example `EMAIL`, always present as `EMAIL?: SendEmail`) keeps the compiler's declaration.
48
+
34
49
  ## Fields
35
50
 
36
51
  ### `sendEmail`
@@ -122,6 +122,14 @@ bundling or evaluation failed, and the underlying local error. Output remains
122
122
  optional. A successful harvest reports its denominator —
123
123
  `✔ Resolved 12 of 12 action input schema(s)`.
124
124
 
125
+ Evaluation errors carry a stack trace mapped back to your source files, so
126
+ they name the file and line that threw — including a shared module the action
127
+ imports. Actions are evaluated one after another in one local process; if one
128
+ action's module-level code hangs or ends that process (a loop that never
129
+ exits, a top-level `await` that never settles, `process.exit`), only that
130
+ action fails, with a message ending `— while loading THIS action`, and every
131
+ other action is still harvested.
132
+
125
133
  The count covers the action files **you wrote**. Actions the compiler generates
126
134
  from a table's [`transitions:`](/define/transitions) have no file in your tree,
127
135
  so the CLI never harvests them: they take no input, and the compiler emits
@@ -190,6 +198,41 @@ as array items (the table must be a `defineTable()` resource — anything else
190
198
  is a compile error). At
191
199
  runtime it is a real Zod object built from the table's columns.
192
200
 
201
+ The table can come from anywhere you would import it: the feature's
202
+ `.quickback/define-action` helper, its own table module (the import an action
203
+ in `actions/<table>/` uses), a sibling table's module, or another feature's
204
+ table module. The harvester records the table's owning feature and module, not
205
+ the import spelling, so every form resolves to the same table — another
206
+ feature's table becomes `Api.<otherFeature>.<table>.Row` and that feature's
207
+ component:
208
+
209
+ {/* doc-compile: skip — cross-fence dependency: the action imports three tables across two features (`banking/bankStatements`, `banking/transfers`, `payments/payments`) that the fence does not show, and the gate compiles each fence as an isolated project. The whole project compiles in `tests/e2e/fixtures/row-any-import`. */}
210
+
211
+ ```typescript title="quickback/features/banking/actions/bankStatements/review.ts"
212
+ import { z } from "zod";
213
+ import { defineAction, row } from "../../.quickback/define-action.bankStatements";
214
+ import { bankStatements } from "../../bankStatements";
215
+ import { transfers } from "../../transfers";
216
+ import { payments } from "../../../payments/payments";
217
+
218
+ export default defineAction({
219
+ description: "Review a statement with its matched transfer and payments",
220
+ input: z.object({}),
221
+ output: z.object({
222
+ statement: row(bankStatements),
223
+ transfer: row(transfers).nullable(),
224
+ payments: z.array(row(payments)),
225
+ }),
226
+ access: { roles: ["member"] },
227
+ execute: async ({ record }) => ({ statement: record, transfer: null, payments: [] }),
228
+ });
229
+ ```
230
+
231
+ If `row()` is handed something that is not a table (a column such as
232
+ `row(bankStatements.id)`, or a schema you built), the compile warns, naming
233
+ the action file and the position (`output.transfer`, `output.payments[]`).
234
+ That position is `{}` in OpenAPI and `unknown` in `quickback.gen.ts`.
235
+
193
236
  The harvest substitutes inert proxies for table modules, so anything that
194
237
  derives a schema by enumerating a table's columns — `createSelectSchema` and
195
238
  every equivalent — enumerates **zero** columns. It does not throw. It returns a
@@ -243,7 +286,7 @@ namespace parameters.
243
286
  | `record` | Standalone only | Feature-area transition adapter binding: `{ table, idFrom: "path.<param>", matchScope? }`. Binds + firewalls the record a `transition` operates on from a proven route param. See [Feature-area transition adapter](#feature-area-transition-adapter) |
244
287
  | `bulkVariant` | No | Auto-generate a `POST /:resource/batch/{action}` route alongside the per-record route (record-based actions). See [Bulk Variant](#bulk-variant) |
245
288
  | `webhook` | No | Standalone only. Compile-declared inbound signature verification (`standard-webhooks`, `hmac-sha256`, or `aws-sns`) that runs on the raw bytes **before** parse/access — see [Inbound webhooks](/platform/webhooks/inbound) |
246
- | `rawBody` | No | Standalone, non-GET only. Hand `execute` the request body as received (`rawBody: string`, bounded to 1 MiB) for signature schemes the compiler does not model — a per-organization secret stored in the database, a provider with its own canonicalisation. `input` still parses from the same bytes. Actions with `webhook:` receive `rawBody` automatically — see [Per-organization secrets](/platform/webhooks/inbound#per-organization-secrets-verify-in-the-action) |
289
+ | `rawBody` | No | Standalone, non-GET only. Hand `execute` the request body as received (`rawBody: string`, bounded to 1 MiB) for signature schemes the compiler does not model — a per-organization secret stored in the database, a provider with its own canonicalisation. `input` still parses from the same bytes. Actions with `webhook:` receive `rawBody` automatically. The param is typed exactly that way: `rawBody: string` on those actions, absent on every other — see [Per-organization secrets](/platform/webhooks/inbound#per-organization-secrets-verify-in-the-action) |
247
290
  | `idempotency` | No | `'dedupe'` — PUBLIC-action opt-in for the `Idempotency-Key` header with dedupe-only semantics (duplicate ⇒ `409` reference; the cached body is never served to a second caller). Standalone actions with a **static** path only (a `:param` path is a compile error — the allowlist matches literal request paths) and the action's access must admit `PUBLIC`. Authenticated routes accept the header automatically — see [API contract](/platform/api-contract) |
248
291
  | `cms` | No | Pass-through metadata blob for CMS surfaces |
249
292
 
@@ -263,7 +306,7 @@ guards: {
263
306
  }
264
307
  ```
265
308
 
266
- This allows the `advance` action to set `status = "interview"` even though the field is protected from regular PATCH requests. Direct `PATCH /:id` attempts to set `status` are rejected by the guards layer with **400 GUARD_FIELD_PROTECTED**, and the field is omitted from the generated POST/PATCH body Zod schemas — clients cannot even send it past validation.
309
+ This allows the `advance` action to set `status = "interview"` even though the field is protected from regular PATCH requests. Direct `PATCH /:id` attempts to set `status` are rejected by the guards layer with **400 GUARD_FIELD_PROTECTED** (its `details.actions` names the actions that may change it). The field is also omitted from the generated POST/PATCH body schemas, so OpenAPI and the client types never advertise it.
267
310
 
268
311
  ## Refs (scoped foreign-key inputs)
269
312
 
@@ -64,11 +64,12 @@ export default defineAction({
64
64
 
65
65
  ### Rule shapes
66
66
 
67
- Each entry in `authz.roles` is one of four shapes:
67
+ Each entry in `authz.roles` is one of five shapes:
68
68
 
69
69
  | Shape | Meaning |
70
70
  |---|---|
71
71
  | `{ roles: ['admin', 'member'] }` | Composition — matches any of the listed roles (BA, pseudo, or other named rules) |
72
+ | `{ userRole: ['appmanager', 'sysadmin'] }` | Platform role — the caller's user-table role, same semantics as `access.userRole` on a resource. Lets "paid subscribers **or** operators" be written once: `paid: { or: [{ roles: ['tier_pro'] }, { userRole: ['appmanager', 'sysadmin'] }] }` |
72
73
  | `{ or: [ruleA, ruleB] }` | Matches if **any** sub-rule matches |
73
74
  | `{ and: [ruleA, ruleB] }` | Matches only if **all** sub-rules match |
74
75
  | `{ via: 'relationshipName' }` | Caller proves a declared relationship — see [Relationship-based authorization](#relationship-based-authorization) below |
@@ -77,6 +77,8 @@ export type Job = typeof jobs.$infer;
77
77
 
78
78
  Produces byte-identical output to the `feature()` form above — the compiler expands `feature()` to exactly this shape internally. Use whichever reads better for the file you're writing.
79
79
 
80
+ Code that imports `jobs` — actions, `lib/` files, service handlers — gets the generated Drizzle table (`pgTable` or `sqliteTable`, per your database), because that is what the build hands it. Pass it straight to Drizzle: `db.select({ id: jobs.id }).from(jobs).where(eq(jobs.status, 'open'))`; `typeof jobs.$inferSelect` is the row type. [`quickback check`](/tooling/cli#typecheck-the-authored-tree) types it the same way once the project has compiled.
81
+
80
82
  A few mechanics to know:
81
83
 
82
84
  - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
@@ -1096,12 +1098,13 @@ export default feature('folders', {
1096
1098
 
1097
1099
  `() => folders.id` cannot work here: inside `feature()` there is no `folders`
1098
1100
  binding. In the [two-export form](#qtable--definetable--the-expanded-form)
1099
- the binding exists, but a bare `() => folders.id` inside its own initializer
1100
- is a TypeScript cycle (TS7022/TS7024) in your editor and in `quickback check`.
1101
- Either use `'self'` there too, or annotate the thunk's return type the way
1102
- Drizzle does: `.references((): AnyQuickbackColumn => folders.id)`, with
1103
- `type AnyQuickbackColumn` imported from `@quickback/compiler`. All three
1104
- spellings generate the same schema.
1101
+ the binding exists, and `.references(() => folders.id)` inside its own
1102
+ initializer works: the compiler reads the thunk as source, so its return is
1103
+ not part of the table's type and there is no TypeScript cycle in your editor
1104
+ or in `quickback check`. `'self'` and the annotated
1105
+ `.references((): AnyQuickbackColumn => folders.id)` (with
1106
+ `type AnyQuickbackColumn` from `@quickback/compiler`) are also accepted. All
1107
+ three spellings generate the same schema.
1105
1108
 
1106
1109
  A self-reference is a normal FK everywhere else:
1107
1110
 
@@ -91,12 +91,14 @@ All mounted under your auth base path (`/auth/v1` by default).
91
91
  | `POST` | `/subscriptions/checkout` | Authenticated — creates a Stripe Checkout Session |
92
92
  | `POST` | `/subscriptions/portal` | Authenticated — creates a Stripe billing-portal session |
93
93
  | `GET` | `/subscriptions` | Admin, or org-scoped with `?organizationId=` |
94
- | `POST` | `/subscriptions` | Admin |
95
- | `POST` | `/subscriptions/update` | Admin — takes `{ id, ... }` in the body |
94
+ | `POST` | `/subscriptions` | Admin — `{ userId, tier, organizationId?, status?, limits?, expiresAt?, startsAt? }` |
95
+ | `POST` | `/subscriptions/update` | Admin — takes `{ id, ... }` in the body; any of `tier`, `status`, `limits`, `expiresAt`, `startsAt` |
96
96
  | `POST` | `/subscriptions/delete` | Admin — soft delete, takes `{ id }` in the body |
97
97
 
98
98
  The two admin mutations are `POST` with the id in the **body**, not `PATCH`/`DELETE` on `/subscriptions/:id`. That matches the rest of the Better Auth surface, which is POST-with-body throughout; the generated OpenAPI describes them the same way.
99
99
 
100
+ `expiresAt` and `startsAt` take an ISO-8601 string or epoch milliseconds. This is the manual-billing path: a customer who pays by bank transfer gets a row with a paid-through `expiresAt`, and renewal is bumping that date via `/subscriptions/update`. Omit it (or send `null`) for a comp that grants until revoked — the [expiry bound](#expiry-is-the-second-bound) only applies to rows that carry a date. Anything that does not parse to a real instant is a 400, never a silently expired row.
101
+
100
102
  `GET /subscriptions/me` returns the base tier with `isDefault: true` when the caller has no subscription row, so clients never have to special-case "not subscribed".
101
103
 
102
104
  Checkout takes the tier name, not a price:
@@ -17,6 +17,19 @@ Start keeps authoring, building, and deployment separate:
17
17
 
18
18
  All three tabs remain selectable before a build, so the later stages can explain what they need. Editing a definition after a successful build marks Generated Backend **stale** and blocks Cloudflare deployment until you rebuild. This guarantees that the source being deployed matches the revision you inspected.
19
19
 
20
+ ## Start from an OpenAPI spec
21
+
22
+ Already have an API? On the empty-chat screen, choose **Start from an OpenAPI spec** and upload an OpenAPI 3 file (JSON or YAML, up to 200 operations). Start converts it in your browser before the agent sees it:
23
+
24
+ - Every schema with an id that a `GET` returns becomes a table. Columns map to `q.*` types, `*_id` fields become references, and sensitive names get a masking decision.
25
+ - The spec's CRUD endpoints become CRUD routes, with `guards` taken from the create and update bodies and soft delete where the spec has a `DELETE`.
26
+ - Every other endpoint becomes a typed action stub with its path, method, input and output. The body throws 501.
27
+ - `quickback/OPENAPI.md` records where each endpoint went and what was dropped.
28
+
29
+ The generated files appear in **Quickback Definitions** as if the agent had written them. The first turn then asks the agent to write `quickback.config.ts`, compile, and replace stubs that Quickback already covers — state changes become [transitions](/define/transitions), bulk writes use the [batch routes](/api/batch-operations), filtered lists and counts use query params, simple reports become views. It lists the stubs that still need custom logic and asks you which to write first.
30
+
31
+ Larger specs, Swagger 2.0, and specs with external `$ref`s go through the CLI: `npx openapi-to-quickback convert <spec> quickback/features`, then `quickback build`.
32
+
20
33
  ## Browser vs CLI
21
34
 
22
35
  | | Deploy from Start | `quickback deploy` |
@@ -149,9 +149,35 @@ undone by the compile:
149
149
  export; the build points that path at the generated table module, and
150
150
  `quickback/.quickback/feature-tables.d.ts` gives the check the same named
151
151
  export, typed from the generated schema.
152
+ - **Tables are the generated Drizzle tables** — in the build, the
153
+ `ledgerAccounts` an action imports from a `q.table()` file (or a
154
+ `feature()` file's named export) is the generated `pgTable` /
155
+ `sqliteTable`, so actions pass it straight into Drizzle:
156
+ `db.select({ id: ledgerAccounts.id }).from(ledgerAccounts)`,
157
+ `eq(ledgerAccounts.code, …)`. The check types it the same way —
158
+ `feature-tables.d.ts` maps each table's name to its generated table, for
159
+ your project's dialect — so an unknown column is still an error, and
160
+ `typeof ledgerAccounts.$inferSelect` is the row type.
161
+ - **`.references()` across table files** — a thunk may name another file's
162
+ default export (`import conversations from "./conversations"`, where that
163
+ file ends in `export default defineTable(conversations, …)`), or the
164
+ table being defined (`.references(() => conversations.id)` inside
165
+ `conversations`' own `q.table()`). The build resolves the thunk by the
166
+ table's name; the check accepts both and still checks the column exists.
167
+ - **Generated modules by their generated path** — the build copies
168
+ `quickback/` onto `src/`, so authored code may import a generated module
169
+ the way the generated tree sees it: `import { decryptValue } from
170
+ "../../../lib/encryption"` from `features/<f>/actions/` or `lib/`,
171
+ `"../../lib/encryption"` from `services/schedules/`. The tsconfig's
172
+ `rootDirs` overlays `quickback/` and `src/`, so a path that misses under
173
+ `quickback/` resolves under `src/`, exactly as in the build.
152
174
  - **Queue handlers' dynamic imports** — `await import("./features/…")` is
153
175
  written against the generated `src/` (the handler body is inlined into
154
- `src/queue-consumer.ts`); the tsconfig's `rootDirs` resolves it there too.
176
+ `src/queue-consumer.ts`); the same `rootDirs` resolves it there too.
177
+ - **Declared bindings** — everything `bindings` puts in `wrangler.toml` is
178
+ on `env` (see [Bindings](/configure/bindings)).
179
+ - **ES2022** — both tsconfigs target ES2022, the baseline Workers run, so
180
+ `Array.prototype.at`, `Object.hasOwn` and `Error` `cause` typecheck.
155
181
  - **Service handler contexts** — queue, schedule and email handlers get the
156
182
  `db`, `env` and `services` the generated runners pass them: your project's
157
183
  Drizzle handle, `CloudflareBindings` and `Services`
@@ -161,6 +187,11 @@ undone by the compile:
161
187
 
162
188
  No compile, no server: this is your editor's view of the source, on demand.
163
189
 
190
+ `check` and `build` are held to each other: the output matrix builds every
191
+ fixture — compile, `tsc` of the generated tree — then runs `quickback check`
192
+ on it, and a check error on a project the build accepts fails the matrix.
193
+ The `check-parity` fixtures (D1 and Neon) carry each pattern above.
194
+
164
195
  Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
165
196
  (or a project that has never compiled) exits `2` with a pointer at
166
197
  `quickback build`, which generates the tsconfig, helpers, and compiler types
@@ -52,7 +52,7 @@ quickback/tsconfig.json # Typechecks the authored quickback/ tree (`quic
52
52
  quickback/.quickback/
53
53
  ├── compiler/ # @quickback/compiler declaration snapshot — resolves
54
54
  │ └── … # `import { feature, q, defineTable } from "@quickback/compiler"`
55
- ├── feature-tables.d.ts # Named table exports of feature() files, typed from the generated schema
55
+ ├── feature-tables.d.ts # Every q.table()/feature() table typed as its generated Drizzle table, + feature() named exports
56
56
  └── service-runtime.d.ts # db / env / services types for queue, schedule and email handlers (when any exist)
57
57
  quickback/features/{feature}/
58
58
  └── .quickback/
@@ -577,6 +577,25 @@ if an earlier compiler already rewrote one.
577
577
  > compiling. Compile does not delete snapshots it was never given.
578
578
 
579
579
 
580
+ ### Merging branches that both added migrations
581
+
582
+ Everything under `quickback/drizzle/` is generated — never hand-edit a `.sql`
583
+ file or snapshot, and never resolve a merge conflict inside one. When your branch
584
+ and the target branch each added a migration, the numbers collide and
585
+ `meta/_journal.json` conflicts. Resolve it by regenerating, not merging:
586
+
587
+ 1. Merge the `quickback/` definitions (features, config) as normal.
588
+ 2. Take the target branch's `quickback/drizzle/` as-is, dropping the migrations
589
+ your branch added. The target's history is what deployed databases have.
590
+ 3. `quickback build`. Your schema changes are diffed against the target's latest
591
+ snapshot and appended as a fresh migration after it.
592
+ 4. `quickback migrations doctor` to confirm the journal and snapshots agree.
593
+
594
+ Only drop migrations that were never applied anywhere. D1 records applied
595
+ migrations by path, so if your branch's migration already ran against a shared
596
+ or preview database, dropping it leaves that database drifted — resolve that
597
+ database before merging.
598
+
580
599
  For non-interactive environments (cloud compile, CI), table/column renames must be declared with `compiler.migrations.renames` in `quickback.config.ts`. This avoids interactive rename prompts during migration generation.
581
600
 
582
601
  Migration files follow the Drizzle Kit naming convention: