@quickback-dev/cli 0.9.5

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 (122) hide show
  1. package/README.md +7 -0
  2. package/dist/commands/claude.d.ts +13 -0
  3. package/dist/commands/claude.d.ts.map +1 -0
  4. package/dist/commands/claude.js +305 -0
  5. package/dist/commands/claude.js.map +1 -0
  6. package/dist/commands/compile.d.ts +18 -0
  7. package/dist/commands/compile.d.ts.map +1 -0
  8. package/dist/commands/compile.js +326 -0
  9. package/dist/commands/compile.js.map +1 -0
  10. package/dist/commands/create.d.ts +18 -0
  11. package/dist/commands/create.d.ts.map +1 -0
  12. package/dist/commands/create.js +798 -0
  13. package/dist/commands/create.js.map +1 -0
  14. package/dist/commands/cursor.d.ts +11 -0
  15. package/dist/commands/cursor.d.ts.map +1 -0
  16. package/dist/commands/cursor.js +156 -0
  17. package/dist/commands/cursor.js.map +1 -0
  18. package/dist/commands/docs.d.ts +10 -0
  19. package/dist/commands/docs.d.ts.map +1 -0
  20. package/dist/commands/docs.js +93 -0
  21. package/dist/commands/docs.js.map +1 -0
  22. package/dist/commands/example.d.ts +7 -0
  23. package/dist/commands/example.d.ts.map +1 -0
  24. package/dist/commands/example.js +153 -0
  25. package/dist/commands/example.js.map +1 -0
  26. package/dist/commands/init.d.ts +6 -0
  27. package/dist/commands/init.d.ts.map +1 -0
  28. package/dist/commands/init.js +383 -0
  29. package/dist/commands/init.js.map +1 -0
  30. package/dist/commands/login.d.ts +16 -0
  31. package/dist/commands/login.d.ts.map +1 -0
  32. package/dist/commands/login.js +287 -0
  33. package/dist/commands/login.js.map +1 -0
  34. package/dist/commands/logout.d.ts +7 -0
  35. package/dist/commands/logout.d.ts.map +1 -0
  36. package/dist/commands/logout.js +19 -0
  37. package/dist/commands/logout.js.map +1 -0
  38. package/dist/commands/mcp.d.ts +21 -0
  39. package/dist/commands/mcp.d.ts.map +1 -0
  40. package/dist/commands/mcp.js +331 -0
  41. package/dist/commands/mcp.js.map +1 -0
  42. package/dist/commands/whoami.d.ts +7 -0
  43. package/dist/commands/whoami.d.ts.map +1 -0
  44. package/dist/commands/whoami.js +37 -0
  45. package/dist/commands/whoami.js.map +1 -0
  46. package/dist/cursor/quickback.mdc +277 -0
  47. package/dist/docs/content.d.ts +7 -0
  48. package/dist/docs/content.d.ts.map +1 -0
  49. package/dist/docs/content.js +577 -0
  50. package/dist/docs/content.js.map +1 -0
  51. package/dist/examples/recruitment.tar.gz +0 -0
  52. package/dist/index.d.ts +12 -0
  53. package/dist/index.d.ts.map +1 -0
  54. package/dist/index.js +188 -0
  55. package/dist/index.js.map +1 -0
  56. package/dist/lib/api-client.d.ts +103 -0
  57. package/dist/lib/api-client.d.ts.map +1 -0
  58. package/dist/lib/api-client.js +231 -0
  59. package/dist/lib/api-client.js.map +1 -0
  60. package/dist/lib/api-client.test.d.ts +2 -0
  61. package/dist/lib/api-client.test.d.ts.map +1 -0
  62. package/dist/lib/api-client.test.js +133 -0
  63. package/dist/lib/api-client.test.js.map +1 -0
  64. package/dist/lib/artifact-routing.d.ts +8 -0
  65. package/dist/lib/artifact-routing.d.ts.map +1 -0
  66. package/dist/lib/artifact-routing.js +34 -0
  67. package/dist/lib/artifact-routing.js.map +1 -0
  68. package/dist/lib/artifact-routing.test.d.ts +2 -0
  69. package/dist/lib/artifact-routing.test.d.ts.map +1 -0
  70. package/dist/lib/artifact-routing.test.js +37 -0
  71. package/dist/lib/artifact-routing.test.js.map +1 -0
  72. package/dist/lib/async-utils.d.ts +6 -0
  73. package/dist/lib/async-utils.d.ts.map +1 -0
  74. package/dist/lib/async-utils.js +26 -0
  75. package/dist/lib/async-utils.js.map +1 -0
  76. package/dist/lib/auth.d.ts +55 -0
  77. package/dist/lib/auth.d.ts.map +1 -0
  78. package/dist/lib/auth.js +102 -0
  79. package/dist/lib/auth.js.map +1 -0
  80. package/dist/lib/compiler-stubs.d.ts +108 -0
  81. package/dist/lib/compiler-stubs.d.ts.map +1 -0
  82. package/dist/lib/compiler-stubs.js +142 -0
  83. package/dist/lib/compiler-stubs.js.map +1 -0
  84. package/dist/lib/drizzle-meta-routing.test.d.ts +2 -0
  85. package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
  86. package/dist/lib/drizzle-meta-routing.test.js +123 -0
  87. package/dist/lib/drizzle-meta-routing.test.js.map +1 -0
  88. package/dist/lib/file-loader.d.ts +165 -0
  89. package/dist/lib/file-loader.d.ts.map +1 -0
  90. package/dist/lib/file-loader.js +577 -0
  91. package/dist/lib/file-loader.js.map +1 -0
  92. package/dist/lib/file-loader.test.d.ts +2 -0
  93. package/dist/lib/file-loader.test.d.ts.map +1 -0
  94. package/dist/lib/file-loader.test.js +75 -0
  95. package/dist/lib/file-loader.test.js.map +1 -0
  96. package/dist/lib/file-writer.d.ts +30 -0
  97. package/dist/lib/file-writer.d.ts.map +1 -0
  98. package/dist/lib/file-writer.js +122 -0
  99. package/dist/lib/file-writer.js.map +1 -0
  100. package/dist/lib/helpers.d.ts +39 -0
  101. package/dist/lib/helpers.d.ts.map +1 -0
  102. package/dist/lib/helpers.js +299 -0
  103. package/dist/lib/helpers.js.map +1 -0
  104. package/dist/lib/markdown-renderer.d.ts +8 -0
  105. package/dist/lib/markdown-renderer.d.ts.map +1 -0
  106. package/dist/lib/markdown-renderer.js +151 -0
  107. package/dist/lib/markdown-renderer.js.map +1 -0
  108. package/dist/lib/shell.d.ts +15 -0
  109. package/dist/lib/shell.d.ts.map +1 -0
  110. package/dist/lib/shell.js +32 -0
  111. package/dist/lib/shell.js.map +1 -0
  112. package/dist/skill/SKILL.md +887 -0
  113. package/dist/skill/agents/quickback-specialist/AGENT.md +298 -0
  114. package/dist/templates/registry.d.ts +36 -0
  115. package/dist/templates/registry.d.ts.map +1 -0
  116. package/dist/templates/registry.js +181 -0
  117. package/dist/templates/registry.js.map +1 -0
  118. package/package.json +55 -0
  119. package/src/cursor/quickback.mdc +277 -0
  120. package/src/examples/recruitment.tar.gz +0 -0
  121. package/src/skill/SKILL.md +887 -0
  122. package/src/skill/agents/quickback-specialist/AGENT.md +298 -0
@@ -0,0 +1,887 @@
1
+ ---
2
+ name: quickback
3
+ description: Quickback API engine documentation - use when working with Quickback projects, defining resources, schemas, security pillars (Firewall, Access, Guards, Masking), actions, webhooks, or deployment
4
+ allowed-tools: Read, Grep, Glob
5
+ ---
6
+
7
+ # Quickback
8
+
9
+ Quickback is two things:
10
+
11
+ 1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
12
+ 2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
13
+
14
+ The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure. Not a managed platform — real code you own and control.
15
+
16
+ ## Accessing Documentation
17
+
18
+ The fastest way to look up detailed docs is via the CLI:
19
+
20
+ ```bash
21
+ quickback docs # List all available topics
22
+ quickback docs <topic> # Show docs for a specific topic
23
+ quickback docs firewall # Example: firewall docs
24
+ quickback docs cms/record-layouts # Example: CMS record layouts
25
+ ```
26
+
27
+ Full online docs: https://docs.quickback.dev
28
+
29
+ ---
30
+
31
+ # PART 1: THE COMPILER
32
+
33
+ The compiler takes your TypeScript definitions and generates API routes, middleware, migrations, typed SDKs, OpenAPI specs, and AI tool definitions.
34
+
35
+ ```
36
+ ┌─────────────────────────────────────────────────────────┐
37
+ │ YOU DEFINE (in TypeScript) │
38
+ │ • Drizzle schema (your data models) │
39
+ │ • Security layers (Firewall, Access, Guards, Masking) │
40
+ │ • Views, Validation, Layouts │
41
+ │ • Actions (your business operations) │
42
+ ├─────────────────────────────────────────────────────────┤
43
+ │ QUICKBACK COMPILES TO │
44
+ │ • Database migrations (via Drizzle) │
45
+ │ • API route handlers (Hono) │
46
+ │ • Typed client SDK for your frontend │
47
+ │ • AI tool definitions │
48
+ │ • OpenAPI specification │
49
+ └─────────────────────────────────────────────────────────┘
50
+ ```
51
+
52
+ ## Project Structure
53
+
54
+ ```
55
+ my-app/
56
+ ├── quickback/
57
+ │ ├── quickback.config.ts
58
+ │ └── features/
59
+ │ └── {feature-name}/
60
+ │ ├── {table}.ts # Schema + security (defineTable)
61
+ │ ├── actions.ts # Custom actions (optional)
62
+ │ ├── handlers/ # Action handlers (optional)
63
+ │ └── pages/ # Custom CMS pages (optional)
64
+ │ └── {slug}.ts # definePage() call
65
+ ├── src/ # ← compiled output
66
+ │ ├── index.ts # API entry (Hono)
67
+ │ └── apps/
68
+ │ ├── cms/ # ← CMS static assets (when cms: true)
69
+ │ │ ├── index.html
70
+ │ │ └── assets/
71
+ │ └── account/ # ← Account UI assets (when account: true/object)
72
+ │ ├── index.html
73
+ │ └── assets/
74
+ └── ...
75
+ ```
76
+
77
+ ## quickback.config.ts
78
+
79
+ ```typescript
80
+ import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
81
+
82
+ export default defineConfig({
83
+ name: "my-saas-app",
84
+ cms: true, // Embed CMS admin UI in compiled Worker (or { domain: "cms.example.com" })
85
+ account: { // Embed Account UI (auth, profile, orgs, admin) in compiled Worker
86
+ domain: "auth.example.com", // Optional: custom domain (served at / instead of /account/)
87
+ adminDomain: "admin.example.com", // Optional: separate admin domain
88
+ name: "My App",
89
+ companyName: "My Company",
90
+ tagline: "Build faster, ship sooner",
91
+ build: true, // Set false to skip SPA rebuild on subsequent compiles
92
+ auth: {
93
+ password: true, // Email/password login (default: false)
94
+ emailOTP: true, // Email OTP login (default: true)
95
+ passkey: true, // WebAuthn passkeys (default: true)
96
+ signup: true, // User registration (default: true)
97
+ organizations: true, // Multi-tenant org management (default: true)
98
+ admin: true, // Admin panel (default: true)
99
+ emailVerification: true, // Require email verification (default: true)
100
+ },
101
+ },
102
+ providers: {
103
+ runtime: defineRuntime("cloudflare"),
104
+ database: defineDatabase("cloudflare-d1"),
105
+ auth: defineAuth("better-auth"),
106
+ },
107
+ build: {
108
+ outputDir: "dist",
109
+ dependencies: {
110
+ "fast-xml-parser": "^4.5.0", // Third-party packages used in action handlers
111
+ },
112
+ },
113
+ });
114
+ ```
115
+
116
+ Minimal: `account: true` enables with all defaults. `account: { build: false }` skips rebuild on subsequent compiles.
117
+
118
+ ## Compile Output and State Artifacts
119
+
120
+ - Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
121
+ - CMS assets → `src/apps/cms/` (served at `/cms/` or root on custom domain)
122
+ - Account UI assets → `src/apps/account/` (served at `/account/` or root on custom domain)
123
+ - Drizzle migration SQL and meta files live under `quickback/drizzle/...` — Quickback owns this state and never writes a project-root `drizzle/` folder
124
+ - Security contract reports are written to `quickback/reports/...`
125
+
126
+ ## Automatic Audit Fields
127
+
128
+ Quickback automatically injects these fields into every table:
129
+ - `createdAt`, `modifiedAt`, `deletedAt` (timestamps)
130
+ - `createdBy`, `modifiedBy`, `deletedBy` (user IDs)
131
+
132
+ **Do NOT add these to your schema files.** They are auto-injected by the compiler.
133
+
134
+ ---
135
+
136
+ ## Feature Definitions
137
+
138
+ Features live in `quickback/features/{name}/` with one file per table.
139
+
140
+ Quickback offers **three co-equal authoring patterns** — all compile to the same generated runtime, the compiler dispatches per file:
141
+
142
+ - **`feature()`** (recommended default) — single default export, one import, everything in one call. Use for new code.
143
+ - **`q.table()` + `defineTable()`** — the two-export form. Same `q` DSL, more explicit. Use when you want the table identifier named before the default export.
144
+ - **Drizzle `sqliteTable()` / `pgTable()` + `defineTable()`** — interop with existing Drizzle code.
145
+
146
+ ### Example: todos.ts (`feature()` — recommended default)
147
+
148
+ ```typescript
149
+ import { feature, q } from "@quickback/compiler";
150
+
151
+ export default feature("todos", {
152
+ columns: {
153
+ id: q.id(),
154
+ title: q.text().required(),
155
+ description: q.text().optional(),
156
+ completed: q.bool().default(false),
157
+ userId: q.text().required(),
158
+ organizationId: q.text().required(),
159
+ },
160
+ firewall: { organization: {}, owner: {} },
161
+ crud: {
162
+ list: { access: { roles: ["member", "admin"] } },
163
+ get: { access: { roles: ["member", "admin"] } },
164
+ create: { access: { roles: ["member", "admin"] } },
165
+ update: { access: { roles: ["admin"] } },
166
+ delete: { access: { roles: ["admin"] }, mode: "soft" },
167
+ },
168
+ guards: {
169
+ createable: ["title", "description", "completed"],
170
+ updatable: ["title", "description", "completed"],
171
+ },
172
+ masking: {
173
+ userId: { type: "redact", show: { roles: ["admin"] } },
174
+ },
175
+ });
176
+ ```
177
+
178
+ **q DSL quick reference:** column names default to snake_case of the JS key (`organizationId` → `organization_id`). `q.id()` emits a cuid2 primary key. Chainable modifiers: `.required()` / `.optional()` / `.default(v)` / `.unique()` / `.index()` / `.references(() => other.id, { onDelete: 'cascade' })`.
179
+
180
+ The `feature()` form is compile-time sugar — the compiler expands it to `q.table()` + `defineTable()` internally. Use whichever reads best for the file.
181
+
182
+ ### Example: same todos using the two-export form
183
+
184
+ ```typescript
185
+ import { q, defineTable } from "@quickback/compiler";
186
+
187
+ export const todos = q.table("todos", {
188
+ id: q.id(),
189
+ title: q.text().required(),
190
+ completed: q.bool().default(false),
191
+ userId: q.text().required(),
192
+ organizationId: q.text().required(),
193
+ });
194
+
195
+ export default defineTable(todos, {
196
+ firewall: { organization: {}, owner: {} },
197
+ crud: { /* same as above */ },
198
+ guards: { /* same as above */ },
199
+ });
200
+
201
+ export type Todo = typeof todos.$infer;
202
+ ```
203
+
204
+ ### Example: same todos with Drizzle (for interop)
205
+
206
+ ```typescript
207
+ import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
208
+ import { defineTable } from "@quickback/compiler";
209
+
210
+ export const todos = sqliteTable("todos", {
211
+ id: text("id").primaryKey(),
212
+ title: text("title").notNull(),
213
+ completed: integer("completed", { mode: "boolean" }).default(false),
214
+ userId: text("user_id").notNull(),
215
+ organizationId: text("organization_id").notNull(),
216
+ });
217
+
218
+ export default defineTable(todos, {
219
+ firewall: { organization: {}, owner: {} },
220
+ crud: { /* same as above */ },
221
+ guards: { /* same as above */ },
222
+ });
223
+ ```
224
+
225
+ ### Internal/Junction Tables (No API)
226
+
227
+ Tables without a `defineTable()` / `feature()` default export get no API routes:
228
+
229
+ ```typescript
230
+ export const roomAmenities = q.table('roomAmenities', {
231
+ roomId: q.text().required(),
232
+ amenityId: q.text().required(),
233
+ });
234
+ ```
235
+
236
+ The compiler warns once per such table so you confirm the opt-out is intentional.
237
+
238
+ ### Handlers use `q.*` for query helpers too
239
+
240
+ Custom action handlers query via the same `q` namespace:
241
+
242
+ ```typescript
243
+ // quickback/features/mail/handlers/inbound.ts
244
+ import { q } from "../../../lib/q";
245
+ import mailboxes from "../mailboxes";
246
+ import messages from "../messages";
247
+
248
+ export const execute = async ({ unsafeDb, input }) => {
249
+ const mailbox = await unsafeDb.query.mailboxes.findFirst({
250
+ where: q.eq(mailboxes.address, input.mailboxAddress),
251
+ });
252
+ // …
253
+ };
254
+ ```
255
+
256
+ Available: `q.and`, `q.or`, `q.not`, `q.eq`, `q.ne`, `q.gt`, `q.gte`, `q.lt`, `q.lte`, `q.like`, `q.ilike`, `q.inArray`, `q.notInArray`, `q.isNull`, `q.isNotNull`, `q.between`, `q.desc`, `q.asc`, `q.sql`. Pure re-export of Drizzle's query builder under the Quickback namespace — users can still `import { eq } from "drizzle-orm"` directly if they prefer.
257
+
258
+ ### Explicit scope in unsafe handlers — `unsafeDb.scopeTo(...)`
259
+
260
+ When an unsafe handler (webhook, cron, bulk importer) knows its tenant out-of-band, call `scopeTo` instead of hand-rolling `organizationId` on every query. The firewall runs unchanged with a synthesized ctx:
261
+
262
+ ```typescript
263
+ export const execute = async ({ unsafeDb, input }) => {
264
+ const [mailbox] = await unsafeDb.select().from(mailboxes)
265
+ .where(q.eq(mailboxes.id, input.mailboxId));
266
+ if (!mailbox) return { ok: false };
267
+
268
+ const db = unsafeDb.scopeTo({ organizationId: mailbox.organizationId });
269
+ await db.insert(messages).values({ mailboxId: mailbox.id, body: input.body });
270
+ return { ok: true };
271
+ };
272
+ ```
273
+
274
+ `scopeTo` accepts `{ organizationId?, userId?, teamId? }` — any subset. Missing keys fall back to the ambient `ctx` values. Every downstream `.select/.update/.delete` gets a `WHERE` scope clause; every `.insert().values()` auto-injects the scope columns. Reach for this any time an unsafe handler needs scoped writes — it is the canonical way to keep tenant isolation while the handler bypasses the request ctx.
275
+
276
+ ### Import style
277
+
278
+ With `feature()`, tables are **default exports** — use default imports in actions/other files:
279
+
280
+ ```typescript
281
+ // features/applications/actions.ts
282
+ import applications from "./applications";
283
+ import { defineActions } from "@quickback/compiler";
284
+ ```
285
+
286
+ With the two-export form, tables are **named exports** — use named imports:
287
+
288
+ ```typescript
289
+ import { applications } from "./applications";
290
+ ```
291
+
292
+ Both produce the same typed handle.
293
+
294
+ ---
295
+
296
+ ## Input Hints
297
+
298
+ Control how the CMS renders form inputs. Key values:
299
+
300
+ | Hint | Renders As |
301
+ |------|-----------|
302
+ | `richtext` | Tiptap rich text editor (edit) / formatted HTML (view). Stores HTML. |
303
+ | `select` | Dropdown select |
304
+ | `textarea` | Multi-line text |
305
+ | `currency` | Currency input |
306
+ | `checkbox` | Checkbox toggle |
307
+
308
+ ```typescript
309
+ inputHints: { description: "richtext", status: "select" }
310
+ ```
311
+
312
+ ---
313
+
314
+ ## Four Security Layers
315
+
316
+ Every API request passes through four layers in order:
317
+
318
+ ```
319
+ Request → Firewall → Access → Guards → Database → Masking → Response
320
+ ```
321
+
322
+ | Layer | Purpose | Failure |
323
+ |-------|---------|---------|
324
+ | **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
325
+ | **Access** | Role-based CRUD permissions (deny by default) | 403 |
326
+ | **Guards** | Field modification rules (protected/immutable fields) | 400 |
327
+ | **Masking** | PII redaction for unauthorized viewers | — |
328
+
329
+ ### 1. Firewall — Data Isolation
330
+
331
+ Compiles WHERE clauses to isolate data by ownership. Auto-detects column names.
332
+
333
+ ```typescript
334
+ firewall: {
335
+ organization: {}, // WHERE organizationId = ctx.activeOrgId
336
+ owner: { mode: 'optional' }, // AND (ownerId = ctx.userId OR ownerId IS NULL)
337
+ team: {}, // WHERE teamId = ctx.activeTeamId
338
+ softDelete: {}, // AND deletedAt IS NULL
339
+ exception: true, // No filtering (public resources)
340
+ }
341
+ ```
342
+
343
+ Auto-detection:
344
+ - `organization` → looks for `organizationId` or `organization_id`
345
+ - `owner` → looks for `userId` or `user_id`
346
+ - `team` → looks for `teamId` or `team_id`
347
+
348
+ Column overrides:
349
+
350
+ ```typescript
351
+ firewall: {
352
+ organization: {
353
+ column: 'tenant_id',
354
+ source: 'ctx.tenant.id',
355
+ },
356
+ }
357
+ ```
358
+
359
+ Owner modes: default = strict (only own records), `optional` = own + NULL owner (admin pattern).
360
+
361
+ ### 2. Access — Permission Checks
362
+
363
+ Role-based and record-based access control. Deny by default.
364
+
365
+ ```typescript
366
+ crud: {
367
+ list: { access: { roles: ['member+'] } }, // member, admin, owner
368
+ get: { access: { roles: ['member+'] } },
369
+ create: { access: { roles: ['admin+'] } }, // admin, owner
370
+ update: {
371
+ access: {
372
+ or: [
373
+ { roles: ['admin+'] },
374
+ { record: { createdBy: { equals: '$ctx.userId' } } },
375
+ ],
376
+ },
377
+ },
378
+ delete: { access: { roles: ['owner'] } }, // owner only
379
+ }
380
+ ```
381
+
382
+ **Role hierarchy**: Configure `auth.roleHierarchy` in your config (e.g., `['member', 'admin', 'owner']`) and use the `+` suffix to mean "this role and above". `"member+"` expands to `["member", "admin", "owner"]` at compile time. Roles without `+` are exact matches.
383
+
384
+ Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
385
+
386
+ Context variables: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.activeTeamId`, `$ctx.roles`, `$ctx.isAnonymous`
387
+
388
+ **Special role `PUBLIC`**: Use `roles: ["PUBLIC"]` for unauthenticated access (contact forms, webhooks). Every PUBLIC invocation is mandatory audit logged. The wildcard `"*"` is not supported and will fail at compile time.
389
+
390
+ ### 3. Guards — Field Protection
391
+
392
+ ```typescript
393
+ guards: {
394
+ createable: ['name', 'description'], // Allowed on POST
395
+ updatable: ['description'], // Allowed on PATCH
396
+ immutable: ['invoiceNumber'], // Set once, never change
397
+ protected: { status: ['approve'] }, // Only via named actions
398
+ }
399
+ ```
400
+
401
+ System-managed fields (always protected): `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`
402
+
403
+ PUT/Upsert requires both `generateId: false` and `guards: false`.
404
+
405
+ ### 4. Masking — PII Redaction
406
+
407
+ ```typescript
408
+ masking: {
409
+ ssn: { type: 'ssn', show: { roles: ['admin', 'hr'] } },
410
+ email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
411
+ }
412
+ ```
413
+
414
+ Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
415
+
416
+ Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
417
+
418
+ ---
419
+
420
+ ## Views — Column-Level Security
421
+
422
+ Named projections that control which fields are visible based on role.
423
+
424
+ ```typescript
425
+ views: {
426
+ summary: {
427
+ fields: ['id', 'name', 'email'],
428
+ access: { roles: ['member', 'admin'] },
429
+ },
430
+ full: {
431
+ fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
432
+ access: { roles: ['admin'] },
433
+ },
434
+ }
435
+ ```
436
+
437
+ Generated endpoints: `GET /api/v1/{resource}/views/{viewName}`
438
+
439
+ ---
440
+
441
+ ## Validation
442
+
443
+ ```typescript
444
+ validation: {
445
+ name: { minLength: 1, maxLength: 100 },
446
+ capacity: { min: 1, max: 1000 },
447
+ roomType: { enum: ['meeting', 'conference', 'breakout'] },
448
+ email: { email: true },
449
+ code: { pattern: '^[A-Z]{3}$' },
450
+ }
451
+ ```
452
+
453
+ ---
454
+
455
+ ## CMS Record Layouts
456
+
457
+ Control how fields are grouped on the CMS record detail page.
458
+
459
+ ```typescript
460
+ layouts: {
461
+ default: {
462
+ sections: [
463
+ { label: "Contact Info", columns: 2, fields: ["name", "email", "phone"] },
464
+ { label: "Notes", collapsed: true, fields: ["notes", "internalNotes"] },
465
+ ],
466
+ },
467
+ }
468
+ ```
469
+
470
+ Section options: `label` (string), `fields` (string[]), `columns` (1|2, default 1), `collapsed` (boolean, default false). Unassigned fields go to "Other Fields".
471
+
472
+ ---
473
+
474
+ ## Account UI — Authentication & Account Management
475
+
476
+ A complete pre-built SPA for login, signup, profile, organizations, and admin. Built from source at compile time (inside Docker) with your config baked in.
477
+
478
+ ### What's Included
479
+
480
+ | Section | Pages |
481
+ |---------|-------|
482
+ | **Auth** | Login, signup, email OTP, forgot password, email verification |
483
+ | **Account** | Profile, devices/sessions, passkeys, account deletion |
484
+ | **Organizations** | Dashboard, org creation, member management, invitations, API keys, org settings |
485
+ | **Admin** | User management (search, create, ban/unban, reset passwords, view sessions) |
486
+ | **CLI** | Device authorization flow for `quickback login` |
487
+
488
+ ### Enabling
489
+
490
+ ```typescript
491
+ // Minimal
492
+ account: true
493
+
494
+ // Full config
495
+ account: {
496
+ domain: "auth.example.com",
497
+ adminDomain: "admin.example.com",
498
+ name: "My App",
499
+ companyName: "My Company",
500
+ tagline: "Build faster, ship sooner",
501
+ auth: {
502
+ password: true, // Email/password (default: false)
503
+ emailOTP: true, // Email OTP (default: true)
504
+ passkey: true, // WebAuthn passkeys (default: true)
505
+ signup: true, // Registration (default: true)
506
+ organizations: true, // Multi-tenant orgs (default: true)
507
+ admin: true, // Admin panel (default: true)
508
+ emailVerification: true, // Require email verification (default: true)
509
+ },
510
+ }
511
+ ```
512
+
513
+ ### Compile-Time Feature Gating
514
+
515
+ Disabled features are **removed before the Vite build** — route files are excluded from source, so they never appear in the JavaScript bundle. Not runtime checks.
516
+
517
+ ### Routing
518
+
519
+ - **Unified domain (default):** Served at `/account/` alongside CMS at `/cms/` and API at `/api/`
520
+ - **Custom domain:** Served at root `/` on `auth.example.com`
521
+ - **Admin domain:** Admin routes served at root `/` on `admin.example.com`
522
+ - Cross-subdomain auth cookies auto-configured when multiple custom domains detected
523
+
524
+ ### Skip Rebuild
525
+
526
+ ```typescript
527
+ account: { build: false, /* ...other options */ }
528
+ ```
529
+
530
+ Skips the SPA build on subsequent compiles — useful when iterating on API features only.
531
+
532
+ ### Standalone & Library Usage
533
+
534
+ Account UI also works outside the compiler:
535
+ - **Template:** Clone repo, configure `.env`, deploy as separate Worker
536
+ - **Library:** `npm install quickback-better-auth-account-ui` and import as React component
537
+
538
+ Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
539
+
540
+ ---
541
+
542
+ ## Actions — Custom Business Logic
543
+
544
+ Defined in a separate `actions.ts` file using `defineActions()`.
545
+
546
+ ```typescript
547
+ import { todos } from './todos';
548
+ import { defineActions } from '@quickback/compiler';
549
+ import { z } from 'zod';
550
+
551
+ export default defineActions(todos, {
552
+ complete: {
553
+ description: "Mark todo as complete",
554
+ input: z.object({ completedAt: z.string().datetime().optional() }),
555
+ guard: { roles: ["member", "admin"], record: { completed: { equals: false } } },
556
+ execute: async ({ db, record, ctx, input }) => {
557
+ await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
558
+ return { success: true };
559
+ },
560
+ sideEffects: "sync",
561
+ },
562
+ archive: {
563
+ description: "Archive a todo",
564
+ input: z.object({}),
565
+ guard: { roles: ["admin"] },
566
+ handler: "./handlers/archive",
567
+ },
568
+ });
569
+ ```
570
+
571
+ **Record-based** (default): `POST /api/v1/{resource}/:id/{action}`
572
+ **Standalone**: `standalone: true`, custom `path` and `method`
573
+
574
+ Action options: `standalone`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget)
575
+
576
+ ### Actions-Only Features
577
+
578
+ Features that only contain standalone actions (no tables). Use `defineActions(null, { ... })`:
579
+
580
+ ```typescript
581
+ // quickback/features/utilities/actions.ts
582
+ import { defineActions } from '@quickback/compiler';
583
+ import { z } from 'zod';
584
+
585
+ export default defineActions(null, {
586
+ healthCheck: {
587
+ standalone: true,
588
+ path: "/health",
589
+ method: "GET",
590
+ description: "Health check endpoint",
591
+ input: z.object({}),
592
+ guard: { roles: ["member", "admin"] },
593
+ handler: "./handlers/health-check",
594
+ },
595
+ });
596
+ ```
597
+
598
+ All actions in an actions-only feature must have `standalone: true` (since there's no table for record-based actions).
599
+
600
+ ---
601
+
602
+ ## API Reference
603
+
604
+ ### CRUD Operations
605
+
606
+ | Method | Endpoint | Description |
607
+ |--------|----------|-------------|
608
+ | `GET` | `/api/v1/{resource}` | List records |
609
+ | `GET` | `/api/v1/{resource}/:id` | Get single record |
610
+ | `POST` | `/api/v1/{resource}` | Create record |
611
+ | `PATCH` | `/api/v1/{resource}/:id` | Update record |
612
+ | `DELETE` | `/api/v1/{resource}/:id` | Delete record |
613
+ | `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
614
+
615
+ ### Batch Operations
616
+
617
+ `POST|PATCH|DELETE|PUT /api/v1/{resource}/batch` with `{ "records": [...], "options": { "atomic": false } }`
618
+
619
+ ### Query Parameters
620
+
621
+ | Feature | Syntax |
622
+ |---------|--------|
623
+ | Pagination | `?limit=50&offset=0` (max 100) |
624
+ | Filter | `?status=active`, `?amount.gt=100`, `?status.in=draft,pending` |
625
+ | Sort | `?sort=status,-createdAt` (multi-sort, `-` = desc) |
626
+ | Fields | `?fields=id,name,status` |
627
+ | Total count | `?total=true` |
628
+ | Search | `?search=conference` (OR'd LIKE across text columns) |
629
+
630
+ Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
631
+
632
+ ### Response Format
633
+
634
+ ```json
635
+ {
636
+ "data": [{ "id": "...", "title": "Todo 1" }],
637
+ "pagination": { "limit": 10, "offset": 0, "count": 2, "total": 42 }
638
+ }
639
+ ```
640
+
641
+ ### Error Responses
642
+
643
+ | Status | Layer | Meaning |
644
+ |--------|-------|---------|
645
+ | `401` | Auth | Invalid/expired session |
646
+ | `403` | Access | Insufficient permissions |
647
+ | `404` | Firewall | Record not found or outside scope |
648
+ | `400` | Guards | Invalid field modification |
649
+
650
+ ---
651
+
652
+ ## Database Dialects
653
+
654
+ | Stack | Import | Table Function |
655
+ |-------|--------|----------------|
656
+ | Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
657
+ | Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
658
+ | MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
659
+
660
+ ---
661
+
662
+ # PART 2: THE QUICKBACK STACK
663
+
664
+ The Quickback Stack is a production-ready backend platform built entirely on Cloudflare's edge infrastructure. It's a Supabase alternative where everything runs on your own Cloudflare account — your data, your infrastructure, global edge performance.
665
+
666
+ ```
667
+ ┌─────────────────────────────────────────────────────────┐
668
+ │ QUICKBACK STACK ON CLOUDFLARE │
669
+ │ │
670
+ │ Workers — API runtime (Hono) │
671
+ │ D1 — SQLite database at the edge │
672
+ │ R2 — S3-compatible file storage │
673
+ │ KV — Distributed key-value store │
674
+ │ Durable Objects — Realtime WebSockets │
675
+ │ Queues — Background job processing │
676
+ │ Workers AI — Embeddings & vector search │
677
+ │ Better Auth — Authentication & organizations │
678
+ └─────────────────────────────────────────────────────────┘
679
+ ```
680
+
681
+ ## Authentication (Better Auth)
682
+
683
+ Built on Better Auth with multi-tenant organization support.
684
+
685
+ - Email/password, magic links, passkeys, email OTP
686
+ - Three org roles: `owner`, `admin`, `member`
687
+ - Session storage in KV namespace
688
+ - All auth routes at `/auth/v1/*`
689
+ - Extensible via Better Auth plugins
690
+ - **JWT fast-path** — authenticated API requests validate via HMAC-SHA256 JWT (0 DB queries). Tokens mint and rotate automatically; session cookies are the source of truth. Separate from Better Auth's `jwt` plugin (opt-in, for JWKS/external identity). See `quickback docs stack/auth/jwt-optimization`
691
+ - **Account UI** — pre-built SPA for login, signup, profile, orgs, admin (see Account UI section above)
692
+
693
+ ```typescript
694
+ // Config
695
+ providers: {
696
+ auth: defineAuth("better-auth"),
697
+ }
698
+ ```
699
+
700
+ Docs: `quickback docs stack/auth/using-auth` | https://docs.quickback.dev/stack/auth
701
+
702
+ ## Database (D1)
703
+
704
+ SQLite at the edge with zero configuration. Multi-database pattern for independent scaling:
705
+
706
+ | Binding | Purpose |
707
+ |---------|---------|
708
+ | `DB` | Application data (features) |
709
+ | `AUTH_DB` | Auth sessions & users |
710
+ | `FILES_DB` | File metadata |
711
+ | `WEBHOOKS_DB` | Webhook tracking |
712
+
713
+ - Drizzle ORM for type-safe queries
714
+ - Auto-generated migrations on compile
715
+ - Application-layer security (firewall, access, guards, masking)
716
+ - Local dev with `.wrangler/state/`
717
+ - Neon Postgres available as alternative
718
+
719
+ ```typescript
720
+ providers: {
721
+ database: defineDatabase("cloudflare-d1", {
722
+ splitDatabases: true,
723
+ }),
724
+ }
725
+ ```
726
+
727
+ Docs: `quickback docs stack/database/d1` | https://docs.quickback.dev/stack/database/d1
728
+
729
+ ## File Storage (R2)
730
+
731
+ S3-compatible object storage with built-in access control.
732
+
733
+ - Two-worker architecture: API worker (upload/manage) + Files worker (serve)
734
+ - Bucket-scoped access policies (public, organization, user)
735
+ - File metadata tracked in `FILES_DB`
736
+ - Soft deletes with org-level tenant isolation
737
+ - API at `/storage/v1/*`
738
+
739
+ Docs: `quickback docs stack/storage/r2` | https://docs.quickback.dev/stack/storage/r2
740
+
741
+ ## KV Storage
742
+
743
+ Distributed key-value store optimized for reads (300+ edge locations, sub-millisecond).
744
+
745
+ - Use cases: sessions, caching, rate limiting, feature flags
746
+ - Eventually consistent (60 second propagation)
747
+ - TTL/expiration support
748
+
749
+ Docs: `quickback docs stack/storage/kv` | https://docs.quickback.dev/stack/storage/kv
750
+
751
+ ## Realtime (Durable Objects)
752
+
753
+ WebSocket connections for live updates via organization-scoped Durable Objects.
754
+
755
+ - CRUD event broadcasting (insert, update, delete)
756
+ - Custom broadcasts and event namespaces
757
+ - Role-based filtering and per-role field masking
758
+ - Session token or API key authentication
759
+ - Type-safe with `defineRealtime()` for custom events
760
+ - Endpoint: `/realtime/v1/websocket`
761
+
762
+ Docs: `quickback docs stack/realtime/durable-objects` | https://docs.quickback.dev/stack/realtime
763
+
764
+ ## Queues (Background Processing)
765
+
766
+ Cloudflare Queues for reliable async job processing.
767
+
768
+ | Queue | Purpose |
769
+ |-------|---------|
770
+ | `EMBEDDINGS_QUEUE` | Auto-generate embeddings |
771
+ | `WEBHOOKS_QUEUE` | Webhook delivery |
772
+ | Custom queues | Your background jobs |
773
+
774
+ - Custom handlers via `defineQueue()` in `services/queues/`
775
+ - Auto-retry up to 3 times, max batch 10, 30s timeout
776
+ - Chaining between queues
777
+
778
+ Docs: `quickback docs stack/queues/using-queues` | https://docs.quickback.dev/stack/queues
779
+
780
+ ## Vector & Embeddings (Workers AI)
781
+
782
+ Auto-generated embeddings for similarity search and classification.
783
+
784
+ - Table-level config via `embeddings` in `defineTable()`
785
+ - Service-level config via `defineEmbedding()`
786
+ - Default model: `@cf/baai/bge-base-en-v1.5` (768 dimensions)
787
+ - Async processing via `EMBEDDINGS_QUEUE`
788
+ - Vector storage in D1 + optional Vectorize index
789
+ - API: `/api/v1/embeddings`
790
+
791
+ Docs: `quickback docs stack/vector/embeddings` | https://docs.quickback.dev/stack/vector
792
+
793
+ ## Webhooks
794
+
795
+ ### Inbound (Receiving)
796
+
797
+ Receive events from Stripe, Paddle, GitHub, etc. at `POST /webhooks/v1/inbound/:provider`
798
+
799
+ ```typescript
800
+ import { onWebhookEvent } from './lib/webhooks';
801
+
802
+ onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
803
+ const { data, env } = ctx;
804
+ await createSubscription({ ... });
805
+ });
806
+ ```
807
+
808
+ ### Outbound (Sending)
809
+
810
+ Emit signed events when data changes. HMAC-SHA256 signing, async delivery via queue with exponential backoff retry.
811
+
812
+ ```typescript
813
+ import { emitWebhookEvent } from './lib/webhooks';
814
+
815
+ await emitWebhookEvent('user.created', { id: user.id, email: user.email }, { organizationId: orgId }, env);
816
+ ```
817
+
818
+ Event patterns: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
819
+ Endpoint management: `/webhooks/v1/endpoints`
820
+
821
+ Docs: `quickback docs stack/webhooks/outbound` | https://docs.quickback.dev/stack/webhooks
822
+
823
+ ---
824
+
825
+ # CLI Commands
826
+
827
+ | Command | Description |
828
+ |---------|-------------|
829
+ | `quickback create <template> <name>` | Create project from template |
830
+ | `quickback compile` | Compile definitions to output (copies CMS assets if `cms: true`) |
831
+ | `quickback docs [topic]` | Browse built-in documentation |
832
+ | `quickback login` | Authenticate for Pro templates |
833
+ | `quickback logout` | Clear stored credentials |
834
+ | `quickback whoami` | Show current auth status |
835
+ | `quickback claude install` | Install Claude Code skill |
836
+ | `quickback claude update` | Update to latest skill version |
837
+
838
+ ## Available Templates
839
+
840
+ | Template | Stack | Status |
841
+ |----------|-------|--------|
842
+ | `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
843
+ | `bun` | Bun + SQLite + Better Auth | Free |
844
+ | `turso` | Turso/LibSQL + Better Auth | Pro |
845
+
846
+ ## Development Workflow
847
+
848
+ ```bash
849
+ quickback create cloudflare my-app # 1. Create project
850
+ # Define features in quickback/features/
851
+ quickback compile # 2. Compile
852
+ npm install && npm run dev # 3. Run
853
+ ```
854
+
855
+ ---
856
+
857
+ # Online Documentation
858
+
859
+ - [Getting Started](https://docs.quickback.dev/compiler/getting-started)
860
+ - [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
861
+ - [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
862
+ - [Firewall](https://docs.quickback.dev/compiler/definitions/firewall)
863
+ - [Access](https://docs.quickback.dev/compiler/definitions/access)
864
+ - [Guards](https://docs.quickback.dev/compiler/definitions/guards)
865
+ - [Masking](https://docs.quickback.dev/compiler/definitions/masking)
866
+ - [Views](https://docs.quickback.dev/compiler/definitions/views)
867
+ - [Actions](https://docs.quickback.dev/compiler/definitions/actions)
868
+ - [CRUD API](https://docs.quickback.dev/compiler/using-the-api/crud)
869
+ - [Query Parameters](https://docs.quickback.dev/compiler/using-the-api/query-params)
870
+ - [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)
871
+ - [Stack Overview](https://docs.quickback.dev/stack)
872
+ - [D1 Database](https://docs.quickback.dev/stack/database/d1)
873
+ - [R2 Storage](https://docs.quickback.dev/stack/storage/r2)
874
+ - [Realtime](https://docs.quickback.dev/stack/realtime)
875
+ - [Queues](https://docs.quickback.dev/stack/queues)
876
+ - [Embeddings](https://docs.quickback.dev/stack/vector)
877
+ - [Webhooks](https://docs.quickback.dev/stack/webhooks)
878
+ - [Account UI Overview](https://docs.quickback.dev/account-ui)
879
+ - [Account UI with Quickback](https://docs.quickback.dev/account-ui/with-quickback)
880
+ - [Account UI Standalone](https://docs.quickback.dev/account-ui/standalone)
881
+ - [Account UI Features](https://docs.quickback.dev/account-ui/features)
882
+ - [Account UI Environment Variables](https://docs.quickback.dev/account-ui/environment-variables)
883
+ - [Account UI Customization](https://docs.quickback.dev/account-ui/customization)
884
+ - [CMS Overview](https://docs.quickback.dev/cms)
885
+ - [CMS Dashboard](https://docs.quickback.dev/cms/dashboard)
886
+ - [CMS Custom Pages](https://docs.quickback.dev/cms/pages)
887
+ - [CMS Record Layouts](https://docs.quickback.dev/cms/record-layouts)