@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
|
@@ -82,7 +82,27 @@ A few mechanics to know:
|
|
|
82
82
|
- **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
|
|
83
83
|
- **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
|
|
84
84
|
- **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
|
|
85
|
-
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path.
|
|
85
|
+
- **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`. An FK declares a *pointer*, not ownership — when the child rows are a **composition** of one root (junctions, phones/emails, line items), also declare [`owns`](/define/changesets) on the root to generate the atomic aggregate write path. `other` must be a **feature table in the same database**.
|
|
86
|
+
|
|
87
|
+
> **Never FK Better Auth tables**
|
|
88
|
+
>
|
|
89
|
+
> `.references(() => users.id)` (or `user`, `organization`, `member`, `session`) on a feature column is illegal. Those tables live in `AUTH_DB`; your features live in `DB`. SQLite cannot FK across D1 databases, and drizzle-kit fails generating features migrations:
|
|
90
|
+
>
|
|
91
|
+
> `Critical command failed: Generate features database migrations`
|
|
92
|
+
>
|
|
93
|
+
> A Start chat compile (`complete=false`) still succeeds — it never runs drizzle-kit. The complete compile (`complete=true` — Generated Backend, or `quickback compile`) is the first time that command runs.
|
|
94
|
+
>
|
|
95
|
+
> A junction's `userId` is a **plain text** Better Auth id, not a SQL FK:
|
|
96
|
+
>
|
|
97
|
+
> {/* doc-compile: skip — two-column excerpt, not a host feature */}
|
|
98
|
+
> ```typescript
|
|
99
|
+
> userId: q.text().required(), // ctx.userId — no .references()
|
|
100
|
+
> channelId: q.text().required().references(() => channels.id, { onDelete: 'cascade' }),
|
|
101
|
+
> ```
|
|
102
|
+
>
|
|
103
|
+
> `authz.relationships` `subject: { column: 'userId', equals: 'ctx.userId' }` does not need, and must not create, a SQL FK. See [Relationships](/define/relationships). To query Better Auth tables, use `c.get("authDb")` from an action — see [Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
104
|
+
|
|
105
|
+
|
|
86
106
|
- **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
|
|
87
107
|
|
|
88
108
|
### Column Types
|
|
@@ -101,6 +121,8 @@ A few mechanics to know:
|
|
|
101
121
|
| `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
|
|
102
122
|
| `q.stamp({ fromScope, claim })` | `text(...).notNull()` (nullable with `optional: true`) | `z.string().optional()` |
|
|
103
123
|
|
|
124
|
+
In request bodies a column that is not `.required()` is `.optional().nullable()` — omit it to leave it untouched, send `null` to clear it. `""` is not a blank: it is validated like any other value. `.required()` columns never accept `null`.
|
|
125
|
+
|
|
104
126
|
`q.text()` and `q.url()` accept either a SQL-name string or an options object — `q.text({ sqlName: 'org_id', maxLength: 80 })`. `maxLength` adds `z.string().max(n)` at the validation edge; the SQL column stays `text` (D1 ignores `VARCHAR(n)` length anyway).
|
|
105
127
|
|
|
106
128
|
`q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
|
|
@@ -716,27 +738,35 @@ For LIST endpoints, labels are batch-resolved efficiently — one query per FK c
|
|
|
716
738
|
|
|
717
739
|
## References
|
|
718
740
|
|
|
719
|
-
|
|
741
|
+
Declare every feature-table foreign key in the schema with `.references()`.
|
|
742
|
+
That one declaration creates the database relationship and gives the API,
|
|
743
|
+
schema registry, and CMS the same target for label resolution and
|
|
744
|
+
selector/typeahead controls:
|
|
720
745
|
|
|
721
|
-
{/* doc-compile: skip —
|
|
746
|
+
{/* doc-compile: skip — cross-table column excerpt; the complete table forms appear at the top of this page. */}
|
|
722
747
|
```typescript
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
referredById: "candidate",
|
|
728
|
-
},
|
|
729
|
-
// ... firewall, guards, crud
|
|
748
|
+
const applications = q.table("applications", {
|
|
749
|
+
id: q.id(),
|
|
750
|
+
candidateId: q.text().required().references(() => candidates.id),
|
|
751
|
+
jobId: q.text().required().references(() => jobs.id),
|
|
730
752
|
});
|
|
731
753
|
```
|
|
732
754
|
|
|
733
|
-
|
|
755
|
+
Do this even when a column name appears obvious, such as `sessionId` beside a
|
|
756
|
+
`sessions` table. A matching `*Id` name is a useful compiler suggestion when a
|
|
757
|
+
relationship might be missing; it is not enough evidence to silently invent
|
|
758
|
+
one. CMS-ready schemas state the relationship explicitly.
|
|
734
759
|
|
|
735
|
-
|
|
760
|
+
The legacy resource-level `references: { vendorId: "contact" }` map can override
|
|
761
|
+
schema-registry target metadata for an alias, but it does not create a database
|
|
762
|
+
foreign key. Prefer `.references(() => contacts.id)` whenever the target is a
|
|
763
|
+
feature table in the same database. Do **not** add `.references()` for Better
|
|
764
|
+
Auth ids (`userId`, `organizationId`, `memberId`, or auth `sessionId`): those
|
|
765
|
+
rows live in `AUTH_DB`, outside the feature database.
|
|
736
766
|
|
|
737
767
|
## Input Hints
|
|
738
768
|
|
|
739
|
-
Control how the CMS renders form inputs for specific columns. By default the CMS infers
|
|
769
|
+
Control how the CMS renders form inputs for specific columns. By default the CMS infers the control from the column itself — `q.timestamp()` → date-time picker, `q.bool()` → checkbox, `q.int()` → number, `q.enum()` → select, `q.url()` → URL input, `q.json()` → textarea, and name patterns for plain text (`*Url`, `*Notes`, `email`). The registry carries the q column `kind`, so this works on SQLite too, where every timestamp is `text` at the SQL layer. `inputHints` overrides the inference:
|
|
740
770
|
|
|
741
771
|
{/* doc-compile: skip — one-key excerpt: the fence is the `inputHints` map only, with firewall/guards/crud already elided to `// ...`. This page's whole-file examples are the `feature()` and `q.table()`+`defineTable()` forms at the top, which the gate does compile. */}
|
|
742
772
|
```typescript
|
|
@@ -770,7 +800,7 @@ export default defineTable(jobs, {
|
|
|
770
800
|
| `time` | Time picker |
|
|
771
801
|
| `currency` | Currency input with formatting |
|
|
772
802
|
|
|
773
|
-
Input hints are emitted in the schema registry as `inputHints` on the table metadata, and the CMS reads them to render the appropriate form controls.
|
|
803
|
+
Input hints are emitted in the schema registry as `inputHints` on the table metadata, and the CMS reads them to render the appropriate form controls. The bundled CMS form renders `richtext`, `select`, `checkbox`, `textarea`, `date`, `datetime`, `currency`, `number`, `email`, `url`, and `text` today; any other hint falls back to the inferred control.
|
|
774
804
|
|
|
775
805
|
### Rich Text Example
|
|
776
806
|
|
|
@@ -124,7 +124,7 @@ the stored bytes are, the pillars govern who reaches them.
|
|
|
124
124
|
## Where this is enforced
|
|
125
125
|
|
|
126
126
|
Everything on this page is a **compile-time** decision. The pillars are declared in your
|
|
127
|
-
feature files, checked for coherence when you run `quickback
|
|
127
|
+
feature files, checked for coherence when you run `quickback build`, and emitted as
|
|
128
128
|
generated middleware and query builders. There is no runtime policy engine to
|
|
129
129
|
misconfigure and no rules to keep in sync by hand — if a policy is incoherent, the
|
|
130
130
|
compile fails.
|
|
@@ -31,6 +31,13 @@ export const episodes = q.table('episodes', {
|
|
|
31
31
|
});
|
|
32
32
|
|
|
33
33
|
export default defineTable(episodes, {
|
|
34
|
+
guards: {
|
|
35
|
+
createable: ["title"],
|
|
36
|
+
updatable: ["title"],
|
|
37
|
+
protected: {
|
|
38
|
+
isPublished: ["publish", "revertToDraft"],
|
|
39
|
+
},
|
|
40
|
+
},
|
|
34
41
|
transitions: {
|
|
35
42
|
publish: { field: "isPublished", from: false, to: true, access: { roles: ["admin+"] } },
|
|
36
43
|
revertToDraft: { field: "isPublished", from: true, to: false, access: { roles: ["admin+"] } },
|
|
@@ -38,6 +45,23 @@ export default defineTable(episodes, {
|
|
|
38
45
|
});
|
|
39
46
|
```
|
|
40
47
|
|
|
48
|
+
`isPublished` has a schema default and is absent from both `createable` and
|
|
49
|
+
`updatable`. The transition names are its only writers. A workflow-owned field
|
|
50
|
+
cannot also be directly updatable; listing it in both `updatable` and
|
|
51
|
+
`protected` is a compile error and would undermine the state machine.
|
|
52
|
+
|
|
53
|
+
> **Table-level transitions need a fixed `to`**
|
|
54
|
+
>
|
|
55
|
+
> Every `transitions.<name>` entry must name a literal target: `to` with either
|
|
56
|
+
> `from` (scalar or array) or a `fromTo` map. A target that varies per call
|
|
57
|
+
> (`via: "nextStatus"` — read from the action's input) is **not** accepted at
|
|
58
|
+
> table level; the compile fails with
|
|
59
|
+
> `[quickback:transitions] <feature>/<table> transitions.<name>: table-level fromTo transitions need a fixed to (via-style input targets require a hand-written action)`.
|
|
60
|
+
> Write that one as `actions/<name>.ts` with `transition: { field, via, fromTo }`
|
|
61
|
+
> (see [Transition (state-machine policy)](#transition-state-machine-policy)) —
|
|
62
|
+
> or split it into one fixed-target entry per step (`toScreening`, `toInterview`, …).
|
|
63
|
+
|
|
64
|
+
|
|
41
65
|
The generated actions mount exactly where an authored file would
|
|
42
66
|
(`POST /episodes/:id/publish`, operationId `episodesPublish`, same MCP tool
|
|
43
67
|
name), ride the same OpenAPI/security-contract pipeline, and delete cleanly:
|
|
@@ -164,8 +188,7 @@ current state. Without it, an `advance` action whose input enum allows
|
|
|
164
188
|
```typescript
|
|
165
189
|
// features/applications/actions/advance.ts
|
|
166
190
|
import { z } from "zod";
|
|
167
|
-
import { defineAction } from "../.quickback/define-action";
|
|
168
|
-
import { applications } from "../applications";
|
|
191
|
+
import { defineAction, applications } from "../.quickback/define-action";
|
|
169
192
|
|
|
170
193
|
export default defineAction({
|
|
171
194
|
description: "Move an application forward in the pipeline.",
|
|
@@ -187,8 +210,7 @@ export default defineAction({
|
|
|
187
210
|
```typescript
|
|
188
211
|
// features/applications/actions/hire.ts
|
|
189
212
|
import { z } from "zod";
|
|
190
|
-
import { defineAction } from "../.quickback/define-action";
|
|
191
|
-
import { applications } from "../applications";
|
|
213
|
+
import { defineAction, applications } from "../.quickback/define-action";
|
|
192
214
|
|
|
193
215
|
export default defineAction({
|
|
194
216
|
description: "Finalize an offer.",
|
|
@@ -243,3 +265,12 @@ The same 409 code is used when an `access.record` predicate (without
|
|
|
243
265
|
`transition`) fails — for example `record: { status: { equals: "pending" } }`
|
|
244
266
|
called against a paid invoice now returns 409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`,
|
|
245
267
|
not a misleading 403.
|
|
268
|
+
|
|
269
|
+
## In the CMS
|
|
270
|
+
|
|
271
|
+
The schema registry carries each action's `field`, `fromTo`, `to`/`via`,
|
|
272
|
+
literal `guard`, and `idempotent`. The CMS evaluates them against the row and
|
|
273
|
+
**hides** any transition the record's current state cannot take — no
|
|
274
|
+
`fromTo[current]` entry admits the target, the row is already in the `to`
|
|
275
|
+
state, or a literal guard fails. Nothing extra to declare; see
|
|
276
|
+
[CMS Actions → Transition State](/ui/admin/actions#transition-state).
|
|
@@ -106,6 +106,15 @@ Live Views, with full application context:
|
|
|
106
106
|
handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) => { ... }
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
+
The `db` a handler receives is the **features** database. There is no `c` and
|
|
110
|
+
no `authDb`. Prefer `ctx.userId`, `ctx.activeOrgId`, `ctx.roles`, and
|
|
111
|
+
`ctx.userRole` for the acting user.
|
|
112
|
+
|
|
113
|
+
Do **not** import `../../auth/schema` from the table file to reach AUTH_DB —
|
|
114
|
+
that import used to survive compile and then fail package-mode wrangler with
|
|
115
|
+
`Could not resolve`. Checking that another user is an org member belongs in
|
|
116
|
+
an [action](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
117
|
+
|
|
109
118
|
- **`before*` hooks are synchronous.** Return a partial object to merge
|
|
110
119
|
into the write payload, or throw to reject — the write never executes and
|
|
111
120
|
the request gets a structured `TRIGGER_REJECTED` (422) error. Audit
|
|
@@ -116,9 +125,11 @@ handler: ({ table, op, values /* before */, row /* after */, ctx, db, env }) =>
|
|
|
116
125
|
`TRIGGER_AFTER_FAILED` (500) with `details.committed: true` — the row was
|
|
117
126
|
already persisted (no transactions on D1), so clients must not blind-retry.
|
|
118
127
|
- Handlers must be **inline arrow/function expressions**. Imports they
|
|
119
|
-
reference are hoisted into the generated registry
|
|
120
|
-
|
|
121
|
-
as
|
|
128
|
+
reference are hoisted into the generated registry (`src/lib/trigger-hooks.ts`)
|
|
129
|
+
with relative paths rewritten from the table file — including dynamic
|
|
130
|
+
`import("…")` inside the handler. Write them as they resolve next to the
|
|
131
|
+
table. Each table's drizzle object is auto-imported under its authored
|
|
132
|
+
name — so this works as written:
|
|
122
133
|
|
|
123
134
|
```typescript
|
|
124
135
|
import { eq } from 'drizzle-orm';
|
|
@@ -99,6 +99,39 @@ returns `VIEW_REQUIRED` once views are declared.
|
|
|
99
99
|
|
|
100
100
|
Views support the same query parameters as the list endpoint:
|
|
101
101
|
|
|
102
|
+
Declare a view's query surface explicitly with `query.filterable`,
|
|
103
|
+
`query.searchable`, and `query.sortable`. Those allowlists are authoritative
|
|
104
|
+
for that view: a field listed there does **not** also need `.filterable()` or
|
|
105
|
+
`.searchable()` on its column definition. Column-level modifiers configure
|
|
106
|
+
ordinary CRUD reads and provide helpful defaults when the compiler generates a
|
|
107
|
+
surface; an explicitly configured view does not require the declaration twice.
|
|
108
|
+
On the ordinary CRUD collection endpoint, the column modifiers remain the
|
|
109
|
+
declaration: only columns marked `.filterable(...)` accept filters, and
|
|
110
|
+
`.searchable()` determines the default cross-column search set. Pagination is
|
|
111
|
+
independent of these allowlists and remains available on both CRUD reads and
|
|
112
|
+
named views.
|
|
113
|
+
|
|
114
|
+
```typescript
|
|
115
|
+
columns: {
|
|
116
|
+
candidateId: q.text().required(), // no column-level query modifier needed
|
|
117
|
+
stage: q.enum(['applied', 'interview', 'offer']).required(),
|
|
118
|
+
},
|
|
119
|
+
read: {
|
|
120
|
+
views: {
|
|
121
|
+
pipeline: {
|
|
122
|
+
fields: ['id', 'candidateId', 'stage'],
|
|
123
|
+
query: {
|
|
124
|
+
filterable: ['stage'],
|
|
125
|
+
searchable: ['candidateId'],
|
|
126
|
+
},
|
|
127
|
+
},
|
|
128
|
+
},
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Unknown columns, encrypted columns, and masked-column query restrictions are
|
|
133
|
+
still validated normally.
|
|
134
|
+
|
|
102
135
|
### Pagination
|
|
103
136
|
|
|
104
137
|
| Parameter | Description | Default | Max |
|
package/dist/skill/docs/index.md
CHANGED
|
@@ -9,7 +9,7 @@ mkdir my-app && cd my-app
|
|
|
9
9
|
npx @quickback-dev/cli start
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
`start` is interactive — it asks for a template, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; you can finish later with `quickback
|
|
12
|
+
`start` is interactive — it asks for a template, scaffolds the project on disk, and only prompts for an account just before compiling. If you cancel at the login prompt the scaffold stays put; you can finish later with `quickback build`.
|
|
13
13
|
|
|
14
14
|
Prefer scripting?
|
|
15
15
|
|
|
@@ -17,7 +17,7 @@ Prefer scripting?
|
|
|
17
17
|
npm install -g @quickback-dev/cli
|
|
18
18
|
quickback create cloudflare my-app
|
|
19
19
|
cd my-app
|
|
20
|
-
quickback
|
|
20
|
+
quickback build
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
## How it works
|
|
@@ -4,12 +4,12 @@ API keys provide programmatic access for CI/CD pipelines, scripts, and server-to
|
|
|
4
4
|
|
|
5
5
|
## Creating API Keys
|
|
6
6
|
|
|
7
|
-
Create API keys from
|
|
7
|
+
Create API keys from [Account UI](/ui/account/features/api-keys) (`/api-keys`, linked from profile). Each key is owned by you and scoped to an organization.
|
|
8
8
|
|
|
9
9
|
## Usage
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
|
-
QUICKBACK_API_KEY=your_api_key quickback
|
|
12
|
+
QUICKBACK_API_KEY=your_api_key quickback build
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
API keys are validated by the same `/internal/validate` endpoint as session tokens. See [Authentication](/tooling/cloud-compiler/authentication) for details.
|
|
@@ -33,6 +33,43 @@ app.get('/api/me', async (c) => {
|
|
|
33
33
|
|
|
34
34
|
`ctx` also carries `authMethod` (`'session' | 'jwt' | 'api-key' | 'oauth' | 'principal'`), `userRole` (the global user-table role), `activeTeamId`, and `scope`. In action and CRUD handlers this same object arrives as the `ctx` argument — you rarely call `c.get('ctx')` directly.
|
|
35
35
|
|
|
36
|
+
## Application Profiles
|
|
37
|
+
|
|
38
|
+
Treat the Better Auth user row as login identity, not automatically as the
|
|
39
|
+
application's complete client or customer model. Before defining feature
|
|
40
|
+
tables, decide whether signed-in people need domain data beyond the identity
|
|
41
|
+
already available on `ctx.user`—for example a customer number, onboarding
|
|
42
|
+
state, preferences, billing metadata, clinical details, or relationships that
|
|
43
|
+
other feature records must reference.
|
|
44
|
+
|
|
45
|
+
If the auth identity fields are enough, use `ctx.userId` / `ctx.user` directly
|
|
46
|
+
and do not create an empty duplicate profile. If the product needs domain data
|
|
47
|
+
or relationships, create a first-class feature resource such as `customers`,
|
|
48
|
+
`clientProfiles`, or `patientProfiles`. Give it its own feature-table primary
|
|
49
|
+
key and normal access, firewall, masking, and guard rules.
|
|
50
|
+
|
|
51
|
+
Use `userId: q.text().required().index()` for the basic link to the Better Auth
|
|
52
|
+
identity. Quickback emits the physical `user_id` column. Treat it as a plain
|
|
53
|
+
text **logical foreign key**: a self-create/bootstrap action derives it from
|
|
54
|
+
`ctx.userId`, and generic clients must not supply or update it through
|
|
55
|
+
`guards.createable` / `guards.updatable`. If the model permits one profile per
|
|
56
|
+
identity globally, add `unique: [{ columns: ["userId"] }]`; if it permits one
|
|
57
|
+
per organization, use `unique: [{ columns: ["organizationId", "userId"] }]`
|
|
58
|
+
instead. Declare explicitly when `userId` is also the row-ownership firewall
|
|
59
|
+
column rather than relying on its name.
|
|
60
|
+
|
|
61
|
+
Do not write `.references(() => user.id)` or `.references(() => users.id)` on
|
|
62
|
+
that link. With the default split-D1 provider, Better Auth lives in `AUTH_DB`
|
|
63
|
+
and feature resources live in `DB`, so SQLite cannot enforce a cross-database
|
|
64
|
+
foreign key. A provider may place both stores in one physical database, but the
|
|
65
|
+
auth schema remains compiler-owned rather than an authored feature-table
|
|
66
|
+
import; keeping this link logical makes the definition portable. Other feature
|
|
67
|
+
tables should use a real feature-database FK such as
|
|
68
|
+
`profileId: q.text().required().references(() => profiles.id)` so the CMS can
|
|
69
|
+
resolve the profile label. See [Schema → References](/define/schema#references),
|
|
70
|
+
[Firewall → ownerId vs userId](/define/firewall#ownerid-vs-userid), and
|
|
71
|
+
[Start patterns → Referencing users](/start/patterns).
|
|
72
|
+
|
|
36
73
|
## Organization Context
|
|
37
74
|
|
|
38
75
|
When organizations are enabled, the active organization is on the auth context as `activeOrgId`:
|
|
@@ -22,7 +22,7 @@ Quickback generates separate D1 databases for different concerns:
|
|
|
22
22
|
|
|
23
23
|
| Database | Binding | Purpose |
|
|
24
24
|
|----------|---------|---------|
|
|
25
|
-
| `AUTH_DB` | `AUTH_DB` | Better Auth tables (user
|
|
25
|
+
| `AUTH_DB` | `AUTH_DB` | Better Auth tables (`user`, `session`, `account`, `organization`, `member`) |
|
|
26
26
|
| `DB` | `DB` | Your application data |
|
|
27
27
|
| `FILES_DB` | `FILES_DB` | File metadata for R2 uploads |
|
|
28
28
|
| `WEBHOOKS_DB` | `WEBHOOKS_DB` | Webhook delivery tracking |
|
|
@@ -32,6 +32,18 @@ This separation provides:
|
|
|
32
32
|
- **Isolation** - Auth schema changes don't touch your data
|
|
33
33
|
- **Clarity** - Clear ownership of each database
|
|
34
34
|
|
|
35
|
+
SQLite foreign keys cannot cross those databases. Feature columns must never
|
|
36
|
+
`.references()` Better Auth tables (`user` / `users` / `organization` /
|
|
37
|
+
`member`). Store a Better Auth id as plain text (`userId: q.text().required()`).
|
|
38
|
+
A `.references(() => users.id)` on a feature table makes deploy fail with
|
|
39
|
+
`Critical command failed: Generate features database migrations`. See
|
|
40
|
+
[Schema → References](/define/schema).
|
|
41
|
+
|
|
42
|
+
The scoped feature `db` never includes those tables — query them from an
|
|
43
|
+
action with `c.get("authDb")`, not from a trigger. On D1 the membership table
|
|
44
|
+
is `member`, not `organization_membership`. See
|
|
45
|
+
[Scoped DB](/define/actions/scoped-db#reaching-better-auth-tables-authdb).
|
|
46
|
+
|
|
35
47
|
## Drizzle ORM Integration
|
|
36
48
|
|
|
37
49
|
Quickback uses [Drizzle ORM](https://orm.drizzle.team/) for type-safe database access:
|
|
@@ -81,7 +93,7 @@ Quickback generates migrations automatically at compile time based on your schem
|
|
|
81
93
|
|
|
82
94
|
```bash
|
|
83
95
|
# Compile your project (generates migrations)
|
|
84
|
-
quickback
|
|
96
|
+
quickback build
|
|
85
97
|
|
|
86
98
|
# Apply migrations locally
|
|
87
99
|
wrangler d1 migrations apply DB --local
|
|
@@ -92,7 +104,7 @@ wrangler d1 migrations apply DB --remote
|
|
|
92
104
|
|
|
93
105
|
Migration files are generated in `quickback/drizzle/` and version-controlled with your code. You never need to manually generate migrations—just define your schema and compile.
|
|
94
106
|
|
|
95
|
-
Generation runs locally: `quickback
|
|
107
|
+
Generation runs locally: `quickback build` invokes your project's own
|
|
96
108
|
`drizzle-kit` against migration state that never leaves your machine. Note that
|
|
97
109
|
generating a migration is not the same as applying one — `_journal.json` records
|
|
98
110
|
which migration files *exist*, while D1's own `d1_migrations` table records which
|
|
@@ -359,11 +359,11 @@ connection string from the Hyperdrive configuration identified by `id`.
|
|
|
359
359
|
## Better Auth schema generation
|
|
360
360
|
|
|
361
361
|
`src/auth/schema.ts` is a compiler-owned artifact derived with the Better Auth
|
|
362
|
-
CLI during `quickback
|
|
362
|
+
CLI during `quickback build`. The generated `build` script is deliberately
|
|
363
363
|
read-only with respect to generated source:
|
|
364
364
|
|
|
365
365
|
```bash
|
|
366
|
-
quickback
|
|
366
|
+
quickback build # regenerates src/auth/schema.ts and the project output
|
|
367
367
|
npm run build # runs tsc only; does not rewrite generated files
|
|
368
368
|
```
|
|
369
369
|
|
|
@@ -382,7 +382,7 @@ generated `package.json` — that's the Better Auth CLI package (the
|
|
|
382
382
|
The qualifier script adjusts the CLI output for Postgres schema placement.
|
|
383
383
|
`auth:schema` produces the intermediate Better Auth output and may remove
|
|
384
384
|
Quickback's generated-file envelope. Do not commit that intermediate file;
|
|
385
|
-
rerun `quickback
|
|
385
|
+
rerun `quickback build` to restore the canonical project bytes. Don't
|
|
386
386
|
hand-edit `src/auth/schema.ts`.
|
|
387
387
|
|
|
388
388
|
Recompiling also replaces previously generated `package.json` lifecycle
|
|
@@ -397,7 +397,7 @@ Drizzle journal covers auth tables, feature tables, indexes, FK/cascade
|
|
|
397
397
|
semantics, and the RLS layer:
|
|
398
398
|
|
|
399
399
|
```bash
|
|
400
|
-
quickback
|
|
400
|
+
quickback build # generates migrations under quickback/drizzle/
|
|
401
401
|
npm run db:migrate # applies schema AND the RLS layer, in order
|
|
402
402
|
```
|
|
403
403
|
|
|
@@ -59,7 +59,7 @@ Two `../` — up from `services/email/` to `quickback/`, then down into `feature
|
|
|
59
59
|
## What the compiler emits
|
|
60
60
|
|
|
61
61
|
1. **`deliverInboundEmail(message, env)`** in `src/lib/email.ts` — the shared dispatcher.
|
|
62
|
-
2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback
|
|
62
|
+
2. **`email(cfMessage, env, ctx)`** on the Worker default export — Cloudflare adapter. Regenerated on every `quickback build`.
|
|
63
63
|
3. **No wrangler inbound binding.** Cloudflare: configure Email Routing in the dashboard. SES: Receipt rule + S3 + SNS; call `deliverInboundEmail` with the fetched `.eml`.
|
|
64
64
|
4. The existing outbound `[[send_email]]` binding (Cloudflare) / SES plugin (aws-ses) is unchanged.
|
|
65
65
|
|
|
@@ -278,10 +278,12 @@ as a normal `postgres_changes` frame on the table's room.
|
|
|
278
278
|
"data": { "eventId": "…", "documentId": "…" } }
|
|
279
279
|
```
|
|
280
280
|
|
|
281
|
-
The bundled CMS
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
281
|
+
The bundled CMS and Account SPAs consume these envelopes as-is:
|
|
282
|
+
match on `qbframe`, read the row from `data`, and (for live views) the
|
|
283
|
+
monotonic seq from `qbseq`. The full channel/message catalog ships as
|
|
284
|
+
`GET /asyncapi.json` (AsyncAPI 3.0), served under the same auth gating as
|
|
285
|
+
`/openapi.json`. Any project with realtime or webhooks serves it, and it
|
|
286
|
+
documents the CloudEvents envelopes above.
|
|
285
287
|
|
|
286
288
|
## Cloudflare Only
|
|
287
289
|
|
|
@@ -41,7 +41,7 @@ Two `../` — up from `services/schedules/` to `quickback/`, then down into `fea
|
|
|
41
41
|
|
|
42
42
|
1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
|
|
43
43
|
2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules.
|
|
44
|
-
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback
|
|
44
|
+
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback build`, so there's nothing to hand-maintain.
|
|
45
45
|
|
|
46
46
|
## Execute context
|
|
47
47
|
|
|
@@ -7,11 +7,11 @@ The Quickback Stack uses Cloudflare's storage primitives for different use cases
|
|
|
7
7
|
| Service | Use Case | Pages |
|
|
8
8
|
|---------|----------|-------|
|
|
9
9
|
| **KV** | Sessions, caching, rate limiting | [Setup](/platform/storage/kv) · [Usage](/platform/storage/using-kv) |
|
|
10
|
-
| **R2** |
|
|
10
|
+
| **R2** | Hosted file bytes (listing photos, avatars, attachments) | [Setup](/platform/storage/r2) · [Usage](/platform/storage/using-r2) |
|
|
11
11
|
|
|
12
12
|
## Getting Started
|
|
13
13
|
|
|
14
14
|
- **[KV Setup](/platform/storage/kv)** — Namespace and bindings configuration
|
|
15
15
|
- **[Using KV](/platform/storage/using-kv)** — Sessions, caching, rate limiting
|
|
16
|
-
- **[R2 Setup](/platform/storage/r2)** —
|
|
17
|
-
- **[Using R2](/platform/storage/using-r2)** —
|
|
16
|
+
- **[R2 Setup](/platform/storage/r2)** — Public vs signed reads, buckets, bindings
|
|
17
|
+
- **[Using R2](/platform/storage/using-r2)** — URL fields, public buckets, signed uploads
|