@decocms/blocks-cli 7.20.10 → 7.21.1

package/scripts/migrate/phase-analyze.ts

@@ -10,6 +10,7 @@ import { log, logPhase } from "./types";
 import { extractSectionMetadata } from "./analyzers/section-metadata";
 import { classifyIslands } from "./analyzers/island-classifier";
 import { inventoryLoaders } from "./analyzers/loader-inventory";
+import { extractTailwindConfig } from "./analyzers/tailwind-config";
 
 const PATTERN_DETECTORS: Array<[DetectedPattern, RegExp]> = [
   ["preact-hooks", /from\s+["']preact\/hooks["']/],
@@ -632,6 +633,18 @@ export function analyze(ctx: MigrationContext): void {
   ctx.themeColors = theme.colors;
   ctx.fontFamily = theme.fontFamily;
 
+  // Extract the source site's tailwind.config.ts BEFORE it gets deleted in
+  // cleanup — otherwise custom colors/fontFamily/safelist are silently
+  // dropped (see decocms/blocks#369, gotcha #48 in the migration skill).
+  ctx.tailwindConfig = extractTailwindConfig(ctx.sourceDir);
+  const twColorCount = Object.keys(ctx.tailwindConfig.colors).length;
+  if (twColorCount > 0) {
+    console.log(`  Tailwind config: ${twColorCount} custom color(s) ported from tailwind.config.ts`);
+  }
+  if (ctx.tailwindConfig.reviewItems.length > 0) {
+    ctx.manualReviewItems.push(...ctx.tailwindConfig.reviewItems);
+  }
+
   console.log(`  Site: ${ctx.siteName}`);
   console.log(`  Platform: ${ctx.platform}${ctx.vtexAccount ? ` (account: ${ctx.vtexAccount})` : ""}`);
   console.log(`  GTM ID: ${ctx.gtmId || "none"}`);

package/scripts/migrate/phase-cleanup.test.ts

@@ -20,6 +20,7 @@ function makeCtx(sourceDir: string, dryRun = false): MigrationContext {
     importMap: {},
     discoveredNpmDeps: {},
     themeColors: {},
+  tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
     fontFamily: null,
     files: [],
     sectionMetas: [],

package/scripts/migrate/phase-compile.test.ts

@@ -16,6 +16,7 @@ function makeCtx(sourceDir: string, dryRun = false): MigrationContext {
 		importMap: {},
 		discoveredNpmDeps: {},
 		themeColors: {},
+	tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
 		fontFamily: null,
 		files: [],
 		sectionMetas: [],
@@ -172,6 +173,53 @@ describe("compile (phase 8)", () => {
 		expect(result.typecheck.passed).toBe(false);
 		expect(result.build.passed).toBe(true);
 	});
+
+	it("skips the CSS compile check when src/styles/app.css doesn't exist", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		const ctx = makeCtx(tmpDir);
+		const { runner, calls } = fakeRunner({
+			"npx tsc --noEmit": { ok: true },
+		});
+		const result = compile(ctx, { runner });
+		expect(result.css.ran).toBe(false);
+		expect(calls).toEqual(["npx tsc --noEmit"]);
+	});
+
+	it("runs and fails the CSS compile check when app.css exists and the CLI errors", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		fs.mkdirSync(path.join(tmpDir, "src", "styles"), { recursive: true });
+		fs.writeFileSync(path.join(tmpDir, "src", "styles", "app.css"), "@import \"tailwindcss\";\n");
+		const ctx = makeCtx(tmpDir);
+		const { runner } = fakeRunner({
+			"npx tsc --noEmit": { ok: true },
+		});
+		const cssAwareRunner = (cmd: string, cwd: string) => {
+			if (cmd.includes("@tailwindcss/cli")) {
+				return { ok: false, output: "Cannot apply unknown utility class `font-bebas-neue`" };
+			}
+			return runner(cmd, cwd);
+		};
+		const result = compile(ctx, { runner: cssAwareRunner });
+		expect(result.css.ran).toBe(true);
+		expect(result.css.passed).toBe(false);
+		expect(result.css.output).toContain("font-bebas-neue");
+		expect(result.shouldFail).toBe(false); // non-strict: warning only
+	});
+
+	it("promotes a CSS compile failure to abort in --strict mode", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		fs.mkdirSync(path.join(tmpDir, "src", "styles"), { recursive: true });
+		fs.writeFileSync(path.join(tmpDir, "src", "styles", "app.css"), "@import \"tailwindcss\";\n");
+		const ctx = makeCtx(tmpDir);
+		const cssAwareRunner = (cmd: string): CompileRunResult => {
+			if (cmd.includes("@tailwindcss/cli")) return { ok: false, output: "invalid CSS" };
+			return { ok: true };
+		};
+		const result = compile(ctx, { runner: cssAwareRunner, strict: true });
+		expect(result.typecheck.passed).toBe(true);
+		expect(result.css.passed).toBe(false);
+		expect(result.shouldFail).toBe(true);
+	});
 });
 
 describe("truncate helper", () => {

package/scripts/migrate/phase-compile.ts

@@ -25,6 +25,7 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { gray, green, red, yellow } from "./colors";
+import { checkCssCompiles } from "./css-compile-check";
 import type { MigrationContext } from "./types";
 import { logPhase } from "./types";
 
@@ -48,6 +49,15 @@ export interface CompileResult {
 	skipped: boolean;
 	typecheck: { ran: boolean; passed: boolean; output?: string };
 	build: { ran: boolean; passed: boolean; output?: string };
+	/**
+	 * Real Tailwind v4 compilation of src/styles/app.css via the site's own
+	 * `@tailwindcss/cli` install. Catches the exact failure mode of
+	 * decocms/blocks#369 / skill gotcha #48 (dropped custom theme tokens ->
+	 * "Cannot apply unknown utility class") during migration instead of at
+	 * runtime. `unmatchedClassWarnings` is informational only — it never
+	 * fails the build (see css-compile-check.ts for why).
+	 */
+	css: { ran: boolean; passed: boolean; output?: string; unmatchedClassWarnings: string[] };
 	/** True iff compile decided the migration should fail (only in strict mode). */
 	shouldFail: boolean;
 }
@@ -96,6 +106,7 @@ export function compile(
 		skipped: false,
 		typecheck: { ran: false, passed: false },
 		build: { ran: false, passed: false },
+		css: { ran: false, passed: false, unmatchedClassWarnings: [] },
 		shouldFail: false,
 	};
 
@@ -136,6 +147,32 @@ export function compile(
 		console.log("");
 	}
 
+	// CSS compile check — real Tailwind v4 build of src/styles/app.css.
+	console.log("  Running: CSS compile check (npx @tailwindcss/cli)...");
+	const cssResult = checkCssCompiles(ctx, runner);
+	result.css.ran = cssResult.ran;
+	result.css.passed = cssResult.passed;
+	result.css.unmatchedClassWarnings = cssResult.unmatchedClassWarnings;
+
+	if (!cssResult.ran) {
+		console.log(`  ${gray("–")} Skipped (no src/styles/app.css)`);
+	} else if (cssResult.passed) {
+		console.log(`  ${green("✓")} CSS compiled`);
+		if (cssResult.unmatchedClassWarnings.length > 0) {
+			console.log(
+				`  ${yellow("⚠")} ${cssResult.unmatchedClassWarnings.length} class(es) used in src/ produced no CSS output (dropped theme token or typo?):`,
+			);
+			console.log(`    ${cssResult.unmatchedClassWarnings.slice(0, 20).join(", ")}`);
+		}
+	} else {
+		result.css.output = cssResult.output;
+		const output = truncate(cssResult.output ?? "", MAX_OUTPUT_LINES);
+		const icon = opts.strict ? red("✗") : yellow("⚠");
+		console.log(`  ${icon} CSS compile failed:\n`);
+		console.log(output);
+		console.log("");
+	}
+
 	// Optional Vite build (heavier, opt-in).
 	if (opts.withBuild) {
 		console.log("  Running: Vite build (npx vite build)...");
@@ -158,6 +195,7 @@ export function compile(
 	// Decide whether to fail the migration.
 	const anyFailed =
 		(result.typecheck.ran && !result.typecheck.passed) ||
+		(result.css.ran && !result.css.passed) ||
 		(result.build.ran && !result.build.passed);
 
 	if (anyFailed && opts.strict) {

package/scripts/migrate/phase-report.test.ts

@@ -0,0 +1,103 @@
+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 { report } from "./phase-report";
+import { createContext } from "./types";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "phase-report-test-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("report — CSS Migration section", () => {
+  it("summarizes tokens ported from tailwind.config.ts", () => {
+    const ctx = createContext(tmpDir);
+    ctx.tailwindConfig = {
+      colors: { perola: "#F5F0E8", "brand-500": "#B10200" },
+      fontFamily: { "bebas-neue": "Bebas Neue, sans-serif" },
+      screens: {},
+      safelist: ["bg-red-500"],
+      safelistPatterns: [],
+      plugins: [],
+      reviewItems: [],
+    };
+
+    report(ctx);
+
+    const content = fs.readFileSync(path.join(tmpDir, "MIGRATION_REPORT.md"), "utf-8");
+    expect(content).toContain("## CSS Migration");
+    expect(content).toContain("2 color(s), 1 font stack(s), 0 breakpoint(s)");
+    expect(content).toContain("1 safelist entrie(s)");
+  });
+
+  it("lists CSS-specific manual review items separately from unrelated ones", () => {
+    const ctx = createContext(tmpDir);
+    ctx.manualReviewItems = [
+      {
+        file: "src/styles/app.css",
+        reason: "safelist pattern /^grid-cols-/ cannot be auto-converted",
+        severity: "warning",
+      },
+      {
+        file: "src/components/Foo.tsx",
+        reason: "useComponent(...) call site detected — needs manual React conversion",
+        severity: "error",
+      },
+    ];
+
+    report(ctx);
+
+    const content = fs.readFileSync(path.join(tmpDir, "MIGRATION_REPORT.md"), "utf-8");
+    const cssSection = content.split("## CSS Migration")[1].split("## Always Check")[0];
+    expect(cssSection).toContain("safelist pattern");
+    expect(cssSection).not.toContain("useComponent");
+  });
+
+  it("reports no CSS findings when none exist", () => {
+    const ctx = createContext(tmpDir);
+    report(ctx);
+    const content = fs.readFileSync(path.join(tmpDir, "MIGRATION_REPORT.md"), "utf-8");
+    expect(content).toContain("No CSS-specific findings from this run.");
+  });
+
+  it("does not miscategorize an unrelated finding whose reason merely contains 'collapse' as a substring of another word", () => {
+    const ctx = createContext(tmpDir);
+    ctx.manualReviewItems = [
+      {
+        file: "src/components/Nav.tsx",
+        reason: "the mobile nav state collapsed unexpectedly during the smoke test — needs manual QA",
+        severity: "warning",
+      },
+    ];
+
+    report(ctx);
+
+    const content = fs.readFileSync(path.join(tmpDir, "MIGRATION_REPORT.md"), "utf-8");
+    const cssSection = content.split("## CSS Migration")[1].split("## Always Check")[0];
+    expect(cssSection).toContain("No CSS-specific findings from this run.");
+    expect(cssSection).not.toContain("collapsed unexpectedly");
+  });
+
+  it("still categorizes a genuine DaisyUI collapse finding as CSS-specific", () => {
+    const ctx = createContext(tmpDir);
+    ctx.manualReviewItems = [
+      {
+        file: "src/components/Filters.tsx",
+        reason: "DaisyUI .collapse usage found — its expand/collapse chain breaks under Tailwind v4.",
+        severity: "warning",
+      },
+    ];
+
+    report(ctx);
+
+    const content = fs.readFileSync(path.join(tmpDir, "MIGRATION_REPORT.md"), "utf-8");
+    const cssSection = content.split("## CSS Migration")[1].split("## Always Check")[0];
+    expect(cssSection).toContain("DaisyUI .collapse usage found");
+  });
+});

package/scripts/migrate/phase-report.ts

@@ -1,8 +1,39 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MigrationContext } from "./types";
+import type { MigrationContext, ReviewItem } from "./types";
 import { logPhase } from "./types";
 
+// Word-only keywords are matched with \b boundaries so a generic English
+// word like "collapse" doesn't misfire on an unrelated finding's reason
+// text (e.g. a JS/UX note that happens to mention "collapse" in a
+// non-DaisyUI sense). Path-/symbol-like keywords (containing non-word
+// characters) are matched as plain substrings since \b doesn't apply to them.
+const CSS_REVIEW_KEYWORDS = [
+  "tailwind.config.ts",
+  "safelist",
+  "oklch",
+  "css-styling.md",
+  "@theme",
+  "@apply",
+  "@utility",
+  "DaisyUI",
+  "collapse",
+];
+
+const CSS_REVIEW_KEYWORD_MATCHERS = CSS_REVIEW_KEYWORDS.map((k) =>
+  /^\w+$/.test(k) ? new RegExp(`\\b${k}\\b`, "i") : k,
+);
+
+function isCssReviewItem(item: ReviewItem): boolean {
+  return (
+    item.file.endsWith("app.css") ||
+    item.file === "tailwind.config.ts" ||
+    CSS_REVIEW_KEYWORD_MATCHERS.some((k) =>
+      typeof k === "string" ? item.reason.includes(k) : k.test(item.reason),
+    )
+  );
+}
+
 const FRAMEWORK_FINDINGS = [
   "Session/analytics SDK is boilerplate duplicated across all sites — should be a single framework function",
   "GTM event system (useGTMEvent, data-gtm-* listeners) is universal pattern — should be in @decocms/blocks",
@@ -129,6 +160,37 @@ export function report(ctx: MigrationContext): void {
     lines.push("");
   }
 
+  // CSS Migration — replaces the old generic "DaisyUI/Tailwind" checkboxes
+  // with what was actually ported/detected for THIS site, so a human
+  // doesn't have to re-derive it from scratch.
+  lines.push("## CSS Migration");
+  lines.push("");
+  const twColorCount = Object.keys(ctx.tailwindConfig.colors).length;
+  const twFontCount = Object.keys(ctx.tailwindConfig.fontFamily).length;
+  const twScreenCount = Object.keys(ctx.tailwindConfig.screens).length;
+  const twSafelistCount = ctx.tailwindConfig.safelist.length;
+  lines.push(
+    `- **tailwind.config.ts porting**: ${twColorCount} color(s), ${twFontCount} font stack(s), ${twScreenCount} breakpoint(s) ported into \`src/styles/app.css\` \`@theme\`; ${twSafelistCount} safelist entrie(s) ported via \`@source inline(...)\`.`,
+  );
+  lines.push(
+    "- **Real CSS compile check**: runs in the compile phase (`npx @tailwindcss/cli`) against `src/styles/app.css` — catches unknown-utility-class errors before they ship. Re-run any time with `bun run tailwind:lint`.",
+  );
+
+  const cssReviewItems = ctx.manualReviewItems.filter(isCssReviewItem);
+  if (cssReviewItems.length > 0) {
+    lines.push("");
+    lines.push(`**${cssReviewItems.length} CSS-specific finding(s) requiring manual review:**`);
+    lines.push("");
+    for (const item of cssReviewItems) {
+      const icon = item.severity === "error" ? "🔴" : item.severity === "warning" ? "🟡" : "🔵";
+      lines.push(`${icon} **\`${item.file}\`**: ${item.reason}`);
+    }
+  } else {
+    lines.push("");
+    lines.push("- No CSS-specific findings from this run.");
+  }
+  lines.push("");
+
   // Always-present manual review items
   lines.push("## Always Check (site-specific)");
   lines.push("");
@@ -136,9 +198,7 @@ export function report(ctx: MigrationContext): void {
   lines.push("- [ ] `src/setup/section-loaders.ts` — verify extracted loaders work correctly");
   lines.push("- [ ] `src/hooks/useCart.ts` — wire to actual server functions for your platform");
   lines.push("- [ ] `src/worker-entry.ts` — verify CSP, proxy, and segment builder");
-  lines.push("- [ ] DaisyUI v4 to v5 class name changes");
-  lines.push("- [ ] Tailwind v3 to v4: verify all utility classes still work");
-  lines.push("- [ ] Check `src/styles/app.css` theme colors match the original design");
+  lines.push("- [ ] See the **CSS Migration** section above for DaisyUI v4→v5 / Tailwind v3→v4 findings specific to this site");
   lines.push("- [ ] Run `npm run generate:blocks` and `npm run generate:schema` after migration");
   lines.push("");
 

package/scripts/migrate/phase-verify.test.ts

@@ -28,6 +28,7 @@ function makeCtx(sourceDir: string): MigrationContext {
     importMap: {},
     discoveredNpmDeps: {},
     themeColors: {},
+  tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
     fontFamily: null,
     files: [],
     sectionMetas: [],

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

@@ -0,0 +1,150 @@
+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 { createContext } from "../types";
+import { generateAppCss } from "./app-css";
+
+describe("generateAppCss — tailwind.config.ts porting", () => {
+  it("emits custom colors, fonts, and breakpoints ported from tailwind.config.ts", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig = {
+      colors: { perola: "#F5F0E8", "brand-500": "#B10200" },
+      fontFamily: { "bebas-neue": "Bebas Neue, sans-serif" },
+      screens: { "3xl": "1920px" },
+      safelist: ["bg-red-500", "text-brand-500"],
+      safelistPatterns: [],
+      plugins: [],
+      reviewItems: [],
+    };
+
+    const css = generateAppCss(ctx);
+
+    expect(css).toContain("--color-perola: #F5F0E8;");
+    expect(css).toContain("--color-brand-500: #B10200;");
+    expect(css).toContain("--font-bebas-neue: Bebas Neue, sans-serif;");
+    expect(css).toContain("--breakpoint-3xl: 1920px;");
+    expect(css).toContain('@source inline("bg-red-500 text-brand-500");');
+  });
+
+  it("does not duplicate a custom color that collides with a daisyUI semantic key", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig.colors = { primary: "#000000" };
+
+    const css = generateAppCss(ctx);
+    // The daisyUI theme's own --color-primary is emitted once in the plugin
+    // block; the ported tailwind.config.ts value must not add a second,
+    // conflicting @theme declaration.
+    const themeBlockMatch = css.match(/@theme \{[\s\S]*?\n\}/);
+    expect(themeBlockMatch).not.toBeNull();
+    const occurrences = (themeBlockMatch![0].match(/--color-primary:/g) ?? []).length;
+    expect(occurrences).toBe(0);
+  });
+
+  it("flags unconvertible safelist regex patterns as manual review items", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig.safelistPatterns = ["/^grid-cols-/"];
+
+    generateAppCss(ctx);
+
+    expect(
+      ctx.manualReviewItems.some((i) => i.reason.includes("/^grid-cols-/")),
+    ).toBe(true);
+  });
+
+  it("uses a custom tailwind.config.ts gray-* override instead of declaring the v3 default gray scale a second time", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig.colors = { "gray-50": "#111111", "gray-500": "#222222" };
+
+    const css = generateAppCss(ctx);
+    const themeBlockMatch = css.match(/@theme \{[\s\S]*?\n\}/);
+    expect(themeBlockMatch).not.toBeNull();
+    const themeBlock = themeBlockMatch![0];
+
+    // gray-50/500 must be declared exactly once, with the custom value —
+    // not once with the custom value and once more with the hardcoded
+    // default (which would silently win via CSS's last-declaration-wins).
+    expect((themeBlock.match(/--color-gray-50:/g) ?? []).length).toBe(1);
+    expect(themeBlock).toContain("--color-gray-50: #111111;");
+    expect(themeBlock).not.toContain("--color-gray-50: #f9fafb;");
+    expect((themeBlock.match(/--color-gray-500:/g) ?? []).length).toBe(1);
+    expect(themeBlock).toContain("--color-gray-500: #222222;");
+    // Untouched shades still fall back to the v3 default.
+    expect(themeBlock).toContain("--color-gray-950: #030712;");
+  });
+});
+
+describe("generateAppCss — oklch fixer scope (gotcha #43)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "app-css-oklch-scope-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("does not rewrite a hex/oklch(var()) pair declared in the site's own original CSS", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "tailwind.css"),
+      `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --icon-color: #1a1a1a;
+}
+.icon {
+  fill: oklch(var(--icon-color));
+}
+`,
+      "utf-8",
+    );
+
+    const ctx = createContext(tmpDir);
+    const css = generateAppCss(ctx);
+
+    // The site's own declaration must survive untouched — the oklch fixer
+    // must not reach into content it doesn't own.
+    expect(css).toContain("--icon-color: #1a1a1a;");
+    expect(css).not.toMatch(/--icon-color:\s*[\d.]+\s+[\d.]+\s+[\d.]+;/);
+  });
+});
+
+describe("generateAppCss — @apply rewrites classes behind a modifier prefix", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "app-css-apply-variant-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("renames a variant-prefixed class inside @apply, not just bare tokens", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "tailwind.css"),
+      `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer components {
+  .btn-brand {
+    @apply md:flex-grow hover:ring rounded;
+  }
+}
+`,
+      "utf-8",
+    );
+
+    const ctx = createContext(tmpDir);
+    const css = generateAppCss(ctx);
+
+    expect(css).toContain("md:grow");
+    expect(css).toContain("hover:ring-3");
+    expect(css).not.toContain("md:flex-grow");
+    expect(css).not.toMatch(/hover:ring(?!-3)/);
+  });
+});