canopycms 0.12.1 → 0.13.0

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';
 /**
@@ -80,10 +81,9 @@ export interface CanopyServices {
         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.
+     * 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.
      */
@@ -110,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;

package/dist/services.js

@@ -17,6 +17,7 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { getConfigDefaults } from './config/index.js';
 import { createCheckBranchAccess, createCheckContentAccess, createContentAccessChecker, loadPathPermissions, } from './authorization/index.js';
 import { GitManager, GitRemoteRefMissingError } from './git-manager.js';
@@ -139,6 +140,33 @@ export const createTestCanopyServices = async (config, options = {}) => {
     };
     return _createCanopyServicesInternal(testConfig, options);
 };
+/**
+ * A remote URL's local path as git reads it: a `file://` URL, a drive path, or a path relative to
+ * `cwd` with its links resolved; undefined for a scheme or git's scp form (a colon before any
+ * slash), which name another host.
+ */
+const localPathOf = async (url, cwd) => {
+    if (url.startsWith('file://')) {
+        try {
+            return fileURLToPath(url);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (process.platform === 'win32' && /^[A-Za-z]:[\\/]/.test(url))
+        return path.resolve(url);
+    const colon = url.indexOf(':');
+    const slash = url.search(/[\\/]/);
+    if (colon >= 0 && (slash < 0 || colon < slash))
+        return undefined;
+    return path.resolve(await fs.realpath(cwd).catch(() => cwd), url);
+};
+/** Whether two paths name one directory, symlinks resolved where they exist. */
+const samePath = async (a, b) => {
+    const real = (p) => fs.realpath(p).catch(() => path.resolve(p));
+    return (await real(a)) === (await real(b));
+};
 /** Shared implementation; call createCanopyServices or createTestCanopyServices. */
 async function _createCanopyServicesInternal(config, options) {
     // Mode-specific requirements, e.g. prod's git bot credentials for GitHub.
@@ -269,6 +297,10 @@ async function _createCanopyServicesInternal(config, options) {
         // stopped on a conflict is discarded by its abort.
         const committed = await withContentWriteLock(options.context.branchRoot, async () => {
             await refuseDuringRebase(options.context.branchRoot);
+            // A submit since the caller's read: a branch in review takes no commit until it is withdrawn.
+            const branchStatus = (await readBranchMetadataFile(options.context.branchRoot))?.branch.status;
+            if (branchStatus !== undefined && branchStatus !== 'editing')
+                return false;
             await git.checkoutBranch(options.context.branch.name);
             const status = await git.status();
             const uncommitted = (await readRecordedEditors(options.context))?.uncommittedEditors ?? [];
@@ -509,6 +541,29 @@ async function _createCanopyServicesInternal(config, options) {
             };
         }
     };
+    const runBaseUpdateNow = async (context) => {
+        const mode = services.config.mode;
+        const strategy = operatingStrategy(mode);
+        if (!strategy.baseUpdateRunsInRequest()) {
+            throw new Error(`CanopyCMS: in ${mode} mode the worker answers requests for the latest changes, never a request.`);
+        }
+        // baseRoot is the workspace's content-branches directory, where the worker looks.
+        const workspacePath = path.dirname(context.baseRoot);
+        const origin = await createGitManagerFor(context.branchRoot).getRemoteUrl();
+        const originPath = origin && (await localPathOf(origin, context.branchRoot));
+        if (!originPath || !(await samePath(originPath, path.join(workspacePath, 'remote.git')))) {
+            return 'other-remote';
+        }
+        // Loaded only when a run is asked for: a server that never runs one never loads the worker.
+        const { createLocalWorker } = await import('./worker/cms-worker.js');
+        const worker = createLocalWorker({
+            workspacePath,
+            baseBranch: context.branch.baseBranch ?? baseBranchOf(services.config),
+            contentRoot: services.config.contentRoot || 'content',
+            settingsBranch: strategy.getSettingsBranchName(services.config),
+        });
+        return worker.syncBranchNow(context.branch.name);
+    };
     const operatingMode = config.mode;
     const modeStrategy = operatingStrategy(operatingMode);
     const registry = modeStrategy.supportsBranching()
@@ -528,6 +583,7 @@ async function _createCanopyServicesInternal(config, options) {
         commitFiles,
         commitSavedWork,
         submitBranch,
+        runBaseUpdateNow,
         commitToSettingsBranch,
         getSettingsBranchRoot,
         recordBranchEditor,

package/dist/types.d.ts

@@ -49,6 +49,8 @@ export interface BranchReview {
     };
     /** ISO timestamp of the verdict. */
     at: string;
+    /** The head commit the reviewer's page showed, which the API checked against the clone's. */
+    commit?: string;
 }
 /** What keeps a pull request behind its base. `base` is the branch GitHub says it targets now. */
 export type PullRequestHold = {
@@ -108,9 +110,10 @@ export interface BranchMetadata {
      */
     pushedToGitHubAt?: string;
     /**
-     * The latest editor URL a submit took from its request (editor-url.ts); a submit that took
-     * none, or used config.editorUrl, leaves it as it was. A comment change re-renders the PR's
-     * comment summary with config.editorUrl or this, so a commenter never supplies the links.
+     * The editor URL the latest submit resolved (editor-url.ts): config.editorUrl, else one taken
+     * from its request; a submit that resolved none leaves it as it was. A comment change re-renders
+     * the PR's comment summary with config.editorUrl or this, so a commenter never supplies the
+     * links. The worker links the conflicts status with it (worker/conflicts-status.ts).
      */
     editorUrl?: string;
     /** Sync status for async GitHub operations (used when Lambda has no internet) */
@@ -165,6 +168,12 @@ export interface BranchMetadata {
      * rebase loop's self-heal pass.
      */
     historyRewrittenFrom?: string;
+    /**
+     * The rebased tip of the latest rewrite while `historyRewrittenFrom` is set: the one commit a
+     * rewrite's publish moves `remote.git` to, since the clone can hold a commit made after it that
+     * no one has submitted. Advanced by each rewrite, cleared with the marker.
+     */
+    historyRewrittenTo?: string;
     /**
      * The newest commit this deployment has seen on GitHub's branch, or knows it will hold once a
      * queued push of a rewrite lands: the last one it pushed, took in or published, and any
@@ -228,6 +237,12 @@ export interface BranchMetadata {
     baseUpdateRequestedAt?: string;
     /** The worker's answer to the latest request for the latest changes (worker/rebase.ts). */
     lastBaseUpdate?: LastBaseUpdate;
+    /**
+     * The first base commit the worker's automatic sync left out because the branch holds saved but
+     * uncommitted work, which it never commits (worker/rebase.ts). The editor shows that the latest
+     * changes are waiting; cleared once the sync finds the branch holding the base, or in review.
+     */
+    latestChangesWaiting?: string;
 }
 /** How a requested update from the base went. */
 export type BaseUpdateOutcome = 'merged' | 'up-to-date' | 'conflicts' | 'failed';
@@ -334,6 +349,21 @@ export interface UnpublishableBranchesReport {
     count: number;
     at: string;
 }
+/**
+ * The last git sync's failures to set the "CanopyCMS conflicts" status on pull request heads
+ * (worker/conflicts-status.ts): `permission` when GitHub refused the credential (it lacks the Commit
+ * statuses permission), `unreachable` when GitHub or the gateway could not be reached or GitHub was
+ * busy, `other` for anything else, a gateway refusal or an unreadable conflict record included.
+ * `branches` lists at most 50 names, `count` all of them.
+ */
+export interface ConflictsStatusFailure {
+    reason: 'permission' | 'unreachable' | 'other';
+    /** [REDACT] Served to the admin panel, so sanitized. */
+    message: string;
+    branches: string[];
+    count: number;
+    at: string;
+}
 /**
  * Wire shape of the worker's self-reported status file (worker-status.json, under
  * the task queue dir), written by the CmsWorker daemon. Read-only here: GET
@@ -432,6 +462,8 @@ export interface WorkerStatusReport {
      * into a restarted worker's first snapshot, so the bound survives restarts.
      */
     baseHold?: BaseSchemaHold;
+    /** Present while the last git sync failed to set a conflicts status; not carried over a restart. */
+    conflictsStatusFailure?: ConflictsStatusFailure;
     /**
      * How the last worker that ran stopped, carried into each new worker's snapshot
      * (task-queue/worker-status.ts's `readCarriedOverStatus`). A worker that fails at startup

package/dist/utils/git.d.ts

@@ -99,6 +99,13 @@ export declare function stageAllExceptCanopyState(git: SimpleGit): Promise<void>
  * for).
  */
 export declare function isRebaseInProgress(repoPath: string): Promise<boolean>;
+/**
+ * The commit HEAD names, read from the files: a detached HEAD's sha, or the branch's loose ref,
+ * else its line in `packed-refs`. Null for any other layout, a reftable store among them, which
+ * the caller reads with git instead. Files only, as {@link resolveGitDir} is, for the branch
+ * listing that reads every clone in review (api/branch.ts).
+ */
+export declare function readHeadCommitFromFiles(repoPath: string): Promise<string | null>;
 /**
  * The repository's current HEAD branch name, or `fallback` when detection fails or HEAD is
  * detached.

package/dist/utils/git.js

@@ -223,6 +223,41 @@ export async function isRebaseInProgress(repoPath) {
         .catch(() => false)));
     return results.some(Boolean);
 }
+const FULL_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+/**
+ * The commit HEAD names, read from the files: a detached HEAD's sha, or the branch's loose ref,
+ * else its line in `packed-refs`. Null for any other layout, a reftable store among them, which
+ * the caller reads with git instead. Files only, as {@link resolveGitDir} is, for the branch
+ * listing that reads every clone in review (api/branch.ts).
+ */
+export async function readHeadCommitFromFiles(repoPath) {
+    const gitDir = await resolveGitDir(repoPath);
+    if (!gitDir)
+        return null;
+    try {
+        const head = (await fs.readFile(path.join(gitDir, 'HEAD'), 'utf-8')).trim();
+        if (FULL_SHA.test(head))
+            return head;
+        const ref = /^ref: (refs\/heads\/\S+)$/.exec(head)?.[1];
+        if (!ref || ref.split('/').includes('..'))
+            return null;
+        const commonFile = await fs.readFile(path.join(gitDir, 'commondir'), 'utf-8').catch(() => null);
+        const refsDir = commonFile ? path.resolve(gitDir, commonFile.trim()) : gitDir;
+        const loose = await fs.readFile(path.join(refsDir, ref), 'utf-8').catch(() => null);
+        if (loose !== null)
+            return FULL_SHA.test(loose.trim()) ? loose.trim() : null;
+        const packed = await fs.readFile(path.join(refsDir, 'packed-refs'), 'utf-8').catch(() => '');
+        for (const line of packed.split('\n')) {
+            const [sha, name] = line.split(' ');
+            if (name === ref && FULL_SHA.test(sha))
+                return sha;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The repository's current HEAD branch name, or `fallback` when detection fails or HEAD is
  * detached.

package/dist/version.d.ts

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

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.1';
+export const CANOPYCMS_VERSION = '0.13.0';

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

@@ -67,10 +67,34 @@ export declare function commitMerge(git: SimpleGit, plan: Extract<MergePlan, {
 /** 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.
+ * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else, the
+ * item keys of entries under `contentRoot` aside: a re-key ({@link buildRekey}) changes no content.
+ * A conflict counts as no: whoever settled it chose what `merged` holds.
  */
-export declare function isCleanMergeOf(git: SimpleGit, merged: string, from: string, other: string): Promise<boolean>;
+export declare function isCleanMergeOf(git: SimpleGit, merged: string, from: string, other: string, contentRoot: string): Promise<boolean>;
+/**
+ * A commit on `tip` that gives the items of every entry a merge on the branch's own line in
+ * `from..tip` (first parents: never the base's history) brought in the keys the field merge of
+ * that merge's two parents gives them, where it holds what git merged
+ * (field-merge.ts `rekeyOnly`) and `tip` still holds the merge's version. Git keeps each item under
+ * the key its side's copy held, which can name another item once the other side changed it; the
+ * field merge's are the keys a later merge reads correctly. Null when no item needs a new key.
+ */
+export declare function buildRekey(git: SimpleGit, clonePath: string, args: {
+    from: string;
+    tip: string;
+    contentRoot: string;
+    timeoutMs: number;
+    message: string;
+    /**
+     * Only entries `head` holds as `since` held them: a merge of `head` with the re-key reads an
+     * entry `head` changed against `since`'s keys, which git's merge keeps and a re-key would not.
+     */
+    unchangedIn?: {
+        head: string;
+        since: string;
+    };
+}): Promise<BuiltMerge | null>;
 /**
  * Move `refs/heads/<branchRef>` in remote.git to `sha` as a plain push, so it can only ever
  * fast-forward. Resolves false when it would not: under the caller's locks, the only writers left

package/dist/worker/branch-merge.js

@@ -7,7 +7,8 @@ import { normalizeFilesystemPath } from '../paths/normalize.js';
 import { ROOT_COLLECTION_ID } from '../paths/types.js';
 import { isNonFastForwardRejection } from '../utils/git.js';
 import { getErrorMessage, redactCredentials } from '../utils/error.js';
-import { resolveFieldMerge } from './field-merge.js';
+import { parseTypedFilename } from '../utils/typed-filename.js';
+import { changedFiles, resolveFieldMerge, differsInItemKeysOnly, } from './field-merge.js';
 import { runGit } from './git-process.js';
 import { pinnedReceivePack, sharedRepoGit, sharedRepoProcessOptions } from './shared-repo-git.js';
 /**
@@ -190,10 +191,11 @@ export async function commitMerge(git, plan, { head, other, message }) {
 /** Whether `plan` is git's own merge with nothing for a person. */
 export const mergesAsGitDoes = (plan) => plan.kind === 'planned' && plan.asGitDoes;
 /**
- * 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.
+ * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else, the
+ * item keys of entries under `contentRoot` aside: a re-key ({@link buildRekey}) changes no content.
+ * A conflict counts as no: whoever settled it chose what `merged` holds.
  */
-export async function isCleanMergeOf(git, merged, from, other) {
+export async function isCleanMergeOf(git, merged, from, other, contentRoot) {
     const output = await git.raw([
         'merge-tree',
         '--write-tree',
@@ -205,7 +207,106 @@ export async function isCleanMergeOf(git, merged, from, other) {
     const { tree, stages } = parseMergeTree(output, from, other);
     if (stages.length > 0)
         return false;
-    return (await git.revparse(['--verify', '--end-of-options', `${merged}^{tree}`])).trim() === tree;
+    const mergedTree = (await git.revparse(['--verify', '--end-of-options', `${merged}^{tree}`])).trim();
+    if (mergedTree === tree)
+        return true;
+    for (const { before, after } of await changedFiles(git, tree, mergedTree)) {
+        if (!before || !after || !(await differsInItemKeysOnly(git, before, after, contentRoot))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * A commit on `tip` that gives the items of every entry a merge on the branch's own line in
+ * `from..tip` (first parents: never the base's history) brought in the keys the field merge of
+ * that merge's two parents gives them, where it holds what git merged
+ * (field-merge.ts `rekeyOnly`) and `tip` still holds the merge's version. Git keeps each item under
+ * the key its side's copy held, which can name another item once the other side changed it; the
+ * field merge's are the keys a later merge reads correctly. Null when no item needs a new key.
+ */
+export async function buildRekey(git, clonePath, args) {
+    const { from, tip, contentRoot, timeoutMs, message, unchangedIn } = args;
+    const merges = (await git.raw([
+        'rev-list',
+        '--first-parent',
+        '--merges',
+        '--reverse',
+        '--end-of-options',
+        `${from}..${tip}`,
+    ]))
+        .split('\n')
+        .filter((line) => OBJECT_ID.test(line));
+    if (merges.length === 0)
+        return null;
+    const flatSchema = await readSchemaSnapshot(clonePath);
+    const updates = new Map();
+    const keyRemaps = [];
+    for (const merge of merges) {
+        const parents = (await git.raw(['rev-list', '--parents', '-n', '1', '--end-of-options', merge]))
+            .trim()
+            .split(' ')
+            .slice(1);
+        if (parents.length !== 2)
+            continue;
+        const bases = (await git.raw(['merge-base', '--all', '--end-of-options', ...parents]))
+            .split('\n')
+            .filter((line) => OBJECT_ID.test(line));
+        if (bases.length !== 1)
+            continue;
+        const field = await resolveFieldMerge({
+            git,
+            clonePath,
+            ancestor: bases[0],
+            head: parents[0],
+            other: parents[1],
+            mergedTree: (await git.revparse(['--verify', '--end-of-options', `${merge}^{tree}`])).trim(),
+            conflicted: new Set(),
+            contentRoot,
+            flatSchema,
+            collectionIdOf: (file) => conflictFilesToContentIds([file], contentRoot)[0],
+            timeoutMs,
+            rekeyOnly: true,
+        });
+        const applied = new Set();
+        for (const [file, blob] of field.updates) {
+            // A later commit that changed the entry again decided its keys itself.
+            if (!blob || (await blobAt(git, merge, file)) !== (await blobAt(git, tip, file)))
+                continue;
+            if (unchangedIn &&
+                (await blobAt(git, unchangedIn.head, file)) !== (await blobAt(git, unchangedIn.since, file))) {
+                continue;
+            }
+            updates.set(file, blob);
+            const id = parseTypedFilename(path.posix.basename(file))?.id;
+            if (id !== undefined)
+                applied.add(id);
+        }
+        keyRemaps.push(...field.keyRemaps.filter((r) => r.contentId !== undefined && applied.has(r.contentId)));
+    }
+    if (updates.size === 0)
+        return null;
+    const tipTree = (await git.revparse(['--verify', '--end-of-options', `${tip}^{tree}`])).trim();
+    const tree = await withUpdates(clonePath, { gitTree: tipTree, updates, timeoutMs });
+    const sha = (await git.raw(['commit-tree', '-p', tip, '-m', message, '--end-of-options', tree])).trim();
+    return {
+        kind: 'built',
+        sha,
+        gitConflicted: [],
+        conflicts: [],
+        keptPaths: [],
+        asGitDoes: false,
+        keyRemaps,
+        paths: new Map(),
+    };
+}
+/** The blob `commit` holds at `file`, or null for none. */
+async function blobAt(git, commit, file) {
+    const out = await git
+        .raw(['rev-parse', '--verify', '--quiet', '--end-of-options', `${commit}:${file}`])
+        .catch(() => '');
+    const oid = out.trim();
+    return OBJECT_ID.test(oid) ? oid : null;
 }
 /** `gitTree` with each of `updates` in place, through a throwaway index. */
 async function withUpdates(clonePath, args) {

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

@@ -15,8 +15,8 @@ export declare const MAX_PULL_REQUEST_TITLE_LENGTH = 1024;
  * @internal Exported for tests.
  */
 export declare const MAX_PULL_REQUEST_BODY_LENGTH = 65536;
-export type GatewayOperation = 'push' | 'delete' | 'pull-request';
-export type RefusalReason = 'invalid' | 'protected' | 'settings' | 'other-settings' | 'outside-namespace' | 'not-a-commit' | 'too-long';
+export type GatewayOperation = 'push' | 'delete' | 'pull-request' | 'commit-status';
+export type RefusalReason = 'invalid' | 'protected' | 'settings' | 'other-settings' | 'outside-namespace' | 'not-a-commit' | 'too-long' | 'not-head';
 /** The refusals {@link BranchPolicy.assertPushAllowed} makes. */
 export type PushPolicyRefusal = 'protected' | 'settings' | 'other-settings' | 'outside-namespace';
 /**
@@ -217,3 +217,19 @@ export declare function assertPullRequestText(refusing: string, branch: string,
     title?: string;
     body?: string;
 }): void;
+/**
+ * The longest commit status description the gateway sends, the length GitHub documents for a
+ * deployment status's; its own descriptions are far shorter.
+ * @internal Exported for tests.
+ */
+export declare const MAX_COMMIT_STATUS_DESCRIPTION_LENGTH = 140;
+/** The longest commit status target URL the gateway sends, as the editor URL is capped. */
+export declare const MAX_COMMIT_STATUS_URL_LENGTH = 2048;
+/**
+ * Refuse a commit status description over the cap or holding a control character, and a target
+ * URL that is not plain http(s) or carries credentials. `branch` names the pull request's head.
+ */
+export declare function assertCommitStatusText(refusing: string, branch: string, text: {
+    description: string;
+    targetUrl?: string;
+}): void;

package/dist/worker/branch-policy.js

@@ -442,6 +442,42 @@ export function assertPullRequestText(refusing, branch, text) {
         throw new GatewayRefusalError('pull-request', branch, 'too-long', `${refusing}: ${over}`);
     }
 }
+/**
+ * The longest commit status description the gateway sends, the length GitHub documents for a
+ * deployment status's; its own descriptions are far shorter.
+ * @internal Exported for tests.
+ */
+export const MAX_COMMIT_STATUS_DESCRIPTION_LENGTH = 140;
+/** The longest commit status target URL the gateway sends, as the editor URL is capped. */
+export const MAX_COMMIT_STATUS_URL_LENGTH = 2048;
+/**
+ * Refuse a commit status description over the cap or holding a control character, and a target
+ * URL that is not plain http(s) or carries credentials. `branch` names the pull request's head.
+ */
+export function assertCommitStatusText(refusing, branch, text) {
+    if (text.description.length > MAX_COMMIT_STATUS_DESCRIPTION_LENGTH) {
+        throw new GatewayRefusalError('commit-status', branch, 'too-long', `${refusing}: its description is longer than ${MAX_COMMIT_STATUS_DESCRIPTION_LENGTH} characters`);
+    }
+    // eslint-disable-next-line no-control-regex -- the control characters are what it refuses
+    if (/[\u0000-\u001f\u007f]/.test(text.description)) {
+        throw new GatewayRefusalError('commit-status', branch, 'invalid', `${refusing}: its description holds a control character`);
+    }
+    if (text.targetUrl !== undefined && !isPlainWebUrl(text.targetUrl)) {
+        throw new GatewayRefusalError('commit-status', branch, 'invalid', `${refusing}: its target URL is not a plain http(s) URL of at most ${MAX_COMMIT_STATUS_URL_LENGTH} characters`);
+    }
+}
+function isPlainWebUrl(raw) {
+    if (raw.length > MAX_COMMIT_STATUS_URL_LENGTH)
+        return false;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    return (url.protocol === 'https:' || url.protocol === 'http:') && !url.username && !url.password;
+}
 /** Equal, or naming the same workspace directory. */
 function sameBranch(a, b) {
     return a === b || sanitizeBranchName(a) === sanitizeBranchName(b);

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,7 @@ export declare class CmsWorker {
     private log;
     private statusReport?;
     private warnedDivergences;
+    private conflictsStatusesSet;
     private branchSyncRequests;
     private gitSyncRequested;
     private wakeGitSync;
@@ -510,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;
@@ -517,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`).
@@ -246,6 +246,7 @@ 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.
@@ -365,6 +366,7 @@ 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(),
@@ -1305,12 +1307,21 @@ 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, 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) -----------------------------
     //
     // `syncGit` is the public loop entry `scheduleLoop` drives. The three private
@@ -1349,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 {};