@quickback-dev/cli 0.66.23 → 0.66.24
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.
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +2 -0
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +237 -180
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/skill/docs/api/batch-operations.md +12 -3
- package/dist/skill/docs/api/crud.md +5 -1
- package/dist/skill/docs/api/errors.md +19 -0
- package/dist/skill/docs/api/typescript.md +5 -0
- package/dist/skill/docs/configure/bindings.md +15 -0
- package/dist/skill/docs/define/actions/defining.md +45 -2
- package/dist/skill/docs/define/schema.md +9 -6
- package/dist/skill/docs/start/deploy-browser.md +13 -0
- package/dist/skill/docs/tooling/cli.md +32 -1
- package/dist/skill/docs/tooling/output.md +1 -1
- package/package.json +1 -1
- package/src/skill/docs/api/batch-operations.md +12 -3
- package/src/skill/docs/api/crud.md +5 -1
- package/src/skill/docs/api/errors.md +19 -0
- package/src/skill/docs/api/typescript.md +5 -0
- package/src/skill/docs/configure/bindings.md +15 -0
- package/src/skill/docs/define/actions/defining.md +45 -2
- package/src/skill/docs/define/schema.md +9 -6
- package/src/skill/docs/start/deploy-browser.md +13 -0
- package/src/skill/docs/tooling/cli.md +32 -1
- package/src/skill/docs/tooling/output.md +1 -1
|
@@ -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
|
|
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
|
|
|
@@ -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,
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
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
|
|
|
@@ -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
|
|
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 #
|
|
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/
|