@mandujs/core 0.54.31 → 0.55.0-beta.1

package/src/bundler/css.ts

@@ -15,41 +15,62 @@
 import { spawn } from "bun";
 import path from "path";
 import fs from "fs/promises";
-import { watch as fsWatch, type FSWatcher } from "fs";
+import { existsSync, watch as fsWatch, type FSWatcher } from "fs";
 import { withPerf } from "../perf";
 
-/**
- * Tailwind CLI 실행 명령어를 결정한다.
- * Windows에서 Bun.spawn은 PATH 기반 명령어 해석이 불안정하므로 (#152)
- * `bun run mandu` 환경에서는 process.execPath (bun 절대 경로)를 사용한다.
- * Standalone Mandu binary에서는 process.execPath가 mandu.exe를 가리키므로
- * `mandu x @tailwindcss/cli`로 오해석된다. 이 경우 PATH에서 Bun을 찾는다.
- */
-function isBunExecutable(executablePath: string | undefined): boolean {
-  if (!executablePath) return false;
-  const base = path.basename(executablePath).toLowerCase();
-  return base === "bun" || base === "bun.exe";
-}
-
-type WhichExecutable = (command: string) => string | null | undefined;
-
-function resolveBunExecutable(
-  execPath = process.execPath,
-  which: WhichExecutable = (command) => Bun.which(command),
-): string {
-  if (isBunExecutable(execPath)) return execPath;
-  const fromPath = which("bun");
-  if (fromPath) return fromPath;
-  return process.platform === "win32" ? "bun.exe" : "bun";
-}
-
-function getTailwindCommand(
-  args: string[],
-  execPath = process.execPath,
-  which?: WhichExecutable,
-): string[] {
-  return [resolveBunExecutable(execPath, which), "x", ...args];
-}
+/**
+ * Tailwind CLI 실행 명령어를 결정한다. 프로젝트에 설치된 CLI 엔트리가
+ * 있으면 직접 실행해 `bun x`의 네트워크 조회와 전역 캐시 잠금을 피한다.
+ * 로컬 엔트리가 없을 때만 `bun x`로 fallback한다.
+ * Windows에서 Bun.spawn은 PATH 기반 명령어 해석이 불안정하므로 (#152)
+ * `bun run mandu` 환경에서는 process.execPath (bun 절대 경로)를 사용한다.
+ * Standalone Mandu binary에서는 process.execPath가 mandu.exe를 가리키므로
+ * `mandu x @tailwindcss/cli`로 오해석된다. 이 경우 PATH에서 Bun을 찾는다.
+ */
+function isBunExecutable(executablePath: string | undefined): boolean {
+  if (!executablePath) return false;
+  // `path.basename()` only understands the current host separator. Tests,
+  // wrappers, and cross-compiled binaries can still hand us a Windows path on
+  // POSIX (or vice versa), so normalize both separators before inspecting it.
+  const base = path.posix.basename(executablePath.replace(/\\/g, "/")).toLowerCase();
+  return base === "bun" || base === "bun.exe";
+}
+
+type WhichExecutable = (command: string) => string | null | undefined;
+
+function resolveBunExecutable(
+  execPath = process.execPath,
+  which: WhichExecutable = (command) => Bun.which(command),
+): string {
+  if (isBunExecutable(execPath)) return execPath;
+  const fromPath = which("bun");
+  if (fromPath) return fromPath;
+  return process.platform === "win32" ? "bun.exe" : "bun";
+}
+
+function getTailwindCommand(
+  args: string[],
+  execPath = process.execPath,
+  which?: WhichExecutable,
+  rootDir?: string,
+  fileExists: (candidate: string) => boolean = existsSync,
+): string[] {
+  const bunExecutable = resolveBunExecutable(execPath, which);
+  if (rootDir && args[0] === "@tailwindcss/cli") {
+    const localEntry = path.join(
+      rootDir,
+      "node_modules",
+      "@tailwindcss",
+      "cli",
+      "dist",
+      "index.mjs",
+    );
+    if (fileExists(localEntry)) {
+      return [bunExecutable, localEntry, ...args.slice(1)];
+    }
+  }
+  return [bunExecutable, "x", ...args];
+}
 
 // ========== Types ==========
 
@@ -144,7 +165,7 @@ async function runCSSBuild(
   if (minify) args.push("--minify");
 
   try {
-    const proc = spawn(getTailwindCommand(args), {
+    const proc = spawn(getTailwindCommand(args, process.execPath, undefined, rootDir), {
       cwd: rootDir,
       stdout: "pipe",
       stderr: "pipe",
@@ -344,13 +365,13 @@ export function getCSSServerPath(): string {
 /**
  * CSS 링크 태그 생성
  */
-export function generateCSSLinkTag(isDev: boolean = false): string {
-  const cacheBust = isDev ? `?t=${Date.now()}` : "";
-  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
-}
-
-export const __private = {
-  getTailwindCommand,
-  isBunExecutable,
-  resolveBunExecutable,
-};
+export function generateCSSLinkTag(isDev: boolean = false): string {
+  const cacheBust = isDev ? `?t=${Date.now()}` : "";
+  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
+}
+
+export const __private = {
+  getTailwindCommand,
+  isBunExecutable,
+  resolveBunExecutable,
+};

package/src/bundler/dev.ts

@@ -6,7 +6,7 @@ import type * as __ManduContentCollectionTypes0 from "../content/collection";
 
 import type { RoutesManifest } from "../spec/schema";
 import { buildClientBundles } from "./build";
-import type { BundleResult } from "./types";
+import type { BundleManifest, BundleResult } from "./types";
 import { PORTS, TIMEOUTS } from "../constants";
 import { mark, measure, withPerf } from "../perf";
 import { HMR_PERF } from "../perf/hmr-markers";
@@ -21,13 +21,13 @@ import {
   scanFileImports,
   DEFAULT_MAX_CLOSURE_DEPTH,
 } from "./reverse-import-graph";
-import path from "path";
-import fs from "fs";
-import { LRUCache } from "../utils/lru-cache";
-import { registerCacheSize, unregisterCacheSize } from "../observability/metrics";
-export { generateFastRefreshPreamble } from "./fast-refresh-preamble";
-
-/**
+import path from "path";
+import fs from "fs";
+import { LRUCache } from "../utils/lru-cache";
+import { registerCacheSize, unregisterCacheSize } from "../observability/metrics";
+export { generateFastRefreshPreamble } from "./fast-refresh-preamble";
+
+/**
  * #184: 공통 디렉토리 변경 시 사용하는 sentinel.
  * `onSSRChange`에 특정 파일 경로 대신 이 상수를 전달하면 "전체 SSR 레지스트리 invalidate" 의미.
  */
@@ -137,12 +137,21 @@ export interface RebuildResult {
 }
 
 export interface DevBundler {
-  /** 초기 빌드 결과 */
-  initialBuild: BundleResult;
-  /** Reverse import graph initial seed completion for deterministic tests. */
-  reverseGraphReady: Promise<void>;
-  /** 파일 감시 중지 */
-  close: () => void;
+  /** 초기 빌드 결과 */
+  initialBuild: BundleResult;
+  /** Reverse import graph initial seed completion for deterministic tests. */
+  reverseGraphReady: Promise<void>;
+  /** 파일 감시 중지 */
+  close: () => void;
+}
+
+function replaceBundleManifest(
+  target: BundleManifest,
+  source: BundleManifest,
+): void {
+  const mutable = target as unknown as Record<string, unknown>;
+  for (const key of Object.keys(mutable)) delete mutable[key];
+  Object.assign(mutable, source);
 }
 
 /**
@@ -420,11 +429,16 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     reactCompiler,
   });
 
-  if (initialBuild.success) {
-    console.log(`✅ Built ${initialBuild.stats.bundleCount} islands`);
-  } else {
-    console.error("⚠️  Initial build had errors:", initialBuild.errors);
-  }
+  if (initialBuild.success) {
+    console.log(`✅ Built ${initialBuild.stats.bundleCount} islands`);
+  } else {
+    console.error("⚠️  Initial build had errors:", initialBuild.errors);
+    onError?.(
+      new Error(
+        `Initial client bundle build failed:\n${initialBuild.errors.join("\n")}`,
+      ),
+    );
+  }
 
   // clientModule 경로에서 routeId 매핑 생성
   const clientModuleToRoute = new Map<string, string>();
@@ -650,8 +664,8 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   // surface typed-only stubs that have no source yet); misses simply
   // keep the legacy "silent drop" behavior so no project is made
   // worse by turning this on.
-  const reverseGraph = new ReverseImportGraph();
-  let reverseGraphSeedPromise: Promise<void> | null = null;
+  const reverseGraph = new ReverseImportGraph();
+  let reverseGraphSeedPromise: Promise<void> | null = null;
 
   /**
    * Re-scan a single file's imports and update its row in the
@@ -1243,15 +1257,15 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
    * stay silent. Dispatch is idempotent — each root is touched at
    * most once per change via the `dispatched` set.
    */
-  const dispatchByTransitiveImporters = async (
-    changedFile: string,
-  ): Promise<number> => {
-    const absChanged = path.resolve(rootDir, changedFile);
-    if (reverseGraphSeedPromise) {
-      await reverseGraphSeedPromise;
-    }
-
-    // Refresh the changed file's OWN imports first. A leaf edit can
+  const dispatchByTransitiveImporters = async (
+    changedFile: string,
+  ): Promise<number> => {
+    const absChanged = path.resolve(rootDir, changedFile);
+    if (reverseGraphSeedPromise) {
+      await reverseGraphSeedPromise;
+    }
+
+    // Refresh the changed file's OWN imports first. A leaf edit can
     // legitimately add or remove imports (e.g. switching a barrel
     // from `./en` to `./ko`); the reverse graph must track that so
     // the NEXT unknown-file change uses the correct set.
@@ -1338,8 +1352,9 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
           reactCompiler,
         });
         const buildTime = performance.now() - startTime;
-        if (result.success) {
-          console.log(
+        if (result.success) {
+          replaceBundleManifest(initialBuild.manifest, result.manifest);
+          console.log(
             `✅ Rebuilt ${targetIds.length} island(s) in ${buildTime.toFixed(0)}ms`,
           );
           for (const targetId of targetIds) {
@@ -1399,8 +1414,9 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
 
         const buildTime = performance.now() - startTime;
 
-        if (result.success) {
-          // #184: common dir 변경은 SSR 모듈 캐시 invalidation이 필요 — wildcard 시그널
+        if (result.success) {
+          replaceBundleManifest(initialBuild.manifest, result.manifest);
+          // #184: common dir 변경은 SSR 모듈 캐시 invalidation이 필요 — wildcard 시그널
           // 빌드 성공한 경우에만 SSR 레지스트리를 clear (실패 시 마지막 good state 유지)
           // 주의: Bun의 transitive ESM 캐시는 프로세스 레벨이라 이 시그널만으로는
           //      `src/shared/**`을 transitive하게 import하는 SSR 모듈까지 완전히 갱신되지 않음.
@@ -1525,8 +1541,9 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
 
       const buildTime = performance.now() - startTime;
 
-      if (result.success) {
-        console.log(`✅ Rebuilt in ${buildTime.toFixed(0)}ms`);
+      if (result.success) {
+        replaceBundleManifest(initialBuild.manifest, result.manifest);
+        console.log(`✅ Rebuilt in ${buildTime.toFixed(0)}ms`);
         onRebuild?.({
           routeId,
           success: true,
@@ -1663,17 +1680,17 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
   // and the first user edit can't race the seed (first event goes
   // through the 100 ms debounce, by which point the scan has finished
   // for any realistic project size).
-  reverseGraphSeedPromise = seedReverseGraph().catch((err) => {
-    console.warn(
-      "[Mandu HMR] reverse import-graph seed skipped:",
-      err instanceof Error ? err.message : String(err),
-    );
-  });
-
-  return {
-    initialBuild,
-    reverseGraphReady: reverseGraphSeedPromise,
-    close: () => {
+  reverseGraphSeedPromise = seedReverseGraph().catch((err) => {
+    console.warn(
+      "[Mandu HMR] reverse import-graph seed skipped:",
+      err instanceof Error ? err.message : String(err),
+    );
+  });
+
+  return {
+    initialBuild,
+    reverseGraphReady: reverseGraphSeedPromise,
+    close: () => {
       // B6: clear all per-file timers to release event-loop refs.
       // Phase 17 — `LRUCache.clear()` fires the registered `onEvict`
       // (`clearTimeout(timer)`) for every entry before dropping them,
@@ -1738,9 +1755,12 @@ export interface HMRMessage {
   data?: {
     routeId?: string;
     layoutPath?: string;
-    cssPath?: string;
-    message?: string;
-    timestamp?: number;
+    cssPath?: string;
+    message?: string;
+    name?: string;
+    stack?: string;
+    kind?: "build" | "guard" | "css" | "prebuild";
+    timestamp?: number;
     file?: string;
     violations?: Array<{ line: number; message: string }>;
     changeType?: "add" | "change" | "delete";
@@ -1820,8 +1840,16 @@ export function createHMRServer(
   //
   // Monotonic counter; resets to 0 on server boot (restart is a full
   // reload anyway so clients can't meaningfully resume across it).
-  let lastRebuildId = 0;
-  const replayBuffer: HMRReplayEnvelope[] = [];
+  let lastRebuildId = 0;
+  const replayBuffer: HMRReplayEnvelope[] = [];
+  let latestBuildError: HMRMessage | null = null;
+
+  const sendConnected = (ws: { send: (data: string) => void }): void => {
+    ws.send(
+      JSON.stringify({ type: "connected", data: { timestamp: Date.now(), id: lastRebuildId } }),
+    );
+    if (latestBuildError) ws.send(JSON.stringify(latestBuildError));
+  };
 
   /** Drop envelopes older than `REPLAY_MAX_AGE_MS`. Called opportunistically. */
   const pruneOldReplays = (): void => {
@@ -1887,18 +1915,14 @@ export function createHMRServer(
     ws: { send: (data: string) => void },
     since: number | null,
   ): void => {
-    if (since === null) {
-      ws.send(
-        JSON.stringify({ type: "connected", data: { timestamp: Date.now(), id: lastRebuildId } }),
-      );
-      return;
-    }
+    if (since === null) {
+      sendConnected(ws);
+      return;
+    }
     // Already caught up — nothing to replay but still greet.
-    if (since >= lastRebuildId) {
-      ws.send(
-        JSON.stringify({ type: "connected", data: { timestamp: Date.now(), id: lastRebuildId } }),
-      );
-      return;
+    if (since >= lastRebuildId) {
+      sendConnected(ws);
+      return;
     }
     pruneOldReplays();
     const oldestId = replayBuffer.length > 0 ? replayBuffer[0]!.id : null;
@@ -1916,9 +1940,7 @@ export function createHMRServer(
     }
     // Replay every envelope strictly newer than `since`.
     mark(HMR_PERF.HMR_REPLAY_FLUSH);
-    ws.send(
-      JSON.stringify({ type: "connected", data: { timestamp: Date.now(), id: lastRebuildId } }),
-    );
+    sendConnected(ws);
     for (const env of replayBuffer) {
       if (env.id <= since) continue;
       // Wrap in a thin envelope so the client can see the id; keep the
@@ -2171,11 +2193,21 @@ export function createHMRServer(
         envelopeId = envelope.id;
       }
 
-      const outgoing: HMRMessage =
-        envelopeId !== undefined
-          ? { ...message, data: { ...(message.data ?? {}), id: envelopeId } }
-          : message;
-      const payload = JSON.stringify(outgoing);
+      const outgoing: HMRMessage =
+        envelopeId !== undefined
+          ? { ...message, data: { ...(message.data ?? {}), id: envelopeId } }
+          : message;
+      if (outgoing.type === "error") {
+        latestBuildError = outgoing;
+      } else if (
+        outgoing.type === "reload" ||
+        outgoing.type === "full-reload" ||
+        outgoing.type === "island-update" ||
+        outgoing.type === "layout-update"
+      ) {
+        latestBuildError = null;
+      }
+      const payload = JSON.stringify(outgoing);
       fanout(payload);
       measure(HMR_PERF.HMR_BROADCAST, HMR_PERF.HMR_BROADCAST);
     },
@@ -2217,8 +2249,8 @@ export function createHMRServer(
   };
 }
 
-/**
- * HMR 클라이언트 스크립트 생성
+/**
+ * HMR 클라이언트 스크립트 생성
  * 브라우저에서 실행되어 HMR 서버와 연결.
  *
  * Phase 7.0 R1 Agent C additions:

package/src/bundler/fast-refresh-preamble.ts

@@ -1,47 +1,47 @@
-/**
- * Small runtime-safe Fast Refresh preamble helper.
- *
- * Keep this separate from `bundler/dev.ts`: SSR runtimes import the helper
- * while edge bundles must not pull the dev bundler, build graph, or TypeScript
- * compiler into production worker output.
- */
-export function generateFastRefreshPreamble(
-  glueUrl: string,
-  runtimeUrl: string,
-): string {
-  // Both URLs must be non-empty. If either is missing (e.g. vendor
-  // shim build failed), the caller should skip this preamble entirely.
-  if (!glueUrl || !runtimeUrl) {
-    return `<script>/* Mandu Fast Refresh: missing runtime assets, preamble skipped */</script>`;
-  }
-  // JSON.stringify escapes the URLs safely for inline `<script>`:
-  //   - quotes produce a valid JS string literal
-  //   - forward-slashes / backslashes are handled
-  // We also `split('</')` to avoid a stray `</script>` sequence in the
-  // URL bytes breaking the enclosing tag. This is the same defense
-  // Vite uses in its own preamble emitter.
-  const glueLit = JSON.stringify(glueUrl).split("</").join('<"+"/');
-  const runtimeLit = JSON.stringify(runtimeUrl).split("</").join('<"+"/');
-  return `<script>
-// Phase 7.1 B-3 React Fast Refresh preamble (Mandu dev-only)
-(function () {
-  if (typeof window === "undefined") return;
-  // Install inert stubs so transformed modules that run BEFORE the
-  // async runtime upgrade don't hit ReferenceError on $RefreshReg$.
-  if (!window.$RefreshReg$) window.$RefreshReg$ = function () {};
-  if (!window.$RefreshSig$) window.$RefreshSig$ = function () { return function (t) { return t; }; };
-  // Async-load the glue; failures are reported but never throw out of
-  // the preamble — a missing runtime degrades to full-reload HMR.
-  import(${glueLit})
-    .then(function (mod) {
-      var runtimeImport = function () { return import(${runtimeLit}); };
-      if (mod && typeof mod.installGlobal === "function") {
-        return mod.installGlobal({ runtimeImport: runtimeImport });
-      }
-    })
-    .catch(function (err) {
-      console.error("[Mandu Fast Refresh] preamble failed:", err);
-    });
-})();
-</script>`;
-}
+/**
+ * Small runtime-safe Fast Refresh preamble helper.
+ *
+ * Keep this separate from `bundler/dev.ts`: SSR runtimes import the helper
+ * while edge bundles must not pull the dev bundler, build graph, or TypeScript
+ * compiler into production worker output.
+ */
+export function generateFastRefreshPreamble(
+  glueUrl: string,
+  runtimeUrl: string,
+): string {
+  // Both URLs must be non-empty. If either is missing (e.g. vendor
+  // shim build failed), the caller should skip this preamble entirely.
+  if (!glueUrl || !runtimeUrl) {
+    return `<script>/* Mandu Fast Refresh: missing runtime assets, preamble skipped */</script>`;
+  }
+  // JSON.stringify escapes the URLs safely for inline `<script>`:
+  //   - quotes produce a valid JS string literal
+  //   - forward-slashes / backslashes are handled
+  // We also `split('</')` to avoid a stray `</script>` sequence in the
+  // URL bytes breaking the enclosing tag. This is the same defense
+  // Vite uses in its own preamble emitter.
+  const glueLit = JSON.stringify(glueUrl).split("</").join('<"+"/');
+  const runtimeLit = JSON.stringify(runtimeUrl).split("</").join('<"+"/');
+  return `<script>
+// Phase 7.1 B-3 React Fast Refresh preamble (Mandu dev-only)
+(function () {
+  if (typeof window === "undefined") return;
+  // Install inert stubs so transformed modules that run BEFORE the
+  // async runtime upgrade don't hit ReferenceError on $RefreshReg$.
+  if (!window.$RefreshReg$) window.$RefreshReg$ = function () {};
+  if (!window.$RefreshSig$) window.$RefreshSig$ = function () { return function (t) { return t; }; };
+  // Async-load the glue; failures are reported but never throw out of
+  // the preamble — a missing runtime degrades to full-reload HMR.
+  import(${glueLit})
+    .then(function (mod) {
+      var runtimeImport = function () { return import(${runtimeLit}); };
+      if (mod && typeof mod.installGlobal === "function") {
+        return mod.installGlobal({ runtimeImport: runtimeImport });
+      }
+    })
+    .catch(function (err) {
+      console.error("[Mandu Fast Refresh] preamble failed:", err);
+    });
+})();
+</script>`;
+}