@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/mcp/apitools.ts

@@ -0,0 +1,335 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+import { latestRunDir } from "../code/index.ts"
+import { expandHeaders, runContracts } from "../api/run.ts"
+import { setFromSpec } from "../api/spec.ts"
+import { loadSet, newSetId, runCard, saveSet, scenarioRunCard, scenariosCard, setCard } from "../api/store.ts"
+import { readNetwork, setFromRun } from "../api/traffic.ts"
+import { addScenarios, runScenarios, scenarioFromRun, scenariosFromSpec } from "../api/scenario.ts"
+import { planScenarios } from "../api/plan.ts"
+import { loadCases } from "../cases/index.ts"
+import { writeApiTests } from "../api/write.ts"
+import type { ContractSet, Scenario } from "../api/types.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+
+const list = (v: unknown) => (Array.isArray(v) ? v.map(String) : typeof v === "string" && v.trim() ? v.split(",").map((s) => s.trim()) : [])
+
+/** A run folder from a path or a run id, else the latest run. */
+function runFolder(ref: unknown, ctx: ToolContext): string {
+  const out = ctx.config.export.outDir
+  if (ref) {
+    const r = String(ref)
+    for (const c of [path.resolve(ctx.cwd, r), path.join(out, r)]) if (existsSync(path.join(c, "run.json"))) return c
+    throw new Error(`No run "${r}": give the run folder or its id.`)
+  }
+  const latest = latestRunDir(out)
+  if (!latest) throw new Error("No browser run yet. Run the flow in the browser first: its API calls are recorded as it runs.")
+  return latest
+}
+
+function headers(ctx: ToolContext): Record<string, string> {
+  const { headers, missing } = expandHeaders(ctx.config.api?.headers)
+  if (missing.length) ctx.emit?.({ type: "info", text: `api.headers reads ${[...new Set(missing)].join(", ")}, which ${missing.length === 1 ? "is" : "are"} not set: those headers are not sent`, ok: false })
+  return headers
+}
+
+const summary = (set: ContractSet) =>
+  set.contracts.map((c) => ({ id: c.id, protocol: c.protocol, expect_status: c.expect.status, changes_data: c.writes || undefined, needs_data: c.needsData, key_fields: c.expect.fields?.map((f) => f.path), seen: c.source.samples }))
+
+/** Ask before running scenarios that change data; true when they may run. */
+async function confirmWrites(ctx: ToolContext, scenarios: { name: string; writes: boolean }[], where: string): Promise<boolean> {
+  const writing = scenarios.filter((s) => s.writes)
+  if (!writing.length || !ctx.ask) return true
+  const answer = await ctx.ask({
+    title: `Run ${writing.length} scenario${writing.length === 1 ? "" : "s"} that change data?`,
+    detail: `Against ${where}. They create, change, or delete data: only on a test environment.`,
+    lines: writing.slice(0, 10).map((s) => `• ${s.name}`),
+    options: [
+      { id: "yes", label: "Yes, run them" },
+      { id: "no", label: "No, read-only scenarios only" },
+    ],
+  })
+  return answer === "yes"
+}
+
+/** The contract set to build scenarios on: a given set, a description to read, the run's own, or the newest. */
+async function baseSet(args: Record<string, any>, ctx: ToolContext): Promise<{ set: ContractSet; fresh: boolean }> {
+  if (args.spec) {
+    const ref = String(args.spec).trim()
+    const src = /^(https?|grpcs?):\/\//i.test(ref) ? ref : path.resolve(ctx.cwd, ref)
+    ctx.emit?.({ type: "info", text: `Reading the API description: ${ref}` })
+    return { set: await setFromSpec(src, newSetId(ctx.config, String(args.name || ref)), { headers: headers(ctx), name: args.name ? String(args.name) : undefined, baseUrl: args.base_url ? String(args.base_url) : undefined }), fresh: true }
+  }
+  return { set: loadSet(ctx.config, args.set_id ? String(args.set_id) : undefined).set, fresh: false }
+}
+
+/** API and contract tests: contracts from browser runs and API descriptions, run directly or written as tests. */
+export const API_TOOLS: McpTool[] = [
+  {
+    name: "api_contracts",
+    description:
+      "Make API contracts: one per API operation, with an example call and what the answer must have (status, content type, JSON schema, key fields). from: run turns the calls a browser run saw the application make (XHR and fetch; REST, GraphQL, SOAP and gRPC-web) into contracts, grouped by operation, without a model; from: spec reads an API description from a link or file: OpenAPI 3 or Swagger 2 (JSON, YAML, or the Swagger UI page), WSDL (SOAP), a GraphQL endpoint (introspection), an SDL or introspection file, .proto files, or grpc://host:port with reflection. Shows the contracts and returns set_id for run_api_contracts and write_api_tests. Credentials are never stored.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", enum: ["run", "spec"], description: "run (default when no spec is given): a browser run's API calls; spec: an API description" },
+        run_dir: { type: "string", description: "from run: the run folder or id (default: the latest run)" },
+        spec: { type: "string", description: "from spec: link or file path of the API description" },
+        include: { type: "array", items: { type: "string" }, description: "Only operations whose id or name contains one of these (e.g. 'orders', 'POST /api/cart')" },
+        name: { type: "string", description: "A name for the set" },
+        base_url: { type: "string", description: "Base URL to run against, when it is not the one in the description or run" },
+        third_party: { type: "boolean", description: "from run: keep calls to other sites than the page's (default: api.third_party, off)" },
+      },
+    },
+    async run(args, ctx) {
+      const fromSpec = args.from === "spec" || (args.from !== "run" && args.spec)
+      let set: ContractSet
+      if (fromSpec) {
+        const ref = String(args.spec || "").trim()
+        if (!ref) throw new Error("spec is required: the link or file of the API description.")
+        const src = /^(https?|grpcs?):\/\//i.test(ref) ? ref : path.resolve(ctx.cwd, ref)
+        ctx.emit?.({ type: "info", text: `Reading the API description: ${ref}` })
+        set = await setFromSpec(src, newSetId(ctx.config, String(args.name || ref)), { headers: headers(ctx), include: list(args.include), name: args.name ? String(args.name) : undefined, baseUrl: args.base_url ? String(args.base_url) : undefined })
+      } else {
+        const dir = runFolder(args.run_dir, ctx)
+        ctx.emit?.({ type: "info", text: `Reading the API calls of run ${path.basename(dir)}` })
+        set = setFromRun(dir, { id: newSetId(ctx.config, String(args.name || `run-${path.basename(dir)}`)), name: args.name ? String(args.name) : undefined, include: list(args.include), thirdParty: args.third_party === true || ctx.config.api?.thirdParty === true })
+        if (args.base_url) set.baseUrl = String(args.base_url)
+      }
+      const saved = saveSet(ctx.config, set)
+      ctx.emit?.({ type: "card", card: setCard(set, saved.dir, ctx.cwd) })
+      const reads = set.contracts.filter((c) => !c.writes && !c.needsData?.length).length
+      return {
+        set_id: set.id,
+        name: set.name,
+        base_url: set.baseUrl || undefined,
+        contracts: summary(set),
+        skipped: set.skipped,
+        files: { contracts: saved.file, brief: saved.brief },
+        next_step: set.contracts.length
+          ? `${reads} of ${set.contracts.length} can run as they are (read-only, with real values). Offer to run them now (run_api_contracts, fast, no browser) and to write them as tests in the repository (write_api_tests).${set.contracts.some((c) => c.needsData?.length) ? " Others need real values: the user can edit the examples in contracts.json." : ""}`
+          : "No operations found. Say what was left out and why.",
+      }
+    },
+  },
+  {
+    name: "run_api_contracts",
+    description:
+      "Run a contract set straight against the API (no browser, no model): makes each example call and checks status, content type, schema, and key fields (GraphQL: no errors; SOAP: no fault and the expected elements; gRPC through grpcurl). Calls that change data run only with allow_writes, after the user agrees; calls without real example values are skipped unless include_needs_data. Credentials come from api.headers in forgeqe.yaml. Writes results.json and junit.xml.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        set_id: { type: "string", description: "From api_contracts (default: the newest set), or a contracts.json path" },
+        base_url: { type: "string", description: "Run against this base URL (another environment)" },
+        only: { type: "array", items: { type: "string" }, description: "Only contracts whose id or name contains one of these" },
+        allow_writes: { type: "boolean", description: "Also run calls that change data (POST, PUT, PATCH, DELETE, mutations). Only on a test environment, after the user agrees." },
+        include_needs_data: { type: "boolean", description: "Also run calls whose example values were made up from the description" },
+      },
+    },
+    async run(args, ctx) {
+      const { set, dir } = loadSet(ctx.config, args.set_id ? String(args.set_id) : undefined)
+      let allowWrites = args.allow_writes === true
+      const writes = set.contracts.filter((c) => c.writes)
+      if (allowWrites && writes.length && ctx.ask) {
+        const ok = await ctx.ask({
+          title: `Run ${writes.length} call${writes.length === 1 ? "" : "s"} that change data?`,
+          detail: `Against ${args.base_url || ctx.config.api?.baseUrl || set.baseUrl}. Only do this on a test environment.`,
+          lines: writes.slice(0, 10).map((c) => `• ${c.id}`),
+          options: [
+            { id: "yes", label: "Yes, run them" },
+            { id: "no", label: "No, read-only calls only" },
+          ],
+        })
+        allowWrites = ok === "yes"
+      }
+      const runDir = path.join(dir, "runs", new Date().toISOString().replace(/[:.]/g, "-"))
+      const baseUrl = args.base_url ? String(args.base_url) : ctx.config.api?.baseUrl || set.baseUrl
+      ctx.emit?.({ type: "info", text: `Running ${set.contracts.length} API contracts against ${baseUrl || "their own URLs"}` })
+      const run = await runContracts(set, {
+        baseUrl,
+        headers: headers(ctx),
+        allowWrites,
+        includeNeedsData: args.include_needs_data === true,
+        only: list(args.only),
+        timeoutSeconds: ctx.config.api?.timeoutSeconds,
+        signal: ctx.signal,
+        dir: runDir,
+      })
+      ctx.emit?.({ type: "card", card: runCard(run, set, ctx.cwd) })
+      return {
+        counts: run.counts,
+        base_url: run.baseUrl,
+        failed: run.results.filter((r) => r.status === "failed" || r.status === "error").map((r) => ({ id: r.id, http_status: r.httpStatus, reason: r.reason, failed_checks: r.checks.filter((c) => !c.ok) })),
+        skipped: run.results.filter((r) => r.status === "skipped").map((r) => ({ id: r.id, reason: r.reason })),
+        results: path.join(runDir, "results.json"),
+        junit: path.join(runDir, "junit.xml"),
+      }
+    },
+  },
+  {
+    name: "write_api_tests",
+    description:
+      "Scribe, the coding agent, writes API and contract tests for a contract set in the repository's own framework and HTTP client (Playwright request, pytest with requests, REST Assured, HttpClient...), and ForgeQE runs them until they pass. No browser: faster and steadier than UI tests for the same logic. Calls that change data are left out unless include_writes. Takes a few minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        set_id: { type: "string", description: "From api_contracts (default: the newest set)" },
+        repo: { type: "string", description: "Repository folder (default: the working directory)" },
+        only: { type: "array", items: { type: "string" }, description: "Only contracts whose id or name contains one of these" },
+        include_writes: { type: "boolean", description: "Also write tests for calls that change data" },
+        base_url: { type: "string", description: "Base URL the tests default to" },
+        scenarios: { type: "array", items: { type: "string" }, description: "Write these scenarios (ids, names, or test case ids from api_scenarios; ['all'] for every one) as end-to-end tests, on the repository's existing API helpers, instead of one test per contract" },
+      },
+    },
+    async run(args, ctx) {
+      const loaded = loadSet(ctx.config, args.set_id ? String(args.set_id) : undefined)
+      const only = list(args.only).map((s) => s.toLowerCase())
+      const set = only.length ? { ...loaded.set, contracts: loaded.set.contracts.filter((c) => only.some((o) => `${c.id} ${c.name}`.toLowerCase().includes(o))) } : loaded.set
+      if (!set.contracts.length) throw new Error("No contracts to write tests for.")
+      const wanted = list(args.scenarios).map((s) => s.toLowerCase())
+      let scenarios: Scenario[] | undefined
+      if (wanted.length) {
+        scenarios = (loaded.set.scenarios || []).filter((sc) => wanted.includes("all") || wanted.some((w) => `${sc.id} ${sc.name} ${sc.caseId || ""}`.toLowerCase().includes(w)))
+        if (!scenarios.length) throw new Error(`No scenarios match ${wanted.join(", ")} in set ${loaded.set.id}: make them with api_scenarios first.`)
+      }
+      const repo = args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.cwd
+      const started = Date.now()
+      const r = await writeApiTests({
+        config: ctx.config,
+        repo,
+        set,
+        setDir: loaded.dir,
+        baseUrl: args.base_url ? String(args.base_url) : undefined,
+        writes: args.include_writes === true,
+        scenarios,
+        signal: ctx.signal,
+        onEvent: (event) => ctx.emit?.({ type: "agent", event }),
+        open: ctx.openSession,
+        runTest: ctx.runTest,
+      })
+      const secs = Math.round((Date.now() - started) / 1000)
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: r.status === "passed" ? "ok" : r.status === "stopped" ? "stopped" : "fail",
+          title: r.status === "passed" ? `API tests written and passing: ${set.name}` : `API tests ${r.status}: ${set.name}`,
+          stats: [`${r.attempts} attempt${r.attempts === 1 ? "" : "s"}`, `${secs}s`, r.model].filter(Boolean).join(" · "),
+          body: [
+            r.testFile ? `Test      ${r.testFile}` : "",
+            r.command ? `Run       ${r.command}` : "",
+            r.reused.length ? `Reused    ${r.reused.join(", ")}` : "",
+            r.changed.length ? `Changed   ${r.changed.join(", ")}` : "",
+            r.helpersChanged.length ? `Helpers   ${r.helpersChanged.join(", ")} changed; the tests that use them still pass` : "",
+            ...r.mapped.map((m) => `Mapped    ${m.caseId} → ${m.testName}`),
+            ...r.writeBack.map((w) => `${w.error ? "✗" : "✓"} ${w.text}${w.error ? `: ${w.error}` : ""}`),
+            r.notes ? `\n${r.notes}` : "",
+          ].filter(Boolean),
+        },
+      })
+      return { status: r.status, test_file: r.testFile, command: r.command, changed: r.changed, reused: r.reused, helpers_changed: r.helpersChanged, mapped: r.mapped, write_back: r.writeBack, notes: r.notes, attempts: r.attempts, output: r.status === "passed" ? undefined : r.output.slice(-3000), usage: r.usage }
+    },
+  },
+  {
+    name: "api_scenarios",
+    description:
+      "Make end-to-end API scenarios: calls in order, each using values earlier answers gave (an order id from 'create order' in 'get order'), with checks at each step. from: run turns a browser run's API calls into one chained scenario, finding the values that flowed from one answer into a later request (no model). from: spec makes, from an API description or contract set, each resource's lifecycle (create, read, update, delete, then 404), browsing (list, then an item), the description's links, and negative cases (unknown id → 404, no credentials → 401/403, empty body → 400/422) (no model). from: cases plans one scenario per test case (Azure DevOps, Jira, Xray, TestRail, Zephyr, qTest, files) and from: text plans one from plain English, both by the model against the set's operations. Shows the scenarios step by step and saves them in the contract set; nothing runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", enum: ["run", "spec", "cases", "text"], description: "run: a browser run; spec: an API description or contract set; cases: test cases; text: plain English" },
+        run_dir: { type: "string", description: "from run: the run folder or id (default: the latest run)" },
+        spec: { type: "string", description: "Link or file of an API description to plan against (else set_id, else the newest contract set)" },
+        set_id: { type: "string", description: "Contract set to plan against and save into (default: the newest)" },
+        cases: { type: "array", items: { type: "string" }, description: "from cases: test case references as find_test_cases takes them (ado:2238, ado:plan/12/suite/34, jira:SHOP-12, testrail:C12, a file path)" },
+        text: { type: "string", description: "from text: the scenario in plain English, or a story's text and acceptance criteria" },
+        negative: { type: "boolean", description: "from spec: also the negative cases (default true)" },
+        name: { type: "string" },
+        base_url: { type: "string" },
+      },
+      required: ["from"],
+    },
+    async run(args, ctx) {
+      const from = String(args.from)
+      let set: ContractSet
+      let made: Scenario[] = []
+      const extra: string[] = []
+      let replace: string[] = []
+      if (from === "run") {
+        const dir = runFolder(args.run_dir, ctx)
+        ctx.emit?.({ type: "info", text: `Chaining the API calls of run ${path.basename(dir)}` })
+        const thirdParty = ctx.config.api?.thirdParty === true
+        set = setFromRun(dir, { id: newSetId(ctx.config, String(args.name || `run-${path.basename(dir)}`)), name: args.name ? String(args.name) : undefined, thirdParty })
+        if (args.base_url) set.baseUrl = String(args.base_url)
+        const goal = set.name.replace(/^API calls of: /, "")
+        const flow = scenarioFromRun(readNetwork(dir), set, { goal, runId: path.basename(dir), thirdParty })
+        if (flow) made = [flow]
+      } else if (from === "spec") {
+        const base = await baseSet(args, ctx)
+        set = base.set
+        const out = scenariosFromSpec(set, { negative: args.negative !== false })
+        made = out.scenarios
+        extra.push(...out.notes)
+        replace = ["lifecycle", "browse", "linked", "negative"]
+      } else if (from === "cases" || from === "text") {
+        set = (await baseSet(args, ctx)).set
+        const cases = from === "cases" ? await loadCases(list(args.cases), ctx.config.sources) : undefined
+        if (from === "cases" && !cases?.length) throw new Error("No test cases found for those references.")
+        if (from === "text" && !String(args.text || "").trim()) throw new Error("text is required: the scenario in plain English.")
+        const plan = await planScenarios({ config: ctx.config, set, cases, text: args.text ? String(args.text) : undefined, cwd: ctx.cwd, signal: ctx.signal, onEvent: (event) => ctx.emit?.({ type: "agent", event }), open: ctx.openSession })
+        made = plan.scenarios
+        extra.push(...plan.unmatched.map((u) => `No operation for: ${u}`), ...plan.notRunnable.map((n) => `${n.caseId} not planned: ${n.reason}`))
+      } else throw new Error("from must be run, spec, cases, or text.")
+      const updated = addScenarios(set, made, replace)
+      const saved = saveSet(ctx.config, updated)
+      const ids = new Set(made.map((m) => m.id))
+      const final = (updated.scenarios || []).filter((s) => ids.has(s.id) || made.includes(s))
+      ctx.emit?.({ type: "card", card: scenariosCard(updated, final, saved.dir, ctx.cwd, extra) })
+      return {
+        set_id: updated.id,
+        scenarios: final.map((s) => ({ id: s.id, name: s.name, kind: s.kind, case_id: s.caseId, changes_data: s.writes || undefined, steps: s.steps.map((st) => `${st.method} ${st.path}${st.save ? ` (saves ${Object.keys(st.save).join(", ")})` : ""}`), notes: s.notes })),
+        notes: extra.length ? extra : undefined,
+        files: { contracts: saved.file, brief: saved.brief },
+        next_step: final.length
+          ? "Show the user the scenarios (they see the card). Offer to run them now with run_api_scenarios (it asks before any that change data) and to write them as end-to-end tests on the repository's existing API helpers with write_api_tests and scenarios."
+          : "No scenarios were made: say why from the notes.",
+      }
+    },
+  },
+  {
+    name: "run_api_scenarios",
+    description:
+      "Run a contract set's API scenarios straight against the API (no browser, no model): each step in order, values passed from one answer to the next, every step's checks, and the cleanup steps when a scenario fails part-way. Scenarios that change data run only after the user agrees. Writes scenario-results.json and scenarios-junit.xml.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        set_id: { type: "string", description: "Default: the newest set" },
+        only: { type: "array", items: { type: "string" }, description: "Only scenarios whose id, name, or test case id contains one of these" },
+        base_url: { type: "string" },
+        allow_writes: { type: "boolean", description: "Run scenarios that change data (the user is asked first). Default true: most scenarios create data; the question is the consent." },
+      },
+    },
+    async run(args, ctx) {
+      const { set, dir } = loadSet(ctx.config, args.set_id ? String(args.set_id) : undefined)
+      if (!set.scenarios?.length) throw new Error(`Set ${set.id} has no scenarios: make some with api_scenarios.`)
+      const only = list(args.only).map((s) => s.toLowerCase())
+      const chosen = set.scenarios.filter((sc) => !only.length || only.some((o) => `${sc.id} ${sc.name} ${sc.caseId || ""}`.toLowerCase().includes(o)))
+      const baseUrl = args.base_url ? String(args.base_url) : ctx.config.api?.baseUrl || set.baseUrl
+      const allowWrites = args.allow_writes !== false && (await confirmWrites(ctx, chosen, baseUrl || "the API"))
+      const runDir = path.join(dir, "runs", `scenarios-${new Date().toISOString().replace(/[:.]/g, "-")}`)
+      ctx.emit?.({ type: "info", text: `Running ${chosen.length} API scenario${chosen.length === 1 ? "" : "s"} against ${baseUrl || "their own URLs"}` })
+      const run = await runScenarios(set, { baseUrl, headers: headers(ctx), allowWrites, only: list(args.only), timeoutSeconds: ctx.config.api?.timeoutSeconds, signal: ctx.signal, dir: runDir })
+      ctx.emit?.({ type: "card", card: scenarioRunCard(run, set, ctx.cwd) })
+      return {
+        counts: run.counts,
+        base_url: run.baseUrl,
+        failed: run.results
+          .filter((r) => r.status === "failed" || r.status === "error")
+          .map((r) => ({ scenario: r.name, reason: r.reason, failed_step: r.steps.find((s) => s.status === "failed" || s.status === "error")?.name, checks: r.steps.flatMap((s) => s.checks.filter((c) => !c.ok)), cleanup: r.cleanup?.map((c) => `${c.name}: ${c.status}`) })),
+        skipped: run.results.filter((r) => r.status === "skipped").map((r) => ({ scenario: r.name, reason: r.reason })),
+        results: path.join(runDir, "scenario-results.json"),
+        junit: path.join(runDir, "scenarios-junit.xml"),
+      }
+    },
+  },
+]

package/src/mcp/captools.ts

@@ -0,0 +1,25 @@
+import { capability, CAPABILITIES } from "../capabilities/registry.ts"
+import { capabilityDetail, capabilityList } from "../capabilities/render.ts"
+import type { McpTool } from "./tools.ts"
+
+/** What ForgeQE can do, from src/capabilities/registry.ts, with whether each capability works in this setup. */
+export const CAPABILITY_TOOLS: McpTool[] = [
+  {
+    name: "capabilities",
+    description:
+      "What ForgeQE can do. Without ids: every capability by area, with a summary and whether it works in this setup (ready, partial: works but some parts need setup, needs_setup), and what ForgeQE does not do (out_of_scope). With ids: each capability's details: the tools that do it, example requests, what is missing here and how to set it up, what the request must supply, its limits, and its documentation sections in full. Use it for any question about what ForgeQE can do, whether it supports something, or what a feature needs; nothing runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ids: { type: "array", items: { type: "string", enum: CAPABILITIES.map((c) => c.id) }, description: "Capabilities to describe (from the list or the session notes)" },
+      },
+    },
+    async run(args, ctx) {
+      const ids: string[] = Array.isArray(args.ids) ? args.ids.map(String) : []
+      if (!ids.length) return capabilityList(ctx.config)
+      const unknown = ids.filter((id) => !capability(id))
+      if (unknown.length) throw new Error(`No capability ${unknown.join(", ")}. Known: ${CAPABILITIES.map((c) => c.id).join(", ")}.`)
+      return { capabilities: ids.map((id) => capabilityDetail(capability(id)!, ctx.config)) }
+    },
+  },
+]

package/src/mcp/casetools.ts

@@ -0,0 +1,223 @@
+import type { Card } from "../card.ts"
+import { casesFrom, type CaseSelector } from "../cases/index.ts"
+import { gatherContext, type Context } from "../cases/context.ts"
+import { checkCases, checkSummary, type CaseCheck } from "../cases/quality.ts"
+import type { TestCase } from "../cases/types.ts"
+import type { AppConfig } from "../config.ts"
+import { readPages } from "../memory.ts"
+import { DEFAULT_THRESHOLDS, releaseReadiness, saveReadiness, type Readiness } from "../cases/readiness.ts"
+import { updateAdoCase } from "../cases/save.ts"
+import { writeAdoWikiPage } from "../cases/wiki.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+import { notifiedLine, notify, readinessNotice } from "../notify/events.ts"
+
+const MARK = { ready: "✓", review: "▲", not_runnable: "✗" } as const
+
+/** Page memory, when it is on: every page and element earlier runs met. */
+const pagesOf = (config: AppConfig) => (config.memory?.enabled !== false && config.memory?.dir ? readPages(config.memory.dir) : [])
+
+/** At most this many cases get their requirements, documents, and passages gathered in one check. */
+const MAX_CONTEXT_CASES = 15
+
+/** The check as a card: each case's verdict, what it tests (its requirement chain), and its findings. */
+export function checkCard(checks: CaseCheck[], context?: Context): Card {
+  const body: string[] = []
+  for (const c of checks) {
+    body.push(`${MARK[c.verdict]} ${c.id}  ${c.title}`)
+    const cc = context?.cases.get(c.id)
+    if (cc?.chain.length) body.push(`    tests ${cc.chain.map((id) => { const r = context!.requirements.get(id); return r ? `${r.type} ${id.replace(/^ADO-/, "")} "${r.title}"` : id }).join(" ← ")}`)
+    for (const u of cc?.uncovered.slice(0, 3) || []) body.push(`    criterion maybe not covered: ${u.length > 100 ? `${u.slice(0, 99)}…` : u}`)
+    for (const f of c.findings.slice(0, 6)) body.push(`    ${f.step ? `step ${f.step}: ` : ""}${f.message}`)
+    if (c.findings.length > 6) body.push(`    and ${c.findings.length - 6} more`)
+  }
+  const bad = checks.some((c) => c.verdict === "not_runnable")
+  return { status: bad ? "fail" : checks.some((c) => c.verdict === "review") ? "info" : "ok", title: "Test case check", stats: checkSummary(checks), body }
+}
+
+/** What the tools return for a check, for the agent to add its own judgement to; with the gathered context when there is one. */
+export function checkResult(checks: CaseCheck[], context?: Context) {
+  return {
+    summary: checkSummary(checks),
+    cases: checks.map((c) => {
+      const cc = context?.cases.get(c.id)
+      return {
+        id: c.id,
+        title: c.title,
+        link: c.url,
+        verdict: c.verdict,
+        findings: c.findings,
+        ...(cc
+          ? {
+              tests_requirements: cc.chain.length ? cc.chain : undefined,
+              criteria_maybe_not_covered: cc.uncovered.length ? cc.uncovered : undefined,
+              documents: cc.docs.length ? cc.docs : undefined,
+              passages: cc.passages.length ? cc.passages : undefined,
+              context_errors: cc.errors.length ? cc.errors : undefined,
+            }
+          : {}),
+      }
+    }),
+    ...(context?.requirements.size ? { requirements: Object.fromEntries(context.requirements) } : {}),
+    ...(context?.docs.size ? { documents: Object.fromEntries([...context.docs].map(([url, d]) => [url, { title: d.title, text: d.text }])) } : {}),
+  }
+}
+
+/** Check cases with the rules, show the card, and (with suite.case_check: block) say which ones not to run. */
+export function precheck(cases: Parameters<typeof checkCases>[0], ctx: ToolContext): { checks: CaseCheck[]; skip: Set<string> } {
+  const mode = ctx.config.suite.caseCheck || "warn"
+  if (mode === "off") return { checks: [], skip: new Set() }
+  const checks = checkCases(cases, pagesOf(ctx.config))
+  if (checks.some((c) => c.verdict !== "ready")) ctx.emit?.({ type: "card", card: checkCard(checks) })
+  const skip = new Set(mode === "block" ? checks.filter((c) => c.verdict === "not_runnable").map((c) => c.id) : [])
+  return { checks, skip }
+}
+
+export const CASE_TOOLS: McpTool[] = [
+  {
+    name: "check_test_cases",
+    description:
+      "Check test cases before running them, without running anything. Rules: no steps, no expected results, vague expected results (\"works correctly\"), steps without the test data they need, unfilled placeholders, credentials in the case, several actions in one step, no start page, duplicates. Page memory: steps naming a field or control earlier runs never saw on that page. Context: the requirements each case tests (its story or PBI, then feature and epic, with acceptance criteria; Jira's linked issues and parents), the Confluence pages they link to, and passages from the RAG service when one is configured, with acceptance criteria no step seems to cover. Returns a verdict per case with findings and the context, and shows a card; judge the cases against their requirements.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sources: { type: "array", description: "The same sources as find_test_cases", items: { type: "object" } },
+        depth: { type: "string", enum: ["full", "quick"], description: "full (default): also read the requirements each case tests (story, feature, epic), their linked Confluence pages, and the RAG service when configured. quick: rules and page memory only, no reads" },
+      },
+      required: ["sources"],
+    },
+    async run(args, ctx) {
+      const cases: TestCase[] = await casesFrom(args.sources as CaseSelector[], ctx.config.sources, ctx.cwd)
+      const checks = checkCases(cases, pagesOf(ctx.config))
+      const full = args.depth !== "quick"
+      if (full) ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: `Reading what ${cases.length === 1 ? "the case tests" : "the cases test"}: requirements above ${cases.length === 1 ? "it" : "them"}, linked documents${ctx.config.rag ? ", and the RAG service" : ""}…` } })
+      const context = full ? await gatherContext(cases.slice(0, MAX_CONTEXT_CASES), ctx.config) : undefined
+      ctx.emit?.({ type: "card", card: checkCard(checks, context) })
+      return {
+        ...checkResult(checks, context),
+        ...(full && cases.length > MAX_CONTEXT_CASES ? { note: `Requirements were read for the first ${MAX_CONTEXT_CASES} cases; check the rest in smaller groups.` } : {}),
+        next_step: full
+          ? "For each case, judge it against what it tests: the acceptance criteria of its requirements (tests_requirements, nearest first), the linked documents, and the passages. Say which criteria no step covers, steps that check something no requirement asks for, expected results that contradict the requirement, and steps the page memory findings show the application does not have. Then what to fix, in plain words. Offer to rewrite a case and save it with update_test_case."
+          : checks.some((c) => c.verdict !== "ready")
+            ? "Tell the user what to fix in each case, in plain words, with your own findings added. Offer to rewrite a case and save it with update_test_case."
+            : "The cases are ready to run.",
+      }
+    },
+  },
+  {
+    name: "update_test_case",
+    description:
+      "Rewrite an Azure DevOps Test Case's steps (and optionally its title) after the user agrees: ForgeQE shows the current and the new steps and asks (Update / Don't update); the reason goes into the work item's history, and the old steps stay there. Use it for a case run_test_cases classified as test case needs updating (write the steps from what the run found the application does: run_details has every step and element), or a case check_test_cases found unclear. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed to these exact steps.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The test case: ADO-2236, 2236, or its link" },
+        title: { type: "string", description: "A new title, only when the old one no longer fits" },
+        steps: {
+          type: "array",
+          items: { type: "object", properties: { action: { type: "string" }, expected: { type: "string" } }, required: ["action"] },
+          description: "Every step of the case as it should be, each with the expected result the page shows",
+        },
+        reason: { type: "string", description: "Why, in one sentence, e.g. 'The page has no email field; the form is the automation practice form.'" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to these steps" },
+      },
+      required: ["id", "steps", "reason"],
+    },
+    async run(args, ctx) {
+      const id = Number(/(\d+)\s*$/.exec(String(args.id).replace(/[/?#].*$/, ""))?.[1] || /edit\/(\d+)/.exec(String(args.id))?.[1])
+      if (!id) throw new Error(`"${args.id}" is not an Azure DevOps test case id.`)
+      if (!ctx.config.sources.ado) throw new Error("Azure DevOps is not set up: updating test cases works for Azure DevOps Test Cases.")
+      const steps = (args.steps as { action: string; expected?: string }[]).filter((s) => s?.action?.trim()).map((s) => ({ action: s.action.trim(), ...(s.expected?.trim() ? { expected: s.expected.trim() } : {}) }))
+      if (!steps.length) throw new Error("steps is empty.")
+      const [current] = await casesFrom([{ source: "azure_devops", ids: [String(id)] } as CaseSelector], ctx.config.sources, ctx.cwd)
+      const show = (list: { action: string; expected?: string }[]) => list.map((s, i) => `  ${i + 1}. ${s.action}${s.expected ? `  → ${s.expected}` : ""}`)
+      const lines = ["Now:", ...show(current?.steps || []), "", "New:", ...show(steps), "", `Why: ${args.reason}`]
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Update test case ${id}${args.title ? ` and rename it "${args.title}"` : ""}?`,
+          detail: current?.url,
+          lines,
+          options: [
+            { id: "update", label: "Update test case" },
+            { id: "no", label: "Don't update" },
+          ],
+        })
+        if (choice !== "update") return { updated: false, reason: "The user chose not to update the test case." }
+      } else if (args.confirmed !== true) {
+        return { updated: false, needs_confirmation: true, current: current?.steps, proposed: steps, next_step: "Show the user the current and new steps; call update_test_case again with confirmed: true only after they agree." }
+      }
+      const url = await updateAdoCase(ctx.config.sources, id, { title: args.title ? String(args.title) : undefined, steps, reason: String(args.reason) })
+      ctx.emit?.({ type: "card", card: { status: "ok", title: `Test case ${id} updated`, stats: `${steps.length} steps`, body: [...show(steps), "", `Why: ${args.reason}`, url] } })
+      return { updated: true, url, steps: steps.length, next_step: "Offer to run it again with run_test_cases." }
+    },
+  },
+  {
+    name: "release_readiness",
+    description:
+      "Requirement coverage and release readiness for an Azure DevOps scope: a sprint (or 'current'), an area path, an epic or feature and everything under it, or work item ids. For each story: its test cases, whether each is automated, and its last result (Azure DevOps test points, else ForgeQE's own runs); stories with no test case, cases not automated, open bugs by severity, flaky and quarantined tests; and a verdict, GO, GO WITH RISKS, or NO-GO, with the blocking reasons and the risks (thresholds in forgeqe.yaml under release:). Saves readiness.md and shows a card; with publish, writes it to the project wiki after the user confirms.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sprint: { type: "string", description: "A sprint name, or 'current'" },
+        area: { type: "string", description: "An area path, e.g. QI-Claims\\Portal" },
+        parent: { type: "number", description: "An epic or feature id: every story under it" },
+        ids: { type: "array", items: { type: "number" }, description: "Story or PBI ids" },
+        project: { type: "string", description: "The project, when sources.azure_devops.project is not set" },
+        publish: { type: "string", description: "A wiki page path to publish the report to, e.g. /Release readiness/Sprint 12 (asks first)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to publish" },
+      },
+    },
+    async run(args, ctx) {
+      if (!ctx.config.sources.ado) throw new Error("Release readiness reads Azure DevOps: set up sources.azure_devops first.")
+      const scope = {
+        ...(args.sprint ? { sprint: String(args.sprint) } : {}),
+        ...(args.area ? { area: String(args.area) } : {}),
+        ...(args.parent ? { parent: Number(args.parent) } : {}),
+        ...(Array.isArray(args.ids) && args.ids.length ? { ids: (args.ids as unknown[]).map(Number).filter(Boolean) } : {}),
+        ...(args.project ? { project: String(args.project) } : {}),
+      }
+      ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: "Reading stories, test cases, results, and bugs…" } })
+      const r = await releaseReadiness(ctx.config, ctx.cwd, scope, ctx.config.release || DEFAULT_THRESHOLDS)
+      const saved = saveReadiness(ctx.config, r)
+      ctx.emit?.({ type: "card", card: readinessCard(r, saved.dir) })
+      let published: string | undefined
+      if (args.publish) {
+        const pagePath = String(args.publish).startsWith("/") ? String(args.publish) : `/${args.publish}`
+        let go = args.confirmed === true
+        if (ctx.ask) go = (await ctx.ask({ title: `Publish the report to the wiki page ${pagePath}?`, lines: [`${r.verdict} · ${r.scope}`], options: [{ id: "yes", label: "Publish" }, { id: "no", label: "Don't publish" }] })) === "yes"
+        if (go) published = (await writeAdoWikiPage(ctx.config.sources, { path: pagePath, content: saved.markdown, ...(scope.project ? { project: scope.project } : {}) })).url
+      }
+      const notified = ctx.session === "shell" ? [] : await notify(ctx.config, "release", readinessNotice(r, ctx.config, { file: `${saved.dir}/readiness.md`, published }))
+      return {
+        ...(notified.length ? { notified: notifiedLine(notified) } : {}),
+        scope: r.scope,
+        verdict: r.verdict,
+        blocking: r.blockers,
+        risks: r.risks,
+        counts: r.counts,
+        pass_rate: r.passRate,
+        untested_stories: r.stories.filter((s) => !s.cases.length).map((s) => ({ id: s.id, title: s.title })),
+        failing: r.stories.flatMap((s) => s.cases.filter((c) => c.outcome === "failed").map((c) => ({ story: s.id, case: c.id, title: c.title }))),
+        open_bugs: r.bugs.map((b) => ({ id: b.id, title: b.title, severity: b.severityText })),
+        report: `${saved.dir}/readiness.md`,
+        ...(published ? { published } : {}),
+        notes: r.notes.length ? r.notes : undefined,
+        next_step: "Give the verdict first, then what blocks it and the risks, in plain words. Offer to publish to the wiki (publish), to post the verdict to the team's notification channels (notify, when this session has them), to run the cases not run (run_test_cases), and an Azure DevOps dashboard (create_ado_dashboard) for the team.",
+      }
+    },
+  },
+]
+
+function readinessCard(r: Readiness, dir: string): Card {
+  const c = r.counts
+  return {
+    status: r.verdict === "GO" ? "ok" : r.verdict === "NO-GO" ? "fail" : "info",
+    title: `${r.verdict}: ${r.scope}`,
+    stats: `${c.stories} stories · ${c.cases} test cases · ${c.automated} automated · pass rate ${r.passRate === null ? "–" : `${r.passRate}%`} · ${r.bugs.length} open bugs`,
+    body: [
+      ...r.blockers.map((b) => `✗ ${b}`),
+      ...r.risks.map((b) => `▲ ${b}`),
+      ...(r.blockers.length || r.risks.length ? [""] : []),
+      `Report    ${dir}/readiness.md`,
+    ],
+  }
+}