@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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';
@@ -146,7 +154,10 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   const currentVersion = /** @type {string} */ (options.from);
   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);
@@ -195,6 +206,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 +265,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     skipCodemods,
     root: cwd,
     protection,
+    coversTarget: !cliBehindCore,
   });
   const coreResult =
     codemodResult && 'totalFilesChanged' in codemodResult
@@ -271,6 +294,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 +323,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
           complete: false,
           errorCode: 'ERR_CODEMOD_PROTECTED',
           errors: coreResult?.errors ?? [],
+          ...(cliBehindCore ? {cliBehindCore} : {}),
         },
       };
     }
@@ -316,6 +341,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,
@@ -381,6 +407,7 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
       to: targetVersion,
       agentDocs,
       ...(registryResult ? {registryCompositions: registryResult.summary} : {}),
+      cliBehindCore,
     });
   }
 
@@ -620,6 +647,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(
@@ -655,7 +683,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/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;

package/api/upgrade/status/status.mjs

@@ -10,6 +10,10 @@
  *   - `config_fixable` — DRY-RUN only: the config fails strict validation but a
  *     pending core CONFIG codemod would repair it; preview the fix, don't write.
  *
+ * `no_codemods` and `config_fixable` also carry `cliBehindCore` when the
+ * installed Core is newer than this CLI: the run cannot finish the upgrade, so
+ * neither says it is done, and `logCliBehindCore` names the command that can.
+ *
  * These builders own the exact human progress lines for their path (emitted via
  * the shared `logger`) and return the `upgrade.status` envelope; the caller
  * just returns what they hand back.
@@ -40,13 +44,43 @@ export function statusUpToDate({from, to, agentDocs, registryCompositions}) {
 }
 
 /**
- * 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}, to, platform = process.platform) {
+  const shell = platform === 'win32' ? ' in PowerShell' : '';
+  logger.warn(
+    `This CLI (${cliVersion}) is older than the installed @astryxdesign/core (${to}): ` +
+      `it has no codemods for releases after ${cliVersion}, so it cannot finish this upgrade. ` +
+      `Run it${shell} with the CLI that matches your Core:`,
+  );
+  logger.warn(`  ${command}`);
+}
+
+/**
+ * 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}) {
-  logger.log('[ok] No codemods available for this version range.');
-  logger.log(registryCompositions?.ok === false ? 'Finished with unresolved registry items\n' : 'Done\n');
+export function statusNoCodemods({from, to, agentDocs, registryCompositions, cliBehindCore}) {
+  if (cliBehindCore) logCliBehindCore(cliBehindCore, to);
+  else logger.log('[ok] No codemods available for this version range.');
+  logger.log(
+    registryCompositions?.ok === false
+      ? 'Finished with unresolved registry items\n'
+      : cliBehindCore
+        ? 'Upgrade incomplete\n'
+        : 'Done\n',
+  );
   return {
     type: 'upgrade.status',
     data: {
@@ -55,6 +89,7 @@ export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
       to,
       agentDocs,
       ...(registryCompositions ? {registryCompositions} : {}),
+      ...(cliBehindCore ? {cliBehindCore} : {}),
     },
   };
 }
@@ -63,10 +98,10 @@ export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
  * 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}) {
   const codemodFlags = configCodemods.map(name => `--codemod ${name}`).join(' ');
   const suggestedCommand = `astryx upgrade --from ${from} ${codemodFlags} --apply`;
   const guidance =
@@ -77,7 +112,8 @@ export function statusConfigFixable({from, to, configError, configCodemods, agen
   logger.warn(guidance);
   logger.log(`  ${formatCliCommand(suggestedCommand)}`);
   logger.log('Integrations are skipped in this preview; they will be processed on the --apply run.');
-  logger.log('Dry run complete\n');
+  if (cliBehindCore) logCliBehindCore(cliBehindCore, to);
+  logger.log(cliBehindCore ? 'Upgrade incomplete\n' : 'Dry run complete\n');
   return {
     type: 'upgrade.status',
     data: {
@@ -90,6 +126,7 @@ export function statusConfigFixable({from, to, configError, configCodemods, agen
       message: guidance,
       note: 'Integrations are skipped in this preview; they will be processed on the --apply run.',
       agentDocs,
+      ...(cliBehindCore ? {cliBehindCore} : {}),
     },
   };
 }

package/api/upgrade/upgrade.doc.mjs

@@ -22,7 +22,10 @@ export const doc = {
     'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
     'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
     'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
-    'copied compositions.',
+    'copied compositions. Core codemods ship inside the CLI, so a CLI older than the installed ' +
+    'Core has none for the releases after its own version: the result then carries ' +
+    '`cliBehindCore` with the command that runs the same upgrade on the matching CLI.' +
+    " In global mode: in a project, the CLI runs `upgrade` with the project's own CLI, whichever astryx command started it (in a project with no CLI of its own, the one you started); this function runs the codemods of the package it is imported from. With `cwd` outside a project, `list` lists this release's codemods, `registry` finds no copied compositions, and a migration writes nothing and fails with `ERR_VERSION_DETECT`. See {@link namespace:global} and {@link generic:who-answers}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -118,12 +121,12 @@ export const doc = {
     {
       type: 'upgrade.status',
       description:
-        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
+        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary. When the installed Core is newer than the CLI, no_codemods and config_fixable also carry cliBehindCore ({cliVersion, command}): this CLI has no codemods for the releases after cliVersion, and command runs the same upgrade with the CLI release that matches the installed Core.',
     },
     {
       type: 'upgrade.run',
       description:
-        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
+        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run, and command runs the same upgrade with the matching CLI.',
     },
   ],
   throws: [

package/api/upgrade/upgrade.mjs

@@ -26,6 +26,7 @@ import {registryUpgrade} from './registry/registry.mjs';
 import {run} from './run/run.mjs';
 import {isValidSemver} 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';
@@ -91,7 +92,10 @@ export async function upgrade(options = {}, {cwd = process.cwd()} = {}) {
   }
 
   if (!options.list && !options.from) {
-    const msg = `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
+    // Outside a project there is no version to install (spec AST-081 FR3).
+    const msg = isOutsideProject(cwd)
+      ? 'Missing required --from. This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.'
+      : `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
     logger.error(msg);
     logger.log('Aborted\n');
     throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);

package/api/upgrade/upgrade.type.d.mts

@@ -160,6 +160,22 @@ export type ProtectedCodemodFile = {
      */
     commands: string[];
 };
+/**
+ * Present only when the installed `@astryxdesign/core` (the response's `to`) is
+ * newer than the running CLI. Core codemods ship inside the CLI, so this CLI
+ * has none for the releases after `cliVersion`: the run could not migrate them,
+ * whatever else the response reports.
+ */
+export type CliBehindCore = {
+    /**
+     * The running CLI's version, the last release it has codemods for.
+     */
+    cliVersion: string;
+    /**
+     * The same upgrade, run with the CLI release that matches the installed Core. It first changes to the folder this run used, then names the directory this run scanned as an absolute `--path`, both with symbolic links resolved, so pasted from any folder it finds the same Core and scans the same directory. It is written for a POSIX shell (sh, bash, zsh), or for PowerShell on Windows, with each argument quoted for that shell; cmd.exe is not a target.
+     */
+    command: string;
+};
 /**
  * astryx --json upgrade [--apply]
  */
@@ -190,6 +206,7 @@ export type UpgradeRunResponse = {
             codemod: string;
             error: string;
         }[] | undefined;
+        cliBehindCore?: CliBehindCore | undefined;
     };
 };
 /**
@@ -202,6 +219,10 @@ export type UpgradeRunResponse = {
  *   range) would repair it. The dry run previews the fix without writing and
  *   reports the exact command to apply it; integrations are skipped for the
  *   preview (they will be processed on the `--apply` run).
+ *
+ * `no_codemods` and `config_fixable` carry `cliBehindCore` when the installed
+ * Core is newer than this CLI; `no_codemods` then means only that this CLI has
+ * no codemods for the range.
  */
 export type UpgradeStatusResponse = {
     type: "upgrade.status";
@@ -217,6 +238,7 @@ export type UpgradeStatusResponse = {
         to: string;
         agentDocs: AgentDocsSummary;
         registryCompositions?: RegistryCompositionSummary;
+        cliBehindCore?: CliBehindCore;
     } | {
         status: "config_fixable";
         from: string;
@@ -227,6 +249,7 @@ export type UpgradeStatusResponse = {
         message: string;
         note: string;
         agentDocs: AgentDocsSummary;
+        cliBehindCore?: CliBehindCore;
     };
 };
 /**

package/api/upgrade/upgrade.type.mjs

@@ -106,6 +106,16 @@
  * @property {string[]} commands Exact regeneration commands found in generated headers, when present.
  */
 
+/**
+ * Present only when the installed `@astryxdesign/core` (the response's `to`) is
+ * newer than the running CLI. Core codemods ship inside the CLI, so this CLI
+ * has none for the releases after `cliVersion`: the run could not migrate them,
+ * whatever else the response reports.
+ * @typedef {object} CliBehindCore
+ * @property {string} cliVersion The running CLI's version, the last release it has codemods for.
+ * @property {string} command The same upgrade, run with the CLI release that matches the installed Core. It first changes to the folder this run used, then names the directory this run scanned as an absolute `--path`, both with symbolic links resolved, so pasted from any folder it finds the same Core and scans the same directory. It is written for a POSIX shell (sh, bash, zsh), or for PowerShell on Windows, with each argument quoted for that shell; cmd.exe is not a target.
+ */
+
 /**
  * astryx --json upgrade [--apply]
  * @typedef {object} UpgradeRunResponse
@@ -127,6 +137,7 @@
  * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient.
  * @property {number} [data.transformsApplied] Total codemod changes. A code or config codemod counts once for each file it changed, so one file changed by four of them counts four times; a project codemod counts once, however many files it writes.
  * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
+ * @property {CliBehindCore} [data.cliBehindCore] Present only when the installed Core is newer than this CLI: codemods for the releases after `cliBehindCore.cliVersion` did not run.
  */
 
 /**
@@ -140,9 +151,13 @@
  *   reports the exact command to apply it; integrations are skipped for the
  *   preview (they will be processed on the `--apply` run).
  *
+ * `no_codemods` and `config_fixable` carry `cliBehindCore` when the installed
+ * Core is newer than this CLI; `no_codemods` then means only that this CLI has
+ * no codemods for the range.
+ *
  * @typedef {object} UpgradeStatusResponse
  * @property {'upgrade.status'} type
- * @property {{status: 'up_to_date', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary} | {status: 'no_codemods', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary} | {status: 'config_fixable', from: string, to: string, configError: string, configCodemods: string[], suggestedCommand: string, message: string, note: string, agentDocs: AgentDocsSummary}} data
+ * @property {{status: 'up_to_date', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary} | {status: 'no_codemods', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary, cliBehindCore?: CliBehindCore} | {status: 'config_fixable', from: string, to: string, configError: string, configCodemods: string[], suggestedCommand: string, message: string, note: string, agentDocs: AgentDocsSummary, cliBehindCore?: CliBehindCore}} data
  */
 
 /**

package/assets/codemods/__tests__/registry.test.mjs

@@ -31,6 +31,7 @@ describe('registry', () => {
         '0.6.4',
         '0.6.7',
         '0.7.0',
+        '0.7.2',
       ]);
     });
   });

package/assets/codemods/registry.mjs

@@ -32,6 +32,7 @@ const registry = new Map([
   ['0.6.4', () => import('./transforms/v0.6.4/index.mjs')],
   ['0.6.7', () => import('./transforms/v0.6.7/index.mjs')],
   ['0.7.0', () => import('./transforms/v0.7.0/index.mjs')],
+  ['0.7.2', () => import('./transforms/v0.7.2/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/assets/codemods/runner.mjs

@@ -418,6 +418,7 @@ async function runProjectCodemod(
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
  * @param {string} [options.root] - Project root a project codemod reads (default: the process cwd)
  * @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} [options.protection] - Preloaded protection resolver
+ * @param {boolean} [options.coversTarget] - False when these codemods stop before the installed target (the CLI is older than Core), so a run with no changes does not say the code is up to date. Default true.
  * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, changedFiles: string[], writtenFiles: string[], stagedContents: Map<string, string>, protectedFiles: import('../../authoring/codemod/type').CodemodRunResult['protectedFiles'], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} | {ok: false, reason: string, resolvedPath: string}>}
  */
 export async function runCodemods(
@@ -430,6 +431,7 @@ export async function runCodemods(
     silent = false,
     root = process.cwd(),
     protection: providedProtection,
+    coversTarget = true,
   },
 ) {
   // No-op stub object so silent mode skips log output entirely without
@@ -643,7 +645,11 @@ export async function runCodemods(
     errors.length === 0 &&
     protectedFiles.length === 0
   ) {
-    log.success('No changes needed — your code is already up to date!');
+    // Codemods that stop before the installed target cannot vouch for the
+    // code; the caller says what is missing.
+    if (coversTarget) {
+      log.success('No changes needed — your code is already up to date!');
+    }
   } else if (apply && protectedFiles.length > 0) {
     log.warn(
       `Applied ${totalTransformsApplied} owned change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}; protected changes remain.`,

package/assets/codemods/transforms/next/index.mjs

@@ -7,14 +7,4 @@
  * this file into the resolved version folder.
  */
 
-import migrateListEdgeCompensationToEdge, {
-  meta as migrateListEdgeCompensationToEdgeMeta,
-} from './migrate-list-edge-compensation-to-edge.mjs';
-
-export default [
-  {
-    name: 'migrate-list-edge-compensation-to-edge',
-    transform: migrateListEdgeCompensationToEdge,
-    meta: migrateListEdgeCompensationToEdgeMeta,
-  },
-];
+export default [];

package/assets/codemods/transforms/v0.7.2/index.mjs

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file next transform manifest
+ *
+ * Staged codemods for the next release. The Version Packages PR promotes
+ * this file into the resolved version folder.
+ */
+
+import migrateListEdgeCompensationToEdge, {
+  meta as migrateListEdgeCompensationToEdgeMeta,
+} from './migrate-list-edge-compensation-to-edge.mjs';
+
+export default [
+  {
+    name: 'migrate-list-edge-compensation-to-edge',
+    transform: migrateListEdgeCompensationToEdge,
+    meta: migrateListEdgeCompensationToEdgeMeta,
+  },
+];