@quickback-dev/cli 0.66.21 → 0.66.22

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 (84) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  3. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  4. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  5. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  6. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  7. package/dist/lib/migrations/file-envelopes.js +21 -51
  8. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  9. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  10. package/dist/lib/migrations/prompt-runner.js +6 -1
  11. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  12. package/dist/skill/docs/api/actions.md +13 -6
  13. package/dist/skill/docs/api/batch-operations.md +6 -2
  14. package/dist/skill/docs/api/crud.md +72 -9
  15. package/dist/skill/docs/api/errors.md +78 -6
  16. package/dist/skill/docs/api/openapi.md +1 -1
  17. package/dist/skill/docs/api/query-params.md +6 -7
  18. package/dist/skill/docs/api/typescript.md +193 -0
  19. package/dist/skill/docs/configure/index.md +36 -2
  20. package/dist/skill/docs/configure/providers.md +32 -7
  21. package/dist/skill/docs/define/changesets.md +2 -0
  22. package/dist/skill/docs/define/guards.md +7 -2
  23. package/dist/skill/docs/define/masking.md +14 -0
  24. package/dist/skill/docs/define/read.md +3 -0
  25. package/dist/skill/docs/define/schema.md +13 -10
  26. package/dist/skill/docs/define/transitions.md +9 -4
  27. package/dist/skill/docs/index.md +1 -0
  28. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  29. package/dist/skill/docs/platform/payments/index.md +1 -1
  30. package/dist/skill/docs/start/frontend.md +278 -0
  31. package/dist/skill/docs/start/index.md +1 -0
  32. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  33. package/dist/skill/docs/tooling/output.md +38 -9
  34. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  35. package/dist/skill/docs/ui/admin/actions.md +6 -2
  36. package/dist/skill/docs/ui/admin/index.md +1 -1
  37. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  38. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  39. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  40. package/dist/skill/docs/ui/admin/security.md +2 -2
  41. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  42. package/dist/skill/docs/ui/components/auth.md +90 -0
  43. package/dist/skill/docs/ui/components/index.md +48 -0
  44. package/dist/skill/docs/ui/components/install.md +118 -0
  45. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  46. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  47. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  48. package/package.json +1 -1
  49. package/src/skill/docs/api/actions.md +13 -6
  50. package/src/skill/docs/api/batch-operations.md +6 -2
  51. package/src/skill/docs/api/crud.md +72 -9
  52. package/src/skill/docs/api/errors.md +78 -6
  53. package/src/skill/docs/api/openapi.md +1 -1
  54. package/src/skill/docs/api/query-params.md +6 -7
  55. package/src/skill/docs/api/typescript.md +193 -0
  56. package/src/skill/docs/configure/index.md +36 -2
  57. package/src/skill/docs/configure/providers.md +32 -7
  58. package/src/skill/docs/define/changesets.md +2 -0
  59. package/src/skill/docs/define/guards.md +7 -2
  60. package/src/skill/docs/define/masking.md +14 -0
  61. package/src/skill/docs/define/read.md +3 -0
  62. package/src/skill/docs/define/schema.md +13 -10
  63. package/src/skill/docs/define/transitions.md +9 -4
  64. package/src/skill/docs/index.md +1 -0
  65. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  66. package/src/skill/docs/platform/payments/index.md +1 -1
  67. package/src/skill/docs/start/frontend.md +278 -0
  68. package/src/skill/docs/start/index.md +1 -0
  69. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  70. package/src/skill/docs/tooling/output.md +38 -9
  71. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  72. package/src/skill/docs/ui/admin/actions.md +6 -2
  73. package/src/skill/docs/ui/admin/index.md +1 -1
  74. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  75. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  76. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  77. package/src/skill/docs/ui/admin/security.md +2 -2
  78. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  79. package/src/skill/docs/ui/components/auth.md +90 -0
  80. package/src/skill/docs/ui/components/index.md +48 -0
  81. package/src/skill/docs/ui/components/install.md +118 -0
  82. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  83. package/src/skill/docs/ui/components/resource-form.md +80 -0
  84. 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
 
@@ -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.
@@ -107,6 +107,33 @@ Quickback now adds a D1-specific safety pass around Drizzle-generated migrations
107
107
 
108
108
  If `quickback build` now fails with a D1 replay error, treat that as a real migration problem instead of a deploy-time surprise. The generated SQL needs manual intervention or a schema change that Drizzle can express more safely.
109
109
 
110
+ ### Recompile changed the comments at the top of an old migration
111
+
112
+ A recompile hands every existing migration back byte-for-byte, including the
113
+ generated header comment in whatever wording it was first stamped with
114
+ (`quickback compile` or `quickback build`). Earlier compilers did not:
115
+
116
+ - a header stamped as `quickback compile` was restamped as `quickback build`;
117
+ - the compiler's own comment banner directly under the header — on the
118
+ Postgres RLS migration (`NNNN_quickback_rls_*.sql`) and the table-triggers
119
+ migration (`NNNN_quickback_triggers_*.sql`) — was deleted, and a later
120
+ recompile deleted the comment block after it too.
121
+
122
+ Only comments changed; no SQL statement was touched. What that means depends
123
+ on how you deploy:
124
+
125
+ - **Browser deploys (Cloudflare connection).** The deploy ledger hashes each
126
+ applied migration, so the rewritten file refused the redeploy with
127
+ `migration "…" already ran against this database with different content`.
128
+ Nothing was applied. Redeploy — Start keeps the bytes that were actually
129
+ applied, and the compiler now returns them unchanged.
130
+ - **`quickback deploy`, `wrangler d1 migrations apply`, `npm run db:migrate`.**
131
+ These record migrations by name or timestamp, not content, so nothing was
132
+ refused and the database is unaffected. Leave the file as it is on disk:
133
+ whatever shape it has now stays stable across recompiles. If you want the
134
+ original comments back, restore the file from git — it is a comment-only
135
+ change.
136
+
110
137
  ## Runtime Issues
111
138
 
112
139
  ### 401 on all requests
@@ -154,6 +181,46 @@ grep -r "missingExportName" quickback/.archives/src-2026-04-27T16-31-02-014/
154
181
 
155
182
  Anything in `src/` not produced by the latest compile is removed on every compile — see [CLI → Compile Definitions](/tooling/cli#compile-definitions) for the full contract.
156
183
 
184
+ ## Data Issues
185
+
186
+ Every compile that has something to check emits `reports/data-remediation.sql` in the project root. It is **read-only as emitted**: every statement is a `SELECT`, the repair `UPDATE`s are commented out, and neither the compiler nor the CLI ever runs it. Run it deliberately, read the results, then decide.
187
+
188
+ On D1, pass the file to `--command` so the results print (run it from the project root; `DB` is the features database binding — the report's header names yours):
189
+
190
+ ```bash
191
+ npx wrangler d1 execute DB --remote --command "$(cat reports/data-remediation.sql)"
192
+ # the wrangler dev database instead:
193
+ npx wrangler d1 execute DB --local --command "$(cat reports/data-remediation.sql)"
194
+ ```
195
+
196
+ Don't use `--file` with `--remote` here: that path is D1's bulk import, which takes the database offline while it runs and prints no result rows. On Postgres: `psql "$DATABASE_URL" -f reports/data-remediation.sql`.
197
+
198
+ ### Timestamps read 1970-01-01 (SQLite / D1)
199
+
200
+ From compiler v0.33.2 (2026-05-21) until the fix, a Drizzle insert on SQLite / D1 that omitted a timestamp column persisted `1970-01-01T00:00:00.000Z` instead of the insert time. The column carries that constant as its DDL default so `ALTER TABLE ADD COLUMN` works, and Drizzle preferred it over the column's `$defaultFn`. Affected:
201
+
202
+ - **Every `.defaultNow()` column** (q or raw Drizzle), on every insert that omitted it — including ordinary `POST` / batch / upsert requests.
203
+ - **`createdAt` / `modifiedAt`**, only on inserts that did not go through the request `db` — queue and cron handlers' `db`, `createDb()` handles, and your own Drizzle instances. Requests and actions stamp both explicitly, so their rows are correct.
204
+
205
+ Postgres is not affected: `.defaultNow()` there is a real `DEFAULT now()`.
206
+
207
+ Recompiling fixes new writes. Existing rows keep the epoch — the real times were never recorded, so nothing can recover them. The report counts sentinel rows per column. Where the table also has a trustworthy `created_at`, it carries a commented repair like:
208
+
209
+ ```sql
210
+ -- UPDATE "applications" SET "applied_at" = "created_at" WHERE "applied_at" = '1970-01-01T00:00:00.000Z' AND "created_at" <> '1970-01-01T00:00:00.000Z';
211
+ ```
212
+
213
+ > The repair is an **approximation**: it writes the row's creation time, not the value the column should have held. That is right for "created" or "applied" style columns written at insert, and wrong for anything that means something else. Run a repair only for columns where that trade is acceptable. Take a backup first (`npx wrangler d1 export <features-database-name> --remote --output backup.sql` — the `database_name` of the `DB` binding in `wrangler.toml`), then run the one statement, uncommented, with `--command`. `created_at` itself has no proxy on the row; the report says so instead of offering a repair.
214
+
215
+
216
+ Raw SQL still reaches the DDL default. If you insert with ``db.run(sql`INSERT …`)``, set the timestamp columns yourself.
217
+
218
+ ### Stored `javascript:` / `data:` URLs
219
+
220
+ Until the fix, `q.url()` accepted any scheme the WHATWG URL parser does, including `javascript:` and `data:`. A UI that renders such a value as a link is a stored-XSS hole. `q.url()` now accepts only absolute `http(s)` URLs. The bundled CMS never renders url values as links, and the Account consent page links only `http(s)` values.
221
+
222
+ For each `q.url()` column, the report lists the rows whose value is not `http(s)`. There is no automatic repair. Fix, clear, or delete each row yourself. Until you have, make sure your own UI only links `http(s)` values — for example, check `new URL(value).protocol`.
223
+
157
224
  ## See Also
158
225
 
159
226
  - [Cloud Compiler Troubleshooting](/tooling/cloud-compiler/troubleshooting) — CLI and authentication issues
@@ -59,12 +59,16 @@ Clicking an action opens a modal dialog with:
59
59
 
60
60
  The dialog generates the appropriate input control for each field:
61
61
 
62
- | Zod Type | Input Control | Notes |
62
+ | `inputFields[].type` | Input Control | Notes |
63
63
  |----------|--------------|-------|
64
64
  | `string` | Text input or FK typeahead | Free text unless the field resolves to an emitted `fkTarget` |
65
65
  | `number` | Number input | Step 0.01, supports decimals |
66
66
  | `boolean` | Checkbox | With label text |
67
- | `array<string>` | Text input | Comma-separated values, split on save |
67
+ | `enum` | Text input | The allowed values are in `inputFields[].enum` |
68
+ | `array<…>` | Text input | Comma-separated values, split on save |
69
+
70
+ The types come from the action's input JSON Schema — see
71
+ [ActionInputField](/ui/admin/schema-format#actioninputfield).
68
72
 
69
73
  Required fields are marked with a red asterisk. Default values from the schema are pre-filled.
70
74
 
@@ -201,7 +201,7 @@ That is a deliberate trade: the old gate answered a wrong-role caller with a `30
201
201
 
202
202
  The gates that carry real data:
203
203
 
204
- 1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
204
+ 1. **`/api/v1/schema`** — the metadata endpoint. Admits `sysadmin`, plus any caller with a membership when `access: "member"`. Otherwise `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement (`401 AUTH_MISSING` when not signed in). Without the registry there is no CMS.
205
205
  2. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, org membership *or* sysadmin in `"member"` mode.
206
206
  3. **Account UI link** — the profile CMS action is hidden for callers who wouldn't get in. For admitted members it activates the selected organization before opening the CMS.
207
207
 
@@ -137,11 +137,15 @@ The CMS generates create and edit forms from the table's guard configuration:
137
137
 
138
138
  ### Create Form
139
139
 
140
- Shows all fields listed in `guards.createable`. Required fields (notNull without a default) are marked with a red asterisk. Validation rules from the schema (min/max length, enum constraints, email format) are enforced client-side.
140
+ Shows all fields listed in the registry's `guards.createable`, which is the
141
+ compiler-resolved set `POST` accepts. That set is populated even when the
142
+ table declares no `guards`. Required fields (notNull without a default) are marked with a red asterisk. Validation rules from the schema (min/max length, enum constraints, email format) are enforced client-side.
141
143
 
142
144
  ### Edit Form
143
145
 
144
- Shows all fields listed in `guards.updatable`. Additionally:
146
+ Shows all fields listed in the registry's `guards.updatable` (the resolved set
147
+ `PATCH` accepts). Only fields you changed are sent, so an untouched value that
148
+ was read back masked is never written over the real one. Additionally:
145
149
 
146
150
  - **Immutable fields** appear as disabled inputs with a lock icon
147
151
  - **Protected fields** appear as disabled inputs with the note "Updated via actions only"