@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,431 @@
1
+ # Complete Example
2
+
3
+ This example shows a complete resource definition using all five security layers, and the production code Quickback generates from it.
4
+
5
+ ## What You Define
6
+
7
+ A `candidates` resource for a multi-tenant recruitment application with:
8
+ - Organization-level data isolation
9
+ - Role-based CRUD permissions
10
+ - Field-level write protection
11
+ - PII masking for sensitive fields
12
+ - Column-level views for different access levels
13
+
14
+ ```typescript title="quickback/features/candidates/candidates.ts"
15
+ import { feature, q } from '@quickback/compiler';
16
+
17
+ export default feature('candidates', {
18
+ columns: {
19
+ id: q.id(),
20
+ name: q.text().required(),
21
+ email: q.text().required(),
22
+ phone: q.text().optional(),
23
+ resumeUrl: q.text().optional(),
24
+ source: q.text().optional(), // e.g. "linkedin", "referral", "careers-page"
25
+ internalNotes: q.text().optional(),
26
+ organizationId: q.scope("organization"),
27
+ // Note: createdAt, createdBy, modifiedAt, modifiedBy are auto-injected
28
+ },
29
+
30
+ // firewall — auto-derived from q.scope("organization") + soft-delete deletedAt;
31
+ // explicit declaration is optional once a scope column is declared.
32
+
33
+ // GUARDS — Field-level protection
34
+ guards: {
35
+ createable: ['name', 'email', 'phone', 'resumeUrl', 'source'],
36
+ updatable: ['name', 'phone'],
37
+ },
38
+
39
+ // MASKING — PII redaction (query.roles defaults to show.roles)
40
+ masking: {
41
+ email: { type: 'email', show: { roles: ['hiring-manager', 'recruiter'] } },
42
+ phone: { type: 'phone', show: { roles: ['hiring-manager', 'recruiter'] } },
43
+ },
44
+
45
+ // READ — Collection + per-id GET, plus named views
46
+ read: {
47
+ access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] },
48
+ views: {
49
+ pipeline: {
50
+ fields: ['id', 'name', 'source'],
51
+ access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] },
52
+ },
53
+ full: {
54
+ fields: ['id', 'name', 'email', 'phone', 'resumeUrl', 'source', 'internalNotes'],
55
+ access: { roles: ['hiring-manager', 'recruiter'] },
56
+ },
57
+ },
58
+ },
59
+
60
+ // CRUD — Write operations
61
+ crud: {
62
+ create: { access: { roles: ['hiring-manager', 'recruiter'] } },
63
+ update: { access: { roles: ['hiring-manager', 'recruiter'] } },
64
+ delete: { access: { roles: ['hiring-manager'] }, mode: 'hard' },
65
+ },
66
+ });
67
+ ```
68
+
69
+ > Prefer the explicit two-export form (or interop with existing Drizzle schemas)? See [feature() — single-export sugar](/compiler/definitions/feature) and [Schema: choosing between `q` and Drizzle](/compiler/definitions/schema#choosing-between-q-and-drizzle). All forms compile identically; mix freely per file.
70
+
71
+ ---
72
+
73
+ ## What Quickback Generates
74
+
75
+ Run `quickback compile` and Quickback generates production-ready code.
76
+
77
+ ### Security Helpers
78
+
79
+ ```typescript title="src/features/candidates/candidates.resource.ts"
80
+ import { eq, and } from 'drizzle-orm';
81
+ import { candidates } from './schema';
82
+ import type { AppContext } from '../../lib/types';
83
+ import { masks } from '../../lib/masks';
84
+
85
+ /**
86
+ * Firewall conditions for candidates
87
+ * Auto-derived from q.scope("organization") + audit-injected deletedAt.
88
+ * 2 predicates: tenant scope AND soft-delete filter.
89
+ */
90
+ export function buildFirewallConditions(ctx: AppContext) {
91
+ return and(
92
+ eq(candidates.organizationId, ctx.activeOrgId!),
93
+ isNull(candidates.deletedAt),
94
+ );
95
+ }
96
+
97
+ /**
98
+ * Guards configuration for field modification rules.
99
+ * organizationId is added to systemManaged because q.scope("organization")
100
+ * is bound to ctx.activeOrgId — clients cannot submit it.
101
+ */
102
+ export const GUARDS_CONFIG = {
103
+ createable: new Set(['name', 'email', 'phone', 'resumeUrl', 'source']),
104
+ updatable: new Set(['name', 'phone']),
105
+ immutable: new Set([]),
106
+ protected: {},
107
+ systemManaged: new Set([
108
+ 'createdAt', 'createdBy',
109
+ 'modifiedAt', 'modifiedBy',
110
+ 'deletedAt', 'deletedBy',
111
+ 'organizationId', // ← added by q.scope("organization")
112
+ ]),
113
+ };
114
+
115
+ /**
116
+ * Validates field input for CREATE operations.
117
+ */
118
+ export function validateCreate(input: Record<string, any>) {
119
+ const systemManaged: string[] = [];
120
+ const protectedFields: Array<{ field: string; actions: string[] }> = [];
121
+ const notCreateable: string[] = [];
122
+
123
+ for (const field of Object.keys(input)) {
124
+ if (GUARDS_CONFIG.systemManaged.has(field)) {
125
+ systemManaged.push(field);
126
+ continue;
127
+ }
128
+ if (field in GUARDS_CONFIG.protected) {
129
+ const actions = [...GUARDS_CONFIG.protected[field]];
130
+ protectedFields.push({ field, actions });
131
+ continue;
132
+ }
133
+ if (!GUARDS_CONFIG.createable.has(field) && !GUARDS_CONFIG.immutable.has(field)) {
134
+ notCreateable.push(field);
135
+ }
136
+ }
137
+
138
+ const valid = systemManaged.length === 0 &&
139
+ protectedFields.length === 0 &&
140
+ notCreateable.length === 0;
141
+
142
+ return { valid, systemManaged, protected: protectedFields, notCreateable };
143
+ }
144
+
145
+ /**
146
+ * Validates field input for UPDATE operations.
147
+ */
148
+ export function validateUpdate(input: Record<string, any>) {
149
+ const systemManaged: string[] = [];
150
+ const immutable: string[] = [];
151
+ const protectedFields: Array<{ field: string; actions: string[] }> = [];
152
+ const notUpdatable: string[] = [];
153
+
154
+ for (const field of Object.keys(input)) {
155
+ if (GUARDS_CONFIG.systemManaged.has(field)) {
156
+ systemManaged.push(field);
157
+ continue;
158
+ }
159
+ if (GUARDS_CONFIG.immutable.has(field)) {
160
+ immutable.push(field);
161
+ continue;
162
+ }
163
+ if (field in GUARDS_CONFIG.protected) {
164
+ const actions = [...GUARDS_CONFIG.protected[field]];
165
+ protectedFields.push({ field, actions });
166
+ continue;
167
+ }
168
+ if (!GUARDS_CONFIG.updatable.has(field)) {
169
+ notUpdatable.push(field);
170
+ }
171
+ }
172
+
173
+ const valid = systemManaged.length === 0 &&
174
+ immutable.length === 0 &&
175
+ protectedFields.length === 0 &&
176
+ notUpdatable.length === 0;
177
+
178
+ return { valid, systemManaged, immutable, protected: protectedFields, notUpdatable };
179
+ }
180
+
181
+ /**
182
+ * Masks sensitive fields based on user role
183
+ */
184
+ export function maskCandidate<T extends Record<string, any>>(
185
+ record: T,
186
+ ctx: AppContext
187
+ ): T {
188
+ const masked: any = { ...record };
189
+
190
+ // email: show to hiring-manager, recruiter
191
+ if (!ctx.roles?.some(r => ['hiring-manager', 'recruiter'].includes(r))) {
192
+ if (masked['email'] != null) {
193
+ masked['email'] = masks.email(masked['email']);
194
+ }
195
+ }
196
+
197
+ // phone: show to hiring-manager, recruiter
198
+ if (!ctx.roles?.some(r => ['hiring-manager', 'recruiter'].includes(r))) {
199
+ if (masked['phone'] != null) {
200
+ masked['phone'] = masks.phone(masked['phone']);
201
+ }
202
+ }
203
+
204
+ return masked as T;
205
+ }
206
+
207
+ export function maskCandidates<T extends Record<string, any>>(
208
+ records: T[],
209
+ ctx: AppContext
210
+ ): T[] {
211
+ return records.map(r => maskCandidate(r, ctx));
212
+ }
213
+
214
+ // CRUD Access configuration (write operations only)
215
+ export const CRUD_ACCESS = {
216
+ create: { access: { roles: ['hiring-manager', 'recruiter'] } },
217
+ update: { access: { roles: ['hiring-manager', 'recruiter'] } },
218
+ delete: { access: { roles: ['hiring-manager'] }, mode: 'hard' },
219
+ };
220
+
221
+ // Views configuration (read pipeline)
222
+ export const VIEWS_CONFIG = {
223
+ pipeline: {
224
+ fields: ['id', 'name', 'source'],
225
+ access: { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] },
226
+ },
227
+ full: {
228
+ fields: ['id', 'name', 'email', 'phone', 'resumeUrl', 'source', 'internalNotes'],
229
+ access: { roles: ['hiring-manager', 'recruiter'] },
230
+ },
231
+ } as const;
232
+ ```
233
+
234
+ ### API Routes
235
+
236
+ The generated routes wire everything together:
237
+
238
+ ```typescript title="src/features/candidates/candidates.routes.ts"
239
+ import { Hono } from 'hono';
240
+ import { eq, and } from 'drizzle-orm';
241
+ import { candidates } from './schema';
242
+ import {
243
+ buildFirewallConditions,
244
+ validateCreate,
245
+ validateUpdate,
246
+ maskCandidate,
247
+ maskCandidates,
248
+ VIEWS_CONFIG,
249
+ CRUD_ACCESS,
250
+ } from './candidates.resource';
251
+ import { evaluateAccess } from '../../lib/access';
252
+ import { AuthErrors, AccessErrors, GuardErrors } from '../../lib/errors';
253
+
254
+ const app = new Hono();
255
+
256
+ // GET /candidates?view=<name> — unified read handler dispatched by ?view
257
+ const READ_ACCESS = { roles: ['owner', 'hiring-manager', 'recruiter', 'interviewer'] };
258
+
259
+ app.get('/', async (c) => {
260
+ const ctx = c.get('ctx');
261
+ const db = c.get('db');
262
+
263
+ const params = Object.fromEntries(new URL(c.req.url).searchParams);
264
+ const view = VIEWS_CONFIG[params.view as keyof typeof VIEWS_CONFIG];
265
+ if (!view) return c.json({ error: 'View required', code: 'VIEW_REQUIRED' }, 400);
266
+
267
+ // Per-view access gate (falls back to read-level access)
268
+ if (!await evaluateAccess(view.access ?? READ_ACCESS, ctx)) {
269
+ return c.json(AccessErrors.roleRequired(view.access?.roles ?? READ_ACCESS.roles, ctx.roles), 403);
270
+ }
271
+
272
+ // Query with firewall conditions, project view fields, mask, return.
273
+ const results = await db.select(/* projected fields */).from(candidates)
274
+ .where(buildFirewallConditions(ctx));
275
+
276
+ return c.json({ data: maskCandidates(results, ctx), view: params.view });
277
+ });
278
+
279
+ // POST /candidates - Create with guards
280
+ app.post('/', async (c) => {
281
+ const ctx = c.get('ctx');
282
+ const db = c.get('db');
283
+
284
+ // Access check
285
+ if (!await evaluateAccess(CRUD_ACCESS.create.access, ctx)) {
286
+ return c.json(AccessErrors.roleRequired(
287
+ CRUD_ACCESS.create.access.roles,
288
+ ctx.roles
289
+ ), 403);
290
+ }
291
+
292
+ const body = await c.req.json();
293
+
294
+ // Guards validation
295
+ const validation = validateCreate(body);
296
+ if (!validation.valid) {
297
+ if (validation.systemManaged.length > 0) {
298
+ return c.json(GuardErrors.systemManaged(validation.systemManaged), 400);
299
+ }
300
+ if (validation.notCreateable.length > 0) {
301
+ return c.json(GuardErrors.fieldNotCreateable(validation.notCreateable), 400);
302
+ }
303
+ }
304
+
305
+ // Apply ownership and audit fields
306
+ const data = {
307
+ id: 'cnd_' + crypto.randomUUID().replace(/-/g, ''),
308
+ ...body,
309
+ organizationId: ctx.activeOrgId,
310
+ createdAt: new Date().toISOString(),
311
+ createdBy: ctx.userId,
312
+ modifiedAt: new Date().toISOString(),
313
+ modifiedBy: ctx.userId,
314
+ };
315
+
316
+ const result = await db.insert(candidates).values(data).returning();
317
+ return c.json(maskCandidate(result[0], ctx), 201);
318
+ });
319
+
320
+ // PATCH /candidates/:id - Update with guards
321
+ app.patch('/:id', async (c) => {
322
+ const ctx = c.get('ctx');
323
+ const db = c.get('db');
324
+ const id = c.req.param('id');
325
+
326
+ // Fetch with firewall
327
+ const [record] = await db.select().from(candidates)
328
+ .where(and(buildFirewallConditions(ctx), eq(candidates.id, id)));
329
+
330
+ if (!record) {
331
+ return c.json({ error: 'Not found', code: 'NOT_FOUND' }, 404);
332
+ }
333
+
334
+ // Access check
335
+ if (!await evaluateAccess(CRUD_ACCESS.update.access, ctx)) {
336
+ return c.json(AccessErrors.roleRequired(
337
+ CRUD_ACCESS.update.access.roles,
338
+ ctx.roles
339
+ ), 403);
340
+ }
341
+
342
+ const body = await c.req.json();
343
+
344
+ // Guards validation
345
+ const validation = validateUpdate(body);
346
+ if (!validation.valid) {
347
+ if (validation.notUpdatable.length > 0) {
348
+ return c.json(GuardErrors.fieldNotUpdatable(validation.notUpdatable), 400);
349
+ }
350
+ }
351
+
352
+ // Apply audit fields
353
+ const data = {
354
+ ...body,
355
+ modifiedAt: new Date().toISOString(),
356
+ modifiedBy: ctx.userId,
357
+ };
358
+
359
+ const result = await db.update(candidates).set(data)
360
+ .where(eq(candidates.id, id)).returning();
361
+
362
+ return c.json(maskCandidate(result[0], ctx));
363
+ });
364
+
365
+ export default app;
366
+ ```
367
+
368
+ ---
369
+
370
+ ## Runtime Behavior
371
+
372
+ ### Masking by Role
373
+
374
+ | Role | `email` | `phone` |
375
+ |------|---------|---------|
376
+ | **hiring-manager** | `jane@example.com` | `555-123-4567` |
377
+ | **recruiter** | `jane@example.com` | `555-123-4567` |
378
+ | **interviewer** | `j***@e******.com` | `******4567` |
379
+
380
+ ### Views + Masking Interaction
381
+
382
+ Views control **which fields are returned**. Masking controls **what values are shown**.
383
+
384
+ | Endpoint | Role | `phone` in response? | `phone` value |
385
+ |----------|------|--------------------|-------------|
386
+ | `/candidates?view=pipeline` | interviewer | No | N/A |
387
+ | `/candidates?view=pipeline` | recruiter | No | N/A |
388
+ | `/candidates?view=full` | interviewer | No | N/A (no access) |
389
+ | `/candidates?view=full` | recruiter | Yes | `555-123-4567` |
390
+
391
+ ### Guards Enforcement
392
+
393
+ ```bash
394
+ # Allowed: Create with createable fields
395
+ POST /candidates
396
+ { "name": "Jane Smith", "email": "jane@example.com", "source": "linkedin" }
397
+
398
+ # Rejected: Update non-updatable field
399
+ PATCH /candidates/cnd_123
400
+ { "email": "new@example.com" }
401
+ # -> 400: "Field 'email' is not updatable"
402
+
403
+ # Rejected: Set system-managed field
404
+ POST /candidates
405
+ { "name": "Jane Smith", "createdBy": "hacker" }
406
+ # -> 400: "System-managed fields cannot be set: createdBy"
407
+ ```
408
+
409
+ ---
410
+
411
+ ## Generated API Endpoints
412
+
413
+ | Method | Endpoint | Access |
414
+ |--------|----------|--------|
415
+ | `GET` | `/candidates` | owner, hiring-manager, recruiter, interviewer |
416
+ | `GET` | `/candidates/:id` | owner, hiring-manager, recruiter, interviewer |
417
+ | `POST` | `/candidates` | hiring-manager, recruiter |
418
+ | `PATCH` | `/candidates/:id` | hiring-manager, recruiter |
419
+ | `DELETE` | `/candidates/:id` | hiring-manager |
420
+ | `GET` | `/candidates?view=pipeline` | owner, hiring-manager, recruiter, interviewer |
421
+ | `GET` | `/candidates?view=full` | hiring-manager, recruiter |
422
+
423
+ ---
424
+
425
+ ## Key Takeaways
426
+
427
+ 1. **~50 lines of configuration** generates **~500+ lines of production code**
428
+ 2. **Security is declarative** - you describe *what* you want, not *how*
429
+ 3. **All layers work together** - Firewall -> Access -> Guards -> Masking
430
+ 4. **Code is readable and auditable** - no magic, just TypeScript
431
+ 5. **Type-safe from definition to API** - Drizzle schema drives everything
@@ -0,0 +1,178 @@
1
+ # Hand-Crafted Setup
2
+
3
+ If you have an existing project and want to add Quickback-generated API endpoints, you can set up the definitions directory manually instead of using a template.
4
+
5
+ ## Prerequisites
6
+
7
+ - An existing Hono-based project (Cloudflare Workers or Bun)
8
+ - Node.js 18+ or Bun installed
9
+ - The Quickback CLI: `npm install -g @quickback-dev/cli`
10
+
11
+ ## Setup
12
+
13
+ ### 1. Create the Quickback Directory
14
+
15
+ Create a `quickback/` directory in your project root with the following structure:
16
+
17
+ ```
18
+ your-project/
19
+ ├── quickback/
20
+ │ ├── quickback.config.ts
21
+ │ └── features/
22
+ │ └── (your features go here)
23
+ ├── src/ # Your existing code
24
+ ├── package.json
25
+ └── ...
26
+ ```
27
+
28
+ ```bash
29
+ mkdir -p quickback/features
30
+ ```
31
+
32
+ ### 2. Write Your Config
33
+
34
+ Create `quickback/quickback.config.ts`:
35
+
36
+ ```typescript
37
+ import { defineConfig } from "@quickback/compiler";
38
+
39
+ export default defineConfig({
40
+ name: "my-app",
41
+ template: "hono",
42
+ features: ["organizations"],
43
+ providers: {
44
+ runtime: { name: "cloudflare", config: {} },
45
+ database: {
46
+ name: "cloudflare-d1",
47
+ config: { binding: "DB" },
48
+ },
49
+ auth: { name: "better-auth", config: {} },
50
+ },
51
+ });
52
+ ```
53
+
54
+ Adjust the providers to match your existing stack. See [Providers](/compiler/config/providers) for all options.
55
+
56
+ ### 3. Create Your First Feature
57
+
58
+ Create a feature directory with a schema + security definition:
59
+
60
+ ```bash
61
+ mkdir quickback/features/candidates
62
+ ```
63
+
64
+ Create `quickback/features/candidates/candidates.ts`:
65
+
66
+ ```typescript
67
+ import { sqliteTable, text } from "drizzle-orm/sqlite-core";
68
+ import { defineTable } from "@quickback/compiler";
69
+
70
+ export const candidates = sqliteTable("candidates", {
71
+ id: text("id").primaryKey(),
72
+ name: text("name").notNull(),
73
+ email: text("email").notNull(),
74
+ phone: text("phone"),
75
+ source: text("source"),
76
+ organizationId: text("organization_id").notNull(),
77
+ });
78
+
79
+ export default defineTable(candidates, {
80
+ firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
81
+ guards: {
82
+ createable: ["name", "email", "phone", "source"],
83
+ updatable: ["name", "phone"],
84
+ },
85
+ masking: {
86
+ email: { type: "email", show: { roles: ["hiring-manager", "recruiter"] } },
87
+ phone: { type: "phone", show: { roles: ["hiring-manager", "recruiter"] } },
88
+ },
89
+ read: {
90
+ access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
91
+ },
92
+ crud: {
93
+ create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
94
+ update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
95
+ delete: { access: { roles: ["owner", "hiring-manager"] }, mode: "soft" },
96
+ },
97
+ });
98
+ ```
99
+
100
+ ### 4. Log In and Compile
101
+
102
+ ```bash
103
+ quickback login
104
+ quickback compile
105
+ ```
106
+
107
+ The compiler generates a complete `src/` directory with route handlers, middleware, database schemas, and migrations.
108
+
109
+ ### 5. Integrate with Your Existing Code
110
+
111
+ The compiled output creates a self-contained Hono app in `src/index.ts`. If you need to integrate the generated routes into an existing Hono app, you can import the feature routes directly:
112
+
113
+ ```typescript
114
+ import { Hono } from "hono";
115
+ import candidatesRoutes from "./features/candidates/routes";
116
+
117
+ const app = new Hono();
118
+
119
+ // Your existing routes
120
+ app.get("/", (c) => c.json({ status: "ok" }));
121
+
122
+ // Mount generated feature routes
123
+ app.route("/api/v1/candidates", candidatesRoutes);
124
+
125
+ export default app;
126
+ ```
127
+
128
+ ## Directory Structure
129
+
130
+ The compiler expects this structure inside `quickback/`:
131
+
132
+ ```
133
+ quickback/
134
+ ├── quickback.config.ts # Required: compiler configuration
135
+ └── features/ # Required: feature definitions
136
+ ├── candidates/
137
+ │ ├── candidates.ts # Schema + security (defineTable)
138
+ │ └── actions.ts # Optional: custom actions
139
+ ├── jobs/
140
+ │ ├── jobs.ts
141
+ │ └── actions.ts
142
+ └── ...
143
+ ```
144
+
145
+ Each feature directory should contain:
146
+ - **`{name}.ts`** — The main definition file using `defineTable()` (required)
147
+ - **`actions.ts`** — Custom actions using `defineActions()` (optional)
148
+
149
+ ## Adding Features
150
+
151
+ To add a new feature, create a new directory under `quickback/features/` and recompile:
152
+
153
+ ```bash
154
+ mkdir quickback/features/jobs
155
+ # Create jobs/jobs.ts with defineTable(...)
156
+ quickback compile
157
+ ```
158
+
159
+ The compiler detects all features automatically — no registration needed.
160
+
161
+ ## Recompiling
162
+
163
+ After any change to your definitions, recompile to regenerate the output:
164
+
165
+ ```bash
166
+ quickback compile
167
+ ```
168
+
169
+ The compiler regenerates the entire `src/` directory. Your definitions in `quickback/` are the source of truth — never edit the generated files directly.
170
+
171
+ **Warning:** Don't edit files in `src/` manually. They will be overwritten on the next compile. All changes should be made in your `quickback/` definitions.
172
+
173
+ ## Next Steps
174
+
175
+ - [Configuration reference](/compiler/config) — All config options
176
+ - [Schema definitions](/compiler/definitions/schema) — Define tables with `defineTable()`
177
+ - [Security pillars](/compiler/definitions) — Firewall, Access, Guards, Masking
178
+ - [Templates](/compiler/getting-started/templates) — Use a template for new projects instead