@quickback-dev/cli 0.66.3 → 0.66.4

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 (61) hide show
  1. package/dist/index.js +1 -1
  2. package/dist/skill/docs/api/errors.md +1 -1
  3. package/dist/skill/docs/api/openapi.md +26 -6
  4. package/dist/skill/docs/changelog/index.md +14 -0
  5. package/dist/skill/docs/configure/agents.md +2 -2
  6. package/dist/skill/docs/configure/auth.md +13 -0
  7. package/dist/skill/docs/define/firewall.md +1 -0
  8. package/dist/skill/docs/define/scopes.md +32 -0
  9. package/dist/skill/docs/platform/api-contract/index.md +36 -1
  10. package/dist/skill/docs/platform/auth/security.md +40 -15
  11. package/dist/skill/docs/platform/realtime/using-realtime.md +8 -0
  12. package/dist/skill/docs/platform/storage/r2.md +9 -6
  13. package/dist/skill/docs/platform/storage/using-r2.md +23 -8
  14. package/dist/skill/docs/ui/account/features/admin.md +3 -1
  15. package/package.json +1 -1
  16. package/src/skill/docs/api/errors.md +1 -1
  17. package/src/skill/docs/api/openapi.md +26 -6
  18. package/src/skill/docs/changelog/index.md +14 -0
  19. package/src/skill/docs/configure/agents.md +2 -2
  20. package/src/skill/docs/configure/auth.md +13 -0
  21. package/src/skill/docs/define/firewall.md +1 -0
  22. package/src/skill/docs/define/scopes.md +32 -0
  23. package/src/skill/docs/platform/api-contract/index.md +36 -1
  24. package/src/skill/docs/platform/auth/security.md +40 -15
  25. package/src/skill/docs/platform/realtime/using-realtime.md +8 -0
  26. package/src/skill/docs/platform/storage/r2.md +9 -6
  27. package/src/skill/docs/platform/storage/using-r2.md +23 -8
  28. package/src/skill/docs/ui/account/features/admin.md +3 -1
  29. package/dist/codex/AGENTS.md +0 -290
  30. package/dist/commands/codex.d.ts +0 -16
  31. package/dist/commands/codex.d.ts.map +0 -1
  32. package/dist/commands/codex.js +0 -159
  33. package/dist/commands/codex.js.map +0 -1
  34. package/dist/commands/compile.d.ts +0 -62
  35. package/dist/commands/compile.d.ts.map +0 -1
  36. package/dist/commands/compile.js +0 -830
  37. package/dist/commands/compile.js.map +0 -1
  38. package/dist/commands/compile.test.d.ts +0 -2
  39. package/dist/commands/compile.test.d.ts.map +0 -1
  40. package/dist/commands/compile.test.js +0 -150
  41. package/dist/commands/compile.test.js.map +0 -1
  42. package/dist/commands/init.d.ts +0 -6
  43. package/dist/commands/init.d.ts.map +0 -1
  44. package/dist/commands/init.js +0 -405
  45. package/dist/commands/init.js.map +0 -1
  46. package/dist/docs/content.d.ts +0 -7
  47. package/dist/docs/content.d.ts.map +0 -1
  48. package/dist/docs/content.js +0 -672
  49. package/dist/docs/content.js.map +0 -1
  50. package/dist/lib/helpers.d.ts +0 -39
  51. package/dist/lib/helpers.d.ts.map +0 -1
  52. package/dist/lib/helpers.js +0 -299
  53. package/dist/lib/helpers.js.map +0 -1
  54. package/dist/lib/sweep-stale.d.ts +0 -25
  55. package/dist/lib/sweep-stale.d.ts.map +0 -1
  56. package/dist/lib/sweep-stale.js +0 -179
  57. package/dist/lib/sweep-stale.js.map +0 -1
  58. package/dist/lib/sweep-stale.test.d.ts +0 -2
  59. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  60. package/dist/lib/sweep-stale.test.js +0 -130
  61. package/dist/lib/sweep-stale.test.js.map +0 -1
@@ -347,6 +347,38 @@ so it can only ever carry the role the caller actually proved this request.
347
347
 
348
348
  - A **multi-lane `via:`** (e.g. `via: ['attendeeOf', 'organizerOf']`) mints the matched lane's role — `attendeeOf` → `scope.event.roles = ['attendee']`, `organizerOf` → `['organizer']`. The resolver records which lane opened the gate, so there is no ambiguity.
349
349
  - A **bulk-grant lane** (`{ roles: [...] }` or `{ team: true }`) mints **no** scope role — it opens the gate via the caller's org role without proving a relationship. The gate passes; the caller carries their org role, not a minted scope role.
350
+ - **The org claim is only ever signed beside a membership role.** Every mint site — `/scope/v1/enter`, the namespace resolver, `/api/v1/token` — writes `orgId` into the token only when a membership `role` accompanies it, and the auth middleware ignores an `orgId` claim that arrives without a `role`. A relationship-promoted tenant (the in-request `ctx.activeOrgId` stamped from the proven row so the firewall resolves) is never persisted as a bare tenant grant.
351
+
352
+ ### The bulk-grant lane is tenant-bound
353
+
354
+ An org role is only good **inside the caller's own org**. When the namespace
355
+ hydrates a shared resource whose table carries an organization column (the
356
+ `loads` / `exposeAs` target), the resolver checks that the requested instance
357
+ belongs to `ctx.activeOrgId` *before* honouring a `{ roles }` / `{ team }`
358
+ lane. If it does not — an org-B admin entering an org-A event — the lane does
359
+ not apply: the caller is re-evaluated through the relationship lanes as a
360
+ **relationship-only principal**, with `ctx.roles = []` and the in-request tenant
361
+ re-stamped from the proven row (exactly the state a caller with no org seat
362
+ gets). No relationship → `403`. Any `ctx.roles`-based check in the action then
363
+ fails for them, scoped-db inserts stamp the *instance's* org, and the
364
+ namespace re-mint carries no org claim.
365
+
366
+ Multi-target namespaces (lanes that hydrate *different* tables) hydrate nothing
367
+ for a role caller, so there is nothing to bind there — put the tenant check in
368
+ the firewall of each table instead (an org arm in an [`any` group tenant-binds
369
+ its scope arms](/define/firewall#allany-groups--null-safe-scope-semantics) automatically).
370
+
371
+ ### Dropping the org claim on purpose
372
+
373
+ Guest and crew clients that must never ride the user's org membership into a
374
+ scope can mint an identity token without it:
375
+
376
+ ```bash
377
+ curl -X POST https://api.example.com/api/v1/token \
378
+ -H "Cookie: <session>" -H "Content-Type: application/json" \
379
+ -d '{ "dropOrg": true }'
380
+ # → { token } with no orgId / role claim; scope entry then proves only relationships
381
+ ```
350
382
 
351
383
  > The realtime [ws-ticket](/platform/realtime/durable-objects#namespace-backed-tickets-per-matched-lane) can authorize through this same namespace `via:`, issuing a per-matched-lane WebSocket ticket — so the socket gate and the REST gate stay identical.
352
384
 
@@ -115,11 +115,14 @@ export default defineAction({
115
115
 
116
116
  ## One axis: routes
117
117
 
118
- `contract` has a single key. It selects the URL prefix and nothing else.
118
+ `contract.routes` is the one behavioural axis. It selects the URL prefix and
119
+ nothing else. (`contract.redirects`, below, adds same-origin path redirects —
120
+ it changes no behaviour of the canonical routes.)
119
121
 
120
122
  | Key | Controls | Default |
121
123
  |---|---|---|
122
124
  | `routes` | The URL prefix, and nothing else | `'v1'` |
125
+ | `redirects` | Same-origin path redirects, emitted natively | none |
123
126
 
124
127
  A project with no `contract` block serves `/api/v1`. Set `routes: "v2"` to
125
128
  serve `/api/v2` instead — the behavior is identical either way.
@@ -176,6 +179,38 @@ service, so an older CLI gets the same output.
176
179
  | Auth base | `/auth/v1` | `/auth/v2` |
177
180
  | Realtime base | `/broadcast/v1` | `/broadcast/v2` |
178
181
 
182
+ ### `redirects` — keep answering an old prefix
183
+
184
+ A project that keeps `routes: "v1"` can still answer an older `/api/v2/*`
185
+ prefix by declaring the redirect — as config, not as a hand-edit of the
186
+ generated `src/index.ts` that the next compile clobbers:
187
+
188
+ {/* doc-compile: skip — config fragment, not a compilable project */}
189
+ ```typescript
190
+ contract: {
191
+ routes: "v1",
192
+ redirects: [
193
+ { from: "/api/v2/*", to: "/api/v1/*" }, // 308 by default
194
+ { from: "/auth/v2/*", to: "/auth/v1/*" },
195
+ { from: "/broadcast/v2/*", to: "/broadcast/v1/*" },
196
+ { from: "/legacy/health", to: "/health", status: 301 },
197
+ ],
198
+ }
199
+ ```
200
+
201
+ - `from` / `to` are **paths** — they must start with `/` and can never be a
202
+ full URL or a `//host` form, so a rule cannot become an open redirect. The
203
+ emitted `Location` is always same-origin.
204
+ - A trailing `/*` makes a **prefix** rule: it matches the bare prefix and
205
+ everything under it, and carries the remainder across (`/api/v2/events/7`
206
+ → `/api/v1/events/7`). `from` and `to` must both end with `/*` or neither.
207
+ - The query string is preserved; `status` is `308` (method + body preserving)
208
+ by default, or `301` / `302` / `307`.
209
+ - Rules are validated at compile time (self-redirects and prefix loops are
210
+ rejected) and emitted right after the CORS mount, ahead of auth, so
211
+ preflights still get their headers and every later layer sees canonical
212
+ paths only.
213
+
179
214
  ## Machine-readable contract
180
215
 
181
216
  - `GET /openapi.json` — OpenAPI 3.1: Problem responses, cursor params,
@@ -89,28 +89,53 @@ auth: defineAuth("better-auth", {
89
89
  enabled: true,
90
90
  window: 60, // 60 second window
91
91
  max: 100, // 100 requests per IP per window
92
+ storage: "database", // default on Cloudflare Workers — see below
92
93
  customRules: {
94
+ // Merged ON TOP of the built-in per-route rules (same path → yours wins)
93
95
  "/sign-in/email": { window: 60, max: 10 },
94
- "/sign-in/social": { window: 60, max: 10 },
95
- "/device/init": { window: 60, max: 5 },
96
- "/device/poll": { window: 60, max: 30 },
97
- "/device/token": { window: 60, max: 10 },
98
96
  }
99
97
  }
100
98
  })
101
99
  ```
102
100
 
103
- ### Custom Rules by Endpoint
104
-
105
- Set different limits based on endpoint sensitivity:
106
-
107
- | Endpoint Type | Recommended Limit | Reasoning |
108
- |---------------|-------------------|-----------|
109
- | Sign-in | 10/min per IP | Prevent credential stuffing |
110
- | Device codes | 5/min per IP | Prevent device code enumeration |
111
- | Token exchange | 10/min per IP | Prevent token brute-force |
112
- | Polling | 30/min per IP | Allow reasonable polling (every 2s) |
113
- | General API | 100/min per IP | Balance abuse prevention and usability |
101
+ ### Counter storage
102
+
103
+ Better Auth's own default keeps the counters in **process memory**. On
104
+ Cloudflare Workers that memory is per-isolate and per-colo, so counters reset
105
+ constantly and are bypassed by spreading requests across edges — an in-memory
106
+ limiter is decorative on the target runtime. The compiler therefore defaults
107
+ `rateLimit.storage` to **`"database"`** on Cloudflare: counters live in the auth
108
+ database (Better Auth adds a `rateLimit` table through the normal schema
109
+ generation, so a recompile produces the migration). On bun / node — one
110
+ long-lived process — the default is `"memory"`.
111
+
112
+ | `storage` | Where counters live | Use when |
113
+ |-----------|---------------------|----------|
114
+ | `"database"` | Auth database (`rateLimit` table) | Cloudflare Workers (default there) |
115
+ | `"memory"` | Process memory | Single long-lived process (bun / node default) |
116
+
117
+ ### Built-in rules for every credential door
118
+
119
+ The compiler always emits a per-route rule for **every** credential endpoint
120
+ Better Auth mounts — not just password sign-in — so an OTP verify door (a
121
+ 6-digit, 10<sup>6</sup>-space code) is never left under the 100/min general
122
+ limit. Your `customRules` **merge on top**: declare a path to change its limit,
123
+ or add paths for project plugins.
124
+
125
+ | Route(s) | Default | Reasoning |
126
+ |----------|---------|-----------|
127
+ | `/sign-in/email`, `/sign-in/username`, `/sign-in/social`, `/sign-in/anonymous` | 10/min per IP | Credential stuffing |
128
+ | `/sign-up/email` | 5/min per IP | Account-creation abuse |
129
+ | `/forget-password`, `/request-password-reset`, `/reset-password` | 5/min per IP | Reset-token brute force, mail bombing |
130
+ | `/sign-in/email-otp`, `/email-otp/send-verification-otp`, `/email-otp/verify-email`, `/email-otp/check-verification-otp`, `/email-otp/reset-password`, `/email-otp/request-password-reset` | 5/min per IP | OTP brute force + mail bombing |
131
+ | `/send-verification-email`, `/verify-email`, `/sign-in/magic-link`, `/magic-link/verify` | 5–10/min per IP | Link/token brute force |
132
+ | `/phone-number/send-otp`, `/phone-number/verify`, `/phone-number/request-password-reset`, `/phone-number/reset-password` | 5/min per IP | SMS OTP brute force + SMS cost |
133
+ | `/two-factor/send-otp`, `/two-factor/verify-otp`, `/two-factor/verify-totp`, `/two-factor/verify-backup-code` | 5/min per IP | Second-factor brute force |
134
+ | `/device/init` / `/device/poll` / `/device/token` | 5 / 30 / 10 per min per IP | Device-code enumeration, polling, token exchange |
135
+ | Everything else under `/auth/v1` | `max` (100/min per IP) | General abuse prevention |
136
+
137
+ Set an edge rate-limit binding as well for defence in depth
138
+ ([`rateLimit`](/define/rate-limit)) — the two layers are independent.
114
139
 
115
140
  ### Why Per-IP?
116
141
 
@@ -184,6 +184,14 @@ Events can target a specific user lane. Only that user receives the broadcast
184
184
 
185
185
  Each WebSocket connection is attached to exactly one resolved scope: `scopeKey`, `organizationId`, or `userId`. Users can only subscribe to the scope stamped into their ws ticket, enforced during authentication and ticket minting.
186
186
 
187
+ There is **no shared fallback room**. A signed-in caller with no active
188
+ organization (a self-registered account, an attendee-only account, external
189
+ crew) gets a non-scoped ticket bound to their **own user room**
190
+ (`user-<userId>`), so the only frames it can ever receive are ones addressed to
191
+ that user. Emits from a request with no `ctx.activeOrgId` and no resource scope
192
+ are skipped rather than delivered somewhere every org-less subscriber could
193
+ read, and a broadcast target that names no room is refused.
194
+
187
195
  ## Reconnection
188
196
 
189
197
  WebSocket connections can drop due to network issues. Implement reconnection logic in your client — note that you need to fetch a fresh ticket on each reconnect since tickets expire after 60 seconds:
@@ -290,7 +290,7 @@ curl -X POST https://api.example.com/storage/v1/presign/videos/clip.mp4 \
290
290
  # "key": "org_abc/videos/clip.mp4",
291
291
  # "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
292
292
  # "method": "PUT",
293
- # "headers": { "Content-Type": "video/mp4" },
293
+ # "headers": { "Content-Length": "73400320", "Content-Type": "video/mp4" },
294
294
  # "expiresAt": "2026-06-02T12:10:00.000Z"
295
295
  # }
296
296
 
@@ -302,9 +302,11 @@ curl -X POST https://api.example.com/storage/v1/confirm/videos/clip.mp4 \
302
302
  -H "Authorization: Bearer <token>"
303
303
  ```
304
304
 
305
- > If `contentType` is supplied at step 1 it is **bound into the signature** — the
306
- > client MUST send exactly that `Content-Type` header on the PUT, or R2 rejects
307
- > it. Omit it to let the client send any type.
305
+ > The `size` and `contentType` from step 1 are **bound into the signature** as
306
+ > `Content-Length` and `Content-Type` — the client MUST replay the returned
307
+ > `headers` verbatim on the PUT, or R2 rejects it. That is what makes
308
+ > `maxFileSize` and `allowedTypes` real limits on the object that lands, not
309
+ > just on the request that asked for a URL.
308
310
 
309
311
 
310
312
  ### Required secrets
@@ -336,13 +338,14 @@ export default defineAction({
336
338
  description: 'Issue a presigned R2 upload URL for a media file on an event.',
337
339
  path: '/event/:eventId/media/sign-upload',
338
340
  method: 'POST',
339
- input: z.object({ filename: z.string(), contentType: z.string() }),
341
+ input: z.object({ filename: z.string(), contentType: z.string(), size: z.number().int().nonnegative() }),
340
342
  access: { roles: ['admin', 'member', 'scope:event:attendee'] },
341
343
  async execute({ input, ctx, db, storage }) {
342
344
  // Tenant-scoped key — secure by construction
343
345
  const key = `org/${ctx.activeOrgId}/event/${input.eventId}/${crypto.randomUUID()}-${input.filename}`;
344
346
  const upload = await storage.signPutUrl(key, {
345
347
  contentType: input.contentType,
348
+ contentLength: input.size,
346
349
  expiresIn: 600,
347
350
  });
348
351
  await db.insert(images).values({ key, eventId: input.eventId /* … */ });
@@ -355,7 +358,7 @@ export default defineAction({
355
358
 
356
359
  | Method | Returns | Use |
357
360
  |--------|---------|-----|
358
- | `signPutUrl(key, { contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 |
361
+ | `signPutUrl(key, { contentLength, contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 — size (and type) are signed and checked against `maxFileSize` / `allowedTypes` |
359
362
  | `signGetUrl(key, { expiresIn?, downloadFilename? })` | `string` | Client downloads directly from R2 |
360
363
 
361
364
  This is the supported replacement for streaming a raw binary body through an
@@ -92,11 +92,15 @@ export default defineAction({
92
92
  description: "Sign a direct-to-R2 upload URL and record the object key on the media row.",
93
93
  path: "/media/sign-upload",
94
94
  method: "POST",
95
- input: z.object({ filename: z.string(), contentType: z.string() }),
95
+ input: z.object({ filename: z.string(), contentType: z.string(), size: z.number().int().nonnegative() }),
96
96
  access: { roles: ["member"] },
97
97
  async execute({ input, ctx, db, storage }) {
98
98
  const key = `org/${ctx.activeOrgId}/${crypto.randomUUID()}-${input.filename}`;
99
- const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
99
+ const upload = await storage.signPutUrl(key, {
100
+ contentType: input.contentType, // bound into the signature
101
+ contentLength: input.size, // required — bound into the signature, checked against maxFileSize
102
+ expiresIn: 600,
103
+ });
100
104
  await db.insert(media).values({ key /* … */ });
101
105
  return { uploadUrl: upload.url, key, headers: upload.headers };
102
106
  },
@@ -107,17 +111,28 @@ export default defineAction({
107
111
  # 1. Ask your action for a signed URL (your auth/roles run here)
108
112
  curl -X POST https://api.example.com/api/v1/media/sign-upload \
109
113
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
110
- -d '{ "filename": "report.pdf", "contentType": "application/pdf" }'
111
- # → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Type": "application/pdf" } }
114
+ -d '{ "filename": "report.pdf", "contentType": "application/pdf", "size": 48213 }'
115
+ # → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Length": "48213", "Content-Type": "application/pdf" } }
112
116
 
113
117
  # 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
114
118
  curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
115
119
  ```
116
120
 
117
- `storage.signPutUrl(key, { contentType?, expiresIn?, bucket? })` returns
118
- `{ url, method, headers, key, expiresAt }`; `storage.signGetUrl(key, { expiresIn?, downloadFilename?, bucket? })`
119
- returns a presigned GET URL. Pass `bucket` to target a bucket other than the
120
- configured default.
121
+ `storage.signPutUrl(key, { contentLength, contentType?, expiresIn?, bucket? })`
122
+ returns `{ url, method, headers, key, expiresAt }`;
123
+ `storage.signGetUrl(key, { expiresIn?, downloadFilename?, bucket? })` returns a
124
+ presigned GET URL. Pass `bucket` to target a bucket other than the configured
125
+ default.
126
+
127
+ **The size and type are signed, and the declared limits are enforced.**
128
+ `contentLength` is required: it is checked against `fileStorage.maxFileSize`
129
+ (the presign is refused above it) and bound into the signature as the
130
+ `Content-Length` header, so the URL cannot upload a different size than the
131
+ action approved. `contentType` is bound the same way, and when the project
132
+ declares `fileStorage.allowedTypes` it is required and must be on the list. A
133
+ PUT that does not replay the returned `headers` verbatim is rejected by R2. A
134
+ project that declares neither limit gets no ceiling and no allowlist — the
135
+ signature is still size-bound.
121
136
 
122
137
  Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
123
138
  and `R2_SECRET_ACCESS_KEY` secrets. A [browser deploy](/start/deploy-browser)
@@ -45,7 +45,9 @@ These run on `/auth/v1/admin/*`, emitted by Quickback because Better Auth's orga
45
45
 
46
46
  The admin panel is restricted to platform roles on the Better Auth user record: **`appmanager`** (the control plane) and **`sysadmin`** (which adds cross-tenant data access on top). Everyone else is redirected away from `/admin`.
47
47
 
48
- > **`role: "admin"` is not a platform role.** The compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`, so a user set to `"admin"` passed the UI guard and then got `403` from every admin API call — an operator who looked promoted and could not act. Removed in v0.62; migrate those rows to `"appmanager"`.
48
+ > **`role: "admin"` is not a platform role.** By default the compiler seeds the admin plugin with `adminRoles: ["appmanager", "sysadmin"]`, so a user set to `"admin"` passed the UI guard and then got `403` from every admin API call — an operator who looked promoted and could not act. Removed in v0.62; migrate those rows to `"appmanager"`.
49
+ >
50
+ > A project that declares `plugins: { admin: { adminRoles, roles } }` gets **exactly** that: the declared `adminRoles` list and role → access-controller map are emitted verbatim (`appmanager: userAc` narrows the provisioning operator to no admin API at all; `adminRoles: ["sysadmin"]` keeps set-role / impersonate / ban for `sysadmin` only). The compiler never re-widens a declared role, and refuses a declaration it cannot honour.
49
51
 
50
52
 
51
53
  To grant operator access to a user:
@@ -1,290 +0,0 @@
1
- # Quickback
2
-
3
- Quickback is two things:
4
-
5
- 1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
6
- 2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
7
-
8
- The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure.
9
-
10
- ## Project Structure
11
-
12
- ```
13
- my-app/
14
- ├── quickback/
15
- │ ├── quickback.config.ts
16
- │ └── features/
17
- │ └── {feature-name}/
18
- │ ├── {table}.ts # Schema + security (defineTable)
19
- │ ├── actions/ # One file per action — defineAction({...}) (optional)
20
- │ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
21
- │ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
22
- │ └── lib/ # Feature-local helpers, copied verbatim (optional)
23
- └── ...
24
- ```
25
-
26
- ## quickback.config.ts
27
-
28
- ```typescript
29
- import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
30
-
31
- export default defineConfig({
32
- name: "my-saas-app",
33
- providers: {
34
- runtime: defineRuntime("cloudflare"),
35
- database: defineDatabase("cloudflare-d1"),
36
- auth: defineAuth("better-auth"),
37
- },
38
- });
39
- ```
40
-
41
- ## Automatic Audit Fields
42
-
43
- Quickback auto-injects: `createdAt`, `modifiedAt`, `deletedAt`, `createdBy`, `modifiedBy`, `deletedBy`. Do NOT define these in schemas.
44
-
45
- ## defineTable() — Schema + Security
46
-
47
- Each feature file exports a Drizzle table and a `defineTable()` default export with security config:
48
-
49
- ```typescript
50
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
51
- import { defineTable } from "@quickback/compiler";
52
-
53
- export const todos = sqliteTable("todos", {
54
- id: integer("id").primaryKey(),
55
- title: text("title").notNull(),
56
- description: text("description"),
57
- completed: integer("completed", { mode: "boolean" }).default(false),
58
- userId: text("user_id").notNull(),
59
- organizationId: text("organization_id").notNull(),
60
- });
61
-
62
- export default defineTable(todos, {
63
- firewall: [
64
- { field: "organizationId", equals: "ctx.activeOrgId" },
65
- { field: "userId", equals: "ctx.userId" },
66
- { field: "deletedAt", isNull: true },
67
- ],
68
- read: { access: { roles: ["member", "admin"] } },
69
- create: { access: { roles: ["member", "admin"] } },
70
- update: { access: { roles: ["admin"] } },
71
- delete: { access: { roles: ["admin"] }, mode: "soft" },
72
- guards: {
73
- createable: ["title", "description", "completed"],
74
- updatable: ["title", "description", "completed"],
75
- },
76
- masking: {
77
- userId: { type: "redact", show: { roles: ["admin"] } },
78
- },
79
- });
80
- ```
81
-
82
- ## Four Security Layers
83
-
84
- Every request passes through: `Request → Firewall → Access → Guards → Database → Masking → Response`
85
-
86
- ### 1. Firewall — Data Isolation
87
-
88
- Auto WHERE clauses for tenant isolation. Predicates are AND'd:
89
-
90
- ```typescript
91
- firewall: [
92
- { field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
93
- { field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
94
- { field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
95
- { field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL
96
- ]
97
-
98
- // Public/system resources opt out of tenant scoping (soft-delete still applied):
99
- firewall: [{ exception: true }]
100
- ```
101
-
102
- Auto-derived when omitted: scans the schema for `organizationId` / `ownerId` / `teamId` and emits matching predicates. Two or more isolation columns → declare explicitly.
103
-
104
- ### 2. Access — Permission Checks
105
-
106
- Role-based and record-based (deny by default). Reads (`GET /` and `GET /:id`) gate via `read.access`; mutations gate via `create.access`, `update.access`, `delete.access`, and `upsert.access`.
107
-
108
- ```typescript
109
- read: { access: { roles: ['member'] } }, // gates GET / and GET /:id
110
- create: { access: { roles: ['admin'] } },
111
- update: {
112
- access: {
113
- or: [
114
- { roles: ['admin'] },
115
- { record: { createdBy: { equals: '$ctx.userId' } } },
116
- ],
117
- },
118
- },
119
- delete: { access: { roles: ['admin'] } },
120
- ```
121
-
122
- > **DSL v2:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`.
123
-
124
- Operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
125
- Context: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.roles`
126
-
127
- ### 3. Guards — Field Protection
128
-
129
- ```typescript
130
- guards: {
131
- createable: ['name', 'description'],
132
- updatable: ['description'],
133
- immutable: ['invoiceNumber'],
134
- protected: { status: ['approve'] }, // Only via named actions
135
- }
136
- ```
137
-
138
- ### 4. Masking — PII Redaction
139
-
140
- ```typescript
141
- masking: {
142
- ssn: { type: 'ssn', show: { roles: ['admin'] } },
143
- email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
144
- }
145
- ```
146
-
147
- Types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
148
-
149
- ## Views — Column Projections
150
-
151
- ```typescript
152
- views: {
153
- summary: { fields: ['id', 'name'], access: { roles: ['member'] } },
154
- full: { fields: ['id', 'name', 'phone', 'ssn'], access: { roles: ['admin'] } },
155
- }
156
- ```
157
-
158
- ## Validation
159
-
160
- ```typescript
161
- validation: {
162
- name: { minLength: 1, maxLength: 100 },
163
- capacity: { min: 1, max: 1000 },
164
- roomType: { enum: ['meeting', 'conference'] },
165
- email: { email: true },
166
- }
167
- ```
168
-
169
- ## Actions — Custom Business Logic
170
-
171
- One file per action under `actions/<name>.ts`. The filename is the action name AND URL segment. `actions/<name>.ts` binds to the feature's primary table; `actions/<table>/<name>.ts` binds to a sibling table. Setting `path:` makes the action standalone.
172
-
173
- ```typescript
174
- // features/todos/actions/complete.ts
175
- import { z } from "zod";
176
- import { eq } from "drizzle-orm";
177
- import { defineAction } from "../.quickback/define-action";
178
- import { todos } from "../todos";
179
-
180
- export default defineAction({
181
- description: "Mark todo as complete",
182
- input: z.object({ completedAt: z.string().datetime().optional() }),
183
- access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
184
- async execute({ db, record, auditFields }) {
185
- await db.update(todos)
186
- .set({ completed: true, modifiedAt: auditFields!.modifiedAt })
187
- .where(eq(todos.id, record.id));
188
- return { success: true };
189
- },
190
- });
191
- ```
192
-
193
- Record-based (no `path:`): `POST /api/v1/{resource}/:id/{action}`
194
- Standalone (`path:` set): custom `path` and `method`
195
-
196
- `execute:` must be an `async (ctx) => { … }` arrow function. Retired (rejected at load time): bundled `actions.ts`, `_feature.ts`, `handlers/` directory, `defineActions()`.
197
-
198
- ### Actions-Only Features (no tables)
199
-
200
- A feature with no top-level `*.ts` files is "tableless" — every action must be standalone (have `path:`).
201
-
202
- ```typescript
203
- // quickback/features/utilities/actions/health-check.ts
204
- import { z } from "zod";
205
- import { defineAction } from "../.quickback/define-action";
206
-
207
- export default defineAction({
208
- description: "Health check",
209
- path: "/health",
210
- method: "GET",
211
- input: z.object({}),
212
- access: { roles: ["member", "admin"] },
213
- async execute() { return { ok: true }; },
214
- });
215
- ```
216
-
217
- ### Public Actions
218
-
219
- Use `roles: ["PUBLIC"]` for unauthenticated endpoints. Mandatory audit logged. The wildcard `"*"` is not supported.
220
-
221
- ```typescript
222
- access: { roles: ["PUBLIC"] } // No auth, audit logged
223
- access: { roles: ["member"] } // Requires auth + role
224
- ```
225
-
226
- ## Custom Dependencies
227
-
228
- ```typescript
229
- export default defineConfig({
230
- build: {
231
- dependencies: {
232
- "fast-xml-parser": "^4.5.0",
233
- },
234
- },
235
- });
236
- ```
237
-
238
- ## CMS Layouts
239
-
240
- ```typescript
241
- layouts: {
242
- default: {
243
- sections: [
244
- { label: "Details", columns: 2, fields: ["name", "email"] },
245
- { label: "Notes", collapsed: true, fields: ["notes"] },
246
- ],
247
- },
248
- }
249
- ```
250
-
251
- ## API Reference
252
-
253
- | Method | Endpoint | Description |
254
- |--------|----------|-------------|
255
- | `GET` | `/api/v1/{resource}` | List |
256
- | `GET` | `/api/v1/{resource}/:id` | Get |
257
- | `POST` | `/api/v1/{resource}` | Create |
258
- | `PATCH` | `/api/v1/{resource}/:id` | Update |
259
- | `DELETE` | `/api/v1/{resource}/:id` | Delete |
260
-
261
- Query params: `?limit=50&offset=0`, `?status=active`, `?sort=-createdAt`, `?fields=id,name`, `?search=text`
262
- Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
263
-
264
- ## Database Dialects
265
-
266
- | Stack | Import | Table Function |
267
- |-------|--------|----------------|
268
- | Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
269
- | Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
270
-
271
- ## Migrations are generated — never hand-merge them
272
-
273
- The files under `quickback/drizzle/` (`*.sql`, `meta/_journal.json`, `meta/*_snapshot.json`) are **generated artifacts**, not source. Never hand-edit them, and never resolve a merge or rebase conflict inside them.
274
-
275
- When integrating a branch: get the feature/schema `.ts` files in first, then run `quickback compile`. The compiler regenerates the migrations from the merged schema and journals them in the correct (append-only) order. Hand-merging migration SQL or snapshots produces schema drift and broken ordering that only surfaces at deploy time. If a migration file conflicts during a merge, take either side to unblock, then recompile and let the compiler restate the migrations.
276
-
277
- ## CLI Commands
278
-
279
- ```bash
280
- quickback create <template> <name> # Create project
281
- quickback compile # Compile definitions
282
- quickback docs [topic] # Show documentation
283
- quickback claude install # Install Claude Code skill
284
- quickback cursor install # Install Cursor rules
285
- quickback codex install # Install Codex AGENTS.md rules
286
- ```
287
-
288
- ## Full Documentation
289
-
290
- https://docs.quickback.dev
@@ -1,16 +0,0 @@
1
- /**
2
- * Codex command - manage ChatGPT Codex AGENTS.md rules.
3
- *
4
- * Codex reads `AGENTS.md` from the project root (merging up the tree), so unlike
5
- * Cursor's dedicated .mdc file the rules live in a file the user may also own.
6
- * We therefore manage only a delimited block, leaving the rest of AGENTS.md
7
- * untouched.
8
- *
9
- * Usage:
10
- * quickback codex install # Add/update the Quickback block in ./AGENTS.md
11
- * quickback codex update # Alias for install (refresh the block)
12
- * quickback codex remove # Strip the Quickback block
13
- * quickback codex status # Check installation status
14
- */
15
- export declare function codex(args: string[]): Promise<void>;
16
- //# sourceMappingURL=codex.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/commands/codex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAwIH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBzD"}