@mmerterden/multi-agent-pipeline 20.29.0 → 20.30.0

package/pipeline/scripts/run-results.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+/**
+ * @file run-results.mjs  -  what a run produced, read from its own files: the
+ * diff summary, the review findings, the test outcome, the screenshots and,
+ * for an analysis run, the documents it wrote.
+ *
+ * Every source is a file or a state field the phases already write; nothing is
+ * computed here that a phase did not record:
+ *
+ *   diff      agent-state `diffRisk` (diff-risk-score.mjs, Phase 3), else the
+ *             file and line counts of `.review-diff.txt`
+ *   findings  `triage-output.json` (Phase 3 triage), else agent-state
+ *             `review.findings` (a standalone /multi-agent:review)
+ *   tests     agent-state `uiTest` and the `test-summary` gate entries
+ *             (test-summary.mjs)
+ *   evidence  `.pipeline/evidence/*.png|jpg` and agent-state `visualEvidence`
+ *   analysis  agent-state `analysisSpec.outputs` (the documents' text) and
+ *             `analysis.docPath[]`
+ *
+ * Each file is looked for in the run's log directory, its `artifacts/` copy
+ * (worktree-finalize.sh salvages there) and, while the run is live, its
+ * worktree. The state's worktreePath is used only when git lists it as a
+ * worktree of the state's projectRoot. A part with no source is null, never
+ * an empty success.
+ *
+ * An analysis document is read only when its real path sits inside one of
+ * those roots and it is Markdown or HTML; any other path in the state keeps
+ * its name with `text: null`, so a state file cannot point the reader at an
+ * arbitrary file.
+ *
+ * Text a person or tool wrote (finding text, test names, document bodies) is
+ * scrubbed and run through the credential redactor; paths are reduced to file
+ * names.
+ *
+ * Usage:
+ *   run-results.mjs <task-id> [--json]
+ *   run-results.mjs <task-id> --evidence <name>      one image, base64, as JSON
+ *
+ * Exit: 0 printed, 2 usage, 3 no such run or image.
+ *
+ * @module pipeline/scripts/run-results
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { selectRuns } from "./runs-index.mjs";
+import { createRedactor } from "./transcript-index.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const EVIDENCE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.(?:png|jpe?g)$/i;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+const MAX_DOC_CHARS = 200_000;
+const MAX_FINDINGS = 200;
+const DOC_EXT = /\.(?:md|markdown|html?)$/i;
+
+export class ResultsError extends Error {}
+
+function readState(dir) {
+  for (const p of [join(dir, "agent-state.json"), join(dir, "artifacts", "agent-state.json")]) {
+    if (existsSync(p)) return readRegularJson(p, null) ?? {};
+  }
+  return {};
+}
+
+const realOrNull = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The state's worktreePath when git lists it as a worktree of the state's
+ * projectRoot, else null.
+ */
+export function verifiedWorktree(state) {
+  const wt = typeof state.worktreePath === "string" ? realOrNull(state.worktreePath) : null;
+  const root = typeof state.projectRoot === "string" ? realOrNull(state.projectRoot) : null;
+  if (!wt || !root) return null;
+  let listing;
+  try {
+    listing = execFileSync("git", ["-C", root, "worktree", "list", "--porcelain"], {
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+  for (const line of listing.split("\n")) {
+    if (line.startsWith("worktree ") && realOrNull(line.slice(9)) === wt) return wt;
+  }
+  return null;
+}
+
+/** The directories a run's files may be in, most durable first. */
+function roots(run, state) {
+  const out = [run.dir, join(run.dir, "artifacts")];
+  const wt = verifiedWorktree(state);
+  if (wt) out.push(wt);
+  return out;
+}
+
+/** The real path of `p` when it is a Markdown or HTML file inside one of `dirs`. */
+function containedDoc(p, dirs) {
+  const real = realOrNull(p);
+  if (!real || !DOC_EXT.test(real)) return null;
+  for (const d of dirs) {
+    const rd = realOrNull(d);
+    if (rd && real.startsWith(rd + sep)) return real;
+  }
+  return null;
+}
+
+function firstExisting(dirs, rel) {
+  for (const d of dirs) {
+    const p = join(d, rel);
+    try {
+      if (statSync(p).isFile()) return p;
+    } catch {
+      // Not in this root.
+    }
+  }
+  return null;
+}
+
+function diffPart(state, dirs) {
+  const r = state.diffRisk;
+  if (r && typeof r === "object" && Number.isInteger(r.files)) {
+    return {
+      files: r.files,
+      added: Number.isInteger(r.loc_added) ? r.loc_added : null,
+      removed: Number.isInteger(r.loc_removed) ? r.loc_removed : null,
+      maxScore: typeof r.max_score === "number" ? r.max_score : null,
+      signals: Array.isArray(r.signals) ? r.signals.map(String) : [],
+      changed: [],
+      source: "diffRisk",
+    };
+  }
+  const p = firstExisting(dirs, ".review-diff.txt");
+  if (!p) return null;
+  const files = new Set();
+  let added = 0;
+  let removed = 0;
+  for (const line of readFileSync(p, "utf8").split("\n")) {
+    const m = /^\+\+\+ b\/(.+)$/.exec(line);
+    if (m) files.add(m[1]);
+    else if (line.startsWith("+") && !line.startsWith("+++")) added++;
+    else if (line.startsWith("-") && !line.startsWith("---")) removed++;
+  }
+  return {
+    files: files.size,
+    added,
+    removed,
+    maxScore: null,
+    signals: [],
+    changed: [...files].slice(0, 200).map((f) => basename(f)),
+    source: ".review-diff.txt",
+  };
+}
+
+function findingsPart(state, dirs, R) {
+  const p = firstExisting(dirs, "triage-output.json");
+  const triage = p ? readRegularJson(p, null) : null;
+  const shape = (f, verdict) => ({
+    severity: String(f?.severity ?? "unknown"),
+    file: f?.file ? basename(String(f.file)) : null,
+    line: Number.isInteger(f?.line) ? f.line : null,
+    issue: R.excerpt(f?.issue ?? f?.title ?? f?.message ?? "", 400),
+    fix: f?.fix ? R.excerpt(f.fix, 400) : null,
+    reviewer: f?.reviewer ? String(f.reviewer) : null,
+    verdict,
+  });
+  if (triage && typeof triage === "object") {
+    const items = [];
+    for (const v of ["accepted", "deferred", "rejected"]) {
+      for (const f of Array.isArray(triage[v]) ? triage[v] : []) items.push(shape(f, v));
+    }
+    return {
+      approved: typeof triage.approved === "boolean" ? triage.approved : null,
+      items: items.slice(0, MAX_FINDINGS),
+      total: items.length,
+      source: "triage-output.json",
+    };
+  }
+  const review = state.review;
+  if (review && Array.isArray(review.findings)) {
+    const items = review.findings.map((f) => shape(f, f?.status ?? f?.verdict ?? "accepted"));
+    return {
+      approved: null,
+      items: items.slice(0, MAX_FINDINGS),
+      total: items.length,
+      source: "agent-state review",
+    };
+  }
+  return null;
+}
+
+function testsPart(state, R) {
+  const gates = Array.isArray(state.gates) ? state.gates : [];
+  const summaries = gates.filter(
+    (g) => g && (g.gate === "test-summary" || g.name === "test-summary"),
+  );
+  const last = summaries.at(-1) ?? null;
+  const ui = state.uiTest && typeof state.uiTest === "object" ? state.uiTest : null;
+  if (!last && !ui) return null;
+  const count = (k) => {
+    const v = last?.counts?.[k] ?? last?.[k];
+    return Number.isInteger(v) ? v : null;
+  };
+  return {
+    status: last?.status ?? last?.verdict ?? ui?.status ?? null,
+    passed: count("passed"),
+    failed: count("failed"),
+    skipped: count("skipped"),
+    uiTest: ui
+      ? {
+          ran: ui.ran === true,
+          status: ui.status ?? null,
+          notRunReason: ui.notRunReason ? R.excerpt(ui.notRunReason, 200) : null,
+        }
+      : null,
+    source: last ? "test-summary gate" : "agent-state uiTest",
+  };
+}
+
+function evidenceDirs(dirs) {
+  return dirs.map((d) => join(d, ".pipeline", "evidence")).filter((d) => existsSync(d));
+}
+
+function evidencePart(state, dirs) {
+  const names = new Map();
+  for (const d of evidenceDirs(dirs)) {
+    let list;
+    try {
+      list = readdirSync(d);
+    } catch {
+      continue;
+    }
+    for (const f of list) if (EVIDENCE_NAME.test(f) && !names.has(f)) names.set(f, null);
+  }
+  const ve = state.visualEvidence;
+  for (const side of ["before", "after"]) {
+    for (const e of Array.isArray(ve?.[side]) ? ve[side] : []) {
+      const f = typeof e?.file === "string" ? basename(e.file) : null;
+      if (f && names.has(f)) names.set(f, side);
+    }
+  }
+  return [...names.entries()].sort().map(([name, phase]) => ({ name, phase }));
+}
+
+function analysisPart(state, dirs, R) {
+  const outputs = state.analysisSpec?.outputs;
+  const paths = [
+    ...(Array.isArray(outputs?.localPaths) ? outputs.localPaths : []),
+    ...(Array.isArray(state.analysis?.docPath) ? state.analysis.docPath : []),
+  ].filter((p) => typeof p === "string");
+  if (!paths.length && !outputs) return null;
+  const documents = [];
+  for (const p of [...new Set(paths)]) {
+    const real = containedDoc(p, dirs);
+    try {
+      if (!real || !statSync(real).isFile()) throw new Error("not readable here");
+      const text = readFileSync(real, "utf8").slice(0, MAX_DOC_CHARS);
+      documents.push({ name: basename(p), text: R.clean(text) });
+    } catch {
+      documents.push({ name: basename(p), text: null });
+    }
+  }
+  return {
+    documents,
+    confluencePages: Array.isArray(outputs?.confluencePageUrls)
+      ? outputs.confluencePageUrls.length
+      : 0,
+    jiraIssueKey:
+      typeof outputs?.jiraIssueKey === "string" &&
+      /^[A-Z][A-Z0-9_]*-[0-9]+$/.test(outputs.jiraIssueKey)
+        ? outputs.jiraIssueKey
+        : null,
+  };
+}
+
+function runFor(taskId) {
+  const { found, records } = selectRuns({ taskId });
+  if (!found || !records.length) throw new ResultsError("no such run");
+  return records[0];
+}
+
+/** Everything a run produced, as one document. */
+export function runResults(taskId) {
+  const run = runFor(taskId);
+  const state = readState(run.dir);
+  const dirs = roots(run, state);
+  const R = createRedactor();
+  return {
+    contractVersion: CONTRACT_VERSION,
+    taskId: run.taskId,
+    diff: diffPart(state, dirs),
+    findings: findingsPart(state, dirs, R),
+    tests: testsPart(state, R),
+    evidence: evidencePart(state, dirs),
+    analysis: analysisPart(state, dirs, R),
+  };
+}
+
+/**
+ * One screenshot as base64. The name must be a bare image file name found in
+ * one of the run's evidence directories; its real path must stay inside it.
+ */
+export function runEvidence(taskId, name) {
+  if (typeof name !== "string" || !EVIDENCE_NAME.test(name))
+    throw new ResultsError("no such image");
+  const run = runFor(taskId);
+  const state = readState(run.dir);
+  for (const d of evidenceDirs(roots(run, state))) {
+    const p = join(d, name);
+    let real;
+    let realDir;
+    try {
+      real = realpathSync(p);
+      realDir = realpathSync(d);
+    } catch {
+      continue;
+    }
+    if (!real.startsWith(realDir + sep)) continue;
+    const st = statSync(real);
+    if (!st.isFile() || st.size > MAX_IMAGE_BYTES) continue;
+    const mime = /\.png$/i.test(name) ? "image/png" : "image/jpeg";
+    return {
+      contractVersion: CONTRACT_VERSION,
+      taskId: run.taskId,
+      name,
+      mime,
+      data: readFileSync(real).toString("base64"),
+    };
+  }
+  throw new ResultsError("no such image");
+}
+
+function main(argv) {
+  const [taskId, ...rest] = argv;
+  if (!taskId) {
+    process.stderr.write("usage: run-results.mjs <task-id> [--json] | --evidence <name>\n");
+    return 2;
+  }
+  try {
+    if (rest[0] === "--evidence") {
+      process.stdout.write(JSON.stringify(runEvidence(taskId, rest[1])) + "\n");
+      return 0;
+    }
+    if (rest.some((a) => a !== "--json")) {
+      process.stderr.write("usage: run-results.mjs <task-id> [--json] | --evidence <name>\n");
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(runResults(taskId), null, 2) + "\n");
+    return 0;
+  } catch (err) {
+    if (!(err instanceof ResultsError)) throw err;
+    process.stderr.write(`run-results: ${err.message}\n`);
+    return 3;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("run-results", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/service-read.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * @file service-read.mjs  -  read one thing from Confluence, Crashlytics or
+ * Figma through the clients the pipeline already ships, for a client that
+ * shows it next to a run:
+ *
+ *   confluence <page>        lib/fetch-confluence.sh: a page by id or by https
+ *                            URL, both only on the configured
+ *                            prefs.global.hosts.confluence; a URL on any other
+ *                            host, or any URL when no host is configured, is
+ *                            refused before the script runs; title, markdown
+ *                            body, API contracts count
+ *   crashlytics <issue-url>  lib/fetch-crashlytics.sh: one Crashlytics issue,
+ *                            title, occurrences, impacted users, top frames
+ *   figma <file-key> <node>  lib/figma-screenshot.sh (REST with the Figma
+ *                            token, tier 2): one PNG render of a frame. The
+ *                            Figma MCP is never called here; the pipeline
+ *                            keeps MCP access to the analysis phase.
+ *
+ * Search across Confluence, a per-version Crashlytics trend and a Figma file
+ * browser have no client in the pipeline, so none is offered; a client asks
+ * an agent instead.
+ *
+ * The scripts run as child processes without blocking the caller's event
+ * loop (contract-server.mjs serves other routes meanwhile).
+ *
+ * Credentials are read only by those scripts, through credential-store.sh.
+ * Every text that comes back is scrubbed and redacted; an image comes back as
+ * base64.
+ *
+ * Usage:
+ *   service-read.mjs confluence <page-id|https-url>
+ *   service-read.mjs crashlytics <https-issue-url>
+ *   service-read.mjs figma <file-key> <node-id>
+ *
+ * MA_FETCH_CONFLUENCE, MA_FETCH_CRASHLYTICS and MA_FIGMA_SCREENSHOT stand in
+ * for the scripts (tests).
+ *
+ * Exit: 0 printed, 1 refused or failed, 2 usage.
+ *
+ * @module pipeline/scripts/service-read
+ */
+
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRedactor } from "./transcript-index.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TIMEOUT_MS = 90_000;
+const MAX_TEXT = 100_000;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+export const PAGE_ID = /^[0-9]{1,20}$/;
+export const FIGMA_KEY = /^[A-Za-z0-9]{10,64}$/;
+export const FIGMA_NODE = /^[0-9]{1,10}[:-][0-9]{1,10}$/;
+
+export class ServiceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const script = (env, name, override) =>
+  env[override] ||
+  [join(HERE, "..", "lib", name), join(HERE, "..", "..", "lib", name)].find((p) => existsSync(p));
+
+function httpsUrl(v, host = null) {
+  if (typeof v !== "string" || v.length > 2048) return null;
+  let u;
+  try {
+    u = new URL(v);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" || u.username || u.password) return null;
+  if (host && u.hostname !== host) return null;
+  return u.toString();
+}
+
+async function run(env, file, args, failCodes) {
+  if (!file) throw new ServiceError("not-installed", "the service client is not installed");
+  const r = await spawnAsync("bash", [file, ...args], { env, timeoutMs: TIMEOUT_MS });
+  if (r.status !== 0) {
+    const why = failCodes[r.status] ?? "the service could not be read";
+    throw new ServiceError("service-failed", why);
+  }
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    throw new ServiceError(
+      "service-failed",
+      "the service answered with something that is not JSON",
+    );
+  }
+}
+
+function confluenceHost(env) {
+  try {
+    const prefs = JSON.parse(
+      readFileSync(
+        env.MULTI_AGENT_PREFS ||
+          join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json"),
+        "utf8",
+      ),
+    );
+    const h = prefs?.global?.hosts?.confluence;
+    return typeof h === "string" && h ? h.replace(/^https?:\/\//, "").replace(/\/.*$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One Confluence page, by id or by a URL on the configured host only. */
+export async function confluencePage(page, env = process.env) {
+  let args;
+  const host = confluenceHost(env);
+  if (PAGE_ID.test(String(page))) {
+    if (!host) throw new ServiceError("not-configured", "no Confluence host is configured");
+    args = ["--host", host, "--page-id", String(page)];
+  } else {
+    const url = httpsUrl(page);
+    if (!url) throw new ServiceError("bad-input", "a page id or an https URL is required");
+    if (!host) {
+      throw new ServiceError(
+        "host-not-allowed",
+        "no Confluence host is configured, so only a page id is accepted",
+      );
+    }
+    if (new URL(url).hostname !== host) {
+      throw new ServiceError("host-not-allowed", "that host is not the configured Confluence host");
+    }
+    args = [url];
+  }
+  const d = await run(env, script(env, "fetch-confluence.sh", "MA_FETCH_CONFLUENCE"), args, {
+    2: "the Confluence credential is missing or was refused",
+    3: "Confluence could not be reached",
+    6: "that host is not the configured Confluence host",
+  });
+  const R = createRedactor();
+  return {
+    contractVersion: CONTRACT_VERSION,
+    service: "confluence",
+    pageId: d?.source?.pageId ? String(d.source.pageId) : null,
+    title: R.excerpt(d?.title ?? "", 300),
+    body: R.clean(String(d?.bodyMarkdown ?? "").slice(0, MAX_TEXT)),
+    apiContracts: Array.isArray(d?.apiContracts) ? d.apiContracts.length : 0,
+  };
+}
+
+/** One Crashlytics issue. */
+export async function crashlyticsIssue(issueUrl, env = process.env) {
+  const url = httpsUrl(issueUrl, "console.firebase.google.com");
+  if (!url) throw new ServiceError("bad-input", "a Firebase console issue URL is required");
+  const d = await run(env, script(env, "fetch-crashlytics.sh", "MA_FETCH_CRASHLYTICS"), [url], {
+    2: "the Firebase credential is missing or was refused",
+    3: "Crashlytics could not be reached",
+  });
+  const R = createRedactor();
+  const i = d?.issue ?? {};
+  return {
+    contractVersion: CONTRACT_VERSION,
+    service: "crashlytics",
+    title: R.excerpt(i.title ?? "", 300),
+    type: i.type ? String(i.type) : null,
+    occurrences: Number.isFinite(i.occurrences) ? i.occurrences : null,
+    impactedUsers: Number.isFinite(i.impactedUsers) ? i.impactedUsers : null,
+    stackTrace: (Array.isArray(i.stackTrace) ? i.stackTrace : [])
+      .slice(0, 40)
+      .map((f) => R.excerpt(typeof f === "string" ? f : JSON.stringify(f), 300)),
+  };
+}
+
+/** One frame rendered as PNG. */
+export async function figmaFrame(fileKey, nodeId, env = process.env) {
+  if (!FIGMA_KEY.test(String(fileKey)) || !FIGMA_NODE.test(String(nodeId))) {
+    throw new ServiceError("bad-input", "a Figma file key and a node id (1:2) are required");
+  }
+  const out = mkdtempSync(join(tmpdir(), "ma-figma-"));
+  try {
+    const file = script(env, "figma-screenshot.sh", "MA_FIGMA_SCREENSHOT");
+    if (!file) throw new ServiceError("not-installed", "the service client is not installed");
+    const r = await spawnAsync(
+      "bash",
+      [file, "--file-key", fileKey, "--node-id", nodeId.replace("-", ":"), "--output-dir", out],
+      { env, timeoutMs: TIMEOUT_MS, maxBytes: 1024 * 1024 },
+    );
+    const why = {
+      2: "the Figma token is missing or was refused",
+      4: "no such frame",
+      5: "Figma is rate limiting; try again later",
+      6: "Figma could not be reached",
+    };
+    if (r.status !== 0)
+      throw new ServiceError("service-failed", why[r.status] ?? "the frame could not be rendered");
+    const png = readdirSync(out).find((f) => f.endsWith(".png"));
+    if (!png || statSync(join(out, png)).size > MAX_IMAGE_BYTES) {
+      throw new ServiceError("service-failed", "the frame could not be rendered");
+    }
+    return {
+      contractVersion: CONTRACT_VERSION,
+      service: "figma",
+      fileKey,
+      nodeId: nodeId.replace("-", ":"),
+      mime: "image/png",
+      data: readFileSync(join(out, png)).toString("base64"),
+    };
+  } finally {
+    rmSync(out, { recursive: true, force: true });
+  }
+}
+
+async function main(argv) {
+  const [svc, a, b, ...rest] = argv;
+  try {
+    let out;
+    if (svc === "confluence" && a && !b) out = await confluencePage(a);
+    else if (svc === "crashlytics" && a && !b) out = await crashlyticsIssue(a);
+    else if (svc === "figma" && a && b && !rest.length) out = await figmaFrame(a, b);
+    else {
+      process.stderr.write(
+        "usage: service-read.mjs confluence <page> | crashlytics <issue-url> | figma <file-key> <node-id>\n",
+      );
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return 0;
+  } catch (err) {
+    if (!(err instanceof ServiceError)) throw err;
+    process.stderr.write(`service-read: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("service-read", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}