@payloadcms/codemod 4.0.0-internal.167c7cd → 4.0.0-internal.2f0d313

package/README.md

@@ -19,6 +19,40 @@ With no arguments, runs every registered transform against the current directory
 - `--dry` — analyze only; write nothing.
 - `--print` — print transformed sources to stdout instead of writing.
 
+## `upgrade` command
+
+`npx @payloadcms/codemod upgrade [path]` performs the mechanical v3 -> v4 slice:
+
+1. Resolves the current Payload canary from the npm registry (override with `--tag <dist-tag>`).
+2. Rewrites `package.json`: pins `payload` + every `@payloadcms/*` to that exact version in
+   lockstep, removes dependency overrides pinning them, converts their carets to exact, and writes
+   the TypeScript / `@types/node` / `engines.node` floors. The `@payloadcms/eslint-*` packages are
+   versioned independently, so they are set to `latest` rather than lockstep-pinned.
+3. Installs with your detected package manager.
+4. Runs every registered transform against the now-v4 tree.
+5. Prints a report and points you at the bundled runbook for the rest.
+
+It does NOT upgrade Next.js. Payload v4 requires Next 16; run Next's own recommended agent
+workflow (linked from the bundled runbook) to bump Next and migrate the code together. The report
+prints the required Next target.
+
+### `upgrade` flags
+
+- `--tag <dist-tag>` — dist-tag to resolve Payload versions from (default `canary`).
+- `--dry` — preview the `package.json` changes and planned steps; write and install nothing.
+- `--force` — skip the dirty-git-tree warning.
+
+### `upgrade prompt`
+
+`npx @payloadcms/codemod upgrade prompt` prints an orchestration prompt for a coding agent to run
+the full v3 -> v4 upgrade, Next.js 16 included. It is offline and stateless: it writes nothing and
+makes no network calls. The text is project-agnostic, so pipe it to your agent and run it from the
+project root.
+
+The prompt sequences the upgrade (mechanical slice via this command, then Next.js via Next's own
+codemods and agent workflow, then regeneration, judgment work, and verification) and points at the
+bundled runbook and migration guide for detail rather than restating them.
+
 ## How it works
 
 The tool loads your project via [ts-morph](https://ts-morph.com/), using your `tsconfig.json` when present, otherwise globbing `**/*.{ts,tsx,js,jsx}` (excluding `node_modules`, `dist`, `.next`, `build`). Each registered transform is applied in order against the shared project; changes are saved at the end unless `--dry` or `--print` is passed.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAaA,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DhF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiBA,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CA6EhF"}

package/dist/cli.js

@@ -1,12 +1,32 @@
-/* eslint-disable no-console */ import { existsSync, writeFileSync } from 'node:fs';
+/* eslint-disable no-console */ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { IndentationText, Project, QuoteKind } from 'ts-morph';
 import { parseFlags } from './cli.parseFlags.js';
 import { transforms as registry } from './registry.js';
 import { runTransforms } from './runner.js';
+import { runUpgrade } from './upgrade/index.js';
+import { renderUpgradePrompt } from './upgrade/prompt.js';
 import { loadPackageJsons, serializePackageJson } from './utils/packageJson.js';
+import { loadProject } from './utils/project.js';
 export async function main(argv = process.argv.slice(2)) {
     const flags = parseFlags(argv);
+    if (flags.command === 'upgrade' && flags.emitPrompt) {
+        console.log(renderUpgradePrompt());
+        return;
+    }
+    if (flags.command === 'upgrade') {
+        const { failed } = await runUpgrade({
+            flags: {
+                dry: flags.dry,
+                force: flags.force,
+                tag: flags.tag ?? 'canary'
+            },
+            path: flags.path
+        });
+        if (failed) {
+            process.exitCode = 1;
+        }
+        return;
+    }
     if (flags.list) {
         printList();
         return;
@@ -71,31 +91,6 @@ function printList() {
         console.log(`${t.name}  ${t.description}`);
     }
 }
-function loadProject(path) {
-    const manipulationSettings = {
-        indentationText: IndentationText.TwoSpaces,
-        quoteKind: QuoteKind.Single,
-        useTrailingCommas: true
-    };
-    const tsconfigPath = resolve(path, 'tsconfig.json');
-    if (existsSync(tsconfigPath)) {
-        return new Project({
-            manipulationSettings,
-            tsConfigFilePath: tsconfigPath
-        });
-    }
-    const project = new Project({
-        manipulationSettings
-    });
-    project.addSourceFilesAtPaths([
-        `${path}/**/*.{ts,tsx,js,jsx}`,
-        '!**/node_modules/**',
-        '!**/dist/**',
-        '!**/.next/**',
-        '!**/build/**'
-    ]);
-    return project;
-}
 function snapshotProject(project) {
     return new Map(project.getSourceFiles().map((file)=>[
             file.getFilePath(),

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["/* eslint-disable no-console */\nimport { existsSync, writeFileSync } from 'node:fs'\nimport { resolve } from 'node:path'\nimport { IndentationText, Project, QuoteKind } from 'ts-morph'\n\nimport type { TransformRunResult } from './runner.js'\nimport type { Transform } from './types.js'\n\nimport { parseFlags } from './cli.parseFlags.js'\nimport { transforms as registry } from './registry.js'\nimport { runTransforms } from './runner.js'\nimport { loadPackageJsons, serializePackageJson } from './utils/packageJson.js'\n\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const flags = parseFlags(argv)\n\n  if (flags.list) {\n    printList()\n    return\n  }\n\n  const selected = selectTransforms(registry, flags.transform)\n  if (selected.length === 0) {\n    console.error(`No transforms matched${flags.transform ? ` \"${flags.transform}\"` : ''}.`)\n    process.exitCode = 1\n    return\n  }\n\n  const project = loadProject(resolve(flags.path))\n  const snapshot = snapshotProject(project)\n\n  const packageJsons = loadPackageJsons(resolve(flags.path))\n\n  const { failed, results } = await runTransforms({\n    // Shares the same `data` reference, so transform mutations are visible\n    // below for change detection (do not clone here).\n    packageJsons: packageJsons.map(({ data, path }) => ({ data, path })),\n    project,\n    transforms: selected,\n  })\n\n  const changed = project\n    .getSourceFiles()\n    .filter((file) => snapshot.get(file.getFilePath()) !== file.getFullText())\n\n  const changedPackageJsons = packageJsons.filter(\n    (pkg) => serializePackageJson(pkg.data, pkg.originalText) !== pkg.originalText,\n  )\n\n  if (flags.print) {\n    if (changed.length === 0 && changedPackageJsons.length === 0) {\n      console.log('(no files changed)')\n    } else {\n      for (const file of changed) {\n        console.log(`// ${file.getFilePath()}`)\n        console.log(file.getFullText())\n      }\n      for (const pkg of changedPackageJsons) {\n        console.log(`// ${pkg.path}`)\n        console.log(serializePackageJson(pkg.data, pkg.originalText))\n      }\n    }\n  } else if (!flags.dry) {\n    await Promise.all(changed.map((file) => file.save()))\n    for (const pkg of changedPackageJsons) {\n      writeFileSync(pkg.path, serializePackageJson(pkg.data, pkg.originalText))\n    }\n  }\n\n  printSummary(results)\n\n  if (failed) {\n    process.exitCode = 1\n  }\n}\n\nfunction selectTransforms(available: Transform[], name: string | undefined): Transform[] {\n  if (!name) {\n    return available\n  }\n  return available.filter((t) => t.name === name)\n}\n\nfunction printList(): void {\n  if (registry.length === 0) {\n    console.log('No transforms registered.')\n    return\n  }\n  for (const t of registry) {\n    console.log(`${t.name}  ${t.description}`)\n  }\n}\n\nfunction loadProject(path: string): Project {\n  const manipulationSettings = {\n    indentationText: IndentationText.TwoSpaces,\n    quoteKind: QuoteKind.Single,\n    useTrailingCommas: true,\n  }\n  const tsconfigPath = resolve(path, 'tsconfig.json')\n  if (existsSync(tsconfigPath)) {\n    return new Project({ manipulationSettings, tsConfigFilePath: tsconfigPath })\n  }\n  const project = new Project({ manipulationSettings })\n  project.addSourceFilesAtPaths([\n    `${path}/**/*.{ts,tsx,js,jsx}`,\n    '!**/node_modules/**',\n    '!**/dist/**',\n    '!**/.next/**',\n    '!**/build/**',\n  ])\n  return project\n}\n\nfunction snapshotProject(project: Project): Map<string, string> {\n  return new Map(project.getSourceFiles().map((file) => [file.getFilePath(), file.getFullText()]))\n}\n\nfunction printSummary(results: TransformRunResult[]): void {\n  console.log('')\n  console.log('Codemod summary:')\n  for (const r of results) {\n    if (r.error) {\n      console.log(`  [FAIL] ${r.name} — ${r.error.message}`)\n      continue\n    }\n    console.log(`  [ok] ${r.name} — ${r.filesChanged.length} file(s) changed`)\n    for (const note of r.notes ?? []) {\n      console.log(`      note: ${note}`)\n    }\n  }\n}\n"],"names":["existsSync","writeFileSync","resolve","IndentationText","Project","QuoteKind","parseFlags","transforms","registry","runTransforms","loadPackageJsons","serializePackageJson","main","argv","process","slice","flags","list","printList","selected","selectTransforms","transform","length","console","error","exitCode","project","loadProject","path","snapshot","snapshotProject","packageJsons","failed","results","map","data","changed","getSourceFiles","filter","file","get","getFilePath","getFullText","changedPackageJsons","pkg","originalText","print","log","dry","Promise","all","save","printSummary","available","name","t","description","manipulationSettings","indentationText","TwoSpaces","quoteKind","Single","useTrailingCommas","tsconfigPath","tsConfigFilePath","addSourceFilesAtPaths","Map","r","message","filesChanged","note","notes"],"mappings":"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"}
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["import type { Project } from 'ts-morph'\n\n/* eslint-disable no-console */\nimport { writeFileSync } from 'node:fs'\nimport { resolve } from 'node:path'\n\nimport type { TransformRunResult } from './runner.js'\nimport type { Transform } from './types.js'\n\nimport { parseFlags } from './cli.parseFlags.js'\nimport { transforms as registry } from './registry.js'\nimport { runTransforms } from './runner.js'\nimport { runUpgrade } from './upgrade/index.js'\nimport { renderUpgradePrompt } from './upgrade/prompt.js'\nimport { loadPackageJsons, serializePackageJson } from './utils/packageJson.js'\nimport { loadProject } from './utils/project.js'\n\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const flags = parseFlags(argv)\n\n  if (flags.command === 'upgrade' && flags.emitPrompt) {\n    console.log(renderUpgradePrompt())\n    return\n  }\n\n  if (flags.command === 'upgrade') {\n    const { failed } = await runUpgrade({\n      flags: { dry: flags.dry, force: flags.force, tag: flags.tag ?? 'canary' },\n      path: flags.path,\n    })\n    if (failed) {\n      process.exitCode = 1\n    }\n    return\n  }\n\n  if (flags.list) {\n    printList()\n    return\n  }\n\n  const selected = selectTransforms(registry, flags.transform)\n  if (selected.length === 0) {\n    console.error(`No transforms matched${flags.transform ? ` \"${flags.transform}\"` : ''}.`)\n    process.exitCode = 1\n    return\n  }\n\n  const project = loadProject(resolve(flags.path))\n  const snapshot = snapshotProject(project)\n\n  const packageJsons = loadPackageJsons(resolve(flags.path))\n\n  const { failed, results } = await runTransforms({\n    // Shares the same `data` reference, so transform mutations are visible\n    // below for change detection (do not clone here).\n    packageJsons: packageJsons.map(({ data, path }) => ({ data, path })),\n    project,\n    transforms: selected,\n  })\n\n  const changed = project\n    .getSourceFiles()\n    .filter((file) => snapshot.get(file.getFilePath()) !== file.getFullText())\n\n  const changedPackageJsons = packageJsons.filter(\n    (pkg) => serializePackageJson(pkg.data, pkg.originalText) !== pkg.originalText,\n  )\n\n  if (flags.print) {\n    if (changed.length === 0 && changedPackageJsons.length === 0) {\n      console.log('(no files changed)')\n    } else {\n      for (const file of changed) {\n        console.log(`// ${file.getFilePath()}`)\n        console.log(file.getFullText())\n      }\n      for (const pkg of changedPackageJsons) {\n        console.log(`// ${pkg.path}`)\n        console.log(serializePackageJson(pkg.data, pkg.originalText))\n      }\n    }\n  } else if (!flags.dry) {\n    await Promise.all(changed.map((file) => file.save()))\n    for (const pkg of changedPackageJsons) {\n      writeFileSync(pkg.path, serializePackageJson(pkg.data, pkg.originalText))\n    }\n  }\n\n  printSummary(results)\n\n  if (failed) {\n    process.exitCode = 1\n  }\n}\n\nfunction selectTransforms(available: Transform[], name: string | undefined): Transform[] {\n  if (!name) {\n    return available\n  }\n  return available.filter((t) => t.name === name)\n}\n\nfunction printList(): void {\n  if (registry.length === 0) {\n    console.log('No transforms registered.')\n    return\n  }\n  for (const t of registry) {\n    console.log(`${t.name}  ${t.description}`)\n  }\n}\n\nfunction snapshotProject(project: Project): Map<string, string> {\n  return new Map(project.getSourceFiles().map((file) => [file.getFilePath(), file.getFullText()]))\n}\n\nfunction printSummary(results: TransformRunResult[]): void {\n  console.log('')\n  console.log('Codemod summary:')\n  for (const r of results) {\n    if (r.error) {\n      console.log(`  [FAIL] ${r.name} — ${r.error.message}`)\n      continue\n    }\n    console.log(`  [ok] ${r.name} — ${r.filesChanged.length} file(s) changed`)\n    for (const note of r.notes ?? []) {\n      console.log(`      note: ${note}`)\n    }\n  }\n}\n"],"names":["writeFileSync","resolve","parseFlags","transforms","registry","runTransforms","runUpgrade","renderUpgradePrompt","loadPackageJsons","serializePackageJson","loadProject","main","argv","process","slice","flags","command","emitPrompt","console","log","failed","dry","force","tag","path","exitCode","list","printList","selected","selectTransforms","transform","length","error","project","snapshot","snapshotProject","packageJsons","results","map","data","changed","getSourceFiles","filter","file","get","getFilePath","getFullText","changedPackageJsons","pkg","originalText","print","Promise","all","save","printSummary","available","name","t","description","Map","r","message","filesChanged","note","notes"],"mappings":"AAEA,6BAA6B,GAC7B,SAASA,aAAa,QAAQ,UAAS;AACvC,SAASC,OAAO,QAAQ,YAAW;AAKnC,SAASC,UAAU,QAAQ,sBAAqB;AAChD,SAASC,cAAcC,QAAQ,QAAQ,gBAAe;AACtD,SAASC,aAAa,QAAQ,cAAa;AAC3C,SAASC,UAAU,QAAQ,qBAAoB;AAC/C,SAASC,mBAAmB,QAAQ,sBAAqB;AACzD,SAASC,gBAAgB,EAAEC,oBAAoB,QAAQ,yBAAwB;AAC/E,SAASC,WAAW,QAAQ,qBAAoB;AAEhD,OAAO,eAAeC,KAAKC,OAAiBC,QAAQD,IAAI,CAACE,KAAK,CAAC,EAAE;IAC/D,MAAMC,QAAQb,WAAWU;IAEzB,IAAIG,MAAMC,OAAO,KAAK,aAAaD,MAAME,UAAU,EAAE;QACnDC,QAAQC,GAAG,CAACZ;QACZ;IACF;IAEA,IAAIQ,MAAMC,OAAO,KAAK,WAAW;QAC/B,MAAM,EAAEI,MAAM,EAAE,GAAG,MAAMd,WAAW;YAClCS,OAAO;gBAAEM,KAAKN,MAAMM,GAAG;gBAAEC,OAAOP,MAAMO,KAAK;gBAAEC,KAAKR,MAAMQ,GAAG,IAAI;YAAS;YACxEC,MAAMT,MAAMS,IAAI;QAClB;QACA,IAAIJ,QAAQ;YACVP,QAAQY,QAAQ,GAAG;QACrB;QACA;IACF;IAEA,IAAIV,MAAMW,IAAI,EAAE;QACdC;QACA;IACF;IAEA,MAAMC,WAAWC,iBAAiBzB,UAAUW,MAAMe,SAAS;IAC3D,IAAIF,SAASG,MAAM,KAAK,GAAG;QACzBb,QAAQc,KAAK,CAAC,CAAC,qBAAqB,EAAEjB,MAAMe,SAAS,GAAG,CAAC,EAAE,EAAEf,MAAMe,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QACvFjB,QAAQY,QAAQ,GAAG;QACnB;IACF;IAEA,MAAMQ,UAAUvB,YAAYT,QAAQc,MAAMS,IAAI;IAC9C,MAAMU,WAAWC,gBAAgBF;IAEjC,MAAMG,eAAe5B,iBAAiBP,QAAQc,MAAMS,IAAI;IAExD,MAAM,EAAEJ,MAAM,EAAEiB,OAAO,EAAE,GAAG,MAAMhC,cAAc;QAC9C,uEAAuE;QACvE,kDAAkD;QAClD+B,cAAcA,aAAaE,GAAG,CAAC,CAAC,EAAEC,IAAI,EAAEf,IAAI,EAAE,GAAM,CAAA;gBAAEe;gBAAMf;YAAK,CAAA;QACjES;QACA9B,YAAYyB;IACd;IAEA,MAAMY,UAAUP,QACbQ,cAAc,GACdC,MAAM,CAAC,CAACC,OAAST,SAASU,GAAG,CAACD,KAAKE,WAAW,QAAQF,KAAKG,WAAW;IAEzE,MAAMC,sBAAsBX,aAAaM,MAAM,CAC7C,CAACM,MAAQvC,qBAAqBuC,IAAIT,IAAI,EAAES,IAAIC,YAAY,MAAMD,IAAIC,YAAY;IAGhF,IAAIlC,MAAMmC,KAAK,EAAE;QACf,IAAIV,QAAQT,MAAM,KAAK,KAAKgB,oBAAoBhB,MAAM,KAAK,GAAG;YAC5Db,QAAQC,GAAG,CAAC;QACd,OAAO;YACL,KAAK,MAAMwB,QAAQH,QAAS;gBAC1BtB,QAAQC,GAAG,CAAC,CAAC,GAAG,EAAEwB,KAAKE,WAAW,IAAI;gBACtC3B,QAAQC,GAAG,CAACwB,KAAKG,WAAW;YAC9B;YACA,KAAK,MAAME,OAAOD,oBAAqB;gBACrC7B,QAAQC,GAAG,CAAC,CAAC,GAAG,EAAE6B,IAAIxB,IAAI,EAAE;gBAC5BN,QAAQC,GAAG,CAACV,qBAAqBuC,IAAIT,IAAI,EAAES,IAAIC,YAAY;YAC7D;QACF;IACF,OAAO,IAAI,CAAClC,MAAMM,GAAG,EAAE;QACrB,MAAM8B,QAAQC,GAAG,CAACZ,QAAQF,GAAG,CAAC,CAACK,OAASA,KAAKU,IAAI;QACjD,KAAK,MAAML,OAAOD,oBAAqB;YACrC/C,cAAcgD,IAAIxB,IAAI,EAAEf,qBAAqBuC,IAAIT,IAAI,EAAES,IAAIC,YAAY;QACzE;IACF;IAEAK,aAAajB;IAEb,IAAIjB,QAAQ;QACVP,QAAQY,QAAQ,GAAG;IACrB;AACF;AAEA,SAASI,iBAAiB0B,SAAsB,EAAEC,IAAwB;IACxE,IAAI,CAACA,MAAM;QACT,OAAOD;IACT;IACA,OAAOA,UAAUb,MAAM,CAAC,CAACe,IAAMA,EAAED,IAAI,KAAKA;AAC5C;AAEA,SAAS7B;IACP,IAAIvB,SAAS2B,MAAM,KAAK,GAAG;QACzBb,QAAQC,GAAG,CAAC;QACZ;IACF;IACA,KAAK,MAAMsC,KAAKrD,SAAU;QACxBc,QAAQC,GAAG,CAAC,GAAGsC,EAAED,IAAI,CAAC,EAAE,EAAEC,EAAEC,WAAW,EAAE;IAC3C;AACF;AAEA,SAASvB,gBAAgBF,OAAgB;IACvC,OAAO,IAAI0B,IAAI1B,QAAQQ,cAAc,GAAGH,GAAG,CAAC,CAACK,OAAS;YAACA,KAAKE,WAAW;YAAIF,KAAKG,WAAW;SAAG;AAChG;AAEA,SAASQ,aAAajB,OAA6B;IACjDnB,QAAQC,GAAG,CAAC;IACZD,QAAQC,GAAG,CAAC;IACZ,KAAK,MAAMyC,KAAKvB,QAAS;QACvB,IAAIuB,EAAE5B,KAAK,EAAE;YACXd,QAAQC,GAAG,CAAC,CAAC,SAAS,EAAEyC,EAAEJ,IAAI,CAAC,GAAG,EAAEI,EAAE5B,KAAK,CAAC6B,OAAO,EAAE;YACrD;QACF;QACA3C,QAAQC,GAAG,CAAC,CAAC,OAAO,EAAEyC,EAAEJ,IAAI,CAAC,GAAG,EAAEI,EAAEE,YAAY,CAAC/B,MAAM,CAAC,gBAAgB,CAAC;QACzE,KAAK,MAAMgC,QAAQH,EAAEI,KAAK,IAAI,EAAE,CAAE;YAChC9C,QAAQC,GAAG,CAAC,CAAC,YAAY,EAAE4C,MAAM;QACnC;IACF;AACF"}

package/dist/cli.parseFlags.d.ts

@@ -1,8 +1,13 @@
+export type CliCommand = 'upgrade';
 export type CliFlags = {
+    command?: CliCommand;
     dry: boolean;
+    emitPrompt: boolean;
+    force: boolean;
     list: boolean;
     path: string;
     print: boolean;
+    tag?: string;
     transform?: string;
 };
 export declare function parseFlags(argv: string[]): CliFlags;

package/dist/cli.parseFlags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.parseFlags.d.ts","sourceRoot":"","sources":["../src/cli.parseFlags.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,OAAO,CAAA;IACZ,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CAoBnD"}
+{"version":3,"file":"cli.parseFlags.d.ts","sourceRoot":"","sources":["../src/cli.parseFlags.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,SAAS,CAAA;AAElC,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,GAAG,EAAE,OAAO,CAAA;IACZ,UAAU,EAAE,OAAO,CAAA;IACnB,KAAK,EAAE,OAAO,CAAA;IACd,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CAmCnD"}

package/dist/cli.parseFlags.js

@@ -12,6 +12,10 @@ export function parseFlags(argv) {
                 type: 'boolean',
                 default: false
             },
+            force: {
+                type: 'boolean',
+                default: false
+            },
             list: {
                 type: 'boolean',
                 default: false
@@ -20,16 +24,31 @@ export function parseFlags(argv) {
                 type: 'boolean',
                 default: false
             },
+            tag: {
+                type: 'string'
+            },
             transform: {
                 type: 'string'
             }
         }
     });
+    const isUpgrade = positionals[0] === 'upgrade';
+    const command = isUpgrade ? 'upgrade' : undefined;
+    // `upgrade prompt [path]` emits the orchestration prompt; `prompt` consumes
+    // positional 1, shifting the path to positional 2.
+    const emitPrompt = isUpgrade && positionals[1] === 'prompt';
+    const upgradePath = emitPrompt ? positionals[2] : positionals[1];
+    // When `upgrade` is present it consumes positional 0; the path shifts to positional 1.
+    const path = (isUpgrade ? upgradePath : positionals[0]) ?? process.cwd();
     return {
+        command,
         dry: Boolean(values.dry) || Boolean(values['dry-run']),
+        emitPrompt,
+        force: Boolean(values.force),
         list: Boolean(values.list),
-        path: positionals[0] ?? process.cwd(),
+        path,
         print: Boolean(values.print),
+        tag: values.tag,
         transform: values.transform
     };
 }

package/dist/cli.parseFlags.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli.parseFlags.ts"],"sourcesContent":["import { parseArgs } from 'node:util'\n\nexport type CliFlags = {\n  dry: boolean\n  list: boolean\n  path: string\n  print: boolean\n  transform?: string\n}\n\nexport function parseFlags(argv: string[]): CliFlags {\n  const { positionals, values } = parseArgs({\n    allowPositionals: true,\n    args: argv,\n    options: {\n      dry: { type: 'boolean', default: false },\n      'dry-run': { type: 'boolean', default: false },\n      list: { type: 'boolean', default: false },\n      print: { type: 'boolean', default: false },\n      transform: { type: 'string' },\n    },\n  })\n\n  return {\n    dry: Boolean(values.dry) || Boolean(values['dry-run']),\n    list: Boolean(values.list),\n    path: positionals[0] ?? process.cwd(),\n    print: Boolean(values.print),\n    transform: values.transform,\n  }\n}\n"],"names":["parseArgs","parseFlags","argv","positionals","values","allowPositionals","args","options","dry","type","default","list","print","transform","Boolean","path","process","cwd"],"mappings":"AAAA,SAASA,SAAS,QAAQ,YAAW;AAUrC,OAAO,SAASC,WAAWC,IAAc;IACvC,MAAM,EAAEC,WAAW,EAAEC,MAAM,EAAE,GAAGJ,UAAU;QACxCK,kBAAkB;QAClBC,MAAMJ;QACNK,SAAS;YACPC,KAAK;gBAAEC,MAAM;gBAAWC,SAAS;YAAM;YACvC,WAAW;gBAAED,MAAM;gBAAWC,SAAS;YAAM;YAC7CC,MAAM;gBAAEF,MAAM;gBAAWC,SAAS;YAAM;YACxCE,OAAO;gBAAEH,MAAM;gBAAWC,SAAS;YAAM;YACzCG,WAAW;gBAAEJ,MAAM;YAAS;QAC9B;IACF;IAEA,OAAO;QACLD,KAAKM,QAAQV,OAAOI,GAAG,KAAKM,QAAQV,MAAM,CAAC,UAAU;QACrDO,MAAMG,QAAQV,OAAOO,IAAI;QACzBI,MAAMZ,WAAW,CAAC,EAAE,IAAIa,QAAQC,GAAG;QACnCL,OAAOE,QAAQV,OAAOQ,KAAK;QAC3BC,WAAWT,OAAOS,SAAS;IAC7B;AACF"}
+{"version":3,"sources":["../src/cli.parseFlags.ts"],"sourcesContent":["import { parseArgs } from 'node:util'\n\nexport type CliCommand = 'upgrade'\n\nexport type CliFlags = {\n  command?: CliCommand\n  dry: boolean\n  emitPrompt: boolean\n  force: boolean\n  list: boolean\n  path: string\n  print: boolean\n  tag?: string\n  transform?: string\n}\n\nexport function parseFlags(argv: string[]): CliFlags {\n  const { positionals, values } = parseArgs({\n    allowPositionals: true,\n    args: argv,\n    options: {\n      dry: { type: 'boolean', default: false },\n      'dry-run': { type: 'boolean', default: false },\n      force: { type: 'boolean', default: false },\n      list: { type: 'boolean', default: false },\n      print: { type: 'boolean', default: false },\n      tag: { type: 'string' },\n      transform: { type: 'string' },\n    },\n  })\n\n  const isUpgrade = positionals[0] === 'upgrade'\n  const command = isUpgrade ? 'upgrade' : undefined\n  // `upgrade prompt [path]` emits the orchestration prompt; `prompt` consumes\n  // positional 1, shifting the path to positional 2.\n  const emitPrompt = isUpgrade && positionals[1] === 'prompt'\n  const upgradePath = emitPrompt ? positionals[2] : positionals[1]\n  // When `upgrade` is present it consumes positional 0; the path shifts to positional 1.\n  const path = (isUpgrade ? upgradePath : positionals[0]) ?? process.cwd()\n\n  return {\n    command,\n    dry: Boolean(values.dry) || Boolean(values['dry-run']),\n    emitPrompt,\n    force: Boolean(values.force),\n    list: Boolean(values.list),\n    path,\n    print: Boolean(values.print),\n    tag: values.tag,\n    transform: values.transform,\n  }\n}\n"],"names":["parseArgs","parseFlags","argv","positionals","values","allowPositionals","args","options","dry","type","default","force","list","print","tag","transform","isUpgrade","command","undefined","emitPrompt","upgradePath","path","process","cwd","Boolean"],"mappings":"AAAA,SAASA,SAAS,QAAQ,YAAW;AAgBrC,OAAO,SAASC,WAAWC,IAAc;IACvC,MAAM,EAAEC,WAAW,EAAEC,MAAM,EAAE,GAAGJ,UAAU;QACxCK,kBAAkB;QAClBC,MAAMJ;QACNK,SAAS;YACPC,KAAK;gBAAEC,MAAM;gBAAWC,SAAS;YAAM;YACvC,WAAW;gBAAED,MAAM;gBAAWC,SAAS;YAAM;YAC7CC,OAAO;gBAAEF,MAAM;gBAAWC,SAAS;YAAM;YACzCE,MAAM;gBAAEH,MAAM;gBAAWC,SAAS;YAAM;YACxCG,OAAO;gBAAEJ,MAAM;gBAAWC,SAAS;YAAM;YACzCI,KAAK;gBAAEL,MAAM;YAAS;YACtBM,WAAW;gBAAEN,MAAM;YAAS;QAC9B;IACF;IAEA,MAAMO,YAAYb,WAAW,CAAC,EAAE,KAAK;IACrC,MAAMc,UAAUD,YAAY,YAAYE;IACxC,4EAA4E;IAC5E,mDAAmD;IACnD,MAAMC,aAAaH,aAAab,WAAW,CAAC,EAAE,KAAK;IACnD,MAAMiB,cAAcD,aAAahB,WAAW,CAAC,EAAE,GAAGA,WAAW,CAAC,EAAE;IAChE,uFAAuF;IACvF,MAAMkB,OAAO,AAACL,CAAAA,YAAYI,cAAcjB,WAAW,CAAC,EAAE,AAAD,KAAMmB,QAAQC,GAAG;IAEtE,OAAO;QACLN;QACAT,KAAKgB,QAAQpB,OAAOI,GAAG,KAAKgB,QAAQpB,MAAM,CAAC,UAAU;QACrDe;QACAR,OAAOa,QAAQpB,OAAOO,KAAK;QAC3BC,MAAMY,QAAQpB,OAAOQ,IAAI;QACzBS;QACAR,OAAOW,QAAQpB,OAAOS,KAAK;QAC3BC,KAAKV,OAAOU,GAAG;QACfC,WAAWX,OAAOW,SAAS;IAC7B;AACF"}

package/dist/cli.parseFlags.spec.js

@@ -3,10 +3,14 @@ import { parseFlags } from './cli.parseFlags.js';
 describe('parseFlags', ()=>{
     it('defaults path to cwd when no positional arg is given', ()=>{
         expect(parseFlags([])).toEqual({
+            command: undefined,
             dry: false,
+            emitPrompt: false,
+            force: false,
             list: false,
             path: process.cwd(),
             print: false,
+            tag: undefined,
             transform: undefined
         });
     });
@@ -44,6 +48,74 @@ describe('parseFlags', ()=>{
             '--dry-run'
         ]).dry).toBe(true);
     });
+    it('parses the upgrade subcommand with default path', ()=>{
+        expect(parseFlags([
+            'upgrade'
+        ])).toMatchObject({
+            command: 'upgrade',
+            path: process.cwd()
+        });
+    });
+    it('parses upgrade with path, tag, force, and dry', ()=>{
+        expect(parseFlags([
+            'upgrade',
+            './app',
+            '--tag',
+            'latest',
+            '--force',
+            '--dry'
+        ])).toMatchObject({
+            command: 'upgrade',
+            dry: true,
+            force: true,
+            path: './app',
+            tag: 'latest'
+        });
+    });
+    it('parses `upgrade prompt` with default path', ()=>{
+        expect(parseFlags([
+            'upgrade',
+            'prompt'
+        ])).toMatchObject({
+            command: 'upgrade',
+            emitPrompt: true,
+            path: process.cwd()
+        });
+    });
+    it('parses `upgrade prompt <path>` with tag', ()=>{
+        expect(parseFlags([
+            'upgrade',
+            'prompt',
+            './app',
+            '--tag',
+            'latest'
+        ])).toMatchObject({
+            command: 'upgrade',
+            emitPrompt: true,
+            path: './app',
+            tag: 'latest'
+        });
+    });
+    it('leaves emitPrompt false for a plain upgrade run', ()=>{
+        expect(parseFlags([
+            'upgrade',
+            './app'
+        ])).toMatchObject({
+            command: 'upgrade',
+            emitPrompt: false,
+            path: './app'
+        });
+    });
+    it('leaves command undefined for a bare path invocation', ()=>{
+        expect(parseFlags([
+            './src',
+            '--dry'
+        ])).toMatchObject({
+            command: undefined,
+            dry: true,
+            path: './src'
+        });
+    });
 });
 
 //# sourceMappingURL=cli.parseFlags.spec.js.map

package/dist/cli.parseFlags.spec.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cli.parseFlags.spec.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\n\nimport { parseFlags } from './cli.parseFlags.js'\n\ndescribe('parseFlags', () => {\n  it('defaults path to cwd when no positional arg is given', () => {\n    expect(parseFlags([])).toEqual({\n      dry: false,\n      list: false,\n      path: process.cwd(),\n      print: false,\n      transform: undefined,\n    })\n  })\n\n  it('reads positional path', () => {\n    expect(parseFlags(['./src']).path).toBe('./src')\n  })\n\n  it('parses flags', () => {\n    expect(parseFlags(['./src', '--dry', '--print'])).toMatchObject({\n      dry: true,\n      path: './src',\n      print: true,\n    })\n  })\n\n  it('parses --transform', () => {\n    expect(parseFlags(['--transform', 'rename-slate-export'])).toMatchObject({\n      transform: 'rename-slate-export',\n    })\n  })\n\n  it('parses --list', () => {\n    expect(parseFlags(['--list']).list).toBe(true)\n  })\n\n  it('treats --dry-run as an alias for --dry', () => {\n    expect(parseFlags(['--dry-run']).dry).toBe(true)\n  })\n})\n"],"names":["describe","expect","it","parseFlags","toEqual","dry","list","path","process","cwd","print","transform","undefined","toBe","toMatchObject"],"mappings":"AAAA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAE7C,SAASC,UAAU,QAAQ,sBAAqB;AAEhDH,SAAS,cAAc;IACrBE,GAAG,wDAAwD;QACzDD,OAAOE,WAAW,EAAE,GAAGC,OAAO,CAAC;YAC7BC,KAAK;YACLC,MAAM;YACNC,MAAMC,QAAQC,GAAG;YACjBC,OAAO;YACPC,WAAWC;QACb;IACF;IAEAV,GAAG,yBAAyB;QAC1BD,OAAOE,WAAW;YAAC;SAAQ,EAAEI,IAAI,EAAEM,IAAI,CAAC;IAC1C;IAEAX,GAAG,gBAAgB;QACjBD,OAAOE,WAAW;YAAC;YAAS;YAAS;SAAU,GAAGW,aAAa,CAAC;YAC9DT,KAAK;YACLE,MAAM;YACNG,OAAO;QACT;IACF;IAEAR,GAAG,sBAAsB;QACvBD,OAAOE,WAAW;YAAC;YAAe;SAAsB,GAAGW,aAAa,CAAC;YACvEH,WAAW;QACb;IACF;IAEAT,GAAG,iBAAiB;QAClBD,OAAOE,WAAW;YAAC;SAAS,EAAEG,IAAI,EAAEO,IAAI,CAAC;IAC3C;IAEAX,GAAG,0CAA0C;QAC3CD,OAAOE,WAAW;YAAC;SAAY,EAAEE,GAAG,EAAEQ,IAAI,CAAC;IAC7C;AACF"}
+{"version":3,"sources":["../src/cli.parseFlags.spec.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\n\nimport { parseFlags } from './cli.parseFlags.js'\n\ndescribe('parseFlags', () => {\n  it('defaults path to cwd when no positional arg is given', () => {\n    expect(parseFlags([])).toEqual({\n      command: undefined,\n      dry: false,\n      emitPrompt: false,\n      force: false,\n      list: false,\n      path: process.cwd(),\n      print: false,\n      tag: undefined,\n      transform: undefined,\n    })\n  })\n\n  it('reads positional path', () => {\n    expect(parseFlags(['./src']).path).toBe('./src')\n  })\n\n  it('parses flags', () => {\n    expect(parseFlags(['./src', '--dry', '--print'])).toMatchObject({\n      dry: true,\n      path: './src',\n      print: true,\n    })\n  })\n\n  it('parses --transform', () => {\n    expect(parseFlags(['--transform', 'rename-slate-export'])).toMatchObject({\n      transform: 'rename-slate-export',\n    })\n  })\n\n  it('parses --list', () => {\n    expect(parseFlags(['--list']).list).toBe(true)\n  })\n\n  it('treats --dry-run as an alias for --dry', () => {\n    expect(parseFlags(['--dry-run']).dry).toBe(true)\n  })\n\n  it('parses the upgrade subcommand with default path', () => {\n    expect(parseFlags(['upgrade'])).toMatchObject({\n      command: 'upgrade',\n      path: process.cwd(),\n    })\n  })\n\n  it('parses upgrade with path, tag, force, and dry', () => {\n    expect(parseFlags(['upgrade', './app', '--tag', 'latest', '--force', '--dry'])).toMatchObject({\n      command: 'upgrade',\n      dry: true,\n      force: true,\n      path: './app',\n      tag: 'latest',\n    })\n  })\n\n  it('parses `upgrade prompt` with default path', () => {\n    expect(parseFlags(['upgrade', 'prompt'])).toMatchObject({\n      command: 'upgrade',\n      emitPrompt: true,\n      path: process.cwd(),\n    })\n  })\n\n  it('parses `upgrade prompt <path>` with tag', () => {\n    expect(parseFlags(['upgrade', 'prompt', './app', '--tag', 'latest'])).toMatchObject({\n      command: 'upgrade',\n      emitPrompt: true,\n      path: './app',\n      tag: 'latest',\n    })\n  })\n\n  it('leaves emitPrompt false for a plain upgrade run', () => {\n    expect(parseFlags(['upgrade', './app'])).toMatchObject({\n      command: 'upgrade',\n      emitPrompt: false,\n      path: './app',\n    })\n  })\n\n  it('leaves command undefined for a bare path invocation', () => {\n    expect(parseFlags(['./src', '--dry'])).toMatchObject({\n      command: undefined,\n      dry: true,\n      path: './src',\n    })\n  })\n})\n"],"names":["describe","expect","it","parseFlags","toEqual","command","undefined","dry","emitPrompt","force","list","path","process","cwd","print","tag","transform","toBe","toMatchObject"],"mappings":"AAAA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAE7C,SAASC,UAAU,QAAQ,sBAAqB;AAEhDH,SAAS,cAAc;IACrBE,GAAG,wDAAwD;QACzDD,OAAOE,WAAW,EAAE,GAAGC,OAAO,CAAC;YAC7BC,SAASC;YACTC,KAAK;YACLC,YAAY;YACZC,OAAO;YACPC,MAAM;YACNC,MAAMC,QAAQC,GAAG;YACjBC,OAAO;YACPC,KAAKT;YACLU,WAAWV;QACb;IACF;IAEAJ,GAAG,yBAAyB;QAC1BD,OAAOE,WAAW;YAAC;SAAQ,EAAEQ,IAAI,EAAEM,IAAI,CAAC;IAC1C;IAEAf,GAAG,gBAAgB;QACjBD,OAAOE,WAAW;YAAC;YAAS;YAAS;SAAU,GAAGe,aAAa,CAAC;YAC9DX,KAAK;YACLI,MAAM;YACNG,OAAO;QACT;IACF;IAEAZ,GAAG,sBAAsB;QACvBD,OAAOE,WAAW;YAAC;YAAe;SAAsB,GAAGe,aAAa,CAAC;YACvEF,WAAW;QACb;IACF;IAEAd,GAAG,iBAAiB;QAClBD,OAAOE,WAAW;YAAC;SAAS,EAAEO,IAAI,EAAEO,IAAI,CAAC;IAC3C;IAEAf,GAAG,0CAA0C;QAC3CD,OAAOE,WAAW;YAAC;SAAY,EAAEI,GAAG,EAAEU,IAAI,CAAC;IAC7C;IAEAf,GAAG,mDAAmD;QACpDD,OAAOE,WAAW;YAAC;SAAU,GAAGe,aAAa,CAAC;YAC5Cb,SAAS;YACTM,MAAMC,QAAQC,GAAG;QACnB;IACF;IAEAX,GAAG,iDAAiD;QAClDD,OAAOE,WAAW;YAAC;YAAW;YAAS;YAAS;YAAU;YAAW;SAAQ,GAAGe,aAAa,CAAC;YAC5Fb,SAAS;YACTE,KAAK;YACLE,OAAO;YACPE,MAAM;YACNI,KAAK;QACP;IACF;IAEAb,GAAG,6CAA6C;QAC9CD,OAAOE,WAAW;YAAC;YAAW;SAAS,GAAGe,aAAa,CAAC;YACtDb,SAAS;YACTG,YAAY;YACZG,MAAMC,QAAQC,GAAG;QACnB;IACF;IAEAX,GAAG,2CAA2C;QAC5CD,OAAOE,WAAW;YAAC;YAAW;YAAU;YAAS;YAAS;SAAS,GAAGe,aAAa,CAAC;YAClFb,SAAS;YACTG,YAAY;YACZG,MAAM;YACNI,KAAK;QACP;IACF;IAEAb,GAAG,mDAAmD;QACpDD,OAAOE,WAAW;YAAC;YAAW;SAAQ,GAAGe,aAAa,CAAC;YACrDb,SAAS;YACTG,YAAY;YACZG,MAAM;QACR;IACF;IAEAT,GAAG,uDAAuD;QACxDD,OAAOE,WAAW;YAAC;YAAS;SAAQ,GAAGe,aAAa,CAAC;YACnDb,SAASC;YACTC,KAAK;YACLI,MAAM;QACR;IACF;AACF"}

package/dist/runbook/payload-v4-upgrade.md

@@ -0,0 +1,55 @@
+# Payload v3 -> v4: remaining steps
+
+`payload-codemod upgrade` has done the mechanical slice: pinned Payload packages to v4,
+removed conflicting overrides, written the toolchain floors, installed, and run the AST
+transforms. This checklist is what it did NOT do. The authoritative breaking-change list is
+the migration guide (`docs/migration-guide/v4.mdx`, also bundled at `dist/runbook/v4.mdx`):
+<https://github.com/payloadcms/payload/blob/main/docs/migration-guide/v4.mdx>
+
+Report each item as verified / cannot-confirm / broken. Do not call the upgrade complete while
+any gate fails or any generated file is stale.
+
+## 0. Before upgrading (do on v3)
+
+Some migrations need v3 tooling that v4 removes, so they must run BEFORE `payload-codemod upgrade`,
+while the v3 packages are still installed:
+
+- Slate richtext is deleted in v4. Migrate Slate -> Lexical on v3; the migration path is gone once
+  packages are pinned to v4.
+
+## 1. Next.js 16
+
+Payload v4 requires Next 16. The command did not touch Next. Run Next's own recommended agent
+workflow, which bumps Next + React and migrates the code as one unit:
+<https://nextjs.org/docs/app/guides/upgrading/version-16#use-an-ai-agent-recommended>
+
+Keep the resulting Next version within `>=16.2.6 <17` (the exact target is printed in the
+upgrade report), since Next's `upgrade latest` may point past 16 in future.
+
+## 2. Regenerate generated files
+
+```bash
+payload generate:types && payload generate:importmap
+```
+
+Never hand-edit `payload-types.ts` or `importMap.js` — regenerate them. If a credential wall
+blocks generation, set dummy env values and re-run.
+
+## 3. Manual v4 items (not covered by transforms)
+
+- SCSS is gone: move `@payloadcms/ui/scss` to `@payloadcms/ui/css`; rename `--theme-*` -> `--color-*`.
+- Sweep agent/editor instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`) for APIs v4 removed.
+- Cron parsing is strict now: `/10 * * * *` -> `*/10 * * * *`.
+- Jobs: run DB migrations for the new lease/stats fields.
+- Review per-transform notes printed in the upgrade report for spots needing manual review.
+
+## 4. Verify
+
+- `tsc --noEmit` (delete `tsconfig.tsbuildinfo` first; set `checkJs: true` so `importMap.js` is covered).
+- Run integration tests and e2e separately.
+- Build.
+- Confirm native modules (e.g. `sharp`) still load.
+
+## 5. Report honestly
+
+Distinguish verified, cannot-confirm, and broken. A silent gap reads as "checked and fine".