@mandujs/core 0.53.1 → 0.53.3

package/src/db/migrations/runner.ts

@@ -69,7 +69,7 @@ import type {
   PendingMigration,
   SqlProvider,
 } from "../../resource/ddl/types";
-import type { Db } from "../index";
+import { withPinnedDbHandle, type Db } from "../index";
 import {
   DEFAULT_HISTORY_TABLE,
   SAFE_HISTORY_TABLE_RE,
@@ -128,6 +128,24 @@ export class MigrationTimeoutError extends Error {
   }
 }
 
+function assertNoTamperedHistory(
+  history: HistoryRow[],
+  diskByVersion: Map<string, PendingMigration>,
+): void {
+  for (const row of history) {
+    if (row.success !== 1) continue;
+    const disk = diskByVersion.get(row.version);
+    if (!disk) continue; // orphan on the history side — surfaced via status(), not apply()
+    if (disk.checksum !== row.checksum) {
+      throw new MigrationTamperedError(
+        disk.filename,
+        row.checksum,
+        disk.checksum,
+      );
+    }
+  }
+}
+
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 /** Options for {@link createMigrationRunner}. */
@@ -246,34 +264,18 @@ export function createMigrationRunner(
   async function apply(
     opts: { dryRun?: boolean } = {},
   ): Promise<AppliedMigration[]> {
-    await ensureReady();
-
-    // Tamper check BEFORE acquiring the lock so the fast-fail path
-    // doesn't hold the advisory lock longer than necessary.
-    const history = await readAllHistory(db, historyTable);
     const diskFiles = await readMigrationsFromDisk(migrationsDir);
     const diskByVersion = new Map(diskFiles.map((f) => [f.version, f]));
-    for (const row of history) {
-      if (row.success !== 1) continue;
-      const disk = diskByVersion.get(row.version);
-      if (!disk) continue; // orphan on the history side — surfaced via status(), not apply()
-      if (disk.checksum !== row.checksum) {
-        throw new MigrationTamperedError(
-          disk.filename,
-          row.checksum,
-          disk.checksum,
-        );
-      }
-    }
 
-    const appliedVersions = new Set(
-      history.filter((h) => h.success === 1).map((h) => h.version),
-    );
-    const pending = diskFiles.filter((f) => !appliedVersions.has(f.version));
-    if (pending.length === 0) return [];
-
-    // Dry-run: report what we WOULD apply, no IO, no history.
     if (opts.dryRun === true) {
+      await ensureReady();
+      const history = await readAllHistory(db, historyTable);
+      assertNoTamperedHistory(history, diskByVersion);
+
+      const appliedVersions = new Set(
+        history.filter((h) => h.success === 1).map((h) => h.version),
+      );
+      const pending = diskFiles.filter((f) => !appliedVersions.has(f.version));
       return pending.map<AppliedMigration>((p) => ({
         version: p.version,
         filename: p.filename,
@@ -290,100 +292,115 @@ export function createMigrationRunner(
 
     const applied: AppliedMigration[] = [];
 
-    heldLock = await acquireMigrationLock(db, lockStrategy);
-    try {
-      for (const migration of pending) {
-        const start = Date.now();
-
-        const statements = splitStatements(migration.sql);
-        if (statements.length === 0) {
-          // Empty migration — still record a history row so we don't
-          // re-run it. execution_ms = 0 reflects reality.
+    const runLockedApply = async (): Promise<AppliedMigration[]> => {
+      heldLock = await acquireMigrationLock(db, lockStrategy);
+      try {
+        await ensureReady();
+        const lockedHistory = await readAllHistory(db, historyTable);
+        assertNoTamperedHistory(lockedHistory, diskByVersion);
+        const lockedAppliedVersions = new Set(
+          lockedHistory.filter((h) => h.success === 1).map((h) => h.version),
+        );
+        const lockedPending = diskFiles.filter((f) => !lockedAppliedVersions.has(f.version));
+
+        for (const migration of lockedPending) {
+          const start = Date.now();
+
+          const statements = splitStatements(migration.sql);
+          if (statements.length === 0) {
+            // Empty migration — still record a history row so we don't
+            // re-run it. execution_ms = 0 reflects reality.
+            await insertHistory(db, historyTable, {
+              version: migration.version,
+              filename: migration.filename,
+              checksum: migration.checksum,
+              applied_at: new Date(),
+              execution_ms: 0,
+              success: 1,
+              installed_by: installedBy,
+            });
+            applied.push({
+              version: migration.version,
+              filename: migration.filename,
+              checksum: migration.checksum,
+              appliedAt: new Date(),
+              executionMs: 0,
+              success: true,
+            });
+            continue;
+          }
+
+          try {
+            await db.transaction(async (tx) => {
+              for (const stmt of statements) {
+                await execRaw(tx, stmt);
+                const elapsed = Date.now() - start;
+                if (elapsed > applyTimeoutMs) {
+                  throw new MigrationTimeoutError(
+                    migration.filename,
+                    elapsed,
+                    applyTimeoutMs,
+                  );
+                }
+              }
+            });
+          } catch (err) {
+            if (err instanceof MigrationTimeoutError) throw err;
+            // Wrap with migration context so downstream callers know
+            // which file blew up. Preserve the original stack where
+            // possible via `cause`.
+            const msg = err instanceof Error ? err.message : String(err);
+            const wrapped = new Error(
+              `[@mandujs/core/db/migrations] Failed to apply ${migration.filename}: ${msg}`,
+            );
+            // Preserve the original as a `cause` chain for diagnostics.
+            (wrapped as { cause?: unknown }).cause = err;
+            throw wrapped;
+          }
+
+          const executionMs = Date.now() - start;
+          const appliedAt = new Date();
+
+          // History row is written AFTER the SQL transaction commits.
+          // If this INSERT itself fails, the migration has run but we
+          // have no record — the user will see it as pending again.
+          // Mitigation: the insert is a single tiny statement; in
+          // practice it either succeeds or the whole connection is
+          // dead (in which case subsequent apply() calls will also fail
+          // and the user will debug from the DB side).
           await insertHistory(db, historyTable, {
             version: migration.version,
             filename: migration.filename,
             checksum: migration.checksum,
-            applied_at: new Date(),
-            execution_ms: 0,
+            applied_at: appliedAt,
+            execution_ms: executionMs,
             success: 1,
             installed_by: installedBy,
           });
+
           applied.push({
             version: migration.version,
             filename: migration.filename,
             checksum: migration.checksum,
-            appliedAt: new Date(),
-            executionMs: 0,
+            appliedAt,
+            executionMs,
             success: true,
           });
-          continue;
         }
-
-        try {
-          await db.transaction(async (tx) => {
-            for (const stmt of statements) {
-              await execRaw(tx, stmt);
-              const elapsed = Date.now() - start;
-              if (elapsed > applyTimeoutMs) {
-                throw new MigrationTimeoutError(
-                  migration.filename,
-                  elapsed,
-                  applyTimeoutMs,
-                );
-              }
-            }
-          });
-        } catch (err) {
-          if (err instanceof MigrationTimeoutError) throw err;
-          // Wrap with migration context so downstream callers know
-          // which file blew up. Preserve the original stack where
-          // possible via `cause`.
-          const msg = err instanceof Error ? err.message : String(err);
-          const wrapped = new Error(
-            `[@mandujs/core/db/migrations] Failed to apply ${migration.filename}: ${msg}`,
-          );
-          // Preserve the original as a `cause` chain for diagnostics.
-          (wrapped as { cause?: unknown }).cause = err;
-          throw wrapped;
+      } finally {
+        if (heldLock) {
+          await heldLock.release();
+          heldLock = null;
         }
+      }
 
-        const executionMs = Date.now() - start;
-        const appliedAt = new Date();
-
-        // History row is written AFTER the SQL transaction commits.
-        // If this INSERT itself fails, the migration has run but we
-        // have no record — the user will see it as pending again.
-        // Mitigation: the insert is a single tiny statement; in
-        // practice it either succeeds or the whole connection is
-        // dead (in which case subsequent apply() calls will also fail
-        // and the user will debug from the DB side).
-        await insertHistory(db, historyTable, {
-          version: migration.version,
-          filename: migration.filename,
-          checksum: migration.checksum,
-          applied_at: appliedAt,
-          execution_ms: executionMs,
-          success: 1,
-          installed_by: installedBy,
-        });
+      return applied;
+    };
 
-        applied.push({
-          version: migration.version,
-          filename: migration.filename,
-          checksum: migration.checksum,
-          appliedAt,
-          executionMs,
-          success: true,
-        });
-      }
-    } finally {
-      if (heldLock) {
-        await heldLock.release();
-        heldLock = null;
-      }
+    if (lockStrategy === "mysql_get_lock") {
+      return await withPinnedDbHandle(db, runLockedApply);
     }
-
-    return applied;
+    return await runLockedApply();
   }
 
   async function status(): Promise<MigrationStatus> {

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;