@quickback-dev/cli 0.66.1 → 0.66.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +804 -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/skill/SKILL.md +6 -6
- package/dist/skill/docs/api/actions.md +27 -3
- package/dist/skill/docs/api/batch-operations.md +4 -0
- package/dist/skill/docs/api/crud.md +64 -0
- package/dist/skill/docs/api/index.md +1 -1
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +19 -2
- package/dist/skill/docs/changelog/index.md +33 -1
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/index.md +8 -3
- package/dist/skill/docs/configure/providers.md +3 -0
- package/dist/skill/docs/configure/variables.md +3 -3
- package/dist/skill/docs/define/access.md +7 -0
- package/dist/skill/docs/define/actions/defining.md +39 -8
- package/dist/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/dist/skill/docs/define/actions/scoped-db.md +46 -16
- 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 +14 -7
- package/dist/skill/docs/define/guards.md +34 -3
- package/dist/skill/docs/define/schema.md +29 -17
- package/dist/skill/docs/define/security.md +1 -1
- package/dist/skill/docs/define/transitions.md +35 -4
- 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 +1 -1
- package/dist/skill/docs/platform/auth/using-auth.md +37 -0
- package/dist/skill/docs/platform/database/d1.md +2 -2
- 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/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 +39 -44
- package/dist/skill/docs/start/deploy-owner-access.md +28 -19
- package/dist/skill/docs/start/deploy.md +2 -2
- package/dist/skill/docs/start/first-api.md +1 -1
- package/dist/skill/docs/start/hand-crafted.md +3 -3
- package/dist/skill/docs/start/index.md +3 -3
- 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 +2 -2
- 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 +40 -19
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- 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 +47 -2
- package/dist/skill/docs/tooling/output.md +32 -2
- package/dist/skill/docs/tooling/troubleshooting.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/avatars.md +24 -8
- package/dist/skill/docs/ui/account/features/index.md +9 -5
- package/dist/skill/docs/ui/account/features/organizations.md +3 -2
- package/dist/skill/docs/ui/account/index.md +3 -1
- package/dist/skill/docs/ui/account/with-quickback.md +1 -1
- 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 +6 -6
- package/src/skill/docs/api/actions.md +27 -3
- package/src/skill/docs/api/batch-operations.md +4 -0
- package/src/skill/docs/api/crud.md +64 -0
- package/src/skill/docs/api/index.md +1 -1
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +19 -2
- package/src/skill/docs/changelog/index.md +33 -1
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/index.md +8 -3
- package/src/skill/docs/configure/providers.md +3 -0
- package/src/skill/docs/configure/variables.md +3 -3
- package/src/skill/docs/define/access.md +7 -0
- package/src/skill/docs/define/actions/defining.md +39 -8
- package/src/skill/docs/define/actions/record-and-standalone.md +7 -4
- package/src/skill/docs/define/actions/scoped-db.md +46 -16
- 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 +14 -7
- package/src/skill/docs/define/guards.md +34 -3
- package/src/skill/docs/define/schema.md +29 -17
- package/src/skill/docs/define/security.md +1 -1
- package/src/skill/docs/define/transitions.md +35 -4
- 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 +1 -1
- package/src/skill/docs/platform/auth/using-auth.md +37 -0
- package/src/skill/docs/platform/database/d1.md +2 -2
- 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/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 +39 -44
- package/src/skill/docs/start/deploy-owner-access.md +28 -19
- package/src/skill/docs/start/deploy.md +2 -2
- package/src/skill/docs/start/first-api.md +1 -1
- package/src/skill/docs/start/hand-crafted.md +3 -3
- package/src/skill/docs/start/index.md +3 -3
- 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 +2 -2
- 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 +40 -19
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- 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 +47 -2
- package/src/skill/docs/tooling/output.md +32 -2
- package/src/skill/docs/tooling/troubleshooting.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/avatars.md +24 -8
- package/src/skill/docs/ui/account/features/index.md +9 -5
- package/src/skill/docs/ui/account/features/organizations.md +3 -2
- package/src/skill/docs/ui/account/index.md +3 -1
- package/src/skill/docs/ui/account/with-quickback.md +1 -1
- 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
|
@@ -157,11 +157,14 @@ Drizzle's relational query API — `db.query.<table>.findFirst()` /
|
|
|
157
157
|
relations config and your `where` alone, so the scoped wrapper cannot inject
|
|
158
158
|
the org/owner/team firewall into it. The scoped `db` therefore exposes the
|
|
159
159
|
Drizzle select builder—the path where Quickback can guarantee firewall
|
|
160
|
-
injection—and refuses `db.query.<table>` rather than returning unscoped rows
|
|
160
|
+
injection—and refuses `db.query.<table>` rather than returning unscoped rows.
|
|
161
|
+
The compiler rejects authored uses before code generation, including Start's
|
|
162
|
+
definition-validation build; the generated runtime guard remains as a
|
|
163
|
+
fail-closed backstop:
|
|
161
164
|
|
|
162
165
|
```typescript
|
|
163
166
|
async execute({ db, input }) {
|
|
164
|
-
// ❌
|
|
167
|
+
// ❌ Compile error: relational queries aren't org-scoped
|
|
165
168
|
const item = await db.query.media.findFirst({ where: eq(media.id, input.id) });
|
|
166
169
|
|
|
167
170
|
// ✅ Scoped builder — firewall conditions injected automatically
|
|
@@ -303,25 +306,53 @@ export default defineAction({
|
|
|
303
306
|
|
|
304
307
|
### Importing Tables
|
|
305
308
|
|
|
306
|
-
|
|
309
|
+
The action's own generated helper supplies `defineAction` and the tables owned
|
|
310
|
+
by that feature. It does not re-export tables from sibling features. Import a
|
|
311
|
+
cross-feature table from that feature's generated helper or generated table
|
|
312
|
+
module, and import Drizzle query operators through the generated project
|
|
313
|
+
`lib/q`:
|
|
307
314
|
|
|
315
|
+
{/* doc-compile: skip — demonstrates generated cross-feature helper and runtime paths; the isolated fence does not declare either feature. */}
|
|
308
316
|
```typescript
|
|
309
|
-
// features/
|
|
310
|
-
import {
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
import {
|
|
317
|
+
// features/waitlist/actions/promote.ts
|
|
318
|
+
import {
|
|
319
|
+
defineAction,
|
|
320
|
+
waitlistEntries,
|
|
321
|
+
} from "../.quickback/define-action";
|
|
322
|
+
import { reservations } from "../../reservations/.quickback/define-action";
|
|
323
|
+
import { q } from "../../../lib/q";
|
|
315
324
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
325
|
+
export default defineAction({
|
|
326
|
+
// ...input, access, and transition...
|
|
327
|
+
async execute({ db, record, whereRecord, now }) {
|
|
328
|
+
const existing = await db
|
|
329
|
+
.select()
|
|
330
|
+
.from(reservations)
|
|
331
|
+
.where(q.eq(reservations.waitlistEntryId, record.id));
|
|
332
|
+
|
|
333
|
+
await db
|
|
334
|
+
.update(waitlistEntries)
|
|
335
|
+
.set({ promotedAt: now })
|
|
336
|
+
.where(whereRecord!(waitlistEntries));
|
|
337
|
+
|
|
338
|
+
return existing;
|
|
339
|
+
},
|
|
340
|
+
});
|
|
319
341
|
```
|
|
320
342
|
|
|
321
343
|
**Path pattern from `features/{name}/actions/`:**
|
|
322
|
-
|
|
323
|
-
-
|
|
324
|
-
-
|
|
344
|
+
|
|
345
|
+
- Own feature helper: `../.quickback/define-action`
|
|
346
|
+
- Other feature helper: `../../{other-feature}/.quickback/define-action`
|
|
347
|
+
- Other generated table module: `../../{other-feature}/{table-file-name}`
|
|
348
|
+
- Generated project query helper: `../../../lib/q`
|
|
349
|
+
- Other generated lib files: `../../../lib/{module}` (for example,
|
|
350
|
+
`../../../lib/realtime` or `../../../lib/webhooks`)
|
|
351
|
+
|
|
352
|
+
Keep `defineAction` from the action's own feature: that helper binds `record`,
|
|
353
|
+
`whereRecord`, and `whereTransition`. Import only the external table from a
|
|
354
|
+
sibling feature. The waitlist/reservations names above are just the common
|
|
355
|
+
pattern; the rule applies to every cross-feature action.
|
|
325
356
|
|
|
326
357
|
### Executor Parameters
|
|
327
358
|
|
|
@@ -500,4 +531,3 @@ exports the Better Auth CLI's plural names: `users`, `organizations`,
|
|
|
500
531
|
| Action `execute` | `c.get("authDb")` | Import schema from `../../../auth/schema` |
|
|
501
532
|
| [Account hooks](/ui/account/hooks) | `{ authDb, authSchema }` injected | Use the injected namespace — do not invent a path to `auth/schema` |
|
|
502
533
|
| Trigger `handler:` | **none** | Args are `{ ctx, db, env }` — `db` is features only. There is no `c`. Prefer `ctx` for the acting user. Do not import `../../auth/schema` from the table file to reach AUTH_DB; that path used to compile and then fail package-mode wrangler. Check another user's membership in an action. |
|
|
503
|
-
|
|
@@ -553,7 +553,7 @@ Actions that keep their existing `import { defineAction } from '../.quickback/de
|
|
|
553
553
|
|
|
554
554
|
#### Compile-time advisory
|
|
555
555
|
|
|
556
|
-
When `quickback
|
|
556
|
+
When `quickback build` sees a namespace-scoped action still importing the generic helper, it emits a one-line advisory pointing at the narrowed path:
|
|
557
557
|
|
|
558
558
|
```text
|
|
559
559
|
[quickback:typing] action "feedMoments" in feature "feeds" lives under
|
|
@@ -58,6 +58,7 @@ compile.
|
|
|
58
58
|
| `AUTHZ_UNREACHABLE_ROLE` | warn | A scoped role declared under `authz.scopes` with **no grant profile** — it can authorize no read, action, or channel. Dead config, deny-safe. |
|
|
59
59
|
| `AUTHZ_UNREACHABLE_VIEW` | warn | A grant's `read` names a `resource:view` whose resource has no firewall — no role can reach that view. (A reachability proxy — heuristic by design.) |
|
|
60
60
|
| `AUTHZ_NOT_OVER_RESOURCE` | warn | A `not` whose operand resolves to a **resource (SQL) site** — `NOT EXISTS` over a nullable join can silently pass (the null-trap). The site resolution is conservative, so this stays advisory. |
|
|
61
|
+
| `AUTHZ_RECORD_PREDICATE_NOT_ON_LIST` | warn | A **constant** `read.access.record` predicate (`status: { equals: "published" }`, `id: { equals: "never" }`). `access.record` runs against a loaded row on `GET /:id` only — `GET /`, `POST /batch`, and the MCP list tool stop at the role gate, so the rows still list. Omit `read` to hide a resource; use the firewall to filter. `$ctx`-relative predicates are the per-record shape and stay silent. |
|
|
61
62
|
| `AUTHZ_PUSHDOWN_COST` | info | Per-permission report: how many SQL subqueries the permission lowers to, plus the max recursive-CTE depth. Advisory, never fails a build. |
|
|
62
63
|
|
|
63
64
|
A few codes are reserved in the diagnostic enum for the milestones that emit
|
|
@@ -26,7 +26,7 @@ That one modifier changes what a database breach means: a leaked D1 backup, expo
|
|
|
26
26
|
- **`org_data_keys`** — one row per organization holding a random 256-bit data key (DEK), stored **wrapped** under the `ENCRYPTION_KEK` worker secret. Created lazily on the org's first encrypted write.
|
|
27
27
|
- **Write path** — every write (CRUD routes, batch routes, and `db.insert`/`db.update` inside your actions) flows through the same chokepoint, which AES-256-GCM-encrypts the column before anything else sees it. Audit snapshots, webhook payloads, and realtime deltas therefore carry ciphertext by construction.
|
|
28
28
|
- **Read path** — generated routes decrypt behind the firewall and then apply masking, so authorized callers see plaintext and everyone else sees the redaction — never ciphertext.
|
|
29
|
-
- **`ctx.crypto`** — explicit `await ctx.crypto.decrypt(value)` / `ctx.crypto.encrypt(value)` for action code that processes the field server-side (building a manifest, sending an email). Scoped to the caller's active organization.
|
|
29
|
+
- **`ctx.crypto`** — explicit `await ctx.crypto.decrypt(value)` / `ctx.crypto.encrypt(value)` for action code that processes the field server-side (building a manifest, sending an email). Scoped to the caller's active organization. `ctx.crypto` is only hydrated for authenticated requests — inside schedules, queue consumers, email handlers, and `PUBLIC` actions it is undefined. There, import the primitives directly: `import { encryptValue, decryptValue } from '../lib/encryption'` and call `decryptValue(env, db, organizationId, stored)`. Writes through the `withInternalContext` handle still encrypt automatically.
|
|
30
30
|
- **Boot guard** — a project with encrypted columns refuses to serve without `ENCRYPTION_KEK` (503 `MISSING_ENV`), instead of silently storing plaintext.
|
|
31
31
|
|
|
32
32
|
Values at rest look like `qbenc:1:<keyVersion>:<iv>:<ciphertext>` — the prefix makes accidental plaintext detectable, and the embedded key version supports rotation with lazy re-encryption on write.
|
|
@@ -96,7 +96,7 @@ export default feature("episodes", {
|
|
|
96
96
|
guards: { updatable: ["title"], protected: { isPublished: ["publish"] } },
|
|
97
97
|
masking: { submitterEmail: { type: "email", show: { roles: ["admin"] } } },
|
|
98
98
|
transitions: { publish: { field: "isPublished", from: false, to: true, access: { roles: ["admin+"] } } },
|
|
99
|
-
realtime: { enabled: true, onInsert: true, onUpdate: true },
|
|
99
|
+
realtime: { enabled: true, onInsert: true, onUpdate: true, access: { roles: ["member+"] } }, // access is mandatory — the audience of the broadcast
|
|
100
100
|
embeddings: { fields: ["title", "summary"] },
|
|
101
101
|
});
|
|
102
102
|
```
|
|
@@ -104,7 +104,7 @@ export default feature("episodes", {
|
|
|
104
104
|
| Key | Gives you | Reference |
|
|
105
105
|
|---|---|---|
|
|
106
106
|
| `read.views` | Named column projections, each with its own route and access rule | [Views](/define/views) |
|
|
107
|
-
| `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades | [Transitions](/define/transitions) |
|
|
107
|
+
| `transitions` | Guarded state changes generated as real `POST /:id/{name}` actions — guards, stamps, `undo`, cascades. **Fixed target only**: each entry needs a literal `to` (with `from` or `fromTo`). A variable target read from input (`via: "nextStatus"`) is a hand-written `actions/<name>.ts` with `transition: { via }` — the compiler errors otherwise. | [Transitions](/define/transitions) |
|
|
108
108
|
| `triggers` | `before`/`after` hooks on write, lowered to a real SQL trigger or an application handler | [Triggers](/define/triggers) |
|
|
109
109
|
| `realtime` | Per-table broadcasts on insert/update/delete, audience-scoped | [Realtime](/platform/realtime/using-realtime) |
|
|
110
110
|
| `owns` | The composition boundary that turns on atomic parent-plus-children writes | [Changesets](/define/changesets) |
|
|
@@ -124,7 +124,7 @@ one" routing table at the top of [Actions](/define/actions).
|
|
|
124
124
|
That means:
|
|
125
125
|
|
|
126
126
|
- **Both forms remain supported indefinitely.** Mix them freely — some files `feature(...)`, some files `q.table() + defineTable()`, some files Drizzle `sqliteTable() + defineTable()`. The compiler dispatches per file.
|
|
127
|
-
- **Action files get
|
|
127
|
+
- **Action files get their bound context from the generated helper.** Each action lives in its own file under `actions/` and imports `defineAction` plus tables owned by that feature from `../.quickback/define-action`. The helper re-exports every table **in that feature** typed with the generated schema, so `record` and the audit columns are visible without casts. It does not export tables from a sibling feature: import those separately from that feature's generated helper or table module, while keeping `defineAction` local. Query operators come from project `lib/q`.
|
|
128
128
|
- **Diagnostics are identical.** Missing firewall → same warning. Protected-field wiring → same check. Nothing about `feature()` weakens the secure-by-default posture.
|
|
129
129
|
|
|
130
130
|
## Aliases
|
|
@@ -193,6 +193,7 @@ another **feature table in the same database** — never Better Auth `users` /
|
|
|
193
193
|
lifecycle of its own — junction memberships, normalized phones/emails, line
|
|
194
194
|
items — declare the composition with `owns` on the root table:
|
|
195
195
|
|
|
196
|
+
{/* doc-compile: skip — excerpt: the owned `tasks` / `projectMembers` tables and the `people` ref target live in sibling files the fence cannot carry; the compiler rejects `owns` that names an undefined table. */}
|
|
196
197
|
```ts
|
|
197
198
|
export default feature("projects", {
|
|
198
199
|
columns: {
|
|
@@ -206,6 +207,9 @@ export default feature("projects", {
|
|
|
206
207
|
tasks: { table: "tasks", fk: "projectId", inherit: ["organizationId"] },
|
|
207
208
|
members: { table: "projectMembers", fk: "projectId", refs: { personId: "people" }, inherit: ["organizationId"] },
|
|
208
209
|
},
|
|
210
|
+
// `owns` only matters on a write path — declare the changeset ops it rides
|
|
211
|
+
create: { access: { roles: ["member+"] } },
|
|
212
|
+
update: { access: { roles: ["member+"] } },
|
|
209
213
|
});
|
|
210
214
|
```
|
|
211
215
|
|
|
@@ -222,13 +226,16 @@ mounting its raw route.
|
|
|
222
226
|
|
|
223
227
|
Action bodies need to run queries against the database. Quickback's compiled projects expose the Drizzle query-builder helpers on the same `q` namespace you use for schema authoring, so `execute` stays inside one DSL:
|
|
224
228
|
|
|
229
|
+
{/* doc-compile: skip — excerpt: the `mail` feature's `mailboxes` / `messages` / `threads` tables live in sibling files the fence cannot carry, and the generated `define-action` helper only re-exports tables that exist in the feature. */}
|
|
225
230
|
```ts title="quickback/features/mail/actions/inbound.ts"
|
|
226
231
|
import { z } from "zod";
|
|
227
|
-
import {
|
|
232
|
+
import {
|
|
233
|
+
defineAction,
|
|
234
|
+
mailboxes,
|
|
235
|
+
messages,
|
|
236
|
+
threads,
|
|
237
|
+
} from "../.quickback/define-action";
|
|
228
238
|
import { q } from "../../../lib/q";
|
|
229
|
-
import { mailboxes } from "../mailboxes";
|
|
230
|
-
import { messages } from "../messages";
|
|
231
|
-
import { threads } from "../threads";
|
|
232
239
|
|
|
233
240
|
export default defineAction({
|
|
234
241
|
description: "Ingest an inbound email into the right thread.",
|
|
@@ -55,7 +55,8 @@ guards: {
|
|
|
55
55
|
// Fields only modifiable via specific actions
|
|
56
56
|
protected?: Record<string, string[]>;
|
|
57
57
|
|
|
58
|
-
// Fields set on CREATE,
|
|
58
|
+
// Fields set on CREATE, blocked on every generic update.
|
|
59
|
+
// Actions can still write them — see the note below.
|
|
59
60
|
immutable?: string[];
|
|
60
61
|
}
|
|
61
62
|
```
|
|
@@ -66,8 +67,18 @@ guards: {
|
|
|
66
67
|
|------|------------------|
|
|
67
68
|
| `createable` | Fields allowed in create (POST) request body |
|
|
68
69
|
| `updatable` | Fields allowed in update (PATCH) request body |
|
|
69
|
-
| `protected` | Fields blocked from direct writes,
|
|
70
|
-
| `immutable` | Fields allowed on create, blocked on all updates |
|
|
70
|
+
| `protected` | Fields blocked from direct writes; the named actions are documentation, not enforcement (see below) |
|
|
71
|
+
| `immutable` | Fields allowed on create, blocked on all generic updates (actions can still write them) |
|
|
72
|
+
|
|
73
|
+
> **Guards bind the generic CRUD surface, not actions.** `createable`,
|
|
74
|
+
> `updatable`, `immutable`, and `protected` are enforced by the generated
|
|
75
|
+
> `validateCreate` / `validateUpdate`, which only the CRUD, batch, and changeset
|
|
76
|
+
> routes call. An action handler writes through a scoped `db` with no field-level
|
|
77
|
+
> checks, so it can write any column — including an `immutable` one, and including
|
|
78
|
+
> a `protected` one not listed in that field's action names. Treat the names in
|
|
79
|
+
> `protected` as intent you are documenting, and keep the enforcement in the
|
|
80
|
+
> action's own access rules.
|
|
81
|
+
|
|
71
82
|
|
|
72
83
|
**Combining lists:**
|
|
73
84
|
|
|
@@ -76,6 +87,15 @@ guards: {
|
|
|
76
87
|
- `protected` - Don't also list in `createable` or `updatable` (they're mutually exclusive)
|
|
77
88
|
- `immutable` - Don't also list in `updatable` (contradiction)
|
|
78
89
|
|
|
90
|
+
> **Workflow-owned fields have one writer.** If a status or state column is
|
|
91
|
+
> managed by transitions or named actions, put it only in `protected`, mapped to
|
|
92
|
+
> those transition/action names. Never also put it in `createable` or
|
|
93
|
+
> `updatable`: the compiler rejects either contradiction, and a direct POST or
|
|
94
|
+
> PATCH path would bypass the workflow. Give the column its initial value with a
|
|
95
|
+
> schema default. Records then begin in that state, and only the declared
|
|
96
|
+
> transitions/actions may write the field.
|
|
97
|
+
|
|
98
|
+
|
|
79
99
|
```typescript
|
|
80
100
|
guards: {
|
|
81
101
|
createable: ["candidateId", "jobId", "notes", "source"],
|
|
@@ -260,6 +280,13 @@ When upsert creates a new record, ownership fields are auto-set from context:
|
|
|
260
280
|
| `'serial'` | No | Database auto-increments |
|
|
261
281
|
| `false` | Yes (if guards: false) | Client provides ID |
|
|
262
282
|
|
|
283
|
+
Need client-generated ids without giving up server minting or guards? Set
|
|
284
|
+
`allowClientIds: true` instead — creates accept an **optional**
|
|
285
|
+
strategy-shaped `id` (for optimistic updates), guards stay on, and the id is
|
|
286
|
+
exempt from `createable`. See
|
|
287
|
+
[Client-supplied IDs](/api/crud#client-supplied-ids-optimistic-updates).
|
|
288
|
+
Upsert still requires `generateId: false` + `guards: false`.
|
|
289
|
+
|
|
263
290
|
## Compile-Time Validation
|
|
264
291
|
|
|
265
292
|
The Quickback compiler validates your guards configuration and will error if:
|
|
@@ -269,3 +296,7 @@ The Quickback compiler validates your guards configuration and will error if:
|
|
|
269
296
|
3. **Field in both `updatable` and `immutable`** - Contradictory: immutable fields cannot be updated
|
|
270
297
|
4. **Field in `protected` doesn't exist in schema** - Referenced field must exist in the table
|
|
271
298
|
5. **Field in `createable`/`updatable`/`immutable` doesn't exist in schema** - All referenced fields must exist
|
|
299
|
+
|
|
300
|
+
Transition/action-managed status fields belong only in `protected`, use a
|
|
301
|
+
schema default for their initial value, and may be written only by the named
|
|
302
|
+
transitions/actions.
|
|
@@ -90,7 +90,7 @@ A few mechanics to know:
|
|
|
90
90
|
>
|
|
91
91
|
> `Critical command failed: Generate features database migrations`
|
|
92
92
|
>
|
|
93
|
-
> A Start chat compile (`complete=false`) still succeeds — it never runs drizzle-kit.
|
|
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
94
|
>
|
|
95
95
|
> A junction's `userId` is a **plain text** Better Auth id, not a SQL FK:
|
|
96
96
|
>
|
|
@@ -121,6 +121,8 @@ A few mechanics to know:
|
|
|
121
121
|
| `q.scope(kind)` | `text(...).notNull()` | `z.string()` |
|
|
122
122
|
| `q.stamp({ fromScope, claim })` | `text(...).notNull()` (nullable with `optional: true`) | `z.string().optional()` |
|
|
123
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
|
+
|
|
124
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).
|
|
125
127
|
|
|
126
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.
|
|
@@ -623,14 +625,16 @@ compliance.
|
|
|
623
625
|
|
|
624
626
|
### Protected system fields
|
|
625
627
|
|
|
626
|
-
|
|
628
|
+
These fields never take their value from client input, even with `guards: false` — but the mechanism differs by field class:
|
|
627
629
|
|
|
628
|
-
- `id` (when `generateId` is not `false`)
|
|
629
630
|
- `createdAt`, `createdBy` *(audit — always present)*
|
|
630
631
|
- `modifiedAt`, `modifiedBy` *(audit — always present)*
|
|
631
632
|
- `deletedAt`, `deletedBy` *(soft-delete — present when delete mode allows soft)*
|
|
632
633
|
|
|
633
|
-
|
|
634
|
+
The six audit/soft-delete columns are **overwritten** by the runtime wrapper — a request body that carries one is server-stamped before the SQL is built.
|
|
635
|
+
|
|
636
|
+
`id` (when `generateId` is not `false`) is **rejected at the edge** instead: it is omitted from the `.strict()` Zod body schema, so a body carrying it is a `400 VALIDATION_ERROR`, and the guards `createable` allow-list backstops that. Nothing overwrites `id` at the insert — the Zod/guards boundary is the protection. Under
|
|
637
|
+
[`allowClientIds: true`](/api/crud#client-supplied-ids-optimistic-updates) a strategy-shaped `id` is accepted on create only.
|
|
634
638
|
|
|
635
639
|
## Auto-Indexes
|
|
636
640
|
|
|
@@ -736,27 +740,35 @@ For LIST endpoints, labels are batch-resolved efficiently — one query per FK c
|
|
|
736
740
|
|
|
737
741
|
## References
|
|
738
742
|
|
|
739
|
-
|
|
743
|
+
Declare every feature-table foreign key in the schema with `.references()`.
|
|
744
|
+
That one declaration creates the database relationship and gives the API,
|
|
745
|
+
schema registry, and CMS the same target for label resolution and
|
|
746
|
+
selector/typeahead controls:
|
|
740
747
|
|
|
741
|
-
{/* doc-compile: skip —
|
|
748
|
+
{/* doc-compile: skip — cross-table column excerpt; the complete table forms appear at the top of this page. */}
|
|
742
749
|
```typescript
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
referredById: "candidate",
|
|
748
|
-
},
|
|
749
|
-
// ... firewall, guards, crud
|
|
750
|
+
const applications = q.table("applications", {
|
|
751
|
+
id: q.id(),
|
|
752
|
+
candidateId: q.text().required().references(() => candidates.id),
|
|
753
|
+
jobId: q.text().required().references(() => jobs.id),
|
|
750
754
|
});
|
|
751
755
|
```
|
|
752
756
|
|
|
753
|
-
|
|
757
|
+
Do this even when a column name appears obvious, such as `sessionId` beside a
|
|
758
|
+
`sessions` table. A matching `*Id` name is a useful compiler suggestion when a
|
|
759
|
+
relationship might be missing; it is not enough evidence to silently invent
|
|
760
|
+
one. CMS-ready schemas state the relationship explicitly.
|
|
754
761
|
|
|
755
|
-
|
|
762
|
+
The legacy resource-level `references: { vendorId: "contact" }` map can override
|
|
763
|
+
schema-registry target metadata for an alias, but it does not create a database
|
|
764
|
+
foreign key. Prefer `.references(() => contacts.id)` whenever the target is a
|
|
765
|
+
feature table in the same database. Do **not** add `.references()` for Better
|
|
766
|
+
Auth ids (`userId`, `organizationId`, `memberId`, or auth `sessionId`): those
|
|
767
|
+
rows live in `AUTH_DB`, outside the feature database.
|
|
756
768
|
|
|
757
769
|
## Input Hints
|
|
758
770
|
|
|
759
|
-
Control how the CMS renders form inputs for specific columns. By default the CMS infers
|
|
771
|
+
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:
|
|
760
772
|
|
|
761
773
|
{/* 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. */}
|
|
762
774
|
```typescript
|
|
@@ -790,7 +802,7 @@ export default defineTable(jobs, {
|
|
|
790
802
|
| `time` | Time picker |
|
|
791
803
|
| `currency` | Currency input with formatting |
|
|
792
804
|
|
|
793
|
-
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.
|
|
805
|
+
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.
|
|
794
806
|
|
|
795
807
|
### Rich Text Example
|
|
796
808
|
|
|
@@ -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).
|
|
@@ -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/src/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
|
|
@@ -9,7 +9,7 @@ Create API keys from [Account UI](/ui/account/features/api-keys) (`/api-keys`, l
|
|
|
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`:
|
|
@@ -93,7 +93,7 @@ Quickback generates migrations automatically at compile time based on your schem
|
|
|
93
93
|
|
|
94
94
|
```bash
|
|
95
95
|
# Compile your project (generates migrations)
|
|
96
|
-
quickback
|
|
96
|
+
quickback build
|
|
97
97
|
|
|
98
98
|
# Apply migrations locally
|
|
99
99
|
wrangler d1 migrations apply DB --local
|
|
@@ -104,7 +104,7 @@ wrangler d1 migrations apply DB --remote
|
|
|
104
104
|
|
|
105
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.
|
|
106
106
|
|
|
107
|
-
Generation runs locally: `quickback
|
|
107
|
+
Generation runs locally: `quickback build` invokes your project's own
|
|
108
108
|
`drizzle-kit` against migration state that never leaves your machine. Note that
|
|
109
109
|
generating a migration is not the same as applying one — `_journal.json` records
|
|
110
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
|
|