canopycms 0.12.0 → 0.13.0

package/dist/worker/cms-worker.d.ts

@@ -1,6 +1,7 @@
 import { type GitHubAuthConfig } from './github-auth.js';
 import { type GitHubGateway } from './github-gateway.js';
 import type { WorkerStatusReport } from '../types.js';
+import { type RebaseSummary } from './rebase.js';
 export { PermanentTaskError, isPermanentTaskFailure } from './task-runner.js';
 export { workerLog, workerLogWarn, workerLogError, installWorkerLogger } from './log.js';
 export { resolveWorkerGitHubAuth, normalizeGitHubAppPrivateKey, DEFAULT_GIT_TOKEN_MINT_TIMEOUT_MS, DEFAULT_GITHUB_TOKEN_REFRESH_MIN_INTERVAL_MS, type GitHubAppAuth, type GitHubAuthConfig, } from './github-auth.js';
@@ -205,6 +206,10 @@ export declare class CmsWorker {
     private log;
     private statusReport?;
     private warnedDivergences;
+    private conflictsStatusesSet;
+    private branchSyncRequests;
+    private gitSyncRequested;
+    private wakeGitSync;
     private lockLostMessage?;
     private statusWriterAtLock?;
     private settleSelfStopped;
@@ -333,8 +338,18 @@ export declare class CmsWorker {
      * Run `fn` repeatedly, the next invocation starting `interval` ms after the
      * previous one COMPLETES. setTimeout chaining rather than setInterval, so
      * executions cannot overlap when one runs longer than the interval.
+     *
+     * `early` lets a request cut the rest short to {@link EARLY_RUN_MIN_REST_MS}, or `interval` if
+     * shorter: `setWake`
+     * receives a function that does so while the loop rests, and undefined while a run is in
+     * flight; a request made during a run shows in `requested()` when it ends. Any number of
+     * requests coalesce into one early run.
      */
     private scheduleLoop;
+    /** See {@link WorkerContext.requestBranchSync}. */
+    private requestBranchSync;
+    /** See {@link WorkerContext.takeBranchSyncRequests}; called once per git sync cycle. */
+    private takeBranchSyncRequests;
     private get baseBranch();
     private get sanitizedBaseBranch();
     private requireBaseBranch;
@@ -477,9 +492,9 @@ export declare class CmsWorker {
      */
     private branchWorkspacePath;
     /**
-     * Test-only seam: awaited inside `rebaseActiveBranches()`'s conflict round,
-     * after `git rebase` reported conflicted files and BEFORE the
-     * `checkout --theirs` resolution loop overwrites them. No-op in production.
+     * Test-only seam: awaited inside `rebaseActiveBranches()`'s rebase round,
+     * after `git rebase` reported conflicted files and BEFORE the rebase is
+     * aborted for a merge. No-op in production.
      *
      * A test subclass overrides this to land a real `ContentStore` write at
      * exactly the instant the rebase is mid-flight, with no sleeps or shell
@@ -497,6 +512,13 @@ export declare class CmsWorker {
      */
     protected afterRebaseCompletedForTesting(): Promise<void>;
     private rebaseActiveBranches;
+    /**
+     * Bring the base into one branch now and answer its request for the latest changes
+     * (rebase.ts `syncBranchNow`).
+     */
+    syncBranchNow(branchName: string): Promise<'answered' | 'busy'>;
+    /** Bring the base into every branch now, answering their requests from this run's start. */
+    syncBranchesNow(): Promise<RebaseSummary>;
     syncGit(): Promise<void>;
     private pushSettingsBranches;
     private refreshBaseBranchWorkspace;
@@ -504,3 +526,15 @@ export declare class CmsWorker {
     private pollMergeState;
     refreshAuthCache(): Promise<void>;
 }
+/**
+ * A worker over a workspace with no GitHub, for git steps run where no worker loop runs: dev's
+ * "Get latest changes" (services.ts `runBaseUpdateNow`) and the test app's e2e sync route. It is
+ * never started, so it takes no worker lock. Its GitHub settings are placeholders: a sync asks
+ * GitHub only about a branch's pull request, which dev never opens.
+ */
+export declare function createLocalWorker(options: {
+    workspacePath: string;
+    baseBranch: string;
+    contentRoot: string;
+    settingsBranch?: string;
+}): CmsWorker;

package/dist/worker/cms-worker.js

@@ -20,7 +20,7 @@ import { DEFAULT_SCHEMA_HOLD_MAX_MS, readCarriedBaseHold } from './schema-gate.j
 import { readCarriedGatewayPolicy, readCarriedUnpublishableBranches, } from './unpublishable-branches.js';
 import { SharedRepoRefusalError, UntrustedRepoConfigError, assertSharedRepoConfig, sharedRepoGit, } from './shared-repo-git.js';
 import { executeTask, orphanRecoveryMaxAgeMs, processTaskQueue, pushBranchToGitHub, updateBranchMetadata, } from './task-runner.js';
-import { pollMergeState, runRebaseCycle } from './rebase.js';
+import { pollMergeState, runRebaseCycle, syncBranchNow } from './rebase.js';
 import { cleanupTrashedBranchDirs, pushSettingsBranches, refreshBaseBranchWorkspace, syncGit, } from './git-sync.js';
 // Re-exported because this module is the package's advertised worker
 // entrypoint (`canopycms/worker/cms-worker`).
@@ -227,6 +227,11 @@ export async function recordWorkerStartupFailure(options) {
         await release?.().catch(() => { });
     }
 }
+/**
+ * The shortest rest before a run `scheduleLoop`'s `early` starts, so a request repeated while a
+ * branch stays locked cannot keep the git sync, and its GitHub fetch, running back to back.
+ */
+const EARLY_RUN_MIN_REST_MS = 10_000;
 export class CmsWorker {
     constructor(config) {
         this.config = config;
@@ -241,6 +246,11 @@ export class CmsWorker {
         this.releaseLockFn = null;
         this.log = cmsTaskQueueLogger;
         this.warnedDivergences = new Map();
+        this.conflictsStatusesSet = new Map();
+        // Branches asked for since the git sync last took them (requestBranchSync), by directory name.
+        this.branchSyncRequests = new Set();
+        // Set by any request; cleared by the next cycle, which takes it.
+        this.gitSyncRequested = false;
         /**
          * Settles once the worker has stopped for a reason it chose itself (its lock was
          * compromised), after the drain and its record in worker-status.json. Never settles for a
@@ -356,6 +366,9 @@ export class CmsWorker {
             ensureStatusReport: () => this.ensureStatusReport(),
             ensureSettingsBranch: () => this.ensureSettingsBranch(),
             warnedDivergences: () => this.warnedDivergences,
+            conflictsStatusesSet: () => this.conflictsStatusesSet,
+            requestBranchSync: (branchRef) => this.requestBranchSync(branchRef),
+            takeBranchSyncRequests: () => this.takeBranchSyncRequests(),
             afterConflictDetectedForTesting: () => this.afterConflictDetectedForTesting(),
             afterRebaseCompletedForTesting: () => this.afterRebaseCompletedForTesting(),
         };
@@ -487,7 +500,12 @@ export class CmsWorker {
         const taskInterval = this.config.taskPollInterval ?? 5_000;
         const gitInterval = this.gitSyncIntervalMs;
         this.scheduleLoop('task queue', () => this.processTaskQueue(), taskInterval);
-        this.scheduleLoop('git sync', () => this.syncGit(), gitInterval);
+        this.scheduleLoop('git sync', () => this.syncGit(), gitInterval, {
+            requested: () => this.gitSyncRequested,
+            setWake: (wake) => {
+                this.wakeGitSync = wake;
+            },
+        });
         if (this.config.refreshAuthCache) {
             const cacheInterval = this.config.authCacheRefreshInterval ?? 15 * 60_000;
             this.scheduleLoop('auth cache refresh', () => this.refreshAuthCache(), cacheInterval);
@@ -695,22 +713,53 @@ export class CmsWorker {
      * Run `fn` repeatedly, the next invocation starting `interval` ms after the
      * previous one COMPLETES. setTimeout chaining rather than setInterval, so
      * executions cannot overlap when one runs longer than the interval.
+     *
+     * `early` lets a request cut the rest short to {@link EARLY_RUN_MIN_REST_MS}, or `interval` if
+     * shorter: `setWake`
+     * receives a function that does so while the loop rests, and undefined while a run is in
+     * flight; a request made during a run shows in `requested()` when it ends. Any number of
+     * requests coalesce into one early run.
      */
-    scheduleLoop(label, fn, interval) {
-        const run = () => {
+    scheduleLoop(label, fn, interval, early) {
+        // `delay` counts from `restStartedAt`, so a later wake never pushes the next run out.
+        const run = (delay, restStartedAt = Date.now()) => {
             if (!this.running)
                 return;
-            const timeout = setTimeout(async () => {
+            const fire = async () => {
                 this.activeTimeouts.delete(timeout);
+                early?.setWake(undefined);
                 const operation = fn().catch((err) => {
                     workerLogError('Worker loop error:', err instanceof Error ? err.message : err);
                 });
                 await this.trackOperation(label, operation);
-                run();
-            }, interval);
+                run(early?.requested() ? Math.min(interval, EARLY_RUN_MIN_REST_MS) : interval);
+            };
+            const timeout = setTimeout(fire, Math.max(0, delay - (Date.now() - restStartedAt)));
             this.activeTimeouts.add(timeout);
+            early?.setWake(() => {
+                const rested = Date.now() - restStartedAt;
+                const sooner = Math.max(0, Math.min(interval, EARLY_RUN_MIN_REST_MS) - rested);
+                if (sooner >= delay - rested || !this.activeTimeouts.delete(timeout))
+                    return;
+                clearTimeout(timeout);
+                run(rested + sooner, restStartedAt);
+            });
         };
-        run();
+        run(early?.requested() ? Math.min(interval, EARLY_RUN_MIN_REST_MS) : interval);
+    }
+    /** See {@link WorkerContext.requestBranchSync}. */
+    requestBranchSync(branchRef) {
+        if (branchRef !== undefined)
+            this.branchSyncRequests.add(sanitizeBranchName(branchRef));
+        this.gitSyncRequested = true;
+        this.wakeGitSync?.();
+    }
+    /** See {@link WorkerContext.takeBranchSyncRequests}; called once per git sync cycle. */
+    takeBranchSyncRequests() {
+        const taken = { branches: this.branchSyncRequests, requested: this.gitSyncRequested };
+        this.branchSyncRequests = new Set();
+        this.gitSyncRequested = false;
+        return taken;
     }
     get baseBranch() {
         return this.requireBaseBranch().name;
@@ -1232,9 +1281,9 @@ export class CmsWorker {
         return path.join(this.contentBranchesPath, sanitizeBranchName(branchRefName));
     }
     /**
-     * Test-only seam: awaited inside `rebaseActiveBranches()`'s conflict round,
-     * after `git rebase` reported conflicted files and BEFORE the
-     * `checkout --theirs` resolution loop overwrites them. No-op in production.
+     * Test-only seam: awaited inside `rebaseActiveBranches()`'s rebase round,
+     * after `git rebase` reported conflicted files and BEFORE the rebase is
+     * aborted for a merge. No-op in production.
      *
      * A test subclass overrides this to land a real `ContentStore` write at
      * exactly the instant the rebase is mid-flight, with no sleeps or shell
@@ -1258,11 +1307,20 @@ export class CmsWorker {
     // directly and that calls `pollMergeState` directly. Neither is on
     // WorkerContext, so a stub installed on either is a no-op for production.
     //
-    // `rebaseActiveBranches` also has a consumer outside the test files:
-    // apps/test-app/app/api/e2e-test/rebase/route.ts drives it from an e2e
-    // fixture route. Do not delete it as unused.
-    async rebaseActiveBranches(gatewayPolicy, gitHub) {
-        return runRebaseCycle(this.ctx(), gatewayPolicy, gitHub);
+    async rebaseActiveBranches(gatewayPolicy, gitHub, requested) {
+        return runRebaseCycle(this.ctx(), gatewayPolicy, gitHub, requested);
+    }
+    // --- Runs with no loop ({@link createLocalWorker}) -----------------------
+    /**
+     * Bring the base into one branch now and answer its request for the latest changes
+     * (rebase.ts `syncBranchNow`).
+     */
+    async syncBranchNow(branchName) {
+        return syncBranchNow(this.ctx(), branchName);
+    }
+    /** Bring the base into every branch now, answering their requests from this run's start. */
+    async syncBranchesNow() {
+        return runRebaseCycle(this.ctx(), undefined, undefined, new Set(), { fetchedAt: Date.now() }, true);
     }
     // --- Git-sync cluster (worker/git-sync.ts) -----------------------------
     //
@@ -1302,3 +1360,17 @@ export class CmsWorker {
         }
     }
 }
+/**
+ * A worker over a workspace with no GitHub, for git steps run where no worker loop runs: dev's
+ * "Get latest changes" (services.ts `runBaseUpdateNow`) and the test app's e2e sync route. It is
+ * never started, so it takes no worker lock. Its GitHub settings are placeholders: a sync asks
+ * GitHub only about a branch's pull request, which dev never opens.
+ */
+export function createLocalWorker(options) {
+    return new CmsWorker({
+        ...options,
+        githubOwner: 'local',
+        githubRepo: 'local',
+        githubToken: 'local',
+    });
+}

package/dist/worker/conflicts-status.d.ts

@@ -0,0 +1,20 @@
+import type { ConflictsStatusFailure } from '../types.js';
+import type { GitHubConflictsStatus } from './github-gateway.js';
+import type { WorkerContext } from './worker-context.js';
+export type ConflictsStatusContext = Pick<WorkerContext, 'contentBranchesPath' | 'sanitizedBaseBranch' | 'github' | 'conflictsStatusesSet' | 'shutdownSignal' | 'taskTimeoutMs' | 'requestBranchSync'>;
+/** The state and description a branch's conflict record calls for. */
+type ConflictsStatusText = Pick<GitHubConflictsStatus, 'state' | 'description'>;
+/**
+ * What `branchRoot`'s conflict record calls for: failure with the number of choices open, or while
+ * the record is held after a damaged one was set aside, or does not parse; success otherwise.
+ * @internal Exported for tests.
+ */
+export declare function conflictsStatusOf(branchRoot: string): Promise<ConflictsStatusText>;
+/**
+ * Set the conflicts status on every pull request whose head, as `githubTips` (this cycle's GitHub
+ * fetch) holds it, lacks the one its branch calls for. Returns the failure to report, undefined
+ * when every status was set, or null when the stage could not say: the branches could not be
+ * listed, or a drain cut it off. Never throws.
+ */
+export declare function setConflictsStatuses(ctx: ConflictsStatusContext, githubTips: ReadonlyMap<string, string>): Promise<ConflictsStatusFailure | undefined | null>;
+export {};

package/dist/worker/conflicts-status.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { BranchMetadataFileManager } from '../branch-metadata.js';
+import { BranchMetadataCorruptError } from '../branch-metadata-file.js';
+import { editorDeepLink, resolveEditorUrl } from '../editor-url.js';
+import { MergeConflictStore, MergeConflictsFileFormatError, MergeConflictsFileMalformedError, openConflictCount, } from '../merge-conflicts.js';
+import { getErrorMessage, isNodeError, sanitizeErrorMessage } from '../utils/error.js';
+import { escapeForLog } from '../utils/escape-text.js';
+import { GatewayRefusalError, MAX_COMMIT_STATUS_URL_LENGTH } from './branch-policy.js';
+import { getHttpStatus, isPermissionDenial } from './github-errors.js';
+import { workerLog, workerLogWarn } from './log.js';
+/** The most branch names a failure report lists. */
+const MAX_REPORTED_BRANCHES = 50;
+/**
+ * What `branchRoot`'s conflict record calls for: failure with the number of choices open, or while
+ * the record is held after a damaged one was set aside, or does not parse; success otherwise.
+ * @internal Exported for tests.
+ */
+export async function conflictsStatusOf(branchRoot) {
+    try {
+        const record = await new MergeConflictStore(branchRoot).read();
+        if (record?.held) {
+            return {
+                state: 'failure',
+                description: 'Conflict record set aside: an admin must release the branch in the editor',
+            };
+        }
+        const open = record ? openConflictCount(record.entries) : 0;
+        if (open === 0)
+            return { state: 'success', description: 'No conflicting changes to resolve' };
+        return {
+            state: 'failure',
+            description: open === 1
+                ? '1 conflicting change to resolve in the editor'
+                : `${open} conflicting changes to resolve in the editor`,
+        };
+    }
+    catch (err) {
+        if (err instanceof MergeConflictsFileMalformedError ||
+            err instanceof MergeConflictsFileFormatError) {
+            return { state: 'failure', description: "Couldn't read this branch's conflicts" };
+        }
+        throw err;
+    }
+}
+/**
+ * Set the conflicts status on every pull request whose head, as `githubTips` (this cycle's GitHub
+ * fetch) holds it, lacks the one its branch calls for. Returns the failure to report, undefined
+ * when every status was set, or null when the stage could not say: the branches could not be
+ * listed, or a drain cut it off. Never throws.
+ */
+export async function setConflictsStatuses(ctx, githubTips) {
+    let due;
+    let unreadable;
+    try {
+        ;
+        ({ due, unreadable } = await dueStatuses(ctx, githubTips));
+    }
+    catch (err) {
+        workerLogWarn(`Could not read the branches' conflicts for their status: ${getErrorMessage(err)}`);
+        return null;
+    }
+    const set = ctx.conflictsStatusesSet();
+    const failed = [];
+    let failure;
+    for (const [index, { branch, status, key }] of due.entries()) {
+        if (ctx.shutdownSignal().aborted)
+            return null;
+        try {
+            // Bounded, so a GitHub that stalls holds the sync for one timeout, not one per branch.
+            await ctx
+                .github()
+                .setConflictsStatus(status, AbortSignal.any([ctx.shutdownSignal(), AbortSignal.timeout(ctx.taskTimeoutMs)]));
+            set.set(branch, key);
+            workerLog(`Set the conflicts status of PR #${status.pullRequest} (${escapeForLog(branch)}) at ` +
+                `${status.sha.slice(0, 7)}: ${status.state}`);
+        }
+        catch (err) {
+            if (ctx.shutdownSignal().aborted)
+                return null;
+            if (err instanceof GatewayRefusalError && err.reason === 'not-head') {
+                // GitHub moves a pull request's head a moment after the push, so this cycle's tip can be
+                // ahead of it: one more sync for that tip, and no loop if the two never agree.
+                const asked = `not-head:${branch}`;
+                if (set.get(asked) !== status.sha) {
+                    set.set(asked, status.sha);
+                    ctx.requestBranchSync(branch);
+                }
+                continue;
+            }
+            const message = sanitizeErrorMessage(getErrorMessage(err));
+            failed.push(branch);
+            workerLogWarn(`Could not set the conflicts status of ${escapeForLog(branch)}: ${message}`);
+            // The gateway's refusals for the pull request itself report as `other`, retried each cycle.
+            const reason = err instanceof GatewayRefusalError
+                ? 'other'
+                : isPermissionDenial(err)
+                    ? 'permission'
+                    : isUnreachable(err)
+                        ? 'unreachable'
+                        : 'other';
+            // A refused credential names its remedy over any other failure.
+            if (reason === 'permission' || !failure)
+                failure = { reason, message };
+            // Every later write would meet the same GitHub; the next cycle tries again.
+            if (reason !== 'other') {
+                failed.push(...due.slice(index + 1).map((d) => d.branch));
+                break;
+            }
+        }
+    }
+    // After GitHub's answers, whose reason and remedy come first.
+    for (const u of unreadable)
+        failed.push(u.branch);
+    failure ??= unreadable[0] && { reason: 'other', message: unreadable[0].message };
+    if (!failure)
+        return undefined;
+    return {
+        ...failure,
+        branches: failed.slice(0, MAX_REPORTED_BRANCHES),
+        count: failed.length,
+        at: new Date().toISOString(),
+    };
+}
+/**
+ * A failure to reach GitHub or the gateway, or GitHub busy: no status at all, a timeout, a rate
+ * limit (a 403 that is not a permission denial), or a server error.
+ */
+function isUnreachable(err) {
+    const status = getHttpStatus(err);
+    return status === null || status === 403 || status === 408 || status === 429 || status >= 500;
+}
+/**
+ * Each branch with a pull request whose head lacks the status it calls for, and each whose conflict
+ * record could not be read, which costs only its own status. A branch.json that cannot be read says
+ * nothing of a pull request, so it is logged and skipped. Throws only when the branches directory
+ * cannot be listed.
+ */
+async function dueStatuses(ctx, githubTips) {
+    let entries;
+    try {
+        entries = await fs.readdir(ctx.contentBranchesPath, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return { due: [], unreadable: [] };
+        throw err;
+    }
+    const set = ctx.conflictsStatusesSet();
+    const due = [];
+    const unreadable = [];
+    const cannotRead = (branch, err) => {
+        const message = sanitizeErrorMessage(getErrorMessage(err));
+        workerLogWarn(`Could not read ${escapeForLog(branch)} for its conflicts status: ${message}`);
+        unreadable.push({ branch, message });
+    };
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const dir = entry.name;
+        // The base branch has no pull request; `.trash-*` directories hold purged branches.
+        if (!entry.isDirectory() || dir.startsWith('.') || dir === ctx.sanitizedBaseBranch)
+            continue;
+        const branchRoot = path.join(ctx.contentBranchesPath, dir);
+        let meta;
+        try {
+            meta = await BranchMetadataFileManager.loadOnly(branchRoot);
+        }
+        catch (err) {
+            if (!(err instanceof BranchMetadataCorruptError) &&
+                !(isNodeError(err) && err.code === 'ENOENT'))
+                workerLogWarn(`Could not read ${escapeForLog(dir)}'s branch.json for its conflicts status: ` +
+                    sanitizeErrorMessage(getErrorMessage(err)));
+            continue;
+        }
+        const branch = meta?.branch;
+        if (!branch || branch.status === 'archived' || branch.pullRequestNumber === undefined)
+            continue;
+        if (branch.pullRequestState === 'merged' || branch.pullRequestState === 'closed')
+            continue;
+        const sha = githubTips.get(branch.name);
+        if (sha === undefined)
+            continue;
+        let text;
+        try {
+            text = await conflictsStatusOf(branchRoot);
+        }
+        catch (err) {
+            cannotRead(branch.name, err);
+            continue;
+        }
+        const editorUrl = branch.editorUrl && resolveEditorUrl({ configured: branch.editorUrl });
+        const link = editorUrl && editorDeepLink(editorUrl, branch.name);
+        const status = {
+            pullRequest: branch.pullRequestNumber,
+            sha,
+            ...text,
+            // A link the gateway would refuse is left off, so it never costs the status.
+            ...(link && link.length <= MAX_COMMIT_STATUS_URL_LENGTH && { targetUrl: link }),
+        };
+        const key = JSON.stringify(status);
+        if (set.get(branch.name) !== key)
+            due.push({ branch: branch.name, status, key });
+    }
+    return { due, unreadable };
+}

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

@@ -0,0 +1,80 @@
+import type { SimpleGit } from 'simple-git';
+import type { FlatSchemaItem } from '../config/types.js';
+import { type KeyRemap } from '../merge/entry-merge.js';
+import { type FoundEntryConflict } from '../merge-conflicts.js';
+import type { ContentId } from '../paths/types.js';
+/**
+ * The worker's side of the field merge: which files of a merge the engine (`merge/entry-merge.ts`)
+ * decides, and the blobs it decides them with. A merge's three versions are the merge base
+ * (ancestor), the commit coming in (base) and the branch's own (branch). Every entry file and
+ * `.collection.json` changed on both sides goes through the engine, whether or not git found a
+ * conflict in it: a merge git calls clean can still be wrong, such as a duplicate frontmatter key.
+ *
+ * Entries are paired by the content ID in their file names, and `.collection.json` files by their
+ * collection's, not by path, so a rename on one side meets an edit on the other whatever git's
+ * rename detection makes of it. A collection directory one side moved moves the other side's files
+ * in it too. An entry changed on one side only takes that side's version: where git's rename
+ * detection put something else there, the pairing by ID puts it right.
+ */
+/** A file in one version of the tree. */
+export interface TreeFile {
+    path: string;
+    oid: string;
+    mode: string;
+}
+/** What the resolver makes of a merge, for `planMerge` to stage. */
+export interface FieldMergeResult {
+    /** Paths whose blob in the merge replaces git's: a file, or null for none. */
+    updates: Map<string, TreeFile | null>;
+    /** Every path of the units the resolver decided: git's conflicts on them are settled. */
+    covered: Set<string>;
+    conflicts: FoundEntryConflict[];
+    /** Item keys the merge changed, by the logical path the branch's comment threads name. */
+    keyRemaps: Array<{
+        entryPath: string;
+        contentId?: string;
+        remaps: KeyRemap[];
+    }>;
+    /** Where each entry or collection with a conflict on record may now be: its path in the merge. */
+    paths: Map<string, string>;
+    /** Why git's merge can't be settled by rule, where it can't. */
+    unsettled?: string;
+}
+export interface FieldMergeArgs {
+    git: SimpleGit;
+    clonePath: string;
+    ancestor: string;
+    head: string;
+    other: string;
+    /** The tree git's merge wrote. */
+    mergedTree: string;
+    /** Paths git left conflicted. */
+    conflicted: ReadonlySet<string>;
+    contentRoot: string;
+    /** The branch's entry types, which name conflicts as the "Show changes" drawer does. */
+    flatSchema: readonly FlatSchemaItem[] | undefined;
+    /** The content ID a `.collection.json` path belongs to. */
+    collectionIdOf: (file: string) => ContentId | undefined;
+    timeoutMs: number;
+    /**
+     * Git's merge stands, and only the item keys of an entry both sides changed change: to the field
+     * merge's, where it holds the same content with no conflict ({@link rekeyAsMerged}).
+     */
+    rekeyOnly?: boolean;
+}
+/** `diff-tree --raw` from `from` to `to`, without rename detection: each path's two files. */
+export declare function changedFiles(git: SimpleGit, from: string, to: string): Promise<Array<{
+    path: string;
+    before?: TreeFile;
+    after?: TreeFile;
+}>>;
+/**
+ * Whether two versions of one entry file under `contentRoot` differ in item keys alone: what a
+ * re-key changes. False for anything else, a file's mode or path included.
+ */
+export declare function differsInItemKeysOnly(git: SimpleGit, x: TreeFile, y: TreeFile, contentRoot: string): Promise<boolean>;
+/**
+ * Decide every entry file and `.collection.json` the merge touches. Nothing is staged here: the
+ * result says which blobs replace git's, and which conflicts a person must resolve.
+ */
+export declare function resolveFieldMerge(args: FieldMergeArgs): Promise<FieldMergeResult>;