@akinon/projectzero 2.0.0-beta.22 → 2.0.0-beta.24

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @akinon/projectzero
 
+## 2.0.0-beta.24
+
+### Patch Changes
+
+- 64003f74: ZERO-4337: Add upgrade-to-2 orchestrator codemod for brand projects
+- 2f008a92: ZERO-4337: Add upgrade-to-2 orchestrator codemod
+
+## 2.0.0-beta.23
+
+### Patch Changes
+
+- 3fa934ea: ZERO-4338: Rename middleware.ts to proxy.ts for Next 16 convention
+
 ## 2.0.0-beta.22
 
 ### Patch Changes

package/app-template/CHANGELOG.md

@@ -1,5 +1,69 @@
 # projectzeronext
 
+## 2.0.0-beta.24
+
+### Patch Changes
+
+- @akinon/next@2.0.0-beta.24
+- @akinon/pz-akifast@2.0.0-beta.24
+- @akinon/pz-apple-pay@2.0.0-beta.24
+- @akinon/pz-b2b@2.0.0-beta.24
+- @akinon/pz-basket-gift-pack@2.0.0-beta.24
+- @akinon/pz-bkm@2.0.0-beta.24
+- @akinon/pz-checkout-gift-pack@2.0.0-beta.24
+- @akinon/pz-click-collect@2.0.0-beta.24
+- @akinon/pz-credit-payment@2.0.0-beta.24
+- @akinon/pz-cybersource-uc@2.0.0-beta.24
+- @akinon/pz-flow-payment@2.0.0-beta.24
+- @akinon/pz-google-pay@2.0.0-beta.24
+- @akinon/pz-gpay@2.0.0-beta.24
+- @akinon/pz-haso@2.0.0-beta.24
+- @akinon/pz-hepsipay@2.0.0-beta.24
+- @akinon/pz-masterpass@2.0.0-beta.24
+- @akinon/pz-masterpass-rest@2.0.0-beta.24
+- @akinon/pz-multi-basket@2.0.0-beta.24
+- @akinon/pz-one-click-checkout@2.0.0-beta.24
+- @akinon/pz-otp@2.0.0-beta.24
+- @akinon/pz-pay-on-delivery@2.0.0-beta.24
+- @akinon/pz-saved-card@2.0.0-beta.24
+- @akinon/pz-similar-products@2.0.0-beta.24
+- @akinon/pz-tabby-extension@2.0.0-beta.24
+- @akinon/pz-tamara-extension@2.0.0-beta.24
+- @akinon/pz-theme@2.0.0-beta.24
+- @akinon/pz-virtual-try-on@2.0.0-beta.24
+
+## 2.0.0-beta.23
+
+### Patch Changes
+
+- @akinon/next@2.0.0-beta.23
+- @akinon/pz-akifast@2.0.0-beta.23
+- @akinon/pz-apple-pay@2.0.0-beta.23
+- @akinon/pz-b2b@2.0.0-beta.23
+- @akinon/pz-basket-gift-pack@2.0.0-beta.23
+- @akinon/pz-bkm@2.0.0-beta.23
+- @akinon/pz-checkout-gift-pack@2.0.0-beta.23
+- @akinon/pz-click-collect@2.0.0-beta.23
+- @akinon/pz-credit-payment@2.0.0-beta.23
+- @akinon/pz-cybersource-uc@2.0.0-beta.23
+- @akinon/pz-flow-payment@2.0.0-beta.23
+- @akinon/pz-google-pay@2.0.0-beta.23
+- @akinon/pz-gpay@2.0.0-beta.23
+- @akinon/pz-haso@2.0.0-beta.23
+- @akinon/pz-hepsipay@2.0.0-beta.23
+- @akinon/pz-masterpass@2.0.0-beta.23
+- @akinon/pz-masterpass-rest@2.0.0-beta.23
+- @akinon/pz-multi-basket@2.0.0-beta.23
+- @akinon/pz-one-click-checkout@2.0.0-beta.23
+- @akinon/pz-otp@2.0.0-beta.23
+- @akinon/pz-pay-on-delivery@2.0.0-beta.23
+- @akinon/pz-saved-card@2.0.0-beta.23
+- @akinon/pz-similar-products@2.0.0-beta.23
+- @akinon/pz-tabby-extension@2.0.0-beta.23
+- @akinon/pz-tamara-extension@2.0.0-beta.23
+- @akinon/pz-theme@2.0.0-beta.23
+- @akinon/pz-virtual-try-on@2.0.0-beta.23
+
 ## 2.0.0-beta.22
 
 ### Patch Changes

package/app-template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectzeronext",
-  "version": "2.0.0-beta.22",
+  "version": "2.0.0-beta.24",
   "private": true,
   "license": "MIT",
   "scripts": {
@@ -24,33 +24,33 @@
     "test:middleware": "jest middleware-matcher.test.ts --bail"
   },
   "dependencies": {
-    "@akinon/next": "2.0.0-beta.22",
-    "@akinon/pz-akifast": "2.0.0-beta.22",
-    "@akinon/pz-apple-pay": "2.0.0-beta.22",
-    "@akinon/pz-b2b": "2.0.0-beta.22",
-    "@akinon/pz-basket-gift-pack": "2.0.0-beta.22",
-    "@akinon/pz-bkm": "2.0.0-beta.22",
-    "@akinon/pz-checkout-gift-pack": "2.0.0-beta.22",
-    "@akinon/pz-click-collect": "2.0.0-beta.22",
-    "@akinon/pz-credit-payment": "2.0.0-beta.22",
-    "@akinon/pz-cybersource-uc": "2.0.0-beta.22",
-    "@akinon/pz-flow-payment": "2.0.0-beta.22",
-    "@akinon/pz-google-pay": "2.0.0-beta.22",
-    "@akinon/pz-gpay": "2.0.0-beta.22",
-    "@akinon/pz-haso": "2.0.0-beta.22",
-    "@akinon/pz-hepsipay": "2.0.0-beta.22",
-    "@akinon/pz-masterpass": "2.0.0-beta.22",
-    "@akinon/pz-masterpass-rest": "2.0.0-beta.22",
-    "@akinon/pz-multi-basket": "2.0.0-beta.22",
-    "@akinon/pz-one-click-checkout": "2.0.0-beta.22",
-    "@akinon/pz-otp": "2.0.0-beta.22",
-    "@akinon/pz-pay-on-delivery": "2.0.0-beta.22",
-    "@akinon/pz-saved-card": "2.0.0-beta.22",
-    "@akinon/pz-similar-products": "2.0.0-beta.22",
-    "@akinon/pz-tabby-extension": "2.0.0-beta.22",
-    "@akinon/pz-tamara-extension": "2.0.0-beta.22",
-    "@akinon/pz-theme": "2.0.0-beta.22",
-    "@akinon/pz-virtual-try-on": "2.0.0-beta.22",
+    "@akinon/next": "2.0.0-beta.24",
+    "@akinon/pz-akifast": "2.0.0-beta.24",
+    "@akinon/pz-apple-pay": "2.0.0-beta.24",
+    "@akinon/pz-b2b": "2.0.0-beta.24",
+    "@akinon/pz-basket-gift-pack": "2.0.0-beta.24",
+    "@akinon/pz-bkm": "2.0.0-beta.24",
+    "@akinon/pz-checkout-gift-pack": "2.0.0-beta.24",
+    "@akinon/pz-click-collect": "2.0.0-beta.24",
+    "@akinon/pz-credit-payment": "2.0.0-beta.24",
+    "@akinon/pz-cybersource-uc": "2.0.0-beta.24",
+    "@akinon/pz-flow-payment": "2.0.0-beta.24",
+    "@akinon/pz-google-pay": "2.0.0-beta.24",
+    "@akinon/pz-gpay": "2.0.0-beta.24",
+    "@akinon/pz-haso": "2.0.0-beta.24",
+    "@akinon/pz-hepsipay": "2.0.0-beta.24",
+    "@akinon/pz-masterpass": "2.0.0-beta.24",
+    "@akinon/pz-masterpass-rest": "2.0.0-beta.24",
+    "@akinon/pz-multi-basket": "2.0.0-beta.24",
+    "@akinon/pz-one-click-checkout": "2.0.0-beta.24",
+    "@akinon/pz-otp": "2.0.0-beta.24",
+    "@akinon/pz-pay-on-delivery": "2.0.0-beta.24",
+    "@akinon/pz-saved-card": "2.0.0-beta.24",
+    "@akinon/pz-similar-products": "2.0.0-beta.24",
+    "@akinon/pz-tabby-extension": "2.0.0-beta.24",
+    "@akinon/pz-tamara-extension": "2.0.0-beta.24",
+    "@akinon/pz-theme": "2.0.0-beta.24",
+    "@akinon/pz-virtual-try-on": "2.0.0-beta.24",
     "@hookform/resolvers": "2.9.0",
     "@next/third-parties": "16.1.6",
     "@react-google-maps/api": "2.17.1",
@@ -73,7 +73,7 @@
     "yup": "0.32.11"
   },
   "devDependencies": {
-    "@akinon/eslint-plugin-projectzero": "2.0.0-beta.22",
+    "@akinon/eslint-plugin-projectzero": "2.0.0-beta.24",
     "@semantic-release/changelog": "6.0.2",
     "@semantic-release/exec": "6.0.3",
     "@semantic-release/git": "10.0.1",

package/app-template/src/{middleware.ts → proxy.ts}

@@ -3,7 +3,7 @@ import { NextMiddleware, NextResponse } from 'next/server';
 
 /**
  * !IMPORTANT
- * Do not remove this file or withPzDefault middleware.
+ * Do not remove this file or withPzDefault wrapper.
  * It is required for the application to work properly.
  * If you need to add custom matcher, don't remove the existing one.
  */
@@ -18,7 +18,7 @@ export const config = {
   ]
 };
 
-const middleware: NextMiddleware = () =>
+const proxy: NextMiddleware = () =>
   // req: PzNextRequest,
   // event: NextFetchEvent
   {
@@ -32,4 +32,4 @@ const middleware: NextMiddleware = () =>
     return NextResponse.next();
   };
 
-export default withPzDefault(middleware);
+export default withPzDefault(proxy);

package/codemods/upgrade-to-2/index.js

@@ -0,0 +1,549 @@
+/**
+ * upgrade-to-2: orchestrator codemod that chains every step required to move
+ * a Project Zero brand project from pz-next 1.x to 2.0 beta.
+ *
+ * Steps (in order):
+ *   1. Preflight checks (git state, package.json, Node.js project)
+ *   2. Create a backup git branch (pre-upgrade-2-YYYYMMDD)
+ *   3. Bump package.json dependencies to the 2.0 target matrix
+ *   4. Run @next/codemod upgrade (Next 16 + React 19)
+ *   5. Run migrate-auth-v5 codemod (next-auth v4 -> v5)
+ *   6. Run sentry-9 codemod (only when @sentry/nextjs is present)
+ *   7. yarn clean && yarn install
+ *   8. yarn build (validation)
+ *   9. Summary report
+ *
+ * Out of scope in this first version:
+ *   - Tailwind v3 -> v4 migration (run manually with @tailwindcss/upgrade)
+ *   - migrate-segments codemod (separate task)
+ *
+ * Usage:
+ *   cd <brand-root>
+ *   npx @akinon/projectzero codemod --codemod=upgrade-to-2 [flags]
+ *
+ *   Flags:
+ *     --dry-run             Preview only. No package.json writes, no install,
+ *                           codemods invoked in dry-run where supported.
+ *     --skip-preflight      Skip git state / package.json checks
+ *     --skip-backup         Do not create pre-upgrade-2-* branch
+ *     --skip-bump           Do not modify package.json
+ *     --skip-next-codemod   Do not run @next/codemod upgrade
+ *     --skip-auth           Do not run migrate-auth-v5
+ *     --skip-sentry         Do not run sentry-9 (auto-skipped if not needed)
+ *     --skip-install        Do not run yarn install
+ *     --skip-build          Do not run yarn build
+ *     --interactive         Pause for confirmation after each step
+ *     --verbose             Extra logs
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync, spawnSync } = require('child_process');
+const readline = require('readline');
+
+const AUTH_CODEMOD = path.resolve(__dirname, '..', 'migrate-auth-v5');
+const SENTRY_CODEMOD = path.resolve(__dirname, '..', 'sentry-9');
+
+const TARGET_MATRIX = {
+  dependencies: {
+    next: '16.2.4',
+    react: '19.2.5',
+    'react-dom': '19.2.5',
+    'next-auth': '5.0.0-beta.25',
+    '@akinon/next': 'beta'
+  },
+  devDependencies: {
+    '@types/react': '19.2.14',
+    '@types/react-dom': '19.2.3',
+    'eslint-config-next': '16.2.4',
+    tailwindcss: '3.4.17',
+    '@akinon/projectzero': 'beta',
+    '@akinon/eslint-plugin-projectzero': 'beta',
+    '@akinon/tsconfig': 'beta'
+  },
+  conditional: {
+    '@sentry/nextjs': '^9.0.0'
+  }
+};
+
+const STEP_COLUMN_WIDTH = 32;
+
+function log(msg) {
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  console.log(`[${ts}] ${msg}`);
+}
+
+function logStep(step, msg) {
+  const padded = step.padEnd(STEP_COLUMN_WIDTH, ' ');
+  log(`${padded} ${msg}`);
+}
+
+function runCommand(cmd, { cwd, dryRun, verbose }) {
+  if (dryRun) {
+    log(`[DRY] ${cmd}`);
+    return { status: 0, dry: true };
+  }
+  if (verbose) log(`$ ${cmd}`);
+  try {
+    execSync(cmd, { cwd, stdio: 'inherit' });
+    return { status: 0 };
+  } catch (err) {
+    return { status: err.status || 1, error: err };
+  }
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.question(`${question} [Y/n] `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() !== 'n');
+    });
+  });
+}
+
+function parseArgs(argv) {
+  const flags = {
+    dryRun: argv.includes('--dry-run'),
+    skipPreflight: argv.includes('--skip-preflight'),
+    skipBackup: argv.includes('--skip-backup'),
+    skipBump: argv.includes('--skip-bump'),
+    skipNextCodemod: argv.includes('--skip-next-codemod'),
+    skipAuth: argv.includes('--skip-auth'),
+    skipSentry: argv.includes('--skip-sentry'),
+    skipInstall: argv.includes('--skip-install'),
+    skipBuild: argv.includes('--skip-build'),
+    interactive: argv.includes('--interactive'),
+    verbose: argv.includes('--verbose')
+  };
+  return flags;
+}
+
+function readPackageJson(cwd) {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+}
+
+function writePackageJson(cwd, pkg) {
+  const pkgPath = path.join(cwd, 'package.json');
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+}
+
+function stepPreflight(cwd, flags) {
+  logStep('[1/9] Preflight', 'starting');
+
+  const pkg = readPackageJson(cwd);
+  if (!pkg) {
+    throw new Error('No package.json found in working directory');
+  }
+
+  if (!pkg.dependencies?.next && !pkg.devDependencies?.next) {
+    throw new Error('This does not appear to be a Next.js project (no `next` dependency)');
+  }
+
+  const gitStatus = spawnSync('git', ['status', '--porcelain'], {
+    cwd,
+    encoding: 'utf-8'
+  });
+  if (gitStatus.status !== 0) {
+    throw new Error('git not available or not a git repo');
+  }
+  const dirty = gitStatus.stdout.trim().length > 0;
+  if (dirty && !flags.dryRun) {
+    throw new Error(
+      'Working directory has uncommitted changes. Commit or stash before running upgrade-to-2.'
+    );
+  }
+
+  const currentNext =
+    pkg.dependencies?.next || pkg.devDependencies?.next || 'unknown';
+  const currentReact = pkg.dependencies?.react || 'unknown';
+  const currentAuth = pkg.dependencies?.['next-auth'] || 'unknown';
+  const currentAkinon = pkg.dependencies?.['@akinon/next'] || 'unknown';
+
+  log(`  Current: next@${currentNext} react@${currentReact} next-auth@${currentAuth} @akinon/next@${currentAkinon}`);
+  log(`  Target:  next@${TARGET_MATRIX.dependencies.next} react@${TARGET_MATRIX.dependencies.react} next-auth@${TARGET_MATRIX.dependencies['next-auth']} @akinon/next@beta`);
+
+  logStep('[1/9] Preflight', 'ok');
+}
+
+function stepBackup(cwd, flags) {
+  if (flags.skipBackup) {
+    logStep('[2/9] Backup branch', 'skipped');
+    return null;
+  }
+  const today = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+  const branchName = `pre-upgrade-2-${today}`;
+
+  if (flags.dryRun) {
+    logStep('[2/9] Backup branch', `[DRY] git branch ${branchName}`);
+    return branchName;
+  }
+
+  const existing = spawnSync(
+    'git',
+    ['rev-parse', '--verify', branchName],
+    { cwd, encoding: 'utf-8' }
+  );
+  if (existing.status === 0) {
+    logStep('[2/9] Backup branch', `already exists: ${branchName}`);
+    return branchName;
+  }
+
+  const result = spawnSync('git', ['branch', branchName], {
+    cwd,
+    stdio: 'inherit'
+  });
+  if (result.status !== 0) {
+    throw new Error(`Failed to create backup branch ${branchName}`);
+  }
+  logStep('[2/9] Backup branch', `created ${branchName}`);
+  return branchName;
+}
+
+function bumpDepsSection(section, matrix) {
+  const changes = [];
+  if (!section) return { section: section || {}, changes };
+  for (const [name, version] of Object.entries(matrix)) {
+    if (section[name] !== undefined && section[name] !== version) {
+      changes.push(`${name}: ${section[name]} -> ${version}`);
+      section[name] = version;
+    }
+  }
+  return { section, changes };
+}
+
+function pinNextScriptsToWebpack(pkg) {
+  // Next 16 defaults build/dev to Turbopack, which surfaces bundle-time
+  // errors for Node APIs used on the edge runtime (e.g. CompressionStream
+  // inside @akinon/next/lib/cache.ts). pz-next itself ships with
+  // `next dev --webpack` / `next build --webpack` until those are fixed;
+  // brand projects need the same flag to build successfully.
+  const changes = [];
+  if (!pkg.scripts) return changes;
+
+  ['dev', 'build'].forEach((scriptName) => {
+    const current = pkg.scripts[scriptName];
+    if (typeof current !== 'string') return;
+    if (current.includes('--webpack')) return;
+    if (!/\bnext\s+(dev|build)\b/.test(current)) return;
+    const updated = current.replace(
+      /\bnext\s+(dev|build)\b/,
+      'next $1 --webpack'
+    );
+    pkg.scripts[scriptName] = updated;
+    changes.push(`scripts.${scriptName}: "${current}" -> "${updated}"`);
+  });
+
+  return changes;
+}
+
+function stepBump(cwd, flags) {
+  if (flags.skipBump) {
+    logStep('[3/9] Bump deps', 'skipped');
+    return { hasSentry: false, changes: [] };
+  }
+
+  const pkg = readPackageJson(cwd);
+  const hasSentry = Boolean(pkg.dependencies?.['@sentry/nextjs']);
+
+  const allChanges = [];
+  const deps = bumpDepsSection(pkg.dependencies, TARGET_MATRIX.dependencies);
+  allChanges.push(...deps.changes);
+  pkg.dependencies = deps.section;
+
+  const devDeps = bumpDepsSection(
+    pkg.devDependencies,
+    TARGET_MATRIX.devDependencies
+  );
+  allChanges.push(...devDeps.changes);
+  pkg.devDependencies = devDeps.section;
+
+  if (hasSentry) {
+    const sentryDeps = bumpDepsSection(pkg.dependencies, {
+      '@sentry/nextjs': TARGET_MATRIX.conditional['@sentry/nextjs']
+    });
+    allChanges.push(...sentryDeps.changes);
+    pkg.dependencies = sentryDeps.section;
+  }
+
+  const scriptChanges = pinNextScriptsToWebpack(pkg);
+  allChanges.push(...scriptChanges);
+
+  if (allChanges.length === 0) {
+    logStep('[3/9] Bump deps', 'already at target, no changes');
+    return { hasSentry, changes: [] };
+  }
+
+  if (flags.dryRun) {
+    logStep('[3/9] Bump deps', `[DRY] ${allChanges.length} changes`);
+    allChanges.forEach((c) => log(`  - ${c}`));
+  } else {
+    writePackageJson(cwd, pkg);
+    logStep('[3/9] Bump deps', `${allChanges.length} changes applied`);
+    if (flags.verbose) allChanges.forEach((c) => log(`  - ${c}`));
+  }
+
+  return { hasSentry, changes: allChanges };
+}
+
+function stepNextCodemod(cwd, flags) {
+  if (flags.skipNextCodemod) {
+    logStep('[5/9] Next codemod', 'skipped');
+    return { ok: true };
+  }
+  const cmd = flags.dryRun
+    ? 'npx --yes @next/codemod@latest upgrade latest --verbose'
+    : 'npx --yes @next/codemod@latest upgrade latest';
+  logStep('[5/9] Next codemod', `running ${cmd}`);
+  const result = runCommand(cmd, { cwd, dryRun: false, verbose: flags.verbose });
+  if (result.status !== 0) {
+    logStep('[5/9] Next codemod', `FAILED (exit ${result.status})`);
+    return { ok: false };
+  }
+  logStep('[5/9] Next codemod', 'ok');
+  return { ok: true };
+}
+
+function stepAuthCodemod(cwd, flags) {
+  if (flags.skipAuth) {
+    logStep('[6/9] Auth codemod', 'skipped');
+    return { ok: true };
+  }
+  logStep('[6/9] Auth codemod', 'running migrate-auth-v5');
+  try {
+    const prevArgv = process.argv;
+    process.argv = [
+      process.argv[0],
+      process.argv[1],
+      ...(flags.dryRun ? ['--dry-run'] : [])
+    ];
+    const codemod = require(AUTH_CODEMOD);
+    const savedCwd = process.cwd();
+    process.chdir(cwd);
+    const result = codemod.transform();
+    const finish = () => {
+      process.chdir(savedCwd);
+      process.argv = prevArgv;
+    };
+    if (result && typeof result.then === 'function') {
+      return result.then(
+        () => {
+          finish();
+          logStep('[6/9] Auth codemod', 'ok');
+          return { ok: true };
+        },
+        (err) => {
+          finish();
+          logStep('[6/9] Auth codemod', `FAILED: ${err.message}`);
+          return { ok: false };
+        }
+      );
+    }
+    finish();
+    logStep('[6/9] Auth codemod', 'ok');
+    return { ok: true };
+  } catch (err) {
+    logStep('[6/9] Auth codemod', `FAILED: ${err.message}`);
+    return { ok: false };
+  }
+}
+
+function stepSentryCodemod(cwd, flags, hasSentry) {
+  if (flags.skipSentry || !hasSentry) {
+    const reason = flags.skipSentry ? 'skipped' : 'no @sentry/nextjs, skipping';
+    logStep('[7/9] Sentry codemod', reason);
+    return { ok: true };
+  }
+  if (flags.dryRun) {
+    logStep('[7/9] Sentry codemod', '[DRY] would run sentry-9');
+    return { ok: true };
+  }
+  logStep('[7/9] Sentry codemod', 'running sentry-9');
+  try {
+    const savedCwd = process.cwd();
+    process.chdir(cwd);
+    const codemod = require(SENTRY_CODEMOD);
+    codemod.transform();
+    process.chdir(savedCwd);
+    logStep('[7/9] Sentry codemod', 'ok');
+    return { ok: true };
+  } catch (err) {
+    logStep('[7/9] Sentry codemod', `FAILED: ${err.message}`);
+    return { ok: false };
+  }
+}
+
+function stepInstall(cwd, flags) {
+  if (flags.skipInstall) {
+    logStep('[4/9] yarn install', 'skipped');
+    return { ok: true };
+  }
+  if (flags.dryRun) {
+    logStep('[4/9] yarn install', '[DRY] yarn clean && yarn');
+    return { ok: true };
+  }
+  logStep('[4/9] yarn install', 'running yarn clean && yarn');
+  const clean = runCommand('yarn clean', {
+    cwd,
+    dryRun: false,
+    verbose: flags.verbose
+  });
+  if (clean.status !== 0) {
+    log('  yarn clean failed, continuing with yarn install');
+  }
+  const install = runCommand('yarn', {
+    cwd,
+    dryRun: false,
+    verbose: flags.verbose
+  });
+  if (install.status !== 0) {
+    logStep('[4/9] yarn install', `FAILED (exit ${install.status})`);
+    return { ok: false };
+  }
+  logStep('[4/9] yarn install', 'ok');
+  return { ok: true };
+}
+
+function stepBuild(cwd, flags) {
+  if (flags.skipBuild) {
+    logStep('[8/9] yarn build', 'skipped');
+    return { ok: true };
+  }
+  if (flags.dryRun) {
+    logStep('[8/9] yarn build', '[DRY] yarn build');
+    return { ok: true };
+  }
+  logStep('[8/9] yarn build', 'running');
+  const result = runCommand('yarn build', {
+    cwd,
+    dryRun: false,
+    verbose: flags.verbose
+  });
+  if (result.status !== 0) {
+    logStep('[8/9] yarn build', `FAILED (exit ${result.status})`);
+    return { ok: false };
+  }
+  logStep('[8/9] yarn build', 'ok');
+  return { ok: true };
+}
+
+function countTodoMarkers(cwd) {
+  const authFile = path.join(cwd, 'src', 'auth.ts');
+  if (!fs.existsSync(authFile)) return 0;
+  const content = fs.readFileSync(authFile, 'utf-8');
+  return (content.match(/TODO:v5/g) || []).length;
+}
+
+function stepReport(cwd, results) {
+  logStep('[9/9] Report', 'summary');
+  const pkg = readPackageJson(cwd) || {};
+  const todoCount = countTodoMarkers(cwd);
+
+  console.log('\n==================== upgrade-to-2 summary ====================');
+  console.log(`  Preflight:       ${results.preflight ? 'ok' : 'failed'}`);
+  console.log(`  Backup branch:   ${results.backupBranch || 'skipped'}`);
+  console.log(`  Deps changes:    ${results.bumpChanges}`);
+  console.log(`  Install:         ${results.install ? 'ok' : 'FAILED'}`);
+  console.log(`  Next codemod:    ${results.nextCodemod ? 'ok' : 'FAILED'}`);
+  console.log(`  Auth codemod:    ${results.authCodemod ? 'ok' : 'FAILED'}`);
+  console.log(`  Sentry codemod:  ${results.sentryCodemod ? 'ok' : results.sentrySkippedReason || 'FAILED'}`);
+  console.log(`  Build:           ${results.build ? 'ok' : 'FAILED'}`);
+  console.log('');
+  console.log(`  Versions after:`);
+  console.log(`    next:         ${pkg.dependencies?.next || '-'}`);
+  console.log(`    react:        ${pkg.dependencies?.react || '-'}`);
+  console.log(`    next-auth:    ${pkg.dependencies?.['next-auth'] || '-'}`);
+  console.log(`    @akinon/next: ${pkg.dependencies?.['@akinon/next'] || '-'}`);
+  if (pkg.dependencies?.['@sentry/nextjs']) {
+    console.log(`    @sentry/nextjs: ${pkg.dependencies['@sentry/nextjs']}`);
+  }
+  console.log('');
+  if (todoCount > 0) {
+    console.log(`  Manual work left in src/auth.ts: ${todoCount} TODO:v5 markers`);
+    console.log(`    grep -n "TODO:v5" src/auth.ts`);
+  }
+  console.log('  Next steps (manual):');
+  console.log('    - Tailwind v4 migration: npx @tailwindcss/upgrade@latest');
+  console.log('    - Review backup branch: ' + (results.backupBranch || 'n/a'));
+  console.log('    - Run dev server and smoke test auth, cart, checkout');
+  console.log('==============================================================\n');
+}
+
+async function maybePause(flags, stepLabel) {
+  if (!flags.interactive) return true;
+  const ok = await confirm(`Continue after ${stepLabel}?`);
+  if (!ok) {
+    log('Aborted by user.');
+    process.exit(1);
+  }
+  return true;
+}
+
+async function transform() {
+  const cwd = path.resolve(process.cwd());
+  const flags = parseArgs(process.argv);
+
+  log(`upgrade-to-2 starting in ${cwd}${flags.dryRun ? ' (DRY RUN)' : ''}`);
+
+  const results = {};
+
+  try {
+    if (!flags.skipPreflight) {
+      stepPreflight(cwd, flags);
+      results.preflight = true;
+      await maybePause(flags, 'preflight');
+    } else {
+      logStep('[1/9] Preflight', 'skipped');
+      results.preflight = true;
+    }
+
+    results.backupBranch = stepBackup(cwd, flags);
+    await maybePause(flags, 'backup');
+
+    const bumpResult = stepBump(cwd, flags);
+    results.bumpChanges = bumpResult.changes.length;
+    const hasSentry = bumpResult.hasSentry;
+    await maybePause(flags, 'bump');
+
+    results.install = stepInstall(cwd, flags).ok;
+    await maybePause(flags, 'install');
+
+    results.nextCodemod = stepNextCodemod(cwd, flags).ok;
+    await maybePause(flags, 'next-codemod');
+
+    const authResult = stepAuthCodemod(cwd, flags);
+    const authAwaited = authResult && typeof authResult.then === 'function'
+      ? await authResult
+      : authResult;
+    results.authCodemod = authAwaited.ok;
+    await maybePause(flags, 'auth-codemod');
+
+    const sentryResult = stepSentryCodemod(cwd, flags, hasSentry);
+    results.sentryCodemod = sentryResult.ok;
+    if (flags.skipSentry) results.sentrySkippedReason = 'skipped';
+    else if (!hasSentry) results.sentrySkippedReason = 'no @sentry/nextjs';
+    await maybePause(flags, 'sentry-codemod');
+
+    results.build = stepBuild(cwd, flags).ok;
+  } catch (err) {
+    log(`FATAL: ${err.message}`);
+    process.exitCode = 1;
+  }
+
+  stepReport(cwd, results);
+  log('upgrade-to-2 done');
+}
+
+module.exports = { transform };
+
+if (require.main === module) {
+  transform().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/projectzero",
-  "version": "2.0.0-beta.22",
+  "version": "2.0.0-beta.24",
   "private": false,
   "description": "CLI tool to manage your Project Zero Next project",
   "bin": {