@mandujs/mcp 0.32.3 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.32.3",
+  "version": "0.33.0",
   "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.46.0",
+    "@mandujs/core": "^0.47.0",
     "@mandujs/ate": "^0.25.1",
     "@mandujs/skills": "^0.19.0",
     "@modelcontextprotocol/sdk": "^1.25.3"

package/src/tools/deploy-plan.ts

@@ -0,0 +1,330 @@
+/**
+ * MCP tools — deploy intent inspection & compile.
+ *
+ * Issue #250 — Phase 1 follow-up.
+ *
+ * Two read-mostly tools agents use to drive Mandu's deploy pipeline:
+ *
+ *   - `mandu.deploy.plan` — run the heuristic inferer over the routes
+ *     manifest and the existing intent cache. Returns the next cache
+ *     + a per-route diff. Default is read-only (`apply: false`); pass
+ *     `apply: true` to atomically write `.mandu/deploy.intent.json`.
+ *
+ *   - `mandu.deploy.compile` — compile the manifest + cache into a
+ *     concrete `vercel.json` (other targets land in subsequent
+ *     phases). Returns the config object, the per-route summary, and
+ *     compile warnings. Read-only — never writes vercel.json.
+ *
+ * The two tools share the same `@mandujs/core/deploy` engine the CLI
+ * uses, so agents and humans see identical results. Going through the
+ * core API rather than spawning the CLI keeps the response structured
+ * and avoids a child-process roundtrip.
+ *
+ * @see packages/cli/src/commands/deploy/plan.ts — interactive CLI
+ * @see packages/cli/src/commands/deploy/adapters/vercel.ts — adapter
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  compileVercelJson,
+  emptyDeployIntentCache,
+  isStaticIntentValidFor,
+  loadDeployIntentCache,
+  planDeploy,
+  saveDeployIntentCache,
+  VercelCompileError,
+  buildDeployInferenceContext,
+  type DeployIntent,
+  type DeployIntentCache,
+  type PlanDiffEntry,
+  type VercelCompileResult,
+} from "@mandujs/core/deploy";
+import { generateManifest, loadManifest, type RoutesManifest } from "@mandujs/core";
+import path from "node:path";
+
+/**
+ * Resolve the routes manifest for the project.
+ *
+ * Prefer the on-disk `.mandu/routes.manifest.json` (fast, written by
+ * `mandu build` / `mandu dev`). When that's missing, scan `app/`
+ * directly via `generateManifest()` so the tool keeps working in a
+ * fresh checkout. Returns `{ manifest, error }` — the error surface
+ * is `null` when at least one path succeeded, otherwise it carries
+ * the most specific reason so the MCP response can guide the agent.
+ */
+async function resolveManifestForTooling(
+  projectRoot: string,
+): Promise<{ manifest: RoutesManifest | null; error: string | null }> {
+  const manifestPath = path.join(projectRoot, ".mandu", "routes.manifest.json");
+  try {
+    const result = await loadManifest(manifestPath);
+    if (result.success && result.data) {
+      return { manifest: result.data, error: null };
+    }
+    // Fall through to fs scan if the on-disk manifest is missing/malformed.
+  } catch {
+    // Fall through.
+  }
+  try {
+    const result = await generateManifest(projectRoot);
+    return { manifest: result.manifest, error: null };
+  } catch (err) {
+    return {
+      manifest: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+// ─── deploy.plan ──────────────────────────────────────────────────────
+
+interface DeployPlanInput {
+  /**
+   * When true, write the next cache to `.mandu/deploy.intent.json`.
+   * Default false — agents should review the diff and call again with
+   * `apply: true` only after the human sign-off.
+   */
+  apply?: boolean;
+  /** Force re-inference even on unchanged source hashes. */
+  reinfer?: boolean;
+}
+
+interface DeployPlanResultPayload {
+  /** ISO timestamp the inferer wrote into the next cache. */
+  generated_at: string;
+  /** Identifier of the inferer (`heuristic` for now; brain in M4). */
+  brain_model: string;
+  /** Per-route diff suitable for rendering as a table. */
+  diff: Array<{
+    route_id: string;
+    pattern: string;
+    kind: PlanDiffEntry["kind"];
+    runtime?: DeployIntent["runtime"];
+    previous_runtime?: DeployIntent["runtime"];
+    rationale?: string;
+    source?: "explicit" | "inferred";
+  }>;
+  /** Validation warnings (intent vs route shape). */
+  warnings: string[];
+  /** Total intents in the next cache. */
+  intent_count: number;
+  /** Whether the cache file was actually written. */
+  applied: boolean;
+}
+
+async function deployPlanHandler(
+  projectRoot: string,
+  input: DeployPlanInput,
+): Promise<DeployPlanResultPayload | { error: string; hint?: string }> {
+  const apply = input.apply === true;
+  const reinfer = input.reinfer === true;
+
+  const { manifest, error: manifestError } = await resolveManifestForTooling(projectRoot);
+  if (!manifest) {
+    return {
+      error: `Routes manifest could not be resolved: ${manifestError ?? "unknown reason"}`,
+      hint: "Run `mandu build` (or ensure `app/` exists with at least one route) before calling deploy tools.",
+    };
+  }
+
+  let previous: DeployIntentCache;
+  try {
+    previous = await loadDeployIntentCache(projectRoot);
+  } catch (err) {
+    return {
+      error: `Failed to load .mandu/deploy.intent.json: ${err instanceof Error ? err.message : String(err)}`,
+      hint: "Delete or restore the file, then call `mandu.deploy.plan` again.",
+    };
+  }
+
+  const result = await planDeploy({
+    rootDir: projectRoot,
+    manifest,
+    previous,
+    reinfer,
+    brainModel: "heuristic",
+  });
+
+  // Validate every entry against route shape so agents see the same
+  // warnings the CLI surfaces.
+  const warnings: string[] = [];
+  for (const route of manifest.routes) {
+    const entry = result.cache.intents[route.id];
+    if (!entry) continue;
+    const ctx = await buildDeployInferenceContext(projectRoot, route);
+    const validation = isStaticIntentValidFor(entry.intent, {
+      isDynamic: ctx.isDynamic,
+      hasGenerateStaticParams: ctx.hasGenerateStaticParams,
+      kind: ctx.kind,
+    });
+    if (!validation.ok) {
+      warnings.push(`${route.id} (${route.pattern}): ${validation.reason}`);
+    }
+  }
+
+  if (apply) {
+    await saveDeployIntentCache(projectRoot, result.cache);
+  }
+
+  return {
+    generated_at: result.cache.generatedAt,
+    brain_model: result.cache.brainModel,
+    diff: result.diff.map((d) => ({
+      route_id: d.routeId,
+      pattern: d.pattern,
+      kind: d.kind,
+      runtime: d.next?.intent.runtime,
+      previous_runtime: d.previous?.intent.runtime,
+      rationale: d.next?.rationale,
+      source: d.next?.source,
+    })),
+    warnings,
+    intent_count: Object.keys(result.cache.intents).length,
+    applied: apply,
+  };
+}
+
+// ─── deploy.compile ───────────────────────────────────────────────────
+
+interface DeployCompileInput {
+  /** Adapter target. Only `vercel` is supported in M3. */
+  target?: "vercel";
+  /** Project name override (Mandu bookkeeping; not emitted into output). */
+  project_name?: string;
+}
+
+interface DeployCompileResultPayload {
+  target: "vercel";
+  /** Concrete vercel.json contents the adapter would write. */
+  config: VercelCompileResult["config"];
+  /** Compile warnings (e.g. #248 runtime gaps). */
+  warnings: string[];
+  /** Per-route summary the CLI prints in dry-run. */
+  per_route: VercelCompileResult["perRoute"];
+}
+
+async function deployCompileHandler(
+  projectRoot: string,
+  input: DeployCompileInput,
+): Promise<DeployCompileResultPayload | { error: string; hint?: string; routes?: ReadonlyArray<{ route_id: string; reason: string }> }> {
+  const target = input.target ?? "vercel";
+  if (target !== "vercel") {
+    return {
+      error: `Target "${target}" not supported yet. Phase 1 ships the Vercel compiler only.`,
+      hint: "Pass target=\"vercel\" or wait for the Fly compiler in Phase 2.",
+    };
+  }
+
+  const { manifest, error: manifestError } = await resolveManifestForTooling(projectRoot);
+  if (!manifest) {
+    return {
+      error: `Routes manifest could not be resolved: ${manifestError ?? "unknown reason"}`,
+      hint: "Run `mandu build` (or ensure `app/` exists with at least one route) before calling deploy tools.",
+    };
+  }
+
+  let cache: DeployIntentCache;
+  try {
+    cache = await loadDeployIntentCache(projectRoot);
+  } catch (err) {
+    return {
+      error: `Failed to load .mandu/deploy.intent.json: ${err instanceof Error ? err.message : String(err)}`,
+      hint: "Run `mandu.deploy.plan` (with apply=true) first, then re-run `mandu.deploy.compile`.",
+    };
+  }
+  if (Object.keys(cache.intents).length === 0) {
+    cache = emptyDeployIntentCache();
+    return {
+      error: "Intent cache is empty",
+      hint: "Run `mandu.deploy.plan` with apply=true to populate .mandu/deploy.intent.json first.",
+    };
+  }
+
+  const projectName = input.project_name ?? deriveProjectName(projectRoot);
+  try {
+    const result = compileVercelJson(manifest, cache, { projectName });
+    return {
+      target: "vercel",
+      config: result.config,
+      warnings: result.warnings,
+      per_route: result.perRoute,
+    };
+  } catch (err) {
+    if (err instanceof VercelCompileError) {
+      return {
+        error: "Vercel compile failed",
+        hint: "Resolve the per-route reasons below — usually by re-running `mandu.deploy.plan` with apply=true after editing the offending route.",
+        routes: err.routes.map((r) => ({ route_id: r.routeId, reason: r.reason })),
+      };
+    }
+    throw err;
+  }
+}
+
+function deriveProjectName(projectRoot: string): string {
+  // Mirror the CLI's default — last path segment, sanitised.
+  const last = projectRoot.split(/[\\/]/).filter(Boolean).pop() ?? "mandu-project";
+  return last.toLowerCase().replace(/[^a-z0-9-_]/g, "-").slice(0, 100);
+}
+
+// ─── MCP definitions + handlers ───────────────────────────────────────
+
+export const deployPlanToolDefinitions: Tool[] = [
+  {
+    name: "mandu.deploy.plan",
+    description:
+      "Infer DeployIntent for every route via the offline heuristic and (optionally) write `.mandu/deploy.intent.json`. Returns the per-route diff plus validation warnings. Default `apply: false` is read-only — agents should review before persisting. The `reinfer` flag forces re-inference even on unchanged source hashes.",
+    annotations: {
+      readOnlyHint: false,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        apply: {
+          type: "boolean",
+          description:
+            "When true, atomically write the next cache to `.mandu/deploy.intent.json`. Default false (preview-only).",
+        },
+        reinfer: {
+          type: "boolean",
+          description: "Force re-inference even on unchanged source hashes.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu.deploy.compile",
+    description:
+      "Compile the routes manifest + `.mandu/deploy.intent.json` into a concrete `vercel.json`. Returns the config object, per-route summary, and compile warnings (e.g. runtime gaps from issue #248). Read-only — does not write vercel.json. Phase 1 supports `target: \"vercel\"` only.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          enum: ["vercel"],
+          description: "Adapter target. Phase 1 supports vercel only.",
+        },
+        project_name: {
+          type: "string",
+          description:
+            "Project name override (Mandu bookkeeping; never emitted into vercel.json). Defaults to the directory name.",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function deployPlanTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.deploy.plan": async (args) =>
+      deployPlanHandler(projectRoot, args as DeployPlanInput),
+    "mandu.deploy.compile": async (args) =>
+      deployCompileHandler(projectRoot, args as DeployCompileInput),
+  };
+  return handlers;
+}

package/src/tools/index.ts

@@ -63,6 +63,7 @@ export { compositeTools, compositeToolDefinitions } from "./composite.js";
 // Phase 14.3 — AI/agent loop-closure tool suite
 export { runTestsTools, runTestsToolDefinitions } from "./run-tests.js";
 export { deployPreviewTools, deployPreviewToolDefinitions } from "./deploy-preview.js";
+export { deployPlanTools, deployPlanToolDefinitions } from "./deploy-plan.js";
 export { aiBriefTools, aiBriefToolDefinitions } from "./ai-brief.js";
 export { loopCloseTools, loopCloseToolDefinitions } from "./loop-close.js";
 // #243 — docs search/get for agents grounding answers in real framework docs
@@ -137,6 +138,7 @@ import { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
 import { compositeTools, compositeToolDefinitions } from "./composite.js";
 import { runTestsTools, runTestsToolDefinitions } from "./run-tests.js";
 import { deployPreviewTools, deployPreviewToolDefinitions } from "./deploy-preview.js";
+import { deployPlanTools, deployPlanToolDefinitions } from "./deploy-plan.js";
 import { aiBriefTools, aiBriefToolDefinitions } from "./ai-brief.js";
 import { loopCloseTools, loopCloseToolDefinitions } from "./loop-close.js";
 import { docsTools, docsToolDefinitions } from "./docs.js";
@@ -254,6 +256,8 @@ const TOOL_MODULES: ToolModule[] = [
   // Phase 14.3 — AI/agent loop-closure suite
   { category: "run-tests", definitions: runTestsToolDefinitions, handlers: runTestsTools },
   { category: "deploy-preview", definitions: deployPreviewToolDefinitions, handlers: deployPreviewTools },
+  // #250 — DeployIntent inspection / compile (Phase 1)
+  { category: "deploy-plan", definitions: deployPlanToolDefinitions, handlers: deployPlanTools },
   { category: "ai-brief", definitions: aiBriefToolDefinitions, handlers: aiBriefTools },
   { category: "loop-close", definitions: loopCloseToolDefinitions, handlers: loopCloseTools },
   { category: "docs", definitions: docsToolDefinitions, handlers: docsTools },