@openclaw/fs-safe 0.4.7 → 0.5.1

package/dist/sidecar-lock.js

@@ -2,7 +2,11 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { sameFileIdentity } from "./file-identity.js";
-import { readSidecarLockSnapshot, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotMatches, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { readSidecarLockSnapshot, relativeSidecarLockPath, releaseSidecarReclaimGuard, removeSidecarLockIfUnchanged, removeStaleSidecarLockIfAllowed, serializeSidecarLockPayload, sidecarLockSnapshotMatches, sidecarLockSnapshotStillPresent, sidecarReclaimGuardExists, tryAcquireSidecarReclaimGuard, } from "./sidecar-lock-reclaim.js";
+import { FsSafeError } from "./errors.js";
+import { createNativeExclusiveFile } from "./native-operations.js";
+import { createHeldSidecarLockHandle } from "./sidecar-lock-handle.js";
+import { computeSidecarLockDelayMs, defaultSidecarLockShouldReclaim, } from "./sidecar-lock-policy.js";
 const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
 function getGlobalManagers() {
     const globalWithState = globalThis;
@@ -28,6 +32,9 @@ function resolveManagerState(key) {
         // Backfill state created by fs-safe versions that predate reclaim guards.
         state.reclaimCleanupRegistered ??= false;
         state.reclaimGuards ??= new Set();
+        for (const held of state.held.values()) {
+            held.refCount ??= 1;
+        }
     }
     return state;
 }
@@ -83,28 +90,6 @@ async function resolveNormalizedTargetPath(targetPath) {
         return resolved;
     }
 }
-function computeDelayMs(retry, attempt) {
-    const minTimeout = retry.minTimeout ?? 50;
-    const maxTimeout = retry.maxTimeout ?? 1000;
-    const factor = retry.factor ?? 1;
-    const base = Math.min(maxTimeout, Math.max(minTimeout, minTimeout * factor ** attempt));
-    const jitter = retry.randomize ? 1 + Math.random() : 1;
-    return Math.min(maxTimeout, Math.round(base * jitter));
-}
-async function defaultShouldReclaim(params) {
-    const createdAt = typeof params.payload?.createdAt === "string" ? params.payload.createdAt : "";
-    const createdAtMs = Date.parse(createdAt);
-    if (Number.isFinite(createdAtMs) && params.nowMs - createdAtMs > params.staleMs) {
-        return true;
-    }
-    try {
-        const stat = await fs.stat(params.lockPath);
-        return params.nowMs - stat.mtimeMs > params.staleMs;
-    }
-    catch {
-        return true;
-    }
-}
 function releaseAllReclaimGuardsSync(state) {
     for (const reclaimGuardPath of state.reclaimGuards) {
         try {
@@ -120,7 +105,7 @@ function releaseAllLocksSync(state) {
     for (const [normalizedTargetPath, held] of state.held) {
         void held.handle.close().catch(() => undefined);
         try {
-            if (snapshotMatchesSync(held.lockPath, held.snapshot)) {
+            if (!held.lockRoot && snapshotMatchesSync(held.lockPath, held.snapshot)) {
                 fsSync.rmSync(held.lockPath, { force: true });
             }
         }
@@ -131,17 +116,17 @@ function releaseAllLocksSync(state) {
     }
     releaseAllReclaimGuardsSync(state);
 }
-async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
+async function releaseHeldLock(state, normalizedTargetPath, held, options = {}) {
     const current = state.held.get(normalizedTargetPath);
     if (current !== held) {
         return false;
     }
-    if (opts.force) {
-        held.count = 0;
+    if (options.force) {
+        held.refCount = 0;
     }
     else {
-        held.count -= 1;
-        if (held.count > 0) {
+        held.refCount -= 1;
+        if (held.refCount > 0) {
             return false;
         }
     }
@@ -150,9 +135,16 @@ async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
         return true;
     }
     state.held.delete(normalizedTargetPath);
+    if (held.compromiseTimer) {
+        clearInterval(held.compromiseTimer);
+        held.compromiseTimer = undefined;
+    }
     held.releasePromise = (async () => {
         await held.handle.close().catch(() => undefined);
-        await removeSidecarLockIfUnchanged(held.lockPath, held.snapshot);
+        await removeSidecarLockIfUnchanged(held.lockPath, held.snapshot, {
+            lockRoot: held.lockRoot,
+            parsePayload: held.parsePayload,
+        });
     })();
     try {
         await held.releasePromise;
@@ -162,6 +154,13 @@ async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
         held.releasePromise = undefined;
     }
 }
+function handleForHeldLock(state, normalizedTargetPath, held) {
+    return createHeldSidecarLockHandle({
+        normalizedTargetPath,
+        held,
+        release: async () => await releaseHeldLock(state, normalizedTargetPath, held),
+    });
+}
 export function createSidecarLockManager(key) {
     const state = resolveManagerState(key);
     function ensureExitCleanupRegistered() {
@@ -181,15 +180,12 @@ export function createSidecarLockManager(key) {
         const normalizedTargetPath = await resolveNormalizedTargetPath(options.targetPath);
         const lockPath = options.lockPath ?? `${normalizedTargetPath}.lock`;
         const held = state.held.get(normalizedTargetPath);
-        if (held && options.allowReentrant) {
-            held.count += 1;
-            const release = () => releaseHeldLock(state, normalizedTargetPath, held).then(() => undefined);
-            return {
-                lockPath,
-                normalizedTargetPath,
-                release,
-                [Symbol.asyncDispose]: release,
-            };
+        if (held &&
+            options.reentrantOwner !== undefined &&
+            held.reentrantOwner !== undefined &&
+            options.reentrantOwner === held.reentrantOwner) {
+            held.refCount += 1;
+            return handleForHeldLock(state, normalizedTargetPath, held);
         }
         const startedAt = Date.now();
         const retry = options.retry ?? {};
@@ -212,7 +208,7 @@ export function createSidecarLockManager(key) {
             const remaining = options.timeoutMs === undefined || options.timeoutMs === Number.POSITIVE_INFINITY
                 ? Number.POSITIVE_INFINITY
                 : Math.max(0, options.timeoutMs - elapsed);
-            const delay = Math.min(computeDelayMs(retry, attempt), remaining);
+            const delay = Math.min(computeSidecarLockDelayMs(retry, attempt), remaining);
             attempt += 1;
             await new Promise((resolve) => setTimeout(resolve, delay));
         };
@@ -224,18 +220,36 @@ export function createSidecarLockManager(key) {
                 }
                 let handle = null;
                 try {
-                    handle = await fs.open(lockPath, "wx");
                     const payload = await options.payload();
                     const { raw, ownershipToken } = serializeSidecarLockPayload(payload);
-                    await handle.writeFile(raw, "utf8");
+                    if (options.lockRoot) {
+                        const relativeLockPath = relativeSidecarLockPath(options.lockRoot, lockPath);
+                        try {
+                            await options.lockRoot.create(relativeLockPath, raw, { mkdir: true, mode: 0o600 });
+                        }
+                        catch (error) {
+                            if (error instanceof FsSafeError && error.code === "already-exists") {
+                                throw Object.assign(new Error("sidecar lock exists"), { code: "EEXIST" });
+                            }
+                            throw error;
+                        }
+                        handle = (await options.lockRoot.open(relativeLockPath)).handle;
+                    }
+                    else {
+                        handle = (await createNativeExclusiveFile(lockPath, 0o600)) ?? await fs.open(lockPath, "wx");
+                        await handle.writeFile(raw, "utf8");
+                    }
                     const snapshot = { raw, payload, stat: await handle.stat(), ownershipToken };
                     const createdHeld = {
-                        count: 1,
+                        refCount: 1,
+                        reentrantOwner: options.reentrantOwner,
                         handle,
                         lockPath,
                         snapshot,
                         acquiredAt: Date.now(),
                         metadata: options.metadata ?? {},
+                        lockRoot: options.lockRoot,
+                        parsePayload: options.parsePayload,
                     };
                     state.held.set(normalizedTargetPath, createdHeld);
                     if (ownsReclaimGuard) {
@@ -248,13 +262,21 @@ export function createSidecarLockManager(key) {
                             throw err;
                         }
                     }
-                    const release = () => releaseHeldLock(state, normalizedTargetPath, createdHeld).then(() => undefined);
-                    return {
-                        lockPath,
-                        normalizedTargetPath,
-                        release,
-                        [Symbol.asyncDispose]: release,
-                    };
+                    const returnedHandle = handleForHeldLock(state, normalizedTargetPath, createdHeld);
+                    const interval = options.compromiseCheckIntervalMs;
+                    if (options.onCompromised && interval !== undefined && interval > 0) {
+                        createdHeld.compromiseTimer = setInterval(() => {
+                            void returnedHandle.verifyStillHeld().then((stillHeld) => {
+                                if (!stillHeld && createdHeld.compromiseTimer) {
+                                    clearInterval(createdHeld.compromiseTimer);
+                                    createdHeld.compromiseTimer = undefined;
+                                    options.onCompromised?.({ lockPath, normalizedTargetPath });
+                                }
+                            });
+                        }, interval);
+                        createdHeld.compromiseTimer.unref();
+                    }
+                    return returnedHandle;
                 }
                 catch (err) {
                     if (handle) {
@@ -271,11 +293,16 @@ export function createSidecarLockManager(key) {
                         }
                         // If payload serialization/write fails, the file may be empty or
                         // partial JSON, so remove while our exclusive handle is still open.
-                        await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                        if (!options.lockRoot) {
+                            await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                        }
                         await handle.close().catch(() => undefined);
                         // Windows can refuse removing an open file; retry after close but
                         // only if the path still points at the file identity we created.
-                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot);
+                        await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        });
                     }
                     if (err.code !== "EEXIST") {
                         throw err;
@@ -286,11 +313,18 @@ export function createSidecarLockManager(key) {
                         continue;
                     }
                     const nowMs = Date.now();
-                    const snapshot = await readSidecarLockSnapshot(lockPath);
+                    const snapshot = await readSidecarLockSnapshot(lockPath, {
+                        lockRoot: options.lockRoot,
+                        parsePayload: options.parsePayload,
+                    });
                     if (!snapshot) {
                         continue;
                     }
-                    const shouldReclaim = options.shouldReclaim ?? defaultShouldReclaim;
+                    if (state.held.has(normalizedTargetPath)) {
+                        await waitForRetry();
+                        continue;
+                    }
+                    const shouldReclaim = options.shouldReclaim ?? defaultSidecarLockShouldReclaim;
                     if (await shouldReclaim({
                         lockPath,
                         normalizedTargetPath,
@@ -299,7 +333,10 @@ export function createSidecarLockManager(key) {
                         nowMs,
                         heldByThisProcess: state.held.has(normalizedTargetPath),
                     })) {
-                        if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot))) {
+                        if (!(await sidecarLockSnapshotStillPresent(lockPath, snapshot, {
+                            lockRoot: options.lockRoot,
+                            parsePayload: options.parsePayload,
+                        }))) {
                             continue;
                         }
                         const staleRecovery = options.staleRecovery ?? "fail-closed";
@@ -314,6 +351,8 @@ export function createSidecarLockManager(key) {
                                 normalizedTargetPath,
                                 snapshot,
                                 shouldRemoveStaleLock: options.shouldRemoveStaleLock,
+                                lockRoot: options.lockRoot,
+                                parsePayload: options.parsePayload,
                             });
                             if (removal === "removed" || removal === "changed") {
                                 continue;

package/dist/temp-cleanup.d.ts

@@ -1,6 +1,12 @@
+import { type FileIdentityStat } from "./file-identity.js";
+export type TempPathIdentityReceipt = FileIdentityStat;
+export type TempPathRegistration = (() => void) & {
+    setIdentity(identity: FileIdentityStat): void;
+};
 export declare function registerTempPathForExit(tempPath: string, options?: {
     recursive?: boolean;
-}): () => void;
+    identity?: FileIdentityStat;
+}): TempPathRegistration;
 export declare function __cleanupRegisteredTempPathsForTest(): void;
 export declare function __cleanupRegisteredTempPathForTest(tempPath: string): void;
 //# sourceMappingURL=temp-cleanup.d.ts.map

package/dist/temp-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-cleanup.d.ts","sourceRoot":"","sources":["../src/temp-cleanup.ts"],"names":[],"mappings":"AAqBA,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,MAAM,IAAI,CAYZ;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAUzE"}
+{"version":3,"file":"temp-cleanup.d.ts","sourceRoot":"","sources":["../src/temp-cleanup.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC;AAEvD,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG;IAChD,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/C,CAAC;AAmCF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAAE,GAC7D,oBAAoB,CAyBtB;AAED,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAYzE"}

package/dist/temp-cleanup.js

@@ -1,10 +1,24 @@
 import fsSync from "node:fs";
+import { sameFileIdentity } from "./file-identity.js";
 const tempCleanupEntries = new Map();
 let cleanupRegistered = false;
+function pathStillMatchesReceipt(entry) {
+    if (!entry.identity) {
+        return false;
+    }
+    try {
+        return sameFileIdentity(fsSync.lstatSync(entry.path), entry.identity);
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
 function cleanupRegisteredTempPathsSync() {
     for (const entry of tempCleanupEntries.values()) {
         try {
-            fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+            if (pathStillMatchesReceipt(entry)) {
+                fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+            }
         }
         catch {
             // Process-exit cleanup is best-effort.
@@ -17,13 +31,27 @@ export function registerTempPathForExit(tempPath, options) {
         cleanupRegistered = true;
         process.once("exit", cleanupRegisteredTempPathsSync);
     }
-    tempCleanupEntries.set(tempPath, {
+    const entry = {
         path: tempPath,
         recursive: options?.recursive === true,
-    });
-    return () => {
+        identity: options?.identity,
+    };
+    if (!entry.identity) {
+        try {
+            entry.identity = fsSync.lstatSync(tempPath);
+        }
+        catch {
+            // Callers that register before creation set the identity after opening.
+        }
+    }
+    tempCleanupEntries.set(tempPath, entry);
+    const unregister = (() => {
         tempCleanupEntries.delete(tempPath);
+    });
+    unregister.setIdentity = (identity) => {
+        entry.identity = identity;
     };
+    return unregister;
 }
 export function __cleanupRegisteredTempPathsForTest() {
     cleanupRegisteredTempPathsSync();
@@ -34,7 +62,9 @@ export function __cleanupRegisteredTempPathForTest(tempPath) {
         return;
     }
     try {
-        fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+        if (pathStillMatchesReceipt(entry)) {
+            fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+        }
     }
     finally {
         tempCleanupEntries.delete(tempPath);

package/dist/temp-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAiBF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyBD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AA0EF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAaT;AAyBD,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqBpB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE;IACN,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,EACD,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/temp-target.js

@@ -4,8 +4,56 @@ import path from "node:path";
 import { assertSafePathSegment, sanitizeSafePathSegment } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
+const HYPHEN_CHAR_CODE = 0x2d;
+const DOT_CHAR_CODE = 0x2e;
+const NUMBER_ZERO_CHAR_CODE = 0x30;
+const NUMBER_NINE_CHAR_CODE = 0x39;
+const UPPERCASE_A_CHAR_CODE = 0x41;
+const UPPERCASE_Z_CHAR_CODE = 0x5a;
+const UNDERSCORE_CHAR_CODE = 0x5f;
+const LOWERCASE_A_CHAR_CODE = 0x61;
+const LOWERCASE_Z_CHAR_CODE = 0x7a;
+function trimHyphenEdges(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charCodeAt(start) === HYPHEN_CHAR_CODE) {
+        start += 1;
+    }
+    while (end > start && value.charCodeAt(end - 1) === HYPHEN_CHAR_CODE) {
+        end -= 1;
+    }
+    return start === 0 && end === value.length ? value : value.slice(start, end);
+}
+function isExtensionCharCode(charCode) {
+    return ((charCode >= NUMBER_ZERO_CHAR_CODE && charCode <= NUMBER_NINE_CHAR_CODE) ||
+        (charCode >= UPPERCASE_A_CHAR_CODE && charCode <= UPPERCASE_Z_CHAR_CODE) ||
+        (charCode >= LOWERCASE_A_CHAR_CODE && charCode <= LOWERCASE_Z_CHAR_CODE) ||
+        charCode === DOT_CHAR_CODE ||
+        charCode === UNDERSCORE_CHAR_CODE ||
+        charCode === HYPHEN_CHAR_CODE);
+}
+function trailingExtensionChars(value) {
+    let start = value.length;
+    while (start > 0 && isExtensionCharCode(value.charCodeAt(start - 1))) {
+        start -= 1;
+    }
+    return start === value.length ? "" : value.slice(start);
+}
+function trimLeadingExtensionPunctuation(value) {
+    let start = 0;
+    while (start < value.length) {
+        const charCode = value.charCodeAt(start);
+        if (charCode !== DOT_CHAR_CODE &&
+            charCode !== UNDERSCORE_CHAR_CODE &&
+            charCode !== HYPHEN_CHAR_CODE) {
+            break;
+        }
+        start += 1;
+    }
+    return start === 0 ? value : value.slice(start);
+}
 function sanitizePrefix(prefix) {
-    const normalized = prefix.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    const normalized = trimHyphenEdges(prefix.replace(/[^a-zA-Z0-9_-]+/g, "-"));
     return normalized || "tmp";
 }
 function sanitizeExtension(extension) {
@@ -13,8 +61,8 @@ function sanitizeExtension(extension) {
         return "";
     }
     const normalized = extension.startsWith(".") ? extension : `.${extension}`;
-    const suffix = normalized.match(/[a-zA-Z0-9._-]+$/)?.[0] ?? "";
-    const token = suffix.replace(/^[._-]+/, "");
+    const suffix = trailingExtensionChars(normalized);
+    const token = trimLeadingExtensionPunctuation(suffix);
     return token ? `.${token}` : "";
 }
 export function sanitizeTempFileName(fileName) {

package/dist/temp.d.ts

@@ -1,3 +1,4 @@
-export { tempWorkspace, type TempWorkspace, type TempWorkspaceOptions, tempWorkspaceSync, type TempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
+export { tempWorkspace, type TempWorkspace, type TempWorkspaceOptions, type TempWorkspaceCleanupResult, tempWorkspaceSync, type TempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
+export type { TempPathIdentityReceipt } from "./temp-cleanup.js";
 export { resolveSecureTempRoot, type ResolveSecureTempRootOptions } from "./secure-temp-dir.js";
 //# sourceMappingURL=temp.d.ts.map

package/dist/temp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp.d.ts","sourceRoot":"","sources":["../src/temp.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"temp.d.ts","sourceRoot":"","sources":["../src/temp.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/test-hooks.d.ts

@@ -1,4 +1,5 @@
 import type { FileHandle } from "node:fs/promises";
+import type { FileIdentityStat } from "./file-identity.js";
 export type FsSafeTestHooks = {
     afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
     beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
@@ -10,6 +11,8 @@ export type FsSafeTestHooks = {
     afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
     beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
+    afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
+    beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
 };
 export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;

package/dist/test-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClE,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}
+{"version":3,"file":"test-hooks.d.ts","sourceRoot":"","sources":["../src/test-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG;IAC5B,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC/D,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,2BAA2B,CAAC,EAAE,CAC5B,SAAS,EAAE,OAAO,GAAG,OAAO,EAC5B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxE,+BAA+B,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,0BAA0B,CAAC,EAAE,CAC3B,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,EACtC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8BAA8B,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9E,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE,yBAAyB,CAAC,EAAE,CAC1B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,0BAA0B,CAAC,EAAE,CAC3B,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,kBAAkB,EAC1D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}

package/dist/windows-permissions-native.d.ts

@@ -0,0 +1,9 @@
+import type { PermissionCheck, SafeStatResult } from "./permissions.js";
+export declare function inspectWindowsPermissionsNative(params: {
+    targetPath: string;
+    stat: SafeStatResult;
+    effectiveIsDir: boolean;
+    effectiveMode: number | null;
+    bits: number | null;
+}): PermissionCheck | undefined;
+//# sourceMappingURL=windows-permissions-native.d.ts.map

package/dist/windows-permissions-native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-permissions-native.d.ts","sourceRoot":"","sources":["../src/windows-permissions-native.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExE,wBAAgB,+BAA+B,CAAC,MAAM,EAAE;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,GAAG,eAAe,GAAG,SAAS,CA2B9B"}

package/dist/windows-permissions-native.js

@@ -0,0 +1,31 @@
+import { getNativeBinding } from "./native.js";
+export function inspectWindowsPermissionsNative(params) {
+    const native = getNativeBinding();
+    if (!native)
+        return undefined;
+    try {
+        const facts = native.readOwnerAndDacl(params.targetPath);
+        if (facts.fallbackRequired)
+            return undefined;
+        return {
+            ok: true,
+            isSymlink: params.stat.isSymlink,
+            isDir: params.effectiveIsDir,
+            mode: params.effectiveMode,
+            bits: params.bits,
+            source: "windows-acl",
+            worldWritable: facts.worldWritable,
+            groupWritable: facts.groupWritable,
+            worldReadable: facts.worldReadable,
+            groupReadable: facts.groupReadable,
+            ownerSid: facts.ownerSid,
+            ownerTrusted: facts.ownerClass !== "foreign",
+            aclSummary: `native owner=${facts.ownerClass} world=` +
+                `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
+                `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}