canopycms 0.11.1 → 0.12.1

package/dist/api/branch-entry-changes.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { ContentFormat } from '../config/index.js';
-import type { LogicalPath } from '../paths/types.js';
+import type { ContentId, LogicalPath } from '../paths/types.js';
 /** One side of an entry's change: its file as the editor reads it, references unresolved. */
 export interface EntryChangeSide {
     format: ContentFormat;
@@ -33,7 +33,7 @@ export declare const readBranchEntryChange: import("./route-builder.js").RouteDe
     /** A moved entry's path at the base. */
     from: z.ZodOptional<z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>>;
     /** The entry's content id: both sides must carry it, so a slug reused by another entry isn't it. */
-    id: z.ZodOptional<z.ZodType<import("../paths/index.js").ContentId, z.ZodTypeDef, import("../paths/index.js").ContentId>>;
+    id: z.ZodOptional<z.ZodType<ContentId, z.ZodTypeDef, ContentId>>;
 }, "strip", z.ZodTypeAny, {
     branch: string & {
         readonly __brand: "BranchName";
@@ -41,7 +41,7 @@ export declare const readBranchEntryChange: import("./route-builder.js").RouteDe
     entryPath: string & {
         readonly __brand: "LogicalPath";
     };
-    id?: import("../paths/index.js").ContentId | undefined;
+    id?: ContentId | undefined;
     from?: LogicalPath | undefined;
 }, {
     branch: string & {
@@ -50,9 +50,64 @@ export declare const readBranchEntryChange: import("./route-builder.js").RouteDe
     entryPath: string & {
         readonly __brand: "LogicalPath";
     };
-    id?: import("../paths/index.js").ContentId | undefined;
+    id?: ContentId | undefined;
     from?: LogicalPath | undefined;
 }>, undefined, BranchEntryChangeResponse>;
+declare const restoreBodySchema: z.ZodObject<{
+    /** The deleted entry's content id, which the base file must carry and the restore keeps. */
+    id: z.ZodType<ContentId, z.ZodTypeDef, ContentId>;
+}, "strip", z.ZodTypeAny, {
+    id: string & {
+        readonly __brand: "ContentId";
+    };
+}, {
+    id: string & {
+        readonly __brand: "ContentId";
+    };
+}>;
+interface RestoreEntryData {
+    logicalPath: string;
+    contentId: string;
+    /** The entry is back, but its collection's manual order couldn't be updated. */
+    warning?: string;
+}
+export type RestoreEntryResponse = ApiResponse<RestoreEntryData>;
+/**
+ * Puts back an entry deleted on the branch, as the commit the branch forked from holds it, with
+ * its content id (`ContentStore.restore`).
+ * POST /:branch/restore-entry/...entryPath
+ * @internal Exported for tests.
+ */
+export declare const restoreBranchEntry: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+    branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+    entryPath: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
+}, "strip", z.ZodTypeAny, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+    entryPath: string & {
+        readonly __brand: "LogicalPath";
+    };
+}, {
+    branch: string & {
+        readonly __brand: "BranchName";
+    };
+    entryPath: string & {
+        readonly __brand: "LogicalPath";
+    };
+}>, z.ZodObject<{
+    /** The deleted entry's content id, which the base file must carry and the restore keeps. */
+    id: z.ZodType<ContentId, z.ZodTypeDef, ContentId>;
+}, "strip", z.ZodTypeAny, {
+    id: string & {
+        readonly __brand: "ContentId";
+    };
+}, {
+    id: string & {
+        readonly __brand: "ContentId";
+    };
+}>, RestoreEntryResponse>;
+export type RestoreEntryBody = z.infer<typeof restoreBodySchema>;
 export declare const BRANCH_ENTRY_CHANGE_ROUTES: {
     readonly entry: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
@@ -60,7 +115,7 @@ export declare const BRANCH_ENTRY_CHANGE_ROUTES: {
         /** A moved entry's path at the base. */
         from: z.ZodOptional<z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>>;
         /** The entry's content id: both sides must carry it, so a slug reused by another entry isn't it. */
-        id: z.ZodOptional<z.ZodType<import("../paths/index.js").ContentId, z.ZodTypeDef, import("../paths/index.js").ContentId>>;
+        id: z.ZodOptional<z.ZodType<ContentId, z.ZodTypeDef, ContentId>>;
     }, "strip", z.ZodTypeAny, {
         branch: string & {
             readonly __brand: "BranchName";
@@ -68,7 +123,7 @@ export declare const BRANCH_ENTRY_CHANGE_ROUTES: {
         entryPath: string & {
             readonly __brand: "LogicalPath";
         };
-        id?: import("../paths/index.js").ContentId | undefined;
+        id?: ContentId | undefined;
         from?: LogicalPath | undefined;
     }, {
         branch: string & {
@@ -77,7 +132,37 @@ export declare const BRANCH_ENTRY_CHANGE_ROUTES: {
         entryPath: string & {
             readonly __brand: "LogicalPath";
         };
-        id?: import("../paths/index.js").ContentId | undefined;
+        id?: ContentId | undefined;
         from?: LogicalPath | undefined;
     }>, undefined, BranchEntryChangeResponse>;
+    readonly restore: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
+        entryPath: z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>;
+    }, "strip", z.ZodTypeAny, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+    }, {
+        branch: string & {
+            readonly __brand: "BranchName";
+        };
+        entryPath: string & {
+            readonly __brand: "LogicalPath";
+        };
+    }>, z.ZodObject<{
+        /** The deleted entry's content id, which the base file must carry and the restore keeps. */
+        id: z.ZodType<ContentId, z.ZodTypeDef, ContentId>;
+    }, "strip", z.ZodTypeAny, {
+        id: string & {
+            readonly __brand: "ContentId";
+        };
+    }, {
+        id: string & {
+            readonly __brand: "ContentId";
+        };
+    }>, RestoreEntryResponse>;
 };
+export {};

package/dist/api/branch-entry-changes.js

@@ -2,19 +2,22 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
 import { entryRefFromRepoPath, entryRefFromRepoPathShape, parseEntryParts, } from '../content-listing.js';
-import { ContentStore, ContentStoreError } from '../content-store.js';
+import { BranchSyncingError, ContentConflictError, ContentStore, ContentStoreError, } from '../content-store.js';
 import { resolveCollectionPath } from '../content-id-index.js';
 import { BaseBranchMissingError } from '../git-manager.js';
 import { getBranchProtection } from '../authorization/protected-branch.js';
+import { SchemaOps, SchemaStoreBusyError } from '../schema/schema-store.js';
+import { canopyLogWarn } from '../utils/logger.js';
+import { isRebaseInProgress } from '../utils/git.js';
 import { baseBranchOf } from '../utils/base-branch.js';
 import { findBodyFieldName } from '../utils/body-field.js';
 import { entryAsRead } from '../utils/calendar-day.js';
-import { isNodeError, isNotFoundError } from '../utils/error.js';
+import { isNodeError, isNotFoundError, sanitizeErrorMessage } from '../utils/error.js';
 import { getFormatExtension } from '../utils/format.js';
 import { entryLogicalPath } from '../paths/index.js';
 import { defineEndpoint } from './route-builder.js';
 import { branchNameSchema, contentIdSchema, logicalPathSchema } from './validators.js';
-import { branchReadFailedResponse, readWhileSteady, unsteadyReadResponse, } from './branch-changes.js';
+import { branchReadFailedResponse, readWhileSteady, SYNCING_ERROR, unsteadyReadResponse, } from './branch-changes.js';
 /** The most of a side's file read, so one huge file can't hold the API or the browser. */
 const MAX_SIDE_BYTES = 1024 * 1024;
 const NOT_COMPARABLE_ERROR = "This entry can't be compared.";
@@ -110,14 +113,13 @@ const readAfter = async (store, flatSchema, target, id) => {
     }
 };
 /**
- * The entry at `logicalPath` in `mergeBase`'s tree, matched by `contentId` when there is one.
- * Looked for under the collection's directory first, then the whole content root when that
- * directory isn't in the base tree (a collection renamed or deleted on the branch). Files map
- * to entries as GET /:branch/changes maps them, so the entry it lists resolves to the same
- * file here. A base file whose collection or entry type the schema no longer has is keyed with
- * `afterFields`, the saved side's, so its unchanged items carry the keys the saved side's do.
+ * The file of the entry at `logicalPath` in `mergeBase`'s tree, matched by `contentId` when
+ * there is one. Looked for under the collection's directory first, then the whole content root
+ * when that directory isn't in the base tree (a collection renamed or deleted on the branch).
+ * Files map to entries as GET /:branch/changes maps them, so the entry it lists resolves to the
+ * same file here.
  */
-const readBefore = async (git, mergeBase, logicalPath, match, branchContext, contentRoot) => {
+const findBaseFile = async (git, mergeBase, logicalPath, contentId, branchContext, contentRoot) => {
     const { flatSchema, branchRoot } = branchContext;
     const collectionPath = logicalPath.slice(0, logicalPath.lastIndexOf('/'));
     const collectionDir = await resolveCollectionPath(branchRoot, collectionPath);
@@ -132,35 +134,9 @@ const readBefore = async (git, mergeBase, logicalPath, match, branchContext, con
             const ref = placed.kind === 'other' ? entryRefFromRepoPathShape(file.path, contentRoot) : placed;
             if (ref?.kind !== 'entry' || ref.logicalPath !== logicalPath)
                 continue;
-            if (match.contentId !== undefined && ref.contentId !== match.contentId)
+            if (contentId !== undefined && ref.contentId !== contentId)
                 continue;
-            if (file.size > MAX_SIDE_BYTES)
-                return 'too-large';
-            const entryType = entryTypeIn(flatSchema, ref.collectionPath, ref.entryType);
-            const fields = entryType?.schema ?? match.afterFields ?? [];
-            // An entry type the schema no longer has is parsed by its extension.
-            const format = entryType?.format ?? FORMATS.find((f) => file.path.endsWith(getFormatExtension(f)));
-            if (!format)
-                return 'unreadable';
-            const raw = await git.showFile(mergeBase, file.path);
-            if (raw === undefined)
-                return undefined;
-            let parsed;
-            try {
-                parsed = parseEntryParts(raw, format);
-            }
-            catch {
-                return 'unreadable';
-            }
-            return {
-                format,
-                entryType: ref.entryType,
-                data: entryAsRead(fields, parsed.data),
-                ...(parsed.body !== undefined && {
-                    body: parsed.body,
-                    bodyFieldName: findBodyFieldName(fields),
-                }),
-            };
+            return { path: file.path, size: file.size, ref, placed: placed.kind === 'entry' };
         }
         // The collection's directory is in the base tree, so an entry not in it is new.
         if (files.length > 0)
@@ -168,6 +144,44 @@ const readBefore = async (git, mergeBase, logicalPath, match, branchContext, con
     }
     return undefined;
 };
+/**
+ * The entry at `logicalPath` in `mergeBase`'s tree (`findBaseFile`), read as the editor reads
+ * one. A base file whose collection or entry type the schema no longer has is keyed with
+ * `afterFields`, the saved side's, so its unchanged items carry the keys the saved side's do.
+ */
+const readBefore = async (git, mergeBase, logicalPath, match, branchContext, contentRoot) => {
+    const file = await findBaseFile(git, mergeBase, logicalPath, match.contentId, branchContext, contentRoot);
+    if (!file)
+        return undefined;
+    const { ref } = file;
+    if (file.size > MAX_SIDE_BYTES)
+        return 'too-large';
+    const entryType = entryTypeIn(branchContext.flatSchema, ref.collectionPath, ref.entryType);
+    const fields = entryType?.schema ?? match.afterFields ?? [];
+    // An entry type the schema no longer has is parsed by its extension.
+    const format = entryType?.format ?? FORMATS.find((f) => file.path.endsWith(getFormatExtension(f)));
+    if (!format)
+        return 'unreadable';
+    const raw = await git.showFile(mergeBase, file.path);
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = parseEntryParts(raw, format);
+    }
+    catch {
+        return 'unreadable';
+    }
+    return {
+        format,
+        entryType: ref.entryType,
+        data: entryAsRead(fields, parsed.data),
+        ...(parsed.body !== undefined && {
+            body: parsed.body,
+            bodyFieldName: findBodyFieldName(fields),
+        }),
+    };
+};
 const entryChangeHandler = async (gc, ctx, req, params) => {
     const { branchContext } = gc;
     const { config } = ctx.services;
@@ -255,6 +269,226 @@ export const readBranchEntryChange = defineEndpoint({
     guards: ['branchAccessWithSchema'],
     handler: entryChangeHandler,
 });
+const restoreParamsSchema = z.object({
+    branch: branchNameSchema,
+    entryPath: logicalPathSchema,
+});
+const restoreBodySchema = z.object({
+    /** The deleted entry's content id, which the base file must carry and the restore keeps. */
+    id: contentIdSchema,
+});
+const NOT_RESTORABLE_ERROR = "This entry isn't on the base branch, so it can't be restored.";
+const TYPE_CHANGED_ERROR = "This entry's type or format has changed since it was deleted, so it can't be restored.";
+const TOO_LARGE_TO_RESTORE_ERROR = 'This entry is too large to restore here.';
+const UNREADABLE_TO_RESTORE_ERROR = "This entry's saved file doesn't read, so it can't be restored.";
+/** `order` with `id` put back after its nearest predecessor in `baseOrder` that `order` holds. */
+const orderWith = (order, id, baseOrder) => {
+    const at = baseOrder.indexOf(id);
+    for (let i = at - 1; i >= 0; i--) {
+        const index = order.indexOf(baseOrder[i]);
+        if (index >= 0)
+            return [...order.slice(0, index + 1), id, ...order.slice(index + 1)];
+    }
+    return [id, ...order];
+};
+/** A collection's `order` in its `.collection.json` at `rev`, or undefined when it has none. */
+const orderAt = async (git, rev, collectionRepoDir) => {
+    const raw = await git.showFile(rev, `${collectionRepoDir}/.collection.json`);
+    if (raw === undefined)
+        return undefined;
+    try {
+        const order = JSON.parse(raw)?.order;
+        return Array.isArray(order) && order.every((id) => typeof id === 'string') ? order : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Git failing in a restore's pre-write HEAD check, answered as a failed read is. */
+class HeadReadError extends Error {
+    constructor(failure) {
+        super("Couldn't read the branch's HEAD");
+        this.failure = failure;
+    }
+}
+const restoreEntryHandler = async (gc, ctx, req, params, body) => {
+    const { branchContext } = gc;
+    const { branchRoot } = branchContext;
+    const { config } = ctx.services;
+    const base = branchContext.branch.baseBranch ?? baseBranchOf(config);
+    const contentRoot = config.contentRoot || 'content';
+    const store = new ContentStore(branchRoot, branchContext.flatSchema, {
+        contentRootName: contentRoot,
+    });
+    const target = canonicalPath(store, underContentRoot(params.entryPath, contentRoot));
+    const notRestorable = {
+        ok: false,
+        status: 404,
+        error: NOT_RESTORABLE_ERROR,
+    };
+    if (!target.stored)
+        return notRestorable;
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchRoot, req.user);
+    if (!checkAccess(target.logicalPath, 'edit').allowed) {
+        return { ok: false, status: 403, error: 'Forbidden' };
+    }
+    const { collectionPath, slug } = target.stored;
+    const collectionDir = await resolveCollectionPath(branchRoot, collectionPath);
+    const collectionRepoDir = collectionDir && path.relative(branchRoot, collectionDir).split(path.sep).join('/');
+    const git = ctx.services.createGitManagerFor(branchRoot, {
+        baseBranch: branchContext.branch.baseBranch,
+    });
+    let read;
+    try {
+        read = await readWhileSteady(branchRoot, git, async () => {
+            const mergeBase = await git.mergeBaseWithBase();
+            if (!mergeBase)
+                return undefined;
+            const file = await findBaseFile(git, mergeBase, target.logicalPath, body.id, branchContext, contentRoot);
+            if (!file)
+                return undefined;
+            // Only a file the current schema places as this entry type, by name and extension, goes
+            // back: another format's bytes under this type's extension would not read.
+            if (!file.placed)
+                return 'type-changed';
+            if (file.size > MAX_SIDE_BYTES)
+                return 'too-large';
+            const raw = await git.showFile(mergeBase, file.path);
+            if (raw === undefined)
+                return undefined;
+            const baseOrder = collectionRepoDir
+                ? await orderAt(git, mergeBase, collectionRepoDir)
+                : undefined;
+            return {
+                raw,
+                entryType: file.ref.entryType,
+                head: await git.headSha(),
+                ...(baseOrder && { baseOrder }),
+            };
+        });
+    }
+    catch (err) {
+        if (err instanceof BaseBranchMissingError)
+            return notRestorable;
+        return branchReadFailedResponse(branchContext.branch.name, base, err);
+    }
+    if (!read.steady)
+        return unsteadyReadResponse(read.reason, base);
+    const entry = read.value;
+    if (entry === 'too-large')
+        return { ok: false, status: 413, error: TOO_LARGE_TO_RESTORE_ERROR };
+    if (entry === 'type-changed')
+        return { ok: false, status: 409, error: TYPE_CHANGED_ERROR };
+    if (!entry)
+        return notRestorable;
+    const entryType = entryTypeIn(branchContext.flatSchema, collectionPath, entry.entryType);
+    if (!entryType)
+        return { ok: false, status: 409, error: TYPE_CHANGED_ERROR };
+    try {
+        parseEntryParts(entry.raw, entryType.format);
+    }
+    catch {
+        return { ok: false, status: 422, error: UNREADABLE_TO_RESTORE_ERROR };
+    }
+    // As a create checks it (SCH-H3, api/content.ts), best-effort: count-then-write isn't atomic.
+    const { maxItems } = entryType;
+    if (maxItems !== undefined &&
+        (await store.countEntriesOfType(collectionPath, entry.entryType)) >= maxItems) {
+        return {
+            ok: false,
+            status: 422,
+            error: `Cannot restore entry: type "${entry.entryType}" allows at most ${maxItems} ${maxItems === 1 ? 'entry' : 'entries'}`,
+        };
+    }
+    try {
+        await store.restore(collectionPath, slug, { id: body.id, entryTypeName: entry.entryType, raw: entry.raw }, {
+            // The bytes are the merge base's as HEAD stood at the read; a sync since may have
+            // updated the entry upstream, so a moved HEAD refuses rather than reverting that.
+            beforeWrite: async () => {
+                let moved;
+                try {
+                    moved = (await isRebaseInProgress(branchRoot)) || (await git.headSha()) !== entry.head;
+                }
+                catch (err) {
+                    throw new HeadReadError(err);
+                }
+                if (moved)
+                    throw new BranchSyncingError(SYNCING_ERROR(base));
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof HeadReadError) {
+            return branchReadFailedResponse(branchContext.branch.name, base, err.failure);
+        }
+        if (err instanceof BranchSyncingError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.message,
+                code: err.outcome === 'unknown' ? 'WRITE_OUTCOME_UNKNOWN' : 'BRANCH_SYNCING',
+            };
+        }
+        // A refusal the editor can act on: the slug or the id is taken, or a URL is contested.
+        if (err instanceof ContentConflictError)
+            return { ok: false, status: 409, error: err.message };
+        if (err instanceof ContentStoreError) {
+            return { ok: false, status: 400, error: sanitizeErrorMessage(err.message) };
+        }
+        throw err;
+    }
+    const warning = await restoreOrder(ctx, branchContext, collectionPath, body.id, entry.baseOrder);
+    return {
+        ok: true,
+        status: 200,
+        data: { logicalPath: target.logicalPath, contentId: body.id, ...(warning && { warning }) },
+    };
+};
+/**
+ * Puts a restored entry's id back in its collection's manual order, after its nearest neighbour
+ * at the base, undoing what a delete took out (api/entries.ts). Best-effort: the entry is back
+ * either way, so a failure is a warning. Runs after the restore, whose content-write lock a
+ * schema write also takes.
+ */
+const restoreOrder = async (ctx, branchContext, collectionPath, id, baseOrder) => {
+    const collection = branchContext.flatSchema.find((item) => item.type === 'collection' && item.logicalPath === collectionPath);
+    const order = collection?.order;
+    if (!order || !baseOrder?.includes(id) || order.includes(id))
+        return undefined;
+    const schemaStore = new SchemaOps(path.join(branchContext.branchRoot, ctx.services.config.contentRoot || 'content'), ctx.services.entrySchemaRegistry, ctx.services, branchContext.branchRoot);
+    try {
+        await schemaStore.updateOrder(collectionPath, orderWith(order, id, baseOrder));
+        return undefined;
+    }
+    catch (err) {
+        // An `'unknown'` outcome means the update ran to completion.
+        if (err instanceof SchemaStoreBusyError && err.outcome === 'unknown')
+            return undefined;
+        canopyLogWarn(`CanopyCMS: restored ${collectionPath}/${id} but not its place in the order:`, err);
+        return 'Entry restored, but its place in the collection order couldn’t be put back, so it is listed last.';
+    }
+};
+/**
+ * Puts back an entry deleted on the branch, as the commit the branch forked from holds it, with
+ * its content id (`ContentStore.restore`).
+ * POST /:branch/restore-entry/...entryPath
+ * @internal Exported for tests.
+ */
+export const restoreBranchEntry = defineEndpoint({
+    namespace: 'changes',
+    name: 'restore',
+    method: 'POST',
+    path: '/:branch/restore-entry/...entryPath',
+    params: restoreParamsSchema,
+    body: restoreBodySchema,
+    bodyType: 'RestoreEntryBody',
+    responseType: 'RestoreEntryResponse',
+    response: {},
+    defaultMockData: { logicalPath: '', contentId: '' },
+    guards: ['schema', 'writableBranch'],
+    handler: restoreEntryHandler,
+});
 export const BRANCH_ENTRY_CHANGE_ROUTES = {
     entry: readBranchEntryChange,
+    restore: restoreBranchEntry,
 };

package/dist/api/branch-review.js

@@ -6,6 +6,8 @@ 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';
@@ -131,22 +133,52 @@ 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.
+    // 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 () => {
+            await assertNoOpenConflicts(branchContext.branchRoot);
+            return 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;
+            });
+        });
+    }
+    catch (err) {
+        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,

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

@@ -4,6 +4,7 @@ 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 { 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, {

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.
@@ -275,6 +287,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>;