Skip to content

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

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

/**
 * @file One test per row of AST-081's "Who answers when global and project
 * copies meet" table (spec AST-081 FR11). Each row runs real copies of this
 * CLI, packed the way it is published and labeled with test versions, in the
 * install layouts the row names, with a private home folder, cache, and
 * search path, and checks who answered and what the run printed.
 *
 * Rows that depend on an operating system's own file system (G25, G26) test
 * their path rules here; on macOS and Windows themselves they run only in
 * the cross-platform smoke workflow.
 */

import {afterAll, afterEach, beforeAll, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {spawn, spawnSync} from 'node:child_process';
import {
  globalCli,
  packedCli,
  placeCli,
  recyclePlacedCopies,
  releasePackedCli,
  seedPackedRelease,
  startRegistry,
} from '../test-utils/global-local-fixtures.mjs';
import {
  CLI_VERSION,
  cleanupFixtures,
  installCore,
  project,
  tempDir,
  writeJson,
} from '../test-utils/release-fixtures.mjs';
import {installPlaceOf, isGlobalCopy} from '../foundation/release/choose.mjs';
import {globalUpgradeCommand} from '../foundation/release/notices.mjs';
import {relativeWithin, samePath} from '../foundation/fs/path-compare.mjs';
import {userCacheDir} from '../foundation/env/user-dirs.mjs';
import {astryxCommandsOnSearchPath} from '../foundation/env/search-path.mjs';
import {npmCommand, tryLock} from '../foundation/release/cache.mjs';
import {LEASE_SILENCE_MS} from '../foundation/release/lock-lease.mjs';

const POSIX = process.platform !== 'win32';
const ROOT = typeof process.getuid === 'function' && process.getuid() === 0;
const OFFLINE = 'http://127.0.0.1:9/';

beforeAll(() => {
  packedCli();
}, 120_000);
/**
 * Every private computer the running test made, settled before cleanup.
 * @type {ReturnType<typeof computer>[]}
 */
const computers = [];
// The hook's own limit is above the wait's 60 s, so a stuck step fails with
// the message below and its folders are still removed.
afterEach(async () => {
  const busy = await settleBackgroundSteps(computers.splice(0));
  try {
    recyclePlacedCopies({keep: busy.length === 0});
  } finally {
    cleanupFixtures();
  }
  if (busy.length > 0) {
    throw new Error(
      `A background step was still writing into ${busy.join(', ')} 60 s after the test: it is stuck.`,
    );
  }
}, 90_000);
afterAll(() => {
  releasePackedCli();
});

/**
 * A private computer: a home folder, a cache, and a search path.
 * @param {{path?: string[]}} [options]
 */
function computer(options = {}) {
  const home = tempDir('home');
  const cache = path.join(home, '.cache');
  // A `node` command for scripts that start with `#!/usr/bin/env node`, and
  // the runner's npm, linked to its entry file as distributions install it,
  // so a run finds npm wherever this Node keeps it.
  const nodeBin = tempDir('node-bin');
  fs.symlinkSync(process.execPath, path.join(nodeBin, 'node'));
  const npm = npmCommand();
  if (POSIX && npm.prefix.length > 0) {
    fs.symlinkSync(npm.prefix[0], path.join(nodeBin, 'npm'));
  }
  const pc = {
    home,
    cache,
    /** The `astryx` cache folder global mode uses. */
    astryxCache: path.join(cache, 'astryx'),
    path: [...(options.path ?? []), nodeBin],
  };
  computers.push(pc);
  return pc;
}

/**
 * Wait until no background step a run started still writes into these
 * computers' home folders: one that outlived its test would put the removed
 * home folder back, left behind in the system temp directory. A step is done
 * once it has released the state file's locks and, for the computer-level
 * agent text, recorded the release it wrote. The CLI starts each step
 * detached and keeps no handle to it, so this reads what the step records.
 * @param {ReturnType<typeof computer>[]} pcs
 * @returns {Promise<string[]>} the home folders a step still writes into
 *   after 60 s
 */
async function settleBackgroundSteps(pcs) {
  const deadline = Date.now() + 60_000;
  /** @type {string[]} */
  const busy = [];
  for (const pc of pcs) {
    const stateDir = path.join(pc.home, '.config', 'astryx');
    const writing = () => {
      if (
        fs.existsSync(path.join(stateDir, '.lock-check')) ||
        fs.existsSync(path.join(stateDir, '.lock-state'))
      ) {
        return true;
      }
      const {agentText} = readState(pc);
      return (
        agentText?.attemptFor !== undefined &&
        agentText.writtenBy !== agentText.attemptFor
      );
    };
    while (writing() && Date.now() < deadline) {
      await new Promise(done => setTimeout(done, 50));
    }
    if (writing()) busy.push(pc.home);
  }
  return busy;
}

/**
 * The environment a run gets on a private computer.
 * @param {ReturnType<typeof computer>} pc
 * @param {Record<string, string | undefined>} [env]
 */
function envOf(pc, env = {}) {
  const base = Object.fromEntries(
    Object.entries(process.env).filter(
      // A proxy would carry the request for the local test registry away.
      ([k]) =>
        !/^(?:npm_|XDG_|ASTRYX|CI$|NO_UPDATE_NOTIFIER$|(?:https?|all|no)_proxy$)/iu.test(
          k,
        ),
    ),
  );
  return {
    ...base,
    HOME: pc.home,
    USERPROFILE: pc.home,
    XDG_CACHE_HOME: pc.cache,
    XDG_CONFIG_HOME: path.join(pc.home, '.config'),
    PATH: pc.path.join(path.delimiter),
    npm_config_registry: OFFLINE,
    npm_config_update_notifier: 'false',
    // An unreachable registry fails at once instead of after npm's backoff.
    npm_config_fetch_retry_mintimeout: '50',
    npm_config_fetch_retry_maxtimeout: '100',
    NO_COLOR: '1',
    ...env,
  };
}

/**
 * Run an `astryx` entry file with node, on a private computer.
 * @param {string} bin
 * @param {string[]} args
 * @param {{cwd: string, pc: ReturnType<typeof computer>, env?: Record<string, string | undefined>}} options
 */
function run(bin, args, {cwd, pc, env = {}}) {
  const result = spawnSync(process.execPath, [bin, ...args], {
    cwd,
    encoding: 'utf8',
    env: envOf(pc, env),
    timeout: 60_000,
  });
  return {
    status: result.status,
    stdout: result.stdout.trim(),
    stderr: result.stderr,
    /** The stderr lines that start with `astryx: `. */
    lines: result.stderr
      .split(/\r?\n/u)
      .filter(line => line.startsWith('astryx: ')),
    /** The update notice lines (FR10). */
    notice: result.stderr
      .split(/\r?\n/u)
      .filter(line =>
        /^(?:A new release of Astryx|To upgrade|The astryx command)/u.test(
          line,
        ),
      ),
  };
}

/**
 * A project with Core installed at `core`, and its own CLI at `cli`.
 * @param {{core?: string, cli?: string, brokenCli?: string, declare?: Record<string, string>}} spec
 */
function makeProject({core, cli, brokenCli, declare}) {
  const deps = {
    ...(core ? {'@astryxdesign/core': core} : {}),
    ...(cli ? {'@astryxdesign/cli': cli} : {}),
    ...(brokenCli ? {'@astryxdesign/cli': brokenCli} : {}),
    ...declare,
  };
  const dir = project(tempDir('project'), deps);
  if (core) installCore(dir, core);
  if (cli)
    placeCli(path.join(dir, 'node_modules', '@astryxdesign', 'cli'), cli);
  // A project CLI that cannot start: its package, with no astryx command.
  if (brokenCli) {
    writeJson(
      path.join(dir, 'node_modules', '@astryxdesign', 'cli', 'package.json'),
      {
        name: '@astryxdesign/cli',
        version: brokenCli,
      },
    );
  }
  return dir;
}

/**
 * What discover lists as available beyond the official Astryx list, which it
 * always reads.
 * @param {any} discover
 * @returns {any[]}
 */
const notOfficial = discover =>
  (discover.meta?.available ?? []).filter(
    (/** @type {any} */ entry) => entry.source !== 'Astryx',
  );

/** doctor's fix where no install command fits (spec AST-081 FR2). */
const DOCTOR_RUN_FROM_PROJECT =
  "Run this from the Astryx project's folder, or declare an Astryx package in this folder's package.json to make it a project of its own.";

/**
 * The hint's advice in a folder whose package.json is not the project's: the
 * same words as doctor's, naming no command (spec AST-081 FR5).
 */
const RUN_FROM_PROJECT = DOCTOR_RUN_FROM_PROJECT;

/**
 * The once-a-day hint in a project with no CLI of its own.
 * @param {string} answered
 * @param {string} core
 */
const noCliHint = (answered, core) =>
  `astryx: this project has no Astryx CLI installed; answered by CLI ${answered} while its Core is ${core}. To match, run: npm install @astryxdesign/cli@${core}`;

/** @param {string} version */
const handedTo = version => (/** @type {string} */ from) =>
  `astryx: answered by this project's CLI ${version}, handed over from CLI ${from}`;
/** @param {string} version */
const matchedLine = version =>
  `astryx: answered by CLI ${version} with Core ${version}, the release that matches this project's Core`;
/** @param {string} version */
const outsideLine = version =>
  `astryx: answered by CLI ${version} with Core ${version}, outside a project`;

/**
 * Every file under `dir`, for before-and-after comparisons.
 * @param {string} dir
 * @returns {string[]}
 */
function filesIn(dir) {
  /** @type {string[]} */
  const out = [];
  const walk = (/** @type {string} */ d) => {
    for (const entry of fs.readdirSync(d, {withFileTypes: true})) {
      const p = path.join(d, entry.name);
      if (entry.isDirectory()) walk(p);
      else out.push(path.relative(dir, p));
    }
  };
  walk(dir);
  return out.sort();
}

/**
 * Write the global copy's state.
 * @param {ReturnType<typeof computer>} pc
 * @param {Record<string, unknown>} state
 */
function globalState(pc, state) {
  writeJson(path.join(pc.home, '.config', 'astryx', 'state.json'), state);
}

/**
 * The saved state.
 * @param {ReturnType<typeof computer>} pc
 * @returns {Record<string, any>}
 */
function readState(pc) {
  try {
    return JSON.parse(
      fs.readFileSync(
        path.join(pc.home, '.config', 'astryx', 'state.json'),
        'utf8',
      ),
    );
  } catch {
    return {};
  }
}

/**
 * An integration (by default `@acme/widgets`) installed in `root`'s
 * node_modules, with one doc topic; `manifest` replaces its manifest's text.
 * @param {string} root
 * @param {{topic: string, peers?: Record<string, string>, name?: string, manifest?: string}} options
 */
function acmeWidgets(root, {topic, peers, name = '@acme/widgets', manifest}) {
  const dir = path.join(root, 'node_modules', ...name.split('/'));
  writeJson(path.join(dir, 'package.json'), {
    name,
    version: '1.0.0',
    ...(peers ? {peerDependencies: peers} : {}),
  });
  fs.writeFileSync(
    path.join(dir, 'astryx.integration.mjs'),
    manifest ?? "export default {docs: './docs'};\n",
  );
  fs.mkdirSync(path.join(dir, 'docs'), {recursive: true});
  fs.writeFileSync(
    path.join(dir, 'docs', `${topic}.doc.mjs`),
    `export const docs = ${JSON.stringify({
      type: 'generic',
      name: topic,
      title: 'Deploying',
      description: 'How to ship an app built with Acme widgets.',
      category: 'guide',
      sections: [
        {
          title: 'Overview',
          content: [{type: 'prose', text: 'Push the button.'}],
        },
      ],
    })};\n`,
  );
  return dir;
}

/** The two lines of a newer-release notice. */
const available = (/** @type {string} */ cur, /** @type {string} */ next) =>
  `A new release of Astryx is available: ${cur} → ${next}`;

describe.skipIf(!POSIX)(
  'who answers when global and project copies meet',
  () => {
    it('G1 global copy newer than the project CLI, which matches its Core', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.1', {root: pc.home});
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.status).toBe(0);
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([handedTo('9.0.0')('9.0.1')]);
    });

    it('G2 global copy older than the project CLI', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({core: '9.0.1', cli: '9.0.1'});
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.1');
      expect(r.lines).toEqual([handedTo('9.0.1')('9.0.0')]);
    });

    it("G3 the project CLI differs from its Core: the project's own CLI answers, as before global mode", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      seedPackedRelease(pc.astryxCache, '9.0.1');
      const dir = makeProject({core: '9.0.1', cli: '9.0.0'});
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([handedTo('9.0.0')('9.0.5')]);
    });

    it('G4 Core only, no CLI: the copy that started the run answers, as released, with a hint once a day; nothing is installed', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({core: '9.0.1'});
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([noCliHint('9.0.0', '9.0.1')]);
      // Once a day per project.
      expect(run(g.bin, ['--version'], {cwd: dir, pc}).lines).toEqual([]);
      const json = run(g.bin, ['docs', '--json'], {cwd: dir, pc});
      expect(JSON.parse(json.stdout).meta.answeredBy).toEqual({
        cli: '9.0.0',
        core: '9.0.1',
        copy: 'starting',
      });
      // Nothing is installed for the project (the global copy's own Core
      // step, G52, is the only thing that may touch the cache).
      expect(
        fs.existsSync(path.join(pc.astryxCache, 'releases', '9.0.1')),
      ).toBe(false);
      expect(
        fs.existsSync(
          path.join(pc.astryxCache, 'releases', '.failed-9.0.1.json'),
        ),
      ).toBe(false);
      // A copy equal to the project's Core prints no hint.
      const same = makeProject({core: '9.0.0'});
      expect(run(g.bin, ['--version'], {cwd: same, pc}).lines).toEqual([]);
    });

    it('G5 a fresh clone, nothing installed: the copy that started the run answers, naming the Core its lockfile records, writing nothing there', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({declare: {'@astryxdesign/core': '^9.0.0'}});
      writeJson(path.join(dir, 'package-lock.json'), {
        lockfileVersion: 3,
        packages: {
          '': {dependencies: {'@astryxdesign/core': '^9.0.0'}},
          'node_modules/@astryxdesign/core': {version: '9.0.1'},
        },
      });
      const before = filesIn(dir);
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([noCliHint('9.0.0', '9.0.1')]);
      // A command that reads Core uses the answering release's own Core; when
      // it cannot be downloaded, the error says so for this project.
      const offline = run(g.bin, ['component', 'Button', '--json'], {
        cwd: dir,
        pc,
      });
      const error = JSON.parse(offline.stdout);
      expect(error.code).toBe('ERR_VERSIONS_UNAVAILABLE');
      expect(error.error).toMatch(
        /^This project has no Core installed, and Core 9\.0\.0 could not be downloaded \(.+\)\. Install the project's dependencies, then run again\.$/u,
      );
      expect(error.error).not.toMatch(/Outside a project/u);
      expect(filesIn(dir)).toEqual(before);
    });

    it("outside a project, a render whose page needs Core says the answering release's Core could not be downloaded", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = tempDir('page');
      fs.writeFileSync(
        path.join(dir, 'page.jsx'),
        "import {Button} from '@astryxdesign/core';\nexport default () => <Button label=\"Go\" />;\n",
      );
      const r = run(g.bin, ['experimental', 'render', 'page.jsx', '--json'], {
        cwd: dir,
        pc,
      });
      const error = JSON.parse(r.stdout);
      expect(error.code).toBe('ERR_VERSIONS_UNAVAILABLE');
      expect(error.error).toMatch(
        /^Core 9\.0\.0 could not be (?:installed|downloaded).*\. Outside a project, commands that read Core use the Core of the release that answers; run again when the package registry can be reached\.$/u,
      );
      expect(fs.existsSync(path.join(dir, 'page.html'))).toBe(false);
    });

    it("in a fresh clone, doctor names the lockfile's Core as the daily hint and notice do", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.5',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check: one would ask
        // the unreachable test registry, and its failure, recorded whenever
        // npm gives up, would join doctor's newest-release line.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      const dir = makeProject({declare: {'@astryxdesign/core': '^9.0.0'}});
      writeJson(path.join(dir, 'package-lock.json'), {
        lockfileVersion: 3,
        packages: {
          '': {dependencies: {'@astryxdesign/core': '^9.0.0'}},
          'node_modules/@astryxdesign/core': {version: '9.0.1'},
        },
      });
      const notice = run(g.bin, ['--version'], {cwd: dir, pc}).notice;
      expect(notice[1]).toBe(
        'To upgrade, run: npm install @astryxdesign/[email protected] @astryxdesign/[email protected], then npx astryx upgrade --from 9.0.1 --apply',
      );
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: dir, pc}).stdout,
      );
      const check = (/** @type {string} */ id) =>
        doctor.data.checks.find((/** @type {any} */ c) => c.id === id);
      // FR2's warning, with the Core the lockfile records.
      expect(check('version-alignment')).toMatchObject({
        status: 'warn',
        message:
          'This project has no Astryx CLI installed; CLI 9.0.0, the one you started, answered while its Core is 9.0.1.',
        fix: 'To match, run: npm install @astryxdesign/[email protected].',
      });
      // The same release and upgrade step as the notice.
      expect(check('newest-release').message).toBe(
        'This project uses Astryx 9.0.1; 9.0.5 is the newest.',
      );
      expect(check('newest-release').fix).toContain(
        'npx astryx upgrade --from 9.0.1 --apply',
      );
    });

    it("in a tool folder that installs its own Core inside a project, the hint and doctor say to run from the project's folder, and the notice upgrades the project", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.7',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      const app = makeProject({core: '9.0.1'});
      writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});
      const tool = path.join(app, 'tools', 'codegen');
      writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
      installCore(tool, '9.0.5');
      const before = fs.readFileSync(path.join(tool, 'package.json'), 'utf8');

      const r = run(g.bin, ['--version'], {cwd: tool, pc});
      expect(r.lines).toContain(
        `astryx: this project has no Astryx CLI installed; answered by CLI 9.0.0 while its Core is 9.0.5. ${RUN_FROM_PROJECT}`,
      );
      expect(r.notice).toEqual([
        'A new release of Astryx is available: 9.0.1 → 9.0.7',
        `To upgrade, run: cd ${app} && npm install @astryxdesign/[email protected] @astryxdesign/[email protected], then cd ${app} && npx astryx upgrade --from 9.0.1 --apply`,
      ]);
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,
      );
      // The same comparison and Core as the hint: the Core the run reads.
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'version-alignment',
        ),
      ).toMatchObject({
        status: 'warn',
        message:
          'This project has no Astryx CLI installed; CLI 9.0.0, the one you started, answered while its Core is 9.0.5.',
        fix: DOCTOR_RUN_FROM_PROJECT,
      });
      expect(doctor.meta.answeredBy.core).toBe('9.0.5');
      // Nothing above suggests adding Astryx to the tool's own package.json.
      expect(
        [...r.lines, ...r.notice].some(line => /run: npm install/u.test(line)),
      ).toBe(false);
      expect(fs.readFileSync(path.join(tool, 'package.json'), 'utf8')).toBe(
        before,
      );
    });

    it('in a tool folder whose Core matches the CLI inside a project on another Core, neither the hint nor doctor warns', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const app = makeProject({core: '9.0.1'});
      writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});
      const tool = path.join(app, 'tools', 'codegen');
      writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
      installCore(tool, '9.0.0');

      const r = run(g.bin, ['--version'], {cwd: tool, pc});
      expect(r.lines.filter(line => line.includes('no Astryx CLI'))).toEqual(
        [],
      );
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,
      );
      const check = doctor.data.checks.find(
        (/** @type {any} */ c) => c.id === 'version-alignment',
      );
      expect(check.status).toBe('info');
      expect(check).not.toHaveProperty('fix');
    });

    it('in a folder with no package.json inside a home folder that installs Astryx, gives no project advice', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.7',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      writeJson(path.join(pc.home, 'package.json'), {
        name: 'home',
        dependencies: {'@astryxdesign/core': '9.0.1'},
      });
      writeJson(path.join(pc.home, 'package-lock.json'), {lockfileVersion: 3});
      installCore(pc.home, '9.0.1');
      const folder = path.join(pc.home, 'notes');
      fs.mkdirSync(folder, {recursive: true});

      const r = run(g.bin, ['--version'], {cwd: folder, pc});
      expect(r.lines.filter(line => line.includes('no Astryx CLI'))).toEqual(
        [],
      );
      expect(r.notice).toEqual([]);
    });

    it("in a tool folder whose project installs its own CLI, doctor's alignment fix points at the project, not at a command that leaves the warning", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const app = makeProject({core: '9.0.1', cli: '9.0.0'});
      writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});
      const tool = path.join(app, 'tools', 'codegen');
      writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
      installCore(tool, '9.0.5');

      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,
      );
      const check = doctor.data.checks.find(
        (/** @type {any} */ c) => c.id === 'version-alignment',
      );
      expect(check).toMatchObject({
        status: 'warn',
        fix: DOCTOR_RUN_FROM_PROJECT,
      });
      // The message keeps naming the Core this folder reads.
      expect(check.message).toContain('Core is 9.0.5');
    });

    it('in a folder that installs Core with no Astryx project above, gives no install advice', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.7',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      const tool = tempDir('tool');
      writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
      writeJson(path.join(tool, 'package-lock.json'), {lockfileVersion: 3});
      installCore(tool, '9.0.5');

      const r = run(g.bin, ['--version'], {cwd: tool, pc});
      expect(r.lines.filter(line => line.includes('To match'))).toEqual([]);
      expect(r.notice).toEqual([]);
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: tool, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'version-alignment',
        ),
      ).toMatchObject({
        status: 'warn',
        fix: DOCTOR_RUN_FROM_PROJECT,
      });
      // The skip says why, so doctor does not claim nothing newer is known.
      expect(readState(pc).noticeSkips?.project?.reason).toBe('no-project');
    });

    it("in a member its workspace lists, which declares no Astryx package, the advice stays the member's own, as before", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.7',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      const root = makeProject({core: '9.0.1'});
      const rootPkg = JSON.parse(
        fs.readFileSync(path.join(root, 'package.json'), 'utf8'),
      );
      writeJson(path.join(root, 'package.json'), {
        ...rootPkg,
        workspaces: ['apps/*'],
      });
      writeJson(path.join(root, 'package-lock.json'), {lockfileVersion: 3});
      const member = path.join(root, 'apps', 'web');
      writeJson(path.join(member, 'package.json'), {name: 'web'});
      installCore(member, '9.0.5');

      const r = run(g.bin, ['--version'], {cwd: member, pc});
      const all = [...r.lines, ...r.notice].join('\n');
      expect(all).not.toContain(`cd ${root}`);
      expect(r.lines).toContain(noCliHint('9.0.0', '9.0.5'));
    });

    it('G6 the installed Core wins over a lockfile that disagrees, for the release a project whose CLI cannot start gets', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      seedPackedRelease(pc.astryxCache, '9.0.1');
      const dir = makeProject({core: '9.0.1', brokenCli: '9.0.0'});
      writeJson(path.join(dir, 'package-lock.json'), {
        lockfileVersion: 3,
        packages: {'node_modules/@astryxdesign/core': {version: '9.0.0'}},
      });
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.1');
      expect(r.lines).toEqual([matchedLine('9.0.1')]);
    });

    it('G7 a workspace member with its own Core but no CLI of its own, and any other member, use the root CLI', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      seedPackedRelease(pc.astryxCache, '9.0.1');
      const root = makeProject({core: '9.0.0', cli: '9.0.0'});
      const member = path.join(root, 'packages', 'app');
      project(member, {'@astryxdesign/core': '9.0.1'});
      installCore(member, '9.0.1');
      const other = path.join(root, 'packages', 'docs');
      fs.mkdirSync(other, {recursive: true});
      expect(run(g.bin, ['--version'], {cwd: member, pc}).stdout).toBe('9.0.0');
      const r = run(g.bin, ['--version'], {cwd: other, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([handedTo('9.0.0')('9.0.5')]);
    });

    it('G8 a folder inside another project answers with the enclosing project (the released read reach)', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      const root = makeProject({core: '9.0.0', cli: '9.0.0'});
      const nested = path.join(root, 'apps', 'nested');
      project(nested, {'@astryxdesign/core': '9.0.1'});
      fs.mkdirSync(path.join(root, 'vendor', 'repo', '.git'), {
        recursive: true,
      });
      for (const cwd of [nested, path.join(root, 'vendor', 'repo')]) {
        expect(run(g.bin, ['--version'], {cwd, pc}).stdout).toBe('9.0.0');
      }

      // What prints there (spec AST-040 FR9): an enclosing project with no
      // CLI of its own and a Core the global copy does not match. A cloned
      // repository with its own .git belongs to no project, so it gets no
      // hint and no notice; a tool folder inside the project is told to run
      // from the project's folder.
      const pc2 = computer();
      const g2 = globalCli('npm', '9.0.0', {root: pc2.home});
      globalState(pc2, {
        latest: '9.0.7',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      const app = makeProject({core: '9.0.1'});
      writeJson(path.join(app, 'package-lock.json'), {lockfileVersion: 3});
      const clone = path.join(app, 'vendor', 'repo');
      fs.mkdirSync(path.join(clone, '.git'), {recursive: true});
      const inClone = run(g2.bin, ['--version'], {cwd: clone, pc: pc2});
      expect(inClone.stdout).toBe('9.0.0');
      expect(
        inClone.lines.filter(line => line.includes('no Astryx CLI')),
      ).toEqual([]);
      expect(inClone.notice).toEqual([]);
      const tool = path.join(app, 'tools', 'codegen');
      writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
      installCore(tool, '9.0.5');
      expect(run(g2.bin, ['--version'], {cwd: tool, pc: pc2}).lines).toContain(
        `astryx: this project has no Astryx CLI installed; answered by CLI 9.0.0 while its Core is 9.0.5. ${RUN_FROM_PROJECT}`,
      );
    });

    it('G9 outside a project: every copy answers itself, the global copy included, whatever releases are cached', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      seedPackedRelease(pc.astryxCache, '9.0.2');
      globalState(pc, {firstRunAt: Date.now()});
      const empty = tempDir('empty');
      const r = run(g.bin, ['--version'], {cwd: empty, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([outsideLine('9.0.0')]);
      const runner = placeCli(
        path.join(
          tempDir('npx'),
          '_npx',
          'abc',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.3',
      );
      const own = run(runner.bin, ['--version'], {cwd: empty, pc});
      expect(own.stdout).toBe('9.0.3');
      expect(own.lines).toEqual([outsideLine('9.0.3')]);
    });

    it("G10 a version typed on a package runner: exactly that release outside a project, the project's release inside one", () => {
      const pc = computer();
      const runner = placeCli(
        path.join(
          tempDir('npx'),
          '_npx',
          'def',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.3',
      );
      expect(
        run(runner.bin, ['--version'], {cwd: tempDir('empty'), pc}).stdout,
      ).toBe('9.0.3');
      const dir = makeProject({core: '9.0.1', cli: '9.0.1'});
      const r = run(runner.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.1');
      expect(r.lines).toEqual([handedTo('9.0.1')('9.0.3')]);
    });

    it('G11 a global copy that predates the hand-off answers itself; newer copies and doctor name its replacement, even in a fresh home', () => {
      const pc = computer();
      // A release from before the hand-off: no release-choice module.
      const old = globalCli('npm', '9.0.0', {root: pc.home});
      fs.rmSync(path.join(old.dir, 'foundation', 'release', 'choose.mjs'));
      pc.path.unshift(old.binDir);
      const dir = makeProject({core: '9.0.1', cli: '9.0.1'});
      const projectBin = path.join(
        dir,
        'node_modules',
        '@astryxdesign',
        'cli',
        'clients',
        'cli',
        'bin',
        'astryx.mjs',
      );
      const r = run(projectBin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.1');
      expect(r.lines).toEqual([]);
      expect(r.notice).toEqual([
        'The astryx command on this computer runs CLI 9.0.0, which answers every folder itself.',
        'To upgrade, run: npm i -g --prefix ~/.npm-global @astryxdesign/cli@latest',
      ]);
      expect(run(projectBin, ['--version'], {cwd: dir, pc}).notice).toEqual([]);
      const doctor = JSON.parse(
        run(projectBin, ['doctor', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'cli-on-path',
        ),
      ).toMatchObject({
        status: 'warn',
        fix: 'To upgrade, run: `npm i -g --prefix ~/.npm-global @astryxdesign/cli@latest`.',
      });
    });

    it('G12 two global installs: the first on the search path starts and answers itself; doctor lists both', () => {
      const pc = computer();
      const npm = globalCli('npm', '9.0.0', {root: pc.home});
      const pnpm = globalCli('pnpm', '9.0.1', {root: pc.home});
      pc.path.unshift(npm.binDir, pnpm.binDir);
      const empty = tempDir('empty');
      expect(run(npm.bin, ['--version'], {cwd: empty, pc}).stdout).toBe(
        '9.0.0',
      );
      expect(run(pnpm.bin, ['--version'], {cwd: empty, pc}).stdout).toBe(
        '9.0.1',
      );
      const doctor = JSON.parse(
        run(npm.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      const check = doctor.data.checks.find(
        (/** @type {any} */ c) => c.id === 'cli-on-path',
      );
      expect(check.status).toBe('pass');
      expect(check.message).toContain(path.join(npm.binDir, 'astryx'));
      expect(check.message).toContain(
        `Later on the search path: ${path.join(pnpm.binDir, 'astryx')} (CLI 9.0.1)`,
      );
    });

    it('G13 an astryx earlier on the search path that is not the Astryx CLI: init --user and doctor warn', () => {
      const pc = computer();
      const other = tempDir('other');
      fs.writeFileSync(path.join(other, 'astryx'), '#!/bin/sh\necho other\n');
      fs.chmodSync(path.join(other, 'astryx'), 0o755);
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      pc.path.unshift(other, g.binDir);
      const empty = tempDir('empty');
      const init = JSON.parse(
        run(g.bin, ['--json', 'init', '--user'], {cwd: empty, pc}).stdout,
      );
      expect(init.data.warnings[0]).toContain('No `astryx` command');
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'cli-on-path',
        ).status,
      ).toBe('warn');
    });

    // One test for each layout: each starts the CLI three times.
    for (const [layout, step] of /** @type {const} */ ([
      // The npm layout is a prefix in the home folder, so the step names it.
      ['npm', 'npm i -g --prefix ~/.npm-global @astryxdesign/cli'],
      ['pnpm', 'pnpm add -g @astryxdesign/cli'],
      ['bun', 'bun add -g @astryxdesign/cli'],
    ])) {
      it(`the skill outlives the CLI installed for the computer (${layout}): it repeats the step that installed it, and doctor names it too`, () => {
        const pc = computer();
        let g;
        if (layout === 'bun') {
          // Bun's global folder, as `bun add -g` makes it.
          const global = path.join(pc.home, '.bun', 'install', 'global');
          writeJson(path.join(global, 'package.json'), {
            dependencies: {'@astryxdesign/cli': '9.0.0'},
          });
          fs.writeFileSync(path.join(global, 'bun.lock'), '{}');
          const placed = placeCli(
            path.join(global, 'node_modules', '@astryxdesign', 'cli'),
            '9.0.0',
          );
          const binDir = path.join(pc.home, '.bun', 'bin');
          fs.mkdirSync(binDir, {recursive: true});
          fs.symlinkSync(placed.bin, path.join(binDir, 'astryx'));
          g = {...placed, binDir};
        } else {
          g = globalCli(layout, '9.0.0', {root: pc.home});
        }
        pc.path.unshift(g.binDir);
        const empty = tempDir('empty');
        expect(run(g.bin, ['init', '--user'], {cwd: empty, pc}).status).toBe(0);
        const skill = path.join(
          pc.home,
          '.agents',
          'skills',
          'astryx',
          'SKILL.md',
        );
        expect(fs.readFileSync(skill, 'utf8')).toContain(
          `If \`astryx\` is not found, run \`${step}\` first.`,
        );
        // A restart removes the CLI installed for the computer and keeps the
        // home folder. The way back is a package runner, whose own temporary
        // copy answers; started directly, and with the runner's .bin folder
        // first on the search path, as npx and pnpm dlx put it. That copy
        // does not count, so doctor names the step either way.
        fs.rmSync(path.join(g.binDir, 'astryx'));
        fs.rmSync(g.dir, {recursive: true, force: true});
        pc.path.splice(pc.path.indexOf(g.binDir), 1);
        const runner = placeCli(
          path.join(
            tempDir('npx'),
            '_npx',
            'r1',
            'node_modules',
            '@astryxdesign',
            'cli',
          ),
          '9.0.0',
        );
        const runnerBin = path.join(
          path.dirname(path.dirname(runner.dir)),
          '.bin',
        );
        fs.mkdirSync(runnerBin, {recursive: true});
        fs.symlinkSync(runner.bin, path.join(runnerBin, 'astryx'));
        const agentText = () =>
          JSON.parse(
            run(runner.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
          ).data.checks.find(
            (/** @type {any} */ c) => c.id === 'computer-agent-text',
          );
        for (const first of [false, true]) {
          if (first) pc.path.unshift(runnerBin);
          const check = agentText();
          expect(check.message).toContain(
            'but no `astryx` command is on the search path',
          );
          expect(check.fix).toBe(
            `Run \`${step}\`, the step the skill names for when \`astryx\` is not found.`,
          );
        }
        pc.path.shift();
      });
    }

    // Volta's command is a shim of its own, not a link into the package, so
    // the search-path scan cannot trace it; an astryx on the search path that
    // cannot be traced may run the CLI, so doctor never calls it gone.
    it("on a working Volta install, doctor does not report the skill's CLI as gone", () => {
      const pc = computer();
      const g = globalCli('volta', '9.0.0', {root: pc.home});
      fs.rmSync(path.join(g.binDir, 'astryx'));
      fs.writeFileSync(
        path.join(g.binDir, 'astryx'),
        '#!/bin/sh\n# volta-shim\nexit 0\n',
      );
      fs.chmodSync(path.join(g.binDir, 'astryx'), 0o755);
      pc.path.unshift(g.binDir);
      const empty = tempDir('empty');
      expect(run(g.bin, ['init', '--user'], {cwd: empty, pc}).status).toBe(0);
      const check = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      ).data.checks.find(
        (/** @type {any} */ c) => c.id === 'computer-agent-text',
      );
      expect(check.message).toContain('matches this release');
      expect(check.message).not.toContain('no `astryx` command');
      expect(check.fix).toBeUndefined();
      // Run through a package runner's copy too, its .bin first on the
      // search path, as npx puts it: Volta's shim still counts.
      const runner = placeCli(
        path.join(
          tempDir('npx'),
          '_npx',
          'v1',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.0',
      );
      const runnerBin = path.join(
        path.dirname(path.dirname(runner.dir)),
        '.bin',
      );
      fs.mkdirSync(runnerBin, {recursive: true});
      fs.symlinkSync(runner.bin, path.join(runnerBin, 'astryx'));
      pc.path.unshift(runnerBin);
      const viaRunner = JSON.parse(
        run(runner.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      ).data.checks.find(
        (/** @type {any} */ c) => c.id === 'computer-agent-text',
      );
      expect(viaRunner.message).not.toContain('no `astryx` command');
      expect(viaRunner.fix).toBeUndefined();
    });

    // Any `astryx` the scan cannot trace, such as an asdf or mise shim, may
    // run the CLI: doctor stays quiet rather than call it gone.
    it("with an untraceable astryx shim on the search path, doctor run through a package runner does not report the skill's CLI as gone", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      pc.path.unshift(g.binDir);
      const empty = tempDir('empty');
      expect(run(g.bin, ['init', '--user'], {cwd: empty, pc}).status).toBe(0);
      pc.path.splice(pc.path.indexOf(g.binDir), 1);
      const shims = path.join(pc.home, '.asdf', 'shims');
      fs.mkdirSync(shims, {recursive: true});
      fs.writeFileSync(
        path.join(shims, 'astryx'),
        '#!/bin/sh\nexec asdf exec astryx "$@"\n',
      );
      fs.chmodSync(path.join(shims, 'astryx'), 0o755);
      pc.path.unshift(shims);
      const runner = placeCli(
        path.join(
          tempDir('npx'),
          '_npx',
          'a1',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.0',
      );
      const check = JSON.parse(
        run(runner.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      ).data.checks.find(
        (/** @type {any} */ c) => c.id === 'computer-agent-text',
      );
      expect(check.message).not.toContain('no `astryx` command');
      expect(check.fix).toBeUndefined();
    });

    it('with the global copy on the search path, doctor gives no restore report', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      pc.path.unshift(g.binDir);
      const empty = tempDir('empty');
      expect(run(g.bin, ['init', '--user'], {cwd: empty, pc}).status).toBe(0);
      const check = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      ).data.checks.find(
        (/** @type {any} */ c) => c.id === 'computer-agent-text',
      );
      expect(check.message).toContain('matches this release');
      expect(check.message).not.toContain('no `astryx` command');
      expect(check.fix).toBeUndefined();
    });

    it('two global installs of one release find the same skill current, and neither rewrites the step the other wrote', () => {
      const pc = computer();
      const npm = globalCli('npm', '9.0.0', {root: pc.home});
      const pnpm = globalCli('pnpm', '9.0.0', {root: pc.home});
      pc.path.unshift(npm.binDir, pnpm.binDir);
      const empty = tempDir('empty');
      const skill = path.join(
        pc.home,
        '.agents',
        'skills',
        'astryx',
        'SKILL.md',
      );
      expect(run(npm.bin, ['init', '--user'], {cwd: empty, pc}).status).toBe(0);
      const written = fs.readFileSync(skill, 'utf8');
      expect(written).toContain(
        'run `npm i -g --prefix ~/.npm-global @astryxdesign/cli` first.',
      );
      const fromPnpm = JSON.parse(
        run(pnpm.bin, ['--json', 'init', '--user'], {cwd: empty, pc}).stdout,
      );
      expect(
        fromPnpm.data.files.find((/** @type {any} */ f) => f.path === skill)
          .action,
      ).toBe('unchanged');
      expect(fs.readFileSync(skill, 'utf8')).toBe(written);
      const doctor = JSON.parse(
        run(pnpm.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-agent-text',
        ).message,
      ).toContain('matches this release');
    });

    it('G14 a Node version manager: each Node has its own global copy, which answers itself', () => {
      const pc = computer();
      for (const layout of /** @type {const} */ (['nvm', 'fnm', 'volta'])) {
        const copy = globalCli(layout, '9.0.0', {root: pc.home});
        expect(isGlobalCopy(copy.dir, pc.astryxCache)).toBe(true);
        expect(
          run(copy.bin, ['--version'], {cwd: tempDir('empty'), pc}).stdout,
        ).toBe('9.0.0');
      }
    });

    it('G15 a project pinned through a package manager shim: as for that project, and nothing written there', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      seedPackedRelease(pc.astryxCache, '9.0.1');
      const dir = makeProject({core: '9.0.1', brokenCli: '9.0.1'});
      const pkg = JSON.parse(
        fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
      );
      writeJson(path.join(dir, 'package.json'), {
        ...pkg,
        packageManager: '[email protected]',
      });
      const before = filesIn(dir);
      expect(run(g.bin, ['--version'], {cwd: dir, pc}).stdout).toBe('9.0.1');
      // A release that must be fetched and cannot be: the starting copy
      // answers, as before global mode, without touching the project.
      const missing = makeProject({core: '9.0.7', brokenCli: '9.0.7'});
      const missingBefore = filesIn(missing);
      const r = run(g.bin, ['--version'], {cwd: missing, pc});
      expect(r.status).toBe(0);
      expect(r.stdout).toBe('9.0.0');
      expect(filesIn(missing)).toEqual(missingBefore);
      expect(filesIn(dir)).toEqual(before);
    });

    it.skipIf(ROOT)(
      'G16 a global copy installed with administrator rights: nothing is written to its install folder',
      () => {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home});
        const prefix = path.join(pc.home, '.npm-global');
        const before = filesIn(prefix);
        fs.chmodSync(g.dir, 0o555);
        try {
          const r = run(g.bin, ['--version'], {cwd: tempDir('empty'), pc});
          expect(r.status).toBe(0);
          expect(r.stdout).toBe('9.0.0');
        } finally {
          fs.chmodSync(g.dir, 0o755);
        }
        expect(filesIn(prefix)).toEqual(before);
      },
    );

    it.skipIf(ROOT)(
      'G17 the cache cannot be written: the global copy still answers outside and in a Core-only project; when a project whose CLI cannot start needs a release, it answers instead, with a warning and copy fallback',
      () => {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home});
        fs.mkdirSync(pc.astryxCache, {recursive: true});
        fs.chmodSync(pc.astryxCache, 0o555);
        try {
          const outside = run(g.bin, ['--version'], {
            cwd: tempDir('empty'),
            pc,
          });
          expect(outside.status).toBe(0);
          expect(outside.stdout).toBe('9.0.0');
          const coreOnly = makeProject({core: '9.0.1'});
          expect(run(g.bin, ['--version'], {cwd: coreOnly, pc}).stdout).toBe(
            '9.0.0',
          );
          const dir = makeProject({core: '9.0.1', brokenCli: '9.0.1'});
          const text = run(g.bin, ['--version'], {cwd: dir, pc});
          expect(text.status).toBe(0);
          expect(text.stdout).toBe('9.0.0');
          expect(text.lines).toEqual([
            expect.stringMatching(
              /^astryx: could not get Astryx 9\.0\.1 to match this project's Core \(the release cache .* cannot be written.*\); answering with CLI 9\.0\.0 instead$/u,
            ),
          ]);
          const json = run(g.bin, ['docs', '--json'], {cwd: dir, pc});
          expect(json.status).toBe(0);
          expect(JSON.parse(json.stdout).meta.answeredBy.copy).toBe('fallback');
        } finally {
          fs.chmodSync(pc.astryxCache, 0o755);
        }
      },
    );

    it('G18 cache and configuration folders set by environment: absolute ones are used, relative ones ignored', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      const before = filesIn(dir);
      const r = run(g.bin, ['--version'], {
        cwd: dir,
        pc,
        env: {XDG_CACHE_HOME: 'rel-cache', XDG_CONFIG_HOME: 'rel-config'},
      });
      expect(r.status).toBe(0);
      expect(filesIn(dir)).toEqual(before);
      expect(fs.existsSync(path.join(pc.home, '.config', 'astryx'))).toBe(true);
      expect(
        userCacheDir({
          home: pc.home,
          platform: 'linux',
          env: {XDG_CACHE_HOME: '/abs'},
        }),
      ).toBe(path.join('/abs', 'astryx'));
    });

    it('G19 continuous integration (CI set, a fresh home): no check and no notice; the guide is written in the background', async () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const r = run(g.bin, ['--version'], {
        cwd: tempDir('empty'),
        pc,
        env: {CI: 'true'},
      });
      expect(r.lines).toEqual([outsideLine('9.0.0')]);
      expect(r.notice).toEqual([]);
      expect(readState(pc).checkedAt).toBeUndefined();
      expect(readState(pc).firstRunAt).toBeUndefined();
      const skill = path.join(
        pc.home,
        '.agents',
        'skills',
        'astryx',
        'SKILL.md',
      );
      for (let i = 0; i < 100 && !fs.existsSync(skill); i++) {
        await new Promise(done => setTimeout(done, 100));
      }
      expect(fs.readFileSync(skill, 'utf8')).toContain('name: astryx');
    });

    it.skipIf(ROOT)(
      'G20 a read-only home folder: the run answers, and nothing is written',
      () => {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home});
        fs.chmodSync(pc.home, 0o555);
        try {
          const r = run(g.bin, ['--version'], {cwd: tempDir('empty'), pc});
          expect(r.status).toBe(0);
          expect(r.stdout).toBe('9.0.0');
          expect(fs.existsSync(path.join(pc.home, '.agents'))).toBe(false);
        } finally {
          fs.chmodSync(pc.home, 0o755);
        }
      },
    );

    it("G21 a shared cache: another computer's lock is taken over once it goes unrenewed", () => {
      const lock = path.join(tempDir('cache'), 'releases', '.lock-9.0.1');
      fs.mkdirSync(lock, {recursive: true});
      writeJson(path.join(lock, 'owner.json'), {
        pid: 7,
        host: 'another-computer',
      });
      const t0 = Date.now();
      expect(tryLock(lock, {now: t0})).toBe(false);
      expect(tryLock(lock, {now: t0 + LEASE_SILENCE_MS - 1})).toBe(false);
      expect(tryLock(lock, {now: t0 + LEASE_SILENCE_MS})).toBe(true);
    });

    it('G22 a project behind the newest release: the notice after the command, once a day, after a real check of the registry', async () => {
      const registry = await startRegistry({
        versions: ['9.0.1', '9.0.5'],
        latest: '9.0.5',
      });
      try {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home});
        globalState(pc, {firstRunAt: Date.now() - 2 * 24 * 60 * 60_000});
        const env = {npm_config_registry: registry.url};
        run(g.bin, ['--version'], {cwd: tempDir('empty'), pc, env});
        // That run started two background steps: the check and the
        // computer-level agent text. Each takes the state file's lock to
        // record its result, so a later run's notice could find the lock
        // held. Wait for both completion records, not for a time: the
        // check's latest release with its lock released, and the agent
        // text written for this release.
        const stateDir = path.join(pc.home, '.config', 'astryx');
        const settled = () => {
          const state = readState(pc);
          return (
            state.latest === '9.0.5' &&
            state.agentText?.writtenBy === '9.0.0' &&
            !fs.existsSync(path.join(stateDir, '.lock-check')) &&
            !fs.existsSync(path.join(stateDir, '.lock-state'))
          );
        };
        const deadline = Date.now() + 150_000;
        while (!settled() && Date.now() < deadline) {
          await new Promise(done => setTimeout(done, 100));
        }
        expect(readState(pc).latest).toBe('9.0.5');
        expect(readState(pc).agentText?.writtenBy).toBe('9.0.0');
        // The check installed nothing.
        expect(
          fs.existsSync(path.join(pc.astryxCache, 'releases', '9.0.5')),
        ).toBe(false);
        const dir = makeProject({core: '9.0.1', cli: '9.0.1'});
        writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
        const json = run(g.bin, ['--version', '--json'], {cwd: dir, pc, env});
        expect(json.notice).toEqual([]);
        const first = run(g.bin, ['--version'], {cwd: dir, pc, env});
        expect(first.lines).toEqual([handedTo('9.0.1')('9.0.0')]);
        expect(first.notice).toEqual([
          available('9.0.1', '9.0.5'),
          'To upgrade, run: npm install @astryxdesign/[email protected] @astryxdesign/[email protected], then npx astryx upgrade --from 9.0.1 --apply',
        ]);
        // The notice comes after the command's own output.
        expect(first.stderr.trim().split('\n').at(-1)).toBe(first.notice[1]);
        expect(run(g.bin, ['--version'], {cwd: dir, pc, env}).notice).toEqual(
          [],
        );
      } finally {
        await registry.close();
      }
    }, 240_000);

    it("a host's door names the upgrade step of the project update notice, printed as the run ends (b32)", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.5',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: Date.now() - 2 * 24 * 60 * 60_000,
      });
      const dir = makeProject({core: '9.0.0'});
      writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
      // A host that runs the CLI inside its door, as the programmatic entry does.
      const host = path.join(tempDir('host'), 'host.mjs');
      fs.writeFileSync(
        host,
        [
          "import {pathToFileURL} from 'node:url';",
          `const at = rel => pathToFileURL(${JSON.stringify(g.dir)} + '/' + rel).href;`,
          "const {runWithCliDoor} = await import(at('foundation/env/cli-command.mjs'));",
          "const {startRun} = await import(at('foundation/release/handoff.mjs'));",
          `await runWithCliDoor('host astryx', () => startRun({cliRoot: ${JSON.stringify(g.dir)}, argv: ['--version']}));`,
          '',
        ].join('\n'),
      );
      const r = run(host, [], {cwd: dir, pc});
      expect(r.status).toBe(0);
      expect(r.notice).toEqual([
        available('9.0.0', '9.0.5'),
        'To upgrade, run: npm install @astryxdesign/[email protected] @astryxdesign/[email protected], then host astryx upgrade --from 9.0.0 --apply',
      ]);
    });

    it('G23 the newest release needs a newer Node: the global copy answers, and the notice and doctor name the Node first', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.5',
        latestNode: '>=99',
        checkOkAt: Date.now(),
        checkedAt: Date.now(),
        firstRunAt: Date.now(),
      });
      const empty = tempDir('empty');
      const r = run(g.bin, ['--version'], {cwd: empty, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.notice).toEqual([
        available('9.0.0', '9.0.5'),
        `To upgrade, install Node >=99 (this computer runs Node ${process.versions.node}), then run: npm i -g --prefix ~/.npm-global @astryxdesign/cli@latest`,
      ]);
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'newest-release',
        ),
      ).toMatchObject({
        status: 'info',
        fix: `To upgrade, install Node >=99 (this computer runs Node ${process.versions.node}), then run: npm i -g --prefix ~/.npm-global @astryxdesign/cli@latest.`,
      });
    });

    it('G24 a link to a project folder answers as the folder does', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      const link = path.join(tempDir('links'), 'app');
      fs.symlinkSync(dir, link, 'dir');
      const r = run(g.bin, ['--version'], {cwd: link, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([handedTo('9.0.0')('9.0.5')]);
    });

    it('G25 a file system that ignores letter case: paths compare without case there (path rules)', () => {
      for (const platform of /** @type {const} */ (['darwin', 'win32'])) {
        expect(samePath('/Users/Ada/App', '/users/ada/app', platform)).toBe(
          true,
        );
      }
      expect(samePath('/home/ada/App', '/home/ada/app', 'linux')).toBe(false);
      expect(
        relativeWithin(
          '/Users/Ada/Proj',
          '/users/ada/proj/node_modules',
          'darwin',
        ),
      ).toBe('node_modules');
      expect(
        relativeWithin(
          'C:\\Users\\Ada\\Proj',
          'c:\\users\\ada\\PROJ\\sub',
          'win32',
        ),
      ).toBe('sub');
    });

    it('G26 Windows paths and installs follow the same rules (path rules)', () => {
      expect(
        installPlaceOf(
          'C:\\Users\\ada\\AppData\\Roaming\\npm\\node_modules\\@astryxdesign\\cli',
        ),
      ).toEqual({
        runner: false,
        owner: 'C:\\Users\\ada\\AppData\\Roaming\\npm',
        knownGlobal: false,
      });
      expect(
        installPlaceOf(
          'C:\\Users\\ada\\AppData\\Local\\Yarn\\Data\\global\\node_modules\\@astryxdesign\\cli',
        ).knownGlobal,
      ).toBe(true);
      expect(
        installPlaceOf(
          'C:\\Users\\ada\\AppData\\Local\\npm-cache\\_npx\\1a2b\\node_modules\\@astryxdesign\\cli',
        ).runner,
      ).toBe(true);
      expect(
        userCacheDir({
          home: 'C:\\Users\\ada',
          platform: 'win32',
          env: {LOCALAPPDATA: 'C:\\Users\\ada\\AppData\\Local'},
        }),
      ).toBe('C:\\Users\\ada\\AppData\\Local\\astryx\\Cache');
      // npm's Windows shim names the package beside it.
      const bin = tempDir('winbin');
      const pkg = path.join(bin, 'node_modules', '@astryxdesign', 'cli');
      writeJson(path.join(pkg, 'package.json'), {
        name: '@astryxdesign/cli',
        version: '9.0.0',
      });
      fs.writeFileSync(
        path.join(bin, 'astryx.cmd'),
        '@ECHO off\r\n"%~dp0\\node_modules\\@astryxdesign\\cli\\clients\\cli\\bin\\astryx.mjs" %*\r\n',
      );
      expect(
        astryxCommandsOnSearchPath({searchPath: bin, platform: 'win32'}),
      ).toEqual([
        {
          file: path.join(bin, 'astryx.cmd'),
          astryx: true,
          cliRoot: pkg,
          version: '9.0.0',
          handsOff: false,
        },
      ]);
    });

    it('G27 a package script puts the project CLI first: it answers, whatever its version', () => {
      const pc = computer();
      seedPackedRelease(pc.astryxCache, '9.0.1');
      const dir = makeProject({core: '9.0.1', cli: '9.0.0'});
      const binDir = path.join(dir, 'node_modules', '.bin');
      fs.mkdirSync(binDir, {recursive: true});
      const projectBin = path.join(
        dir,
        'node_modules',
        '@astryxdesign',
        'cli',
        'clients',
        'cli',
        'bin',
        'astryx.mjs',
      );
      fs.symlinkSync(projectBin, path.join(binDir, 'astryx'));
      pc.path.unshift(binDir);
      const result = spawnSync('astryx', ['--version'], {
        cwd: dir,
        encoding: 'utf8',
        env: {
          ...Object.fromEntries(
            Object.entries(process.env).filter(
              ([key]) => !/^(?:npm_|XDG_|CI$|NO_UPDATE_NOTIFIER$)/iu.test(key),
            ),
          ),
          HOME: pc.home,
          XDG_CACHE_HOME: pc.cache,
          XDG_CONFIG_HOME: path.join(pc.home, '.config'),
          PATH: pc.path.join(path.delimiter),
          npm_config_registry: OFFLINE,
        },
      });
      expect(result.stdout.trim()).toBe('9.0.0');
    });

    it("G28 a Yarn Plug'n'Play project, whose own CLI Astryx cannot see, is answered by the copy that started the run", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({declare: {'@astryxdesign/core': '^9.0.0'}});
      fs.writeFileSync(path.join(dir, '.pnp.cjs'), '');
      fs.writeFileSync(
        path.join(dir, 'yarn.lock'),
        '__metadata:\n  version: 8\n\n"@astryxdesign/core@npm:^9.0.0":\n  version: 9.0.1\n',
      );
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([
        expect.stringMatching(
          /^astryx: this project has no Astryx CLI installed; answered by CLI 9\.0\.0 while its Core is 9\.0\.1\. To match, run: yarn add @astryxdesign\/cli@9\.0\.1$/u,
        ),
      ]);
    });

    it('G29 a package runner that reuses the global install answers as the global copy', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const r = run(g.bin, ['--version'], {
        cwd: tempDir('empty'),
        pc,
        env: {npm_command: 'exec', npm_lifecycle_event: 'npx'},
      });
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines).toEqual([outsideLine('9.0.0')]);
    });

    it('G30 init --user inside a project answers for the computer and writes nothing in the project', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      const before = filesIn(dir);
      const r = run(g.bin, ['init', '--user'], {cwd: dir, pc});
      expect(r.status).toBe(0);
      expect(r.lines).toEqual([
        'astryx: answered by CLI 9.0.5 with Core 9.0.5, for this computer',
      ]);
      expect(
        fs.existsSync(
          path.join(pc.home, '.claude', 'skills', 'astryx', 'SKILL.md'),
        ),
      ).toBe(true);
      expect(filesIn(dir)).toEqual(before);
    });

    it('G31 a damaged cached release is not used: the run installs it again, or, when it cannot, the starting copy answers instead', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const cached = seedPackedRelease(pc.astryxCache, '9.0.2');
      const dir = makeProject({core: '9.0.2', brokenCli: '9.0.2'});
      expect(run(g.bin, ['--version'], {cwd: dir, pc}).stdout).toBe('9.0.2');
      fs.rmSync(
        path.join(
          cached.dir,
          'node_modules',
          '@astryxdesign',
          'core',
          'package.json',
        ),
      );
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.status).toBe(0);
      expect(r.stdout).toBe('9.0.0');
      expect(r.lines.filter(l => l.includes('could not get'))).toEqual([
        expect.stringMatching(/^astryx: could not get Astryx 9\.0\.2 /u),
      ]);
    });

    it('G32 a workspace whose own CLI sits beside its own Core answers with that CLI', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const root = tempDir('repo');
      writeJson(path.join(root, 'package.json'), {name: 'repo', private: true});
      writeJson(path.join(root, 'packages', 'core', 'package.json'), {
        name: '@astryxdesign/core',
        version: '9.0.4',
      });
      placeCli(path.join(root, 'packages', 'cli'), '9.0.4');
      // The repository root and another member; `packages/cli` itself reads its
      // own node_modules, which these copies share with this checkout.
      const member = path.join(root, 'apps', 'site');
      fs.mkdirSync(member, {recursive: true});
      for (const cwd of [root, member]) {
        const r = run(g.bin, ['--version'], {cwd, pc});
        expect(r.stdout).toBe('9.0.4');
        expect(r.lines).toEqual([handedTo('9.0.4')('9.0.0')]);
      }
      // Inside the CLI's own package, whose node_modules links this
      // checkout's Core: label the workspace with that Core's version.
      const repo = tempDir('repo');
      writeJson(path.join(repo, 'package.json'), {name: 'repo', private: true});
      writeJson(path.join(repo, 'packages', 'core', 'package.json'), {
        name: '@astryxdesign/core',
        version: CLI_VERSION,
      });
      const own = placeCli(path.join(repo, 'packages', 'cli'), CLI_VERSION);
      for (const cwd of [own.dir, path.join(own.dir, 'foundation')]) {
        const r = run(g.bin, ['--version'], {cwd, pc});
        expect(r.stdout).toBe(CLI_VERSION);
        expect(r.lines).toEqual([handedTo(CLI_VERSION)('9.0.0')]);
      }
    });

    it('G33 the global copy behind the newest release: the notice after the command names the package manager that installed it', () => {
      for (const [layout, command] of /** @type {const} */ ([
        // The npm layout is a prefix in the home folder (`~/.npm-global`),
        // so the upgrade names it.
        ['npm', 'npm i -g --prefix ~/.npm-global @astryxdesign/cli@latest'],
        ['pnpm', 'pnpm add -g @astryxdesign/cli@latest'],
        ['volta', 'volta install @astryxdesign/cli@latest'],
      ])) {
        const pc = computer();
        const g = globalCli(layout, '9.0.0', {root: pc.home});
        globalState(pc, {
          latest: '9.0.5',
          checkOkAt: Date.now(),
          firstRunAt: Date.now(),
        });
        const empty = tempDir('empty');
        const r = run(g.bin, ['--version'], {cwd: empty, pc});
        expect(r.status).toBe(0);
        expect(r.notice).toEqual([
          available('9.0.0', '9.0.5'),
          `To upgrade, run: ${command}`,
        ]);
        expect(run(g.bin, ['--version'], {cwd: empty, pc}).notice).toEqual([]);
      }
      // A failed command prints no notice.
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      globalState(pc, {
        latest: '9.0.5',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: 0,
      });
      const failed = run(g.bin, ['no-such-command'], {
        cwd: tempDir('empty'),
        pc,
      });
      expect(failed.status).not.toBe(0);
      expect(failed.notice).toEqual([]);
    });

    it('G34 NO_UPDATE_NOTIFIER or CI set: no check and no notice, whatever is due', () => {
      for (const env of [{NO_UPDATE_NOTIFIER: '1'}, {CI: '1'}]) {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home});
        globalState(pc, {
          latest: '9.0.5',
          checkOkAt: 1,
          checkedAt: 1,
          firstRunAt: 1,
        });
        const r = run(g.bin, ['--version'], {cwd: tempDir('empty'), pc, env});
        expect(r.notice).toEqual([]);
        expect(readState(pc).checkedAt).toBe(1);
        expect(readState(pc).notifiedAt).toBeUndefined();
      }
    });

    it('G35 outside a project: an integration installed beside the global copy contributes its docs, components, and discover entry', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {
        topic: 'acme-deploying',
      });
      const empty = tempDir('empty');
      const docs = JSON.parse(
        run(g.bin, ['docs', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        docs.data.find((/** @type {any} */ t) => t.topic === 'acme-deploying'),
      ).toMatchObject({package: '@acme/widgets'});
      const discover = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(discover.data.map((/** @type {any} */ p) => p.name)).toContain(
        '@acme/widgets',
      );
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-integrations',
        ),
      ).toMatchObject({
        status: 'pass',
        message: 'Used outside a project: @acme/[email protected].',
      });
    });

    it("G36 inside a project: an integration installed for the computer adds nothing, and discover and doctor list it as available with the project's install command", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {
        topic: 'acme-deploying',
      });
      // The global copy is on the search path, as it is once installed.
      pc.path.unshift(g.binDir);
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
      const docs = JSON.parse(
        run(g.bin, ['docs', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(
        docs.data.some((/** @type {any} */ t) => t.topic === 'acme-deploying'),
      ).toBe(false);
      const discover = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(discover.data).toEqual([]);
      expect(notOfficial(discover)).toEqual([
        {
          name: '@acme/widgets',
          package: '@acme/widgets',
          components: [],
          version: '1.0.0',
          source: 'installed for this computer',
          install: 'npm install @acme/widgets',
        },
      ]);
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-integrations',
        ),
      ).toMatchObject({
        status: 'info',
        fix: 'To use one in this project, run `npm install @acme/widgets`.',
      });
    });

    /**
     * The global npm copy on the search path, with `@acme/widgets` installed
     * beside it for the computer.
     */
    function computerWithWidgets() {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {
        topic: 'acme-deploying',
      });
      pc.path.unshift(g.binDir);
      /** @param {string} cwd */
      const integrationsCheck = cwd =>
        JSON.parse(
          run(g.bin, ['doctor', '--json'], {cwd, pc}).stdout,
        ).data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-integrations',
        );
      return {pc, g, integrationsCheck};
    }

    /** A project with Core and the CLI, installed with npm. */
    function npmProject() {
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
      return dir;
    }

    // As G36, in four cases; each runs the CLI at most twice.
    it("from a tool folder inside a project (as G36), discover and doctor point an integration installed for the computer at the project's folder", () => {
      const {pc, g, integrationsCheck} = computerWithWidgets();
      const dir = npmProject();
      const tool = path.join(dir, 'tools', 'codegen');
      writeJson(path.join(tool, 'package.json'), {name: 'codegen'});
      const discover = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: tool, pc}).stdout,
      );
      // A run there loads integrations from the tool's own package.json, so
      // a package added to the project would stay unused there: no command,
      // only the way to the project.
      expect(notOfficial(discover)).toEqual([
        {
          name: '@acme/widgets',
          package: '@acme/widgets',
          components: [],
          version: '1.0.0',
          source: 'installed for this computer',
        },
      ]);
      expect(integrationsCheck(tool).fix).toBe(DOCTOR_RUN_FROM_PROJECT);
    });

    it("from the project's folder (as G36), discover and doctor give the command that adds an integration installed for the computer", () => {
      const {pc, g, integrationsCheck} = computerWithWidgets();
      const dir = npmProject();
      const fromProject = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(notOfficial(fromProject)[0].install).toBe(
        'npm install @acme/widgets',
      );
      expect(integrationsCheck(dir).fix).toBe(
        'To use one in this project, run `npm install @acme/widgets`.',
      );
    });

    it('once the project installs it (as G36), discover and doctor no longer offer an integration installed for the computer', () => {
      const {pc, g, integrationsCheck} = computerWithWidgets();
      const dir = npmProject();
      const pkg = JSON.parse(
        fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
      );
      writeJson(path.join(dir, 'package.json'), {
        ...pkg,
        dependencies: {...pkg.dependencies, '@acme/widgets': '1.0.0'},
      });
      acmeWidgets(dir, {topic: 'acme-project'});
      const after = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(notOfficial(after)).toEqual([]);
      expect(integrationsCheck(dir)).not.toHaveProperty('fix');
    });

    it('with no project (as G36), discover names no command for an integration installed for the computer', () => {
      const {pc, g} = computerWithWidgets();
      // A folder that installs Core but belongs to no project.
      const alone = tempDir('alone');
      writeJson(path.join(alone, 'package.json'), {name: 'alone'});
      installCore(alone, '9.0.0');
      const lone = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: alone, pc}).stdout,
      );
      for (const entry of notOfficial(lone)) {
        expect(entry).not.toHaveProperty('install');
      }
    });

    it("G37 a project that installs the same integration uses only its own copy, outside the project's folder rules too", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {
        topic: 'acme-global',
      });
      // The global copy is on the search path, as it is once installed.
      pc.path.unshift(g.binDir);
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      const pkg = JSON.parse(
        fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
      );
      writeJson(path.join(dir, 'package.json'), {
        ...pkg,
        dependencies: {...pkg.dependencies, '@acme/widgets': '1.0.0'},
      });
      acmeWidgets(dir, {topic: 'acme-project'});
      const docs = JSON.parse(
        run(g.bin, ['docs', '--json'], {cwd: dir, pc}).stdout,
      );
      const topics = docs.data.map((/** @type {any} */ t) => t.topic);
      expect(topics).toContain('acme-project');
      expect(topics).not.toContain('acme-global');
      const discover = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(notOfficial(discover)).toEqual([]);
    });

    it('G38 an integration whose peer range excludes the answering release is skipped outside a project, and doctor warns', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {
        topic: 'acme-deploying',
        peers: {'@astryxdesign/core': '>=10.0.0'},
      });
      const empty = tempDir('empty');
      const docs = JSON.parse(
        run(g.bin, ['docs', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        docs.data.some((/** @type {any} */ t) => t.topic === 'acme-deploying'),
      ).toBe(false);
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-integrations',
        ),
      ).toMatchObject({
        status: 'warn',
        message:
          "Skipped @acme/[email protected]: it needs @astryxdesign/core >=10.0.0, and this computer's CLI is 9.0.0.",
      });
    });

    it("G39 a door's package set: integrations installed with the CLI in one root count, with no host entry", () => {
      const pc = computer();
      const root = tempDir('runtime');
      writeJson(path.join(root, 'package.json'), {
        name: 'door-runtime',
        private: true,
        dependencies: {
          '@astryxdesign/cli': '9.0.0',
          '@acme/widgets': '1.0.0',
        },
      });
      const cli = placeCli(
        path.join(root, 'node_modules', '@astryxdesign', 'cli'),
        '9.0.0',
      );
      acmeWidgets(root, {topic: 'acme-door'});
      const docs = JSON.parse(
        run(cli.bin, ['docs', '--json'], {cwd: tempDir('empty'), pc}).stdout,
      );
      expect(
        docs.data.find((/** @type {any} */ t) => t.topic === 'acme-door'),
      ).toMatchObject({package: '@acme/widgets'});
    });

    it('G40 pnpm global folders: one shared folder before pnpm 11, a folder per package since, with or without the global virtual store', () => {
      const pc = computer();
      // Before pnpm 11: the CLI's files are in `global/5/.pnpm`, and
      // `global/5/package.json` lists everything installed globally.
      const g5 = path.join(pc.home, '.local', 'share', 'pnpm', 'global', '5');
      const real5 = placeCli(
        path.join(
          g5,
          '.pnpm',
          '@[email protected]',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.0',
      );
      writeJson(path.join(g5, 'package.json'), {
        dependencies: {'@astryxdesign/cli': '9.0.0', '@acme/widgets': '1.0.0'},
      });
      fs.mkdirSync(path.join(g5, 'node_modules', '@astryxdesign'), {
        recursive: true,
      });
      fs.symlinkSync(
        real5.dir,
        path.join(g5, 'node_modules', '@astryxdesign', 'cli'),
      );
      acmeWidgets(g5, {topic: 'acme-pnpm10'});
      const empty = tempDir('empty');
      const docs10 = JSON.parse(
        run(real5.bin, ['docs', '--json'], {cwd: empty, pc}).stdout,
      );
      expect(docs10.data.map((/** @type {any} */ t) => t.topic)).toContain(
        'acme-pnpm10',
      );

      // pnpm 11 and later: each global package has a folder of its own under
      // `global/v11`, and the files are in `store/v11/links`.
      const pc2 = computer();
      const home = path.join(pc2.home, '.local', 'share', 'pnpm');
      const store = placeCli(
        path.join(
          home,
          'store',
          'v11',
          'links',
          '@astryxdesign',
          'cli',
          '9.0.0',
          'h1',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.0',
      );
      const cliFolder = path.join(home, 'global', 'v11', 'a1');
      writeJson(path.join(cliFolder, 'package.json'), {
        dependencies: {'@astryxdesign/cli': '9.0.0'},
      });
      fs.mkdirSync(path.join(cliFolder, 'node_modules', '@astryxdesign'), {
        recursive: true,
      });
      fs.symlinkSync(
        store.dir,
        path.join(cliFolder, 'node_modules', '@astryxdesign', 'cli'),
      );
      const widgetsFolder = path.join(home, 'global', 'v11', 'b2');
      writeJson(path.join(widgetsFolder, 'package.json'), {
        dependencies: {'@acme/widgets': '1.0.0'},
      });
      acmeWidgets(widgetsFolder, {topic: 'acme-pnpm11'});
      const docs11 = JSON.parse(
        run(store.bin, ['docs', '--json'], {cwd: tempDir('empty'), pc: pc2})
          .stdout,
      );
      expect(docs11.data.map((/** @type {any} */ t) => t.topic)).toContain(
        'acme-pnpm11',
      );

      // pnpm 12: no global virtual store, so the CLI's files sit inside its
      // own global folder, under `.pnpm`.
      const pc3 = computer();
      const g12 = path.join(
        pc3.home,
        '.local',
        'share',
        'pnpm',
        'global',
        'v11',
      );
      const own = path.join(g12, 'c3');
      writeJson(path.join(own, 'package.json'), {
        dependencies: {'@astryxdesign/cli': '9.0.0'},
      });
      const inner = placeCli(
        path.join(
          own,
          'node_modules',
          '.pnpm',
          '@[email protected]',
          'node_modules',
          '@astryxdesign',
          'cli',
        ),
        '9.0.0',
      );
      fs.mkdirSync(path.join(own, 'node_modules', '@astryxdesign'), {
        recursive: true,
      });
      fs.symlinkSync(
        inner.dir,
        path.join(own, 'node_modules', '@astryxdesign', 'cli'),
      );
      const sibling = path.join(g12, 'd4');
      writeJson(path.join(sibling, 'package.json'), {
        dependencies: {'@acme/widgets': '1.0.0'},
      });
      acmeWidgets(sibling, {topic: 'acme-pnpm12'});
      const docs12 = JSON.parse(
        run(inner.bin, ['docs', '--json'], {cwd: tempDir('empty'), pc: pc3})
          .stdout,
      );
      expect(docs12.data.map((/** @type {any} */ t) => t.topic)).toContain(
        'acme-pnpm12',
      );
    });

    it("G41 an integration's own source folder, outside a project: the folder's copy is used, and doctor says so without a warning", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      acmeWidgets(path.resolve(g.dir, '..', '..', '..'), {
        topic: 'acme-global',
      });
      const source = tempDir('source');
      writeJson(path.join(source, 'package.json'), {
        name: '@acme/widgets',
        version: '2.0.0',
      });
      fs.writeFileSync(
        path.join(source, 'astryx.integration.mjs'),
        'export default {};\n',
      );
      const docs = JSON.parse(
        run(g.bin, ['docs', '--json'], {cwd: source, pc}).stdout,
      );
      expect(docs.data.map((/** @type {any} */ t) => t.topic)).not.toContain(
        'acme-global',
      );
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: source, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-integrations',
        ),
      ).toMatchObject({
        status: 'pass',
        message:
          '@acme/[email protected] is not used here: this folder loads its own copy of @acme/widgets.',
      });
    });

    it('G42 inside a project, an integration installed for the computer is offered only when its peer range admits the project release and it loads', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const lib = path.resolve(g.dir, '..', '..', '..');
      acmeWidgets(lib, {topic: 'acme-ok'});
      acmeWidgets(lib, {
        topic: 'acme-old',
        name: '@acme/old',
        peers: {'@astryxdesign/core': '>=10.0.0'},
      });
      acmeWidgets(lib, {
        topic: 'acme-broken',
        name: '@acme/broken',
        manifest: "throw new Error('broken');\n",
      });
      pc.path.unshift(g.binDir);
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
      const discover = JSON.parse(
        run(g.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(
        notOfficial(discover).map((/** @type {any} */ p) => p.name),
      ).toEqual(['@acme/widgets']);
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-integrations',
        ).fix,
      ).toBe('To use one in this project, run `npm install @acme/widgets`.');
    });

    it("G43 inside a project a door's package set answers for: its integrations are offered as available", () => {
      const pc = computer();
      const root = tempDir('runtime');
      writeJson(path.join(root, 'package.json'), {
        name: 'door-runtime',
        private: true,
        dependencies: {'@astryxdesign/cli': '9.0.0', '@acme/widgets': '1.0.0'},
      });
      const cli = placeCli(
        path.join(root, 'node_modules', '@astryxdesign', 'cli'),
        '9.0.0',
      );
      acmeWidgets(root, {topic: 'acme-door'});
      // The project installs only Core 9.0.0, so the door's copy, which
      // started the run, answers it.
      const dir = makeProject({core: '9.0.0'});
      writeJson(path.join(dir, 'package-lock.json'), {lockfileVersion: 3});
      const discover = JSON.parse(
        run(cli.bin, ['discover', '--json'], {cwd: dir, pc}).stdout,
      );
      expect(discover.meta.answeredBy.copy).toBe('starting');
      expect(notOfficial(discover)).toEqual([
        {
          name: '@acme/widgets',
          package: '@acme/widgets',
          components: [],
          version: '1.0.0',
          source: 'installed for this computer',
          install: 'npm install @acme/widgets',
        },
      ]);
    });

    it("G44 npm's own prefix (npm i -g --prefix ~/.local): the upgrade names that prefix, integrations installed there apply outside a project, and doctor finds ~/.local/bin/astryx", () => {
      const pc = computer();
      const prefix = path.join(pc.home, '.local');
      const cli = placeCli(
        path.join(prefix, 'lib', 'node_modules', '@astryxdesign', 'cli'),
        '9.0.0',
      );
      fs.mkdirSync(path.join(prefix, 'bin'), {recursive: true});
      fs.symlinkSync(cli.bin, path.join(prefix, 'bin', 'astryx'));
      pc.path.unshift(path.join(prefix, 'bin'));
      acmeWidgets(path.join(prefix, 'lib'), {topic: 'acme-prefix'});
      globalState(pc, {
        latest: '9.0.5',
        checkOkAt: Date.now(),
        // Checked just now, so no run starts an update check.
        checkedAt: Date.now(),
        firstRunAt: 0,
      });
      const empty = tempDir('empty');
      const docs = run(cli.bin, ['docs', '--json'], {cwd: empty, pc});
      expect(
        JSON.parse(docs.stdout).data.map((/** @type {any} */ t) => t.topic),
      ).toContain('acme-prefix');
      // --json prints no notice; a text run does.
      expect(docs.notice).toEqual([]);
      expect(run(cli.bin, ['--version'], {cwd: empty, pc}).notice).toEqual([
        available('9.0.0', '9.0.5'),
        'To upgrade, run: npm i -g --prefix ~/.local @astryxdesign/cli@latest',
      ]);
      const doctor = JSON.parse(
        run(cli.bin, ['doctor', '--json'], {cwd: empty, pc}).stdout,
      );
      const onPath = doctor.data.checks.find(
        (/** @type {any} */ c) => c.id === 'cli-on-path',
      );
      expect(onPath.status).toBe('pass');
      expect(onPath.message).toContain(path.join(prefix, 'bin', 'astryx'));
    });

    it("G45 the agent guide: the global copy's first run writes one file and links Claude Code's folder to it; a folder Astryx did not create is kept and doctor names it; --remove-agents removes the file and the link", async () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const file = path.join(
        pc.home,
        '.agents',
        'skills',
        'astryx',
        'SKILL.md',
      );
      const claude = path.join(pc.home, '.claude', 'skills', 'astryx');
      run(g.bin, ['--version'], {cwd: tempDir('empty'), pc});
      for (let i = 0; i < 100 && !fs.existsSync(claude); i++) {
        await new Promise(done => setTimeout(done, 100));
      }
      expect(fs.readFileSync(file, 'utf8')).toContain('name: astryx');
      expect(fs.lstatSync(claude).isSymbolicLink()).toBe(true);
      expect(fs.readFileSync(path.join(claude, 'SKILL.md'), 'utf8')).toBe(
        fs.readFileSync(file, 'utf8'),
      );
      const removed = run(g.bin, ['init', '--user', '--remove-agents'], {
        cwd: tempDir('empty'),
        pc,
      });
      expect(removed.status).toBe(0);
      expect(fs.existsSync(file)).toBe(false);
      expect(fs.existsSync(claude)).toBe(false);

      // A folder someone else put there is never replaced.
      fs.mkdirSync(claude, {recursive: true});
      fs.writeFileSync(path.join(claude, 'SKILL.md'), 'mine\n');
      expect(
        run(g.bin, ['init', '--user'], {cwd: tempDir('empty'), pc}).status,
      ).toBe(0);
      expect(fs.readFileSync(path.join(claude, 'SKILL.md'), 'utf8')).toBe(
        'mine\n',
      );
      const doctor = JSON.parse(
        run(g.bin, ['doctor', '--json'], {cwd: tempDir('empty'), pc}).stdout,
      );
      expect(
        doctor.data.checks.find(
          (/** @type {any} */ c) => c.id === 'computer-agent-text',
        ).message,
      ).toContain(
        `Not linked, because something Astryx did not create is there: ~${path.sep}${path.join('.claude', 'skills', 'astryx')}`,
      );
    });

    it('G46 docs global inside a project whose release predates it: the copy that started the run answers, for this computer, never handed off', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      for (const args of [
        ['docs', 'global'],
        ['docs', 'global/problems'],
      ]) {
        const r = run(g.bin, args, {cwd: dir, pc});
        expect(r.status).toBe(0);
        expect(r.lines).toEqual([
          'astryx: answered by CLI 9.0.5 with Core 9.0.5, for this computer',
        ]);
      }
      // Any other docs topic is still the project's.
      expect(run(g.bin, ['docs'], {cwd: dir, pc}).lines).toEqual([
        "astryx: answered by this project's CLI 9.0.0, handed over from CLI 9.0.5",
      ]);
    });

    it('G47 a project whose own CLI is newer than its Core, online or offline: that CLI answers and nothing is fetched', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({core: '9.0.3', cli: '9.0.4'});
      for (const registry of [undefined, OFFLINE]) {
        const env = registry ? {npm_config_registry: registry} : {};
        const r = run(g.bin, ['--version'], {cwd: dir, pc, env});
        expect(r.status).toBe(0);
        expect(r.stdout).toBe('9.0.4');
        expect(r.lines.some(l => l.includes('could not get Astryx'))).toBe(
          false,
        );
        const json = run(g.bin, ['docs', '--json'], {cwd: dir, pc, env});
        expect(JSON.parse(json.stdout).meta.answeredBy).toMatchObject({
          cli: '9.0.4',
          copy: 'project',
        });
      }
      expect(
        fs.existsSync(path.join(pc.astryxCache, 'releases', '9.0.3')),
      ).toBe(false);
    });

    it('G48 offline, a project whose own CLI cannot start: the starting copy answers, with one warning and copy fallback', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({core: '9.0.3', brokenCli: '9.0.3'});
      const r = run(g.bin, ['--version'], {cwd: dir, pc});
      expect(r.status).toBe(0);
      expect(r.stdout).toBe('9.0.0');
      // After the line saying it tries to install the release, one warning.
      expect(r.lines.filter(l => !l.includes('installing'))).toEqual([
        expect.stringMatching(
          /^astryx: could not get Astryx 9\.0\.3 to match this project's Core \(.+\); answering with CLI 9\.0\.0 instead$/u,
        ),
      ]);
      const json = run(g.bin, ['docs', '--json'], {cwd: dir, pc});
      expect(JSON.parse(json.stdout).meta.answeredBy).toMatchObject({
        cli: '9.0.0',
        copy: 'fallback',
      });
    });

    // One row of the table, in three cases: each replays only the installs it
    // needs, and a failed install waits out the CLI's own bounded retry.
    describe('G49 offline, a release that failed to install is retried after 2 minutes, then after 10 once it fails again, by any copy sharing the cache; a success forgets it', () => {
      /**
       * G49's world: a global CLI and a project whose own CLI cannot start and
       * whose Core release cannot be installed (the registry is unreachable),
       * with the record of that release's failed installs. Each case below
       * replays only the installs it needs: a failed one waits out the CLI's
       * own bounded retry, a few seconds each.
       */
      const g49 = () => {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home});
        const dir = makeProject({core: '9.0.3', brokenCli: '9.0.3'});
        const record = path.join(
          pc.astryxCache,
          'releases',
          '.failed-9.0.3.json',
        );
        const read = () => JSON.parse(fs.readFileSync(record, 'utf8'));
        return {
          pc,
          g,
          dir,
          record,
          read,
          /** Runs `astryx --version` with `bin`; the global copy by default. */
          version: (bin = g.bin) => run(bin, ['--version'], {cwd: dir, pc}),
          /** Move the last failure `minutes` into the past. @param {number} minutes */
          age: (/** @type {number} */ minutes) => {
            const old = read();
            fs.writeFileSync(
              record,
              JSON.stringify({...old, at: old.at - minutes * 60_000}),
            );
          },
        };
      };
      const installs = (/** @type {{lines: string[]}} */ r) =>
        r.lines.filter(l => l.includes('installing')).length;

      it('the first failure is recorded, and neither this copy nor another sharing the cache tries again within 2 minutes', () => {
        const {pc, version, read} = g49();
        expect(installs(version())).toBe(1);
        expect(read().failures).toBe(1);
        const other = globalCli('npm', '9.0.1', {
          root: path.join(pc.home, 'other'),
        });
        for (const bin of [undefined, other.bin]) {
          const again = version(bin);
          expect(again.status).toBe(0);
          expect(installs(again)).toBe(0);
          expect(again.lines).toEqual([
            expect.stringMatching(
              /^astryx: could not get Astryx 9\.0\.3 to match this project's Core \(.+; last tried 1 minute ago, tried again after 2 minutes\); answering with CLI 9\.0\.[01] instead$/u,
            ),
          ]);
        }
      });

      it('after 2 minutes it is tried again, and a second failure in a row waits 10', () => {
        const {version, read, age} = g49();
        expect(installs(version())).toBe(1);
        age(3);
        expect(installs(version())).toBe(1);
        expect(read().failures).toBe(2);
        age(3);
        const waiting = version();
        expect(installs(waiting)).toBe(0);
        expect(waiting.lines[0]).toMatch(/tried again after 10 minutes\)/u);
      });

      it('after 10 minutes two failures in a row are tried again, and a success forgets them', () => {
        const {pc, record, version, read, age} = g49();
        expect(installs(version())).toBe(1);
        // A second failure in a row, recorded as the CLI records it.
        fs.writeFileSync(record, JSON.stringify({...read(), failures: 2}));
        // Past 10 minutes it installs again, for real, and fails a third time.
        age(11);
        expect(installs(version())).toBe(1);
        expect(read().failures).toBe(3);
        // A release installed by then answers, and forgets the failures.
        seedPackedRelease(pc.astryxCache, '9.0.3');
        expect(version().stdout).toBe('9.0.3');
        expect(fs.existsSync(record)).toBe(false);
      });
    });

    it('G50 a global copy in a Bun global folder moved with BUN_INSTALL: global only while BUN_INSTALL names it; an app under a folder named install/global is not', () => {
      const pc = computer();
      const bunHome = path.join(pc.home, 'mybun');
      const global = path.join(bunHome, 'install', 'global');
      writeJson(path.join(global, 'package.json'), {
        dependencies: {'@astryxdesign/cli': '9.0.0'},
      });
      fs.writeFileSync(path.join(global, 'bun.lock'), '{}');
      const copy = placeCli(
        path.join(global, 'node_modules', '@astryxdesign', 'cli'),
        '9.0.0',
      );
      const where = {home: pc.home, platform: /** @type {const} */ ('linux')};
      expect(
        isGlobalCopy(copy.dir, pc.astryxCache, {
          ...where,
          env: {BUN_INSTALL: bunHome},
        }),
      ).toBe(true);
      expect(
        globalUpgradeCommand(copy.dir, {...where, env: {BUN_INSTALL: bunHome}}),
      ).toBe('bun add -g @astryxdesign/cli@latest');
      // Nothing names that folder: not global, so no check and no skill.
      expect(isGlobalCopy(copy.dir, pc.astryxCache, {...where, env: {}})).toBe(
        false,
      );
      // An npm app whose folder happens to end in install/global.
      const app = path.join(pc.home, 'work', 'install', 'global');
      writeJson(path.join(app, 'package.json'), {
        name: 'app',
        dependencies: {'@astryxdesign/cli': '9.0.0'},
      });
      const own = placeCli(
        path.join(app, 'node_modules', '@astryxdesign', 'cli'),
        '9.0.0',
      );
      expect(isGlobalCopy(own.dir, pc.astryxCache, {...where, env: {}})).toBe(
        false,
      );
    });

    it("G51 a global copy in a Yarn 1 global folder moved with global-folder: global when Yarn's settings name it; an app made with yarn add alone is not", () => {
      const pc = computer();
      const global = path.join(pc.home, 'myyarn-global');
      const yarnLike = (/** @type {string} */ dir) => {
        writeJson(path.join(dir, 'package.json'), {
          dependencies: {'@astryxdesign/cli': '9.0.0'},
        });
        fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
        return placeCli(
          path.join(dir, 'node_modules', '@astryxdesign', 'cli'),
          '9.0.0',
        );
      };
      const copy = yarnLike(global);
      const where = {
        home: pc.home,
        platform: /** @type {const} */ ('linux'),
        env: {},
      };
      // Not named by Yarn's settings yet: not global.
      expect(isGlobalCopy(copy.dir, pc.astryxCache, where)).toBe(false);
      // `yarn config set global-folder ~/myyarn-global` writes ~/.yarnrc.
      fs.writeFileSync(
        path.join(pc.home, '.yarnrc'),
        'global-folder "~/myyarn-global"\n',
      );
      expect(isGlobalCopy(copy.dir, pc.astryxCache, where)).toBe(true);
      expect(globalUpgradeCommand(copy.dir, where)).toBe(
        'yarn global add @astryxdesign/cli@latest',
      );
      // And through the environment.
      fs.rmSync(path.join(pc.home, '.yarnrc'));
      expect(
        isGlobalCopy(copy.dir, pc.astryxCache, {
          ...where,
          env: {YARN_GLOBAL_FOLDER: global},
        }),
      ).toBe(true);
      // A fresh app made with `yarn add @astryxdesign/core @astryxdesign/cli`
      // holds the same files: never global.
      const app = yarnLike(path.join(pc.home, 'my-app'));
      expect(isGlobalCopy(app.dir, pc.astryxCache, where)).toBe(false);
      // Its own CLI, run in it, starts no update check and writes no skill.
      const r = run(app.bin, ['--version'], {
        cwd: path.join(pc.home, 'my-app'),
        pc,
      });
      expect(r.status).toBe(0);
      expect(
        fs.existsSync(path.join(pc.home, '.agents', 'skills', 'astryx')),
      ).toBe(false);
      expect(
        fs.existsSync(path.join(pc.home, '.config', 'astryx', 'state.json')),
      ).toBe(false);
    });

    it.skipIf(process.platform === 'win32')(
      'G52 the global copy installs its own Core into the cache in the background, never in CI or on Windows and never blocking a command; offline, the failure waits out the backoff',
      async () => {
        const pc = computer();
        const g = globalCli('npm', '9.0.0', {root: pc.home, coreStep: true});
        const empty = tempDir('empty');
        const failed = path.join(
          pc.astryxCache,
          'releases',
          '.failed-9.0.0.json',
        );
        // In CI, no download starts.
        expect(
          run(g.bin, ['--version'], {cwd: empty, pc, env: {CI: 'true'}}).status,
        ).toBe(0);
        await new Promise(resolve => setTimeout(resolve, 2000));
        expect(fs.existsSync(failed)).toBe(false);
        // Otherwise the detached step tries it; the run itself returns at once.
        const started = Date.now();
        const r = run(g.bin, ['--version'], {cwd: empty, pc});
        expect(r.status).toBe(0);
        expect(r.stdout).toBe('9.0.0');
        expect(Date.now() - started).toBeLessThan(15_000);
        // Offline here: the step records the failure for the backoff.
        for (let i = 0; i < 100 && !fs.existsSync(failed); i++) {
          await new Promise(resolve => setTimeout(resolve, 200));
        }
        expect(fs.existsSync(failed)).toBe(true);
        // A cached release means nothing more to do.
        fs.rmSync(failed);
        seedPackedRelease(pc.astryxCache, '9.0.0');
        expect(run(g.bin, ['--version'], {cwd: empty, pc}).status).toBe(0);
        await new Promise(resolve => setTimeout(resolve, 2000));
        expect(fs.existsSync(failed)).toBe(false);
      },
      60_000,
    );

    it("G53 pnpm's global virtual store: a project's own CLI kept in the store's links folder is not global; one a pnpm global folder links to is", () => {
      const pc = computer();
      const home = path.join(pc.home, '.local', 'share', 'pnpm');
      const where = {
        home: pc.home,
        platform: /** @type {const} */ ('linux'),
        env: {},
      };
      /** A CLI in the store's links folder. @param {string} hash */
      const inStore = hash =>
        placeCli(
          path.join(
            home,
            'store',
            'v11',
            'links',
            '@astryxdesign',
            'cli',
            '9.0.0',
            hash,
            'node_modules',
            '@astryxdesign',
            'cli',
          ),
          '9.0.0',
        );
      // A project links its own CLI from the store: not global, so no check
      // and no skill for each project run.
      const projectCli = inStore('p1');
      const app = path.join(pc.home, 'app');
      writeJson(path.join(app, 'package.json'), {
        name: 'app',
        dependencies: {'@astryxdesign/cli': '9.0.0'},
      });
      fs.mkdirSync(path.join(app, 'node_modules', '@astryxdesign'), {
        recursive: true,
      });
      fs.symlinkSync(
        projectCli.dir,
        path.join(app, 'node_modules', '@astryxdesign', 'cli'),
      );
      expect(isGlobalCopy(projectCli.dir, pc.astryxCache, where)).toBe(false);
      // `pnpm add -g` links one from a global folder: global.
      const globalCli11 = inStore('g1');
      const folder = path.join(home, 'global', 'v11', 'a1');
      writeJson(path.join(folder, 'package.json'), {
        dependencies: {'@astryxdesign/cli': '9.0.0'},
      });
      fs.mkdirSync(path.join(folder, 'node_modules', '@astryxdesign'), {
        recursive: true,
      });
      fs.symlinkSync(
        globalCli11.dir,
        path.join(folder, 'node_modules', '@astryxdesign', 'cli'),
      );
      expect(isGlobalCopy(globalCli11.dir, pc.astryxCache, where)).toBe(true);
      expect(isGlobalCopy(projectCli.dir, pc.astryxCache, where)).toBe(false);
      // Run in the project, its own CLI starts no check and writes no skill.
      const r = run(projectCli.bin, ['--version'], {cwd: app, pc});
      expect(r.status).toBe(0);
      expect(
        fs.existsSync(path.join(pc.home, '.agents', 'skills', 'astryx')),
      ).toBe(false);
    });

    it('G54 a folder deeper than the nearby look in a project with its own CLI: that CLI answers, and no false hint', () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.5', {root: pc.home});
      const dir = makeProject({core: '9.0.0', cli: '9.0.0'});
      for (const rel of [
        ['src', 'a', 'b', 'c', 'd', 'e'],
        ['src', 'app', '(shop)', 'orders', '[id]', 'edit', 'deeper'],
      ]) {
        const deep = path.join(dir, ...rel);
        fs.mkdirSync(deep, {recursive: true});
        const r = run(g.bin, ['--version'], {cwd: deep, pc});
        expect(r.stdout).toBe('9.0.0');
        expect(r.lines).toEqual([handedTo('9.0.0')('9.0.5')]);
      }
    });

    it('G55 a --json run in a fresh clone returns before the background Core step ends, with clean JSON', async () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      // A slow stand-in for the step, which marks when it starts and ends.
      const startedMark = path.join(pc.home, 'core-step-started');
      const marker = path.join(pc.home, 'core-step-ended');
      const worker = path.join(
        g.dir,
        'foundation',
        'release',
        'core-worker.mjs',
      );
      fs.rmSync(worker, {force: true});
      fs.writeFileSync(
        worker,
        [
          "import * as fs from 'node:fs';",
          `fs.writeFileSync(${JSON.stringify(startedMark)}, '');`,
          `setTimeout(() => fs.writeFileSync(${JSON.stringify(marker)}, ''), 20000);`,
        ].join('\n'),
      );
      const dir = makeProject({declare: {'@astryxdesign/core': '^9.0.0'}});
      writeJson(path.join(dir, 'package-lock.json'), {
        lockfileVersion: 3,
        packages: {'node_modules/@astryxdesign/core': {version: '9.0.0'}},
      });
      const started = Date.now();
      // spawnSync waits until the run's output pipes close.
      const r = run(g.bin, ['docs', '--json'], {cwd: dir, pc});
      expect(Date.now() - started).toBeLessThan(10_000);
      expect(() => JSON.parse(r.stdout)).not.toThrow();
      expect(r.stderr).toBe('');
      expect(fs.existsSync(marker)).toBe(false);
      // The step did start, after the command; on Windows it never starts.
      for (let i = 0; i < 50 && !fs.existsSync(startedMark); i++) {
        await new Promise(resolve => setTimeout(resolve, 100));
      }
      expect(fs.existsSync(startedMark)).toBe(process.platform !== 'win32');
    });

    it("G56 an open search outside a project gets the release's Core as component does; when it cannot, it says what it skipped, never silently", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const empty = tempDir('empty');
      // Offline, with nothing cached: one install attempt, then the rest of
      // the search, flagged.
      const json = run(g.bin, ['search', 'button', '--json'], {cwd: empty, pc});
      expect(json.status).toBe(0);
      expect(JSON.parse(json.stdout).meta.partial).toMatchObject({
        skipped: ['component', 'hook', 'template'],
        reason: expect.stringContaining('could not be installed'),
      });
      const text = run(g.bin, ['search', 'button'], {cwd: empty, pc});
      expect(text.status).toBe(0);
      expect(
        text.lines.filter(l =>
          l.startsWith(
            'astryx: components, hooks, and templates were not searched: ',
          ),
        ),
      ).toHaveLength(1);
      // With the release cached, the search reads its Core: nothing skipped.
      seedPackedRelease(pc.astryxCache, '9.0.0');
      const cached = run(g.bin, ['search', 'button', '--json'], {
        cwd: empty,
        pc,
      });
      expect(JSON.parse(cached.stdout).meta?.partial).toBeUndefined();
    });

    it("G57 a folder deeper than the nearby look in a project with only Core: that Core is read, never the starting copy's", () => {
      const pc = computer();
      const g = globalCli('npm', '9.0.0', {root: pc.home});
      const dir = makeProject({core: '9.0.1'});
      for (const rel of [
        ['a', 'b', 'c', 'd', 'e'],
        ['src', 'a', 'b', 'c', 'd', 'e'],
        ['src', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k'],
        ['src', 'app', '(shop)', 'orders', '[id]', 'edit'],
      ]) {
        const deep = path.join(dir, ...rel);
        fs.mkdirSync(deep, {recursive: true});
        const json = run(g.bin, ['docs', '--json'], {cwd: deep, pc});
        expect(JSON.parse(json.stdout).meta.answeredBy, rel.join('/')).toEqual({
          cli: '9.0.0',
          core: '9.0.1',
          copy: 'starting',
        });
        // The command reads the project's Core (here an empty stand-in with
        // no components), not the one the copy carries, which has Button.
        const component = run(g.bin, ['component', 'Button', '--json'], {
          cwd: deep,
          pc,
        });
        expect(
          component.status,
          `${rel.join('/')}: ${component.stdout}`,
        ).not.toBe(0);
        expect(JSON.parse(component.stdout).code).not.toBe(
          'ERR_VERSIONS_UNAVAILABLE',
        );
      }
    });

    it.skipIf(process.platform === 'win32')(
      "G58 an interrupt reaches the project's CLI exactly once: passed on after 5 seconds when only the starting copy got it, never when the whole group did and the CLI stopped in time",
      async () => {
        const pc = computer();
        const g = globalCli('npm', '9.0.5', {root: pc.home});
        /**
         * A project whose own CLI records each interrupt it gets, then stops
         * as `onInterrupt` says.
         * @param {string} onInterrupt
         */
        const stubProject = onInterrupt => {
          const dir = project(tempDir('project'), {
            '@astryxdesign/cli': '9.0.0',
          });
          const cliDir = path.join(dir, 'node_modules', '@astryxdesign', 'cli');
          writeJson(path.join(cliDir, 'package.json'), {
            name: '@astryxdesign/cli',
            version: '9.0.0',
            type: 'module',
            bin: {astryx: 'clients/cli/bin/astryx.mjs'},
          });
          const bin = path.join(cliDir, 'clients', 'cli', 'bin', 'astryx.mjs');
          fs.mkdirSync(path.dirname(bin), {recursive: true});
          fs.writeFileSync(
            bin,
            [
              "import * as fs from 'node:fs';",
              "const log = process.cwd() + '/interrupts.log';",
              "fs.writeFileSync(log, '');",
              onInterrupt,
              // Written whole under another name, then renamed into place:
              // a reader never finds the file empty.
              "const pidFile = process.cwd() + '/child.pid';",
              "fs.writeFileSync(pidFile + '.tmp', String(process.pid));",
              "fs.renameSync(pidFile + '.tmp', pidFile);",
              'setInterval(() => {}, 1000);',
            ].join('\n'),
          );
          return dir;
        };
        const HANDLES =
          "process.on('SIGINT', () => { fs.appendFileSync(log, 'SIGINT\\n'); setTimeout(() => process.exit(130), 200); });";
        /**
         * Start a run in `dir` and interrupt it: the starting copy alone, as an
         * agent's kill('SIGINT') does, or its whole process group, as a
         * terminal's Ctrl-C does.
         * @param {string} dir
         * @param {'alone' | 'group'} target
         */
        const interrupt = async (dir, target) => {
          const child = spawn(process.execPath, [g.bin, '--version'], {
            cwd: dir,
            env: envOf(pc),
            stdio: 'pipe',
            // A process group of its own, so the group can be signalled.
            detached: true,
          });
          const pidFile = path.join(dir, 'child.pid');
          // The CLI writes its pid once it handles interrupts. Wait for that,
          // or for the run to end without it, however long a busy machine
          // takes to get there.
          while (
            !fs.existsSync(pidFile) &&
            child.exitCode === null &&
            child.signalCode === null
          ) {
            await new Promise(resolve => setTimeout(resolve, 50));
          }
          expect(fs.existsSync(pidFile)).toBe(true);
          const childPid = Number(fs.readFileSync(pidFile, 'utf8'));
          // A pid of 0 would make the checks below ask about this process's
          // own process group.
          expect(childPid).toBeGreaterThan(0);
          const started = Date.now();
          if (target === 'group') {
            process.kill(-(/** @type {number} */ (child.pid)), 'SIGINT');
          } else {
            child.kill('SIGINT');
          }
          /** @type {[number | null, NodeJS.Signals | null] | null} */
          const ended = await new Promise(resolve => {
            const timer = setTimeout(() => resolve(null), 15_000);
            child.on('exit', (c, s) => {
              clearTimeout(timer);
              resolve([c, s]);
            });
          });
          if (!ended) {
            // The run did not stop: end both, then fail below.
            child.kill('SIGKILL');
            try {
              process.kill(childPid, 'SIGKILL');
            } catch {
              // Already gone.
            }
          }
          const [code, signal] = ended ?? [null, null];
          let alive = true;
          try {
            process.kill(childPid, 0);
          } catch {
            alive = false;
          }
          return {
            code,
            signal,
            alive,
            seconds: (Date.now() - started) / 1000,
            interrupts: fs
              .readFileSync(path.join(dir, 'interrupts.log'), 'utf8')
              .split('\n')
              .filter(Boolean).length,
          };
        };
        // The starting copy alone: passed on once, after the grace; the run
        // ends with the CLI's exit status.
        const alone = await interrupt(stubProject(HANDLES), 'alone');
        expect(alone).toMatchObject({
          code: 130,
          signal: null,
          alive: false,
          interrupts: 1,
        });
        expect(alone.seconds).toBeGreaterThanOrEqual(5);
        expect(alone.seconds).toBeLessThan(10);
        // The whole group: the CLI already has it and stops in time, so it is
        // not passed on again.
        const group = await interrupt(stubProject(HANDLES), 'group');
        expect(group).toMatchObject({
          code: 130,
          signal: null,
          alive: false,
          interrupts: 1,
        });
        expect(group.seconds).toBeLessThan(5);
        // A CLI that leaves the interrupt to Node ends by the signal, and so
        // does the run.
        const dies = await interrupt(stubProject(''), 'alone');
        expect(dies).toMatchObject({
          code: null,
          signal: 'SIGINT',
          alive: false,
        });
      },
      60_000,
    );
  },
);

it('names every row of the table exactly once', () => {
  const text = fs.readFileSync(new URL(import.meta.url), 'utf8');
  const rows = [
    ...text.matchAll(
      /^\s+(?:it|describe)(?:\.skipIf\([^)]*\)\()?\(?\s*['"](G\d+) /gmu,
    ),
  ].map(m => m[1]);
  expect(rows).toEqual(Array.from({length: 58}, (_, i) => `G${i + 1}`));
  expect(os.EOL).toBeTypeOf('string');
});