@decocms/start 2.9.0 → 2.10.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/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;

package/scripts/migrate/transforms/section-conventions.ts

@@ -1,4 +1,8 @@
-import type { TransformResult, SectionMeta } from "../types";
+import type {
+	SectionConventionSets,
+} from "../config";
+import { resolveSectionConventions } from "../config";
+import type { SectionMeta, TransformResult } from "../types";
 
 /**
  * Adds section convention exports (sync, eager, layout, cache)
@@ -6,158 +10,179 @@ import type { TransformResult, SectionMeta } from "../types";
  *
  * These exports are read by generate-sections.ts in @decocms/start
  * to build the sections.gen.ts registry.
+ *
+ * The set of section *names* that get hints applied is configurable
+ * via `.deco-migrate.config.json` (see `migrate/config.ts`). The exported
+ * `transformSectionConventions` keeps a back-compat signature using the
+ * baked-in defaults; new callers should prefer
+ * `createSectionConventionsTransform(sets)` so config can drive the lists.
  */
 
-const EAGER_SYNC_SECTIONS = new Set([
-  "UtilLinks",
-  "DepartamentList",
-  "ImageGallery",
-  "BannersGrid",
-  "Carousel",
-  "Tipbar",
-  "Live",
-]);
-
-const SYNC_SECTIONS = new Set([
-  "ProductShelf",
-  "ProductShelfTabbed",
-  "ProductShelfGroup",
-  "ProductShelfTopSort",
-  "CouponList",
-  "NotFoundChallenge",
-  "MountedPDP",
-  "BackgroundWrapper",
-  "SearchResult",
-  "LpCartao",
-]);
-
-const LISTING_CACHE_SECTIONS = new Set([
-  "ProductShelf",
-  "ProductShelfTabbed",
-  "ProductShelfGroup",
-  "ProductShelfTimedOffers",
-]);
-
-const STATIC_CACHE_SECTIONS = new Set([
-  "InstagramPosts",
-  "Faq",
-]);
-
 function getSectionBasename(filePath: string): string {
-  return filePath.split("/").pop()?.replace(/\.\w+$/, "") || "";
+	return filePath.split("/").pop()?.replace(/\.\w+$/, "") || "";
+}
+
+/**
+ * Build a `transformSectionConventions` closure bound to the given
+ * resolved sets. This is the preferred entry point — the caller (usually
+ * `phase-transform`) loads config once and passes the sets in.
+ */
+export function createSectionConventionsTransform(
+	sets: SectionConventionSets,
+) {
+	return (
+		content: string,
+		sectionMeta: SectionMeta | undefined,
+	): TransformResult => transformWithSets(content, sectionMeta, sets);
 }
 
+/** Default-configured transform. Uses the baked-in defaults from `config.ts`. */
+const defaultSets = resolveSectionConventions(null);
+
 export function transformSectionConventions(
-  content: string,
-  sectionMeta: SectionMeta | undefined,
+	content: string,
+	sectionMeta: SectionMeta | undefined,
+): TransformResult {
+	return transformWithSets(content, sectionMeta, defaultSets);
+}
+
+function transformWithSets(
+	content: string,
+	sectionMeta: SectionMeta | undefined,
+	sets: SectionConventionSets,
 ): TransformResult {
-  if (!sectionMeta) {
-    return { content, changed: false, notes: [] };
-  }
-
-  const notes: string[] = [];
-  let result = content;
-  let changed = false;
-  const basename = getSectionBasename(sectionMeta.path);
-
-  // Header, footer, theme → eager + sync + layout
-  if (sectionMeta.isHeader || sectionMeta.isFooter || sectionMeta.isTheme) {
-    if (!result.includes("export const eager")) {
-      result += "\nexport const eager = true;\n";
-      notes.push("Added: export const eager = true");
-      changed = true;
-    }
-    if (!result.includes("export const sync")) {
-      result += "export const sync = true;\n";
-      notes.push("Added: export const sync = true");
-      changed = true;
-    }
-    // Header in golden does NOT have layout=true; only footer+theme do
-    if ((sectionMeta.isFooter || sectionMeta.isTheme) && !result.includes("export const layout")) {
-      result += "export const layout = true;\n";
-      notes.push("Added: export const layout = true");
-      changed = true;
-    }
-  }
-
-  // Known eager+sync sections (non-layout)
-  if (EAGER_SYNC_SECTIONS.has(basename)) {
-    if (!result.includes("export const eager")) {
-      result += "\nexport const eager = true;\n";
-      notes.push(`Added: export const eager = true (${basename})`);
-      changed = true;
-    }
-    if (!result.includes("export const sync")) {
-      result += "export const sync = true;\n";
-      notes.push(`Added: export const sync = true (${basename})`);
-      changed = true;
-    }
-  }
-
-  // Known sync-only sections
-  if (SYNC_SECTIONS.has(basename) && !result.includes("export const sync")) {
-    result += "\nexport const sync = true;\n";
-    notes.push(`Added: export const sync = true (${basename})`);
-    changed = true;
-  }
-
-  // Listing cache sections
-  if (LISTING_CACHE_SECTIONS.has(basename) && !result.includes("export const cache")) {
-    result += '\nexport const cache = "listing";\n';
-    notes.push(`Added: export const cache = "listing" (${basename})`);
-    changed = true;
-  }
-
-  // Static cache sections
-  if (STATIC_CACHE_SECTIONS.has(basename) && !result.includes("export const cache")) {
-    result += '\nexport const cache = "static";\n';
-    notes.push(`Added: export const cache = "static" (${basename})`);
-    changed = true;
-  }
-
-  // Generic: listing sections not already matched above
-  if (sectionMeta.isListing && !result.includes("export const cache")) {
-    result += '\nexport const cache = "listing";\n';
-    notes.push('Added: export const cache = "listing"');
-    changed = true;
-  }
-
-  // Sections with loaders that use device → add sync (needs SSR device detection)
-  if (sectionMeta.hasLoader && sectionMeta.loaderUsesDevice && !result.includes("export const sync")) {
-    result += "\nexport const sync = true;\n";
-    notes.push("Added: export const sync = true (loader uses device)");
-    changed = true;
-  }
-
-  // Sections that render nested Section children need sync so they're in
-  // the syncComponents registry (SectionRenderer resolves the string key).
-  const hasNestedSections =
-    /children:\s*Section\b/.test(result) || /fallback:\s*Section\b/.test(result);
-  if (hasNestedSections && !result.includes("export const sync")) {
-    result += "\nexport const sync = true;\n";
-    notes.push("Added: export const sync = true (renders nested Section children)");
-    changed = true;
-  }
-
-  // Re-export sections that wrap PDP/nested content need sync too.
-  // Detect: file is a re-export AND the target component renders nested Sections
-  const isReExport = /^export\s+\{[^}]*default[^}]*\}\s+from\s+/.test(result.trim());
-  if (isReExport && (basename === "MountedPDP" || basename === "NotFoundChallenge")) {
-    if (!result.includes("export const sync")) {
-      result += "\nexport const sync = true;\n";
-      notes.push(`Added: export const sync = true (re-export: ${basename})`);
-      changed = true;
-    }
-  }
-
-  // Don't add LoadingFallback re-exports to thin section files —
-  // we can't guarantee the target component exports it.
-  // Instead, if it's a listing section, a generic skeleton will be added below.
-
-  // Generate a basic LoadingFallback if the section doesn't have one
-  // and it's a listing section (visible skeleton improvement)
-  if (sectionMeta.isListing && !sectionMeta.hasLoadingFallback && !result.includes("LoadingFallback")) {
-    result += `
+	if (!sectionMeta) {
+		return { content, changed: false, notes: [] };
+	}
+
+	const notes: string[] = [];
+	let result = content;
+	let changed = false;
+	const basename = getSectionBasename(sectionMeta.path);
+
+	// Header, footer, theme → eager + sync + layout
+	if (sectionMeta.isHeader || sectionMeta.isFooter || sectionMeta.isTheme) {
+		if (!result.includes("export const eager")) {
+			result += "\nexport const eager = true;\n";
+			notes.push("Added: export const eager = true");
+			changed = true;
+		}
+		if (!result.includes("export const sync")) {
+			result += "export const sync = true;\n";
+			notes.push("Added: export const sync = true");
+			changed = true;
+		}
+		// Header in golden does NOT have layout=true; only footer+theme do
+		if (
+			(sectionMeta.isFooter || sectionMeta.isTheme) &&
+			!result.includes("export const layout")
+		) {
+			result += "export const layout = true;\n";
+			notes.push("Added: export const layout = true");
+			changed = true;
+		}
+	}
+
+	// Known eager+sync sections (non-layout)
+	if (sets.eagerSync.has(basename)) {
+		if (!result.includes("export const eager")) {
+			result += "\nexport const eager = true;\n";
+			notes.push(`Added: export const eager = true (${basename})`);
+			changed = true;
+		}
+		if (!result.includes("export const sync")) {
+			result += "export const sync = true;\n";
+			notes.push(`Added: export const sync = true (${basename})`);
+			changed = true;
+		}
+	}
+
+	// Known sync-only sections
+	if (sets.sync.has(basename) && !result.includes("export const sync")) {
+		result += "\nexport const sync = true;\n";
+		notes.push(`Added: export const sync = true (${basename})`);
+		changed = true;
+	}
+
+	// Listing cache sections
+	if (
+		sets.listingCache.has(basename) &&
+		!result.includes("export const cache")
+	) {
+		result += '\nexport const cache = "listing";\n';
+		notes.push(`Added: export const cache = "listing" (${basename})`);
+		changed = true;
+	}
+
+	// Static cache sections
+	if (
+		sets.staticCache.has(basename) &&
+		!result.includes("export const cache")
+	) {
+		result += '\nexport const cache = "static";\n';
+		notes.push(`Added: export const cache = "static" (${basename})`);
+		changed = true;
+	}
+
+	// Generic: listing sections not already matched above
+	if (sectionMeta.isListing && !result.includes("export const cache")) {
+		result += '\nexport const cache = "listing";\n';
+		notes.push('Added: export const cache = "listing"');
+		changed = true;
+	}
+
+	// Sections with loaders that use device → add sync (needs SSR device detection)
+	if (
+		sectionMeta.hasLoader &&
+		sectionMeta.loaderUsesDevice &&
+		!result.includes("export const sync")
+	) {
+		result += "\nexport const sync = true;\n";
+		notes.push("Added: export const sync = true (loader uses device)");
+		changed = true;
+	}
+
+	// Sections that render nested Section children need sync so they're in
+	// the syncComponents registry (SectionRenderer resolves the string key).
+	const hasNestedSections =
+		/children:\s*Section\b/.test(result) ||
+		/fallback:\s*Section\b/.test(result);
+	if (hasNestedSections && !result.includes("export const sync")) {
+		result += "\nexport const sync = true;\n";
+		notes.push(
+			"Added: export const sync = true (renders nested Section children)",
+		);
+		changed = true;
+	}
+
+	// Re-export sections that wrap PDP/nested content need sync too.
+	// Detect: file is a re-export AND the target component renders nested Sections
+	const isReExport = /^export\s+\{[^}]*default[^}]*\}\s+from\s+/.test(
+		result.trim(),
+	);
+	if (
+		isReExport &&
+		(basename === "MountedPDP" || basename === "NotFoundChallenge")
+	) {
+		if (!result.includes("export const sync")) {
+			result += "\nexport const sync = true;\n";
+			notes.push(`Added: export const sync = true (re-export: ${basename})`);
+			changed = true;
+		}
+	}
+
+	// Don't add LoadingFallback re-exports to thin section files —
+	// we can't guarantee the target component exports it.
+	// Instead, if it's a listing section, a generic skeleton will be added below.
+
+	// Generate a basic LoadingFallback if the section doesn't have one
+	// and it's a listing section (visible skeleton improvement)
+	if (
+		sectionMeta.isListing &&
+		!sectionMeta.hasLoadingFallback &&
+		!result.includes("LoadingFallback")
+	) {
+		result += `
 export function LoadingFallback() {
   return (
     <div className="w-full py-8">
@@ -177,9 +202,9 @@ export function LoadingFallback() {
   );
 }
 `;
-    notes.push("Added: LoadingFallback skeleton for listing section");
-    changed = true;
-  }
+		notes.push("Added: LoadingFallback skeleton for listing section");
+		changed = true;
+	}
 
-  return { content: result, changed, notes };
+	return { content: result, changed, notes };
 }

package/scripts/migrate/types.ts

@@ -137,6 +137,14 @@ export interface MigrationContext {
   vtexAccount: string | null;
   gtmId: string | null;
 
+  /**
+   * Per-site config loaded from `.deco-migrate.config.json`. `null` means
+   * no config file was present — defaults apply throughout. Imported
+   * lazily as `MigrateConfig` to avoid a circular dependency between
+   * `types.ts` and `config.ts`.
+   */
+  config?: import("./config").MigrateConfig | null;
+
   /** deno.json import map entries */
   importMap: Record<string, string>;
 
@@ -191,7 +199,11 @@ export interface TransformResult {
 
 export function createContext(
   sourceDir: string,
-  opts: { dryRun?: boolean; verbose?: boolean } = {},
+  opts: {
+    dryRun?: boolean;
+    verbose?: boolean;
+    config?: import("./config").MigrateConfig | null;
+  } = {},
 ): MigrationContext {
   return {
     sourceDir,
@@ -199,6 +211,7 @@ export function createContext(
     platform: "custom",
     vtexAccount: null,
     gtmId: null,
+    config: opts.config ?? null,
     importMap: {},
     discoveredNpmDeps: {},
     themeColors: {},

package/scripts/migrate.ts

@@ -25,6 +25,7 @@
 
 import * as path from "node:path";
 import { execSync } from "node:child_process";
+import { loadConfig, validateConfig } from "./migrate/config";
 import { createContext, logPhase } from "./migrate/types";
 import { analyze } from "./migrate/phase-analyze";
 import { scaffold } from "./migrate/phase-scaffold";
@@ -121,9 +122,19 @@ async function main() {
   stat("Mode", opts.dryRun ? yellow("DRY RUN") : green("EXECUTE"));
   stat("Verbose", opts.verbose ? "yes" : "no");
 
+  // Load optional per-site config from `.deco-migrate.config.json`. Drives
+  // section-conventions hardcoded lists today; future fields will tune
+  // import rewrites, scaffolding, etc.
+  const siteConfig = loadConfig(sourceDir);
+  if (siteConfig) {
+    validateConfig(siteConfig);
+    stat("Config", green(".deco-migrate.config.json (loaded)"));
+  }
+
   const ctx = createContext(sourceDir, {
     dryRun: opts.dryRun,
     verbose: opts.verbose,
+    config: siteConfig,
   });
 
   try {