@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
@@ -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
@@ -259,6 +259,16 @@ projects acquire build and deployment fixes without losing unrelated tooling.
259
259
 
260
260
  These files are generated only when the corresponding features are configured:
261
261
 
262
+ ### TypeScript artifacts
263
+
264
+ | File | Emitted | Config |
265
+ |------|---------|--------|
266
+ | `quickback.gen.ts` | By default | [`types`](/api/typescript#configuration) |
267
+ | `api-types.gen.ts` | By default | [`openapi.types`](/api/openapi) |
268
+ | `quickback.client.ts` | Opt-in | [`client`](/api/typescript#fetch-client) — a zero-dependency `fetch` client typed by `quickback.gen.ts`; the [components](/ui/components) build on it |
269
+
270
+ All three sit outside `src/`, and each accepts a custom path or a list of paths.
271
+
262
272
  ### Database provider setup files
263
273
 
264
274
  Every compile emits an environment example named for the configured provider.
@@ -412,6 +422,15 @@ Set `compiler.securityContracts.report.signature.required: true` to fail compila
412
422
 
413
423
  The report names the compiler that produced it twice: `compilerVersion` is the semver, and `compilerBuildId` is `<version>@<gitSha>@<builtAt>` — the same string the compiler's `/health` endpoint reports as `buildId`. The semver is a floor that can serve several hosted builds, so a drift tripwire should pin on `compilerBuildId`, not `compilerVersion`.
414
424
 
425
+ ### Data Remediation Report
426
+
427
+ `reports/data-remediation.sql` is emitted when the project has something to check. It is **read-only as emitted** — every statement is a `SELECT`, and the compiler never runs it:
428
+
429
+ - **SQLite / D1:** a count of rows whose `.defaultNow()` or audit timestamp holds the `1970-01-01T00:00:00.000Z` epoch sentinel, per column, with a commented-out repair `UPDATE` where the row has a separate `created_at` to approximate from.
430
+ - **Every dialect:** per `q.url()` column, the rows whose value is not an `http(s)` URL (`javascript:`, `data:`, …).
431
+
432
+ How to run it and what the repair means: [Troubleshooting → Data issues](/tooling/troubleshooting#data-issues).
433
+
415
434
  ### Realtime
416
435
 
417
436
  When any feature has `realtime` configured:
@@ -459,24 +478,28 @@ The compiler separates schemas into two files:
459
478
 
460
479
  ## Generated Routes
461
480
 
462
- For each feature, the compiler generates a routes file at `src/features/{name}/routes.ts` containing:
481
+ For each table with routes, the compiler generates `src/features/{feature}/{table}.routes.ts` containing:
463
482
 
464
483
  | Route | Generated When |
465
484
  |-------|----------------|
466
- | `GET /` | `crud.list` configured |
467
- | `GET /:id` | `crud.get` configured |
485
+ | `GET /` | [`read`](/define/read) declared |
486
+ | `GET /:id` | [`read`](/define/read) declared |
487
+ | `GET /views/{name}` | `read.views.{name}` declared |
468
488
  | `POST /` | `crud.create` configured |
469
489
  | `PATCH /:id` | `crud.update` configured |
470
490
  | `DELETE /:id` | `crud.delete` configured |
471
- | `PUT /:id` | `crud.put` configured |
472
- | `POST /batch` | `crud.create` exists (auto-enabled) |
473
- | `PATCH /batch` | `crud.update` exists (auto-enabled) |
474
- | `DELETE /batch` | `crud.delete` exists (auto-enabled) |
475
- | `PUT /batch` | `crud.put` exists (auto-enabled) |
476
- | `GET /views/{name}` | `views` configured |
491
+ | `PUT /:id` | `crud.put` configured, with `generateId: false` and `guards: false` |
492
+ | `POST /batch` | `crud.create` exists (auto-enabled; `crud.batchCreate: false` opts out) |
493
+ | `PATCH /batch` | `crud.update` exists (auto-enabled; `crud.batchUpdate: false` opts out) |
494
+ | `DELETE /batch` | `crud.delete` exists (auto-enabled; `crud.batchDelete: false` opts out) |
495
+ | `PUT /batch` | `crud.batchUpsert`, or `crud.create` + `crud.update` when `PUT` is enabled |
477
496
  | `POST /:id/{action}` | Record-based actions defined |
478
497
  | `POST /{action}` | Standalone actions defined |
479
498
 
499
+ `crud.list` and `crud.get` are rejected at compile time — collection and
500
+ single-record reads come from `read`. A verb with `routes: false` or mapped to
501
+ an action (`crud.create.action`) emits no raw route and no batch variant.
502
+
480
503
  Routes are mounted under `/api/v1/{feature}` by default, or
481
504
  `/api/v2/{feature}` when `contract: { routes: "v2" }` is set. The standard API shape
482
505
  selects semantics and leaves these paths alone.
@@ -543,6 +566,12 @@ is drift on a live database with no clean fix-forward.
543
566
  Only `meta/_journal.json` is expected to change, because that is where a new
544
567
  entry lands.
545
568
 
569
+ The generated header and footer comments count as part of the file. New
570
+ migrations are stamped with the current header; an existing one keeps the
571
+ header it was first stamped with, byte for byte, because deploy ledgers hash
572
+ applied migrations. See [Troubleshooting](/tooling/troubleshooting#recompile-changed-the-comments-at-the-top-of-an-old-migration)
573
+ if an earlier compiler already rewrote one.
574
+
546
575
  > If `quickback migrations doctor` reports snapshot drift — more journal entries
547
576
  > than snapshot files — that drift came from your project's history, not from
548
577
  > compiling. Compile does not delete snapshots it was never given.