@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
@@ -0,0 +1,94 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file The CLI never asks a question, so no help text, manifest entry or
5
+ * error-code description may say a flag skips a prompt. Each flag's text states
6
+ * what happens without it instead, and the CLI does that.
7
+ */
8
+
9
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
+ import * as fs from 'node:fs';
11
+ import * as os from 'node:os';
12
+ import * as path from 'node:path';
13
+ import {fileURLToPath} from 'node:url';
14
+ import {runCli} from '../../../test-utils/run-cli.mjs';
15
+ import {doc as errorCodesDoc} from '../../../foundation/response/error-codes.doc.mjs';
16
+ import {doc as upgradeFn} from '../../../api/upgrade/upgrade.doc.mjs';
17
+
18
+ const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
19
+ const SLOW = 30_000;
20
+
21
+ /** @type {string} */
22
+ let tmpDir;
23
+
24
+ beforeEach(() => {
25
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-prompt-'));
26
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
27
+ });
28
+
29
+ afterEach(() => {
30
+ fs.rmSync(tmpDir, {recursive: true, force: true});
31
+ });
32
+
33
+ /**
34
+ * One option's description from the manifest (subcommands are nested).
35
+ * @param {string} command @param {string} flag
36
+ */
37
+ async function optionText(command, flag) {
38
+ const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
39
+ /** @typedef {{name: string, options: Array<{flag: string, description: string}>, subcommands?: ManifestCommand[]}} ManifestCommand */
40
+ /** @param {ManifestCommand[]} list @returns {ManifestCommand | undefined} */
41
+ const find = list => {
42
+ for (const c of list) {
43
+ const hit = c.name === command ? c : find(c.subcommands ?? []);
44
+ if (hit) return hit;
45
+ }
46
+ return undefined;
47
+ };
48
+ const cmd = find(JSON.parse(stdout).data.commands);
49
+ return cmd?.options.find(o => o.flag.includes(flag))?.description ?? '';
50
+ }
51
+
52
+ describe('no help text describes a prompt', () => {
53
+ it('theme add --overwrite states the refusal, and a refused run writes nothing', async () => {
54
+ const help = await optionText('theme add', '--overwrite');
55
+ expect(help).not.toMatch(/prompt/i);
56
+ expect(help).toContain('ERR_FILE_EXISTS');
57
+ expect(help).toMatch(/nothing is written/);
58
+
59
+ const first = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
60
+ expect(first.status).toBe(0);
61
+ const {outputDir, files} = JSON.parse(first.stdout).data;
62
+ expect(files.length).toBeGreaterThan(1);
63
+ const dir = path.join(tmpDir, outputDir);
64
+ fs.writeFileSync(path.join(dir, files[0]), '// edited\n');
65
+ fs.rmSync(path.join(dir, files[1]));
66
+
67
+ const refused = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
68
+ expect(refused.status).toBe(1);
69
+ expect(JSON.parse(refused.stdout).code).toBe('ERR_FILE_EXISTS');
70
+ expect(fs.readFileSync(path.join(dir, files[0]), 'utf8')).toBe('// edited\n');
71
+ expect(fs.existsSync(path.join(dir, files[1]))).toBe(false);
72
+ }, SLOW);
73
+
74
+ it('upgrade --install-deps names the failure without it, in help and in the API doc', async () => {
75
+ const help = await optionText('upgrade', '--install-deps');
76
+ const param = upgradeFn.params?.find(p => p.name === 'options.installDeps')?.description ?? '';
77
+ for (const text of [help, param]) {
78
+ expect(text).not.toMatch(/prompt/i);
79
+ expect(text).toContain('ERR_DEP_MISSING');
80
+ }
81
+ }, SLOW);
82
+
83
+ it('ERR_FILE_EXISTS is described without an interactive mode, in the code set, its doc and the README table', () => {
84
+ const member = errorCodesDoc.members.find(m => m.value === 'ERR_FILE_EXISTS');
85
+ expect(member?.description).toBe('Refused to overwrite an existing file.');
86
+
87
+ const source = fs.readFileSync(path.join(CLI_ROOT, 'foundation/response/error-codes.mjs'), 'utf8');
88
+ expect(source).toMatch(/\/\*\* Refused to overwrite an existing file\. \*\/\s*ERR_FILE_EXISTS:/);
89
+
90
+ const readme = fs.readFileSync(path.join(CLI_ROOT, 'README.md'), 'utf8');
91
+ const row = readme.split('\n').find(line => line.startsWith('| `ERR_FILE_EXISTS`'));
92
+ expect(row).toMatch(/\| Refused to overwrite an existing file\.\s+\|$/);
93
+ });
94
+ });
@@ -12,7 +12,7 @@ export const doc = {
12
12
  type: 'command',
13
13
  name: 'search',
14
14
  displayName: 'astryx search',
15
- namespace: 'cli',
15
+ namespace: 'cli/commands',
16
16
  summary: 'Search components, hooks, docs, and templates in one ranked list',
17
17
  description:
18
18
  'Terminal front-end to search(): prints one ranked, greppable list across ' +
@@ -29,11 +29,11 @@ export const doc = {
29
29
  {
30
30
  flag: '--limit <n>',
31
31
  param: 'options.limit',
32
- description: 'Max number of results (default 20)',
32
+ description: 'Max number of results, a positive integer (default 20)',
33
33
  },
34
34
  {
35
35
  flag: '--verbose',
36
- description: 'Verbose output (include import paths and match reason)',
36
+ description: "Also print each result's score and match reason",
37
37
  },
38
38
  ],
39
39
  examples: [
@@ -45,7 +45,10 @@ export const doc = {
45
45
  ],
46
46
  exitCodes: [
47
47
  {code: 0, when: 'success (including zero matches)'},
48
- {code: 1, when: 'invalid --type or a non-positive --limit'},
48
+ {
49
+ code: 1,
50
+ when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
51
+ },
49
52
  ],
50
53
  related: ['component', 'hook', 'docs', 'template', 'build'],
51
54
  };
@@ -16,7 +16,7 @@
16
16
  * astryx search button Ranked results across all domains
17
17
  * astryx search modal --type component Filter to a single domain
18
18
  * astryx search forms --limit 5 Cap the result count
19
- * astryx search button --verbose Verbose (include import / reason)
19
+ * astryx search button --verbose Also print score / reason
20
20
  * astryx search button --json Typed JSON envelope
21
21
  */
22
22
 
@@ -49,16 +49,15 @@ export function registerSearch(program) {
49
49
 
50
50
  try {
51
51
  const project = await Project.load(process.cwd());
52
- await warnOnIntegrationIssues(project.loadedIntegrations, {json});
52
+ await warnOnIntegrationIssues(project, {json});
53
53
  } catch {
54
54
  // Never let the nudge break the command.
55
55
  }
56
56
 
57
- // Parse --limit to a number; the API validates it (positive integer) and
58
- // throws ERR_INVALID_ARGUMENT, so we pass NaN through rather than
59
- // pre-rejecting with a generic code here.
60
- const limit =
61
- options.limit != null ? Number.parseInt(options.limit, 10) : 20;
57
+ // Number(), not parseInt(): parseInt truncates `1.5` and `5abc` into
58
+ // integers the API would reject. The API validates the value, so the
59
+ // flag and `search({limit})` accept and refuse the same inputs.
60
+ const limit = options.limit != null ? Number(options.limit) : 20;
62
61
 
63
62
  /** @type {import('../../../api/search/search.type.mjs').SearchResponse} */
64
63
  let result;
@@ -116,15 +115,32 @@ export function registerSearch(program) {
116
115
  const fields = options.verbose
117
116
  ? [
118
117
  'name',
118
+ 'section',
119
119
  'domain',
120
+ 'package',
121
+ 'title',
120
122
  'displayName',
123
+ 'kind',
121
124
  'score',
122
125
  'reason',
123
126
  'import',
124
127
  'description',
125
128
  'command',
129
+ 'parent',
126
130
  ]
127
- : ['name', 'domain', 'displayName', 'import', 'description', 'command'];
131
+ : [
132
+ 'name',
133
+ 'section',
134
+ 'domain',
135
+ 'package',
136
+ 'title',
137
+ 'displayName',
138
+ 'kind',
139
+ 'import',
140
+ 'description',
141
+ 'command',
142
+ 'parent',
143
+ ];
128
144
 
129
145
  // The heading mirrors the JSON: `matchCount` is what matched, and the
130
146
  // records below are the slice `--limit` allowed. Saying only "(20)" when
@@ -135,7 +151,10 @@ export function registerSearch(program) {
135
151
  ? `Results for "${q}" (${results.length} of ${matchCount})`
136
152
  : `Results for "${q}" (${results.length})`,
137
153
  ),
138
- records(results, {fields, format: {command: formatCliCommand}}),
154
+ records(results, {
155
+ fields,
156
+ format: {command: formatCliCommand, parent: formatCliCommand},
157
+ }),
139
158
  );
140
159
  return answered;
141
160
  },
@@ -11,6 +11,8 @@
11
11
  */
12
12
 
13
13
  import {describe, it, expect} from 'vitest';
14
+ import * as fs from 'node:fs';
15
+ import * as os from 'node:os';
14
16
  import * as path from 'node:path';
15
17
  import {fileURLToPath} from 'node:url';
16
18
  import {search, scoreCandidate, SEARCH_DOMAINS} from '../../../api/search/search.mjs';
@@ -28,6 +30,33 @@ const OPTS = {cwd: REPO_ROOT};
28
30
  // the vitest per-test timeout. Give both the same generous scan budget.
29
31
  const SCAN_TIMEOUT = 30_000;
30
32
 
33
+ /**
34
+ * A JSON value as the formatters print it (they normalize typography to ASCII).
35
+ * @param {unknown} value
36
+ */
37
+ function asText(value) {
38
+ return (Array.isArray(value) ? value.join(', ') : String(value))
39
+ .replace(/[\u2014\u2013]/g, '-')
40
+ .replace(/[\u2018\u2019]/g, "'")
41
+ .replace(/[\u201C\u201D]/g, '"')
42
+ .replace(/\u2026/g, '...')
43
+ .replace(/\u00a0/g, ' ')
44
+ .trimEnd();
45
+ }
46
+
47
+ /**
48
+ * Whether some text line prints `key:` with this value. The command field gains
49
+ * the caller's invocation prefix, so the value is matched as the line's end; a
50
+ * multi-line value is matched by its first line.
51
+ * @param {string[]} lines
52
+ * @param {string} key
53
+ * @param {unknown} value
54
+ */
55
+ function printsField(lines, key, value) {
56
+ const shown = asText(value).split('\n')[0].trimEnd();
57
+ return lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown));
58
+ }
59
+
31
60
  describe('search() API — ranking', () => {
32
61
  it('ranks an exact component name match first', async () => {
33
62
  const {data} = await search('button', OPTS);
@@ -172,6 +201,20 @@ describe('search CLI — exit codes + JSON contract', () => {
172
201
  expect(r.status).toBe(1);
173
202
  });
174
203
 
204
+ it.each(['1.5', '5abc'])(
205
+ 'refuses --limit %s like search({limit}) does, in both modes',
206
+ async value => {
207
+ await expect(
208
+ search('x', {...OPTS, limit: Number(value)}),
209
+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
210
+ const json = await runCli(['--json', 'search', 'x', '--limit', value], REPO_ROOT);
211
+ expect(json.status).toBe(1);
212
+ expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
213
+ const text = await runCli(['search', 'x', '--limit', value], REPO_ROOT);
214
+ expect(text.status).toBe(1);
215
+ },
216
+ );
217
+
175
218
  it('emits a valid --json envelope', async () => {
176
219
  const r = await runCli(['--json', 'search', 'button'], REPO_ROOT);
177
220
  expect(r.status).toBe(0);
@@ -223,6 +266,25 @@ describe('search CLI — exit codes + JSON contract', () => {
223
266
  expect(r.stdout).toContain('description:');
224
267
  });
225
268
 
269
+ it('prints every result field under its JSON key (score and reason with --verbose)', async () => {
270
+ // One query that reaches all four domains, so every per-domain field shows.
271
+ const args = ['search', 'theme', '--limit', '60'];
272
+ const env = JSON.parse((await runCli(['--json', ...args], REPO_ROOT)).stdout);
273
+ expect(new Set(env.data.results.map(r => r.domain))).toEqual(new Set(SEARCH_DOMAINS));
274
+ const plain = (await runCli(args, REPO_ROOT)).stdout.split('\n');
275
+ const verbose = (await runCli([...args, '--verbose'], REPO_ROOT)).stdout.split('\n');
276
+ for (const result of env.data.results) {
277
+ for (const [key, value] of Object.entries(result)) {
278
+ if (value == null || value === '') continue;
279
+ const label = `${result.domain} ${result.name}: ${key}`;
280
+ expect(printsField(verbose, key, value), label).toBe(true);
281
+ if (key !== 'score' && key !== 'reason') {
282
+ expect(printsField(plain, key, value), label).toBe(true);
283
+ }
284
+ }
285
+ }
286
+ }, 90_000);
287
+
226
288
  it('--verbose exits 0 and prints import/match detail', async () => {
227
289
  // Regression: the boolean verbose flag was named --detail, which collided
228
290
  // with the value-taking global `--detail <level>` — a bare `search
@@ -236,4 +298,17 @@ describe('search CLI — exit codes + JSON contract', () => {
236
298
  expect(r.stdout).toContain('score:');
237
299
  expect(r.stdout).toContain('reason:');
238
300
  });
301
+
302
+ it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
303
+ const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
304
+ try {
305
+ const json = await runCli(['--json', 'search', 'button'], empty);
306
+ expect(json.status).toBe(1);
307
+ expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
308
+ const text = await runCli(['search', 'button'], empty);
309
+ expect(text.status).toBe(1);
310
+ } finally {
311
+ fs.rmSync(empty, {recursive: true, force: true});
312
+ }
313
+ });
239
314
  }, SCAN_TIMEOUT);
@@ -89,6 +89,12 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
89
89
  expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
90
90
  });
91
91
 
92
+ it('is quiet in an integration package, which is not an app', async () => {
93
+ asProject();
94
+ write('astryx.integration.mjs', 'export default {};\n');
95
+ expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
96
+ });
97
+
92
98
  it('does not nudge for the installer command itself', async () => {
93
99
  asProject();
94
100
  expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);
@@ -12,7 +12,7 @@ export const doc = {
12
12
  type: 'command',
13
13
  name: 'swizzle',
14
14
  displayName: 'astryx swizzle',
15
- namespace: 'cli',
15
+ namespace: 'cli/commands',
16
16
  summary: 'Copy component source for customization',
17
17
  description:
18
18
  "Ejects a component's source from the resolved @astryxdesign/core (or its owning " +
@@ -40,7 +40,8 @@ export const doc = {
40
40
  {
41
41
  flag: '-f, --overwrite',
42
42
  param: 'options.overwrite',
43
- description: 'Overwrite existing files without prompting',
43
+ description:
44
+ 'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
44
45
  },
45
46
  ],
46
47
  examples: [
@@ -74,6 +74,37 @@ describe('swizzle path safety', () => {
74
74
  expect(fs.existsSync(absTarget)).toBe(false);
75
75
  });
76
76
 
77
+ it('rejects a component directory that is a symlink out of the project', async () => {
78
+ const {project, outside} = buildFakeRepo(tmpDir);
79
+ const base = path.join(project, 'components', 'astryx');
80
+ fs.mkdirSync(base, {recursive: true});
81
+ fs.symlinkSync(outside, path.join(base, 'Button'));
82
+
83
+ const result = await runCli(['--json', 'swizzle', 'Button'], project);
84
+
85
+ expect(result.code).not.toBe(0);
86
+ expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
87
+ expect(fs.readdirSync(outside)).toEqual([]);
88
+ });
89
+
90
+ it('rejects an existing file that is a symlink out of the project, even with --overwrite', async () => {
91
+ const {project, outside} = buildFakeRepo(tmpDir);
92
+ const outDir = path.join(project, 'components', 'astryx', 'Button');
93
+ fs.mkdirSync(outDir, {recursive: true});
94
+ const target = path.join(outside, 'kept.txt');
95
+ fs.writeFileSync(target, 'kept\n');
96
+ fs.symlinkSync(target, path.join(outDir, 'Button.tsx'));
97
+
98
+ const result = await runCli(
99
+ ['--json', 'swizzle', 'Button', '--overwrite'],
100
+ project,
101
+ );
102
+
103
+ expect(result.code).not.toBe(0);
104
+ expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
105
+ expect(fs.readFileSync(target, 'utf-8')).toBe('kept\n');
106
+ });
107
+
77
108
  it('requires --overwrite in non-interactive mode when files already exist', async () => {
78
109
  const {project} = buildFakeRepo(tmpDir);
79
110
  const outDir = path.join(project, 'components', 'astryx', 'Button');
@@ -92,4 +123,15 @@ describe('swizzle path safety', () => {
92
123
  // Existing file unchanged
93
124
  expect(fs.readFileSync(existingPath, 'utf-8')).toBe('// my customizations\n');
94
125
  });
126
+
127
+ // The CLI never prompts: without --overwrite it refuses with a code, and the
128
+ // manifest agents read must say so.
129
+ it('describes --overwrite by its refusal, not a prompt', async () => {
130
+ const {project} = buildFakeRepo(tmpDir);
131
+ const result = await runCli(['--json', 'manifest'], project);
132
+ const swizzle = JSON.parse(result.stdout).data.commands.find(c => c.name === 'swizzle');
133
+ const overwrite = swizzle.options.find(o => o.flag.includes('--overwrite'));
134
+ expect(overwrite.description).not.toMatch(/prompt/i);
135
+ expect(overwrite.description).toContain('ERR_FILE_EXISTS');
136
+ });
95
137
  });
@@ -13,21 +13,41 @@ export const doc = {
13
13
  type: 'command',
14
14
  name: 'template',
15
15
  displayName: 'astryx template',
16
- namespace: 'cli',
16
+ namespace: 'cli/commands',
17
17
  summary: 'Inject a page or block template',
18
18
  description:
19
19
  'One entry point for the template family: with no name it lists the discovered ' +
20
20
  'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +
21
- 'into the project at a target path. Narrow an ambiguous name with --type and/or --package. ' +
22
- '--cdn writes the no-build-step CDN starter page, which ships as an asset rather than as ' +
23
- 'a discovered template.',
21
+ 'into the project at a target path. A configured integration replacement is the ' +
22
+ 'default for its Core id; use --package @astryxdesign/core for the original. ' +
23
+ 'Narrow other ambiguous names with --type and/or --package. --cdn writes the ' +
24
+ 'no-build-step CDN starter page, which ships as an asset rather than as a ' +
25
+ 'discovered template.',
24
26
  fn: 'template',
25
27
  args: [
26
- {name: 'name', param: 'name', required: false},
27
- {name: 'path', param: 'options.targetPath', required: false},
28
+ {
29
+ name: 'name',
30
+ param: 'name',
31
+ required: false,
32
+ description: 'Template id (see --list). Omit it to list the templates.',
33
+ },
34
+ {
35
+ name: 'path',
36
+ param: 'options.targetPath',
37
+ required: false,
38
+ description:
39
+ 'Where to scaffold the template, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
40
+ "any other path is a directory, which receives page.tsx for a page template or the block's own file name for a block. " +
41
+ 'Omit it to print the source.',
42
+ },
28
43
  ],
29
44
  options: [
30
- {flag: '--list', param: 'options.list', description: 'List available templates'},
45
+ {
46
+ flag: '--list',
47
+ param: 'options.list',
48
+ description:
49
+ 'List available templates (narrow with --type and --package) and do nothing else: <name>, <path>, --skeleton and --overwrite are ignored',
50
+ },
31
51
  {
32
52
  flag: '--type <type>',
33
53
  param: 'options.type',
@@ -37,37 +57,56 @@ export const doc = {
37
57
  {
38
58
  flag: '--package <pkg>',
39
59
  param: 'options.package',
40
- description: 'Narrow to templates from a specific package',
60
+ description:
61
+ 'Narrow to templates from a specific package. Use @astryxdesign/core to select an original hidden by an integration replacement.',
41
62
  },
42
63
  {
43
64
  flag: '--skeleton',
44
65
  param: 'options.skeleton',
45
66
  description:
46
- 'Show layout skeleton with spatial annotations (padding, gap, nesting)',
67
+ 'Show layout skeleton with spatial annotations (padding, gap, nesting) instead of the source. Needs <name>. ' +
68
+ 'It writes nothing, so <path> and --overwrite are ignored; --list and --cdn take precedence',
47
69
  },
48
70
  {
49
71
  flag: '--cdn [path]',
50
72
  param: 'options.cdn',
51
73
  description:
52
- 'Write the no-build-step CDN starter page (default: cdn.template.html)',
74
+ 'Write the no-build-step CDN starter page and do nothing else: <name>, --list, --skeleton, --type and --package are ignored. ' +
75
+ 'The page goes to the --cdn value, else to <path>, else cdn.template.html, and that path is always the file itself. ' +
76
+ 'A value right after --cdn (anything not starting with -) is taken as that path',
53
77
  },
54
78
  {
55
79
  flag: '-f, --overwrite',
56
80
  param: 'options.overwrite',
57
- description: 'Overwrite existing files without prompting',
81
+ description:
82
+ 'Replace an existing target file. Without it an existing file is refused (ERR_FILE_EXISTS) and an existing CDN page is left as is',
58
83
  },
59
84
  ],
60
85
  examples: [
61
86
  {label: 'List templates', cli: 'astryx template --json'},
87
+ {
88
+ label: 'List exact Core ids',
89
+ cli: 'astryx --json template --list --package @astryxdesign/core',
90
+ },
62
91
  {
63
92
  label: 'Scaffold into the app',
64
93
  cli: 'astryx template dashboard ./src/app',
65
94
  },
95
+ {
96
+ label: 'Select a replaced Core original',
97
+ cli: 'astryx template shell-side-nav ./src/app --package @astryxdesign/core',
98
+ },
66
99
  {label: 'CDN starter page', cli: 'astryx template --cdn'},
67
- {label: 'CDN starter page, elsewhere', cli: 'astryx template --cdn public/demo.html'},
100
+ {
101
+ label: 'CDN starter page, elsewhere',
102
+ cli: 'astryx template --cdn public/demo.html',
103
+ },
68
104
  ],
69
105
  exitCodes: [
70
- {code: 0, when: 'success, including a CDN page left untouched because it already exists'},
106
+ {
107
+ code: 0,
108
+ when: 'success, including a CDN page left untouched because it already exists',
109
+ },
71
110
  {
72
111
  code: 1,
73
112
  when: 'unknown or ambiguous template, no source, a path escape, or an existing target without --overwrite',
@@ -0,0 +1,117 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `astryx template` documents which of its flags win when they are
5
+ * combined, and behaves as documented. Option text is read from the generated
6
+ * manifest, the same strings `--help` prints.
7
+ */
8
+
9
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
+ import * as fs from 'node:fs';
11
+ import * as os from 'node:os';
12
+ import * as path from 'node:path';
13
+ import {runCli} from '../../../test-utils/run-cli.mjs';
14
+
15
+ const SLOW = 30_000;
16
+
17
+ /** @type {string} */
18
+ let tmpDir;
19
+
20
+ beforeEach(() => {
21
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-flags-'));
22
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
23
+ });
24
+
25
+ afterEach(() => {
26
+ fs.rmSync(tmpDir, {recursive: true, force: true});
27
+ });
28
+
29
+ /** @param {string} rel */
30
+ const exists = rel => fs.existsSync(path.join(tmpDir, rel));
31
+
32
+ /** Files in the project, ignoring package.json. */
33
+ const written = () => fs.readdirSync(tmpDir).filter(f => f !== 'package.json');
34
+
35
+ /**
36
+ * template's option descriptions from the manifest, keyed by long flag.
37
+ * @returns {Promise<Record<string, string>>}
38
+ */
39
+ async function templateOptions() {
40
+ const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
41
+ const template = JSON.parse(stdout).data.commands.find(
42
+ (/** @type {{name: string}} */ c) => c.name === 'template',
43
+ );
44
+ return Object.fromEntries(
45
+ template.options.map((/** @type {{flag: string, description: string}} */ o) => [
46
+ o.flag.match(/--[a-z-]+/)?.[0],
47
+ o.description,
48
+ ]),
49
+ );
50
+ }
51
+
52
+ /** @param {string[]} args */
53
+ async function templateJson(args) {
54
+ const result = await runCli(['--json', 'template', ...args], tmpDir);
55
+ return {status: result.status, envelope: JSON.parse(result.stdout)};
56
+ }
57
+
58
+ describe('astryx template flag precedence', () => {
59
+ it('--list: help says <name>, <path>, --skeleton and --overwrite are ignored, and they are', async () => {
60
+ const help = (await templateOptions())['--list'];
61
+ for (const ignored of ['<name>', '<path>', '--skeleton', '--overwrite']) {
62
+ expect(help).toContain(ignored);
63
+ }
64
+ expect(help).toMatch(/are ignored/);
65
+
66
+ const {status, envelope} = await templateJson([
67
+ 'dashboard',
68
+ './src/page.tsx',
69
+ '--list',
70
+ '--skeleton',
71
+ '--overwrite',
72
+ ]);
73
+ expect(status).toBe(0);
74
+ expect(envelope.type).toBe('template.list');
75
+ expect(written()).toEqual([]);
76
+ }, SLOW);
77
+
78
+ it('--skeleton: help says it needs <name> and writes nothing, and it does', async () => {
79
+ const help = (await templateOptions())['--skeleton'];
80
+ expect(help).toMatch(/Needs <name>/);
81
+ expect(help).toMatch(/writes nothing, so <path> and --overwrite are ignored/);
82
+ expect(help).toMatch(/--list and --cdn take precedence/);
83
+
84
+ const shown = await templateJson(['dashboard', './src/page.tsx', '--skeleton', '--overwrite']);
85
+ expect(shown.status).toBe(0);
86
+ expect(shown.envelope.type).toBe('template.skeleton');
87
+ expect(written()).toEqual([]);
88
+
89
+ const nameless = await templateJson(['--skeleton']);
90
+ expect(nameless.status).toBe(1);
91
+ expect(nameless.envelope.code).toBe('ERR_UNKNOWN_TEMPLATE');
92
+ }, SLOW);
93
+
94
+ it('--cdn: help says it overrides everything and where the page goes, and the CLI does that', async () => {
95
+ const help = (await templateOptions())['--cdn'];
96
+ for (const ignored of ['<name>', '--list', '--skeleton', '--type', '--package']) {
97
+ expect(help).toContain(ignored);
98
+ }
99
+ expect(help).toMatch(/--cdn value, else to <path>, else cdn\.template\.html/);
100
+ expect(help).toMatch(/always the file itself/);
101
+ expect(help).toMatch(/value right after --cdn/);
102
+
103
+ const everything = await templateJson(['dashboard', '--list', '--skeleton', '--type', 'bogus', '--cdn']);
104
+ expect(everything.envelope.type).toBe('template.cdn');
105
+ expect(everything.envelope.data.path).toBe('cdn.template.html');
106
+
107
+ // A bare --cdn writes to <path>, and a path with no extension is still the file.
108
+ const positional = await templateJson(['dashboard', 'demo', '--cdn']);
109
+ expect(positional.envelope.data.path).toBe('demo');
110
+ expect(fs.statSync(path.join(tmpDir, 'demo')).isFile()).toBe(true);
111
+
112
+ // The word after --cdn is its value, not the template name.
113
+ const value = await templateJson(['--cdn', 'dashboard']);
114
+ expect(value.envelope.data.path).toBe('dashboard');
115
+ expect(exists('dashboard')).toBe(true);
116
+ }, SLOW);
117
+ });