@quickback-dev/cli 0.10.16 → 0.10.20

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 (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,52 @@
1
+ # Glossary
2
+
3
+ Quick reference for terms used across the Quickback documentation.
4
+
5
+ ## Core Concepts
6
+
7
+ | Term | Definition |
8
+ |------|-----------|
9
+ | **Feature** | A directory in `quickback/features/` containing related tables and actions. Example: a `candidates` feature with `candidates.ts`, `candidate-notes.ts`, and `actions.ts`. |
10
+ | **Resource** | A table with a `defineTable()` default export. Each resource gets its own CRUD API endpoints (`GET`, `POST`, `PATCH`, `DELETE`, plus batch operations). Example: `candidates.ts` with `defineTable()` generates `/api/v1/candidates`. |
11
+ | **Internal Table** | A Drizzle table exported WITHOUT `defineTable()`. Used as supporting data (junction tables, lookup tables) — no API routes generated. |
12
+ | **Definition** | A TypeScript file in `quickback/features/` that defines a table schema and/or security configuration. |
13
+ | **Compilation** | The process of transforming your definitions into production-ready code: routes, middleware, types, and migrations. |
14
+
15
+ ## Security Layers
16
+
17
+ | Term | Definition |
18
+ |------|-----------|
19
+ | **Firewall** | Row-level data isolation. Automatically adds WHERE clauses (e.g., `WHERE organizationId = ?`) to every query so users only see data they should. |
20
+ | **Access** | CRUD operation permissions. Controls which roles can perform list, get, create, update, and delete operations. |
21
+ | **Guards** | Field-level write protection. Controls which fields can be set on create (`createable`), modified on update (`updatable`), changed only via actions (`protected`), or never changed after creation (`immutable`). |
22
+ | **Masking** | Field-level read protection. Redacts sensitive values (SSN, email, phone) in API responses based on the user's role. |
23
+ | **Views** | Column-level projections. Named subsets of fields (e.g., "summary", "full") with their own access control. Accessed via `GET /api/v1/{resource}/views/{name}`. |
24
+
25
+ ## Actions
26
+
27
+ | Term | Definition |
28
+ |------|-----------|
29
+ | **Action** | Custom business logic endpoint beyond CRUD. Defined with `defineActions()` in an `actions.ts` file. |
30
+ | **Record Action** | An action that operates on a specific record (`POST /api/v1/{resource}/:id/{action}`). Receives the record in the handler. Example: `POST /api/v1/applications/:id/advance-stage`. |
31
+ | **Standalone Action** | An action not tied to a specific record (`POST /api/v1/{resource}/{action}`). Used for hiring reports, AI resume screening, bulk candidate imports. |
32
+ | **Scoped DB** | The security-filtered database handle passed to action handlers. Automatically applies firewall, soft-delete, and org isolation. |
33
+ | **Unsafe Mode** | When an action enables `unsafe` (prefer object form), it receives `rawDb` for explicit admin/cross-tenant operations. Cross-tenant mode requires admin role + audit trail. |
34
+
35
+ ## Configuration
36
+
37
+ | Term | Definition |
38
+ |------|-----------|
39
+ | **`defineTable()`** | The function that combines a Drizzle schema with security configuration. Imported from `@quickback/compiler`. |
40
+ | **`defineActions()`** | The function that defines custom actions for a table. Imported from `@quickback/compiler`. |
41
+ | **`defineConfig()`** | The function that configures your Quickback project (runtime, database, auth providers). Lives in `quickback/quickback.config.ts`. |
42
+ | **Audit Fields** | Auto-injected columns: `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`. You don't define these — the compiler adds them. |
43
+ | **Soft Delete** | Default delete behavior. Sets `deletedAt` instead of removing the row. Soft-deleted records are filtered from queries automatically. |
44
+ | **Hard Delete** | Permanent row removal. Configured per-resource with `delete: { mode: "hard" }`. |
45
+
46
+ ## Infrastructure
47
+
48
+ | Term | Definition |
49
+ |------|-----------|
50
+ | **Cloud Compiler** | The remote compilation service at `compiler.quickback.dev`. The CLI sends your definitions and receives generated code back. |
51
+ | **Stack** | The runtime infrastructure (Cloudflare Workers, D1, KV, R2, Better Auth) where your compiled API runs. |
52
+ | **Template** | A pre-configured project starter (`cloudflare`, `bun`, `turso`) created by `quickback create`. |
@@ -0,0 +1,164 @@
1
+ # feature() — single-export sugar
2
+
3
+ The `q.table()` + `defineTable()` pair has been co-equal with Drizzle since day one. It works, but it means two exports and two concepts for something most feature files treat as one unit: a table with a security contract.
4
+
5
+ `feature()` collapses both into a single default export.
6
+
7
+ ## Before
8
+
9
+ ```ts title="quickback/features/contacts.ts"
10
+ import { q, defineTable } from "@quickback/compiler";
11
+
12
+ export const contacts = q.table("contacts", {
13
+ id: q.id(),
14
+ organizationId: q.text().required().index(),
15
+ address: q.text().required().index(),
16
+ name: q.text().optional(),
17
+ });
18
+
19
+ export default defineTable(contacts, {
20
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
21
+ read: { access: { roles: ["member+"] } },
22
+ crud: {
23
+ create: { access: { roles: ["member+"] } },
24
+ update: { access: { roles: ["member+"] } },
25
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
26
+ },
27
+ guards: { createable: ["address", "name"] },
28
+ });
29
+
30
+ export type Contact = typeof contacts.$infer;
31
+ ```
32
+
33
+ ## After
34
+
35
+ ```ts title="quickback/features/contacts.ts"
36
+ import { feature, q } from "@quickback/compiler";
37
+
38
+ export default feature("contacts", {
39
+ columns: {
40
+ id: q.id(),
41
+ organizationId: q.text().required().index(),
42
+ address: q.text().required().index(),
43
+ name: q.text().optional(),
44
+ },
45
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
46
+ read: { access: { roles: ["member+"] } },
47
+ crud: {
48
+ create: { access: { roles: ["member+"] } },
49
+ update: { access: { roles: ["member+"] } },
50
+ delete: { access: { roles: ["admin+"] }, mode: "soft" },
51
+ },
52
+ guards: { createable: ["address", "name"] },
53
+ });
54
+ ```
55
+
56
+ Type inference still works — `typeof import("./contacts").default.$infer` gives you the `Contact` row type.
57
+
58
+ ## How it works
59
+
60
+ `feature(name, config)` is a **compile-time sugar**, not a runtime abstraction. When the compiler sees `export default feature(...)`, it rewrites the source to the canonical two-export form before any parsing runs. Every downstream layer — dialect pass, audit injection, security contracts, CRUD routes, OpenAPI, MCP tools, RLS emission — runs on the same Drizzle source it always did. Zero runtime cost; zero semantic difference from `q.table()` + `defineTable()`.
61
+
62
+ That means:
63
+
64
+ - **Both forms remain supported indefinitely.** Mix them freely — some files `feature(...)`, some files `q.table() + defineTable()`, some files Drizzle `sqliteTable() + defineTable()`. The compiler dispatches per file.
65
+ - **Action files reference the table by default import.** `import contacts from "./contacts"` gives you the same typed handle `q.table("contacts", ...)` would have returned, so `defineActions(contacts, { … })` still works.
66
+ - **Diagnostics are identical.** Missing firewall → same warning. Protected-field wiring → same check. Nothing about `feature()` weakens the secure-by-default posture.
67
+
68
+ ## Aliases
69
+
70
+ `q` is canonical (matches Zod's `z.`, Superstruct's `s.`). `qb` is exported as an alias if you'd rather self-document the namespace:
71
+
72
+ ```ts
73
+ import { feature, qb } from "@quickback/compiler";
74
+
75
+ export default feature("contacts", {
76
+ columns: { id: qb.id(), name: qb.text().required() },
77
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
78
+ // …
79
+ });
80
+ ```
81
+
82
+ Same object, two names — pick one.
83
+
84
+ ## When to use which
85
+
86
+ | Pattern | When |
87
+ |---|---|
88
+ | `feature(name, {...})` | Default. One table, one security contract, one file. |
89
+ | `q.table()` + `defineTable()` | Multiple tables per file (rare), or you want to reference the table identifier before the default export. |
90
+ | `sqliteTable()` / `pgTable()` + `defineTable()` | Interop with existing Drizzle code / migrations. |
91
+ | `q.table(...)` alone (no `defineTable`) | Internal join/lookup/pivot tables with no public API. Compiler warns so you confirm the opt-out is intentional. |
92
+
93
+ ## Feature directory layout
94
+
95
+ A feature directory holds tables, optional shared schemas, and the handler files that back any actions:
96
+
97
+ ```
98
+ features/podcast/
99
+ ├── episodes.ts ← defineTable + (optional) defineActions(episodes, {…})
100
+ ├── shows.ts ← defineTable + (optional) defineActions(shows, {…})
101
+ ├── episode-tags.ts ← defineTable only (junction)
102
+ ├── _feature.ts ← non-table-bound actions + shared zod schemas
103
+ ├── handlers/
104
+ │ ├── episodes/{publish,revertToDraft}.ts
105
+ │ └── shows/…
106
+ └── lib/
107
+ └── shared.ts ← feature-local helpers, copied verbatim
108
+ ```
109
+
110
+ Three things to know:
111
+
112
+ - **`handlers/` walks recursively**, keyed by relative path (`handlers/episodes/publish.ts`). The canonical layout is per-table subdirectories so action handlers stay grouped with the table they act on.
113
+ - **`lib/` rides along** — feature-local helper modules get copied verbatim into the generated output. Use this for shared utilities that both handlers and inline `execute:` bodies reference.
114
+ - **`_feature.ts` is the universal slot** for non-table-bound actions and shared schemas. Top-level decls in `_feature.ts` get prepended once to the merged actions module, so a `const sharedSchema = z.object({…})` in `_feature.ts` is referenceable from any sibling action's `input:` without re-declaring it.
115
+
116
+ For everything action-related — three modes, conflict rules, the `_feature.ts` shape — see [Actions](/compiler/definitions/actions).
117
+
118
+ ## Handlers — one `q` namespace for everything
119
+
120
+ Custom action handlers need to run queries against the database. Quickback's compiled projects expose the Drizzle query-builder helpers on the same `q` namespace you use for schema authoring, so handler code stays inside one DSL:
121
+
122
+ ```ts title="quickback/features/mail/handlers/inbound.ts"
123
+ import { q } from "../../../lib/q";
124
+ import mailboxes from "../mailboxes";
125
+ import messages from "../messages";
126
+ import threads from "../threads";
127
+
128
+ export const execute = async ({ unsafeDb, input }) => {
129
+ // Find the mailbox this email was addressed to
130
+ const mailbox = await unsafeDb.query.mailboxes.findFirst({
131
+ where: q.eq(mailboxes.address, input.mailboxAddress),
132
+ });
133
+ if (!mailbox) return { error: "unknown mailbox" };
134
+
135
+ // Look up the thread by in-reply-to + organization scope
136
+ const thread = input.parsed.inReplyTo
137
+ ? await unsafeDb.query.threads.findFirst({
138
+ where: q.and(
139
+ q.eq(threads.organizationId, mailbox.organizationId),
140
+ q.eq(threads.lastMessageId, input.parsed.inReplyTo),
141
+ ),
142
+ })
143
+ : null;
144
+
145
+ // Insert the new message
146
+ await unsafeDb.insert(messages).values({
147
+ id: crypto.randomUUID(),
148
+ threadId: thread?.id,
149
+ organizationId: mailbox.organizationId,
150
+ subject: input.parsed.subject,
151
+ createdAt: new Date().toISOString(),
152
+ });
153
+
154
+ return { ok: true };
155
+ };
156
+ ```
157
+
158
+ The `q` in handlers is a runtime re-export of Drizzle's query builder — `q.eq`, `q.and`, `q.or`, `q.not`, `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, zero wrapper cost.
159
+
160
+ **The compiler generates `src/lib/q.ts`** in every project so the runtime `q` is always available. You never need to `import { eq } from "drizzle-orm"` in a handler — though you can if you want (Quickback doesn't hide drizzle, it just offers a consistent surface that matches the schema DSL).
161
+
162
+ ## Why one namespace
163
+
164
+ Quickback is an opinionated wrapper with opinionated security. One DSL for schema (`q.table`, `q.text`, `q.id`), one DSL for queries (`q.eq`, `q.and`, `q.gte`), one opt-in for routes (`feature()` / `defineTable`). You never need to learn the names of the underlying tools to write a feature — the same way Next.js users don't need to know they're using webpack, or Astro users don't need to know they're using Vite.
@@ -0,0 +1,285 @@
1
+ # Firewall - Data Isolation
2
+
3
+ The firewall generates WHERE clauses automatically to isolate data by user, organization, or team.
4
+
5
+ ## Basic Usage
6
+
7
+ The cleanest pattern is `q.scope()` — declare the tenant column once and the firewall is auto-derived:
8
+
9
+ ```typescript
10
+ // features/candidates/candidates.ts
11
+ import { feature, q } from '@quickback/compiler';
12
+
13
+ export default feature('candidates', {
14
+ columns: {
15
+ id: q.id(),
16
+ name: q.text().required(),
17
+ email: q.text().required(),
18
+ organizationId: q.scope('organization'), // Auto-derives the firewall
19
+ },
20
+ // No firewall: block needed — auto-derived as
21
+ // [{ field: 'organizationId', equals: 'ctx.activeOrgId' },
22
+ // { field: 'deletedAt', isNull: true }]
23
+ // ... guards, crud, read
24
+ });
25
+ ```
26
+
27
+ If you need to declare the firewall explicitly, two forms are accepted — pick whichever reads better:
28
+
29
+ **Named-scope** (compact, default for simple overrides):
30
+
31
+ ```typescript
32
+ firewall: { organization: { column: 'tenant_id' } }
33
+ firewall: { owner: { column: 'account_user_id' } }
34
+ firewall: { exception: true } // opt out of tenant scoping entirely
35
+ ```
36
+
37
+ **Predicate array** (explicit, required for `in`-lists or custom non-scope predicates):
38
+
39
+ ```typescript
40
+ firewall: [
41
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
42
+ { field: 'deletedAt', isNull: true },
43
+ ]
44
+ ```
45
+
46
+ Both shapes compile to the same canonical predicate array internally — the named-scope object is coerced at parse time. Pick by readability.
47
+
48
+ ## Auto-detected column synonyms
49
+
50
+ When you omit the `firewall:` block entirely, the compiler scans the schema for one of these isolation columns and auto-derives the predicates:
51
+
52
+ | Scope | Accepted column names |
53
+ |---|---|
54
+ | Organization | `organizationId`, `organisationId`, `orgId`, `organization`, `organisation`, `org` |
55
+ | User | `userId` |
56
+ | Team | `teamId` |
57
+
58
+ `ownerId` is **not** auto-detected — it's reserved for business-logic ownership (who owns this record), not access control. A table that has only `ownerId` and no isolation column raises a targeted error explaining the distinction; either rename to `userId` if the column controls access, add an isolation column, or specify `firewall:` explicitly.
59
+
60
+ ## Predicate Shape
61
+
62
+ ```typescript
63
+ type FirewallPredicate =
64
+ | { field: string; equals: string } // column = ctx.* (or literal)
65
+ | { field: string; isNull: true } // column IS NULL
66
+ | { field: string; in: string[] | string }// column IN (...)
67
+ | { exception: true }; // opt out of tenant scoping
68
+
69
+ type FirewallConfig = ReadonlyArray<FirewallPredicate>;
70
+
71
+ // Resource top-level (sibling to `firewall:`)
72
+ firewallErrorMode?: 'reveal' | 'hide';
73
+ ```
74
+
75
+ Predicates are AND'd together. `firewallErrorMode` lives at the resource top level — it's a presentation-layer choice (403 vs 404), not a query-shape one.
76
+
77
+ ## Context Sources
78
+
79
+ When `equals` references the request context, use these standard sources:
80
+
81
+ | Source | Description |
82
+ |--------|-------------|
83
+ | `ctx.userId` | Current authenticated user's ID |
84
+ | `ctx.activeOrgId` | User's active organization ID |
85
+ | `ctx.activeTeamId` | User's active team ID |
86
+
87
+ These values are populated by the auth middleware from the user's session. Any predicate where `equals` starts with `ctx.` is treated as server-derived: the column lands in `GUARDS_CONFIG.systemManaged` (clients cannot submit it) and is auto-populated on create / upsert from the context.
88
+
89
+ ## Auto-Derivation
90
+
91
+ When the `firewall:` block is omitted, the compiler scans the schema for known scope columns and synthesises the predicate array:
92
+
93
+ | Column found | Predicate emitted |
94
+ |--------------|-------------------|
95
+ | `organizationId` / `organisationId` / `orgId` / `organization` / `organisation` / `org` | `{ field: '...', equals: 'ctx.activeOrgId' }` |
96
+ | `userId` | `{ field: 'userId', equals: 'ctx.userId' }` |
97
+ | `teamId` | `{ field: 'teamId', equals: 'ctx.activeTeamId' }` |
98
+ | `deletedAt` (always present via audit injection) | `{ field: 'deletedAt', isNull: true }` — appended automatically whenever the schema carries the column, regardless of which firewall shape you wrote |
99
+
100
+ `q.scope(kind)` is the canonical way to declare the column — auto-derivation works the same way for plain `q.text().required()` or Drizzle `text(...).notNull()` columns named to match the convention.
101
+
102
+ **Rules:**
103
+ - Exactly one isolation column → auto-derived.
104
+ - Zero columns AND no PUBLIC route → compile-time error ("missing isolation column").
105
+ - Two or more (e.g. `organizationId` + `ownerId`) → compile-time error; declare `firewall:` explicitly.
106
+
107
+ ## What `{ exception: true }` Actually Does
108
+
109
+ `{ exception: true }` disables **tenant scoping only** — the generated `buildFirewallConditions()` emits no tenant `WHERE` clauses. It does **not** affect:
110
+
111
+ - **Audit field injection.** `createdAt`, `modifiedAt`, `createdBy`, `modifiedBy`, `deletedAt`, `deletedBy` are always added to every table unless you disable them globally with `compiler.features.auditFields: false`.
112
+ - **Soft-delete filtering.** If the table has a `deletedAt` column (which it does by default, thanks to audit injection), the firewall still emits `isNull(<table>.deletedAt)` so soft-deleted records stay hidden. To opt out of soft-delete filtering on an exception resource, either set `compiler.features.auditFields: false` globally or hand-author a schema without `deletedAt`.
113
+
114
+ So `firewall: [{ exception: true }]` on the default configuration returns `isNull(<table>.deletedAt)` from `buildFirewallConditions()` — no tenant filter, soft-delete filter still applied.
115
+
116
+ ## Common Patterns
117
+
118
+ ```typescript
119
+ // Public/system table - no tenant filtering (soft-delete still applied)
120
+ firewall: [{ exception: true }]
121
+
122
+ // Organization-scoped (auto-derived when organizationId is present — block can be omitted)
123
+ firewall: [
124
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
125
+ { field: 'deletedAt', isNull: true },
126
+ ]
127
+
128
+ // User-owned personal data
129
+ firewall: [
130
+ { field: 'ownerId', equals: 'ctx.userId' },
131
+ { field: 'deletedAt', isNull: true },
132
+ ]
133
+
134
+ // Multi-tenant + per-team scoping
135
+ firewall: [
136
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
137
+ { field: 'teamId', equals: 'ctx.activeTeamId' },
138
+ { field: 'deletedAt', isNull: true },
139
+ ]
140
+
141
+ // Custom ctx field
142
+ firewall: [
143
+ { field: 'workspaceId', equals: 'ctx.activeWorkspaceId' },
144
+ ]
145
+
146
+ // Status-gated (literal value, not ctx-derived — does NOT add to systemManaged)
147
+ firewall: [
148
+ { field: 'organizationId', equals: 'ctx.activeOrgId' },
149
+ { field: 'status', in: ['active', 'pending'] },
150
+ ]
151
+ ```
152
+
153
+ ## Error Responses
154
+
155
+ When a record isn't found behind the firewall (wrong org, soft-deleted, or genuinely doesn't exist), the error response depends on `firewallErrorMode`:
156
+
157
+ ### Reveal Mode (Default)
158
+
159
+ Returns **403** with a structured error:
160
+
161
+ ```json
162
+ {
163
+ "error": "Record not found or not accessible",
164
+ "layer": "firewall",
165
+ "code": "FIREWALL_NOT_FOUND",
166
+ "hint": "Check the record ID and your organization membership"
167
+ }
168
+ ```
169
+
170
+ This is developer-friendly and helps debug access issues during development.
171
+
172
+ ### Hide Mode
173
+
174
+ Returns **404** with a generic error:
175
+
176
+ ```json
177
+ {
178
+ "error": "Not found",
179
+ "code": "NOT_FOUND"
180
+ }
181
+ ```
182
+
183
+ Use `firewallErrorMode: 'hide'` for security-hardened deployments where you don't want attackers to distinguish between "record exists but you can't access it" and "record doesn't exist":
184
+
185
+ ```typescript
186
+ export default defineTable(records, {
187
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
188
+ firewallErrorMode: 'hide', // Opaque 404s prevent record enumeration
189
+ });
190
+ ```
191
+
192
+ ### Foreign-Key Referential Checks
193
+
194
+ Generated `POST /` and `POST /batch` handlers validate every foreign-key column against the **target table's** firewall before inserting. If a record references a row that the caller can't see (wrong org, soft-deleted, or non-existent), the request fails with:
195
+
196
+ ```json
197
+ {
198
+ "error": "Referenced jobs row not found",
199
+ "code": "FK_NOT_FOUND",
200
+ "layer": "validation",
201
+ "field": "jobId"
202
+ }
203
+ ```
204
+
205
+ This closes a cross-tenant injection vector: even if an attacker knows a foreign tenant's row ID, they cannot attach a child record to it, and they cannot trigger a cross-tenant cascade delete. The check uses the target table's `buildXFirewallConditions(ctx)` helper, so it honors whatever firewall predicates the target declared (organization, owner, team, custom). FKs to tables with `{ exception: true }` get a plain existence check (still verifies the row exists, doesn't tenant-scope it).
206
+
207
+ The check runs after guards but before the insert, so it appears as `layer: "validation"` in error responses. Status code is `400`, not `404` — returning `404` would leak existence of out-of-scope rows.
208
+
209
+ ### Pre-Record ID-Probe Defense
210
+
211
+ Independent of `firewallErrorMode`, generated `/:id` handlers run a
212
+ **role-only access check before** the firewall query (see
213
+ [Access ordering](/compiler/definitions/access#evaluation-order)). A caller
214
+ without the right role gets 403 before the database is touched, so they
215
+ can't distinguish "row exists out-of-scope" from "row doesn't exist" via
216
+ response timing or status differences.
217
+
218
+ `firewallErrorMode` controls what happens **after** the role check passes
219
+ but the firewall hides the row — i.e., when an authorized caller asks for
220
+ a record in another tenant. Use `'hide'` to make that case indistinguishable
221
+ from a non-existent ID.
222
+
223
+ ## Rules
224
+
225
+ - Every resource MUST have at least one tenant predicate OR `{ exception: true }` OR a PUBLIC route
226
+ - `{ exception: true }` cannot be combined with tenant predicates in the same array
227
+
228
+ ## Why Can't You Mix `{ exception: true }` with Tenant Predicates?
229
+
230
+ They represent opposite intentions:
231
+ - `{ exception: true }` = "Don't generate tenant `WHERE` clauses, data is public/global"
232
+ - Tenant predicates = "Generate tenant `WHERE` clauses to isolate data"
233
+
234
+ Combining them would be contradictory — you can't both isolate and not isolate. (Note: soft-delete filtering is independent of this decision, see above.)
235
+
236
+ ## Handling "Some Public, Some Private" Data
237
+
238
+ If you need records that are sometimes public and sometimes scoped, you have two options:
239
+
240
+ ### Option 1: Two Separate Tables
241
+
242
+ Split into two tables - one public, one scoped:
243
+
244
+ ```typescript
245
+ // features/job-templates/template-library.ts - Public job templates
246
+ export default defineTable(templateLibrary, {
247
+ firewall: [{ exception: true }],
248
+ // ...
249
+ });
250
+
251
+ // features/job-templates/custom-templates.ts - Org's custom job templates
252
+ export default defineTable(customTemplates, {
253
+ firewall: [{ field: 'ownerId', equals: 'ctx.userId' }],
254
+ // ...
255
+ });
256
+ ```
257
+
258
+ ### Option 2: Use Access Control Instead
259
+
260
+ Keep tenant scope but make access permissive, then control visibility via `access`:
261
+
262
+ ```typescript
263
+ // features/jobs/jobs.ts
264
+ export default defineTable(jobs, {
265
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
266
+ read: {
267
+ // Anyone in the org can list — visibility differences are handled
268
+ // via record-level access conditions on /:id
269
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
270
+ },
271
+ crud: {
272
+ // Use record conditions to allow public jobs OR owned jobs on GET /:id
273
+ // (single-record GET inherits read.access, with optional record-level overrides)
274
+ },
275
+ // ...
276
+ });
277
+ ```
278
+
279
+ ### Which to Choose?
280
+
281
+ | Scenario | Recommendation |
282
+ |----------|----------------|
283
+ | Truly global data (app config, public job templates) | `exception: true` in separate resource |
284
+ | "Public within org" but still org-isolated | Ownership scope + permissive access rules |
285
+ | Recruiter can toggle job postings public/private | Ownership scope + `visibility` field + access conditions |