@dbx-tools/core 0.6.68 → 0.6.70

package/index.ts

@@ -6,6 +6,7 @@ export * as bin from "./src/bin.ts";
 export * as brand from "./src/brand.ts";
 export * as exec from "./src/exec.ts";
 export * as file from "./src/file.ts";
+export * as fileLock from "./src/file-lock.ts";
 export * as processLock from "./src/process-lock.ts";
 export * as project from "./src/project.ts";
 export type { BinContext, BinSelectionContext, BinSelector, BinVersionOutput, BinVersionParser, BinOptions, BinUrl } from "./src/bin.ts";
@@ -13,4 +14,5 @@ export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContex
 export type { BrandContext, BrandContextInput } from "./src/brand.ts";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.ts";
 export type { ExecStdio, LineHandler, StdioOption, ExecResult, ChildProcessResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec.ts";
+export type { FileLockBackend, FileLockAcquisition, FileLockOptions } from "./src/file-lock.ts";
 export type { ProjectContext } from "./src/project.ts";

package/lib/index.d.ts

@@ -2,6 +2,7 @@ export * as bin from "./src/bin.ts";
 export * as brand from "./src/brand.ts";
 export * as exec from "./src/exec.ts";
 export * as file from "./src/file.ts";
+export * as fileLock from "./src/file-lock.ts";
 export * as processLock from "./src/process-lock.ts";
 export * as project from "./src/project.ts";
 export type { BinContext, BinSelectionContext, BinSelector, BinVersionOutput, BinVersionParser, BinOptions, BinUrl } from "./src/bin.ts";
@@ -9,4 +10,5 @@ export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContex
 export type { BrandContext, BrandContextInput } from "./src/brand.ts";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.ts";
 export type { ExecStdio, LineHandler, StdioOption, ExecResult, ChildProcessResult, ExecOptions, SyncExecStdio, SyncExecOptions, SpawnArgs } from "./src/exec.ts";
+export type { FileLockBackend, FileLockAcquisition, FileLockOptions } from "./src/file-lock.ts";
 export type { ProjectContext } from "./src/project.ts";

package/lib/index.js

@@ -5,8 +5,9 @@ export * as bin from "./src/bin.js";
 export * as brand from "./src/brand.js";
 export * as exec from "./src/exec.js";
 export * as file from "./src/file.js";
+export * as fileLock from "./src/file-lock.js";
 export * as processLock from "./src/process-lock.js";
 export * as project from "./src/project.js";
 export { BrandContextSchema, defaultBrandContext, parseBrandContext, brandContextJsonSchema, brandContextPrompt } from "./src/brand.js";
 export { COMMAND_NOT_FOUND_EXIT_CODE } from "./src/exec.js";
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxXQUFXLE1BQU0sdUJBQXVCLENBQUM7QUFDckQsT0FBTyxLQUFLLE9BQU8sTUFBTSxrQkFBa0IsQ0FBQztBQUU1QyxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsbUJBQW1CLEVBQUUsaUJBQWlCLEVBQUUsc0JBQXNCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUV4SSxPQUFPLEVBQUUsMkJBQTJCLEVBQUUsTUFBTSxlQUFlLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBHRU5FUkFURUQgYnkgcHJvamVuIHdhdGNoIC0gRE8gTk9UIEVESVQuXG4vLyBSZWdlbmVyYXRlZCBmcm9tIHRoZSBleHBvcnRpbmcgbW9kdWxlcyBpbiAuL3NyYy5cbi8vIEhhbmQgZWRpdHMgYXJlIG92ZXJ3cml0dGVuIG9uIHRoZSBuZXh0IHdhdGNoOyB0aGlzIGZpbGUgaXMgcmVhZC1vbmx5LlxuXG5leHBvcnQgKiBhcyBiaW4gZnJvbSBcIi4vc3JjL2Jpbi50c1wiO1xuZXhwb3J0ICogYXMgYnJhbmQgZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgKiBhcyBleGVjIGZyb20gXCIuL3NyYy9leGVjLnRzXCI7XG5leHBvcnQgKiBhcyBmaWxlIGZyb20gXCIuL3NyYy9maWxlLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9jZXNzTG9jayBmcm9tIFwiLi9zcmMvcHJvY2Vzcy1sb2NrLnRzXCI7XG5leHBvcnQgKiBhcyBwcm9qZWN0IGZyb20gXCIuL3NyYy9wcm9qZWN0LnRzXCI7XG5leHBvcnQgdHlwZSB7IEJpbkNvbnRleHQsIEJpblNlbGVjdGlvbkNvbnRleHQsIEJpblNlbGVjdG9yLCBCaW5WZXJzaW9uT3V0cHV0LCBCaW5WZXJzaW9uUGFyc2VyLCBCaW5PcHRpb25zLCBCaW5VcmwgfSBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgeyBCcmFuZENvbnRleHRTY2hlbWEsIGRlZmF1bHRCcmFuZENvbnRleHQsIHBhcnNlQnJhbmRDb250ZXh0LCBicmFuZENvbnRleHRKc29uU2NoZW1hLCBicmFuZENvbnRleHRQcm9tcHQgfSBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCB0eXBlIHsgQnJhbmRDb250ZXh0LCBCcmFuZENvbnRleHRJbnB1dCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHsgQ09NTUFORF9OT1RfRk9VTkRfRVhJVF9DT0RFIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgRXhlY1N0ZGlvLCBMaW5lSGFuZGxlciwgU3RkaW9PcHRpb24sIEV4ZWNSZXN1bHQsIENoaWxkUHJvY2Vzc1Jlc3VsdCwgRXhlY09wdGlvbnMsIFN5bmNFeGVjU3RkaW8sIFN5bmNFeGVjT3B0aW9ucywgU3Bhd25BcmdzIH0gZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCB0eXBlIHsgUHJvamVjdENvbnRleHQgfSBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuIl19
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssS0FBSyxNQUFNLGdCQUFnQixDQUFDO0FBQ3hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sZUFBZSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFdBQVcsTUFBTSx1QkFBdUIsQ0FBQztBQUNyRCxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBRTVDLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxtQkFBbUIsRUFBRSxpQkFBaUIsRUFBRSxzQkFBc0IsRUFBRSxrQkFBa0IsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBRXhJLE9BQU8sRUFBRSwyQkFBMkIsRUFBRSxNQUFNLGVBQWUsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEdFTkVSQVRFRCBieSBwcm9qZW4gd2F0Y2ggLSBETyBOT1QgRURJVC5cbi8vIFJlZ2VuZXJhdGVkIGZyb20gdGhlIGV4cG9ydGluZyBtb2R1bGVzIGluIC4vc3JjLlxuLy8gSGFuZCBlZGl0cyBhcmUgb3ZlcndyaXR0ZW4gb24gdGhlIG5leHQgd2F0Y2g7IHRoaXMgZmlsZSBpcyByZWFkLW9ubHkuXG5cbmV4cG9ydCAqIGFzIGJpbiBmcm9tIFwiLi9zcmMvYmluLnRzXCI7XG5leHBvcnQgKiBhcyBicmFuZCBmcm9tIFwiLi9zcmMvYnJhbmQudHNcIjtcbmV4cG9ydCAqIGFzIGV4ZWMgZnJvbSBcIi4vc3JjL2V4ZWMudHNcIjtcbmV4cG9ydCAqIGFzIGZpbGUgZnJvbSBcIi4vc3JjL2ZpbGUudHNcIjtcbmV4cG9ydCAqIGFzIGZpbGVMb2NrIGZyb20gXCIuL3NyYy9maWxlLWxvY2sudHNcIjtcbmV4cG9ydCAqIGFzIHByb2Nlc3NMb2NrIGZyb20gXCIuL3NyYy9wcm9jZXNzLWxvY2sudHNcIjtcbmV4cG9ydCAqIGFzIHByb2plY3QgZnJvbSBcIi4vc3JjL3Byb2plY3QudHNcIjtcbmV4cG9ydCB0eXBlIHsgQmluQ29udGV4dCwgQmluU2VsZWN0aW9uQ29udGV4dCwgQmluU2VsZWN0b3IsIEJpblZlcnNpb25PdXRwdXQsIEJpblZlcnNpb25QYXJzZXIsIEJpbk9wdGlvbnMsIEJpblVybCB9IGZyb20gXCIuL3NyYy9iaW4udHNcIjtcbmV4cG9ydCB7IEJyYW5kQ29udGV4dFNjaGVtYSwgZGVmYXVsdEJyYW5kQ29udGV4dCwgcGFyc2VCcmFuZENvbnRleHQsIGJyYW5kQ29udGV4dEpzb25TY2hlbWEsIGJyYW5kQ29udGV4dFByb21wdCB9IGZyb20gXCIuL3NyYy9icmFuZC50c1wiO1xuZXhwb3J0IHR5cGUgeyBCcmFuZENvbnRleHQsIEJyYW5kQ29udGV4dElucHV0IH0gZnJvbSBcIi4vc3JjL2JyYW5kLnRzXCI7XG5leHBvcnQgeyBDT01NQU5EX05PVF9GT1VORF9FWElUX0NPREUgfSBmcm9tIFwiLi9zcmMvZXhlYy50c1wiO1xuZXhwb3J0IHR5cGUgeyBFeGVjU3RkaW8sIExpbmVIYW5kbGVyLCBTdGRpb09wdGlvbiwgRXhlY1Jlc3VsdCwgQ2hpbGRQcm9jZXNzUmVzdWx0LCBFeGVjT3B0aW9ucywgU3luY0V4ZWNTdGRpbywgU3luY0V4ZWNPcHRpb25zLCBTcGF3bkFyZ3MgfSBmcm9tIFwiLi9zcmMvZXhlYy50c1wiO1xuZXhwb3J0IHR5cGUgeyBGaWxlTG9ja0JhY2tlbmQsIEZpbGVMb2NrQWNxdWlzaXRpb24sIEZpbGVMb2NrT3B0aW9ucyB9IGZyb20gXCIuL3NyYy9maWxlLWxvY2sudHNcIjtcbmV4cG9ydCB0eXBlIHsgUHJvamVjdENvbnRleHQgfSBmcm9tIFwiLi9zcmMvcHJvamVjdC50c1wiO1xuIl19

package/lib/src/file-lock.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Cascading cross-process mutual exclusion via a lockfile.
+ *
+ * Serializes concurrent *processes* (two `bun run demo` shells, a CLI beside a
+ * server) on the same key. For in-process / worker-thread exclusion use
+ * {@link withProcessLock} from `./process-lock.ts` instead.
+ *
+ * Backends, in order:
+ *
+ * 1. **flock** — `flock(2)` via Bun FFI on Unix when `bun:ffi` can load libc.
+ *    Not available on Windows, and not available under plain Node (no FFI).
+ *    Kernel releases the lock when the fd closes (including process death).
+ * 2. **file** — atomic lock-directory creation. This is the strategy used by
+ *    `proper-lockfile`: `mkdir` is atomic on Windows, Unix, and network file
+ *    systems where `open(..., "wx")` may not be reliable. Optional stale
+ *    detection uses the directory mtime plus a heartbeat.
+ *
+ * The first backend that can be *initialized* is used for the whole call. A busy
+ * lock waits; an unavailable backend falls through to the next.
+ *
+ * @module
+ */
+/** Backends {@link withFileLock} can attempt, in cascade order. */
+export type FileLockBackend = "flock" | "file";
+/** Result metadata when a caller wants to know which backend ran. */
+export interface FileLockAcquisition {
+    backend: FileLockBackend;
+}
+export interface FileLockOptions {
+    /**
+     * Directory for lockfiles. Defaults to `$TMPDIR/dbx-tools-locks`.
+     */
+    dir?: string;
+    /** Override the cascade. Defaults to `flock` → `file`. */
+    backends?: readonly FileLockBackend[];
+    /**
+     * Stop waiting and throw after this many milliseconds. Omit to poll forever.
+     */
+    timeoutMs?: number;
+    /**
+     * Age after which an unrefreshed lock directory may be removed. Omit to
+     * disable stale detection. Only used by the `file` backend.
+     */
+    staleMs?: number;
+    /**
+     * Interval for refreshing the lock directory mtime when `staleMs` is set.
+     * Defaults to half of `staleMs`.
+     */
+    updateMs?: number;
+    /** Invoked once the backend for this call has been chosen. */
+    onAcquire?: (acquisition: FileLockAcquisition) => void;
+}
+/**
+ * Run `fn` while holding a cross-process lock named by `key`.
+ *
+ * `key` is canonicalized with `object.toStableKey`, the same identity rule as
+ * process and Postgres advisory locks.
+ *
+ * @example
+ * await withFileLock(["cache", "appkit"], async () => {
+ *   await migrate();
+ * });
+ */
+export declare function withFileLock<T>(key: unknown, fn: () => T | Promise<T>, options?: FileLockOptions): Promise<T>;

package/lib/src/file-lock.js

@@ -0,0 +1,242 @@
+/**
+ * Cascading cross-process mutual exclusion via a lockfile.
+ *
+ * Serializes concurrent *processes* (two `bun run demo` shells, a CLI beside a
+ * server) on the same key. For in-process / worker-thread exclusion use
+ * {@link withProcessLock} from `./process-lock.ts` instead.
+ *
+ * Backends, in order:
+ *
+ * 1. **flock** — `flock(2)` via Bun FFI on Unix when `bun:ffi` can load libc.
+ *    Not available on Windows, and not available under plain Node (no FFI).
+ *    Kernel releases the lock when the fd closes (including process death).
+ * 2. **file** — atomic lock-directory creation. This is the strategy used by
+ *    `proper-lockfile`: `mkdir` is atomic on Windows, Unix, and network file
+ *    systems where `open(..., "wx")` may not be reliable. Optional stale
+ *    detection uses the directory mtime plus a heartbeat.
+ *
+ * The first backend that can be *initialized* is used for the whole call. A busy
+ * lock waits; an unavailable backend falls through to the next.
+ *
+ * @module
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { mkdir, open, rm, stat, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { async, error, functionModule, hash, log, object } from "@dbx-tools/shared-core";
+const logger = log.logger("core:file-lock");
+const DEFAULT_BACKENDS = ["flock", "file"];
+/** Poll interval while waiting for a contended OS lock. */
+const POLL_MS = 50;
+/** `flock(2)` operation bits (Linux / macOS / BSD). */
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+/**
+ * Run `fn` while holding a cross-process lock named by `key`.
+ *
+ * `key` is canonicalized with `object.toStableKey`, the same identity rule as
+ * process and Postgres advisory locks.
+ *
+ * @example
+ * await withFileLock(["cache", "appkit"], async () => {
+ *   await migrate();
+ * });
+ */
+export async function withFileLock(key, fn, options = {}) {
+    validateOptions(options);
+    const id = lockId(key);
+    const backends = options.backends ?? DEFAULT_BACKENDS;
+    const dir = options.dir ?? join(tmpdir(), "dbx-tools-locks");
+    const deadline = options.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs;
+    for (const backend of backends) {
+        switch (backend) {
+            case "flock": {
+                const lockPath = join(dir, `${id}.flock`);
+                const flock = await resolveFlock();
+                if (!flock) {
+                    logger.debug("lock backend unavailable", { backend, key: id });
+                    continue;
+                }
+                logger.debug("acquiring lock", { backend, key: id, path: lockPath });
+                options.onAcquire?.({ backend });
+                return holdFlock(lockPath, flock, deadline, fn);
+            }
+            case "file": {
+                const lockPath = join(dir, `${id}.lock`);
+                logger.debug("acquiring lock", { backend, key: id, path: lockPath });
+                options.onAcquire?.({ backend });
+                return holdLockDirectory(lockPath, deadline, options.staleMs, options.updateMs, fn);
+            }
+            default: {
+                const _exhaustive = backend;
+                throw new Error(`unknown file-lock backend: ${String(_exhaustive)}`);
+            }
+        }
+    }
+    throw new Error("withFileLock: no lock backend available");
+}
+function validateOptions(options) {
+    if (options.timeoutMs !== undefined && options.timeoutMs < 0) {
+        throw new TypeError("timeoutMs must be non-negative");
+    }
+    if (options.staleMs !== undefined && options.staleMs <= 0) {
+        throw new TypeError("staleMs must be positive");
+    }
+    if (options.updateMs !== undefined) {
+        if (options.staleMs === undefined) {
+            throw new TypeError("updateMs requires staleMs");
+        }
+        if (options.updateMs <= 0 || options.updateMs > options.staleMs / 2) {
+            throw new TypeError("updateMs must be positive and no greater than half of staleMs");
+        }
+    }
+}
+/** Canonical filesystem-safe id for a lock key. */
+function lockId(key) {
+    const stable = object
+        .toOneOrMany(key)
+        .map((part) => object.toStableKey(part))
+        .join("\u0000");
+    // Short digest so paths stay well under OS limits; collisions are fine — they
+    // only merge critical sections that already shared a key string.
+    return hash.fnvHash(stable);
+}
+/**
+ * Resolve `flock(2)` through Bun FFI when possible.
+ *
+ * Memoized: the FFI import + libc `dlopen` run once per process. Returns
+ * `undefined` on Windows, under plain Node, or when libc cannot be loaded —
+ * callers fall through to the next backend. A miss is cached too, so a process
+ * that cannot flock never retries the load.
+ */
+const resolveFlock = functionModule.memoize(async () => {
+    if (process.platform === "win32")
+        return undefined;
+    if (!process.versions.bun)
+        return undefined;
+    try {
+        // Dynamic specifier so `tsc` (no `@types` for `bun:ffi`) does not resolve it;
+        // the import only succeeds under Bun at runtime.
+        const specifier = "bun:ffi";
+        const ffi = (await import(__rewriteRelativeImportExtension(specifier)));
+        const libPath = process.platform === "darwin" ? "libSystem.B.dylib" : `libc.${ffi.suffix}`;
+        const lib = ffi.dlopen(libPath, {
+            flock: { args: ["i32", "i32"], returns: "i32" },
+        });
+        return lib.symbols.flock;
+    }
+    catch (cause) {
+        logger.debug("flock FFI unavailable", { error: error.errorMessage(cause) });
+        return undefined;
+    }
+});
+async function holdFlock(lockPath, flock, deadline, fn) {
+    await ensureParentDir(lockPath);
+    const handle = await open(lockPath, "a+");
+    try {
+        await waitForFlock(handle.fd, flock, lockPath, deadline);
+        try {
+            return await fn();
+        }
+        finally {
+            flock(handle.fd, LOCK_UN);
+        }
+    }
+    finally {
+        await handle.close().catch(() => { });
+    }
+}
+async function waitForFlock(fd, flock, lockPath, deadline) {
+    for (;;) {
+        const rc = flock(fd, LOCK_EX | LOCK_NB);
+        if (rc === 0)
+            return;
+        assertBeforeDeadline(lockPath, deadline);
+        await async.sleep(POLL_MS);
+    }
+}
+/**
+ * Atomic lock-directory creation — the portable / Windows path.
+ *
+ * `mkdir` is the same primitive used by `proper-lockfile`: it is atomic across
+ * supported local and network filesystems. When stale detection is enabled,
+ * the holder refreshes mtime so a live long-running lock is never reclaimed.
+ */
+async function holdLockDirectory(lockPath, deadline, staleMs, updateMs, fn) {
+    await ensureParentDir(lockPath);
+    await acquireLockDirectory(lockPath, deadline, staleMs);
+    const stopHeartbeat = startHeartbeat(lockPath, staleMs, updateMs);
+    try {
+        return await fn();
+    }
+    finally {
+        stopHeartbeat();
+        await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+    }
+}
+async function acquireLockDirectory(lockPath, deadline, staleMs) {
+    for (;;) {
+        try {
+            await mkdir(lockPath);
+            return;
+        }
+        catch (cause) {
+            const err = cause;
+            if (err.code !== "EEXIST")
+                throw error.toError(cause);
+            if (staleMs !== undefined)
+                await maybeReclaimStale(lockPath, staleMs);
+            assertBeforeDeadline(lockPath, deadline);
+            await async.sleep(POLL_MS);
+        }
+    }
+}
+async function maybeReclaimStale(lockPath, staleMs) {
+    try {
+        const { mtimeMs } = await stat(lockPath);
+        const age = Date.now() - mtimeMs;
+        if (age < staleMs)
+            return;
+        logger.debug("reclaiming stale lock directory", { path: lockPath, ageMs: age });
+        await rm(lockPath, { recursive: true, force: true });
+    }
+    catch (cause) {
+        const err = cause;
+        if (err.code !== "ENOENT")
+            throw error.toError(cause);
+    }
+}
+function startHeartbeat(lockPath, staleMs, updateMs) {
+    if (staleMs === undefined)
+        return () => { };
+    const intervalMs = updateMs ?? Math.max(1, Math.floor(staleMs / 2));
+    const timer = setInterval(() => {
+        const now = new Date();
+        void utimes(lockPath, now, now).catch((cause) => {
+            logger.warn("file lock heartbeat failed", {
+                path: lockPath,
+                error: error.errorMessage(cause),
+            });
+        });
+    }, intervalMs);
+    timer.unref();
+    return () => clearInterval(timer);
+}
+function assertBeforeDeadline(lockPath, deadline) {
+    if (deadline !== undefined && Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for file lock: ${lockPath}`);
+    }
+}
+async function ensureParentDir(lockPath) {
+    await mkdir(dirname(lockPath), { recursive: true });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZS1sb2NrLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ZpbGUtbG9jay50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBcUJHOzs7Ozs7Ozs7QUFFSCxPQUFPLEVBQUUsS0FBSyxFQUFFLElBQUksRUFBRSxFQUFFLEVBQUUsSUFBSSxFQUFFLE1BQU0sRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQ2pFLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxTQUFTLENBQUM7QUFDakMsT0FBTyxFQUFFLE9BQU8sRUFBRSxJQUFJLEVBQUUsTUFBTSxXQUFXLENBQUM7QUFFMUMsT0FBTyxFQUFFLEtBQUssRUFBRSxLQUFLLEVBQUUsY0FBYyxFQUFFLElBQUksRUFBRSxHQUFHLEVBQUUsTUFBTSxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFekYsTUFBTSxNQUFNLEdBQUcsR0FBRyxDQUFDLE1BQU0sQ0FBQyxnQkFBZ0IsQ0FBQyxDQUFDO0FBSzVDLE1BQU0sZ0JBQWdCLEdBQStCLENBQUMsT0FBTyxFQUFFLE1BQU0sQ0FBQyxDQUFDO0FBRXZFLDJEQUEyRDtBQUMzRCxNQUFNLE9BQU8sR0FBRyxFQUFFLENBQUM7QUFFbkIsdURBQXVEO0FBQ3ZELE1BQU0sT0FBTyxHQUFHLENBQUMsQ0FBQztBQUNsQixNQUFNLE9BQU8sR0FBRyxDQUFDLENBQUM7QUFDbEIsTUFBTSxPQUFPLEdBQUcsQ0FBQyxDQUFDO0FBMENsQjs7Ozs7Ozs7OztHQVVHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxZQUFZLENBQ2hDLEdBQVksRUFDWixFQUF3QixFQUN4QixVQUEyQixFQUFFO0lBRTdCLGVBQWUsQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUN6QixNQUFNLEVBQUUsR0FBRyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDdkIsTUFBTSxRQUFRLEdBQUcsT0FBTyxDQUFDLFFBQVEsSUFBSSxnQkFBZ0IsQ0FBQztJ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RSxJQUFJLEVBQUUsQ0FBQyxDQUFDO0FBQ3RELENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvKipcbiAqIENhc2NhZGluZyBjcm9zcy1wcm9jZXNzIG11dHVhbCBleGNsdXNpb24gdmlhIGEgbG9ja2ZpbGUuXG4gKlxuICogU2VyaWFsaXplcyBjb25jdXJyZW50ICpwcm9jZXNzZXMqICh0d28gYGJ1biBydW4gZGVtb2Agc2hlbGxzLCBhIENMSSBiZXNpZGUgYVxuICogc2VydmVyKSBvbiB0aGUgc2FtZSBrZXkuIEZvciBpbi1wcm9jZXNzIC8gd29ya2VyLXRocmVhZCBleGNsdXNpb24gdXNlXG4gKiB7QGxpbmsgd2l0aFByb2Nlc3NMb2NrfSBmcm9tIGAuL3Byb2Nlc3MtbG9jay50c2AgaW5zdGVhZC5cbiAqXG4gKiBCYWNrZW5kcywgaW4gb3JkZXI6XG4gKlxuICogMS4gKipmbG9jayoqIOKAlCBgZmxvY2soMilgIHZpYSBCdW4gRkZJIG9uIFVuaXggd2hlbiBgYnVuOmZmaWAgY2FuIGxvYWQgbGliYy5cbiAqICAgIE5vdCBhdmFpbGFibGUgb24gV2luZG93cywgYW5kIG5vdCBhdmFpbGFibGUgdW5kZXIgcGxhaW4gTm9kZSAobm8gRkZJKS5cbiAqICAgIEtlcm5lbCByZWxlYXNlcyB0aGUgbG9jayB3aGVuIHRoZSBmZCBjbG9zZXMgKGluY2x1ZGluZyBwcm9jZXNzIGRlYXRoKS5cbiAqIDIuICoqZmlsZSoqIOKAlCBhdG9taWMgbG9jay1kaXJlY3RvcnkgY3JlYXRpb24uIFRoaXMgaXMgdGhlIHN0cmF0ZWd5IHVzZWQgYnlcbiAqICAgIGBwcm9wZXItbG9ja2ZpbGVgOiBgbWtkaXJgIGlzIGF0b21pYyBvbiBXaW5kb3dzLCBVbml4LCBhbmQgbmV0d29yayBmaWxlXG4gKiAgICBzeXN0ZW1zIHdoZXJlIGBvcGVuKC4uLiwgXCJ3eFwiKWAgbWF5IG5vdCBiZSByZWxpYWJsZS4gT3B0aW9uYWwgc3RhbGVcbiAqICAgIGRldGVjdGlvbiB1c2VzIHRoZSBkaXJlY3RvcnkgbXRpbWUgcGx1cyBhIGhlYXJ0YmVhdC5cbiAqXG4gKiBUaGUgZmlyc3QgYmFja2VuZCB0aGF0IGNhbiBiZSAqaW5pdGlhbGl6ZWQqIGlzIHVzZWQgZm9yIHRoZSB3aG9sZSBjYWxsLiBBIGJ1c3lcbiAqIGxvY2sgd2FpdHM7IGFuIHVuYXZhaWxhYmxlIGJhY2tlbmQgZmFsbHMgdGhyb3VnaCB0byB0aGUgbmV4dC5cbiAqXG4gKiBAbW9kdWxlXG4gKi9cblxuaW1wb3J0IHsgbWtkaXIsIG9wZW4sIHJtLCBzdGF0LCB1dGltZXMgfSBmcm9tIFwibm9kZTpmcy9wcm9taXNlc1wiO1xuaW1wb3J0IHsgdG1wZGlyIH0gZnJvbSBcIm5vZGU6b3NcIjtcbmltcG9ydCB7IGRpcm5hbWUsIGpvaW4gfSBmcm9tIFwibm9kZTpwYXRoXCI7XG5cbmltcG9ydCB7IGFzeW5jLCBlcnJvciwgZnVuY3Rpb25Nb2R1bGUsIGhhc2gsIGxvZywgb2JqZWN0IH0gZnJvbSBcIkBkYngtdG9vbHMvc2hhcmVkLWNvcmVcIjtcblxuY29uc3QgbG9nZ2VyID0gbG9nLmxvZ2dlcihcImNvcmU6ZmlsZS1sb2NrXCIpO1xuXG4vKiogQmFja2VuZHMge0BsaW5rIHdpdGhGaWxlTG9ja30gY2FuIGF0dGVtcHQsIGluIGNhc2NhZGUgb3JkZXIuICovXG5leHBvcnQgdHlwZSBGaWxlTG9ja0JhY2tlbmQgPSBcImZsb2NrXCIgfCBcImZpbGVcIjtcblxuY29uc3QgREVGQVVMVF9CQUNLRU5EUzogcmVhZG9ubHkgRmlsZUxvY2tCYWNrZW5kW10gPSBbXCJmbG9ja1wiLCBcImZpbGVcIl07XG5cbi8qKiBQb2xsIGludGVydmFsIHdoaWxlIHdhaXRpbmcgZm9yIGEgY29udGVuZGVkIE9TIGxvY2suICovXG5jb25zdCBQT0xMX01TID0gNTA7XG5cbi8qKiBgZmxvY2soMilgIG9wZXJhdGlvbiBiaXRzIChMaW51eCAvIG1hY09TIC8gQlNEKS4gKi9cbmNvbnN0IExPQ0tfRVggPSAyO1xuY29uc3QgTE9DS19OQiA9IDQ7XG5jb25zdCBMT0NLX1VOID0gODtcblxuLyoqIFJlc3VsdCBtZXRhZGF0YSB3aGVuIGEgY2FsbGVyIHdhbnRzIHRvIGtub3cgd2hpY2ggYmFja2VuZCByYW4uICovXG5leHBvcnQgaW50ZXJmYWNlIEZpbGVMb2NrQWNxdWlzaXRpb24ge1xuICBiYWNrZW5kOiBGaWxlTG9ja0JhY2tlbmQ7XG59XG5cbmV4cG9ydCBpbnRlcmZhY2UgRmlsZUxvY2tPcHRpb25zIHtcbiAgLyoqXG4gICAqIERpcmVjdG9yeSBmb3IgbG9ja2ZpbGVzLiBEZWZhdWx0cyB0byBgJFRNUERJUi9kYngtdG9vbHMtbG9ja3NgLlxuICAgKi9cbiAgZGlyPzogc3RyaW5nO1xuICAvKiogT3ZlcnJpZGUgdGhlIGNhc2NhZGUuIERlZmF1bHRzIHRvIGBmbG9ja2Ag4oaSIGBmaWxlYC4gKi9cbiAgYmFja2VuZHM/OiByZWFkb25seSBGaWxlTG9ja0JhY2tlbmRbXTtcbiAgLyoqXG4gICAqIFN0b3Agd2FpdGluZyBhbmQgdGhyb3cgYWZ0ZXIgdGhpcyBtYW55IG1pbGxpc2Vjb25kcy4gT21pdCB0byBwb2xsIGZvcmV2ZXIuXG4gICAqL1xuICB0aW1lb3V0TXM/OiBudW1iZXI7XG4gIC8qKlxuICAgKiBBZ2UgYWZ0ZXIgd2hpY2ggYW4gdW5yZWZyZXNoZWQgbG9jayBkaXJlY3RvcnkgbWF5IGJlIHJlbW92ZWQuIE9taXQgdG9cbiAgICogZGlzYWJsZSBzdGFsZSBkZXRlY3Rpb24uIE9ubHkgdXNlZCBieSB0aGUgYGZpbGVgIGJhY2tlbmQuXG4gICAqL1xuICBzdGFsZU1zPzogbnVtYmVyO1xuICAvKipcbiAgICogSW50ZXJ2YWwgZm9yIHJlZnJlc2hpbmcgdGhlIGxvY2sgZGlyZWN0b3J5IG10aW1lIHdoZW4gYHN0YWxlTXNgIGlzIHNldC5cbiAgICogRGVmYXVsdHMgdG8gaGFsZiBvZiBgc3RhbGVNc2AuXG4gICAqL1xuICB1cGRhdGVNcz86IG51bWJlcjtcbiAgLyoqIEludm9rZWQgb25jZSB0aGUgYmFja2VuZCBmb3IgdGhpcyBjYWxsIGhhcyBiZWVuIGNob3Nlbi4gKi9cbiAgb25BY3F1aXJlPzogKGFjcXVpc2l0aW9uOiBGaWxlTG9ja0FjcXVpc2l0aW9uKSA9PiB2b2lkO1xufVxuXG50eXBlIEZsb2NrRm4gPSAoZmQ6IG51bWJlciwgb3BlcmF0aW9uOiBudW1iZXIpID0+IG51bWJlcjtcblxuaW50ZXJmYWNlIEJ1bkZmaU1vZHVsZSB7XG4gIGRsb3BlbjogKFxuICAgIHBhdGg6IHN0cmluZyxcbiAgICBzeW1ib2xzOiBSZWNvcmQ8c3RyaW5nLCB7IGFyZ3M6IHN0cmluZ1tdOyByZXR1cm5zOiBzdHJpbmcgfT4sXG4gICkgPT4geyBzeW1ib2xzOiB7IGZsb2NrOiBGbG9ja0ZuIH0gfTtcbiAgc3VmZml4OiBzdHJpbmc7XG59XG5cbi8qKlxuICogUnVuIGBmbmAgd2hpbGUgaG9sZGluZyBhIGNyb3NzLXByb2Nlc3MgbG9jayBuYW1lZCBieSBga2V5YC5cbiAqXG4gKiBga2V5YCBpcyBjYW5vbmljYWxpemVkIHdpdGggYG9iamVjdC50b1N0YWJsZUtleWAsIHRoZSBzYW1lIGlkZW50aXR5IHJ1bGUgYXNcbiAqIHByb2Nlc3MgYW5kIFBvc3RncmVzIGFkdmlzb3J5IGxvY2tzLlxuICpcbiAqIEBleGFtcGxlXG4gKiBhd2FpdCB3aXRoRmlsZUxvY2soW1wiY2FjaGVcIiwgXCJhcHBraXRcIl0sIGFzeW5jICgpID0+IHtcbiAqICAgYXdhaXQgbWlncmF0ZSgpO1xuICogfSk7XG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiB3aXRoRmlsZUxvY2s8VD4oXG4gIGtleTogdW5rbm93bixcbiAgZm46ICgpID0+IFQgfCBQcm9taXNlPFQ+LFxuICBvcHRpb25zOiBGaWxlTG9ja09wdGlvbnMgPSB7fSxcbik6IFByb21pc2U8VD4ge1xuICB2YWxpZGF0ZU9wdGlvbnMob3B0aW9ucyk7XG4gIGNvbnN0IGlkID0gbG9ja0lkKGtleSk7XG4gIGNvbnN0IGJhY2tlbmRzID0gb3B0aW9ucy5iYWNrZW5kcyA/PyBERUZBVUxUX0JBQ0tFTkRTO1xuICBjb25zdCBkaXIgPSBvcHRpb25zLmRpciA/PyBqb2luKHRtcGRpcigpLCBcImRieC10b29scy1sb2Nrc1wiKTtcbiAgY29uc3QgZGVhZGxpbmUgPSBvcHRpb25zLnRpbWVvdXRNcyA9PT0gdW5kZWZpbmVkID8gdW5kZWZpbmVkIDogRGF0ZS5ub3coKSArIG9wdGlvbnMudGltZW91dE1zO1xuXG4gIGZvciAoY29uc3QgYmFja2VuZCBvZiBiYWNrZW5kcykge1xuICAgIHN3aXRjaCAoYmFja2VuZCkge1xuICAgICAgY2FzZSBcImZsb2NrXCI6IHtcbiAgICAgICAgY29uc3QgbG9ja1BhdGggPSBqb2luKGRpciwgYCR7aWR9LmZsb2NrYCk7XG4gICAgICAgIGNvbnN0IGZsb2NrID0gYXdhaXQgcmVzb2x2ZUZsb2NrKCk7XG4gICAgICAgIGlmICghZmxvY2spIHtcbiAgICAgICAgICBsb2dnZXIuZGVidWcoXCJsb2NrIGJhY2tlbmQgdW5hdmFpbGFibGVcIiwgeyBiYWNrZW5kLCBrZXk6IGlkIH0pO1xuICAgICAgICAgIGNvbnRpbnVlO1xuICAgICAgICB9XG4gICAgICAgIGxvZ2dlci5kZWJ1ZyhcImFjcXVpcmluZyBsb2NrXCIsIHsgYmFja2VuZCwga2V5OiBpZCwgcGF0aDogbG9ja1BhdGggfSk7XG4gICAgICAgIG9wdGlvbnMub25BY3F1aXJlPy4oeyBiYWNrZW5kIH0pO1xuICAgICAgICByZXR1cm4gaG9sZEZsb2NrKGxvY2tQYXRoLCBmbG9jaywgZGVhZGxpbmUsIGZuKTtcbiAgICAgIH1cbiAgICAgIGNhc2UgXCJmaWxlXCI6IHtcbiAgICAgICAgY29uc3QgbG9ja1BhdGggPSBqb2luKGRpciwgYCR7aWR9LmxvY2tgKTtcbiAgICAgICAgbG9nZ2VyLmRlYnVnKFwiYWNxdWlyaW5nIGxvY2tcIiwgeyBiYWNrZW5kLCBrZXk6IGlkLCBwYXRoOiBsb2NrUGF0aCB9KTtcbiAgICAgICAgb3B0aW9ucy5vbkFjcXVpcmU/Lih7IGJhY2tlbmQgfSk7XG4gICAgICAgIHJldHVybiBob2xkTG9ja0RpcmVjdG9yeShsb2NrUGF0aCwgZGVhZGxpbmUsIG9wdGlvbnMuc3RhbGVNcywgb3B0aW9ucy51cGRhdGVNcywgZm4pO1xuICAgICAgfVxuICAgICAgZGVmYXVsdDoge1xuICAgICAgICBjb25zdCBfZXhoYXVzdGl2ZTogbmV2ZXIgPSBiYWNrZW5kO1xuICAgICAgICB0aHJvdyBuZXcgRXJyb3IoYHVua25vd24gZmlsZS1sb2NrIGJhY2tlbmQ6ICR7U3RyaW5nKF9leGhhdXN0aXZlKX1gKTtcbiAgICAgIH1cbiAgICB9XG4gIH1cblxuICB0aHJvdyBuZXcgRXJyb3IoXCJ3aXRoRmlsZUxvY2s6IG5vIGxvY2sgYmFja2VuZCBhdmFpbGFibGVcIik7XG59XG5cbmZ1bmN0aW9uIHZhbGlkYXRlT3B0aW9ucyhvcHRpb25zOiBGaWxlTG9ja09wdGlvbnMpOiB2b2lkIHtcbiAgaWYgKG9wdGlvbnMudGltZW91dE1zICE9PSB1bmRlZmluZWQgJiYgb3B0aW9ucy50aW1lb3V0TXMgPCAwKSB7XG4gICAgdGhyb3cgbmV3IFR5cGVFcnJvcihcInRpbWVvdXRNcyBtdXN0IGJlIG5vbi1uZWdhdGl2ZVwiKTtcbiAgfVxuICBpZiAob3B0aW9ucy5zdGFsZU1zICE9PSB1bmRlZmluZWQgJiYgb3B0aW9ucy5zdGFsZU1zIDw9IDApIHtcbiAgICB0aHJvdyBuZXcgVHlwZUVycm9yKFwic3RhbGVNcyBtdXN0IGJlIHBvc2l0aXZlXCIpO1xuICB9XG4gIGlmIChvcHRpb25zLnVwZGF0ZU1zICE9PSB1bmRlZmluZWQpIHtcbiAgICBpZiAob3B0aW9ucy5zdGFsZU1zID09PSB1bmRlZmluZWQpIHtcbiAgICAgIHRocm93IG5ldyBUeXBlRXJyb3IoXCJ1cGRhdGVNcyByZXF1aXJlcyBzdGFsZU1zXCIpO1xuICAgIH1cbiAgICBpZiAob3B0aW9ucy51cGRhdGVNcyA8PSAwIHx8IG9wdGlvbnMudXBkYXRlTXMgPiBvcHRpb25zLnN0YWxlTXMgLyAyKSB7XG4gICAgICB0aHJvdyBuZXcgVHlwZUVycm9yKFwidXBkYXRlTXMgbXVzdCBiZSBwb3NpdGl2ZSBhbmQgbm8gZ3JlYXRlciB0aGFuIGhhbGYgb2Ygc3RhbGVNc1wiKTtcbiAgICB9XG4gIH1cbn1cblxuLyoqIENhbm9uaWNhbCBmaWxlc3lzdGVtLXNhZmUgaWQgZm9yIGEgbG9jayBrZXkuICovXG5mdW5jdGlvbiBsb2NrSWQoa2V5OiB1bmtub3duKTogc3RyaW5nIHtcbiAgY29uc3Qgc3RhYmxlID0gb2JqZWN0XG4gICAgLnRvT25lT3JNYW55KGtleSlcbiAgICAubWFwKChwYXJ0KSA9PiBvYmplY3QudG9TdGFibGVLZXkocGFydCkpXG4gICAgLmpvaW4oXCJcXHUwMDAwXCIpO1xuICAvLyBTaG9ydCBkaWdlc3Qgc28gcGF0aHMgc3RheSB3ZWxsIHVuZGVyIE9TIGxpbWl0czsgY29sbGlzaW9ucyBhcmUgZmluZSDigJQgdGhleVxuICAvLyBvbmx5IG1lcmdlIGNyaXRpY2FsIHNlY3Rpb25zIHRoYXQgYWxyZWFkeSBzaGFyZWQgYSBrZXkgc3RyaW5nLlxuICByZXR1cm4gaGFzaC5mbnZIYXNoKHN0YWJsZSk7XG59XG5cbi8qKlxuICogUmVzb2x2ZSBgZmxvY2soMilgIHRocm91Z2ggQnVuIEZGSSB3aGVuIHBvc3NpYmxlLlxuICpcbiAqIE1lbW9pemVkOiB0aGUgRkZJIGltcG9ydCArIGxpYmMgYGRsb3BlbmAgcnVuIG9uY2UgcGVyIHByb2Nlc3MuIFJldHVybnNcbiAqIGB1bmRlZmluZWRgIG9uIFdpbmRvd3MsIHVuZGVyIHBsYWluIE5vZGUsIG9yIHdoZW4gbGliYyBjYW5ub3QgYmUgbG9hZGVkIOKAlFxuICogY2FsbGVycyBmYWxsIHRocm91Z2ggdG8gdGhlIG5leHQgYmFja2VuZC4gQSBtaXNzIGlzIGNhY2hlZCB0b28sIHNvIGEgcHJvY2Vzc1xuICogdGhhdCBjYW5ub3QgZmxvY2sgbmV2ZXIgcmV0cmllcyB0aGUgbG9hZC5cbiAqL1xuY29uc3QgcmVzb2x2ZUZsb2NrID0gZnVuY3Rpb25Nb2R1bGUubWVtb2l6ZShhc3luYyAoKTogUHJvbWlzZTxGbG9ja0ZuIHwgdW5kZWZpbmVkPiA9PiB7XG4gIGlmIChwcm9jZXNzLnBsYXRmb3JtID09PSBcIndpbjMyXCIpIHJldHVybiB1bmRlZmluZWQ7XG4gIGlmICghcHJvY2Vzcy52ZXJzaW9ucy5idW4pIHJldHVybiB1bmRlZmluZWQ7XG5cbiAgdHJ5IHtcbiAgICAvLyBEeW5hbWljIHNwZWNpZmllciBzbyBgdHNjYCAobm8gYEB0eXBlc2AgZm9yIGBidW46ZmZpYCkgZG9lcyBub3QgcmVzb2x2ZSBpdDtcbiAgICAvLyB0aGUgaW1wb3J0IG9ubHkgc3VjY2VlZHMgdW5kZXIgQnVuIGF0IHJ1bnRpbWUuXG4gICAgY29uc3Qgc3BlY2lmaWVyID0gXCJidW46ZmZpXCI7XG4gICAgY29uc3QgZmZpID0gKGF3YWl0IGltcG9ydChzcGVjaWZpZXIpKSBhcyB1bmtub3duIGFzIEJ1bkZmaU1vZHVsZTtcbiAgICBjb25zdCBsaWJQYXRoID1cbiAgICAgIHByb2Nlc3MucGxhdGZvcm0gPT09IFwiZGFyd2luXCIgPyBcImxpYlN5c3RlbS5CLmR5bGliXCIgOiBgbGliYy4ke2ZmaS5zdWZmaXh9YDtcbiAgICBjb25zdCBsaWIgPSBmZmkuZGxvcGVuKGxpYlBhdGgsIHtcbiAgICAgIGZsb2NrOiB7IGFyZ3M6IFtcImkzMlwiLCBcImkzMlwiXSwgcmV0dXJuczogXCJpMzJcIiB9LFxuICAgIH0pO1xuICAgIHJldHVybiBsaWIuc3ltYm9scy5mbG9jaztcbiAgfSBjYXRjaCAoY2F1c2UpIHtcbiAgICBsb2dnZXIuZGVidWcoXCJmbG9jayBGRkkgdW5hdmFpbGFibGVcIiwgeyBlcnJvcjogZXJyb3IuZXJyb3JNZXNzYWdlKGNhdXNlKSB9KTtcbiAgICByZXR1cm4gdW5kZWZpbmVkO1xuICB9XG59KTtcblxuYXN5bmMgZnVuY3Rpb24gaG9sZEZsb2NrPFQ+KFxuICBsb2NrUGF0aDogc3RyaW5nLFxuICBmbG9jazogRmxvY2tGbixcbiAgZGVhZGxpbmU6IG51bWJlciB8IHVuZGVmaW5lZCxcbiAgZm46ICgpID0+IFQgfCBQcm9taXNlPFQ+LFxuKTogUHJvbWlzZTxUPiB7XG4gIGF3YWl0IGVuc3VyZVBhcmVudERpcihsb2NrUGF0aCk7XG4gIGNvbnN0IGhhbmRsZSA9IGF3YWl0IG9wZW4obG9ja1BhdGgsIFwiYStcIik7XG4gIHRyeSB7XG4gICAgYXdhaXQgd2FpdEZvckZsb2NrKGhhbmRsZS5mZCwgZmxvY2ssIGxvY2tQYXRoLCBkZWFkbGluZSk7XG4gICAgdHJ5IHtcbiAgICAgIHJldHVybiBhd2FpdCBmbigpO1xuICAgIH0gZmluYWxseSB7XG4gICAgICBmbG9jayhoYW5kbGUuZmQsIExPQ0tfVU4pO1xuICAgIH1cbiAgfSBmaW5hbGx5IHtcbiAgICBhd2FpdCBoYW5kbGUuY2xvc2UoKS5jYXRjaCgoKSA9PiB7fSk7XG4gIH1cbn1cblxuYXN5bmMgZnVuY3Rpb24gd2FpdEZvckZsb2NrKFxuICBmZDogbnVtYmVyLFxuICBmbG9jazogRmxvY2tGbixcbiAgbG9ja1BhdGg6IHN0cmluZyxcbiAgZGVhZGxpbmU6IG51bWJlciB8IHVuZGVmaW5lZCxcbik6IFByb21pc2U8dm9pZD4ge1xuICBmb3IgKDs7KSB7XG4gICAgY29uc3QgcmMgPSBmbG9jayhmZCwgTE9DS19FWCB8IExPQ0tfTkIpO1xuICAgIGlmIChyYyA9PT0gMCkgcmV0dXJuO1xuICAgIGFzc2VydEJlZm9yZURlYWRsaW5lKGxvY2tQYXRoLCBkZWFkbGluZSk7XG4gICAgYXdhaXQgYXN5bmMuc2xlZXAoUE9MTF9NUyk7XG4gIH1cbn1cblxuLyoqXG4gKiBBdG9taWMgbG9jay1kaXJlY3RvcnkgY3JlYXRpb24g4oCUIHRoZSBwb3J0YWJsZSAvIFdpbmRvd3MgcGF0aC5cbiAqXG4gKiBgbWtkaXJgIGlzIHRoZSBzYW1lIHByaW1pdGl2ZSB1c2VkIGJ5IGBwcm9wZXItbG9ja2ZpbGVgOiBpdCBpcyBhdG9taWMgYWNyb3NzXG4gKiBzdXBwb3J0ZWQgbG9jYWwgYW5kIG5ldHdvcmsgZmlsZXN5c3RlbXMuIFdoZW4gc3RhbGUgZGV0ZWN0aW9uIGlzIGVuYWJsZWQsXG4gKiB0aGUgaG9sZGVyIHJlZnJlc2hlcyBtdGltZSBzbyBhIGxpdmUgbG9uZy1ydW5uaW5nIGxvY2sgaXMgbmV2ZXIgcmVjbGFpbWVkLlxuICovXG5hc3luYyBmdW5jdGlvbiBob2xkTG9ja0RpcmVjdG9yeTxUPihcbiAgbG9ja1BhdGg6IHN0cmluZyxcbiAgZGVhZGxpbmU6IG51bWJlciB8IHVuZGVmaW5lZCxcbiAgc3RhbGVNczogbnVtYmVyIHwgdW5kZWZpbmVkLFxuICB1cGRhdGVNczogbnVtYmVyIHwgdW5kZWZpbmVkLFxuICBmbjogKCkgPT4gVCB8IFByb21pc2U8VD4sXG4pOiBQcm9taXNlPFQ+IHtcbiAgYXdhaXQgZW5zdXJlUGFyZW50RGlyKGxvY2tQYXRoKTtcbiAgYXdhaXQgYWNxdWlyZUxvY2tEaXJlY3RvcnkobG9ja1BhdGgsIGRlYWRsaW5lLCBzdGFsZU1zKTtcbiAgY29uc3Qgc3RvcEhlYXJ0YmVhdCA9IHN0YXJ0SGVhcnRiZWF0KGxvY2tQYXRoLCBzdGFsZU1zLCB1cGRhdGVNcyk7XG4gIHRyeSB7XG4gICAgcmV0dXJuIGF3YWl0IGZuKCk7XG4gIH0gZmluYWxseSB7XG4gICAgc3RvcEhlYXJ0YmVhdCgpO1xuICAgIGF3YWl0IHJtKGxvY2tQYXRoLCB7IHJlY3Vyc2l2ZTogdHJ1ZSwgZm9yY2U6IHRydWUgfSkuY2F0Y2goKCkgPT4ge30pO1xuICB9XG59XG5cbmFzeW5jIGZ1bmN0aW9uIGFjcXVpcmVMb2NrRGlyZWN0b3J5KFxuICBsb2NrUGF0aDogc3RyaW5nLFxuICBkZWFkbGluZTogbnVtYmVyIHwgdW5kZWZpbmVkLFxuICBzdGFsZU1zOiBudW1iZXIgfCB1bmRlZmluZWQsXG4pOiBQcm9taXNlPHZvaWQ+IHtcbiAgZm9yICg7Oykge1xuICAgIHRyeSB7XG4gICAgICBhd2FpdCBta2Rpcihsb2NrUGF0aCk7XG4gICAgICByZXR1cm47XG4gICAgfSBjYXRjaCAoY2F1c2UpIHtcbiAgICAgIGNvbnN0IGVyciA9IGNhdXNlIGFzIE5vZGVKUy5FcnJub0V4Y2VwdGlvbjtcbiAgICAgIGlmIChlcnIuY29kZSAhPT0gXCJFRVhJU1RcIikgdGhyb3cgZXJyb3IudG9FcnJvcihjYXVzZSk7XG4gICAgICBpZiAoc3RhbGVNcyAhPT0gdW5kZWZpbmVkKSBhd2FpdCBtYXliZVJlY2xhaW1TdGFsZShsb2NrUGF0aCwgc3RhbGVNcyk7XG4gICAgICBhc3NlcnRCZWZvcmVEZWFkbGluZShsb2NrUGF0aCwgZGVhZGxpbmUpO1xuICAgICAgYXdhaXQgYXN5bmMuc2xlZXAoUE9MTF9NUyk7XG4gICAgfVxuICB9XG59XG5cbmFzeW5jIGZ1bmN0aW9uIG1heWJlUmVjbGFpbVN0YWxlKGxvY2tQYXRoOiBzdHJpbmcsIHN0YWxlTXM6IG51bWJlcik6IFByb21pc2U8dm9pZD4ge1xuICB0cnkge1xuICAgIGNvbnN0IHsgbXRpbWVNcyB9ID0gYXdhaXQgc3RhdChsb2NrUGF0aCk7XG4gICAgY29uc3QgYWdlID0gRGF0ZS5ub3coKSAtIG10aW1lTXM7XG4gICAgaWYgKGFnZSA8IHN0YWxlTXMpIHJldHVybjtcbiAgICBsb2dnZXIuZGVidWcoXCJyZWNsYWltaW5nIHN0YWxlIGxvY2sgZGlyZWN0b3J5XCIsIHsgcGF0aDogbG9ja1BhdGgsIGFnZU1zOiBhZ2UgfSk7XG4gICAgYXdhaXQgcm0obG9ja1BhdGgsIHsgcmVjdXJzaXZlOiB0cnVlLCBmb3JjZTogdHJ1ZSB9KTtcbiAgfSBjYXRjaCAoY2F1c2UpIHtcbiAgICBjb25zdCBlcnIgPSBjYXVzZSBhcyBOb2RlSlMuRXJybm9FeGNlcHRpb247XG4gICAgaWYgKGVyci5jb2RlICE9PSBcIkVOT0VOVFwiKSB0aHJvdyBlcnJvci50b0Vycm9yKGNhdXNlKTtcbiAgfVxufVxuXG5mdW5jdGlvbiBzdGFydEhlYXJ0YmVhdChcbiAgbG9ja1BhdGg6IHN0cmluZyxcbiAgc3RhbGVNczogbnVtYmVyIHwgdW5kZWZpbmVkLFxuICB1cGRhdGVNczogbnVtYmVyIHwgdW5kZWZpbmVkLFxuKTogKCkgPT4gdm9pZCB7XG4gIGlmIChzdGFsZU1zID09PSB1bmRlZmluZWQpIHJldHVybiAoKSA9PiB7fTtcbiAgY29uc3QgaW50ZXJ2YWxNcyA9IHVwZGF0ZU1zID8/IE1hdGgubWF4KDEsIE1hdGguZmxvb3Ioc3RhbGVNcyAvIDIpKTtcbiAgY29uc3QgdGltZXIgPSBzZXRJbnRlcnZhbCgoKSA9PiB7XG4gICAgY29uc3Qgbm93ID0gbmV3IERhdGUoKTtcbiAgICB2b2lkIHV0aW1lcyhsb2NrUGF0aCwgbm93LCBub3cpLmNhdGNoKChjYXVzZSkgPT4ge1xuICAgICAgbG9nZ2VyLndhcm4oXCJmaWxlIGxvY2sgaGVhcnRiZWF0IGZhaWxlZFwiLCB7XG4gICAgICAgIHBhdGg6IGxvY2tQYXRoLFxuICAgICAgICBlcnJvcjogZXJyb3IuZXJyb3JNZXNzYWdlKGNhdXNlKSxcbiAgICAgIH0pO1xuICAgIH0pO1xuICB9LCBpbnRlcnZhbE1zKTtcbiAgdGltZXIudW5yZWYoKTtcbiAgcmV0dXJuICgpID0+IGNsZWFySW50ZXJ2YWwodGltZXIpO1xufVxuXG5mdW5jdGlvbiBhc3NlcnRCZWZvcmVEZWFkbGluZShsb2NrUGF0aDogc3RyaW5nLCBkZWFkbGluZTogbnVtYmVyIHwgdW5kZWZpbmVkKTogdm9pZCB7XG4gIGlmIChkZWFkbGluZSAhPT0gdW5kZWZpbmVkICYmIERhdGUubm93KCkgPj0gZGVhZGxpbmUpIHtcbiAgICB0aHJvdyBuZXcgRXJyb3IoYFRpbWVkIG91dCB3YWl0aW5nIGZvciBmaWxlIGxvY2s6ICR7bG9ja1BhdGh9YCk7XG4gIH1cbn1cblxuYXN5bmMgZnVuY3Rpb24gZW5zdXJlUGFyZW50RGlyKGxvY2tQYXRoOiBzdHJpbmcpOiBQcm9taXNlPHZvaWQ+IHtcbiAgYXdhaXQgbWtkaXIoZGlybmFtZShsb2NrUGF0aCksIHsgcmVjdXJzaXZlOiB0cnVlIH0pO1xufVxuIl19

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/bin.ts","../src/brand.ts","../src/exec.ts","../src/file.ts","../src/process-lock.ts","../src/project.ts","../index.ts"],"version":"5.9.3"}
+{"root":["../src/bin.ts","../src/brand.ts","../src/exec.ts","../src/file-lock.ts","../src/file.ts","../src/process-lock.ts","../src/project.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -23,7 +23,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@dbx-tools/shared-core": "0.6.68",
+    "@dbx-tools/shared-core": "0.6.70",
     "extract-zip": "^2.0.1",
     "tar": "^7.5.22",
     "yaml": "^2.9.0"
@@ -42,7 +42,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.6.68",
+  "version": "0.6.70",
   "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {

package/src/file-lock.ts

@@ -0,0 +1,312 @@
+/**
+ * Cascading cross-process mutual exclusion via a lockfile.
+ *
+ * Serializes concurrent *processes* (two `bun run demo` shells, a CLI beside a
+ * server) on the same key. For in-process / worker-thread exclusion use
+ * {@link withProcessLock} from `./process-lock.ts` instead.
+ *
+ * Backends, in order:
+ *
+ * 1. **flock** — `flock(2)` via Bun FFI on Unix when `bun:ffi` can load libc.
+ *    Not available on Windows, and not available under plain Node (no FFI).
+ *    Kernel releases the lock when the fd closes (including process death).
+ * 2. **file** — atomic lock-directory creation. This is the strategy used by
+ *    `proper-lockfile`: `mkdir` is atomic on Windows, Unix, and network file
+ *    systems where `open(..., "wx")` may not be reliable. Optional stale
+ *    detection uses the directory mtime plus a heartbeat.
+ *
+ * The first backend that can be *initialized* is used for the whole call. A busy
+ * lock waits; an unavailable backend falls through to the next.
+ *
+ * @module
+ */
+
+import { mkdir, open, rm, stat, utimes } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { async, error, functionModule, hash, log, object } from "@dbx-tools/shared-core";
+
+const logger = log.logger("core:file-lock");
+
+/** Backends {@link withFileLock} can attempt, in cascade order. */
+export type FileLockBackend = "flock" | "file";
+
+const DEFAULT_BACKENDS: readonly FileLockBackend[] = ["flock", "file"];
+
+/** Poll interval while waiting for a contended OS lock. */
+const POLL_MS = 50;
+
+/** `flock(2)` operation bits (Linux / macOS / BSD). */
+const LOCK_EX = 2;
+const LOCK_NB = 4;
+const LOCK_UN = 8;
+
+/** Result metadata when a caller wants to know which backend ran. */
+export interface FileLockAcquisition {
+  backend: FileLockBackend;
+}
+
+export interface FileLockOptions {
+  /**
+   * Directory for lockfiles. Defaults to `$TMPDIR/dbx-tools-locks`.
+   */
+  dir?: string;
+  /** Override the cascade. Defaults to `flock` → `file`. */
+  backends?: readonly FileLockBackend[];
+  /**
+   * Stop waiting and throw after this many milliseconds. Omit to poll forever.
+   */
+  timeoutMs?: number;
+  /**
+   * Age after which an unrefreshed lock directory may be removed. Omit to
+   * disable stale detection. Only used by the `file` backend.
+   */
+  staleMs?: number;
+  /**
+   * Interval for refreshing the lock directory mtime when `staleMs` is set.
+   * Defaults to half of `staleMs`.
+   */
+  updateMs?: number;
+  /** Invoked once the backend for this call has been chosen. */
+  onAcquire?: (acquisition: FileLockAcquisition) => void;
+}
+
+type FlockFn = (fd: number, operation: number) => number;
+
+interface BunFfiModule {
+  dlopen: (
+    path: string,
+    symbols: Record<string, { args: string[]; returns: string }>,
+  ) => { symbols: { flock: FlockFn } };
+  suffix: string;
+}
+
+/**
+ * Run `fn` while holding a cross-process lock named by `key`.
+ *
+ * `key` is canonicalized with `object.toStableKey`, the same identity rule as
+ * process and Postgres advisory locks.
+ *
+ * @example
+ * await withFileLock(["cache", "appkit"], async () => {
+ *   await migrate();
+ * });
+ */
+export async function withFileLock<T>(
+  key: unknown,
+  fn: () => T | Promise<T>,
+  options: FileLockOptions = {},
+): Promise<T> {
+  validateOptions(options);
+  const id = lockId(key);
+  const backends = options.backends ?? DEFAULT_BACKENDS;
+  const dir = options.dir ?? join(tmpdir(), "dbx-tools-locks");
+  const deadline = options.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs;
+
+  for (const backend of backends) {
+    switch (backend) {
+      case "flock": {
+        const lockPath = join(dir, `${id}.flock`);
+        const flock = await resolveFlock();
+        if (!flock) {
+          logger.debug("lock backend unavailable", { backend, key: id });
+          continue;
+        }
+        logger.debug("acquiring lock", { backend, key: id, path: lockPath });
+        options.onAcquire?.({ backend });
+        return holdFlock(lockPath, flock, deadline, fn);
+      }
+      case "file": {
+        const lockPath = join(dir, `${id}.lock`);
+        logger.debug("acquiring lock", { backend, key: id, path: lockPath });
+        options.onAcquire?.({ backend });
+        return holdLockDirectory(lockPath, deadline, options.staleMs, options.updateMs, fn);
+      }
+      default: {
+        const _exhaustive: never = backend;
+        throw new Error(`unknown file-lock backend: ${String(_exhaustive)}`);
+      }
+    }
+  }
+
+  throw new Error("withFileLock: no lock backend available");
+}
+
+function validateOptions(options: FileLockOptions): void {
+  if (options.timeoutMs !== undefined && options.timeoutMs < 0) {
+    throw new TypeError("timeoutMs must be non-negative");
+  }
+  if (options.staleMs !== undefined && options.staleMs <= 0) {
+    throw new TypeError("staleMs must be positive");
+  }
+  if (options.updateMs !== undefined) {
+    if (options.staleMs === undefined) {
+      throw new TypeError("updateMs requires staleMs");
+    }
+    if (options.updateMs <= 0 || options.updateMs > options.staleMs / 2) {
+      throw new TypeError("updateMs must be positive and no greater than half of staleMs");
+    }
+  }
+}
+
+/** Canonical filesystem-safe id for a lock key. */
+function lockId(key: unknown): string {
+  const stable = object
+    .toOneOrMany(key)
+    .map((part) => object.toStableKey(part))
+    .join("\u0000");
+  // Short digest so paths stay well under OS limits; collisions are fine — they
+  // only merge critical sections that already shared a key string.
+  return hash.fnvHash(stable);
+}
+
+/**
+ * Resolve `flock(2)` through Bun FFI when possible.
+ *
+ * Memoized: the FFI import + libc `dlopen` run once per process. Returns
+ * `undefined` on Windows, under plain Node, or when libc cannot be loaded —
+ * callers fall through to the next backend. A miss is cached too, so a process
+ * that cannot flock never retries the load.
+ */
+const resolveFlock = functionModule.memoize(async (): Promise<FlockFn | undefined> => {
+  if (process.platform === "win32") return undefined;
+  if (!process.versions.bun) return undefined;
+
+  try {
+    // Dynamic specifier so `tsc` (no `@types` for `bun:ffi`) does not resolve it;
+    // the import only succeeds under Bun at runtime.
+    const specifier = "bun:ffi";
+    const ffi = (await import(specifier)) as unknown as BunFfiModule;
+    const libPath =
+      process.platform === "darwin" ? "libSystem.B.dylib" : `libc.${ffi.suffix}`;
+    const lib = ffi.dlopen(libPath, {
+      flock: { args: ["i32", "i32"], returns: "i32" },
+    });
+    return lib.symbols.flock;
+  } catch (cause) {
+    logger.debug("flock FFI unavailable", { error: error.errorMessage(cause) });
+    return undefined;
+  }
+});
+
+async function holdFlock<T>(
+  lockPath: string,
+  flock: FlockFn,
+  deadline: number | undefined,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  await ensureParentDir(lockPath);
+  const handle = await open(lockPath, "a+");
+  try {
+    await waitForFlock(handle.fd, flock, lockPath, deadline);
+    try {
+      return await fn();
+    } finally {
+      flock(handle.fd, LOCK_UN);
+    }
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+async function waitForFlock(
+  fd: number,
+  flock: FlockFn,
+  lockPath: string,
+  deadline: number | undefined,
+): Promise<void> {
+  for (;;) {
+    const rc = flock(fd, LOCK_EX | LOCK_NB);
+    if (rc === 0) return;
+    assertBeforeDeadline(lockPath, deadline);
+    await async.sleep(POLL_MS);
+  }
+}
+
+/**
+ * Atomic lock-directory creation — the portable / Windows path.
+ *
+ * `mkdir` is the same primitive used by `proper-lockfile`: it is atomic across
+ * supported local and network filesystems. When stale detection is enabled,
+ * the holder refreshes mtime so a live long-running lock is never reclaimed.
+ */
+async function holdLockDirectory<T>(
+  lockPath: string,
+  deadline: number | undefined,
+  staleMs: number | undefined,
+  updateMs: number | undefined,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  await ensureParentDir(lockPath);
+  await acquireLockDirectory(lockPath, deadline, staleMs);
+  const stopHeartbeat = startHeartbeat(lockPath, staleMs, updateMs);
+  try {
+    return await fn();
+  } finally {
+    stopHeartbeat();
+    await rm(lockPath, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function acquireLockDirectory(
+  lockPath: string,
+  deadline: number | undefined,
+  staleMs: number | undefined,
+): Promise<void> {
+  for (;;) {
+    try {
+      await mkdir(lockPath);
+      return;
+    } catch (cause) {
+      const err = cause as NodeJS.ErrnoException;
+      if (err.code !== "EEXIST") throw error.toError(cause);
+      if (staleMs !== undefined) await maybeReclaimStale(lockPath, staleMs);
+      assertBeforeDeadline(lockPath, deadline);
+      await async.sleep(POLL_MS);
+    }
+  }
+}
+
+async function maybeReclaimStale(lockPath: string, staleMs: number): Promise<void> {
+  try {
+    const { mtimeMs } = await stat(lockPath);
+    const age = Date.now() - mtimeMs;
+    if (age < staleMs) return;
+    logger.debug("reclaiming stale lock directory", { path: lockPath, ageMs: age });
+    await rm(lockPath, { recursive: true, force: true });
+  } catch (cause) {
+    const err = cause as NodeJS.ErrnoException;
+    if (err.code !== "ENOENT") throw error.toError(cause);
+  }
+}
+
+function startHeartbeat(
+  lockPath: string,
+  staleMs: number | undefined,
+  updateMs: number | undefined,
+): () => void {
+  if (staleMs === undefined) return () => {};
+  const intervalMs = updateMs ?? Math.max(1, Math.floor(staleMs / 2));
+  const timer = setInterval(() => {
+    const now = new Date();
+    void utimes(lockPath, now, now).catch((cause) => {
+      logger.warn("file lock heartbeat failed", {
+        path: lockPath,
+        error: error.errorMessage(cause),
+      });
+    });
+  }, intervalMs);
+  timer.unref();
+  return () => clearInterval(timer);
+}
+
+function assertBeforeDeadline(lockPath: string, deadline: number | undefined): void {
+  if (deadline !== undefined && Date.now() >= deadline) {
+    throw new Error(`Timed out waiting for file lock: ${lockPath}`);
+  }
+}
+
+async function ensureParentDir(lockPath: string): Promise<void> {
+  await mkdir(dirname(lockPath), { recursive: true });
+}