@quickback-dev/cli 0.66.0 → 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.
- package/README.md +7 -4
- package/dist/commands/build.d.ts +51 -0
- package/dist/commands/build.d.ts.map +1 -0
- package/dist/commands/build.js +793 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/build.test.d.ts +2 -0
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/build.test.js +150 -0
- package/dist/commands/build.test.js.map +1 -0
- package/dist/commands/check.d.ts +2 -2
- package/dist/commands/check.js +4 -4
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.d.ts +1 -1
- package/dist/commands/create.js +7 -7
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/deploy.d.ts +6 -6
- package/dist/commands/deploy.js +23 -23
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/example.js +1 -1
- package/dist/commands/example.js.map +1 -1
- package/dist/commands/mcp.js +1 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/commands/migrate.d.ts +1 -1
- package/dist/commands/migrate.js +3 -3
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrations.js +2 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/push.js +1 -1
- package/dist/commands/push.js.map +1 -1
- package/dist/commands/start.js +1 -1
- package/dist/commands/start.js.map +1 -1
- package/dist/cursor/quickback.mdc +1 -1
- package/dist/index.js +18 -15
- package/dist/index.js.map +1 -1
- package/dist/lib/auth.js +1 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/compiler-floor.d.ts +1 -1
- package/dist/lib/compiler-floor.js +1 -1
- package/dist/lib/file-loader.js +2 -2
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +16 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.js +16 -0
- package/dist/lib/file-writer.test.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +3 -3
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/prepare-output.test.js +1 -1
- package/dist/lib/prepare-output.test.js.map +1 -1
- package/dist/lib/schema-sync/index.js +1 -1
- package/dist/lib/schema-sync/index.test.js +1 -1
- package/dist/lib/schema-sync/index.test.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +5 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/lib/wrangler-resources.test.js +6 -0
- package/dist/lib/wrangler-resources.test.js.map +1 -1
- package/dist/skill/SKILL.md +24 -9
- package/dist/skill/docs/api/crud.md +7 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/changelog/index.md +27 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +11 -5
- package/dist/skill/docs/configure/providers.md +6 -3
- package/dist/skill/docs/configure/single-tenant.md +7 -3
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +10 -0
- package/dist/skill/docs/define/actions/defining.md +35 -7
- package/dist/skill/docs/define/actions/index.md +1 -1
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +68 -21
- package/dist/skill/docs/define/areas.md +1 -1
- package/dist/skill/docs/define/diagnostics.md +1 -0
- package/dist/skill/docs/define/encryption.md +1 -1
- package/dist/skill/docs/define/feature.md +17 -8
- package/dist/skill/docs/define/firewall.md +2 -0
- package/dist/skill/docs/define/guards.md +27 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/relationships.md +7 -0
- package/dist/skill/docs/define/schema.md +44 -14
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- package/dist/skill/docs/define/triggers.md +14 -3
- package/dist/skill/docs/define/views.md +33 -0
- package/dist/skill/docs/index.md +2 -2
- package/dist/skill/docs/platform/auth/api-keys.md +2 -2
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +15 -3
- package/dist/skill/docs/platform/database/neon.md +4 -4
- package/dist/skill/docs/platform/email/index.md +1 -1
- package/dist/skill/docs/platform/queues/handlers.md +1 -1
- package/dist/skill/docs/platform/queues/using-queues.md +1 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +6 -4
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/index.md +3 -3
- package/dist/skill/docs/platform/storage/r2.md +87 -37
- package/dist/skill/docs/platform/storage/using-r2.md +99 -19
- package/dist/skill/docs/platform/webhooks/inbound.md +40 -0
- package/dist/skill/docs/start/deploy-browser.md +40 -45
- package/dist/skill/docs/start/deploy-owner-access.md +60 -52
- package/dist/skill/docs/start/deploy.md +4 -4
- package/dist/skill/docs/start/first-api.md +2 -2
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- package/dist/skill/docs/start/patterns.md +17 -2
- package/dist/skill/docs/start/quickstart.md +3 -3
- package/dist/skill/docs/start/template-blog.md +2 -2
- package/dist/skill/docs/start/template-cloudflare.md +3 -3
- package/dist/skill/docs/start/template-empty.md +1 -1
- package/dist/skill/docs/start/templates.md +1 -1
- package/dist/skill/docs/tooling/claude-skill.md +1 -1
- package/dist/skill/docs/tooling/cli.md +21 -16
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/dist/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
- package/dist/skill/docs/tooling/output.md +23 -2
- package/dist/skill/docs/tooling/troubleshooting.md +1 -1
- package/dist/skill/docs/ui/account/customization.md +1 -1
- package/dist/skill/docs/ui/account/environment-variables.md +2 -2
- package/dist/skill/docs/ui/account/features/admin.md +1 -1
- package/dist/skill/docs/ui/account/features/api-keys.md +10 -8
- package/dist/skill/docs/ui/account/features/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +16 -11
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/hooks.md +2 -0
- package/dist/skill/docs/ui/account/index.md +10 -5
- package/dist/skill/docs/ui/account/with-quickback.md +2 -2
- package/dist/skill/docs/ui/admin/actions.md +97 -3
- package/dist/skill/docs/ui/admin/components.md +4 -6
- package/dist/skill/docs/ui/admin/connecting.md +15 -3
- package/dist/skill/docs/ui/admin/index.md +71 -6
- package/dist/skill/docs/ui/admin/inline-editing.md +38 -4
- package/dist/skill/docs/ui/admin/record-layouts.md +22 -21
- package/dist/skill/docs/ui/admin/schema-format.md +39 -2
- package/dist/skill/docs/ui/admin/schema-registry.md +107 -7
- package/dist/skill/docs/ui/admin/security.md +19 -4
- package/dist/skill/docs/ui/admin/table-views.md +59 -12
- package/package.json +1 -1
- package/src/cursor/quickback.mdc +1 -1
- package/src/skill/SKILL.md +24 -9
- package/src/skill/docs/api/crud.md +7 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/changelog/index.md +27 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +11 -5
- package/src/skill/docs/configure/providers.md +6 -3
- package/src/skill/docs/configure/single-tenant.md +7 -3
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +10 -0
- package/src/skill/docs/define/actions/defining.md +35 -7
- package/src/skill/docs/define/actions/index.md +1 -1
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +68 -21
- package/src/skill/docs/define/areas.md +1 -1
- package/src/skill/docs/define/diagnostics.md +1 -0
- package/src/skill/docs/define/encryption.md +1 -1
- package/src/skill/docs/define/feature.md +17 -8
- package/src/skill/docs/define/firewall.md +2 -0
- package/src/skill/docs/define/guards.md +27 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/relationships.md +7 -0
- package/src/skill/docs/define/schema.md +44 -14
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- package/src/skill/docs/define/triggers.md +14 -3
- package/src/skill/docs/define/views.md +33 -0
- package/src/skill/docs/index.md +2 -2
- package/src/skill/docs/platform/auth/api-keys.md +2 -2
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +15 -3
- package/src/skill/docs/platform/database/neon.md +4 -4
- package/src/skill/docs/platform/email/index.md +1 -1
- package/src/skill/docs/platform/queues/handlers.md +1 -1
- package/src/skill/docs/platform/queues/using-queues.md +1 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +6 -4
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/index.md +3 -3
- package/src/skill/docs/platform/storage/r2.md +87 -37
- package/src/skill/docs/platform/storage/using-r2.md +99 -19
- package/src/skill/docs/platform/webhooks/inbound.md +40 -0
- package/src/skill/docs/start/deploy-browser.md +40 -45
- package/src/skill/docs/start/deploy-owner-access.md +60 -52
- package/src/skill/docs/start/deploy.md +4 -4
- package/src/skill/docs/start/first-api.md +2 -2
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- package/src/skill/docs/start/patterns.md +17 -2
- package/src/skill/docs/start/quickstart.md +3 -3
- package/src/skill/docs/start/template-blog.md +2 -2
- package/src/skill/docs/start/template-cloudflare.md +3 -3
- package/src/skill/docs/start/template-empty.md +1 -1
- package/src/skill/docs/start/templates.md +1 -1
- package/src/skill/docs/tooling/claude-skill.md +1 -1
- package/src/skill/docs/tooling/cli.md +21 -16
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +5 -3
- package/src/skill/docs/tooling/cloud-compiler/index.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +74 -1
- package/src/skill/docs/tooling/output.md +23 -2
- package/src/skill/docs/tooling/troubleshooting.md +1 -1
- package/src/skill/docs/ui/account/customization.md +1 -1
- package/src/skill/docs/ui/account/environment-variables.md +2 -2
- package/src/skill/docs/ui/account/features/admin.md +1 -1
- package/src/skill/docs/ui/account/features/api-keys.md +10 -8
- package/src/skill/docs/ui/account/features/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +16 -11
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/hooks.md +2 -0
- package/src/skill/docs/ui/account/index.md +10 -5
- package/src/skill/docs/ui/account/with-quickback.md +2 -2
- package/src/skill/docs/ui/admin/actions.md +97 -3
- package/src/skill/docs/ui/admin/components.md +4 -6
- package/src/skill/docs/ui/admin/connecting.md +15 -3
- package/src/skill/docs/ui/admin/index.md +71 -6
- package/src/skill/docs/ui/admin/inline-editing.md +38 -4
- package/src/skill/docs/ui/admin/record-layouts.md +22 -21
- package/src/skill/docs/ui/admin/schema-format.md +39 -2
- package/src/skill/docs/ui/admin/schema-registry.md +107 -7
- package/src/skill/docs/ui/admin/security.md +19 -4
- package/src/skill/docs/ui/admin/table-views.md +59 -12
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
18
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
80
|
-
|
|
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'
|
|
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
|
|
104
|
-
- Admins
|
|
105
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|