@mandujs/mcp 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,146 @@
1
+ /**
2
+ * `mandu_ate_prompt` — Phase A.3 prompt catalog tool.
3
+ *
4
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.2 and §7 (A.3 extension
5
+ * "Pre-composed prompts") for the design.
6
+ *
7
+ * Semantics:
8
+ * - If `context` is provided, the handler composes the full prompt
9
+ * (template + matched exemplars + serialized context) and returns
10
+ * a single ready-to-send-to-LLM string.
11
+ * - If `context` is omitted, the handler returns the raw template body +
12
+ * sha256 + a peek at available exemplars — the agent composes.
13
+ *
14
+ * Snake_case tool name (§11 decision #4). Read-only.
15
+ */
16
+
17
+ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
18
+ import {
19
+ loadPrompt,
20
+ scanExemplars,
21
+ composePrompt,
22
+ type Exemplar,
23
+ } from "@mandujs/ate";
24
+
25
+ export const atePromptToolDefinitions: Tool[] = [
26
+ {
27
+ name: "mandu_ate_prompt",
28
+ annotations: {
29
+ readOnlyHint: true,
30
+ },
31
+ description:
32
+ "Phase A.3 agent-native prompt catalog. Returns the system prompt for a " +
33
+ "given test kind, with Mandu-specific primitives, anti-patterns, and the " +
34
+ "selector convention baked in. When `context` is passed, the handler " +
35
+ "also injects up-to-3 matching exemplars (tagged with @ate-exemplar:) " +
36
+ "plus the JSON context block and returns a fully composed, ready-to-" +
37
+ "send-to-LLM string. When `context` is omitted, the handler returns the " +
38
+ "raw template + the separate exemplar list so the agent can compose. " +
39
+ "Kinds available in v1: filling_unit, filling_integration, e2e_playwright. " +
40
+ "The returned sha256 is stable per-version and safe as a cache key.",
41
+ inputSchema: {
42
+ type: "object",
43
+ properties: {
44
+ repoRoot: {
45
+ type: "string",
46
+ description:
47
+ "Absolute path to the Mandu project root. Required when context is " +
48
+ "omitted so we can scan exemplars from the repo.",
49
+ },
50
+ kind: {
51
+ type: "string",
52
+ description:
53
+ "Prompt kind. v1 catalog: filling_unit | filling_integration | e2e_playwright.",
54
+ },
55
+ version: {
56
+ type: "number",
57
+ description:
58
+ "Pin to a specific template version. Defaults to the highest available.",
59
+ },
60
+ context: {
61
+ type: "object",
62
+ description:
63
+ "Optional semantic context (usually the output of mandu_ate_context). " +
64
+ "When present, the returned `prompt` is pre-composed.",
65
+ additionalProperties: true,
66
+ },
67
+ maxPositive: {
68
+ type: "number",
69
+ description: "Max positive exemplars to inject. Default 3.",
70
+ },
71
+ maxAnti: {
72
+ type: "number",
73
+ description: "Max anti-exemplars to inject. Default 1.",
74
+ },
75
+ },
76
+ required: ["kind"],
77
+ },
78
+ },
79
+ ];
80
+
81
+ export function atePromptTools(_projectRoot: string) {
82
+ return {
83
+ mandu_ate_prompt: async (args: Record<string, unknown>) => {
84
+ const kind = args.kind as string | undefined;
85
+ if (!kind || typeof kind !== "string") {
86
+ return { ok: false, error: "'kind' is required and must be a string" };
87
+ }
88
+
89
+ const version = typeof args.version === "number" ? args.version : undefined;
90
+ const repoRoot = typeof args.repoRoot === "string" ? args.repoRoot : undefined;
91
+ const context = args.context;
92
+ const maxPositive = typeof args.maxPositive === "number" ? args.maxPositive : undefined;
93
+ const maxAnti = typeof args.maxAnti === "number" ? args.maxAnti : undefined;
94
+
95
+ try {
96
+ // When context is given, return a pre-composed prompt.
97
+ if (context !== undefined) {
98
+ const composed = await composePrompt({
99
+ kind,
100
+ version,
101
+ context,
102
+ repoRoot,
103
+ ...(maxPositive !== undefined ? { maxPositive } : {}),
104
+ ...(maxAnti !== undefined ? { maxAnti } : {}),
105
+ });
106
+ return {
107
+ ok: true,
108
+ prompt: composed.prompt,
109
+ sha256: composed.sha256,
110
+ version: composed.version,
111
+ kind: composed.kind,
112
+ exemplarCount: composed.exemplarCount,
113
+ antiCount: composed.antiCount,
114
+ tokenEstimate: composed.tokenEstimate,
115
+ };
116
+ }
117
+
118
+ // Otherwise: raw template + exemplar peek so the agent composes.
119
+ const loaded = loadPrompt(kind, version);
120
+ let exemplars: Exemplar[] = [];
121
+ if (repoRoot) {
122
+ try {
123
+ const all = await scanExemplars(repoRoot);
124
+ exemplars = all.filter((e) => e.kind === kind).slice(0, 5);
125
+ } catch {
126
+ // non-fatal — caller may invoke without a repoRoot
127
+ }
128
+ }
129
+ return {
130
+ ok: true,
131
+ prompt: loaded.raw,
132
+ sha256: loaded.sha256,
133
+ version: loaded.frontmatter.version,
134
+ kind: loaded.frontmatter.kind,
135
+ exemplars,
136
+ exemplarCount: exemplars.filter((e) => !e.anti).length,
137
+ antiCount: exemplars.filter((e) => e.anti).length,
138
+ tokenEstimate: Math.ceil(loaded.raw.length / 4),
139
+ };
140
+ } catch (err) {
141
+ const msg = err instanceof Error ? err.message : String(err);
142
+ return { ok: false, error: msg };
143
+ }
144
+ },
145
+ };
146
+ }
@@ -0,0 +1,85 @@
1
+ /**
2
+ * `mandu_ate_recall` — Phase B.2 memory read tool.
3
+ *
4
+ * See docs/ate/phase-b-spec.md §B.2. Agents call this BEFORE generating
5
+ * a spec so they can reference prior intent / rejected healing history.
6
+ *
7
+ * Snake_case (§11 decision #4). Read-only.
8
+ */
9
+
10
+ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
11
+ import { recallMemory, type MemoryEventKind } from "@mandujs/ate";
12
+
13
+ export const ateRecallToolDefinitions: Tool[] = [
14
+ {
15
+ name: "mandu_ate_recall",
16
+ annotations: {
17
+ readOnlyHint: true,
18
+ },
19
+ description:
20
+ "Phase B.2 memory recall. Queries the project-local " +
21
+ ".mandu/ate-memory.jsonl append-only log with substring + token-" +
22
+ "overlap scoring (no embeddings). Useful BEFORE generation to see " +
23
+ "previously rejected specs, accepted heals, or intent history for " +
24
+ "the same route. Returns { events, totalMatching }. Default limit 10, " +
25
+ "default sinceDays 90. Filter by kind: intent_history | rejected_spec " +
26
+ "| accepted_healing | rejected_healing | prompt_version_drift | " +
27
+ "boundary_gap_filled | coverage_snapshot.",
28
+ inputSchema: {
29
+ type: "object",
30
+ properties: {
31
+ repoRoot: {
32
+ type: "string",
33
+ description: "Absolute path to the Mandu project root.",
34
+ },
35
+ intent: {
36
+ type: "string",
37
+ description: "Natural-language intent to search (substring + token overlap).",
38
+ },
39
+ route: {
40
+ type: "string",
41
+ description: "Route id or pattern ('api-signup' or '/api/signup').",
42
+ },
43
+ kind: {
44
+ type: "string",
45
+ description: "Filter by event kind.",
46
+ },
47
+ limit: {
48
+ type: "number",
49
+ description: "Max events to return. Default 10.",
50
+ },
51
+ sinceDays: {
52
+ type: "number",
53
+ description: "Drop events older than N days. Default 90.",
54
+ },
55
+ },
56
+ required: ["repoRoot"],
57
+ },
58
+ },
59
+ ];
60
+
61
+ export function ateRecallTools(_projectRoot: string) {
62
+ return {
63
+ mandu_ate_recall: async (args: Record<string, unknown>) => {
64
+ const repoRoot = args.repoRoot as string | undefined;
65
+ if (!repoRoot || typeof repoRoot !== "string") {
66
+ return { ok: false, error: "repoRoot is required" };
67
+ }
68
+ try {
69
+ const result = recallMemory(repoRoot, {
70
+ intent: typeof args.intent === "string" ? args.intent : undefined,
71
+ route: typeof args.route === "string" ? args.route : undefined,
72
+ kind:
73
+ typeof args.kind === "string"
74
+ ? (args.kind as MemoryEventKind)
75
+ : undefined,
76
+ limit: typeof args.limit === "number" ? args.limit : undefined,
77
+ sinceDays: typeof args.sinceDays === "number" ? args.sinceDays : undefined,
78
+ });
79
+ return { ok: true, ...result };
80
+ } catch (err) {
81
+ return { ok: false, error: err instanceof Error ? err.message : String(err) };
82
+ }
83
+ },
84
+ };
85
+ }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * `mandu_ate_remember` — Phase B.2 memory write tool.
3
+ *
4
+ * Snake_case (§11 decision #4). Idempotent append.
5
+ */
6
+
7
+ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
8
+ import {
9
+ appendMemoryEvent,
10
+ parseMemoryEvent,
11
+ type MemoryEvent,
12
+ } from "@mandujs/ate";
13
+
14
+ export const ateRememberToolDefinitions: Tool[] = [
15
+ {
16
+ name: "mandu_ate_remember",
17
+ description:
18
+ "Phase B.2 memory write. Appends one event to the project-local " +
19
+ ".mandu/ate-memory.jsonl. File auto-rotates to .bak when it crosses " +
20
+ "10 MB. Supported event kinds (discriminated union by `kind`): " +
21
+ "intent_history | rejected_spec | accepted_healing | rejected_healing " +
22
+ "| prompt_version_drift | boundary_gap_filled | coverage_snapshot. " +
23
+ "Timestamp defaults to now (ISO-8601 UTC) if omitted.",
24
+ inputSchema: {
25
+ type: "object",
26
+ properties: {
27
+ repoRoot: {
28
+ type: "string",
29
+ description: "Absolute path to the Mandu project root.",
30
+ },
31
+ event: {
32
+ type: "object",
33
+ description:
34
+ "MemoryEvent object. Must carry a `kind` discriminator plus the " +
35
+ "event-kind-specific required fields (see @mandujs/ate memory/schema.ts).",
36
+ additionalProperties: true,
37
+ },
38
+ },
39
+ required: ["repoRoot", "event"],
40
+ },
41
+ },
42
+ ];
43
+
44
+ export function ateRememberTools(_projectRoot: string) {
45
+ return {
46
+ mandu_ate_remember: async (args: Record<string, unknown>) => {
47
+ const repoRoot = args.repoRoot as string | undefined;
48
+ const eventRaw = args.event;
49
+
50
+ if (!repoRoot || typeof repoRoot !== "string") {
51
+ return { ok: false, error: "repoRoot is required" };
52
+ }
53
+ if (!eventRaw || typeof eventRaw !== "object") {
54
+ return { ok: false, error: "event is required" };
55
+ }
56
+
57
+ // Default the timestamp if the caller omitted it (agents do).
58
+ const draft = { ...(eventRaw as Record<string, unknown>) };
59
+ if (typeof draft.timestamp !== "string") {
60
+ draft.timestamp = new Date().toISOString();
61
+ }
62
+ const parsed = parseMemoryEvent(draft);
63
+ if (!parsed) {
64
+ return {
65
+ ok: false,
66
+ error:
67
+ "Event failed validation. Check that `kind` and the kind-specific required fields are present.",
68
+ };
69
+ }
70
+
71
+ try {
72
+ const result = appendMemoryEvent(repoRoot, parsed as MemoryEvent);
73
+ return { ok: true, written: result.written, rotation: result.rotation ?? null };
74
+ } catch (err) {
75
+ return { ok: false, error: err instanceof Error ? err.message : String(err) };
76
+ }
77
+ },
78
+ };
79
+ }
@@ -0,0 +1,154 @@
1
+ /**
2
+ * `mandu_ate_run` — Phase A.2 agent-facing spec runner.
3
+ *
4
+ * Wraps `@mandujs/ate`'s `runSpec` behind the MCP tool surface.
5
+ *
6
+ * Semantics: execute a single spec file (Playwright or bun:test,
7
+ * auto-detected from the path), then return the failure.v1-shaped
8
+ * JSON — `{ status: "pass", ... }` on green, full failure envelope
9
+ * on red. Shard argument is forwarded transparently.
10
+ *
11
+ * The handler validates the returned shape against the failure.v1
12
+ * Zod schema on failure (cheap, catches translator regressions).
13
+ * On pass we return the pass envelope as-is.
14
+ *
15
+ * Snake_case naming per §11 decision 4.
16
+ */
17
+ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
18
+ import { runSpec, failureV1Schema, type RunResult } from "@mandujs/ate";
19
+
20
+ export const ateRunToolDefinitions: Tool[] = [
21
+ {
22
+ name: "mandu_ate_run",
23
+ annotations: {
24
+ readOnlyHint: false,
25
+ },
26
+ description:
27
+ "Phase A.2 agent-native spec runner. Executes ONE spec file " +
28
+ "(Playwright if the path matches tests/e2e/** or *.e2e.ts, otherwise bun:test) " +
29
+ "and returns structured JSON. On pass: { status: 'pass', durationMs, assertions, graphVersion, runId }. " +
30
+ "On fail: a failure.v1 envelope with discriminated `kind` (one of: selector_drift, " +
31
+ "contract_mismatch, redirect_unexpected, hydration_timeout, rate_limit_exceeded, " +
32
+ "csrf_invalid, fixture_missing, semantic_divergence), kind-specific `detail`, " +
33
+ "`healing.auto[]` (deterministic replacements when confidence >= threshold), " +
34
+ "`healing.requires_llm` (true for shape-level failures), `flakeScore`, `lastPassedAt`, " +
35
+ "`graphVersion` (agent cache invalidation key), and trace/screenshot/dom artifacts " +
36
+ "staged under .mandu/ate-artifacts/<runId>/. Use `shard: { current, total }` to " +
37
+ "distribute across CI workers.",
38
+ inputSchema: {
39
+ type: "object",
40
+ properties: {
41
+ repoRoot: {
42
+ type: "string",
43
+ description: "Absolute path to the Mandu project root",
44
+ },
45
+ spec: {
46
+ oneOf: [
47
+ { type: "string" },
48
+ {
49
+ type: "object",
50
+ properties: {
51
+ path: { type: "string" },
52
+ },
53
+ required: ["path"],
54
+ },
55
+ ],
56
+ description:
57
+ "Spec file — either a path string (relative to repoRoot) or { path }. " +
58
+ "Runner is auto-detected from the path (Playwright vs bun:test).",
59
+ },
60
+ headed: {
61
+ type: "boolean",
62
+ description: "Playwright only — run headed. Default: false (headless).",
63
+ },
64
+ trace: {
65
+ type: "boolean",
66
+ description: "Playwright only — capture trace. Default: true.",
67
+ },
68
+ shard: {
69
+ type: "object",
70
+ properties: {
71
+ current: { type: "number", minimum: 1 },
72
+ total: { type: "number", minimum: 1 },
73
+ },
74
+ required: ["current", "total"],
75
+ description:
76
+ "CI sharding — `current` is 1-based. Playwright receives --shard=current/total; " +
77
+ "bun:test falls back to hash-based partitioning.",
78
+ },
79
+ },
80
+ required: ["repoRoot", "spec"],
81
+ },
82
+ },
83
+ ];
84
+
85
+ export function ateRunTools(_projectRoot: string) {
86
+ return {
87
+ mandu_ate_run: async (args: Record<string, unknown>) => {
88
+ const { repoRoot, spec, headed, trace, shard } = args as {
89
+ repoRoot: string;
90
+ spec: string | { path: string };
91
+ headed?: boolean;
92
+ trace?: boolean;
93
+ shard?: { current: number; total: number };
94
+ };
95
+ if (!repoRoot || typeof repoRoot !== "string") {
96
+ return { ok: false, error: "repoRoot is required" };
97
+ }
98
+ if (!spec) {
99
+ return { ok: false, error: "spec is required" };
100
+ }
101
+ const specPath = typeof spec === "string" ? spec : spec?.path;
102
+ if (!specPath || typeof specPath !== "string") {
103
+ return { ok: false, error: "spec.path or spec string is required" };
104
+ }
105
+ if (shard) {
106
+ if (
107
+ typeof shard.current !== "number" ||
108
+ typeof shard.total !== "number" ||
109
+ shard.current < 1 ||
110
+ shard.total < 1 ||
111
+ shard.current > shard.total
112
+ ) {
113
+ return {
114
+ ok: false,
115
+ error: `invalid shard: ${JSON.stringify(shard)} (current must be 1..total)`,
116
+ };
117
+ }
118
+ }
119
+
120
+ let result: RunResult;
121
+ try {
122
+ result = await runSpec({
123
+ repoRoot,
124
+ spec: specPath,
125
+ headed,
126
+ trace,
127
+ shard,
128
+ });
129
+ } catch (err) {
130
+ return {
131
+ ok: false,
132
+ error: `runSpec failed: ${err instanceof Error ? err.message : String(err)}`,
133
+ };
134
+ }
135
+
136
+ // On failure, re-validate the shape against failure.v1. The
137
+ // runSpec path already does this, but re-checking at the MCP
138
+ // boundary means a buggy translator is caught before the
139
+ // payload crosses the wire.
140
+ if (result.status === "fail") {
141
+ const parsed = failureV1Schema.safeParse(result);
142
+ if (!parsed.success) {
143
+ return {
144
+ ok: false,
145
+ error: `runSpec emitted invalid failure.v1: ${parsed.error.issues[0]?.message ?? "schema mismatch"}`,
146
+ result,
147
+ };
148
+ }
149
+ return { ok: true, result: parsed.data };
150
+ }
151
+ return { ok: true, result };
152
+ },
153
+ };
154
+ }
@@ -0,0 +1,160 @@
1
+ /**
2
+ * `mandu_ate_save` — Phase A.3 spec persistence with lint-before-write.
3
+ *
4
+ * See `docs/ate/roadmap-v2-agent-native.md` §4.7 and the §7 extension
5
+ * ("mandu_ate_save lint-before-write").
6
+ *
7
+ * Semantics:
8
+ * 1. Run `lintSpecContent` (from @mandujs/ate) which:
9
+ * - parses with ts-morph (syntax errors block),
10
+ * - walks import declarations (banned typos, unknown @mandujs/* barrels),
11
+ * - detects anti-patterns (bare localhost, hand-rolled CSRF, DB mocks).
12
+ * 2. If any *blocking* diagnostic fires, return { saved: false, ... } WITHOUT
13
+ * writing. Otherwise write and return { saved: true, path }.
14
+ *
15
+ * Snake_case tool name (§11 decision #4).
16
+ */
17
+
18
+ import type { Tool } from "@modelcontextprotocol/sdk/types.js";
19
+ import { writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
20
+ import { dirname, isAbsolute } from "node:path";
21
+ import {
22
+ lintSpecContent,
23
+ appendMemoryEvent,
24
+ nowTimestamp,
25
+ type LintDiagnostic,
26
+ } from "@mandujs/ate";
27
+
28
+ // Re-export the diagnostic shape so callers can type-check against it without
29
+ // pulling @mandujs/ate directly.
30
+ export type { LintDiagnostic, LintSeverity } from "@mandujs/ate";
31
+
32
+ export const ateSaveToolDefinitions: Tool[] = [
33
+ {
34
+ name: "mandu_ate_save",
35
+ description:
36
+ "Phase A.3 persist-with-lint. Writes an agent-generated test file to " +
37
+ "disk, but first runs a small lint pass that blocks common LLM mistakes: " +
38
+ "ts-morph syntax errors, unresolved / banned import paths, hand-rolled " +
39
+ "CSRF cookies, DB mocks when createTestDb is available, and bare " +
40
+ "`localhost:<port>` URLs (prefer 127.0.0.1 per roadmap §9.2). Returns " +
41
+ "{ saved: true, path, lintDiagnostics: [warnings...] } on success or " +
42
+ "{ saved: false, blockingErrors: [...], lintDiagnostics: [...] } when " +
43
+ "a blocker fires (in which case no file is written).",
44
+ inputSchema: {
45
+ type: "object",
46
+ properties: {
47
+ path: {
48
+ type: "string",
49
+ description:
50
+ "Absolute path where the spec will be written. Parent directories are created if needed.",
51
+ },
52
+ content: {
53
+ type: "string",
54
+ description: "The full TypeScript test source to write.",
55
+ },
56
+ intent: {
57
+ type: "string",
58
+ description:
59
+ "Optional short description of what the test is verifying (logged to ATE memory).",
60
+ },
61
+ kind: {
62
+ type: "string",
63
+ description:
64
+ "Optional prompt kind this spec was generated for (filling_unit, filling_integration, e2e_playwright).",
65
+ },
66
+ sourcePrompt: {
67
+ type: "object",
68
+ description:
69
+ "Optional { kind, version } back-reference to the prompt that produced this spec (used by future memory queries).",
70
+ additionalProperties: true,
71
+ },
72
+ allowWarnings: {
73
+ type: "boolean",
74
+ description:
75
+ "When true, non-blocking warnings still allow the write (default true). When false, even warnings block.",
76
+ },
77
+ },
78
+ required: ["path", "content"],
79
+ },
80
+ },
81
+ ];
82
+
83
+ export function ateSaveTools(projectRoot: string) {
84
+ return {
85
+ mandu_ate_save: async (args: Record<string, unknown>) => {
86
+ const path = args.path as string | undefined;
87
+ const content = args.content as string | undefined;
88
+ const intent = typeof args.intent === "string" ? args.intent : undefined;
89
+ const kind = typeof args.kind === "string" ? args.kind : undefined;
90
+ const allowWarnings = args.allowWarnings !== false;
91
+
92
+ if (!path || typeof path !== "string") {
93
+ return { saved: false, error: "'path' is required" };
94
+ }
95
+ if (!isAbsolute(path)) {
96
+ return {
97
+ saved: false,
98
+ error: "'path' must be absolute — relative paths are rejected to prevent cwd drift.",
99
+ };
100
+ }
101
+ if (typeof content !== "string") {
102
+ return { saved: false, error: "'content' is required and must be a string" };
103
+ }
104
+
105
+ const diagnostics = await lintSpecContent(path, content);
106
+
107
+ const blocking = diagnostics.filter((d) => d.blocking);
108
+ const warnings = diagnostics.filter((d) => !d.blocking);
109
+
110
+ if (blocking.length > 0 || (!allowWarnings && warnings.length > 0)) {
111
+ return {
112
+ saved: false,
113
+ path,
114
+ blockingErrors: blocking,
115
+ lintDiagnostics: diagnostics,
116
+ };
117
+ }
118
+
119
+ const parent = dirname(path);
120
+ if (!existsSync(parent)) {
121
+ mkdirSync(parent, { recursive: true });
122
+ }
123
+ if (!statSync(parent).isDirectory()) {
124
+ return { saved: false, path, error: `Parent path is not a directory: ${parent}` };
125
+ }
126
+
127
+ writeFileSync(path, content, "utf8");
128
+
129
+ // Phase B.2 — auto-record intent_history event. Non-fatal on failure.
130
+ try {
131
+ appendMemoryEvent(projectRoot, {
132
+ kind: "intent_history",
133
+ timestamp: nowTimestamp(),
134
+ intent: intent ?? "(no intent supplied)",
135
+ agent: typeof args.agent === "string" ? (args.agent as string) : "unknown",
136
+ resulting: { saved: [path] },
137
+ ...(kind ? { routeId: kind } : {}),
138
+ });
139
+ } catch {
140
+ // swallow
141
+ }
142
+
143
+ return {
144
+ saved: true,
145
+ path,
146
+ bytes: Buffer.byteLength(content, "utf8"),
147
+ lintDiagnostics: diagnostics,
148
+ };
149
+ },
150
+ };
151
+ }
152
+
153
+ // Re-export for tests that need direct access (package.json test patterns
154
+ // already reach here).
155
+ export async function lintContent(
156
+ path: string,
157
+ content: string,
158
+ ): Promise<LintDiagnostic[]> {
159
+ return lintSpecContent(path, content);
160
+ }
package/src/tools/ate.ts CHANGED
@@ -171,16 +171,27 @@ export const ateToolDefinitions: Tool[] = [
171
171
  readOnlyHint: true,
172
172
  },
173
173
  description:
174
- "ATE Optimization — Impact Analysis: Calculate the minimal subset of routes affected by changed files using git diff. " +
175
- "Avoids running the full test suite when only part of the codebase changed. " +
176
- "Returns selectedRoutes to pass to mandu.ate.generate (onlyRoutes) or mandu.ate.run. " +
177
- "Typical use: run after `git commit` to test only affected routes in CI.",
174
+ "ATE Impact Analysis (Phase B.3 v2). Calculates the minimal set of " +
175
+ "routes / specs affected by changed files using git diff, classifies " +
176
+ "contract changes (additive / breaking / renaming), and returns " +
177
+ "`affected.specsToReRun`, `affected.specsLikelyBroken`, " +
178
+ "`affected.missingCoverage`, plus a `suggestions` list keyed to " +
179
+ "re_run / heal / regenerate / add_boundary_test. Stamped with " +
180
+ "graphVersion for agent caching. Keeps v1 fields (changedFiles, " +
181
+ "selectedRoutes, warnings) for backwards compatibility. " +
182
+ "Pass `since: 'working'` for uncommitted changes, `since: 'staged'` " +
183
+ "for staged changes, or a git rev (default: HEAD~1) for committed diffs.",
178
184
  inputSchema: {
179
185
  type: "object",
180
186
  properties: {
181
187
  repoRoot: { type: "string", description: "Absolute path to the Mandu project root" },
182
- base: { type: "string", description: "Git base ref for diff (default: HEAD~1 or main branch)" },
183
- head: { type: "string", description: "Git head ref for diff (default: current working tree)" },
188
+ base: { type: "string", description: "Git base ref (legacy v1 use `since` instead)" },
189
+ head: { type: "string", description: "Git head ref (legacy v1 defaults to HEAD)" },
190
+ since: {
191
+ type: "string",
192
+ description:
193
+ "v2 diff source: 'HEAD~1' | 'staged' | 'working' | any git rev. Default 'HEAD~1'.",
194
+ },
184
195
  },
185
196
  required: ["repoRoot"],
186
197
  },
@@ -333,11 +344,27 @@ export function ateTools(projectRoot: string) {
333
344
  return ateHeal({ repoRoot, runId });
334
345
  },
335
346
  "mandu.ate.impact": async (args: Record<string, unknown>) => {
336
- const { repoRoot, base, head } = args as {
347
+ const { repoRoot, base, head, since } = args as {
337
348
  repoRoot: string;
338
349
  base?: string;
339
350
  head?: string;
351
+ since?: "HEAD~1" | "staged" | "working" | string;
340
352
  };
353
+
354
+ // Phase B.3 — try the v2 impact pipeline first so callers get
355
+ // `affected`, `suggestions`, `contractDiffs`, `graphVersion` in
356
+ // addition to the v1 fields. Fall back to v1 on failure so the
357
+ // tool contract stays backwards compatible.
358
+ try {
359
+ const { computeImpactV2 } = await import("@mandujs/ate");
360
+ const v2 = await computeImpactV2({
361
+ repoRoot,
362
+ since: since ?? base,
363
+ });
364
+ return { ok: true, ...v2 };
365
+ } catch {
366
+ // Fall through to v1.
367
+ }
341
368
  return ateImpact({ repoRoot, base, head });
342
369
  },
343
370
  "mandu.ate.auto_pipeline": async (args: Record<string, unknown>) => {