@decocms/start 2.10.0 → 2.12.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

@@ -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/.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,11 +1,12 @@
 {
   "name": "@decocms/start",
-  "version": "2.10.0",
+  "version": "2.12.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,371 @@
+/**
+ * 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, 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                                     */
+/* ------------------------------------------------------------------ */
+
+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;
+  },
+  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;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* 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',
+      },
+    ];
+  },
+  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`,
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* 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 },
+      },
+    ];
+  },
+  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`,
+      },
+    ];
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* 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,
+  },
+};