@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
|
@@ -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.
|
|
@@ -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
|
-
|
|
|
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
|
-
| `
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
191
|
-
| `updatable` | Fields
|
|
192
|
-
| `immutable` |
|
|
193
|
-
| `protected` |
|
|
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` |
|
|
281
|
-
| `type` |
|
|
282
|
-
| `required` |
|
|
283
|
-
| `default` |
|
|
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
|
-
##
|
|
318
|
+
## ViewMeta
|
|
286
319
|
|
|
287
320
|
Named column projection with access control:
|
|
288
321
|
|
|
289
322
|
```typescript
|
|
290
|
-
interface
|
|
323
|
+
interface ViewMeta {
|
|
291
324
|
fields: string[];
|
|
292
325
|
access: AccessRule;
|
|
293
|
-
query
|
|
294
|
-
filterable
|
|
295
|
-
searchable
|
|
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` |
|
|
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***@
|
|
365
|
-
| `phone` | `
|
|
366
|
-
| `ssn` | `123-45-6789` |
|
|
367
|
-
| `redact` |
|
|
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,
|
|
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
|
-
|
|
416
|
+
enum?: string[];
|
|
376
417
|
maxLength?: number;
|
|
418
|
+
minLength?: number;
|
|
377
419
|
min?: number;
|
|
378
420
|
max?: number;
|
|
379
|
-
|
|
380
|
-
|
|
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
|
|
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[]; //
|
|
68
|
-
updatable: string[]; //
|
|
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,
|
|
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
|
|
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
|
|
91
|
-
searchable
|
|
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
|
-
|
|
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`.
|