@mandujs/core 0.53.2 → 0.53.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.53.2",
+  "version": "0.53.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/diagnose/__tests__/checks.test.ts

@@ -17,6 +17,7 @@ import {
   checkCloneElementWarnings,
   checkDevArtifactsInProd,
   checkPackageExportGaps,
+  checkNestedInternalCore,
 } from "../checks";
 import { runExtendedDiagnose, buildReport } from "../run";
 
@@ -319,6 +320,75 @@ describe("checkPackageExportGaps", () => {
   });
 });
 
+// ──────────────────────────────────────────────────────────────────
+// nested_internal_core (#261)
+// ──────────────────────────────────────────────────────────────────
+
+describe("checkNestedInternalCore", () => {
+  let rootDir: string;
+  beforeEach(async () => { rootDir = await mkTmpRoot(); });
+  afterEach(async () => { await fs.rm(rootDir, { recursive: true, force: true }); });
+
+  async function seedHoistedCore(version: string): Promise<void> {
+    await writeFile(rootDir, "node_modules/@mandujs/core/package.json", JSON.stringify({
+      name: "@mandujs/core", version,
+    }));
+  }
+
+  async function seedNestedCore(parent: string, version: string): Promise<void> {
+    await writeFile(
+      rootDir,
+      `node_modules/@mandujs/${parent}/node_modules/@mandujs/core/package.json`,
+      JSON.stringify({ name: "@mandujs/core", version }),
+    );
+  }
+
+  it("skips when hoisted @mandujs/core is not installed", async () => {
+    const result = await checkNestedInternalCore(rootDir);
+    expect(result.ok).toBe(true);
+    expect(result.details?.skipped).toBe(true);
+  });
+
+  it("passes when no nested core exists", async () => {
+    await seedHoistedCore("0.53.2");
+    // Seed a sibling without nested core
+    await writeFile(rootDir, "node_modules/@mandujs/mcp/package.json", JSON.stringify({
+      name: "@mandujs/mcp", version: "0.36.2",
+    }));
+    const result = await checkNestedInternalCore(rootDir);
+    expect(result.ok).toBe(true);
+    expect(result.details?.scannedSiblings).toBe(1);
+  });
+
+  it("passes when nested core matches hoisted version exactly", async () => {
+    await seedHoistedCore("0.53.2");
+    await seedNestedCore("mcp", "0.53.2");
+    const result = await checkNestedInternalCore(rootDir);
+    expect(result.ok).toBe(true);
+  });
+
+  it("flags a stale nested core that shadows hoisted (#261 repro)", async () => {
+    await seedHoistedCore("0.53.2");
+    await seedNestedCore("mcp", "0.47.0");
+    const result = await checkNestedInternalCore(rootDir);
+    expect(result.ok).toBe(false);
+    expect(result.severity).toBe("error");
+    expect(result.message).toMatch(/@mandujs\/mcp/);
+    expect(result.message).toMatch(/0\.47\.0/);
+    expect(result.suggestion).toMatch(/rm -rf node_modules\/@mandujs\/mcp\/node_modules/);
+    expect(result.details?.mismatchCount).toBe(1);
+  });
+
+  it("reports every mismatched sibling, not just one", async () => {
+    await seedHoistedCore("0.53.2");
+    await seedNestedCore("mcp", "0.47.0");
+    await seedNestedCore("ate", "0.50.0");
+    const result = await checkNestedInternalCore(rootDir);
+    expect(result.ok).toBe(false);
+    expect(result.details?.mismatchCount).toBe(2);
+  });
+});
+
 // ──────────────────────────────────────────────────────────────────
 // aggregator
 // ──────────────────────────────────────────────────────────────────
@@ -328,10 +398,10 @@ describe("runExtendedDiagnose", () => {
   beforeEach(async () => { rootDir = await mkTmpRoot(); });
   afterEach(async () => { await fs.rm(rootDir, { recursive: true, force: true }); });
 
-  it("runs all 6 extended checks and returns a structured report", async () => {
+  it("runs all 7 extended checks and returns a structured report", async () => {
     const report = await runExtendedDiagnose(rootDir);
-    // Phase 18.χ added `a11y_hints` — total is now 6.
-    expect(report.summary.total).toBe(6);
+    // #261 added `nested_internal_core` — total is now 7.
+    expect(report.summary.total).toBe(7);
     // manifest is missing → at least one error
     expect(report.healthy).toBe(false);
     expect(report.errorCount).toBeGreaterThanOrEqual(1);
@@ -341,6 +411,7 @@ describe("runExtendedDiagnose", () => {
     expect(rules).toContain("cloneelement_warnings");
     expect(rules).toContain("dev_artifacts_in_prod");
     expect(rules).toContain("package_export_gaps");
+    expect(rules).toContain("nested_internal_core");
     expect(rules).toContain("a11y_hints");
   });
 

package/src/diagnose/checks.ts

@@ -718,3 +718,115 @@ export async function checkA11yHints(rootDir: string): Promise<DiagnoseCheckResu
     },
   };
 }
+
+// ────────────────────────────────────────────────────────────────────────
+// 7. nested_internal_core (#261)
+// ────────────────────────────────────────────────────────────────────────
+
+interface NestedCoreSite {
+  parentPackage: string;
+  nestedVersion: string;
+  relativePath: string;
+}
+
+async function readPackageVersion(pkgJsonPath: string): Promise<string | null> {
+  try {
+    const raw = await fs.readFile(pkgJsonPath, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    return typeof parsed.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+async function listMandujsSiblings(rootDir: string): Promise<string[]> {
+  const dir = path.join(rootDir, "node_modules", "@mandujs");
+  try {
+    const entries = (await fs.readdir(dir, { withFileTypes: true })) as Dirent[];
+    return entries
+      .filter((e) => e.isDirectory() && e.name !== "core")
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * #261 check 7: detect a stale `@mandujs/core` nested inside another
+ * `@mandujs/*` package's `node_modules`.
+ *
+ * Symptom: `bunx @mandujs/mcp` fails with `Cannot find module
+ * @mandujs/core/<subpath>` even though the project has the latest
+ * `@mandujs/core` hoisted at the top level. Cause: a previous install
+ * left an older core nested under `@mandujs/<sibling>/node_modules`,
+ * which wins module resolution from inside that sibling's code, and the
+ * older core's `exports` map lacks the subpath the sibling now imports.
+ *
+ * This check walks `node_modules/@mandujs/*` siblings, looks for a
+ * nested `node_modules/@mandujs/core/package.json`, and compares the
+ * version to the hoisted core. A mismatch is reported as `error`
+ * (boot-breaking on the user's machine) with a copy-pastable fix.
+ */
+export async function checkNestedInternalCore(rootDir: string): Promise<DiagnoseCheckResult> {
+  const hoistedPath = path.join(rootDir, "node_modules", "@mandujs", "core", "package.json");
+  const hoistedVersion = await readPackageVersion(hoistedPath);
+
+  if (!hoistedVersion) {
+    return {
+      ok: true,
+      rule: "nested_internal_core",
+      message: "@mandujs/core not installed at the project root — skipping nested-version check.",
+      details: { skipped: true },
+    };
+  }
+
+  const siblings = await listMandujsSiblings(rootDir);
+  const mismatches: NestedCoreSite[] = [];
+
+  for (const sibling of siblings) {
+    const nestedPkgJson = path.join(
+      rootDir,
+      "node_modules",
+      "@mandujs",
+      sibling,
+      "node_modules",
+      "@mandujs",
+      "core",
+      "package.json",
+    );
+    const nestedVersion = await readPackageVersion(nestedPkgJson);
+    if (!nestedVersion) continue;
+    if (nestedVersion === hoistedVersion) continue;
+    mismatches.push({
+      parentPackage: `@mandujs/${sibling}`,
+      nestedVersion,
+      relativePath: path.relative(rootDir, nestedPkgJson),
+    });
+  }
+
+  if (mismatches.length === 0) {
+    return {
+      ok: true,
+      rule: "nested_internal_core",
+      message: `No stale nested @mandujs/core found (hoisted: ${hoistedVersion}, scanned ${siblings.length} sibling(s)).`,
+      details: { hoistedVersion, scannedSiblings: siblings.length },
+    };
+  }
+
+  const first = mismatches[0];
+  const fixCommand = `rm -rf node_modules/${first.parentPackage}/node_modules`;
+  return {
+    ok: false,
+    rule: "nested_internal_core",
+    severity: "error",
+    message:
+      `${mismatches.length} stale nested @mandujs/core install(s) shadow the hoisted ${hoistedVersion}. ` +
+      `First: ${first.parentPackage} pinned to ${first.nestedVersion} (${first.relativePath}).`,
+    suggestion: `Run \`${fixCommand}\` and re-test \`bunx @mandujs/mcp\`, or remove node_modules and bun.lock entirely and \`bun install\`.`,
+    details: {
+      hoistedVersion,
+      mismatchCount: mismatches.length,
+      mismatches,
+    },
+  };
+}

package/src/diagnose/index.ts

@@ -11,6 +11,7 @@ export {
   checkCloneElementWarnings,
   checkDevArtifactsInProd,
   checkPackageExportGaps,
+  checkNestedInternalCore,
   checkA11yHints,
 } from "./checks";
 export { EXTENDED_CHECKS, runExtendedDiagnose, buildReport } from "./run";

package/src/diagnose/run.ts

@@ -12,6 +12,7 @@ import {
   checkCloneElementWarnings,
   checkDevArtifactsInProd,
   checkPackageExportGaps,
+  checkNestedInternalCore,
   checkA11yHints,
 } from "./checks";
 
@@ -30,6 +31,7 @@ export const EXTENDED_CHECKS = [
   { name: "cloneelement_warnings", run: checkCloneElementWarnings },
   { name: "dev_artifacts_in_prod", run: checkDevArtifactsInProd },
   { name: "package_export_gaps", run: checkPackageExportGaps },
+  { name: "nested_internal_core", run: checkNestedInternalCore },
   { name: "a11y_hints", run: checkA11yHints },
 ] as const;
 

package/src/runtime/ssr.ts

@@ -772,10 +772,11 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? generateFastRefreshPreambleTag(isDev, bundleManifest, resolvedCspNonce)
     : "";
 
-  // Issue #191 — DevTools 번들 (~1.15 MB) 주입 결정.
-  //   - 기본: island 이 하나라도 있을 때만 주입. Pure-SSR 페이지는 0 bytes 다운로드.
-  //   - `devtools === true`  → 강제 주입 (SSR-only 프로젝트에서 Kitchen panel 원할 때)
-  //   - `devtools === false` → 강제 스킵 (island 프로젝트에서도 Kitchen 비활성화)
+  // Issue #191 + #259 — DevTools 번들 (~1.15 MB) 주입 결정.
+  //   - 기본 (dev only): 항상 주입. SSR-only 랜딩에서도 Kitchen 패널 사용 가능.
+  //   - `devtools === true`  → 강제 주입 (의미 변화 없음)
+  //   - `devtools === false` → 강제 스킵 (필요 시 1.15 MB 절약)
+  // 프로덕션 빌드는 `isDev` 가드로 0 bytes 보장.
   // Cache-bust 은 `manifest.buildTime` 우선, 없으면 `Date.now()`.
   let devtoolsScript = "";
   if (isDev && shouldInjectDevtools(devtools, bundleManifest)) {
@@ -1039,27 +1040,27 @@ window.__MANDU_HMR_PORT__ = ${hmrPort};
 }
 
 /**
- * Issue #191 — Determine whether the dev-only `_devtools.js` bundle
- * (~1.15 MB React dev runtime + Kitchen panel) should be injected
- * into the HTML response.
+ * Issue #191 + #259 — Determine whether the dev-only `_devtools.js`
+ * bundle (~1.15 MB React dev runtime + Kitchen panel) should be injected
+ * into the HTML response. The caller gates with `isDev`, so this only
+ * affects dev-mode responses (prod always skips, regardless of the
+ * decision below).
  *
  * Decision table (`devtools` option × manifest shape):
  *
- *   | `devtools`  | hasIslands | inject? | rationale                   |
- *   |-------------|------------|---------|-----------------------------|
- *   | `true`      | any        | YES     | explicit opt-in             |
- *   | `false`     | any        | NO      | explicit opt-out            |
- *   | `undefined` | true       | YES     | default, hydration runtime  |
- *   | `undefined` | false      | NO      | pure-SSR — save 1.15 MB     |
- *   | `undefined` | no manifest| NO      | nothing to hydrate anyway   |
+ *   | `devtools`  | hasIslands | inject? | rationale                    |
+ *   |-------------|------------|---------|------------------------------|
+ *   | `true`      | any        | YES     | explicit opt-in              |
+ *   | `false`     | any        | NO      | explicit opt-out             |
+ *   | `undefined` | true       | YES     | default, hydration runtime   |
+ *   | `undefined` | false      | YES     | dev DX: Kitchen on SSR pages |
+ *   | `undefined` | no manifest| YES     | dev DX: Kitchen pre-build    |
  *
- * `hasIslands` is derived from the existing manifest shape rather than
- * a new field, so no bundler-side change is required:
- *   - `manifest.islands` is populated only when per-island code
- *     splitting produced at least one bundle (build.ts:1654).
- *   - `manifest.bundles` entries exist only for routes where
- *     `needsHydration()` is true (build.ts:70 filter).
- * Either non-empty ⇒ some route on this server hydrates ⇒ devtools useful.
+ * #259 reverted the original #191 default (skip when no islands): SSR-only
+ * landing/marketing pages are the exact place where Kitchen network/error
+ * panels are most needed, and the 1.15 MB cost only applies in dev — prod
+ * builds never emit `_devtools.js`. Users who explicitly want the old
+ * behavior on a per-app basis can still set `dev.devtools: false`.
  *
  * @internal Exported via `_testOnly_shouldInjectDevtools` below so
  * `tests/runtime/devtools-inject.test.ts` can table-test the matrix
@@ -1067,19 +1068,11 @@ window.__MANDU_HMR_PORT__ = ${hmrPort};
  */
 function shouldInjectDevtools(
   devtools: boolean | undefined,
-  manifest: BundleManifest | undefined,
+  _manifest: BundleManifest | undefined,
 ): boolean {
-  // Explicit overrides take absolute precedence.
   if (devtools === true) return true;
   if (devtools === false) return false;
-
-  // Default behavior: inject only when there is at least one island.
-  if (!manifest) return false;
-  const hasIslandsMap =
-    manifest.islands && Object.keys(manifest.islands).length > 0;
-  const hasBundles =
-    manifest.bundles && Object.keys(manifest.bundles).length > 0;
-  return Boolean(hasIslandsMap || hasBundles);
+  return true;
 }
 
 /**

package/src/runtime/streaming-ssr.ts

@@ -80,10 +80,10 @@ export interface StreamingError {
 export interface StreamingMetrics {
   /** Shell ready까지 걸린 시간 (ms) */
   shellReadyTime: number;
-  /** All ready까지 걸린 시간 (ms) */
-  allReadyTime: number;
-  /** Deferred chunk 개수 */
-  deferredChunkCount: number;
+  /** All ready까지 걸린 시간 (ms) */
+  allReadyTime: number;
+  /** Deferred chunk 개수 */
+  deferredChunkCount: number;
   /** 에러 발생 여부 */
   hasError: boolean;
   /** 시작 시간 */
@@ -202,7 +202,7 @@ export interface StreamingSSROptions {
 }
 
 /**
- * Issue #191 — Streaming-SSR mirror of `ssr.ts:shouldInjectDevtools`.
+ * Issue #191 + #259 — Streaming-SSR mirror of `ssr.ts:shouldInjectDevtools`.
  * Kept in sync manually (tiny pure function, not worth a cross-module
  * runtime import — the ssr.ts → streaming-ssr.ts re-export direction
  * means a circular import here would force a refactor of the whole
@@ -211,16 +211,11 @@ export interface StreamingSSROptions {
  */
 function shouldInjectDevtoolsStreaming(
   devtools: boolean | undefined,
-  manifest: BundleManifest | undefined,
+  _manifest: BundleManifest | undefined,
 ): boolean {
   if (devtools === true) return true;
   if (devtools === false) return false;
-  if (!manifest) return false;
-  const hasIslandsMap =
-    manifest.islands && Object.keys(manifest.islands).length > 0;
-  const hasBundles =
-    manifest.bundles && Object.keys(manifest.bundles).length > 0;
-  return Boolean(hasIslandsMap || hasBundles);
+  return true;
 }
 
 /**
@@ -778,10 +773,10 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     scripts.push(generateHMRScript(hmrPort));
   }
 
-  // 11. Issue #191 — DevTools 번들 (~1.15 MB) 주입 결정.
-  //   - 기본: manifest 에 island/bundle 이 있을 때만 주입 (pure-SSR 페이지는 스킵).
-  //   - `devtools === true`  → 강제 주입 (SSR-only 프로젝트에서 Kitchen 원할 때).
-  //   - `devtools === false` → 강제 스킵.
+  // 11. Issue #191 + #259 — DevTools 번들 (~1.15 MB) 주입 결정.
+  //   - 기본 (dev only): 항상 주입. SSR-only 랜딩에서도 Kitchen 사용 가능.
+  //   - `devtools === false` → 강제 스킵 (필요 시 1.15 MB 절약).
+  //   - 프로덕션 빌드는 `isDev` 가드로 0 bytes 보장.
   //   - Cache-bust (`?v=buildTime`) 로 HMR 후 stale 방지.
   if (isDev && shouldInjectDevtoolsStreaming(devtools, bundleManifest)) {
     scripts.push(generateStreamingDevtoolsScript(bundleManifest));
@@ -1001,9 +996,9 @@ export async function renderToStream(
 
   // 메트릭 수집
   const metrics: StreamingMetrics = {
-    shellReadyTime: 0,
-    allReadyTime: 0,
-    deferredChunkCount: 0,
+    shellReadyTime: 0,
+    allReadyTime: 0,
+    deferredChunkCount: 0,
     hasError: false,
     startTime: Date.now(),
   };
@@ -1379,9 +1374,9 @@ export async function renderWithDeferredData(
   const encoder = new TextEncoder();
   const startTime = Date.now();
 
-  // 준비된 deferred 스크립트를 담을 배열 (mutable)
-  const readyScripts: string[] = [];
-  let allDeferredSettled = false;
+  // 준비된 deferred 스크립트를 담을 배열 (mutable)
+  const readyScripts: string[] = [];
+  let allDeferredSettled = false;
 
   // 1. Deferred promises 병렬 시작 (막지 않음!)
   const deferredEntries = Object.entries(deferredPromises);
@@ -1395,11 +1390,11 @@ export async function renderWithDeferredData(
             );
             const data = await Promise.race([promise, timeoutPromise]);
 
-            // 스크립트 생성 및 추가
-            const script = generateDeferredDataScript(routeId, key, data);
-            readyScripts.push(script);
-
-            if (isDev) {
+            // 스크립트 생성 및 추가
+            const script = generateDeferredDataScript(routeId, key, data);
+            readyScripts.push(script);
+
+            if (isDev) {
               console.log(`[Mandu Streaming] Deferred ready: ${key} (${Date.now() - startTime}ms)`);
             }
           } catch (error) {
@@ -1473,22 +1468,22 @@ export async function renderWithDeferredData(
 
         // 최종 메트릭 보고 (injectedCount가 실제 메트릭)
         if (onMetrics && baseMetrics) {
-          onMetrics({
-            ...baseMetrics,
-            deferredChunkCount: injectedCount,
-            allReadyTime: Date.now() - startTime,
-          });
+          onMetrics({
+            ...baseMetrics,
+            deferredChunkCount: injectedCount,
+            allReadyTime: Date.now() - startTime,
+          });
         }
 
         controller.close();
       } catch (error) {
         controller.error(error);
       }
-    },
-    cancel() {
-      void reader.cancel();
-    },
-  });
+    },
+    cancel() {
+      void reader.cancel();
+    },
+  });
 
   // Phase 7.2 R1 Agent C (H1): if the base stream produced a CSP
   // nonce during shell emission, forward the matching header on the