canopycms 0.5.0 → 0.7.0

package/dist/editor/hooks/useBranchManager.js

@@ -20,14 +20,50 @@ import { isNonApiResponse } from '../../api/client.js';
 import { isGatewayFailure, isUnanswered, UnansweredError } from '../unanswered.js';
 import { describeUnsaved } from './useBranchActions.js';
 import { writeEditorUrl } from './editor-history.js';
+import { approveMessage, NoteNotSavedMessage, RequestChangesForm, } from '../components/ReviewDialogs.js';
 const BRANCHES_LOAD_FAILED_TOAST_ID = 'canopy-branches-load-failed';
 const BRANCH_OUTCOME_UNKNOWN_TOAST_ID = 'canopy-branch-outcome-unknown';
-/** The error a refused branch action throws; a gateway's 5xx says nothing of whether it ran. */
-function actionError(result, fallback) {
-    return isGatewayFailure(result) ? new UnansweredError() : new Error(result.error || fallback);
+/** The API's 409: the branch is no longer in the state the action needs, so a retry cannot pass. */
+class StaleStatusError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'StaleStatusError';
+    }
+}
+/** An answer that refused the action, with its HTTP status: a 4xx is a refusal no retry passes. */
+class RefusedError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'RefusedError';
+    }
+}
+/**
+ * The error a refused branch action throws; a gateway's 5xx says nothing of whether it ran.
+ * With `staleIsConflict`, the API's 409 is a `StaleStatusError`.
+ */
+function actionError(result, fallback, staleIsConflict = false) {
+    if (isGatewayFailure(result))
+        return new UnansweredError();
+    const message = result.error || fallback;
+    if (result.ok)
+        return new Error(message);
+    return staleIsConflict && result.status === 409 && !isNonApiResponse(result)
+        ? new StaleStatusError(message)
+        : new RefusedError(message, result.status);
 }
+/** Whether a branch's status still lets the reviewer act: Approve needs submitted. */
+const acceptsReview = (status, kind) => kind === 'approve' ? status === 'submitted' : status === 'submitted' || status === 'approved';
+/** The line for a branch the reviewer's page still showed in review after it left. */
+const leftReviewMessage = (status, kind) => status === 'editing'
+    ? "This branch is no longer in review: it's back with its editor."
+    : status === 'approved' && kind === 'approve'
+        ? 'This branch is already approved.'
+        : `This branch is ${status}, so ${kind === 'approve' ? "it can't be approved" : "changes can't be requested"}.`;
 /** @internal Exported for tests. */
-export const branchActionOutcomeUnknown = (action) => `${action} may have gone through even though the server didn't answer. Check the branch's status before trying again.`;
+export const branchActionOutcomeUnknown = (action, check = "Check the branch's status before trying again.") => `${action} may have gone through even though the server didn't answer. ${check}`;
+/** Where to look after a Request changes nobody answered: the status, and the note it carried. */
+const REQUEST_CHANGES_CHECK = `Check the branch's status and its comments in "Comments".`;
 /**
  * Wire a confirm modal's exits so exactly ONE of {confirmed, dismissed} runs,
  * whichever happens first.
@@ -119,13 +155,32 @@ const showWithdrawConfirmation = (branchName, pr, onConfirm, onDismiss, returnFo
         ...focusReturnProps(returnFocusTo),
     });
 };
-const showRequestChangesConfirmation = (branchName, onConfirm, onDismiss) => {
+const showApproveConfirmation = (branchName, pr, onConfirm, onDismiss, returnFocusTo) => {
+    openConfirm({
+        title: EDITOR_ACTIONS.approve,
+        children: _jsx(Text, { size: "sm", children: approveMessage(branchName, !!pr.pullRequestNumber) }),
+        labels: { confirm: EDITOR_ACTIONS.approve, cancel: 'Cancel' },
+        confirmProps: { color: 'brand', 'data-testid': 'confirm-approve-branch' },
+        ...confirmModalHandlers(onConfirm, onDismiss),
+        ...focusReturnProps(returnFocusTo),
+    });
+};
+/**
+ * `onConfirm` receives the note as typed, which the dialog starts with `initialNote` and reports
+ * through `onNoteChange` as it changes, so a draft outlives the dialog.
+ */
+const showRequestChangesConfirmation = (branchName, pr, initialNote, onNoteChange, onConfirm, onDismiss, returnFocusTo) => {
+    let note = initialNote;
     openConfirm({
         title: EDITOR_ACTIONS.requestChanges,
-        children: (_jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Send "${branchName}" back to its editor?\n\nThis will:\n• Change the branch status back to "editing"\n• Let its editor change it and submit again` })),
+        children: (_jsx(RequestChangesForm, { branchName: branchName, hasPullRequest: !!pr.pullRequestNumber, initialNote: initialNote, onNoteChange: (value) => {
+                note = value;
+                onNoteChange(value);
+            } })),
         labels: { confirm: EDITOR_ACTIONS.requestChanges, cancel: 'Cancel' },
         confirmProps: { color: 'red', 'data-testid': 'confirm-request-changes' },
-        ...confirmModalHandlers(onConfirm, onDismiss),
+        ...confirmModalHandlers(() => onConfirm(note), onDismiss),
+        ...focusReturnProps(returnFocusTo),
     });
 };
 /**
@@ -392,24 +447,118 @@ export function useBranchManager(options) {
     };
     // A workflow action that got no answer may have gone through, so the list reloads to show
     // where the branch stands rather than inviting a blind retry.
-    const showOutcomeUnknown = (action) => {
+    const showOutcomeUnknown = (action, check) => {
         notifications.hide(BRANCH_OUTCOME_UNKNOWN_TOAST_ID);
         notifications.show({
             id: BRANCH_OUTCOME_UNKNOWN_TOAST_ID,
-            message: branchActionOutcomeUnknown(action),
+            message: branchActionOutcomeUnknown(action, check),
             color: 'yellow',
             autoClose: false,
             withCloseButton: true,
         });
     };
-    const reportActionFailure = async (err, fallback, action) => {
+    const reportActionFailure = async (err, fallback, action, follow = {}) => {
         if (isUnanswered(err)) {
-            showOutcomeUnknown(action);
-            await loadBranches();
+            showOutcomeUnknown(action, follow.check);
+            const fresh = await reloadBranches();
+            follow.afterUnanswered?.(fresh);
             return;
         }
         notifications.show({ message: err instanceof Error ? err.message : fallback, color: 'red' });
     };
+    // A note typed in the Request changes dialog, by branch, until a request carries it or the
+    // branch leaves review.
+    const noteDrafts = useRef(new Map());
+    // The stale-status toasts that carry a note and stay up, by id: a plain one never replaces them.
+    const stickyStaleToasts = useRef(new Set());
+    /**
+     * A review action found its branch out of review, or the page already knew it was. A warning,
+     * not an error: nothing is lost yet. A typed note is shown to copy, so it stays up until
+     * dismissed, and a later toast without a note leaves it be. The note's draft is the caller's to
+     * judge: Request changes still takes a branch that is merely approved.
+     */
+    const showLeftReview = (branch, message, note) => {
+        const id = `canopy-review-stale-${branch}`;
+        if (!note && stickyStaleToasts.current.has(id))
+            return;
+        notifications.hide(id);
+        stickyStaleToasts.current.delete(id);
+        if (note)
+            stickyStaleToasts.current.add(id);
+        notifications.show({
+            id,
+            message: note ? (_jsx(NoteNotSavedMessage, { message: message, note: note, hint: "Copy it to keep it." })) : (message),
+            color: 'yellow',
+            withCloseButton: true,
+            ...(note ? { autoClose: false, onClose: () => stickyStaleToasts.current.delete(id) } : {}),
+        });
+    };
+    /** Forgets a branch's draft when the listing shows it out of review. */
+    const dropDraftsOutOfReview = (branches) => {
+        for (const { name, status } of branches) {
+            if (!acceptsReview(status, 'request-changes'))
+                noteDrafts.current.delete(name);
+        }
+    };
+    const reviewFailureId = (kind, branch) => `canopy-${kind}-failed-${branch}`;
+    /**
+     * Why an Approve or Request changes failed. Retry only on an API 5xx, 408, 429 or unsent request;
+     * a timeout or gateway 5xx may have landed, so it reloads and says what to check. Other 4xx: a
+     * plain message and a reload. A 409 means the branch left review (see `showLeftReview`).
+     */
+    const reportReviewFailure = async (err, kind, branch, details) => {
+        if (err instanceof StaleStatusError) {
+            showLeftReview(branch, err.message, details.note);
+            // What the branch is now decides whether a Request changes note is still wanted.
+            const fresh = await reloadBranches();
+            if (fresh)
+                dropDraftsOutOfReview(fresh.branches);
+            return;
+        }
+        if (isUnanswered(err)) {
+            await reportActionFailure(err, details.fallback, details.label, details);
+            return;
+        }
+        const message = err instanceof Error ? err.message : details.fallback;
+        const id = reviewFailureId(kind, branch);
+        notifications.hide(id);
+        // A 4xx is a refusal no retry passes, except for asking again later (408, 429).
+        if (err instanceof RefusedError &&
+            err.status < 500 &&
+            err.status !== 408 &&
+            err.status !== 429) {
+            notifications.show({
+                id,
+                message: details.note ? (_jsx(NoteNotSavedMessage, { message: message, note: details.note, hint: "Copy it to keep it." })) : (message),
+                color: 'red',
+                ...(details.note ? { autoClose: false } : {}),
+            });
+            await loadBranches();
+            return;
+        }
+        notifications.show({
+            id,
+            message: (_jsx(RetryToastMessage, { message: message, onRetry: () => {
+                    notifications.hide(id);
+                    void (async () => {
+                        // The page may be stale by now: a branch that left review has nothing to retry.
+                        // The listing is fetched first, so the decision is made on where the branch is now.
+                        const fresh = await reloadBranches();
+                        const status = (fresh?.branches ?? latest.current.branches).find((b) => b.name === branch)?.status;
+                        if (status !== undefined && !acceptsReview(status, kind)) {
+                            showLeftReview(branch, leftReviewMessage(status, kind), noteDrafts.current.get(branch));
+                            // An approved branch still takes Request changes, so its draft stays.
+                            if (!acceptsReview(status, 'request-changes'))
+                                noteDrafts.current.delete(branch);
+                            return;
+                        }
+                        details.retry();
+                    })();
+                } })),
+            color: 'red',
+            autoClose: false,
+        });
+    };
     const handleSubmit = (requested, returnFocusTo) => {
         const branchNameToSubmit = listedName(requested);
         return singleFlight('submit', branchNameToSubmit, async () => {
@@ -440,9 +589,9 @@ export function useBranchManager(options) {
                     }
                     options.setBusy(true);
                     try {
-                        const result = await apiClient.workflow.submit({
-                            branch: branchNameToSubmit,
-                        });
+                        const result = await apiClient.workflow.submit({ branch: branchNameToSubmit }, 
+                        // The PR body links back here; the server checks the host (editor-url.ts).
+                        { editorUrl: `${window.location.origin}${window.location.pathname}` });
                         if (!result.ok)
                             throw actionError(result, 'Failed to submit branch');
                         const stamped = result.data?.stamped;
@@ -497,28 +646,93 @@ export function useBranchManager(options) {
             }, () => resolve(), returnFocusTo);
         }));
     };
-    const handleRequestChanges = (branchNameForChanges) => singleFlight('request-changes', branchNameForChanges, () => new Promise((resolve) => {
-        showRequestChangesConfirmation(branchNameForChanges, async () => {
-            options.setBusy(true);
-            try {
-                const result = await apiClient.workflow.requestChanges({
-                    branch: branchNameForChanges,
-                });
-                if (!result.ok)
-                    throw actionError(result, 'Failed to request changes');
-                notifications.show({ message: 'Changes requested', color: 'blue' });
-                updateCreatedBranch(branchNameForChanges, result.data?.branch);
-                await loadBranches();
-            }
-            catch (err) {
-                await reportActionFailure(err, 'Failed to request changes', EDITOR_ACTIONS.requestChanges);
-            }
-            finally {
-                options.setBusy(false);
-                resolve();
-            }
-        }, () => resolve());
-    }));
+    const handleApprove = (requested, returnFocusTo) => {
+        const branchNameToApprove = listedName(requested);
+        return singleFlight('approve', branchNameToApprove, () => new Promise((resolve, reject) => {
+            showApproveConfirmation(branchNameToApprove, pullRequestOf(branchNameToApprove), async () => {
+                options.setBusy(true);
+                try {
+                    const result = await apiClient.workflow.approve({
+                        branch: branchNameToApprove,
+                    });
+                    if (!result.ok)
+                        throw actionError(result, 'Failed to approve branch', true);
+                    notifications.hide(reviewFailureId('approve', branchNameToApprove));
+                    notifications.show({ message: 'Branch approved', color: 'green' });
+                    updateCreatedBranch(branchNameToApprove, result.data?.branch);
+                    await loadBranches();
+                    resolve();
+                }
+                catch (err) {
+                    await reportReviewFailure(err, 'approve', branchNameToApprove, {
+                        fallback: 'Failed to approve branch',
+                        label: `${EDITOR_ACTIONS.approve} "${branchNameToApprove}"`,
+                        retry: () => void handleApprove(branchNameToApprove, returnFocusTo).catch(() => { }),
+                    });
+                    reject(err);
+                }
+                finally {
+                    options.setBusy(false);
+                }
+            }, () => resolve(), returnFocusTo);
+        }));
+    };
+    const handleRequestChanges = (requested, returnFocusTo) => {
+        const branchNameForChanges = listedName(requested);
+        // A draft is for the review cycle it was typed in; a branch already out of review starts clean.
+        dropDraftsOutOfReview(latest.current.branches.filter((b) => b.name === branchNameForChanges));
+        return singleFlight('request-changes', branchNameForChanges, () => new Promise((resolve) => {
+            showRequestChangesConfirmation(branchNameForChanges, pullRequestOf(branchNameForChanges), noteDrafts.current.get(branchNameForChanges) ?? '', (draft) => {
+                if (draft)
+                    noteDrafts.current.set(branchNameForChanges, draft);
+                else
+                    noteDrafts.current.delete(branchNameForChanges);
+            }, async (note) => {
+                options.setBusy(true);
+                try {
+                    const result = await apiClient.workflow.requestChanges({ branch: branchNameForChanges }, { note: note.trim() || undefined });
+                    if (!result.ok)
+                        throw actionError(result, 'Failed to request changes', true);
+                    noteDrafts.current.delete(branchNameForChanges);
+                    notifications.hide(reviewFailureId('request-changes', branchNameForChanges));
+                    notifications.show({ message: 'Changes requested', color: 'blue' });
+                    // The note is saved apart from the status change, so it can fail on its own;
+                    // the warning stays up, with the note to copy, because the words are not saved.
+                    const warning = result.data?.warning;
+                    if (warning) {
+                        notifications.show({
+                            message: _jsx(NoteNotSavedMessage, { message: warning, note: note.trim() }),
+                            color: 'yellow',
+                            autoClose: false,
+                            withCloseButton: true,
+                        });
+                    }
+                    updateCreatedBranch(branchNameForChanges, result.data?.branch);
+                    await loadBranches();
+                    options.onChangesRequested?.(branchNameForChanges);
+                }
+                catch (err) {
+                    await reportReviewFailure(err, 'request-changes', branchNameForChanges, {
+                        fallback: 'Failed to request changes',
+                        label: `${EDITOR_ACTIONS.requestChanges} on "${branchNameForChanges}"`,
+                        note: note.trim() || undefined,
+                        retry: () => void handleRequestChanges(branchNameForChanges, returnFocusTo).catch(() => { }),
+                        check: REQUEST_CHANGES_CHECK,
+                        afterUnanswered: (fresh) => {
+                            // The write may have landed along with its note.
+                            options.onChangesRequested?.(branchNameForChanges);
+                            if (fresh)
+                                dropDraftsOutOfReview(fresh.branches);
+                        },
+                    });
+                }
+                finally {
+                    options.setBusy(false);
+                    resolve();
+                }
+            }, () => resolve(), returnFocusTo);
+        }));
+    };
     /** After a delete: drop it from the created-branch overlay, and leave it if it is open. */
     const leaveDeletedBranch = (deleted, fresh) => {
         forgetCreatedBranch(deleted);
@@ -612,6 +826,7 @@ export function useBranchManager(options) {
         addCreatedBranch,
         handleSubmit,
         handleWithdraw,
+        handleApprove,
         handleRequestChanges,
         handleDelete,
         handleReloadBranchData,

package/dist/editor-url.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The editor's public URL, for links written into pull request bodies, and the deep links
+ * built on it. The editor reads `?branch=` and `&entry=` (an entry's logical path) on load.
+ */
+export interface ResolveEditorUrlInput {
+    /** `config.editorUrl`, already validated by the config schema. */
+    configured?: string;
+    /** The page URL the editor client reported. */
+    claimed?: string;
+    /** The request's header getter. */
+    header?: (name: string) => string | null;
+}
+/**
+ * The editor URL for links: the configured one; else the client-reported page URL when its
+ * host is the one the request was addressed to (see requestHost); else undefined. The host
+ * check is what stops a request from naming an arbitrary site as the editor.
+ */
+export declare function resolveEditorUrl(input: ResolveEditorUrlInput): string | undefined;
+/** A link to `branch` in the editor at `editorUrl`, optionally opening the entry at `entryPath`. */
+export declare function editorDeepLink(editorUrl: string, branch: string, entryPath?: string): string;

package/dist/editor-url.js

@@ -0,0 +1,71 @@
+/**
+ * The editor's public URL, for links written into pull request bodies, and the deep links
+ * built on it. The editor reads `?branch=` and `&entry=` (an entry's logical path) on load.
+ */
+/** Longest editor URL accepted, before and after URL encoding. */
+const MAX_URL_LENGTH = 2048;
+/** The editor page URL with no query or fragment, or undefined if it is not plain http(s). */
+function editorPageUrl(raw) {
+    if (raw.length > MAX_URL_LENGTH)
+        return undefined;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return undefined;
+    if (url.username || url.password)
+        return undefined;
+    const page = `${url.origin}${url.pathname}`;
+    return page.length > MAX_URL_LENGTH ? undefined : page;
+}
+/**
+ * The host the request was addressed to: the last `x-forwarded-host` value, else `Host`. A
+ * proxy that appends puts its own value last, after any the client sent. Behind canopycms-cdk's
+ * CloudFront the Lambda's own Host is the Function URL's, and the default viewer-request
+ * function overwrites `x-forwarded-host` with the viewer's Host.
+ */
+function requestHost(header) {
+    const forwarded = header('x-forwarded-host')?.split(',').at(-1)?.trim();
+    const host = forwarded || header('host')?.trim();
+    return host || undefined;
+}
+/** `host` as `URL.host` spells it under `protocol`, or undefined if it is not a bare host[:port]. */
+function normalizeHost(host, protocol) {
+    if (/[\s/\\@?#]/.test(host))
+        return undefined;
+    try {
+        return new URL(`${protocol}//${host}`).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The editor URL for links: the configured one; else the client-reported page URL when its
+ * host is the one the request was addressed to (see requestHost); else undefined. The host
+ * check is what stops a request from naming an arbitrary site as the editor.
+ */
+export function resolveEditorUrl(input) {
+    if (input.configured)
+        return editorPageUrl(input.configured);
+    if (!input.claimed || !input.header)
+        return undefined;
+    const claimed = editorPageUrl(input.claimed);
+    const host = requestHost(input.header);
+    if (!claimed || !host)
+        return undefined;
+    const url = new URL(claimed);
+    return normalizeHost(host, url.protocol) === url.host ? claimed : undefined;
+}
+/** A link to `branch` in the editor at `editorUrl`, optionally opening the entry at `entryPath`. */
+export function editorDeepLink(editorUrl, branch, entryPath) {
+    const url = new URL(editorUrl);
+    url.searchParams.set('branch', branch);
+    if (entryPath !== undefined)
+        url.searchParams.set('entry', entryPath);
+    return url.href;
+}

package/dist/git-manager.js

@@ -1052,11 +1052,12 @@ export class GitManager {
                 sourceRoot: options.sourceRoot,
                 allowNetworkRemoteInProd: options.allowNetworkRemoteInProd,
             });
-            // A content clone skips its own checkout because checkoutFreshClone runs
-            // the one checkout this workspace needs.
+            // No clone checks out: the checkout step below is the one checkout each
+            // workspace needs (checkoutFreshClone for content; createOrphanSettingsBranch
+            // for settings, which writes only the settings files, never the base tree).
             await step('clone', () => GitManager.cloneWorkspace(remoteUrl, options.workspacePath, baseBranch, {
                 remoteName,
-                noCheckout: options.branchType === 'content',
+                noCheckout: true,
                 config: identity,
             }));
             justCloned = true;
@@ -1590,7 +1591,7 @@ export class GitManager {
             await this.createOrphanSettingsBranchInner(branchName, initialFiles);
         }
         finally {
-            // Both branches of Inner swap the working tree (checkout / checkout --orphan)
+            // Both branches of Inner swap the working tree (checkout / switch --orphan)
             await this.invalidateContentIndexes();
         }
     }
@@ -1630,8 +1631,11 @@ export class GitManager {
         // branchName is consumed as --orphan's literal argument value (like -b/-B
         // above), so it can't be reinterpreted as a flag; git's own ref-name
         // validation additionally rejects a leading-hyphen value here.
-        await this.git.raw(['checkout', '--orphan', branchName]);
-        // The orphan starts from the base branch's index. `--sparse` also removes entries outside a
+        // `switch`, not `checkout`: `checkout --orphan` keeps HEAD's tree, and on a `--no-checkout`
+        // clone (no index) writes every base file into the working tree; `switch --orphan` starts
+        // from the empty tree either way.
+        await this.git.raw(['switch', '--orphan', branchName]);
+        // A backstop for an index `switch` left behind. `--sparse` also removes entries outside a
         // sparse cone, which a plain `rm` leaves in the index, and so in the first commit.
         await this.git.raw(['rm', '-r', '-f', '-q', '--sparse', '--ignore-unmatch', '--', '.']);
         const leftover = (await this.git.raw(['ls-files'])).trim();

package/dist/github-service.d.ts

@@ -159,7 +159,7 @@ export declare class GitHubService {
         number: number;
         url: string;
     }>;
-    updatePullRequest(prNumber: number, options: Partial<Pick<PullRequestOptions, 'title' | 'body'>>): Promise<void>;
+    updatePullRequest(prNumber: number, options: Partial<Pick<PullRequestOptions, 'title' | 'body'>>, signal?: AbortSignal): Promise<void>;
     /**
      * Idempotent create-or-update, bound to this instance's octokit/owner/repo.
      * See {@link createOrUpdatePullRequest}.
@@ -177,7 +177,7 @@ export declare class GitHubService {
         number: number;
         url: string;
     }>;
-    getPullRequest(prNumber: number): Promise<PullRequestDetails>;
+    getPullRequest(prNumber: number, signal?: AbortSignal): Promise<PullRequestDetails>;
     convertToDraft(prNumber: number): Promise<void>;
     convertToReady(prNumber: number): Promise<void>;
     closePullRequest(prNumber: number): Promise<void>;

package/dist/github-service.js

@@ -258,13 +258,14 @@ export class GitHubService {
             url: response.data.html_url,
         };
     }
-    async updatePullRequest(prNumber, options) {
+    async updatePullRequest(prNumber, options, signal) {
         await this.octokit.pulls.update({
             owner: this.owner,
             repo: this.repo,
             pull_number: prNumber,
             title: options.title,
             body: options.body,
+            ...(signal ? { request: { signal } } : {}),
         });
     }
     /**
@@ -285,11 +286,12 @@ export class GitHubService {
         });
         return { number: result.number, url: result.url };
     }
-    async getPullRequest(prNumber) {
+    async getPullRequest(prNumber, signal) {
         const response = await this.octokit.pulls.get({
             owner: this.owner,
             repo: this.repo,
             pull_number: prNumber,
+            ...(signal ? { request: { signal } } : {}),
         });
         return {
             number: response.data.number,

package/dist/pr-comments.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The worker action that re-renders a PR's editor-comment summary: enqueued by
+ * api/pr-comment-sync.ts, run by worker/task-runner.ts.
+ */
+export declare const SYNC_PR_COMMENTS_ACTION = "sync-pr-comments";
+/**
+ * `body` with its comment summary re-rendered from `branchRoot`'s comments.json, or undefined
+ * when there is nothing to write: no summary block to replace, or no change.
+ */
+export declare function renderPrCommentsBody(options: {
+    branchRoot: string;
+    branch: string;
+    editorUrl?: string;
+    body: string | null | undefined;
+}): Promise<string | undefined>;
+/**
+ * The in-process lock every direct-path write of a branch's PR body holds (submit and comment
+ * sync), so neither writes back a body read before the other's write.
+ */
+export declare function prBodyLockKey(branchRoot: string): string;
+/**
+ * A submit's section with its comment block re-rendered from comments.json, for a queued submit
+ * whose block was rendered when it was queued: a comment change since then, or a sync task that
+ * ran while this one waited out a retry, would otherwise be overwritten. If comments.json cannot
+ * be read, the section keeps the block it was queued with.
+ */
+export declare function refreshCommentsBlock(options: {
+    branchRoot: string;
+    branch: string;
+    editorUrl?: string;
+    section: string;
+    warn: (message: string) => void;
+}): Promise<string>;

package/dist/pr-comments.js

@@ -0,0 +1,41 @@
+import { CommentStore } from './comment-store.js';
+import { getErrorMessage } from './utils/error.js';
+import { buildCommentsBlock, mergeCommentsBlock } from './submission-attribution.js';
+/**
+ * The worker action that re-renders a PR's editor-comment summary: enqueued by
+ * api/pr-comment-sync.ts, run by worker/task-runner.ts.
+ */
+export const SYNC_PR_COMMENTS_ACTION = 'sync-pr-comments';
+/**
+ * `body` with its comment summary re-rendered from `branchRoot`'s comments.json, or undefined
+ * when there is nothing to write: no summary block to replace, or no change.
+ */
+export async function renderPrCommentsBody(options) {
+    const threads = await new CommentStore(options.branchRoot).listThreadsStrict();
+    const next = mergeCommentsBlock(options.body, buildCommentsBlock(threads, options.branch, options.editorUrl));
+    return next === undefined || next === options.body ? undefined : next;
+}
+/**
+ * The in-process lock every direct-path write of a branch's PR body holds (submit and comment
+ * sync), so neither writes back a body read before the other's write.
+ */
+export function prBodyLockKey(branchRoot) {
+    return `pr-body:${branchRoot}`;
+}
+/**
+ * A submit's section with its comment block re-rendered from comments.json, for a queued submit
+ * whose block was rendered when it was queued: a comment change since then, or a sync task that
+ * ran while this one waited out a retry, would otherwise be overwritten. If comments.json cannot
+ * be read, the section keeps the block it was queued with.
+ */
+export async function refreshCommentsBlock(options) {
+    try {
+        const threads = await new CommentStore(options.branchRoot).listThreadsStrict();
+        const block = buildCommentsBlock(threads, options.branch, options.editorUrl);
+        return mergeCommentsBlock(options.section, block) ?? options.section;
+    }
+    catch (err) {
+        options.warn(`Could not re-read the editor comments of ${options.branch}; the PR gets the summary from submit time: ${getErrorMessage(err)}`);
+        return options.section;
+    }
+}