@astryxdesign/cli 0.0.0-bootstrap.0 → 0.0.15

package/src/index.mjs

@@ -0,0 +1,334 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Astryx CLI — Commander program setup
+ *
+ * Registers all commands via lazy loading. If one command fails to load
+ * (bad import, syntax error), the other commands still work.
+ */
+
+import {Command, Option} from 'commander';
+import {fileURLToPath} from 'node:url';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {checkForUpdate} from './utils/update-check.mjs';
+import {getRunPrefix} from './utils/package-manager.mjs';
+import {API_VERSION, setJsonMode} from './lib/json.mjs';
+import {buildManifest} from './lib/manifest.mjs';
+import {cliError} from './lib/cli-error.mjs';
+import {ERROR_CODES} from './lib/error-codes.mjs';
+import {levenshteinDistance} from './lib/string-utils.mjs';
+import {installJsonShim} from './lib/json-shim.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Read version from package.json so it stays in sync
+const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
+
+// Intercept `xds --version --json` (or `-V --json`) before Commander processes
+// the version flag and exits. Commander's built-in version handler prints the
+// raw version string and calls process.exit, bypassing our hooks — so the
+// only correct place to JSON-ify it is here.
+const _argv = process.argv.slice(2);
+if (
+  (_argv.includes('--version') || _argv.includes('-V')) &&
+  _argv.includes('--json')
+) {
+  process.__xdsJsonHandled = true;
+  console.log(JSON.stringify({apiVersion: API_VERSION, type: 'version', data: {version: pkg.version}}, null, 2));
+  process.exit(0);
+}
+
+export const program = new Command();
+
+/**
+ * Allowlist of fully-qualified command names that natively support --json.
+ * Subcommands are listed by their full path (parent + leaf), e.g. "theme build".
+ *
+ * Commands NOT in this set will be rejected by the preAction hook below
+ * BEFORE any side effects can run. This protects users from partial state
+ * (e.g. files written, then --json error printed) on commands that don't
+ * yet support structured output.
+ */
+export const JSON_SUPPORTED = new Set([
+  'component',
+  'docs',
+  'discover',
+  'search',
+  'swizzle',
+  'template',
+  'hook',
+  'theme build',
+  'gap-report',
+  'upgrade',
+  'manifest',
+  'doctor',
+]);
+
+program
+  .name('astryx')
+  .description('Design system CLI — components, themes, and tooling')
+  .version(pkg.version)
+  .option('--zh', 'Output docs in Chinese Simplified')
+  .option('--dense', 'Output docs in compressed dense format (token-efficient)')
+  .addOption(
+    new Option(
+      '--lang <locale>',
+      'Output docs in specified language/format (en, zh, dense)',
+    ).choices(['en', 'zh', 'dense']),
+  )
+  .addOption(
+    new Option('--detail <level>', 'Output detail level (full, compact, brief)')
+      .choices(['full', 'compact', 'brief'])
+      .default('full'),
+  )
+  .option(
+    '--json',
+    'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
+  )
+  .addHelpCommand('help', 'Show all commands')
+  .action((options, cmd) => {
+    // If Commander handed us a positional that didn't match any subcommand,
+    // treat it as "unknown command" — exit 1 with a helpful suggestion.
+    // This is the bare-invocation handler; if cmd.args has content here,
+    // none of the registered subcommands matched.
+    const extras = (cmd && cmd.args) || [];
+    if (extras.length > 0) {
+      const unknown = String(extras[0]);
+      const known = (program.commands || [])
+        .filter((c) => !c._hidden && c.name() !== 'help')
+        .map((c) => c.name());
+      const close = known
+        .map((name) => ({name, distance: levenshteinDistance(unknown.toLowerCase(), name.toLowerCase())}))
+        .filter((s) => s.distance <= 3)
+        .sort((a, b) => a.distance - b.distance)
+        .slice(0, 3)
+        .map((s) => ({name: s.name, reason: 'did you mean this?'}));
+      // If we have close matches, surface those. Otherwise list all known commands
+      // so callers (including AI agents) can see what's available.
+      const suggestions = close.length > 0
+        ? close
+        : known.map((name) => ({name, reason: 'available command'}));
+      cliError(`unknown command '${unknown}'`, {suggestions, code: ERROR_CODES.ERR_UNKNOWN_COMMAND});
+      return;
+    }
+
+    // `xds` (no subcommand) — print help, or emit a JSON envelope when --json.
+    if (program.opts().json) {
+      // Emit the full capability manifest so an agent can drive the entire
+      // CLI from one call — no need to scrape `--help` text. We derive this
+      // from Commander metadata (commands, args, flags) and layer on the
+      // JSON_SUPPORTED allowlist + per-command response types. See
+      // lib/manifest.mjs.
+      //
+      // Backwards-compat: the envelope keeps `type: 'help'` and the original
+      // shallow fields (`name`, `version`, `commands` as a string[] of names,
+      // `jsonSupported`) that earlier consumers read. The richer, structured
+      // surface is embedded under `data.manifest` (and is also available
+      // standalone via `astryx manifest --json` as `type: 'manifest'`).
+      process.__xdsJsonHandled = true;
+      const manifest = buildManifest(program, {
+        jsonSupported: JSON_SUPPORTED,
+        version: pkg.version,
+      });
+      console.log(JSON.stringify({
+        apiVersion: API_VERSION,
+        type: 'help',
+        data: {
+          name: manifest.name,
+          version: manifest.version,
+          // Original flat list of command names (string[]) — kept for compat.
+          commands: manifest.commands.map((c) => c.name),
+          jsonSupported: manifest.jsonSupported,
+          // Enriched, self-describing surface (the full manifest payload).
+          manifest,
+        },
+      }, null, 2));
+      return;
+    }
+    program.help();
+  });
+
+/**
+ * Compute the fully qualified command name, e.g. "theme build" or "gap-report".
+ * @param {import('commander').Command} actionCommand
+ * @returns {string}
+ */
+function fullCommandName(actionCommand) {
+  const parts = [];
+  let cmd = actionCommand;
+  while (cmd && cmd !== program) {
+    parts.unshift(cmd.name());
+    cmd = cmd.parent;
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Pre-action hook: gate --json BEFORE any command body runs.
+ *
+ * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
+ * emit a structured error envelope and exit 1 — without running the command's
+ * action (so no filesystem mutations, no clack prompts, no spawned processes).
+ *
+ * This is the single source of truth for "command does not support --json".
+ * Individual commands should NOT re-check this; they may assume that if their
+ * action runs with --json, they are responsible for emitting an envelope on
+ * every code path.
+ */
+program.hook('preAction', (thisCommand, actionCommand) => {
+  if (!program.opts().json) return;
+  // Engage global JSON mode so humanLog()/humanWarn() across commands become
+  // no-ops — stdout now carries only the JSON envelope.
+  setJsonMode(true);
+  // The root program's own action (no subcommand) is handled directly in
+  // its action handler — let it through. fullCommandName is '' there.
+  if (actionCommand === program) return;
+  const fullName = fullCommandName(actionCommand);
+  if (JSON_SUPPORTED.has(fullName)) return;
+  process.__xdsJsonHandled = true;
+  console.log(JSON.stringify({
+    apiVersion: API_VERSION,
+    error: `JSON output is not supported for the '${fullName}' command`,
+    code: ERROR_CODES.ERR_INVALID_OPTION,
+  }, null, 2));
+  process.exit(1);
+});
+
+/**
+ * Belt-and-suspenders postAction: if a "supported" command somehow forgot
+ * to emit a JSON envelope on a code path, surface that as a structured error
+ * rather than silent stdout corruption. This should never fire in practice;
+ * if it does, it's a bug in the command implementation.
+ */
+program.hook('postAction', (thisCommand, actionCommand) => {
+  if (!program.opts().json) return;
+  if (process.__xdsJsonHandled) return;
+  const fullName = fullCommandName(actionCommand);
+  console.log(JSON.stringify({
+    apiVersion: API_VERSION,
+    error: `Internal: '${fullName}' completed without emitting a JSON envelope`,
+  }, null, 2));
+  process.exit(1);
+});
+
+/**
+ * Post-action hook: print update hint after any command output.
+ * Only fires for commands that produce output agents read (component, docs, etc.).
+ * Suppressed when --json is active to avoid contaminating stdout.
+ */
+const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
+program.hook('postAction', (thisCommand, actionCommand) => {
+  if (program.opts().json) return;
+  try {
+    if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
+      const hint = checkForUpdate();
+      if (hint) {
+        console.error(`\n${hint}`);
+      }
+    }
+  } catch {
+    // Never let update check break the CLI
+  }
+});
+
+/**
+ * Command registry — each command is lazy-loaded so a broken command
+ * doesn't take down the entire CLI.
+ */
+const commands = [
+  {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
+  {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
+  {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
+  {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
+  // agent-docs folded into init — functions still importable from agent-docs.mjs
+  {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
+  {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
+  {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
+  {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
+  {name: 'hook', path: './commands/hook/index.mjs', register: 'registerHook'},
+  {name: 'discover', path: './commands/discover.mjs', register: 'registerDiscover'},
+  {name: 'search', path: './commands/search.mjs', register: 'registerSearch'},
+  {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
+];
+
+for (const cmd of commands) {
+  try {
+    const mod = await import(cmd.path);
+    mod[cmd.register](program);
+  } catch (e) {
+    // Command fails to load but CLI still works
+    program
+      .command(cmd.name)
+      .description(`(failed to load: ${e.message})`)
+      .action(() => {
+        console.error(`Command "${cmd.name}" failed to load:`);
+        console.error(e.message);
+        process.exit(1);
+      });
+  }
+}
+
+// Capability manifest — a single, self-describing view of the whole CLI so
+// agents can discover every command, argument, flag, and response type without
+// scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
+// `xds --json` embeds the same payload under data.manifest for convenience.
+program
+  .command('manifest')
+  .description('Print the full CLI capability manifest (use with --json)')
+  .action(() => {
+    const manifest = buildManifest(program, {
+      jsonSupported: JSON_SUPPORTED,
+      version: pkg.version,
+    });
+    if (program.opts().json) {
+      process.__xdsJsonHandled = true;
+      console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest}, null, 2));
+      return;
+    }
+    // Human-readable summary. Agents should use --json.
+    console.log(`\n${manifest.name} v${manifest.version} — ${manifest.commands.length} commands\n`);
+    for (const c of manifest.commands) {
+      const tag = c.json ? ' [--json]' : '';
+      console.log(`  ${c.name}${tag}`);
+      if (c.description) console.log(`    ${c.description}`);
+    }
+    console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
+  });
+
+// Hidden command used by package.json postinstall scripts
+program
+  .command('postinstall', {hidden: true})
+  .action(() => {
+    const run = getRunPrefix();
+    const r = `${run} xds`;
+    const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
+    const W = 49; // inner width of the box
+    const line = (s) => `  │ ${pad(s, W)}│`;
+    console.log(`
+  ╭${'─'.repeat(W + 2)}╮
+${line('')}
+${line('  Design system installed!')}
+${line('')}
+${line('  Get started:')}
+${line(`    ${r} init          Interactive setup`)}
+${line(`    ${r} --help        See all commands`)}
+${line('')}
+${line('  Or run directly:')}
+${line(`    ${r} init           Setup + AI agent docs`)}
+${line(`    ${r} component     Browse component docs`)}
+${line(`    ${r} hook          Browse hook docs`)}
+${line(`    ${r} docs          Design system reference`)}
+${line(`    ${r} swizzle       Customize a component`)}
+${line(`    ${r} template      Add a page template`)}
+${line('')}
+  ╰${'─'.repeat(W + 2)}╯
+`);
+  });
+
+// Install the JSON shim AFTER all commands are registered so we can
+// patch outputHelp on every command (root + subcommands). The shim
+// extends the --json contract to cover Commander's parse-time short
+// circuits (parse errors, unknown options, --help, unknown commands).
+// See packages/cli/src/lib/json-shim.mjs for the rationale.
+installJsonShim(program);

package/src/lib/cli-error.mjs

@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Astryx CLI — central error handling helper.
+ *
+ * ## Exit-code policy
+ *
+ * The Astryx CLI follows one rule above all: **exit code is the contract**. CI
+ * scripts and AI agents read it before they read any text. Every error path
+ * across every command must agree on the exit code so that callers can
+ * detect failure without parsing stdout/stderr.
+ *
+ * Specifically:
+ *
+ *   1. **Any user-visible error → exit 1.** This includes "command not
+ *      found", "unknown subcommand", "invalid argument", "file missing",
+ *      "validation failed", and every `Error: ...` line we ever print.
+ *
+ *   2. **"Did you mean…" suggestions are still errors.** Suggestion lists
+ *      help the user recover, but the CLI still exits 1. The user asked for
+ *      something we couldn't deliver.
+ *
+ *   3. **Help-display is success.** `xds`, `xds --help`, `xds <cmd> --help`,
+ *      and `xds --version` all exit 0. The user got what they asked for.
+ *
+ *   4. **Empty / no-args invocations:** if the command has a sensible
+ *      default (e.g. `astryx component` lists all components, `astryx docs` lists
+ *      all topics), exit 0. If the command requires arguments (e.g. `xds
+ *      theme build`), Commander rejects it with exit 1.
+ *
+ *   5. **`--json` and non-`--json` agree on exit code.** The same error case
+ *      MUST exit with the same code in both modes. The shape of the message
+ *      differs (envelope vs. plain text); the exit code does not.
+ *
+ *   6. **Prefer `process.exitCode = 1; return` over `process.exit(1)`** when
+ *      the action handler is the last thing on the call stack. This lets
+ *      pending I/O (stderr buffers, postAction hooks) finish cleanly. Use
+ *      `process.exit(1)` only when an immediate halt is required.
+ *
+ * The JSON envelope shape MUST match the contract from the json.mjs module:
+ *
+ *   { apiVersion: 1, error: <string>, code: <string>, suggestions?: [...] }
+ *
+ * The `code` is a stable, machine-readable identifier (see error-codes.mjs).
+ * It is the field AI agents and CI scripts should branch on — never the
+ * human-readable `error` string, which changes freely. Human output stays
+ * clean: the code is omitted from the printed "Error: …" line and surfaces
+ * only in the JSON envelope.
+ *
+ * NEVER add ad-hoc fields. NEVER vary the shape. Consumers depend on it.
+ */
+
+import {isJsonMode, jsonError as _jsonError, humanWarn} from './json.mjs';
+import {ERROR_CODES} from './error-codes.mjs';
+
+/**
+ * Suggestion object — matches the shape used by API errors and the JSON
+ * envelope's `suggestions` field.
+ * @typedef {{name: string, reason?: string}} Suggestion
+ */
+
+/**
+ * Options for {@link cliError}.
+ * @typedef {object} CliErrorOptions
+ * @property {string} [code] - Stable machine-readable error code from
+ *   error-codes.mjs (e.g. ERR_UNKNOWN_COMPONENT). Emitted as the `code`
+ *   field of the JSON envelope. Defaults to ERR_UNKNOWN when omitted.
+ *   This is the field machine consumers branch on; the human `error`
+ *   string may change at any time.
+ * @property {Suggestion[]} [suggestions] - Optional "did you mean…" list.
+ *   Printed under the error message in human mode and serialized as the
+ *   `suggestions` field in JSON mode.
+ * @property {number} [exitCode] - Override the exit code. Defaults to 1.
+ *   Don't set this unless you have a specific reason — every error in the
+ *   CLI should exit 1.
+ * @property {boolean} [hard] - When true, call `process.exit` immediately
+ *   instead of setting `process.exitCode`. Default: true. We default to hard
+ *   exits for commands because Commander's action handlers don't always
+ *   propagate a `return` cleanly through nested awaits.
+ */
+
+/**
+ * Emit a user-visible error and stop the current command.
+ *
+ * Routes the error through the JSON envelope when `--json` is active, or to
+ * stderr otherwise. Always sets a non-zero exit code (default 1). Use this
+ * in place of every ad-hoc `console.error('Error: …'); process.exit(1)`
+ * pair across the CLI.
+ *
+ * @param {string} message - Human-readable error message. The leading
+ *   "Error: " prefix is added automatically in human mode; in JSON mode the
+ *   message is placed verbatim in the envelope's `error` field.
+ * @param {CliErrorOptions} [options]
+ * @returns {never} - Never returns; either exits the process or throws via
+ *   `jsonError` (which itself exits).
+ */
+export function cliError(message, options = {}) {
+  const {suggestions, exitCode = 1, hard = true} = options;
+  const code = options.code || ERROR_CODES.ERR_UNKNOWN;
+
+  if (isJsonMode()) {
+    // jsonError emits the envelope on stdout and calls process.exit(1).
+    // We don't honor a custom exitCode in JSON mode — the contract is exit 1.
+    // The stable `code` is carried into the envelope; the human-facing
+    // branch below intentionally omits it to keep stderr clean.
+    _jsonError(message, suggestions, code);
+    // Unreachable, but keeps the type-checker honest.
+    return /** @type {never} */ (undefined);
+  }
+
+  // Human mode: prefix "Error:" and print suggestions on subsequent lines.
+  // Use console.error directly — we always want stderr for errors regardless
+  // of the JSON-mode flag (we already handled JSON above).
+  console.error(`Error: ${message}`);
+  if (suggestions?.length) {
+    console.error('');
+    for (const s of suggestions) {
+      const tag = s.reason ? `  ${s.name}  (${s.reason})` : `  ${s.name}`;
+      console.error(tag);
+    }
+  }
+
+  if (hard) {
+    process.exit(exitCode);
+  } else {
+    process.exitCode = exitCode;
+  }
+  return /** @type {never} */ (undefined);
+}
+
+/**
+ * Clean exit. Mostly a marker for intent — `process.exit(0)` works fine,
+ * but using cliExit at success boundaries makes greps for "exit policy"
+ * sites unambiguous.
+ * @param {number} [code]
+ * @returns {never}
+ */
+export function cliExit(code = 0) {
+  process.exit(code);
+}
+
+/**
+ * Assert a condition; on failure, emit a CLI error.
+ *
+ * Convenience wrapper for the common pattern:
+ *
+ *   if (!something) { cliError('something is required'); }
+ *
+ * @param {unknown} condition - Truthy → no-op. Falsy → cliError.
+ * @param {string} message
+ * @param {CliErrorOptions} [options]
+ * @returns {asserts condition}
+ */
+export function assertOrExit(condition, message, options) {
+  if (!condition) {
+    cliError(message, options);
+  }
+}
+
+// Re-export humanWarn for callers that want a non-fatal warning channel.
+// Warnings should NOT change the exit code.
+export {humanWarn};

package/src/lib/cli-error.test.mjs

@@ -0,0 +1,199 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the central CLI error helper (`cli-error.mjs`).
+ *
+ * What we lock in here:
+ *   - cliError prints "Error: <msg>" to stderr in human mode and never
+ *     touches stdout (preserves stdout discipline).
+ *   - cliError emits the JSON envelope shape from json.mjs in JSON mode.
+ *   - assertOrExit short-circuits on falsy conditions and returns silently
+ *     on truthy ones (no side effects).
+ *   - The exit code is 1 in both modes, matching the policy.
+ *
+ * E2E exit codes for actual subcommand invocations are tested in
+ * cli-exit-codes.test.mjs.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {cliError, assertOrExit, cliExit} from './cli-error.mjs';
+import {setJsonMode, API_VERSION} from './json.mjs';
+
+describe('cliError — human mode', () => {
+  let stderr;
+  let stdout;
+  let exitCode;
+  let exitSpy;
+
+  beforeEach(() => {
+    setJsonMode(false);
+    stderr = [];
+    stdout = [];
+    exitCode = null;
+    vi.spyOn(console, 'error').mockImplementation((...a) => stderr.push(a.join(' ')));
+    vi.spyOn(console, 'log').mockImplementation((...a) => stdout.push(a.join(' ')));
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation((code) => {
+      exitCode = code ?? 0;
+      throw new Error(`__exit_${exitCode}__`);
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('prints "Error: <msg>" to stderr and exits 1', () => {
+    expect(() => cliError('something broke')).toThrow('__exit_1__');
+    expect(stderr).toContain('Error: something broke');
+    expect(stdout).toEqual([]);
+    expect(exitCode).toBe(1);
+  });
+
+  it('prints suggestions on subsequent stderr lines', () => {
+    expect(() =>
+      cliError('No component named "Buton"', {
+        suggestions: [
+          {name: 'Button', reason: 'closest match'},
+          {name: 'ButtonGroup', reason: 'related'},
+        ],
+      }),
+    ).toThrow('__exit_1__');
+    expect(stderr[0]).toBe('Error: No component named "Buton"');
+    expect(stderr).toContain('  Button  (closest match)');
+    expect(stderr).toContain('  ButtonGroup  (related)');
+  });
+
+  it('omits "(reason)" when suggestion has no reason field', () => {
+    expect(() =>
+      cliError('Unknown topic', {suggestions: [{name: 'color'}, {name: 'spacing'}]}),
+    ).toThrow('__exit_1__');
+    expect(stderr).toContain('  color');
+    expect(stderr).toContain('  spacing');
+  });
+
+  it('respects custom exitCode', () => {
+    expect(() => cliError('msg', {exitCode: 2})).toThrow('__exit_2__');
+    expect(exitCode).toBe(2);
+  });
+
+  it('uses process.exitCode when hard:false', () => {
+    const original = process.exitCode;
+    try {
+      // Should NOT throw — sets process.exitCode and returns.
+      cliError('soft', {hard: false});
+      expect(process.exitCode).toBe(1);
+      expect(exitSpy).not.toHaveBeenCalled();
+    } finally {
+      process.exitCode = original;
+    }
+  });
+});
+
+describe('cliError — JSON mode', () => {
+  let stderr;
+  let stdout;
+  let exitCode;
+
+  beforeEach(() => {
+    setJsonMode(true);
+    stderr = [];
+    stdout = [];
+    exitCode = null;
+    vi.spyOn(console, 'error').mockImplementation((...a) => stderr.push(a.join(' ')));
+    vi.spyOn(console, 'log').mockImplementation((...a) => stdout.push(a.join(' ')));
+    vi.spyOn(process, 'exit').mockImplementation((code) => {
+      exitCode = code ?? 0;
+      throw new Error(`__exit_${exitCode}__`);
+    });
+  });
+
+  afterEach(() => {
+    setJsonMode(false);
+    vi.restoreAllMocks();
+  });
+
+  it('emits a JSON envelope on stdout, nothing on stderr, and exits 1', () => {
+    expect(() => cliError('json mode error')).toThrow('__exit_1__');
+    expect(stderr).toEqual([]);
+    expect(stdout.length).toBe(1);
+    const env = JSON.parse(stdout[0]);
+    expect(env.apiVersion).toBe(API_VERSION);
+    expect(env.error).toBe('json mode error');
+    expect(env.suggestions).toBeUndefined();
+    expect(exitCode).toBe(1);
+  });
+
+  it('serializes suggestions in the envelope', () => {
+    expect(() =>
+      cliError('No component named "Buton"', {
+        suggestions: [{name: 'Button', reason: 'closest match'}],
+      }),
+    ).toThrow('__exit_1__');
+    const env = JSON.parse(stdout[0]);
+    expect(env.suggestions).toEqual([{name: 'Button', reason: 'closest match'}]);
+  });
+
+  it('always exits 1 in JSON mode (custom exitCode is ignored — contract)', () => {
+    expect(() => cliError('msg', {exitCode: 2})).toThrow('__exit_1__');
+    expect(exitCode).toBe(1);
+  });
+});
+
+describe('assertOrExit', () => {
+  let exitCalled;
+
+  beforeEach(() => {
+    setJsonMode(false);
+    exitCalled = false;
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(process, 'exit').mockImplementation(() => {
+      exitCalled = true;
+      throw new Error('__exit__');
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('is a no-op for truthy conditions', () => {
+    expect(() => assertOrExit(true, 'should not fire')).not.toThrow();
+    expect(() => assertOrExit('non-empty', 'should not fire')).not.toThrow();
+    expect(() => assertOrExit(1, 'should not fire')).not.toThrow();
+    expect(exitCalled).toBe(false);
+  });
+
+  it('triggers cliError for falsy conditions', () => {
+    expect(() => assertOrExit(false, 'must be true')).toThrow('__exit__');
+    expect(exitCalled).toBe(true);
+  });
+
+  it('triggers cliError for null/undefined', () => {
+    expect(() => assertOrExit(null, 'nope')).toThrow('__exit__');
+    expect(exitCalled).toBe(true);
+  });
+});
+
+describe('cliExit', () => {
+  it('calls process.exit with given code', () => {
+    let called = null;
+    vi.spyOn(process, 'exit').mockImplementation((code) => {
+      called = code;
+      throw new Error('__exit__');
+    });
+    expect(() => cliExit(0)).toThrow('__exit__');
+    expect(called).toBe(0);
+    vi.restoreAllMocks();
+  });
+
+  it('defaults to exit code 0', () => {
+    let called = null;
+    vi.spyOn(process, 'exit').mockImplementation((code) => {
+      called = code;
+      throw new Error('__exit__');
+    });
+    expect(() => cliExit()).toThrow('__exit__');
+    expect(called).toBe(0);
+    vi.restoreAllMocks();
+  });
+});