@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/foundation/release/handoff.mjs

@@ -0,0 +1,524 @@
+// 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);
+    });
+  });
+}

package/foundation/release/lock-lease.d.mts

@@ -0,0 +1,23 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Renew the holder's record: the same process and computer, with a counter
+ * that changes on every renewal. Never throws.
+ * @param {string} lockDir
+ */
+export function renewLock(lockDir: string): void;
+/**
+ * Whether a lock held from another computer has gone silent: its record has
+ * not changed for `LEASE_SILENCE_MS` of this process's own observation.
+ * @param {string} lockDir
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function foreignLockIsSilent(lockDir: string, now?: number): boolean;
+/** Forget what this process observed (tests). */
+export function forgetObservedLocks(): void;
+/** How often the holder renews its record while the package manager works. */
+export const LEASE_RENEW_MS: 10000;
+/** How long a record from another computer may go unrenewed, as observed. */
+export const LEASE_SILENCE_MS: 60000;

package/foundation/release/lock-lease.mjs

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The lease on a release install's lock in the per-user cache (spec
+ * AST-081 FR11).
+ *
+ * A lock folder records its holder in `owner.json`: the process id and the
+ * computer's name. On the same computer a waiting run checks whether that
+ * process still runs. A cache shared between computers cannot check another
+ * computer's processes, so the holder renews its record every
+ * `LEASE_RENEW_MS` while the package manager works, and a waiting run takes
+ * a lock from another computer over once it has seen the record go unrenewed
+ * for `LEASE_SILENCE_MS`. The waiting run judges by change it observes, never
+ * by comparing clocks, so computers whose clocks differ agree.
+ *
+ * @input  the lock folder
+ * @output the renewed record, and whether a foreign record has gone silent
+ * @position foundation/release — renewed by npm-guard.mjs, read by cache.mjs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** How often the holder renews its record while the package manager works. */
+export const LEASE_RENEW_MS = 10_000;
+
+/** How long a record from another computer may go unrenewed, as observed. */
+export const LEASE_SILENCE_MS = 60_000;
+
+/**
+ * Renew the holder's record: the same process and computer, with a counter
+ * that changes on every renewal. Never throws.
+ * @param {string} lockDir
+ */
+export function renewLock(lockDir) {
+  const file = path.join(lockDir, 'owner.json');
+  try {
+    const owner = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const next = {...owner, beat: (Number(owner.beat) || 0) + 1};
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(next));
+    fs.renameSync(tmp, file);
+  } catch {
+    // A lock that was taken over or removed has no record to renew.
+  }
+}
+
+/**
+ * What this process last saw of each foreign lock: the record's text and
+ * when that text was first seen.
+ * @type {Map<string, {text: string, since: number}>}
+ */
+const observed = new Map();
+
+/**
+ * Whether a lock held from another computer has gone silent: its record has
+ * not changed for `LEASE_SILENCE_MS` of this process's own observation.
+ * @param {string} lockDir
+ * @param {number} [now]
+ * @returns {boolean}
+ */
+export function foreignLockIsSilent(lockDir, now = Date.now()) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(lockDir, 'owner.json'), 'utf-8');
+  } catch {
+    text = '';
+  }
+  const seen = observed.get(lockDir);
+  if (!seen || seen.text !== text) {
+    observed.set(lockDir, {text, since: now});
+    return false;
+  }
+  return now - seen.since >= LEASE_SILENCE_MS;
+}
+
+/** Forget what this process observed (tests). */
+export function forgetObservedLocks() {
+  observed.clear();
+}