@payloadcms/codemod 4.0.0-internal.2f0d313 → 4.0.0-internal.31ba7ee

package/dist/upgrade/dispatch.d.ts

@@ -0,0 +1,38 @@
+import type { Agent, DispatchChoice } from './selectAgent.js';
+import { runUpgrade } from './index.js';
+type UpgradeFlags = Parameters<typeof runUpgrade>[0]['flags'];
+type RunDispatchArgs = {
+    agentFlag?: string;
+    path: string;
+    upgradeFlags: UpgradeFlags;
+};
+export type DispatchDeps = {
+    detectAgents: () => Agent[];
+    isInteractive: boolean;
+    promptChoice: (agents: Agent[]) => Promise<DispatchChoice>;
+    renderPrompt: () => string;
+    runMechanical: (args: {
+        flags: UpgradeFlags;
+        path: string;
+    }) => Promise<{
+        failed: boolean;
+    }>;
+    spawnAgent: (args: {
+        agent: Agent;
+        cwd: string;
+        promptFilePath: string;
+    }) => Promise<{
+        code: number;
+    }>;
+    writePromptFile: (contents: string) => string;
+};
+/**
+ * Bare `upgrade`: pick how to run the full v3 -> v4 upgrade. Hands the
+ * orchestration prompt to a detected coding agent, runs the mechanical slice
+ * here, or prints the prompt for manual use.
+ */
+export declare function runDispatch({ agentFlag, path, upgradeFlags }: RunDispatchArgs, deps?: DispatchDeps): Promise<{
+    failed: boolean;
+}>;
+export {};
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/upgrade/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/upgrade/dispatch.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAKvC,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;AAE7D,KAAK,eAAe,GAAG;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,YAAY,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,YAAY,EAAE,MAAM,KAAK,EAAE,CAAA;IAC3B,aAAa,EAAE,OAAO,CAAA;IACtB,YAAY,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;IAC1D,YAAY,EAAE,MAAM,MAAM,CAAA;IAC1B,aAAa,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC5F,UAAU,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;QACnF,IAAI,EAAE,MAAM,CAAA;KACb,CAAC,CAAA;IACF,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;CAC9C,CAAA;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,eAAe,EAClD,IAAI,GAAE,YAAoC,GACzC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAmC9B"}

package/dist/upgrade/dispatch.js

@@ -0,0 +1,132 @@
+/* eslint-disable no-console */ import * as p from '@clack/prompts';
+import { spawn } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { runUpgrade } from './index.js';
+import { renderUpgradePrompt } from './prompt.js';
+import { detectInstalledAgents, selectDispatch } from './selectAgent.js';
+import { resolveSelfCommand } from './selfCommand.js';
+/**
+ * Bare `upgrade`: pick how to run the full v3 -> v4 upgrade. Hands the
+ * orchestration prompt to a detected coding agent, runs the mechanical slice
+ * here, or prints the prompt for manual use.
+ */ export async function runDispatch({ agentFlag, path, upgradeFlags }, deps = defaultDispatchDeps()) {
+    const installed = deps.detectAgents();
+    let choice;
+    try {
+        choice = await selectDispatch({
+            agentFlag,
+            installed,
+            isInteractive: deps.isInteractive,
+            prompt: deps.promptChoice
+        });
+    } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return {
+            failed: true
+        };
+    }
+    if (choice.kind === 'run') {
+        return deps.runMechanical({
+            flags: upgradeFlags,
+            path
+        });
+    }
+    const promptText = deps.renderPrompt();
+    if (choice.kind === 'print') {
+        console.log(promptText);
+        return {
+            failed: false
+        };
+    }
+    const promptFilePath = deps.writePromptFile(promptText);
+    console.log(`Handing the upgrade prompt to ${choice.agent.label}...`);
+    const { code } = await deps.spawnAgent({
+        agent: choice.agent,
+        cwd: resolve(path),
+        promptFilePath
+    });
+    return {
+        failed: code !== 0
+    };
+}
+function defaultDispatchDeps() {
+    return {
+        detectAgents: detectInstalledAgents,
+        isInteractive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        promptChoice: promptChoiceFromTerminal,
+        renderPrompt: ()=>renderUpgradePrompt({
+                command: resolveSelfCommand()
+            }),
+        runMechanical: (args)=>runUpgrade(args),
+        spawnAgent: spawnAgentInteractive,
+        writePromptFile: (contents)=>{
+            const dir = mkdtempSync(join(tmpdir(), 'payload-v4-upgrade-'));
+            const filePath = join(dir, 'prompt.md');
+            writeFileSync(filePath, contents);
+            return filePath;
+        }
+    };
+}
+/** Clack select: each installed agent, then run the slice or print the prompt. */ async function promptChoiceFromTerminal(agents) {
+    p.intro('Payload v3 -> v4 upgrade');
+    const selection = await p.select({
+        message: 'How do you want to run it?',
+        options: [
+            ...agents.map((agent)=>({
+                    hint: `hand the prompt to \`${agent.command}\``,
+                    label: agent.label,
+                    value: agent.id
+                })),
+            {
+                hint: 'pin versions, install, run the codemods now',
+                label: 'Run the mechanical steps',
+                value: 'run'
+            },
+            {
+                hint: 'run it yourself or paste it elsewhere',
+                label: 'Just print the prompt',
+                value: 'print'
+            }
+        ]
+    });
+    // Cancelling (Ctrl-C) falls back to printing the prompt so the user keeps it.
+    if (p.isCancel(selection)) {
+        return {
+            kind: 'print'
+        };
+    }
+    if (selection === 'run') {
+        return {
+            kind: 'run'
+        };
+    }
+    const agent = agents.find((a)=>a.id === selection);
+    return agent ? {
+        agent,
+        kind: 'agent'
+    } : {
+        kind: 'print'
+    };
+}
+/** Interactive agent session seeded with a one-line pointer to the prompt file. */ function spawnAgentInteractive({ agent, cwd, promptFilePath }) {
+    const launchPrompt = `Read ${promptFilePath} and follow it to upgrade this project from Payload v3 to v4.`;
+    return new Promise((resolveSpawn)=>{
+        const child = spawn(agent.command, [
+            launchPrompt
+        ], {
+            cwd,
+            shell: false,
+            stdio: 'inherit'
+        });
+        child.on('close', (code)=>resolveSpawn({
+                code: code ?? 1
+            }));
+        child.on('error', ()=>resolveSpawn({
+                code: 1
+            }));
+    });
+}
+
+//# sourceMappingURL=dispatch.js.map

package/dist/upgrade/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/upgrade/dispatch.ts"],"sourcesContent":["/* eslint-disable no-console */\nimport * as p from '@clack/prompts'\nimport { spawn } from 'node:child_process'\nimport { mkdtempSync, writeFileSync } from 'node:fs'\nimport { tmpdir } from 'node:os'\nimport { join, resolve } from 'node:path'\n\nimport type { Agent, DispatchChoice } from './selectAgent.js'\n\nimport { runUpgrade } from './index.js'\nimport { renderUpgradePrompt } from './prompt.js'\nimport { detectInstalledAgents, selectDispatch } from './selectAgent.js'\nimport { resolveSelfCommand } from './selfCommand.js'\n\ntype UpgradeFlags = Parameters<typeof runUpgrade>[0]['flags']\n\ntype RunDispatchArgs = {\n  agentFlag?: string\n  path: string\n  upgradeFlags: UpgradeFlags\n}\n\nexport type DispatchDeps = {\n  detectAgents: () => Agent[]\n  isInteractive: boolean\n  promptChoice: (agents: Agent[]) => Promise<DispatchChoice>\n  renderPrompt: () => string\n  runMechanical: (args: { flags: UpgradeFlags; path: string }) => Promise<{ failed: boolean }>\n  spawnAgent: (args: { agent: Agent; cwd: string; promptFilePath: string }) => Promise<{\n    code: number\n  }>\n  writePromptFile: (contents: string) => string\n}\n\n/**\n * Bare `upgrade`: pick how to run the full v3 -> v4 upgrade. Hands the\n * orchestration prompt to a detected coding agent, runs the mechanical slice\n * here, or prints the prompt for manual use.\n */\nexport async function runDispatch(\n  { agentFlag, path, upgradeFlags }: RunDispatchArgs,\n  deps: DispatchDeps = defaultDispatchDeps(),\n): Promise<{ failed: boolean }> {\n  const installed = deps.detectAgents()\n\n  let choice: DispatchChoice\n  try {\n    choice = await selectDispatch({\n      agentFlag,\n      installed,\n      isInteractive: deps.isInteractive,\n      prompt: deps.promptChoice,\n    })\n  } catch (err) {\n    console.error(err instanceof Error ? err.message : String(err))\n    return { failed: true }\n  }\n\n  if (choice.kind === 'run') {\n    return deps.runMechanical({ flags: upgradeFlags, path })\n  }\n\n  const promptText = deps.renderPrompt()\n\n  if (choice.kind === 'print') {\n    console.log(promptText)\n    return { failed: false }\n  }\n\n  const promptFilePath = deps.writePromptFile(promptText)\n  console.log(`Handing the upgrade prompt to ${choice.agent.label}...`)\n  const { code } = await deps.spawnAgent({\n    agent: choice.agent,\n    cwd: resolve(path),\n    promptFilePath,\n  })\n  return { failed: code !== 0 }\n}\n\nfunction defaultDispatchDeps(): DispatchDeps {\n  return {\n    detectAgents: detectInstalledAgents,\n    isInteractive: Boolean(process.stdin.isTTY && process.stdout.isTTY),\n    promptChoice: promptChoiceFromTerminal,\n    renderPrompt: () => renderUpgradePrompt({ command: resolveSelfCommand() }),\n    runMechanical: (args) => runUpgrade(args),\n    spawnAgent: spawnAgentInteractive,\n    writePromptFile: (contents) => {\n      const dir = mkdtempSync(join(tmpdir(), 'payload-v4-upgrade-'))\n      const filePath = join(dir, 'prompt.md')\n      writeFileSync(filePath, contents)\n      return filePath\n    },\n  }\n}\n\n/** Clack select: each installed agent, then run the slice or print the prompt. */\nasync function promptChoiceFromTerminal(agents: Agent[]): Promise<DispatchChoice> {\n  p.intro('Payload v3 -> v4 upgrade')\n  const selection = await p.select({\n    message: 'How do you want to run it?',\n    options: [\n      ...agents.map((agent) => ({\n        hint: `hand the prompt to \\`${agent.command}\\``,\n        label: agent.label,\n        value: agent.id,\n      })),\n      {\n        hint: 'pin versions, install, run the codemods now',\n        label: 'Run the mechanical steps',\n        value: 'run',\n      },\n      {\n        hint: 'run it yourself or paste it elsewhere',\n        label: 'Just print the prompt',\n        value: 'print',\n      },\n    ],\n  })\n\n  // Cancelling (Ctrl-C) falls back to printing the prompt so the user keeps it.\n  if (p.isCancel(selection)) {\n    return { kind: 'print' }\n  }\n  if (selection === 'run') {\n    return { kind: 'run' }\n  }\n  const agent = agents.find((a) => a.id === selection)\n  return agent ? { agent, kind: 'agent' } : { kind: 'print' }\n}\n\n/** Interactive agent session seeded with a one-line pointer to the prompt file. */\nfunction spawnAgentInteractive({\n  agent,\n  cwd,\n  promptFilePath,\n}: {\n  agent: Agent\n  cwd: string\n  promptFilePath: string\n}): Promise<{ code: number }> {\n  const launchPrompt = `Read ${promptFilePath} and follow it to upgrade this project from Payload v3 to v4.`\n  return new Promise((resolveSpawn) => {\n    const child = spawn(agent.command, [launchPrompt], { cwd, shell: false, stdio: 'inherit' })\n    child.on('close', (code) => resolveSpawn({ code: code ?? 1 }))\n    child.on('error', () => resolveSpawn({ code: 1 }))\n  })\n}\n"],"names":["p","spawn","mkdtempSync","writeFileSync","tmpdir","join","resolve","runUpgrade","renderUpgradePrompt","detectInstalledAgents","selectDispatch","resolveSelfCommand","runDispatch","agentFlag","path","upgradeFlags","deps","defaultDispatchDeps","installed","detectAgents","choice","isInteractive","prompt","promptChoice","err","console","error","Error","message","String","failed","kind","runMechanical","flags","promptText","renderPrompt","log","promptFilePath","writePromptFile","agent","label","code","spawnAgent","cwd","Boolean","process","stdin","isTTY","stdout","promptChoiceFromTerminal","command","args","spawnAgentInteractive","contents","dir","filePath","agents","intro","selection","select","options","map","hint","value","id","isCancel","find","a","launchPrompt","Promise","resolveSpawn","child","shell","stdio","on"],"mappings":"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"}

package/dist/upgrade/index.d.ts

@@ -3,7 +3,8 @@ import { runTransforms as defaultRunTransforms } from '../runner.js';
 export type UpgradeFlags = {
     dry: boolean;
     force: boolean;
-    tag: string;
+    /** Explicit --tag; when absent the default is derived from the running version. */
+    tag?: string;
 };
 type RunUpgradeArgs = {
     flags: UpgradeFlags;

package/dist/upgrade/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upgrade/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAuC,WAAW,EAAE,MAAM,YAAY,CAAA;AAGlF,OAAO,EAAE,aAAa,IAAI,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAUpE,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,OAAO,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,YAAY,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,mBAAmB,GAAG;IACzB,aAAa,CAAC,EAAE,OAAO,oBAAoB,CAAA;CAC5C,CAAA;AAsBD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,cAAc,EAC/B,IAAI,GAAE,WAA2B,EACjC,SAAS,GAAE,mBAAwB,GAClC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CAqF9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/upgrade/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAuC,WAAW,EAAE,MAAM,YAAY,CAAA;AAGlF,OAAO,EAAE,aAAa,IAAI,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAepE,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,OAAO,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,YAAY,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,mBAAmB,GAAG;IACzB,aAAa,CAAC,EAAE,OAAO,oBAAoB,CAAA;CAC5C,CAAA;AAmBD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,cAAc,EAC/B,IAAI,GAAE,WAA2B,EACjC,SAAS,GAAE,mBAAwB,GAClC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,CA6F9B"}

package/dist/upgrade/index.js

@@ -1,4 +1,5 @@
-/* eslint-disable no-console */ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+/* eslint-disable no-console */ import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import semver from 'semver';
@@ -6,12 +7,13 @@ import { transforms as registry } from '../registry.js';
 import { runTransforms as defaultRunTransforms } from '../runner.js';
 import { loadPackageJsons, serializePackageJson } from '../utils/packageJson.js';
 import { loadProject } from '../utils/project.js';
+import { resolveDefaultTag } from './defaultTag.js';
 import { detectPackageManager } from './detectPackageManager.js';
 import { renderReport } from './report.js';
 import { resolveVersions } from './resolveVersions.js';
-import { isPayloadEslintPackage, rewritePackageJson } from './rewritePackageJson.js';
+import { isPayloadEslintPackage, isPlaceholderSpec, rewritePackageJson } from './rewritePackageJson.js';
 import { runInstall } from './runInstall.js';
-import { RUNBOOK_RELATIVE_PATH } from './types.js';
+import { MIGRATION_GUIDE_RELATIVE_PATH, RUNBOOK_RELATIVE_PATH } from './types.js';
 const defaultDeps = ()=>({
         exists: existsSync,
         fetchRegistry: async (name)=>{
@@ -21,19 +23,19 @@ const defaultDeps = ()=>({
             }
             return await res.json();
         },
-        spawn: (command, args, options)=>import('node:child_process').then(({ spawn })=>new Promise((resolveSpawn)=>{
-                    const child = spawn(command, args, {
-                        ...options,
-                        shell: false,
-                        stdio: 'inherit'
-                    });
-                    child.on('close', (code)=>resolveSpawn({
-                            code: code ?? 1
-                        }));
-                    child.on('error', ()=>resolveSpawn({
-                            code: 1
-                        }));
-                }))
+        spawn: (command, args, options)=>new Promise((resolveSpawn)=>{
+                const child = spawn(command, args, {
+                    ...options,
+                    shell: false,
+                    stdio: 'inherit'
+                });
+                child.on('close', (code)=>resolveSpawn({
+                        code: code ?? 1
+                    }));
+                child.on('error', ()=>resolveSpawn({
+                        code: 1
+                    }));
+            })
     });
 /**
  * Compose the upgrade pipeline: preflight -> resolve -> rewrite -> install ->
@@ -55,9 +57,10 @@ const defaultDeps = ()=>({
         console.warn('Warning: git tree is dirty. Commit or stash first, or pass --force.');
     }
     // 2. RESOLVE VERSIONS
+    const tag = flags.tag ?? resolveDefaultTag();
     const resolved = await resolveVersions({
         fetchRegistry: deps.fetchRegistry,
-        tag: flags.tag
+        tag
     });
     warnStaleNode(resolved);
     // 3. REWRITE package.json
@@ -118,17 +121,24 @@ const defaultDeps = ()=>({
         }
     }
     // 7. REPORT
+    const distDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+    const migrationGuideAbsPath = join(distDir, MIGRATION_GUIDE_RELATIVE_PATH);
     const model = {
         floorsWritten: summary.floorsWritten,
+        migrationGuidePath: deps.exists(migrationGuideAbsPath) ? migrationGuideAbsPath : undefined,
         nextTarget: resolved.nextTarget,
         overridesRemoved: summary.overridesRemoved,
-        runbookPath: resolve(dirname(fileURLToPath(import.meta.url)), '..', RUNBOOK_RELATIVE_PATH),
+        placeholdersSkipped: summary.placeholdersSkipped,
+        runbookPath: join(distDir, RUNBOOK_RELATIVE_PATH),
         transforms: results,
         versions
     };
     console.log(renderReport(model));
+    // A resolution mismatch means the installed tree is not confirmed v4, so the
+    // run failed even when every transform succeeded (resolution over intent).
+    const resolutionFailed = versions.some((v)=>!v.ok);
     return {
-        failed
+        failed: failed || resolutionFailed
     };
 }
 function warnStaleNode(resolved) {
@@ -152,6 +162,11 @@ function verifyResolution(projectPath, data, resolved) {
         if (isPayloadEslintPackage(name)) {
             continue;
         }
+        // Workspace/catalog/link specs were left unpinned, so there is no exact
+        // version to verify against.
+        if (isPlaceholderSpec(deps[name])) {
+            continue;
+        }
         const installed = readInstalledVersion(projectPath, name);
         rows.push({
             name,
@@ -171,11 +186,21 @@ function readInstalledVersion(projectPath, name) {
     }
 }
 /**
- * Best-effort dirty-tree check. Real detection would shell out to `git
- * status`; until that lands, absence of a signal is treated as clean so the
- * warning never produces a false alarm.
- */ function isGitTreeDirty(_projectPath) {
-    return false;
+ * Best-effort dirty-tree check via `git status --porcelain`. Any failure (not a
+ * repo, git missing) yields no signal and is treated as clean, so the warning
+ * never produces a false alarm outside a working git tree.
+ */ function isGitTreeDirty(projectPath) {
+    const result = spawnSync('git', [
+        'status',
+        '--porcelain'
+    ], {
+        cwd: projectPath,
+        encoding: 'utf8'
+    });
+    if (result.error || result.status !== 0) {
+        return false;
+    }
+    return result.stdout.trim().length > 0;
 }
 function asRecord(value) {
     return typeof value === 'object' && value !== null ? value : {};

package/dist/upgrade/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/upgrade/index.ts"],"sourcesContent":["/* eslint-disable no-console */\nimport { existsSync, readFileSync, writeFileSync } from 'node:fs'\nimport { dirname, join, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport semver from 'semver'\n\nimport type { ReportModel, VersionReportRow } from './report.js'\nimport type { RegistryPackument, ResolvedVersions, UpgradeDeps } from './types.js'\n\nimport { transforms as registry } from '../registry.js'\nimport { runTransforms as defaultRunTransforms } from '../runner.js'\nimport { loadPackageJsons, serializePackageJson } from '../utils/packageJson.js'\nimport { loadProject } from '../utils/project.js'\nimport { detectPackageManager } from './detectPackageManager.js'\nimport { renderReport } from './report.js'\nimport { resolveVersions } from './resolveVersions.js'\nimport { isPayloadEslintPackage, rewritePackageJson } from './rewritePackageJson.js'\nimport { runInstall } from './runInstall.js'\nimport { RUNBOOK_RELATIVE_PATH } from './types.js'\n\nexport type UpgradeFlags = {\n  dry: boolean\n  force: boolean\n  tag: string\n}\n\ntype RunUpgradeArgs = {\n  flags: UpgradeFlags\n  path: string\n}\n\ntype RunUpgradeOverrides = {\n  runTransforms?: typeof defaultRunTransforms\n}\n\nconst defaultDeps = (): UpgradeDeps => ({\n  exists: existsSync,\n  fetchRegistry: async (name) => {\n    const res = await fetch(`https://registry.npmjs.org/${name}`)\n    if (!res.ok) {\n      throw new Error(`Registry lookup failed for ${name}: ${res.status}`)\n    }\n    return (await res.json()) as RegistryPackument\n  },\n  spawn: (command, args, options) =>\n    import('node:child_process').then(\n      ({ spawn }) =>\n        new Promise((resolveSpawn) => {\n          const child = spawn(command, args, { ...options, shell: false, stdio: 'inherit' })\n          child.on('close', (code) => resolveSpawn({ code: code ?? 1 }))\n          child.on('error', () => resolveSpawn({ code: 1 }))\n        }),\n    ),\n})\n\n/**\n * Compose the upgrade pipeline: preflight -> resolve -> rewrite -> install ->\n * verify -> transforms -> report. Install runs before transforms so a failed\n * install aborts before any codemod touches source files.\n */\nexport async function runUpgrade(\n  { flags, path }: RunUpgradeArgs,\n  deps: UpgradeDeps = defaultDeps(),\n  overrides: RunUpgradeOverrides = {},\n): Promise<{ failed: boolean }> {\n  const runTransforms = overrides.runTransforms ?? defaultRunTransforms\n  const projectPath = resolve(path)\n\n  // 1. PREFLIGHT\n  const packageManager = detectPackageManager(projectPath, deps.exists)\n  const packageJsonPath = join(projectPath, 'package.json')\n  if (!deps.exists(packageJsonPath)) {\n    console.error(`No package.json found at ${packageJsonPath}.`)\n    return { failed: true }\n  }\n  if (!flags.force && isGitTreeDirty(projectPath)) {\n    console.warn('Warning: git tree is dirty. Commit or stash first, or pass --force.')\n  }\n\n  // 2. RESOLVE VERSIONS\n  const resolved = await resolveVersions({ fetchRegistry: deps.fetchRegistry, tag: flags.tag })\n  warnStaleNode(resolved)\n\n  // 3. REWRITE package.json\n  const original = readFileSync(packageJsonPath, 'utf8')\n  const data = JSON.parse(original) as Record<string, unknown>\n  const summary = rewritePackageJson({ data, resolved })\n  const nextText = serializePackageJson(data, original)\n\n  if (flags.dry) {\n    console.log('[dry] package.json changes:')\n    console.log(nextText)\n    console.log(`[dry] would run: ${packageManager} install`)\n    console.log('[dry] would then run Payload transforms.')\n    return { failed: false }\n  }\n\n  writeFileSync(packageJsonPath, nextText)\n\n  // 4. INSTALL\n  const install = await runInstall({ packageManager, path: projectPath, spawn: deps.spawn })\n  if (install.code !== 0) {\n    console.error(`Install failed (exit ${install.code}). Aborting before transforms.`)\n    return { failed: true }\n  }\n\n  // 5. VERIFY RESOLUTION\n  const versions = verifyResolution(projectPath, data, resolved)\n\n  // 6. RUN PAYLOAD TRANSFORMS\n  // Reload package.jsons from disk so transforms see the rewritten root file\n  // (and any other package.json files in the tree) with the same reference\n  // semantics the bare transform path relies on for in-place mutation.\n  const packageJsons = loadPackageJsons(projectPath)\n  const project = loadProject(projectPath)\n  const snapshot = new Map(project.getSourceFiles().map((f) => [f.getFilePath(), f.getFullText()]))\n  const { failed, results } = await runTransforms({\n    packageJsons: packageJsons.map(({ data: pkgData, path: pkgPath }) => ({\n      data: pkgData,\n      path: pkgPath,\n    })),\n    project,\n    transforms: registry,\n  })\n  await Promise.all(\n    project\n      .getSourceFiles()\n      .filter((f) => snapshot.get(f.getFilePath()) !== f.getFullText())\n      .map((f) => f.save()),\n  )\n  for (const pkg of packageJsons) {\n    const text = serializePackageJson(pkg.data, pkg.originalText)\n    if (text !== pkg.originalText) {\n      writeFileSync(pkg.path, text)\n    }\n  }\n\n  // 7. REPORT\n  const model: ReportModel = {\n    floorsWritten: summary.floorsWritten,\n    nextTarget: resolved.nextTarget,\n    overridesRemoved: summary.overridesRemoved,\n    runbookPath: resolve(dirname(fileURLToPath(import.meta.url)), '..', RUNBOOK_RELATIVE_PATH),\n    transforms: results,\n    versions,\n  }\n  console.log(renderReport(model))\n\n  return { failed }\n}\n\nfunction warnStaleNode(resolved: ResolvedVersions): void {\n  const running = process.versions.node\n  if (!semver.satisfies(running, resolved.enginesNode)) {\n    console.warn(\n      `Warning: running Node ${running} does not satisfy ${resolved.enginesNode}. ` +\n        'Install may resolve incorrectly; switch Node before continuing.',\n    )\n  }\n}\n\nfunction verifyResolution(\n  projectPath: string,\n  data: Record<string, unknown>,\n  resolved: ResolvedVersions,\n): VersionReportRow[] {\n  const rows: VersionReportRow[] = []\n  const deps = { ...asRecord(data.dependencies), ...asRecord(data.devDependencies) }\n  for (const name of Object.keys(deps)) {\n    if (name !== 'payload' && !name.startsWith('@payloadcms/')) {\n      continue\n    }\n    // eslint packages are versioned independently, so they are not part of the\n    // lockstep-pinned set and cannot be verified against the payload version.\n    if (isPayloadEslintPackage(name)) {\n      continue\n    }\n    const installed = readInstalledVersion(projectPath, name)\n    rows.push({\n      name,\n      ok: installed === resolved.payloadVersion,\n      resolved: installed,\n      wrote: resolved.payloadVersion,\n    })\n  }\n  return rows\n}\n\nfunction readInstalledVersion(projectPath: string, name: string): string | undefined {\n  try {\n    const pkgPath = join(projectPath, 'node_modules', name, 'package.json')\n    return JSON.parse(readFileSync(pkgPath, 'utf8')).version as string\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Best-effort dirty-tree check. Real detection would shell out to `git\n * status`; until that lands, absence of a signal is treated as clean so the\n * warning never produces a false alarm.\n */\nfunction isGitTreeDirty(_projectPath: string): boolean {\n  return false\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> {\n  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {}\n}\n"],"names":["existsSync","readFileSync","writeFileSync","dirname","join","resolve","fileURLToPath","semver","transforms","registry","runTransforms","defaultRunTransforms","loadPackageJsons","serializePackageJson","loadProject","detectPackageManager","renderReport","resolveVersions","isPayloadEslintPackage","rewritePackageJson","runInstall","RUNBOOK_RELATIVE_PATH","defaultDeps","exists","fetchRegistry","name","res","fetch","ok","Error","status","json","spawn","command","args","options","then","Promise","resolveSpawn","child","shell","stdio","on","code","runUpgrade","flags","path","deps","overrides","projectPath","packageManager","packageJsonPath","console","error","failed","force","isGitTreeDirty","warn","resolved","tag","warnStaleNode","original","data","JSON","parse","summary","nextText","dry","log","install","versions","verifyResolution","packageJsons","project","snapshot","Map","getSourceFiles","map","f","getFilePath","getFullText","results","pkgData","pkgPath","all","filter","get","save","pkg","text","originalText","model","floorsWritten","nextTarget","overridesRemoved","runbookPath","url","running","process","node","satisfies","enginesNode","rows","asRecord","dependencies","devDependencies","Object","keys","startsWith","installed","readInstalledVersion","push","payloadVersion","wrote","version","undefined","_projectPath","value"],"mappings":"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"}
+{"version":3,"sources":["../../src/upgrade/index.ts"],"sourcesContent":["/* eslint-disable no-console */\nimport { spawn, spawnSync } from 'node:child_process'\nimport { existsSync, readFileSync, writeFileSync } from 'node:fs'\nimport { dirname, join, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport semver from 'semver'\n\nimport type { ReportModel, VersionReportRow } from './report.js'\nimport type { RegistryPackument, ResolvedVersions, UpgradeDeps } from './types.js'\n\nimport { transforms as registry } from '../registry.js'\nimport { runTransforms as defaultRunTransforms } from '../runner.js'\nimport { loadPackageJsons, serializePackageJson } from '../utils/packageJson.js'\nimport { loadProject } from '../utils/project.js'\nimport { resolveDefaultTag } from './defaultTag.js'\nimport { detectPackageManager } from './detectPackageManager.js'\nimport { renderReport } from './report.js'\nimport { resolveVersions } from './resolveVersions.js'\nimport {\n  isPayloadEslintPackage,\n  isPlaceholderSpec,\n  rewritePackageJson,\n} from './rewritePackageJson.js'\nimport { runInstall } from './runInstall.js'\nimport { MIGRATION_GUIDE_RELATIVE_PATH, RUNBOOK_RELATIVE_PATH } from './types.js'\n\nexport type UpgradeFlags = {\n  dry: boolean\n  force: boolean\n  /** Explicit --tag; when absent the default is derived from the running version. */\n  tag?: string\n}\n\ntype RunUpgradeArgs = {\n  flags: UpgradeFlags\n  path: string\n}\n\ntype RunUpgradeOverrides = {\n  runTransforms?: typeof defaultRunTransforms\n}\n\nconst defaultDeps = (): UpgradeDeps => ({\n  exists: existsSync,\n  fetchRegistry: async (name) => {\n    const res = await fetch(`https://registry.npmjs.org/${name}`)\n    if (!res.ok) {\n      throw new Error(`Registry lookup failed for ${name}: ${res.status}`)\n    }\n    return (await res.json()) as RegistryPackument\n  },\n  spawn: (command, args, options) =>\n    new Promise((resolveSpawn) => {\n      const child = spawn(command, args, { ...options, shell: false, stdio: 'inherit' })\n      child.on('close', (code) => resolveSpawn({ code: code ?? 1 }))\n      child.on('error', () => resolveSpawn({ code: 1 }))\n    }),\n})\n\n/**\n * Compose the upgrade pipeline: preflight -> resolve -> rewrite -> install ->\n * verify -> transforms -> report. Install runs before transforms so a failed\n * install aborts before any codemod touches source files.\n */\nexport async function runUpgrade(\n  { flags, path }: RunUpgradeArgs,\n  deps: UpgradeDeps = defaultDeps(),\n  overrides: RunUpgradeOverrides = {},\n): Promise<{ failed: boolean }> {\n  const runTransforms = overrides.runTransforms ?? defaultRunTransforms\n  const projectPath = resolve(path)\n\n  // 1. PREFLIGHT\n  const packageManager = detectPackageManager(projectPath, deps.exists)\n  const packageJsonPath = join(projectPath, 'package.json')\n  if (!deps.exists(packageJsonPath)) {\n    console.error(`No package.json found at ${packageJsonPath}.`)\n    return { failed: true }\n  }\n  if (!flags.force && isGitTreeDirty(projectPath)) {\n    console.warn('Warning: git tree is dirty. Commit or stash first, or pass --force.')\n  }\n\n  // 2. RESOLVE VERSIONS\n  const tag = flags.tag ?? resolveDefaultTag()\n  const resolved = await resolveVersions({ fetchRegistry: deps.fetchRegistry, tag })\n  warnStaleNode(resolved)\n\n  // 3. REWRITE package.json\n  const original = readFileSync(packageJsonPath, 'utf8')\n  const data = JSON.parse(original) as Record<string, unknown>\n  const summary = rewritePackageJson({ data, resolved })\n  const nextText = serializePackageJson(data, original)\n\n  if (flags.dry) {\n    console.log('[dry] package.json changes:')\n    console.log(nextText)\n    console.log(`[dry] would run: ${packageManager} install`)\n    console.log('[dry] would then run Payload transforms.')\n    return { failed: false }\n  }\n\n  writeFileSync(packageJsonPath, nextText)\n\n  // 4. INSTALL\n  const install = await runInstall({ packageManager, path: projectPath, spawn: deps.spawn })\n  if (install.code !== 0) {\n    console.error(`Install failed (exit ${install.code}). Aborting before transforms.`)\n    return { failed: true }\n  }\n\n  // 5. VERIFY RESOLUTION\n  const versions = verifyResolution(projectPath, data, resolved)\n\n  // 6. RUN PAYLOAD TRANSFORMS\n  // Reload package.jsons from disk so transforms see the rewritten root file\n  // (and any other package.json files in the tree) with the same reference\n  // semantics the bare transform path relies on for in-place mutation.\n  const packageJsons = loadPackageJsons(projectPath)\n  const project = loadProject(projectPath)\n  const snapshot = new Map(project.getSourceFiles().map((f) => [f.getFilePath(), f.getFullText()]))\n  const { failed, results } = await runTransforms({\n    packageJsons: packageJsons.map(({ data: pkgData, path: pkgPath }) => ({\n      data: pkgData,\n      path: pkgPath,\n    })),\n    project,\n    transforms: registry,\n  })\n  await Promise.all(\n    project\n      .getSourceFiles()\n      .filter((f) => snapshot.get(f.getFilePath()) !== f.getFullText())\n      .map((f) => f.save()),\n  )\n  for (const pkg of packageJsons) {\n    const text = serializePackageJson(pkg.data, pkg.originalText)\n    if (text !== pkg.originalText) {\n      writeFileSync(pkg.path, text)\n    }\n  }\n\n  // 7. REPORT\n  const distDir = resolve(dirname(fileURLToPath(import.meta.url)), '..')\n  const migrationGuideAbsPath = join(distDir, MIGRATION_GUIDE_RELATIVE_PATH)\n  const model: ReportModel = {\n    floorsWritten: summary.floorsWritten,\n    migrationGuidePath: deps.exists(migrationGuideAbsPath) ? migrationGuideAbsPath : undefined,\n    nextTarget: resolved.nextTarget,\n    overridesRemoved: summary.overridesRemoved,\n    placeholdersSkipped: summary.placeholdersSkipped,\n    runbookPath: join(distDir, RUNBOOK_RELATIVE_PATH),\n    transforms: results,\n    versions,\n  }\n  console.log(renderReport(model))\n\n  // A resolution mismatch means the installed tree is not confirmed v4, so the\n  // run failed even when every transform succeeded (resolution over intent).\n  const resolutionFailed = versions.some((v) => !v.ok)\n  return { failed: failed || resolutionFailed }\n}\n\nfunction warnStaleNode(resolved: ResolvedVersions): void {\n  const running = process.versions.node\n  if (!semver.satisfies(running, resolved.enginesNode)) {\n    console.warn(\n      `Warning: running Node ${running} does not satisfy ${resolved.enginesNode}. ` +\n        'Install may resolve incorrectly; switch Node before continuing.',\n    )\n  }\n}\n\nfunction verifyResolution(\n  projectPath: string,\n  data: Record<string, unknown>,\n  resolved: ResolvedVersions,\n): VersionReportRow[] {\n  const rows: VersionReportRow[] = []\n  const deps = { ...asRecord(data.dependencies), ...asRecord(data.devDependencies) }\n  for (const name of Object.keys(deps)) {\n    if (name !== 'payload' && !name.startsWith('@payloadcms/')) {\n      continue\n    }\n    // eslint packages are versioned independently, so they are not part of the\n    // lockstep-pinned set and cannot be verified against the payload version.\n    if (isPayloadEslintPackage(name)) {\n      continue\n    }\n    // Workspace/catalog/link specs were left unpinned, so there is no exact\n    // version to verify against.\n    if (isPlaceholderSpec(deps[name])) {\n      continue\n    }\n    const installed = readInstalledVersion(projectPath, name)\n    rows.push({\n      name,\n      ok: installed === resolved.payloadVersion,\n      resolved: installed,\n      wrote: resolved.payloadVersion,\n    })\n  }\n  return rows\n}\n\nfunction readInstalledVersion(projectPath: string, name: string): string | undefined {\n  try {\n    const pkgPath = join(projectPath, 'node_modules', name, 'package.json')\n    return JSON.parse(readFileSync(pkgPath, 'utf8')).version as string\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Best-effort dirty-tree check via `git status --porcelain`. Any failure (not a\n * repo, git missing) yields no signal and is treated as clean, so the warning\n * never produces a false alarm outside a working git tree.\n */\nfunction isGitTreeDirty(projectPath: string): boolean {\n  const result = spawnSync('git', ['status', '--porcelain'], {\n    cwd: projectPath,\n    encoding: 'utf8',\n  })\n  if (result.error || result.status !== 0) {\n    return false\n  }\n  return result.stdout.trim().length > 0\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> {\n  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {}\n}\n"],"names":["spawn","spawnSync","existsSync","readFileSync","writeFileSync","dirname","join","resolve","fileURLToPath","semver","transforms","registry","runTransforms","defaultRunTransforms","loadPackageJsons","serializePackageJson","loadProject","resolveDefaultTag","detectPackageManager","renderReport","resolveVersions","isPayloadEslintPackage","isPlaceholderSpec","rewritePackageJson","runInstall","MIGRATION_GUIDE_RELATIVE_PATH","RUNBOOK_RELATIVE_PATH","defaultDeps","exists","fetchRegistry","name","res","fetch","ok","Error","status","json","command","args","options","Promise","resolveSpawn","child","shell","stdio","on","code","runUpgrade","flags","path","deps","overrides","projectPath","packageManager","packageJsonPath","console","error","failed","force","isGitTreeDirty","warn","tag","resolved","warnStaleNode","original","data","JSON","parse","summary","nextText","dry","log","install","versions","verifyResolution","packageJsons","project","snapshot","Map","getSourceFiles","map","f","getFilePath","getFullText","results","pkgData","pkgPath","all","filter","get","save","pkg","text","originalText","distDir","url","migrationGuideAbsPath","model","floorsWritten","migrationGuidePath","undefined","nextTarget","overridesRemoved","placeholdersSkipped","runbookPath","resolutionFailed","some","v","running","process","node","satisfies","enginesNode","rows","asRecord","dependencies","devDependencies","Object","keys","startsWith","installed","readInstalledVersion","push","payloadVersion","wrote","version","result","cwd","encoding","stdout","trim","length","value"],"mappings":"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"}

package/dist/upgrade/prompt.d.ts

@@ -4,8 +4,11 @@
  * gates, runs this package's `upgrade` command for the deterministic slice,
  * delegates Next.js to Next's own agent workflow, and points at the migration
  * guide for the judgment work rather than restating any of it. The text is
- * static and project-agnostic — the agent runs it from the project root. Pure:
- * the caller prints it.
+ * project-agnostic (the agent runs it from the project root). `command` is the
+ * token that re-invokes this CLI, so a local checkout points followers at the
+ * local build instead of the published package. Pure: the caller prints it.
  */
-export declare function renderUpgradePrompt(): string;
+export declare function renderUpgradePrompt({ command, }?: {
+    command?: string;
+}): string;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/upgrade/prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/upgrade/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAgE5C"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/upgrade/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,OAAmC,GACpC,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAiEpC"}

package/dist/upgrade/prompt.js

@@ -4,13 +4,14 @@
  * gates, runs this package's `upgrade` command for the deterministic slice,
  * delegates Next.js to Next's own agent workflow, and points at the migration
  * guide for the judgment work rather than restating any of it. The text is
- * static and project-agnostic — the agent runs it from the project root. Pure:
- * the caller prints it.
- */ export function renderUpgradePrompt() {
+ * project-agnostic (the agent runs it from the project root). `command` is the
+ * token that re-invokes this CLI, so a local checkout points followers at the
+ * local build instead of the published package. Pure: the caller prints it.
+ */ export function renderUpgradePrompt({ command = 'npx @payloadcms/codemod' } = {}) {
     return `You are upgrading this project from Payload v3 to v4, Next.js 16 included.
 
 Ground rule: resolution over intent. A step is done only when it installs, builds, and boots.
-Never report a task complete because the edit looks right — confirm it. A silent gap reads as
+Never report a task complete because the edit looks right. Confirm it. A silent gap reads as
 "checked and fine".
 
 ## 0. Preconditions
@@ -27,15 +28,16 @@ Do not proceed to step 2 until these are complete and committed.
 ## 2. Payload mechanical slice
 Run this from the project root:
 
-    npx @payloadcms/codemod upgrade .
+    ${command} upgrade run
 
-Add \`--tag <dist-tag>\` to resolve Payload from a non-default dist-tag (default is \`canary\`).
+By default it resolves Payload from the dist-tag this CLI was installed under (\`beta\` when you
+ran \`@payloadcms/codemod@beta\`, else \`canary\`). Add \`--tag <dist-tag>\` to pin a specific one.
 This pins the Payload packages to v4, removes conflicting overrides, writes the toolchain
 floors, installs, and runs the AST transforms. Read its report:
 - It prints the resolved payload version, the required Next target, and the path to the
   bundled runbook and migration guide. Use those paths below.
 - The unmet \`@payloadcms/next\` peer against Next 15 is EXPECTED at this point. Do NOT downgrade
-  payload to satisfy it — step 3 resolves it by upgrading Next.
+  payload to satisfy it; step 3 resolves it by upgrading Next.
 - Do not hand-edit the versions it pinned.
 
 ## 3. Next.js 16 (delegate to Next's workflow)
@@ -50,12 +52,12 @@ afterward so the \`@payloadcms/next\` peer resolves.
 
 ## 4. Regenerate generated files
 \`payload generate:types && payload generate:importmap\`. Never hand-edit \`payload-types.ts\` or
-\`importMap.js\` — regenerate them.
+\`importMap.js\`; regenerate them.
 
 ## 5. Fix-forward judgment work (against the now-v4 tree)
 These depend on the v4 APIs and types existing, so they follow the upgrade. Open the bundled
 migration guide (\`v4.mdx\`, path printed in step 2) and the bundled runbook
-(\`runbook/payload-v4-upgrade.md\`) and work the items they list — SCSS -> CSS and \`--theme-*\` ->
+(\`runbook/payload-v4-upgrade.md\`) and work the items they list: SCSS -> CSS and \`--theme-*\` ->
 \`--color-*\` token renames, Lexical union type-narrowing, jobs DB migrations, strict cron parsing,
 and anything flagged in the per-transform notes. Consult the guide for each; do not guess from
 memory.

package/dist/upgrade/prompt.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/upgrade/prompt.ts"],"sourcesContent":["/**\n * Render the overarching agent prompt for a full Payload v3 -> v4 upgrade,\n * Next.js 16 included. The prompt is a thin orchestrator: it sequences the\n * gates, runs this package's `upgrade` command for the deterministic slice,\n * delegates Next.js to Next's own agent workflow, and points at the migration\n * guide for the judgment work rather than restating any of it. The text is\n * static and project-agnostic — the agent runs it from the project root. Pure:\n * the caller prints it.\n */\nexport function renderUpgradePrompt(): string {\n  return `You are upgrading this project from Payload v3 to v4, Next.js 16 included.\n\nGround rule: resolution over intent. A step is done only when it installs, builds, and boots.\nNever report a task complete because the edit looks right — confirm it. A silent gap reads as\n\"checked and fine\".\n\n## 0. Preconditions\n- Work on a clean git tree or a fresh branch.\n- Use Node >=24.15 (the exact engines floor is printed by the command in step 2).\n\n## 1. Pre-upgrade migrations (do these on v3, before touching versions)\nSome migrations need the v3 tooling that v4 deletes, so they MUST run before the upgrade:\n- Slate richtext is removed in v4. Migrate Slate -> Lexical while still on v3; the migration path\n  is gone once the packages are pinned to v4.\n\nDo not proceed to step 2 until these are complete and committed.\n\n## 2. Payload mechanical slice\nRun this from the project root:\n\n    npx @payloadcms/codemod upgrade .\n\nAdd \\`--tag <dist-tag>\\` to resolve Payload from a non-default dist-tag (default is \\`canary\\`).\nThis pins the Payload packages to v4, removes conflicting overrides, writes the toolchain\nfloors, installs, and runs the AST transforms. Read its report:\n- It prints the resolved payload version, the required Next target, and the path to the\n  bundled runbook and migration guide. Use those paths below.\n- The unmet \\`@payloadcms/next\\` peer against Next 15 is EXPECTED at this point. Do NOT downgrade\n  payload to satisfy it — step 3 resolves it by upgrading Next.\n- Do not hand-edit the versions it pinned.\n\n## 3. Next.js 16 (delegate to Next's workflow)\nPayload v4 requires Next 16. The command above did not touch Next. Run Next's own recommended\nagent workflow, which bumps Next + React and migrates the code as one unit:\n<https://nextjs.org/docs/app/guides/upgrading/version-16#use-an-ai-agent-recommended>\n\nIn short: run \\`npx @next/codemod@canary upgrade latest\\`, then\n\\`npx @next/codemod@canary next-async-request-api .\\`, and follow Next's AGENTS.md workflow for\nthe rest. Keep the result within the Next target range printed in step 2's report. Reinstall\nafterward so the \\`@payloadcms/next\\` peer resolves.\n\n## 4. Regenerate generated files\n\\`payload generate:types && payload generate:importmap\\`. Never hand-edit \\`payload-types.ts\\` or\n\\`importMap.js\\` — regenerate them.\n\n## 5. Fix-forward judgment work (against the now-v4 tree)\nThese depend on the v4 APIs and types existing, so they follow the upgrade. Open the bundled\nmigration guide (\\`v4.mdx\\`, path printed in step 2) and the bundled runbook\n(\\`runbook/payload-v4-upgrade.md\\`) and work the items they list — SCSS -> CSS and \\`--theme-*\\` ->\n\\`--color-*\\` token renames, Lexical union type-narrowing, jobs DB migrations, strict cron parsing,\nand anything flagged in the per-transform notes. Consult the guide for each; do not guess from\nmemory.\n\n## 6. Verify\n- \\`tsc --noEmit\\` (delete \\`tsconfig.tsbuildinfo\\` first; set \\`checkJs: true\\` so \\`importMap.js\\` is covered).\n- Run integration and e2e tests separately.\n- Build.\n- Confirm native modules (e.g. \\`sharp\\`) still load.\n\n## 7. Report\nDistinguish verified, cannot-confirm, and broken. Do not call the upgrade complete while any\ngate fails or any generated file is stale.\n`\n}\n"],"names":["renderUpgradePrompt"],"mappings":"AAAA;;;;;;;;CAQC,GACD,OAAO,SAASA;IACd,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DV,CAAC;AACD"}
+{"version":3,"sources":["../../src/upgrade/prompt.ts"],"sourcesContent":["/**\n * Render the overarching agent prompt for a full Payload v3 -> v4 upgrade,\n * Next.js 16 included. The prompt is a thin orchestrator: it sequences the\n * gates, runs this package's `upgrade` command for the deterministic slice,\n * delegates Next.js to Next's own agent workflow, and points at the migration\n * guide for the judgment work rather than restating any of it. The text is\n * project-agnostic (the agent runs it from the project root). `command` is the\n * token that re-invokes this CLI, so a local checkout points followers at the\n * local build instead of the published package. Pure: the caller prints it.\n */\nexport function renderUpgradePrompt({\n  command = 'npx @payloadcms/codemod',\n}: { command?: string } = {}): string {\n  return `You are upgrading this project from Payload v3 to v4, Next.js 16 included.\n\nGround rule: resolution over intent. A step is done only when it installs, builds, and boots.\nNever report a task complete because the edit looks right. Confirm it. A silent gap reads as\n\"checked and fine\".\n\n## 0. Preconditions\n- Work on a clean git tree or a fresh branch.\n- Use Node >=24.15 (the exact engines floor is printed by the command in step 2).\n\n## 1. Pre-upgrade migrations (do these on v3, before touching versions)\nSome migrations need the v3 tooling that v4 deletes, so they MUST run before the upgrade:\n- Slate richtext is removed in v4. Migrate Slate -> Lexical while still on v3; the migration path\n  is gone once the packages are pinned to v4.\n\nDo not proceed to step 2 until these are complete and committed.\n\n## 2. Payload mechanical slice\nRun this from the project root:\n\n    ${command} upgrade run\n\nBy default it resolves Payload from the dist-tag this CLI was installed under (\\`beta\\` when you\nran \\`@payloadcms/codemod@beta\\`, else \\`canary\\`). Add \\`--tag <dist-tag>\\` to pin a specific one.\nThis pins the Payload packages to v4, removes conflicting overrides, writes the toolchain\nfloors, installs, and runs the AST transforms. Read its report:\n- It prints the resolved payload version, the required Next target, and the path to the\n  bundled runbook and migration guide. Use those paths below.\n- The unmet \\`@payloadcms/next\\` peer against Next 15 is EXPECTED at this point. Do NOT downgrade\n  payload to satisfy it; step 3 resolves it by upgrading Next.\n- Do not hand-edit the versions it pinned.\n\n## 3. Next.js 16 (delegate to Next's workflow)\nPayload v4 requires Next 16. The command above did not touch Next. Run Next's own recommended\nagent workflow, which bumps Next + React and migrates the code as one unit:\n<https://nextjs.org/docs/app/guides/upgrading/version-16#use-an-ai-agent-recommended>\n\nIn short: run \\`npx @next/codemod@canary upgrade latest\\`, then\n\\`npx @next/codemod@canary next-async-request-api .\\`, and follow Next's AGENTS.md workflow for\nthe rest. Keep the result within the Next target range printed in step 2's report. Reinstall\nafterward so the \\`@payloadcms/next\\` peer resolves.\n\n## 4. Regenerate generated files\n\\`payload generate:types && payload generate:importmap\\`. Never hand-edit \\`payload-types.ts\\` or\n\\`importMap.js\\`; regenerate them.\n\n## 5. Fix-forward judgment work (against the now-v4 tree)\nThese depend on the v4 APIs and types existing, so they follow the upgrade. Open the bundled\nmigration guide (\\`v4.mdx\\`, path printed in step 2) and the bundled runbook\n(\\`runbook/payload-v4-upgrade.md\\`) and work the items they list: SCSS -> CSS and \\`--theme-*\\` ->\n\\`--color-*\\` token renames, Lexical union type-narrowing, jobs DB migrations, strict cron parsing,\nand anything flagged in the per-transform notes. Consult the guide for each; do not guess from\nmemory.\n\n## 6. Verify\n- \\`tsc --noEmit\\` (delete \\`tsconfig.tsbuildinfo\\` first; set \\`checkJs: true\\` so \\`importMap.js\\` is covered).\n- Run integration and e2e tests separately.\n- Build.\n- Confirm native modules (e.g. \\`sharp\\`) still load.\n\n## 7. Report\nDistinguish verified, cannot-confirm, and broken. Do not call the upgrade complete while any\ngate fails or any generated file is stale.\n`\n}\n"],"names":["renderUpgradePrompt","command"],"mappings":"AAAA;;;;;;;;;CASC,GACD,OAAO,SAASA,oBAAoB,EAClCC,UAAU,yBAAyB,EACd,GAAG,CAAC,CAAC;IAC1B,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;IAoBN,EAAEA,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2Cd,CAAC;AACD"}

package/dist/upgrade/report.d.ts

@@ -7,8 +7,11 @@ export type VersionReportRow = {
 };
 export type ReportModel = {
     floorsWritten: string[];
+    /** Absolute path to the bundled migration guide, when it shipped with this build. */
+    migrationGuidePath?: string;
     nextTarget: null | string;
     overridesRemoved: string[];
+    placeholdersSkipped: string[];
     runbookPath: string;
     transforms: TransformRunResult[];
     versions: VersionReportRow[];

package/dist/upgrade/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/upgrade/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,UAAU,EAAE,IAAI,GAAG,MAAM,CAAA;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,kBAAkB,EAAE,CAAA;IAChC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B,CAAA;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA+CvD"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/upgrade/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,UAAU,EAAE,IAAI,GAAG,MAAM,CAAA;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,kBAAkB,EAAE,CAAA;IAChC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B,CAAA;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAyDvD"}

package/dist/upgrade/report.js

@@ -14,6 +14,9 @@
     if (model.overridesRemoved.length > 0) {
         lines.push(`Overrides removed: ${model.overridesRemoved.join(', ')}`, '');
     }
+    if (model.placeholdersSkipped.length > 0) {
+        lines.push(`Left as-is (workspace/catalog/link specs): ${model.placeholdersSkipped.join(', ')}`, '');
+    }
     if (model.floorsWritten.length > 0) {
         lines.push(`Floors written: ${model.floorsWritten.join(', ')}`, '');
     }
@@ -33,8 +36,11 @@
     lines.push(`  Target Next version: ${model.nextTarget ?? '(see @payloadcms/next peer range)'}`);
     lines.push('  The unmet @payloadcms/next peer is expected until you upgrade Next — that is the immediate next step.');
     lines.push('');
-    lines.push('Not done by this command — see the runbook for the remaining steps:');
-    lines.push(`  ${model.runbookPath}`);
+    lines.push('Not done by this command. See these for the remaining steps:');
+    lines.push(`  runbook: ${model.runbookPath}`);
+    if (model.migrationGuidePath) {
+        lines.push(`  migration guide: ${model.migrationGuidePath}`);
+    }
     return lines.join('\n');
 }
 

package/dist/upgrade/report.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/upgrade/report.ts"],"sourcesContent":["import type { TransformRunResult } from '../runner.js'\n\nexport type VersionReportRow = {\n  name: string\n  ok: boolean\n  resolved?: string\n  wrote: string\n}\n\nexport type ReportModel = {\n  floorsWritten: string[]\n  nextTarget: null | string\n  overridesRemoved: string[]\n  runbookPath: string\n  transforms: TransformRunResult[]\n  versions: VersionReportRow[]\n}\n\n/** Build the honest end-of-run report string. Pure — the caller prints it. */\nexport function renderReport(model: ReportModel): string {\n  const lines: string[] = []\n  lines.push('Payload v4 upgrade — mechanical steps complete', '')\n\n  lines.push('Versions written -> resolved')\n  for (const v of model.versions) {\n    const resolved = v.resolved ?? '(unresolved)'\n    lines.push(`  ${v.name}  ${v.wrote} -> ${resolved}  ${v.ok ? 'ok' : 'MISMATCH'}`)\n  }\n  const anyMismatch = model.versions.some((v) => !v.ok)\n  if (anyMismatch) {\n    lines.push('  ! Resolution mismatch — tree is NOT confirmed v4. Investigate before continuing.')\n  }\n  lines.push('')\n\n  if (model.overridesRemoved.length > 0) {\n    lines.push(`Overrides removed: ${model.overridesRemoved.join(', ')}`, '')\n  }\n\n  if (model.floorsWritten.length > 0) {\n    lines.push(`Floors written: ${model.floorsWritten.join(', ')}`, '')\n  }\n\n  lines.push('Transforms')\n  for (const r of model.transforms) {\n    if (r.error) {\n      lines.push(`  [FAIL] ${r.name} — ${r.error.message}`)\n      continue\n    }\n    lines.push(`  [ok] ${r.name} — ${r.filesChanged.length} file(s) changed`)\n    for (const note of r.notes ?? []) {\n      lines.push(`      note: ${note}`)\n    }\n  }\n  lines.push('')\n\n  lines.push('Next.js: not upgraded by this command')\n  lines.push(`  Target Next version: ${model.nextTarget ?? '(see @payloadcms/next peer range)'}`)\n  lines.push(\n    '  The unmet @payloadcms/next peer is expected until you upgrade Next — that is the immediate next step.',\n  )\n  lines.push('')\n\n  lines.push('Not done by this command — see the runbook for the remaining steps:')\n  lines.push(`  ${model.runbookPath}`)\n\n  return lines.join('\\n')\n}\n"],"names":["renderReport","model","lines","push","v","versions","resolved","name","wrote","ok","anyMismatch","some","overridesRemoved","length","join","floorsWritten","r","transforms","error","message","filesChanged","note","notes","nextTarget","runbookPath"],"mappings":"AAkBA,4EAA4E,GAC5E,OAAO,SAASA,aAAaC,KAAkB;IAC7C,MAAMC,QAAkB,EAAE;IAC1BA,MAAMC,IAAI,CAAC,kDAAkD;IAE7DD,MAAMC,IAAI,CAAC;IACX,KAAK,MAAMC,KAAKH,MAAMI,QAAQ,CAAE;QAC9B,MAAMC,WAAWF,EAAEE,QAAQ,IAAI;QAC/BJ,MAAMC,IAAI,CAAC,CAAC,EAAE,EAAEC,EAAEG,IAAI,CAAC,EAAE,EAAEH,EAAEI,KAAK,CAAC,IAAI,EAAEF,SAAS,EAAE,EAAEF,EAAEK,EAAE,GAAG,OAAO,YAAY;IAClF;IACA,MAAMC,cAAcT,MAAMI,QAAQ,CAACM,IAAI,CAAC,CAACP,IAAM,CAACA,EAAEK,EAAE;IACpD,IAAIC,aAAa;QACfR,MAAMC,IAAI,CAAC;IACb;IACAD,MAAMC,IAAI,CAAC;IAEX,IAAIF,MAAMW,gBAAgB,CAACC,MAAM,GAAG,GAAG;QACrCX,MAAMC,IAAI,CAAC,CAAC,mBAAmB,EAAEF,MAAMW,gBAAgB,CAACE,IAAI,CAAC,OAAO,EAAE;IACxE;IAEA,IAAIb,MAAMc,aAAa,CAACF,MAAM,GAAG,GAAG;QAClCX,MAAMC,IAAI,CAAC,CAAC,gBAAgB,EAAEF,MAAMc,aAAa,CAACD,IAAI,CAAC,OAAO,EAAE;IAClE;IAEAZ,MAAMC,IAAI,CAAC;IACX,KAAK,MAAMa,KAAKf,MAAMgB,UAAU,CAAE;QAChC,IAAID,EAAEE,KAAK,EAAE;YACXhB,MAAMC,IAAI,CAAC,CAAC,SAAS,EAAEa,EAAET,IAAI,CAAC,GAAG,EAAES,EAAEE,KAAK,CAACC,OAAO,EAAE;YACpD;QACF;QACAjB,MAAMC,IAAI,CAAC,CAAC,OAAO,EAAEa,EAAET,IAAI,CAAC,GAAG,EAAES,EAAEI,YAAY,CAACP,MAAM,CAAC,gBAAgB,CAAC;QACxE,KAAK,MAAMQ,QAAQL,EAAEM,KAAK,IAAI,EAAE,CAAE;YAChCpB,MAAMC,IAAI,CAAC,CAAC,YAAY,EAAEkB,MAAM;QAClC;IACF;IACAnB,MAAMC,IAAI,CAAC;IAEXD,MAAMC,IAAI,CAAC;IACXD,MAAMC,IAAI,CAAC,CAAC,uBAAuB,EAAEF,MAAMsB,UAAU,IAAI,qCAAqC;IAC9FrB,MAAMC,IAAI,CACR;IAEFD,MAAMC,IAAI,CAAC;IAEXD,MAAMC,IAAI,CAAC;IACXD,MAAMC,IAAI,CAAC,CAAC,EAAE,EAAEF,MAAMuB,WAAW,EAAE;IAEnC,OAAOtB,MAAMY,IAAI,CAAC;AACpB"}
+{"version":3,"sources":["../../src/upgrade/report.ts"],"sourcesContent":["import type { TransformRunResult } from '../runner.js'\n\nexport type VersionReportRow = {\n  name: string\n  ok: boolean\n  resolved?: string\n  wrote: string\n}\n\nexport type ReportModel = {\n  floorsWritten: string[]\n  /** Absolute path to the bundled migration guide, when it shipped with this build. */\n  migrationGuidePath?: string\n  nextTarget: null | string\n  overridesRemoved: string[]\n  placeholdersSkipped: string[]\n  runbookPath: string\n  transforms: TransformRunResult[]\n  versions: VersionReportRow[]\n}\n\n/** Build the honest end-of-run report string. Pure — the caller prints it. */\nexport function renderReport(model: ReportModel): string {\n  const lines: string[] = []\n  lines.push('Payload v4 upgrade — mechanical steps complete', '')\n\n  lines.push('Versions written -> resolved')\n  for (const v of model.versions) {\n    const resolved = v.resolved ?? '(unresolved)'\n    lines.push(`  ${v.name}  ${v.wrote} -> ${resolved}  ${v.ok ? 'ok' : 'MISMATCH'}`)\n  }\n  const anyMismatch = model.versions.some((v) => !v.ok)\n  if (anyMismatch) {\n    lines.push('  ! Resolution mismatch — tree is NOT confirmed v4. Investigate before continuing.')\n  }\n  lines.push('')\n\n  if (model.overridesRemoved.length > 0) {\n    lines.push(`Overrides removed: ${model.overridesRemoved.join(', ')}`, '')\n  }\n\n  if (model.placeholdersSkipped.length > 0) {\n    lines.push(\n      `Left as-is (workspace/catalog/link specs): ${model.placeholdersSkipped.join(', ')}`,\n      '',\n    )\n  }\n\n  if (model.floorsWritten.length > 0) {\n    lines.push(`Floors written: ${model.floorsWritten.join(', ')}`, '')\n  }\n\n  lines.push('Transforms')\n  for (const r of model.transforms) {\n    if (r.error) {\n      lines.push(`  [FAIL] ${r.name} — ${r.error.message}`)\n      continue\n    }\n    lines.push(`  [ok] ${r.name} — ${r.filesChanged.length} file(s) changed`)\n    for (const note of r.notes ?? []) {\n      lines.push(`      note: ${note}`)\n    }\n  }\n  lines.push('')\n\n  lines.push('Next.js: not upgraded by this command')\n  lines.push(`  Target Next version: ${model.nextTarget ?? '(see @payloadcms/next peer range)'}`)\n  lines.push(\n    '  The unmet @payloadcms/next peer is expected until you upgrade Next — that is the immediate next step.',\n  )\n  lines.push('')\n\n  lines.push('Not done by this command. See these for the remaining steps:')\n  lines.push(`  runbook: ${model.runbookPath}`)\n  if (model.migrationGuidePath) {\n    lines.push(`  migration guide: ${model.migrationGuidePath}`)\n  }\n\n  return lines.join('\\n')\n}\n"],"names":["renderReport","model","lines","push","v","versions","resolved","name","wrote","ok","anyMismatch","some","overridesRemoved","length","join","placeholdersSkipped","floorsWritten","r","transforms","error","message","filesChanged","note","notes","nextTarget","runbookPath","migrationGuidePath"],"mappings":"AAqBA,4EAA4E,GAC5E,OAAO,SAASA,aAAaC,KAAkB;IAC7C,MAAMC,QAAkB,EAAE;IAC1BA,MAAMC,IAAI,CAAC,kDAAkD;IAE7DD,MAAMC,IAAI,CAAC;IACX,KAAK,MAAMC,KAAKH,MAAMI,QAAQ,CAAE;QAC9B,MAAMC,WAAWF,EAAEE,QAAQ,IAAI;QAC/BJ,MAAMC,IAAI,CAAC,CAAC,EAAE,EAAEC,EAAEG,IAAI,CAAC,EAAE,EAAEH,EAAEI,KAAK,CAAC,IAAI,EAAEF,SAAS,EAAE,EAAEF,EAAEK,EAAE,GAAG,OAAO,YAAY;IAClF;IACA,MAAMC,cAAcT,MAAMI,QAAQ,CAACM,IAAI,CAAC,CAACP,IAAM,CAACA,EAAEK,EAAE;IACpD,IAAIC,aAAa;QACfR,MAAMC,IAAI,CAAC;IACb;IACAD,MAAMC,IAAI,CAAC;IAEX,IAAIF,MAAMW,gBAAgB,CAACC,MAAM,GAAG,GAAG;QACrCX,MAAMC,IAAI,CAAC,CAAC,mBAAmB,EAAEF,MAAMW,gBAAgB,CAACE,IAAI,CAAC,OAAO,EAAE;IACxE;IAEA,IAAIb,MAAMc,mBAAmB,CAACF,MAAM,GAAG,GAAG;QACxCX,MAAMC,IAAI,CACR,CAAC,2CAA2C,EAAEF,MAAMc,mBAAmB,CAACD,IAAI,CAAC,OAAO,EACpF;IAEJ;IAEA,IAAIb,MAAMe,aAAa,CAACH,MAAM,GAAG,GAAG;QAClCX,MAAMC,IAAI,CAAC,CAAC,gBAAgB,EAAEF,MAAMe,aAAa,CAACF,IAAI,CAAC,OAAO,EAAE;IAClE;IAEAZ,MAAMC,IAAI,CAAC;IACX,KAAK,MAAMc,KAAKhB,MAAMiB,UAAU,CAAE;QAChC,IAAID,EAAEE,KAAK,EAAE;YACXjB,MAAMC,IAAI,CAAC,CAAC,SAAS,EAAEc,EAAEV,IAAI,CAAC,GAAG,EAAEU,EAAEE,KAAK,CAACC,OAAO,EAAE;YACpD;QACF;QACAlB,MAAMC,IAAI,CAAC,CAAC,OAAO,EAAEc,EAAEV,IAAI,CAAC,GAAG,EAAEU,EAAEI,YAAY,CAACR,MAAM,CAAC,gBAAgB,CAAC;QACxE,KAAK,MAAMS,QAAQL,EAAEM,KAAK,IAAI,EAAE,CAAE;YAChCrB,MAAMC,IAAI,CAAC,CAAC,YAAY,EAAEmB,MAAM;QAClC;IACF;IACApB,MAAMC,IAAI,CAAC;IAEXD,MAAMC,IAAI,CAAC;IACXD,MAAMC,IAAI,CAAC,CAAC,uBAAuB,EAAEF,MAAMuB,UAAU,IAAI,qCAAqC;IAC9FtB,MAAMC,IAAI,CACR;IAEFD,MAAMC,IAAI,CAAC;IAEXD,MAAMC,IAAI,CAAC;IACXD,MAAMC,IAAI,CAAC,CAAC,WAAW,EAAEF,MAAMwB,WAAW,EAAE;IAC5C,IAAIxB,MAAMyB,kBAAkB,EAAE;QAC5BxB,MAAMC,IAAI,CAAC,CAAC,mBAAmB,EAAEF,MAAMyB,kBAAkB,EAAE;IAC7D;IAEA,OAAOxB,MAAMY,IAAI,CAAC;AACpB"}

package/dist/upgrade/rewritePackageJson.d.ts

@@ -7,6 +7,7 @@ export type RewriteSummary = {
     floorsWritten: string[];
     overridesRemoved: string[];
     pinnedPayload: string[];
+    placeholdersSkipped: string[];
 };
 export declare const isPayloadPackage: (name: string) => boolean;
 /**
@@ -14,6 +15,12 @@ export declare const isPayloadPackage: (name: string) => boolean;
  * payload packages, so they are tracked on `latest` rather than lockstep-pinned.
  */
 export declare const isPayloadEslintPackage: (name: string) => boolean;
+/**
+ * A dependency whose version is resolved by the package manager, not a semver
+ * range: `workspace:*`, `catalog:`, `link:`, `file:`, `npm:` aliases, URLs.
+ * Overwriting one with an exact version would break the link, so it is left as-is.
+ */
+export declare const isPlaceholderSpec: (spec: unknown) => boolean;
 /**
  * Mutate `data` in place for a v4 upgrade: exact-pin payload packages, drop
  * payload dependency overrides, and write the toolchain floors. Never touches

package/dist/upgrade/rewritePackageJson.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rewritePackageJson.d.ts","sourceRoot":"","sources":["../../src/upgrade/rewritePackageJson.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,QAAQ,EAAE,gBAAgB,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAA;CACxB,CAAA;AAID,eAAO,MAAM,gBAAgB,SAAU,MAAM,KAAG,OACO,CAAA;AAEvD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,SAAU,MAAM,KAAG,OACf,CAAA;AAEvC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,GAAG,cAAc,CAKlF"}
+{"version":3,"file":"rewritePackageJson.d.ts","sourceRoot":"","sources":["../../src/upgrade/rewritePackageJson.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,QAAQ,EAAE,gBAAgB,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,mBAAmB,EAAE,MAAM,EAAE,CAAA;CAC9B,CAAA;AAOD,eAAO,MAAM,gBAAgB,SAAU,MAAM,KAAG,OACO,CAAA;AAEvD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,SAAU,MAAM,KAAG,OACf,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,SAAU,OAAO,KAAG,OACO,CAAA;AAEzD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,WAAW,GAAG,cAAc,CAKlF"}