@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/foundation/fs/read-record.test.mjs

@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for read-record: which paths an operation read, and whether
+ * any changed since, including a change made while the operation ran.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {recordReads, unchangedSince} from './read-record.mjs';
+
+function scratch() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-read-record-'));
+  const file = path.join(dir, 'doc.txt');
+  fs.writeFileSync(file, 'one');
+  return {dir, file};
+}
+
+describe('recordReads', () => {
+  it('records a read file and a listed folder, and sees them unchanged', () => {
+    const {dir, file} = scratch();
+    /** @type {Map<string, string>} */
+    const seen = new Map();
+    recordReads(seen, () => {
+      fs.readFileSync(file, 'utf8');
+      fs.readdirSync(dir);
+    });
+    expect([...seen.keys()]).toEqual(expect.arrayContaining([file, dir]));
+    expect(unchangedSince(seen)).toBe(true);
+  });
+
+  it('sees an edit made after the operation', () => {
+    const {file} = scratch();
+    /** @type {Map<string, string>} */
+    const seen = new Map();
+    recordReads(seen, () => fs.readFileSync(file, 'utf8'));
+    const later = new Date(Date.now() + 5_000);
+    fs.writeFileSync(file, 'two, longer');
+    fs.utimesSync(file, later, later);
+    expect(unchangedSince(seen)).toBe(false);
+  });
+
+  it('sees an edit made while the operation ran, after the file was read', () => {
+    const {file} = scratch();
+    /** @type {Map<string, string>} */
+    const seen = new Map();
+    recordReads(seen, () => {
+      fs.readFileSync(file, 'utf8');
+      const later = new Date(Date.now() + 5_000);
+      fs.writeFileSync(file, 'edited mid-run');
+      fs.utimesSync(file, later, later);
+    });
+    expect(unchangedSince(seen)).toBe(false);
+  });
+
+  it('sees a file added to a folder it probed', () => {
+    const {dir} = scratch();
+    /** @type {Map<string, string>} */
+    const seen = new Map();
+    recordReads(seen, () => fs.existsSync(path.join(dir, 'missing.txt')));
+    const later = new Date(Date.now() + 5_000);
+    fs.writeFileSync(path.join(dir, 'missing.txt'), 'now here');
+    fs.utimesSync(dir, later, later);
+    expect(unchangedSince(seen)).toBe(false);
+  });
+
+  it('records nothing outside an operation', () => {
+    const {file} = scratch();
+    /** @type {Map<string, string>} */
+    const seen = new Map();
+    recordReads(seen, () => {});
+    fs.readFileSync(file, 'utf8');
+    expect(seen.size).toBe(0);
+  });
+});

package/foundation/integrations/autolink.d.mts

@@ -21,7 +21,8 @@ export function readDeclaredDependencies(projectDir: string): Array<{
  *
  * Walking up matters because hoisting is normal — yarn and npm workspaces lift
  * a workspace member's dependency to the repo root, so the app's own
- * node_modules can be empty of a package it genuinely declares.
+ * node_modules can be empty of a package it genuinely declares. Integrations
+ * named in astryx.config resolve through the same walk.
  *
  * Presence is decided by the package's own package.json, not the directory, so
  * a stale empty directory is not mistaken for an install.

package/foundation/integrations/autolink.mjs

@@ -39,6 +39,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {findNodeModulesPackage} from '../fs/paths.mjs';
 import {findManifestPaths, loadIntegrations} from './integrations.mjs';
 import {resolveProviders} from './provider-resolution.mjs';
 
@@ -123,7 +124,8 @@ export function readDeclaredDependencies(projectDir) {
  *
  * Walking up matters because hoisting is normal — yarn and npm workspaces lift
  * a workspace member's dependency to the repo root, so the app's own
- * node_modules can be empty of a package it genuinely declares.
+ * node_modules can be empty of a package it genuinely declares. Integrations
+ * named in astryx.config resolve through the same walk.
  *
  * Presence is decided by the package's own package.json, not the directory, so
  * a stale empty directory is not mistaken for an install.
@@ -135,18 +137,7 @@ export function readDeclaredDependencies(projectDir) {
  */
 export function resolveInstalledPackageDir(name, fromDir) {
   if (!isBarePackageName(name)) return null;
-  const segments = name.split('/');
-  let dir = path.resolve(fromDir);
-  for (let i = 0; i < 50; i++) {
-    const packageDir = path.join(dir, 'node_modules', ...segments);
-    if (fs.existsSync(path.join(packageDir, 'package.json'))) {
-      return {packageDir, hostDir: dir};
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
+  return findNodeModulesPackage(fromDir, name);
 }
 
 /**

package/foundation/integrations/cli-peer-version.d.mts

@@ -0,0 +1,36 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The running CLI version.
+ * @returns {string}
+ */
+export function cliVersion(): string;
+/**
+ * Why the running CLI is outside an integration's declared
+ * `@astryxdesign/cli` peer range, or null when it is inside it (or when no
+ * peer is declared or the package.json cannot be read).
+ *
+ * A CLI below the range is told to upgrade Core and the CLI together, with
+ * the project's own install command, and then to run the upgrade codemods.
+ * A CLI above it (the range has an upper bound, such as `^0.6.0`) is
+ * told to look for a release of the package that supports it, since
+ * upgrading the CLI cannot help there; the author of the package in the
+ * current folder is told to test with this CLI and widen the range.
+ *
+ * @param {import('./integrations.mjs').LoadedIntegration} integration
+ * @param {string} [version] the running CLI version; defaults to this CLI's
+ *   own package.json version
+ * @param {string} [cwd] where the install command would run; decides the
+ *   package manager it names
+ * @param {{own?: boolean, from?: string}} [options] `own`: the package is
+ *   the one being authored in the current folder, so above the range its
+ *   author is told to test with this CLI and widen the range instead; `from`:
+ *   the version the project's upgrade starts from when it is not the running
+ *   CLI's, such as the Core of a project with no CLI of its own
+ * @returns {string | null}
+ */
+export function cliPeerVersionProblem(integration: import("./integrations.mjs").LoadedIntegration, version?: string, cwd?: string, { own, from }?: {
+    own?: boolean;
+    from?: string;
+}): string | null;

package/foundation/integrations/cli-peer-version.mjs

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Warn when the running CLI is outside an integration's declared peer
+ * range.
+ *
+ * An integration published against a newer CLI declares
+ * `"@astryxdesign/cli": ">=X.Y.Z"` in peerDependencies. When the running CLI
+ * does not satisfy that range, the integration's newer contributions may not
+ * load correctly. This module detects that mismatch and says why, naming the
+ * package, the range, the running version, and what to do.
+ *
+ * @input A loaded integration (with __packageDir) and the running CLI version.
+ * @output The message, or null when the CLI is inside the range.
+ * @position foundation/integrations — read by api/integration/validate-integration,
+ *   which reports it as a `cli_peer_version` note in `doctor integration
+ *   validate` and `integration check`, never a warning, so it fails nothing
+ *   (architecture:cli-surface INV35).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {satisfiesRange, semverCompare} from '../env/semver.mjs';
+import {
+  detectPackageManager,
+  getCliInvocation,
+} from '../env/package-manager.mjs';
+import {CLI_PACKAGE, lowestAdmitted} from './cli-requirement.mjs';
+
+/** The command that adds a package, by package manager. */
+const ADD_VERB = /** @type {Record<string, string>} */ ({
+  pnpm: 'pnpm add',
+  yarn: 'yarn add',
+  bun: 'bun add',
+  npm: 'npm install',
+});
+
+/**
+ * Read the CLI's own version from its package.json.
+ * @returns {string}
+ */
+function readCliVersion() {
+  const cliPkg = path.resolve(import.meta.dirname, '..', '..', 'package.json');
+  return JSON.parse(fs.readFileSync(cliPkg, 'utf8')).version;
+}
+
+/** Cached CLI version, read once. @type {string | undefined} */
+let _cliVersion;
+
+/**
+ * The running CLI version.
+ * @returns {string}
+ */
+export function cliVersion() {
+  if (_cliVersion == null) _cliVersion = readCliVersion();
+  return _cliVersion;
+}
+
+/**
+ * Why the running CLI is outside an integration's declared
+ * `@astryxdesign/cli` peer range, or null when it is inside it (or when no
+ * peer is declared or the package.json cannot be read).
+ *
+ * A CLI below the range is told to upgrade Core and the CLI together, with
+ * the project's own install command, and then to run the upgrade codemods.
+ * A CLI above it (the range has an upper bound, such as `^0.6.0`) is
+ * told to look for a release of the package that supports it, since
+ * upgrading the CLI cannot help there; the author of the package in the
+ * current folder is told to test with this CLI and widen the range.
+ *
+ * @param {import('./integrations.mjs').LoadedIntegration} integration
+ * @param {string} [version] the running CLI version; defaults to this CLI's
+ *   own package.json version
+ * @param {string} [cwd] where the install command would run; decides the
+ *   package manager it names
+ * @param {{own?: boolean, from?: string}} [options] `own`: the package is
+ *   the one being authored in the current folder, so above the range its
+ *   author is told to test with this CLI and widen the range instead; `from`:
+ *   the version the project's upgrade starts from when it is not the running
+ *   CLI's, such as the Core of a project with no CLI of its own
+ * @returns {string | null}
+ */
+export function cliPeerVersionProblem(
+  integration,
+  version,
+  cwd = process.cwd(),
+  {own = false, from} = {},
+) {
+  const ver = version ?? cliVersion();
+  if (!integration.__packageDir) return null;
+
+  let pkg;
+  try {
+    pkg = JSON.parse(
+      fs.readFileSync(path.join(integration.__packageDir, 'package.json'), 'utf8'),
+    );
+  } catch {
+    return null;
+  }
+
+  const range = pkg?.peerDependencies?.[CLI_PACKAGE];
+  if (typeof range !== 'string') return null;
+  if (satisfiesRange(ver, range)) return null;
+
+  const name = integration.name ?? pkg.name ?? '(integration)';
+  const lowest = lowestAdmitted(range);
+  if (lowest != null && semverCompare(ver, lowest) < 0) {
+    // Core and the CLI move together, then the upgrade codemods run, as the
+    // project-upgrade notice does: moving only the CLI would leave it ahead of
+    // Core. A package's own folder holds them as dev dependencies.
+    const verb = ADD_VERB[detectPackageManager(cwd)] ?? ADD_VERB.npm;
+    const install = `${verb}${own ? ' -D' : ''} @astryxdesign/core@latest ${CLI_PACKAGE}@latest`;
+    const upgrade = `${getCliInvocation(cwd, {installed: true})} upgrade --from ${from ?? ver} --apply`;
+    return (
+      `${name} needs ${CLI_PACKAGE} ${range}, but this CLI is ${ver}, so ` +
+      `some of what it ships may not load. Upgrade Core and the CLI ` +
+      `together: \`${install}\`, then \`${upgrade}\`.`
+    );
+  }
+  if (own) {
+    return (
+      `${name} declares ${CLI_PACKAGE} ${range}, but this CLI is ${ver}, ` +
+      `outside that range. Test the package with this CLI, and if it works, ` +
+      `widen the ${CLI_PACKAGE} range in its peerDependencies.`
+    );
+  }
+  return (
+    `${name} supports ${CLI_PACKAGE} ${range}, but this CLI is ${ver}, ` +
+    `outside that range, so some of what it ships may not work as its ` +
+    `author tested. Look for a release of ${name} that supports ${ver}.`
+  );
+}

package/foundation/integrations/cli-peer-version.test.mjs

@@ -0,0 +1,354 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the CLI peer version warning.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {cliPeerVersionProblem, cliVersion} from './cli-peer-version.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+/** @type {string} */
+let tmpDir;
+
+beforeAll(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-cli-peer-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * @param {string} name
+ * @param {Record<string, unknown>} pkgJson
+ */
+function makeIntegration(name, pkgJson) {
+  const dir = path.join(tmpDir, name.replace(/[/@]/g, '_'));
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkgJson));
+  return {name, version: String(pkgJson.version ?? '1.0.0'), __packageDir: dir};
+}
+
+describe('cliPeerVersionProblem', () => {
+  it('returns null when no @astryxdesign/cli peer is declared', () => {
+    const integration = makeIntegration('@test/no-peer', {
+      name: '@test/no-peer',
+      version: '1.0.0',
+    });
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).toBeNull();
+  });
+
+  it('returns null when the CLI satisfies the peer range', () => {
+    const integration = makeIntegration('@test/satisfied', {
+      name: '@test/satisfied',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.6.0'},
+    });
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).toBeNull();
+  });
+
+  it('warns when the CLI is below the peer range', () => {
+    const integration = makeIntegration('@test/needs-newer', {
+      name: '@test/needs-newer',
+      version: '2.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.8.0'},
+    });
+    const project = path.join(tmpDir, 'npm-project');
+    fs.mkdirSync(project, {recursive: true});
+    fs.writeFileSync(path.join(project, 'package-lock.json'), '{}\n');
+    expect(cliPeerVersionProblem(integration, '0.6.5', project)).toBe(
+      '@test/needs-newer needs @astryxdesign/cli >=0.8.0, but this CLI is 0.6.5, so some of what it ships may not load. Upgrade Core and the CLI together: `npm install @astryxdesign/core@latest @astryxdesign/cli@latest`, then `npx astryx upgrade --from 0.6.5 --apply`.',
+    );
+  });
+
+  it("names the project's own package manager in the upgrade command", () => {
+    const project = path.join(tmpDir, 'pnpm-project');
+    fs.mkdirSync(project, {recursive: true});
+    fs.writeFileSync(path.join(project, 'pnpm-lock.yaml'), "lockfileVersion: '9.0'\n");
+    const integration = makeIntegration('@test/pnpm', {
+      name: '@test/pnpm',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.8.0'},
+    });
+    expect(cliPeerVersionProblem(integration, '0.6.5', project)).toContain(
+      '`pnpm add @astryxdesign/core@latest @astryxdesign/cli@latest`, then `pnpm exec astryx upgrade --from 0.6.5 --apply`',
+    );
+  });
+
+  it('starts the upgrade from the version it is given, such as a Core-only project\'s Core', () => {
+    const project = path.join(tmpDir, 'from-npm-project');
+    fs.mkdirSync(project, {recursive: true});
+    fs.writeFileSync(path.join(project, 'package-lock.json'), '{}\n');
+    const integration = makeIntegration('@test/from', {
+      name: '@test/from',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.8.0'},
+    });
+    expect(
+      cliPeerVersionProblem(integration, '0.7.3', project, {from: '0.6.0'}),
+    ).toContain('upgrade --from 0.6.0 --apply');
+  });
+
+  it('installs them as dev dependencies in the package being authored', () => {
+    const project = path.join(tmpDir, 'own-npm-project');
+    fs.mkdirSync(project, {recursive: true});
+    fs.writeFileSync(path.join(project, 'package-lock.json'), '{}\n');
+    const integration = makeIntegration('@test/own-below', {
+      name: '@test/own-below',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.8.0'},
+    });
+    expect(
+      cliPeerVersionProblem(integration, '0.6.5', project, {own: true}),
+    ).toContain(
+      '`npm install -D @astryxdesign/core@latest @astryxdesign/cli@latest`, then `npx astryx upgrade --from 0.6.5 --apply`',
+    );
+  });
+
+  it('does not ask for an upgrade when the CLI is newer than the range', () => {
+    const integration = makeIntegration('@test/older', {
+      name: '@test/older',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.6.0'},
+    });
+    expect(cliPeerVersionProblem(integration, '0.7.3', tmpDir)).toBe(
+      '@test/older supports @astryxdesign/cli ^0.6.0, but this CLI is 0.7.3, outside that range, so some of what it ships may not work as its author tested. Look for a release of @test/older that supports 0.7.3.',
+    );
+  });
+
+  it('handles a caret range that excludes the running CLI', () => {
+    const integration = makeIntegration('@test/caret', {
+      name: '@test/caret',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^1.0.0'},
+    });
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).toContain(
+      '^1.0.0',
+    );
+  });
+
+  it('returns null for a caret range the CLI satisfies', () => {
+    const integration = makeIntegration('@test/caret-ok', {
+      name: '@test/caret-ok',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.6.0'},
+    });
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).toBeNull();
+  });
+
+  it('tells the author to test and widen the range when the package is their own', () => {
+    const integration = makeIntegration('@test/own', {
+      name: '@test/own',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.6.0'},
+    });
+    expect(cliPeerVersionProblem(integration, '0.7.3', tmpDir, {own: true})).toBe(
+      '@test/own declares @astryxdesign/cli ^0.6.0, but this CLI is 0.7.3, outside that range. Test the package with this CLI, and if it works, widen the @astryxdesign/cli range in its peerDependencies.',
+    );
+  });
+
+  it('warns for an optional peer the CLI does not satisfy', () => {
+    // Optional peers are still peers: the integration needs a newer CLI to
+    // work fully. The warning is about the CLI version, not about whether
+    // the peer is required for install.
+    const integration = makeIntegration('@test/optional', {
+      name: '@test/optional',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.9.0'},
+      peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
+    });
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).not.toBeNull();
+  });
+
+  it('handles a prerelease CLI version gracefully', () => {
+    const integration = makeIntegration('@test/prerelease', {
+      name: '@test/prerelease',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '>=0.7.0'},
+    });
+    // A canary like 0.7.0-canary.abc123 should satisfy >=0.7.0
+    expect(cliPeerVersionProblem(integration, '0.7.0-canary.abc123', tmpDir)).toBeNull();
+    // A canary below the floor should warn
+    expect(
+      cliPeerVersionProblem(integration, '0.6.5-canary.xyz', tmpDir),
+    ).not.toBeNull();
+  });
+
+  it('returns null when __packageDir is missing', () => {
+    const integration = {name: '@test/no-dir', version: '1.0.0'};
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).toBeNull();
+  });
+
+  it('returns null when package.json cannot be read', () => {
+    const integration = {
+      name: '@test/bad-dir',
+      version: '1.0.0',
+      __packageDir: path.join(tmpDir, 'nonexistent'),
+    };
+    expect(cliPeerVersionProblem(integration, '0.6.5', tmpDir)).toBeNull();
+  });
+});
+
+describe('cliVersion', () => {
+  it('returns a valid semver string', () => {
+    const ver = cliVersion();
+    expect(ver).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});
+
+describe('as a note that fails nothing', () => {
+  /**
+   * An integration package at `dir` whose CLI peer range is `range`.
+   * @param {string} dir
+   * @param {string} range
+   */
+  function writeIntegration(dir, range) {
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        peerDependencies: {'@astryxdesign/cli': range},
+      }),
+    );
+    fs.writeFileSync(path.join(dir, 'astryx.integration.mjs'), 'export default {};\n');
+  }
+
+  /**
+   * A project with a lockfile that installs @acme/widgets.
+   * @param {string} range
+   */
+  function project(range) {
+    const root = fs.mkdtempSync(path.join(tmpDir, 'project-'));
+    fs.writeFileSync(
+      path.join(root, 'package.json'),
+      JSON.stringify({
+        name: 'app',
+        version: '1.0.0',
+        dependencies: {'@acme/widgets': '^1.0.0'},
+      }),
+    );
+    fs.writeFileSync(path.join(root, 'package-lock.json'), '{}\n');
+    writeIntegration(path.join(root, 'node_modules', '@acme', 'widgets'), range);
+    return root;
+  }
+
+  /** @param {string} [dev] */
+  const below = (dev = '') =>
+    `@acme/widgets needs @astryxdesign/cli >=99.0.0, but this CLI is ${cliVersion()}, so some of what it ships may not load. Upgrade Core and the CLI together: \`npm install${dev} @astryxdesign/core@latest @astryxdesign/cli@latest\`, then \`npx astryx upgrade --from ${cliVersion()} --apply\`.`;
+
+  it('doctor integration validate lists it in data.notes, never in data.issues, and exits 0', async () => {
+    const cwd = project('>=99.0.0');
+    const {status, stdout} = await runCli(
+      ['doctor', 'integration', 'validate', '@acme/widgets', '--json'],
+      {cwd},
+    );
+    const {data} = JSON.parse(stdout);
+    expect(status).toBe(0);
+    expect(data.notes).toContainEqual({code: 'cli_peer_version', message: below()});
+    expect(data.issues.map((/** @type {{code: string}} */ i) => i.code)).not.toContain(
+      'cli_peer_version',
+    );
+  });
+
+  it('integration check --strict carries the note and still exits 0', async () => {
+    const pkg = fs.mkdtempSync(path.join(tmpDir, 'package-'));
+    writeIntegration(pkg, '>=99.0.0');
+    fs.writeFileSync(path.join(pkg, 'package-lock.json'), '{}\n');
+    const {status, stdout} = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      {cwd: pkg},
+    );
+    const envelope = JSON.parse(stdout);
+    const validate = envelope.data.checks[0].response.data;
+    expect(validate.notes).toContainEqual({
+      code: 'cli_peer_version',
+      message: below(' -D'),
+    });
+    expect(validate.issues.map((/** @type {{code: string}} */ i) => i.code)).not.toContain(
+      'cli_peer_version',
+    );
+    expect(envelope.data.failed).toBe(false);
+    expect(status).toBe(0);
+  });
+
+  it('starts the upgrade from the Core of a project with no CLI of its own', async () => {
+    const cwd = project('>=99.0.0');
+    const pkgJson = path.join(cwd, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, 'utf8'));
+    pkg.dependencies['@astryxdesign/core'] = '0.6.0';
+    fs.writeFileSync(pkgJson, JSON.stringify(pkg));
+    const core = path.join(cwd, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(core, {recursive: true});
+    fs.writeFileSync(
+      path.join(core, 'package.json'),
+      JSON.stringify({name: '@astryxdesign/core', version: '0.6.0'}),
+    );
+    const {status, stdout} = await runCli(
+      ['doctor', 'integration', 'validate', '@acme/widgets', '--json'],
+      {cwd},
+    );
+    expect(status).toBe(0);
+    const note = JSON.parse(stdout).data.notes.find(
+      (/** @type {{code: string}} */ n) => n.code === 'cli_peer_version',
+    );
+    expect(note.message).toContain('upgrade --from 0.6.0 --apply');
+    expect(note.message).not.toContain(`--from ${cliVersion()}`);
+  });
+
+  it('asks for a release of an installed package that supports a CLI above its range', async () => {
+    const cwd = project('^0.6.0');
+    const {stdout} = await runCli(
+      ['doctor', 'integration', 'validate', '@acme/widgets', '--json'],
+      {cwd},
+    );
+    expect(JSON.parse(stdout).data.notes).toContainEqual({
+      code: 'cli_peer_version',
+      message: `@acme/widgets supports @astryxdesign/cli ^0.6.0, but this CLI is ${cliVersion()}, outside that range, so some of what it ships may not work as its author tested. Look for a release of @acme/widgets that supports ${cliVersion()}.`,
+    });
+  });
+
+  it('tells the author of the package in the current folder to test and widen a range below this CLI', async () => {
+    const pkg = fs.mkdtempSync(path.join(tmpDir, 'package-'));
+    writeIntegration(pkg, '^0.6.0');
+    const {status, stdout} = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      {cwd: pkg},
+    );
+    const envelope = JSON.parse(stdout);
+    expect(envelope.data.checks[0].response.data.notes).toContainEqual({
+      code: 'cli_peer_version',
+      message: `@acme/widgets declares @astryxdesign/cli ^0.6.0, but this CLI is ${cliVersion()}, outside that range. Test the package with this CLI, and if it works, widen the @astryxdesign/cli range in its peerDependencies.`,
+    });
+    expect(envelope.data.failed).toBe(false);
+    expect(status).toBe(0);
+  });
+
+  it('leaves integration verify as it was: no warning, no issue', async () => {
+    const pkg = fs.mkdtempSync(path.join(tmpDir, 'package-'));
+    writeIntegration(pkg, '>=99.0.0');
+    const {stdout} = await runCli(['--json', 'integration', 'verify'], {
+      cwd: pkg,
+    });
+    expect(stdout).not.toContain('cli_peer_version');
+    const text = await runCli(['integration', 'verify'], {cwd: pkg});
+    expect(text.stdout + text.stderr).not.toContain('needs @astryxdesign/cli');
+  }, 120_000);
+
+  it('says nothing when the CLI is in the range', async () => {
+    const cwd = project(`>=${cliVersion()}`);
+    const {stdout} = await runCli(
+      ['doctor', 'integration', 'validate', '@acme/widgets', '--json'],
+      {cwd},
+    );
+    const {data} = JSON.parse(stdout);
+    expect(
+      (data.notes ?? []).map((/** @type {{code: string}} */ n) => n.code),
+    ).not.toContain('cli_peer_version');
+  });
+});

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

@@ -34,15 +34,18 @@ export function computerInstallRoots(cliRoot: string, options?: {
 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
+ * 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}} options
+ * @param {{cliRoot: string, release: string, cacheDir?: string, approved?: readonly string[]}} options
  * @returns {ComputerIntegrationCandidate[]}
  */
-export function scanComputerIntegrations({ cliRoot, release, cacheDir }: {
+export function scanComputerIntegrations({ cliRoot, release, cacheDir, approved, }: {
     cliRoot: string;
     release: string;
     cacheDir?: string;
+    approved?: readonly string[];
 }): ComputerIntegrationCandidate[];
 /**
  * Load the compatible computer-level integrations as provider candidates,