@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/foundation/fs/paths.d.mts

@@ -1,11 +1,67 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The Core a command answers from: the project's (see
+ * {@link findProjectCoreDir}), else, when a copy other than the project's own
+ * CLI answers, the Core that copy carries (spec AST-081 FR3): the
+ * `@astryxdesign/core` of its own release, beside it or in the per-user
+ * release cache. Never fetches; {@link requireCoreDir} does.
+ *
+ * Commands that judge or change a project (`doctor`, `swizzle`, `upgrade`)
+ * read {@link findProjectCoreDir} instead, so a carried Core never passes a
+ * project check or lands in a folder that installed none.
+ *
+ * @param {string} [startDir]
+ * @returns {string | null}
+ */
+export function findCoreDir(startDir?: string): string | null;
+/**
+ * Why a command that reads Core cannot run, when the answering release's own
+ * Core is needed and cannot be installed: outside a project, or in a project
+ * with nothing installed (spec AST-081 FR3).
+ * @param {{unavailable: string | null, version?: string, reason?: string}} found
+ * @param {boolean} inProject
+ * @returns {string}
+ */
+export function unavailableCoreMessage(found: {
+    unavailable: string | null;
+    version?: string;
+    reason?: string;
+}, inProject: boolean): string;
+/**
+ * Like {@link findCoreDir}, but a copy that carries no Core installs its
+ * release's Core into the per-user cache first. Throws ERR_CORE_NOT_FOUND
+ * when there is no Core to answer from, and ERR_VERSIONS_UNAVAILABLE when the
+ * carried Core is needed and cannot be installed.
+ *
+ * @param {string} [startDir]
+ * @returns {string}
+ */
+export function requireCoreDir(startDir?: string): string;
+/**
+ * The carried Core alone, for a caller that already looked for the project's
+ * Core its own way: the folder, or null when the copy answering in `startDir`
+ * is the project's own CLI or carries none.
+ * @param {string} startDir
+ * @param {{fetch?: boolean}} [options]
+ * @returns {string | null}
+ */
+export function findCarriedCoreDir(startDir: string, { fetch }?: {
+    fetch?: boolean;
+}): string | null;
 /**
  * Find packages/core directory by walking up from startDir.
  * Also checks node_modules/@astryxdesign/core for installed usage.
+ *
+ * The project's Core only: in the folder or four above it, the reach every
+ * released version used, else from the folder of the package.json that makes
+ * the folder part of a project, however deep the folder is.
+ *
+ * @param {string} [startDir]
+ * @returns {string | null}
  */
-export function findCoreDir(startDir?: string): string | null;
+export function findProjectCoreDir(startDir?: string): string | null;
 /**
  * Locate a package the project at `startDir` actually installed.
  *

package/foundation/fs/paths.mjs

@@ -11,17 +11,144 @@ import {createRequire} from 'node:module';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {listDir, pathExists} from './listing-cache.mjs';
+import {ERROR_CODES} from '../response/error-codes.mjs';
+import {carriedCore, runChoice} from '../release/run-context.mjs';
+import {findDeclaringPackage} from '../release/project.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 /** Root of the @astryxdesign/cli package */
 export const CLI_ROOT = path.resolve(__dirname, '..', '..');
 
+/**
+ * The Core a command answers from: the project's (see
+ * {@link findProjectCoreDir}), else, when a copy other than the project's own
+ * CLI answers, the Core that copy carries (spec AST-081 FR3): the
+ * `@astryxdesign/core` of its own release, beside it or in the per-user
+ * release cache. Never fetches; {@link requireCoreDir} does.
+ *
+ * Commands that judge or change a project (`doctor`, `swizzle`, `upgrade`)
+ * read {@link findProjectCoreDir} instead, so a carried Core never passes a
+ * project check or lands in a folder that installed none.
+ *
+ * @param {string} [startDir]
+ * @returns {string | null}
+ */
+export function findCoreDir(startDir = process.cwd()) {
+  return findProjectCoreDir(startDir) ?? carriedCoreFor(startDir).dir;
+}
+
+/**
+ * Why a command that reads Core cannot run, when the answering release's own
+ * Core is needed and cannot be installed: outside a project, or in a project
+ * with nothing installed (spec AST-081 FR3).
+ * @param {{unavailable: string | null, version?: string, reason?: string}} found
+ * @param {boolean} inProject
+ * @returns {string}
+ */
+export function unavailableCoreMessage(found, inProject) {
+  const unwritable = /cannot be written/.test(found.unavailable ?? '');
+  if (inProject) {
+    const core = found.version ? `Core ${found.version}` : 'its Core';
+    const why = found.reason ? ` (${found.reason})` : '';
+    return `This project has no Core installed, and ${core} could not be downloaded${why}. Install the project's dependencies${unwritable ? ', or make that folder writable' : ''}, then run again.`;
+  }
+  return `${found.unavailable}. Outside a project, commands that read Core use the Core of the release that answers; ${unwritable ? 'make that folder writable and run again' : 'run again when the package registry can be reached'}.`;
+}
+
+/**
+ * Like {@link findCoreDir}, but a copy that carries no Core installs its
+ * release's Core into the per-user cache first. Throws ERR_CORE_NOT_FOUND
+ * when there is no Core to answer from, and ERR_VERSIONS_UNAVAILABLE when the
+ * carried Core is needed and cannot be installed.
+ *
+ * @param {string} [startDir]
+ * @returns {string}
+ */
+export function requireCoreDir(startDir = process.cwd()) {
+  const found = findProjectCoreDir(startDir) ?? carriedCoreFor(startDir, true);
+  if (typeof found === 'string') return found;
+  if (found.unavailable) {
+    throw codedError(
+      unavailableCoreMessage(found, runChoice(startDir).inProject),
+      ERROR_CODES.ERR_VERSIONS_UNAVAILABLE,
+    );
+  }
+  if (found.dir) return found.dir;
+  throw codedError(
+    'Could not find @astryxdesign/core package',
+    ERROR_CODES.ERR_CORE_NOT_FOUND,
+  );
+}
+
+/**
+ * An Error carrying a stable error code, which the JSON envelope and every
+ * command's error output read the way they read an API error's.
+ * @param {string} message
+ * @param {string} code
+ * @returns {Error & {code: string}}
+ */
+function codedError(message, code) {
+  return Object.assign(new Error(message), {code});
+}
+
+/**
+ * The carried Core alone, for a caller that already looked for the project's
+ * Core its own way: the folder, or null when the copy answering in `startDir`
+ * is the project's own CLI or carries none.
+ * @param {string} startDir
+ * @param {{fetch?: boolean}} [options]
+ * @returns {string | null}
+ */
+export function findCarriedCoreDir(startDir, {fetch = false} = {}) {
+  return carriedCoreFor(startDir, fetch).dir;
+}
+
+/**
+ * The carried Core for a run in `startDir`, when the copy answering there is
+ * not the project's own CLI.
+ * @param {string} startDir
+ * @param {boolean} [fetch]
+ * @returns {{dir: string | null, unavailable: string | null, version?: string, reason?: string}}
+ */
+function carriedCoreFor(startDir, fetch = false) {
+  const carried = carriedCore({fetch: false});
+  if (!carried.dir && !fetch) return carried;
+  if (runChoice(startDir).copy === 'project') {
+    return {dir: null, unavailable: null};
+  }
+  return carried.dir ? carried : carriedCore({fetch: true});
+}
+
 /**
  * Find packages/core directory by walking up from startDir.
  * Also checks node_modules/@astryxdesign/core for installed usage.
+ *
+ * The project's Core only: in the folder or four above it, the reach every
+ * released version used, else from the folder of the package.json that makes
+ * the folder part of a project, however deep the folder is.
+ *
+ * @param {string} [startDir]
+ * @returns {string | null}
  */
-export function findCoreDir(startDir = process.cwd()) {
+export function findProjectCoreDir(startDir = process.cwd()) {
+  const near = findNearbyCoreDir(startDir);
+  if (near) return near;
+  // A folder deeper than that reach still belongs to the project the walk to
+  // its package.json finds, so its Core is looked up from there too (spec
+  // AST-081, a folder's project): never the carried Core in its place.
+  const declaring = findDeclaringPackage(startDir);
+  return declaring && declaring.dir !== path.resolve(startDir)
+    ? findNearbyCoreDir(declaring.dir)
+    : null;
+}
+
+/**
+ * The Core installed in `startDir` or one of the four folders above it.
+ * @param {string} startDir
+ * @returns {string | null}
+ */
+function findNearbyCoreDir(startDir) {
   let dir = startDir;
 
   for (let i = 0; i < 5; i++) {
@@ -153,7 +280,7 @@ export function discoverExternalPackages(startDir = process.cwd()) {
   if (!nodeModulesDir) return externals;
 
   /** @param {string} searchDir */
-  const scanDir = (searchDir) => {
+  const scanDir = searchDir => {
     if (!fs.existsSync(searchDir)) return;
     const entries = fs.readdirSync(searchDir, {withFileTypes: true});
 
@@ -236,7 +363,8 @@ export function existsCaseExact(targetPath, rootDir) {
 
   const rel = path.relative(rootDir, targetPath);
   if (rel === '') return true;
-  if (path.isAbsolute(rel) || rel === '..' || rel.startsWith(`..${path.sep}`)) return false;
+  if (path.isAbsolute(rel) || rel === '..' || rel.startsWith(`..${path.sep}`))
+    return false;
 
   let dir = rootDir;
   for (const segment of rel.split(path.sep)) {

package/foundation/fs/paths.test.mjs

@@ -4,7 +4,9 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {findCoreDir, findProjectRoot, listComponents, discoverExternalPackages, existsCaseExact, findInstalledPackage} from './paths.mjs';
+import {findCoreDir, findProjectCoreDir, findProjectRoot, listComponents, discoverExternalPackages, existsCaseExact, findInstalledPackage} from './paths.mjs';
+import {CLI_ROOT} from './paths.mjs';
+import {linkThisCliAsProjectCli} from '../../test-utils/release-fixtures.mjs';
 
 let tmpDir;
 
@@ -39,6 +41,13 @@ describe('findCoreDir', () => {
   });
 
   it('returns null when nothing found', () => {
+    expect(findProjectCoreDir(tmpDir)).toBeNull();
+  });
+
+  it('falls back to the carried Core outside a project, and only there', () => {
+    // This copy's carried Core is the workspace Core beside it.
+    expect(findCoreDir(tmpDir)).toBe(path.resolve(CLI_ROOT, '..', 'core'));
+    linkThisCliAsProjectCli(tmpDir);
     expect(findCoreDir(tmpDir)).toBeNull();
   });
 });

package/foundation/integrations/computer-integrations.d.mts

@@ -0,0 +1,78 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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: string, options?: {
+    cacheDir?: string;
+}): string | null;
+/**
+ * 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: string, options?: {
+    cacheDir?: string;
+}): string[];
+/**
+ * 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: Record<string, any>, release: string): string | null;
+/**
+ * The computer-level integrations installed beside the CLI at `cliRoot`, in
+ * name order (declaration order when the root declares them). Reads
+ * package.json files only.
+ * @param {{cliRoot: string, release: string, cacheDir?: string}} options
+ * @returns {ComputerIntegrationCandidate[]}
+ */
+export function scanComputerIntegrations({ cliRoot, release, cacheDir }: {
+    cliRoot: string;
+    release: string;
+    cacheDir?: string;
+}): ComputerIntegrationCandidate[];
+/**
+ * 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 function loadComputerIntegrations(candidates: ComputerIntegrationCandidate[], options?: {
+    fresh?: boolean;
+    exclude?: Iterable<string>;
+}): Promise<import("./provider-resolution.mjs").ProviderCandidate[]>;
+export type ComputerIntegrationCandidate = {
+    /**
+     * the package name
+     */
+    name: string;
+    version: string | undefined;
+    description: string | undefined;
+    packageDir: string;
+    /**
+     * the folder whose node_modules holds it
+     */
+    hostDir: string;
+    /**
+     * why its peer ranges exclude the
+     * answering release, or null
+     */
+    incompatible: string | null;
+};

package/foundation/integrations/computer-integrations.mjs

@@ -0,0 +1,316 @@
+// 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). Reads
+ * package.json files only.
+ * @param {{cliRoot: string, release: string, cacheDir?: string}} options
+ * @returns {ComputerIntegrationCandidate[]}
+ */
+export function scanComputerIntegrations({cliRoot, release, cacheDir}) {
+  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});
+  }
+  return found;
+}
+
+/**
+ * Add the integrations installed in one install root.
+ * @param {string} root
+ * @param {{self: string, release: string, found: ComputerIntegrationCandidate[], seen: Set<string>}} into
+ */
+function scanRoot(root, {self, release, found, seen}) {
+  const declared = readPackage(root)
+    ? readDeclaredDependencies(root).map(d => d.name)
+    : installedNames(root);
+  for (const name of declared) {
+    if (NOT_INTEGRATIONS.has(name)) continue;
+    const resolved = 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;
+}