@quickback-dev/cli 0.17.1 → 0.31.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 (85) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +17 -1
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.d.ts.map +1 -1
  5. package/dist/docs/content.js +28 -63
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/lib/api-client.d.ts +17 -0
  9. package/dist/lib/api-client.d.ts.map +1 -1
  10. package/dist/lib/api-client.js.map +1 -1
  11. package/dist/lib/file-loader.d.ts +24 -0
  12. package/dist/lib/file-loader.d.ts.map +1 -1
  13. package/dist/lib/file-loader.js +46 -0
  14. package/dist/lib/file-loader.js.map +1 -1
  15. package/dist/skill/docs/changelog.md +780 -1174
  16. package/dist/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  17. package/dist/skill/docs/compiler/cloud-compiler/index.md +9 -9
  18. package/dist/skill/docs/compiler/config/domains.md +44 -10
  19. package/dist/skill/docs/compiler/config/output.md +1 -1
  20. package/dist/skill/docs/compiler/config/providers.md +6 -12
  21. package/dist/skill/docs/compiler/config/variables.md +0 -30
  22. package/dist/skill/docs/compiler/definitions/access.md +203 -1
  23. package/dist/skill/docs/compiler/definitions/actions.md +40 -7
  24. package/dist/skill/docs/compiler/definitions/schema.md +6 -10
  25. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
  26. package/dist/skill/docs/compiler/getting-started/templates.md +58 -56
  27. package/dist/skill/docs/compiler/index.md +15 -34
  28. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  29. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  30. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  31. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  32. package/dist/skill/docs/compiler/targets/index.md +6 -34
  33. package/dist/skill/docs/index.md +11 -5
  34. package/dist/skill/docs/stack/account-ui/customization.md +2 -14
  35. package/dist/skill/docs/stack/account-ui/environment-variables.md +7 -1
  36. package/dist/skill/docs/stack/account-ui/features/avatars.md +2 -4
  37. package/dist/skill/docs/stack/account-ui/features/index.md +1 -1
  38. package/dist/skill/docs/stack/account-ui/features/organizations.md +31 -11
  39. package/dist/skill/docs/stack/account-ui/index.md +5 -43
  40. package/dist/skill/docs/stack/account-ui/with-quickback.md +2 -75
  41. package/dist/skill/docs/stack/auth/plugins/index.md +74 -0
  42. package/dist/skill/docs/stack/index.md +8 -4
  43. package/package.json +1 -1
  44. package/src/skill/docs/changelog.md +780 -1174
  45. package/src/skill/docs/compiler/cloud-compiler/cli.md +54 -33
  46. package/src/skill/docs/compiler/cloud-compiler/index.md +9 -9
  47. package/src/skill/docs/compiler/config/domains.md +44 -10
  48. package/src/skill/docs/compiler/config/output.md +1 -1
  49. package/src/skill/docs/compiler/config/providers.md +6 -12
  50. package/src/skill/docs/compiler/config/variables.md +0 -30
  51. package/src/skill/docs/compiler/definitions/access.md +203 -1
  52. package/src/skill/docs/compiler/definitions/actions.md +40 -7
  53. package/src/skill/docs/compiler/definitions/schema.md +6 -10
  54. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +49 -54
  55. package/src/skill/docs/compiler/getting-started/templates.md +58 -56
  56. package/src/skill/docs/compiler/index.md +15 -34
  57. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +1 -2
  58. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +0 -1
  59. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +19 -0
  60. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +1 -1
  61. package/src/skill/docs/compiler/targets/index.md +6 -34
  62. package/src/skill/docs/index.md +11 -5
  63. package/src/skill/docs/stack/account-ui/customization.md +2 -14
  64. package/src/skill/docs/stack/account-ui/environment-variables.md +7 -1
  65. package/src/skill/docs/stack/account-ui/features/avatars.md +2 -4
  66. package/src/skill/docs/stack/account-ui/features/index.md +1 -1
  67. package/src/skill/docs/stack/account-ui/features/organizations.md +31 -11
  68. package/src/skill/docs/stack/account-ui/index.md +5 -43
  69. package/src/skill/docs/stack/account-ui/with-quickback.md +2 -75
  70. package/src/skill/docs/stack/auth/plugins/index.md +74 -0
  71. package/src/skill/docs/stack/index.md +8 -4
  72. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  73. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  74. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  75. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  76. package/dist/skill/docs/stack/account-ui/library-usage.md +0 -257
  77. package/dist/skill/docs/stack/account-ui/standalone.md +0 -149
  78. package/dist/skill/docs/stack/account-ui/worker.md +0 -362
  79. package/src/skill/docs/compiler/targets/supabase-rls/index.md +0 -55
  80. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +0 -48
  81. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +0 -99
  82. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +0 -88
  83. package/src/skill/docs/stack/account-ui/library-usage.md +0 -257
  84. package/src/skill/docs/stack/account-ui/standalone.md +0 -149
  85. package/src/skill/docs/stack/account-ui/worker.md +0 -362
@@ -5,33 +5,58 @@ The Quickback CLI is the fastest way to create, compile, and manage your backend
5
5
  ## Installation
6
6
 
7
7
  ```bash
8
+ # One-shot via npx — recommended for first run
9
+ npx @quickback-dev/cli start
10
+
11
+ # Or install globally for repeat use
8
12
  npm install -g @quickback-dev/cli
9
13
  ```
10
14
 
11
15
  ## Commands
12
16
 
13
- ### Create a Project
17
+ ### Start a Project (interactive)
18
+
19
+ ```bash
20
+ quickback start
21
+ ```
22
+
23
+ Interactive onboarding designed for new users. No flags required.
24
+
25
+ - Prompts for a template (curated free-tier picker: `cloudflare`, `todos`, `blog`, `empty`)
26
+ - Prompts for a project name (defaults to the current directory's name if empty)
27
+ - Auto-detects whether to scaffold in-place or create a `./<name>/` subdirectory
28
+ - Defers login until just before the compile step — cancel at the auth prompt and the scaffold stays on disk, ready for `quickback compile` later
29
+
30
+ **Example:**
31
+ ```bash
32
+ mkdir my-app && cd my-app
33
+ npx @quickback-dev/cli start
34
+ ```
35
+
36
+ ### Create a Project (scriptable)
14
37
 
15
38
  ```bash
16
39
  quickback create <template> <name>
17
40
  ```
18
41
 
19
42
  **Templates:**
20
- - `cloudflare` - Cloudflare Workers + D1 + Better Auth (free)
21
- - `supabase` - Hono + Supabase Postgres + Supabase Auth (free)
22
- - `blog` - Single-tenant blog (PUBLIC reads, admin writes) (free)
23
- - `empty` - Cloudflare scaffold, no example features (free)
24
- - `multi-tenant` - Full SaaS with orgs, teams, billing (pro)
43
+ - `cloudflare` — Cloudflare Workers + D1 + Better Auth, bare scaffold (free)
44
+ - `todos` — Working todos example with masking + actions + a named view (free)
45
+ - `blog` — Single-tenant blog, PUBLIC reads, admin writes (free)
46
+ - `empty` — Cloudflare scaffold, no example features (free)
47
+ - `saas` — Full B2B SaaS: orgs, R2 file storage, webhooks, split databases, realtime (pro)
25
48
 
26
49
  **Example:**
27
50
  ```bash
28
- quickback create cloudflare my-app
51
+ quickback create todos my-app
29
52
  ```
30
53
 
31
54
  This scaffolds a complete project with:
32
- - `quickback.config.ts` - Project configuration
33
- - `quickback/features/` - Your table definitions
34
- - Example todos feature with full security configuration
55
+ - `quickback.config.ts` — Project configuration
56
+ - `quickback/features/` — Your table definitions
57
+ - Example feature with full security configuration (for `todos` / `blog` / `saas`)
58
+
59
+ See the [Templates](/compiler/getting-started/templates) page for a deeper guide on choosing between them.
35
60
 
36
61
  ### Compile Definitions
37
62
 
@@ -68,19 +93,6 @@ ls quickback/.archives/
68
93
 
69
94
  As a safety net, the wipe is **skipped** when the manifest contains zero files for the target directory — that's almost always an upstream compile bug, and we'd rather keep your last working tree than overwrite it with nothing.
70
95
 
71
- ### Initialize Structure
72
-
73
- ```bash
74
- quickback init
75
- ```
76
-
77
- Creates the Quickback folder structure in an existing project:
78
- ```
79
- quickback/
80
- features/
81
- quickback.config.ts
82
- ```
83
-
84
96
  ### View Documentation
85
97
 
86
98
  ```bash
@@ -209,18 +221,27 @@ The active organization is stored in your credentials and sent with compile requ
209
221
  ## Quick Start
210
222
 
211
223
  ```bash
212
- # 1. Create a new project
213
- quickback create cloudflare my-app
214
- cd my-app
224
+ # 1. Start a new project (interactive — picks template, scaffolds,
225
+ # prompts for login only when needed)
226
+ mkdir my-app && cd my-app
227
+ npx @quickback-dev/cli start
228
+
229
+ # 2. Run locally
230
+ npm run dev
231
+ ```
215
232
 
216
- # 2. Define your tables in quickback/features/
217
- # (Already has example todos feature)
233
+ Or the scriptable form:
218
234
 
219
- # 3. Compile
220
- quickback compile
235
+ ```bash
236
+ # 1. Create the project (scaffolds + compiles + installs)
237
+ quickback create todos my-app # prompts for login on first compile
238
+ cd my-app
221
239
 
222
- # 4. Run
240
+ # 2. Run
223
241
  npm run dev
242
+
243
+ # 3. Recompile after editing definitions
244
+ quickback compile
224
245
  ```
225
246
 
226
247
  ## Options
@@ -278,9 +299,9 @@ Make sure the CLI is installed globally:
278
299
  npm install -g @quickback-dev/cli
279
300
  ```
280
301
 
281
- Or use npx:
302
+ Or use npx (no global install needed):
282
303
  ```bash
283
- npx @quickback-dev/cli create cloudflare my-app
304
+ npx @quickback-dev/cli start
284
305
  ```
285
306
 
286
307
  ### Compile errors
@@ -24,18 +24,18 @@ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI
24
24
  ## Quick Start
25
25
 
26
26
  ```bash
27
- # 1. Install the CLI
28
- npm install -g @quickback-dev/cli
27
+ # 1. Scaffold + compile interactively
28
+ mkdir my-app && cd my-app
29
+ npx @quickback-dev/cli start
30
+ ```
29
31
 
30
- # 2. Create a project
32
+ `start` walks through template selection, scaffolding, login (only when needed), and the first compile in one flow. Or do it scriptably:
33
+
34
+ ```bash
35
+ npm install -g @quickback-dev/cli
31
36
  quickback create cloudflare my-app
32
37
  cd my-app
33
-
34
- # 3. Log in
35
- quickback login
36
-
37
- # 4. Compile
38
- quickback compile
38
+ quickback compile # prompts for login on the first run
39
39
  ```
40
40
 
41
41
  ## Existing Databases
@@ -1,17 +1,17 @@
1
1
  # Multi-Domain Architecture
2
2
 
3
- A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, and Admin panel on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
3
+ A single Quickback-compiled Cloudflare Worker can serve your API, CMS, Account UI, Admin panel, and your own product SPAs on separate custom domains. The compiler generates hostname-based routing so each domain serves the right content.
4
4
 
5
5
  ## How It Works
6
6
 
7
- When you configure custom domains for CMS, Account, or Admin, the compiler:
7
+ When you configure custom domains for CMS, Account, Admin, or `apps`, the compiler:
8
8
 
9
9
  1. Adds `custom_domain` routes to `wrangler.toml`
10
10
  2. Generates hostname-based middleware in the Worker
11
11
  3. Auto-configures cross-subdomain cookies for shared authentication
12
12
  4. Auto-infers a unified `quickback.{baseDomain}` fallback domain
13
13
 
14
- All five domains point to the **same Worker** — there's only one deployment.
14
+ All configured domains point to the **same Worker** — there's only one deployment.
15
15
 
16
16
  ## Domain Types
17
17
 
@@ -21,6 +21,7 @@ All five domains point to the **same Worker** — there's only one deployment.
21
21
  | `cms.example.com` | `cms: { domain }` | CMS SPA | Blocked (404) |
22
22
  | `auth.example.com` | `account: { domain }` | Account SPA | Pass-through |
23
23
  | `admin.example.com` | `account: { adminDomain }` | Account SPA | Pass-through |
24
+ | `www.example.com` | `apps: { <name>: { domain } }` | User-authored SPA | Pass-through |
24
25
  | `quickback.example.com` | Auto-inferred | Everything | All |
25
26
 
26
27
  ### CMS Domain
@@ -35,6 +36,32 @@ Serves the Account SPA at root (`/`). API and auth routes pass through to the Wo
35
36
 
36
37
  Identical behavior to the Account domain — serves the same Account SPA at root. The Account SPA's client-side router handles the `/admin` route, restricting access to users with the `admin` role.
37
38
 
39
+ ### App Domains
40
+
41
+ Mount your own product SPAs on dedicated hostnames via the `apps` field. Each entry binds one or more hostnames to a directory under `src/apps/<name>/` and inherits the same API/auth pass-through behavior as the Account domain — so the SPA can hit `/api/v1/...` and `/auth/...` same-origin without CORS.
42
+
43
+ ```typescript
44
+ apps: {
45
+ www: {
46
+ domain: "www.example.com",
47
+ aliasDomains: ["example.com"], // apex serves the same SPA
48
+ },
49
+ marketing: {
50
+ domain: "marketing.example.com",
51
+ },
52
+ }
53
+ ```
54
+
55
+ | Option | Required | Description |
56
+ |--------|----------|-------------|
57
+ | `domain` | Yes | Primary custom hostname served at root (`/`) |
58
+ | `aliasDomains` | No | Additional hostnames that serve the same SPA. Each gets its own `custom_domain = true` route. Common case: apex (`example.com`) alongside `www.example.com`. |
59
+ | `assetsDir` | No | Subdirectory under `src/apps/` to serve from. Defaults to the record key. Override only when the on-disk directory needs to differ from the URL-facing name. |
60
+
61
+ Drop the prebuilt SPA output at `quickback/apps/<name>/` — the source-apps passthrough copies it byte-for-byte into `src/apps/<name>/` on every compile. The compiler doesn't build the SPA; it just emits routing for whatever's already there. See [Output Structure](/compiler/config/output#source-apps-quickbackapps) for the passthrough rules.
62
+
63
+ The names `cms`, `account`, and `public` are reserved (they collide with compiler-emitted directories under `src/apps/`). Two app entries can't claim the same hostname, and an app's hostname can't collide with `cms.domain` / `account.domain` / `account.adminDomain`.
64
+
38
65
  ### Unified Domain
39
66
 
40
67
  The compiler auto-infers a `quickback.{baseDomain}` domain from your configured custom domains. For example, if you have `cms.example.com`, it creates `quickback.example.com`.
@@ -68,11 +95,12 @@ export default {
68
95
  name: "My App",
69
96
  auth: { password: true, admin: true },
70
97
  },
71
- trustedOrigins: [
72
- "https://auth.example.com",
73
- "https://admin.example.com",
74
- "https://cms.example.com",
75
- ],
98
+ apps: {
99
+ www: {
100
+ domain: "www.example.com",
101
+ aliasDomains: ["example.com"],
102
+ },
103
+ },
76
104
  providers: {
77
105
  runtime: { name: "cloudflare", config: {
78
106
  routes: [{ pattern: "api.example.com", custom_domain: true }],
@@ -82,6 +110,8 @@ export default {
82
110
  };
83
111
  ```
84
112
 
113
+ `trustedOrigins` is optional here — every `cms.domain`, `account.domain`, `account.adminDomain`, and `apps[*].domain` (plus aliases) is automatically added. Declare `trustedOrigins` only when you need to allow an origin the compiler can't infer (e.g. a third-party domain).
114
+
85
115
  This generates the following `wrangler.toml` routes:
86
116
 
87
117
  ```toml
@@ -90,18 +120,20 @@ routes = [
90
120
  { pattern = "cms.example.com", custom_domain = true },
91
121
  { pattern = "auth.example.com", custom_domain = true },
92
122
  { pattern = "admin.example.com", custom_domain = true },
123
+ { pattern = "www.example.com", custom_domain = true },
124
+ { pattern = "example.com", custom_domain = true },
93
125
  { pattern = "quickback.example.com", custom_domain = true }
94
126
  ]
95
127
  ```
96
128
 
97
129
  ## Cross-Subdomain Authentication
98
130
 
99
- When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing:
131
+ When two or more custom domains share a parent domain (e.g., `cms.example.com` + `auth.example.com` + `www.example.com`), the compiler automatically configures Better Auth for cross-subdomain cookie sharing. App hostnames (primary + aliases) are folded into the shared-parent detection alongside the CMS, Account, Admin, and top-level `domain` slots:
100
132
 
101
133
  - Sets `crossSubDomainCookies: { enabled: true, domain: '.example.com' }`
102
134
  - Sets `sameSite: 'none'` and `secure: true` on auth cookies
103
135
 
104
- This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com` and `admin.example.com` — no additional setup needed.
136
+ This means a user who logs in on `auth.example.com` is automatically authenticated on `cms.example.com`, `admin.example.com`, and `www.example.com` — no additional setup needed. Apex aliases (e.g. `example.com` listed under `aliasDomains`) are recognized as already being the parent — they don't break shared-parent equality.
105
137
 
106
138
  > **Automatic Detection**
107
139
  >
@@ -128,6 +160,8 @@ The compiler generates middleware that checks `new URL(c.req.url).hostname` on e
128
160
 
129
161
  **Account/Admin domain** — API and auth routes (`/api/`, `/auth/`, `/admin/`, `/storage/`, `/health`) pass through to Hono handlers. All other paths are mapped to the `/account/` asset prefix and served with SPA fallback to `/account/index.html`.
130
162
 
163
+ **App domain** — Identical to Account: API/auth/admin/storage/health pass through, other paths map to `/<assetsDir>/` with SPA fallback. The multi-domain catchall (emitted when both CMS and Account are configured) explicitly skips app hostnames, so an API miss on an app host lands in `app.notFound` (404 JSON) instead of stray-serving a sibling SPA's HTML.
164
+
131
165
  **Unified domain** — No hostname filtering. CMS is served at `/cms/`, Account at `/account/`. Root (`/`) redirects to `/cms/`. API routes work at their standard paths.
132
166
 
133
167
  ## Without Custom Domains
@@ -353,7 +353,7 @@ Notes:
353
353
 
354
354
  ### Source Apps (`quickback/apps/`)
355
355
 
356
- For hand-authored TypeScript apps that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing.
356
+ For hand-authored TypeScript apps and prebuilt SPA bundles that live alongside the compiler-emitted SPA shells, drop them under `quickback/apps/<name>/`. The CLI copies the tree into `src/apps/<name>/` on every compile, byte-for-byte, after the compiler has finished writing. Bind a directory to a hostname via [`config.apps`](/compiler/config/domains#app-domains) — the compiler emits the matching Worker middleware automatically.
357
357
 
358
358
  ```
359
359
  quickback/apps/ # Source — checked into your repo
@@ -4,11 +4,7 @@ Providers configure which services your compiled backend targets.
4
4
 
5
5
  ## Runtime Providers
6
6
 
7
- | Provider | Description |
8
- |----------|-------------|
9
- | `cloudflare` | Cloudflare Workers (Hono) |
10
- | `bun` | Bun runtime (Hono) |
11
- | `node` | Node.js runtime (Hono) |
7
+ The Quickback Stack is **Cloudflare-only**. `cloudflare` is the single supported runtime.
12
8
 
13
9
  ```typescript
14
10
  import { defineRuntime } from "@quickback/compiler";
@@ -63,13 +59,12 @@ providers: {
63
59
 
64
60
  ## Database Providers
65
61
 
62
+ Two databases are supported, both Cloudflare-native:
63
+
66
64
  | Provider | Description |
67
65
  |----------|-------------|
68
- | `cloudflare-d1` | Cloudflare D1 (SQLite) |
69
- | `better-sqlite3` | SQLite via better-sqlite3 (Bun/Node) |
70
- | `libsql` | LibSQL / Turso |
71
- | `neon` | Neon (PostgreSQL) |
72
- | `supabase` | Supabase (PostgreSQL) |
66
+ | `cloudflare-d1` | Cloudflare D1 (SQLite at the edge) |
67
+ | `neon` | Neon (PostgreSQL over Hyperdrive) |
73
68
 
74
69
  ```typescript
75
70
  import { defineDatabase } from "@quickback/compiler";
@@ -235,8 +230,7 @@ See [Realtime](/stack/realtime) for the client-side connection flow and helper e
235
230
 
236
231
  | Provider | Description |
237
232
  |----------|-------------|
238
- | `better-auth` | Better Auth with plugins |
239
- | `supabase-auth` | Supabase Auth |
233
+ | `better-auth` | Better Auth with plugins (default) |
240
234
  | `external` | External auth via Cloudflare service binding |
241
235
 
242
236
  ```typescript
@@ -107,36 +107,6 @@ For running remote migrations with `drizzle-kit`, set these in `.env`:
107
107
  | `CLOUDFLARE_AUDIT_DATABASE_ID` | Security audit D1 database ID (unsafe cross-tenant actions) |
108
108
  | `CLOUDFLARE_DATABASE_ID` | Database ID (single DB mode) |
109
109
 
110
- ## Bun Variables
111
-
112
- Set these in a `.env` file in your project root:
113
-
114
- | Variable | Description | Default |
115
- |----------|-------------|---------|
116
- | `NODE_ENV` | Runtime environment | `development` |
117
- | `PORT` | Server port | `3000` |
118
- | `BETTER_AUTH_SECRET` | Auth encryption secret | — (required) |
119
- | `BETTER_AUTH_URL` | Public URL of your server | `http://localhost:3000` |
120
- | `DATABASE_PATH` | Path to SQLite file | `./data/app.db` |
121
-
122
- ## Turso (LibSQL) Variables
123
-
124
- In addition to the Bun variables above:
125
-
126
- | Variable | Description | Default |
127
- |----------|-------------|---------|
128
- | `DATABASE_URL` | LibSQL connection URL | `file:./data/app.db` |
129
- | `DATABASE_AUTH_TOKEN` | Turso auth token (required for remote) | — |
130
-
131
- ```bash
132
- # Local development
133
- DATABASE_URL=file:./data/app.db
134
-
135
- # Production (Turso cloud)
136
- DATABASE_URL=libsql://your-db-slug.turso.io
137
- DATABASE_AUTH_TOKEN=eyJhbGciOi...
138
- ```
139
-
140
110
  ## Social Login Providers
141
111
 
142
112
  When social login is configured in your auth provider:
@@ -321,10 +321,118 @@ Resource definitions reference declared roles by name in `roles: [...]` arrays e
321
321
  | `crud.*.access` `roles: ['guest']` | ✓ Supported | Inline async lookup per request |
322
322
  | `read.access` / `read.views.*.access` `roles: ['guest']` | ✓ Supported | Same inline path |
323
323
  | `masking.<field>.show` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — async/batched mask functions deferred |
324
- | `actions.<name>.access` `roles: ['guest']` | ⚠ Refused at compile | v1 limitation — explicit `relationshipBindings` deferred |
324
+ | **Standalone** `actions.<name>.access` `roles: ['guest']` | ✓ Supported (v0.19+) | Inline gate; surface must expose `resource.column` as path param or input field |
325
+ | **Record-based** `actions.<name>.access` `roles: ['guest']` | ⚠ Fail-closed at runtime | Runtime helper denies; inline emission is a planned follow-up. Use `firewall: { exception: true }` or move the check into `execute()` until then |
325
326
 
326
327
  For the surfaces that are not yet supported, the compiler refuses at build time with a clear error pointing to a workaround. The runtime evaluator fails closed on relationship arms regardless, so silent grants are impossible.
327
328
 
329
+ ### Standalone actions: surface keys and `loads` / `exposeAs` (v0.19+)
330
+
331
+ When a standalone action's `access.roles` references a relationship-role, the compiler emits a runtime gate between input validation and `execute()`. The gate reads the relationship's `resource.column` value from the action surface — either a path parameter (`:eventId`) or an input field (`input.eventId`). If neither is present, the compiler:
332
+
333
+ - **v0.19** — emits a `[quickback:authz]` warning and skips resolver emission. The action's own hand-rolled gate (if any) keeps the route working at runtime.
334
+ - **v0.20** — hard compile error. Set `firewall: { exception: true }` to opt out (cross-tenant/admin routes only).
335
+
336
+ Pair the relationship with `loads` + `exposeAs` to hydrate the loaded resource onto `ctx`:
337
+
338
+ ```typescript
339
+ authz: {
340
+ relationships: {
341
+ attendeeOf: {
342
+ from: 'guests',
343
+ subject: { column: 'userId', equals: 'ctx.userId' },
344
+ resource: { column: 'eventId' },
345
+ where: { status: 'confirmed' },
346
+ loads: 'events', // ← v0.19+: load matching event row
347
+ exposeAs: 'event', // ← onto ctx.event for the action body
348
+ },
349
+ },
350
+ roles: {
351
+ attendee: { via: 'attendeeOf' },
352
+ },
353
+ }
354
+ ```
355
+
356
+ The resolver (v0.20):
357
+
358
+ 1. **Cheap in-memory role check** first — `ctx.roles?.includes('admin')` and friends. If the caller has a qualifying role, this short-circuits and no DB queries fire for the access gate.
359
+ 2. **Firewall-gated relationship match** if the role check failed — `SELECT { organizationId, teamId } FROM guests WHERE userId=ctx.userId AND eventId=input.eventId AND status='confirmed'` with the `guests` table's full firewall AND-applied. If neither role nor relationship qualifies → 403.
360
+ 3. **Tenant stamping from the matched row** — for any tenant column the `from` table carries (`organizationId`, `teamId`), the resolver stamps `ctx.activeOrgId ??= matchedRow.organizationId` (and similar for team). This is **in-memory mutation of the request-scoped ctx only** — no JWT remint, no session-record write, no persistent grant.
361
+ 4. **Firewall-gated load of the loaded resource** — `SELECT * FROM events WHERE id = :eventId AND buildEventsFirewallConditions(ctx, db)`. The events firewall is applied as normal; it succeeds for attendees because tenant was just stamped from the relationship row.
362
+ 5. Assigns the loaded row to `ctx.event` for the action body.
363
+
364
+ **No firewall bypass anywhere.** Both queries run with their respective tables' full firewalls. The relationship row's existence is the proof that the caller is authorized; its tenant columns are the source of the stamped claim.
365
+
366
+ ### Conditional tenant preconditions (v0.20+)
367
+
368
+ Standalone actions in features with org/team-scoped tables previously emitted unconditional preconditions:
369
+
370
+ ```ts
371
+ if (!ctx.activeOrgId) return c.json(AccessErrors.noOrg(), 403);
372
+ if (!ctx.activeTeamId) return c.json(AccessErrors.noTeam(), 403);
373
+ ```
374
+
375
+ 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
+
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.
378
+
379
+ 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
+
381
+ ### Requirement on the relationship's `from` table
382
+
383
+ For the v0.20 tenant-stamping to work, the relationship's `from` table must carry tenant columns:
384
+
385
+ - For org stamping: an `organizationId` column (or whatever spelling the project's auth-provider defaults pick).
386
+ - For team stamping: a `teamId` column.
387
+
388
+ When the `from` table has **neither**, the compiler emits a `[quickback:authz]` warning at compile time:
389
+
390
+ ```
391
+ Relationship "X" at authz.relationships.X has no organization or team columns
392
+ on its `from` table ("guests"). Action "Y" will compile, but downstream
393
+ scoped-db queries inside execute() may 403 because ctx.activeOrgId /
394
+ activeTeamId cannot be stamped from the match row. Either add the tenant
395
+ column to "guests", or set firewall: { exception: true } on the action.
396
+ ```
397
+
398
+ The relationship match still works (existence check), but no tenant gets stamped — so the conventional precondition still fires and the action still 403s for callers without a session-resident tenant claim. Add the tenant column (or denormalize it onto the relationship table during writes) to enable the stamping path.
399
+
400
+ The body can then trust `ctx.event` and drop the hand-rolled `SELECT … FROM guests WHERE …` boilerplate:
401
+
402
+ ```ts
403
+ // features/chat/actions/getInbox.ts
404
+ export default defineAction({
405
+ path: '/chat/get-inbox',
406
+ input: z.object({ eventId: z.number().int().positive() }),
407
+ access: { roles: ['admin', 'member', 'attendee'] }, // attendee is a relationship-role
408
+ execute: async ({ db, ctx, input }) => {
409
+ // No hand-rolled attendance check needed — the resolver already ran.
410
+ // ctx.event is the loaded events row (typed as any in v0.19; cast as
411
+ // needed — narrow per-action types are a follow-up).
412
+ const event = ctx.event as typeof events.$inferSelect;
413
+ // … domain logic only.
414
+ },
415
+ });
416
+ ```
417
+
418
+ `loads` and `exposeAs` are co-required (set both or neither). `exposeAs` must be a valid JS identifier and must not collide with built-in `ctx` fields (`userId`, `activeOrgId`, `activeTeamId`, `db`, etc.).
419
+
420
+ ### Action firewall escape hatch (v0.19+)
421
+
422
+ `defineAction({ firewall: { exception: true } })` opts the action out of the inherited session-key preconditions (`ctx.activeOrgId` / `ctx.activeTeamId` requirements) AND the relationship resolver. The handler receives `unsafeDb` for raw Drizzle access. Use for cross-tenant or admin routes whose surface intentionally doesn't name a session/relationship key:
423
+
424
+ ```ts
425
+ defineAction({
426
+ path: '/admin/cross-tenant-report',
427
+ firewall: { exception: true },
428
+ unsafe: { reason: 'cross-tenant audit', adminOnly: true, targetScope: 'all' },
429
+ access: { roles: ['ADMIN'] },
430
+ execute: async ({ unsafeDb, ctx }) => { /* cross-org query */ },
431
+ });
432
+ ```
433
+
434
+ `firewall: { exception: true }` is the declarative twin of `unsafe: true` — they're conceptually distinct: `firewall.exception` opts out of the gate-emission pillars; `unsafe` signals audit/cross-tenant intent (and still applies for logging). Most cross-tenant actions set both.
435
+
328
436
  ### Recommended pattern: gate at the firewall layer
329
437
 
330
438
  Most of the time, relationship-based row visibility is what you want, and putting it at the **firewall** layer is the cleanest expression. The firewall is row-filter; the access layer is route/role-filter; let each do its job:
@@ -434,6 +542,100 @@ The validator and resolver reject:
434
542
  - `+` hierarchy suffix on a relationship-role name (terminal, like pseudo-roles).
435
543
  - Relationship-roles in `masking.show` / `actions.access` (deferred surfaces — see the table above).
436
544
 
545
+ ## Namespace mounts (hoisted relationship middleware)
546
+
547
+ When several standalone actions share a path prefix and the same relationship gate — `/event/:eventId/announce`, `/event/:eventId/cancel`, `/event/:eventId/respond` — declaring the gate per-action means writing the same `roles: ['attendee']` over and over AND paying the relationship-resolver cost N times per request (one subquery + one row-load, multiplied by the number of actions).
548
+
549
+ Namespace mounts hoist the resolver into one Hono middleware that runs once per request. Every action under the prefix skips the inline gate; `ctx.<exposeAs>` is hydrated by the middleware and typed automatically inside the handlers.
550
+
551
+ Two declaration sites depending on whether the participating actions live in one feature or many:
552
+
553
+ ### Single feature: `defineTable({ namespace })` (v0.23+)
554
+
555
+ Use when every action under the prefix lives in the same feature directory. The namespace travels with the table that owns it — no addition to `quickback.config.ts` needed.
556
+
557
+ ```typescript
558
+ // features/events/events.ts
559
+ export default defineTable(events, {
560
+ firewall: [...],
561
+ crud: { ... },
562
+ namespace: {
563
+ prefix: '/event/:eventId', // absolute URL path
564
+ via: 'attendeeOf', // relationship gate (must exist in authz.relationships)
565
+ },
566
+ });
567
+
568
+ // features/events/actions/post-announcement.ts
569
+ export default defineAction({
570
+ path: '/event/:eventId/announcements',
571
+ method: 'POST',
572
+ // No gate boilerplate. ctx.event is typed inside execute().
573
+ });
574
+ ```
575
+
576
+ The compiler emits one `app.use(...)` on the events feature's Hono app. Every standalone action in `features/events/actions/` whose path starts with `/event/:eventId/` joins the namespace automatically.
577
+
578
+ ### Cross-feature: `authz.namespaces` (v0.24+)
579
+
580
+ Use when the namespace spans multiple features. The declaration sits next to your other authz config in `quickback.config.ts`.
581
+
582
+ ```typescript
583
+ // quickback.config.ts
584
+ authz: {
585
+ relationships: {
586
+ attendeeOf: {
587
+ from: 'guests',
588
+ subject: { column: 'userId', equals: 'ctx.userId' },
589
+ resource: { column: 'eventId' },
590
+ loads: 'events',
591
+ exposeAs: 'event',
592
+ },
593
+ },
594
+ namespaces: {
595
+ eventScope: { prefix: '/event/:eventId', via: 'attendeeOf' },
596
+ },
597
+ }
598
+
599
+ // features/feeds/actions/feed-moments.ts (in a different feature)
600
+ export default defineAction({
601
+ path: '/event/:eventId/feed-moments',
602
+ method: 'POST',
603
+ });
604
+
605
+ // features/rsvp/actions/respond.ts (and another)
606
+ export default defineAction({
607
+ path: '/event/:eventId/respond',
608
+ method: 'POST',
609
+ });
610
+ ```
611
+
612
+ The compiler emits one synthetic `src/routes/__namespace-event-scope.routes.ts` that imports each contributing feature's `actions` map under a distinct alias, mounts the resolver middleware once, and dispatches to the matching action. Worker-root mount order ensures the middleware fires before any per-feature route handler under the prefix.
613
+
614
+ ### Discovery is path-prefix-only
615
+
616
+ Actions opt in by matching `path:` against a declared namespace prefix. There's no `namespace: 'foo'` field on `defineAction` — the path string is the discoverable surface, consistent with how `path:` already determines an action's URL.
617
+
618
+ ### Requirements (enforced at compile time)
619
+
620
+ Both forms share the same shape checks:
621
+
622
+ - **`via:` must point at a declared `authz.relationships[*]` entry**, and that relationship must declare `loads + exposeAs`. Without `loads` there's nothing for the middleware to hydrate, and the namespace gate becomes indistinguishable from a per-action access rule.
623
+ - **`prefix:` must contain at least one `:param` segment** (e.g. `/event/:eventId`). The middleware reads the relationship key from `c.req.param()` because no request body has been parsed at middleware time.
624
+ - **One declaration per namespace name.** The same name in both `defineTable({ namespace })` and `authz.namespaces` is rejected. The project-level form is canonical for cross-feature; the table-level form is the single-feature shorthand.
625
+
626
+ Project-level only:
627
+
628
+ - **Ambiguous prefixes** like `/a/:x` and `/a/:y` (same shape, different `:param` names) are rejected. Strict super/sub-set relationships (`/event/:e` vs `/event/:e/admin`) are fine — the harvester routes each action to the longest matching prefix.
629
+ - **Unused namespace** emits a `[quickback:authz]` warning when no action's path matches the declared prefix. Not a hard error — the namespace may be staged ahead of the actions.
630
+
631
+ ### What namespace actions get for free
632
+
633
+ Inside a namespace action's `execute()`:
634
+
635
+ - `ctx.<exposeAs>` is populated by the middleware with the loaded resource row, typed as `typeof <loadsTable>.$inferSelect`.
636
+ - Tenant context (`ctx.activeOrgId` / `ctx.activeTeamId`) is stamped from the matched relationship row when its `from` table carries those columns. Downstream scoped queries work without further setup.
637
+ - The action's own `access:` block (additional roles, userRole, record predicates, OTHER relationship arms) still runs after the namespace gate — namespace handles entry, per-action gates further.
638
+
437
639
  ## Read & Write Configuration
438
640
 
439
641
  Reads (`GET /` and `GET /:id`) live under `read:`; mutations live under top-level `create:`, `update:`, `delete:`, and `upsert:`. See [Read](/compiler/definitions/read) for the full read pipeline reference.