canopycms 0.12.0 → 0.13.0

package/dist/merge-conflicts.js

@@ -0,0 +1,451 @@
+/**
+ * The conflicts the worker's merges found on a branch and nobody has resolved yet:
+ * `.canopy-meta/merge-conflicts.json` in the branch clone, never committed, one record per entry.
+ * The working tree holds the author's value at each one (merge/entry-merge.ts), so nothing here is
+ * needed to read the branch; it is what says which values a person still has to choose.
+ *
+ * `branch.json` `conflictFiles` is derived from it: the content IDs it names, none for a clone with
+ * no such file (`reconcileMergeConflicts`, worker/github-commits.ts).
+ *
+ * Writers run under the comment store's three layers (comment-store.ts): the in-process mutex, the
+ * cross-host lockfile, then version OCC. The worker writes it holding the branch's provisioning and
+ * content-write locks.
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { withLock } from './utils/async-mutex.js';
+import { isNotFoundError } from './utils/error.js';
+import { withOccFileLock, withOccRetry, writeOccJsonFile } from './utils/occ-json-write.js';
+import { isPlainRecord } from './validation/field-traversal.js';
+const MERGE_CONFLICTS_FILE = 'merge-conflicts.json';
+/** A record field naming where the entry is, which both sides moved to different places. */
+export { LOCATION_CONFLICT_KEY } from './merge/conflict-path.js';
+/** The record's format; a file of another is left as it is ({@link MergeConflictsFileFormatError}). */
+const RECORD_SCHEMA = 2;
+// Strict throughout: within one `RECORD_SCHEMA` the format is fixed, so a member this code doesn't
+// know is a file it didn't write, refused rather than dropped on the next write.
+const sidesSchema = z
+    .object({
+    ancestor: z.string().optional(),
+    base: z.string().optional(),
+    branch: z.string().optional(),
+})
+    .strict();
+const dataPathSchema = z.array(z.union([
+    z.object({ field: z.string() }).strict(),
+    z.object({ item: z.string() }).strict(),
+    z.object({ blockData: z.literal(true) }).strict(),
+]));
+const sidePathsSchema = z
+    .object({
+    ancestor: dataPathSchema.optional(),
+    base: dataPathSchema.optional(),
+    branch: dataPathSchema.optional(),
+})
+    .strict();
+const entrySchema = z.lazy(() => z
+    .object({
+    path: z.string(),
+    mergeSha: z.string(),
+    kind: z.enum(['fields', 'deleted-on-base', 'deleted-on-branch', 'unreadable']),
+    sides: sidesSchema,
+    fields: z
+        .array(z
+        .object({
+        key: z.string(),
+        dataPath: dataPathSchema,
+        sidePaths: sidePathsSchema,
+        kind: z.enum(['changed', 'removed-on-base', 'removed-by-you']),
+        item: z.literal(true).optional(),
+        text: z.literal(true).optional(),
+        mergeSha: z.string(),
+        sides: sidesSchema,
+    })
+        .strict())
+        .optional(),
+    previous: entrySchema.optional(),
+})
+    .strict());
+const fileSchema = z
+    .object({
+    schema: z.literal(RECORD_SCHEMA),
+    version: z.number(),
+    writeId: z.string().optional(),
+    landing: z
+        .object({ mergeSha: z.string(), keptOverGitHub: z.array(z.string()).optional() })
+        .strict()
+        .optional(),
+    held: z.object({ aside: z.string(), at: z.string() }).strict().optional(),
+    entries: z.record(z.string(), entrySchema),
+    remaps: z
+        .array(z
+        .object({
+        mergeSha: z.string(),
+        entryPath: z.string(),
+        remaps: z.array(z.object({ within: z.array(z.string()), from: z.string(), to: z.string() }).strict()),
+    })
+        .strict())
+        .optional(),
+})
+    .strict();
+/**
+ * merge-conflicts.json names another format than this module reads, `found`. It is left as it is,
+ * unlike a file that doesn't parse: a worker of that format reads it, and its choices would be lost
+ * if it were set aside. The worker's next merge refuses it too, so the branch shows as failing to
+ * take its base in until the file is dealt with.
+ */
+export class MergeConflictsFileFormatError extends Error {
+    constructor(found) {
+        super(`merge-conflicts.json is in format ${found}, and this code reads format ${RECORD_SCHEMA}; left as it is`);
+        this.found = found;
+        this.name = 'MergeConflictsFileFormatError';
+    }
+}
+/** merge-conflicts.json is there but is not a record this module wrote. */
+export class MergeConflictsFileMalformedError extends Error {
+    constructor(detail) {
+        super(`merge-conflicts.json is malformed: ${detail}`);
+        this.name = 'MergeConflictsFileMalformedError';
+    }
+}
+/**
+ * `existing` with what one merge, `mergeSha`, found. An entry this merge found no conflict in keeps
+ * its record: its value is still the author's, which this merge took as the branch's own change.
+ * A field found again keeps the ancestor it was first found against, and that ancestor's path, so
+ * the person still sees what they started from, and takes this merge's base and branch. An
+ * entry-level conflict replaces the entry's record; an `unreadable` record stands against fields
+ * found later, taking this merge's base and branch. `paths` moves the kept records of entries this
+ * merge moved. Every record this merge changes keeps the one it replaced as `previous`. Pure.
+ */
+export function withFoundConflicts(existing, found, mergeSha, paths = new Map()) {
+    const entries = {};
+    const changed = (prior, next) => ({
+        ...next,
+        mergeSha,
+        ...(prior && { previous: prior }),
+    });
+    for (const [id, entry] of Object.entries(existing)) {
+        const at = paths.get(id);
+        entries[id] =
+            at === undefined || at === entry.path ? entry : changed(entry, { ...entry, path: at });
+    }
+    for (const { contentId, path: at, kind, sides, fields } of found) {
+        const prior = existing[contentId];
+        if (kind !== 'fields' || !fields || fields.length === 0) {
+            entries[contentId] = changed(prior, { path: at, kind, sides });
+            continue;
+        }
+        if (prior?.kind === 'unreadable') {
+            // A version merged as one value nobody has chosen on stands: this merge compared against it
+            // as merged, so its changes would be lost unasked. The choice decides the whole entry, the
+            // fields this merge found included, and compares this merge's versions with the first
+            // ancestor. A deleted entry's record goes once both sides hold the entry again.
+            const { ancestor: _later, ...latest } = sides;
+            const ancestor = prior.sides.ancestor;
+            entries[contentId] = changed(prior, {
+                path: at,
+                kind: prior.kind,
+                sides: { ...latest, ...(ancestor !== undefined && { ancestor }) },
+            });
+            continue;
+        }
+        const priorFields = prior?.kind === 'fields' ? (prior.fields ?? []) : [];
+        const keys = new Set(fields.map((f) => f.key));
+        const kept = priorFields.filter((f) => !keys.has(f.key));
+        const { ancestor: _ours, ...latest } = sides;
+        const now = fields.map((field) => {
+            const earlier = priorFields.find((f) => f.key === field.key);
+            const ancestor = earlier ? earlier.sides.ancestor : sides.ancestor;
+            // The path travels with its blob: the first ancestor's, or none when that had no value here.
+            const { ancestor: _found, ...latestPaths } = field.sidePaths;
+            const ancestorPath = earlier ? earlier.sidePaths.ancestor : field.sidePaths.ancestor;
+            return {
+                ...field,
+                sidePaths: {
+                    ...latestPaths,
+                    ...(ancestorPath !== undefined && { ancestor: ancestorPath }),
+                },
+                mergeSha,
+                sides: { ...latest, ...(ancestor !== undefined && { ancestor }) },
+            };
+        });
+        entries[contentId] = changed(prior, { path: at, kind, sides, fields: [...kept, ...now] });
+    }
+    return entries;
+}
+/**
+ * `field` with the item keys `remaps` changed renamed in its key and data path. Each remap names
+ * an item by the keys it had before this merge, as the comment store's do, so all match against
+ * the original path and apply at once. The key holds one token per data path step but `blockData`.
+ */
+function withRemappedKeys(field, remaps) {
+    const renamed = new Map();
+    for (const { within, from, to } of remaps) {
+        const enclosing = [];
+        field.dataPath.forEach((segment, n) => {
+            if (!('item' in segment))
+                return;
+            const hit = segment.item === from &&
+                enclosing.length === within.length &&
+                enclosing.every((k, m) => k === within[m]);
+            if (hit && !renamed.has(n))
+                renamed.set(n, to);
+            enclosing.push(segment.item);
+        });
+    }
+    if (renamed.size === 0)
+        return field;
+    const dataPath = field.dataPath.map((segment, n) => {
+        const to = renamed.get(n);
+        return to === undefined ? segment : { item: to };
+    });
+    const tokens = [...field.key.matchAll(/([.?]?)([^.?]+)/g)].map(([, sep, name]) => [sep, name]);
+    let token = 0;
+    field.dataPath.forEach((segment, n) => {
+        if ('blockData' in segment)
+            return;
+        const to = renamed.get(n);
+        if (to !== undefined && tokens[token])
+            tokens[token] = [tokens[token][0], to];
+        token++;
+    });
+    const key = tokens.map(([sep, name]) => `${sep}${name}`).join('');
+    return { ...field, key, dataPath };
+}
+/**
+ * `entries` with the item keys a merge, `mergeSha`, changed renamed in the conflicts on record,
+ * as the branch's comment threads are, so a conflict found again under the new key is the same
+ * one. A record this renames keeps the one it replaced as `previous`, so a merge that never lands
+ * gives the old keys back. Pure.
+ */
+export function withRemappedItemKeys(entries, remaps, mergeSha) {
+    const out = { ...entries };
+    for (const { contentId, remaps: changed } of remaps) {
+        const entry = contentId === undefined ? undefined : out[contentId];
+        if (!entry?.fields)
+            continue;
+        const fields = entry.fields.map((field) => withRemappedKeys(field, changed));
+        if (fields.every((field, n) => field === entry.fields?.[n]))
+            continue;
+        out[contentId] = { ...entry, fields, mergeSha, previous: entry };
+    }
+    return out;
+}
+/**
+ * `entries` as the branch's history has them: a record whose `mergeSha` fails `holds` gives back the
+ * one it replaced, or goes when it replaced none, and a record whose merge the branch holds drops
+ * the one it replaced. A field whose own merge fails `holds` goes too, and an entry with no field
+ * left. Pure.
+ */
+export function withoutMergesGone(entries, holds) {
+    const kept = {};
+    for (const [id, newest] of Object.entries(entries)) {
+        let entry = newest;
+        while (entry && !holds(entry.mergeSha))
+            entry = entry.previous;
+        if (!entry)
+            continue;
+        const { previous: _landed, ...landed } = entry;
+        if (landed.kind !== 'fields') {
+            kept[id] = landed;
+            continue;
+        }
+        const fields = (landed.fields ?? []).filter((f) => holds(f.mergeSha));
+        if (fields.length > 0)
+            kept[id] = { ...landed, fields };
+    }
+    return kept;
+}
+/**
+ * `entries` without the fields of `contentId`'s record that `resolved` names, each by its own
+ * `mergeSha` and `key`, and without the record once no field is left. A pair the record no longer
+ * holds, as after a newer merge found that field again, is left out of `cleared`. A record left with
+ * fields keeps its `previous`; a record left with none goes with it, since a merge keeps every field
+ * the record it replaced held, so those were resolved too. Pure.
+ */
+export function withoutResolvedFields(entries, contentId, resolved) {
+    const entry = entries[contentId];
+    if (entry?.kind !== 'fields')
+        return { entries: { ...entries }, cleared: [] };
+    const cleared = [];
+    const fields = (entry.fields ?? []).filter((field) => {
+        const match = resolved.some((r) => r.mergeSha === field.mergeSha && r.key === field.key);
+        if (match)
+            cleared.push({ mergeSha: field.mergeSha, key: field.key });
+        return !match;
+    });
+    const { [contentId]: _resolved, ...rest } = entries;
+    if (cleared.length === 0)
+        return { entries: { ...entries }, cleared };
+    return {
+        entries: fields.length > 0 ? { ...rest, [contentId]: { ...entry, fields } } : rest,
+        cleared,
+    };
+}
+/**
+ * `entries` without `contentId`'s entry-level record, when `mergeSha` is the merge that last changed
+ * it; null when it is not there, or a later merge changed it. Pure.
+ */
+export function withoutEntryConflict(entries, contentId, mergeSha) {
+    const entry = entries[contentId];
+    if (!entry || entry.kind === 'fields' || entry.mergeSha !== mergeSha)
+        return null;
+    const { [contentId]: _resolved, ...rest } = entries;
+    return rest;
+}
+/** How many choices `entries` leave a person: each field conflict, and each entry-level one. */
+export function openConflictCount(entries) {
+    return Object.values(entries).reduce((n, entry) => n + (entry.kind === 'fields' ? (entry.fields ?? []).length : 1), 0);
+}
+/** What `branch.json` holds for `entries`: the content IDs with a conflict open, sorted. */
+export function conflictFilesOf(entries) {
+    const conflictFiles = Object.keys(entries).sort();
+    return {
+        conflictStatus: conflictFiles.length > 0 ? 'conflicts-detected' : 'clean',
+        conflictFiles,
+    };
+}
+/**
+ * A submit or approval refused while the branch has conflicts open, `count` of them, or with none
+ * it can count (`count` null): a record that doesn't parse, which the worker's next cycle sets aside
+ * and holds; one held after that (`held`); or one of another format, left until a developer deals
+ * with it.
+ */
+export class OpenMergeConflictsError extends Error {
+    constructor(count, 
+    /** The record was set aside as unparseable, so which conflicts are open is lost. */
+    held = false) {
+        super(held
+            ? "This branch's record of conflicts was damaged and set aside, so it's on hold until an admin releases it."
+            : count === null
+                ? "Couldn't check this branch for changes that conflict with newer ones. Try again in a moment."
+                : count === 1
+                    ? 'A change on this branch conflicts with a newer change on the site.'
+                    : `${count} changes on this branch conflict with newer changes on the site.`);
+        this.count = count;
+        this.held = held;
+        this.name = 'OpenMergeConflictsError';
+    }
+}
+/**
+ * Throws {@link OpenMergeConflictsError} while `branchRoot`'s record holds a conflict, is held after
+ * one was set aside, or does not parse. A clone with no record has none open.
+ */
+export async function assertNoOpenConflicts(branchRoot) {
+    let record;
+    try {
+        record = await new MergeConflictStore(branchRoot).read();
+    }
+    catch (err) {
+        if (err instanceof MergeConflictsFileMalformedError ||
+            err instanceof MergeConflictsFileFormatError)
+            throw new OpenMergeConflictsError(null);
+        throw err;
+    }
+    if (record?.held)
+        throw new OpenMergeConflictsError(null, true);
+    const count = record ? openConflictCount(record.entries) : 0;
+    if (count > 0)
+        throw new OpenMergeConflictsError(count);
+}
+/** A branch clone's merge-conflicts.json. */
+export class MergeConflictStore {
+    constructor(branchRoot, settleMs) {
+        this.settleMs = settleMs;
+        // Resolved, so two spellings of one branch root share the in-process lock key.
+        this.filePath = path.join(path.resolve(branchRoot), '.canopy-meta', MERGE_CONFLICTS_FILE);
+    }
+    /** Whether the clone has a record at all. */
+    async exists() {
+        return fs.stat(this.filePath).then(() => true, () => false);
+    }
+    /**
+     * Copy a file that does not parse as a record aside, and replace it with a new one that is
+     * `held`, as which conflicts were open is lost with it. Resolves the copy's path, or null when
+     * the file parses by the time the locks are held, as another call may have set it aside.
+     * The new record is written beside the file and renamed over it, so a worker killed at any step
+     * leaves a record that still refuses the gate: the damaged one, or the held one.
+     */
+    async quarantine() {
+        return withLock(this.filePath, () => withOccFileLock(this.filePath, async () => {
+            const parses = await this.read().then(() => true, (err) => {
+                if (err instanceof MergeConflictsFileMalformedError)
+                    return false;
+                throw err;
+            });
+            if (parses)
+                return null;
+            const stamp = `${Date.now()}-${randomUUID().slice(0, 8)}`;
+            const aside = `${this.filePath}.malformed-${stamp}`;
+            await fs.copyFile(this.filePath, aside);
+            const held = { aside: path.basename(aside), at: new Date().toISOString() };
+            const next = `${this.filePath}.held-${stamp}`;
+            await writeOccJsonFile(next, { schema: RECORD_SCHEMA, entries: {}, held }, { expectedVersion: null, settleMs: this.settleMs });
+            await fs.rename(next, this.filePath);
+            return aside;
+        }));
+    }
+    /** The record, or null when the clone has none. Throws on a file that does not parse as one. */
+    async read() {
+        let text;
+        try {
+            text = await fs.readFile(this.filePath, 'utf-8');
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                return null;
+            throw err;
+        }
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            throw new MergeConflictsFileMalformedError('it is not JSON');
+        }
+        const schema = isPlainRecord(json) ? json.schema : undefined;
+        if (typeof schema === 'number' && schema !== RECORD_SCHEMA) {
+            throw new MergeConflictsFileFormatError(schema);
+        }
+        const parsed = fileSchema.safeParse(json);
+        if (!parsed.success)
+            throw new MergeConflictsFileMalformedError(parsed.error.message);
+        return parsed.data;
+    }
+    /**
+     * Replace what the file holds with what `change` makes of it, under the module's locks. `change`
+     * gets null when there is no file yet, and returns null to write nothing; a `held` it leaves out
+     * stays. Resolves what was written, or null.
+     */
+    async update(change) {
+        return withLock(this.filePath, () => withOccFileLock(this.filePath, () => withOccRetry(async () => {
+            const current = await this.read();
+            const next = change(current && {
+                entries: current.entries,
+                ...(current.remaps && { remaps: current.remaps }),
+                ...(current.landing && { landing: current.landing }),
+                ...(current.held && { held: current.held }),
+            });
+            if (next === null)
+                return null;
+            // A hold stays unless the change names `held`, as only a release does, setting it undefined.
+            const held = Object.prototype.hasOwnProperty.call(next, 'held')
+                ? next.held
+                : current?.held;
+            const payload = {
+                schema: RECORD_SCHEMA,
+                entries: next.entries,
+                ...(next.remaps && { remaps: next.remaps }),
+                ...(next.landing && { landing: next.landing }),
+                ...(held && { held }),
+            };
+            await writeOccJsonFile(this.filePath, payload, {
+                expectedVersion: current ? current.version : null,
+                settleMs: this.settleMs,
+            });
+            return next;
+        })));
+    }
+}

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 true;
+    }
     getPermissionsFileName() {
         return 'permissions.json';
     }

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

@@ -39,6 +39,9 @@ class ProdStrategy extends ProdClientSafeStrategy {
             autoDetectRemotePath: path.join(this.getWorkspaceRoot(), 'remote.git'),
         };
     }
+    baseUpdateRunsInRequest() {
+        return false;
+    }
     requiresExistingRepo() {
         return false; // Will clone if needed
     }
@@ -91,6 +94,9 @@ class DevStrategy extends DevClientSafeStrategy {
             envVarName: 'CANOPYCMS_REMOTE_URL',
         };
     }
+    baseUpdateRunsInRequest() {
+        return true;
+    }
     requiresExistingRepo() {
         return false;
     }

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

@@ -33,6 +33,12 @@ export interface ClientSafeStrategy {
     supportsBranching(): boolean;
     supportsComments(): boolean;
     supportsPullRequests(): boolean;
+    /**
+     * Whether a request for the latest changes (base-update.ts) gets an answer, so the editor offers
+     * "Get latest changes": from the worker's sync, or from the request itself
+     * ({@link ClientUnsafeStrategy.baseUpdateRunsInRequest}).
+     */
+    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') */
@@ -74,6 +80,13 @@ export interface ClientUnsafeStrategy extends ClientSafeStrategy {
     getPermissionsFilePath(root: string): string;
     getGroupsFilePath(root: string): string;
     getRemoteUrlConfig(): RemoteUrlConfig;
+    /**
+     * Whether a request for the latest changes runs the worker's merge for its branch in the request
+     * (services.ts `runBaseUpdateNow`), for a mode with no worker loop to answer it. False where the
+     * worker answers: there the request is only queued, and a merge in a request would race the
+     * worker's own.
+     */
+    baseUpdateRunsInRequest(): boolean;
     /** Whether this mode requires an existing git repository */
     requiresExistingRepo(): boolean;
     /** The permissions/groups branch: `canopycms-settings-{deploymentName}`. */

package/dist/services.d.ts

@@ -7,6 +7,7 @@ import { GitManager } from './git-manager.js';
 import { BranchRegistry } from './branch-registry.js';
 import { type GitHubService } from './github-service.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
+import type { BaseUpdateRun } from './base-update.js';
 import { type EditorLookup, type SubmissionEditor } from './submission-attribution.js';
 import { type StampedEntry } from './stamp-on-publish.js';
 /**
@@ -79,13 +80,27 @@ export interface CanopyServices {
         files: string | string[];
         message: string;
     }) => Promise<void>;
+    /**
+     * Commit the branch's saved but uncommitted work in its clone, pushing nothing: only a later
+     * submit publishes it, whatever the worker merges on top (worker/publish-decision.ts). 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: {
@@ -95,6 +110,14 @@ export interface CanopyServices {
         lookupEditor?: EditorLookup;
         message?: string;
     }) => Promise<SubmitBranchResult>;
+    /**
+     * Bring the base into the branch now and answer its request for the latest changes, where the
+     * mode's strategy runs that in the request (operating-mode `baseUpdateRunsInRequest`); rejects
+     * in any other mode, where only the worker may. Resolves `busy` when a lock held the merge back,
+     * the request then answered `failed`, and `other-remote`, running nothing, for a clone of another
+     * remote than the workspace's `remote.git`.
+     */
+    runBaseUpdateNow: (context: BranchContext) => Promise<BaseUpdateRun>;
     /** Commit to the settings branch (for permissions/groups) and push it; never opens a PR */
     commitToSettingsBranch: (options: {
         branchRoot: string;