Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
7.3 KB
Raw Blame
// 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, package?, data, meta? }
 *      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, isErrorCode} from './error-codes.mjs';
import {recordEnvelope, setOutcome} from '../debug/index.mjs';
import {answeredBy} from '../release/run-context.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, package?, 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. `package` names the npm package that owns the one thing the result is
 * about (spec cli-surface INV28); it is written directly after `type`.
 *
 * @param {{type: string, package?: string, data: unknown, meta?: Record<string, unknown>}} response
 * @returns {void}
 */
export function jsonOut(response) {
  /** @type {any} */
  const envelope = {apiVersion: API_VERSION, type: response.type};
  if (response.package !== undefined) envelope.package = response.package;
  envelope.data = response.data;
  // Every successful result names the release that answered (spec AST-081
  // FR5): the CLI, the Core it paired with, and which copy it was.
  envelope.meta = {...(response.meta ?? {}), answeredBy: answeredBy()};
  // Serialize BEFORE marking handled. If JSON.stringify throws (a circular
  // reference or a BigInt in `data` — an author bug in a command's return
  // value), the `__xdsJsonHandled` flag must stay unset so the bin error
  // boundary is still free to emit a JSON error envelope. Setting the flag
  // first leaves a --json consumer with empty stdout + exit 1 (an unparseable
  // non-envelope), violating the "every --json emission is a single valid
  // envelope" contract.
  const out = JSON.stringify(envelope, null, 2);
  process.__xdsJsonHandled = true;
  recordEnvelope(response.type);
  console.log(out);
}

/**
 * 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. Only a registered code (error-codes.mjs) is
 * taken from either source, so a Node system error's `ENOENT` never reaches
 * the envelope. It always appears on the envelope so consumers can branch on
 * it unconditionally.
 *
 * @param {unknown} err
 * @param {import('./base').Suggestion[]} [suggestions]
 * @param {string} [code] - Explicit stable error code. Overrides any code
 *   carried on a thrown Error.
 * @param {Record<string, unknown>} [receipt] - What the failed command had
 *   already done, for a command that changes files before it can fail.
 *   Overrides a `receipt` carried on a thrown Error. Additive: the envelope
 *   is still an error with its `code`.
 * @returns {{apiVersion: number, error: string, code: string, suggestions?: import('./base').Suggestion[], receipt?: Record<string, unknown>}}
 */
export function toErrorEnvelope(err, suggestions, code, receipt) {
  const message =
    err instanceof Error ? err.message : typeof err === 'string' ? err : String(err);
  const carried =
    err && typeof err === 'object' ? /** @type {any} */ (err).code : undefined;
  const resolvedCode = [code, carried].find(isErrorCode) ?? ERROR_CODES.ERR_UNKNOWN;
  /** @type {any} */
  const env = {apiVersion: API_VERSION, error: message, code: resolvedCode};
  if (Array.isArray(suggestions) && suggestions.length) env.suggestions = suggestions;
  const carriedReceipt =
    err && typeof err === 'object' ? /** @type {any} */ (err).receipt : undefined;
  const resolvedReceipt = receipt ?? carriedReceipt;
  if (resolvedReceipt && typeof resolvedReceipt === 'object') {
    env.receipt = resolvedReceipt;
  }
  return env;
}

/**
 * Output a structured JSON error and exit.
 * @param {string} message
 * @param {import('./base').Suggestion[]} [suggestions]
 * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
 * @param {Record<string, unknown>} [receipt] - What the command had already
 *   done before it failed (see toErrorEnvelope).
 */
export function jsonError(message, suggestions, code, receipt) {
  process.__xdsJsonHandled = true;
  const err = toErrorEnvelope(message, suggestions, code, receipt);
  // No-op when cliError already classified this failure — first outcome wins.
  setOutcome('error', {exitCode: 1, error: new Error(message), code: err.code});
  console.log(JSON.stringify(err, null, 2));
  process.exit(1);
}