@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

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 (276) hide show
  1. package/README.md +22 -1
  2. package/api/blog/blog.doc.mjs +1 -0
  3. package/api/build/build.doc.mjs +1 -0
  4. package/api/component/component.doc.mjs +1 -0
  5. package/api/discover/discover.doc.mjs +1 -0
  6. package/api/docs/_adapter.d.mts +3 -8
  7. package/api/docs/_adapter.mjs +13 -105
  8. package/api/docs/detail/section/section.mjs +9 -15
  9. package/api/docs/detail/section/section.test.mjs +15 -6
  10. package/api/docs/docs.doc.mjs +1 -0
  11. package/api/docs/list/list.mjs +3 -7
  12. package/api/doctor/doctor.d.mts +25 -3
  13. package/api/doctor/doctor.doc.mjs +1 -0
  14. package/api/doctor/doctor.mjs +186 -14
  15. package/api/doctor/doctor.test.mjs +332 -7
  16. package/api/gap-report/gap-report.doc.mjs +1 -0
  17. package/api/hook/_adapter.mjs +19 -5
  18. package/api/hook/hook.doc.mjs +1 -0
  19. package/api/hook/list/list.d.mts +1 -1
  20. package/api/hook/list/list.mjs +69 -17
  21. package/api/init/init.doc.mjs +1 -0
  22. package/api/integration/add-contribution.mjs +7 -7
  23. package/api/integration/add-contribution.test.mjs +37 -3
  24. package/api/integration/add-theme.mjs +34 -64
  25. package/api/integration/add-theme.test.mjs +105 -21
  26. package/api/integration/authoring-checks.test.mjs +8 -4
  27. package/api/integration/integration-block-exports.test.mjs +10 -6
  28. package/api/integration/integrationAdd.doc.mjs +1 -0
  29. package/api/integration/integrationAddAgentDoc.doc.mjs +1 -0
  30. package/api/integration/integrationAddCodemod.doc.mjs +1 -0
  31. package/api/integration/integrationAddComponent.doc.mjs +1 -0
  32. package/api/integration/integrationAddDoc.doc.mjs +1 -0
  33. package/api/integration/integrationAddTemplate.doc.mjs +1 -0
  34. package/api/integration/integrationAddTheme.doc.mjs +6 -5
  35. package/api/integration/integrationComponentConflicts.doc.mjs +1 -0
  36. package/api/integration/integrationDocConflicts.doc.mjs +1 -0
  37. package/api/integration/integrationPackCheck.doc.mjs +1 -0
  38. package/api/integration/integrationTemplateConflicts.doc.mjs +1 -0
  39. package/api/integration/pack-check.test.mjs +17 -47
  40. package/api/integration/summarizeIssues.doc.mjs +1 -0
  41. package/api/integration/validate-integration-fixes.test.mjs +1389 -0
  42. package/api/integration/validate-integration.mjs +50 -102
  43. package/api/integration/validate-integration.test.mjs +85 -23
  44. package/api/integration/validate-unread-theme-folders.test.mjs +110 -0
  45. package/api/integration/validateIntegration.doc.mjs +1 -0
  46. package/api/json/assertResponse.doc.mjs +1 -0
  47. package/api/json/isError.doc.mjs +1 -0
  48. package/api/json/parseResponse.doc.mjs +1 -0
  49. package/api/layout/layoutCheck.doc.mjs +1 -0
  50. package/api/layout/layoutExpand.doc.mjs +1 -0
  51. package/api/layout/layoutGrammar.doc.mjs +1 -0
  52. package/api/search/search.doc.mjs +1 -0
  53. package/api/search/search.mjs +16 -6
  54. package/api/swizzle/swizzle.doc.mjs +1 -0
  55. package/api/template/template-suffix.test.mjs +41 -21
  56. package/api/template/template.doc.mjs +1 -0
  57. package/api/theme/_adapter.d.mts +2 -3
  58. package/api/theme/_adapter.mjs +4 -5
  59. package/api/theme/add/add.binary.test.mjs +10 -17
  60. package/api/theme/add/add.test.mjs +14 -1
  61. package/api/theme/generateTonalPalette.doc.mjs +1 -0
  62. package/api/theme/integration-themes.test.mjs +39 -28
  63. package/api/theme/list/list.test.mjs +19 -20
  64. package/api/theme/listThemes.doc.mjs +6 -5
  65. package/api/theme/themeAdd.doc.mjs +4 -3
  66. package/api/theme/themeBuild.doc.mjs +1 -0
  67. package/api/theme/themeList.doc.mjs +6 -3
  68. package/api/theme/themeListAvailable.doc.mjs +5 -3
  69. package/api/theme/themePaletteGenerate.doc.mjs +1 -0
  70. package/api/theme/themeTargets.doc.mjs +1 -0
  71. package/api/theme/themeTemplate.doc.mjs +1 -0
  72. package/api/upgrade/_adapter.d.mts +32 -5
  73. package/api/upgrade/_adapter.mjs +97 -69
  74. package/api/upgrade/provider-agreement.test.mjs +152 -0
  75. package/api/upgrade/run/run.mjs +356 -59
  76. package/api/upgrade/upgrade.doc.mjs +6 -1
  77. package/api/upgrade/upgrade.type.d.mts +34 -0
  78. package/api/upgrade/upgrade.type.mjs +15 -0
  79. package/assets/codemods/__tests__/runner.test.mjs +330 -8
  80. package/assets/codemods/integration-discovery.mjs +8 -2
  81. package/assets/codemods/integration-discovery.test.mjs +15 -0
  82. package/assets/codemods/integration-runner.mjs +56 -4
  83. package/assets/codemods/integration-runner.protection.test.mjs +153 -0
  84. package/assets/codemods/run-codemod.mjs +177 -34
  85. package/assets/codemods/runner.mjs +350 -102
  86. package/assets/codemods/transforms/next/__tests__/migrate-native-picker-to-presentation.test.mjs +63 -0
  87. package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs +220 -0
  88. package/assets/codemods/transforms/next/index.mjs +19 -1
  89. package/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs +148 -0
  90. package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs +141 -0
  91. package/assets/docs/cli-integrations.doc.mjs +30 -30
  92. package/assets/docs/cli.doc.mjs +15 -0
  93. package/assets/docs/theme.doc.mjs +1 -1
  94. package/assets/templates/blocks/components/DateInput/DateInputDateRange.tsx +1 -1
  95. package/assets/templates/blocks/components/Item/ItemDocumentTabs.doc.mjs +14 -0
  96. package/assets/templates/blocks/components/Item/ItemDocumentTabs.tsx +100 -0
  97. package/assets/templates/blocks/components/TimeInput/TimeInputConstrained.tsx +1 -0
  98. package/assets/templates/themes/butter/butterTheme.doc.mjs +11 -0
  99. package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs +11 -0
  100. package/assets/templates/themes/gothic/gothicTheme.doc.mjs +11 -0
  101. package/assets/templates/themes/matcha/matchaTheme.doc.mjs +11 -0
  102. package/assets/templates/themes/neutral/neutralTheme.doc.mjs +11 -0
  103. package/assets/templates/themes/stone/stoneTheme.doc.mjs +11 -0
  104. package/assets/templates/themes/y2k/y2kTheme.doc.mjs +11 -0
  105. package/authoring/codemod/codemod.doc.mjs +1 -1
  106. package/authoring/codemod/type.ts +12 -0
  107. package/authoring/config/config.doc.mjs +1 -1
  108. package/authoring/debug/debug.doc.d.mts +11 -0
  109. package/authoring/debug/debug.doc.mjs +182 -0
  110. package/authoring/doctypes/_schema.d.mts +71 -141
  111. package/authoring/doctypes/_schema.mjs +29 -2
  112. package/authoring/doctypes/base/graph-fields.doc.mjs +1 -1
  113. package/authoring/doctypes/command/command.doc.mjs +1 -1
  114. package/authoring/doctypes/command/type.ts +1 -1
  115. package/authoring/doctypes/component/type.ts +2 -2
  116. package/authoring/doctypes/doctypes-new.test.mjs +48 -6
  117. package/authoring/doctypes/enum/enum.doc.mjs +1 -1
  118. package/authoring/doctypes/enum/type.ts +1 -1
  119. package/authoring/doctypes/function/function.doc.mjs +1 -1
  120. package/authoring/doctypes/function/type.ts +1 -1
  121. package/authoring/doctypes/hook/type.ts +2 -2
  122. package/authoring/doctypes/load-contract.test.mjs +3 -2
  123. package/authoring/doctypes/namespace/namespace.doc.mjs +2 -2
  124. package/authoring/doctypes/namespace/parse.test.mjs +23 -25
  125. package/authoring/doctypes/namespace/type.ts +5 -2
  126. package/authoring/doctypes/parse.d.mts +4 -2
  127. package/authoring/doctypes/parse.mjs +10 -5
  128. package/authoring/doctypes/reference/reference.doc.mjs +6 -4
  129. package/authoring/doctypes/reference/type.ts +9 -10
  130. package/authoring/doctypes/schema/schema.doc.mjs +1 -1
  131. package/authoring/doctypes/schema/type.ts +1 -2
  132. package/authoring/doctypes/template/template.doc.mjs +3 -3
  133. package/authoring/doctypes/theme/parse.d.mts +35 -0
  134. package/authoring/doctypes/theme/parse.mjs +76 -0
  135. package/authoring/doctypes/theme/theme.doc.d.mts +9 -0
  136. package/authoring/doctypes/theme/theme.doc.mjs +79 -0
  137. package/authoring/doctypes/theme/type.ts +42 -0
  138. package/authoring/doctypes/types.ts +2 -1
  139. package/authoring/gap-report/gap-report.doc.d.mts +12 -0
  140. package/authoring/gap-report/gap-report.doc.mjs +183 -0
  141. package/authoring/index.d.mts +1 -0
  142. package/authoring/index.d.ts +7 -4
  143. package/authoring/index.mjs +2 -1
  144. package/authoring/integration/integration.doc.mjs +2 -2
  145. package/authoring/integration/type.ts +3 -9
  146. package/clients/cli/__tests__/cliManifest.test.ts +27 -29
  147. package/clients/cli/commands/blog.doc.mjs +1 -1
  148. package/clients/cli/commands/build-theme.adaptations.test.mjs +100 -1
  149. package/clients/cli/commands/build-theme.mjs +10 -44
  150. package/clients/cli/commands/build.doc.mjs +1 -1
  151. package/clients/cli/commands/component.doc.mjs +1 -1
  152. package/clients/cli/commands/discover.doc.mjs +1 -1
  153. package/clients/cli/commands/docs.doc.mjs +1 -1
  154. package/clients/cli/commands/docs.mjs +15 -58
  155. package/clients/cli/commands/docs.test.mjs +11 -14
  156. package/clients/cli/commands/doctor-integration-components.doc.mjs +1 -1
  157. package/clients/cli/commands/doctor-integration-docs.doc.mjs +1 -1
  158. package/clients/cli/commands/doctor-integration-templates.doc.mjs +1 -1
  159. package/clients/cli/commands/doctor-integration-validate.doc.mjs +1 -1
  160. package/clients/cli/commands/doctor-integration.doc.mjs +1 -1
  161. package/clients/cli/commands/doctor-integration.test.mjs +15 -7
  162. package/clients/cli/commands/doctor.doc.mjs +1 -1
  163. package/clients/cli/commands/gap-report.doc.mjs +1 -1
  164. package/clients/cli/commands/hook.doc.mjs +1 -1
  165. package/clients/cli/commands/init.doc.mjs +1 -1
  166. package/clients/cli/commands/integration-add.controls.test.mjs +1 -1
  167. package/clients/cli/commands/integration-add.doc.mjs +1 -1
  168. package/clients/cli/commands/integration-pack.doc.mjs +1 -1
  169. package/clients/cli/commands/integration-real-world.test.mjs +3 -9
  170. package/clients/cli/commands/integration.doc.mjs +1 -1
  171. package/clients/cli/commands/layout-check.doc.mjs +1 -1
  172. package/clients/cli/commands/layout-expand.doc.mjs +1 -1
  173. package/clients/cli/commands/layout-grammar.doc.mjs +1 -1
  174. package/clients/cli/commands/layout.doc.mjs +1 -1
  175. package/clients/cli/commands/manifest.doc.mjs +1 -1
  176. package/clients/cli/commands/search.doc.mjs +1 -1
  177. package/clients/cli/commands/swizzle.doc.mjs +1 -1
  178. package/clients/cli/commands/template.doc.mjs +1 -1
  179. package/clients/cli/commands/text-json-parity.test.mjs +718 -0
  180. package/clients/cli/commands/theme-add.doc.mjs +2 -2
  181. package/clients/cli/commands/theme-build.doc.mjs +1 -1
  182. package/clients/cli/commands/theme-list.doc.mjs +2 -2
  183. package/clients/cli/commands/theme-palette-generate.doc.mjs +3 -3
  184. package/clients/cli/commands/theme-palette.doc.mjs +1 -1
  185. package/clients/cli/commands/theme-targets.behavior.test.mjs +4 -3
  186. package/clients/cli/commands/theme-targets.doc.mjs +1 -1
  187. package/clients/cli/commands/theme-template.doc.mjs +1 -1
  188. package/clients/cli/commands/theme.doc.mjs +1 -1
  189. package/clients/cli/commands/upgrade.doc.mjs +3 -2
  190. package/clients/cli/commands/upgrade.file-protection.test.mjs +228 -0
  191. package/clients/cli/commands/upgrade.mjs +29 -7
  192. package/clients/cli/formatters/index.mjs +2 -0
  193. package/clients/cli/formatters/index.test.mjs +6 -0
  194. package/clients/cli/lib/hook-format.mjs +14 -5
  195. package/foundation/config/project-themes.test.mjs +11 -19
  196. package/foundation/config/project.d.mts +8 -0
  197. package/foundation/config/project.mjs +50 -21
  198. package/foundation/config/project.test.mjs +3 -16
  199. package/foundation/discovery/authoring-self-docs.d.mts +6 -0
  200. package/foundation/discovery/authoring-self-docs.mjs +17 -7
  201. package/foundation/discovery/authoring-self-docs.test.mjs +3 -2
  202. package/foundation/discovery/authoring-surface.d.mts +74 -0
  203. package/foundation/discovery/authoring-surface.mjs +525 -0
  204. package/foundation/discovery/authoring-surface.test.mjs +392 -0
  205. package/foundation/discovery/cli-self-docs.d.mts +113 -0
  206. package/foundation/discovery/cli-self-docs.mjs +514 -0
  207. package/foundation/discovery/cli-self-docs.test.mjs +437 -0
  208. package/foundation/discovery/component-loader.d.mts +35 -38
  209. package/foundation/discovery/component-loader.mjs +53 -222
  210. package/foundation/discovery/docs-discovery.d.mts +3 -2
  211. package/foundation/discovery/docs-discovery.mjs +14 -17
  212. package/foundation/discovery/docs-discovery.test.mjs +15 -15
  213. package/foundation/discovery/docs-section-key.d.mts +19 -8
  214. package/foundation/discovery/docs-section-key.mjs +119 -32
  215. package/foundation/discovery/docs-section-key.test.mjs +41 -19
  216. package/foundation/discovery/template-adapter.d.mts +7 -0
  217. package/foundation/discovery/template-adapter.mjs +27 -40
  218. package/foundation/discovery/template-adapter.test.mjs +15 -0
  219. package/foundation/discovery/theme-discovery.d.mts +67 -7
  220. package/foundation/discovery/theme-discovery.mjs +916 -186
  221. package/foundation/discovery/theme-discovery.test.mjs +613 -219
  222. package/foundation/doc-compiler/bundle.d.mts +47 -0
  223. package/foundation/doc-compiler/bundle.mjs +218 -0
  224. package/foundation/doc-compiler/bundle.test.mjs +255 -0
  225. package/foundation/doc-compiler/compile.d.mts +200 -0
  226. package/foundation/doc-compiler/compile.mjs +259 -9
  227. package/foundation/doc-compiler/diagnostics.d.mts +126 -0
  228. package/foundation/doc-compiler/diagnostics.mjs +277 -0
  229. package/foundation/doc-compiler/doc-compiler.test.mjs +28 -1
  230. package/foundation/doc-compiler/doc-loads.test.mjs +1642 -0
  231. package/foundation/doc-compiler/import.d.mts +24 -0
  232. package/foundation/doc-compiler/import.mjs +59 -0
  233. package/foundation/doc-compiler/inputs.d.mts +102 -0
  234. package/foundation/doc-compiler/inputs.mjs +286 -0
  235. package/foundation/doc-compiler/inputs.test.mjs +299 -0
  236. package/foundation/doc-compiler/ir.d.mts +13 -0
  237. package/foundation/doc-compiler/ir.mjs +189 -12
  238. package/foundation/doc-compiler/lower-doc.test.mjs +492 -0
  239. package/foundation/doc-compiler/overlays.d.mts +37 -0
  240. package/foundation/doc-compiler/overlays.mjs +206 -0
  241. package/foundation/doc-compiler/parse-readable.d.mts +9 -0
  242. package/foundation/doc-compiler/parse-readable.mjs +29 -0
  243. package/foundation/doc-compiler/read.d.mts +126 -0
  244. package/foundation/doc-compiler/read.mjs +320 -0
  245. package/foundation/doc-compiler/read.test.mjs +313 -0
  246. package/foundation/doc-compiler/source.d.mts +33 -0
  247. package/foundation/doc-compiler/source.mjs +128 -0
  248. package/foundation/fs/file-protection.d.mts +33 -0
  249. package/foundation/fs/file-protection.mjs +825 -0
  250. package/foundation/fs/file-protection.test.mjs +250 -0
  251. package/foundation/integrations/autolink.d.mts +58 -1
  252. package/foundation/integrations/autolink.mjs +143 -57
  253. package/foundation/integrations/contribution-fixes.d.mts +145 -0
  254. package/foundation/integrations/contribution-fixes.mjs +1284 -0
  255. package/foundation/integrations/contribution-inventory.d.mts +1 -1
  256. package/foundation/integrations/contribution-inventory.mjs +17 -20
  257. package/foundation/integrations/contribution-inventory.test.mjs +67 -27
  258. package/foundation/integrations/integrations.d.mts +3 -0
  259. package/foundation/integrations/integrations.mjs +11 -97
  260. package/foundation/integrations/provider-ledger.test.mjs +275 -0
  261. package/foundation/integrations/provider-resolution.d.mts +152 -0
  262. package/foundation/integrations/provider-resolution.mjs +576 -0
  263. package/foundation/integrations/provider-resolution.test.mjs +369 -0
  264. package/foundation/integrations/theme-descriptor.d.mts +8 -0
  265. package/foundation/integrations/theme-descriptor.mjs +44 -0
  266. package/foundation/integrations/validate-contributions.mjs +104 -10
  267. package/foundation/response/error-codes.d.mts +3 -1
  268. package/foundation/response/error-codes.d.ts +2 -0
  269. package/foundation/response/error-codes.doc.mjs +12 -2
  270. package/foundation/response/error-codes.mjs +7 -1
  271. package/foundation/response/error-codes.test.mjs +55 -11
  272. package/foundation/response/response-types.doc.mjs +1 -1
  273. package/foundation/response/response.doc.mjs +1 -1
  274. package/foundation/text/string-utils.mjs +22 -10
  275. package/package.json +10 -9
  276. package/assets/templates/themes/manifest.json +0 -95
@@ -84,7 +84,7 @@ export const docs = {
84
84
  content: [
85
85
  {
86
86
  type: 'prose',
87
- text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync; add palette outputs to the theme catalog after generation.',
87
+ text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync. Palette outputs live inside the theme directory, which ships as one unit, so there is nothing to register after generation.',
88
88
  },
89
89
  {
90
90
  type: 'code',
@@ -94,7 +94,7 @@ export const docs = {
94
94
  },
95
95
  {
96
96
  type: 'prose',
97
- text: "Edit the generated theme and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`, and list the theme source, request, candidate, and receipt in the catalog entry's `files` array. Add any optional wrapper, refs, icon, or preview modules only when you author them, and list each one too. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.",
97
+ text: 'Edit the generated theme descriptor, source, and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`, a reproducibility receipt. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`. The whole theme directory is copied and packed as one unit, so an optional wrapper, refs, icon, or preview module you add inside it ships with the theme. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source or descriptor fails before a consumer sees it.',
98
98
  },
99
99
  {
100
100
  type: 'code',
@@ -104,7 +104,7 @@ export const docs = {
104
104
  },
105
105
  {
106
106
  type: 'prose',
107
- text: 'The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies every file listed by the selected catalog entry, including nested token modules, and refuses to overwrite existing project files.',
107
+ text: "The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies the selected theme's complete directory, including its typed `.doc.mjs`, nested token modules, and receipts, and refuses to overwrite existing project files.",
108
108
  },
109
109
  ],
110
110
  },
@@ -119,7 +119,7 @@ export const docs = {
119
119
  {
120
120
  type: 'code',
121
121
  lang: 'text',
122
- code: "Kind Metadata suffix type stamp Source file\n──────── ───────────────────────── ───────────── ──────────────────────\nComponent Name.doc.{ts,mjs,js} 'component' Name.tsx (same stem)\nTemplate Name.template.{ts,mjs,js} 'page'/'block' Name.tsx (same stem)\nDoc topic topic.doc.{ts,mjs,js} 'generic' (none — docs are prose)\nCodemod <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme manifest.json entry — <slug>/<entry>.ts",
122
+ code: "Kind Metadata file type stamp Source file\n──────── ───────────────────────── ───────────── ──────────────────────\nComponent Name.doc.mjs 'component' Name.tsx (same stem)\nTemplate Name.doc.mjs 'page'/'block' Name.tsx (same stem)\nDoc topic topic.doc.mjs 'generic' (none — docs are prose)\nCodemod <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme <slug>/nameTheme.doc.mjs 'theme' <slug>/nameTheme.ts (same stem)\n\nReleased .doc.js files, template .doc.ts files, and .template.{ts,mjs,js}\ntemplates still load. A component or topic .doc.ts loads only from a package\nlinked from outside node_modules; installed, it is listed but cannot be read.",
123
123
  },
124
124
  {
125
125
  type: 'prose',
@@ -152,7 +152,7 @@ export const docs = {
152
152
  content: [
153
153
  {
154
154
  type: 'prose',
155
- text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates).",
155
+ text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a strongly typed `.doc.mjs` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.mjs`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates). Released `.doc.js` docs remain readable for compatibility. A `.doc.ts` component doc reads only when the package is linked from outside node_modules, not once it is installed. New authoring uses `.doc.mjs`.",
156
156
  },
157
157
  {
158
158
  type: 'prose',
@@ -161,7 +161,7 @@ export const docs = {
161
161
  {
162
162
  type: 'code',
163
163
  lang: 'typescript',
164
- code: "// AcmeCarousel.doc.ts\nexport default {\n type: 'component',\n name: 'AcmeCarousel',\n description: 'A carousel that cycles through slides.',\n // props, usage, examples, ...\n} satisfies import('@astryxdesign/cli/authoring').ComponentDoc;",
164
+ code: "// AcmeCarousel.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {\n type: 'component',\n name: 'AcmeCarousel',\n displayName: 'Acme Carousel',\n usage: {description: 'A carousel that cycles through slides.'},\n props: [],\n};",
165
165
  },
166
166
  ],
167
167
  },
@@ -171,7 +171,7 @@ export const docs = {
171
171
  content: [
172
172
  {
173
173
  type: 'prose',
174
- text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) as its default export in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`. Do not use the `.doc.{ts,mjs,js}` suffix — that is for component docs and reference docs.",
174
+ text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a strongly typed plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a same-stem `.doc.mjs`, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.doc.mjs`. Released `.template.*` files remain readable for compatibility.",
175
175
  },
176
176
  {
177
177
  type: 'prose',
@@ -180,7 +180,7 @@ export const docs = {
180
180
  {
181
181
  type: 'code',
182
182
  lang: 'typescript',
183
- code: "// AcmeLandingPage.template.ts\nexport default {\n type: 'page',\n // name, description, preview, ...\n};",
183
+ code: "// AcmeLandingPage.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n type: 'page',\n name: 'acme-landing-page',\n displayName: 'Acme Landing Page',\n description: 'A complete product landing page.',\n};",
184
184
  },
185
185
  {
186
186
  type: 'prose',
@@ -194,12 +194,12 @@ export const docs = {
194
194
  content: [
195
195
  {
196
196
  type: 'prose',
197
- text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object with `type: 'generic'` as its default export — not `'component'` (that is for component docs with a same-stem source file). This is the same shape core's own topics use.",
197
+ text: "Point the integration file's `docs` field at a directory of reference docs and every strongly typed `{topic}.doc.mjs` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'` — not `'component'` (that is for component docs with a same-stem source file) — the same shape core's own topics use.",
198
198
  },
199
199
  {
200
200
  type: 'code',
201
201
  lang: 'typescript',
202
- code: "// docs/deploying.doc.ts\nexport default {\n type: 'generic',\n name: 'deploying',\n title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n category: 'guide',\n sections: [\n {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n ],\n};",
202
+ code: "// docs/deploying.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n type: 'generic',\n name: 'deploying',\n title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n category: 'guide',\n sections: [\n {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n ],\n};",
203
203
  },
204
204
  {
205
205
  type: 'prose',
@@ -212,7 +212,7 @@ export const docs = {
212
212
  },
213
213
  {
214
214
  type: 'prose',
215
- text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
215
+ text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. The topic keeps its own title and description; only `replaces` renames it. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
216
216
  },
217
217
  {
218
218
  type: 'list',
@@ -233,38 +233,25 @@ export const docs = {
233
233
  content: [
234
234
  {
235
235
  type: 'prose',
236
- text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`, place the source under one directory per slug, and list it in `themes/manifest.json`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
236
+ text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`. Give each lower-kebab slug its own directory containing a theme source and mandatory same-stem, strongly typed `.doc.mjs`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
237
237
  },
238
238
  {
239
239
  type: 'code',
240
240
  lang: 'text',
241
- code: 'themes/\n manifest.json\n ocean/\n oceanTheme.ts\n palette.config.json\n tokens/\n ocean.palette.ts\n ocean.palette.receipt.json',
241
+ code: 'themes/\n ocean/\n oceanTheme.ts\n oceanTheme.doc.mjs\n palette.config.json\n tokens/\n ocean.palette.ts\n ocean.palette.receipt.json',
242
242
  },
243
243
  {
244
244
  type: 'prose',
245
- text: 'The root catalog `manifest.json` must be `{ "version": 1, "themes": [...] }`. Each entry in the `themes` array requires every field shown below — omitting any one is a hard validation error:',
246
- },
247
- {
248
- type: 'list',
249
- style: 'unordered',
250
- items: [
251
- '`slug` — lowercase kebab-case starting with a letter (e.g. `"ocean"`). Must be unique within the catalog.',
252
- '`displayName` — human-readable label (e.g. `"Ocean"`).',
253
- '`description` — string description of the theme.',
254
- '`maintained` — boolean indicating active maintenance.',
255
- '`entry` — source file relative to `themes/<slug>/` (e.g. `"oceanTheme.ts"`).',
256
- '`exportName` — a valid JS identifier naming the runtime export in the entry file (e.g. `"oceanTheme"`). Astryx parses the source without executing it and rejects missing or type-only exports.',
257
- '`files` — non-empty array of filenames relative to `themes/<slug>/`. Must include the entry file and every local static import the entry source uses. Astryx validates that every listed file exists on disk and that every local import in the entry names a file in this list.',
258
- ],
245
+ text: '`ThemeDoc` owns `name` (the slug), `displayName`, `description`, and `maintained`. The descriptor/source stem supplies the source entry and required named runtime export. Astryx parses the source without executing it, confines every local static import and re-export to the theme directory, copies that complete directory, and rejects missing or type-only exports.',
259
246
  },
260
247
  {
261
248
  type: 'code',
262
- lang: 'json',
263
- code: '{\n "version": 1,\n "themes": [{\n "slug": "ocean",\n "displayName": "Ocean",\n "description": "Ocean theme with OKLCH palettes.",\n "maintained": true,\n "entry": "oceanTheme.ts",\n "exportName": "oceanTheme",\n "files": [\n "oceanTheme.ts",\n "palette.config.json",\n "tokens/ocean.palette.ts",\n "tokens/ocean.palette.receipt.json"\n ]\n }]\n}',
249
+ lang: 'javascript',
250
+ code: "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n type: 'theme',\n name: 'ocean',\n displayName: 'Ocean',\n description: 'Ocean theme.',\n maintained: true,\n};",
264
251
  },
265
252
  {
266
253
  type: 'prose',
267
- text: 'The generated candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output; list it only if you create it.',
254
+ text: 'The generated palette candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output.',
268
255
  },
269
256
  {
270
257
  type: 'prose',
@@ -343,6 +330,19 @@ export const docs = {
343
330
  lang: 'bash',
344
331
  code: '# Preview what would change (dry-run, the default)\nastryx upgrade --from 0.1.0\n\n# Apply the migration\nastryx upgrade --from 0.1.0 --apply',
345
332
  },
333
+ {
334
+ type: 'prose',
335
+ text: 'Core and integration upgrade codemods do not edit existing consumer files that the working tree protects. Protection is VCS-neutral: Astryx reads nested `.gitattributes` rules for `linguist-generated` and `linguist-vendored`, leading `@generated` and `@partially-generated` comments, standard `Code generated … DO NOT EDIT.` comments, `.gitignore`, and `.hgignore` directly from disk. Later attribute rules, explicit false or unset values, and ignore negation keep their normal semantics. Installed dependencies, VCS metadata, paths outside the project, and symbolic links are also protected. Directory or file names such as `dist` and `generated` are not evidence by themselves.',
336
+ },
337
+ {
338
+ type: 'prose',
339
+ text: 'A protected file is transformed only in memory. If it would change, the upgrade applies eligible owned-source edits, runs `hooks.postCodemod` regeneration, and checks the protected file again. A remaining change makes the run incomplete and exits nonzero with `ERR_CODEMOD_PROTECTED`; JSON output lists `modifiedFiles` and `protectedFiles` with every effective declaration. Generated headers may include `Command: <exact command>` so the result can tell a consumer how to regenerate when no hook resolves the output. Dry-run uses the same classification without writing.',
340
+ },
341
+ {
342
+ type: 'code',
343
+ lang: 'text',
344
+ code: '# .gitattributes\ngenerated/** linguist-generated=true\nvendor/** linguist-vendored=true\n\n# A later rule can explicitly return an authored file to normal handling\ngenerated/hand-authored.ts linguist-generated=false',
345
+ },
346
346
  {
347
347
  type: 'prose',
348
348
  text: 'All authoring types are exported from `@astryxdesign/cli/authoring`: `ComponentDoc`, `HookDoc`, and `ReferenceDoc` for docs, `TemplateDoc` for templates, and `AstryxConfig`, `AstryxIntegration`, and `AstryxCodemod` for the project files. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',
@@ -0,0 +1,15 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `astryx docs cli`: every command, API function, output schema, and
5
+ * enum the CLI documents, one section each.
6
+ *
7
+ * Built from the docs whose `namespace` is `cli/commands` or `cli/api`, so it
8
+ * cannot drift from the commands and functions it describes. `astryx doctor`
9
+ * names a CLI doc with no namespace, or one no topic reads.
10
+ */
11
+
12
+ import {buildCliTopic} from '../../foundation/discovery/cli-self-docs.mjs';
13
+
14
+ /** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
15
+ export const docs = await buildCliTopic();
@@ -152,7 +152,7 @@ function App() {
152
152
  },
153
153
  {
154
154
  type: 'prose',
155
- text: 'The copy is editable project source, not a reference back into node_modules. Every file named by the theme catalog comes with it, including nested token or palette modules. A second add refuses to overwrite those files unless you pass `--overwrite`.',
155
+ text: 'The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`.',
156
156
  },
157
157
  ],
158
158
  },
@@ -41,7 +41,7 @@ export default function DateInputDateRange() {
41
41
  max={max}
42
42
  description={description}
43
43
  placeholder="Select a booking date"
44
- nativePicker="never"
44
+ presentation="adaptive-bottom-sheet"
45
45
  value={value}
46
46
  onChange={setValue}
47
47
  />
@@ -0,0 +1,14 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
4
+ export const doc = {
5
+ type: 'block',
6
+ exampleFor: 'Item',
7
+ name: 'Item — Document Tabs',
8
+ displayName: 'Item — Document Tabs',
9
+ description:
10
+ 'Single-row, horizontally scrollable document switcher with compact selected rows, leading file icons, instant reveal-on-hover close actions with reserved geometry, stable separators, and an add control outside the scroll area. Use for editor tabs, workspace tabs, open documents, files, canvases, or panels.',
11
+ isReady: true,
12
+ aspectRatio: 16 / 4,
13
+ componentsUsed: ['Item', 'Divider', 'Icon', 'IconButton', 'Layout'],
14
+ };
@@ -0,0 +1,100 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ import {Fragment} from 'react';
6
+ import * as stylex from '@stylexjs/stylex';
7
+
8
+ import {Divider} from '@astryxdesign/core/Divider';
9
+ import {useContainerReveal} from '@astryxdesign/core/hooks';
10
+ import {Icon} from '@astryxdesign/core/Icon';
11
+ import {IconButton} from '@astryxdesign/core/IconButton';
12
+ import {Item} from '@astryxdesign/core/Item';
13
+ import {HStack} from '@astryxdesign/core/Layout';
14
+ import {mergeProps} from '@astryxdesign/core/utils';
15
+ import {DocumentIcon, PlusIcon, XMarkIcon} from '@heroicons/react/24/outline';
16
+
17
+ const TABS = [
18
+ {name: 'Project brief', isActive: true},
19
+ {name: 'Research notes', isActive: false},
20
+ {name: 'Interaction prototype', isActive: false},
21
+ ];
22
+
23
+ const styles = stylex.create({
24
+ strip: {minWidth: 0, flexShrink: 1, scrollbarWidth: 'none'},
25
+ rule: {height: 16},
26
+ hidden: {visibility: 'hidden'},
27
+ tab: {flexShrink: 1, width: 164, minWidth: 96},
28
+ action: {margin: 'calc(-1 * var(--spacing-1))', transitionProperty: 'none'},
29
+ });
30
+ function DocumentTab({name, isActive}: (typeof TABS)[number]) {
31
+ const {getContainerProps, getContentRevealProps} = useContainerReveal();
32
+ const revealProps = getContentRevealProps({
33
+ forceVisibility: isActive ? 'shown' : undefined,
34
+ isLayoutPreserved: true,
35
+ });
36
+ return (
37
+ <Item
38
+ label={name}
39
+ density="compact"
40
+ isSelected={isActive}
41
+ onClick={() => {}}
42
+ aria-current={isActive ? 'true' : undefined}
43
+ {...getContainerProps()}
44
+ startContent={
45
+ <Icon
46
+ icon={DocumentIcon}
47
+ size="sm"
48
+ color={isActive ? 'primary' : 'secondary'}
49
+ />
50
+ }
51
+ endContent={
52
+ <IconButton
53
+ label={`Close ${name}`}
54
+ variant="ghost"
55
+ size="sm"
56
+ icon={<Icon icon={XMarkIcon} size="sm" />}
57
+ {...mergeProps(revealProps, stylex.props(styles.action))}
58
+ />
59
+ }
60
+ xstyle={styles.tab}
61
+ />
62
+ );
63
+ }
64
+
65
+ export default function ItemDocumentTabs() {
66
+ return (
67
+ <HStack width="100%" maxWidth={600} gap={0.5} vAlign="center">
68
+ <HStack
69
+ role="group"
70
+ aria-label="Open documents"
71
+ vAlign="center"
72
+ paddingInline={2}
73
+ paddingBlock={1}
74
+ isScrollable
75
+ xstyle={styles.strip}>
76
+ {TABS.map((tab, index) => (
77
+ <Fragment key={tab.name}>
78
+ {index > 0 ? (
79
+ <Divider
80
+ orientation="vertical"
81
+ xstyle={[
82
+ styles.rule,
83
+ (TABS[index - 1]?.isActive || tab.isActive) && styles.hidden,
84
+ ]}
85
+ />
86
+ ) : null}
87
+ <DocumentTab {...tab} />
88
+ </Fragment>
89
+ ))}
90
+ </HStack>
91
+ <IconButton
92
+ label="New document"
93
+ tooltip="New document"
94
+ variant="ghost"
95
+ size="sm"
96
+ icon={<Icon icon={PlusIcon} size="sm" color="secondary" />}
97
+ />
98
+ </HStack>
99
+ );
100
+ }
@@ -17,6 +17,7 @@ export default function TimeInputConstrained() {
17
17
  max={'22:00' as never}
18
18
  description="Evening seating: 5 PM – 10 PM"
19
19
  placeholder="Select reservation time"
20
+ presentation="adaptive-bottom-sheet"
20
21
  value={evening as never}
21
22
  onChange={setEvening as never}
22
23
  hasClear
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'butter',
7
+ displayName: 'Butter',
8
+ description:
9
+ 'Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable.',
10
+ maintained: false,
11
+ };
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'chocolate',
7
+ displayName: 'Chocolate',
8
+ description:
9
+ 'Warm chocolate theme for Astryx — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons',
10
+ maintained: false,
11
+ };
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'gothic',
7
+ displayName: 'Gothic',
8
+ description:
9
+ 'Deep blue-grays and a signature display serif. Dramatic and editorial, for surfaces that want to be remembered.',
10
+ maintained: false,
11
+ };
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'matcha',
7
+ displayName: 'Matcha',
8
+ description:
9
+ 'Earthy greens with a calm, organic feel. Naturalistic and grounded, great for wellness or content-first apps.',
10
+ maintained: false,
11
+ };
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'neutral',
7
+ displayName: 'Neutral',
8
+ description:
9
+ 'Restrained warm grays. Minimal and quiet, so the content stays the focus.',
10
+ maintained: true,
11
+ };
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'stone',
7
+ displayName: 'Stone',
8
+ description:
9
+ 'Warm stone and slate, earthy and understated, with just enough character to feel handcrafted.',
10
+ maintained: false,
11
+ };
@@ -0,0 +1,11 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
4
+ export default {
5
+ type: 'theme',
6
+ name: 'y2k',
7
+ displayName: 'Y2K',
8
+ description:
9
+ 'Hot pinks, lime greens, and Poppins. Bubbly, playful, and unmistakably retro.',
10
+ maintained: false,
11
+ };
@@ -12,7 +12,7 @@ export const doc = {
12
12
  type: 'schema',
13
13
  name: 'codemod',
14
14
  displayName: 'Astryx Codemod',
15
- namespace: 'cli',
15
+ namespace: 'authoring',
16
16
  description:
17
17
  'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
18
18
  "plain object with a `type` discriminant: 'code' rewrites source files, " +
@@ -128,7 +128,19 @@ export interface CodemodEntry {
128
128
  /** The result of running a single codemod over one or more files. */
129
129
  export interface CodemodRunResult {
130
130
  filesChanged: number;
131
+ /** Existing owned files changed or previewed by this codemod. */
132
+ changedFiles: string[];
133
+ /** Files actually written; empty during a dry run. */
131
134
  writtenFiles: string[];
135
+ /** Existing files that require the change but are protected. */
136
+ protectedFiles: Array<{
137
+ file: string;
138
+ codemod: string;
139
+ reason: string;
140
+ declaration: string;
141
+ generated: boolean;
142
+ command?: string;
143
+ }>;
132
144
  errors: Array<{file: string; codemod: string; error: string}>;
133
145
  }
134
146
 
@@ -11,7 +11,7 @@ export const doc = {
11
11
  type: 'schema',
12
12
  name: 'config',
13
13
  displayName: 'Astryx Config',
14
- namespace: 'cli',
14
+ namespace: 'authoring',
15
15
  description:
16
16
  'The optional astryx.config.* file at your project root. Declares which ' +
17
17
  'integrations to load, where to route issue links, post-codemod hooks, local ' +
@@ -0,0 +1,11 @@
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 DebugEvent, the record of one CLI run.
6
+ * @input The DebugEvent type beside it (`type.ts`), which `parse.mjs` reads.
7
+ * @output The `debug-event` section of `astryx docs authoring`.
8
+ * @position packages/cli/authoring/debug — schema documentation
9
+ */
10
+ /** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
11
+ export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;