@decocms/start 2.10.0 → 2.11.0

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

@@ -5,6 +5,29 @@ 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`). 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
+
+# Fail the run (exit 2) if any warning-severity findings exist
+npx -p @decocms/start deco-post-cleanup --strict
+```
+
+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.
+
 ## 1. Delete unused `src/lib/*` shims
 
 The migration script's `templates/lib-utils.ts` generates 11 shim files

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@decocms/start",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
   "bin": {
-    "deco-migrate": "./scripts/migrate.ts"
+    "deco-migrate": "./scripts/migrate.ts",
+    "deco-post-cleanup": "./scripts/migrate-post-cleanup.ts"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -59,6 +60,7 @@
     "./scripts/generate-schema": "./scripts/generate-schema.ts",
     "./scripts/generate-invoke": "./scripts/generate-invoke.ts",
     "./scripts/migrate": "./scripts/migrate.ts",
+    "./scripts/migrate-post-cleanup": "./scripts/migrate-post-cleanup.ts",
     "./scripts/tailwind-lint": "./scripts/tailwind-lint.ts",
     "./vite": "./src/vite/plugin.js",
     "./daemon": "./src/daemon/index.ts"

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

@@ -0,0 +1,293 @@
+/**
+ * Post-migration cleanup audit — rule implementations.
+ *
+ * Each rule mirrors a section in
+ * `.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md`.
+ * The intent is to take the human checklist and make it programmatically
+ * detectable so future migrations get the same scrubbing automatically.
+ *
+ * Rules are intentionally read-only here — `--fix` is a follow-up.
+ */
+
+import type { Finding, Rule, RuleContext } from "./types";
+
+const SRC_GLOB_EXCLUDES = ["node_modules", "dist", ".wrangler", ".vite", ".tanstack", "build"];
+
+/* ------------------------------------------------------------------ */
+/* Rule 1 — dead `src/lib/*` shims                                     */
+/* ------------------------------------------------------------------ */
+
+const EXPORT_RE = /^export\s+(?:function|const|interface|type|class)\s+([A-Za-z_][A-Za-z0-9_]*)/gm;
+
+function extractExports(content: string): string[] {
+  const out: string[] = [];
+  for (const m of content.matchAll(EXPORT_RE)) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+function symbolUsedOutsideLib(siteDir: string, fs: RuleContext["fs"], symbol: string): boolean {
+  const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+  const re = new RegExp(`\\b${symbol}\\b`);
+  for (const file of tsFiles) {
+    if (file.includes("/src/lib/")) continue;
+    const content = fs.readText(file);
+    if (re.test(content)) return true;
+  }
+  return false;
+}
+
+const ruleDeadLibShims: Rule = {
+  id: "dead-lib-shims",
+  title: "Dead src/lib/* shims",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const libFiles = fs.glob(siteDir, "src/lib/*.ts", SRC_GLOB_EXCLUDES);
+    if (libFiles.length === 0) return [];
+
+    const findings: Finding[] = [];
+    for (const abs of libFiles) {
+      const rel = abs.slice(siteDir.length + 1);
+      const content = fs.readText(abs);
+      const exports = extractExports(content);
+      if (exports.length === 0) continue;
+      const allDead = exports.every((s) => !symbolUsedOutsideLib(siteDir, fs, s));
+      if (!allDead) continue;
+      findings.push({
+        rule: "dead-lib-shims",
+        severity: "info",
+        file: rel,
+        message: `${exports.length} export(s), 0 external imports`,
+        fix: `rm ${rel}`,
+        meta: { exports },
+      });
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 2 — obsolete inline vite plugins                               */
+/* ------------------------------------------------------------------ */
+
+const OBSOLETE_VITE_PLUGINS: { name: string; reason: string }[] = [
+  {
+    name: "site-manual-chunks",
+    reason: "framework's decoVitePlugin() now owns chunking",
+  },
+  {
+    name: "deco-stub-meta-gen",
+    reason: "framework now stubs meta.gen.{json,ts} on the client by default",
+  },
+];
+
+const ruleObsoleteVitePlugins: Rule = {
+  id: "obsolete-vite-plugins",
+  title: "Obsolete inline Vite plugins",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    const candidates = ["vite.config.ts", "vite.config.js", "vite.config.mjs"];
+    for (const rel of candidates) {
+      const abs = `${siteDir}/${rel}`;
+      if (!fs.exists(abs)) continue;
+      const content = fs.readText(abs);
+      for (const plugin of OBSOLETE_VITE_PLUGINS) {
+        const re = new RegExp(`name:\\s*["']${plugin.name}["']`);
+        if (!re.test(content)) continue;
+        findings.push({
+          rule: "obsolete-vite-plugins",
+          severity: "warning",
+          file: rel,
+          message: `'${plugin.name}' plugin is obsolete — ${plugin.reason}`,
+          fix: `delete the inline '${plugin.name}' plugin from ${rel}`,
+          meta: { plugin: plugin.name },
+        });
+      }
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 3 — dead `src/runtime.ts` invoke shim                          */
+/* ------------------------------------------------------------------ */
+
+const ruleDeadRuntimeShim: Rule = {
+  id: "dead-runtime-shim",
+  title: "Dead src/runtime.ts invoke shim",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const abs = `${siteDir}/src/runtime.ts`;
+    if (!fs.exists(abs)) return [];
+    const content = fs.readText(abs);
+    // Heuristic: if the file's only meaningful exports are `invoke` /
+    // `createNestedInvokeProxy`, it's purely a shim.
+    const exports = extractExports(content);
+    const onlyInvokeShim =
+      exports.length > 0 && exports.every((e) => ["invoke", "createNestedInvokeProxy"].includes(e));
+    if (!onlyInvokeShim) return [];
+    return [
+      {
+        rule: "dead-runtime-shim",
+        severity: "info",
+        file: "src/runtime.ts",
+        message: `Only re-exports invoke (${exports.join(", ")}) — replace with @decocms/start/sdk`,
+        fix: 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts',
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 4 — site-local `withSiteGlobals` workaround                    */
+/* ------------------------------------------------------------------ */
+
+const ruleSiteLocalGlobals: Rule = {
+  id: "site-local-with-globals",
+  title: "Site-local withSiteGlobals wrapper",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    const candidates = fs.glob(siteDir, "src/**/withSiteGlobals.ts", SRC_GLOB_EXCLUDES);
+    for (const abs of candidates) {
+      const content = fs.readText(abs);
+      // Heuristic: any local definition (function/const) of withSiteGlobals or
+      // cmsRouteWithGlobals indicates a local wrapper, not a re-export from
+      // the framework. The framework version would just re-export.
+      const definesWrapper =
+        /(?:export\s+)?(?:function|const)\s+(?:withSiteGlobals|cmsRouteWithGlobals)\b/.test(
+          content,
+        );
+      const reExportsFromFramework = /from\s+['"]@decocms\/start\/routes['"]/.test(content);
+      if (!definesWrapper || reExportsFromFramework) continue;
+      const rel = abs.slice(siteDir.length + 1);
+      const lineCount = content.split("\n").length;
+      findings.push({
+        rule: "site-local-with-globals",
+        severity: "warning",
+        file: rel,
+        message: `Local wrapper (~${lineCount} LOC) — framework now exports withSiteGlobals from @decocms/start/routes`,
+        fix: "delete the local wrapper and import { withSiteGlobals } from '@decocms/start/routes'",
+        meta: { lineCount },
+      });
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 5 — `~/lib/vtex-*` shim regression                             */
+/* ------------------------------------------------------------------ */
+
+const ruleVtexShimRegression: Rule = {
+  id: "vtex-shim-regression",
+  title: "Imports from ~/lib/vtex-* (silent stub regression)",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    const findings: Finding[] = [];
+    const re = /from\s+['"]~\/lib\/vtex-([A-Za-z0-9-]+)['"]/g;
+    for (const abs of tsFiles) {
+      if (abs.includes("/src/lib/")) continue;
+      const content = fs.readText(abs);
+      const matches = [...content.matchAll(re)];
+      if (matches.length === 0) continue;
+      const rel = abs.slice(siteDir.length + 1);
+      const shims = [...new Set(matches.map((m) => `vtex-${m[1]}`))];
+      findings.push({
+        rule: "vtex-shim-regression",
+        severity: "warning",
+        file: rel,
+        message: `Imports from dead shim(s): ${shims.join(", ")} — runtime is silently stubbed`,
+        fix: "Repoint imports to '@decocms/apps/vtex/...' or 'apps/commerce/utils/...'",
+        meta: { shims },
+      });
+    }
+    return findings;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 6 — local `src/types/widgets.ts` shadowing framework           */
+/* ------------------------------------------------------------------ */
+
+const ruleLocalWidgetsTypes: Rule = {
+  id: "local-widgets-types",
+  title: "Local src/types/widgets.ts shadowing framework",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const abs = `${siteDir}/src/types/widgets.ts`;
+    if (!fs.exists(abs)) return [];
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+    const re = /from\s+['"]~\/types\/widgets['"]/;
+    let importCount = 0;
+    for (const f of tsFiles) {
+      if (f === abs) continue;
+      if (re.test(fs.readText(f))) importCount++;
+    }
+    return [
+      {
+        rule: "local-widgets-types",
+        severity: "info",
+        file: "src/types/widgets.ts",
+        message: `Local file shadows @decocms/start/types/widgets (used in ${importCount} place(s))`,
+        fix: 'rewrite imports to "@decocms/start/types/widgets" and rm src/types/widgets.ts',
+        meta: { importCount },
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* Rule 7 — orphan "TODO: framework" comments                          */
+/* ------------------------------------------------------------------ */
+
+const ruleFrameworkTodos: Rule = {
+  id: "framework-todos",
+  title: "Orphan TODOs deferring to the framework",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const tsFiles = [
+      ...fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES),
+      ...fs.glob(siteDir, "vite.config.ts", SRC_GLOB_EXCLUDES),
+    ];
+    const findings: Finding[] = [];
+    const re = /TODO[^\n]*?(?:deco|framework|move into)/i;
+    for (const abs of tsFiles) {
+      const content = fs.readText(abs);
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (!re.test(lines[i])) continue;
+        const rel = abs.slice(siteDir.length + 1);
+        findings.push({
+          rule: "framework-todos",
+          severity: "info",
+          file: `${rel}:${i + 1}`,
+          message: lines[i].trim().slice(0, 120),
+          fix: "Triage: shipped → adopt; deferred → file issue; obsolete → delete",
+        });
+      }
+    }
+    return findings;
+  },
+};
+
+export const ALL_RULES: Rule[] = [
+  ruleDeadLibShims,
+  ruleObsoleteVitePlugins,
+  ruleDeadRuntimeShim,
+  ruleSiteLocalGlobals,
+  ruleVtexShimRegression,
+  ruleLocalWidgetsTypes,
+  ruleFrameworkTodos,
+];
+
+/** Exported for direct unit tests. */
+export const _internals = {
+  extractExports,
+  symbolUsedOutsideLib,
+  rules: {
+    ruleDeadLibShims,
+    ruleObsoleteVitePlugins,
+    ruleDeadRuntimeShim,
+    ruleSiteLocalGlobals,
+    ruleVtexShimRegression,
+    ruleLocalWidgetsTypes,
+    ruleFrameworkTodos,
+  },
+};

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

@@ -0,0 +1,288 @@
+import { describe, expect, it } from "vitest";
+import { _internals, ALL_RULES } from "./rules";
+import { runAudit } from "./runner";
+import type { FsAdapter } from "./types";
+
+/**
+ * In-memory FsAdapter for tests. Maps absolute path → file content.
+ * `glob` does a literal substring-pattern match — good enough for our
+ * tests which never use complex globs.
+ */
+function makeFs(files: Record<string, string>): FsAdapter {
+  const norm = Object.fromEntries(
+    Object.entries(files).map(([k, v]) => [k.replace(/\\/g, "/"), v]),
+  );
+  return {
+    exists(absPath) {
+      return absPath.replace(/\\/g, "/") in norm;
+    },
+    readText(absPath) {
+      const key = absPath.replace(/\\/g, "/");
+      if (!(key in norm)) throw new Error(`ENOENT: ${absPath}`);
+      return norm[key];
+    },
+    glob(siteDir, pattern, excludeDirs = []) {
+      const root = siteDir.replace(/\\/g, "/");
+      const all = Object.keys(norm).filter((p) => p.startsWith(`${root}/`));
+      const filtered = all.filter((p) => {
+        const rel = p.slice(root.length + 1);
+        return !excludeDirs.some((dir) => rel.startsWith(`${dir}/`));
+      });
+      // Build a regex that handles ** and {a,b} the same way the real
+      // adapter does — but lighter, just enough for the test patterns.
+      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 SITE = "/site";
+
+describe("runAudit — empty site", () => {
+  it("returns zero findings on an empty tree", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    expect(report.site).toBe(SITE);
+    expect(report.totalFindings).toBe(0);
+    expect(report.rules).toHaveLength(ALL_RULES.length);
+    for (const r of report.rules) expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: dead-lib-shims", () => {
+  it("flags a shim whose only export is unreferenced", () => {
+    const fs = makeFs({
+      "/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);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/lib/dead.ts");
+    expect(r.findings[0].fix).toContain("rm src/lib/dead.ts");
+  });
+
+  it("does not flag a shim referenced from outside src/lib", () => {
+    const fs = makeFs({
+      "/site/src/lib/used.ts": "export function helper() { return 1; }\n",
+      "/site/src/sections/Caller.tsx": 'import { helper } from "~/lib/used";\nhelper();\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does not flag a shim with no exports at all (likely intentional empty file)", () => {
+    const fs = makeFs({
+      "/site/src/lib/empty.ts": "// nothing here\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags only when ALL exports are dead — partial use spares the file", () => {
+    const fs = makeFs({
+      "/site/src/lib/mixed.ts": "export const used = 1;\nexport const unused = 2;\n",
+      "/site/src/sections/Caller.tsx": 'import { used } from "~/lib/mixed";\nconsole.log(used);\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-lib-shims")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: obsolete-vite-plugins", () => {
+  it("detects site-manual-chunks", () => {
+    const fs = makeFs({
+      "/site/vite.config.ts": `
+        export default defineConfig({
+          plugins: [
+            { name: "site-manual-chunks", config() { return {}; } },
+          ],
+        });
+      `,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.plugin).toBe("site-manual-chunks");
+  });
+
+  it("detects deco-stub-meta-gen", () => {
+    const fs = makeFs({
+      "/site/vite.config.ts": 'plugins: [{ name: "deco-stub-meta-gen", enforce: "pre" }]',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.plugin).toBe("deco-stub-meta-gen");
+  });
+
+  it("returns zero findings when both are absent", () => {
+    const fs = makeFs({
+      "/site/vite.config.ts": 'plugins: [{ name: "react", enforce: "pre" }]',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: dead-runtime-shim", () => {
+  it("flags an invoke-only runtime.ts", () => {
+    const fs = makeFs({
+      "/site/src/runtime.ts":
+        "export const invoke = createNestedInvokeProxy();\nexport function createNestedInvokeProxy() { return {}; }\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toBe("src/runtime.ts");
+  });
+
+  it("does not flag a runtime.ts that exports site-specific helpers", () => {
+    const fs = makeFs({
+      "/site/src/runtime.ts": "export const invoke = {};\nexport const customHelper = () => 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: site-local-with-globals", () => {
+  it("flags a local cmsRouteWithGlobals wrapper", () => {
+    const lines = Array(120).fill("// boilerplate").join("\n");
+    const fs = makeFs({
+      "/site/src/server/routes/withSiteGlobals.ts": `${lines}\nexport function cmsRouteWithGlobals() { return {}; }\n`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "site-local-with-globals")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.lineCount).toBeGreaterThan(100);
+  });
+
+  it("does not flag a re-export from the framework", () => {
+    const fs = makeFs({
+      "/site/src/server/routes/withSiteGlobals.ts":
+        'export { withSiteGlobals } from "@decocms/start/routes";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "site-local-with-globals")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: vtex-shim-regression", () => {
+  it("flags imports from ~/lib/vtex-segment", () => {
+    const fs = makeFs({
+      "/site/src/sections/Foo.tsx": 'import { getSegment } from "~/lib/vtex-segment";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.shims).toContain("vtex-segment");
+  });
+
+  it("does not flag imports from src/lib itself", () => {
+    const fs = makeFs({
+      "/site/src/lib/vtex-segment.ts": 'import other from "~/lib/vtex-fetch";\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "vtex-shim-regression")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: local-widgets-types", () => {
+  it("flags presence of src/types/widgets.ts and counts imports", () => {
+    const fs = makeFs({
+      "/site/src/types/widgets.ts": "export type ImageWidget = string;\n",
+      "/site/src/sections/A.tsx": 'import type { ImageWidget } from "~/types/widgets";\n',
+      "/site/src/sections/B.tsx": 'import type { ImageWidget } from "~/types/widgets";\n',
+      "/site/src/sections/C.tsx": "export const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-widgets-types")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.importCount).toBe(2);
+  });
+
+  it("returns zero findings when the file does not exist", () => {
+    const fs = makeFs({
+      "/site/src/sections/A.tsx": "export const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "local-widgets-types")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("rule: framework-todos", () => {
+  it("flags TODOs that mention deco/framework/move into", () => {
+    const fs = makeFs({
+      "/site/src/sections/Foo.tsx":
+        "// TODO: move into decoVitePlugin in next release\nexport const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "framework-todos")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].file).toContain(":1");
+  });
+
+  it("does not flag unrelated TODOs", () => {
+    const fs = makeFs({
+      "/site/src/sections/Foo.tsx": "// TODO: i18n strings\nexport const x = 1;\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "framework-todos")!;
+    expect(r.findings).toEqual([]);
+  });
+});
+
+describe("internals", () => {
+  it("extractExports parses common forms (top-level, unindented)", () => {
+    const code = [
+      "export const a = 1;",
+      "export function b() {}",
+      "export interface C {}",
+      "export type D = string;",
+      "export class E {}",
+      "const private_ = 1;",
+    ].join("\n");
+    expect(_internals.extractExports(code).sort()).toEqual(["C", "D", "E", "a", "b"]);
+  });
+});
+
+describe("runAudit — totals", () => {
+  it("totalFindings sums across all rules", () => {
+    const fs = makeFs({
+      "/site/src/lib/dead.ts": "export const x = 1;\n",
+      "/site/vite.config.ts": 'plugins: [{ name: "site-manual-chunks", config() {} }]',
+      "/site/src/sections/Foo.tsx":
+        "// TODO: deco framework should own this\nexport const y = 2;\n",
+    });
+    const report = runAudit(SITE, fs);
+    expect(report.totalFindings).toBe(3);
+  });
+});

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

@@ -0,0 +1,97 @@
+/**
+ * Post-migration cleanup audit — orchestrator.
+ *
+ * `runAudit` is the testable, FS-injected entry. The CLI in
+ * `../../migrate-post-cleanup.ts` wires up the real disk adapter.
+ */
+
+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";
+
+export function runAudit(
+  siteDir: string,
+  adapter: FsAdapter,
+  rules: Rule[] = ALL_RULES,
+): AuditReport {
+  const summaries: RuleSummary[] = rules.map((r) => ({
+    rule: r.id,
+    title: r.title,
+    findings: r.run({ siteDir, fs: adapter }),
+  }));
+  return {
+    site: siteDir,
+    rules: summaries,
+    totalFindings: summaries.reduce((acc, s) => acc + s.findings.length, 0),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Real disk adapter                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Minimal recursive-walk glob — intentionally tiny, no external deps.
+ * Supports `**`, `*`, and `{a,b,c}` brace expansion.  Does NOT support
+ * extglob, negation, or `?`. That's fine: every pattern in this audit
+ * fits the supported subset.
+ */
+function expandBraces(pattern: string): string[] {
+  const m = pattern.match(/\{([^{}]+)\}/);
+  if (!m) return [pattern];
+  const [whole, inner] = m;
+  const start = pattern.indexOf(whole);
+  const before = pattern.slice(0, start);
+  const after = pattern.slice(start + whole.length);
+  const branches = inner.split(",");
+  return branches.flatMap((b) => expandBraces(`${before}${b}${after}`));
+}
+
+function patternToRegex(pattern: string): RegExp {
+  const re = pattern
+    .replace(/[.+^$()|]/g, "\\$&")
+    .replace(/\*\*\//g, "<<DBL>>")
+    .replace(/\*\*/g, "<<DBL>>")
+    .replace(/\*/g, "[^/]*")
+    .replace(/<<DBL>>/g, "(?:.*/)?");
+  return new RegExp(`^${re}$`);
+}
+
+function walk(dir: string, rootDir: string, excludeDirs: Set<string>, out: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (excludeDirs.has(entry.name)) continue;
+      walk(abs, rootDir, excludeDirs, out);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+}
+
+export const realFsAdapter: FsAdapter = {
+  exists(absPath: string) {
+    return fs.existsSync(absPath);
+  },
+  readText(absPath: string) {
+    return fs.readFileSync(absPath, "utf-8");
+  },
+  glob(siteDir: string, pattern: string, excludeDirs: string[] = []) {
+    const allFiles: string[] = [];
+    walk(siteDir, siteDir, new Set(excludeDirs), allFiles);
+    const patterns = expandBraces(pattern).map(patternToRegex);
+    const matches = allFiles.filter((abs) => {
+      const rel = abs.slice(siteDir.length + 1).replace(/\\/g, "/");
+      return patterns.some((re) => re.test(rel));
+    });
+    return matches.sort();
+  },
+};

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

@@ -0,0 +1,66 @@
+/**
+ * Post-migration cleanup audit — shared types.
+ *
+ * The audit runner is a thin orchestrator: it loads the site, runs each
+ * rule, and prints the findings. The interesting bits live in `rules.ts`.
+ *
+ * Rules are pure(ish) functions over an injected `FsAdapter`, which means
+ * they can be unit-tested with an in-memory file system and never touch
+ * the real disk in CI.
+ */
+
+export type Severity = "info" | "warning";
+
+export interface Finding {
+  /** Stable rule identifier (e.g. "dead-lib-shims"). */
+  rule: string;
+  severity: Severity;
+  /** Site-relative path of the file the finding refers to. */
+  file: string;
+  /** One-line message — shown in default text output. */
+  message: string;
+  /** Suggested human action, if any. */
+  fix?: string;
+  /** Free-form structured payload for JSON consumers. */
+  meta?: Record<string, unknown>;
+}
+
+export interface RuleSummary {
+  /** Stable rule identifier. */
+  rule: string;
+  /** Human-readable section title. */
+  title: string;
+  findings: Finding[];
+}
+
+export interface AuditReport {
+  site: string;
+  rules: RuleSummary[];
+  totalFindings: number;
+}
+
+/**
+ * Minimal file-system adapter — read + glob. Keeping the surface tiny
+ * is what lets us pass an in-memory map in unit tests.
+ */
+export interface FsAdapter {
+  exists(absPath: string): boolean;
+  readText(absPath: string): string;
+  /**
+   * Return absolute paths matching the glob, ordered by path. Globs are
+   * relative to `siteDir`. Implementations must respect `excludeDirs` and
+   * skip them entirely.
+   */
+  glob(siteDir: string, pattern: string, excludeDirs?: string[]): string[];
+}
+
+export interface RuleContext {
+  siteDir: string;
+  fs: FsAdapter;
+}
+
+export interface Rule {
+  id: string;
+  title: string;
+  run(ctx: RuleContext): Finding[];
+}

package/scripts/migrate-post-cleanup.ts

@@ -0,0 +1,156 @@
+#!/usr/bin/env tsx
+/**
+ * Post-Migration Cleanup Audit
+ *
+ * Read-only audit that scans a migrated site for dead code and obsolete
+ * boilerplate that the framework now owns. Mirrors the human checklist at
+ * `.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md`
+ * but turns it into something CI can actually run.
+ *
+ * Usage (from a migrated site directory):
+ *   npx -p @decocms/start deco-post-cleanup
+ *   npx -p @decocms/start deco-post-cleanup --json
+ *
+ * Options:
+ *   --source <dir>   Site directory to audit (default: current directory)
+ *   --json           Emit machine-readable JSON instead of pretty text
+ *   --strict         Exit code 2 if any warning-severity findings exist
+ *   --help, -h       Show this help
+ *
+ * This script is intentionally read-only. Auto-fix support (`--fix`) is
+ * a planned follow-up — see the SKILL doc.
+ */
+
+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 type { AuditReport, Severity } from "./migrate/post-cleanup/types";
+
+interface CliOpts {
+  source: string;
+  json: boolean;
+  strict: boolean;
+  help: boolean;
+}
+
+function parseArgs(args: string[]): CliOpts {
+  let source = ".";
+  let json = false;
+  let strict = false;
+  let help = false;
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--source":
+        source = args[++i];
+        break;
+      case "--json":
+        json = true;
+        break;
+      case "--strict":
+        strict = true;
+        break;
+      case "--help":
+      case "-h":
+        help = true;
+        break;
+    }
+  }
+  return { source, json, strict, help };
+}
+
+function showHelp() {
+  console.log(`
+  @decocms/start — Post-Migration Cleanup Audit
+
+  Scans a migrated site for dead code and obsolete boilerplate that the
+  framework now owns. Read-only — prints findings, does not modify files.
+
+  Usage:
+    npx -p @decocms/start deco-post-cleanup [options]
+
+  Options:
+    --source <dir>   Site directory to audit (default: .)
+    --json           Emit machine-readable JSON instead of pretty text
+    --strict         Exit code 2 if any warning-severity findings exist
+    --help, -h       Show this help
+
+  Examples:
+    npx -p @decocms/start deco-post-cleanup
+    npx -p @decocms/start deco-post-cleanup --source ./my-site --json
+
+  See: .agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md
+  `);
+}
+
+function severityColor(sev: Severity, text: string): string {
+  if (sev === "warning") return yellow(text);
+  return gray(text);
+}
+
+function printText(report: AuditReport): void {
+  banner("Post-Migration Cleanup Audit");
+  console.log(`  ${gray("Site:")} ${bold(report.site)}`);
+  console.log(`  ${gray("Findings:")} ${bold(String(report.totalFindings))}`);
+  console.log("");
+
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    const count = summary.findings.length;
+    const headColor = count === 0 ? green : yellow;
+    console.log(`${headColor(`[${idx}] ${summary.title}`)} ${gray(`(${count} found)`)}`);
+    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 (count === 0) console.log(`    ${gray("(nothing to clean up)")}`);
+    console.log("");
+  }
+
+  const warnings = report.rules
+    .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`)}`,
+  );
+  if (report.totalFindings > 0) {
+    console.log(gray("  See post-migration-cleanup.md for the canonical fix steps per rule."));
+  }
+}
+
+function printJson(report: AuditReport): void {
+  console.log(JSON.stringify(report, null, 2));
+}
+
+function shouldFail(report: AuditReport, strict: boolean): boolean {
+  if (!strict) return false;
+  return report.rules.some((r) => r.findings.some((f) => f.severity === "warning"));
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const siteDir = path.resolve(opts.source);
+  const report = runAudit(siteDir, realFsAdapter);
+
+  if (opts.json) {
+    printJson(report);
+  } else {
+    printText(report);
+  }
+
+  if (shouldFail(report, opts.strict)) {
+    process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  console.error(red(`Audit failed: ${(err as Error).message}`));
+  process.exit(1);
+});