@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/host/index.d.ts

@@ -0,0 +1,116 @@
+// 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>;

package/host/index.mjs

@@ -0,0 +1,295 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `@astryxdesign/cli/host`, the programmatic host entry (spec AST-081
+ * FR1). A tool that carries this CLI starts one run of it with explicit
+ * inputs: the arguments, the working folder, the command name its users type,
+ * and, when it found the project's own CLI and did not run it, the reason.
+ *
+ * Its package sets, the integrations it approves, and its own discover sources
+ * are matched, loaded, and recorded as architecture:cli-surface INV30 says; a
+ * hosted run installs nothing. 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.
+ *
+ * @input `runHostedCli` options (see host/index.d.ts for the contract).
+ * @output The run's exit status and the packages it resolved, each with its
+ *   source. The run owns the process's working folder, arguments, standard
+ *   streams, and exit, exactly as a run of the `astryx` bin does: every path
+ *   on which the bin exits the process exits it here too (host/index.d.ts
+ *   lists them).
+ * @position host — the package's `./host` export; calls clients/cli/run.mjs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const CLI_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+const BIN = path.join(CLI_ROOT, 'clients', 'cli', 'bin', 'astryx.mjs');
+
+/**
+ * The process, seen as the holder of one mark: whether a hosted run started in
+ * it, whichever copy of the CLI started it.
+ */
+const processMarks = /** @type {{__astryxHostRunStarted?: boolean}} */ (
+  /** @type {unknown} */ (process)
+);
+
+/** The longest reason a host may give for not running the project's CLI. */
+const MAX_REASON_LENGTH = 120;
+
+const OPTION_NAMES = new Set([
+  'argv',
+  'cwd',
+  'cliCommand',
+  'declinedProjectCli',
+  'roots',
+  'integrations',
+  'discoverSources',
+]);
+
+/** A bare npm package name, scoped or not. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+
+/**
+ * @param {string} message
+ * @returns {TypeError}
+ */
+function invalid(message) {
+  return new TypeError(`runHostedCli: ${message}`);
+}
+
+/**
+ * Check every input before anything runs.
+ * @param {unknown} options
+ * @returns {Promise<{argv: string[], cwd: string, cliCommand: string | undefined, declinedProjectCli: string | undefined, roots: string[], integrations: string[], discoverSources: Function[]}>}
+ */
+async function readOptions(options) {
+  if (options === undefined) options = {};
+  if (
+    options === null ||
+    typeof options !== 'object' ||
+    Array.isArray(options)
+  ) {
+    throw invalid('options must be an object');
+  }
+  const record = /** @type {Record<string, unknown>} */ (options);
+  for (const key of Object.keys(record)) {
+    if (!OPTION_NAMES.has(key)) {
+      throw invalid(
+        `unknown option "${key}"; the options are ${[...OPTION_NAMES].join(', ')}`,
+      );
+    }
+  }
+
+  const argv = record.argv ?? [];
+  if (!Array.isArray(argv) || !argv.every(arg => typeof arg === 'string')) {
+    throw invalid('argv must be an array of strings');
+  }
+
+  const cwdInput = record.cwd ?? process.cwd();
+  if (typeof cwdInput !== 'string' || cwdInput === '') {
+    throw invalid('cwd must be a folder path');
+  }
+  const cwd = path.resolve(cwdInput);
+  let isFolder = false;
+  try {
+    isFolder = fs.statSync(cwd).isDirectory();
+  } catch {
+    isFolder = false;
+  }
+  if (!isFolder) throw invalid(`cwd is not a folder: ${cwd}`);
+
+  let cliCommand;
+  if (record.cliCommand !== undefined) {
+    const {parseCliCommandField} =
+      await import('../authoring/integration/schema.mjs');
+    try {
+      cliCommand = parseCliCommandField(record.cliCommand, 'cliCommand');
+    } catch (err) {
+      throw invalid(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  const declinedProjectCli = record.declinedProjectCli;
+  if (
+    declinedProjectCli !== undefined &&
+    (typeof declinedProjectCli !== 'string' ||
+      declinedProjectCli === '' ||
+      declinedProjectCli !== declinedProjectCli.trim() ||
+      /[\r\n]/u.test(declinedProjectCli) ||
+      declinedProjectCli.length > MAX_REASON_LENGTH)
+  ) {
+    throw invalid(
+      `declinedProjectCli must be a non-blank single line of at most ${MAX_REASON_LENGTH} characters, with no surrounding spaces`,
+    );
+  }
+
+  const rootsInput = record.roots ?? [];
+  if (
+    !Array.isArray(rootsInput) ||
+    !rootsInput.every(root => typeof root === 'string' && root !== '')
+  ) {
+    throw invalid('roots must be an array of folder paths');
+  }
+  /** @type {string[]} */
+  const roots = [];
+  for (const root of rootsInput) {
+    const folder = path.resolve(root);
+    let isRoot = false;
+    try {
+      isRoot = fs.statSync(folder).isDirectory();
+    } catch {
+      isRoot = false;
+    }
+    if (!isRoot) {
+      throw invalid(`roots names a path that is not a folder: ${folder}`);
+    }
+    if (!roots.includes(folder)) roots.push(folder);
+  }
+
+  const integrations = record.integrations ?? [];
+  if (
+    !Array.isArray(integrations) ||
+    !integrations.every(
+      name => typeof name === 'string' && PACKAGE_NAME.test(name),
+    )
+  ) {
+    throw invalid('integrations must be an array of package names');
+  }
+
+  const discoverSources = record.discoverSources ?? [];
+  if (
+    !Array.isArray(discoverSources) ||
+    !discoverSources.every(source => typeof source === 'function')
+  ) {
+    throw invalid('discoverSources must be an array of functions');
+  }
+
+  return {
+    argv: [...argv],
+    cwd,
+    cliCommand,
+    declinedProjectCli: /** @type {string | undefined} */ (declinedProjectCli),
+    roots,
+    integrations: [...new Set(/** @type {string[]} */ (integrations))],
+    discoverSources: [...discoverSources],
+  };
+}
+
+/**
+ * The bin's Node version gate, for a host process: same message, same exit
+ * status, same JSON envelope.
+ * @param {string[]} argv
+ * @returns {Promise<boolean>} whether the run may go on
+ */
+async function nodeVersionGate(argv) {
+  const {isNodeVersionSupported, unsupportedNodeMessage} =
+    await import('../foundation/env/node-version.mjs');
+  if (isNodeVersionSupported(process.versions.node)) return true;
+  const msg = unsupportedNodeMessage(process.versions.node);
+  if (argv.includes('--json')) {
+    process.stdout.write(
+      `${JSON.stringify({apiVersion: 1, error: msg, code: 'ERR_NODE_VERSION'}, null, 2)}\n`,
+    );
+  } else {
+    process.stderr.write(`${msg}\n`);
+  }
+  process.exitCode = 1;
+  return false;
+}
+
+/**
+ * Load another release's host entry, from one of the host's package sets, to
+ * hand this run over to in this process (architecture:cli-surface INV30). The
+ * run stays one call of the host's: the one-call mark passes to the entry that
+ * answers, and the call settles with that entry's result.
+ * @param {string} hostEntry the package set's `host/index.mjs`
+ * @returns {Promise<(options: import('./index.js').HostedCliOptions) => Promise<import('./index.js').HostedCliResult>>}
+ */
+async function loadHostEntry(hostEntry) {
+  const entry = await import(pathToFileURL(hostEntry).href);
+  if (typeof entry.runHostedCli !== 'function') {
+    throw new Error(`${hostEntry} exports no runHostedCli`);
+  }
+  return options => {
+    processMarks.__astryxHostRunStarted = false;
+    return entry.runHostedCli(options);
+  };
+}
+
+/**
+ * Run the CLI once in this process, as the `astryx` bin would run with the
+ * same arguments in the same folder, for a tool that carries this CLI.
+ *
+ * @param {import('./index.js').HostedCliOptions} [options]
+ * @returns {Promise<import('./index.js').HostedCliResult>}
+ */
+export async function runHostedCli(options) {
+  const input = await readOptions(options);
+  if (processMarks.__astryxHostRunStarted) {
+    throw new Error(
+      'runHostedCli: a run already started in this process; start each run in a new process',
+    );
+  }
+  processMarks.__astryxHostRunStarted = true;
+
+  process.chdir(input.cwd);
+  process.argv = [process.argv[0] ?? process.execPath, BIN, ...input.argv];
+  if (!(await nodeVersionGate(input.argv))) return {status: 1, packages: []};
+
+  const {installPlaceOf, projectRootOf} =
+    await import('../foundation/release/choose.mjs');
+  const {readReleaseFacts} = await import('../foundation/release/project.mjs');
+  const {activateHostedRun, recordResolved, resolvedPackages} =
+    await import('../foundation/runtime/package-root.mjs');
+  const real = fs.realpathSync(CLI_ROOT);
+  let projectRoot = null;
+  try {
+    projectRoot = projectRootOf(readReleaseFacts(input.cwd));
+  } catch {
+    projectRoot = null;
+  }
+  activateHostedRun({
+    roots: input.roots,
+    integrations: input.integrations,
+    discoverSources: input.discoverSources,
+    // The root that holds this CLI, or, for a CLI that is not installed in a
+    // node_modules folder, the folder beside it that holds its Core.
+    startingRoot: installPlaceOf(real).owner ?? path.dirname(real),
+    projectRoot,
+    loadHostEntry,
+  });
+  recordResolved(
+    '@astryxdesign/cli',
+    JSON.parse(fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'))
+      .version,
+    CLI_ROOT,
+  );
+
+  const {runCli} = await import('../clients/cli/run.mjs');
+  const run = () =>
+    runCli({
+      cliRoot: CLI_ROOT,
+      argv: [...input.argv],
+      declinedProjectCli: input.declinedProjectCli,
+    });
+  let answered;
+  if (input.cliCommand === undefined) {
+    answered = await run();
+  } else {
+    const {runWithCliDoor} = await import('../foundation/env/cli-command.mjs');
+    answered = await runWithCliDoor(input.cliCommand, run);
+  }
+  // Another package set's host entry answered the run (INV30).
+  if (answered) return answered;
+  const code = process.exitCode;
+  return {
+    status: typeof code === 'number' ? code : Number(code ?? 0) || 0,
+    packages: resolvedPackages(),
+  };
+}