canopycms 0.0.61 → 0.0.63

package/dist/settings-workspace.js

@@ -2,83 +2,41 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { GitManager } from './git-manager.js';
 import { createDebugLogger } from './utils/debug.js';
-import { getErrorMessage, isFileExistsError } from './utils/error.js';
+import { getErrorMessage } from './utils/error.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 to prevent concurrent workspace initialization within the same process.
 // Settings only need one lock (not per-branch like content branches).
 let settingsInitLock = null;
-// Stale lock threshold — init should complete well within this window
-const LOCK_STALE_MS = 30_000;
+const SETTINGS_INIT_LOCK_DIR = '.settings-init';
+const SETTINGS_INIT_LOCK_NAME = 'lock';
 /**
- * Acquire a file-based lock for cross-process synchronization.
- * Uses O_CREAT|O_EXCL (wx flag) for atomic file creation.
- * Stale locks (older than LOCK_STALE_MS) are cleaned up automatically.
+ * Directory the cross-process init lock is anchored on — a dedicated sibling of
+ * the settings root, and NOT the settings root itself.
  *
- * Returns true if lock was acquired, false if another process holds it.
- */
-async function acquireFileLock(lockPath) {
-    const lockContent = JSON.stringify({
-        pid: process.pid,
-        timestamp: new Date().toISOString(),
-    });
-    await fs.mkdir(path.dirname(lockPath), { recursive: true });
-    try {
-        const handle = await fs.open(lockPath, 'wx');
-        await handle.writeFile(lockContent, 'utf-8');
-        await handle.close();
-        return true;
-    }
-    catch (err) {
-        if (!isFileExistsError(err))
-            throw err;
-    }
-    // Lock file exists — check if stale
-    try {
-        const stat = await fs.stat(lockPath);
-        const ageMs = Date.now() - stat.mtimeMs;
-        if (ageMs < LOCK_STALE_MS) {
-            // Lock is fresh — another process is initializing
-            return false;
-        }
-        // Stale lock — another process likely crashed during init
-        log.debug('workspace', 'Removing stale settings init lock', { ageMs });
-        await fs.unlink(lockPath).catch(() => { });
-    }
-    catch {
-        // Lock file vanished between check and stat — try again
-    }
-    // Retry lock acquisition after stale cleanup
-    try {
-        const handle = await fs.open(lockPath, 'wx');
-        await handle.writeFile(lockContent, 'utf-8');
-        await handle.close();
-        return true;
-    }
-    catch (retryErr) {
-        if (isFileExistsError(retryErr))
-            return false;
-        throw retryErr;
-    }
-}
-async function releaseFileLock(lockPath) {
-    await fs.unlink(lockPath).catch(() => { });
-}
-/**
- * Manages settings filesystem workspace and git operations.
+ * Two properties this name has to satisfy:
  *
- * Settings are stored separately from content branches:
- * - prod/dev: Orphan git branches (no shared history with content)
- *
- * Unlike BranchWorkspaceManager, this does not:
- * - Create or manage metadata files
- * - Interact with the branch registry
- * - Check for special cases (settings are always settings)
- *
- * Uses two layers of locking:
- * - In-memory Promise lock for within-process serialization (Lambda request lifecycle)
- * - File-based lock for cross-process synchronization (multiple Lambda instances on EFS)
+ * 1. **It must not pre-create the settings root.** `acquireProvisioningLock`
+ *    mkdir's its target, and `GitManager.initializeWorkspace` clones INTO the
+ *    settings root — `git clone` refuses a destination that already has content
+ *    in it. So the lock lives beside the settings root, never inside it.
+ * 2. **It must not alias any other proper-lockfile target.** proper-lockfile
+ *    keys its module-level bookkeeping (refresh timer + release function) by the
+ *    TARGET path passed to `lock()`, not by `lockfilePath`, so two live locks in
+ *    one process that share a target clobber each other's registry entry (see
+ *    `.claude/future-tasks/proper-lockfile-hazards.md`). This target is a
+ *    dedicated dot-directory, so it collides with none of the existing targets:
+ *    the content-branches root and the bare remote's parent (provisioning locks
+ *    — note the latter IS `path.dirname(settingsRoot)`, which is precisely why
+ *    this cannot be anchored there: settings init calls into
+ *    `ensureLocalSimulatedRemote` while holding this lock), `<branchRoot>/.canopy-meta`
+ *    (content-write lock), `<workspaceRoot>/.tasks` (worker task lock), and the
+ *    individual JSON file paths used by `withOccFileLock`.
  */
+export function settingsInitLockTarget(settingsRoot) {
+    return path.join(path.dirname(path.resolve(settingsRoot)), SETTINGS_INIT_LOCK_DIR);
+}
 /**
  * Whether a settings workspace actually holds settings data yet. Used by the
  * rename guard to tell an already-populated workspace (refuse) apart from a
@@ -99,6 +57,87 @@ async function settingsFilesPresent(settingsRoot) {
     }
     return false;
 }
+/**
+ * Rename guard (settings-branch protection). Refuses to boot when an
+ * ALREADY-POPULATED settings workspace would be re-orphaned under a different
+ * branch name.
+ *
+ * Trace of what happens without it: GitManager.initializeWorkspace sees an
+ * existing .git (no clone happens) and goes straight to
+ * createOrphanSettingsBranch(branchName). If that name isn't already known, git
+ * runs `checkout --orphan <name>` + `rm -rf .` + an empty `--allow-empty`
+ * commit — orphan branches share no history, so this isn't a "migration", it
+ * PERMANENTLY WIPES permissions.json/groups.json with nothing to recover from.
+ * That almost always means deploymentName / settingsBranch /
+ * CANOPYCMS_DEPLOYMENT_NAME changed on a live deployment (see
+ * resolveDeploymentName in operating-mode/deployment-name.ts).
+ *
+ * What this deliberately does NOT refuse, and why it matters:
+ * initializeWorkspace clones at the BASE branch and only creates the orphan
+ * branch several steps later (addConfig, resolveRemoteUrl, ensureRemote come in
+ * between). If that first init is interrupted — a Lambda timeout on a slow EFS
+ * clone, an OOM, a spot interruption — it leaves a perfectly valid repo sitting
+ * on the base branch with NO settings files in it. Refusing on "branch differs"
+ * alone would then brick the deployment permanently on every subsequent boot, to
+ * protect data that was never written. So the refusal additionally requires
+ * evidence that this really is a populated settings workspace: either it is
+ * checked out on some OTHER settings branch, or the settings files are actually
+ * on disk.
+ *
+ * This function is NEVER gated on holding the init lock — see its two call
+ * sites in ensureGitWorkspace and the comment there.
+ */
+async function assertSettingsWorkspaceIdentity(options) {
+    const repoExists = await GitManager.repoExistsAt(options.settingsRoot);
+    if (!repoExists)
+        return;
+    let currentBranch;
+    let readError;
+    try {
+        const existing = new GitManager({ repoPath: options.settingsRoot });
+        currentBranch = (await existing.status()).current ?? undefined;
+    }
+    catch (err) {
+        currentBranch = undefined;
+        readError = getErrorMessage(err);
+    }
+    const onDifferentBranch = currentBranch !== options.branchName;
+    const looksLikeSettingsBranch = currentBranch !== undefined && currentBranch.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX);
+    const hasSettingsData = await settingsFilesPresent(options.settingsRoot);
+    if (onDifferentBranch && (looksLikeSettingsBranch || hasSettingsData)) {
+        throw new Error(`CanopyCMS: refusing to initialize settings workspace at ${options.settingsRoot}. ` +
+            (currentBranch
+                ? `It is currently on branch '${currentBranch}', but this deployment resolved ` +
+                    `settings branch '${options.branchName}'.`
+                : `Its current branch could not be read (${readError ?? 'unknown error'}), but it ` +
+                    `holds settings files, and this deployment resolved settings branch ` +
+                    `'${options.branchName}'.`) +
+            ` Proceeding would run \`git checkout --orphan\` + \`rm -rf .\` on this workspace, ` +
+            `which PERMANENTLY WIPES permissions.json/groups.json (orphan branches share no ` +
+            `history — there is nothing to migrate from). This almost always means ` +
+            `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.`);
+    }
+}
+/**
+ * Manages settings filesystem workspace and git operations.
+ *
+ * Settings are stored separately from content branches:
+ * - prod/dev: Orphan git branches (no shared history with content)
+ *
+ * Unlike BranchWorkspaceManager, this does not:
+ * - Create or manage metadata files
+ * - Interact with the branch registry
+ * - Check for special cases (settings are always settings)
+ *
+ * Uses two layers of locking, mirroring BranchWorkspaceManager:
+ * - In-memory Promise lock for within-process serialization (Lambda request lifecycle)
+ * - `acquireProvisioningLock` (proper-lockfile) for cross-process/cross-host
+ *   synchronization of the init itself (multiple Lambda containers on EFS)
+ */
 export class SettingsWorkspaceManager {
     constructor(config) {
         this.config = config;
@@ -117,88 +156,34 @@ export class SettingsWorkspaceManager {
                         branchName: options.branchName,
                         mode: options.mode,
                     });
-                    // Layer 2: File-based lock (prevents concurrent init across processes)
-                    // Lock file is placed OUTSIDE the settings root (as a sibling) so that
-                    // acquireFileLock's mkdir does not pre-create the settings directory,
-                    // which would cause git clone to fail ("already exists and is not empty").
-                    const lockPath = path.join(path.dirname(options.settingsRoot), '.settings-init.lock');
-                    const acquired = await acquireFileLock(lockPath);
+                    // Rename guard, run LOCK-FREE and unconditionally, before any waiting.
+                    // A deployment whose settings-branch name no longer matches the
+                    // workspace on disk is misconfigured, not contended: it must refuse
+                    // immediately rather than queue behind a live provisioner for what can
+                    // be minutes. Running it here also keeps the guarantee the guard has
+                    // always had — no code path reaches initializeWorkspace without it
+                    // 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).
+                    //
+                    // This replaced a bespoke O_CREAT|O_EXCL + 30s-mtime scheme whose
+                    // return value was only ever used to decide whether to release: the
+                    // loser proceeded into initializeWorkspace anyway, concurrently with
+                    // the holder, where it could see a half-written .git, classify it
+                    // corrupt, and `rm -rf` it out from under the in-flight clone.
+                    const releaseLock = await acquireProvisioningLock(settingsInitLockTarget(options.settingsRoot), SETTINGS_INIT_LOCK_NAME);
                     try {
-                        // Rename guard (settings-branch protection). Refuses to boot when
-                        // an ALREADY-POPULATED settings workspace would be re-orphaned
-                        // under a different branch name.
-                        //
-                        // Trace of what happens without it: GitManager.initializeWorkspace
-                        // sees an existing .git (no clone happens) and goes straight to
-                        // createOrphanSettingsBranch(options.branchName). If that name
-                        // isn't already known, git runs `checkout --orphan <name>` +
-                        // `rm -rf .` + an empty `--allow-empty` commit — orphan branches
-                        // share no history, so this isn't a "migration", it PERMANENTLY
-                        // WIPES permissions.json/groups.json with nothing to recover from.
-                        // That almost always means deploymentName / settingsBranch /
-                        // CANOPYCMS_DEPLOYMENT_NAME changed on a live deployment (see
-                        // resolveDeploymentName in operating-mode/deployment-name.ts).
-                        //
-                        // What this deliberately does NOT refuse, and why it matters:
-                        // initializeWorkspace clones at the BASE branch and only creates
-                        // the orphan branch several steps later (addConfig, resolveRemoteUrl,
-                        // ensureRemote come in between). If that first init is interrupted
-                        // — a Lambda timeout on a slow EFS clone, an OOM, a spot
-                        // interruption — it leaves a perfectly valid repo sitting on the
-                        // base branch with NO settings files in it. Refusing on "branch
-                        // differs" alone would then brick the deployment permanently on
-                        // every subsequent boot, to protect data that was never written.
-                        // So the refusal additionally requires evidence that this really
-                        // is a populated settings workspace: either it is checked out on
-                        // some OTHER settings branch, or the settings files are actually
-                        // on disk.
-                        const repoExists = await GitManager.repoExistsAt(options.settingsRoot);
-                        // Deliberately NOT gated on `acquired`: when another process holds
-                        // the init lock, THIS process still proceeds to initializeWorkspace
-                        // below (pre-existing concurrent-init design), so skipping the
-                        // guard here would let the un-locked process wipe a populated
-                        // workspace — concurrent cold starts are routine right after a
-                        // deploy, which is exactly when a changed deploymentName arrives.
-                        // Running the guard lock-free cannot false-positive on a
-                        // legitimate concurrent init: a first-ever init sits on the base
-                        // branch with no settings files (fires neither arm of the
-                        // condition below), and a same-name re-init has
-                        // currentBranch === options.branchName. The only mid-init state
-                        // that fires is another process initializing a DIFFERENT settings
-                        // branch name — the rename hazard itself, where firing is correct.
-                        if (repoExists) {
-                            let currentBranch;
-                            let readError;
-                            try {
-                                const existing = new GitManager({ repoPath: options.settingsRoot });
-                                currentBranch = (await existing.status()).current ?? undefined;
-                            }
-                            catch (err) {
-                                currentBranch = undefined;
-                                readError = getErrorMessage(err);
-                            }
-                            const onDifferentBranch = currentBranch !== options.branchName;
-                            const looksLikeSettingsBranch = currentBranch !== undefined &&
-                                currentBranch.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX);
-                            const hasSettingsData = await settingsFilesPresent(options.settingsRoot);
-                            if (onDifferentBranch && (looksLikeSettingsBranch || hasSettingsData)) {
-                                throw new Error(`CanopyCMS: refusing to initialize settings workspace at ${options.settingsRoot}. ` +
-                                    (currentBranch
-                                        ? `It is currently on branch '${currentBranch}', but this deployment resolved ` +
-                                            `settings branch '${options.branchName}'.`
-                                        : `Its current branch could not be read (${readError ?? 'unknown error'}), but it ` +
-                                            `holds settings files, and this deployment resolved settings branch ` +
-                                            `'${options.branchName}'.`) +
-                                    ` Proceeding would run \`git checkout --orphan\` + \`rm -rf .\` on this workspace, ` +
-                                    `which PERMANENTLY WIPES permissions.json/groups.json (orphan branches share no ` +
-                                    `history — there is nothing to migrate from). This almost always means ` +
-                                    `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.`);
-                            }
-                        }
+                        // Re-run the guard on the now-stable state. If we waited above, the
+                        // previous holder may have created the workspace (or moved it onto
+                        // its own settings branch) after we sampled it, and acting on that
+                        // stale sample is exactly the destructive path the guard exists to
+                        // stop. Still not gated on any "did I win the race" flag — there is
+                        // no such flag by design; every process either holds the lock here
+                        // or has already thrown.
+                        await assertSettingsWorkspaceIdentity(options);
                         // GitManager.initializeWorkspace is idempotent (checks for .git),
                         // so it's safe to call even if another process just finished init.
                         await GitManager.initializeWorkspace({
@@ -217,8 +202,11 @@ export class SettingsWorkspaceManager {
                         });
                     }
                     finally {
-                        if (acquired) {
-                            await releaseFileLock(lockPath);
+                        try {
+                            await releaseLock();
+                        }
+                        catch (err) {
+                            log.debug('workspace', 'Failed to release settings-init lock', { err });
                         }
                     }
                 }

package/dist/settings-workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings-workspace.js","sourceRoot":"","sources":["../src/settings-workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACjC,OAAO,IAAI,MAAM,WAAW,CAAA;AAG5B,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAA;AAEzD,MAAM,GAAG,GAAG,iBAAiB,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAA;AAE9D,yFAAyF;AACzF,sEAAsE;AACtE,IAAI,gBAAgB,GAAyB,IAAI,CAAA;AAEjD,sEAAsE;AACtE,MAAM,aAAa,GAAG,MAAM,CAAA;AAS5B;;;;;;GAMG;AACH,KAAK,UAAU,eAAe,CAAC,QAAgB;IAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC;QACjC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC,CAAA;IAEF,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAE3D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QAC5C,MAAM,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QAC5C,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAA;IACxC,CAAC;IAED,oCAAoC;IACpC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,CAAA;QACvC,IAAI,KAAK,GAAG,aAAa,EAAE,CAAC;YAC1B,kDAAkD;YAClD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,0DAA0D;QAC1D,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,mCAAmC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QACtE,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QAC5C,MAAM,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;QAC5C,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,OAAO,QAAQ,EAAE,CAAC;QAClB,IAAI,iBAAiB,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAA;QAC7C,MAAM,QAAQ,CAAA;IAChB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,QAAgB;IAC7C,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAC3C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH;;;;;;GAMG;AACH,KAAK,UAAU,oBAAoB,CAAC,YAAoB;IACtD,MAAM,KAAK,GAAG,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAA;IACjD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC,CAAA;YAC9C,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,wCAAwC;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,OAAO,wBAAwB;IAGnC,YAAY,MAAoB;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,OAAuC;QAC9D,OAAO,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,oBAAoB,EAAE,KAAK,IAAI,EAAE;YAC7D,+EAA+E;YAC/E,IAAI,gBAAgB,EAAE,CAAC;gBACrB,MAAM,gBAAgB,CAAA;gBACtB,OAAM;YACR,CAAC;YAED,oCAAoC;YACpC,gBAAgB,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC7B,IAAI,CAAC;oBACH,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,iCAAiC,EAAE;wBACxD,UAAU,EAAE,OAAO,CAAC,UAAU;wBAC9B,IAAI,EAAE,OAAO,CAAC,IAAI;qBACnB,CAAC,CAAA;oBAEF,uEAAuE;oBACvE,uEAAuE;oBACvE,sEAAsE;oBACtE,2EAA2E;oBAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,qBAAqB,CAAC,CAAA;oBACrF,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;oBAEhD,IAAI,CAAC;wBACH,kEAAkE;wBAClE,+DAA+D;wBAC/D,iCAAiC;wBACjC,EAAE;wBACF,mEAAmE;wBACnE,gEAAgE;wBAChE,+DAA+D;wBAC/D,6DAA6D;wBAC7D,iEAAiE;wBACjE,gEAAgE;wBAChE,mEAAmE;wBACnE,6DAA6D;wBAC7D,8DAA8D;wBAC9D,+DAA+D;wBAC/D,EAAE;wBACF,8DAA8D;wBAC9D,iEAAiE;wBACjE,sEAAsE;wBACtE,mEAAmE;wBACnE,yDAAyD;wBACzD,iEAAiE;wBACjE,gEAAgE;wBAChE,gEAAgE;wBAChE,iEAAiE;wBACjE,iEAAiE;wBACjE,iEAAiE;wBACjE,iEAAiE;wBACjE,WAAW;wBACX,MAAM,UAAU,GAAG,MAAM,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC,CAAA;wBACtE,mEAAmE;wBACnE,oEAAoE;wBACpE,+DAA+D;wBAC/D,8DAA8D;wBAC9D,+DAA+D;wBAC/D,kEAAkE;wBAClE,yDAAyD;wBACzD,iEAAiE;wBACjE,0DAA0D;wBAC1D,gDAAgD;wBAChD,gEAAgE;wBAChE,kEAAkE;wBAClE,mEAAmE;wBACnE,IAAI,UAAU,EAAE,CAAC;4BACf,IAAI,aAAiC,CAAA;4BACrC,IAAI,SAA6B,CAAA;4BACjC,IAAI,CAAC;gCACH,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;gCACnE,aAAa,GAAG,CAAC,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,IAAI,SAAS,CAAA;4BAChE,CAAC;4BAAC,OAAO,GAAG,EAAE,CAAC;gCACb,aAAa,GAAG,SAAS,CAAA;gCACzB,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;4BAClC,CAAC;4BAED,MAAM,iBAAiB,GAAG,aAAa,KAAK,OAAO,CAAC,UAAU,CAAA;4BAC9D,MAAM,uBAAuB,GAC3B,aAAa,KAAK,SAAS;gCAC3B,aAAa,CAAC,UAAU,CAAC,+BAA+B,CAAC,CAAA;4BAC3D,MAAM,eAAe,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAA;4BAExE,IAAI,iBAAiB,IAAI,CAAC,uBAAuB,IAAI,eAAe,CAAC,EAAE,CAAC;gCACtE,MAAM,IAAI,KAAK,CACb,2DAA2D,OAAO,CAAC,YAAY,IAAI;oCACjF,CAAC,aAAa;wCACZ,CAAC,CAAC,8BAA8B,aAAa,kCAAkC;4CAC7E,oBAAoB,OAAO,CAAC,UAAU,IAAI;wCAC5C,CAAC,CAAC,yCAAyC,SAAS,IAAI,eAAe,YAAY;4CACjF,qEAAqE;4CACrE,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC;oCAC/B,oFAAoF;oCACpF,iFAAiF;oCACjF,wEAAwE;oCACxE,4EAA4E;oCAC5E,kFAAkF;oCAClF,8CAA8C;oCAC9C,IAAI,aAAa,IAAI,OAAO,CAAC,UAAU,wCAAwC;oCAC/E,kBAAkB,OAAO,CAAC,YAAY,wBAAwB,CACjE,CAAA;4BACH,CAAC;wBACH,CAAC;wBAED,kEAAkE;wBAClE,mEAAmE;wBACnE,MAAM,UAAU,CAAC,mBAAmB,CAAC;4BACnC,aAAa,EAAE,OAAO,CAAC,YAAY;4BACnC,UAAU,EAAE,OAAO,CAAC,UAAU;4BAC9B,IAAI,EAAE,OAAO,CAAC,IAAI;4BAClB,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;4BACzC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;4BAClC,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;4BAC9C,SAAS,EAAE,OAAO,CAAC,SAAS;4BAC5B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;4BACzC,wBAAwB,EAAE,IAAI,CAAC,MAAM,CAAC,wBAAwB;4BAC9D,UAAU,EAAE,QAAQ,EAAE,6CAA6C;4BACnE,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB;4BAC9C,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;yBACjD,CAAC,CAAA;oBACJ,CAAC;4BAAS,CAAC;wBACT,IAAI,QAAQ,EAAE,CAAC;4BACb,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAA;wBACjC,CAAC;oBACH,CAAC;gBACH,CAAC;wBAAS,CAAC;oBACT,oEAAoE;oBACpE,gBAAgB,GAAG,IAAI,CAAA;gBACzB,CAAC;YACH,CAAC,CAAC,EAAE,CAAA;YAEJ,sCAAsC;YACtC,MAAM,gBAAgB,CAAA;QACxB,CAAC,CAAC,CAAA;IACJ,CAAC;CACF"}
+{"version":3,"file":"settings-workspace.js","sourceRoot":"","sources":["../src/settings-workspace.ts"],"names":[],"mappings":"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"}

package/dist/static/index.d.ts

@@ -6,10 +6,12 @@ import { type EntryFieldError } from '../validation/entry-validator';
  * (no Next.js types) so that any framework adapter — e.g. canopycms-next — can map them to its own
  * static-generation shapes (generateStaticParams, sitemap, metadata).
  *
- * Sitemap (`collectPublishedEntries`) and SEO metadata (`extractSeoFields`) helpers are tracked as
- * follow-up work; see .claude/future-tasks/static-export-sitemap.md and
- * .claude/future-tasks/static-export-seo-metadata.md.
+ * - `collectStaticPaths` — routable paths only, for `generateStaticParams`.
+ * - `collectRoutableEntries` — the same enumeration with each entry's `data` and `updatedAt`
+ *   carried through, for surfaces that must inspect content (sitemap, feeds, search index).
+ * - `./seo` — `extractSeoFields` / `isNoindexEntry` / URL shaping, re-exported below.
  */
+export { DEFAULT_SEO_FIELD_NAMES, extractSeoFields, isNoindexEntry, isAbsoluteUrl, withTrailingSlash, resolveSeoUrl, stripTrailingSlashes, type SeoFields, type SeoFieldNames, type SeoFieldLocation, type SeoOgType, type SeoTwitterCard, type ExtractSeoFieldsOptions, type ResolveSeoUrlOptions, } from './seo';
 /** A routable content entry, reduced to what static path generation needs. */
 export interface StaticPathEntry {
     /**
@@ -27,6 +29,26 @@ export interface StaticPathEntry {
     /** Entry type name (e.g. 'post', 'doc'). */
     entryType: string;
 }
+/**
+ * A routable content entry with its content attached — everything `StaticPathEntry` carries,
+ * plus the entry `data` and its `updatedAt`.
+ *
+ * This is what surfaces that must look INSIDE an entry need (sitemap, feeds, index grids),
+ * as opposed to `generateStaticParams`, which only needs the path.
+ */
+export interface RoutableEntry<T = Record<string, unknown>> extends StaticPathEntry {
+    /** Raw entry data (frontmatter merged with the body field for md/mdx), as `listEntries` returns it. */
+    data: T;
+    /**
+     * Filesystem mtime (ISO 8601) of the entry file.
+     *
+     * Caveat, and read it before wiring this to a sitemap `<lastmod>`: this is a checkout-time
+     * timestamp, not an editorial one. A fresh CI clone (or a fresh branch-clone checkout) resets
+     * every file's mtime, so there it says "when this tree was checked out", not "when this content
+     * was last edited". Treat it as "changed since the last build" at best.
+     */
+    updatedAt?: string;
+}
 export interface CollectStaticPathsOptions {
     /**
      * Scope to a collection logical path (e.g. 'content/posts'). Defaults to the whole content root.
@@ -36,6 +58,35 @@ export interface CollectStaticPathsOptions {
     /** Keep only entries matching this predicate (e.g. drop the root index, or filter by entryType). */
     filter?: (entry: StaticPathEntry) => boolean;
 }
+export interface CollectRoutableEntriesOptions<T = Record<string, unknown>> {
+    /**
+     * Scope to a collection logical path (e.g. 'content/posts'). Defaults to the whole content root.
+     * Skips loading entries outside this scope.
+     */
+    rootPath?: string;
+    /** Keep only entries matching this predicate. Runs after `data` is attached, so it can read content. */
+    filter?: (entry: RoutableEntry<T>) => boolean;
+}
+/**
+ * Enumerate routable content entries WITH their data — the input to any surface that must read
+ * inside an entry to decide what to publish (sitemap, RSS, search index, index grids).
+ *
+ * Identical enumeration to `collectStaticPaths` (same single `listEntries` pass, same build-time
+ * schema-validity guard); it simply keeps `data` and `updatedAt` instead of discarding them.
+ *
+ * **Enumerates every entry type by default.** There is no allow-list of "publishable" types, and
+ * that is deliberate: a sitemap built from a hand-maintained list of entry types silently omits
+ * whichever type nobody remembered to add, and nothing fails. Narrow the result with `filter`
+ * when you actually mean to — omission should be a decision, not an oversight.
+ *
+ * `noindex` is NOT applied here: an entry that must not be advertised must still be built. Apply
+ * `isNoindexEntry` at the advertising surface (as `generateContentSitemap` does).
+ *
+ * @example
+ * const entries = await collectRoutableEntries(await getCanopyForBuild())
+ * const published = entries.filter((e) => !isNoindexEntry(e.data))
+ */
+export declare function collectRoutableEntries<T = Record<string, unknown>>(ctx: Pick<CanopyBuildContext, 'listEntries'>, options?: CollectRoutableEntriesOptions<T>): Promise<RoutableEntry<T>[]>;
 /**
  * Enumerate routable content entries as neutral path descriptors for static generation.
  *
@@ -57,6 +108,15 @@ export interface InvalidBuildEntry {
     entryPath: string;
     errors: EntryFieldError[];
 }
+/**
+ * What the build-time validity scan needs off a listing item. `data` is `unknown` rather than
+ * `ListEntriesItem['data']` so a caller that listed with an entry-shape generic (e.g.
+ * `collectRoutableEntries<PostContent>`) can still be scanned — the scan re-guards the value
+ * anyway, since on-disk data is never trusted.
+ */
+type BuildScanItem = Pick<ListEntriesItem, 'entryPath' | 'schema'> & {
+    data: unknown;
+};
 /**
  * Scan listEntries-shaped items for schema-invalid entries.
  *
@@ -71,7 +131,7 @@ export interface InvalidBuildEntry {
  * Items whose `schema` couldn't be resolved (unknown entry type) are skipped here — that's a
  * different failure class, handled elsewhere.
  */
-export declare function findInvalidEntries(items: readonly Pick<ListEntriesItem, 'entryPath' | 'schema' | 'data'>[]): InvalidBuildEntry[];
+export declare function findInvalidEntries(items: readonly BuildScanItem[]): InvalidBuildEntry[];
 /**
  * Throw a single, descriptive Error if any item is schema-invalid.
  *
@@ -79,5 +139,5 @@ export declare function findInvalidEntries(items: readonly Pick<ListEntriesItem,
  * disappears from a static build is a worse failure mode than a red build. Lists every
  * offending entry so one build catches every abandoned scaffold, not just the first.
  */
-export declare function assertBuildEntriesValid(items: readonly Pick<ListEntriesItem, 'entryPath' | 'schema' | 'data'>[], phaseLabel: string): void;
+export declare function assertBuildEntriesValid(items: readonly BuildScanItem[], phaseLabel: string): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/static/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAEvF;;;;;;;;GAQG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oGAAoG;IACpG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAA;CAC7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,EAC5C,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,eAAe,EAAE,CAAC,CAc5B;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B;AAkCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC,EAAE,GACvE,iBAAiB,EAAE,CAWrB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC,EAAE,EACxE,UAAU,EAAE,MAAM,GACjB,IAAI,CAkBN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/static/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAEvF;;;;;;;;;GASG;AAEH,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC1B,MAAM,OAAO,CAAA;AAEd,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,eAAe;IACjF,uGAAuG;IACvG,IAAI,EAAE,CAAC,CAAA;IACP;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oGAAoG;IACpG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,OAAO,CAAA;CAC7C;AAED,MAAM,WAAW,6BAA6B,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wGAAwG;IACxG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,OAAO,CAAA;CAC9C;AA6BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,EAC5C,OAAO,GAAE,6BAA6B,CAAC,CAAC,CAAM,GAC7C,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAO7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,CAAC,EAC5C,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,eAAe,EAAE,CAAC,CAW5B;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,eAAe,EAAE,CAAA;CAC1B;AAED;;;;;GAKG;AACH,KAAK,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,QAAQ,CAAC,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAkCtF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,iBAAiB,EAAE,CAWvF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAkBjG"}

package/dist/static/index.js

@@ -1,5 +1,62 @@
 import { isBuildMode } from '../build-mode.js';
 import { validateEntryData } from '../validation/entry-validator.js';
+/**
+ * Framework-agnostic helpers for static-site generation. These produce neutral data structures
+ * (no Next.js types) so that any framework adapter — e.g. canopycms-next — can map them to its own
+ * static-generation shapes (generateStaticParams, sitemap, metadata).
+ *
+ * - `collectStaticPaths` — routable paths only, for `generateStaticParams`.
+ * - `collectRoutableEntries` — the same enumeration with each entry's `data` and `updatedAt`
+ *   carried through, for surfaces that must inspect content (sitemap, feeds, search index).
+ * - `./seo` — `extractSeoFields` / `isNoindexEntry` / URL shaping, re-exported below.
+ */
+export { DEFAULT_SEO_FIELD_NAMES, extractSeoFields, isNoindexEntry, isAbsoluteUrl, withTrailingSlash, resolveSeoUrl, stripTrailingSlashes, } from './seo.js';
+/**
+ * Shared enumeration behind `collectStaticPaths` and `collectRoutableEntries`.
+ *
+ * `phaseLabel` only names the phase in the build-guard error, but it is threaded through rather
+ * than fixed so the message points at the surface that actually failed.
+ */
+async function enumerateRoutableEntries(ctx, rootPath, phaseLabel) {
+    const entries = await ctx.listEntries({ rootPath });
+    // Build-time only: `next dev` runs generateStaticParams against the live working tree, where
+    // fresh create-scaffolds legitimately exist mid-edit. Only fail the actual production build —
+    // an abandoned schema-invalid scaffold shipping into a static build silently drops that page's
+    // route (or worse, renders broken), which is worse than a red build.
+    if (isBuildMode())
+        assertBuildEntriesValid(entries, phaseLabel);
+    return entries.map((entry) => ({
+        urlPath: entry.urlPath,
+        segments: entry.urlPath === '/' ? [] : entry.urlPath.replace(/^\//, '').split('/'),
+        slug: entry.slug,
+        entryType: entry.entryType,
+        data: entry.data,
+        ...(entry.updatedAt ? { updatedAt: entry.updatedAt } : {}),
+    }));
+}
+/**
+ * Enumerate routable content entries WITH their data — the input to any surface that must read
+ * inside an entry to decide what to publish (sitemap, RSS, search index, index grids).
+ *
+ * Identical enumeration to `collectStaticPaths` (same single `listEntries` pass, same build-time
+ * schema-validity guard); it simply keeps `data` and `updatedAt` instead of discarding them.
+ *
+ * **Enumerates every entry type by default.** There is no allow-list of "publishable" types, and
+ * that is deliberate: a sitemap built from a hand-maintained list of entry types silently omits
+ * whichever type nobody remembered to add, and nothing fails. Narrow the result with `filter`
+ * when you actually mean to — omission should be a decision, not an oversight.
+ *
+ * `noindex` is NOT applied here: an entry that must not be advertised must still be built. Apply
+ * `isNoindexEntry` at the advertising surface (as `generateContentSitemap` does).
+ *
+ * @example
+ * const entries = await collectRoutableEntries(await getCanopyForBuild())
+ * const published = entries.filter((e) => !isNoindexEntry(e.data))
+ */
+export async function collectRoutableEntries(ctx, options = {}) {
+    const entries = await enumerateRoutableEntries(ctx, options.rootPath, 'routable entry enumeration');
+    return options.filter ? entries.filter(options.filter) : entries;
+}
 /**
  * Enumerate routable content entries as neutral path descriptors for static generation.
  *
@@ -14,18 +71,14 @@ import { validateEntryData } from '../validation/entry-validator.js';
  * const posts = await collectStaticPaths(await getCanopyForBuild(), { rootPath: 'content/posts' })
  */
 export async function collectStaticPaths(ctx, options = {}) {
-    const entries = await ctx.listEntries({ rootPath: options.rootPath });
-    // Build-time only: `next dev` runs generateStaticParams against the live working tree, where
-    // fresh create-scaffolds legitimately exist mid-edit. Only fail the actual production build —
-    // an abandoned schema-invalid scaffold shipping into a static build silently drops that page's
-    // route (or worse, renders broken), which is worse than a red build.
-    if (isBuildMode())
-        assertBuildEntriesValid(entries, 'static path enumeration');
-    const mapped = entries.map((entry) => ({
-        urlPath: entry.urlPath,
-        segments: entry.urlPath === '/' ? [] : entry.urlPath.replace(/^\//, '').split('/'),
-        slug: entry.slug,
-        entryType: entry.entryType,
+    const entries = await enumerateRoutableEntries(ctx, options.rootPath, 'static path enumeration');
+    // Drop data/updatedAt: generateStaticParams needs paths only, and returning entry content from
+    // a path-enumeration helper invites page code to read content from the admin build context.
+    const mapped = entries.map(({ urlPath, segments, slug, entryType }) => ({
+        urlPath,
+        segments,
+        slug,
+        entryType,
     }));
     return options.filter ? mapped.filter(options.filter) : mapped;
 }

package/dist/static/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/static/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/static/index.ts"],"names":[],"mappings":"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"}