Skip to content

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

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

/**
 * `@astryxdesign/cli/host`: the programmatic host entry. A tool that carries
 * this CLI starts one run of it per process with explicit inputs
 * (`spec:AST-081` FR1).
 */

import type {DiscoverSource} from '../authoring/discover/type.js';

/** The inputs of one hosted run. Every option is optional. */
export interface HostedCliOptions {
  /** The arguments after `astryx`. Default: none. */
  argv?: readonly string[];
  /**
   * The working folder of the run. The run changes the process's working
   * folder to it, finds its project there, and writes where the command
   * writes from there. Default: the process's working folder.
   */
  cwd?: string;
  /**
   * The command the tool's users type to run the CLI, such as
   * `acme astryx`. Printed commands start with it unless the integrations
   * the run loads declare their own. A non-blank single line of at most 120
   * characters, with no surrounding spaces and no Astryx agent-docs marker
   * text. Default: none; printed commands use the package manager's name.
   */
  cliCommand?: string;
  /**
   * When the tool found the project's own CLI and did not run it, why, in the
   * tool's own words, such as `cannot-start` or `untrusted`: a non-blank
   * single line of at most 120 characters, with no surrounding spaces. The
   * run is then never handed to that CLI: its release answers in its place
   * when this copy, or a package set's host entry, is that release;
   * otherwise this copy answers with one warning line naming the reason and
   * `meta.answeredBy.copy` set to `fallback`. Default: none; a project's own
   * CLI answers its project.
   */
  declinedProjectCli?: string;
  /**
   * The tool's package sets, in its order of preference: folders whose
   * `node_modules` each hold a CLI, the Core equal to it, and the
   * integrations installed with them. Inside a project, a set fills only the
   * `@astryxdesign/*` packages the project leaves uninstalled that are not
   * integrations. When a release other than this copy answers the folder,
   * the first set whose CLI and Core are that release and that holds what the
   * project would install for those packages serves the run. A run never
   * installs a release: with no such set, this copy answers with one warning
   * line. Default: none.
   */
  roots?: readonly string[];
  /**
   * Integrations the tool approves for use outside a project, by package
   * name. Each loads from the package set that serves the run, as an
   * integration installed for the computer does, and a name that set does not
   * hold is left out. Default: none.
   */
  integrations?: readonly string[];
  /**
   * The tool's own discover sources. `astryx discover` calls them after every
   * integration's source and before the official list, and reports each as
   * the host's. Another package set's host entry that answers the run gets
   * them too; a run handed to a CLI's bin does not. Default: none.
   */
  discoverSources?: readonly DiscoverSource[];
}

/** One package a hosted run resolved. */
export interface HostedPackage {
  /** The package name. */
  name: string;
  /** Its version, or null when its package.json gives none. */
  version: string | null;
  /** Whether it came from the project or from a package set. */
  source: 'project' | 'package-set';
}

/**
 * The outcome of a hosted run that returned: this copy's, or, when another
 * package set's release answered through its own host entry, that entry's.
 */
export interface HostedCliResult {
  /** The run's exit status, as the `astryx` bin would exit. */
  status: number;
  /** Each package the run resolved: the CLI, its Core, and its integrations. */
  packages: HostedPackage[];
}

/**
 * Run the CLI once in this process, as the `astryx` bin would with the same
 * arguments in the same folder.
 *
 * The run owns the process's working folder, arguments, standard streams,
 * and exit. The call settles when the command returns. Like the bin, the run
 * instead ends the process, with the exit status the bin would exit with, and
 * the call never settles, when it:
 * - prints help or the version (`--help`, `-h`, `help`, `--version`, `-V`,
 *   `--version --json`), with status 0;
 * - rejects the command line, such as an unknown command or option;
 * - reports an error it stops on, including every error in `--json` mode;
 * - meets an unexpected error, with status 1;
 * - hands the run to another CLI's bin: the project's own CLI when
 *   `declinedProjectCli` is absent, or a package set whose CLI ships no host
 *   entry.
 *
 * When another package set's release answers through its own host entry,
 * that entry runs in this process with the same inputs, and the call settles
 * with its result.
 *
 * Rejects with a `TypeError`, before anything runs, for an unknown option or
 * an invalid value; and with an `Error`, before anything runs, when a run has
 * already started in this process.
 */
export declare function runHostedCli(
  options?: HostedCliOptions,
): Promise<HostedCliResult>;