@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/mcp/external.ts

@@ -0,0 +1,172 @@
+import type { AppConfig } from "../config.ts"
+
+/** Azure DevOps MCP tool groups ForgeQE loads unless sources.azure_devops.mcp_domains says otherwise: every group the server has. */
+export const ADO_DOMAINS = ["all"]
+export const ROVO_URL = "https://mcp.atlassian.com/v2/mcp"
+/** Also the time allowed for the first start, when npx or uvx downloads the server. */
+const TIMEOUT_MS = 120_000
+
+export type ExternalServer = {
+  /** The agent runtime's name for the server; its tools are called `<name>_<tool>`. */
+  name: string
+  label: string
+  /** For the agent: what the server is for. */
+  about: string
+  config: Record<string, unknown>
+  /** Values ForgeQE derives from its environment (e.g. base64 of email:token) for {env:} references in config. */
+  secrets: Record<string, string>
+}
+
+export type ExternalPlan = { servers: ExternalServer[]; skipped: { label: string; why: string }[] }
+
+type Which = (bin: string) => string | null
+
+const b64 = (s: string) => Buffer.from(s).toString("base64")
+
+/** The organization name Microsoft's MCP server takes, or null for Azure DevOps Server (on-premises). */
+export function adoOrganization(orgUrl: string): string | null {
+  let u: URL
+  try {
+    u = new URL(orgUrl)
+  } catch {
+    return null
+  }
+  if (u.hostname === "dev.azure.com") return u.pathname.split("/").filter(Boolean)[0] || null
+  return u.hostname.match(/^([^.]+)\.visualstudio\.com$/)?.[1] || null
+}
+
+/**
+ * MCP servers for the systems in forgeqe.yaml: Microsoft's Azure DevOps server, mcp-atlassian or Atlassian's hosted
+ * server for Jira, and anything under `mcp:`. Credentials stay in the environment: configs refer to them as {env:NAME}.
+ * A system whose server cannot start here is listed in `skipped`; ForgeQE's own API tools still cover it.
+ */
+export function externalMcp(cfg: AppConfig, which: Which = Bun.which, env: NodeJS.ProcessEnv = process.env): ExternalPlan {
+  const servers: ExternalServer[] = []
+  const skipped: ExternalPlan["skipped"] = []
+  const { ado, jira, confluence: conf } = cfg.sources
+  const confMissing = conf ? [conf.cloud && !env[conf.emailEnv] ? conf.emailEnv : "", env[conf.tokenEnv] ? "" : conf.tokenEnv].filter(Boolean) : []
+  const confVars: Record<string, string> | undefined =
+    conf && !confMissing.length
+      ? {
+          CONFLUENCE_URL: conf.url,
+          ...(conf.cloud ? { CONFLUENCE_USERNAME: `{env:${conf.emailEnv}}`, CONFLUENCE_API_TOKEN: `{env:${conf.tokenEnv}}` } : { CONFLUENCE_PERSONAL_TOKEN: `{env:${conf.tokenEnv}}` }),
+          ...(conf.space ? { CONFLUENCE_SPACES_FILTER: conf.space } : {}),
+        }
+      : undefined
+  let confCovered = false
+
+  if (ado && ado.mcp !== false) {
+    const label = "Azure DevOps MCP"
+    const org = adoOrganization(ado.orgUrl)
+    const pat = env[ado.tokenEnv]
+    const auth = pat ? "pat" : which("az") ? "azcli" : null
+    if (!org) skipped.push({ label, why: "Microsoft's server supports Azure DevOps Services only, not Azure DevOps Server" })
+    else if (!which("npx")) skipped.push({ label, why: "it needs Node.js (npx)" })
+    else if (!auth) skipped.push({ label, why: `set ${ado.tokenEnv}, or sign in with az login` })
+    else {
+      servers.push({
+        name: "azure_devops",
+        label,
+        about:
+          `Microsoft's Azure DevOps MCP server: organization ${org}${ado.project ? `, project ${ado.project}` : ", every project"} (work items, boards, test plans, pipelines, repos, wiki pages, search across code, wikis and work items, security alerts). ` +
+          "Always pass project to its tools that take one: without it the server asks the client to pick a project, which this session cannot answer, so the call fails. " +
+          "Its wiki tools only work in a wiki that exists and cannot create one; write wiki pages with ForgeQE's write_ado_wiki_page, which creates the project wiki when there is none. " +
+          (ado.project
+            ? `Use ${ado.project} unless the user names another project.`
+            : "Work item ids are unique in the organization, so getting a work item by id works with any project name (from azure_devops_core_list_projects); its System.TeamProject field says which project it is in, so use that project for follow-up calls on it."),
+        config: {
+          type: "local",
+          command: ["npx", "-y", "@azure-devops/mcp", org, "-a", auth, "-d", ...(ado.mcpDomains || ADO_DOMAINS)],
+          ...(pat ? { environment: { PERSONAL_ACCESS_TOKEN: "{env:FORGEQE_ADO_MCP_TOKEN}" } } : {}),
+          enabled: true,
+          timeout: TIMEOUT_MS,
+        },
+        secrets: pat ? { FORGEQE_ADO_MCP_TOKEN: b64(`forgeqe:${pat}`) } : {},
+      })
+    }
+  }
+
+  if (jira && jira.mcp !== false) {
+    const email = jira.cloud ? env[jira.emailEnv] : undefined
+    const token = env[jira.tokenEnv]
+    const missing = [jira.cloud && !email ? jira.emailEnv : "", token ? "" : jira.tokenEnv].filter(Boolean)
+    if (jira.mcp === "rovo") {
+      const label = "Atlassian Rovo MCP"
+      if (!jira.cloud) skipped.push({ label, why: "Atlassian's hosted server is for Jira Cloud; use mcp: mcp-atlassian for Server/Data Center" })
+      else if (missing.length) skipped.push({ label, why: `set ${missing.join(" and ")}` })
+      else {
+        confCovered = Boolean(conf?.cloud && new URL(conf.url).host === new URL(jira.url).host)
+        servers.push({
+          name: "atlassian",
+          label,
+          about: `Atlassian's Rovo MCP server for ${jira.url} (Jira issues, JQL search, comments, transitions${confCovered ? "; Confluence pages and CQL search" : ""}; pass the cloudId where a tool asks for it)`,
+          config: { type: "remote", url: ROVO_URL, headers: { Authorization: "Basic {env:FORGEQE_ATLASSIAN_MCP_AUTH}" }, oauth: false, enabled: true, timeout: TIMEOUT_MS },
+          secrets: { FORGEQE_ATLASSIAN_MCP_AUTH: b64(`${email}:${token}`) },
+        })
+      }
+    } else {
+      const label = "Jira MCP (mcp-atlassian)"
+      if (!which("uvx")) skipped.push({ label, why: "it needs uv (uvx)" })
+      else if (missing.length) skipped.push({ label, why: `set ${missing.join(" and ")}` })
+      else {
+        const credentials = jira.cloud
+          ? { JIRA_USERNAME: `{env:${jira.emailEnv}}`, JIRA_API_TOKEN: `{env:${jira.tokenEnv}}` }
+          : { JIRA_PERSONAL_TOKEN: `{env:${jira.tokenEnv}}` }
+        confCovered = Boolean(confVars)
+        servers.push({
+          name: "atlassian",
+          label,
+          about: `mcp-atlassian for Jira ${jira.cloud ? "Cloud" : "Server/Data Center"} at ${jira.url} (issues, JQL search, comments, transitions)${confVars ? ` and Confluence at ${conf!.url} (pages, CQL search)` : ""}`,
+          config: {
+            type: "local",
+            command: ["uvx", "mcp-atlassian"],
+            environment: { JIRA_URL: jira.url, ...credentials, ...confVars, TOOLSETS: "default" },
+            enabled: true,
+            timeout: TIMEOUT_MS,
+          },
+          secrets: {},
+        })
+      }
+    }
+  }
+
+  if (conf && !confCovered) {
+    const label = "Confluence MCP (mcp-atlassian)"
+    if (!which("uvx")) skipped.push({ label, why: "it needs uv (uvx)" })
+    else if (!confVars) skipped.push({ label, why: `set ${confMissing.join(" and ")}` })
+    else {
+      servers.push({
+        name: "confluence",
+        label,
+        about: `mcp-atlassian for Confluence ${conf.cloud ? "Cloud" : "Server/Data Center"} at ${conf.url} (pages, CQL search)`,
+        config: { type: "local", command: ["uvx", "mcp-atlassian"], environment: { ...confVars, TOOLSETS: "default" }, enabled: true, timeout: TIMEOUT_MS },
+        secrets: {},
+      })
+    }
+  }
+
+  for (const [name, server] of Object.entries(cfg.mcp || {})) {
+    const at = servers.findIndex((s) => s.name === name)
+    if (at >= 0) servers.splice(at, 1)
+    if (server.enabled === false) continue
+    servers.push({
+      name,
+      label: `${name} MCP`,
+      about: `${name}: ${server.type === "remote" ? server.url : server.command.join(" ")} (from forgeqe.yaml)`,
+      config: { ...server, enabled: true, timeout: server.timeout ?? TIMEOUT_MS },
+      secrets: {},
+    })
+  }
+  return { servers, skipped }
+}
+
+/** Lines for the agent's session notes. */
+export function externalNotes(plan: ExternalPlan): string[] {
+  if (!plan.servers.length && !plan.skipped.length) return []
+  return [
+    ...(plan.servers.length
+      ? ["MCP servers for other systems (tools are named <server>_<tool>; a server whose tools are missing did not connect):", ...plan.servers.map((s) => `- ${s.name}: ${s.about}`)]
+      : []),
+    ...plan.skipped.map((s) => `${s.label} is not available (${s.why}); use ForgeQE's tools for that system.`),
+  ]
+}

package/src/mcp/git.ts

@@ -0,0 +1,78 @@
+import { withoutTelemetry } from "../privacy.ts"
+
+export type Out = { code: number; out: string }
+
+export async function sh(cmd: string[], cwd: string, opts: { env?: Record<string, string>; stdin?: string } = {}): Promise<Out> {
+  const proc = Bun.spawn(cmd, {
+    cwd,
+    env: { ...withoutTelemetry(process.env), GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1", NO_COLOR: "1", ...opts.env },
+    stdin: opts.stdin === undefined ? "ignore" : new Blob([opts.stdin]),
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited])
+  return { code, out: [out, err].filter((s) => s.trim()).join("\n").trim() }
+}
+
+/** The remote's default branch (origin/HEAD), or null when the clone does not know it. */
+async function defaultBranch(cwd: string, remote: string): Promise<string | null> {
+  const head = await sh(["git", "symbolic-ref", "--quiet", "--short", `refs/remotes/${remote}/HEAD`], cwd)
+  if (head.code === 0 && head.out) return head.out.replace(`${remote}/`, "")
+  const show = await sh(["git", "ls-remote", "--symref", remote, "HEAD"], cwd)
+  return show.out.match(/ref: refs\/heads\/(\S+)\s+HEAD/)?.[1] || null
+}
+
+/**
+ * Push the current commit to `branch` on the remote. Never the remote's default branch, never main or master, and
+ * never forced; the agent has no other way to push.
+ */
+export async function pushBranch(cwd: string, branch: string, remote = "origin"): Promise<string> {
+  const name = branch.trim().replace(/^refs\/heads\//, "")
+  const valid = await sh(["git", "check-ref-format", "--branch", name], cwd)
+  if (!name || valid.code !== 0 || name.startsWith("-")) throw new Error(`"${branch}" is not a valid branch name.`)
+  const main = await defaultBranch(cwd, remote)
+  const blocked = new Set(["main", "master", ...(main ? [main] : [])])
+  if (blocked.has(name)) throw new Error(`Refusing to push to ${name}: it is the default branch. Push to a new branch instead.`)
+  const res = await sh(["git", "push", "--set-upstream", remote, `HEAD:refs/heads/${name}`], cwd)
+  if (res.code !== 0) throw new Error(`git push to ${remote}/${name} failed:\n${res.out.slice(-3000)}`)
+  const sha = (await sh(["git", "rev-parse", "--short", "HEAD"], cwd)).out
+  return `Pushed ${sha} to ${remote}/${name}.${res.out ? `\n${res.out.slice(-1500)}` : ""}`
+}
+
+export type SecretTarget = {
+  platform: "github" | "azure_devops"
+  name: string
+  /** github: owner/repo (default: the repo in cwd). */
+  repo?: string
+  /** azure_devops: pipeline name. */
+  pipeline?: string
+  org?: string
+  project?: string
+}
+
+/**
+ * Store an environment variable of this process as a pipeline secret. The value goes to gh on stdin, or to az through
+ * its AZURE_DEVOPS_EXT_PIPELINE_VAR_ variable; it is never in argv, a result, or an error message.
+ */
+export async function setCiSecret(cwd: string, t: SecretTarget): Promise<string> {
+  const name = t.name.trim()
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`"${t.name}" is not a valid secret name.`)
+  const value = process.env[name]
+  if (!value) throw new Error(`${name} is not set in ForgeQE's environment, so there is no value to store. Ask the user to export it and restart ForgeQE.`)
+  const scrub = (s: string) => s.split(value).join("***")
+
+  if (t.platform === "github") {
+    const res = await sh(["gh", "secret", "set", name, ...(t.repo ? ["--repo", t.repo] : [])], cwd, { stdin: value })
+    if (res.code !== 0) throw new Error(`gh secret set ${name} failed: ${scrub(res.out).slice(-1500)}`)
+    return `GitHub Actions secret ${name} set${t.repo ? ` on ${t.repo}` : ""} from the environment.`
+  }
+
+  if (!t.pipeline) throw new Error("Azure DevOps secrets need the pipeline name.")
+  const scope = [...(t.org ? ["--org", t.org] : []), ...(t.project ? ["--project", t.project] : [])]
+  const env = { [`AZURE_DEVOPS_EXT_PIPELINE_VAR_${name}`]: value }
+  const args = (verb: "create" | "update") => ["az", "pipelines", "variable", verb, "--name", name, "--secret", "true", "--pipeline-name", t.pipeline!, ...scope, "--output", "none"]
+  let res = await sh(args("create"), cwd, { env })
+  if (res.code !== 0 && /already exists/i.test(res.out)) res = await sh(args("update"), cwd, { env })
+  if (res.code !== 0) throw new Error(`az pipelines variable ${name} failed: ${scrub(res.out).slice(-1500)}`)
+  return `Azure Pipelines secret variable ${name} set on ${t.pipeline} from the environment.`
+}

package/src/mcp/notifytools.ts

@@ -0,0 +1,49 @@
+import { NOTIFY_EVENTS } from "../config.ts"
+import { notifiedLine, reportLinks } from "../notify/events.ts"
+import { sendNotice, type Notice, type Status } from "../notify/notice.ts"
+import type { McpTool } from "./tools.ts"
+
+const STATUSES: Status[] = ["good", "bad", "warn"]
+
+/** Posting to the team's channels on request; what is posted without asking is set per channel in forgeqe.yaml. */
+export const NOTIFY_TOOLS: McpTool[] = [
+  {
+    name: "notify",
+    description:
+      `Post a message to the team's notification channels (notify.channels in forgeqe.yaml: Teams channels and email), only when the user asks for it ("post the results to the QA channel", "tell the team the release is NO-GO"). A card with a title, a status colour, one line per point, and an optional link to a report or page. Channels also get some events without asking (${NOTIFY_EVENTS.join(", ")}) from runs outside the shell, so do not post those again.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "One line, e.g. Checkout suite: 2 of 14 cases failed" },
+        status: { type: "string", enum: STATUSES, description: "good (green), bad (red), or warn (amber)" },
+        lines: { type: "array", items: { type: "string" }, description: "The points, one line each: what failed and why, what to do" },
+        report: { type: "string", description: "A report file under the reports folder, linked when the folder is published (notify.report_url)" },
+        link: { type: "object", properties: { title: { type: "string" }, url: { type: "string" } }, required: ["title", "url"], description: "A page to open, e.g. a pull request or a wiki page" },
+        channels: { type: "array", items: { type: "string" }, description: "Channel names from forgeqe.yaml; default every channel" },
+      },
+      required: ["title", "status", "lines"],
+    },
+    async run(args, ctx) {
+      const all = ctx.config.notify?.channels || []
+      if (!all.length) throw new Error("No notification channels: add notify.channels to forgeqe.yaml (a Teams webhook_env or email for each).")
+      const names: string[] = Array.isArray(args.channels) && args.channels.length ? args.channels.map(String) : all.map((c) => c.name)
+      const unknown = names.filter((n) => !all.some((c) => c.name === n))
+      if (unknown.length) throw new Error(`No channel ${unknown.join(", ")}. Channels: ${all.map((c) => c.name).join(", ")}.`)
+      const links = reportLinks(ctx.config, args.report ? String(args.report) : undefined)
+      const link = args.link?.url ? [{ title: String(args.link.title || "Open"), url: String(args.link.url) }] : []
+      const notice: Notice = {
+        source: "ForgeQE",
+        title: String(args.title),
+        status: STATUSES.includes(args.status) ? args.status : "warn",
+        subtitle: new Date().toLocaleString(),
+        items: (Array.isArray(args.lines) ? args.lines : []).map((l: unknown) => ({ line: String(l) })),
+        actions: [...link, ...links.actions],
+        ...(links.note ? { note: links.note } : {}),
+      }
+      const sent = await Promise.all(all.filter((c) => names.includes(c.name)).map(async (c) => ({ channel: c.name, sent: await sendNotice(c, notice) })))
+      const text = notifiedLine(sent)
+      ctx.emit?.({ type: "info", text, ok: sent.every((s) => s.sent.every((x) => x.ok)) })
+      return { notified: text }
+    },
+  },
+]

package/src/mcp/prtools.ts

@@ -0,0 +1,261 @@
+import path from "node:path"
+
+import { noAgentModel } from "../llm.ts"
+import { existsSync, readFileSync } from "node:fs"
+
+import { loadSelection, selectionCard, type TestsRun } from "../code/find.ts"
+import { loadReview, postPrComment, postReview, resolvePr, reviewCard, reviewPullRequest, type Platform } from "../code/prreview.ts"
+import { resultsMarkdown, selectPrTests } from "../code/prtests.ts"
+import { analyzeAreas, type AreaImpact } from "../code/areas.ts"
+import { gitRemotes, parsePrRef } from "../code/prreview.ts"
+import type { Card } from "../card.ts"
+import type { McpTool } from "./tools.ts"
+
+/** Review a pull request with Scribe, then post the findings to it once the user agrees. */
+export const PR_TOOLS: McpTool[] = [
+  {
+    name: "review_pull_request",
+    description:
+      "Review a pull request in Azure DevOps or GitHub. ForgeQE reads the pull request (description, branches, linked work items or issues), fetches its branches into the local clone and checks the head out in a temporary worktree (the user's branch and files are not touched), and Scribe, the coding agent, reviews the diff with the code around it for bugs, security, requirements, tests, and performance. Shows the findings to the user and returns review_id for post_pr_review; nothing is posted. Takes a few minutes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pr: { type: "string", description: "The pull request's link, or its number in the working directory's repository (e.g. 42, #42, !42)" },
+        platform: { type: "string", enum: ["azure_devops", "github"], description: "For a number, when the clone has both kinds of remote" },
+        repo: { type: "string", description: "Local clone of the pull request's repository, relative to the working directory (default: the working directory)" },
+        focus: { type: "string", description: "What the user wants the review to concentrate on, in their words" },
+      },
+      required: ["pr"],
+    },
+    async run(args, ctx) {
+      const noModel = noAgentModel(ctx.config.llm, ctx.config.code.model, "Scribe")
+      if (noModel) throw new Error(noModel)
+      const pr = String(args.pr || "").trim()
+      if (!pr) throw new Error("pr is required.")
+      const review = await reviewPullRequest({
+        config: ctx.config,
+        repo: args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.cwd,
+        pr,
+        platform: args.platform as Platform | undefined,
+        focus: args.focus ? String(args.focus) : undefined,
+        signal: ctx.signal,
+        onEvent: (event) => ctx.emit?.({ type: "agent", event }),
+        open: ctx.openSession as never,
+      })
+      ctx.emit?.({ type: "card", card: reviewCard(review, ctx.cwd) })
+      const inline = review.inline.filter(Boolean).length
+      return {
+        review_id: review.id,
+        pull_request: review.pr.url,
+        title: review.pr.title,
+        verdict: review.verdict,
+        summary: review.summary,
+        findings: review.findings,
+        files_changed: review.files.length,
+        report: path.join(review.dir, "review.md"),
+        next_step: review.findings.length
+          ? `The user sees the findings. Offer to post them: post_pr_review with this review_id puts ${inline} on their lines and the rest in one summary comment, after the user confirms.`
+          : "Tell the user nothing needs fixing; offer post_pr_review to leave the summary on the pull request.",
+      }
+    },
+  },
+  {
+    name: "post_pr_review",
+    description:
+      "Post a review from review_pull_request to its pull request after the user confirms: ForgeQE asks the user (Post / Don't post), then adds one comment per finding on its line and one summary comment with the verdict (on GitHub, a review with event COMMENT; it never approves or requests changes). Refuses when the pull request has new commits since the review. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed to post this review.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        review_id: { type: "string", description: "From review_pull_request" },
+        confirmed: { type: "boolean", description: "Only where ForgeQE cannot ask: the user agreed to post this review" },
+      },
+      required: ["review_id"],
+    },
+    async run(args, ctx) {
+      const review = loadReview(ctx.config, String(args.review_id))
+      if (review.posted) return { posted: false, reason: `Already posted on ${review.posted.at}.`, links: review.posted.links }
+      const n = review.findings.length
+      const inline = review.inline.filter(Boolean).length
+      const what = `${n ? `${n} finding${n === 1 ? "" : "s"} (${inline} on their lines) and ` : ""}a summary comment`
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Post the review to pull request ${review.pr.ref.number}?`,
+          detail: review.pr.url,
+          lines: [`${what} on "${review.pr.title}":`, ...review.findings.slice(0, 15).map((f) => `  • ${f.severity}: ${f.title}${f.file ? ` (${f.file}${f.line ? `:${f.line}` : ""})` : ""}`), ...(n > 15 ? [`  and ${n - 15} more`] : [])],
+          options: [
+            { id: "post", label: "Post review" },
+            { id: "no", label: "Don't post" },
+          ],
+        })
+        if (choice !== "post") return { posted: false, reason: "The user chose not to post the review." }
+      } else if (args.confirmed !== true) {
+        return {
+          posted: false,
+          needs_confirmation: true,
+          pull_request: review.pr.url,
+          would_post: what,
+          next_step: "Ask the user whether to post this review to the pull request; call post_pr_review again with confirmed: true only after they say yes.",
+        }
+      }
+      ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: `Posting the review to ${review.pr.url}…` } })
+      const links = await postReview(review, ctx.config)
+      ctx.emit?.({ type: "card", card: { status: "ok", title: `Review posted to pull request ${review.pr.ref.number}`, stats: what, body: links } })
+      return { posted: true, comments: inline + 1, links }
+    },
+  },
+  {
+    name: "select_pr_tests",
+    description:
+      "Pick the repository's automated tests a pull request can break, to run only those: the test files it changes, the tests that import a changed file (through page objects and helpers), the tests that name a changed class or page object, and the tests mapped to the test cases of the work items it is linked to. With agent (the default when a model is set up), Scribe checks the candidates by reading the tests, adds tests that drive the changed behaviour through the UI, and gives exact list and run commands; without, the impacted Playwright or pytest files are selected as they are. Shows the list and returns selection_id for run_tests. Give pr (a link or number) or base (a branch, to compare the current branch with).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pr: { type: "string", description: "The pull request's link, or its number in this repository" },
+        base: { type: "string", description: "Without pr: the branch to compare HEAD with (default: the remote's default branch)" },
+        platform: { type: "string", enum: ["azure_devops", "github"] },
+        repo: { type: "string", description: "Local clone, relative to the working directory (default: the working directory)" },
+        agent: { type: "boolean", description: "false: only the import and name analysis, no model (fast, for a quick look or CI)" },
+      },
+    },
+    async run(args, ctx) {
+      const agent = args.agent !== false && !noAgentModel(ctx.config.llm, ctx.config.code.model, "Scribe")
+      const out = await selectPrTests({
+        config: ctx.config,
+        repo: args.repo ? path.resolve(ctx.cwd, String(args.repo)) : ctx.cwd,
+        pr: args.pr ? String(args.pr) : undefined,
+        base: args.base ? String(args.base) : undefined,
+        platform: args.platform as Platform | undefined,
+        agent,
+        signal: ctx.signal,
+        onEvent: (event) => ctx.emit?.({ type: "agent", event }),
+        open: ctx.openSession as never,
+        runTest: ctx.runTest,
+      })
+      if (out.selection) ctx.emit?.({ type: "card", card: selectionCard(out.selection, ctx.cwd) })
+      return {
+        ...(out.pr ? { pull_request: out.pr.url, title: out.pr.title } : {}),
+        changed_files: out.impact.changed.length,
+        impacted: out.impact.tests,
+        no_test_reaches: out.impact.untested.length ? out.impact.untested : undefined,
+        selection_id: out.selection?.id,
+        count: out.selection?.tests.length || 0,
+        run_command: out.selection?.runCommand,
+        notes: out.notes.length ? out.notes : undefined,
+        next_step: out.selection?.tests.length
+          ? `Call run_tests with this selection_id (it asks the user first)${out.pr ? ", then offer post_pr_test_results to put the results on the pull request" : ""}. Mention the changed files no test reaches: they are a coverage gap.`
+          : "Say no test was found for these changes, and name the changed files no test reaches as a coverage gap.",
+      }
+    },
+  },
+  {
+    name: "post_pr_test_results",
+    description:
+      "Post the results of run_tests for a pull request's selection on the pull request, as one comment (passed and failed counts, each failed test with its message, the command), after the user confirms. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selection_id: { type: "string", description: "From select_pr_tests, after run_tests ran it" },
+        pr: { type: "string", description: "The pull request's link or number" },
+        platform: { type: "string", enum: ["azure_devops", "github"] },
+        confirmed: { type: "boolean" },
+      },
+      required: ["selection_id", "pr"],
+    },
+    async run(args, ctx) {
+      const sel = loadSelection(ctx.config, String(args.selection_id))
+      const file = path.join(sel.dir, "results.json")
+      if (!existsSync(file)) return { posted: false, reason: "The selection has not run yet: call run_tests first." }
+      const run = JSON.parse(readFileSync(file, "utf8")) as TestsRun
+      const { root, ref } = await resolvePr(sel.repo, String(args.pr), args.platform as Platform | undefined)
+      const markdown = resultsMarkdown(run, `pull request ${ref.number}`)
+      if (ctx.ask) {
+        const choice = await ctx.ask({
+          title: `Post the test results to pull request ${ref.number}?`,
+          lines: markdown.split("\n").slice(0, 20),
+          options: [
+            { id: "post", label: "Post results" },
+            { id: "no", label: "Don't post" },
+          ],
+        })
+        if (choice !== "post") return { posted: false, reason: "The user chose not to post the results." }
+      } else if (args.confirmed !== true) {
+        return { posted: false, needs_confirmation: true, comment: markdown, next_step: "Show the user the comment; call again with confirmed: true only after they agree." }
+      }
+      const url = await postPrComment(ref, ctx.config, root, markdown)
+      ctx.emit?.({ type: "card", card: { status: run.status === "passed" ? "ok" : "fail", title: `Test results posted to pull request ${ref.number}`, body: [url] } })
+      return { posted: true, url }
+    },
+  },
+  {
+    name: "analyze_pr_impact",
+    description:
+      "Which parts of the product a pull request touches, for the product's code repository, which may be another repository than the tests. Reads the pull request from a local clone of the product repository (product_repo, or the working directory when it is one), else through the GitHub or Azure DevOps API. Ties its changes to the product by: the work items it is linked to (with feature, epic, and Area Path); the test ids, ids, labels, texts, and routes its changed code carries, matched against page memory (every element ForgeQE met on each page); with a clone, the pages that import a changed shared component. Then, in the automation repository (the working directory): the tests that visit those pages, the test cases they automate, and the test cases of the impacted requirements nobody automated (manual tests to run). Returns the evidence and shows a card; write the impact report from it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pr: { type: "string", description: "The pull request's link (or its number when the working directory or product_repo is a clone of its repository)" },
+        product_repo: { type: "string", description: "A local clone of the product repository, when it is not the working directory (optional: without one, the API is used)" },
+      },
+      required: ["pr"],
+    },
+    async run(args, ctx) {
+      ctx.emit?.({ type: "agent", event: { type: "code", kind: "info", text: "Reading the pull request and tying its changes to the product…" } })
+      const impact = await analyzeAreas(ctx.config, String(args.pr), { productRepo: args.product_repo ? String(args.product_repo) : undefined, cwd: ctx.cwd })
+      ctx.emit?.({ type: "card", card: impactCard(impact) })
+      return {
+        pull_request: impact.pr.url,
+        title: impact.pr.title,
+        read_from: impact.via,
+        changed_files: impact.files,
+        requirements: impact.requirements.map((r) => ({ id: r.id, type: r.type, title: r.title, area: r.area, parent: r.parent, acceptance: r.acceptance || undefined })),
+        pages: impact.pages,
+        routes: impact.routes.length ? impact.routes : undefined,
+        tests: impact.tests,
+        manual_test_cases: impact.manual,
+        ui_files_not_tied_to_a_page: impact.unmapped.length ? impact.unmapped : undefined,
+        notes: impact.notes.length ? impact.notes : undefined,
+        next_step:
+          "Write the impact report: the product areas this changes (features and epics, Area Paths, pages), each with its evidence and a risk (high for shared components, sign-in, payments, data and migrations, or many pages; low for one page's text), side effects the evidence does not show but the diff suggests, the automated tests to run (select_pr_tests can pick and run them), the manual test cases to run, and the gaps: areas with no test. Offer to post it on the pull request with comment_on_pr.",
+      }
+    },
+  },
+  {
+    name: "comment_on_pr",
+    description: "Post one markdown comment on a pull request (an impact report, a summary) after the user confirms. Where ForgeQE cannot ask (an MCP client), pass confirmed: true only after the user agreed to this text.",
+    inputSchema: {
+      type: "object",
+      properties: { pr: { type: "string", description: "The pull request's link or number" }, markdown: { type: "string" }, confirmed: { type: "boolean" } },
+      required: ["pr", "markdown"],
+    },
+    async run(args, ctx) {
+      const ref = parsePrRef(String(args.pr), await gitRemotes(ctx.cwd).catch(() => []))
+      const markdown = String(args.markdown)
+      if (ctx.ask) {
+        const choice = await ctx.ask({ title: `Post this comment on pull request ${ref.number}?`, lines: markdown.split("\n").slice(0, 25), options: [{ id: "post", label: "Post comment" }, { id: "no", label: "Don't post" }] })
+        if (choice !== "post") return { posted: false, reason: "The user chose not to post it." }
+      } else if (args.confirmed !== true) {
+        return { posted: false, needs_confirmation: true, next_step: "Show the user the comment; call again with confirmed: true only after they agree." }
+      }
+      const url = await postPrComment(ref, ctx.config, ctx.cwd, markdown)
+      return { posted: true, url }
+    },
+  },
+]
+
+/** The evidence as a card: areas, pages, tests, manual cases, and what is not tied to anything. */
+function impactCard(i: AreaImpact): Card {
+  const body: string[] = []
+  const reqs = i.requirements.filter((r) => !/test case/i.test(r.type))
+  if (reqs.length) body.push("Requirements", ...reqs.slice(0, 10).map((r) => `  ${r.type} ${r.id.replace(/^ADO-/, "")} "${r.title}"${r.area ? `  (${r.area})` : ""}`), "")
+  if (i.pages.length) body.push("Pages", ...i.pages.slice(0, 12).map((p) => `  ${p.page}${p.title ? ` "${p.title}"` : ""}: ${p.evidence.slice(0, 3).join(", ")}${p.evidence.length > 3 ? `, and ${p.evidence.length - 3} more` : ""}`), "")
+  if (i.tests.length) body.push("Automated tests that reach them", ...i.tests.slice(0, 12).map((t) => `  ${t.file}${t.caseId ? ` (${t.caseId})` : ""}: ${t.reasons[0]}`), "")
+  if (i.manual.length) body.push("Manual test cases for these requirements", ...i.manual.slice(0, 12).map((m) => `  ${m.id} ${m.title || ""}`.trimEnd()), "")
+  if (i.unmapped.length) body.push(`UI files not tied to a page: ${i.unmapped.slice(0, 8).join(", ")}${i.unmapped.length > 8 ? ", …" : ""}`)
+  for (const n of i.notes) body.push(n)
+  return {
+    status: "info",
+    title: `Impact of pull request ${i.pr.ref.number}: ${i.pr.title}`,
+    stats: [`${i.files.length} files`, `${i.pages.length} pages`, `${i.tests.length} tests`, `${i.manual.length} manual cases`].join(" · "),
+    body,
+  }
+}