@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/release/handoff.e2e.test.mjs

@@ -0,0 +1,278 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The hand-off through the real bin: a run started in this copy, in a
+ * project whose release is another one, is answered by that release with the
+ * same arguments, folder, standard streams, and exit status, and one line on
+ * standard error in text mode (spec AST-081 FR2, FR9).
+ */
+
+import {describe, it, expect, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {
+  CLI_VERSION,
+  cleanupFixtures,
+  installCore,
+  linkThisCliAsProjectCli,
+  installStandInCli,
+  project,
+  seedRelease,
+  tempDir,
+  writeJson,
+} from '../../test-utils/release-fixtures.mjs';
+
+const BIN = fileURLToPath(
+  new URL('../../clients/cli/bin/astryx.mjs', import.meta.url),
+);
+const SELF_VERSION = JSON.parse(
+  fs.readFileSync(
+    fileURLToPath(new URL('../../package.json', import.meta.url)),
+    'utf-8',
+  ),
+).version;
+
+afterEach(cleanupFixtures);
+
+/**
+ * Run this copy's bin in `cwd` with a private home and cache.
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {{input?: string, cache?: string, home?: string, env?: Record<string, string>}} [options]
+ */
+function run(cwd, args, options = {}) {
+  const home = options.home ?? tempDir('home');
+  const cache = options.cache ?? tempDir('cache');
+  const result = spawnSync(process.execPath, [BIN, ...args], {
+    cwd,
+    encoding: 'utf-8',
+    input: options.input ?? '',
+    env: {
+      // Not the package manager running the tests: its npm_* settings would
+      // name it as the project's package manager. Nor the test runner's CI
+      // or NO_UPDATE_NOTIFIER, which turn update notices off.
+      ...Object.fromEntries(
+        Object.entries(process.env).filter(
+          ([key]) => !/^(?:npm_|CI$|NO_UPDATE_NOTIFIER$)/iu.test(key),
+        ),
+      ),
+      HOME: home,
+      USERPROFILE: home,
+      XDG_CACHE_HOME: cache,
+      LOCALAPPDATA: cache,
+      XDG_CONFIG_HOME: path.join(home, '.config'),
+      APPDATA: path.join(home, 'AppData', 'Roaming'),
+      NO_COLOR: '1',
+      ...options.env,
+    },
+    timeout: 60_000,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    /** The stand-in's report, when a stand-in answered. */
+    report: () => JSON.parse(result.stdout.trim().split('\n').pop() ?? 'null'),
+  };
+}
+
+describe('hand-off to the project CLI', () => {
+  it('passes argv, folder, stdin and the exit status, with one stderr line', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.6.8'});
+    installCore(root, '0.6.8');
+    installStandInCli(root, '0.6.8');
+    const src = path.join(root, 'src');
+    fs.mkdirSync(src);
+    const result = run(src, ['component', 'Button', '--exit', '7'], {
+      input: 'piped',
+    });
+    expect(result.status).toBe(7);
+    expect(result.report()).toEqual({
+      version: '0.6.8',
+      args: ['component', 'Button', '--exit', '7'],
+      cwd: src,
+      stdin: 'piped',
+    });
+    const lines = result.stderr.trim().split('\n');
+    expect(lines).toEqual([
+      `astryx: answered by this project's CLI 0.6.8, handed over from CLI ${SELF_VERSION}`,
+      'stand-in 0.6.8',
+    ]);
+  });
+
+  it('prints no line with --json', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.6.8'});
+    installCore(root, '0.6.8');
+    installStandInCli(root, '0.6.8');
+    const result = run(root, ['docs', '--json']);
+    expect(result.status).toBe(0);
+    expect(result.stderr.trim()).toBe('stand-in 0.6.8');
+  });
+
+  it("a project CLI that cannot start: the release matching the project's Core answers; offline, this copy, with the warning", () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.6.8'});
+    installCore(root, '0.6.8');
+    installStandInCli(root, '0.6.8', {bin: false});
+    const offline = {npm_config_registry: 'http://127.0.0.1:9'};
+    const json = run(root, ['docs', '--json'], {env: offline});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).meta.answeredBy.copy).toBe('fallback');
+    const text = run(root, ['--version'], {env: offline});
+    expect(text.status).toBe(0);
+    expect(text.stdout.trim()).toBe(SELF_VERSION);
+    expect(text.stderr).toMatch(
+      /astryx: could not get Astryx 0\.6\.8 to match this project's Core/u,
+    );
+  });
+});
+
+describe('hand-off to the matched release', () => {
+  it("runs the project's own CLI even when its version differs from the project's Core", () => {
+    const cache = tempDir('cache');
+    seedRelease(path.join(cache, 'astryx'), '0.7.0');
+    const root = project(tempDir(), {'@astryxdesign/core': '0.7.0'});
+    installCore(root, '0.7.0');
+    installStandInCli(root, '0.6.8');
+    const result = run(root, ['upgrade', '--from', '0.6.8'], {cache});
+    expect(result.status).toBe(0);
+    expect(result.report()).toMatchObject({
+      version: '0.6.8',
+      args: ['upgrade', '--from', '0.6.8'],
+    });
+  });
+
+  it("runs the cached release equal to the project's Core when the project's own CLI cannot start", () => {
+    const cache = tempDir('cache');
+    seedRelease(path.join(cache, 'astryx'), '0.7.0');
+    const root = project(tempDir(), {'@astryxdesign/core': '0.7.0'});
+    installCore(root, '0.7.0');
+    installStandInCli(root, '0.6.8', {bin: false});
+    const result = run(root, ['upgrade', '--from', '0.6.8'], {cache});
+    expect(result.status).toBe(0);
+    expect(result.report()).toMatchObject({
+      version: '0.7.0',
+      args: ['upgrade', '--from', '0.6.8'],
+    });
+    expect(result.stderr.trim().split('\n')).toEqual([
+      "astryx: answered by CLI 0.7.0 with Core 0.7.0, the release that matches this project's Core",
+      'stand-in 0.7.0',
+    ]);
+  });
+
+  it('answers a Core-only project itself, as released, with no line and no install', () => {
+    const cache = tempDir('cache');
+    const root = project(tempDir(), {'@astryxdesign/core': '0.7.0'});
+    installCore(root, '0.7.0');
+    const result = run(root, ['docs', '--json'], {cache});
+    expect(result.status).toBe(0);
+    expect(JSON.parse(result.stdout).meta.answeredBy).toEqual({
+      cli: SELF_VERSION,
+      core: '0.7.0',
+      copy: 'starting',
+    });
+    expect(fs.existsSync(path.join(cache, 'astryx', 'releases', '0.7.0'))).toBe(
+      false,
+    );
+  });
+});
+
+describe('answering itself', () => {
+  it('outside a project: one line in text mode, answeredBy in JSON', () => {
+    const empty = tempDir('empty');
+    const text = run(empty, ['--version']);
+    expect(text.stdout.trim()).toBe(SELF_VERSION);
+    expect(text.stderr.trim()).toBe(
+      `astryx: answered by CLI ${SELF_VERSION} with Core ${SELF_VERSION}, outside a project`,
+    );
+    const json = run(empty, ['docs', '--json']);
+    expect(json.stderr).toBe('');
+    expect(JSON.parse(json.stdout).meta.answeredBy).toEqual({
+      cli: SELF_VERSION,
+      core: SELF_VERSION,
+      copy: 'carried',
+    });
+  });
+});
+
+describe('answeredBy on every successful JSON result', () => {
+  it('covers the manifest, the version, and help', () => {
+    const empty = tempDir('empty');
+    for (const args of [
+      ['manifest', '--json'],
+      ['--json'],
+      ['--version', '--json'],
+      ['component', '--help', '--json'],
+    ]) {
+      const result = run(empty, args);
+      expect(result.status, args.join(' ')).toBe(0);
+      expect(
+        JSON.parse(result.stdout).meta?.answeredBy,
+        args.join(' '),
+      ).toEqual({
+        cli: SELF_VERSION,
+        core: SELF_VERSION,
+        copy: 'carried',
+      });
+    }
+  });
+});
+
+describe('computer-level commands are never handed to a project', () => {
+  it('answers init --user itself inside a project whose CLI is another release', () => {
+    const root = project(tempDir(), {'@astryxdesign/core': '0.6.8'});
+    installCore(root, '0.6.8');
+    installStandInCli(root, '0.6.8');
+    for (const args of [
+      ['init', '--user'],
+      ['--json', 'init', '--user', '--remove-agents'],
+    ]) {
+      const result = run(root, args);
+      expect(result.status, result.stderr).toBe(0);
+      expect(result.stdout).not.toContain('"version":"0.6.8"');
+      expect(result.stderr).not.toContain('stand-in');
+    }
+    const text = run(root, ['init', '--user']);
+    expect(text.stderr.split('\n')[0]).toBe(
+      `astryx: answered by CLI ${SELF_VERSION} with Core ${SELF_VERSION}, for this computer`,
+    );
+  });
+});
+
+describe('update notices through the real bin (FR10)', () => {
+  it('prints the project notice after the command, once a day, never with --json, in CI, or with NO_UPDATE_NOTIFIER', () => {
+    const [major, minor, patch] = CLI_VERSION.split(/[.-]/u).map(Number);
+    const newest = `${major}.${minor}.${patch + 1}`;
+    const root = project(tempDir(), {
+      '@astryxdesign/core': CLI_VERSION,
+      '@astryxdesign/cli': CLI_VERSION,
+    });
+    installCore(root, CLI_VERSION);
+    linkThisCliAsProjectCli(root);
+    writeJson(path.join(root, 'package-lock.json'), {lockfileVersion: 3});
+    const cache = tempDir('cache');
+    const home = tempDir('home');
+    writeJson(path.join(home, '.config', 'astryx', 'state.json'), {
+      latest: newest,
+      checkOkAt: 1,
+    });
+    const notice = [
+      `A new release of Astryx is available: ${CLI_VERSION} → ${newest}`,
+      `To upgrade, run: npm install @astryxdesign/core@${newest} @astryxdesign/cli@${newest}, then npx astryx upgrade --from ${CLI_VERSION} --apply`,
+    ];
+    for (const env of [{CI: 'true'}, {NO_UPDATE_NOTIFIER: '1'}]) {
+      const off = run(root, ['--version'], {cache, home, env});
+      expect(off.stderr).not.toContain('A new release');
+    }
+    const json = run(root, ['--version', '--json'], {cache, home});
+    expect(json.status).toBe(0);
+    expect(json.stderr).not.toContain('A new release');
+    const first = run(root, ['--version'], {cache, home});
+    expect(first.status).toBe(0);
+    expect(first.stdout.trim()).toBe(CLI_VERSION);
+    expect(first.stderr.trim().split('\n').slice(-2)).toEqual(notice);
+    const second = run(root, ['--version'], {cache, home});
+    expect(second.stderr).not.toContain('A new release');
+  });
+});

package/foundation/release/handoff.mjs

@@ -0,0 +1,357 @@
+// 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).
+ *
+ * @input  the running copy, argv, the working folder
+ * @output returns when this copy answers; otherwise never returns
+ * @position foundation/release — called once by clients/cli/bin/astryx.mjs.
+ */
+
+import {spawn} from 'node:child_process';
+import {writeSync} from 'node:fs';
+import {
+  chooseRelease,
+  isComputerLevel,
+  isGlobalCopy,
+  namesWhoAnswered,
+  packageRootOf,
+  runningCopy,
+} from './choose.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';
+
+/** 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 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);
+}
+
+/**
+ * Choose who answers and hand off when it is not this copy.
+ * @param {{cliRoot: string, argv: string[]}} input argv after `node astryx`
+ * @returns {Promise<void>} resolves when this copy answers
+ */
+export async function startRun({cliRoot, argv}) {
+  const json = argv.includes('--json');
+  const self = runningCopy(cliRoot);
+  const cacheDir = userCacheDir();
+  const global = 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,
+    };
+  }
+
+  if (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 (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));
+    process.once('exit', code => {
+      if (code === 0) notify();
+    });
+    return;
+  }
+
+  let bin = choice.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;
+
+/**
+ * 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;