@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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 (728) hide show
  1. package/CHANGELOG.md +194 -0
  2. package/README.md +152 -107
  3. package/api/blog/blog.doc.mjs +1 -0
  4. package/api/build/_adapter.d.mts +50 -0
  5. package/api/build/_adapter.mjs +60 -0
  6. package/api/build/build.doc.mjs +22 -10
  7. package/api/build/build.test.mjs +219 -8
  8. package/api/build/build.type.d.mts +91 -2
  9. package/api/build/build.type.mjs +52 -8
  10. package/api/build/help/help.d.mts +12 -5
  11. package/api/build/help/help.mjs +69 -6
  12. package/api/build/kit/kit.d.mts +4 -1
  13. package/api/build/kit/kit.mjs +208 -53
  14. package/api/build/kit/rank.d.mts +44 -0
  15. package/api/build/kit/rank.mjs +432 -0
  16. package/api/build/kit/rank.test.mjs +196 -0
  17. package/api/component/_adapter.d.mts +31 -12
  18. package/api/component/_adapter.mjs +79 -15
  19. package/api/component/component.d.mts +6 -3
  20. package/api/component/component.doc.mjs +49 -19
  21. package/api/component/component.mjs +339 -22
  22. package/api/component/component.test.mjs +38 -0
  23. package/api/component/component.type.d.mts +47 -11
  24. package/api/component/component.type.mjs +76 -24
  25. package/api/component/detail/blocks/blocks.d.mts +2 -1
  26. package/api/component/detail/blocks/blocks.mjs +4 -3
  27. package/api/component/list/list.d.mts +0 -5
  28. package/api/component/list/list.mjs +40 -11
  29. package/api/discover/_adapter.d.mts +114 -6
  30. package/api/discover/_adapter.mjs +372 -17
  31. package/api/discover/_adapter.test.mjs +215 -0
  32. package/api/discover/_catalog-view.d.mts +115 -0
  33. package/api/discover/_catalog-view.mjs +203 -0
  34. package/api/discover/_catalog-view.test.mjs +128 -0
  35. package/api/discover/detail/detail.d.mts +18 -6
  36. package/api/discover/detail/detail.mjs +67 -13
  37. package/api/discover/detail/detail.test.mjs +85 -0
  38. package/api/discover/detail/item/item.d.mts +26 -0
  39. package/api/discover/detail/item/item.mjs +78 -0
  40. package/api/discover/detail/item/item.test.mjs +73 -0
  41. package/api/discover/discover.d.mts +3 -9
  42. package/api/discover/discover.doc.mjs +62 -18
  43. package/api/discover/discover.mjs +220 -36
  44. package/api/discover/discover.test.mjs +11 -2
  45. package/api/discover/discover.type.d.mts +150 -11
  46. package/api/discover/discover.type.mjs +107 -17
  47. package/api/discover/list/list.d.mts +20 -6
  48. package/api/discover/list/list.mjs +45 -12
  49. package/api/discover/list/list.test.mjs +46 -0
  50. package/api/discover/search/search.d.mts +18 -16
  51. package/api/discover/search/search.mjs +102 -56
  52. package/api/discover/search/search.test.mjs +144 -10
  53. package/api/docs/_adapter.d.mts +277 -41
  54. package/api/docs/_adapter.mjs +993 -108
  55. package/api/docs/compiled-topics.test.mjs +78 -0
  56. package/api/docs/detail/detail.mjs +22 -63
  57. package/api/docs/detail/section/section.d.mts +1 -1
  58. package/api/docs/detail/section/section.mjs +54 -19
  59. package/api/docs/detail/section/section.test.mjs +50 -0
  60. package/api/docs/docOverlays.test.mjs +27 -1
  61. package/api/docs/docs.d.mts +10 -3
  62. package/api/docs/docs.doc.mjs +55 -16
  63. package/api/docs/docs.mjs +53 -10
  64. package/api/docs/docs.type.d.mts +221 -5
  65. package/api/docs/docs.type.mjs +153 -11
  66. package/api/docs/index/index.d.mts +18 -0
  67. package/api/docs/index/index.mjs +40 -0
  68. package/api/docs/index/index.test.mjs +62 -0
  69. package/api/docs/list/list.mjs +28 -12
  70. package/api/docs/node/node.d.mts +43 -0
  71. package/api/docs/node/node.mjs +192 -0
  72. package/api/docs/reference-blocks.test.mjs +406 -0
  73. package/api/doctor/doctor.d.mts +104 -1
  74. package/api/doctor/doctor.doc.mjs +18 -8
  75. package/api/doctor/doctor.mjs +635 -7
  76. package/api/doctor/doctor.test.mjs +732 -11
  77. package/api/doctor/doctor.type.d.mts +1 -1
  78. package/api/doctor/doctor.type.mjs +1 -1
  79. package/api/gap-report/gap-report.doc.mjs +27 -14
  80. package/api/hook/_adapter.mjs +19 -5
  81. package/api/hook/hook.doc.mjs +7 -3
  82. package/api/hook/hook.type.d.mts +3 -3
  83. package/api/hook/hook.type.mjs +11 -11
  84. package/api/hook/list/list.d.mts +2 -2
  85. package/api/hook/list/list.mjs +69 -17
  86. package/api/index.d.mts +2 -1
  87. package/api/index.mjs +6 -3
  88. package/api/init/init.doc.mjs +22 -12
  89. package/api/init/init.test.mjs +41 -1
  90. package/api/init/remove/remove.mjs +1 -1
  91. package/api/init/run/run.mjs +20 -10
  92. package/api/integration/add-contribution.component-names.test.mjs +120 -0
  93. package/api/integration/add-contribution.d.mts +2 -1
  94. package/api/integration/add-contribution.mjs +130 -15
  95. package/api/integration/add-contribution.test.mjs +258 -7
  96. package/api/integration/add-helpers.d.mts +5 -2
  97. package/api/integration/add-helpers.mjs +36 -9
  98. package/api/integration/add-theme.mjs +56 -65
  99. package/api/integration/add-theme.test.mjs +139 -21
  100. package/api/integration/authoring-checks.mjs +138 -28
  101. package/api/integration/authoring-checks.test.mjs +179 -7
  102. package/api/integration/authoring-checks.type.mjs +6 -1
  103. package/api/integration/integration-authoring.type.d.mts +3 -1
  104. package/api/integration/integration-authoring.type.mjs +2 -0
  105. package/api/integration/integration-block-exports.test.mjs +10 -6
  106. package/api/integration/integrationAdd.doc.mjs +14 -4
  107. package/api/integration/integrationAddAgentDoc.doc.mjs +1 -0
  108. package/api/integration/integrationAddCodemod.doc.mjs +1 -0
  109. package/api/integration/integrationAddComponent.doc.mjs +2 -1
  110. package/api/integration/integrationAddDoc.doc.mjs +8 -1
  111. package/api/integration/integrationAddTemplate.doc.mjs +1 -0
  112. package/api/integration/integrationAddTheme.doc.mjs +6 -5
  113. package/api/integration/integrationComponentConflicts.doc.mjs +1 -0
  114. package/api/integration/integrationDocConflicts.doc.mjs +2 -1
  115. package/api/integration/integrationPackCheck.doc.mjs +5 -4
  116. package/api/integration/integrationTemplateConflicts.doc.d.mts +3 -0
  117. package/api/integration/integrationTemplateConflicts.doc.mjs +4 -0
  118. package/api/integration/pack-check.lifecycle-output.test.mjs +107 -0
  119. package/api/integration/pack-check.mjs +160 -11
  120. package/api/integration/pack-check.test.mjs +477 -47
  121. package/api/integration/pack-check.type.d.mts +26 -2
  122. package/api/integration/pack-check.type.mjs +15 -2
  123. package/api/integration/summarizeIssues.doc.mjs +1 -0
  124. package/api/integration/template-conflict-compatibility.test.mjs +73 -0
  125. package/api/integration/validate-integration-fixes.test.mjs +1389 -0
  126. package/api/integration/validate-integration.mjs +52 -102
  127. package/api/integration/validate-integration.test.mjs +179 -26
  128. package/api/integration/validate-unread-theme-folders.test.mjs +110 -0
  129. package/api/integration/validateIntegration.doc.mjs +3 -2
  130. package/api/json/assertResponse.doc.mjs +2 -1
  131. package/api/json/envelope-types.test.mjs +76 -0
  132. package/api/json/index.ts +2 -0
  133. package/api/json/isError.doc.mjs +2 -1
  134. package/api/json/parseResponse.doc.mjs +3 -2
  135. package/api/layout/_adapter.mjs +20 -5
  136. package/api/layout/expand/expand.mjs +7 -5
  137. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  138. package/api/layout/grammar/grammar.mjs +2 -1
  139. package/api/layout/layoutCheck.doc.mjs +1 -0
  140. package/api/layout/layoutExpand.doc.mjs +2 -1
  141. package/api/layout/layoutGrammar.doc.mjs +1 -0
  142. package/api/search/search-return-type.test.mjs +54 -0
  143. package/api/search/search.d.mts +89 -12
  144. package/api/search/search.doc.mjs +8 -2
  145. package/api/search/search.mjs +697 -97
  146. package/api/search/search.type.d.mts +15 -3
  147. package/api/search/search.type.mjs +5 -2
  148. package/api/swizzle/copy/copy.mjs +28 -11
  149. package/api/swizzle/swizzle.doc.mjs +8 -5
  150. package/api/swizzle/swizzle.type.d.mts +2 -2
  151. package/api/swizzle/swizzle.type.mjs +2 -2
  152. package/api/template/copy/copy.mjs +18 -24
  153. package/api/template/copy/copy.test.mjs +26 -0
  154. package/api/template/list/list.mjs +1 -0
  155. package/api/template/table-floating-bulk-actions.test.mjs +66 -0
  156. package/api/template/template-integration.test.mjs +1072 -3
  157. package/api/template/template-suffix.test.mjs +41 -21
  158. package/api/template/template.d.mts +1 -1
  159. package/api/template/template.doc.mjs +32 -9
  160. package/api/template/template.mjs +45 -8
  161. package/api/template/template.type.d.mts +12 -14
  162. package/api/template/template.type.mjs +15 -14
  163. package/api/theme/_adapter.d.mts +2 -3
  164. package/api/theme/_adapter.mjs +4 -5
  165. package/api/theme/add/add.binary.test.mjs +84 -0
  166. package/api/theme/add/add.mjs +31 -22
  167. package/api/theme/add/add.rollback.test.mjs +158 -0
  168. package/api/theme/add/add.staging.test.mjs +83 -0
  169. package/api/theme/add/add.test.mjs +14 -1
  170. package/api/theme/build/build.family.test.mjs +7 -12
  171. package/api/theme/build/build.mjs +140 -59
  172. package/api/theme/build/build.public-component-vars.test.mjs +1 -1
  173. package/api/theme/build/build.receipt-doc.test.mjs +111 -0
  174. package/api/theme/build/build.rollback.test.mjs +148 -0
  175. package/api/theme/build/build.test.mjs +127 -0
  176. package/api/theme/build/font-warning.mjs +3 -3
  177. package/api/theme/build/font-warning.test.mjs +5 -2
  178. package/api/theme/generateTonalPalette.doc.mjs +2 -2
  179. package/api/theme/integration-themes.test.mjs +39 -28
  180. package/api/theme/list/list.test.mjs +19 -20
  181. package/api/theme/listThemes.doc.mjs +6 -5
  182. package/api/theme/palette/generate/generate.mjs +8 -3
  183. package/api/theme/palette/generate/generate.test.mjs +96 -0
  184. package/api/theme/palette/generate/generator.d.mts +10 -13
  185. package/api/theme/palette/generate/generator.mjs +15 -4
  186. package/api/theme/palette/generate/generator.test.mjs +10 -0
  187. package/api/theme/template/template.mjs +11 -2
  188. package/api/theme/template/template.test.mjs +20 -0
  189. package/api/theme/theme.type.d.mts +170 -11
  190. package/api/theme/theme.type.mjs +94 -27
  191. package/api/theme/themeAdd.doc.mjs +12 -12
  192. package/api/theme/themeBuild.doc.mjs +21 -17
  193. package/api/theme/themeList.doc.mjs +6 -3
  194. package/api/theme/themeListAvailable.doc.mjs +6 -3
  195. package/api/theme/themePaletteGenerate.doc.mjs +16 -8
  196. package/api/theme/themeTargets.doc.mjs +4 -2
  197. package/api/theme/themeTemplate.doc.mjs +8 -3
  198. package/api/upgrade/_adapter.d.mts +32 -5
  199. package/api/upgrade/_adapter.mjs +139 -22
  200. package/api/upgrade/list/list.mjs +2 -1
  201. package/api/upgrade/list/list.test.mjs +73 -0
  202. package/api/upgrade/project-context.test.mjs +272 -0
  203. package/api/upgrade/provider-agreement.test.mjs +152 -0
  204. package/api/upgrade/run/files-changed.test.mjs +111 -0
  205. package/api/upgrade/run/run.mjs +358 -59
  206. package/api/upgrade/status/status.mjs +2 -2
  207. package/api/upgrade/upgrade.doc.mjs +32 -23
  208. package/api/upgrade/upgrade.type.d.mts +43 -5
  209. package/api/upgrade/upgrade.type.mjs +29 -13
  210. package/assets/codemods/__tests__/registry.test.mjs +1 -0
  211. package/assets/codemods/__tests__/runner.test.mjs +332 -8
  212. package/assets/codemods/file-count.test.mjs +163 -0
  213. package/assets/codemods/integration-discovery.mjs +48 -4
  214. package/assets/codemods/integration-discovery.test.mjs +73 -0
  215. package/assets/codemods/integration-runner.mjs +59 -7
  216. package/assets/codemods/integration-runner.protection.test.mjs +153 -0
  217. package/assets/codemods/registry.mjs +1 -0
  218. package/assets/codemods/run-codemod.mjs +177 -34
  219. package/assets/codemods/runner.mjs +353 -104
  220. package/assets/codemods/term-log.mjs +32 -8
  221. package/assets/codemods/term-log.test.mjs +19 -1
  222. package/assets/codemods/transform-prop.mjs +109 -0
  223. package/assets/codemods/transform-prop.test.mjs +95 -0
  224. package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
  225. package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
  226. package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
  227. package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
  228. package/assets/codemods/transforms/v0.3.0/__tests__/unwrap-authoring-factories.test.mjs +27 -5
  229. package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs +20 -5
  230. package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
  231. package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
  232. package/assets/codemods/transforms/v0.6.4/__tests__/migrate-native-picker-to-presentation.test.mjs +63 -0
  233. package/assets/codemods/transforms/v0.6.4/__tests__/migrate-theme-catalog-to-descriptors.test.mjs +220 -0
  234. package/assets/codemods/transforms/v0.6.4/index.mjs +31 -0
  235. package/assets/codemods/transforms/v0.6.4/migrate-native-picker-to-presentation.mjs +148 -0
  236. package/assets/codemods/transforms/v0.6.4/migrate-theme-catalog-to-descriptors.mjs +141 -0
  237. package/assets/docs/README.md +12 -1
  238. package/assets/docs/authoring.doc.mjs +14 -0
  239. package/assets/docs/browser-support.doc.mjs +11 -11
  240. package/assets/docs/color.doc.mjs +8 -2
  241. package/assets/docs/elevation.doc.mjs +6 -4
  242. package/assets/docs/getting-started.doc.mjs +6 -17
  243. package/assets/docs/icons.doc.mjs +2 -21
  244. package/assets/docs/illustrations.doc.mjs +7 -15
  245. package/assets/docs/internationalization.doc.mjs +7 -5
  246. package/assets/docs/layout.doc.dense.mjs +132 -84
  247. package/assets/docs/layout.doc.mjs +134 -78
  248. package/assets/docs/migration.doc.mjs +19 -21
  249. package/assets/docs/motion.doc.mjs +16 -3
  250. package/assets/docs/principles.doc.dense.mjs +5 -5
  251. package/assets/docs/principles.doc.mjs +14 -6
  252. package/assets/docs/principles.doc.zh.mjs +6 -6
  253. package/assets/docs/shape.doc.mjs +8 -3
  254. package/assets/docs/spacing.doc.mjs +7 -2
  255. package/assets/docs/styling-libraries.doc.mjs +10 -6
  256. package/assets/docs/styling.doc.mjs +22 -26
  257. package/assets/docs/theme.doc.dense.mjs +58 -18
  258. package/assets/docs/theme.doc.mjs +60 -50
  259. package/assets/docs/theme.doc.zh.mjs +9 -8
  260. package/assets/docs/tokens.doc.dense.mjs +2 -2
  261. package/assets/docs/tokens.doc.mjs +390 -9
  262. package/assets/docs/tokens.doc.zh.mjs +2 -2
  263. package/assets/docs/tree/add-a-component.doc.mjs +75 -0
  264. package/assets/docs/tree/add-a-theme.doc.mjs +85 -0
  265. package/assets/docs/tree/add-a-topic.doc.mjs +144 -0
  266. package/assets/docs/tree/agent-guidance.doc.mjs +138 -0
  267. package/assets/docs/tree/api.doc.mjs +30 -0
  268. package/assets/docs/tree/block-template.doc.mjs +130 -0
  269. package/assets/docs/tree/build-the-template.doc.mjs +28 -0
  270. package/assets/docs/tree/building-blocks.doc.mjs +46 -0
  271. package/assets/docs/tree/check-your-docs.doc.mjs +137 -0
  272. package/assets/docs/tree/checks.doc.mjs +119 -0
  273. package/assets/docs/tree/cli.doc.mjs +23 -0
  274. package/assets/docs/tree/codemods.doc.mjs +147 -0
  275. package/assets/docs/tree/commands.doc.mjs +25 -0
  276. package/assets/docs/tree/component-family.doc.mjs +113 -0
  277. package/assets/docs/tree/component-imports.doc.mjs +69 -0
  278. package/assets/docs/tree/component-lookups.doc.mjs +149 -0
  279. package/assets/docs/tree/components.doc.mjs +23 -0
  280. package/assets/docs/tree/configuration.doc.mjs +23 -0
  281. package/assets/docs/tree/debug-and-gap-reports.doc.mjs +182 -0
  282. package/assets/docs/tree/define-the-theme.doc.mjs +118 -0
  283. package/assets/docs/tree/describe-the-component.doc.mjs +57 -0
  284. package/assets/docs/tree/docs.doc.mjs +21 -0
  285. package/assets/docs/tree/document-the-template.doc.mjs +28 -0
  286. package/assets/docs/tree/document-the-theme.doc.mjs +68 -0
  287. package/assets/docs/tree/export-template-assets.doc.mjs +147 -0
  288. package/assets/docs/tree/extend-or-replace.doc.mjs +103 -0
  289. package/assets/docs/tree/fonts-and-assets.doc.mjs +106 -0
  290. package/assets/docs/tree/generate-a-palette.doc.mjs +66 -0
  291. package/assets/docs/tree/grade-template-with-agent.doc.mjs +105 -0
  292. package/assets/docs/tree/help.doc.mjs +16 -0
  293. package/assets/docs/tree/integrations.doc.mjs +40 -0
  294. package/assets/docs/tree/links.doc.mjs +98 -0
  295. package/assets/docs/tree/package-and-test.doc.mjs +32 -0
  296. package/assets/docs/tree/page-template.doc.mjs +71 -0
  297. package/assets/docs/tree/publishing.doc.mjs +111 -0
  298. package/assets/docs/tree/quick-start.doc.mjs +272 -0
  299. package/assets/docs/tree/replace-a-core-component.doc.mjs +104 -0
  300. package/assets/docs/tree/replace-a-core-template.doc.mjs +172 -0
  301. package/assets/docs/tree/sections-and-placement.doc.mjs +108 -0
  302. package/assets/docs/tree/see-it-in-an-app.doc.mjs +59 -0
  303. package/assets/docs/tree/ship.doc.mjs +16 -0
  304. package/assets/docs/tree/short-and-findable.doc.mjs +108 -0
  305. package/assets/docs/tree/single-component.doc.mjs +165 -0
  306. package/assets/docs/tree/start-a-template.doc.mjs +143 -0
  307. package/assets/docs/tree/subcomponent.doc.mjs +115 -0
  308. package/assets/docs/tree/template-assets.doc.mjs +64 -0
  309. package/assets/docs/tree/template-doc-overview.doc.mjs +109 -0
  310. package/assets/docs/tree/template-fonts.doc.mjs +102 -0
  311. package/assets/docs/tree/template-grading-rubric.doc.mjs +452 -0
  312. package/assets/docs/tree/template-icons.doc.mjs +97 -0
  313. package/assets/docs/tree/template-images-media.doc.mjs +127 -0
  314. package/assets/docs/tree/template-styles.doc.mjs +93 -0
  315. package/assets/docs/tree/templates.doc.mjs +34 -0
  316. package/assets/docs/tree/test-in-an-app.doc.mjs +115 -0
  317. package/assets/docs/tree/test-template-in-app.doc.mjs +128 -0
  318. package/assets/docs/tree/themes.doc.mjs +39 -0
  319. package/assets/docs/tree/troubleshooting.doc.mjs +149 -0
  320. package/assets/docs/tree/upgrading.doc.mjs +103 -0
  321. package/assets/docs/tree/use-a-theme-in-an-app.doc.mjs +51 -0
  322. package/assets/docs/tree/verify-packed-template.doc.mjs +77 -0
  323. package/assets/docs/tree/versioning.doc.mjs +161 -0
  324. package/assets/docs/tree/write-good-templates.doc.mjs +64 -0
  325. package/assets/docs/tree/write-the-template-file.doc.mjs +154 -0
  326. package/assets/docs/typography.doc.mjs +24 -4
  327. package/assets/docs/working-with-ai.doc.mjs +34 -26
  328. package/assets/templates/blocks/components/CheckboxList/CheckboxListSelectAllPattern.doc.mjs +1 -1
  329. package/assets/templates/blocks/components/CheckboxList/CheckboxListSelectAllPattern.tsx +1 -3
  330. package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx +1 -1
  331. package/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx +1 -1
  332. package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs +14 -0
  333. package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx +100 -0
  334. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
  335. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
  336. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
  337. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
  338. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
  339. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
  340. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
  341. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
  342. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
  343. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
  344. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
  345. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
  346. package/assets/templates/blocks/components/Table/TableBulkActionsTable.doc.mjs +14 -0
  347. package/assets/templates/blocks/components/Table/TableBulkActionsTable.tsx +71 -0
  348. package/assets/templates/blocks/components/Table/TableFloatingBulkActionsTable.doc.mjs +19 -0
  349. package/assets/templates/blocks/components/Table/TableFloatingBulkActionsTable.tsx +139 -0
  350. package/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx +1 -0
  351. package/assets/templates/blocks/components/Timer/TimerFormats.doc.mjs +14 -0
  352. package/assets/templates/blocks/components/Timer/TimerFormats.tsx +34 -0
  353. package/assets/templates/blocks/components/Timer/TimerInline.doc.mjs +14 -0
  354. package/assets/templates/blocks/components/Timer/TimerInline.tsx +14 -0
  355. package/assets/templates/blocks/components/Timer/TimerShowcase.doc.mjs +13 -0
  356. package/assets/templates/blocks/components/Timer/TimerShowcase.tsx +47 -0
  357. package/assets/templates/blocks/components/Timer/TimerTypography.doc.mjs +14 -0
  358. package/assets/templates/blocks/components/Timer/TimerTypography.tsx +31 -0
  359. package/assets/templates/blocks/components/Toolbar/ToolbarTableFilter.doc.mjs +19 -3
  360. package/assets/templates/blocks/components/Toolbar/ToolbarTableFilter.tsx +383 -65
  361. package/assets/templates/pages/table-tree/page.tsx +1704 -0
  362. package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
  363. package/assets/templates/themes/butter/butterTheme.doc.mjs +11 -0
  364. package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs +11 -0
  365. package/assets/templates/themes/gothic/gothicTheme.doc.mjs +11 -0
  366. package/assets/templates/themes/matcha/matchaTheme.doc.mjs +11 -0
  367. package/assets/templates/themes/neutral/neutralTheme.doc.mjs +11 -0
  368. package/assets/templates/themes/stone/stoneTheme.doc.mjs +11 -0
  369. package/assets/templates/themes/y2k/y2kTheme.doc.mjs +11 -0
  370. package/authoring/_shared/contract.ts +22 -0
  371. package/authoring/codemod/codemod.doc.mjs +7 -2
  372. package/authoring/codemod/parse.d.mts +8 -8
  373. package/authoring/codemod/parse.mjs +8 -6
  374. package/authoring/codemod/type.ts +12 -0
  375. package/authoring/config/config.doc.mjs +11 -3
  376. package/authoring/config/debug-composition.test.mjs +92 -0
  377. package/authoring/config/parse.d.mts +15 -13
  378. package/authoring/config/parse.mjs +27 -8
  379. package/authoring/config/parse.test.mjs +8 -0
  380. package/authoring/config/type.ts +29 -6
  381. package/authoring/debug/debug.doc.d.mts +11 -0
  382. package/authoring/debug/debug.doc.mjs +182 -0
  383. package/authoring/debug/parse.d.mts +8 -8
  384. package/authoring/debug/parse.mjs +3 -3
  385. package/authoring/discover/discover.doc.d.mts +13 -0
  386. package/authoring/discover/discover.doc.mjs +138 -0
  387. package/authoring/discover/parse.d.mts +24 -0
  388. package/authoring/discover/parse.mjs +128 -0
  389. package/authoring/discover/parse.test.mjs +124 -0
  390. package/authoring/discover/type.ts +87 -0
  391. package/authoring/doctypes/_schema.d.mts +792 -24
  392. package/authoring/doctypes/_schema.mjs +549 -39
  393. package/authoring/doctypes/base/graph-fields.doc.d.mts +9 -0
  394. package/authoring/doctypes/base/graph-fields.doc.mjs +64 -0
  395. package/authoring/doctypes/base/type.ts +43 -0
  396. package/authoring/doctypes/command/command.doc.mjs +4 -3
  397. package/authoring/doctypes/command/parse.d.mts +2 -2
  398. package/authoring/doctypes/command/parse.mjs +1 -1
  399. package/authoring/doctypes/command/type.ts +5 -4
  400. package/authoring/doctypes/component/component.doc.mjs +12 -3
  401. package/authoring/doctypes/component/parse.d.mts +2 -2
  402. package/authoring/doctypes/component/parse.mjs +1 -1
  403. package/authoring/doctypes/component/type.ts +14 -5
  404. package/authoring/doctypes/doctypes-new.test.mjs +48 -6
  405. package/authoring/doctypes/enum/enum.doc.mjs +1 -1
  406. package/authoring/doctypes/enum/parse.d.mts +2 -2
  407. package/authoring/doctypes/enum/parse.mjs +1 -1
  408. package/authoring/doctypes/enum/type.ts +4 -2
  409. package/authoring/doctypes/function/function.doc.mjs +7 -2
  410. package/authoring/doctypes/function/parse.d.mts +2 -2
  411. package/authoring/doctypes/function/parse.mjs +1 -1
  412. package/authoring/doctypes/function/type.ts +9 -4
  413. package/authoring/doctypes/hook/hook.doc.mjs +4 -0
  414. package/authoring/doctypes/hook/parse.d.mts +2 -2
  415. package/authoring/doctypes/hook/parse.mjs +1 -1
  416. package/authoring/doctypes/hook/type.ts +5 -4
  417. package/authoring/doctypes/legacy.d.mts +8 -6
  418. package/authoring/doctypes/legacy.mjs +5 -4
  419. package/authoring/doctypes/load-contract.test.mjs +233 -0
  420. package/authoring/doctypes/namespace/namespace.doc.d.mts +9 -0
  421. package/authoring/doctypes/namespace/namespace.doc.mjs +128 -0
  422. package/authoring/doctypes/namespace/parse.d.mts +12 -0
  423. package/authoring/doctypes/namespace/parse.mjs +25 -0
  424. package/authoring/doctypes/namespace/parse.test.mjs +163 -0
  425. package/authoring/doctypes/namespace/type.ts +74 -0
  426. package/authoring/doctypes/parse.d.mts +22 -18
  427. package/authoring/doctypes/parse.mjs +22 -11
  428. package/authoring/doctypes/parse.test.mjs +77 -3
  429. package/authoring/doctypes/reference/parse.d.mts +2 -2
  430. package/authoring/doctypes/reference/parse.mjs +8 -5
  431. package/authoring/doctypes/reference/reference.doc.mjs +55 -6
  432. package/authoring/doctypes/reference/type.ts +75 -7
  433. package/authoring/doctypes/schema/parse.d.mts +2 -2
  434. package/authoring/doctypes/schema/parse.mjs +1 -1
  435. package/authoring/doctypes/schema/schema.doc.mjs +2 -2
  436. package/authoring/doctypes/schema/type.ts +4 -4
  437. package/authoring/doctypes/template/parse.d.mts +94 -1
  438. package/authoring/doctypes/template/parse.mjs +40 -2
  439. package/authoring/doctypes/template/parse.test.mjs +26 -2
  440. package/authoring/doctypes/template/template.doc.mjs +13 -3
  441. package/authoring/doctypes/template/type.ts +13 -2
  442. package/authoring/doctypes/theme/parse.d.mts +35 -0
  443. package/authoring/doctypes/theme/parse.mjs +76 -0
  444. package/authoring/doctypes/theme/theme.doc.d.mts +9 -0
  445. package/authoring/doctypes/theme/theme.doc.mjs +79 -0
  446. package/authoring/doctypes/theme/type.ts +42 -0
  447. package/authoring/doctypes/types.ts +12 -10
  448. package/authoring/gap-report/gap-report.doc.d.mts +12 -0
  449. package/authoring/gap-report/gap-report.doc.mjs +183 -0
  450. package/authoring/gap-report/parse.d.mts +10 -10
  451. package/authoring/gap-report/parse.mjs +6 -6
  452. package/authoring/gap-report/type.ts +1 -1
  453. package/authoring/identity/identity.doc.d.mts +9 -0
  454. package/authoring/identity/identity.doc.mjs +61 -0
  455. package/authoring/identity/type.ts +132 -0
  456. package/authoring/index.d.mts +3 -0
  457. package/authoring/index.d.ts +62 -17
  458. package/authoring/index.mjs +4 -1
  459. package/authoring/integration/integration.doc.mjs +22 -13
  460. package/authoring/integration/parse.d.mts +2 -2
  461. package/authoring/integration/parse.mjs +1 -1
  462. package/authoring/integration/parse.test.mjs +10 -1
  463. package/authoring/integration/schema.d.mts +6 -4
  464. package/authoring/integration/schema.mjs +9 -3
  465. package/authoring/integration/type.ts +19 -8
  466. package/authoring/shadcn/receipt.d.mts +6 -6
  467. package/clients/cli/__tests__/cliManifest.test.ts +27 -29
  468. package/clients/cli/command-load-failure.test.mjs +83 -0
  469. package/clients/cli/commands/blog.doc.mjs +1 -1
  470. package/clients/cli/commands/blog.mjs +23 -8
  471. package/clients/cli/commands/blog.test.mjs +42 -1
  472. package/clients/cli/commands/build-theme.adaptations.test.mjs +100 -1
  473. package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
  474. package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
  475. package/clients/cli/commands/build-theme.mjs +16 -50
  476. package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
  477. package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
  478. package/clients/cli/commands/build.doc.mjs +16 -8
  479. package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
  480. package/clients/cli/commands/build.mjs +137 -114
  481. package/clients/cli/commands/build.playbook.test.mjs +75 -0
  482. package/clients/cli/commands/build.text-fields.test.mjs +81 -0
  483. package/clients/cli/commands/component/index.mjs +153 -61
  484. package/clients/cli/commands/component-batch.test.mjs +341 -0
  485. package/clients/cli/commands/component-ownership.test.mjs +92 -3
  486. package/clients/cli/commands/component-package.test.mjs +46 -0
  487. package/clients/cli/commands/component-resolution.test.mjs +21 -0
  488. package/clients/cli/commands/component.doc.mjs +28 -10
  489. package/clients/cli/commands/component.test.mjs +19 -0
  490. package/clients/cli/commands/detail-levels.test.mjs +2 -2
  491. package/clients/cli/commands/discover.broken-integration.test.mjs +52 -5
  492. package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
  493. package/clients/cli/commands/discover.doc.mjs +55 -9
  494. package/clients/cli/commands/discover.mjs +393 -118
  495. package/clients/cli/commands/discover.sources.test.mjs +267 -0
  496. package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
  497. package/clients/cli/commands/docs.doc.mjs +28 -6
  498. package/clients/cli/commands/docs.mjs +295 -38
  499. package/clients/cli/commands/doctor-integration-components.doc.mjs +1 -1
  500. package/clients/cli/commands/doctor-integration-docs.doc.mjs +6 -5
  501. package/clients/cli/commands/doctor-integration-templates.doc.mjs +15 -8
  502. package/clients/cli/commands/doctor-integration-validate.doc.mjs +1 -1
  503. package/clients/cli/commands/doctor-integration.doc.mjs +1 -1
  504. package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
  505. package/clients/cli/commands/doctor-integration.test.mjs +143 -8
  506. package/clients/cli/commands/doctor.doc.mjs +4 -2
  507. package/clients/cli/commands/doctor.mjs +108 -37
  508. package/clients/cli/commands/doctor.test.mjs +42 -0
  509. package/clients/cli/commands/gap-report.doc.mjs +27 -15
  510. package/clients/cli/commands/gap-report.test.mjs +72 -0
  511. package/clients/cli/commands/hook/index.mjs +7 -17
  512. package/clients/cli/commands/hook.doc.mjs +1 -1
  513. package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
  514. package/clients/cli/commands/init.doc.mjs +24 -10
  515. package/clients/cli/commands/init.flag-help.test.mjs +153 -0
  516. package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
  517. package/clients/cli/commands/integration-add.doc.mjs +39 -13
  518. package/clients/cli/commands/integration-authoring.test.mjs +74 -19
  519. package/clients/cli/commands/integration-pack.doc.mjs +6 -10
  520. package/clients/cli/commands/integration-real-world.test.mjs +4 -10
  521. package/clients/cli/commands/integration-verify.doc.mjs +22 -0
  522. package/clients/cli/commands/integration.doc.mjs +5 -5
  523. package/clients/cli/commands/integration.mjs +75 -43
  524. package/clients/cli/commands/interactive-guard.test.mjs +101 -24
  525. package/clients/cli/commands/json-contract.test.mjs +33 -0
  526. package/clients/cli/commands/layout-check.doc.mjs +15 -4
  527. package/clients/cli/commands/layout-expand.doc.mjs +22 -5
  528. package/clients/cli/commands/layout-grammar.doc.mjs +1 -1
  529. package/clients/cli/commands/layout.doc.mjs +3 -3
  530. package/clients/cli/commands/layout.mjs +21 -9
  531. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  532. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  533. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  534. package/clients/cli/commands/manifest.doc.mjs +2 -2
  535. package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
  536. package/clients/cli/commands/search.doc.mjs +16 -6
  537. package/clients/cli/commands/search.mjs +49 -11
  538. package/clients/cli/commands/search.test.mjs +92 -0
  539. package/clients/cli/commands/setup-nudge.test.mjs +6 -0
  540. package/clients/cli/commands/swizzle.doc.mjs +4 -3
  541. package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
  542. package/clients/cli/commands/template.doc.mjs +53 -14
  543. package/clients/cli/commands/template.flag-help.test.mjs +117 -0
  544. package/clients/cli/commands/template.mjs +4 -91
  545. package/clients/cli/commands/template.path-help.test.mjs +40 -0
  546. package/clients/cli/commands/text-json-parity.test.mjs +725 -0
  547. package/clients/cli/commands/theme-add.doc.mjs +5 -4
  548. package/clients/cli/commands/theme-build.doc.mjs +8 -7
  549. package/clients/cli/commands/theme-list.doc.mjs +2 -2
  550. package/clients/cli/commands/theme-palette-generate.doc.mjs +12 -7
  551. package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
  552. package/clients/cli/commands/theme-palette.doc.mjs +2 -3
  553. package/clients/cli/commands/theme-targets.behavior.test.mjs +4 -3
  554. package/clients/cli/commands/theme-targets.doc.mjs +3 -3
  555. package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
  556. package/clients/cli/commands/theme-template.doc.mjs +2 -2
  557. package/clients/cli/commands/theme.doc.mjs +3 -2
  558. package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
  559. package/clients/cli/commands/upgrade.doc.mjs +83 -12
  560. package/clients/cli/commands/upgrade.file-protection.test.mjs +228 -0
  561. package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
  562. package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
  563. package/clients/cli/commands/upgrade.mjs +29 -7
  564. package/clients/cli/formatters/index.mjs +164 -1
  565. package/clients/cli/formatters/index.test.mjs +97 -0
  566. package/clients/cli/index.mjs +47 -34
  567. package/clients/cli/latest-version-env.test.mjs +50 -0
  568. package/clients/cli/lib/cli-error.test.mjs +7 -0
  569. package/clients/cli/lib/component-format.mjs +9 -9
  570. package/clients/cli/lib/component-format.test.mjs +1 -1
  571. package/clients/cli/lib/define-command.mjs +56 -6
  572. package/clients/cli/lib/define-command.test.mjs +54 -0
  573. package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
  574. package/clients/cli/lib/exit-codes.test.mjs +113 -0
  575. package/clients/cli/lib/hook-format.mjs +19 -10
  576. package/clients/cli/lib/json-shim.mjs +62 -16
  577. package/clients/cli/lib/json-shim.test.mjs +83 -0
  578. package/clients/cli/lib/manifest.d.ts +2 -0
  579. package/clients/cli/lib/manifest.mjs +53 -6
  580. package/clients/cli/lib/manifest.test.mjs +22 -2
  581. package/clients/cli/lib/parse-error-format.test.mjs +81 -0
  582. package/foundation/agent-docs/agent-docs.d.mts +7 -2
  583. package/foundation/agent-docs/agent-docs.mjs +83 -13
  584. package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
  585. package/foundation/config/integration-debug.test.mjs +28 -3
  586. package/foundation/config/project-themes.test.mjs +11 -19
  587. package/foundation/config/project.d.mts +20 -11
  588. package/foundation/config/project.mjs +263 -91
  589. package/foundation/config/project.test.mjs +270 -21
  590. package/foundation/discovery/authoring-self-docs.d.mts +87 -0
  591. package/foundation/discovery/authoring-self-docs.mjs +237 -0
  592. package/foundation/discovery/authoring-self-docs.test.mjs +174 -0
  593. package/foundation/discovery/authoring-surface.d.mts +74 -0
  594. package/foundation/discovery/authoring-surface.mjs +525 -0
  595. package/foundation/discovery/authoring-surface.test.mjs +392 -0
  596. package/foundation/discovery/cli-self-docs.d.mts +119 -0
  597. package/foundation/discovery/cli-self-docs.mjs +504 -0
  598. package/foundation/discovery/cli-self-docs.test.mjs +395 -0
  599. package/foundation/discovery/component-discovery.d.mts +39 -1
  600. package/foundation/discovery/component-discovery.mjs +50 -1
  601. package/foundation/discovery/component-loader.d.mts +35 -38
  602. package/foundation/discovery/component-loader.mjs +53 -222
  603. package/foundation/discovery/docs-discovery.d.mts +119 -11
  604. package/foundation/discovery/docs-discovery.mjs +427 -108
  605. package/foundation/discovery/docs-discovery.test.mjs +386 -20
  606. package/foundation/discovery/docs-output-budget.d.mts +28 -0
  607. package/foundation/discovery/docs-output-budget.mjs +50 -0
  608. package/foundation/discovery/docs-section-key.d.mts +116 -0
  609. package/foundation/discovery/docs-section-key.mjs +322 -0
  610. package/foundation/discovery/docs-section-key.test.mjs +246 -0
  611. package/foundation/discovery/template-adapter.d.mts +113 -11
  612. package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
  613. package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
  614. package/foundation/discovery/template-adapter.mjs +774 -83
  615. package/foundation/discovery/template-adapter.test.mjs +57 -0
  616. package/foundation/discovery/template-conflict-release.d.mts +13 -0
  617. package/foundation/discovery/template-conflict-release.mjs +40 -0
  618. package/foundation/discovery/template-conflict-release.test.mjs +40 -0
  619. package/foundation/discovery/theme-discovery.d.mts +67 -7
  620. package/foundation/discovery/theme-discovery.mjs +916 -186
  621. package/foundation/discovery/theme-discovery.test.mjs +613 -219
  622. package/foundation/discovery/theming-targets.test.mjs +4 -0
  623. package/foundation/doc-compiler/bundle.d.mts +47 -0
  624. package/foundation/doc-compiler/bundle.mjs +278 -0
  625. package/foundation/doc-compiler/bundle.test.mjs +266 -0
  626. package/foundation/doc-compiler/compile.d.mts +343 -0
  627. package/foundation/doc-compiler/compile.mjs +558 -0
  628. package/foundation/doc-compiler/diagnostics.d.mts +126 -0
  629. package/foundation/doc-compiler/diagnostics.mjs +305 -0
  630. package/foundation/doc-compiler/doc-compiler.test.mjs +714 -0
  631. package/foundation/doc-compiler/doc-loads.test.mjs +1643 -0
  632. package/foundation/doc-compiler/import.d.mts +24 -0
  633. package/foundation/doc-compiler/import.mjs +59 -0
  634. package/foundation/doc-compiler/inputs.d.mts +102 -0
  635. package/foundation/doc-compiler/inputs.mjs +291 -0
  636. package/foundation/doc-compiler/inputs.test.mjs +298 -0
  637. package/foundation/doc-compiler/ir.d.mts +22 -0
  638. package/foundation/doc-compiler/ir.mjs +471 -0
  639. package/foundation/doc-compiler/lenses.d.mts +36 -0
  640. package/foundation/doc-compiler/lenses.mjs +173 -0
  641. package/foundation/doc-compiler/links.d.mts +162 -0
  642. package/foundation/doc-compiler/links.mjs +294 -0
  643. package/foundation/doc-compiler/links.test.mjs +192 -0
  644. package/foundation/doc-compiler/lower-doc.test.mjs +495 -0
  645. package/foundation/doc-compiler/overlays.d.mts +37 -0
  646. package/foundation/doc-compiler/overlays.mjs +206 -0
  647. package/foundation/doc-compiler/parse-readable.d.mts +9 -0
  648. package/foundation/doc-compiler/parse-readable.mjs +29 -0
  649. package/foundation/doc-compiler/read.d.mts +127 -0
  650. package/foundation/doc-compiler/read.mjs +325 -0
  651. package/foundation/doc-compiler/read.test.mjs +313 -0
  652. package/foundation/doc-compiler/source.d.mts +33 -0
  653. package/foundation/doc-compiler/source.mjs +128 -0
  654. package/foundation/doc-compiler/tree.d.mts +292 -0
  655. package/foundation/doc-compiler/tree.mjs +881 -0
  656. package/foundation/fs/file-protection.d.mts +33 -0
  657. package/foundation/fs/file-protection.mjs +825 -0
  658. package/foundation/fs/file-protection.test.mjs +250 -0
  659. package/foundation/fs/module-loader.d.mts +1 -0
  660. package/foundation/fs/module-loader.mjs +50 -1
  661. package/foundation/fs/module-loader.stdout.test.mjs +332 -0
  662. package/foundation/fs/path-safety.d.mts +3 -2
  663. package/foundation/fs/path-safety.mjs +49 -19
  664. package/foundation/fs/path-safety.test.mjs +50 -0
  665. package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
  666. package/foundation/identity/provider-identity.d.mts +90 -0
  667. package/foundation/identity/provider-identity.mjs +320 -0
  668. package/foundation/identity/provider-identity.test.mjs +254 -0
  669. package/foundation/identity/providers.d.mts +7 -0
  670. package/foundation/identity/providers.mjs +16 -0
  671. package/foundation/integrations/autolink.d.mts +58 -1
  672. package/foundation/integrations/autolink.mjs +143 -45
  673. package/foundation/integrations/autolink.test.mjs +1 -1
  674. package/foundation/integrations/cli-requirement.d.mts +65 -0
  675. package/foundation/integrations/cli-requirement.mjs +189 -0
  676. package/foundation/integrations/cli-requirement.test.mjs +89 -0
  677. package/foundation/integrations/contribution-fixes.d.mts +145 -0
  678. package/foundation/integrations/contribution-fixes.mjs +1284 -0
  679. package/foundation/integrations/contribution-inventory.d.mts +3 -2
  680. package/foundation/integrations/contribution-inventory.mjs +28 -25
  681. package/foundation/integrations/contribution-inventory.test.mjs +86 -27
  682. package/foundation/integrations/integration-warnings.d.mts +9 -2
  683. package/foundation/integrations/integration-warnings.mjs +52 -21
  684. package/foundation/integrations/integration-warnings.test.mjs +74 -1
  685. package/foundation/integrations/integrations.d.mts +63 -3
  686. package/foundation/integrations/integrations.mjs +122 -9
  687. package/foundation/integrations/integrations.test.mjs +415 -1
  688. package/foundation/integrations/provider-conflicts.test.mjs +125 -0
  689. package/foundation/integrations/provider-ledger.test.mjs +275 -0
  690. package/foundation/integrations/provider-resolution.d.mts +152 -0
  691. package/foundation/integrations/provider-resolution.mjs +576 -0
  692. package/foundation/integrations/provider-resolution.test.mjs +369 -0
  693. package/foundation/integrations/theme-descriptor.d.mts +8 -0
  694. package/foundation/integrations/theme-descriptor.mjs +44 -0
  695. package/foundation/integrations/validate-contributions.d.mts +2 -0
  696. package/foundation/integrations/validate-contributions.mjs +131 -29
  697. package/foundation/response/base.d.ts +8 -4
  698. package/foundation/response/batch.type.d.mts +33 -0
  699. package/foundation/response/batch.type.mjs +34 -0
  700. package/foundation/response/error-codes.d.mts +3 -1
  701. package/foundation/response/error-codes.d.ts +2 -0
  702. package/foundation/response/error-codes.doc.mjs +19 -12
  703. package/foundation/response/error-codes.mjs +8 -2
  704. package/foundation/response/error-codes.test.mjs +166 -14
  705. package/foundation/response/json-contract.test.mjs +57 -17
  706. package/foundation/response/json.d.mts +4 -2
  707. package/foundation/response/json.mjs +8 -10
  708. package/foundation/response/response-types.doc.d.mts +7 -2
  709. package/foundation/response/response-types.doc.mjs +69 -25
  710. package/foundation/response/response-types.doc.test.mjs +181 -0
  711. package/foundation/response/response.doc.mjs +12 -11
  712. package/foundation/text/string-utils.d.mts +8 -0
  713. package/foundation/text/string-utils.mjs +40 -10
  714. package/foundation/xle/expand.d.mts +2 -0
  715. package/foundation/xle/expand.mjs +4 -3
  716. package/foundation/xle/expand.test.mjs +54 -0
  717. package/foundation/xle/xle.test.mjs +13 -0
  718. package/package.json +10 -11
  719. package/api/docs/docs.test.mjs +0 -83
  720. package/api/docs/integrationDocs.test.mjs +0 -208
  721. package/api/search/search.test.mjs +0 -389
  722. package/assets/docs/cli-integrations.doc.mjs +0 -367
  723. package/assets/templates/themes/manifest.json +0 -95
  724. package/clients/cli/commands/docs.test.mjs +0 -102
  725. package/clients/cli/lib/update-check.mjs +0 -83
  726. package/clients/cli/lib/update-check.test.mjs +0 -137
  727. package/clients/cli/update-hint-commands.test.mjs +0 -54
  728. package/foundation/agent-docs/agent-docs.test.mjs +0 -1141
@@ -0,0 +1,182 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file SchemaDoc for DebugEvent, the record of one CLI run.
5
+ * @input The DebugEvent type beside it (`type.ts`), which `parse.mjs` reads.
6
+ * @output The `debug-event` section of `astryx docs authoring`.
7
+ * @position packages/cli/authoring/debug — schema documentation
8
+ */
9
+
10
+ /** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
11
+ export const doc = {
12
+ type: 'schema',
13
+ name: 'debug-event',
14
+ displayName: 'DebugEvent',
15
+ namespace: 'authoring',
16
+ description:
17
+ 'One recorded CLI run: what a `debug` handler receives, whether it is set in astryx.config or exported by an integration manifest. There is exactly one event per run, and every field is present by the time a handler sees it.',
18
+ appliesTo: 'The argument of a `debug` handler',
19
+ fields: [
20
+ {
21
+ name: 'schemaVersion',
22
+ type: 'DebugSchemaVersion',
23
+ description:
24
+ 'Version of the recorded shape: 1, 2, or 3. A field that changes meaning gets a new version, so switch on this.',
25
+ required: true,
26
+ },
27
+ {
28
+ name: 'id',
29
+ type: 'string',
30
+ description: 'Unique per run. Deduplicate on it.',
31
+ required: true,
32
+ },
33
+ {
34
+ name: 'startedAt',
35
+ type: 'string',
36
+ description: 'When the run started, as ISO 8601.',
37
+ required: true,
38
+ },
39
+ {
40
+ name: 'endedAt',
41
+ type: 'string',
42
+ description: 'When the run ended, as ISO 8601.',
43
+ required: true,
44
+ },
45
+ {
46
+ name: 'durationMs',
47
+ type: 'number',
48
+ description: 'How long the run took, in milliseconds.',
49
+ required: true,
50
+ },
51
+ {
52
+ name: 'command',
53
+ type: 'string',
54
+ description:
55
+ 'The full command name. Empty when astryx ran without a command.',
56
+ required: true,
57
+ example: "'theme build'",
58
+ },
59
+ {
60
+ name: 'commandPath',
61
+ type: 'string[]',
62
+ description: 'The command name split into segments.',
63
+ required: true,
64
+ example: "['theme', 'build']",
65
+ },
66
+ {
67
+ name: 'argv',
68
+ type: 'string[]',
69
+ description: 'The arguments after the binary, scrubbed.',
70
+ required: true,
71
+ },
72
+ {
73
+ name: 'args',
74
+ type: 'Record<string, unknown>',
75
+ description: 'Positional arguments, keyed by their declared names.',
76
+ required: true,
77
+ },
78
+ {
79
+ name: 'options',
80
+ type: 'Record<string, unknown>',
81
+ description: 'The command options, as the CLI resolved them.',
82
+ required: true,
83
+ },
84
+ {
85
+ name: 'optionSources',
86
+ type: 'Record<string, DebugOptionSource>',
87
+ description:
88
+ "Where each option value came from: 'cli', 'default', 'env', 'config', or 'implied'. The keys match `options`.",
89
+ required: true,
90
+ },
91
+ {
92
+ name: 'globalOptions',
93
+ type: 'Record<string, unknown>',
94
+ description: 'The root flags, such as --json, --detail, and --lang.',
95
+ required: true,
96
+ },
97
+ {
98
+ name: 'outcome',
99
+ type: 'DebugOutcome',
100
+ description:
101
+ "How the run ended: 'ok', 'error', 'parse-error', 'fatal', 'rejected', or 'incomplete'.",
102
+ required: true,
103
+ },
104
+ {
105
+ name: 'exitCode',
106
+ type: 'number',
107
+ description:
108
+ 'The process exit code. When a signal ended the run, 128 plus the signal number.',
109
+ required: true,
110
+ },
111
+ {
112
+ name: 'signal',
113
+ type: 'string',
114
+ description:
115
+ "The signal that ended the run, such as 'SIGINT'. Null otherwise.",
116
+ required: true,
117
+ },
118
+ {
119
+ name: 'error',
120
+ type: 'DebugEventError',
121
+ description:
122
+ 'The failure: `name`, `message`, `code`, and `stack`. Branch on `code`, never on `message`. Null when nothing failed.',
123
+ required: true,
124
+ },
125
+ {
126
+ name: 'output',
127
+ type: 'DebugEventOutput',
128
+ description:
129
+ 'What the run answered with: JSON mode, the envelope types, the result count and kind, and the stdout and stderr it printed, scrubbed and cut at the capture limit.',
130
+ required: true,
131
+ },
132
+ {
133
+ name: 'env',
134
+ type: 'DebugEventEnv',
135
+ description:
136
+ 'Runtime facts: the CLI and Node versions, platform, CI, package manager, and whether a person, an AI agent, or automation ran the command. It never holds a hostname, a user name, or a raw session ID.',
137
+ required: true,
138
+ },
139
+ {
140
+ name: 'project',
141
+ type: 'DebugEventProject',
142
+ description:
143
+ 'The project the command ran in, as flags and counts. It never holds package names.',
144
+ required: true,
145
+ },
146
+ {
147
+ name: 'redacted',
148
+ type: 'boolean',
149
+ description:
150
+ 'Whether the values in the record were scrubbed. It is true on every event a handler receives. When it is false, treat the log as sensitive.',
151
+ required: true,
152
+ },
153
+ ],
154
+ examples: [
155
+ {
156
+ label: 'Keep a local log of the runs that failed',
157
+ code:
158
+ "import {appendFileSync} from 'node:fs';\n\n" +
159
+ 'export default {\n' +
160
+ ' debug: event => {\n' +
161
+ " if (event.outcome !== 'ok') {\n" +
162
+ " appendFileSync('failed-runs.ndjson', JSON.stringify(event) + '\\n');\n" +
163
+ ' }\n' +
164
+ ' },\n' +
165
+ '};',
166
+ },
167
+ ],
168
+ notes: [
169
+ {
170
+ type: 'prose',
171
+ text: 'The shape only grows: fields are added, never removed or given a new meaning. When a meaning must change, `schemaVersion` gets a new value. In version 3, a null `output.resultKind` means the run never reached an answer, so do not count it together with a version 1 or 2 null.',
172
+ },
173
+ {
174
+ type: 'prose',
175
+ text: 'The handler runs synchronously as the process exits, so a promise it returns is never awaited. It gets a copy of the event, and anything it throws is ignored.',
176
+ },
177
+ {
178
+ type: 'prose',
179
+ text: 'Import DebugEventOutput, DebugEventEnv, DebugEventProject, and DebugEventError from @astryxdesign/cli/authoring for the fields of `output`, `env`, `project`, and `error`.',
180
+ },
181
+ ],
182
+ };
@@ -7,8 +7,8 @@
7
7
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck —
8
8
  * so a field added to the recorder without being published here breaks CI.
9
9
  *
10
- * @typedef {import('../_shared/contract').Expect<
11
- * import('../_shared/contract').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
10
+ * @typedef {import('../_shared/contract.js').Expect<
11
+ * import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
12
12
  * >} _DebugEventDriftLock
13
13
  */
14
14
  /**
@@ -29,8 +29,8 @@ export function parseDebugEvent(input: unknown, label?: string): DebugEvent;
29
29
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck —
30
30
  * so a field added to the recorder without being published here breaks CI.
31
31
  */
32
- export type _DebugEventDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>>;
33
- export type DebugEvent = import("./type").DebugEvent;
32
+ export type _DebugEventDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>>;
33
+ export type DebugEvent = import("./type.js").DebugEvent;
34
34
  import { z } from 'zod';
35
35
  declare const eventSchema: z.ZodObject<{
36
36
  schemaVersion: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
@@ -52,8 +52,8 @@ declare const eventSchema: z.ZodObject<{
52
52
  }>>;
53
53
  globalOptions: z.ZodRecord<z.ZodString, z.ZodUnknown>;
54
54
  outcome: z.ZodEnum<{
55
- ok: "ok";
56
55
  error: "error";
56
+ ok: "ok";
57
57
  "parse-error": "parse-error";
58
58
  fatal: "fatal";
59
59
  rejected: "rejected";
@@ -77,12 +77,12 @@ declare const eventSchema: z.ZodObject<{
77
77
  resultKind: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
78
78
  theme: "theme";
79
79
  component: "component";
80
+ command: "command";
80
81
  hook: "hook";
81
- doc: "doc";
82
82
  template: "template";
83
+ doc: "doc";
83
84
  integration: "integration";
84
85
  migration: "migration";
85
- command: "command";
86
86
  mixed: "mixed";
87
87
  none: "none";
88
88
  }>>>;
@@ -106,10 +106,10 @@ declare const eventSchema: z.ZodObject<{
106
106
  agentSessionIdHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
107
107
  agentSessionIdSource: z.ZodDefault<z.ZodNullable<z.ZodString>>;
108
108
  invocationSource: z.ZodDefault<z.ZodEnum<{
109
+ unknown: "unknown";
109
110
  human: "human";
110
111
  ai: "ai";
111
112
  automation: "automation";
112
- unknown: "unknown";
113
113
  }>>;
114
114
  oneOff: z.ZodBoolean;
115
115
  packageManager: z.ZodNullable<z.ZodString>;
@@ -22,7 +22,7 @@
22
22
  import {z} from 'zod';
23
23
  import {formatZodError} from '../_shared/errors.mjs';
24
24
 
25
- /** @typedef {import('./type').DebugEvent} DebugEvent */
25
+ /** @typedef {import('./type.js').DebugEvent} DebugEvent */
26
26
 
27
27
  const outcomeSchema = z.enum([
28
28
  'ok',
@@ -169,8 +169,8 @@ const eventSchema = z
169
169
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck —
170
170
  * so a field added to the recorder without being published here breaks CI.
171
171
  *
172
- * @typedef {import('../_shared/contract').Expect<
173
- * import('../_shared/contract').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
172
+ * @typedef {import('../_shared/contract.js').Expect<
173
+ * import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof eventSchema>, DebugEvent>
174
174
  * >} _DebugEventDriftLock
175
175
  */
176
176
 
@@ -0,0 +1,13 @@
1
+ // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
2
+ // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
3
+
4
+ /**
5
+ * @file SchemaDoc for DiscoverSource, the function `astryx discover` calls to
6
+ * learn which integrations a project could add.
7
+ * @input The DiscoverSource type and the catalog types beside it (`type.ts`),
8
+ * which `parse.mjs` validates.
9
+ * @output The `discover-source` section of `astryx docs authoring`.
10
+ * @position packages/cli/authoring/discover — schema documentation
11
+ */
12
+ /** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
13
+ export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;
@@ -0,0 +1,138 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file SchemaDoc for DiscoverSource, the function `astryx discover` calls to
5
+ * learn which integrations a project could add.
6
+ * @input The DiscoverSource type and the catalog types beside it (`type.ts`),
7
+ * which `parse.mjs` validates.
8
+ * @output The `discover-source` section of `astryx docs authoring`.
9
+ * @position packages/cli/authoring/discover — schema documentation
10
+ */
11
+
12
+ /** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
13
+ export const doc = {
14
+ type: 'schema',
15
+ name: 'discover-source',
16
+ displayName: 'DiscoverSource',
17
+ namespace: 'authoring',
18
+ description:
19
+ 'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer it saved for that source. Discover only reads: it prints the command that adds a package and never runs it.',
20
+ appliesTo:
21
+ '`discover` in astryx.config.*, or the `discover` named export of astryx.integration.*',
22
+ fields: [
23
+ {
24
+ name: 'context',
25
+ type: 'DiscoverSourceContext',
26
+ description: 'The one argument the source is called with.',
27
+ required: true,
28
+ fields: [
29
+ {
30
+ name: 'context.signal',
31
+ type: 'AbortSignal',
32
+ description: 'Aborted when the source runs past 30 seconds.',
33
+ required: true,
34
+ },
35
+ {
36
+ name: 'context.package',
37
+ type: 'string',
38
+ description:
39
+ 'Set when discover shows one package: return that package with every version.',
40
+ },
41
+ {
42
+ name: 'context.version',
43
+ type: 'string',
44
+ description:
45
+ "With `package`: return that version's contributions. Without it, the latest release's.",
46
+ },
47
+ ],
48
+ },
49
+ {
50
+ name: 'returns',
51
+ type: 'Promise<DiscoverCatalog>',
52
+ description:
53
+ 'The catalog. Discover checks it, ignores fields and item kinds it does not know, and refuses any schemaVersion but 1.',
54
+ required: true,
55
+ fields: [
56
+ {
57
+ name: 'schemaVersion',
58
+ type: '1',
59
+ description: 'Version of the catalog shape.',
60
+ required: true,
61
+ },
62
+ {
63
+ name: 'source',
64
+ type: '{name: string, generatedAt: string, complete: boolean}',
65
+ description:
66
+ 'Who answered, when the data was produced (ISO 8601), and false when the source knows its list is partial.',
67
+ required: true,
68
+ },
69
+ {
70
+ name: 'packages',
71
+ type: 'DiscoverPackage[]',
72
+ description:
73
+ 'One entry per npm package. When two sources list the same package, the earlier source wins.',
74
+ required: true,
75
+ fields: [
76
+ {
77
+ name: 'packages[].package',
78
+ type: 'string',
79
+ description: 'The npm name.',
80
+ required: true,
81
+ },
82
+ {
83
+ name: 'packages[].integration',
84
+ type: 'string',
85
+ description:
86
+ 'Shared by every npm name that publishes the same integration. Discover lists an integration once.',
87
+ required: true,
88
+ },
89
+ {
90
+ name: 'packages[].aliases',
91
+ type: 'string[]',
92
+ description:
93
+ "The integration's other npm names. Discover never offers a package the project has under another name.",
94
+ required: true,
95
+ },
96
+ {
97
+ name: 'packages[].description',
98
+ type: 'string',
99
+ description: 'One line, for the list and search.',
100
+ },
101
+ {
102
+ name: 'packages[].latest',
103
+ type: 'string | null',
104
+ description: 'The latest release. Null when there are only prereleases.',
105
+ required: true,
106
+ },
107
+ {
108
+ name: 'packages[].versions',
109
+ type: 'DiscoverVersion[]',
110
+ description:
111
+ 'Every version, newest first: `{version, publishedAt, prerelease, status}`, where status is `ok` or why the version could not be read.',
112
+ required: true,
113
+ },
114
+ {
115
+ name: 'packages[].contributions',
116
+ type: 'DiscoverContribution[]',
117
+ description:
118
+ "What the requested (else latest) version adds: `{kind, name, title?, summary?, keywords?}`, where kind is `component`, `template`, `doc`, `theme`, `codemod`, or `agent-doc` (a DiscoverKind) and name is the name the CLI uses for it.",
119
+ required: true,
120
+ },
121
+ ],
122
+ },
123
+ ],
124
+ },
125
+ ],
126
+ examples: [
127
+ {
128
+ label: 'A project source in astryx.config',
129
+ code:
130
+ 'export default {\n' +
131
+ ' async discover({signal, package: name, version}) {\n' +
132
+ ' const res = await fetch(catalogUrl(name, version), {signal});\n' +
133
+ ' return res.json();\n' +
134
+ ' },\n' +
135
+ '};',
136
+ },
137
+ ],
138
+ };
@@ -0,0 +1,24 @@
1
+ // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
2
+ // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
3
+
4
+ /**
5
+ * Check a catalog a discover source returned. Throws an Error naming the first
6
+ * problem. Items of a kind this CLI does not know are dropped, and versions are
7
+ * put newest first whatever order the source used.
8
+ *
9
+ * @param {unknown} value
10
+ * @param {string} [label]
11
+ * @returns {import('./type.js').DiscoverCatalog}
12
+ */
13
+ export function parseDiscoverCatalog(value: unknown, label?: string): import("./type.js").DiscoverCatalog;
14
+ /**
15
+ * Check a discover source itself: an async function, like `debug`, that takes
16
+ * `{signal, package?, version?}` and resolves to a catalog.
17
+ *
18
+ * @param {unknown} value
19
+ * @param {string} label
20
+ * @returns {import('./type.js').DiscoverSource}
21
+ */
22
+ export function parseDiscoverSource(value: unknown, label: string): import("./type.js").DiscoverSource;
23
+ /** Item kinds a catalog may list, in display order. */
24
+ export const DISCOVER_KINDS: readonly ["component", "template", "doc", "theme", "codemod", "agent-doc"];
@@ -0,0 +1,128 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file Runtime checks for discover sources and the catalogs they return.
5
+ *
6
+ * The catalog schema is deliberately not strict: a source may add fields this
7
+ * CLI does not know, and they are dropped. An unknown `schemaVersion` is
8
+ * refused, and an item of a kind this CLI does not know is skipped, so a newer
9
+ * source never breaks an older CLI.
10
+ *
11
+ * @position packages/cli/authoring/discover — parse + validate, no I/O.
12
+ */
13
+
14
+ import {z} from 'zod';
15
+
16
+ /** Item kinds a catalog may list, in display order. */
17
+ export const DISCOVER_KINDS = /** @type {const} */ ([
18
+ 'component',
19
+ 'template',
20
+ 'doc',
21
+ 'theme',
22
+ 'codemod',
23
+ 'agent-doc',
24
+ ]);
25
+
26
+ const text = (/** @type {number} */ max) => z.string().min(1).max(max);
27
+
28
+ const contributionSchema = z.object({
29
+ kind: text(32),
30
+ name: text(512),
31
+ title: z.string().max(512).optional(),
32
+ summary: z.string().max(4096).optional(),
33
+ keywords: z.array(z.string().max(128)).max(64).optional(),
34
+ });
35
+
36
+ const versionSchema = z.object({
37
+ version: text(256),
38
+ publishedAt: z.string().max(64).nullable(),
39
+ prerelease: z.boolean(),
40
+ status: text(64),
41
+ });
42
+
43
+ const packageSchema = z.object({
44
+ package: text(214),
45
+ integration: text(214),
46
+ aliases: z.array(text(214)).max(64),
47
+ description: z.string().max(1024).optional(),
48
+ latest: text(256).nullable(),
49
+ versions: z.array(versionSchema).max(50_000),
50
+ contributions: z.array(contributionSchema).max(50_000),
51
+ });
52
+
53
+ const catalogSchema = z.object({
54
+ schemaVersion: z.literal(1),
55
+ source: z.object({
56
+ name: text(256),
57
+ generatedAt: text(64),
58
+ complete: z.boolean(),
59
+ }),
60
+ packages: z.array(packageSchema).max(20_000),
61
+ });
62
+
63
+ /**
64
+ * Newest first by publish time. A version with no known publish time goes
65
+ * last, and ties fall back to the version number.
66
+ * @param {{version: string, publishedAt: string | null}} a
67
+ * @param {{version: string, publishedAt: string | null}} b
68
+ */
69
+ function newestFirst(a, b) {
70
+ const at = Date.parse(a.publishedAt ?? '');
71
+ const bt = Date.parse(b.publishedAt ?? '');
72
+ if (Number.isNaN(at) !== Number.isNaN(bt)) return Number.isNaN(at) ? 1 : -1;
73
+ if (!Number.isNaN(at) && at !== bt) return bt - at;
74
+ return b.version.localeCompare(a.version, 'en', {numeric: true});
75
+ }
76
+
77
+ /**
78
+ * Check a catalog a discover source returned. Throws an Error naming the first
79
+ * problem. Items of a kind this CLI does not know are dropped, and versions are
80
+ * put newest first whatever order the source used.
81
+ *
82
+ * @param {unknown} value
83
+ * @param {string} [label]
84
+ * @returns {import('./type.js').DiscoverCatalog}
85
+ */
86
+ export function parseDiscoverCatalog(value, label = 'discover source') {
87
+ const version =
88
+ value != null && typeof value === 'object'
89
+ ? /** @type {{schemaVersion?: unknown}} */ (value).schemaVersion
90
+ : undefined;
91
+ if (version !== undefined && version !== 1) {
92
+ throw new Error(
93
+ `${label} returned schemaVersion ${String(version)}; this CLI reads schemaVersion 1`,
94
+ );
95
+ }
96
+ const parsed = catalogSchema.safeParse(value);
97
+ if (!parsed.success) {
98
+ const issue = parsed.error.issues[0];
99
+ const where = issue?.path.length ? ` at ${issue.path.join('.')}` : '';
100
+ throw new Error(
101
+ `${label} returned an invalid catalog${where}: ${issue?.message}`,
102
+ );
103
+ }
104
+ const known = /** @type {readonly string[]} */ (DISCOVER_KINDS);
105
+ return /** @type {import('./type.js').DiscoverCatalog} */ ({
106
+ ...parsed.data,
107
+ packages: parsed.data.packages.map(pkg => ({
108
+ ...pkg,
109
+ versions: [...pkg.versions].sort(newestFirst),
110
+ contributions: pkg.contributions.filter(c => known.includes(c.kind)),
111
+ })),
112
+ });
113
+ }
114
+
115
+ /**
116
+ * Check a discover source itself: an async function, like `debug`, that takes
117
+ * `{signal, package?, version?}` and resolves to a catalog.
118
+ *
119
+ * @param {unknown} value
120
+ * @param {string} label
121
+ * @returns {import('./type.js').DiscoverSource}
122
+ */
123
+ export function parseDiscoverSource(value, label) {
124
+ if (typeof value !== 'function') {
125
+ throw new Error(`${label} must be a function`);
126
+ }
127
+ return /** @type {import('./type.js').DiscoverSource} */ (value);
128
+ }
@@ -0,0 +1,124 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file Tests for the discover source and catalog checks.
5
+ */
6
+
7
+ import {describe, it, expect} from 'vitest';
8
+ import {
9
+ DISCOVER_KINDS,
10
+ parseDiscoverCatalog,
11
+ parseDiscoverSource,
12
+ } from './parse.mjs';
13
+
14
+ function catalog(overrides = {}) {
15
+ return {
16
+ schemaVersion: 1,
17
+ source: {
18
+ name: 'Acme catalog',
19
+ generatedAt: '2026-09-30T14:00:00.000Z',
20
+ complete: true,
21
+ },
22
+ packages: [
23
+ {
24
+ package: '@acme/ui',
25
+ integration: 'acme-ui',
26
+ aliases: [],
27
+ latest: '2.0.0',
28
+ versions: [
29
+ {
30
+ version: '2.0.0',
31
+ publishedAt: '2026-09-29T00:00:00.000Z',
32
+ prerelease: false,
33
+ status: 'ok',
34
+ },
35
+ ],
36
+ contributions: [{kind: 'component', name: 'Button'}],
37
+ },
38
+ ],
39
+ ...overrides,
40
+ };
41
+ }
42
+
43
+ describe('parseDiscoverCatalog', () => {
44
+ it('accepts a catalog', () => {
45
+ expect(parseDiscoverCatalog(catalog())).toEqual(catalog());
46
+ });
47
+
48
+ it('drops fields it does not know, so a newer source still works', () => {
49
+ const parsed = parseDiscoverCatalog({...catalog(), cursor: 'next'});
50
+ expect(parsed).not.toHaveProperty('cursor');
51
+ });
52
+
53
+ it('drops items of a kind it does not know', () => {
54
+ const value = catalog();
55
+ value.packages[0].contributions.push({kind: 'widget', name: 'Spinner'});
56
+ expect(parseDiscoverCatalog(value).packages[0].contributions).toEqual([
57
+ {kind: 'component', name: 'Button'},
58
+ ]);
59
+ });
60
+
61
+ it('puts versions newest first whatever order the source used', () => {
62
+ const value = catalog();
63
+ value.packages[0].versions = [
64
+ {
65
+ version: '1.0.0',
66
+ publishedAt: '2026-01-05T00:00:00.000Z',
67
+ prerelease: false,
68
+ status: 'ok',
69
+ },
70
+ {version: '1.5.0', publishedAt: null, prerelease: false, status: 'ok'},
71
+ {
72
+ version: '2.0.0',
73
+ publishedAt: '2026-09-29T00:00:00.000Z',
74
+ prerelease: false,
75
+ status: 'ok',
76
+ },
77
+ {
78
+ version: '2.0.0-rc.1',
79
+ publishedAt: '2026-09-01T00:00:00.000Z',
80
+ prerelease: true,
81
+ status: 'ok',
82
+ },
83
+ ];
84
+ expect(
85
+ parseDiscoverCatalog(value).packages[0].versions.map(v => v.version),
86
+ ).toEqual(['2.0.0', '2.0.0-rc.1', '1.0.0', '1.5.0']);
87
+ });
88
+
89
+ it('refuses a schemaVersion it does not read', () => {
90
+ expect(() => parseDiscoverCatalog(catalog({schemaVersion: 2}))).toThrow(
91
+ 'this CLI reads schemaVersion 1',
92
+ );
93
+ });
94
+
95
+ it('names the first problem and where it is', () => {
96
+ expect(() =>
97
+ parseDiscoverCatalog(catalog({packages: [{package: ''}]}), 'the source'),
98
+ ).toThrow(/^the source returned an invalid catalog at packages\.0\./);
99
+ });
100
+
101
+ it('lists the kinds in display order', () => {
102
+ expect(DISCOVER_KINDS).toEqual([
103
+ 'component',
104
+ 'template',
105
+ 'doc',
106
+ 'theme',
107
+ 'codemod',
108
+ 'agent-doc',
109
+ ]);
110
+ });
111
+ });
112
+
113
+ describe('parseDiscoverSource', () => {
114
+ it('accepts a function', () => {
115
+ const source = async () => catalog();
116
+ expect(parseDiscoverSource(source, 'discover')).toBe(source);
117
+ });
118
+
119
+ it('refuses anything else, such as a URL', () => {
120
+ expect(() =>
121
+ parseDiscoverSource('https://example.com/catalog.json', 'discover'),
122
+ ).toThrow('discover must be a function');
123
+ });
124
+ });