@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,78 @@
1
+ # Endpoints
2
+
3
+ The cloud compiler API is hosted at `https://compiler.quickback.dev`.
4
+
5
+ ## Public (No Auth)
6
+
7
+ | Endpoint | Method | Description |
8
+ |----------|--------|-------------|
9
+ | `/health` | GET | Health check |
10
+ | `/templates` | GET | List available templates |
11
+
12
+ ## Authenticated
13
+
14
+ | Endpoint | Method | Description |
15
+ |----------|--------|-------------|
16
+ | `/compile` | POST | Compile definitions into backend files |
17
+
18
+ The `/compile` endpoint requires either a session token (from `quickback login`) or an API key (via `QUICKBACK_API_KEY` header). See [Authentication](/compiler/cloud-compiler/authentication) for details.
19
+
20
+ ## Environment Variables
21
+
22
+ | Variable | Description |
23
+ |----------|-------------|
24
+ | `QUICKBACK_API_KEY` | API key for authentication (alternative to `quickback login`) |
25
+ | `QUICKBACK_API_URL` | Override compiler API URL (default: `https://compiler.quickback.dev`) |
26
+
27
+ ### Custom Compiler URL
28
+
29
+ Point the CLI to a different compiler (local or custom):
30
+
31
+ ```bash
32
+ QUICKBACK_API_URL=http://localhost:3020 quickback compile
33
+ ```
34
+
35
+ See [Local Compiler](/compiler/cloud-compiler/local-compiler) for running the compiler locally with Docker.
36
+
37
+ ## Streaming Protocol (`POST /compile`)
38
+
39
+ By default `/compile` returns a single JSON response. If the request includes `Accept: text/event-stream`, the compiler upgrades to Server-Sent Events so the CLI can render progress while the build runs.
40
+
41
+ There are two stream protocol versions, negotiated via the `X-Quickback-Stream` request header:
42
+
43
+ | Header | Protocol | Behavior |
44
+ |--------|----------|----------|
45
+ | _(absent)_ | **v1** | Sends `progress` events during the build, then a single `result` event with the entire compilation payload (config, generated files, drizzle output, SPA bundles, etc.) JSON-encoded as one frame. |
46
+ | `X-Quickback-Stream: v2` | **v2 (chunked)** | Sends `progress` events during the build, then a `meta` event with the file count, then one `file` event per generated file, then a final `done` event with metadata, commands, and warnings. |
47
+
48
+ The server echoes the chosen version back as the response `X-Quickback-Stream` header so the CLI knows which framing to parse.
49
+
50
+ ### Why v2
51
+
52
+ Multi-megabyte SPA bundles (CMS + Account, with sourcemaps) take long enough to `JSON.stringify` that the v1 single-frame `result` event blocks Cloudflare's container event loop. Two things break: Docker's `HEALTHCHECK` fails, and the CLI's 120-second connection timeout fires before the body flushes. v2 emits files one at a time and yields back to the event loop every 10 files (`setImmediate`), keeping `/health` responsive and TCP backpressure alive.
53
+
54
+ The `@quickback-dev/cli` v0.10.x and later send `X-Quickback-Stream: v2` automatically. v1 is preserved for older clients.
55
+
56
+ ### Event shapes (v2)
57
+
58
+ ```
59
+ event: progress
60
+ data: { "stage": "vite-cms", "message": "..." }
61
+
62
+ event: meta
63
+ data: { "fileCount": 412, "version": "0.10.3" }
64
+
65
+ event: file
66
+ data: { "path": "src/...", "content": "...", ... }
67
+ …
68
+
69
+ event: done
70
+ data: { "meta": {...}, "commands": [...], "warnings": [...] }
71
+ ```
72
+
73
+ On failure, an `error` event is emitted in either protocol:
74
+
75
+ ```
76
+ event: error
77
+ data: { "error": "Compilation failed", "code": "...", "message": "..." }
78
+ ```
@@ -0,0 +1,65 @@
1
+ # Cloud Compiler
2
+
3
+ Quickback offers a hosted compiler at `https://compiler.quickback.dev`. The CLI uses it to turn your definitions into a complete backend.
4
+
5
+ ## How It Works
6
+
7
+ ```
8
+ ┌──────────────┐ ┌──────────────────────┐
9
+ │ quickback │ POST │ compiler.quickback │
10
+ │ CLI │────────▶│ .dev/compile │
11
+ │ │ │ │
12
+ │ Sends: │ │ Returns: │
13
+ │ - config │ │ - Hono routes │
14
+ │ - features │◀────────│ - Drizzle migrations │
15
+ │ - meta │ │ - TypeScript SDK │
16
+ └──────────────┘ └──────────────────────┘
17
+ ```
18
+
19
+ 1. The CLI reads your `quickback.config.ts` and feature definitions.
20
+ 2. It sends them to the cloud compiler as a JSON payload.
21
+ 3. The compiler generates all backend files (routes, migrations, SDK, OpenAPI spec).
22
+ 4. The CLI writes the generated files to your project.
23
+
24
+ ## Quick Start
25
+
26
+ ```bash
27
+ # 1. Install the CLI
28
+ npm install -g @quickback-dev/cli
29
+
30
+ # 2. Create a project
31
+ quickback create cloudflare my-app
32
+ cd my-app
33
+
34
+ # 3. Log in
35
+ quickback login
36
+
37
+ # 4. Compile
38
+ quickback compile
39
+ ```
40
+
41
+ ## Existing Databases
42
+
43
+ When recompiling an existing project, the CLI automatically sends your Drizzle meta files so the compiler generates **incremental** migrations instead of fresh `CREATE TABLE` statements.
44
+
45
+ Meta files are loaded from `<project>/quickback/drizzle/` only — Quickback owns this state and never reads from a project-root `drizzle/` folder:
46
+ - `quickback/drizzle/auth/meta/`
47
+ - `quickback/drizzle/features/meta/`
48
+ - `quickback/drizzle/files/meta/`
49
+ - `quickback/drizzle/webhooks/meta/`
50
+ - `quickback/drizzle/audit/meta/`
51
+ - `quickback/drizzle/meta/` (single-database mode)
52
+
53
+ Migration and report artifacts are written to the `quickback/` state directory:
54
+ - `quickback/drizzle/...` for Drizzle migration SQL/meta artifacts
55
+ - `quickback/reports/...` for security contract report artifacts
56
+
57
+ No extra configuration needed — the CLI handles this automatically.
58
+
59
+ ## Next Steps
60
+
61
+ - [CLI Reference](/compiler/cloud-compiler/cli) — All CLI commands
62
+ - [Authentication](/compiler/cloud-compiler/authentication) — Login flow and API keys
63
+ - [Endpoints](/compiler/cloud-compiler/endpoints) — Compiler API reference
64
+ - [Troubleshooting](/compiler/cloud-compiler/troubleshooting) — Common issues
65
+ - [Local Compiler](/compiler/cloud-compiler/local-compiler) — Run the compiler locally
@@ -0,0 +1,115 @@
1
+ # Local Compiler
2
+
3
+ Run the Quickback compiler locally using Docker. The local compiler uses the exact same Docker image as the cloud compiler, ensuring identical behavior — including SPA builds with correct environment variables.
4
+
5
+ ## Prerequisites
6
+
7
+ - Docker Desktop installed and running
8
+ - Quickback monorepo cloned locally
9
+ - Authenticated via `quickback login`
10
+
11
+ ## Quick Start
12
+
13
+ From the monorepo root:
14
+
15
+ ```bash
16
+ cd apps/compiler-local && bash dev.sh
17
+ ```
18
+
19
+ This will:
20
+ 1. Ensure Docker Desktop is running
21
+ 2. Stop any existing compiler container
22
+ 3. Build the Docker image from `apps/compiler/Dockerfile`
23
+ 4. Run it on port 3000
24
+
25
+ ### Custom Port
26
+
27
+ ```bash
28
+ bash dev.sh 3001
29
+ ```
30
+
31
+ ## Compiling a Project
32
+
33
+ Point the CLI to your local compiler:
34
+
35
+ ```bash
36
+ QUICKBACK_API_URL=http://localhost:3000 quickback compile
37
+ ```
38
+
39
+ Or export it for the session:
40
+
41
+ ```bash
42
+ export QUICKBACK_API_URL=http://localhost:3000
43
+ quickback compile
44
+ ```
45
+
46
+ Authentication is always required. Run `quickback login` first if you haven't already.
47
+
48
+ ## Manual Build & Run
49
+
50
+ You can also build and run the Docker image directly from the monorepo root:
51
+
52
+ ```bash
53
+ # Build
54
+ docker build -t quickback-compiler -f apps/compiler/Dockerfile .
55
+
56
+ # Run
57
+ docker run --rm -p 3000:3000 quickback-compiler
58
+ ```
59
+
60
+ ## Verify
61
+
62
+ Check the compiler is running:
63
+
64
+ ```bash
65
+ curl http://localhost:3000/health
66
+ ```
67
+
68
+ ## How It Works
69
+
70
+ The Docker image includes:
71
+ - Pre-installed dependencies for compiled projects (`/deps/node_modules`)
72
+ - CMS and Account SPA source code (`/spa/cms/`, `/spa/account/`)
73
+ - Pre-installed SPA dependencies (`/spa-deps/cms/`, `/spa-deps/account/`)
74
+
75
+ When compiling a project with `cms: true` or `account: true`, the compiler builds the SPAs from source inside the container with the correct Vite environment variables (e.g., `VITE_QUICKBACK_API_URL`, `VITE_QUICKBACK_ACCOUNT_URL`). This ensures each project gets properly configured SPA assets without manual intervention.
76
+
77
+ ## Deploying to Cloud
78
+
79
+ After making changes to the compiler, deploy to `compiler.quickback.dev`:
80
+
81
+ ```bash
82
+ cd apps/compiler-cloud && bash deploy.sh
83
+ ```
84
+
85
+ ## Troubleshooting
86
+
87
+ ### Container not starting
88
+
89
+ ```bash
90
+ docker logs quickback-compiler-local
91
+ ```
92
+
93
+ ### Port already in use
94
+
95
+ ```bash
96
+ # Find what's using the port
97
+ lsof -i :3000
98
+
99
+ # Use a different port
100
+ bash dev.sh 3001
101
+ ```
102
+
103
+ ### Docker out of disk space
104
+
105
+ ```bash
106
+ docker system prune -af
107
+ ```
108
+
109
+ ### SPA build warnings
110
+
111
+ If you see SPA build warnings during compilation, ensure the SPA dependency files are up to date:
112
+ - `apps/compiler/deps-spa-cms-package.json`
113
+ - `apps/compiler/deps-spa-account-package.json`
114
+
115
+ These must include all dependencies from `packages/cms/package.json` and `packages/account/package.json` respectively.
@@ -0,0 +1,76 @@
1
+ # Troubleshooting
2
+
3
+ ## 401 Unauthorized
4
+
5
+ Your session may have expired (sessions last 7 days). Re-authenticate:
6
+
7
+ ```bash
8
+ quickback logout
9
+ quickback login
10
+ ```
11
+
12
+ ## Compilation timeout
13
+
14
+ Large projects may take longer to compile. The cloud compiler uses [Cloudflare Containers](https://developers.cloudflare.com/containers/) to run compilation in isolated environments. If you hit timeouts, try [running the compiler locally](/compiler/cloud-compiler/local-compiler).
15
+
16
+ ## "Command not found: quickback"
17
+
18
+ Make sure the CLI is installed globally:
19
+ ```bash
20
+ npm install -g @quickback-dev/cli
21
+ ```
22
+
23
+ Or use npx:
24
+ ```bash
25
+ npx @quickback-dev/cli create cloudflare my-app
26
+ ```
27
+
28
+ ## Compile errors
29
+
30
+ 1. Check your `quickback.config.ts` exists and is valid
31
+ 2. Ensure all tables in `quickback/features/` have valid exports
32
+ 3. Run `quickback compile` with `--verbose` for detailed output
33
+
34
+ ## Drizzle rename prompts in CI/headless compile
35
+
36
+ If compilation fails with an interactive Drizzle message like:
37
+
38
+ - `drizzle-kit requested interactive rename input, but Quickback compile is running headless`
39
+ - `Missing rename hint for table/column ...`
40
+
41
+ then add explicit rename hints in `quickback.config.ts`:
42
+
43
+ ```typescript
44
+ export default defineConfig({
45
+ // ...
46
+ compiler: {
47
+ migrations: {
48
+ renames: {
49
+ tables: {
50
+ events_v2: "events",
51
+ },
52
+ columns: {
53
+ events: {
54
+ summary_text: "summary",
55
+ },
56
+ },
57
+ },
58
+ },
59
+ },
60
+ });
61
+ ```
62
+
63
+ `tables` and `columns` mappings are always `new_name -> old_name`.
64
+
65
+ If a hint is missing, compile now fails loudly with the exact key path to add, for example:
66
+
67
+ - `Expected hint key: compiler.migrations.renames.tables["events_v2"]`
68
+ - `Expected hint key: compiler.migrations.renames.columns["events"]["summary_text"]`
69
+
70
+ ## "Could not load organizations"
71
+
72
+ This can happen if your session token expired or if the API is temporarily unavailable. Re-login:
73
+ ```bash
74
+ quickback logout
75
+ quickback login
76
+ ```
@@ -0,0 +1,144 @@
1
+ # AI Agent Readiness
2
+
3
+ Every compiled Quickback Worker advertises itself to AI agents and MCP clients — no user wiring required. One config flag controls the whole discovery surface.
4
+
5
+ ## What the compiler generates
6
+
7
+ When `agents` is enabled (the default), the Worker serves:
8
+
9
+ | Route | What it is |
10
+ |-------|-----------|
11
+ | `GET /robots.txt` | AI-bot policy with the [Cloudflare Content Signals](https://developers.cloudflare.com/bots/concepts/content-signals/) preamble and explicit `Allow:` rules for GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, Applebot-Extended, Bytespider, MistralAI, Cohere, DuckAssist. |
12
+ | `GET /llms.txt` | Agent-facing summary of the API — project name, authentication, resource list, endpoint conventions — derived from your own config. |
13
+ | `GET /.well-known/oauth-protected-resource` | [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) metadata declaring this Worker as a protected resource. |
14
+ | `GET /.well-known/oauth-authorization-server` | [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) metadata pointing at the sign-in and token endpoints. |
15
+ | `GET /.well-known/api-catalog` | [RFC 9727](https://datatracker.ietf.org/doc/html/rfc9727) catalog linking at `/openapi.json`. |
16
+ | `GET /.well-known/mcp.json` | MCP Server Card — discoverable metadata for the MCP server below. |
17
+ | `POST /mcp` | Auto-generated MCP-over-HTTP server. One tool per OpenAPI operation, JWT auth forwarded through the same middleware as the REST API. |
18
+
19
+ ## Default behavior
20
+
21
+ ```ts title="quickback.config.ts"
22
+ import { defineConfig } from '@quickback/compiler';
23
+
24
+ export default defineConfig({
25
+ name: 'my-api',
26
+ // …
27
+ // agents: true is the default — no need to write it.
28
+ });
29
+ ```
30
+
31
+ Run `quickback compile` and every endpoint above ships in the Worker.
32
+
33
+ ## Opting out
34
+
35
+ ```ts title="quickback.config.ts"
36
+ export default defineConfig({
37
+ // …
38
+ agents: false, // disables everything
39
+ });
40
+ ```
41
+
42
+ ## Fine-grained control
43
+
44
+ Pass an object to toggle individual surfaces:
45
+
46
+ ```ts title="quickback.config.ts"
47
+ export default defineConfig({
48
+ // …
49
+ agents: {
50
+ robotsTxt: true, // default
51
+ llmsTxt: true, // default
52
+ mcp: true, // default
53
+ oauthDiscovery: true, // default
54
+ apiCatalog: true, // default
55
+ allowAiCrawlers: true, // default — flip to false to Disallow in robots.txt
56
+ },
57
+ });
58
+ ```
59
+
60
+ ## The MCP server
61
+
62
+ ### Tools
63
+
64
+ Every operation in your generated OpenAPI spec becomes one MCP tool. The tool name is the operation's `operationId` (e.g. `listCustomers`, `createInvoice`, `sendInvoice`). Each tool's `inputSchema` is a flat JSON Schema combining path params, query params, and the request body.
65
+
66
+ `tools/call` re-enters the same Hono app via `app.request(...)` — so **every existing middleware runs exactly as it would for a direct REST call**: authentication, firewall, access control, guards, masking. No bypass.
67
+
68
+ ### Access-filtered `tools/list`
69
+
70
+ `tools/list` only returns tools the calling identity could actually invoke. Each generated tool entry carries the operation's access metadata (`roles`, `userRole`, `or` / `and` combinators) and `tools/list` filters against `ctx` before responding:
71
+
72
+ - **Unauthenticated callers** see only tools whose access declares the `PUBLIC` pseudo-role, or operations that have no security requirement at all (e.g. sign-in / sign-up).
73
+ - **Authenticated callers** see tools whose role gate intersects their `ctx.roles` or `ctx.userRole`. Admin-only endpoints don't appear for non-admins.
74
+ - **Function-form access** (escape hatch) is opaque at list time — surfaced to any authenticated caller, then evaluated for real on `tools/call`.
75
+ - **Record predicates** are dropped from the list-time check (no record yet) and applied normally on the actual call.
76
+
77
+ This is recon-mitigation, not a security boundary. Hiding a tool from the list never weakens the underlying gate — `tools/call` still runs the full middleware chain and rejects unauthorized invocations the same way a direct REST call would.
78
+
79
+ The unauthenticated `GET /mcp` discovery payload returns server info only; it does **not** enumerate tool names. Inventory is exclusively available via the access-filtered `tools/list`.
80
+
81
+ ### Authentication
82
+
83
+ MCP clients pass their credentials through the standard `Authorization: Bearer <jwt>` header. The generated MCP handler forwards the header verbatim into the internal request, and the same JWT middleware that guards `/api/v1/*` validates it.
84
+
85
+ Mint a JWT from an authenticated session:
86
+
87
+ ```bash
88
+ curl -X POST https://my-api.example.com/api/v1/token \
89
+ -H "Cookie: better-auth.session_token=..." \
90
+ -H "Content-Type: application/json"
91
+ ```
92
+
93
+ ### Connecting clients
94
+
95
+ **Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
96
+
97
+ ```json
98
+ {
99
+ "mcpServers": {
100
+ "my-api": {
101
+ "url": "https://my-api.example.com/mcp",
102
+ "headers": {
103
+ "Authorization": "Bearer <jwt>"
104
+ }
105
+ }
106
+ }
107
+ }
108
+ ```
109
+
110
+ **Cursor** — use the same config shape under `.cursor/mcp.json`.
111
+
112
+ **Quick sanity check with curl:**
113
+
114
+ ```bash
115
+ # List available tools
116
+ curl -X POST https://my-api.example.com/mcp \
117
+ -H "Authorization: Bearer $JWT" \
118
+ -H "Content-Type: application/json" \
119
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
120
+
121
+ # Call a tool
122
+ curl -X POST https://my-api.example.com/mcp \
123
+ -H "Authorization: Bearer $JWT" \
124
+ -H "Content-Type: application/json" \
125
+ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"listCustomers","arguments":{"limit":10}}}'
126
+ ```
127
+
128
+ ### Transport
129
+
130
+ The server speaks the **Streamable HTTP** MCP transport — JSON-RPC 2.0 over `POST`. A plain `GET /mcp` returns the server info document for sanity checks.
131
+
132
+ The MCP route does **not** emit its own CORS headers. The Worker's existing `cors()` middleware applies uniformly, so browser-origin access is governed by the same allowlist as the rest of the API (`auth.trustedOrigins` + the deploy origin). Server-to-server clients (Claude Desktop, Cursor, MCP Inspector) connect with a Bearer token and don't need browser CORS at all. If you want a browser-based MCP client (ChatGPT, Claude.ai) to connect cross-origin, add its origin to `auth.trustedOrigins` like any other web client.
133
+
134
+ ## Verification
135
+
136
+ After you deploy, scan both the REST and MCP surfaces:
137
+
138
+ ```bash
139
+ # Agent-readiness scan (external)
140
+ open https://isitagentready.com/?url=https://my-api.example.com
141
+
142
+ # MCP Inspector (official tool)
143
+ npx @modelcontextprotocol/inspector https://my-api.example.com/mcp
144
+ ```
@@ -0,0 +1,109 @@
1
+ # Auth & JWT
2
+
3
+ The top-level `auth` config block holds provider-agnostic auth knobs that affect how Quickback emits the auth middleware, JWT helpers, and access-rule expansion.
4
+
5
+ ```ts title="quickback.config.ts"
6
+ export default defineConfig({
7
+ // ...
8
+ auth: {
9
+ roleHierarchy: ['member', 'admin', 'owner'],
10
+ jwt: {
11
+ expiresIn: 60,
12
+ issuer: 'my-api',
13
+ // audience, secretEnv, algorithm, revocationCheck...
14
+ },
15
+ },
16
+ });
17
+ ```
18
+
19
+ ## `auth.roleHierarchy`
20
+
21
+ Lowest-to-highest privilege list. Lets access rules use `'role+'` shorthand to mean "this role and above". Documented in detail under [Access — Role hierarchy](/compiler/definitions/access#role-hierarchy).
22
+
23
+ ## `auth.jwt` — JWT bearer-token fast-path
24
+
25
+ Quickback ships its own custom HMAC-SHA256 JWT (not Better Auth's JWT plugin) so it can embed `orgId` and `role` claims the fast-path needs to reconstruct `AppContext` without a database round-trip. The signing secret is shared with Better Auth (`BETTER_AUTH_SECRET`) by default — users only manage one secret.
26
+
27
+ ### Behavior recap
28
+
29
+ 1. The browser SPA gets a JWT via the `set-auth-token` response header on every authenticated call.
30
+ 2. On subsequent requests the SPA sends `Authorization: Bearer <jwt>`.
31
+ 3. The auth middleware's **fast-path** verifies the signature only — no DB query, no session lookup. `AppContext` is reconstructed from JWT claims.
32
+ 4. If verification fails (or no JWT is present), the middleware falls back to session auth.
33
+ 5. After successful session auth, a fresh JWT is minted and returned via `set-auth-token`. The cycle continues.
34
+
35
+ The fast-path is intentionally stateless: it trusts the claims for the full TTL. **Stolen or pre-revocation tokens are valid until they expire.** That's the trade-off the fast-path makes — and the reason `expiresIn` is the most-tuned knob below.
36
+
37
+ ### `expiresIn?: number` — TTL in seconds
38
+
39
+ Default `180` (3 minutes).
40
+
41
+ Lowering this shrinks the worst-case window where a stolen / pre-revocation token still works. Browser SPAs auto-refresh via `set-auth-token` on every authed call, so a low TTL is invisible to logged-in users; only stale server-to-server bearer tokens feel it.
42
+
43
+ ```ts
44
+ auth: { jwt: { expiresIn: 30 } } // 30s — tight post-revocation window
45
+ auth: { jwt: { expiresIn: 3600 } } // 1h — longer-lived tokens for CLI / CI
46
+ ```
47
+
48
+ ### `issuer?: string` — `iss` claim
49
+
50
+ Default omitted.
51
+
52
+ Set this when other services need to distinguish JWTs minted by this Worker from other issuers. The compiler bakes the issuer into both the mint side (added to claims) and the verify side (rejects tokens with mismatched `iss`).
53
+
54
+ ### `audience?: string` — `aud` claim
55
+
56
+ Default omitted.
57
+
58
+ Set this when this Worker's JWTs are consumed by a sibling service that should reject tokens minted for a different audience. Same mint-and-verify treatment as `issuer`.
59
+
60
+ ### `secretEnv?: string` — signing secret env var
61
+
62
+ Default `'BETTER_AUTH_SECRET'`.
63
+
64
+ Override this if you want JWT signing isolated from the Better Auth secret (e.g. rotating one without invalidating the other).
65
+
66
+ ```ts
67
+ auth: { jwt: { secretEnv: 'CUSTOM_JWT_SECRET' } }
68
+ ```
69
+
70
+ The compiler emits `c.env.CUSTOM_JWT_SECRET` (or `process.env.CUSTOM_JWT_SECRET` on Bun/Node) in the auth middleware's verify and mint sites and the `/api/v1/token` endpoint.
71
+
72
+ > **Note:** the files-worker (separate Worker for R2 access) still reads `BETTER_AUTH_SECRET` directly. If you override `secretEnv`, set both env vars to the same value or the files worker's JWT verification will fall back to DB session lookup. Threading `secretEnv` through the files worker is on the roadmap.
73
+
74
+ ### `algorithm?: 'HS256'`
75
+
76
+ Only `HS256` is supported in 0.10.14. `RS256` (asymmetric, public-key verify / private-key sign) is on the roadmap.
77
+
78
+ ### `revocationCheck?: 'none' | 'kv'` — token revocation strategy
79
+
80
+ Default `'none'`.
81
+
82
+ | Value | Behavior | Cost per verify |
83
+ |---|---|---|
84
+ | `'none'` | No revocation check. Stolen tokens valid until TTL expires. Use a low `expiresIn` to bound the replay window. | 0 |
85
+ | `'kv'` | Fast-path consults a denylist KV namespace before accepting the token. Banning a user / revoking sessions writes the user's `sub` to the denylist. | 1 KV read (~5-15ms, edge-cached) |
86
+
87
+ The `'kv'` path keeps the fast-path stateless against the auth DB (still 0 D1 queries) — KV reads on Workers are an order of magnitude cheaper than a D1 round trip *and* give sub-second revocation.
88
+
89
+ > **`'kv'` is deferred to 0.10.15.** Setting `'kv'` in 0.10.14 errors at compile time so the migration path is explicit; the schema accepts it now so users can author their final config today.
90
+
91
+ ## Defaults preserve 0.10.13 behavior
92
+
93
+ Adding the `auth.jwt` block without setting any field is a no-op vs. the 0.10.13 baseline. Each missing field falls back to its hardcoded value:
94
+
95
+ | Field | Default |
96
+ |---|---|
97
+ | `expiresIn` | 180 |
98
+ | `issuer` | omitted |
99
+ | `audience` | omitted |
100
+ | `secretEnv` | `'BETTER_AUTH_SECRET'` |
101
+ | `algorithm` | `'HS256'` |
102
+ | `revocationCheck` | `'none'` |
103
+
104
+ ## Tuning recommendations
105
+
106
+ - **B2C SaaS, mostly browser traffic:** keep defaults. The 180s TTL + auto-refresh model just works.
107
+ - **Pentest engagement / enterprise compliance:** set `expiresIn: 30`. Tokens stay invisible to logged-in users (auto-refreshed every authed call) but stolen-token windows shrink to 30s.
108
+ - **CLI-heavy / long-running CI tokens:** `expiresIn: 3600` for one-hour bearer tokens. Pair with `issuer` / `audience` if multiple services consume the same JWT.
109
+ - **Need immediate revocation:** wait for 0.10.15's `revocationCheck: 'kv'`. Or, today, drop TTL to ~30s — same effect with bounded delay.