canopycms 0.0.61-int.75 → 0.0.62

package/dist/settings-workspace.js

@@ -2,66 +2,125 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { GitManager } from './git-manager.js';
 import { createDebugLogger } from './utils/debug.js';
-import { 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.
+ * Two properties this name has to satisfy:
+ *
+ * 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`.
  */
-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;
+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
+ * clone that was interrupted before its orphan branch was ever created
+ * (harmless — let init finish). File names come from the operating-mode
+ * strategy so this stays in step with whatever the mode calls them.
+ */
+async function settingsFilesPresent(settingsRoot) {
+    const names = ['permissions.json', 'groups.json'];
+    for (const name of names) {
+        try {
+            await fs.access(path.join(settingsRoot, name));
+            return true;
+        }
+        catch {
+            // Not present — keep checking the rest.
         }
-        // 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
+    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 handle = await fs.open(lockPath, 'wx');
-        await handle.writeFile(lockContent, 'utf-8');
-        await handle.close();
-        return true;
+        const existing = new GitManager({ repoPath: options.settingsRoot });
+        currentBranch = (await existing.status()).current ?? undefined;
     }
-    catch (retryErr) {
-        if (isFileExistsError(retryErr))
-            return false;
-        throw retryErr;
+    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.`);
     }
-}
-async function releaseFileLock(lockPath) {
-    await fs.unlink(lockPath).catch(() => { });
 }
 /**
  * Manages settings filesystem workspace and git operations.
@@ -74,9 +133,10 @@ async function releaseFileLock(lockPath) {
  * - Interact with the branch registry
  * - Check for special cases (settings are always settings)
  *
- * Uses two layers of locking:
+ * Uses two layers of locking, mirroring BranchWorkspaceManager:
  * - In-memory Promise lock for within-process serialization (Lambda request lifecycle)
- * - File-based lock for cross-process synchronization (multiple Lambda instances on EFS)
+ * - `acquireProvisioningLock` (proper-lockfile) for cross-process/cross-host
+ *   synchronization of the init itself (multiple Lambda containers on EFS)
  */
 export class SettingsWorkspaceManager {
     constructor(config) {
@@ -96,13 +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 {
+                        // 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({
@@ -121,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":"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"}
+{"version":3,"file":"settings-workspace.js","sourceRoot":"","sources":["../src/settings-workspace.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -1,7 +1,17 @@
 import type { ContentId } from './paths/types';
 export type CanopyUserId = string;
 export type CanopyGroupId = string;
-export type BranchStatus = 'editing' | 'submitted' | 'approved' | 'locked' | 'archived';
+/**
+ * Branch workflow state. Anything other than 'editing' locks content writes --
+ * see authorization/protected-branch.ts `writeBlocked`, the single place that
+ * rule is expressed.
+ *
+ * There is deliberately no separate 'locked' state: 'submitted' already means
+ * "locked while a reviewer looks at the PR", and request-changes/withdraw are
+ * the unlocks. A future admin-freeze feature should reintroduce a status only
+ * alongside real semantics (worker rebase skip list, a set/unset endpoint, UI).
+ */
+export type BranchStatus = 'editing' | 'submitted' | 'approved' | 'archived';
 export type SyncStatus = 'synced' | 'pending-sync' | 'sync-failed';
 export type ConflictStatus = 'clean' | 'conflicts-detected';
 export type PullRequestState = 'open' | 'closed' | 'merged';
@@ -9,7 +19,6 @@ export interface BranchAccessControl {
     allowedUsers?: CanopyUserId[];
     allowedGroups?: CanopyGroupId[];
     managerOrAdminAllowed?: boolean;
-    adminOnly?: boolean;
 }
 export interface BranchMetadata {
     name: string;
@@ -52,6 +61,33 @@ export interface BranchMetadata {
         firstAt: string;
         lastAt: string;
     };
+    /**
+     * Set by the worker's rebase loop when it rewrote history this deployment
+     * had ALREADY published: the commit `remote.git` (and therefore GitHub)
+     * held for this branch, which the rebase replaced.
+     *
+     * Used as the `--force-with-lease` expected value on both hops, so a forced
+     * push can only ever move a ref off the exact commit our own rebase rewrote
+     * away -- never over anyone else's work.
+     *
+     * Set once per rewrite episode and never advanced while still set: across
+     * two rebases before any push lands, GitHub still holds the ORIGINAL
+     * commit, so advancing the marker would aim the lease at a commit GitHub
+     * never had. Cleared only once GitHub is confirmed to hold something else
+     * (CmsWorker.pushBranchToGitHub) -- while it is set, it is the sole trigger
+     * for the rebase loop's self-heal pass.
+     */
+    historyRewrittenFrom?: string;
+    /**
+     * Short, sanitized reason the worker's last GitHub sync task failed
+     * permanently (set alongside `syncStatus: 'sync-failed'` by
+     * CmsWorker.updateBranchMetadataOnFailure) -- e.g. a non-fast-forward push
+     * rejection naming the branch. Absent until a task has failed permanently.
+     * Cleared on the next successful sync task (CmsWorker.updateBranchMetadata
+     * explicitly resets it to undefined) so a stale reason never survives a
+     * later successful push.
+     */
+    syncFailureReason?: string;
 }
 export interface BranchPaths {
     /** Root where all branches live (e.g., /mnt/efs/site, ~/.canopycms/branches) */
@@ -88,10 +124,45 @@ export interface WorkerStatusReport {
         durationMs: number;
         rebased: string[];
         skippedDirty: string[];
+        /**
+         * [SYNC-C1] Branches skipped because a content write held the branch's
+         * cross-host content-write lock (utils/content-write-lock.ts) -- the
+         * worker yields and retries next cycle.
+         *
+         * Optional for the same reason as `tracked` below: absent from a
+         * worker-status.json written by a worker predating that lock. Readers must
+         * tolerate its absence.
+         */
+        skippedLocked?: string[];
         failed: {
             branch: string;
             error: string;
         }[];
+        /**
+         * Outcome of reconciling remote.git's `refs/heads/*` against GitHub's
+         * fetched tips (worker/cms-worker.ts's `reconcileTrackedBranches`) --
+         * the non-destructive replacement for the old fetch refspec that used
+         * to write GitHub's refs directly into `refs/heads/*`.
+         */
+        /**
+         * Optional: absent from a worker-status.json written by a worker that
+         * predates the tracked-branch reconcile (PR #168). Readers must tolerate
+         * its absence rather than assume every status file has it.
+         */
+        tracked?: {
+            created: string[];
+            fastForwarded: string[];
+            ahead: string[];
+            diverged: string[];
+            /**
+             * Optional for the same reason as `tracked` itself: absent from a
+             * status file written before the rebase loop began publishing rewritten
+             * history. Branches here diverged from GitHub because THIS worker
+             * rebased them and the GitHub push is still queued -- expected and
+             * self-resolving, unlike `diverged`.
+             */
+            rewritten?: string[];
+        };
     };
     lastFatalError?: {
         message: string;

package/dist/types.d.ts.map

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

package/dist/utils/content-write-lock.d.ts

@@ -0,0 +1,127 @@
+/**
+ * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and
+ * content writes against the same branch working tree.
+ *
+ * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
+ * `ContentStore`'s write/delete/rename critical sections were guarded only by
+ * the in-process mutex (`utils/async-mutex`), which does not cross that
+ * boundary, while `CmsWorker.rebaseActiveBranches()` rewrites the very same
+ * working tree. A write landing after `git rebase` started is destroyed two
+ * ways -- `git checkout --theirs <file>` overwrites it with the branch's
+ * committed version (and the rebase then SUCCEEDS, logging nothing), and
+ * `git rebase --abort` hard-resets the tree. Either way the editor already got
+ * its 200. This lock is what serializes the two.
+ *
+ * **Asymmetric by design.** The worker retries every branch on its next sync
+ * cycle (~5 minutes) while the editor is a person waiting on a save, so the
+ * worker yields and the writer waits:
+ *
+ * - Worker: {@link tryAcquireContentWriteLock} -- zero retries. On contention
+ *   it skips that branch this cycle (an extension of the existing
+ *   skip-dirty-branches behavior) and picks it up next cycle.
+ * - Writers: {@link withContentWriteLock} -- a short bounded wait, then a
+ *   retriable failure the API surfaces as a 409.
+ *
+ * **Reads never take this lock.** An extra EFS round-trip on every read is not
+ * an acceptable price, and a read racing a rebase gets a consistent-enough
+ * older or newer file, never a destroyed one.
+ *
+ * ## Why the lock is anchored on `{branchRoot}/.canopy-meta`
+ *
+ * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
+ * release function) by the **target path** passed to `lock()`, NOT by
+ * `lockfilePath`. The provisioning lock targets `path.dirname(branchRoot)` --
+ * the shared content-branches directory -- so anchoring here on that same
+ * directory with a different lock NAME would land on the same registry key:
+ * one process holding both (a Lambda container provisioning a workspace and
+ * writing content) would have the second acquisition clobber the first's
+ * bookkeeping. Targeting `{branchRoot}/.canopy-meta` instead gives:
+ *
+ * - a distinct in-process registry key from the provisioning lock (and from
+ *   every other branch's content lock -- the provisioning locks already share
+ *   one key across branches);
+ * - a distinct on-disk lock directory, so the server-enforced mkdir cannot
+ *   collide either; and
+ * - no deadlock potential: the two locks are never both required, and the only
+ *   possible acquisition order (provision, then write) is consistent.
+ *
+ * `.canopy-meta/` is git-excluded in every branch clone (`ensureGitExclude`),
+ * so the lock directory can never dirty the working tree or be swept into
+ * `git add .` at publish time.
+ *
+ * ## Honest caveat (do not oversell this)
+ *
+ * `proper-lockfile` decides a holder is dead by reading the lock directory's
+ * mtime with `fs.stat`, which on EFS is served through the NFS attribute
+ * cache. A live holder refreshes every `stale/2`, but a waiter can read a
+ * cached mtime and conclude the lock is stale when it is not, taking it over.
+ * The failure mode of a bad takeover is exactly today's behavior (two
+ * unsynchronized writers), so this is a strict improvement -- not a proof of
+ * mutual exclusion. See docs/concurrency.md.
+ */
+/** On-disk name of the lock marker (a directory, created by mkdir). */
+export declare const CONTENT_WRITE_LOCK_NAME = "content-write.lock";
+/**
+ * Default bounded wait for a content write.
+ *
+ * Deliberately short. A rebase holds this lock for a fetch plus a replay plus
+ * N conflict rounds of git subprocesses on EFS -- far longer than any wait an
+ * interactive save can absorb, and longer than the API's own latency budget.
+ * So the wait is not sized to outlast a rebase (nothing reasonable could); it
+ * is sized to absorb lock handoff and the short holds of other writers, and to
+ * turn everything longer into a fast, explicit "retry" the editor can act on
+ * rather than a request that hangs toward the Lambda timeout. The worker
+ * revisits the branch next cycle, so the blocked state is transient.
+ *
+ * This is ALSO the writer-vs-writer budget, not only the rebase one. The lock
+ * is per-branch-root, so every write to one branch now serializes behind it
+ * where in-process serialization used to be per-entry -- bounded on Lambda
+ * (one invocation per container), but real under `next dev` and build-time
+ * provisioning across worker processes. The case to watch is a write whose
+ * in-lock path triggers a full `idIndex()` rescan of a large tree over EFS:
+ * that can plausibly exceed this budget and start 409ing unrelated saves.
+ * Making it configurable for prod tuning is tracked in
+ * .claude/future-tasks/content-write-lock-tuning-and-granularity.md.
+ */
+export declare const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
+/**
+ * Thrown when the bounded wait expires with the branch's content lock still
+ * held. Retriable -- callers translate this into a 409 with a message that
+ * says so.
+ *
+ * The message says "syncing OR another save" because BOTH produce it. The
+ * lock is taken by `write`/`delete`/`renameEntry` and by the admin
+ * repair-content-duplicates action as well as by the worker's rebase, so a
+ * message naming only the rebase was a confident claim about something that
+ * may not be happening. `api/content.ts` routes this error ahead of the
+ * generic conflict specifically so the editor sees this wording, which makes
+ * the wording load-bearing rather than cosmetic.
+ */
+export declare class ContentWriteLockBusyError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Acquire the branch's content-write lock WITHOUT waiting.
+ *
+ * Throws an error with `code === 'ELOCKED'` when a live holder has it. Used by
+ * the worker's rebase loop (which skips the branch and retries next cycle) and
+ * by tests standing in for a writer.
+ */
+export declare function tryAcquireContentWriteLock(branchRoot: string): Promise<() => Promise<void>>;
+/**
+ * Acquire the branch's content-write lock with a short bounded wait.
+ *
+ * Retries ONLY on genuine contention (`ELOCKED`), the same discipline
+ * `withOccFileLock` uses: proper-lockfile's own retry loop retries blindly on
+ * any error, which would burn the whole budget re-hitting e.g. ENOENT after
+ * the branch directory was deleted out from under the caller.
+ *
+ * @throws ContentWriteLockBusyError when the budget expires under contention.
+ */
+export declare function acquireContentWriteLock(branchRoot: string, waitMs?: number): Promise<() => Promise<void>>;
+/**
+ * Run `fn` holding the branch's content-write lock, releasing it in a
+ * `finally` so a throw can never strand it.
+ */
+export declare function withContentWriteLock<T>(branchRoot: string, fn: () => Promise<T>, waitMs?: number): Promise<T>;
+//# sourceMappingURL=content-write-lock.d.ts.map

package/dist/utils/content-write-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-write-lock.d.ts","sourceRoot":"","sources":["../../src/utils/content-write-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAUH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,uBAAuB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kCAAkC,OAAO,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBAEhD,OAAO,SAAuI;CAKjJ;AAYD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAA2C,GAClD,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAe9B;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,MAA2C,GAClD,OAAO,CAAC,CAAC,CAAC,CAOZ"}