@desplega.ai/agent-swarm 1.70.0 → 1.71.0

package/src/http/trackers/jira.ts

@@ -0,0 +1,331 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getOAuthTokens } from "../../be/db-queries/oauth";
+import { isJiraEnabled } from "../../jira/app";
+import { getJiraMetadata } from "../../jira/metadata";
+import { getJiraAuthorizationUrl, handleJiraCallback } from "../../jira/oauth";
+import { handleJiraWebhook } from "../../jira/webhook";
+import { deleteJiraWebhook, registerJiraWebhook } from "../../jira/webhook-lifecycle";
+import { route } from "../route-def";
+import { parseQueryParams } from "../utils";
+
+const MANUAL_WEBHOOK_INSTRUCTIONS =
+  "See docs-site/.../guides/jira-integration.mdx for manual webhook registration steps.";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const jiraAuthorize = route({
+  method: "get",
+  path: "/api/trackers/jira/authorize",
+  pattern: ["api", "trackers", "jira", "authorize"],
+  summary: "Redirect to Atlassian OAuth consent screen",
+  tags: ["Trackers"],
+  auth: { apiKey: false },
+  responses: {
+    302: { description: "Redirect to Atlassian OAuth" },
+    500: { description: "Failed to generate authorization URL" },
+    503: { description: "Jira integration not configured" },
+  },
+});
+
+const jiraCallback = route({
+  method: "get",
+  path: "/api/trackers/jira/callback",
+  pattern: ["api", "trackers", "jira", "callback"],
+  summary: "Handle Jira OAuth callback (resolves cloudId via accessible-resources)",
+  tags: ["Trackers"],
+  auth: { apiKey: false },
+  query: z.object({
+    code: z.string(),
+    state: z.string(),
+  }),
+  responses: {
+    200: { description: "OAuth complete" },
+    400: { description: "Invalid state or code" },
+    500: { description: "Token exchange or accessible-resources fetch failed" },
+  },
+});
+
+const jiraStatus = route({
+  method: "get",
+  path: "/api/trackers/jira/status",
+  pattern: ["api", "trackers", "jira", "status"],
+  summary:
+    "Jira connection status, cloudId/siteUrl, token expiry, expected webhook URL, scope/token-config flags",
+  tags: ["Trackers"],
+  responses: {
+    200: { description: "Connection status" },
+    503: { description: "Jira integration not configured" },
+  },
+});
+
+const jiraWebhook = route({
+  method: "post",
+  path: "/api/trackers/jira/webhook/{token}",
+  pattern: ["api", "trackers", "jira", "webhook", null],
+  summary:
+    "Receive Jira webhook events (URL-token authenticated). Phase 2 stub — Phase 3 fills in dispatch.",
+  tags: ["Trackers"],
+  auth: { apiKey: false },
+  params: z.object({ token: z.string() }),
+  responses: {
+    200: { description: "Event accepted" },
+    401: { description: "Invalid URL token" },
+    503: { description: "Jira webhook handler not configured" },
+  },
+});
+
+// Admin: register a new dynamic webhook with Atlassian. apiKey is required
+// (route-factory default). The registered URL embeds JIRA_WEBHOOK_TOKEN so
+// inbound deliveries can be authenticated.
+const jiraWebhookRegister = route({
+  method: "post",
+  path: "/api/trackers/jira/webhook-register",
+  pattern: ["api", "trackers", "jira", "webhook-register"],
+  summary: "Register a Jira dynamic webhook (admin only)",
+  tags: ["Trackers"],
+  body: z.object({
+    jqlFilter: z.string().min(1),
+  }),
+  responses: {
+    200: { description: "Webhook registered" },
+    400: { description: "Invalid jqlFilter" },
+    503: { description: "Jira not connected or JIRA_WEBHOOK_TOKEN missing" },
+  },
+});
+
+// Admin: delete a dynamic webhook from Atlassian and remove from local
+// metadata. apiKey is required (route-factory default).
+const jiraWebhookDelete = route({
+  method: "delete",
+  path: "/api/trackers/jira/webhook/{id}",
+  pattern: ["api", "trackers", "jira", "webhook", null],
+  summary: "Delete a Jira dynamic webhook (admin only)",
+  tags: ["Trackers"],
+  params: z.object({
+    id: z.coerce.number().int().positive(),
+  }),
+  responses: {
+    200: { description: "Webhook deleted" },
+    400: { description: "Invalid webhook id" },
+    503: { description: "Jira not connected" },
+  },
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getWebhookBaseUrl(): string {
+  return process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+}
+
+function getWebhookUrl(): string {
+  const token = process.env.JIRA_WEBHOOK_TOKEN ?? "<unset>";
+  return `${getWebhookBaseUrl()}/api/trackers/jira/webhook/${token}`;
+}
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleJiraTracker(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+): Promise<boolean> {
+  // GET /api/trackers/jira/authorize — redirect to Atlassian OAuth consent
+  if (jiraAuthorize.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    try {
+      const url = await getJiraAuthorizationUrl();
+      if (!url) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Failed to generate authorization URL" }));
+        return true;
+      }
+
+      res.writeHead(302, { Location: url });
+      res.end();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] Failed to generate authorization URL:", message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Failed to generate authorization URL" }));
+    }
+    return true;
+  }
+
+  // GET /api/trackers/jira/callback — handle OAuth callback from Atlassian
+  if (jiraCallback.match(req.method, pathSegments)) {
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraCallback.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true; // parse() already sent 400
+
+    const { code, state } = parsed.query;
+
+    try {
+      await handleJiraCallback(code, state);
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(`<!DOCTYPE html>
+<html>
+<head><title>Jira Connected</title></head>
+<body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0;">
+  <div style="text-align: center;">
+    <h1>Jira Connected</h1>
+    <p>OAuth authorization complete. You can close this window.</p>
+  </div>
+</body>
+</html>`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] OAuth callback failed:", message);
+
+      if (message.includes("Invalid or expired OAuth state")) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid or expired OAuth state" }));
+      } else {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "OAuth callback failed", details: message }));
+      }
+    }
+    return true;
+  }
+
+  // GET /api/trackers/jira/status — connection status (works even when not connected)
+  if (jiraStatus.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    const tokens = getOAuthTokens("jira");
+    const meta = getJiraMetadata();
+    const scope = tokens?.scope ?? null;
+    // Atlassian returns scopes space-separated in the token response.
+    const scopeList = scope ? scope.split(/[\s,]+/).filter(Boolean) : [];
+
+    const hasManageWebhookScope = scopeList.includes("manage:jira-webhook");
+
+    const status: Record<string, unknown> = {
+      provider: "jira",
+      connected: !!tokens,
+      cloudId: meta.cloudId ?? null,
+      siteUrl: meta.siteUrl ?? null,
+      tokenExpiresAt: tokens?.expiresAt ?? null,
+      scope,
+      hasManageWebhookScope,
+      webhookTokenConfigured: Boolean(process.env.JIRA_WEBHOOK_TOKEN),
+      webhookUrl: getWebhookUrl(),
+      webhookIds: meta.webhookIds ?? [],
+    };
+
+    // Phase 5: surface manual-webhook instructions when the OAuth grant
+    // doesn't include `manage:jira-webhook` (admin must register webhooks
+    // manually in the Atlassian UI).
+    if (!hasManageWebhookScope) {
+      status.manualWebhookInstructions = MANUAL_WEBHOOK_INSTRUCTIONS;
+    }
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(status));
+    return true;
+  }
+
+  // POST /api/trackers/jira/webhook/:token — receive Jira dynamic-webhook events.
+  //
+  // Atlassian does not HMAC-sign OAuth 3LO dynamic webhooks (errata I8); we
+  // authenticate via a URL-path token compared with `JIRA_WEBHOOK_TOKEN`.
+  if (jiraWebhook.match(req.method, pathSegments)) {
+    // Path token sits at index 4 of the matched segments
+    // (["api","trackers","jira","webhook", null]). Use the route parser so
+    // we go through the same Zod path-param plumbing the rest of the route
+    // file uses.
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraWebhook.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true; // 400 already sent
+
+    // Read raw body using the same chunk-assembly pattern as
+    // src/http/trackers/linear.ts:166-171 — we don't trust the framework to
+    // hand us a parsed body for webhook routes.
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const rawBody = Buffer.concat(chunks).toString();
+
+    const result = await handleJiraWebhook(parsed.params.token, rawBody);
+
+    // 401 with empty body — no info leak about valid-vs-missing token.
+    if (result.status === 401) {
+      res.writeHead(401);
+      res.end();
+      return true;
+    }
+
+    res.writeHead(result.status, { "Content-Type": "application/json" });
+    res.end(typeof result.body === "string" ? result.body : JSON.stringify(result.body));
+    return true;
+  }
+
+  // POST /api/trackers/jira/webhook-register — admin: register a dynamic webhook.
+  if (jiraWebhookRegister.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+    if (!process.env.JIRA_WEBHOOK_TOKEN) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "JIRA_WEBHOOK_TOKEN is not set" }));
+      return true;
+    }
+
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraWebhookRegister.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    try {
+      const result = await registerJiraWebhook(parsed.body.jqlFilter);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] Webhook register failed:", message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Webhook registration failed", details: message }));
+    }
+    return true;
+  }
+
+  // DELETE /api/trackers/jira/webhook/:id — admin: delete a dynamic webhook.
+  // Note: this pattern overlaps the POST /webhook/:token path; the matcher
+  // disambiguates by HTTP method.
+  if (jiraWebhookDelete.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraWebhookDelete.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    try {
+      await deleteJiraWebhook(parsed.params.id);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ deleted: true, webhookId: parsed.params.id }));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[Jira] Webhook delete failed (id=${parsed.params.id}):`, message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Webhook delete failed", details: message }));
+    }
+    return true;
+  }
+
+  return false;
+}

package/src/jira/adf.ts

@@ -0,0 +1,132 @@
+/**
+ * Atlassian Document Format (ADF) walker.
+ *
+ * Jira REST v3 returns rich-text fields (issue descriptions, comment bodies)
+ * as ADF JSON trees. We need plaintext for prompt rendering and structured
+ * mention extraction for bot-mention detection on inbound webhooks.
+ *
+ * Reference: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
+ *
+ * Supported node types: paragraph, heading, bulletList, orderedList, listItem,
+ * text, mention, hardBreak, codeBlock, blockquote. Unknown types descend into
+ * `content` if present, else are skipped silently. In non-prod environments a
+ * debug line is emitted so unhandled cases surface during dev.
+ */
+
+type AdfNode = {
+  type?: string;
+  text?: string;
+  content?: unknown[];
+  attrs?: Record<string, unknown>;
+};
+
+function isNode(value: unknown): value is AdfNode {
+  return !!value && typeof value === "object";
+}
+
+function asNodeArray(value: unknown): AdfNode[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter(isNode);
+}
+
+/**
+ * Recursively concatenate text from an ADF tree. Mentions are inlined as
+ * `@<displayName>` (or `@<accountId>` if no displayName is present).
+ *
+ * Block-level nodes insert a trailing newline so consecutive paragraphs render
+ * as separate lines. Hard breaks and list items also produce newlines.
+ */
+export function extractText(adf: unknown): string {
+  if (!isNode(adf)) return "";
+
+  const out: string[] = [];
+
+  const visit = (node: AdfNode): void => {
+    const type = typeof node.type === "string" ? node.type : "";
+
+    switch (type) {
+      case "text": {
+        if (typeof node.text === "string") out.push(node.text);
+        return;
+      }
+      case "mention": {
+        const attrs = node.attrs ?? {};
+        const text = typeof attrs.text === "string" ? attrs.text : null;
+        const id = typeof attrs.id === "string" ? attrs.id : null;
+        const display = text ?? id ?? "";
+        // Atlassian mention `text` already starts with "@" sometimes; normalize
+        // to a single leading "@".
+        out.push(display.startsWith("@") ? display : `@${display}`);
+        return;
+      }
+      case "hardBreak": {
+        out.push("\n");
+        return;
+      }
+      case "paragraph":
+      case "heading":
+      case "blockquote":
+      case "codeBlock": {
+        for (const child of asNodeArray(node.content)) visit(child);
+        out.push("\n");
+        return;
+      }
+      case "bulletList":
+      case "orderedList": {
+        for (const child of asNodeArray(node.content)) visit(child);
+        return;
+      }
+      case "listItem": {
+        out.push("- ");
+        for (const child of asNodeArray(node.content)) visit(child);
+        // Block children inside a listItem already trail a newline, so we don't
+        // double-add. But if the listItem only contained inline content, ensure
+        // we end on a newline.
+        if (out.length > 0 && !out[out.length - 1]?.endsWith("\n")) {
+          out.push("\n");
+        }
+        return;
+      }
+      case "doc": {
+        for (const child of asNodeArray(node.content)) visit(child);
+        return;
+      }
+      default: {
+        // Unknown node — descend into content if present.
+        if (process.env.NODE_ENV !== "production" && type) {
+          console.log(`[jira.adf] unknown node type: ${type}`);
+        }
+        for (const child of asNodeArray(node.content)) visit(child);
+        return;
+      }
+    }
+  };
+
+  visit(adf);
+
+  // Collapse trailing whitespace, preserve internal newlines.
+  return out.join("").replace(/\n+$/g, "");
+}
+
+/**
+ * Collect Atlassian `accountId` values from every `mention` node in the tree.
+ * Returns an empty array when no mentions exist or the input is malformed.
+ */
+export function extractMentions(adf: unknown): string[] {
+  if (!isNode(adf)) return [];
+
+  const ids: string[] = [];
+
+  const visit = (node: AdfNode): void => {
+    if (node.type === "mention") {
+      const id = node.attrs?.id;
+      if (typeof id === "string" && id.length > 0) ids.push(id);
+      return;
+    }
+    for (const child of asNodeArray(node.content)) visit(child);
+  };
+
+  visit(adf);
+
+  return ids;
+}

package/src/jira/app.ts

@@ -0,0 +1,65 @@
+import { upsertOAuthApp } from "../be/db-queries/oauth";
+import { initJiraOutboundSync, teardownJiraOutboundSync } from "./outbound";
+// Side-effect import: registers all Jira event templates in the in-memory
+// registry at module load time (mirrors `src/linear/templates.ts`).
+import "./templates";
+import { resetBotAccountIdCache } from "./sync";
+import { startJiraWebhookKeepalive, stopJiraWebhookKeepalive } from "./webhook-lifecycle";
+
+let initialized = false;
+
+export function isJiraEnabled(): boolean {
+  const disabled = process.env.JIRA_DISABLE;
+  if (disabled === "true" || disabled === "1") return false;
+  const enabled = process.env.JIRA_ENABLED;
+  if (enabled === "false" || enabled === "0") return false;
+  return !!process.env.JIRA_CLIENT_ID;
+}
+
+export function resetJira(): void {
+  // Phase 3: drop the cached bot accountId so a reconnect as a different
+  // Atlassian user re-resolves identity on the next inbound webhook.
+  resetBotAccountIdCache();
+  teardownJiraOutboundSync();
+  stopJiraWebhookKeepalive();
+  initialized = false;
+}
+
+export function initJira(): boolean {
+  if (initialized) return isJiraEnabled();
+  initialized = true;
+
+  if (!isJiraEnabled()) {
+    console.log("[Jira] Integration disabled or JIRA_CLIENT_ID not set");
+    return false;
+  }
+
+  const clientId = process.env.JIRA_CLIENT_ID!;
+  const clientSecret = process.env.JIRA_CLIENT_SECRET ?? "";
+  const redirectUri =
+    process.env.JIRA_REDIRECT_URI ??
+    `http://localhost:${process.env.PORT || "3013"}/api/trackers/jira/callback`;
+
+  upsertOAuthApp("jira", {
+    clientId,
+    clientSecret,
+    authorizeUrl: "https://auth.atlassian.com/authorize",
+    tokenUrl: "https://auth.atlassian.com/oauth/token",
+    redirectUri,
+    // Atlassian uses space-separated scopes (NOT comma-separated like Linear).
+    // We persist them as-stored; the OAuth wrapper splits on "," so we keep
+    // commas here and the wrapper.ts join(",") will recombine — see oauth.ts
+    // where we override scopes from the comma-stored value back to spaces in
+    // the authorize URL via the standard `scopes` array path.
+    scopes: "read:jira-work,write:jira-work,manage:jira-webhook,offline_access,read:me",
+    // Intentionally omit metadata: cloudId/siteUrl/webhookIds are written by
+    // the OAuth callback + webhook-register flows. upsertOAuthApp preserves
+    // existing metadata on UPDATE when not passed.
+  });
+
+  initJiraOutboundSync();
+  startJiraWebhookKeepalive();
+
+  console.log("[Jira] Integration initialized");
+  return true;
+}

package/src/jira/client.ts

@@ -0,0 +1,82 @@
+import { getOAuthTokens } from "../be/db-queries/oauth";
+import { ensureToken } from "../oauth/ensure-token";
+import { getJiraMetadata } from "./metadata";
+
+/**
+ * Resolve a fresh Jira access token (refreshes if expiring soon).
+ *
+ * Throws if no tokens are stored — callers should treat this as "not yet
+ * connected" rather than a programmer error.
+ */
+export async function getJiraAccessToken(): Promise<string> {
+  await ensureToken("jira");
+  const tokens = getOAuthTokens("jira");
+  if (!tokens) {
+    throw new Error("Jira not connected — no OAuth tokens stored");
+  }
+  return tokens.accessToken;
+}
+
+/**
+ * Resolve the current workspace `cloudId` from `oauth_apps.metadata`.
+ *
+ * Throws if the OAuth callback hasn't completed yet (no cloudId persisted).
+ */
+export function getJiraCloudId(): string {
+  const meta = getJiraMetadata();
+  if (!meta.cloudId) {
+    throw new Error("Jira cloudId not resolved — complete OAuth before calling Jira REST API");
+  }
+  return meta.cloudId;
+}
+
+/**
+ * Typed fetch wrapper for the Atlassian Jira REST API.
+ *
+ * - Prepends `https://api.atlassian.com/ex/jira/{cloudId}` to `path`.
+ * - Sets `Authorization: Bearer <token>` and `Accept: application/json`.
+ * - Sets `Content-Type: application/json` when a body is provided.
+ * - On 401: refreshes the token (forced via `ensureToken("jira", 0)`) and
+ *   retries once.
+ * - On 429: respects `Retry-After` (in seconds) with a single retry.
+ *
+ * Returns the raw `Response` — callers handle `response.json()`/`response.text()`
+ * themselves so we don't impose a parse contract.
+ */
+export async function jiraFetch(path: string, init?: RequestInit): Promise<Response> {
+  if (!path.startsWith("/")) {
+    throw new Error(`jiraFetch path must start with '/' — got: ${path}`);
+  }
+
+  const send = async (token: string): Promise<Response> => {
+    const cloudId = getJiraCloudId();
+    const url = `https://api.atlassian.com/ex/jira/${cloudId}${path}`;
+    const headers = new Headers(init?.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    if (!headers.has("Accept")) headers.set("Accept", "application/json");
+    if (init?.body && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    return fetch(url, { ...init, headers });
+  };
+
+  let token = await getJiraAccessToken();
+  let response = await send(token);
+
+  if (response.status === 401) {
+    // Force refresh — bufferMs=0 means "always refresh if any expiry is set"
+    await ensureToken("jira", 0);
+    token = await getJiraAccessToken();
+    response = await send(token);
+  }
+
+  if (response.status === 429) {
+    const retryAfterRaw = response.headers.get("Retry-After");
+    const retryAfter = retryAfterRaw ? Number.parseInt(retryAfterRaw, 10) : NaN;
+    const delayMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 1000;
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    response = await send(token);
+  }
+
+  return response;
+}

package/src/jira/index.ts

@@ -0,0 +1,24 @@
+export { extractMentions, extractText } from "./adf";
+export { initJira, isJiraEnabled, resetJira } from "./app";
+export {
+  handleCommentEvent,
+  handleIssueDeleteEvent,
+  handleIssueEvent,
+  resetBotAccountIdCache,
+  resolveBotAccountId,
+} from "./sync";
+export {
+  handleJiraWebhook,
+  isDuplicateDelivery,
+  markDelivery,
+  synthesizeDeliveryId,
+  verifyJiraWebhookToken,
+} from "./webhook";
+export type { RegisterJiraWebhookResult } from "./webhook-lifecycle";
+export {
+  deleteJiraWebhook,
+  refreshJiraWebhooks,
+  registerJiraWebhook,
+  startJiraWebhookKeepalive,
+  stopJiraWebhookKeepalive,
+} from "./webhook-lifecycle";