@mandujs/mcp 0.38.1 → 0.38.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.38.1",
+  "version": "0.38.2",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.54.7",
+    "@mandujs/core": "^0.54.8",
     "@mandujs/ate": "^0.26.1",
     "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/tools/hydration.ts

@@ -61,8 +61,22 @@ export const hydrationToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.island.list",
-    description:
-      "List all routes that have client-side hydration (islands). Shows hydration strategy and priority for each.",
+    description:
+      "Legacy alias for page client mount diagnostics. Prefer mandu.pageClientMount.list for terminology that separates page-level hydration from nested islands.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "mandu.pageClientMount.list",
+    description:
+      "List page-level client mounts: page routes that need a route-level clientModule and bundle. This is distinct from nested islands/partials.",
     annotations: {
       readOnlyHint: true,
     },
@@ -220,19 +234,19 @@ export function hydrationTools(projectRoot: string) {
       };
     },
 
-    "mandu.island.list": async () => {
-      // Load manifest
-      const manifestResult = await loadManifest(paths.manifestPath);
-      if (!manifestResult.success || !manifestResult.data) {
-        return { error: manifestResult.errors };
-      }
-
-      const islands = manifestResult.data.routes
+    "mandu.pageClientMount.list": async () => {
+      // Load manifest
+      const manifestResult = await loadManifest(paths.manifestPath);
+      if (!manifestResult.success || !manifestResult.data) {
+        return { error: manifestResult.errors };
+      }
+
+      const pageClientMounts = manifestResult.data.routes
         .filter((route) => route.kind === "page")
         .map((route) => {
           const hydration = getRouteHydration(route);
-          const isIsland = needsHydration(route);
-          const warning = isIsland && !route.clientModule
+          const needsClientMount = needsHydration(route);
+          const warning = needsClientMount && !route.clientModule
             ? `Route has hydration strategy '${hydration.strategy}' but no clientModule; build would emit no route bundle.`
             : null;
 
@@ -241,29 +255,44 @@ export function hydrationTools(projectRoot: string) {
             pattern: route.pattern,
             hasClientModule: !!route.clientModule,
             clientModule: route.clientModule || null,
-            isIsland,
-            status: isIsland ? (route.clientModule ? "ready" : "broken") : "static",
+            needsClientMount,
+            // Backward compatibility for older agents that read `isIsland`.
+            isIsland: needsClientMount,
+            status: needsClientMount ? (route.clientModule ? "ready" : "broken") : "static",
             warning,
             hydration: {
               strategy: hydration.strategy,
               priority: hydration.priority,
               preload: hydration.preload,
-            },
-          };
-        });
-
-      const islandCount = islands.filter((i) => i.isIsland).length;
-      const staticCount = islands.filter((i) => !i.isIsland).length;
-
-      return {
-        totalPages: islands.length,
-        islandCount,
-        staticCount,
-        islands: islands.filter((i) => i.isIsland),
-        staticPages: islands.filter((i) => !i.isIsland),
-      };
+            },
+          };
+        });
+
+      const pageClientMountCount = pageClientMounts.filter((i) => i.needsClientMount).length;
+      const staticCount = pageClientMounts.filter((i) => !i.needsClientMount).length;
+      const activeMounts = pageClientMounts.filter((i) => i.needsClientMount);
+      const staticPages = pageClientMounts.filter((i) => !i.needsClientMount);
+
+      return {
+        terminology: {
+          pageClientMount:
+            "A page route whose whole page is hydrated from a route-level clientModule and route bundle.",
+          island:
+            "A nested or route-local island bundle, distinct from page client mounts. Use mandu.runtime.status for both collections.",
+        },
+        totalPages: pageClientMounts.length,
+        pageClientMountCount,
+        staticCount,
+        pageClientMounts: activeMounts,
+        staticPages,
+        // Backward compatibility for older clients.
+        islandCount: pageClientMountCount,
+        islands: activeMounts,
+      };
     },
 
+    "mandu.island.list": async () => handlers["mandu.pageClientMount.list"]({}),
+
     "mandu.hydration.set": async (args: Record<string, unknown>) => {
       const validationError = validateRouteIdArgs(
         args,
@@ -423,6 +452,7 @@ export function hydrationTools(projectRoot: string) {
   handlers["mandu_build"] = handlers["mandu.build"];
   handlers["mandu_build_status"] = handlers["mandu.build.status"];
   handlers["mandu_list_islands"] = handlers["mandu.island.list"];
+  handlers["mandu_page_client_mount_list"] = handlers["mandu.pageClientMount.list"];
   handlers["mandu_set_hydration"] = handlers["mandu.hydration.set"];
   handlers["mandu_hydration_set"] = handlers["mandu.hydration.set"];
   handlers["mandu_add_client_slot"] = handlers["mandu.hydration.addClientSlot"];

package/src/tools/runtime.ts

@@ -5,7 +5,13 @@
 
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { getProjectPaths } from "../utils/project.js";
-import { loadManduConfig, loadManifest, needsHydration } from "@mandujs/core";
+import {
+  getRouteHydration,
+  loadManduConfig,
+  loadManifest,
+  needsHydration,
+  type BundleManifest,
+} from "@mandujs/core";
 import { getDevServerState } from "./project.js";
 import { readRuntimeControl } from "../utils/runtime-control.js";
 import path from "path";
@@ -69,6 +75,20 @@ export const runtimeToolDefinitions: Tool[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "mandu.runtime.status",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Single source of truth for Mandu client runtime state. Separates page client mounts from nested islands and compares routes manifest, bundle manifest, and generated route artifacts.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
   {
     name: "mandu.runtime.contractOptions",
     annotations: {
@@ -330,6 +350,67 @@ export default Mandu.contract({
       };
     },
 
+    "mandu.runtime.status": async () => {
+      const result = await loadManifest(paths.manifestPath);
+      if (!result.success || !result.data) {
+        return {
+          success: false,
+          error: result.errors,
+        };
+      }
+
+      const bundleManifest = await readBundleManifest(projectRoot);
+      const pageRoutes = result.data.routes.filter((route) => route.kind === "page");
+      const pageClientMounts = await Promise.all(
+        pageRoutes.map(async (route) =>
+          describePageClientMount(projectRoot, route, bundleManifest),
+        ),
+      );
+      const nestedIslands = Object.entries(bundleManifest?.islands ?? {}).map(([id, island]) => ({
+        islandId: id,
+        routeId: island.route,
+        bundleUrl: island.js,
+        priority: island.priority,
+      }));
+      const partials = Object.entries(bundleManifest?.partials ?? {}).map(([id, partial]) => ({
+        partialId: id,
+        bundleUrl: partial.js,
+        priority: partial.priority,
+      }));
+      const consistencyChecks = buildRuntimeConsistencyChecks(pageClientMounts, bundleManifest);
+      const failedChecks = consistencyChecks.filter((check) => check.status === "fail");
+      const brokenMounts = pageClientMounts.filter((mount) => mount.status === "broken");
+
+      return {
+        success: failedChecks.length === 0 && brokenMounts.length === 0,
+        terminology: {
+          pageClientMount:
+            "A page route whose whole page is hydrated from a route-level clientModule and route bundle.",
+          island:
+            "A nested or route-local island bundle listed in .mandu/manifest.json islands, distinct from page client mounts.",
+          partial:
+            "An inline partial hydration boundary listed in .mandu/manifest.json partials.",
+        },
+        sources: {
+          routesManifest: ".mandu/routes.manifest.json",
+          bundleManifest: bundleManifest ? ".mandu/manifest.json" : null,
+          generatedRoutes: ".mandu/generated/web/routes/*.route.tsx",
+        },
+        summary: {
+          totalPages: pageRoutes.length,
+          pageClientMountCount: pageClientMounts.filter((mount) => mount.needsClientMount).length,
+          brokenPageClientMountCount: brokenMounts.length,
+          nestedIslandCount: nestedIslands.length,
+          partialCount: partials.length,
+          failedConsistencyCheckCount: failedChecks.length,
+        },
+        pageClientMounts,
+        islands: nestedIslands,
+        partials,
+        consistencyChecks,
+      };
+    },
+
     "mandu.runtime.contractOptions": async (args: Record<string, unknown>) => {
       const { routeId } = args as { routeId: string };
 
@@ -636,10 +717,181 @@ export const appLogger = logger(${JSON.stringify(config, null, 2)});
   handlers["mandu_list_logger_options"] = handlers["mandu.runtime.loggerOptions"];
   handlers["mandu_generate_logger_config"] = handlers["mandu.runtime.loggerConfig"];
   handlers["mandu_runtime_probe"] = handlers["mandu.runtime.probe"];
+  handlers["mandu_runtime_status"] = handlers["mandu.runtime.status"];
 
   return handlers;
 }
 
+type PageRouteForStatus = Parameters<typeof needsHydration>[0] & {
+  id: string;
+  pattern: string;
+  clientModule?: string;
+};
+
+type PageClientMountStatus = {
+  routeId: string;
+  pattern: string;
+  needsClientMount: boolean;
+  hasClientModule: boolean;
+  clientModule: string | null;
+  hydration: ReturnType<typeof getRouteHydration>;
+  bundleUrl: string | null;
+  status: "static" | "pending" | "healthy" | "broken";
+  reasons: string[];
+  generatedRoute: GeneratedRouteInspection;
+};
+
+type GeneratedRouteInspection = {
+  path: string;
+  exists: boolean;
+  kind: "missing" | "client_mount" | "placeholder" | "custom";
+  referencesClientModule: boolean;
+  callsIslandRender: boolean;
+};
+
+type RuntimeConsistencyCheck = {
+  check: string;
+  status: "pass" | "fail" | "skip";
+  failingRoutes?: string[];
+  reason?: string;
+};
+
+async function readBundleManifest(projectRoot: string): Promise<BundleManifest | null> {
+  const filePath = path.join(projectRoot, ".mandu/manifest.json");
+  try {
+    const raw = await Bun.file(filePath).text();
+    return JSON.parse(raw) as BundleManifest;
+  } catch {
+    return null;
+  }
+}
+
+async function describePageClientMount(
+  projectRoot: string,
+  route: PageRouteForStatus,
+  bundleManifest: BundleManifest | null,
+): Promise<PageClientMountStatus> {
+  const hydration = getRouteHydration(route);
+  const needsClientMount = needsHydration(route);
+  const bundle = bundleManifest?.bundles?.[route.id] ?? null;
+  const generatedRoute = await inspectGeneratedRoute(projectRoot, route);
+  const reasons: string[] = [];
+
+  if (needsClientMount && !route.clientModule) {
+    reasons.push("missing_client_module");
+  }
+  if (needsClientMount && route.clientModule && bundleManifest && !bundle) {
+    reasons.push("missing_bundle");
+  }
+  if (needsClientMount && route.clientModule && generatedRoute.exists && !generatedRoute.referencesClientModule) {
+    reasons.push("generated_route_not_using_client_module");
+  }
+  if (needsClientMount && !route.clientModule && generatedRoute.kind === "placeholder") {
+    reasons.push("generated_placeholder_for_hydrating_route");
+  }
+
+  const status = !needsClientMount
+    ? "static"
+    : reasons.length > 0
+      ? "broken"
+      : bundleManifest
+        ? "healthy"
+        : "pending";
+
+  return {
+    routeId: route.id,
+    pattern: route.pattern,
+    needsClientMount,
+    hasClientModule: !!route.clientModule,
+    clientModule: route.clientModule ?? null,
+    hydration,
+    bundleUrl: bundle?.js ?? null,
+    status,
+    reasons,
+    generatedRoute,
+  };
+}
+
+async function inspectGeneratedRoute(
+  projectRoot: string,
+  route: PageRouteForStatus,
+): Promise<GeneratedRouteInspection> {
+  const relPath = `.mandu/generated/web/routes/${route.id}.route.tsx`;
+  const filePath = path.join(projectRoot, relPath);
+  let source: string;
+  try {
+    source = await Bun.file(filePath).text();
+  } catch {
+    return {
+      path: relPath,
+      exists: false,
+      kind: "missing",
+      referencesClientModule: false,
+      callsIslandRender: false,
+    };
+  }
+
+  const normalized = source.replace(/\\/g, "/");
+  const clientModule = route.clientModule?.replace(/\\/g, "/") ?? null;
+  const referencesClientModule = clientModule ? normalized.includes(`Client Module: ${clientModule}`) : false;
+  const callsIslandRender = normalized.includes("islandModule.definition.render");
+  const placeholder =
+    normalized.includes('React.createElement("h1", null') &&
+    normalized.includes(`Route ID: ${route.id}`);
+
+  return {
+    path: relPath,
+    exists: true,
+    kind: referencesClientModule && callsIslandRender
+      ? "client_mount"
+      : placeholder
+        ? "placeholder"
+        : "custom",
+    referencesClientModule,
+    callsIslandRender,
+  };
+}
+
+function buildRuntimeConsistencyChecks(
+  pageClientMounts: PageClientMountStatus[],
+  bundleManifest: BundleManifest | null,
+): RuntimeConsistencyCheck[] {
+  const activeMounts = pageClientMounts.filter((mount) => mount.needsClientMount);
+  const missingClientModule = activeMounts
+    .filter((mount) => !mount.hasClientModule)
+    .map((mount) => mount.routeId);
+  const missingBundle = activeMounts
+    .filter((mount) => mount.hasClientModule && bundleManifest && !mount.bundleUrl)
+    .map((mount) => mount.routeId);
+  const generatedMismatch = activeMounts
+    .filter((mount) => mount.generatedRoute.exists && mount.generatedRoute.kind !== "client_mount")
+    .map((mount) => mount.routeId);
+
+  return [
+    {
+      check: "hydrating-routes-have-client-module",
+      status: missingClientModule.length > 0 ? "fail" : "pass",
+      failingRoutes: missingClientModule,
+    },
+    {
+      check: "client-modules-have-route-bundles",
+      status: !bundleManifest ? "skip" : missingBundle.length > 0 ? "fail" : "pass",
+      failingRoutes: missingBundle,
+      reason: !bundleManifest ? "No .mandu/manifest.json found. Run mandu.build first." : undefined,
+    },
+    {
+      check: "generated-routes-match-client-modules",
+      status: generatedMismatch.length > 0 ? "fail" : "pass",
+      failingRoutes: generatedMismatch,
+    },
+    {
+      check: "terminology-separated",
+      status: "pass",
+      reason: "pageClientMounts, islands, and partials are reported as separate collections.",
+    },
+  ];
+}
+
 function insertAfter(content: string, search: string): boolean {
   return content.includes(search);
 }