@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/copy-tree-portable.js

@@ -0,0 +1,245 @@
+import { setMaxListeners } from "node:events";
+import fs from "node:fs";
+import fsp, {} from "node:fs/promises";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { assertStagedDirectoryCurrent, exactIdentityMatches, openStagedDirectory, } from "./staged-directory.js";
+function timestampSeconds(nanoseconds) {
+    // Dates discard sub-millisecond precision; negative numbers mean "now" in
+    // Node's utimes API. Numeric strings retain fractional, pre-epoch timestamps.
+    return String(Number(nanoseconds / 1000000000n) + Number(nanoseconds % 1000000000n) / 1e9);
+}
+/** Byte-copy adapter for the shared immutable-source, caller-owned namespace contract. */
+export async function copyOwnedTree(source, destination, options) {
+    const callerSignal = options.signal ? AbortSignal.any([options.signal]) : undefined;
+    const cancellation = new AbortController();
+    const signal = cancellation.signal;
+    setMaxListeners(options.concurrency, signal);
+    const pending = new Set();
+    const finishing = new Set();
+    const buffers = [];
+    let failure = undefined;
+    function recordFailure(value) {
+        failure ??= { value };
+        cancellation.abort(failure);
+    }
+    if (callerSignal)
+        callerSignal.onabort = () => recordFailure(callerSignal.reason);
+    async function schedule(operation, children) {
+        signal.throwIfAborted();
+        const task = operation()
+            .catch((error) => {
+            recordFailure(error);
+        })
+            .finally(() => {
+            pending.delete(task);
+            children.delete(task);
+        });
+        pending.add(task);
+        children.add(task);
+        if (pending.size >= options.concurrency)
+            await Promise.race(pending);
+        signal.throwIfAborted();
+    }
+    async function copyFile(from, to, stat) {
+        const input = await fsp.open(from, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        let output;
+        try {
+            const opened = await input.stat({ bigint: true });
+            if (!opened.isFile() || !exactIdentityMatches(stat, opened)) {
+                throw new FsSafeError("path-mismatch", "copy source changed while opening");
+            }
+            output = await fsp.open(to, "wx", 0o600);
+            if (options.copyFileContents) {
+                // napi-rs owns onabort. Each admitted file gets a separate signal; the
+                // shared failure signal is private, so callers cannot intercept its relay.
+                const fileCancellation = new AbortController();
+                const abortFile = () => fileCancellation.abort();
+                signal.addEventListener("abort", abortFile, { once: true });
+                try {
+                    signal.throwIfAborted();
+                    await options.copyFileContents(input.fd, output.fd, fileCancellation.signal);
+                }
+                finally {
+                    signal.removeEventListener("abort", abortFile);
+                    fileCancellation.signal.onabort = null;
+                }
+            }
+            else {
+                const buffer = buffers.pop() ??
+                    Buffer.allocUnsafe(process.platform === "win32" ? 1024 * 1024 : 128 * 1024);
+                try {
+                    let position = 0;
+                    while (true) {
+                        signal.throwIfAborted();
+                        const { bytesRead } = await input.read(buffer, 0, buffer.length, position);
+                        if (bytesRead === 0)
+                            break;
+                        let written = 0;
+                        while (written < bytesRead) {
+                            signal.throwIfAborted();
+                            const { bytesWritten } = await output.write(buffer, written, bytesRead - written, position + written);
+                            if (bytesWritten === 0)
+                                throw new Error("copy write made no progress");
+                            written += bytesWritten;
+                        }
+                        position += bytesRead;
+                    }
+                }
+                finally {
+                    buffers.push(buffer);
+                }
+            }
+            signal.throwIfAborted();
+            if (process.platform !== "win32")
+                await output.chmod(Number(stat.mode & 4095n));
+            await output.utimes(timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
+        }
+        catch (error) {
+            recordFailure(error);
+        }
+        if (output) {
+            try {
+                await output.close();
+            }
+            catch (error) {
+                recordFailure(error);
+            }
+        }
+        try {
+            await input.close();
+        }
+        catch (error) {
+            recordFailure(error);
+        }
+    }
+    async function copyDirectory(from, to, parentChildren) {
+        signal.throwIfAborted();
+        const stat = await fsp.lstat(from, { bigint: true });
+        // Exclusive admission prevents merging a pre-existing directory, including
+        // any destination left by an unsuccessful native clone.
+        await fsp.mkdir(to, { mode: 0o700 });
+        const target = openStagedDirectory(to);
+        const children = new Set();
+        let original;
+        try {
+            original = openStagedDirectory(from);
+            if (!exactIdentityMatches(stat, original.receipt.identity)) {
+                throw new FsSafeError("path-mismatch", "copy source directory changed while opening");
+            }
+            for (const entry of await fsp.readdir(from, { withFileTypes: true })) {
+                signal.throwIfAborted();
+                assertStagedDirectoryCurrent(target.receipt);
+                assertStagedDirectoryCurrent(original.receipt);
+                const childSource = path.join(from, entry.name);
+                const childTarget = path.join(to, entry.name);
+                const child = await fsp.lstat(childSource, { bigint: true });
+                if (child.isDirectory()) {
+                    await copyDirectory(childSource, childTarget, children);
+                }
+                else if (child.isFile()) {
+                    await schedule(() => copyFile(childSource, childTarget, child), children);
+                }
+                else if (child.isSymbolicLink()) {
+                    const link = process.platform === "win32"
+                        ? await fsp.readlink(childSource)
+                        : await fsp.readlink(childSource, { encoding: "buffer" });
+                    let type;
+                    if (process.platform === "win32") {
+                        // Older Node releases infer link type from the destination, where a
+                        // relative directory target may not exist yet. Inspect the source.
+                        // lstat does not expose the Windows link's directory attribute, so
+                        // an unresolved source cannot be recreated with a proven type.
+                        try {
+                            type = (await fsp.stat(childSource)).isDirectory() ? "dir" : "file";
+                        }
+                        catch (error) {
+                            if (error instanceof Error &&
+                                "code" in error &&
+                                (error.code === "ENOENT" || error.code === "ENOTDIR" || error.code === "ELOOP")) {
+                                throw new FsSafeError("unsupported-platform", "byte copying cannot determine the type of an unresolved Windows symbolic link", { cause: error });
+                            }
+                            throw error;
+                        }
+                    }
+                    signal.throwIfAborted();
+                    await fsp.symlink(link, childTarget, type);
+                }
+                else {
+                    throw new FsSafeError("not-file", "tree copying does not support special files");
+                }
+            }
+        }
+        catch (error) {
+            recordFailure(error);
+            throw error;
+        }
+        finally {
+            // Traversal can advance into siblings while this directory's own files
+            // settle. Children retain their parents and finish metadata bottom-up.
+            const completion = (async () => {
+                try {
+                    await Promise.all(children);
+                    signal.throwIfAborted();
+                    if (original) {
+                        assertStagedDirectoryCurrent(original.receipt);
+                        assertStagedDirectoryCurrent(target.receipt);
+                        if (process.platform !== "win32")
+                            fs.fchmodSync(target.fd, Number(stat.mode & 4095n));
+                        await fsp.utimes(to, timestampSeconds(stat.atimeNs), timestampSeconds(stat.mtimeNs));
+                        assertStagedDirectoryCurrent(target.receipt);
+                    }
+                }
+                catch (error) {
+                    recordFailure(error);
+                }
+                if (original) {
+                    try {
+                        fs.closeSync(original.fd);
+                    }
+                    catch (error) {
+                        recordFailure(error);
+                    }
+                }
+                try {
+                    fs.closeSync(target.fd);
+                }
+                catch (error) {
+                    recordFailure(error);
+                }
+            })()
+                .catch((error) => {
+                recordFailure(error);
+            })
+                .finally(() => {
+                finishing.delete(completion);
+                parentChildren?.delete(completion);
+            });
+            finishing.add(completion);
+            parentChildren?.add(completion);
+            // Bound traversed-but-unsettled directories as well as file workers;
+            // ancestors stay open along the current traversal path.
+            if (finishing.size >= options.concurrency)
+                await Promise.race(finishing);
+        }
+        signal.throwIfAborted();
+    }
+    try {
+        callerSignal?.throwIfAborted();
+        await copyDirectory(source.receipt.realPath, destination);
+        await Promise.all(finishing);
+        signal.throwIfAborted();
+    }
+    catch (error) {
+        recordFailure(error);
+    }
+    finally {
+        await Promise.all(finishing);
+        if (callerSignal)
+            callerSignal.onabort = null;
+    }
+    if (failure)
+        throw failure.value;
+    options.signal?.throwIfAborted();
+    signal.throwIfAborted();
+}

package/node_modules/@openclaw/fs-safe/dist/copy.d.ts

@@ -0,0 +1,15 @@
+import { type CopyCloneMode } from "./copy-policy.js";
+export { readCloneFileMetadata, type CloneFileMetadata } from "./clone-metadata.js";
+export type { CopyCloneMode } from "./copy-policy.js";
+export type TreeCloneBackend = "apfs" | "btrfs" | "refs" | "xfs" | "zfs";
+export type CopyTreeOptions = {
+    clone?: CopyCloneMode;
+    signal?: AbortSignal;
+    concurrency?: number;
+};
+/** Inspect an existing real directory without creating probe files. */
+export declare function probeTreeClone(parentPath: string): TreeCloneBackend | undefined;
+/** Create an empty clone source: a Btrfs subvolume or an ordinary supported directory. */
+export declare function createCloneSource(destination: string, options?: Pick<CopyTreeOptions, "signal">): Promise<void>;
+/** Copy an immutable, caller-owned tree, preferring native cloning unless configured otherwise. */
+export declare function copyTree(source: string, destination: string, options?: CopyTreeOptions): Promise<void>;

package/node_modules/@openclaw/fs-safe/dist/copy.js

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertAbsolutePathInput } from "./absolute-path.js";
+import { resolveCopyCloneMode } from "./copy-policy.js";
+import { copyOwnedTree } from "./copy-tree-portable.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding, requireNativeBinding } from "./native.js";
+import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
+export { readCloneFileMetadata } from "./clone-metadata.js";
+function firstFailure(current, value) {
+    return current ?? { value };
+}
+function closeDescriptor(fd, failure) {
+    try {
+        fs.closeSync(fd);
+        return failure;
+    }
+    catch (error) {
+        return firstFailure(failure, error);
+    }
+}
+/** Inspect an existing real directory without creating probe files. */
+export function probeTreeClone(parentPath) {
+    const native = getNativeBinding();
+    if (!native)
+        return undefined;
+    const parent = openStagedDirectory(assertAbsolutePathInput(parentPath));
+    let backend;
+    let failure;
+    try {
+        backend = native.probeTreeClone(parent.fd) ?? undefined;
+    }
+    catch (error) {
+        failure = firstFailure(failure, error);
+    }
+    failure = closeDescriptor(parent.fd, failure);
+    if (failure)
+        throw failure.value;
+    return backend;
+}
+/** Create an empty clone source: a Btrfs subvolume or an ordinary supported directory. */
+export async function createCloneSource(destination, options = {}) {
+    await materializeTree(undefined, destination, options, "always");
+}
+/** Copy an immutable, caller-owned tree, preferring native cloning unless configured otherwise. */
+export async function copyTree(source, destination, options = {}) {
+    options.signal?.throwIfAborted();
+    const policy = resolveCopyCloneMode(options.clone, "auto");
+    await materializeTree(source, destination, options, policy);
+}
+function cloneUnavailable(error) {
+    if (error instanceof FsSafeError && error.code === "unsupported-platform")
+        return true;
+    if (!(error instanceof Error) || !("code" in error))
+        return false;
+    // ENOTSUP also describes unsupported contents (for example named streams).
+    // Only capability failures may select a byte copy, never lossy source errors.
+    return error.code === "CLONE_UNAVAILABLE" || error.code === "EXDEV" || error.code === "ENOSYS";
+}
+async function materializeTree(source, destination, options, policy) {
+    options.signal?.throwIfAborted();
+    const concurrency = options.concurrency ?? 16;
+    if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 32) {
+        throw new FsSafeError("invalid-path", "clone concurrency must be an integer between 1 and 32");
+    }
+    const native = policy === "always"
+        ? requireNativeBinding()
+        : policy === "auto"
+            ? getNativeBinding()
+            : undefined;
+    const target = assertAbsolutePathInput(destination);
+    const name = path.basename(target);
+    if (!name)
+        throw new FsSafeError("invalid-path", "clone destination must name a child directory");
+    const parent = openStagedDirectory(path.dirname(target));
+    let original;
+    let failure;
+    try {
+        const supported = native?.probeTreeClone(parent.fd);
+        if (!supported && policy === "always") {
+            throw new FsSafeError("unsupported-platform", "destination filesystem does not support tree cloning");
+        }
+        if (source !== undefined) {
+            original = openStagedDirectory(assertAbsolutePathInput(source));
+            const relative = path.relative(original.receipt.realPath, path.join(parent.receipt.realPath, name));
+            if (relative === "" ||
+                (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`))) {
+                throw new FsSafeError("invalid-path", "clone destination must be outside the source tree");
+            }
+            assertStagedDirectoryCurrent(original.receipt);
+        }
+        assertStagedDirectoryCurrent(parent.receipt);
+        options.signal?.throwIfAborted();
+        let cloned = false;
+        // napi-rs uses the supplied signal's onabort property. Give it a private
+        // signal so caller handlers and other admitted native operations stay intact.
+        const nativeSignal = options.signal && supported ? AbortSignal.any([options.signal]) : undefined;
+        try {
+            if (native && supported) {
+                nativeSignal?.throwIfAborted();
+                await native.cloneTree(original?.fd ?? null, parent.fd, name, concurrency, nativeSignal);
+                cloned = true;
+            }
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (policy !== "auto" || !cloneUnavailable(error)) {
+                if (error instanceof Error && "code" in error && error.code === "CLONE_UNAVAILABLE") {
+                    throw new FsSafeError("unsupported-platform", error.message, { cause: error });
+                }
+                throw error;
+            }
+        }
+        finally {
+            if (nativeSignal)
+                nativeSignal.onabort = null;
+        }
+        options.signal?.throwIfAborted();
+        assertStagedDirectoryCurrent(parent.receipt);
+        if (original)
+            assertStagedDirectoryCurrent(original.receipt);
+        if (!cloned && original) {
+            await copyOwnedTree(original, target, {
+                signal: options.signal,
+                concurrency: options.concurrency ?? (process.platform === "win32" ? 4 : 1),
+                copyFileContents: process.platform === "win32" || process.platform === "linux"
+                    ? native?.copyFileContents
+                    : undefined,
+            });
+            options.signal?.throwIfAborted();
+            assertStagedDirectoryCurrent(parent.receipt);
+            assertStagedDirectoryCurrent(original.receipt);
+        }
+    }
+    catch (error) {
+        failure = firstFailure(failure, error);
+    }
+    if (original)
+        failure = closeDescriptor(original.fd, failure);
+    failure = closeDescriptor(parent.fd, failure);
+    if (failure)
+        throw failure.value;
+}

package/node_modules/@openclaw/fs-safe/dist/create-owned-file.d.ts

@@ -0,0 +1,7 @@
+export type OwnedFileDescriptorSync = {
+    readonly fd: number;
+    close(): void;
+    [Symbol.dispose](): void;
+};
+/** Capture the descriptor's creator-owned closer before it can be reused. */
+export declare function ownFileDescriptorSync(fd: number, closeFd?: (fd: number) => void): OwnedFileDescriptorSync;

package/node_modules/@openclaw/fs-safe/dist/create-owned-file.js

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+/** Capture the descriptor's creator-owned closer before it can be reused. */
+export function ownFileDescriptorSync(fd, closeFd = fs.closeSync) {
+    let open = true;
+    const owner = {
+        fd,
+        close() {
+            if (!open)
+                return;
+            open = false;
+            closeFd(fd);
+        },
+        [Symbol.dispose]() { owner.close(); },
+    };
+    return Object.freeze(owner);
+}

package/node_modules/@openclaw/fs-safe/dist/create.d.ts

@@ -0,0 +1,17 @@
+import { type FileHandle } from "node:fs/promises";
+import { type OwnedFileDescriptorSync } from "./create-owned-file.js";
+import { type CreationPermissions, type CreationParentIdentity } from "./creation-boundary.js";
+export type { OwnedFileDescriptorSync } from "./create-owned-file.js";
+export type CreateFileOptions = CreateDirectoryOptions;
+export declare function createFileSync(targetPath: string, options?: CreateFileOptions): OwnedFileDescriptorSync;
+/** Internal async writer; Windows preparation uses the nonblocking stage owner. */
+export declare function createFileHandle(targetPath: string, options?: CreateFileOptions, admission?: CreationAdmission): Promise<FileHandle>;
+export type CreateDirectoryOptions = CreationPermissions & {
+    assertBeforeMutation?: () => void;
+};
+export type CreationAdmission = {
+    expectedParentIdentity?: CreationParentIdentity;
+};
+export declare function createDirectory(targetPath: string, options?: CreateDirectoryOptions): Promise<void>;
+export declare function createDirectoryWithAdmission(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): Promise<void>;
+export declare function createDirectorySync(targetPath: string, options?: CreateDirectoryOptions): void;