@decocms/blocks-cli 7.0.0

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

@@ -0,0 +1,193 @@
+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 { _truncateForTesting, compile } from "./phase-compile";
+import type { CompileRunResult } from "./phase-compile";
+import type { MigrationContext } from "./types";
+
+function makeCtx(sourceDir: string, dryRun = false): MigrationContext {
+	return {
+		sourceDir,
+		siteName: "test-site",
+		platform: "vtex",
+		vtexAccount: null,
+		gtmId: null,
+		importMap: {},
+		discoveredNpmDeps: {},
+		themeColors: {},
+		fontFamily: null,
+		files: [],
+		sectionMetas: [],
+		islandClassifications: [],
+		islandWrapperTargets: new Map(),
+		loaderInventory: [],
+		scaffoldedFiles: [],
+		transformedFiles: [],
+		deletedFiles: [],
+		movedFiles: [],
+		manualReviewItems: [],
+		frameworkFindings: [],
+		dryRun,
+		verbose: false,
+	};
+}
+
+function fakeRunner(
+	responses: Record<string, CompileRunResult>,
+): {
+	calls: string[];
+	runner: (cmd: string, cwd: string) => CompileRunResult;
+} {
+	const calls: string[] = [];
+	const runner = (cmd: string, _cwd: string): CompileRunResult => {
+		calls.push(cmd);
+		return responses[cmd] ?? { ok: true };
+	};
+	return { calls, runner };
+}
+
+describe("compile (phase 8)", () => {
+	let tmpDir: string;
+	let logSpy: ReturnType<typeof vi.spyOn>;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "compile-test-"));
+		logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+	});
+
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+		logSpy.mockRestore();
+	});
+
+	it("is a no-op in dry-run mode", () => {
+		const ctx = makeCtx(tmpDir, true);
+		const { runner, calls } = fakeRunner({});
+		const result = compile(ctx, { runner });
+		expect(result.skipped).toBe(true);
+		expect(result.typecheck.ran).toBe(false);
+		expect(result.shouldFail).toBe(false);
+		expect(calls).toEqual([]);
+	});
+
+	it("skips when node_modules/ is missing", () => {
+		const ctx = makeCtx(tmpDir);
+		const { runner, calls } = fakeRunner({});
+		const result = compile(ctx, { runner });
+		expect(result.skipped).toBe(true);
+		expect(result.typecheck.ran).toBe(false);
+		expect(calls).toEqual([]);
+	});
+
+	it("runs typecheck when node_modules/ exists and reports success", () => {
+		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.skipped).toBe(false);
+		expect(result.typecheck.ran).toBe(true);
+		expect(result.typecheck.passed).toBe(true);
+		expect(result.shouldFail).toBe(false);
+		expect(calls).toEqual(["npx tsc --noEmit"]);
+	});
+
+	it("captures tsc failure output and emits a warning by default", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		const ctx = makeCtx(tmpDir);
+		const tscOutput = "src/foo.ts(10,5): error TS2322: Type mismatch.";
+		const { runner } = fakeRunner({
+			"npx tsc --noEmit": { ok: false, output: tscOutput },
+		});
+		const result = compile(ctx, { runner });
+		expect(result.typecheck.passed).toBe(false);
+		expect(result.typecheck.output).toBe(tscOutput);
+		// In default (non-strict) mode, failure does not abort the migration.
+		expect(result.shouldFail).toBe(false);
+	});
+
+	it("promotes tsc failure to abort in --strict mode", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		const ctx = makeCtx(tmpDir);
+		const { runner } = fakeRunner({
+			"npx tsc --noEmit": { ok: false, output: "TS error" },
+		});
+		const result = compile(ctx, { runner, strict: true });
+		expect(result.typecheck.passed).toBe(false);
+		expect(result.shouldFail).toBe(true);
+	});
+
+	it("runs vite build only when --with-build is passed", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		const ctx = makeCtx(tmpDir);
+		const { runner, calls } = fakeRunner({
+			"npx tsc --noEmit": { ok: true },
+			"npx vite build": { ok: true },
+		});
+		const result = compile(ctx, { runner, withBuild: true });
+		expect(calls).toEqual(["npx tsc --noEmit", "npx vite build"]);
+		expect(result.build.ran).toBe(true);
+		expect(result.build.passed).toBe(true);
+	});
+
+	it("does not run vite build by default", () => {
+		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(calls).toEqual(["npx tsc --noEmit"]);
+		expect(result.build.ran).toBe(false);
+	});
+
+	it("aborts in strict mode when build fails even if typecheck passes", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		const ctx = makeCtx(tmpDir);
+		const { runner } = fakeRunner({
+			"npx tsc --noEmit": { ok: true },
+			"npx vite build": { ok: false, output: "Vite build error" },
+		});
+		const result = compile(ctx, {
+			runner,
+			withBuild: true,
+			strict: true,
+		});
+		expect(result.typecheck.passed).toBe(true);
+		expect(result.build.passed).toBe(false);
+		expect(result.shouldFail).toBe(true);
+	});
+
+	it("still runs build after a tsc failure (strict mode aborts at the end)", () => {
+		fs.mkdirSync(path.join(tmpDir, "node_modules"), { recursive: true });
+		const ctx = makeCtx(tmpDir);
+		const { runner, calls } = fakeRunner({
+			"npx tsc --noEmit": { ok: false, output: "TS error" },
+			"npx vite build": { ok: true },
+		});
+		const result = compile(ctx, { runner, withBuild: true });
+		expect(calls).toEqual(["npx tsc --noEmit", "npx vite build"]);
+		expect(result.typecheck.passed).toBe(false);
+		expect(result.build.passed).toBe(true);
+	});
+});
+
+describe("truncate helper", () => {
+	it("returns input unchanged when within line limit", () => {
+		const input = "line1\nline2\nline3";
+		expect(_truncateForTesting(input, 10)).toBe(input);
+	});
+
+	it("truncates output exceeding the line limit", () => {
+		const lines = Array.from({ length: 100 }, (_, i) => `line${i}`);
+		const out = _truncateForTesting(lines.join("\n"), 50);
+		const outLines = out.split("\n");
+		// 50 kept lines + 1 truncation marker
+		expect(outLines).toHaveLength(51);
+		expect(outLines[0]).toBe("line0");
+		expect(outLines[49]).toBe("line49");
+		expect(outLines[50]).toContain("50 more lines truncated");
+	});
+});

package/scripts/migrate/phase-compile.ts

@@ -0,0 +1,177 @@
+/**
+ * Phase 8 — Compile.
+ *
+ * After scaffolding, transforming, and bootstrapping the migrated site,
+ * actually run the TypeScript compiler (and optionally a full Vite build) to
+ * catch regressions that escaped the static `phase-verify` checks.
+ *
+ * This is the gate that would have caught past migration regressions like:
+ *   - #105 TS5097 (rewriter leaving `.ts` extensions in imports)
+ *   - the dead `src/lib/*` shims that broke `phase-cleanup`
+ *   - import-rewrite gaps where `from "apps/foo"` silently became `from ""`
+ *
+ * Behavior:
+ *   - Default: typecheck only (`tsc --noEmit`). Failures are surfaced as
+ *     warnings — the migration completes, but the user sees the diagnostics.
+ *   - `--strict`: failures abort the migration with a non-zero exit code so
+ *     CI can fail.
+ *   - `--with-build`: also runs `npx vite build` after typecheck. Slower
+ *     (~30-90s) but catches runtime-only issues like missing exports.
+ *
+ * No-ops in dry-run mode.
+ */
+
+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 type { MigrationContext } from "./types";
+import { logPhase } from "./types";
+
+export type CompileRunResult =
+	| { ok: true }
+	| { ok: false; output: string };
+
+export interface CompileOptions {
+	/** Promote typecheck/build failures from warnings to errors (exit code 2). */
+	strict?: boolean;
+	/** Also run `npx vite build` after typecheck. */
+	withBuild?: boolean;
+	/**
+	 * Internal: override the command runner. Tests inject a stub here; the
+	 * default uses `child_process.execSync`.
+	 */
+	runner?: (cmd: string, cwd: string) => CompileRunResult;
+}
+
+export interface CompileResult {
+	skipped: boolean;
+	typecheck: { ran: boolean; passed: boolean; output?: string };
+	build: { ran: boolean; passed: boolean; output?: string };
+	/** True iff compile decided the migration should fail (only in strict mode). */
+	shouldFail: boolean;
+}
+
+const MAX_OUTPUT_LINES = 50;
+
+function truncate(output: string, maxLines: number): string {
+	const lines = output.split("\n");
+	if (lines.length <= maxLines) return output;
+	return [
+		...lines.slice(0, maxLines),
+		gray(`  … (${lines.length - maxLines} more lines truncated)`),
+	].join("\n");
+}
+
+/** Default command runner — uses execSync. Overridable for tests. */
+function defaultRunner(cmd: string, cwd: string): CompileRunResult {
+	try {
+		execSync(cmd, { cwd, stdio: "pipe" });
+		return { ok: true };
+	} catch (e: unknown) {
+		const err = e as { stdout?: Buffer; stderr?: Buffer; message?: string };
+		const stdout = err.stdout?.toString() ?? "";
+		const stderr = err.stderr?.toString() ?? "";
+		const output = (stdout + stderr).trim() || err.message || "Unknown error";
+		return { ok: false, output };
+	}
+}
+
+/** Exported for testing. */
+export { truncate as _truncateForTesting };
+
+/**
+ * Run the post-bootstrap compile checks.
+ *
+ * Returns `{ shouldFail }` so the caller (migrate.ts) can decide whether to
+ * exit non-zero. We don't `process.exit()` ourselves so this stays unit-testable.
+ */
+export function compile(
+	ctx: MigrationContext,
+	opts: CompileOptions = {},
+): CompileResult {
+	logPhase("Compile (TypeScript + optional build)");
+
+	const result: CompileResult = {
+		skipped: false,
+		typecheck: { ran: false, passed: false },
+		build: { ran: false, passed: false },
+		shouldFail: false,
+	};
+
+	if (ctx.dryRun) {
+		console.log("  Skipping compile in dry-run mode\n");
+		result.skipped = true;
+		return result;
+	}
+
+	// Compile relies on `node_modules/`. If bootstrap was skipped or failed
+	// before the install step we have nothing to typecheck — bail with a
+	// clear message rather than exploding.
+	const nodeModules = path.join(ctx.sourceDir, "node_modules");
+	if (!fs.existsSync(nodeModules)) {
+		console.log(
+			`  ${yellow("⚠")} Skipping compile — node_modules/ missing (bootstrap likely failed)\n`,
+		);
+		result.skipped = true;
+		return result;
+	}
+
+	const runner = opts.runner ?? defaultRunner;
+
+	// Typecheck.
+	console.log("  Running: TypeScript typecheck (npx tsc --noEmit)...");
+	const tsc = runner("npx tsc --noEmit", ctx.sourceDir);
+	result.typecheck.ran = true;
+	result.typecheck.passed = tsc.ok;
+
+	if (tsc.ok) {
+		console.log(`  ${green("✓")} Typecheck passed`);
+	} else {
+		const output = truncate(tsc.output, MAX_OUTPUT_LINES);
+		result.typecheck.output = tsc.output;
+		const icon = opts.strict ? red("✗") : yellow("⚠");
+		console.log(`  ${icon} Typecheck failed:\n`);
+		console.log(output);
+		console.log("");
+	}
+
+	// Optional Vite build (heavier, opt-in).
+	if (opts.withBuild) {
+		console.log("  Running: Vite build (npx vite build)...");
+		const vite = runner("npx vite build", ctx.sourceDir);
+		result.build.ran = true;
+		result.build.passed = vite.ok;
+
+		if (vite.ok) {
+			console.log(`  ${green("✓")} Build passed`);
+		} else {
+			const output = truncate(vite.output, MAX_OUTPUT_LINES);
+			result.build.output = vite.output;
+			const icon = opts.strict ? red("✗") : yellow("⚠");
+			console.log(`  ${icon} Build failed:\n`);
+			console.log(output);
+			console.log("");
+		}
+	}
+
+	// Decide whether to fail the migration.
+	const anyFailed =
+		(result.typecheck.ran && !result.typecheck.passed) ||
+		(result.build.ran && !result.build.passed);
+
+	if (anyFailed && opts.strict) {
+		result.shouldFail = true;
+		console.log(
+			`  ${red("Compile failed in strict mode — migration aborted.")}\n`,
+		);
+	} else if (anyFailed) {
+		console.log(
+			`  ${yellow("Compile completed with errors.")} Re-run with ${gray("--strict")} in CI to fail the build.\n`,
+		);
+	} else {
+		console.log(`  ${green("Compile passed.")}\n`);
+	}
+
+	return result;
+}

package/scripts/migrate/phase-report.ts

@@ -0,0 +1,243 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { MigrationContext } from "./types";
+import { logPhase } from "./types";
+
+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/start",
+  "Route files (__root.tsx, index.tsx, $.tsx, deco/*) are near-identical across sites — should be generated by framework",
+  "server.ts, worker-entry.ts, router.tsx are pure boilerplate — should be a single createSite() call",
+  "setup.ts section registration via import.meta.glob is 100% boilerplate — framework should handle this",
+  "runtime.ts invoke proxy is identical across sites — already in @decocms/start but sites still have local copies",
+  "apps/site.ts is mostly empty after migration — platform config should be in a config file, not code",
+];
+
+export function report(ctx: MigrationContext): void {
+  logPhase("Report");
+
+  ctx.frameworkFindings = FRAMEWORK_FINDINGS;
+
+  const lines: string[] = [];
+
+  lines.push("# Migration Report");
+  lines.push("");
+  lines.push(`**Site:** ${ctx.siteName}`);
+  lines.push(`**Platform:** ${ctx.platform}`);
+  lines.push(`**GTM ID:** ${ctx.gtmId || "none"}`);
+  lines.push(`**Date:** ${new Date().toISOString().split("T")[0]}`);
+  lines.push(`**Mode:** ${ctx.dryRun ? "DRY RUN" : "EXECUTED"}`);
+  lines.push("");
+
+  // Summary
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`| Metric | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Files analyzed | ${ctx.files.length} |`);
+  lines.push(`| Files scaffolded | ${ctx.scaffoldedFiles.length} |`);
+  lines.push(`| Files transformed | ${ctx.transformedFiles.length} |`);
+  lines.push(`| Files deleted | ${ctx.deletedFiles.length} |`);
+  lines.push(`| Files moved | ${ctx.movedFiles.length} |`);
+  lines.push(
+    `| Manual review items | ${ctx.manualReviewItems.length} |`,
+  );
+  lines.push("");
+
+  // Scaffolded files
+  lines.push("## Scaffolded Files (new)");
+  lines.push("");
+  for (const f of ctx.scaffoldedFiles) {
+    lines.push(`- \`${f}\``);
+  }
+  lines.push("");
+
+  // Transformed files
+  lines.push("## Transformed Files");
+  lines.push("");
+  for (const f of ctx.transformedFiles) {
+    lines.push(`- \`${f}\``);
+  }
+  lines.push("");
+
+  // Deleted files
+  lines.push("## Deleted Files");
+  lines.push("");
+  for (const f of ctx.deletedFiles) {
+    lines.push(`- \`${f}\``);
+  }
+  lines.push("");
+
+  // Moved files
+  if (ctx.movedFiles.length > 0) {
+    lines.push("## Moved Files");
+    lines.push("");
+    for (const { from, to } of ctx.movedFiles) {
+      lines.push(`- \`${from}\` → \`${to}\``);
+    }
+    lines.push("");
+  }
+
+  // Manual review
+  if (ctx.manualReviewItems.length > 0) {
+    lines.push("## Manual Review Required");
+    lines.push("");
+    for (const item of ctx.manualReviewItems) {
+      const icon = item.severity === "error"
+        ? "🔴"
+        : item.severity === "warning"
+        ? "🟡"
+        : "🔵";
+      lines.push(`${icon} **\`${item.file}\`**: ${item.reason}`);
+    }
+    lines.push("");
+  }
+
+  // Analyzer summaries
+  if (ctx.sectionMetas.length > 0) {
+    lines.push("## Section Analysis");
+    lines.push("");
+    const withLoader = ctx.sectionMetas.filter((m) => m.hasLoader).length;
+    const layouts = ctx.sectionMetas.filter((m) => m.isHeader || m.isFooter || m.isTheme).length;
+    const listings = ctx.sectionMetas.filter((m) => m.isListing).length;
+    lines.push(`- **${ctx.sectionMetas.length}** sections analyzed`);
+    lines.push(`- **${withLoader}** have loaders (extracted to \`setup/section-loaders.ts\`)`);
+    lines.push(`- **${layouts}** are layout sections (eager + sync + layout)`);
+    lines.push(`- **${listings}** are listing sections (cache = "listing")`);
+    lines.push("");
+  }
+
+  if (ctx.islandClassifications.length > 0) {
+    const wrappers = ctx.islandClassifications.filter((c) => c.type === "wrapper").length;
+    const standalone = ctx.islandClassifications.filter((c) => c.type === "standalone").length;
+    lines.push("## Island Elimination");
+    lines.push("");
+    lines.push(`- **${ctx.islandClassifications.length}** islands classified`);
+    lines.push(`- **${wrappers}** wrappers (deleted, imports repointed)`);
+    lines.push(`- **${standalone}** standalone (moved to \`src/components/\`)`);
+    lines.push("");
+  }
+
+  if (ctx.loaderInventory.length > 0) {
+    const custom = ctx.loaderInventory.filter((l) => l.isCustom).length;
+    const mapped = ctx.loaderInventory.filter((l) => l.appsEquivalent).length;
+    lines.push("## Loader Inventory");
+    lines.push("");
+    lines.push(`- **${ctx.loaderInventory.length}** loaders inventoried`);
+    lines.push(`- **${mapped}** mapped to \`@decocms/apps\` equivalents`);
+    lines.push(`- **${custom}** custom (included in \`setup/commerce-loaders.ts\`)`);
+    lines.push("");
+  }
+
+  // Always-present manual review items
+  lines.push("## Always Check (site-specific)");
+  lines.push("");
+  lines.push("- [ ] `src/setup/commerce-loaders.ts` — verify each loader mapping is correct");
+  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("- [ ] Run `npm run generate:blocks` and `npm run generate:schema` after migration");
+  lines.push("");
+
+  // Known Issues
+  lines.push("## Known Issues (Tailwind v3 → v4 + React)");
+  lines.push("");
+  lines.push("### Negative z-index on background images");
+  lines.push("");
+  lines.push("The migration script automatically converts `-z-{n}` to `z-0` on `<img>` and `<Image>` elements.");
+  lines.push("However, if you have **non-image elements** with negative z-index (e.g. `-z-10` on a `<div>` used as a background layer), they may become invisible.");
+  lines.push("");
+  lines.push("**Why it breaks:** In TanStack Start/React, section wrappers (`<section>`) or parent elements can create");
+  lines.push("CSS stacking contexts (via `animation`, `transform`, `will-change`, `filter`, `isolation`, etc.).");
+  lines.push("A child with negative z-index gets trapped inside that stacking context and renders behind the parent's background — making it invisible.");
+  lines.push("");
+  lines.push("**How to fix:**");
+  lines.push("1. Replace `-z-{n}` with `z-0` on the background element");
+  lines.push("2. Content siblings render on top naturally via DOM order (they come after in the HTML)");
+  lines.push("3. If needed, add `relative z-10` to content siblings to ensure they stay above");
+  lines.push("");
+  lines.push("**How to detect:** Search for remaining negative z-index: `grep -rn '\\-z-' src/ --include='*.tsx'`");
+  lines.push("");
+  lines.push("### Opacity utility classes");
+  lines.push("");
+  lines.push("Tailwind v4 removed `bg-opacity-{n}`, `text-opacity-{n}`, etc. The script converts them to");
+  lines.push("the modifier syntax (e.g. `bg-black bg-opacity-20` → `bg-black/20`). If a color and its opacity");
+  lines.push("are not in the same className string (e.g. set via different conditional branches), the script");
+  lines.push("flags them for manual review.");
+  lines.push("");
+  lines.push("**How to detect:** `grep -rn 'opacity-' src/ --include='*.tsx'`");
+  lines.push("");
+
+  // Framework findings
+  lines.push("## Framework Findings");
+  lines.push("");
+  lines.push(
+    "> These are patterns found during migration that should eventually be handled by `@decocms/start` instead of being duplicated in every site.",
+  );
+  lines.push("");
+  for (const finding of ctx.frameworkFindings) {
+    lines.push(`- ${finding}`);
+  }
+  lines.push("");
+
+  // Next steps
+  lines.push("## Next Steps");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("# 1. Install dependencies (bun is the canonical PM)");
+  lines.push("bun install");
+  lines.push("");
+  lines.push("# 2. Generate CMS blocks and schema");
+  lines.push("bun run generate:blocks");
+  lines.push("bun run generate:schema");
+  lines.push("");
+  lines.push("# 3. Generate routes");
+  lines.push("bunx tsr generate");
+  lines.push("");
+  lines.push("# 4. Type check");
+  lines.push("bunx tsc --noEmit");
+  lines.push("");
+  lines.push("# 5. Find unused code");
+  lines.push("bun run knip");
+  lines.push("");
+  lines.push("# 6. Run dev server");
+  lines.push("npm run dev");
+  lines.push("");
+  lines.push("# 7. (Once wrangler.jsonc is wired) enable CF-native observability");
+  lines.push("#    Adds the canonical `observability` block to wrangler.jsonc so the");
+  lines.push("#    Cloudflare runtime captures console.* logs and auto-instrumented");
+  lines.push("#    traces directly into the CF dashboard (Workers & Pages -> <site>");
+  lines.push("#    -> Observability). No external destination required — the CF");
+  lines.push("#    dashboard is the destination.");
+  lines.push("#");
+  lines.push("#    Forwarding to a future ClickHouse-backed OTel collector is on the");
+  lines.push("#    roadmap (placeholder lives at");
+  lines.push("#    @decocms/start/sdk/otelAdapters/clickhouseCollector); when it");
+  lines.push("#    ships, the codemod gains a `--destination-logs` /");
+  lines.push("#    `--destination-traces` flag to point at it.");
+  lines.push("npx -p @decocms/start deco-cf-observability         # dry-run");
+  lines.push("npx -p @decocms/start deco-cf-observability --write # apply");
+  lines.push("```");
+  lines.push("");
+
+  const content = lines.join("\n");
+
+  if (ctx.dryRun) {
+    console.log("\n" + content);
+  } else {
+    const reportPath = path.join(ctx.sourceDir, "MIGRATION_REPORT.md");
+    fs.writeFileSync(reportPath, content, "utf-8");
+    console.log(`  Report written to MIGRATION_REPORT.md`);
+  }
+
+  // Print summary to console
+  console.log(`\n  === Migration ${ctx.dryRun ? "(DRY RUN)" : "COMPLETE"} ===`);
+  console.log(`  Scaffolded: ${ctx.scaffoldedFiles.length}`);
+  console.log(`  Transformed: ${ctx.transformedFiles.length}`);
+  console.log(`  Deleted: ${ctx.deletedFiles.length}`);
+  console.log(`  Moved: ${ctx.movedFiles.length}`);
+  console.log(`  Manual review: ${ctx.manualReviewItems.length}`);
+}