@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/jira/jira-client.js

@@ -0,0 +1,313 @@
+/**
+ * JIRA REST API client.
+ *
+ * Supports both JIRA Cloud (Basic auth: email + API token) and
+ * JIRA Server/Data Center (Bearer token / PAT).
+ *
+ * Uses only native fetch — no external HTTP library needed.
+ */
+export class JiraClient {
+    baseUrl;
+    authHeader;
+    isCloud;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.isCloud = this.baseUrl.includes(".atlassian.net");
+        if (this.isCloud && config.email) {
+            // Cloud: Basic auth with email:apiToken
+            const creds = Buffer.from(`${config.email}:${config.apiToken}`).toString("base64");
+            this.authHeader = `Basic ${creds}`;
+        }
+        else {
+            // Server/Data Center: Bearer PAT
+            this.authHeader = `Bearer ${config.apiToken}`;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Core HTTP
+    // ---------------------------------------------------------------------------
+    async request(path, options) {
+        const url = `${this.baseUrl}/rest/api/${this.isCloud ? "3" : "2"}${path}`;
+        const res = await fetch(url, {
+            ...options,
+            headers: {
+                "Authorization": this.authHeader,
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                ...options?.headers,
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`JIRA API ${res.status}: ${res.statusText} — ${body.slice(0, 500)}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return res.json();
+    }
+    // ---------------------------------------------------------------------------
+    // Issue operations
+    // ---------------------------------------------------------------------------
+    async getIssue(issueKey) {
+        return this.request(`/issue/${encodeURIComponent(issueKey)}?fields=summary,description,status,labels,attachment,reporter,assignee,creator,comment`);
+    }
+    async getIssueAttachments(issueKey) {
+        const issue = await this.getIssue(issueKey);
+        return issue.fields.attachment ?? [];
+    }
+    /**
+     * Download an attachment binary. The `content` URL from JIRA requires the
+     * same auth header, so we can't just fetch it unauthenticated.
+     */
+    async downloadAttachment(contentUrl) {
+        const res = await fetch(contentUrl, {
+            headers: {
+                "Authorization": this.authHeader,
+                "Accept": "*/*",
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`JIRA attachment download failed: ${res.status} ${res.statusText}`);
+        }
+        return Buffer.from(await res.arrayBuffer());
+    }
+    // ---------------------------------------------------------------------------
+    // Feedback operations
+    // ---------------------------------------------------------------------------
+    async addComment(issueKey, markdown) {
+        if (this.isCloud) {
+            // Cloud API v3 uses Atlassian Document Format
+            await this.request(`/issue/${encodeURIComponent(issueKey)}/comment`, {
+                method: "POST",
+                body: JSON.stringify({
+                    body: markdownToAdf(markdown),
+                }),
+            });
+        }
+        else {
+            // Server API v2 uses plain text/wiki markup
+            await this.request(`/issue/${encodeURIComponent(issueKey)}/comment`, {
+                method: "POST",
+                body: JSON.stringify({ body: markdown }),
+            });
+        }
+    }
+    /**
+     * Transition an issue to a target status by name.
+     * Looks up available transitions to find the matching one.
+     */
+    async transitionIssue(issueKey, targetStatusName) {
+        const res = await this.request(`/issue/${encodeURIComponent(issueKey)}/transitions`);
+        const match = res.transitions.find((t) => t.name.toLowerCase() === targetStatusName.toLowerCase() ||
+            t.to.name.toLowerCase() === targetStatusName.toLowerCase());
+        if (!match)
+            return false;
+        await this.request(`/issue/${encodeURIComponent(issueKey)}/transitions`, {
+            method: "POST",
+            body: JSON.stringify({ transition: { id: match.id } }),
+        });
+        return true;
+    }
+    /**
+     * Assign an issue to a user by account ID (Cloud) or username (Server).
+     */
+    async assignIssue(issueKey, assignee) {
+        await this.request(`/issue/${encodeURIComponent(issueKey)}/assignee`, {
+            method: "PUT",
+            body: JSON.stringify(this.isCloud ? { accountId: assignee.accountId } : { name: assignee.name }),
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Search
+    // ---------------------------------------------------------------------------
+    async searchJql(jql, maxResults = 20) {
+        // Cloud deprecated `/search` in favor of `/search/jql` (changelog CHANGE-2046).
+        // The new endpoint keeps the same `issues[]` response shape; we don't need
+        // pagination (maxResults is capped at 100) so nextPageToken is ignored.
+        // Server/DC still uses the legacy `/search` on API v2.
+        const path = this.isCloud ? "/search/jql" : "/search";
+        const res = await this.request(`${path}?jql=${encodeURIComponent(jql)}&maxResults=${maxResults}&fields=summary,description,status,labels,attachment,reporter,assignee,creator,comment`);
+        return res.issues ?? [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert simple markdown text to Atlassian Document Format (ADF).
+ * Handles paragraphs, bulletLists, tables, bold (**text**), italic (_text_),
+ * inline code (`text`), and links ([label](url)). Strips HTML comments.
+ * Good enough for status/clarification comments.
+ */
+export function markdownToAdf(markdown) {
+    // HTML comments are not an ADF node type — they leak through as literal text.
+    // Strip them here so stray markers or annotations don't surface in Jira comments.
+    const normalized = markdown.replace(/<!--[\s\S]*?-->/g, "");
+    const lines = normalized.split("\n");
+    const content = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.trim() === "") {
+            i++;
+            continue;
+        }
+        // Table: pipe-row header + separator row + pipe-row data rows.
+        // Tolerates blank lines between rows because Jira re-renders each line
+        // as its own paragraph when the table parser doesn't fire, and LLMs
+        // sometimes emit tables that way.
+        if (isTableRow(line)) {
+            let j = i + 1;
+            while (j < lines.length && lines[j].trim() === "")
+                j++;
+            if (j < lines.length && isTableSeparator(lines[j])) {
+                const headerCells = splitTableRow(line);
+                const rows = [buildTableRow(headerCells, "tableHeader")];
+                i = j + 1;
+                while (i < lines.length) {
+                    if (lines[i].trim() === "") {
+                        i++;
+                        continue;
+                    }
+                    if (!isTableRow(lines[i]))
+                        break;
+                    rows.push(buildTableRow(splitTableRow(lines[i]), "tableCell"));
+                    i++;
+                }
+                content.push({
+                    type: "table",
+                    attrs: { isNumberColumnEnabled: false, layout: "default" },
+                    content: rows,
+                });
+                continue;
+            }
+        }
+        // Bullet list: consecutive lines starting with "- "
+        if (/^\s*-\s+/.test(line)) {
+            const items = [];
+            while (i < lines.length && /^\s*-\s+/.test(lines[i])) {
+                const itemText = lines[i].replace(/^\s*-\s+/, "");
+                items.push({
+                    type: "listItem",
+                    content: [{ type: "paragraph", content: parseInlineMarkdown(itemText) }],
+                });
+                i++;
+            }
+            content.push({ type: "bulletList", content: items });
+            continue;
+        }
+        content.push({ type: "paragraph", content: parseInlineMarkdown(line) });
+        i++;
+    }
+    return { version: 1, type: "doc", content };
+}
+function isTableRow(line) {
+    const t = line.trim();
+    return t.length >= 2 && t.startsWith("|") && t.endsWith("|");
+}
+function isTableSeparator(line) {
+    if (!isTableRow(line))
+        return false;
+    const inner = line.trim().slice(1, -1);
+    return /^\s*:?-+:?\s*(\|\s*:?-+:?\s*)*$/.test(inner);
+}
+function splitTableRow(line) {
+    const inner = line.trim().slice(1, -1);
+    return inner.split("|").map((s) => s.trim());
+}
+function buildTableRow(cells, cellType) {
+    return {
+        type: "tableRow",
+        content: cells.map((text) => ({
+            type: cellType,
+            attrs: {},
+            // ADF rejects empty text nodes — substitute a single space for blank cells.
+            content: [{ type: "paragraph", content: parseInlineMarkdown(text.length > 0 ? text : " ") }],
+        })),
+    };
+}
+/**
+ * Parse inline markdown (bold + links) into ADF inline nodes.
+ * Scans left-to-right, handling **bold** and [label](url) as first-class constructs
+ * and falling through to plain text between them.
+ */
+function parseInlineMarkdown(text) {
+    const nodes = [];
+    let i = 0;
+    function pushText(raw, marks) {
+        if (!raw)
+            return;
+        const node = { type: "text", text: raw };
+        if (marks && marks.length)
+            node.marks = marks;
+        nodes.push(node);
+    }
+    while (i < text.length) {
+        // Bold: **...**
+        if (text[i] === "*" && text[i + 1] === "*") {
+            const end = text.indexOf("**", i + 2);
+            if (end !== -1) {
+                pushText(text.slice(i + 2, end), [{ type: "strong" }]);
+                i = end + 2;
+                continue;
+            }
+        }
+        // Italic: _..._ (word-boundary aware — avoids matching snake_case identifiers)
+        if (text[i] === "_") {
+            const prev = i > 0 ? text[i - 1] : "";
+            if (!prev || !/\w/.test(prev)) {
+                const end = text.indexOf("_", i + 1);
+                if (end > i + 1) {
+                    const next = text[end + 1] ?? "";
+                    const inner = text.slice(i + 1, end);
+                    if ((!next || !/\w/.test(next)) && inner.trim() === inner && inner.length > 0) {
+                        pushText(inner, [{ type: "em" }]);
+                        i = end + 1;
+                        continue;
+                    }
+                }
+            }
+        }
+        // Inline code: `...`
+        if (text[i] === "`") {
+            const end = text.indexOf("`", i + 1);
+            if (end !== -1) {
+                pushText(text.slice(i + 1, end), [{ type: "code" }]);
+                i = end + 1;
+                continue;
+            }
+        }
+        // Link: [label](url)
+        if (text[i] === "[") {
+            const labelEnd = text.indexOf("]", i + 1);
+            if (labelEnd !== -1 && text[labelEnd + 1] === "(") {
+                const urlEnd = text.indexOf(")", labelEnd + 2);
+                if (urlEnd !== -1) {
+                    const label = text.slice(i + 1, labelEnd);
+                    const url = text.slice(labelEnd + 2, urlEnd);
+                    nodes.push({
+                        type: "text",
+                        text: label,
+                        marks: [{ type: "link", attrs: { href: url } }],
+                    });
+                    i = urlEnd + 1;
+                    continue;
+                }
+            }
+        }
+        // Plain run up to the next special char
+        let next = text.length;
+        for (const marker of ["**", "[", "`", "_"]) {
+            const idx = text.indexOf(marker, i);
+            if (idx !== -1 && idx < next)
+                next = idx;
+        }
+        if (next === i)
+            next = i + 1;
+        pushText(text.slice(i, next));
+        i = next;
+    }
+    if (nodes.length === 0)
+        nodes.push({ type: "text", text });
+    return nodes;
+}

package/dist/jira/jira-poller.d.ts

@@ -0,0 +1,46 @@
+/**
+ * JIRA polling mode.
+ *
+ * Periodically queries JIRA via JQL to find tickets that need action. Used
+ * when webhooks aren't available (firewall, local dev, etc.).
+ *
+ * The poller inspects each matching issue and decides which processing mode
+ * to run based on current status + comment history:
+ *
+ *   - To Do, no prior agent comment         → review (first look)
+ *   - To Do, new reporter comment (approval) → execute
+ *   - To Do, new reporter comment (other)   → review (re-review with new info)
+ *   - In Review, new reporter comment (approval) → publish
+ *   - In Review, new reporter comment (other)    → execute (apply follow-up edits)
+ *
+ * Deduplication key = `${issueKey}:${status}:${commentCount}`, so the poller
+ * re-processes only when state meaningfully changes.
+ *
+ * Enabled via JIRA_POLL_ENABLED=1.
+ */
+import type { Logger } from "../logger.ts";
+import { type JiraProcessingMode } from "./jira-processor.ts";
+import type { JiraConfig, JiraIssue } from "./jira-types.ts";
+export type PollerRoute = {
+    mode: JiraProcessingMode;
+    reason: string;
+} | null;
+/**
+ * Decide whether an issue found by the poller needs processing right now, and
+ * in which mode. Returns null when the issue should be left alone (e.g. agent
+ * has already reviewed and is waiting for the reporter).
+ */
+export declare function routePollerIssue(issue: JiraIssue, config: JiraConfig): PollerRoute;
+export declare function startJiraPoller(options: {
+    config: JiraConfig;
+    generatedImageDir: string;
+    orchestratorPublicOrigin: string;
+    sitePublicOrigin: string;
+    logger: Logger;
+}): void;
+export declare function stopJiraPoller(): void;
+export declare function getPollerStatus(): {
+    running: boolean;
+    processedCount: number;
+    isPolling: boolean;
+};

package/dist/jira/jira-poller.js

@@ -0,0 +1,184 @@
+/**
+ * JIRA polling mode.
+ *
+ * Periodically queries JIRA via JQL to find tickets that need action. Used
+ * when webhooks aren't available (firewall, local dev, etc.).
+ *
+ * The poller inspects each matching issue and decides which processing mode
+ * to run based on current status + comment history:
+ *
+ *   - To Do, no prior agent comment         → review (first look)
+ *   - To Do, new reporter comment (approval) → execute
+ *   - To Do, new reporter comment (other)   → review (re-review with new info)
+ *   - In Review, new reporter comment (approval) → publish
+ *   - In Review, new reporter comment (other)    → execute (apply follow-up edits)
+ *
+ * Deduplication key = `${issueKey}:${status}:${commentCount}`, so the poller
+ * re-processes only when state meaningfully changes.
+ *
+ * Enabled via JIRA_POLL_ENABLED=1.
+ */
+import { JiraClient } from "./jira-client.js";
+import { processJiraTicket, adfToPlainText, isAgentAuthoredComment } from "./jira-processor.js";
+import { isApprovalComment } from "./jira-approval.js";
+// Dedup: per-issue state fingerprint we've already processed.
+const processedStates = new Map();
+let pollTimer = null;
+let clearTimer = null;
+let isPolling = false;
+function statusEquals(a, b) {
+    if (!a || !b)
+        return false;
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+function fingerprint(issue) {
+    const status = issue.fields.status?.name ?? "?";
+    const commentCount = issue.fields.comment?.comments?.length ?? 0;
+    return `${issue.key}:${status}:${commentCount}`;
+}
+/**
+ * Decide whether an issue found by the poller needs processing right now, and
+ * in which mode. Returns null when the issue should be left alone (e.g. agent
+ * has already reviewed and is waiting for the reporter).
+ */
+export function routePollerIssue(issue, config) {
+    const status = issue.fields.status?.name;
+    const comments = issue.fields.comment?.comments ?? [];
+    const agentId = config.agentAccountId;
+    const bodyOf = (c) => typeof c.body === "string" ? c.body : adfToPlainText(c.body);
+    // Classify by body shape too, not only accountId — solo Jira tenants have
+    // the same human acting as reporter + agent, and we must still see reporter
+    // replies to progress the workflow.
+    const agentComments = comments.filter((c) => isAgentAuthoredComment(bodyOf(c), c.author?.accountId, agentId));
+    const nonAgentComments = comments.filter((c) => !agentComments.includes(c));
+    const latestAgent = agentComments.at(-1);
+    const latestNonAgent = nonAgentComments.at(-1);
+    const hasNewerReporterComment = (latestNonAgent) => {
+        if (!latestNonAgent)
+            return false;
+        if (!latestAgent)
+            return true;
+        return latestNonAgent.created > latestAgent.created;
+    };
+    const latestBodyText = (c) => c ? bodyOf(c) : "";
+    // ---- Review stage ----
+    if (statusEquals(status, config.reviewStatus) || statusEquals(status, config.triggerStatus)) {
+        if (agentComments.length === 0) {
+            return { mode: "review", reason: "first review — To Do ticket with no agent comment" };
+        }
+        if (hasNewerReporterComment(latestNonAgent)) {
+            const body = latestBodyText(latestNonAgent);
+            if (isApprovalComment(body)) {
+                return { mode: "execute", reason: "approval comment on To Do" };
+            }
+            return { mode: "review", reason: "new reporter comment on To Do — re-review" };
+        }
+        return null;
+    }
+    // ---- Preview stage ----
+    if (statusEquals(status, config.previewStatus)) {
+        if (hasNewerReporterComment(latestNonAgent)) {
+            const body = latestBodyText(latestNonAgent);
+            if (isApprovalComment(body)) {
+                return { mode: "publish", reason: "approval comment on In Review" };
+            }
+            return { mode: "execute", reason: "follow-up comment on In Review — re-edit" };
+        }
+        return null;
+    }
+    return null;
+}
+export function startJiraPoller(options) {
+    const { config, generatedImageDir, orchestratorPublicOrigin, sitePublicOrigin, logger } = options;
+    if (pollTimer) {
+        logger.warn("JIRA poller already running, skipping duplicate start");
+        return;
+    }
+    const client = new JiraClient(config);
+    logger.info({ jql: config.pollJql, intervalMs: config.pollIntervalMs }, "JIRA: starting poller");
+    async function poll() {
+        if (isPolling)
+            return;
+        isPolling = true;
+        try {
+            const issues = await client.searchJql(config.pollJql, 20);
+            const actionable = [];
+            for (const issue of issues) {
+                const route = routePollerIssue(issue, config);
+                if (!route)
+                    continue;
+                const fp = fingerprint(issue);
+                if (processedStates.get(issue.key) === fp)
+                    continue;
+                actionable.push({ issue, route, fp });
+            }
+            if (actionable.length > 0) {
+                logger.info({ count: actionable.length, keys: actionable.map((a) => `${a.issue.key}(${a.route.mode})`) }, "JIRA: poller found actionable issues");
+            }
+            for (const { issue, route, fp } of actionable) {
+                processedStates.set(issue.key, fp);
+                try {
+                    await processJiraTicket({
+                        issueKey: issue.key,
+                        config,
+                        mode: route.mode,
+                        generatedImageDir,
+                        orchestratorPublicOrigin,
+                        sitePublicOrigin,
+                        logger,
+                    });
+                }
+                catch (err) {
+                    logger.error({ issueKey: issue.key, mode: route.mode, error: err instanceof Error ? err.message : String(err) }, "JIRA: poller failed to process issue");
+                }
+            }
+        }
+        catch (err) {
+            logger.error({ error: err instanceof Error ? err.message : String(err) }, "JIRA: poller query failed");
+        }
+        finally {
+            isPolling = false;
+        }
+    }
+    void poll();
+    pollTimer = setInterval(() => void poll(), config.pollIntervalMs);
+    // Clear dedup cache every 24h so issues that sit in the same state for a
+    // long time can still be re-picked-up if needed (e.g. after server restart
+    // with stale cache).
+    const CLEAR_INTERVAL_MS = 24 * 60 * 60 * 1000;
+    clearTimer = setInterval(() => {
+        const cleared = processedStates.size;
+        processedStates.clear();
+        logger.debug({ cleared }, "JIRA: cleared poller dedup cache");
+    }, CLEAR_INTERVAL_MS);
+    const shutdown = () => {
+        if (pollTimer) {
+            clearInterval(pollTimer);
+            pollTimer = null;
+        }
+        if (clearTimer) {
+            clearInterval(clearTimer);
+            clearTimer = null;
+        }
+        logger.info("JIRA: poller stopped");
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+}
+export function stopJiraPoller() {
+    if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+    }
+    if (clearTimer) {
+        clearInterval(clearTimer);
+        clearTimer = null;
+    }
+}
+export function getPollerStatus() {
+    return {
+        running: pollTimer !== null,
+        processedCount: processedStates.size,
+        isPolling,
+    };
+}

package/dist/jira/jira-processor.d.ts

@@ -0,0 +1,103 @@
+/**
+ * JIRA ticket processor.
+ *
+ * Extracts instructions + attachments from a JIRA issue, runs the agent loop
+ * to edit the site, then posts results back to the ticket.
+ */
+import type { Logger } from "../logger.ts";
+import type { JiraConfig, JiraIssue, JiraProcessingResult, JiraProcessingEntry, JiraUser } from "./jira-types.ts";
+/**
+ * Controls what processJiraTicket does:
+ *  - "review":  agent reads the ticket without tools, posts a plan-or-questions
+ *               comment, does not change the site, does not transition the issue.
+ *  - "execute": agent runs with the full tool set, applies edits, transitions
+ *               the issue to the preview status (or directly to done if
+ *               autoPublish is enabled).
+ *  - "publish": publish the session's draft, transition to done.
+ */
+export type JiraProcessingMode = "review" | "execute" | "publish";
+export declare function getProcessingStatus(): {
+    queue: JiraProcessingEntry[];
+    recent: JiraProcessingResult[];
+};
+/**
+ * Convert Atlassian Document Format to plain text.
+ * Handles the common node types: paragraph, heading, text, hardBreak, listItem, codeBlock.
+ */
+export declare function adfToPlainText(node: unknown): string;
+/**
+ * Render the ticket's comment thread as plain text labelled by role
+ * (Agent / Reporter). Returns "" when there are no comments.
+ *
+ * Long bodies are truncated to keep token usage bounded — the reporter's
+ * latest reply is what matters most, and we don't want old agent formatting
+ * boilerplate to crowd out the real task context.
+ */
+export declare function buildCommentHistory(issue: JiraIssue, agentAccountId: string | undefined): string;
+export declare function processJiraTicket(options: {
+    issueKey: string;
+    config: JiraConfig;
+    /** Which stage of the workflow to run. Defaults to "execute" for backward compat. */
+    mode?: JiraProcessingMode;
+    generatedImageDir: string;
+    orchestratorPublicOrigin: string;
+    sitePublicOrigin: string;
+    logger: Logger;
+    assignBackTo?: JiraUser;
+}): Promise<JiraProcessingResult>;
+export type ReviewDecision = {
+    decision: "proceed" | "questions";
+    plan: string[];
+    questions?: string[];
+};
+/**
+ * Extract the review JSON from raw agent output. Tolerant of: leading/trailing
+ * prose, ```json fences, and stray <thinking> tags.
+ */
+export declare function parseReviewDecision(raw: string): ReviewDecision;
+/**
+ * Count how many prior review-mode comments the agent has posted on this issue,
+ * so we can cap the number of review passes per ticket.
+ */
+export declare function countAgentReviewComments(issue: JiraIssue, agentAccountId: string | undefined): number;
+/**
+ * Decide whether a comment was authored by our agent.
+ *
+ * Looks at both the author's accountId AND the body shape. This matters because
+ * in solo/dev Jira tenants the reporter and agent share a single human's
+ * accountId — filtering by accountId alone would discard every reporter reply
+ * as a self-loop and the workflow would stall.
+ */
+export declare function isAgentAuthoredComment(body: string, authorAccountId: string | undefined, agentAccountId: string | undefined): boolean;
+/**
+ * Strip internal reasoning artifacts from an agent summary before posting to Jira.
+ * Claude occasionally emits <thinking>…</thinking> and similar XML-style reasoning
+ * tags as plain text, plus interstitial tool-calling narration accumulates across
+ * turns. Drop the noise, collapse whitespace.
+ */
+export declare function cleanAgentSummary(raw: string): string;
+export type SiteResolution = {
+    siteId: string;
+    via: "text-match" | "single-site" | "env-fallback" | "default-fallback";
+} | {
+    ambiguous: true;
+    candidates: Array<{
+        id: string;
+        name?: string;
+    }>;
+};
+/**
+ * Decide which site a ticket targets.
+ *
+ * Priority:
+ * 1. Ticket text (summary + description + reporter comments) uniquely names a
+ *    registered site → use it. Reporter comments are included so that a reply
+ *    to the "Which site?" clarification comment ("use avocado-stories") is
+ *    honoured instead of looping the same question.
+ * 2. Multiple registered sites → ambiguous, ask the reporter.
+ *    (JIRA_SITE_ID is intentionally NOT consulted here — it's a fallback, not a lock,
+ *    so adding a second site doesn't silently keep editing the first one.)
+ * 3. Exactly one registered site → use it.
+ * 4. No registered sites → use `config.siteId` (JIRA_SITE_ID env or built-in default).
+ */
+export declare function resolveSiteForTicket(issue: JiraIssue, config: JiraConfig): SiteResolution;