canopycms 0.12.0 → 0.13.0

package/dist/api/admin.d.ts

@@ -91,10 +91,10 @@ declare const listAdminTasksParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    status: "failed" | "pending" | "corrupt" | "processing" | "completed";
+    status: "failed" | "pending" | "processing" | "completed" | "corrupt";
     limit?: number | undefined;
 }, {
-    status: "failed" | "pending" | "corrupt" | "processing" | "completed";
+    status: "failed" | "pending" | "processing" | "completed" | "corrupt";
     limit?: number | undefined;
 }>;
 export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
@@ -168,10 +168,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
         limit: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        status: "failed" | "pending" | "corrupt" | "processing" | "completed";
+        status: "failed" | "pending" | "processing" | "completed" | "corrupt";
         limit?: number | undefined;
     }, {
-        status: "failed" | "pending" | "corrupt" | "processing" | "completed";
+        status: "failed" | "pending" | "processing" | "completed" | "corrupt";
         limit?: number | undefined;
     }>, undefined, AdminTasksResponse>;
     readonly retryTask: import("./route-builder.js").RouteDefinition<z.ZodObject<{

package/dist/api/branch-review.d.ts

@@ -1,9 +1,17 @@
 import { z } from 'zod';
 import { type BranchListItemResponse } from './branch.js';
-export interface RequestChangesBody {
+/** What a verdict carries besides the branch: the commit the reviewer's page showed. */
+interface ReviewedHead {
+    /** The listing's `headSha` (api/branch.ts) the page was showing. */
+    headSha?: string;
+}
+export interface RequestChangesBody extends ReviewedHead {
     /** Saved as a branch comment; trimmed before its length is checked, and ignored when empty. */
     note?: string;
 }
+export type ApproveBody = ReviewedHead;
+/** @internal Exported for tests. */
+export declare const BRANCH_MOVED_ERROR = "This branch changed since you opened it. Review the latest changes.";
 export declare const requestChanges: import("./route-builder.js").RouteDefinition<z.ZodObject<{
     branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
 }, "strip", z.ZodTypeAny, {
@@ -16,9 +24,12 @@ export declare const requestChanges: import("./route-builder.js").RouteDefinitio
     };
 }>, z.ZodOptional<z.ZodObject<{
     note: z.ZodOptional<z.ZodString>;
+    headSha: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    headSha?: string | undefined;
     note?: string | undefined;
 }, {
+    headSha?: string | undefined;
     note?: string | undefined;
 }>>, BranchListItemResponse>;
 export declare const approveBranch: import("./route-builder.js").RouteDefinition<z.ZodObject<{
@@ -31,4 +42,11 @@ export declare const approveBranch: import("./route-builder.js").RouteDefinition
     branch: string & {
         readonly __brand: "BranchName";
     };
-}>, undefined, BranchListItemResponse>;
+}>, z.ZodOptional<z.ZodObject<{
+    headSha: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    headSha?: string | undefined;
+}, {
+    headSha?: string | undefined;
+}>>, BranchListItemResponse>;
+export {};

package/dist/api/branch-review.js

@@ -6,14 +6,73 @@ import { defineEndpoint } from './route-builder.js';
 import { syncConvertToDraft } from './github-sync.js';
 import { syncPrComments } from './pr-comment-sync.js';
 import { CommentStore } from '../comment-store.js';
+import { assertNoOpenConflicts, OpenMergeConflictsError } from '../merge-conflicts.js';
+import { ContentWriteLockBusyError, withContentWriteLock } from '../utils/content-write-lock.js';
 import { getErrorMessage } from '../utils/error.js';
 import { REQUEST_CHANGES_NOTE_MAX_LENGTH } from '../authorization/review-role.js';
 import { getBranchProtection, isAdmin } from '../authorization/index.js';
 import { sanitizeDisplayName } from '../submission-attribution.js';
-/** Optional on the wire: a bodiless request means no note. */
+const FULL_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/** Optional on the wire, so a request without one gets {@link BRANCH_MOVED_ERROR}, not a 400. */
+const headShaSchema = z.string().regex(FULL_SHA).optional();
 const requestChangesBodySchema = z
-    .object({ note: z.string().trim().max(REQUEST_CHANGES_NOTE_MAX_LENGTH).optional() })
+    .object({
+    note: z.string().trim().max(REQUEST_CHANGES_NOTE_MAX_LENGTH).optional(),
+    headSha: headShaSchema,
+})
     .optional();
+const approveBodySchema = z.object({ headSha: headShaSchema }).optional();
+/** @internal Exported for tests. */
+export const BRANCH_MOVED_ERROR = 'This branch changed since you opened it. Review the latest changes.';
+const branchMoved = {
+    ok: false,
+    status: 409,
+    code: 'BRANCH_MOVED',
+    error: BRANCH_MOVED_ERROR,
+};
+class BranchMovedError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'BranchMovedError';
+    }
+}
+class HeadUnreadableError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'HeadUnreadableError';
+    }
+}
+const headUnreadable = {
+    ok: false,
+    status: 503,
+    error: "Couldn't read this branch right now. Try again in a moment.",
+};
+/**
+ * Throws unless the clone's HEAD is `sent`, the commit the reviewer saw, and returns it. A request
+ * naming none, from a page loaded before the editor sent one, is refused: what it showed is
+ * unknown. Called under the content-write lock: a submit and the worker move HEAD only while
+ * holding it (docs/concurrency.md, "Who takes it"), so the head checked is the one the verdict is
+ * written against.
+ */
+const assertReviewedHead = async (ctx, { branch, branchRoot }, sent) => {
+    if (!sent)
+        throw new BranchMovedError();
+    let head;
+    try {
+        const git = ctx.services.createGitManagerFor(branchRoot, { baseBranch: branch.baseBranch });
+        head = await git.headSha();
+        // A git that exits quietly answers nothing, which is no head at all.
+        if (!FULL_SHA.test(head))
+            throw new Error(`no commit in its answer (${head.length} chars)`);
+    }
+    catch (err) {
+        console.error(`CanopyCMS: Could not read the head of ${branch.name}:`, getErrorMessage(err));
+        throw new HeadUnreadableError();
+    }
+    if (head !== sent)
+        throw new BranchMovedError();
+    return sent;
+};
 const NOTE_NOT_SAVED_WARNING = "Changes were requested, but your note couldn't be saved.";
 /**
  * The 409 for a branch that left review before this request arrived, because the reviewer's page
@@ -41,38 +100,62 @@ const approveConflict = (status) => ({
  * The verdict `user` gives. The reviewer guard admits only authenticated users, and the record is
  * always written, so a new verdict replaces whatever the last one left.
  */
-const reviewBy = (user, state) => ({
+const reviewBy = (user, state, commit) => ({
     state,
     by: {
         userId: user.userId,
         name: user.type === 'authenticated' ? sanitizeDisplayName(user.name) : undefined,
     },
     at: new Date().toISOString(),
+    commit,
 });
 const requestChangesHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
     if (!canRequestChangesFrom(branchContext.branch.status)) {
         return requestChangesConflict(branchContext.branch.status);
     }
-    await syncConvertToDraft(ctx, branchContext);
+    const headSha = body?.headSha;
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     // The status the guard read can be stale by now, so the save checks the status on disk, in the
-    // same step that writes. A branch that left review meanwhile is refused, and the draft
-    // conversion above is left as it is: withdraw converts the pull request to a draft too, and a
-    // merged one cannot be converted.
+    // same step that writes, and the head under the lock with it. A branch that left review or moved
+    // meanwhile is refused before the pull request is touched.
     let found;
-    const updated = await meta.saveIf({
-        branch: {
-            name: branchContext.branch.name,
-            status: 'editing',
-            review: reviewBy(req.user, 'changes-requested'),
-        },
-    }, (existing) => {
-        found = existing?.branch.status;
-        return canRequestChangesFrom(found);
-    });
+    let updated;
+    try {
+        updated = await withContentWriteLock(branchContext.branchRoot, async () => {
+            const commit = await assertReviewedHead(ctx, branchContext, headSha);
+            return meta.saveIf({
+                branch: {
+                    name: branchContext.branch.name,
+                    status: 'editing',
+                    review: reviewBy(req.user, 'changes-requested', commit),
+                },
+            }, (existing) => {
+                found = existing?.branch.status;
+                return canRequestChangesFrom(found);
+            });
+        });
+    }
+    catch (err) {
+        if (err instanceof BranchMovedError)
+            return branchMoved;
+        if (err instanceof HeadUnreadableError)
+            return headUnreadable;
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? "This branch is being synced, so changes weren't requested. Try again in a moment."
+                    : 'This branch was being synced while changes were requested, so the request may not have been recorded. Refresh to check.',
+            };
+        }
+        throw err;
+    }
     if (!updated)
         return requestChangesConflict(found);
+    // Best-effort: syncConvertToDraft only logs a failure.
+    await syncConvertToDraft(ctx, { ...branchContext, branch: updated.branch });
     // The note is written after the status change so a failed write never blocks the branch from
     // returning to editing; the caller is warned instead.
     const note = body?.note;
@@ -104,8 +187,9 @@ const requestChangesHandler = async (gc, ctx, req, _params, body) => {
         },
     };
 };
-const approveBranchHandler = async (gc, ctx, req, _params) => {
+const approveBranchHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
+    const headSha = body?.headSha;
     // Approve is a CanopyCMS status only. The CMS authors its pull requests and GitHub refuses
     // an author's approval review, so nothing is sent to GitHub.
     if (branchContext.branch.createdBy === req.user.userId) {
@@ -130,23 +214,58 @@ const approveBranchHandler = async (gc, ctx, req, _params) => {
         };
     }
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
-    // As for request changes, the status on disk decides, in the step that writes. So does an
-    // unfinished submit: what's approved may not be what the pull request holds.
+    // As for request changes, the status on disk and the head decide, in the step that writes. So
+    // does an unfinished submit: what's approved may not be what the pull request holds. So do
+    // conflicts: a merge of GitHub's commits can record some on a branch in review, under the
+    // content-write lock held here, so none lands between the check and the write.
     let found;
     let unfinished = false;
     let notQueued = false;
-    const updated = await meta.saveIf({
-        branch: {
-            name: branchContext.branch.name,
-            status: 'approved',
-            review: reviewBy(req.user, 'approved'),
-        },
-    }, (existing) => {
-        found = existing?.branch.status;
-        unfinished = existing?.branch.submitUnfinished === true;
-        notQueued = existing?.branch.submitNotQueued === true;
-        return found === 'submitted' && !unfinished;
-    });
+    let updated;
+    try {
+        updated = await withContentWriteLock(branchContext.branchRoot, async () => {
+            const commit = await assertReviewedHead(ctx, branchContext, headSha);
+            await assertNoOpenConflicts(branchContext.branchRoot);
+            return meta.saveIf({
+                branch: {
+                    name: branchContext.branch.name,
+                    status: 'approved',
+                    review: reviewBy(req.user, 'approved', commit),
+                },
+            }, (existing) => {
+                found = existing?.branch.status;
+                unfinished = existing?.branch.submitUnfinished === true;
+                notQueued = existing?.branch.submitNotQueued === true;
+                return found === 'submitted' && !unfinished;
+            });
+        });
+    }
+    catch (err) {
+        if (err instanceof BranchMovedError)
+            return branchMoved;
+        if (err instanceof HeadUnreadableError)
+            return headUnreadable;
+        if (err instanceof OpenMergeConflictsError) {
+            return {
+                ok: false,
+                status: 409,
+                code: 'OPEN_CONFLICTS',
+                error: err.count === null
+                    ? err.message
+                    : `${err.message} Use "Request changes" so its editor can choose what to keep.`,
+            };
+        }
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? 'This branch is being synced, or a save is in flight, so it was not approved. Try again in a moment.'
+                    : 'This branch was being synced while it was approved, so the approval may not have been recorded. Refresh to check.',
+            };
+        }
+        throw err;
+    }
     if (unfinished && found === 'submitted') {
         return {
             ok: false,
@@ -199,6 +318,8 @@ export const approveBranch = defineEndpoint({
     method: 'POST',
     path: '/:branch/approve',
     params: branchParamSchema,
+    body: approveBodySchema,
+    bodyType: 'ApproveBody',
     responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {

package/dist/api/branch-status.d.ts

@@ -3,7 +3,8 @@ import type { ApiResponse } from './types.js';
 import { type BranchListItem, type BranchListItemResponse } from './branch.js';
 import type { StampedEntry } from '../stamp-on-publish.js';
 export type { BranchMergeResponse } from './branch-merge.js';
-export type { RequestChangesBody } from './branch-review.js';
+export type { ApproveBody, RequestChangesBody } from './branch-review.js';
+export type { UpdateFromBaseResponse } from './branch-update-from-base.js';
 /**
  * A submit's answer: the branch, plus the entries the submit stamped (stamp-on-publish.ts) when
  * there were any, so the editor can carry its open forms and drafts onto their new versions.
@@ -74,6 +75,17 @@ export declare const WORKFLOW_ROUTES: {
             readonly __brand: "BranchName";
         };
     }>, undefined, BranchListItemResponse>;
+    readonly updateFromBase: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+    }>, undefined, import("./branch-update-from-base.js").UpdateFromBaseResponse>;
     readonly requestChanges: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {
@@ -86,9 +98,12 @@ export declare const WORKFLOW_ROUTES: {
         };
     }>, z.ZodOptional<z.ZodObject<{
         note: z.ZodOptional<z.ZodString>;
+        headSha: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
+        headSha?: string | undefined;
         note?: string | undefined;
     }, {
+        headSha?: string | undefined;
         note?: string | undefined;
     }>>, BranchListItemResponse>;
     readonly approve: import("./route-builder.js").RouteDefinition<z.ZodObject<{
@@ -101,7 +116,13 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, BranchListItemResponse>;
+    }>, z.ZodOptional<z.ZodObject<{
+        headSha: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        headSha?: string | undefined;
+    }, {
+        headSha?: string | undefined;
+    }>>, BranchListItemResponse>;
     readonly markMerged: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/branch-status.js

@@ -3,6 +3,7 @@ import { branchParamSchema } from './validators.js';
 import { toBranchListItem } from './branch.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { withdrawBranch } from './branch-withdraw.js';
+import { updateFromBase } from './branch-update-from-base.js';
 import { requestChanges, approveBranch } from './branch-review.js';
 import { markAsMerged } from './branch-merge.js';
 import { ARCHIVE_BRANCH_ROUTES } from './archived-branches.js';
@@ -14,6 +15,7 @@ import { isNonFastForwardRejection } from '../utils/git.js';
 import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
 import { NothingToSubmitError } from '../services.js';
+import { OpenMergeConflictsError } from '../merge-conflicts.js';
 import { baseBranchOf } from '../utils/base-branch.js';
 import { shortNameOf } from '../branch-param.js';
 import { resolveEditorUrl } from '../editor-url.js';
@@ -118,6 +120,16 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
         if (err instanceof NothingToSubmitError) {
             return { ok: false, status: 400, error: err.message };
         }
+        if (err instanceof OpenMergeConflictsError) {
+            return {
+                ok: false,
+                status: 409,
+                code: 'OPEN_CONFLICTS',
+                error: err.count === null
+                    ? err.message
+                    : `${err.message} Choose what to keep in "Show changes", then submit again.`,
+            };
+        }
         const shortName = shortNameOf(ctx.services.config, branchContext.branch.name);
         // Retriable either way: a resubmit commits nothing new and pushes only
         // what has not reached the remote.
@@ -196,8 +208,9 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
             status: 'submitted',
             submittedAt,
             ...pushed,
-            // Only a request-derived URL: config.editorUrl is read live by every later re-render.
-            ...(editorUrl && !ctx.services.config.editorUrl ? { editorUrl } : {}),
+            // config.editorUrl, when set, still wins in every later re-render here; the worker, which
+            // has no config, links the conflicts status with this.
+            ...(editorUrl ? { editorUrl } : {}),
             syncFailureReason: prResult.syncFailureReason,
             pullRequestUrl: prResult.prUrl ?? branchContext.branch.pullRequestUrl,
             pullRequestNumber: prResult.prNumber ?? branchContext.branch.pullRequestNumber,
@@ -275,6 +288,7 @@ export const WORKFLOW_ROUTES = {
     getStatus: getBranchStatus,
     submit: submitBranchForMerge,
     withdraw: withdrawBranch,
+    updateFromBase,
     requestChanges: requestChanges,
     approve: approveBranch,
     markMerged: markAsMerged,

package/dist/api/branch-update-from-base.d.ts

@@ -0,0 +1,23 @@
+import type { z } from 'zod';
+import type { ApiResponse } from './types.js';
+import { type BranchListItem } from './branch.js';
+/**
+ * A request for the latest changes: when it was made, which the editor waits on until the
+ * branch's `lastBaseUpdate.at` reaches it, and the branch as it stands with the request recorded.
+ */
+export type UpdateFromBaseResponse = ApiResponse<{
+    requestedAt: string;
+    branch: BranchListItem;
+}>;
+/** Get the latest changes: bring the base branch into this one at the worker's next chance. */
+export declare const updateFromBase: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+    branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+}, "strip", z.ZodTypeAny, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+}, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+}>, undefined, UpdateFromBaseResponse>;