@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
@@ -15,7 +15,10 @@
15
15
  */
16
16
 
17
17
  import {findCoreDir} from '../../foundation/fs/paths.mjs';
18
- import {findHookDoc, getAllHookNames} from '../../foundation/discovery/hook-discovery.mjs';
18
+ import {
19
+ findHookDoc,
20
+ getAllHookNames,
21
+ } from '../../foundation/discovery/hook-discovery.mjs';
19
22
  import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
20
23
  import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
21
24
  import {AstryxError} from '../error.mjs';
@@ -30,7 +33,11 @@ import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
30
33
  export function resolveCoreDir(cwd) {
31
34
  const coreDir = findCoreDir(cwd);
32
35
  if (!coreDir) {
33
- throw new AstryxError('Could not find @astryxdesign/core package', undefined, ERROR_CODES.ERR_CORE_NOT_FOUND);
36
+ throw new AstryxError(
37
+ 'Could not find @astryxdesign/core package',
38
+ undefined,
39
+ ERROR_CODES.ERR_CORE_NOT_FOUND,
40
+ );
34
41
  }
35
42
  return coreDir;
36
43
  }
@@ -44,7 +51,11 @@ export function resolveCoreDir(cwd) {
44
51
  * @param {{zh?: boolean, lang?: string|null}} [opts]
45
52
  * @returns {Promise<import('./hook.type.mjs').HookDoc>}
46
53
  */
47
- export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} = {}) {
54
+ export async function resolveHookDoc(
55
+ coreDir,
56
+ name,
57
+ {zh = false, lang = null} = {},
58
+ ) {
48
59
  const docPath = findHookDoc(coreDir, name);
49
60
 
50
61
  if (!docPath) {
@@ -59,7 +70,10 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
59
70
  .filter(m => m.distance <= 5)
60
71
  .sort((a, b) => a.distance - b.distance)
61
72
  .slice(0, 5)
62
- .map(m => ({name: m.name, reason: `similar name (distance ${m.distance})`}));
73
+ .map(m => ({
74
+ name: m.name,
75
+ reason: `similar name (distance ${m.distance})`,
76
+ }));
63
77
 
64
78
  throw new AstryxError(
65
79
  `No hook named "${name}"`,
@@ -68,5 +82,5 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
68
82
  );
69
83
  }
70
84
 
71
- return loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
85
+ return loadDocs(docPath, {zh, lang, root: 'hooks'});
72
86
  }
@@ -11,6 +11,7 @@ export const doc = {
11
11
  type: 'function',
12
12
  kind: 'api',
13
13
  name: 'hook',
14
+ namespace: 'cli/api',
14
15
  displayName: 'hook()',
15
16
  summary:
16
17
  'Resolve a hook by name, or list the catalog, with an optional params-only slice.',
@@ -4,7 +4,7 @@
4
4
  export type HookDoc = import("@astryxdesign/cli/authoring").HookDoc;
5
5
  export type HookParamDoc = import("@astryxdesign/cli/authoring").HookParamDoc;
6
6
  /**
7
- * xds --json hook [--list] [--category X] [--detail names|compact|full]
7
+ * astryx --json hook [--list] [--category X] [--detail names|compact|full]
8
8
  *
9
9
  * The list view emits ONE `hook.list` type across all three detail levels; the
10
10
  * depth is carried in `data.detail` and `data.components` holds the grouped map
@@ -39,14 +39,14 @@ export type HookBriefEntry = {
39
39
  import: string;
40
40
  };
41
41
  /**
42
- * xds --json hook <name>
42
+ * astryx --json hook <name>
43
43
  */
44
44
  export type HookDetailResponse = {
45
45
  type: "hook.detail";
46
46
  data: HookDoc;
47
47
  };
48
48
  /**
49
- * xds --json hook <name> --params
49
+ * astryx --json hook <name> --params
50
50
  */
51
51
  export type HookDetailParamsResponse = {
52
52
  type: "hook.detail.params";
@@ -11,14 +11,14 @@
11
11
  *
12
12
  * Invocation -> type discriminator
13
13
  * ------------------------------------------------------------------
14
- * xds --json hook -> hook.list (data.detail='names')
15
- * xds --json hook --list -> hook.list (data.detail='names')
16
- * xds --json hook --category State -> hook.list (filtered)
17
- * xds --json hook --list --detail compact -> hook.list (data.detail='compact')
18
- * xds --json hook --list --detail full -> hook.list (data.detail='full')
19
- * xds --json hook useMediaQuery -> hook.detail
20
- * xds --json hook useMediaQuery --params -> hook.detail.params
21
- * (not found) -> CLIError
14
+ * astryx --json hook -> hook.list (data.detail='names')
15
+ * astryx --json hook --list -> hook.list (data.detail='names')
16
+ * astryx --json hook --category State -> hook.list (filtered)
17
+ * astryx --json hook --list --detail compact -> hook.list (data.detail='compact')
18
+ * astryx --json hook --list --detail full -> hook.list (data.detail='full')
19
+ * astryx --json hook useMediaQuery -> hook.detail
20
+ * astryx --json hook useMediaQuery --params -> hook.detail.params
21
+ * (not found) -> CLIError
22
22
  */
23
23
 
24
24
  // Re-export the authored-doc types from core so the hook leaves reference these
@@ -28,7 +28,7 @@
28
28
  /** @typedef {import('@astryxdesign/cli/authoring').HookParamDoc} HookParamDoc */
29
29
 
30
30
  /**
31
- * xds --json hook [--list] [--category X] [--detail names|compact|full]
31
+ * astryx --json hook [--list] [--category X] [--detail names|compact|full]
32
32
  *
33
33
  * The list view emits ONE `hook.list` type across all three detail levels; the
34
34
  * depth is carried in `data.detail` and `data.components` holds the grouped map
@@ -56,14 +56,14 @@
56
56
  */
57
57
 
58
58
  /**
59
- * xds --json hook <name>
59
+ * astryx --json hook <name>
60
60
  * @typedef {object} HookDetailResponse
61
61
  * @property {'hook.detail'} type
62
62
  * @property {HookDoc} data
63
63
  */
64
64
 
65
65
  /**
66
- * xds --json hook <name> --params
66
+ * astryx --json hook <name> --params
67
67
  * @typedef {object} HookDetailParamsResponse
68
68
  * @property {'hook.detail.params'} type
69
69
  * @property {HookParamDoc[]} data
@@ -10,10 +10,10 @@
10
10
  * @param {string|null} [options.lang]
11
11
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
12
12
  */
13
- export function list({ cwd, category, detail, zh, lang }?: {
13
+ export function list({ cwd, category, detail, zh, lang, }?: {
14
14
  cwd?: string | undefined;
15
15
  category?: string | undefined;
16
- detail?: "names" | "compact" | "full" | "brief" | undefined;
16
+ detail?: "compact" | "full" | "names" | "brief" | undefined;
17
17
  zh?: boolean | undefined;
18
18
  lang?: string | null | undefined;
19
19
  }): Promise<import("../hook.type.mjs").HookListResponse>;
@@ -13,7 +13,10 @@
13
13
  * @position api/hook/list/list.mjs — dispatched from ../hook.mjs
14
14
  */
15
15
 
16
- import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
16
+ import {
17
+ discoverHooks,
18
+ findHookDoc,
19
+ } from '../../../foundation/discovery/hook-discovery.mjs';
17
20
  import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
18
21
  import {AstryxError} from '../../error.mjs';
19
22
  import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -28,7 +31,13 @@ import {resolveCoreDir} from '../_adapter.mjs';
28
31
  * @param {string|null} [options.lang]
29
32
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
30
33
  */
31
- export async function list({cwd = process.cwd(), category, detail = 'names', zh = false, lang = null} = {}) {
34
+ export async function list({
35
+ cwd = process.cwd(),
36
+ category,
37
+ detail = 'names',
38
+ zh = false,
39
+ lang = null,
40
+ } = {}) {
32
41
  const coreDir = resolveCoreDir(cwd);
33
42
  const hooks = discoverHooks(coreDir);
34
43
 
@@ -51,20 +60,31 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
51
60
  const docPath = findHookDoc(coreDir, hookName);
52
61
  if (docPath) {
53
62
  try {
54
- const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
63
+ const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
55
64
  entries.push({
56
65
  name: hookName,
57
66
  description: docs.usage?.description || '',
58
67
  import: docs.importPath || '@astryxdesign/core/hooks',
59
68
  });
60
69
  } catch {
61
- entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
70
+ entries.push({
71
+ name: hookName,
72
+ description: '',
73
+ import: '@astryxdesign/core/hooks',
74
+ });
62
75
  }
63
76
  } else {
64
- entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
77
+ entries.push({
78
+ name: hookName,
79
+ description: '',
80
+ import: '@astryxdesign/core/hooks',
81
+ });
65
82
  }
66
83
  }
67
- return {type: 'hook.list', data: {detail: 'compact', components: {[match[0]]: entries}}};
84
+ return {
85
+ type: 'hook.list',
86
+ data: {detail: 'compact', components: {[match[0]]: entries}},
87
+ };
68
88
  }
69
89
 
70
90
  if (detail === 'full') {
@@ -74,19 +94,33 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
74
94
  const docPath = findHookDoc(coreDir, hookName);
75
95
  if (docPath) {
76
96
  try {
77
- entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
97
+ entries.push(await loadDocs(docPath, {zh, lang, root: 'hooks'}));
78
98
  } catch {
79
- entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
99
+ entries.push(
100
+ /** @type {import('../hook.type.mjs').HookDoc} */ ({
101
+ name: hookName,
102
+ }),
103
+ );
80
104
  }
81
105
  } else {
82
- entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
106
+ entries.push(
107
+ /** @type {import('../hook.type.mjs').HookDoc} */ ({
108
+ name: hookName,
109
+ }),
110
+ );
83
111
  }
84
112
  }
85
- return {type: 'hook.list', data: {detail: 'full', components: {[match[0]]: entries}}};
113
+ return {
114
+ type: 'hook.list',
115
+ data: {detail: 'full', components: {[match[0]]: entries}},
116
+ };
86
117
  }
87
118
 
88
119
  // Default: names only
89
- return {type: 'hook.list', data: {detail: 'names', components: {[match[0]]: match[1]}}};
120
+ return {
121
+ type: 'hook.list',
122
+ data: {detail: 'names', components: {[match[0]]: match[1]}},
123
+ };
90
124
  }
91
125
 
92
126
  // All hooks
@@ -99,17 +133,25 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
99
133
  const docPath = findHookDoc(coreDir, hookName);
100
134
  if (docPath) {
101
135
  try {
102
- const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
136
+ const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
103
137
  result[cat].push({
104
138
  name: hookName,
105
139
  description: docs.usage?.description || '',
106
140
  import: docs.importPath || '@astryxdesign/core/hooks',
107
141
  });
108
142
  } catch {
109
- result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
143
+ result[cat].push({
144
+ name: hookName,
145
+ description: '',
146
+ import: '@astryxdesign/core/hooks',
147
+ });
110
148
  }
111
149
  } else {
112
- result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
150
+ result[cat].push({
151
+ name: hookName,
152
+ description: '',
153
+ import: '@astryxdesign/core/hooks',
154
+ });
113
155
  }
114
156
  }
115
157
  }
@@ -125,12 +167,22 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
125
167
  const docPath = findHookDoc(coreDir, hookName);
126
168
  if (docPath) {
127
169
  try {
128
- result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
170
+ result[cat].push(
171
+ await loadDocs(docPath, {zh, lang, root: 'hooks'}),
172
+ );
129
173
  } catch {
130
- result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
174
+ result[cat].push(
175
+ /** @type {import('../hook.type.mjs').HookDoc} */ ({
176
+ name: hookName,
177
+ }),
178
+ );
131
179
  }
132
180
  } else {
133
- result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
181
+ result[cat].push(
182
+ /** @type {import('../hook.type.mjs').HookDoc} */ ({
183
+ name: hookName,
184
+ }),
185
+ );
134
186
  }
135
187
  }
136
188
  }
package/api/index.d.mts CHANGED
@@ -38,7 +38,7 @@ export * from "./integration/pack-check.type.mjs";
38
38
  export * from "./integration/validate-integration.type.mjs";
39
39
  export * from "./integration/authoring-checks.type.mjs";
40
40
  export type Logger = import("./logger.mjs").Logger;
41
- export { themeBuild, themeAdd, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
41
+ export { themeBuild, themeAdd, themeTemplate, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
42
42
  export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
43
43
  export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
44
44
  export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";
package/api/index.mjs CHANGED
@@ -28,6 +28,7 @@ export {template} from './template/template.mjs';
28
28
  export {
29
29
  themeBuild,
30
30
  themeAdd,
31
+ themeTemplate,
31
32
  themeList,
32
33
  themeListAvailable,
33
34
  themeTargets,
@@ -11,6 +11,7 @@ export const doc = {
11
11
  type: 'function',
12
12
  kind: 'api',
13
13
  name: 'init',
14
+ namespace: 'cli/api',
14
15
  displayName: 'init()',
15
16
  summary:
16
17
  'Non-interactive project setup: install agent docs and point at the theme + build workflows.',
@@ -90,6 +91,10 @@ export const doc = {
90
91
  code: 'ERR_FILE_EXISTS',
91
92
  when: 'scaffolding a template would overwrite an existing page.tsx',
92
93
  },
94
+ {
95
+ code: 'ERR_PATH_TRAVERSAL',
96
+ when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
97
+ },
93
98
  ],
94
99
  examples: [
95
100
  {label: 'Default setup', code: 'const r = await init();'},
@@ -97,5 +102,5 @@ export const doc = {
97
102
  {label: 'Remove agent docs', code: 'await init({removeAgents: true});'},
98
103
  ],
99
104
  command: 'init',
100
- related: ['doctor', 'upgrade', 'build', 'theme'],
105
+ related: ['doctor', 'upgrade', 'build', 'themeTemplate'],
101
106
  };
@@ -230,13 +230,40 @@ describe('init() — logger', () => {
230
230
  errSpy.mockRestore();
231
231
  }
232
232
  const text = lines.join('\n');
233
- expect(text).toContain('✓ AI agent docs installed → AGENTS.md');
233
+ expect(text).toContain('[ok] AI agent docs installed -> AGENTS.md');
234
234
  expect(text).toContain(' Next steps:');
235
235
  // The exact next-steps block the CLI prints comes from getNextSteps().
236
236
  expect(text).toContain(getNextSteps('npx astryx')[2].slice(0, 20));
237
237
  });
238
238
  });
239
239
 
240
+ describe('init() — ASCII output', () => {
241
+ it('prints only ASCII on the default, all-features, re-run, template, and remove paths', async () => {
242
+ /** @type {string[]} */
243
+ const lines = [];
244
+ const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
245
+ const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(a.join(' ')));
246
+ const empty = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-remove-'));
247
+ logger.setSilent(false);
248
+ try {
249
+ await init({}, {cwd: tmpDir});
250
+ await init({all: true}, {cwd: tmpDir});
251
+ await init({all: true}, {cwd: tmpDir});
252
+ await init({features: 'template', templateName: 'blank'}, {cwd: tmpDir});
253
+ await init({removeAgents: true}, {cwd: tmpDir});
254
+ await init({removeAgents: true}, {cwd: empty});
255
+ } finally {
256
+ logger.setSilent(true);
257
+ logSpy.mockRestore();
258
+ errSpy.mockRestore();
259
+ fs.rmSync(empty, {recursive: true, force: true});
260
+ }
261
+ expect(lines.length).toBeGreaterThan(0);
262
+ expect(lines.some(line => line.startsWith('[ok] Removed'))).toBe(true);
263
+ expect(lines.filter(line => /[\u0080-\uFFFF]/.test(line))).toEqual([]);
264
+ });
265
+ });
266
+
240
267
  describe('init() — write-path safety', () => {
241
268
  it('template scaffold refuses to clobber an existing page.tsx', async () => {
242
269
  const dest = path.join(tmpDir, 'src', 'pages', 'blank');
@@ -260,4 +287,17 @@ describe('init() — write-path safety', () => {
260
287
  init({features: 'template', templateName: '../../etc/evil'}, {cwd: tmpDir}),
261
288
  ).rejects.toMatchObject({code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
262
289
  });
290
+
291
+ it('refuses a template write that a symlinked src would carry outside cwd (ERR_PATH_TRAVERSAL)', async () => {
292
+ const outside = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-outside-'));
293
+ try {
294
+ fs.symlinkSync(outside, path.join(tmpDir, 'src'), 'dir');
295
+ await expect(
296
+ init({features: 'template', templateName: 'blank'}, {cwd: tmpDir}),
297
+ ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
298
+ expect(fs.readdirSync(outside)).toEqual([]);
299
+ } finally {
300
+ fs.rmSync(outside, {recursive: true, force: true});
301
+ }
302
+ });
263
303
  });
@@ -24,6 +24,6 @@ import {logger} from '../../logger.mjs';
24
24
  */
25
25
  export async function remove({cwd = process.cwd()} = {}) {
26
26
  removeAgentDocs(cwd);
27
- logger.log('✓ AI agent docs removed.');
27
+ logger.log('[ok] AI agent docs removed.');
28
28
  return {type: 'init.remove', data: {removed: true}};
29
29
  }
@@ -17,7 +17,7 @@
17
17
  import * as path from 'node:path';
18
18
  import * as fs from 'node:fs';
19
19
  import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
20
- import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
20
+ import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.mjs';
21
21
  import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
22
22
  import {
23
23
  installAgentDocs,
@@ -98,7 +98,7 @@ async function applyAgents(cwd, options, invocation, data) {
98
98
  renderedBlock,
99
99
  });
100
100
  data.docsWritten = written;
101
- logger.log(`✓ AI agent docs installed → ${written.join(', ')}`);
101
+ logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
102
102
  } catch (err) {
103
103
  // PathSafetyError carries a precise, user-actionable message — surface it
104
104
  // (and flag exit 1) instead of the generic "could not install" warning so
@@ -132,8 +132,8 @@ function applyTheme(cwd, invocation, data) {
132
132
  data.themeTemplatePath = didWrite ? written : null;
133
133
  logger.log(
134
134
  didWrite
135
- ? `✓ Theme template written → ${written}`
136
- : `• ${written} already exists — left as is.`,
135
+ ? `[ok] Theme template written -> ${written}`
136
+ : `- ${written} already exists - left as is.`,
137
137
  );
138
138
  } catch {
139
139
  // Soft failure, like agent docs: the guidance below is still useful.
@@ -166,16 +166,16 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
166
166
  // Point agents at the build workflow rather than dumping page-template
167
167
  // names — `build` surfaces pages AND blocks AND components for an idea,
168
168
  // and `build` with no args is the full how-to-build playbook.
169
- logger.log('✓ To build UI, use these commands:');
169
+ logger.log('[ok] To build UI, use these commands:');
170
170
  logger.log('');
171
171
  logger.log(
172
- ` ${invocation} build "<what you're building>" build a page — kit: closest template + blocks + components`,
172
+ ` ${invocation} build "<what you're building>" build a page - kit: closest template + blocks + components`,
173
173
  );
174
174
  logger.log(
175
175
  ` ${invocation} build the how-to-build workflow (read this first)`,
176
176
  );
177
177
  logger.log(
178
- ` ${invocation} search <query> find anything — components, docs, templates, blocks`,
178
+ ` ${invocation} search <query> find anything - components, docs, templates, blocks`,
179
179
  );
180
180
  logger.log('');
181
181
  data.template = 'workflow';
@@ -190,9 +190,19 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
190
190
  );
191
191
  }
192
192
 
193
- const outputDir = path.resolve(cwd, `./src/pages/${templateName}`);
193
+ let destFile;
194
+ try {
195
+ destFile = assertWithin(path.join('src', 'pages', templateName, 'page.tsx'), cwd, {
196
+ label: 'template output path',
197
+ });
198
+ } catch (err) {
199
+ if (err instanceof PathSafetyError) {
200
+ throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
201
+ }
202
+ throw err;
203
+ }
204
+ const outputDir = path.dirname(destFile);
194
205
  const srcPath = path.join(CLI_ROOT, 'assets', 'templates', 'pages', templateName, 'page.tsx');
195
- const destFile = path.join(outputDir, 'page.tsx');
196
206
  // Don't clobber a user's existing page — same guard the peer template/copy and
197
207
  // theme/add write-leaves apply (init is a public API surface too).
198
208
  if (fs.existsSync(destFile)) {
@@ -206,7 +216,7 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
206
216
  fs.mkdirSync(outputDir, {recursive: true});
207
217
  fs.copyFileSync(srcPath, destFile);
208
218
  const rel = path.relative(cwd, outputDir);
209
- logger.log(`✓ Template created at ${rel}/page.tsx`);
219
+ logger.log(`[ok] Template created at ${rel}/page.tsx`);
210
220
  data.template = 'created';
211
221
  data.templatePath = rel;
212
222
  }
@@ -0,0 +1,120 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
4
+ import * as fs from 'node:fs';
5
+ import * as path from 'node:path';
6
+ import {integrationAdd, integrationAddComponent} from './add-contribution.mjs';
7
+ import {discoverIntegrationComponents} from '../../foundation/discovery/component-discovery.mjs';
8
+
9
+ let tmpDir;
10
+
11
+ beforeEach(() => {
12
+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-add-component-'));
13
+ fs.writeFileSync(
14
+ path.join(tmpDir, 'package.json'),
15
+ `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist']}, null, 2)}\n`,
16
+ );
17
+ fs.writeFileSync(
18
+ path.join(tmpDir, 'astryx.integration.mjs'),
19
+ "export default {\n components: './components',\n};\n",
20
+ );
21
+ });
22
+
23
+ afterEach(() => {
24
+ fs.rmSync(tmpDir, {recursive: true, force: true});
25
+ });
26
+
27
+ /** @param {string} relativeDoc */
28
+ function writeAuthoredComponent(relativeDoc) {
29
+ const doc = path.join(tmpDir, relativeDoc);
30
+ fs.mkdirSync(path.dirname(doc), {recursive: true});
31
+ fs.writeFileSync(
32
+ doc,
33
+ "export default {\n type: 'component',\n name: 'AcmeWidget',\n description: 'The authored AcmeWidget.',\n props: [],\n};\n",
34
+ );
35
+ fs.writeFileSync(
36
+ doc.replace(/\.doc\.(?:ts|mjs|js)$/u, '.tsx'),
37
+ 'export function AcmeWidget() {\n return <div>Authored</div>;\n}\n',
38
+ );
39
+ }
40
+
41
+ /** Every file under the package, with its bytes. */
42
+ function snapshot() {
43
+ /** @type {Record<string, string>} */
44
+ const files = {};
45
+ /** @param {string} dir */
46
+ const walk = dir => {
47
+ for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
48
+ const full = path.join(dir, entry.name);
49
+ if (entry.isDirectory()) walk(full);
50
+ else files[path.relative(tmpDir, full)] = fs.readFileSync(full, 'utf-8');
51
+ }
52
+ };
53
+ walk(tmpDir);
54
+ return files;
55
+ }
56
+
57
+ describe('integrationAddComponent name collisions', () => {
58
+ it('refuses a name a nested component doc already defines', async () => {
59
+ writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
60
+ const before = snapshot();
61
+
62
+ await expect(
63
+ integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
64
+ ).rejects.toMatchObject({
65
+ code: 'ERR_FILE_EXISTS',
66
+ message: expect.stringContaining(
67
+ 'components/AcmeWidget/AcmeWidget.doc.mjs',
68
+ ),
69
+ });
70
+ expect(snapshot()).toEqual(before);
71
+ expect(
72
+ discoverIntegrationComponents({
73
+ name: '@acme/widgets',
74
+ components: path.join(tmpDir, 'components'),
75
+ }).map(component => path.relative(tmpDir, component.docPath)),
76
+ ).toEqual([path.join('components', 'AcmeWidget', 'AcmeWidget.doc.mjs')]);
77
+ });
78
+
79
+ it('refuses the same collision under --dry-run', async () => {
80
+ writeAuthoredComponent('components/widgets/AcmeWidget.doc.mjs');
81
+
82
+ await expect(
83
+ integrationAdd('component', 'AcmeWidget', {cwd: tmpDir, dryRun: true}),
84
+ ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
85
+ });
86
+
87
+ it('refuses a same-stem doc with another extension in the root', async () => {
88
+ fs.mkdirSync(path.join(tmpDir, 'components'));
89
+ fs.writeFileSync(
90
+ path.join(tmpDir, 'components', 'AcmeWidget.doc.ts'),
91
+ "export default {type: 'component', name: 'AcmeWidget', props: []};\n",
92
+ );
93
+ const before = snapshot();
94
+
95
+ await expect(
96
+ integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
97
+ ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
98
+ expect(snapshot()).toEqual(before);
99
+ });
100
+
101
+ it('still adds a component whose name is free', async () => {
102
+ writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
103
+
104
+ const result = await integrationAddComponent('AcmeBadge', {cwd: tmpDir});
105
+
106
+ expect(result.data.files).toEqual([
107
+ 'components/AcmeBadge.doc.mjs',
108
+ 'components/AcmeBadge.tsx',
109
+ 'package.json',
110
+ ]);
111
+ expect(
112
+ discoverIntegrationComponents({
113
+ name: '@acme/widgets',
114
+ components: path.join(tmpDir, 'components'),
115
+ })
116
+ .map(component => component.name)
117
+ .sort(),
118
+ ).toEqual(['AcmeBadge', 'AcmeWidget']);
119
+ });
120
+ });
@@ -31,7 +31,7 @@ export function integrationAddAgentDoc(line: string, options?: import("./integra
31
31
  *
32
32
  * @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
33
33
  * @param {string} name
34
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string}} [options]
34
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
35
35
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
36
36
  */
37
37
  export function integrationAdd(kind: "component" | "doc" | "template" | "codemod" | "agent-doc" | "theme", name: string, options?: {
@@ -41,4 +41,5 @@ export function integrationAdd(kind: "component" | "doc" | "template" | "codemod
41
41
  to?: string;
42
42
  replaces?: string;
43
43
  extends?: string;
44
+ parent?: string;
44
45
  }): Promise<import("./integration-authoring.type.mjs").IntegrationAddResponse>;