@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/clients/cli/commands/interactive-guard.test.mjs

@@ -1,17 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Subprocess no-hang tests for `astryx init`.
+ * @file Subprocess no-hang tests: the CLI never waits on stdin (INV1).
  *
- * TTY was removed from the CLI: `init` is non-interactive by default and must
- * run cleanly (exit 0, writing the agent cheat sheet) instead of hanging on a
- * prompt. These tests spawn the CLI with stdin/stdout NOT a TTY (the CI / piped
- * / agent condition). A hang would show as signal SIGTERM + status null; we
- * assert `signal === null && status === 0` to prove it exits cleanly and works.
+ * Every run gets a stdin pipe that stays open and silent, the way an agent's
+ * harness holds it. A prompt or a stdin read for control flow then blocks until
+ * the deadline, and the run ends with signal SIGTERM and status null. With stdin
+ * ignored or closed, the same read would see EOF at once and pass.
+ *
+ * Every command and group in the manifest runs once, with a placeholder for
+ * each required argument so its action is reached, plus the bare `astryx`.
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import {spawnSync} from 'node:child_process';
+import {spawn, spawnSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
@@ -19,37 +21,112 @@ import {fileURLToPath} from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI = path.resolve(__dirname, '..', 'bin', 'astryx.mjs');
+const DEADLINE_MS = 20_000;
+// Keeps every run offline: `blog` fetches its feed when run bare.
+const OFFLINE = `data:text/javascript,${encodeURIComponent(
+  "globalThis.fetch = () => Promise.reject(new TypeError('fetch failed'));",
+)}`;
+
+/**
+ * Run `node <argv>` with a stdin pipe that is never written or ended.
+ * @param {string[]} argv
+ * @param {string} cwd
+ * @param {number} [deadline]
+ * @returns {Promise<{status: number | null, signal: NodeJS.Signals | null, output: string}>}
+ */
+function runHeld(argv, cwd, deadline = DEADLINE_MS) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, argv, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0', CI: ''},
+    });
+    // Never written or ended; a late EPIPE after exit is not a result.
+    child.stdin.on('error', () => {});
+    let output = '';
+    child.stdout.setEncoding('utf8').on('data', chunk => (output += chunk));
+    child.stderr.setEncoding('utf8').on('data', chunk => (output += chunk));
+    const timer = setTimeout(() => child.kill('SIGTERM'), deadline);
+    child.on('error', error => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (status, signal) => {
+      clearTimeout(timer);
+      resolve({status, signal, output});
+    });
+  });
+}
 
-let tmpDir;
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+function runCli(args, cwd) {
+  return runHeld(['--import', OFFLINE, CLI, ...args], cwd);
+}
 
-function runCli(args) {
-  return spawnSync(process.execPath, [CLI, ...args], {
-    cwd: tmpDir,
+/** @returns {Array<[string, string[]]>} */
+function manifestInvocations() {
+  const manifest = spawnSync(process.execPath, [CLI, 'manifest', '--json'], {
     encoding: 'utf8',
-    timeout: 20_000,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    env: {...process.env, FORCE_COLOR: '0', CI: ''},
   });
+  /** @type {string[][]} */
+  const invocations = [[]];
+  /** @param {any[]} commands */
+  const walk = commands => {
+    for (const command of commands) {
+      invocations.push([
+        ...command.name.split(' '),
+        ...command.arguments.filter((/** @type {any} */ a) => a.required).map(() => 'x'),
+      ]);
+      walk(command.subcommands ?? []);
+    }
+  };
+  walk(JSON.parse(manifest.stdout).data.commands);
+  return invocations.map(args => [['astryx', ...args].join(' '), args]);
 }
 
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+describe('the harness holds stdin open', () => {
+  it('so a stdin read is reported as a hang', async () => {
+    const r = await runHeld(['-e', 'process.stdin.resume()'], os.tmpdir(), 1_000);
+    expect(r.signal).toBe('SIGTERM');
+    expect(r.status).toBeNull();
+  });
 });
 
-afterEach(() => {
-  fs.rmSync(tmpDir, {recursive: true, force: true});
+describe('every command exits without waiting on stdin', () => {
+  it.concurrent.for(manifestInvocations())('%s', async ([label, args], {expect}) => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+    try {
+      const r = await runCli(args, cwd);
+      expect(r.signal, `${label} waited on stdin:\n${r.output.slice(-500)}`).toBeNull();
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
 });
 
 describe('init is non-interactive by default (no TTY needed)', () => {
-  it('runs cleanly (exit 0, no hang) and writes agent docs', () => {
-    const r = runCli(['init']);
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-interactive-guard-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, {recursive: true, force: true});
+  });
+
+  it('runs cleanly (exit 0, no hang) and writes agent docs', async () => {
+    const r = await runCli(['init'], tmpDir);
     expect(r.signal).toBeNull(); // did not hang
     expect(r.status).toBe(0); // succeeded without a TTY
     expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0); // wrote the cheat sheet
   });
 
-  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
-    runCli(['init']);
+  it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', async () => {
+    await runCli(['init'], tmpDir);
     // init injects into existing agent-doc files if present, else creates AGENTS.md
     const candidates = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', path.join('.claude', 'CLAUDE.md')];
     const doc = candidates.find(f => fs.existsSync(path.join(tmpDir, f)));
@@ -57,8 +134,8 @@ describe('init is non-interactive by default (no TTY needed)', () => {
     expect(fs.readFileSync(path.join(tmpDir, doc), 'utf8')).toMatch(/ASTRYX:START/);
   });
 
-  it('still runs --features agents non-interactively', () => {
-    const r = runCli(['init', '--features', 'agents']);
+  it('still runs --features agents non-interactively', async () => {
+    const r = await runCli(['init', '--features', 'agents'], tmpDir);
     expect(r.signal).toBeNull();
     expect(r.status).toBe(0);
     expect(fs.readdirSync(tmpDir).length).toBeGreaterThan(0);

package/clients/cli/commands/json-contract.test.mjs

@@ -172,3 +172,36 @@ describe('--json contract: supported commands emit valid envelopes', () => {
     expect(parsed.data.summary.fail).toBeGreaterThan(0);
   });
 });
+
+describe('--json contract: the flag describes the envelopes it emits', () => {
+  /** @param {string} shape e.g. ` apiVersion, error, code, suggestions? ` */
+  const fields = shape => shape.split(',').map(f => f.trim().replace(/\?$/, ''));
+
+  it('names every field of the success and error envelopes', async () => {
+    const manifest = parseJson((await runCli(['manifest', '--json'], {cwd: tmpDir})).stdout);
+    const {description} = manifest.data.globalOptions.find(o => o.flag === '--json');
+    const match = /Success envelope: \{([^}]*)\}.*Error envelope: \{([^}]*)\}/.exec(description);
+    expect(match, description).not.toBeNull();
+    const [, success, error] = /** @type {RegExpExecArray} */ (match);
+
+    for (const key of Object.keys(manifest)) expect(fields(success)).toContain(key);
+    expect(fields(success)).toContain('meta');
+
+    // An unknown command's envelope carries every error field, suggestions included.
+    const failure = parseJson((await runCli(['bogus-cmd', '--json'], {cwd: tmpDir})).stdout);
+    expect(Object.keys(failure)).toContain('suggestions');
+    for (const key of Object.keys(failure)) expect(fields(error)).toContain(key);
+  });
+
+  it('the CLI README describes the same envelopes', () => {
+    const readme = fs.readFileSync(new URL('../../../README.md', import.meta.url), 'utf8');
+    const line = readme
+      .split('\n')
+      .find(l => l.startsWith('- `--json`: Output as typed JSON envelope:'));
+    expect(line, 'README global --json line').toBeDefined();
+    const [success, error] = [...String(line).matchAll(/`\{([^}]*)\}`/g)].map(m => fields(m[1]));
+    expect(success).toEqual(expect.arrayContaining(['apiVersion', 'type', 'data', 'meta']));
+    expect(error).toEqual(expect.arrayContaining(['apiVersion', 'error', 'code', 'suggestions']));
+    expect(readme).toContain('{"apiVersion": 1, "type": "component.detail"');
+  });
+});

package/clients/cli/commands/layout-check.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout check',
   displayName: 'astryx layout check',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Validate a layout expression and echo canonical compact/outline forms',
   description:
@@ -21,9 +21,20 @@ export const doc = {
     'echoes it back in both canonical surfaces (compact and outline). An invalid but ' +
     'parseable expression is reported with line/col and suggestions, and exits non-zero.',
   fn: 'layoutCheck',
-  args: [{name: 'expression', param: 'expression', required: false}],
+  args: [
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+  ],
   options: [
-    {flag: '--file <file>', description: 'Read the expression from a file'},
+    {
+      flag: '--file <file>',
+      description: 'Read the expression from a file (used instead of the argument when both are given)',
+    },
     {
       flag: '--form <form>',
       param: 'options.form',
@@ -47,7 +58,7 @@ export const doc = {
     {code: 0, when: 'the expression is valid'},
     {
       code: 1,
-      when: 'the expression is invalid or empty, has a syntax error, or a bad --form',
+      when: 'the expression is invalid, empty or over 5 MB (from stdin or --file), has a syntax error, or a bad --form',
     },
   ],
   related: ['layout expand', 'layout grammar'],

package/clients/cli/commands/layout-expand.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout expand',
   displayName: 'astryx layout expand',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
@@ -21,11 +21,28 @@ export const doc = {
     'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
   fn: 'layoutExpand',
   args: [
-    {name: 'expression', param: 'expression', required: false},
-    {name: 'path', param: 'options.targetPath', required: false},
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+    {
+      name: 'path',
+      param: 'options.targetPath',
+      required: false,
+      description:
+        '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; ' +
+        'any other path is a directory, which receives <Name>.tsx (see --name). An existing file there is replaced. ' +
+        'Omit it to print the code.',
+    },
   ],
   options: [
-    {flag: '--file <file>', description: 'Read the expression from a file'},
+    {
+      flag: '--file <file>',
+      description: 'Read the expression from a file (used instead of the argument when both are given)',
+    },
     {
       flag: '--form <form>',
       param: 'options.form',
@@ -59,7 +76,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'a missing/empty expression, a bad --name or --form, a parse/validation error, or a path escape',
+      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',
     },
   ],
   related: ['layout check', 'layout grammar'],

package/clients/cli/commands/layout-grammar.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout grammar',
   displayName: 'astryx layout grammar',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
   description:

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'layout',
   displayName: 'astryx layout',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +
@@ -27,8 +27,8 @@ export const doc = {
     },
   ],
   exitCodes: [
-    {code: 0, when: 'success (help shown, or a subcommand succeeded)'},
-    {code: 1, when: 'an unknown subcommand'},
+    {code: 0, when: 'a subcommand succeeded, or --help'},
+    {code: 1, when: 'no subcommand (help is printed) or an unknown subcommand'},
   ],
   related: ['template', 'build'],
 };

package/clients/cli/commands/layout.mjs

@@ -59,6 +59,9 @@ import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
  * @property {boolean} [loose]
  */
 
+/** The largest layout expression read from --file or stdin. */
+const MAX_EXPRESSION_BYTES = 5 * 1024 * 1024; // 5 MB
+
 /**
  * Resolve the expression from arg, --file, or stdin ('-').
  * @param {string} [expr]
@@ -78,8 +81,7 @@ async function readExpression(expr, options = {}) {
         code: ERROR_CODES.ERR_FILE_NOT_FOUND,
       });
     }
-    const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5 MB
-    if (stat.size > MAX_FILE_SIZE) {
+    if (stat.size > MAX_EXPRESSION_BYTES) {
       cliError(
         `File "${options.file}" is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 5 MB)`,
         {code: ERROR_CODES.ERR_FILE_NOT_FOUND},
@@ -100,9 +102,19 @@ async function readExpression(expr, options = {}) {
     }
   }
   if (expr === '-') {
+    // Capped like --file: an endless stream must not be buffered whole.
     /** @type {Buffer[]} */
     const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(/** @type {Buffer} */ (chunk));
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      size += /** @type {Buffer} */ (chunk).length;
+      if (size > MAX_EXPRESSION_BYTES) {
+        cliError('The layout expression on stdin is too large (max 5 MB)', {
+          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
+        });
+      }
+      chunks.push(/** @type {Buffer} */ (chunk));
+    }
     return Buffer.concat(chunks).toString('utf-8');
   }
   return expr ?? '';
@@ -154,15 +166,15 @@ export function registerLayout(program) {
       if (result.data.written) {
         out.push(
           text(`[ok] Expanded to ${result.data.written}`),
+          // Field names are the JSON keys; todos are summarised, not listed.
           record(
+            {componentsUsed: result.data.componentsUsed, todos: result.data.todos},
             {
-              components: result.data.componentsUsed,
-              todos:
-                result.data.todos.length > 0
-                  ? `${result.data.todos.length} (search for "TODO(xle)")`
-                  : '',
+              format: {
+                todos: (/** @type {string[]} */ todos) =>
+                  `${todos.length} (search for "TODO(xle)")`,
+              },
             },
-            {labels: {components: 'Components', todos: 'TODOs'}},
           ),
         );
       } else {

package/clients/cli/commands/layout.path-help.test.mjs

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` and `layout check` document their input modes (the
+ * argument, `-` for stdin, --file) and where `layout expand` writes.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
+
+const SLOW = 30_000;
+
+describe('layout argument behavior is documented', () => {
+  it('layout expand help covers stdin, --file precedence and the output path rule', async () => {
+    const {status, stdout} = await runCli(['layout', 'expand', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+    expect(stdout).toContain('<Name>.tsx');
+    expect(stdout).toMatch(/existing file there is replaced/);
+    const exts = [...(stdout.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)];
+    expect(exts.length).toBeGreaterThan(0);
+    for (const [ext] of exts) expect(isFilePathArg(`src/Page${ext}`)).toBe(true);
+  }, SLOW);
+
+  it('layout check help covers stdin and --file precedence', async () => {
+    const {status, stdout} = await runCli(['layout', 'check', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+  }, SLOW);
+});

package/clients/cli/commands/layout.stdin-cap.test.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout check -` reads the expression from stdin under the same 5 MB
+ * cap as --file, instead of buffering whatever the pipe delivers. Spawns the
+ * real bin, since the in-process harness has no stdin.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(HERE, '../bin/astryx.mjs');
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(HERE, '../../../..');
+const SLOW = 60_000;
+
+/** @param {string} input @param {string[]} [extra] */
+function checkFromStdin(input, extra = []) {
+  return spawnSync(process.execPath, [BIN, 'layout', 'check', '-', ...extra], {
+    cwd: REPO,
+    input,
+    encoding: 'utf-8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+describe('layout check - (stdin)', () => {
+  it('refuses more than 5 MB with ERR_INVALID_ARGUMENT, in both modes', () => {
+    // Valid once trimmed, so only the cap can reject it.
+    const big = ' '.repeat(5 * 1024 * 1024 + 1) + 'V';
+    const json = checkFromStdin(big, ['--json']);
+    expect(json.status).toBe(1);
+    expect(JSON.parse(json.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    const human = checkFromStdin(big);
+    expect(human.status).toBe(1);
+    expect(human.stderr + human.stdout).toMatch(/too large/);
+  }, SLOW);
+
+  it('still reads a normal expression', () => {
+    const r = checkFromStdin('V > B', ['--json']);
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout).data.valid).toBe(true);
+  }, SLOW);
+});

package/clients/cli/commands/layout.text-fields.test.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` text output names its fields after the JSON keys, so
+ * the two views stay greppable against each other.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+describe('layout expand text fields mirror the JSON keys', () => {
+  let cwd;
+  beforeEach(() => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-text-fields-'));
+  });
+  afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
+
+  it('labels every record field with a key of the layout.expand data', async () => {
+    const expr = 'V > B + {not-a-real-block}';
+    const json = await runCli(['layout', 'expand', expr, './a', '--loose', '--json'], cwd);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.todos.length).toBeGreaterThan(0);
+
+    const human = await runCli(['layout', 'expand', expr, './b', '--loose'], cwd);
+    expect(human.status).toBe(0);
+    const fields = human.stdout
+      .split('\n')
+      .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
+      .filter(Boolean);
+    expect(fields).toEqual(['componentsUsed', 'todos']);
+    for (const field of fields) expect(Object.keys(data)).toContain(field);
+  }, SLOW);
+});

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'manifest',
   displayName: 'astryx manifest',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +

package/clients/cli/commands/no-prompt-wording.test.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The CLI never asks a question, so no help text, manifest entry or
+ * error-code description may say a flag skips a prompt. Each flag's text states
+ * what happens without it instead, and the CLI does that.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as errorCodesDoc} from '../../../foundation/response/error-codes.doc.mjs';
+import {doc as upgradeFn} from '../../../api/upgrade/upgrade.doc.mjs';
+
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const SLOW = 30_000;
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-prompt-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * One option's description from the manifest (subcommands are nested).
+ * @param {string} command @param {string} flag
+ */
+async function optionText(command, flag) {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  /** @typedef {{name: string, options: Array<{flag: string, description: string}>, subcommands?: ManifestCommand[]}} ManifestCommand */
+  /** @param {ManifestCommand[]} list @returns {ManifestCommand | undefined} */
+  const find = list => {
+    for (const c of list) {
+      const hit = c.name === command ? c : find(c.subcommands ?? []);
+      if (hit) return hit;
+    }
+    return undefined;
+  };
+  const cmd = find(JSON.parse(stdout).data.commands);
+  return cmd?.options.find(o => o.flag.includes(flag))?.description ?? '';
+}
+
+describe('no help text describes a prompt', () => {
+  it('theme add --overwrite states the refusal, and a refused run writes nothing', async () => {
+    const help = await optionText('theme add', '--overwrite');
+    expect(help).not.toMatch(/prompt/i);
+    expect(help).toContain('ERR_FILE_EXISTS');
+    expect(help).toMatch(/nothing is written/);
+
+    const first = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
+    expect(first.status).toBe(0);
+    const {outputDir, files} = JSON.parse(first.stdout).data;
+    expect(files.length).toBeGreaterThan(1);
+    const dir = path.join(tmpDir, outputDir);
+    fs.writeFileSync(path.join(dir, files[0]), '// edited\n');
+    fs.rmSync(path.join(dir, files[1]));
+
+    const refused = await runCli(['--json', 'theme', 'add', 'matcha'], tmpDir);
+    expect(refused.status).toBe(1);
+    expect(JSON.parse(refused.stdout).code).toBe('ERR_FILE_EXISTS');
+    expect(fs.readFileSync(path.join(dir, files[0]), 'utf8')).toBe('// edited\n');
+    expect(fs.existsSync(path.join(dir, files[1]))).toBe(false);
+  }, SLOW);
+
+  it('upgrade --install-deps names the failure without it, in help and in the API doc', async () => {
+    const help = await optionText('upgrade', '--install-deps');
+    const param = upgradeFn.params?.find(p => p.name === 'options.installDeps')?.description ?? '';
+    for (const text of [help, param]) {
+      expect(text).not.toMatch(/prompt/i);
+      expect(text).toContain('ERR_DEP_MISSING');
+    }
+  }, SLOW);
+
+  it('ERR_FILE_EXISTS is described without an interactive mode, in the code set, its doc and the README table', () => {
+    const member = errorCodesDoc.members.find(m => m.value === 'ERR_FILE_EXISTS');
+    expect(member?.description).toBe('Refused to overwrite an existing file.');
+
+    const source = fs.readFileSync(path.join(CLI_ROOT, 'foundation/response/error-codes.mjs'), 'utf8');
+    expect(source).toMatch(/\/\*\* Refused to overwrite an existing file\. \*\/\s*ERR_FILE_EXISTS:/);
+
+    const readme = fs.readFileSync(path.join(CLI_ROOT, 'README.md'), 'utf8');
+    const row = readme.split('\n').find(line => line.startsWith('| `ERR_FILE_EXISTS`'));
+    expect(row).toMatch(/\| Refused to overwrite an existing file\.\s+\|$/);
+  });
+});

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'search',
   displayName: 'astryx search',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
     'Terminal front-end to search(): prints one ranked, greppable list across ' +
@@ -29,11 +29,11 @@ export const doc = {
     {
       flag: '--limit <n>',
       param: 'options.limit',
-      description: 'Max number of results (default 20)',
+      description: 'Max number of results, a positive integer (default 20)',
     },
     {
       flag: '--verbose',
-      description: 'Verbose output (include import paths and match reason)',
+      description: "Also print each result's score and match reason",
     },
   ],
   examples: [
@@ -45,7 +45,10 @@ export const doc = {
   ],
   exitCodes: [
     {code: 0, when: 'success (including zero matches)'},
-    {code: 1, when: 'invalid --type or a non-positive --limit'},
+    {
+      code: 1,
+      when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
+    },
   ],
   related: ['component', 'hook', 'docs', 'template', 'build'],
 };