Skip to content

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

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

/**
 * @file The per-user cache of CLI releases.
 *
 * Global mode answers some runs with a release other than the copy that
 * started them (spec AST-081 FR2, FR6): the release that matches a project's
 * Core, the newest release for the global copy, or the Core a copy carries
 * outside a project. Each is installed here, once, through the package
 * manager, and reused by every later run:
 *
 *     <user cache>/astryx/releases/<version>/
 *       package.json                 (an empty private package)
 *       node_modules/@astryxdesign/cli
 *       node_modules/@astryxdesign/core
 *       release.json                 (written last: the release is verified)
 *
 * A release counts only once `release.json` exists. It is written after the
 * install finished, the CLI started and reported its own version, and the
 * release supports this computer's Node. An install builds in a temporary
 * folder beside the others and is renamed into place, so a run never sees a
 * half-installed release, and a lock keeps two runs from installing the same
 * release at once.
 *
 * The package manager is npm, started from the Node that runs the CLI, so the
 * registry, proxy, and offline settings in the user's npm configuration
 * apply. No Astryx setting changes where or how releases install.
 *
 * @input  a release version
 * @output the release's folder, or why it is unavailable
 * @position foundation/release — used by the bin's hand-off, by the carried
 *   Core lookup, and by the background refresh worker.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {spawnSync} from 'node:child_process';
import {createHash} from 'node:crypto';
import {fileURLToPath} from 'node:url';
import {satisfiesRange} from '../env/semver.mjs';
import {readJson} from './project.mjs';
import {userCacheDir as userCacheDirFor} from '../env/user-dirs.mjs';
import {foreignLockIsSilent} from './lock-lease.mjs';
import {relativeWithin} from '../fs/path-compare.mjs';

/**
 * The per-user cache directory every Astryx cache lives in, never inside a
 * project (`foundation/env/user-dirs.mjs`).
 * @returns {string}
 */
export function userCacheDir() {
  return userCacheDirFor();
}

/**
 * The folder all cached releases live in.
 * @param {string} [cacheDir]
 * @returns {string}
 */
export function releasesDir(cacheDir = userCacheDir()) {
  return path.join(cacheDir, 'releases');
}

/** A release version safe to use as a folder name and an npm spec. */
const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;

/**
 * Is `version` a plain release version?
 * @param {unknown} version
 * @returns {version is string}
 */
export function isReleaseVersion(version) {
  return typeof version === 'string' && VERSION_RE.test(version);
}

/**
 * A cached, verified release.
 * @typedef {object} CachedRelease
 * @property {string} version
 * @property {string} dir the release folder
 * @property {string} cliDir its `@astryxdesign/cli`
 * @property {string} coreDir its `@astryxdesign/core`
 * @property {string} bin the CLI's `astryx` entry file
 */

/**
 * The entry file a CLI package's `astryx` bin points at.
 * @param {string} cliDir
 * @returns {string | null}
 */
export function cliBinOf(cliDir) {
  const pkg = readJson(path.join(cliDir, 'package.json'));
  const bin =
    typeof pkg?.bin === 'string' ? pkg.bin : pkg?.bin && pkg.bin.astryx;
  if (typeof bin !== 'string') return null;
  const file = path.join(cliDir, bin);
  return fs.existsSync(file) ? file : null;
}

/**
 * The files whose bytes a cached release's marker records, relative to the
 * release folder: enough to notice a damaged or half-written release without
 * reading every file on each run.
 * @param {string} bin the CLI's entry file
 * @param {string} dir the release folder
 * @returns {string[]}
 */
function checkedFiles(bin, dir) {
  return [
    path.join('node_modules', '@astryxdesign', 'cli', 'package.json'),
    path.join('node_modules', '@astryxdesign', 'core', 'package.json'),
    path.relative(dir, bin),
  ];
}

/**
 * The sha256 of a file, or null when it cannot be read.
 * @param {string} file
 * @returns {string | null}
 */
function fileHash(file) {
  try {
    return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
  } catch {
    return null;
  }
}

/**
 * The cached release `version`, when it is installed and verified: its
 * marker parses, names the version, and records the bytes of the CLI's and
 * Core's package.json and the CLI's entry file, and those files still have
 * them, and the number and total size of the two packages' files are the
 * ones recorded. Anything else is a damaged release, which counts as absent and is
 * replaced the next time a run needs it.
 * @param {string} version
 * @param {string} [cacheDir]
 * @returns {CachedRelease | null}
 */
export function cachedRelease(version, cacheDir = userCacheDir()) {
  if (!isReleaseVersion(version)) return null;
  const key = `${cacheDir}\0${version}`;
  if (verified.has(key)) return verified.get(key) ?? null;
  const result = verifyRelease(version, cacheDir);
  // Only a verified release is remembered; an absent one is looked at again,
  // since another run may be installing it.
  if (result) verified.set(key, result);
  return result;
}

/**
 * Releases this process already verified, so a run checks each one once.
 * @type {Map<string, CachedRelease>}
 */
const verified = new Map();

/** Forget which releases this process verified, so the next look checks again. */
export function forgetVerifiedReleases() {
  verified.clear();
}

/**
 * The number of files and their total size under a package folder.
 * @param {string} dir
 * @returns {{count: number, bytes: number}}
 */
function treeSize(dir) {
  let count = 0;
  let bytes = 0;
  /** @param {string} d */
  const walk = d => {
    for (const entry of fs.readdirSync(d, {withFileTypes: true})) {
      const p = path.join(d, entry.name);
      if (entry.isDirectory()) walk(p);
      else {
        count += 1;
        bytes += fs.statSync(p).size;
      }
    }
  };
  walk(dir);
  return {count, bytes};
}

/**
 * The size record of a release's two packages.
 * @param {string} dir the release folder
 * @returns {{cli: {count: number, bytes: number}, core: {count: number, bytes: number}} | null}
 */
export function releaseTree(dir) {
  try {
    return {
      cli: treeSize(path.join(dir, 'node_modules', '@astryxdesign', 'cli')),
      core: treeSize(path.join(dir, 'node_modules', '@astryxdesign', 'core')),
    };
  } catch {
    return null;
  }
}

/**
 * The check behind {@link cachedRelease}.
 * @param {string} version
 * @param {string} cacheDir
 * @returns {CachedRelease | null}
 */
function verifyRelease(version, cacheDir) {
  const dir = path.join(releasesDir(cacheDir), version);
  const marker = readJson(path.join(dir, 'release.json'));
  if (!marker || marker.version !== version || !marker.files) return null;
  const cliDir = path.join(dir, 'node_modules', '@astryxdesign', 'cli');
  const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
  const bin = cliBinOf(cliDir);
  if (!bin) return null;
  for (const rel of checkedFiles(bin, dir)) {
    const want = marker.files[rel.split(path.sep).join('/')];
    if (typeof want !== 'string' || fileHash(path.join(dir, rel)) !== want) {
      return null;
    }
  }
  // Every other file of the two packages: a deleted or truncated module
  // changes the count or the total size.
  if (
    JSON.stringify(releaseTree(dir)) !== JSON.stringify(marker.tree ?? null)
  ) {
    return null;
  }
  return {version, dir, cliDir, coreDir, bin};
}

/**
 * Is `dir` inside the release cache? A copy that lives there was started by
 * global mode, never installed by a person.
 * @param {string} dir
 * @param {string} [cacheDir]
 * @returns {boolean}
 */
export function isInReleaseCache(dir, cacheDir = userCacheDir()) {
  return (
    relativeWithin(realOrSelf(releasesDir(cacheDir)), realOrSelf(dir)) !== null
  );
}

/**
 * @param {string} p
 * @returns {string}
 */
function realOrSelf(p) {
  try {
    return fs.realpathSync(p);
  } catch {
    return path.resolve(p);
  }
}

/**
 * How to start npm, never through a shell, so nothing a project declares is
 * read by one: npm's own entry file run with this Node, from beside the
 * running Node, else from beside an `npm` on the PATH (on Windows, npm's
 * `npm.cmd` shim sits next to its `node_modules`); else `npm` on the PATH,
 * started directly. An `npm` beside the running Node or on the PATH that
 * links to npm's entry file (as distribution packages install it, such as
 * `/usr/bin/npm` to `/usr/lib/node_modules_22/npm/bin/npm-cli.js`) counts as
 * that entry file.
 * @param {{env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, execPath?: string}} [where]
 *   `execPath`: the Node that runs npm (default: this one)
 * @returns {{command: string, prefix: string[], shell: false}}
 */
export function npmCommand(where = {}) {
  const {
    env = process.env,
    platform = process.platform,
    execPath = process.execPath,
  } = where;
  const paths = platform === 'win32' ? path.win32 : path.posix;
  const nodeDir = paths.dirname(execPath);
  const entry = (/** @type {string} */ dir) =>
    paths.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js');
  const candidates = [
    ...(platform === 'win32'
      ? [entry(nodeDir)]
      : [
          paths.join(
            nodeDir,
            '..',
            'lib',
            'node_modules',
            'npm',
            'bin',
            'npm-cli.js',
          ),
          entry(nodeDir),
        ]),
    ...String(env.PATH ?? env.Path ?? '')
      .split(platform === 'win32' ? ';' : ':')
      .filter(Boolean)
      .filter(dir =>
        fs.existsSync(
          paths.join(dir, platform === 'win32' ? 'npm.cmd' : 'npm'),
        ),
      )
      .flatMap(dir =>
        platform === 'win32'
          ? [entry(dir)]
          : [
              paths.join(
                dir,
                '..',
                'lib',
                'node_modules',
                'npm',
                'bin',
                'npm-cli.js',
              ),
            ],
      ),
  ];
  if (platform !== 'win32') {
    // An `npm` that links to npm's entry file: beside the running Node first.
    for (const dir of [
      nodeDir,
      ...String(env.PATH ?? '')
        .split(':')
        .filter(Boolean),
    ]) {
      try {
        const real = fs.realpathSync(paths.join(dir, 'npm'));
        if (paths.basename(real) === 'npm-cli.js') candidates.push(real);
      } catch {
        // No npm there.
      }
    }
  }
  for (const file of candidates) {
    if (fs.existsSync(file)) {
      return {command: execPath, prefix: [file], shell: false};
    }
  }
  return {command: 'npm', prefix: [], shell: false};
}

/**
 * Whether `spec` reads as an npm version range and nothing else: versions,
 * `x`/`*` wildcards, prerelease tags, the range operators, `||`, and spaces.
 * Anything a shell or npm would read as more, such as `&`, `;`, a lone `|`,
 * quotes, or a URL, is refused.
 * @param {string} spec
 * @returns {boolean}
 */
export function isVersionRange(spec) {
  if (typeof spec !== 'string' || spec.trim() === '' || spec.length > 256) {
    return false;
  }
  if (/[^0-9A-Za-z.\-+^~<>=|*\s]/u.test(spec)) return false;
  return !/(?:^|[^|])\|(?:[^|]|$)/u.test(spec);
}

/**
 * The result of running npm.
 * @typedef {object} NpmResult
 * @property {number | null} status
 * @property {NodeJS.Signals | null} [signal] the signal that ended npm, such as Ctrl-C's
 * @property {string} stdout
 * @property {string} stderr
 * @property {Error} [error]
 */

/**
 * Run npm synchronously with no output on the caller's streams.
 * @param {string[]} args
 * npm runs under npm-guard.mjs, which gives it a process group of its own
 * and ends that group when the time limit passes, when this run goes away
 * (even killed outright), or when this run receives Ctrl-C. So no install
 * outlives the run that started it.
 *
 * @param {string[]} args
 * @param {{cwd?: string, timeoutMs?: number, pidFile?: string, npm?: {command: string, prefix: string[], shell?: false}}} [options]
 *   `pidFile` receives npm's process id while it runs (the release lock's
 *   record); `npm` replaces how npm is started (tests).
 * @returns {NpmResult}
 */
export function runNpm(args, options = {}) {
  const {command, prefix} = options.npm ?? npmCommand();
  const timeoutMs = options.timeoutMs ?? 300_000;
  const direct = process.platform === 'win32';
  const result = direct
    ? spawnSync(command, [...prefix, ...args], {
        cwd: options.cwd ?? os.tmpdir(),
        encoding: 'utf-8',
        // Never a shell: a declared range must not reach one.
        shell: false,
        stdio: ['ignore', 'pipe', 'pipe'],
        timeout: timeoutMs,
        // npm defers SIGTERM until its work finishes, so a time limit has to
        // end it outright or the limit never takes effect.
        killSignal: 'SIGKILL',
        windowsHide: true,
      })
    : spawnSync(
        process.execPath,
        [
          GUARD,
          String(timeoutMs),
          options.pidFile ?? '',
          command,
          ...prefix,
          ...args,
        ],
        {
          cwd: options.cwd ?? os.tmpdir(),
          encoding: 'utf-8',
          stdio: ['ignore', 'pipe', 'pipe'],
          // A backstop only: the guard ends npm at the limit itself.
          timeout: timeoutMs + 30_000,
          killSignal: 'SIGKILL',
          windowsHide: true,
        },
      );
  const timedOut = !direct && result.status === 124;
  return {
    status: timedOut ? null : result.status,
    signal: result.signal ?? null,
    stdout: result.stdout ?? '',
    stderr: result.stderr ?? '',
    ...(timedOut
      ? {error: Object.assign(new Error('npm timed out'), {code: 'ETIMEDOUT'})}
      : result.error
        ? {error: result.error}
        : {}),
  };
}

/** The guard npm runs under. */
const GUARD = fileURLToPath(new URL('./npm-guard.mjs', import.meta.url));

/**
 * The newest published version that `spec` (a dist-tag or a range) names,
 * asked of the registry through npm.
 * @param {string} name e.g. `@astryxdesign/core`
 * @param {string} spec e.g. `latest`, `^0.6.8`
 * @param {{run?: typeof runNpm}} [options]
 * @returns {string | null}
 */
export function resolvePublishedVersion(name, spec, options = {}) {
  if (!isVersionRange(spec) || !/^@astryxdesign\/[a-z-]+$/u.test(name)) {
    return null;
  }
  const run = options.run ?? runNpm;
  const result = run(
    ['view', `${name}@${spec}`, 'version', '--json', ...BOUNDED_FETCH],
    {timeoutMs: 60_000},
  );
  if (result.status !== 0) return null;
  let parsed;
  try {
    parsed = JSON.parse(result.stdout || 'null');
  } catch {
    return null;
  }
  const versions = (Array.isArray(parsed) ? parsed : [parsed]).filter(
    isReleaseVersion,
  );
  return versions.length > 0 ? versions[versions.length - 1] : null;
}

/**
 * The release the registry tags `latest` for the CLI, and the Node range it
 * declares; null when the registry cannot be asked, with the reason given to
 * `onFailure`: `npm-missing` (npm cannot be started), `npm-failed: <npm's
 * error code>` (npm ran and failed, such as on ECONNREFUSED or E404), or
 * `bad-reply` (npm's answer names no release).
 * @param {{run?: typeof runNpm, onFailure?: (reason: string) => void}} [options]
 * @returns {{version: string, node: string | null} | null}
 */
export function resolveLatestRelease(options = {}) {
  const run = options.run ?? runNpm;
  const fail = (/** @type {string} */ reason) => {
    options.onFailure?.(reason);
    return null;
  };
  const result = run(
    [
      'view',
      '@astryxdesign/cli@latest',
      'version',
      'engines',
      '--json',
      ...BOUNDED_FETCH,
    ],
    {timeoutMs: 60_000},
  );
  if (result.status !== 0) {
    if (/** @type {any} */ (result.error)?.code === 'ENOENT') {
      return fail('npm-missing');
    }
    const code =
      /npm (?:error|ERR!) code (\S+)/u.exec(result.stderr)?.[1] ??
      /** @type {any} */ (result.error)?.code ??
      (result.signal ? result.signal : `exit ${result.status}`);
    return fail(`npm-failed: ${code}`);
  }
  let parsed;
  try {
    parsed = JSON.parse(result.stdout || 'null');
  } catch {
    return fail('bad-reply');
  }
  const info = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
  if (typeof info === 'string') {
    return isReleaseVersion(info)
      ? {version: info, node: null}
      : fail('bad-reply');
  }
  if (!info || !isReleaseVersion(info.version)) return fail('bad-reply');
  const node = info.engines?.node;
  return {version: info.version, node: typeof node === 'string' ? node : null};
}

/**
 * Registry requests give up after one retry and 30 seconds each, so a run with
 * no network fails in seconds with ERR_VERSIONS_UNAVAILABLE instead of waiting
 * out npm's default retries. Registry, proxy, and offline settings still come
 * from the user's npm configuration.
 */
const BOUNDED_FETCH = [
  '--fetch-retries=1',
  '--fetch-timeout=30000',
  // One quick retry, so an offline run learns it is offline in seconds.
  '--fetch-retry-mintimeout=2000',
  '--fetch-retry-maxtimeout=10000',
];

/**
 * How long a failed install of a release is remembered, so offline runs do
 * not start npm again on every run (spec AST-081 FR2): 2 minutes after a
 * first failure, so a passing registry hiccup is retried soon, and 10 minutes
 * after a second failure in a row. A successful install forgets it.
 * @param {number} failures the failures in a row, 1 or more
 * @returns {number}
 */
export function failedInstallWaitMs(failures) {
  return (failures >= 2 ? 10 : 2) * 60_000;
}

/**
 * The record of a failed install of `version`: a file in the release cache,
 * shared by every copy of the CLI that uses this cache.
 * @param {string} version
 * @param {string} cacheDir
 * @returns {string}
 */
function failedRecordPath(version, cacheDir) {
  return path.join(releasesDir(cacheDir), `.failed-${version}.json`);
}

/**
 * The recorded failed installs of `version` in a row, when the last was
 * within its wait (failedInstallWaitMs), or null.
 * @param {string} version
 * @param {string} cacheDir
 * @param {number} [now]
 * @returns {{at: number, reason: string, failures: number, waitMs: number} | null}
 */
export function recentFailedInstall(version, cacheDir, now = Date.now()) {
  const record = readFailedInstall(version, cacheDir);
  if (!record) return null;
  const waitMs = failedInstallWaitMs(record.failures);
  const age = now - record.at;
  return age >= 0 && age < waitMs ? {...record, waitMs} : null;
}

/**
 * The record of failed installs of `version`, whatever its age, or null.
 * @param {string} version
 * @param {string} cacheDir
 * @returns {{at: number, reason: string, failures: number} | null}
 */
function readFailedInstall(version, cacheDir) {
  const record = readJson(failedRecordPath(version, cacheDir));
  if (
    !record ||
    typeof record.at !== 'number' ||
    typeof record.reason !== 'string'
  ) {
    return null;
  }
  const failures =
    Number.isInteger(record.failures) && record.failures > 0
      ? record.failures
      : 1;
  return {at: record.at, reason: record.reason, failures};
}

/**
 * Remember, or forget, a failed install of `version`. Never fails a run.
 * @param {string} version
 * @param {string} cacheDir
 * @param {string | null} reason null forgets it
 */
function recordFailedInstall(version, cacheDir, reason) {
  const file = failedRecordPath(version, cacheDir);
  try {
    if (reason === null) {
      fs.rmSync(file, {force: true});
      return;
    }
    fs.mkdirSync(path.dirname(file), {recursive: true});
    const failures = (readFailedInstall(version, cacheDir)?.failures ?? 0) + 1;
    const tmp = `${file}.${process.pid}.tmp`;
    fs.writeFileSync(
      tmp,
      `${JSON.stringify({at: Date.now(), reason, failures})}\n`,
    );
    fs.renameSync(tmp, file);
  } catch {
    // An unwritable cache already answers for itself.
  }
}

/**
 * The longest an install may take: generous, so a slow but moving download
 * finishes, while a stalled one still ends in ERR_VERSIONS_UNAVAILABLE.
 */
export const INSTALL_TIMEOUT_MS = 15 * 60_000;

/**
 * The exit statuses a package manager uses when Ctrl-C, a closed terminal, or
 * a termination request stopped it.
 * @type {Record<number, NodeJS.Signals>}
 */
const EXIT_SIGNALS = {129: 'SIGHUP', 130: 'SIGINT', 143: 'SIGTERM'};

/** Sleep the thread without spinning. @param {number} ms */
function sleep(ms) {
  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
}

/** How long a lock may stand before a run treats its holder as gone. */
const STALE_LOCK_MS = 30 * 60_000;

/**
 * How long a lock held from another computer (a shared cache) may stand,
 * however often its holder renews it; one whose holder stops renewing it is
 * taken over sooner (lock-lease.mjs).
 */
const FOREIGN_LOCK_MS = 20 * 60_000;

/** How long a lock with no owner record may stand: its holder died taking it. */
const UNOWNED_LOCK_MS = 10_000;

/**
 * Is process `pid` on this computer still running?
 * @param {number} pid
 * @returns {boolean}
 */
function isAlive(pid) {
  try {
    process.kill(pid, 0);
    return true;
  } catch (error) {
    // EPERM: it runs, as another user.
    return /** @type {NodeJS.ErrnoException} */ (error).code === 'EPERM';
  }
}

/**
 * Has the run holding `lockDir` gone? Its owner record names a process on
 * this computer that no longer runs; or there is no record and the lock is
 * older than a run needs to write one; or another computer holds it for
 * longer than an install takes, or its holder there stopped renewing it; or
 * it is older than any install.
 * @param {string} lockDir
 * @param {number} now
 * @returns {boolean}
 */
function lockIsStale(lockDir, now) {
  let age;
  try {
    age = now - fs.statSync(lockDir).mtimeMs;
  } catch {
    return false;
  }
  if (age > STALE_LOCK_MS) return true;
  const owner = readJson(path.join(lockDir, 'owner.json'));
  if (!owner) return age > UNOWNED_LOCK_MS;
  if (owner.host !== os.hostname() || !Number.isInteger(owner.pid)) {
    return age > FOREIGN_LOCK_MS || foreignLockIsSilent(lockDir, now);
  }
  // A live holder on this computer is installing, however slowly.
  return !isAlive(owner.pid);
}

/**
 * Take a lock folder, or return false when another live run holds it. A lock
 * whose holder has gone, such as a run stopped with Ctrl-C or killed, is taken
 * over at once, and one from another computer once its holder has stopped
 * renewing it. Throws when the cache folder cannot be written.
 * @param {string} lockDir
 * @param {{now?: number}} [options] the clock, for tests
 * @returns {boolean}
 */
export function tryLock(lockDir, {now = Date.now()} = {}) {
  fs.mkdirSync(path.dirname(lockDir), {recursive: true});
  try {
    fs.mkdirSync(lockDir);
  } catch (error) {
    if (/** @type {NodeJS.ErrnoException} */ (error).code !== 'EEXIST') {
      throw error;
    }
    if (!lockIsStale(lockDir, now)) return false;
    // The run that held it is gone; end the install it left running, if any,
    // before starting another.
    endRecordedInstall(lockDir, {now});
    const aside = `${lockDir}.stale-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
    try {
      fs.renameSync(lockDir, aside);
    } catch {
      // Another run took it over first.
      return false;
    }
    fs.rmSync(aside, {recursive: true, force: true});
    try {
      fs.mkdirSync(lockDir);
    } catch {
      return false;
    }
  }
  try {
    fs.writeFileSync(
      path.join(lockDir, 'owner.json'),
      JSON.stringify({pid: process.pid, host: os.hostname(), at: Date.now()}),
    );
  } catch {
    // Without a record the lock still expires on its own.
  }
  return true;
}

/**
 * What the system says about the process `pid`: its arguments (exact from
 * `/proc`; split on spaces from `ps` or PowerShell, so a path with a space in
 * it never matches), and when it started (ms since the epoch). Read from `/proc` where there is one, else from `ps` (or
 * PowerShell on Windows); null for what cannot be read.
 * @param {number} pid
 * @param {string} procRoot
 * @returns {{argv: string[] | null, startedAt: number | null}}
 */
function processFactsOf(pid, procRoot) {
  try {
    let argv = fs
      .readFileSync(path.join(procRoot, String(pid), 'cmdline'), 'utf-8')
      .split('\u0000')
      .filter(Boolean);
    // npm sets its process title to its command line, which Linux shows as
    // one argument ("npm install @astryxdesign/[email protected] …"): split it as the
    // ps path does.
    if (argv.length === 1) argv = argv[0].trim().split(/\s+/u);
    /** @type {number | null} */
    let startedAt = null;
    try {
      // Field 22 of /proc/<pid>/stat: start time in clock ticks after boot
      // (100 a second on Linux); /proc/stat's btime: boot, in seconds.
      const stat = fs.readFileSync(
        path.join(procRoot, String(pid), 'stat'),
        'utf-8',
      );
      const ticks = Number(
        stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19],
      );
      const btime = Number(
        /^btime (\d+)$/mu.exec(
          fs.readFileSync(path.join(procRoot, 'stat'), 'utf-8'),
        )?.[1],
      );
      if (Number.isFinite(ticks) && Number.isFinite(btime)) {
        startedAt = btime * 1000 + ticks * 10;
      }
    } catch {
      // Start time unknown.
    }
    return {argv, startedAt};
  } catch {
    // No process table here.
  }
  if (process.platform === 'win32') {
    const result = spawnSync(
      'powershell.exe',
      [
        '-NoProfile',
        '-NonInteractive',
        '-Command',
        `$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}'; if ($p) { [DateTimeOffset]::new($p.CreationDate).ToUnixTimeMilliseconds(); $p.CommandLine }`,
      ],
      {encoding: 'utf-8', windowsHide: true, timeout: 10_000},
    );
    const [started, ...rest] = (result.stdout ?? '').trim().split(/\r?\n/u);
    const line = rest.join(' ').trim();
    return {
      argv: line
        ? line.split(/\s+/u).map(arg => arg.replace(/^"(.*)"$/u, '$1'))
        : null,
      startedAt: Number(started) || null,
    };
  }
  const result = spawnSync(
    'ps',
    ['-o', 'lstart=', '-o', 'args=', '-p', String(pid)],
    {
      encoding: 'utf-8',
      timeout: 5000,
    },
  );
  const line = (result.stdout ?? '').split(/\r?\n/u)[0] ?? '';
  // `lstart` is a fixed 24-character date, such as `Tue Oct 20 03:52:54 2026`.
  const startedAt = Date.parse(line.slice(0, 24));
  const args = line.slice(24).trim();
  return {
    argv: args ? args.split(/\s+/u) : null,
    startedAt: Number.isFinite(startedAt) ? startedAt : null,
  };
}

/**
 * Whether a process's arguments are this CLI's install of `version`, as
 * runNpm starts it: the program (`argv[0]`) is npm, or a Node running npm's
 * entry file `npm-cli.js` (`argv[1]`), each exactly by name, and the arguments
 * include `install` and `@astryxdesign/cli@<version>`. A Node is one named
 * `node` (with a version, such as `node22`), or one with the same file name
 * as the Node runNpm starts npm with (`node`, by default this one), however
 * it is named, such as `nodejs` or `node-linux-x64`. A program that only
 * has `npm` somewhere in its name or arguments is not.
 * @param {string[]} argv
 * @param {string} version
 * @param {{node?: string}} [options] `node`: the Node runNpm starts npm with
 *   (npmCommand's `execPath`; default: this one)
 * @returns {boolean}
 */
export function isReleaseInstall(
  argv,
  version,
  {node = process.execPath} = {},
) {
  const name = (/** @type {string | undefined} */ arg) =>
    (arg ?? '')
      .split(/[\\/]/u)
      .pop()
      ?.replace(/\.(?:exe|cmd)$/iu, '')
      .toLowerCase() ?? '';
  const program = name(argv[0]);
  const isNode = /^node(?:[-.\d]*)$/u.test(program) || program === name(node);
  const npm = program === 'npm' || (isNode && name(argv[1]) === 'npm-cli.js');
  return (
    npm &&
    argv.includes('install') &&
    argv.includes(`@astryxdesign/cli@${version}`)
  );
}

/**
 * End the npm process group a stale lock records, only when that process is
 * surely the install the lock was taken for: its command line is this CLI's
 * install of the lock's release (isReleaseInstall), the lock is younger than
 * any install may take, and the process started no earlier than the lock.
 * Anything less certain is left alone, and the lock is simply taken over,
 * since a recorded process id can name an unrelated process once the install
 * ended.
 * @param {string} lockDir a `.lock-<version>` folder
 * @param {{now?: number, procRoot?: string, factsOf?: (pid: number) => {argv: string[] | null, startedAt: number | null}}} [options]
 *   the clock, the process table's folder, and the fact reader, for tests
 * @returns {'ended' | 'left'} whether a process group was ended
 */
export function endRecordedInstall(
  lockDir,
  {now = Date.now(), procRoot = '/proc', factsOf} = {},
) {
  let pid;
  try {
    pid = Number(fs.readFileSync(path.join(lockDir, 'npm.pid'), 'utf-8'));
  } catch {
    return 'left';
  }
  if (!Number.isInteger(pid) || pid <= 1 || !isAlive(pid)) return 'left';
  const version = /^\.lock-(.+)$/u.exec(path.basename(lockDir))?.[1];
  if (!version) return 'left';
  const owner = readJson(path.join(lockDir, 'owner.json'));
  const at = typeof owner?.at === 'number' ? owner.at : null;
  if (at === null || !(now - at >= 0 && now - at < INSTALL_TIMEOUT_MS)) {
    return 'left';
  }
  const facts = (factsOf ?? (id => processFactsOf(id, procRoot)))(pid);
  if (!facts.argv || !isReleaseInstall(facts.argv, version)) return 'left';
  // Started before the lock was taken: an older process that reuses the id.
  // A second's slack covers clocks that round.
  if (facts.startedAt === null || facts.startedAt < at - 1000) return 'left';
  try {
    process.kill(process.platform === 'win32' ? pid : -pid, 'SIGKILL');
    return 'ended';
  } catch {
    // Already gone.
    return 'left';
  }
}

/**
 * Remove a folder by renaming it aside first, so a run never sees it half
 * removed.
 * @param {string} dir
 */
function removeAside(dir) {
  const aside = `${dir}.removing-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
  try {
    fs.renameSync(dir, aside);
  } catch {
    return;
  }
  fs.rmSync(aside, {recursive: true, force: true});
}

/**
 * Why a release could not be made available.
 * @typedef {object} ReleaseUnavailable
 * @property {string} version
 * @property {string} reason one plain sentence
 * @property {NodeJS.Signals} [signal] the install was stopped by this signal
 */

/**
 * Install release `version` into the cache, verify it, and return it. A
 * release already cached returns at once. When another run is installing the
 * same release, this waits for it.
 *
 * @param {string} version
 * @param {{cacheDir?: string, run?: typeof runNpm, nodeVersion?: string, waitMs?: number, onProgress?: (event: 'install' | 'wait', version: string) => void}} [options]
 *   `onProgress` hears once when an install starts and once when the run
 *   starts waiting for another run's install.
 * @returns {CachedRelease | ReleaseUnavailable}
 */
export function ensureRelease(version, options = {}) {
  const {
    cacheDir = userCacheDir(),
    run = runNpm,
    nodeVersion = process.versions.node,
    waitMs = INSTALL_TIMEOUT_MS + 60_000,
    onProgress = () => {},
  } = options;
  if (!isReleaseVersion(version)) {
    return {version: String(version), reason: 'it is not a release version'};
  }
  const existing = cachedRelease(version, cacheDir);
  if (existing) {
    // Installed by now, by any copy: forget any failure.
    if (readFailedInstall(version, cacheDir)) {
      recordFailedInstall(version, cacheDir, null);
    }
    return existing;
  }
  // A recent failed install is not retried: offline, every run would start
  // npm again and wait for it (FR2).
  const failed = recentFailedInstall(version, cacheDir);
  if (failed) {
    const minutes = Math.max(1, Math.round((Date.now() - failed.at) / 60_000));
    return {
      version,
      reason: `${failed.reason}; last tried ${minutes} minute${minutes === 1 ? '' : 's'} ago, tried again after ${failed.waitMs / 60_000} minutes`,
    };
  }
  try {
    const result = ensureLocked(version, {
      cacheDir,
      run,
      nodeVersion,
      waitMs,
      onProgress,
    });
    // Stopped with Ctrl-C (or closed): the lock and scratch folder are already
    // cleared; end the run the way the signal would have.
    if ('signal' in result && result.signal)
      process.kill(process.pid, result.signal);
    if ('bin' in result) recordFailedInstall(version, cacheDir, null);
    else if (
      'reason' in result &&
      !('signal' in result && result.signal) &&
      result.reason !== 'another run is still installing it'
    ) {
      recordFailedInstall(version, cacheDir, result.reason);
    }
    return result;
  } catch (error) {
    const code = /** @type {NodeJS.ErrnoException} */ (error).code;
    return {
      version,
      reason: `the release cache ${releasesDir(cacheDir)} cannot be written${code ? ` (${code})` : ''}`,
    };
  }
}

/**
 * `ensureRelease` under the per-release lock.
 * @param {string} version
 * @param {{cacheDir: string, run: typeof runNpm, nodeVersion: string, waitMs: number, onProgress: (event: 'install' | 'wait', version: string) => void}} options
 * @returns {CachedRelease | ReleaseUnavailable}
 */
function ensureLocked(
  version,
  {cacheDir, run, nodeVersion, waitMs, onProgress},
) {
  const root = releasesDir(cacheDir);
  const lockDir = path.join(root, `.lock-${version}`);
  const deadline = Date.now() + waitMs;
  let waiting = false;
  while (!tryLock(lockDir)) {
    const ready = cachedRelease(version, cacheDir);
    if (ready) return ready;
    if (Date.now() > deadline) {
      return {version, reason: 'another run is still installing it'};
    }
    if (!waiting) {
      waiting = true;
      onProgress('wait', version);
    }
    sleep(200);
  }
  // A run stopped mid-install (Ctrl-C, a closed terminal) frees the lock and
  // its scratch folder on the way out; a killed one is taken over by the
  // owner check in tryLock.
  const release = () => {
    for (const entry of safeList(root)) {
      if (entry.startsWith(`.tmp-${version}-${process.pid}-`)) {
        fs.rmSync(path.join(root, entry), {recursive: true, force: true});
      }
    }
    fs.rmSync(lockDir, {recursive: true, force: true});
  };
  /** @param {NodeJS.Signals} signal */
  const onSignal = signal => {
    release();
    removeSignalHandlers();
    process.kill(process.pid, signal);
  };
  const signals = /** @type {NodeJS.Signals[]} */ ([
    'SIGINT',
    'SIGTERM',
    'SIGHUP',
  ]);
  const removeSignalHandlers = () => {
    for (const signal of signals) process.off(signal, onSignal);
  };
  for (const signal of signals) process.on(signal, onSignal);
  try {
    const again = cachedRelease(version, cacheDir);
    if (again) return again;
    // Under the lock, anything left for this version is a damaged release or
    // the scratch folder of a run that stopped: clear both.
    for (const entry of safeList(root)) {
      if (
        entry.startsWith(`.tmp-${version}-`) ||
        entry.startsWith(`${version}.removing-`) ||
        entry.startsWith(`.lock-${version}.stale-`)
      ) {
        fs.rmSync(path.join(root, entry), {recursive: true, force: true});
      }
    }
    removeAside(path.join(root, version));
    verified.delete(`${cacheDir}\0${version}`);
    onProgress('install', version);
    return installLocked(version, {cacheDir, run, nodeVersion});
  } finally {
    removeSignalHandlers();
    release();
  }
}

/**
 * A folder's entries, or none.
 * @param {string} dir
 * @returns {string[]}
 */
function safeList(dir) {
  try {
    return fs.readdirSync(dir);
  } catch {
    return [];
  }
}

/**
 * The install itself, under the lock.
 * @param {string} version
 * @param {{cacheDir: string, run: typeof runNpm, nodeVersion: string}} options
 * @returns {CachedRelease | ReleaseUnavailable}
 */
function installLocked(version, {cacheDir, run, nodeVersion}) {
  const root = releasesDir(cacheDir);
  const tmp = path.join(
    root,
    `.tmp-${version}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`,
  );
  fs.mkdirSync(tmp, {recursive: true});
  try {
    fs.writeFileSync(
      path.join(tmp, 'package.json'),
      `${JSON.stringify({name: 'astryx-release', private: true}, null, 2)}\n`,
    );
    const install = run(
      [
        'install',
        '--no-save',
        '--no-package-lock',
        '--ignore-scripts',
        '--no-audit',
        '--no-fund',
        '--prefer-offline',
        ...BOUNDED_FETCH,
        '--loglevel=error',
        `@astryxdesign/cli@${version}`,
        `@astryxdesign/core@${version}`,
      ],
      {
        cwd: tmp,
        timeoutMs: INSTALL_TIMEOUT_MS,
        pidFile: path.join(root, `.lock-${version}`, 'npm.pid'),
      },
    );
    // Our own time limit ends npm: that is a timeout, not a stopped run.
    if (/** @type {any} */ (install.error)?.code === 'ETIMEDOUT') {
      return {
        version,
        reason: `the install did not finish within ${INSTALL_TIMEOUT_MS / 60_000} minutes`,
      };
    }
    const stoppedBy = install.signal ?? EXIT_SIGNALS[install.status ?? -1];
    if (stoppedBy) {
      return {version, reason: 'the install was stopped', signal: stoppedBy};
    }
    if (install.status !== 0) {
      return {version, reason: npmFailure(install)};
    }
    const cliDir = path.join(tmp, 'node_modules', '@astryxdesign', 'cli');
    const cliPkg = readJson(path.join(cliDir, 'package.json'));
    if (cliPkg?.version !== version) {
      return {version, reason: 'the package manager installed another version'};
    }
    const engine = cliPkg?.engines?.node;
    if (typeof engine === 'string' && !satisfiesRange(nodeVersion, engine)) {
      return {
        version,
        reason: `it needs Node ${engine}, and this computer runs Node ${nodeVersion}`,
      };
    }
    const bin = cliBinOf(cliDir);
    if (!bin) return {version, reason: 'its CLI has no astryx command'};
    // A check, not a person's run: the shared update-notifier variable keeps
    // a release that prints update notices from printing them here, and from
    // using up the day's notices (spec AST-081 FR10).
    const started = spawnSync(process.execPath, [bin, '--version'], {
      cwd: tmp,
      encoding: 'utf-8',
      env: {...process.env, NO_UPDATE_NOTIFIER: '1'},
      stdio: ['ignore', 'pipe', 'pipe'],
      timeout: 60_000,
      windowsHide: true,
    });
    const reported = String(started.stdout ?? '')
      .trim()
      .split(/\r?\n/)
      .pop();
    if (started.status !== 0 || reported !== version) {
      return {version, reason: 'its CLI did not start and report its version'};
    }
    /** @type {Record<string, string | null>} */
    const files = {};
    for (const rel of checkedFiles(bin, tmp)) {
      files[rel.split(path.sep).join('/')] = fileHash(path.join(tmp, rel));
    }
    fs.writeFileSync(
      path.join(tmp, 'release.json'),
      `${JSON.stringify({version, verifiedAt: new Date().toISOString(), files, tree: releaseTree(tmp)}, null, 2)}\n`,
    );

    const dest = path.join(root, version);
    try {
      fs.renameSync(tmp, dest);
    } catch {
      // A finished release already holds the name; keep that one.
    }
    return (
      cachedRelease(version, cacheDir) ?? {
        version,
        reason: 'it could not be saved in the cache',
      }
    );
  } catch (error) {
    return {
      version,
      reason: `installing it failed (${error instanceof Error ? error.message : String(error)})`,
    };
  } finally {
    fs.rmSync(tmp, {recursive: true, force: true});
  }
}

/**
 * One sentence on why npm failed.
 * @param {NpmResult} result
 * @returns {string}
 */
function npmFailure(result) {
  if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') {
    return 'npm, which installs releases, was not found';
  }
  const text = `${result.stderr}\n${result.stdout}`;
  if (/E404|404 Not Found|No matching version|ETARGET/i.test(text)) {
    return 'the registry does not have it';
  }
  if (
    /ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|offline|network/i.test(
      text,
    )
  ) {
    return 'the registry could not be reached';
  }
  return 'the package manager could not install it';
}