@mandujs/mcp 0.19.6 → 0.20.0

package/src/tools/deploy-preview.ts

@@ -0,0 +1,316 @@
+/**
+ * MCP tool — `mandu.deploy.preview`
+ *
+ * Invokes `mandu deploy --target=<target> --dry-run` in a child process
+ * and parses the stdout into a structured artifact list.
+ *
+ * Safety:
+ *   • `--dry-run` is *always* passed. The tool cannot be coerced into
+ *     triggering a real deployment.
+ *   • Target is validated against the known adapter list; unknown values
+ *     fail fast without spawning a process.
+ *   • The child has a 5-minute ceiling; it's killed if it overruns.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { spawn } from "bun";
+import path from "path";
+
+// Mirror the adapter list from `packages/cli/src/commands/deploy/types.ts`.
+// Keep this in sync manually — imports from @mandujs/cli would introduce a
+// cross-package coupling for a single string-union.
+const DEPLOY_TARGETS = [
+  "docker",
+  "fly",
+  "vercel",
+  "railway",
+  "netlify",
+  "cf-pages",
+  "docker-compose",
+] as const;
+type DeployTarget = (typeof DEPLOY_TARGETS)[number];
+const VALID_TARGET_SET = new Set<string>(DEPLOY_TARGETS);
+
+interface DeployPreviewInput {
+  target?: string;
+}
+
+interface ArtifactEntry {
+  path: string;
+  preserved: boolean;
+  description?: string;
+}
+
+interface DeployPreviewResult {
+  target: DeployTarget;
+  mode: "dry-run";
+  artifact_list: ArtifactEntry[];
+  warnings: string[];
+  /** Text diff extracted from the preview output, if present. */
+  diff?: string;
+  exit_code: number;
+  /** Trailing 2000 chars of stdout for diagnostic context. */
+  stdout_tail?: string;
+  /** Trailing 2000 chars of stderr for diagnostic context. */
+  stderr_tail?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Input validation
+// ─────────────────────────────────────────────────────────────────────────
+
+const COMMAND_TIMEOUT_MS = 5 * 60_000;
+
+function validateInput(raw: Record<string, unknown>): {
+  ok: true;
+  target: DeployTarget;
+} | { ok: false; error: string; field: string; hint: string } {
+  const target = raw.target;
+  if (typeof target !== "string" || target.length === 0) {
+    return {
+      ok: false,
+      error: "'target' is required",
+      field: "target",
+      hint: `Pass one of: ${DEPLOY_TARGETS.join(", ")}`,
+    };
+  }
+  if (!VALID_TARGET_SET.has(target)) {
+    return {
+      ok: false,
+      error: `Unknown deploy target: ${target}`,
+      field: "target",
+      hint: `Supported: ${DEPLOY_TARGETS.join(", ")}`,
+    };
+  }
+  return { ok: true, target: target as DeployTarget };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Output parsing
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse the CLI's artifact-rendering block:
+ *
+ *   📦 Adapter prepare: docker
+ *     + .mandu/deploy/docker/Dockerfile — production image
+ *     • .mandu/deploy/docker/.dockerignore
+ *     + .mandu/deploy/docker/entrypoint.sh
+ *
+ * Returns `preserved=true` for `•` (existing) and `false` for `+` (new).
+ */
+export function parseDeployPreviewOutput(raw: string): {
+  artifacts: ArtifactEntry[];
+  warnings: string[];
+  diff?: string;
+} {
+  const lines = raw.split(/\r?\n/);
+  const artifacts: ArtifactEntry[] = [];
+  const warnings: string[] = [];
+  const diffLines: string[] = [];
+
+  let inDiff = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\r$/, "");
+    const trimmed = line.trim();
+
+    // Diff mode gates the other regexes: inside a fenced block we don't
+    // re-interpret `+` / `•` as artifact markers.
+    if (inDiff) {
+      if (/^```$/.test(trimmed)) {
+        inDiff = false;
+      } else {
+        diffLines.push(line);
+      }
+      continue;
+    }
+
+    if (!trimmed) continue;
+
+    // Opening of a diff block: triple-backtick (optionally language-tagged)
+    // or an unfenced `diff --git` header.
+    if (/^```\S*$/.test(trimmed)) {
+      inDiff = true;
+      continue;
+    }
+    if (/^diff\s+--git\s/.test(trimmed)) {
+      inDiff = true;
+      diffLines.push(trimmed);
+      continue;
+    }
+
+    // Artifact: prefix `+` or `•` after leading whitespace.
+    const artifactMatch = /^([+•])\s+(.+)$/.exec(trimmed);
+    if (artifactMatch) {
+      const marker = artifactMatch[1];
+      const rest = artifactMatch[2];
+      const emDashIdx = rest.indexOf(" — ");
+      const p = emDashIdx >= 0 ? rest.slice(0, emDashIdx).trim() : rest.trim();
+      const desc = emDashIdx >= 0 ? rest.slice(emDashIdx + 3).trim() : undefined;
+      artifacts.push({
+        path: p,
+        preserved: marker === "•",
+        ...(desc ? { description: desc } : {}),
+      });
+      continue;
+    }
+
+    // Warning: lines that start with ⚠️ or "Warning:"
+    if (/^\s*(?:⚠️|warning:)/i.test(trimmed)) {
+      warnings.push(trimmed.replace(/^⚠️\s*/u, "").replace(/^warning:\s*/i, "").trim());
+      continue;
+    }
+  }
+
+  const result: { artifacts: ArtifactEntry[]; warnings: string[]; diff?: string } = {
+    artifacts,
+    warnings,
+  };
+  if (diffLines.length > 0) {
+    result.diff = diffLines.join("\n").trim();
+  }
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Child process invocation
+// ─────────────────────────────────────────────────────────────────────────
+
+function tailString(s: string, max = 2000): string {
+  if (s.length <= max) return s;
+  return s.slice(-max);
+}
+
+async function resolveManduCommand(projectRoot: string): Promise<string[]> {
+  const localBin = path.join(projectRoot, "node_modules", ".bin", "mandu");
+  try {
+    const f = Bun.file(localBin);
+    if (await f.exists()) {
+      return ["bun", "run", localBin];
+    }
+  } catch {}
+
+  const monorepoCli = path.resolve(projectRoot, "packages", "cli", "src", "main.ts");
+  try {
+    const f = Bun.file(monorepoCli);
+    if (await f.exists()) {
+      return ["bun", "run", monorepoCli];
+    }
+  } catch {}
+
+  return ["mandu"];
+}
+
+async function runProcess(
+  cmd: string[],
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
+  const proc = spawn(cmd, {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  let timedOut = false;
+  const handle = setTimeout(() => {
+    timedOut = true;
+    try {
+      proc.kill();
+    } catch {}
+  }, timeoutMs);
+
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    return { stdout, stderr, exitCode: exitCode ?? 1, timedOut };
+  } finally {
+    clearTimeout(handle);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Handler
+// ─────────────────────────────────────────────────────────────────────────
+
+async function deployPreview(
+  projectRoot: string,
+  input: DeployPreviewInput,
+): Promise<DeployPreviewResult | { error: string; field?: string; hint?: string }> {
+  const validated = validateInput(input as Record<string, unknown>);
+  if (!validated.ok) {
+    return {
+      error: validated.error,
+      field: validated.field,
+      hint: validated.hint,
+    };
+  }
+
+  const { target } = validated;
+  const base = await resolveManduCommand(projectRoot);
+  const cmd = [...base, "deploy", `--target=${target}`, "--dry-run"];
+
+  let proc: { stdout: string; stderr: string; exitCode: number; timedOut: boolean };
+  try {
+    proc = await runProcess(cmd, projectRoot, COMMAND_TIMEOUT_MS);
+  } catch (err) {
+    return {
+      error: `Failed to spawn deploy preview: ${err instanceof Error ? err.message : String(err)}`,
+      hint: "Verify that @mandujs/cli is installed and accessible",
+    };
+  }
+
+  const parsed = parseDeployPreviewOutput(`${proc.stdout}\n${proc.stderr}`);
+
+  const result: DeployPreviewResult = {
+    target,
+    mode: "dry-run",
+    artifact_list: parsed.artifacts,
+    warnings: parsed.warnings,
+    exit_code: proc.exitCode,
+    stdout_tail: tailString(proc.stdout),
+    stderr_tail: tailString(proc.stderr),
+  };
+  if (parsed.diff) result.diff = parsed.diff;
+  if (proc.timedOut) result.warnings.push("deploy preview timed out");
+  return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// MCP tool definition + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const deployPreviewToolDefinitions: Tool[] = [
+  {
+    name: "mandu.deploy.preview",
+    description:
+      "Preview a deployment by running `mandu deploy --target=<t> --dry-run`. Returns the structured artifact list, parsed warnings, and any diff the adapter emits. Always dry-run — this tool cannot trigger a real deployment.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          enum: [...DEPLOY_TARGETS],
+          description:
+            "Deployment adapter target. Each adapter controls the artifact set — see `mandu deploy --help` for details.",
+        },
+      },
+      required: ["target"],
+    },
+  },
+];
+
+export function deployPreviewTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.deploy.preview": async (args) =>
+      deployPreview(projectRoot, args as DeployPreviewInput),
+  };
+  return handlers;
+}

package/src/tools/index.ts

@@ -32,6 +32,11 @@ export { resourceTools, resourceToolDefinitions } from "./resource.js";
 export { componentTools, componentToolDefinitions } from "./component.js";
 export { kitchenTools, kitchenToolDefinitions } from "./kitchen.js";
 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 { aiBriefTools, aiBriefToolDefinitions } from "./ai-brief.js";
+export { loopCloseTools, loopCloseToolDefinitions } from "./loop-close.js";
 
 // 도구 모듈 import (등록용)
 import { specTools, specToolDefinitions } from "./spec.js";
@@ -54,6 +59,10 @@ import { resourceTools, resourceToolDefinitions } from "./resource.js";
 import { componentTools, componentToolDefinitions } from "./component.js";
 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 { aiBriefTools, aiBriefToolDefinitions } from "./ai-brief.js";
+import { loopCloseTools, loopCloseToolDefinitions } from "./loop-close.js";
 
 /**
  * 도구 모듈 정보
@@ -94,6 +103,11 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "component", definitions: componentToolDefinitions, handlers: componentTools },
   { category: "kitchen", definitions: kitchenToolDefinitions, handlers: kitchenTools },
   { category: "composite", definitions: compositeToolDefinitions, handlers: compositeTools },
+  // Phase 14.3 — AI/agent loop-closure suite
+  { category: "run-tests", definitions: runTestsToolDefinitions, handlers: runTestsTools },
+  { category: "deploy-preview", definitions: deployPreviewToolDefinitions, handlers: deployPreviewTools },
+  { category: "ai-brief", definitions: aiBriefToolDefinitions, handlers: aiBriefTools },
+  { category: "loop-close", definitions: loopCloseToolDefinitions, handlers: loopCloseTools },
 ];
 
 /**

package/src/tools/loop-close.ts

@@ -0,0 +1,175 @@
+/**
+ * MCP tool — `mandu.loop.close`
+ *
+ * Thin, safe adapter over `@mandujs/skills/loop-closure`. Given agent
+ * output (stdout, stderr, exitCode), runs the built-in loop-closure
+ * detectors and returns a structured follow-up prompt:
+ *
+ *   {
+ *     stallReason: string,
+ *     nextPrompt: string,
+ *     evidence: Array<{ kind, file?, line?, snippet, label? }>
+ *   }
+ *
+ * SAFETY INVARIANTS — enforced by design:
+ *   - `closeLoop()` is pure: no I/O, no spawn, no file writes.
+ *   - This wrapper adds only input validation + field shaping.
+ *   - The `nextPrompt` is ADVISORY text. It is never auto-executed.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { closeLoop, listDetectorIds } from "@mandujs/skills/loop-closure";
+
+interface LoopCloseInput {
+  stdout?: unknown;
+  stderr?: unknown;
+  exitCode?: unknown;
+  detectors?: unknown;
+}
+
+function validateInput(raw: Record<string, unknown>): {
+  ok: true;
+  value: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    detectors?: string[];
+  };
+} | { ok: false; error: string; field: string; hint: string } {
+  const stdout = raw.stdout ?? "";
+  if (typeof stdout !== "string") {
+    return {
+      ok: false,
+      error: "'stdout' must be a string",
+      field: "stdout",
+      hint: "Omit or pass '' for no stdout",
+    };
+  }
+
+  const stderr = raw.stderr ?? "";
+  if (typeof stderr !== "string") {
+    return {
+      ok: false,
+      error: "'stderr' must be a string",
+      field: "stderr",
+      hint: "Omit or pass '' for no stderr",
+    };
+  }
+
+  let exitCode = 0;
+  if (raw.exitCode !== undefined) {
+    if (typeof raw.exitCode !== "number" || !Number.isFinite(raw.exitCode)) {
+      return {
+        ok: false,
+        error: "'exitCode' must be a finite number",
+        field: "exitCode",
+        hint: "Pass the child-process exit code, typically 0 (success) or non-zero (failure)",
+      };
+    }
+    exitCode = Math.trunc(raw.exitCode);
+  }
+
+  let detectors: string[] | undefined;
+  if (raw.detectors !== undefined) {
+    if (!Array.isArray(raw.detectors) ||
+        !raw.detectors.every((d) => typeof d === "string")) {
+      return {
+        ok: false,
+        error: "'detectors' must be an array of detector IDs",
+        field: "detectors",
+        hint: `Valid IDs: ${listDetectorIds().join(", ")}`,
+      };
+    }
+    detectors = raw.detectors as string[];
+  }
+
+  return {
+    ok: true,
+    value: { stdout, stderr, exitCode, ...(detectors ? { detectors } : {}) },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Handler
+// ─────────────────────────────────────────────────────────────────────────
+
+async function runLoopClose(
+  input: LoopCloseInput,
+): Promise<
+  | {
+      stallReason: string;
+      nextPrompt: string;
+      evidence: Array<{
+        kind: string;
+        file?: string;
+        line?: number;
+        snippet: string;
+        label?: string;
+      }>;
+      detectors_run: string[];
+    }
+  | { error: string; field?: string; hint?: string }
+> {
+  const validated = validateInput(input as Record<string, unknown>);
+  if (!validated.ok) {
+    return {
+      error: validated.error,
+      field: validated.field,
+      hint: validated.hint,
+    };
+  }
+
+  const report = closeLoop(validated.value);
+  return {
+    stallReason: report.stallReason,
+    nextPrompt: report.nextPrompt,
+    evidence: report.evidence,
+    detectors_run: validated.value.detectors ?? listDetectorIds(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Tool definition + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const loopCloseToolDefinitions: Tool[] = [
+  {
+    name: "mandu.loop.close",
+    description:
+      "Analyze agent output (stdout, stderr, exitCode) and return a structured `nextPrompt` that names the primary stall pattern, explains how to address it, and lists supporting evidence. This tool is pure — it never writes files, spawns processes, or auto-executes anything. The returned prompt is advisory text only.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        stdout: {
+          type: "string",
+          description: "Captured stdout from the most recent command/run.",
+        },
+        stderr: {
+          type: "string",
+          description: "Captured stderr from the most recent command/run.",
+        },
+        exitCode: {
+          type: "number",
+          description: "Child-process exit code. Defaults to 0 when omitted.",
+        },
+        detectors: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional detector-ID allow-list. Omit to run the full built-in set.",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function loopCloseTools(_projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.loop.close": async (args) => runLoopClose(args as LoopCloseInput),
+  };
+  return handlers;
+}