@wardby/cli 0.3.0 → 0.4.1

package/dist/core/host-status.js

@@ -1,3 +1,4 @@
+import { CODING_CODE_PROVIDER } from "../coding/protocol.js";
 import { storedServiceNames } from "../coding/services/catalog.js";
 import { SERVICE_UNREADY_CATEGORY, serviceRefusalSentence, serviceUnreadySentence, } from "../coding/services/wording.js";
 import { PROTECTED_PATH_CATEGORY, PROTECTED_PATH_HOST_LINE } from "../coding/protected-path-wording.js";
@@ -8,7 +9,7 @@ const log = logger.child({ module: "host-status" });
 /** Keeps the edited comment readable; the full reply stays on the run. */
 const MAX_REPLY_CHARS = 2000;
 const TERMINAL = new Set(["succeeded", "failed", "refused", "lost", "budget_exhausted", "cancelled"]);
-const runLine = (runId) => `<sub>wardby run \`${runId}\`</sub>`;
+export const runLine = (runId) => `<sub>wardby run \`${runId}\`</sub>`;
 export function workingBody(runId) {
     return `👀 Working on it.\n\n${runLine(runId)}`;
 }
@@ -33,12 +34,18 @@ function pullRequestOutcome(result) {
         return null;
     if (!Number.isInteger(r.pullRequestNumber) || r.pullRequestNumber <= 0)
         return null;
-    return { outcome: r.outcome, repository: r.repository, pullRequestNumber: r.pullRequestNumber };
+    return {
+        outcome: r.outcome,
+        repository: r.repository,
+        pullRequestNumber: r.pullRequestNumber,
+        codeProvider: CODING_CODE_PROVIDER,
+        ...(typeof r.pullRequestUrl === "string" ? { pullRequestUrl: r.pullRequestUrl } : {}),
+    };
 }
 /** The agent's reply as a quote, cut to MAX_REPLY_CHARS, with @-mentions defused so nobody is pinged. */
+const cutReply = (text) => text.length > MAX_REPLY_CHARS ? `${text.slice(0, MAX_REPLY_CHARS)}…` : text;
 function quoteReply(text) {
-    const cut = text.length > MAX_REPLY_CHARS ? `${text.slice(0, MAX_REPLY_CHARS)}…` : text;
-    return cut
+    return cutReply(text)
         .replace(/@(?=[\w-])/g, "@​")
         .split("\n")
         .map((line) => `> ${line}`)
@@ -106,7 +113,41 @@ export function outcomeBody(run, repository, pullRequests, failedChildren = [],
     }
     if (links.length > 0)
         return `✅ ${links.join(", ")}.\n\n${footer}`;
-    return `✅ Finished without opening a pull request.${quoted}\n\n${footer}`;
+    if (opts.replyAsAnswer && reply)
+        return `✅ ${cutReply(reply)}\n\n${footer}`;
+    return `✅ ${opts.noPullRequestText ?? "Finished without opening a pull request."}${quoted}\n\n${footer}`;
+}
+/** The parts of a finished run's outcome a status comment reports; shared by GitHub and Jira status comments. */
+export async function collectRunOutcome(db, run) {
+    const children = await db.run.findMany({
+        where: { parentRunId: run.id },
+        select: {
+            id: true,
+            status: true,
+            error: true,
+            codingRun: { select: { result: true, failureCategory: true, services: true } },
+        },
+        orderBy: { startedAt: "asc" },
+    });
+    const pullRequests = children
+        .map((c) => {
+        const pr = pullRequestOutcome(c.codingRun?.result);
+        return pr ? { ...pr, runId: c.id } : null;
+    })
+        .filter((pr) => pr !== null);
+    const failedChildren = children
+        .filter((c) => TERMINAL.has(c.status) && c.status !== "succeeded")
+        .map((c) => ({
+        id: c.id,
+        status: c.status,
+        failureCategory: c.codingRun?.failureCategory ?? null,
+        error: c.error ?? null,
+        services: storedServiceNames(c.codingRun?.services),
+    }));
+    const budgetSentence = run.status === "budget_exhausted" || run.status === "refused"
+        ? await loadBudgetSentence(db, run.id, run.status)
+        : undefined;
+    return { pullRequests, failedChildren, ...(budgetSentence ? { budgetSentence } : {}) };
 }
 /**
  * Writes a finished run's outcome to its status comment and marks it
@@ -128,31 +169,7 @@ export async function completeHostStatus(db, run, hosts, opts = {}) {
         const host = hosts[status.provider];
         if (!host)
             return;
-        const children = await db.run.findMany({
-            where: { parentRunId: run.id },
-            select: {
-                id: true,
-                status: true,
-                error: true,
-                codingRun: { select: { result: true, failureCategory: true, services: true } },
-            },
-            orderBy: { startedAt: "asc" },
-        });
-        const pullRequests = children
-            .map((c) => pullRequestOutcome(c.codingRun?.result))
-            .filter((pr) => pr !== null);
-        const failedChildren = children
-            .filter((c) => TERMINAL.has(c.status) && c.status !== "succeeded")
-            .map((c) => ({
-            id: c.id,
-            status: c.status,
-            failureCategory: c.codingRun?.failureCategory ?? null,
-            error: c.error ?? null,
-            services: storedServiceNames(c.codingRun?.services),
-        }));
-        const budgetSentence = run.status === "budget_exhausted" || run.status === "refused"
-            ? await loadBudgetSentence(db, run.id, run.status)
-            : undefined;
+        const { pullRequests, failedChildren, budgetSentence } = await collectRunOutcome(db, run);
         const body = outcomeBody(run, status.repository, pullRequests, failedChildren, { budgetSentence });
         let commentId = status.commentId;
         if (commentId) {

package/dist/core/issue-bridge.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Links a run's pull requests to the issue that started it: records each
+ * issue/PR pair, puts a web link on the issue, and applies the link's
+ * configured status move. Provider-neutral: a code host is only ever
+ * { provider, repository, number }. The issue key comes from the run tree
+ * (RunIssueStatus), never from model output. The status move is a control-plane
+ * action (not gated by allowedTransitions). Nothing here throws, except
+ * handlePullRequestClosed's lookup before it has claimed anything (so the
+ * webhook delivery is rolled back and redelivered).
+ */
+import { type PrismaClient } from "#prisma";
+import { type IssueTracker, type IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+export type IssueBridgeDb = Pick<PrismaClient, "issuePullRequest">;
+export type PullRequestClosedDb = Pick<PrismaClient, "issuePullRequest" | "agentIssueProject">;
+export interface BridgedPullRequest {
+    codeProvider: string;
+    repository: string;
+    number: number;
+    url: string;
+    openedByRunId: string;
+    outcome: "pull_request_opened" | "pull_request_updated";
+}
+export interface RecordPullRequestsInput {
+    issueKey: string;
+    issueProvider: string;
+    agentId: string;
+    /** The status the link moves the issue to when a pull request is opened, if configured. */
+    onPullRequestOpened?: string | null;
+    pullRequests: BridgedPullRequest[];
+}
+export declare const pullRequestGlobalId: (pr: Pick<BridgedPullRequest, "codeProvider" | "repository" | "number">) => string;
+/**
+ * Returns sentences for the outcome comment (a refused status move); empty
+ * when there is nothing to say. Safe to repeat (a retried completion): each
+ * pair's side effects happen once — the status move only when this call newly
+ * recorded an opened pull request, and a merged/closed pair is never re-linked
+ * (re-posting its web link would un-resolve it). An unreadable store skips
+ * both rather than risk repeating them.
+ */
+export declare function recordPullRequests(db: IssueBridgeDb, tracker: IssueTracker, input: RecordPullRequestsInput): Promise<{
+    notes: string[];
+}>;
+export interface ClosedPullRequest {
+    codeProvider: string;
+    repository: string;
+    number: number;
+    merged: boolean;
+}
+/**
+ * A pull request wardby recorded against an issue was merged or closed: marks
+ * each still-open pair, and, where the agent's link to the issue's project is
+ * still write, comments on the issue (and on merge resolves the web link and
+ * applies the link's onPullRequestMerged move). Only rows wardby wrote are
+ * touched, matched by the host's own identity for the PR — nothing from the
+ * PR's text. The row is claimed first (open → merged/closed), so a duplicate
+ * or concurrent delivery finds nothing to do. Throws only when the lookup of
+ * linked rows fails — before anything is claimed — so the caller's webhook
+ * delivery is rolled back and redelivered; never throws after that.
+ */
+export declare function handlePullRequestClosed(db: PullRequestClosedDb, trackers: IssueTrackerRegistry | undefined, pr: ClosedPullRequest): Promise<void>;

package/dist/core/issue-bridge.js

@@ -0,0 +1,189 @@
+/**
+ * Links a run's pull requests to the issue that started it: records each
+ * issue/PR pair, puts a web link on the issue, and applies the link's
+ * configured status move. Provider-neutral: a code host is only ever
+ * { provider, repository, number }. The issue key comes from the run tree
+ * (RunIssueStatus), never from model output. The status move is a control-plane
+ * action (not gated by allowedTransitions). Nothing here throws, except
+ * handlePullRequestClosed's lookup before it has claimed anything (so the
+ * webhook delivery is rolled back and redelivered).
+ */
+import { Prisma } from "#prisma";
+import { projectOf, } from "../providers/issue-tracker/types.js";
+import { logger } from "./logger.js";
+const log = logger.child({ module: "issue-bridge" });
+export const pullRequestGlobalId = (pr) => `wardby:pr:${pr.codeProvider}:${pr.repository}#${pr.number}`;
+/**
+ * Makes sure the issue/PR pair has a row, without ever overwriting one: a new
+ * row is "created"; an existing open one gets its url refreshed ("open"); a
+ * merged or closed one is left alone ("settled"). A lost create race (P2002)
+ * reads back the winner's row. "unknown" when the store could not be read.
+ */
+async function ensurePair(db, input, pr) {
+    const where = {
+        codeProvider_repository_number_issueProvider_issueKey: {
+            codeProvider: pr.codeProvider,
+            repository: pr.repository,
+            number: pr.number,
+            issueProvider: input.issueProvider,
+            issueKey: input.issueKey,
+        },
+    };
+    try {
+        let existing = await db.issuePullRequest.findUnique({ where, select: { state: true } });
+        if (!existing) {
+            try {
+                await db.issuePullRequest.create({
+                    data: {
+                        issueProvider: input.issueProvider,
+                        issueKey: input.issueKey,
+                        codeProvider: pr.codeProvider,
+                        repository: pr.repository,
+                        number: pr.number,
+                        url: pr.url,
+                        agentId: input.agentId,
+                        openedByRunId: pr.openedByRunId,
+                    },
+                });
+                return "created";
+            }
+            catch (err) {
+                if (!(err instanceof Prisma.PrismaClientKnownRequestError && err.code === "P2002"))
+                    throw err;
+                existing = await db.issuePullRequest.findUnique({ where, select: { state: true } });
+                if (!existing)
+                    return "unknown";
+            }
+        }
+        if (existing.state !== "open")
+            return "settled";
+        await db.issuePullRequest.update({ where, data: { url: pr.url } });
+        return "open";
+    }
+    catch (err) {
+        log.warn({ err, issueKey: input.issueKey, repository: pr.repository, number: pr.number }, "could not record the issue/PR pair");
+        return "unknown";
+    }
+}
+/**
+ * Returns sentences for the outcome comment (a refused status move); empty
+ * when there is nothing to say. Safe to repeat (a retried completion): each
+ * pair's side effects happen once — the status move only when this call newly
+ * recorded an opened pull request, and a merged/closed pair is never re-linked
+ * (re-posting its web link would un-resolve it). An unreadable store skips
+ * both rather than risk repeating them.
+ */
+export async function recordPullRequests(db, tracker, input) {
+    const notes = [];
+    try {
+        let newlyOpened = false;
+        for (const pr of input.pullRequests) {
+            const state = await ensurePair(db, input, pr);
+            if (state === "created" && pr.outcome === "pull_request_opened")
+                newlyOpened = true;
+            if (state !== "created" && state !== "open")
+                continue;
+            try {
+                await tracker.addRemoteLink(input.issueKey, {
+                    globalId: pullRequestGlobalId(pr),
+                    url: pr.url,
+                    title: `${pr.repository}#${pr.number}`,
+                });
+            }
+            catch (err) {
+                log.warn({ err, issueKey: input.issueKey, repository: pr.repository, number: pr.number }, "could not link the pull request on the issue");
+            }
+        }
+        const target = input.onPullRequestOpened;
+        if (target && newlyOpened) {
+            try {
+                await tracker.transitionTo(input.issueKey, target);
+            }
+            catch (err) {
+                log.warn({ err, issueKey: input.issueKey, target }, "could not move the issue after a pull request opened");
+                notes.push(`Could not move ${input.issueKey} to "${target}"; it may need a manual move.`);
+            }
+        }
+    }
+    catch (err) {
+        log.warn({ err, issueKey: input.issueKey }, "could not bridge the pull requests to the issue");
+    }
+    return { notes };
+}
+/**
+ * A pull request wardby recorded against an issue was merged or closed: marks
+ * each still-open pair, and, where the agent's link to the issue's project is
+ * still write, comments on the issue (and on merge resolves the web link and
+ * applies the link's onPullRequestMerged move). Only rows wardby wrote are
+ * touched, matched by the host's own identity for the PR — nothing from the
+ * PR's text. The row is claimed first (open → merged/closed), so a duplicate
+ * or concurrent delivery finds nothing to do. Throws only when the lookup of
+ * linked rows fails — before anything is claimed — so the caller's webhook
+ * delivery is rolled back and redelivered; never throws after that.
+ */
+export async function handlePullRequestClosed(db, trackers, pr) {
+    if (!trackers)
+        return;
+    const where = { codeProvider: pr.codeProvider, repository: pr.repository, number: pr.number };
+    // Not caught: nothing is claimed yet, and a throw rolls back the delivery so it is redelivered.
+    const rows = await db.issuePullRequest.findMany({ where: { ...where, state: "open" } });
+    for (const row of rows) {
+        try {
+            const claimed = await db.issuePullRequest.updateMany({
+                where: { id: row.id, state: "open" },
+                data: { state: pr.merged ? "merged" : "closed" },
+            });
+            if (claimed.count === 0)
+                continue;
+            const tracker = trackers[row.issueProvider];
+            if (!tracker)
+                continue;
+            const link = await db.agentIssueProject.findUnique({
+                where: {
+                    agentId_provider_projectKey: {
+                        agentId: row.agentId,
+                        provider: row.issueProvider,
+                        projectKey: projectOf(row.issueKey),
+                    },
+                },
+                select: { access: true, commentVisibilityRole: true, onPullRequestMerged: true },
+            });
+            if (link?.access !== "write")
+                continue;
+            const ref = `[${row.repository}#${row.number}](${row.url})`;
+            let markdown;
+            if (pr.merged) {
+                await tracker
+                    .addRemoteLink(row.issueKey, {
+                    globalId: pullRequestGlobalId(row),
+                    url: row.url,
+                    title: `${row.repository}#${row.number}`,
+                    status: { resolved: true },
+                })
+                    .catch((err) => log.warn({ err, issueKey: row.issueKey, ...where }, "could not resolve the pull request's web link"));
+                markdown = `✅ Pull request ${ref} was merged.`;
+                const target = link.onPullRequestMerged;
+                if (target) {
+                    try {
+                        const moved = await tracker.transitionTo(row.issueKey, target);
+                        markdown += ` Moved to ${moved.toStatus}.`;
+                    }
+                    catch (err) {
+                        log.warn({ err, issueKey: row.issueKey, target }, "could not move the issue after its pull request merged");
+                        markdown += ` Could not move ${row.issueKey} to "${target}"; it may need a manual move.`;
+                    }
+                }
+            }
+            else {
+                markdown = `Pull request ${ref} was closed without merging.`;
+            }
+            await tracker.comment(row.issueKey, {
+                markdown,
+                ...(link.commentVisibilityRole ? { visibilityRole: link.commentVisibilityRole } : {}),
+            });
+        }
+        catch (err) {
+            log.warn({ err, issueKey: row.issueKey, ...where }, "could not bridge the closed pull request to the issue");
+        }
+    }
+}

package/dist/core/issue-dedupe.d.ts

@@ -0,0 +1,70 @@
+import type { PrismaClient } from "#prisma";
+import { type CreateIssueInput, type IssueTracker, type TrackerCallOptions } from "../providers/issue-tracker/types.js";
+export declare const FINGERPRINT_MAX_LENGTH = 200;
+/**
+ * Each tracker call inside the lock: a whole-call cap, and a 429 fails at once rather than sleeping. Jira
+ * Cloud calls through the api.atlassian.com gateway routinely take several seconds each, and one tracker
+ * call can be a few requests (a create resolves the issue type and its fields first), so the cap is generous.
+ */
+export declare const TRACKER_CALL_OPTIONS: Readonly<TrackerCallOptions>;
+/** How long a sighting waits for another sighting of the same fingerprint before answering "busy". */
+export declare const DEDUPE_LOCK_TIMEOUT_MS = 5000;
+/**
+ * The critical section is the lock wait (5 s) plus at most two bounded tracker calls (getIssue, then
+ * createIssue or comment: 2 x 30 s) plus a few row reads/writes; 90 s leaves ample margin so a create is
+ * never in flight when the transaction (and with it the advisory lock) is torn down. The cost: each
+ * sighting in progress holds one pool connection for up to this long, and waiters hold one for up to
+ * the lock timeout (callers waiting for a free connection give up after maxWait).
+ */
+export declare const DEDUPE_TRANSACTION_TIMEOUT_MS = 90000;
+export type IssueDedupeDb = Pick<PrismaClient, "$transaction">;
+export interface IssueDedupeLink {
+    provider: string;
+    projectKey: string;
+    access: string;
+    commentVisibilityRole?: string | null;
+}
+export interface FileIssueInput {
+    agentId: string;
+    runId?: string | null;
+    link: IssueDedupeLink;
+    tracker: IssueTracker;
+    fingerprint?: string | null;
+    /** Everything but the project, which comes from the link. */
+    create: Omit<CreateIssueInput, "projectKey">;
+    /** Appended after the description (and after any "Regression of" line), so it stays the last line. */
+    footerMarkdown?: string;
+    /** Posted on the existing issue when the fingerprint is seen again. */
+    seenAgainMarkdown: string;
+    /** false: only a seen-again update may happen; a create or regression returns issue_cap_reached. Default true. */
+    createAllowed?: boolean;
+}
+export type FileIssueOutcome = "created" | "seen_again" | "regression";
+export type FileIssueSuccess = {
+    outcome: FileIssueOutcome;
+    issueKey: string;
+    url: string;
+    seenCount: number;
+};
+export type FileIssueResult = FileIssueSuccess | {
+    error: string;
+    message: string;
+};
+export declare const BUSY_RESULT: {
+    readonly error: "busy";
+    readonly message: "another sighting of this fingerprint is being filed; try again";
+};
+/**
+ * The part of a fingerprint that identifies it: letters and digits only, lower-cased (Unicode-normalised),
+ * so a model's small slips in case, punctuation or spacing ("checkout-api" vs "checkoutapi") still match.
+ */
+export declare function normalizeFingerprint(fingerprint: string): string;
+export declare function fingerprintHash(fingerprint: string): string;
+/** A stable signed 64-bit advisory-lock key for one (provider, project, hash). */
+export declare function dedupeLockKey(provider: string, projectKey: string, hash: string): bigint;
+export declare function fileIssue(deps: {
+    db: IssueDedupeDb;
+    lockTimeoutMs?: number;
+}, input: FileIssueInput): Promise<FileIssueResult>;
+/** Postgres lock_not_available (55P03), as raised when lock_timeout expires, however the driver wraps it. */
+export declare function isLockTimeout(err: unknown): boolean;