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

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 (206) hide show
  1. package/README.md +86 -72
  2. package/api/build/build.doc.mjs +3 -3
  3. package/api/build/build.test.mjs +14 -3
  4. package/api/build/build.type.d.mts +35 -1
  5. package/api/build/build.type.mjs +24 -3
  6. package/api/build/help/help.d.mts +8 -5
  7. package/api/build/help/help.mjs +56 -6
  8. package/api/component/component.doc.mjs +12 -3
  9. package/api/component/component.mjs +31 -2
  10. package/api/component/component.test.mjs +38 -0
  11. package/api/component/component.type.d.mts +16 -5
  12. package/api/component/component.type.mjs +13 -5
  13. package/api/component/detail/blocks/blocks.d.mts +2 -1
  14. package/api/component/detail/blocks/blocks.mjs +4 -3
  15. package/api/component/list/list.d.mts +0 -5
  16. package/api/component/list/list.mjs +37 -9
  17. package/api/discover/discover.doc.mjs +1 -1
  18. package/api/gap-report/gap-report.doc.mjs +7 -4
  19. package/api/init/init.doc.mjs +4 -0
  20. package/api/init/init.test.mjs +41 -1
  21. package/api/init/remove/remove.mjs +1 -1
  22. package/api/init/run/run.mjs +20 -10
  23. package/api/integration/add-contribution.component-names.test.mjs +120 -0
  24. package/api/integration/add-contribution.mjs +11 -0
  25. package/api/integration/add-contribution.test.mjs +80 -0
  26. package/api/integration/integrationAdd.doc.mjs +7 -4
  27. package/api/integration/integrationAddComponent.doc.mjs +1 -1
  28. package/api/integration/validate-integration.mjs +2 -0
  29. package/api/integration/validate-integration.test.mjs +91 -0
  30. package/api/integration/validateIntegration.doc.mjs +1 -1
  31. package/api/json/envelope-types.test.mjs +76 -0
  32. package/api/json/parseResponse.doc.mjs +2 -2
  33. package/api/layout/expand/expand.mjs +7 -5
  34. package/api/layout/expand/expand.path-safety.test.mjs +53 -0
  35. package/api/layout/grammar/grammar.mjs +2 -1
  36. package/api/layout/layoutExpand.doc.mjs +1 -1
  37. package/api/search/search-return-type.test.mjs +54 -0
  38. package/api/search/search.d.mts +2 -9
  39. package/api/search/search.doc.mjs +5 -1
  40. package/api/search/search.mjs +10 -3
  41. package/api/search/search.test.mjs +34 -0
  42. package/api/swizzle/copy/copy.mjs +28 -11
  43. package/api/swizzle/swizzle.doc.mjs +1 -1
  44. package/api/template/copy/copy.mjs +17 -23
  45. package/api/template/copy/copy.test.mjs +17 -0
  46. package/api/template/template.doc.mjs +2 -1
  47. package/api/theme/add/add.binary.test.mjs +91 -0
  48. package/api/theme/add/add.mjs +20 -3
  49. package/api/theme/add/add.staging.test.mjs +66 -0
  50. package/api/theme/build/build.mjs +114 -37
  51. package/api/theme/build/build.public-component-vars.test.mjs +1 -1
  52. package/api/theme/build/build.receipt-doc.test.mjs +111 -0
  53. package/api/theme/build/font-warning.mjs +3 -3
  54. package/api/theme/build/font-warning.test.mjs +5 -2
  55. package/api/theme/palette/generate/generate.mjs +7 -2
  56. package/api/theme/palette/generate/generate.test.mjs +96 -0
  57. package/api/theme/palette/generate/generator.mjs +8 -1
  58. package/api/theme/palette/generate/generator.test.mjs +10 -0
  59. package/api/theme/template/template.mjs +11 -2
  60. package/api/theme/template/template.test.mjs +15 -0
  61. package/api/theme/themeBuild.doc.mjs +7 -4
  62. package/api/theme/themeTemplate.doc.mjs +4 -1
  63. package/api/upgrade/_adapter.mjs +27 -4
  64. package/api/upgrade/list/list.mjs +2 -1
  65. package/api/upgrade/list/list.test.mjs +73 -0
  66. package/api/upgrade/status/status.mjs +2 -2
  67. package/api/upgrade/upgrade.doc.mjs +2 -1
  68. package/api/upgrade/upgrade.type.d.mts +4 -0
  69. package/api/upgrade/upgrade.type.mjs +1 -0
  70. package/assets/codemods/term-log.mjs +32 -8
  71. package/assets/codemods/term-log.test.mjs +19 -1
  72. package/assets/codemods/transform-prop.mjs +109 -0
  73. package/assets/codemods/transform-prop.test.mjs +95 -0
  74. package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs +86 -165
  75. package/assets/codemods/transforms/v0.0.14/rename-status-variants.mjs +72 -210
  76. package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs +83 -115
  77. package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs +57 -186
  78. package/assets/codemods/transforms/v0.6.0/__tests__/next-codemods.test.mjs +47 -0
  79. package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs +57 -10
  80. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.doc.mjs +14 -0
  81. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaInlineRail.tsx +61 -0
  82. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.doc.mjs +14 -0
  83. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaOverscrollChaining.tsx +126 -0
  84. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.doc.mjs +15 -0
  85. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaShowcase.tsx +86 -0
  86. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.doc.mjs +14 -0
  87. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyGroupHeaders.tsx +99 -0
  88. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.doc.mjs +14 -0
  89. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaStickyPassthrough.tsx +122 -0
  90. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.doc.mjs +14 -0
  91. package/assets/templates/blocks/components/ScrollableArea/ScrollableAreaTwoAxisBoard.tsx +95 -0
  92. package/assets/templates/pages/table-tree/page.tsx +1704 -0
  93. package/assets/templates/pages/table-tree/template.doc.mjs +12 -0
  94. package/authoring/config/config.doc.mjs +1 -1
  95. package/authoring/config/debug-composition.test.mjs +92 -0
  96. package/authoring/config/type.ts +15 -3
  97. package/clients/cli/command-load-failure.test.mjs +83 -0
  98. package/clients/cli/commands/blog.mjs +23 -8
  99. package/clients/cli/commands/blog.test.mjs +42 -1
  100. package/clients/cli/commands/build-theme.ascii-output.test.mjs +161 -0
  101. package/clients/cli/commands/build-theme.flag-docs.test.mjs +110 -0
  102. package/clients/cli/commands/build-theme.mjs +5 -5
  103. package/clients/cli/commands/build-theme.path-safety.test.mjs +86 -1
  104. package/clients/cli/commands/build-theme.variants.test.mjs +76 -0
  105. package/clients/cli/commands/build.doc.mjs +4 -1
  106. package/clients/cli/commands/build.exit-codes-doc.test.mjs +50 -0
  107. package/clients/cli/commands/build.mjs +32 -47
  108. package/clients/cli/commands/build.playbook.test.mjs +75 -0
  109. package/clients/cli/commands/build.text-fields.test.mjs +40 -0
  110. package/clients/cli/commands/component/index.mjs +2 -7
  111. package/clients/cli/commands/component-package.test.mjs +46 -0
  112. package/clients/cli/commands/component-resolution.test.mjs +21 -0
  113. package/clients/cli/commands/component.test.mjs +19 -0
  114. package/clients/cli/commands/detail-levels.test.mjs +2 -2
  115. package/clients/cli/commands/discover.broken-integration.test.mjs +48 -0
  116. package/clients/cli/commands/discover.components-flag.test.mjs +97 -0
  117. package/clients/cli/commands/discover.doc.mjs +4 -2
  118. package/clients/cli/commands/discover.mjs +3 -3
  119. package/clients/cli/commands/discover.text-projection.test.mjs +103 -0
  120. package/clients/cli/commands/doctor-integration.package-json.test.mjs +53 -0
  121. package/clients/cli/commands/doctor.mjs +6 -16
  122. package/clients/cli/commands/doctor.test.mjs +42 -0
  123. package/clients/cli/commands/gap-report.doc.mjs +16 -5
  124. package/clients/cli/commands/gap-report.test.mjs +72 -0
  125. package/clients/cli/commands/hook/index.mjs +7 -17
  126. package/clients/cli/commands/hook.text-projection.test.mjs +45 -0
  127. package/clients/cli/commands/init.doc.mjs +19 -8
  128. package/clients/cli/commands/init.flag-help.test.mjs +153 -0
  129. package/clients/cli/commands/integration-add.controls.test.mjs +132 -0
  130. package/clients/cli/commands/integration-add.doc.mjs +21 -5
  131. package/clients/cli/commands/interactive-guard.test.mjs +101 -24
  132. package/clients/cli/commands/json-contract.test.mjs +33 -0
  133. package/clients/cli/commands/layout-check.doc.mjs +14 -3
  134. package/clients/cli/commands/layout-expand.doc.mjs +21 -4
  135. package/clients/cli/commands/layout.doc.mjs +2 -2
  136. package/clients/cli/commands/layout.mjs +21 -9
  137. package/clients/cli/commands/layout.path-help.test.mjs +33 -0
  138. package/clients/cli/commands/layout.stdin-cap.test.mjs +47 -0
  139. package/clients/cli/commands/layout.text-fields.test.mjs +39 -0
  140. package/clients/cli/commands/no-prompt-wording.test.mjs +94 -0
  141. package/clients/cli/commands/search.doc.mjs +6 -3
  142. package/clients/cli/commands/search.mjs +17 -7
  143. package/clients/cli/commands/search.test.mjs +75 -0
  144. package/clients/cli/commands/swizzle.doc.mjs +2 -1
  145. package/clients/cli/commands/swizzle.path-safety.test.mjs +42 -0
  146. package/clients/cli/commands/template.doc.mjs +28 -6
  147. package/clients/cli/commands/template.flag-help.test.mjs +117 -0
  148. package/clients/cli/commands/template.path-help.test.mjs +40 -0
  149. package/clients/cli/commands/theme-add.doc.mjs +2 -1
  150. package/clients/cli/commands/theme-build.doc.mjs +7 -6
  151. package/clients/cli/commands/theme-palette-generate.test.mjs +19 -0
  152. package/clients/cli/commands/theme-template.behavior.test.mjs +12 -0
  153. package/clients/cli/commands/theme-template.doc.mjs +1 -1
  154. package/clients/cli/commands/upgrade.ascii-output.test.mjs +87 -0
  155. package/clients/cli/commands/upgrade.doc.mjs +17 -6
  156. package/clients/cli/commands/upgrade.flag-help.test.mjs +188 -0
  157. package/clients/cli/commands/upgrade.hook-output.test.mjs +88 -0
  158. package/clients/cli/index.mjs +13 -30
  159. package/clients/cli/latest-version-env.test.mjs +50 -0
  160. package/clients/cli/lib/cli-error.test.mjs +7 -0
  161. package/clients/cli/lib/component-format.mjs +9 -9
  162. package/clients/cli/lib/component-format.test.mjs +1 -1
  163. package/clients/cli/lib/define-command.mjs +32 -6
  164. package/clients/cli/lib/doc-text-ascii.test.mjs +82 -0
  165. package/clients/cli/lib/exit-codes.test.mjs +97 -0
  166. package/clients/cli/lib/hook-format.mjs +5 -5
  167. package/clients/cli/lib/json-shim.mjs +38 -2
  168. package/clients/cli/lib/json-shim.test.mjs +83 -0
  169. package/clients/cli/lib/manifest.d.ts +2 -0
  170. package/clients/cli/lib/manifest.mjs +22 -0
  171. package/clients/cli/lib/manifest.test.mjs +17 -0
  172. package/foundation/agent-docs/agent-docs.d.mts +4 -0
  173. package/foundation/agent-docs/agent-docs.mjs +69 -3
  174. package/foundation/agent-docs/agent-docs.path-safety.test.mjs +266 -4
  175. package/foundation/config/integration-debug.test.mjs +28 -3
  176. package/foundation/config/project.mjs +123 -9
  177. package/foundation/config/project.test.mjs +126 -0
  178. package/foundation/discovery/template-adapter.d.mts +14 -5
  179. package/foundation/discovery/template-adapter.fixture-refs.test.mjs +248 -0
  180. package/foundation/discovery/template-adapter.integration-isolation.test.mjs +94 -0
  181. package/foundation/discovery/template-adapter.mjs +292 -25
  182. package/foundation/discovery/theming-targets.test.mjs +4 -0
  183. package/foundation/fs/module-loader.d.mts +1 -0
  184. package/foundation/fs/module-loader.mjs +50 -1
  185. package/foundation/fs/module-loader.stdout.test.mjs +332 -0
  186. package/foundation/fs/path-safety.d.mts +3 -2
  187. package/foundation/fs/path-safety.mjs +49 -19
  188. package/foundation/fs/path-safety.test.mjs +50 -0
  189. package/foundation/fs/publish-file-hardlink-unavailable.test.mjs +129 -94
  190. package/foundation/integrations/autolink.mjs +6 -1
  191. package/foundation/response/base.d.ts +8 -4
  192. package/foundation/response/error-codes.doc.mjs +1 -2
  193. package/foundation/response/error-codes.mjs +1 -1
  194. package/foundation/response/error-codes.test.mjs +83 -0
  195. package/foundation/response/json-contract.test.mjs +11 -0
  196. package/foundation/response/json.d.mts +4 -2
  197. package/foundation/response/json.mjs +8 -10
  198. package/foundation/response/response-types.doc.mjs +10 -10
  199. package/foundation/response/response-types.doc.test.mjs +158 -0
  200. package/foundation/xle/expand.d.mts +2 -0
  201. package/foundation/xle/expand.mjs +3 -2
  202. package/foundation/xle/expand.test.mjs +54 -0
  203. package/package.json +9 -9
  204. package/clients/cli/lib/update-check.mjs +0 -83
  205. package/clients/cli/lib/update-check.test.mjs +0 -137
  206. package/clients/cli/update-hint-commands.test.mjs +0 -54
@@ -0,0 +1,117 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `astryx template` documents which of its flags win when they are
5
+ * combined, and behaves as documented. Option text is read from the generated
6
+ * manifest, the same strings `--help` prints.
7
+ */
8
+
9
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
+ import * as fs from 'node:fs';
11
+ import * as os from 'node:os';
12
+ import * as path from 'node:path';
13
+ import {runCli} from '../../../test-utils/run-cli.mjs';
14
+
15
+ const SLOW = 30_000;
16
+
17
+ /** @type {string} */
18
+ let tmpDir;
19
+
20
+ beforeEach(() => {
21
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-flags-'));
22
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
23
+ });
24
+
25
+ afterEach(() => {
26
+ fs.rmSync(tmpDir, {recursive: true, force: true});
27
+ });
28
+
29
+ /** @param {string} rel */
30
+ const exists = rel => fs.existsSync(path.join(tmpDir, rel));
31
+
32
+ /** Files in the project, ignoring package.json. */
33
+ const written = () => fs.readdirSync(tmpDir).filter(f => f !== 'package.json');
34
+
35
+ /**
36
+ * template's option descriptions from the manifest, keyed by long flag.
37
+ * @returns {Promise<Record<string, string>>}
38
+ */
39
+ async function templateOptions() {
40
+ const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
41
+ const template = JSON.parse(stdout).data.commands.find(
42
+ (/** @type {{name: string}} */ c) => c.name === 'template',
43
+ );
44
+ return Object.fromEntries(
45
+ template.options.map((/** @type {{flag: string, description: string}} */ o) => [
46
+ o.flag.match(/--[a-z-]+/)?.[0],
47
+ o.description,
48
+ ]),
49
+ );
50
+ }
51
+
52
+ /** @param {string[]} args */
53
+ async function templateJson(args) {
54
+ const result = await runCli(['--json', 'template', ...args], tmpDir);
55
+ return {status: result.status, envelope: JSON.parse(result.stdout)};
56
+ }
57
+
58
+ describe('astryx template flag precedence', () => {
59
+ it('--list: help says <name>, <path>, --skeleton and --overwrite are ignored, and they are', async () => {
60
+ const help = (await templateOptions())['--list'];
61
+ for (const ignored of ['<name>', '<path>', '--skeleton', '--overwrite']) {
62
+ expect(help).toContain(ignored);
63
+ }
64
+ expect(help).toMatch(/are ignored/);
65
+
66
+ const {status, envelope} = await templateJson([
67
+ 'dashboard',
68
+ './src/page.tsx',
69
+ '--list',
70
+ '--skeleton',
71
+ '--overwrite',
72
+ ]);
73
+ expect(status).toBe(0);
74
+ expect(envelope.type).toBe('template.list');
75
+ expect(written()).toEqual([]);
76
+ }, SLOW);
77
+
78
+ it('--skeleton: help says it needs <name> and writes nothing, and it does', async () => {
79
+ const help = (await templateOptions())['--skeleton'];
80
+ expect(help).toMatch(/Needs <name>/);
81
+ expect(help).toMatch(/writes nothing, so <path> and --overwrite are ignored/);
82
+ expect(help).toMatch(/--list and --cdn take precedence/);
83
+
84
+ const shown = await templateJson(['dashboard', './src/page.tsx', '--skeleton', '--overwrite']);
85
+ expect(shown.status).toBe(0);
86
+ expect(shown.envelope.type).toBe('template.skeleton');
87
+ expect(written()).toEqual([]);
88
+
89
+ const nameless = await templateJson(['--skeleton']);
90
+ expect(nameless.status).toBe(1);
91
+ expect(nameless.envelope.code).toBe('ERR_UNKNOWN_TEMPLATE');
92
+ }, SLOW);
93
+
94
+ it('--cdn: help says it overrides everything and where the page goes, and the CLI does that', async () => {
95
+ const help = (await templateOptions())['--cdn'];
96
+ for (const ignored of ['<name>', '--list', '--skeleton', '--type', '--package']) {
97
+ expect(help).toContain(ignored);
98
+ }
99
+ expect(help).toMatch(/--cdn value, else to <path>, else cdn\.template\.html/);
100
+ expect(help).toMatch(/always the file itself/);
101
+ expect(help).toMatch(/value right after --cdn/);
102
+
103
+ const everything = await templateJson(['dashboard', '--list', '--skeleton', '--type', 'bogus', '--cdn']);
104
+ expect(everything.envelope.type).toBe('template.cdn');
105
+ expect(everything.envelope.data.path).toBe('cdn.template.html');
106
+
107
+ // A bare --cdn writes to <path>, and a path with no extension is still the file.
108
+ const positional = await templateJson(['dashboard', 'demo', '--cdn']);
109
+ expect(positional.envelope.data.path).toBe('demo');
110
+ expect(fs.statSync(path.join(tmpDir, 'demo')).isFile()).toBe(true);
111
+
112
+ // The word after --cdn is its value, not the template name.
113
+ const value = await templateJson(['--cdn', 'dashboard']);
114
+ expect(value.envelope.data.path).toBe('dashboard');
115
+ expect(exists('dashboard')).toBe(true);
116
+ }, SLOW);
117
+ });
@@ -0,0 +1,40 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `template <name> <path>` decides by extension whether <path> is the
5
+ * file to write or a directory to write into. Help and the manifest say so,
6
+ * and every extension they list is one the resolver treats as a file.
7
+ */
8
+
9
+ import {describe, it, expect} from 'vitest';
10
+ import {runCli} from '../../../test-utils/run-cli.mjs';
11
+ import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
12
+
13
+ const SLOW = 30_000;
14
+
15
+ /** @param {string} text */
16
+ const listedExtensions = text =>
17
+ [...(text.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)].map(m => m[0]);
18
+
19
+ describe('template path resolution is documented', () => {
20
+ it('help explains the file-or-directory rule and the default file names', async () => {
21
+ const {status, stdout} = await runCli(['template', '--help']);
22
+ expect(status).toBe(0);
23
+ expect(stdout).toMatch(/Arguments:/);
24
+ expect(stdout).toContain('page.tsx');
25
+ expect(stdout).toMatch(/block's own file name/);
26
+ }, SLOW);
27
+
28
+ it('the manifest carries the same description, and its extensions are the resolver\'s', async () => {
29
+ const {stdout} = await runCli(['manifest', '--json']);
30
+ const {data} = JSON.parse(stdout);
31
+ const template = data.commands.find((/** @type {any} */ c) => c.name === 'template');
32
+ const pathArg = template.arguments.find((/** @type {any} */ a) => a.name === 'path');
33
+ expect(pathArg.description).toContain('page.tsx');
34
+
35
+ const exts = listedExtensions(pathArg.description);
36
+ expect(exts.length).toBeGreaterThan(0);
37
+ for (const ext of exts) expect(isFilePathArg(`out/page${ext}`)).toBe(true);
38
+ expect(isFilePathArg('out/page')).toBe(false);
39
+ }, SLOW);
40
+ });
@@ -28,7 +28,8 @@ export const doc = {
28
28
  {
29
29
  flag: '-f, --overwrite',
30
30
  param: 'options.overwrite',
31
- description: 'Overwrite existing files without prompting',
31
+ description:
32
+ 'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
32
33
  },
33
34
  {flag: '--list', description: 'List available themes'},
34
35
  {
@@ -28,34 +28,35 @@ export const doc = {
28
28
  {
29
29
  flag: '--family',
30
30
  description:
31
- 'Build the selected extension family into one keyed CSS, JS, and declaration set',
31
+ 'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
32
32
  },
33
33
  {
34
34
  flag: '--family-key <key>',
35
35
  description:
36
- 'Lower-kebab filename stem required with --family; must differ from every member name',
36
+ 'Lower-kebab filename stem required with --family and refused without it; must differ from every member name (ERR_THEME_INVALID)',
37
37
  },
38
38
  {
39
39
  flag: '-o, --out <path>',
40
40
  param: 'options.out',
41
- description: 'Output CSS file path (single theme only)',
41
+ description:
42
+ 'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
42
43
  },
43
44
  {
44
45
  flag: '--icons-specifier <specifier>',
45
46
  param: 'options.iconsSpecifier',
46
47
  description:
47
- 'Override the icon-registry import in the generated JS module (for example, ./icons.mjs)',
48
+ "Override the icon-registry import in the generated JS module, for example ./icons.mjs (default: the specifier in the theme source's own import). With --family it applies to every member's icon import",
48
49
  },
49
50
  {
50
51
  flag: '-w, --watch',
51
52
  description:
52
- 'Rebuild automatically when a theme file changes (Ctrl-C to stop)',
53
+ 'Rebuild automatically when a theme file changes (Ctrl-C to stop). Refused with --check, --family, or --json (ERR_THEME_INVALID)',
53
54
  },
54
55
  {
55
56
  flag: '-c, --check',
56
57
  param: 'options.check',
57
58
  description:
58
- 'Verify the committed outputs match the source without writing; exit non-zero if stale',
59
+ 'Verify the committed outputs match the source without writing; exit non-zero if stale. Composes with --family and several files; refused with --watch (ERR_THEME_INVALID)',
59
60
  },
60
61
  ],
61
62
  examples: [
@@ -132,4 +132,23 @@ describe('astryx theme palette generate', () => {
132
132
  code: 'ERR_PALETTE_GENERATION',
133
133
  });
134
134
  });
135
+
136
+ it('returns ERR_WRITE_FAILED for an output path it cannot use', async () => {
137
+ fs.writeFileSync(path.join(temporaryDirectory, 'blocker'), '');
138
+ const {status, stdout} = await runCli(
139
+ [
140
+ '--json',
141
+ 'theme',
142
+ 'palette',
143
+ 'generate',
144
+ 'palette.config.json',
145
+ '--out',
146
+ 'blocker/ocean.palette.ts',
147
+ ],
148
+ {cwd: temporaryDirectory},
149
+ );
150
+
151
+ expect(status).toBe(1);
152
+ expect(JSON.parse(stdout)).toMatchObject({code: 'ERR_WRITE_FAILED'});
153
+ });
135
154
  });
@@ -82,4 +82,16 @@ describe('astryx theme template', () => {
82
82
  expect(stderr).toMatch(/outside the project root/);
83
83
  expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
84
84
  });
85
+
86
+ it('fails a write with ERR_WRITE_FAILED under --json', async () => {
87
+ fs.writeFileSync(path.join(tmpDir, 'blocker'), '');
88
+
89
+ const {status, stdout} = await runCli(
90
+ ['--json', 'theme', 'template', 'blocker/theme.ts'],
91
+ {cwd: tmpDir},
92
+ );
93
+
94
+ expect(status).toBe(1);
95
+ expect(JSON.parse(stdout).code).toBe('ERR_WRITE_FAILED');
96
+ });
85
97
  });
@@ -36,7 +36,7 @@ export const doc = {
36
36
  ],
37
37
  exitCodes: [
38
38
  {code: 0, when: 'success, including when an existing file was left untouched'},
39
- {code: 1, when: 'the target path escapes the project'},
39
+ {code: 1, when: 'the target path escapes the project, or the file cannot be written'},
40
40
  ],
41
41
  related: ['theme add', 'theme list', 'theme build'],
42
42
  };
@@ -0,0 +1,87 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `astryx upgrade` human output is plain ASCII on every path: the codemod
5
+ * list, up to date, an empty range, a dry run, and an apply that runs a
6
+ * post-codemod hook and refreshes the agent docs.
7
+ */
8
+
9
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
+ import * as fs from 'node:fs';
11
+ import * as path from 'node:path';
12
+ import {runCli} from '../../../test-utils/run-cli.mjs';
13
+ import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';
14
+
15
+ const NON_ASCII = /[\u0080-\uFFFF]/;
16
+
17
+ let tmpDir;
18
+
19
+ /** @param {string} rel @param {string} body */
20
+ function write(rel, body) {
21
+ const file = path.join(tmpDir, rel);
22
+ fs.mkdirSync(path.dirname(file), {recursive: true});
23
+ fs.writeFileSync(file, body);
24
+ }
25
+
26
+ /**
27
+ * Output lines (stdout and stderr) that contain a non-ASCII character.
28
+ * @param {string[]} args
29
+ */
30
+ async function nonAsciiLines(args) {
31
+ const r = await runCli(args, {cwd: tmpDir});
32
+ expect(r.status).toBe(0);
33
+ return `${r.stdout}\n${r.stderr}`
34
+ .split('\n')
35
+ .filter(line => NON_ASCII.test(line));
36
+ }
37
+
38
+ beforeEach(() => {
39
+ // Repo-local so the config module can be imported under Vitest.
40
+ tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-upgrade-ascii-'));
41
+ write('package.json', JSON.stringify({name: 'consumer', private: true}));
42
+ write(
43
+ 'node_modules/@astryxdesign/core/package.json',
44
+ JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
45
+ );
46
+ write(
47
+ 'src/panel.tsx',
48
+ "import {useResizable} from '@astryxdesign/core';\n" +
49
+ 'export const usePanel = () => useResizable({defaultSize: 250, minSizePx: 200});\n',
50
+ );
51
+ });
52
+
53
+ afterEach(() => {
54
+ fs.rmSync(tmpDir, {recursive: true, force: true});
55
+ });
56
+
57
+ describe('upgrade human output is ASCII', () => {
58
+ it('lists codemods', async () => {
59
+ expect(await nonAsciiLines(['upgrade', '--list'])).toEqual([]);
60
+ });
61
+
62
+ it('reports up to date and a missing agent-docs block', async () => {
63
+ expect(await nonAsciiLines(['upgrade', '--from', '0.6.0'])).toEqual([]);
64
+ });
65
+
66
+ it('reports a range with no codemods', async () => {
67
+ expect(
68
+ await nonAsciiLines(['upgrade', '--from', '0.6.0', '--force']),
69
+ ).toEqual([]);
70
+ });
71
+
72
+ it('previews and applies codemods, runs a hook, and refreshes agent docs', async () => {
73
+ write(
74
+ 'astryx.config.mjs',
75
+ `export default {hooks: {postCodemod: [{name: 'noop', buildCommand: () => ({command: ${JSON.stringify(process.execPath)}, args: ['-e', '0']})}]}};\n`,
76
+ );
77
+ write('AGENTS.md', `# Agents\n\n${generateCompressedIndex('0.5.0')}\n`);
78
+
79
+ expect(await nonAsciiLines(['upgrade', '--from', '0.5.0'])).toEqual([]);
80
+ expect(
81
+ await nonAsciiLines(['upgrade', '--from', '0.5.0', '--apply']),
82
+ ).toEqual([]);
83
+ expect(fs.readFileSync(path.join(tmpDir, 'src/panel.tsx'), 'utf8')).toContain(
84
+ 'minSize: 200',
85
+ );
86
+ });
87
+ });
@@ -19,6 +19,7 @@ export const doc = {
19
19
  'running the registered codemods, and refreshes the fully rendered managed ' +
20
20
  'agent-docs block when Core or configured integration guidance changes. ' +
21
21
  'Dry-run by default. --apply writes codemod and receipt changes, runs hooks, then refreshes agent docs. ' +
22
+ 'Anything a post-codemod hook prints goes to stderr, so stdout carries only the result. ' +
22
23
  'ShadCN-copied compositions are checked automatically during a normal upgrade, or alone with --registry.',
23
24
  fn: 'upgrade',
24
25
  options: [
@@ -26,7 +27,8 @@ export const doc = {
26
27
  flag: '--from <version>',
27
28
  param: 'options.from',
28
29
  description:
29
- 'Previous version before the dependency upgrade; required unless --list or --registry is set',
30
+ 'Previous version before the dependency upgrade; required unless --list or --registry is set. ' +
31
+ 'The target is the installed @astryxdesign/core version, or legacy @xds/core when @astryxdesign/core is not installed',
30
32
  },
31
33
  {
32
34
  flag: '--apply',
@@ -44,7 +46,9 @@ export const doc = {
44
46
  {
45
47
  flag: '--codemod <name>',
46
48
  param: 'options.codemod',
47
- description: 'Run a specific transform only',
49
+ description:
50
+ 'Run only the named codemod. Optional codemods run only when named here; a normal run skips them. ' +
51
+ 'Also skips the check of ShadCN-copied compositions. An unknown name exits 1 with ERR_UNKNOWN_CODEMOD when the version range has codemods',
48
52
  },
49
53
  {
50
54
  flag: '--skip-codemod <name...>',
@@ -68,20 +72,23 @@ export const doc = {
68
72
  {
69
73
  flag: '--install-deps',
70
74
  param: 'options.installDeps',
71
- description: 'Auto-install jscodeshift without prompting',
75
+ description:
76
+ 'Install jscodeshift when it is missing. Without it, a missing jscodeshift fails the command with ERR_DEP_MISSING',
72
77
  default: false,
73
78
  },
74
79
  {
75
80
  flag: '--registry',
76
81
  param: 'options.registry',
77
82
  description:
78
- 'Only reconcile ShadCN-copied compositions; --from is not required',
83
+ 'Only reconcile ShadCN-copied compositions; --from is not required. ' +
84
+ 'Combining it with --list, --from, --force, --codemod, --skip-codemod, --integration or --install-deps exits 1 with ERR_INVALID_ARGUMENT',
79
85
  default: false,
80
86
  },
81
87
  {
82
88
  flag: '--list',
83
89
  param: 'options.list',
84
- description: 'List available codemods',
90
+ description:
91
+ 'List available codemods and do nothing else. Every other flag is ignored, except --registry, which is refused (exit 1)',
85
92
  default: false,
86
93
  },
87
94
  ],
@@ -97,7 +104,11 @@ export const doc = {
97
104
  {code: 0, when: 'success (including dry-run previews)'},
98
105
  {
99
106
  code: 1,
100
- when: 'missing or invalid --from, a --path escape, an unknown codemod, a codemod failure, or unresolved registry items',
107
+ when:
108
+ 'missing or invalid --from, --registry with --list or a migration flag, a --path escape, ' +
109
+ 'no installed @astryxdesign/core (or legacy @xds/core), jscodeshift missing and not installed by --install-deps, ' +
110
+ 'an astryx.config that fails validation and that no pending config codemod repairs, ' +
111
+ 'an unknown codemod, a codemod or post-codemod hook failure, or unresolved registry items',
101
112
  },
102
113
  ],
103
114
  related: ['init', 'doctor'],
@@ -0,0 +1,188 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `astryx upgrade` documents how its flags interact and when it exits 1,
5
+ * and behaves as documented. Option text is read from the generated manifest
6
+ * (the same strings `--help` prints); exit codes from the CommandDoc.
7
+ */
8
+
9
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
+ import * as fs from 'node:fs';
11
+ import * as os from 'node:os';
12
+ import * as path from 'node:path';
13
+ import {runCli} from '../../../test-utils/run-cli.mjs';
14
+ import {doc as upgradeDoc} from './upgrade.doc.mjs';
15
+
16
+ const SLOW = 30_000;
17
+
18
+ /** @type {string} */
19
+ let tmpDir;
20
+
21
+ beforeEach(() => {
22
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-upgrade-flags-'));
23
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
24
+ fs.mkdirSync(path.join(tmpDir, 'src'));
25
+ fs.writeFileSync(path.join(tmpDir, 'src', 'index.ts'), 'const foo = 1;\n');
26
+ });
27
+
28
+ afterEach(() => {
29
+ fs.rmSync(tmpDir, {recursive: true, force: true});
30
+ });
31
+
32
+ /** @param {string} name @param {string} version */
33
+ function installPackage(name, version) {
34
+ const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
35
+ fs.mkdirSync(dir, {recursive: true});
36
+ fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name, version}));
37
+ }
38
+
39
+ /** @param {string} rel @param {string} body */
40
+ function write(rel, body) {
41
+ fs.mkdirSync(path.dirname(path.join(tmpDir, rel)), {recursive: true});
42
+ fs.writeFileSync(path.join(tmpDir, rel), body);
43
+ }
44
+
45
+ /**
46
+ * upgrade's option descriptions from the manifest, keyed by long flag.
47
+ * @returns {Promise<Record<string, string>>}
48
+ */
49
+ async function upgradeOptions() {
50
+ const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
51
+ const upgrade = JSON.parse(stdout).data.commands.find(
52
+ (/** @type {{name: string}} */ c) => c.name === 'upgrade',
53
+ );
54
+ return Object.fromEntries(
55
+ upgrade.options.map((/** @type {{flag: string, description: string}} */ o) => [
56
+ o.flag.match(/--[a-z-]+/)?.[0],
57
+ o.description,
58
+ ]),
59
+ );
60
+ }
61
+
62
+ /** @param {string[]} args */
63
+ async function upgradeJson(args) {
64
+ const result = await runCli(['--json', 'upgrade', ...args], tmpDir);
65
+ return {status: result.status, envelope: JSON.parse(result.stdout)};
66
+ }
67
+
68
+ const exit1 = () => upgradeDoc.exitCodes?.find(e => e.code === 1)?.when ?? '';
69
+
70
+ const MIGRATION_FLAGS = [
71
+ ['--from', '0.5.0'],
72
+ ['--force'],
73
+ ['--codemod', 'x'],
74
+ ['--skip-codemod', 'x'],
75
+ ['--integration', 'x'],
76
+ ['--install-deps'],
77
+ ];
78
+
79
+ describe('astryx upgrade flag interactions', () => {
80
+ it('--list: help says it ignores every other flag but --registry, and it does', async () => {
81
+ const options = await upgradeOptions();
82
+ expect(options['--list']).toMatch(/Every other flag is ignored, except --registry/);
83
+
84
+ installPackage('@astryxdesign/core', '0.6.0');
85
+ const listed = await upgradeJson([
86
+ '--list',
87
+ '--from',
88
+ 'bogus',
89
+ '--codemod',
90
+ 'bogus',
91
+ '--apply',
92
+ '--path',
93
+ '../outside',
94
+ ]);
95
+ expect(listed.status).toBe(0);
96
+ expect(listed.envelope.type).toBe('upgrade.list');
97
+
98
+ const refused = await upgradeJson(['--list', '--registry']);
99
+ expect(refused.status).toBe(1);
100
+ expect(refused.envelope.code).toBe('ERR_INVALID_ARGUMENT');
101
+ }, SLOW);
102
+
103
+ it('--registry: help names every flag it refuses, and each exits 1', async () => {
104
+ const options = await upgradeOptions();
105
+ for (const [flag] of MIGRATION_FLAGS) expect(options['--registry']).toContain(flag);
106
+ expect(options['--registry']).toContain('--list');
107
+ expect(options['--registry']).toContain('ERR_INVALID_ARGUMENT');
108
+
109
+ for (const flag of MIGRATION_FLAGS) {
110
+ const {status, envelope} = await upgradeJson(['--registry', ...flag]);
111
+ expect(status, flag[0]).toBe(1);
112
+ expect(envelope.code, flag[0]).toBe('ERR_INVALID_ARGUMENT');
113
+ }
114
+ }, SLOW);
115
+
116
+ it('--codemod: help says it runs optional codemods and skips the composition check, and it does', async () => {
117
+ const options = await upgradeOptions();
118
+ expect(options['--codemod']).toMatch(/Optional codemods run only when named here/);
119
+ expect(options['--codemod']).toMatch(/skips the check of ShadCN-copied compositions/);
120
+
121
+ installPackage('@astryxdesign/core', '0.0.15');
122
+ // An unreadable receipt leaves a registry item unresolved.
123
+ write('src/components/.astryx/broken.json', '{}');
124
+
125
+ const normal = await upgradeJson(['--from', '0.0.14']);
126
+ expect(normal.status).toBe(1);
127
+ expect(normal.envelope.data.registryCompositions.invalid).toBe(1);
128
+
129
+ // 0.0.15 ships one optional codemod, which only runs when named.
130
+ const named = await upgradeJson(['--from', '0.0.14', '--codemod', 'migrate-theme-selectors-to-data-attrs']);
131
+ expect(named.status).toBe(0);
132
+ expect(named.envelope.data.codemods).toBe(1);
133
+ expect(named.envelope.data.registryCompositions).toBeUndefined();
134
+ expect(normal.envelope.data.codemods).toBe(6);
135
+ }, SLOW);
136
+
137
+ it('--from: help names the legacy @xds/core target, which upgrade falls back to', async () => {
138
+ const options = await upgradeOptions();
139
+ expect(options['--from']).toMatch(/legacy @xds\/core/);
140
+
141
+ installPackage('@xds/core', '0.0.20');
142
+ const {status, envelope} = await upgradeJson(['--from', '0.0.19']);
143
+ expect(status).toBe(0);
144
+ expect(envelope.data.to).toBe('0.0.20');
145
+ }, SLOW);
146
+ });
147
+
148
+ describe('astryx upgrade exit codes', () => {
149
+ it('lists a missing core, which exits 1 in both modes', async () => {
150
+ expect(exit1()).toMatch(/no installed @astryxdesign\/core/);
151
+ const text = await runCli(['upgrade', '--from', '0.5.0'], tmpDir);
152
+ const json = await upgradeJson(['--from', '0.5.0']);
153
+ expect(text.status).toBe(1);
154
+ expect(json.status).toBe(1);
155
+ expect(json.envelope.code).toBe('ERR_VERSION_DETECT');
156
+ }, SLOW);
157
+
158
+ it('lists an astryx.config no codemod repairs, which exits 1', async () => {
159
+ expect(exit1()).toMatch(/astryx\.config that fails validation/);
160
+ installPackage('@astryxdesign/core', '0.6.0');
161
+ write('astryx.config.mjs', "export default {theme: 'neutral'};\n");
162
+ const {status, envelope} = await upgradeJson(['--from', '0.5.0']);
163
+ expect(status).toBe(1);
164
+ expect(envelope.code).toBe('ERR_INVALID_ARGUMENT');
165
+ }, SLOW);
166
+
167
+ it('lists a post-codemod hook failure, which exits 1', async () => {
168
+ expect(exit1()).toMatch(/post-codemod hook failure/);
169
+ installPackage('@astryxdesign/core', '0.6.0');
170
+ write(
171
+ 'src/panel.tsx',
172
+ "import {useResizable} from '@astryxdesign/core';\nexport const r = () => useResizable({minSizePx: 200});\n",
173
+ );
174
+ write(
175
+ 'astryx.config.mjs',
176
+ "export default {hooks: {postCodemod: [{buildCommand: () => { throw new Error('formatter crashed'); }}]}};\n",
177
+ );
178
+ const {status, envelope} = await upgradeJson(['--from', '0.5.0']);
179
+ expect(status).toBe(1);
180
+ expect(envelope.code).toBe('ERR_CODEMOD_FAILED');
181
+ expect(envelope.error).toMatch(/Post-codemod hook failed/);
182
+ }, SLOW);
183
+
184
+ it('lists a missing jscodeshift and the refused flag combinations', () => {
185
+ expect(exit1()).toMatch(/jscodeshift missing and not installed/);
186
+ expect(exit1()).toMatch(/--registry with --list or a migration flag/);
187
+ });
188
+ });