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

package/api/upgrade/run/run.d.mts

@@ -7,9 +7,11 @@
  * on failure. Progress is emitted through the shared `logger` (silent by default).
  *
  * @param {import('../_adapter.mjs').UpgradeOptions} [options]
- * @param {{cwd?: string}} [ctx]
+ * @param {{cwd?: string, origin?: string}} [ctx] `origin` is the folder the
+ *   command ran in, when `cwd` is the project root above it
  * @returns {Promise<import('../upgrade.type.mjs').UpgradeStatusResponse | import('../upgrade.type.mjs').UpgradeRunResponse>}
  */
-export function run(options?: import("../_adapter.mjs").UpgradeOptions, { cwd }?: {
+export function run(options?: import("../_adapter.mjs").UpgradeOptions, { cwd, origin }?: {
     cwd?: string;
+    origin?: string;
 }): Promise<import("../upgrade.type.mjs").UpgradeStatusResponse | import("../upgrade.type.mjs").UpgradeRunResponse>;

package/api/upgrade/run/run.mjs

@@ -15,12 +15,18 @@
  * ShadCN-copied compositions → post-codemod hooks → render + refresh agent docs
  * from final post-upgrade state. Integration DISCOVERY errors skip that
  * integration; execution errors abort before the agent-doc write.
+ *
+ * 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 then carries `cliBehindCore`, and no human line says the
+ * upgrade finished; the warning names the same upgrade on the matching CLI.
  */
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
   detectInstalledTargetVersion,
+  detectCliBehindCore,
   prepareAgentDocsRefresh,
   applyAgentDocsRefresh,
   inspectAgentDocs,
@@ -42,9 +48,11 @@ import {
   statusUpToDate,
   statusNoCodemods,
   statusConfigFixable,
+  logCliBehindCore,
 } from '../status/status.mjs';
 import {semverGte} from '../../../foundation/env/semver.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
 import {logger} from '../../logger.mjs';
@@ -107,10 +115,11 @@ function loadFileProtection(cwd) {
  * on failure. Progress is emitted through the shared `logger` (silent by default).
  *
  * @param {import('../_adapter.mjs').UpgradeOptions} [options]
- * @param {{cwd?: string}} [ctx]
+ * @param {{cwd?: string, origin?: string}} [ctx] `origin` is the folder the
+ *   command ran in, when `cwd` is the project root above it
  * @returns {Promise<import('../upgrade.type.mjs').UpgradeStatusResponse | import('../upgrade.type.mjs').UpgradeRunResponse>}
  */
-export async function run(options = {}, {cwd = process.cwd()} = {}) {
+export async function run(options = {}, {cwd = process.cwd(), origin} = {}) {
   // Resolve the source dir against the API's cwd (not process.cwd()) so a
   // programmatic caller in another directory scans the right tree. Confine it to
   // cwd: --apply rewrites files in place, so a `..`-escaping or out-of-tree
@@ -144,9 +153,18 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   const sourcePathFound = fs.existsSync(path_);
 
   const currentVersion = /** @type {string} */ (options.from);
+  // Named first, so a run that stops on the Core lookup below still says which
+  // folder it searched (spec:AST-040 FR12).
+  if (origin != null) {
+    logger.log(`Project root: ${path.relative(origin, cwd) || '.'}`);
+    logger.log(`Source folder: ${path.relative(origin, path_) || '.'}`);
+  }
   const installed = detectInstalledTargetVersion(cwd);
   if (!installed) {
-    const msg = `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
+    // Outside a project there is no version to install (spec AST-081 FR3).
+    const msg = isOutsideProject(cwd)
+      ? 'Could not find installed @astryxdesign/core (or legacy @xds/core). This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.'
+      : `Could not find installed @astryxdesign/core (or legacy @xds/core). Install the target version first, then rerun \`${getCliInvocation()} upgrade --from <old-version>\`.`;
     logger.error(msg);
     logger.log('Aborted\n');
     throw new AstryxError(msg, undefined, ERROR_CODES.ERR_VERSION_DETECT);
@@ -159,6 +177,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       {apply, path: path_},
       {
         cwd,
+        origin,
         expectedVersion:
           installed.packageName === '@astryxdesign/core'
             ? targetVersion
@@ -181,6 +200,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     const registryResult = await reconcileCompositions();
     const agentDocsPlan = await prepareAgentDocsRefresh({
       cwd,
+      origin,
       installedVersion: targetVersion,
       apply,
     });
@@ -195,6 +215,17 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     });
   }
 
+  // Past the up-to-date exit, codemods are needed through targetVersion. A
+  // CLI older than that has none for the releases after its own version.
+  const cliBehindCore = detectCliBehindCore({
+    from: currentVersion,
+    to: targetVersion,
+    packageName: installed.packageName,
+    options,
+    cwd,
+    sourcePath: path_,
+  });
+
   const versionManifests = await getCoreVersionManifests(
     currentVersion,
     targetVersion,
@@ -243,6 +274,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     skipCodemods,
     root: cwd,
     protection,
+    coversTarget: !cliBehindCore,
   });
   const coreResult =
     codemodResult && 'totalFilesChanged' in codemodResult
@@ -271,6 +303,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       for (const item of protectedFiles) {
         logger.error(`  ${item.file} — ${item.declarations.join('; ')}`);
       }
+      if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
       logger.log('Upgrade incomplete: protected changes remain\n');
       return {
         type: 'upgrade.run',
@@ -299,6 +332,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
           complete: false,
           errorCode: 'ERR_CODEMOD_PROTECTED',
           errors: coreResult?.errors ?? [],
+          ...(cliBehindCore ? {cliBehindCore} : {}),
         },
       };
     }
@@ -316,6 +350,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
         to: targetVersion,
         configError: configErr.message,
         configCodemods: coreConfigCodemodNames,
+        cliBehindCore,
         agentDocs:
           /** @type {import('../upgrade.type.mjs').AgentDocsSummary} */ ({
             status: inspection.status,
@@ -370,6 +405,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     // No codemods in range — safe to render agent docs from current state.
     const agentDocsPlan = await prepareAgentDocsRefresh({
       cwd,
+      origin,
       installedVersion: targetVersion,
       apply,
     });
@@ -381,6 +417,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       to: targetVersion,
       agentDocs,
       ...(registryResult ? {registryCompositions: registryResult.summary} : {}),
+      cliBehindCore,
     });
   }
 
@@ -620,6 +657,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   }
   receipt.errors = finalErrors;
   if (registryResult) receipt.registryCompositions = registryResult.summary;
+  if (cliBehindCore) receipt.cliBehindCore = cliBehindCore;
 
   if (protectedFiles.length > 0) {
     logger.error(
@@ -643,6 +681,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   if (protectedFiles.length === 0) {
     const agentDocsPlan = await prepareAgentDocsRefresh({
       cwd,
+      origin,
       installedVersion: targetVersion,
       apply,
       fresh: true,
@@ -655,7 +694,12 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   }
 
   const registryOk = receipt.registryCompositions?.ok ?? true;
-  const done = apply ? 'Upgrade complete' : 'Dry run complete';
+  if (cliBehindCore) logCliBehindCore(cliBehindCore, targetVersion);
+  const done = cliBehindCore
+    ? 'Upgrade incomplete'
+    : apply
+      ? 'Upgrade complete'
+      : 'Dry run complete';
   logger.log(
     protectedFiles.length > 0
       ? 'Upgrade incomplete: protected changes remain\n'

package/api/upgrade/run/run.test.mjs

@@ -3,18 +3,41 @@
 /**
  * @file Colocated tests for the upgrade.run leaf — the --path scan dir must be
  * confined to cwd (upgrade rewrites source in place with --apply, so an escaping
- * or out-of-tree path must be rejected), and the receipt must say whether that
- * dir existed at all.
+ * or out-of-tree path must be rejected), the receipt must say whether that
+ * dir existed at all, a run from any folder in a project upgrades that
+ * project (the nearest folder whose package.json declares Astryx, never the
+ * home folder) and names files relative to the folder it ran in, and the
+ * target Core is the project's own.
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {upgrade} from '../upgrade.mjs';
+import {relativeToOrigin} from '../_adapter.mjs';
+import {logger} from '../../logger.mjs';
+import {generateCompressedIndex} from '../../../foundation/agent-docs/agent-docs.mjs';
 
 const SLOW = 30_000;
 
+/**
+ * Run `fn` with `home` as the home folder.
+ * @template T
+ * @param {string} home @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+async function withHome(home, fn) {
+  const previous = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    return await fn();
+  } finally {
+    if (previous === undefined) delete process.env.HOME;
+    else process.env.HOME = previous;
+  }
+}
+
 function seedProject(dir) {
   fs.writeFileSync(
     path.join(dir, 'package.json'),
@@ -95,3 +118,394 @@ describe('upgrade.run — sourcePathFound', () => {
     expect(res.data.sourcePathFound).toBe(true);
   }, SLOW);
 });
+
+/** Core 0.7.0 renamed this prop; its codemod renames it on Typeahead. */
+const OLD_PROP_SOURCE =
+  "import {Typeahead} from '@astryxdesign/core';\n" +
+  'export const App = () => <Typeahead label="Fruit" emptySearchResultsText="None" />;\n';
+
+/**
+ * A project with Core 0.7.0 installed and src/App.tsx using a prop that 0.7.0
+ * renamed.
+ * @param {string} dir
+ */
+function seedOldPropProject(dir) {
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+  );
+  const core = path.join(dir, 'node_modules', '@astryxdesign', 'core');
+  fs.mkdirSync(core, {recursive: true});
+  fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.7.0'}));
+  fs.mkdirSync(path.join(dir, 'src', 'l1', 'l2'), {recursive: true});
+  fs.writeFileSync(path.join(dir, 'src', 'App.tsx'), OLD_PROP_SOURCE);
+}
+
+describe('upgrade.run — a run from a subfolder upgrades the project', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-scope-'));
+    seedOldPropProject(dir);
+  });
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  const appSource = () => fs.readFileSync(path.join(dir, 'src', 'App.tsx'), 'utf-8');
+
+  it.each([['src', 'App.tsx'], ['src/l1/l2', '../../App.tsx']])(
+    'scans the project src by default when run from %s',
+    async (folder, reported) => {
+      const res = await upgrade({from: '0.6.8', apply: true}, {cwd: path.join(dir, folder)});
+
+      expect(res.type).toBe('upgrade.run');
+      expect(res.data.sourcePathFound).toBe(true);
+      expect(res.data.filesChanged).toBe(1);
+      expect(res.data.modifiedFiles).toEqual([reported]);
+      expect(appSource()).toContain('emptySearchText="None"');
+    },
+    SLOW,
+  );
+
+  it('reads a path you name relative to the folder you ran in', async () => {
+    const res = await upgrade({from: '0.6.8', path: '../..', apply: true}, {cwd: path.join(dir, 'src', 'l1', 'l2')});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.filesChanged).toBe(1);
+    expect(appSource()).toContain('emptySearchText="None"');
+  }, SLOW);
+
+  it('still rejects a path outside the project', async () => {
+    await expect(
+      upgrade({from: '0.6.8', path: '../../..'}, {cwd: path.join(dir, 'src', 'l1')}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(appSource()).toBe(OLD_PROP_SOURCE);
+  }, SLOW);
+
+  it("refreshes the agent docs at the project root, not the folder it ran in", async () => {
+    fs.writeFileSync(
+      path.join(dir, 'AGENTS.md'),
+      `# Agents\n\n${generateCompressedIndex('0.6.8')}\n`,
+    );
+
+    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: path.join(dir, 'src', 'l1')});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.agentDocs.action).toBe('refreshed');
+    expect(res.data.agentDocs.files).toEqual(['../../AGENTS.md']);
+    expect(fs.existsSync(path.join(dir, 'src', 'l1', 'AGENTS.md'))).toBe(false);
+  }, SLOW);
+});
+
+describe('upgrade.run — the result names files relative to the folder it ran in', () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-receipt-'));
+    seedOldPropProject(dir);
+    fs.writeFileSync(path.join(dir, 'src', 'Generated.tsx'), `// @generated\n${OLD_PROP_SOURCE}`);
+    fs.writeFileSync(path.join(dir, 'src', 'Vendored.tsx'), OLD_PROP_SOURCE);
+    fs.writeFileSync(path.join(dir, '.gitattributes'), 'src/Vendored.tsx linguist-generated\n');
+    fs.writeFileSync(path.join(dir, 'AGENTS.md'), `# Agents\n\n${generateCompressedIndex('0.6.8')}\n`);
+    fs.mkdirSync(path.join(dir, 'frontend'), {recursive: true});
+  });
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  it.each([
+    ['frontend', '../'],
+    ['.', ''],
+  ])('from %s, every file path resolves from that folder', async (folder, up) => {
+    const cwd = path.join(dir, folder);
+
+    const res = await upgrade({from: '0.6.8'}, {cwd});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.modifiedFiles).toEqual([`${up}src/App.tsx`]);
+    expect(res.data.protectedFiles.map(item => item.file)).toEqual([
+      `${up}src/Generated.tsx`,
+      `${up}src/Vendored.tsx`,
+    ]);
+    for (const file of [...res.data.modifiedFiles, ...res.data.protectedFiles.map(item => item.file)]) {
+      expect(fs.existsSync(path.join(cwd, file))).toBe(true);
+    }
+    // The file a declaration names resolves from that folder too.
+    const vendored = res.data.protectedFiles.find(item => item.file.endsWith('Vendored.tsx'));
+    expect(vendored?.declarations).toEqual([`linguist-generated in ${up}.gitattributes:1`]);
+    expect(fs.existsSync(path.join(cwd, `${up}.gitattributes`))).toBe(true);
+  }, SLOW);
+
+  it('leaves a result from a run at the project root as it is', () => {
+    const result = {type: 'upgrade.run', data: {modifiedFiles: ['src/App.tsx']}};
+
+    expect(relativeToOrigin(result, {cwd: dir})).toBe(result);
+  });
+
+  it('rewrites every project-relative path and passes the copied-composition summary through', () => {
+    const registryCompositions = {items: [{item: 'example', path: 'components/Example.tsx', files: []}]};
+    const result = relativeToOrigin(
+      {
+        type: 'upgrade.run',
+        data: {
+          agentDocs: {status: 'stale', files: ['AGENTS.md']},
+          modifiedFiles: ['src/App.tsx'],
+          protectedFiles: [
+            {
+              file: 'src/Generated.tsx',
+              codemods: ['a'],
+              declarations: [
+                '@generated marker',
+                'excluded by .gitignore',
+                'excluded by src/.hgignore:3',
+                'linguist-generated in .gitattributes:1',
+                'symbolic link at src/linked',
+                'installed dependency metadata node_modules/x',
+              ],
+            },
+          ],
+          declinedCandidates: [{file: 'src/Loose.tsx', reason: 'unproven'}],
+          errors: [{file: '.', codemod: 'post-codemod-hook', error: 'failed'}],
+          registryCompositions,
+        },
+      },
+      {cwd: dir, origin: path.join(dir, 'apps', 'web')},
+    );
+
+    expect(result.data).toEqual({
+      agentDocs: {status: 'stale', files: ['../../AGENTS.md']},
+      modifiedFiles: ['../../src/App.tsx'],
+      protectedFiles: [
+        {
+          file: '../../src/Generated.tsx',
+          codemods: ['a'],
+          declarations: [
+            '@generated marker',
+            'excluded by ../../.gitignore',
+            'excluded by ../../src/.hgignore:3',
+            'linguist-generated in ../../.gitattributes:1',
+            'symbolic link at ../../src/linked',
+            'installed dependency metadata node_modules/x',
+          ],
+        },
+      ],
+      declinedCandidates: [{file: '../../src/Loose.tsx', reason: 'unproven'}],
+      errors: [{file: '../..', codemod: 'post-codemod-hook', error: 'failed'}],
+      registryCompositions,
+    });
+  });
+});
+
+describe("upgrade.run — the target Core is the project's own", () => {
+  let dir;
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-own-core-'));
+    seedOldPropProject(dir);
+  });
+  afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  /**
+   * A project nested in `dir`, with src/App.tsx using the renamed prop.
+   * @param {Record<string, string>} dependencies
+   */
+  function nestedProject(dependencies) {
+    const nested = path.join(dir, 'apps', 'web');
+    fs.mkdirSync(path.join(nested, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(nested, 'package.json'), JSON.stringify({name: 'web', dependencies}));
+    fs.writeFileSync(path.join(nested, 'src', 'App.tsx'), OLD_PROP_SOURCE);
+    return nested;
+  }
+
+  it.each([
+    ['declares no Astryx package', {}],
+    ['declares a Core it has not installed', {'@astryxdesign/core': '0.6.8'}],
+  ])(
+    'does not upgrade a project that %s to the Core of the home folder above it',
+    async (_label, dependencies) => {
+      const nested = nestedProject(dependencies);
+
+      await withHome(dir, () =>
+        expect(
+          upgrade({from: '0.6.8', apply: true}, {cwd: nested}),
+        ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'}),
+      );
+      expect(fs.readFileSync(path.join(nested, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+      expect(fs.readFileSync(path.join(dir, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+    },
+    SLOW,
+  );
+
+  it('names the folder it searched before stopping on a missing Core, from a subfolder (AST-040 FR12)', async () => {
+    fs.rmSync(path.join(dir, 'node_modules'), {recursive: true, force: true});
+    const sub = path.join(dir, 'src', 'l1');
+    const log = vi.spyOn(logger, 'log');
+    try {
+      await expect(upgrade({from: '0.6.8'}, {cwd: sub})).rejects.toMatchObject({
+        code: 'ERR_VERSION_DETECT',
+      });
+      const lines = log.mock.calls.map(([line]) => String(line));
+      expect(lines).toContain('Project root: ../..');
+      expect(lines.indexOf('Project root: ../..')).toBeLessThan(
+        lines.indexOf('Aborted\n'),
+      );
+    } finally {
+      log.mockRestore();
+    }
+  }, SLOW);
+
+  it('does not upgrade a nested project that declares a Core it has not installed to the Core above it', async () => {
+    const nested = nestedProject({'@astryxdesign/core': '0.6.8'});
+
+    await expect(
+      upgrade({from: '0.6.8', apply: true}, {cwd: nested}),
+    ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'});
+    expect(fs.readFileSync(path.join(nested, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+  }, SLOW);
+
+  it.each([
+    ['an override at the workspace root forces', {overrides: {'@astryxdesign/core': '0.7.0'}}, {'@astryxdesign/core': '~0.6.8'}],
+    ['a resolution at the workspace root forces', {resolutions: {'@astryxdesign/core': '0.7.0'}}, {'@astryxdesign/core': '0.6.8'}],
+    ['only a stale peer range names', {}, null],
+    ['the member declares another version of, not yet installed', {}, {'@astryxdesign/core': '0.9.0'}],
+  ])(
+    'upgrades a workspace member to a hoisted Core that %s',
+    async (_label, rootFields, dependencies) => {
+      fs.writeFileSync(
+        path.join(dir, 'package.json'),
+        JSON.stringify({name: 'root', private: true, workspaces: ['apps/*'], ...rootFields}),
+      );
+      const member = dependencies
+        ? nestedProject(dependencies)
+        : nestedProject({});
+      if (!dependencies) {
+        fs.writeFileSync(
+          path.join(member, 'package.json'),
+          JSON.stringify({name: 'web', peerDependencies: {'@astryxdesign/core': '^0.6.8'}}),
+        );
+      }
+
+      const res = await upgrade({from: '0.6.8', apply: true}, {cwd: member});
+
+      expect(res.type).toBe('upgrade.run');
+      expect(res.data.to).toBe('0.7.0');
+      expect(res.data.modifiedFiles).toEqual(['src/App.tsx']);
+      expect(fs.readFileSync(path.join(member, 'src', 'App.tsx'), 'utf-8')).toContain('emptySearchText="None"');
+    },
+    SLOW,
+  );
+
+  it('does not upgrade a project its workspace does not list to the hoisted Core', async () => {
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name: 'root', private: true, workspaces: ['packages/*']}),
+    );
+    const project = nestedProject({'@astryxdesign/core': '0.9.0'});
+
+    await expect(
+      upgrade({from: '0.6.8', apply: true}, {cwd: project}),
+    ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'});
+    expect(fs.readFileSync(path.join(project, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+  }, SLOW);
+
+  it.each([[['apps/*']], [['{apps/*,tools/*}']]])('upgrades a member that declares no Astryx package, in its own src, when the workspace lists %j', async workspaces => {
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name: 'root', private: true, workspaces, dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const member = nestedProject({});
+
+    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: path.join(member, 'src')});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.modifiedFiles).toEqual(['App.tsx']);
+    expect(fs.readFileSync(path.join(member, 'src', 'App.tsx'), 'utf-8')).toContain('emptySearchText="None"');
+    expect(fs.readFileSync(path.join(dir, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+  }, SLOW);
+});
+
+describe('upgrade.run — the project is the nearest folder that declares Astryx', () => {
+  let home;
+  beforeEach(() => {
+    home = fs.mkdtempSync(path.join(os.tmpdir(), 'upg-home-'));
+  });
+  afterEach(() => fs.rmSync(home, {recursive: true, force: true}));
+
+  // Astryx installed in a home folder whose src holds loose files and another
+  // project, run from a folder with no package.json.
+  it('does not upgrade the home folder from a folder inside it', async () => {
+    seedOldPropProject(home);
+    fs.mkdirSync(path.join(home, 'src', 'repoA', 'src'), {recursive: true});
+    fs.writeFileSync(
+      path.join(home, 'src', 'repoA', 'package.json'),
+      JSON.stringify({name: 'repoA', dependencies: {'@astryxdesign/core': '0.6.8'}}),
+    );
+    fs.writeFileSync(path.join(home, 'src', 'repoA', 'src', 'a.tsx'), OLD_PROP_SOURCE);
+    const desktop = path.join(home, 'Desktop');
+    fs.mkdirSync(desktop, {recursive: true});
+
+    await withHome(home, () =>
+      expect(
+        upgrade({from: '0.6.8', apply: true}, {cwd: desktop}),
+      ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'}),
+    );
+    expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+    expect(fs.readFileSync(path.join(home, 'src', 'repoA', 'src', 'a.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+  }, SLOW);
+
+  // Installing Core does not make a folder a project.
+  it('treats a folder that installs Core without declaring it as part of the project above it', async () => {
+    seedOldPropProject(home);
+    const tool = path.join(home, 'tools', 'codegen');
+    const core = path.join(tool, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(core, {recursive: true});
+    fs.writeFileSync(path.join(tool, 'package.json'), JSON.stringify({name: 'codegen'}));
+    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.9.0'}));
+
+    const res = await upgrade({from: '0.6.8', apply: true}, {cwd: tool});
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.to).toBe('0.7.0');
+    expect(res.data.modifiedFiles).toEqual(['../../src/App.tsx']);
+  }, SLOW);
+
+  it('names the project root and the folder it scans before a dry run in a folder that installs Core without declaring it', async () => {
+    seedOldPropProject(home);
+    const tool = path.join(home, 'tools', 'codegen');
+    const core = path.join(tool, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(core, {recursive: true});
+    fs.writeFileSync(path.join(tool, 'package.json'), JSON.stringify({name: 'codegen'}));
+    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({name: '@astryxdesign/core', version: '0.9.0'}));
+    const log = vi.spyOn(logger, 'log');
+    try {
+      const res = await upgrade({from: '0.6.8'}, {cwd: tool});
+
+      expect(res.type).toBe('upgrade.run');
+      const lines = log.mock.calls.map(([line]) => String(line));
+      expect(lines).toContain('Project root: ../..');
+      expect(lines).toContain(`Source folder: ${path.join('..', '..', 'src')}`);
+      expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+    } finally {
+      log.mockRestore();
+    }
+  }, SLOW);
+
+  it('upgrades the home folder as a folder outside any project, when run there', async () => {
+    seedOldPropProject(home);
+
+    const res = await withHome(home, () => upgrade({from: '0.6.8', apply: true}, {cwd: home}));
+
+    expect(res.type).toBe('upgrade.run');
+    expect(res.data.modifiedFiles).toEqual(['src/App.tsx']);
+    expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toContain('emptySearchText="None"');
+  }, SLOW);
+
+  it('does not leave a repository for the project around it', async () => {
+    seedOldPropProject(home);
+    const repo = path.join(home, 'vendor', 'repo');
+    fs.mkdirSync(path.join(repo, '.git'), {recursive: true});
+    fs.mkdirSync(path.join(repo, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(repo, 'package.json'), JSON.stringify({name: 'repo'}));
+    fs.writeFileSync(path.join(repo, 'src', 'App.tsx'), OLD_PROP_SOURCE);
+
+    await expect(
+      upgrade({from: '0.6.8', apply: true}, {cwd: repo}),
+    ).rejects.toMatchObject({code: 'ERR_VERSION_DETECT'});
+    expect(fs.readFileSync(path.join(repo, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+    expect(fs.readFileSync(path.join(home, 'src', 'App.tsx'), 'utf-8')).toBe(OLD_PROP_SOURCE);
+  }, SLOW);
+});

package/api/upgrade/status/status.d.mts

@@ -13,27 +13,43 @@ export function statusUpToDate({ from, to, agentDocs, registryCompositions }: {
     registryCompositions?: import("../upgrade.type.mjs").RegistryCompositionSummary;
 }): import("../upgrade.type.mjs").UpgradeStatusResponse;
 /**
- * No core or integration codemods apply to the requested version range.
- * @param {{from: string, to: string, agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary}} data
+ * The one warning for a CLI older than the installed Core: it has no codemods
+ * for the releases after its own version, and the pinned command does. The
+ * command gets a line of its own, so it copies exactly, whatever quotes or
+ * backticks its arguments carry. On Windows it is written for PowerShell, and
+ * the warning says so.
+ * @param {import('../upgrade.type.mjs').CliBehindCore} cliBehindCore
+ * @param {string} to the installed Core version
+ * @param {string} [platform] the `process.platform` the command was printed
+ *   for, as `quoteCommandArgument` and `commandInFolder` take it
+ */
+export function logCliBehindCore({ cliVersion, command }: import("../upgrade.type.mjs").CliBehindCore, to: string, platform?: string): void;
+/**
+ * No core or integration codemods apply to the requested version range. When
+ * the CLI is older than the installed Core, that only means this CLI has none:
+ * the result carries `cliBehindCore` and the human lines say so.
+ * @param {{from: string, to: string, agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary, cliBehindCore?: import('../upgrade.type.mjs').CliBehindCore | null}} data
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
-export function statusNoCodemods({ from, to, agentDocs, registryCompositions }: {
+export function statusNoCodemods({ from, to, agentDocs, registryCompositions, cliBehindCore }: {
     from: string;
     to: string;
     agentDocs: import("../upgrade.type.mjs").AgentDocsSummary;
     registryCompositions?: import("../upgrade.type.mjs").RegistryCompositionSummary;
+    cliBehindCore?: import("../upgrade.type.mjs").CliBehindCore | null;
 }): import("../upgrade.type.mjs").UpgradeStatusResponse;
 /**
  * DRY-RUN only: the consumer's astryx.config fails strict validation, but a
  * pending core CONFIG codemod previewed a change that would repair it. Preview
  * the fix + report the exact `--apply` command; integrations are skipped here.
- * @param {{from: string, to: string, configError: string, configCodemods: string[], agentDocs: import('../upgrade.type.mjs').AgentDocsSummary}} data
+ * @param {{from: string, to: string, configError: string, configCodemods: string[], agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, cliBehindCore?: import('../upgrade.type.mjs').CliBehindCore | null}} data
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
-export function statusConfigFixable({ from, to, configError, configCodemods, agentDocs }: {
+export function statusConfigFixable({ from, to, configError, configCodemods, agentDocs, cliBehindCore }: {
     from: string;
     to: string;
     configError: string;
     configCodemods: string[];
     agentDocs: import("../upgrade.type.mjs").AgentDocsSummary;
+    cliBehindCore?: import("../upgrade.type.mjs").CliBehindCore | null;
 }): import("../upgrade.type.mjs").UpgradeStatusResponse;