@quickback-dev/cli 0.66.21 → 0.66.23

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 (114) hide show
  1. package/dist/commands/check.js +1 -1
  2. package/dist/commands/check.js.map +1 -1
  3. package/dist/commands/create.js +82 -165
  4. package/dist/commands/create.js.map +1 -1
  5. package/dist/commands/mcp.d.ts.map +1 -1
  6. package/dist/commands/mcp.js +92 -1
  7. package/dist/commands/mcp.js.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/lib/api-client.d.ts +3 -0
  10. package/dist/lib/api-client.d.ts.map +1 -1
  11. package/dist/lib/api-client.js +1 -1
  12. package/dist/lib/api-client.js.map +1 -1
  13. package/dist/lib/file-writer.d.ts +2 -0
  14. package/dist/lib/file-writer.d.ts.map +1 -1
  15. package/dist/lib/file-writer.js.map +1 -1
  16. package/dist/lib/harness.d.ts +59 -0
  17. package/dist/lib/harness.d.ts.map +1 -0
  18. package/dist/lib/harness.js +178 -0
  19. package/dist/lib/harness.js.map +1 -0
  20. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  21. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  22. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  23. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  24. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  25. package/dist/lib/migrations/file-envelopes.js +21 -51
  26. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  27. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  28. package/dist/lib/migrations/prompt-runner.js +6 -1
  29. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  30. package/dist/skill/docs/api/actions.md +13 -6
  31. package/dist/skill/docs/api/batch-operations.md +6 -2
  32. package/dist/skill/docs/api/crud.md +72 -9
  33. package/dist/skill/docs/api/errors.md +78 -6
  34. package/dist/skill/docs/api/openapi.md +1 -1
  35. package/dist/skill/docs/api/query-params.md +6 -7
  36. package/dist/skill/docs/api/typescript.md +193 -0
  37. package/dist/skill/docs/configure/index.md +36 -2
  38. package/dist/skill/docs/configure/providers.md +32 -7
  39. package/dist/skill/docs/define/changesets.md +2 -0
  40. package/dist/skill/docs/define/guards.md +7 -2
  41. package/dist/skill/docs/define/masking.md +14 -0
  42. package/dist/skill/docs/define/read.md +3 -0
  43. package/dist/skill/docs/define/schema.md +13 -10
  44. package/dist/skill/docs/define/transitions.md +9 -4
  45. package/dist/skill/docs/index.md +1 -0
  46. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  47. package/dist/skill/docs/platform/payments/index.md +1 -1
  48. package/dist/skill/docs/start/frontend.md +278 -0
  49. package/dist/skill/docs/start/index.md +1 -0
  50. package/dist/skill/docs/start/template-blog.md +36 -58
  51. package/dist/skill/docs/start/templates.md +3 -3
  52. package/dist/skill/docs/tooling/claude-skill.md +10 -1
  53. package/dist/skill/docs/tooling/cli.md +5 -1
  54. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
  55. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  56. package/dist/skill/docs/tooling/output.md +38 -9
  57. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  58. package/dist/skill/docs/ui/admin/actions.md +6 -2
  59. package/dist/skill/docs/ui/admin/index.md +1 -1
  60. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  61. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  62. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  63. package/dist/skill/docs/ui/admin/security.md +2 -2
  64. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  65. package/dist/skill/docs/ui/components/auth.md +90 -0
  66. package/dist/skill/docs/ui/components/index.md +48 -0
  67. package/dist/skill/docs/ui/components/install.md +118 -0
  68. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  69. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  70. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  71. package/dist/templates/registry.js +1 -1
  72. package/dist/templates/registry.js.map +1 -1
  73. package/package.json +1 -1
  74. package/src/skill/docs/api/actions.md +13 -6
  75. package/src/skill/docs/api/batch-operations.md +6 -2
  76. package/src/skill/docs/api/crud.md +72 -9
  77. package/src/skill/docs/api/errors.md +78 -6
  78. package/src/skill/docs/api/openapi.md +1 -1
  79. package/src/skill/docs/api/query-params.md +6 -7
  80. package/src/skill/docs/api/typescript.md +193 -0
  81. package/src/skill/docs/configure/index.md +36 -2
  82. package/src/skill/docs/configure/providers.md +32 -7
  83. package/src/skill/docs/define/changesets.md +2 -0
  84. package/src/skill/docs/define/guards.md +7 -2
  85. package/src/skill/docs/define/masking.md +14 -0
  86. package/src/skill/docs/define/read.md +3 -0
  87. package/src/skill/docs/define/schema.md +13 -10
  88. package/src/skill/docs/define/transitions.md +9 -4
  89. package/src/skill/docs/index.md +1 -0
  90. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  91. package/src/skill/docs/platform/payments/index.md +1 -1
  92. package/src/skill/docs/start/frontend.md +278 -0
  93. package/src/skill/docs/start/index.md +1 -0
  94. package/src/skill/docs/start/template-blog.md +36 -58
  95. package/src/skill/docs/start/templates.md +3 -3
  96. package/src/skill/docs/tooling/claude-skill.md +10 -1
  97. package/src/skill/docs/tooling/cli.md +5 -1
  98. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
  99. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  100. package/src/skill/docs/tooling/output.md +38 -9
  101. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  102. package/src/skill/docs/ui/admin/actions.md +6 -2
  103. package/src/skill/docs/ui/admin/index.md +1 -1
  104. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  105. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  106. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  107. package/src/skill/docs/ui/admin/security.md +2 -2
  108. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  109. package/src/skill/docs/ui/components/auth.md +90 -0
  110. package/src/skill/docs/ui/components/index.md +48 -0
  111. package/src/skill/docs/ui/components/install.md +118 -0
  112. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  113. package/src/skill/docs/ui/components/resource-form.md +80 -0
  114. package/src/skill/docs/ui/components/resource-table.md +46 -0
@@ -110,7 +110,7 @@ A few mechanics to know:
110
110
  | Builder | Drizzle equivalent | Zod type |
111
111
  |---------|---------------------|----------|
112
112
  | `q.text()` | `text(...)` | `z.string()` |
113
- | `q.url()` | `text(...)` | `z.string().url()` |
113
+ | `q.url()` | `text(...)` | `z.string().url({ protocol: /^https?$/ })` |
114
114
  | `q.int()` | `integer(...)` | `z.number().int()` |
115
115
  | `q.bigint()` | `bigint(..., { mode: 'number' })` | `z.number().int()` within ±(2^53 − 1) |
116
116
  | `q.smallint()` | `smallint(...)` | `z.number().int()` within −32768..32767 |
@@ -132,9 +132,9 @@ In request bodies a column that is not `.required()` is `.optional().nullable()`
132
132
 
133
133
  `q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
134
134
 
135
- `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
135
+ `q.url()` is `q.text()` plus an absolute-`http(s)`-URL check at the validation edge, so `javascript:` / `data:` / `ftp:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
136
136
 
137
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting. This keeps q's output decoupled from any specific ID library.
137
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting (default `"uuid"`). This keeps q's output decoupled from any specific ID library.
138
138
 
139
139
  #### Typed JSON columns
140
140
 
@@ -168,11 +168,12 @@ The schema must be written inline from `z` and literals, because the compiler co
168
168
  - using `z` anywhere else in the table file
169
169
  - importing anything from `zod` other than `{ z }`
170
170
 
171
- For `generateId: "cuid"`, there is one important nuance: import-capable runtime
172
- paths can emit real `createId()` usage, but compiler-managed schema
173
- auto-injection may keep the same `createId()` call site and back it with a
174
- file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes do not
175
- depend on project `node_modules`.
171
+ Under `generateId: "cuid"`, `"nanoid"`, or `"short"`, the `q.id()` default
172
+ calls an npm helper (`createId` from `@paralleldrive/cuid2`, or `nanoid` /
173
+ `customAlphabet` from `nanoid`). Don't import it in the table file, which may
174
+ not import either package. The compiler adds the import to the generated
175
+ `schema.ts` and the package to `package.json`, so the default mints the same
176
+ id shape as the CRUD route.
176
177
 
177
178
  ### Decimals, dates, 64-bit integers, and arrays
178
179
 
@@ -229,6 +230,8 @@ What you can query depends on the type. The compiler refuses the rest at compile
229
230
 
230
231
  `.searchable()` and `.filterable("like")` are text-only. Masks that format strings (`email`, `phone`, `partial`, and the rest) are refused on `q.bigint()`, `q.smallint()`, and array columns; use `redact` or `custom` there. Decimal and date values are strings, so every mask type works on them. `.defaultNow()` is only accepted on `q.timestamp()`.
231
232
 
233
+ `.defaultNow()` stamps the insert time whenever an insert omits the column. On Postgres it is a real `DEFAULT now()`. On SQLite / D1 the column carries a constant `DEFAULT '1970-01-01T00:00:00.000Z'` (D1 refuses a non-constant default on `ALTER TABLE ADD COLUMN`) plus a `$defaultFn`, and the generated `src/db/index.ts` makes every Drizzle insert use the `$defaultFn` — so only raw SQL that omits the column gets the epoch. Compilers from v0.33.2 until this fix wrote the epoch for Drizzle inserts too; see [Troubleshooting → timestamps read 1970-01-01](/tooling/troubleshooting#timestamps-read-1970-01-01-sqlite--d1) to find and repair affected rows.
234
+
232
235
  ### q.scope() — tenant scope columns
233
236
 
234
237
  `q.scope(kind)` is the canonical way to declare a column that holds a tenant-scope value (org / owner / team). It compiles to `text(...).notNull()` like a regular required text column, plus metadata that the compiler reads to:
@@ -672,7 +675,7 @@ Opt out of audit injection entirely with `compiler.features.auditFields: false`
672
675
 
673
676
  The scoped `db` injected into actions stamps these four columns for you. A handle built directly from `createDb()` does not — that's the documented escape hatch for system writes, sessionless principals, and broad reads the scoped wrapper over-narrows.
674
677
 
675
- Those writes still land in audit-managed tables, and the managed columns carry a DDL default of the unix epoch (so `ALTER TABLE ADD COLUMN` works on populated tables). An omitted column therefore **does not** fail loudly on `NOT NULL` — it silently persists `1970-01-01T00:00:00.000Z`, which reads as a real timestamp everywhere downstream.
678
+ Those writes still land in audit-managed tables. A Drizzle insert that omits `createdAt` / `modifiedAt` gets the insert time (Postgres `DEFAULT now()`; on SQLite the column's `$defaultFn`), but nothing fills `createdBy` / `modifiedBy` — they stay `NULL`. On SQLite the managed timestamps also carry a DDL default of the unix epoch (so `ALTER TABLE ADD COLUMN` works on populated tables), so **raw SQL** that omits them does not fail on `NOT NULL` — it silently persists `1970-01-01T00:00:00.000Z`, which reads as a real timestamp everywhere downstream.
676
679
 
677
680
  Spread the stamp instead of hand-writing four columns at each call site:
678
681
 
@@ -771,7 +774,7 @@ If this is an intentional system-side write, use the unwrapped db directly.
771
774
  Two paths to fix it, depending on intent:
772
775
 
773
776
  - **Mint a synthetic actor** (preferred — preserves attribution) — populate `ctx.userId` with one of the conventions above before calling into your handler.
774
- - **Bypass the wrapper entirely** — use the unwrapped `createDb` instead of the request-context `db`. Use this only for migrations, schema repair, or backfill scripts where you genuinely don't want any audit attribution. The audit columns will fall back to DB defaults (`createdAt`/`modifiedAt` populate from `defaultNow()`; `createdBy`/`modifiedBy` end up `NULL`).
777
+ - **Bypass the wrapper entirely** — use the unwrapped `createDb` instead of the request-context `db`. Use this only for migrations, schema repair, or backfill scripts where you genuinely don't want any audit attribution. `createdAt`/`modifiedAt` still get the insert time from their column default (a raw SQL insert that omits them on SQLite gets the epoch — set them yourself); `createdBy`/`modifiedBy` end up `NULL`.
775
778
 
776
779
  ### Disabling Audit Fields
777
780
 
@@ -256,14 +256,19 @@ otherwise the action would be unreachable, which is almost certainly a bug.
256
256
 
257
257
  ### Wire-level errors
258
258
 
259
- The compiled guard returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** with
260
- the field, the current value, the requested target, and the allowed set:
259
+ The compiled guard returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** as
260
+ `application/problem+json` (like every [API error](/api/errors)), with the
261
+ field, the current value, the requested target, and the allowed set:
261
262
 
262
263
  ```json
263
264
  {
264
- "error": "Action not allowed for current record state",
265
- "layer": "access",
265
+ "type": "https://quickback.dev/problems/access-action-not-allowed-for-state",
266
+ "title": "Access action not allowed for state",
267
+ "status": 409,
266
268
  "code": "ACCESS_ACTION_NOT_ALLOWED_FOR_STATE",
269
+ "detail": "Action not allowed for current record state",
270
+ "instance": "/api/v1/applications/app_123/advance",
271
+ "layer": "access",
267
272
  "details": {
268
273
  "field": "status",
269
274
  "current": "interview",
@@ -76,5 +76,6 @@ The runtime services around your compiled code. Everything you need for a comple
76
76
  - **[Webhooks](/platform/webhooks)** — Inbound (signed) and outbound (retried)
77
77
  - **[Admin UI](/ui/admin)** — Schema-driven admin UI
78
78
  - **[Account UI](/ui/account)** — Pre-built auth and profile pages
79
+ - **[Components](/ui/components)** — shadcn tables, forms, and action dialogs for your own React app
79
80
 
80
81
  Everything runs on **your own Cloudflare account** — no Quickback infrastructure between you and your data.
@@ -124,7 +124,7 @@ When `fromOpenAPI: false`, the emitted call has `capabilities: []` and no proxy
124
124
  - **WebAuthn step-up isn't wired in the approval UI yet.** Capabilities tagged `approvalStrength: "webauthn"` show a Step-up badge but the actual escalation call isn't made — the upstream API for that escalation is still settling. Until it lands, those capabilities will fail server-side regardless of approval.
125
125
  - **No CLI helpers for listing / revoking agents.** Use the BA admin API directly.
126
126
  - **Self-fetch on Cloudflare Workers** adds one subrequest per capability call (~50ms). For typical agent traffic this is fine; for very high-frequency agents consider pinning a custom `onExecute` that uses `app.request()` for in-process routing.
127
- - **`@better-auth/agent-auth` 0.4.5 ships ESM-only exports** without a `require` condition. The compiler image patches the package's `package.json` at install time so the Better Auth CLI's `auth generate` step (jiti / CJS) can resolve it. Remove the patch in the Dockerfile when upstream ships proper exports.
127
+ - **`@better-auth/agent-auth` 0.6.2 ships ESM-only exports** without a `require` condition. The compiler image patches the package's `package.json` at install time so the Better Auth CLI's `auth generate` step (jiti / CJS) can resolve it. Remove the patch in the Dockerfile when upstream ships proper exports.
128
128
 
129
129
  ## Why bearer-only?
130
130
 
@@ -39,7 +39,7 @@ Condition 2 is broader than it may look, and deliberately so. There is no
39
39
  per-provider inbound webhook configuration surface: the inbound route registers
40
40
  exactly one provider, Stripe, so *any* project that turned webhooks on is a
41
41
  project that can receive Stripe events. The same condition adds `stripe` to the
42
- generated `package.json` (pinned at `^22.5.0`), so the dependency and the client
42
+ generated `package.json` (pinned at `^22.6.1`), so the dependency and the client
43
43
  can never disagree about whether Stripe is in play.
44
44
 
45
45
  > **Accepted over-trigger.** A project that only *receives* Stripe webhooks and
@@ -0,0 +1,278 @@
1
+ # Build a frontend
2
+
3
+ This guide builds a React app that lists, creates, edits, and closes jobs
4
+ against your API. It uses the [components](/ui/components) (shadcn registry
5
+ items) on top of the emitted [fetch client](/api/typescript#fetch-client).
6
+
7
+ ```
8
+ my-app/
9
+ ├── quickback.config.ts
10
+ ├── quickback/features/jobs/ # your API definitions
11
+ ├── src/ # generated Worker (never edit)
12
+ └── web/ # your React app (you own it)
13
+ └── src/lib/
14
+ ├── quickback.client.ts # emitted every compile
15
+ └── quickback.gen.ts # emitted every compile
16
+ ```
17
+
18
+ ## 1. Scaffold the app
19
+
20
+ From the project root, create a Vite app with a shadcn **base-ui** style. The
21
+ components don't support Radix styles.
22
+
23
+ ```bash
24
+ npx shadcn@latest init -t vite -b base -p nova -n web
25
+ cd web && npm install better-auth && cd ..
26
+ ```
27
+
28
+ ## 2. Emit the client into it
29
+
30
+ Add three keys to the scaffolded config and keep everything else:
31
+
32
+ ```typescript
33
+ // quickback.config.ts
34
+ import { defineConfig } from "@quickback/compiler";
35
+
36
+ export default defineConfig({
37
+ // …name, providers, etc. from the scaffold
38
+ types: { output: "web/src/lib/quickback.gen.ts" },
39
+ client: "web/src/lib/quickback.client.ts",
40
+ // The components read GET /api/v1/schema. Its default ("sysadmin")
41
+ // would 403 every other user; "member" admits organization members.
42
+ schemaRegistry: { access: "member" },
43
+ });
44
+ ```
45
+
46
+ The client imports its types from the first `types` output, so both files
47
+ live inside `web/`.
48
+
49
+ ## 3. Define the API
50
+
51
+ ```typescript
52
+ // quickback/features/jobs/jobs.ts
53
+ import { feature, q } from "@quickback/compiler";
54
+
55
+ export default feature("jobs", {
56
+ columns: {
57
+ id: q.id(),
58
+ title: q.text().required(),
59
+ department: q.text().required(),
60
+ status: q.text().default("open").required(),
61
+ salaryMin: q.int().optional(),
62
+ organizationId: q.scope("organization"),
63
+ ...q.audit(),
64
+ ...q.softDelete(),
65
+ },
66
+ guards: {
67
+ createable: ["title", "department", "salaryMin"],
68
+ updatable: ["title", "department", "salaryMin"],
69
+ protected: { status: ["close"] },
70
+ },
71
+ read: { access: { roles: ["owner", "admin", "member"] } },
72
+ create: { access: { roles: ["owner", "admin"] } },
73
+ update: { access: { roles: ["owner", "admin"] } },
74
+ delete: { access: { roles: ["owner", "admin"] }, mode: "soft" },
75
+ });
76
+
77
+ // quickback/features/jobs/actions/close.ts
78
+ import { z } from "zod";
79
+ import { eq } from "drizzle-orm";
80
+ import { defineAction, jobs } from "../.quickback/define-action";
81
+
82
+ export default defineAction({
83
+ description: "Close the job to new applications",
84
+ input: z.object({ reason: z.string().optional() }),
85
+ access: { roles: ["owner", "admin"], record: { status: { equals: "open" } } },
86
+ async execute({ db, record }) {
87
+ const [row] = await db
88
+ .update(jobs)
89
+ .set({ status: "closed" })
90
+ .where(eq(jobs.id, record.id))
91
+ .returning();
92
+ return row;
93
+ },
94
+ });
95
+ ```
96
+
97
+ `status` is `protected`: the form shows it disabled, and only `close` can
98
+ change it.
99
+
100
+ ```bash
101
+ quickback build # writes src/ and web/src/lib/quickback.{client,gen}.ts
102
+ npm run dev # API on http://localhost:8787
103
+ ```
104
+
105
+ ## 4. Add the components
106
+
107
+ In `web/components.json`, add the registry:
108
+
109
+ ```json
110
+ {
111
+ "registries": {
112
+ "@quickback": "https://docs.quickback.dev/r/{style}/{name}.json"
113
+ }
114
+ }
115
+ ```
116
+
117
+ ```bash
118
+ cd web
119
+ npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
120
+ npx shadcn add dialog
121
+ ```
122
+
123
+ This installs `quickback-provider` too, since every item depends on it.
124
+
125
+ ## 5. Sign in and render
126
+
127
+ ```tsx
128
+ // web/src/lib/api.ts
129
+ import { createAuthClient } from "better-auth/react"
130
+ import { organizationClient } from "better-auth/client/plugins"
131
+ import { createClient } from "@/lib/quickback.client"
132
+
133
+ const baseURL = import.meta.env.VITE_API_URL ?? "http://localhost:8787"
134
+
135
+ export const auth = createAuthClient({ baseURL, basePath: "/auth/v1", plugins: [organizationClient()] })
136
+ export const client = createClient({ baseUrl: baseURL })
137
+ ```
138
+
139
+ ```tsx
140
+ // web/src/App.tsx
141
+ import { useState } from "react"
142
+ import { auth, client } from "@/lib/api"
143
+ import { buttonVariants } from "@/components/ui/button"
144
+ import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"
145
+ import { QuickbackProvider } from "@/components/quickback-provider"
146
+ import { ResourceTable } from "@/components/resource-table"
147
+ import { ResourceForm } from "@/components/resource-form"
148
+ import { ActionDialog } from "@/components/action-dialog"
149
+
150
+ export default function App() {
151
+ const session = auth.useSession()
152
+ const member = auth.useActiveMember()
153
+ if (session.isPending) return null
154
+ if (!session.data) return <SignIn />
155
+ // Roles are a UI hint (masking, hiding Delete); the API stays authoritative.
156
+ return (
157
+ <QuickbackProvider client={client} roles={member.data ? [member.data.role] : undefined}>
158
+ <Jobs />
159
+ </QuickbackProvider>
160
+ )
161
+ }
162
+
163
+ function SignIn() {
164
+ const [error, setError] = useState<string>()
165
+ async function submit(form: FormData) {
166
+ const res = await auth.signIn.email({
167
+ email: String(form.get("email")),
168
+ password: String(form.get("password")),
169
+ })
170
+ if (res.error) return setError(res.error.message)
171
+ // Tables are firewalled to the active organization — pick one.
172
+ const orgs = await auth.organization.list()
173
+ const org = orgs.data?.[0] ?? (await auth.organization.create({ name: "Acme", slug: `acme-${Date.now()}` })).data
174
+ if (org) await auth.organization.setActive({ organizationId: org.id })
175
+ }
176
+ return (
177
+ <form action={submit} className="mx-auto flex max-w-sm flex-col gap-2 p-6">
178
+ <label>Email <input name="email" type="email" required /></label>
179
+ <label>Password <input name="password" type="password" required /></label>
180
+ <button className={buttonVariants()}>Sign in</button>
181
+ {error && <p role="alert">{error}</p>}
182
+ </form>
183
+ )
184
+ }
185
+
186
+ function Jobs() {
187
+ const [editing, setEditing] = useState<string | null>() // undefined closed, null create
188
+ const [closing, setClosing] = useState<string>()
189
+ const done = () => setEditing(undefined)
190
+
191
+ return (
192
+ <main className="mx-auto flex max-w-5xl flex-col gap-4 p-6">
193
+ <button className={buttonVariants()} onClick={() => setEditing(null)}>New job</button>
194
+
195
+ <ResourceTable
196
+ table="jobs"
197
+ onRowClick={(row) => setEditing(String(row.id))}
198
+ rowActions={(row) => (
199
+ <button className={buttonVariants({ variant: "outline", size: "sm" })} onClick={() => setClosing(String(row.id))}>
200
+ Close
201
+ </button>
202
+ )}
203
+ />
204
+
205
+ <Dialog open={editing !== undefined} onOpenChange={(open) => !open && done()}>
206
+ <DialogContent>
207
+ <DialogHeader><DialogTitle>{editing ? "Edit job" : "New job"}</DialogTitle></DialogHeader>
208
+ {editing !== undefined && (
209
+ <ResourceForm table="jobs" id={editing ?? undefined} onSuccess={done} onCancel={done} onDeleted={done} />
210
+ )}
211
+ </DialogContent>
212
+ </Dialog>
213
+
214
+ <ActionDialog
215
+ table="jobs"
216
+ action="close"
217
+ id={closing}
218
+ open={closing !== undefined}
219
+ onOpenChange={(open) => !open && setClosing(undefined)}
220
+ />
221
+ </main>
222
+ )
223
+ }
224
+ ```
225
+
226
+ Create an account first. Either `POST /auth/v1/sign-up/email` as in the
227
+ [quickstart](/start/quickstart#test-your-api), or add a sign-up form with
228
+ `auth.signUp.email`. Then run the app:
229
+
230
+ ```bash
231
+ npm run dev # http://localhost:5173
232
+ ```
233
+
234
+ The browser sends the Better Auth session cookie with every request.
235
+ `http://localhost:5173` is a trusted origin by default until the project has
236
+ a production domain, so writes pass the CSRF check. See
237
+ [Auth](/ui/components/auth) for the rules, and for bearer tokens in React
238
+ Native.
239
+
240
+ What you get for free:
241
+
242
+ - **Only permitted fields.** The form shows `guards.createable` /
243
+ `updatable`, and `status` stays locked.
244
+ - **Errors inline.** A guard or validation `400` shows under its field. A
245
+ `403` shows the problem's `detail`.
246
+ - **Close only when open.** The action's `record` precondition runs on the
247
+ server. Closing a closed job shows the rejection in the dialog.
248
+ - **Role-aware.** Delete and `close` both require `owner` or `admin`. A
249
+ `member` therefore sees no Delete button, and the Close dialog shows a role
250
+ message instead of its form. The API enforces the same rules either way.
251
+
252
+ ## 6. Ship it on the same Worker
253
+
254
+ Serve the built app from the API's own Worker. It shares the API's origin, so
255
+ it needs no CORS setup, and its hostname is trusted automatically.
256
+
257
+ ```bash
258
+ cd web && VITE_API_URL=https://app.example.com npm run build && cd ..
259
+ rm -rf quickback/apps/web && cp -r web/dist quickback/apps/web
260
+ ```
261
+
262
+ ```typescript
263
+ // quickback.config.ts — add alongside the rest
264
+ apps: {
265
+ web: { domain: "app.example.com" },
266
+ },
267
+ ```
268
+
269
+ `quickback build` copies `quickback/apps/web/` into the Worker's assets, then
270
+ `quickback deploy` ships both. See
271
+ [App domains](/configure/domains#app-domains). To host the app elsewhere
272
+ instead, add its origin to [`trustedOrigins`](/configure#trusted-origins).
273
+
274
+ ## Next
275
+
276
+ - [Components](/ui/components): every prop and hook
277
+ - [Fetch client](/api/typescript#fetch-client): typed calls beyond the components
278
+ - [Query parameters](/api/query-params): what `useList` params map to
@@ -36,6 +36,7 @@ quickback/
36
36
  - **[Define](/define)** — the DSL: schema, the security pillars, reads, writes, actions
37
37
  - **[Configure](/configure)** — `quickback.config.ts`, providers, domains, bindings
38
38
  - **[Use the API](/api)** — what the generated endpoints look like
39
+ - **[Build a frontend](/start/frontend)** — a React app on your API with the typed client and shadcn components
39
40
 
40
41
  The rest of this page is the vocabulary the other pages assume.
41
42
 
@@ -19,10 +19,7 @@ my-site/
19
19
  │ ├── quickback.config.ts # Pinned-organization config
20
20
  │ └── features/
21
21
  │ └── posts/
22
- │ ├── posts.ts # Schema + security (defineTable)
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 { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
63
- import { defineTable } from "@quickback/compiler";
59
+ import { q, defineTable } from "@quickback/compiler";
64
60
 
65
- export const posts = sqliteTable("posts", {
66
- id: text("id").primaryKey(),
67
- title: text("title").notNull(),
68
- slug: text("slug").notNull().unique(),
69
- content: text("content"),
70
- excerpt: text("excerpt"),
71
- status: text("status").notNull().default("draft"),
72
- publishedAt: text("published_at"),
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("author_id").notNull(),
76
+ authorId: q.text().required(),
81
77
 
82
- // Compiler-managed columns — the audit quartet on every table, plus the
83
- // soft-delete pair because `delete.mode` is "soft".
84
- createdAt: text("created_at").notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString()),
85
- modifiedAt: text("modified_at").notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString()).$onUpdate(() => new Date().toISOString()),
86
- createdBy: text("created_by"),
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", "status", "publishedAt"],
101
- updatable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
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 Actions (actions/publish.ts, actions/unpublish.ts)
125
+ ### Post Transitions (publish / unpublish)
121
126
 
122
- The template scaffolds one file per action under `features/posts/actions/`. Each is a `defineAction` with a record-level access condition and an `execute` handler:
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
- ```typescript
125
- // quickback/features/posts/actions/publish.ts
126
- import { z } from "zod";
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
- `unpublish.ts` is the mirror image — it requires `status: "published"` and reverts the post to draft. These actions are admin-only and include record-level access conditions: you can only publish drafts and unpublish published posts.
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 actions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
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 actions and views in ~80 lines you can scan in five minutes.
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 actions, 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.
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
- Run `quickback build` to validate. Share the error messages with Claude for fixes.
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
 
@@ -165,7 +165,11 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
165
165
  (or a project that has never compiled) exits `2` with a pointer at
166
166
  `quickback build`, which generates the tsconfig, helpers, and compiler types
167
167
  the check resolves against. Re-run `quickback build` after schema changes so
168
- they track your tables.
168
+ they track your tables — or, in an AI tool, let the [MCP `validate` tool](/tooling/claude-skill#available-tools)
169
+ refresh them: it writes the same typing files, client types, and specs from a
170
+ validation compile without producing the runtime — including the handful of
171
+ `src/` modules the `define-action` helper types `db`, `ctx`, and the table
172
+ against, so action files check too.
169
173
 
170
174
  Within a feature, the single helper import
171
175
  (`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.
@@ -94,6 +94,12 @@ A failed generate or postprocessor leaves existing migration history untouched.
94
94
  Do not use raw `drizzle-kit generate` as an equivalent workaround for an auth
95
95
  upgrade: it skips Quickback's OAuth client backfills and resource-grant cleanup.
96
96
 
97
+ `drizzle-kit exited after answering a rename prompt without writing a migration`
98
+ means the generator process ended mid-prompt. A prompt only appears when there
99
+ is a schema diff, so this is always a failure: nothing was written and the
100
+ existing history is untouched. Re-run the build; if it repeats, report it with
101
+ the Drizzle output from the error.
102
+
97
103
  ## `Critical command failed: Generate features database migrations`
98
104
 
99
105
  drizzle-kit could not load the generated **features** schema. The usual cause on