canopycms 0.0.67 → 0.0.68-int.94

package/dist/git-manager.d.ts

@@ -69,6 +69,17 @@ export declare class GitRemoteRefMissingError extends Error {
      */
     gitError?: unknown | undefined);
 }
+/**
+ * No git remote is configured and the one the strategy auto-detects does not
+ * exist yet: in prod, the EC2 worker creates `{workspaceRoot}/remote.git` on
+ * its first boot, so until then every request that needs a workspace fails
+ * here. Usually transient, unlike a missing remote in a mode with nothing to wait for.
+ * The HTTP layer maps it to a 503 (`http/worker-not-ready.ts`).
+ */
+export declare class RemoteNotReadyError extends Error {
+    readonly expectedRemotePath: string;
+    constructor(expectedRemotePath: string);
+}
 export interface ResolveRemoteUrlOptions {
     mode: OperatingMode;
     remoteUrl?: string;
@@ -173,7 +184,7 @@ export declare class GitManager {
      * deleteBranchHandler: a head left in `remote.git` forever makes the
      * create -> publish -> squash-merge -> delete -> reuse-the-name cycle reject
      * the reused branch's first publish non-fast-forward against the stale head
-     * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip is
+     * (`GitManager.push()` pushes the branch to the same name, and a squash-merged old tip is
      * not an ancestor of the new branch), and a retried submit then skips the
      * local push on a clean tree and enqueues the worker push of the STALE head,
      * resurrecting the deleted branch's content on GitHub as an apparent success.
@@ -223,6 +234,8 @@ export declare class GitManager {
      * @param source - Where `url` came from, for the thrown error message only.
      */
     private static assertRemoteUrlAllowedInMode;
+    /** The not-ready error for a mode whose remote is auto-detected, or `undefined` for other modes. */
+    private static remoteNotReadyError;
     /**
      * Resolves the remote URL for git operations following the priority:
      * 1. Explicit remoteUrl parameter
@@ -283,8 +296,15 @@ export declare class GitManager {
     rebaseOntoBase(): Promise<void>;
     private rebaseOntoBaseInner;
     add(files: string | string[]): Promise<void>;
+    /** Stage every working-tree change except canopycms's own state. See {@link stageAllExceptCanopyState}. */
+    addAllExceptCanopyState(): Promise<void>;
     commit(message: string): Promise<void>;
     push(branch?: string): Promise<void>;
+    /**
+     * The checked-out branch's plain name. `rev-parse --abbrev-ref HEAD` prints
+     * `heads/<name>` when a same-named tag exists, which is not a branch name.
+     */
+    private currentBranchName;
     /**
      * Whether the local branch has commits the remote mirror doesn't -- i.e.
      * whether push() would move the remote ref forward.
@@ -303,6 +323,13 @@ export declare class GitManager {
      * ("couldn't find remote ref"); that counts as "ahead", not an error.
      */
     hasUnpushedCommits(branch?: string): Promise<boolean>;
+    /**
+     * Repo-relative paths that differ between HEAD and its merge base with the
+     * base branch: everything the branch changes, across all of its commits.
+     * Diffs against the just-fetched base tip pinned to a SHA — the pullBaseInner
+     * constraint.
+     */
+    listChangedPathsSinceBase(): Promise<string[]>;
     ensureAuthor(author: {
         name: string;
         email: string;
@@ -317,11 +344,58 @@ export declare class GitManager {
      */
     ensureGitExclude(pattern: string): Promise<void>;
     /**
-     * Create an orphan branch (no shared history) for settings, so
-     * deployment-specific settings never pollute content history. It holds only
-     * settings files committed by explicit path (permissions.json, groups.json at
-     * the workspace root).
+     * Put the workspace on the settings branch: an orphan (no shared history),
+     * so deployment-specific settings never pollute content history. It holds
+     * only settings files committed by explicit path (permissions.json,
+     * groups.json at the workspace root).
+     *
+     * The remote is the settings branch's durable copy, and the workspace clone
+     * is `--single-branch` at the base branch, so the remote is asked first:
+     * - no local branch: check out the remote's, or create an empty orphan only
+     *   when the remote has none. An unreadable remote throws
+     *   {@link SettingsRemoteUnreadableError} rather than guess "none".
+     * - local branch present: a history unrelated to the remote's is repaired
+     *   onto the remote's when the local branch is still its empty initial
+     *   commit with a clean working tree, and otherwise throws
+     *   {@link SettingsBranchDivergedError}; local commits are never discarded.
+     *   An unreadable remote throws only for that empty branch, since one that
+     *   holds settings can serve them and the next save surfaces the remote error.
+     * Either way a remote branch holding content is never adopted:
+     * {@link SettingsBranchHasContentHistoryError}.
      */
     createOrphanSettingsBranch(branchName: string, initialFiles: Record<string, string>): Promise<void>;
     private createOrphanSettingsBranchInner;
+    /**
+     * Compares the checked-out local settings branch with the remote's tip.
+     * Related histories are left for the next settings pull to reconcile; only
+     * an unrelated one is acted on here.
+     */
+    private reconcileLocalSettingsBranch;
+    /**
+     * The remote's tip for `branch`, or `undefined` when the remote has no such
+     * branch. A remote that cannot be read throws: `ls-remote` exits 0 with no
+     * output only for a reachable remote without the ref.
+     */
+    private remoteBranchTip;
+    /**
+     * Fetch `branch` from the remote and return the fetched commit, pinned as
+     * pullBaseInner explains. The full ref: a bare name resolves to a
+     * same-named tag first.
+     */
+    private fetchBranchTip;
+    /**
+     * Refuse to adopt a remote settings branch that holds content: its tip has a file other than
+     * the settings files, or its roots include the base branch's (a settings branch is an orphan).
+     * Neither alone suffices: a base can have a root of its own, and a content tree can be pruned.
+     * The base comes from the remote when the clone lacks it (it was cloned at an earlier base).
+     */
+    private assertNotContentHistory;
+    private baseBranchRev;
+    private rootCommits;
+    /**
+     * Whether `branch` is a single parentless commit with an empty tree, as
+     * orphan creation leaves it. Full refs throughout: a bare name resolves to a
+     * same-named tag first, and clones fetch tags.
+     */
+    private isEmptyInitialBranch;
 }

package/dist/git-manager.js

@@ -20,7 +20,7 @@ import { invalidateContentIndexesForRoot } from './content-index-registry.js';
 import { invalidateBranchContentCaches } from './content-index-generation.js';
 import { createDebugLogger } from './utils/debug.js';
 import { getErrorMessage, isNotFoundError } from './utils/error.js';
-import { isMissingRemoteRefFailure, isNetworkRemoteUrl, resolveBaseBranch } from './utils/git.js';
+import { isMissingRemoteRefFailure, isNetworkRemoteUrl, resolveBaseBranch, stageAllExceptCanopyState, } from './utils/git.js';
 import { acquireProvisioningLock } from './utils/provisioning-lock.js';
 const log = createDebugLogger({ prefix: 'GitManager' });
 /**
@@ -166,6 +166,78 @@ export class GitRemoteRefMissingError extends Error {
         this.name = 'GitRemoteRefMissingError';
     }
 }
+/**
+ * No git remote is configured and the one the strategy auto-detects does not
+ * exist yet: in prod, the EC2 worker creates `{workspaceRoot}/remote.git` on
+ * its first boot, so until then every request that needs a workspace fails
+ * here. Usually transient, unlike a missing remote in a mode with nothing to wait for.
+ * The HTTP layer maps it to a 503 (`http/worker-not-ready.ts`).
+ */
+export class RemoteNotReadyError extends Error {
+    constructor(expectedRemotePath) {
+        super(`CanopyCMS: no git remote is available yet. defaultRemoteUrl (or CANOPYCMS_REMOTE_URL) is ` +
+            `not set and the CMS worker has not created ${expectedRemotePath}; the worker may still be starting.`);
+        this.expectedRemotePath = expectedRemotePath;
+        this.name = 'RemoteNotReadyError';
+    }
+}
+/**
+ * Settings provisioning could not read the remote's settings branch, so it cannot tell a remote
+ * that has none from one it failed to reach. It stops instead of starting an empty settings
+ * branch: settings that silently vanish drop restrictive path rules, so content they hid
+ * becomes readable under `defaultPathAccess: { read: 'allow' }`.
+ */
+class SettingsRemoteUnreadableError extends Error {
+    constructor(branch, remote, 
+    /** The underlying git failure; see {@link GitRemoteRefMissingError.gitError}. */
+    gitError) {
+        super(`CanopyCMS: could not read settings branch '${branch}' from remote '${remote}', so ` +
+            `the settings workspace was not provisioned: ${getErrorMessage(gitError)}`);
+        this.branch = branch;
+        this.remote = remote;
+        this.gitError = gitError;
+        this.name = 'SettingsRemoteUnreadableError';
+    }
+}
+/**
+ * The workspace's settings branch shares no history with the remote's and holds work of its
+ * own, so neither copy can be chosen automatically, and a settings save could never pull.
+ */
+class SettingsBranchDivergedError extends Error {
+    constructor(branch, workspacePath, 
+    /** What the workspace holds beyond an empty initial commit. */
+    localWork) {
+        super(`CanopyCMS: settings branch '${branch}' in ${workspacePath} shares no history with the ` +
+            `remote's '${branch}', and holds ${localWork}. Settings saves cannot pull until one copy ` +
+            `is chosen. To keep the remote's settings: copy anything you need out of ` +
+            `${workspacePath}, move it aside, and restart; the next start checks out the remote's ` +
+            `'${branch}', and copied changes can then be re-applied in the editor.`);
+        this.branch = branch;
+        this.workspacePath = workspacePath;
+        this.localWork = localWork;
+        this.name = 'SettingsBranchDivergedError';
+    }
+}
+/** The only files a settings branch ever commits (explicit paths at its root). */
+const SETTINGS_BRANCH_FILES = new Set(['permissions.json', 'groups.json']);
+/**
+ * The remote's settings branch holds content rather than settings. Adopting it would load no
+ * groups or path rules, and settings saves would then commit onto content history.
+ */
+class SettingsBranchHasContentHistoryError extends Error {
+    constructor(branch, remote, 
+    /** What shows it is content. */
+    evidence) {
+        super(`CanopyCMS: the settings branch '${branch}' on remote '${remote}' holds content, not ` +
+            `settings (${evidence}), so it was not checked out. Restore '${branch}' on the remote ` +
+            `from a copy of the settings (it may hold only permissions.json and groups.json), ` +
+            `then restart.`);
+        this.branch = branch;
+        this.remote = remote;
+        this.evidence = evidence;
+        this.name = 'SettingsBranchHasContentHistoryError';
+    }
+}
 export class GitManager {
     constructor(options, gitOptions) {
         this.repoPath = path.resolve(options.repoPath);
@@ -407,7 +479,7 @@ export class GitManager {
      * deleteBranchHandler: a head left in `remote.git` forever makes the
      * create -> publish -> squash-merge -> delete -> reuse-the-name cycle reject
      * the reused branch's first publish non-fast-forward against the stale head
-     * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip is
+     * (`GitManager.push()` pushes the branch to the same name, and a squash-merged old tip is
      * not an ancestor of the new branch), and a retried submit then skips the
      * local push on a clean tree and enqueues the worker push of the STALE head,
      * resurrecting the deleted branch's content on GitHub as an apparent success.
@@ -562,6 +634,12 @@ export class GitManager {
             `intentionally runs git against a network remote (e.g. a single-VM deployment), set ` +
             `config.allowNetworkRemoteInProd: true to acknowledge this.`);
     }
+    /** The not-ready error for a mode whose remote is auto-detected, or `undefined` for other modes. */
+    static async remoteNotReadyError(mode) {
+        const { operatingStrategy } = await import('./operating-mode/index.js');
+        const { autoDetectRemotePath } = operatingStrategy(mode).getRemoteUrlConfig();
+        return autoDetectRemotePath ? new RemoteNotReadyError(autoDetectRemotePath) : undefined;
+    }
     /**
      * Resolves the remote URL for git operations following the priority:
      * 1. Explicit remoteUrl parameter
@@ -686,6 +764,7 @@ export class GitManager {
             }
         }
         let justCloned = false;
+        let resolvedRemoteUrl;
         if (!repoExists) {
             const remoteUrl = await GitManager.resolveRemoteUrl({
                 mode: options.mode,
@@ -696,6 +775,9 @@ export class GitManager {
                 allowNetworkRemoteInProd: options.allowNetworkRemoteInProd,
             });
             if (!remoteUrl) {
+                const notReady = await GitManager.remoteNotReadyError(options.mode);
+                if (notReady)
+                    throw notReady;
                 throw new Error('CanopyCMS: defaultRemoteUrl (or CANOPYCMS_REMOTE_URL) is required to initialize workspace');
             }
             try {
@@ -708,6 +790,7 @@ export class GitManager {
                     `from ${remoteUrl} (base branch '${baseBranch}'): ${getErrorMessage(err)}`);
             }
             justCloned = true;
+            resolvedRemoteUrl = remoteUrl;
             // Mark as managed immediately after clone so ensureRemote's guard works,
             // and set a fallback author identity: GIT_CEILING_DIRECTORIES blocks
             // global gitconfig, and internal commits (e.g. orphan branch init) need
@@ -748,9 +831,20 @@ export class GitManager {
             if (remoteUrl) {
                 await git.ensureRemote(remoteUrl);
             }
+            resolvedRemoteUrl = remoteUrl;
         }
         if (options.branchType === 'orphan') {
-            await git.createOrphanSettingsBranch(options.branchName, {});
+            try {
+                await git.createOrphanSettingsBranch(options.branchName, {});
+            }
+            catch (err) {
+                // A remote that is unreadable because the worker has not (re)created
+                // it yet is the transient not-ready case, not a broken workspace.
+                if (err instanceof SettingsRemoteUnreadableError && !resolvedRemoteUrl) {
+                    throw (await GitManager.remoteNotReadyError(options.mode)) ?? err;
+                }
+                throw err;
+            }
             // Settings mutations hold an OCC lockfile (<file>.lock, see
             // authorization/settings-file-store.ts) inside this git-committed
             // workspace. Commits here stage explicit paths, but a crash-orphaned lock
@@ -893,7 +987,8 @@ export class GitManager {
         const branches = await this.git.branch();
         const currentBranch = branches.current;
         try {
-            await this.git.fetch(this.remote, currentBranch);
+            // The full ref: a bare name resolves to a same-named tag first.
+            await this.git.fetch(this.remote, `refs/heads/${currentBranch}`);
         }
         catch (err) {
             // The only benign failure here: the branch has never been pushed, so the
@@ -970,13 +1065,19 @@ export class GitManager {
         const fileArray = Array.isArray(files) ? files : [files];
         await this.git.add(fileArray);
     }
+    /** Stage every working-tree change except canopycms's own state. See {@link stageAllExceptCanopyState}. */
+    async addAllExceptCanopyState() {
+        await stageAllExceptCanopyState(this.git);
+    }
     async commit(message) {
         await this.git.commit(message);
     }
     async push(branch) {
-        const target = branch ?? (await this.git.revparse(['--abbrev-ref', 'HEAD']));
-        // Explicit refspec (local:remote) so push works for branches not yet in the
-        // remote (e.g. orphan settings branches). Built via raw() rather than the
+        const target = branch ?? (await this.currentBranchName());
+        // Explicit full-ref refspec (local:remote) so push works for branches not
+        // yet in the remote (e.g. orphan settings branches), and a same-named tag
+        // cannot redirect it: a short name for a new remote branch would create
+        // `refs/heads/heads/<name>`. Built via raw() rather than the
         // push() wrapper so `--end-of-options` sits immediately before the
         // positional remote/refspec, guarding against a refspec starting with '-'
         // being parsed as a git option (e.g. --receive-pack=...). Real flags must
@@ -986,9 +1087,20 @@ export class GitManager {
             '--set-upstream',
             '--end-of-options',
             this.remote,
-            `${target}:${target}`,
+            `refs/heads/${target}:refs/heads/${target}`,
         ]);
     }
+    /**
+     * The checked-out branch's plain name. `rev-parse --abbrev-ref HEAD` prints
+     * `heads/<name>` when a same-named tag exists, which is not a branch name.
+     */
+    async currentBranchName() {
+        const branches = await this.git.branch();
+        if (branches.detached || !branches.current) {
+            throw new Error(`CanopyCMS: no branch is checked out (detached HEAD) in ${this.repoPath}`);
+        }
+        return branches.current;
+    }
     /**
      * Whether the local branch has commits the remote mirror doesn't -- i.e.
      * whether push() would move the remote ref forward.
@@ -1010,12 +1122,14 @@ export class GitManager {
         // `--end-of-options` before every caller-influenced ref name, as in push()
         // above: names are sanitized upstream, but this file's rule is that a
         // positional is guarded where it is passed, not where it was validated.
-        const target = branch ?? (await this.git.revparse(['--abbrev-ref', '--end-of-options', 'HEAD']));
-        const localSha = (await this.git.revparse(['--end-of-options', target])).trim();
+        // Each rev-parse needs `--verify`: without it, rev-parse echoes
+        // `--end-of-options` as its own output line ahead of the result.
+        const target = branch ?? (await this.git.revparse(['--verify', '--abbrev-ref', '--end-of-options', 'HEAD']));
+        const localSha = (await this.git.revparse(['--verify', '--end-of-options', target])).trim();
         let fetchedTip;
         try {
             await this.git.raw(['fetch', '--end-of-options', this.remote, target]);
-            fetchedTip = (await this.git.revparse(['--end-of-options', 'FETCH_HEAD'])).trim();
+            fetchedTip = (await this.git.revparse(['--verify', '--end-of-options', 'FETCH_HEAD'])).trim();
         }
         catch {
             // No ref on the remote yet -- the branch has never been pushed.
@@ -1028,6 +1142,27 @@ export class GitManager {
         const aheadCount = (await this.git.raw(['rev-list', '--count', `${fetchedTip}..${localSha}`])).trim();
         return aheadCount !== '0';
     }
+    /**
+     * Repo-relative paths that differ between HEAD and its merge base with the
+     * base branch: everything the branch changes, across all of its commits.
+     * Diffs against the just-fetched base tip pinned to a SHA — the pullBaseInner
+     * constraint.
+     */
+    async listChangedPathsSinceBase() {
+        await this.git.raw(['fetch', '--end-of-options', this.remote, this.baseBranch]);
+        // `--verify`: without it rev-parse echoes `--end-of-options` back as output.
+        const baseTip = (await this.git.revparse(['--verify', '--end-of-options', 'FETCH_HEAD'])).trim();
+        // -z: NUL-separated and unquoted, so no path needs unescaping.
+        const output = await this.git.raw([
+            'diff',
+            '--name-only',
+            '-z',
+            '--no-renames',
+            `${baseTip}...HEAD`,
+            '--',
+        ]);
+        return output.split('\0').filter((p) => p.length > 0);
+    }
     async ensureAuthor(author) {
         const config = (await this.git.listConfig());
         // Verify this is a CanopyCMS-managed workspace before setting author
@@ -1089,10 +1224,24 @@ export class GitManager {
         await ensureGitExcludePattern(this.repoPath, pattern);
     }
     /**
-     * Create an orphan branch (no shared history) for settings, so
-     * deployment-specific settings never pollute content history. It holds only
-     * settings files committed by explicit path (permissions.json, groups.json at
-     * the workspace root).
+     * Put the workspace on the settings branch: an orphan (no shared history),
+     * so deployment-specific settings never pollute content history. It holds
+     * only settings files committed by explicit path (permissions.json,
+     * groups.json at the workspace root).
+     *
+     * The remote is the settings branch's durable copy, and the workspace clone
+     * is `--single-branch` at the base branch, so the remote is asked first:
+     * - no local branch: check out the remote's, or create an empty orphan only
+     *   when the remote has none. An unreadable remote throws
+     *   {@link SettingsRemoteUnreadableError} rather than guess "none".
+     * - local branch present: a history unrelated to the remote's is repaired
+     *   onto the remote's when the local branch is still its empty initial
+     *   commit with a clean working tree, and otherwise throws
+     *   {@link SettingsBranchDivergedError}; local commits are never discarded.
+     *   An unreadable remote throws only for that empty branch, since one that
+     *   holds settings can serve them and the next save surfaces the remote error.
+     * Either way a remote branch holding content is never adopted:
+     * {@link SettingsBranchHasContentHistoryError}.
      */
     async createOrphanSettingsBranch(branchName, initialFiles) {
         try {
@@ -1104,14 +1253,36 @@ export class GitManager {
         }
     }
     async createOrphanSettingsBranchInner(branchName, initialFiles) {
-        log.debug('git', 'Creating orphan settings branch', { branchName });
+        log.debug('git', 'Ensuring settings branch', { branchName });
         const branches = await this.git.branch();
-        if (branches.all.includes(branchName)) {
-            log.debug('git', 'Orphan branch already exists', { branchName });
+        const localExists = branches.all.includes(branchName);
+        if (localExists) {
             // No separator here — see checkoutBranch() above for why plain
             // `git checkout <branch>` can't safely take one. branchName is always an
             // internal/config-derived settings-branch name, never user input.
             await this.git.checkout(branchName);
+        }
+        let remoteTip;
+        try {
+            remoteTip = await this.remoteBranchTip(branchName);
+        }
+        catch (err) {
+            if (localExists && !(await this.isEmptyInitialBranch(branchName))) {
+                log.debug('git', 'Remote unreadable; serving the local settings branch', { branchName });
+                return;
+            }
+            throw new SettingsRemoteUnreadableError(branchName, this.remote, err);
+        }
+        if (localExists) {
+            await this.reconcileLocalSettingsBranch(branchName, remoteTip);
+            return;
+        }
+        if (remoteTip) {
+            const fetchedTip = await this.fetchBranchTip(branchName);
+            await this.assertNotContentHistory(branchName, fetchedTip);
+            // `-b` consumes branchName as its literal value; see checkoutBranchInner.
+            await this.git.raw(['checkout', '-b', branchName, fetchedTip]);
+            log.debug('git', 'Checked out the remote settings branch', { branchName });
             return;
         }
         // branchName is consumed as --orphan's literal argument value (like -b/-B
@@ -1134,4 +1305,123 @@ export class GitManager {
         await this.git.commit('Initialize settings branch', ['--allow-empty']);
         log.debug('git', 'Orphan settings branch created', { branchName });
     }
+    /**
+     * Compares the checked-out local settings branch with the remote's tip.
+     * Related histories are left for the next settings pull to reconcile; only
+     * an unrelated one is acted on here.
+     */
+    async reconcileLocalSettingsBranch(branchName, remoteTip) {
+        if (!remoteTip)
+            return;
+        const localTip = (await this.git.revparse([`refs/heads/${branchName}`])).trim();
+        if (localTip === remoteTip)
+            return;
+        const fetchedTip = await this.fetchBranchTip(branchName);
+        const [localRoots, remoteRoots] = await Promise.all([
+            this.rootCommits(localTip),
+            this.rootCommits(fetchedTip),
+        ]);
+        if (localRoots.some((root) => remoteRoots.includes(root)))
+            return;
+        const localWork = [];
+        if (!(await this.isEmptyInitialBranch(branchName))) {
+            localWork.push('commits beyond its empty initial commit');
+        }
+        const uncommitted = await this.getUncommittedFiles();
+        if (uncommitted.length > 0) {
+            localWork.push(`uncommitted changes to ${uncommitted.join(', ')}`);
+        }
+        if (localWork.length > 0) {
+            throw new SettingsBranchDivergedError(branchName, this.repoPath, localWork.join(' and '));
+        }
+        await this.assertNotContentHistory(branchName, fetchedTip);
+        // `checkout -B` resets the current branch onto the fetched tip, and
+        // refuses rather than overwrite a file written since the check above.
+        await this.git.raw(['checkout', '-B', branchName, fetchedTip]);
+        log.debug('git', 'Replaced an empty settings branch with the remote one', { branchName });
+    }
+    /**
+     * The remote's tip for `branch`, or `undefined` when the remote has no such
+     * branch. A remote that cannot be read throws: `ls-remote` exits 0 with no
+     * output only for a reachable remote without the ref.
+     */
+    async remoteBranchTip(branch) {
+        const ref = `refs/heads/${branch}`;
+        const output = await this.git.raw(['ls-remote', '--heads', this.remote, ref]);
+        for (const line of output.split('\n')) {
+            const [sha, name] = line.trim().split('\t');
+            if (sha && name === ref)
+                return sha;
+        }
+        return undefined;
+    }
+    /**
+     * Fetch `branch` from the remote and return the fetched commit, pinned as
+     * pullBaseInner explains. The full ref: a bare name resolves to a
+     * same-named tag first.
+     */
+    async fetchBranchTip(branch) {
+        await this.git.fetch(this.remote, `refs/heads/${branch}`);
+        return (await this.git.revparse(['FETCH_HEAD'])).trim();
+    }
+    /**
+     * Refuse to adopt a remote settings branch that holds content: its tip has a file other than
+     * the settings files, or its roots include the base branch's (a settings branch is an orphan).
+     * Neither alone suffices: a base can have a root of its own, and a content tree can be pruned.
+     * The base comes from the remote when the clone lacks it (it was cloned at an earlier base).
+     */
+    async assertNotContentHistory(branchName, tip) {
+        const tree = await this.git.raw(['ls-tree', '-r', '--name-only', tip]);
+        const strays = tree.split('\n').filter((file) => file && !SETTINGS_BRANCH_FILES.has(file));
+        if (strays.length > 0) {
+            const shown = strays.slice(0, 3).join(', ') + (strays.length > 3 ? ', …' : '');
+            throw new SettingsBranchHasContentHistoryError(branchName, this.remote, `it holds ${shown}`);
+        }
+        const [tipRoots, baseRoots] = await Promise.all([
+            this.rootCommits(tip),
+            this.baseBranchRev(branchName).then((rev) => this.rootCommits(rev)),
+        ]);
+        if (tipRoots.some((root) => baseRoots.includes(root))) {
+            throw new SettingsBranchHasContentHistoryError(branchName, this.remote, `it shares history with the base branch '${this.baseBranch}'`);
+        }
+    }
+    async baseBranchRev(settingsBranch) {
+        for (const ref of [
+            `refs/heads/${this.baseBranch}`,
+            `refs/remotes/${this.remote}/${this.baseBranch}`,
+        ]) {
+            // `--quiet` makes a missing ref a silent non-zero exit, which simple-git resolves
+            // with empty output rather than rejecting.
+            const sha = await this.git
+                .raw(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+                .catch(() => '');
+            if (sha.trim())
+                return sha.trim();
+        }
+        try {
+            return await this.fetchBranchTip(this.baseBranch);
+        }
+        catch (err) {
+            throw new Error(`CanopyCMS: could not read base branch '${this.baseBranch}' from remote ` +
+                `'${this.remote}', so settings branch '${settingsBranch}' was not checked out: ` +
+                `${getErrorMessage(err)}`);
+        }
+    }
+    async rootCommits(rev) {
+        const output = await this.git.raw(['rev-list', '--max-parents=0', rev]);
+        return output.split('\n').filter(Boolean);
+    }
+    /**
+     * Whether `branch` is a single parentless commit with an empty tree, as
+     * orphan creation leaves it. Full refs throughout: a bare name resolves to a
+     * same-named tag first, and clones fetch tags.
+     */
+    async isEmptyInitialBranch(branch) {
+        const ref = `refs/heads/${branch}`;
+        const commits = await this.git.raw(['rev-list', '--max-count=2', ref]);
+        if (commits.split('\n').filter(Boolean).length !== 1)
+            return false;
+        const tree = await this.git.raw(['ls-tree', ref]);
+        return tree.trim() === '';
+    }
 }

package/dist/github-service.d.ts

@@ -76,6 +76,7 @@ export interface PullRequestDetails {
     state: 'open' | 'closed';
     merged: boolean;
     draft: boolean;
+    body: string;
 }
 export interface CreateOrUpdatePullRequestParams {
     octokit: Octokit;
@@ -87,6 +88,11 @@ export interface CreateOrUpdatePullRequestParams {
     body: string;
     /** Convert a pre-existing draft PR to ready-for-review after updating it. */
     markReadyIfDraft?: boolean;
+    /**
+     * `body` is the canopycms PR section: an existing PR keeps the text outside
+     * its section (see mergePrSection) instead of having its body replaced.
+     */
+    mergeSectionIntoBody?: boolean;
     /** Forwarded to all GitHub requests (worker task-timeout abort). */
     signal?: AbortSignal;
 }
@@ -128,6 +134,8 @@ export declare class GitHubService {
         body: string;
         /** Convert a pre-existing draft PR to ready-for-review after updating it. */
         markReadyIfDraft?: boolean;
+        /** See {@link CreateOrUpdatePullRequestParams.mergeSectionIntoBody}. */
+        mergeSectionIntoBody?: boolean;
     }): Promise<{
         number: number;
         url: string;

package/dist/github-service.js

@@ -7,6 +7,7 @@ import { getErrorMessage } from './utils/error.js';
 // or CloudWatch folds it into the previous event. Under Lambda/dev the helper
 // is plain console. See utils/logger.ts.
 import { canopyLogWarn } from './utils/logger.js';
+import { mergePrSection } from './submission-attribution.js';
 const ThrottledOctokit = Octokit.plugin(throttling);
 /**
  * Retry primary rate limits at most twice and only for short waits; beyond
@@ -67,6 +68,7 @@ export function createCanopyOctokit(options) {
  */
 export async function createOrUpdatePullRequest(params) {
     const { octokit, owner, repo, head, base, title, body, markReadyIfDraft, signal } = params;
+    const mergeSection = params.mergeSectionIntoBody === true;
     // CONDITIONAL spread: with no signal, the request objects below carry no
     // `request` key at all (github-service.test.ts asserts on their exact shape).
     const requestOption = signal ? { request: { signal } } : {};
@@ -92,7 +94,7 @@ export async function createOrUpdatePullRequest(params) {
             repo,
             pull_number: existing.number,
             title,
-            body,
+            body: mergeSection ? mergePrSection(existing.body, body) : body,
             ...requestOption,
         });
         // Only a pre-existing PR can be a draft on this path — pulls.create
@@ -185,6 +187,7 @@ export class GitHubService {
             title: options.title,
             body: options.body,
             markReadyIfDraft: options.markReadyIfDraft,
+            mergeSectionIntoBody: options.mergeSectionIntoBody,
         });
         return { number: result.number, url: result.url };
     }
@@ -200,6 +203,7 @@ export class GitHubService {
             state: response.data.state,
             merged: response.data.merged ?? false,
             draft: response.data.draft ?? false,
+            body: response.data.body ?? '',
         };
     }
     async convertToDraft(prNumber) {