canopycms 0.0.67 → 0.0.68-int.101

package/dist/services.js

@@ -9,8 +9,13 @@ import { operatingStrategy } from './operating-mode/index.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
 import { enqueueTask } from './task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from './task-queue/task-queue-config.js';
-import { detectHeadBranch } from './utils/git.js';
+import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
+import { timeRequestPhase } from './utils/request-timing.js';
+import { BRANCH_META_DIR } from './branch-metadata-file.js';
+import { appendTrailers, buildEditorTrailers, } from './submission-attribution.js';
+import { getErrorMessage, redactCredentials } from './utils/error.js';
+import { withContentWriteLock } from './utils/content-write-lock.js';
 /**
  * A per-instance active-branch detector with its own 5s TTL cache, in priority
  * order: an explicitly configured value; `defaultBaseBranch ?? 'main'` with no
@@ -97,7 +102,7 @@ async function _createCanopyServicesInternal(config, options) {
     const branchSchemaCache = options.branchSchemaCache ?? new BranchSchemaCache(config.mode);
     const checkBranchAccess = createCheckBranchAccess(config.defaultBranchAccess ?? 'deny', config);
     // Content access loads permissions dynamically from the settings branch (orphan git branch)
-    const getSettingsBranchRoot = options.getSettingsBranchRoot ??
+    const ensureSettingsBranchRoot = options.getSettingsBranchRoot ??
         (async () => {
             const strategy = operatingStrategy(config.mode);
             const settingsRoot = strategy.getSettingsRoot();
@@ -111,9 +116,10 @@ async function _createCanopyServicesInternal(config, options) {
             });
             return settingsRoot;
         });
+    const getSettingsBranchRoot = () => timeRequestPhase('settingsRoot', ensureSettingsBranchRoot);
     const contentAccessDeps = {
         checkBranchAccess,
-        loadPathPermissions,
+        loadPathPermissions: (repoRoot, mode) => timeRequestPhase('permissions', () => loadPathPermissions(repoRoot, mode)),
         defaultPathAccess: config.defaultPathAccess ?? 'deny',
         mode: config.mode,
         getSettingsBranchRoot,
@@ -137,8 +143,13 @@ async function _createCanopyServicesInternal(config, options) {
             name: config.gitBotAuthorName,
             email: config.gitBotAuthorEmail,
         });
-        await git.add(options.files);
-        await git.commit(options.message);
+        // [SYNC-C1] Unlocked, a commit made while a rebase is stopped on a conflict
+        // lands on its detached head with the rebase's half-resolved index, and the
+        // rebase's `--abort` discards it.
+        await withContentWriteLock(options.context.branchRoot, async () => {
+            await git.add(options.files);
+            await git.commit(options.message);
+        });
     };
     const submitBranch = async (options) => {
         // Defense-in-depth: refuse to push the base branch to itself even if the
@@ -156,23 +167,53 @@ async function _createCanopyServicesInternal(config, options) {
             name: config.gitBotAuthorName,
             email: config.gitBotAuthorEmail,
         });
-        await git.checkoutBranch(options.context.branch.name);
-        const status = await git.status();
-        // Commit and push answer two DIFFERENT questions. Committing cleans the
-        // working tree, so one combined "tree is dirty" gate makes a retry after a
-        // failed push a silent no-op: nothing left to commit, the block is skipped,
-        // and success is reported though the commit never reached the remote. Push
-        // whenever there is something new to send — we just committed, or the local
-        // branch already had unpushed commits from an earlier attempt.
-        let committed = false;
-        if (status.files.length > 0) {
-            await git.add('.');
-            await git.commit(options.message ?? `Submit ${options.context.branch.name}`);
-            committed = true;
+        // [SYNC-C1] Commits the whole working tree, so it holds the branch's
+        // content-write lock from checkout through push. Unlocked, its checkout
+        // succeeds while the worker's rebase is stopped on a conflict, the commit
+        // lands on the branch, and the rebase's `--abort` resets the branch past it
+        // after this reported success. The push stays inside so no rebase rewrites
+        // the commit between commit and push.
+        const submitted = await withContentWriteLock(options.context.branchRoot, async () => {
+            await git.checkoutBranch(options.context.branch.name);
+            const status = await git.status();
+            // Commit and push answer two DIFFERENT questions. Committing cleans the
+            // working tree, so one combined "tree is dirty" gate makes a retry after a
+            // failed push a silent no-op: nothing left to commit, the block is skipped,
+            // and success is reported though the commit never reached the remote. Push
+            // whenever there is something new to send — we just committed, or the local
+            // branch already had unpushed commits from an earlier attempt.
+            // canopycms's own state under .canopy-meta/ is never content, so it neither
+            // makes a commit worth creating nor gets staged into one.
+            let committed = false;
+            if (status.files.some((f) => !isCanopyInternalPath(f.path))) {
+                await git.addAllExceptCanopyState();
+                const trailers = buildEditorTrailers(options.submitter ? [options.submitter] : [], {
+                    editedBy: config.gitEditedByTrailers ?? true,
+                    coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
+                });
+                await git.commit(appendTrailers(options.message ?? `Submit ${options.context.branch.name}`, trailers));
+                committed = true;
+            }
+            if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
+                await git.push(options.context.branch.name);
+            }
+            return status;
+        });
+        // The list only feeds the PR body, so a failure to compute it falls back to
+        // this submit's own working-tree changes rather than failing a submit that
+        // has already been pushed.
+        let changedPaths;
+        try {
+            changedPaths = await git.listChangedPathsSinceBase();
         }
-        if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
-            await git.push(options.context.branch.name);
+        catch (err) {
+            console.warn(`CanopyCMS: Could not list the changes on ${options.context.branch.name} against its base; ` +
+                "the PR body lists only this submit's changes:", redactCredentials(getErrorMessage(err)));
+            changedPaths = submitted.files.map((f) => f.path);
         }
+        return {
+            changedPaths: changedPaths.filter((p) => !p.startsWith(`${BRANCH_META_DIR}/`)),
+        };
     };
     // Must be initialized before closures that reference it (commitToSettingsBranch)
     let githubService;
@@ -233,57 +274,31 @@ async function _createCanopyServicesInternal(config, options) {
                     error: error instanceof Error ? error.message : 'Push failed',
                 };
             }
-            // Create or update PR — dual-path like content branches (api/github-sync.ts)
-            if (options.createPR !== false) {
-                // Permissions and groups are read live from the settings workspace
-                // (getSettingsBranchRoot), never from this PR's base branch, so the
-                // change took effect when it was committed and pushed above, before
-                // this PR existed. Merging re-activates nothing; it only records the
-                // change on `base` for review and audit history.
-                const settingsPRBody = 'Automated PR for permission and group changes. These changes already took ' +
-                    'effect in the CMS when they were saved — merging this PR does not change ' +
-                    "what's live; it only records the change here for review and audit history.";
-                // Direct path: githubService available (has internet)
-                if (githubService) {
-                    let prUrl;
-                    try {
-                        // Settings-branch PRs never pass markReadyIfDraft: a settings sync
-                        // has no explicit "submit for review" step the way a content submit
-                        // does, so an existing draft PR stays draft until an admin says so.
-                        const result = await githubService.createOrUpdatePR({
-                            head: settingsBranch,
-                            base: config.defaultBaseBranch ?? 'main',
-                            title: 'Update permissions and groups',
-                            body: settingsPRBody,
-                        });
-                        prUrl = result.url;
-                    }
-                    catch (err) {
-                        console.warn('Failed to create/update PR:', err);
-                        return { committed: true, pushed: true, syncStatus: 'sync-failed' };
-                    }
-                    return { committed: true, pushed: true, prUrl, syncStatus: 'synced' };
-                }
-                // Async path: queue task for worker (prod Lambda has no internet)
-                const taskDir = getTaskQueueDir(config);
-                try {
-                    await enqueueTask(taskDir, {
-                        action: 'push-and-create-or-update-pr',
-                        payload: {
-                            branch: settingsBranch,
-                            baseBranch: config.defaultBaseBranch ?? 'main',
-                            title: 'Update permissions and groups',
-                            body: settingsPRBody,
-                        },
-                    });
-                    return { committed: true, pushed: true, syncStatus: 'pending-sync' };
-                }
-                catch (err) {
-                    console.warn('Failed to enqueue settings PR task:', err);
-                    return { committed: true, pushed: true, syncStatus: 'sync-failed' };
-                }
+            // The settings branch is an orphan: it shares no history with the base
+            // branch, so GitHub rejects a PR for it. The change took effect when it
+            // was committed and pushed above (permissions and groups are read live
+            // from the settings workspace); the only GitHub step is mirroring the
+            // branch, so there is never a PR.
+            if (!operatingStrategy(mode).supportsPullRequests()) {
+                return { committed: true, pushed: true };
+            }
+            // With a githubService the push above already reached GitHub: both it and
+            // the workspace remote come from `defaultRemoteUrl`. Without one (prod
+            // Lambda has no internet) the worker pushes it.
+            if (githubService) {
+                return { committed: true, pushed: true, syncStatus: 'synced' };
+            }
+            try {
+                await enqueueTask(getTaskQueueDir(config), {
+                    action: 'push-branch',
+                    payload: { branch: settingsBranch },
+                });
+                return { committed: true, pushed: true, syncStatus: 'pending-sync' };
+            }
+            catch (err) {
+                console.warn('Failed to enqueue settings push task:', err);
+                return { committed: true, pushed: true, syncStatus: 'sync-failed' };
             }
-            return { committed: true, pushed: true };
         }
         catch (error) {
             return {

package/dist/settings-workspace.d.ts

@@ -8,8 +8,8 @@ import type { OperatingMode } from './operating-mode/index.js';
  * its target, and `GitManager.initializeWorkspace` clones INTO the settings
  * root, which `git clone` refuses if anything is already there. A dedicated
  * dot-directory also keeps this marker out of `path.dirname(settingsRoot)`,
- * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — settings init
- * calls into that while holding this lock, so separate directories make the
+ * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — an in-place
+ * settings re-init calls into that while holding this lock, so separate directories make the
  * nesting obvious rather than incidental. For how a lock's anchor path is
  * chosen, see utils/provisioning-lock.ts and docs/concurrency.md.
  * @internal Exported for tests.
@@ -27,12 +27,32 @@ export interface EnsureSettingsWorkspaceOptions {
  * BranchWorkspaceManager this writes no metadata files and never touches the
  * branch registry.
  *
+ * A first clone follows [PROV-1] (branch-provisioning.ts): it is built in a
+ * staging sibling and renamed into place, so a process killed mid-clone never
+ * leaves a half-made workspace at the settings root. Never sparse: the orphan
+ * init's `git rm -rf .` would leave out-of-cone base files in the tree.
+ *
  * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
  * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
- * across processes and hosts.
+ * across processes and hosts around the publish and every in-place init.
  */
 export declare class SettingsWorkspaceManager {
     private readonly config;
     constructor(config: CanopyConfig);
     ensureGitWorkspace(options: EnsureSettingsWorkspaceOptions): Promise<void>;
+    private initOptions;
+    /**
+     * Layer 2 around the init itself (proper-lockfile: heartbeat-refreshed while the holder lives,
+     * so a slow EFS operation is not mistaken for a crash, and patient retries so a loser WAITS
+     * instead of racing into a concurrent init).
+     */
+    private withInitLock;
+    /** Re-init an existing workspace where it is; false when, under the lock, there is none. */
+    private ensureInPlace;
+    /**
+     * Clone and set up the settings branch in a staging sibling, then publish it under the init
+     * lock, moving an interrupted first init aside to `.trash-settings-*`. A workspace someone
+     * else published meanwhile wins and the staging copy is dropped.
+     */
+    private provisionStaged;
 }

package/dist/settings-workspace.js

@@ -1,14 +1,61 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { GitManager } from './git-manager.js';
+import { removeLeftoverDir, settingsStagingDirName, settingsTrashDirName, } from './branch-provisioning.js';
 import { createDebugLogger } from './utils/debug.js';
-import { getErrorMessage } from './utils/error.js';
+import { getErrorMessage, isNodeError } from './utils/error.js';
+import { canopyLogWarn } from './utils/logger.js';
+import { ProvisionLog } from './utils/provision-log.js';
 import { acquireProvisioningLock } from './utils/provisioning-lock.js';
 import { RESERVED_SETTINGS_BRANCH_PREFIX } from './paths/index.js';
 const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
 // In-memory lock against concurrent init within one process. One lock suffices,
 // unlike content branches, which need one per branch.
 let settingsInitLock = null;
+/**
+ * Settings workspaces this process has fully ensured, keyed by {@link ensuredKey}. A hit
+ * skips the guard, the init lock and initializeWorkspace's dozen git subprocesses, which
+ * otherwise ran on every API request. It is sound because settings freshness never comes from
+ * that pass: it reads the remote only to provision the settings branch or repair an empty one
+ * (GitManager.createOrphanSettingsBranch), saves pull, and every process reads the one shared
+ * workspace. Everything it verified is fixed for the process: the settings-branch name resolves once
+ * from config, the remote URL comes from config, and nothing in CanopyCMS checks the settings
+ * workspace out onto another branch. groups.json and permissions.json are still read from
+ * disk on every request; only the provisioning is memoized. Failures are never recorded. In
+ * dev, a hit also skips re-seeding a deleted `.canopy-dev/remote.git`; a dev-server restart
+ * re-seeds it.
+ *
+ * A hit still reads `.git/HEAD`, so a workspace removed, re-cloned onto another branch, or
+ * caught mid-clone by another process (HEAD still on the base branch) misses and runs the full
+ * path, guard and lock included.
+ */
+const ensuredSettingsWorkspaces = new Set();
+function ensuredKey(options) {
+    return `${path.resolve(options.settingsRoot)}\0${options.branchName}`;
+}
+async function headBranch(settingsRoot) {
+    try {
+        const head = (await fs.readFile(path.join(settingsRoot, '.git', 'HEAD'), 'utf-8')).trim();
+        return head.startsWith('ref: refs/heads/') ? head.slice('ref: refs/heads/'.length) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function checkedOutOn(settingsRoot, branchName) {
+    return (await headBranch(settingsRoot)) === branchName;
+}
+async function hasLocalBranch(settingsRoot, branchName) {
+    const gitDir = path.join(settingsRoot, '.git');
+    try {
+        await fs.access(path.join(gitDir, 'refs', 'heads', branchName));
+        return true;
+    }
+    catch {
+        const packed = await fs.readFile(path.join(gitDir, 'packed-refs'), 'utf-8').catch(() => '');
+        return packed.split('\n').some((line) => line.endsWith(` refs/heads/${branchName}`));
+    }
+}
 const SETTINGS_INIT_LOCK_DIR = '.settings-init';
 const SETTINGS_INIT_LOCK_NAME = 'lock';
 /**
@@ -19,8 +66,8 @@ const SETTINGS_INIT_LOCK_NAME = 'lock';
  * its target, and `GitManager.initializeWorkspace` clones INTO the settings
  * root, which `git clone` refuses if anything is already there. A dedicated
  * dot-directory also keeps this marker out of `path.dirname(settingsRoot)`,
- * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — settings init
- * calls into that while holding this lock, so separate directories make the
+ * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — an in-place
+ * settings re-init calls into that while holding this lock, so separate directories make the
  * nesting obvious rather than incidental. For how a lock's anchor path is
  * chosen, see utils/provisioning-lock.ts and docs/concurrency.md.
  * @internal Exported for tests.
@@ -48,14 +95,49 @@ async function settingsFilesPresent(settingsRoot) {
     }
     return false;
 }
+/**
+ * What occupies the settings root.
+ *
+ * `interrupted` is a first init that died before its settings branch existed: not on this
+ * deployment's settings branch or any `canopycms-settings-*` one, no local ref for it, and no
+ * settings files -- what the rename guard lets through, minus a local settings branch that could
+ * hold unpushed commits. A clone killed in place leaves this behind, often with a stale
+ * `config.lock` that fails every later git config write.
+ */
+async function settingsRootState(options) {
+    let entries;
+    try {
+        entries = await fs.readdir(options.settingsRoot);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return 'vacant';
+        if (isNodeError(err) && err.code === 'ENOTDIR')
+            return 'interrupted';
+        throw err;
+    }
+    if (entries.length === 0)
+        return 'vacant';
+    if (await settingsFilesPresent(options.settingsRoot))
+        return 'in-use';
+    if (!(await GitManager.repoExistsAt(options.settingsRoot)))
+        return 'interrupted';
+    const head = await headBranch(options.settingsRoot);
+    if (head === options.branchName || head?.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX)) {
+        return 'in-use';
+    }
+    if (await hasLocalBranch(options.settingsRoot, options.branchName))
+        return 'in-use';
+    return 'interrupted';
+}
 /**
  * Rename guard (settings-branch protection): refuse to boot when an
  * ALREADY-POPULATED settings workspace would be re-orphaned under a different
  * branch name.
  *
  * Without it, GitManager.initializeWorkspace sees an existing .git, skips the
- * clone, and calls createOrphanSettingsBranch(branchName); for an unknown name
- * git then runs `checkout --orphan <name>` + `rm -rf .` + an empty commit.
+ * clone, and calls createOrphanSettingsBranch(branchName); for a name neither the
+ * workspace nor its remote has, git then runs `checkout --orphan <name>` + `rm -rf .` + an empty commit.
  * Orphan branches share no history, so that is not a migration — it
  * PERMANENTLY WIPES permissions.json/groups.json with nothing to recover from.
  * The trigger is almost always deploymentName / settingsBranch /
@@ -103,8 +185,9 @@ async function assertSettingsWorkspaceIdentity(options) {
             `deploymentName, settingsBranch, or CANOPYCMS_DEPLOYMENT_NAME changed on a ` +
             `deployment that already has a populated settings workspace. To resolve: restore ` +
             `the previous value so this resolves back to ` +
-            `'${currentBranch ?? options.branchName}', or, if starting fresh is genuinely ` +
-            `intended, move ${options.settingsRoot} aside manually first.`);
+            `'${currentBranch ?? options.branchName}', or, if switching is genuinely intended, ` +
+            `move ${options.settingsRoot} aside manually first: the next start checks out ` +
+            `'${options.branchName}' from the remote, or starts it empty if the remote has none.`);
     }
 }
 /**
@@ -113,15 +196,26 @@ async function assertSettingsWorkspaceIdentity(options) {
  * BranchWorkspaceManager this writes no metadata files and never touches the
  * branch registry.
  *
+ * A first clone follows [PROV-1] (branch-provisioning.ts): it is built in a
+ * staging sibling and renamed into place, so a process killed mid-clone never
+ * leaves a half-made workspace at the settings root. Never sparse: the orphan
+ * init's `git rm -rf .` would leave out-of-cone base files in the tree.
+ *
  * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
  * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
- * across processes and hosts.
+ * across processes and hosts around the publish and every in-place init.
  */
 export class SettingsWorkspaceManager {
     constructor(config) {
         this.config = config;
     }
     async ensureGitWorkspace(options) {
+        const key = ensuredKey(options);
+        if (ensuredSettingsWorkspaces.has(key)) {
+            if (await checkedOutOn(options.settingsRoot, options.branchName))
+                return;
+            ensuredSettingsWorkspaces.delete(key);
+        }
         return log.timed('workspace', 'ensureGitWorkspace', async () => {
             // Layer 1: In-memory lock (prevents redundant async calls within same process)
             if (settingsInitLock) {
@@ -141,44 +235,11 @@ export class SettingsWorkspaceManager {
                     // Running it here also means no path reaches initializeWorkspace
                     // without the guard having run in THIS process.
                     await assertSettingsWorkspaceIdentity(options);
-                    // Layer 2: cross-process/cross-host lock around the init itself
-                    // (proper-lockfile: heartbeat-refreshed while the holder lives, so a
-                    // slow EFS clone is not mistaken for a crash, and patient retries so a
-                    // loser WAITS instead of racing into a concurrent clone).
-                    const releaseLock = await acquireProvisioningLock(settingsInitLockTarget(options.settingsRoot), SETTINGS_INIT_LOCK_NAME);
-                    try {
-                        // Re-run the guard on the now-stable state: a previous holder may
-                        // have created the workspace, or moved it onto its own settings
-                        // branch, after we sampled it above, and acting on that stale
-                        // sample is the destructive path the guard exists to stop. Not
-                        // gated on any "did I win the race" flag — by design there is none;
-                        // every process here either holds the lock or has already thrown.
-                        await assertSettingsWorkspaceIdentity(options);
-                        // initializeWorkspace is idempotent (it checks for .git), so this
-                        // is safe even if another process just finished init.
-                        await GitManager.initializeWorkspace({
-                            workspacePath: options.settingsRoot,
-                            branchName: options.branchName,
-                            mode: options.mode,
-                            baseBranch: this.config.defaultBaseBranch,
-                            sourceRoot: this.config.sourceRoot,
-                            defaultRemoteUrl: this.config.defaultRemoteUrl,
-                            remoteUrl: options.remoteUrl,
-                            remoteName: this.config.defaultRemoteName,
-                            allowNetworkRemoteInProd: this.config.allowNetworkRemoteInProd,
-                            branchType: 'orphan', // Key difference: orphan branch for settings
-                            gitBotAuthorName: this.config.gitBotAuthorName,
-                            gitBotAuthorEmail: this.config.gitBotAuthorEmail,
-                        });
-                    }
-                    finally {
-                        try {
-                            await releaseLock();
-                        }
-                        catch (err) {
-                            log.debug('workspace', 'Failed to release settings-init lock', { err });
-                        }
+                    if ((await settingsRootState(options)) !== 'in-use' ||
+                        !(await this.ensureInPlace(options))) {
+                        await this.provisionStaged(options);
                     }
+                    ensuredSettingsWorkspaces.add(key);
                 }
                 finally {
                     settingsInitLock = null;
@@ -187,4 +248,95 @@ export class SettingsWorkspaceManager {
             await settingsInitLock;
         });
     }
+    initOptions(options, workspacePath) {
+        return {
+            workspacePath,
+            branchName: options.branchName,
+            mode: options.mode,
+            baseBranch: this.config.defaultBaseBranch,
+            sourceRoot: this.config.sourceRoot,
+            defaultRemoteUrl: this.config.defaultRemoteUrl,
+            remoteUrl: options.remoteUrl,
+            remoteName: this.config.defaultRemoteName,
+            allowNetworkRemoteInProd: this.config.allowNetworkRemoteInProd,
+            branchType: 'orphan',
+            gitBotAuthorName: this.config.gitBotAuthorName,
+            gitBotAuthorEmail: this.config.gitBotAuthorEmail,
+        };
+    }
+    /**
+     * Layer 2 around the init itself (proper-lockfile: heartbeat-refreshed while the holder lives,
+     * so a slow EFS operation is not mistaken for a crash, and patient retries so a loser WAITS
+     * instead of racing into a concurrent init).
+     */
+    async withInitLock(options, run) {
+        const releaseLock = await acquireProvisioningLock(settingsInitLockTarget(options.settingsRoot), SETTINGS_INIT_LOCK_NAME);
+        try {
+            // Re-run the guard on the now-stable state: a previous holder may
+            // have created the workspace, or moved it onto its own settings
+            // branch, after we sampled it above, and acting on that stale
+            // sample is the destructive path the guard exists to stop. Not
+            // gated on any "did I win the race" flag — by design there is none;
+            // every process here either holds the lock or has already thrown.
+            await assertSettingsWorkspaceIdentity(options);
+            return await run();
+        }
+        finally {
+            try {
+                await releaseLock();
+            }
+            catch (err) {
+                log.debug('workspace', 'Failed to release settings-init lock', { err });
+            }
+        }
+    }
+    /** Re-init an existing workspace where it is; false when, under the lock, there is none. */
+    async ensureInPlace(options) {
+        return this.withInitLock(options, async () => {
+            if ((await settingsRootState(options)) !== 'in-use')
+                return false;
+            await GitManager.initializeWorkspace(this.initOptions(options, options.settingsRoot));
+            return true;
+        });
+    }
+    /**
+     * Clone and set up the settings branch in a staging sibling, then publish it under the init
+     * lock, moving an interrupted first init aside to `.trash-settings-*`. A workspace someone
+     * else published meanwhile wins and the staging copy is dropped.
+     */
+    async provisionStaged(options) {
+        const settingsRoot = path.resolve(options.settingsRoot);
+        const workspaceRoot = path.dirname(settingsRoot);
+        await fs.mkdir(workspaceRoot, { recursive: true });
+        const stagingPath = path.join(workspaceRoot, settingsStagingDirName());
+        const provisionLog = new ProvisionLog('settings');
+        let published = false;
+        try {
+            await GitManager.initializeWorkspace({
+                ...this.initOptions(options, stagingPath),
+                provisionLog,
+            });
+            published = await provisionLog.step('publish', () => this.withInitLock(options, async () => {
+                const state = await settingsRootState(options);
+                if (state === 'in-use')
+                    return false;
+                if (state === 'interrupted') {
+                    const trashName = settingsTrashDirName();
+                    await fs.rename(settingsRoot, path.join(workspaceRoot, trashName));
+                    canopyLogWarn(`[canopy] Moved an unfinished settings workspace clone aside as ${trashName}`);
+                }
+                await fs.rename(stagingPath, settingsRoot);
+                return true;
+            }));
+        }
+        catch (err) {
+            provisionLog.finish('error');
+            throw err;
+        }
+        finally {
+            if (!published)
+                await removeLeftoverDir(stagingPath);
+        }
+        provisionLog.finish(published ? 'ok' : 'exists');
+    }
 }

package/dist/static/seo.d.ts

@@ -9,14 +9,14 @@
  * entry-schema.ts, which builds a schema group from these same names so the schema side and
  * the read side cannot drift.
  */
-import { isAbsoluteUrl, stripTrailingSlashes } from '../utils/url-prefix.js';
+import { isAbsoluteUrl, stripTrailingSlashes, withTrailingSlash } from '../utils/url-prefix.js';
 /**
  * Re-exported so this module's public surface (and `canopycms/server`'s, via `static/index.ts`)
  * is unchanged by their move to `utils/url-prefix.ts` — where they now sit beside
  * `joinUrlPrefix`, the shared join that `assets/asset-url.ts` also needs and that must not
  * import anything under `static/`.
  */
-export { isAbsoluteUrl, stripTrailingSlashes };
+export { isAbsoluteUrl, stripTrailingSlashes, withTrailingSlash };
 /** og:type values covered by the recommended group. */
 export type SeoOgType = 'website' | 'article' | 'profile';
 /** twitter:card values covered by the recommended group. */
@@ -87,18 +87,6 @@ export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFi
  * resolves for anyone holding the link.
  */
 export declare function isNoindexEntry(entryData: unknown, opts?: SeoFieldLocation): boolean;
-/**
- * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
- *
- * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
- * `/blog/rss.xml`) alone, and never doubles an existing slash.
- *
- * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
- * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
- * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
- * with a trailing slash" means and breaks the URL).
- */
-export declare function withTrailingSlash(path: string): string;
 export interface ResolveSeoUrlOptions {
     /** Site origin (e.g. `https://example.com`). Trailing slashes are stripped. */
     siteUrl?: string;

package/dist/static/seo.js

@@ -9,14 +9,14 @@
  * entry-schema.ts, which builds a schema group from these same names so the schema side and
  * the read side cannot drift.
  */
-import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes, toSameOriginPath, } from '../utils/url-prefix.js';
+import { isAbsoluteUrl, joinUrlPrefix, stripTrailingSlashes, toSameOriginPath, withTrailingSlash, } from '../utils/url-prefix.js';
 /**
  * Re-exported so this module's public surface (and `canopycms/server`'s, via `static/index.ts`)
  * is unchanged by their move to `utils/url-prefix.ts` — where they now sit beside
  * `joinUrlPrefix`, the shared join that `assets/asset-url.ts` also needs and that must not
  * import anything under `static/`.
  */
-export { isAbsoluteUrl, stripTrailingSlashes };
+export { isAbsoluteUrl, stripTrailingSlashes, withTrailingSlash };
 /**
  * The recommended SEO field names. `defineSeoFieldGroup()` emits a schema group using exactly
  * these names, so an adopter who uses both ends needs no configuration at all.
@@ -106,29 +106,6 @@ export function extractSeoFields(entryData, opts = {}) {
 export function isNoindexEntry(entryData, opts = {}) {
     return extractSeoFields(entryData, opts).noindex === true;
 }
-/**
- * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
- *
- * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
- * `/blog/rss.xml`) alone, and never doubles an existing slash.
- *
- * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
- * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
- * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
- * with a trailing slash" means and breaks the URL).
- */
-export function withTrailingSlash(path) {
-    const splitIndex = path.search(/[?#]/);
-    const base = splitIndex === -1 ? path : path.slice(0, splitIndex);
-    const suffix = splitIndex === -1 ? '' : path.slice(splitIndex);
-    const withLeading = base.startsWith('/') ? base : `/${base}`;
-    if (withLeading === '/' || withLeading.endsWith('/'))
-        return withLeading + suffix;
-    const lastSegment = withLeading.slice(withLeading.lastIndexOf('/') + 1);
-    if (lastSegment.includes('.'))
-        return withLeading + suffix;
-    return `${withLeading}/${suffix}`;
-}
 /**
  * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
  *