@wardby/cli 0.6.0 → 0.8.0

package/dist/providers/vcs/github-remote.js

@@ -1,4 +1,4 @@
-import { CONTINUATION_CLOSED_ERROR } from "../../coding/continuation-wording.js";
+import { budgetStoppedChangesSentence, CONTINUATION_CLOSED_ERROR } from "../../coding/continuation-wording.js";
 import { normalizeGitHubRepository, normalizeGitRef } from "../../coding/protocol.js";
 import { logger } from "../../core/logger.js";
 import { validateChangedPath } from "./git.js";
@@ -79,7 +79,57 @@ export class GitHubRemote {
         if (!open)
             throw new Error(CONTINUATION_CLOSED_ERROR);
     }
-    async publish({ workspace: prepared, details, changedPaths }) {
+    /** See GitRemote.pullRequestBase: the root run's open PR's current base branch. Never throws. */
+    async pullRequestBase(input) {
+        const github = this.options.github;
+        if (!input.continuation || !github.openPullRequestBase)
+            return null;
+        try {
+            const found = await github.openPullRequestBase({
+                runId: input.continuation.rootRunId,
+                repository: input.repository,
+                baseRef: input.baseRef,
+                headRef: input.headRef,
+            });
+            return found ? { ref: found.baseRef } : null;
+        }
+        catch (error) {
+            logger.warn({ err: error, runId: input.runId }, "could not read the continuation pull request's base branch; continuing without merging it");
+            return null;
+        }
+    }
+    /** See VcsProvider.continuationPullRequestDraft: GitHub's draft flag on the root run's open PR. Never throws. */
+    async continuationPullRequestDraft(workspace) {
+        const github = this.options.github;
+        if (!workspace.continuation || !github.openPullRequestDraft)
+            return undefined;
+        try {
+            const draft = await github.openPullRequestDraft({
+                runId: workspace.continuation.rootRunId,
+                repository: workspace.repository,
+                baseRef: workspace.baseRef,
+                headRef: workspace.headRef,
+            });
+            return draft ?? undefined;
+        }
+        catch (error) {
+            logger.warn({ err: error, runId: workspace.runId }, "could not read the continuation pull request's draft state");
+            return undefined;
+        }
+    }
+    /** A continuation's description comment, written before the push (see GitRemote.proposeDescriptionBeforePush). Never throws. */
+    async proposeDescriptionBeforePush({ workspace: prepared, details, changedPaths, commitSha, }) {
+        const github = this.options.github;
+        if (!prepared.continuation || !details?.description || !github.proposeDescriptionComment)
+            return;
+        try {
+            await github.proposeDescriptionComment(this.descriptionInput({ ...prepared, continuation: prepared.continuation }, { ...details, description: details.description }, changedPaths, commitSha));
+        }
+        catch (error) {
+            logger.warn({ err: error, runId: prepared.runId }, "pre-push description comment failed");
+        }
+    }
+    async publish({ workspace: prepared, details, changedPaths, commitSha }) {
         // Revision-in-place: identify the PR by the run that originally opened
         // it (createOrFindDraftPullRequest's marker-based lookup keys on that
         // run's id), not this run's own -- this finds the existing open PR and
@@ -99,11 +149,65 @@ export class GitHubRemote {
             tag: details?.tag,
             packages: details?.packages,
             packageRefusals: details?.packageRefusals,
+            ...(details?.packageAudit ? { packageAudit: details.packageAudit } : {}),
+            ...(details?.restoredDependencies?.length ? { restoredDependencies: details.restoredDependencies } : {}),
             changedLockfiles: changedPaths.filter(isLockfilePath),
             ...(details?.issue ? { issue: details.issue } : {}),
+            ...(details?.issueNumber !== undefined ? { issueNumber: details.issueNumber } : {}),
             ...(details?.related ? { related: details.related } : {}),
         });
-        return { kind: "pull_request", number: pullRequest.number, url: pullRequest.url };
+        let description;
+        if (prepared.continuation) {
+            description = await this.updateDescription(prepared, details, changedPaths, commitSha);
+        }
+        else if (pullRequest.descriptionSha256) {
+            description = { kind: "written", sha256: pullRequest.descriptionSha256 };
+        }
+        return {
+            kind: "pull_request",
+            number: pullRequest.number,
+            url: pullRequest.url,
+            ...(description ? { description } : {}),
+        };
+    }
+    /** The no-push path: a fix round that changed nothing still re-derives its PR description. */
+    async refreshDescription(workspace, details) {
+        // No push: the head is the commit the workspace was checked out at.
+        return this.updateDescription(workspace, details, [], workspace.baseCommit);
+    }
+    /** Never throws: a description problem must not fail an already-pushed run. */
+    async updateDescription(prepared, details, changedPaths, headSha) {
+        const github = this.options.github;
+        if (!prepared.continuation || !details?.description || !github.updatePullRequestDescription)
+            return undefined;
+        try {
+            return await github.updatePullRequestDescription(this.descriptionInput({ ...prepared, continuation: prepared.continuation }, { ...details, description: details.description }, changedPaths, headSha));
+        }
+        catch (error) {
+            logger.warn({ err: error, runId: prepared.runId }, "pull request description update failed");
+            return { kind: "skipped", reason: "error" };
+        }
+    }
+    descriptionInput(prepared, details, changedPaths, headSha) {
+        return {
+            rootRunId: prepared.continuation.rootRunId,
+            runId: prepared.runId,
+            repository: prepared.repository,
+            baseRef: prepared.baseRef,
+            headRef: prepared.headRef,
+            ...(headSha && /^[0-9a-f]{40}$/.test(headSha) ? { headSha } : {}),
+            summary: details.summary,
+            tests: details.tests,
+            tag: details.tag,
+            packages: details.packages,
+            packageRefusals: details.packageRefusals,
+            ...(details.packageAudit ? { packageAudit: details.packageAudit } : {}),
+            ...(details.restoredDependencies?.length ? { restoredDependencies: details.restoredDependencies } : {}),
+            changedLockfiles: changedPaths.filter(isLockfilePath),
+            ...(details.issue ? { issue: details.issue } : {}),
+            ...(details.issueNumber !== undefined ? { issueNumber: details.issueNumber } : {}),
+            baseline: details.description.baseline,
+        };
     }
     /**
      * Best-effort "wardby is working on this PR" signal (see VcsProvider) --
@@ -163,21 +267,27 @@ export class GitHubRemote {
             const summarySuffix = details?.summary ? `\n\n${details.summary}` : "";
             const budgetSuffix = details?.budgetSentence ? ` ${details.budgetSentence}` : "";
             const body = outcome === "succeeded"
-                ? `✅ ${label} finished.${summarySuffix}`
-                : outcome === "budget_exhausted"
-                    ? `❌ ${label} ran out of budget.${budgetSuffix}${summarySuffix}`
-                    : details?.serviceSentence
-                        ? `❌ ${label} could not start: ${details.serviceSentence}${summarySuffix}`
-                        : details?.providerSentence
-                            ? `❌ ${label} could not run: ${details.providerSentence}${summarySuffix}`
-                            : details?.protectedPathSentence
-                                ? `❌ ${label} could not open its changes: ${details.protectedPathSentence}${summarySuffix}`
-                                : `❌ ${label} failed.${summarySuffix}`;
+                ? `✅ ${label} finished.${details?.mergeSentence ? ` ${details.mergeSentence}` : ""}${details?.overrunSentence ? ` ${details.overrunSentence}` : ""}${summarySuffix}`
+                : outcome === "budget_exhausted" && details?.changesPushed
+                    ? `⚠️ ${label} ran out of budget before finishing.${budgetSuffix} ${budgetStoppedChangesSentence(details.changesPushed.pullRequestNumber
+                        ? `#${details.changesPushed.pullRequestNumber}`
+                        : "this pull request", false)}${details?.mergeSentence ? ` ${details.mergeSentence}` : ""}${summarySuffix}`
+                    : outcome === "budget_exhausted"
+                        ? `❌ ${label} ran out of budget.${budgetSuffix}${summarySuffix}`
+                        : details?.serviceSentence
+                            ? `❌ ${label} could not start: ${details.serviceSentence}${summarySuffix}`
+                            : details?.providerSentence
+                                ? `❌ ${label} could not run: ${details.providerSentence}${summarySuffix}`
+                                : details?.protectedPathSentence
+                                    ? `❌ ${label} could not open its changes: ${details.protectedPathSentence}${summarySuffix}`
+                                    : details?.conflictMarkersSentence
+                                        ? `❌ ${label} could not push its changes: ${details.conflictMarkersSentence}${summarySuffix}`
+                                        : `❌ ${label} failed.${summarySuffix}`;
             await Promise.allSettled([
                 this.options.github.updateContinuationStatusComment({ ...identity, body }),
                 this.options.github.completeContinuationCheckRun({
                     repository: workspace.repository,
-                    headSha: workspace.baseCommit,
+                    ...(workspace.baseCommit ? { headSha: workspace.baseCommit } : { headRef: workspace.headRef }),
                     runId: workspace.runId,
                     outcome: outcome === "succeeded" ? "succeeded" : "failed",
                 }),

package/dist/providers/vcs/github.d.ts

@@ -1,3 +1,8 @@
+import { type PackageAuditReport } from "../../coding/registry/audit-mode.js";
+import { RELATED_SECTION_END, RELATED_SECTION_START } from "./pr-description.js";
+import type { DescriptionBaseline, DescriptionUpdateResult, RelatedPullRequestEntry, RelatedPullRequestState, RelatedPullRequestsInput, RepositoryFileInput } from "./types.js";
+export type { DescriptionBaseline, DescriptionUpdateResult, RelatedPullRequestEntry, RelatedPullRequestState, RelatedPullRequestsInput, RepositoryFileInput, };
+export { RELATED_SECTION_END, RELATED_SECTION_START };
 export interface GitHubAppConfig {
     appId: string;
     privateKey: string;
@@ -13,6 +18,9 @@ export interface PackageReport {
     ecosystem: string;
     name: string;
     version: string;
+    /** Blocking advisories the run's packagePolicy.acceptedAdvisories waived
+     *  to serve it; listed under "Accepted advisories". */
+    acceptedAdvisories?: readonly string[];
 }
 /** One package the registry proxy refused during the run (RegistryFetch outcome "refused"). */
 export interface PackageRefusal {
@@ -32,6 +40,15 @@ export interface PullRequestInput {
     /** Deduplicated by the caller isn't required — pullRequestBody dedupes itself (ecosystem+name+version / +reason). */
     packages?: readonly PackageReport[];
     packageRefusals?: readonly PackageRefusal[];
+    /**
+     * Package audit mode (control-plane records, never model output): rendered
+     * as a [!CAUTION] banner with the packages installed outside the allowlist
+     * (and, in full mode, versions served past advisories). Kept when the
+     * packages section is dropped for size.
+     */
+    packageAudit?: PackageAuditReport;
+    /** Folders whose node_modules the dependency cache restored from a snapshot ("." for the root); control-plane data. */
+    restoredDependencies?: readonly string[];
     /** Lock files the run changed (repository paths); with refusals, the PR body warns they may be incomplete. */
     changedLockfiles?: readonly string[];
     /**
@@ -55,15 +72,57 @@ export interface PullRequestInput {
         url?: string;
         trackerName?: string;
     };
+    /**
+     * The issue in this pull request's own repository the run came from (a
+     * mention on a GitHub issue; control-plane data, never model output): the
+     * body's first visible line is `From issue #N`, the GitHub issue's form of
+     * the issue line above. It links the issue but never closes it: whether
+     * merging closes it is the agent's choice (`Resolves #N` or `Refs #N` in
+     * its summary). Used only when `issue` renders no line.
+     */
+    issueNumber?: number;
     /**
      * The request's other pull requests (control-plane rows only), rendered as
      * the marked "Related pull requests" section. Rendering failures omit it.
      */
     related?: RelatedPullRequestsInput;
+    /**
+     * The run that last wrote this description (a fix round), rendered as the
+     * hidden `<!-- wardby-latest:<runId> -->` last line. The root run marker
+     * stays first. Dropped when it isn't a safe run id.
+     */
+    latestRunId?: string;
+    /**
+     * What the packages list covers: this run (the default), or every run on
+     * the pull request (a later run's description update, whose `packages` are
+     * cumulative). Only the section title differs.
+     */
+    packagesScope?: "run" | "pull_request";
 }
 export interface PullRequestResult {
     number: number;
     url: string;
+    /**
+     * Hash (descriptionSha256) of the body in GitHub's create response. Set only
+     * when this call created the pull request; absent when it found one.
+     */
+    descriptionSha256?: string;
+}
+/**
+ * A fix round's description update. `runId` is this (latest) run; the pull
+ * request is re-found by `rootRunId`'s marker. `related` is ignored: the
+ * current body's Related block is kept verbatim.
+ */
+export interface UpdateDescriptionInput extends Omit<PullRequestInput, "runId" | "acceptReadyForReview"> {
+    rootRunId: string;
+    runId: string;
+    baseline: DescriptionBaseline;
+    /**
+     * The head commit this description describes (the run's pushed commit, or
+     * the unchanged head of a no-change round); stamped on the fallback
+     * comment so a reviewer only trusts a proposal for the head it reviews.
+     */
+    headSha?: string;
 }
 /** See VcsProvider.notifyContinuationStarted/Finished (types.ts) — these back that GitHub-specific mechanism. */
 export interface ContinuationStatusCommentInput {
@@ -82,17 +141,18 @@ export interface ContinuationCheckRunInput {
     /** Stored as the check run's external_id — the re-lookup key, so no numeric id needs to be cached anywhere. */
     runId: string;
 }
-export interface ContinuationCheckRunCompleteInput extends ContinuationCheckRunInput {
-    outcome: "succeeded" | "failed";
-}
-/** One file at one ref, read through the API without a clone. */
-export interface RepositoryFileInput {
+export interface ContinuationCheckRunCompleteInput {
     repository: string;
-    ref: string;
-    /** Repository-relative POSIX path. */
-    path: string;
-    /** Refused above this many bytes. */
-    maxBytes: number;
+    runId: string;
+    outcome: "succeeded" | "failed";
+    /** The commit the check run was created on. */
+    headSha?: string;
+    /**
+     * Used when headSha is unknown (the run's workspace is gone): the check run is
+     * looked up on the pull request's head branch, which a run that pushed nothing
+     * left at that commit.
+     */
+    headRef?: string;
 }
 export interface GitHubRepositoryAccess {
     withRepositoryToken<T>(repository: string, action: (token: string) => Promise<T>): Promise<T>;
@@ -108,6 +168,46 @@ export interface GitHubRepositoryAccess {
         baseRef: string;
         headRef: string;
     }): Promise<PullRequestResult | null>;
+    /**
+     * Whether the root run's marked open pull request is still a draft: true or
+     * false, or null when it is not open (merged, closed, or gone). Optional:
+     * without it a caller treats the draft state as unknown.
+     */
+    openPullRequestDraft?(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+    }): Promise<boolean | null>;
+    /**
+     * The current base branch of the root run's marked open pull request (it
+     * changes when someone retargets the PR), or null when the PR is not open or
+     * its head or base is in another repository (a fork). Optional: without it,
+     * continuations are not brought up to date with their target branch.
+     */
+    openPullRequestBase?(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+    }): Promise<{
+        number: number;
+        baseRef: string;
+    } | null>;
+    /**
+     * Rewrites the root run's open pull request description for a fix round,
+     * or, when a person edited it since wardby last wrote it, upserts a comment
+     * carrying the proposed description instead. Never throws. Optional:
+     * without it, descriptions are not updated after the first run.
+     */
+    updatePullRequestDescription?(input: UpdateDescriptionInput): Promise<DescriptionUpdateResult>;
+    /**
+     * Before a fix round's push: when wardby can't write the description
+     * directly, writes (or updates) the fallback comment stamped with the head
+     * about to be pushed, so it already exists when the push starts a review.
+     * True when it wrote one. Never throws. Optional.
+     */
+    proposeDescriptionComment?(input: UpdateDescriptionInput): Promise<boolean>;
     /** Creates the status comment if none exists yet for this run, else updates it. */
     upsertContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
     /** Updates the status comment if one already exists for this run; a no-op otherwise (never creates). */
@@ -124,48 +224,19 @@ export interface GitHubRepositoryAccess {
     readFileAtRef?(input: RepositoryFileInput): Promise<string | null>;
 }
 type Fetch = typeof globalThis.fetch;
-/** Accepts bounded opaque installation tokens without allowing control characters. */
-export declare function isSafeGitHubInstallationToken(value: unknown): value is string;
 /**
  * Same shape as ISSUE_KEY (issue-tracker/types.ts); duplicated so the VCS layer
  * stays free of issue-tracker imports (a test keeps the two in step). The
  * executor validates with the shared one.
  */
 export declare const PR_ISSUE_KEY: RegExp;
+/** Same shape as GITHUB_ISSUE_KEY (issue-tracker/types.ts), duplicated likewise. Only the Related section shows one. */
+export declare const PR_GITHUB_ISSUE_KEY: RegExp;
 export declare function pullRequestTitle(input: PullRequestInput): string;
-export declare const RELATED_SECTION_START = "<!-- wardby-related:start -->";
-export declare const RELATED_SECTION_END = "<!-- wardby-related:end -->";
 /** At most this many pull requests are listed; the rest are counted. */
 export declare const MAX_RELATED_PULL_REQUESTS = 20;
 /** GitHub rejects a pull request body longer than this. */
 export declare const MAX_PULL_REQUEST_BODY_CHARS = 65536;
-export type RelatedPullRequestState = "open" | "draft" | "merged" | "closed";
-/** One pull request of the request's set, from stored control-plane rows only. */
-export interface RelatedPullRequestEntry {
-    repository: string;
-    /** Absent only for `self` while the pull request is being created. */
-    number?: number;
-    /** Live state; absent when unknown (at creation). */
-    state?: RelatedPullRequestState;
-    /** The pull request whose description this section is in. */
-    self?: boolean;
-    /**
-     * Step in the delegating agent's declared merge order (1-99), from
-     * CodingRun.mergeOrder; absent = the delegating agent set no order
-     * (an open entry is listed under "Not ordered:" when any other entry,
-     * open or done, has one).
-     */
-    mergeOrder?: number;
-}
-export interface RelatedPullRequestsInput {
-    /** In merge order: by mergeOrder when set, else the order the request's coding runs were dispatched. */
-    entries: readonly RelatedPullRequestEntry[];
-    issue?: {
-        key: string;
-        url?: string;
-        trackerName?: string;
-    };
-}
 /**
  * The "Related pull requests" block, markers included, built only from
  * stored rows (never agent text). Open (and draft, and not-yet-known) pull
@@ -204,8 +275,15 @@ export declare function isLockfilePath(path: string): boolean;
  */
 /** Rendered verbatim in refusalWarning's first line, and used to locate it in tests. */
 export declare const DEPENDENCY_INSTALL_INCOMPLETE = "Dependency install incomplete.";
-/** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
-export declare function pullRequestBody(input: PullRequestInput): string;
+/**
+ * The pull request body, within GitHub's MAX_PULL_REQUEST_BODY_CHARS. When it
+ * would be longer, the informational Packages section goes first; if that is
+ * not enough, the agent's summary is truncated to fit (fitSummary keeps its
+ * closing-keyword line). The other sections are bounded and stay whole.
+ */
+export declare function pullRequestBody(input: PullRequestInput, options?: {
+    omitPackages?: boolean;
+}): string;
 export declare class GitHubAppClient implements GitHubRepositoryAccess {
     private readonly config;
     private readonly fetchImpl;
@@ -276,6 +354,59 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
         baseRef: string;
         headRef: string;
     }): Promise<PullRequestResult | null>;
+    /** See GitHubRepositoryAccess.openPullRequestDraft: GitHub's own `draft` flag on the marked open PR. */
+    openPullRequestDraft(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+    }): Promise<boolean | null>;
+    /** See GitHubRepositoryAccess.openPullRequestBase: the marked open PR's current base, same repository only. */
+    openPullRequestBase(input: {
+        runId: string;
+        repository: string;
+        baseRef: string;
+        headRef: string;
+    }): Promise<{
+        number: number;
+        baseRef: string;
+    } | null>;
+    /**
+     * A fix round's description update (see GitHubRepositoryAccess). One
+     * repository token; every failure becomes `skipped:error`.
+     */
+    updatePullRequestDescription(input: UpdateDescriptionInput): Promise<DescriptionUpdateResult>;
+    /** See GitHubRepositoryAccess.proposeDescriptionComment. */
+    proposeDescriptionComment(input: UpdateDescriptionInput): Promise<boolean>;
+    /** The validated repository and refs; throws unless this is wardby's own pull request branch. */
+    private descriptionTarget;
+    /**
+     * The open pull request, the description this run proposes, and whether
+     * wardby may write it directly: it is unedited (recorded or rebuilt hash),
+     * or a person copied wardby's latest proposal in (taken back). Null when
+     * the pull request isn't open. `comments` is set when it was read.
+     */
+    private descriptionState;
+    /**
+     * The rebuilt description: the generated sections from this run with
+     * `summary` as the agent text, the latest-run marker last, and the current
+     * body's Related block re-inserted verbatim. `proposed` drops the Packages
+     * section when `full` exceeds GitHub's limit, and is undefined when it still
+     * would.
+     */
+    private proposedDescription;
+    /**
+     * Creates the pull request's one description comment, or edits the newest
+     * one this App wrote (unchanged text is not re-sent); older duplicates are
+     * rewritten to point at it. A comment anyone else wrote is never edited.
+     */
+    private upsertDescriptionComment;
+    /** Once a run applied its description, a pending proposal in the description comment is marked applied. */
+    private markDescriptionCommentApplied;
+    /** Rewrites duplicate description comments to a pointer at the one in use. */
+    private supersedeDescriptionComments;
+    /** The description comments this App wrote (see findDescriptionComments; the reviewer reads them the same way). */
+    private findDescriptionComments;
     private appJwt;
     private mintRepositoryToken;
     /**
@@ -289,8 +420,17 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
     private mintScopedToken;
     private revokeToken;
     private findPullRequest;
+    /**
+     * findPullRequest, plus the matched pull request's raw body and payload. Not
+     * filtered by base: a person may retarget the PR, and the head branch plus the
+     * run marker already identify it. When several open PRs match, the one on
+     * `baseRef` wins.
+     */
+    private findMarkedPullRequest;
     private parsePullRequest;
     private findStatusComment;
+    /** The first comment on the pull request (first page) whose body `matches`. */
+    private findMarkedComment;
     private findCheckRun;
     /** Public for the code-review host, which issues its own REST calls with tokens minted here. */
     requestJson(path: string, bearer: string, init?: RequestInit, expectedStatuses?: number[]): Promise<Response>;
@@ -300,4 +440,3 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
      */
     graphql(bearer: string, query: string, variables: Record<string, unknown>): Promise<Record<string, unknown>>;
 }
-export {};