@astryxdesign/cli 0.2.0 → 0.3.0

package/clients/cli/index.mjs

@@ -0,0 +1,468 @@
+// 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.
+ *
+ * The program is built by {@link createProgram} — a factory so tests can drive
+ * a FRESH program in-process (via parseAsync) instead of spawning `node
+ * bin/astryx.mjs` per assertion. `bin/astryx.mjs` and legacy importers use the
+ * eager {@link program} singleton, which is just `await createProgram()`.
+ */
+
+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 './lib/update-check.mjs';
+import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';
+import {buildManifest} from './lib/manifest.mjs';
+import {cliError} from './lib/cli-error.mjs';
+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 {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.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. (Bin-time only: guarded on argv,
+// so importing this module in tests is a no-op.)
+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);
+}
+
+/**
+ * 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',
+  'blog',
+  'discover',
+  'search',
+  'build',
+  'swizzle',
+  'template',
+  'hook',
+  'theme build',
+  'theme list',
+  'theme add',
+  'upgrade',
+  'manifest',
+  'doctor',
+  'validate-integration',
+  'layout expand',
+  'layout check',
+  'layout grammar',
+]);
+
+/**
+ * Compute the fully qualified command name, e.g. "theme build" or "swizzle".
+ * @param {import('commander').Command} actionCommand
+ * @param {import('commander').Command} root the root program
+ * @returns {string}
+ */
+function fullCommandName(actionCommand, root) {
+  const parts = [];
+  /** @type {import('commander').Command | null} */
+  let cmd = actionCommand;
+  while (cmd && cmd !== root) {
+    parts.unshift(cmd.name());
+    cmd = cmd.parent;
+  }
+  return parts.join(' ');
+}
+
+/**
+ * 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: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
+  {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: '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: '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: 'build', path: './commands/build.mjs', register: 'registerBuild'},
+  {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
+  {
+    name: 'validate-integration',
+    path: './commands/validate-integration.mjs',
+    register: 'registerValidateIntegration',
+  },
+];
+
+const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
+const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+
+/**
+ * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
+ * commands, manifest/postinstall, json-shim). Async because commands are
+ * lazy-imported. Each call returns an independent Command so tests can
+ * parseAsync repeatedly without commander state leaking between runs.
+ *
+ * @returns {Promise<import('commander').Command>}
+ */
+export async function createProgram() {
+  const program = new Command();
+
+  // Deterministic, single-line help. Commander wraps each option/command
+  // description to a column width (80 when captured non-TTY), which splits long
+  // descriptions like --json across several indented lines. Override `wrap` to a
+  // no-op so every item stays on one line — matching the rest of the CLI's
+  // plain, unwrapped, width-independent output. Set before subcommands are
+  // registered so they inherit it via copyInheritedSettings.
+  program.configureHelp({wrap: (str) => str});
+
+  // Document the text-output contract in --help so agents know how to parse/grep
+  // it (and when to reach for --json instead). Kept in sync with the formatter
+  // kit in clients/cli/formatters.
+  program.addHelpText(
+    'after',
+    '\n' +
+      [
+        section(
+          'Output format',
+          'Text mirrors --json (the machine-readable surface); it is built from these blocks:',
+        ),
+        records(
+          [
+            {
+              block: 'Record',
+              shape: 'aligned "key: value" lines = one item; records separated by a blank line',
+            },
+            {
+              block: 'Section',
+              shape: 'a header line (no "key:"), optional one-line subtitle, then its records/list',
+            },
+            {block: 'List', shape: '"- value" lines for a simple sequence of values'},
+            {block: 'Text', shape: 'free-form prose / notes'},
+            {block: 'Code', shape: 'a verbatim block (source, skeleton, or doc), emitted exactly'},
+          ],
+          {fields: ['block', 'shape']},
+        ),
+        text(
+          'Grep a field across records, e.g.  astryx search button | grep "^command:". ' +
+            'Errors/warnings go to stderr; use --json for structured parsing.',
+        ),
+      ]
+        .map(block => block.toString())
+        .join('\n\n'),
+  );
+
+  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) => !(/** @type {any} */ (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();
+    });
+
+  /**
+   * 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 interactive 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, program);
+    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, program);
+    console.log(JSON.stringify({
+      apiVersion: API_VERSION,
+      error: `Internal: '${fullName}' completed without emitting a JSON envelope`,
+      // `code` always appears on an error envelope so consumers can branch on
+      // it unconditionally. This belt-and-suspenders path is an internal
+      // condition, so it uses the generic ERR_UNKNOWN.
+      code: ERROR_CODES.ERR_UNKNOWN,
+    }, 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.
+   */
+  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
+    }
+  });
+
+  /**
+   * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
+   * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
+   * the user/agent that setup is missing.
+   *
+   * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
+   * ones whose action errors or calls process.exit (postAction is skipped then).
+   *
+   * Suppressed in --json: that is machine output with a strict clean stdout+stderr
+   * contract (json-shim.test: "error envelopes have empty stderr"), and --json
+   * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
+   * The core/cli postinstall layers already nudge at install time regardless of
+   * --json; a machine-readable nudge could later be an envelope field. Also skipped
+   * for the installer commands themselves and outside a project (no package.json).
+   */
+  program.hook('preAction', (thisCommand, actionCommand) => {
+    try {
+      if (program.opts().json) return; // machine mode — keep --json output clean
+      if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
+      const cwd = process.cwd();
+      if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+      if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
+      // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
+      // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
+      // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.
+      console.error(
+        `\nNext step: run \`${getCliInvocation(cwd)} init\` to finish setup and install the Astryx agent prompt.`,
+      );
+    } catch {
+      // Never let the nudge break a command.
+    }
+  });
+
+  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: ${/** @type {any} */ (e).message})`)
+        .action(() => {
+          console.error(`Command "${cmd.name}" failed to load:`);
+          console.error(/** @type {any} */ (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.
+  // Intentionally CLI-special — no `api/manifest`. It introspects the live
+  // Commander `program`, so extracting it to `api/` would create the `api → cli`
+  // cycle from #4302. `buildManifest(program)` lives in lib/; see its header.
+  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 as greppable records (agents should use --json).
+      // One record per command: name, whether it supports --json, and the
+      // description.
+      emit(
+        section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
+        records(
+          manifest.commands.map(c => ({
+            command: c.name,
+            json: c.json ? 'yes' : '',
+            description: c.description || '',
+          })),
+          {fields: ['command', 'json', 'description']},
+        ),
+        text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
+      );
+    });
+
+  // Hidden command used by package.json postinstall scripts
+  program
+    .command('postinstall', {hidden: true})
+    .action(() => {
+      const r = getCliInvocation();
+      const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
+      const W = 49; // inner width of the box
+      const line = (/** @type {string} */ s) => `  │ ${pad(s, W)}│`;
+      console.log(`
+  ╭${'─'.repeat(W + 2)}╮
+${line('')}
+${line('  Design system installed!')}
+${line('')}
+${line('  Get started:')}
+${line(`    ${r} init          Setup + AI agent docs`)}
+${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/lib/json-shim.mjs for the rationale.
+  installJsonShim(program);
+
+  return program;
+}
+
+/**
+ * Eager singleton program for `bin/astryx.mjs` and legacy importers. Tests
+ * should call {@link createProgram} to get an isolated instance.
+ */
+export const program = await createProgram();

package/clients/cli/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 '../../../foundation/response/json.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+
+/**
+ * Suggestion object — matches the shape used by API errors and the JSON
+ * envelope's `suggestions` field. Canonical definition lives in types/base.
+ * @typedef {import('../../../foundation/response/base').Suggestion} 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};