@quickback-dev/cli 0.66.22 → 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/commands/check.js +1 -1
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.js +82 -165
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +92 -1
- package/dist/commands/mcp.js.map +1 -1
- 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/lib/api-client.d.ts +3 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +59 -0
- package/dist/lib/harness.d.ts.map +1 -0
- package/dist/lib/harness.js +178 -0
- package/dist/lib/harness.js.map +1 -0
- 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/start/template-blog.md +36 -58
- package/dist/skill/docs/start/templates.md +3 -3
- package/dist/skill/docs/tooling/claude-skill.md +10 -1
- package/dist/skill/docs/tooling/cli.md +37 -2
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- package/dist/skill/docs/tooling/output.md +1 -1
- package/dist/templates/registry.js +1 -1
- package/dist/templates/registry.js.map +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/start/template-blog.md +36 -58
- package/src/skill/docs/start/templates.md +3 -3
- package/src/skill/docs/tooling/claude-skill.md +10 -1
- package/src/skill/docs/tooling/cli.md +37 -2
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- 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` |
|
|
@@ -19,10 +19,7 @@ my-site/
|
|
|
19
19
|
│ ├── quickback.config.ts # Pinned-organization config
|
|
20
20
|
│ └── features/
|
|
21
21
|
│ └── posts/
|
|
22
|
-
│
|
|
23
|
-
│ └── actions/
|
|
24
|
-
│ ├── publish.ts # Publish action
|
|
25
|
-
│ └── unpublish.ts # Unpublish action
|
|
22
|
+
│ └── posts.ts # Schema, security, and publish/unpublish transitions
|
|
26
23
|
├── src/ # Compiled output (generated)
|
|
27
24
|
├── package.json
|
|
28
25
|
├── tsconfig.json
|
|
@@ -59,17 +56,16 @@ Replace `org_replace_me` with a real Better Auth organization id before deployin
|
|
|
59
56
|
The template includes a `posts` feature with public read access and admin-only write access:
|
|
60
57
|
|
|
61
58
|
```typescript
|
|
62
|
-
import {
|
|
63
|
-
import { defineTable } from "@quickback/compiler";
|
|
59
|
+
import { q, defineTable } from "@quickback/compiler";
|
|
64
60
|
|
|
65
|
-
export const posts =
|
|
66
|
-
id:
|
|
67
|
-
title: text(
|
|
68
|
-
slug: text(
|
|
69
|
-
content: text(
|
|
70
|
-
excerpt: text(
|
|
71
|
-
status: text(
|
|
72
|
-
publishedAt:
|
|
61
|
+
export const posts = q.table("posts", {
|
|
62
|
+
id: q.id(),
|
|
63
|
+
title: q.text().required(),
|
|
64
|
+
slug: q.text().required().unique(),
|
|
65
|
+
content: q.text().optional(),
|
|
66
|
+
excerpt: q.text().optional(),
|
|
67
|
+
status: q.text().default("draft").required(),
|
|
68
|
+
publishedAt: q.timestamp().optional(),
|
|
73
69
|
|
|
74
70
|
// Author tracking only — this is metadata, not access control.
|
|
75
71
|
// Named "authorId" (not "userId") because a `userId` column on a feature
|
|
@@ -77,16 +73,13 @@ export const posts = sqliteTable("posts", {
|
|
|
77
73
|
// column (that name is `ownerId`), and it errors when it is the only
|
|
78
74
|
// candidate column on the table. Reads here are gated by PUBLIC; writes by
|
|
79
75
|
// the admin access check below.
|
|
80
|
-
authorId: text(
|
|
76
|
+
authorId: q.text().required(),
|
|
81
77
|
|
|
82
|
-
// Compiler-managed columns —
|
|
83
|
-
//
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
modifiedBy: text("modified_by"),
|
|
88
|
-
deletedAt: text("deleted_at"),
|
|
89
|
-
deletedBy: text("deleted_by"),
|
|
78
|
+
// Compiler-managed columns — declared, not magic. `...q.audit()` is the
|
|
79
|
+
// audit quartet on every table; `...q.softDelete()` adds the soft-delete
|
|
80
|
+
// pair because `delete.mode` is "soft".
|
|
81
|
+
...q.audit(),
|
|
82
|
+
...q.softDelete(),
|
|
90
83
|
});
|
|
91
84
|
|
|
92
85
|
export default defineTable(posts, {
|
|
@@ -97,9 +90,21 @@ export default defineTable(posts, {
|
|
|
97
90
|
softDelete: {},
|
|
98
91
|
},
|
|
99
92
|
guards: {
|
|
100
|
-
createable: ["title", "slug", "content", "excerpt"
|
|
101
|
-
updatable: ["title", "slug", "content", "excerpt"
|
|
93
|
+
createable: ["title", "slug", "content", "excerpt"],
|
|
94
|
+
updatable: ["title", "slug", "content", "excerpt"],
|
|
102
95
|
immutable: ["id", "authorId"],
|
|
96
|
+
// `status` is workflow-owned: only the transitions below write it.
|
|
97
|
+
protected: { status: ["publish", "unpublish"] },
|
|
98
|
+
},
|
|
99
|
+
// Transitions generate POST /api/v1/posts/:id/publish and its inverse,
|
|
100
|
+
// stamping publishedAt on publish and clearing it on unpublish.
|
|
101
|
+
transitions: {
|
|
102
|
+
publish: {
|
|
103
|
+
field: "status", from: "draft", to: "published",
|
|
104
|
+
stamp: { at: "publishedAt" },
|
|
105
|
+
undo: "unpublish",
|
|
106
|
+
access: { roles: ["admin"] },
|
|
107
|
+
},
|
|
103
108
|
},
|
|
104
109
|
read: {
|
|
105
110
|
access: { roles: ["PUBLIC"] },
|
|
@@ -117,42 +122,15 @@ export default defineTable(posts, {
|
|
|
117
122
|
- **`authorId`** is plain metadata recording who wrote the post — it is deliberately *not* a firewall scope, because an owner predicate would hide every post from anonymous readers
|
|
118
123
|
- **`softDelete`** marks posts as deleted rather than removing them from the database
|
|
119
124
|
|
|
120
|
-
### Post
|
|
125
|
+
### Post Transitions (publish / unpublish)
|
|
121
126
|
|
|
122
|
-
The template
|
|
127
|
+
The template declares the post lifecycle as [transitions](/define/transitions) on the table instead of hand-written action files. The compiler generates both actions — `POST /api/v1/posts/:id/publish` and `POST /api/v1/posts/:id/unpublish` — with the from/to guard, idempotency, and CMS buttons built in:
|
|
123
128
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
import { eq } from "drizzle-orm";
|
|
128
|
-
// The generated per-feature helper re-exports the bound table, so one import
|
|
129
|
-
// gets you both — and `posts` here is the GENERATED table, with the audit
|
|
130
|
-
// columns visible on `record` without `as any`.
|
|
131
|
-
import { defineAction, posts } from "../.quickback/define-action";
|
|
132
|
-
|
|
133
|
-
export default defineAction({
|
|
134
|
-
description: "Publish a draft post",
|
|
135
|
-
input: z.object({}),
|
|
136
|
-
access: {
|
|
137
|
-
roles: ["admin"],
|
|
138
|
-
record: { status: { equals: "draft" } },
|
|
139
|
-
},
|
|
140
|
-
sideEffects: "sync",
|
|
141
|
-
async execute({ db, record }) {
|
|
142
|
-
const [updated] = await db
|
|
143
|
-
.update(posts)
|
|
144
|
-
.set({
|
|
145
|
-
status: "published",
|
|
146
|
-
publishedAt: new Date().toISOString(),
|
|
147
|
-
})
|
|
148
|
-
.where(eq(posts.id, record.id))
|
|
149
|
-
.returning();
|
|
150
|
-
return updated;
|
|
151
|
-
},
|
|
152
|
-
});
|
|
153
|
-
```
|
|
129
|
+
- **`publish`** requires `status: "draft"`, sets `status: "published"`, and stamps `publishedAt`.
|
|
130
|
+
- **`unpublish`** is the generated `undo` pair: it requires `status: "published"`, reverts to `draft`, and clears `publishedAt`.
|
|
131
|
+
- Both are admin-only via `access: { roles: ["admin"] }`; `guards.protected` means nothing else can write `status`, not even a plain `PATCH`.
|
|
154
132
|
|
|
155
|
-
|
|
133
|
+
Need custom logic in the handler? Write `actions/publish.ts` yourself — an explicit action file always wins over the generated one — and keep the same `transition:` block so the guard stays compiler-owned. See [Actions](/define/actions).
|
|
156
134
|
|
|
157
135
|
## Setup Steps
|
|
158
136
|
|
|
@@ -23,9 +23,9 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
|
|
|
23
23
|
| Template | Includes | Command |
|
|
24
24
|
|----------|----------|---------|
|
|
25
25
|
| `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
|
|
26
|
-
| `todos` | Working todos feature: schema, masking, two
|
|
26
|
+
| `todos` | Working todos feature: schema, masking, two transitions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
|
|
27
27
|
|
|
28
|
-
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus
|
|
28
|
+
The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus transitions and views in ~80 lines you can scan in five minutes.
|
|
29
29
|
|
|
30
30
|
### Fixed-org starter
|
|
31
31
|
|
|
@@ -70,7 +70,7 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
|
|
|
70
70
|
|
|
71
71
|
### Todos (recommended for newcomers)
|
|
72
72
|
|
|
73
|
-
Best for learning by reading. Full multi-tenant security pillars, two
|
|
73
|
+
Best for learning by reading. Full multi-tenant security pillars, two transitions (`complete` / `uncomplete`), a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
|
|
74
74
|
|
|
75
75
|
### Blog (pinned-organization CMS)
|
|
76
76
|
|
|
@@ -45,8 +45,15 @@ Add to your AI tool's MCP config:
|
|
|
45
45
|
|
|
46
46
|
### Available Tools
|
|
47
47
|
|
|
48
|
+
The server is a harness, not just a docs index: the agent scaffolds, edits, validates, and builds your project through it, and every compiler error comes back as the tool result. That closed loop is what makes an AI tool converge on a working Quickback backend — the same loop that powers [start.quickback.dev](https://start.quickback.dev), pointed at the project on your disk.
|
|
49
|
+
|
|
48
50
|
| Tool | Description |
|
|
49
51
|
|------|-------------|
|
|
52
|
+
| `status` | Onboarding diagnostic: is this a project, are you logged in, is the compiler reachable, what to do next |
|
|
53
|
+
| `create` | Scaffold a new project from a template (`todos`, `saas`, `blog`, `empty`, `cloudflare`) |
|
|
54
|
+
| `validate` | Validation compile of `quickback/` — seconds, no migrations. Returns `DEFINITIONS VALID` plus warnings or the exact errors to fix, and on success writes the authoring surface the compiler tags: the authored-tree types (`quickback/tsconfig.json`, `.quickback/` helpers and the `src/` modules they type against), `api-types.gen.ts` / `quickback.gen.ts`, and the OpenAPI, AsyncAPI, and schema-registry specs. After three consecutive failures the result tells the agent to stop patching and replan |
|
|
55
|
+
| `check` | Typecheck the authored tree against the generated helpers (`quickback check`) — tables, config, and action files all check right after `validate`, no build needed |
|
|
56
|
+
| `build` | Full compile: the deployable runtime in `src/`, migrations, `wrangler.toml` (`quickback build`) |
|
|
50
57
|
| `list_topics` | List all 100+ documentation topics |
|
|
51
58
|
| `get_doc` | Get a specific doc (supports fuzzy matching — e.g., "firewall") |
|
|
52
59
|
| `search_docs` | Search documentation by keyword |
|
|
@@ -57,6 +64,8 @@ Add to your AI tool's MCP config:
|
|
|
57
64
|
|
|
58
65
|
All documentation topics are also registered as MCP resources at `quickback://docs/{topic}`.
|
|
59
66
|
|
|
67
|
+
`validate` and `build` use your CLI login (`quickback login`, one-time device auth) or `QUICKBACK_API_KEY`. The server reads the directory it was started in, so start it from your project root — or, for a brand-new project, call `create` and then restart it from the new folder.
|
|
68
|
+
|
|
60
69
|
## Claude Code Skill
|
|
61
70
|
|
|
62
71
|
### Installation
|
|
@@ -263,7 +272,7 @@ Make sure the skill file exists and Claude Code is restarted. You can also invok
|
|
|
263
272
|
|
|
264
273
|
### Generated code has errors
|
|
265
274
|
|
|
266
|
-
|
|
275
|
+
Ask the agent to call the `validate` tool (or run `quickback build` yourself and paste the errors). The compiler's messages name the file and the fix.
|
|
267
276
|
|
|
268
277
|
## Cursor IDE Rules
|
|
269
278
|
|
|
@@ -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,11 +187,20 @@ 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
|
|
167
198
|
the check resolves against. Re-run `quickback build` after schema changes so
|
|
168
|
-
they track your tables
|
|
199
|
+
they track your tables — or, in an AI tool, let the [MCP `validate` tool](/tooling/claude-skill#available-tools)
|
|
200
|
+
refresh them: it writes the same typing files, client types, and specs from a
|
|
201
|
+
validation compile without producing the runtime — including the handful of
|
|
202
|
+
`src/` modules the `define-action` helper types `db`, `ctx`, and the table
|
|
203
|
+
against, so action files check too.
|
|
169
204
|
|
|
170
205
|
Within a feature, the single helper import
|
|
171
206
|
(`import { defineAction, tickets } from "../.quickback/define-action"`) is
|
|
@@ -45,6 +45,16 @@ Raw-files requests work with both `?complete=true` and `?complete=false`
|
|
|
45
45
|
(validation-only) compiles. The v2 action-schema completeness gate applies to
|
|
46
46
|
both modes; `complete=false` is not an escape hatch for a partial harvest.
|
|
47
47
|
|
|
48
|
+
Every generated file carries `path`, `content`, and `type`. Files that make up
|
|
49
|
+
the **authoring surface** additionally carry `authoring: true`: the `quickback/`
|
|
50
|
+
typing files (`tsconfig.json`, the `@quickback/compiler` declaration twin, the
|
|
51
|
+
per-feature `.quickback/define-action` helpers), the root client types
|
|
52
|
+
(`api-types.gen.ts`, `quickback.gen.ts`), the specs under
|
|
53
|
+
`src/apps/__quickback/spec/`, and the transitive import closure each helper
|
|
54
|
+
needs from `src/`. A thin client that wants types and specs during development
|
|
55
|
+
without producing a runtime writes exactly the tagged files from a
|
|
56
|
+
`complete=false` compile — that is what the CLI's [MCP `validate` tool](/tooling/claude-skill#available-tools) does.
|
|
57
|
+
|
|
48
58
|
## Edge validation backend
|
|
49
59
|
|
|
50
60
|
Validation compiles (`POST /compile?complete=false`) may be served by an edge Worker instead of the compiler container. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
|
|
@@ -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/
|