Skip to content

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

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

/**
 * @file The computer-level agent text (spec AST-081 FR8): one skill file,
 * `~/.agents/skills/astryx/SKILL.md`, which most coding agents read, linked
 * into the skill folder of each agent that reads only its own
 * (`SKILL_LINKS`), so every agent on the computer knows Astryx is there.
 *
 * - One file is written. Each other folder gets a link to its folder: a
 *   directory symlink, or a junction on Windows, which needs no
 *   administrator rights. A refresh rewrites only the file; the links follow.
 * - `SKILL_LINKS` is the one table of link targets: a folder relative to the
 *   home folder, and the folder that must already exist for it to be linked
 *   (`null`: always). The writer, the remover, doctor, and the docs all read it.
 * - The text is version-free and names only stable entry points
 *   (`STABLE_COMMANDS`), so an older file never misleads. It is short: the
 *   skill only has to say that Astryx is here, when to use it, and where to
 *   start; the CLI's own docs carry the rest.
 * - The file keeps the Astryx markers, which tell a file Astryx wrote from one
 *   a person wrote, and records inside them a hash of its text, which tells an
 *   edited file from an older rendering. A file without the markers, an
 *   edited file, and a symlinked file are never changed. A link target that
 *   holds anything Astryx did not create is never replaced; doctor names it.
 * - The links Astryx made are recorded in the settings file, so removal
 *   removes exactly those.
 *
 * `astryx init --user` writes and removes them, and the global copy's
 * background step (`foundation/release/agent-text-worker.mjs`) keeps the file
 * on its release (FR7, FR8). Both honor the settings file
 * (`foundation/env/user-settings.mjs`). This module names fixed paths in the
 * home folder and nothing else.
 *
 * @input  the home folder, the host's door (if any), the settings file
 * @output the rendered text, its state on disk, and the write/remove receipt rows
 * @position foundation/agent-docs — read by `init --user`, by the background
 *   step, and by `doctor`.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {createHash} from 'node:crypto';
import {cliDoor} from '../env/cli-command.mjs';
import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';
import {samePath} from '../fs/path-compare.mjs';
import {CLI_ROOT} from '../fs/paths.mjs';
import {CLI_PACKAGE} from '../env/package-manager.mjs';
import {isGlobalCopy} from '../release/choose.mjs';
import {globalUpgradeCommand} from '../release/notices.mjs';
import {
  MARKER_START,
  MARKER_END,
  SELF_CHECK_CSS,
  WORKFLOW_STEPS,
  WORKFLOW_TITLE,
} from './agent-doc-state.mjs';

/** The command the computer-level text uses when no host door is set. */
export const COMPUTER_COMMAND = 'astryx';

/** The install step for the CLI copy the computer-level text relies on. */
export const COMPUTER_INSTALL_STEP = 'npm i -g @astryxdesign/cli';

/**
 * What to do when the `astryx` command the text names is not found, as on a
 * machine whose home folder outlives its system folders: the skill file
 * survives a restart while the CLI installed for the computer does not.
 * @param {string} install the install step
 * @returns {string}
 */
export function computerRestoreLine(install) {
  return `If \`${COMPUTER_COMMAND}\` is not found, run \`${install}\` first.`;
}

/**
 * The step the CLI installed for the computer names for itself: the command
 * that installs it again with the same package manager into the same folder,
 * as the update notice names it but with no version. Null for any other copy.
 * @param {string} [cliRoot]
 * @returns {string | null}
 */
function ownInstallStep(cliRoot = CLI_ROOT) {
  try {
    if (isGlobalCopy(cliRoot)) {
      return globalUpgradeCommand(cliRoot).replace(
        `${CLI_PACKAGE}@latest`,
        CLI_PACKAGE,
      );
    }
  } catch {
    // A copy whose install cannot be read names none of its own.
  }
  return null;
}

/**
 * The step the skill file in `home` records, or null.
 * @param {string} home
 * @returns {string | null}
 */
function recordedInstallStep(home) {
  try {
    return skillInstallStepOf(fs.readFileSync(computerSkillFile(home), 'utf8'));
  } catch {
    return null;
  }
}

/**
 * The install step the text names. `judge`: the step a file is judged by, the
 * one it records first, so every copy of one release, two global installs
 * included, finds the same text current. `write`: the step a write records,
 * the global copy's own first, since only the CLI installed for the computer
 * chooses it. Either way npm's when there is no other.
 * @param {{cliRoot?: string, home?: string, for?: 'judge' | 'write'}} [options]
 * @returns {string}
 */
export function computerInstallStep({
  cliRoot = CLI_ROOT,
  home = os.homedir(),
  for: use = 'write',
} = {}) {
  const own = ownInstallStep(cliRoot);
  const recorded = recordedInstallStep(home);
  return (
    (use === 'judge' ? (recorded ?? own) : (own ?? recorded)) ??
    COMPUTER_INSTALL_STEP
  );
}

/**
 * The install step a skill file's text records, or null when it records
 * none.
 * @param {string} content
 * @returns {string | null}
 */
export function skillInstallStepOf(content) {
  return /is not found, run `(.+?)` first\./u.exec(content)?.[1] ?? null;
}

/** The skill folder, relative to the home folder, that holds the one file. */
const SKILL_FOLDER = path.join('.agents', 'skills', 'astryx');

/**
 * Where the skill folder reaches agents that read only their own skills
 * folder, each relative to the home folder: the agent's skills folder, the
 * folder that must already exist for it to be used (`null`: always), and how:
 * `link`, a folder link to the skill folder with a relative target, or `copy`,
 * a managed copy of the file for an agent whose scanner skips links. Public
 * agents only. Never a store another tool manages, such as `~/.codex/skills`.
 * @type {ReadonlyArray<{skills: string, when: string | null, mode: 'link' | 'copy'}>}
 */
export const SKILL_LINKS = Object.freeze([
  {skills: path.join('.claude', 'skills'), when: null, mode: 'link'},
  {skills: path.join('.kiro', 'skills'), when: '.kiro', mode: 'link'},
  {
    skills: path.join('.codeium', 'windsurf', 'skills'),
    when: path.join('.codeium', 'windsurf'),
    mode: 'link',
  },
  {skills: path.join('.letta', 'skills'), when: '.letta', mode: 'link'},
  {
    skills: path.join(
      'Library',
      'Developer',
      'Xcode',
      'CodingAssistant',
      'ClaudeAgentConfig',
      'skills',
    ),
    when: path.join('Library', 'Developer', 'Xcode', 'CodingAssistant'),
    mode: 'link',
  },
  // Kimi reads only the first of `~/.config/agents/skills` and
  // `~/.agents/skills` that exists.
  {
    skills: path.join('.config', 'agents', 'skills'),
    when: path.join('.config', 'agents', 'skills'),
    mode: 'link',
  },
  {skills: path.join('.continue', 'skills'), when: '.continue', mode: 'copy'},
]);

/**
 * The commands the text may name: stable entry points every release keeps.
 * computer-agent-text.test.mjs fails on any other.
 */
export const STABLE_COMMANDS = Object.freeze([
  'search',
  'docs',
  'component',
  'template',
  'build',
  'theme',
  'init',
  'doctor',
  'help',
]);

/**
 * When an agent should load the skill; the frontmatter `description`. One
 * sentence.
 */
const SKILL_DESCRIPTION =
  'Astryx, a design system and UI library, is available on this computer through the astryx command; use it when building or changing UI, choosing components, layout, styling or theming, working with a design system, or in any project that depends on @astryxdesign packages or mentions Astryx.';

/**
 * A home-folder path as a person reads it: `~/.claude/skills/astryx`.
 * @param {string} file
 * @param {string} [home]
 * @returns {string}
 */
export function displayHomePath(file, home = os.homedir()) {
  const rel = path.relative(home, file);
  return rel && !rel.startsWith('..') && !path.isAbsolute(rel)
    ? `~${path.sep}${rel}`
    : file;
}

/**
 * The skill file's absolute path.
 * @param {string} [home]
 * @returns {string}
 */
export function computerSkillFile(home = os.homedir()) {
  return path.join(home, SKILL_FOLDER, 'SKILL.md');
}

/**
 * The absolute path of each link the table names, and whether it is wanted
 * on this computer (its condition folder exists).
 * @param {string} [home]
 * @returns {Array<{path: string, wanted: boolean, mode: 'link' | 'copy'}>}
 */
export function computerSkillLinks(home = os.homedir()) {
  return SKILL_LINKS.map(({skills, when, mode}) => ({
    path: path.join(home, skills, 'astryx'),
    wanted: when == null || fs.existsSync(path.join(home, when)),
    mode,
  }));
}

/**
 * The command the computer-level text tells agents to run: the host's door
 * when one started this run, else `astryx`. An integration's `cliCommand`
 * never applies: no project, so no integration, is in scope.
 * @returns {string}
 */
export function computerAgentCommand() {
  return cliDoor() ?? COMPUTER_COMMAND;
}

/**
 * The body lines, with `run` as the command and `install` as the step that
 * installs it.
 * @param {string} run
 * @param {string} install
 * @returns {string[]}
 */
function bodyLines(run, install) {
  return [
    'Astryx, a design system and UI library, is available on this computer.',
    'Use it when you build or change UI, pick components, or style or theme an app.',
    `Its docs, components, templates, and themes are all reachable through \`${run}\`. Start with \`${run} search '<what you need>'\`.`,
    `Then read \`${run} component <Name>\` or \`${run} docs <topic>\`, not the package's files.`,
    "In a project, the project's version of Astryx answers automatically.",
    // How to build, which discovery alone leaves to the agent's own page
    // route: in a project, from the template, with the project agent docs'
    // own workflow lines.
    // A project that already installs Core gets the CLI at that version, as
    // the CLI's own hint for that state says, never a newer CLI beside it.
    `To build UI, work in a project folder (create one if there is none). Add \`@astryxdesign/core\` and \`@astryxdesign/cli\` to a new project or one without \`@astryxdesign/core\`; to a project that already has \`@astryxdesign/core\`, add \`@astryxdesign/cli\` at the same version. Run \`${run} init\` there and follow the agent docs it writes.`,
    WORKFLOW_TITLE,
    ...WORKFLOW_STEPS.map(step => step.replaceAll('`astryx ', `\`${run} `)),
    `Before you deliver, re-read each file; ${SELF_CHECK_CSS}. Then build the project and deliver that build, not a description of it.`,
    // A host's door is the host's to restore; only the global command has an
    // install step to name.
    ...(run === COMPUTER_COMMAND ? [computerRestoreLine(install)] : []),
  ];
}

/**
 * The command a skill file's text names: the one in its "Start with" line,
 * or null when the text has none.
 * @param {string} content
 * @returns {string | null}
 */
export function skillCommandOf(content) {
  return /Start with `(.+?) search '/u.exec(content)?.[1] ?? null;
}

/**
 * The full skill file.
 * @param {{command?: string, install?: string}} [options]
 * @returns {string}
 */
export function renderComputerAgentText({
  command = computerAgentCommand(),
  install = COMPUTER_INSTALL_STEP,
} = {}) {
  return withHash(
    [
      '---',
      'name: astryx',
      // Quoted: the description holds `: ` and `;`, which strict YAML parsers
      // can misread, and an agent tool that fails to parse drops the skill.
      `description: ${JSON.stringify(SKILL_DESCRIPTION)}`,
      '---',
      '',
      MARKER_START,
      ...bodyLines(command, install),
      MARKER_END,
      '',
    ].join('\n'),
  );
}

/** The line, right after the start marker, that records the file's hash. */
const HASH_LINE = /^<!-- astryx-managed sha256:([0-9a-f]{64}) -->\n/mu;

/**
 * The sha256 of a file's text without its hash line.
 * @param {string} text
 * @returns {string}
 */
function hashOf(text) {
  return createHash('sha256').update(text).digest('hex');
}

/**
 * Insert the hash line after the start marker.
 * @param {string} text a rendering without a hash line
 * @returns {string}
 */
function withHash(text) {
  const at = text.indexOf(MARKER_START);
  if (at === -1) return text;
  const lineEnd = text.indexOf('\n', at);
  const cut = lineEnd === -1 ? text.length : lineEnd + 1;
  return `${text.slice(0, cut)}<!-- astryx-managed sha256:${hashOf(text)} -->\n${text.slice(cut)}`;
}

/**
 * Whether a file with the markers is unedited: it carries a hash line, and
 * the hash matches the rest of its text.
 * @param {string} content
 * @returns {boolean}
 */
function isUnedited(content) {
  const match = HASH_LINE.exec(content);
  if (!match) return false;
  return hashOf(content.replace(HASH_LINE, '')) === match[1];
}

/**
 * What is at one path of the computer-level text.
 * - `absent`: nothing there.
 * - `current`: an Astryx file with exactly this release's rendering.
 * - `differs`: an unedited Astryx file (its recorded hash matches) with
 *   another rendering, such as another release's.
 * - `edited`: an Astryx file (it has the markers) whose text no longer
 *   matches its recorded hash, or that records none: a person changed it.
 *   Never changed.
 * - `foreign`: a file without the Astryx markers, a symlink, or something
 *   other than a regular file. Never changed.
 * - `linked`, `dangling` (a link only): a link to the skill folder, or one
 *   whose folder is missing (see linkStateOf).
 * @typedef {'absent' | 'current' | 'differs' | 'edited' | 'foreign' | 'linked' | 'dangling'} ComputerAgentTextState
 */

/**
 * @param {string} content
 * @returns {boolean}
 */
function hasMarkers(content) {
  const start = content.indexOf(MARKER_START);
  return start !== -1 && content.indexOf(MARKER_END, start) !== -1;
}

/**
 * The state of one path, read without following a symlinked file.
 * @param {string} file
 * @param {string} expected
 * @returns {ComputerAgentTextState}
 */
function stateOf(file, expected) {
  /** @type {fs.Stats} */
  let stat;
  try {
    stat = fs.lstatSync(file);
  } catch {
    return 'absent';
  }
  if (!stat.isFile()) return 'foreign';
  let content;
  try {
    content = fs.readFileSync(file, 'utf8');
  } catch {
    return 'foreign';
  }
  if (!hasMarkers(content)) return 'foreign';
  if (content === expected) return 'current';
  return isUnedited(content) ? 'differs' : 'edited';
}

/**
 * The state of one link target.
 * - `linked`: a link to the skill folder.
 * - `dangling`: a link to the skill folder, which is not there, as in a
 *   container that mounts only the agent's own folder.
 * - `absent`: nothing there.
 * - `differs`: a real folder holding only an unedited Astryx skill file, as a
 *   copy left it; replaced by the link.
 * - `foreign`: anything else. Never changed.
 * @param {string} at
 * @param {string} folder the skill folder
 * @returns {ComputerAgentTextState}
 */
function linkStateOf(at, folder) {
  /** @type {fs.Stats} */
  let stat;
  try {
    stat = fs.lstatSync(at);
  } catch {
    return 'absent';
  }
  if (stat.isSymbolicLink()) {
    const leads = pointsAt(at, folder);
    if (leads == null) return 'foreign';
    // A link the system cannot follow to the folder is broken, whatever its
    // text says.
    if (leads === 'names') return 'dangling';
    return fs.existsSync(path.join(folder, 'SKILL.md')) ? 'linked' : 'dangling';
  }
  if (!stat.isDirectory()) return 'foreign';
  return copyStateOf(at, '') === 'differs' ? 'differs' : 'foreign';
}

/**
 * The state of a managed copy: a real folder at `at` holding only the skill
 * file, read like the skill file itself.
 * @param {string} at
 * @param {string} expected
 * @returns {ComputerAgentTextState}
 */
function copyStateOf(at, expected) {
  /** @type {fs.Stats} */
  let stat;
  try {
    stat = fs.lstatSync(at);
  } catch {
    return 'absent';
  }
  if (!stat.isDirectory()) return 'foreign';
  let names;
  try {
    names = fs.readdirSync(at);
  } catch {
    return 'foreign';
  }
  if (names.length === 0) return 'absent';
  if (names.length !== 1 || names[0] !== 'SKILL.md') return 'foreign';
  const state = stateOf(path.join(at, 'SKILL.md'), expected);
  return state === 'current' && expected === '' ? 'differs' : state;
}

/**
 * Where the link at `at` leads `folder`'s way, as the system follows it: a
 * relative target resolves from the folder the link really sits in, which
 * differs from its path when a folder above it is itself a link (such as
 * `~/.claude` linked to a dotfiles folder). `reaches`: the system reaches
 * `folder` (which may be missing). `names`: only the target's text, read from
 * the link's path, names `folder`, as a link an earlier release made under a
 * linked folder does; the system cannot follow it. Otherwise null.
 * @param {string} at
 * @param {string} folder
 * @returns {'reaches' | 'names' | null}
 */
function pointsAt(at, folder) {
  try {
    const text = fs.readlinkSync(at);
    const followed = path.resolve(realPath(path.dirname(at)), text);
    const wanted = realPath(folder);
    if (samePath(followed.replace(/[\\/]+$/u, ''), wanted)) return 'reaches';
    const named = path.resolve(path.dirname(at), text);
    return samePath(named.replace(/[\\/]+$/u, ''), folder) ? 'names' : null;
  } catch {
    return null;
  }
}

/**
 * `p` with every link in it resolved, as far as it exists: a missing tail is
 * kept as written.
 * @param {string} p
 * @returns {string}
 */
function realPath(p) {
  try {
    return fs.realpathSync(p);
  } catch {
    const parent = path.dirname(p);
    return parent === p ? p : path.join(realPath(parent), path.basename(p));
  }
}

/**
 * Read-only: the state of the skill file against this release's rendering,
 * then of each place the table wants on this computer, or that Astryx linked.
 * @param {{home?: string, command?: string, links?: readonly string[]}} [options]
 *   `links`: the links Astryx made, from the settings file
 * @returns {Array<{path: string, state: ComputerAgentTextState, link?: true}>}
 */
export function inspectComputerAgentText({
  home = os.homedir(),
  command,
  links = [],
} = {}) {
  const expected = renderComputerAgentText({
    command,
    install: computerInstallStep({home, for: 'judge'}),
  });
  const folder = path.join(home, SKILL_FOLDER);
  const made = new Set(links);
  return [
    {
      path: computerSkillFile(home),
      state: stateOf(computerSkillFile(home), expected),
    },
    ...computerSkillLinks(home)
      .filter(place => place.wanted || made.has(place.path))
      .map(place => {
        const linkState = linkStateOf(place.path, folder);
        const state =
          place.mode === 'copy' && linkState !== 'linked'
            ? copyStateOf(place.path, expected)
            : linkState;
        return {path: place.path, state, link: /** @type {const} */ (true)};
      }),
  ];
}

/**
 * Write `content` to `file` without following a symlink planted at it.
 * @param {string} file
 * @param {string} content
 */
function writeNoFollow(file, content) {
  const flags =
    fs.constants.O_WRONLY |
    fs.constants.O_CREAT |
    fs.constants.O_TRUNC |
    (fs.constants.O_NOFOLLOW ?? 0);
  const fd = fs.openSync(file, flags, 0o644);
  try {
    fs.writeFileSync(fd, content);
  } finally {
    fs.closeSync(fd);
  }
}

/**
 * Why a path was kept: a person edited it, or Astryx did not create it.
 * @param {ComputerAgentTextState} state
 * @returns {'edited' | 'not-astryx'}
 */
const keptReason = state => (state === 'edited' ? 'edited' : 'not-astryx');

/**
 * Remove an unedited Astryx file, or a folder holding only one, and its
 * emptied folder.
 * @param {string} file
 */
function removeFile(file) {
  fs.unlinkSync(file);
  try {
    fs.rmdirSync(path.dirname(file));
  } catch {
    // The folder holds something else; leave it.
  }
}

/**
 * Link `at` to `folder`: a folder symlink with a relative target, which
 * survives a moved or synced home folder, or a junction (absolute) on Windows.
 * The target is relative to the folder the link really sits in, because the
 * system resolves it from there: with `~/.claude` linked to
 * `~/dotfiles/.claude`, a target worked out from `~/.claude/skills` would
 * dangle. With no common base between the two, the target is absolute.
 * @param {string} at
 * @param {string} folder
 */
function makeLink(at, folder) {
  fs.mkdirSync(path.dirname(at), {recursive: true});
  if (process.platform === 'win32') {
    fs.symlinkSync(folder, at, 'junction');
    return;
  }
  const realFolder = fs.realpathSync(folder);
  const relative = path.relative(fs.realpathSync(path.dirname(at)), realFolder);
  fs.symlinkSync(path.isAbsolute(relative) ? realFolder : relative, at, 'dir');
}

/**
 * Write or refresh a managed copy of the skill file in the folder `at`.
 * @param {string} at
 * @param {string} expected
 * @returns {import('../../api/init/init.type.mjs').InitUserFile}
 */
function writeCopy(at, expected) {
  const state = copyStateOf(at, expected);
  if (state === 'current') return {path: at, action: 'unchanged'};
  if (state === 'foreign' || state === 'edited') {
    return {path: at, action: 'kept', reason: keptReason(state)};
  }
  try {
    fs.mkdirSync(at, {recursive: true});
    writeNoFollow(path.join(at, 'SKILL.md'), expected);
    return {path: at, action: 'written'};
  } catch {
    return {path: at, action: 'kept', reason: 'not-astryx'};
  }
}

/**
 * Write or refresh the skill file, and link it into every folder the table
 * wants on this computer. A file without the Astryx markers, an edited one, a
 * symlinked one, and a link target holding anything Astryx did not create are
 * kept as they are. Returns the receipt rows and the links that now point at
 * the skill folder, for the settings file.
 * @param {{home?: string, command?: string}} [options]
 * @returns {{rows: import('../../api/init/init.type.mjs').InitUserFile[], links: string[]}}
 */
export function writeComputerAgentText({home = os.homedir(), command} = {}) {
  // Judged by the step the file records, so a file another copy of this
  // release wrote stays as it is; a write records this copy's own step.
  const judged = renderComputerAgentText({
    command,
    install: computerInstallStep({home, for: 'judge'}),
  });
  const file = computerSkillFile(home);
  const folder = path.dirname(file);
  /** @type {import('../../api/init/init.type.mjs').InitUserFile[]} */
  const rows = [];
  const state = stateOf(file, judged);
  const expected =
    state === 'current'
      ? judged
      : renderComputerAgentText({
          command,
          install: computerInstallStep({home, for: 'write'}),
        });
  if (state === 'foreign' || state === 'edited') {
    rows.push({path: file, action: 'kept', reason: keptReason(state)});
  } else if (state === 'current') {
    rows.push({path: file, action: 'unchanged'});
  } else {
    fs.mkdirSync(folder, {recursive: true});
    writeNoFollow(file, expected);
    rows.push({path: file, action: 'written'});
  }
  /** @type {string[]} */
  const links = [];
  for (const place of computerSkillLinks(home)) {
    if (!place.wanted) continue;
    const at = place.path;
    const linkState = linkStateOf(at, folder);
    if (linkState === 'linked') {
      links.push(at);
      rows.push({path: at, action: 'unchanged'});
      continue;
    }
    if (place.mode === 'copy') {
      rows.push(writeCopy(at, expected));
      continue;
    }
    if (linkState === 'foreign') {
      rows.push({path: at, action: 'kept', reason: 'not-astryx'});
      continue;
    }
    if (linkState === 'differs') removeFile(path.join(at, 'SKILL.md'));
    // The skill folder exists now, so a link still dangling here is one
    // whose target the system resolves from a linked folder above it: an
    // Astryx link, remade so that it resolves.
    if (linkState === 'dangling') fs.unlinkSync(at);
    try {
      makeLink(at, folder);
      links.push(at);
      rows.push({path: at, action: 'linked'});
    } catch {
      // A folder link that cannot be made (Windows without a junction, a
      // file system without links) gets a managed copy instead.
      rows.push(writeCopy(at, expected));
    }
  }
  return {rows, links};
}

/**
 * Remove the skill file and every link Astryx made that still points at its
 * folder. A file without the Astryx markers, an edited one, or a symlinked
 * one, and any link Astryx did not make, are kept.
 * @param {{home?: string, links?: readonly string[]}} [options]
 * @returns {import('../../api/init/init.type.mjs').InitUserFile[]}
 */
export function removeComputerAgentText({
  home = os.homedir(),
  links = [],
} = {}) {
  const file = computerSkillFile(home);
  const folder = path.dirname(file);
  /** @type {import('../../api/init/init.type.mjs').InitUserFile[]} */
  const rows = [];
  for (const at of links) {
    const linkState = linkStateOf(at, folder);
    if (linkState !== 'linked' && linkState !== 'dangling') continue;
    try {
      fs.unlinkSync(at);
      rows.push({path: at, action: 'removed'});
    } catch {
      rows.push({path: at, action: 'kept', reason: 'not-astryx'});
    }
  }
  // Managed copies are told apart by their markers and hash, like the file.
  for (const place of computerSkillLinks(home)) {
    if (copyStateOf(place.path, '') !== 'differs') continue;
    removeFile(path.join(place.path, 'SKILL.md'));
    rows.push({path: place.path, action: 'removed'});
  }
  const state = stateOf(file, '');
  if (state === 'absent') {
    rows.unshift({path: file, action: 'absent'});
  } else if (state === 'foreign' || state === 'edited') {
    rows.unshift({path: file, action: 'kept', reason: keptReason(state)});
  } else {
    removeFile(file);
    rows.unshift({path: file, action: 'removed'});
  }
  return rows;
}

/**
 * Whether the `astryx` a shell would run from this computer's search path is
 * the Astryx CLI: the first `astryx` found is the one that runs.
 * @param {{searchPath?: string, platform?: NodeJS.Platform}} [options]
 * @returns {boolean}
 */
export function astryxOnSearchPath(options = {}) {
  return astryxCommandsOnSearchPath(options)[0]?.astryx ?? false;
}