@raybase/create 0.0.2 → 0.3.4

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 (644) hide show
  1. package/LICENSE +21 -0
  2. package/THIRD_PARTY_NOTICES.md +38 -0
  3. package/assets/apple-touch-icons/0.png +0 -0
  4. package/assets/apple-touch-icons/1.png +0 -0
  5. package/assets/apple-touch-icons/2.png +0 -0
  6. package/assets/apple-touch-icons/3.png +0 -0
  7. package/assets/apple-touch-icons/4.png +0 -0
  8. package/assets/apple-touch-icons/5.png +0 -0
  9. package/assets/apple-touch-icons/6.png +0 -0
  10. package/assets/apple-touch-icons/7.png +0 -0
  11. package/assets/apple-touch-icons/8.png +0 -0
  12. package/assets/apple-touch-icons/9.png +0 -0
  13. package/assets/apple-touch-icons/A.png +0 -0
  14. package/assets/apple-touch-icons/B.png +0 -0
  15. package/assets/apple-touch-icons/C.png +0 -0
  16. package/assets/apple-touch-icons/D.png +0 -0
  17. package/assets/apple-touch-icons/E.png +0 -0
  18. package/assets/apple-touch-icons/F.png +0 -0
  19. package/assets/apple-touch-icons/G.png +0 -0
  20. package/assets/apple-touch-icons/H.png +0 -0
  21. package/assets/apple-touch-icons/I.png +0 -0
  22. package/assets/apple-touch-icons/J.png +0 -0
  23. package/assets/apple-touch-icons/K.png +0 -0
  24. package/assets/apple-touch-icons/L.png +0 -0
  25. package/assets/apple-touch-icons/M.png +0 -0
  26. package/assets/apple-touch-icons/N.png +0 -0
  27. package/assets/apple-touch-icons/O.png +0 -0
  28. package/assets/apple-touch-icons/P.png +0 -0
  29. package/assets/apple-touch-icons/Q.png +0 -0
  30. package/assets/apple-touch-icons/R.png +0 -0
  31. package/assets/apple-touch-icons/S.png +0 -0
  32. package/assets/apple-touch-icons/T.png +0 -0
  33. package/assets/apple-touch-icons/U.png +0 -0
  34. package/assets/apple-touch-icons/V.png +0 -0
  35. package/assets/apple-touch-icons/W.png +0 -0
  36. package/assets/apple-touch-icons/X.png +0 -0
  37. package/assets/apple-touch-icons/Y.png +0 -0
  38. package/assets/apple-touch-icons/Z.png +0 -0
  39. package/assets/apple-touch-icons/default.png +0 -0
  40. package/dist/.source-hash +1 -0
  41. package/dist/index.d.ts +56 -0
  42. package/dist/index.d.ts.map +1 -0
  43. package/dist/index.js +2353 -0
  44. package/dist/index.js.map +1 -0
  45. package/dist/raybase-package-ranges.d.ts +11 -0
  46. package/dist/raybase-package-ranges.d.ts.map +1 -0
  47. package/dist/raybase-package-ranges.js +11 -0
  48. package/dist/raybase-package-ranges.js.map +1 -0
  49. package/dist/source-fetch.d.ts +91 -0
  50. package/dist/source-fetch.d.ts.map +1 -0
  51. package/dist/source-fetch.js +325 -0
  52. package/dist/source-fetch.js.map +1 -0
  53. package/dist/source-hash.d.ts +2 -0
  54. package/dist/source-hash.d.ts.map +1 -0
  55. package/dist/source-hash.js +23 -0
  56. package/dist/source-hash.js.map +1 -0
  57. package/dist/starter-description.d.ts +44 -0
  58. package/dist/starter-description.d.ts.map +1 -0
  59. package/dist/starter-description.js +273 -0
  60. package/dist/starter-description.js.map +1 -0
  61. package/dist/starter-source.d.ts +43 -0
  62. package/dist/starter-source.d.ts.map +1 -0
  63. package/dist/starter-source.js +156 -0
  64. package/dist/starter-source.js.map +1 -0
  65. package/dist/store-app-apply.d.ts +27 -0
  66. package/dist/store-app-apply.d.ts.map +1 -0
  67. package/dist/store-app-apply.js +100 -0
  68. package/dist/store-app-apply.js.map +1 -0
  69. package/dist/store-app-manifest.d.ts +86 -0
  70. package/dist/store-app-manifest.d.ts.map +1 -0
  71. package/dist/store-app-manifest.js +110 -0
  72. package/dist/store-app-manifest.js.map +1 -0
  73. package/dist/store-app-registry.d.ts +30 -0
  74. package/dist/store-app-registry.d.ts.map +1 -0
  75. package/dist/store-app-registry.js +232 -0
  76. package/dist/store-app-registry.js.map +1 -0
  77. package/models/recommended.json +42 -0
  78. package/modules/api/templates/react-router/app/api/operations.ts +8 -0
  79. package/modules/api/templates/tanstack-start/src/api/operations.ts +15 -0
  80. package/modules/docs/templates/astro-emdash/content/docs/getting-started.mdx +13 -0
  81. package/modules/docs/templates/astro-emdash/content/docs/index.mdx +13 -0
  82. package/modules/docs/templates/astro-emdash/content/docs/mcp.mdx +11 -0
  83. package/modules/docs/templates/astro-emdash/content/docs/meta.json +4 -0
  84. package/modules/docs/templates/astro-emdash/site/content/docs/getting-started.mdx +12 -0
  85. package/modules/docs/templates/astro-emdash/site/content/docs/index.mdx +12 -0
  86. package/modules/docs/templates/astro-emdash/site/content/docs/mcp.mdx +10 -0
  87. package/modules/docs/templates/astro-emdash/site/content/docs/meta.json +4 -0
  88. package/modules/docs/templates/astro-emdash/site/source.config.ts +10 -0
  89. package/modules/docs/templates/astro-emdash/site/src/docs/docs-assets.ts +1 -0
  90. package/modules/docs/templates/astro-emdash/site/src/docs/docs-client.tsx +22 -0
  91. package/modules/docs/templates/astro-emdash/site/src/docs/docs-data.ts +24 -0
  92. package/modules/docs/templates/astro-emdash/site/src/docs/docs-handler.tsx +105 -0
  93. package/modules/docs/templates/astro-emdash/site/src/docs/docs-layout.tsx +56 -0
  94. package/modules/docs/templates/astro-emdash/site/src/docs/docs-mdx.tsx +79 -0
  95. package/modules/docs/templates/astro-emdash/site/src/docs/docs-page-actions.tsx +146 -0
  96. package/modules/docs/templates/astro-emdash/site/src/docs/docs-page.tsx +70 -0
  97. package/modules/docs/templates/astro-emdash/site/src/docs/llm-text.ts +61 -0
  98. package/modules/docs/templates/astro-emdash/site/src/docs/source.ts +7 -0
  99. package/modules/docs/templates/astro-emdash/site/src/pages/docs/[...slug].ts +6 -0
  100. package/modules/docs/templates/astro-emdash/site/src/pages/docs/api/markdown.ts +4 -0
  101. package/modules/docs/templates/astro-emdash/site/src/pages/docs/api/search.ts +4 -0
  102. package/modules/docs/templates/astro-emdash/site/src/pages/llms.txt.ts +8 -0
  103. package/modules/docs/templates/astro-emdash/site/src/styles-docs.css +3 -0
  104. package/modules/docs/templates/astro-emdash/source.config.ts +10 -0
  105. package/modules/docs/templates/astro-emdash/src/docs/docs-assets.ts +1 -0
  106. package/modules/docs/templates/astro-emdash/src/docs/docs-client.tsx +22 -0
  107. package/modules/docs/templates/astro-emdash/src/docs/docs-data.ts +24 -0
  108. package/modules/docs/templates/astro-emdash/src/docs/docs-handler.tsx +105 -0
  109. package/modules/docs/templates/astro-emdash/src/docs/docs-layout.tsx +56 -0
  110. package/modules/docs/templates/astro-emdash/src/docs/docs-mdx.tsx +79 -0
  111. package/modules/docs/templates/astro-emdash/src/docs/docs-page-actions.tsx +146 -0
  112. package/modules/docs/templates/astro-emdash/src/docs/docs-page.tsx +70 -0
  113. package/modules/docs/templates/astro-emdash/src/docs/llm-text.ts +61 -0
  114. package/modules/docs/templates/astro-emdash/src/docs/source.ts +7 -0
  115. package/modules/docs/templates/astro-emdash/src/routes/docs/$.tsx +22 -0
  116. package/modules/docs/templates/astro-emdash/src/routes/docs/api/markdown.ts +12 -0
  117. package/modules/docs/templates/astro-emdash/src/routes/docs/api/search.ts +12 -0
  118. package/modules/docs/templates/astro-emdash/src/routes/docs.index.tsx +22 -0
  119. package/modules/docs/templates/astro-emdash/src/routes/docs.tsx +22 -0
  120. package/modules/docs/templates/astro-emdash/src/styles-docs.css +3 -0
  121. package/modules/docs/templates/react-router/app/components/mdx.tsx +79 -0
  122. package/modules/docs/templates/react-router/app/lib/layout.shared.tsx +54 -0
  123. package/modules/docs/templates/react-router/app/lib/source.ts +7 -0
  124. package/modules/docs/templates/react-router/app/routes/docs.$.tsx +49 -0
  125. package/modules/docs/templates/react-router/app/routes/docs.api.search.ts +10 -0
  126. package/modules/docs/templates/react-router/app/routes/docs.tsx +13 -0
  127. package/modules/docs/templates/react-router/content/docs/getting-started.mdx +8 -0
  128. package/modules/docs/templates/react-router/content/docs/index.mdx +8 -0
  129. package/modules/docs/templates/react-router/content/docs/mcp.mdx +121 -0
  130. package/modules/docs/templates/react-router/content/docs/meta.json +4 -0
  131. package/modules/docs/templates/react-router/source.config.ts +5 -0
  132. package/modules/docs/templates/tanstack-start/content/docs/getting-started.mdx +10 -0
  133. package/modules/docs/templates/tanstack-start/content/docs/index.mdx +8 -0
  134. package/modules/docs/templates/tanstack-start/content/docs/mcp.mdx +121 -0
  135. package/modules/docs/templates/tanstack-start/content/docs/meta.json +4 -0
  136. package/modules/docs/templates/tanstack-start/source.config.ts +10 -0
  137. package/modules/docs/templates/tanstack-start/src/docs/docs-assets.ts +1 -0
  138. package/modules/docs/templates/tanstack-start/src/docs/docs-client.tsx +22 -0
  139. package/modules/docs/templates/tanstack-start/src/docs/docs-data.ts +24 -0
  140. package/modules/docs/templates/tanstack-start/src/docs/docs-handler.tsx +105 -0
  141. package/modules/docs/templates/tanstack-start/src/docs/docs-layout.tsx +56 -0
  142. package/modules/docs/templates/tanstack-start/src/docs/docs-mdx.tsx +79 -0
  143. package/modules/docs/templates/tanstack-start/src/docs/docs-page-actions.tsx +146 -0
  144. package/modules/docs/templates/tanstack-start/src/docs/docs-page.tsx +70 -0
  145. package/modules/docs/templates/tanstack-start/src/docs/llm-text.ts +61 -0
  146. package/modules/docs/templates/tanstack-start/src/docs/source.ts +7 -0
  147. package/modules/docs/templates/tanstack-start/src/routes/docs/$.tsx +22 -0
  148. package/modules/docs/templates/tanstack-start/src/routes/docs/api/markdown.ts +12 -0
  149. package/modules/docs/templates/tanstack-start/src/routes/docs/api/search.ts +12 -0
  150. package/modules/docs/templates/tanstack-start/src/routes/docs.index.tsx +22 -0
  151. package/modules/docs/templates/tanstack-start/src/routes/docs.tsx +22 -0
  152. package/modules/docs/templates/tanstack-start/src/styles-docs.css +3 -0
  153. package/modules/guide/templates/astro-emdash/content/guide/capability-map.md +17 -0
  154. package/modules/guide/templates/astro-emdash/src/components/guide-widget.tsx +41 -0
  155. package/modules/guide/templates/astro-emdash/src/guide/actions.ts +8 -0
  156. package/modules/guide/templates/astro-emdash/src/guide/config.ts +21 -0
  157. package/modules/guide/templates/astro-emdash/src/guide/corpus.gen.ts +4 -0
  158. package/modules/guide/templates/astro-emdash/src/guide/corpus.manifest.json +72 -0
  159. package/modules/guide/templates/astro-emdash/src/guide/corpus.ts +4 -0
  160. package/modules/guide/templates/astro-emdash/src/guide/resources.json +4 -0
  161. package/modules/guide/templates/react-router/app/components/guide-widget.tsx +29 -0
  162. package/modules/guide/templates/react-router/app/guide/actions.ts +3 -0
  163. package/modules/guide/templates/react-router/app/guide/config.ts +21 -0
  164. package/modules/guide/templates/react-router/app/guide/corpus.gen.ts +4 -0
  165. package/modules/guide/templates/react-router/app/guide/corpus.manifest.json +22 -0
  166. package/modules/guide/templates/react-router/app/guide/corpus.ts +4 -0
  167. package/modules/guide/templates/react-router/app/guide/resources.json +4 -0
  168. package/modules/guide/templates/react-router/content/guide/capability-map.md +13 -0
  169. package/modules/guide/templates/tanstack-start/content/guide/capability-map.md +17 -0
  170. package/modules/guide/templates/tanstack-start/src/components/guide-widget.tsx +41 -0
  171. package/modules/guide/templates/tanstack-start/src/guide/actions.ts +17 -0
  172. package/modules/guide/templates/tanstack-start/src/guide/config.ts +21 -0
  173. package/modules/guide/templates/tanstack-start/src/guide/corpus.gen.ts +4 -0
  174. package/modules/guide/templates/tanstack-start/src/guide/corpus.manifest.json +22 -0
  175. package/modules/guide/templates/tanstack-start/src/guide/corpus.ts +4 -0
  176. package/modules/guide/templates/tanstack-start/src/guide/resources.json +4 -0
  177. package/modules/openai-subscription/templates/astro-emdash/.agents/skills/raybase-openai-subscription/SKILL.md +57 -0
  178. package/modules/openai-subscription/templates/astro-emdash/.agents/skills/raybase-openai-subscription/references/compatibility-and-testing.md +129 -0
  179. package/modules/openai-subscription/templates/astro-emdash/.agents/skills/raybase-openai-subscription/references/module-contract.md +133 -0
  180. package/modules/openai-subscription/templates/astro-emdash/.agents/skills/raybase-openai-subscription/references/structured-outputs.md +159 -0
  181. package/modules/openai-subscription/templates/astro-emdash/src/openai-subscription.ts +11 -0
  182. package/modules/openai-subscription/templates/react-router/.agents/skills/raybase-openai-subscription/SKILL.md +57 -0
  183. package/modules/openai-subscription/templates/react-router/.agents/skills/raybase-openai-subscription/references/compatibility-and-testing.md +129 -0
  184. package/modules/openai-subscription/templates/react-router/.agents/skills/raybase-openai-subscription/references/module-contract.md +133 -0
  185. package/modules/openai-subscription/templates/react-router/.agents/skills/raybase-openai-subscription/references/structured-outputs.md +159 -0
  186. package/modules/openai-subscription/templates/react-router/app/openai-subscription.ts +11 -0
  187. package/modules/openai-subscription/templates/tanstack-start/.agents/skills/raybase-openai-subscription/SKILL.md +57 -0
  188. package/modules/openai-subscription/templates/tanstack-start/.agents/skills/raybase-openai-subscription/references/compatibility-and-testing.md +129 -0
  189. package/modules/openai-subscription/templates/tanstack-start/.agents/skills/raybase-openai-subscription/references/module-contract.md +133 -0
  190. package/modules/openai-subscription/templates/tanstack-start/.agents/skills/raybase-openai-subscription/references/structured-outputs.md +159 -0
  191. package/modules/openai-subscription/templates/tanstack-start/src/openai-subscription.ts +11 -0
  192. package/package.json +34 -8
  193. package/skills/README.md +122 -0
  194. package/skills/raybase-actions/SKILL.md +223 -0
  195. package/skills/raybase-actions/references/action-patterns.md +190 -0
  196. package/skills/raybase-actions/references/adapting-actions.md +93 -0
  197. package/skills/raybase-actions/references/testing-actions.md +48 -0
  198. package/skills/raybase-agent-debugging/SKILL.md +230 -0
  199. package/skills/raybase-ai/SKILL.md +1310 -0
  200. package/skills/raybase-api/SKILL.md +45 -0
  201. package/skills/raybase-astro-emdash/SKILL.md +143 -0
  202. package/skills/raybase-astro-emdash-content-model/SKILL.md +217 -0
  203. package/skills/raybase-astro-emdash-content-model/references/LICENSE-emdash +9 -0
  204. package/skills/raybase-astro-emdash-content-model/references/emdash-collections.md +265 -0
  205. package/skills/raybase-astro-emdash-design/LICENSE-impeccable +60 -0
  206. package/skills/raybase-astro-emdash-design/SKILL.md +170 -0
  207. package/skills/raybase-astro-emdash-design/reference/color.md +91 -0
  208. package/skills/raybase-astro-emdash-design/reference/copy.md +73 -0
  209. package/skills/raybase-astro-emdash-design/reference/direction.md +115 -0
  210. package/skills/raybase-astro-emdash-design/reference/imagery.md +84 -0
  211. package/skills/raybase-astro-emdash-design/reference/layout.md +69 -0
  212. package/skills/raybase-astro-emdash-design/reference/motion.md +75 -0
  213. package/skills/raybase-astro-emdash-design/reference/polish.md +75 -0
  214. package/skills/raybase-astro-emdash-design/reference/typography.md +72 -0
  215. package/skills/raybase-astro-emdash-galley/SKILL.md +265 -0
  216. package/skills/raybase-astro-emdash-migration/SKILL.md +218 -0
  217. package/skills/raybase-astro-emdash-migration/references/inventory-and-conversion.md +242 -0
  218. package/skills/raybase-astro-emdash-security-review/SKILL.md +68 -0
  219. package/skills/raybase-astro-emdash-theme-selection/SKILL.md +216 -0
  220. package/skills/raybase-auth/SKILL.md +358 -0
  221. package/skills/raybase-background-jobs/SKILL.md +774 -0
  222. package/skills/raybase-building/SKILL.md +409 -0
  223. package/skills/raybase-building/references/interview-and-spec.md +87 -0
  224. package/skills/raybase-building/references/planning-docs.md +26 -0
  225. package/skills/raybase-building/references/schema-and-config.md +70 -0
  226. package/skills/raybase-changing-a-live-app/SKILL.md +119 -0
  227. package/skills/raybase-data-and-policies/SKILL.md +377 -0
  228. package/skills/raybase-deploy/SKILL.md +136 -0
  229. package/skills/raybase-docs-writing/SKILL.md +119 -0
  230. package/skills/raybase-guide/SKILL.md +235 -0
  231. package/skills/raybase-mcp/SKILL.md +309 -0
  232. package/skills/raybase-mcp/agents/openai.yaml +4 -0
  233. package/skills/raybase-notifications/SKILL.md +138 -0
  234. package/skills/raybase-pro-migration/SKILL.md +28 -0
  235. package/skills/raybase-react-router/SKILL.md +241 -0
  236. package/skills/raybase-react-router-design/LICENSE-impeccable +60 -0
  237. package/skills/raybase-react-router-design/SKILL.md +135 -0
  238. package/skills/raybase-react-router-design/reference/color.md +87 -0
  239. package/skills/raybase-react-router-design/reference/copy.md +83 -0
  240. package/skills/raybase-react-router-design/reference/delight.md +48 -0
  241. package/skills/raybase-react-router-design/reference/interaction.md +91 -0
  242. package/skills/raybase-react-router-design/reference/layout.md +82 -0
  243. package/skills/raybase-react-router-design/reference/motion.md +86 -0
  244. package/skills/raybase-react-router-design/reference/polish.md +79 -0
  245. package/skills/raybase-react-router-design/reference/typography.md +71 -0
  246. package/skills/raybase-react-router-security-review/LICENSE +22 -0
  247. package/skills/raybase-react-router-security-review/SKILL.md +190 -0
  248. package/skills/raybase-react-router-security-review/agents/openai.yaml +4 -0
  249. package/skills/raybase-react-router-security-review/references/api-security.md +519 -0
  250. package/skills/raybase-react-router-security-review/references/authentication.md +353 -0
  251. package/skills/raybase-react-router-security-review/references/authorization.md +372 -0
  252. package/skills/raybase-react-router-security-review/references/business-logic.md +443 -0
  253. package/skills/raybase-react-router-security-review/references/cryptography.md +329 -0
  254. package/skills/raybase-react-router-security-review/references/csrf.md +398 -0
  255. package/skills/raybase-react-router-security-review/references/data-protection.md +378 -0
  256. package/skills/raybase-react-router-security-review/references/deserialization.md +410 -0
  257. package/skills/raybase-react-router-security-review/references/error-handling.md +436 -0
  258. package/skills/raybase-react-router-security-review/references/file-security.md +457 -0
  259. package/skills/raybase-react-router-security-review/references/injection.md +259 -0
  260. package/skills/raybase-react-router-security-review/references/logging.md +433 -0
  261. package/skills/raybase-react-router-security-review/references/misconfiguration.md +435 -0
  262. package/skills/raybase-react-router-security-review/references/modern-threats.md +475 -0
  263. package/skills/raybase-react-router-security-review/references/raybase-react-router-security.md +235 -0
  264. package/skills/raybase-react-router-security-review/references/ssrf.md +413 -0
  265. package/skills/raybase-react-router-security-review/references/supply-chain.md +405 -0
  266. package/skills/raybase-react-router-security-review/references/xss.md +336 -0
  267. package/skills/raybase-realtime/SKILL.md +158 -0
  268. package/skills/raybase-realtime/agents/openai.yaml +4 -0
  269. package/skills/raybase-schema/SKILL.md +209 -0
  270. package/skills/raybase-search/SKILL.md +137 -0
  271. package/skills/raybase-search/agents/openai.yaml +4 -0
  272. package/skills/raybase-settings/SKILL.md +139 -0
  273. package/skills/raybase-settings/agents/openai.yaml +4 -0
  274. package/skills/raybase-tanstack-start/SKILL.md +166 -0
  275. package/skills/raybase-tanstack-start-design/LICENSE-impeccable +60 -0
  276. package/skills/raybase-tanstack-start-design/SKILL.md +140 -0
  277. package/skills/raybase-tanstack-start-design/reference/color.md +80 -0
  278. package/skills/raybase-tanstack-start-design/reference/copy.md +83 -0
  279. package/skills/raybase-tanstack-start-design/reference/delight.md +48 -0
  280. package/skills/raybase-tanstack-start-design/reference/interaction.md +91 -0
  281. package/skills/raybase-tanstack-start-design/reference/layout.md +82 -0
  282. package/skills/raybase-tanstack-start-design/reference/motion.md +86 -0
  283. package/skills/raybase-tanstack-start-design/reference/polish.md +79 -0
  284. package/skills/raybase-tanstack-start-design/reference/typography.md +71 -0
  285. package/skills/raybase-tanstack-start-security-review/LICENSE +22 -0
  286. package/skills/raybase-tanstack-start-security-review/SKILL.md +194 -0
  287. package/skills/raybase-tanstack-start-security-review/agents/openai.yaml +4 -0
  288. package/skills/raybase-tanstack-start-security-review/references/api-security.md +519 -0
  289. package/skills/raybase-tanstack-start-security-review/references/authentication.md +353 -0
  290. package/skills/raybase-tanstack-start-security-review/references/authorization.md +372 -0
  291. package/skills/raybase-tanstack-start-security-review/references/business-logic.md +443 -0
  292. package/skills/raybase-tanstack-start-security-review/references/cryptography.md +329 -0
  293. package/skills/raybase-tanstack-start-security-review/references/csrf.md +398 -0
  294. package/skills/raybase-tanstack-start-security-review/references/data-protection.md +378 -0
  295. package/skills/raybase-tanstack-start-security-review/references/deserialization.md +410 -0
  296. package/skills/raybase-tanstack-start-security-review/references/error-handling.md +436 -0
  297. package/skills/raybase-tanstack-start-security-review/references/file-security.md +457 -0
  298. package/skills/raybase-tanstack-start-security-review/references/injection.md +259 -0
  299. package/skills/raybase-tanstack-start-security-review/references/logging.md +433 -0
  300. package/skills/raybase-tanstack-start-security-review/references/misconfiguration.md +435 -0
  301. package/skills/raybase-tanstack-start-security-review/references/modern-threats.md +475 -0
  302. package/skills/raybase-tanstack-start-security-review/references/raybase-tanstack-security.md +208 -0
  303. package/skills/raybase-tanstack-start-security-review/references/ssrf.md +413 -0
  304. package/skills/raybase-tanstack-start-security-review/references/supply-chain.md +405 -0
  305. package/skills/raybase-tanstack-start-security-review/references/xss.md +336 -0
  306. package/skills-manifest.json +41 -0
  307. package/templates/astro-emdash/.dev.vars.example +7 -0
  308. package/templates/astro-emdash/AGENTS.md +122 -0
  309. package/templates/astro-emdash/DESIGN.md +90 -0
  310. package/templates/astro-emdash/components.json +21 -0
  311. package/templates/astro-emdash/content/docs/getting-started.mdx +20 -0
  312. package/templates/astro-emdash/content/docs/index.mdx +13 -0
  313. package/templates/astro-emdash/content/docs/mcp.mdx +11 -0
  314. package/templates/astro-emdash/content/docs/meta.json +4 -0
  315. package/templates/astro-emdash/content/docs/site-templates.mdx +62 -0
  316. package/templates/astro-emdash/dev/CODEBASE-MAP.md +46 -0
  317. package/templates/astro-emdash/dev/SPEC-OVERVIEW.md +15 -0
  318. package/templates/astro-emdash/dev/SPEC.md +84 -0
  319. package/templates/astro-emdash/dev/features/archive/.gitkeep +1 -0
  320. package/templates/astro-emdash/docs/theme-previews/base.svg +24 -0
  321. package/templates/astro-emdash/docs/theme-previews/steel.svg +24 -0
  322. package/templates/astro-emdash/docs/theme-previews/zen.svg +24 -0
  323. package/templates/astro-emdash/docs/themes.md +106 -0
  324. package/templates/astro-emdash/drizzle.config.ts +5 -0
  325. package/templates/astro-emdash/gitignore +11 -0
  326. package/templates/astro-emdash/migrations/app/meta/_journal.json +5 -0
  327. package/templates/astro-emdash/package.json +79 -0
  328. package/templates/astro-emdash/pnpm-workspace.yaml +71 -0
  329. package/templates/astro-emdash/public/_headers +4 -0
  330. package/templates/astro-emdash/site/astro.config.mjs +120 -0
  331. package/templates/astro-emdash/site/demo/README.md +72 -0
  332. package/templates/astro-emdash/site/demo/content/collection.json +43 -0
  333. package/templates/astro-emdash/site/demo/content/entries.json +120 -0
  334. package/templates/astro-emdash/site/demo/templates/demo-article-card/manifest.json +51 -0
  335. package/templates/astro-emdash/site/demo/templates/demo-article-card/sample-content.json +5 -0
  336. package/templates/astro-emdash/site/demo/templates/demo-article-card/template.liquid +48 -0
  337. package/templates/astro-emdash/site/demo/templates/demo-article-page/host.json +9 -0
  338. package/templates/astro-emdash/site/demo/templates/demo-article-page/manifest.json +38 -0
  339. package/templates/astro-emdash/site/demo/templates/demo-article-page/sample-content.json +34 -0
  340. package/templates/astro-emdash/site/demo/templates/demo-article-page/template.liquid +84 -0
  341. package/templates/astro-emdash/site/demo/templates/demo-articles-index/manifest.json +64 -0
  342. package/templates/astro-emdash/site/demo/templates/demo-articles-index/page.json +7 -0
  343. package/templates/astro-emdash/site/demo/templates/demo-articles-index/sample-content.json +24 -0
  344. package/templates/astro-emdash/site/demo/templates/demo-articles-index/template.liquid +100 -0
  345. package/templates/astro-emdash/site/demo/templates/demo-menu-nav/manifest.json +51 -0
  346. package/templates/astro-emdash/site/demo/templates/demo-menu-nav/sample-content.json +5 -0
  347. package/templates/astro-emdash/site/demo/templates/demo-menu-nav/template.liquid +70 -0
  348. package/templates/astro-emdash/site/gitignore +1 -0
  349. package/templates/astro-emdash/site/package.json +56 -0
  350. package/templates/astro-emdash/site/scripts/apply-site-templates.mjs +560 -0
  351. package/templates/astro-emdash/site/scripts/galley-demo.mjs +298 -0
  352. package/templates/astro-emdash/site/scripts/seed-galley-starter.mjs +360 -0
  353. package/templates/astro-emdash/site/scripts/site-origin.mjs +45 -0
  354. package/templates/astro-emdash/site/seed/seed.json +154 -0
  355. package/templates/astro-emdash/site/seed/templates/.gitkeep +1 -0
  356. package/templates/astro-emdash/site/src/components/RaybaseSignedInMenu.astro +163 -0
  357. package/templates/astro-emdash/site/src/components/blocks/RaybaseActionIsland.astro +41 -0
  358. package/templates/astro-emdash/site/src/content-door/raybase-routes.ts +738 -0
  359. package/templates/astro-emdash/site/src/content-door/resolve-page.ts +142 -0
  360. package/templates/astro-emdash/site/src/content-door/seed.ts +85 -0
  361. package/templates/astro-emdash/site/src/env.d.ts +12 -0
  362. package/templates/astro-emdash/site/src/layouts/SiteLayout.astro +68 -0
  363. package/templates/astro-emdash/site/src/lib/palettes.gen.ts +7 -0
  364. package/templates/astro-emdash/site/src/lib/site-motion.ts +169 -0
  365. package/templates/astro-emdash/site/src/lib/site-shell.ts +294 -0
  366. package/templates/astro-emdash/site/src/live.config.ts +8 -0
  367. package/templates/astro-emdash/site/src/middleware.ts +20 -0
  368. package/templates/astro-emdash/site/src/pages/[...slug].astro +113 -0
  369. package/templates/astro-emdash/site/src/pages/_raybase/handoff/consume.ts +6 -0
  370. package/templates/astro-emdash/site/src/pages/_raybase/islands/action.ts +8 -0
  371. package/templates/astro-emdash/site/src/pages/_raybase/sign-out/index.ts +6 -0
  372. package/templates/astro-emdash/site/src/styles/palette-fonts.gen.css +1 -0
  373. package/templates/astro-emdash/site/src/styles/palettes.gen.css +3 -0
  374. package/templates/astro-emdash/site/src/styles.css +607 -0
  375. package/templates/astro-emdash/site/tsconfig.json +12 -0
  376. package/templates/astro-emdash/site/wrangler.jsonc +34 -0
  377. package/templates/astro-emdash/source.config.ts +10 -0
  378. package/templates/astro-emdash/src/actions.ts +58 -0
  379. package/templates/astro-emdash/src/ai/agents.ts +20 -0
  380. package/templates/astro-emdash/src/ai/retrieval.ts +36 -0
  381. package/templates/astro-emdash/src/auth-door.ts +18 -0
  382. package/templates/astro-emdash/src/client.tsx +25 -0
  383. package/templates/astro-emdash/src/components/.gitkeep +1 -0
  384. package/templates/astro-emdash/src/components/account-menu.tsx +91 -0
  385. package/templates/astro-emdash/src/components/auth-shell.tsx +69 -0
  386. package/templates/astro-emdash/src/components/mode-toggle.tsx +32 -0
  387. package/templates/astro-emdash/src/components/search-command-palette.tsx +107 -0
  388. package/templates/astro-emdash/src/components/setup-token-page.tsx +196 -0
  389. package/templates/astro-emdash/src/components/ui/avatar.tsx +107 -0
  390. package/templates/astro-emdash/src/components/ui/badge.tsx +52 -0
  391. package/templates/astro-emdash/src/components/ui/button.tsx +69 -0
  392. package/templates/astro-emdash/src/components/ui/checkbox.tsx +29 -0
  393. package/templates/astro-emdash/src/components/ui/dialog.tsx +158 -0
  394. package/templates/astro-emdash/src/components/ui/dropdown-menu.tsx +303 -0
  395. package/templates/astro-emdash/src/components/ui/input.tsx +20 -0
  396. package/templates/astro-emdash/src/components/ui/label.tsx +20 -0
  397. package/templates/astro-emdash/src/components/ui/scroll-area.tsx +53 -0
  398. package/templates/astro-emdash/src/components/ui/select.tsx +215 -0
  399. package/templates/astro-emdash/src/components/ui/separator.tsx +23 -0
  400. package/templates/astro-emdash/src/components/ui/sheet.tsx +138 -0
  401. package/templates/astro-emdash/src/components/ui/sidebar.tsx +728 -0
  402. package/templates/astro-emdash/src/components/ui/skeleton.tsx +13 -0
  403. package/templates/astro-emdash/src/components/ui/textarea.tsx +18 -0
  404. package/templates/astro-emdash/src/components/ui/tooltip.tsx +66 -0
  405. package/templates/astro-emdash/src/db/migrations.gen.ts +6 -0
  406. package/templates/astro-emdash/src/db/schema.ts +6 -0
  407. package/templates/astro-emdash/src/db/seed.ts +16 -0
  408. package/templates/astro-emdash/src/db/storage.ts +32 -0
  409. package/templates/astro-emdash/src/docs/docs-assets.ts +1 -0
  410. package/templates/astro-emdash/src/docs/docs-client.tsx +22 -0
  411. package/templates/astro-emdash/src/docs/docs-data.ts +24 -0
  412. package/templates/astro-emdash/src/docs/docs-handler.tsx +105 -0
  413. package/templates/astro-emdash/src/docs/docs-layout.tsx +56 -0
  414. package/templates/astro-emdash/src/docs/docs-mdx.tsx +79 -0
  415. package/templates/astro-emdash/src/docs/docs-page-actions.tsx +146 -0
  416. package/templates/astro-emdash/src/docs/docs-page.tsx +70 -0
  417. package/templates/astro-emdash/src/docs/llm-text.ts +61 -0
  418. package/templates/astro-emdash/src/docs/source.ts +7 -0
  419. package/templates/astro-emdash/src/guide/corpus.gen.ts +4 -0
  420. package/templates/astro-emdash/src/guide/corpus.manifest.json +72 -0
  421. package/templates/astro-emdash/src/hooks/use-mobile.ts +19 -0
  422. package/templates/astro-emdash/src/jobs.example.ts +48 -0
  423. package/templates/astro-emdash/src/lib/account.ts +12 -0
  424. package/templates/astro-emdash/src/lib/auth-client.ts +181 -0
  425. package/templates/astro-emdash/src/lib/utils.ts +6 -0
  426. package/templates/astro-emdash/src/mcp-app.ts +57 -0
  427. package/templates/astro-emdash/src/notifications.example.ts +37 -0
  428. package/templates/astro-emdash/src/raybase.auth.ts +70 -0
  429. package/templates/astro-emdash/src/raybase.config.ts +49 -0
  430. package/templates/astro-emdash/src/raybase.server.ts +56 -0
  431. package/templates/astro-emdash/src/realtime.example.ts +18 -0
  432. package/templates/astro-emdash/src/router.tsx +19 -0
  433. package/templates/astro-emdash/src/routes/__root.tsx +56 -0
  434. package/templates/astro-emdash/src/routes/_app/admin.tsx +13 -0
  435. package/templates/astro-emdash/src/routes/_app/forgot-password.tsx +97 -0
  436. package/templates/astro-emdash/src/routes/_app/index.tsx +169 -0
  437. package/templates/astro-emdash/src/routes/_app/invite.$token.tsx +11 -0
  438. package/templates/astro-emdash/src/routes/_app/login.tsx +193 -0
  439. package/templates/astro-emdash/src/routes/_app/profile.tsx +98 -0
  440. package/templates/astro-emdash/src/routes/_app/reset-password.$token.tsx +15 -0
  441. package/templates/astro-emdash/src/routes/_app/reset-password.tsx +115 -0
  442. package/templates/astro-emdash/src/routes/_app/setup.$token.tsx +11 -0
  443. package/templates/astro-emdash/src/routes/_app/signup.tsx +141 -0
  444. package/templates/astro-emdash/src/routes/_app/verify-email.$token.tsx +15 -0
  445. package/templates/astro-emdash/src/routes/_app/verify-email.tsx +154 -0
  446. package/templates/astro-emdash/src/routes/_app.tsx +33 -0
  447. package/templates/astro-emdash/src/routes/admin/$.ts +20 -0
  448. package/templates/astro-emdash/src/routes/api/$.ts +19 -0
  449. package/templates/astro-emdash/src/routes/docs/$.tsx +22 -0
  450. package/templates/astro-emdash/src/routes/docs/api/markdown.ts +12 -0
  451. package/templates/astro-emdash/src/routes/docs/api/search.ts +12 -0
  452. package/templates/astro-emdash/src/routes/docs.index.tsx +22 -0
  453. package/templates/astro-emdash/src/routes/docs.tsx +22 -0
  454. package/templates/astro-emdash/src/search.ts +6 -0
  455. package/templates/astro-emdash/src/settings.ts +12 -0
  456. package/templates/astro-emdash/src/styles-docs.css +3 -0
  457. package/templates/astro-emdash/src/styles.css +101 -0
  458. package/templates/astro-emdash/src/themes/base.css +76 -0
  459. package/templates/astro-emdash/src/themes/carbon.css +76 -0
  460. package/templates/astro-emdash/src/themes/fonts.css +25 -0
  461. package/templates/astro-emdash/src/themes/sage.css +76 -0
  462. package/templates/astro-emdash/src/themes/sand.css +76 -0
  463. package/templates/astro-emdash/src/themes/slate.css +81 -0
  464. package/templates/astro-emdash/src/themes/ultra.css +76 -0
  465. package/templates/astro-emdash/src/themes/zen.css +76 -0
  466. package/templates/astro-emdash/src/worker-entry.ts +31 -0
  467. package/templates/astro-emdash/tests/raybase-patterns.test.ts +29 -0
  468. package/templates/astro-emdash/tsconfig.json +36 -0
  469. package/templates/astro-emdash/vite.config.ts +130 -0
  470. package/templates/astro-emdash/vitest.config.ts +8 -0
  471. package/templates/astro-emdash/wrangler.jsonc +112 -0
  472. package/templates/react-router/.dev.vars.example +5 -0
  473. package/templates/react-router/.editorconfig +15 -0
  474. package/templates/react-router/AGENTS.md +54 -0
  475. package/templates/react-router/README.md +52 -0
  476. package/templates/react-router/app/app.css +44 -0
  477. package/templates/react-router/app/components/mdx.tsx +79 -0
  478. package/templates/react-router/app/components/ui/button.tsx +45 -0
  479. package/templates/react-router/app/components/ui/card.tsx +87 -0
  480. package/templates/react-router/app/components/ui/separator.tsx +22 -0
  481. package/templates/react-router/app/db/migrations.gen.ts +6 -0
  482. package/templates/react-router/app/db/schema.ts +56 -0
  483. package/templates/react-router/app/db/seed.ts +14 -0
  484. package/templates/react-router/app/entry.server.tsx +41 -0
  485. package/templates/react-router/app/globals.d.ts +1 -0
  486. package/templates/react-router/app/lib/layout.shared.tsx +52 -0
  487. package/templates/react-router/app/lib/source.ts +7 -0
  488. package/templates/react-router/app/lib/utils.ts +6 -0
  489. package/templates/react-router/app/raybase.server.ts +65 -0
  490. package/templates/react-router/app/root.tsx +23 -0
  491. package/templates/react-router/app/routes/_index.tsx +53 -0
  492. package/templates/react-router/app/routes/docs.$.tsx +49 -0
  493. package/templates/react-router/app/routes/docs.api.search.ts +10 -0
  494. package/templates/react-router/app/routes/docs.tsx +13 -0
  495. package/templates/react-router/app/routes.ts +3 -0
  496. package/templates/react-router/components.json +22 -0
  497. package/templates/react-router/content/docs/getting-started.mdx +15 -0
  498. package/templates/react-router/content/docs/index.mdx +8 -0
  499. package/templates/react-router/content/docs/mcp.mdx +121 -0
  500. package/templates/react-router/content/docs/meta.json +4 -0
  501. package/templates/react-router/dev/CODEBASE-MAP.md +48 -0
  502. package/templates/react-router/dev/SPEC-OVERVIEW.md +35 -0
  503. package/templates/react-router/dev/SPEC.md +93 -0
  504. package/templates/react-router/dev/features/archive/.gitkeep +1 -0
  505. package/templates/react-router/drizzle.config.ts +5 -0
  506. package/templates/react-router/env.d.ts +53 -0
  507. package/templates/react-router/gitignore +23 -0
  508. package/templates/react-router/migrations/app/meta/_journal.json +1 -0
  509. package/templates/react-router/package.json +70 -0
  510. package/templates/react-router/public/_headers +4 -0
  511. package/templates/react-router/public/favicon.ico +0 -0
  512. package/templates/react-router/react-router.config.ts +9 -0
  513. package/templates/react-router/source.config.ts +5 -0
  514. package/templates/react-router/tests/raybase-patterns.test.ts +23 -0
  515. package/templates/react-router/tsconfig.json +27 -0
  516. package/templates/react-router/vite.config.ts +59 -0
  517. package/templates/react-router/vitest.config.ts +8 -0
  518. package/templates/react-router/workers/app.ts +40 -0
  519. package/templates/react-router/wrangler.jsonc +111 -0
  520. package/templates/tanstack-start/.dev.vars.example +5 -0
  521. package/templates/tanstack-start/AGENTS.md +95 -0
  522. package/templates/tanstack-start/DESIGN.md +65 -0
  523. package/templates/tanstack-start/components.json +21 -0
  524. package/templates/tanstack-start/content/docs/getting-started.mdx +65 -0
  525. package/templates/tanstack-start/content/docs/index.mdx +10 -0
  526. package/templates/tanstack-start/content/docs/mcp.mdx +122 -0
  527. package/templates/tanstack-start/content/docs/meta.json +4 -0
  528. package/templates/tanstack-start/dev/CODEBASE-MAP.md +84 -0
  529. package/templates/tanstack-start/dev/SPEC-OVERVIEW.md +46 -0
  530. package/templates/tanstack-start/dev/SPEC.md +213 -0
  531. package/templates/tanstack-start/dev/features/archive/.gitkeep +1 -0
  532. package/templates/tanstack-start/docs/theme-previews/base.svg +24 -0
  533. package/templates/tanstack-start/docs/theme-previews/steel.svg +24 -0
  534. package/templates/tanstack-start/docs/theme-previews/zen.svg +24 -0
  535. package/templates/tanstack-start/docs/themes.md +116 -0
  536. package/templates/tanstack-start/drizzle.config.ts +5 -0
  537. package/templates/tanstack-start/gitignore +11 -0
  538. package/templates/tanstack-start/migrations/app/0000_low_karen_page.sql +26 -0
  539. package/templates/tanstack-start/migrations/app/meta/0000_snapshot.json +196 -0
  540. package/templates/tanstack-start/migrations/app/meta/_journal.json +13 -0
  541. package/templates/tanstack-start/package.json +77 -0
  542. package/templates/tanstack-start/public/_headers +8 -0
  543. package/templates/tanstack-start/public/icons/app-icon-maskable.svg +1 -0
  544. package/templates/tanstack-start/public/icons/app-icon.svg +1 -0
  545. package/templates/tanstack-start/public/icons/apple-touch-icon.png +0 -0
  546. package/templates/tanstack-start/public/manifest.webmanifest +14 -0
  547. package/templates/tanstack-start/public/raybase-push-sw.js +32 -0
  548. package/templates/tanstack-start/source.config.ts +10 -0
  549. package/templates/tanstack-start/src/actions.ts +560 -0
  550. package/templates/tanstack-start/src/ai/agents.ts +78 -0
  551. package/templates/tanstack-start/src/ai/retrieval.ts +36 -0
  552. package/templates/tanstack-start/src/auth-door.ts +18 -0
  553. package/templates/tanstack-start/src/client.tsx +25 -0
  554. package/templates/tanstack-start/src/components/.gitkeep +1 -0
  555. package/templates/tanstack-start/src/components/account-menu.tsx +127 -0
  556. package/templates/tanstack-start/src/components/auth-shell.tsx +69 -0
  557. package/templates/tanstack-start/src/components/install-app.tsx +35 -0
  558. package/templates/tanstack-start/src/components/mode-toggle.tsx +32 -0
  559. package/templates/tanstack-start/src/components/search-command-palette.tsx +107 -0
  560. package/templates/tanstack-start/src/components/setup-token-page.tsx +197 -0
  561. package/templates/tanstack-start/src/components/ui/avatar.tsx +107 -0
  562. package/templates/tanstack-start/src/components/ui/badge.tsx +52 -0
  563. package/templates/tanstack-start/src/components/ui/button.tsx +69 -0
  564. package/templates/tanstack-start/src/components/ui/checkbox.tsx +29 -0
  565. package/templates/tanstack-start/src/components/ui/dialog.tsx +158 -0
  566. package/templates/tanstack-start/src/components/ui/dropdown-menu.tsx +303 -0
  567. package/templates/tanstack-start/src/components/ui/input.tsx +20 -0
  568. package/templates/tanstack-start/src/components/ui/label.tsx +20 -0
  569. package/templates/tanstack-start/src/components/ui/scroll-area.tsx +53 -0
  570. package/templates/tanstack-start/src/components/ui/select.tsx +215 -0
  571. package/templates/tanstack-start/src/components/ui/separator.tsx +23 -0
  572. package/templates/tanstack-start/src/components/ui/sheet.tsx +138 -0
  573. package/templates/tanstack-start/src/components/ui/sidebar.tsx +728 -0
  574. package/templates/tanstack-start/src/components/ui/skeleton.tsx +13 -0
  575. package/templates/tanstack-start/src/components/ui/textarea.tsx +18 -0
  576. package/templates/tanstack-start/src/components/ui/tooltip.tsx +66 -0
  577. package/templates/tanstack-start/src/db/migrations.gen.ts +6 -0
  578. package/templates/tanstack-start/src/db/schema.ts +90 -0
  579. package/templates/tanstack-start/src/db/seed.ts +106 -0
  580. package/templates/tanstack-start/src/db/storage.ts +32 -0
  581. package/templates/tanstack-start/src/docs/docs-assets.ts +1 -0
  582. package/templates/tanstack-start/src/docs/docs-client.tsx +22 -0
  583. package/templates/tanstack-start/src/docs/docs-data.ts +24 -0
  584. package/templates/tanstack-start/src/docs/docs-handler.tsx +105 -0
  585. package/templates/tanstack-start/src/docs/docs-layout.tsx +56 -0
  586. package/templates/tanstack-start/src/docs/docs-mdx.tsx +79 -0
  587. package/templates/tanstack-start/src/docs/docs-page-actions.tsx +146 -0
  588. package/templates/tanstack-start/src/docs/docs-page.tsx +70 -0
  589. package/templates/tanstack-start/src/docs/llm-text.ts +61 -0
  590. package/templates/tanstack-start/src/docs/source.ts +7 -0
  591. package/templates/tanstack-start/src/hooks/use-mobile.ts +19 -0
  592. package/templates/tanstack-start/src/hooks/use-pwa-install.ts +77 -0
  593. package/templates/tanstack-start/src/jobs.example.ts +56 -0
  594. package/templates/tanstack-start/src/lib/account.ts +13 -0
  595. package/templates/tanstack-start/src/lib/auth-client.ts +187 -0
  596. package/templates/tanstack-start/src/lib/push-client.ts +98 -0
  597. package/templates/tanstack-start/src/lib/utils.ts +6 -0
  598. package/templates/tanstack-start/src/mcp-app.ts +74 -0
  599. package/templates/tanstack-start/src/notifications.example.ts +37 -0
  600. package/templates/tanstack-start/src/raybase.auth.ts +86 -0
  601. package/templates/tanstack-start/src/raybase.config.ts +86 -0
  602. package/templates/tanstack-start/src/raybase.server.ts +155 -0
  603. package/templates/tanstack-start/src/realtime.example.ts +46 -0
  604. package/templates/tanstack-start/src/router.tsx +19 -0
  605. package/templates/tanstack-start/src/routes/__root.tsx +73 -0
  606. package/templates/tanstack-start/src/routes/_app/admin.tsx +13 -0
  607. package/templates/tanstack-start/src/routes/_app/forgot-password.tsx +97 -0
  608. package/templates/tanstack-start/src/routes/_app/index.tsx +1316 -0
  609. package/templates/tanstack-start/src/routes/_app/invite.$token.tsx +11 -0
  610. package/templates/tanstack-start/src/routes/_app/login.tsx +193 -0
  611. package/templates/tanstack-start/src/routes/_app/profile.tsx +98 -0
  612. package/templates/tanstack-start/src/routes/_app/reset-password.$token.tsx +16 -0
  613. package/templates/tanstack-start/src/routes/_app/reset-password.tsx +115 -0
  614. package/templates/tanstack-start/src/routes/_app/setup.$token.tsx +11 -0
  615. package/templates/tanstack-start/src/routes/_app/signup.tsx +141 -0
  616. package/templates/tanstack-start/src/routes/_app/verify-email.$token.tsx +15 -0
  617. package/templates/tanstack-start/src/routes/_app/verify-email.tsx +154 -0
  618. package/templates/tanstack-start/src/routes/_app.tsx +33 -0
  619. package/templates/tanstack-start/src/routes/admin/$.ts +20 -0
  620. package/templates/tanstack-start/src/routes/api/$.ts +19 -0
  621. package/templates/tanstack-start/src/routes/docs/$.tsx +22 -0
  622. package/templates/tanstack-start/src/routes/docs/api/markdown.ts +12 -0
  623. package/templates/tanstack-start/src/routes/docs/api/search.ts +12 -0
  624. package/templates/tanstack-start/src/routes/docs.index.tsx +22 -0
  625. package/templates/tanstack-start/src/routes/docs.tsx +22 -0
  626. package/templates/tanstack-start/src/search.ts +26 -0
  627. package/templates/tanstack-start/src/settings.ts +12 -0
  628. package/templates/tanstack-start/src/styles-docs.css +3 -0
  629. package/templates/tanstack-start/src/styles.css +73 -0
  630. package/templates/tanstack-start/src/themes/base.css +76 -0
  631. package/templates/tanstack-start/src/themes/carbon.css +76 -0
  632. package/templates/tanstack-start/src/themes/fonts.css +18 -0
  633. package/templates/tanstack-start/src/themes/sage.css +76 -0
  634. package/templates/tanstack-start/src/themes/sand.css +76 -0
  635. package/templates/tanstack-start/src/themes/slate.css +76 -0
  636. package/templates/tanstack-start/src/themes/ultra.css +76 -0
  637. package/templates/tanstack-start/src/themes/zen.css +76 -0
  638. package/templates/tanstack-start/src/worker-entry.ts +30 -0
  639. package/templates/tanstack-start/tests/raybase-patterns.test.ts +247 -0
  640. package/templates/tanstack-start/tsconfig.json +33 -0
  641. package/templates/tanstack-start/vite.config.ts +132 -0
  642. package/templates/tanstack-start/vitest.config.ts +8 -0
  643. package/templates/tanstack-start/wrangler.jsonc +112 -0
  644. package/README.md +0 -3
@@ -0,0 +1,774 @@
1
+ ---
2
+ name: raybase-background-jobs
3
+ description: Build and operate Raybase background jobs. Use when a Raybase or Raybase Pro app needs durable asynchronous work, Cloudflare Queues, scheduled jobs, defineJob/defineJobs, enqueueRaybaseJob, retries, idempotency, job policies, service principals, the Jobs admin UI, or raybase jobs enable, doctor, and deploy wiring.
4
+ ---
5
+
6
+ # Raybase Background Jobs
7
+
8
+ Use jobs for work that should outlive the request, retry safely, be visible in
9
+ admin, or run on a cron. Keep normal request/response code for immediate reads,
10
+ small writes, validation, and UI transitions.
11
+
12
+ Choose the timing primitive before defining a job:
13
+
14
+ | Need | Use |
15
+ | --- | --- |
16
+ | One keyed event at a known exact future moment | Keyed Job schedule |
17
+ | Genuinely recurring wall-clock work | Cron-scheduled Agent or Job |
18
+ | Model judgment revisited once | Agent wake |
19
+ | Fan-out or retryable durable work | Queue Job |
20
+ | Fan-out followed by exactly one join step | Job batch (see Batches) |
21
+
22
+ For an exact one-shot deadline, call `ctx.jobs.schedules.create({ name, key,
23
+ at, input })`. The key is globally unique inside the current data Durable
24
+ Object; namespace it by domain, for example `billing:renew:${id}`. Use
25
+ `replace(key, ...)` to supersede or reactivate an existing key, `cancel(key)`
26
+ for a terminal cancellation, and `suspend`/`resume` when delivery should pause
27
+ without losing the booked target. Core arms the database Durable Object alarm
28
+ for the exact booked instant. Do not create a `dueAt` table and poll it every
29
+ minute.
30
+
31
+ If a model should make a judgment and revisit it once later, use an Agent wake.
32
+ Read the one-shot wakes subsection in `raybase-ai`; wakes share the Jobs queue
33
+ and Durable Object alarm multiplexer but keep collapse-to-one and without-a-signed-in-user
34
+ Agent semantics.
35
+
36
+ ## Workflow
37
+
38
+ 1. Define jobs in an app-owned module such as `src/jobs.ts`.
39
+ 2. Pass `jobs` to the generated app's `createRaybaseApp` call.
40
+ 3. Confirm the worker entry exports `queue`; export `scheduled` when the app also uses a maintenance/backstop cron.
41
+ 4. Run `raybase jobs enable`.
42
+ 5. Run `raybase doctor`, then deploy with `raybase deploy`.
43
+ 6. Verify the Jobs tab in `/admin` and add focused tests for policy, idempotency,
44
+ retry, and scheduling behavior.
45
+
46
+ If a job completion, failure, digest, reminder, or escalation should notify a
47
+ user/operator, read `raybase-notifications` and call
48
+ the job context `notifications.send()` with a stable `dedupeKey`.
49
+ Do not write custom outbox tables or fetch Slack/Teams/webhook providers
50
+ directly from job code.
51
+
52
+ ## Define Jobs
53
+
54
+ Prefer stable job names and JSON-schema inputs unless the app already uses Zod.
55
+
56
+ ```ts
57
+ import { defineJob, anyOf, notificationRecipient, role, fromService } from "@raybase/core"; // Pro: @raybase-pro/pro
58
+ import { appRoles } from "./raybase.config";
59
+
60
+ export const jobs = {
61
+ exportReport: defineJob({
62
+ name: "reports.export",
63
+ input: {
64
+ type: "object",
65
+ properties: {
66
+ reportId: { type: "string", minLength: 1 }
67
+ },
68
+ required: ["reportId"],
69
+ additionalProperties: false
70
+ },
71
+ enqueue: anyOf(role(appRoles, "operations"), fromService("scheduler")),
72
+ view: role(appRoles, "operations"),
73
+ cancel: role(appRoles, "operations"),
74
+ retry: role(appRoles, "operations"),
75
+ runAs: "actor",
76
+ retries: { maxAttempts: 3, backoff: "exponential", delay: "30 seconds" },
77
+ retention: { success: "14 days", failure: "60 days" },
78
+ schedule: { cron: "0 6 * * *", timezone: "UTC", input: { reportId: "daily" } },
79
+ handler: async ({ input, db, log, progress, signal }) => {
80
+ if (signal.aborted) return null;
81
+ log.info("Starting report export", input);
82
+ await progress({ step: "querying" });
83
+ const result = await db.list("reports", { limit: 100 });
84
+ const rows = result.rows;
85
+ await progress({ step: "done", count: rows.length });
86
+ return { count: rows.length };
87
+ }
88
+ })
89
+ };
90
+ ```
91
+
92
+ For Pro apps, import from `@raybase-pro/pro`. In Pro, user principals use
93
+ membership ids and operators use identity ids.
94
+
95
+ ## Action-Backed Jobs
96
+
97
+ When queued work is the background form of a business mutation used by UI, MCP,
98
+ Guide, Agents, or API, define it once with `defineAction()` and adapt it with
99
+ `jobFromAction()`. Read `.agents/skills/raybase-actions/SKILL.md` for action
100
+ design details.
101
+
102
+ ```ts
103
+ import { anyOf, fromService, jobFromAction, role } from "@raybase/core"; // Pro: @raybase-pro/pro
104
+ import { actions } from "./actions";
105
+ import { appRoles } from "./raybase.config";
106
+
107
+ export const jobs = {
108
+ approveRequest: jobFromAction(actions.approveRequest, {
109
+ enqueue: anyOf(role(appRoles, "operations"), fromService("scheduler")),
110
+ runAs: "actor",
111
+ view: role(appRoles, "operations"),
112
+ retry: role(appRoles, "operations"),
113
+ retries: { maxAttempts: 3, backoff: "exponential", delay: "30 seconds" },
114
+ retention: { success: "14 days", failure: "60 days" }
115
+ })
116
+ };
117
+ ```
118
+
119
+ `enqueue` and `runAs` are required. `runAs` is `"actor"`, `"system"`, or
120
+ `{ userRef: "inputField" }`. Queue execution re-resolves the stored
121
+ actor/runAs principal and re-evaluates the action policy when the message runs;
122
+ if the actor no longer passes policy, the run is denied and the action handler
123
+ does not run.
124
+
125
+ Use stable idempotency keys when enqueueing and when the action itself performs
126
+ repeatable state transitions or external sends:
127
+
128
+ ```ts
129
+ await fetch("/api/jobs/requests.approve", {
130
+ method: "POST",
131
+ headers: { "content-type": "application/json" },
132
+ body: JSON.stringify({
133
+ input: { id: requestId },
134
+ options: { idempotencyKey: `requests.approve:${requestId}` }
135
+ })
136
+ });
137
+ ```
138
+
139
+ Action-backed jobs can be scheduled with the normal `schedule` object. Prefer a
140
+ service-principal enqueue policy for system rhythms and keep action handlers
141
+ safe for late or repeated execution.
142
+
143
+ ```ts
144
+ export const jobs = {
145
+ nightlyReview: jobFromAction(actions.reviewOverdueRequests, {
146
+ enqueue: fromService("scheduler"),
147
+ runAs: "system",
148
+ retries: { maxAttempts: 3, backoff: "exponential", delay: "1 minute" },
149
+ schedule: {
150
+ cron: "0 8 * * *",
151
+ timezone: "Europe/Paris",
152
+ input: { window: "overdue" },
153
+ enabled: true
154
+ }
155
+ })
156
+ };
157
+ ```
158
+
159
+ `jobFromAction()` rejects public-audience actions. Do not adapt public Guide or
160
+ public API actions to jobs. Do not adapt `requiresInternalControl` actions
161
+ unless you have confirmed the adapter surface safely supports internal control;
162
+ prefer a direct `defineJob()` for internal operational work.
163
+
164
+ Keep direct `defineJob()` for jobs that are background-only and not shared with
165
+ UI/MCP/API/Agents, such as external syncs, digests, cleanup, imports, file
166
+ processing, backup checks, and provider delivery.
167
+
168
+ ## Model Calls from Job Handlers
169
+
170
+ Direct `defineJob()` handlers receive the runtime's provider-neutral `ctx.ai`
171
+ client and `ctx.settings`. Actions adapted with `jobFromAction()` receive the
172
+ same clients on their action context. `ctx.ai` supports `chat`, `chatStream`,
173
+ `object`, and `embed`; do not construct a provider client or fabricate an HTTP
174
+ request inside a job.
175
+
176
+ Read app-scoped settings at execution time and use structured output when the
177
+ job needs model judgment:
178
+
179
+ ```ts
180
+ import { z } from "zod";
181
+ import { defineJob, fromService } from "@raybase/core"; // Pro: @raybase-pro/pro
182
+
183
+ export const classifyImport = defineJob({
184
+ name: "imports.classify",
185
+ input: z.object({ importId: z.string(), sample: z.string() }),
186
+ enqueue: fromService("scheduler"),
187
+ runAs: "system",
188
+ handler: async ({ input, ai, settings, signal }) => {
189
+ if (signal.aborted) return null;
190
+ // importConfidenceFloor is an app-scoped setting defined by this app.
191
+ const confidenceFloor = await settings.get("importConfidenceFloor");
192
+ const classification = await ai.object({
193
+ schema: z.object({
194
+ category: z.enum(["customers", "orders", "unknown"]),
195
+ confidence: z.number().min(0).max(1)
196
+ }),
197
+ prompt: `Classify this import sample:\n\n${input.sample}`
198
+ }, { signal });
199
+ if (signal.aborted) return null;
200
+ return { importId: input.importId, confidenceFloor, classification };
201
+ }
202
+ });
203
+ ```
204
+
205
+ An explicit `model` on an AI call wins. Otherwise `chat()` and `object()` use
206
+ the resolved runtime default, including a current app-level
207
+ `defaultAiModel` override. The queue runner carries `ctx.signal` into the AI
208
+ client; also pass it in per-call options and check it at natural boundaries
209
+ around other work.
210
+
211
+ Model calls are nondeterministic, and queue delivery remains at-least-once.
212
+ Retries may therefore produce a different valid answer. Keep durable writes,
213
+ provider sends, and other external effects idempotent with stable domain keys;
214
+ do not mistake a validated model result for exactly-once execution. `ctx.ai`
215
+ does not grant Agent conversation state or raw privileged runtime access.
216
+
217
+ Principal and usage accounting follow the job's resolved execution lane:
218
+
219
+ - `runAs: "system"` jobs use the `system` service principal, claim the
220
+ app-wide AI budget lane without inventing a user, and record service
221
+ attribution with a null user id. Declared schedules are seeded by the
222
+ `scheduler` service; dynamic schedules preserve their creator, and the
223
+ job's `runAs` still determines the final execution lane when they fire.
224
+ - Actor/user execution retains the resolved real user and records the user AI
225
+ budget and usage attribution in addition to the app-wide budget.
226
+ - Runtime-owned usage evidence records the service name on the service lane;
227
+ user-attributed rows have no service name. Both lanes add trusted `jobName`
228
+ and `jobRunId` metadata so operators can correlate a call with its job run.
229
+ The evidence does not copy prompts or arbitrary model content.
230
+
231
+ Treat those records as runtime-owned operator evidence. Generated app code
232
+ must not query `_ai_usage_events` or other Raybase system tables directly.
233
+
234
+ ## Repeatable Jobs
235
+
236
+ Use the existing `schedule` object for hourly, daily, weekly, and other
237
+ repeatable work. Do not invent helper APIs such as `everyDayAt()` unless the app
238
+ already has such helpers; the canonical Raybase form is explicit cron plus an
239
+ optional timezone and input.
240
+
241
+ Good repeatable-job examples:
242
+
243
+ ```ts
244
+ import { defineJob, notificationRecipient, role, fromService } from "@raybase/core";
245
+ import { appRoles } from "./raybase.config";
246
+
247
+ export const jobs = {
248
+ hourlySync: defineJob({
249
+ name: "integrations.hourly-sync",
250
+ input: { type: "object", properties: {}, additionalProperties: false },
251
+ enqueue: fromService("scheduler"),
252
+ view: role(appRoles, "operations"),
253
+ retry: role(appRoles, "operations"),
254
+ runAs: "system",
255
+ retries: { maxAttempts: 3, backoff: "exponential", delay: "1 minute" },
256
+ schedule: { cron: "0 * * * *", input: {} },
257
+ handler: async ({ db, log }) => {
258
+ log.info("Running hourly sync");
259
+ // Store external cursors/checkpoints in app data so late or repeated
260
+ // runs are safe.
261
+ }
262
+ }),
263
+
264
+ dailyDigest: defineJob({
265
+ name: "notifications.daily-digest",
266
+ input: { type: "object", properties: {}, additionalProperties: false },
267
+ enqueue: fromService("scheduler"),
268
+ view: role(appRoles, "operations"),
269
+ runAs: "system",
270
+ schedule: {
271
+ cron: "0 8 * * *",
272
+ timezone: "Europe/Paris",
273
+ input: {},
274
+ enabled: true
275
+ },
276
+ handler: async ({ log, notifications }) => {
277
+ log.info("Building daily digest");
278
+ await notifications.send({
279
+ title: "Daily digest ready",
280
+ to: [notificationRecipient.role("operations")],
281
+ channels: ["feed"],
282
+ dedupeKey: "digest:daily"
283
+ });
284
+ }
285
+ }),
286
+
287
+ weeklyReport: defineJob({
288
+ name: "reports.weekly",
289
+ input: { type: "object", properties: {}, additionalProperties: false },
290
+ enqueue: fromService("scheduler"),
291
+ view: role(appRoles, "operations"),
292
+ runAs: "system",
293
+ schedule: { cron: "0 9 * * mon", timezone: "America/New_York", input: {} },
294
+ handler: async ({ db }) => {
295
+ // Generate the weekly report.
296
+ }
297
+ })
298
+ };
299
+ ```
300
+
301
+ Cron format is five fields: minute, hour, day of month, month, weekday. Prefer
302
+ human-readable job names and admin descriptions over clever cron expressions.
303
+ If the schedule should be visible to non-technical operators, choose examples
304
+ that read naturally in `/admin`: hourly sync, daily digest, weekly report,
305
+ monthly invoice run, stale-record cleanup, backup verification, SLA escalation.
306
+
307
+ `raybase jobs enable` configures the producer and consumer queue and does not
308
+ add a Cloudflare cron trigger. Job schedules, Agent schedules, wakes, and
309
+ follow-ups share the data Durable Object's single alarm. A user-declared coarse
310
+ cron may remain as an optional reconciliation/maintenance backstop; it is not
311
+ required for scheduler correctness and `jobs enable` preserves it unchanged.
312
+
313
+ Runtime schedules are available in module routes, actions, and job handlers:
314
+
315
+ ```ts
316
+ await ctx.jobs.schedules.create({
317
+ name: "billing.renew",
318
+ key: `billing:renew:${subscriptionId}`,
319
+ at: renewalAt,
320
+ input: { subscriptionId }
321
+ });
322
+ ```
323
+
324
+ Scheduled handlers receive `ctx.schedule` with `key`, immutable `bookedAt`,
325
+ `generation`, and a `late` flag. Queue-enqueued runs omit this field.
326
+
327
+ When a DO-backed recurring Job schedule is late, Raybase coalesces all missed
328
+ cron occurrences into one catch-up run, then books the first matching
329
+ occurrence after the current app time. The catch-up run still exposes the
330
+ original missed occurrence through `ctx.schedule.bookedAt`; use that signed
331
+ instant for period identity and idempotency when needed. This is separate from
332
+ the local `raybase dev` substitute for top-level Wrangler Cron Triggers, which
333
+ continues to replay its declared trigger occurrences in order.
334
+
335
+ Repeatable handlers must be safe when they run late or more than once:
336
+
337
+ - Use stable job names and explicit JSON input.
338
+ - Store external sync cursors, sent-digest markers, or invoice period markers in
339
+ app data when the work has side effects.
340
+ - Compare retry delay with the schedule interval. When the delay is greater
341
+ than or equal to the interval, assume a retry can overlap the next scheduled
342
+ run; make the handler idempotent and document its dedupe key, cursor, or
343
+ period marker explicitly.
344
+ - For bounded sweeps such as `db.list(..., { limit: 100 })`, inspect `total` or
345
+ a continuation cursor. Process or enqueue the next page, or log the stated
346
+ remainder for the next schedule; never report success as if the limit meant
347
+ every matching row was handled.
348
+ - Treat scheduled timing as at-least-once and approximate, not a wall-clock
349
+ guarantee.
350
+ - Prefer `runAs: "system"` plus `fromService("scheduler")` for purely
351
+ operational rhythms.
352
+ - Use the Jobs admin UI to verify last run, next run, failures, retry/cancel,
353
+ and schedule visibility before handing off.
354
+
355
+ ## Local Development
356
+
357
+ Wrangler/Vite does not automatically run configured Cron Triggers locally, so
358
+ `raybase dev` supplies a serialized local ticker for the top-level
359
+ `triggers.crons` declarations in `wrangler.jsonc`. After the local spine is
360
+ ready, it fires every declared expression once, then follows each expression's
361
+ UTC occurrences using Raybase's app clock. Moving local time forward replays
362
+ missed occurrences in order; a large jump with a minute cron intentionally
363
+ creates a large serial catch-up sequence.
364
+
365
+ Use `raybase dev --cron-interval 2s` (or another duration of at least one
366
+ second) to compress the cadence during development. This override still fires
367
+ every expression once at startup, then fires each expression serially on the
368
+ wall-clock interval using a fresh app-clock timestamp. Use `raybase dev
369
+ --no-cron` when a test must prove that no scheduled work runs. Projects with no
370
+ declared crons start no ticker and report `DO alarms only; no crons declared`.
371
+
372
+ Every successful local fire logs the expression, intended virtual timestamp,
373
+ and whether it was a startup, natural schedule, or interval event. Delivery is
374
+ at-least-once: a failed connection can be retried after the Worker accepted the
375
+ request, so handlers and their effects must remain idempotent. Do not manually
376
+ call Wrangler's `/cdn-cgi/handler/scheduled` URL as setup; the CLI owns the
377
+ readiness probe, timestamp conversion, retry, restart recovery, and shutdown.
378
+
379
+ ## Wire Handlers
380
+
381
+ In `src/raybase.server.ts`, pass jobs to Raybase through the generated app:
382
+
383
+ ```ts
384
+ import { createRaybaseApp } from "@raybase/core/worker";
385
+ import { jobs } from "./jobs";
386
+
387
+ const raybase = createRaybaseApp({
388
+ config: appConfig,
389
+ schema,
390
+ appMigrations,
391
+ seed,
392
+ jobs
393
+ });
394
+
395
+ export const raybaseHandler = raybase.handler;
396
+ export class RaybaseAIChatAgentObject extends raybase.RaybaseAIChatAgentObject {}
397
+ ```
398
+
399
+ In `src/worker-entry.ts`, keep both non-fetch exports:
400
+
401
+ ```ts
402
+ import serverEntry from "@tanstack/react-start/server-entry";
403
+ import type { RaybaseEnv } from "@raybase/core/worker";
404
+ import { raybaseHandler } from "./raybase.server";
405
+
406
+ export { RaybaseDatabaseObject } from "@raybase/core/do";
407
+ export { RaybaseAIChatAgentObject } from "./raybase.server";
408
+
409
+ export default {
410
+ async fetch(request: Request, env: unknown, ctx: ExecutionContext): Promise<Response> {
411
+ return (serverEntry as unknown as { fetch: (request: Request, env: unknown, ctx: ExecutionContext) => Promise<Response> }).fetch(request, env, ctx);
412
+ },
413
+ queue: raybaseHandler.queue,
414
+ async scheduled(event: ScheduledController, env: RaybaseEnv, ctx: ExecutionContext): Promise<void> {
415
+ if (raybaseHandler.scheduled) await raybaseHandler.scheduled(event, env, ctx);
416
+ }
417
+ };
418
+ ```
419
+
420
+ This example is for TanStack Start and astro-emdash spines (both use
421
+ `@tanstack/react-start/server-entry`). React Router apps differ: the app module is
422
+ `app/raybase.server.ts` and the worker entry is `workers/app.ts`, which routes
423
+ through react-router's `createRequestHandler` and already exports
424
+ `queue: raybaseHandler.queue` and `scheduled: raybaseHandler.scheduled`
425
+ directly - keep those exports, not the TanStack wrapper above.
426
+
427
+ `raybase doctor` fails when jobs exist but `queue` is missing. It only requires
428
+ `scheduled` when the Wrangler config declares a platform cron. The Durable
429
+ Object re-export is still required.
430
+
431
+ ## Enqueue Work
432
+
433
+ For user-triggered work, call the built-in endpoint:
434
+
435
+ ```ts
436
+ await fetch("/api/jobs/reports.export", {
437
+ method: "POST",
438
+ headers: { "content-type": "application/json" },
439
+ body: JSON.stringify({
440
+ input: { reportId },
441
+ options: { idempotencyKey: `report:${reportId}` }
442
+ })
443
+ });
444
+ ```
445
+
446
+ For server/internal calls, use `enqueueRaybaseJob` with the current environment,
447
+ config, schema, and principal. Always pass a stable `idempotencyKey` for
448
+ repeat-safe actions. `delay` is a floor, not exact timing; queue batching and
449
+ claiming add latency.
450
+
451
+ When an Agent turn hook or an action running on the Agent lane enqueues jobs,
452
+ derive each key from the server-provided turn identity:
453
+
454
+ ```ts
455
+ await ctx.jobs.enqueue("reports.index", { reportId }, {
456
+ idempotencyKey: `turn:${ctx.runId}:0:index-report`
457
+ });
458
+ ```
459
+
460
+ The key shape is `turn:<runId>:<ordinal>`. Assign the ordinal in server-side
461
+ code to the logical side effect and keep it stable across retries; never derive
462
+ it from retry count, time, or random data. A domain suffix such as
463
+ `index-report` can make evidence easier to read, but the run id and stable
464
+ ordinal remain the uniqueness source. Do not render `runId` into a prompt or
465
+ ask the model to reproduce it.
466
+
467
+ This key deduplicates that enqueue side effect within one Agent run. Every
468
+ future turn has a fresh run id, and enqueue deduplication is not exactly-once
469
+ handler execution. The job handler and each external operation still need
470
+ their own stable idempotency or domain key.
471
+
472
+ ## Batches
473
+
474
+ Use a batch when many jobs fan out and one step must run after all of them
475
+ finish. Do not keep a "remaining" counter in app data: retries, redelivery,
476
+ and expired leases make hand-rolled counters miss or double-count, and the
477
+ pipeline stalls. A crawler that fetches a sitemap, crawls N pages, aggregates
478
+ once, infers N pages, then marks the site complete is two chained batches:
479
+
480
+ ```ts
481
+ import { anyOf, defineJob, fromService, role } from "@raybase/core"; // Pro: @raybase-pro/pro
482
+ import { z } from "zod";
483
+ import { appRoles } from "./raybase.config";
484
+
485
+ const crawl = z.object({ siteId: z.string(), crawlId: z.string() });
486
+ const crawler = anyOf(role(appRoles, "operations"), fromService("system"));
487
+
488
+ export const jobs = {
489
+ sitemap: defineJob({
490
+ name: "crawl.sitemap", input: crawl, enqueue: crawler, runAs: "system",
491
+ handler: async ({ input, jobs }) => {
492
+ const batch = await jobs.batches.create({
493
+ name: "crawl.pages",
494
+ key: `crawl:${input.crawlId}:pages`,
495
+ onComplete: { job: "crawl.aggregate", input },
496
+ onFailure: { job: "crawl.failed", input }
497
+ });
498
+ const urls = await fetchSitemap(input.siteId);
499
+ await jobs.batches.enqueueMany(batch.id, "crawl.page", urls.map((url) => ({ input: { ...input, url }, idempotencyKey: url })));
500
+ await jobs.batches.seal(batch.id);
501
+ }
502
+ }),
503
+ aggregate: defineJob({
504
+ name: "crawl.aggregate", input: crawl, enqueue: crawler, runAs: "system",
505
+ handler: async ({ input, batch, jobs }) => {
506
+ // batch.counts: { total, pending, succeeded, failed, cancelled, denied, expired }
507
+ let cursor: string | null = null;
508
+ do {
509
+ const page = await batch!.children({ status: "succeeded", cursor });
510
+ await mergeIntoSiteIndex(input.siteId, page.children.map((child) => child.result));
511
+ cursor = page.cursor;
512
+ } while (cursor);
513
+ // The next stage is a new batch created from this continuation.
514
+ const infer = await jobs.batches.create({
515
+ name: "crawl.infer",
516
+ key: `crawl:${input.crawlId}:infer`,
517
+ onComplete: { job: "crawl.complete", input }
518
+ });
519
+ const pageIds = await crawledPageIds(input.crawlId);
520
+ await jobs.batches.enqueueMany(infer.id, "crawl.infer-page", pageIds.map((pageId) => ({ input: { ...input, pageId }, idempotencyKey: pageId })));
521
+ await jobs.batches.seal(infer.id);
522
+ }
523
+ })
524
+ // crawl.page, crawl.failed, crawl.infer-page and crawl.complete are ordinary jobs.
525
+ };
526
+ ```
527
+
528
+ - The continuation fires exactly once, after `seal`, when every child is
529
+ terminal: succeeded, failed after its retries, cancelled, or denied. A child
530
+ whose lease expires is failed by the lease sweep. An empty sealed batch
531
+ completes at once.
532
+ - `onFailure` runs instead of `onComplete` when any child did not succeed or
533
+ the batch was cancelled. Without `onFailure`, `onComplete` always runs and
534
+ reads `ctx.batch.counts`. Continuation input is fixed at `create`.
535
+ - `ctx.batch` (or `ctx.job.batch` in an action-backed job) carries `id`,
536
+ `key`, `counts`, `cancelled`, and `children({ status, cursor, limit })`,
537
+ which returns up to 100 children per page in enqueue order with their parsed
538
+ `result` or `error`.
539
+ - `create` is idempotent by `key`, which is unique in the data Durable Object
540
+ (per organization in Pro): the same name and continuations return the
541
+ existing batch, anything else throws. Put a run identity in the key so the
542
+ next crawl gets a new batch.
543
+ - Child idempotency keys are scoped to the batch. Repeating an enqueue returns
544
+ the existing child, so a retried parent never duplicates work. Always pass
545
+ one when the parent can run more than once.
546
+ - Add a fan-out with `enqueueMany(batchId, job, items)`, where each item is
547
+ `{ input, idempotencyKey?, delay? }`, what `enqueue` takes for one child.
548
+ Every input is validated and the child job's `enqueue` policy checked
549
+ before anything is written. Each chunk of 100 is then written in one data
550
+ Durable Object transaction, with its runs, enqueue events and audit rows,
551
+ and sent in one queue batch send. The call returns the runs in item order.
552
+ `enqueue` in a loop costs a Durable Object call and a queue send per
553
+ child. Over thousands of children that runs into the invocation's
554
+ subrequest and duration limits, so use `enqueueMany` for any fan-out past a
555
+ few dozen. If a chunk commits but its send fails, the call throws. When the
556
+ parent retries with the same idempotency keys, every child that was never
557
+ delivered is sent again.
558
+ - After `seal`, only a running child of the same batch may add children (for
559
+ example links it discovered). Anyone else gets an error.
560
+ - `cancel(batchId, reason)` cancels every pending child and fires the
561
+ continuation once with `ctx.batch.cancelled === true`. Cancelling one child
562
+ counts it as cancelled.
563
+ - Batches do not nest: `batches.create` inside a batch child throws, because
564
+ the outer batch would not wait for it. Chain stages from the continuation,
565
+ as above.
566
+ - `create` checks the continuation jobs' `enqueue` policies; `enqueue` and
567
+ `enqueueMany` check the child job's. `get` and `children` use the `onComplete` job's `view`
568
+ policy, `seal` its `enqueue`, and `cancel` its `cancel` policy.
569
+ - An operator retry of a continuation keeps `ctx.batch`; a retried child runs
570
+ on its own and does not rejoin the batch.
571
+ - `/admin` Jobs shows each batch's progress, runs, and continuation run.
572
+ Operator MCP exposes `job_batches_query` and `job_batch_detail`.
573
+
574
+ ## Concurrency and Rate Limits
575
+
576
+ Bound in-flight work on the job declaration. Raybase enforces the bound when
577
+ the data Durable Object claims a run, so it holds however many consumer
578
+ invocations Cloudflare starts:
579
+
580
+ ```ts
581
+ import { z } from "zod";
582
+ import { defineJob, fromService } from "@raybase/core"; // Pro: @raybase-pro/pro
583
+
584
+ export const jobs = {
585
+ crawlPage: defineJob({
586
+ name: "sites.crawl-page",
587
+ input: z.object({ siteId: z.string(), url: z.string().url() }),
588
+ enqueue: fromService("crawler"),
589
+ runAs: "system",
590
+ // At most 20 crawls in flight, and at most 3 against any one customer origin.
591
+ concurrency: {
592
+ max: 20,
593
+ perKey: { key: (input) => `origin:${input.siteId}`, max: 3 }
594
+ },
595
+ // A fetch takes seconds, so a crashed crawl gives its origin slot back fast.
596
+ leaseDuration: "2 minutes",
597
+ handler: async ({ input, signal }) => {
598
+ // fetch input.url, honouring signal
599
+ }
600
+ }),
601
+
602
+ summarizePage: defineJob({
603
+ name: "sites.summarize-page",
604
+ input: z.object({ siteId: z.string(), pageId: z.string() }),
605
+ enqueue: fromService("crawler"),
606
+ runAs: "system",
607
+ concurrency: { max: 10 },
608
+ // Token bucket over starts: 2 per second sustained, 5 back to back,
609
+ // shared by every job that returns the same key.
610
+ rateLimit: { perSecond: 2, burst: 5, key: () => "provider:openai" },
611
+ // Inference can run for several minutes; lease it past the slowest call.
612
+ leaseDuration: "20 minutes",
613
+ handler: async ({ input, ai, signal }) => {
614
+ // ai.object(...) with signal
615
+ }
616
+ })
617
+ };
618
+ ```
619
+
620
+ - `concurrency.max` bounds the runs of this job name that hold a live lease.
621
+ - `concurrency.perKey` bounds runs that share a key. The key is computed from
622
+ the parsed input when the run is enqueued, so make it a pure function of the
623
+ input; a key function that throws or returns an empty string fails the
624
+ enqueue. Keys are shared by every job in the data Durable Object, like
625
+ schedule keys, so namespace them. Two jobs that both return
626
+ `origin:${siteId}` share that origin's slots: use that deliberately to bound
627
+ combined load on one origin or provider, and use distinct prefixes
628
+ otherwise. Each job compares the shared count with its own `perKey.max`.
629
+ - Pair `perKey` with `max` when keys are unbounded, such as one per customer
630
+ site. `perKey` alone lets one job fill every consumer invocation across many
631
+ keys.
632
+ - `rateLimit` is a token bucket over run starts, retries included: `perSecond`
633
+ refills it (fractions allowed, `0.5` is one start every two seconds) and
634
+ `burst` is its capacity, defaulting to `max(1, ceil(perSecond))`. Its
635
+ optional `key` shares a bucket across jobs exactly as `perKey` does; without
636
+ it, each job name has its own bucket. Jobs that share a rate-limit key should
637
+ declare the same `perSecond` and `burst`.
638
+ - A claim over a full limit is deferred, never failed. The run stays `queued`,
639
+ spends no attempt, records `deferredReason` and a `deferrals` count, and
640
+ writes one `deferred` event per wait. The admin Jobs tab shows these runs as
641
+ `deferred`.
642
+ - A run waiting for a concurrency slot is parked in the data Durable Object,
643
+ and its queue message is acknowledged rather than redelivered, so a backlog
644
+ does not poll. A slot is released when the run holding it completes, fails
645
+ (including a failure that schedules a retry), is denied or cancelled, or
646
+ loses its lease to the sweep. The Durable Object then sends a message to
647
+ the oldest parked runs that a claim would now admit. A woken run holds its
648
+ slot for up to 30 seconds while its message is in flight, so a newcomer
649
+ cannot take it, and waiting runs start in the order they were enqueued.
650
+ The Durable Object alarm checks parked runs every minute as a backstop, in
651
+ case a wake could not be sent or never arrived. The claim still decides, so
652
+ a wake never puts a job over its limit.
653
+ - A rate-limited run is redelivered as a fresh queue message once its next
654
+ token is due. Neither kind of wait uses up the consumer's `max_retries` or
655
+ reaches the dead-letter queue.
656
+ - A run counts toward its limits while its lease is live. The lease is the
657
+ job's `leaseDuration`, else `appConfig.jobs.leaseDuration`, else `5 minutes`.
658
+ When a worker dies mid-run, the slot frees as soon as the lease expires: the
659
+ sweep fails the run and wakes the next waiter. A handler that outlives its
660
+ lease stops counting toward the limit, is failed by the sweep, and has its
661
+ completion refused.
662
+ - Choose `leaseDuration` from the job's slowest handler. Use about twice its
663
+ worst observed duration, and never less than its own timeouts, such as a
664
+ model call's. A shorter lease gives a crashed run's slot back sooner. Give a
665
+ seconds-long crawl job a lease of a minute or two, and give a minutes-long
666
+ inference job its own longer lease rather than raising the app-wide default.
667
+ - Cancelling a run frees its slot at once, but its handler keeps running to
668
+ the end and its result is discarded. The next waiter can therefore start
669
+ while the cancelled handler is still finishing, and until it finishes the
670
+ origin can see one more request than its cap.
671
+ - Limits are scoped to one data Durable Object. Separate apps, deployments,
672
+ and Pro organizations do not share them, so they are not a global provider
673
+ quota.
674
+ - A run enqueued before its job declared `perKey` or `rateLimit.key` has no
675
+ stored key; only the job's unkeyed limits apply to it.
676
+ - Batch children and continuations are ordinary runs of their jobs and wait on
677
+ those jobs' limits. A parked child is still pending in its batch, so a
678
+ limited fan-out joins later but never early. Cancelling the batch cancels its
679
+ parked children without starting them, and the slots its running children
680
+ held go to the next waiters.
681
+
682
+ The consumer's `max_concurrency` sits above these limits. The queue handler
683
+ works through each delivered batch of queue messages one at a time, so
684
+ `max_concurrency` is the most queue messages (job runs, schedule dispatch, Agent wakes and follow-ups) the app runs
685
+ at once. `raybase jobs enable` writes 25 in Core, or the largest declared job
686
+ limit plus 5 when that is higher, and keeps a value the app has already tuned.
687
+ `raybase doctor` warns with `jobs-concurrency-consumer` when a job's limit is
688
+ at or above the consumer's `max_concurrency` (the limit never binds, or that
689
+ job alone can occupy every invocation) and when the consumer sets no
690
+ `max_concurrency`.
691
+
692
+ ## Policy Traps
693
+
694
+ - Scheduled and system jobs run as service principals. Service principals never
695
+ satisfy `role()` or `owns()`. Gate scheduled work with
696
+ `anyOf(role(appRoles, "operations"), fromService("scheduler"))`.
697
+ - `owns(column)` evaluates against the job run row, not arbitrary app data. In
698
+ core it compares to `user.id`; in Pro it compares to membership id.
699
+ - `runAs` is only `"actor"`, `"system"`, or `{ userRef: "inputField" }`.
700
+ `userRef` must point to a string in the job input or enqueue fails.
701
+ - Policies are re-evaluated when the queue message runs. If the actor is
702
+ disabled or no longer passes policy, the run is marked denied and the handler
703
+ does not run.
704
+ - Cancellation does not interrupt JavaScript. Handlers must check `ctx.signal`
705
+ at natural boundaries and return early.
706
+ - `mode: "workflow"` is not enabled in this Raybase version. Do not set it.
707
+ For fan-out with a join step, use a batch.
708
+ - Concurrency and rate limits are checked when a run is claimed, not when it
709
+ is enqueued. Enqueue never blocks. A backlog over a concurrency limit waits
710
+ parked in the data Durable Object, and a backlog over a rate limit waits in
711
+ the queue.
712
+
713
+ ## Infrastructure
714
+
715
+ Run:
716
+
717
+ ```bash
718
+ raybase jobs enable
719
+ raybase doctor
720
+ raybase deploy
721
+ ```
722
+
723
+ `jobs enable` patches `wrangler.jsonc` with:
724
+ - `RAYBASE_JOBS` queue producer
725
+ - queue consumer with a dead-letter queue and a `max_concurrency` ceiling
726
+ (see Concurrency and Rate Limits; an existing value is kept)
727
+ - the same `queues` block mirrored into every existing named environment
728
+ (named envs such as `env.local-dev` do not inherit top-level `queues`)
729
+ - optional `RAYBASE_JOB_ARTIFACTS` R2 binding when `--r2` is used
730
+
731
+ It does not add a cron. The data Durable Object alarm is the primary scheduler;
732
+ an app-owned coarse cron is an optional reconciliation and maintenance backstop.
733
+
734
+ An app that enables Jobs infrastructure only for Agent schedule, wake, or
735
+ follow-up triggers — with no deterministic jobs of its own — must set
736
+ `jobs: { enabled: true }` in `appConfig`. Registering an empty `defineJobs({})`
737
+ alone still fails doctor's `jobs-handler` check: the manifest then carries zero
738
+ job names while the `defineJobs(` source match marks the project as using jobs.
739
+
740
+ `deploy` creates the Cloudflare Queue and `<queue>-dlq`. Do not hand-edit only
741
+ part of the queue config and skip `jobs enable`.
742
+
743
+ ## Pro Rules
744
+
745
+ - Job truth lives in each organization's Durable Object. Do not query job tables
746
+ from D1 or add `organization_id` columns to app tables for jobs.
747
+ - In multi-org admin calls, include `adminOrgId` on `/api/admin/jobs/*` routes.
748
+ - Scheduled fanout is bounded and cursor-paginated across organizations; a large
749
+ fleet may not run every organization's due jobs on every cron tick.
750
+ - `createdBy` on Pro job runs is a membership id. `owns("createdBy")` compares
751
+ to membership id, not identity id.
752
+ - Concurrency and rate limits apply per organization: each organization's data
753
+ Durable Object counts only its own runs. Raybase provides no fleet-wide
754
+ per-job limit. The consumer's `max_concurrency` (Pro default 100) is the only
755
+ bound across organizations, and it bounds all queue work, not one job.
756
+
757
+ ## Verify
758
+
759
+ Before handing off:
760
+ - `raybase doctor` passes.
761
+ - The worker entry exports `queue`, plus `scheduled` when Wrangler declares a cron.
762
+ - `/admin` Jobs shows runs, events, schedules, retry/cancel, and settings.
763
+ - Tests cover allowed and denied enqueue, service-principal scheduled enqueue,
764
+ idempotency keys, retries, cancellation where relevant, and Pro org isolation.
765
+ - Jobs that call rate-limited providers or customer origins declare
766
+ `concurrency` or `rateLimit`, and doctor reports no `jobs-concurrency-consumer`
767
+ warning.
768
+
769
+ Forbidden:
770
+ - Do not write directly to `raybase_job_*` tables from app code.
771
+ - Do not count batch children in app data; use `ctx.jobs.batches`.
772
+ - Do not send raw Cloudflare Queue messages; use Raybase enqueue APIs.
773
+ - Do not use raw R2 for job artifacts unless Raybase exposes a safe artifact API.
774
+ - Do not assume enqueue success guarantees execution; runtime policy can deny.