@quickback-dev/cli 0.34.2 → 0.38.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 (33) hide show
  1. package/dist/docs/content.d.ts.map +1 -1
  2. package/dist/docs/content.js +35 -5
  3. package/dist/docs/content.js.map +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/skill/SKILL.md +3 -3
  6. package/dist/skill/agents/quickback-specialist/AGENT.md +3 -3
  7. package/dist/skill/docs/changelog.md +442 -0
  8. package/dist/skill/docs/compiler/definitions/arrows.md +269 -0
  9. package/dist/skill/docs/compiler/definitions/diagnostics.md +136 -0
  10. package/dist/skill/docs/compiler/definitions/feature.md +3 -3
  11. package/dist/skill/docs/compiler/definitions/fga.md +314 -0
  12. package/dist/skill/docs/compiler/definitions/firewall.md +93 -6
  13. package/dist/skill/docs/compiler/definitions/permissions.md +145 -0
  14. package/dist/skill/docs/compiler/definitions/scopes.md +339 -0
  15. package/dist/skill/docs/compiler/definitions/views.md +66 -0
  16. package/dist/skill/docs/stack/realtime/durable-objects.md +43 -0
  17. package/dist/skill/docs/stack/realtime/live-views.md +168 -0
  18. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
  19. package/package.json +1 -1
  20. package/src/skill/SKILL.md +3 -3
  21. package/src/skill/agents/quickback-specialist/AGENT.md +3 -3
  22. package/src/skill/docs/changelog.md +442 -0
  23. package/src/skill/docs/compiler/definitions/arrows.md +269 -0
  24. package/src/skill/docs/compiler/definitions/diagnostics.md +136 -0
  25. package/src/skill/docs/compiler/definitions/feature.md +3 -3
  26. package/src/skill/docs/compiler/definitions/fga.md +314 -0
  27. package/src/skill/docs/compiler/definitions/firewall.md +93 -6
  28. package/src/skill/docs/compiler/definitions/permissions.md +145 -0
  29. package/src/skill/docs/compiler/definitions/scopes.md +339 -0
  30. package/src/skill/docs/compiler/definitions/views.md +66 -0
  31. package/src/skill/docs/stack/realtime/durable-objects.md +43 -0
  32. package/src/skill/docs/stack/realtime/live-views.md +168 -0
  33. package/src/skill/docs/stack/realtime/partyserver-rooms.md +22 -2
@@ -155,6 +155,14 @@ bindings: {
155
155
  access: { resource: { feature: 'interactions', table: 'interactions' } },
156
156
  },
157
157
 
158
+ // Room keyed by a unique non-PK column (v0.36+). A Yjs page editor is
159
+ // addressed by `event_pages.yjsRoomId`, not the row id — `key` tells the
160
+ // gate which column the roomId matches.
161
+ {
162
+ name: 'PageRoom', className: 'PageRoom', from: 'lib/PageRoom',
163
+ access: { resource: { feature: 'event-pages', table: 'eventPages', key: 'yjsRoomId' } },
164
+ },
165
+
158
166
  // Genuinely public room (no auth, no row lookup) — opt out explicitly.
159
167
  { name: 'PublicLobby', className: 'PublicLobby', from: 'lib/PublicLobby',
160
168
  access: 'public' },
@@ -166,11 +174,23 @@ What the compiler emits:
166
174
 
167
175
  - **`access: { resource: 'chats' }`** — `app.use('/realtime/chat/*', …)` that 401s anonymous, parses the URL segment as a row id, queries `chats` with the resource's `buildFirewallConditions(ctx)` and `eq(chats.id, rowId)`, and 403s when the row is invisible to the caller (out-of-org, soft-deleted, etc.). The DO's `onLoad` / `onConnect` then runs only for rows the user can already read.
168
176
  - **`access: { resource: { feature, table } }`** — same gate, but the schema import + firewall alias are keyed off the pinned `table` instead of the feature name. Required when a feature owns more than one resourceful table; the access gate emit can't pick which table's firewall to query otherwise.
169
- - **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate. Each `resources[kind].resource` accepts either form (string shorthand or `{ feature, table }`).
177
+ - **`access: { resource: { feature, table, key } }`** — same gate, but it matches the roomId against `table.<key>` instead of `table.id`. Use it when the room is addressed by a unique non-PK column — e.g. a Yjs editor keyed by `event_pages.yjsRoomId` (`ns.idFromName(row.yjsRoomId)`). `key` defaults to `'id'`, so existing pins are unchanged. The compiler validates the column exists at compile time. `key` also works inside each multi-resource branch.
178
+ - **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate. Each `resources[kind].resource` accepts either form (string shorthand or `{ feature, table, key? }`).
170
179
  - **`access: 'public'`** — `app.use('/realtime/<kebab>/*', …)` that just passes through. Use for anonymous game lobbies / public collab pads where the room itself is the unit of access.
171
180
  - **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`. (v0.11.1 behavior.)
172
181
 
173
- Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table.
182
+ Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table. When `key` is set, the column is checked against the pinned table's schema.
183
+
184
+ ### Migrating a hand-rolled `onConnect` room to a declarative gate
185
+
186
+ If a room currently enforces access by hand inside `onConnect` / `onBeforeConnect` — typically because the room sits on a multi-table feature and an earlier compiler refused the ambiguous string shorthand — you can almost always replace it with a declarative `access` block. The decision is just "what is the roomId?":
187
+
188
+ 1. **roomId is a table's row id** → `access: { resource: { feature, table } }`.
189
+ 2. **roomId is a unique non-PK column** (a slug, a `yjsRoomId`) → add `key`: `access: { resource: { feature, table, key: 'yjsRoomId' } }`.
190
+ 3. **one DO class serves several room kinds** (e.g. `conv-<id>` / `ticket-<id>`) → the multi-resource form with a `pattern` that captures the kind and id.
191
+ 4. **access depends on membership, not just tenant** (e.g. "is this user an attendee of the event that owns this page") → you do **not** need hand-written code. Declare the pinned table's firewall with a `via:` relationship; the gate runs the table's *full* `buildFirewallConditions`, relationship subqueries included.
192
+
193
+ The declarative gate runs the exact firewall the CRUD `GET /:id` handler enforces, with the same 401/403 semantics, *before* the WebSocket upgrade — so by the time `onConnect` fires the caller is already authorized. Dropping the hand-rolled check also closes a common gap: a room with no `access` block is reachable by **any** authenticated user who can guess a room id, regardless of tenant.
174
194
 
175
195
  ### Hand-written mount with `onBeforeConnect`
176
196