@openclaw/fs-safe 0.1.0

package/dist/sidecar-lock.js

@@ -0,0 +1,235 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+const GLOBAL_STATE_KEY = Symbol.for("fsSafe.sidecarLockManagers");
+function getGlobalManagers() {
+    const globalWithState = globalThis;
+    if (!globalWithState[GLOBAL_STATE_KEY]) {
+        globalWithState[GLOBAL_STATE_KEY] = new Map();
+    }
+    return globalWithState[GLOBAL_STATE_KEY];
+}
+function resolveManagerState(key) {
+    const managers = getGlobalManagers();
+    let state = managers.get(key);
+    if (!state) {
+        state = { cleanupRegistered: false, held: new Map() };
+        managers.set(key, state);
+    }
+    return state;
+}
+async function readJsonPayload(lockPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(lockPath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveNormalizedTargetPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    const dir = path.dirname(resolved);
+    await fs.mkdir(dir, { recursive: true });
+    try {
+        return path.join(await fs.realpath(dir), path.basename(resolved));
+    }
+    catch {
+        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 releaseAllLocksSync(state) {
+    for (const [normalizedTargetPath, held] of state.held) {
+        void held.handle.close().catch(() => undefined);
+        try {
+            fsSync.rmSync(held.lockPath, { force: true });
+        }
+        catch {
+            // Best-effort process-exit cleanup.
+        }
+        state.held.delete(normalizedTargetPath);
+    }
+}
+async function releaseHeldLock(state, normalizedTargetPath, held, opts = {}) {
+    const current = state.held.get(normalizedTargetPath);
+    if (current !== held) {
+        return false;
+    }
+    if (opts.force) {
+        held.count = 0;
+    }
+    else {
+        held.count -= 1;
+        if (held.count > 0) {
+            return false;
+        }
+    }
+    if (held.releasePromise) {
+        await held.releasePromise.catch(() => undefined);
+        return true;
+    }
+    state.held.delete(normalizedTargetPath);
+    held.releasePromise = (async () => {
+        await held.handle.close().catch(() => undefined);
+        await fs.rm(held.lockPath, { force: true }).catch(() => undefined);
+    })();
+    try {
+        await held.releasePromise;
+        return true;
+    }
+    finally {
+        held.releasePromise = undefined;
+    }
+}
+export function createSidecarLockManager(key) {
+    const state = resolveManagerState(key);
+    function ensureExitCleanupRegistered() {
+        if (state.cleanupRegistered) {
+            return;
+        }
+        state.cleanupRegistered = true;
+        process.on("exit", () => releaseAllLocksSync(state));
+    }
+    async function acquire(options) {
+        ensureExitCleanupRegistered();
+        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,
+            };
+        }
+        const startedAt = Date.now();
+        const retry = options.retry ?? {};
+        const maxRetries = options.timeoutMs === Number.POSITIVE_INFINITY ? undefined : retry.retries;
+        let attempt = 0;
+        while (true) {
+            let handle = null;
+            try {
+                handle = await fs.open(lockPath, "wx");
+                const createdHeld = {
+                    count: 1,
+                    handle,
+                    lockPath,
+                    acquiredAt: Date.now(),
+                    metadata: options.metadata ?? {},
+                };
+                state.held.set(normalizedTargetPath, createdHeld);
+                await handle.writeFile(`${JSON.stringify(await options.payload(), null, 2)}\n`, "utf8");
+                const release = () => releaseHeldLock(state, normalizedTargetPath, createdHeld).then(() => undefined);
+                return {
+                    lockPath,
+                    normalizedTargetPath,
+                    release,
+                    [Symbol.asyncDispose]: release,
+                };
+            }
+            catch (err) {
+                if (handle) {
+                    const current = state.held.get(normalizedTargetPath);
+                    if (current?.handle === handle) {
+                        state.held.delete(normalizedTargetPath);
+                    }
+                    await handle.close().catch(() => undefined);
+                    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                }
+                if (err.code !== "EEXIST") {
+                    throw err;
+                }
+                const nowMs = Date.now();
+                const payload = await readJsonPayload(lockPath);
+                const shouldReclaim = options.shouldReclaim ?? defaultShouldReclaim;
+                if (await shouldReclaim({
+                    lockPath,
+                    normalizedTargetPath,
+                    payload,
+                    staleMs: options.staleMs,
+                    nowMs,
+                    heldByThisProcess: state.held.has(normalizedTargetPath),
+                })) {
+                    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                    continue;
+                }
+                const elapsed = Date.now() - startedAt;
+                if ((options.timeoutMs !== undefined &&
+                    options.timeoutMs !== Number.POSITIVE_INFINITY &&
+                    elapsed >= options.timeoutMs) ||
+                    (maxRetries !== undefined && attempt >= maxRetries)) {
+                    throw Object.assign(new Error(`file lock timeout for ${normalizedTargetPath}`), {
+                        code: "file_lock_timeout",
+                        lockPath,
+                        normalizedTargetPath,
+                    });
+                }
+                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);
+                attempt += 1;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+    async function withLock(options, fn) {
+        const lock = await acquire(options);
+        try {
+            return await fn();
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    async function drain() {
+        for (const [normalizedTargetPath, held] of Array.from(state.held.entries())) {
+            await releaseHeldLock(state, normalizedTargetPath, held, { force: true }).catch(() => undefined);
+        }
+    }
+    function reset() {
+        releaseAllLocksSync(state);
+    }
+    function heldEntries() {
+        return Array.from(state.held.entries()).map(([normalizedTargetPath, held]) => ({
+            normalizedTargetPath,
+            lockPath: held.lockPath,
+            acquiredAt: held.acquiredAt,
+            metadata: held.metadata,
+            forceRelease: () => releaseHeldLock(state, normalizedTargetPath, held, { force: true }),
+        }));
+    }
+    return { acquire, withLock, drain, reset, heldEntries };
+}
+export async function withSidecarLock(targetPath, options, fn) {
+    const manager = createSidecarLockManager(options.managerKey ?? `fs-safe.sidecar-lock:${targetPath}`);
+    const { managerKey: _managerKey, ...acquireOptions } = options;
+    return await manager.withLock({ ...acquireOptions, targetPath }, fn);
+}

package/dist/store.d.ts

@@ -0,0 +1,3 @@
+export { fileStore, fileStoreSync, type FileStore, type FileStoreOptions, type FileStorePruneOptions, type FileStoreReadOptions, type FileStoreSync, type FileStoreWriteOptions, } from "./file-store.js";
+export { jsonStore, type JsonStore, type JsonFileStoreOptions, type JsonStoreLockOptions, type JsonStoreOptions, } from "./json-store.js";
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,SAAS,EACT,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/store.js

@@ -0,0 +1,2 @@
+export { fileStore, fileStoreSync, } from "./file-store.js";
+export { jsonStore, } from "./json-store.js";

package/dist/string-coerce.d.ts

@@ -0,0 +1,14 @@
+export declare function readStringValue(value: unknown): string | undefined;
+export declare function normalizeNullableString(value: unknown): string | null;
+export declare function normalizeOptionalString(value: unknown): string | undefined;
+export declare function normalizeStringifiedOptionalString(value: unknown): string | undefined;
+export declare function normalizeOptionalLowercaseString(value: unknown): string | undefined;
+export declare function normalizeLowercaseStringOrEmpty(value: unknown): string;
+export declare function normalizeFastMode(raw?: string | boolean | null): boolean | undefined;
+export declare function lowercasePreservingWhitespace(value: string): string;
+export declare function localeLowercasePreservingWhitespace(value: string): string;
+export declare function resolvePrimaryStringValue(value: unknown): string | undefined;
+export declare function normalizeOptionalThreadValue(value: unknown): string | number | undefined;
+export declare function normalizeOptionalStringifiedId(value: unknown): string | undefined;
+export declare function hasNonEmptyString(value: unknown): value is string;
+//# sourceMappingURL=string-coerce.d.ts.map

package/dist/string-coerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-coerce.d.ts","sourceRoot":"","sources":["../src/string-coerce.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAMrE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE1E;AAED,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQrF;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEnF;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAepF;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQ5E;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAKxF;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE"}

package/dist/string-coerce.js

@@ -0,0 +1,72 @@
+export function readStringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function normalizeNullableString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+export function normalizeOptionalString(value) {
+    return normalizeNullableString(value) ?? undefined;
+}
+export function normalizeStringifiedOptionalString(value) {
+    if (typeof value === "string") {
+        return normalizeOptionalString(value);
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return normalizeOptionalString(String(value));
+    }
+    return undefined;
+}
+export function normalizeOptionalLowercaseString(value) {
+    return normalizeOptionalString(value)?.toLowerCase();
+}
+export function normalizeLowercaseStringOrEmpty(value) {
+    return normalizeOptionalLowercaseString(value) ?? "";
+}
+export function normalizeFastMode(raw) {
+    if (typeof raw === "boolean") {
+        return raw;
+    }
+    if (!raw) {
+        return undefined;
+    }
+    const key = normalizeLowercaseStringOrEmpty(raw);
+    if (["off", "false", "no", "0", "disable", "disabled", "normal"].includes(key)) {
+        return false;
+    }
+    if (["on", "true", "yes", "1", "enable", "enabled", "fast"].includes(key)) {
+        return true;
+    }
+    return undefined;
+}
+export function lowercasePreservingWhitespace(value) {
+    return value.toLowerCase();
+}
+export function localeLowercasePreservingWhitespace(value) {
+    return value.toLocaleLowerCase();
+}
+export function resolvePrimaryStringValue(value) {
+    if (typeof value === "string") {
+        return normalizeOptionalString(value);
+    }
+    if (!value || typeof value !== "object") {
+        return undefined;
+    }
+    return normalizeOptionalString(value.primary);
+}
+export function normalizeOptionalThreadValue(value) {
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? Math.trunc(value) : undefined;
+    }
+    return normalizeOptionalString(value);
+}
+export function normalizeOptionalStringifiedId(value) {
+    const normalized = normalizeOptionalThreadValue(value);
+    return normalized == null ? undefined : String(normalized);
+}
+export function hasNonEmptyString(value) {
+    return normalizeOptionalString(value) !== undefined;
+}

package/dist/symlink-parents.d.ts

@@ -0,0 +1,12 @@
+export type AssertNoSymlinkParentsOptions = {
+    rootDir: string;
+    targetPath: string;
+    allowMissing?: boolean;
+    allowOutsideRoot?: boolean;
+    allowRootChildSymlink?: boolean;
+    requireDirectories?: boolean;
+    messagePrefix?: string;
+};
+export declare function assertNoSymlinkParents(params: AssertNoSymlinkParentsOptions): Promise<void>;
+export declare function assertNoSymlinkParentsSync(params: AssertNoSymlinkParentsOptions): void;
+//# sourceMappingURL=symlink-parents.d.ts.map

package/dist/symlink-parents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symlink-parents.d.ts","sourceRoot":"","sources":["../src/symlink-parents.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAyBF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,6BAA6B,GACpC,IAAI,CA0BN"}

package/dist/symlink-parents.js

@@ -0,0 +1,78 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isNotFoundPathError } from "./path.js";
+function resolvePathWalk(params) {
+    const root = path.resolve(params.rootDir);
+    const target = path.resolve(params.targetPath);
+    const relative = path.relative(root, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        if (params.allowOutsideRoot) {
+            return null;
+        }
+        throw new Error(`${params.messagePrefix ?? "Path"} must stay under ${root}.`);
+    }
+    return {
+        root,
+        segments: relative && relative !== "." ? relative.split(path.sep).filter(Boolean) : [],
+    };
+}
+function formatUnsafePath(params, current) {
+    return `${params.messagePrefix ?? "Path"} must not traverse symlinked directory: ${current}`;
+}
+export async function assertNoSymlinkParents(params) {
+    const walk = resolvePathWalk(params);
+    if (!walk) {
+        return;
+    }
+    let current = walk.root;
+    for (const segment of walk.segments) {
+        current = path.join(current, segment);
+        try {
+            const stat = await fs.lstat(current);
+            if (stat.isSymbolicLink()) {
+                if (params.allowRootChildSymlink && path.dirname(current) === walk.root) {
+                    continue;
+                }
+                throw new Error(formatUnsafePath(params, current));
+            }
+            if (params.requireDirectories && !stat.isDirectory()) {
+                throw new Error(`${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
+            }
+        }
+        catch (err) {
+            if (isNotFoundPathError(err) && params.allowMissing !== false) {
+                return;
+            }
+            throw err;
+        }
+    }
+}
+export function assertNoSymlinkParentsSync(params) {
+    const walk = resolvePathWalk(params);
+    if (!walk) {
+        return;
+    }
+    let current = walk.root;
+    for (const segment of walk.segments) {
+        current = path.join(current, segment);
+        try {
+            const stat = fsSync.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                if (params.allowRootChildSymlink && path.dirname(current) === walk.root) {
+                    continue;
+                }
+                throw new Error(formatUnsafePath(params, current));
+            }
+            if (params.requireDirectories && !stat.isDirectory()) {
+                throw new Error(`${params.messagePrefix ?? "Path"} must traverse directories: ${current}`);
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT" && params.allowMissing !== false) {
+                return;
+            }
+            throw err;
+        }
+    }
+}

package/dist/temp-cleanup.d.ts

@@ -0,0 +1,6 @@
+export declare function registerTempPathForExit(tempPath: string, options?: {
+    recursive?: boolean;
+}): () => void;
+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

@@ -0,0 +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"}

package/dist/temp-cleanup.js

@@ -0,0 +1,42 @@
+import fsSync from "node:fs";
+const tempCleanupEntries = new Map();
+let cleanupRegistered = false;
+function cleanupRegisteredTempPathsSync() {
+    for (const entry of tempCleanupEntries.values()) {
+        try {
+            fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+        }
+        catch {
+            // Process-exit cleanup is best-effort.
+        }
+    }
+    tempCleanupEntries.clear();
+}
+export function registerTempPathForExit(tempPath, options) {
+    if (!cleanupRegistered) {
+        cleanupRegistered = true;
+        process.once("exit", cleanupRegisteredTempPathsSync);
+    }
+    tempCleanupEntries.set(tempPath, {
+        path: tempPath,
+        recursive: options?.recursive === true,
+    });
+    return () => {
+        tempCleanupEntries.delete(tempPath);
+    };
+}
+export function __cleanupRegisteredTempPathsForTest() {
+    cleanupRegisteredTempPathsSync();
+}
+export function __cleanupRegisteredTempPathForTest(tempPath) {
+    const entry = tempCleanupEntries.get(tempPath);
+    if (!entry) {
+        return;
+    }
+    try {
+        fsSync.rmSync(entry.path, { force: true, recursive: entry.recursive });
+    }
+    finally {
+        tempCleanupEntries.delete(tempPath);
+    }
+}

package/dist/temp-target.d.ts

@@ -0,0 +1,28 @@
+export type TempFile = {
+    dir: string;
+    path: string;
+    file(fileName?: string): string;
+    cleanup: () => Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+export declare function sanitizeTempFileName(fileName: string): string;
+export declare function buildRandomTempFilePath(params: {
+    rootDir?: string;
+    prefix: string;
+    extension?: string;
+    now?: number;
+    uuid?: string;
+}): string;
+export declare function tempFile(params: {
+    rootDir?: string;
+    prefix: string;
+    fileName?: string;
+    onCleanupError?: (error: unknown) => void;
+}): Promise<TempFile>;
+export declare function withTempFile<T>(params: {
+    rootDir?: string;
+    prefix: string;
+    fileName?: string;
+    onCleanupError?: (error: unknown) => void;
+}, fn: (tmpPath: string) => Promise<T>): Promise<T>;
+//# sourceMappingURL=temp-target.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"temp-target.d.ts","sourceRoot":"","sources":["../src/temp-target.ts"],"names":[],"mappings":"AAMA,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,CAWT;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

@@ -0,0 +1,84 @@
+import crypto from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+function sanitizePrefix(prefix) {
+    const normalized = prefix.replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    return normalized || "tmp";
+}
+function sanitizeExtension(extension) {
+    if (!extension) {
+        return "";
+    }
+    const normalized = extension.startsWith(".") ? extension : `.${extension}`;
+    const suffix = normalized.match(/[a-zA-Z0-9._-]+$/)?.[0] ?? "";
+    const token = suffix.replace(/^[._-]+/, "");
+    return token ? `.${token}` : "";
+}
+export function sanitizeTempFileName(fileName) {
+    const base = path.basename(fileName).replace(/[^a-zA-Z0-9._-]+/g, "-");
+    const normalized = base.replace(/^-+|-+$/g, "");
+    return normalized || "download.bin";
+}
+export function buildRandomTempFilePath(params) {
+    const rootDir = resolveTempRoot(params.rootDir);
+    const prefix = sanitizePrefix(params.prefix);
+    const extension = sanitizeExtension(params.extension);
+    const nowCandidate = params.now;
+    const now = typeof nowCandidate === "number" && Number.isFinite(nowCandidate)
+        ? Math.trunc(nowCandidate)
+        : Date.now();
+    const uuid = params.uuid?.trim() || crypto.randomUUID();
+    return path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
+}
+function isNodeErrorWithCode(err, code) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === code);
+}
+async function cleanupTempDir(dir, onCleanupError) {
+    try {
+        await rm(dir, { recursive: true, force: true });
+    }
+    catch (err) {
+        if (!isNodeErrorWithCode(err, "ENOENT")) {
+            onCleanupError?.(err);
+        }
+    }
+}
+function resolveTempRoot(rootDir) {
+    return rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" });
+}
+export async function tempFile(params) {
+    const rootDir = resolveTempRoot(params.rootDir);
+    const prefix = `${sanitizePrefix(params.prefix)}-`;
+    const dir = await mkdtemp(path.join(rootDir, prefix));
+    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true });
+    const file = (fileName) => path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+    const cleanup = async () => {
+        try {
+            await cleanupTempDir(dir, params.onCleanupError);
+        }
+        finally {
+            unregisterTempDir();
+        }
+    };
+    return {
+        dir,
+        path: file(),
+        file,
+        cleanup,
+        [Symbol.asyncDispose]: cleanup,
+    };
+}
+export async function withTempFile(params, fn) {
+    const target = await tempFile(params);
+    try {
+        return await fn(target.path);
+    }
+    finally {
+        await target.cleanup();
+    }
+}

package/dist/temp.d.ts

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

package/dist/temp.d.ts.map

@@ -0,0 +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"}

package/dist/temp.js

@@ -0,0 +1,2 @@
+export { tempWorkspace, tempWorkspaceSync, withTempWorkspace, withTempWorkspaceSync, } from "./private-temp-workspace.js";
+export { resolveSecureTempRoot } from "./secure-temp-dir.js";

package/dist/test-hooks.d.ts

@@ -0,0 +1,9 @@
+import type { FileHandle } from "node:fs/promises";
+export type FsSafeTestHooks = {
+    afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
+    beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
+    afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;
+};
+export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
+export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;
+//# sourceMappingURL=test-hooks.d.ts.map

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

@@ -0,0 +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;CAC5E,CAAC;AAQF,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAEhE;AAED,wBAAgB,2BAA2B,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAKzE"}

package/dist/test-hooks.js

@@ -0,0 +1,13 @@
+let fsSafeTestHooks;
+function allowFsSafeTestHooks() {
+    return process.env.NODE_ENV === "test" || process.env.VITEST === "true";
+}
+export function getFsSafeTestHooks() {
+    return fsSafeTestHooks;
+}
+export function __setFsSafeTestHooksForTest(hooks) {
+    if (hooks && !allowFsSafeTestHooks()) {
+        throw new Error("__setFsSafeTestHooksForTest is only available in tests");
+    }
+    fsSafeTestHooks = hooks;
+}

package/dist/text-atomic.d.ts

@@ -0,0 +1,7 @@
+export type WriteTextAtomicOptions = {
+    mode?: number;
+    dirMode?: number;
+    trailingNewline?: boolean;
+};
+export declare function writeTextAtomic(filePath: string, content: string, options?: WriteTextAtomicOptions): Promise<void>;
+//# sourceMappingURL=text-atomic.d.ts.map

package/dist/text-atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-atomic.d.ts","sourceRoot":"","sources":["../src/text-atomic.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAWf"}