@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

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 (571) hide show
  1. package/README.md +114 -76
  2. package/api/blog/blog.doc.mjs +1 -0
  3. package/api/build/build.doc.mjs +4 -3
  4. package/api/build/build.test.mjs +14 -3
  5. package/api/build/build.type.d.mts +36 -2
  6. package/api/build/build.type.mjs +25 -4
  7. package/api/build/help/help.d.mts +8 -5
  8. package/api/build/help/help.mjs +56 -6
  9. package/api/component/_adapter.d.mts +6 -12
  10. package/api/component/_adapter.mjs +20 -10
  11. package/api/component/component.doc.mjs +13 -3
  12. package/api/component/component.mjs +91 -14
  13. package/api/component/component.test.mjs +38 -0
  14. package/api/component/component.type.d.mts +22 -11
  15. package/api/component/component.type.mjs +32 -24
  16. package/api/component/detail/blocks/blocks.d.mts +2 -1
  17. package/api/component/detail/blocks/blocks.mjs +4 -3
  18. package/api/component/list/list.d.mts +0 -5
  19. package/api/component/list/list.mjs +40 -11
  20. package/api/discover/discover.doc.mjs +2 -1
  21. package/api/discover/discover.type.d.mts +4 -4
  22. package/api/discover/discover.type.mjs +10 -10
  23. package/api/docs/_adapter.d.mts +230 -41
  24. package/api/docs/_adapter.mjs +734 -108
  25. package/api/docs/compiled-topics.test.mjs +78 -0
  26. package/api/docs/detail/detail.mjs +22 -63
  27. package/api/docs/detail/section/section.d.mts +1 -1
  28. package/api/docs/detail/section/section.mjs +54 -19
  29. package/api/docs/detail/section/section.test.mjs +50 -0
  30. package/api/docs/docs.d.mts +10 -3
  31. package/api/docs/docs.doc.mjs +54 -16
  32. package/api/docs/docs.mjs +53 -10
  33. package/api/docs/docs.test.mjs +164 -4
  34. package/api/docs/docs.type.d.mts +205 -5
  35. package/api/docs/docs.type.mjs +137 -11
  36. package/api/docs/index/index.d.mts +18 -0
  37. package/api/docs/index/index.mjs +40 -0
  38. package/api/docs/index/index.test.mjs +62 -0
  39. package/api/docs/integration-tree.test.mjs +547 -0
  40. package/api/docs/integrationDocs.test.mjs +114 -8
  41. package/api/docs/list/list.mjs +28 -12
  42. package/api/docs/node/node.d.mts +43 -0
  43. package/api/docs/node/node.mjs +192 -0
  44. package/api/doctor/doctor.d.mts +99 -1
  45. package/api/doctor/doctor.doc.mjs +1 -0
  46. package/api/doctor/doctor.mjs +544 -1
  47. package/api/doctor/doctor.test.mjs +610 -1
  48. package/api/gap-report/gap-report.doc.mjs +8 -4
  49. package/api/hook/_adapter.mjs +19 -5
  50. package/api/hook/hook.doc.mjs +1 -0
  51. package/api/hook/hook.type.d.mts +3 -3
  52. package/api/hook/hook.type.mjs +11 -11
  53. package/api/hook/list/list.d.mts +2 -2
  54. package/api/hook/list/list.mjs +69 -17
  55. package/api/index.d.mts +1 -1
  56. package/api/index.mjs +1 -0
  57. package/api/init/init.doc.mjs +6 -1
  58. package/api/init/init.test.mjs +41 -1
  59. package/api/init/remove/remove.mjs +1 -1
  60. package/api/init/run/run.mjs +20 -10
  61. package/api/integration/add-contribution.component-names.test.mjs +120 -0
  62. package/api/integration/add-contribution.d.mts +2 -1
  63. package/api/integration/add-contribution.mjs +130 -15
  64. package/api/integration/add-contribution.test.mjs +258 -7
  65. package/api/integration/add-theme.mjs +34 -64
  66. package/api/integration/add-theme.test.mjs +105 -21
  67. package/api/integration/authoring-checks.mjs +108 -31
  68. package/api/integration/authoring-checks.test.mjs +171 -6
  69. package/api/integration/authoring-checks.type.d.mts +3 -1
  70. package/api/integration/authoring-checks.type.mjs +3 -1
  71. package/api/integration/integration-authoring.type.d.mts +3 -1
  72. package/api/integration/integration-authoring.type.mjs +2 -0
  73. package/api/integration/integration-block-exports.test.mjs +10 -6
  74. package/api/integration/integrationAdd.doc.mjs +14 -4
  75. package/api/integration/integrationAddAgentDoc.doc.mjs +1 -0
  76. package/api/integration/integrationAddCodemod.doc.mjs +1 -0
  77. package/api/integration/integrationAddComponent.doc.mjs +2 -1
  78. package/api/integration/integrationAddDoc.doc.mjs +8 -1
  79. package/api/integration/integrationAddTemplate.doc.mjs +1 -0
  80. package/api/integration/integrationAddTheme.doc.mjs +6 -5
  81. package/api/integration/integrationComponentConflicts.doc.mjs +1 -0
  82. package/api/integration/integrationDocConflicts.doc.mjs +2 -1
  83. package/api/integration/integrationPackCheck.doc.mjs +2 -1
  84. package/api/integration/integrationTemplateConflicts.doc.mjs +7 -5
  85. package/api/integration/pack-check.mjs +83 -7
  86. package/api/integration/pack-check.test.mjs +387 -47
  87. package/api/integration/pack-check.type.d.mts +26 -2
  88. package/api/integration/pack-check.type.mjs +14 -1
  89. package/api/integration/summarizeIssues.doc.mjs +1 -0
  90. package/api/integration/validate-integration-fixes.test.mjs +1389 -0
  91. package/api/integration/validate-integration.mjs +52 -102
  92. package/api/integration/validate-integration.test.mjs +179 -26
  93. package/api/integration/validate-unread-theme-folders.test.mjs +110 -0
  94. package/api/integration/validateIntegration.doc.mjs +3 -2
  95. package/api/json/assertResponse.doc.mjs +1 -0
  96. package/api/json/envelope-types.test.mjs +76 -0
  97. package/api/json/index.ts +2 -0
  98. package/api/json/isError.doc.mjs +1 -0
  99. package/api/json/parseResponse.doc.mjs +3 -2
  100. package/api/layout/_adapter.mjs +20 -5
  101. package/api/layout/expand/expand.mjs +7 -5
  102. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  103. package/api/layout/grammar/grammar.mjs +2 -1
  104. package/api/layout/layoutCheck.doc.mjs +1 -0
  105. package/api/layout/layoutExpand.doc.mjs +2 -1
  106. package/api/layout/layoutGrammar.doc.mjs +1 -0
  107. package/api/search/search-return-type.test.mjs +54 -0
  108. package/api/search/search.d.mts +29 -11
  109. package/api/search/search.doc.mjs +8 -2
  110. package/api/search/search.mjs +337 -41
  111. package/api/search/search.test.mjs +124 -1
  112. package/api/search/search.type.d.mts +15 -3
  113. package/api/search/search.type.mjs +5 -2
  114. package/api/swizzle/copy/copy.mjs +28 -11
  115. package/api/swizzle/swizzle.doc.mjs +2 -1
  116. package/api/swizzle/swizzle.type.d.mts +2 -2
  117. package/api/swizzle/swizzle.type.mjs +2 -2
  118. package/api/template/copy/copy.mjs +17 -23
  119. package/api/template/copy/copy.test.mjs +17 -0
  120. package/api/template/list/list.mjs +1 -0
  121. package/api/template/template-integration.test.mjs +1022 -3
  122. package/api/template/template-suffix.test.mjs +41 -21
  123. package/api/template/template.d.mts +1 -1
  124. package/api/template/template.doc.mjs +30 -8
  125. package/api/template/template.mjs +45 -8
  126. package/api/template/template.type.d.mts +12 -14
  127. package/api/template/template.type.mjs +15 -14
  128. package/api/theme/_adapter.d.mts +2 -3
  129. package/api/theme/_adapter.mjs +4 -5
  130. package/api/theme/add/add.binary.test.mjs +84 -0
  131. package/api/theme/add/add.mjs +20 -3
  132. package/api/theme/add/add.staging.test.mjs +66 -0
  133. package/api/theme/add/add.test.mjs +14 -1
  134. package/api/theme/build/build.mjs +133 -42
  135. package/api/theme/build/build.public-component-vars.test.mjs +1 -1
  136. package/api/theme/build/build.receipt-doc.test.mjs +111 -0
  137. package/api/theme/build/build.test.mjs +127 -0
  138. package/api/theme/build/font-warning.mjs +3 -3
  139. package/api/theme/build/font-warning.test.mjs +5 -2
  140. package/api/theme/generateTonalPalette.doc.mjs +1 -0
  141. package/api/theme/integration-themes.test.mjs +39 -28
  142. package/api/theme/list/list.test.mjs +19 -20
  143. package/api/theme/listThemes.doc.mjs +6 -5
  144. package/api/theme/palette/generate/generate.mjs +8 -3
  145. package/api/theme/palette/generate/generate.test.mjs +96 -0
  146. package/api/theme/palette/generate/generator.d.mts +10 -13
  147. package/api/theme/palette/generate/generator.mjs +15 -4
  148. package/api/theme/palette/generate/generator.test.mjs +10 -0
  149. package/api/theme/template/template.mjs +11 -2
  150. package/api/theme/template/template.test.mjs +20 -0
  151. package/api/theme/theme.type.d.mts +170 -11
  152. package/api/theme/theme.type.mjs +94 -27
  153. package/api/theme/themeAdd.doc.mjs +4 -3
  154. package/api/theme/themeBuild.doc.mjs +8 -4
  155. package/api/theme/themeList.doc.mjs +6 -3
  156. package/api/theme/themeListAvailable.doc.mjs +5 -3
  157. package/api/theme/themePaletteGenerate.doc.mjs +1 -0
  158. package/api/theme/themeTargets.doc.mjs +1 -0
  159. package/api/theme/themeTemplate.doc.mjs +6 -2
  160. package/api/upgrade/_adapter.d.mts +32 -5
  161. package/api/upgrade/_adapter.mjs +139 -22
  162. package/api/upgrade/list/list.mjs +2 -1
  163. package/api/upgrade/list/list.test.mjs +73 -0
  164. package/api/upgrade/project-context.test.mjs +272 -0
  165. package/api/upgrade/provider-agreement.test.mjs +152 -0
  166. package/api/upgrade/run/run.mjs +356 -59
  167. package/api/upgrade/status/status.mjs +2 -2
  168. package/api/upgrade/upgrade.doc.mjs +12 -5
  169. package/api/upgrade/upgrade.type.d.mts +43 -5
  170. package/api/upgrade/upgrade.type.mjs +27 -11
  171. package/assets/codemods/__tests__/runner.test.mjs +330 -8
  172. package/assets/codemods/integration-discovery.mjs +48 -4
  173. package/assets/codemods/integration-discovery.test.mjs +73 -0
  174. package/assets/codemods/integration-runner.mjs +56 -4
  175. package/assets/codemods/integration-runner.protection.test.mjs +153 -0
  176. package/assets/codemods/run-codemod.mjs +177 -34
  177. package/assets/codemods/runner.mjs +350 -102
  178. package/assets/codemods/term-log.mjs +32 -8
  179. package/assets/codemods/term-log.test.mjs +19 -1
  180. package/assets/codemods/transform-prop.mjs +109 -0
  181. package/assets/codemods/transform-prop.test.mjs +95 -0
  182. package/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs +63 -0
  183. package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs +220 -0
  184. package/assets/codemods/transforms/next/index.mjs +19 -1
  185. package/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs +148 -0
  186. package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs +141 -0
  187. package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
  188. package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
  189. package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
  190. package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
  191. package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs +27 -5
  192. package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs +20 -5
  193. package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
  194. package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
  195. package/assets/docs/README.md +9 -0
  196. package/assets/docs/authoring.doc.mjs +14 -0
  197. package/assets/docs/getting-started.doc.mjs +2 -2
  198. package/assets/docs/principles.doc.mjs +6 -6
  199. package/assets/docs/styling-libraries.doc.mjs +3 -3
  200. package/assets/docs/styling.doc.mjs +4 -4
  201. package/assets/docs/theme.doc.mjs +4 -4
  202. package/assets/docs/tokens.doc.mjs +1 -1
  203. package/assets/docs/tree/api.doc.mjs +30 -0
  204. package/assets/docs/tree/cli.doc.mjs +23 -0
  205. package/assets/docs/tree/commands.doc.mjs +25 -0
  206. package/assets/docs/{cli-integrations.doc.mjs → tree/integrations.doc.mjs} +124 -25
  207. package/assets/docs/tree/integrations.test.mjs +62 -0
  208. package/assets/docs/tree/writing-docs.doc.mjs +286 -0
  209. package/assets/docs/working-with-ai.doc.mjs +1 -1
  210. package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx +1 -1
  211. package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs +14 -0
  212. package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx +100 -0
  213. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
  214. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
  215. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
  216. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
  217. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
  218. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
  219. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
  220. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
  221. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
  222. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
  223. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
  224. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
  225. package/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx +1 -0
  226. package/assets/templates/pages/table-tree/page.tsx +1704 -0
  227. package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
  228. package/assets/templates/themes/butter/butterTheme.doc.mjs +11 -0
  229. package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs +11 -0
  230. package/assets/templates/themes/gothic/gothicTheme.doc.mjs +11 -0
  231. package/assets/templates/themes/matcha/matchaTheme.doc.mjs +11 -0
  232. package/assets/templates/themes/neutral/neutralTheme.doc.mjs +11 -0
  233. package/assets/templates/themes/stone/stoneTheme.doc.mjs +11 -0
  234. package/assets/templates/themes/y2k/y2kTheme.doc.mjs +11 -0
  235. package/authoring/_shared/contract.ts +22 -0
  236. package/authoring/codemod/codemod.doc.mjs +7 -2
  237. package/authoring/codemod/parse.d.mts +8 -8
  238. package/authoring/codemod/parse.mjs +8 -6
  239. package/authoring/codemod/type.ts +12 -0
  240. package/authoring/config/config.doc.mjs +2 -2
  241. package/authoring/config/debug-composition.test.mjs +92 -0
  242. package/authoring/config/parse.d.mts +13 -13
  243. package/authoring/config/parse.mjs +8 -8
  244. package/authoring/config/type.ts +18 -6
  245. package/authoring/debug/debug.doc.d.mts +11 -0
  246. package/authoring/debug/debug.doc.mjs +182 -0
  247. package/authoring/debug/parse.d.mts +8 -8
  248. package/authoring/debug/parse.mjs +3 -3
  249. package/authoring/doctypes/_schema.d.mts +718 -23
  250. package/authoring/doctypes/_schema.mjs +519 -39
  251. package/authoring/doctypes/base/graph-fields.doc.d.mts +9 -0
  252. package/authoring/doctypes/base/graph-fields.doc.mjs +64 -0
  253. package/authoring/doctypes/base/type.ts +41 -0
  254. package/authoring/doctypes/command/command.doc.mjs +4 -3
  255. package/authoring/doctypes/command/parse.d.mts +2 -2
  256. package/authoring/doctypes/command/parse.mjs +1 -1
  257. package/authoring/doctypes/command/type.ts +5 -4
  258. package/authoring/doctypes/component/component.doc.mjs +6 -3
  259. package/authoring/doctypes/component/parse.d.mts +2 -2
  260. package/authoring/doctypes/component/parse.mjs +1 -1
  261. package/authoring/doctypes/component/type.ts +6 -5
  262. package/authoring/doctypes/doctypes-new.test.mjs +48 -6
  263. package/authoring/doctypes/enum/enum.doc.mjs +1 -1
  264. package/authoring/doctypes/enum/parse.d.mts +2 -2
  265. package/authoring/doctypes/enum/parse.mjs +1 -1
  266. package/authoring/doctypes/enum/type.ts +4 -2
  267. package/authoring/doctypes/function/function.doc.mjs +7 -2
  268. package/authoring/doctypes/function/parse.d.mts +2 -2
  269. package/authoring/doctypes/function/parse.mjs +1 -1
  270. package/authoring/doctypes/function/type.ts +9 -4
  271. package/authoring/doctypes/hook/hook.doc.mjs +4 -0
  272. package/authoring/doctypes/hook/parse.d.mts +2 -2
  273. package/authoring/doctypes/hook/parse.mjs +1 -1
  274. package/authoring/doctypes/hook/type.ts +5 -4
  275. package/authoring/doctypes/legacy.d.mts +8 -6
  276. package/authoring/doctypes/legacy.mjs +5 -4
  277. package/authoring/doctypes/load-contract.test.mjs +208 -0
  278. package/authoring/doctypes/namespace/namespace.doc.d.mts +9 -0
  279. package/authoring/doctypes/namespace/namespace.doc.mjs +128 -0
  280. package/authoring/doctypes/namespace/parse.d.mts +12 -0
  281. package/authoring/doctypes/namespace/parse.mjs +25 -0
  282. package/authoring/doctypes/namespace/parse.test.mjs +163 -0
  283. package/authoring/doctypes/namespace/type.ts +74 -0
  284. package/authoring/doctypes/parse.d.mts +22 -18
  285. package/authoring/doctypes/parse.mjs +22 -11
  286. package/authoring/doctypes/parse.test.mjs +77 -3
  287. package/authoring/doctypes/reference/parse.d.mts +2 -2
  288. package/authoring/doctypes/reference/parse.mjs +8 -5
  289. package/authoring/doctypes/reference/reference.doc.mjs +20 -5
  290. package/authoring/doctypes/reference/type.ts +53 -5
  291. package/authoring/doctypes/schema/parse.d.mts +2 -2
  292. package/authoring/doctypes/schema/parse.mjs +1 -1
  293. package/authoring/doctypes/schema/schema.doc.mjs +1 -1
  294. package/authoring/doctypes/schema/type.ts +4 -4
  295. package/authoring/doctypes/template/parse.d.mts +94 -1
  296. package/authoring/doctypes/template/parse.mjs +40 -2
  297. package/authoring/doctypes/template/parse.test.mjs +26 -2
  298. package/authoring/doctypes/template/template.doc.mjs +13 -3
  299. package/authoring/doctypes/template/type.ts +13 -2
  300. package/authoring/doctypes/theme/parse.d.mts +35 -0
  301. package/authoring/doctypes/theme/parse.mjs +76 -0
  302. package/authoring/doctypes/theme/theme.doc.d.mts +9 -0
  303. package/authoring/doctypes/theme/theme.doc.mjs +79 -0
  304. package/authoring/doctypes/theme/type.ts +42 -0
  305. package/authoring/doctypes/types.ts +12 -10
  306. package/authoring/gap-report/gap-report.doc.d.mts +12 -0
  307. package/authoring/gap-report/gap-report.doc.mjs +183 -0
  308. package/authoring/gap-report/parse.d.mts +10 -10
  309. package/authoring/gap-report/parse.mjs +6 -6
  310. package/authoring/gap-report/type.ts +1 -1
  311. package/authoring/identity/identity.doc.d.mts +9 -0
  312. package/authoring/identity/identity.doc.mjs +61 -0
  313. package/authoring/identity/type.ts +132 -0
  314. package/authoring/index.d.mts +2 -0
  315. package/authoring/index.d.ts +52 -17
  316. package/authoring/index.mjs +3 -1
  317. package/authoring/integration/integration.doc.mjs +15 -8
  318. package/authoring/integration/parse.d.mts +2 -2
  319. package/authoring/integration/parse.mjs +1 -1
  320. package/authoring/integration/parse.test.mjs +10 -1
  321. package/authoring/integration/schema.d.mts +6 -4
  322. package/authoring/integration/schema.mjs +9 -3
  323. package/authoring/integration/type.ts +19 -8
  324. package/authoring/shadcn/receipt.d.mts +6 -6
  325. package/clients/cli/__tests__/cliManifest.test.ts +27 -29
  326. package/clients/cli/command-load-failure.test.mjs +83 -0
  327. package/clients/cli/commands/blog.doc.mjs +1 -1
  328. package/clients/cli/commands/blog.mjs +23 -8
  329. package/clients/cli/commands/blog.test.mjs +42 -1
  330. package/clients/cli/commands/build-theme.adaptations.test.mjs +100 -1
  331. package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
  332. package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
  333. package/clients/cli/commands/build-theme.mjs +16 -50
  334. package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
  335. package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
  336. package/clients/cli/commands/build.doc.mjs +5 -2
  337. package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
  338. package/clients/cli/commands/build.mjs +37 -49
  339. package/clients/cli/commands/build.playbook.test.mjs +75 -0
  340. package/clients/cli/commands/build.text-fields.test.mjs +40 -0
  341. package/clients/cli/commands/component/index.mjs +3 -8
  342. package/clients/cli/commands/component-ownership.test.mjs +3 -3
  343. package/clients/cli/commands/component-package.test.mjs +46 -0
  344. package/clients/cli/commands/component-resolution.test.mjs +21 -0
  345. package/clients/cli/commands/component.doc.mjs +1 -1
  346. package/clients/cli/commands/component.test.mjs +19 -0
  347. package/clients/cli/commands/detail-levels.test.mjs +2 -2
  348. package/clients/cli/commands/discover.broken-integration.test.mjs +52 -5
  349. package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
  350. package/clients/cli/commands/discover.doc.mjs +5 -3
  351. package/clients/cli/commands/discover.mjs +4 -4
  352. package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
  353. package/clients/cli/commands/docs.doc.mjs +28 -6
  354. package/clients/cli/commands/docs.mjs +238 -24
  355. package/clients/cli/commands/docs.test.mjs +193 -1
  356. package/clients/cli/commands/doctor-integration-components.doc.mjs +1 -1
  357. package/clients/cli/commands/doctor-integration-docs.doc.mjs +3 -3
  358. package/clients/cli/commands/doctor-integration-templates.doc.mjs +15 -8
  359. package/clients/cli/commands/doctor-integration-validate.doc.mjs +1 -1
  360. package/clients/cli/commands/doctor-integration.doc.mjs +1 -1
  361. package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
  362. package/clients/cli/commands/doctor-integration.test.mjs +83 -8
  363. package/clients/cli/commands/doctor.doc.mjs +1 -1
  364. package/clients/cli/commands/doctor.mjs +30 -25
  365. package/clients/cli/commands/doctor.test.mjs +42 -0
  366. package/clients/cli/commands/gap-report.doc.mjs +17 -6
  367. package/clients/cli/commands/gap-report.test.mjs +72 -0
  368. package/clients/cli/commands/hook/index.mjs +7 -17
  369. package/clients/cli/commands/hook.doc.mjs +1 -1
  370. package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
  371. package/clients/cli/commands/init.doc.mjs +20 -9
  372. package/clients/cli/commands/init.flag-help.test.mjs +153 -0
  373. package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
  374. package/clients/cli/commands/integration-add.doc.mjs +32 -6
  375. package/clients/cli/commands/integration-authoring.test.mjs +13 -9
  376. package/clients/cli/commands/integration-pack.doc.mjs +1 -1
  377. package/clients/cli/commands/integration-real-world.test.mjs +3 -9
  378. package/clients/cli/commands/integration.doc.mjs +1 -1
  379. package/clients/cli/commands/integration.mjs +1 -0
  380. package/clients/cli/commands/interactive-guard.test.mjs +101 -24
  381. package/clients/cli/commands/json-contract.test.mjs +33 -0
  382. package/clients/cli/commands/layout-check.doc.mjs +15 -4
  383. package/clients/cli/commands/layout-expand.doc.mjs +22 -5
  384. package/clients/cli/commands/layout-grammar.doc.mjs +1 -1
  385. package/clients/cli/commands/layout.doc.mjs +3 -3
  386. package/clients/cli/commands/layout.mjs +21 -9
  387. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  388. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  389. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  390. package/clients/cli/commands/manifest.doc.mjs +1 -1
  391. package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
  392. package/clients/cli/commands/search.doc.mjs +7 -4
  393. package/clients/cli/commands/search.mjs +28 -9
  394. package/clients/cli/commands/search.test.mjs +75 -0
  395. package/clients/cli/commands/setup-nudge.test.mjs +6 -0
  396. package/clients/cli/commands/swizzle.doc.mjs +3 -2
  397. package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
  398. package/clients/cli/commands/template.doc.mjs +52 -13
  399. package/clients/cli/commands/template.flag-help.test.mjs +117 -0
  400. package/clients/cli/commands/template.mjs +4 -91
  401. package/clients/cli/commands/template.path-help.test.mjs +40 -0
  402. package/clients/cli/commands/text-json-parity.test.mjs +719 -0
  403. package/clients/cli/commands/theme-add.doc.mjs +4 -3
  404. package/clients/cli/commands/theme-build.doc.mjs +8 -7
  405. package/clients/cli/commands/theme-list.doc.mjs +2 -2
  406. package/clients/cli/commands/theme-palette-generate.doc.mjs +9 -5
  407. package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
  408. package/clients/cli/commands/theme-palette.doc.mjs +1 -1
  409. package/clients/cli/commands/theme-targets.behavior.test.mjs +4 -3
  410. package/clients/cli/commands/theme-targets.doc.mjs +1 -1
  411. package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
  412. package/clients/cli/commands/theme-template.doc.mjs +2 -2
  413. package/clients/cli/commands/theme.doc.mjs +1 -1
  414. package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
  415. package/clients/cli/commands/upgrade.doc.mjs +22 -10
  416. package/clients/cli/commands/upgrade.file-protection.test.mjs +228 -0
  417. package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
  418. package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
  419. package/clients/cli/commands/upgrade.mjs +29 -7
  420. package/clients/cli/formatters/index.mjs +164 -1
  421. package/clients/cli/formatters/index.test.mjs +97 -0
  422. package/clients/cli/index.mjs +21 -30
  423. package/clients/cli/latest-version-env.test.mjs +50 -0
  424. package/clients/cli/lib/cli-error.test.mjs +7 -0
  425. package/clients/cli/lib/component-format.mjs +9 -9
  426. package/clients/cli/lib/component-format.test.mjs +1 -1
  427. package/clients/cli/lib/define-command.mjs +32 -6
  428. package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
  429. package/clients/cli/lib/exit-codes.test.mjs +97 -0
  430. package/clients/cli/lib/hook-format.mjs +19 -10
  431. package/clients/cli/lib/json-shim.mjs +38 -2
  432. package/clients/cli/lib/json-shim.test.mjs +83 -0
  433. package/clients/cli/lib/manifest.d.ts +2 -0
  434. package/clients/cli/lib/manifest.mjs +36 -2
  435. package/clients/cli/lib/manifest.test.mjs +17 -0
  436. package/foundation/agent-docs/agent-docs.d.mts +4 -0
  437. package/foundation/agent-docs/agent-docs.mjs +70 -3
  438. package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
  439. package/foundation/agent-docs/agent-docs.test.mjs +10 -1
  440. package/foundation/config/integration-debug.test.mjs +28 -3
  441. package/foundation/config/project-themes.test.mjs +11 -19
  442. package/foundation/config/project.d.mts +20 -11
  443. package/foundation/config/project.mjs +263 -91
  444. package/foundation/config/project.test.mjs +270 -21
  445. package/foundation/discovery/authoring-self-docs.d.mts +75 -0
  446. package/foundation/discovery/authoring-self-docs.mjs +224 -0
  447. package/foundation/discovery/authoring-self-docs.test.mjs +165 -0
  448. package/foundation/discovery/authoring-surface.d.mts +74 -0
  449. package/foundation/discovery/authoring-surface.mjs +525 -0
  450. package/foundation/discovery/authoring-surface.test.mjs +392 -0
  451. package/foundation/discovery/cli-self-docs.d.mts +119 -0
  452. package/foundation/discovery/cli-self-docs.mjs +490 -0
  453. package/foundation/discovery/cli-self-docs.test.mjs +375 -0
  454. package/foundation/discovery/component-discovery.d.mts +39 -1
  455. package/foundation/discovery/component-discovery.mjs +50 -1
  456. package/foundation/discovery/component-loader.d.mts +35 -38
  457. package/foundation/discovery/component-loader.mjs +53 -222
  458. package/foundation/discovery/docs-discovery.d.mts +116 -11
  459. package/foundation/discovery/docs-discovery.mjs +389 -108
  460. package/foundation/discovery/docs-discovery.test.mjs +325 -20
  461. package/foundation/discovery/docs-output-budget.d.mts +28 -0
  462. package/foundation/discovery/docs-output-budget.mjs +50 -0
  463. package/foundation/discovery/docs-section-key.d.mts +116 -0
  464. package/foundation/discovery/docs-section-key.mjs +322 -0
  465. package/foundation/discovery/docs-section-key.test.mjs +246 -0
  466. package/foundation/discovery/template-adapter.d.mts +113 -11
  467. package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
  468. package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
  469. package/foundation/discovery/template-adapter.mjs +774 -83
  470. package/foundation/discovery/template-adapter.test.mjs +57 -0
  471. package/foundation/discovery/theme-discovery.d.mts +67 -7
  472. package/foundation/discovery/theme-discovery.mjs +916 -186
  473. package/foundation/discovery/theme-discovery.test.mjs +613 -219
  474. package/foundation/discovery/theming-targets.test.mjs +4 -0
  475. package/foundation/doc-compiler/bundle.d.mts +47 -0
  476. package/foundation/doc-compiler/bundle.mjs +278 -0
  477. package/foundation/doc-compiler/bundle.test.mjs +266 -0
  478. package/foundation/doc-compiler/compile.d.mts +343 -0
  479. package/foundation/doc-compiler/compile.mjs +558 -0
  480. package/foundation/doc-compiler/diagnostics.d.mts +126 -0
  481. package/foundation/doc-compiler/diagnostics.mjs +305 -0
  482. package/foundation/doc-compiler/doc-compiler.test.mjs +714 -0
  483. package/foundation/doc-compiler/doc-loads.test.mjs +1642 -0
  484. package/foundation/doc-compiler/import.d.mts +24 -0
  485. package/foundation/doc-compiler/import.mjs +59 -0
  486. package/foundation/doc-compiler/inputs.d.mts +102 -0
  487. package/foundation/doc-compiler/inputs.mjs +291 -0
  488. package/foundation/doc-compiler/inputs.test.mjs +299 -0
  489. package/foundation/doc-compiler/ir.d.mts +22 -0
  490. package/foundation/doc-compiler/ir.mjs +471 -0
  491. package/foundation/doc-compiler/lenses.d.mts +34 -0
  492. package/foundation/doc-compiler/lenses.mjs +128 -0
  493. package/foundation/doc-compiler/links.d.mts +135 -0
  494. package/foundation/doc-compiler/links.mjs +253 -0
  495. package/foundation/doc-compiler/links.test.mjs +139 -0
  496. package/foundation/doc-compiler/lower-doc.test.mjs +495 -0
  497. package/foundation/doc-compiler/overlays.d.mts +37 -0
  498. package/foundation/doc-compiler/overlays.mjs +206 -0
  499. package/foundation/doc-compiler/parse-readable.d.mts +9 -0
  500. package/foundation/doc-compiler/parse-readable.mjs +29 -0
  501. package/foundation/doc-compiler/read.d.mts +127 -0
  502. package/foundation/doc-compiler/read.mjs +325 -0
  503. package/foundation/doc-compiler/read.test.mjs +313 -0
  504. package/foundation/doc-compiler/source.d.mts +33 -0
  505. package/foundation/doc-compiler/source.mjs +128 -0
  506. package/foundation/doc-compiler/tree.d.mts +288 -0
  507. package/foundation/doc-compiler/tree.mjs +876 -0
  508. package/foundation/doc-compiler/tree.test.mjs +598 -0
  509. package/foundation/fs/file-protection.d.mts +33 -0
  510. package/foundation/fs/file-protection.mjs +825 -0
  511. package/foundation/fs/file-protection.test.mjs +250 -0
  512. package/foundation/fs/module-loader.d.mts +1 -0
  513. package/foundation/fs/module-loader.mjs +50 -1
  514. package/foundation/fs/module-loader.stdout.test.mjs +332 -0
  515. package/foundation/fs/path-safety.d.mts +3 -2
  516. package/foundation/fs/path-safety.mjs +49 -19
  517. package/foundation/fs/path-safety.test.mjs +50 -0
  518. package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
  519. package/foundation/identity/provider-identity.d.mts +90 -0
  520. package/foundation/identity/provider-identity.mjs +320 -0
  521. package/foundation/identity/provider-identity.test.mjs +254 -0
  522. package/foundation/identity/providers.d.mts +7 -0
  523. package/foundation/identity/providers.mjs +16 -0
  524. package/foundation/integrations/autolink.d.mts +58 -1
  525. package/foundation/integrations/autolink.mjs +143 -45
  526. package/foundation/integrations/autolink.test.mjs +1 -1
  527. package/foundation/integrations/cli-requirement.d.mts +45 -0
  528. package/foundation/integrations/cli-requirement.mjs +154 -0
  529. package/foundation/integrations/cli-requirement.test.mjs +109 -0
  530. package/foundation/integrations/contribution-fixes.d.mts +145 -0
  531. package/foundation/integrations/contribution-fixes.mjs +1284 -0
  532. package/foundation/integrations/contribution-inventory.d.mts +3 -2
  533. package/foundation/integrations/contribution-inventory.mjs +27 -24
  534. package/foundation/integrations/contribution-inventory.test.mjs +86 -27
  535. package/foundation/integrations/integration-warnings.d.mts +9 -2
  536. package/foundation/integrations/integration-warnings.mjs +52 -21
  537. package/foundation/integrations/integration-warnings.test.mjs +74 -1
  538. package/foundation/integrations/integrations.d.mts +49 -2
  539. package/foundation/integrations/integrations.mjs +81 -8
  540. package/foundation/integrations/integrations.test.mjs +384 -1
  541. package/foundation/integrations/provider-conflicts.test.mjs +125 -0
  542. package/foundation/integrations/provider-ledger.test.mjs +275 -0
  543. package/foundation/integrations/provider-resolution.d.mts +152 -0
  544. package/foundation/integrations/provider-resolution.mjs +576 -0
  545. package/foundation/integrations/provider-resolution.test.mjs +369 -0
  546. package/foundation/integrations/theme-descriptor.d.mts +8 -0
  547. package/foundation/integrations/theme-descriptor.mjs +44 -0
  548. package/foundation/integrations/validate-contributions.d.mts +2 -0
  549. package/foundation/integrations/validate-contributions.mjs +131 -29
  550. package/foundation/response/base.d.ts +8 -4
  551. package/foundation/response/error-codes.d.mts +3 -1
  552. package/foundation/response/error-codes.d.ts +2 -0
  553. package/foundation/response/error-codes.doc.mjs +13 -4
  554. package/foundation/response/error-codes.mjs +8 -2
  555. package/foundation/response/error-codes.test.mjs +137 -10
  556. package/foundation/response/json-contract.test.mjs +57 -17
  557. package/foundation/response/json.d.mts +4 -2
  558. package/foundation/response/json.mjs +8 -10
  559. package/foundation/response/response-types.doc.mjs +26 -16
  560. package/foundation/response/response-types.doc.test.mjs +158 -0
  561. package/foundation/response/response.doc.mjs +1 -1
  562. package/foundation/text/string-utils.mjs +22 -10
  563. package/foundation/xle/expand.d.mts +2 -0
  564. package/foundation/xle/expand.mjs +4 -3
  565. package/foundation/xle/expand.test.mjs +54 -0
  566. package/foundation/xle/xle.test.mjs +13 -0
  567. package/package.json +10 -11
  568. package/assets/templates/themes/manifest.json +0 -95
  569. package/clients/cli/lib/update-check.mjs +0 -83
  570. package/clients/cli/lib/update-check.test.mjs +0 -137
  571. package/clients/cli/update-hint-commands.test.mjs +0 -54
@@ -211,11 +211,11 @@ export function formatFontLoadingHelp(themeName, families) {
211
211
  const first = families[0];
212
212
  const slug = first.toLowerCase().replace(/ /g, '-');
213
213
  return `
214
- ⚠ Theme "${themeName}" names fonts it does not load: ${named}
215
- The built CSS only sets font-family — load these in your app, or every
214
+ [note] Theme "${themeName}" names fonts it does not load: ${named}
215
+ The built CSS only sets font-family; load these in your app, or every
216
216
  browser quietly falls back.
217
217
 
218
- Google Fonts (add :wght@… axes as your theme's weights require):
218
+ Google Fonts (add :wght@... axes as your theme's weights require):
219
219
 
220
220
  <link rel="preconnect" href="https://fonts.googleapis.com" />
221
221
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
@@ -227,12 +227,15 @@ describe('formatFontLoadingHelp', () => {
227
227
  const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);
228
228
 
229
229
  it('names the theme and every family in the headline', () => {
230
- expect(help).toContain('⚠');
231
- expect(help).toContain('ocean');
230
+ expect(help).toContain('[note] Theme "ocean"');
232
231
  expect(help).toContain('"Fraunces"');
233
232
  expect(help).toContain('"JetBrains Mono"');
234
233
  });
235
234
 
235
+ it('is plain ASCII', () => {
236
+ expect(help).not.toMatch(/[\u0080-\uffff]/);
237
+ });
238
+
236
239
  it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
237
240
  expect(help).toContain(
238
241
  '<link rel="preconnect" href="https://fonts.googleapis.com"',
@@ -5,6 +5,7 @@ export const doc = {
5
5
  type: 'function',
6
6
  kind: 'api',
7
7
  name: 'generateTonalPalette',
8
+ namespace: 'cli/api',
8
9
  displayName: 'generateTonalPalette()',
9
10
  summary: 'Generate candidate tonal palette data without filesystem effects.',
10
11
  description:
@@ -7,18 +7,14 @@ import {themeAdd} from './add/add.mjs';
7
7
 
8
8
  let tmpDir;
9
9
 
10
- function installThemeIntegration(
11
- packageName,
12
- slug,
13
- source = 'export const oceanTheme = {};\n',
14
- extraFiles = {},
15
- ) {
10
+ function installThemeIntegration(packageName, slug, source, extraFiles = {}) {
16
11
  const packageDir = path.join(
17
12
  tmpDir,
18
13
  'node_modules',
19
14
  ...packageName.split('/'),
20
15
  );
21
16
  const themeDir = path.join(packageDir, 'themes', slug);
17
+ const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
22
18
  fs.mkdirSync(themeDir, {recursive: true});
23
19
  fs.writeFileSync(
24
20
  path.join(packageDir, 'package.json'),
@@ -26,26 +22,21 @@ function installThemeIntegration(
26
22
  );
27
23
  fs.writeFileSync(
28
24
  path.join(packageDir, 'astryx.integration.mjs'),
29
- `export default {themes: './themes'};\n`,
25
+ `export default {themes: './themes'};
26
+ `,
30
27
  );
31
28
  fs.writeFileSync(
32
- path.join(packageDir, 'themes', 'manifest.json'),
33
- JSON.stringify({
34
- version: 1,
35
- themes: [
36
- {
37
- slug,
38
- displayName: slug === 'neutral' ? 'Neutral Plus' : 'Ocean',
39
- description: 'Integration-owned theme.',
40
- maintained: true,
41
- entry: 'oceanTheme.ts',
42
- exportName: 'oceanTheme',
43
- files: ['oceanTheme.ts', ...Object.keys(extraFiles)],
44
- },
45
- ],
46
- }),
29
+ path.join(themeDir, `${stem}.doc.mjs`),
30
+ `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
31
+ export default {type: 'theme', name: '${slug}', displayName: '${slug === 'neutral' ? 'Neutral Plus' : 'Ocean'}', description: 'Integration-owned theme.', maintained: true};
32
+ `,
33
+ );
34
+ fs.writeFileSync(
35
+ path.join(themeDir, `${stem}.ts`),
36
+ source ??
37
+ `export const ${stem} = {};
38
+ `,
47
39
  );
48
- fs.writeFileSync(path.join(themeDir, 'oceanTheme.ts'), source);
49
40
  for (const [relativePath, contents] of Object.entries(extraFiles)) {
50
41
  const file = path.join(themeDir, relativePath);
51
42
  fs.mkdirSync(path.dirname(file), {recursive: true});
@@ -85,23 +76,43 @@ describe('themeAdd with integration themes', () => {
85
76
  ).toContain('oceanTheme');
86
77
  });
87
78
 
88
- it('copies nested files listed by an integration theme catalog', async () => {
79
+ it('copies the complete nested integration theme directory', async () => {
89
80
  installThemeIntegration(
90
81
  '@acme/themes',
91
82
  'ocean',
92
83
  "import {oceanBlue} from './tokens/colors';\nexport const oceanTheme = {oceanBlue};\n",
93
- {'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n"},
84
+ {
85
+ 'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n",
86
+ 'receipts/palette.json': '{"version":1}\n',
87
+ },
94
88
  );
95
89
 
96
90
  const result = await themeAdd('ocean', {cwd: tmpDir});
97
91
 
98
- expect(result.data.files).toEqual(['oceanTheme.ts', 'tokens/colors.ts']);
92
+ expect(result.data.files).toEqual([
93
+ 'oceanTheme.ts',
94
+ 'oceanTheme.doc.mjs',
95
+ 'receipts/palette.json',
96
+ 'tokens/colors.ts',
97
+ ]);
98
+ expect(
99
+ fs.readFileSync(
100
+ path.join(tmpDir, 'src', 'themes', 'ocean', 'oceanTheme.doc.mjs'),
101
+ 'utf-8',
102
+ ),
103
+ ).toContain("type: 'theme'");
99
104
  expect(
100
105
  fs.readFileSync(
101
106
  path.join(tmpDir, 'src', 'themes', 'ocean', 'tokens', 'colors.ts'),
102
107
  'utf-8',
103
108
  ),
104
109
  ).toContain('oceanBlue');
110
+ expect(
111
+ fs.readFileSync(
112
+ path.join(tmpDir, 'src', 'themes', 'ocean', 'receipts', 'palette.json'),
113
+ 'utf-8',
114
+ ),
115
+ ).toBe('{"version":1}\n');
105
116
  });
106
117
 
107
118
  it('rejects a nested destination symlink that escapes the project', async () => {
@@ -146,7 +157,7 @@ describe('themeAdd with integration themes', () => {
146
157
  expect(result.data.package).toBe('@acme/themes');
147
158
  });
148
159
 
149
- it('reports a selected installed package with a corrupted theme catalog', async () => {
160
+ it('reports a selected installed package with a corrupted theme directory', async () => {
150
161
  installThemeIntegration(
151
162
  '@acme/themes',
152
163
  'ocean',
@@ -170,7 +181,7 @@ describe('themeAdd with integration themes', () => {
170
181
  themeAdd('ocean', {cwd: tmpDir, package: '@acme/themes'}),
171
182
  ).rejects.toMatchObject({
172
183
  code: 'ERR_THEME_INVALID',
173
- message: expect.stringContaining('tokens/colors.ts'),
184
+ message: expect.stringContaining('./tokens/colors'),
174
185
  });
175
186
  });
176
187
 
@@ -9,8 +9,13 @@ import {BUNDLED_THEME_PACKAGE} from '../../../foundation/discovery/theme-discove
9
9
  let tmpDir;
10
10
 
11
11
  function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
12
- const packageDir = path.join(tmpDir, 'node_modules', ...packageName.split('/'));
12
+ const packageDir = path.join(
13
+ tmpDir,
14
+ 'node_modules',
15
+ ...packageName.split('/'),
16
+ );
13
17
  const themeDir = path.join(packageDir, 'themes', slug);
18
+ const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
14
19
  fs.mkdirSync(themeDir, {recursive: true});
15
20
  fs.writeFileSync(
16
21
  path.join(packageDir, 'package.json'),
@@ -18,28 +23,19 @@ function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
18
23
  );
19
24
  fs.writeFileSync(
20
25
  path.join(packageDir, 'astryx.integration.mjs'),
21
- `export default {themes: './themes'};\n`,
26
+ `export default {themes: './themes'};
27
+ `,
22
28
  );
23
29
  fs.writeFileSync(
24
- path.join(packageDir, 'themes', 'manifest.json'),
25
- JSON.stringify({
26
- version: 1,
27
- themes: [
28
- {
29
- slug,
30
- displayName: 'Ocean',
31
- description: 'Blue and calm.',
32
- maintained: true,
33
- entry: 'oceanTheme.ts',
34
- exportName: 'oceanTheme',
35
- files: ['oceanTheme.ts'],
36
- },
37
- ],
38
- }),
30
+ path.join(themeDir, `${stem}.doc.mjs`),
31
+ `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
32
+ export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
33
+ `,
39
34
  );
40
35
  fs.writeFileSync(
41
- path.join(themeDir, 'oceanTheme.ts'),
42
- 'export const oceanTheme = {};\n',
36
+ path.join(themeDir, `${stem}.ts`),
37
+ `export const ${stem} = {};
38
+ `,
43
39
  );
44
40
  }
45
41
 
@@ -47,7 +43,10 @@ beforeEach(() => {
47
43
  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-theme-list-'));
48
44
  fs.writeFileSync(
49
45
  path.join(tmpDir, 'package.json'),
50
- JSON.stringify({name: 'consumer', dependencies: {'@acme/themes': '^1.0.0'}}),
46
+ JSON.stringify({
47
+ name: 'consumer',
48
+ dependencies: {'@acme/themes': '^1.0.0'},
49
+ }),
51
50
  );
52
51
  });
53
52
 
@@ -9,25 +9,26 @@ export const doc = {
9
9
  type: 'function',
10
10
  kind: 'api',
11
11
  name: 'listThemes',
12
+ namespace: 'cli/api',
12
13
  displayName: 'listThemes()',
13
- summary: 'Read the CLI bundled-theme manifest.',
14
+ summary: 'Read the CLI bundled-theme descriptors.',
14
15
  description:
15
- 'Reads templates/themes/manifest.json and returns its raw entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
16
+ 'Reads the typed same-stem descriptors under templates/themes and returns normalized entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
16
17
  importPath: '@astryxdesign/cli/api',
17
18
  signature: 'listThemes(): BundledTheme[]',
18
- keywords: ['theme', 'themes', 'manifest', 'bundled', 'adapter', 'list'],
19
+ keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],
19
20
  params: [],
20
21
  returns: [
21
22
  {
22
23
  type: 'BundledTheme[]',
23
24
  description:
24
- 'The bundled manifest entries: slug, displayName, description, maintained, entry, exportName, and files.',
25
+ 'The normalized bundled descriptor entries: slug, displayName, description, maintained, entry, exportName, and files.',
25
26
  },
26
27
  ],
27
28
  throws: [
28
29
  {
29
30
  code: 'ERR_NO_SOURCE',
30
- when: 'the bundled catalog is missing, invalid, or references missing source files',
31
+ when: 'the bundled descriptors are missing, invalid, or have missing source files',
31
32
  },
32
33
  ],
33
34
  examples: [
@@ -86,7 +86,8 @@ function serializePalette(palette, indentation = 0) {
86
86
 
87
87
  /** @param {TonalPaletteCandidate} candidate */
88
88
  export function serializePaletteCandidate(candidate) {
89
- return `{\n "schemaVersion": 1,\n "status": "candidate",\n "recipe": ${JSON.stringify(candidate.recipe)},\n "black": ${JSON.stringify(candidate.black)},\n "white": ${JSON.stringify(candidate.white)},\n "stops": ${JSON.stringify(candidate.stops)},\n "palette": ${serializePalette(candidate.palette, 2)}\n}\n`;
89
+ const stops = candidate.stops.map(stop => ` ${JSON.stringify(stop)}`);
90
+ return `{\n "schemaVersion": 1,\n "status": "candidate",\n "recipe": ${JSON.stringify(candidate.recipe)},\n "black": ${JSON.stringify(candidate.black)},\n "white": ${JSON.stringify(candidate.white)},\n "stops": [\n${stops.join(',\n')}\n ],\n "palette": ${serializePalette(candidate.palette, 2)}\n}\n`;
90
91
  }
91
92
 
92
93
  /** @param {TonalPaletteCandidate} candidate @param {string} outputPath */
@@ -100,7 +101,7 @@ function serializeCandidate(candidate, outputPath) {
100
101
  );
101
102
  }
102
103
 
103
- /** @param {PaletteGenerationResult} result @param {string} candidateText @param {string | null} [previewText] */
104
+ /** @param {PaletteGenerationResult} result @param {string} candidateText @param {string | null} [previewText] @returns {import('../../theme.type.mjs').TonalPaletteGenerationReceipt} */
104
105
  function receiptFor(result, candidateText, previewText = null) {
105
106
  return {
106
107
  schemaVersion: 1,
@@ -168,7 +169,11 @@ function existingFileIdentity(filePath) {
168
169
  ) {
169
170
  return null;
170
171
  }
171
- throw error;
172
+ throw new AstryxError(
173
+ `Could not write palette candidate: ${error instanceof Error ? error.message : String(error)}`,
174
+ undefined,
175
+ ERROR_CODES.ERR_WRITE_FAILED,
176
+ );
172
177
  }
173
178
  }
174
179
 
@@ -1,9 +1,11 @@
1
1
  // Copyright (c) Meta Platforms, Inc. and affiliates.
2
2
 
3
+ import {createHash} from 'node:crypto';
3
4
  import * as fs from 'node:fs';
4
5
  import * as os from 'node:os';
5
6
  import * as path from 'node:path';
6
7
  import {afterEach, describe, expect, it} from 'vitest';
8
+ import {isErrorCode} from '../../../../foundation/response/error-codes.mjs';
7
9
  import {themePaletteGenerate} from './generate.mjs';
8
10
 
9
11
  const temporaryDirectories = [];
@@ -101,6 +103,81 @@ describe('themePaletteGenerate', () => {
101
103
  expect(result.data.receipt).toBe('ocean.palette.receipt.json');
102
104
  });
103
105
 
106
+ it('writes candidate JSON byte-identical to the recipe fixtures', () => {
107
+ const families = [
108
+ {id: 'neutral', name: 'Neutral', seed: '#777777', kind: 'neutral'},
109
+ {id: 'blue', name: 'Blue', seed: '#0074e2'},
110
+ {id: 'orange', name: 'Orange', seed: '#d57113'},
111
+ ];
112
+ const fixtures = [
113
+ [
114
+ {families},
115
+ 3755,
116
+ '11c40191d508274d89d631bb4e1cb662f70ff0dce6c0dec101c317f9f69d3e25',
117
+ ],
118
+ [
119
+ {
120
+ modeStrategy: 'light-only',
121
+ stops: [20, 50, 80],
122
+ families: [
123
+ {
124
+ id: 'blue',
125
+ name: 'Blue',
126
+ seed: '#0074e2',
127
+ anchors: [
128
+ {mode: 'light', stop: 50, color: '#1682d5', policy: 'exact'},
129
+ ],
130
+ },
131
+ ],
132
+ },
133
+ 327,
134
+ 'c42929be3c4b5cb857cada078f62bb5a2242c1a22cfa4ae7546a18592540f7f3',
135
+ ],
136
+ [
137
+ {
138
+ modeStrategy: 'dark-only',
139
+ stops: [40],
140
+ families: [{id: 'red', name: 'Red', seed: '#d62830'}],
141
+ },
142
+ 258,
143
+ '88d3d69865c74c7fb14347b9967575285a7d44ab893087a08bc842bb66b29bbb',
144
+ ],
145
+ [
146
+ {
147
+ stops: [60, 80, 95],
148
+ families: [
149
+ {id: 'green', name: 'Green', seed: '#358a3a'},
150
+ {id: 'teal', name: 'Teal', seed: '#0c7365'},
151
+ {id: 'cyan', name: 'Cyan', seed: '#0c6f82'},
152
+ ],
153
+ },
154
+ 910,
155
+ '873821574fdbe3357304dbc06986bd2e5ec88af80d0f36305626fd826c3cf07b',
156
+ ],
157
+ ];
158
+
159
+ for (const [request, bytes, sha256] of fixtures) {
160
+ const cwd = fixture();
161
+ fs.writeFileSync(
162
+ path.join(cwd, 'palette.config.json'),
163
+ JSON.stringify(request),
164
+ );
165
+
166
+ const printed = themePaletteGenerate('palette.config.json', {}, {cwd});
167
+ expect(printed.data.generationReceipt.candidateSha256).toBe(sha256);
168
+
169
+ const result = themePaletteGenerate(
170
+ 'palette.config.json',
171
+ {out: 'candidate.json'},
172
+ {cwd},
173
+ );
174
+ const written = fs.readFileSync(path.join(cwd, 'candidate.json'));
175
+ expect(written.length).toBe(bytes);
176
+ expect(createHash('sha256').update(written).digest('hex')).toBe(sha256);
177
+ expect(result.data.generationReceipt.candidateSha256).toBe(sha256);
178
+ }
179
+ });
180
+
104
181
  it('preserves mixed decimal and integer stop order in every artifact', () => {
105
182
  const cwd = fixture();
106
183
  fs.writeFileSync(
@@ -267,4 +344,23 @@ describe('themePaletteGenerate', () => {
267
344
  themePaletteGenerate('palette.config.json', {}, {cwd}),
268
345
  ).toThrow('Could not parse palette config');
269
346
  });
347
+
348
+ it('reports an output path it cannot use with a registered error code', () => {
349
+ const cwd = fixture();
350
+ fs.writeFileSync(path.join(cwd, 'blocker'), '');
351
+
352
+ for (const options of [
353
+ {out: 'blocker/ocean.palette.json'},
354
+ {preview: 'blocker/ocean.palette.html'},
355
+ ]) {
356
+ let error;
357
+ try {
358
+ themePaletteGenerate('palette.config.json', options, {cwd});
359
+ } catch (caught) {
360
+ error = caught;
361
+ }
362
+ expect(error).toMatchObject({code: 'ERR_WRITE_FAILED'});
363
+ expect(isErrorCode(error.code)).toBe(true);
364
+ }
365
+ });
270
366
  });
@@ -22,15 +22,17 @@ export function generateTonalPalette(input: import("../../theme.type.mjs").Tonal
22
22
  export function serializeGenerationResult(result: unknown): string;
23
23
  /** @typedef {import('../../theme.type.mjs').TonalPaletteAnchor} TonalPaletteAnchor */
24
24
  /** @typedef {import('../../theme.type.mjs').TonalPaletteGenerationInput} TonalPaletteGenerationInput */
25
+ /** @typedef {import('../../theme.type.mjs').TonalPaletteRampDiagnostics} TonalPaletteRampDiagnostics */
26
+ /** @typedef {import('../../theme.type.mjs').TonalPaletteCoordinationDiagnostics} TonalPaletteCoordinationDiagnostics */
27
+ /** @typedef {import('../../theme.type.mjs').TonalPaletteNormalizedRequest} NormalizedRequest */
25
28
  /** @typedef {[number, number, number]} ColorTriple */
26
29
  /** @typedef {'light' | 'dark'} PaletteMode */
27
30
  /** @typedef {{lightness: number, chroma: number, hue: number}} PolarColor */
28
31
  /** @typedef {TonalPaletteAnchor & {color: string, generatedColor: string, deltaE: number}} AnchorResult */
29
- /** @typedef {{colors: Record<number, string>, diagnostics: Record<string, unknown>}} GeneratedRamp */
32
+ /** @typedef {{colors: Record<number, string>, diagnostics: TonalPaletteRampDiagnostics}} GeneratedRamp */
30
33
  /** @typedef {{id: string, name: string, seed: string, kind: 'chromatic' | 'neutral', anchors: TonalPaletteAnchor[]}} NormalizedFamily */
31
- /** @typedef {{recipe: typeof PALETTE_RECIPE, vibrancy: number, neutralProfile: string, modeStrategy: string, stops: number[], families: NormalizedFamily[]}} NormalizedRequest */
32
34
  /** @typedef {{id: string, name: string, seed: string, light?: GeneratedRamp, dark?: GeneratedRamp}} GeneratedFamily */
33
- /** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: Record<string, unknown>[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
35
+ /** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: TonalPaletteCoordinationDiagnostics[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
34
36
  export const PALETTE_RECIPE: "astryx-oklch-v1";
35
37
  export const PALETTE_BLACK: "#000000";
36
38
  export const PALETTE_WHITE: "#ffffff";
@@ -38,6 +40,9 @@ export const DEFAULT_21_STOPS: readonly number[];
38
40
  export const COMPACT_11_STOPS: readonly number[];
39
41
  export type TonalPaletteAnchor = import("../../theme.type.mjs").TonalPaletteAnchor;
40
42
  export type TonalPaletteGenerationInput = import("../../theme.type.mjs").TonalPaletteGenerationInput;
43
+ export type TonalPaletteRampDiagnostics = import("../../theme.type.mjs").TonalPaletteRampDiagnostics;
44
+ export type TonalPaletteCoordinationDiagnostics = import("../../theme.type.mjs").TonalPaletteCoordinationDiagnostics;
45
+ export type NormalizedRequest = import("../../theme.type.mjs").TonalPaletteNormalizedRequest;
41
46
  export type ColorTriple = [number, number, number];
42
47
  export type PaletteMode = "light" | "dark";
43
48
  export type PolarColor = {
@@ -52,7 +57,7 @@ export type AnchorResult = TonalPaletteAnchor & {
52
57
  };
53
58
  export type GeneratedRamp = {
54
59
  colors: Record<number, string>;
55
- diagnostics: Record<string, unknown>;
60
+ diagnostics: TonalPaletteRampDiagnostics;
56
61
  };
57
62
  export type NormalizedFamily = {
58
63
  id: string;
@@ -61,14 +66,6 @@ export type NormalizedFamily = {
61
66
  kind: "chromatic" | "neutral";
62
67
  anchors: TonalPaletteAnchor[];
63
68
  };
64
- export type NormalizedRequest = {
65
- recipe: typeof PALETTE_RECIPE;
66
- vibrancy: number;
67
- neutralProfile: string;
68
- modeStrategy: string;
69
- stops: number[];
70
- families: NormalizedFamily[];
71
- };
72
69
  export type GeneratedFamily = {
73
70
  id: string;
74
71
  name: string;
@@ -81,7 +78,7 @@ export type PaletteGenerationResult = {
81
78
  status: "candidate";
82
79
  request: NormalizedRequest;
83
80
  families: GeneratedFamily[];
84
- coordination: Record<string, unknown>[];
81
+ coordination: TonalPaletteCoordinationDiagnostics[];
85
82
  errors: {
86
83
  familyId: string;
87
84
  message: string;
@@ -12,15 +12,17 @@ import {
12
12
 
13
13
  /** @typedef {import('../../theme.type.mjs').TonalPaletteAnchor} TonalPaletteAnchor */
14
14
  /** @typedef {import('../../theme.type.mjs').TonalPaletteGenerationInput} TonalPaletteGenerationInput */
15
+ /** @typedef {import('../../theme.type.mjs').TonalPaletteRampDiagnostics} TonalPaletteRampDiagnostics */
16
+ /** @typedef {import('../../theme.type.mjs').TonalPaletteCoordinationDiagnostics} TonalPaletteCoordinationDiagnostics */
17
+ /** @typedef {import('../../theme.type.mjs').TonalPaletteNormalizedRequest} NormalizedRequest */
15
18
  /** @typedef {[number, number, number]} ColorTriple */
16
19
  /** @typedef {'light' | 'dark'} PaletteMode */
17
20
  /** @typedef {{lightness: number, chroma: number, hue: number}} PolarColor */
18
21
  /** @typedef {TonalPaletteAnchor & {color: string, generatedColor: string, deltaE: number}} AnchorResult */
19
- /** @typedef {{colors: Record<number, string>, diagnostics: Record<string, unknown>}} GeneratedRamp */
22
+ /** @typedef {{colors: Record<number, string>, diagnostics: TonalPaletteRampDiagnostics}} GeneratedRamp */
20
23
  /** @typedef {{id: string, name: string, seed: string, kind: 'chromatic' | 'neutral', anchors: TonalPaletteAnchor[]}} NormalizedFamily */
21
- /** @typedef {{recipe: typeof PALETTE_RECIPE, vibrancy: number, neutralProfile: string, modeStrategy: string, stops: number[], families: NormalizedFamily[]}} NormalizedRequest */
22
24
  /** @typedef {{id: string, name: string, seed: string, light?: GeneratedRamp, dark?: GeneratedRamp}} GeneratedFamily */
23
- /** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: Record<string, unknown>[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
25
+ /** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: TonalPaletteCoordinationDiagnostics[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
24
26
 
25
27
  export const PALETTE_RECIPE = 'astryx-oklch-v1';
26
28
  export const PALETTE_BLACK = '#000000';
@@ -35,6 +37,7 @@ export const COMPACT_11_STOPS = Object.freeze([
35
37
 
36
38
  const DARK_CHROMA_FACTOR = 0.85;
37
39
  const RESERVED_FAMILY_IDS = new Set(['black', 'white']);
40
+ const NEUTRAL_PROFILES = ['neutral-v1', 'warm-v1', 'cool-v1', 'custom'];
38
41
 
39
42
  /** @param {number} value @param {number} minimum @param {number} maximum */
40
43
  function clamp(value, minimum, maximum) {
@@ -411,6 +414,7 @@ function buildDiagnostics(colors, stops, sourceHue, gamutMappedStops, anchors) {
411
414
  let minimumAdjacentDeltaE = Number.POSITIVE_INFINITY;
412
415
  let maximumAdjacentDeltaE = 0;
413
416
  let maximumHueDrift = 0;
417
+ /** @type {TonalPaletteRampDiagnostics['hueIdentityRisk']} */
414
418
  let hueIdentityRisk = null;
415
419
  for (let index = 0; index < stops.length; index++) {
416
420
  const stop = stops[index];
@@ -526,6 +530,7 @@ function buildCoordinationDiagnostics(request, families) {
526
530
  chroma: hexToOklch(color).C,
527
531
  };
528
532
  });
533
+ /** @type {[string, string] | null} */
529
534
  let closestFamilies = null;
530
535
  let minimumFamilyDeltaE = Number.POSITIVE_INFINITY;
531
536
  for (let index = 0; index < samples.length; index++) {
@@ -661,11 +666,17 @@ export function normalizeGenerationRequest(input) {
661
666
  anchors,
662
667
  };
663
668
  });
669
+ const neutralProfile = input.neutralProfile ?? 'neutral-v1';
670
+ // The receipt records this request, so an unknown profile fails even when no
671
+ // neutral family reads it.
672
+ if (!NEUTRAL_PROFILES.includes(neutralProfile)) {
673
+ throw new Error(`Unknown neutral profile: ${String(neutralProfile)}`);
674
+ }
664
675
  /** @type {NormalizedRequest} */
665
676
  const request = {
666
677
  recipe: PALETTE_RECIPE,
667
678
  vibrancy: input.vibrancy ?? 50,
668
- neutralProfile: input.neutralProfile ?? 'neutral-v1',
679
+ neutralProfile,
669
680
  modeStrategy,
670
681
  stops,
671
682
  families: normalizedFamilies,
@@ -293,6 +293,16 @@ describe('astryx-oklch-v1 palette generator', () => {
293
293
  ).toThrow('Anchor mode dark is not generated by mode strategy light-only');
294
294
  });
295
295
 
296
+ it('rejects an unknown neutral profile even without a neutral family', () => {
297
+ expect(() =>
298
+ generatePaletteSet({neutralProfile: 'warm-v2', families: [families[1]]}),
299
+ ).toThrow('Unknown neutral profile: warm-v2');
300
+ expect(
301
+ generatePaletteSet({neutralProfile: 'warm-v1', families: [families[1]]})
302
+ .request.neutralProfile,
303
+ ).toBe('warm-v1');
304
+ });
305
+
296
306
  it('normalizes anchor colors in the generation receipt', () => {
297
307
  const result = generatePaletteSet({
298
308
  modeStrategy: 'light-only',
@@ -62,8 +62,17 @@ export function themeTemplate(options = {}) {
62
62
 
63
63
  // Our repo header has no business in someone else's source tree.
64
64
  const contents = stripCopyrightHeader(fs.readFileSync(THEME_TEMPLATE_SRC, 'utf-8'));
65
- fs.mkdirSync(path.dirname(resolved), {recursive: true});
66
- fs.writeFileSync(resolved, contents);
65
+ try {
66
+ fs.mkdirSync(path.dirname(resolved), {recursive: true});
67
+ fs.writeFileSync(resolved, contents);
68
+ } catch (err) {
69
+ const message = err instanceof Error ? err.message : String(err);
70
+ throw new AstryxError(
71
+ `Failed to write the theme template to ${relative}: ${message}`,
72
+ undefined,
73
+ ERROR_CODES.ERR_WRITE_FAILED,
74
+ );
75
+ }
67
76
 
68
77
  return {type: 'theme.template', data: {path: relative, written: true, reason: null}};
69
78
  }
@@ -13,7 +13,9 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
13
13
  import * as fs from 'node:fs';
14
14
  import * as path from 'node:path';
15
15
  import * as os from 'node:os';
16
+ import {themeTemplate as publicThemeTemplate} from '../../index.mjs';
16
17
  import {themeTemplate, THEME_TEMPLATE_DEFAULT_PATH} from './template.mjs';
18
+ import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
17
19
 
18
20
  let tmpDir;
19
21
  beforeEach(() => {
@@ -24,6 +26,10 @@ afterEach(() => {
24
26
  });
25
27
 
26
28
  describe('themeTemplate()', () => {
29
+ it('is available through the public API entry point', () => {
30
+ expect(publicThemeTemplate).toBe(themeTemplate);
31
+ });
32
+
27
33
  it('writes the template and returns a theme.template receipt', () => {
28
34
  const res = themeTemplate({cwd: tmpDir});
29
35
 
@@ -79,4 +85,18 @@ describe('themeTemplate()', () => {
79
85
  );
80
86
  expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
81
87
  });
88
+
89
+ it('reports a failed write with a registered error code', () => {
90
+ fs.writeFileSync(path.join(tmpDir, 'blocker'), '');
91
+
92
+ let error;
93
+ try {
94
+ themeTemplate({cwd: tmpDir, targetPath: 'blocker/theme.ts'});
95
+ } catch (caught) {
96
+ error = caught;
97
+ }
98
+
99
+ expect(error).toMatchObject({code: 'ERR_WRITE_FAILED'});
100
+ expect(isErrorCode(error.code)).toBe(true);
101
+ });
82
102
  });