@quickback-dev/cli 0.51.0 → 0.52.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.
Files changed (91) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +34 -19
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +31 -21
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/action-harvest.d.ts +35 -4
  9. package/dist/lib/action-harvest.d.ts.map +1 -1
  10. package/dist/lib/action-harvest.js +233 -50
  11. package/dist/lib/action-harvest.js.map +1 -1
  12. package/dist/lib/action-harvest.test.js +130 -2
  13. package/dist/lib/action-harvest.test.js.map +1 -1
  14. package/dist/lib/auth.d.ts +6 -0
  15. package/dist/lib/auth.d.ts.map +1 -1
  16. package/dist/lib/auth.js +18 -1
  17. package/dist/lib/auth.js.map +1 -1
  18. package/dist/lib/auth.test.d.ts +2 -0
  19. package/dist/lib/auth.test.d.ts.map +1 -0
  20. package/dist/lib/auth.test.js +19 -0
  21. package/dist/lib/auth.test.js.map +1 -0
  22. package/dist/lib/compile-next-steps.d.ts +4 -0
  23. package/dist/lib/compile-next-steps.d.ts.map +1 -0
  24. package/dist/lib/compile-next-steps.js +69 -0
  25. package/dist/lib/compile-next-steps.js.map +1 -0
  26. package/dist/lib/compile-next-steps.test.d.ts +2 -0
  27. package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
  28. package/dist/lib/compile-next-steps.test.js +76 -0
  29. package/dist/lib/compile-next-steps.test.js.map +1 -0
  30. package/dist/lib/file-loader.d.ts.map +1 -1
  31. package/dist/lib/file-loader.js +1 -0
  32. package/dist/lib/file-loader.js.map +1 -1
  33. package/dist/lib/file-writer.d.ts +1 -1
  34. package/dist/lib/file-writer.d.ts.map +1 -1
  35. package/dist/lib/file-writer.js +20 -5
  36. package/dist/lib/file-writer.js.map +1 -1
  37. package/dist/lib/file-writer.test.d.ts +2 -0
  38. package/dist/lib/file-writer.test.d.ts.map +1 -0
  39. package/dist/lib/file-writer.test.js +90 -0
  40. package/dist/lib/file-writer.test.js.map +1 -0
  41. package/dist/lib/shell.test.d.ts +2 -0
  42. package/dist/lib/shell.test.d.ts.map +1 -0
  43. package/dist/lib/shell.test.js +39 -0
  44. package/dist/lib/shell.test.js.map +1 -0
  45. package/dist/skill/docs/changelog.md +476 -2
  46. package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  47. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  48. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  49. package/dist/skill/docs/compiler/config/auth.md +17 -2
  50. package/dist/skill/docs/compiler/config/index.md +271 -12
  51. package/dist/skill/docs/compiler/config/output.md +49 -3
  52. package/dist/skill/docs/compiler/config/providers.md +12 -1
  53. package/dist/skill/docs/compiler/config/variables.md +5 -0
  54. package/dist/skill/docs/compiler/definitions/access.md +7 -0
  55. package/dist/skill/docs/compiler/definitions/actions.md +267 -9
  56. package/dist/skill/docs/compiler/definitions/bundles.md +69 -0
  57. package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
  58. package/dist/skill/docs/compiler/definitions/masking.md +2 -2
  59. package/dist/skill/docs/compiler/definitions/schema.md +12 -0
  60. package/dist/skill/docs/compiler/definitions/transitions.md +149 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  63. package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
  64. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  65. package/dist/skill/docs/stack/cms/schema-format.md +4 -2
  66. package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
  67. package/dist/skill/docs/stack/realtime/durable-objects.md +17 -4
  68. package/package.json +1 -1
  69. package/src/skill/docs/changelog.md +476 -2
  70. package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  71. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  72. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  73. package/src/skill/docs/compiler/config/auth.md +17 -2
  74. package/src/skill/docs/compiler/config/index.md +271 -12
  75. package/src/skill/docs/compiler/config/output.md +49 -3
  76. package/src/skill/docs/compiler/config/providers.md +12 -1
  77. package/src/skill/docs/compiler/config/variables.md +5 -0
  78. package/src/skill/docs/compiler/definitions/access.md +7 -0
  79. package/src/skill/docs/compiler/definitions/actions.md +267 -9
  80. package/src/skill/docs/compiler/definitions/bundles.md +69 -0
  81. package/src/skill/docs/compiler/definitions/firewall.md +6 -1
  82. package/src/skill/docs/compiler/definitions/masking.md +2 -2
  83. package/src/skill/docs/compiler/definitions/schema.md +12 -0
  84. package/src/skill/docs/compiler/definitions/transitions.md +149 -0
  85. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +353 -20
  86. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  87. package/src/skill/docs/stack/account-ui/hooks.md +104 -1
  88. package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  89. package/src/skill/docs/stack/cms/schema-format.md +4 -2
  90. package/src/skill/docs/stack/cms/schema-registry.md +4 -2
  91. package/src/skill/docs/stack/realtime/durable-objects.md +17 -4
@@ -121,14 +121,27 @@ import { sendSMSWithSNS, smsTemplates, isValidE164 } from "@quickback-dev/better
121
121
  function getSNSConfig(env: CloudflareBindings | undefined): SNSConfig { /* ... */ }
122
122
 
123
123
  function createAuth(env, cf, executionCtx) {
124
- const fireAndForget = (p) => { /* waitUntil(p) */ };
124
+ const scheduleCredentialDelivery = (delivery) => {
125
+ const observed = delivery.catch(() => {
126
+ console.error(JSON.stringify({
127
+ level: "error",
128
+ event: "auth.credential_delivery_failed",
129
+ }));
130
+ throw new Error("Auth credential delivery failed");
131
+ });
132
+ if (executionCtx) {
133
+ executionCtx.waitUntil(observed);
134
+ return Promise.resolve();
135
+ }
136
+ return observed;
137
+ };
125
138
 
126
139
  return betterAuth({
127
140
  plugins: [
128
141
  phoneNumber({
129
142
  phoneNumberValidator: isValidE164,
130
143
  sendOTP: async ({ phoneNumber, code }) => {
131
- fireAndForget(sendSMSWithSNS(getSNSConfig(env), {
144
+ return scheduleCredentialDelivery(sendSMSWithSNS(getSNSConfig(env), {
132
145
  to: phoneNumber,
133
146
  message: smsTemplates.otp.message({ code, appName: ... }),
134
147
  }));
@@ -140,7 +153,11 @@ function createAuth(env, cf, executionCtx) {
140
153
  }
141
154
  ```
142
155
 
143
- That's the contract: callbacks are fire-and-forget via `executionCtx.waitUntil`, never `await`ed.
156
+ That's the contract: Workers callbacks return after `waitUntil` accepts an
157
+ observed, still-rejecting task, so provider latency stays out of the response.
158
+ Without an execution context, the callback returns the observed promise for the
159
+ caller to await. Failures are logged generically without provider error content
160
+ and are never swallowed.
144
161
 
145
162
  ## Sign-in flow
146
163
 
@@ -8,7 +8,6 @@ The top-level type:
8
8
 
9
9
  ```typescript
10
10
  interface SchemaRegistry {
11
- generatedAt: string;
12
11
  generatedBy: string;
13
12
  version: string;
14
13
  features: Record<string, string[]>;
@@ -22,7 +21,6 @@ interface SchemaRegistry {
22
21
 
23
22
  | Field | Description |
24
23
  |-------|-------------|
25
- | `generatedAt` | ISO 8601 timestamp of when the registry was generated |
26
24
  | `generatedBy` | Always `"quickback-compiler"` |
27
25
  | `version` | Compiler version string |
28
26
  | `features` | Map of feature name to array of source file names |
@@ -32,6 +30,10 @@ interface SchemaRegistry {
32
30
  | `pages` | Map of page slug to full page metadata |
33
31
  | `pagesByFeature` | Map of feature name to array of page slugs in that feature |
34
32
 
33
+ The registry deliberately omits wall-clock generation metadata. Every field is
34
+ derived from compiler inputs, so identical logical input produces
35
+ byte-identical `schema-registry.json` output across consecutive compiles.
36
+
35
37
  ## TableMeta
36
38
 
37
39
  Full metadata for a single table:
@@ -21,7 +21,6 @@ The top-level structure of `schema-registry.json`:
21
21
 
22
22
  ```json
23
23
  {
24
- "generatedAt": "2026-02-14T06:26:53.554Z",
25
24
  "generatedBy": "quickback-compiler",
26
25
  "version": "1.0.0",
27
26
  "features": { ... },
@@ -35,7 +34,6 @@ The top-level structure of `schema-registry.json`:
35
34
 
36
35
  | Field | Type | Description |
37
36
  |-------|------|-------------|
38
- | `generatedAt` | `string` | ISO timestamp of generation |
39
37
  | `generatedBy` | `string` | Always `"quickback-compiler"` |
40
38
  | `version` | `string` | Compiler version used |
41
39
  | `features` | `Record<string, string[]>` | Feature name to file list mapping |
@@ -45,6 +43,10 @@ The top-level structure of `schema-registry.json`:
45
43
  | `pages` | `Record<string, PageMeta>` | Page slug to full page metadata |
46
44
  | `pagesByFeature` | `Record<string, string[]>` | Feature name to page slug list |
47
45
 
46
+ The registry contains no wall-clock generation timestamp. Its bytes are fully
47
+ derived from the logical compiler input, so repeated compiles are stable for
48
+ artifact hashing, caches, and deployment diffs.
49
+
48
50
  ## TableMeta
49
51
 
50
52
  Each table entry contains everything the CMS needs to render its UI:
@@ -35,11 +35,21 @@ export default defineTable(applications, {
35
35
  onDelete: true, // Broadcast on DELETE (default: true)
36
36
  access: { roles: ["recruiter", "hiring-manager"] }, // Audience — MANDATORY, fail-closed
37
37
  fields: ["id", "candidateId", "stage"], // Fields to include (optional)
38
+ scopeKeyFrom: "events:{eventId}", // Sugar for scopeTable + scopeField (optional)
39
+ emitFromActions: true, // Custom-action writes auto-emit after commit (optional)
38
40
  },
39
41
  // ... guards, crud
40
42
  });
41
43
  ```
42
44
 
45
+ `scopeKeyFrom` routes broadcasts to a resource lane instead of the default
46
+ org room — the template form (`"events:{eventId}"`) names the prefix and the
47
+ row column in one string; a bare column name inherits the prefix from
48
+ `scopeTable` (or the project-level ws-ticket default). `emitFromActions`
49
+ extends the same broadcasts to writes made through the scoped `db` inside
50
+ custom record-bound and bulk actions — see the boundary table below. It
51
+ triggers the same mandatory-audience check auto-CRUD broadcasts have.
52
+
43
53
  When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
44
54
 
45
55
  At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need resource-scoped tickets. The mint gate accepts three authorization vocabularies via the discriminated `access` form — pick exactly one arm:
@@ -123,17 +133,20 @@ function can't be replicated by the Broadcaster, so those columns broadcast
123
133
  as `[REDACTED]` (fail closed). Tables that declare neither broadcast openly,
124
134
  as before.
125
135
 
126
- Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually. In action handlers on realtime-enabled projects, Quickback now injects a typed `realtime` helper directly into `execute(...)`; outside actions you still call `createRealtime(env)` yourself.
136
+ Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hono routes — you broadcast manually **unless the table opts in to action emission** (see below). In action handlers on realtime-enabled projects, Quickback injects a typed `realtime` helper directly into `execute(...)`; outside actions you still call `createRealtime(env)` yourself.
127
137
 
128
138
  | Mutation site | Auto-broadcast? | Why |
129
139
  |---|---|---|
130
140
  | Generated CRUD route (`POST /`, `PATCH /:id`, `DELETE /:id`) | Yes | The compiler emits the call after the write returns. |
131
141
  | Generated batch route (`/batch/...`) | Yes | Same pattern, emitted per record. |
132
- | `scoped.insert/update/delete` inside an action handler | No — manual | Scoped-db is a query-shape wrapper (firewall + soft-delete WHERE injection). It deliberately has no side-effects so explicit handlers can write multiple records, conditionally roll back, etc. without surprise broadcasts. |
133
- | `unsafeDb` writes in actions (or any custom route) | No — manual | Same reasoning — `unsafeDb` is the un-wrapped escape hatch. |
142
+ | `db.insert/update/delete` inside a record-bound action, table declares `realtime.emitFromActions: true` | Yes — after commit | The scoped db records each write into a per-request capture collector (recording only — it never calls the transport itself); the route emits identical auto-CRUD frames after `execute` succeeds, via the after-commit effects machinery. |
143
+ | `db.insert/update/delete` inside an action handler (no `emitFromActions`) | No — manual | Scoped-db stays a query-shape wrapper (firewall + soft-delete WHERE injection) with no broadcast side-effects. |
144
+ | `unsafeDb` writes in actions (or any custom route) | No — manual | `unsafeDb` is the un-wrapped escape hatch — invisible to capture too. |
134
145
  | Queue consumers, cron jobs, webhook handlers | No — manual | These run outside the CRUD path entirely. |
135
146
 
136
- The rule of thumb: if your code calls `db.insert(...)` / `scoped.insert(...)` directly, you also call `realtime.insert(...)` directly on the next line. Otherwise the cross-tab live-update you wired up in the SPA won't fire.
147
+ The rule of thumb: opt the table into `realtime: { emitFromActions: true }` (or give the action an `emit:` block for the pre-bound `emitCrud(row, oldRow?)` helper) and the frames take care of themselves; otherwise, if your code calls `db.insert(...)` directly, you also call `realtime.insert(...)` directly on the next line.
148
+
149
+ Two capture caveats: inserts that skip `.returning()` emit the values as written (DB-default columns absent), and updates/deletes cost one extra pre-select on the same WHERE — it replaces the hand-written read every manual emit needed anyway. Capture covers the feature's own table on record-bound and bulk routes; standalone actions and cross-feature writes use `emit:`/`emitCrud` or the raw `realtime.*` API.
137
150
 
138
151
  ## Generated Helper
139
152