@bugmole/cli 0.5.0 → 0.6.0

package/src/registry-worker/jira/routes.ts

@@ -0,0 +1,432 @@
+// Jira Cloud integration routes, webhook, outbox handlers and hooks.
+//
+// Who can do what:
+// - A project manager, in the dashboard, connects, updates and disconnects
+//   Jira. The API token is write-only: no route returns it, and machine API
+//   keys and runners can't set it.
+// - Project members (people or API keys with project write) propose the test
+//   plan to Jira and create tickets for approved tests.
+// - Jira posts comment events to /api/jira/webhook with the connection's own
+//   secret: as X-Hub-Signature (HMAC-SHA256 of the body, Jira's "Secret"
+//   field), an X-Bugmole-Webhook-Secret header (Jira Automation), or a
+//   `token` query parameter. Every accepted delivery is audited; rejections at most once a minute.
+import type { Env, Principal } from "../core.js";
+import { constantTimeEqual, memberOfProject, newId, randomToken, requestJson, response } from "../core.js";
+import { proposalDecidedHooks, runChangedHooks } from "../hooks.js";
+import { auditProject, recordAudit } from "../org/audit.js";
+import { drainSoon, enqueue, PermanentDeliveryError, registerOutboxHandler } from "../notifications/outbox.js";
+import { matchPath, registerPublicRoutes, registerRoutes, type AuthedRouteContext } from "../routes/index.js";
+import { ApiTokenAuth, adf, commentText, JIRA_PROJECT_KEY, JiraApiError, JiraClient, mentionedAccountIds, normalizeJiraSite, type JiraFetchEnv } from "../../integrations/jira.js";
+import {
+  clientFor, connectionById, connectionOf, connectionView, JIRA_UNCONFIGURED, jiraConfigured, openField, sealField, webhookUrl, issueUrl, type ConnectionRow,
+} from "./connection.js";
+import { isPermanentJiraError, proposePlan, refreshPlanIssue, reportRun, requestRetest, ResultsNotReady, syncTickets } from "./workflow.js";
+
+const EMAIL = /^[^\s@]{1,200}@[^\s@]{1,200}\.[^\s@]{2,}$/;
+const TOKEN_MAX = 1000;
+const KEYWORD_MAX = 60;
+const WEBHOOK_BODY_MAX = 512 * 1024;
+
+const forbidden = () => response({ error: "Project scope is not allowed" }, 403);
+const unconfigured = () => response({ error: JIRA_UNCONFIGURED, code: "jira_unconfigured" }, 503);
+const notConnected = () => response({ error: "This project isn't connected to Jira", code: "jira_not_connected" }, 404);
+
+/** Credentials are entered by people in the dashboard, never by keys or runners. */
+function mayManage(principal: Principal): boolean {
+  return !principal.runner && !principal.apiKeyId;
+}
+
+/** A Jira failure, described without anything that could carry a credential. */
+function jiraProblem(error: unknown): string {
+  if (error instanceof JiraApiError) {
+    if (error.status === 401) return "Jira didn't accept that email and API token.";
+    if (error.status === 403) return "That Jira account doesn't have permission for this.";
+    if (error.status === 404) return "Jira couldn't find that project (check the key and that the account can browse it).";
+    return `Jira answered ${error.status}.`;
+  }
+  return "Couldn't reach Jira.";
+}
+
+async function getConnection({ env, principal }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (principal.runner || !(await memberOfProject(env, principal, projectId))) return forbidden();
+  const row = await connectionOf(env, projectId);
+  const linked = await env.DB.prepare("SELECT COUNT(*) AS count FROM jira_issue_links WHERE project_id = ? AND jira_issue_key IS NOT NULL")
+    .bind(projectId).first<{ count: number }>();
+  return response({
+    available: jiraConfigured(env),
+    connection: row ? connectionView(env, row) : null,
+    linkedTickets: linked?.count ?? 0,
+  });
+}
+
+async function saveConnection({ env, principal, request }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!mayManage(principal)) return response({ error: "Jira is connected by a project manager in the dashboard" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return forbidden();
+  if (!jiraConfigured(env)) return unconfigured();
+  const body = await requestJson(request);
+  const existing = await connectionOf(env, projectId);
+  const siteUrl = body?.siteUrl === undefined && existing ? existing.site_url : normalizeJiraSite(body?.siteUrl);
+  const email = typeof body?.email === "string" ? body.email.trim() : existing?.account_email ?? "";
+  const apiToken = typeof body?.apiToken === "string" ? body.apiToken.trim() : "";
+  const projectKey = typeof body?.projectKey === "string" ? body.projectKey.trim().toUpperCase() : existing?.jira_project_key ?? "";
+  const keyword = typeof body?.mentionKeyword === "string" ? body.mentionKeyword.trim() : existing?.mention_keyword ?? "@Bugmole";
+  const executionMode = body?.executionMode ?? existing?.execution_mode ?? "self";
+  const environmentId = body?.environmentId === undefined ? existing?.environment_id ?? null : (typeof body.environmentId === "string" && body.environmentId ? body.environmentId : null);
+  const enabled = body?.enabled === undefined ? existing ? Boolean(existing.enabled) : true : body.enabled === true;
+
+  if (!siteUrl) return response({ error: "siteUrl must be your Jira Cloud site, like https://your-team.atlassian.net" }, 422);
+  if (!EMAIL.test(email)) return response({ error: "email is the Atlassian account the API token belongs to" }, 422);
+  if (!JIRA_PROJECT_KEY.test(projectKey)) return response({ error: "projectKey is the Jira project key, like QA or SHOP" }, 422);
+  if (!keyword || keyword.length > KEYWORD_MAX) return response({ error: `mentionKeyword is the text that asks Bugmole to retest, up to ${KEYWORD_MAX} characters` }, 422);
+  if (executionMode !== "self" && executionMode !== "cloud") return response({ error: "executionMode must be self or cloud" }, 422);
+  if (apiToken.length > TOKEN_MAX) return response({ error: "That API token is too long" }, 422);
+  const credentialChanged = !existing || siteUrl !== existing.site_url || email !== existing.account_email;
+  if (credentialChanged && !apiToken) return response({ error: "apiToken is required to connect (and whenever the site or email changes)" }, 422);
+  if (environmentId) {
+    const environment = await env.DB.prepare("SELECT id FROM project_environments WHERE project_id = ? AND id = ?").bind(projectId, environmentId).first();
+    if (!environment) return response({ error: "Environment not found in this project" }, 422);
+  }
+
+  // Verify before storing anything: the credential works and can see the
+  // project. Pausing, resuming or changing the keyword needs no Jira call, so
+  // a revoked token can still be paused.
+  let accountId = existing?.account_id ?? "";
+  if (credentialChanged || apiToken || projectKey !== existing?.jira_project_key || !accountId) {
+    const token = apiToken || (existing ? await openField(env, existing, "credential") : "");
+    const client = new JiraClient(env as Env & JiraFetchEnv, new ApiTokenAuth(siteUrl, email, token));
+    try {
+      accountId = (await client.myself()).accountId;
+      await client.project(projectKey);
+    } catch (error) {
+      return response({ error: jiraProblem(error), code: "jira_unreachable" }, 422);
+    }
+  }
+
+  const id = existing?.id ?? newId("jira");
+  let webhookSecret: string | null = null;
+  if (existing) {
+    const credential = apiToken ? await sealField(env, projectId, id, "credential", apiToken) : null;
+    await env.DB.prepare(`
+      UPDATE project_jira_connections SET site_url = ?, account_email = ?, account_id = ?, jira_project_key = ?, mention_keyword = ?,
+        execution_mode = ?, environment_id = ?, enabled = ?, last_error = NULL, updated_by = ?, updated_at = CURRENT_TIMESTAMP
+        ${credential ? ", credential_ciphertext = ?, credential_iv = ?, credential_key_version = ?" : ""}
+      WHERE id = ?
+    `).bind(
+      siteUrl, email, accountId, projectKey, keyword, executionMode, environmentId, enabled ? 1 : 0, principal.aegisId,
+      ...(credential ? [credential.ciphertext, credential.iv, credential.keyVersion] : []),
+      id,
+    ).run();
+  } else {
+    webhookSecret = randomToken(24);
+    const credential = await sealField(env, projectId, id, "credential", apiToken);
+    const secret = await sealField(env, projectId, id, "webhook", webhookSecret);
+    try {
+      await env.DB.prepare(`
+        INSERT INTO project_jira_connections (id, project_id, site_url, jira_project_key, auth_type, account_email, account_id,
+          credential_ciphertext, credential_iv, credential_key_version, webhook_secret_ciphertext, webhook_secret_iv, webhook_key_version,
+          mention_keyword, execution_mode, environment_id, enabled, created_by, updated_by)
+        VALUES (?, ?, ?, ?, 'api_token', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).bind(
+        id, projectId, siteUrl, projectKey, email, accountId, credential.ciphertext, credential.iv, credential.keyVersion,
+        secret.ciphertext, secret.iv, secret.keyVersion, keyword, executionMode, environmentId, enabled ? 1 : 0, principal.aegisId, principal.aegisId,
+      ).run();
+    } catch {
+      return response({ error: "This project was just connected by someone else; reload and try again" }, 409);
+    }
+  }
+  await auditProject(env, principal, projectId, {
+    action: existing ? "jira.updated" : "jira.connected",
+    targetType: "jira_connection",
+    targetId: id,
+    data: { siteUrl, projectKey, credentialReplaced: Boolean(apiToken) },
+  }, request);
+  const row = (await connectionOf(env, projectId))!;
+  return response({
+    connection: connectionView(env, row),
+    ...(webhookSecret ? { webhookSecret } : {}),
+  }, existing ? 200 : 201);
+}
+
+async function deleteConnection({ env, principal, request }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!mayManage(principal)) return response({ error: "Jira is disconnected by a project manager in the dashboard" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return forbidden();
+  const row = await connectionOf(env, projectId);
+  if (!row) return notConnected();
+  await env.DB.batch([
+    env.DB.prepare("DELETE FROM project_jira_connections WHERE project_id = ?").bind(projectId),
+    // Tickets stay in Jira; reconnecting finds them again by their case label.
+    env.DB.prepare("DELETE FROM jira_issue_links WHERE project_id = ?").bind(projectId),
+    env.DB.prepare("DELETE FROM jira_plan_issues WHERE project_id = ?").bind(projectId),
+  ]);
+  await auditProject(env, principal, projectId, { action: "jira.disconnected", targetType: "jira_connection", targetId: row.id, data: { siteUrl: row.site_url, projectKey: row.jira_project_key } }, request);
+  return response({ deleted: true });
+}
+
+async function rotateWebhookSecret({ env, principal, request }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!mayManage(principal)) return forbidden();
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return forbidden();
+  if (!jiraConfigured(env)) return unconfigured();
+  const row = await connectionOf(env, projectId);
+  if (!row) return notConnected();
+  const secret = randomToken(24);
+  const sealed = await sealField(env, projectId, row.id, "webhook", secret);
+  await env.DB.prepare("UPDATE project_jira_connections SET webhook_secret_ciphertext = ?, webhook_secret_iv = ?, webhook_key_version = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?")
+    .bind(sealed.ciphertext, sealed.iv, sealed.keyVersion, row.id).run();
+  await auditProject(env, principal, projectId, { action: "jira.webhook_secret_rotated", targetType: "jira_connection", targetId: row.id }, request);
+  return response({ webhookUrl: webhookUrl(env, row.id), webhookSecret: secret });
+}
+
+async function writableConnection(context: AuthedRouteContext, projectId: string): Promise<ConnectionRow | Response> {
+  const { env, principal } = context;
+  if (principal.runner || !(await memberOfProject(env, principal, projectId, "project.write"))) return forbidden();
+  if (!jiraConfigured(env)) return unconfigured();
+  const row = await connectionOf(env, projectId);
+  if (!row) return notConnected();
+  if (!row.enabled) return response({ error: "The Jira connection is paused" }, 409);
+  return row;
+}
+
+async function postPlan(context: AuthedRouteContext, projectId: string): Promise<Response> {
+  const row = await writableConnection(context, projectId);
+  if (row instanceof Response) return row;
+  try {
+    const result = await proposePlan(context.env, context.principal, row);
+    if ("error" in result) return response({ error: result.error }, result.status);
+    if (result.status === 201) {
+      await auditProject(context.env, context.principal, projectId, {
+        action: "jira.plan_proposed", targetType: "jira_issue", targetId: result.planIssue.key, data: { proposals: result.planIssue.proposalIds.length },
+      }, context.request);
+    }
+    return response({ planIssue: result.planIssue }, result.status);
+  } catch (error) {
+    return response({ error: jiraProblem(error), code: "jira_unreachable" }, 502);
+  }
+}
+
+async function postTickets(context: AuthedRouteContext, projectId: string): Promise<Response> {
+  const row = await writableConnection(context, projectId);
+  if (row instanceof Response) return row;
+  const body = await requestJson(context.request);
+  try {
+    const result = await syncTickets(context.env, projectId, { includeExisting: body?.includeExisting === true });
+    if (result.created.length || result.linked.length || result.updated.length || result.retired.length) {
+      await auditProject(context.env, context.principal, projectId, {
+        action: "jira.tickets_synced", targetType: "jira_connection", targetId: row.id,
+        data: { created: result.created.length, linked: result.linked.length, updated: result.updated.length, retired: result.retired.length },
+      }, context.request);
+    }
+    return response(result);
+  } catch (error) {
+    return response({ error: jiraProblem(error), code: "jira_unreachable" }, 502);
+  }
+}
+
+async function listLinks({ env, principal }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (principal.runner || !(await memberOfProject(env, principal, projectId))) return forbidden();
+  const row = await connectionOf(env, projectId);
+  const links = await env.DB.prepare(`
+    SELECT case_set_id AS caseSetId, case_id AS caseId, case_revision AS caseRevision, case_title AS caseTitle,
+           jira_issue_key AS issueKey, last_result AS lastResult, last_run_id AS lastRunId, updated_at AS updatedAt
+    FROM jira_issue_links WHERE project_id = ? AND jira_issue_key IS NOT NULL
+    ORDER BY case_set_id, case_id
+  `).bind(projectId).all<Record<string, unknown> & { issueKey: string }>();
+  const plans = await env.DB.prepare(`
+    SELECT id, jira_issue_key AS issueKey, status, created_at AS createdAt FROM jira_plan_issues WHERE project_id = ? ORDER BY created_at DESC LIMIT 10
+  `).bind(projectId).all<Record<string, unknown> & { issueKey: string }>();
+  return response({
+    connected: Boolean(row),
+    projectKey: row?.jira_project_key ?? null,
+    links: links.results.map((link) => ({ ...link, issueUrl: row ? issueUrl(row, link.issueKey) : null })),
+    planIssues: plans.results.map((plan) => ({ ...plan, issueUrl: row ? issueUrl(row, plan.issueKey) : null })),
+  });
+}
+
+registerRoutes(async (context) => {
+  const { url, request } = context;
+  let params = matchPath(url.pathname, "/api/projects/:projectId/jira");
+  if (params && request.method === "GET") return getConnection(context, params.projectId);
+  if (params && request.method === "PUT") return saveConnection(context, params.projectId);
+  if (params && request.method === "DELETE") return deleteConnection(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/jira/rotate-webhook-secret");
+  if (params && request.method === "POST") return rotateWebhookSecret(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/jira/plan");
+  if (params && request.method === "POST") return postPlan(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/jira/tickets");
+  if (params && request.method === "POST") return postTickets(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/jira/links");
+  if (params && request.method === "GET") return listLinks(context, params.projectId);
+  return null;
+});
+
+// --- Webhook -----------------------------------------------------------------------------------
+
+async function hmacHex(secret: string, body: string): Promise<string> {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(body));
+  return [...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Whether a delivery carries this connection's secret, in any of the accepted forms. */
+export async function webhookAuthentic(request: Request, url: URL, secret: string, body: string): Promise<boolean> {
+  const signature = request.headers.get("x-hub-signature") ?? "";
+  if (signature.startsWith("sha256=")) return constantTimeEqual(signature.slice(7).toLowerCase(), await hmacHex(secret, body));
+  const header = request.headers.get("x-bugmole-webhook-secret") ?? "";
+  if (header) return constantTimeEqual(header, secret);
+  const token = url.searchParams.get("token") ?? "";
+  return Boolean(token) && constantTimeEqual(token, secret);
+}
+
+type CommentEvent = { issueKey: string; projectKey: string | null; commentId: string; authorId: string | null; body: unknown };
+
+export function parseCommentEvent(payload: Record<string, unknown> | null): CommentEvent | null {
+  if (!payload || payload.webhookEvent !== "comment_created") return null;
+  const issue = payload.issue as { key?: unknown; fields?: { project?: { key?: unknown } } } | undefined;
+  const comment = payload.comment as { id?: unknown; body?: unknown; author?: { accountId?: unknown } } | undefined;
+  const issueKey = typeof issue?.key === "string" ? issue.key : "";
+  if (!/^[A-Z][A-Z0-9_]{1,9}-\d{1,10}$/.test(issueKey) || !comment) return null;
+  const commentId = typeof comment.id === "string" || typeof comment.id === "number" ? String(comment.id) : "";
+  if (!/^\d{1,20}$/.test(commentId)) return null;
+  return {
+    issueKey,
+    projectKey: typeof issue?.fields?.project?.key === "string" ? issue.fields.project.key : null,
+    commentId,
+    authorId: typeof comment.author?.accountId === "string" ? comment.author.accountId : null,
+    body: comment.body,
+  };
+}
+
+/** Whether a comment asks Bugmole for a retest: the keyword, or an @mention of Bugmole's own Jira account. */
+export function asksForRetest(row: Pick<ConnectionRow, "mention_keyword" | "account_id">, body: unknown): boolean {
+  if (row.account_id && mentionedAccountIds(body).includes(row.account_id)) return true;
+  return commentText(body).toLowerCase().includes(row.mention_keyword.toLowerCase());
+}
+
+async function webhookAudit(env: Env, row: ConnectionRow, request: Request, action: string, data: Record<string, unknown>, throttleSeconds = 0): Promise<void> {
+  const project = await env.DB.prepare("SELECT workspace_id AS workspaceId FROM projects WHERE id = ?").bind(row.project_id).first<{ workspaceId: string | null }>();
+  if (!project?.workspaceId) return;
+  if (throttleSeconds > 0) {
+    // Anyone who knows a connection id can send bad deliveries; one row per
+    // window records the attempt without letting them flood the audit log.
+    const recent = await env.DB.prepare(`
+      SELECT 1 AS found FROM audit_log
+      WHERE workspace_id = ? AND target_id = ? AND action = ?
+        AND created_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now', ?)
+      LIMIT 1
+    `).bind(project.workspaceId, row.id, action, `-${throttleSeconds} seconds`).first<{ found: number }>();
+    if (recent) return;
+  }
+  await recordAudit(env, { type: "webhook", id: `jira:${row.id}` }, {
+    workspaceId: project.workspaceId, projectId: row.project_id, action, targetType: "jira_connection", targetId: row.id, data,
+  }, request);
+}
+
+registerPublicRoutes(async ({ request, env, url, ctx }) => {
+  if (url.pathname !== "/api/jira/webhook" || request.method !== "POST") return null;
+  const row = await connectionById(env, url.searchParams.get("connection") ?? "");
+  if (!row || !row.enabled) return response({ error: "Unknown connection" }, 404);
+  const raw = await request.text();
+  if (raw.length > WEBHOOK_BODY_MAX) return response({ error: "Payload too large" }, 413);
+  let secret: string;
+  try {
+    secret = await openField(env, row, "webhook");
+  } catch {
+    return response({ error: "This connection can't verify webhooks; rotate its secret" }, 503);
+  }
+  if (!(await webhookAuthentic(request, url, secret, raw))) {
+    await webhookAudit(env, row, request, "jira.webhook_rejected", { reason: "bad_secret" }, 60);
+    return response({ error: "Invalid webhook secret" }, 401);
+  }
+  let payload: Record<string, unknown> | null = null;
+  try {
+    payload = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    payload = null;
+  }
+  const event = parseCommentEvent(payload);
+  if (!event) return response({ ignored: "not_a_new_comment" });
+  if (event.projectKey && event.projectKey !== row.jira_project_key) return response({ ignored: "other_project" });
+  if (!event.projectKey && !event.issueKey.startsWith(`${row.jira_project_key}-`)) return response({ ignored: "other_project" });
+  if (event.authorId && event.authorId === row.account_id) return response({ ignored: "own_comment" });
+  if (!asksForRetest(row, event.body)) return response({ ignored: "no_mention" });
+
+  const outcome = await requestRetest(env, row, event.issueKey, event.commentId);
+  await webhookAudit(env, row, request, "jira.retest_requested", {
+    issueKey: event.issueKey, commentId: event.commentId, requestedBy: event.authorId, queued: outcome.queued,
+    ...(outcome.queued ? { runId: outcome.runId, caseSetId: outcome.caseSetId, caseId: outcome.caseId } : { reason: outcome.reason }),
+  });
+  if (outcome.queued) {
+    await enqueue(env, "jira.comment", {
+      projectId: row.project_id, issueKey: event.issueKey,
+      text: `Bugmole is retesting ${outcome.caseSetId}/${outcome.caseId} (run ${outcome.runId}). The result will be posted here.`,
+    }, { dedupeKey: `jira-retest-ack:${outcome.runId}` });
+    drainSoon(env, ctx);
+    return response({ queued: true, runId: outcome.runId }, 202);
+  }
+  if (outcome.reason !== "not_bugmole_ticket") {
+    const text = outcome.reason === "no_plan"
+      ? "Bugmole couldn't find a published plan for this test's journey, so it can't retest it yet. Publish the plan in Bugmole and mention Bugmole again."
+      : `Bugmole couldn't start a retest: ${outcome.message ?? "the run was refused"}.`;
+    await enqueue(env, "jira.comment", { projectId: row.project_id, issueKey: event.issueKey, text }, { dedupeKey: `jira-retest-fail:${row.id}:${event.issueKey}:${event.commentId}` });
+    drainSoon(env, ctx);
+  }
+  return response({ queued: false, reason: outcome.reason });
+});
+
+// --- Outbox and hooks --------------------------------------------------------------------------
+
+async function withJira(env: Env, projectId: string, work: () => Promise<unknown>): Promise<void> {
+  try {
+    await work();
+    await env.DB.prepare("UPDATE project_jira_connections SET last_error = NULL WHERE project_id = ? AND last_error IS NOT NULL").bind(projectId).run();
+  } catch (error) {
+    if (error instanceof ResultsNotReady) throw error;
+    const message = error instanceof JiraApiError ? jiraProblem(error) : error instanceof Error ? error.message.slice(0, 300) : "Jira call failed";
+    await env.DB.prepare("UPDATE project_jira_connections SET last_error = ? WHERE project_id = ?").bind(message, projectId).run();
+    // A revoked token or a removed project won't start working on a retry.
+    if (isPermanentJiraError(error)) throw new PermanentDeliveryError(message);
+    throw error;
+  }
+}
+
+registerOutboxHandler("jira.tickets.sync", async (env, payload: { projectId: string }) => {
+  await withJira(env, payload.projectId, () => syncTickets(env, payload.projectId));
+});
+
+registerOutboxHandler("jira.plan.refresh", async (env, payload: { projectId: string; planIssueId: string }) => {
+  await withJira(env, payload.projectId, () => refreshPlanIssue(env, payload.planIssueId));
+});
+
+registerOutboxHandler("jira.run.report", async (env, payload: { projectId: string; runId: string }) => {
+  await withJira(env, payload.projectId, () => reportRun(env, payload.runId));
+});
+
+registerOutboxHandler("jira.comment", async (env, payload: { projectId: string; issueKey: string; text: string }) => {
+  const row = await connectionOf(env, payload.projectId);
+  if (!row?.enabled) return;
+  await withJira(env, payload.projectId, async () => (await clientFor(env, row)).comment(payload.issueKey, adf.doc(adf.paragraph(adf.text(payload.text)))));
+});
+
+proposalDecidedHooks.push(async (env, event) => {
+  const row = await env.DB.prepare("SELECT enabled FROM project_jira_connections WHERE project_id = ?").bind(event.projectId).first<{ enabled: number }>();
+  if (!row?.enabled) return;
+  if (event.status === "accepted") {
+    await enqueue(env, "jira.tickets.sync", { projectId: event.projectId }, { dedupeKey: `jira-sync:${event.proposalId}:${event.applied ? "applied" : "accepted"}` });
+  }
+  const plans = await env.DB.prepare("SELECT id, proposal_ids_json AS ids FROM jira_plan_issues WHERE project_id = ? AND status = 'proposed'")
+    .bind(event.projectId).all<{ id: string; ids: string }>();
+  for (const plan of plans.results) {
+    if (!(JSON.parse(plan.ids) as string[]).includes(event.proposalId)) continue;
+    await enqueue(env, "jira.plan.refresh", { projectId: event.projectId, planIssueId: plan.id }, { dedupeKey: `jira-plan:${plan.id}:${event.proposalId}:${event.status}` });
+  }
+});
+
+runChangedHooks.push(async (env, event) => {
+  if (!event.terminal) return;
+  const row = await env.DB.prepare(`
+    SELECT 1 AS linked FROM project_jira_connections c
+    WHERE c.project_id = ? AND c.enabled = 1
+      AND EXISTS (SELECT 1 FROM jira_issue_links l WHERE l.project_id = c.project_id AND l.jira_issue_key IS NOT NULL)
+  `).bind(event.projectId).first<{ linked: number }>();
+  if (!row) return;
+  await enqueue(env, "jira.run.report", { projectId: event.projectId, runId: event.runId }, { dedupeKey: `jira-report:${event.runId}` });
+});