@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,199 @@
1
+ # Connecting
2
+
3
+ The CMS supports two modes: **demo mode** for development and testing, and **live mode** for connecting to a real Quickback API.
4
+
5
+ ## Demo Mode
6
+
7
+ When no `VITE_QUICKBACK_API_URL` is set, the CMS runs in demo mode:
8
+
9
+ - Uses a **mock API client** backed by `localStorage`
10
+ - Loads seed data from JSON files in `data/mock/`
11
+ - Provides a **role switcher** in the header to test owner/admin/member access
12
+ - Simulates authentication sessions without a real backend
13
+
14
+ Demo mode is useful for prototyping your schema, testing guard behavior across roles, and verifying masking rules before deploying.
15
+
16
+ ```bash title=".env.development"
17
+ # No VITE_QUICKBACK_API_URL — CMS runs in demo mode
18
+ ```
19
+
20
+ ### Mock Data
21
+
22
+ Place JSON files in `data/mock/` matching your table names:
23
+
24
+ ```
25
+ data/mock/
26
+ contact.json # Array of contact records
27
+ project.json # Array of project records
28
+ invoice.json # Array of invoice records
29
+ _meta.json # Mock session and org metadata
30
+ ```
31
+
32
+ Each file contains an array of records. The mock client loads them on startup and persists changes to `localStorage`.
33
+
34
+ ### Role Switcher
35
+
36
+ In demo mode, the header displays a role switcher dropdown allowing you to switch between `owner`, `admin`, and `member` roles in real time. This lets you verify:
37
+
38
+ - Which CRUD buttons appear per role
39
+ - Which form fields are editable
40
+ - Which masking rules apply
41
+ - Which actions are available
42
+ - Which views are accessible
43
+
44
+ ## Live Mode
45
+
46
+ Set `VITE_QUICKBACK_API_URL` to connect to a real Quickback API:
47
+
48
+ ```bash title=".env.production"
49
+ VITE_QUICKBACK_API_URL=https://api.example.com
50
+ ```
51
+
52
+ In live mode, the CMS:
53
+
54
+ - Reads the **Better Auth session** from cookies
55
+ - Fetches the user's **organization membership** and role
56
+ - Makes real API calls to the Quickback backend for all CRUD operations
57
+ - Applies server-side security (firewall, guards, masking) in addition to client-side UI filtering
58
+
59
+ ## API Client Interface
60
+
61
+ The CMS communicates with the backend through a standard interface:
62
+
63
+ ```typescript
64
+ interface IApiClient {
65
+ list(table: string, params?: ListParams): Promise<ListResult>;
66
+ get(table: string, id: string): Promise<Record | null>;
67
+ create(table: string, data: Record): Promise<Record>;
68
+ update(table: string, id: string, data: Partial<Record>): Promise<Record>;
69
+ delete(table: string, id: string): Promise<void>;
70
+ executeAction(
71
+ table: string,
72
+ actionName: string,
73
+ recordId: string | null,
74
+ input: Record
75
+ ): Promise<Record>;
76
+ listView(
77
+ table: string,
78
+ viewName: string,
79
+ params?: ListParams
80
+ ): Promise<ListResult>;
81
+ }
82
+ ```
83
+
84
+ ### List Parameters
85
+
86
+ ```typescript
87
+ interface ListParams {
88
+ page?: number;
89
+ pageSize?: number;
90
+ sort?: string;
91
+ order?: "asc" | "desc";
92
+ search?: string;
93
+ filters?: Record<string, unknown>;
94
+ }
95
+ ```
96
+
97
+ ### List Result
98
+
99
+ ```typescript
100
+ interface ListResult {
101
+ data: Record[];
102
+ total: number;
103
+ page: number;
104
+ pageSize: number;
105
+ }
106
+ ```
107
+
108
+ Both the mock client and the live client implement this same interface. The CMS code is identical in both modes — only the underlying transport changes.
109
+
110
+ > **Server-Side Security**
111
+ >
112
+ > In live mode, all four Quickback security layers (firewall, CRUD access, guards, masking) are enforced server-side. The CMS hides unauthorized UI elements as a convenience, but the API rejects unauthorized requests regardless.
113
+
114
+
115
+ ## How the Client is Created
116
+
117
+ The CMS auto-creates the API client based on configuration:
118
+
119
+ 1. **No `VITE_QUICKBACK_API_URL`** — Instantiates the mock client, loads seed data from `data/mock/`, and uses `localStorage` for persistence.
120
+ 2. **`VITE_QUICKBACK_API_URL` is set** — Instantiates the live client, reads the auth session cookie, and makes fetch requests to the Quickback API using the standard REST endpoints (`/api/v1/{table}`).
121
+
122
+ The client is provided via React context (`ApiClientContext`) and available throughout the component tree.
123
+
124
+ ## Embedded Mode (Recommended)
125
+
126
+ Set `cms: true` in your config to embed the CMS directly in your compiled Worker:
127
+
128
+ ```typescript title="quickback/quickback.config.ts"
129
+ export default defineConfig({
130
+ name: "my-app",
131
+ cms: true,
132
+ // ...providers
133
+ });
134
+ ```
135
+
136
+ When you run `quickback compile`, the CLI:
137
+ 1. Builds the CMS SPA from source and places assets in `src/apps/cms/`
138
+ 2. Adds `[assets]` config to `wrangler.toml` with `run_worker_first = true`
139
+ 3. Generates Worker routing to serve the CMS SPA
140
+
141
+ Run `wrangler dev` and the CMS is served at `/cms/`. API routes (`/api/*`, `/auth/*`, etc.) pass through to your Hono app. Same origin — no CORS, auth cookies work naturally. On a custom domain, the CMS is served at root (`/`).
142
+
143
+ ### Custom CMS Domain
144
+
145
+ Optionally serve the CMS on a separate subdomain:
146
+
147
+ ```typescript
148
+ cms: { domain: "cms.example.com" }
149
+ ```
150
+
151
+ This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `cms.example.com` point to the same Worker. The compiler auto-configures hostname-based routing and cross-subdomain cookies.
152
+
153
+ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the Better Auth platform-admin tier) can reach `/cms/*`. Non-admin authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
154
+
155
+ - **Account UI** hides the "Go to CMS" button for non-admins.
156
+ - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-admin. A non-admin who types the CMS URL directly cannot load the app.
157
+ - **`/api/v1/schema`** returns `403 Admin access required` to non-admin callers, so schema metadata can't be scraped by hitting the API directly.
158
+ - **`custom_view` CRUD** is gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
159
+ - **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
160
+
161
+ Your resource CRUD endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `crud.access.roles` you defined.
162
+
163
+ To allow any authenticated user to access the CMS, opt out explicitly:
164
+
165
+ ```typescript
166
+ cms: { access: "user" }
167
+ ```
168
+
169
+ See [Multi-Domain Architecture](/compiler/config/domains) for details on multi-domain routing.
170
+
171
+ ## Multi-Tenant vs Single-Tenant
172
+
173
+ The CMS supports two authentication modes depending on your project's organization configuration.
174
+
175
+ ### Multi-Tenant (Default)
176
+
177
+ In multi-tenant mode, the CMS gates access behind organization membership:
178
+
179
+ 1. User logs in via Better Auth session
180
+ 2. CMS fetches the user's organization memberships
181
+ 3. If the user belongs to multiple organizations, an **org selector** is displayed
182
+ 4. Once an org is selected, the user's role within that org determines their CMS permissions
183
+
184
+ This is the default behavior for all Quickback projects.
185
+
186
+ ### Single-Tenant Mode
187
+
188
+ When your project disables organizations (`features.organizations: false` in config), the compiler sets `singleTenant: true` in the schema registry. In this mode:
189
+
190
+ - No org gate or org selector is shown
191
+ - The user's role is read directly from `user.role` on the session
192
+ - All data is unscoped (no `organizationId` filtering)
193
+
194
+ Single-tenant mode is useful for internal tools, personal projects, or apps that don't need multi-org isolation.
195
+
196
+ ## Next Steps
197
+
198
+ - **[Table Views](/stack/cms/table-views)** — Browse and Data Table view modes
199
+ - **[Security](/stack/cms/security)** — How roles, guards, and masking work in the CMS
@@ -0,0 +1,39 @@
1
+ # Dashboard
2
+
3
+ The CMS dashboard is the home page you see when opening the admin interface. It provides an at-a-glance overview of your entire schema and quick navigation to any table.
4
+
5
+ ## Stats Grid
6
+
7
+ The top of the dashboard displays aggregate statistics across your entire schema:
8
+
9
+ | Stat | Description |
10
+ |------|-------------|
11
+ | **Tables** | Total non-internal tables (excludes join tables and system tables) |
12
+ | **Columns** | Total columns across all tables |
13
+ | **Actions** | Total custom actions across all tables |
14
+ | **Views** | Total named views across all tables |
15
+ | **Masked Fields** | Total fields with masking rules |
16
+
17
+ ## Feature Cards
18
+
19
+ Below the stats grid, the dashboard displays a card for each feature group. Each card lists the feature's tables with metadata:
20
+
21
+ - **Column count** — number of columns in the table
22
+ - **Action count** — number of custom actions (shown with a lightning icon)
23
+ - **View count** — number of named views (shown with an eye icon)
24
+ - **Mask count** — number of masked fields (shown with a shield icon)
25
+
26
+ Clicking a table name navigates directly to that table's browse view.
27
+
28
+ ## Role Context
29
+
30
+ The dashboard shows the current user's role. In demo mode, this reflects the role selected in the role switcher. In live mode, it shows the role from the authenticated session.
31
+
32
+ ## Internal Tables
33
+
34
+ Tables marked as `internal: true` in the schema registry (those without a `defineTable()` resource config) are excluded from the dashboard. These are typically join tables or system tables that don't need direct admin access.
35
+
36
+ ## Next Steps
37
+
38
+ - **[Table Views](/stack/cms/table-views)** — Browse and Data Table view modes
39
+ - **[Custom Pages](/stack/cms/pages)** — Multi-panel pages with matching and drag-drop
@@ -0,0 +1,158 @@
1
+ # Quickback CMS
2
+
3
+ > **Early Access**
4
+ >
5
+ > The Quickback CMS is in early access. It works with any Quickback-compiled API that outputs a schema registry. Expect active development and potential changes.
6
+
7
+
8
+ # Quickback CMS
9
+
10
+ A schema-driven admin interface that reads `schema-registry.json` generated by the Quickback compiler. Every table, column, action, view, and security rule is rendered automatically. Zero UI code per table.
11
+
12
+ ## Overview
13
+
14
+ The CMS generates its entire UI from your Quickback definitions. Define a table with columns, guards, masking, views, and actions in your feature files. Run the compiler. The CMS reads the resulting schema registry and renders a complete admin interface — data tables, inline editing, action dialogs, role-based access, and field masking — all without writing a single line of UI code.
15
+
16
+ ## Key Features
17
+
18
+ - **Schema-driven** — Zero UI code per table. Add a table, recompile, and it appears in the CMS.
19
+ - **Dashboard** — Stats grid and feature cards showing tables, columns, actions, views, and masked fields at a glance.
20
+ - **Custom pages** — Split-panel layouts with drag-and-drop, matching engine, and page-level actions for workflows like reconciliation.
21
+ - **Embedded in your Worker** — Set `cms: true` in config. The CMS is served as static assets from the same Cloudflare Worker as your API — same origin, no CORS, auth cookies work naturally.
22
+ - **Dual view modes** — Table browse mode for navigation and Data Table mode for spreadsheet-style editing.
23
+ - **Role-based access** — Owner, admin, and member roles with live switching. CRUD buttons hidden when unauthorized.
24
+ - **Multi-tenant & single-tenant** — Org-scoped access by default, with single-tenant mode for simpler projects.
25
+ - **Inline spreadsheet editing** — Excel/Google Sheets-like editing with keyboard navigation (arrows, Tab, Enter, Escape).
26
+ - **FK typeahead** — Server-side search for foreign key fields with debounced queries and keyboard navigation.
27
+ - **Field masking** — Email, phone, SSN, and redaction patterns applied per role. Masked fields show a lock icon.
28
+ - **Custom actions** — Action dialogs with auto-generated input forms, access filtering, CMS metadata (icons, categories, confirmations), and side effects warnings.
29
+ - **Views** — Named column-level projections per role. "All Fields" plus custom views in the toolbar.
30
+ - **Auto-form generation** — Create and edit forms built from guards (createable/updatable fields).
31
+ - **Display column auto-detection** — FK labels resolved automatically from `name`, `title`, `label`, `code`, and other common patterns.
32
+
33
+ ## Architecture
34
+
35
+ The CMS sits at the end of the Quickback compilation pipeline:
36
+
37
+ ```
38
+ Quickback Definitions (feature files)
39
+ |
40
+ v
41
+ Compiler
42
+ |
43
+ v
44
+ schema-registry.json
45
+ |
46
+ v
47
+ CMS reads it
48
+ |
49
+ v
50
+ Renders admin UI
51
+ ```
52
+
53
+ Your feature definitions are the single source of truth. The compiler extracts all metadata — columns, types, guards, masking rules, views, actions, validation, and firewall config — into a static JSON file. The CMS consumes that file and renders the appropriate UI for each table.
54
+
55
+ ### How Embedded Serving Works
56
+
57
+ When `cms: true` is set, the compiler builds the CMS SPA from source at compile time (with your project-specific env vars baked in) and outputs the assets to `src/apps/cms/`. It also configures `wrangler.toml`:
58
+
59
+ ```toml
60
+ [assets]
61
+ binding = "ASSETS"
62
+ directory = "src/apps"
63
+ not_found_handling = "none"
64
+ run_worker_first = true
65
+ ```
66
+
67
+ All requests go through the Worker first. The Worker handles SPA routing — serving CMS at `/cms/` on the unified domain and at root (`/`) on a custom CMS domain. API paths (`/api/*`, `/auth/*`, etc.) are handled by Hono as normal.
68
+
69
+ See [Multi-Domain Architecture](/compiler/config/domains) for details on hostname-based routing.
70
+
71
+ > **Zero UI Code**
72
+ >
73
+ > The CMS generates its entire UI from your Quickback definitions. Add a table, recompile, and it appears in the CMS. No UI code to write.
74
+
75
+
76
+ ## Quick Start
77
+
78
+ ### 1. Enable CMS in config
79
+
80
+ ```typescript title="quickback/quickback.config.ts"
81
+ export default defineConfig({
82
+ name: "my-app",
83
+ cms: true,
84
+ // ...providers
85
+ });
86
+ ```
87
+
88
+ ### 2. Compile
89
+
90
+ ```bash
91
+ quickback compile
92
+ ```
93
+
94
+ The compiler generates `schema-registry.json` and copies CMS static assets to `src/apps/`. It also adds an `[assets]` section to `wrangler.toml` so Cloudflare serves the CMS SPA automatically.
95
+
96
+ ### 3. Run
97
+
98
+ ```bash
99
+ npm run dev
100
+ ```
101
+
102
+ Open your Worker URL in a browser — the CMS is served at the root. API routes (`/api/*`, `/auth/*`, etc.) pass through to your Hono app as normal. Everything runs on the same origin — no CORS configuration needed, auth cookies work naturally.
103
+
104
+ ### Optional: Custom CMS domain
105
+
106
+ ```typescript
107
+ cms: { domain: "cms.example.com" }
108
+ ```
109
+
110
+ This adds a custom domain route to `wrangler.toml`. Both domains serve the same Worker — `api.example.com` for the API, `cms.example.com` for the CMS. The compiler also auto-infers a unified `quickback.example.com` domain where everything is available. See [Multi-Domain Architecture](/compiler/config/domains).
111
+
112
+ ### Access gate (admin-only by default)
113
+
114
+ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the user-table role from Better Auth's admin plugin) can reach `/cms/*`. Non-admin authenticated users are redirected to `/account/profile`. The gate is enforced at **four layers** — defense in depth:
115
+
116
+ 1. **Account UI link** — the "Go to CMS" button is hidden for non-admins.
117
+ 2. **CMS SPA shell** — the Worker returns `403 Admin access required` before serving `index.html` to a non-admin. Unauthenticated requests are redirected to the login page.
118
+ 3. **`/api/v1/schema`** — the CMS metadata endpoint checks `ctx.userRole === "admin"` and returns `403` otherwise.
119
+ 4. **`custom_view` CRUD** — the CMS-internal saved-views table is gated on `userRole: ["admin"]` (see the [`userRole` access primitive](/compiler/definitions/access#userrole)) rather than org membership.
120
+
121
+ Your resource CRUD endpoints (`/api/v1/<resource>`) are **not** affected — they continue to use the per-resource `crud.access.roles` you defined.
122
+
123
+ To allow any authenticated user, opt out explicitly:
124
+
125
+ ```typescript
126
+ cms: { access: "user" }
127
+ ```
128
+
129
+ ### Optional: Skip SPA rebuild
130
+
131
+ After the first compile, you can skip rebuilding the CMS SPA on subsequent compiles:
132
+
133
+ ```typescript
134
+ cms: { build: false }
135
+ ```
136
+
137
+ This is useful when you're iterating on API features and don't need to rebuild the CMS UI each time — it saves significant compile time. Set `build: true` (or omit it) when you need to update the CMS assets.
138
+
139
+ ### Optional: Custom output directory
140
+
141
+ ```typescript
142
+ cms: { outputDir: "my-custom-path/cms" }
143
+ ```
144
+
145
+ This changes where the compiled CMS assets are placed (relative to project root), instead of the default `src/apps/cms/`.
146
+
147
+ ## Next Steps
148
+
149
+ - **[Schema Registry](/stack/cms/schema-registry)** — Understand the JSON format the compiler generates
150
+ - **[Connecting](/stack/cms/connecting)** — Demo mode, live mode, CLI command, and auth modes
151
+ - **[Dashboard](/stack/cms/dashboard)** — Stats grid and feature navigation
152
+ - **[Table Views](/stack/cms/table-views)** — Browse and Data Table view modes
153
+ - **[Custom Pages](/stack/cms/pages)** — Split-panel layouts, matching engine, and drag-drop
154
+ - **[Inline Editing](/stack/cms/inline-editing)** — Spreadsheet-style editing and FK typeahead
155
+ - **[Security](/stack/cms/security)** — How the CMS enforces all four security layers
156
+ - **[Actions](/stack/cms/actions)** — Custom actions with input forms, access filtering, and CMS metadata
157
+ - **[Schema Format Reference](/stack/cms/schema-format)** — Full TypeScript types for schema-registry.json
158
+ - **[Components Reference](/stack/cms/components)** — All CMS components and their props
@@ -0,0 +1,136 @@
1
+ # Inline Editing
2
+
3
+ The CMS provides spreadsheet-style inline editing in Data Table mode, plus auto-generated create and edit forms in the record detail view. All editable fields are determined from your table's guard configuration.
4
+
5
+ ## Spreadsheet Editing
6
+
7
+ In Data Table mode, every editable cell becomes an inline editor. Select a cell, start typing, and the value is saved automatically when you move to another cell or press Enter.
8
+
9
+ ### Editable Fields
10
+
11
+ The CMS determines which fields are editable from the table's guards:
12
+
13
+ - **`guards.updatable`** fields are editable in existing records
14
+ - **`guards.createable`** fields are editable in new record forms
15
+ - **`guards.immutable`** fields are locked after creation (shown as disabled in edit mode)
16
+ - **`guards.protected`** fields can only be changed via actions (marked "Updated via actions only")
17
+
18
+ If a table has no explicit guard config, the CMS falls back to making all non-system columns editable (excluding `id`, audit fields, `organizationId`, and `deletedAt`).
19
+
20
+ ## Cell Types
21
+
22
+ Each column type gets a specialized editor:
23
+
24
+ ### Text
25
+
26
+ Standard text input. Type freely and press Enter or Tab to save.
27
+
28
+ ### Number
29
+
30
+ Numeric input with step controls. Supports decimal values (step `0.01` for currency fields). The CMS detects money fields from column names containing `amount`, `total`, `price`, `cost`, `balance`, `rate`, etc.
31
+
32
+ ### Boolean
33
+
34
+ A Yes/No dropdown. Click to toggle between the two values.
35
+
36
+ ### FK Typeahead
37
+
38
+ Foreign key columns (ending in `Id`) get a typeahead dropdown with server-side search:
39
+
40
+ - **Debounced search** — Queries are debounced at 200ms to avoid flooding the API
41
+ - **Server-side filtering** — Sends `?search=query&pageSize=20` to the FK target table's list endpoint
42
+ - **Keyboard navigation** — Arrow keys to navigate options, Enter to select, Escape to close
43
+ - **Auto-loads initial options** — Opens with the first 20 records sorted by display column
44
+ - **Display labels** — Shows the target table's display column value (e.g., "John Smith" instead of `usr_abc123`)
45
+
46
+ The FK target table is derived by stripping the `Id` suffix from the column name. For example, `contactId` searches the `contact` table, and `accountCodeId` searches the `accountCode` table.
47
+
48
+ ### Enum / Select
49
+
50
+ Columns with `validation.enum` render as a select dropdown with all allowed values.
51
+
52
+ ## Display Labels
53
+
54
+ FK cells in the table view show human-readable names instead of raw IDs. The API enriches list responses with `_label` fields:
55
+
56
+ ```
57
+ contactId: "cnt_abc123" → displays "Acme Corporation"
58
+ projectId: "prj_xyz789" → displays "Beach House Renovation"
59
+ ```
60
+
61
+ The label comes from the referenced table's display column (auto-detected from `name`, `title`, `code`, etc.). This works in both Table mode and Data Table mode.
62
+
63
+ ## Keyboard Shortcuts
64
+
65
+ | Shortcut | Action |
66
+ |----------|--------|
67
+ | Arrow keys | Navigate between cells |
68
+ | Tab | Move to next editable cell |
69
+ | Shift + Tab | Move to previous editable cell |
70
+ | Enter | Start editing / confirm edit and move down |
71
+ | Escape | Cancel current edit / deselect cell |
72
+ | Type any character | Start editing the selected cell |
73
+
74
+ ### Navigation Flow
75
+
76
+ 1. **Select** a cell by clicking or using arrow keys
77
+ 2. **Edit** by pressing Enter, Tab, or just typing
78
+ 3. **Save** by pressing Enter (moves down), Tab (moves right to next editable), or clicking elsewhere
79
+ 4. **Cancel** by pressing Escape (reverts to previous value)
80
+
81
+ When you press Tab, the cursor skips non-editable cells and jumps to the next editable cell in the row. At the end of a row, it wraps to the first editable cell of the next row.
82
+
83
+ ## Record Detail View
84
+
85
+ Clicking a row in Table mode navigates to the record detail view. Fields are automatically grouped by type:
86
+
87
+ | Group | Fields Included |
88
+ |-------|----------------|
89
+ | Identity | `name`, `code`, `status`, `title`, `companyName`, fields ending in `Type` or `Status` |
90
+ | Contact Info | `email`, `phone`, `mobile`, `website`, `address1`, `address2`, `city`, `state`, `zip`, `country` |
91
+ | Financial | Money fields, fields with `Percent`, `Rate`, `Markup`, `Discount`, `Currency`, `exchange` |
92
+ | References | All FK columns (ending in `Id`, excluding `id` and `organizationId`) |
93
+ | Settings | Boolean fields |
94
+ | Dates | Date/time fields |
95
+ | Audit | `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy` |
96
+ | Other | Remaining ungrouped fields |
97
+
98
+ Each group is rendered as a card with the group label as a header. Fields display formatted values — dates are localized, money shows currency formatting, booleans render as Yes/No badges, enums use color-coded pills, and FK references are clickable links to the target record.
99
+
100
+ ## Auto-Generated Forms
101
+
102
+ The CMS generates create and edit forms from the table's guard configuration:
103
+
104
+ ### Create Form
105
+
106
+ Shows all fields listed in `guards.createable`. Required fields (notNull without a default) are marked with a red asterisk. Validation rules from the schema (min/max length, enum constraints, email format) are enforced client-side.
107
+
108
+ ### Edit Form
109
+
110
+ Shows all fields listed in `guards.updatable`. Additionally:
111
+
112
+ - **Immutable fields** appear as disabled inputs with a lock icon
113
+ - **Protected fields** appear as disabled inputs with the note "Updated via actions only"
114
+ - **Validation** is applied on submit, with error messages shown per field
115
+
116
+ ### Field Input Types
117
+
118
+ The auto-form selects the appropriate input control based on column type and validation:
119
+
120
+ | Detection | Input Type |
121
+ |-----------|-----------|
122
+ | `mode: "boolean"` | Checkbox |
123
+ | `validation.enum` present | Select dropdown |
124
+ | Column name matches date pattern | Date/time picker |
125
+ | Column name matches money pattern | Number input (step 0.01) |
126
+ | Column name matches URL pattern | URL input |
127
+ | `validation.email: true` | Email input |
128
+ | `type: "integer"` or `type: "real"` | Number input |
129
+ | Long text (description, notes) | Textarea |
130
+ | Default | Text input |
131
+
132
+ ## Next Steps
133
+
134
+ - **[Table Views](/stack/cms/table-views)** — Browse mode and view projections
135
+ - **[Security](/stack/cms/security)** — How guards control editability
136
+ - **[Actions](/stack/cms/actions)** — Trigger actions from the detail view