@astryxdesign/cli 0.2.0 → 0.3.0

package/lib/json-shim.mjs

@@ -1,326 +0,0 @@
-// 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 = [];
-  /** @type {import('commander').Command | null} */
-  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) => !(/** @type {any} */ (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 {import('../types/base').Suggestion[]} [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) {
-  // Commander instances are monkeypatched at runtime with an internal
-  // `__xdsHelpPatched` marker and a replacement `outputHelp`, neither of which
-  // is in commander's public types — treat the instance as untyped here.
-  const anyCmd = /** @type {any} */ (cmd);
-  if (anyCmd.__xdsHelpPatched) return;
-  anyCmd.__xdsHelpPatched = true;
-  const original = cmd.outputHelp.bind(cmd);
-  anyCmd.outputHelp = function patchedOutputHelp(/** @type {any} */ 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(/** @type {any} */ 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/lib/json-shim.test.mjs

@@ -1,209 +0,0 @@
-// 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 {runCli} from '../test-utils/run-cli.mjs';
-
-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', async () => {
-    const {status, stdout, stderr} = await 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', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout} = await 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)', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout} = await 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', async () => {
-    const {status, stdout, stderr} = await 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)', async () => {
-    const {status} = await runCli(['docs', 'color', '--lang', 'zh']);
-    expect(status).toBe(0);
-  });
-
-  it('astryx docs color --lang en is accepted (exit 0)', async () => {
-    const {status} = await 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', async () => {
-    const {status, stdout, stderr} = await 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', async () => {
-    const {status, stdout, stderr} = await 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', async () => {
-    const {status, stdout, stderr} = await 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', async () => {
-    const {status, stdout, stderr} = await 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', async () => {
-    const {status, stdout, stderr} = await 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)', async () => {
-    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} = await runCli(args);
-      expect(stderr, `stderr should be empty for: ${args.join(' ')}`).toBe('');
-    }
-  });
-});

package/lib/json.mjs

@@ -1,147 +0,0 @@
-// 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 JSON response envelope and mark it handled.
- *
- * Structural serializer: pass a command/API result straight through as
- * `{type, data, meta?}`. There is no central response union — the correctness
- * of the `type` discriminator is guaranteed at each API function's `@returns`
- * (that's the fractal source-of-truth point), not by a map in this file.
- *
- * @param {{type: string, data: unknown, meta?: Record<string, unknown>}} response
- * @returns {void}
- */
-export function jsonOut(response) {
-  process.__xdsJsonHandled = true;
-  /** @type {any} */
-  const envelope = {apiVersion: API_VERSION, type: response.type, data: response.data};
-  if (response.meta !== undefined) envelope.meta = response.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 {import('../types/base').Suggestion[]} [suggestions]
- * @param {string} [code] - Explicit stable error code. Overrides any code
- *   carried on a thrown Error.
- * @returns {{apiVersion: number, error: string, code: string, suggestions?: import('../types/base').Suggestion[]}}
- */
-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 {import('../types/base').Suggestion[]} [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);
-}