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

package/api/upgrade/registry/registry.mjs

@@ -414,8 +414,9 @@ async function fetchLatestReceipt(
 /**
  * @param {string} receiptPath
  * @param {string} root
+ * @param {string} [display] the folder reported paths are relative to
  */
-function loadInstalledReceipt(receiptPath, root) {
+function loadInstalledReceipt(receiptPath, root, display = root) {
   let receipt;
   let receiptText;
   try {
@@ -436,7 +437,7 @@ function loadInstalledReceipt(receiptPath, root) {
     }
   } catch (error) {
     throw new Error(
-      `Invalid receipt ${relativePath(receiptPath, root)}: ${error instanceof Error ? error.message : String(error)}`,
+      `Invalid receipt ${relativePath(receiptPath, display)}: ${error instanceof Error ? error.message : String(error)}`,
       {cause: error},
     );
   }
@@ -445,7 +446,7 @@ function loadInstalledReceipt(receiptPath, root) {
     const candidates = receiptFileCandidates(receipt, file).map(candidate => {
       if (registryContentHash(candidate.content) !== candidate.sha256) {
         throw new Error(
-          `Invalid receipt ${relativePath(receiptPath, root)}: stored hash does not match ${file.registryPath} (${candidate.format})`,
+          `Invalid receipt ${relativePath(receiptPath, display)}: stored hash does not match ${file.registryPath} (${candidate.format})`,
         );
       }
       let sourcePath;
@@ -458,7 +459,7 @@ function loadInstalledReceipt(receiptPath, root) {
       } catch (error) {
         if (error instanceof PathSafetyError) {
           throw new Error(
-            `Invalid receipt ${relativePath(receiptPath, root)}: ${error.message}`,
+            `Invalid receipt ${relativePath(receiptPath, display)}: ${error.message}`,
             {cause: error},
           );
         }
@@ -471,7 +472,7 @@ function loadInstalledReceipt(receiptPath, root) {
     );
     if (existing.length > 1) {
       throw new Error(
-        `Invalid receipt ${relativePath(receiptPath, root)}: multiple install variants exist for ${file.registryPath}`,
+        `Invalid receipt ${relativePath(receiptPath, display)}: multiple install variants exist for ${file.registryPath}`,
       );
     }
     return existing[0] ?? candidates[0];
@@ -483,12 +484,14 @@ function loadInstalledReceipt(receiptPath, root) {
 /**
  * @param {string} receiptPath
  * @param {string} root
- * @param {{fetchImpl: typeof fetch, registryOrigin: string, expectedVersion?: string}} options
+ * @param {{fetchImpl: typeof fetch, registryOrigin: string, expectedVersion?: string, display?: string}} options
+ *   `display` is the folder reported paths are relative to, `root` by default
  */
 async function planReceipt(receiptPath, root, options) {
+  const display = options.display ?? root;
   let installed;
   try {
-    installed = loadInstalledReceipt(receiptPath, root);
+    installed = loadInstalledReceipt(receiptPath, root, display);
   } catch (error) {
     return {
       receiptPath,
@@ -584,7 +587,7 @@ async function planReceipt(receiptPath, root, options) {
           oldReceiptText,
         };
       }
-      const displayPath = relativePath(sourcePath, root);
+      const displayPath = relativePath(sourcePath, display);
       try {
         if (!fs.existsSync(sourcePath)) {
           plannedFiles.push({
@@ -636,7 +639,7 @@ async function planReceipt(receiptPath, root, options) {
     const newFile = newReceiptFile
       ? receiptFileForFormat(newReceipt, newReceiptFile, oldFile.format)
       : null;
-    const displayPath = relativePath(oldFile.sourcePath, root);
+    const displayPath = relativePath(oldFile.sourcePath, display);
     if (!newReceiptFile) {
       plannedFiles.push({
         id: oldFile.id,
@@ -856,8 +859,12 @@ function publicAction(action, apply) {
   return action;
 }
 
-/** @param {any} item @param {string} root @param {boolean} apply */
-function publicItem(item, root, apply) {
+/**
+ * @param {any} item
+ * @param {string} display the folder reported paths are relative to
+ * @param {boolean} apply
+ */
+function publicItem(item, display, apply) {
   return {
     item: item.item,
     path: item.itemPath,
@@ -870,7 +877,7 @@ function publicItem(item, root, apply) {
         action: publicAction(file.action, apply),
         ...(file.message ? {message: file.message} : {}),
         ...(file.action === 'conflict' && file.conflictPath
-          ? {conflictFile: relativePath(file.conflictPath, root)}
+          ? {conflictFile: relativePath(file.conflictPath, display)}
           : {}),
       }),
     ),
@@ -968,13 +975,17 @@ function applyPlan(plan) {
 }
 
 /**
+ * Reported paths are relative to the scanned source folder, or, when `origin`
+ * names the folder the command ran in below the project root `cwd`, to that
+ * folder, so they resolve from where the command ran.
  * @param {{apply?: boolean, path?: string}} options
- * @param {{cwd?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
+ * @param {{cwd?: string, origin?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
  */
 export async function reconcileRegistryCompositions(
   options = {},
   {
     cwd = process.cwd(),
+    origin,
     fetchImpl = globalThis.fetch,
     registryOrigin = PUBLIC_SHADCN_REGISTRY_ORIGIN,
     expectedVersion,
@@ -998,6 +1009,7 @@ export async function reconcileRegistryCompositions(
     throw error;
   }
 
+  const display = origin ?? root;
   const apply = options.apply ?? false;
   const receipts = discoverRegistryReceipts(root);
   const summary = emptySummary(apply);
@@ -1019,6 +1031,7 @@ export async function reconcileRegistryCompositions(
         fetchImpl,
         registryOrigin,
         expectedVersion,
+        display,
       }),
   );
 
@@ -1031,7 +1044,7 @@ export async function reconcileRegistryCompositions(
         summary.invalid++;
       }
     }
-    recordItem(summary, publicItem(plan, root, apply), plan.action, apply);
+    recordItem(summary, publicItem(plan, display, apply), plan.action, apply);
     if (!apply) continue;
 
     try {
@@ -1119,13 +1132,17 @@ export function logRegistryCompositionSummary(summary) {
 }
 
 /**
- * Standalone `astryx upgrade --registry` leaf.
+ * Standalone `astryx upgrade --registry` leaf. `ctx.origin` is the folder the
+ * command ran in, when `ctx.cwd` is the project root above it.
  * @param {{apply?: boolean, path?: string}} options
- * @param {{cwd?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
+ * @param {{cwd?: string, origin?: string, fetchImpl?: typeof fetch, registryOrigin?: string, expectedVersion?: string, requireExpectedVersion?: boolean}} [ctx]
  * @returns {Promise<import('../upgrade.type.mjs').UpgradeRegistryResponse>}
  */
 export async function registryUpgrade(options = {}, ctx = {}) {
   const cwd = ctx.cwd ?? process.cwd();
+  if (ctx.origin != null) {
+    logger.log(`Project root: ${path.relative(ctx.origin, cwd) || '.'}`);
+  }
   const installed = detectInstalledTargetVersion(cwd);
   const expectedVersion =
     ctx.expectedVersion ??

package/api/upgrade/registry/registry.test.mjs

@@ -19,6 +19,8 @@ import {
   discoverRegistryReceipts,
   reconcileRegistryCompositions,
 } from './registry.mjs';
+import {upgrade} from '../upgrade.mjs';
+import {logger} from '../../logger.mjs';
 
 const ITEM = {
   name: 'example-button-basic',
@@ -824,3 +826,86 @@ describe('registry composition upgrades', () => {
     expect(fs.readFileSync(sourcePath, 'utf8')).toBe('old\n');
   });
 });
+
+describe('copied-composition paths name files from the folder the command ran in', () => {
+  it('below the project root, and from the scanned source folder at the root', async () => {
+    const {sourcePath} = seed({
+      base: 'value = 1\n',
+      current: 'value = local\n',
+    });
+    const fetchImpl = remote('value = upstream\n');
+    const origin = path.join(project, 'apps', 'web');
+
+    const [atRoot] = (await reconcile({}, {fetchImpl})).summary.items[0].files;
+    const [below] = (await reconcile({}, {fetchImpl, origin})).summary.items[0]
+      .files;
+
+    expect(atRoot).toMatchObject({
+      path: SOURCE_TARGET,
+      conflictFile: `${SOURCE_TARGET}.astryx-conflict`,
+    });
+    expect(below).toMatchObject({
+      path: `../../src/${SOURCE_TARGET}`,
+      conflictFile: `../../src/${SOURCE_TARGET}.astryx-conflict`,
+    });
+    expect(path.resolve(origin, below.path)).toBe(sourcePath);
+  });
+
+  it('for an invalid receipt too', async () => {
+    const value = receipt('base\n');
+    value.files[0].sha256 = '0'.repeat(64);
+    seed({base: 'base\n', receiptValue: value});
+    const fetchImpl = remote('new\n');
+    const origin = path.join(project, 'docs');
+
+    const [atRoot] = (await reconcile({}, {fetchImpl})).summary.items;
+    const [below] = (await reconcile({}, {fetchImpl, origin})).summary.items;
+
+    expect(atRoot.message).toContain(`Invalid receipt ${RECEIPT_TARGET}:`);
+    expect(below.message).toContain(
+      `Invalid receipt ../src/${RECEIPT_TARGET}:`,
+    );
+  });
+
+  it('through upgrade(), with --registry and in a run, which name the project root', async () => {
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({
+        name: 'app',
+        dependencies: {'@astryxdesign/core': '0.6.0'},
+      }),
+    );
+    const core = path.join(project, '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 frontend = path.join(project, 'frontend');
+    fs.mkdirSync(frontend);
+    seed({base: 'old\n'});
+    vi.stubGlobal('fetch', remote('new\n'));
+    const log = vi.spyOn(logger, 'log');
+    try {
+      const registry = await upgrade({registry: true}, {cwd: frontend});
+      const run = await upgrade({from: '0.6.0'}, {cwd: frontend});
+      const atRoot = await upgrade({registry: true}, {cwd: project});
+
+      expect(registry.data.items[0].files[0].path).toBe(
+        `../src/${SOURCE_TARGET}`,
+      );
+      expect(run.data.registryCompositions.items[0].files[0].path).toBe(
+        `../src/${SOURCE_TARGET}`,
+      );
+      expect(atRoot.data.items[0].files[0].path).toBe(SOURCE_TARGET);
+      expect(
+        log.mock.calls.filter(([line]) =>
+          String(line).startsWith('Project root:'),
+        ),
+      ).toEqual([['Project root: ..'], ['Project root: ..']]);
+    } finally {
+      vi.unstubAllGlobals();
+      log.mockRestore();
+    }
+  });
+});

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();
+    }
+  });
+});