@quickback-dev/cli 0.47.0 → 0.47.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 (30) hide show
  1. package/dist/commands/compile.d.ts +1 -1
  2. package/dist/commands/compile.js +1 -1
  3. package/dist/docs/content.js +10 -10
  4. package/dist/docs/content.js.map +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/lib/file-loader.d.ts +1 -1
  7. package/dist/lib/file-loader.d.ts.map +1 -1
  8. package/dist/lib/file-loader.js +16 -3
  9. package/dist/lib/file-loader.js.map +1 -1
  10. package/dist/skill/docs/changelog.md +328 -0
  11. package/dist/skill/docs/compiler/definitions/access.md +17 -0
  12. package/dist/skill/docs/compiler/definitions/actions.md +9 -4
  13. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +27 -8
  14. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +2 -1
  15. package/dist/skill/docs/stack/account-ui/features/organizations.md +1 -1
  16. package/dist/skill/docs/stack/cms/pages.md +1 -1
  17. package/dist/skill/docs/stack/realtime/durable-objects.md +9 -0
  18. package/dist/skill/docs/stack/realtime/live-views.md +4 -0
  19. package/dist/skill/docs/stack/realtime/using-realtime.md +2 -2
  20. package/package.json +1 -1
  21. package/src/skill/docs/changelog.md +328 -0
  22. package/src/skill/docs/compiler/definitions/access.md +17 -0
  23. package/src/skill/docs/compiler/definitions/actions.md +9 -4
  24. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +27 -8
  25. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +2 -1
  26. package/src/skill/docs/stack/account-ui/features/organizations.md +1 -1
  27. package/src/skill/docs/stack/cms/pages.md +1 -1
  28. package/src/skill/docs/stack/realtime/durable-objects.md +9 -0
  29. package/src/skill/docs/stack/realtime/live-views.md +4 -0
  30. package/src/skill/docs/stack/realtime/using-realtime.md +2 -2
@@ -53,9 +53,17 @@ Neon uses PostgreSQL migrations, distinct from D1's SQLite migrations:
53
53
 
54
54
  ```bash
55
55
  quickback compile # generates migrations under quickback/drizzle/
56
- npm run db:migrate # applies them
56
+ npm run db:migrate # applies them — schema AND the RLS layer
57
57
  ```
58
58
 
59
+ The RLS layer (helper functions, policies, triggers) rides the same
60
+ journaled migration set as your schema (v0.45+): the compiler appends a
61
+ content-addressed `<idx>_quickback_rls_<hash>` migration, so one
62
+ `db:migrate` applies everything in order. The RLS migration is idempotent
63
+ (`DROP POLICY IF EXISTS` + re-create) and only a *changed* security config
64
+ appends a new entry — recompiles with unchanged security append nothing. No
65
+ manual SQL application step exists anymore.
66
+
59
67
  ## Row Level Security
60
68
 
61
69
  Quickback emits RLS policies from your `firewall` and `access` config. The Neon target uses Neon Authorize's `auth.user_id()` JWT claim function (the Supabase target uses `auth.uid()` instead — same pattern, different function).
@@ -107,6 +115,18 @@ CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (tru
107
115
  | `is_org_member()` | Checks org membership |
108
116
  | `is_owner(owner_id)` | Checks record ownership |
109
117
 
118
+ All helpers are TEXT-typed to match Better Auth's prefixed ids
119
+ (`org_abc123`). The `user_sessions` table the org helpers read is
120
+ compiler-owned migration state (`src/db/rls-support.schema.ts`), created by
121
+ the journaled migrations and kept in sync automatically: generated Better
122
+ Auth session hooks mirror the session's active organization (and team) into
123
+ it on every session create/update. Switching to "no org" revokes SQL-side
124
+ access — fail closed.
125
+
126
+ RLS coverage includes Better Auth's own tables — including those the
127
+ compiler force-enables (organization, admin, `apikeys`; plus the OAuth/agent
128
+ table families when those surfaces are on, locked to service-role only).
129
+
110
130
  ## Setting up Neon Authorize
111
131
 
112
132
  1. Open **Project Settings → Authorize** in the Neon console
@@ -117,14 +137,13 @@ CREATE POLICY "categories_all" ON categories FOR ALL TO authenticated USING (tru
117
137
 
118
138
  ```
119
139
  quickback/drizzle/
120
- ├── migrations/
121
- │ ├── 0100_create_rls_helpers.sql
122
- │ ├── 0101_create_rls_policies.sql
123
- │ └── 0102_create_indexes.sql
140
+ ├── 0000_<name>.sql # schema migrations (drizzle-kit)
141
+ ├── 0001_quickback_rls_<hash>.sql # journaled RLS layer (content-addressed)
142
+ └── meta/_journal.json # one journal covers both
124
143
  src/
125
- ├── db/schema.ts # Drizzle schema
126
- ├── auth/schema.ts # Better Auth schema
127
- └── lib/neon.ts # Connection helper
144
+ ├── db/schema.ts # Drizzle schema barrel
145
+ ├── db/rls-support.schema.ts # user_sessions + RLS support tables
146
+ └── auth/schema.ts # Better Auth schema (owned by the BA CLI)
128
147
  ```
129
148
 
130
149
  ## When to choose Neon vs D1
@@ -209,7 +209,8 @@ Or enable the in-project browser via the [`docs` config option](#interactive-api
209
209
 
210
210
  Alongside the spec, every compile writes `reports/operations.manifest.json` — a
211
211
  stable, machine-readable index of the full route surface (resource, action,
212
- view, and auth routes):
212
+ view, and auth routes; since v0.47 also the realtime, storage, and FGA
213
+ surfaces):
213
214
 
214
215
  ```json
215
216
  [
@@ -15,7 +15,7 @@ Account UI provides a complete organization management interface when `VITE_ENAB
15
15
  - Change roles and remove members — actions are filtered per-target by the role hierarchy (non-owners can't manage owner-role members)
16
16
  - Leave the organization
17
17
 
18
- > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above."
18
+ > **Note:** These three roles (`owner`, `admin`, `member`) are Better Auth's built-in organization roles and map directly to Account UI's role picker. Use the same roles in your Quickback [Access](/compiler/definitions/access) rules — with [`auth.roleHierarchy`](/compiler/definitions/access#role-hierarchy) configured, you can write `roles: ["member+"]` to mean "member and above." [Custom org roles](/compiler/definitions/access#custom-org-roles) declared in your access trees are auto-registered with the organization plugin (v0.46+), so `invite-member` / `update-member-role` accept them too.
19
19
 
20
20
  ## Invitations
21
21
 
@@ -7,7 +7,7 @@ Custom pages extend the CMS beyond standard table views. Define split-panel layo
7
7
  Pages are defined in your feature directory under a `pages/` folder:
8
8
 
9
9
  ```
10
- quickback/definitions/features/
10
+ quickback/features/
11
11
  banking/
12
12
  bank-accounts.ts # One table per file — any filename
13
13
  bank-transactions.ts
@@ -107,6 +107,15 @@ attendee — their realtime socket now opens.
107
107
 
108
108
  Quickback emits auto-broadcasts in **only one place**: the generated CRUD route handlers (`POST /` create, `PATCH /:id` update, `DELETE /:id` delete) for resources with `realtime.enabled` (or covered by `dbConfig.realtime: true`'s project-level default). Those handlers wrap each successful write with a `realtime.insert / update / delete` call before responding.
109
109
 
110
+ Auto-broadcasts carry the table's declared gates (v0.46+): the
111
+ `realtime.requiredRoles` list becomes the broadcast's `targetRoles` (with
112
+ role-hierarchy `+` expanded), and the table's effective masking config —
113
+ declared plus auto-detected sensitive columns — is applied per subscriber
114
+ role at fanout, matching what the HTTP routes mask. A `type: 'custom'` mask
115
+ function can't be replicated by the Broadcaster, so those columns broadcast
116
+ as `[REDACTED]` (fail closed). Tables that declare neither broadcast openly,
117
+ as before.
118
+
110
119
  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.
111
120
 
112
121
  | Mutation site | Auto-broadcast? | Why |
@@ -145,6 +145,10 @@ are emitted as `DELETE` so the row leaves the surface.
145
145
  - Each included table's `firewall` + `masking` apply on both the initial
146
146
  materialize and the live deltas (masking is applied per subscriber role at
147
147
  fanout), so the two are consistent.
148
+ - A table-level `realtime.requiredRoles` declaration is honored on view
149
+ deltas too (v0.46+): `view_changes` for that table fan out only to
150
+ subscribers holding one of the required roles, exactly like its row-stream
151
+ broadcasts. Tables without `requiredRoles` are unaffected.
148
152
  - **Stricter-child guard.** When a reverse-FK child's firewall is *stricter*
149
153
  than the root's (e.g. an owner-scoped note under an org-scoped person), the
150
154
  raw child row is **never broadcast**. Instead the server emits a *resync
@@ -130,7 +130,7 @@ Custom namespaces (from `defineRealtime()`) use the format `namespace:event` —
130
130
 
131
131
  ### Role-Based Filtering
132
132
 
133
- Events are only delivered to users whose role matches the broadcast's `targetRoles`. If a table's realtime config specifies `requiredRoles: ["hiring-manager", "recruiter"]`, only users with those roles receive the events.
133
+ Events are only delivered to users whose role matches the broadcast's `targetRoles`. If a table's realtime config specifies `requiredRoles: ["hiring-manager", "recruiter"]`, only users with those roles receive the events. This applies to generated CRUD broadcasts and to [live view](/stack/realtime/live-views) `view_changes` deltas alike, enforced at fanout (v0.46+ — recompile and redeploy to pick up the enforcement).
134
134
 
135
135
  ### Per-Role Masking
136
136
 
@@ -145,7 +145,7 @@ masking: {
145
145
  - **Owner sees:** `{ ssn: "123-45-6789" }`
146
146
  - **Recruiter sees:** `{ ssn: "*****6789" }`
147
147
 
148
- Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency.
148
+ Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency. A `type: 'custom'` mask function can't run inside the Broadcaster — those columns broadcast as `[REDACTED]` (fail closed).
149
149
 
150
150
  ### User-Specific Events
151
151