@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.
- 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/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/lib/migrations/drizzle-prompts.d.ts +2 -0
- package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle-prompts.js +11 -0
- package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +21 -51
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
- package/dist/lib/migrations/prompt-runner.js +6 -1
- package/dist/lib/migrations/prompt-runner.js.map +1 -1
- package/dist/skill/docs/api/actions.md +13 -6
- package/dist/skill/docs/api/batch-operations.md +6 -2
- package/dist/skill/docs/api/crud.md +72 -9
- package/dist/skill/docs/api/errors.md +78 -6
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +6 -7
- package/dist/skill/docs/api/typescript.md +193 -0
- package/dist/skill/docs/configure/index.md +36 -2
- package/dist/skill/docs/configure/providers.md +32 -7
- package/dist/skill/docs/define/changesets.md +2 -0
- package/dist/skill/docs/define/guards.md +7 -2
- package/dist/skill/docs/define/masking.md +14 -0
- package/dist/skill/docs/define/read.md +3 -0
- package/dist/skill/docs/define/schema.md +13 -10
- package/dist/skill/docs/define/transitions.md +9 -4
- package/dist/skill/docs/index.md +1 -0
- package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/dist/skill/docs/platform/payments/index.md +1 -1
- package/dist/skill/docs/start/frontend.md +278 -0
- package/dist/skill/docs/start/index.md +1 -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 +5 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/dist/skill/docs/tooling/output.md +38 -9
- package/dist/skill/docs/tooling/troubleshooting.md +67 -0
- package/dist/skill/docs/ui/admin/actions.md +6 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
- package/dist/skill/docs/ui/admin/schema-format.md +74 -36
- package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
- package/dist/skill/docs/ui/admin/security.md +2 -2
- package/dist/skill/docs/ui/components/action-dialog.md +62 -0
- package/dist/skill/docs/ui/components/auth.md +90 -0
- package/dist/skill/docs/ui/components/index.md +48 -0
- package/dist/skill/docs/ui/components/install.md +118 -0
- package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
- package/dist/skill/docs/ui/components/resource-form.md +80 -0
- package/dist/skill/docs/ui/components/resource-table.md +46 -0
- 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/actions.md +13 -6
- package/src/skill/docs/api/batch-operations.md +6 -2
- package/src/skill/docs/api/crud.md +72 -9
- package/src/skill/docs/api/errors.md +78 -6
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +6 -7
- package/src/skill/docs/api/typescript.md +193 -0
- package/src/skill/docs/configure/index.md +36 -2
- package/src/skill/docs/configure/providers.md +32 -7
- package/src/skill/docs/define/changesets.md +2 -0
- package/src/skill/docs/define/guards.md +7 -2
- package/src/skill/docs/define/masking.md +14 -0
- package/src/skill/docs/define/read.md +3 -0
- package/src/skill/docs/define/schema.md +13 -10
- package/src/skill/docs/define/transitions.md +9 -4
- package/src/skill/docs/index.md +1 -0
- package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/src/skill/docs/platform/payments/index.md +1 -1
- package/src/skill/docs/start/frontend.md +278 -0
- package/src/skill/docs/start/index.md +1 -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 +5 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/src/skill/docs/tooling/output.md +38 -9
- package/src/skill/docs/tooling/troubleshooting.md +67 -0
- package/src/skill/docs/ui/admin/actions.md +6 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/inline-editing.md +6 -2
- package/src/skill/docs/ui/admin/schema-format.md +74 -36
- package/src/skill/docs/ui/admin/schema-registry.md +22 -9
- package/src/skill/docs/ui/admin/security.md +2 -2
- package/src/skill/docs/ui/components/action-dialog.md +62 -0
- package/src/skill/docs/ui/components/auth.md +90 -0
- package/src/skill/docs/ui/components/index.md +48 -0
- package/src/skill/docs/ui/components/install.md +118 -0
- package/src/skill/docs/ui/components/quickback-provider.md +123 -0
- package/src/skill/docs/ui/components/resource-form.md +80 -0
- 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
|
-
│
|
|
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
|
|
|
@@ -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
|
|
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 /` | `
|
|
467
|
-
| `GET /:id` | `
|
|
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.
|
|
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.
|