@quickback-dev/cli 0.56.11 → 0.57.0
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/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +20 -1
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrate.d.ts +44 -0
- package/dist/commands/migrate.d.ts.map +1 -0
- package/dist/commands/migrate.js +391 -0
- package/dist/commands/migrate.js.map +1 -0
- package/dist/commands/migrate.test.d.ts +2 -0
- package/dist/commands/migrate.test.d.ts.map +1 -0
- package/dist/commands/migrate.test.js +174 -0
- package/dist/commands/migrate.test.js.map +1 -0
- package/dist/docs/content.js +5 -5
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +6 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/audit-canon.d.ts +22 -0
- package/dist/lib/audit-canon.d.ts.map +1 -0
- package/dist/lib/audit-canon.js +57 -0
- package/dist/lib/audit-canon.js.map +1 -0
- package/dist/skill/docs/changelog.md +56 -0
- package/dist/skill/docs/compiler/definitions/actions.md +39 -3
- package/dist/skill/docs/compiler/definitions/schema.md +28 -4
- package/dist/skill/docs/compiler/definitions/sealed-protocol.md +14 -0
- package/dist/skill/docs/stack/queues/handlers.md +28 -2
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +56 -0
- package/src/skill/docs/compiler/definitions/actions.md +39 -3
- package/src/skill/docs/compiler/definitions/schema.md +28 -4
- package/src/skill/docs/compiler/definitions/sealed-protocol.md +14 -0
- package/src/skill/docs/stack/queues/handlers.md +28 -2
|
@@ -361,7 +361,7 @@ The compiler automatically injects the four **[audit fields](#audit-fields)** (`
|
|
|
361
361
|
|
|
362
362
|
## Audit Fields
|
|
363
363
|
|
|
364
|
-
Quickback
|
|
364
|
+
Quickback maintains four audit columns on **every table** (including child/junction tables without `defineTable`):
|
|
365
365
|
|
|
366
366
|
| Field | Type | Description |
|
|
367
367
|
|-------|------|-------------|
|
|
@@ -374,6 +374,31 @@ Audit fields are a separate concept from soft-delete (`deletedAt`/`deletedBy`)
|
|
|
374
374
|
|
|
375
375
|
Opt out of audit injection entirely with `compiler.features.auditFields: false` in `quickback.config.ts`. (You almost never want to.)
|
|
376
376
|
|
|
377
|
+
### Declaring them visibly — `...q.audit()` / `...q.softDelete()`
|
|
378
|
+
|
|
379
|
+
Historically these columns were invisible: injected into the *generated* schema only, so the table object in your editor didn't have them. They are now declared **visibly** (required by default — see below) so `$infer`, your editor, and the emitted schema all agree:
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
export default feature("candidates", {
|
|
383
|
+
columns: {
|
|
384
|
+
id: q.id(),
|
|
385
|
+
name: q.text({ maxLength: 200 }).required(),
|
|
386
|
+
organizationId: q.scope("organization"),
|
|
387
|
+
...q.audit(), // createdAt / modifiedAt / createdBy / modifiedBy
|
|
388
|
+
...q.softDelete(), // deletedAt / deletedBy — matches crud.delete.mode
|
|
389
|
+
},
|
|
390
|
+
})
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
The spreads are **declarative, not definitional**: the compiler expands them to the exact canonical column lines it would otherwise inject, so emitted output is identical either way. Raw Drizzle tables declare the canonical column lines literally instead (under a `── quickback:audit (compiler-managed) ──` marker). Run **`quickback migrate visible-columns`** to add either form across an existing project in one shot.
|
|
394
|
+
|
|
395
|
+
Two rules keep this safe:
|
|
396
|
+
|
|
397
|
+
- **The compiler validates managed columns against canon — on by default.** A `createdAt` missing its default chain, a `.notNull()` `createdBy`, a defaulted `deletedAt`, a renamed SQL name — each breaks a security pillar (audit integrity, ownership predicates, the Firewall's soft-delete ridge, name-keyed guards/RLS), so divergence is a **compile error**, and every feature table must declare the audit quartet visibly (soft-delete pair iff the resource soft-deletes). Never silently normalized. `compiler.features.visibleAuditColumns: false` opts out — invisible injection returns and divergence downgrades to a warning.
|
|
398
|
+
- **Unknown spreads are a compile error.** The columns object is compiled from source, so `...someSharedCols` can't be resolved — it fails the build rather than silently dropping columns.
|
|
399
|
+
|
|
400
|
+
Note `$insert` types the audit keys as `never` — the wrapper hard-stamps them (below), so supplying one is a type error rather than a silently discarded value.
|
|
401
|
+
|
|
377
402
|
### How auto-injection works (two layers)
|
|
378
403
|
|
|
379
404
|
"Auto-injection" covers two distinct steps. Conflating them is the most common source of confusion:
|
|
@@ -386,16 +411,15 @@ The runtime layer **hard-stamps** every audit field on every write. Caller-suppl
|
|
|
386
411
|
```ts
|
|
387
412
|
// In a custom action handler — caller cannot fake audit attribution
|
|
388
413
|
await db.insert(records).values({
|
|
389
|
-
id: createId(),
|
|
390
414
|
status: 'active',
|
|
391
415
|
createdBy: 'admin', // ← ignored; wrapper writes ctx.userId
|
|
392
416
|
modifiedAt: '1999-01-01', // ← ignored; wrapper writes "now"
|
|
393
417
|
});
|
|
394
418
|
```
|
|
395
419
|
|
|
396
|
-
What the caller is responsible for: `id`
|
|
420
|
+
What the caller is responsible for: the domain fields. (`id` auto-fills via the column's `$defaultFn` — `q.id()` and injected ids both carry one.)
|
|
397
421
|
|
|
398
|
-
What the caller does *not* need to set: any of the
|
|
422
|
+
What the caller does *not* need to set: `id`, the scope column, or any of the audit fields, ever.
|
|
399
423
|
|
|
400
424
|
### Actors: who shows up in `createdBy` / `modifiedBy`
|
|
401
425
|
|
|
@@ -93,6 +93,20 @@ Every sealed blob is `qbseal:<version>:<base64url(json)>`. Three payload shapes:
|
|
|
93
93
|
|
|
94
94
|
The decoder rejects a non-`qbseal:` string, an unknown version, an envelope over 64 KiB, or a malformed body — all fail-closed.
|
|
95
95
|
|
|
96
|
+
### The `SealedValue` type brand (server-side code)
|
|
97
|
+
|
|
98
|
+
A `.sealed()` / `q.vaultRef()` column is typed as an opaque **`SealedValue`**
|
|
99
|
+
brand in the generated Drizzle schema, not `string`. Any server-side code that
|
|
100
|
+
tries to *use* the value as a string — `JSON.parse(row.backgroundCheck)`,
|
|
101
|
+
`.length`, string interpolation — is a **TypeScript compile error**, on reads
|
|
102
|
+
and on `.returning()` alike. That's the type-level face of "the server is
|
|
103
|
+
structurally unable to read it": at rest the column only ever holds a
|
|
104
|
+
`{ __vaultRef }` marker, and the brand keeps action code from string-processing
|
|
105
|
+
or hand-forwarding that marker. Sealed values leave the system exclusively
|
|
106
|
+
through the `/seal/v1` reveal rails below. (Envelope `.encrypted()` columns are
|
|
107
|
+
deliberately *not* branded — they type as `string` because the server can
|
|
108
|
+
decrypt that tier; an action reading one gets `qbenc:` ciphertext.)
|
|
109
|
+
|
|
96
110
|
## The `/seal/v1` lifecycle
|
|
97
111
|
|
|
98
112
|
All routes are `POST`, JSON in/out, mounted at `/seal/v1`, and require an authenticated session with an **active organization** (`requireOrg` → 401/403). Errors use the standard Quickback error envelope. Most write routes accept `"dryRun": true` to validate + preview without persisting.
|
|
@@ -82,18 +82,44 @@ export default defineQueue<ProcessMaterialMessage>({
|
|
|
82
82
|
The `execute` function receives a context object:
|
|
83
83
|
|
|
84
84
|
```typescript
|
|
85
|
-
execute: async ({ message, db, env, services, ack, retry }) => {
|
|
85
|
+
execute: async ({ message, db, env, services, ack, retry, withInternalContext }) => {
|
|
86
86
|
// message - The message payload (typed via generic)
|
|
87
|
-
// db - Drizzle database instance
|
|
87
|
+
// db - Drizzle database instance (raw — you own provenance on writes)
|
|
88
88
|
// env - Cloudflare bindings (AI, queues, etc.)
|
|
89
89
|
// services - Generated services (ai, etc.)
|
|
90
90
|
// ack() - Acknowledge message (auto-called on success)
|
|
91
91
|
// retry() - Retry message (auto-called on failure)
|
|
92
|
+
// withInternalContext - enter the INTERNAL trust zone (see below)
|
|
92
93
|
|
|
93
94
|
return { success: true }; // or { success: false, error: 'reason' }
|
|
94
95
|
}
|
|
95
96
|
```
|
|
96
97
|
|
|
98
|
+
### `withInternalContext` — attributable internal writes
|
|
99
|
+
|
|
100
|
+
Queue runs are server-internal: no authenticated user, no request, no org
|
|
101
|
+
scope. The top-level `db` is the **raw** client — writes through it stamp no
|
|
102
|
+
audit actor, and provenance is your responsibility. When the handler needs to
|
|
103
|
+
touch `roles: ['INTERNAL']`-gated rows, or you want its writes attributed,
|
|
104
|
+
enter the internal trust zone:
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
execute: async ({ message, withInternalContext }) => {
|
|
108
|
+
await withInternalContext(async ({ ctx, db, services }) => {
|
|
109
|
+
// ctx.internal = true, ctx.userId = "system:queue-<name>"
|
|
110
|
+
// db is audit-wrapped: createdBy/modifiedBy stamp as system:queue-<name>
|
|
111
|
+
await db.update(pats).set({ lastUsedAt: new Date().toISOString() });
|
|
112
|
+
});
|
|
113
|
+
return { success: true };
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The handle it passes is **audit-wrapped** — `createdBy`/`modifiedBy` land as
|
|
118
|
+
`system:queue-<name>`, matching the cron schedules' `system:cron-<name>`
|
|
119
|
+
convention, so internal writes are attributable in the audit trail. There is
|
|
120
|
+
no `activeOrgId`: tenant scoping happens at the row level via the message
|
|
121
|
+
payload (e.g. `message.body.organizationId`).
|
|
122
|
+
|
|
97
123
|
## Constants and Imports
|
|
98
124
|
|
|
99
125
|
The compiler extracts top-level constants and imports from your handler file and includes them in the generated queue consumer:
|