@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.
Files changed (109) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +36 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/commands/compile.test.d.ts +2 -0
  5. package/dist/commands/compile.test.d.ts.map +1 -0
  6. package/dist/commands/compile.test.js +83 -0
  7. package/dist/commands/compile.test.js.map +1 -0
  8. package/dist/commands/create.js +15 -11
  9. package/dist/commands/create.js.map +1 -1
  10. package/dist/commands/migrations.d.ts +33 -0
  11. package/dist/commands/migrations.d.ts.map +1 -1
  12. package/dist/commands/migrations.js +41 -2
  13. package/dist/commands/migrations.js.map +1 -1
  14. package/dist/commands/migrations.test.d.ts +2 -0
  15. package/dist/commands/migrations.test.d.ts.map +1 -0
  16. package/dist/commands/migrations.test.js +67 -0
  17. package/dist/commands/migrations.test.js.map +1 -0
  18. package/dist/docs/content.js +24 -24
  19. package/dist/docs/content.js.map +1 -1
  20. package/dist/examples/recruitment.tar.gz +0 -0
  21. package/dist/index.js +1 -1
  22. package/dist/lib/action-harvest.d.ts +48 -0
  23. package/dist/lib/action-harvest.d.ts.map +1 -0
  24. package/dist/lib/action-harvest.js +292 -0
  25. package/dist/lib/action-harvest.js.map +1 -0
  26. package/dist/lib/action-harvest.test.d.ts +2 -0
  27. package/dist/lib/action-harvest.test.d.ts.map +1 -0
  28. package/dist/lib/action-harvest.test.js +112 -0
  29. package/dist/lib/action-harvest.test.js.map +1 -0
  30. package/dist/lib/api-client.d.ts +10 -0
  31. package/dist/lib/api-client.d.ts.map +1 -1
  32. package/dist/lib/api-client.js +17 -1
  33. package/dist/lib/api-client.js.map +1 -1
  34. package/dist/lib/api-client.test.js +19 -0
  35. package/dist/lib/api-client.test.js.map +1 -1
  36. package/dist/lib/artifact-routing.d.ts +1 -0
  37. package/dist/lib/artifact-routing.d.ts.map +1 -1
  38. package/dist/lib/artifact-routing.js +15 -3
  39. package/dist/lib/artifact-routing.js.map +1 -1
  40. package/dist/lib/artifact-routing.test.js +12 -1
  41. package/dist/lib/artifact-routing.test.js.map +1 -1
  42. package/dist/lib/file-loader.d.ts +1 -0
  43. package/dist/lib/file-loader.d.ts.map +1 -1
  44. package/dist/lib/file-loader.js +34 -1
  45. package/dist/lib/file-loader.js.map +1 -1
  46. package/dist/lib/file-loader.test.js +28 -4
  47. package/dist/lib/file-loader.test.js.map +1 -1
  48. package/dist/lib/prepare-state-output.d.ts +8 -0
  49. package/dist/lib/prepare-state-output.d.ts.map +1 -0
  50. package/dist/lib/prepare-state-output.js +17 -0
  51. package/dist/lib/prepare-state-output.js.map +1 -0
  52. package/dist/lib/prepare-state-output.test.d.ts +2 -0
  53. package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
  54. package/dist/lib/prepare-state-output.test.js +31 -0
  55. package/dist/lib/prepare-state-output.test.js.map +1 -0
  56. package/dist/skill/SKILL.md +1 -1
  57. package/dist/skill/docs/changelog.md +201 -0
  58. package/dist/skill/docs/compiler/config/agents.md +1 -1
  59. package/dist/skill/docs/compiler/config/auth.md +1 -1
  60. package/dist/skill/docs/compiler/config/index.md +8 -9
  61. package/dist/skill/docs/compiler/config/providers.md +3 -0
  62. package/dist/skill/docs/compiler/config/single-tenant.md +65 -73
  63. package/dist/skill/docs/compiler/definitions/access.md +40 -33
  64. package/dist/skill/docs/compiler/definitions/actions.md +1 -1
  65. package/dist/skill/docs/compiler/definitions/firewall.md +1 -1
  66. package/dist/skill/docs/compiler/definitions/schema.md +8 -2
  67. package/dist/skill/docs/compiler/getting-started/template-blog.md +7 -7
  68. package/dist/skill/docs/compiler/getting-started/template-empty.md +1 -4
  69. package/dist/skill/docs/compiler/getting-started/templates.md +6 -6
  70. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  71. package/dist/skill/docs/stack/account-ui/features/admin.md +1 -1
  72. package/dist/skill/docs/stack/account-ui/features/index.md +2 -2
  73. package/dist/skill/docs/stack/cms/connecting.md +17 -16
  74. package/dist/skill/docs/stack/cms/index.md +7 -7
  75. package/dist/skill/docs/stack/cms/schema-format.md +0 -2
  76. package/dist/skill/docs/stack/cms/schema-registry.md +0 -6
  77. package/dist/skill/docs/stack/cms/security.md +6 -6
  78. package/dist/skill/docs/stack/realtime/durable-objects.md +5 -7
  79. package/dist/skill/docs/stack/storage/r2.md +112 -3
  80. package/dist/skill/docs/stack/storage/using-r2.md +30 -10
  81. package/dist/templates/registry.js +2 -2
  82. package/dist/templates/registry.js.map +1 -1
  83. package/package.json +1 -1
  84. package/src/examples/recruitment.tar.gz +0 -0
  85. package/src/skill/SKILL.md +1 -1
  86. package/src/skill/docs/changelog.md +201 -0
  87. package/src/skill/docs/compiler/config/agents.md +1 -1
  88. package/src/skill/docs/compiler/config/auth.md +1 -1
  89. package/src/skill/docs/compiler/config/index.md +8 -9
  90. package/src/skill/docs/compiler/config/providers.md +3 -0
  91. package/src/skill/docs/compiler/config/single-tenant.md +65 -73
  92. package/src/skill/docs/compiler/definitions/access.md +40 -33
  93. package/src/skill/docs/compiler/definitions/actions.md +1 -1
  94. package/src/skill/docs/compiler/definitions/firewall.md +1 -1
  95. package/src/skill/docs/compiler/definitions/schema.md +8 -2
  96. package/src/skill/docs/compiler/getting-started/template-blog.md +7 -7
  97. package/src/skill/docs/compiler/getting-started/template-empty.md +1 -4
  98. package/src/skill/docs/compiler/getting-started/templates.md +6 -6
  99. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +2 -2
  100. package/src/skill/docs/stack/account-ui/features/admin.md +1 -1
  101. package/src/skill/docs/stack/account-ui/features/index.md +2 -2
  102. package/src/skill/docs/stack/cms/connecting.md +17 -16
  103. package/src/skill/docs/stack/cms/index.md +7 -7
  104. package/src/skill/docs/stack/cms/schema-format.md +0 -2
  105. package/src/skill/docs/stack/cms/schema-registry.md +0 -6
  106. package/src/skill/docs/stack/cms/security.md +6 -6
  107. package/src/skill/docs/stack/realtime/durable-objects.md +5 -7
  108. package/src/skill/docs/stack/storage/r2.md +112 -3
  109. package/src/skill/docs/stack/storage/using-r2.md +30 -10
@@ -1,10 +1,12 @@
1
- # Single-Tenant Mode
1
+ # Pinned Organization Mode
2
2
 
3
- Single-tenant mode disables the Better Auth organization plugin, removing the `organizationId` requirement from your API. This is ideal for personal sites, blogs, admin panels, or any app with a single tenant.
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
- ## Enabling Single-Tenant Mode
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
- Set `features.organizations` to `false` in your config:
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
- organizations: false,
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
- ## What Changes
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
- ## Firewall Configuration
33
+ ## Removed Single-Tenant Settings
39
34
 
40
- In single-tenant mode, resources use either **owner** scope (user-scoped data) or **exception** (public/system data):
35
+ These older settings now fail the compile with a migration error:
41
36
 
42
- ```typescript
43
- // User-scoped data (requires authentication)
44
- export default defineTable(posts, {
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
- // Public data (no ownership filtering)
53
- export default defineTable(pages, {
54
- firewall: [{ exception: true }],
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
- > Using `q.scope('organization')` / `q.scope('team')` (or any firewall predicate referencing `ctx.activeOrgId` / `ctx.activeTeamId`) with `organizations: false` will cause a compile error. These scopes require the organization plugin.
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
- ## Public Routes
56
+ Pinned organization mode does **not** bring back the old `user.role` mirror on `ctx.roles`.
68
57
 
69
- Use the `PUBLIC` role to expose routes without authentication. This works the same as in multi-tenant mode:
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
- read: {
73
- access: { roles: ['PUBLIC'] }, // GET / and GET /:id — no auth required
74
- },
75
- create: { access: { roles: ['admin'] } }, // Admin only
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
- ## Role-Based Access
75
+ ## Firewalls and Resource Scopes
79
76
 
80
- Roles come from the `user.role` field (managed by Better Auth's [admin plugin](https://www.better-auth.com/docs/plugins/admin)).
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
- > In single-tenant mode `ctx.roles` mirrors `user.role`, so `roles: ["admin"]` and `userRole: ["admin"]` behave the same. Prefer [`userRole`](/compiler/definitions/access#userrole-vs-roles) — it documents intent and keeps the gate correct if you later enable multi-tenant.
79
+ Owner-scoped and public resources are unchanged.
83
80
 
81
+ ## CMS Behavior
84
82
 
83
+ When `features.pinnedOrganizationId` is set:
85
84
 
86
- | Role | Description |
87
- |------|-------------|
88
- | `admin` | Full access, set via Better Auth admin plugin |
89
- | `user` | Default role for authenticated users |
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
- ```typescript
93
- // Admin-only action
94
- export default defineActions({
95
- publish: {
96
- access: { roles: ['admin'] },
97
- execute: async ({ ctx, db }) => {
98
- // ctx.userRole === 'admin'
99
- // ctx.roles === ['admin']
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
- Since single-tenant mode produces a JSON API, pair it with any frontend framework:
101
+ Pinned organization mode still produces the same JSON API shape. Pair it with any frontend framework:
108
102
 
109
103
  ```typescript
110
- // Astro, Next.js, SvelteKit, etc.
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
- // Admin operations require authentication
114
- const res = await fetch('https://api.mysite.com/api/v1/posts', {
115
- method: 'POST',
106
+ const res = await fetch("https://api.mysite.com/api/v1/posts", {
107
+ method: "POST",
116
108
  headers: {
117
- 'Authorization': `Bearer ${token}`,
118
- 'Content-Type': 'application/json',
109
+ Authorization: `Bearer ${token}`,
110
+ "Content-Type": "application/json",
119
111
  },
120
- body: JSON.stringify({ title: 'New Post', content: '...' }),
112
+ body: JSON.stringify({ title: "New Post", content: "..." }),
121
113
  });
122
114
  ```
@@ -56,7 +56,7 @@ delete: { access: { roles: ["owner"] } }, // owner only (no +)
56
56
  The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
57
57
 
58
58
  - Roles without `+` are exact matches (no expansion)
59
- - Pseudo-roles (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
59
+ - Pseudo-roles / reserved markers (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
60
60
  - Using `+` with a role not in the hierarchy throws a compile error
61
61
  - Using `+` without configuring `auth.roleHierarchy` throws a compile error
62
62
 
@@ -89,50 +89,50 @@ interface Access {
89
89
 
90
90
  | Primitive | Checks | Source | Example values |
91
91
  |-----------|--------|--------|----------------|
92
- | `roles` | `ctx.roles` | Org membership (multi-tenant) or single-tenant mirror of `user.role` | `"owner"`, `"admin"`, `"member"` |
93
- | `userRole` | `ctx.userRole` | The `user.role` column (Better Auth admin plugin) | `"user"`, `"admin"` |
92
+ | `roles` | `ctx.roles` | Org membership roles | `"owner"`, `"admin"`, `"member"` |
93
+ | `userRole` | `ctx.userRole` | The `user.role` column (Better Auth / platform control-plane roles) | `"user"`, `"appmanager"`, `"sysadmin"` |
94
94
 
95
- In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide admin.** An org-admin of Acme Corp has no elevated rights across other orgs. If you want to let Better Auth system admins through regardless of org membership (e.g., for support/ops), use `userRole: ["admin"]`.
95
+ In multi-tenant mode, **`roles: ["admin"]` means "org admin" — not a platform-wide role.** An org-admin of Acme Corp has no elevated rights across other orgs. If you want platform control-plane operators through regardless of org membership (CMS, Better Auth admin surfaces, support tooling), use `userRole: ["appmanager"]`. If you need true cross-tenant data-plane access, use `roles: ["SYSADMIN"]` (with `cms: { sysadmin: true }`).
96
96
 
97
- In single-tenant mode (`features.organizations: false`), `ctx.roles` mirrors `user.role`, so `roles: ["admin"]` and `userRole: ["admin"]` behave the same. Using `userRole` in single-tenant code is still preferred — it documents intent and keeps the gate correct if you later enable orgs.
97
+ Pinned organization mode does not change this split. `roles` still come from organization membership in the pinned org, while `userRole` still comes from Better Auth's `user.role` column.
98
98
 
99
99
  ### When to use `userRole`
100
100
 
101
101
  ```typescript
102
- // Platform admin can see SSNs on every customer record, regardless of org
102
+ // Platform control-plane users can see SSNs on every customer record, regardless of org
103
103
  masking: {
104
- ssn: { type: 'ssn', show: { userRole: ['admin'] } },
104
+ ssn: { type: 'ssn', show: { userRole: ['appmanager'] } },
105
105
  }
106
106
 
107
- // Support staff (user.role === 'admin') OR the org owner can refund
107
+ // Platform ops (user.role === 'appmanager') OR the org owner can refund
108
108
  access: {
109
109
  or: [
110
- { userRole: ['admin'] },
110
+ { userRole: ['appmanager'] },
111
111
  { roles: ['owner'] },
112
112
  ],
113
113
  }
114
114
 
115
- // CMS-internal resource: only platform admins
116
- read: { access: { userRole: ['admin'] } },
117
- create: { access: { userRole: ['admin'] } },
118
- update: { access: { userRole: ['admin'] } },
119
- delete: { access: { userRole: ['admin'] } },
115
+ // CMS-internal resource: only platform control-plane users
116
+ read: { access: { userRole: ['appmanager'] } },
117
+ create: { access: { userRole: ['appmanager'] } },
118
+ update: { access: { userRole: ['appmanager'] } },
119
+ delete: { access: { userRole: ['appmanager'] } },
120
120
  ```
121
121
 
122
122
  When `roles` and `userRole` both appear in a single `Access` node, they're combined with AND — the user must satisfy both. Use `or:` to express "one or the other".
123
123
 
124
- `userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"` and `"admin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
124
+ `userRole` doesn't expand with the `+` hierarchy suffix — user-table roles are flat (typically just `"user"`, `"appmanager"`, and `"sysadmin"`). If you've added custom user-table roles via Better Auth, list them explicitly.
125
125
 
126
126
  ### Pseudo-roles
127
127
 
128
- Quickback ships five UPPERCASE role markers that are **not backed by a Better Auth role column** — they're system-level shortcuts handled directly by the compiler. The casing carries the boundary: UPPERCASE = pseudo-role (no plugin context required), lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
128
+ Quickback ships five reserved UPPERCASE markers. Four are real pseudo-roles handled directly by the compiler; `ADMIN` is retained only as a reserved legacy marker so the compiler can fail loudly with migration guidance. The casing carries the boundary: UPPERCASE = compiler-owned marker, lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
129
129
 
130
130
  | Role | Auth gate | Compile-time requirement | Runtime check |
131
131
  |------|-----------|-------------------------|---------------|
132
132
  | `PUBLIC` | bypassed | none — explicit opt-in for unauthenticated access | always passes (auth skipped) |
133
133
  | `AUTHENTICATED` | required | none | `ctx.authenticated === true` |
134
134
  | `USER` | required | resource firewall **must** scope by `userId` | `ctx.authenticated` AND (`ctx.userRole` is unset OR `ctx.userRole === "user"`) |
135
- | `ADMIN` | required | Better Auth admin plugin **must** be enabled | `ctx.authenticated && ctx.userRole === "admin"` |
135
+ | `ADMIN` | required | reserved legacy marker — compiler rejects it | `false` |
136
136
  | `SYSADMIN` | required | `cms: { sysadmin: true }` **must** be set on the project | `ctx.authenticated && ctx.userRole === "sysadmin"` |
137
137
 
138
138
  You can mix pseudo-roles with real roles in the same list — they're OR'd together.
@@ -198,18 +198,22 @@ If you forget the `userId` firewall predicate, the compiler throws:
198
198
 
199
199
  > `roles: ["USER"]` requires the resource to be scoped per-user. Add a `userId` column (auto-scoped) or an explicit owner predicate. If you want any signed-in user to read all records, use `roles: ["AUTHENTICATED"]` instead.
200
200
 
201
- When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically — admins are excluded and should use `["USER", "ADMIN"]` if the same route should serve both.
201
+ When the Better Auth admin plugin is enabled, `USER` matches `user.role === "user"` specifically — appmanagers and sysadmins are excluded. If the same route should serve both, express it explicitly with `or: [{ roles: ["USER"] }, { userRole: ["appmanager"] }]`.
202
202
 
203
- #### `ADMIN` — Better Auth admin-plugin admins
203
+ #### `ADMIN` — legacy reserved marker (compile-time error)
204
204
 
205
- Use `roles: ["ADMIN"]` for system-administrator endpoints. **Requires the Better Auth admin plugin** so `user.role` exists. Compiles to `ctx.userRole === "admin"`.
205
+ `roles: ["ADMIN"]` is no longer supported. The compiler fails hard on any use of `ADMIN` so platform and tenant roles can't be confused.
206
206
 
207
207
  ```typescript
208
- // Platform-admin-only audit log
209
- read: { access: { roles: ["ADMIN"] } }
208
+ // Platform control-plane audit log
209
+ read: { access: { userRole: ["appmanager"] } }
210
210
  ```
211
211
 
212
- Without the admin plugin you get a compile error pointing you to either enable the plugin or use lowercase `roles: ["admin"]` (the org-membership admin role).
212
+ Use one of these instead:
213
+
214
+ - `userRole: ["appmanager"]` for platform control-plane access
215
+ - `roles: ["admin"]` for org-membership admin access
216
+ - `roles: ["SYSADMIN"]` for true cross-tenant access
213
217
 
214
218
  #### `SYSADMIN` — cross-tenant DB-admin tier
215
219
 
@@ -220,23 +224,23 @@ Use `roles: ["SYSADMIN"]` for endpoints that should only be reachable by platfor
220
224
  read: { access: { roles: ["SYSADMIN"] } }
221
225
  ```
222
226
 
223
- `ADMIN` and `SYSADMIN` are **independent** at the evaluator level — `ADMIN` admits `userRole === 'admin'` only, `SYSADMIN` admits `userRole === 'sysadmin'` only. Routes that need both write `access: { roles: ['ADMIN', 'SYSADMIN'] }` explicitly. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, 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, not just their own org's. That escape hatch does NOT fire for `userRole === 'admin'`; admins still go through the firewall like everyone else.
227
+ `SYSADMIN` is distinct from `userRole: ["appmanager"]`. Appmanager is the platform control-plane tier (CMS shell, Better Auth admin surfaces, support tooling); sysadmin is the cross-tenant data-plane tier. The one place sysadmin gets implicit extra powers is **the firewall escape hatch**: when `cms.sysadmin: true`, 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, not just their own org's. That escape hatch does NOT fire for `userRole === 'appmanager'`; appmanagers still go through the firewall like everyone else.
224
228
 
225
- This separation exists so Better Auth admin-plugin powers (user management, impersonation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'admin'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/auth/v1/admin/list-organizations` endpoint, and the SPA's "All organizations" sentinel.
229
+ This separation exists so Better Auth admin-plugin powers (user management, impersonation, org creation) and DB-admin powers (cross-tenant data inspection) stay decoupled. A user can have `user.role === 'appmanager'` without DB-level cross-tenant access; a user can have `user.role === 'sysadmin'` without org-membership context. See [CMS Configuration](/compiler/config#cms-configuration) for the `cms.sysadmin` flag, the cross-tenant `/auth/v1/admin/list-organizations` endpoint, and the SPA's "All organizations" sentinel.
226
230
 
227
231
  #### Mixing pseudo-roles with real roles
228
232
 
229
233
  Pseudo-roles and lowercase real roles compose with OR:
230
234
 
231
235
  ```typescript
232
- // Record owner OR a system admin can read
233
- read: { access: { roles: ["USER", "ADMIN"] } }
236
+ // Record owner OR a platform control-plane user can read
237
+ read: { access: { or: [{ roles: ["USER"] }, { userRole: ["appmanager"] }] } }
234
238
 
235
- // Org owner OR system admin
236
- delete: { access: { roles: ["owner", "ADMIN"] } }
239
+ // Org owner OR sysadmin
240
+ delete: { access: { or: [{ roles: ["owner"] }, { roles: ["SYSADMIN"] }] } }
237
241
  ```
238
242
 
239
- > Note: today, an `ADMIN` match still goes through the `userId` firewall scope on USER-scoped resources — admins see only records they own on those routes. Use `firewall: { exception: true }` on a separate admin-only route if you need cross-user visibility.
243
+ > Note: `userRole: ["appmanager"]` never bypasses a `userId` firewall scope. If you need cross-user visibility, expose a separate route with `firewall: { exception: true }` or a `SYSADMIN`-gated cross-tenant surface.
240
244
 
241
245
  #### Quick reference
242
246
 
@@ -250,8 +254,11 @@ access: { roles: ["AUTHENTICATED"] }
250
254
  // Per-user records (requires userId firewall scope)
251
255
  access: { roles: ["USER"] }
252
256
 
253
- // System admin (requires admin plugin)
254
- access: { roles: ["ADMIN"] }
257
+ // Platform control-plane
258
+ access: { userRole: ["appmanager"] }
259
+
260
+ // Cross-tenant DB-admin tier
261
+ access: { roles: ["SYSADMIN"] }
255
262
 
256
263
  // Org-membership roles with hierarchy expansion
257
264
  access: { roles: ["member+"] } // expands to ["member", "admin", "owner"]
@@ -374,7 +381,7 @@ if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
374
381
 
375
382
  These ran **before** the relationship resolver, which 403'd attendees whose sessions don't carry an active tenant claim (the canonical event-attendee shape).
376
383
 
377
- v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / ADMIN / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before.
384
+ v0.20 makes these preconditions **conditional on relationship supply**. If the access tree contains a relationship arm whose `from` table carries the matching tenant column, the precondition is skipped — the resolver runs first and stamps the value. Pseudo-role short-circuits (PUBLIC / AUTHENTICATED / USER / SYSADMIN) and `firewall: { exception: true }` still bypass the preconditions as before. `ADMIN` is now rejected at compile time.
378
385
 
379
386
  Typical event-attendee setup (`guests` table carries `organizationId`): the org precondition is dropped on every action whose access references `attendee` or `eventStaff`. Org admins still get `ctx.activeOrgId` from their session as today; attendees get it from the relationship row, mid-request. Both paths converge on a valid tenant claim before `execute()` runs.
380
387
 
@@ -686,7 +686,7 @@ export default defineAction({
686
686
  Unsafe cross-tenant actions are generated with:
687
687
 
688
688
  - Better Auth authentication required (no unauthenticated path)
689
- - platform admin gate (`ctx.userRole === "admin"`)
689
+ - sysadmin gate (`ctx.userRole === "sysadmin"`)
690
690
  - mandatory audit logging on deny/success/error
691
691
 
692
692
  `PUBLIC` actions also receive mandatory audit logging (same audit table), since unauthenticated endpoints are high-risk by nature.
@@ -269,7 +269,7 @@ The escape branch is **only** emitted when:
269
269
  - The table has at least one tenant-scope predicate (org / owner / team / `via:` relationship). Tables with no tenant scopes already return what a sysadmin would see, so the runtime check would be dead code.
270
270
  - The firewall does not declare `{ exception: true }` (no tenant scopes to drop).
271
271
 
272
- **Sysadmin is distinct from admin.** `userRole === 'admin'` callers still go through the firewall normally — only `userRole === 'sysadmin'` triggers the bypass. Admins keep their existing universal-bypass at the *access* layer (cross-org reads on per-record routes via `?organizationId=`), but the firewall's row predicate remains in force. Sysadmin is opt-in, configured per-project, and intended for the cross-tenant CMS DB-admin tier — see [CMS Configuration](/compiler/config#cms-configuration).
272
+ **Sysadmin is distinct from appmanager.** `userRole === 'appmanager'` callers still go through the firewall normally — only `userRole === 'sysadmin'` triggers the bypass. Appmanager is the platform control-plane tier, expressed with plain `userRole` checks; sysadmin is the opt-in cross-tenant DB-admin tier. See [CMS Configuration](/compiler/config#cms-configuration).
273
273
 
274
274
  If your project doesn't set `cms.sysadmin: true`, the escape branch is never emitted and the role value is functionally inert.
275
275
 
@@ -71,7 +71,7 @@ Produces byte-identical output to the `feature()` form above — the compiler ex
71
71
  A few mechanics to know:
72
72
 
73
73
  - **Column names** default to snake_case of the JS key — `organizationId` ↔ `organization_id`, `salaryMin` ↔ `salary_min`. Pass a positional argument to override: `q.text('custom_name')`.
74
- - **`q.id()`** emits `text('id').primaryKey()` with a cuid2 app-layer default.
74
+ - **`q.id()`** emits `text('id').primaryKey()` with a provider-driven app-layer default.
75
75
  - **`.required()` / `.optional()`** control NOT NULL. Chain before or after `.default(x)`.
76
76
  - **References:** `q.text().required().references(() => other.id, { onDelete: 'cascade' })`.
77
77
  - **Indexes:** column-level `.index()` or table-level `indexes` / `unique` as a third arg to `q.table(name, cols, { indexes, unique })`. With `feature()`, pass `indexes` and `unique` as top-level keys alongside `columns` — the sugar forwards them into the same `q.table` opts.
@@ -95,7 +95,13 @@ A few mechanics to know:
95
95
 
96
96
  `q.url()` is `q.text()` plus `z.string().url()` at the validation edge, so `javascript:` / `data:` URIs and free-form strings are rejected before they ever land in storage or get rendered in the CMS.
97
97
 
98
- `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting — prefixed UUIDs for D1, `crypto.randomUUID()` for Neon, etc. This keeps q's output decoupled from any specific ID library.
98
+ `q.id()` emits a plain text primary key. Actual ID assignment at insert time is driven by the provider's `generateId` setting. This keeps q's output decoupled from any specific ID library.
99
+
100
+ For `generateId: "cuid"`, there is one important nuance: import-capable runtime
101
+ paths can emit real `createId()` usage, but compiler-managed schema
102
+ auto-injection may keep the same `createId()` call site and back it with a
103
+ file-local `crypto.randomUUID()` polyfill so schema-generation sandboxes do not
104
+ depend on project `node_modules`.
99
105
 
100
106
  ### q.scope() — tenant scope columns
101
107
 
@@ -1,8 +1,8 @@
1
1
  # Blog Template
2
2
 
3
- The blog template creates a single-tenant backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts via Better Auth's admin plugin.
3
+ The blog template creates a fixed-org backend for a blog or CMS, deployed to Cloudflare Workers with D1. Public visitors can read content without authentication, while admins manage posts through their membership in one pinned organization.
4
4
 
5
- This template uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, no `organizationId` columns. Roles come from `user.role` instead of org membership.
5
+ This template uses [pinned organization mode](/compiler/config/single-tenant). Organization support stays on, but the generated project hard-codes one organization id and hides org switching UI.
6
6
 
7
7
  ## Create the Project
8
8
 
@@ -16,7 +16,7 @@ This scaffolds a project with:
16
16
  ```
17
17
  my-site/
18
18
  ├── quickback/
19
- │ ├── quickback.config.ts # Single-tenant config
19
+ │ ├── quickback.config.ts # Pinned-organization config
20
20
  │ └── features/
21
21
  │ └── posts/
22
22
  │ ├── posts.ts # Schema + security (defineTable)
@@ -37,7 +37,7 @@ export default {
37
37
  name: "my-site",
38
38
  template: "hono",
39
39
  features: {
40
- organizations: false,
40
+ pinnedOrganizationId: "org_replace_me",
41
41
  },
42
42
  providers: {
43
43
  runtime: { name: "cloudflare", config: {} },
@@ -50,7 +50,7 @@ export default {
50
50
  };
51
51
  ```
52
52
 
53
- Key difference from the multi-tenant templates: `organizations: false` disables the Better Auth organization plugin. See [Single-Tenant Mode](/compiler/config/single-tenant) for details.
53
+ Replace `org_replace_me` with a real Better Auth organization id before deploying. Unlike the removed single-tenant mode, this template keeps the Better Auth organization plugin and resolves roles from membership in that pinned org. See [Pinned Organization Mode](/compiler/config/single-tenant) for details.
54
54
 
55
55
  ### Posts Feature (posts.ts)
56
56
 
@@ -91,7 +91,7 @@ export default defineTable(posts, {
91
91
  ```
92
92
 
93
93
  - **`PUBLIC`** role on `read.access` means no authentication required for `GET /` and `GET /:id`
94
- - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `role: "admin"` (set via Better Auth's admin plugin)
94
+ - **`admin`** role on `create`, `update`, and `delete` requires an authenticated user with `member.role === "admin"` in the pinned organization
95
95
  - **`owner`** firewall scope tracks who created each post via `ownerId`
96
96
  - **`softDelete`** marks posts as deleted rather than removing them from the database
97
97
 
@@ -270,7 +270,7 @@ npm run deploy
270
270
 
271
271
  ## Next Steps
272
272
 
273
- - [Single-Tenant Mode](/compiler/config/single-tenant) — How single-tenant mode works
273
+ - [Pinned Organization Mode](/compiler/config/single-tenant) — How fixed-org mode works
274
274
  - [Access Control](/compiler/definitions/access) — PUBLIC role and role-based permissions
275
275
  - [Custom Actions](/compiler/definitions/actions) — Add business logic beyond CRUD
276
276
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare) — Multi-tenant alternative
@@ -33,9 +33,6 @@ my-app/
33
33
  export default {
34
34
  name: "my-app",
35
35
  template: "hono",
36
- features: {
37
- organizations: true,
38
- },
39
36
  providers: {
40
37
  runtime: { name: "cloudflare", config: {} },
41
38
  database: {
@@ -47,7 +44,7 @@ export default {
47
44
  };
48
45
  ```
49
46
 
50
- Multi-tenant mode (`organizations: true`) is the default. Change to `organizations: false` for [single-tenant mode](/compiler/config/single-tenant).
47
+ Organization-backed auth is the default. If you want a fixed-org deployment with no org switching UI, add `features.pinnedOrganizationId` as described in [Pinned Organization Mode](/compiler/config/single-tenant).
51
48
 
52
49
  ## Adding Your First Feature
53
50
 
@@ -23,13 +23,13 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
23
23
 
24
24
  The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
25
25
 
26
- ### Single-tenant starter (free)
26
+ ### Fixed-org starter (free)
27
27
 
28
28
  | Template | Includes | Command |
29
29
  |----------|----------|---------|
30
- | `blog` | Single-tenant blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions | `quickback create blog my-site` |
30
+ | `blog` | Blog with PUBLIC reads, admin writes, `publish` / `unpublish` actions, and a pinned organization id placeholder | `quickback create blog my-site` |
31
31
 
32
- The **blog** template uses Better Auth's admin plugin (not the org plugin) and [single-tenant mode](/compiler/config/single-tenant) (`organizations: false`).
32
+ The **blog** template uses [pinned organization mode](/compiler/config/single-tenant) and scaffolds `features.pinnedOrganizationId: "org_replace_me"`.
33
33
 
34
34
  ### Empty scaffold (free)
35
35
 
@@ -68,9 +68,9 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
68
68
 
69
69
  Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
70
70
 
71
- ### Blog (single-tenant CMS)
71
+ ### Blog (pinned-organization CMS)
72
72
 
73
- Best for personal sites, blogs, or any app with a single tenant. Uses [single-tenant mode](/compiler/config/single-tenant) — no organizations, roles come from `user.role` via Better Auth's admin plugin.
73
+ Best for personal sites, blogs, or any app that only needs one organization at runtime. Uses [pinned organization mode](/compiler/config/single-tenant) — organization support stays on, but the generated app hard-codes one org id and hides org switching.
74
74
 
75
75
  - Public JSON API for content
76
76
  - Admin-only editing
@@ -110,4 +110,4 @@ See the individual template guides for detailed setup:
110
110
  - [Cloudflare Template](/compiler/getting-started/template-cloudflare)
111
111
  - [Blog Template](/compiler/getting-started/template-blog)
112
112
  - [Empty Scaffolding](/compiler/getting-started/template-empty)
113
- - [Single-Tenant Mode](/compiler/config/single-tenant)
113
+ - [Pinned Organization Mode](/compiler/config/single-tenant)
@@ -131,7 +131,7 @@ execute: async ({ db, ctx, input }) => {
131
131
  }
132
132
  ```
133
133
 
134
- If you need unscoped access (for example, audited platform admin operations), declare `unsafe` on the action:
134
+ If you need unscoped access (for example, audited cross-tenant sysadmin operations), declare `unsafe` on the action:
135
135
 
136
136
  ```typescript
137
137
  adminReport: {
@@ -152,7 +152,7 @@ adminReport: {
152
152
  Cross-tenant unsafe actions are generated with:
153
153
 
154
154
  - Better Auth authentication required
155
- - platform admin gate (`ctx.userRole === 'admin'`)
155
+ - sysadmin gate (`ctx.userRole === 'sysadmin'`)
156
156
  - mandatory audit logging on denial/success/error
157
157
 
158
158
  Without unsafe mode, `unsafeDb` is `undefined`.
@@ -67,7 +67,7 @@ When both CMS and Account UI are enabled, the admin panel's profile page shows a
67
67
  cms: { domain: "cms.example.com", access: "admin" },
68
68
  ```
69
69
 
70
- With `access: "admin"`, non-admin users can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to admins. See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
70
+ With `access: "admin"`, callers outside the platform control-plane roles can't access the CMS at any layer: the link is hidden in Account UI, the SPA shell returns `403` before serving `index.html`, `/api/v1/schema` returns `403`, and the `custom_view` CRUD is locked to `userRole: ["appmanager"]` (plus `sysadmin` when enabled). See [CMS Connecting](/stack/cms/connecting#restrict-cms-access-to-admin-users-only) for the full enforcement model.
71
71
 
72
72
  ## Related
73
73
 
@@ -196,7 +196,7 @@ ENABLE_ORGANIZATIONS=false
196
196
  ENABLE_ADMIN=false
197
197
  ```
198
198
 
199
- Simple email/password authentication for single-tenant apps.
199
+ Simple email/password authentication for apps that do not need advanced auth methods.
200
200
 
201
201
  ### Maximum Security
202
202
 
@@ -256,7 +256,7 @@ import { setAppConfig } from '@/config/app';
256
256
 
257
257
  setAppConfig({
258
258
  features: {
259
- organizations: false, // Disable organizations
259
+ organizations: false, // Hide organization-management UI
260
260
  passkey: true, // Enable passkey
261
261
  },
262
262
  });