@quickback-dev/cli 0.50.8 → 0.51.1

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 (88) 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.js +22 -22
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/lib/action-harvest.d.ts +35 -4
  8. package/dist/lib/action-harvest.d.ts.map +1 -1
  9. package/dist/lib/action-harvest.js +233 -50
  10. package/dist/lib/action-harvest.js.map +1 -1
  11. package/dist/lib/action-harvest.test.js +130 -2
  12. package/dist/lib/action-harvest.test.js.map +1 -1
  13. package/dist/lib/auth.d.ts +6 -0
  14. package/dist/lib/auth.d.ts.map +1 -1
  15. package/dist/lib/auth.js +18 -1
  16. package/dist/lib/auth.js.map +1 -1
  17. package/dist/lib/auth.test.d.ts +2 -0
  18. package/dist/lib/auth.test.d.ts.map +1 -0
  19. package/dist/lib/auth.test.js +19 -0
  20. package/dist/lib/auth.test.js.map +1 -0
  21. package/dist/lib/compile-next-steps.d.ts +4 -0
  22. package/dist/lib/compile-next-steps.d.ts.map +1 -0
  23. package/dist/lib/compile-next-steps.js +69 -0
  24. package/dist/lib/compile-next-steps.js.map +1 -0
  25. package/dist/lib/compile-next-steps.test.d.ts +2 -0
  26. package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
  27. package/dist/lib/compile-next-steps.test.js +76 -0
  28. package/dist/lib/compile-next-steps.test.js.map +1 -0
  29. package/dist/lib/file-loader.d.ts.map +1 -1
  30. package/dist/lib/file-loader.js +1 -0
  31. package/dist/lib/file-loader.js.map +1 -1
  32. package/dist/lib/file-writer.d.ts +1 -1
  33. package/dist/lib/file-writer.d.ts.map +1 -1
  34. package/dist/lib/file-writer.js +20 -5
  35. package/dist/lib/file-writer.js.map +1 -1
  36. package/dist/lib/file-writer.test.d.ts +2 -0
  37. package/dist/lib/file-writer.test.d.ts.map +1 -0
  38. package/dist/lib/file-writer.test.js +90 -0
  39. package/dist/lib/file-writer.test.js.map +1 -0
  40. package/dist/lib/shell.test.d.ts +2 -0
  41. package/dist/lib/shell.test.d.ts.map +1 -0
  42. package/dist/lib/shell.test.js +39 -0
  43. package/dist/lib/shell.test.js.map +1 -0
  44. package/dist/skill/docs/changelog.md +515 -0
  45. package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  46. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  47. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  48. package/dist/skill/docs/compiler/config/auth.md +28 -4
  49. package/dist/skill/docs/compiler/config/index.md +271 -12
  50. package/dist/skill/docs/compiler/config/output.md +49 -3
  51. package/dist/skill/docs/compiler/config/providers.md +16 -5
  52. package/dist/skill/docs/compiler/config/variables.md +5 -0
  53. package/dist/skill/docs/compiler/definitions/access.md +7 -0
  54. package/dist/skill/docs/compiler/definitions/actions.md +156 -9
  55. package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
  56. package/dist/skill/docs/compiler/definitions/rate-limit.md +11 -9
  57. package/dist/skill/docs/compiler/definitions/schema.md +12 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +357 -20
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  60. package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
  61. package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  62. package/dist/skill/docs/stack/cms/schema-format.md +4 -2
  63. package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
  64. package/dist/skill/docs/stack/realtime/durable-objects.md +12 -7
  65. package/dist/skill/docs/stack/realtime/index.md +37 -7
  66. package/package.json +1 -1
  67. package/src/skill/docs/changelog.md +515 -0
  68. package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
  69. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
  70. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
  71. package/src/skill/docs/compiler/config/auth.md +28 -4
  72. package/src/skill/docs/compiler/config/index.md +271 -12
  73. package/src/skill/docs/compiler/config/output.md +49 -3
  74. package/src/skill/docs/compiler/config/providers.md +16 -5
  75. package/src/skill/docs/compiler/config/variables.md +5 -0
  76. package/src/skill/docs/compiler/definitions/access.md +7 -0
  77. package/src/skill/docs/compiler/definitions/actions.md +156 -9
  78. package/src/skill/docs/compiler/definitions/firewall.md +6 -1
  79. package/src/skill/docs/compiler/definitions/rate-limit.md +11 -9
  80. package/src/skill/docs/compiler/definitions/schema.md +12 -0
  81. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +357 -20
  82. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
  83. package/src/skill/docs/stack/account-ui/hooks.md +104 -1
  84. package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
  85. package/src/skill/docs/stack/cms/schema-format.md +4 -2
  86. package/src/skill/docs/stack/cms/schema-registry.md +4 -2
  87. package/src/skill/docs/stack/realtime/durable-objects.md +12 -7
  88. package/src/skill/docs/stack/realtime/index.md +37 -7
@@ -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:
@@ -42,14 +42,18 @@ export default defineTable(applications, {
42
42
 
43
43
  When any table has realtime enabled, the compiler generates `src/lib/realtime.ts` with helper functions for sending notifications.
44
44
 
45
- At the project level, `providers.database.config.realtime` can stay boolean or become object-shaped when you need relationship-authorized resource tickets:
45
+ 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:
46
46
 
47
47
  ```typescript
48
48
  providers: {
49
49
  database: defineDatabase("cloudflare-d1", {
50
50
  realtime: {
51
51
  wsTicket: {
52
- role: "attendee",
52
+ access: { authzRole: "attendee" }, // authz relationship role (legacy shorthand: role: "attendee")
53
+ // access: { roles: ["member+"] }, // org-membership roles — verifies the org role AND that the
54
+ // // scope row is in the caller's ACTIVE org (org column required)
55
+ // access: { fga: { relation: "viewer", object: "event:{id}" } }, // FGA relation on the scope row —
56
+ // // same evaluator + object template as read-path access:{ fga }
53
57
  requestField: "eventId",
54
58
  scopeTable: "events",
55
59
  },
@@ -58,7 +62,7 @@ providers: {
58
62
  }
59
63
  ```
60
64
 
61
- That tells `/broadcast/v1/ws-ticket` to authenticate with Better Auth, verify the `attendee` relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane.
65
+ That tells `/broadcast/v1/ws-ticket` to authenticate with Better Auth, run the declared gate against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` lane. See [Realtime → Enabling Realtime](/stack/realtime#enabling-realtime) for the full per-arm semantics; all three forms fail closed at compile time (ambiguous names living in two vocabularies, missing `auth.roleHierarchy` for `+`, missing `authz.fga`, unknown FGA type/relation, missing organization column, non-tenant-scoped `scopeTable`).
62
66
 
63
67
  ### Namespace-backed tickets (per-matched-lane)
64
68
 
@@ -97,10 +101,11 @@ attendee — their realtime socket now opens.
97
101
  > only target a room whose resource resolves under the caller's tenant (an org-A
98
102
  > admin requesting an org-B `eventId` gets `403`, not a cross-tenant socket). Because
99
103
  > the room *is* the data — there is no firewall between a ticket and a Durable
100
- > Object room — the compiler **rejects at build time** a namespace-backed
101
- > `wsTicket` whose `scopeTable` has `firewall: { exception: true }` or a non-tenant
102
- > (literal-only) firewall with no org/owner/team isolation. Use a tenant-scoped
103
- > `scopeTable`.
104
+ > Object room — the compiler **rejects at build time** a namespace-backed or
105
+ > FGA-gated `wsTicket` whose `scopeTable` has `firewall: { exception: true }` or a
106
+ > non-tenant (literal-only) firewall with no org/owner/team isolation. (The
107
+ > org-membership form binds by the organization column directly, so it requires
108
+ > that column instead.) Use a tenant-scoped `scopeTable`.
104
109
 
105
110
 
106
111
  ## When auto-broadcast fires (and when you call it manually)
@@ -42,7 +42,7 @@ The Broadcaster Durable Object runs **inline** in your main Quickback worker —
42
42
  | Role-based filtering | Only send events to users with matching roles |
43
43
  | Per-role masking | Different users see different field values based on their role |
44
44
  | User-specific targeting | Send events to a specific user within an org |
45
- | Resource-scoped tickets | Reuse authz relationship roles to mint scope-bound ws tickets |
45
+ | Resource-scoped tickets | Mint scope-bound ws tickets gated by org-membership roles, authz relationship roles, or FGA relations |
46
46
  | Custom broadcasts | Arbitrary events beyond CRUD |
47
47
  | Custom namespaces | `defineRealtime()` for type-safe event helpers |
48
48
  | Ticket-based auth | HMAC-signed tickets verified at WebSocket upgrade — no HTTP round-trip |
@@ -99,17 +99,20 @@ providers: {
99
99
  ```
100
100
 
101
101
  The object form is the **advanced** variant, only needed when you mint
102
- resource-scoped tickets for relationship-authorized subscribers (e.g. an
103
- external attendee who may join one event's channel). `wsTicket.role` must be
104
- an `authz.roles` relationship role — NOT an org-membership role like
105
- `member`/`admin`/`owner` (those names are reserved and will not compile here):
102
+ resource-scoped tickets (e.g. an external attendee who may join one event's
103
+ channel, or an org member who may join one project's room). The mint gate is
104
+ declared with `wsTicket.access`, a discriminated union — the arm names the
105
+ authorization vocabulary, so a bare name can never silently mean two things:
106
106
 
107
107
  ```typescript
108
108
  providers: {
109
109
  database: defineDatabase("cloudflare-d1", {
110
110
  realtime: {
111
111
  wsTicket: {
112
- role: "attendee", // authz relationship role, not an org role
112
+ // Pick EXACTLY ONE arm:
113
+ access: { roles: ["member+"] }, // org-membership roles (hierarchy expands)
114
+ // access: { authzRole: "attendee" }, // authz relationship role
115
+ // access: { fga: { relation: "viewer", object: "event:{id}" } }, // FGA relation on the scope row
113
116
  requestField: "eventId",
114
117
  scopeTable: "events",
115
118
  },
@@ -118,7 +121,34 @@ providers: {
118
121
  }
119
122
  ```
120
123
 
121
- With that config, `/broadcast/v1/ws-ticket` can authenticate the caller, verify the declared authz relationship role against `body.eventId`, and mint a short-lived ticket scoped to the resolved `events:<id>` channel.
124
+ - **`{ roles }` — org-membership roles.** `"member+"` expands via
125
+ `auth.roleHierarchy` (compile error without it). Firewall-consistent: the
126
+ route verifies the caller's org role **and** that the requested `scopeTable`
127
+ row belongs to the caller's *active* organization — an org-A member cannot
128
+ mint a ticket to org B's room. The scope table must therefore carry an
129
+ organization column (compile error otherwise). UPPERCASE pseudo-roles are
130
+ rejected here: a `PUBLIC`/`AUTHENTICATED` ticket factory would hand signed
131
+ room credentials to callers with no org standing.
132
+ - **`{ authzRole }` — a declared `authz.roles` relationship role** (`{ via }`).
133
+ The route probes the relationship table against `body.eventId`; the ticket
134
+ carries the relationship role (e.g. `attendee`). The legacy
135
+ `role: "attendee"` string is the back-compat shorthand for this arm and
136
+ compiles identically. Org-membership names (`member`/`admin`/`owner`) are
137
+ still rejected in this arm — spell those `access: { roles: [...] }`.
138
+ - **`{ fga }` — an FGA relation.** The route loads the `scopeTable` row through
139
+ its own firewall (tenant bind), derives the object from the template
140
+ (`"event:{id}"` — `{field}` tokens read from the row, the same template
141
+ language as the read path's `access: { fga }`), and requires the caller to
142
+ hold `relation` on it via the same org-scoped check evaluator the read path
143
+ uses. Requires `authz.fga`; the object type and relation are validated
144
+ against the model at compile time.
145
+
146
+ Whichever arm you pick, `/broadcast/v1/ws-ticket` authenticates the caller,
147
+ runs that gate against `body.eventId`, and mints a short-lived ticket scoped to
148
+ the resolved `events:<id>` channel. Everything fails closed at compile time:
149
+ a bare name that exists in more than one vocabulary is an ambiguity error
150
+ demanding the explicit arm, and a missing hierarchy, missing FGA model, or
151
+ missing organization column fails the build with an actionable message.
122
152
 
123
153
  ## Pages
124
154
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.50.8",
3
+ "version": "0.51.1",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",