@quickback-dev/cli 0.66.1 → 0.66.2

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 (199) 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 +793 -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/crud.md +7 -0
  56. package/dist/skill/docs/api/index.md +1 -1
  57. package/dist/skill/docs/api/openapi.md +1 -1
  58. package/dist/skill/docs/changelog/index.md +19 -1
  59. package/dist/skill/docs/configure/agents.md +1 -1
  60. package/dist/skill/docs/configure/index.md +8 -3
  61. package/dist/skill/docs/configure/providers.md +1 -0
  62. package/dist/skill/docs/configure/variables.md +3 -3
  63. package/dist/skill/docs/define/access.md +7 -0
  64. package/dist/skill/docs/define/actions/defining.md +35 -7
  65. package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
  66. package/dist/skill/docs/define/actions/scoped-db.md +46 -16
  67. package/dist/skill/docs/define/areas.md +1 -1
  68. package/dist/skill/docs/define/diagnostics.md +1 -0
  69. package/dist/skill/docs/define/encryption.md +1 -1
  70. package/dist/skill/docs/define/feature.md +14 -7
  71. package/dist/skill/docs/define/guards.md +27 -3
  72. package/dist/skill/docs/define/schema.md +24 -14
  73. package/dist/skill/docs/define/security.md +1 -1
  74. package/dist/skill/docs/define/transitions.md +35 -4
  75. package/dist/skill/docs/define/views.md +33 -0
  76. package/dist/skill/docs/index.md +2 -2
  77. package/dist/skill/docs/platform/auth/api-keys.md +1 -1
  78. package/dist/skill/docs/platform/auth/using-auth.md +37 -0
  79. package/dist/skill/docs/platform/database/d1.md +2 -2
  80. package/dist/skill/docs/platform/database/neon.md +4 -4
  81. package/dist/skill/docs/platform/email/index.md +1 -1
  82. package/dist/skill/docs/platform/queues/handlers.md +1 -1
  83. package/dist/skill/docs/platform/queues/using-queues.md +1 -1
  84. package/dist/skill/docs/platform/schedules/index.md +1 -1
  85. package/dist/skill/docs/platform/storage/index.md +3 -3
  86. package/dist/skill/docs/platform/storage/r2.md +87 -37
  87. package/dist/skill/docs/platform/storage/using-r2.md +99 -19
  88. package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
  89. package/dist/skill/docs/start/deploy-browser.md +39 -44
  90. package/dist/skill/docs/start/deploy-owner-access.md +28 -19
  91. package/dist/skill/docs/start/deploy.md +2 -2
  92. package/dist/skill/docs/start/first-api.md +1 -1
  93. package/dist/skill/docs/start/hand-crafted.md +3 -3
  94. package/dist/skill/docs/start/index.md +3 -3
  95. package/dist/skill/docs/start/quickstart.md +3 -3
  96. package/dist/skill/docs/start/template-blog.md +2 -2
  97. package/dist/skill/docs/start/template-cloudflare.md +2 -2
  98. package/dist/skill/docs/start/template-empty.md +1 -1
  99. package/dist/skill/docs/start/templates.md +1 -1
  100. package/dist/skill/docs/tooling/claude-skill.md +1 -1
  101. package/dist/skill/docs/tooling/cli.md +20 -15
  102. package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  103. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  104. package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
  105. package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  106. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  107. package/dist/skill/docs/tooling/output.md +23 -2
  108. package/dist/skill/docs/tooling/troubleshooting.md +1 -1
  109. package/dist/skill/docs/ui/account/environment-variables.md +2 -2
  110. package/dist/skill/docs/ui/account/features/admin.md +1 -1
  111. package/dist/skill/docs/ui/account/features/avatars.md +24 -8
  112. package/dist/skill/docs/ui/account/features/index.md +9 -5
  113. package/dist/skill/docs/ui/account/features/organizations.md +3 -2
  114. package/dist/skill/docs/ui/account/index.md +3 -1
  115. package/dist/skill/docs/ui/account/with-quickback.md +1 -1
  116. package/dist/skill/docs/ui/admin/actions.md +97 -3
  117. package/dist/skill/docs/ui/admin/components.md +4 -6
  118. package/dist/skill/docs/ui/admin/connecting.md +15 -3
  119. package/dist/skill/docs/ui/admin/index.md +71 -6
  120. package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
  121. package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
  122. package/dist/skill/docs/ui/admin/schema-format.md +39 -2
  123. package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
  124. package/dist/skill/docs/ui/admin/security.md +19 -4
  125. package/dist/skill/docs/ui/admin/table-views.md +59 -12
  126. package/package.json +1 -1
  127. package/src/cursor/quickback.mdc +1 -1
  128. package/src/skill/SKILL.md +6 -6
  129. package/src/skill/docs/api/crud.md +7 -0
  130. package/src/skill/docs/api/index.md +1 -1
  131. package/src/skill/docs/api/openapi.md +1 -1
  132. package/src/skill/docs/changelog/index.md +19 -1
  133. package/src/skill/docs/configure/agents.md +1 -1
  134. package/src/skill/docs/configure/index.md +8 -3
  135. package/src/skill/docs/configure/providers.md +1 -0
  136. package/src/skill/docs/configure/variables.md +3 -3
  137. package/src/skill/docs/define/access.md +7 -0
  138. package/src/skill/docs/define/actions/defining.md +35 -7
  139. package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
  140. package/src/skill/docs/define/actions/scoped-db.md +46 -16
  141. package/src/skill/docs/define/areas.md +1 -1
  142. package/src/skill/docs/define/diagnostics.md +1 -0
  143. package/src/skill/docs/define/encryption.md +1 -1
  144. package/src/skill/docs/define/feature.md +14 -7
  145. package/src/skill/docs/define/guards.md +27 -3
  146. package/src/skill/docs/define/schema.md +24 -14
  147. package/src/skill/docs/define/security.md +1 -1
  148. package/src/skill/docs/define/transitions.md +35 -4
  149. package/src/skill/docs/define/views.md +33 -0
  150. package/src/skill/docs/index.md +2 -2
  151. package/src/skill/docs/platform/auth/api-keys.md +1 -1
  152. package/src/skill/docs/platform/auth/using-auth.md +37 -0
  153. package/src/skill/docs/platform/database/d1.md +2 -2
  154. package/src/skill/docs/platform/database/neon.md +4 -4
  155. package/src/skill/docs/platform/email/index.md +1 -1
  156. package/src/skill/docs/platform/queues/handlers.md +1 -1
  157. package/src/skill/docs/platform/queues/using-queues.md +1 -1
  158. package/src/skill/docs/platform/schedules/index.md +1 -1
  159. package/src/skill/docs/platform/storage/index.md +3 -3
  160. package/src/skill/docs/platform/storage/r2.md +87 -37
  161. package/src/skill/docs/platform/storage/using-r2.md +99 -19
  162. package/src/skill/docs/platform/webhooks/inbound.md +40 -0
  163. package/src/skill/docs/start/deploy-browser.md +39 -44
  164. package/src/skill/docs/start/deploy-owner-access.md +28 -19
  165. package/src/skill/docs/start/deploy.md +2 -2
  166. package/src/skill/docs/start/first-api.md +1 -1
  167. package/src/skill/docs/start/hand-crafted.md +3 -3
  168. package/src/skill/docs/start/index.md +3 -3
  169. package/src/skill/docs/start/quickstart.md +3 -3
  170. package/src/skill/docs/start/template-blog.md +2 -2
  171. package/src/skill/docs/start/template-cloudflare.md +2 -2
  172. package/src/skill/docs/start/template-empty.md +1 -1
  173. package/src/skill/docs/start/templates.md +1 -1
  174. package/src/skill/docs/tooling/claude-skill.md +1 -1
  175. package/src/skill/docs/tooling/cli.md +20 -15
  176. package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
  177. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
  178. package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
  179. package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
  180. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +47 -2
  181. package/src/skill/docs/tooling/output.md +23 -2
  182. package/src/skill/docs/tooling/troubleshooting.md +1 -1
  183. package/src/skill/docs/ui/account/environment-variables.md +2 -2
  184. package/src/skill/docs/ui/account/features/admin.md +1 -1
  185. package/src/skill/docs/ui/account/features/avatars.md +24 -8
  186. package/src/skill/docs/ui/account/features/index.md +9 -5
  187. package/src/skill/docs/ui/account/features/organizations.md +3 -2
  188. package/src/skill/docs/ui/account/index.md +3 -1
  189. package/src/skill/docs/ui/account/with-quickback.md +1 -1
  190. package/src/skill/docs/ui/admin/actions.md +97 -3
  191. package/src/skill/docs/ui/admin/components.md +4 -6
  192. package/src/skill/docs/ui/admin/connecting.md +15 -3
  193. package/src/skill/docs/ui/admin/index.md +71 -6
  194. package/src/skill/docs/ui/admin/inline-editing.md +38 -4
  195. package/src/skill/docs/ui/admin/record-layouts.md +22 -21
  196. package/src/skill/docs/ui/admin/schema-format.md +39 -2
  197. package/src/skill/docs/ui/admin/schema-registry.md +107 -7
  198. package/src/skill/docs/ui/admin/security.md +19 -4
  199. package/src/skill/docs/ui/admin/table-views.md +59 -12
@@ -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
 
@@ -9,7 +9,7 @@ Table mode is the default browse experience:
9
9
  - **Click rows** to navigate to the record detail view
10
10
  - **Row action menus** (three-dot icon) with view, edit, delete, and custom actions
11
11
  - **Column headers** are sortable — click to toggle ascending/descending
12
- - **Search bar** for full-text search across all fields
12
+ - **Search bar** for full-text search across fields allowed by the active collection or named-view query contract
13
13
  - **Responsive columns** that adapt to available space
14
14
 
15
15
  Each row shows the most relevant columns for the table. Foreign key columns display human-readable labels (resolved via `_label` fields) instead of raw UUIDs. Boolean columns render as colored Yes/No badges. Enum columns use color-coded pills.
@@ -74,10 +74,22 @@ Views are named column projections defined in your table's resource config. They
74
74
 
75
75
  ### Toolbar
76
76
 
77
- The toolbar shows a view dropdown when the table has views defined. Options include:
77
+ The toolbar shows a view dropdown when the table has named views. Its options
78
+ are the named views the current role may access.
78
79
 
79
- - **All Fields** — Shows all columns (default)
80
- - Custom views — Only show the columns specified in the view config
80
+ For a table with no named views, the toolbar renders no view control and the
81
+ table uses its ordinary collection projection. Declaring any `read.views`
82
+ replaces that projection with the named-view contract; **All Fields** is not an
83
+ extra option alongside the named views. Set `read.defaultView` to choose which
84
+ named projection opens first in the CMS. The schema registry carries that
85
+ selection as `defaultView`, and the CMS calls the named-view route from its
86
+ first request.
87
+
88
+ If named views exist without `read.defaultView`, the registry emits
89
+ `requiresExplicitView: true`. The CMS shows **Choose a view** and makes no data
90
+ request until the user selects an accessible named view. It never silently
91
+ chooses the first accessible projection, because projection choice is part of
92
+ the table's data/access contract.
81
93
 
82
94
  Views are filtered by role access. If a view's access rules require `admin` and the current user is a `member`, that view won't appear in the dropdown.
83
95
 
@@ -87,24 +99,49 @@ Given this definition:
87
99
 
88
100
  ```typescript
89
101
  read: {
102
+ defaultView: 'summary',
90
103
  views: {
91
104
  summary: {
92
105
  fields: ['id', 'name', 'status'],
93
- access: { roles: ['member', 'admin'] },
106
+ access: { roles: ['member+'] },
94
107
  },
95
108
  full: {
96
109
  fields: ['id', 'name', 'status', 'ssn', 'internalNotes'],
97
- access: { roles: ['admin'] },
110
+ access: { roles: ['admin+'] },
98
111
  },
99
112
  },
100
113
  }
101
114
  ```
102
115
 
103
- - Members see: "All Fields" and "summary"
104
- - Admins see: "All Fields", "summary", and "full"
105
- - Owners see: "All Fields", "summary", and "full"
116
+ - Members see `summary`, which opens by default.
117
+ - Admins and owners see `summary` and `full`; `summary` still opens by default.
118
+
119
+ When a view is selected, the CMS calls
120
+ `GET /api/v1/<table>/views/<name>`, fetching only the projected columns. With
121
+ named views but no `read.defaultView`, bare `GET /api/v1/<table>` returns
122
+ `400 VIEW_REQUIRED`. That can be intentional for API callers that must choose a
123
+ projection, but a CMS table intended to open directly should declare an
124
+ accessible default view.
125
+
126
+ ### Views Used by FK Lookups
106
127
 
107
- When a view is selected, the CMS calls the `listView` API endpoint instead of the standard `list`, fetching only the projected columns.
128
+ When this table is the target of an FK selector, a table with no named views
129
+ uses its ordinary collection route. A table with named views is different: the
130
+ CMS lookup uses only the authored `read.defaultView`, verifies that the current
131
+ role may access it, and calls its named-view route. It never retries the bare
132
+ collection endpoint and never chooses another named view automatically.
133
+
134
+ Make that default view lookup-safe by including the table's primary key and
135
+ `displayColumn` in `fields`. For searchable label typeahead, include the
136
+ `displayColumn` in the view's effective `query.searchable` allowlist. An
137
+ explicit named-view allowlist is authoritative, so the column does not also
138
+ need `.searchable()`. The schema registry emits the effective inherited view
139
+ access and searchability so the CMS can decide before requesting data.
140
+
141
+ If the default is missing, inaccessible, or omits the primary key/label, the
142
+ selector is disabled with an actionable message. If the default is otherwise
143
+ valid but its effective searchable list is empty, the selector shows the first
144
+ 50 options as a chooser, keeps search read-only, and sends no `?search`.
108
145
 
109
146
  ## Default Sort
110
147
 
@@ -121,6 +158,10 @@ export default defineTable(podcastEpisodes, {
121
158
 
122
159
  When the CMS loads the table, it applies this sort automatically. Users can still click column headers to change the sort — `defaultSort` only sets the initial state.
123
160
 
161
+ `defaultSort` does not select a named view. Adding or changing it cannot resolve
162
+ `VIEW_REQUIRED`; use `read.defaultView` (or call the explicit named-view route)
163
+ for that.
164
+
124
165
  ## Pagination
125
166
 
126
167
  The bottom of every table view shows pagination controls:
@@ -133,9 +174,15 @@ The default page size is 25 records. The CMS resets to page 1 when you change th
133
174
 
134
175
  ## Search
135
176
 
136
- The search bar performs full-text search across all columns. Type a query and the CMS debounces the request, then fetches matching records from the API.
177
+ The search bar performs full-text search across the fields allowed by the
178
+ active collection or named-view query contract. Type a query and the CMS
179
+ debounces the request, then fetches matching records from the API. For named
180
+ views, the registry's effective `query.searchable` list tells the CMS whether
181
+ the route accepts `?search` and which projected fields participate.
137
182
 
138
- Search works in both Table and Data Table modes, and works with views (searching within the projected columns).
183
+ Search works in both Table and Data Table modes when the active route supports
184
+ it. For FK selectors, an empty named-default-view search allowlist activates
185
+ the first-50 chooser behavior above, which sends no `?search`.
139
186
 
140
187
  ## Next Steps
141
188
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.66.1",
3
+ "version": "0.66.2",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -277,7 +277,7 @@ Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
277
277
 
278
278
  ```bash
279
279
  quickback create <template> <name> # Create project
280
- quickback compile # Compile definitions
280
+ quickback build # Build definitions into your API
281
281
  quickback docs [topic] # Show documentation
282
282
  quickback claude install # Install Claude Code skill
283
283
  quickback cursor install # Install Cursor rules
@@ -46,7 +46,7 @@ Everything runs on the user's own Cloudflare account — no Quickback infrastruc
46
46
  npm install -g @quickback-dev/cli
47
47
  quickback create cloudflare my-app
48
48
  cd my-app
49
- quickback compile
49
+ quickback build
50
50
  wrangler deploy
51
51
  ```
52
52
 
@@ -58,9 +58,9 @@ Three concept files do most of the work:
58
58
 
59
59
  ---
60
60
 
61
- ## What `quickback compile` regenerates (and what it never touches)
61
+ ## What `quickback build` regenerates (and what it never touches)
62
62
 
63
- `quickback compile` is a **pure code generator**. It reads your `quickback/`
63
+ `quickback build` is a **pure code generator**. It reads your `quickback/`
64
64
  definitions, sends them to the compiler service, and writes output to disk. It does
65
65
  **not** connect to, migrate, or read any database — that is a separate, explicit
66
66
  deploy step.
@@ -90,7 +90,7 @@ migrations are no-ops and only pending ones run. The safe loop against a live pr
90
90
  DB:
91
91
 
92
92
  1. Edit `quickback/` definitions.
93
- 2. `quickback compile` → regenerates `src/` and **appends only the new migration(s)**
93
+ 2. `quickback build` → regenerates `src/` and **appends only the new migration(s)**
94
94
  to `quickback/drizzle/` (diffed from your committed meta — it does not rewrite or
95
95
  replay history).
96
96
  3. Deploy → apply pending migrations (no-op for any prod already has), **then**
@@ -306,14 +306,14 @@ from a table file to reach AUTH_DB.
306
306
  ## Quickback CLI (commands the user runs)
307
307
 
308
308
  ```bash
309
- quickback compile # compile project (prompts to log in if not authenticated)
309
+ quickback build # build project (prompts to log in if not authenticated)
310
310
  quickback create <template> # new project from template
311
311
  quickback login # authenticate via browser device flow
312
312
  ```
313
313
 
314
314
  The CLI calls `compiler.quickback.dev` by default. Override with `QUICKBACK_API_URL=http://localhost:3000` for self-hosted compilation.
315
315
 
316
- If you have shell access (e.g. Claude Code), run these commands directly — `quickback compile` is interactive-safe and prompts for login in the browser. In environments without a shell, surface the commands to the user as instructions instead.
316
+ If you have shell access (e.g. Claude Code), run these commands directly — `quickback build` is interactive-safe and prompts for login in the browser. In environments without a shell, surface the commands to the user as instructions instead.
317
317
 
318
318
  ---
319
319
 
@@ -158,6 +158,10 @@ Content-Type: application/json
158
158
  ```
159
159
 
160
160
  Creates a new record. Only fields listed in `guards.createable` are accepted.
161
+ Required columns (`.required()` with no default) must be present; nullable
162
+ columns may be omitted or sent as `null`. An empty string is **not** a blank —
163
+ `""` is validated like any other value (so it fails `q.url()`, `q.enum()`, and
164
+ `q.int()`).
161
165
 
162
166
  ### Response
163
167
 
@@ -196,6 +200,9 @@ Content-Type: application/json
196
200
  ```
197
201
 
198
202
  Updates an existing record. Only fields listed in `guards.updatable` are accepted.
203
+ Omit a key to leave that column untouched; send `null` to clear a nullable
204
+ column. `null` on a `.required()` column is a `400` — the DB would reject the
205
+ write, so the API does first.
199
206
 
200
207
  ### Response
201
208
 
@@ -1,6 +1,6 @@
1
1
  # Using the API
2
2
 
3
- When you run `quickback compile`, Quickback generates a complete REST API from your definitions. This section covers how to use the generated endpoints.
3
+ When you run `quickback build`, Quickback generates a complete REST API from your definitions. This section covers how to use the generated endpoints.
4
4
 
5
5
  ## Base URL
6
6
 
@@ -155,7 +155,7 @@ export default defineConfig({
155
155
  });
156
156
  ```
157
157
 
158
- The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback compile` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
158
+ The file is generated by piping the in-memory spec through [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) — you can keep running it manually if you want a different output path or version, but for the typical case there's nothing to wire up. If your API project and SPA live in the same repo, prefer multiple `openapi.types` outputs over a second manual `codegen:api` step so one `quickback build` keeps both copies in sync. Skipped automatically when `openapi.generate` is `false`.
159
159
 
160
160
  For application code, prefer the compact first-party [`quickback.gen.ts` type tree](/api/typescript). Keep `api-types.gen.ts` for `openapi-fetch` and third-party OpenAPI tooling.
161
161
 
@@ -124,6 +124,22 @@ tenant route. The callback sanitizer now re-applies the basepath to
124
124
  same-origin paths, covering every sign-in flow (password, passkey, email OTP,
125
125
  signup) and social-link callbacks.
126
126
 
127
+ ### Fix: Start deploys of R2 apps failed to resolve `aws4fetch`
128
+
129
+ Package-mode compiles (Start's **Deploy to Cloudflare**) bundle against the
130
+ compiler image's `/deps/node_modules`, not a generated `npm install`. R2
131
+ apps import `aws4fetch` from `src/storage/presign.ts`, but it was only
132
+ declared on the generated `package.json` — CLI deploys worked, Start died
133
+ with `Could not resolve "aws4fetch"`. The compiler image now ships the same
134
+ pin the generator writes.
135
+
136
+ ### Start: seeded admin uses your Quickback email
137
+
138
+ A browser deploy writes the first `sysadmin` with the **verified email on
139
+ your Quickback account**, not a synthetic `owner@<app>.invalid` address.
140
+ Reset admin password still rotates the hash only — the broker never
141
+ `UPDATE`s that email afterwards. See [Owner access](/start/deploy-owner-access).
142
+
127
143
  ## v0.65.0 — August 16, 2026
128
144
 
129
145
  ### All Quickback auth plugins are now bundled — zero `@quickback-dev/*` npm dependencies
@@ -237,7 +253,9 @@ evaluation failed, and the underlying local error. This was previously the
237
253
  behavior of `contract.version: 'v2'` only.
238
254
 
239
255
  `quickback compile --allow-degraded-schemas` restores degrade-and-continue for a
240
- single compile. It prints every action that fell back and why.
256
+ single compile. It prints every action that fell back and why. (Removed in
257
+ 0.66.2 — it worked on a total harvest failure but still threw on a partial one,
258
+ the case it existed for.)
241
259
 
242
260
  The compiler also warns when a caller supplies no schemas at all — `rawFiles`
243
261
  callers such as the Start app cannot harvest — naming how many actions of the
@@ -28,7 +28,7 @@ export default defineConfig({
28
28
  });
29
29
  ```
30
30
 
31
- Run `quickback compile` and every endpoint above ships in the Worker.
31
+ Run `quickback build` and every endpoint above ships in the Worker.
32
32
 
33
33
  ## Opting out
34
34
 
@@ -23,7 +23,7 @@ export default defineConfig({
23
23
 
24
24
  ## Discoverable options block
25
25
 
26
- After your first `quickback compile`, the file gets a managed block bracketed by sentinel comments:
26
+ After your first `quickback build`, the file gets a managed block bracketed by sentinel comments:
27
27
 
28
28
  ```typescript
29
29
  export default defineConfig({
@@ -41,7 +41,7 @@ export default defineConfig({
41
41
  //
42
42
  // Login/signup/profile/orgs SPA. Set `true` for default, or object to customize.
43
43
  // account: {
44
- // fileUploads: false, // show the avatar upload UI on the profile page
44
+ // fileUploads: false, // avatar + org-logo upload. Needs managed R2 + valid R2 credentials. Off on Start.
45
45
  // auth: { passkey: false, emailOTP: false, ... },
46
46
  // ...
47
47
  // },
@@ -76,7 +76,7 @@ Quickback notices that `account` is set above the marker and drops it from the m
76
76
  If you ever want to opt out of the auto-managed block, run:
77
77
 
78
78
  ```bash
79
- quickback compile --no-sync-config
79
+ quickback build --no-sync-config
80
80
  ```
81
81
 
82
82
  ## Required Fields
@@ -310,6 +310,11 @@ export default defineConfig({
310
310
 
311
311
  These are merged into the generated `package.json` alongside Quickback's own dependencies. Run `npm install` after compiling to install them.
312
312
 
313
+ The cloud compiler never installs them — it has no network. A project that
314
+ declares `build.dependencies` therefore skips the [Worker bundle
315
+ check](/tooling/cloud-compiler/troubleshooting#complete-compile-wrangler-bundle-failed)
316
+ and reports that as a compile warning.
317
+
313
318
  ## Headless Migration Rename Hints
314
319
 
315
320
  When `drizzle-kit generate` detects a potential rename, it normally prompts for confirmation. Cloud/CI compiles are non-interactive, so you must provide explicit rename hints.
@@ -100,6 +100,7 @@ single Postgres database with no bindings or split mode (see
100
100
  | `featuresBinding` | `string` | `"DB"` | Binding name for features database |
101
101
  | `databaseId` | `string` | — | D1 database ID for the features database (used in generated wrangler.toml) |
102
102
  | `authDatabaseId` | `string` | — | D1 database ID for the auth database |
103
+ | `authMigrations` | `'managed' \| 'external'` | `'managed'` | `'external'` when another project owns the auth D1 (a sibling worker sharing one auth database): no `db:migrate:auth:*` script is emitted and `db:migrate:*` / `deploy` skip it. Deleting the step from `package.json` by hand does not stick — compiler-owned scripts converge on every compile |
103
104
  | `featuresDatabaseId` | `string` | — | Explicit features DB ID (falls back to `databaseId`) |
104
105
  | `filesDatabaseId` | `string` | — | D1 database ID for the files metadata database |
105
106
  | `webhooksDatabaseId` | `string` | — | D1 database ID for the webhooks database |