@mandujs/mcp 0.38.12 → 0.39.0-beta.1

package/src/tools/ate-exemplar.ts

@@ -1,92 +1,92 @@
-/**
- * `mandu_ate_exemplar` — Phase A.3 exemplar browser.
- *
- * See `docs/ate/roadmap-v2-agent-native.md` §4.3. Returns the
- * `@ate-exemplar:` tagged tests for a given kind so an agent can
- * few-shot against them without paying the "compose the whole prompt"
- * token cost.
- *
- * Snake_case tool name (§11 decision #4). Read-only.
- */
-
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { scanExemplars, type Exemplar } from "@mandujs/ate";
-
-export const ateExemplarToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_exemplar",
-    annotations: {
-      readOnlyHint: true,
-    },
-    description:
-      "Phase A.3 agent-native exemplar browser. Returns up to `limit` tests " +
-      "tagged with `@ate-exemplar: kind=<kind>` from the repo. Each entry " +
-      "carries the file path, start/end line, tags, and the full source of the " +
-      "test() / it() / describe() call that follows the tag. Set " +
-      "includeAnti:true to also surface `@ate-exemplar-anti:` (DO-NOT-do-this) " +
-      "cases. Exemplars are manually curated (roadmap §11 decision 2) — no " +
-      "auto-heuristic. Use this when you want few-shot examples without paying " +
-      "for the full composed prompt.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repoRoot: {
-          type: "string",
-          description: "Absolute path to the Mandu project root.",
-        },
-        kind: {
-          type: "string",
-          description:
-            "Match against the tag's `kind=` attribute. Examples: filling_unit, filling_integration, e2e_playwright.",
-        },
-        limit: {
-          type: "number",
-          description: "Max entries to return. Default 5.",
-        },
-        includeAnti: {
-          type: "boolean",
-          description:
-            "Also include @ate-exemplar-anti markers (default false — only positive exemplars).",
-        },
-      },
-      required: ["repoRoot", "kind"],
-    },
-  },
-];
-
-export function ateExemplarTools(_projectRoot: string) {
-  return {
-    mandu_ate_exemplar: async (args: Record<string, unknown>) => {
-      const repoRoot = args.repoRoot as string | undefined;
-      const kind = args.kind as string | undefined;
-      const limit = typeof args.limit === "number" ? args.limit : 5;
-      const includeAnti = args.includeAnti === true;
-
-      if (!repoRoot || typeof repoRoot !== "string") {
-        return { ok: false, error: "'repoRoot' is required" };
-      }
-      if (!kind || typeof kind !== "string") {
-        return { ok: false, error: "'kind' is required" };
-      }
-
-      try {
-        const all = await scanExemplars(repoRoot);
-        const filtered = all.filter((e) => e.kind === kind);
-        const selected: Exemplar[] = [];
-        const positives = filtered.filter((e) => !e.anti).slice(0, limit);
-        selected.push(...positives);
-        if (includeAnti) {
-          // Reserve up to half the limit for antis so positives aren't crowded out.
-          const antiBudget = Math.max(1, Math.floor(limit / 2));
-          const antis = filtered.filter((e) => e.anti).slice(0, antiBudget);
-          selected.push(...antis);
-        }
-
-        return { ok: true, exemplars: selected, total: filtered.length };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { ok: false, error: msg };
-      }
-    },
-  };
-}
+/**
+ * `mandu_ate_exemplar` — Phase A.3 exemplar browser.
+ *
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.3. Returns the
+ * `@ate-exemplar:` tagged tests for a given kind so an agent can
+ * few-shot against them without paying the "compose the whole prompt"
+ * token cost.
+ *
+ * Snake_case tool name (§11 decision #4). Read-only.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { scanExemplars, type Exemplar } from "@mandujs/ate";
+
+export const ateExemplarToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_exemplar",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.3 agent-native exemplar browser. Returns up to `limit` tests " +
+      "tagged with `@ate-exemplar: kind=<kind>` from the repo. Each entry " +
+      "carries the file path, start/end line, tags, and the full source of the " +
+      "test() / it() / describe() call that follows the tag. Set " +
+      "includeAnti:true to also surface `@ate-exemplar-anti:` (DO-NOT-do-this) " +
+      "cases. Exemplars are manually curated (roadmap §11 decision 2) — no " +
+      "auto-heuristic. Use this when you want few-shot examples without paying " +
+      "for the full composed prompt.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        kind: {
+          type: "string",
+          description:
+            "Match against the tag's `kind=` attribute. Examples: filling_unit, filling_integration, e2e_playwright.",
+        },
+        limit: {
+          type: "number",
+          description: "Max entries to return. Default 5.",
+        },
+        includeAnti: {
+          type: "boolean",
+          description:
+            "Also include @ate-exemplar-anti markers (default false — only positive exemplars).",
+        },
+      },
+      required: ["repoRoot", "kind"],
+    },
+  },
+];
+
+export function ateExemplarTools(_projectRoot: string) {
+  return {
+    mandu_ate_exemplar: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const kind = args.kind as string | undefined;
+      const limit = typeof args.limit === "number" ? args.limit : 5;
+      const includeAnti = args.includeAnti === true;
+
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "'repoRoot' is required" };
+      }
+      if (!kind || typeof kind !== "string") {
+        return { ok: false, error: "'kind' is required" };
+      }
+
+      try {
+        const all = await scanExemplars(repoRoot);
+        const filtered = all.filter((e) => e.kind === kind);
+        const selected: Exemplar[] = [];
+        const positives = filtered.filter((e) => !e.anti).slice(0, limit);
+        selected.push(...positives);
+        if (includeAnti) {
+          // Reserve up to half the limit for antis so positives aren't crowded out.
+          const antiBudget = Math.max(1, Math.floor(limit / 2));
+          const antis = filtered.filter((e) => e.anti).slice(0, antiBudget);
+          selected.push(...antis);
+        }
+
+        return { ok: true, exemplars: selected, total: filtered.length };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: msg };
+      }
+    },
+  };
+}

package/src/tools/ate-flakes.ts

@@ -1,90 +1,90 @@
-/**
- * `mandu_ate_flakes` — Phase A.2 flake detector surface.
- *
- * Returns every spec whose rolling pass/fail transition ratio exceeds
- * `minScore` (default 0.1) within the last `windowSize` runs
- * (default 20). Agents use this to prioritize stabilization work.
- *
- * Data source: `.mandu/ate-run-history.jsonl`, appended to by
- * `runSpec`. When no history is present we return an empty array —
- * not an error.
- *
- * Snake_case naming per §11 decision 4.
- */
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { summarizeFlakes } from "@mandujs/ate";
-
-export const ateFlakesToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_flakes",
-    annotations: {
-      readOnlyHint: true,
-    },
-    description:
-      "Phase A.2 flake detector. Reads `.mandu/ate-run-history.jsonl` and returns specs " +
-      "whose pass/fail status flips often within the rolling window. `flakeScore` = " +
-      "status_transitions / (N - 1) over last `windowSize` non-skipped runs. " +
-      "Pure-pass PPPPP = 0.0 (stable), pure-fail FFFFF = 0.0 (broken, NOT flaky), " +
-      "alternating PFPF = 1.0. Returns an empty list when history is empty or no spec " +
-      "clears `minScore`. Use this to prioritize which flaky tests to fix first — feed " +
-      "a specPath from the result into mandu_ate_run for a re-run + full failure.v1 " +
-      "diagnostic.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repoRoot: {
-          type: "string",
-          description: "Absolute path to the Mandu project root",
-        },
-        windowSize: {
-          type: "number",
-          minimum: 2,
-          description: "Rolling window size. Default: 20.",
-        },
-        minScore: {
-          type: "number",
-          minimum: 0,
-          maximum: 1,
-          description: "Filter threshold for flakeScore. Default: 0.1.",
-        },
-      },
-      required: ["repoRoot"],
-    },
-  },
-];
-
-export function ateFlakesTools(_projectRoot: string) {
-  return {
-    mandu_ate_flakes: async (args: Record<string, unknown>) => {
-      const { repoRoot, windowSize, minScore } = args as {
-        repoRoot: string;
-        windowSize?: number;
-        minScore?: number;
-      };
-      if (!repoRoot || typeof repoRoot !== "string") {
-        return { ok: false, error: "repoRoot is required" };
-      }
-      if (typeof windowSize === "number" && windowSize < 2) {
-        return { ok: false, error: "windowSize must be >= 2" };
-      }
-      if (
-        typeof minScore === "number" &&
-        (minScore < 0 || minScore > 1 || !Number.isFinite(minScore))
-      ) {
-        return { ok: false, error: "minScore must be in [0, 1]" };
-      }
-      try {
-        const flakyTests = summarizeFlakes(repoRoot, {
-          windowSize,
-          minScore,
-        });
-        return { ok: true, flakyTests };
-      } catch (err) {
-        return {
-          ok: false,
-          error: `summarizeFlakes failed: ${err instanceof Error ? err.message : String(err)}`,
-        };
-      }
-    },
-  };
-}
+/**
+ * `mandu_ate_flakes` — Phase A.2 flake detector surface.
+ *
+ * Returns every spec whose rolling pass/fail transition ratio exceeds
+ * `minScore` (default 0.1) within the last `windowSize` runs
+ * (default 20). Agents use this to prioritize stabilization work.
+ *
+ * Data source: `.mandu/ate-run-history.jsonl`, appended to by
+ * `runSpec`. When no history is present we return an empty array —
+ * not an error.
+ *
+ * Snake_case naming per §11 decision 4.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { summarizeFlakes } from "@mandujs/ate";
+
+export const ateFlakesToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_flakes",
+    annotations: {
+      readOnlyHint: true,
+    },
+    description:
+      "Phase A.2 flake detector. Reads `.mandu/ate-run-history.jsonl` and returns specs " +
+      "whose pass/fail status flips often within the rolling window. `flakeScore` = " +
+      "status_transitions / (N - 1) over last `windowSize` non-skipped runs. " +
+      "Pure-pass PPPPP = 0.0 (stable), pure-fail FFFFF = 0.0 (broken, NOT flaky), " +
+      "alternating PFPF = 1.0. Returns an empty list when history is empty or no spec " +
+      "clears `minScore`. Use this to prioritize which flaky tests to fix first — feed " +
+      "a specPath from the result into mandu_ate_run for a re-run + full failure.v1 " +
+      "diagnostic.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root",
+        },
+        windowSize: {
+          type: "number",
+          minimum: 2,
+          description: "Rolling window size. Default: 20.",
+        },
+        minScore: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Filter threshold for flakeScore. Default: 0.1.",
+        },
+      },
+      required: ["repoRoot"],
+    },
+  },
+];
+
+export function ateFlakesTools(_projectRoot: string) {
+  return {
+    mandu_ate_flakes: async (args: Record<string, unknown>) => {
+      const { repoRoot, windowSize, minScore } = args as {
+        repoRoot: string;
+        windowSize?: number;
+        minScore?: number;
+      };
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (typeof windowSize === "number" && windowSize < 2) {
+        return { ok: false, error: "windowSize must be >= 2" };
+      }
+      if (
+        typeof minScore === "number" &&
+        (minScore < 0 || minScore > 1 || !Number.isFinite(minScore))
+      ) {
+        return { ok: false, error: "minScore must be in [0, 1]" };
+      }
+      try {
+        const flakyTests = summarizeFlakes(repoRoot, {
+          windowSize,
+          minScore,
+        });
+        return { ok: true, flakyTests };
+      } catch (err) {
+        return {
+          ok: false,
+          error: `summarizeFlakes failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
+    },
+  };
+}

package/src/tools/ate-mutate.ts

@@ -1,103 +1,103 @@
-/**
- * `mandu_ate_mutate` — Phase C.2 contract-semantic mutation runner.
- *
- * Runs up to 9 mutation operators on a single target file and executes
- * the repo's test command against each mutation. Classifies results as
- * killed / survived / timeout / error and persists
- * `.mandu/ate-mutations/last-run.json` for `mandu_ate_mutation_report`.
- *
- * Spec: docs/ate/phase-c-spec.md §C.2.
- */
-
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { runMutations } from "@mandujs/ate";
-
-export const ateMutateToolDefinitions: Tool[] = [
-  {
-    name: "mandu_ate_mutate",
-    annotations: {
-      readOnlyHint: false,
-    },
-    description:
-      "Phase C.2 — run contract-semantic mutation testing on a target file. " +
-      "9 operators: remove_required_field, narrow_type, widen_enum, flip_nullable, " +
-      "rename_field, swap_sibling_type, skip_middleware, early_return, bypass_validation. " +
-      "Each mutation is written to the target file, the repo's test command runs " +
-      "against it, and the result is classified killed / survived / timeout / error. " +
-      "Default cap 50 mutations per invocation; pass `--all` or maxMutations to lift. " +
-      "The original file is always restored. Persists .mandu/ate-mutations/last-run.json.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        repoRoot: {
-          type: "string",
-          description: "Absolute path to the Mandu project root.",
-        },
-        targetFile: {
-          type: "string",
-          description:
-            "Absolute or repo-relative path to the file to mutate (contract, handler, or filling).",
-        },
-        testCommand: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Optional override for the test command (argv form). Default: resolved from spec-indexer.",
-        },
-        timeoutMs: {
-          type: "number",
-          description: "Per-mutation timeout in ms. Default 120000.",
-        },
-        maxMutations: {
-          type: "number",
-          description: "Cap on the number of mutations executed. Default 50.",
-        },
-        operators: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Optional subset of operator names. Default = all 9. Pass [] to skip execution.",
-        },
-      },
-      required: ["repoRoot", "targetFile"],
-    },
-  },
-];
-
-export function ateMutateTools(_projectRoot: string) {
-  return {
-    mandu_ate_mutate: async (args: Record<string, unknown>) => {
-      const repoRoot = args.repoRoot as string | undefined;
-      const targetFile = args.targetFile as string | undefined;
-      if (!repoRoot || typeof repoRoot !== "string") {
-        return { ok: false, error: "repoRoot is required" };
-      }
-      if (!targetFile || typeof targetFile !== "string") {
-        return { ok: false, error: "targetFile is required" };
-      }
-      try {
-        const result = await runMutations({
-          repoRoot,
-          targetFile,
-          ...(Array.isArray(args.testCommand) ? { testCommand: args.testCommand as string[] } : {}),
-          ...(typeof args.timeoutMs === "number" ? { timeoutMs: args.timeoutMs } : {}),
-          ...(typeof args.maxMutations === "number" ? { maxMutations: args.maxMutations } : {}),
-          ...(Array.isArray(args.operators) ? { operators: args.operators as never } : {}),
-        });
-        return {
-          ok: true,
-          targetFile: result.targetFile,
-          totalGenerated: result.totalGenerated,
-          totalExecuted: result.totalExecuted,
-          reportPath: result.reportPath,
-          results: result.results,
-        };
-      } catch (err) {
-        return {
-          ok: false,
-          error: err instanceof Error ? err.message : String(err),
-        };
-      }
-    },
-  };
-}
+/**
+ * `mandu_ate_mutate` — Phase C.2 contract-semantic mutation runner.
+ *
+ * Runs up to 9 mutation operators on a single target file and executes
+ * the repo's test command against each mutation. Classifies results as
+ * killed / survived / timeout / error and persists
+ * `.mandu/ate-mutations/last-run.json` for `mandu_ate_mutation_report`.
+ *
+ * Spec: docs/ate/phase-c-spec.md §C.2.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { runMutations } from "@mandujs/ate";
+
+export const ateMutateToolDefinitions: Tool[] = [
+  {
+    name: "mandu_ate_mutate",
+    annotations: {
+      readOnlyHint: false,
+    },
+    description:
+      "Phase C.2 — run contract-semantic mutation testing on a target file. " +
+      "9 operators: remove_required_field, narrow_type, widen_enum, flip_nullable, " +
+      "rename_field, swap_sibling_type, skip_middleware, early_return, bypass_validation. " +
+      "Each mutation is written to the target file, the repo's test command runs " +
+      "against it, and the result is classified killed / survived / timeout / error. " +
+      "Default cap 50 mutations per invocation; pass `--all` or maxMutations to lift. " +
+      "The original file is always restored. Persists .mandu/ate-mutations/last-run.json.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repoRoot: {
+          type: "string",
+          description: "Absolute path to the Mandu project root.",
+        },
+        targetFile: {
+          type: "string",
+          description:
+            "Absolute or repo-relative path to the file to mutate (contract, handler, or filling).",
+        },
+        testCommand: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional override for the test command (argv form). Default: resolved from spec-indexer.",
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Per-mutation timeout in ms. Default 120000.",
+        },
+        maxMutations: {
+          type: "number",
+          description: "Cap on the number of mutations executed. Default 50.",
+        },
+        operators: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional subset of operator names. Default = all 9. Pass [] to skip execution.",
+        },
+      },
+      required: ["repoRoot", "targetFile"],
+    },
+  },
+];
+
+export function ateMutateTools(_projectRoot: string) {
+  return {
+    mandu_ate_mutate: async (args: Record<string, unknown>) => {
+      const repoRoot = args.repoRoot as string | undefined;
+      const targetFile = args.targetFile as string | undefined;
+      if (!repoRoot || typeof repoRoot !== "string") {
+        return { ok: false, error: "repoRoot is required" };
+      }
+      if (!targetFile || typeof targetFile !== "string") {
+        return { ok: false, error: "targetFile is required" };
+      }
+      try {
+        const result = await runMutations({
+          repoRoot,
+          targetFile,
+          ...(Array.isArray(args.testCommand) ? { testCommand: args.testCommand as string[] } : {}),
+          ...(typeof args.timeoutMs === "number" ? { timeoutMs: args.timeoutMs } : {}),
+          ...(typeof args.maxMutations === "number" ? { maxMutations: args.maxMutations } : {}),
+          ...(Array.isArray(args.operators) ? { operators: args.operators as never } : {}),
+        });
+        return {
+          ok: true,
+          targetFile: result.targetFile,
+          totalGenerated: result.totalGenerated,
+          totalExecuted: result.totalExecuted,
+          reportPath: result.reportPath,
+          results: result.results,
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+  };
+}