@decocms/start 2.11.0 → 2.13.0

package/.agents/skills/deco-migrate-script/SKILL.md

@@ -485,3 +485,41 @@ This script handles **Phases 0-6** of the [migration playbook](../deco-to-tansta
 - Phase 7-12 — Section registry tuning, route customization, matchers, async rendering, search
 
 The script gets you from "raw Fresh site" to "builds with `npm run build` and has ~0 old imports". Human work starts at runtime debugging and feature wiring.
+
+## Post-Migration Audit (`deco-post-cleanup`)
+
+After the migration script's compile phase passes, run the
+**`deco-post-cleanup`** audit to catch the residual cleanup the
+script leaves behind on existing-but-pre-framework-helpers sites:
+
+```bash
+# Read-only audit (default)
+npx -p @decocms/start deco-post-cleanup
+
+# Auto-fix the safe rules (dead-lib-shims, dead-runtime-shim, local-widgets-types)
+npx -p @decocms/start deco-post-cleanup --fix
+
+# CI gate: auto-fix safe rules, exit 2 if any warnings remain
+npx -p @decocms/start deco-post-cleanup --fix --strict
+```
+
+The audit covers 7 rules (delete dead lib shims, drop obsolete inline
+Vite plugins, delete dead `runtime.ts` invoke shim, delete site-local
+`withSiteGlobals` wrapper, repoint `~/lib/vtex-*` shim regressions,
+delete shadowed `widgets.ts`, surface orphan framework TODOs). The
+detection logic mirrors the canonical checklist at
+[`deco-to-tanstack-migration/references/post-migration-cleanup.md`](../deco-to-tanstack-migration/references/post-migration-cleanup.md).
+
+**Why `compile` and `audit` are complementary:**
+
+| Tool | Catches |
+|------|---------|
+| `phase-compile` (in this script) | TS5097, missing exports, type bugs — anything `tsc --noEmit` finds |
+| `deco-post-cleanup` (separate CLI) | Silent runtime stubs (e.g. dead `~/lib/vtex-*` shims that typecheck cleanly but resolve to `{}` at runtime) |
+
+`tsc` doesn't catch the silent-stub class of bug because the dead
+shim files have valid TypeScript signatures. The audit's pattern
+matches surface what compilation cannot.
+
+Source: `scripts/migrate-post-cleanup.ts` + `scripts/migrate/post-cleanup/`.
+Tests: `scripts/migrate/post-cleanup/runner.test.ts`.

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -8,25 +8,39 @@ after the site has been shipping for weeks.
 ## Run the audit first
 
 This whole checklist is now automated by the **`deco-post-cleanup`**
-audit script (added in `@decocms/start >= 2.11.0`). Run it from the
-site repo to get a structured report of which sections below actually
-apply to your codebase:
+audit script (added in `@decocms/start >= 2.11.0`, `--fix` mode in
+`>= 2.12.0`). Run it from the site repo to get a structured report
+of which sections below actually apply to your codebase:
 
 ```bash
 # Pretty text output, exits 0 unless --strict is passed
 npx -p @decocms/start deco-post-cleanup
 
-# Machine-readable JSON for CI dashboards
-npx -p @decocms/start deco-post-cleanup --json
+# Auto-apply mechanical fixes for the safe rules, then report what's left.
+# Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types.
+# Other rules stay detect-only — they require human judgment.
+npx -p @decocms/start deco-post-cleanup --fix
+
+# Combine for CI: auto-fix safe rules, fail (exit 2) if warnings remain.
+npx -p @decocms/start deco-post-cleanup --fix --strict
 
-# Fail the run (exit 2) if any warning-severity findings exist
-npx -p @decocms/start deco-post-cleanup --strict
+# Machine-readable JSON for dashboards
+npx -p @decocms/start deco-post-cleanup --json
 ```
 
 The audit covers all 7 rules below and prints the exact file path +
-suggested fix for each finding. It is **read-only** — auto-fix support
-is a planned follow-up. Use the audit to scope this checklist to the
-real, current findings instead of triaging the full document by hand.
+suggested fix for each finding. With `--fix`, the three safe rules
+auto-apply (`rm` for dead files, regex-anchored import rewrites for
+shadowed shims). The output explicitly tags rules that require manual
+work as `(0 fixed, manual)`, so you always know what's left after
+auto-fix runs.
+
+Real-world signal: on baggagio, `--fix` produced a byte-identical
+diff to the manual cleanup PR a human had just made (45 files,
++45/-53). On casaevideo-storefront (production), the audit caught
+six silent VTEX shim regressions that no `tsc --noEmit` run can
+detect — those still require manual cleanup until rule 5 gains a
+per-shim mapping table.
 
 ## 1. Delete unused `src/lib/*` shims
 

package/.cursor/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -5,6 +5,43 @@ recurring set of dead-code and boilerplate cleanup that every migrated
 site benefits from. Run this checklist before the first PR review, not
 after the site has been shipping for weeks.
 
+## Run the audit first
+
+This whole checklist is now automated by the **`deco-post-cleanup`**
+audit script (added in `@decocms/start >= 2.11.0`, `--fix` mode in
+`>= 2.12.0`). Run it from the site repo to get a structured report
+of which sections below actually apply to your codebase:
+
+```bash
+# Pretty text output, exits 0 unless --strict is passed
+npx -p @decocms/start deco-post-cleanup
+
+# Auto-apply mechanical fixes for the safe rules, then report what's left.
+# Safe rules: dead-lib-shims, dead-runtime-shim, local-widgets-types.
+# Other rules stay detect-only — they require human judgment.
+npx -p @decocms/start deco-post-cleanup --fix
+
+# Combine for CI: auto-fix safe rules, fail (exit 2) if warnings remain.
+npx -p @decocms/start deco-post-cleanup --fix --strict
+
+# Machine-readable JSON for dashboards
+npx -p @decocms/start deco-post-cleanup --json
+```
+
+The audit covers all 7 rules below and prints the exact file path +
+suggested fix for each finding. With `--fix`, the three safe rules
+auto-apply (`rm` for dead files, regex-anchored import rewrites for
+shadowed shims). The output explicitly tags rules that require manual
+work as `(0 fixed, manual)`, so you always know what's left after
+auto-fix runs.
+
+Real-world signal: on baggagio, `--fix` produced a byte-identical
+diff to the manual cleanup PR a human had just made (45 files,
++45/-53). On casaevideo-storefront (production), the audit caught
+six silent VTEX shim regressions that no `tsc --noEmit` run can
+detect — those still require manual cleanup until rule 5 gains a
+per-shim mapping table.
+
 ## 1. Delete unused `src/lib/*` shims
 
 The migration script's `templates/lib-utils.ts` generates 11 shim files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-cleanup-audit.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for Phase 9 (cleanup audit integration into migrate.ts).
+ *
+ * These exercise the wrapper logic — what it prints, when it fails,
+ * how it interacts with --strict and dry-run. The underlying audit
+ * rules are tested separately in post-cleanup/runner.test.ts; we
+ * stub the disk minimally here just to drive findings counts.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanupAudit } from "./phase-cleanup-audit";
+import { createContext } from "./types";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "deco-migrate-audit-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function makeCtx(overrides?: { dryRun?: boolean }) {
+  return createContext(tmpDir, {
+    dryRun: overrides?.dryRun ?? false,
+    verbose: false,
+  });
+}
+
+describe("cleanupAudit — dry-run", () => {
+  it("is a no-op in dry-run mode (returns false, no console output)", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx({ dryRun: true });
+    const failed = cleanupAudit(ctx);
+    expect(failed).toBe(false);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — empty site", () => {
+  it("prints success and returns false when there are no findings", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx);
+    expect(failed).toBe(false);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/No findings/);
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — info-only findings (e.g. local widgets.ts)", () => {
+  beforeEach(() => {
+    // Set up a finding for rule 6 (local-widgets-types):
+    // need src/types/widgets.ts + at least one importer.
+    fs.mkdirSync(path.join(tmpDir, "src", "types"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "types", "widgets.ts"),
+      "export type ImageWidget = string;\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, "src", "sections"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "sections", "Foo.tsx"),
+      'import type { ImageWidget } from "~/types/widgets";\nexport const x: ImageWidget = "y";\n',
+    );
+  });
+
+  it("prints the finding and returns false (info doesn't fail strict)", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: true });
+    expect(failed).toBe(false);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/Local src\/types\/widgets\.ts/);
+    expect(out).toMatch(/widgets\.ts/);
+    expect(out).toMatch(/deco-post-cleanup --fix/);
+    spy.mockRestore();
+  });
+});
+
+describe("cleanupAudit — warning findings (vtex-shim-regression)", () => {
+  beforeEach(() => {
+    // Trigger rule 5 (vtex-shim-regression, warning severity):
+    // any file outside src/lib/ that imports from ~/lib/vtex-*.
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "loaders", "Product.ts"),
+      'import { fetchSafe } from "~/lib/vtex-fetch";\nexport default fetchSafe;\n',
+    );
+  });
+
+  it("returns false in non-strict mode even with warning findings", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: false });
+    expect(failed).toBe(false);
+    spy.mockRestore();
+  });
+
+  it("returns true in --strict mode when warning findings exist", () => {
+    const spyLog = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    const failed = cleanupAudit(ctx, { strict: true });
+    expect(failed).toBe(true);
+    const out = spyLog.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/--strict/);
+    expect(out).toMatch(/failed the audit/);
+    spyLog.mockRestore();
+  });
+});
+
+describe("cleanupAudit — output truncation", () => {
+  beforeEach(() => {
+    // Fabricate >5 vtex-shim-regression findings to test the cap.
+    fs.mkdirSync(path.join(tmpDir, "src", "loaders"), { recursive: true });
+    for (let i = 0; i < 8; i++) {
+      fs.writeFileSync(
+        path.join(tmpDir, "src", "loaders", `Loader${i}.ts`),
+        'import { fetchSafe } from "~/lib/vtex-fetch";\n',
+      );
+    }
+  });
+
+  it("caps per-rule output at 5 with a 'and N more' suffix", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = makeCtx();
+    cleanupAudit(ctx);
+    const out = spy.mock.calls.map((c) => c.join(" ")).join("\n");
+    expect(out).toMatch(/and 3 more/);
+    spy.mockRestore();
+  });
+});

package/scripts/migrate/phase-cleanup-audit.ts

@@ -0,0 +1,105 @@
+/**
+ * Phase 9: Post-Migration Cleanup Audit
+ *
+ * Runs the same `deco-post-cleanup` audit logic as the standalone CLI,
+ * but inline at the tail of `deco-migrate`. The goal is to surface any
+ * residual debt the migration script can't fix on its own (e.g.
+ * silent vtex shim regressions, orphan TODOs, manual-review items)
+ * the moment the migration completes — without making the user
+ * remember a separate command.
+ *
+ * Behaviour:
+ * - Always READ-ONLY. Auto-fix is opt-in via the standalone CLI's
+ *   `--fix` flag — never invoked from inside the migration script
+ *   to keep the migration's mutation surface predictable.
+ * - Skipped in dry-run (no migrated output to scan).
+ * - Skipped via `--no-cleanup-audit` when integrated runs are noisy.
+ * - In `--strict` mode, returns true (caller exits 2) if any
+ *   warning-severity findings exist. Info findings never fail the
+ *   build — they're just hints.
+ */
+
+import { banner, bold, gray, green, red, yellow } from "./colors";
+import { realFsAdapter, runAudit } from "./post-cleanup/runner";
+import type { AuditReport, Severity } from "./post-cleanup/types";
+import type { MigrationContext } from "./types";
+
+export interface CleanupAuditOptions {
+  /** Promote warning findings to fatal (exit 2 from main). Default: false. */
+  strict?: boolean;
+}
+
+/**
+ * Returns `true` when the caller should exit with a non-zero code.
+ * Always false in normal mode — audit is informational by default.
+ */
+export function cleanupAudit(ctx: MigrationContext, opts: CleanupAuditOptions = {}): boolean {
+  if (ctx.dryRun) {
+    return false;
+  }
+
+  banner("Phase 9: Post-Migration Cleanup Audit");
+
+  const report = runAudit(ctx.sourceDir, realFsAdapter);
+
+  if (report.totalFindings === 0) {
+    console.log(`  ${green("✓")} No findings — migration output is clean.`);
+    return false;
+  }
+
+  printSummary(report);
+
+  const warnings = countSeverity(report, "warning");
+  const infos = countSeverity(report, "info");
+  const willFail = (opts.strict ?? false) && warnings > 0;
+
+  console.log("");
+  console.log(
+    `  ${bold("Audit:")} ${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`,
+  );
+  console.log(
+    `  ${gray("Run")} ${bold("deco-post-cleanup --fix")} ${gray("from this directory to auto-correct the safe rules,")}`,
+  );
+  console.log(`  ${gray("or see post-migration-cleanup.md for the full per-rule playbook.")}`);
+
+  if (willFail) {
+    console.log(
+      `\n  ${red("--strict:")} ${warnings} warning-severity finding(s) failed the audit.`,
+    );
+    return true;
+  }
+
+  return false;
+}
+
+function severityTag(sev: Severity, text: string): string {
+  if (sev === "warning") return yellow(text);
+  return gray(text);
+}
+
+function printSummary(report: AuditReport): void {
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    if (summary.findings.length === 0) continue;
+    const headColor = yellow;
+    console.log(
+      `  ${headColor(`[${idx}] ${summary.title}`)} ${gray(`(${summary.findings.length} found)`)}`,
+    );
+    // Cap the per-rule output so a noisy site doesn't drown the
+    // migration's own report. Standalone CLI shows everything.
+    const visible = summary.findings.slice(0, 5);
+    for (const f of visible) {
+      const tag = severityTag(f.severity, `[${f.severity.toUpperCase()}]`);
+      console.log(`      ${tag} ${bold(f.file)} — ${f.message}`);
+    }
+    const hidden = summary.findings.length - visible.length;
+    if (hidden > 0) {
+      console.log(`      ${gray(`...and ${hidden} more (run deco-post-cleanup for full list)`)}`);
+    }
+  }
+}
+
+function countSeverity(report: AuditReport, sev: Severity): number {
+  return report.rules.flatMap((r) => r.findings).filter((f) => f.severity === sev).length;
+}

package/scripts/migrate/post-cleanup/rules.ts

@@ -9,10 +9,47 @@
  * Rules are intentionally read-only here — `--fix` is a follow-up.
  */
 
-import type { Finding, Rule, RuleContext } from "./types";
+import type { Finding, FixAction, FsWriter, Rule, RuleContext } from "./types";
 
 const SRC_GLOB_EXCLUDES = ["node_modules", "dist", ".wrangler", ".vite", ".tanstack", "build"];
 
+/**
+ * Rewrite all `from "<oldSpec>"` (or `from '<oldSpec>'`) imports in
+ * `src/**` to `from "<newSpec>"`. Returns the list of site-relative
+ * paths actually changed so fix-action summaries can quote a count.
+ * Uses the write side of the FS adapter — never touches disk in unit
+ * tests.
+ *
+ * Intentionally string-anchored on the exact spec; will not pick up
+ * partial-prefix matches like `~/types/widgets-extra`.
+ */
+function rewriteImportSpec(
+  ctx: RuleContext,
+  writer: FsWriter,
+  oldSpec: string,
+  newSpec: string,
+): string[] {
+  const { siteDir, fs } = ctx;
+  const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+  const escaped = oldSpec.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`from\\s+(['"])${escaped}\\1`, "g");
+  const updated: string[] = [];
+  for (const abs of tsFiles) {
+    const content = fs.readText(abs);
+    if (!re.test(content)) {
+      re.lastIndex = 0;
+      continue;
+    }
+    re.lastIndex = 0;
+    const next = content.replace(re, (_m, q) => `from ${q}${newSpec}${q}`);
+    if (next !== content) {
+      writer.writeText(abs, next);
+      updated.push(abs.slice(siteDir.length + 1));
+    }
+  }
+  return updated;
+}
+
 /* ------------------------------------------------------------------ */
 /* Rule 1 — dead `src/lib/*` shims                                     */
 /* ------------------------------------------------------------------ */
@@ -64,6 +101,18 @@ const ruleDeadLibShims: Rule = {
     }
     return findings;
   },
+  applyFix({ siteDir }, findings, writer): FixAction[] {
+    const actions: FixAction[] = [];
+    for (const f of findings) {
+      writer.deleteFile(`${siteDir}/${f.file}`);
+      actions.push({
+        file: f.file,
+        kind: "delete",
+        detail: "deleted (all exports verified unused)",
+      });
+    }
+    return actions;
+  },
 };
 
 /* ------------------------------------------------------------------ */
@@ -135,6 +184,18 @@ const ruleDeadRuntimeShim: Rule = {
       },
     ];
   },
+  applyFix(ctx, findings, writer): FixAction[] {
+    if (findings.length === 0) return [];
+    const updated = rewriteImportSpec(ctx, writer, "~/runtime", "@decocms/start/sdk");
+    writer.deleteFile(`${ctx.siteDir}/src/runtime.ts`);
+    return [
+      {
+        file: "src/runtime.ts",
+        kind: "rewrite-imports+delete",
+        detail: `rewrote ${updated.length} import(s) → @decocms/start/sdk and deleted src/runtime.ts`,
+      },
+    ];
+  },
 };
 
 /* ------------------------------------------------------------------ */
@@ -232,6 +293,23 @@ const ruleLocalWidgetsTypes: Rule = {
       },
     ];
   },
+  applyFix(ctx, findings, writer): FixAction[] {
+    if (findings.length === 0) return [];
+    const updated = rewriteImportSpec(
+      ctx,
+      writer,
+      "~/types/widgets",
+      "@decocms/start/types/widgets",
+    );
+    writer.deleteFile(`${ctx.siteDir}/src/types/widgets.ts`);
+    return [
+      {
+        file: "src/types/widgets.ts",
+        kind: "rewrite-imports+delete",
+        detail: `rewrote ${updated.length} import(s) → @decocms/start/types/widgets and deleted src/types/widgets.ts`,
+      },
+    ];
+  },
 };
 
 /* ------------------------------------------------------------------ */

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { _internals, ALL_RULES } from "./rules";
 import { runAudit } from "./runner";
-import type { FsAdapter } from "./types";
+import type { FsAdapter, FsWriter } from "./types";
 
 /**
  * In-memory FsAdapter for tests. Maps absolute path → file content.
@@ -57,6 +57,75 @@ function makeFs(files: Record<string, string>): FsAdapter {
 
 const SITE = "/site";
 
+/**
+ * Mutable in-memory FS — read AND write share one backing store. Used
+ * for fix-mode tests. The `store` is exposed so tests can assert what
+ * the writer left behind (deletions and content rewrites).
+ */
+function makeMutableFs(initial: Record<string, string>): {
+  fs: FsAdapter;
+  writer: FsWriter;
+  store: Record<string, string>;
+  log: { kind: "delete" | "write"; absPath: string }[];
+} {
+  const store = Object.fromEntries(
+    Object.entries(initial).map(([k, v]) => [k.replace(/\\/g, "/"), v]),
+  );
+  const log: { kind: "delete" | "write"; absPath: string }[] = [];
+  const fs: FsAdapter = {
+    exists(absPath) {
+      return absPath.replace(/\\/g, "/") in store;
+    },
+    readText(absPath) {
+      const k = absPath.replace(/\\/g, "/");
+      if (!(k in store)) throw new Error(`ENOENT: ${absPath}`);
+      return store[k];
+    },
+    glob(siteDir, pattern, excludeDirs = []) {
+      const root = siteDir.replace(/\\/g, "/");
+      const all = Object.keys(store).filter((p) => p.startsWith(`${root}/`));
+      const filtered = all.filter((p) => {
+        const rel = p.slice(root.length + 1);
+        return !excludeDirs.some((dir) => rel.startsWith(`${dir}/`));
+      });
+      const branches = pattern.includes("{")
+        ? pattern
+            .match(/\{([^{}]+)\}/)![1]
+            .split(",")
+            .map((b) => pattern.replace(/\{[^{}]+\}/, b.trim()))
+        : [pattern];
+      const regexes = branches.map((p) => {
+        const re = p
+          .replace(/[.+^$()|]/g, "\\$&")
+          .replace(/\*\*\//g, "<<DBL>>")
+          .replace(/\*\*/g, "<<DBL>>")
+          .replace(/\*/g, "[^/]*")
+          .replace(/<<DBL>>/g, "(?:.*/)?");
+        return new RegExp(`^${re}$`);
+      });
+      return filtered
+        .filter((p) => {
+          const rel = p.slice(root.length + 1);
+          return regexes.some((re) => re.test(rel));
+        })
+        .sort();
+    },
+  };
+  const writer: FsWriter = {
+    deleteFile(absPath) {
+      const k = absPath.replace(/\\/g, "/");
+      delete store[k];
+      log.push({ kind: "delete", absPath: k });
+    },
+    writeText(absPath, content) {
+      const k = absPath.replace(/\\/g, "/");
+      store[k] = content;
+      log.push({ kind: "write", absPath: k });
+    },
+  };
+  return { fs, writer, store, log };
+}
+
 describe("runAudit — empty site", () => {
   it("returns zero findings on an empty tree", () => {
     const fs = makeFs({});
@@ -284,5 +353,108 @@ describe("runAudit — totals", () => {
     });
     const report = runAudit(SITE, fs);
     expect(report.totalFindings).toBe(3);
+    expect(report.totalFixActions).toBe(0);
+  });
+
+  it("supportsAutoFix flag reflects rule capability", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const supported = report.rules
+      .filter((r) => r.supportsAutoFix)
+      .map((r) => r.rule)
+      .sort();
+    expect(supported).toEqual(
+      ["dead-lib-shims", "dead-runtime-shim", "local-widgets-types"].sort(),
+    );
+  });
+});
+
+describe("runAudit — fix mode", () => {
+  it("does not mutate when no writer is provided (default audit-only)", () => {
+    const { fs, store } = makeMutableFs({
+      "/site/src/lib/dead.ts": "export const foo = 1;\n",
+    });
+    const before = { ...store };
+    runAudit(SITE, fs);
+    expect(store).toEqual(before);
+  });
+
+  it("fix mode deletes a dead-lib shim and reports the action", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/lib/dead.ts": "export const foo = 1;\n",
+      "/site/src/sections/Other.tsx": 'export const x = "y";\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].kind).toBe("delete");
+    expect(r.fixes![0].file).toBe("src/lib/dead.ts");
+    expect("/site/src/lib/dead.ts" in store).toBe(false);
+    expect("/site/src/sections/Other.tsx" in store).toBe(true);
+    expect(report.totalFixActions).toBe(1);
+  });
+
+  it("fix mode rewrites runtime imports + deletes runtime.ts", () => {
+    const { fs, writer, store, log } = makeMutableFs({
+      "/site/src/runtime.ts":
+        "export const invoke = createNestedInvokeProxy();\nexport function createNestedInvokeProxy() { return {}; }\n",
+      "/site/src/sections/A.tsx": 'import { invoke } from "~/runtime";\nconsole.log(invoke);\n',
+      "/site/src/sections/B.tsx": "import { invoke } from '~/runtime';\nconsole.log(invoke);\n",
+      "/site/src/sections/C.tsx":
+        'import { other } from "~/something-else";\nconsole.log(other);\n',
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].detail).toMatch(/rewrote 2 import/);
+    expect("/site/src/runtime.ts" in store).toBe(false);
+    expect(store["/site/src/sections/A.tsx"]).toContain('"@decocms/start/sdk"');
+    expect(store["/site/src/sections/B.tsx"]).toContain("'@decocms/start/sdk'");
+    expect(store["/site/src/sections/C.tsx"]).toContain('"~/something-else"');
+    expect(log.filter((e) => e.kind === "delete")).toHaveLength(1);
+    expect(log.filter((e) => e.kind === "write")).toHaveLength(2);
+  });
+
+  it("fix mode rewrites widgets imports + deletes widgets.ts", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/types/widgets.ts": "export type ImageWidget = string;\n",
+      "/site/src/sections/A.tsx":
+        'import type { ImageWidget } from "~/types/widgets";\nexport const x: ImageWidget = "y";\n',
+      "/site/src/sections/B.tsx":
+        "import type { ImageWidget } from '~/types/widgets';\nexport const y: ImageWidget = 'z';\n",
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "local-widgets-types")!;
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].detail).toMatch(/rewrote 2 import/);
+    expect("/site/src/types/widgets.ts" in store).toBe(false);
+    expect(store["/site/src/sections/A.tsx"]).toContain('"@decocms/start/types/widgets"');
+    expect(store["/site/src/sections/B.tsx"]).toContain("'@decocms/start/types/widgets'");
+  });
+
+  it("fix mode is a no-op for rules without applyFix (e.g. framework-todos)", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/sections/Foo.tsx": "// TODO: move into decoVitePlugin\nexport const x = 1;\n",
+    });
+    const beforeStore = { ...store };
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "framework-todos")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toBeUndefined();
+    expect(r.supportsAutoFix).toBe(false);
+    expect(store).toEqual(beforeStore);
+  });
+
+  it("fix mode rewrites only exact matches, not prefix collisions", () => {
+    const { fs, writer, store } = makeMutableFs({
+      "/site/src/types/widgets.ts": "export type ImageWidget = string;\n",
+      "/site/src/sections/A.tsx":
+        'import type { ImageWidget } from "~/types/widgets";\nimport thing from "~/types/widgets-extra";\n',
+    });
+    runAudit(SITE, fs, { writer });
+    expect(store["/site/src/sections/A.tsx"]).toContain('"@decocms/start/types/widgets"');
+    expect(store["/site/src/sections/A.tsx"]).toContain('"~/types/widgets-extra"');
   });
 });

package/scripts/migrate/post-cleanup/runner.ts

@@ -8,22 +8,45 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ALL_RULES } from "./rules";
-import type { AuditReport, FsAdapter, Rule, RuleSummary } from "./types";
+import type { AuditReport, FsAdapter, FsWriter, Rule, RuleSummary } from "./types";
+
+export interface RunAuditOptions {
+  /**
+   * When set, rules with an `applyFix` implementation will run their
+   * fix and the report will include the resulting `FixAction[]`.
+   * Without this, the runner is purely read-only.
+   */
+  writer?: FsWriter;
+  /** Restrict to a subset of rules (defaults to all). */
+  rules?: Rule[];
+}
 
 export function runAudit(
   siteDir: string,
   adapter: FsAdapter,
-  rules: Rule[] = ALL_RULES,
+  options: RunAuditOptions = {},
 ): AuditReport {
-  const summaries: RuleSummary[] = rules.map((r) => ({
-    rule: r.id,
-    title: r.title,
-    findings: r.run({ siteDir, fs: adapter }),
-  }));
+  const rules = options.rules ?? ALL_RULES;
+  const summaries: RuleSummary[] = rules.map((rule) => {
+    const findings = rule.run({ siteDir, fs: adapter });
+    const supportsAutoFix = typeof rule.applyFix === "function";
+    let fixes: RuleSummary["fixes"];
+    if (options.writer && rule.applyFix && findings.length > 0) {
+      fixes = rule.applyFix({ siteDir, fs: adapter }, findings, options.writer);
+    }
+    return {
+      rule: rule.id,
+      title: rule.title,
+      findings,
+      supportsAutoFix,
+      fixes,
+    };
+  });
   return {
     site: siteDir,
     rules: summaries,
     totalFindings: summaries.reduce((acc, s) => acc + s.findings.length, 0),
+    totalFixActions: summaries.reduce((acc, s) => acc + (s.fixes?.length ?? 0), 0),
   };
 }
 
@@ -95,3 +118,20 @@ export const realFsAdapter: FsAdapter = {
     return matches.sort();
   },
 };
+
+/**
+ * Real disk writer used by the CLI when `--fix` is on. Tests should
+ * use a recording adapter and never instantiate this.
+ *
+ * `deleteFile` is intentionally tolerant: if the file is already gone
+ * (race with a previous fix or manual cleanup), we treat that as a
+ * no-op rather than crashing the audit.
+ */
+export const realFsWriter: FsWriter = {
+  deleteFile(absPath: string) {
+    if (fs.existsSync(absPath)) fs.unlinkSync(absPath);
+  },
+  writeText(absPath: string, content: string) {
+    fs.writeFileSync(absPath, content, "utf-8");
+  },
+};

package/scripts/migrate/post-cleanup/types.ts

@@ -31,12 +31,21 @@ export interface RuleSummary {
   /** Human-readable section title. */
   title: string;
   findings: Finding[];
+  /** Populated only when fix mode is on. */
+  fixes?: FixAction[];
+  /**
+   * True when the rule has an `applyFix` implementation. Lets the CLI
+   * tell users which findings would auto-fix vs require manual work.
+   */
+  supportsAutoFix: boolean;
 }
 
 export interface AuditReport {
   site: string;
   rules: RuleSummary[];
   totalFindings: number;
+  /** Total fix actions across all rules (0 if not in fix mode). */
+  totalFixActions: number;
 }
 
 /**
@@ -59,8 +68,39 @@ export interface RuleContext {
   fs: FsAdapter;
 }
 
+/**
+ * Mutating side of the FS adapter. Kept separate from `FsAdapter` so
+ * read-only audits (the default) cannot accidentally write. Tests
+ * substitute a recorder that captures actions without touching disk.
+ */
+export interface FsWriter {
+  deleteFile(absPath: string): void;
+  writeText(absPath: string, content: string): void;
+}
+
+/**
+ * One concrete change applied (or that would have been applied) by a
+ * rule's `applyFix` implementation. Consumed by the CLI to render a
+ * summary, and by the JSON output for CI dashboards.
+ */
+export interface FixAction {
+  /** Site-relative path the action targets. */
+  file: string;
+  /** "delete" | "rewrite-imports" | future: "edit" — kept open. */
+  kind: string;
+  /** Human-readable description, e.g. "deleted" or "rewrote 44 imports". */
+  detail: string;
+}
+
 export interface Rule {
   id: string;
   title: string;
   run(ctx: RuleContext): Finding[];
+  /**
+   * Optional. Implement for rules whose findings can be safely
+   * auto-corrected. Called only when the runner is in fix mode.
+   * Must return one or more `FixAction`s describing what changed
+   * (used both for output and for tests with a stubbed writer).
+   */
+  applyFix?(ctx: RuleContext, findings: Finding[], writer: FsWriter): FixAction[];
 }

package/scripts/migrate/source-layout.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import {
+  detectSourceLayout,
+  explainNonClassicLayout,
+  type FsLike,
+  type SourceLayout,
+} from "./source-layout";
+
+/**
+ * In-memory FsLike for tests. Holds a Set of paths that "exist" — no
+ * content needed since `detectSourceLayout` only calls `existsSync`.
+ */
+function makeFs(paths: string[]): FsLike {
+  const set = new Set(paths.map((p) => p.replace(/\\/g, "/")));
+  return {
+    existsSync(p: string) {
+      return set.has(p.replace(/\\/g, "/"));
+    },
+  };
+}
+
+const SITE = "/site";
+
+describe("detectSourceLayout — classic layout", () => {
+  it("classifies a site with sections/ at root as classic", () => {
+    const fs = makeFs(["/site/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("classic");
+  });
+
+  it("classifies multi-dir root layout as classic", () => {
+    const fs = makeFs(["/site/sections", "/site/islands", "/site/components", "/site/loaders"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("classic");
+  });
+
+  it("any single recognised root dir is enough", () => {
+    for (const d of ["sections", "islands", "components", "loaders", "actions"]) {
+      const fs = makeFs([`/site/${d}`]);
+      expect(detectSourceLayout(SITE, fs)).toBe("classic");
+    }
+  });
+});
+
+describe("detectSourceLayout — modern layout", () => {
+  it("classifies src/sections-only as modern", () => {
+    const fs = makeFs(["/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("modern");
+  });
+
+  it("classifies multi-dir src/ layout as modern", () => {
+    const fs = makeFs(["/site/src/sections", "/site/src/islands", "/site/src/components"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("modern");
+  });
+});
+
+describe("detectSourceLayout — mixed layout", () => {
+  it("flags both root + src/ as mixed", () => {
+    const fs = makeFs(["/site/sections", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("mixed");
+  });
+
+  it("flags partial overlap as mixed (root islands + src sections)", () => {
+    const fs = makeFs(["/site/islands", "/site/src/sections"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("mixed");
+  });
+});
+
+describe("detectSourceLayout — empty layout", () => {
+  it("returns empty when neither root nor src/ has recognised dirs", () => {
+    const fs = makeFs(["/site/package.json", "/site/README.md"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("empty");
+  });
+
+  it("returns empty for an unrelated dir", () => {
+    const fs = makeFs(["/site/random-dir/x.txt"]);
+    expect(detectSourceLayout(SITE, fs)).toBe("empty");
+  });
+});
+
+describe("detectSourceLayout — works against the real disk", () => {
+  it("uses real fs by default", () => {
+    // Just call with no fsAdapter on a real path that doesn't exist —
+    // should return "empty" without throwing. Smoke check that the
+    // default-arg wiring works.
+    expect(detectSourceLayout("/this/does/not/exist")).toBe("empty");
+  });
+});
+
+describe("explainNonClassicLayout — message content", () => {
+  const cases: Array<[Exclude<SourceLayout, "classic">, string[]]> = [
+    ["modern", ['Modern Fresh "src/" layout', "Move src/sections", "File an issue"]],
+    ["mixed", ["Mixed layout", "pick one layout", "clean checkout"]],
+    [
+      "empty",
+      [
+        "No recognizable Deco layout",
+        "sections, islands, components, loaders, actions",
+        "--source",
+      ],
+    ],
+  ];
+
+  for (const [layout, fragments] of cases) {
+    it(`${layout}: includes site path + key guidance`, () => {
+      const msg = explainNonClassicLayout(layout, "/some/site");
+      expect(msg).toContain("/some/site");
+      for (const f of fragments) {
+        expect(msg).toContain(f);
+      }
+    });
+  }
+});

package/scripts/migrate/source-layout.ts

@@ -0,0 +1,103 @@
+/**
+ * Source-layout detection.
+ *
+ * Classic Fresh sites place sections, islands, components etc. at the
+ * repo root. Modern Fresh (post 1.6) and several community starters
+ * use a `src/` layout where everything lives under `src/sections/`,
+ * `src/islands/`, etc. The migration analyzer's `SKIP_DIRS` includes
+ * `"src"` (because the OUTPUT site stores migrated code there), so
+ * a modern-layout source would be silently scanned as if it were
+ * empty — yielding a near-empty migration with no helpful errors.
+ *
+ * This module classifies a source directory into one of:
+ *   - "classic": expected layout (sections/, islands/, …) at root
+ *   - "modern":  src/-layout (src/sections/, src/islands/, …)
+ *   - "mixed":   both root sections/ AND src/sections/ — usually a
+ *                half-migrated repo
+ *   - "empty":   nothing recognizable; could be a fresh scaffold
+ *
+ * The migration script consumes this for an early-abort with an
+ * actionable error message. Eventually the analyzer can be extended
+ * to scan `src/` natively, at which point the "modern" branch can
+ * proceed instead of aborting.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export type SourceLayout = "classic" | "modern" | "mixed" | "empty";
+
+const RECOGNISED_DIRS = ["sections", "islands", "components", "loaders", "actions"];
+
+export interface FsLike {
+  existsSync(p: string): boolean;
+}
+
+const realFs: FsLike = { existsSync: fs.existsSync };
+
+/**
+ * Classify the source directory's layout. Pure function — accepts
+ * a `FsLike` so unit tests can stub the disk without mocking node:fs.
+ */
+export function detectSourceLayout(sourceDir: string, fsAdapter: FsLike = realFs): SourceLayout {
+  const hasRootDir = RECOGNISED_DIRS.some((d) => fsAdapter.existsSync(path.join(sourceDir, d)));
+  const hasSrcDir = RECOGNISED_DIRS.some((d) =>
+    fsAdapter.existsSync(path.join(sourceDir, "src", d)),
+  );
+
+  if (hasRootDir && hasSrcDir) return "mixed";
+  if (hasSrcDir) return "modern";
+  if (hasRootDir) return "classic";
+  return "empty";
+}
+
+/**
+ * Build a human-readable, actionable message for a non-classic
+ * layout. Consumed by the CLI to print before exiting. Lives in
+ * this module so the test can pin the exact wording.
+ */
+export function explainNonClassicLayout(
+  layout: Exclude<SourceLayout, "classic">,
+  sourceDir: string,
+): string {
+  switch (layout) {
+    case "modern":
+      return [
+        `Modern Fresh "src/" layout detected at ${sourceDir}/src.`,
+        "",
+        "  This migration script currently scans only the classic root layout",
+        "  (sections/, islands/, components/, loaders/, actions/ at the repo root).",
+        "",
+        "  Workaround until native support lands:",
+        "  1. Move src/sections, src/islands, src/components, src/loaders, src/actions",
+        "     up one level to the repo root (the script's expected layout).",
+        "  2. Re-run the migration.",
+        "  3. (If desired) Restructure to a src/ layout post-migration — the",
+        "     TanStack Start scaffold uses src/ on the output side regardless.",
+        "",
+        "  File an issue with your site URL so this can be supported natively.",
+      ].join("\n");
+    case "mixed":
+      return [
+        `Mixed layout detected at ${sourceDir}.`,
+        "",
+        "  Both root sections/ and src/sections/ are present. This usually means",
+        "  the migration was previously run partially against this directory, or",
+        "  the source genuinely has parallel layouts (rare).",
+        "",
+        "  Resolution: pick one layout and remove the other before re-running.",
+        "  If this is a half-migrated repo, restore the original via git and",
+        "  run the migration against a clean checkout (--source <fresh-path>).",
+      ].join("\n");
+    case "empty":
+      return [
+        `No recognizable Deco layout found at ${sourceDir}.`,
+        "",
+        "  Expected one of these directories at the repo root or under src/:",
+        `    ${RECOGNISED_DIRS.join(", ")}`,
+        "",
+        "  Did you point --source at the correct directory? It should be the",
+        "  root of an existing Fresh-based Deco site, not the new TanStack site.",
+      ].join("\n");
+  }
+}

package/scripts/migrate-post-cleanup.ts

@@ -22,8 +22,8 @@
  */
 
 import * as path from "node:path";
-import { banner, bold, gray, green, red, yellow } from "./migrate/colors";
-import { realFsAdapter, runAudit } from "./migrate/post-cleanup/runner";
+import { banner, bold, cyan, gray, green, red, yellow } from "./migrate/colors";
+import { realFsAdapter, realFsWriter, runAudit } from "./migrate/post-cleanup/runner";
 import type { AuditReport, Severity } from "./migrate/post-cleanup/types";
 
 interface CliOpts {
@@ -31,6 +31,7 @@ interface CliOpts {
   json: boolean;
   strict: boolean;
   help: boolean;
+  fix: boolean;
 }
 
 function parseArgs(args: string[]): CliOpts {
@@ -38,6 +39,7 @@ function parseArgs(args: string[]): CliOpts {
   let json = false;
   let strict = false;
   let help = false;
+  let fix = false;
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
       case "--source":
@@ -49,13 +51,16 @@ function parseArgs(args: string[]): CliOpts {
       case "--strict":
         strict = true;
         break;
+      case "--fix":
+        fix = true;
+        break;
       case "--help":
       case "-h":
         help = true;
         break;
     }
   }
-  return { source, json, strict, help };
+  return { source, json, strict, help, fix };
 }
 
 function showHelp() {
@@ -70,6 +75,9 @@ function showHelp() {
 
   Options:
     --source <dir>   Site directory to audit (default: .)
+    --fix            Auto-apply mechanical fixes for the safe rules
+                     (dead-lib-shims, dead-runtime-shim, local-widgets-types).
+                     Other rules still detect-only.
     --json           Emit machine-readable JSON instead of pretty text
     --strict         Exit code 2 if any warning-severity findings exist
     --help, -h       Show this help
@@ -77,6 +85,8 @@ function showHelp() {
   Examples:
     npx -p @decocms/start deco-post-cleanup
     npx -p @decocms/start deco-post-cleanup --source ./my-site --json
+    npx -p @decocms/start deco-post-cleanup --fix
+    npx -p @decocms/start deco-post-cleanup --fix --strict   # fail CI if anything left
 
   See: .agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md
   `);
@@ -87,22 +97,36 @@ function severityColor(sev: Severity, text: string): string {
   return gray(text);
 }
 
-function printText(report: AuditReport): void {
-  banner("Post-Migration Cleanup Audit");
+function printText(report: AuditReport, fixMode: boolean): void {
+  banner(fixMode ? "Post-Migration Cleanup Audit (--fix)" : "Post-Migration Cleanup Audit");
   console.log(`  ${gray("Site:")} ${bold(report.site)}`);
   console.log(`  ${gray("Findings:")} ${bold(String(report.totalFindings))}`);
+  if (fixMode) {
+    console.log(`  ${gray("Auto-fixed:")} ${bold(String(report.totalFixActions))}`);
+  }
   console.log("");
 
   let idx = 0;
   for (const summary of report.rules) {
     idx++;
     const count = summary.findings.length;
+    const fixCount = summary.fixes?.length ?? 0;
     const headColor = count === 0 ? green : yellow;
-    console.log(`${headColor(`[${idx}] ${summary.title}`)} ${gray(`(${count} found)`)}`);
+    const suffix = fixMode
+      ? gray(`(${count} found, ${fixCount} fixed${summary.supportsAutoFix ? "" : ", manual"})`)
+      : gray(`(${count} found)`);
+    console.log(`${headColor(`[${idx}] ${summary.title}`)} ${suffix}`);
     for (const f of summary.findings) {
       const tag = severityColor(f.severity, `[${f.severity.toUpperCase()}]`);
       console.log(`    ${tag} ${bold(f.file)} — ${f.message}`);
-      if (f.fix) console.log(`        ${gray("fix:")} ${f.fix}`);
+      if (f.fix && !summary.fixes) {
+        console.log(`        ${gray("fix:")} ${f.fix}`);
+      }
+    }
+    if (summary.fixes) {
+      for (const a of summary.fixes) {
+        console.log(`    ${cyan("[FIXED]")} ${bold(a.file)} — ${a.detail}`);
+      }
     }
     if (count === 0) console.log(`    ${gray("(nothing to clean up)")}`);
     console.log("");
@@ -112,11 +136,15 @@ function printText(report: AuditReport): void {
     .flatMap((r) => r.findings)
     .filter((f) => f.severity === "warning").length;
   const infos = report.totalFindings - warnings;
-  console.log(
-    `${bold("Summary:")} ${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`,
-  );
+  const tail = fixMode
+    ? `${report.totalFindings} finding(s) — ${cyan(`${report.totalFixActions} auto-fixed`)}, ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`
+    : `${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`;
+  console.log(`${bold("Summary:")} ${tail}`);
   if (report.totalFindings > 0) {
-    console.log(gray("  See post-migration-cleanup.md for the canonical fix steps per rule."));
+    const hint = fixMode
+      ? "  Some rules require manual fixes — see post-migration-cleanup.md."
+      : "  Run with --fix to auto-correct the safe rules, or see post-migration-cleanup.md.";
+    console.log(gray(hint));
   }
 }
 
@@ -137,12 +165,14 @@ async function main() {
   }
 
   const siteDir = path.resolve(opts.source);
-  const report = runAudit(siteDir, realFsAdapter);
+  const report = runAudit(siteDir, realFsAdapter, {
+    writer: opts.fix ? realFsWriter : undefined,
+  });
 
   if (opts.json) {
     printJson(report);
   } else {
-    printText(report);
+    printText(report, opts.fix);
   }
 
   if (shouldFail(report, opts.strict)) {

package/scripts/migrate.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env tsx
+
 /**
  * Migration Script: Fresh/Deno/Preact → TanStack Start/React/Cloudflare Workers
  *
@@ -23,18 +24,20 @@
  *   6. Verify   — Smoke test the migrated output
  */
 
-import * as path from "node:path";
 import { execSync } from "node:child_process";
+import * as path from "node:path";
+import { banner, green, red, stat, yellow } from "./migrate/colors";
 import { loadConfig, validateConfig } from "./migrate/config";
-import { createContext, logPhase } from "./migrate/types";
 import { analyze } from "./migrate/phase-analyze";
-import { scaffold } from "./migrate/phase-scaffold";
-import { transform } from "./migrate/phase-transform";
 import { cleanup } from "./migrate/phase-cleanup";
+import { cleanupAudit } from "./migrate/phase-cleanup-audit";
+import { compile } from "./migrate/phase-compile";
 import { report } from "./migrate/phase-report";
+import { scaffold } from "./migrate/phase-scaffold";
+import { transform } from "./migrate/phase-transform";
 import { verify } from "./migrate/phase-verify";
-import { compile } from "./migrate/phase-compile";
-import { banner, stat, red, green, yellow } from "./migrate/colors";
+import { detectSourceLayout, explainNonClassicLayout } from "./migrate/source-layout";
+import { createContext, logPhase } from "./migrate/types";
 
 function parseArgs(args: string[]): {
   source: string;
@@ -44,6 +47,7 @@ function parseArgs(args: string[]): {
   strict: boolean;
   withBuild: boolean;
   noCompile: boolean;
+  noCleanupAudit: boolean;
 } {
   let source = ".";
   let dryRun = false;
@@ -52,6 +56,7 @@ function parseArgs(args: string[]): {
   let strict = false;
   let withBuild = false;
   let noCompile = false;
+  let noCleanupAudit = false;
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
@@ -73,6 +78,9 @@ function parseArgs(args: string[]): {
       case "--no-compile":
         noCompile = true;
         break;
+      case "--no-cleanup-audit":
+        noCleanupAudit = true;
+        break;
       case "--help":
       case "-h":
         help = true;
@@ -80,7 +88,16 @@ function parseArgs(args: string[]): {
     }
   }
 
-  return { source, dryRun, verbose, help, strict, withBuild, noCompile };
+  return {
+    source,
+    dryRun,
+    verbose,
+    help,
+    strict,
+    withBuild,
+    noCompile,
+    noCleanupAudit,
+  };
 }
 
 function showHelp() {
@@ -91,13 +108,15 @@ function showHelp() {
     npx -p @decocms/start deco-migrate [options]
 
   Options:
-    --source <dir>    Source directory (default: .)
-    --dry-run         Preview changes without writing files
-    --verbose         Show detailed output for every file
-    --strict          Fail (exit 2) when typecheck/build report errors
-    --with-build      Also run \`vite build\` after typecheck (slower)
-    --no-compile      Skip the post-bootstrap compile phase entirely
-    --help, -h        Show this help message
+    --source <dir>        Source directory (default: .)
+    --dry-run             Preview changes without writing files
+    --verbose             Show detailed output for every file
+    --strict              Fail (exit 2) when typecheck/build report errors
+    --with-build          Also run \`vite build\` after typecheck (slower)
+    --no-compile          Skip the post-bootstrap compile phase entirely
+    --no-cleanup-audit    Skip the post-migration cleanup audit (run separately
+                          via \`deco-post-cleanup\` if needed)
+    --help, -h            Show this help message
 
   Examples:
     npx -p @decocms/start deco-migrate --dry-run --verbose
@@ -137,6 +156,19 @@ async function main() {
     config: siteConfig,
   });
 
+  // Phase 0: Source-layout detection (early-abort for unsupported layouts).
+  // The analyzer assumes a classic root layout (sections/, islands/, ...);
+  // running it on a modern src/ layout silently yields a near-empty
+  // migration. Detect-and-abort here so the user gets an actionable error
+  // before we touch any files.
+  const layout = detectSourceLayout(sourceDir);
+  if (layout !== "classic") {
+    console.error(red(`Error: ${layout} source layout`));
+    console.error("");
+    console.error(explainNonClassicLayout(layout, sourceDir));
+    process.exit(2);
+  }
+
   try {
     // Phase 1: Analyze source
     analyze(ctx);
@@ -176,6 +208,17 @@ async function main() {
         process.exit(2);
       }
     }
+
+    // Phase 9: Post-migration cleanup audit
+    // Read-only scan that catches residual debt the migration script
+    // can't (or won't) fix. Always informational unless --strict is on,
+    // in which case warning-severity findings exit 2.
+    if (!opts.noCleanupAudit) {
+      const auditFailed = cleanupAudit(ctx, { strict: opts.strict });
+      if (auditFailed) {
+        process.exit(2);
+      }
+    }
   } catch (error) {
     console.error(`\n  ${red("Migration failed:")}`, error);
     process.exit(1);
@@ -210,7 +253,9 @@ function bootstrap(ctx: { sourceDir: string }) {
   run("npx tsr generate", "Generate TanStack routes");
 
   if (failures > 0) {
-    console.log(`\n  ${yellow("Bootstrap completed with warnings.")} Check errors above before running dev.\n`);
+    console.log(
+      `\n  ${yellow("Bootstrap completed with warnings.")} Check errors above before running dev.\n`,
+    );
   } else {
     console.log(`\n  ${green("Ready!")} Run \`${pm} run dev\` to start the dev server.\n`);
   }