@bugmole/cli 0.4.0 → 0.6.0

package/src/integrations/jira.ts

@@ -0,0 +1,264 @@
+// A small Jira Cloud REST client (platform API v3) for what the Bugmole
+// integration needs: create and find issues, read transitions, move an
+// issue, comment with @mentions, and edit labels.
+//
+// Authentication is behind JiraAuthProvider so OAuth 2.0 (3LO) can be added
+// without touching the calls. Today there is one provider, an Atlassian API
+// token (Basic auth with the account email). 3LO needs an Atlassian developer
+// app registered at developer.atlassian.com (client id and secret, callback
+// URL, scopes read:jira-work write:jira-work read:jira-user offline_access);
+// its calls go to https://api.atlassian.com/ex/jira/<cloudId> with a Bearer
+// token instead of the site URL.
+//
+// Nothing here logs or returns a credential: errors carry the HTTP status and
+// Jira's own error text, never request headers.
+
+export type JiraFetchEnv = {
+  /** Test seam. */
+  JIRA_FETCH?: typeof fetch;
+};
+
+export class JiraApiError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message);
+  }
+}
+
+/** Supplies the base URL and Authorization header for Jira calls. */
+export interface JiraAuthProvider {
+  readonly kind: "api_token" | "oauth";
+  /** Where REST paths are resolved: the site for API tokens, api.atlassian.com/ex/jira/<cloudId> for 3LO. */
+  readonly apiBase: string;
+  authorization(): Promise<string>;
+}
+
+export class ApiTokenAuth implements JiraAuthProvider {
+  readonly kind = "api_token" as const;
+  readonly apiBase: string;
+  readonly #header: string;
+
+  constructor(siteUrl: string, email: string, token: string) {
+    this.apiBase = siteUrl.replace(/\/+$/, "");
+    const bytes = new TextEncoder().encode(`${email}:${token}`);
+    let binary = "";
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    this.#header = `Basic ${btoa(binary)}`;
+  }
+
+  async authorization(): Promise<string> {
+    return this.#header;
+  }
+
+  /** Never serialize the credential, even by accident. */
+  toJSON() {
+    return { kind: this.kind, apiBase: this.apiBase };
+  }
+}
+
+const SITE = /^https:\/\/[a-z0-9][a-z0-9-]{0,62}\.atlassian\.net$/;
+
+/**
+ * A Jira Cloud site URL, normalized to https://<name>.atlassian.net, or null.
+ * Only Atlassian-hosted sites are accepted, so a connection can't point the
+ * registry's requests at an arbitrary host.
+ */
+export function normalizeJiraSite(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  let text = value.trim().toLowerCase();
+  if (!text) return null;
+  if (!/^https?:\/\//.test(text)) text = `https://${text}`;
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.port) return null;
+  const site = `https://${url.hostname}`;
+  return SITE.test(site) ? site : null;
+}
+
+export const JIRA_PROJECT_KEY = /^[A-Z][A-Z0-9_]{1,9}$/;
+
+// --- Atlassian Document Format ----------------------------------------------------------------
+
+export type AdfNode = { type: string; attrs?: Record<string, unknown>; content?: AdfNode[]; text?: string; marks?: Array<{ type: string; attrs?: Record<string, unknown> }> };
+export type AdfDoc = { type: "doc"; version: 1; content: AdfNode[] };
+
+export const adf = {
+  doc(...content: AdfNode[]): AdfDoc {
+    return { type: "doc", version: 1, content };
+  },
+  paragraph(...content: AdfNode[]): AdfNode {
+    return { type: "paragraph", content };
+  },
+  text(text: string, marks?: AdfNode["marks"]): AdfNode {
+    return marks?.length ? { type: "text", text, marks } : { type: "text", text };
+  },
+  strong(text: string): AdfNode {
+    return { type: "text", text, marks: [{ type: "strong" }] };
+  },
+  link(text: string, href: string): AdfNode {
+    return { type: "text", text, marks: [{ type: "link", attrs: { href } }] };
+  },
+  mention(accountId: string, name?: string): AdfNode {
+    return { type: "mention", attrs: { id: accountId, text: `@${name ?? accountId}` } };
+  },
+  heading(level: number, text: string): AdfNode {
+    return { type: "heading", attrs: { level }, content: [{ type: "text", text }] };
+  },
+  bullets(items: AdfNode[][]): AdfNode {
+    return { type: "bulletList", content: items.map((content) => ({ type: "listItem", content: [{ type: "paragraph", content }] })) };
+  },
+  ordered(items: string[]): AdfNode {
+    return { type: "orderedList", content: items.map((item) => ({ type: "listItem", content: [{ type: "paragraph", content: [{ type: "text", text: item }] }] })) };
+  },
+};
+
+/** Plain text of a comment body: ADF (API v3) or a wiki-markup string (webhooks, API v2). */
+export function commentText(body: unknown): string {
+  if (typeof body === "string") return body;
+  const parts: string[] = [];
+  const walk = (node: unknown) => {
+    if (!node || typeof node !== "object") return;
+    const value = node as AdfNode;
+    if (value.type === "text" && typeof value.text === "string") parts.push(value.text);
+    if (value.type === "mention" && typeof value.attrs?.text === "string") parts.push(value.attrs.text as string);
+    if (Array.isArray(value.content)) {
+      for (const child of value.content) walk(child);
+      if (value.type === "paragraph") parts.push("\n");
+    }
+  };
+  walk(body);
+  return parts.join(" ").replace(/[ \t]+/g, " ").trim();
+}
+
+/** Account ids mentioned in a comment body: ADF mention nodes, or [~accountid:…] in wiki markup. */
+export function mentionedAccountIds(body: unknown): string[] {
+  const ids = new Set<string>();
+  if (typeof body === "string") {
+    for (const match of body.matchAll(/\[~accountid:([^\]]+)\]/g)) ids.add(match[1]);
+    return [...ids];
+  }
+  const walk = (node: unknown) => {
+    if (!node || typeof node !== "object") return;
+    const value = node as AdfNode;
+    if (value.type === "mention" && typeof value.attrs?.id === "string") ids.add(value.attrs.id as string);
+    if (Array.isArray(value.content)) for (const child of value.content) walk(child);
+  };
+  walk(body);
+  return [...ids];
+}
+
+// --- REST --------------------------------------------------------------------------------------
+
+export type JiraUser = { accountId: string; displayName?: string; emailAddress?: string };
+export type JiraStatus = { name: string; statusCategory?: { key: string; name?: string } };
+export type JiraTransition = { id: string; name: string; to: JiraStatus };
+export type JiraIssue = {
+  id: string;
+  key: string;
+  fields: {
+    summary?: string;
+    status?: JiraStatus;
+    labels?: string[];
+    assignee?: JiraUser | null;
+    reporter?: JiraUser | null;
+  };
+};
+
+export class JiraClient {
+  constructor(private readonly env: JiraFetchEnv, readonly auth: JiraAuthProvider) {}
+
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const response = await (this.env.JIRA_FETCH ?? fetch)(`${this.auth.apiBase}${path}`, {
+      method,
+      headers: {
+        authorization: await this.auth.authorization(),
+        accept: "application/json",
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new JiraApiError(response.status, `Jira ${method} ${path.split("?")[0]} failed (${response.status}) ${jiraErrorText(text)}`.trim());
+    }
+    if (response.status === 204) return undefined as T;
+    const text = await response.text();
+    return (text ? JSON.parse(text) : undefined) as T;
+  }
+
+  myself(): Promise<JiraUser> {
+    return this.request("GET", "/rest/api/3/myself");
+  }
+
+  project(key: string): Promise<{ id: string; key: string; name: string }> {
+    return this.request("GET", `/rest/api/3/project/${encodeURIComponent(key)}`);
+  }
+
+  createIssue(fields: Record<string, unknown>): Promise<{ id: string; key: string }> {
+    return this.request("POST", "/rest/api/3/issue", { fields });
+  }
+
+  getIssue(key: string, fields = "summary,status,labels,assignee,reporter"): Promise<JiraIssue> {
+    return this.request("GET", `/rest/api/3/issue/${encodeURIComponent(key)}?fields=${encodeURIComponent(fields)}`);
+  }
+
+  editIssue(key: string, body: Record<string, unknown>): Promise<void> {
+    return this.request("PUT", `/rest/api/3/issue/${encodeURIComponent(key)}`, body);
+  }
+
+  /** Issues matching a JQL query (the enhanced search endpoint). */
+  async search(jql: string, fields = "summary,labels"): Promise<JiraIssue[]> {
+    const query = new URLSearchParams({ jql, fields, maxResults: "10" });
+    const result = await this.request<{ issues?: JiraIssue[] }>("GET", `/rest/api/3/search/jql?${query}`);
+    return result?.issues ?? [];
+  }
+
+  async transitions(key: string): Promise<JiraTransition[]> {
+    const result = await this.request<{ transitions?: JiraTransition[] }>("GET", `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`);
+    return result?.transitions ?? [];
+  }
+
+  transition(key: string, transitionId: string): Promise<void> {
+    return this.request("POST", `/rest/api/3/issue/${encodeURIComponent(key)}/transitions`, { transition: { id: transitionId } });
+  }
+
+  comment(key: string, body: AdfDoc): Promise<{ id: string }> {
+    return this.request("POST", `/rest/api/3/issue/${encodeURIComponent(key)}/comment`, { body });
+  }
+
+  labels(key: string, change: { add?: string[]; remove?: string[] }): Promise<void> {
+    const operations = [...(change.add ?? []).map((label) => ({ add: label })), ...(change.remove ?? []).map((label) => ({ remove: label }))];
+    return this.editIssue(key, { update: { labels: operations } });
+  }
+}
+
+function jiraErrorText(text: string): string {
+  try {
+    const parsed = JSON.parse(text) as { errorMessages?: string[]; errors?: Record<string, string> };
+    const messages = [...(parsed.errorMessages ?? []), ...Object.entries(parsed.errors ?? {}).map(([field, message]) => `${field}: ${message}`)];
+    return messages.join("; ").slice(0, 300);
+  } catch {
+    return text.slice(0, 200);
+  }
+}
+
+/** The transition that reaches a status in the Done category; one named "Done" first. */
+export function doneTransition(transitions: JiraTransition[]): JiraTransition | undefined {
+  const done = transitions.filter((transition) => transition.to?.statusCategory?.key === "done");
+  return done.find((transition) => transition.to.name.toLowerCase() === "done") ?? done[0];
+}
+
+/** The transition to a status named Blocked (or itself named Blocked), if the workflow has one. */
+export function blockedTransition(transitions: JiraTransition[]): JiraTransition | undefined {
+  return transitions.find((transition) => transition.to?.name?.toLowerCase() === "blocked")
+    ?? transitions.find((transition) => transition.name.toLowerCase() === "blocked");
+}
+
+/** A transition back to a To Do/In Progress-style status, for a ticket that is retested. */
+export function reopenTransition(transitions: JiraTransition[]): JiraTransition | undefined {
+  const open = transitions.filter((transition) => transition.to?.statusCategory?.key === "indeterminate" || transition.to?.statusCategory?.key === "new");
+  return open.find((transition) => /in progress|in test|testing|retest/i.test(transition.to.name)) ?? open[0];
+}

package/src/mcp/roles-and-review.test.ts

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import YAML from "yaml";
+import { callToolInternal, writeSpecFile } from "./server.js";
+import { startLocalRegistryStub } from "../runtime/local-registry-stub.js";
+
+async function project(files: Record<string, string> = {}) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-roles-mcp-"));
+  const specDir = path.join(directory, "spec");
+  await fs.mkdir(specDir, { recursive: true });
+  for (const [name, content] of Object.entries(files)) await fs.writeFile(path.join(specDir, name), content);
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: specDir, artifacts_dir: directory },
+    storage: { provider: "local", localDirectory: directory },
+  };
+  return { directory, specDir, cfg };
+}
+
+/** Points the MCP's registry calls at a local stub for the duration of `run`. */
+async function withRegistry(reviewMode: "manual" | "auto" | "extreme", run: (origin: string) => Promise<void>) {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-roles-registry-"));
+  const stub = await startLocalRegistryStub({ directory, reviewMode });
+  const saved = { url: process.env.BUGMOLE_REGISTRY_URL, key: process.env.BUGMOLE_API_KEY };
+  process.env.BUGMOLE_REGISTRY_URL = stub.origin;
+  process.env.BUGMOLE_API_KEY = "bm_test";
+  try {
+    await run(stub.origin);
+  } finally {
+    if (saved.url === undefined) delete process.env.BUGMOLE_REGISTRY_URL; else process.env.BUGMOLE_REGISTRY_URL = saved.url;
+    if (saved.key === undefined) delete process.env.BUGMOLE_API_KEY; else process.env.BUGMOLE_API_KEY = saved.key;
+    await stub.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+test("bugmole_write_spec lets an agent suggest roles in roles.yaml, never confirm them", async () => {
+  const { specDir, cfg } = await project({ "roles.yaml": "roles:\n  - name: user\n    description: Signed in.\n" });
+  const result = writeSpecFile("roles.yaml", "roles:\n  - name: user\n  - name: admin\n    description: Admin.\n", cfg);
+  assert.deepEqual(result.suggestedRoles, ["admin"]);
+  assert.match(result.message, /person confirms/);
+  const written = YAML.parse(await fs.readFile(path.join(specDir, "roles.yaml"), "utf8"));
+  assert.equal(written.roles[0].status, undefined);
+  assert.equal(written.roles[1].status, "suggested");
+  assert.equal(writeSpecFile("blockers.yaml", "blockers: []\n", cfg).suggestedRoles, undefined, "other spec files are written as given");
+});
+
+test("bugmole_write_test_cases refuses a case set for a role nobody confirmed", async () => {
+  const graph = {
+    version: 2,
+    nodes: [{ id: "screen:/", title: "Home", kind: "screen", route: "/" }],
+    edges: [],
+    journeys: [{ id: "flow:home", name: "Home", actor: "user", nodeIds: ["screen:/"], edgeIds: [], revision: 1, status: "draft" }],
+  };
+  const { cfg } = await project({
+    "journeys.graph.json": JSON.stringify(graph),
+    "roles.yaml": "roles:\n  - name: user\n  - name: admin\n    status: suggested\n",
+  });
+  const caseSet = (actor: string) => ({
+    schemaVersion: 1, caseSetId: "home", journeyId: "flow:home", journeyRevision: 1, actor,
+    cases: [{ caseId: "TC-1", title: "Home loads", nodeId: "screen:/", intent: "Prove home renders", steps: ["Open /"], expected: ["Home renders"], confidence: "low" }],
+  });
+  await assert.rejects(callToolInternal("bugmole_write_test_cases", { caseSet: caseSet("admin") }, cfg), /only suggested/);
+  await assert.rejects(callToolInternal("bugmole_write_test_cases", { caseSet: caseSet("ghost") }, cfg), /not a confirmed role/);
+  const ok = await callToolInternal("bugmole_write_test_cases", { caseSet: caseSet("user") }, cfg);
+  assert.equal(ok.status, "success");
+});
+
+test("bugmole_role_propose sends a suggestion; bugmole_roles_list shows it waiting", async () => {
+  const { cfg } = await project({ "roles.yaml": "roles:\n  - name: user\n" });
+  await withRegistry("extreme", async () => {
+    await assert.rejects(callToolInternal("bugmole_role_propose", { name: "admin" }, cfg), /evidence/);
+    const proposed = await callToolInternal("bugmole_role_propose", {
+      name: "Admin", description: "Admin area.", source: "role_gated_route", evidence: "route /admin",
+    }, cfg);
+    assert.equal(proposed.role.name, "admin");
+    assert.equal(proposed.role.status, "suggested");
+    assert.match(proposed.message, /only after a person confirms/);
+
+    const listed = await callToolInternal("bugmole_roles_list", {}, cfg);
+    assert.deepEqual(listed.confirmed, ["user"]);
+    assert.deepEqual(listed.suggested, ["admin"]);
+    assert.match(listed.nextSteps[0], /Roles page/);
+  });
+});
+
+test("bugmole_task_update says when a completed task went to review, and the note comes back with it", async () => {
+  const { cfg } = await project();
+  await withRegistry("manual", async (origin) => {
+    const created = await callToolInternal("bugmole_task_create", { title: "Fix it", description: "Fix the header", taskType: "code", idempotencyKey: "fix-1" }, cfg);
+    const taskId = created.task.id;
+    const claimed = await callToolInternal("bugmole_task_next", { workerId: "agent-1" }, cfg);
+    assert.equal(claimed.task.id, taskId);
+
+    const done = await callToolInternal("bugmole_task_update", { taskId, workerId: "agent-1", status: "completed", completionSummary: "Fixed" }, cfg);
+    assert.equal(done.inReview, true);
+    assert.equal(done.task.status, "in_review");
+    assert.match(done.nextSteps[0], /not treat this work as accepted/);
+
+    const sent = await fetch(`${origin}/api/tasks/${taskId}/send-back`, {
+      method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ note: "Also fix the footer" }),
+    });
+    assert.equal(sent.status, 200);
+    const again = await callToolInternal("bugmole_task_next", { workerId: "agent-1" }, cfg);
+    assert.equal(again.task.id, taskId);
+    assert.match(again.message, /Also fix the footer/);
+  });
+});