@capagents/forgeqe 1.2.1 → 1.3.0

package/src/mcp/casetools.ts

@@ -6,7 +6,8 @@ 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 { jiraCase, storyCases, updateAdoCase, updateJiraCase, type NewCase } from "../cases/save.ts"
+import { planJourneys, type JourneyCase } from "../cases/journey.ts"
 import { writeAdoWikiPage } from "../cases/wiki.ts"
 import type { McpTool, ToolContext } from "./tools.ts"
 import { notifiedLine, notify, readinessNotice } from "../notify/events.ts"
@@ -106,11 +107,11 @@ export const CASE_TOOLS: McpTool[] = [
   {
     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.",
+      "Rewrite a test case's steps (and optionally its title) in place after the user agrees: an Azure DevOps Test Case (the reason goes into its history, the old steps stay there) or a Jira test issue (the steps in its description are replaced, the text above them kept, and the reason added as a comment). ForgeQE shows the current and the new steps and asks (Update / Don't update). 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), a case check_test_cases found unclear, a change the user asks for after reviewing a case, and a case save_test_cases returned as differs or similar. The case's automated test, when it has one, is brought up to date on its next run. 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" },
+        id: { type: "string", description: "The test case: ADO-2236, 2236, or its link in Azure DevOps; SHOP-31 in Jira" },
         title: { type: "string", description: "A new title, only when the old one no longer fits" },
         steps: {
           type: "array",
@@ -123,17 +124,23 @@ export const CASE_TOOLS: McpTool[] = [
       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 raw = String(args.id).trim()
+      const jiraKey = /^(?!ADO-)[A-Z][A-Z0-9_]*-\d+$/i.test(raw) ? raw.toUpperCase() : /\/browse\/([A-Z][A-Z0-9_]*-\d+)/i.exec(raw)?.[1]?.toUpperCase()
+      const id = jiraKey ? 0 : Number(/(\d+)\s*$/.exec(raw.replace(/[/?#].*$/, ""))?.[1] || /edit\/(\d+)/.exec(raw)?.[1])
+      if (!jiraKey && !id) throw new Error(`"${args.id}" is not an Azure DevOps test case id or a Jira issue key.`)
+      if (jiraKey && !ctx.config.sources.jira) throw new Error("Jira is not set up: add sources.jira to forgeqe.yaml.")
+      if (!jiraKey && !ctx.config.sources.ado) throw new Error("Azure DevOps is not set up: add sources.azure_devops to forgeqe.yaml.")
       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 current: { steps: NewCase["steps"]; url?: string } | undefined = jiraKey
+        ? await jiraCase(ctx.config.sources, jiraKey)
+        : (await casesFrom([{ source: "azure_devops", ids: [String(id)] } as CaseSelector], ctx.config.sources, ctx.cwd))[0]
+      const label = jiraKey || String(id)
       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}"` : ""}?`,
+          title: `Update test case ${label}${args.title ? ` and rename it "${args.title}"` : ""}?`,
           detail: current?.url,
           lines,
           options: [
@@ -145,9 +152,98 @@ export const CASE_TOOLS: McpTool[] = [
       } 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." }
+      const change = { title: args.title ? String(args.title) : undefined, steps, reason: String(args.reason) }
+      const url = jiraKey ? await updateJiraCase(ctx.config.sources, jiraKey, change) : await updateAdoCase(ctx.config.sources, id, change)
+      ctx.emit?.({ type: "card", card: { status: "ok", title: `Test case ${label} 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; its automated test, when it has one, is updated to the new steps in that run." }
+    },
+  },
+  {
+    name: "story_test_cases",
+    description:
+      "The test cases already linked to an Azure DevOps or Jira story, with their steps and expected results. Call it before writing test cases for a story, so you write only the cases its acceptance criteria still need, and propose updates (update_test_case) to linked cases that no longer fit, instead of writing them again. Reads only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"], description: "Where the story is" },
+        story: { type: "string", description: "The story's work item id (Azure DevOps) or issue key (Jira)" },
+      },
+      required: ["system", "story"],
+    },
+    async run(args, ctx) {
+      const story = String(args.story || "").trim()
+      if (!story) throw new Error("story is required.")
+      const found = await storyCases(ctx.config.sources, args.system === "jira" ? "jira" : "azure_devops", story)
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: "info",
+          title: `Test cases linked to ${found.story.id}${found.story.title ? ` ${found.story.title}` : ""}`,
+          stats: `${found.cases.length} linked`,
+          body: found.cases.length ? found.cases.map((c) => `${c.id}  ${c.title}  (${c.steps.length} steps)`) : ["None yet."],
+        },
+      })
+      return {
+        story: found.story,
+        cases: found.cases.map((c) => ({ id: c.id, title: c.title, url: c.url, steps: c.steps.map((st, i) => `${i + 1}. ${st.action}${st.expected ? ` → ${st.expected}` : ""}`) })),
+        next_step: found.cases.length
+          ? "Compare these with the story's acceptance criteria. Write only the cases for criteria and rules no linked case covers, and save only those. For a linked case that no longer fits the story, propose its new steps with update_test_case. Tell the user which criteria the linked cases already cover."
+          : "No case is linked yet: write the cases from the story.",
+      }
+    },
+  },
+  {
+    name: "e2e_journey",
+    description:
+      "Plan end-to-end journeys from test cases that already exist, instead of writing them again: from the cases linked to a story (system and story) or any find_test_cases sources. Groups the cases that start the same way (same start page and first steps, such as signing in), keeps those shared steps once, and lays out each case's remaining steps as a section of one journey, with which case and steps each section comes from. Flags cases that look like negative paths, which may end the session. Writes nothing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"], description: "With story: the story's system" },
+        story: { type: "string", description: "A story whose linked cases to use" },
+        sources: { type: "array", description: "Or the same sources as find_test_cases", items: { type: "object" } },
+      },
+    },
+    async run(args, ctx) {
+      let cases: JourneyCase[]
+      let story: { id: string; title: string; url: string } | undefined
+      if (args.story) {
+        const found = await storyCases(ctx.config.sources, args.system === "jira" ? "jira" : "azure_devops", String(args.story).trim())
+        story = found.story
+        cases = found.cases.map((c) => ({ id: c.id, title: c.title, url: c.url, steps: c.steps }))
+      } else if (Array.isArray(args.sources) && args.sources.length) {
+        cases = (await casesFrom(args.sources as CaseSelector[], ctx.config.sources, ctx.cwd)).map((c) => ({ id: c.id, title: c.title, url: c.url, startUrl: c.startUrl, steps: c.steps }))
+      } else throw new Error("Give a story (with system), or sources.")
+      const plan = planJourneys(cases)
+      ctx.emit?.({
+        type: "card",
+        card: {
+          status: plan.journeys.length ? "ok" : "info",
+          title: `End-to-end journeys${story ? ` for ${story.id}` : ""}`,
+          stats: `${plan.journeys.length} journeys from ${cases.length} cases · ${plan.stepsSaved} repeated steps saved`,
+          body: [
+            ...plan.journeys.flatMap((j, n) => [
+              `Journey ${n + 1}: ${j.shared.length} shared steps, then ${j.sections.length} cases`,
+              ...j.sections.map((sec) => `    ${sec.negative ? "▲" : "·"} ${sec.caseId}  ${sec.title}  (steps ${sec.from}-${sec.to})`),
+            ]),
+            ...(plan.alone.length ? ["", `On their own: ${plan.alone.map((c) => c.id).join(", ")}`] : []),
+          ],
+        },
+      })
+      return {
+        ...(story ? { story } : {}),
+        journeys: plan.journeys.map((j) => ({
+          start_url: j.startUrl,
+          shared_steps: j.shared.length,
+          steps: j.steps.map((st, i) => `${i + 1}. ${st.action}${st.expected ? ` → ${st.expected}` : ""}`),
+          sections: j.sections.map((sec) => ({ case: sec.caseId, title: sec.title, steps: `${sec.from}-${sec.to}`, ...(sec.negative ? { negative: true } : {}) })),
+          repeated_steps_saved: j.saved,
+        })),
+        on_their_own: plan.alone.map((c) => ({ case: c.id, title: c.title })),
+        next_step: plan.journeys.length
+          ? "Order the sections so each leaves the application in the state the next one needs. A negative section (an error, a refusal, signing out, deleting shared data) goes last or stays its own case. Show the user each journey with the cases it covers. When they agree, save each as one case with save_test_cases, titled \"E2E: …\", with a description naming the cases it covers; keep the original cases. Run a journey instead of its separate cases only when the user asks for an end-to-end run."
+          : "The cases share no first steps, so a journey saves nothing: offer to run them as they are.",
+      }
     },
   },
   {

package/src/mcp/commands.ts

@@ -1,6 +1,7 @@
-import { coverageLines, EXTEND_FROM, measureCoverage, type Candidate } from "../code/coverage.ts"
+import { coverageLines, EXTEND_FROM, measureCoverage, settle, type Candidate } from "../code/coverage.ts"
 import { buildGraph } from "../code/graph/graph.ts"
-import { EXISTING_TEST_FILE } from "../code/notes.ts"
+import { EXISTING_TEST_FILE, EXTEND_TEST_FILE } from "../code/notes.ts"
+import { recordDecision, type DecisionRecord } from "../code/decisions.ts"
 import type { ExistingTest, TestTarget } from "../code/prompt.ts"
 import { existsSync, readFileSync } from "node:fs"
 import path from "node:path"
@@ -33,19 +34,54 @@ const clip = (s: string | undefined, n: number) => {
 /** Marks a browser_run that was a task (a lookup in a tool), not a flow to automate; write_test refuses such runs. */
 
 /**
- * Reuse, extend, or new, from what the repository's tests already cover of the run (code graph and page memory).
- * The clear cases go ahead and say why; where the evidence fits more than one way, the user picks, seeing each
- * option's effect. A mode the user gave (through ForgeQE's agent) is followed without asking.
+ * Reuse, extend, add a test beside one, or new, from what the repository's tests already cover of the run (code graph
+ * and page memory). The clear cases go ahead and say why; where the evidence fits more than one way, the user picks,
+ * seeing each option's effect, and with no one to ask a fixed policy decides (settle). A mode the user gave is followed
+ * as it is; one ForgeQE's agent chose before the browser run is followed too, but a test is not made overlong.
  */
 export async function chooseTarget(runDir: string, repo: string, args: Record<string, any>, ctx: ToolContext): Promise<{ target?: TestTarget } | { cancelled: true }> {
-  const asked = typeof args.mode === "string" && args.mode !== "auto" ? (args.mode as "new" | "extend" | "reuse" | "update") : null
-  if (asked === "new") return {}
+  const asked = typeof args.mode === "string" && args.mode !== "auto" ? (args.mode as "new" | "extend" | "reuse" | "update" | "sibling") : null
+  // ForgeQE's agent chose it before the browser run (args.why); otherwise the user named it.
+  const byAgent = Boolean(args.why)
+  const goal = ((): string => {
+    try {
+      return (JSON.parse(readFileSync(path.join(runDir, "run.json"), "utf8")) as { goal?: string }).goal || ""
+    } catch {
+      return ""
+    }
+  })()
+  const note = (by: NonNullable<DecisionRecord["by"]>, mode: NonNullable<DecisionRecord["mode"]>, c: Candidate | undefined, why: string) =>
+    recordDecision(repo, { goal, stage: "chosen", where: "write_test", by, mode, ...(c ? { test: c.test, file: c.file } : {}), why, run_dir: runDir })
+  if (asked === "new") {
+    note(byAgent ? "agent" : "user", "new", undefined, "asked for a new test")
+    return {}
+  }
   const graph = await buildGraph(repo).catch(() => null)
   if (!graph) return {}
   const cov = measureCoverage(runDir, graph, ctx.config.memory.dir)
-  const named = args.test_file ? cov.candidates.find((c) => c.file === String(args.test_file).replace(/^\.\//, "")) : undefined
+  const file = args.test_file ? String(args.test_file).replace(/^\.\//, "") : ""
+  // A test named but not measured (its page objects do not locate this run's elements) is still the one to work from.
+  const measurable = cov.items.flatMap((it, i) => (it.members.length ? [i] : []))
+  // In a file of many tests, the one named (Class.Method, or its method name) when there is one.
+  const testName = args.test_name ? String(args.test_name) : ""
+  const sameTest = (c: Candidate) => !testName || c.test === testName || c.test.endsWith(`.${testName}`)
+  const lineCount = (test: string) => graph.files.find((f) => f.file === file)?.classes.flatMap((k) => k.members.map((m) => ({ k, m }))).find(({ k, m }) => `${k.name}.${m.name}` === test || m.name === test)
+  const unmeasured = (): Candidate => {
+    const test = testName || path.basename(file).replace(/\.[^.]+$/, "")
+    const at = lineCount(test)
+    return { test: at ? `${at.k.name}.${at.m.name}` : test, file, line: at?.m.line || 1, lines: at ? at.m.endLine - at.m.line + 1 : undefined, covered: [], missing: measurable, share: 0 }
+  }
+  const named = file ? cov.candidates.find((c) => c.file === file && sameTest(c)) || unmeasured() : undefined
   let decision = cov.decision
-  if (asked) decision = { mode: asked, ask: false, target: named || cov.candidates[0], why: "the user asked for it" }
+  if (asked) decision = { mode: asked, ask: false, target: named || cov.candidates[0], why: args.why ? String(args.why) : "the user asked for it" }
+  // Not the user's own choice, and no one to ask, or the agent's: ForgeQE's policy settles it.
+  // Who decided: the user, ForgeQE's agent, the coverage measure, or ForgeQE's policy when it changed or settled it.
+  let by: NonNullable<DecisionRecord["by"]> = asked ? (byAgent ? "agent" : "user") : "coverage"
+  if ((!asked || byAgent) && (byAgent || !decision.ask || !ctx.ask)) {
+    const settled = settle(decision)
+    if (settled.mode !== decision.mode || decision.ask) by = "policy"
+    decision = settled
+  }
   const lines = coverageLines(cov)
   const toTarget = (mode: TestTarget["mode"], c: Candidate): TestTarget => ({
     mode,
@@ -54,7 +90,7 @@ export async function chooseTarget(runDir: string, repo: string, args: Record<st
     line: c.line,
     covered: c.covered.map((i) => cov.items[i]!.label),
     missing: c.missing.map((i) => cov.items[i]!.label),
-    why: `it covers ${c.covered.length} of ${c.covered.length + c.missing.length} steps and checks this run located`,
+    why: c.covered.length ? `it covers ${c.covered.length} of ${c.covered.length + c.missing.length} steps and checks this run located` : decision.why,
   })
   const say = (title: string, why: string) =>
     ctx.emit?.({ type: "card", card: { status: "info", title, stats: why, body: lines.length ? ["What the repository's tests already cover of this run:", ...lines] : [] } })
@@ -62,7 +98,7 @@ export async function chooseTarget(runDir: string, repo: string, args: Record<st
     const options = cov.candidates.filter((c) => c.share >= EXTEND_FROM).slice(0, 2).flatMap((c, n) => {
       const name = `${path.basename(c.file)}`
       return c.missing.length
-        ? [{ id: `extend:${n}`, label: `Extend ${name} (adds ${c.missing.length})` }]
+        ? [{ id: `extend:${n}`, label: `Extend ${name} (adds ${c.missing.length})` }, ...(n === 0 ? [{ id: `sibling:${n}`, label: `Add a test beside ${c.test.split(".").pop()} in ${name}` }] : [])]
         : [{ id: `reuse:${n}`, label: `Reuse ${name} as it is` }]
     })
     const answer = await ctx.ask({
@@ -72,18 +108,26 @@ export async function chooseTarget(runDir: string, repo: string, args: Record<st
       options: [...options, { id: "new", label: "Write a new test" }, { id: "cancel", label: "Cancel" }],
     })
     if (!answer || answer === "cancel") return { cancelled: true }
-    if (answer === "new") return {}
-    const [mode, n] = answer.split(":") as ["reuse" | "extend", string]
+    if (answer === "new") {
+      note("user", "new", undefined, `${decision.why}; the user chose a new test`)
+      say("Writing a new test", "the user chose it")
+      return {}
+    }
+    const [mode, n] = answer.split(":") as ["reuse" | "extend" | "sibling", string]
     const c = cov.candidates.filter((x) => x.share >= EXTEND_FROM)[Number(n)]!
-    say(mode === "reuse" ? `Reusing ${c.test}` : `Extending ${c.test}`, "the user chose it")
+    note("user", mode, c, `${decision.why}; the user chose it`)
+    say(mode === "reuse" ? `Reusing ${c.test}` : mode === "sibling" ? `Adding a test beside ${c.test}` : `Extending ${c.test}`, "the user chose it")
     return { target: toTarget(mode, c) }
   }
   if (decision.mode === "new" || !decision.target) {
+    note(by, "new", undefined, decision.why)
     if (cov.candidates.length) say("Writing a new test", decision.why)
     return {}
   }
-  const mode: TestTarget["mode"] = decision.mode === "reuse" ? "reuse" : decision.mode === "update" ? "update" : "extend"
-  say(mode === "reuse" ? `Reusing ${decision.target.test}` : mode === "update" ? `Updating ${decision.target.test}` : `Extending ${decision.target.test}`, decision.why)
+  const mode: TestTarget["mode"] = decision.mode === "reuse" || decision.mode === "update" || decision.mode === "sibling" ? decision.mode : "extend"
+  const verb = { reuse: "Reusing", update: "Updating", sibling: "Adding a test beside", extend: "Extending" }[mode]
+  note(by, mode, decision.target, decision.why)
+  say(`${verb} ${decision.target.test}`, decision.why)
   return { target: toTarget(mode, decision.target) }
 }
 
@@ -158,11 +202,12 @@ export const COMMAND_TOOLS: McpTool[] = [
         repo: { type: "string", description: "Repository to write the test in, relative to the working directory (default: the working directory)" },
         mode: {
           type: "string",
-          enum: ["auto", "new", "extend", "reuse", "update"],
+          enum: ["auto", "new", "extend", "reuse", "update", "sibling"],
           description:
-            "auto (default): ForgeQE measures which existing tests already cover the run, then reuses one that covers it all, extends one that covers most, or writes a new test, and asks the user when that is not clear. new, extend, reuse, update: only when the user said which (\"extend the login test\", \"write a separate test\", \"update it\" after a reused test failed).",
+            "auto (default): ForgeQE measures which existing tests already cover the run, then reuses one that covers it all, extends one that covers most (or adds a test beside it, in its class, when it is already long), or writes a new test that reuses the repository's code, and asks the user when that is not clear. new, extend, reuse, update, sibling: only when the user said which (\"extend the login test\", \"add a separate test next to it\", \"write a separate test\", \"update it\" after a reused test failed).",
         },
-        test_file: { type: "string", description: "With mode extend, reuse, or update: the existing test file (from the user, or from an earlier write_test result)" },
+        test_file: { type: "string", description: "With mode extend, reuse, update, or sibling: the existing test file (from the user, or from an earlier write_test result)" },
+        test_name: { type: "string", description: "With test_file: the test in it (Class.Method or the method name), when the file has more than one" },
       },
     },
     async run(args, ctx) {
@@ -177,8 +222,16 @@ export const COMMAND_TOOLS: McpTool[] = [
       const goal = (readJson(path.join(runDir, "run.json")) as { goal?: string } | null)?.goal || ""
       // browser_run found an earlier test for this flow and it failed: Scribe updates it rather than adding another.
       const existingTest = readJson(path.join(runDir, EXISTING_TEST_FILE)) as ExistingTest | null
+      // ForgeQE's agent chose, before the browser ran, to extend an earlier test: that test, unless the user says otherwise.
+      const extend = readJson(path.join(runDir, EXTEND_TEST_FILE)) as { testFile?: string; test?: string; mode?: "extend" | "sibling" } | null
+      // The agent repeating that choice to write_test (its mode and file) is still the agent's choice, not the user's.
+      const sameChoice = extend?.testFile && args.mode === (extend.mode || "extend") && (!args.test_file || String(args.test_file).replace(/^\.\//, "") === extend.testFile)
+      const how =
+        extend?.testFile && (!args.mode || args.mode === "auto" || sameChoice)
+          ? { ...args, mode: extend.mode || "extend", test_file: extend.testFile, ...(extend.test ? { test_name: extend.test } : {}), why: "chosen before the browser run, from the existing tests closest to this flow" }
+          : args
       // Otherwise: what the repository's tests already cover of this run decides reuse, extend, or new.
-      const chosen = existingTest?.testFile ? { target: undefined } : await chooseTarget(runDir, repo, args, ctx)
+      const chosen = existingTest?.testFile ? { target: undefined } : await chooseTarget(runDir, repo, how, ctx)
       if ("cancelled" in chosen) return { status: "cancelled", notes: "The user cancelled before Scribe started; nothing was changed." }
       const target = chosen.target
       ctx.emit?.({ type: "code-start", runDir, repo, goal })
@@ -200,6 +253,7 @@ export const COMMAND_TOOLS: McpTool[] = [
         throw err
       }
       ctx.emit?.({ type: "code-done", result: r, ms: Date.now() - t0 })
+      recordDecision(repo, { goal, stage: "outcome", where: "write_test", status: r.status, ...(r.existing ? { existing: r.existing } : {}), ...(r.testFile ? { file: r.testFile } : {}), ...(target ? { mode: target.mode, test: target.test } : existingTest ? { mode: "update" } : { mode: "new" }), ...(r.breaches ? { breaches: r.breaches } : {}), run_dir: runDir })
       ctx.emit?.({ type: "card", card: codeCard(buildCodeSummary(r, Date.now() - t0)) })
       return {
         status: r.status,

package/src/mcp/packtools.ts

@@ -0,0 +1,187 @@
+import { realpathSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import { listPacks, loadPack, makePack, packCard, packMarkdown, packRunCard, runPack, type PackSources } from "../pack/index.ts"
+import { packsDir } from "../pack/pack.ts"
+import { runPackOnPipeline } from "../pack/pipeline.ts"
+import type { McpTool, ToolContext } from "./tools.ts"
+
+const clip = (s: string | undefined, n: number) => {
+  const t = (s || "").trim()
+  return t.length <= n ? t : `…${t.slice(-(n - 1))}`
+}
+
+function repoOf(ctx: ToolContext, given?: unknown): string {
+  const p = given ? path.resolve(ctx.cwd, String(given)) : ctx.cwd
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+const ITEM_SCHEMA = {
+  type: "object",
+  properties: {
+    source: { type: "string", description: "The tool it came from: jira, github, azure_devops, confluence, linear…" },
+    id: { type: "string" },
+    title: { type: "string" },
+    text: { type: "string", description: "What changes, in its words: description, acceptance criteria, release note" },
+    url: { type: "string" },
+    type: { type: "string", description: "Story, Bug, Feature, Task…" },
+    kind: { type: "string", enum: ["work_item", "pr", "commit", "note"] },
+    files: { type: "array", items: { type: "string" }, description: "Files it changed, when known" },
+    links: { type: "array", items: { type: "string" }, description: "Work items it refers to: ado:123, jira:PAY-12, github:45" },
+    test_cases: { type: "array", items: { type: "string" }, description: "Test cases that test it (Azure DevOps ids, or ADO-123)" },
+  },
+  required: ["title"],
+}
+
+export const PACK_TOOLS: McpTool[] = [
+  {
+    name: "build_regression_pack",
+    description:
+      "Build a regression pack: the repository's tests that a release's changes can break, each with why it is in (it automates a test case of a changed work item; the change is in the test code it uses; the work item's words match what it does; it works in a risk area the release touches; it is a smoke test), and the changes no test covers, each with the closest test and what it lacks. Changes come from any mix of: an Azure DevOps sprint, area, epic, or work item ids (with their linked pull requests' files); the commits between two refs of a repository; pull requests by number or merged in the last days; and items you read from any other connected tool (Jira, GitHub issues, a release note), passed in items. Saves the pack by name in .forgeqe/packs and shows a card. Nothing runs. Takes seconds.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The pack's name, e.g. release-1.5 (default: release-<date>)" },
+        repo: { type: "string", description: "The test repository (default: the working directory)" },
+        sprint: { type: "string", description: "Azure DevOps sprint name of the team, or current" },
+        iteration: { type: "string", description: "Azure DevOps iteration path and everything under it: a release such as Release 2026.09, or Project\\Release 2026.09\\Sprint 13" },
+        area: { type: "string", description: "Azure DevOps area path" },
+        parent: { type: "number", description: "An Azure DevOps epic or feature: everything under it" },
+        work_items: { type: "array", items: { type: "number" }, description: "Azure DevOps work item ids" },
+        project: { type: "string", description: "Azure DevOps project (default: sources.azure_devops.project)" },
+        range_repo: { type: "string", description: "Repository for from/to (the product's, or the tests' own); default: the test repository" },
+        from: { type: "string", description: "Commits after this ref: a tag, branch, or commit (e.g. release/1.4)" },
+        to: { type: "string", description: "Commits up to this ref (default HEAD)" },
+        prs: { type: "array", items: { type: "string" }, description: "Pull request numbers or URLs" },
+        merged_days: { type: "number", description: "Pull requests merged in the last N days" },
+        pr_repo: { type: "string", description: "Repository the pull requests are in (default: the test repository)" },
+        items: { type: "array", items: ITEM_SCHEMA, description: "Changes you read from other connected tools, as they are" },
+        risk: { type: "boolean", description: "Add tests for risk areas the release touches (default true)" },
+        smoke: { type: "boolean", description: "Add smoke-tagged tests (default true)" },
+      },
+    },
+    async run(args, ctx) {
+      const repo = repoOf(ctx, args.repo)
+      const sources: PackSources = {
+        ...(args.sprint || args.iteration || args.area || args.parent || (Array.isArray(args.work_items) && args.work_items.length)
+          ? { ado: { ...(args.sprint ? { sprint: String(args.sprint) } : {}), ...(args.iteration ? { iteration: String(args.iteration) } : {}), ...(args.area ? { area: String(args.area) } : {}), ...(args.parent ? { parent: Number(args.parent) } : {}), ...(Array.isArray(args.work_items) ? { ids: args.work_items.map(Number).filter(Boolean) } : {}), ...(args.project ? { project: String(args.project) } : {}) } }
+          : {}),
+        ...(args.from ? { range: { repo: repoOf(ctx, args.range_repo || args.repo), from: String(args.from), ...(args.to ? { to: String(args.to) } : {}) } } : {}),
+        ...(Array.isArray(args.prs) && args.prs.length ? { prs: args.prs.map(String) } : {}),
+        ...(Number(args.merged_days) > 0 ? { mergedDays: Number(args.merged_days) } : {}),
+        ...(args.pr_repo ? { prRepo: repoOf(ctx, args.pr_repo) } : {}),
+        ...(Array.isArray(args.items) && args.items.length ? { items: args.items } : {}),
+      }
+      const pack = await makePack({ config: ctx.config, repo, name: args.name ? String(args.name) : undefined, sources, risk: args.risk !== false, smoke: args.smoke !== false })
+      const md = path.join(packsDir(repo), `${pack.name}.md`)
+      writeFileSync(md, `${packMarkdown(pack)}\n`)
+      ctx.emit?.({ type: "card", card: packCard(pack) })
+      return {
+        name: pack.name,
+        tests: pack.tests.map((t) => ({ test: t.test, file: t.file, why: [...new Set(t.reasons.map((r) => r.text))], ...(t.flaky ? { flaky: t.flaky } : {}) })),
+        changes: pack.items.length,
+        from: pack.scope,
+        not_covered: pack.uncovered,
+        risk_areas: pack.risk,
+        notes: pack.notes.length ? pack.notes : undefined,
+        file: md,
+        next_step: [
+          pack.tests.length ? `Offer to run it: run_regression_pack with name ${pack.name} and on local, testmu, or pipeline.` : "",
+          pack.uncovered.length ? "Name the changes no test covers. For one with a closest test, offer to extend that test (browser_run with existing_test and existing_mode extend), so the next pack covers it." : "",
+        ]
+          .filter(Boolean)
+          .join(" "),
+      }
+    },
+  },
+  {
+    name: "run_regression_pack",
+    description:
+      "Run a saved regression pack after the user confirms: on local (this machine's browsers), testmu (TestMu AI's cloud browsers: the repository's tests connect to them through FORGEQE_PW_WS_ENDPOINT), or pipeline (a CI pipeline runs it). Reads each test's result, keeps the run with the pack, and says what changed since its last run. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed. Takes minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The pack's name" },
+        on: { type: "string", enum: ["local", "testmu", "pipeline"], description: "Where to run it (default local)" },
+        pipeline: { type: "string", enum: ["github", "azure_devops"], description: "With on pipeline: which one (default: packs.pipeline.default in forgeqe.yaml)" },
+        browsers: { type: "string", enum: ["local", "testmu"], description: "With on pipeline: the runner's own browser, or TestMu AI's (default local)" },
+        repo: { type: "string", description: "The test repository (default: the working directory)" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to this run" },
+      },
+      required: ["name"],
+    },
+    async run(args, ctx) {
+      const repo = repoOf(ctx, args.repo)
+      const pack = loadPack(repo, String(args.name))
+      const on = args.on === "testmu" || args.on === "pipeline" ? args.on : "local"
+      const browsers = args.browsers === "testmu" ? "testmu" : "local"
+      const where = on === "testmu" ? "on TestMu AI" : on === "pipeline" ? `in the ${args.pipeline === "azure_devops" ? "Azure DevOps" : args.pipeline === "github" ? "GitHub Actions" : "configured"} pipeline${browsers === "testmu" ? " on TestMu AI" : ""}` : "on this machine"
+      const what = `${pack.tests.length} test${pack.tests.length === 1 ? "" : "s"}`
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Run pack ${pack.name} (${what}) ${where}?`,
+          lines: pack.tests.slice(0, 20).map((t) => `  • ${t.test}`).concat(pack.tests.length > 20 ? [`  and ${pack.tests.length - 20} more`] : []),
+          options: [
+            { id: "run", label: `Run ${what} ${where}` },
+            { id: "no", label: "Don't run" },
+          ],
+        })
+        if (choice !== "run") return { ran: false, reason: "The user chose not to run it." }
+      } else if (args.confirmed !== true) {
+        return { ran: false, needs_confirmation: true, tests: pack.tests.map((t) => t.test), on, next_step: "Show the user the pack and where it runs; call run_regression_pack again with confirmed: true only after they say yes." }
+      }
+      const { run, record, notes, pack: after } =
+        on === "pipeline"
+          ? await runPackOnPipeline({
+              config: ctx.config,
+              repo,
+              name: pack.name,
+              ...(args.pipeline === "github" || args.pipeline === "azure_devops" ? { kind: args.pipeline } : {}),
+              target: browsers,
+              signal: ctx.signal,
+              onProgress: (text) => ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text } }),
+            })
+          : await runPack({ config: ctx.config, repo, name: pack.name, on, signal: ctx.signal, runTest: ctx.runTest })
+      ctx.emit?.({ type: "card", card: packRunCard(after, run, record, notes) })
+      const failed = run.tests.filter((t) => t.status === "failed")
+      return {
+        ran: true,
+        on: record.target,
+        status: run.status,
+        passed: run.counts.passed,
+        failed: run.counts.failed,
+        skipped: run.counts.skipped,
+        seconds: run.seconds,
+        failures: failed.length ? failed.map((t) => ({ name: t.name, message: t.message })) : undefined,
+        ...(run.flaky?.length ? { flaky: run.flaky } : {}),
+        previous: after.runs.at(-2) || undefined,
+        output: run.status === "passed" ? undefined : clip(run.output, 3000),
+        folder: run.dir,
+        ...(record.url ? { pipeline_run: record.url } : {}),
+        notes: notes.length ? notes : undefined,
+        next_step: failed.length ? "Name the failing tests with their messages; offer heal_tests for a test the app outgrew, or file the defects (file_bug)." : undefined,
+      }
+    },
+  },
+  {
+    name: "list_regression_packs",
+    description: "The saved regression packs of a repository: name, when built, from what, how many tests and gaps, and their last run. Nothing runs.",
+    inputSchema: { type: "object", properties: { repo: { type: "string" } } },
+    async run(args, ctx) {
+      return {
+        packs: listPacks(repoOf(ctx, args.repo)).map((p) => ({
+          name: p.name,
+          built: p.createdAt.slice(0, 16).replace("T", " "),
+          from: p.scope,
+          tests: p.tests.length,
+          not_covered: p.uncovered.length,
+          last_run: p.runs.at(-1) ? { at: p.runs.at(-1)!.at.slice(0, 16).replace("T", " "), on: p.runs.at(-1)!.target, status: p.runs.at(-1)!.status, failed: p.runs.at(-1)!.counts.failed } : undefined,
+        })),
+      }
+    },
+  },
+]