@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/clients/cli/lib/define-command.mjs

@@ -25,6 +25,9 @@
  */
 
 import {recordCommandResult} from '../../../foundation/debug/index.mjs';
+import {routeSegment} from '../../../foundation/discovery/docs-section-key.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
+import {text} from '../formatters/index.mjs';
 
 /**
  * Marks a Commander command that reports what it answered with, and says HOW:
@@ -78,6 +81,21 @@ export function markReportsResult(cmd) {
   return cmd;
 }
 
+/** The CommandDoc and wrapped FunctionDoc a command was built from. */
+export const COMMAND_DOCS = Symbol.for('astryx.command.docs');
+
+/**
+ * The docs a command was built from; undefined for a hand-registered command.
+ * @param {import('commander').Command} cmd
+ * @returns {{
+ *   doc: import('@astryxdesign/cli/authoring').CommandDoc,
+ *   fn?: import('@astryxdesign/cli/authoring').FunctionDoc,
+ * } | undefined}
+ */
+export function commandDocsOf(cmd) {
+  return /** @type {any} */ (cmd)?.[COMMAND_DOCS];
+}
+
 /**
  * Build a Commander command from a CommandDoc and attach it to `parent`.
  *
@@ -102,6 +120,7 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     .join(' ');
 
   const cmd = parent.command(argSpec ? `${token} ${argSpec}` : token);
+  Object.defineProperty(cmd, COMMAND_DOCS, {value: {doc, fn}, configurable: true});
   if (doc.summary) cmd.description(doc.summary);
 
   const paramDesc = (/** @type {string | undefined} */ name) =>
@@ -126,12 +145,11 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     cmd.addOption(option);
   }
 
-  // `choices` and `examples` are doc metadata surfaced by `astryx docs` and the
-  // doc site; they are intentionally NOT injected into `--help` here. Choices
-  // stay described in the option text (Commander `.choices()` would also change
-  // validation from the api layer's ERR_INVALID_ARGUMENT), and the current CLI
-  // help carries no per-command examples epilog. Keeping both out preserves the
-  // exact `--help`/manifest surface as registrations migrate to this converter.
+  // Help ends with the documented exit codes, the examples, and the docs
+  // route that reads the whole command. `choices` stay in the option text:
+  // Commander `.choices()` would replace the api layer's ERR_INVALID_ARGUMENT
+  // validation.
+  addDocHelp(cmd, doc);
 
   if (action) {
     // The recording seam. An action's job ends at "here is what I answered
@@ -149,3 +167,35 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
   }
   return cmd;
 }
+
+/**
+ * End `cmd`'s help with what its CommandDoc says: the exit codes, then the
+ * examples, then `More:`, the `astryx docs` route that reads the whole command.
+ * @param {import('commander').Command} cmd
+ * @param {import('@astryxdesign/cli/authoring').CommandDoc} doc
+ */
+export function addDocHelp(cmd, doc) {
+  addExitCodesHelp(cmd, doc.exitCodes);
+  // Rendered when help is shown, so the run prefix (npx astryx, pnpm astryx,
+  // ...) is looked up then, not on every start.
+  cmd.addHelpText('after', () => {
+    const examples = (doc.examples ?? []).flatMap(({label, cli}) => [
+      ...(label ? [`  # ${label}`] : []),
+      `  ${formatCliCommand(cli)}`,
+    ]);
+    const more = `More: ${formatCliCommand(`docs cli/commands/${routeSegment(doc.name)}`)}`;
+    const blocks = examples.length > 0 ? [['Examples:', ...examples].join('\n'), more] : [more];
+    return `\n${text(blocks.join('\n\n')).toString()}`;
+  });
+}
+
+/**
+ * End `cmd`'s help with a CommandDoc's exit codes.
+ * @param {import('commander').Command} cmd
+ * @param {import('@astryxdesign/cli/authoring').CommandDoc['exitCodes']} exitCodes
+ */
+export function addExitCodesHelp(cmd, exitCodes) {
+  if (!exitCodes?.length) return;
+  const lines = exitCodes.map(({code, when}) => `  ${code}  ${when}`);
+  cmd.addHelpText('after', `\n${text(['Exit codes:', ...lines].join('\n')).toString()}`);
+}

package/clients/cli/lib/define-command.test.mjs

@@ -7,6 +7,7 @@
 import {Command} from 'commander';
 import {describe, it, expect} from 'vitest';
 import {defineCommand} from './define-command.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 import {doc as searchCommand} from '../commands/search.doc.mjs';
 import {doc as searchFn} from '../../../api/search/search.doc.mjs';
 
@@ -46,4 +47,57 @@ describe('defineCommand', () => {
     expect(cmd.name()).toBe('build');
     expect(cmd.registeredArguments.map(a => a.name())).toEqual(['file']);
   });
+
+  it('ends help with the exit codes, the examples, and the docs route', () => {
+    const program = new Command();
+    const group = program.command('grp');
+    const cmd = defineCommand(
+      group,
+      {
+        type: 'command',
+        name: 'grp sub',
+        displayName: 'astryx grp sub',
+        summary: 'Sub.',
+        examples: [
+          {label: 'Run it', cli: 'astryx grp sub x'},
+          {cli: 'astryx grp sub y --json'},
+        ],
+        exitCodes: [{code: 0, when: 'it works'}],
+      },
+      {action: () => {}},
+    );
+    let out = '';
+    cmd.configureOutput({writeOut: s => (out += s)});
+    cmd.outputHelp();
+    const stem = formatCliCommand('');
+    expect(out.slice(out.indexOf('\nExit codes:\n'))).toBe(
+      [
+        '',
+        'Exit codes:',
+        '  0  it works',
+        '',
+        'Examples:',
+        '  # Run it',
+        `  ${stem} grp sub x`,
+        `  ${stem} grp sub y --json`,
+        '',
+        `More: ${stem} docs cli/commands/grp-sub`,
+        '',
+      ].join('\n'),
+    );
+  });
+
+  it('still names the docs route when a command has no examples', () => {
+    const program = new Command();
+    const cmd = defineCommand(
+      program,
+      {type: 'command', name: 'solo', summary: 'Solo.', exitCodes: [{code: 0, when: 'ok'}]},
+      {action: () => {}},
+    );
+    let out = '';
+    cmd.configureOutput({writeOut: s => (out += s)});
+    cmd.outputHelp();
+    expect(out).not.toContain('Examples:');
+    expect(out.endsWith(`\n\nMore: ${formatCliCommand('docs cli/commands/solo')}\n`)).toBe(true);
+  });
 });

package/clients/cli/lib/doc-text-ascii.test.mjs

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The component and hook text renderers add no non-ASCII characters of
+ * their own: given ASCII-only docs, every view they produce is plain ASCII.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  formatBrief,
+  formatCompact,
+  formatFull,
+  formatProps,
+} from './component-format.mjs';
+import {
+  formatHookBrief,
+  formatHookCompact,
+  formatHookFull,
+  formatHookParams,
+} from './hook-format.mjs';
+
+const NON_ASCII = /[\u0080-\uffff]/g;
+
+/** @param {string} out @returns {string[]} */
+const nonAscii = out => out.match(NON_ASCII) ?? [];
+
+// Every optional field left empty and every optional path taken, so each
+// placeholder, separator, and arrow the renderers emit shows up at least once.
+const componentDoc = {
+  name: 'Widget',
+  description: 'A widget for tests.',
+  props: [
+    {name: 'variant', type: "'solid' | 'ghost'", description: 'Look.'},
+    {name: 'label', type: 'string', description: 'Label.', required: true},
+    {name: 'disabled', type: 'boolean', description: 'Disables it.'},
+    {name: 'tone', type: 'string', description: 'Tone.'},
+  ],
+  theming: {
+    vars: [{name: '--widget-gap', default: '8px', description: 'Gap.'}],
+    derived: [
+      {property: 'padding', expand: 'container'},
+      {property: 'radius', vars: ['--widget-radius']},
+    ],
+    targets: [
+      {className: 'astryx-widget', deprecatedFor: 'astryx-widget-v2'},
+      {className: 'astryx-widget-v2', visualProps: ['variant']},
+    ],
+  },
+};
+
+const hookDoc = {
+  name: 'useWidget',
+  importPath: '@astryxdesign/core/useWidget',
+  usage: {description: 'Widget behavior.'},
+  params: [
+    {name: 'options', type: 'object', description: 'Options.', required: true},
+    {name: 'delay', type: 'number', description: 'Delay.'},
+  ],
+  returns: [{name: 'open', type: 'boolean', description: 'Open state.'}],
+};
+
+describe('component text output is ASCII', () => {
+  it.each([
+    ['formatFull', () => formatFull(componentDoc)],
+    ['formatCompact', () => formatCompact(componentDoc, 'Widget')],
+    ['formatBrief', () => formatBrief(componentDoc, 'Widget', '@astryxdesign/core/Widget')],
+    ['formatProps', () => formatProps(componentDoc, 'Widget')],
+  ])('%s', (_name, render) => {
+    expect(nonAscii(render())).toEqual([]);
+  });
+});
+
+describe('hook text output is ASCII', () => {
+  it.each([
+    ['formatHookFull', () => formatHookFull(hookDoc)],
+    ['formatHookCompact', () => formatHookCompact(hookDoc, hookDoc.importPath)],
+    ['formatHookBrief', () => formatHookBrief(hookDoc)],
+    ['formatHookParams', () => formatHookParams(hookDoc)],
+  ])('%s', (_name, render) => {
+    expect(nonAscii(render())).toEqual([]);
+  });
+});

package/clients/cli/lib/exit-codes.test.mjs

@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every CommandDoc's exit codes reach generated help and the manifest.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {describe, it, expect} from 'vitest';
+import {program, JSON_SUPPORTED} from '../index.mjs';
+import {buildManifest} from './manifest.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const COMMANDS = path.join(path.dirname(fileURLToPath(import.meta.url)), '../commands');
+
+/** @type {any[]} */
+const commandDocs = [];
+for (const file of fs.readdirSync(COMMANDS).sort()) {
+  if (!file.endsWith('.doc.mjs')) continue;
+  const {doc} = await import(pathToFileURL(path.join(COMMANDS, file)).href);
+  if (doc?.type === 'command') commandDocs.push(doc);
+}
+
+const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** @type {Map<string, any>} */
+const entries = new Map();
+const walk = (/** @type {any} */ c) => {
+  entries.set(c.name, c);
+  (c.subcommands || []).forEach(walk);
+};
+manifest.commands.forEach(walk);
+
+describe('command exit codes', () => {
+  it('every CommandDoc documents its exit codes', () => {
+    expect(commandDocs.length).toBeGreaterThan(30);
+    for (const doc of commandDocs) {
+      expect(doc.exitCodes?.length, doc.name).toBeGreaterThan(0);
+    }
+  });
+
+  it.each(commandDocs.map((d) => [d.name, d]))(
+    '`astryx %s --help` lists the documented exit codes, then the examples and the docs route',
+    async (name, doc) => {
+      const {status, stdout} = await runCli([...name.split(' '), '--help']);
+      expect(status).toBe(0);
+      const section = stdout.slice(stdout.indexOf('\nExit codes:\n'));
+      expect(section.startsWith('\nExit codes:\n'), stdout).toBe(true);
+      expect(stdout.match(/\nExit codes?:\n/g), 'one exit-code section').toHaveLength(1);
+      for (const {code, when} of doc.exitCodes) {
+        expect(section).toContain(`\n  ${code}  ${when}\n`);
+      }
+      // Examples follow the exit codes, each under its label, and a `More:`
+      // line names the route that reads the whole command.
+      const examples = section.indexOf('\nExamples:\n');
+      expect(examples > 0, stdout).toBe((doc.examples ?? []).length > 0);
+      for (const {label, cli} of doc.examples ?? []) {
+        const line = ` ${cli.replace(/^astryx\s+/, '')}\n`;
+        expect(section.slice(examples), stdout).toContain(
+          label ? `\n  # ${label}\n` : line,
+        );
+        expect(section.slice(examples)).toContain(line);
+      }
+      const route = `docs cli/commands/${name.replace(/ /g, '-')}`;
+      expect(section, stdout).toMatch(
+        new RegExp(`\\n\\nMore: \\S.* ${route}\\n`),
+      );
+      expect(section.indexOf('\nMore: ')).toBeGreaterThan(examples);
+    },
+  );
+
+  it('bare `astryx layout` exits 1 in both modes, as documented', async () => {
+    const doc = commandDocs.find((d) => d.name === 'layout');
+    expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/^no subcommand/);
+    expect((await runCli(['layout'])).status).toBe(1);
+    expect((await runCli(['layout', '--json'])).status).toBe(1);
+  });
+
+  it('`astryx discover` with a blank query exits 1 only when packages are discovered', async () => {
+    const doc = commandDocs.find((d) => d.name === 'discover');
+    expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/blank query when packages are discovered/);
+    const project = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-exit-discover-'));
+    try {
+      expect((await runCli(['discover', '   ', '--json'], {cwd: project})).status).toBe(0);
+      const pkg = path.join(project, 'node_modules/@acme/ui');
+      fs.mkdirSync(path.join(pkg, 'components'), {recursive: true});
+      fs.writeFileSync(path.join(pkg, 'package.json'), '{"name":"@acme/ui","version":"1.0.0","type":"module"}');
+      fs.writeFileSync(path.join(pkg, 'astryx.integration.mjs'), "export default {components: './components'};\n");
+      fs.writeFileSync(
+        path.join(pkg, 'components/Widget.doc.mjs'),
+        'export const doc = {type: "component", name: "Widget", description: "A widget"};\n',
+      );
+      fs.writeFileSync(path.join(pkg, 'components/Widget.tsx'), 'export function Widget() { return null; }\n');
+      fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app","type":"module"}');
+      fs.writeFileSync(path.join(project, 'astryx.config.mjs'), "export default {integrations: ['@acme/ui']};\n");
+      expect((await runCli(['discover', '--json'], {cwd: project})).status).toBe(0);
+      const blank = await runCli(['discover', '   ', '--json'], {cwd: project});
+      expect(blank.status).toBe(1);
+      expect(JSON.parse(blank.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    } finally {
+      fs.rmSync(project, {recursive: true, force: true});
+    }
+  });
+
+  it('the manifest carries every command exit code', () => {
+    for (const doc of commandDocs) {
+      expect(entries.get(doc.name)?.exitCodes, doc.name).toEqual(
+        doc.exitCodes.map(({code, when}) => ({code, when})),
+      );
+    }
+  });
+});

package/clients/cli/lib/hook-format.mjs

@@ -9,7 +9,10 @@
  * - Brief: signature line with import hint, description, key params
  */
 
-import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {formatAccessibility, mdCell} from './component-format.mjs';
 
@@ -23,7 +26,9 @@ function buildSignature(docs) {
   const name = docs.name;
 
   // Build params string — only top-level params (skip options.foo nested params)
-  const topParams = (docs.params || []).filter((/** @type {any} */ p) => !p.name.includes('.'));
+  const topParams = (docs.params || []).filter(
+    (/** @type {any} */ p) => !p.name.includes('.'),
+  );
   const paramStr = topParams
     .map((/** @type {any} */ p) => {
       const opt = p.required ? '' : '?';
@@ -57,7 +62,7 @@ function formatParamsTable(params) {
   lines.push('| Param | Type | Default | Description |');
   lines.push('|-------|------|---------|-------------|');
   for (const p of params) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '\u2014';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
     lines.push(
       `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
@@ -150,7 +155,9 @@ export function formatHookCompact(docs, importPath) {
   const imp = importPath || docs.importPath;
   if (imp) {
     sections.push('## Import\n');
-    sections.push(`\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`);
+    sections.push(
+      `\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`,
+    );
   }
 
   // Best Practices (matches component compact)
@@ -198,7 +205,7 @@ export function formatHookCompact(docs, importPath) {
 /**
  * Format a brief, LLM-optimized hook summary.
  * Matches component formatBrief conventions:
- *   signature  ← from 'import/path'
+ *   signature  <- from 'import/path'
  *   description
  *   key params
  * @param {any} docs
@@ -211,7 +218,7 @@ export function formatHookBrief(docs) {
   // Signature line with import hint (matches component brief)
   const sig = buildSignature(docs);
   const imp = docs.importPath;
-  output.push(imp ? `${sig}  \u2190 from '${imp}'` : sig);
+  output.push(imp ? `${sig}  <- from '${imp}'` : sig);
 
   // Description (shortened, matches component brief)
   const desc = docs.usage?.description || '';
@@ -225,12 +232,14 @@ export function formatHookBrief(docs) {
     output.push(`  Related: ${docs.relatedComponents.join(', ')}`);
   }
 
-  // Key params (matches component brief 'prop · prop' line)
+  // Key params (matches component brief 'prop, prop' line)
   const paramNames = (docs.params || [])
     .filter((/** @type {any} */ p) => !p.name.includes('.'))
-    .map((/** @type {any} */ p) => p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name);
+    .map((/** @type {any} */ p) =>
+      p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name,
+    );
   if (paramNames.length > 0) {
-    output.push(`  ${paramNames.join(' \u00b7 ')}`);
+    output.push(`  ${paramNames.join(', ')}`);
   }
 
   return output.join('\n') + '\n';
@@ -253,7 +262,7 @@ export async function formatHookBriefAll(coreDir) {
       const docPath = findHookDoc(coreDir, hookName);
       if (docPath) {
         try {
-          const docs = await loadDocs(docPath);
+          const docs = await loadDocs(docPath, {root: 'hooks'});
           output.push(formatHookBrief(docs));
         } catch {
           output.push(`${hookName}\n  (no docs)\n`);

package/clients/cli/lib/json-shim.mjs

@@ -29,11 +29,16 @@
  *   4. Routing unknown-subcommand attempts through the same error
  *      envelope path (so `astryx bogus-cmd --json` gets exit 1 + envelope
  *      instead of exit 0 + help envelope).
+ *   5. Emitting an error envelope, not the help envelope, when Commander
+ *      shows help because the invocation failed (`help <unknown>`, or a
+ *      command group with no subcommand), which exits 1.
  *
- * Non-JSON behavior is preserved exactly: every code path that printed
- * to stderr before still prints to stderr. Commander writes its
- * "error: ..." line via configureOutput.writeErr, which we pass
- * through verbatim outside of --json mode.
+ * Commander writes its own "error: ..." line via configureOutput.writeErr.
+ * The shim drops that line in both modes. Under --json the error envelope
+ * replaces it; in text mode `handleCommanderError` writes the Astryx line
+ * instead (`Error: <message>`, the same message the envelope carries), so
+ * a parse failure reads like every other CLI error. Other stderr output,
+ * such as help printed as the failure report, still passes through.
  */
 
 import {API_VERSION, isJsonMode, toErrorEnvelope} from '../../../foundation/response/json.mjs';
@@ -117,6 +122,35 @@ export function buildHelpEnvelope(cmd) {
   };
 }
 
+/**
+ * The error envelope for help Commander shows because the invocation failed
+ * (it then exits 1): `help <name>` for an unknown name on the root, or a
+ * command group run without a subcommand.
+ *
+ * @param {import('commander').Command} cmd the command whose help was shown
+ * @returns {ReturnType<typeof toErrorEnvelope>}
+ */
+export function buildHelpErrorEnvelope(cmd) {
+  const available = cmd.commands
+    .filter(s => !(/** @type {any} */ (s))._hidden && s.name() !== 'help')
+    .map(s => s.name());
+  if (!cmd.parent) {
+    // Commander dispatches `help <name>` with ['help', <name>, ...] in args.
+    const requested = cmd.args[1];
+    return toErrorEnvelope(
+      requested ? `unknown command '${requested}'` : 'unknown command',
+      available.map(name => ({name, reason: 'available command'})),
+      ERROR_CODES.ERR_UNKNOWN_COMMAND,
+    );
+  }
+  const group = fullNameOf(cmd);
+  return toErrorEnvelope(
+    `'${group}' needs a subcommand`,
+    available.map(name => ({name: `${group} ${name}`, reason: 'available subcommand'})),
+    ERROR_CODES.ERR_MISSING_ARGUMENT,
+  );
+}
+
 /**
  * Emit a JSON error envelope to stdout (the JSON contract uses stdout
  * for both success and error).
@@ -217,11 +251,20 @@ function applyShimRecursively(cmd) {
   });
   cmd.configureOutput({
     writeOut: (str) => process.stdout.write(str),
+    // Commander's own "error: ..." line never reaches the user. Under --json a
+    // consumer parsing both streams must not see it alongside the envelope;
+    // in text mode it is Commander's format, not Astryx's, so an invalid
+    // global option (`--lang zh-Hans`) printed `error: option '--lang
+    // <locale>' argument 'zh-Hans' is invalid…` where every other CLI error
+    // prints `Error: …`. handleCommanderError writes the Astryx line below,
+    // for both modes, from the same message.
+    //
+    // ONLY that line. Commander also writes HELP through this channel when it
+    // shows help because the invocation failed (a command group with no
+    // subcommand), and that output is still wanted in text mode.
     writeErr: (str) => {
-      // Suppress Commander's "error: ..." stderr line when --json is
-      // active, so a JSON consumer parsing both streams doesn't see
-      // it alongside the envelope. Non-JSON callers are unaffected.
       if (jsonActive()) return;
+      if (/^error:\s/i.test(str)) return;
       process.stderr.write(str);
     },
   });
@@ -310,7 +353,9 @@ function patchOutputHelp(cmd) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
-        const env = buildHelpEnvelope(cmd);
+        const env = contextOptions?.error
+          ? buildHelpErrorEnvelope(cmd)
+          : buildHelpEnvelope(cmd);
         process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
       }
       return;
@@ -334,7 +379,9 @@ function patchPrototype(CommandCtor) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
-        const env = buildHelpEnvelope(this);
+        const env = contextOptions?.error
+          ? buildHelpErrorEnvelope(this)
+          : buildHelpEnvelope(this);
         process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
       }
       return;
@@ -396,16 +443,15 @@ export function handleCommanderError(err) {
     code: commanderCodeToErrorCode(code, message),
   });
 
-  // Real error paths.
+  // Real error paths. Strip Commander's "error: " prefix once: in the envelope
+  // the key is already `error`, and in text mode the Astryx prefix replaces it.
+  const cleaned = message.replace(/^error:\s*/i, '');
   if (jsonActive()) {
-    // Strip Commander's "error: " prefix — the envelope key is `error`
-    // already, doubled "error" is noise.
-    const cleaned = message.replace(/^error:\s*/i, '');
     emitJsonError(cleaned, undefined, commanderCodeToErrorCode(code, cleaned));
   } else {
-    // Non-JSON mode: Commander already wrote the "error: ..." line
-    // to stderr via configureOutput.writeErr before throwing the
-    // CommanderError. Nothing to do — exit with the original code.
+    // Commander's own line was suppressed above, so a parse failure reads the
+    // same as every other CLI error — the `Error: …` line cliError prints.
+    process.stderr.write(`Error: ${cleaned}\n`);
   }
   process.exit(exitCode || 1);
 }

package/clients/cli/lib/json-shim.test.mjs

@@ -20,7 +20,12 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {Command} from 'commander';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+import {setJsonMode} from '../../../foundation/response/json.mjs';
 
 function parseJson(stdout) {
   return JSON.parse(stdout);
@@ -207,3 +212,81 @@ describe('--json shim: stdout discipline under --json', () => {
     }
   });
 });
+
+describe('--json shim: help shown for a failed invocation is an error envelope', () => {
+  it('astryx help bogus --json emits ERR_UNKNOWN_COMMAND, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['help', 'bogus', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+    expect(parsed.error).toMatch(/bogus/);
+  });
+
+  it('astryx layout --json (group, no subcommand) emits ERR_MISSING_ARGUMENT, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions.map((s) => s.name)).toContain('layout expand');
+  });
+
+  it('astryx layout (no --json) still prints help to stderr, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/Usage: astryx layout/);
+  });
+
+  it('the real binary emits the same envelope for help bogus --json', () => {
+    // One program per process, so the root's own outputHelp patch is used here.
+    const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
+    const res = spawnSync(process.execPath, [bin, 'help', 'bogus', '--json'], {
+      encoding: 'utf-8',
+      timeout: 20_000,
+    });
+    expect(res.status).toBe(1);
+    expect(res.stderr).toBe('');
+    const parsed = parseJson(res.stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+  });
+
+  it('a group added after install gets the same error envelope', () => {
+    const program = new Command('astryx');
+    installJsonShim(program);
+    // Added later, so only the prototype-level patch covers its outputHelp.
+    const late = new Command('late');
+    late.command('child');
+    program.addCommand(late);
+    /** @type {string[]} */
+    const writes = [];
+    const origWrite = process.stdout.write;
+    // @ts-expect-error - test-only capture
+    process.stdout.write = (chunk) => writes.push(String(chunk)) > 0;
+    setJsonMode(true);
+    delete process.__xdsJsonHandled;
+    try {
+      late.outputHelp({error: true});
+    } finally {
+      process.stdout.write = origWrite;
+      setJsonMode(false);
+      delete process.__xdsJsonHandled;
+    }
+    const parsed = parseJson(writes.join(''));
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
+  });
+
+  it('astryx help layout --json still emits the help envelope, exit 0', async () => {
+    const {status, stdout} = await runCli(['help', 'layout', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.command).toBe('astryx layout');
+  });
+});

package/clients/cli/lib/manifest.d.ts

@@ -48,6 +48,8 @@ export interface ManifestCommand {
   responseTypes?: string[];
   /** Example invocations. */
   examples?: string[];
+  /** Documented exit codes: the process exit status and when it occurs. */
+  exitCodes?: {code: number; when: string}[];
   /** Nested subcommands (e.g. `theme build` under `theme`). */
   subcommands?: ManifestCommand[];
 }