@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/theme/themeTargets.doc.mjs

@@ -62,6 +62,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be resolved from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'outside a project, or in a project with nothing installed, the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
     {code: 'ERR_UNKNOWN_COMPONENT', when: 'a filter matches no target'},
   ],
   examples: [

package/api/theme/use/use.test.mjs

@@ -92,7 +92,7 @@ describe('themeUse', () => {
   it('names theme add when the slug is not added', async () => {
     await expect(themeUse('missing', {cwd: tmpDir})).rejects.toMatchObject({
       code: 'ERR_UNKNOWN_THEME',
-      message: expect.stringContaining('astryx theme add missing'),
+      message: expect.stringContaining(' theme add missing`'),
     });
   });
 });

package/api/upgrade/_adapter.d.mts

@@ -31,6 +31,43 @@ export function detectInstalledTargetVersion(cwd: string): {
     version: string;
     packageName: string;
 } | null;
+/**
+ * Whether the installed Core is newer than this CLI, so part of the requested
+ * range has no codemods here.
+ *
+ * Core codemods ship inside the CLI. A CLI older than the installed
+ * `@astryxdesign/core` has none for the releases after its own version, so it
+ * can find no codemods, or stop partway, while the code still needs those
+ * releases' migrations. The returned command repeats this upgrade with the CLI
+ * release that matches the installed Core.
+ *
+ * Where an upgrade runs decides what it finds: the installed Core is read
+ * from that folder, and `--path` must stay inside it. So the command first
+ * changes to `cwd`, the folder this run used, then names `sourcePath`, the
+ * directory this run scanned, as an absolute `--path`. Both are named by their
+ * physical paths, with every symbolic link resolved: a shell's `cd` follows a
+ * link, but the CLI it starts reads its folder with every link resolved and
+ * checks `--path` against that. Pasted from any folder, the command finds the
+ * same Core and scans the same directory, even after a package runner moved
+ * this run (Yarn 1 runs `yarn astryx` at the project root). It is written for
+ * a POSIX shell, or for PowerShell on Windows (cmd.exe is not a target), with
+ * every argument quoted for that shell.
+ *
+ * Returns null when the CLI covers the whole range (`to` is not newer than
+ * both the CLI and `from`), when the CLI's own version cannot be read, or when
+ * the target is legacy `@xds/core`, which no CLI release shares a version with.
+ *
+ * @param {{from: string, to: string, packageName: string, options: UpgradeOptions, cwd: string, sourcePath: string}} input
+ * @returns {import('./upgrade.type.mjs').CliBehindCore | null}
+ */
+export function detectCliBehindCore({ from, to, packageName, options, cwd, sourcePath, }: {
+    from: string;
+    to: string;
+    packageName: string;
+    options: UpgradeOptions;
+    cwd: string;
+    sourcePath: string;
+}): import("./upgrade.type.mjs").CliBehindCore | null;
 /**
  * @param {(string | null | undefined | false)[] | undefined} files
  * @returns {string[]}
@@ -104,9 +141,9 @@ export function ensureCodemodDeps({ installDeps }?: {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean, coversTarget?: boolean}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent, coversTarget, }: {
     apply: boolean;
     path: string;
     codemod?: string;
@@ -117,6 +154,7 @@ export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply
         classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
     };
     silent?: boolean;
+    coversTarget?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;

package/api/upgrade/_adapter.mjs

@@ -34,7 +34,15 @@ import {
   inspectAgentDocs,
   renderAgentDocsBlock,
 } from '../../foundation/agent-docs/agent-docs.mjs';
-import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
+import {
+  CLI_PACKAGE,
+  commandInFolder,
+  formatCliCommand,
+  getDlxPrefix,
+  quoteCommandArgument,
+} from '../../foundation/env/package-manager.mjs';
+import {isValidSemver, semverGt} from '../../foundation/env/semver.mjs';
+import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import {Project, providerLedgerOf} from '../../foundation/config/project.mjs';
 import {loadIntegrations} from '../../foundation/integrations/integrations.mjs';
 import {resolveProviders} from '../../foundation/integrations/provider-resolution.mjs';
@@ -96,6 +104,99 @@ export function detectInstalledTargetVersion(cwd) {
   return null;
 }
 
+/**
+ * The running CLI's own version, read from its package.json.
+ * @returns {string | null} null when it cannot be read or is not semver
+ */
+function readRunningCliVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf-8'),
+    );
+    return isValidSemver(pkg.version) ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether the installed Core is newer than this CLI, so part of the requested
+ * range has no codemods here.
+ *
+ * Core codemods ship inside the CLI. A CLI older than the installed
+ * `@astryxdesign/core` has none for the releases after its own version, so it
+ * can find no codemods, or stop partway, while the code still needs those
+ * releases' migrations. The returned command repeats this upgrade with the CLI
+ * release that matches the installed Core.
+ *
+ * Where an upgrade runs decides what it finds: the installed Core is read
+ * from that folder, and `--path` must stay inside it. So the command first
+ * changes to `cwd`, the folder this run used, then names `sourcePath`, the
+ * directory this run scanned, as an absolute `--path`. Both are named by their
+ * physical paths, with every symbolic link resolved: a shell's `cd` follows a
+ * link, but the CLI it starts reads its folder with every link resolved and
+ * checks `--path` against that. Pasted from any folder, the command finds the
+ * same Core and scans the same directory, even after a package runner moved
+ * this run (Yarn 1 runs `yarn astryx` at the project root). It is written for
+ * a POSIX shell, or for PowerShell on Windows (cmd.exe is not a target), with
+ * every argument quoted for that shell.
+ *
+ * Returns null when the CLI covers the whole range (`to` is not newer than
+ * both the CLI and `from`), when the CLI's own version cannot be read, or when
+ * the target is legacy `@xds/core`, which no CLI release shares a version with.
+ *
+ * @param {{from: string, to: string, packageName: string, options: UpgradeOptions, cwd: string, sourcePath: string}} input
+ * @returns {import('./upgrade.type.mjs').CliBehindCore | null}
+ */
+export function detectCliBehindCore({
+  from,
+  to,
+  packageName,
+  options,
+  cwd,
+  sourcePath,
+}) {
+  if (packageName !== '@astryxdesign/core') return null;
+  const cliVersion = readRunningCliVersion();
+  if (!cliVersion || !semverGt(to, cliVersion) || !semverGt(to, from)) {
+    return null;
+  }
+  const runFolder = path.resolve(cwd);
+  const folder = physicalFolder(runFolder);
+  const scanned = path.join(folder, path.relative(runFolder, sourcePath));
+  const args = ['upgrade', '--from', from, '--path', scanned];
+  if (options.codemod) args.push('--codemod', options.codemod);
+  for (const name of options.skipCodemod ?? []) {
+    args.push('--skip-codemod', name);
+  }
+  for (const spec of options.integration ?? []) {
+    args.push('--integration', spec);
+  }
+  if (options.force) args.push('--force');
+  if (options.installDeps) args.push('--install-deps');
+  if (options.apply) args.push('--apply');
+  const upgrade = [
+    getDlxPrefix(cwd),
+    ...[`${CLI_PACKAGE}@${to}`, ...args].map(arg => quoteCommandArgument(arg)),
+  ].join(' ');
+  return {cliVersion, command: commandInFolder(folder, upgrade)};
+}
+
+/**
+ * A folder as the operating system reports it to a process that runs there,
+ * with every symbolic link on the way resolved. Falls back to the path as
+ * given when it cannot be resolved.
+ * @param {string} dir an absolute folder
+ * @returns {string}
+ */
+function physicalFolder(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
 /**
  * @param {(string | null | undefined | false)[] | undefined} files
  * @returns {string[]}
@@ -332,11 +433,20 @@ export async function ensureCodemodDeps({installDeps} = {}) {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean, coversTarget?: boolean}} options
  */
 export async function runCoreCodemods(
   versionManifests,
-  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    silent,
+    coversTarget,
+  },
 ) {
   return runCodemods(versionManifests, {
     apply,
@@ -346,6 +456,7 @@ export async function runCoreCodemods(
     silent: silent ?? logger.silent,
     root,
     protection,
+    coversTarget,
   });
 }
 
@@ -367,7 +478,7 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   // The CLI debug preflight may already have imported this config before core
   // CONFIG codemods run. Upgrade needs the bytes now on disk, not that module
   // cache entry; ordinary Project discovery remains cached by default.
-  const project = await Project.load(cwd, {fresh: true});
+  const project = await Project.load(cwd, {fresh: true, core: 'project'});
   const postCodemodHooks = project.config.hooks?.postCodemod ?? [];
   const configuredSpecs = new Set(project.integrations ?? []);
   // Configured packages come from Project, which has already resolved provider
@@ -411,7 +522,9 @@ export async function loadProjectContext(cwd, extraIntegrationSpecs = []) {
   const extras =
     extraSpecs.length === 0
       ? []
-      : await loadIntegrations(extraSpecs, {resolveProviders: false});
+      : // Resolved from the project, as --integration names a package it
+        // installed, not from whichever folder the process started in.
+        await loadIntegrations(extraSpecs, {cwd, resolveProviders: false});
   const {integrations, ledger} = resolveProviders(
     [
       ...candidates,

package/api/upgrade/run/cli-behind-core.test.mjs

@@ -0,0 +1,438 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Core codemods ship inside the CLI, so a CLI older than the installed
+ * Core has none for the releases after its own version. Every result past the
+ * up-to-date exit says so in `cliBehindCore`, with the same upgrade pinned to
+ * the CLI release that matches the Core; a CLI that covers the range returns
+ * what it always did. The pinned command changes to the folder the run used
+ * and names the directory it scanned as an absolute path, both with symbolic
+ * links resolved, so a POSIX shell runs it there, with every argument
+ * unchanged, wherever it is pasted, even when upgrade() reached the project
+ * through a link.
+ */
+
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {execFileSync, spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {upgrade} from '../upgrade.mjs';
+import {logCliBehindCore} from '../status/status.mjs';
+import {logger} from '../../logger.mjs';
+import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
+import {
+  commandInFolder,
+  getDlxPrefix,
+  quoteCommandArgument,
+} from '../../../foundation/env/package-manager.mjs';
+
+const SLOW = 30_000;
+
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'),
+).version;
+const [MAJOR, MINOR] = CLI_VERSION.split('.').map(Number);
+/** A Core release after this CLI: it has no codemods for it. */
+const NEWER_CORE = `${MAJOR}.${MINOR + 1}.0`;
+
+/** A source file a 0.7.0 codemod rewrites (`emptySearchResultsText`). */
+const TYPEAHEAD_SOURCE =
+  "import {Typeahead} from '@astryxdesign/core';\n" +
+  'export const x = <Typeahead emptySearchResultsText="None" />;\n';
+
+let dir;
+
+/** @param {string} version @param {string} [packageName] */
+function installCore(version, packageName = '@astryxdesign/core') {
+  const core = path.join(dir, 'node_modules', ...packageName.split('/'));
+  fs.mkdirSync(core, {recursive: true});
+  fs.writeFileSync(
+    path.join(core, 'package.json'),
+    JSON.stringify({name: packageName, version}),
+  );
+}
+
+/** @param {string} rel @param {string} body */
+function write(rel, body) {
+  const file = path.join(dir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+}
+
+/**
+ * A path in the project as a process running there sees it: every symbolic
+ * link resolved.
+ * @param {string} rel
+ */
+function inProject(rel) {
+  return path.join(fs.realpathSync(dir), rel);
+}
+
+/**
+ * The pinned command for this project, as the CLI prints it.
+ * @param {...string} args the arguments after `upgrade`
+ */
+function pinned(...args) {
+  return commandInFolder(
+    fs.realpathSync(dir),
+    [
+      getDlxPrefix(dir),
+      `@astryxdesign/cli@${NEWER_CORE}`,
+      'upgrade',
+      ...args.map(arg => quoteCommandArgument(arg)),
+    ].join(' '),
+  );
+}
+
+/**
+ * Stand-ins for the package runners: each prints the folder it runs in and the
+ * arguments the shell passed.
+ */
+const RUNNERS = ['npx', 'pnpm', 'yarn', 'bunx']
+  .map(
+    name =>
+      `${name}() { "$0" -e 'process.stdout.write(JSON.stringify({cwd: process.cwd(), argv: process.argv.slice(1)}))' -- "$@"; }`,
+  )
+  .join('; ');
+
+/**
+ * What a POSIX shell runs for `command` pasted in `cwd`: the folder the
+ * package runner ran in, and its arguments from the pinned CLI package on.
+ * @param {string} command
+ * @param {string} cwd the folder the command is pasted in
+ * @returns {{cwd: string, args: string[]}}
+ */
+function runInShell(command, cwd) {
+  const ran = JSON.parse(
+    execFileSync(
+      '/bin/sh',
+      ['-c', `${RUNNERS}; ${command}`, process.execPath],
+      {
+        cwd,
+        encoding: 'utf8',
+      },
+    ),
+  );
+  return {
+    cwd: ran.cwd,
+    args: ran.argv.slice(ran.argv.indexOf(`@astryxdesign/cli@${NEWER_CORE}`)),
+  };
+}
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-cli-behind-'));
+  write('package.json', JSON.stringify({name: 'consumer', version: '1.0.0'}));
+  write('src/index.tsx', TYPEAHEAD_SOURCE);
+});
+
+afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+describe('a CLI older than the installed Core', {timeout: SLOW}, () => {
+  // The defect: the range past this CLI has no codemods here, so the run
+  // reported `no_codemods` (and "already up to date") and exited 0, while the
+  // project still needed the newer releases' migrations.
+  it('marks a range this CLI has no codemods for, and names the CLI that does', async () => {
+    installCore(NEWER_CORE);
+
+    const res = await upgrade({from: CLI_VERSION, apply: true}, {cwd: dir});
+
+    expect(res.type).toBe('upgrade.status');
+    expect(res.data.status).toBe('no_codemods');
+    expect(res.data.cliBehindCore).toEqual({
+      cliVersion: CLI_VERSION,
+      command: pinned(
+        '--from',
+        CLI_VERSION,
+        '--path',
+        inProject('src'),
+        '--apply',
+      ),
+    });
+  });
+
+  it('runs the codemods it has for a range it covers only in part, and marks the rest', async () => {
+    installCore(NEWER_CORE);
+
+    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: dir});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.codemods).toBeGreaterThan(0);
+    expect(fs.readFileSync(path.join(dir, 'src/index.tsx'), 'utf8')).toContain(
+      'emptySearchText="None"',
+    );
+    expect(res.data.cliBehindCore).toEqual({
+      cliVersion: CLI_VERSION,
+      command: pinned('--from', '0.6.8', '--path', inProject('src'), '--apply'),
+    });
+  });
+
+  it('repeats the invocation in the pinned command', async () => {
+    installCore(NEWER_CORE);
+    write('my src/index.tsx', TYPEAHEAD_SOURCE);
+    // An installed integration the run names, so --integration is repeated.
+    write(
+      'node_modules/@acme/widgets/package.json',
+      JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
+    );
+    write(
+      'node_modules/@acme/widgets/astryx.integration.mjs',
+      'export default {};\n',
+    );
+
+    const res = await upgrade(
+      {
+        from: CLI_VERSION,
+        path: 'my src',
+        codemod: 'only-this',
+        skipCodemod: ['first', 'second'],
+        integration: ['@acme/widgets'],
+        force: true,
+        installDeps: true,
+      },
+      {cwd: dir},
+    );
+
+    expect(res.data.cliBehindCore?.command).toBe(
+      pinned(
+        '--from',
+        CLI_VERSION,
+        '--path',
+        inProject('my src'),
+        '--codemod',
+        'only-this',
+        '--skip-codemod',
+        'first',
+        '--skip-codemod',
+        'second',
+        '--integration',
+        '@acme/widgets',
+        '--force',
+        '--install-deps',
+      ),
+    );
+  });
+
+  // Where an upgrade runs decides what it finds: the installed Core is read
+  // from that folder, and --path must stay inside it. The command printed
+  // without a folder failed when pasted anywhere else: ERR_PATH_TRAVERSAL from
+  // a subfolder, ERR_VERSION_DETECT from a parent. A package runner can also
+  // move the run: Yarn 1 runs `yarn astryx` at the project root.
+  it('changes to the folder the run used and names the directory it scanned as an absolute path', async () => {
+    installCore(NEWER_CORE);
+    write('app/index.tsx', TYPEAHEAD_SOURCE);
+    const project = fs.realpathSync(dir);
+
+    for (const [given, scanned] of [
+      [undefined, inProject('src')],
+      ['.', project],
+      ['app', inProject('app')],
+      ['./app/', inProject('app')],
+    ]) {
+      const res = await upgrade(
+        {from: CLI_VERSION, ...(given ? {path: given} : {})},
+        {cwd: dir},
+      );
+      const command = /** @type {string} */ (res.data.cliBehindCore?.command);
+
+      expect(command).toBe(pinned('--from', CLI_VERSION, '--path', scanned));
+      if (process.platform !== 'win32') {
+        for (const pastedIn of [
+          path.join(dir, 'app'),
+          path.dirname(dir),
+          path.parse(dir).root,
+        ]) {
+          const ran = runInShell(command, pastedIn);
+          expect(ran.cwd).toBe(project);
+          expect(ran.args[ran.args.indexOf('--path') + 1]).toBe(scanned);
+        }
+      }
+    }
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'quotes the command so a POSIX shell enters the folder and passes every argument unchanged',
+    async () => {
+      fs.rmSync(dir, {recursive: true, force: true});
+      dir = fs.mkdtempSync(
+        path.join(os.tmpdir(), 'upg cost $5 `date` \'one\' "two" !x -'),
+      );
+      write(
+        'package.json',
+        JSON.stringify({name: 'consumer', version: '1.0.0'}),
+      );
+      write('src/index.tsx', TYPEAHEAD_SOURCE);
+      installCore(NEWER_CORE);
+
+      const res = await upgrade(
+        {
+          from: CLI_VERSION,
+          skipCodemod: ["it's", 'a$b c'],
+          apply: true,
+        },
+        {cwd: dir},
+      );
+
+      const ran = runInShell(
+        /** @type {string} */ (res.data.cliBehindCore?.command),
+        path.dirname(dir),
+      );
+
+      expect(ran.cwd).toBe(fs.realpathSync(dir));
+      expect(ran.args).toEqual([
+        `@astryxdesign/cli@${NEWER_CORE}`,
+        'upgrade',
+        '--from',
+        CLI_VERSION,
+        '--path',
+        inProject('src'),
+        '--skip-codemod',
+        "it's",
+        '--skip-codemod',
+        'a$b c',
+        '--apply',
+      ]);
+    },
+  );
+});
+
+/** The CLI's own bin, which the stand-in runners below run. */
+const BIN = path.join(CLI_ROOT, 'clients', 'cli', 'bin', 'astryx.mjs');
+
+/**
+ * Stand-ins for the package runners: each drops its own words and the pinned
+ * package, then runs this CLI with the rest of the command.
+ */
+const RUNS_THIS_CLI = /** @type {Array<[string, number]>} */ ([
+  ['npx', 1],
+  ['bunx', 1],
+  ['pnpm', 2],
+  ['yarn', 2],
+])
+  .map(
+    ([name, words]) =>
+      `${name}() { shift ${words}; "$0" ${quoteCommandArgument(BIN)} "$@"; }`,
+  )
+  .join('; ');
+
+// A shell's `cd` follows a symbolic link, but the CLI it starts reads its
+// folder with every link resolved and checks --path against that. A command
+// that kept the link upgrade() was given exited 1 with ERR_PATH_TRAVERSAL.
+describe.skipIf(process.platform === 'win32')(
+  'a project upgrade() reaches through a symbolic link',
+  {timeout: SLOW},
+  () => {
+    /** @type {string} */
+    let base;
+
+    beforeEach(() => {
+      fs.rmSync(dir, {recursive: true, force: true});
+      base = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-link-'));
+      dir = path.join(base, 'real', 'my app');
+      write(
+        'package.json',
+        JSON.stringify({name: 'consumer', version: '1.0.0'}),
+      );
+      write('src/index.tsx', TYPEAHEAD_SOURCE);
+      installCore(NEWER_CORE);
+    });
+
+    afterEach(() => fs.rmSync(base, {recursive: true, force: true}));
+
+    /**
+     * Run upgrade() from `cwd`, then the command it prints, in /bin/sh, from
+     * `cwd` and from the folder above the project.
+     * @param {string} cwd
+     */
+    async function expectPrintedCommandToRun(cwd) {
+      const res = await upgrade({from: CLI_VERSION}, {cwd});
+      const command = /** @type {string} */ (res.data.cliBehindCore?.command);
+
+      for (const pastedIn of [cwd, base]) {
+        const ran = spawnSync(
+          '/bin/sh',
+          ['-c', `${RUNS_THIS_CLI}; ${command}`, process.execPath],
+          {cwd: pastedIn, encoding: 'utf8'},
+        );
+
+        expect(ran.status, ran.stderr).toBe(0);
+        expect(ran.stdout).toContain(`Installed target: ${NEWER_CORE}`);
+        expect(ran.stdout).toContain(`Scanning ${inProject('src')} `);
+      }
+      expect(command).toBe(
+        pinned('--from', CLI_VERSION, '--path', inProject('src')),
+      );
+    }
+
+    it('prints a command that runs, from a folder reached through a link above the project', async () => {
+      fs.symlinkSync(path.join(base, 'real'), path.join(base, 'link'), 'dir');
+
+      await expectPrintedCommandToRun(path.join(base, 'link', 'my app'));
+    });
+
+    it('prints a command that runs, through a project root that is a link', async () => {
+      fs.symlinkSync(dir, path.join(base, 'app'), 'dir');
+
+      await expectPrintedCommandToRun(path.join(base, 'app'));
+    });
+  },
+);
+
+describe('a CLI that covers the range', {timeout: SLOW}, () => {
+  it('adds nothing when the installed Core is this CLI release', async () => {
+    installCore(CLI_VERSION);
+
+    const res = await upgrade({from: '0.6.8'}, {cwd: dir});
+
+    expect(res.type).toBe('upgrade.run');
+    expect('cliBehindCore' in res.data).toBe(false);
+  });
+
+  it('adds nothing when --from is already the installed Core', async () => {
+    installCore(NEWER_CORE);
+
+    const res = await upgrade({from: NEWER_CORE}, {cwd: dir});
+
+    expect(res.data.status).toBe('up_to_date');
+    expect('cliBehindCore' in res.data).toBe(false);
+
+    const forced = await upgrade({from: NEWER_CORE, force: true}, {cwd: dir});
+
+    expect(forced.data.status).toBe('no_codemods');
+    expect('cliBehindCore' in forced.data).toBe(false);
+  });
+
+  it('adds nothing for legacy @xds/core, which shares no version with a CLI release', async () => {
+    installCore(NEWER_CORE, '@xds/core');
+
+    const res = await upgrade({from: CLI_VERSION}, {cwd: dir});
+
+    expect(res.data.status).toBe('no_codemods');
+    expect('cliBehindCore' in res.data).toBe(false);
+  });
+});
+
+describe('logCliBehindCore: the warning names the shell its command is written for', () => {
+  it.each([
+    ['win32', 'Run it in PowerShell with the CLI that matches your Core:'],
+    ['linux', 'Run it with the CLI that matches your Core:'],
+    ['darwin', 'Run it with the CLI that matches your Core:'],
+  ])('on %s', (platform, ending) => {
+    const warn = vi.spyOn(logger, 'warn').mockImplementation(() => {});
+    try {
+      logCliBehindCore(
+        {cliVersion: '0.7.0', command: 'cd x; npx y'},
+        '0.8.0',
+        platform,
+      );
+      expect(warn.mock.calls.map(([line]) => String(line))).toEqual([
+        expect.stringMatching(
+          new RegExp(`${ending.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}$`, 'u'),
+        ),
+        '  cd x; npx y',
+      ]);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});