@quickback-dev/cli 0.66.20 → 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 (102) hide show
  1. package/dist/commands/migrate.js +2 -2
  2. package/dist/commands/migrate.js.map +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  5. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  6. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  7. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  8. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  9. package/dist/lib/migrations/file-envelopes.js +21 -51
  10. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  11. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  12. package/dist/lib/migrations/prompt-runner.js +6 -1
  13. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  14. package/dist/skill/docs/api/actions.md +13 -6
  15. package/dist/skill/docs/api/batch-operations.md +6 -2
  16. package/dist/skill/docs/api/crud.md +72 -9
  17. package/dist/skill/docs/api/errors.md +86 -6
  18. package/dist/skill/docs/api/openapi.md +1 -1
  19. package/dist/skill/docs/api/query-params.md +8 -7
  20. package/dist/skill/docs/api/typescript.md +196 -0
  21. package/dist/skill/docs/configure/index.md +36 -2
  22. package/dist/skill/docs/configure/providers.md +37 -9
  23. package/dist/skill/docs/define/actions/defining.md +16 -7
  24. package/dist/skill/docs/define/actions/record-and-standalone.md +10 -0
  25. package/dist/skill/docs/define/actions/scoped-db.md +18 -3
  26. package/dist/skill/docs/define/changesets.md +2 -0
  27. package/dist/skill/docs/define/firewall.md +39 -0
  28. package/dist/skill/docs/define/guards.md +7 -2
  29. package/dist/skill/docs/define/masking.md +14 -0
  30. package/dist/skill/docs/define/read.md +3 -0
  31. package/dist/skill/docs/define/relationships.md +9 -0
  32. package/dist/skill/docs/define/schema.md +14 -10
  33. package/dist/skill/docs/define/transitions.md +12 -5
  34. package/dist/skill/docs/define/triggers.md +2 -1
  35. package/dist/skill/docs/index.md +1 -0
  36. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  37. package/dist/skill/docs/platform/database/neon.md +110 -30
  38. package/dist/skill/docs/platform/payments/index.md +1 -1
  39. package/dist/skill/docs/start/frontend.md +278 -0
  40. package/dist/skill/docs/start/index.md +1 -0
  41. package/dist/skill/docs/tooling/cli.md +28 -7
  42. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  43. package/dist/skill/docs/tooling/output.md +42 -11
  44. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  45. package/dist/skill/docs/ui/admin/actions.md +6 -2
  46. package/dist/skill/docs/ui/admin/index.md +1 -1
  47. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  48. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  49. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  50. package/dist/skill/docs/ui/admin/security.md +2 -2
  51. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  52. package/dist/skill/docs/ui/components/auth.md +90 -0
  53. package/dist/skill/docs/ui/components/index.md +48 -0
  54. package/dist/skill/docs/ui/components/install.md +118 -0
  55. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  56. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  57. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  58. package/package.json +1 -1
  59. package/src/skill/docs/api/actions.md +13 -6
  60. package/src/skill/docs/api/batch-operations.md +6 -2
  61. package/src/skill/docs/api/crud.md +72 -9
  62. package/src/skill/docs/api/errors.md +86 -6
  63. package/src/skill/docs/api/openapi.md +1 -1
  64. package/src/skill/docs/api/query-params.md +8 -7
  65. package/src/skill/docs/api/typescript.md +196 -0
  66. package/src/skill/docs/configure/index.md +36 -2
  67. package/src/skill/docs/configure/providers.md +37 -9
  68. package/src/skill/docs/define/actions/defining.md +16 -7
  69. package/src/skill/docs/define/actions/record-and-standalone.md +10 -0
  70. package/src/skill/docs/define/actions/scoped-db.md +18 -3
  71. package/src/skill/docs/define/changesets.md +2 -0
  72. package/src/skill/docs/define/firewall.md +39 -0
  73. package/src/skill/docs/define/guards.md +7 -2
  74. package/src/skill/docs/define/masking.md +14 -0
  75. package/src/skill/docs/define/read.md +3 -0
  76. package/src/skill/docs/define/relationships.md +9 -0
  77. package/src/skill/docs/define/schema.md +14 -10
  78. package/src/skill/docs/define/transitions.md +12 -5
  79. package/src/skill/docs/define/triggers.md +2 -1
  80. package/src/skill/docs/index.md +1 -0
  81. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  82. package/src/skill/docs/platform/database/neon.md +110 -30
  83. package/src/skill/docs/platform/payments/index.md +1 -1
  84. package/src/skill/docs/start/frontend.md +278 -0
  85. package/src/skill/docs/start/index.md +1 -0
  86. package/src/skill/docs/tooling/cli.md +28 -7
  87. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  88. package/src/skill/docs/tooling/output.md +42 -11
  89. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  90. package/src/skill/docs/ui/admin/actions.md +6 -2
  91. package/src/skill/docs/ui/admin/index.md +1 -1
  92. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  93. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  94. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  95. package/src/skill/docs/ui/admin/security.md +2 -2
  96. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  97. package/src/skill/docs/ui/components/auth.md +90 -0
  98. package/src/skill/docs/ui/components/index.md +48 -0
  99. package/src/skill/docs/ui/components/install.md +118 -0
  100. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  101. package/src/skill/docs/ui/components/resource-form.md +80 -0
  102. package/src/skill/docs/ui/components/resource-table.md +46 -0
@@ -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"
@@ -2,6 +2,13 @@
2
2
 
3
3
  The schema registry is a JSON file with a well-defined structure. Below are the complete TypeScript type definitions used by both the compiler (to generate) and the CMS (to consume).
4
4
 
5
+ The compiler's own definitions are emitted verbatim into
6
+ [`quickback.client.ts`](/api/typescript#fetch-client) as `SchemaRegistry`,
7
+ `TableMeta`, `ViewMeta`, `ValidationRule`, `ActionInputField` and friends —
8
+ import them from there rather than re-declaring them. Where the emitted type is
9
+ looser than the one shown here (`Record<string, unknown>` for `crud`,
10
+ `masking`, `firewall`), the shape below is what the CMS relies on.
11
+
5
12
  ## SchemaRegistry
6
13
 
7
14
  The top-level type:
@@ -42,6 +49,7 @@ Full metadata for a single table:
42
49
  interface TableMeta {
43
50
  name: string;
44
51
  dbName: string;
52
+ apiPath: string;
45
53
  feature: string;
46
54
  columns: ColumnMeta[];
47
55
  firewall: Record<string, unknown>;
@@ -52,7 +60,7 @@ interface TableMeta {
52
60
  upsert?: WriteOperationConfig | false;
53
61
  guards: GuardsConfig;
54
62
  masking: Record<string, MaskingRule>;
55
- views: Record<string, ViewConfig>;
63
+ views: Record<string, ViewMeta>;
56
64
  defaultView?: string;
57
65
  requiresExplicitView?: true;
58
66
  validation: Record<string, ValidationRule>;
@@ -65,6 +73,7 @@ interface TableMeta {
65
73
  ownsRelations?: Record<string, OwnsRelation>;
66
74
  ownedBy?: string;
67
75
  readInclude?: string[];
76
+ emitsAfterCommit?: boolean;
68
77
  routesDisabled?: string[];
69
78
  }
70
79
 
@@ -79,8 +88,9 @@ interface OwnsRelation {
79
88
 
80
89
  | Field | Description |
81
90
  |-------|-------------|
82
- | `name` | camelCase table name (e.g., `"accountCode"`) |
91
+ | `name` | camelCase table name (e.g., `"accountCode"`) — the key in `tables`, and in the client's `resources` |
83
92
  | `dbName` | Snake_case SQL table name (e.g., `"account_code"`) |
93
+ | `apiPath` | Kebab-case URL segment (e.g., `"account-code"`) |
84
94
  | `feature` | Parent feature name (e.g., `"accounting"`) |
85
95
  | `columns` | Ordered array of column metadata |
86
96
  | `firewall` | Tenant isolation config (organization, owner, softDelete, exception) |
@@ -101,6 +111,7 @@ interface OwnsRelation {
101
111
  | `ownsRelations` | The [`owns`](/define/changesets) config verbatim — the CMS renders these as inline [owned-records sections](/ui/admin/owned-records) on the root's record page |
102
112
  | `ownedBy` | Set on owned children: the aggregate-root table that owns this table |
103
113
  | `readInclude` | The `read.include` allowlist — tokens fetchable via `?include=` |
114
+ | `emitsAfterCommit` | The aggregate root emits one CloudEvent after each changeset commit |
104
115
  | `routesDisabled` | Ops declared `routes: false` — access exists (changeset admission) but no raw HTTP route, so the CMS suppresses New/Edit/Delete buttons and inline editing for them |
105
116
 
106
117
  ## ColumnMeta
@@ -174,7 +185,12 @@ interface AccessRule {
174
185
 
175
186
  ## GuardsConfig
176
187
 
177
- Field-level control for create and update operations:
188
+ Field-level control for create and update operations. `createable` and
189
+ `updatable` are the **resolved write policy**, not a copy of the table's
190
+ `guards` block: the compiler emits exactly the fields the generated `POST` /
191
+ `PATCH` routes accept — the same set the OpenAPI `<Table>Create` /
192
+ `<Table>Update` request bodies document. They are populated for every
193
+ resourceful table, including tables that declare no `guards`.
178
194
 
179
195
  ```typescript
180
196
  interface GuardsConfig {
@@ -187,10 +203,13 @@ interface GuardsConfig {
187
203
 
188
204
  | Field | Description |
189
205
  |-------|-------------|
190
- | `createable` | Fields that can be set during record creation |
191
- | `updatable` | Fields that can be modified on existing records |
192
- | `immutable` | Fields that can be set on create but never changed |
193
- | `protected` | Fields only modifiable via named actions (field name to action names) |
206
+ | `createable` | Fields `POST` accepts. With `guards`: `createable` plus `immutable`. Without: every column except the primary key. Both then drop audit columns, firewall/scope columns, and `protected` fields. Under `generateId: false` the client-supplied primary key is included; the optional id from `allowClientIds` is not. |
207
+ | `updatable` | Fields `PATCH` accepts. With `guards`: `updatable`. Without: every column except the primary key. Audit, firewall/scope, `immutable`, and `protected` fields are never included. |
208
+ | `immutable` | The declared `guards.immutable` list: set on create, never changed. |
209
+ | `protected` | The declared `guards.protected` map: fields only modifiable via the named actions. |
210
+
211
+ Columns with a default are included, since the route accepts them as optional.
212
+ Order follows `guards` when declared, otherwise column order.
194
213
 
195
214
  ## ActionMeta
196
215
 
@@ -244,9 +263,13 @@ interface CmsConfig {
244
263
 
245
264
  interface ActionInputField {
246
265
  name: string;
247
- type: string;
266
+ type: string; // "string" | "number" | "boolean" | "enum" | "object" | "array<item>" | "unknown"
248
267
  required: boolean;
249
268
  default?: unknown;
269
+ enum?: Array<string | number | boolean>;
270
+ integer?: true;
271
+ nullable?: true;
272
+ description?: string;
250
273
  }
251
274
  ```
252
275
 
@@ -275,33 +298,45 @@ If the action is already unambiguously table-scoped, the compiler can infer plac
275
298
 
276
299
  ### ActionInputField
277
300
 
301
+ One entry per top-level property of the action's input, derived from the
302
+ action's input **JSON Schema** — the same harvested `z.toJSONSchema()` output
303
+ that feeds OpenAPI and `Api.<x>.actions.<name>.Input` (a static parse of the
304
+ Zod source is the fallback when the harvest is unavailable). Enum values,
305
+ defaults and `.describe()` text survive.
306
+
278
307
  | Field | Description |
279
308
  |-------|-------------|
280
- | `name` | Field identifier |
281
- | `type` | Zod type string: `"string"`, `"number"`, `"boolean"`, `"array<string>"` |
282
- | `required` | Whether the field must be provided |
283
- | `default` | Default value pre-filled in the form |
309
+ | `name` | Input property name |
310
+ | `type` | `"string"`, `"number"`, `"boolean"`, `"enum"`, `"object"`, `"array<item>"` (item type inside the brackets) or `"unknown"` |
311
+ | `required` | Listed in the schema's `required` and has no default |
312
+ | `default` | The schema default (`.default(x)`), pre-filled in the form |
313
+ | `enum` | Allowed values — `z.enum`, `z.literal`, or a union of literals |
314
+ | `integer` | `true` for `z.number().int()` (`type` stays `"number"`) |
315
+ | `nullable` | `true` when the field accepts `null` |
316
+ | `description` | The field's `.describe()` text |
284
317
 
285
- ## ViewConfig
318
+ ## ViewMeta
286
319
 
287
320
  Named column projection with access control:
288
321
 
289
322
  ```typescript
290
- interface ViewConfig {
323
+ interface ViewMeta {
291
324
  fields: string[];
292
325
  access: AccessRule;
293
- query?: {
294
- filterable?: string[] | null;
295
- searchable?: string[];
326
+ query: {
327
+ filterable: string[] | null;
328
+ searchable: string[];
296
329
  sortable?: string[];
297
330
  defaultSort?: string;
298
331
  };
332
+ aggregateOnly?: true;
299
333
  }
300
334
  ```
301
335
 
302
336
  | Field | Description |
303
337
  |-------|-------------|
304
- | `fields` | Array of column names to include in this view |
338
+ | `fields` | The columns every row of this view carries, in order — always resolved (the view's projection, else every column; `[]` for an aggregate-only view), so a UI can lay out the view's columns before the first row arrives |
339
+ | `aggregateOnly` | `true` when the view returns only `aggregations`, no rows |
305
340
  | `access` | Effective role-based access: the view override or inherited table `read.access` |
306
341
  | `query` | Effective view query metadata. Explicit named-view allowlists are authoritative. Current registries materialize inherited `searchable` and q-table `filterable` defaults; `searchable: []` disables search, while `filterable: null` preserves raw Drizzle compatibility when no closed allowlist can be derived. |
307
342
 
@@ -361,44 +396,47 @@ interface MaskingRule {
361
396
 
362
397
  | Type | Input | Output |
363
398
  |------|-------|--------|
364
- | `email` | `john@acme.com` | `j***@acme.com` |
365
- | `phone` | `(555) 123-4567` | `***-***-4567` |
366
- | `ssn` | `123-45-6789` | `***-**-6789` |
367
- | `redact` | Any string | `------` |
399
+ | `email` | `john@acme.com` | `j***@a***.com` |
400
+ | `phone` | `555-123-4567` | `******4567` |
401
+ | `ssn` | `123-45-6789` | `*****6789` |
402
+ | `redact` | Anything | `[REDACTED]` |
403
+
404
+ A redacted non-string column (number, boolean, JSON, array) arrives as the
405
+ string `"[REDACTED]"` — see [Masking](/define/masking#non-string-columns).
368
406
 
369
407
  ## ValidationRule
370
408
 
371
- Per-field validation constraints, mirrored from the Zod the API enforces on request bodies so the CMS can render the right control and validate before it POSTs:
409
+ Per-field validation constraints, **read back from the Zod the API enforces**
410
+ on request bodies — the registry never advertises a rule the server doesn't
411
+ check. The CMS uses them to render the right control and validate before it
412
+ POSTs:
372
413
 
373
414
  ```typescript
374
415
  interface ValidationRule {
375
- minLength?: number;
416
+ enum?: string[];
376
417
  maxLength?: number;
418
+ minLength?: number;
377
419
  min?: number;
378
420
  max?: number;
379
- enum?: string[];
380
- email?: boolean;
421
+ integer?: boolean;
422
+ pattern?: string;
381
423
  url?: boolean;
424
+ email?: boolean;
382
425
  }
383
426
  ```
384
427
 
385
428
  | Rule | Emitted from |
386
429
  |------|--------------|
387
430
  | `enum` | `q.enum([...])`, or `text(..., { enum: [...] })` in raw Drizzle — the CMS renders a select |
388
- | `url` | `q.url()` — the CMS renders a `url` input; the API rejects anything `new URL()` can't parse, including `""` |
431
+ | `url` | `q.url()` — the CMS renders a `url` input; the API accepts only absolute `http(s)` URLs (so not `""`, `javascript:` or `data:`) |
389
432
  | `maxLength` | `q.text({ maxLength })` / `q.url({ maxLength })` |
433
+ | `integer` | `q.int()`, `q.bigint()`, `q.smallint()` — whole numbers only |
434
+ | `min` / `max` | `q.bigint()` (±2^53−1, the JSON-safe range) and `q.smallint()` (−32768…32767), inclusive |
435
+ | `pattern` | `q.decimal({ precision, scale })` — the regex source the decimal string must match |
436
+ | `minLength` / `email` | Only when the enforced Zod carries `.min(n)` / `.email()`; no q column kind emits them today |
390
437
 
391
438
  Columns with no constraints have no entry. Optional fields left blank in the CMS form are omitted from the request body rather than sent as `""` — the API accepts an optional field being absent, not empty.
392
439
 
393
- | Field | Description |
394
- |-------|-------------|
395
- | `minLength` | Minimum string length |
396
- | `maxLength` | Maximum string length |
397
- | `min` | Minimum numeric value |
398
- | `max` | Maximum numeric value |
399
- | `enum` | Array of allowed string values |
400
- | `email` | When `true`, validates email format |
401
-
402
440
  ## PageMeta
403
441
 
404
442
  Full metadata for a custom page:
@@ -15,6 +15,17 @@ export default defineConfig({
15
15
  });
16
16
  ```
17
17
 
18
+ ## Serving and access
19
+
20
+ The registry is served, auth-gated, at `GET /api/v1/schema` — never bundled
21
+ into a frontend. The CMS loads it there; so does
22
+ [`api.schema()`](/api/typescript#fetch-client) in the generated fetch client,
23
+ which types the response as the compiler's own `SchemaRegistry`. The route
24
+ admits platform sysadmins by default; `cms.access: "member"` or, for a
25
+ frontend without the CMS,
26
+ [`schemaRegistry.access`](/configure#schema-registry-access) (`"member"` or
27
+ `"authenticated"`) opens it to your users.
28
+
18
29
  ## Output Shape
19
30
 
20
31
  The top-level structure of `schema-registry.json`:
@@ -64,13 +75,13 @@ interface TableMeta {
64
75
  delete?: WriteOperationConfig | false; // Flat delete config
65
76
  upsert?: WriteOperationConfig | false; // Flat upsert config
66
77
  guards: {
67
- createable: string[]; // Fields allowed on create
68
- updatable: string[]; // Fields allowed on update
78
+ createable: string[]; // Resolved: exactly what POST accepts (set even without `guards`)
79
+ updatable: string[]; // Resolved: exactly what PATCH accepts
69
80
  immutable: string[]; // Fields locked after creation
70
81
  protected: Record<string, string[]>; // Fields writable only via named actions/transitions
71
82
  };
72
83
  masking: Record<string, MaskingRule>; // Per-field masking rules
73
- views: Record<string, ViewConfig>; // Named column projections
84
+ views: Record<string, ViewMeta>; // Named column projections
74
85
  defaultView?: string; // Authored read.defaultView
75
86
  requiresExplicitView?: true; // Named views exist with no default
76
87
  validation: Record<string, ValidationRule>; // Per-field validation
@@ -83,19 +94,21 @@ interface TableMeta {
83
94
  Each named view carries the effective read contract the CMS consumes:
84
95
 
85
96
  ```typescript
86
- interface ViewConfig {
87
- fields: string[];
97
+ interface ViewMeta {
98
+ fields: string[]; // always resolved: the projection, else every column; [] if aggregate-only
88
99
  access: AccessRule;
89
- query?: {
90
- filterable?: string[] | null;
91
- searchable?: string[];
100
+ query: {
101
+ filterable: string[] | null;
102
+ searchable: string[];
92
103
  sortable?: string[];
93
104
  defaultSort?: string;
94
105
  };
106
+ aggregateOnly?: true;
95
107
  }
96
108
  ```
97
109
 
98
- For current registries, `access` is the view's explicit access rule or the
110
+ `fields` is always the resolved column list, so a table can render a view's
111
+ header before its first row arrives. For current registries, `access` is the view's explicit access rule or the
99
112
  inherited table `read.access` when the view omits an override.
100
113
  `query.searchable` is likewise the effective search allowlist: the explicit
101
114
  view list when present, otherwise the compiler's eligible table search fields
@@ -13,7 +13,7 @@ cms: { access: "member" }
13
13
  The shell is served to any signed-in caller so the SPA can explain who is and isn't admitted; the gates that carry data are:
14
14
 
15
15
  1. **Account UI** — the profile CMS action is hidden for callers who wouldn't get in; admitted members select and activate an organization before navigation.
16
- 2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement. Without the registry there is no CMS.
16
+ 2. **`/api/v1/schema`** — the metadata endpoint returns `403` with `CMS_ACCESS_DENIED` and a hint naming the requirement to a signed-in caller without the role, and `401 AUTH_MISSING` to an anonymous one. Without the registry there is no CMS.
17
17
  3. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, or organization membership plus sysadmin in `"member"` mode.
18
18
  4. **In-SPA gate** — the SPA renders the matching blocked, membership-picker, or sysadmin-scope screen before loading CMS data.
19
19
 
@@ -66,7 +66,7 @@ The row action menu also adapts — Edit and Delete entries only appear when the
66
66
 
67
67
  ## Guards
68
68
 
69
- Guards control which fields appear in create and edit forms, and which cells are editable in Data Table mode.
69
+ Guards control which fields appear in create and edit forms, and which cells are editable in Data Table mode. The registry's `createable` / `updatable` lists are the compiler-resolved write policy, the exact fields the API accepts. A table without `guards` still gets full forms with every column except system and scope columns.
70
70
 
71
71
  ### Createable Fields
72
72
 
@@ -0,0 +1,62 @@
1
+ # action-dialog
2
+
3
+ ```bash
4
+ npx shadcn add @quickback/action-dialog
5
+ ```
6
+
7
+ ```tsx
8
+ import { useState } from "react"
9
+ import { buttonVariants } from "@/components/ui/button"
10
+ import { ActionDialog } from "@/components/action-dialog"
11
+
12
+ function CloseJobButton({ id }: { id: string }) {
13
+ const [open, setOpen] = useState(false)
14
+ return (
15
+ <>
16
+ <button type="button" className={buttonVariants({ variant: "outline" })} onClick={() => setOpen(true)}>
17
+ Close
18
+ </button>
19
+ <ActionDialog table="jobs" action="close" id={id} open={open} onOpenChange={setOpen} />
20
+ </>
21
+ )
22
+ }
23
+ ```
24
+
25
+ The dialog is **controlled**. You own `open` and render your own trigger. It
26
+ ships no trigger, so it never needs base-ui's `render=` or Radix's `asChild`.
27
+
28
+ ## Props
29
+
30
+ | Prop | Type | Description |
31
+ |---|---|---|
32
+ | `table` | `string` | Schema-registry table name. Required. |
33
+ | `action` | `string` | Action name as declared on the table. Required. |
34
+ | `id` | `string` | Record id. Required for [record-bound actions](/define/actions/record-and-standalone). Leave it out for standalone ones. |
35
+ | `params` | `Record<string, string>` | Path parameters for standalone actions whose `path` has them. |
36
+ | `open` | `boolean` | Required. |
37
+ | `onOpenChange` | `(open: boolean) => void` | Required. |
38
+ | `onSuccess` | `(output: unknown) => void` | Called with the action's output. |
39
+
40
+ ## Behavior
41
+
42
+ - **Inputs** come from the action's `inputFields` in the schema registry.
43
+ Enums render as selects, booleans as checkboxes, and numbers as number
44
+ inputs. Everything else renders as text. Array inputs take a
45
+ comma-separated list. Empty fields are left out of the input.
46
+ - **Title and description** come from the action's `cms.label` (else its
47
+ name) and its `description`.
48
+ - **Confirmation.** An action with [`cms.destructive`](/ui/admin/actions)
49
+ or `cms.confirm` asks before it runs. A string `confirm` is the message.
50
+ Otherwise the dialog asks `<Action> can't be undone. Continue?`
51
+ (destructive) or `Run <Action>?`. `confirm: false` never asks.
52
+ - **Access.** When the caller's [roles](/ui/components/quickback-provider#roles)
53
+ plainly fail the action's `access.roles`, the dialog shows
54
+ `Your role can't run <Action>.` instead of the form.
55
+ - **On success**, the dialog shows "Done." and the output as JSON. Every
56
+ cached query for the table is invalidated, so an open `ResourceTable`
57
+ refreshes.
58
+ - **On error**, the problem's `detail` shows at the top. Per-field messages
59
+ show under their inputs. Guard rejections, access denials (`403`), and
60
+ failed record preconditions all arrive this way.
61
+ - An unknown `action` shows `"<name>" is not an action on <Table>.` Calling a record-bound
62
+ action without `id` fails with `Action "<name>" on "<table>" needs a record id`.
@@ -0,0 +1,90 @@
1
+ # Auth
2
+
3
+ The components never touch credentials. The emitted client you pass to
4
+ `<QuickbackProvider client>` decides how each request is authenticated.
5
+
6
+ | Mode | Use it for | Credential | Writes need |
7
+ |---|---|---|---|
8
+ | `auth: "cookie"` (default) | Browser apps | Better Auth session cookie, `credentials: "include"` | The page's origin in the trusted origins |
9
+ | `auth: "bearer"` | React Native, CLIs, servers | `Authorization: Bearer <token>` | Nothing extra. Bearer requests skip the CSRF origin check. |
10
+
11
+ ## Browser: cookie
12
+
13
+ Sign in with Better Auth's own client. The session cookie it sets is what the
14
+ Quickback client sends.
15
+
16
+ ```tsx
17
+ import { createAuthClient } from "better-auth/react"
18
+ import { organizationClient } from "better-auth/client/plugins"
19
+ import { createClient } from "@/lib/quickback.client"
20
+
21
+ const baseURL = import.meta.env.VITE_API_URL // e.g. http://localhost:8787
22
+
23
+ export const auth = createAuthClient({
24
+ baseURL,
25
+ basePath: "/auth/v1",
26
+ plugins: [organizationClient()],
27
+ })
28
+
29
+ export const client = createClient({ baseUrl: baseURL })
30
+
31
+ await auth.signIn.email({ email, password })
32
+ // Tenant-scoped tables are firewalled to the session's active organization.
33
+ await auth.organization.setActive({ organizationId })
34
+ ```
35
+
36
+ The cookie only works if the API trusts your page's origin:
37
+
38
+ - **Same Worker (recommended).** Mount the built app with
39
+ [`apps.<name>`](/configure/domains#app-domains). It is then served on the
40
+ same origin as `/api` and `/auth`, and its hostname is trusted
41
+ automatically.
42
+ - **Local dev.** Until a project has a production domain, `http://localhost:5173`
43
+ (Vite), `:3000`, and `:8787` are trusted by default.
44
+ - **Anywhere else.** Add the origin to
45
+ [`trustedOrigins`](/configure#trusted-origins). A write from an untrusted
46
+ origin fails with `403 CSRF_ORIGIN_REJECTED`, and the browser blocks reads
47
+ through CORS.
48
+
49
+ ## React Native and other non-browser clients: bearer
50
+
51
+ React Native has no cookie jar and sends no `Origin` header. Cookie-backed
52
+ writes therefore fail with `403 CSRF_ORIGIN_REJECTED`. Use the bearer lane
53
+ instead:
54
+
55
+ ```tsx
56
+ import * as SecureStore from "expo-secure-store"
57
+ import { createClient } from "@/lib/quickback.client"
58
+
59
+ const KEY = "quickback_session"
60
+
61
+ export const client = createClient({
62
+ baseUrl: "https://api.example.com",
63
+ auth: "bearer",
64
+ sessionStore: {
65
+ get: () => SecureStore.getItemAsync(KEY),
66
+ set: (token) => (token ? SecureStore.setItemAsync(KEY, token) : SecureStore.deleteItemAsync(KEY)),
67
+ },
68
+ })
69
+
70
+ // set-auth-token on /auth/v1/* is saved to sessionStore.
71
+ await client.request("POST", "/auth/v1/sign-in/email", { body: { email, password } })
72
+ await client.request("POST", "/auth/v1/organization/set-active", { body: { organizationId } })
73
+ ```
74
+
75
+ Sign in **through the client**, as above. It saves the `set-auth-token`
76
+ **header**: the signed `<token>.<signature>`. If you sign in with your own
77
+ `fetch`, store that header too, never the body's `token`. The body carries
78
+ the raw session id, and the generated API runs Better Auth's
79
+ `bearer({ requireSignature: true })`. An unsigned token is silently ignored:
80
+ `get-session` returns `null` and every API call answers `401`.
81
+
82
+ With `auth: "bearer"`, the client:
83
+
84
+ - sends `Authorization: Bearer <token>` and defaults `credentials` to `"omit"`;
85
+ - caches the short-lived JWT that API responses return in `set-auth-token`
86
+ (see [JWT optimization](/platform/auth/jwt-optimization));
87
+ - on a `401` with a cached JWT, drops the JWT and retries once with the
88
+ session token from `sessionStore`.
89
+
90
+ Full lane semantics: [Bearer lane](/api/typescript#bearer-lane-react-native-native-clients).
@@ -0,0 +1,48 @@
1
+ # Components
2
+
3
+ Add tables, forms, and action dialogs for your API to your own React app with
4
+ `shadcn add`. There's no fork of the CMS and no admin framework involved. Each
5
+ component is a file in your repo, and you edit it like any other code.
6
+
7
+ ```bash
8
+ npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
9
+ ```
10
+
11
+ ## Two layers
12
+
13
+ | Layer | Who owns it | Regenerated? | Knows the wire format? |
14
+ |---|---|---|---|
15
+ | `quickback.client.ts` | The compiler emits it (`client` config) | Every compile | **Yes. Only this file does.** |
16
+ | `quickback-provider`, `resource-table`, `resource-form`, `action-dialog` | You. `shadcn add` copies them into your repo | Never | No |
17
+
18
+ The components never build a URL, unwrap a list envelope, or parse
19
+ `application/problem+json`. They call the emitted
20
+ [fetch client](/api/typescript#fetch-client) and read the
21
+ [schema registry](/ui/admin/schema-registry) for column kinds, guards, and
22
+ action inputs. When the API changes shape, you recompile and only the client
23
+ changes. Your edits to the components survive.
24
+
25
+ ## Base-ui only
26
+
27
+ The items target shadcn's **base-ui** styles (`base-nova`, `base-mira`, …).
28
+ Radix styles are not supported.
29
+
30
+ - They compose your own primitives (`button`, `dialog`, `table`, …) through
31
+ `registryDependencies`, using base-ui's `render=` prop where composition is
32
+ needed.
33
+ - They never use Radix's `asChild`. On a base-ui project, `shadcn add`
34
+ silently rewrites `asChild` to `render={<firstChild />}`. That still
35
+ typechecks but drops the other children.
36
+ - The namespace URL includes the style (`/r/{style}/{name}.json`), and only
37
+ `base-*` paths exist. A Radix project therefore fails at **install**, with a
38
+ `404` that names its style, before any file is written.
39
+
40
+ ## Pages
41
+
42
+ - [Install](/ui/components/install): the `client` config, the `@quickback` namespace, and direct URLs
43
+ - [Auth](/ui/components/auth): cookie vs bearer, React Native
44
+ - [`quickback-provider`](/ui/components/quickback-provider): `<QuickbackProvider>` and the TanStack Query hooks
45
+ - [`resource-table`](/ui/components/resource-table): paginated, sortable, searchable list
46
+ - [`resource-form`](/ui/components/resource-form): create / edit form
47
+ - [`action-dialog`](/ui/components/action-dialog): run an action with its inputs
48
+ - [Build a frontend](/start/frontend): end-to-end guide