@decocms/start 2.9.0 → 2.11.0

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

@@ -34,6 +34,33 @@ npx tsx node_modules/@decocms/start/scripts/migrate.ts --source /path/to/old-sit
 
 **CI usage:** pair `--strict` with `--with-build` to catch both type and runtime regressions before merge.
 
+### Per-site config: `.deco-migrate.config.json`
+
+Optional JSON file at the source root that customises the migration for sites whose section names don't match the casaevideo-derived defaults baked into the script.
+
+```jsonc
+{
+  "sectionConventions": {
+    // Add to defaults — preferred for sites that share most defaults.
+    "extend": {
+      "sync": ["MyCustomShelf"],
+      "listingCache": ["MyCustomShelf"],
+      "staticCache": ["AboutUs", "PrivacyPolicy"]
+    }
+    // Or replace defaults entirely (rare):
+    // "replace": { "sync": [...], "eagerSync": [...], ... }
+  }
+}
+```
+
+**Categories:**
+- `eagerSync` — section files registered as both eager and sync (rendered above-the-fold, no client-defer).
+- `sync` — registered as sync only (server-side default applies for loading).
+- `listingCache` — emit `export const cache = "listing"` (medium TTL).
+- `staticCache` — emit `export const cache = "static"` (long TTL).
+
+When the file is absent the baked-in casaevideo defaults apply, so existing migrations are unaffected.
+
 ## Architecture
 
 ```

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.9.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/config.test.ts

@@ -0,0 +1,202 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+	DEFAULT_SECTION_CONVENTIONS,
+	loadConfig,
+	resolveSectionConventions,
+	validateConfig,
+} from "./config";
+
+describe("loadConfig", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "config-test-"));
+	});
+
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("returns null when the config file is missing", () => {
+		expect(loadConfig(tmpDir)).toBeNull();
+	});
+
+	it("loads valid JSON", () => {
+		const content = JSON.stringify({
+			sectionConventions: { extend: { sync: ["MySection"] } },
+		});
+		fs.writeFileSync(
+			path.join(tmpDir, ".deco-migrate.config.json"),
+			content,
+			"utf-8",
+		);
+		const config = loadConfig(tmpDir);
+		expect(config).toEqual({
+			sectionConventions: { extend: { sync: ["MySection"] } },
+		});
+	});
+
+	it("throws with a helpful error on malformed JSON", () => {
+		fs.writeFileSync(
+			path.join(tmpDir, ".deco-migrate.config.json"),
+			"not valid json{",
+			"utf-8",
+		);
+		expect(() => loadConfig(tmpDir)).toThrow(
+			/Failed to parse.*Expected valid JSON/s,
+		);
+	});
+});
+
+describe("resolveSectionConventions", () => {
+	it("returns the defaults when config is null", () => {
+		const sets = resolveSectionConventions(null);
+		expect(sets.eagerSync.has("UtilLinks")).toBe(true);
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+		expect(sets.listingCache.has("ProductShelf")).toBe(true);
+		expect(sets.staticCache.has("Faq")).toBe(true);
+	});
+
+	it("preserves all default eagerSync entries", () => {
+		const sets = resolveSectionConventions(null);
+		for (const name of DEFAULT_SECTION_CONVENTIONS.eagerSync ?? []) {
+			expect(sets.eagerSync.has(name)).toBe(true);
+		}
+	});
+
+	it("extend mode adds to defaults", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: {
+				extend: { sync: ["MySection"], staticCache: ["MyStatic"] },
+			},
+		});
+		// Default still present
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+		// Extension added
+		expect(sets.sync.has("MySection")).toBe(true);
+		// Default static still present
+		expect(sets.staticCache.has("Faq")).toBe(true);
+		// Extension added
+		expect(sets.staticCache.has("MyStatic")).toBe(true);
+	});
+
+	it("extend mode handles partial extensions (only some categories)", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: { extend: { eagerSync: ["FrontFacing"] } },
+		});
+		// All defaults still present in untouched categories
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+		expect(sets.staticCache.has("Faq")).toBe(true);
+		// Extension added
+		expect(sets.eagerSync.has("FrontFacing")).toBe(true);
+		// Defaults still present in extended category
+		expect(sets.eagerSync.has("UtilLinks")).toBe(true);
+	});
+
+	it("replace mode discards defaults", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: {
+				replace: { sync: ["OnlyThis"] },
+			},
+		});
+		// Default removed
+		expect(sets.sync.has("ProductShelf")).toBe(false);
+		// Replacement present
+		expect(sets.sync.has("OnlyThis")).toBe(true);
+		// Untouched categories empty
+		expect(sets.eagerSync.size).toBe(0);
+		expect(sets.listingCache.size).toBe(0);
+		expect(sets.staticCache.size).toBe(0);
+	});
+
+	it("replace mode is full replacement, not partial overlay", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: {
+				replace: {
+					eagerSync: ["X"],
+					sync: ["Y"],
+					listingCache: ["Z"],
+					staticCache: ["W"],
+				},
+			},
+		});
+		expect(Array.from(sets.eagerSync)).toEqual(["X"]);
+		expect(Array.from(sets.sync)).toEqual(["Y"]);
+		expect(Array.from(sets.listingCache)).toEqual(["Z"]);
+		expect(Array.from(sets.staticCache)).toEqual(["W"]);
+	});
+
+	it("returns empty sets when given empty arrays in replace", () => {
+		const sets = resolveSectionConventions({
+			sectionConventions: { replace: {} },
+		});
+		expect(sets.eagerSync.size).toBe(0);
+		expect(sets.sync.size).toBe(0);
+		expect(sets.listingCache.size).toBe(0);
+		expect(sets.staticCache.size).toBe(0);
+	});
+
+	it("returns defaults when sectionConventions is undefined", () => {
+		const sets = resolveSectionConventions({});
+		expect(sets.sync.has("ProductShelf")).toBe(true);
+	});
+});
+
+describe("validateConfig", () => {
+	it("accepts an empty config", () => {
+		expect(() => validateConfig({})).not.toThrow();
+	});
+
+	it("accepts a config with extend", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { extend: { sync: ["Foo"] } },
+			}),
+		).not.toThrow();
+	});
+
+	it("accepts a config with replace", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { replace: { sync: ["Foo"] } },
+			}),
+		).not.toThrow();
+	});
+
+	it("rejects non-object root", () => {
+		expect(() => validateConfig("bad")).toThrow(
+			/must be a JSON object/,
+		);
+	});
+
+	it("rejects non-object sectionConventions", () => {
+		expect(() => validateConfig({ sectionConventions: "bad" })).toThrow(
+			/sectionConventions must be an object/,
+		);
+	});
+
+	it("rejects non-array values in convention lists", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { extend: { sync: "not-an-array" } },
+			}),
+		).toThrow(/must be string\[\]/);
+	});
+
+	it("rejects non-string entries in convention lists", () => {
+		expect(() =>
+			validateConfig({
+				sectionConventions: { extend: { sync: [1, 2, 3] } },
+			}),
+		).toThrow(/must be string\[\]/);
+	});
+
+	it("ignores unknown top-level fields gracefully", () => {
+		expect(() =>
+			validateConfig({ unknownField: 123, sectionConventions: {} }),
+		).not.toThrow();
+	});
+});

package/scripts/migrate/config.ts

@@ -0,0 +1,186 @@
+/**
+ * Per-site migration configuration.
+ *
+ * Looks for `.deco-migrate.config.json` next to the source root. The file
+ * is optional — without it the script falls back to a baked-in default set
+ * of section-convention names that work for `casaevideo` and most other
+ * Deco/VTEX sites that derived from the same template.
+ *
+ * The defaults are kept here (not in `transforms/section-conventions.ts`)
+ * so that:
+ *   1. They live alongside the schema that consumes them.
+ *   2. They can be overridden per site without forking the transform.
+ *   3. Other phases (analyze, report) can read them too.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Names of section files that get framework hints applied during the
+ * `transformSectionConventions` step.
+ *
+ * - `eagerSync`: render server-side eagerly *and* register as sync (no
+ *   client-side defer).
+ * - `sync`: register as sync (sectionLoaders.sync), but server-side
+ *   loading remains the default.
+ * - `listingCache`: `export const cache = "listing"` (medium TTL).
+ * - `staticCache`: `export const cache = "static"` (long TTL).
+ */
+export interface SectionConventionConfig {
+	eagerSync?: string[];
+	sync?: string[];
+	listingCache?: string[];
+	staticCache?: string[];
+}
+
+export interface MigrateConfig {
+	sectionConventions?: {
+		/**
+		 * Replace the built-in defaults entirely. Use only when porting a
+		 * site whose section names don't overlap the defaults at all.
+		 */
+		replace?: SectionConventionConfig;
+		/**
+		 * Add to the built-in defaults. Recommended path for sites that
+		 * share most defaults but have a few extra section names.
+		 */
+		extend?: SectionConventionConfig;
+	};
+}
+
+/**
+ * Resolved sets used by `transformSectionConventions`. Always provided —
+ * either from defaults, from config replace, or defaults+config.extend.
+ */
+export interface SectionConventionSets {
+	eagerSync: Set<string>;
+	sync: Set<string>;
+	listingCache: Set<string>;
+	staticCache: Set<string>;
+}
+
+/**
+ * Built-in defaults. Originally extracted from `casaevideo` migration —
+ * these names are common across Deco/VTEX storefronts that share the
+ * lineage. Sites that don't have these sections are unaffected (the
+ * matcher just never fires).
+ */
+export const DEFAULT_SECTION_CONVENTIONS: SectionConventionConfig = {
+	eagerSync: [
+		"UtilLinks",
+		"DepartamentList",
+		"ImageGallery",
+		"BannersGrid",
+		"Carousel",
+		"Tipbar",
+		"Live",
+	],
+	sync: [
+		"ProductShelf",
+		"ProductShelfTabbed",
+		"ProductShelfGroup",
+		"ProductShelfTopSort",
+		"CouponList",
+		"NotFoundChallenge",
+		"MountedPDP",
+		"BackgroundWrapper",
+		"SearchResult",
+		"LpCartao",
+	],
+	listingCache: [
+		"ProductShelf",
+		"ProductShelfTabbed",
+		"ProductShelfGroup",
+		"ProductShelfTimedOffers",
+	],
+	staticCache: ["InstagramPosts", "Faq"],
+};
+
+/** Load `.deco-migrate.config.json` from the source dir, if present. */
+export function loadConfig(sourceDir: string): MigrateConfig | null {
+	const configPath = path.join(sourceDir, ".deco-migrate.config.json");
+	if (!fs.existsSync(configPath)) return null;
+	try {
+		return JSON.parse(fs.readFileSync(configPath, "utf-8")) as MigrateConfig;
+	} catch (e) {
+		const msg = (e as Error).message;
+		throw new Error(
+			`Failed to parse ${configPath}: ${msg}. Expected valid JSON.`,
+		);
+	}
+}
+
+/** Resolve config + defaults into the four sets the transform consumes. */
+export function resolveSectionConventions(
+	config: MigrateConfig | null,
+): SectionConventionSets {
+	const sc = config?.sectionConventions;
+
+	// Replace mode: use only what the user provided. No defaults mixed in.
+	if (sc?.replace) {
+		return toSets(sc.replace);
+	}
+
+	// Default + extend: start from defaults, union in extend lists.
+	const merged: SectionConventionConfig = {
+		eagerSync: [
+			...(DEFAULT_SECTION_CONVENTIONS.eagerSync ?? []),
+			...(sc?.extend?.eagerSync ?? []),
+		],
+		sync: [
+			...(DEFAULT_SECTION_CONVENTIONS.sync ?? []),
+			...(sc?.extend?.sync ?? []),
+		],
+		listingCache: [
+			...(DEFAULT_SECTION_CONVENTIONS.listingCache ?? []),
+			...(sc?.extend?.listingCache ?? []),
+		],
+		staticCache: [
+			...(DEFAULT_SECTION_CONVENTIONS.staticCache ?? []),
+			...(sc?.extend?.staticCache ?? []),
+		],
+	};
+	return toSets(merged);
+}
+
+function toSets(c: SectionConventionConfig): SectionConventionSets {
+	return {
+		eagerSync: new Set(c.eagerSync ?? []),
+		sync: new Set(c.sync ?? []),
+		listingCache: new Set(c.listingCache ?? []),
+		staticCache: new Set(c.staticCache ?? []),
+	};
+}
+
+/** Cheap structural validation — throws on obviously invalid shapes. */
+export function validateConfig(config: unknown): asserts config is MigrateConfig {
+	if (config === null || typeof config !== "object") {
+		throw new Error(".deco-migrate.config.json must be a JSON object");
+	}
+	const c = config as Record<string, unknown>;
+	const sc = c.sectionConventions;
+	if (sc === undefined) return;
+	if (typeof sc !== "object" || sc === null) {
+		throw new Error("sectionConventions must be an object");
+	}
+	const scObj = sc as Record<string, unknown>;
+	for (const key of ["replace", "extend"] as const) {
+		const v = scObj[key];
+		if (v === undefined) continue;
+		if (typeof v !== "object" || v === null) {
+			throw new Error(`sectionConventions.${key} must be an object`);
+		}
+		const sub = v as Record<string, unknown>;
+		for (const f of ["eagerSync", "sync", "listingCache", "staticCache"]) {
+			const arr = sub[f];
+			if (arr === undefined) continue;
+			if (
+				!Array.isArray(arr) ||
+				!arr.every((s): s is string => typeof s === "string")
+			) {
+				throw new Error(`sectionConventions.${key}.${f} must be string[]`);
+			}
+		}
+	}
+}

package/scripts/migrate/phase-transform.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { resolveSectionConventions } from "./config";
 import type { MigrationContext, TransformResult, SectionMeta } from "./types";
 import { log, logPhase } from "./types";
 import { transformImports } from "./transforms/imports";
@@ -8,7 +9,7 @@ import { transformFreshApis } from "./transforms/fresh-apis";
 import { transformDenoIsms } from "./transforms/deno-isms";
 import { transformTailwind } from "./transforms/tailwind";
 import { transformDeadCode } from "./transforms/dead-code";
-import { transformSectionConventions } from "./transforms/section-conventions";
+import { createSectionConventionsTransform } from "./transforms/section-conventions";
 
 /** Map of section path → metadata, populated per-run */
 let sectionMetaMap: Map<string, SectionMeta> | null = null;
@@ -23,6 +24,22 @@ function getSectionMeta(ctx: MigrationContext, relPath: string): SectionMeta | u
   return sectionMetaMap.get(relPath);
 }
 
+/**
+ * Cached per-run section-conventions closure. Built once from the
+ * resolved config sets (`ctx.config.sectionConventions`), so casaevideo
+ * defaults still apply when no config file exists.
+ */
+let cachedSectionTransform:
+  | ReturnType<typeof createSectionConventionsTransform>
+  | null = null;
+
+function getSectionConventionsTransform(ctx: MigrationContext) {
+  if (cachedSectionTransform) return cachedSectionTransform;
+  const sets = resolveSectionConventions(ctx.config ?? null);
+  cachedSectionTransform = createSectionConventionsTransform(sets);
+  return cachedSectionTransform;
+}
+
 /**
  * Apply all transforms to a file's content in the correct order.
  */
@@ -59,7 +76,9 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
   // Section conventions (sync/eager/layout/cache) — only for section files
   if (ctx && relPath && relPath.startsWith("sections/")) {
     const meta = getSectionMeta(ctx, relPath);
-    const result = transformSectionConventions(currentContent, meta);
+    // Build the closure once per ctx, cache it on the context.
+    const sectionTransform = getSectionConventionsTransform(ctx);
+    const result = sectionTransform(currentContent, meta);
     if (result.changed) {
       anyChanged = true;
       currentContent = result.content;