@decocms/blocks-cli 7.0.0

package/scripts/migrate/templates/app-css.ts

@@ -0,0 +1,366 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { MigrationContext } from "../types";
+import type { ExtractedTheme } from "../analyzers/theme-extractor";
+
+/**
+ * Find the original site's custom CSS file.
+ * Deco sites typically have their custom CSS in:
+ * - tailwind.css (root level, combined directives + custom)
+ * - static/tailwind.css (compiled output — skip this)
+ * - static-{brand}/tailwind.css (compiled output — skip this)
+ * - styles/*.css
+ */
+function findOriginalCss(ctx: MigrationContext): string | null {
+  // Prefer root tailwind.css (has custom CSS + directives)
+  const rootCss = path.join(ctx.sourceDir, "tailwind.css");
+  if (fs.existsSync(rootCss)) {
+    return fs.readFileSync(rootCss, "utf-8");
+  }
+
+  // Check for styles/ directory
+  const stylesDir = path.join(ctx.sourceDir, "styles");
+  if (fs.existsSync(stylesDir)) {
+    for (const file of fs.readdirSync(stylesDir)) {
+      if (file.endsWith(".css") && file !== "tailwind.css") {
+        return fs.readFileSync(path.join(stylesDir, file), "utf-8");
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract custom CSS from the original site's CSS file.
+ * Strips TW3 directives (@tailwind base/components/utilities) and
+ * returns only the custom CSS (component overrides, @layer, @font-face, etc.)
+ */
+function extractCustomCss(rawCss: string): string {
+  return rawCss
+    // Remove Tailwind v3 directives (replaced by @import "tailwindcss")
+    .replace(/^@tailwind\s+(?:base|components|utilities)\s*;\s*$/gm, "")
+    // Remove empty lines left over
+    .replace(/^\s*\n/gm, "")
+    .trim();
+}
+
+/**
+ * Transform @apply directives for TW3→TW4 compatibility.
+ * The tailwind.ts transform handles className= attributes in JSX,
+ * but @apply inside CSS also needs class renames.
+ *
+ * Also converts @apply with custom brand/theme colors to native CSS
+ * properties when the utility class might not be registered in TW4.
+ */
+function transformApplyDirectives(css: string): string {
+  return css
+    .replace(/@apply\s+([^;]+);/g, (_match, classes: string) => {
+      let fixed = classes;
+      // flex-grow-0 → grow-0
+      fixed = fixed.replace(/\bflex-grow-0\b/g, "grow-0");
+      fixed = fixed.replace(/\bflex-grow\b/g, "grow");
+      fixed = fixed.replace(/\bflex-shrink-0\b/g, "shrink-0");
+      fixed = fixed.replace(/\bflex-shrink\b/g, "shrink");
+      // transform → removed (auto in v4)
+      fixed = fixed.replace(/\btransform\b(?!-none)/g, "");
+      fixed = fixed.replace(/\bfilter\b/g, "");
+      // ring → ring-3
+      fixed = fixed.replace(/\bring\b(?!-)/g, "ring-3");
+      // Clean up multiple spaces
+      fixed = fixed.replace(/\s{2,}/g, " ").trim();
+      return `@apply ${fixed};`;
+    });
+}
+
+/**
+ * Test if a value looks like oklch coordinates (space-separated numbers,
+ * possibly with `/` for alpha). Examples: "0.5 0.2 30", "0.8 0.15 120 / 0.5"
+ * This distinguishes oklch coordinate values from hex colors.
+ */
+function isOklchCoordinates(val: string): boolean {
+  const trimmed = val.trim();
+  // oklch coordinates: 2-3 space-separated numbers, possibly with / alpha
+  // e.g. "0.5 0.2 30" or "0.85 0.15 120 / 0.5"
+  return /^[\d.]+\s+[\d.]+\s+[\d.]+(\s*\/\s*[\d.]+)?$/.test(trimmed);
+}
+
+/**
+ * Extract the primary font family from @font-face declarations in CSS.
+ * Returns the first font-family name found, or null.
+ */
+function extractPrimaryFontFromCss(css: string): string | null {
+  const fontFaceRe = /@font-face\s*\{[^}]*font-family:\s*["']?([^"';]+)["']?\s*;/g;
+  const families = new Set<string>();
+  let match;
+  while ((match = fontFaceRe.exec(css)) !== null) {
+    families.add(match[1].trim());
+  }
+  if (families.size === 0) return null;
+  // Prefer non-icon fonts
+  const nonIcon = [...families].filter(
+    (f) => !/icon|awesome|material/i.test(f),
+  );
+  return nonIcon[0] || [...families][0];
+}
+
+export function generateAppCss(ctx: MigrationContext, theme?: ExtractedTheme): string {
+  const sections: string[] = [];
+
+  // ── DaisyUI theme plugin ──────────────────────────────────────────
+  const daisyColors = theme?.daisyUiColors ?? {};
+  const c = ctx.themeColors;
+
+  const semanticColors: Record<string, string> = {
+    "--color-primary": daisyColors["--color-primary"] || c["primary"] || "#B10200",
+    "--color-secondary": daisyColors["--color-secondary"] || c["secondary"] || "#141414",
+    "--color-accent": daisyColors["--color-accent"] || c["tertiary"] || "#FFF100",
+    "--color-neutral": daisyColors["--color-neutral"] || c["neutral"] || "#393939",
+    "--color-base-100": daisyColors["--color-base-100"] || c["base-100"] || "#FFFFFF",
+    "--color-base-200": daisyColors["--color-base-200"] || c["base-200"] || "#F3F3F3",
+    "--color-base-300": daisyColors["--color-base-300"] || c["base-300"] || "#868686",
+    "--color-info": daisyColors["--color-info"] || c["info"] || "#006CA1",
+    "--color-success": daisyColors["--color-success"] || c["success"] || "#007552",
+    "--color-warning": daisyColors["--color-warning"] || c["warning"] || "#F8D13A",
+    "--color-error": daisyColors["--color-error"] || c["error"] || "#CF040A",
+  };
+
+  const colorLines = Object.entries(semanticColors)
+    .map(([k, v]) => `  ${k}: ${v};`)
+    .join("\n");
+
+  sections.push(`@import "tailwindcss";
+@plugin "daisyui";
+@plugin "daisyui/theme" {
+  name: "light";
+  default: true;
+  color-scheme: light;
+${colorLines}
+}`);
+
+  // ── @theme block: Tailwind v3->v4 color migration ─────────────────
+  // Determine font family from theme, context, or original CSS @font-face
+  let fontFamily = theme?.fontFamily || ctx.fontFamily;
+  if (!fontFamily) {
+    const originalCssForFont = findOriginalCss(ctx);
+    if (originalCssForFont) {
+      const extracted = extractPrimaryFontFromCss(originalCssForFont);
+      if (extracted) fontFamily = extracted;
+    }
+  }
+  let fontLine = "";
+  if (fontFamily) {
+    const firstFont = fontFamily.split(",")[0].trim().replace(/['"]/g, "");
+    fontLine = `\n  --font-sans: "${firstFont}", ui-sans-serif, system-ui, sans-serif;`;
+  }
+
+  let themeBlock = `/* Tailwind v4: reset default palette (old sites replaced it entirely via theme.colors)
+   then re-add only the colors used by this site. */
+@theme {
+  --color-*: initial;
+
+  --color-white: #fff;
+  --color-black: #000;
+  --color-transparent: transparent;
+  --color-current: currentColor;
+  --color-inherit: inherit;${fontLine}`;
+
+  // Add extracted theme variables to @theme
+  // Theme variables come from the CMS Theme section (.deco/blocks/Theme-*.json).
+  // The CMS sets CSS custom properties on :root at runtime, so @theme entries
+  // should reference var(--x) instead of hardcoding values. For oklch-formatted
+  // values (space-separated numbers like "0.5 0.2 30"), wrap with oklch().
+  const vars = theme?.variables ?? {};
+  if (Object.keys(vars).length > 0) {
+    themeBlock += `\n`;
+    const grouped: Record<string, Array<[string, string]>> = {};
+    for (const [k, v] of Object.entries(vars)) {
+      const prefix = k.replace(/^--/, "").split("-").slice(0, 2).join("-");
+      if (!grouped[prefix]) grouped[prefix] = [];
+      grouped[prefix].push([k, v]);
+    }
+
+    for (const [prefix, entries] of Object.entries(grouped)) {
+      themeBlock += `\n  /* ${prefix} */`;
+      for (const [k, v] of entries) {
+        if (!k.startsWith("--color-") && !k.startsWith("--font-") && !k.startsWith("--breakpoint-")) {
+          const val = v.trim();
+          const isColor = /^#[0-9a-fA-F]{3,8}$/.test(val) ||
+            /^(rgb|hsl|oklch|oklab)\(/.test(val) ||
+            /^(transparent|currentColor|inherit)$/.test(val) ||
+            isOklchCoordinates(val);
+          if (isColor) {
+            const varName = k.replace(/^--/, "");
+            const colorKey = `--color-${varName}`;
+            if (isOklchCoordinates(val)) {
+              themeBlock += `\n  ${colorKey}: oklch(var(${k}));`;
+            } else {
+              themeBlock += `\n  ${colorKey}: var(${k});`;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Gray scale compat (Tailwind v3 had gray-50..gray-950 by default)
+  themeBlock += `
+
+  /* Gray scale (Tailwind v3 default, required for bg-gray-*, text-gray-*, etc.) */
+  --color-gray-50: #f9fafb;
+  --color-gray-100: #f3f4f6;
+  --color-gray-200: #e5e7eb;
+  --color-gray-300: #d1d5db;
+  --color-gray-400: #9ca3af;
+  --color-gray-500: #6b7280;
+  --color-gray-600: #4b5563;
+  --color-gray-700: #374151;
+  --color-gray-800: #1f2937;
+  --color-gray-900: #111827;
+  --color-gray-950: #030712;
+}`;
+  sections.push(themeBlock);
+
+  // ── DaisyUI v5 compat ─────────────────────────────────────────────
+  sections.push(`/* DaisyUI v5: flatten depth/noise to match v4 look */
+:root {
+  --depth: 0;
+  --noise: 0;
+}`);
+
+  // ── :root theme variables ─────────────────────────────────────────
+  if (Object.keys(vars).length > 0) {
+    let rootBlock = `:root {\n`;
+    for (const [k, v] of Object.entries(vars)) {
+      rootBlock += `  ${k}: ${v};\n`;
+    }
+    if (fontFamily) {
+      const firstFont = fontFamily.split(",")[0].trim().replace(/['"]/g, "");
+      rootBlock += `  --font-family: ${firstFont}, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;\n`;
+    }
+    rootBlock += `}`;
+    sections.push(rootBlock);
+  }
+
+  // ── DaisyUI v5 carousel overflow fix ──────────────────────────────
+  sections.push(`/* DaisyUI v5 removed carousel overflow — re-add for horizontal scroll */
+.carousel {
+  -webkit-overflow-scrolling: touch;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  scroll-behavior: smooth;
+}
+
+.carousel > * {
+  scroll-snap-align: start;
+}
+
+ul.carousel,
+ol.carousel {
+  list-style: none;
+  padding: 0;
+}`);
+
+  // ── Container utility (v3 -> v4 migration) ────────────────────────
+  sections.push(`/* Container: replaces Tailwind v3 container plugin config */
+@utility container {
+  margin-inline: auto;
+  padding-inline: 1rem;
+  width: 100%;
+
+  @media (width >= 640px) { max-width: 640px; }
+  @media (width >= 768px) { max-width: 768px; }
+  @media (width >= 1024px) { max-width: 1024px; }
+  @media (width >= 1280px) { max-width: 1280px; }
+  @media (width >= 1536px) { max-width: 1536px; }
+}`);
+
+  // ── Deferred section visibility ───────────────────────────────────
+  sections.push(`/* Deferred section visibility — reduces layout shift while loading */
+section[data-deferred="true"] {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 300px;
+}
+
+.deferred-section {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 300px;
+}`);
+
+  // ── View transitions ──────────────────────────────────────────────
+  sections.push(`@view-transition {
+  navigation: auto;
+}`);
+
+  // ── Base layer resets ─────────────────────────────────────────────
+  sections.push(`@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  body {
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  img,
+  picture,
+  video,
+  canvas,
+  svg {
+    display: block;
+    max-width: 100%;
+  }
+
+  /* Drawer / modal scroll lock */
+  body:has(dialog[open]),
+  body:has(.drawer-toggle:checked) {
+    overflow: hidden;
+  }
+
+  /* Tailwind v3 → v4 compat: restore the default cursor:pointer on interactive
+     elements. Tailwind v4 dropped this from Preflight, leaving Fresh-era sites
+     with hundreds of buttons looking unclickable. See:
+     https://tailwindcss.com/docs/upgrade-guide#default-button-cursor */
+  button:not(:disabled),
+  [role="button"]:not([aria-disabled="true"]),
+  label[for],
+  summary {
+    cursor: pointer;
+  }
+  button:disabled,
+  [role="button"][aria-disabled="true"] {
+    cursor: not-allowed;
+  }
+}`);
+
+  // ── Scrollbar utility ─────────────────────────────────────────────
+  sections.push(`.scrollbar-none {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.scrollbar-none::-webkit-scrollbar {
+  display: none;
+}`);
+
+  // ── Incorporate original site's custom CSS ────────────────────
+  // Instead of throwing away the site's CSS, we extract and append
+  // all custom rules (component overrides, @layer base, @font-face,
+  // typography utilities, feature-specific CSS, etc.)
+  const originalCss = findOriginalCss(ctx);
+  if (originalCss) {
+    const customCss = extractCustomCss(originalCss);
+    if (customCss) {
+      const transformed = transformApplyDirectives(customCss);
+      sections.push(`/* ═══════════════════════════════════════════════════════════════
+   Original site CSS (migrated from tailwind.css)
+   ═══════════════════════════════════════════════════════════════ */
+
+${transformed}`);
+    }
+  }
+
+  return sections.join("\n\n") + "\n";
+}

package/scripts/migrate/templates/cache-config.ts

@@ -0,0 +1,26 @@
+import type { MigrationContext } from "../types";
+
+export function generateCacheConfig(ctx: MigrationContext): string {
+  if (ctx.platform !== "vtex") {
+    return `/**
+ * Cache configuration — customize edge cache profiles per route type.
+ * See @decocms/start/sdk/cacheHeaders for available profiles.
+ */
+// import { setCacheProfile } from "@decocms/start/sdk/cacheHeaders";
+// setCacheProfile("product", { sMaxAge: 300, staleWhileRevalidate: 600 });
+`;
+  }
+
+  return `/**
+ * Cache configuration for VTEX storefront.
+ * Overrides default cache profiles from @decocms/start/sdk/cacheHeaders.
+ */
+// import { setCacheProfile } from "@decocms/start/sdk/cacheHeaders";
+
+// Uncomment and adjust as needed:
+// setCacheProfile("product", { sMaxAge: 300, staleWhileRevalidate: 600 });
+// setCacheProfile("listing", { sMaxAge: 120, staleWhileRevalidate: 300 });
+// setCacheProfile("search", { sMaxAge: 60, staleWhileRevalidate: 120 });
+// setCacheProfile("static", { sMaxAge: 86400, staleWhileRevalidate: 172800 });
+`;
+}

package/scripts/migrate/templates/commerce-loaders.ts

@@ -0,0 +1,230 @@
+import type { MigrationContext } from "../types";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+function hasLoaderByName(ctx: MigrationContext, name: string): boolean {
+  return ctx.loaderInventory.some(
+    (l) => l.path.toLowerCase().includes(name.toLowerCase()),
+  );
+}
+
+function fileExists(ctx: MigrationContext, relPath: string): boolean {
+  const full = path.join(ctx.sourceDir, relPath);
+  if (fs.existsSync(full)) return true;
+  const src = path.join(ctx.sourceDir, "src", relPath);
+  return fs.existsSync(src);
+}
+
+export function generateCommerceLoaders(ctx: MigrationContext): string {
+  const lines: string[] = [];
+  const hasSecrets = fileExists(ctx, "utils/secrets.ts") || fileExists(ctx, "src/utils/secrets.ts");
+  const hasProductReviews = hasLoaderByName(ctx, "reviews/productReviews");
+  const hasBuyTogether = hasLoaderByName(ctx, "product/buyTogether");
+  const hasAutocomplete = hasLoaderByName(ctx, "intelligenseSearch") || hasLoaderByName(ctx, "intelligentSearch");
+  const hasVtexAuth = hasLoaderByName(ctx, "vtex-auth-loader");
+  const hasCollectionPLP = hasLoaderByName(ctx, "productListPageCollection");
+  const hasStores = hasLoaderByName(ctx, "stores");
+  const hasProductCard = hasLoaderByName(ctx, "Layouts/ProductCard");
+  const hasSitename = fileExists(ctx, "utils/sitename.ts") || fileExists(ctx, "src/utils/sitename.ts");
+
+  lines.push(`/**`);
+  lines.push(` * Commerce Loaders — data fetchers registered for CMS block resolution.`);
+  lines.push(` *`);
+  lines.push(` * Standard VTEX loaders come from createVtexCommerceLoaders().`);
+  lines.push(` * Auto-generated pass-throughs come from loaders.gen.ts.`);
+  lines.push(` * This file only contains entries that need custom wiring`);
+  lines.push(` * (cookie injection, secrets, serialization, etc.).`);
+  lines.push(` */`);
+
+  if (ctx.platform === "vtex") {
+    lines.push(`import { getVtexConfig } from "@decocms/apps/vtex";`);
+    lines.push(`import { createVtexCommerceLoaders, createCachedPDPLoader } from "@decocms/apps/vtex/commerceLoaders";`);
+    if (hasAutocomplete) {
+      lines.push(`import { autocompleteSearch } from "@decocms/apps/vtex/loaders/autocomplete";`);
+    }
+    lines.push(`import { getAddressByPostalCode } from "@decocms/apps/vtex/loaders/address";`);
+    lines.push(`import { createAddressFromRequest, updateAddressFromRequest, deleteAddressFromRequest } from "@decocms/apps/vtex/actions/address";`);
+    lines.push(`import { updateProfileFromRequest, newsletterProfileFromRequest, deletePaymentFromRequest, getPasswordLastUpdate } from "@decocms/apps/vtex/actions/profile";`);
+    lines.push(`import { createCachedLoader } from "@decocms/start/sdk/cachedLoader";`);
+
+    if (hasVtexAuth) {
+      lines.push(`import vtexAuthLoader from "../loaders/vtex-auth-loader";`);
+    }
+    if (hasProductReviews) {
+      lines.push(`import productReviewsLoader from "../loaders/reviews/productReviews";`);
+    }
+    if (hasBuyTogether) {
+      lines.push(`import buyTogetherLoader from "../loaders/product/buyTogether";`);
+    }
+    if (hasSecrets) {
+      lines.push(`import { secrets } from "../utils/secrets";`);
+    }
+    if (hasSitename && hasCollectionPLP) {
+      lines.push(`import { useAccount } from "../utils/sitename";`);
+    }
+
+    // Always import siteLoaders — the generate:loaders script creates this file
+    lines.push(`import { siteLoaders } from "../server/cms/loaders.gen";`);
+    lines.push(``);
+
+    lines.push(`const DOMAIN_RE = /;\\s*domain=[^;]*/gi;`);
+    lines.push(``);
+    lines.push(`export const vtexLoaders = createVtexCommerceLoaders();`);
+    lines.push(`export const cachedPDP = createCachedPDPLoader();`);
+
+    if (hasCollectionPLP) {
+      lines.push(`const cachedPLP = vtexLoaders["vtex/loaders/intelligentSearch/productListingPage.ts"];`);
+    }
+    if (hasAutocomplete) {
+      lines.push(`const cachedAutocomplete = createCachedLoader("vtex/autocomplete", autocompleteSearch, "search");`);
+    }
+
+    lines.push(``);
+    lines.push(``);
+  }
+
+  lines.push(`export const COMMERCE_LOADERS: Record<string, (props: any, request?: Request) => Promise<any>> = {`);
+
+  if (ctx.platform === "vtex") {
+    lines.push(`  ...vtexLoaders,`);
+    lines.push(`  ...siteLoaders,`);
+    lines.push(``);
+
+    // Autocomplete aliases
+    if (hasAutocomplete) {
+      lines.push(`  // Autocomplete search — from @decocms/apps`);
+      lines.push(`  "site/loaders/search/intelligenseSearch.ts": cachedAutocomplete,`);
+      lines.push(`  "site/loaders/search/intelligenseSearch": cachedAutocomplete,`);
+      lines.push(``);
+    }
+
+    // Stores pass-through
+    if (hasStores) {
+      lines.push(`  // Stores pass-through`);
+      lines.push(`  "site/loaders/stores.ts": async (props: any) => {`);
+      lines.push(`    const result = props.stores ?? props ?? [];`);
+      lines.push(`    return Array.isArray(result) ? result : [];`);
+      lines.push(`  },`);
+      lines.push(``);
+    }
+
+    // VTEX address CRUD
+    lines.push(`  // VTEX address CRUD — request-aware wrappers from @decocms/apps`);
+    lines.push(`  "vtex/actions/address/createAddress": createAddressFromRequest as any,`);
+    lines.push(`  "vtex/actions/address/updateAddress": updateAddressFromRequest as any,`);
+    lines.push(`  "vtex/actions/address/deleteAddress": deleteAddressFromRequest as any,`);
+    lines.push(`  "vtex/loaders/address/getAddressByZIP": async (props: any) => {`);
+    lines.push(`    return getAddressByPostalCode(props.countryCode, props.postalCode);`);
+    lines.push(`  },`);
+    lines.push(``);
+
+    // Auth cookie stripping
+    if (hasVtexAuth) {
+      lines.push(`  // VTEX auth (Set-Cookie forwarding)`);
+      lines.push(`  "site/loaders/vtex-auth-loader": async (props: any) => {`);
+      lines.push(`    const result = await vtexAuthLoader(props);`);
+      lines.push(`    if (result instanceof Response) {`);
+      lines.push(`      const setCookies = result.headers.getSetCookie?.() ?? [];`);
+      lines.push(`      const strippedCookies = setCookies.map((c) => c.replace(DOMAIN_RE, ""));`);
+      lines.push(`      const body = await result.text();`);
+      lines.push(`      const headers = new Headers({ "Content-Type": "application/json" });`);
+      lines.push(`      for (const cookie of strippedCookies) {`);
+      lines.push(`        headers.append("Set-Cookie", cookie);`);
+      lines.push(`      }`);
+      lines.push(`      return new Response(body, { status: result.status, headers });`);
+      lines.push(`    }`);
+      lines.push(`    return result;`);
+      lines.push(`  },`);
+      lines.push(``);
+    }
+
+    // ProductCard dynamic import
+    if (hasProductCard) {
+      lines.push(`  // CMS-referenced site loaders`);
+      lines.push(`  "site/loaders/Layouts/ProductCard.tsx": async (props: any) => {`);
+      lines.push(`    const mod = await import("../loaders/Layouts/ProductCard");`);
+      lines.push(`    return mod.default(props);`);
+      lines.push(`  },`);
+    }
+
+    // Reviews with secrets
+    if (hasProductReviews) {
+      lines.push(`  "site/loaders/reviews/productReviews.ts": async (props: any) => {`);
+      lines.push(`    const { account } = getVtexConfig();`);
+      lines.push(`    const result = await productReviewsLoader(props, null as any, { account${hasSecrets ? ", ...secrets" : ""} } as any);`);
+      lines.push(`    if (!result) return result;`);
+      lines.push(`    const { getProductReview: _r, reviewLikeAction: _l, reviewVote: _v, getProductsListReviews: _p, ...serializable } = result as any;`);
+      lines.push(`    return serializable;`);
+      lines.push(`  },`);
+    }
+
+    // BuyTogether with secrets
+    if (hasBuyTogether) {
+      lines.push(`  "site/loaders/product/buyTogether.ts": async (props: any) => {`);
+      lines.push(`    const { account } = getVtexConfig();`);
+      lines.push(`    return buyTogetherLoader(props, null as any, { account${hasSecrets ? ", ...secrets" : ""} } as any);`);
+      lines.push(`  },`);
+    }
+
+    // Collection PLP
+    if (hasCollectionPLP && hasSitename) {
+      lines.push(``);
+      lines.push(`  // Collection PLP`);
+      lines.push(`  "site/loaders/search/productListPageCollection.ts": async (props: any) => {`);
+      lines.push(`    const url = new URL(props.__pageUrl || props.__pagePath || "/", "https://localhost");`);
+      lines.push(`    const { search_collection_urls_cvlb } = await import("../utils/search-collection-url-cvlb");`);
+      lines.push(`    const { createBreadcrumbFromPath } = await import("../utils/plpHelpers/plpCollection");`);
+      lines.push(`    const { an: accountName } = useAccount();`);
+      lines.push(`    const collections = search_collection_urls_cvlb[accountName] ?? [];`);
+      lines.push(``);
+      lines.push(`    const normalize = (t: string) =>`);
+      lines.push(`      t.normalize("NFD").replace(/[\\u0300-\\u036f]/g, "").toLowerCase()`);
+      lines.push(`        .replace(/[^a-z0-9\\s-]/g, "").replace(/\\s+/g, "-").replace(/-+/g, "-");`);
+      lines.push(``);
+      lines.push(`    const slug = decodeURIComponent(url.pathname.split("/").pop() ?? "").replace(/-/g, " ");`);
+      lines.push(`    const now = Date.now();`);
+      lines.push(`    const collection = collections.find((c: any) =>`);
+      lines.push(`      normalize(c.name) === normalize(slug) &&`);
+      lines.push(`      new Date(c.dateFrom).getTime() <= now &&`);
+      lines.push(`      now <= new Date(c.dateTo).getTime()`);
+      lines.push(`    );`);
+      lines.push(`    if (!collection) return null;`);
+      lines.push(``);
+      lines.push(`    const collectionId = String(collection.id);`);
+      lines.push(`    const response = await cachedPLP({`);
+      lines.push(`      ...props,`);
+      lines.push(`      selectedFacets: [{ key: "productClusterIds", value: collectionId }],`);
+      lines.push(`      __pageUrl: url.toString(),`);
+      lines.push(`      __pagePath: url.pathname,`);
+      lines.push(`    });`);
+      lines.push(`    if (!response) return null;`);
+      lines.push(``);
+      lines.push(`    return {`);
+      lines.push(`      ...response,`);
+      lines.push(`      breadcrumb: createBreadcrumbFromPath(url.pathname, url, collection.name) ?? {},`);
+      lines.push(`      seo: {`);
+      lines.push(`        title: collection.name,`);
+      lines.push(`        // MIGRATION TODO: replace with site-specific category description`);
+      lines.push(`        description: collection.name,`);
+      lines.push(`        noIndexing: false,`);
+      lines.push(`        canonical: url.toString(),`);
+      lines.push(`      },`);
+      lines.push(`    };`);
+      lines.push(`  },`);
+    }
+
+    lines.push(``);
+    // Profile actions
+    lines.push(`  // Profile actions — request-aware wrappers from @decocms/apps`);
+    lines.push(`  "vtex/actions/profile/updateProfile": updateProfileFromRequest as any,`);
+    lines.push(`  "vtex/actions/profile/updateProfile.ts": updateProfileFromRequest as any,`);
+    lines.push(`  "vtex/actions/profile/newsletterProfile": newsletterProfileFromRequest as any,`);
+    lines.push(`  "vtex/actions/profile/newsletterProfile.ts": newsletterProfileFromRequest as any,`);
+    lines.push(`  "vtex/actions/payments/delete": deletePaymentFromRequest as any,`);
+    lines.push(`  "vtex/loaders/profile/passwordLastUpdate": getPasswordLastUpdate as any,`);
+  }
+
+  lines.push(`};`);
+
+  return lines.join("\n") + "\n";
+}

package/scripts/migrate/templates/cursor-rules.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { generateMigrationPolicyPointerRule } from "./cursor-rules";
+
+describe("generateMigrationPolicyPointerRule", () => {
+	const body = generateMigrationPolicyPointerRule("acme");
+
+	it("emits a Cursor MDC rule with alwaysApply: true frontmatter", () => {
+		expect(body.startsWith("---\n")).toBe(true);
+		expect(body).toContain("alwaysApply: true");
+		expect(body).toContain("description:");
+	});
+
+	it("interpolates the site name into the body", () => {
+		expect(body).toContain("`acme`");
+	});
+
+	it("links to the canonical rule and plan in decocms/deco-start", () => {
+		expect(body).toContain(
+			"https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc",
+		);
+		expect(body).toContain(
+			"https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md",
+		);
+	});
+
+	it("documents D1–D5 by ID, not just by name", () => {
+		expect(body).toContain("**D1**");
+		expect(body).toContain("**D2**");
+		expect(body).toContain("**D3**");
+		expect(body).toContain("**D4**");
+		expect(body).toContain("**D5**");
+	});
+
+	it("points at the post-cleanup --fix command rather than restating policy", () => {
+		expect(body).toContain("deco-post-cleanup --fix");
+		expect(body).toContain("deco-post-cleanup --strict");
+	});
+
+	it("does NOT restate the canonical rule body verbatim (pointer, not a copy)", () => {
+		// Length budget: pointer must stay short to discourage drift.
+		// The canonical rule in decocms/deco-start is ~110 lines / 4–5 KB;
+		// the pointer must be substantially smaller than a copy.
+		expect(body.length).toBeLessThan(3000);
+	});
+
+	it("is deterministic — same site name, same output", () => {
+		const a = generateMigrationPolicyPointerRule("foo");
+		const b = generateMigrationPolicyPointerRule("foo");
+		expect(a).toBe(b);
+	});
+
+	it("escapes nothing weird from siteName — siteName is used as a label only", () => {
+		// We don't sanitise; we trust the migration script to pass a real
+		// package name. But verify nothing surprising happens with hyphens
+		// (a common shape, e.g. "casaevideo-storefront").
+		const out = generateMigrationPolicyPointerRule("casaevideo-storefront");
+		expect(out).toContain("`casaevideo-storefront`");
+	});
+});