@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/notifications.js

@@ -0,0 +1,553 @@
+/**
+ * `notifications` — read-only CLI for the Epic Conductor durable notification
+ * sink (BAPI-755).
+ *
+ *   npx -y @bridge_gpt/mcp-server notifications --repo <repo> --run <epic-key|run-id> [--follow]
+ *
+ * Resolves an epic key or a concrete run id to its canonical epic run via the
+ * EXISTING run-read endpoint (`fetchEpicRunState`, shared with `setup-epic`),
+ * then fetches `GET /jira/epic-runs/runs/{epic_run_id}/notifications` — a new
+ * BAPI-755 endpoint built in parallel on the Python side. This module treats
+ * that endpoint's response shape as a fixed, given contract and validates every
+ * field defensively rather than casting it.
+ *
+ * Strictly read-only and side-effect-free: no mutation, no MCP server startup.
+ * Without `--follow` it prints the latest page once and exits. With `--follow`
+ * it polls forever (until interrupted) at the same ~60s cadence as the
+ * server's own `epic_conductor_notification_sweep` job
+ * (`api/library/scheduled_jobs.py`), draining any full page immediately so a
+ * backlog is caught up fast before returning to normal cadence.
+ *
+ * Credentials are resolved ONLY through the shared conductor access seam
+ * ({@link resolveConductorBridgeApiAccess}, which itself resolves ONLY through
+ * `resolveBapiCredentials`) — never read directly from the environment here,
+ * and never obtained by spawning a subprocess. The API key travels only in the
+ * `X-API-Key` request header, matching the existing conductor Bridge API
+ * client convention; it never appears in a URL, in stdout, in stderr, or in any
+ * thrown/error text.
+ *
+ * Every notification data line goes to stdout (so a script can safely parse
+ * it); every other line — progress, "no data yet", warnings, errors — goes to
+ * stderr. This module deliberately renders in monochrome: no shared ANSI/color
+ * helper exists elsewhere in this codebase for CLI output (the one bespoke use,
+ * `review-tickets.ts`'s fail-loud alert box, is a one-off inline escape
+ * sequence, not a reusable convention), so per this ticket's guidance this CLI
+ * does not invent a new styling system.
+ */
+import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import os from "node:os";
+import { ConductorBridgeApiError, fetchConductorJsonWithTimeout, fetchEpicRunState, resolveConductorBridgeApiAccess, safeDiagnosticMessage, buildConductorJiraUrl, CONDUCTOR_FETCH_TIMEOUT_MS, } from "./conductor/bridge-api-client.js";
+// ---------------------------------------------------------------------------
+// Tunables (injectable — never a bare hardcoded setTimeout/limit downstream)
+// ---------------------------------------------------------------------------
+/**
+ * Follow-mode poll cadence, matching the server's own notification sweep
+ * (`epic_conductor_notification_sweep`, a 60s `IntervalTrigger` in
+ * `api/library/scheduled_jobs.py`). Overridable via
+ * {@link NotificationsCliDeps.pollIntervalMs} for tests.
+ */
+export const NOTIFICATIONS_FOLLOW_POLL_INTERVAL_MS = 60_000;
+/**
+ * Page size requested on every fetch (both the one-shot non-follow fetch and
+ * every follow-mode poll). A page that comes back at exactly this size is
+ * treated as "more may be waiting" and drained immediately, without a poll
+ * delay; a page smaller than this is "caught up". Overridable via
+ * {@link NotificationsCliDeps.pageLimit} for tests.
+ */
+export const NOTIFICATIONS_DEFAULT_PAGE_LIMIT = 200;
+function isSafeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value);
+}
+function isValidTimestamp(value) {
+    return typeof value === "string" && value.trim() !== "" && !Number.isNaN(Date.parse(value));
+}
+/** A nullable/absent field must be `null`/absent, or a non-empty string. */
+function readNullableNonEmptyString(record, key) {
+    const raw = record[key];
+    if (raw === undefined || raw === null)
+        return { ok: true, value: null };
+    return typeof raw === "string" && raw.trim() !== "" ? { ok: true, value: raw } : { ok: false };
+}
+/** A nullable/absent field must be `null`/absent, or a positive safe integer. */
+function readNullablePositiveInt(record, key) {
+    const raw = record[key];
+    if (raw === undefined || raw === null)
+        return { ok: true, value: null };
+    return isSafeInteger(raw) && raw > 0 ? { ok: true, value: raw } : { ok: false };
+}
+/** A nullable/absent field must be `null`/absent, or a valid timestamp string. */
+function readNullableTimestamp(record, key) {
+    const raw = record[key];
+    if (raw === undefined || raw === null)
+        return { ok: true, value: null };
+    return isValidTimestamp(raw) ? { ok: true, value: raw } : { ok: false };
+}
+/** Validate one raw notification item. Returns `null` for any malformed shape. */
+function validateNotification(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    if (!isSafeInteger(r.id) || r.id <= 0)
+        return null;
+    if (typeof r.kind !== "string" || r.kind.trim() === "")
+        return null;
+    if (!isValidTimestamp(r.created_at))
+        return null;
+    if (!isSafeInteger(r.attempt_count) || r.attempt_count < 0)
+        return null;
+    const ticketKey = readNullableNonEmptyString(r, "ticket_key");
+    if (!ticketKey.ok)
+        return null;
+    const gate = readNullableNonEmptyString(r, "gate");
+    if (!gate.ok)
+        return null;
+    const reason = readNullableNonEmptyString(r, "reason");
+    if (!reason.ok)
+        return null;
+    const headSha = readNullableNonEmptyString(r, "head_sha");
+    if (!headSha.ok)
+        return null;
+    const prNumber = readNullablePositiveInt(r, "pr_number");
+    if (!prNumber.ok)
+        return null;
+    const sentAt = readNullableTimestamp(r, "sent_at");
+    if (!sentAt.ok)
+        return null;
+    return {
+        id: r.id,
+        kind: r.kind,
+        ticket_key: ticketKey.value,
+        gate: gate.value,
+        reason: reason.value,
+        pr_number: prNumber.value,
+        head_sha: headSha.value,
+        attempt_count: r.attempt_count,
+        sent_at: sentAt.value,
+        created_at: r.created_at,
+    };
+}
+/** Validate the whole `{ notifications: [...] }` envelope. Never casts blindly. */
+function validateNotificationsResponse(parsed) {
+    if (!parsed || typeof parsed !== "object") {
+        return { ok: false, error: "malformed notifications response: expected a JSON object" };
+    }
+    const list = parsed.notifications;
+    if (!Array.isArray(list)) {
+        return { ok: false, error: "malformed notifications response: 'notifications' is not an array" };
+    }
+    const notifications = [];
+    for (let i = 0; i < list.length; i++) {
+        const n = validateNotification(list[i]);
+        if (!n) {
+            return { ok: false, error: `malformed notifications response: invalid entry at index ${i}` };
+        }
+        notifications.push(n);
+    }
+    return { ok: true, notifications };
+}
+// ---------------------------------------------------------------------------
+// Sanitized error classification (never a raw body/URL/API key)
+// ---------------------------------------------------------------------------
+/**
+ * Classify a thrown fetch error as recoverable (network hiccup, timeout, 5xx,
+ * or 429 — worth a follow-mode retry) or terminal (auth failure, 404, or any
+ * other non-2xx — never retried). Always returns a bounded, secret-free
+ * message via the shared {@link safeDiagnosticMessage} formatter.
+ */
+function describeConductorFetchError(err) {
+    if (err instanceof ConductorBridgeApiError) {
+        const recoverable = err.kind === "network" ||
+            err.kind === "timeout" ||
+            err.kind === "server" ||
+            (err.kind === "http" && err.status === 429);
+        return { recoverable, message: safeDiagnosticMessage(err, "Bridge API request failed") };
+    }
+    return { recoverable: false, message: "unexpected error contacting the Bridge API" };
+}
+/**
+ * Resolve `epicKeyOrRunId` to a canonical {@link ResolvedNotificationRun} via
+ * the SAME run-read endpoint `setup-epic` already uses ({@link fetchEpicRunState},
+ * `GET /jira/epic-runs/runs/{identifier}/state?repo_name=...` — the server
+ * accepts either the epic key or the concrete run UUID as `{identifier}`).
+ *
+ * `fetchEpicRunState` itself casts the parsed JSON to `EpicRunState` without
+ * validation; this function does NOT trust that cast — it re-validates the
+ * three fields it actually needs (`epic_run_id`, `epic_key`, `repo_name`) as
+ * non-empty strings, and rejects a response whose `repo_name` disagrees with
+ * the repo the caller authenticated against, before returning anything.
+ */
+export async function resolveNotificationRun(access, epicKeyOrRunId, fetchImpl = globalThis.fetch) {
+    let state;
+    try {
+        state = await fetchEpicRunState(access, epicKeyOrRunId, fetchImpl);
+    }
+    catch (err) {
+        const described = describeConductorFetchError(err);
+        return { ok: false, error: `could not resolve run '${epicKeyOrRunId}': ${described.message}` };
+    }
+    if (!state || typeof state !== "object") {
+        return { ok: false, error: `could not resolve run '${epicKeyOrRunId}': malformed response` };
+    }
+    const run = state.epic_run;
+    if (!run || typeof run !== "object") {
+        return { ok: false, error: `could not resolve run '${epicKeyOrRunId}': response is missing epic_run` };
+    }
+    const r = run;
+    const epicRunId = r.epic_run_id;
+    const epicKey = r.epic_key;
+    const repoName = r.repo_name;
+    if (typeof epicRunId !== "string" || epicRunId.trim() === "") {
+        return { ok: false, error: `could not resolve run '${epicKeyOrRunId}': missing/invalid epic_run_id` };
+    }
+    if (typeof epicKey !== "string" || epicKey.trim() === "") {
+        return { ok: false, error: `could not resolve run '${epicKeyOrRunId}': missing/invalid epic_key` };
+    }
+    if (typeof repoName !== "string" || repoName.trim() === "") {
+        return { ok: false, error: `could not resolve run '${epicKeyOrRunId}': missing/invalid repo_name` };
+    }
+    if (repoName !== access.repoName) {
+        return {
+            ok: false,
+            error: `could not resolve run '${epicKeyOrRunId}': it belongs to a different repository`,
+        };
+    }
+    return { ok: true, run: { epicRunId, epicKey, repoName } };
+}
+/**
+ * `GET /jira/epic-runs/runs/{epicRunId}/notifications?repo_name=...`
+ * (`&after_id=...` only when a cursor is supplied, `&limit=...` always).
+ * URL-encodes the run id; sends the API key ONLY as the `X-API-Key` header,
+ * matching the existing conductor Bridge API client convention — never in the
+ * URL. Validates the parsed response defensively via
+ * {@link validateNotificationsResponse} rather than casting it.
+ */
+export async function fetchNotificationsPage(access, epicRunId, options, fetchImpl = globalThis.fetch) {
+    const params = {
+        repo_name: access.repoName,
+        limit: String(options.limit),
+    };
+    if (options.afterId !== undefined) {
+        params.after_id = String(options.afterId);
+    }
+    const url = buildConductorJiraUrl(access.baseUrl, `/epic-runs/runs/${encodeURIComponent(epicRunId)}/notifications`, params);
+    let parsed;
+    try {
+        parsed = await fetchConductorJsonWithTimeout(url, { "X-API-Key": access.apiKey }, CONDUCTOR_FETCH_TIMEOUT_MS, fetchImpl);
+    }
+    catch (err) {
+        const described = describeConductorFetchError(err);
+        return { ok: false, recoverable: described.recoverable, error: described.message };
+    }
+    const validated = validateNotificationsResponse(parsed);
+    if (!validated.ok) {
+        return { ok: false, recoverable: false, error: validated.error };
+    }
+    return { ok: true, notifications: validated.notifications };
+}
+// ---------------------------------------------------------------------------
+// Line formatting
+// ---------------------------------------------------------------------------
+/**
+ * Bound on the rendered `reason=` segment. The server already bounds stored
+ * reason text (BAPI-755 backend); this is a client-side belt-and-suspenders
+ * cap so a single notification line can never grow unboundedly even if that
+ * server-side bound changes. ~200 chars keeps one line legible in a terminal.
+ */
+const REASON_MAX_LENGTH = 200;
+/** Collapse embedded newlines/control chars to single spaces and bound the length. */
+function normalizeReasonText(raw) {
+    // Control characters (\x00-\x1f, \x7f) become a single space -- this
+    // covers \n, \r, \t and anything else that could break a single terminal
+    // line -- then any remaining run of whitespace collapses to one space.
+    // eslint-disable-next-line no-control-regex -- deliberately matching control chars
+    const collapsed = raw.replace(/[\x00-\x1f\x7f]+/g, " ").replace(/\s+/g, " ").trim();
+    return collapsed.length > REASON_MAX_LENGTH ? `${collapsed.slice(0, REASON_MAX_LENGTH)}…` : collapsed;
+}
+/**
+ * Render one stable one-line grammar:
+ *   `created_at | kind | ticket=... | gate=... | pr=... | sha=... | reason=...`
+ * `created_at` and `kind` are always first and always present. Every other
+ * segment is OMITTED (never rendered as `ticket=null`/`ticket=undefined`) when
+ * the corresponding field is absent.
+ */
+export function formatNotificationLine(notification) {
+    const segments = [notification.created_at, notification.kind];
+    if (notification.ticket_key)
+        segments.push(`ticket=${notification.ticket_key}`);
+    if (notification.gate)
+        segments.push(`gate=${notification.gate}`);
+    if (notification.pr_number !== null)
+        segments.push(`pr=${notification.pr_number}`);
+    if (notification.head_sha)
+        segments.push(`sha=${notification.head_sha}`);
+    if (notification.reason)
+        segments.push(`reason=${normalizeReasonText(notification.reason)}`);
+    return segments.join(" | ");
+}
+/** User-facing usage text for `notifications`, including `-h`/`--help`. */
+export function getNotificationsUsage() {
+    return [
+        "Usage: mcp-server notifications --repo <repo> --run <epic-key|run-id> [--follow]",
+        "",
+        "Read-only: prints an epic run's durable notification feed (BAPI-755), one line",
+        "per notification, oldest first. <epic-key|run-id> is resolved to the canonical",
+        "epic run via the existing run-read endpoint, exactly like setup-epic does.",
+        "",
+        "Required:",
+        "  --repo <name>          Repo name",
+        "  --run <epic-key|id>    Epic key (e.g. BAPI-405) or a concrete run id",
+        "",
+        "Options:",
+        "  --follow               Keep polling for new notifications (~60s cadence,",
+        "                         catching up immediately on any backlog) and print",
+        "                         each new one as it arrives, until interrupted",
+        "                         (Ctrl-C). Without it, prints the latest page once",
+        "                         and exits.",
+        "  -h, --help             Show this help",
+        "",
+        "Each line has the form:",
+        "  <created_at> | <kind> | ticket=... | gate=... | pr=... | sha=... | reason=...",
+        "Every ticket=/gate=/pr=/sha=/reason= segment is OMITTED when the",
+        "corresponding field is absent — never rendered as 'null' or 'undefined'.",
+        "",
+        "All notification data is written to stdout (safe to pipe/parse); progress",
+        "and diagnostic text is written to stderr.",
+    ].join("\n");
+}
+const NOTIFICATIONS_KNOWN_FLAGS = new Set(["--repo", "--run", "--follow"]);
+/**
+ * Parse `notifications` argv. Requires non-blank `--repo` and `--run`, accepts
+ * an optional `--follow` boolean flag (and its `--help`), and REJECTS unknown
+ * flags, duplicate flags, a flag with a missing/blank value, and any
+ * positional (non-flag) argument. Mirrors the flag-parsing shape already used
+ * by `parseMcpInvokeArgs` (`mcp-invoke.ts`): `--flag value` or `--flag=value`,
+ * duplicate detection per flag, missing-value detection before the flag is
+ * consumed.
+ */
+export function parseNotificationsArgs(argv) {
+    let repo;
+    let run;
+    let follow = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            return { ok: true, help: true };
+        }
+        let flag = token;
+        let value;
+        const eq = token.indexOf("=");
+        if (token.startsWith("--") && eq !== -1) {
+            flag = token.slice(0, eq);
+            value = token.slice(eq + 1);
+        }
+        if (!NOTIFICATIONS_KNOWN_FLAGS.has(flag)) {
+            if (token.startsWith("-")) {
+                return { ok: false, error: `Unknown flag: ${flag}` };
+            }
+            return { ok: false, error: `Unexpected positional argument: ${token}` };
+        }
+        if (flag === "--follow") {
+            if (value !== undefined) {
+                return { ok: false, error: "--follow does not take a value" };
+            }
+            if (follow) {
+                return { ok: false, error: "Duplicate --follow flag" };
+            }
+            follow = true;
+            continue;
+        }
+        if (value === undefined) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                return { ok: false, error: `Missing value for ${flag}` };
+            }
+            value = next;
+            i++;
+        }
+        const trimmed = value.trim();
+        if (trimmed === "") {
+            return { ok: false, error: `${flag} requires a non-blank value` };
+        }
+        if (flag === "--repo") {
+            if (repo !== undefined)
+                return { ok: false, error: "Duplicate --repo flag" };
+            repo = trimmed;
+        }
+        else {
+            if (run !== undefined)
+                return { ok: false, error: "Duplicate --run flag" };
+            run = trimmed;
+        }
+    }
+    if (repo === undefined)
+        return { ok: false, error: "Missing required --repo flag" };
+    if (run === undefined)
+        return { ok: false, error: "Missing required --run flag" };
+    return { ok: true, args: { repo, run, follow } };
+}
+export function createDefaultNotificationsCliDeps() {
+    return {
+        env: process.env,
+        cwd: process.cwd(),
+        platform: process.platform,
+        homedir: os.homedir,
+        readFile: (p) => fsReadFile(p, "utf-8"),
+        stat: (p) => fsStat(p),
+        fetch: globalThis.fetch,
+        stdout: (line) => {
+            process.stdout.write(`${line}\n`);
+        },
+        stderr: (line) => {
+            process.stderr.write(`${line}\n`);
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => new Date(),
+        isTTY: Boolean(process.stderr.isTTY),
+        onSignal: (signal, handler) => {
+            process.on(signal, handler);
+            return () => {
+                process.off(signal, handler);
+            };
+        },
+        pollIntervalMs: NOTIFICATIONS_FOLLOW_POLL_INTERVAL_MS,
+        pageLimit: NOTIFICATIONS_DEFAULT_PAGE_LIMIT,
+    };
+}
+/** Print each notification whose id advances `cursor`; returns the new cursor. */
+function emitNewRows(page, cursor, stdout) {
+    let next = cursor;
+    for (const n of page) {
+        if (next !== undefined && n.id <= next)
+            continue;
+        stdout(formatNotificationLine(n));
+        next = next === undefined ? n.id : Math.max(next, n.id);
+    }
+    return next;
+}
+/**
+ * CLI entry for the read-only `notifications` subcommand. Returns a process
+ * exit code (never calls `process.exit` itself — the caller in `index.ts`
+ * assigns the return value to `process.exitCode`, matching every other
+ * subcommand here).
+ *
+ * Non-follow: fetches the latest (no-cursor) page once, prints it in
+ * ascending id order, exits 0. An empty result is reported on stderr, naming
+ * the resolved run and pointing at `--follow` — never implying data loss.
+ *
+ * Follow: repeatedly fetches (cursor-advancing), printing only new rows.
+ * A page that comes back at `pageLimit` is drained immediately (no sleep)
+ * until a page comes back under the limit, then normal `pollIntervalMs`
+ * cadence resumes. A RECOVERABLE fetch failure (network/timeout/5xx/429) is a
+ * stderr warning that keeps the last confirmed cursor and retries after the
+ * normal wait; a TERMINAL failure (401/403/404/malformed response) exits 1
+ * immediately with no further polling. A clean interruption (SIGINT/SIGTERM)
+ * exits 0 with no stack trace.
+ */
+export async function runNotificationsCli(argv, overrides = {}) {
+    const deps = { ...createDefaultNotificationsCliDeps(), ...overrides };
+    const parsed = parseNotificationsArgs(argv);
+    if (!parsed.ok) {
+        deps.stderr(`Error: ${parsed.error}`);
+        deps.stderr("");
+        deps.stderr(getNotificationsUsage());
+        return 1;
+    }
+    // Narrowing on a single `in` check (rather than the prior compound
+    // `"help" in parsed && parsed.help`) so TypeScript can actually exclude the
+    // `{ ok: true; help: true }` branch below — a compound `&&` condition's
+    // negation isn't narrowed the same way by control-flow analysis.
+    if ("help" in parsed) {
+        deps.stdout(getNotificationsUsage());
+        return 0;
+    }
+    const { repo, run, follow } = parsed.args;
+    const accessResult = await resolveConductorBridgeApiAccess({
+        env: deps.env,
+        cwd: deps.cwd,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        repoName: repo,
+    });
+    if (!accessResult.ok) {
+        deps.stderr(`Error: cannot reach the Bridge API: ${accessResult.error}`);
+        return 1;
+    }
+    const access = accessResult.access;
+    const fetchImpl = deps.fetch;
+    if (deps.isTTY)
+        deps.stderr("Checking...");
+    const resolved = await resolveNotificationRun(access, run, fetchImpl);
+    if (!resolved.ok) {
+        deps.stderr(`Error: ${resolved.error}`);
+        return 1;
+    }
+    const { epicRunId, epicKey } = resolved.run;
+    if (!follow) {
+        const page = await fetchNotificationsPage(access, epicRunId, { limit: deps.pageLimit }, fetchImpl);
+        if (!page.ok) {
+            deps.stderr(`Error: could not fetch notifications for ${epicKey} (${epicRunId}): ${page.error}`);
+            return 1;
+        }
+        if (page.notifications.length === 0) {
+            deps.stderr(`No notifications yet for ${epicKey} (${epicRunId}). Re-run with --follow to wait for future ones.`);
+            return 0;
+        }
+        emitNewRows(page.notifications, undefined, deps.stdout);
+        return 0;
+    }
+    // --- Follow mode -----------------------------------------------------
+    let stopped = false;
+    let resolveStop;
+    const stopPromise = new Promise((resolve) => {
+        resolveStop = resolve;
+    });
+    const requestStop = () => {
+        if (!stopped) {
+            stopped = true;
+            resolveStop?.();
+        }
+    };
+    const disposers = [deps.onSignal("SIGINT", requestStop), deps.onSignal("SIGTERM", requestStop)];
+    try {
+        let cursor;
+        let announcedWaiting = false;
+        while (!stopped) {
+            // Drain loop: keep fetching immediately (no sleep) while pages come
+            // back full — catches up on a backlog fast before returning to the
+            // normal poll cadence.
+            for (;;) {
+                const page = await fetchNotificationsPage(access, epicRunId, { afterId: cursor, limit: deps.pageLimit }, fetchImpl);
+                if (!page.ok) {
+                    if (!page.recoverable) {
+                        deps.stderr(`Error: notifications fetch failed for ${epicKey} (${epicRunId}): ${page.error}`);
+                        return 1;
+                    }
+                    deps.stderr(`Warning: notifications fetch failed, retrying: ${page.error}`);
+                    break; // Exit the drain loop; the outer loop waits, then retries.
+                }
+                if (page.notifications.length === 0) {
+                    if (cursor === undefined && !announcedWaiting) {
+                        deps.stderr(`No notifications yet for ${epicKey} (${epicRunId}) — waiting (--follow).`);
+                        announcedWaiting = true;
+                    }
+                    break; // Nothing to drain.
+                }
+                cursor = emitNewRows(page.notifications, cursor, deps.stdout);
+                if (page.notifications.length < deps.pageLimit)
+                    break; // Caught up.
+                if (stopped)
+                    break;
+            }
+            if (stopped)
+                break;
+            await Promise.race([deps.sleep(deps.pollIntervalMs), stopPromise]);
+        }
+        return 0;
+    }
+    finally {
+        for (const dispose of disposers)
+            dispose();
+    }
+}