@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
@@ -21,11 +21,28 @@ export const doc = {
21
21
  'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
22
22
  fn: 'layoutExpand',
23
23
  args: [
24
- {name: 'expression', param: 'expression', required: false},
25
- {name: 'path', param: 'options.targetPath', required: false},
24
+ {
25
+ name: 'expression',
26
+ param: 'expression',
27
+ required: false,
28
+ description:
29
+ 'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
30
+ },
31
+ {
32
+ name: 'path',
33
+ param: 'options.targetPath',
34
+ required: false,
35
+ description:
36
+ 'Where to write the TSX, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
37
+ 'any other path is a directory, which receives <Name>.tsx (see --name). An existing file there is replaced. ' +
38
+ 'Omit it to print the code.',
39
+ },
26
40
  ],
27
41
  options: [
28
- {flag: '--file <file>', description: 'Read the expression from a file'},
42
+ {
43
+ flag: '--file <file>',
44
+ description: 'Read the expression from a file (used instead of the argument when both are given)',
45
+ },
29
46
  {
30
47
  flag: '--form <form>',
31
48
  param: 'options.form',
@@ -59,7 +76,7 @@ export const doc = {
59
76
  {code: 0, when: 'success'},
60
77
  {
61
78
  code: 1,
62
- when: 'a missing/empty expression, a bad --name or --form, a parse/validation error, or a path escape',
79
+ when: 'a missing, empty or over-5 MB expression (from stdin or --file), a bad --name or --form, a parse/validation error, or a path escape',
63
80
  },
64
81
  ],
65
82
  related: ['layout check', 'layout grammar'],
@@ -27,8 +27,8 @@ export const doc = {
27
27
  },
28
28
  ],
29
29
  exitCodes: [
30
- {code: 0, when: 'success (help shown, or a subcommand succeeded)'},
31
- {code: 1, when: 'an unknown subcommand'},
30
+ {code: 0, when: 'a subcommand succeeded, or --help'},
31
+ {code: 1, when: 'no subcommand (help is printed) or an unknown subcommand'},
32
32
  ],
33
33
  related: ['template', 'build'],
34
34
  };
@@ -59,6 +59,9 @@ import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
59
59
  * @property {boolean} [loose]
60
60
  */
61
61
 
62
+ /** The largest layout expression read from --file or stdin. */
63
+ const MAX_EXPRESSION_BYTES = 5 * 1024 * 1024; // 5 MB
64
+
62
65
  /**
63
66
  * Resolve the expression from arg, --file, or stdin ('-').
64
67
  * @param {string} [expr]
@@ -78,8 +81,7 @@ async function readExpression(expr, options = {}) {
78
81
  code: ERROR_CODES.ERR_FILE_NOT_FOUND,
79
82
  });
80
83
  }
81
- const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 MB
82
- if (stat.size > MAX_FILE_SIZE) {
84
+ if (stat.size > MAX_EXPRESSION_BYTES) {
83
85
  cliError(
84
86
  `File "${options.file}" is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 5 MB)`,
85
87
  {code: ERROR_CODES.ERR_FILE_NOT_FOUND},
@@ -100,9 +102,19 @@ async function readExpression(expr, options = {}) {
100
102
  }
101
103
  }
102
104
  if (expr === '-') {
105
+ // Capped like --file: an endless stream must not be buffered whole.
103
106
  /** @type {Buffer[]} */
104
107
  const chunks = [];
105
- for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
108
+ let size = 0;
109
+ for await (const chunk of process.stdin) {
110
+ size += /** @type {Buffer} */ (chunk).length;
111
+ if (size > MAX_EXPRESSION_BYTES) {
112
+ cliError('The layout expression on stdin is too large (max 5 MB)', {
113
+ code: ERROR_CODES.ERR_INVALID_ARGUMENT,
114
+ });
115
+ }
116
+ chunks.push(/** @type {Buffer} */ (chunk));
117
+ }
106
118
  return Buffer.concat(chunks).toString('utf-8');
107
119
  }
108
120
  return expr ?? '';
@@ -154,15 +166,15 @@ export function registerLayout(program) {
154
166
  if (result.data.written) {
155
167
  out.push(
156
168
  text(`[ok] Expanded to ${result.data.written}`),
169
+ // Field names are the JSON keys; todos are summarised, not listed.
157
170
  record(
171
+ {componentsUsed: result.data.componentsUsed, todos: result.data.todos},
158
172
  {
159
- components: result.data.componentsUsed,
160
- todos:
161
- result.data.todos.length > 0
162
- ? `${result.data.todos.length} (search for "TODO(xle)")`
163
- : '',
173
+ format: {
174
+ todos: (/** @type {string[]} */ todos) =>
175
+ `${todos.length} (search for "TODO(xle)")`,
176
+ },
164
177
  },
165
- {labels: {components: 'Components', todos: 'TODOs'}},
166
178
  ),
167
179
  );
168
180
  } else {
@@ -0,0 +1,33 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `layout expand` and `layout check` document their input modes (the
5
+ * argument, `-` for stdin, --file) and where `layout expand` writes.
6
+ */
7
+
8
+ import {describe, it, expect} from 'vitest';
9
+ import {runCli} from '../../../test-utils/run-cli.mjs';
10
+ import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
11
+
12
+ const SLOW = 30_000;
13
+
14
+ describe('layout argument behavior is documented', () => {
15
+ it('layout expand help covers stdin, --file precedence and the output path rule', async () => {
16
+ const {status, stdout} = await runCli(['layout', 'expand', '--help']);
17
+ expect(status).toBe(0);
18
+ expect(stdout).toMatch(/Pass - to read it from stdin/);
19
+ expect(stdout).toMatch(/instead of the argument/);
20
+ expect(stdout).toContain('<Name>.tsx');
21
+ expect(stdout).toMatch(/existing file there is replaced/);
22
+ const exts = [...(stdout.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)];
23
+ expect(exts.length).toBeGreaterThan(0);
24
+ for (const [ext] of exts) expect(isFilePathArg(`src/Page${ext}`)).toBe(true);
25
+ }, SLOW);
26
+
27
+ it('layout check help covers stdin and --file precedence', async () => {
28
+ const {status, stdout} = await runCli(['layout', 'check', '--help']);
29
+ expect(status).toBe(0);
30
+ expect(stdout).toMatch(/Pass - to read it from stdin/);
31
+ expect(stdout).toMatch(/instead of the argument/);
32
+ }, SLOW);
33
+ });
@@ -0,0 +1,47 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `layout check -` reads the expression from stdin under the same 5 MB
5
+ * cap as --file, instead of buffering whatever the pipe delivers. Spawns the
6
+ * real bin, since the in-process harness has no stdin.
7
+ */
8
+
9
+ import {describe, it, expect} from 'vitest';
10
+ import {spawnSync} from 'node:child_process';
11
+ import * as path from 'node:path';
12
+ import {fileURLToPath} from 'node:url';
13
+
14
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
15
+ const BIN = path.resolve(HERE, '../bin/astryx.mjs');
16
+ // Run against the monorepo root so @astryxdesign/core is discoverable.
17
+ const REPO = path.resolve(HERE, '../../../..');
18
+ const SLOW = 60_000;
19
+
20
+ /** @param {string} input @param {string[]} [extra] */
21
+ function checkFromStdin(input, extra = []) {
22
+ return spawnSync(process.execPath, [BIN, 'layout', 'check', '-', ...extra], {
23
+ cwd: REPO,
24
+ input,
25
+ encoding: 'utf-8',
26
+ maxBuffer: 16 * 1024 * 1024,
27
+ });
28
+ }
29
+
30
+ describe('layout check - (stdin)', () => {
31
+ it('refuses more than 5 MB with ERR_INVALID_ARGUMENT, in both modes', () => {
32
+ // Valid once trimmed, so only the cap can reject it.
33
+ const big = ' '.repeat(5 * 1024 * 1024 + 1) + 'V';
34
+ const json = checkFromStdin(big, ['--json']);
35
+ expect(json.status).toBe(1);
36
+ expect(JSON.parse(json.stdout).code).toBe('ERR_INVALID_ARGUMENT');
37
+ const human = checkFromStdin(big);
38
+ expect(human.status).toBe(1);
39
+ expect(human.stderr + human.stdout).toMatch(/too large/);
40
+ }, SLOW);
41
+
42
+ it('still reads a normal expression', () => {
43
+ const r = checkFromStdin('V > B', ['--json']);
44
+ expect(r.status).toBe(0);
45
+ expect(JSON.parse(r.stdout).data.valid).toBe(true);
46
+ }, SLOW);
47
+ });
@@ -0,0 +1,39 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file `layout expand` text output names its fields after the JSON keys, so
5
+ * the two views stay greppable against each other.
6
+ */
7
+
8
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
9
+ import * as fs from 'node:fs';
10
+ import * as path from 'node:path';
11
+ import {runCli} from '../../../test-utils/run-cli.mjs';
12
+
13
+ const SLOW = 60_000;
14
+
15
+ describe('layout expand text fields mirror the JSON keys', () => {
16
+ let cwd;
17
+ beforeEach(() => {
18
+ // Inside the workspace so @astryxdesign/core resolves.
19
+ cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-text-fields-'));
20
+ });
21
+ afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
22
+
23
+ it('labels every record field with a key of the layout.expand data', async () => {
24
+ const expr = 'V > B + {not-a-real-block}';
25
+ const json = await runCli(['layout', 'expand', expr, './a', '--loose', '--json'], cwd);
26
+ expect(json.status).toBe(0);
27
+ const {data} = JSON.parse(json.stdout);
28
+ expect(data.todos.length).toBeGreaterThan(0);
29
+
30
+ const human = await runCli(['layout', 'expand', expr, './b', '--loose'], cwd);
31
+ expect(human.status).toBe(0);
32
+ const fields = human.stdout
33
+ .split('\n')
34
+ .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
35
+ .filter(Boolean);
36
+ expect(fields).toEqual(['componentsUsed', 'todos']);
37
+ for (const field of fields) expect(Object.keys(data)).toContain(field);
38
+ }, SLOW);
39
+ });
@@ -0,0 +1,94 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file The CLI never asks a question, so no help text, manifest entry or
5
+ * error-code description may say a flag skips a prompt. Each flag's text states
6
+ * what happens without it instead, and the CLI does that.
7
+ */
8
+
9
+ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
10
+ import * as fs from 'node:fs';
11
+ import * as os from 'node:os';
12
+ import * as path from 'node:path';
13
+ import {fileURLToPath} from 'node:url';
14
+ import {runCli} from '../../../test-utils/run-cli.mjs';
15
+ import {doc as errorCodesDoc} from '../../../foundation/response/error-codes.doc.mjs';
16
+ import {doc as upgradeFn} from '../../../api/upgrade/upgrade.doc.mjs';
17
+
18
+ const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
19
+ const SLOW = 30_000;
20
+
21
+ /** @type {string} */
22
+ let tmpDir;
23
+
24
+ beforeEach(() => {
25
+ tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-prompt-'));
26
+ fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
27
+ });
28
+
29
+ afterEach(() => {
30
+ fs.rmSync(tmpDir, {recursive: true, force: true});
31
+ });
32
+
33
+ /**
34
+ * One option's description from the manifest (subcommands are nested).
35
+ * @param {string} command @param {string} flag
36
+ */
37
+ async function optionText(command, flag) {
38
+ const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
39
+ /** @typedef {{name: string, options: Array<{flag: string, description: string}>, subcommands?: ManifestCommand[]}} ManifestCommand */
40
+ /** @param {ManifestCommand[]} list @returns {ManifestCommand | undefined} */
41
+ const find = list => {
42
+ for (const c of list) {
43
+ const hit = c.name === command ? c : find(c.subcommands ?? []);
44
+ if (hit) return hit;
45
+ }
46
+ return undefined;
47
+ };
48
+ const cmd = find(JSON.parse(stdout).data.commands);
49
+ return cmd?.options.find(o => o.flag.includes(flag))?.description ?? '';
50
+ }
51
+
52
+ describe('no help text describes a prompt', () => {
53
+ it('theme add --overwrite states the refusal, and a refused run writes nothing', async () => {
54
+ const help = await optionText('theme add', '--overwrite');
55
+ expect(help).not.toMatch(/prompt/i);
56
+ expect(help).toContain('ERR_FILE_EXISTS');
57
+ expect(help).toMatch(/nothing is written/);
58
+
59
+ const first = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
60
+ expect(first.status).toBe(0);
61
+ const {outputDir, files} = JSON.parse(first.stdout).data;
62
+ expect(files.length).toBeGreaterThan(1);
63
+ const dir = path.join(tmpDir, outputDir);
64
+ fs.writeFileSync(path.join(dir, files[0]), '// edited\n');
65
+ fs.rmSync(path.join(dir, files[1]));
66
+
67
+ const refused = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
68
+ expect(refused.status).toBe(1);
69
+ expect(JSON.parse(refused.stdout).code).toBe('ERR_FILE_EXISTS');
70
+ expect(fs.readFileSync(path.join(dir, files[0]), 'utf8')).toBe('// edited\n');
71
+ expect(fs.existsSync(path.join(dir, files[1]))).toBe(false);
72
+ }, SLOW);
73
+
74
+ it('upgrade --install-deps names the failure without it, in help and in the API doc', async () => {
75
+ const help = await optionText('upgrade', '--install-deps');
76
+ const param = upgradeFn.params?.find(p => p.name === 'options.installDeps')?.description ?? '';
77
+ for (const text of [help, param]) {
78
+ expect(text).not.toMatch(/prompt/i);
79
+ expect(text).toContain('ERR_DEP_MISSING');
80
+ }
81
+ }, SLOW);
82
+
83
+ it('ERR_FILE_EXISTS is described without an interactive mode, in the code set, its doc and the README table', () => {
84
+ const member = errorCodesDoc.members.find(m => m.value === 'ERR_FILE_EXISTS');
85
+ expect(member?.description).toBe('Refused to overwrite an existing file.');
86
+
87
+ const source = fs.readFileSync(path.join(CLI_ROOT, 'foundation/response/error-codes.mjs'), 'utf8');
88
+ expect(source).toMatch(/\/\*\* Refused to overwrite an existing file\. \*\/\s*ERR_FILE_EXISTS:/);
89
+
90
+ const readme = fs.readFileSync(path.join(CLI_ROOT, 'README.md'), 'utf8');
91
+ const row = readme.split('\n').find(line => line.startsWith('| `ERR_FILE_EXISTS`'));
92
+ expect(row).toMatch(/\| Refused to overwrite an existing file\.\s+\|$/);
93
+ });
94
+ });
@@ -29,11 +29,11 @@ export const doc = {
29
29
  {
30
30
  flag: '--limit <n>',
31
31
  param: 'options.limit',
32
- description: 'Max number of results (default 20)',
32
+ description: 'Max number of results, a positive integer (default 20)',
33
33
  },
34
34
  {
35
35
  flag: '--verbose',
36
- description: 'Verbose output (include import paths and match reason)',
36
+ description: "Also print each result's score and match reason",
37
37
  },
38
38
  ],
39
39
  examples: [
@@ -45,7 +45,10 @@ export const doc = {
45
45
  ],
46
46
  exitCodes: [
47
47
  {code: 0, when: 'success (including zero matches)'},
48
- {code: 1, when: 'invalid --type or a non-positive --limit'},
48
+ {
49
+ code: 1,
50
+ when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
51
+ },
49
52
  ],
50
53
  related: ['component', 'hook', 'docs', 'template', 'build'],
51
54
  };
@@ -16,7 +16,7 @@
16
16
  * astryx search button Ranked results across all domains
17
17
  * astryx search modal --type component Filter to a single domain
18
18
  * astryx search forms --limit 5 Cap the result count
19
- * astryx search button --verbose Verbose (include import / reason)
19
+ * astryx search button --verbose Also print score / reason
20
20
  * astryx search button --json Typed JSON envelope
21
21
  */
22
22
 
@@ -54,11 +54,10 @@ export function registerSearch(program) {
54
54
  // Never let the nudge break the command.
55
55
  }
56
56
 
57
- // Parse --limit to a number; the API validates it (positive integer) and
58
- // throws ERR_INVALID_ARGUMENT, so we pass NaN through rather than
59
- // pre-rejecting with a generic code here.
60
- const limit =
61
- options.limit != null ? Number.parseInt(options.limit, 10) : 20;
57
+ // Number(), not parseInt(): parseInt truncates `1.5` and `5abc` into
58
+ // integers the API would reject. The API validates the value, so the
59
+ // flag and `search({limit})` accept and refuse the same inputs.
60
+ const limit = options.limit != null ? Number(options.limit) : 20;
62
61
 
63
62
  /** @type {import('../../../api/search/search.type.mjs').SearchResponse} */
64
63
  let result;
@@ -117,14 +116,25 @@ export function registerSearch(program) {
117
116
  ? [
118
117
  'name',
119
118
  'domain',
119
+ 'title',
120
120
  'displayName',
121
+ 'kind',
121
122
  'score',
122
123
  'reason',
123
124
  'import',
124
125
  'description',
125
126
  'command',
126
127
  ]
127
- : ['name', 'domain', 'displayName', 'import', 'description', 'command'];
128
+ : [
129
+ 'name',
130
+ 'domain',
131
+ 'title',
132
+ 'displayName',
133
+ 'kind',
134
+ 'import',
135
+ 'description',
136
+ 'command',
137
+ ];
128
138
 
129
139
  // The heading mirrors the JSON: `matchCount` is what matched, and the
130
140
  // records below are the slice `--limit` allowed. Saying only "(20)" when
@@ -11,6 +11,8 @@
11
11
  */
12
12
 
13
13
  import {describe, it, expect} from 'vitest';
14
+ import * as fs from 'node:fs';
15
+ import * as os from 'node:os';
14
16
  import * as path from 'node:path';
15
17
  import {fileURLToPath} from 'node:url';
16
18
  import {search, scoreCandidate, SEARCH_DOMAINS} from '../../../api/search/search.mjs';
@@ -28,6 +30,33 @@ const OPTS = {cwd: REPO_ROOT};
28
30
  // the vitest per-test timeout. Give both the same generous scan budget.
29
31
  const SCAN_TIMEOUT = 30_000;
30
32
 
33
+ /**
34
+ * A JSON value as the formatters print it (they normalize typography to ASCII).
35
+ * @param {unknown} value
36
+ */
37
+ function asText(value) {
38
+ return (Array.isArray(value) ? value.join(', ') : String(value))
39
+ .replace(/[\u2014\u2013]/g, '-')
40
+ .replace(/[\u2018\u2019]/g, "'")
41
+ .replace(/[\u201C\u201D]/g, '"')
42
+ .replace(/\u2026/g, '...')
43
+ .replace(/\u00a0/g, ' ')
44
+ .trimEnd();
45
+ }
46
+
47
+ /**
48
+ * Whether some text line prints `key:` with this value. The command field gains
49
+ * the caller's invocation prefix, so the value is matched as the line's end; a
50
+ * multi-line value is matched by its first line.
51
+ * @param {string[]} lines
52
+ * @param {string} key
53
+ * @param {unknown} value
54
+ */
55
+ function printsField(lines, key, value) {
56
+ const shown = asText(value).split('\n')[0].trimEnd();
57
+ return lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown));
58
+ }
59
+
31
60
  describe('search() API — ranking', () => {
32
61
  it('ranks an exact component name match first', async () => {
33
62
  const {data} = await search('button', OPTS);
@@ -172,6 +201,20 @@ describe('search CLI — exit codes + JSON contract', () => {
172
201
  expect(r.status).toBe(1);
173
202
  });
174
203
 
204
+ it.each(['1.5', '5abc'])(
205
+ 'refuses --limit %s like search({limit}) does, in both modes',
206
+ async value => {
207
+ await expect(
208
+ search('x', {...OPTS, limit: Number(value)}),
209
+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
210
+ const json = await runCli(['--json', 'search', 'x', '--limit', value], REPO_ROOT);
211
+ expect(json.status).toBe(1);
212
+ expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
213
+ const text = await runCli(['search', 'x', '--limit', value], REPO_ROOT);
214
+ expect(text.status).toBe(1);
215
+ },
216
+ );
217
+
175
218
  it('emits a valid --json envelope', async () => {
176
219
  const r = await runCli(['--json', 'search', 'button'], REPO_ROOT);
177
220
  expect(r.status).toBe(0);
@@ -223,6 +266,25 @@ describe('search CLI — exit codes + JSON contract', () => {
223
266
  expect(r.stdout).toContain('description:');
224
267
  });
225
268
 
269
+ it('prints every result field under its JSON key (score and reason with --verbose)', async () => {
270
+ // One query that reaches all four domains, so every per-domain field shows.
271
+ const args = ['search', 'theme', '--limit', '60'];
272
+ const env = JSON.parse((await runCli(['--json', ...args], REPO_ROOT)).stdout);
273
+ expect(new Set(env.data.results.map(r => r.domain))).toEqual(new Set(SEARCH_DOMAINS));
274
+ const plain = (await runCli(args, REPO_ROOT)).stdout.split('\n');
275
+ const verbose = (await runCli([...args, '--verbose'], REPO_ROOT)).stdout.split('\n');
276
+ for (const result of env.data.results) {
277
+ for (const [key, value] of Object.entries(result)) {
278
+ if (value == null || value === '') continue;
279
+ const label = `${result.domain} ${result.name}: ${key}`;
280
+ expect(printsField(verbose, key, value), label).toBe(true);
281
+ if (key !== 'score' && key !== 'reason') {
282
+ expect(printsField(plain, key, value), label).toBe(true);
283
+ }
284
+ }
285
+ }
286
+ }, 90_000);
287
+
226
288
  it('--verbose exits 0 and prints import/match detail', async () => {
227
289
  // Regression: the boolean verbose flag was named --detail, which collided
228
290
  // with the value-taking global `--detail <level>` — a bare `search
@@ -236,4 +298,17 @@ describe('search CLI — exit codes + JSON contract', () => {
236
298
  expect(r.stdout).toContain('score:');
237
299
  expect(r.stdout).toContain('reason:');
238
300
  });
301
+
302
+ it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
303
+ const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
304
+ try {
305
+ const json = await runCli(['--json', 'search', 'button'], empty);
306
+ expect(json.status).toBe(1);
307
+ expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
308
+ const text = await runCli(['search', 'button'], empty);
309
+ expect(text.status).toBe(1);
310
+ } finally {
311
+ fs.rmSync(empty, {recursive: true, force: true});
312
+ }
313
+ });
239
314
  }, SCAN_TIMEOUT);
@@ -40,7 +40,8 @@ export const doc = {
40
40
  {
41
41
  flag: '-f, --overwrite',
42
42
  param: 'options.overwrite',
43
- description: 'Overwrite existing files without prompting',
43
+ description:
44
+ 'Replace existing files. Without it, existing files fail the command with ERR_FILE_EXISTS and nothing is written',
44
45
  },
45
46
  ],
46
47
  examples: [
@@ -74,6 +74,37 @@ describe('swizzle path safety', () => {
74
74
  expect(fs.existsSync(absTarget)).toBe(false);
75
75
  });
76
76
 
77
+ it('rejects a component directory that is a symlink out of the project', async () => {
78
+ const {project, outside} = buildFakeRepo(tmpDir);
79
+ const base = path.join(project, 'components', 'astryx');
80
+ fs.mkdirSync(base, {recursive: true});
81
+ fs.symlinkSync(outside, path.join(base, 'Button'));
82
+
83
+ const result = await runCli(['--json', 'swizzle', 'Button'], project);
84
+
85
+ expect(result.code).not.toBe(0);
86
+ expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
87
+ expect(fs.readdirSync(outside)).toEqual([]);
88
+ });
89
+
90
+ it('rejects an existing file that is a symlink out of the project, even with --overwrite', async () => {
91
+ const {project, outside} = buildFakeRepo(tmpDir);
92
+ const outDir = path.join(project, 'components', 'astryx', 'Button');
93
+ fs.mkdirSync(outDir, {recursive: true});
94
+ const target = path.join(outside, 'kept.txt');
95
+ fs.writeFileSync(target, 'kept\n');
96
+ fs.symlinkSync(target, path.join(outDir, 'Button.tsx'));
97
+
98
+ const result = await runCli(
99
+ ['--json', 'swizzle', 'Button', '--overwrite'],
100
+ project,
101
+ );
102
+
103
+ expect(result.code).not.toBe(0);
104
+ expect(JSON.parse(result.stdout).code).toBe('ERR_PATH_TRAVERSAL');
105
+ expect(fs.readFileSync(target, 'utf-8')).toBe('kept\n');
106
+ });
107
+
77
108
  it('requires --overwrite in non-interactive mode when files already exist', async () => {
78
109
  const {project} = buildFakeRepo(tmpDir);
79
110
  const outDir = path.join(project, 'components', 'astryx', 'Button');
@@ -92,4 +123,15 @@ describe('swizzle path safety', () => {
92
123
  // Existing file unchanged
93
124
  expect(fs.readFileSync(existingPath, 'utf-8')).toBe('// my customizations\n');
94
125
  });
126
+
127
+ // The CLI never prompts: without --overwrite it refuses with a code, and the
128
+ // manifest agents read must say so.
129
+ it('describes --overwrite by its refusal, not a prompt', async () => {
130
+ const {project} = buildFakeRepo(tmpDir);
131
+ const result = await runCli(['--json', 'manifest'], project);
132
+ const swizzle = JSON.parse(result.stdout).data.commands.find(c => c.name === 'swizzle');
133
+ const overwrite = swizzle.options.find(o => o.flag.includes('--overwrite'));
134
+ expect(overwrite.description).not.toMatch(/prompt/i);
135
+ expect(overwrite.description).toContain('ERR_FILE_EXISTS');
136
+ });
95
137
  });
@@ -23,11 +23,29 @@ export const doc = {
23
23
  'a discovered template.',
24
24
  fn: 'template',
25
25
  args: [
26
- {name: 'name', param: 'name', required: false},
27
- {name: 'path', param: 'options.targetPath', required: false},
26
+ {
27
+ name: 'name',
28
+ param: 'name',
29
+ required: false,
30
+ description: 'Template id (see --list). Omit it to list the templates.',
31
+ },
32
+ {
33
+ name: 'path',
34
+ param: 'options.targetPath',
35
+ required: false,
36
+ description:
37
+ 'Where to scaffold the template, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
38
+ "any other path is a directory, which receives page.tsx for a page template or the block's own file name for a block. " +
39
+ 'Omit it to print the source.',
40
+ },
28
41
  ],
29
42
  options: [
30
- {flag: '--list', param: 'options.list', description: 'List available templates'},
43
+ {
44
+ flag: '--list',
45
+ param: 'options.list',
46
+ description:
47
+ 'List available templates (narrow with --type and --package) and do nothing else: <name>, <path>, --skeleton and --overwrite are ignored',
48
+ },
31
49
  {
32
50
  flag: '--type <type>',
33
51
  param: 'options.type',
@@ -43,18 +61,22 @@ export const doc = {
43
61
  flag: '--skeleton',
44
62
  param: 'options.skeleton',
45
63
  description:
46
- 'Show layout skeleton with spatial annotations (padding, gap, nesting)',
64
+ 'Show layout skeleton with spatial annotations (padding, gap, nesting) instead of the source. Needs <name>. ' +
65
+ 'It writes nothing, so <path> and --overwrite are ignored; --list and --cdn take precedence',
47
66
  },
48
67
  {
49
68
  flag: '--cdn [path]',
50
69
  param: 'options.cdn',
51
70
  description:
52
- 'Write the no-build-step CDN starter page (default: cdn.template.html)',
71
+ 'Write the no-build-step CDN starter page and do nothing else: <name>, --list, --skeleton, --type and --package are ignored. ' +
72
+ 'The page goes to the --cdn value, else to <path>, else cdn.template.html, and that path is always the file itself. ' +
73
+ 'A value right after --cdn (anything not starting with -) is taken as that path',
53
74
  },
54
75
  {
55
76
  flag: '-f, --overwrite',
56
77
  param: 'options.overwrite',
57
- description: 'Overwrite existing files without prompting',
78
+ description:
79
+ 'Replace an existing target file. Without it an existing file is refused (ERR_FILE_EXISTS) and an existing CDN page is left as is',
58
80
  },
59
81
  ],
60
82
  examples: [