Skip to content

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

TypeScript
4.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * Shared types for the Astryx CLI JSON API.
 *
 * `CLIError` and `CLIUnsupportedError` are the two error shapes. Success
 * responses are the structural `{ type, data, meta? }` envelope (`CLIResponse`)
 * — there is NO central union of every response. Each command's precise
 * response type is the source of truth at its own function; import the
 * per-command type, or use `ReturnType<typeof fn>`, when you need it.
 */

import type {ErrorCode} from './error-codes';

/**
 * A "did you mean…" suggestion attached to an error. `reason` is optional:
 * some call sites emit bare `{name}` (e.g. a list of candidate component names)
 * with no per-item explanation.
 */
export interface Suggestion {
  name: string;
  reason?: string;
}

/**
 * Structured error. Check `'error' in result` to discriminate.
 *
 * Branch on `code` (a stable machine-readable identifier), never on the
 * human-readable `error` string, which changes freely.
 */
export interface CLIError {
  /** Version of the JSON envelope contract, as on the success envelope. */
  apiVersion: number;
  error: string;
  code: ErrorCode;
  suggestions?: Suggestion[];
  /**
   * What the command had already done when it failed, present only on errors
   * from a command that changes files before it can fail (for example the
   * `upgrade.run` data of a failed `astryx upgrade`). The error is still an
   * error: branch on `code`.
   */
  receipt?: Record<string, unknown>;
}

/** Returned by the fallback hook for commands without --json support. */
export interface CLIUnsupportedError {
  apiVersion: number;
  error: `JSON output is not supported for the '${string}' command`;
  code: ErrorCode;
}

/**
 * A success response: a `type` discriminator, the `package` that owns what the
 * response is about, its `data` payload, and an optional `meta` object
 * (emitted as a sibling of `data`, never merged in) that carries
 * `answeredBy` and fields such as `deprecations`. `--json` prints it with
 * `apiVersion` added (see `parseResponse`).
 *
 * `package` is present when the response is about one thing: one component,
 * one doc, one template. A response that lists things from more than one
 * package leaves it out, and each listed item names its own `package`.
 *
 * Structural by design — there is no central union of every response `type`.
 * A specific command narrows `data` via its own return type.
 */
/**
 * Which copy of the CLI answered a run (spec AST-081 FR5): carried in `meta`
 * on every successful machine-readable result of a release that has it.
 * - `project`: the project's own CLI.
 * - `starting`: the copy that started the run, in a project with no CLI of
 *   its own.
 * - `matched`: the release equal to the project's Core, when the project's
 *   own CLI cannot start, from the per-user cache or the copy that started
 *   the run.
 * - `carried`: outside a project, the copy that started the run, with the Core
 *   it carries.
 * - `fallback`: the matched release could not be obtained, so the copy that
 *   started the run answered instead.
 */
export interface AnsweredBy {
  /** The answering CLI's version. */
  cli: string;
  /** The Core the run pairs with, or `null` when there is none. */
  core: string | null;
  copy: 'project' | 'starting' | 'matched' | 'carried' | 'fallback';
}

export interface CLIResponse {
  type: string;
  package?: string;
  data: unknown;
  meta?: {answeredBy?: AnsweredBy} & Record<string, unknown>;
}

/** Wrap any response type to include possible error shapes. */
export type CLIResult<T> = T | CLIError | CLIUnsupportedError;

/**
 * Output a JSON response envelope. Structural serializer — the correctness of
 * the `type` discriminator is guaranteed at each API function's return type,
 * not by a central map here.
 */
export function jsonOut(response: CLIResponse): void;

/**
 * Output a structured JSON error and exit.
 */
export function jsonError(
  message: string,
  suggestions?: Suggestion[],
  code?: ErrorCode,
): never;

/** Parse raw CLI output (string or object) into a typed result. */
export function parseResponse(
  raw: unknown,
): (CLIResponse & {apiVersion: number}) | CLIError | CLIUnsupportedError;

/** Type guard: returns true if result is an error. */
export function isError(
  result: unknown,
): result is CLIError | CLIUnsupportedError;

/**
 * Assert a specific response type. Throws on error or type mismatch. Narrows
 * the returned `type` to the expected literal; `data` stays `unknown` — import
 * the per-command response type when you need a precise payload.
 */
export function assertResponse<T extends string>(
  raw: unknown,
  type: T,
): CLIResponse & {apiVersion: number; type: T};

declare global {
  namespace NodeJS {
    interface Process {
      __xdsJsonHandled?: boolean;
    }
  }
}