@astryxdesign/cli 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/src/lib/json-shim.mjs

@@ -0,0 +1,321 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Commander shim that extends the --json contract to cover
+ * Commander's parse-time short-circuits (parse errors, unknown options,
+ * --help display, unknown subcommands).
+ *
+ * Background: PR #2467 set up the --json envelope and a `preAction` gate.
+ * That works for the normal command-execution path, but Commander's own
+ * error and help paths run BEFORE preAction:
+ *
+ *   - Missing required argument / unknown option → `_displayError`
+ *     writes "error: ..." to stderr and calls `_exit(1)` synchronously.
+ *   - `--help` → `outputHelp()` writes raw "Usage:" text to stdout
+ *     and calls `_exit(0)`.
+ *
+ * Neither path emits the JSON envelope, and neither throws (so the
+ * try/catch in `bin/astryx.mjs` never sees them). The result: a --json
+ * consumer receives empty stdout + raw stderr, breaking the contract.
+ *
+ * The shim closes the gap by:
+ *   1. Calling `exitOverride()` so Commander throws CommanderError
+ *      instead of calling `process.exit` synchronously.
+ *   2. Routing those errors through a single handler that emits a
+ *      JSON error envelope when --json is in argv.
+ *   3. Overriding each command's `outputHelp` so --help emits a
+ *      structured JSON help envelope (instead of raw text) when
+ *      --json is set.
+ *   4. Routing unknown-subcommand attempts through the same error
+ *      envelope path (so `astryx bogus-cmd --json` gets exit 1 + envelope
+ *      instead of exit 0 + help envelope).
+ *
+ * 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 './json.mjs';
+import {ERROR_CODES} from './error-codes.mjs';
+
+/**
+ * Cheap argv check used before preAction has had a chance to engage
+ * `setJsonMode`. We can't rely on `program.opts().json` here because
+ * Commander throws during parse — opts may not be populated yet.
+ * @returns {boolean}
+ */
+function argvHasJson() {
+  return process.argv.slice(2).includes('--json');
+}
+
+/** @returns {boolean} */
+function jsonActive() {
+  return isJsonMode() || argvHasJson();
+}
+
+/**
+ * Build a structured JSON help envelope for a given Commander command.
+ * Mirrors the existing root help envelope shape, but works for any
+ * subcommand (e.g. `astryx component --help --json`).
+ *
+ * @param {import('commander').Command} cmd
+ * @returns {{apiVersion: number, type: 'help', data: object}}
+ */
+export function buildHelpEnvelope(cmd) {
+  // Reconstruct the fully-qualified command name (e.g. "astryx theme build").
+  const nameParts = [];
+  let c = cmd;
+  while (c) {
+    nameParts.unshift(c.name());
+    c = c.parent;
+  }
+
+  /** @type {Array<{flags: string, description: string, defaultValue?: unknown, choices?: string[]}>} */
+  const options = cmd.options.map((o) => {
+    /** @type {any} */
+    const opt = {flags: o.flags, description: o.description || ''};
+    if (o.defaultValue !== undefined) opt.defaultValue = o.defaultValue;
+    if (Array.isArray(o.argChoices) && o.argChoices.length) opt.choices = o.argChoices;
+    return opt;
+  });
+
+  const subcommands = cmd.commands
+    .filter((s) => !s._hidden)
+    .map((s) => ({name: s.name(), description: s.description() || ''}));
+
+  return {
+    apiVersion: API_VERSION,
+    type: 'help',
+    data: {
+      command: nameParts.join(' '),
+      description: cmd.description() || '',
+      usage: `${nameParts.join(' ')} ${cmd.usage()}`.trim(),
+      options,
+      subcommands,
+    },
+  };
+}
+
+/**
+ * Emit a JSON error envelope to stdout (the JSON contract uses stdout
+ * for both success and error).
+ *
+ * @param {string} message
+ * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
+ */
+function emitJsonError(message, suggestions, code) {
+  if (process.__xdsJsonHandled) return;
+  process.__xdsJsonHandled = true;
+  const env = toErrorEnvelope(message, suggestions, code);
+  process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
+}
+
+/**
+ * Map a Commander parse-error code (and its message) to a stable Astryx error
+ * code. Commander's own codes are stable enough, but they aren't part of our
+ * documented contract — so we translate them into the `ERR_*` taxonomy.
+ *
+ * The `--lang` / `--detail` choice violations both arrive as
+ * `commander.invalidArgument`; we disambiguate on the option name in the
+ * message so consumers get the precise ERR_INVALID_LANG / ERR_INVALID_DETAIL.
+ *
+ * @param {string} commanderCode - e.g. 'commander.unknownOption'
+ * @param {string} message
+ * @returns {string}
+ */
+function commanderCodeToErrorCode(commanderCode, message) {
+  switch (commanderCode) {
+    case 'commander.unknownCommand':
+      return ERROR_CODES.ERR_UNKNOWN_COMMAND;
+    case 'commander.unknownOption':
+      return ERROR_CODES.ERR_INVALID_OPTION;
+    case 'commander.missingArgument':
+    case 'commander.missingMandatoryOptionValue':
+      return ERROR_CODES.ERR_MISSING_ARGUMENT;
+    case 'commander.excessArguments':
+      return ERROR_CODES.ERR_INVALID_ARGUMENT;
+    case 'commander.invalidArgument':
+    case 'commander.invalidOptionArgument': {
+      if (/--lang\b/.test(message)) return ERROR_CODES.ERR_INVALID_LANG;
+      if (/--detail\b/.test(message)) return ERROR_CODES.ERR_INVALID_DETAIL;
+      return ERROR_CODES.ERR_INVALID_ARGUMENT;
+    }
+    default:
+      return ERROR_CODES.ERR_UNKNOWN;
+  }
+}
+
+/**
+ * Install the shim on a Commander program. Idempotent — safe to call
+ * once at program-construction time.
+ *
+ * @param {import('commander').Command} program
+ */
+export function installJsonShim(program) {
+  // exitOverride() and configureOutput() do NOT auto-cascade to
+  // subcommands that were registered BEFORE the shim runs (Commander
+  // copies these settings from parent at command-creation time, not
+  // at parse time). So we walk the whole tree and apply them
+  // explicitly to every node.
+  applyShimRecursively(program);
+
+  // Don't tack the help text onto error output. We render help
+  // ourselves (or as JSON) and don't want Commander's stderr help dump
+  // interleaving with our error envelope.
+  program.showHelpAfterError(false);
+
+  // Patch outputHelp on every command (root + subcommands) so
+  // `--help` emits a JSON envelope when --json is active. Commander
+  // creates subcommands lazily, so wrap recursively + patch any
+  // new ones added later by walking after registration.
+  patchHelpRecursively(program);
+}
+
+/**
+ * Apply exitOverride and JSON-aware configureOutput to a command and
+ * all of its descendants. We do this recursively because Commander
+ * only copies these settings to children created AFTER the parent is
+ * configured — and our subcommands were already registered by the
+ * time installJsonShim runs.
+ *
+ * @param {import('commander').Command} cmd
+ */
+function applyShimRecursively(cmd) {
+  cmd.exitOverride();
+  cmd.configureOutput({
+    writeOut: (str) => process.stdout.write(str),
+    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;
+      process.stderr.write(str);
+    },
+  });
+  for (const sub of cmd.commands) {
+    applyShimRecursively(sub);
+  }
+}
+
+/**
+ * Walk the command tree and override outputHelp on every command so that
+ * `--help --json` emits a structured help envelope instead of raw text.
+ *
+ * @param {import('commander').Command} cmd
+ */
+function patchHelpRecursively(cmd) {
+  patchOutputHelp(cmd);
+  for (const sub of cmd.commands) {
+    patchHelpRecursively(sub);
+  }
+  // If new subcommands are added later (via commands.push or
+  // .command(...)), patch them on first .help()/--help. Commander
+  // doesn't fire an event for command registration, so we hook into
+  // Command.prototype here (one-time, idempotent).
+  if (!Command_outputHelp_patched) {
+    patchPrototype(cmd.constructor);
+    Command_outputHelp_patched = true;
+  }
+}
+
+let Command_outputHelp_patched = false;
+
+/**
+ * Replace outputHelp on a single Command instance.
+ * @param {import('commander').Command} cmd
+ */
+function patchOutputHelp(cmd) {
+  if (cmd.__xdsHelpPatched) return;
+  cmd.__xdsHelpPatched = true;
+  const original = cmd.outputHelp.bind(cmd);
+  cmd.outputHelp = function patchedOutputHelp(contextOptions) {
+    if (jsonActive()) {
+      if (!process.__xdsJsonHandled) {
+        process.__xdsJsonHandled = true;
+        const env = buildHelpEnvelope(cmd);
+        process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
+      }
+      return;
+    }
+    return original(contextOptions);
+  };
+}
+
+/**
+ * Patch Command.prototype so that any subcommand created after install
+ * also gets the JSON help override. Belt-and-suspenders for late-bound
+ * commands.
+ * @param {Function} CommandCtor
+ */
+function patchPrototype(CommandCtor) {
+  const proto = CommandCtor.prototype;
+  if (proto.__xdsHelpPatched) return;
+  proto.__xdsHelpPatched = true;
+  const original = proto.outputHelp;
+  proto.outputHelp = function patchedProtoOutputHelp(contextOptions) {
+    if (jsonActive()) {
+      if (!process.__xdsJsonHandled) {
+        process.__xdsJsonHandled = true;
+        const env = buildHelpEnvelope(this);
+        process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
+      }
+      return;
+    }
+    return original.call(this, contextOptions);
+  };
+}
+
+/**
+ * Convert a CommanderError thrown during parse into either a JSON
+ * envelope (under --json) or the legacy stderr behavior, then exit
+ * with the right code.
+ *
+ * Codes we care about (Commander 14):
+ *   commander.helpDisplayed       — `--help` was used (exit 0)
+ *   commander.help                — same family (exit 0)
+ *   commander.version             — `--version` was used (exit 0)
+ *   commander.unknownCommand      — `astryx bogus-cmd`
+ *   commander.unknownOption       — `--bogus-flag`
+ *   commander.missingArgument     — `astryx theme build` (no <file>)
+ *   commander.invalidArgument     — bad value for argParser
+ *   commander.invalidOptionArgument
+ *   commander.excessArguments
+ *
+ * @param {unknown} err
+ * @returns {boolean} true if handled (caller should not re-throw)
+ */
+export function handleCommanderError(err) {
+  if (!err || typeof err !== 'object' || !('code' in err)) return false;
+  const code = /** @type {{code?: string, exitCode?: number, message?: string}} */ (err).code;
+  if (typeof code !== 'string' || !code.startsWith('commander.')) return false;
+
+  const exitCode = /** @type {{exitCode?: number}} */ (err).exitCode ?? 1;
+  const message = /** @type {{message?: string}} */ (err).message ?? '';
+
+  // Help / version success paths — Commander already wrote the output
+  // (via our patched outputHelp for help; via its own writer for version,
+  // which we handle separately in index.mjs argv preflight). Just exit
+  // with the right code.
+  if (
+    code === 'commander.helpDisplayed' ||
+    code === 'commander.help' ||
+    code === 'commander.version'
+  ) {
+    process.exit(exitCode);
+  }
+
+  // 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 {
+    // 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/src/lib/json-shim.test.mjs

@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration tests for the JSON shim — extends the --json
+ * contract to cover Commander's parse-time short-circuits.
+ *
+ * Spawns the CLI as a real subprocess so Commander hooks, exitOverride,
+ * and process.exit fire end-to-end. Asserts:
+ *
+ *   1. `--help --json` (root + subcommand) emits a JSON help envelope,
+ *      not raw "Usage:" text. Exit 0.
+ *   2. Parse errors (missing required arg, unknown option) emit a
+ *      JSON error envelope on stdout. Exit 1.
+ *   3. Unknown subcommand produces an error envelope (not a help
+ *      envelope with exit 0).
+ *   4. Invalid `--detail` choice produces a single error envelope
+ *      (not error then help).
+ *   5. Non-`--json` invocations still print to stderr and exit 1
+ *      exactly as before — no regression.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+function runCli(args) {
+  const res = spawnSync('node', [CLI_BIN, ...args], {
+    encoding: 'utf-8',
+    timeout: 20_000,
+  });
+  return {
+    status: res.status,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+  };
+}
+
+function parseJson(stdout) {
+  return JSON.parse(stdout);
+}
+
+describe('--json shim: --help renders JSON envelope', () => {
+  it('astryx --help --json emits a help envelope (not raw text), exit 0', () => {
+    const {status, stdout, stderr} = runCli(['--help', '--json']);
+    expect(status).toBe(0);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data).toBeDefined();
+    expect(parsed.data.command).toBe('astryx');
+    // Should list known subcommands
+    const subNames = parsed.data.subcommands.map((s) => s.name);
+    expect(subNames).toContain('component');
+    expect(subNames).toContain('theme');
+  });
+
+  it('astryx component --help --json emits a subcommand help envelope', () => {
+    const {status, stdout} = runCli(['component', '--help', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.command).toBe('astryx component');
+    // Should expose its options
+    const flags = parsed.data.options.map((o) => o.flags);
+    expect(flags).toContain('--list');
+  });
+
+  it('astryx theme build --help --json emits a nested subcommand help envelope', () => {
+    const {status, stdout} = runCli(['theme', 'build', '--help', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.command).toBe('astryx theme build');
+    expect(parsed.data.usage).toMatch(/<file>/);
+  });
+});
+
+describe('--json shim: parse errors emit JSON error envelope', () => {
+  it('astryx theme build --json (missing required arg) emits error envelope, exit 1', () => {
+    const {status, stdout} = runCli(['theme', 'build', '--json']);
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.error).toMatch(/missing required argument/i);
+    expect(parsed.error).toMatch(/file/i);
+  });
+
+  it('astryx --bogus-flag --json (unknown option) emits error envelope, exit 1', () => {
+    const {status, stdout} = runCli(['--bogus-flag', '--json']);
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.error).toMatch(/unknown option/i);
+    expect(parsed.error).toMatch(/--bogus-flag/);
+  });
+
+  it('astryx component --json --bogus-flag (unknown option on subcmd) emits error envelope, exit 1', () => {
+    const {status, stdout} = runCli(['component', '--json', '--bogus-flag']);
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.error).toMatch(/unknown option/i);
+  });
+});
+
+describe('--json shim: unknown subcommand emits error envelope', () => {
+  it('astryx bogus-cmd --json emits error envelope, exit 1 (not exit 0 + help)', () => {
+    const {status, stdout} = runCli(['bogus-cmd', '--json']);
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.error).toMatch(/unknown command/i);
+    expect(parsed.error).toMatch(/bogus-cmd/);
+    // Suggestions should list known commands
+    expect(Array.isArray(parsed.suggestions)).toBe(true);
+    const names = parsed.suggestions.map((s) => s.name);
+    expect(names).toContain('component');
+  });
+});
+
+describe('--json shim: invalid --detail choice', () => {
+  it('astryx --detail bogus --json emits a single error envelope, exit 1', () => {
+    const {status, stdout} = runCli(['--detail', 'bogus', '--json']);
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.error).toMatch(/--detail/);
+    expect(parsed.error).toMatch(/invalid|allowed/i);
+    // Single emission only — stdout must be exactly one JSON document.
+    // (parseJson would have thrown if there were two concatenated docs.)
+    // Belt-and-suspenders: count opening braces at column 0.
+    const topLevelBraces = stdout.split('\n').filter((l) => l === '{').length;
+    expect(topLevelBraces).toBe(1);
+  });
+});
+
+describe('--json shim: invalid --lang choice', () => {
+  it('astryx docs color --lang fr --json emits a single error envelope, exit 1', () => {
+    const {status, stdout} = runCli(['docs', 'color', '--lang', 'fr', '--json']);
+    expect(status).toBe(1);
+    const parsed = parseJson(stdout);
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.error).toMatch(/--lang/);
+    expect(parsed.error).toMatch(/invalid|allowed/i);
+    // Single emission only — stdout must be exactly one JSON document.
+    const topLevelBraces = stdout.split('\n').filter((l) => l === '{').length;
+    expect(topLevelBraces).toBe(1);
+  });
+
+  it('astryx docs color --lang fr (no --json) writes to stderr and exits 1', () => {
+    const {status, stdout, stderr} = runCli(['docs', 'color', '--lang', 'fr']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/--lang/);
+  });
+
+  it('astryx docs color --lang zh is accepted (exit 0)', () => {
+    const {status} = runCli(['docs', 'color', '--lang', 'zh']);
+    expect(status).toBe(0);
+  });
+
+  it('astryx docs color --lang en is accepted (exit 0)', () => {
+    const {status} = runCli(['docs', 'color', '--lang', 'en']);
+    expect(status).toBe(0);
+  });
+});
+
+describe('--json shim: non-JSON behavior is preserved', () => {
+  it('astryx theme build (no --json, missing arg) writes to stderr and exits 1', () => {
+    const {status, stdout, stderr} = runCli(['theme', 'build']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/missing required argument/i);
+  });
+
+  it('astryx --bogus-flag (no --json) writes to stderr and exits 1', () => {
+    const {status, stdout, stderr} = runCli(['--bogus-flag']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/unknown option/i);
+  });
+
+  it('astryx bogus-cmd (no --json) writes to stderr and exits 1', () => {
+    const {status, stdout, stderr} = runCli(['bogus-cmd']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/unknown command/i);
+  });
+
+  it('astryx --detail bogus (no --json) writes to stderr and exits 1', () => {
+    const {status, stdout, stderr} = runCli(['--detail', 'bogus']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/--detail/);
+  });
+
+  it('astryx --help (no --json) writes raw help text to stdout, exit 0', () => {
+    const {status, stdout, stderr} = runCli(['--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^Usage: astryx/);
+    expect(stderr).toBe('');
+  });
+});
+
+describe('--json shim: stdout discipline under --json', () => {
+  it('all error envelopes have empty stderr (no leak of legacy "error: ..." line)', () => {
+    const cases = [
+      ['theme', 'build', '--json'],
+      ['--bogus-flag', '--json'],
+      ['bogus-cmd', '--json'],
+      ['--detail', 'bogus', '--json'],
+      ['docs', 'color', '--lang', 'fr', '--json'],
+    ];
+    for (const args of cases) {
+      const {stderr} = runCli(args);
+      expect(stderr, `stderr should be empty for: ${args.join(' ')}`).toBe('');
+    }
+  });
+});

package/src/lib/json.mjs

@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Internal JSON output helpers and the CLI's "JSON is always JSON"
+ * contract.
+ *
+ * The contract has four guarantees, enforced here and in index.mjs:
+ *
+ *   1. EVERY emission in --json mode is a single valid JSON envelope.
+ *      Success: { apiVersion, type, data }
+ *      Error:   { apiVersion, error, code, suggestions? }
+ *      The `code` is a stable, machine-readable identifier (see
+ *      error-codes.mjs). Consumers should branch on `code`, never on the
+ *      human-readable `error` string.
+ *   2. Commands that don't support --json are rejected BEFORE any side
+ *      effect (preAction gate in index.mjs).
+ *   3. Human-facing chatter is suppressed in --json mode (see humanLog /
+ *      setJsonMode) so it can never corrupt stdout.
+ *   4. Uncaught throws in --json mode become a JSON error envelope, never a
+ *      raw stack trace (see toErrorEnvelope / the bin error boundary).
+ *
+ * Commands call jsonOut(type, data) for success and jsonError(msg) for
+ * errors. Consumer-facing utilities (parseResponse, isError, assertResponse)
+ * live in parse.mjs and are exported via @astryxdesign/cli/json.
+ */
+
+/**
+ * Version of the JSON envelope contract. Bump on breaking shape changes so
+ * consumers can negotiate. Exposed on every envelope as `apiVersion`.
+ */
+import {ERROR_CODES} from './error-codes.mjs';
+
+export const API_VERSION = 1;
+
+/**
+ * Process-wide flag: are we emitting machine-readable JSON? Set once, early,
+ * from the parsed --json option (see setJsonMode in index.mjs). Read by
+ * humanLog() so human output is suppressed without every call site having to
+ * thread a `json` boolean.
+ *
+ * @type {boolean}
+ */
+let _jsonMode = false;
+
+/**
+ * Enable/disable JSON mode globally. Called once from index.mjs as soon as
+ * the root options are known (preAction), before any command body runs.
+ * @param {boolean} on
+ */
+export function setJsonMode(on) {
+  _jsonMode = Boolean(on);
+}
+
+/** @returns {boolean} */
+export function isJsonMode() {
+  return _jsonMode;
+}
+
+/**
+ * Human-facing output that is automatically suppressed in --json mode.
+ *
+ * This is the stdout-discipline primitive: instead of scattering
+ * `if (!json) console.log(...)` across commands (easy to forget, and one
+ * miss corrupts the JSON), route all human chatter through humanLog. In JSON
+ * mode it is a no-op, guaranteeing stdout carries only the JSON envelope.
+ *
+ * @param {...unknown} args
+ */
+export function humanLog(...args) {
+  if (_jsonMode) return;
+  console.log(...args);
+}
+
+/**
+ * Human-facing stderr (warnings, hints). Also suppressed in JSON mode so a
+ * stray warning can't interleave with piped output. Use jsonError for real
+ * errors that must reach a JSON consumer.
+ * @param {...unknown} args
+ */
+export function humanWarn(...args) {
+  if (_jsonMode) return;
+  console.error(...args);
+}
+
+/**
+ * Output a typed JSON response envelope and mark as handled.
+ * Type safety enforced via declaration in types/base.d.ts —
+ * data must match the declared shape for the given type discriminator.
+ * @template {import('../types/base').CLIResponseType} T
+ * @param {T} type
+ * @param {import('../types/base').CLIResponseDataMap[T]} data
+ * @param {Record<string, unknown>} [meta] - Optional sidecar metadata (e.g.
+ *   {configured: false}). Emitted as a sibling of data, never merged into it.
+ * @returns {void}
+ */
+export function jsonOut(type, data, meta) {
+  process.__xdsJsonHandled = true;
+  /** @type {any} */
+  const envelope = {apiVersion: API_VERSION, type, data};
+  if (meta !== undefined) envelope.meta = meta;
+  console.log(JSON.stringify(envelope, null, 2));
+}
+
+/**
+ * Build a structured error envelope without emitting it. Used by the bin
+ * error boundary to convert an uncaught throw into the contract's error
+ * shape.
+ *
+ * The `code` is resolved in priority order: an explicit `code` argument,
+ * then a `code` property carried on a thrown Error/AstryxError, then the
+ * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
+ * consumers can branch on it unconditionally.
+ *
+ * @param {unknown} err
+ * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {string} [code] - Explicit stable error code. Overrides any code
+ *   carried on a thrown Error.
+ * @returns {{apiVersion: number, error: string, code: string, suggestions?: Array<{name: string, reason: string}>}}
+ */
+export function toErrorEnvelope(err, suggestions, code) {
+  const message =
+    err instanceof Error ? err.message : typeof err === 'string' ? err : String(err);
+  const resolvedCode =
+    code ||
+    (err && typeof err === 'object' &&
+    typeof (/** @type {any} */ (err).code) === 'string'
+      ? /** @type {any} */ (err).code
+      : undefined) ||
+    ERROR_CODES.ERR_UNKNOWN;
+  /** @type {any} */
+  const env = {apiVersion: API_VERSION, error: message, code: resolvedCode};
+  if (suggestions?.length) env.suggestions = suggestions;
+  return env;
+}
+
+/**
+ * Output a structured JSON error and exit.
+ * @param {string} message
+ * @param {Array<{name: string, reason: string}>} [suggestions]
+ * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
+ */
+export function jsonError(message, suggestions, code) {
+  process.__xdsJsonHandled = true;
+  const err = toErrorEnvelope(message, suggestions, code);
+  console.log(JSON.stringify(err, null, 2));
+  process.exit(1);
+}