@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/clients/cli/commands/search.test.mjs

@@ -191,18 +191,6 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('No results');
   });
 
-  it('takes every word after `search` as one query', async () => {
-    // Commander took only the first word, so `search dark mode` searched for
-    // "dark" and dropped "mode" without a word.
-    const json = await runCli(['--json', 'search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
-    expect(json.status).toBe(0);
-    const env = JSON.parse(json.stdout);
-    expect(env.data.query).toBe('dark mode');
-    expect(env.data.results[0]).toMatchObject({name: 'theme', section: 'light-dark-mode'});
-    const text = await runCli(['search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
-    expect(text.stdout).toContain('Results for "dark mode"');
-  }, SCAN_TIMEOUT);
-
   it('exits 1 for an invalid --type', async () => {
     const r = await runCli(['search', 'x', '--type', 'bogus'], REPO_ROOT);
     expect(r.status).toBe(1);
@@ -311,19 +299,14 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('reason:');
   });
 
-  it('searches the docs when no @astryxdesign/core is reachable, and exits 1 for --type component', async () => {
+  it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
     const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
     try {
-      const open = await runCli(['--json', 'search', 'make', 'an', 'integration'], empty);
-      expect(open.status).toBe(0);
-      expect(JSON.parse(open.stdout).data.results[0]).toMatchObject({domain: 'doc'});
-      // The text says the search covered the docs alone.
-      const text = await runCli(['search', 'button'], empty);
-      expect(text.status).toBe(0);
-      expect(text.stdout).toContain('only the docs were searched');
-      const json = await runCli(['--json', 'search', 'button', '--type', 'component'], empty);
+      const json = await runCli(['--json', 'search', 'button'], empty);
       expect(json.status).toBe(1);
       expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
+      const text = await runCli(['search', 'button'], empty);
+      expect(text.status).toBe(1);
     } finally {
       fs.rmSync(empty, {recursive: true, force: true});
     }

package/clients/cli/commands/swizzle.doc.mjs

@@ -46,7 +46,7 @@ export const doc = {
   ],
   examples: [
     {label: 'List swizzlable components', cli: 'astryx swizzle --list'},
-    {label: 'Eject a component', cli: 'astryx swizzle Button'},
+    {label: 'Eject a component', cli: 'astryx swizzle XDSButton'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

package/clients/cli/commands/template.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   name: 'template',
   displayName: 'astryx template',
   namespace: 'cli/commands',
-  summary: 'List, show, or scaffold page and block templates',
+  summary: 'Inject a page or block template',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +

package/clients/cli/commands/text-json-parity.test.mjs

@@ -372,17 +372,28 @@ const CASES = [
     skipFieldChecks: true,
   },
   {
-    name: 'integration verify',
-    args: ['integration', 'verify'],
+    name: 'integration pack',
+    args: ['integration', 'pack', '--check'],
     // Needs a packable project; pack itself may exit differently.
     skipFieldChecks: true,
   },
+  // ── Layout command: remove these cases when the layout command is deleted ──
   {
-    // The deprecated alias of `integration verify`.
-    name: 'integration pack',
-    args: ['integration', 'pack', '--check'],
+    name: 'layout check',
+    args: ['layout', 'check', 'Button'],
+    skipFieldChecks: true,
+  },
+  {
+    name: 'layout expand',
+    args: ['layout', 'expand', 'Button'],
+    skipFieldChecks: true,
+  },
+  {
+    name: 'layout grammar',
+    args: ['layout', 'grammar'],
     skipFieldChecks: true,
   },
+  // ── End layout cases ──
   {
     name: 'manifest',
     args: ['manifest'],

package/clients/cli/commands/theme-add.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
   examples: [
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
     {
-      label: 'Pick the owner when two packages ship the same slug',
+      label: 'Select an integration theme',
       cli: 'astryx theme add ocean --package @acme/themes',
     },
   ],

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -35,13 +35,12 @@ export const doc = {
     {
       flag: '--preview <path>',
       param: 'options.preview',
-      description: 'Write a self-contained HTML preview page; the path must end in .html',
+      description: 'Write a standardized self-contained HTML preview',
     },
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description:
-        'Replace existing candidate, receipt, and preview files. Without it, if any of them exists, nothing is written',
+      description: 'Replace existing candidate and receipt files',
     },
   ],
   examples: [

package/clients/cli/commands/theme-palette.doc.mjs

@@ -8,7 +8,8 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Create and work with theme-owned color palettes',
   description:
-    'Palette authoring tools. generate writes a palette candidate for you to review before a theme uses it.',
+    'Palette authoring tools. The initial generate command creates reviewable candidates. ' +
+    'Palette inspection and diagnostic commands are intentionally deferred to follow-up work.',
   subcommands: ['generate'],
   examples: [
     {

package/clients/cli/commands/theme-targets.doc.mjs

@@ -20,8 +20,8 @@ export const doc = {
     'the component that declares it, and the props and states that are legal override keys ' +
     'under it. This is the whole themeable surface in one command: what auditing a theme, or ' +
     'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
-    'component to assemble. Pass a component name to scope it; pass any other text to search ' +
-    'target keys, classes, and components. `--json` for a list a repo can lint its own theme against.',
+    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
+    'keys. `--json` for a list a repo can lint its own theme against.',
   fn: 'themeTargets',
   args: [{name: 'filter', param: 'filter', required: false}],
   examples: [

package/clients/cli/commands/theme.doc.mjs

@@ -13,8 +13,7 @@ export const doc = {
   name: 'theme',
   displayName: 'astryx theme',
   namespace: 'cli/commands',
-  summary:
-    'Create and build themes: add a shipped one, compile to CSS, or list what a theme can override',
+  summary: 'Theme tools: build, export, and manage themes',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
     'subcommand list; the work happens in the subcommands: compile a theme (build), ' +

package/clients/cli/commands/upgrade.doc.mjs

@@ -13,8 +13,7 @@ export const doc = {
   name: 'upgrade',
   displayName: 'astryx upgrade',
   namespace: 'cli/commands',
-  summary:
-    'Update your code after upgrading Astryx, and refresh ShadCN-copied components',
+  summary: 'Migrate versions and update ShadCN-copied compositions',
   description:
     'Migrates project source from a previous Astryx version to the installed one by ' +
     'running the registered codemods, and refreshes the fully rendered managed ' +
@@ -34,7 +33,7 @@ export const doc = {
     {
       flag: '--apply',
       param: 'options.apply',
-      description: 'Write changes to disk; without it, the run is a dry run',
+      description: 'Write changes to disk (default: dry-run)',
       default: false,
     },
     {
@@ -81,8 +80,7 @@ export const doc = {
       flag: '--registry',
       param: 'options.registry',
       description:
-        'Only update ShadCN-copied compositions from their install receipts: unchanged files are updated, ' +
-        'edits that do not overlap are merged, and conflicts are left untouched; --from is not required. ' +
+        'Only reconcile ShadCN-copied compositions; --from is not required. ' +
         'Combining it with --list, --from, --force, --codemod, --skip-codemod, --integration or --install-deps exits 1 with ERR_INVALID_ARGUMENT',
       default: false,
     },
@@ -115,61 +113,4 @@ export const doc = {
     },
   ],
   related: ['init', 'doctor'],
-  notes: [
-    {type: 'heading', level: 3, text: 'Protected files'},
-    {
-      type: 'prose',
-      text:
-        'Codemods never write to a file your project marks as generated, vendored, or ignored. ' +
-        'upgrade reads these marks from the files on disk, so the answer is the same with any version control, or none. ' +
-        'A file is protected when:',
-    },
-    {
-      type: 'list',
-      style: 'unordered',
-      items: [
-        'a `.gitattributes` file marks it `linguist-generated` or `linguist-vendored`',
-        'its leading comment says `@generated`, `@partially-generated`, or `Code generated ... DO NOT EDIT.`',
-        'a `.gitignore`, or the `.hgignore` at the project root, excludes it',
-        'it is an installed dependency (such as anything in `node_modules`), is inside `.git`, `.hg`, or `.sl`, is a symbolic link, or is outside the project',
-      ],
-    },
-    {
-      type: 'prose',
-      text:
-        'Rules work as they do in Git: a later rule wins, so `linguist-generated=false` or a `!` line in an ignore file ' +
-        'returns a file to normal handling. A folder name such as `dist` or `generated` protects nothing by itself. ' +
-        'If a protection file cannot be read or parsed, upgrade stops with ERR_CODEMOD_PROTECTION_SOURCE before it writes anything.',
-    },
-    {
-      type: 'code',
-      lang: 'text',
-      code:
-        '# .gitattributes\n' +
-        'generated/** linguist-generated=true\n' +
-        'vendor/** linguist-vendored=true\n' +
-        '\n' +
-        '# A later rule returns one authored file to normal handling\n' +
-        'generated/hand-authored.ts linguist-generated=false',
-    },
-    {
-      type: 'prose',
-      text:
-        'When a codemod would change a protected file, upgrade makes the change only in memory and leaves the file as it is. ' +
-        'The rest of the upgrade goes ahead. With --apply, your other files are written, then upgrade runs the ' +
-        '`hooks.postCodemod` commands from astryx.config (see `astryx docs authoring config`) and checks the protected ' +
-        'files again. If one still needs the change, the run is incomplete: it exits 1, prints ' +
-        'ERR_CODEMOD_PROTECTED with each file and the rule that protects it, and does not refresh the agent docs. ' +
-        'Regenerate or edit those files, then run the same upgrade again. A dry run reports the same files and writes nothing.',
-    },
-    {
-      type: 'prose',
-      text:
-        'With --json, the receipt says `complete: false` and `errorCode: "ERR_CODEMOD_PROTECTED"`. `modifiedFiles` lists the files ' +
-        'upgrade changed (or would change), and `protectedFiles` lists each blocked file with its `reasons`, `declarations` ' +
-        '(the rules that protect it), `codemods`, and `commands`. A generated file can name the command that rebuilds it on a ' +
-        '`Command:` line in its header, such as `// Command: pnpm run gen:panel`; upgrade prints it as ' +
-        '`Regenerate with: <command>` and lists it in `commands`.',
-    },
-  ],
 };

package/clients/cli/index.mjs

@@ -24,7 +24,7 @@ import {emit, section, text, records} from './formatters/index.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
-import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
+import {addExitCodesHelp, markReportsResult} from './lib/define-command.mjs';
 import {doc as manifestDoc} from './commands/manifest.doc.mjs';
 import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
@@ -95,7 +95,6 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
-  'integration verify',
   'integration pack',
   'upgrade',
   'manifest',
@@ -104,6 +103,9 @@ export const JSON_SUPPORTED = new Set([
   'doctor integration templates',
   'doctor integration components',
   'doctor integration docs',
+  'layout expand',
+  'layout check',
+  'layout grammar',
 ]);
 
 /**
@@ -262,6 +264,7 @@ const commands = [
   {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
+  {name: 'layout', path: './commands/layout.mjs', register: 'registerLayout'},
   {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
   {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
   {name: 'integration', path: './commands/integration.mjs', register: 'registerIntegration'},
@@ -339,24 +342,16 @@ export async function createProgram() {
     .name('astryx')
     .description('Design system CLI — components, themes, and tooling')
     .version(pkg.version)
-    // These four change only the reads named in their text; every other
-    // command ignores them.
-    .option(
-      '--zh',
-      'Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)',
-    )
-    .option('--dense', 'Token-efficient dense text for component <Name> and docs <topic> reads')
+    .option('--zh', 'Output docs in Chinese Simplified')
+    .option('--dense', 'Output docs in compressed dense format (token-efficient)')
     .addOption(
       new Option(
         '--lang <locale>',
-        'Language or format for component and docs reads: en (default), zh (as --zh), or dense (as --dense)',
+        'Output docs in specified language/format (en, zh, dense)',
       ).choices(['en', 'zh', 'dense']),
     )
     .addOption(
-      new Option(
-        '--detail <level>',
-        'Detail level for component, hook, and docs tree reads (e.g. docs cli/commands/build). Lists default to brief',
-      )
+      new Option('--detail <level>', 'Output detail level (full, compact, brief)')
         .choices(['full', 'compact', 'brief'])
         .default('full'),
     )
@@ -476,19 +471,6 @@ export async function createProgram() {
     const fullName = fullCommandName(actionCommand, program);
     if (JSON_SUPPORTED.has(fullName)) return;
     process.__xdsJsonHandled = true;
-    // A group given a word it does not have reports an unknown subcommand and
-    // lists the ones it has, in JSON as in text, even when a flag follows it.
-    const extras = actionCommand.commands.length > 0 ? actionCommand.args : [];
-    const unknown = extras.find(arg => !String(arg).startsWith('-'));
-    if (unknown != null) {
-      cliError(`unknown subcommand '${fullName} ${unknown}'`, {
-        code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
-        suggestions: actionCommand.commands.map(child => ({
-          name: child.name(),
-          reason: 'available subcommand',
-        })),
-      });
-    }
     debug.setOutcome('rejected', {
       exitCode: 1,
       code: ERROR_CODES.ERR_INVALID_OPTION,
@@ -623,7 +605,7 @@ export async function createProgram() {
         text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
       );
     });
-  addDocHelp(manifestCommand, manifestDoc);
+  addExitCodesHelp(manifestCommand, manifestDoc.exitCodes);
   markReportsResult(manifestCommand);
 
   // Hidden command used by package.json postinstall scripts

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

@@ -25,8 +25,6 @@
  */
 
 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';
 
 /**
@@ -145,11 +143,10 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     cmd.addOption(option);
   }
 
-  // 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);
+  // Help ends with the documented exit codes. `choices` stay in the option
+  // text: Commander `.choices()` would replace the api layer's
+  // ERR_INVALID_ARGUMENT validation.
+  addExitCodesHelp(cmd, doc.exitCodes);
 
   if (action) {
     // The recording seam. An action's job ends at "here is what I answered
@@ -168,27 +165,6 @@ 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

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

@@ -7,7 +7,6 @@
 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';
 
@@ -47,57 +46,4 @@ 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/exit-codes.test.mjs

@@ -34,14 +34,14 @@ manifest.commands.forEach(walk);
 
 describe('command exit codes', () => {
   it('every CommandDoc documents its exit codes', () => {
-    expect(commandDocs.length).toBeGreaterThan(25);
+    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',
+    '`astryx %s --help` lists the documented exit codes',
     async (name, doc) => {
       const {status, stdout} = await runCli([...name.split(' '), '--help']);
       expect(status).toBe(0);
@@ -51,25 +51,16 @@ describe('command exit codes', () => {
       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/);

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

@@ -33,12 +33,10 @@
  *      shows help because the invocation failed (`help <unknown>`, or a
  *      command group with no subcommand), which exits 1.
  *
- * 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.
+ * 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.
  */
 
 import {API_VERSION, isJsonMode, toErrorEnvelope} from '../../../foundation/response/json.mjs';
@@ -251,20 +249,11 @@ 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);
     },
   });
@@ -443,15 +432,16 @@ export function handleCommanderError(err) {
     code: commanderCodeToErrorCode(code, message),
   });
 
-  // 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, '');
+  // Real error paths.
   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 {
-    // 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`);
+    // 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.
   }
   process.exit(exitCode || 1);
 }

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

@@ -225,6 +225,23 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
     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));
@@ -240,9 +257,6 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
   });
 
   it('a group added after install gets the same error envelope', () => {
-    // This is the only coverage of the no-subcommand path: every group the CLI
-    // ships has an action of its own (see command-result-coverage.test.mjs), so
-    // a group without one has to be built here.
     const program = new Command('astryx');
     installJsonShim(program);
     // Added later, so only the prototype-level patch covers its outputHelp.
@@ -268,11 +282,11 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
     expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
   });
 
-  it('astryx help theme --json still emits the help envelope, exit 0', async () => {
-    const {status, stdout} = await runCli(['help', 'theme', '--json']);
+  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 theme');
+    expect(parsed.data.command).toBe('astryx layout');
   });
 });