Skip to content

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

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

/**
 * @file Which release answers a run (spec AST-081 FR2, FR3, FR6, FR9).
 *
 * As released, the project decides who answers (DEC-10):
 *
 * - **In a project that installs its own CLI**, that CLI answers, whatever its
 *   version: every other copy hands the run to it, `astryx upgrade` included.
 * - **In a project with no CLI of its own** (only Core, or nothing installed
 *   yet), the copy that started the run answers, as it always has; a hint,
 *   once a day, names the command that adds the CLI at Core's version
 *   (notices.mjs).
 * - **When the project's own CLI cannot start**, the release equal to the
 *   project's Core answers (the matched release): the copy that started the
 *   run when it is that release, else the release in the per-user cache,
 *   installed first. When it cannot be obtained, the copy that started the
 *   run answers, announced (handoff.mjs).
 * - **Outside a project**, every copy answers itself, the global copy
 *   included; a newer release is announced, never installed (notices.mjs).
 *
 * Core deciding over the project's own CLI, and the matched release for a
 * project with only Core, are the next minor release's change.
 *
 * A copy never hands a run to itself, so a run is handed off at most once:
 * the copy it reaches makes the same choice and finds itself.
 *
 * @input  the folder, the running copy
 * @output a {@link ReleaseChoice}
 * @position foundation/release — called once per run by handoff.mjs.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {
  readReleaseFacts,
  readJson,
  CORE_PACKAGE_NAME,
  CLI_PACKAGE_NAME,
} from './project.mjs';
import {
  cliBinOf,
  isInReleaseCache,
  isReleaseVersion,
  resolvePublishedVersion,
  userCacheDir,
} from './cache.mjs';
import {relativeWithin, samePath} from '../fs/path-compare.mjs';

/**
 * The copy that is running.
 * @typedef {object} RunningCopy
 * @property {string} version its package version
 * @property {string} root its package folder
 */

/**
 * Who answers the run.
 * @typedef {object} ReleaseChoice
 * @property {'project' | 'starting' | 'matched' | 'carried' | 'fallback'} copy
 *   the kind of copy that answers (`meta.answeredBy.copy`): `project`, the
 *   project's own CLI; `starting`, the copy that started the run, in a project
 *   with no CLI of its own; `matched`, the release equal to the project's
 *   Core, when the project's own CLI cannot start; `carried`, outside a
 *   project; `fallback`, the copy that started the run when the matched
 *   release could not be obtained (spec AST-081 FR2, FR5)
 * @property {'self' | 'project-cli' | 'release'} answer `self`: this copy;
 *   `project-cli`: hand off to the project's CLI; `release`: hand off to the
 *   cached release `version`
 * @property {string} version the release that answers
 * @property {string | null} bin the entry file to hand off to (`project-cli`
 *   and a cached `release` that is already installed)
 * @property {string | null} coreVersion the Core the answering release pairs
 *   with, when known now
 * @property {boolean} inProject
 * @property {string | null} unavailable why the release cannot answer, when it
 *   cannot
 */

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

/** Folder-name patterns of package-manager global installs that hold a package.json. */
const GLOBAL_OWNER_PATTERNS = [
  // pnpm: `<pnpm home>/global/5` before pnpm 10, `<pnpm home>/global/v11/<id>` since.
  /[\\/]global[\\/]v?\d+(?:[\\/][^\\/]+)?$/,
  // Yarn 1: `~/.config/yarn/global`, or `%LOCALAPPDATA%\Yarn\Data\global` on Windows.
  /[\\/]yarn[\\/](?:data[\\/])?global$/i,
  // Bun: `<BUN_INSTALL>/install/global`, `~/.bun/install/global` by default.
  /[\\/]install[\\/]global$/i,
];

/**
 * Where a global install's settings come from: the home folder, the
 * environment, and the platform. Defaults to this process's.
 * @typedef {{home?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform}} GlobalWhere
 */

/**
 * The value a line `<key> <value>` or `<key>=<value>` sets in a package
 * manager's settings file (`.yarnrc`, `.npmrc`, `bunfig.toml`), unquoted, or
 * null.
 * @param {string} file
 * @param {string} key
 * @returns {string | null}
 */
function settingIn(file, key) {
  let text;
  try {
    text = fs.readFileSync(file, 'utf8');
  } catch {
    return null;
  }
  const escaped = key.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
  const match = new RegExp(
    `^\\s*${escaped}\\s*(?:=|\\s)\\s*(.+?)\\s*$`,
    'mu',
  ).exec(text);
  if (!match) return null;
  return match[1].replace(/^(["'])(.*)\1$/u, '$2');
}

/**
 * An absolute folder from a setting, with `~` for the home folder; null for a
 * relative or empty one.
 * @param {string | null | undefined} value
 * @param {string} home
 * @param {NodeJS.Platform} platform
 * @returns {string | null}
 */
function absoluteFolder(value, home, platform) {
  if (!value) return null;
  const paths = platform === 'win32' ? path.win32 : path.posix;
  const expanded = value.startsWith('~')
    ? paths.join(home, value.slice(1))
    : value;
  return paths.isAbsolute(expanded) ? paths.normalize(expanded) : null;
}

/**
 * The global folders the package managers' own settings name on this
 * computer, read the way each package manager reads them, never guessed from
 * a folder's layout:
 * - Bun: `$BUN_INSTALL/install/global`, else `~/.bun/install/global`, and a
 *   `globalDir` in `~/.bunfig.toml` or `$XDG_CONFIG_HOME/.bunfig.toml`.
 * - Yarn 1: the `global-folder` setting (`YARN_GLOBAL_FOLDER`,
 *   `npm_config_global_folder`, or `global-folder` in `~/.yarnrc`), else
 *   `<data folder>/global`: `%LOCALAPPDATA%\Yarn\Data` on Windows,
 *   `$XDG_DATA_HOME/yarn`, else `~/.config/yarn`.
 * - pnpm: `<PNPM_HOME>/global`, else `<data folder>/global` (`$XDG_DATA_HOME/pnpm`,
 *   else `%LOCALAPPDATA%\pnpm`, `~/Library/pnpm`, or `~/.local/share/pnpm`), and a
 *   `global-dir` in `~/.npmrc` or pnpm's `rc` file; a global install is a
 *   numbered folder below it.
 * @param {GlobalWhere} [where]
 * @returns {Array<{manager: 'bun' | 'yarn' | 'pnpm', folder: string}>}
 */
export function configuredGlobalFolders(where = {}) {
  const {
    home = os.homedir(),
    env = process.env,
    platform = process.platform,
  } = where;
  const paths = platform === 'win32' ? path.win32 : path.posix;
  const abs = (/** @type {string | null | undefined} */ value) =>
    absoluteFolder(value, home, platform);
  const xdgConfig = abs(env.XDG_CONFIG_HOME) ?? paths.join(home, '.config');
  const xdgData = abs(env.XDG_DATA_HOME);
  const localAppData =
    abs(env.LOCALAPPDATA) ?? paths.join(home, 'AppData', 'Local');
  /** @type {Array<{manager: 'bun' | 'yarn' | 'pnpm', folder: string}>} */
  const out = [];
  // Bun
  out.push({
    manager: 'bun',
    folder: paths.join(
      abs(env.BUN_INSTALL) ?? paths.join(home, '.bun'),
      'install',
      'global',
    ),
  });
  for (const file of [
    paths.join(home, '.bunfig.toml'),
    paths.join(xdgConfig, '.bunfig.toml'),
  ]) {
    const dir = abs(settingIn(file, 'globalDir'));
    if (dir) out.push({manager: 'bun', folder: dir});
  }
  // Yarn 1
  const yarnSetting =
    abs(env.YARN_GLOBAL_FOLDER) ??
    abs(env.npm_config_global_folder) ??
    abs(settingIn(paths.join(home, '.yarnrc'), 'global-folder'));
  const yarnData =
    platform === 'win32'
      ? paths.join(localAppData, 'Yarn', 'Data')
      : xdgData
        ? paths.join(xdgData, 'yarn')
        : paths.join(home, '.config', 'yarn');
  out.push({
    manager: 'yarn',
    folder: yarnSetting ?? paths.join(yarnData, 'global'),
  });
  // pnpm
  // pnpm's data folder: PNPM_HOME, else $XDG_DATA_HOME/pnpm on any platform,
  // else the platform's own.
  const pnpmHome =
    abs(env.PNPM_HOME) ??
    (xdgData
      ? paths.join(xdgData, 'pnpm')
      : platform === 'win32'
        ? paths.join(localAppData, 'pnpm')
        : platform === 'darwin'
          ? paths.join(home, 'Library', 'pnpm')
          : paths.join(home, '.local', 'share', 'pnpm'));
  out.push({manager: 'pnpm', folder: paths.join(pnpmHome, 'global')});
  for (const file of [
    paths.join(home, '.npmrc'),
    paths.join(xdgConfig, 'pnpm', 'rc'),
  ]) {
    const dir = abs(settingIn(file, 'global-dir'));
    if (dir) out.push({manager: 'pnpm', folder: dir});
  }
  return out;
}

/**
 * The package manager's global folder that holds the CLI at `root`, when the
 * package manager's own settings name that folder (configuredGlobalFolders);
 * null otherwise. A folder that only looks like one, such as an app made with
 * `yarn add` alone or one under a folder named `install/global`, is not.
 * @param {string} root the CLI package's real folder
 * @param {GlobalWhere} [where]
 * @returns {{manager: 'bun' | 'pnpm' | 'yarn', folder: string} | null}
 */
export function globalFolderOf(root, where = {}) {
  const place = installPlaceOf(root);
  if (place.runner || !place.owner) return null;
  const owner = place.owner;
  const platform = where.platform ?? process.platform;
  for (const known of configuredGlobalFolders(where)) {
    // Compared as real folders, so a linked home folder reads the same.
    const folder = real(known.folder);
    if (known.manager === 'pnpm') {
      // `<global-dir>/<n>` before pnpm 11, `<global-dir>/v<n>/<id>` since.
      const rel = relativeWithin(folder, owner, platform);
      if (rel !== null && /^v?\d+(?:[\\/][^\\/]+)?$/u.test(rel)) {
        return {manager: 'pnpm', folder: owner};
      }
    } else if (samePath(folder, owner, platform)) {
      return {manager: known.manager, folder: owner};
    }
  }
  return null;
}

/** Path markers of package runners' temporary installs. */
const RUNNER_CACHE =
  /[\\/]_npx[\\/]|[\\/]dlx[-\\/]|[\\/]\.bun[\\/]install[\\/]cache[\\/]|[\\/]bunx-|[\\/]xfs-/i;

/**
 * Where an installed CLI package lives: its owner, the folder that holds the
 * `node_modules` it is in (above pnpm's `.pnpm` store), and whether that owner
 * is named like a package manager's default global folder (`knownGlobal`, a
 * hint only: isGlobalCopy decides from the package managers' settings). Pure:
 * reads no file, and
 * accepts either separator, so Windows paths read the same on every platform.
 * @param {string} root the package's real folder
 * @returns {{runner: boolean, owner: string | null, knownGlobal: boolean}}
 */
export function installPlaceOf(root) {
  if (RUNNER_CACHE.test(root)) {
    return {runner: true, owner: null, knownGlobal: false};
  }
  const sep = /^[A-Za-z]:\\|^\\\\/.test(root) ? '\\' : path.sep;
  const parts = root.split(/[\\/]/);
  const at = parts.lastIndexOf('node_modules');
  if (at < 1) return {runner: false, owner: null, knownGlobal: false};
  let owner = parts.slice(0, at).join(sep) || sep;
  // pnpm keeps the real folder in `<owner>/node_modules/.pnpm/<id>/node_modules`,
  // or, for its global folder before pnpm 11, in `<owner>/.pnpm/<id>/node_modules`.
  const pnpmAt = parts.lastIndexOf('.pnpm');
  if (pnpmAt > 0 && pnpmAt < at) {
    owner =
      parts
        .slice(0, parts[pnpmAt - 1] === 'node_modules' ? pnpmAt - 1 : pnpmAt)
        .join(sep) || sep;
  }
  return {
    runner: false,
    owner,
    knownGlobal: GLOBAL_OWNER_PATTERNS.some(re => re.test(owner)),
  };
}

/**
 * Whether `root` is inside a pnpm store's `links` folder (`<store>/v<N>/links`),
 * where the global virtual store keeps its packages.
 * @param {string} root
 * @returns {boolean}
 */
function inPnpmStoreLinks(root) {
  const parts = root.split(/[\\/]/);
  const at = parts.lastIndexOf('links');
  return at >= 2 && /^v\d+$/u.test(parts[at - 1]);
}

/**
 * Whether a global folder of pnpm's, as its settings name it, installs the
 * CLI package at `root`: `<global-dir>/v<N>/<id>/node_modules/@astryxdesign/cli`
 * (or `<global-dir>/<N>/node_modules/…` before pnpm 11) resolves to it.
 * @param {string} root the CLI package's real folder
 * @param {GlobalWhere} where
 * @returns {boolean}
 */
function linkedFromPnpmGlobal(root, where) {
  const platform = where.platform ?? process.platform;
  const cliIn = (/** @type {string} */ dir) =>
    path.join(dir, 'node_modules', '@astryxdesign', 'cli');
  for (const known of configuredGlobalFolders(where)) {
    if (known.manager !== 'pnpm') continue;
    /** @type {string[]} */
    let versions;
    try {
      versions = fs.readdirSync(known.folder);
    } catch {
      continue;
    }
    for (const version of versions.filter(v => /^v?\d+$/u.test(v))) {
      const dir = path.join(known.folder, version);
      /** @type {string[]} */
      let ids = [];
      try {
        ids = fs.readdirSync(dir);
      } catch {
        // Not a folder.
      }
      for (const candidate of [dir, ...ids.map(id => path.join(dir, id))]) {
        if (samePath(real(cliIn(candidate)), root, platform)) return true;
      }
    }
  }
  return false;
}

/**
 * Is the running copy the CLI package installed for the computer
 * (`npm i -g`, `pnpm add -g`, `yarn global add`, `bun add -g`, Volta)?
 *
 * Read from where the package lives: in a `node_modules` folder whose owner
 * holds no package.json (npm's global folder), or whose owner is a global
 * folder a package manager's own settings name (globalFolderOf). A copy in a
 * project, in a package runner's temporary install, or in the release cache
 * is not, and when unsure the answer is no: a copy that is not global runs no
 * update check and writes no agent skill.
 *
 * @param {string} cliRoot
 * @param {string} [cacheDir]
 * @param {GlobalWhere} [where]
 * @returns {boolean}
 */
export function isGlobalCopy(cliRoot, cacheDir = userCacheDir(), where = {}) {
  const root = real(cliRoot);
  const place = installPlaceOf(root);
  if (place.runner || !place.owner || isInReleaseCache(root, cacheDir)) {
    return false;
  }
  if (globalFolderOf(root, where)) return true;
  // pnpm's global virtual store keeps every package, a project's own CLI
  // included, in `<store>/v<N>/links/…`, whose folders hold no package.json:
  // global only when a pnpm global folder the settings name links to it.
  if (inPnpmStoreLinks(root)) return linkedFromPnpmGlobal(root, where);
  // npm's global folder holds no package.json; a project always has one.
  return !fs.existsSync(path.join(place.owner, 'package.json'));
}

/**
 * The Core release a project records, without asking the registry: the Core
 * the folder reads, else the version its lockfile records, else an exact
 * declared version; null for a range.
 * @param {import('./project.mjs').ReleaseFacts} facts
 * @returns {string | null}
 */
export function coreVersionOf(facts) {
  if (facts.core) return facts.core.version;
  if (isReleaseVersion(facts.lockedCoreVersion)) {
    return /** @type {string} */ (facts.lockedCoreVersion);
  }
  if (facts.declaredCoreRange) {
    return exactOrRange(CORE_PACKAGE_NAME, facts.declaredCoreRange).version;
  }
  return null;
}

/**
 * The release that matches a project's facts, before any registry question.
 * @param {import('./project.mjs').ReleaseFacts} facts
 * @returns {{version: string | null, range: {name: string, spec: string} | null}}
 */
export function matchedVersionOf(facts) {
  if (facts.core) return {version: facts.core.version, range: null};
  if (isReleaseVersion(facts.lockedCoreVersion)) {
    return {version: facts.lockedCoreVersion, range: null};
  }
  if (facts.declaredCoreRange) {
    return exactOrRange(CORE_PACKAGE_NAME, facts.declaredCoreRange);
  }
  if (facts.cli) return {version: facts.cli.version, range: null};
  if (isReleaseVersion(facts.lockedCliVersion)) {
    return {version: facts.lockedCliVersion, range: null};
  }
  if (facts.declaredCliRange) {
    return exactOrRange(CLI_PACKAGE_NAME, facts.declaredCliRange);
  }
  return {version: null, range: null};
}

/**
 * @param {string} name
 * @param {string} spec
 * @returns {{version: string | null, range: {name: string, spec: string} | null}}
 */
function exactOrRange(name, spec) {
  const trimmed = spec.trim().replace(/^=/, '').replace(/^v/, '');
  if (isReleaseVersion(trimmed)) return {version: trimmed, range: null};
  return {version: null, range: {name, spec}};
}

/**
 * Choose who answers a run started by `self` in `cwd`.
 *
 * A command that acts on the computer rather than the folder is chosen as
 * outside a project wherever it runs (`computer`), so a project's older CLI
 * never answers it.
 *
 * @param {{cwd: string, self: RunningCopy, cacheDir?: string, resolve?: typeof resolvePublishedVersion, computer?: boolean}} input
 * @returns {ReleaseChoice}
 */
export function chooseRelease({
  cwd,
  self,
  resolve = resolvePublishedVersion,
  computer = false,
}) {
  const facts = computer ? OUTSIDE : readReleaseFacts(cwd);
  const selfReal = real(self.root);

  if (!facts.inProject) {
    return {
      copy: 'carried',
      answer: 'self',
      version: self.version,
      bin: null,
      coreVersion: null,
      inProject: false,
      unavailable: null,
    };
  }

  // A project that installs its own CLI is answered by that CLI, whatever its
  // version, and a project with none by the copy that started the run, as
  // released (FR2, DEC-10; `spec:AST-017` FR12). Only a project whose own CLI
  // cannot start gets the Core-matched release.
  if (!facts.cli) {
    // A copy that lives inside the project itself, such as a workspace's own
    // CLI package beside its Core package, is the project's own CLI.
    const inside = isInside(selfReal, projectRootOf(facts));
    return {
      copy: inside ? 'project' : 'starting',
      answer: 'self',
      version: self.version,
      bin: null,
      coreVersion: coreVersionOf(facts),
      inProject: true,
      unavailable: null,
    };
  }
  {
    if (samePath(real(facts.cli.dir), selfReal)) {
      return {
        copy: 'project',
        answer: 'self',
        version: facts.cli.version,
        bin: null,
        coreVersion: facts.core?.version ?? null,
        inProject: true,
        unavailable: null,
      };
    }
    const bin = cliBinOf(facts.cli.dir);
    if (bin) {
      return {
        copy: 'project',
        answer: 'project-cli',
        version: facts.cli.version,
        bin,
        coreVersion: facts.core?.version ?? null,
        inProject: true,
        unavailable: null,
      };
    }
  }
  let {version, range} = matchedVersionOf(facts);
  if (!version && range) {
    version = resolve(range.name, range.spec);
    if (!version) {
      return {
        copy: 'matched',
        answer: 'release',
        version: `${range.name}@${range.spec}`,
        bin: null,
        coreVersion: null,
        inProject: true,
        unavailable: `no published release of ${range.name} matching "${range.spec}" could be found`,
      };
    }
  }

  const coreVersion = facts.core?.version ?? version;
  if (!version || version === self.version) {
    // A copy that lives inside the project itself, such as a workspace's own
    // CLI package beside its Core package, is the project's own CLI.
    if (isInside(selfReal, projectRootOf(facts))) {
      return {
        copy: 'project',
        answer: 'self',
        version: self.version,
        bin: null,
        coreVersion: facts.core?.version ?? null,
        inProject: true,
        unavailable: null,
      };
    }
    return {
      copy: 'matched',
      answer: 'self',
      version: self.version,
      bin: null,
      coreVersion,
      inProject: true,
      unavailable: null,
    };
  }
  return {
    copy: 'matched',
    answer: 'release',
    version,
    bin: null,
    coreVersion,
    inProject: true,
    unavailable: null,
  };
}

/**
 * The folder a project's facts point at: the declaring package.json's folder,
 * else the folder that holds the Core (the one above its node_modules, or the
 * workspace root above `packages/core`).
 * @param {import('./project.mjs').ReleaseFacts} facts
 * @returns {string | null}
 */
export function projectRootOf(facts) {
  if (facts.declaringDir) return facts.declaringDir;
  const dir = facts.core?.dir ?? facts.cli?.dir;
  if (!dir) return null;
  const parts = path.resolve(dir).split(path.sep);
  const at = parts.indexOf('node_modules');
  if (at > 0) return parts.slice(0, at).join(path.sep) || path.sep;
  return path.dirname(path.dirname(dir));
}

/**
 * Is `child` inside `parent` (both real paths), outside any node_modules
 * folder in between? A package installed into a project's node_modules is
 * found as the project's CLI already; this covers a copy that is part of the
 * project's own source, such as a workspace package.
 * @param {string} child
 * @param {string | null} parent
 * @returns {boolean}
 */
function isInside(child, parent) {
  if (!parent) return false;
  const rel = relativeWithin(real(parent), child);
  if (rel === null) return false;
  return !rel.split(/[\\/]/).includes('node_modules');
}

/** The facts of a folder outside any project. */
const OUTSIDE = Object.freeze({
  inProject: false,
  core: null,
  cli: null,
  declaringDir: null,
  declaredCoreRange: null,
  declaredCliRange: null,
  lockedCoreVersion: null,
  lockedCliVersion: null,
});

/** Options that take a value, so their value is not the command or topic. */
const VALUE_OPTIONS = new Set(['--lang', '--detail', '--depth']);

/**
 * Is this run a command that acts on the computer rather than the folder it
 * runs in? `astryx init --user`, which writes the computer-level agent text,
 * and `astryx docs global[/…]`, the docs of global mode itself, which the copy
 * that started the run answers, so they are readable inside a project whose
 * release predates them (spec AST-081 FR8, FR9).
 * @param {string[]} argv arguments after `astryx`
 * @returns {boolean}
 */
export function isComputerLevel(argv) {
  const words = [];
  for (let i = 0; i < argv.length && words.length < 2; i++) {
    const arg = argv[i];
    if (VALUE_OPTIONS.has(arg)) {
      i += 1;
      continue;
    }
    if (!arg.startsWith('-')) words.push(arg);
  }
  const [command, topic] = words;
  if (command === 'init') return argv.includes('--user');
  return (
    command === 'docs' &&
    typeof topic === 'string' &&
    (topic === 'global' || topic.startsWith('global/'))
  );
}

/**
 * The running copy, from its package folder.
 * @param {string} root
 * @returns {RunningCopy}
 */
export function runningCopy(root) {
  const pkg = readJson(path.join(root, 'package.json'));
  return {version: String(pkg?.version ?? '0.0.0'), root};
}

/**
 * Does the package at `cliDir` print its own who-answered line? Releases that
 * carry this module do; older ones answer silently, so the copy that hands a
 * run to them prints the line for them.
 * @param {string} cliDir
 * @returns {boolean}
 */
export function namesWhoAnswered(cliDir) {
  return fs.existsSync(
    path.join(cliDir, 'foundation', 'release', 'choose.mjs'),
  );
}

/**
 * The CLI package folder an entry file belongs to.
 * @param {string} bin
 * @returns {string}
 */
export function packageRootOf(bin) {
  let dir = path.dirname(real(bin));
  for (;;) {
    if (readJson(path.join(dir, 'package.json'))?.name === CLI_PACKAGE_NAME)
      return dir;
    const parent = path.dirname(dir);
    if (parent === dir) return path.dirname(real(bin));
    dir = parent;
  }
}