@openclaw/fs-safe 0.1.0

package/dist/text-atomic.js

@@ -0,0 +1,13 @@
+import { replaceFileAtomic } from "./replace-file.js";
+export async function writeTextAtomic(filePath, content, options) {
+    const payload = options?.trailingNewline && !content.endsWith("\n") ? `${content}\n` : content;
+    await replaceFileAtomic({
+        filePath,
+        content: payload,
+        mode: options?.mode ?? 0o600,
+        dirMode: options?.dirMode ?? (0o777 & ~process.umask()),
+        copyFallbackOnPermissionError: true,
+        syncTempFile: true,
+        syncParentDir: true,
+    });
+}

package/dist/timing.d.ts

@@ -0,0 +1,6 @@
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, labelOrOptions?: string | {
+    label?: string;
+    message?: string;
+    createError?: () => Error;
+}): Promise<T>;
+//# sourceMappingURL=timing.d.ts.map

package/dist/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,cAAc,GAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAErF,GACA,OAAO,CAAC,CAAC,CAAC,CAuBZ"}

package/dist/timing.js

@@ -0,0 +1,24 @@
+export async function withTimeout(promise, timeoutMs, labelOrOptions = {
+    message: "timeout",
+}) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return await promise;
+    }
+    const options = typeof labelOrOptions === "string" ? { label: labelOrOptions } : labelOrOptions;
+    const createError = options.createError ??
+        (() => new Error(options.message ?? `${options.label ?? "operation"} timed out after ${timeoutMs}ms`));
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(createError()), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}

package/dist/trash.d.ts

@@ -0,0 +1,5 @@
+export type MovePathToTrashOptions = {
+    allowedRoots?: Iterable<string>;
+};
+export declare function movePathToTrash(targetPath: string, options?: MovePathToTrashOptions): Promise<string>;
+//# sourceMappingURL=trash.d.ts.map

package/dist/trash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AA4HF,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,MAAM,CAAC,CAcjB"}

package/dist/trash.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const TRASH_DESTINATION_COLLISION_CODES = new Set(["EEXIST", "ENOTEMPTY", "ERR_FS_CP_EEXIST"]);
+const TRASH_DESTINATION_RETRY_LIMIT = 4;
+function getFsErrorCode(error) {
+    if (!error || typeof error !== "object" || !("code" in error)) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function isTrashDestinationCollision(error) {
+    const code = getFsErrorCode(error);
+    return Boolean(code && TRASH_DESTINATION_COLLISION_CODES.has(code));
+}
+function isSameOrChildPath(candidate, parent) {
+    return candidate === parent || candidate.startsWith(`${parent}${path.sep}`);
+}
+function resolveAllowedTrashRoots(allowedRoots) {
+    const roots = [...(allowedRoots ?? [os.homedir(), os.tmpdir()])].map((root) => {
+        try {
+            return path.resolve(fs.realpathSync.native(root));
+        }
+        catch {
+            return path.resolve(root);
+        }
+    });
+    return [...new Set(roots)];
+}
+function assertAllowedTrashTarget(targetPath, allowedRoots) {
+    let resolvedTargetPath = path.resolve(targetPath);
+    try {
+        resolvedTargetPath = path.resolve(fs.realpathSync.native(targetPath));
+    }
+    catch {
+        // The subsequent move will surface missing or inaccessible targets.
+    }
+    const isAllowed = resolveAllowedTrashRoots(allowedRoots).some((root) => resolvedTargetPath !== root && isSameOrChildPath(resolvedTargetPath, root));
+    if (!isAllowed) {
+        throw new Error(`Refusing to trash path outside allowed roots: ${targetPath}`);
+    }
+}
+function resolveTrashDir() {
+    const homeDir = os.homedir();
+    const trashDir = path.join(homeDir, ".Trash");
+    fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
+    const trashDirStat = fs.lstatSync(trashDir);
+    if (!trashDirStat.isDirectory() || trashDirStat.isSymbolicLink()) {
+        throw new Error(`Refusing to use non-directory/symlink trash directory: ${trashDir}`);
+    }
+    const realHome = path.resolve(fs.realpathSync.native(homeDir));
+    const resolvedTrashDir = path.resolve(fs.realpathSync.native(trashDir));
+    if (resolvedTrashDir === realHome || !isSameOrChildPath(resolvedTrashDir, realHome)) {
+        throw new Error(`Trash directory escaped home directory: ${trashDir}`);
+    }
+    return resolvedTrashDir;
+}
+function trashBaseName(targetPath) {
+    const resolvedTargetPath = path.resolve(targetPath);
+    if (resolvedTargetPath === path.parse(resolvedTargetPath).root) {
+        throw new Error(`Refusing to trash root path: ${targetPath}`);
+    }
+    const base = path.basename(resolvedTargetPath).replace(/[\\/]+/g, "");
+    if (!base) {
+        throw new Error(`Unable to derive safe trash basename for: ${targetPath}`);
+    }
+    return base;
+}
+function resolveContainedPath(root, leaf) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedPath = path.resolve(resolvedRoot, leaf);
+    if (!isSameOrChildPath(resolvedPath, resolvedRoot) || resolvedPath === resolvedRoot) {
+        throw new Error(`Trash destination escaped trash directory: ${resolvedPath}`);
+    }
+    return resolvedPath;
+}
+function reserveTrashDestination(trashDir, base, timestamp) {
+    const containerPrefix = resolveContainedPath(trashDir, `${base}-${timestamp}-`);
+    const container = fs.mkdtempSync(containerPrefix);
+    const resolvedContainer = path.resolve(container);
+    const resolvedTrashDir = path.resolve(trashDir);
+    if (resolvedContainer === resolvedTrashDir ||
+        !isSameOrChildPath(resolvedContainer, resolvedTrashDir)) {
+        throw new Error(`Trash destination escaped trash directory: ${container}`);
+    }
+    return resolveContainedPath(container, base);
+}
+function movePathToDestination(targetPath, dest) {
+    try {
+        fs.renameSync(targetPath, dest);
+        return true;
+    }
+    catch (error) {
+        if (getFsErrorCode(error) !== "EXDEV") {
+            if (isTrashDestinationCollision(error)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    try {
+        fs.cpSync(targetPath, dest, { recursive: true, force: false, errorOnExist: true });
+        fs.rmSync(targetPath, { recursive: true, force: false });
+        return true;
+    }
+    catch (error) {
+        if (isTrashDestinationCollision(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function movePathToTrash(targetPath, options = {}) {
+    // Avoid resolving external trash helpers through the service PATH during cleanup.
+    const base = trashBaseName(targetPath);
+    assertAllowedTrashTarget(targetPath, options.allowedRoots);
+    const trashDir = resolveTrashDir();
+    const timestamp = Date.now();
+    for (let attempt = 0; attempt < TRASH_DESTINATION_RETRY_LIMIT; attempt += 1) {
+        const dest = reserveTrashDestination(trashDir, base, timestamp);
+        if (movePathToDestination(targetPath, dest)) {
+            return dest;
+        }
+    }
+    throw new Error(`Unable to choose a unique trash destination for ${targetPath}`);
+}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export type FastPathMode = "auto" | "never" | "require";
+export type SafeEncoding = BufferEncoding | null;
+export type PathStat = {
+    dev: number;
+    gid: number;
+    ino: number;
+    isDirectory: boolean;
+    isFile: boolean;
+    isSymbolicLink: boolean;
+    mode: number;
+    mtimeMs: number;
+    nlink: number;
+    size: number;
+    uid: number;
+};
+export type DirEntry = PathStat & {
+    name: string;
+};
+export type BasePathOptions = {
+    rootDir: string;
+    relativePath: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,IAAI,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/walk.d.ts

@@ -0,0 +1,26 @@
+import fsSync from "node:fs";
+export type WalkEntryKind = "file" | "directory" | "symlink" | "other";
+export type WalkSymlinkPolicy = "skip" | "follow" | "include";
+export type WalkDirectoryEntry = {
+    name: string;
+    path: string;
+    relativePath: string;
+    depth: number;
+    kind: WalkEntryKind;
+    dirent: fsSync.Dirent;
+};
+export type WalkDirectoryOptions = {
+    maxDepth?: number;
+    maxEntries?: number;
+    symlinks?: WalkSymlinkPolicy;
+    include?: (entry: WalkDirectoryEntry) => boolean;
+    descend?: (entry: WalkDirectoryEntry) => boolean;
+};
+export type WalkDirectoryResult = {
+    entries: WalkDirectoryEntry[];
+    scannedEntryCount: number;
+    truncated: boolean;
+};
+export declare function walkDirectorySync(rootDir: string, options?: WalkDirectoryOptions): WalkDirectoryResult;
+export declare function walkDirectory(rootDir: string, options?: WalkDirectoryOptions): Promise<WalkDirectoryResult>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAI7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AA8DF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAiDrB;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAiD9B"}

package/dist/walk.js

@@ -0,0 +1,169 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+function kindForDirent(dirent) {
+    if (dirent.isDirectory())
+        return "directory";
+    if (dirent.isFile())
+        return "file";
+    if (dirent.isSymbolicLink())
+        return "symlink";
+    return "other";
+}
+function shouldStop(result, options) {
+    return options.maxEntries !== undefined && result.scannedEntryCount >= Math.max(0, options.maxEntries);
+}
+function buildEntry(params) {
+    const fullPath = path.join(params.dir, params.dirent.name);
+    const relativePath = path.relative(params.rootDir, fullPath) || params.dirent.name;
+    return {
+        name: params.dirent.name,
+        path: fullPath,
+        relativePath,
+        depth: params.depth,
+        kind: params.kind ?? kindForDirent(params.dirent),
+        dirent: params.dirent,
+    };
+}
+function resolveSyncKind(fullPath, dirent, symlinks) {
+    const kind = kindForDirent(dirent);
+    if (kind !== "symlink")
+        return kind;
+    if (symlinks === "skip")
+        return null;
+    if (symlinks === "include")
+        return "symlink";
+    try {
+        const stat = fsSync.statSync(fullPath);
+        if (stat.isDirectory())
+            return "directory";
+        if (stat.isFile())
+            return "file";
+    }
+    catch {
+        return null;
+    }
+    return "other";
+}
+async function resolveAsyncKind(fullPath, dirent, symlinks) {
+    const kind = kindForDirent(dirent);
+    if (kind !== "symlink")
+        return kind;
+    if (symlinks === "skip")
+        return null;
+    if (symlinks === "include")
+        return "symlink";
+    try {
+        const stat = await fs.stat(fullPath);
+        if (stat.isDirectory())
+            return "directory";
+        if (stat.isFile())
+            return "file";
+    }
+    catch {
+        return null;
+    }
+    return "other";
+}
+export function walkDirectorySync(rootDir, options = {}) {
+    const root = path.resolve(rootDir);
+    const symlinks = options.symlinks ?? "skip";
+    const result = { entries: [], scannedEntryCount: 0, truncated: false };
+    const visitedDirs = new Set();
+    function visit(dir, depth) {
+        if (options.maxDepth !== undefined && depth > options.maxDepth)
+            return;
+        let realDir;
+        try {
+            realDir = fsSync.realpathSync(dir);
+        }
+        catch {
+            return;
+        }
+        if (visitedDirs.has(realDir))
+            return;
+        visitedDirs.add(realDir);
+        let entries;
+        try {
+            entries = fsSync.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const dirent of entries) {
+            if (shouldStop(result, options)) {
+                result.truncated = true;
+                return;
+            }
+            result.scannedEntryCount += 1;
+            const fullPath = path.join(dir, dirent.name);
+            const kind = resolveSyncKind(fullPath, dirent, symlinks);
+            if (!kind)
+                continue;
+            const entry = buildEntry({ rootDir: root, dir, dirent, depth, kind });
+            if (options.include?.(entry) ?? true) {
+                result.entries.push(entry);
+            }
+            if (kind === "directory" &&
+                (options.maxDepth === undefined || depth < options.maxDepth) &&
+                (options.descend?.(entry) ?? true)) {
+                visit(fullPath, depth + 1);
+                if (result.truncated)
+                    return;
+            }
+        }
+    }
+    visit(root, 1);
+    return result;
+}
+export async function walkDirectory(rootDir, options = {}) {
+    const root = path.resolve(rootDir);
+    const symlinks = options.symlinks ?? "skip";
+    const result = { entries: [], scannedEntryCount: 0, truncated: false };
+    const visitedDirs = new Set();
+    async function visit(dir, depth) {
+        if (options.maxDepth !== undefined && depth > options.maxDepth)
+            return;
+        let realDir;
+        try {
+            realDir = await fs.realpath(dir);
+        }
+        catch {
+            return;
+        }
+        if (visitedDirs.has(realDir))
+            return;
+        visitedDirs.add(realDir);
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const dirent of entries) {
+            if (shouldStop(result, options)) {
+                result.truncated = true;
+                return;
+            }
+            result.scannedEntryCount += 1;
+            const fullPath = path.join(dir, dirent.name);
+            const kind = await resolveAsyncKind(fullPath, dirent, symlinks);
+            if (!kind)
+                continue;
+            const entry = buildEntry({ rootDir: root, dir, dirent, depth, kind });
+            if (options.include?.(entry) ?? true) {
+                result.entries.push(entry);
+            }
+            if (kind === "directory" &&
+                (options.maxDepth === undefined || depth < options.maxDepth) &&
+                (options.descend?.(entry) ?? true)) {
+                await visit(fullPath, depth + 1);
+                if (result.truncated)
+                    return;
+            }
+        }
+    }
+    await visit(root, 1);
+    return result;
+}

package/dist/write-queue.d.ts

@@ -0,0 +1,2 @@
+export declare function serializePathWrite<T>(key: string, run: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=write-queue.d.ts.map

package/dist/write-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-queue.d.ts","sourceRoot":"","sources":["../src/write-queue.ts"],"names":[],"mappings":"AAEA,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkB1F"}

package/dist/write-queue.js

@@ -0,0 +1,18 @@
+const writeQueues = new Map();
+export async function serializePathWrite(key, run) {
+    const previous = writeQueues.get(key) ?? Promise.resolve();
+    const task = (async () => {
+        await previous.catch(() => undefined);
+        return await run();
+    })();
+    const done = task.then(() => undefined, () => undefined);
+    writeQueues.set(key, done);
+    try {
+        return await task;
+    }
+    finally {
+        if (writeQueues.get(key) === done) {
+            writeQueues.delete(key);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@openclaw/fs-safe",
+  "version": "0.1.0",
+  "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openclaw/fs-safe.git"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./root": {
+      "types": "./dist/root.d.ts",
+      "default": "./dist/root.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./path": {
+      "types": "./dist/path.d.ts",
+      "default": "./dist/path.js"
+    },
+    "./advanced": {
+      "types": "./dist/advanced.d.ts",
+      "default": "./dist/advanced.js"
+    },
+    "./json": {
+      "types": "./dist/json.d.ts",
+      "default": "./dist/json.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "default": "./dist/store.js"
+    },
+    "./secret": {
+      "types": "./dist/secret.d.ts",
+      "default": "./dist/secret.js"
+    },
+    "./permissions": {
+      "types": "./dist/permissions-public.d.ts",
+      "default": "./dist/permissions-public.js"
+    },
+    "./secure-file": {
+      "types": "./dist/secure-file.d.ts",
+      "default": "./dist/secure-file.js"
+    },
+    "./file-lock": {
+      "types": "./dist/file-lock.d.ts",
+      "default": "./dist/file-lock.js"
+    },
+    "./walk": {
+      "types": "./dist/walk.d.ts",
+      "default": "./dist/walk.js"
+    },
+    "./temp": {
+      "types": "./dist/temp.d.ts",
+      "default": "./dist/temp.js"
+    },
+    "./atomic": {
+      "types": "./dist/atomic.d.ts",
+      "default": "./dist/atomic.js"
+    },
+    "./archive": {
+      "types": "./dist/archive.d.ts",
+      "default": "./dist/archive.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./test-hooks": {
+      "types": "./dist/test-hooks.d.ts",
+      "default": "./dist/test-hooks.js"
+    }
+  },
+  "scripts": {
+    "benchmark": "node scripts/benchmark.mjs",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "node scripts/prepack-build.mjs",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "check": "pnpm build && pnpm test",
+    "docs:site": "node scripts/build-docs-site.mjs"
+  },
+  "optionalDependencies": {
+    "jszip": "^3.10.1",
+    "tar": "7.5.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.19",
+    "@vitest/coverage-v8": "3.2.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  },
+  "engines": {
+    "node": ">=20.11"
+  }
+}