@quickback-dev/cli 0.66.1 → 0.66.3

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 (205) hide show
  1. package/README.md +7 -4
  2. package/dist/commands/build.d.ts +51 -0
  3. package/dist/commands/build.d.ts.map +1 -0
  4. package/dist/commands/build.js +804 -0
  5. package/dist/commands/build.js.map +1 -0
  6. package/dist/commands/build.test.d.ts +2 -0
  7. package/dist/commands/build.test.d.ts.map +1 -0
  8. package/dist/commands/build.test.js +150 -0
  9. package/dist/commands/build.test.js.map +1 -0
  10. package/dist/commands/check.d.ts +2 -2
  11. package/dist/commands/check.js +4 -4
  12. package/dist/commands/check.js.map +1 -1
  13. package/dist/commands/create.d.ts +1 -1
  14. package/dist/commands/create.js +7 -7
  15. package/dist/commands/create.js.map +1 -1
  16. package/dist/commands/deploy.d.ts +6 -6
  17. package/dist/commands/deploy.js +23 -23
  18. package/dist/commands/deploy.js.map +1 -1
  19. package/dist/commands/example.js +1 -1
  20. package/dist/commands/example.js.map +1 -1
  21. package/dist/commands/mcp.js +1 -1
  22. package/dist/commands/mcp.js.map +1 -1
  23. package/dist/commands/migrate.d.ts +1 -1
  24. package/dist/commands/migrate.js +3 -3
  25. package/dist/commands/migrate.js.map +1 -1
  26. package/dist/commands/migrations.js +2 -2
  27. package/dist/commands/migrations.js.map +1 -1
  28. package/dist/commands/push.js +1 -1
  29. package/dist/commands/push.js.map +1 -1
  30. package/dist/commands/start.js +1 -1
  31. package/dist/commands/start.js.map +1 -1
  32. package/dist/cursor/quickback.mdc +1 -1
  33. package/dist/index.js +18 -15
  34. package/dist/index.js.map +1 -1
  35. package/dist/lib/auth.js +1 -1
  36. package/dist/lib/auth.js.map +1 -1
  37. package/dist/lib/compiler-floor.d.ts +1 -1
  38. package/dist/lib/compiler-floor.js +1 -1
  39. package/dist/lib/file-loader.js +2 -2
  40. package/dist/lib/file-loader.js.map +1 -1
  41. package/dist/lib/file-writer.d.ts +2 -0
  42. package/dist/lib/file-writer.d.ts.map +1 -1
  43. package/dist/lib/file-writer.js +16 -0
  44. package/dist/lib/file-writer.js.map +1 -1
  45. package/dist/lib/file-writer.test.js +16 -0
  46. package/dist/lib/file-writer.test.js.map +1 -1
  47. package/dist/lib/migrations/file-envelopes.js +3 -3
  48. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  49. package/dist/lib/prepare-output.test.js +1 -1
  50. package/dist/lib/prepare-output.test.js.map +1 -1
  51. package/dist/lib/schema-sync/index.js +1 -1
  52. package/dist/lib/schema-sync/index.test.js +1 -1
  53. package/dist/lib/schema-sync/index.test.js.map +1 -1
  54. package/dist/skill/SKILL.md +6 -6
  55. package/dist/skill/docs/api/actions.md +27 -3
  56. package/dist/skill/docs/api/batch-operations.md +4 -0
  57. package/dist/skill/docs/api/crud.md +64 -0
  58. package/dist/skill/docs/api/index.md +1 -1
  59. package/dist/skill/docs/api/openapi.md +1 -1
  60. package/dist/skill/docs/api/query-params.md +19 -2
  61. package/dist/skill/docs/changelog/index.md +33 -1
  62. package/dist/skill/docs/configure/agents.md +1 -1
  63. package/dist/skill/docs/configure/index.md +8 -3
  64. package/dist/skill/docs/configure/providers.md +3 -0
  65. package/dist/skill/docs/configure/variables.md +3 -3
  66. package/dist/skill/docs/define/access.md +7 -0
  67. package/dist/skill/docs/define/actions/defining.md +39 -8
  68. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  69. package/dist/skill/docs/define/actions/scoped-db.md +46 -16
  70. package/dist/skill/docs/define/areas.md +1 -1
  71. package/dist/skill/docs/define/diagnostics.md +1 -0
  72. package/dist/skill/docs/define/encryption.md +1 -1
  73. package/dist/skill/docs/define/feature.md +14 -7
  74. package/dist/skill/docs/define/guards.md +34 -3
  75. package/dist/skill/docs/define/schema.md +29 -17
  76. package/dist/skill/docs/define/security.md +1 -1
  77. package/dist/skill/docs/define/transitions.md +35 -4
  78. package/dist/skill/docs/define/views.md +33 -0
  79. package/dist/skill/docs/index.md +2 -2
  80. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  81. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  82. package/dist/skill/docs/platform/database/d1.md +2 -2
  83. package/dist/skill/docs/platform/database/neon.md +4 -4
  84. package/dist/skill/docs/platform/email/index.md +1 -1
  85. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  86. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  87. package/dist/skill/docs/platform/schedules/index.md +1 -1
  88. package/dist/skill/docs/platform/storage/index.md +3 -3
  89. package/dist/skill/docs/platform/storage/r2.md +87 -37
  90. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  91. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  92. package/dist/skill/docs/start/deploy-browser.md +39 -44
  93. package/dist/skill/docs/start/deploy-owner-access.md +28 -19
  94. package/dist/skill/docs/start/deploy.md +2 -2
  95. package/dist/skill/docs/start/first-api.md +1 -1
  96. package/dist/skill/docs/start/hand-crafted.md +3 -3
  97. package/dist/skill/docs/start/index.md +3 -3
  98. package/dist/skill/docs/start/quickstart.md +3 -3
  99. package/dist/skill/docs/start/template-blog.md +2 -2
  100. package/dist/skill/docs/start/template-cloudflare.md +2 -2
  101. package/dist/skill/docs/start/template-empty.md +1 -1
  102. package/dist/skill/docs/start/templates.md +1 -1
  103. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  104. package/dist/skill/docs/tooling/cli.md +40 -19
  105. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  106. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  107. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  108. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  109. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  110. package/dist/skill/docs/tooling/output.md +32 -2
  111. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  112. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  113. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  114. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  115. package/dist/skill/docs/ui/account/features/index.md +9 -5
  116. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  117. package/dist/skill/docs/ui/account/index.md +3 -1
  118. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  119. package/dist/skill/docs/ui/admin/actions.md +97 -3
  120. package/dist/skill/docs/ui/admin/components.md +4 -6
  121. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  122. package/dist/skill/docs/ui/admin/index.md +71 -6
  123. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  124. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  125. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  126. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  127. package/dist/skill/docs/ui/admin/security.md +19 -4
  128. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  129. package/package.json +1 -1
  130. package/src/cursor/quickback.mdc +1 -1
  131. package/src/skill/SKILL.md +6 -6
  132. package/src/skill/docs/api/actions.md +27 -3
  133. package/src/skill/docs/api/batch-operations.md +4 -0
  134. package/src/skill/docs/api/crud.md +64 -0
  135. package/src/skill/docs/api/index.md +1 -1
  136. package/src/skill/docs/api/openapi.md +1 -1
  137. package/src/skill/docs/api/query-params.md +19 -2
  138. package/src/skill/docs/changelog/index.md +33 -1
  139. package/src/skill/docs/configure/agents.md +1 -1
  140. package/src/skill/docs/configure/index.md +8 -3
  141. package/src/skill/docs/configure/providers.md +3 -0
  142. package/src/skill/docs/configure/variables.md +3 -3
  143. package/src/skill/docs/define/access.md +7 -0
  144. package/src/skill/docs/define/actions/defining.md +39 -8
  145. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  146. package/src/skill/docs/define/actions/scoped-db.md +46 -16
  147. package/src/skill/docs/define/areas.md +1 -1
  148. package/src/skill/docs/define/diagnostics.md +1 -0
  149. package/src/skill/docs/define/encryption.md +1 -1
  150. package/src/skill/docs/define/feature.md +14 -7
  151. package/src/skill/docs/define/guards.md +34 -3
  152. package/src/skill/docs/define/schema.md +29 -17
  153. package/src/skill/docs/define/security.md +1 -1
  154. package/src/skill/docs/define/transitions.md +35 -4
  155. package/src/skill/docs/define/views.md +33 -0
  156. package/src/skill/docs/index.md +2 -2
  157. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  158. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  159. package/src/skill/docs/platform/database/d1.md +2 -2
  160. package/src/skill/docs/platform/database/neon.md +4 -4
  161. package/src/skill/docs/platform/email/index.md +1 -1
  162. package/src/skill/docs/platform/queues/handlers.md +1 -1
  163. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  164. package/src/skill/docs/platform/schedules/index.md +1 -1
  165. package/src/skill/docs/platform/storage/index.md +3 -3
  166. package/src/skill/docs/platform/storage/r2.md +87 -37
  167. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  168. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  169. package/src/skill/docs/start/deploy-browser.md +39 -44
  170. package/src/skill/docs/start/deploy-owner-access.md +28 -19
  171. package/src/skill/docs/start/deploy.md +2 -2
  172. package/src/skill/docs/start/first-api.md +1 -1
  173. package/src/skill/docs/start/hand-crafted.md +3 -3
  174. package/src/skill/docs/start/index.md +3 -3
  175. package/src/skill/docs/start/quickstart.md +3 -3
  176. package/src/skill/docs/start/template-blog.md +2 -2
  177. package/src/skill/docs/start/template-cloudflare.md +2 -2
  178. package/src/skill/docs/start/template-empty.md +1 -1
  179. package/src/skill/docs/start/templates.md +1 -1
  180. package/src/skill/docs/tooling/claude-skill.md +1 -1
  181. package/src/skill/docs/tooling/cli.md +40 -19
  182. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  183. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  184. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  185. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  186. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  187. package/src/skill/docs/tooling/output.md +32 -2
  188. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  189. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  190. package/src/skill/docs/ui/account/features/admin.md +1 -1
  191. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  192. package/src/skill/docs/ui/account/features/index.md +9 -5
  193. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  194. package/src/skill/docs/ui/account/index.md +3 -1
  195. package/src/skill/docs/ui/account/with-quickback.md +1 -1
  196. package/src/skill/docs/ui/admin/actions.md +97 -3
  197. package/src/skill/docs/ui/admin/components.md +4 -6
  198. package/src/skill/docs/ui/admin/connecting.md +15 -3
  199. package/src/skill/docs/ui/admin/index.md +71 -6
  200. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  201. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  202. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  203. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  204. package/src/skill/docs/ui/admin/security.md +19 -4
  205. package/src/skill/docs/ui/admin/table-views.md +59 -12
@@ -29,9 +29,60 @@ The CMS generates its entire UI from your Quickback definitions. Define a table
29
29
  - **FK typeahead** — Server-side search for foreign key fields with debounced queries and keyboard navigation.
30
30
  - **Field masking** — Email, phone, SSN, and redaction patterns applied per role. Masked fields show a lock icon.
31
31
  - **Custom actions** — Action dialogs with auto-generated input forms, access filtering, CMS metadata (icons, categories, confirmations), and side effects warnings.
32
- - **Views** — Named column-level projections per role. "All Fields" plus custom views in the toolbar.
33
- - **Auto-form generation** — Create and edit forms built from guards (createable/updatable fields).
34
- - **Display column auto-detection** — FK labels resolved automatically from `name`, `title`, `label`, `code`, and other common patterns.
32
+ - **Views** — Named column-level projections per role, with an explicit default projection for CMS table entry.
33
+ - **Auto-form generation** — Create and edit forms built from guards (createable/updatable fields). Inputs follow the column's constraints — `q.enum` renders a select, `q.url` a URL input, `q.text({ maxLength })` a length-capped field — required columns are marked and constraints shown as helper text, untouched optional fields are omitted from the request (cleared ones are sent as `null`), and a `VALIDATION_ERROR` from the API is shown inline under the offending fields.
34
+ - **Human-readable relationships** — FK labels and selectors use the target table's `displayColumn` and an authored schema reference.
35
+
36
+ ## CMS Readiness Review
37
+
38
+ Enabling the CMS makes the definitions visible; it does not invent a safe UI
39
+ workflow. Before compiling a CMS-backed project, review every visible table
40
+ against this checklist:
41
+
42
+ 1. **Collection entry** — A table with no named views can use its ordinary
43
+ collection projection. Once `read.views` contains a named view, there is no
44
+ implicit full-row fallback. Set `read.defaultView` to an accessible named
45
+ view when the CMS must open the table directly. Without it, bare
46
+ `GET /api/v1/<table>` correctly returns `400 VIEW_REQUIRED`; callers must use
47
+ `GET /api/v1/<table>/views/<name>`. The registry marks that intentional
48
+ state with `requiresExplicitView: true`, so the CMS shows **Choose a view**
49
+ and makes no data request until one is selected. It never silently chooses
50
+ the first accessible projection. `defaultSort` only chooses ordering and
51
+ cannot satisfy view selection or fix `VIEW_REQUIRED`.
52
+ 2. **Labels** — Set `displayColumn` on tables used as FK targets or record
53
+ titles. Auto-detection is a convenience, but an explicit value makes the
54
+ intended human label stable.
55
+ 3. **Relationships** — For feature-table foreign keys, declare the relationship
56
+ in the schema with `.references(() => target.id)`. The CMS needs the emitted
57
+ `fkTarget` for selector/typeahead controls. Treat a matching `*Id` sibling
58
+ table name as a compiler diagnostic suggestion, not as proof of a
59
+ relationship. Better Auth ids are the exception: they live in `AUTH_DB` and
60
+ remain plain text, not cross-database FKs. When a target has named views,
61
+ its role-accessible `read.defaultView` must include its primary key and
62
+ `displayColumn`; the CMS lookup uses that named route only. Add the label to
63
+ the view's effective `query.searchable` for typeahead, or it becomes a
64
+ first-50 chooser with no search request.
65
+ 4. **CRUD controls** — **New** requires generated `create` CRUD, admitted
66
+ `create.access`, and all required non-default inputs in
67
+ `guards.createable`. Edit controls require generated `update` CRUD,
68
+ admitted `update.access`, and fields in `guards.updatable`. A protected
69
+ workflow field belongs in neither generic write list. Give it a schema
70
+ default for creation; only its named transitions/actions may write it.
71
+ 5. **Business actions** — A record-bound action needs an existing row. A
72
+ workflow that creates the first row should be a standalone action with
73
+ `path:` and explicit table-toolbar placement, such as
74
+ `cms: { placement: "tables", tables: ["reservations"] }`. Check action
75
+ roles and record conditions, and use `cms.hidden` only when the action is
76
+ intentionally API-only. Action input names are humanized (`sessionId`
77
+ becomes **Session**). The CMS resolves a matching `fkTarget` through the
78
+ parent-table column metadata, then reads the FK target through its safe
79
+ collection or named-default-view route. It renders search only when that
80
+ route supports it. Without an explicit schema relationship, the action
81
+ dialog falls back to plain text.
82
+
83
+ Read [Schema Registry](/ui/admin/schema-registry),
84
+ [Table Views](/ui/admin/table-views), and [Actions](/ui/admin/actions) before
85
+ authoring or reviewing a CMS-backed schema.
35
86
 
36
87
  ## Architecture
37
88
 
@@ -91,7 +142,7 @@ export default defineConfig({
91
142
  ### 2. Compile
92
143
 
93
144
  ```bash
94
- quickback compile
145
+ quickback build
95
146
  ```
96
147
 
97
148
  The compiler generates `schema-registry.json` and copies CMS static assets to `src/apps/`. It also adds an `[assets]` section to `wrangler.toml` so Cloudflare serves the CMS SPA automatically.
@@ -125,6 +176,20 @@ This adds a custom domain route to `wrangler.toml`. Both domains serve the same
125
176
  cms: { access: "member" } // let organization members in
126
177
  ```
127
178
 
179
+ Start apps ship that setting. A sysadmin who also holds an organization membership uses the seat (`owner` / `admin` / `member`) rather than the cross-tenant picker — the picker is only for a sysadmin who belongs to nothing.
180
+
181
+ > **File uploads need valid R2 credentials**
182
+ >
183
+ > Profile pictures and organization logos are **Account UI**, not the CMS — they
184
+ > live at `/account/profile` and `/account/<slug>/settings`. They only work with
185
+ > `account.fileUploads: true`, [managed R2](/platform/storage/r2)
186
+ > (`defineFileStorage("cloudflare-r2", { managed: true })`), and the
187
+ > `R2_ACCOUNT_ID` / `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` secrets. A
188
+ > Start `workers.dev` deploy can create the bucket; it cannot mint those
189
+ > credentials, so Start leaves uploads off. Pasting a URL into a `q.url()`
190
+ > column in the CMS is just a string — it does not upload bytes.
191
+
192
+
128
193
  > **`user.role === "appmanager"` does not open the CMS in either mode.** appmanager is the *control plane* — users, organizations, and subscriptions at [`/account/admin`](/ui/account) — and deliberately holds no tenant-data powers. Keeping those separable is the entire point of the appmanager/sysadmin split. An appmanager who is also a member of an organization gets in as that member, on the membership, not on the platform role.
129
194
 
130
195
 
@@ -138,7 +203,7 @@ The gates that carry real data:
138
203
 
139
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.
140
205
  2. **`custom_view` routes** — saved views follow whoever is admitted: the `sysadmin` tier in `"sysadmin"` mode, org membership *or* sysadmin in `"member"` mode.
141
- 3. **Account UI link** — the "Go to CMS" button is hidden for callers who wouldn't get in.
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.
142
207
 
143
208
  Your resource API endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `read`, `create`, `update`, `delete`, and `upsert` access rules you defined.
144
209
 
@@ -162,7 +227,7 @@ The shell is served to any signed-in caller, and the SPA resolves one of six sta
162
227
 
163
228
  The decision is a pure function (`resolveCmsAccess`), so the table above is tested rather than described.
164
229
 
165
- Sysadmin scope lives in the browser and rides every request as `?organizationId=` — it is not part of the session, because a sysadmin holds no membership row for Better Auth to make active. Change it from the sidebar.
230
+ For a zero-membership sysadmin in explicit cross-tenant mode, scope lives in the browser and rides every request as `?organizationId=` because Better Auth has no membership row to make active. Change it from the sidebar. A sysadmin who also holds memberships follows the ordinary membership flow instead; selecting a membership clears any older cross-tenant override. The sidebar shows the sole organization as static text and becomes a dropdown only when the user belongs to multiple organizations.
166
231
 
167
232
  #### `access: "sysadmin"` without `cms.sysadmin`
168
233
 
@@ -17,6 +17,30 @@ The CMS determines which fields are editable from the table's guards:
17
17
 
18
18
  If a table has no explicit guard config, the CMS falls back to making all non-system columns editable (excluding `id`, audit fields, `organizationId`, and `deletedAt`).
19
19
 
20
+ ### When Create and Edit Controls Exist
21
+
22
+ The CMS does not invent write operations. It shows **New** only when the schema
23
+ registry contains generated `create` CRUD for the table and the current
24
+ membership role passes `create.access`. It shows edit links and inline editors
25
+ only when generated `update` CRUD exists, `update.access` admits that role, and
26
+ the field is updatable. The API enforces the same rules even if someone calls
27
+ it without the CMS.
28
+
29
+ For a table that should be manageable in the CMS:
30
+
31
+ - Define `create` with CMS-appropriate access and include every required,
32
+ caller-supplied field in `guards.createable`. Required fields supplied by a
33
+ schema default or by the system stay out of the form.
34
+ - Define `update` with CMS-appropriate access and put only ordinary editable
35
+ fields in `guards.updatable`.
36
+ - Give workflow-managed status/state fields a default, map them to the named
37
+ transitions/actions in `guards.protected`, and never also list them in
38
+ `updatable` or `createable`. The CMS changes those fields through action
39
+ controls, not a direct input.
40
+
41
+ `guards` shape the fields inside an allowed operation; they do not grant CRUD
42
+ access or create a missing route.
43
+
20
44
  ## Cell Types
21
45
 
22
46
  Each column type gets a specialized editor:
@@ -35,15 +59,25 @@ A Yes/No dropdown. Click to toggle between the two values.
35
59
 
36
60
  ### FK Typeahead
37
61
 
38
- Foreign key columns (ending in `Id`) get a typeahead dropdown with server-side search:
62
+ Foreign key columns with an emitted `fkTarget` get a typeahead dropdown with server-side search:
39
63
 
40
64
  - **Debounced search** — Queries are debounced at 200ms to avoid flooding the API
41
- - **Server-side filtering** — Sends `?search=query&pageSize=20` to the FK target table's list endpoint
65
+ - **Server-side filtering** — Sends `?search=` only when the target collection or named default view supports search
42
66
  - **Keyboard navigation** — Arrow keys to navigate options, Enter to select, Escape to close
43
- - **Auto-loads initial options** — Opens with the first 20 records sorted by display column
67
+ - **Auto-loads initial options** — Opens with the first 10 matching records when search is supported, or the first 50 records when it is not
44
68
  - **Display labels** — Shows the target table's display column value (e.g., "John Smith" instead of `usr_abc123`)
45
69
 
46
- The FK target table is derived by stripping the `Id` suffix from the column name. For example, `contactId` searches the `contact` table, and `accountCodeId` searches the `accountCode` table.
70
+ The FK target table comes from schema-registry metadata. Declare feature-table
71
+ relationships with `.references(() => target.id)` so the compiler emits a
72
+ reliable `fkTarget`; a name ending in `Id` is not enough to establish the
73
+ relationship. For example, `sessionId` can resolve through its parent-table
74
+ column metadata and search the `sessions` target table.
75
+
76
+ For a target with named views, the editor uses only an authored default view
77
+ that the current role can access. That projection must contain the target
78
+ primary key and `displayColumn`; there is no bare-list fallback. If the
79
+ effective `query.searchable` list is empty, the editor shows the first 50
80
+ options with a read-only search box and sends no `?search` request.
47
81
 
48
82
  ### Enum / Select
49
83
 
@@ -5,7 +5,7 @@ The CMS record detail page groups fields into collapsible sections. By default,
5
5
  There are two layers:
6
6
 
7
7
  1. **Code-defined layouts** — developers configure named layouts in the table config
8
- 2. **User-created views** — end-users create and save custom views via the CMS UI
8
+ 2. **Custom layouts** — end-users create and save record layouts through the CMS table settings
9
9
 
10
10
  ## Code-Defined Layouts
11
11
 
@@ -75,41 +75,42 @@ When a table has multiple named layouts, a dropdown appears in the record detail
75
75
 
76
76
  If only one layout is defined, it's used automatically without showing a dropdown.
77
77
 
78
- ## User-Created Custom Views
78
+ ## Custom Record Layouts
79
79
 
80
80
  End-users can create their own record layouts via the CMS UI. These are stored in the database and can be shared with other organization members.
81
81
 
82
- ### Creating a View
82
+ ### Creating a Layout
83
83
 
84
- 1. Open any record detail page
85
- 2. Click the **+ View** button in the header
86
- 3. In the view builder dialog:
87
- - Name your view
84
+ 1. Open the table
85
+ 2. Click the settings cog in the table header
86
+ 3. Open **Record layouts** and click **Create**
87
+ 4. In the record layout dialog:
88
+ - Name your layout
88
89
  - Add sections and assign fields from a dropdown
89
90
  - Set columns (1 or 2) and collapsed state per section
90
91
  - Optionally share with your organization
91
- 4. Click **Create View**
92
+ 5. Click **Create layout**
92
93
 
93
- The new view appears in the layout dropdown alongside code-defined layouts.
94
+ The new layout appears in the record-page layout dropdown alongside code-defined layouts.
94
95
 
95
- ### Editing and Deleting Views
96
+ ### Editing and Deleting Layouts
96
97
 
97
- - Click the **gear icon** next to the dropdown to edit the current custom view
98
- - Click the **trash icon** to delete it (with confirmation)
98
+ - Open **Record layouts** from the table header to edit or delete a custom layout
99
+ - Open a record and click **Customize layout** to edit the active custom layout against that record
99
100
  - Code-defined layouts cannot be edited or deleted from the CMS
100
101
 
101
102
  ### Access Control
102
103
 
103
104
  | Operation | Who Can Do It |
104
105
  |-----------|---------------|
105
- | Create a view | Any member, admin, or owner |
106
- | Edit/delete own views | The creator |
107
- | Edit/delete any view | Admins and owners |
108
- | View shared views | All organization members |
106
+ | Create a layout | Any member, admin, or owner |
107
+ | Edit/delete own layouts | The creator |
108
+ | Edit/delete any layout | Admins and owners |
109
+ | View shared layouts | All organization members |
109
110
 
110
- ### Setting Up the Custom View Feature
111
+ ### Setting Up Custom Layout Storage
111
112
 
112
- To enable user-created views, add a `customView` table to your Quickback project:
113
+ To enable custom record layouts, add a `customView` table to your Quickback project:
113
114
 
114
115
  ```typescript
115
116
  // quickback/features/cms/custom-view.ts
@@ -164,16 +165,16 @@ export default defineTable(customView, {
164
165
  });
165
166
  ```
166
167
 
167
- Compile your project to generate the API endpoints. The CMS will automatically detect the `customView` table and enable the view builder UI.
168
+ Compile your project to generate the API endpoints. The CMS automatically detects the `customView` table and enables record layout management.
168
169
 
169
170
  ## Fallback Behavior
170
171
 
171
172
  | Scenario | Result |
172
173
  |----------|--------|
173
- | No `layouts` config, no custom views | Auto-grouping by naming heuristics |
174
+ | No `layouts` config, no custom layouts | Auto-grouping by naming heuristics |
174
175
  | `layouts` config defined | Uses "default" layout or first available |
175
176
  | Multiple layouts | Dropdown for switching, persisted per table |
176
- | Custom views created | Appear in dropdown below code-defined layouts |
177
+ | Custom layouts created | Appear in dropdown below code-defined layouts |
177
178
 
178
179
  ## Next Steps
179
180
 
@@ -53,6 +53,8 @@ interface TableMeta {
53
53
  guards: GuardsConfig;
54
54
  masking: Record<string, MaskingRule>;
55
55
  views: Record<string, ViewConfig>;
56
+ defaultView?: string;
57
+ requiresExplicitView?: true;
56
58
  validation: Record<string, ValidationRule>;
57
59
  actions: ActionMeta[];
58
60
  displayColumn?: string;
@@ -75,6 +77,8 @@ interface TableMeta {
75
77
  | `guards` | Field-level create/update/immutable/protected rules |
76
78
  | `masking` | Per-field masking rules keyed by column name |
77
79
  | `views` | Named column projections keyed by view name |
80
+ | `defaultView` | Authored `read.defaultView`, used for initial CMS and FK lookup reads |
81
+ | `requiresExplicitView` | Emitted as `true` when named views exist without a default and the CMS must not issue a bare collection read |
78
82
  | `validation` | Per-field validation rules keyed by column name |
79
83
  | `actions` | Array of action definitions scoped to this table |
80
84
  | `displayColumn` | Column used as human-readable label (auto-detected or explicit) |
@@ -93,6 +97,7 @@ interface ColumnMeta {
93
97
  dbName: string;
94
98
  type: "text" | "integer" | "real" | "blob";
95
99
  mode?: "boolean";
100
+ kind?: string;
96
101
  primaryKey: boolean;
97
102
  notNull: boolean;
98
103
  defaultValue?: string | number | boolean;
@@ -106,6 +111,7 @@ interface ColumnMeta {
106
111
  | `dbName` | Snake_case SQL column name |
107
112
  | `type` | SQLite storage type |
108
113
  | `mode` | When `"boolean"`, an integer column represents true/false |
114
+ | `kind` | q-DSL column kind (`text`, `url`, `int`, `bool`, `uuid`, `timestamp`, `json`, `id`, `enum`, `scope`, `stamp`) — q-authored columns only. The CMS picks the form control from it (`timestamp` → date-time picker, `bool` → checkbox…), so `inputHints` is only needed to override. Absent on raw-Drizzle tables, where `type` is all there is. |
109
115
  | `primaryKey` | Whether this column is the primary key |
110
116
  | `notNull` | Whether the column has a NOT NULL constraint |
111
117
  | `defaultValue` | Static default value (strings, numbers, or booleans) |
@@ -183,6 +189,7 @@ interface ActionMeta {
183
189
  roles: string[];
184
190
  record?: Record<string, unknown>;
185
191
  };
192
+ transition?: ActionTransitionMeta; // record actions with a state machine
186
193
  standalone?: boolean;
187
194
  path?: string;
188
195
  method?: string;
@@ -191,6 +198,20 @@ interface ActionMeta {
191
198
  cms?: CmsConfig;
192
199
  }
193
200
 
201
+ /** The state-machine subset of the action's `transition` policy. Write-side
202
+ * keys (stamp, clears, onIllegal) are omitted; a `custom` guard function is
203
+ * replaced by `hasCustomGuard: true`. The CMS hides the action when the
204
+ * record's current state cannot take it — see /ui/admin/actions#transition-state. */
205
+ interface ActionTransitionMeta {
206
+ field?: string | null;
207
+ fromTo?: Record<string, Array<string | number | boolean>>;
208
+ to?: string | number | boolean;
209
+ via?: string;
210
+ guard?: Record<string, string | number | boolean | { null: true } | { notNull: true }>;
211
+ hasCustomGuard?: boolean;
212
+ idempotent?: "noop" | "error";
213
+ }
214
+
194
215
  interface CmsConfig {
195
216
  label?: string;
196
217
  icon?: string;
@@ -253,13 +274,20 @@ Named column projection with access control:
253
274
  interface ViewConfig {
254
275
  fields: string[];
255
276
  access: AccessRule;
277
+ query?: {
278
+ filterable?: string[] | null;
279
+ searchable?: string[];
280
+ sortable?: string[];
281
+ defaultSort?: string;
282
+ };
256
283
  }
257
284
  ```
258
285
 
259
286
  | Field | Description |
260
287
  |-------|-------------|
261
288
  | `fields` | Array of column names to include in this view |
262
- | `access` | Role-based access rules (same shape as CrudConfig access) |
289
+ | `access` | Effective role-based access: the view override or inherited table `read.access` |
290
+ | `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. |
263
291
 
264
292
  ## CmsLayout
265
293
 
@@ -324,7 +352,7 @@ interface MaskingRule {
324
352
 
325
353
  ## ValidationRule
326
354
 
327
- Per-field validation constraints:
355
+ 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:
328
356
 
329
357
  ```typescript
330
358
  interface ValidationRule {
@@ -334,9 +362,18 @@ interface ValidationRule {
334
362
  max?: number;
335
363
  enum?: string[];
336
364
  email?: boolean;
365
+ url?: boolean;
337
366
  }
338
367
  ```
339
368
 
369
+ | Rule | Emitted from |
370
+ |------|--------------|
371
+ | `enum` | `q.enum([...])`, or `text(..., { enum: [...] })` in raw Drizzle — the CMS renders a select |
372
+ | `url` | `q.url()` — the CMS renders a `url` input; the API rejects anything `new URL()` can't parse, including `""` |
373
+ | `maxLength` | `q.text({ maxLength })` / `q.url({ maxLength })` |
374
+
375
+ 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.
376
+
340
377
  | Field | Description |
341
378
  |-------|-------------|
342
379
  | `minLength` | Minimum string length |
@@ -4,7 +4,7 @@ The schema registry is a static JSON file generated by the Quickback compiler. I
4
4
 
5
5
  ## Generation
6
6
 
7
- Schema registry generation is **enabled by default**. Run `quickback compile` and the compiler outputs `schema-registry.json` alongside your compiled API files.
7
+ Schema registry generation is **enabled by default**. Run `quickback build` and the compiler outputs `schema-registry.json` alongside your compiled API files.
8
8
 
9
9
  To disable generation:
10
10
 
@@ -67,10 +67,12 @@ interface TableMeta {
67
67
  createable: string[]; // Fields allowed on create
68
68
  updatable: string[]; // Fields allowed on update
69
69
  immutable: string[]; // Fields locked after creation
70
- protected: Record<string, string[]>; // Fields only updatable via actions
70
+ protected: Record<string, string[]>; // Fields writable only via named actions/transitions
71
71
  };
72
72
  masking: Record<string, MaskingRule>; // Per-field masking rules
73
73
  views: Record<string, ViewConfig>; // Named column projections
74
+ defaultView?: string; // Authored read.defaultView
75
+ requiresExplicitView?: true; // Named views exist with no default
74
76
  validation: Record<string, ValidationRule>; // Per-field validation
75
77
  actions: ActionMeta[]; // Table-scoped actions for this table
76
78
  displayColumn?: string; // Human-readable label column
@@ -78,8 +80,72 @@ interface TableMeta {
78
80
  }
79
81
  ```
80
82
 
83
+ Each named view carries the effective read contract the CMS consumes:
84
+
85
+ ```typescript
86
+ interface ViewConfig {
87
+ fields: string[];
88
+ access: AccessRule;
89
+ query?: {
90
+ filterable?: string[] | null;
91
+ searchable?: string[];
92
+ sortable?: string[];
93
+ defaultSort?: string;
94
+ };
95
+ }
96
+ ```
97
+
98
+ For current registries, `access` is the view's explicit access rule or the
99
+ inherited table `read.access` when the view omits an override.
100
+ `query.searchable` is likewise the effective search allowlist: the explicit
101
+ view list when present, otherwise the compiler's eligible table search fields
102
+ after masked fields are removed. An empty array means the named view does not
103
+ support `?search`; it does not mean the table has no rows. `query.filterable`
104
+ contains the explicit named-view allowlist when authored, otherwise a q table's
105
+ column-level `.filterable()` defaults. Raw Drizzle tables emit `null` when no
106
+ closed filter allowlist can be derived, preserving their compatibility mode.
107
+
81
108
  `create`, `update`, `delete`, and `upsert` mirror the preferred flat DSL from `defineTable(...)`. The legacy `crud` block is still emitted for backwards compatibility with older consumers.
82
109
 
110
+ The registry is a projection of authored definitions, not a source of missing
111
+ intent. In particular:
112
+
113
+ - `views` lists the named projections available to the CMS. `defaultView`
114
+ carries the authored `read.defaultView`. When named views exist without one,
115
+ the registry emits `requiresExplicitView: true`; the CMS must show **Choose a
116
+ view** without making a collection request. It must not silently choose the
117
+ first accessible projection, because that would invent an access/shape
118
+ contract. **All Fields** is absent whenever `views` is nonempty. A bare API
119
+ collection request in this state returns `VIEW_REQUIRED`. `defaultSort` is
120
+ unrelated; it controls ordering only.
121
+ - `displayColumn` supplies the human-readable label used for records and
122
+ referenced values. Set it explicitly when the table is a user-facing FK
123
+ target.
124
+ - `crud`, the flat write-operation metadata, and `guards` determine whether
125
+ **New** and edit controls can exist and which inputs they expose.
126
+ - `actions` and `featureActions`, together with action access and `cms`
127
+ metadata, determine whether a control is record-bound, toolbar-placed,
128
+ disabled by state, or intentionally hidden.
129
+
130
+ ### Named-view targets and FK lookups
131
+
132
+ An FK lookup targeting a table with no named views uses the ordinary collection
133
+ route. Once the target declares named views, the CMS may automatically use only
134
+ its authored, role-accessible `defaultView`. It calls
135
+ `GET /api/v1/<target>/views/<defaultView>` and never retries a bare collection
136
+ or silently chooses another view.
137
+
138
+ That default view is lookup-safe when its `fields` include both the target's
139
+ primary key and `displayColumn`. If the default is missing, inaccessible to the
140
+ current role, or omits either identity/label field, the CMS disables the lookup
141
+ and displays an actionable explanation without making a data request.
142
+
143
+ For label typeahead, include the `displayColumn` in the effective
144
+ `query.searchable` allowlist. An explicit named-view allowlist is authoritative,
145
+ so the column does not also need `.searchable()`. When the effective searchable
146
+ list is empty, the selector remains usable as a first-50 chooser; its search
147
+ box is read-only and the CMS sends no `?search` parameter.
148
+
83
149
  ## Feature Actions
84
150
 
85
151
  Standalone actions do not always belong to a single table. When an action is attached to a multi-table feature root, the compiler emits it under `featureActions[featureName]` instead of duplicating it across every table.
@@ -92,6 +158,14 @@ interface SchemaRegistry {
92
158
 
93
159
  The CMS uses `featureActions` for toolbar-style actions that apply to the feature as a whole. Use `cms.placement` on standalone actions to control whether they show for the whole feature or only selected tables.
94
160
 
161
+ Action dialogs derive labels and controls from `ActionMeta.inputFields` plus the
162
+ table registry. An input named `sessionId` is labeled **Session**. When a
163
+ corresponding column has `fkTarget: "sessions"`, the CMS renders a typeahead
164
+ using the target table's `displayColumn` and the lookup read contract above;
165
+ otherwise it renders a plain text input. This is another reason to author the
166
+ schema-level `.references()` even when the action, rather than generic create
167
+ CRUD, is the visible create flow.
168
+
95
169
  > **Internal Tables**
96
170
  >
97
171
  > Tables without a `defineTable()` resource config are marked `internal: true` and hidden from the CMS sidebar. These are typically join tables or system tables.
@@ -118,11 +192,26 @@ The compiler automatically includes the system columns (`id`, `organizationId`),
118
192
 
119
193
  ### fkTarget — FK Resolution
120
194
 
121
- Columns ending in `Id` may have a `fkTarget` property indicating which table they reference. This is resolved in priority order:
195
+ Columns with an authored feature-table relationship have an `fkTarget`
196
+ property indicating which table they reference. In the Quickback schema DSL,
197
+ declare that relationship on the column:
122
198
 
123
- 1. **Explicit `references`** — from your `defineTable()` config (highest priority)
124
- 2. **Drizzle `.references()`** — parsed from schema source code
125
- 3. **Convention** — strip `Id` suffix, match table name directly
199
+ {/* doc-compile: skip — cross-table column excerpt; complete table forms live in /define/schema. */}
200
+ ```typescript
201
+ sessionId: q.text().required().references(() => sessions.id)
202
+ ```
203
+
204
+ The compiler also understands Drizzle's equivalent `.references()` form. A
205
+ legacy `defineTable({ references: { ... } })` map can override registry target
206
+ metadata, but it does not create the database foreign key; prefer the
207
+ schema-level relationship.
208
+
209
+ Do not rely on a column merely ending in `Id`. A same-named sibling table is a
210
+ useful warning/suggestion when the explicit relationship is missing, but the
211
+ name alone cannot establish author intent. CMS-ready definitions make every
212
+ feature-table relationship explicit. Better Auth identifiers such as `userId`
213
+ and `organizationId` are intentionally different: their tables live in
214
+ `AUTH_DB`, so feature columns must not add cross-database `.references()` calls.
126
215
 
127
216
  ```json
128
217
  {
@@ -177,6 +266,11 @@ If you don't explicitly set `displayColumn` in your resource config, the compile
177
266
 
178
267
  The first match wins. If no candidate matches, the table has no display column and the CMS falls back to showing IDs.
179
268
 
269
+ For a table used in CMS selectors or record titles, prefer explicit config even
270
+ when auto-detection currently finds the same column. It records which label is
271
+ part of the UI contract and prevents a later schema change from silently
272
+ changing that label.
273
+
180
274
  ### Explicit Config
181
275
 
182
276
  Set it explicitly in your table definition:
@@ -201,7 +295,13 @@ roomTypeId: "rt_abc123" → displayed as "Master Bedroom"
201
295
  accountCodeId: "ac_xyz789" → displayed as "4100 - Revenue"
202
296
  ```
203
297
 
204
- The FK target table is resolved from the `fkTarget` property on each column. For simple cases like `roomTypeId` → `roomType`, the compiler auto-detects it. For non-obvious mappings (e.g., `vendorId` → `contact`), use explicit [`references`](/define/schema#references) in your `defineTable()` config.
298
+ The FK target table is resolved from the `fkTarget` property on each column.
299
+ Declare a schema-level [`.references()` relationship](/define/schema#references)
300
+ for feature-table ids, including apparently obvious cases such as
301
+ `roomTypeId` → `roomTypes`. Do not make selector behavior depend on a naming
302
+ heuristic. For a legacy metadata-only alias such as `vendorId` → `contact`, the
303
+ resource `references` map can override `fkTarget`, but it is not a substitute
304
+ for a database FK when the two feature tables genuinely have one.
205
305
 
206
306
  ## Pages
207
307
 
@@ -12,10 +12,10 @@ cms: { access: "member" }
12
12
 
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
- 1. **Account UI** — the "Go to CMS" button is hidden for callers who wouldn't get in.
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
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.
17
- 4. **`custom_view` routes** — the CMS-internal saved-views table uses `userRole: ["appmanager"]` (and, when `cms.sysadmin: true`, also admits `sysadmin`), so saved views can't be read or modified from outside the CMS by non-operator accounts.
18
- 5. **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
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
+ 4. **In-SPA gate** — the SPA renders the matching blocked, membership-picker, or sysadmin-scope screen before loading CMS data.
19
19
 
20
20
  Your resource API endpoints keep whatever `read`, `create`, `update`, `delete`, or `upsert` access rules you defined — they're the app's data API and unaffected by the CMS gate.
21
21
 
@@ -55,6 +55,13 @@ With the config above:
55
55
  - **Admins** see Create and Edit buttons but no Delete
56
56
  - **Owners** see all buttons
57
57
 
58
+ When an operation admits a pseudo-role (`PUBLIC`, `AUTHENTICATED`, or
59
+ `SESSION`) instead of an org membership role, the CMS still shows the
60
+ button to anyone who is in the CMS with a membership. A public contact
61
+ form (`create: { access: { roles: ["PUBLIC"] } }`) can be filled by
62
+ anonymous callers *and* by staff in the admin UI — hiding **New** from
63
+ the owner would be stricter than the API.
64
+
58
65
  The row action menu also adapts — Edit and Delete entries only appear when the role has the corresponding permission.
59
66
 
60
67
  ## Guards
@@ -104,6 +111,11 @@ guards: {
104
111
  }
105
112
  ```
106
113
 
114
+ A protected field belongs in neither `guards.createable` nor
115
+ `guards.updatable`. For transition-managed status/state, declare a schema
116
+ default for the initial value and allow only the named transitions/actions to
117
+ write it.
118
+
107
119
  ## Masking
108
120
 
109
121
  Masking rules redact sensitive data based on the user's role. The CMS applies masking client-side for display and the API enforces it server-side in responses.
@@ -161,7 +173,10 @@ read: {
161
173
  }
162
174
  ```
163
175
 
164
- Members only see the "summary" view option. Admins and owners see both "summary" and "financial". The "All Fields" option is always available.
176
+ Members only see the `summary` view option. Admins and owners see `summary` and
177
+ `financial`. **All Fields** is absent because named views define the available
178
+ projections. Since this excerpt does not declare `read.defaultView`, the CMS
179
+ shows **Choose a view** and makes no data request until the user selects one.
165
180
 
166
181
  ## Firewall
167
182