@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
package/dist/index.js ADDED
@@ -0,0 +1,2353 @@
1
+ #!/usr/bin/env node
2
+ import { spawnSync } from "node:child_process";
3
+ import { createHash, generateKeyPairSync, randomBytes } from "node:crypto";
4
+ import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
5
+ import { basename, dirname, join, relative, resolve, sep } from "node:path";
6
+ import { fileURLToPath } from "node:url";
7
+ import { Command } from "commander";
8
+ import { applyEdits, modify, parse } from "jsonc-parser";
9
+ import { applyStoreAppOverlay, assertSafeProjectFiles } from "./store-app-apply.js";
10
+ import { resolveStoreApp } from "./store-app-registry.js";
11
+ import { RAYBASE_PACKAGE_RANGES } from "./raybase-package-ranges.js";
12
+ import { hashSourceTree } from "./source-hash.js";
13
+ import { STARTER_DESCRIPTION_FILE, starterRangeProblem } from "./starter-description.js";
14
+ import { STARTER_TREE_SKIP, resolveStarterSource } from "./starter-source.js";
15
+ export { MAX_SOURCE_BYTES, assertSafeSourcePath, directoryIntegrity, downloadGithubRepo, extractArchive, fetchSourceBuffer, materializeDirectFiles, parseGithubSource, rejectSymlinks, sha256Hex, sha256SourceIntegrity, siblingHref, splitSourceRef, validateDirectFileManifest } from "./source-fetch.js";
16
+ export { STARTER_DESCRIPTION_FILE, STARTER_FRAMEWORKS, StarterDescriptionError, readStarterDescription, satisfiesSemverRange, starterRangeProblem, validateStarterDescription } from "./starter-description.js";
17
+ export { parseStarterSource, resolveStarterSource } from "./starter-source.js";
18
+ const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
19
+ const FRAMEWORKS = ["tanstack-start", "react-router", "astro-emdash"];
20
+ const DEFAULT_FRAMEWORK = "tanstack-start";
21
+ const FRAMEWORK_HELP = `Frameworks (each has a built-in starter):
22
+ tanstack-start Pick for secure internal apps, dashboards, approval tools, and CRUD workflows. This is the default.
23
+ react-router Pick for a React Router app with Raybase sign-in, admin, and data in the same worker.
24
+ astro-emdash Pick for a public Astro + EmDash content site governed by a Raybase spine.`;
25
+ // Where each framework's built-in starter lives in the raybase repo (local
26
+ // mode) vs the published package (bundled by scripts/prepare-create-raybase.mjs into templates/<name>).
27
+ const FRAMEWORK_SOURCE_DIRS = {
28
+ "tanstack-start": "templates/tanstack-start",
29
+ "react-router": "templates/react-router",
30
+ "astro-emdash": "templates/astro-emdash"
31
+ };
32
+ const SKILLS_MANIFEST = loadSkillsManifest();
33
+ const BASE_SKILLS = SKILLS_MANIFEST.base;
34
+ const FRAMEWORK_SKILLS = Object.fromEntries(FRAMEWORKS.map((framework) => [framework, [...BASE_SKILLS, ...(SKILLS_MANIFEST.frameworks[framework] ?? [])]]));
35
+ function loadSkillsManifest() {
36
+ const file = join(packageRoot, "skills-manifest.json");
37
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
38
+ const isNameList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
39
+ // Only base is required. A framework with no skills of its own may be left
40
+ // out; a key that names no framework is a typo and is refused.
41
+ const frameworks = parsed.frameworks ?? {};
42
+ const frameworksValid = typeof frameworks === "object" &&
43
+ !Array.isArray(frameworks) &&
44
+ Object.entries(frameworks).every(([framework, skills]) => FRAMEWORKS.includes(framework) && isNameList(skills));
45
+ if (parsed.schemaVersion !== 1 || !isNameList(parsed.base) || !frameworksValid) {
46
+ throw new Error(`Invalid skills manifest at ${file}: expected schemaVersion 1, a base skill array, and optional skill arrays keyed by framework (${FRAMEWORKS.join(", ")}).`);
47
+ }
48
+ return { ...parsed, frameworks };
49
+ }
50
+ const DOCS_SKILL = "raybase-docs-writing";
51
+ const GUIDE_SKILL = "raybase-guide";
52
+ const API_SKILL = "raybase-api";
53
+ // Skills provenance lock. Stamped by every install/sync so `raybase doctor`
54
+ // can compare what was installed against the CLI's bundled snapshot, and so
55
+ // sync can prune skills it installed without touching user-authored ones.
56
+ // Declared before program.parse below: the create command runs during module
57
+ // evaluation, so later top-level consts would still be in their TDZ.
58
+ const SKILLS_LOCK_FILE = ".raybase/skills.json";
59
+ // Where a project created with --starter records what it was created from:
60
+ // the source as given, the GitHub commit or the integrity it resolved to, and
61
+ // the skills the starter brought. Same footing as .raybase/kits.json.
62
+ const STARTER_LOCK_FILE = ".raybase/starter.json";
63
+ // The Raybase version a starter's `raybase` range is checked against at
64
+ // create time. create-raybase and the raybase CLI release together.
65
+ const CREATE_RAYBASE_VERSION = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version;
66
+ const FIRST_PARTY_MODULES = ["docs", "guide", "api"];
67
+ const noKeptFiles = new Set();
68
+ const DEFAULT_MODULES = ["docs", "guide"];
69
+ const ASTRO_EMDASH_SITE_DOCS_FILES = [
70
+ "site/source.config.ts",
71
+ "site/content/docs/index.mdx",
72
+ "site/content/docs/getting-started.mdx",
73
+ "site/content/docs/mcp.mdx",
74
+ "site/content/docs/meta.json",
75
+ "site/src/docs/docs-assets.ts",
76
+ "site/src/docs/docs-client.tsx",
77
+ "site/src/docs/docs-data.ts",
78
+ "site/src/docs/docs-handler.tsx",
79
+ "site/src/docs/docs-layout.tsx",
80
+ "site/src/docs/docs-mdx.tsx",
81
+ "site/src/docs/docs-page-actions.tsx",
82
+ "site/src/docs/docs-page.tsx",
83
+ "site/src/docs/llm-text.ts",
84
+ "site/src/docs/source.ts",
85
+ "site/src/pages/docs/[...slug].ts",
86
+ "site/src/pages/docs/api/markdown.ts",
87
+ "site/src/pages/docs/api/search.ts",
88
+ "site/src/pages/llms.txt.ts",
89
+ "site/src/styles-docs.css"
90
+ ];
91
+ const MODULE_FILES = {
92
+ docs: {
93
+ "tanstack-start": [
94
+ "source.config.ts",
95
+ "content/docs/index.mdx",
96
+ "content/docs/getting-started.mdx",
97
+ "content/docs/mcp.mdx",
98
+ "content/docs/meta.json",
99
+ "src/docs/docs-assets.ts",
100
+ "src/docs/docs-client.tsx",
101
+ "src/docs/docs-data.ts",
102
+ "src/docs/docs-handler.tsx",
103
+ "src/docs/docs-layout.tsx",
104
+ "src/docs/docs-mdx.tsx",
105
+ "src/docs/docs-page-actions.tsx",
106
+ "src/docs/docs-page.tsx",
107
+ "src/docs/llm-text.ts",
108
+ "src/docs/source.ts",
109
+ "src/styles-docs.css",
110
+ "src/routes/docs.index.tsx",
111
+ "src/routes/docs.tsx",
112
+ "src/routes/docs/$.tsx",
113
+ "src/routes/docs/api/markdown.ts",
114
+ "src/routes/docs/api/search.ts"
115
+ ],
116
+ "react-router": [
117
+ "source.config.ts",
118
+ "content/docs/index.mdx",
119
+ "content/docs/getting-started.mdx",
120
+ "content/docs/mcp.mdx",
121
+ "content/docs/meta.json",
122
+ "app/components/mdx.tsx",
123
+ "app/lib/source.ts",
124
+ "app/lib/layout.shared.tsx",
125
+ "app/routes/docs.tsx",
126
+ "app/routes/docs.$.tsx",
127
+ "app/routes/docs.api.search.ts"
128
+ ],
129
+ "astro-emdash": [
130
+ "source.config.ts",
131
+ "content/docs/index.mdx",
132
+ "content/docs/getting-started.mdx",
133
+ "content/docs/mcp.mdx",
134
+ "content/docs/meta.json",
135
+ "src/docs/docs-assets.ts",
136
+ "src/docs/docs-client.tsx",
137
+ "src/docs/docs-data.ts",
138
+ "src/docs/docs-handler.tsx",
139
+ "src/docs/docs-layout.tsx",
140
+ "src/docs/docs-mdx.tsx",
141
+ "src/docs/docs-page-actions.tsx",
142
+ "src/docs/docs-page.tsx",
143
+ "src/docs/llm-text.ts",
144
+ "src/docs/source.ts",
145
+ "src/styles-docs.css",
146
+ "src/routes/docs.index.tsx",
147
+ "src/routes/docs.tsx",
148
+ "src/routes/docs/$.tsx",
149
+ "src/routes/docs/api/markdown.ts",
150
+ "src/routes/docs/api/search.ts"
151
+ ]
152
+ },
153
+ guide: {
154
+ "tanstack-start": [
155
+ "src/components/guide-widget.tsx",
156
+ "src/guide/actions.ts",
157
+ "src/guide/config.ts",
158
+ "src/guide/corpus.ts",
159
+ "src/guide/corpus.gen.ts",
160
+ "src/guide/corpus.manifest.json",
161
+ "src/guide/resources.json",
162
+ "content/guide/capability-map.md"
163
+ ],
164
+ "react-router": [
165
+ "app/components/guide-widget.tsx",
166
+ "app/guide/actions.ts",
167
+ "app/guide/config.ts",
168
+ "app/guide/corpus.ts",
169
+ "app/guide/corpus.gen.ts",
170
+ "app/guide/corpus.manifest.json",
171
+ "app/guide/resources.json",
172
+ "content/guide/capability-map.md"
173
+ ],
174
+ "astro-emdash": [
175
+ "src/components/guide-widget.tsx",
176
+ "src/guide/actions.ts",
177
+ "src/guide/config.ts",
178
+ "src/guide/corpus.ts",
179
+ "src/guide/corpus.gen.ts",
180
+ "src/guide/corpus.manifest.json",
181
+ "src/guide/resources.json",
182
+ "content/guide/capability-map.md"
183
+ ]
184
+ },
185
+ api: {
186
+ "tanstack-start": ["src/api/operations.ts"],
187
+ "react-router": ["app/api/operations.ts"],
188
+ "astro-emdash": ["src/api/operations.ts"]
189
+ }
190
+ };
191
+ const MODULE_PACKAGES = {
192
+ docs: "@raybase/docs",
193
+ guide: "@raybase/guide",
194
+ api: "@raybase/api"
195
+ };
196
+ const MODULE_SKILLS = {
197
+ docs: [DOCS_SKILL],
198
+ guide: [GUIDE_SKILL],
199
+ api: [API_SKILL]
200
+ };
201
+ const MODULE_COMMANDS = {
202
+ docs: [],
203
+ guide: ["guide enable", "guide disable", "guide index", "guide status"],
204
+ api: []
205
+ };
206
+ const GUIDE_DEPENDENCIES = {
207
+ "@assistant-ui/react": "^0.11.29",
208
+ "@raybase/agent-ui": RAYBASE_PACKAGE_RANGES["@raybase/agent-ui"],
209
+ "@raybase/guide": RAYBASE_PACKAGE_RANGES["@raybase/guide"],
210
+ "lucide-react": "^1.18.0"
211
+ };
212
+ function moduleFileMode(id, template, path) {
213
+ if (id === "docs") {
214
+ if (path.startsWith("content/docs/") || path.startsWith("site/content/docs/"))
215
+ return "editable";
216
+ return "copy";
217
+ }
218
+ if (id === "guide") {
219
+ const guideRoot = template === "react-router" ? "app/guide" : "src/guide";
220
+ if (path === `${guideRoot}/actions.ts` || path === `${guideRoot}/resources.json` || path === `${guideRoot}/config.ts` || path === "content/guide/capability-map.md")
221
+ return "editable";
222
+ if (path === `${guideRoot}/corpus.manifest.json`)
223
+ return "generated";
224
+ return "copy";
225
+ }
226
+ return "copy";
227
+ }
228
+ const DEFAULT_AI_CONFIG_BLOCK = ` ai: {
229
+ enabled: true,
230
+ defaults: {
231
+ model: "@cf/zai-org/glm-4.7-flash",
232
+ embeddingModel: "@cf/baai/bge-base-en-v1.5",
233
+ maxInputChars: 20000,
234
+ maxOutputTokens: 1200
235
+ },
236
+ limits: {
237
+ // Daily spend caps are opt-in and unlimited when unset. Set them only if
238
+ // your inference lane bills per token and you want a hard ceiling:
239
+ // perUserDailyRequests: 50,
240
+ // perUserDailyOutputTokens: 25000,
241
+ // perAppDailyRequests: 500,
242
+ perPublicDailyRequests: 200,
243
+ perPublicDailyOutputTokens: 60000,
244
+ maxToolCallsPerTurn: 6,
245
+ maxLoopStepsPerTurn: 8,
246
+ maxConversationMessages: 40
247
+ }
248
+ },`;
249
+ const AI_CONFIG_PLACEHOLDER = ` // To enable user-facing AI chat features, run \`raybase ai enable\`.
250
+ // ai: {
251
+ // enabled: true
252
+ // }`;
253
+ // Local working state that must never be copied out of a repo checkout
254
+ // (untracked installs, dev caches, personal credentials). Mirrored in
255
+ // scripts/prepare-create-raybase.mjs for the published bundle.
256
+ const FRAMEWORK_EXCLUDES = new Set([
257
+ "node_modules",
258
+ "package-lock.json",
259
+ ".source",
260
+ ".wrangler",
261
+ ".react-router",
262
+ ".cache",
263
+ ".raybase",
264
+ "build",
265
+ "dist",
266
+ ".env",
267
+ ".dev.vars",
268
+ ".DS_Store",
269
+ "pnpm-lock.yaml"
270
+ ]);
271
+ const CANONICAL_SPEC_PATH = "dev/SPEC.md";
272
+ const PLANNING_STUB_DEV_FILES = new Set([".DS_Store", "SPEC.md", "SPEC-OVERVIEW.md"]);
273
+ const PLANNING_DOC_PATHS = ["dev/SPEC.md", "dev/SPEC-OVERVIEW.md"];
274
+ const RECOMMENDED_MODELS_URL = "https://raybase.dev/models/recommended.json";
275
+ const FALLBACK_RECOMMENDED_GUIDE_MODEL = "@cf/zai-org/glm-4.7-flash";
276
+ const program = new Command();
277
+ program
278
+ .name("create-raybase")
279
+ .argument("[directory]", "Project directory")
280
+ .option("--name <name>", "App display name")
281
+ .option("--framework <framework>", `Framework, created from its built-in starter: ${FRAMEWORKS.join(" | ")} (default ${DEFAULT_FRAMEWORK})`)
282
+ .option("--starter <source>", `Create from a starter outside Raybase: a folder, a GitHub repository (github:<owner>/<repo>[/<path>][#ref]) or a web address serving its file-manifest.json. The starter describes itself in ${STARTER_DESCRIPTION_FILE}`)
283
+ .option("--from <store-app>", "Verified Raybase Store app id")
284
+ .option("--store-registry <source>", "Store registry URL. Defaults to the hosted Raybase Store registry.")
285
+ .option("--offline", "Skip network checks; only valid when creating from a built-in starter or a starter folder")
286
+ .option("--local-packages <repoRoot>", "Resolve the built-in starters, skills, and @raybase packages from a local raybase repo checkout (or set RAYBASE_LOCAL)")
287
+ .option("--registry <origin>", "A registry other than the public npm registry that serves @raybase packages, written to the project's .npmrc with its read token taken from REGISTRY_READ_TOKEN")
288
+ .option("--skip-install", "Do not install dependencies")
289
+ .option("--skip-git", "Do not initialize git")
290
+ .option("--without <module>", "Skip a default first-party module (docs | guide)", collect, [])
291
+ .option("--with <module>", "Add an optional first-party module while keeping defaults (api)", collect, [])
292
+ .option("--only <module>", "Install only the listed first-party module(s); may repeat", collect, [])
293
+ .option("--bare", "Install no first-party modules")
294
+ .option("--refresh-skills", "Only refresh Raybase skills in the current project")
295
+ .option("--json", "Print machine-readable output")
296
+ .addHelpText("after", `\n${FRAMEWORK_HELP}`)
297
+ .action(async (directory, options) => {
298
+ try {
299
+ await createRaybaseProject(directory === undefined ? undefined : String(directory), options);
300
+ }
301
+ catch (error) {
302
+ console.error(error instanceof Error ? error.message : String(error));
303
+ process.exit(1);
304
+ }
305
+ });
306
+ if (process.argv[1] === fileURLToPath(import.meta.url)) {
307
+ program.parse(process.argv);
308
+ }
309
+ export async function createRaybaseProject(directory, options) {
310
+ const cwd = process.cwd();
311
+ if (options.starter && options.from) {
312
+ throw new Error("--starter and --from cannot be combined: a Store app is built on a framework's built-in starter.");
313
+ }
314
+ if (options.starter && options.refreshSkills)
315
+ throw new Error("--starter creates a project; --refresh-skills refreshes the current one. Pass one of them.");
316
+ const storeApp = options.from && !options.refreshSkills ? await resolveStoreApp(options.from, { registry: options.storeRegistry, offline: Boolean(options.offline) }) : null;
317
+ let starter = null;
318
+ try {
319
+ if (options.starter) {
320
+ starter = await resolveStarterSource(options.starter, { cwd, offline: Boolean(options.offline) });
321
+ const declared = starter.description.framework;
322
+ if (options.framework !== undefined && options.framework !== declared) {
323
+ throw new Error(`The starter "${starter.description.name}" is built on the ${declared} framework (its ${STARTER_DESCRIPTION_FILE}), but --framework ${options.framework} was passed. Drop --framework, or pass --framework ${declared}.`);
324
+ }
325
+ const rangeProblem = starterRangeProblem(starter.description, CREATE_RAYBASE_VERSION);
326
+ if (rangeProblem) {
327
+ throw new Error(`${rangeProblem} Use a version of the starter made for Raybase ${CREATE_RAYBASE_VERSION}, or a create-raybase inside the starter's range.`);
328
+ }
329
+ }
330
+ if (storeApp && options.framework && options.framework !== DEFAULT_FRAMEWORK && options.framework !== storeApp.manifest.baseFramework) {
331
+ throw new Error(`Store app ${storeApp.id} is built on the ${storeApp.manifest.baseFramework} framework; do not pass --framework with --from.`);
332
+ }
333
+ if (storeApp && (options.bare || options.without?.length || options.with?.length || options.only?.length)) {
334
+ throw new Error("--bare, --without, --with, and --only are not supported with whole-app Store apps in v1.");
335
+ }
336
+ const projectDirectory = directory ?? storeApp?.id ?? "raybase-app";
337
+ const projectDir = options.refreshSkills ? cwd : resolve(cwd, projectDirectory);
338
+ // basename (not the raw argument) so scaffolding in place (".") names the
339
+ // project after the folder the user already made for it.
340
+ const projectName = basename(projectDir);
341
+ const appName = options.name ?? storeApp?.manifest.install.appNameSuggestion ?? humanize(projectName);
342
+ // Same derivation as the letter-mark favicon in the template's __root.tsx.
343
+ const appInitial = appName.trim().charAt(0).toUpperCase().replace(/[^A-Z0-9]/, "") || "A";
344
+ const localRoot = resolveLocalRoot(options.localPackages ?? process.env.RAYBASE_LOCAL) ?? sourceCheckoutRoot();
345
+ const template = options.refreshSkills
346
+ ? detectFramework(projectDir)
347
+ : starter?.description.framework ?? storeApp?.manifest.baseFramework ?? parseFramework(options.framework);
348
+ // The tree the project is copied from: the starter, or the framework's built-in starter.
349
+ const sourceDir = starter ? starter.root : options.refreshSkills ? null : frameworkSourceDir(template, localRoot);
350
+ const selectedModules = options.refreshSkills ? detectInstalledModules(projectDir) : storeApp ? modulesForStoreApp(storeApp) : resolveSelectedModules(options);
351
+ const docsEnabled = selectedModules.has("docs");
352
+ const guideEnabled = selectedModules.has("guide");
353
+ const apiEnabled = selectedModules.has("api");
354
+ const guideAiModel = guideEnabled && !options.refreshSkills
355
+ ? await resolveRecommendedGuideAiModel({ offline: Boolean(options.offline), localRoot })
356
+ : null;
357
+ assertNode();
358
+ assertFreshLocalBuild(localRoot);
359
+ if (sourceDir)
360
+ assertStarterNode(sourceDir, starter?.description.name ?? template);
361
+ if (!options.skipInstall && !options.offline)
362
+ await checkNetwork();
363
+ if (!options.refreshSkills) {
364
+ // Pre-created workspace folders commonly hold agent skills the user wired
365
+ // up, .git, local env/scratch files, a playground BUILD-LOG.md, or a dev/
366
+ // planning dir already — treat those as empty rather than forcing a
367
+ // nested scaffold.
368
+ const scaffoldSafeEntries = new Set([".agents", ".claude", ".git", ".DS_Store", ".env", "tmp", "BUILD-LOG.md"]);
369
+ const blockingEntries = existsSync(projectDir)
370
+ ? readdirSync(projectDir).filter((entry) => !scaffoldSafeEntries.has(entry) && !(entry === "dev" && isScaffoldSafeDevDir(projectDir, sourceDir)))
371
+ : [];
372
+ if (blockingEntries.length > 0) {
373
+ throw new Error(`${projectDir} already exists and is not empty (found: ${blockingEntries.slice(0, 5).join(", ")}).`);
374
+ }
375
+ const preservedPlanningDocs = readPlanningDocs(projectDir);
376
+ mkdirSync(projectDir, { recursive: true });
377
+ if (starter) {
378
+ copyStarterTree(starter, projectDir);
379
+ }
380
+ else {
381
+ cpSync(sourceDir, projectDir, {
382
+ recursive: true,
383
+ filter: (source) => !FRAMEWORK_EXCLUDES.has(source.split("/").pop() ?? "")
384
+ });
385
+ }
386
+ restoreGitignores(projectDir);
387
+ if (starter?.description.spec)
388
+ writeStarterSpec(starter, projectDir);
389
+ replacePlaceholders(projectDir, {
390
+ __APP_NAME__: appName,
391
+ __APP_INITIAL__: appInitial,
392
+ __PACKAGE_NAME__: slugify(projectName)
393
+ });
394
+ restorePlanningDocs(projectDir, preservedPlanningDocs);
395
+ normalizeRaybaseDeps(projectDir, localRoot);
396
+ const docsPlacement = resolveDocsPlacement(projectDir, template, docsEnabled);
397
+ // Module files the starter supplies itself are kept, not laid over.
398
+ const keptModuleFiles = new Set(starter?.description.moduleFiles ?? []);
399
+ for (const file of keptModuleFiles) {
400
+ if (!existsSync(join(projectDir, file)))
401
+ throw new Error(`The starter "${starter.description.name}" lists ${file} in moduleFiles (its ${STARTER_DESCRIPTION_FILE}) but does not contain it.`);
402
+ }
403
+ configureDocs(projectDir, template, docsEnabled, docsPlacement, localRoot, keptModuleFiles);
404
+ configureGuide(projectDir, template, guideEnabled, docsEnabled, localRoot, keptModuleFiles);
405
+ configureApi(projectDir, template, apiEnabled, localRoot, keptModuleFiles);
406
+ if (guideAiModel)
407
+ configureAiDefaultModel(projectDir, template, guideAiModel);
408
+ if (storeApp) {
409
+ applyStoreAppOverlay(projectDir, storeApp, localRoot);
410
+ ensureAgentInstructions(projectDir, template, docsEnabled, guideEnabled, apiEnabled);
411
+ assertSafeProjectFiles(projectDir);
412
+ replacePlaceholders(projectDir, {
413
+ __APP_NAME__: appName,
414
+ __APP_INITIAL__: appInitial,
415
+ __PACKAGE_NAME__: slugify(projectName)
416
+ });
417
+ restorePlanningDocs(projectDir, preservedPlanningDocs);
418
+ normalizeRaybaseDeps(projectDir, localRoot);
419
+ if (guideAiModel)
420
+ configureAiDefaultModel(projectDir, template, guideAiModel);
421
+ }
422
+ applyAppleTouchIcon(projectDir, appInitial);
423
+ ensureDevVars(projectDir, template, guideEnabled, apiEnabled);
424
+ if (starter)
425
+ appendStarterDevVars(projectDir, starter.description);
426
+ recordScaffoldedModules(projectDir, template, selectedModules, docsPlacement, keptModuleFiles);
427
+ }
428
+ const appId = ensureAppId(projectDir);
429
+ installSkills(projectDir, template, localRoot, docsEnabled, guideEnabled, apiEnabled);
430
+ const starterSkills = starter ? installStarterSkills(projectDir, starter) : {};
431
+ ensureAgentInstructions(projectDir, template, docsEnabled, guideEnabled, apiEnabled);
432
+ if (starter?.description.agentInstructions) {
433
+ mergeStarterAgentInstructions(projectDir, starter, { __APP_NAME__: appName, __APP_INITIAL__: appInitial, __PACKAGE_NAME__: slugify(projectName) });
434
+ }
435
+ ensureSpec(projectDir, appName, template);
436
+ if (starter)
437
+ writeStarterLock(projectDir, starter, starterSkills);
438
+ // Published @raybase packages are served by a private registry, not npm; a
439
+ // scaffold without this mapping cannot install its own dependencies.
440
+ // Raybase's packages are on the public npm registry, which needs no .npmrc.
441
+ if (!options.refreshSkills && !localRoot && options.registry)
442
+ writeRegistryNpmrc(projectDir, options.registry);
443
+ if (!options.refreshSkills && !options.skipInstall) {
444
+ const install = installCommand(projectDir);
445
+ run(install.command, install.args, projectDir);
446
+ }
447
+ if (!options.refreshSkills && !options.skipGit) {
448
+ initGit(projectDir);
449
+ }
450
+ const result = {
451
+ ok: true,
452
+ projectDir,
453
+ appName,
454
+ appId,
455
+ framework: template,
456
+ storeApp: storeApp
457
+ ? {
458
+ id: storeApp.manifest.id,
459
+ version: storeApp.manifest.version,
460
+ provenance: join(projectDir, ".raybase/store-app.json")
461
+ }
462
+ : undefined,
463
+ starter: starter
464
+ ? {
465
+ name: starter.description.name,
466
+ source: starter.source.type,
467
+ resolvedRef: starter.source.resolvedRef ?? undefined,
468
+ integrity: starter.source.integrity,
469
+ provenance: join(projectDir, STARTER_LOCK_FILE)
470
+ }
471
+ : undefined,
472
+ docs: docsEnabled,
473
+ guide: guideEnabled,
474
+ api: apiEnabled,
475
+ localPackages: localRoot ?? undefined,
476
+ next: withStarterNextSteps(nextSteps(projectDir, template, docsEnabled, guideEnabled, apiEnabled, storeApp), starter)
477
+ };
478
+ if (options.json) {
479
+ console.log(JSON.stringify(result, null, 2));
480
+ }
481
+ else {
482
+ console.log("RAYBASE_NEXT_STEPS_START");
483
+ console.log(JSON.stringify(result, null, 2));
484
+ console.log("RAYBASE_NEXT_STEPS_END");
485
+ }
486
+ }
487
+ finally {
488
+ storeApp?.cleanup();
489
+ starter?.cleanup();
490
+ }
491
+ }
492
+ // The @raybase half of Pro's scaffolder's mapping (create-raybase-pro adds a
493
+ // line for @raybase-pro, and raybase pro upgrade adds it to a Core app): the
494
+ // scope points at the registry and the read token comes from the environment,
495
+ // never the file.
496
+ function writeRegistryNpmrc(projectDir, origin) {
497
+ const registry = new URL(origin);
498
+ const file = join(projectDir, ".npmrc");
499
+ const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
500
+ if (/^@raybase:registry=/m.test(existing))
501
+ return;
502
+ const lines = [`@raybase:registry=${registry.origin}/`, `//${registry.host}/:_authToken=\${REGISTRY_READ_TOKEN}`];
503
+ writeFileSync(file, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${lines.join("\n")}\n`);
504
+ }
505
+ // The published bundle carries each .gitignore as `gitignore`, because npm
506
+ // never packs .gitignore (scripts/prepare-create-raybase.mjs). Without the
507
+ // rename, the scaffold's first commit would take .dev.vars and .env.
508
+ function restoreGitignores(directory) {
509
+ for (const entry of readdirSync(directory, { withFileTypes: true })) {
510
+ if (entry.name === "node_modules")
511
+ continue;
512
+ const path = join(directory, entry.name);
513
+ if (entry.isDirectory())
514
+ restoreGitignores(path);
515
+ else if (entry.name === "gitignore" && !existsSync(join(directory, ".gitignore")))
516
+ renameSync(path, join(directory, ".gitignore"));
517
+ }
518
+ }
519
+ function collect(value, previous) {
520
+ return [...previous, value];
521
+ }
522
+ function parseFramework(value) {
523
+ const framework = value ?? DEFAULT_FRAMEWORK;
524
+ if (!FRAMEWORKS.includes(framework)) {
525
+ throw new Error(`Unknown framework "${framework}". Valid frameworks: ${FRAMEWORKS.join(", ")}.`);
526
+ }
527
+ return framework;
528
+ }
529
+ function detectFramework(projectDir) {
530
+ const file = join(projectDir, "package.json");
531
+ if (!existsSync(file))
532
+ throw new Error(`No package.json in ${projectDir}. Run --refresh-skills from a Raybase project root.`);
533
+ let declared;
534
+ try {
535
+ declared = JSON.parse(readFileSync(file, "utf8")).raybase?.framework;
536
+ }
537
+ catch (error) {
538
+ throw new Error(`package.json in ${projectDir} could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
539
+ }
540
+ if (declared === undefined || declared === null || declared === "") {
541
+ throw new Error(`package.json has no raybase.framework. Set it to one of: ${FRAMEWORKS.join(", ")}.`);
542
+ }
543
+ if (!FRAMEWORKS.includes(declared)) {
544
+ throw new Error(`package.json raybase.framework is ${JSON.stringify(declared)}, which is not a Raybase framework. Use one of: ${FRAMEWORKS.join(", ")}.`);
545
+ }
546
+ return declared;
547
+ }
548
+ function detectInstalledModules(projectDir) {
549
+ const lockFile = join(projectDir, ".raybase/modules.json");
550
+ if (existsSync(lockFile)) {
551
+ const parsed = JSON.parse(readFileSync(lockFile, "utf8"));
552
+ if (Number(parsed.schemaVersion) > 1)
553
+ throw new Error(".raybase/modules.json schemaVersion is newer than this create-raybase. Upgrade @raybase/create.");
554
+ if (parsed.schemaVersion !== 1 || !parsed.modules || typeof parsed.modules !== "object") {
555
+ throw new Error(".raybase/modules.json is not a valid Raybase Modules lock file.");
556
+ }
557
+ return new Set(FIRST_PARTY_MODULES.filter((module) => parsed.modules?.[module]?.enabled === true));
558
+ }
559
+ const file = join(projectDir, "package.json");
560
+ if (!existsSync(file))
561
+ return new Set(DEFAULT_MODULES);
562
+ try {
563
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
564
+ const modules = parsed.raybase?.modules;
565
+ if (!modules)
566
+ return new Set(DEFAULT_MODULES);
567
+ return new Set(FIRST_PARTY_MODULES.filter((module) => modules[module]?.enabled === true));
568
+ }
569
+ catch {
570
+ return new Set(DEFAULT_MODULES);
571
+ }
572
+ }
573
+ function resolveSelectedModules(options) {
574
+ const without = options.without ?? [];
575
+ const withModules = options.with ?? [];
576
+ const only = options.only ?? [];
577
+ if (options.bare && (without.length || withModules.length || only.length)) {
578
+ throw new Error("--bare cannot be combined with --without, --with, or --only. Use --bare by itself for a platform-only app.");
579
+ }
580
+ if (only.length && (without.length || withModules.length))
581
+ throw new Error("--only cannot be combined with --without or --with.");
582
+ const unknown = [...without, ...withModules, ...only].filter((module) => !FIRST_PARTY_MODULES.includes(module));
583
+ if (unknown.length)
584
+ throw new Error(`Unknown module "${unknown[0]}". Available first-party modules: ${FIRST_PARTY_MODULES.join(", ")}.`);
585
+ if (options.bare)
586
+ return new Set();
587
+ if (only.length)
588
+ return new Set(only);
589
+ const selected = new Set(DEFAULT_MODULES);
590
+ for (const module of without)
591
+ selected.delete(module);
592
+ for (const module of withModules)
593
+ selected.add(module);
594
+ return selected;
595
+ }
596
+ function modulesForStoreApp(storeApp) {
597
+ const modules = new Set();
598
+ if (storeApp.manifest.modules?.docs?.enabled === true)
599
+ modules.add("docs");
600
+ if (storeApp.manifest.modules?.guide?.enabled === true)
601
+ modules.add("guide");
602
+ if (storeApp.manifest.modules?.api?.enabled === true)
603
+ modules.add("api");
604
+ return modules;
605
+ }
606
+ function resolveDocsPlacement(projectDir, template, docsEnabled) {
607
+ if (!docsEnabled)
608
+ return "spine";
609
+ if (template !== "astro-emdash")
610
+ return "spine";
611
+ const spec = readSpecPublicDocumentation(projectDir);
612
+ return spec.documentation === "public docs on the public site" && spec.docsExposure === "public" ? "site" : "spine";
613
+ }
614
+ function readSpecPublicDocumentation(projectDir) {
615
+ const file = join(projectDir, CANONICAL_SPEC_PATH);
616
+ if (!existsSync(file))
617
+ return {};
618
+ const source = readFileSync(file, "utf8");
619
+ return {
620
+ publicSurface: specLine(source, "Public surface"),
621
+ documentation: specLine(source, "Documentation"),
622
+ docsExposure: specLine(source, "Docs exposure")
623
+ };
624
+ }
625
+ function specLine(source, label) {
626
+ const match = source.match(new RegExp(`^${escapeRegExp(label)}:\\s*(.+?)\\s*$`, "mi"));
627
+ return match?.[1]?.trim();
628
+ }
629
+ function frameworkSourceDir(template, localRoot) {
630
+ if (localRoot) {
631
+ const source = join(localRoot, FRAMEWORK_SOURCE_DIRS[template]);
632
+ if (!existsSync(source))
633
+ throw new Error(`Built-in starter ${source} not found in the local raybase repo.`);
634
+ return source;
635
+ }
636
+ const bundled = join(packageRoot, "templates", template);
637
+ if (existsSync(bundled))
638
+ return bundled;
639
+ throw new Error(`Bundled starter for "${template}" is missing. Reinstall create-raybase or pass --local-packages.`);
640
+ }
641
+ // iOS home-screen icons must be PNG, so the letter can't be substituted into
642
+ // them like the SVG icons. Instead a pre-baked tile matching the app initial
643
+ // (assets/apple-touch-icons, regenerated by scripts/bake-apple-touch-icons.mjs)
644
+ // replaces the template's stock placeholder.
645
+ function applyAppleTouchIcon(projectDir, appInitial) {
646
+ const target = join(projectDir, "public/icons/apple-touch-icon.png");
647
+ if (!existsSync(target))
648
+ return;
649
+ const tiles = join(packageRoot, "assets/apple-touch-icons");
650
+ const tile = join(tiles, `${appInitial}.png`);
651
+ const stockTile = join(tiles, "default.png");
652
+ if (!existsSync(tile) || !existsSync(stockTile))
653
+ return;
654
+ // A store-app overlay may ship branded icons; only replace the stock tile.
655
+ if (!readFileSync(target).equals(readFileSync(stockTile)))
656
+ return;
657
+ cpSync(tile, target);
658
+ }
659
+ // A pre-existing dev/ planning dir is scaffold-safe when merging the template
660
+ // into it cannot clobber anything: entries colliding with the built-in starter's
661
+ // dev/ payload block the scaffold, except the SPEC docs that
662
+ // readPlanningDocs/restorePlanningDocs round-trip.
663
+ function isScaffoldSafeDevDir(projectDir, sourceDir) {
664
+ const devDir = join(projectDir, "dev");
665
+ if (!existsSync(devDir) || !statSync(devDir).isDirectory())
666
+ return false;
667
+ const templateDevDir = join(sourceDir, "dev");
668
+ const templateEntries = new Set(existsSync(templateDevDir) ? readdirSync(templateDevDir) : []);
669
+ for (const preserved of PLANNING_STUB_DEV_FILES)
670
+ templateEntries.delete(preserved);
671
+ return readdirSync(devDir).every((entry) => !templateEntries.has(entry));
672
+ }
673
+ function readPlanningDocs(projectDir) {
674
+ const docs = new Map();
675
+ for (const relativePath of PLANNING_DOC_PATHS) {
676
+ const file = join(projectDir, relativePath);
677
+ if (existsSync(file) && statSync(file).isFile()) {
678
+ docs.set(relativePath, readFileSync(file, "utf8"));
679
+ }
680
+ }
681
+ return docs;
682
+ }
683
+ function restorePlanningDocs(projectDir, docs) {
684
+ for (const [relativePath, contents] of docs) {
685
+ const file = join(projectDir, relativePath);
686
+ mkdirSync(dirname(file), { recursive: true });
687
+ writeFileSync(file, contents);
688
+ }
689
+ }
690
+ function resolveLocalRoot(value) {
691
+ if (!value)
692
+ return null;
693
+ const root = resolve(value);
694
+ assertLocalRoot(root, "--local-packages");
695
+ return root;
696
+ }
697
+ function sourceCheckoutRoot() {
698
+ const root = resolve(packageRoot, "../..");
699
+ if (!existsSync(join(root, "packages/create-raybase/src/index.ts")))
700
+ return null;
701
+ for (const source of Object.values(FRAMEWORK_SOURCE_DIRS)) {
702
+ if (!existsSync(join(root, source)))
703
+ return null;
704
+ }
705
+ try {
706
+ assertLocalRoot(root, "auto-detected source checkout");
707
+ }
708
+ catch {
709
+ return null;
710
+ }
711
+ return root;
712
+ }
713
+ function assertLocalRoot(root, label) {
714
+ for (const probe of [
715
+ "packages/core/package.json",
716
+ "packages/docs/package.json",
717
+ "packages/guide/package.json",
718
+ "packages/api/package.json",
719
+ "packages/agent-ui/package.json",
720
+ "packages/cli/package.json",
721
+ "skills/raybase-building"
722
+ ]) {
723
+ if (!existsSync(join(root, probe))) {
724
+ throw new Error(`${label}: ${root} does not look like a raybase repo checkout (missing ${probe}).`);
725
+ }
726
+ }
727
+ // link: deps resolve their own dependencies through the repo's install.
728
+ if (!existsSync(join(root, "node_modules"))) {
729
+ throw new Error(`${label}: run \`pnpm install\` in ${root} first (linked packages resolve their dependencies through the repo's node_modules).`);
730
+ }
731
+ }
732
+ // In local mode the built-in starters and skills are read straight from the repo, so
733
+ // they cannot go stale — but the running dist/index.js can. Fail loudly when
734
+ // the repo source no longer matches the build being executed. The comparison
735
+ // is content-based: the build stamps a source-tree signature into
736
+ // dist/.source-hash, because git operations from concurrent checkouts refresh
737
+ // src mtimes without changing content, so an mtime guard false-positives
738
+ // right after a clean build.
739
+ function assertFreshLocalBuild(localRoot) {
740
+ if (!localRoot || process.env.RAYBASE_LOCAL_ALLOW_STALE === "1")
741
+ return;
742
+ const distFile = fileURLToPath(import.meta.url);
743
+ const srcDir = join(localRoot, "packages/create-raybase/src");
744
+ if (!distFile.startsWith(localRoot) || !existsSync(srcDir))
745
+ return;
746
+ const stampFile = join(dirname(distFile), ".source-hash");
747
+ if (existsSync(stampFile)) {
748
+ if (readFileSync(stampFile, "utf8").trim() !== hashSourceTree(srcDir)) {
749
+ throw new Error("create-raybase source differs from the build you are running. Run `pnpm build` in the raybase repo first (or set RAYBASE_LOCAL_ALLOW_STALE=1).");
750
+ }
751
+ return;
752
+ }
753
+ // Builds that predate stamping (or a bare tsc run): mtimes are all we have.
754
+ const srcFile = join(srcDir, "index.ts");
755
+ if (existsSync(srcFile) && statSync(srcFile).mtimeMs > statSync(distFile).mtimeMs) {
756
+ throw new Error("create-raybase source is newer than the build you are running. Run `pnpm build` in the raybase repo first (or set RAYBASE_LOCAL_ALLOW_STALE=1).");
757
+ }
758
+ }
759
+ // Built-in starters may carry repo-relative file: deps (so in-place starter
760
+ // development inside the raybase repo keeps working). Scaffolded projects get
761
+ // them normalized: absolute link: paths in local mode, published semver
762
+ // otherwise, so dependency installation works wherever the project lives.
763
+ // link:, not file:, for local mode — pnpm copies file: deps into its store,
764
+ // which both freezes core edits out of the project and tries to resolve the
765
+ // cli's `@raybase/core@workspace:*` outside a workspace (install error).
766
+ // link: symlinks into the repo, whose own node_modules satisfies everything.
767
+ function normalizeRaybaseDeps(projectDir, localRoot) {
768
+ normalizePackageRaybaseDeps(join(projectDir, "package.json"), localRoot);
769
+ const sitePackage = join(projectDir, "site", "package.json");
770
+ if (existsSync(sitePackage))
771
+ normalizePackageRaybaseDeps(sitePackage, localRoot);
772
+ }
773
+ function normalizePackageRaybaseDeps(file, localRoot) {
774
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
775
+ const sources = localRoot
776
+ ? {
777
+ "@raybase/agent-ui": `link:${join(localRoot, "packages/agent-ui")}`,
778
+ "@raybase/core": `link:${join(localRoot, "packages/core")}`,
779
+ "@raybase/emdash": `link:${join(localRoot, "packages/emdash")}`,
780
+ "@raybase/galley": localGalleyPackageRange(localRoot),
781
+ "@raybase/docs": `link:${join(localRoot, "packages/docs")}`,
782
+ "@raybase/guide": `link:${join(localRoot, "packages/guide")}`,
783
+ "@raybase/api": `link:${join(localRoot, "packages/api")}`,
784
+ "@raybase/cli": `link:${join(localRoot, "packages/cli")}`
785
+ }
786
+ : {
787
+ ...RAYBASE_PACKAGE_RANGES
788
+ };
789
+ let changed = false;
790
+ for (const section of ["dependencies", "devDependencies"]) {
791
+ const deps = parsed[section];
792
+ if (!deps)
793
+ continue;
794
+ for (const [name, source] of Object.entries(sources)) {
795
+ if (deps[name] && deps[name] !== source) {
796
+ deps[name] = source;
797
+ changed = true;
798
+ }
799
+ }
800
+ }
801
+ if (changed)
802
+ writeFileSync(file, `${JSON.stringify(parsed, null, 2)}\n`);
803
+ }
804
+ // Local workerd reads .dev.vars, which FRAMEWORK_EXCLUDES keeps out of the
805
+ // copy (a starter developer's working file may hold real credentials) — so
806
+ // scaffolds get a fresh one with local-mode defaults. Without it the worker
807
+ // inherits production values from wrangler vars (no local persona, and
808
+ // /admin 500s on the missing auth secret).
809
+ function defaultLocalAiMode(template, guideEnabled) {
810
+ return template === "tanstack-start" && guideEnabled ? "live" : "disabled";
811
+ }
812
+ function localAuthSecret() {
813
+ return randomBytes(32).toString("base64url");
814
+ }
815
+ function localBackupSecret() {
816
+ return randomBytes(32).toString("base64url");
817
+ }
818
+ function localApiKeySecret() {
819
+ return randomBytes(32).toString("hex");
820
+ }
821
+ function localHandoffPrivateJwk() {
822
+ const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
823
+ const jwk = privateKey.export({ format: "jwk" });
824
+ jwk.alg = "ES256";
825
+ jwk.use = "sig";
826
+ jwk.kid = `raybase-handoff-${createHash("sha256").update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y })).digest("hex").slice(0, 16)}`;
827
+ return JSON.stringify(jwk);
828
+ }
829
+ function ensureDevVars(projectDir, template, guideEnabled, apiEnabled) {
830
+ const file = join(projectDir, ".dev.vars");
831
+ if (existsSync(file))
832
+ return;
833
+ const aiMode = defaultLocalAiMode(template, guideEnabled);
834
+ const authSecret = localAuthSecret();
835
+ const backupSecret = localBackupSecret();
836
+ const apiSecretLine = apiEnabled ? `RAYBASE_API_KEY_SECRET=${localApiKeySecret()}\n` : "";
837
+ mkdirSync(join(projectDir, ".raybase"), { recursive: true });
838
+ writeFileSync(join(projectDir, ".raybase/backups-key-current"), `${backupSecret}\n`, { mode: 0o600 });
839
+ writeFileSync(join(projectDir, ".raybase/backups-key-retained"), "", { mode: 0o600 });
840
+ if (template === "astro-emdash") {
841
+ const handoffJwk = localHandoffPrivateJwk();
842
+ mkdirSync(join(projectDir, ".raybase"), { recursive: true });
843
+ writeFileSync(join(projectDir, ".raybase/handoff-private-jwk"), `${handoffJwk}\n`, { mode: 0o600 });
844
+ writeFileSync(file, `RAYBASE_ENV=local
845
+ BETTER_AUTH_SECRET=${authSecret}
846
+ BETTER_AUTH_URL=http://localhost:3000
847
+ RAYBASE_BACKUPS_KEY=${backupSecret}
848
+ RAYBASE_HANDOFF_PRIVATE_JWK=${handoffJwk}
849
+ RAYBASE_SITE_ORIGIN=http://127.0.0.1:4321
850
+ RAYBASE_AI_MODE=${aiMode}
851
+ RAYBASE_AI_GATEWAY_ID=
852
+ RAYBASE_AI_GATEWAY_CACHE=
853
+ RAYBASE_AI_GATEWAY_AUTH=
854
+ RAYBASE_AI_MOCK_RESPONSE=
855
+ ${apiSecretLine}
856
+ `);
857
+ return;
858
+ }
859
+ writeFileSync(file, `RAYBASE_ENV=local
860
+ BETTER_AUTH_SECRET=${authSecret}
861
+ BETTER_AUTH_URL=http://localhost:3000
862
+ RAYBASE_BACKUPS_KEY=${backupSecret}
863
+ RAYBASE_AI_MODE=${aiMode}
864
+ RAYBASE_AI_GATEWAY_ID=
865
+ RAYBASE_AI_GATEWAY_CACHE=
866
+ RAYBASE_AI_GATEWAY_AUTH=
867
+ RAYBASE_AI_MOCK_RESPONSE=
868
+ ${apiSecretLine}
869
+ `);
870
+ }
871
+ function assertNode() {
872
+ const major = Number(process.versions.node.split(".")[0]);
873
+ if (major < 20)
874
+ throw new Error("Raybase requires Node.js 20 or newer.");
875
+ }
876
+ function assertStarterNode(sourceDir, label) {
877
+ const packageFile = join(sourceDir, "package.json");
878
+ if (!existsSync(packageFile))
879
+ return;
880
+ let nodeRange;
881
+ try {
882
+ const parsed = JSON.parse(readFileSync(packageFile, "utf8"));
883
+ if (typeof parsed.engines?.node === "string")
884
+ nodeRange = parsed.engines.node.trim();
885
+ }
886
+ catch {
887
+ return;
888
+ }
889
+ if (!nodeRange || satisfiesNodeRange(process.versions.node, nodeRange))
890
+ return;
891
+ throw new Error(`The ${label} starter requires Node.js ${nodeRange}, but this process is running Node.js v${process.versions.node}. ` +
892
+ "Switch Node versions before running create-raybase, then retry.");
893
+ }
894
+ function satisfiesNodeRange(version, range) {
895
+ return range.split("||").some((alternative) => {
896
+ const comparators = alternative.trim().split(/\s+/).filter(Boolean);
897
+ if (comparators.length === 0)
898
+ return true;
899
+ return comparators.every((comparator) => satisfiesComparator(version, comparator));
900
+ });
901
+ }
902
+ function satisfiesComparator(version, comparator) {
903
+ if (comparator === "*" || comparator.toLowerCase() === "x")
904
+ return true;
905
+ const match = comparator.match(/^(>=|>|<=|<|=)?\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
906
+ // The preflight supports the simple comparator ranges used by Raybase's
907
+ // built-in starters. Unknown npm range syntax fails open so pnpm remains the source
908
+ // of truth instead of create-raybase blocking a valid install.
909
+ if (!match)
910
+ return true;
911
+ const [, operator = "=", major, minor = "0", patch = "0"] = match;
912
+ const comparison = compareVersions(version, `${major}.${minor}.${patch}`);
913
+ switch (operator) {
914
+ case ">":
915
+ return comparison > 0;
916
+ case ">=":
917
+ return comparison >= 0;
918
+ case "<":
919
+ return comparison < 0;
920
+ case "<=":
921
+ return comparison <= 0;
922
+ case "=":
923
+ return comparison === 0;
924
+ default:
925
+ return comparison === 0;
926
+ }
927
+ }
928
+ function compareVersions(left, right) {
929
+ const leftParts = parseVersion(left);
930
+ const rightParts = parseVersion(right);
931
+ for (let index = 0; index < 3; index += 1) {
932
+ const diff = leftParts[index] - rightParts[index];
933
+ if (diff !== 0)
934
+ return diff > 0 ? 1 : -1;
935
+ }
936
+ return 0;
937
+ }
938
+ function parseVersion(value) {
939
+ const match = value.match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
940
+ if (!match)
941
+ return [0, 0, 0];
942
+ return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
943
+ }
944
+ async function checkNetwork() {
945
+ const controller = new AbortController();
946
+ const timeout = setTimeout(() => controller.abort(), 6000);
947
+ try {
948
+ const response = await fetch("https://registry.npmjs.org/create-raybase", {
949
+ method: "HEAD",
950
+ signal: controller.signal
951
+ });
952
+ if (!response.ok && response.status !== 404)
953
+ throw new Error(`npm registry returned ${response.status}`);
954
+ }
955
+ catch (error) {
956
+ throw new Error(`Network check failed: ${error instanceof Error ? error.message : String(error)}`);
957
+ }
958
+ finally {
959
+ clearTimeout(timeout);
960
+ }
961
+ }
962
+ function installSkills(projectDir, template, localRoot, docsEnabled, guideEnabled, apiEnabled) {
963
+ applySkillsSync(projectDir, { framework: template, localRoot, docsEnabled, guideEnabled, apiEnabled });
964
+ }
965
+ // Refresh the installed .agents/skills set in place for the project's framework
966
+ // and enabled modules — first-party `raybase skills sync`. Overwrites local
967
+ // skill edits (reported) and prunes previously stamped skills that left the
968
+ // expected set.
969
+ export function syncProjectSkills(projectDir, options = {}) {
970
+ const framework = detectFramework(projectDir);
971
+ const modules = detectInstalledModules(projectDir);
972
+ const localRoot = options.localRoot !== undefined ? options.localRoot : resolveLocalRoot(process.env.RAYBASE_LOCAL) ?? sourceCheckoutRoot();
973
+ return applySkillsSync(projectDir, {
974
+ framework,
975
+ localRoot,
976
+ docsEnabled: modules.has("docs"),
977
+ guideEnabled: modules.has("guide"),
978
+ apiEnabled: modules.has("api"),
979
+ dryRun: Boolean(options.dryRun)
980
+ });
981
+ }
982
+ // Staleness check for `raybase doctor`: never throws, never writes. Compares
983
+ // the stamped install hashes (or, unstamped, the installed trees) against the
984
+ // bundled skill snapshot. `checked: false` means there is nothing reliable to
985
+ // compare — no installed skills, no resolvable snapshot, or unreadable state.
986
+ export function checkProjectSkills(projectDir) {
987
+ try {
988
+ if (!isDirectoryLike(join(projectDir, ".agents", "skills")))
989
+ return { checked: false };
990
+ const framework = detectFramework(projectDir);
991
+ const modules = detectInstalledModules(projectDir);
992
+ const localRoot = resolveLocalRoot(process.env.RAYBASE_LOCAL) ?? sourceCheckoutRoot();
993
+ const expected = skillsForFramework(framework, modules.has("docs"), modules.has("guide"), modules.has("api"));
994
+ const prior = readSkillsLock(projectDir);
995
+ const missing = [];
996
+ const stale = [];
997
+ for (const bundle of expected) {
998
+ const source = skillSource(bundle, localRoot);
999
+ if (!isDirectoryLike(source))
1000
+ return { checked: false };
1001
+ const target = join(projectDir, ".agents", "skills", bundle);
1002
+ if (!isDirectoryLike(target)) {
1003
+ missing.push(bundle);
1004
+ continue;
1005
+ }
1006
+ // With a stamp, local edits are respected: only an upstream move of the
1007
+ // bundled skill counts as stale. Without one, compare trees directly.
1008
+ const baseline = prior?.skills[bundle]?.sha256 ?? hashSkillTree(target);
1009
+ if (baseline !== hashSkillTree(source))
1010
+ stale.push(bundle);
1011
+ }
1012
+ const removable = Object.keys(prior?.skills ?? {}).filter((bundle) => !expected.includes(bundle) && pathEntryExists(join(projectDir, ".agents", "skills", bundle)));
1013
+ return { checked: true, framework, stamped: prior !== null, missing, stale, removable };
1014
+ }
1015
+ catch {
1016
+ return { checked: false };
1017
+ }
1018
+ }
1019
+ function applySkillsSync(projectDir, input) {
1020
+ const dryRun = Boolean(input.dryRun);
1021
+ const expected = skillsForFramework(input.framework, input.docsEnabled, input.guideEnabled, input.apiEnabled);
1022
+ const prior = readSkillsLock(projectDir);
1023
+ const report = {
1024
+ ok: true,
1025
+ dryRun,
1026
+ framework: input.framework,
1027
+ modules: { api: input.apiEnabled, docs: input.docsEnabled, guide: input.guideEnabled },
1028
+ added: [],
1029
+ updated: [],
1030
+ removed: [],
1031
+ unchanged: [],
1032
+ localEditsOverwritten: [],
1033
+ lockFile: SKILLS_LOCK_FILE
1034
+ };
1035
+ const lock = {
1036
+ schemaVersion: 1,
1037
+ framework: input.framework,
1038
+ modules: report.modules,
1039
+ skills: {},
1040
+ syncedAt: new Date().toISOString()
1041
+ };
1042
+ for (const bundle of expected) {
1043
+ const source = skillSource(bundle, input.localRoot);
1044
+ if (!existsSync(source)) {
1045
+ throw new Error(`Skills bundle ${bundle} not found at ${source}. Re-run pnpm prepare:create in the raybase repo.`);
1046
+ }
1047
+ const sourceHash = hashSkillTree(source);
1048
+ const target = join(projectDir, ".agents", "skills", bundle);
1049
+ const installedHash = isDirectoryLike(target) ? hashSkillTree(target) : null;
1050
+ if (installedHash === null) {
1051
+ report.added.push(bundle);
1052
+ }
1053
+ else if (installedHash === sourceHash) {
1054
+ report.unchanged.push(bundle);
1055
+ }
1056
+ else {
1057
+ report.updated.push(bundle);
1058
+ const stamped = prior?.skills[bundle]?.sha256;
1059
+ if (stamped && stamped !== installedHash)
1060
+ report.localEditsOverwritten.push(bundle);
1061
+ }
1062
+ lock.skills[bundle] = { sha256: sourceHash };
1063
+ if (dryRun)
1064
+ continue;
1065
+ if (installedHash !== sourceHash) {
1066
+ mkdirSync(dirname(target), { recursive: true });
1067
+ // Remove-then-copy so files deleted upstream do not linger in the app.
1068
+ rmSync(target, { recursive: true, force: true });
1069
+ cpSync(source, target, { recursive: true });
1070
+ }
1071
+ ensureDirectorySymlink(join(projectDir, ".claude", "skills", bundle), target);
1072
+ }
1073
+ // Prune only what a previous install stamped: user-authored skills in
1074
+ // .agents/skills are invisible to the lock and stay untouched.
1075
+ for (const bundle of Object.keys(prior?.skills ?? {})) {
1076
+ if (expected.includes(bundle))
1077
+ continue;
1078
+ const target = join(projectDir, ".agents", "skills", bundle);
1079
+ if (!pathEntryExists(target))
1080
+ continue;
1081
+ report.removed.push(bundle);
1082
+ if (dryRun)
1083
+ continue;
1084
+ rmSync(target, { recursive: true, force: true });
1085
+ const link = join(projectDir, ".claude", "skills", bundle);
1086
+ if (pathEntryExists(link))
1087
+ rmSync(link, { recursive: true, force: true });
1088
+ }
1089
+ if (!dryRun)
1090
+ writeSkillsLock(projectDir, lock);
1091
+ return report;
1092
+ }
1093
+ function readSkillsLock(projectDir) {
1094
+ const file = join(projectDir, SKILLS_LOCK_FILE);
1095
+ if (!existsSync(file))
1096
+ return null;
1097
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
1098
+ if (Number(parsed.schemaVersion) > 1)
1099
+ throw new Error(`${SKILLS_LOCK_FILE} schemaVersion is newer than this create-raybase. Upgrade create-raybase.`);
1100
+ if (parsed.schemaVersion !== 1 || !parsed.skills || typeof parsed.skills !== "object") {
1101
+ throw new Error(`${SKILLS_LOCK_FILE} is not a valid Raybase skills lock file.`);
1102
+ }
1103
+ return parsed;
1104
+ }
1105
+ function writeSkillsLock(projectDir, lock) {
1106
+ const file = join(projectDir, SKILLS_LOCK_FILE);
1107
+ mkdirSync(dirname(file), { recursive: true });
1108
+ writeFileSync(file, stableJson(lock));
1109
+ }
1110
+ // Deterministic tree hash: sorted POSIX-relative paths + file contents.
1111
+ function hashSkillTree(dir) {
1112
+ const hash = createHash("sha256");
1113
+ const files = walk(dir)
1114
+ .map((file) => relative(dir, file).split(sep).join("/"))
1115
+ .sort();
1116
+ for (const file of files) {
1117
+ hash.update(file);
1118
+ hash.update("\0");
1119
+ hash.update(readFileSync(join(dir, ...file.split("/"))));
1120
+ hash.update("\0");
1121
+ }
1122
+ return hash.digest("hex");
1123
+ }
1124
+ function isDirectoryLike(path) {
1125
+ try {
1126
+ return statSync(path).isDirectory();
1127
+ }
1128
+ catch {
1129
+ return false;
1130
+ }
1131
+ }
1132
+ function skillsForFramework(template, docsEnabled, guideEnabled, apiEnabled) {
1133
+ return [
1134
+ ...FRAMEWORK_SKILLS[template],
1135
+ ...(docsEnabled ? [DOCS_SKILL] : []),
1136
+ ...(guideEnabled ? [GUIDE_SKILL] : []),
1137
+ ...(apiEnabled ? [API_SKILL] : [])
1138
+ ];
1139
+ }
1140
+ function skillSource(bundle, localRoot) {
1141
+ if (bundle === API_SKILL && localRoot)
1142
+ return join(localRoot, "packages/api/skills", bundle);
1143
+ return localRoot ? join(localRoot, "skills", bundle) : join(packageRoot, "skills", bundle);
1144
+ }
1145
+ function ensureDirectorySymlink(link, target) {
1146
+ if (pathEntryExists(link)) {
1147
+ const stat = lstatSync(link);
1148
+ if (stat.isSymbolicLink() && resolve(dirname(link), readlinkSync(link)) === target)
1149
+ return;
1150
+ rmSync(link, { recursive: true, force: true });
1151
+ }
1152
+ mkdirSync(dirname(link), { recursive: true });
1153
+ symlinkSync(relativeLinkTarget(link, target), link, "dir");
1154
+ }
1155
+ function ensureFileSymlink(link, target, replaceExistingFile) {
1156
+ if (pathEntryExists(link)) {
1157
+ const stat = lstatSync(link);
1158
+ if (stat.isSymbolicLink()) {
1159
+ if (resolve(dirname(link), readlinkSync(link)) === target)
1160
+ return;
1161
+ rmSync(link, { recursive: true, force: true });
1162
+ mkdirSync(dirname(link), { recursive: true });
1163
+ symlinkSync(relativeLinkTarget(link, target), link, "file");
1164
+ return;
1165
+ }
1166
+ const canReplaceFile = !stat.isDirectory() && (replaceExistingFile || readFileSync(link, "utf8") === readFileSync(target, "utf8"));
1167
+ if (!canReplaceFile)
1168
+ return;
1169
+ rmSync(link, { recursive: true, force: true });
1170
+ }
1171
+ mkdirSync(dirname(link), { recursive: true });
1172
+ symlinkSync(relativeLinkTarget(link, target), link, "file");
1173
+ }
1174
+ function relativeLinkTarget(link, target) {
1175
+ return relative(dirname(link), target).split(sep).join("/");
1176
+ }
1177
+ function pathEntryExists(path) {
1178
+ try {
1179
+ lstatSync(path);
1180
+ return true;
1181
+ }
1182
+ catch (error) {
1183
+ if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
1184
+ return false;
1185
+ throw error;
1186
+ }
1187
+ }
1188
+ function ensureAgentInstructions(projectDir, template, docsEnabled, guideEnabled, apiEnabled) {
1189
+ const agentsFile = join(projectDir, "AGENTS.md");
1190
+ const claudeFile = join(projectDir, "CLAUDE.md");
1191
+ const docsPlacement = docsEnabled ? currentDocsPlacement(projectDir) : "spine";
1192
+ const block = defaultAgentBlock(template, docsEnabled, guideEnabled, apiEnabled, docsPlacement);
1193
+ const createdFromClaude = !existsSync(agentsFile) && pathEntryExists(claudeFile) && !lstatSync(claudeFile).isSymbolicLink();
1194
+ if (!existsSync(agentsFile)) {
1195
+ writeFileSync(agentsFile, createdFromClaude ? readFileSync(claudeFile, "utf8") : block);
1196
+ }
1197
+ const existing = readFileSync(agentsFile, "utf8");
1198
+ if (!existing.includes("Raybase conventions")) {
1199
+ writeFileSync(agentsFile, `${existing.trim()}\n\n${block}`);
1200
+ }
1201
+ ensureFileSymlink(claudeFile, agentsFile, createdFromClaude);
1202
+ }
1203
+ function defaultAgentBlock(template, docsEnabled, guideEnabled, apiEnabled, docsPlacement) {
1204
+ const docsPath = template === "astro-emdash" && docsPlacement === "site" ? "site/content/docs" : "content/docs";
1205
+ const sourceRoot = template === "react-router" ? "app" : "src";
1206
+ const docsLine = docsEnabled ? `- /docs lives in ${docsPath}; use .agents/skills/raybase-docs-writing/SKILL.md before changing docs.\n` : "";
1207
+ const guideLine = guideEnabled
1208
+ ? `- Guide is enabled; use .agents/skills/raybase-guide/SKILL.md before changing ${sourceRoot}/guide or app workflows. Keep Guide context current, and expose only intentional workflows through narrow Guide actions.\n`
1209
+ : "";
1210
+ const apiLine = apiEnabled ? "- API is enabled; use .agents/skills/raybase-api/SKILL.md before exposing external HTTP operations.\n" : "";
1211
+ const frameworkLine = template === "react-router"
1212
+ ? "Routes are React Router file routes in app/routes; Raybase owns /login, /setup, /invite, /admin, /api and /mcp ahead of the router (workers/app.ts)."
1213
+ : "For TanStack Start route/layout/framework work, read .agents/skills/raybase-tanstack-start/SKILL.md.";
1214
+ return `# Raybase conventions
1215
+
1216
+ Use the raybase-* skills in .agents/skills before changing this app. ${frameworkLine} Claude Code compatibility links live in .claude/skills.
1217
+
1218
+ Commands:
1219
+ - raybase dev
1220
+ - raybase doctor
1221
+ - raybase migrate
1222
+ - raybase deploy
1223
+ - raybase backup
1224
+ - raybase invite --owner
1225
+
1226
+ ${docsLine}${guideLine}${apiLine}
1227
+ Access:
1228
+ - \`dev/SPEC.md\` must contain \`Signup mode\`, \`Cloudflare email capability\`, \`Auth email features\`, \`Invite delivery\`, and \`Password recovery\` lines before implementation.
1229
+ - Default to \`Signup mode: invite-only\`, \`Cloudflare email capability: free-compatible\`, \`Auth email features: none\`, \`Invite delivery: admin-shared links\`, and \`Password recovery: admin-assisted\`.
1230
+ - Public signup is controlled by \`appConfig.auth.signupMode\`, not \`auth.publicRoutes\`. Use \`"public"\` for provider and password signup, or \`"provider-only"\` for provider signup with the password door closed.
1231
+ - Both public signup modes create normal \`user\` users only; Raybase \`/admin\` remains invite/operator-only. Password sign-in stays available to existing accounts in every mode.
1232
+ - Password-based public signup, password reset, emailed invites, welcome email, and magic links require owner-confirmed Workers Paid plus Cloudflare Email Sending/domain onboarding and \`Cloudflare email capability: transactional-email\`. Provider-only signup needs no auth email because the provider verifies the email.
1233
+ - Cloudflare verified destination addresses are only for operator/admin notifications or intentional test sends; do not treat them as user verification, password reset, invite email, magic-link auth, or public signup.
1234
+
1235
+ Living planning docs:
1236
+ - Write \`dev/SPEC.md\` and \`dev/SPEC-OVERVIEW.md\` together before asking for approval; capture why the app exists and what success looks like when that is not already clear. Present the overview inline in the approval message and link \`dev/SPEC.md\` as the full spec.
1237
+ - Read \`dev/SPEC.md\`, \`dev/SPEC-OVERVIEW.md\`, and \`dev/CODEBASE-MAP.md\` before substantial product or architecture work.
1238
+ - Update them when the product story, business value, or architecture changes; skip churn for tiny fixes.
1239
+ - Use \`dev/features/<feature-slug>/\` for temporary feature proposals, then archive implemented proposals under \`dev/features/archive/\` after folding durable facts into the canonical planning docs.
1240
+
1241
+ Prohibitions:
1242
+ - Do not add custom auth.
1243
+ - Do not import or use unsafeDb.
1244
+ - Do not deploy without raybase doctor passing.
1245
+ - Do not change schema outside ${sourceRoot}/db/schema.ts plus raybase migrate.
1246
+ `;
1247
+ }
1248
+ function ensureSpec(projectDir, appName, template) {
1249
+ const file = join(projectDir, CANONICAL_SPEC_PATH);
1250
+ if (existsSync(file))
1251
+ return;
1252
+ mkdirSync(dirname(file), { recursive: true });
1253
+ if (template === "astro-emdash") {
1254
+ writeFileSync(file, `# ${appName} Spec
1255
+
1256
+ Status: Draft placeholder - not approved for implementation.
1257
+
1258
+ This file is the owner-facing source of truth for the Raybase + Astro/EmDash content site the agent will build. Replace this placeholder with an approved plain-language spec before changing content collections, Galley templates, public pages, Raybase Actions, jobs, docs, Guide, MCP, or deployment wiring.
1259
+
1260
+ ## Content Site Purpose And Audience
1261
+
1262
+ TBD
1263
+
1264
+ Describe who reads the public site, what the site must communicate or publish, and what success looks like.
1265
+
1266
+ ## Access
1267
+
1268
+ Signup mode: invite-only
1269
+ Cloudflare email capability: free-compatible
1270
+ Auth email features: none
1271
+ Invite delivery: admin-shared links
1272
+ Password recovery: admin-assisted
1273
+
1274
+ Default: only invited users can sign in. For provider and password signup, use
1275
+ \`Signup mode: public self-signup\` with \`auth.signupMode: "public"\`. For provider
1276
+ signup with the password door closed, use \`Signup mode: provider-only
1277
+ self-signup\` with \`auth.signupMode: "provider-only"\`. Both public modes create
1278
+ normal \`user\` users only; password sign-in stays available to existing accounts,
1279
+ and Raybase \`/admin\` remains invite/operator-only.
1280
+
1281
+ Raybase spine access is invite-only by default. EmDash admin access is reached through a Raybase-minted handoff token and an HttpOnly content-worker cookie that expires with it. Public visitors can read published content only.
1282
+
1283
+ ## Public Surface / Documentation
1284
+
1285
+ Public surface: public Astro/EmDash site
1286
+ Documentation: docs inside the app
1287
+ Docs exposure: public
1288
+
1289
+ Docs are public by default. With docs placement \`spine\` the spine serves
1290
+ \`/docs\` and \`/docs/api/search\` to signed-out visitors; with \`Documentation:
1291
+ public docs on the public site\` they move to the public Astro site.
1292
+ \`Docs exposure: signed-in only\` is a choice for \`spine\` placement; write it
1293
+ here only together with the sign-in check the raybase-astro-emdash skill
1294
+ describes.
1295
+
1296
+ ## Content Ownership
1297
+
1298
+ EmDash owns content editing, schema builder, media, drafts, and publishing in its own content D1 database and media R2 bucket. Raybase owns identity, admin/operator surfaces, audit, agents, deploy orchestration, and declared public Raybase Actions.
1299
+
1300
+ ## Pages, Galley Templates, And Media
1301
+
1302
+ TBD
1303
+
1304
+ List the public pages and expected runtime-authored Galley templates. Ordinary public sections should use Galley templates and \`pages.content\` Portable Text blocks rather than new Astro source components.
1305
+
1306
+ ## Raybase Server Islands
1307
+
1308
+ TBD
1309
+
1310
+ List any public Raybase-powered islands. Each island must call an allowlisted public Raybase Action with output validation; content data must never supply arbitrary URLs.
1311
+
1312
+ ## Open Questions
1313
+
1314
+ - What audience, content model, Galley templates, media needs, and public Raybase islands should replace this placeholder?
1315
+ `);
1316
+ return;
1317
+ }
1318
+ writeFileSync(file, `# ${appName} Spec
1319
+
1320
+ Status: Draft placeholder - not approved for implementation.
1321
+
1322
+ This file is the owner-facing source of truth for the app the agent will build. Replace this placeholder with an approved plain-language spec that explains why the app exists and what value it should produce before writing app-specific schema, policies, screens, docs, jobs, notifications, MCP tools, or Store app customizations. Write dev/SPEC-OVERVIEW.md from the same app facts at the same time, paste that overview into the approval message, and link dev/SPEC.md as the full spec.
1323
+
1324
+ ## Purpose And Business Value
1325
+
1326
+ TBD
1327
+
1328
+ Describe the problem this app solves, why that problem matters to the owner and
1329
+ users, and what success should look like.
1330
+
1331
+ Security default: this is an internal app. Only invited users can sign in, and uninvited visitors see a login wall.
1332
+
1333
+ ## Access
1334
+
1335
+ Signup mode: invite-only
1336
+ Cloudflare email capability: free-compatible
1337
+ Auth email features: none
1338
+ Invite delivery: admin-shared links
1339
+ Password recovery: admin-assisted
1340
+
1341
+ Default: only invited users can sign in. For provider and password signup, use
1342
+ \`Signup mode: public self-signup\` with \`auth.signupMode: "public"\`. For
1343
+ provider signup with the password door closed, use \`Signup mode: provider-only
1344
+ self-signup\` with \`auth.signupMode: "provider-only"\`. Both public modes
1345
+ create normal \`user\` users only; password sign-in stays available to existing
1346
+ accounts, and Raybase \`/admin\` remains invite/operator-only.
1347
+
1348
+ The default Cloudflare email capability is Free-compatible: Raybase generates
1349
+ single-use setup and invite links, but admins copy and share invite links
1350
+ manually. There is no self-service password reset, magic-link/passwordless
1351
+ auth, public-signup email verification, invite email, welcome email, or other
1352
+ auth email to arbitrary recipients.
1353
+
1354
+ Use \`Cloudflare email capability: transactional-email\` only after the owner
1355
+ has confirmed Workers Paid plus Cloudflare Email Sending/domain onboarding.
1356
+ Then list only approved \`Auth email features\` from \`password-reset\`,
1357
+ \`invite-email\`, \`welcome-email\`, \`public-signup-email-verification\`, and
1358
+ \`magic-link\`, and align \`Invite delivery\` and \`Password recovery\` with
1359
+ the app config. Cloudflare verified destination addresses may be used for
1360
+ operator/admin notifications or intentional test sends only; they are not a
1361
+ Raybase auth mode for end-user verification, reset, invites, or magic links.
1362
+
1363
+ ## Public Surface / Documentation
1364
+
1365
+ Public surface: none
1366
+ Documentation: in-app docs
1367
+ Docs exposure: public
1368
+
1369
+ Docs are public by default: \`/docs\` and \`/docs/api/search\` answer signed-out
1370
+ visitors. \`Docs exposure: signed-in only\` is a choice; write it here only
1371
+ together with the sign-in check on the docs routes that the framework skill
1372
+ describes.
1373
+
1374
+ ## What The App Does
1375
+
1376
+ TBD
1377
+
1378
+ ## Users And Roles
1379
+
1380
+ TBD
1381
+
1382
+ Use business role names such as manager, approver, or operations. Operator access to /admin is separate from app roles.
1383
+
1384
+ ## Data Model
1385
+
1386
+ TBD
1387
+
1388
+ ## Permissions
1389
+
1390
+ TBD
1391
+
1392
+ Describe who can read, create, update, and delete each kind of record. Every app table must have explicit read, create, update, and delete policies.
1393
+
1394
+ ## Workflows
1395
+
1396
+ TBD
1397
+
1398
+ Describe the important business workflows, approvals, state changes, imports, exports, reminders, and reports the app must support.
1399
+
1400
+ ## Integrations, Files, AI, And MCP
1401
+
1402
+ TBD
1403
+
1404
+ Name any external systems, uploads, generated files, AI/Guide behavior, search, notifications, jobs, or MCP tools the app needs.
1405
+
1406
+ ## Open Questions
1407
+
1408
+ - What owner-approved purpose, business value, users, data, permissions, and workflows should replace this placeholder?
1409
+
1410
+ Agents must stop here until the owner has approved a real spec. Do not infer business value, roles, data, permissions, workflows, Store app fit, docs, jobs, notifications, or MCP tools from this placeholder.
1411
+ `);
1412
+ }
1413
+ function nextSteps(projectDir, template, docsEnabled, guideEnabled, apiEnabled, storeApp) {
1414
+ const storeSteps = storeApp
1415
+ ? [
1416
+ `Store app ${storeApp.manifest.id}@${storeApp.manifest.version} was installed.`,
1417
+ ".raybase/store-app.json records Store provenance.",
1418
+ "Store dev/SPEC.md is a canonical baseline; confirm it is approved as-is or record approved access/signup/email-capability deltas before customization."
1419
+ ]
1420
+ : [];
1421
+ if (template === "astro-emdash") {
1422
+ const docsPlacement = currentDocsPlacement(projectDir);
1423
+ const docsPath = docsPlacement === "site" ? "site/content/docs" : "content/docs";
1424
+ const docsStep = docsPlacement === "site"
1425
+ ? "Docs live at /docs on the public Astro/EmDash site; follow .agents/skills/raybase-docs-writing/SKILL.md before changing site/content/docs."
1426
+ : "Docs live at /docs on the spine; follow .agents/skills/raybase-docs-writing/SKILL.md before changing content/docs.";
1427
+ const guideKnowledge = docsEnabled ? `${docsPath}, content/guide, and site content docs` : "content/guide and site content docs";
1428
+ return [
1429
+ "cd " + projectDir,
1430
+ ...storeSteps,
1431
+ ...(storeApp
1432
+ ? []
1433
+ : [
1434
+ "Replace dev/SPEC.md and dev/SPEC-OVERVIEW.md together: interview the owner, fill in content site audience / Raybase spine access / EmDash D1-R2 ownership / page and Galley template model / Server Island policy, paste the overview into the approval message, link dev/SPEC.md as the full spec, and get approval before content-site changes."
1435
+ ]),
1436
+ "Follow .agents/skills/raybase-astro-emdash/SKILL.md before changing site/",
1437
+ ...(docsEnabled ? [docsStep] : []),
1438
+ ...(guideEnabled
1439
+ ? [`Guide is enabled on the Raybase spine; keep ${guideKnowledge} current, document what Guide can do, add narrow Guide actions for intended workflows, then run raybase guide index after knowledge changes.`]
1440
+ : []),
1441
+ ...(apiEnabled ? ["API is enabled at /api/v1 on the spine; set deployed RAYBASE_API_KEY_SECRET and manage keys from /admin/api."] : []),
1442
+ "After the first raybase deploy, copy the printed content site URL into src/raybase.config.ts appConfig.handoff.resources[].origin before production handoff.",
1443
+ "raybase dev (starts the Raybase spine on :3000 and the Astro/EmDash site on :4321, or the next free port when :4321 is taken)"
1444
+ ];
1445
+ }
1446
+ const guideKnowledge = docsEnabled ? "content/docs and content/guide" : "content/guide";
1447
+ return [
1448
+ "cd " + projectDir,
1449
+ ...storeSteps,
1450
+ ...(storeApp
1451
+ ? []
1452
+ : [
1453
+ "Replace dev/SPEC.md and dev/SPEC-OVERVIEW.md together: interview the owner, fill in access/signup mode / Cloudflare email capability / auth email features / purpose and business value / users / data / permissions / workflows, paste the overview into the approval message, link dev/SPEC.md as the full spec, and get approval before schema or screens."
1454
+ ]),
1455
+ template === "react-router"
1456
+ ? "Follow .agents/skills/raybase-building/SKILL.md; app routes live in app/routes and read the signed-in user with currentUser() from app/raybase.server.ts"
1457
+ : "Follow .agents/skills/raybase-building/SKILL.md and .agents/skills/raybase-tanstack-start/SKILL.md",
1458
+ ...(docsEnabled ? ["Docs live at /docs; follow .agents/skills/raybase-docs-writing/SKILL.md before changing content/docs."] : []),
1459
+ ...(guideEnabled
1460
+ ? [`Guide is enabled; keep ${guideKnowledge} current, document what Guide can do, add narrow Guide actions for intended workflows, then run raybase guide index after knowledge changes.`]
1461
+ : []),
1462
+ ...(apiEnabled ? ["API is enabled at /api/v1; set deployed RAYBASE_API_KEY_SECRET and manage keys from /admin/api."] : []),
1463
+ "raybase dev"
1464
+ ];
1465
+ }
1466
+ function configureDocs(projectDir, template, enabled, placement, localRoot, keep = noKeptFiles) {
1467
+ const packageFile = join(projectDir, "package.json");
1468
+ const parsed = JSON.parse(readFileSync(packageFile, "utf8"));
1469
+ parsed.raybase = {
1470
+ ...(parsed.raybase ?? {}),
1471
+ framework: template,
1472
+ modules: {
1473
+ ...(parsed.raybase?.modules ?? {}),
1474
+ docs: { enabled, package: "@raybase/docs", placement }
1475
+ }
1476
+ };
1477
+ if (!enabled || placement === "site") {
1478
+ parsed.dependencies = parsed.dependencies ?? {};
1479
+ parsed.devDependencies = parsed.devDependencies ?? {};
1480
+ delete parsed.dependencies?.["@raybase/docs"];
1481
+ if (enabled)
1482
+ parsed.dependencies["@raybase/docs"] = localRaybasePackageRange("@raybase/docs", RAYBASE_PACKAGE_RANGES["@raybase/docs"], localRoot);
1483
+ // lucide-react stays: base app components (src/components/ui, _app routes) import it outside docs.
1484
+ for (const name of ["fumadocs-core", "fumadocs-ui"])
1485
+ delete parsed.dependencies?.[name];
1486
+ for (const name of ["fumadocs-mdx", "@types/mdx"])
1487
+ delete parsed.devDependencies?.[name];
1488
+ }
1489
+ writeFileSync(packageFile, `${JSON.stringify(parsed, null, 2)}\n`);
1490
+ if (!enabled) {
1491
+ pruneDocsFiles(projectDir, template);
1492
+ }
1493
+ else if (placement === "site") {
1494
+ pruneDocsFiles(projectDir, template, { keepServerModule: true });
1495
+ copySiteDocsTemplate(projectDir, template, localRoot, keep);
1496
+ configureSiteDocsPackage(projectDir);
1497
+ patchSiteDocsAstroConfig(projectDir, true);
1498
+ ensureSiteSourceIgnored(projectDir);
1499
+ patchDocsServerModule(projectDir, template, placement);
1500
+ }
1501
+ else {
1502
+ patchDocsServerModule(projectDir, template, placement);
1503
+ }
1504
+ }
1505
+ function configureGuide(projectDir, template, enabled, docsEnabled, localRoot, keep = noKeptFiles) {
1506
+ const packageFile = join(projectDir, "package.json");
1507
+ const parsed = JSON.parse(readFileSync(packageFile, "utf8"));
1508
+ parsed.raybase = {
1509
+ ...(parsed.raybase ?? {}),
1510
+ modules: {
1511
+ ...(parsed.raybase?.modules ?? {}),
1512
+ guide: { enabled, package: "@raybase/guide" }
1513
+ }
1514
+ };
1515
+ parsed.dependencies = parsed.dependencies ?? {};
1516
+ if (enabled) {
1517
+ for (const [name, range] of Object.entries(GUIDE_DEPENDENCIES)) {
1518
+ parsed.dependencies[name] = localRaybasePackageRange(name, range, localRoot);
1519
+ }
1520
+ }
1521
+ else {
1522
+ delete parsed.dependencies["@assistant-ui/react"];
1523
+ delete parsed.dependencies["@raybase/agent-ui"];
1524
+ delete parsed.dependencies["@raybase/guide"];
1525
+ }
1526
+ writeFileSync(packageFile, `${JSON.stringify(parsed, null, 2)}\n`);
1527
+ if (enabled) {
1528
+ copyGuideTemplate(projectDir, template, localRoot, keep);
1529
+ patchGuideServerModule(projectDir, template, true);
1530
+ patchGuideWidget(projectDir, template, true);
1531
+ patchGuideCss(projectDir, template, true);
1532
+ enableTemplateAi(projectDir, template);
1533
+ if (!docsEnabled)
1534
+ disableGuideDocsSurface(projectDir, template);
1535
+ }
1536
+ else {
1537
+ disableTemplateAi(projectDir, template);
1538
+ patchGuideCss(projectDir, template, false);
1539
+ pruneGuideFiles(projectDir, template);
1540
+ }
1541
+ }
1542
+ function copySiteDocsTemplate(projectDir, template, localRoot, keep = noKeptFiles) {
1543
+ if (template !== "astro-emdash")
1544
+ return;
1545
+ const sourceRoot = localRoot ? join(localRoot, "packages/docs/templates/astro-emdash") : join(packageRoot, "modules/docs/templates/astro-emdash");
1546
+ const fallbackRoot = join(packageRoot, "templates/astro-emdash");
1547
+ const root = existsSync(sourceRoot) ? sourceRoot : fallbackRoot;
1548
+ for (const rel of ASTRO_EMDASH_SITE_DOCS_FILES) {
1549
+ if (keep.has(rel))
1550
+ continue;
1551
+ const source = join(root, rel);
1552
+ const target = join(projectDir, rel);
1553
+ if (!existsSync(source))
1554
+ throw new Error(`Docs module template file ${rel} is missing at ${source}.`);
1555
+ mkdirSync(dirname(target), { recursive: true });
1556
+ cpSync(source, target);
1557
+ }
1558
+ }
1559
+ function configureSiteDocsPackage(projectDir) {
1560
+ const file = join(projectDir, "site/package.json");
1561
+ if (!existsSync(file))
1562
+ return;
1563
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
1564
+ parsed.dependencies = {
1565
+ ...(parsed.dependencies ?? {}),
1566
+ "fumadocs-core": "16.10.3",
1567
+ "fumadocs-ui": "16.10.3",
1568
+ "lucide-react": "1.18.0"
1569
+ };
1570
+ parsed.devDependencies = {
1571
+ ...(parsed.devDependencies ?? {}),
1572
+ "fumadocs-mdx": "15.0.12",
1573
+ "@types/mdx": "^2.0.14"
1574
+ };
1575
+ writeFileSync(file, `${JSON.stringify(parsed, null, 2)}\n`);
1576
+ }
1577
+ function patchSiteDocsAstroConfig(projectDir, enabled) {
1578
+ const file = join(projectDir, "site/astro.config.mjs");
1579
+ if (!existsSync(file))
1580
+ return;
1581
+ let source = readFileSync(file, "utf8");
1582
+ if (enabled) {
1583
+ if (!source.includes('from "fumadocs-mdx/vite"'))
1584
+ source = ensureImportLine(source, 'import mdx from "fumadocs-mdx/vite";\n');
1585
+ if (!/\bmdx\(\)/.test(source))
1586
+ source = source.replace(/vite:\s*\{\s*/, (match) => `${match}plugins: [mdx()],\n `);
1587
+ }
1588
+ else {
1589
+ source = source.replace(/^import mdx from "fumadocs-mdx\/vite";\n/m, "").replace(/\s*plugins:\s*\[\s*mdx\(\)\s*\],?\n/m, "");
1590
+ }
1591
+ writeFileSync(file, source);
1592
+ }
1593
+ function ensureSiteSourceIgnored(projectDir) {
1594
+ const file = join(projectDir, "site/.gitignore");
1595
+ const source = existsSync(file) ? readFileSync(file, "utf8") : "";
1596
+ if (/(^|\n)\.source\/?(\n|$)/.test(source))
1597
+ return;
1598
+ writeFileSync(file, `${source.replace(/\s*$/, "")}\n.source/\n`);
1599
+ }
1600
+ function patchDocsServerModule(projectDir, template, placement) {
1601
+ const file = join(projectDir, template === "react-router" ? "app/raybase.server.ts" : "src/raybase.server.ts");
1602
+ if (!existsSync(file))
1603
+ return;
1604
+ let source = readFileSync(file, "utf8");
1605
+ source = ensureExactImport(source, "@raybase/docs", "docsModule");
1606
+ const guideEnabled = exactImportPattern("@raybase/guide", "guideModule").test(source);
1607
+ const apiEnabled = exactImportPattern("./api/operations", "api").test(source);
1608
+ source = replaceNamedRegion(source, "raybase:modules", renderModulesRegion({ template, docs: true, guide: guideEnabled, api: apiEnabled, docsPlacement: placement }));
1609
+ source = ensureRaybaseEnvImport(source);
1610
+ writeFileSync(file, source);
1611
+ }
1612
+ function localRaybasePackageRange(name, range, localRoot) {
1613
+ if (!localRoot || !name.startsWith("@raybase/"))
1614
+ return range;
1615
+ if (name === "@raybase/galley")
1616
+ return localGalleyPackageRange(localRoot);
1617
+ return `link:${join(localRoot, "packages", name.split("/")[1] ?? "")}`;
1618
+ }
1619
+ function localGalleyPackageRange(localRoot) {
1620
+ if (!localRoot)
1621
+ return RAYBASE_PACKAGE_RANGES["@raybase/galley"];
1622
+ for (const candidate of [
1623
+ resolve(localRoot, "../galley"),
1624
+ resolve(localRoot, "../../galley"),
1625
+ resolve(localRoot, "../../../galley")
1626
+ ]) {
1627
+ if (existsSync(join(candidate, "package.json")))
1628
+ return `link:${candidate}`;
1629
+ }
1630
+ return RAYBASE_PACKAGE_RANGES["@raybase/galley"];
1631
+ }
1632
+ function copyGuideTemplate(projectDir, template, localRoot, keep = noKeptFiles) {
1633
+ const sourceRoot = guideTemplateRoot(template, localRoot);
1634
+ for (const rel of MODULE_FILES.guide[template]) {
1635
+ if (keep.has(rel))
1636
+ continue;
1637
+ const source = join(sourceRoot, rel);
1638
+ const target = join(projectDir, rel);
1639
+ if (!existsSync(source))
1640
+ throw new Error(`Guide module template file ${rel} is missing at ${source}.`);
1641
+ mkdirSync(dirname(target), { recursive: true });
1642
+ cpSync(source, target);
1643
+ }
1644
+ }
1645
+ function guideTemplateRoot(template, localRoot) {
1646
+ if (localRoot)
1647
+ return join(localRoot, "packages/guide/templates", template);
1648
+ const bundled = join(packageRoot, "modules/guide/templates", template);
1649
+ if (existsSync(bundled))
1650
+ return bundled;
1651
+ return join(packageRoot, "templates", template);
1652
+ }
1653
+ function configureApi(projectDir, template, enabled, localRoot, keep = noKeptFiles) {
1654
+ const packageFile = join(projectDir, "package.json");
1655
+ const parsed = JSON.parse(readFileSync(packageFile, "utf8"));
1656
+ parsed.raybase = {
1657
+ ...(parsed.raybase ?? {}),
1658
+ modules: {
1659
+ ...(parsed.raybase?.modules ?? {}),
1660
+ api: { enabled, package: "@raybase/api" }
1661
+ }
1662
+ };
1663
+ parsed.dependencies = parsed.dependencies ?? {};
1664
+ if (enabled) {
1665
+ parsed.dependencies["@raybase/api"] = localRoot ? `link:${join(localRoot, "packages/api")}` : RAYBASE_PACKAGE_RANGES["@raybase/api"];
1666
+ copyApiTemplate(projectDir, template, localRoot, keep);
1667
+ patchApiServerModule(projectDir, template, true);
1668
+ }
1669
+ else {
1670
+ delete parsed.dependencies["@raybase/api"];
1671
+ pruneApiFiles(projectDir, template);
1672
+ patchApiServerModule(projectDir, template, false);
1673
+ }
1674
+ writeFileSync(packageFile, `${JSON.stringify(parsed, null, 2)}\n`);
1675
+ }
1676
+ function copyApiTemplate(projectDir, template, localRoot, keep = noKeptFiles) {
1677
+ const sourceRoot = apiTemplateRoot(template, localRoot);
1678
+ for (const rel of MODULE_FILES.api[template]) {
1679
+ if (keep.has(rel))
1680
+ continue;
1681
+ const source = join(sourceRoot, rel);
1682
+ const target = join(projectDir, rel);
1683
+ if (!existsSync(source))
1684
+ throw new Error(`API module template file ${rel} is missing at ${source}.`);
1685
+ mkdirSync(dirname(target), { recursive: true });
1686
+ cpSync(source, target);
1687
+ }
1688
+ }
1689
+ function apiTemplateRoot(template, localRoot) {
1690
+ if (localRoot)
1691
+ return join(localRoot, "packages/api/templates", template);
1692
+ const bundled = join(packageRoot, "modules/api/templates", template);
1693
+ if (existsSync(bundled))
1694
+ return bundled;
1695
+ return join(packageRoot, "templates", template);
1696
+ }
1697
+ function pruneApiFiles(projectDir, template) {
1698
+ for (const rel of MODULE_FILES.api[template])
1699
+ rmSync(join(projectDir, rel), { recursive: true, force: true });
1700
+ }
1701
+ function patchApiServerModule(projectDir, template, enabled) {
1702
+ const file = join(projectDir, template === "react-router" ? "app/raybase.server.ts" : "src/raybase.server.ts");
1703
+ if (!existsSync(file))
1704
+ return;
1705
+ let source = readFileSync(file, "utf8");
1706
+ if (enabled)
1707
+ source = ensureExactImport(source, "./api/operations", "api");
1708
+ else
1709
+ source = source.replace(exactImportPattern("./api/operations", "api"), "");
1710
+ const docsEnabled = exactImportPattern("@raybase/docs", "docsModule").test(source);
1711
+ const guideEnabled = exactImportPattern("@raybase/guide", "guideModule").test(source);
1712
+ source = replaceNamedRegion(source, "raybase:modules", renderModulesRegion({ template, docs: docsEnabled, guide: guideEnabled, api: enabled, docsPlacement: currentDocsPlacement(projectDir) }));
1713
+ if (docsEnabled || guideEnabled)
1714
+ source = ensureRaybaseEnvImport(source);
1715
+ writeFileSync(file, source);
1716
+ }
1717
+ function recordScaffoldedModules(projectDir, template, selectedModules, docsPlacement, keep = noKeptFiles) {
1718
+ const packageJson = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
1719
+ const sitePackageJson = docsPlacement === "site" && existsSync(join(projectDir, "site/package.json"))
1720
+ ? JSON.parse(readFileSync(join(projectDir, "site/package.json"), "utf8"))
1721
+ : {};
1722
+ const now = new Date().toISOString();
1723
+ const modules = {};
1724
+ for (const id of selectedModules) {
1725
+ const moduleFiles = id === "docs" && template === "astro-emdash" && docsPlacement === "site" ? [...ASTRO_EMDASH_SITE_DOCS_FILES] : MODULE_FILES[id][template];
1726
+ const files = moduleFiles
1727
+ .filter((file) => existsSync(join(projectDir, file)))
1728
+ .map((file) => {
1729
+ const sha = sha256File(join(projectDir, file));
1730
+ return {
1731
+ installedSha256: sha,
1732
+ // A file the starter supplies in place of the module's is the app's own.
1733
+ mode: keep.has(file) ? "editable" : moduleFileMode(id, template, file),
1734
+ path: file,
1735
+ sourceSha256: sha
1736
+ };
1737
+ });
1738
+ const dependencySource = id === "docs" && docsPlacement === "site" ? { ...(packageJson.dependencies ?? {}), ...(sitePackageJson.dependencies ?? {}) } : packageJson.dependencies;
1739
+ const devDependencySource = id === "docs" && docsPlacement === "site" ? { ...(packageJson.devDependencies ?? {}), ...(sitePackageJson.devDependencies ?? {}) } : packageJson.devDependencies;
1740
+ modules[id] = {
1741
+ commands: MODULE_COMMANDS[id],
1742
+ dependencies: moduleDependencyRecord(dependencySource, id),
1743
+ devDependencies: moduleDependencyRecord(devDependencySource, id),
1744
+ doctorHooks: [id],
1745
+ enabled: true,
1746
+ files,
1747
+ id,
1748
+ ...(id === "docs" ? { placement: docsPlacement } : {}),
1749
+ installedAt: now,
1750
+ nextSteps: id === "guide"
1751
+ ? [
1752
+ `Keep ${docsPlacement === "site" ? "site/content/docs" : "content/docs"} and content/guide current with what the app does and what Guide can do.`,
1753
+ "Add narrow Guide actions for intended user workflows, then run raybase guide index after knowledge changes.",
1754
+ "Run raybase doctor."
1755
+ ]
1756
+ : ["Commit .raybase/modules.json with the app.", "Run raybase doctor."],
1757
+ packageName: MODULE_PACKAGES[id],
1758
+ skills: MODULE_SKILLS[id],
1759
+ template,
1760
+ updatedAt: now,
1761
+ version: "0.1.0"
1762
+ };
1763
+ }
1764
+ const file = join(projectDir, ".raybase/modules.json");
1765
+ mkdirSync(dirname(file), { recursive: true });
1766
+ writeFileSync(file, stableJson({ schemaVersion: 1, updatedAt: now, modules }));
1767
+ }
1768
+ function moduleDependencyRecord(dependencies, id) {
1769
+ const names = id === "docs"
1770
+ ? ["@raybase/docs", "fumadocs-core", "fumadocs-ui", "lucide-react", "fumadocs-mdx", "@types/mdx"]
1771
+ : id === "guide"
1772
+ ? ["@assistant-ui/react", "@raybase/agent-ui", "@raybase/guide", "lucide-react"]
1773
+ : ["@raybase/api"];
1774
+ return Object.fromEntries(names.flatMap((name) => (dependencies?.[name] ? [[name, dependencies[name]]] : [])));
1775
+ }
1776
+ function enableTemplateAi(projectDir, template) {
1777
+ const file = join(projectDir, "wrangler.jsonc");
1778
+ const source = readFileSync(file, "utf8");
1779
+ const parsed = parse(source);
1780
+ if (!parsed.ai) {
1781
+ writeFileSync(file, editJsoncValue(source, ["ai"], { binding: "AI" }));
1782
+ }
1783
+ if (template === "tanstack-start") {
1784
+ const latest = readFileSync(file, "utf8");
1785
+ writeFileSync(file, removeLocalAiPlaceholder(editJsoncValue(latest, ["env", "local-dev", "ai"], { binding: "AI", remote: true })));
1786
+ }
1787
+ enableTemplateAiConfig(projectDir, template);
1788
+ }
1789
+ function enableTemplateAiConfig(projectDir, template) {
1790
+ const file = join(projectDir, template === "react-router" ? "app/db/schema.ts" : "src/raybase.config.ts");
1791
+ if (!existsSync(file))
1792
+ return;
1793
+ const source = readFileSync(file, "utf8");
1794
+ if (/^\s*ai\s*:/m.test(source))
1795
+ return;
1796
+ // Keeps the Gateway and BYOK hints in the template's comment above the block.
1797
+ let next = source.replace(/\n\s*\/\/ To enable user-facing AI (?:chat )?features, run `raybase ai enable`\.\n([\s\S]*?)[ \t]*\/\/ ai: \{[\s\S]*?\n\s*\/\/ \}\n?/m, (_match, hints) => `\n${hints}${DEFAULT_AI_CONFIG_BLOCK}\n`);
1798
+ if (next === source && template === "react-router") {
1799
+ next = source.replace(/realtime:\s*\{\s*enabled:\s*true\s*\}/, (match) => `${match},\n${DEFAULT_AI_CONFIG_BLOCK}`);
1800
+ }
1801
+ if (next === source) {
1802
+ next = source.replace(/\n\}\s+satisfies\s+RaybaseConfig;/, `,\n${DEFAULT_AI_CONFIG_BLOCK}\n} satisfies RaybaseConfig;`);
1803
+ }
1804
+ if (next !== source)
1805
+ writeFileSync(file, next);
1806
+ }
1807
+ function configureAiDefaultModel(projectDir, template, model) {
1808
+ const file = join(projectDir, template === "react-router" ? "app/db/schema.ts" : "src/raybase.config.ts");
1809
+ if (!existsSync(file))
1810
+ return;
1811
+ const source = readFileSync(file, "utf8");
1812
+ const escaped = JSON.stringify(model);
1813
+ const existingModelPattern = /(\n\s*defaults:\s*\{\n)(\s*)model:\s*"[^"]*",/m;
1814
+ let next = source.replace(existingModelPattern, `$1$2model: ${escaped},`);
1815
+ if (!existingModelPattern.test(source)) {
1816
+ next = source.replace(/(\n\s*defaults:\s*\{\n)/m, `$1 model: ${escaped},\n`);
1817
+ }
1818
+ if (next !== source)
1819
+ writeFileSync(file, next);
1820
+ }
1821
+ async function resolveRecommendedGuideAiModel(input) {
1822
+ if (!input.offline) {
1823
+ const remote = await fetchRecommendedGuideAiModel().catch(() => null);
1824
+ if (remote)
1825
+ return remote;
1826
+ }
1827
+ return bundledRecommendedGuideAiModel(input.localRoot) ?? FALLBACK_RECOMMENDED_GUIDE_MODEL;
1828
+ }
1829
+ async function fetchRecommendedGuideAiModel() {
1830
+ const response = await fetch(RECOMMENDED_MODELS_URL, { headers: { accept: "application/json" } });
1831
+ if (!response.ok)
1832
+ return null;
1833
+ return recommendedGuideAiModelFromManifest(await response.json());
1834
+ }
1835
+ function bundledRecommendedGuideAiModel(localRoot) {
1836
+ const candidates = [
1837
+ localRoot ? join(localRoot, "apps/landing/models/recommended.json") : null,
1838
+ join(packageRoot, "models/recommended.json")
1839
+ ].filter((candidate) => Boolean(candidate));
1840
+ for (const candidate of candidates) {
1841
+ if (!existsSync(candidate))
1842
+ continue;
1843
+ const model = recommendedGuideAiModelFromManifest(JSON.parse(readFileSync(candidate, "utf8")));
1844
+ if (model)
1845
+ return model;
1846
+ }
1847
+ return null;
1848
+ }
1849
+ function recommendedGuideAiModelFromManifest(value) {
1850
+ if (!value || typeof value !== "object")
1851
+ return null;
1852
+ const manifest = value;
1853
+ if (manifest.schemaVersion !== 1)
1854
+ return null;
1855
+ const model = manifest.defaults?.guide?.model ?? manifest.defaults?.chat?.model;
1856
+ return typeof model === "string" && model.trim() ? model.trim() : null;
1857
+ }
1858
+ function disableTemplateAi(projectDir, template) {
1859
+ const wranglerFile = join(projectDir, "wrangler.jsonc");
1860
+ replaceInFile(wranglerFile, [
1861
+ [/,\n\s*"ai":\s*\{\n\s*"binding":\s*"AI"\n\s*\}/m, ""],
1862
+ [/\n\s*"ai":\s*\{\n\s*"binding":\s*"AI"\n\s*\},/m, "\n"]
1863
+ ]);
1864
+ if (template === "tanstack-start") {
1865
+ const latest = readFileSync(wranglerFile, "utf8");
1866
+ writeFileSync(wranglerFile, editJsoncValue(latest, ["env", "local-dev", "ai"], undefined));
1867
+ }
1868
+ const configFile = join(projectDir, template === "react-router" ? "app/db/schema.ts" : "src/raybase.config.ts");
1869
+ replaceInFile(configFile, [
1870
+ [/\n\s*ai:\s*\{\n\s*enabled:\s*true,[\s\S]*?\n\s*maxConversationMessages:\s*40\n\s*\}\n\s*\},?/m, ""]
1871
+ ]);
1872
+ if (existsSync(configFile)) {
1873
+ const source = readFileSync(configFile, "utf8");
1874
+ if (!/To enable user-facing AI (?:chat )?features/.test(source)) {
1875
+ const next = source.replace(/\n\s*\/\/ To add app-specific user-facing agents, define them in src\/ai\/agents\.ts and pass\n\s*\/\/ agents to createRaybaseApp in src\/raybase\.server\.ts\./m, `\n${AI_CONFIG_PLACEHOLDER}`);
1876
+ if (next !== source)
1877
+ writeFileSync(configFile, next);
1878
+ }
1879
+ }
1880
+ }
1881
+ function pruneDocsFiles(projectDir, template, options = {}) {
1882
+ const files = template === "react-router"
1883
+ ? [
1884
+ "source.config.ts",
1885
+ "content",
1886
+ "app/components/mdx.tsx",
1887
+ "app/lib/source.ts",
1888
+ "app/lib/layout.shared.tsx",
1889
+ "app/routes/docs.tsx",
1890
+ "app/routes/docs.$.tsx",
1891
+ "app/routes/docs.api.search.ts"
1892
+ ]
1893
+ : [
1894
+ "source.config.ts",
1895
+ "content",
1896
+ "src/components/docs-page-actions.tsx",
1897
+ "src/components/mdx.tsx",
1898
+ "src/lib/docs-server.ts",
1899
+ "src/lib/llm-text.ts",
1900
+ "src/lib/source.ts",
1901
+ "src/lib/layout.shared.tsx",
1902
+ "src/docs",
1903
+ "src/styles-docs.css",
1904
+ "src/routes/docs.index.tsx",
1905
+ "src/routes/docs.tsx",
1906
+ "src/routes/docs"
1907
+ ];
1908
+ for (const file of files)
1909
+ rmSync(join(projectDir, file), { recursive: true, force: true });
1910
+ if (!options.keepServerModule)
1911
+ removeServerModule(projectDir, template, "docs");
1912
+ replaceInFile(join(projectDir, template === "react-router" ? "app/db/schema.ts" : "src/raybase.config.ts"), [
1913
+ [/\n\s*docs:\s*\{[\s\S]*?\n\s*\},/m, ""]
1914
+ ]);
1915
+ replaceInFile(join(projectDir, template === "react-router" ? "app/app.css" : "src/styles.css"), [
1916
+ [/^\/\* Keep after app Tailwind integrations so Fumadocs layout utilities win the cascade in Vite dev\. \*\/\n/m, ""],
1917
+ [/^@import "fumadocs-ui\/style\.css";\n/m, ""],
1918
+ [/^@import "fumadocs-ui\/css\/neutral\.css";\n/m, ""],
1919
+ [/^@import "fumadocs-ui\/css\/preset\.css";\n/m, ""]
1920
+ ]);
1921
+ if (template === "tanstack-start") {
1922
+ replaceInFile(join(projectDir, "src/routes/__root.tsx"), [
1923
+ [/^import \{ RootProvider \} from "fumadocs-ui\/provider\/tanstack";\n/m, ""],
1924
+ [
1925
+ / <RootProvider search=\{\{ options: \{ api: "\/docs\/api\/search" \} \}\}>\n \{devServerSsr \? <LoadingShell \/> : <Outlet \/>\}\n <\/RootProvider>/m,
1926
+ " {devServerSsr ? <LoadingShell /> : <Outlet />}"
1927
+ ]
1928
+ ]);
1929
+ }
1930
+ replaceInFile(join(projectDir, "vite.config.ts"), [
1931
+ [/^import mdx from "fumadocs-mdx\/vite";\n/m, ""],
1932
+ [/\bmdx\(\),\s*/g, ""]
1933
+ ]);
1934
+ replaceInFile(join(projectDir, "AGENTS.md"), [
1935
+ [/^- `?\/docs`? lives in `?content\/docs`?; use `?\.(?:agents|claude)\/skills\/raybase-docs-writing\/SKILL\.md`? before changing docs\.\n/m, ""],
1936
+ [/^- Fumadocs is served by the app at `?\/docs`?; search is served at `?\/docs\/api\/search`?\.\n/m, ""],
1937
+ [/^- `?\/docs`? is a public, non-embedded React Router docs site outside `?\/app`?; search is served at `?\/docs\/api\/search`?, not `?\/api\/search`?\.\n/m, ""]
1938
+ ]);
1939
+ replaceInFile(join(projectDir, template === "react-router" ? "app/routes/_index.tsx" : "src/routes/_app/index.tsx"), [
1940
+ [/\n\s*<a className="[^"]*" href="\/docs" data-raybase-docs-nav>\n\s*Docs\n\s*<\/a>/m, ""]
1941
+ ]);
1942
+ }
1943
+ function pruneGuideFiles(projectDir, template) {
1944
+ const files = template === "react-router"
1945
+ ? ["app/components/guide-widget.tsx", "app/guide"]
1946
+ : ["src/components/guide-widget.tsx", "src/guide"];
1947
+ for (const file of files)
1948
+ rmSync(join(projectDir, file), { recursive: true, force: true });
1949
+ patchGuideServerModule(projectDir, template, false);
1950
+ patchGuideWidget(projectDir, template, false);
1951
+ }
1952
+ function disableGuideDocsSurface(projectDir, template) {
1953
+ const file = join(projectDir, template === "react-router" ? "app/guide/config.ts" : "src/guide/config.ts");
1954
+ replaceInFile(file, [
1955
+ [/docs: \{ enabled: true, audience: "signed-in" \}/, 'docs: { enabled: false, audience: "signed-in" }']
1956
+ ]);
1957
+ }
1958
+ function patchGuideServerModule(projectDir, template, enabled) {
1959
+ const file = join(projectDir, template === "react-router" ? "app/raybase.server.ts" : "src/raybase.server.ts");
1960
+ if (!existsSync(file))
1961
+ return;
1962
+ let source = readFileSync(file, "utf8");
1963
+ if (enabled) {
1964
+ source = ensureExactImport(source, "@raybase/guide", "guideModule");
1965
+ source = ensureExactImport(source, "./guide/actions", "guideActions");
1966
+ source = ensureExactImport(source, "./guide/config", "guideConfig");
1967
+ source = ensureExactImport(source, "./guide/corpus", "guideCorpus");
1968
+ }
1969
+ else {
1970
+ source = source
1971
+ .replace(exactImportPattern("@raybase/guide", "guideModule"), "")
1972
+ .replace(exactImportPattern("./guide/actions", "guideActions"), "")
1973
+ .replace(exactImportPattern("./guide/config", "guideConfig"), "")
1974
+ .replace(exactImportPattern("./guide/corpus", "guideCorpus"), "");
1975
+ }
1976
+ const docsEnabled = exactImportPattern("@raybase/docs", "docsModule").test(source);
1977
+ const apiEnabled = exactImportPattern("./api/operations", "api").test(source);
1978
+ source = replaceNamedRegion(source, "raybase:modules", renderModulesRegion({ template, docs: docsEnabled, guide: enabled, api: apiEnabled, docsPlacement: currentDocsPlacement(projectDir) }));
1979
+ if (docsEnabled || enabled)
1980
+ source = ensureRaybaseEnvImport(source);
1981
+ writeFileSync(file, source);
1982
+ }
1983
+ function patchGuideWidget(projectDir, template, enabled) {
1984
+ const file = join(projectDir, template === "react-router" ? "app/root.tsx" : "src/routes/__root.tsx");
1985
+ if (!existsSync(file))
1986
+ return;
1987
+ let source = readFileSync(file, "utf8");
1988
+ const importLine = template === "react-router" ? 'import { GuideWidget } from "./components/guide-widget";\n' : 'import { GuideWidget } from "../components/guide-widget";\n';
1989
+ const renderLine = template === "react-router" ? "<GuideWidget />" : "{devServerSsr ? null : <GuideWidget />}";
1990
+ if (enabled) {
1991
+ source = ensureImportLine(source, importLine);
1992
+ source = replaceNamedRegion(source, "raybase:guide-widget", renderLine);
1993
+ }
1994
+ else {
1995
+ source = source.replace(importLine, "");
1996
+ source = replaceNamedRegion(source, "raybase:guide-widget", "");
1997
+ }
1998
+ writeFileSync(file, source);
1999
+ }
2000
+ function patchGuideCss(projectDir, template, enabled) {
2001
+ const file = join(projectDir, template === "react-router" ? "app/app.css" : "src/styles.css");
2002
+ if (!existsSync(file))
2003
+ return;
2004
+ let source = readFileSync(file, "utf8");
2005
+ const line = '@source "../node_modules/@raybase/agent-ui/dist";\n';
2006
+ if (enabled) {
2007
+ if (!source.includes(line))
2008
+ source = source.replace(/^@import "tailwindcss";\n/m, `@import "tailwindcss";\n${line}`);
2009
+ }
2010
+ else {
2011
+ source = source.replace(line, "");
2012
+ }
2013
+ writeFileSync(file, source);
2014
+ }
2015
+ function removeServerModule(projectDir, template, module) {
2016
+ const file = join(projectDir, template === "react-router" ? "app/raybase.server.ts" : "src/raybase.server.ts");
2017
+ if (!existsSync(file))
2018
+ return;
2019
+ let source = readFileSync(file, "utf8");
2020
+ const docsEnabled = module === "docs" ? false : exactImportPattern("@raybase/docs", "docsModule").test(source);
2021
+ const guideEnabled = module === "guide" ? false : exactImportPattern("@raybase/guide", "guideModule").test(source);
2022
+ const apiEnabled = module === "api" ? false : exactImportPattern("./api/operations", "api").test(source);
2023
+ if (module === "docs") {
2024
+ source = source.replace(exactImportPattern("@raybase/docs", "docsModule"), "");
2025
+ }
2026
+ else if (module === "guide") {
2027
+ source = source
2028
+ .replace(exactImportPattern("@raybase/guide", "guideModule"), "")
2029
+ .replace(exactImportPattern("./guide/actions", "guideActions"), "")
2030
+ .replace(exactImportPattern("./guide/config", "guideConfig"), "")
2031
+ .replace(exactImportPattern("./guide/corpus", "guideCorpus"), "");
2032
+ }
2033
+ else {
2034
+ source = source.replace(exactImportPattern("./api/operations", "api"), "");
2035
+ }
2036
+ source = replaceNamedRegion(source, "raybase:modules", renderModulesRegion({ template, docs: docsEnabled, guide: guideEnabled, api: apiEnabled, docsPlacement: currentDocsPlacement(projectDir) }));
2037
+ if (docsEnabled || guideEnabled)
2038
+ source = ensureRaybaseEnvImport(source);
2039
+ writeFileSync(file, source);
2040
+ }
2041
+ function replaceInFile(file, replacements) {
2042
+ if (!existsSync(file))
2043
+ return;
2044
+ const source = readFileSync(file, "utf8");
2045
+ let next = source;
2046
+ for (const [pattern, replacement] of replacements)
2047
+ next = next.replace(pattern, replacement);
2048
+ if (next !== source)
2049
+ writeFileSync(file, next);
2050
+ }
2051
+ function currentDocsPlacement(projectDir) {
2052
+ try {
2053
+ const parsed = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
2054
+ return parsed.raybase?.modules?.docs?.placement === "site" ? "site" : "spine";
2055
+ }
2056
+ catch {
2057
+ return "spine";
2058
+ }
2059
+ }
2060
+ function editJsoncValue(source, path, value) {
2061
+ return applyEdits(source, modify(source, path, value, { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
2062
+ }
2063
+ function removeLocalAiPlaceholder(source) {
2064
+ return source.replace(/\n\s*\/\/ Live local Workers AI uses a remote binding and Wrangler login\.\n\s*\/\/ Add with `raybase ai enable --dev --mode live`:\n\s*\/\/ "ai": \{\n\s*\/\/ "binding": "AI",\n\s*\/\/ "remote": true\n\s*\/\/ \},/m, "");
2065
+ }
2066
+ // The React Router starter's createRaybaseApp is typed by its worker Env
2067
+ // (env.d.ts, which workers/app.ts passes through), so its modules are too.
2068
+ function moduleEnvType(template) {
2069
+ return template === "react-router" ? "Env" : "RaybaseEnv";
2070
+ }
2071
+ function renderModulesRegion(input) {
2072
+ const env = moduleEnvType(input.template);
2073
+ const docsModuleCall = input.docs && input.docsPlacement === "site" ? ` docsModule<${env}>({ placement: "site", audience: "public" })` : ` docsModule<${env}>()`;
2074
+ const entries = [
2075
+ input.docs ? docsModuleCall : null,
2076
+ input.guide ? ` guideModule<${env}>({ config: guideConfig, corpus: guideCorpus, actions: guideActions })` : null,
2077
+ input.api ? " api" : null
2078
+ ].filter(Boolean);
2079
+ return entries.length ? `modules: [\n${entries.join(",\n")}\n],` : "modules: [],";
2080
+ }
2081
+ function replaceNamedRegion(source, name, body) {
2082
+ const start = `${name}:start`;
2083
+ const end = `${name}:end`;
2084
+ const startMatches = indexesOf(source, start);
2085
+ const endMatches = indexesOf(source, end);
2086
+ if (startMatches.length !== 1 || endMatches.length !== 1 || endMatches[0] < startMatches[0]) {
2087
+ throw new Error(`Expected exactly one ordered ${name} anchor region.`);
2088
+ }
2089
+ const startLineEnd = source.indexOf("\n", startMatches[0]);
2090
+ const endLineStart = source.lastIndexOf("\n", endMatches[0]);
2091
+ if (startLineEnd === -1 || endLineStart === -1 || endLineStart < startLineEnd) {
2092
+ throw new Error(`Malformed ${name} anchor region.`);
2093
+ }
2094
+ const linePrefix = source.slice(source.lastIndexOf("\n", startMatches[0]) + 1, startMatches[0]);
2095
+ const indent = /^\s*/.exec(linePrefix)?.[0] ?? "";
2096
+ const replacement = body.trim()
2097
+ ? `\n${indent}${body.trim().replace(/\n/g, `\n${indent}`)}\n${indent}`
2098
+ : `\n${indent}`;
2099
+ return `${source.slice(0, startLineEnd)}${replacement}${source.slice(endLineStart)}`;
2100
+ }
2101
+ function indexesOf(source, needle) {
2102
+ const indexes = [];
2103
+ let index = source.indexOf(needle);
2104
+ while (index !== -1) {
2105
+ indexes.push(index);
2106
+ index = source.indexOf(needle, index + needle.length);
2107
+ }
2108
+ return indexes;
2109
+ }
2110
+ function exactImportPattern(moduleSpecifier, binding) {
2111
+ return new RegExp(`^import \\{ ${escapeRegExp(binding)} \\} from "${escapeRegExp(moduleSpecifier)}";\\n`, "m");
2112
+ }
2113
+ function ensureExactImport(source, moduleSpecifier, binding) {
2114
+ if (exactImportPattern(moduleSpecifier, binding).test(source))
2115
+ return source;
2116
+ const matches = [...source.matchAll(/^import .*\n/gm)];
2117
+ const line = `import { ${binding} } from "${moduleSpecifier}";\n`;
2118
+ const last = matches.at(-1);
2119
+ if (!last?.index && last?.index !== 0)
2120
+ return `${line}${source}`;
2121
+ return `${source.slice(0, last.index + last[0].length)}${line}${source.slice(last.index + last[0].length)}`;
2122
+ }
2123
+ function ensureImportLine(source, line) {
2124
+ if (source.includes(line))
2125
+ return source;
2126
+ const matches = [...source.matchAll(/^import .*\n/gm)];
2127
+ const last = matches.at(-1);
2128
+ if (!last?.index && last?.index !== 0)
2129
+ return `${line}${source}`;
2130
+ return `${source.slice(0, last.index + last[0].length)}${line}${source.slice(last.index + last[0].length)}`;
2131
+ }
2132
+ function ensureRaybaseEnvImport(source) {
2133
+ if (/^import\s+(?:type\s+)?\{[^}]*\bRaybaseEnv\b[^}]*\}\s+from "@raybase\/core\/worker";\n/m.test(source))
2134
+ return source;
2135
+ return ensureImportLine(source, 'import type { RaybaseEnv } from "@raybase/core/worker";\n');
2136
+ }
2137
+ function escapeRegExp(value) {
2138
+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
2139
+ }
2140
+ function replacePlaceholders(root, replacements) {
2141
+ for (const file of walk(root)) {
2142
+ if (statSync(file).isDirectory())
2143
+ continue;
2144
+ const source = readFileSync(file, "utf8");
2145
+ let next = source;
2146
+ for (const [key, value] of Object.entries(replacements)) {
2147
+ next = next.split(key).join(value);
2148
+ }
2149
+ if (next !== source)
2150
+ writeFileSync(file, next);
2151
+ }
2152
+ }
2153
+ function initGit(projectDir) {
2154
+ const git = spawnSync("git", ["--version"], { encoding: "utf8" });
2155
+ if (git.status !== 0)
2156
+ return;
2157
+ run("git", ["init"], projectDir);
2158
+ run("git", ["add", "."], projectDir);
2159
+ const commit = spawnSync("git", ["commit", "-m", "Initial Raybase app"], {
2160
+ cwd: projectDir,
2161
+ stdio: "ignore"
2162
+ });
2163
+ if (commit.status !== 0) {
2164
+ console.log("Git initialized. Initial commit skipped because git user identity is not configured.");
2165
+ }
2166
+ }
2167
+ function run(command, args, cwd) {
2168
+ const result = spawnSync(command, args, { cwd, stdio: "inherit" });
2169
+ if (result.status !== 0)
2170
+ throw new Error(`${command} ${args.join(" ")} failed.`);
2171
+ }
2172
+ function installCommand(projectDir) {
2173
+ if (existsSync(join(projectDir, "package-lock.json")))
2174
+ return { command: "npm", args: ["install"] };
2175
+ return { command: "pnpm", args: ["install"] };
2176
+ }
2177
+ function walk(root) {
2178
+ const files = [];
2179
+ for (const item of readdirSync(root)) {
2180
+ const path = join(root, item);
2181
+ const stat = statSync(path);
2182
+ if (stat.isDirectory())
2183
+ files.push(...walk(path));
2184
+ else
2185
+ files.push(path);
2186
+ }
2187
+ return files;
2188
+ }
2189
+ function sha256File(file) {
2190
+ return createHash("sha256").update(readFileSync(file)).digest("hex");
2191
+ }
2192
+ function stableJson(value) {
2193
+ return `${JSON.stringify(sortJson(value), null, 2)}\n`;
2194
+ }
2195
+ function sortJson(value) {
2196
+ if (Array.isArray(value))
2197
+ return value.map(sortJson);
2198
+ if (!value || typeof value !== "object")
2199
+ return value;
2200
+ return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, val]) => [key, sortJson(val)]));
2201
+ }
2202
+ // --- starters from outside Raybase -----------------------------------------
2203
+ // raybase.starter.json is the starter's own description; see
2204
+ // ./starter-description.ts. The files it names as inputs (agent
2205
+ // instructions, the SPEC template, skill folders) are consumed here and not
2206
+ // copied into the project; raybase.starter.json itself stays at the root.
2207
+ function starterInputPaths(description) {
2208
+ return [description.agentInstructions, description.spec, ...(description.skills ?? [])]
2209
+ .filter((path) => Boolean(path))
2210
+ .map((path) => path.replace(/^\.\//, "").replace(/\/+$/, ""));
2211
+ }
2212
+ function copyStarterTree(starter, projectDir) {
2213
+ const inputs = new Set(starterInputPaths(starter.description));
2214
+ cpSync(starter.root, projectDir, {
2215
+ recursive: true,
2216
+ filter: (source) => {
2217
+ const rel = relative(starter.root, source).split(sep).join("/");
2218
+ if (!rel)
2219
+ return true;
2220
+ const name = rel.split("/").pop() ?? "";
2221
+ if (FRAMEWORK_EXCLUDES.has(name) || STARTER_TREE_SKIP.has(name))
2222
+ return false;
2223
+ // A web starter is materialized beside its own file-manifest.json.
2224
+ if (rel === "file-manifest.json" && starter.source.type === "web")
2225
+ return false;
2226
+ return !inputs.has(rel);
2227
+ }
2228
+ });
2229
+ // cpSync creates the folders that held only inputs; drop them when empty.
2230
+ for (const input of inputs) {
2231
+ let dir = dirname(join(projectDir, input));
2232
+ while (dir.startsWith(`${projectDir}${sep}`) && existsSync(dir) && readdirSync(dir).length === 0) {
2233
+ rmSync(dir, { recursive: true, force: true });
2234
+ dir = dirname(dir);
2235
+ }
2236
+ }
2237
+ }
2238
+ function writeStarterSpec(starter, projectDir) {
2239
+ const target = join(projectDir, CANONICAL_SPEC_PATH);
2240
+ mkdirSync(dirname(target), { recursive: true });
2241
+ // Placeholders (__APP_NAME__ …) are replaced with the rest of the tree.
2242
+ cpSync(join(starter.root, starter.description.spec), target);
2243
+ }
2244
+ function appendStarterDevVars(projectDir, description) {
2245
+ const entries = Object.entries(description.devVars ?? {});
2246
+ if (!entries.length)
2247
+ return;
2248
+ const file = join(projectDir, ".dev.vars");
2249
+ const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
2250
+ const present = new Set(existing.split(/\r?\n/).map((line) => line.match(/^\s*([A-Z][A-Z0-9_]*)\s*=/)?.[1]).filter(Boolean));
2251
+ const lines = entries.filter(([name]) => !present.has(name)).map(([name, value]) => `${name}=${value}`);
2252
+ if (!lines.length)
2253
+ return;
2254
+ const body = existing.replace(/\s*$/, "");
2255
+ writeFileSync(file, `${body}${body ? "\n" : ""}# From the starter ${JSON.stringify(description.name)} (${STARTER_DESCRIPTION_FILE} devVars)\n${lines.join("\n")}\n`);
2256
+ }
2257
+ // A starter's skills install beside Raybase's: .agents/skills/<folder name>
2258
+ // plus the .claude/skills link. They are not stamped in .raybase/skills.json,
2259
+ // so `raybase skills sync` and --refresh-skills neither prune them nor count
2260
+ // them as drift; .raybase/starter.json records them instead.
2261
+ function installStarterSkills(projectDir, starter) {
2262
+ const installed = {};
2263
+ for (const entry of starter.description.skills ?? []) {
2264
+ const path = entry.replace(/^\.\//, "").replace(/\/+$/, "");
2265
+ const name = path.split("/").pop();
2266
+ const source = join(starter.root, path);
2267
+ const target = join(projectDir, ".agents", "skills", name);
2268
+ if (resolve(source) !== resolve(target)) {
2269
+ rmSync(target, { recursive: true, force: true });
2270
+ mkdirSync(dirname(target), { recursive: true });
2271
+ cpSync(source, target, { recursive: true });
2272
+ }
2273
+ ensureDirectorySymlink(join(projectDir, ".claude", "skills", name), target);
2274
+ installed[name] = { path, sha256: hashSkillTree(target) };
2275
+ }
2276
+ return installed;
2277
+ }
2278
+ function mergeStarterAgentInstructions(projectDir, starter, replacements) {
2279
+ const agentsFile = join(projectDir, "AGENTS.md");
2280
+ const marker = `<!-- ${STARTER_DESCRIPTION_FILE} agentInstructions -->`;
2281
+ const existing = existsSync(agentsFile) ? readFileSync(agentsFile, "utf8") : "";
2282
+ if (existing.includes(marker))
2283
+ return;
2284
+ let block = readFileSync(join(starter.root, starter.description.agentInstructions), "utf8").trim();
2285
+ for (const [key, value] of Object.entries(replacements))
2286
+ block = block.split(key).join(value);
2287
+ writeFileSync(agentsFile, `${existing.trim()}\n\n${marker}\n${block}\n`);
2288
+ }
2289
+ function writeStarterLock(projectDir, starter, skills) {
2290
+ const file = join(projectDir, STARTER_LOCK_FILE);
2291
+ mkdirSync(dirname(file), { recursive: true });
2292
+ writeFileSync(file, stableJson({
2293
+ schemaVersion: 1,
2294
+ name: starter.description.name,
2295
+ framework: starter.description.framework,
2296
+ raybase: starter.description.raybase,
2297
+ source: starter.source,
2298
+ skills,
2299
+ createdAt: new Date().toISOString(),
2300
+ createdWith: { "@raybase/create": CREATE_RAYBASE_VERSION }
2301
+ }));
2302
+ }
2303
+ // The starter's own steps go before the final "raybase dev".
2304
+ function withStarterNextSteps(steps, starter) {
2305
+ const extra = starter?.description.nextSteps ?? [];
2306
+ if (!extra.length)
2307
+ return steps;
2308
+ const last = steps.at(-1);
2309
+ return last?.startsWith("raybase dev") ? [...steps.slice(0, -1), ...extra, last] : [...steps, ...extra];
2310
+ }
2311
+ // Every project gets a short random app id at scaffold time, stored in
2312
+ // package.json under raybase.appId and stamped onto the deployed worker as a
2313
+ // var by `raybase deploy`. It is the app's durable identity: deploy uses it to
2314
+ // tell "my previous deployment" apart from "an unrelated worker that happens
2315
+ // to share the directory-derived name". Existing ids are always preserved —
2316
+ // the id must stay stable across re-scaffolds and skill refreshes.
2317
+ function ensureAppId(projectDir) {
2318
+ const file = join(projectDir, "package.json");
2319
+ if (!existsSync(file))
2320
+ return null;
2321
+ const parsed = JSON.parse(readFileSync(file, "utf8"));
2322
+ const existing = parsed.raybase?.appId;
2323
+ if (existing)
2324
+ return existing;
2325
+ const appId = generateAppId();
2326
+ parsed.raybase = { ...(parsed.raybase ?? {}), appId };
2327
+ writeFileSync(file, `${JSON.stringify(parsed, null, 2)}\n`);
2328
+ return appId;
2329
+ }
2330
+ function generateAppId() {
2331
+ // Hostname-safe and unambiguous (no 0/o, 1/l/i): the id may end up in a
2332
+ // workers.dev label if deploy ever needs it in a name.
2333
+ const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
2334
+ const bytes = randomBytes(6);
2335
+ let id = "";
2336
+ for (const byte of bytes)
2337
+ id += alphabet[byte % alphabet.length];
2338
+ return id;
2339
+ }
2340
+ function humanize(value) {
2341
+ return value
2342
+ .split(/[\/_-]/)
2343
+ .filter(Boolean)
2344
+ .map((part) => part[0]?.toUpperCase() + part.slice(1))
2345
+ .join(" ") || "Raybase App";
2346
+ }
2347
+ function slugify(value) {
2348
+ return value
2349
+ .toLowerCase()
2350
+ .replace(/[^a-z0-9]+/g, "-")
2351
+ .replace(/^-|-$/g, "") || "raybase-app";
2352
+ }
2353
+ //# sourceMappingURL=index.js.map