Skip to content

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

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

/**
 * @file The first thing every run does: choose the release that answers and,
 * when it is not this copy, hand the run to it (spec AST-081 FR2, FR6, FR9).
 *
 * Runs in the bin right after the Node version gate, before the CLI loads
 * the folder's `astryx.config`, its integrations, or its Core. A hand-off
 * starts the chosen CLI with exactly this run's arguments, working folder, and
 * standard streams, adds nothing to its environment, options, or
 * configuration, and ends this process with that CLI's exit status. The
 * chosen copy makes the same choice and finds itself, so a run is handed off
 * at most once.
 *
 * In text mode a run that a copy other than the project's own CLI answers
 * prints one line on standard error naming the CLI and Core that answered; a
 * run with `--json` prints none and carries `meta.answeredBy` instead. After a
 * successful command, the copy that started the run prints any update notice
 * (notices.mjs); a global copy also starts the daily update check, which
 * installs nothing (global-state.mjs).
 *
 * A programmatic host that found the project's own CLI and did not run it
 * passes the reason (spec AST-081 FR1, FR2). That run is never handed to the
 * project's CLI: this copy answers in its place when it is that CLI's release,
 * saying so in a line of its own; a package set of the host's whose CLI is
 * that release answers through its own host entry; and otherwise this copy
 * answers as for a release that cannot be obtained, with the warning naming
 * the reason.
 *
 * A hosted run installs nothing (architecture:cli-surface INV30): a release
 * other than this copy comes only from the first of the host's package sets
 * that qualifies. When that CLI ships a host entry, the entry runs in this
 * process with the same inputs, discover sources included, and the host's
 * call settles with its result; otherwise its bin takes the run. With no such
 * set, this copy answers, announced.
 *
 * @input  the running copy, argv, the working folder, and a host's
 *   declined-project-CLI reason
 * @output returns when this copy answers, or with another release's result
 *   when its host entry answered; never returns after a hand-off to a bin
 * @position foundation/release — called once per run by clients/cli/run.mjs.
 */

import {spawn} from 'node:child_process';
import {writeSync} from 'node:fs';
import {
  chooseRelease,
  isComputerLevel,
  isGlobalCopy,
  namesWhoAnswered,
  packageRootOf,
  projectRootOf,
  runningCopy,
} from './choose.mjs';
import {readReleaseFacts} from './project.mjs';
import {ensureRelease, userCacheDir} from './cache.mjs';
import {
  maybeFetchCore,
  maybeKeepAgentText,
  maybeStartCheck,
} from './global-state.mjs';
import {recordRunChoice} from './run-context.mjs';
import {noticeLines} from './notices.mjs';
import {cliDoor, runWithCliDoor} from '../env/cli-command.mjs';
import {hostedRun} from '../runtime/package-root.mjs';
import {qualifyingRoot} from '../runtime/package-set.mjs';

/** Where each release's notes are published. */

/**
 * The who-answered line for a run a copy other than the project's own CLI
 * answers.
 * @param {import('./choose.mjs').ReleaseChoice} choice
 * @param {boolean} [computer] the command acts on the computer, not the folder
 * @returns {string}
 */
export function whoAnsweredLine(choice, computer = false) {
  const core = choice.coreVersion ?? choice.version;
  if (computer) {
    return `astryx: answered by CLI ${choice.version} with Core ${core}, for this computer`;
  }
  return choice.copy === 'matched'
    ? `astryx: answered by CLI ${choice.version} with Core ${core}, the release that matches this project's Core`
    : `astryx: answered by CLI ${choice.version} with Core ${core}, outside a project`;
}

/**
 * The line for a run this copy answers in place of the project's own CLI,
 * which a host declined, when this copy is that CLI's release (FR2).
 * @param {string} version
 * @param {string} reason the reason, as {@link declinedReasonText} words it
 * @returns {string}
 */
export function inPlaceOfProjectLine(version, reason) {
  return `astryx: answered by CLI ${version}, the release of this project's CLI, in its place (${reason})`;
}

/**
 * The line for a run handed to the project's own CLI.
 * @param {string} projectVersion
 * @param {string} startedIn the version of the copy the run started in
 * @returns {string}
 */
export function handedToProjectLine(projectVersion, startedIn) {
  return `astryx: answered by this project's CLI ${projectVersion}, handed over from CLI ${startedIn}`;
}

/**
 * One line on standard error while a release installs, so a slow download
 * never looks like a hang. Text mode only.
 * @param {'install' | 'wait'} event
 * @param {string} version
 */
export function progressLine(event, version) {
  console.error(progressText(event, version));
}

/**
 * The text of {@link progressLine}.
 * @param {'install' | 'wait'} event
 * @param {string} version
 * @returns {string}
 */
export function progressText(event, version) {
  return event === 'install'
    ? `astryx: installing CLI release ${version} into the per-user cache (once)...`
    : `astryx: waiting for another run to finish installing CLI release ${version}...`;
}

/**
 * The warning a run prints, in text mode, when the release that matches the
 * project's Core cannot be obtained and the copy that answered before global
 * mode answers instead (spec AST-081 FR2).
 * @param {string} wanted the matched release, or the range it was read from
 * @param {string} reason why it cannot be obtained
 * @param {string} answering the version that answers instead
 * @returns {string}
 */
export function fallbackLine(wanted, reason, answering) {
  return `astryx: could not get Astryx ${wanted} to match this project's Core (${reason}); answering with CLI ${answering} instead`;
}

/**
 * Fail the run before any command starts, in the shape every command fails
 * in: the JSON error envelope on stdout with `--json`, else `Error: …` on
 * standard error. Exit status 1.
 * @param {string} message
 * @param {boolean} json
 * @returns {never}
 */
function failUnavailable(message, json) {
  if (json) {
    process.stdout.write(
      `${JSON.stringify(
        {apiVersion: 1, error: message, code: 'ERR_VERSIONS_UNAVAILABLE'},
        null,
        2,
      )}\n`,
    );
  } else {
    console.error(`Error: ${message}`);
  }
  process.exit(1);
}

/**
 * The fallback warning's reason for a project CLI a host declined.
 * @param {string} reason the host's own words
 * @returns {string}
 */
export function declinedReasonText(reason) {
  return `project CLI skipped: ${reason}`;
}

/**
 * Choose who answers and hand off when it is not this copy.
 * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
 *   argv after `node astryx`; the reason a programmatic host declined the
 *   project's own CLI, when it did
 * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
 *   resolves with nothing when this copy answers, and with that release's
 *   result when another package set's host entry answered a hosted run
 */
export async function startRun({cliRoot, argv, declinedProjectCli}) {
  const json = argv.includes('--json');
  const self = runningCopy(cliRoot);
  const cacheDir = userCacheDir();
  // A host carries its own CLI and keeps it current itself: a hosted copy
  // runs none of the global copy's background work, and installs nothing.
  const hosted = hostedRun();
  const global = !hosted && isGlobalCopy(cliRoot, cacheDir);
  if (global) {
    try {
      maybeStartCheck();
    } catch {
      // A check that cannot start never fails a run.
    }
    try {
      // The global copy keeps the computer-level agent text on its own
      // release's text, so it follows each upgrade of the copy (FR8).
      maybeKeepAgentText({release: self});
    } catch {
      // Nor does the agent text.
    }
    // And its own Core, so component reads work offline outside a project
    // after one online run (FR3). Started as the run ends, so it never takes
    // the install lock from this run's own Core read, nor holds anything the
    // command's caller waits on while the command runs.
    process.once('exit', () => {
      try {
        maybeFetchCore({release: self, cacheDir});
      } catch {
        // Nor does the Core download.
      }
    });
  }

  const computer = isComputerLevel(argv);
  /** @type {import('./choose.mjs').ReleaseChoice} */
  let choice;
  try {
    choice = chooseRelease({
      cwd: process.cwd(),
      self,
      cacheDir,
      computer,
    });
  } catch {
    choice = {
      copy: 'carried',
      answer: 'self',
      version: self.version,
      bin: null,
      coreVersion: null,
      inProject: false,
      unavailable: null,
    };
  }

  // A host declined the project's own CLI (FR2): the run is never handed to
  // it. The release equal to that CLI's version answers in its place when
  // this copy is that release, or when a package set of the host's holds it
  // with a host entry; otherwise this copy answers, announced as for a release
  // that cannot be obtained, naming the reason.
  let declined = null;
  /** Set when this copy answers in place of the declined CLI, its release. */
  let inPlace = null;
  if (
    declinedProjectCli &&
    choice.copy === 'project' &&
    choice.answer !== 'self'
  ) {
    if (choice.version === self.version) {
      // Still the project CLI's release (`copy` stays `project`), never the
      // release matched to the project's Core, which can be another.
      choice = {...choice, answer: 'self', bin: null, unavailable: null};
      inPlace = declinedReasonText(declinedProjectCli);
    } else {
      const served = hosted
        ? qualifyingRoot({
            release: choice.version,
            projectDir: projectDirOf(process.cwd()),
            roots: hosted.roots,
            needsHostEntry: true,
          })
        : null;
      if (served && 'root' in served && served.hostEntry) {
        const answered = await answerInPackageSet(
          served.hostEntry,
          served.root,
          {argv, declinedProjectCli},
        );
        if (answered) return answered;
      }
      declined = declinedReasonText(declinedProjectCli);
    }
  }

  if (!declined && choice.unavailable && choice.copy === 'project') {
    failUnavailable(
      `This project's CLI ${choice.version} could not be started: ${choice.unavailable}. Reinstall the project's dependencies.`,
      json,
    );
  }

  // A host's door holds only inside the call that set it; notices print as
  // the process exits, outside it, so the door this run started under is
  // kept and set again for them (FR5).
  const door = cliDoor();
  /** FR10: after a successful command, at most once a day per notice. */
  const notify = () => {
    const print = () => {
      for (const line of noticeLines({
        cwd: process.cwd(),
        self,
        choice: computer ? {...choice, inProject: false} : choice,
        json,
        cacheDir,
      })) {
        // Synchronous: the process is exiting.
        writeSync(2, `${line}\n`);
      }
    };
    try {
      if (door) runWithCliDoor(door, print);
      else print();
    } catch {
      // A notice never fails a run.
    }
  };
  /**
   * The matched release cannot be obtained: the copy that started the run
   * answers instead, as before global mode, announced (FR2).
   * @param {string} reason
   * @returns {Promise<void>}
   */
  const fallBack = async reason => {
    recordRunChoice({
      ...choice,
      copy: 'fallback',
      answer: 'self',
      version: self.version,
      bin: null,
      coreVersion: null,
      unavailable: null,
    });
    if (!json) {
      console.error(fallbackLine(choice.version, reason, self.version));
    }
    process.once('exit', code => {
      if (code === 0) notify();
    });
  };

  if (declined) {
    await fallBack(declined);
    return;
  }

  if (choice.unavailable) {
    await fallBack(choice.unavailable);
    return;
  }

  if (choice.answer === 'self') {
    recordRunChoice(choice);
    // A project with no CLI of its own is answered as released, with no
    // line; a hint after the command, once a day, says how to match it.
    if (!json && (choice.copy === 'matched' || choice.copy === 'carried'))
      console.error(whoAnsweredLine(choice, computer));
    else if (!json && inPlace)
      console.error(inPlaceOfProjectLine(choice.version, inPlace));
    process.once('exit', code => {
      if (code === 0) notify();
    });
    return;
  }

  let bin = choice.bin;
  if (!bin && hosted) {
    const served = qualifyingRoot({
      release: choice.version,
      projectDir: projectDirOf(process.cwd()),
      roots: hosted.roots,
    });
    if (!('root' in served)) {
      await fallBack(served.reason);
      return;
    }
    if (served.hostEntry) {
      const answered = await answerInPackageSet(served.hostEntry, served.root, {
        argv,
      });
      if (answered) return answered;
    }
    // A hosted run installs nothing (INV30): a set whose CLI starts through
    // neither its host entry nor a bin leaves this copy to answer.
    if (!served.bin) {
      await fallBack(
        `the CLI ${choice.version} in the package set at ${served.root} could not be started`,
      );
      return;
    }
    bin = served.bin;
  }
  if (!bin) {
    const release = ensureRelease(choice.version, {
      cacheDir,
      onProgress: json ? undefined : progressLine,
    });
    if (!('bin' in release)) {
      await fallBack(release.reason);
      return;
    }
    bin = release.bin;
  }

  if (!json) {
    if (choice.copy === 'project') {
      console.error(handedToProjectLine(choice.version, self.version));
    } else if (!namesWhoAnswered(packageRootOf(bin))) {
      console.error(whoAnsweredLine(choice, computer));
    }
  }

  await handOff(bin, argv, choice, json, notify);
}

/**
 * How long a hand-off waits after an interrupt before passing it on to a CLI
 * that is still running. An interrupt sent to the whole process group (a
 * terminal's Ctrl-C, a process manager) already reached that CLI, and one that
 * stops within this time is never interrupted twice; one sent to this process
 * alone (an agent's `kill('SIGINT')`) stops the run once it is passed on.
 */
export const INTERRUPT_GRACE_MS = 5000;

/**
 * The project folder a run in `cwd` belongs to, or null outside a project.
 * @param {string} cwd
 * @returns {string | null}
 */
function projectDirOf(cwd) {
  try {
    return projectRootOf(readReleaseFacts(cwd));
  } catch {
    return null;
  }
}

/**
 * Hand a hosted run over to the CLI of one of the host's package sets,
 * through that CLI's own host entry, in this process, with the inputs this run
 * got: the arguments, the folder, the command name, the approved integrations,
 * the discover sources, and the reason the host declined the project's CLI.
 * Its roots are that package set alone. That CLI prints its own who-answered
 * line and notices, and the host's call settles with its result.
 * @param {string} hostEntry the package set's `host/index.mjs`
 * @param {string} root the package set
 * @param {{argv: string[], declinedProjectCli?: string}} run
 * @returns {Promise<import('../../host/index.js').HostedCliResult | null>} null
 *   when the entry cannot be loaded, before anything ran
 */
async function answerInPackageSet(hostEntry, root, {argv, declinedProjectCli}) {
  const hosted = hostedRun();
  if (!hosted?.loadHostEntry) return null;
  let answer;
  try {
    answer = await hosted.loadHostEntry(hostEntry);
  } catch {
    return null;
  }
  const door = cliDoor();
  return answer({
    argv,
    cwd: process.cwd(),
    roots: [root],
    integrations: [...hosted.integrations],
    discoverSources: [...hosted.discoverSources],
    ...(door ? {cliCommand: door} : {}),
    ...(declinedProjectCli ? {declinedProjectCli} : {}),
  });
}

/**
 * Run `bin` as this run and end with its exit status.
 * @param {string} bin
 * @param {string[]} argv
 * @param {import('./choose.mjs').ReleaseChoice} choice
 * @param {boolean} json
 * @param {() => void} [notify] prints update notices after a successful run
 * @returns {Promise<never>}
 */
function handOff(bin, argv, choice, json, notify = () => {}) {
  return new Promise(() => {
    const child = spawn(process.execPath, [bin, ...argv], {
      stdio: 'inherit',
      windowsHide: false,
    });
    /** @param {NodeJS.Signals} signal */
    const forward = signal => {
      try {
        child.kill(signal);
      } catch {
        // The child is already gone.
      }
    };
    const running = () => child.exitCode === null && child.signalCode === null;
    // An interrupt is passed on only to a CLI still running after the grace
    // (see INTERRUPT_GRACE_MS): one sent to this process alone then stops the
    // run, and one the whole process group got is not delivered twice to a CLI
    // that stops in time. On Windows, Ctrl-C reaches every process in the
    // console and a forwarded SIGINT would end the child abruptly, so this
    // process only outlives it.
    const onInterrupt = () => {
      if (process.platform === 'win32' || !running()) return;
      setTimeout(() => {
        if (running()) forward('SIGINT');
      }, INTERRUPT_GRACE_MS).unref();
    };
    process.on('SIGINT', onInterrupt);
    process.on('SIGTERM', forward);
    process.on('SIGHUP', forward);
    child.on('error', error => {
      failUnavailable(
        choice.copy === 'project'
          ? `This project's CLI ${choice.version} could not be started: ${error.message}. Reinstall the project's dependencies.`
          : `CLI release ${choice.version} could not be started: ${error.message}.`,
        json,
      );
    });
    child.on('exit', (code, signal) => {
      process.off('SIGINT', onInterrupt);
      process.off('SIGTERM', forward);
      process.off('SIGHUP', forward);
      if (signal) {
        process.kill(process.pid, signal);
        return;
      }
      if (code === 0) notify();
      process.exit(code ?? 1);
    });
  });
}