@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.
- package/dist/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +34 -19
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +22 -22
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +35 -4
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +233 -50
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/action-harvest.test.js +130 -2
- package/dist/lib/action-harvest.test.js.map +1 -1
- package/dist/lib/auth.d.ts +6 -0
- package/dist/lib/auth.d.ts.map +1 -1
- package/dist/lib/auth.js +18 -1
- package/dist/lib/auth.js.map +1 -1
- package/dist/lib/auth.test.d.ts +2 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/auth.test.js +19 -0
- package/dist/lib/auth.test.js.map +1 -0
- package/dist/lib/compile-next-steps.d.ts +4 -0
- package/dist/lib/compile-next-steps.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.js +69 -0
- package/dist/lib/compile-next-steps.js.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts +2 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.js +76 -0
- package/dist/lib/compile-next-steps.test.js.map +1 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +1 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.d.ts +1 -1
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +20 -5
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/file-writer.test.d.ts +2 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.js +90 -0
- package/dist/lib/file-writer.test.js.map +1 -0
- package/dist/lib/shell.test.d.ts +2 -0
- package/dist/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/shell.test.js +39 -0
- package/dist/lib/shell.test.js.map +1 -0
- package/dist/skill/docs/changelog.md +515 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +16 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
- package/dist/skill/docs/compiler/config/auth.md +28 -4
- package/dist/skill/docs/compiler/config/index.md +271 -12
- package/dist/skill/docs/compiler/config/output.md +49 -3
- package/dist/skill/docs/compiler/config/providers.md +16 -5
- package/dist/skill/docs/compiler/config/variables.md +5 -0
- package/dist/skill/docs/compiler/definitions/access.md +7 -0
- package/dist/skill/docs/compiler/definitions/actions.md +156 -9
- package/dist/skill/docs/compiler/definitions/firewall.md +6 -1
- package/dist/skill/docs/compiler/definitions/rate-limit.md +11 -9
- package/dist/skill/docs/compiler/definitions/schema.md +12 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +357 -20
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
- package/dist/skill/docs/stack/account-ui/hooks.md +104 -1
- package/dist/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
- package/dist/skill/docs/stack/cms/schema-format.md +4 -2
- package/dist/skill/docs/stack/cms/schema-registry.md +4 -2
- package/dist/skill/docs/stack/realtime/durable-objects.md +12 -7
- package/dist/skill/docs/stack/realtime/index.md +37 -7
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +515 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +16 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +4 -2
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +17 -5
- package/src/skill/docs/compiler/config/auth.md +28 -4
- package/src/skill/docs/compiler/config/index.md +271 -12
- package/src/skill/docs/compiler/config/output.md +49 -3
- package/src/skill/docs/compiler/config/providers.md +16 -5
- package/src/skill/docs/compiler/config/variables.md +5 -0
- package/src/skill/docs/compiler/definitions/access.md +7 -0
- package/src/skill/docs/compiler/definitions/actions.md +156 -9
- package/src/skill/docs/compiler/definitions/firewall.md +6 -1
- package/src/skill/docs/compiler/definitions/rate-limit.md +11 -9
- package/src/skill/docs/compiler/definitions/schema.md +12 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +357 -20
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +7 -1
- package/src/skill/docs/stack/account-ui/hooks.md +104 -1
- package/src/skill/docs/stack/auth/plugins/aws-sns.md +20 -3
- package/src/skill/docs/stack/cms/schema-format.md +4 -2
- package/src/skill/docs/stack/cms/schema-registry.md +4 -2
- package/src/skill/docs/stack/realtime/durable-objects.md +12 -7
- 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
|
|
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
|
-
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
102
|
-
> (literal-only) firewall with no org/owner/team isolation.
|
|
103
|
-
>
|
|
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 |
|
|
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
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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",
|