@capagents/forgeqe 1.1.3 → 1.1.5

package/src/config.ts

@@ -38,6 +38,13 @@ export type BrowserRemoteConfig = {
   extra?: Record<string, unknown>
 }
 
+/** A named remote browser (devices: in a provider file): the provider's shared remote settings with its own on top. */
+export type BrowserDevice = {
+  name: string
+  provider: RemoteBrowserProvider
+  remote: BrowserRemoteConfig
+}
+
 export type BrowserConfig = {
   provider: BrowserProvider
   headless: boolean
@@ -51,6 +58,8 @@ export type BrowserConfig = {
   remote?: BrowserRemoteConfig
   remotes: BrowserRemoteConfigs
   providerFiles: BrowserProviderFiles
+  /** Named devices from the provider files, by name; names are unique across providers. */
+  devices: Record<string, BrowserDevice>
   /** ForgeQE overlay in a visible browser: edge glow, a bar with the current step, the person's input locked. */
   overlay: boolean
   /** A second model call checks the finished run against the goal, and its verdict can fail a run the agent completed. */
@@ -63,20 +72,6 @@ export type MemoryConfig = {
   replay: ReplayMode
 }
 
-export type CacheConfig = {
-  enabled: boolean
-  /** Redis connection string, e.g. redis://127.0.0.1:6379. */
-  redisUrl: string
-  /** Prefix for every Redis key this ForgeQE workspace writes. */
-  keyPrefix: string
-  /** Default TTL for cached JSON payloads, in seconds. */
-  defaultTtlSeconds: number
-  /** TTL for BI external dataset exports, in seconds. */
-  biTtlSeconds: number
-  /** Socket connect timeout for Redis, in milliseconds. */
-  connectTimeoutMs: number
-}
-
 function runtimeBin(value: unknown, base: string): string | undefined {
   if (!value) return undefined
   const s = String(value)
@@ -92,6 +87,8 @@ export type CodeConfig = {
   stallAfter?: number
   /** Give Scribe a Playwright-driven browser, set up like the run's, switched on once a step fails. */
   liveBrowser?: boolean
+  /** Give Scribe the code graph of the repository (code_find, code_outline, code_element, …) and link the handoff's elements to the page objects that locate them (code.graph, default true). */
+  graph?: boolean
   /** Before Scribe starts, replay the run's steps as a Playwright script and hand over what worked and where it failed. */
   replay?: boolean
   /** Model for ForgeQE's agent and Scribe as provider/model, instead of the run's llms.json profile. */
@@ -136,11 +133,16 @@ export type SourcesConfig = {
   qtest?: { url: string; tokenEnv: string; projectId: number; statuses: { passed: string; failed: string; error: string } }
   /** File a bug for each failed case, or comment on the open one ForgeQE filed before. */
   bugs?: BugsConfig
+  /**
+   * GitHub: issues as test cases and bugs, and GitHub's MCP server for ForgeQE's agent. `repo` (owner/name) is the default
+   * for issue references; the token is `tokenEnv`, else the GitHub CLI's sign-in. `toolsets`: the MCP server's tool groups.
+   */
+  github?: { repo?: string; apiUrl: string; tokenEnv: string; mcp: boolean; toolsets: string[] }
 }
 
 export type BugsConfig = {
-  system: "jira" | "azure_devops"
-  /** Jira project key. Azure DevOps uses this, or sources.azure_devops.project. */
+  system: "jira" | "azure_devops" | "github"
+  /** Jira project key; GitHub owner/repo (default sources.github.repo). Azure DevOps uses this, or sources.azure_devops.project. */
   project?: string
   /** Jira issue type or Azure DevOps work item type. */
   type: string
@@ -149,6 +151,11 @@ export type BugsConfig = {
   areaPath?: string
   /** Also file bugs for cases that could not run (status error). */
   onError: boolean
+  /**
+   * "defect" (the default): one bug per defect, so cases failing the same way (the same failed request, the same
+   * uncaught error) share a bug, each added to it. "case": one bug per failing case.
+   */
+  groupBy?: "defect" | "case"
 }
 
 /** A site the browser agent can sign in to. Values come from the environment; the agent only sees placeholders. */
@@ -321,6 +328,9 @@ function notifyConfig(raw: unknown): NotifyConfig | undefined {
     if (unknown.length) throw new Error(`${where}.on: ${unknown.join(", ")} is not an event. Events: ${NOTIFY_EVENTS.join(", ")}.`)
     return { name, ...alerts, on: on as NotifyEvent[] }
   })
+  // No channels set up, but a Teams webhook in the environment: a "teams" channel for messages the user asks for. It
+  // takes no events (on: []), so runs nobody watches never start posting to it unasked.
+  if (!channels.length && process.env.TEAMS_WEBHOOK_URL?.trim()) channels.push({ name: "teams", teams: { webhookEnv: "TEAMS_WEBHOOK_URL" }, on: [] })
   if (!channels.length) return undefined
   return { channels, ...(n.report_url ? { reportUrl: trimUrl(n.report_url) } : {}) }
 }
@@ -348,8 +358,6 @@ export type AppConfig = {
   configPath?: string
   /** `mcp:` in forgeqe.yaml: more MCP servers for ForgeQE's agent, by name. */
   mcp?: Record<string, ExtraMcpServer>
-  /** Optional Redis-backed cache for deterministic external data fetches. */
-  cache?: CacheConfig
   activeProfile: string
   profiles: Record<string, LlmProfile>
   llm: LlmProfile
@@ -361,6 +369,8 @@ export type AppConfig = {
   prompts: { stepInstruction: string; guiderails: string; dirs?: { dir: string; source: string }[] }
   /** Product knowledge (.forgeqe/knowledge): see src/knowledge.ts. */
   knowledge?: { dir: string; browserMaxChars: number }
+  /** Defect intelligence (defects: in forgeqe.yaml): see src/cases/defects.ts, repro.ts, rca.ts. */
+  defects: DefectsConfig
   export: { outDir: string; format: string }
   memory: MemoryConfig
   code: CodeConfig
@@ -410,22 +420,6 @@ function domainConfig(raw: unknown): DomainConfig | undefined {
   return { industry, regulations, ...(d.notes ? { notes: String(d.notes).trim() } : {}) }
 }
 
-function cacheConfig(raw: unknown): CacheConfig | undefined {
-  const c = asRecord(raw)
-  const asked = raw !== undefined || Boolean(process.env.FORGEQE_REDIS_URL)
-  if (!asked || c.enabled === false) return undefined
-  const redisUrl = String(c.redis_url || c.url || process.env.FORGEQE_REDIS_URL || "").trim()
-  if (!redisUrl) throw new Error('cache.redis_url is required when cache is enabled. Example: cache: { redis_url: "redis://127.0.0.1:6379" }')
-  return {
-    enabled: true,
-    redisUrl,
-    keyPrefix: String(c.key_prefix || "forgeqe").trim() || "forgeqe",
-    defaultTtlSeconds: positiveInt(c.default_ttl_seconds, 3600, "cache.default_ttl_seconds"),
-    biTtlSeconds: positiveInt(c.bi_ttl_seconds, 900, "cache.bi_ttl_seconds"),
-    connectTimeoutMs: positiveInt(c.connect_timeout_ms, 3000, "cache.connect_timeout_ms"),
-  }
-}
-
 export function replayMode(raw: unknown): ReplayMode {
   const mode = String(raw || "verify").toLowerCase()
   if (mode === "trust" || mode === "off") return mode
@@ -471,12 +465,12 @@ const REMOTE_BROWSER_DEFAULTS: Record<RemoteBrowserProvider, Pick<BrowserRemoteC
   browserstack: {
     usernameEnv: "BROWSERSTACK_USERNAME",
     accessKeyEnv: "BROWSERSTACK_ACCESS_KEY",
-    endpoint: "wss://cdp.browserstack.com/playwright",
+    endpoint: "wss://cdp.browserstack.com/puppeteer",
   },
   testmu: {
     usernameEnv: "LT_USERNAME",
     accessKeyEnv: "LT_ACCESS_KEY",
-    endpoint: "wss://cdp.lambdatest.com/playwright",
+    endpoint: "wss://cdp.lambdatest.com/puppeteer",
   },
 }
 
@@ -545,9 +539,20 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   const defaults = REMOTE_BROWSER_DEFAULTS[provider]
   const browser = String(remote.browser || "").trim()
   if (!browser) throw new Error(`${where}.remote.browser is required when browser.provider is ${provider}.`)
+  // The engine drives the browser over the Chrome DevTools Protocol, so the grid must hand back a Chromium browser.
+  if (!/chrome|edge|chromium/i.test(browser) || /^(playwright|pw)-/i.test(browser)) {
+    throw new Error(`${where}.remote.browser is "${browser}": ForgeQE drives remote browsers over the Chrome DevTools Protocol, so use chrome or edge.`)
+  }
+  // Checked live: TestMu AI's CDP endpoint opens Chrome sessions only; an Edge session never opens and times out.
+  if (provider === "testmu" && !/chrome/i.test(browser)) {
+    throw new Error(`${where}.remote.browser is "${browser}": TestMu AI's CDP endpoint only serves Chrome, so use Chrome there (Edge works on BrowserStack).`)
+  }
   const browserVersion = String(remote.browser_version || remote.browserVersion || "latest").trim() || "latest"
-  const os = String(remote.os || "").trim() || undefined
-  const osVersion = String(remote.os_version || remote.osVersion || "").trim() || undefined
+  const rawOs = String(remote.os || "").trim() || undefined
+  const rawOsVersion = String(remote.os_version || remote.osVersion || "").trim() || undefined
+  // BrowserStack documents "Windows" and "OS X" with versions like 11 or Sequoia: what people write maps onto those.
+  const os = provider === "browserstack" && rawOs ? browserstackOs(rawOs) : rawOs
+  const osVersion = provider === "browserstack" && rawOsVersion && os === "OS X" ? titleCase(rawOsVersion) : rawOsVersion
   const platform = String(remote.platform || "").trim() || undefined
   if (provider === "browserstack" && (!os || !osVersion)) {
     throw new Error(`${where}.remote.os and ${where}.remote.os_version are required when browser.provider is browserstack.`)
@@ -555,12 +560,16 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   if (provider === "testmu" && !platform && !os) {
     throw new Error(`${where}.remote.platform is required when browser.provider is testmu, or set ${where}.remote.os (and optionally os_version).`)
   }
+  const endpoint = String(remote.endpoint || defaults.endpoint).trim().replace(/\/+$/, "")
+  if (/\/playwright$/i.test(endpoint)) {
+    throw new Error(`${where}.remote.endpoint ${endpoint} speaks Playwright's own protocol; ForgeQE needs the CDP endpoint (${defaults.endpoint}).`)
+  }
   const extra = objectMap(remote.extra ?? remote.capabilities, `${where}.remote.extra`)
   return {
     provider,
     usernameEnv: String(remote.username_env || remote.usernameEnv || defaults.usernameEnv),
     accessKeyEnv: String(remote.access_key_env || remote.accessKeyEnv || defaults.accessKeyEnv),
-    endpoint: String(remote.endpoint || defaults.endpoint).trim().replace(/\/+$/, ""),
+    endpoint,
     browser,
     browserVersion,
     ...(os ? { os } : {}),
@@ -574,28 +583,68 @@ function browserRemoteConfig(raw: Record<string, unknown>, provider: BrowserProv
   }
 }
 
-function browserRemoteConfigs(browser: Record<string, unknown>, provider: BrowserProvider, base: string): { remotes: BrowserRemoteConfigs; providerFiles: BrowserProviderFiles } {
+function browserstackOs(os: string): string {
+  if (/^(os ?x|macos|mac( ?os)?)$/i.test(os)) return "OS X"
+  if (/^win(dows)?$/i.test(os)) return "Windows"
+  return os
+}
+
+const titleCase = (s: string) => s.toLowerCase().replace(/\b[a-z]/g, (c) => c.toUpperCase())
+
+/** A device name: what the user and the agent call it ("win11-chrome"), also used in folder names. */
+export const DEVICE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+
+function browserRemoteConfigs(
+  browser: Record<string, unknown>,
+  provider: BrowserProvider,
+  base: string,
+): { remotes: BrowserRemoteConfigs; providerFiles: BrowserProviderFiles; devices: Record<string, BrowserDevice> } {
   const providerFiles = browserProviderFiles(browser, base)
   const remotes: BrowserRemoteConfigs = {}
+  const devices: Record<string, BrowserDevice> = {}
   for (const remoteProvider of REMOTE_BROWSER_PROVIDERS) {
     const fromFile = providerFiles[remoteProvider] ? browserProviderFileSection(providerFiles[remoteProvider]!, remoteProvider) : undefined
     const inline = provider === remoteProvider ? browser : undefined
     if (!fromFile && !inline) continue
     const where = fromFile ? `browser.providers.${remoteProvider}` : "browser"
-    remotes[remoteProvider] = browserRemoteConfig(
-      {
-        ...(fromFile || {}),
-        ...(inline || {}),
-        remote: { ...asRecord(fromFile?.remote), ...asRecord(inline?.remote) },
-      },
-      remoteProvider,
-      where,
-    )
+    const shared = { ...asRecord(fromFile?.remote), ...asRecord(inline?.remote) }
+    const named = objectMap(fromFile?.devices, `${where}.devices`) || {}
+    for (const [name, raw] of Object.entries(named)) {
+      if (!DEVICE_NAME.test(name)) throw new Error(`${where}.devices.${name}: a device name uses letters, digits, ".", "_" and "-".`)
+      const other = devices[name]
+      if (other) throw new Error(`Device ${name} is in both ${other.provider} and ${remoteProvider}; device names must be unique.`)
+      const remote = browserRemoteConfig({ remote: { ...shared, ...asRecord(raw) } }, remoteProvider, `${where}.devices.${name}`)!
+      devices[name] = { name, provider: remoteProvider, remote }
+    }
+    // A provider file that only lists devices: its first device is the provider's default browser.
+    const first = Object.values(devices).find((d) => d.provider === remoteProvider)
+    remotes[remoteProvider] =
+      !String(shared.browser || "").trim() && first
+        ? first.remote
+        : browserRemoteConfig({ ...(fromFile || {}), ...(inline || {}), remote: shared }, remoteProvider, where)
   }
-  return { remotes, providerFiles }
+  return { remotes, providerFiles, devices }
 }
 
-export function browserConfigFor(config: Pick<AppConfig, "browser">, provider = config.browser.provider): Pick<BrowserConfig, "provider" | "remote"> {
+/**
+ * The browser a run uses: a named device (which also picks its provider), else the provider's default remote,
+ * else the local browser. A device on another provider than the one asked for is an error, not a silent switch.
+ */
+export function browserConfigFor(
+  config: Pick<AppConfig, "browser">,
+  provider?: BrowserProvider,
+  device?: string,
+): Pick<BrowserConfig, "provider" | "remote"> & { device?: string } {
+  if (device) {
+    const d = config.browser.devices?.[device]
+    if (!d) {
+      const known = Object.keys(config.browser.devices || {})
+      throw new Error(`No browser device named ${device}. ${known.length ? `Configured: ${known.join(", ")}.` : "None is configured yet."} Add one with browser_devices, or under devices: in the provider's YAML file.`)
+    }
+    if (provider && provider !== d.provider) throw new Error(`Device ${device} is on ${d.provider}, not ${provider}.`)
+    // The session name shows the device in the provider's dashboard.
+    return { provider: d.provider, remote: { ...d.remote, name: [d.remote.name, device].filter(Boolean).join(" · ") }, device }
+  }
   const chosen = provider || config.browser.provider || "local"
   if (chosen === "local") return { provider: chosen }
   const remote = config.browser.remotes?.[chosen] || ((config.browser.provider === chosen || !config.browser.provider) ? config.browser.remote : undefined)
@@ -775,11 +824,10 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
 
   const sessionsDir = configPath ? path.join(projectDir(base), "sessions") : path.join(forgeqeHome(), "sessions")
   const provider = browserProvider(browser.provider)
-  const { remotes, providerFiles } = browserRemoteConfigs(browser, provider, base)
+  const { remotes, providerFiles, devices } = browserRemoteConfigs(browser, provider, base)
   const config: AppConfig = {
     configPath,
     mcp: extraMcpServers(yaml.mcp, base),
-    cache: cacheConfig(yaml.cache),
     activeProfile,
     profiles,
     llm: profiles[activeProfile] || { ...NO_PROFILE },
@@ -796,6 +844,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       remote: provider === "local" ? undefined : remotes[provider],
       remotes,
       providerFiles,
+      devices,
       overlay: browser.overlay !== false,
       judge: browser.judge === true,
     },
@@ -805,6 +854,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       dirs: promptDirsFor(prompts, base, configPath),
     },
     knowledge: knowledgeConfig(asRecord(yaml.knowledge), base, configPath),
+    defects: defectsConfig(asRecord(yaml.defects), base),
     export: {
       outDir,
       format: String(exp.format || "playwright"),
@@ -824,6 +874,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       testTimeoutSeconds: Number(code.test_timeout_seconds || 600),
       stallAfter: Math.max(2, Number(code.stall_after || 5)),
       liveBrowser: code.live_browser !== false,
+      graph: code.graph !== false,
       replay: code.replay !== false,
       model: code.model ? String(code.model) : undefined,
       ...(code.review_profile ? { reviewProfile: String(code.review_profile) } : {}),
@@ -1026,6 +1077,26 @@ function sourcesConfig(raw: Record<string, unknown>): SourcesConfig {
     ...optional("zephyr", zephyrConfig(raw.zephyr)),
     ...optional("qtest", qtestConfig(asRecord(raw.qtest))),
     ...optional("bugs", bugsConfig(raw.bugs)),
+    ...optional("github", githubConfig(raw.github)),
+  }
+}
+
+/** The GitHub MCP server's tool groups ForgeQE loads unless sources.github.toolsets says otherwise. */
+export const GITHUB_TOOLSETS = ["repos", "issues", "pull_requests", "actions"]
+
+function githubConfig(raw: unknown): SourcesConfig["github"] {
+  if (raw === undefined || raw === null) return undefined
+  if (raw === false) return { apiUrl: "https://api.github.com", tokenEnv: "GITHUB_TOKEN", mcp: false, toolsets: [] }
+  const g = asRecord(raw)
+  const repo = String(g.repo || "").trim()
+  if (repo && !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new Error(`sources.github.repo is owner/name; got "${repo}".`)
+  const toolsets = Array.isArray(g.toolsets) ? g.toolsets.map(String).filter(Boolean) : GITHUB_TOOLSETS
+  return {
+    ...(repo ? { repo } : {}),
+    apiUrl: String(g.api_url || "https://api.github.com").replace(/\/+$/, ""),
+    tokenEnv: String(g.token_env || "GITHUB_TOKEN"),
+    mcp: g.mcp !== false,
+    toolsets,
   }
 }
 
@@ -1049,6 +1120,27 @@ function promptDirsFor(p: Record<string, unknown>, base: string, configPath: str
   return dirs.filter((d, i) => dirs.findIndex((x) => path.resolve(x.dir) === path.resolve(d.dir)) === i)
 }
 
+export type DefectsConfig = {
+  /** The application's own repository: suspect commits, and the code the root-cause analysis reads. */
+  productRepo?: string
+  /** Run the first case of each new defect once more, to see whether it repeats. */
+  reproduce: boolean
+  /** A model writes a root-cause hypothesis for new defects and regressions. */
+  analyze: boolean
+  /** Most defects analysed by the model in one suite. */
+  maxAnalyses: number
+}
+
+export function defectsConfig(d: Record<string, unknown>, base: string): DefectsConfig {
+  const max = Number(d.max_analyses)
+  return {
+    ...(d.product_repo ? { productRepo: path.resolve(base, String(d.product_repo)) } : {}),
+    reproduce: d.reproduce !== false,
+    analyze: d.analyze !== false,
+    maxAnalyses: Number.isInteger(max) && max >= 0 && d.max_analyses !== undefined ? max : 3,
+  }
+}
+
 function knowledgeConfig(k: Record<string, unknown>, base: string, configPath: string | undefined): NonNullable<AppConfig["knowledge"]> {
   const dir = k.dir ? path.resolve(base, String(k.dir)) : configPath ? path.join(projectDir(base), "knowledge") : path.join(forgeqeHome(), "knowledge")
   const max = Number(k.browser_max_chars)
@@ -1076,9 +1168,12 @@ function apiConfig(a: Record<string, unknown>): ApiConfig {
   }
 }
 
+/** The tables forgeqe bi always exports; a dataset id may not reuse one. */
+export const BI_BUILTIN_TABLES = ["suites", "case_results", "step_results", "writebacks", "readiness", "readiness_stories", "readiness_cases", "external_datasets"]
+
 function biConfig(b: Record<string, unknown>, base: string, outDir: string, configPath: string | undefined): BiConfig {
   const evidenceDir = path.resolve(base, String(b.evidence_dir || path.join(".", "evidence")))
-  const defaultDataDir = path.join(evidenceDir, "sources", "forgeqe", "data")
+  const defaultDataDir = path.join(evidenceDir, "sources", "forgeqe")
   const title = String(b.title || "ForgeQE BI").trim() || "ForgeQE BI"
   const datasets = Object.entries(asRecord(b.datasets)).map(([id, value]) => biDataset(id, asRecord(value)))
   return {
@@ -1091,7 +1186,9 @@ function biConfig(b: Record<string, unknown>, base: string, outDir: string, conf
 }
 
 function biDataset(id: string, raw: Record<string, unknown>): BiDatasetConfig {
-  if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error(`bi.datasets.${id}: ids may only use letters, digits, - and _.`)
+  // The id is the dataset's table name in Evidence's SQL (forgeqe.<id>), so it must be a plain identifier.
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(id)) throw new Error(`bi.datasets.${id}: ids may only use letters, digits and _, and must not start with a digit.`)
+  if (BI_BUILTIN_TABLES.includes(id)) throw new Error(`bi.datasets.${id}: ${id} is one of ForgeQE's own BI tables; choose another id.`)
   const title = String(raw.title || id.replace(/[-_]+/g, " ").trim()).trim()
   const kind = String(raw.kind || "").trim().toLowerCase()
   if (kind === "ado_wiql") {
@@ -1183,7 +1280,7 @@ function bugsConfig(raw: unknown): BugsConfig | undefined {
   if (raw === undefined || raw === null || raw === false) return undefined
   const b = asRecord(raw)
   const system = String(b.system || "").toLowerCase().replace(/[\s-]/g, "_")
-  if (system !== "jira" && system !== "azure_devops") throw new Error(`sources.bugs.system must be jira or azure_devops; got "${String(b.system ?? "")}".`)
+  if (system !== "jira" && system !== "azure_devops" && system !== "github") throw new Error(`sources.bugs.system must be jira, azure_devops, or github; got "${String(b.system ?? "")}".`)
   if (system === "jira" && !b.project) throw new Error("sources.bugs.project is required for Jira: the project key bugs are filed in.")
   return {
     system,
@@ -1192,9 +1289,16 @@ function bugsConfig(raw: unknown): BugsConfig | undefined {
     labels: Array.isArray(b.labels) ? b.labels.map(String).filter(Boolean) : ["forgeqe"],
     ...(b.area_path ? { areaPath: String(b.area_path) } : {}),
     onError: b.on_error === true,
+    ...(groupBy(b.group_by) === "case" ? { groupBy: "case" as const } : {}),
   }
 }
 
+function groupBy(raw: unknown): "defect" | "case" {
+  if (raw === undefined || raw === null || raw === "defect") return "defect"
+  if (raw === "case") return "case"
+  throw new Error(`sources.bugs.group_by must be defect or case; got "${String(raw)}".`)
+}
+
 function jiraMcp(raw: unknown): JiraMcp | false {
   if (raw === false || raw === "false" || raw === "off") return false
   if (raw === undefined || raw === null || raw === true || raw === "mcp-atlassian") return "mcp-atlassian"

package/src/mcp/attachtools.ts

@@ -0,0 +1,223 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs"
+import path from "node:path"
+
+import { adoSettings } from "../cases/ado.ts"
+import { http, textToAdf } from "../cases/http.ts"
+import { jiraApi } from "../cases/jira.ts"
+import type { AppConfig } from "../config.ts"
+import type { McpTool } from "./tools.ts"
+
+/**
+ * Evidence onto an existing work item or issue: files from a run (screenshots, the report, JUnit, the trace) uploaded
+ * as attachments, posted in a comment (images inline, text as text), or both. Only files inside the working folder or
+ * the reports folders can go, so a request can never send anything else from the machine.
+ */
+
+const MAX_FILE = 25 * 1024 * 1024
+/** Text read into a comment; longer text is attached instead. */
+const MAX_COMMENT_TEXT = 20_000
+const IMAGE = /\.(png|jpe?g|gif|webp)$/i
+const TEXT = /\.(md|txt|log|json|xml|csv|ya?ml)$/i
+const MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".html": "text/html",
+  ".json": "application/json",
+  ".xml": "application/xml",
+}
+
+export type Pick = "last_screenshot" | "failure_screenshot" | "report" | "junit" | "trace"
+const PICKS: Pick[] = ["last_screenshot", "failure_screenshot", "report", "junit", "trace"]
+
+type File = { path: string; name: string; data: Buffer; type: string }
+
+/** Files a run folder holds, by what they are. A suite folder's last screenshot is its last case's. */
+export function pickFiles(runDir: string, picks: Pick[]): string[] {
+  const out: string[] = []
+  const lastShot = (dir: string): string | undefined => {
+    const steps = path.join(dir, "steps")
+    const shots = existsSync(steps) ? readdirSync(steps).filter((f) => IMAGE.test(f)).sort() : []
+    if (shots.length) return path.join(steps, shots[shots.length - 1])
+    if (existsSync(path.join(dir, "failure.png"))) return path.join(dir, "failure.png")
+    // A suite folder: its case folders, last one first.
+    const cases = readdirSync(dir).filter((d) => statSync(path.join(dir, d)).isDirectory() && d !== "steps").sort().reverse()
+    for (const c of cases) {
+      const shot = lastShot(path.join(dir, c))
+      if (shot) return shot
+    }
+    return undefined
+  }
+  for (const pick of picks) {
+    const file =
+      pick === "last_screenshot"
+        ? lastShot(runDir)
+        : pick === "failure_screenshot"
+          ? [path.join(runDir, "failure.png")].find(existsSync)
+          : pick === "report"
+            ? path.join(runDir, "report.html")
+            : pick === "junit"
+              ? path.join(runDir, "junit.xml")
+              : path.join(runDir, "trace.md")
+    if (!file || !existsSync(file)) throw new Error(`${runDir} has no ${pick.replace("_", " ")}.`)
+    out.push(file)
+  }
+  return out
+}
+
+/** A file to send: inside the working folder or a reports folder, and not too big. */
+function readAllowed(file: string, config: AppConfig, cwd: string): File {
+  if (!existsSync(file)) throw new Error(`No such file: ${file}`)
+  const real = realpathSync(file)
+  const roots = [cwd, config.export?.outDir, config.suite?.outDir, config.monitor?.outDir].filter(Boolean).map((r) => (existsSync(r!) ? realpathSync(r!) : path.resolve(r!)))
+  if (!roots.some((r) => real === r || real.startsWith(`${r}${path.sep}`))) {
+    throw new Error(`${file} is outside the working folder and the reports folders, so it is not sent.`)
+  }
+  const size = statSync(real).size
+  if (size > MAX_FILE) throw new Error(`${file} is ${(size / 1024 / 1024).toFixed(1)} MB; the limit is ${MAX_FILE / 1024 / 1024} MB.`)
+  return { path: real, name: path.basename(real), data: readFileSync(real), type: MIME[path.extname(real).toLowerCase()] || "application/octet-stream" }
+}
+
+const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+
+type Outcome = { item: string; url?: string; attached: string[]; commented: boolean; inline: string[] }
+
+async function toAdo(config: AppConfig, id: string, files: File[], mode: string, comment: string): Promise<Outcome> {
+  const { auth, org } = adoSettings(config.sources)
+  if (!/^\d+$/.test(id)) throw new Error(`An Azure DevOps work item id is a number; got "${id}".`)
+  // Comments and attachments live in the work item's own project.
+  const { data: wi } = await http<{ fields?: Record<string, unknown>; _links?: { html?: { href?: string } } }>(`${org}/_apis/wit/workitems/${id}?fields=System.TeamProject&api-version=7.1`, { auth })
+  const project = encodeURIComponent(String(wi.fields?.["System.TeamProject"] || ""))
+  const scoped = `${org}/${project}`
+  const upload = async (f: File) => {
+    const res = await fetch(`${scoped}/_apis/wit/attachments?fileName=${encodeURIComponent(f.name)}&api-version=7.1`, {
+      method: "POST",
+      headers: { Authorization: auth, "Content-Type": "application/octet-stream", Accept: "application/json" },
+      body: new Uint8Array(f.data),
+    })
+    if (!res.ok) throw new Error(`Uploading ${f.name} to work item ${id} failed: ${res.status} ${res.statusText}.`)
+    return ((await res.json()) as { url: string }).url
+  }
+  const out: Outcome = { item: `#${id}`, url: wi._links?.html?.href, attached: [], commented: false, inline: [] }
+  const urls = new Map<string, string>()
+  if (mode === "attach" || mode === "both") {
+    const ops = []
+    for (const f of files) {
+      const url = await upload(f)
+      urls.set(f.path, url)
+      ops.push({ op: "add", path: "/relations/-", value: { rel: "AttachedFile", url, attributes: { comment: comment ? comment.slice(0, 250) : "Added by ForgeQE" } } })
+      out.attached.push(f.name)
+    }
+    await http(`${org}/_apis/wit/workitems/${id}?api-version=7.1`, { method: "PATCH", auth, body: ops, contentType: "application/json-patch+json" })
+  }
+  if (mode === "comment" || mode === "both") {
+    const parts = comment ? [`<p>${esc(comment).replace(/\n/g, "<br>")}</p>`] : []
+    for (const f of files) {
+      if (IMAGE.test(f.name)) {
+        const url = urls.get(f.path) || (await upload(f))
+        parts.push(`<p><b>${esc(f.name)}</b><br><img src="${url}" alt="${esc(f.name)}"></p>`)
+        out.inline.push(f.name)
+      } else if (TEXT.test(f.name) && f.data.length <= MAX_COMMENT_TEXT) {
+        parts.push(`<p><b>${esc(f.name)}</b></p><pre>${esc(f.data.toString("utf8"))}</pre>`)
+        out.inline.push(f.name)
+      } else {
+        // An HTML report or a big file cannot go in a comment: it is attached, and the comment names it.
+        const url = urls.get(f.path) || (await upload(f))
+        if (!urls.has(f.path)) {
+          await http(`${org}/_apis/wit/workitems/${id}?api-version=7.1`, {
+            method: "PATCH",
+            auth,
+            body: [{ op: "add", path: "/relations/-", value: { rel: "AttachedFile", url, attributes: { comment: "Added by ForgeQE" } } }],
+            contentType: "application/json-patch+json",
+          })
+          out.attached.push(f.name)
+        }
+        parts.push(`<p>Attached: <a href="${url}">${esc(f.name)}</a></p>`)
+      }
+    }
+    await http(`${scoped}/_apis/wit/workItems/${id}/comments?api-version=7.1-preview.4`, { auth, body: { text: parts.join("\n") } })
+    out.commented = true
+  }
+  return out
+}
+
+async function toJira(config: AppConfig, key: string, files: File[], mode: string, comment: string): Promise<Outcome> {
+  const j = jiraApi(config.sources, "Attaching to Jira")
+  const issue = key.trim().toUpperCase()
+  if (!/^[A-Z][A-Z0-9_]*-\d+$/.test(issue)) throw new Error(`A Jira issue key looks like SHOP-12; got "${key}".`)
+  const out: Outcome = { item: issue, url: `${j.url}/browse/${issue}`, attached: [], commented: false, inline: [] }
+  // Jira shows images from the issue's attachments, so files go up as attachments in either mode.
+  const send = files.filter((f) => mode !== "comment" || !(TEXT.test(f.name) && f.data.length <= MAX_COMMENT_TEXT))
+  for (const f of send) {
+    const form = new FormData()
+    form.append("file", new Blob([new Uint8Array(f.data)], { type: f.type }), f.name)
+    const res = await fetch(`${j.api}/issue/${encodeURIComponent(issue)}/attachments`, {
+      method: "POST",
+      headers: { Authorization: j.auth, "X-Atlassian-Token": "no-check", Accept: "application/json" },
+      body: form,
+    })
+    if (!res.ok) throw new Error(`Attaching ${f.name} to ${issue} failed: ${res.status} ${res.statusText}.`)
+    out.attached.push(f.name)
+  }
+  if (mode === "comment" || mode === "both") {
+    const lines = comment ? [comment, ""] : []
+    for (const f of files) {
+      if (TEXT.test(f.name) && f.data.length <= MAX_COMMENT_TEXT) {
+        lines.push(`${f.name}:`, f.data.toString("utf8"), "")
+        out.inline.push(f.name)
+      } else if (IMAGE.test(f.name) && !j.cloud) {
+        // Jira Server/Data Center wiki markup shows an attached image in the comment.
+        lines.push(`!${f.name}|thumbnail!`)
+        out.inline.push(f.name)
+      } else lines.push(`Attached: ${f.name}`)
+    }
+    const text = lines.join("\n").trim()
+    await http(`${j.api}/issue/${encodeURIComponent(issue)}/comment`, { auth: j.auth, body: { body: j.cloud ? textToAdf(text) : text } })
+    out.commented = true
+  }
+  return out
+}
+
+export const ATTACH_TOOLS: McpTool[] = [
+  {
+    name: "attach_to_work_item",
+    description:
+      "Put evidence on an existing Azure DevOps work item or Jira issue, when the user asks (\"add the screenshot to ADO 256\", \"attach the report to SHOP-12\", \"comment the results on the bug\"). mode attach uploads the files as attachments; comment posts a comment with images shown inline and text files as text (an HTML report cannot be shown in a comment, so it is attached and named); both does both. Files come from a run folder by what they are (pick), or by path; only files in the working folder or the reports folders can be sent. Returns the item's link and what went where.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", enum: ["azure_devops", "jira"] },
+        item: { type: "string", description: "Work item id (azure_devops), e.g. 256, or issue key (jira), e.g. SHOP-12" },
+        mode: { type: "string", enum: ["attach", "comment", "both"], description: "attach: upload as attachments. comment: one comment with the files in it. both: attachments and a comment (default when the user did not say)" },
+        run_dir: { type: "string", description: "A run or suite folder from browser_run or run_test_cases, to pick files from" },
+        pick: { type: "array", items: { type: "string", enum: PICKS }, description: "What to take from run_dir: last_screenshot, failure_screenshot, report, junit, trace" },
+        files: { type: "array", items: { type: "string" }, description: "Other files by path, relative to the working folder" },
+        comment: { type: "string", description: "Text for the comment (comment/both), and the attachment note: what ran, where, the result" },
+      },
+      required: ["system", "item"],
+    },
+    async run(args, ctx) {
+      const mode = String(args.mode || "both")
+      if (!["attach", "comment", "both"].includes(mode)) throw new Error(`mode is attach, comment, or both; got "${mode}".`)
+      const picks = (Array.isArray(args.pick) ? args.pick.map(String) : []) as Pick[]
+      const bad = picks.filter((p) => !PICKS.includes(p))
+      if (bad.length) throw new Error(`pick takes ${PICKS.join(", ")}; got ${bad.join(", ")}.`)
+      if (picks.length && !args.run_dir) throw new Error("pick needs run_dir: the run folder to take the files from.")
+      const runDir = args.run_dir ? path.resolve(ctx.cwd, String(args.run_dir)) : ""
+      const paths = [...(runDir ? pickFiles(runDir, picks.length ? picks : ["last_screenshot"]) : []), ...(Array.isArray(args.files) ? args.files.map((f) => path.resolve(ctx.cwd, String(f))) : [])]
+      const comment = String(args.comment || "").trim()
+      if (!paths.length && !comment) throw new Error("Nothing to add: give run_dir (and pick), files, or a comment.")
+      if (!paths.length && mode === "attach") throw new Error("Nothing to attach: give run_dir (and pick) or files.")
+      const files = [...new Set(paths)].map((p) => readAllowed(p, ctx.config, ctx.cwd))
+      const out = args.system === "jira" ? await toJira(ctx.config, String(args.item), files, mode, comment) : await toAdo(ctx.config, String(args.item), files, mode, comment)
+      return {
+        item: out.item,
+        ...(out.url ? { link: out.url } : {}),
+        ...(out.attached.length ? { attached: out.attached } : {}),
+        ...(out.commented ? { comment: out.inline.length ? `posted, with ${out.inline.join(", ")} in it` : "posted" } : {}),
+      }
+    },
+  },
+]

package/src/mcp/commands.ts

@@ -361,7 +361,7 @@ export const COMMAND_TOOLS: McpTool[] = [
             note: "The user switches profiles with Tab or /profile in the shell, or --profile.",
           }
         case "mcp_servers": {
-          const { servers, skipped } = externalMcp(cfg)
+          const { servers, skipped } = externalMcp(cfg, Bun.which, process.env, { cwd: ctx.cwd })
           return {
             servers: servers.map((s) => {
               const c = s.config as { type: string; command?: string[]; url?: string }