canopycms 0.12.0 → 0.12.1

package/dist/operating-mode/client-safe-strategy.d.ts

@@ -9,6 +9,7 @@ export declare class ProdClientSafeStrategy implements ClientSafeStrategy {
     supportsBranching(): boolean;
     supportsComments(): boolean;
     supportsPullRequests(): boolean;
+    syncsBranchesWithBase(): boolean;
     getPermissionsFileName(): string;
     getGroupsFileName(): string;
     shouldCommit(): boolean;
@@ -19,6 +20,7 @@ export declare class DevClientSafeStrategy implements ClientSafeStrategy {
     supportsBranching(): boolean;
     supportsComments(): boolean;
     supportsPullRequests(): boolean;
+    syncsBranchesWithBase(): boolean;
     getPermissionsFileName(): string;
     getGroupsFileName(): string;
     shouldCommit(): boolean;

package/dist/operating-mode/client-safe-strategy.js

@@ -16,6 +16,9 @@ export class ProdClientSafeStrategy {
     supportsPullRequests() {
         return true;
     }
+    syncsBranchesWithBase() {
+        return true;
+    }
     getPermissionsFileName() {
         return 'permissions.json';
     }
@@ -42,6 +45,9 @@ export class DevClientSafeStrategy {
     supportsPullRequests() {
         return false; // No real GitHub in local dev mode
     }
+    syncsBranchesWithBase() {
+        return false;
+    }
     getPermissionsFileName() {
         return 'permissions.json';
     }

package/dist/operating-mode/types.d.ts

@@ -33,6 +33,11 @@ export interface ClientSafeStrategy {
     supportsBranching(): boolean;
     supportsComments(): boolean;
     supportsPullRequests(): boolean;
+    /**
+     * Whether a worker brings the base branch into editing branches, so a request for the latest
+     * changes (base-update.ts) gets an answer. Dev runs no git sync.
+     */
+    syncsBranchesWithBase(): boolean;
     /** Get the permissions file name (e.g., 'permissions.json' or 'permissions.local.json') */
     getPermissionsFileName(): string;
     /** Get the groups file name (e.g., 'groups.json' or 'groups.local.json') */

package/dist/services.d.ts

@@ -79,13 +79,28 @@ export interface CanopyServices {
         files: string | string[];
         message: string;
     }) => Promise<void>;
+    /**
+     * Commit the branch's saved but uncommitted work in its clone, pushing nothing. A later submit
+     * pushes it, or, on a branch published before, the worker's merge of the base once it moves
+     * (worker/rebase.ts, `aheadOfPublished`). Its trailers name the editors who saved since the last
+     * commit.
+     * Holds the branch's content-write lock; rejects with `ContentWriteLockBusyError` when busy.
+     * Resolves whether there was anything to commit.
+     */
+    commitSavedWork: (options: {
+        context: BranchContext;
+        message: string;
+        /** Names the editors; without it they are credited by id. */
+        lookupEditor?: EditorLookup;
+    }) => Promise<boolean>;
     /**
      * Submit branch: fill new entries' empty `stampOnPublish` fields
      * (stamp-on-publish.ts), commit all changes (with the submitter's trailers)
      * and push to remote. Resolves with every path the branch changes against its base,
      * and with `stamped`, the entries this submit stamped.
      * Holds the branch's content-write lock; rejects with
-     * `ContentWriteLockBusyError` when busy, and with `NothingToSubmitError`
+     * `ContentWriteLockBusyError` when busy, with `OpenMergeConflictsError` before committing while
+     * a merge's conflicts are open (merge-conflicts.ts), and with `NothingToSubmitError`
      * before pushing when the branch changes nothing.
      */
     submitBranch: (options: {

package/dist/services.js

@@ -30,14 +30,15 @@ import { enqueueTask } from './task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from './task-queue/task-queue-config.js';
 import { baseBranchOf } from './utils/base-branch.js';
 import { shortNameOf } from './branch-param.js';
-import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
+import { detectHeadBranch, isCanopyInternalPath, isRebaseInProgress } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
 import { timeRequestPhase } from './utils/request-timing.js';
 import { appendTrailers, buildEditorTrailers, describeEditors, MAX_LISTED_ENTRIES, } from './submission-attribution.js';
 import { getBranchMetadataFileManager, recordBranchEditor } from './branch-metadata.js';
 import { readBranchMetadataFile } from './branch-metadata-file.js';
 import { getErrorMessage, redactCredentials } from './utils/error.js';
-import { withContentWriteLock } from './utils/content-write-lock.js';
+import { ContentWriteLockBusyError, withContentWriteLock } from './utils/content-write-lock.js';
+import { assertNoOpenConflicts } from './merge-conflicts.js';
 import { ContentStore } from './content-store.js';
 import { entryLogicalPathOfFile } from './content-id-index.js';
 import { stampNewEntries } from './stamp-on-publish.js';
@@ -213,10 +214,77 @@ async function _createCanopyServicesInternal(config, options) {
         // lands on its detached head with the rebase's half-resolved index, and the
         // rebase's `--abort` discards it.
         await withContentWriteLock(options.context.branchRoot, async () => {
+            await refuseDuringRebase(options.context.branchRoot);
             await git.add(options.files);
             await git.commit(options.message);
         });
     };
+    /**
+     * Inside the content-write lock, before a commit: a rebase left by a worker that died holds no
+     * lock, and its recovery (`rebase --abort`, worker/rebase.ts) would reset the branch past the
+     * commit, silently. In prod the worker clears it on its next cycle, so this is a retry.
+     */
+    const refuseDuringRebase = async (branchRoot) => {
+        if (await isRebaseInProgress(branchRoot))
+            throw new ContentWriteLockBusyError();
+    };
+    /**
+     * Commit every saved change but canopycms's own state, if there is one, with trailers naming
+     * `credited` and then the editors who saved since the last commit. Runs inside the caller's
+     * content-write lock. Resolves whether it committed.
+     */
+    const commitSavedChanges = async (git, status, commit) => {
+        if (!status.files.some((f) => !isCanopyInternalPath(f.path)))
+            return false;
+        await git.addAllExceptCanopyState();
+        const committers = commit.uncommitted.map((userId) => commit.named.get(userId) ?? { userId });
+        const trailers = buildEditorTrailers(commit.credited ? [commit.credited, ...committers] : committers, {
+            editedBy: config.gitEditedByTrailers ?? true,
+            coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
+        });
+        await git.commit(appendTrailers(commit.message, trailers));
+        return true;
+    };
+    /** Clear the editors a commit named; a failure leaves them for the next commit to name again. */
+    const markCommitted = async (context, uncommitted) => {
+        if (uncommitted.length === 0)
+            return;
+        try {
+            await getBranchMetadataFileManager(context.branchRoot, context.baseRoot).markEditorsCommitted(uncommitted);
+        }
+        catch (err) {
+            console.warn(`CanopyCMS: Could not clear the committed editors of ${context.branch.name}:`, getErrorMessage(err));
+        }
+    };
+    /** The editors recorded on the branch, each with the name `lookupEditor` gives. */
+    const namedEditors = async (context, lookupEditor) => new Map((await describeEditors((await readRecordedEditors(context))?.editors ?? [], memoizeLookup(lookupEditor))).map((e) => [e.userId, e]));
+    const commitSavedWork = async (options) => {
+        const git = createGitManagerFor(options.context.branchRoot, {
+            baseBranch: options.context.branch.baseBranch,
+        });
+        await git.ensureAuthor({ name: config.gitBotAuthorName, email: config.gitBotAuthorEmail });
+        // Names are looked up before taking the lock, so a slow auth provider never holds it.
+        const named = await namedEditors(options.context, options.lookupEditor);
+        // [SYNC-C1] Locked for the same reason as submitBranch: a commit landing while a rebase is
+        // stopped on a conflict is discarded by its abort.
+        const committed = await withContentWriteLock(options.context.branchRoot, async () => {
+            await refuseDuringRebase(options.context.branchRoot);
+            await git.checkoutBranch(options.context.branch.name);
+            const status = await git.status();
+            const uncommitted = (await readRecordedEditors(options.context))?.uncommittedEditors ?? [];
+            const done = await commitSavedChanges(git, status, {
+                message: options.message,
+                uncommitted,
+                named,
+            });
+            // Inside the lock, as submitBranch does: a save after it would record its editor as still
+            // uncommitted, and this would then clear them with the save left out of the commit.
+            if (done)
+                await markCommitted(options.context, uncommitted);
+            return done;
+        });
+        return committed;
+    };
     /** Runs inside submitBranch's content-write lock; a stamp that fails never blocks the submit. */
     const stampNewEntriesOrWarn = async (context, git) => {
         const contentRoot = services.config.contentRoot || 'content';
@@ -286,6 +354,9 @@ async function _createCanopyServicesInternal(config, options) {
         let recorded = {};
         let stamped = [];
         const submitted = await withContentWriteLock(options.context.branchRoot, async () => {
+            await refuseDuringRebase(options.context.branchRoot);
+            // In the lock, as the worker records a merge's conflicts in it before the merge lands.
+            await assertNoOpenConflicts(options.context.branchRoot);
             await git.checkoutBranch(options.context.branch.name);
             // Before the status read, so the stamp joins this commit even when an earlier attempt
             // already committed the entry and only its push failed.
@@ -303,18 +374,13 @@ async function _createCanopyServicesInternal(config, options) {
             // branch already had unpushed commits from an earlier attempt.
             // canopycms's own state under .canopy-meta/ is never content, so it neither
             // makes a commit worth creating nor gets staged into one.
-            let committed = false;
             const preCommitSha = await git.headSha();
-            if (status.files.some((f) => !isCanopyInternalPath(f.path))) {
-                await git.addAllExceptCanopyState();
-                const committers = uncommitted.map((userId) => named.get(userId) ?? { userId });
-                const trailers = buildEditorTrailers(options.submitter ? [options.submitter, ...committers] : committers, {
-                    editedBy: config.gitEditedByTrailers ?? true,
-                    coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
-                });
-                await git.commit(appendTrailers(options.message ?? `Submit ${options.context.branch.name}`, trailers));
-                committed = true;
-            }
+            const committed = await commitSavedChanges(git, status, {
+                message: options.message ?? `Submit ${options.context.branch.name}`,
+                credited: options.submitter,
+                uncommitted,
+                named,
+            });
             // The diff runs after the commit so it covers saved-but-uncommitted edits too, and
             // before the push so a branch with nothing to submit never reaches the remote. A diff
             // that cannot be computed lets the submit through: the list only feeds the PR body, and
@@ -333,15 +399,8 @@ async function _createCanopyServicesInternal(config, options) {
                     await git.resetKeepingChanges(preCommitSha);
                 throw new NothingToSubmitError(shortNameOf(config, options.context.branch.name), effectiveBase);
             }
-            // A failure here leaves them uncommitted, so the next commit names them again.
-            if (committed && uncommitted.length > 0) {
-                try {
-                    await getBranchMetadataFileManager(options.context.branchRoot, options.context.baseRoot).markEditorsCommitted(uncommitted);
-                }
-                catch (err) {
-                    console.warn(`CanopyCMS: Could not clear the committed editors of ${options.context.branch.name}:`, getErrorMessage(err));
-                }
-            }
+            if (committed)
+                await markCommitted(options.context, uncommitted);
             if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
                 await git.push(options.context.branch.name);
             }
@@ -467,6 +526,7 @@ async function _createCanopyServicesInternal(config, options) {
         githubService,
         bootstrapAdminIds,
         commitFiles,
+        commitSavedWork,
         submitBranch,
         commitToSettingsBranch,
         getSettingsBranchRoot,

package/dist/task-queue/cms-task-queue.d.ts

@@ -5,7 +5,9 @@
  */
 import type { Task, TaskQueueLogger } from './types.js';
 /** Actions the EC2 worker can execute on behalf of Lambda. */
-export type TaskAction = 'push-and-create-pr' | 'push-and-update-pr' | 'push-and-create-or-update-pr' | 'convert-to-draft' | 'close-pr' | 'delete-remote-branch' | 'push-branch' | 'sync-pr-comments';
+export type TaskAction = 'push-and-create-pr' | 'push-and-update-pr' | 'push-and-create-or-update-pr' | 'convert-to-draft' | 'close-pr' | 'delete-remote-branch' | 'push-branch' | 'sync-pr-comments'
+/** Wake the git sync early for `payload.branch` (base-update.ts). */
+ | 'sync-branch';
 /** A task with a CMS-specific action. */
 export type WorkerTask = Task & {
     action: TaskAction;

package/dist/types.d.ts

@@ -115,9 +115,12 @@ export interface BranchMetadata {
     editorUrl?: string;
     /** Sync status for async GitHub operations (used when Lambda has no internet) */
     syncStatus?: SyncStatus;
-    /** Whether any rebase of this branch kept its version of an entry base also changed */
+    /** Whether {@link conflictFiles} names any entry */
     conflictStatus?: ConflictStatus;
-    /** ContentIds of the entries where a rebase kept the branch's version; cleared when it merges */
+    /**
+     * ContentIds of the entries with a merge conflict a person has yet to resolve, derived from the
+     * clone's merge-conflicts.json (merge-conflicts.ts); cleared when the branch merges
+     */
     conflictFiles?: ContentId[];
     /**
      * Lifecycle state of the branch's PR as last observed by the worker's merge-poll
@@ -217,6 +220,29 @@ export interface BranchMetadata {
     uncommittedEditors?: CanopyUserId[];
     /** The reviewer's verdict on the last submit; absent until a reviewer acts. */
     review?: BranchReview;
+    /**
+     * When someone last asked for the latest changes (api/branch-update-from-base.ts). The request
+     * stands while this is newer than `lastBaseUpdate.at`; the editor holds the form read-only and
+     * polls meanwhile, and the worker answers it even after a restart lost its wake-up.
+     */
+    baseUpdateRequestedAt?: string;
+    /** The worker's answer to the latest request for the latest changes (worker/rebase.ts). */
+    lastBaseUpdate?: LastBaseUpdate;
+}
+/** How a requested update from the base went. */
+export type BaseUpdateOutcome = 'merged' | 'up-to-date' | 'conflicts' | 'failed';
+export interface LastBaseUpdate {
+    /**
+     * When the GitHub fetch began that the branch was brought up to, as the gateway reports it
+     * (worker/github-gateway.ts, `GitHubFetchResult.startedAt`): a request is answered only from a
+     * fetch begun at or after it, so a cycle already running when it arrived never ends it.
+     */
+    at: string;
+    outcome: BaseUpdateOutcome;
+    /** The base commit the branch now contains; absent when it failed before reading one. */
+    baseSha?: string;
+    /** For `conflicts`: how many entries the merge left a conflict in for a person. */
+    keptEntries?: number;
 }
 export interface BranchPaths {
     /** Root where all branches live (e.g., /mnt/efs/site, ~/.canopycms/branches) */

package/dist/utils/content-serialize.d.ts

@@ -17,7 +17,7 @@
  * (validation/entry-validator.ts) at the API boundary, not by a schema-blind serialiser.
  */
 import type { FieldConfig } from '../config/index.js';
-import { type MarkdownBodyFormat } from './markdown-body-splice.js';
+import type { MarkdownBodyFormat } from './markdown-parse.js';
 /**
  * Serialise entry data as a YAML file, carrying the comments of `existingRaw` through.
  *
@@ -39,3 +39,20 @@ export declare function serializeYaml(data: Record<string, unknown>, existingRaw
  * what the read path reads, so a `date` field's bare date counts as the day it writes.
  */
 export declare function serializeFrontmatter(editorBody: string, data: Record<string, unknown>, existingRaw: string | undefined, format: MarkdownBodyFormat, fields?: readonly FieldConfig[]): string;
+/** What a save hands the serialiser: `ContentStore.write`'s input, less its version token. */
+export type SerializableEntry = {
+    format: MarkdownBodyFormat;
+    data?: Record<string, unknown>;
+    body: string;
+} | {
+    format: 'json';
+    data: Record<string, unknown>;
+} | {
+    format: 'yaml';
+    data: Record<string, unknown>;
+};
+/**
+ * An entry's file text as a save writes it: `entry` serialised onto `existingRaw`, the file's
+ * current text (absent for a new file). `fields` is the entry type's schema.
+ */
+export declare function serializeEntry(entry: SerializableEntry, existingRaw: string | undefined, fields: readonly FieldConfig[]): string;

package/dist/utils/content-serialize.js

@@ -24,6 +24,7 @@ import { ITEM_KEY, isItemKey } from '../item-keys.js';
 import { withCalendarDays } from './calendar-day.js';
 import { createDebugLogger } from './debug.js';
 import { getErrorMessage } from './error.js';
+import { serializeJson } from './json-source-splice.js';
 import { preserveMarkdownSource } from './markdown-body-splice.js';
 import { snapshotDocument, spliceSource, withSourceLineEndings } from './yaml-source-splice.js';
 const log = createDebugLogger({ prefix: 'ContentSerialize' });
@@ -681,3 +682,14 @@ export function serializeFrontmatter(editorBody, data, existingRaw, format, fiel
     log.debug('content-serialize', 'reconciled frontmatter reads back differently; writing as gray-matter prints it');
     return matter.stringify(file, data);
 }
+/**
+ * An entry's file text as a save writes it: `entry` serialised onto `existingRaw`, the file's
+ * current text (absent for a new file). `fields` is the entry type's schema.
+ */
+export function serializeEntry(entry, existingRaw, fields) {
+    if (entry.format === 'json')
+        return serializeJson(entry.data, existingRaw);
+    if (entry.format === 'yaml')
+        return serializeYaml(entry.data, existingRaw);
+    return serializeFrontmatter(entry.body, entry.data ?? {}, existingRaw, entry.format, fields);
+}

package/dist/utils/content-write-lock.d.ts

@@ -4,9 +4,9 @@
  *
  * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem, so `ContentStore`'s
  * in-process mutex (`utils/async-mutex`) does not cover the worker's rebase (`rebaseOneBranch` in
- * worker/rebase.ts) rewriting the same tree. A write landing after `git rebase` started is
- * destroyed either way -- `git checkout --theirs` overwrites it and the rebase then SUCCEEDS
- * silently, or `git rebase --abort` hard-resets the tree -- and the editor already got its 200.
+ * worker/rebase.ts) rewriting the same tree. A write landing after `git rebase` started makes the
+ * next replayed commit fail, and the `git rebase --abort` that follows hard-resets the tree,
+ * discarding it -- and the editor already got its 200.
  *
  * **Asymmetric by design.** The worker retries every branch on its next sync cycle (~5 minutes)
  * while the editor is a person waiting on a save, so the worker yields and the writer waits:

package/dist/utils/content-write-lock.js

@@ -4,9 +4,9 @@
  *
  * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem, so `ContentStore`'s
  * in-process mutex (`utils/async-mutex`) does not cover the worker's rebase (`rebaseOneBranch` in
- * worker/rebase.ts) rewriting the same tree. A write landing after `git rebase` started is
- * destroyed either way -- `git checkout --theirs` overwrites it and the rebase then SUCCEEDS
- * silently, or `git rebase --abort` hard-resets the tree -- and the editor already got its 200.
+ * worker/rebase.ts) rewriting the same tree. A write landing after `git rebase` started makes the
+ * next replayed commit fail, and the `git rebase --abort` that follows hard-resets the tree,
+ * discarding it -- and the editor already got its 200.
  *
  * **Asymmetric by design.** The worker retries every branch on its next sync cycle (~5 minutes)
  * while the editor is a person waiting on a save, so the worker yields and the writer waits:

package/dist/utils/markdown-body-splice.d.ts

@@ -23,7 +23,7 @@
  * then both again from the edit as sent; failing all four, the restyled edit is written whole,
  * or the edit as sent when it did not read back: the worst case is never different content.
  */
-export type MarkdownBodyFormat = 'md' | 'mdx';
+import { type MarkdownBodyFormat } from './markdown-parse.js';
 /**
  * `text`'s top-level blocks, each as its source text and its `canonical` form, or undefined when
  * `text` does not parse: two bodies mean the same to the splice exactly when their `meaning`

package/dist/utils/markdown-body-splice.js

@@ -23,32 +23,14 @@
  * then both again from the edit as sent; failing all four, the restyled edit is written whole,
  * or the edit as sent when it did not read back: the worst case is never different content.
  */
-import { fromMarkdown } from 'mdast-util-from-markdown';
-import { gfmFromMarkdown } from 'mdast-util-gfm';
-import { mdxFromMarkdown } from 'mdast-util-mdx';
-import { gfm } from 'micromark-extension-gfm';
-import { mdxjs } from 'micromark-extension-mdxjs';
 import { createDebugLogger } from './debug.js';
 import { getErrorMessage } from './error.js';
+import { parseMarkdownBody as parse, } from './markdown-parse.js';
 import { orderedNumber, restyleMarkdown } from './markdown-restyle.js';
 import { withSourceLineEndings } from './yaml-source-splice.js';
 const log = createDebugLogger({ prefix: 'MarkdownBodySplice' });
 /** Above this many LCS cells the middle of a sequence is treated as one changed run. */
 const MAX_LCS_CELLS = 4_000_000;
-function parse(text, format) {
-    try {
-        return format === 'mdx'
-            ? fromMarkdown(text, {
-                extensions: [gfm(), mdxjs()],
-                mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
-            })
-            : fromMarkdown(text, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] });
-    }
-    catch (err) {
-        log.debug('markdown-body-splice', 'body does not parse', { error: getErrorMessage(err) });
-        return undefined;
-    }
-}
 /**
  * A node's meaning as a string: its tree without source positions. `data` goes too, because
  * the parser fills it only with derived information (an MDX expression's estree, which carries

package/dist/utils/markdown-parse.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The md/mdx body parser the save path and the merge engine share, so both read a body the same
+ * way. Dependency-free of node built-ins: the merge engine runs in the browser bundle too.
+ */
+import { fromMarkdown } from 'mdast-util-from-markdown';
+export type MarkdownBodyFormat = 'md' | 'mdx';
+export type MarkdownRoot = ReturnType<typeof fromMarkdown>;
+/** `text`'s mdast with GFM, and MDX for `mdx`; undefined when it does not parse. */
+export declare function parseMarkdownBody(text: string, format: MarkdownBodyFormat): MarkdownRoot | undefined;

package/dist/utils/markdown-parse.js

@@ -0,0 +1,27 @@
+/**
+ * The md/mdx body parser the save path and the merge engine share, so both read a body the same
+ * way. Dependency-free of node built-ins: the merge engine runs in the browser bundle too.
+ */
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { gfmFromMarkdown } from 'mdast-util-gfm';
+import { mdxFromMarkdown } from 'mdast-util-mdx';
+import { gfm } from 'micromark-extension-gfm';
+import { mdxjs } from 'micromark-extension-mdxjs';
+import { createDebugLogger } from './debug.js';
+import { getErrorMessage } from './error.js';
+const log = createDebugLogger({ prefix: 'MarkdownParse' });
+/** `text`'s mdast with GFM, and MDX for `mdx`; undefined when it does not parse. */
+export function parseMarkdownBody(text, format) {
+    try {
+        return format === 'mdx'
+            ? fromMarkdown(text, {
+                extensions: [gfm(), mdxjs()],
+                mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
+            })
+            : fromMarkdown(text, { extensions: [gfm()], mdastExtensions: [gfmFromMarkdown()] });
+    }
+    catch (err) {
+        log.debug('markdown-parse', 'body does not parse', { error: getErrorMessage(err) });
+        return undefined;
+    }
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CANOPYCMS_VERSION = "0.12.0";
+export declare const CANOPYCMS_VERSION = "0.12.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
 // tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
-export const CANOPYCMS_VERSION = '0.12.0';
+export const CANOPYCMS_VERSION = '0.12.1';

package/dist/worker/branch-merge.d.ts

@@ -1,14 +1,30 @@
 import type { SimpleGit } from 'simple-git';
-import { type ContentId } from '../paths/types.js';
-import type { ConflictStatus } from '../types.js';
+import type { KeyRemap } from '../merge/entry-merge.js';
+import type { FoundEntryConflict } from '../merge-conflicts.js';
 import type { WorkerContext } from './worker-context.js';
-/** What {@link buildMergeCommit} made of the two commits. */
-export type BuiltMerge = 
-/** `sha` is the merge, reachable from no ref yet. `conflicted` kept the branch's version. */
-{
-    kind: 'built';
-    sha: string;
-    conflicted: string[];
+/** What {@link planMerge} made of the two commits. */
+export type MergePlan = {
+    kind: 'planned';
+    /** The merge's tree. */
+    tree: string;
+    /** The tree git's own merge wrote, conflict markers and all. */
+    gitTree: string;
+    /** Paths git could not merge, whoever settled them. */
+    gitConflicted: string[];
+    /** What a person must still decide, entry by entry. */
+    conflicts: FoundEntryConflict[];
+    /** Paths where the branch's version stands over the other side's change, whole or in part. */
+    keptPaths: string[];
+    /** Git's own merge with nothing for a person: no conflict, and every file as git merged it. */
+    asGitDoes: boolean;
+    /** Item keys the merge changed, by the entry path the branch's comment threads name. */
+    keyRemaps: Array<{
+        entryPath: string;
+        contentId?: string;
+        remaps: KeyRemap[];
+    }>;
+    /** Where each entry the merge decided stands in it. */
+    paths: Map<string, string>;
 }
 /** Git met conflicts no rule settles safely. Nothing was built. */
  | {
@@ -16,19 +32,40 @@ export type BuiltMerge =
     conflicts: string[];
     paths: string[];
 };
+/** {@link commitMerge}'s commit of a planned merge; `sha` is reachable from no ref yet. */
+export type BuiltMerge = Omit<Extract<MergePlan, {
+    kind: 'planned';
+}>, 'kind' | 'tree' | 'gitTree'> & {
+    kind: 'built';
+    sha: string;
+};
 /**
- * The merge of `other` into `head`, as a commit no ref names, with `head` the first parent. A path
- * git cannot merge keeps `head`'s side, stage 2, at the path git reports, or stays deleted when
- * `head` has no such stage: the rule the rebase loop applies to a conflict, since `head` has the
- * editor's work. The commit takes its identity from the clone's `user.*`, written when the clone
- * is provisioned.
+ * The merge of `other` into `head`, as a tree. Every entry and `.collection.json` both sides
+ * changed is merged field by field (field-merge.ts), which settles git's conflicts there, whatever
+ * their kind. A path git cannot merge that is no entry keeps `head`'s side, stage 2, at the path
+ * git reports, or stays deleted when `head` has no such stage: `head` has the editor's work. With
+ * no single merge base, git's merge stands as that rule leaves it, since a field merge needs one
+ * version both sides started from.
  */
-export declare function buildMergeCommit(git: SimpleGit, clonePath: string, args: {
+export declare function planMerge(git: SimpleGit, clonePath: string, args: {
     head: string;
     other: string;
-    message: string;
+    contentRoot: string;
     timeoutMs: number;
+}): Promise<MergePlan>;
+/**
+ * {@link planMerge}'s merge as a commit no ref names, with `head` the first parent. The commit takes
+ * its identity from the clone's `user.*`, written when the clone is provisioned.
+ */
+export declare function commitMerge(git: SimpleGit, plan: Extract<MergePlan, {
+    kind: 'planned';
+}>, { head, other, message }: {
+    head: string;
+    other: string;
+    message: string;
 }): Promise<BuiltMerge>;
+/** Whether `plan` is git's own merge with nothing for a person. */
+export declare const mergesAsGitDoes: (plan: MergePlan) => boolean;
 /**
  * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else. A
  * conflict counts as no: whoever settled it chose what `merged` holds.
@@ -45,24 +82,3 @@ export declare function commitsApart(git: SimpleGit, a: string, b: string): Prom
     onlyA: number;
     onlyB: number;
 }>;
-/**
- * Map the file paths a rebase or merge kept the branch's version of onto the ContentIds the
- * editor shows as conflicted, deduplicated. IDs rather than paths because they are
- * immutable: a later slug rename must not orphan a conflict marker. Paths that
- * carry no recoverable ID are dropped rather than guessed at.
- *
- * Pure.
- */
-export declare function conflictFilesToContentIds(conflictedFiles: readonly string[], contentRoot: string): ContentId[];
-/**
- * The conflict record after a rebase or merge: the IDs already recorded plus
- * its own. A conflict means this branch's version replaced base's change to
- * that entry, which a later clean rebase does not undo, so the record only
- * grows until the branch merges (buildMergedBranchUpdate clears it).
- *
- * Pure.
- */
-export declare function recordConflicts(recorded: readonly ContentId[] | undefined, found: readonly ContentId[]): {
-    conflictStatus: ConflictStatus;
-    conflictFiles: ContentId[];
-};