@quickback-dev/cli 0.10.15 → 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,241 @@
1
+ # Guards - Field Modification Rules
2
+
3
+ Control which fields can be modified in CREATE vs UPDATE operations.
4
+
5
+ ## Basic Usage
6
+
7
+ ```typescript
8
+ // features/applications/applications.ts
9
+ import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
10
+ import { defineTable } from '@quickback/compiler';
11
+
12
+ export const applications = sqliteTable('applications', {
13
+ id: text('id').primaryKey(),
14
+ candidateId: text('candidate_id').notNull(),
15
+ jobId: text('job_id').notNull(),
16
+ stage: text('stage').notNull().default('applied'),
17
+ appliedAt: text('applied_at').notNull(),
18
+ notes: text('notes'),
19
+ organizationId: text('organization_id').notNull(),
20
+ });
21
+
22
+ export default defineTable(applications, {
23
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
24
+ guards: {
25
+ createable: ["candidateId", "jobId", "notes"],
26
+ updatable: ["notes"],
27
+ protected: {
28
+ stage: ["advance-stage", "reject"],
29
+ },
30
+ immutable: ["appliedAt", "candidateId", "jobId"],
31
+ },
32
+ crud: {
33
+ // ...
34
+ },
35
+ });
36
+ ```
37
+
38
+ ## Configuration Options
39
+
40
+ ```typescript
41
+ guards: {
42
+ // Fields allowed on CREATE
43
+ createable?: string[];
44
+
45
+ // Fields allowed on UPDATE/PATCH
46
+ updatable?: string[];
47
+
48
+ // Fields only modifiable via specific actions
49
+ protected?: Record<string, string[]>;
50
+
51
+ // Fields set on CREATE, never modified after
52
+ immutable?: string[];
53
+ }
54
+ ```
55
+
56
+ ## How It Works
57
+
58
+ | List | What it controls |
59
+ |------|------------------|
60
+ | `createable` | Fields allowed in create (POST) request body |
61
+ | `updatable` | Fields allowed in update (PATCH) request body |
62
+ | `protected` | Fields blocked from CRUD, only modifiable via named actions |
63
+ | `immutable` | Fields allowed on create, blocked on all updates |
64
+
65
+ **Combining lists:**
66
+
67
+ - `createable` + `updatable` - Most fields go in both (can set on create AND modify later)
68
+ - `createable` only - Field is set once, cannot be changed via update
69
+ - `protected` - Don't also list in `createable` or `updatable` (they're mutually exclusive)
70
+ - `immutable` - Don't also list in `updatable` (contradiction)
71
+
72
+ ```typescript
73
+ guards: {
74
+ createable: ["candidateId", "jobId", "notes", "source"],
75
+ updatable: ["notes"],
76
+ // "candidateId", "jobId" are only in createable = set once, can't change via update
77
+ protected: {
78
+ stage: ["advance-stage", "reject"], // NOT in createable/updatable
79
+ },
80
+ immutable: ["appliedAt"], // NOT in updatable
81
+ }
82
+ ```
83
+
84
+ **If a field is not listed anywhere, it cannot be set by the client.**
85
+
86
+ ## System-Managed Fields (Always Protected)
87
+
88
+ `GUARDS_CONFIG.systemManaged` rejects any field in this set from client input — even with `guards: false`. The set always includes the audit fields:
89
+
90
+ - `createdAt`, `createdBy`
91
+ - `modifiedAt`, `modifiedBy`
92
+ - `deletedAt`, `deletedBy`
93
+
94
+ It also extends with **scope columns** — any firewall predicate whose `equals` references `ctx.*` adds its `field` to systemManaged. Most commonly this comes from `q.scope()`:
95
+
96
+ ```typescript
97
+ columns: {
98
+ organizationId: q.scope('organization'), // → adds 'organizationId' to systemManaged
99
+ }
100
+ ```
101
+
102
+ The same applies to a hand-rolled firewall:
103
+
104
+ ```typescript
105
+ firewall: [
106
+ { field: 'tenantId', equals: 'ctx.activeOrgId' }, // → systemManaged
107
+ { field: 'workspaceId', equals: 'ctx.activeWorkspaceId' }, // → systemManaged
108
+ { field: 'status', equals: 'active' }, // literal, NOT added
109
+ ]
110
+ ```
111
+
112
+ The semantic rule is "if the firewall says this column's value comes from the request context, the client cannot submit it." The value is auto-populated on create / upsert from `ctx`.
113
+
114
+ ## Example
115
+
116
+ ```typescript
117
+ guards: {
118
+ createable: ["candidateId", "jobId", "notes"],
119
+ updatable: ["notes"],
120
+ protected: {
121
+ stage: ["advance-stage", "reject"], // Only these actions can modify stage
122
+ },
123
+ immutable: ["appliedAt", "candidateId", "jobId"],
124
+ }
125
+ ```
126
+
127
+ ## Disabling Guards
128
+
129
+ ```typescript
130
+ guards: false // Only system fields protected
131
+ ```
132
+
133
+ When `guards: false` is set, all user-defined fields become writable via CRUD operations. This is useful for:
134
+ - External sync scenarios where you need full field control
135
+ - Batch upsert operations where field restrictions would be limiting
136
+ - Simple tables where field-level protection isn't needed
137
+
138
+ ## PUT/Upsert with External IDs
139
+
140
+ When you disable guards AND use client-provided IDs, you unlock PUT (upsert) operations. This is designed for **syncing data from external systems**.
141
+
142
+ ### Requirements for PUT
143
+
144
+ 1. `generateId: false` in database config (client provides IDs)
145
+ 2. `guards: false` in resource definition
146
+
147
+ ### How PUT Works
148
+
149
+ ```
150
+ PUT /resource/:id
151
+ ├── Record exists? → UPDATE (replace all fields)
152
+ └── Record missing? → CREATE with provided ID
153
+ ```
154
+
155
+ ### Database Config
156
+
157
+ ```typescript
158
+ // quickback.config.ts
159
+ export default {
160
+ database: {
161
+ generateId: false, // Client provides IDs (enables PUT)
162
+ // Other options: 'uuid' | 'cuid' | 'nanoid' | 'short' | 'prefixed' | 'serial'
163
+ }
164
+ };
165
+ ```
166
+
167
+ ### Table Definition
168
+
169
+ ```typescript
170
+ // features/integrations/ats-imports.ts
171
+ export default defineTable(atsImports, {
172
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
173
+ guards: false, // Disables field restrictions
174
+ crud: {
175
+ put: {
176
+ access: { roles: ['hiring-manager', 'sync-service'] }
177
+ }
178
+ },
179
+ });
180
+ ```
181
+
182
+ ## What's Still Protected with guards: false
183
+
184
+ Even with `guards: false`, system-managed fields are ALWAYS protected. This includes:
185
+
186
+ - `createdAt`, `createdBy` — set on INSERT only
187
+ - `modifiedAt`, `modifiedBy` — auto-updated
188
+ - `deletedAt`, `deletedBy` — set on soft delete
189
+ - Any column declared via `q.scope()` (or any firewall predicate using `equals: 'ctx.*'`) — auto-populated from request context
190
+
191
+ So `guards: false` only opens up user-defined business fields. Tenant scope and audit fields stay locked down regardless.
192
+
193
+ ## Ownership Auto-Population
194
+
195
+ When PUT creates a new record, ownership fields are auto-set from context:
196
+
197
+ ```typescript
198
+ // Client sends: PUT /ats-imports/ext-123 { candidateName: "Jane Doe" }
199
+ // Server creates:
200
+ {
201
+ id: "ext-123", // Client-provided
202
+ candidateName: "Jane Doe", // Client-provided
203
+ organizationId: ctx.activeOrgId, // Auto-set from firewall
204
+ createdAt: now, // Auto-set
205
+ createdBy: ctx.userId, // Auto-set
206
+ modifiedAt: now, // Auto-set
207
+ modifiedBy: ctx.userId, // Auto-set
208
+ }
209
+ ```
210
+
211
+ ## Use Cases for PUT/External IDs
212
+
213
+ | Use Case | Why PUT? |
214
+ |----------|----------|
215
+ | External API sync | External system controls the ID |
216
+ | Webhook handlers | Events come with their own IDs |
217
+ | Data migration | Preserve IDs from source system |
218
+ | Idempotent updates | Safe to retry (no duplicate creates) |
219
+ | Bulk upsert | Create or update in one operation |
220
+
221
+ ## ID Generation Options
222
+
223
+ | `generateId` | PUT Available? | Notes |
224
+ |--------------|----------------|-------|
225
+ | `'uuid'` | No | Server generates UUID |
226
+ | `'cuid'` | No | Server generates CUID |
227
+ | `'nanoid'` | No | Server generates nanoid |
228
+ | `'short'` | No | Server generates 6-char alphanumeric ID (e.g. `a3F9xK`) |
229
+ | `'prefixed'` | No | Server generates prefixed ID (e.g. `room_abc123`) |
230
+ | `'serial'` | No | Database auto-increments |
231
+ | `false` | Yes (if guards: false) | Client provides ID |
232
+
233
+ ## Compile-Time Validation
234
+
235
+ The Quickback compiler validates your guards configuration and will error if:
236
+
237
+ 1. **Field in both `createable` and `protected`** - A field cannot be both client-writable on create and action-only
238
+ 2. **Field in both `updatable` and `protected`** - A field cannot be both client-writable on update and action-only
239
+ 3. **Field in both `updatable` and `immutable`** - Contradictory: immutable fields cannot be updated
240
+ 4. **Field in `protected` doesn't exist in schema** - Referenced field must exist in the table
241
+ 5. **Field in `createable`/`updatable`/`immutable` doesn't exist in schema** - All referenced fields must exist
@@ -0,0 +1,219 @@
1
+ # Definitions Overview
2
+
3
+ Before diving into specific features, let's understand how Quickback's pieces connect. This page gives you the mental model for everything that follows.
4
+
5
+ ## The Big Picture
6
+
7
+ Quickback is a **backend compiler**. You write definition files, and Quickback compiles them into a production-ready API.
8
+
9
+ 1. **You write definitions** - Table files with schema and security config using `defineTable`
10
+ 2. **Quickback compiles them** - Analyzes your definitions at build time
11
+ 3. **You get a production API** - `GET /jobs`, `POST /jobs`, `PATCH /jobs/:id`, `DELETE /jobs/:id`, batch operations, plus custom actions
12
+
13
+ ## File Structure
14
+
15
+ Your definitions live in a `quickback/features/` folder organized by feature:
16
+
17
+ ```
18
+ my-app/
19
+ ├── quickback/
20
+ │ ├── quickback.config.ts # Compiler configuration
21
+ │ └── features/
22
+ │ └── {feature-name}/
23
+ │ ├── candidates.ts # Table + config (defineTable)
24
+ │ ├── applications.ts # Secondary table + config
25
+ │ ├── interview-scores.ts # Internal table (no routes)
26
+ │ ├── actions.ts # Custom actions (optional)
27
+ │ └── handlers/ # Action handlers (optional)
28
+ │ └── advance-stage.ts
29
+ ├── src/ # Generated code (output)
30
+ └── package.json
31
+ ```
32
+
33
+ **Table files** use `defineTable` to combine schema and security config:
34
+
35
+ ```typescript
36
+ // features/candidates/candidates.ts
37
+ import { sqliteTable, text } from "drizzle-orm/sqlite-core";
38
+ import { defineTable } from "@quickback/compiler";
39
+
40
+ export const candidates = sqliteTable("candidates", {
41
+ id: text("id").primaryKey(),
42
+ organizationId: text("organization_id").notNull(),
43
+ name: text("name").notNull(),
44
+ email: text("email").notNull(),
45
+ phone: text("phone"),
46
+ source: text("source"),
47
+ });
48
+
49
+ export default defineTable(candidates, {
50
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
51
+ guards: {
52
+ createable: ["name", "email", "phone", "source"],
53
+ updatable: ["name", "phone"],
54
+ },
55
+ masking: {
56
+ email: { type: 'email', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
57
+ phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
58
+ },
59
+ read: {
60
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
61
+ },
62
+ crud: {
63
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
64
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
65
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
66
+ },
67
+ });
68
+
69
+ export type Candidate = typeof candidates.$inferSelect;
70
+ ```
71
+
72
+ **Key points:**
73
+ - Tables with `export default defineTable(...)` → CRUD routes generated
74
+ - Tables without default export → internal/junction tables (no routes)
75
+ - Route path derived from filename: `applications.ts` → `/api/v1/applications`
76
+
77
+ > **1 Resource = 1 Security Boundary**
78
+ >
79
+ > Each `defineTable()` defines its own complete security boundary — its own firewall (who sees the data), access rules (role requirements), guards (field validation), and masking (redaction). These are compiled into a single resource file that wraps all CRUD routes for that table.
80
+ >
81
+ > A table **without** `defineTable()` is a supporting table — used internally by actions or handlers, but never exposed as its own API endpoint. See [Internal Tables](/compiler/definitions/schema#internal-tables-no-routes) for details.
82
+
83
+
84
+ ## The Four Security Layers
85
+
86
+ Every API request passes through four security layers, in order:
87
+
88
+ ```
89
+ Request → Firewall → Access → Guards → Masking → Response
90
+ │ │ │ │
91
+ │ │ │ └── Hide sensitive fields
92
+ │ │ └── Block field modifications
93
+ │ └── Check roles & conditions
94
+ └── Isolate data by owner/org/team
95
+ ```
96
+
97
+ > **Security Applies Everywhere**
98
+ >
99
+ > These security layers protect both **API responses** and **Realtime broadcasts**. When you enable [Realtime](/stack/realtime/durable-objects), the same masking rules apply to WebSocket messages - ensuring users only see data they're authorized to view.
100
+
101
+
102
+ ### 1. Firewall (Data Isolation)
103
+
104
+ The firewall controls **which records** a user can see. It automatically adds WHERE clauses to every query based on your schema columns:
105
+
106
+ | Column in Schema | What happens |
107
+ |------------------|--------------|
108
+ | `organization_id` | Data isolated by organization |
109
+ | `user_id` | Data isolated by user (personal data) |
110
+
111
+ No manual configuration needed - Quickback applies smart rules based on your schema.
112
+
113
+ [Learn more about Firewall →](/compiler/definitions/firewall)
114
+
115
+ ### 2. Access (CRUD Permissions)
116
+
117
+ Access controls **which operations** a user can perform. It checks roles and record conditions. Reads (`GET /` and `GET /:id`) live under `read:`; writes live under `crud:`.
118
+
119
+ ```typescript
120
+ read: {
121
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
122
+ },
123
+ crud: {
124
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
125
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
126
+ delete: { access: { roles: ["owner", "hiring-manager"] } },
127
+ }
128
+ ```
129
+
130
+ [Learn more about Access →](/compiler/definitions/access)
131
+
132
+ ### 3. Guards (Field Modification Rules)
133
+
134
+ Guards control **which fields** can be modified in each operation.
135
+
136
+ | Guard Type | What it means |
137
+ |------------|---------------|
138
+ | `createable` | Fields that can be set when creating |
139
+ | `updatable` | Fields that can be changed when updating |
140
+ | `protected` | Fields that can only be changed via specific actions |
141
+ | `immutable` | Fields that can never be changed after creation |
142
+
143
+ [Learn more about Guards →](/compiler/definitions/guards)
144
+
145
+ ### 4. Masking (Data Redaction)
146
+
147
+ Masking hides sensitive fields from users who shouldn't see them.
148
+
149
+ ```typescript
150
+ masking: {
151
+ email: { type: 'email' }, // Shows: j***@e******.com
152
+ phone: { type: 'phone' }, // Shows: ******4567
153
+ salary: { type: 'redact' }, // Shows: [REDACTED]
154
+ }
155
+ ```
156
+
157
+ [Learn more about Masking →](/compiler/definitions/masking)
158
+
159
+ ## How They Work Together
160
+
161
+ **Scenario:** An interviewer requests `GET /candidates/cnd_123`
162
+
163
+ 1. **Firewall** checks: Is candidate `cnd_123` in the user's organization?
164
+ - Yes → Continue
165
+ - No → 404 Not Found (as if it doesn't exist)
166
+
167
+ 2. **Access** checks: Can interviewers perform GET?
168
+ - Yes → Continue
169
+ - No → 403 Forbidden
170
+
171
+ 3. **Guards** don't apply to GET (they're for writes)
172
+
173
+ 4. **Masking** applies: User is an `interviewer`, not `recruiter` or `hiring-manager`
174
+ - Email: `jane@company.com` → `j***@c******.com`
175
+ - Phone: `555-123-4567` → `******4567`
176
+
177
+ 5. **Response** sent with masked data
178
+
179
+ ## Locked Down by Default
180
+
181
+ Quickback is **secure by default**. Nothing is accessible until you explicitly allow it.
182
+
183
+ | Layer | Default | What you must do |
184
+ |-------|---------|------------------|
185
+ | Firewall | AUTO | Auto-detects from `organization_id`/`user_id` columns. Only configure for exceptions. |
186
+ | Access | DENIED | Explicitly define `access` rules with roles |
187
+ | Guards | LOCKED | Explicitly list `createable`, `updatable` fields |
188
+ | Actions | BLOCKED | Explicitly define `access` for each action |
189
+
190
+ **You must deliberately open each door.** This prevents accidental data exposure.
191
+
192
+ ## Other Resource Options
193
+
194
+ Beyond the four security layers, `defineTable` accepts a handful of declarative hints that shape the generated API and the CMS without touching your security posture.
195
+
196
+ | Option | What it does | Full reference |
197
+ |---|---|---|
198
+ | `views` | Named column projections — `GET /resource/views/{name}` returns a subset of columns under its own access rule. | [Views](/compiler/definitions/views) |
199
+ | `references` | Explicit FK target table for columns that don't follow the "Id"-stripped convention (e.g. `vendorId → contact`). | [CMS Schema Registry](/stack/cms/schema-registry) |
200
+ | `displayColumn` | Column to use as the human-readable label in FK resolutions and CMS list views (auto-detected as `name`/`title`/`label` if not set). | [CMS Table Views](/stack/cms/table-views) |
201
+ | `defaultSort` | Default sort order for CMS list rendering (`{ field, order: "asc" \| "desc" }`). | [CMS Table Views](/stack/cms/table-views) |
202
+ | `inputHints` | Per-column CMS input type: `select`, `richtext`, `textarea`, `lookup`, `currency`, etc. Pure CMS hint, no runtime effect. | [CMS Record Layouts](/stack/cms/record-layouts) |
203
+ | `layouts` | Named record-page layouts — group fields into sections (collapsed, multi-column). Falls back to auto-grouping if unset. | [CMS Record Layouts](/stack/cms/record-layouts) |
204
+ | `embeddings` | Auto-generate vector embeddings for specified fields on insert/update. | [Stack → Embeddings](/stack/vector/using-embeddings) |
205
+ | `realtime` | Per-table broadcast config (`enabled`, `onInsert`, `onUpdate`, `onDelete`, `requiredRoles`, `fields`). | [Stack → Realtime](/stack/realtime/using-realtime) |
206
+ | `path` | Override the route base path (defaults to feature name). | — |
207
+
208
+ All options are optional — omit them and Quickback uses sensible defaults (auto-detected display column, auto-grouped layout, no embeddings, no realtime).
209
+
210
+ ## Next Steps
211
+
212
+ 1. [Database Schema](/compiler/definitions/schema) — Define your tables
213
+ 2. [Firewall](/compiler/definitions/firewall) — Set up data isolation
214
+ 3. [Access](/compiler/definitions/access) — Configure CRUD permissions
215
+ 4. [Guards](/compiler/definitions/guards) — Control field modifications
216
+ 5. [Masking](/compiler/definitions/masking) — Hide sensitive data
217
+ 6. [Views](/compiler/definitions/views) — Column-level security
218
+ 7. [Validation](/compiler/definitions/validation) — Field validation rules
219
+ 8. [Actions](/compiler/definitions/actions) — Add custom business logic