Skip to content

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

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

/**
 * @file Computer-level integrations (spec AST-081 FR12): the integration
 * packages installed in the same install root as the running copy of the CLI,
 * such as a package manager's global folder beside a global copy, or the
 * package set a door installs together.
 *
 * - The install root is the folder whose `node_modules` holds the running
 *   CLI package (above pnpm's `.pnpm` store). pnpm 11 and later give each
 *   global package a folder of its own, and every one of them counts. A
 *   package runner's temporary install and the per-user release cache are not
 *   install roots: they hold what one run asked for.
 * - When the root has a package.json, its declared dependencies are read, as
 *   autolink reads a project's; otherwise (npm's global folder) every package
 *   directly in its `node_modules`, scoped ones included. Either way, only a
 *   package with exactly one root `astryx.integration.*` manifest counts, and
 *   the CLI and Core packages never do.
 * - Outside a project they load as a project's integrations do (Project.load).
 *   One whose declared `@astryxdesign/core` or `@astryxdesign/cli` peer range
 *   excludes the answering release is skipped, and doctor says why.
 * - Inside a project none load; discover lists the ones the project does not
 *   install as available, and doctor names them.
 *
 * Listing reads package.json files only; nothing is imported until a load.
 *
 * @input  the running CLI package's folder
 * @output the computer-level integration candidates, and their loaded records
 * @position foundation/integrations — read by config/project, discover, and
 *   doctor.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {findManifestPaths, loadIntegrations} from './integrations.mjs';
import {
  readDeclaredDependencies,
  resolveInstalledPackageDir,
} from './autolink.mjs';
import {installPlaceOf} from '../release/choose.mjs';
import {isInReleaseCache} from '../release/cache.mjs';
import {satisfiesRange} from '../env/semver.mjs';

/** Packages that are the CLI itself, never an integration of it. */
const NOT_INTEGRATIONS = new Set(['@astryxdesign/cli', '@astryxdesign/core']);

/** Peers whose ranges must admit the answering release. */
const RELEASE_PEERS = ['@astryxdesign/core', '@astryxdesign/cli'];

/**
 * @typedef {object} ComputerIntegrationCandidate
 * @property {string} name the package name
 * @property {string | undefined} version
 * @property {string | undefined} description
 * @property {string} packageDir
 * @property {string} hostDir the folder whose node_modules holds it
 * @property {string | null} incompatible why its peer ranges exclude the
 *   answering release, or null
 */

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

/**
 * @param {string} dir
 * @returns {Record<string, any> | null}
 */
function readPackage(dir) {
  try {
    const pkg = JSON.parse(
      fs.readFileSync(path.join(dir, 'package.json'), 'utf8'),
    );
    return pkg && typeof pkg === 'object' ? pkg : null;
  } catch {
    return null;
  }
}

/**
 * The install root of the CLI package at `cliRoot`, or null when it has none
 * that counts: it is not installed in a `node_modules` folder, or it lives in
 * a package runner's temporary install or the per-user release cache.
 * @param {string} cliRoot
 * @param {{cacheDir?: string}} [options]
 * @returns {string | null}
 */
export function computerInstallRoot(cliRoot, options = {}) {
  const root = real(cliRoot);
  const place = installPlaceOf(root);
  if (place.runner || !place.owner) return null;
  if (isInReleaseCache(root, options.cacheDir)) return null;
  return place.owner;
}

/**
 * Every install root that holds packages installed with the CLI at
 * `cliRoot`. Usually one: its install root. pnpm 11 and later install each
 * global package in a folder of its own, `<pnpm home>/global/v<N>/<id>`, with
 * its files in `<pnpm home>/store/v<N>/links` or inside that folder, so every
 * such global folder counts, provided one of them installs this CLI.
 * @param {string} cliRoot
 * @param {{cacheDir?: string}} [options]
 * @returns {string[]}
 */
export function computerInstallRoots(cliRoot, options = {}) {
  const fromPnpm = pnpmGlobalFolders(real(cliRoot));
  if (fromPnpm.length > 0) return fromPnpm;
  const root = computerInstallRoot(cliRoot, options);
  return root ? [root] : [];
}

/**
 * pnpm's global folders for a CLI installed globally by pnpm 11 or later, or
 * none. Its files are either in pnpm's store (`<home>/store/v<N>/links/...`,
 * with the global virtual store) or inside its own global folder
 * (`<home>/global/v<N>/<id>/node_modules/...`, without it).
 * @param {string} cli the CLI package's real path
 * @returns {string[]}
 */
function pnpmGlobalFolders(cli) {
  const parts = cli.split(/[\\/]/);
  /** @type {string | null} */
  let globalDir = null;
  const storeAt = parts.lastIndexOf('store');
  if (
    storeAt > 0 &&
    /^v\d+$/.test(parts[storeAt + 1] ?? '') &&
    parts[storeAt + 2] === 'links'
  ) {
    const home = parts.slice(0, storeAt).join(path.sep) || path.sep;
    globalDir = path.join(home, 'global', parts[storeAt + 1]);
  } else {
    const at = parts.findIndex(
      (part, k) =>
        part === 'global' &&
        /^v\d+$/.test(parts[k + 1] ?? '') &&
        parts[k + 3] === 'node_modules',
    );
    if (at > 0) globalDir = parts.slice(0, at + 2).join(path.sep) || path.sep;
  }
  if (globalDir == null) return [];
  /** @type {string[]} */
  let names;
  try {
    names = fs.readdirSync(globalDir).sort();
  } catch {
    return [];
  }
  const folders = names
    .map(name => path.join(globalDir, name))
    .filter(dir => fs.existsSync(path.join(dir, 'package.json')));
  const installsThisCli = folders.some(
    dir => real(path.join(dir, 'node_modules', '@astryxdesign', 'cli')) === cli,
  );
  return installsThisCli ? folders : [];
}

/**
 * Every package name directly in `<root>/node_modules`, scoped ones included.
 * @param {string} root
 * @returns {string[]}
 */
function installedNames(root) {
  const modules = path.join(root, 'node_modules');
  /** @type {string[]} */
  const names = [];
  /** @type {fs.Dirent[]} */
  let entries;
  try {
    entries = fs.readdirSync(modules, {withFileTypes: true});
  } catch {
    return names;
  }
  for (const entry of entries) {
    if (entry.name.startsWith('.')) continue;
    if (entry.name.startsWith('@')) {
      try {
        for (const scoped of fs.readdirSync(path.join(modules, entry.name))) {
          if (!scoped.startsWith('.')) names.push(`${entry.name}/${scoped}`);
        }
      } catch {
        // An unreadable scope folder holds nothing to read.
      }
    } else {
      names.push(entry.name);
    }
  }
  return names.sort();
}

/**
 * Why `pkg`'s peer ranges exclude `release`, or null when they admit it.
 * @param {Record<string, any>} pkg
 * @param {string} release the answering release's version
 * @returns {string | null}
 */
export function peerProblem(pkg, release) {
  const peers = pkg.peerDependencies;
  if (!peers || typeof peers !== 'object') return null;
  for (const peer of RELEASE_PEERS) {
    const range = peers[peer];
    if (typeof range !== 'string') continue;
    let admits;
    try {
      admits = satisfiesRange(release, range);
    } catch {
      // A range this CLI cannot read never keeps the integration out.
      admits = true;
    }
    if (!admits) {
      return `it needs ${peer} ${range}, and this computer's CLI is ${release}`;
    }
  }
  return null;
}

/**
 * The computer-level integrations installed beside the CLI at `cliRoot`, in
 * name order (declaration order when the root declares them), then each
 * integration a host approves (`approved`, architecture:cli-surface INV30),
 * resolved by name from the package set that holds that CLI alone. Reads
 * package.json files only.
 * @param {{cliRoot: string, release: string, cacheDir?: string, approved?: readonly string[]}} options
 * @returns {ComputerIntegrationCandidate[]}
 */
export function scanComputerIntegrations({
  cliRoot,
  release,
  cacheDir,
  approved = [],
}) {
  const self = real(cliRoot);
  /** @type {ComputerIntegrationCandidate[]} */
  const found = [];
  const seen = new Set();
  for (const root of computerInstallRoots(cliRoot, {cacheDir})) {
    scanRoot(root, {self, release, found, seen});
  }
  const owner = approved.length > 0 ? installPlaceOf(self).owner : null;
  if (owner) scanRoot(owner, {self, release, found, seen}, approved);
  return found;
}

/**
 * `name` as installed in `root`'s own `node_modules`, never in a folder above.
 * @param {string} name
 * @param {string} root
 * @returns {{packageDir: string, hostDir: string} | null}
 */
function ownPackageDir(name, root) {
  const packageDir = path.join(root, 'node_modules', ...name.split('/'));
  return fs.existsSync(path.join(packageDir, 'package.json'))
    ? {packageDir, hostDir: root}
    : null;
}

/**
 * Add the integrations installed in one install root: those it declares or
 * installs, or, given `approved`, those names installed in its own
 * `node_modules`.
 * @param {string} root
 * @param {{self: string, release: string, found: ComputerIntegrationCandidate[], seen: Set<string>}} into
 * @param {readonly string[] | null} [approved]
 */
function scanRoot(root, {self, release, found, seen}, approved = null) {
  const declared =
    approved ??
    (readPackage(root)
      ? readDeclaredDependencies(root).map(d => d.name)
      : installedNames(root));
  for (const name of declared) {
    if (NOT_INTEGRATIONS.has(name)) continue;
    const resolved = approved
      ? ownPackageDir(name, root)
      : resolveInstalledPackageDir(name, root);
    if (!resolved) continue;
    const identity = real(resolved.packageDir);
    if (identity === self || seen.has(identity)) continue;
    if (findManifestPaths(resolved.packageDir).length !== 1) continue;
    const pkg = readPackage(resolved.packageDir);
    if (!pkg || typeof pkg.name !== 'string') continue;
    if (NOT_INTEGRATIONS.has(pkg.name)) continue;
    seen.add(identity);
    found.push({
      name: pkg.name,
      version: typeof pkg.version === 'string' ? pkg.version : undefined,
      description:
        typeof pkg.description === 'string' ? pkg.description : undefined,
      packageDir: resolved.packageDir,
      hostDir: resolved.hostDir,
      incompatible: peerProblem(pkg, release),
    });
  }
}

/**
 * Load the compatible computer-level integrations as provider candidates,
 * each in isolation, under the autolinked policy (a broken one is recorded
 * and contributes nothing; the same package reached twice loads once). Each
 * loaded record is marked `__computer`. An incompatible one is not loaded.
 * @param {ComputerIntegrationCandidate[]} candidates
 * @param {{fresh?: boolean, exclude?: Iterable<string>}} [options] `exclude`
 *   names packages the folder already loads, which keep their own copy
 * @returns {Promise<import('./provider-resolution.mjs').ProviderCandidate[]>}
 */
export async function loadComputerIntegrations(candidates, options = {}) {
  const {fresh = false, exclude = []} = options;
  const taken = new Set(exclude);
  /** @type {import('./provider-resolution.mjs').ProviderCandidate[]} */
  const loaded = [];
  for (const candidate of candidates) {
    if (candidate.incompatible || taken.has(candidate.name)) continue;
    try {
      const [integration] = await loadIntegrations([candidate.name], {
        cwd: candidate.hostDir,
        fresh,
      });
      loaded.push({
        source: 'autolinked',
        spec: candidate.name,
        packageDir: candidate.packageDir,
        ...(integration == null
          ? {}
          : {integration: {...integration, __computer: true}}),
      });
    } catch (error) {
      loaded.push({
        source: 'autolinked',
        spec: candidate.name,
        packageDir: candidate.packageDir,
        error: error instanceof Error ? error.message : String(error),
      });
    }
  }
  return loaded;
}