@mandujs/mcp 0.30.0 → 0.32.0

package/src/tools/guard.ts

@@ -10,6 +10,8 @@ import {
   applyHealing,
   healAll,
   explainRule,
+  // Follow-up E — type-aware lint bridge
+  runTsgolint,
   type GuardConfig,
   type ViolationType,
   type GuardPreset,
@@ -20,7 +22,7 @@ export const guardToolDefinitions: Tool[] = [
   {
     name: "mandu.guard.check",
     description:
-      "Run guard checks to validate spec integrity, generated files, and slot files",
+      "Run guard checks to validate spec integrity, generated files, and slot files. Set typeAware=true to additionally run `oxlint --type-aware` (tsgolint) and merge its results.",
     annotations: {
       readOnlyHint: true,
     },
@@ -31,6 +33,11 @@ export const guardToolDefinitions: Tool[] = [
           type: "boolean",
           description: "If true, attempt to automatically fix violations",
         },
+        typeAware: {
+          type: "boolean",
+          description:
+            "If true, invoke `oxlint --type-aware` after the architecture check and include its violations in the response under `typeAware`. When the config has `guard.typeAware` set, this defaults to true; set false to opt out for a single call.",
+        },
       },
       required: [],
     },
@@ -119,7 +126,10 @@ export function guardTools(projectRoot: string) {
 
   const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
     "mandu.guard.check": async (args: Record<string, unknown>) => {
-      const { autoCorrect = false } = args as { autoCorrect?: boolean };
+      const { autoCorrect = false, typeAware: typeAwareArg } = args as {
+        autoCorrect?: boolean;
+        typeAware?: boolean;
+      };
 
       // Load manifest
       const manifestResult = await loadManifest(paths.manifestPath);
@@ -133,12 +143,53 @@ export function guardTools(projectRoot: string) {
       // Run guard check
       const checkResult = await runGuardCheck(manifestResult.data, projectRoot);
 
+      // Follow-up E — resolve type-aware defaulting from config, then
+      // run the bridge when enabled. Result envelope is always included
+      // in the tool response so MCP clients have a single stable shape.
+      let projectConfig: Awaited<ReturnType<typeof readConfig>> | undefined;
+      try {
+        projectConfig = await readConfig(projectRoot);
+      } catch {
+        projectConfig = undefined;
+      }
+      const typeAwareCfg = (
+        projectConfig?.guard as
+          | { typeAware?: Record<string, unknown> }
+          | undefined
+      )?.typeAware;
+      const typeAwareEnabled =
+        typeAwareArg !== undefined ? typeAwareArg : typeAwareCfg !== undefined;
+
+      let typeAwareResponse: Record<string, unknown> | undefined;
+      if (typeAwareEnabled) {
+        const bridge = await runTsgolint({
+          projectRoot,
+          rules: typeAwareCfg?.rules as string[] | undefined,
+          severity: typeAwareCfg?.severity as
+            | "off"
+            | "warn"
+            | "error"
+            | undefined,
+          configPath: typeAwareCfg?.configPath as string | undefined,
+        });
+        typeAwareResponse = {
+          skipped: bridge.skipped,
+          summary: bridge.summary,
+          violations: bridge.violations,
+        };
+      }
+
       if (checkResult.passed) {
         return {
-          passed: true,
+          passed: typeAwareResponse
+            ? (typeAwareResponse.violations as Array<{ severity: string }>).filter(
+                (v) => v.severity === "error",
+              ).length === 0
+            : true,
           violations: [],
           message: "All guard checks passed",
           relatedSkills: ["mandu-guard-guide", "mandu-debug"],
+          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
         };
       }
 
@@ -161,6 +212,7 @@ export function guardTools(projectRoot: string) {
             rolledBack: autoCorrectResult.rolledBack,
             changeId: autoCorrectResult.changeId,
           },
+          ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
         };
       }
 
@@ -175,6 +227,7 @@ export function guardTools(projectRoot: string) {
         message: `Found ${checkResult.violations.length} violation(s)`,
         tip: "Use autoCorrect: true to attempt automatic fixes",
         relatedSkills: ["mandu-guard-guide", "mandu-debug"],
+        ...(typeAwareResponse ? { typeAware: typeAwareResponse } : {}),
       };
     },
 

package/src/tools/index.ts

@@ -65,6 +65,10 @@ 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";
+// #243 — docs search/get for agents grounding answers in real framework docs
+export { docsTools, docsToolDefinitions } from "./docs.js";
+// #240 guardrail-default — lint run + setup for existing projects
+export { lintTools, lintToolDefinitions } from "./lint.js";
 // Phase 18.ι — AI refactor MCP tools
 export {
   rewriteGeneratedBarrelTools,
@@ -135,6 +139,8 @@ 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";
+import { docsTools, docsToolDefinitions } from "./docs.js";
+import { lintTools, lintToolDefinitions } from "./lint.js";
 // Phase 18.ι — AI refactor MCP tools
 import {
   rewriteGeneratedBarrelTools,
@@ -250,6 +256,8 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "deploy-preview", definitions: deployPreviewToolDefinitions, handlers: deployPreviewTools },
   { category: "ai-brief", definitions: aiBriefToolDefinitions, handlers: aiBriefTools },
   { category: "loop-close", definitions: loopCloseToolDefinitions, handlers: loopCloseTools },
+  { category: "docs", definitions: docsToolDefinitions, handlers: docsTools },
+  { category: "lint", definitions: lintToolDefinitions, handlers: lintTools },
   // Phase 18.ι — AI refactor tools (destructive writes; dry-run by default)
   {
     category: "refactor-barrel",

package/src/tools/lint.ts

@@ -0,0 +1,226 @@
+/**
+ * MCP tools — `mandu.lint` + `mandu.lint.setup`
+ *
+ * Gives agents a first-class way to:
+ *   1. Run oxlint on a project and get structured error/warning counts
+ *      (read-only, no side effects).
+ *   2. One-shot install oxlint + scaffold `.oxlintrc.json` + wire
+ *      scripts on an existing project (destructive — writes files).
+ *
+ * The setup tool mirrors `mandu lint --setup`. We spawn the CLI as a
+ * subprocess rather than linking to the CLI source so MCP builds
+ * don't pull `packages/cli` into their import graph.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Shared helpers
+// ─────────────────────────────────────────────────────────────────────────
+
+async function oxlintAvailable(rootDir: string): Promise<boolean> {
+  const binName = process.platform === "win32" ? "oxlint.exe" : "oxlint";
+  const localBin = path.resolve(rootDir, "node_modules", ".bin", binName);
+  try {
+    await fs.access(localBin);
+    return true;
+  } catch {
+    // Not in local node_modules — probe PATH.
+  }
+  try {
+    const proc = Bun.spawn({
+      cmd: ["bun", "x", "oxlint", "--version"],
+      cwd: rootDir,
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+interface LintParsed {
+  errors: number;
+  warnings: number;
+  raw: string;
+  parseFailed: boolean;
+}
+
+async function runOxlintOnce(rootDir: string, typeAware: boolean): Promise<LintParsed> {
+  const cmd = typeAware
+    ? ["bun", "x", "oxlint", "--type-aware", "."]
+    : ["bun", "x", "oxlint", "."];
+  const proc = Bun.spawn({
+    cmd,
+    cwd: rootDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  await proc.exited;
+  const raw = stderr + stdout;
+  const match = raw.match(/Found (\d+) warnings? and (\d+) errors?/);
+  if (!match) {
+    return { errors: 0, warnings: 0, raw, parseFailed: true };
+  }
+  return {
+    errors: Number(match[2]),
+    warnings: Number(match[1]),
+    raw,
+    parseFailed: false,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// mandu.lint — run oxlint, return counts
+// ─────────────────────────────────────────────────────────────────────────
+
+interface LintInput {
+  typeAware?: unknown;
+}
+
+interface LintResult {
+  installed: boolean;
+  ran: boolean;
+  errors: number;
+  warnings: number;
+  passed: boolean;
+  hint?: string;
+  rawTail?: string;
+}
+
+async function handleLint(projectRoot: string, input: LintInput): Promise<LintResult> {
+  const typeAware = input.typeAware === true;
+  const installed = await oxlintAvailable(projectRoot);
+  if (!installed) {
+    return {
+      installed: false,
+      ran: false,
+      errors: 0,
+      warnings: 0,
+      passed: false,
+      hint:
+        "oxlint is not installed in this project. Call `mandu.lint.setup` or run `mandu lint --setup` in the shell to install + configure.",
+    };
+  }
+  const result = await runOxlintOnce(projectRoot, typeAware);
+  if (result.parseFailed) {
+    return {
+      installed: true,
+      ran: true,
+      errors: 0,
+      warnings: 0,
+      passed: false,
+      hint: "oxlint ran but output could not be parsed. See `rawTail` for the last 2 KB.",
+      rawTail: result.raw.slice(-2048),
+    };
+  }
+  return {
+    installed: true,
+    ran: true,
+    errors: result.errors,
+    warnings: result.warnings,
+    passed: result.errors === 0,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// mandu.lint.setup — install oxlint + wire scripts + baseline
+// ─────────────────────────────────────────────────────────────────────────
+
+interface LintSetupInput {
+  dryRun?: unknown;
+}
+
+interface LintSetupResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  dryRun: boolean;
+  hint?: string;
+}
+
+async function handleLintSetup(projectRoot: string, input: LintSetupInput): Promise<LintSetupResult> {
+  const dryRun = input.dryRun === true;
+  const args = ["run", "--cwd", projectRoot, "mandu", "lint", "--setup", "--yes"];
+  if (dryRun) args.push("--dry-run");
+  const proc = Bun.spawn({
+    cmd: ["bun", ...args],
+    cwd: projectRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  const ok = exitCode === 0;
+  return {
+    ok,
+    stdout,
+    stderr,
+    exitCode,
+    dryRun,
+    hint: ok
+      ? dryRun
+        ? "Dry-run completed. Re-run without `dryRun: true` to apply the changes."
+        : "Setup completed. Run `mandu.lint` to see the current baseline."
+      : "Setup command failed. See `stderr` for details. A frequent cause is `mandu` CLI not being installed — `bun add -D @mandujs/cli` in the project first.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// MCP tool definitions + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const lintToolDefinitions: Tool[] = [
+  {
+    name: "mandu.lint",
+    description:
+      "Run oxlint on the project and return structured error/warning counts. Read-only — never modifies files. Pass `typeAware: true` to also run `oxlint --type-aware` (requires `oxlint-tsgolint`). Agents should call this after edits as part of the guardrail chain alongside `mandu.guard.check` and `mandu.doctor`.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        typeAware: {
+          type: "boolean",
+          description:
+            "Run `oxlint --type-aware` in addition to the core pass (requires `oxlint-tsgolint`). Default false.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu.lint.setup",
+    description:
+      "Install oxlint into an existing project: copies `.oxlintrc.json`, wires `lint`/`lint:fix` scripts, adds `oxlint` devDep, runs `bun install`. Idempotent — re-running produces no additional changes. Destructive — writes files. Set `dryRun: true` to print the plan only.",
+    annotations: { readOnlyHint: false, destructiveHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        dryRun: {
+          type: "boolean",
+          description: "Print the plan without writing files. Default false.",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function lintTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.lint": async (args) => handleLint(projectRoot, args as LintInput),
+    "mandu.lint.setup": async (args) => handleLintSetup(projectRoot, args as LintSetupInput),
+  };
+  return handlers;
+}