@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
@@ -29,6 +29,9 @@
29
29
  * 4. Routing unknown-subcommand attempts through the same error
30
30
  * envelope path (so `astryx bogus-cmd --json` gets exit 1 + envelope
31
31
  * instead of exit 0 + help envelope).
32
+ * 5. Emitting an error envelope, not the help envelope, when Commander
33
+ * shows help because the invocation failed (`help <unknown>`, or a
34
+ * command group with no subcommand), which exits 1.
32
35
  *
33
36
  * Non-JSON behavior is preserved exactly: every code path that printed
34
37
  * to stderr before still prints to stderr. Commander writes its
@@ -117,6 +120,35 @@ export function buildHelpEnvelope(cmd) {
117
120
  };
118
121
  }
119
122
 
123
+ /**
124
+ * The error envelope for help Commander shows because the invocation failed
125
+ * (it then exits 1): `help <name>` for an unknown name on the root, or a
126
+ * command group run without a subcommand.
127
+ *
128
+ * @param {import('commander').Command} cmd the command whose help was shown
129
+ * @returns {ReturnType<typeof toErrorEnvelope>}
130
+ */
131
+ export function buildHelpErrorEnvelope(cmd) {
132
+ const available = cmd.commands
133
+ .filter(s => !(/** @type {any} */ (s))._hidden && s.name() !== 'help')
134
+ .map(s => s.name());
135
+ if (!cmd.parent) {
136
+ // Commander dispatches `help <name>` with ['help', <name>, ...] in args.
137
+ const requested = cmd.args[1];
138
+ return toErrorEnvelope(
139
+ requested ? `unknown command '${requested}'` : 'unknown command',
140
+ available.map(name => ({name, reason: 'available command'})),
141
+ ERROR_CODES.ERR_UNKNOWN_COMMAND,
142
+ );
143
+ }
144
+ const group = fullNameOf(cmd);
145
+ return toErrorEnvelope(
146
+ `'${group}' needs a subcommand`,
147
+ available.map(name => ({name: `${group} ${name}`, reason: 'available subcommand'})),
148
+ ERROR_CODES.ERR_MISSING_ARGUMENT,
149
+ );
150
+ }
151
+
120
152
  /**
121
153
  * Emit a JSON error envelope to stdout (the JSON contract uses stdout
122
154
  * for both success and error).
@@ -310,7 +342,9 @@ function patchOutputHelp(cmd) {
310
342
  if (jsonActive()) {
311
343
  if (!process.__xdsJsonHandled) {
312
344
  process.__xdsJsonHandled = true;
313
- const env = buildHelpEnvelope(cmd);
345
+ const env = contextOptions?.error
346
+ ? buildHelpErrorEnvelope(cmd)
347
+ : buildHelpEnvelope(cmd);
314
348
  process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
315
349
  }
316
350
  return;
@@ -334,7 +368,9 @@ function patchPrototype(CommandCtor) {
334
368
  if (jsonActive()) {
335
369
  if (!process.__xdsJsonHandled) {
336
370
  process.__xdsJsonHandled = true;
337
- const env = buildHelpEnvelope(this);
371
+ const env = contextOptions?.error
372
+ ? buildHelpErrorEnvelope(this)
373
+ : buildHelpEnvelope(this);
338
374
  process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
339
375
  }
340
376
  return;
@@ -20,7 +20,12 @@
20
20
  */
21
21
 
22
22
  import {describe, it, expect} from 'vitest';
23
+ import {spawnSync} from 'node:child_process';
24
+ import {fileURLToPath} from 'node:url';
25
+ import {Command} from 'commander';
23
26
  import {runCli} from '../../../test-utils/run-cli.mjs';
27
+ import {installJsonShim} from './json-shim.mjs';
28
+ import {setJsonMode} from '../../../foundation/response/json.mjs';
24
29
 
25
30
  function parseJson(stdout) {
26
31
  return JSON.parse(stdout);
@@ -207,3 +212,81 @@ describe('--json shim: stdout discipline under --json', () => {
207
212
  }
208
213
  });
209
214
  });
215
+
216
+ describe('--json shim: help shown for a failed invocation is an error envelope', () => {
217
+ it('astryx help bogus --json emits ERR_UNKNOWN_COMMAND, exit 1', async () => {
218
+ const {status, stdout, stderr} = await runCli(['help', 'bogus', '--json']);
219
+ expect(status).toBe(1);
220
+ expect(stderr).toBe('');
221
+ const parsed = parseJson(stdout);
222
+ expect(parsed).not.toHaveProperty('type');
223
+ expect(parsed.apiVersion).toBe(1);
224
+ expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
225
+ expect(parsed.error).toMatch(/bogus/);
226
+ });
227
+
228
+ it('astryx layout --json (group, no subcommand) emits ERR_MISSING_ARGUMENT, exit 1', async () => {
229
+ const {status, stdout, stderr} = await runCli(['layout', '--json']);
230
+ expect(status).toBe(1);
231
+ expect(stderr).toBe('');
232
+ const parsed = parseJson(stdout);
233
+ expect(parsed).not.toHaveProperty('type');
234
+ expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
235
+ expect(parsed.suggestions.map((s) => s.name)).toContain('layout expand');
236
+ });
237
+
238
+ it('astryx layout (no --json) still prints help to stderr, exit 1', async () => {
239
+ const {status, stdout, stderr} = await runCli(['layout']);
240
+ expect(status).toBe(1);
241
+ expect(stdout).toBe('');
242
+ expect(stderr).toMatch(/Usage: astryx layout/);
243
+ });
244
+
245
+ it('the real binary emits the same envelope for help bogus --json', () => {
246
+ // One program per process, so the root's own outputHelp patch is used here.
247
+ const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
248
+ const res = spawnSync(process.execPath, [bin, 'help', 'bogus', '--json'], {
249
+ encoding: 'utf-8',
250
+ timeout: 20_000,
251
+ });
252
+ expect(res.status).toBe(1);
253
+ expect(res.stderr).toBe('');
254
+ const parsed = parseJson(res.stdout);
255
+ expect(parsed).not.toHaveProperty('type');
256
+ expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
257
+ });
258
+
259
+ it('a group added after install gets the same error envelope', () => {
260
+ const program = new Command('astryx');
261
+ installJsonShim(program);
262
+ // Added later, so only the prototype-level patch covers its outputHelp.
263
+ const late = new Command('late');
264
+ late.command('child');
265
+ program.addCommand(late);
266
+ /** @type {string[]} */
267
+ const writes = [];
268
+ const origWrite = process.stdout.write;
269
+ // @ts-expect-error - test-only capture
270
+ process.stdout.write = (chunk) => writes.push(String(chunk)) > 0;
271
+ setJsonMode(true);
272
+ delete process.__xdsJsonHandled;
273
+ try {
274
+ late.outputHelp({error: true});
275
+ } finally {
276
+ process.stdout.write = origWrite;
277
+ setJsonMode(false);
278
+ delete process.__xdsJsonHandled;
279
+ }
280
+ const parsed = parseJson(writes.join(''));
281
+ expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
282
+ expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
283
+ });
284
+
285
+ it('astryx help layout --json still emits the help envelope, exit 0', async () => {
286
+ const {status, stdout} = await runCli(['help', 'layout', '--json']);
287
+ expect(status).toBe(0);
288
+ const parsed = parseJson(stdout);
289
+ expect(parsed.type).toBe('help');
290
+ expect(parsed.data.command).toBe('astryx layout');
291
+ });
292
+ });
@@ -48,6 +48,8 @@ export interface ManifestCommand {
48
48
  responseTypes?: string[];
49
49
  /** Example invocations. */
50
50
  examples?: string[];
51
+ /** Documented exit codes: the process exit status and when it occurs. */
52
+ exitCodes?: {code: number; when: string}[];
51
53
  /** Nested subcommands (e.g. `theme build` under `theme`). */
52
54
  subcommands?: ManifestCommand[];
53
55
  }
@@ -35,6 +35,8 @@
35
35
  */
36
36
 
37
37
  import {API_VERSION} from '../../../foundation/response/json.mjs';
38
+ import {commandDocsOf} from './define-command.mjs';
39
+ import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
38
40
 
39
41
  /**
40
42
  * Response `type` discriminators each fully-qualified command can emit in
@@ -237,6 +239,18 @@ function fullName(cmd, root) {
237
239
  return parts.join(' ');
238
240
  }
239
241
 
242
+ /**
243
+ * The docs a command was built from. `manifest` is registered by hand in
244
+ * index.mjs, so its CommandDoc is read here.
245
+ * @param {import('commander').Command} cmd
246
+ * @param {string} name
247
+ */
248
+ function docsOf(cmd, name) {
249
+ return (
250
+ commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
251
+ );
252
+ }
253
+
240
254
  /**
241
255
  * Recursively describe a Commander command and its subcommands.
242
256
  *
@@ -252,6 +266,8 @@ function describeCommand(cmd, root, jsonSupported) {
252
266
  // `_hidden` is a Commander internal not present on its public types.
253
267
  if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
254
268
 
269
+ const docs = docsOf(cmd, name);
270
+
255
271
  const subcommands = /** @type {object[]} */ (
256
272
  (cmd.commands || [])
257
273
  .map(sub => describeCommand(sub, root, jsonSupported))
@@ -284,6 +300,12 @@ function describeCommand(cmd, root, jsonSupported) {
284
300
 
285
301
  if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
286
302
 
303
+ const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
304
+ code,
305
+ when,
306
+ }));
307
+ if (exitCodes.length > 0) entry.exitCodes = exitCodes;
308
+
287
309
  // Sort subcommands by name for a stable, agent-facing contract — the same
288
310
  // guarantee the top-level command list makes. Otherwise Commander
289
311
  // registration order leaks into the manifest and a pure reorder of
@@ -196,3 +196,20 @@ describe('manifest: e2e', () => {
196
196
  .toContain('component.list');
197
197
  });
198
198
  });
199
+
200
+ describe('manifest: text projection', () => {
201
+ it('astryx manifest (text) uses the JSON entry keys as its field names', async () => {
202
+ const text = await runCli(['manifest']);
203
+ expect(text.status).toBe(0);
204
+ const json = JSON.parse((await runCli(['manifest', '--json'])).stdout);
205
+ const jsonKeys = new Set(json.data.commands.flatMap((c) => Object.keys(c)));
206
+ const textKeys = new Set(
207
+ text.stdout
208
+ .split('\n')
209
+ .map((line) => /^([A-Za-z]+):\s/.exec(line)?.[1])
210
+ .filter(Boolean),
211
+ );
212
+ expect(textKeys).toContain('name');
213
+ for (const key of textKeys) expect(jsonKeys).toContain(key);
214
+ });
215
+ });
@@ -182,6 +182,8 @@ export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
182
182
  /**
183
183
  * Remove Astryx section from all known agent doc files.
184
184
  * @param {string} targetDir
185
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
186
+ * resolves outside `targetDir`; nothing is changed.
185
187
  */
186
188
  export function removeAgentDocs(targetDir: string): void;
187
189
  /**
@@ -208,6 +210,8 @@ export function removeAgentDocs(targetDir: string): void;
208
210
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
209
211
  * and upgrade pass one shared block to every target.
210
212
  * @returns {string[]} List of files written
213
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
214
+ * write resolves outside `targetDir`; nothing is written.
211
215
  */
212
216
  export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
213
217
  zh?: boolean | undefined;
@@ -22,11 +22,12 @@
22
22
  import * as fs from 'node:fs';
23
23
  import * as path from 'node:path';
24
24
  import {findCoreDir, CLI_ROOT} from '../fs/paths.mjs';
25
- import {assertWithin} from '../fs/path-safety.mjs';
25
+ import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
26
26
  import {getCliInvocation} from '../env/package-manager.mjs';
27
27
  import {discoverComponents} from '../discovery/component-discovery.mjs';
28
28
  import {Project} from '../config/project.mjs';
29
29
  import {humanLog} from '../response/json.mjs';
30
+ import {ERROR_CODES} from '../response/error-codes.mjs';
30
31
  import {
31
32
  AGENTS_MD,
32
33
  CLAUDE_MD,
@@ -705,12 +706,65 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
705
706
  return true;
706
707
  }
707
708
 
709
+ /**
710
+ * Whether an agent-doc file already carries a managed-block marker.
711
+ * @param {string} filePath
712
+ * @returns {boolean}
713
+ */
714
+ function hasManagedMarker(filePath) {
715
+ try {
716
+ const content = fs.readFileSync(filePath, 'utf-8');
717
+ return content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START);
718
+ } catch {
719
+ return false;
720
+ }
721
+ }
722
+
723
+ /**
724
+ * Whether `removeXdsBlock` would change `filePath`: it holds one well-formed
725
+ * managed block.
726
+ * @param {string} filePath
727
+ * @returns {boolean}
728
+ */
729
+ function hasRemovableBlock(filePath) {
730
+ try {
731
+ return findManagedBlock(fs.readFileSync(filePath, 'utf-8')) != null;
732
+ } catch {
733
+ return false;
734
+ }
735
+ }
736
+
737
+ /**
738
+ * Every file a run writes must resolve inside `targetDir`, symlinks
739
+ * included. Checked for the whole write set before the first write, so an
740
+ * escape writes nothing.
741
+ * @param {string} targetDir
742
+ * @param {Iterable<string>} relPaths
743
+ */
744
+ function assertTargetsWithin(targetDir, relPaths) {
745
+ for (const p of relPaths) {
746
+ assertWithin(p, targetDir, {label: 'agent docs path'});
747
+ }
748
+ }
749
+
708
750
  /**
709
751
  * Remove Astryx section from all known agent doc files.
710
752
  * @param {string} targetDir
753
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
754
+ * resolves outside `targetDir`; nothing is changed.
711
755
  */
712
756
  export function removeAgentDocs(targetDir) {
713
757
  const allPaths = discoverAgentDocs(targetDir);
758
+ try {
759
+ assertTargetsWithin(
760
+ targetDir,
761
+ allPaths.filter(p => hasRemovableBlock(path.join(targetDir, p))),
762
+ );
763
+ } catch (err) {
764
+ // The code reaches the error envelope as is, so it must be registered.
765
+ if (!(err instanceof PathSafetyError)) throw err;
766
+ throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
767
+ }
714
768
 
715
769
  for (const p of allPaths) {
716
770
  const filePath = path.join(targetDir, p);
@@ -718,9 +772,9 @@ export function removeAgentDocs(targetDir) {
718
772
  const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
719
773
  if (removeXdsBlock(filePath, {deleteIfEmpty})) {
720
774
  if (!fs.existsSync(filePath)) {
721
- humanLog(`✓ Removed empty ${p}`);
775
+ humanLog(`[ok] Removed empty ${p}`);
722
776
  } else {
723
- humanLog(`✓ Removed design system section from ${p}`);
777
+ humanLog(`[ok] Removed design system section from ${p}`);
724
778
  }
725
779
  }
726
780
  }
@@ -750,6 +804,8 @@ export function removeAgentDocs(targetDir) {
750
804
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
751
805
  * and upgrade pass one shared block to every target.
752
806
  * @returns {string[]} List of files written
807
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
808
+ * write resolves outside `targetDir`; nothing is written.
753
809
  */
754
810
  export function installAgentDocs(
755
811
  targetDir,
@@ -806,6 +862,7 @@ export function installAgentDocs(
806
862
  // Agent preset
807
863
  if (agent) {
808
864
  const {inject, create} = resolveAgentPaths(targetDir, agent);
865
+ assertTargetsWithin(targetDir, [...inject, ...create]);
809
866
  for (const p of inject) {
810
867
  injectXdsBlock(path.join(targetDir, p), compressedIndex);
811
868
  written.push(p);
@@ -833,6 +890,14 @@ export function installAgentDocs(
833
890
  if (existing.length > 0) {
834
891
  const wrappers = discoverAgentDocWrappers(targetDir, existing);
835
892
  const targets = existing.filter(p => !wrappers.has(p));
893
+ // A refresh skips unmarked files and a wrapper is only written when it
894
+ // carries a block, so only the files this run writes are checked.
895
+ /** @param {string} p */
896
+ const marked = p => hasManagedMarker(path.join(targetDir, p));
897
+ assertTargetsWithin(targetDir, [
898
+ ...targets.filter(p => !onlyReplace || marked(p)),
899
+ ...[...wrappers].filter(marked),
900
+ ]);
836
901
 
837
902
  for (const p of targets) {
838
903
  const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
@@ -860,6 +925,7 @@ export function installAgentDocs(
860
925
  if (onlyReplace) return written;
861
926
 
862
927
  const defaultPath = AGENTS_MD;
928
+ assertTargetsWithin(targetDir, [defaultPath]);
863
929
  injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
864
930
  createIfMissing: true,
865
931
  header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,