@decocms/start 2.7.0 → 2.8.0

package/.agents/skills/deco-migrate-script/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deco-migrate-script
-description: Automated migration script that converts Deco storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Runs 7 phases (analyze, scaffold, transform, cleanup, report, verify, bootstrap). Use when running the migration script, debugging its output, extending it with new transforms, or understanding what it does. Located at scripts/migrate.ts in @decocms/start.
+description: Automated migration script that converts Deco storefronts from Fresh/Preact/Deno to TanStack Start/React/Cloudflare Workers. Runs 8 phases (analyze, scaffold, transform, cleanup, report, verify, bootstrap, compile). Use when running the migration script, debugging its output, extending it with new transforms, or understanding what it does. Located at scripts/migrate.ts in @decocms/start.
 globs:
   - "scripts/migrate.ts"
   - "scripts/migrate/**/*"
@@ -27,8 +27,13 @@ npx tsx node_modules/@decocms/start/scripts/migrate.ts --source /path/to/old-sit
 | `--source <dir>` | Source site directory (default: `.`) |
 | `--dry-run` | Preview changes without writing files |
 | `--verbose` | Show detailed per-file output |
+| `--strict` | Promote post-bootstrap typecheck/build failures from warnings to errors (exit 2) |
+| `--with-build` | After typecheck, also run `npx vite build` for full runtime validation (slower) |
+| `--no-compile` | Skip the post-bootstrap compile phase entirely |
 | `--help` | Show help |
 
+**CI usage:** pair `--strict` with `--with-build` to catch both type and runtime regressions before merge.
+
 ## Architecture
 
 ```
@@ -42,6 +47,7 @@ scripts/migrate/
 ├── phase-cleanup.ts            ← Phase 4: delete old artifacts
 ├── phase-report.ts             ← Phase 5: generate MIGRATION_REPORT.md
 ├── phase-verify.ts             ← Phase 6: smoke tests
+├── phase-compile.ts            ← Phase 8: post-bootstrap tsc/vite-build
 ├── transforms/                 ← Transform modules (applied in order)
 │   ├── imports.ts              ← 70+ import rewriting rules
 │   ├── jsx.ts                  ← JSX attribute fixes
@@ -264,6 +270,26 @@ Runs automatically after all phases (skipped in `--dry-run`):
 2. `npx tsx node_modules/@decocms/start/scripts/generate-blocks.ts`
 3. `npx tsr generate`
 
+### Phase 8: Compile
+
+Runs automatically after bootstrap (skipped in `--dry-run` or with `--no-compile`):
+
+1. `npx tsc --noEmit` — surfaces any typecheck regression introduced by the
+   transform pipeline. Output is captured and printed (truncated to ~50 lines)
+   so users can see the actual TypeScript diagnostics.
+2. `npx vite build` — only when `--with-build` is passed. Catches
+   runtime-only issues that escape typecheck (missing exports, broken
+   barrel files, server/client boundary violations).
+
+Failures are warnings by default — the migration completes and tells the
+user to inspect the diagnostics. With `--strict`, failures abort with
+exit code `2` so CI can fail the pipeline.
+
+Skipped automatically when `node_modules/` is missing (e.g. bootstrap
+failed before install). This is the gate that catches regressions like
+`#105 TS5097` (rewriter leaving `.ts` extensions in imports) or dead
+shim references that escape the static `phase-verify` checks.
+
 ## Key Design Decisions
 
 ### MigrationContext (types.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

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.ts

@@ -32,6 +32,7 @@ import { transform } from "./migrate/phase-transform";
 import { cleanup } from "./migrate/phase-cleanup";
 import { report } from "./migrate/phase-report";
 import { verify } from "./migrate/phase-verify";
+import { compile } from "./migrate/phase-compile";
 import { banner, stat, red, green, yellow } from "./migrate/colors";
 
 function parseArgs(args: string[]): {
@@ -39,11 +40,17 @@ function parseArgs(args: string[]): {
   dryRun: boolean;
   verbose: boolean;
   help: boolean;
+  strict: boolean;
+  withBuild: boolean;
+  noCompile: boolean;
 } {
   let source = ".";
   let dryRun = false;
   let verbose = false;
   let help = false;
+  let strict = false;
+  let withBuild = false;
+  let noCompile = false;
 
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
@@ -56,6 +63,15 @@ function parseArgs(args: string[]): {
       case "--verbose":
         verbose = true;
         break;
+      case "--strict":
+        strict = true;
+        break;
+      case "--with-build":
+        withBuild = true;
+        break;
+      case "--no-compile":
+        noCompile = true;
+        break;
       case "--help":
       case "-h":
         help = true;
@@ -63,7 +79,7 @@ function parseArgs(args: string[]): {
     }
   }
 
-  return { source, dryRun, verbose, help };
+  return { source, dryRun, verbose, help, strict, withBuild, noCompile };
 }
 
 function showHelp() {
@@ -77,11 +93,15 @@ function showHelp() {
     --source <dir>    Source directory (default: .)
     --dry-run         Preview changes without writing files
     --verbose         Show detailed output for every file
+    --strict          Fail (exit 2) when typecheck/build report errors
+    --with-build      Also run \`vite build\` after typecheck (slower)
+    --no-compile      Skip the post-bootstrap compile phase entirely
     --help, -h        Show this help message
 
   Examples:
     npx -p @decocms/start deco-migrate --dry-run --verbose
     npx -p @decocms/start deco-migrate --source ./my-site
+    npx -p @decocms/start deco-migrate --strict --with-build
     npx -p @decocms/start deco-migrate
   `);
 }
@@ -132,6 +152,19 @@ async function main() {
     if (!ctx.dryRun) {
       bootstrap(ctx);
     }
+
+    // Phase 8: Compile (typecheck + optional build)
+    // Skipped in dry-run, when --no-compile is passed, or when bootstrap
+    // didn't install dependencies (handled inside `compile`).
+    if (!opts.noCompile) {
+      const compileResult = compile(ctx, {
+        strict: opts.strict,
+        withBuild: opts.withBuild,
+      });
+      if (compileResult.shouldFail) {
+        process.exit(2);
+      }
+    }
   } catch (error) {
     console.error(`\n  ${red("Migration failed:")}`, error);
     process.exit(1);