@quickback-dev/cli 0.38.0 → 0.39.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 +36 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/compile.test.d.ts +2 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- package/dist/commands/compile.test.js +83 -0
- package/dist/commands/compile.test.js.map +1 -0
- package/dist/commands/create.js +15 -11
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/migrations.d.ts +33 -0
- package/dist/commands/migrations.d.ts.map +1 -1
- package/dist/commands/migrations.js +41 -2
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/migrations.test.d.ts +2 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.js +67 -0
- package/dist/commands/migrations.test.js.map +1 -0
- package/dist/docs/content.js +24 -24
- package/dist/docs/content.js.map +1 -1
- package/dist/examples/recruitment.tar.gz +0 -0
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +48 -0
- package/dist/lib/action-harvest.d.ts.map +1 -0
- package/dist/lib/action-harvest.js +292 -0
- package/dist/lib/action-harvest.js.map +1 -0
- package/dist/lib/action-harvest.test.d.ts +2 -0
- package/dist/lib/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/action-harvest.test.js +112 -0
- package/dist/lib/action-harvest.test.js.map +1 -0
- package/dist/lib/api-client.d.ts +10 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +17 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/api-client.test.js +19 -0
- package/dist/lib/api-client.test.js.map +1 -1
- package/dist/lib/artifact-routing.d.ts +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +15 -3
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/artifact-routing.test.js +12 -1
- package/dist/lib/artifact-routing.test.js.map +1 -1
- package/dist/lib/file-loader.d.ts +1 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +34 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.js +28 -4
- package/dist/lib/file-loader.test.js.map +1 -1
- package/dist/lib/prepare-state-output.d.ts +8 -0
- package/dist/lib/prepare-state-output.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.js +17 -0
- package/dist/lib/prepare-state-output.js.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts +2 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.js +31 -0
- package/dist/lib/prepare-state-output.test.js.map +1 -0
- package/dist/skill/SKILL.md +1 -1
- package/dist/skill/docs/changelog.md +201 -0
- package/dist/skill/docs/compiler/config/agents.md +1 -1
- package/dist/skill/docs/compiler/config/auth.md +1 -1
- package/dist/skill/docs/compiler/config/index.md +8 -9
- package/dist/skill/docs/compiler/config/providers.md +3 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
- package/dist/skill/docs/compiler/definitions/access.md +40 -33
- package/dist/skill/docs/compiler/definitions/actions.md +1 -1
- package/dist/skill/docs/compiler/definitions/firewall.md +1 -1
- package/dist/skill/docs/compiler/definitions/schema.md +8 -2
- package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
- package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
- package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
- package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
- package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
- package/dist/skill/docs/stack/cms/connecting.md +17 -16
- package/dist/skill/docs/stack/cms/index.md +7 -7
- package/dist/skill/docs/stack/cms/schema-format.md +0 -2
- package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
- package/dist/skill/docs/stack/cms/security.md +6 -6
- package/dist/skill/docs/stack/realtime/durable-objects.md +5 -7
- package/dist/skill/docs/stack/storage/r2.md +112 -3
- package/dist/skill/docs/stack/storage/using-r2.md +30 -10
- package/dist/templates/registry.js +2 -2
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/examples/recruitment.tar.gz +0 -0
- package/src/skill/SKILL.md +1 -1
- package/src/skill/docs/changelog.md +201 -0
- package/src/skill/docs/compiler/config/agents.md +1 -1
- package/src/skill/docs/compiler/config/auth.md +1 -1
- package/src/skill/docs/compiler/config/index.md +8 -9
- package/src/skill/docs/compiler/config/providers.md +3 -0
- package/src/skill/docs/compiler/config/single-tenant.md +65 -73
- package/src/skill/docs/compiler/definitions/access.md +40 -33
- package/src/skill/docs/compiler/definitions/actions.md +1 -1
- package/src/skill/docs/compiler/definitions/firewall.md +1 -1
- package/src/skill/docs/compiler/definitions/schema.md +8 -2
- package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
- package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
- package/src/skill/docs/compiler/getting-started/templates.md +6 -6
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
- package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
- package/src/skill/docs/stack/account-ui/features/index.md +2 -2
- package/src/skill/docs/stack/cms/connecting.md +17 -16
- package/src/skill/docs/stack/cms/index.md +7 -7
- package/src/skill/docs/stack/cms/schema-format.md +0 -2
- package/src/skill/docs/stack/cms/schema-registry.md +0 -6
- package/src/skill/docs/stack/cms/security.md +6 -6
- package/src/skill/docs/stack/realtime/durable-objects.md +5 -7
- package/src/skill/docs/stack/storage/r2.md +112 -3
- package/src/skill/docs/stack/storage/using-r2.md +30 -10
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { afterEach, describe, expect, it } from 'bun:test';
|
|
2
|
+
import { promises as fs } from 'fs';
|
|
3
|
+
import { join } from 'path';
|
|
4
|
+
import { tmpdir } from 'os';
|
|
5
|
+
import { prepareStateArtifacts } from './prepare-state-output.js';
|
|
6
|
+
const tempDirs = [];
|
|
7
|
+
async function createTempDir() {
|
|
8
|
+
const dir = await fs.mkdtemp(join(tmpdir(), 'quickback-cli-state-'));
|
|
9
|
+
tempDirs.push(dir);
|
|
10
|
+
return dir;
|
|
11
|
+
}
|
|
12
|
+
afterEach(async () => {
|
|
13
|
+
await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
|
|
14
|
+
});
|
|
15
|
+
describe('prepareStateArtifacts', () => {
|
|
16
|
+
// User story: As a Neon user rerunning compile locally, I need stale
|
|
17
|
+
// top-level drizzle migrations removed from quickback/drizzle/ so only the
|
|
18
|
+
// compiler's current manifest is synced back to disk.
|
|
19
|
+
it('wipes compiler-owned drizzle state before syncing fresh files', async () => {
|
|
20
|
+
const stateDir = await createTempDir();
|
|
21
|
+
await fs.mkdir(join(stateDir, 'drizzle', 'meta'), { recursive: true });
|
|
22
|
+
await fs.writeFile(join(stateDir, 'drizzle', '0000_stale.sql'), '-- stale');
|
|
23
|
+
await fs.writeFile(join(stateDir, 'drizzle', 'meta', '_journal.json'), '{"version":"7"}');
|
|
24
|
+
await prepareStateArtifacts(stateDir, [
|
|
25
|
+
{ path: 'drizzle/0000_current.sql', content: '-- current' },
|
|
26
|
+
{ path: 'drizzle/meta/_journal.json', content: '{"version":"7"}' },
|
|
27
|
+
]);
|
|
28
|
+
expect(await fs.readdir(join(stateDir, 'drizzle')).catch(() => [])).toEqual([]);
|
|
29
|
+
});
|
|
30
|
+
});
|
|
31
|
+
//# sourceMappingURL=prepare-state-output.test.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"prepare-state-output.test.js","sourceRoot":"","sources":["../../src/lib/prepare-state-output.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAC3D,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,QAAQ,GAAa,EAAE,CAAC;AAE9B,KAAK,UAAU,aAAa;IAC1B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,CAAC,KAAK,IAAI,EAAE;IACnB,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACnG,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,qEAAqE;IACrE,2EAA2E;IAC3E,sDAAsD;IACtD,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,QAAQ,GAAG,MAAM,aAAa,EAAE,CAAC;QACvC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,CAAC,EAAE,UAAU,CAAC,CAAC;QAC5E,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,iBAAiB,CAAC,CAAC;QAE1F,MAAM,qBAAqB,CAAC,QAAQ,EAAE;YACpC,EAAE,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,YAAY,EAAE;YAC3D,EAAE,IAAI,EAAE,4BAA4B,EAAE,OAAO,EAAE,iBAAiB,EAAE;SACnE,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
|
package/dist/skill/SKILL.md
CHANGED
|
@@ -214,7 +214,7 @@ The path layout mirrors the public docs site (https://docs.quickback.dev). Open
|
|
|
214
214
|
- `output` — `build.outputDir`, custom dependencies
|
|
215
215
|
- `domains` — multi-domain hostname routing (CMS / account / admin)
|
|
216
216
|
- `spa` — single-worker SPA mount (your product app at the apex)
|
|
217
|
-
- `single-tenant` —
|
|
217
|
+
- `single-tenant` — pinned organization mode and migration away from removed `organizations: false`
|
|
218
218
|
- `agents` — robots.txt, llms.txt, MCP, OAuth discovery
|
|
219
219
|
|
|
220
220
|
**Stack — runtime services** (`docs/stack/<topic>.md`)
|
|
@@ -1,5 +1,206 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.39.0 — June 2, 2026
|
|
4
|
+
|
|
5
|
+
Media and large-binary uploads are now first-class. Instead of streaming file
|
|
6
|
+
bytes through your Worker — which hits the request-body cap and burns Worker
|
|
7
|
+
CPU/duration — an action mints a short-lived **presigned URL** and the client
|
|
8
|
+
uploads the bytes **directly to R2**. The Worker only signs; it never sits in
|
|
9
|
+
the data path. This is the supported way to author image/video/document upload
|
|
10
|
+
endpoints, and it survives every `quickback compile` with no generated-file
|
|
11
|
+
patching.
|
|
12
|
+
|
|
13
|
+
Requires R2 file storage (`defineFileStorage("cloudflare-r2", …)`).
|
|
14
|
+
|
|
15
|
+
### `ctx.storage` — sign uploads from any action
|
|
16
|
+
|
|
17
|
+
When R2 file storage is configured, every `defineAction` execute receives a
|
|
18
|
+
typed `storage` signer. Your action runs all the usual security layers (auth,
|
|
19
|
+
roles, org/relationship scope), computes a tenant-scoped key, hands the client
|
|
20
|
+
an upload URL, and stores the key in **your own table** — no separate metadata
|
|
21
|
+
system required:
|
|
22
|
+
|
|
23
|
+
```ts
|
|
24
|
+
export default defineAction({
|
|
25
|
+
path: "/event/:eventId/media/upload-file-binary",
|
|
26
|
+
method: "POST",
|
|
27
|
+
input: z.object({ filename: z.string(), contentType: z.string() }),
|
|
28
|
+
access: { roles: ["admin", "member", "scope:event:attendee"] },
|
|
29
|
+
async execute({ input, ctx, c, db, storage }) {
|
|
30
|
+
const eventId = c.req.param("eventId");
|
|
31
|
+
const key = `org/${ctx.activeOrgId}/event/${eventId}/${crypto.randomUUID()}-${input.filename}`;
|
|
32
|
+
const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
|
|
33
|
+
await db.insert(images).values({ key, eventId });
|
|
34
|
+
return { uploadUrl: upload.url, key, headers: upload.headers, expiresAt: upload.expiresAt };
|
|
35
|
+
},
|
|
36
|
+
});
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`storage` exposes `signPutUrl(key, { contentType?, expiresIn? })` (returns
|
|
40
|
+
`{ url, method, headers, key, expiresAt }`) and
|
|
41
|
+
`signGetUrl(key, { expiresIn?, downloadFilename? })` (returns a presigned GET
|
|
42
|
+
URL). Construction is zero-cost — actions that never touch `storage` pay
|
|
43
|
+
nothing.
|
|
44
|
+
|
|
45
|
+
### Managed presign + confirm endpoints
|
|
46
|
+
|
|
47
|
+
For the zero-config path, the built-in storage API now exposes a presigned
|
|
48
|
+
upload alongside the existing through-Worker upload:
|
|
49
|
+
|
|
50
|
+
- `POST /storage/v1/presign/:bucket/*path` — runs the bucket's auth/role/scope
|
|
51
|
+
checks, validates the declared `contentType` + `size` against bucket limits,
|
|
52
|
+
records a pending object row, and returns `{ id, key, uploadUrl, method,
|
|
53
|
+
headers, expiresAt }`
|
|
54
|
+
- `POST /storage/v1/confirm/:bucket/*path` — reconciles the recorded size and
|
|
55
|
+
etag against what actually landed in R2 (`HEAD`)
|
|
56
|
+
|
|
57
|
+
### Setup: R2 API token
|
|
58
|
+
|
|
59
|
+
Presigning uses R2's S3 API, which needs an **R2 API token** — the Workers R2
|
|
60
|
+
binding cannot presign on its own. Set three secrets:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
wrangler secret put R2_ACCOUNT_ID
|
|
64
|
+
wrangler secret put R2_ACCESS_KEY_ID
|
|
65
|
+
wrangler secret put R2_SECRET_ACCESS_KEY
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`aws4fetch` is added to the generated `package.json` automatically, and the R2
|
|
69
|
+
presign secrets are added to the generated `Env` type. If you pass `contentType`
|
|
70
|
+
to `signPutUrl`, the client must replay exactly that `Content-Type` header on
|
|
71
|
+
the `PUT`.
|
|
72
|
+
|
|
73
|
+
### No raw-body action flag
|
|
74
|
+
|
|
75
|
+
Streaming a raw binary request body through an action is intentionally **not**
|
|
76
|
+
supported. Presigning delivers the same result — large files, no body cap —
|
|
77
|
+
without poking a hole in the body-parsing layer, so JSON actions and the ~1 MiB
|
|
78
|
+
JSON cap stay intact for every other route.
|
|
79
|
+
|
|
80
|
+
### Storage routes hardened
|
|
81
|
+
|
|
82
|
+
Enabling R2 file storage previously exposed several latent type errors in the
|
|
83
|
+
generated `/storage/v1/*` routes (dead references from an old multipart
|
|
84
|
+
refactor, JSON-string role columns treated as arrays, a few undefined
|
|
85
|
+
variables). The full storage surface now type-checks cleanly when file storage
|
|
86
|
+
is configured.
|
|
87
|
+
|
|
88
|
+
## v0.38.1 — May 26, 2026
|
|
89
|
+
|
|
90
|
+
Custom action handlers get the same typed ergonomics as generated CRUD paths:
|
|
91
|
+
typed Cloudflare bindings on `env`, a first-class typed `realtime` helper when
|
|
92
|
+
realtime is enabled, and no more `createRealtime(...)` boilerplate inside every
|
|
93
|
+
action just to emit an explicit broadcast.
|
|
94
|
+
|
|
95
|
+
### Neon compile output and local recompile state are now stable
|
|
96
|
+
|
|
97
|
+
The Neon + Cloudflare path now emits a correct runtime/output surface instead
|
|
98
|
+
of leaking SQLite-era state.
|
|
99
|
+
|
|
100
|
+
- `wrangler.toml` no longer emits a stray `[[d1_databases]]` block for Neon
|
|
101
|
+
projects
|
|
102
|
+
- repeated local Neon compiles now upload and sync the root PostgreSQL Drizzle
|
|
103
|
+
state correctly, so `drizzle-kit` can report "No schema changes" instead of
|
|
104
|
+
regenerating duplicate `0000_*.sql` files
|
|
105
|
+
- stale root Drizzle migrations from earlier bad compiles are pruned during the
|
|
106
|
+
compile/sync path
|
|
107
|
+
|
|
108
|
+
### Shared-target namespace hydration now works for bulk-grant lanes
|
|
109
|
+
|
|
110
|
+
Bulk-grant namespace callers (`{ roles: [...] }`, `{ team: true }`) now inherit
|
|
111
|
+
the namespace's shared hydration target when every relationship lane points at
|
|
112
|
+
the same resource load shape.
|
|
113
|
+
|
|
114
|
+
That fixes the case where a namespace like:
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
via: ['attendeeOf', 'organizerOf', { roles: ['admin', 'owner'] }]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
would authorize an org admin through the bulk lane but leave `ctx.event`
|
|
121
|
+
undefined, even though the sibling relationship lanes all hydrated the same
|
|
122
|
+
`events` row.
|
|
123
|
+
|
|
124
|
+
Runtime behavior is now split cleanly:
|
|
125
|
+
|
|
126
|
+
- **Shared target** — if all hydrating lanes share the same `loads`,
|
|
127
|
+
`exposeAs`, and resource key, hydration runs unconditionally after the gate
|
|
128
|
+
passes, so bulk callers get the same `ctx.<exposeAs>` as relationship callers
|
|
129
|
+
- **Distinct targets** — if lanes hydrate different tables / keys / ctx slots,
|
|
130
|
+
hydration stays per-matched-lane to avoid cross-table false 404s
|
|
131
|
+
|
|
132
|
+
Standalone action typing now matches that runtime behavior too: shared-target
|
|
133
|
+
hydration remains non-optional, while distinct-target multi-lane hydration stays
|
|
134
|
+
optional.
|
|
135
|
+
|
|
136
|
+
### Platform role split: `appmanager` for control-plane, `sysadmin` for cross-tenant
|
|
137
|
+
|
|
138
|
+
Quickback no longer treats `user.role === "admin"` as the platform-wide role.
|
|
139
|
+
The control-plane role is now `user.role === "appmanager"` (CMS shell, Better
|
|
140
|
+
Auth admin endpoints, support tooling), while `user.role === "sysadmin"`
|
|
141
|
+
remains the only true cross-tenant data-plane tier.
|
|
142
|
+
|
|
143
|
+
This also retires the `ADMIN` pseudo-role. Any `roles: ["ADMIN"]` usage now
|
|
144
|
+
fails the compile with migration guidance:
|
|
145
|
+
|
|
146
|
+
- `userRole: ["appmanager"]` for platform control-plane access
|
|
147
|
+
- `roles: ["admin"]` for org-membership admin access
|
|
148
|
+
- `roles: ["SYSADMIN"]` for true cross-tenant access
|
|
149
|
+
|
|
150
|
+
Runtime behavior now matches that split end-to-end:
|
|
151
|
+
|
|
152
|
+
- Better Auth's admin plugin is generated with `adminRoles: ["appmanager", "sysadmin"]`
|
|
153
|
+
- CMS / OpenAPI / auth-admin surfaces gate on `appmanager` (and admit
|
|
154
|
+
`sysadmin` where appropriate)
|
|
155
|
+
- unsafe cross-tenant actions and tenant-bypass helpers require `sysadmin` only
|
|
156
|
+
|
|
157
|
+
### Typed `env` + injected `realtime` in action handlers
|
|
158
|
+
|
|
159
|
+
The generated `<feature>/.quickback/define-action.ts` helper now types action
|
|
160
|
+
`env` from the project's runtime bindings surface instead of `any`, so custom
|
|
161
|
+
bindings like R2 buckets, queues, Durable Objects, auth env vars, and split DB
|
|
162
|
+
bindings no longer need `(env as any)` casts inside action handlers.
|
|
163
|
+
|
|
164
|
+
When realtime is enabled in config, action handlers also receive a typed
|
|
165
|
+
`realtime` helper directly in `execute(...)`. It exposes the same
|
|
166
|
+
`insert/update/delete/broadcast` methods as `createRealtime(env)`, but without
|
|
167
|
+
the extra import or hand-rolled factory call in every custom action.
|
|
168
|
+
|
|
169
|
+
This is a DX-only change. The auto-broadcast boundary is unchanged: generated
|
|
170
|
+
CRUD routes still broadcast automatically, while custom action writes still
|
|
171
|
+
broadcast explicitly.
|
|
172
|
+
|
|
173
|
+
### `generateId: "cuid"` docs now reflect the split runtime/schema behavior
|
|
174
|
+
|
|
175
|
+
Quickback's `cuid` strategy is now documented as the split path it actually is:
|
|
176
|
+
compiler-managed schema auto-injection keeps the `createId()` call site but may
|
|
177
|
+
back it with a file-local `crypto.randomUUID()` polyfill, while import-capable
|
|
178
|
+
runtime paths still emit real `createId()` usage.
|
|
179
|
+
|
|
180
|
+
That matters most for `compiler.injectId` and other schema-emission paths that
|
|
181
|
+
run in sandboxes where project `node_modules` are not visible. The generated
|
|
182
|
+
schema can safely keep:
|
|
183
|
+
|
|
184
|
+
```ts
|
|
185
|
+
id: text("id").primaryKey().$defaultFn(() => createId())
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
while satisfying the reference via:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
const createId = () => crypto.randomUUID();
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
instead of importing `@paralleldrive/cuid2` inside the schema-generation
|
|
195
|
+
environment.
|
|
196
|
+
|
|
197
|
+
**Important nuance:** this is not a guarantee that every generated id is a true
|
|
198
|
+
cuid2 string. Auto-injected schema paths may produce UUID-shaped strings
|
|
199
|
+
through the polyfill, while runtime paths that can import helpers may still use
|
|
200
|
+
real `createId()`. If you need strict cuid2 shape everywhere, explicitly import
|
|
201
|
+
`createId` from `@paralleldrive/cuid2` in the authored schema file; the
|
|
202
|
+
compiler preserves that import and skips the polyfill.
|
|
203
|
+
|
|
3
204
|
## v0.38.0 — May 26, 2026
|
|
4
205
|
|
|
5
206
|
**Per-matched-lane authorization** for multi-lane namespaces — across both the
|
|
@@ -70,7 +70,7 @@ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool na
|
|
|
70
70
|
`tools/list` only returns tools the calling identity could actually invoke. Each generated tool entry carries the operation's access metadata (`roles`, `userRole`, `or` / `and` combinators) and `tools/list` filters against `ctx` before responding:
|
|
71
71
|
|
|
72
72
|
- **Unauthenticated callers** see only tools whose access declares the `PUBLIC` pseudo-role, or operations that have no security requirement at all (e.g. sign-in / sign-up).
|
|
73
|
-
- **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`.
|
|
73
|
+
- **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Platform-operator endpoints don't appear for callers outside the required user roles.
|
|
74
74
|
- **Function-form access** (escape hatch) is opaque at list time — surfaced to any authenticated caller, then evaluated for real on `tools/call`.
|
|
75
75
|
- **Record predicates** are dropped from the list-time check (no record yet) and applied normally on the actual call.
|
|
76
76
|
|
|
@@ -125,7 +125,7 @@ export default defineConfig({
|
|
|
125
125
|
Both fields override compiler-emitted browser redirects in the CMS shell:
|
|
126
126
|
|
|
127
127
|
- **Unauthenticated visitor hits a CMS route** → `302 → <loginUrl>?redirect=<original-url>`
|
|
128
|
-
- **Authenticated user fails the `cms.access: 'admin'` role check** → `302 → <profileUrl>`
|
|
128
|
+
- **Authenticated user fails the `cms.access: 'admin'` platform-role check** → `302 → <profileUrl>`
|
|
129
129
|
|
|
130
130
|
The `?redirect=…` query param is preserved unchanged so the central sign-in surface can bounce the user back after authentication.
|
|
131
131
|
|
|
@@ -8,7 +8,6 @@ import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickb
|
|
|
8
8
|
export default defineConfig({
|
|
9
9
|
name: "my-app",
|
|
10
10
|
template: "hono",
|
|
11
|
-
features: { organizations: true },
|
|
12
11
|
providers: {
|
|
13
12
|
runtime: defineRuntime("cloudflare"),
|
|
14
13
|
database: defineDatabase("cloudflare-d1"),
|
|
@@ -87,7 +86,7 @@ quickback compile --no-sync-config
|
|
|
87
86
|
|
|
88
87
|
| Field | Type | Description |
|
|
89
88
|
|-------|------|-------------|
|
|
90
|
-
| `features` | `object` | Feature flags — see [
|
|
89
|
+
| `features` | `object` | Feature flags such as `pinnedOrganizationId` — see [Pinned Organization Mode](/compiler/config/single-tenant) |
|
|
91
90
|
| `build` | `object` | Build options (`outputDir`, `packageManager`, `dependencies`) |
|
|
92
91
|
| `compiler` | `object` | Compiler options — `features.auditFields: false` disables audit field injection project-wide; `migrations.renames` provides rename hints for headless CI; `securityContracts` tunes the route/SQL invariants checker |
|
|
93
92
|
| `openapi` | `object` | OpenAPI spec generation (`generate`, `publish`, `docs: 'scalar' \| 'swagger'` for an in-browser API reference) — see [OpenAPI](/compiler/targets/hono-api/using-the-api/openapi) |
|
|
@@ -304,8 +303,8 @@ cms: { domain: "cms.example.com", sysadmin: true },
|
|
|
304
303
|
| Option | Type | Default | Description |
|
|
305
304
|
|--------|------|---------|-------------|
|
|
306
305
|
| `domain` | `string` | — | Custom domain for CMS. Adds a `custom_domain` route to `wrangler.toml`. |
|
|
307
|
-
| `access` | `"user" \| "admin"` | `"
|
|
308
|
-
| `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"
|
|
306
|
+
| `access` | `"user" \| "admin"` | `"admin"` | Controls who can access the CMS. When `"admin"`, platform control-plane users (`user.role === "appmanager"`) can enter; when `sysadmin` mode is also on, `user.role === "sysadmin"` is admitted too. The gate is enforced at the Worker level (SPA shell, `/api/v1/schema`, and `custom_view` CRUD all return 403 to callers outside those roles) and in the SPA. Also hides the CMS link in Account UI. See [CMS Connecting](/stack/cms/connecting) for the full enforcement model. |
|
|
307
|
+
| `sysadmin` | `boolean` | `false` | Cross-tenant DB-admin tier. When `true`, opts into the `SYSADMIN` pseudo-role (`user.role === "sysadmin"`), the firewall escape hatch (sysadmins bypass tenant scopes, soft-delete still enforced), the cross-tenant `/auth/v1/admin/list-organizations` endpoint (sibling of Better Auth's `/auth/v1/admin/list-users`, gated to sysadmin only), and the SPA's "All organizations" sentinel. The CMS HTML gate admits `userRole === "sysadmin"` alongside `"appmanager"`. Off by default. See [`SYSADMIN` pseudo-role](/compiler/definitions/access#sysadmin--cross-tenant-db-admin-tier). |
|
|
309
308
|
|
|
310
309
|
### Sysadmin tier (`cms.sysadmin: true`)
|
|
311
310
|
|
|
@@ -313,11 +312,11 @@ Quickback's default model assumes every CMS user belongs to at least one organiz
|
|
|
313
312
|
|
|
314
313
|
`cms: { sysadmin: true }` introduces a separate role tier:
|
|
315
314
|
|
|
316
|
-
- **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"
|
|
315
|
+
- **Role**: `user.role === "sysadmin"` (set on the Better Auth user table). Distinct from `"appmanager"` — appmanagers keep platform control-plane access (CMS shell, Better Auth admin surfaces, support tooling), while sysadmins get true cross-tenant data access. `ADMIN` is now a rejected legacy pseudo-role; use `userRole: ["appmanager"]` for control-plane gates and `roles: ["SYSADMIN"]` for cross-tenant access.
|
|
317
316
|
- **Firewall**: every `buildFirewallConditions()` emits an `if (ctx.userRole === "sysadmin") return undefined` (or just the soft-delete predicate when present) at the top, so sysadmins see every tenant's rows. See [Firewall escape hatch](/compiler/definitions/firewall#sysadmin-escape-hatch).
|
|
318
317
|
- **Org listing**: a `GET /auth/v1/admin/list-organizations` endpoint selects directly from the auth-schema `organization` table — every row, every tenant. Sits under Better Auth's admin URL namespace (sibling of `/auth/v1/admin/list-users`) so the URL shape matches BA convention; the handler is Quickback-emitted and gated to `user.role === "sysadmin"` only. For the membership-bound caller's-orgs listing, use BA's own `/auth/v1/organization/list`.
|
|
319
318
|
- **CMS SPA**: when the user is a sysadmin, the header switcher loads from the cross-tenant endpoint, defaults to "All organizations" (which omits `?organizationId=` and reaches the firewall escape), and pins selected tenants via `?organizationId=` on every API call. Org admins keep the existing membership-based switcher.
|
|
320
|
-
- **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"
|
|
319
|
+
- **CMS HTML gate**: admits `userRole === "sysadmin"` alongside `"appmanager"`. Org admins are not locked out when you set `cms.access: "user"`; `cms.access: "admin"` is specifically the platform control-plane gate.
|
|
321
320
|
|
|
322
321
|
Off by default. Projects that don't enable it get zero behavior change; setting `cms.sysadmin: true` and granting a user `user.role = "sysadmin"` is the only way to unlock the cross-tenant view.
|
|
323
322
|
|
|
@@ -369,8 +368,8 @@ Control which authentication features are exposed. Disabled features are exclude
|
|
|
369
368
|
| `auth.emailOTP` | `boolean` | `false` | adds `emailOtp` plugin | Email one-time password login — adds plugin server-side, surfaces UI |
|
|
370
369
|
| `auth.passkey` | `boolean` | `false` | adds `passkey` plugin | WebAuthn/FIDO2 passkey authentication — adds plugin server-side, surfaces UI |
|
|
371
370
|
| `auth.signup` | `boolean` | `true` | `emailAndPassword.disableSignUp` (inverted) | Self-service account registration — false hides the UI **and** rejects the server endpoint with 403 |
|
|
372
|
-
| `auth.organizations` | `boolean` | `
|
|
373
|
-
| `auth.admin` | `boolean` | `false` | UI surface only
|
|
371
|
+
| `auth.organizations` | `boolean` | `true` | UI surface only | Organization management UI (dashboard, invitations, roles). Server-side organization support stays on regardless; set `features.pinnedOrganizationId` when you want one fixed org with no switching UI |
|
|
372
|
+
| `auth.admin` | `boolean` | `false` | UI surface only | Admin panel for user management in the Account SPA. The Better Auth admin plugin is compiler-managed separately from this UI toggle |
|
|
374
373
|
| `auth.emailVerification` | `boolean` | `false` | `emailAndPassword.requireEmailVerification` | Require email verification before sessions are issued. False = sessions usable immediately after signup |
|
|
375
374
|
|
|
376
375
|
## Trusted Origins
|
|
@@ -506,5 +505,5 @@ See the sub-pages for detailed reference on each section:
|
|
|
506
505
|
- [Providers](/compiler/config/providers) — Runtime, database, and auth options
|
|
507
506
|
- [Variables](/compiler/config/variables) — Environment variables and flags
|
|
508
507
|
- [Output](/compiler/config/output) — Generated file structure
|
|
509
|
-
- [
|
|
508
|
+
- [Pinned Organization Mode](/compiler/config/single-tenant) — Fixed-org deployments without org switching UI
|
|
510
509
|
- [Multi-Domain Architecture](/compiler/config/domains) — Custom domains, hostname routing, and cross-subdomain auth
|
|
@@ -226,6 +226,9 @@ See [Realtime](/stack/realtime) for the client-side connection flow and helper e
|
|
|
226
226
|
> `"short"` produces IDs with ~56.8 billion possible values (62^6). That's fine for small/scoped tables like rooms, invites, or share codes — but at roughly 238,000 rows you hit a 50% chance of collision (birthday bound). Don't use it for high-volume records. `"nanoid"` and `"short"` both require the `nanoid` package in your project.
|
|
227
227
|
|
|
228
228
|
|
|
229
|
+
> `generateId: "cuid"` is not byte-for-byte uniform across every compiler path. Import-capable runtime paths emit real `createId()` usage, but compiler-managed schema auto-injection may preserve the `createId()` call site with a file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes stay dependency-free. If you require true cuid2 strings everywhere, explicitly import `createId` from `@paralleldrive/cuid2` in the authored schema file.
|
|
230
|
+
|
|
231
|
+
|
|
229
232
|
## Auth Providers
|
|
230
233
|
|
|
231
234
|
| Provider | Description |
|
|
@@ -1,10 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Pinned Organization Mode
|
|
2
2
|
|
|
3
|
-
Single-tenant mode
|
|
3
|
+
Single-tenant mode has been removed. If you want a one-org deployment without org switching overhead, use `features.pinnedOrganizationId` instead.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Pinned organization mode keeps Better Auth's organization plugin, organization membership roles, and org-scoped firewalls enabled. The only difference is that Quickback hard-codes one active organization id at runtime and hides the switching UI.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Enabling Pinned Organization Mode
|
|
8
|
+
|
|
9
|
+
Set a real organization id in your config:
|
|
8
10
|
|
|
9
11
|
```typescript
|
|
10
12
|
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
@@ -13,7 +15,7 @@ export default defineConfig({
|
|
|
13
15
|
name: "my-site",
|
|
14
16
|
template: "hono",
|
|
15
17
|
features: {
|
|
16
|
-
|
|
18
|
+
pinnedOrganizationId: "org_123",
|
|
17
19
|
},
|
|
18
20
|
providers: {
|
|
19
21
|
runtime: defineRuntime("cloudflare"),
|
|
@@ -23,100 +25,90 @@ export default defineConfig({
|
|
|
23
25
|
});
|
|
24
26
|
```
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
> **Use a Real Organization ID**
|
|
29
|
+
>
|
|
30
|
+
> `pinnedOrganizationId` must point at an organization that actually exists in your Better Auth data. The compiler does not create the organization for you.
|
|
27
31
|
|
|
28
|
-
| Aspect | Multi-Tenant (default) | Single-Tenant |
|
|
29
|
-
|--------|----------------------|---------------|
|
|
30
|
-
| Organization plugin | Enabled | Disabled |
|
|
31
|
-
| `organizationId` columns | Required on resources | Not used |
|
|
32
|
-
| Role source | Org membership table | `user.role` field |
|
|
33
|
-
| Firewall scopes | `owner`, `organization`, `team`, `exception` | `owner`, `exception` only |
|
|
34
|
-
| Admin org endpoints | Use Better Auth's `/auth/v1/organization/list` (caller's orgs) and `/auth/v1/admin/list-organizations` when `cms.sysadmin: true` (cross-tenant) | N/A (no org plugin) |
|
|
35
|
-
| `ctx.activeOrgId` | From session/JWT | Always `undefined` |
|
|
36
|
-
| `ctx.roles` | From org member role | From `user.role` |
|
|
37
32
|
|
|
38
|
-
##
|
|
33
|
+
## Removed Single-Tenant Settings
|
|
39
34
|
|
|
40
|
-
|
|
35
|
+
These older settings now fail the compile with a migration error:
|
|
41
36
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],
|
|
46
|
-
read: {
|
|
47
|
-
access: { roles: ['user', 'admin'] },
|
|
48
|
-
},
|
|
49
|
-
create: { access: { roles: ['admin'] } },
|
|
50
|
-
});
|
|
37
|
+
- `features.organizations: false`
|
|
38
|
+
- `providers.database.config.organizations: false`
|
|
39
|
+
- `providers.auth.config.plugins.organization = false`
|
|
51
40
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
read: {
|
|
56
|
-
access: { roles: ['PUBLIC'] },
|
|
57
|
-
},
|
|
58
|
-
create: { access: { roles: ['admin'] } },
|
|
59
|
-
update: { access: { roles: ['admin'] } },
|
|
60
|
-
delete: { access: { roles: ['admin'] } },
|
|
61
|
-
});
|
|
62
|
-
```
|
|
41
|
+
Replace them with `features.pinnedOrganizationId`.
|
|
42
|
+
|
|
43
|
+
## What Changes
|
|
63
44
|
|
|
64
|
-
|
|
45
|
+
| Aspect | Default Org Mode | Pinned Organization Mode |
|
|
46
|
+
|--------|------------------|--------------------------|
|
|
47
|
+
| Organization plugin | Enabled | Enabled |
|
|
48
|
+
| Role source | Org membership table | Org membership table in the pinned org |
|
|
49
|
+
| Firewall scopes | `owner`, `organization`, `team`, `exception` | Same |
|
|
50
|
+
| `ctx.activeOrgId` | From session / JWT / API key context | Always the configured org id |
|
|
51
|
+
| CMS org selector | Visible when caller can switch orgs | Hidden |
|
|
52
|
+
| CMS org gate | Requires an active org selection | Bypassed; pinned org is injected automatically |
|
|
65
53
|
|
|
54
|
+
## Access and Roles
|
|
66
55
|
|
|
67
|
-
|
|
56
|
+
Pinned organization mode does **not** bring back the old `user.role` mirror on `ctx.roles`.
|
|
68
57
|
|
|
69
|
-
Use
|
|
58
|
+
- Use `roles: ["owner" | "admin" | "member"]` for data-plane access based on membership in the pinned org.
|
|
59
|
+
- Use `userRole: [...]` for platform-wide Better Auth roles stored on `user.role` (`appmanager`, `sysadmin`, etc.).
|
|
70
60
|
|
|
71
61
|
```typescript
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
62
|
+
export default defineActions({
|
|
63
|
+
publish: {
|
|
64
|
+
access: {
|
|
65
|
+
or: [
|
|
66
|
+
{ roles: ["admin"] }, // admin in the pinned org
|
|
67
|
+
{ userRole: ["appmanager"] }, // platform control-plane role
|
|
68
|
+
],
|
|
69
|
+
},
|
|
70
|
+
execute: async () => ({ ok: true }),
|
|
71
|
+
},
|
|
72
|
+
});
|
|
76
73
|
```
|
|
77
74
|
|
|
78
|
-
##
|
|
75
|
+
## Firewalls and Resource Scopes
|
|
79
76
|
|
|
80
|
-
|
|
77
|
+
Organization-scoped resources keep working in pinned mode. `q.scope("organization")`, `q.scope("team")`, and any firewall predicate that references `ctx.activeOrgId` still compile and run normally — they just see the pinned organization id instead of a user-selected one.
|
|
81
78
|
|
|
82
|
-
|
|
79
|
+
Owner-scoped and public resources are unchanged.
|
|
83
80
|
|
|
81
|
+
## CMS Behavior
|
|
84
82
|
|
|
83
|
+
When `features.pinnedOrganizationId` is set:
|
|
85
84
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
| `PUBLIC` | Unauthenticated access (special keyword) |
|
|
85
|
+
- the CMS hides the org switcher
|
|
86
|
+
- the CMS skips the org-selection gate
|
|
87
|
+
- API calls and realtime connections use the pinned org automatically
|
|
88
|
+
- role checks still come from the caller's membership in that org
|
|
91
89
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
},
|
|
101
|
-
},
|
|
102
|
-
});
|
|
103
|
-
```
|
|
90
|
+
This is the intended replacement for the old single-tenant CMS flow.
|
|
91
|
+
|
|
92
|
+
## Migration from Single-Tenant Mode
|
|
93
|
+
|
|
94
|
+
1. Remove `features.organizations: false`.
|
|
95
|
+
2. Add `features.pinnedOrganizationId: "<real-org-id>"`.
|
|
96
|
+
3. Remove any assumptions that `ctx.roles` mirrors `user.role`.
|
|
97
|
+
4. If you need platform-wide roles, keep those checks on `userRole`, not `roles`.
|
|
104
98
|
|
|
105
99
|
## Consuming the API
|
|
106
100
|
|
|
107
|
-
|
|
101
|
+
Pinned organization mode still produces the same JSON API shape. Pair it with any frontend framework:
|
|
108
102
|
|
|
109
103
|
```typescript
|
|
110
|
-
|
|
111
|
-
const posts = await fetch('https://api.mysite.com/api/v1/posts').then(r => r.json());
|
|
104
|
+
const posts = await fetch("https://api.mysite.com/api/v1/posts").then((r) => r.json());
|
|
112
105
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
method: 'POST',
|
|
106
|
+
const res = await fetch("https://api.mysite.com/api/v1/posts", {
|
|
107
|
+
method: "POST",
|
|
116
108
|
headers: {
|
|
117
|
-
|
|
118
|
-
|
|
109
|
+
Authorization: `Bearer ${token}`,
|
|
110
|
+
"Content-Type": "application/json",
|
|
119
111
|
},
|
|
120
|
-
body: JSON.stringify({ title:
|
|
112
|
+
body: JSON.stringify({ title: "New Post", content: "..." }),
|
|
121
113
|
});
|
|
122
114
|
```
|