@decocms/blocks-cli 7.21.0 → 7.22.0

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-legacy-specifiers.test.ts

@@ -0,0 +1,134 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { checks } from "./phase-verify";
+import type { MigrationContext } from "./types";
+
+/**
+ * #367: blocks-cli must never leave the frozen pre-7.x-split package
+ * specifiers (@decocms/start@6.30.0, @decocms/apps@5.4.0) in a migrated
+ * site's src/ — including via a transform hand-off marker (jsx.ts emits
+ * `@decocms/start/hooks` as a same-run marker that phase-cleanup.ts is
+ * supposed to resolve to `@decocms/blocks/hooks`) that leaks past cleanup
+ * if the pipeline order ever changes.
+ */
+
+function makeCtx(sourceDir: string): MigrationContext {
+  return {
+    sourceDir,
+    siteName: "test-site",
+    platform: "custom",
+    vtexAccount: null,
+    gtmId: null,
+    importMap: {},
+    discoveredNpmDeps: {},
+    themeColors: {},
+    fontFamily: null,
+    files: [],
+    sectionMetas: [],
+    islandClassifications: [],
+    islandWrapperTargets: new Map(),
+    loaderInventory: [],
+    scaffoldedFiles: [],
+    transformedFiles: [],
+    deletedFiles: [],
+    movedFiles: [],
+    manualReviewItems: [],
+    frameworkFindings: [],
+    dryRun: false,
+    verbose: false,
+  };
+}
+
+const legacySpecifierCheck = checks.find(
+  (c) => c.name === "No frozen pre-split package specifiers in src/ (@decocms/start, @decocms/apps/*)",
+);
+if (!legacySpecifierCheck) {
+  throw new Error("verify check not found — name changed?");
+}
+
+function runCheck(ctx: MigrationContext): { ok: boolean; output: string } {
+  const lines: string[] = [];
+  const spy = vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+    lines.push(args.map((a) => String(a)).join(" "));
+  });
+  try {
+    const ok = legacySpecifierCheck!.fn(ctx);
+    return { ok, output: lines.join("\n") };
+  } finally {
+    spy.mockRestore();
+  }
+}
+
+describe("verify check: 'No frozen pre-split package specifiers in src/' (#367)", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "verify-legacy-specifiers-"));
+    fs.mkdirSync(path.join(tmp, "src", "hooks"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("passes when src/ only imports from the current split packages", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "useUser.ts"),
+      `import { SectionRenderer } from "@decocms/blocks/hooks";\n` +
+        `import { invoke } from "@decocms/blocks/sdk/invoke";\n` +
+        `export const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+    expect(output).toBe("");
+  });
+
+  it("fails when a `@decocms/start/hooks` hand-off marker leaked past cleanup", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "useUser.ts"),
+      `import { SectionRenderer } from "@decocms/start/hooks";\nexport const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+    expect(output).toContain("@decocms/start");
+  });
+
+  it("fails on a bare `@decocms/start` import (no subpath)", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "setup.ts"),
+      `import "@decocms/start";\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+  });
+
+  it("fails on a `@decocms/apps/vtex/...` monolith subpath import", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "old.ts"),
+      `import { getUser } from "@decocms/apps/vtex/loaders/user";\nexport const x = 1;\n`,
+    );
+    const { ok, output } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(false);
+    expect(output).toContain("@decocms/apps/");
+  });
+
+  it("does not flag the current @decocms/apps-vtex split package", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "useUser.ts"),
+      `import { getUser } from "@decocms/apps-vtex/loaders/user";\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+  });
+
+  it("ignores commented-out references", () => {
+    fs.writeFileSync(
+      path.join(tmp, "src", "hooks", "Docs.ts"),
+      `// import { x } from "@decocms/start/hooks"\nexport const x = 1;\n`,
+    );
+    const { ok } = runCheck(makeCtx(tmp));
+    expect(ok).toBe(true);
+  });
+});

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/phase-verify.ts

@@ -410,6 +410,30 @@ export const checks: Check[] = [
       return true;
     },
   },
+  {
+    // Fleet-wide regression guard, complementing the scaffolder-only check
+    // in templates/no-legacy-packages.test.ts (#367): the frozen
+    // pre-7.x-split packages (@decocms/start@6.30.0, @decocms/apps@5.4.0)
+    // must never appear in a migrated site's src/, even via a transform
+    // hand-off marker that leaked past cleanup (see jsx.ts's
+    // `@decocms/start/hooks` same-run hand-off to phase-cleanup.ts).
+    name: "No frozen pre-split package specifiers in src/ (@decocms/start, @decocms/apps/*)",
+    severity: "error",
+    fn: (ctx) => {
+      const srcDir = path.join(ctx.sourceDir, "src");
+      if (!fs.existsSync(srcDir)) return true;
+      const bad = [
+        ...findFilesWithPattern(srcDir, /(?:from|import)\s+["']@decocms\/start(?:\/|["'])/),
+        ...findFilesWithPattern(srcDir, /from\s+["']@decocms\/apps\//),
+      ];
+      const unique = [...new Set(bad)];
+      if (unique.length > 0) {
+        console.log(`    Still references frozen @decocms/start or @decocms/apps/* specifiers: ${unique.join(", ")}`);
+        return false;
+      }
+      return true;
+    },
+  },
   {
     name: "Setup infrastructure is complete",
     severity: "error",