canopycms 0.12.0 → 0.12.1

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>;

package/dist/api/branch-update-from-base.js

@@ -0,0 +1,176 @@
+import { branchParamSchema } from './validators.js';
+import { toBranchListItem } from './branch.js';
+import { defineEndpoint } from './route-builder.js';
+import { canPerformWorkflowAction, getBranchProtection } from '../authorization/index.js';
+import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
+import { clientOperatingStrategy } from '../operating-mode/index.js';
+import { enqueueTask, listTasks } from '../task-queue/cms-task-queue.js';
+import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
+import { BASE_UPDATE_GIVE_UP_MS, BASE_UPDATE_REQUEST_INTERVAL_MS, SYNC_BRANCH_ACTION, isBaseUpdatePending, } from '../base-update.js';
+import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
+import { getErrorMessage, redactCredentials } from '../utils/error.js';
+import { baseBranchOf } from '../utils/base-branch.js';
+/**
+ * Ask the worker to bring the base branch into this one now, rather than at its next sync
+ * (base-update.ts). Saved work is committed first, locally: the sync skips a branch with
+ * uncommitted changes, so without the commit the request would do nothing.
+ *
+ * The request is recorded on branch.json, which is what the worker answers, so a lost task or a
+ * worker restart costs only the wait for its next regular cycle. The task only wakes it early.
+ * A request joins the last one, answering with its time: while that is unanswered, under
+ * BASE_UPDATE_GIVE_UP_MS old and either under BASE_UPDATE_REQUEST_INTERVAL_MS old or still queued;
+ * or once it was answered under BASE_UPDATE_REQUEST_INTERVAL_MS ago without failing. Anything
+ * else, a Retry after a failure among them, is a new request.
+ */
+const updateFromBaseHandler = async (gc, ctx, req, _params) => {
+    const { branchContext } = gc;
+    const { config } = ctx.services;
+    const { branch } = branchContext;
+    if (!clientOperatingStrategy(config.mode).syncsBranchesWithBase()) {
+        return {
+            ok: false,
+            status: 409,
+            error: `Getting the latest changes needs the CMS worker, which ${config.mode} mode doesn't run.`,
+        };
+    }
+    const { isProtected } = getBranchProtection(config, branch.name, branch.baseBranch);
+    const allowed = canPerformWorkflowAction(branchContext, req.user, config.defaultBranchAccess ?? 'deny', { isProtectedBranch: isProtected });
+    if (!allowed) {
+        return {
+            ok: false,
+            status: 403,
+            error: 'You do not have permission to get the latest changes for this branch.',
+        };
+    }
+    if (isProtected) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'This branch is the one changes come from, so it has no latest changes to get.',
+        };
+    }
+    // Only an editing branch takes the base in; the worker leaves the others as they are.
+    if (branch.status !== 'editing') {
+        return {
+            ok: false,
+            status: 409,
+            error: branch.status === 'submitted' || branch.status === 'approved'
+                ? 'This branch is in review. Withdraw it from review to get the latest changes.'
+                : "This branch can't be edited, so it can't get the latest changes.",
+        };
+    }
+    const base = branch.baseBranch ?? baseBranchOf(config);
+    const { authPlugin } = ctx;
+    try {
+        await ctx.services.commitSavedWork({
+            context: branchContext,
+            message: `Save changes before getting the latest from ${base}`,
+            lookupEditor: authPlugin ? (id) => authPlugin.getUserMetadata(id) : undefined,
+        });
+    }
+    catch (err) {
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? 'This branch is being synced, or a save is in progress. Nothing changed; try again in a moment.'
+                    : "This branch was being synced while your saved work was prepared, so the latest changes weren't requested. Try again.",
+            };
+        }
+        console.error(`CanopyCMS: Could not commit the saved changes of ${branch.name} before getting the latest:`, redactCredentials(getErrorMessage(err)));
+        return {
+            ok: false,
+            status: 500,
+            error: "Your saved changes couldn't be prepared, so the latest changes weren't requested.",
+        };
+    }
+    const taskDir = getTaskQueueDir(config);
+    const queued = (await listTasks(taskDir, 'pending', Number.MAX_SAFE_INTEGER)).some((t) => t.action === SYNC_BRANCH_ACTION && t.payload.branch === branch.name);
+    const now = Date.now();
+    let requestedAt = new Date(now).toISOString();
+    let joined = false;
+    let leftEditing;
+    const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
+    const saved = await meta.update((existing) => {
+        if (existing?.branch.name !== branch.name)
+            return null;
+        // A submit since the guard read: the worker would leave the request standing until a withdraw.
+        if (existing.branch.status !== 'editing') {
+            leftEditing = existing.branch.status;
+            return null;
+        }
+        const last = existing.branch.baseUpdateRequestedAt;
+        const age = last === undefined ? Infinity : now - Date.parse(last);
+        const answer = existing.branch.lastBaseUpdate;
+        const pending = isBaseUpdatePending(existing.branch);
+        // An unanswered request is joined until the editor stops waiting on it. An answer under the
+        // interval old stands for a new click too, except a failure, whose Retry must ask again.
+        const joinsPending = pending && age < BASE_UPDATE_GIVE_UP_MS && (queued || age < BASE_UPDATE_REQUEST_INTERVAL_MS);
+        const answeredRecently = !pending &&
+            answer !== undefined &&
+            answer.outcome !== 'failed' &&
+            now - Date.parse(answer.at) < BASE_UPDATE_REQUEST_INTERVAL_MS;
+        if (last !== undefined && (joinsPending || answeredRecently)) {
+            requestedAt = last;
+            joined = true;
+            return null;
+        }
+        return { branch: { baseUpdateRequestedAt: requestedAt } };
+    }, { keepUpdatedAt: true });
+    if (leftEditing) {
+        return {
+            ok: false,
+            status: 409,
+            error: leftEditing === 'submitted' || leftEditing === 'approved'
+                ? 'This branch is in review. Withdraw it from review to get the latest changes.'
+                : "This branch can't be edited, so it can't get the latest changes.",
+        };
+    }
+    const current = saved ?? (await BranchMetadataFileManager.loadOnly(branchContext.branchRoot));
+    if (current?.branch.name !== branch.name) {
+        return { ok: false, status: 404, error: 'This branch no longer exists.' };
+    }
+    // A wake-up already queued serves the new request too.
+    if (!joined && !queued) {
+        try {
+            await enqueueTask(taskDir, { action: SYNC_BRANCH_ACTION, payload: { branch: branch.name } });
+        }
+        catch (err) {
+            // The worker's next regular sync answers the recorded request anyway, only later.
+            console.warn(`CanopyCMS: Could not queue the request for the latest changes on ${branch.name}:`, getErrorMessage(err));
+        }
+    }
+    return {
+        ok: true,
+        status: 202,
+        data: { requestedAt, branch: toBranchListItem(config, current.branch, req.user) },
+    };
+};
+/** Get the latest changes: bring the base branch into this one at the worker's next chance. */
+export const updateFromBase = defineEndpoint({
+    namespace: 'workflow',
+    name: 'updateFromBase',
+    // Commits saved work on the shared filesystem before answering.
+    clientTimeout: 'long',
+    method: 'POST',
+    path: '/:branch/update-from-base',
+    params: branchParamSchema,
+    responseType: 'UpdateFromBaseResponse',
+    response: {},
+    defaultMockData: {
+        requestedAt: '2024-01-01T00:00:00.000Z',
+        branch: {
+            name: 'test-branch',
+            status: 'editing',
+            access: {},
+            createdBy: 'user-1',
+            createdAt: '2024-01-01',
+            updatedAt: '2024-01-01',
+            baseUpdateRequestedAt: '2024-01-01T00:00:00.000Z',
+        },
+    },
+    // As Withdraw: the handler's canPerformWorkflowAction decides who may ask.
+    guards: ['branch'],
+    handler: updateFromBaseHandler,
+});

package/dist/api/branch.d.ts

@@ -82,6 +82,11 @@ export type BranchListResponse = ApiResponse<{
     defaultBranch?: string;
     /** Profiles of the listed branches' creators, in no order; unknown ids are absent. */
     users: UserProfile[];
+    /**
+     * The server's clock as it answered, in ms since the epoch, so the editor times a wait for the
+     * latest changes against the clock that stamped the request rather than the browser's.
+     */
+    serverTime?: number;
 }>;
 /** Response type for branch deletion */
 export type BranchDeleteResponse = ApiResponse<{

package/dist/api/branch.js

@@ -528,6 +528,7 @@ const branchListResponse = async (ctx, req, branches, defaultBranch) => {
             branches: branches.map((context) => toBranchListItem(ctx.services.config, context.branch, req.user)),
             defaultBranch,
             users,
+            serverTime: Date.now(),
         },
     };
 };

package/dist/api/client.d.ts

@@ -11,7 +11,8 @@ import type { OperatingMode } from '../operating-mode/types.js';
 import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
 import type { BranchChangesResponse } from './branch-changes.js';
 import type { BranchEntryChangeResponse, RestoreEntryBody, RestoreEntryResponse } from './branch-entry-changes.js';
-import type { BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse } from './branch-status.js';
+import type { EntryConflictResponse, MergeConflictsResponse, ReleaseConflictsHoldResponse, ResolveEntryConflictBody, ResolveEntryConflictResponse } from './merge-conflicts.js';
+import type { BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse, UpdateFromBaseResponse } from './branch-status.js';
 import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, DeleteArchivedBranchesBody, DeleteArchivedBranchesResponse, DismissUnpublishedResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
 import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResponse, RenameEntryBody, RenameEntryResponse, ValidateReferencesBody, WriteContentBody } from './content.js';
@@ -95,9 +96,21 @@ export declare class CanopyApiClient {
         /** POST /:branch/restore-entry/...entryPath */
         restore: (params: Record<string, string>, body: RestoreEntryBody, options?: RequestOptions) => Promise<RestoreEntryResponse>;
     };
+    readonly conflicts: {
+        /** GET /:branch/conflicts */
+        list: (params: Record<string, string>, options?: RequestOptions) => Promise<MergeConflictsResponse>;
+        /** GET /:branch/conflicts/...entryPath */
+        entry: (params: Record<string, string>, options?: RequestOptions) => Promise<EntryConflictResponse>;
+        /** POST /:branch/resolve-entry/...entryPath */
+        resolveEntry: (params: Record<string, string>, body: ResolveEntryConflictBody, options?: RequestOptions) => Promise<ResolveEntryConflictResponse>;
+        /** POST /:branch/conflicts/release-hold */
+        releaseHold: (params: Record<string, string>, options?: RequestOptions) => Promise<ReleaseConflictsHoldResponse>;
+    };
     readonly workflow: {
         /** POST /:branch/withdraw */
         withdraw: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
+        /** POST /:branch/update-from-base */
+        updateFromBase: (params: Record<string, string>, options?: RequestOptions) => Promise<UpdateFromBaseResponse>;
         /** POST /:branch/request-changes */
         requestChanges: (params: Record<string, string>, body: RequestChangesBody, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/approve */

package/dist/api/client.js

@@ -55,11 +55,33 @@ export class CanopyApiClient {
                 return this.request('POST', this.buildPath('/:branch/restore-entry/...entryPath', params), body, 'standard', options);
             },
         };
+        this.conflicts = {
+            /** GET /:branch/conflicts */
+            list: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/conflicts', params), undefined, 'standard', options);
+            },
+            /** GET /:branch/conflicts/...entryPath */
+            entry: (params, options) => {
+                return this.request('GET', this.buildPath('/:branch/conflicts/...entryPath', params), undefined, 'standard', options);
+            },
+            /** POST /:branch/resolve-entry/...entryPath */
+            resolveEntry: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/resolve-entry/...entryPath', params), body, 'standard', options);
+            },
+            /** POST /:branch/conflicts/release-hold */
+            releaseHold: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/conflicts/release-hold', params), undefined, 'standard', options);
+            },
+        };
         this.workflow = {
             /** POST /:branch/withdraw */
             withdraw: (params, options) => {
                 return this.request('POST', this.buildPath('/:branch/withdraw', params), undefined, 'standard', options);
             },
+            /** POST /:branch/update-from-base */
+            updateFromBase: (params, options) => {
+                return this.request('POST', this.buildPath('/:branch/update-from-base', params), undefined, 'long', options);
+            },
             /** POST /:branch/request-changes */
             requestChanges: (params, body, options) => {
                 return this.request('POST', this.buildPath('/:branch/request-changes', params), body, 'standard', options);

package/dist/api/comments.d.ts

@@ -60,16 +60,16 @@ export declare const COMMENT_ROUTES: {
     }, "strip", z.ZodTypeAny, {
         type: "branch" | "entry" | "field";
         text: string;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         itemKeys?: string[] | undefined;
-        entryPath?: LogicalPath | undefined;
         canopyPath?: string | undefined;
     }, {
         type: "branch" | "entry" | "field";
         text: string;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         itemKeys?: string[] | undefined;
-        entryPath?: LogicalPath | undefined;
         canopyPath?: string | undefined;
     }>, AddCommentResponse>;
     readonly resolve: import("./route-builder.js").RouteDefinition<z.ZodObject<{

package/dist/api/content.d.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-import type { EntryValidationIssue } from '../config/index.js';
+import type { ContentFormat, EntrySchema, EntryValidationIssue } from '../config/index.js';
 import { type LogicalPath, type Slug } from '../paths/index.js';
+import type { ResolvedFieldConflict } from '../merge-conflicts.js';
 export type ContentReadResponse = ApiResponse<{
     format: string;
     data: Record<string, unknown>;
@@ -22,6 +23,11 @@ export type ContentWriteResponse = ApiResponse<{
      * editor has exactly one save-warnings notification to render (useEntryManager.ts).
      */
     validationWarnings?: EntryValidationIssue[];
+    /**
+     * Of the `resolvedConflicts` sent with an update, the ones this save cleared: one sent but not
+     * here was stale, unless a warning says the choice wasn't recorded.
+     */
+    resolvedConflicts?: ResolvedFieldConflict[];
 }>;
 export type ReferenceValidationResponse = ApiResponse<{
     valid: boolean;
@@ -48,6 +54,13 @@ export interface WriteContentBody {
      * from "lost the token", so an update has to prove which version it read.
      */
     expectedVersion?: number | null;
+    /**
+     * Field conflicts a merge left on this entry that the saved values resolve, each named as
+     * `GET /:branch/conflicts/...entryPath` names it. Cleared once the entry is written, under the
+     * save's locks; a pair the record no longer holds is ignored. A save that leaves a conflicting
+     * field out leaves its conflict open.
+     */
+    resolvedConflicts?: ResolvedFieldConflict[];
 }
 export interface ValidateReferencesBody {
     data: Record<string, unknown>;
@@ -55,6 +68,12 @@ export interface ValidateReferencesBody {
 export interface RenameEntryBody {
     newSlug: string;
 }
+/**
+ * What a save writes for `data`, an entry's form data: an md/mdx file's body-field key dropped
+ * (that field is the file's body), references collapsed to IDs, and every list item and block
+ * keyed. `backfill-item-keys` writes through this too, so its files are a save's.
+ */
+export declare function entryDataAsSaved(fields: EntrySchema, format: ContentFormat, data: Record<string, unknown>): Record<string, unknown>;
 /**
  * Exported routes for router registration
  */
@@ -102,16 +121,34 @@ export declare const CONTENT_ROUTES: {
         data: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>;
         body: z.ZodOptional<z.ZodString>;
         expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        resolvedConflicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            mergeSha: z.ZodString;
+            key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            key: string;
+            mergeSha: string;
+        }, {
+            key: string;
+            mergeSha: string;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         format: "md" | "mdx" | "json" | "yaml";
         data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
+        resolvedConflicts?: {
+            key: string;
+            mergeSha: string;
+        }[] | undefined;
     }, {
         format: "md" | "mdx" | "json" | "yaml";
         data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
+        resolvedConflicts?: {
+            key: string;
+            mergeSha: string;
+        }[] | undefined;
     }>, ContentWriteResponse>;
     readonly validateReferences: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;

package/dist/api/content.js

@@ -14,6 +14,8 @@ import { getErrorMessage, isNotFoundError, sanitizeErrorMessage } from '../utils
 import { isDataOnlyFormat } from '../utils/format.js';
 import { withItemKeys } from '../item-keys.js';
 import { findBodyFieldName } from '../utils/body-field.js';
+import { canopyLogWarn } from '../utils/logger.js';
+import { clearFieldConflicts, resolvedConflictsSchema } from './merge-conflicts.js';
 /**
  * Parse an API path into logical path segments, prepending the content root if needed.
  * Shared by all content API handlers.
@@ -60,6 +62,7 @@ const writeContentBodySchema = z.object({
     body: z.string().max(MAX_CONTENT_BODY_CHARS).optional(),
     // null or omitted = create ("must not already exist"); see WriteContentBody.
     expectedVersion: z.number().nullish(),
+    resolvedConflicts: resolvedConflictsSchema.optional(),
 });
 const validateReferencesParamsSchema = z.object({
     branch: branchNameSchema,
@@ -133,6 +136,15 @@ function withoutKey(record, key) {
     const { [key]: _dropped, ...rest } = record;
     return rest;
 }
+/**
+ * What a save writes for `data`, an entry's form data: an md/mdx file's body-field key dropped
+ * (that field is the file's body), references collapsed to IDs, and every list item and block
+ * keyed. `backfill-item-keys` writes through this too, so its files are a save's.
+ */
+export function entryDataAsSaved(fields, format, data) {
+    const own = isDataOnlyFormat(format) ? data : withoutKey(data, findBodyFieldName(fields));
+    return withItemKeys(fields, normalizeReferenceValues(fields, own), 'content');
+}
 /** The policy's issues in the stored entry, which a save may keep. */
 const storedMarkdownSafetyIssues = async (store, collectionPath, slug, fields, siteAllow) => {
     // A stored file that does not read keeps nothing, so the save's code is refused, not a 500.
@@ -393,9 +405,7 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
     // Every list item and block leaves a save keyed (`item-keys.ts`). A key sent is kept, so a
     // thread naming it still finds its item; one missing is filled from the item's content, as a
     // read fills one.
-    const normalizedData = requestData === undefined
-        ? undefined
-        : withItemKeys(fields, normalizeReferenceValues(fields, requestData), 'content');
+    const normalizedData = requestData === undefined ? undefined : entryDataAsSaved(fields, body.format, requestData);
     // Computed before the validateEntry hook and the entry-link scan too, not just the write, so
     // every consumer agrees on the same bytes — otherwise an adopter's hook could see a resolved
     // object while the file got an ID string, depending on whether the post came from the editor.
@@ -475,10 +485,32 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
                 body: body.body ?? '',
                 expectedVersion,
             };
+        // Under the write's own locks, so no merge records a conflict between the value written and
+        // the record cleared. A failure to clear keeps the save: the conflict stays open, and says so.
+        let resolvedConflicts;
+        const resolving = expectedVersion === null ? [] : (body.resolvedConflicts ?? []);
+        const afterWrite = async ({ id }) => {
+            if (!id || resolving.length === 0)
+                return;
+            try {
+                resolvedConflicts = await clearFieldConflicts(branchContext, id, resolving);
+            }
+            catch (err) {
+                canopyLogWarn(`CanopyCMS: saved ${logicalPathSegments.join('/')} but couldn't mark its conflicts resolved:`, getErrorMessage(err));
+                resolvedConflicts = [];
+                validationWarnings = [
+                    ...(validationWarnings ?? []),
+                    {
+                        level: 'warning',
+                        message: 'Saved, but your choice for its conflicting changes wasn’t recorded. Choose again, then save.',
+                    },
+                ];
+            }
+        };
         // Pass the resolved entryTypeName (not the raw, possibly-omitted
         // params.entryType) so the store's own format check agrees with the type
         // we just validated against.
-        const result = await store.write(schemaItem.logicalPath, slug, writeInput, entryTypeName);
+        const result = await store.write(schemaItem.logicalPath, slug, writeInput, entryTypeName, undefined, { afterWrite });
         // Validate entry links in body content (warnings only, don't block save).
         // Reuses the entry-type fields resolved above for schema validation. Folded into
         // `validationWarnings` (not a separate `entryLinkWarnings` field) so the editor's one
@@ -494,7 +526,11 @@ const writeContentHandler = async (gc, ctx, req, params, body) => {
             }));
             validationWarnings = [...(validationWarnings ?? []), ...linkWarnings];
         }
-        return { ok: true, status: 200, data: { ...result, validationWarnings } };
+        return {
+            ok: true,
+            status: 200,
+            data: { ...result, validationWarnings, ...(resolvedConflicts && { resolvedConflicts }) },
+        };
     }
     catch (err) {
         if (err instanceof ContentConflictError) {