@struktoai/mirage-node 0.0.7-alpha.2 → 0.0.7

package/dist/runtime/js/host/fs.js

@@ -0,0 +1,978 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { Buffer } from 'node:buffer';
+import { constants } from 'node:fs';
+import { createRequire } from 'node:module';
+import { posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { classify } from '@struktoai/mirage-core/errors/classify';
+import { ebadf, einval, isMissingPath } from '@struktoai/mirage-core/errors/fs';
+import { posixErrno, posixPhrase } from '@struktoai/mirage-core/errors/posix';
+import { workspaceBridge } from '@struktoai/mirage-core/runtime/binding';
+import { RuntimeFiles } from '@struktoai/mirage-core/runtime/files';
+import { posixStat } from '@struktoai/mirage-core/runtime/stat';
+import { PrefixResolver } from '@struktoai/mirage-core/runtime/resolver';
+import { MountMode } from '@struktoai/mirage-core/types';
+import { entryName } from '@struktoai/mirage-core/utils/remnants';
+import { DESCRIPTOR_CALLS, LISTENED_CALLS, PATH_ARGS, REFUSED_CALLS, ROUTED_CALLS, } from "./constants.js";
+import { Descriptors, openFlags, readAt, readOn } from "./descriptors.js";
+const fs = createRequire(import.meta.url)('node:fs');
+const { S_IFMT, S_IFREG, S_IFDIR, S_IFCHR, S_IFLNK, W_OK, X_OK, COPYFILE_EXCL } = constants;
+/** `path` as a string a mount could serve, or null: a descriptor and a
+ * Buffer are host spellings no mount uses. */
+function spelled(path) {
+    if (typeof path === 'string')
+        return path;
+    if (path instanceof URL && path.protocol === 'file:')
+        return fileURLToPath(path);
+    return null;
+}
+/** A stamp in nanoseconds, as node's BigIntStats spells one. */
+function ns(date) {
+    return BigInt(date.getTime()) * 1000000n;
+}
+/** A refusal spelled the way node's own fs spells an error. */
+function refusal(condition, syscall, path) {
+    const err = new Error(`${condition}: ${posixPhrase(condition).toLowerCase()}, ${syscall} '${path}'`);
+    err.code = condition;
+    err.errno = -posixErrno(condition);
+    err.syscall = syscall;
+    err.path = path;
+    return err;
+}
+function fsError(error, syscall, path) {
+    const condition = classify(error);
+    if (condition === null)
+        return error instanceof Error ? error : new Error(String(error), { cause: error });
+    const converted = refusal(condition, syscall, path ?? '');
+    if (path === undefined) {
+        converted.message = `${condition}: ${posixPhrase(condition).toLowerCase()}, ${syscall}`;
+        delete converted.path;
+    }
+    return Object.assign(converted, { cause: error });
+}
+function syncRefusal(name, path) {
+    const err = refusal('ENOTSUP', name, path);
+    err.message = `mirage.patchNodeFs: sync fs methods not supported on a mounted path; use fs.promises.${name.replace(/Sync$/, '')} ('${path}')`;
+    return err;
+}
+/** An options argument's fields; node takes null, a number (a mode)
+ * and a string (an encoding) there too, which name none of them. */
+function fieldsOf(options) {
+    return typeof options === 'object' && options !== null ? options : {};
+}
+function encodingOf(options) {
+    if (typeof options === 'string')
+        return options;
+    return (fieldsOf(options).encoding ?? undefined);
+}
+function bytesOf(data, options) {
+    if (typeof data === 'string')
+        return Buffer.from(data, encodingOf(options) ?? 'utf8');
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    throw new TypeError('mirage.patchNodeFs: data must be a string or an ArrayBufferView');
+}
+/** An async iterator whose first read throws `err`: the shape node's
+ * `fs.promises.glob` and `watch` answer in, failures included. */
+function refusedIterator(err) {
+    return {
+        next: () => Promise.reject(err),
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+    };
+}
+/** A time argument (seconds, a numeric string, a Date) as the ISO stamp
+ * setattr stores. */
+function stampOf(time) {
+    const ms = time instanceof Date ? time.getTime() : Number(time) * 1000;
+    return new Date(ms).toISOString();
+}
+/** Refuse an integer argument outside `[min, max]` as node does. */
+function checkRange(name, value, max, min = 0) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw Object.assign(new RangeError(`The value of "${name}" is out of range. It must be >= ${String(min)} && <= ${String(max)}. Received ${String(value)}`), { code: 'ERR_OUT_OF_RANGE' });
+    }
+}
+/** A read's buffer, where in it to put the bytes, how many to read and
+ * from where, out of any of node's read spellings: `(buffer, offset,
+ * length, position)`, `(buffer, options)`, `(options)` or nothing, then
+ * the caller's own buffer object, which node hands back. A null position
+ * reads at the descriptor's position and advances it. */
+function readArgs(args) {
+    const [first, ...rest] = args;
+    const view = ArrayBuffer.isView(first);
+    const options = fieldsOf((view ? rest[0] : first));
+    const given = view ? first : options.buffer;
+    const original = ArrayBuffer.isView(given) ? given : Buffer.alloc(16384);
+    const buffer = new Uint8Array(original.buffer, original.byteOffset, original.byteLength);
+    const positional = view && typeof rest[0] !== 'object';
+    const offset = Number((positional ? rest[0] : options.offset) ?? 0);
+    const length = Number((positional ? rest[1] : options.length) ?? buffer.byteLength - offset);
+    const position = (positional ? rest[2] : options.position);
+    checkRange('offset', offset, buffer.length);
+    checkRange('length', length, buffer.length - offset);
+    if (typeof position === 'number' || typeof position === 'bigint')
+        checkRange('position', Number(position), Number.MAX_SAFE_INTEGER, -1);
+    return [buffer, offset, length, positionOf(position), original];
+}
+/** A write's bytes and where they go, out of node's write spellings:
+ * `(buffer, offset, length, position)`, `(buffer, options)` and
+ * `(string, position, encoding)`. */
+function writeArgs(data, rest) {
+    if (typeof data === 'string') {
+        const encoding = (typeof rest[1] === 'string' ? rest[1] : 'utf8');
+        return [Buffer.from(data, encoding), positionOf(rest[0])];
+    }
+    const bytes = bytesOf(data, null);
+    const options = typeof rest[0] === 'object' ? fieldsOf(rest[0]) : null;
+    const offset = Number((options === null ? rest[0] : options.offset) ?? 0);
+    const length = Number((options === null ? rest[1] : options.length) ?? bytes.byteLength - offset);
+    const position = (options === null ? rest[2] : options.position);
+    return [bytes.subarray(offset, offset + length), positionOf(position)];
+}
+// The routed calls that take a descriptor or a FileHandle in the path
+// slot as well as a path.
+const FILE_CALLS = new Set(['appendFile', 'readFile', 'writeFile']);
+/** Answer a node callback from a promise of what follows its error slot. */
+function answer(work, done) {
+    work.then((values) => {
+        done(null, ...values);
+    }, (err) => {
+        done(err);
+    });
+}
+/** A position argument as an offset, or null for "at the position": node
+ * reads anything but a number there (`fs.write(fd, 'x', 'utf8', cb)`'s
+ * encoding included) and a negative one as the descriptor's position. */
+function positionOf(position) {
+    if (typeof position !== 'number' && typeof position !== 'bigint')
+        return null;
+    const at = Number(position);
+    return Number.isNaN(at) || at < 0 ? null : at;
+}
+/**
+ * The `FileHandle` `fs.promises.open` answers a mounted path with: node's
+ * own methods over a descriptor of the patch's, whose writes land at
+ * `close` or `sync`. It holds the descriptor it opened, not just its
+ * number: once that is closed, here or through `fs.close`, every call is
+ * EBADF, even after a later open takes the number.
+ */
+class MountedFileHandle {
+    host;
+    fd;
+    desc;
+    closed = false;
+    constructor(host, fd, desc) {
+        this.host = host;
+        this.fd = fd;
+        this.desc = desc;
+    }
+    /** Whether the descriptor this handle opened is still open. */
+    live() {
+        return (!this.closed && this.desc !== undefined && this.host.descriptors.get(this.fd) === this.desc);
+    }
+    /** A descriptor call on this handle's descriptor; EBADF once it closed. */
+    call(name, ...args) {
+        if (!this.live())
+            return Promise.reject(fsError(ebadf(String(this.fd)), name));
+        return this.host.descriptorCall(name, [this.fd, ...args]);
+    }
+    async read(...args) {
+        const [bytesRead, buffer] = await this.call('read', ...args);
+        return { bytesRead: bytesRead, buffer };
+    }
+    async readv(buffers, position) {
+        const [bytesRead] = await this.call('readv', buffers, position);
+        return { bytesRead: bytesRead, buffers };
+    }
+    async write(...args) {
+        const [bytesWritten, buffer] = await this.call('write', ...args);
+        return { bytesWritten: bytesWritten, buffer };
+    }
+    async writev(buffers, position) {
+        const [bytesWritten] = await this.call('writev', buffers, position);
+        return { bytesWritten: bytesWritten, buffers };
+    }
+    readFile(options) {
+        return this.host.fileCall('readFile', this, [options]);
+    }
+    async writeFile(data, options) {
+        await this.host.fileCall('writeFile', this, [data, options]);
+    }
+    appendFile(data, options) {
+        return this.writeFile(data, options);
+    }
+    async stat(options) {
+        return (await this.call('fstat', options))[0];
+    }
+    async truncate(len = 0) {
+        await this.call('ftruncate', len);
+    }
+    async sync() {
+        await this.call('fsync');
+    }
+    async datasync() {
+        await this.call('fdatasync');
+    }
+    async chmod(mode) {
+        await this.call('fchmod', mode);
+    }
+    async chown(uid, gid) {
+        await this.call('fchown', uid, gid);
+    }
+    async utimes(atime, mtime) {
+        await this.call('futimes', atime, mtime);
+    }
+    async close() {
+        const live = this.live();
+        this.closed = true;
+        if (live)
+            await this.host.descriptorCall('close', [this.fd]);
+    }
+    [Symbol.asyncDispose]() {
+        return this.close();
+    }
+    // node's streams call back through `fs.read`, `fs.write` and `fs.close`,
+    // which the patch answers for this descriptor.
+    createReadStream(options) {
+        if (!this.live())
+            throw ebadf(String(this.fd));
+        return fs.createReadStream(null, { ...fieldsOf(options), fd: this.fd });
+    }
+    createWriteStream(options) {
+        if (!this.live())
+            throw ebadf(String(this.fd));
+        return fs.createWriteStream(null, { ...fieldsOf(options), fd: this.fd });
+    }
+}
+/**
+ * Every routed fs call, answered on a mount: python's `HostFs` for
+ * node. One method per name in `ROUTED_CALLS`, each taking the call's
+ * own arguments with its path arguments already spelled as strings. The
+ * calls ride `RuntimeFiles` over `ws.vfs.dispatch`, so they run as the
+ * facade's session and land on `ws.vfs.records`. A call with one end on
+ * a mount and the other on the host reaches the host through `native`,
+ * node's own functions as they were before the patch.
+ */
+class HostFs {
+    ws;
+    native;
+    files;
+    // The descriptors `open` hands out for mounted paths (descriptors.ts).
+    descriptors;
+    // One stamp for the patch's life, the choice python's HostFs makes: a
+    // backend that reports no mtime would otherwise answer a new time on
+    // every stat, and "did it change?" heuristics fire on that.
+    born = Date.now();
+    constructor(ws, native) {
+        this.ws = ws;
+        this.native = native;
+        this.files = new RuntimeFiles(workspaceBridge(async (name, path, args, kwargs) => {
+            try {
+                const [value] = await ws.vfs.dispatch(name, path, args, kwargs);
+                return value;
+            }
+            catch (err) {
+                if (classify(err) !== null)
+                    throw err;
+                // An op that fails with no condition (an upstream 502 a REST
+                // mount throws as it came) answers EIO, the kernel's word for a
+                // device that failed, as a guest's file adapter does; the original
+                // rides along as the cause.
+                throw Object.assign(refusal('EIO', name, path), { cause: err });
+            }
+        }), new PrefixResolver(() => [], (directory) => ws.namespace.linkNamesUnder(directory)));
+        this.descriptors = new Descriptors(this.files, native, ws.namespace);
+    }
+    /** Whether `path` is under a mount the patch answers for. The synthetic
+     * root anchor matches every path but backs no files, so a path only it
+     * catches stays on the host; a mount the caller put at `/` is honored.
+     * A relative path names the process's working directory, which stays
+     * node's whatever is mounted, and a `Buffer` spelling is the host's,
+     * as a bytes path is on the python entry point. */
+    mounted(path) {
+        if (typeof path !== 'string' || !path.startsWith('/'))
+            return false;
+        const mount = this.ws.registry.tryMountFor(path);
+        if (mount === null)
+            return false;
+        return !(this.ws.syntheticRoot && mount === this.ws.registry.rootMount);
+    }
+    statsOf(path, st, options, unlinked = false) {
+        // The stat every runtime shares; an owner the row lacks is this
+        // process's own.
+        const posix = posixStat(st, path, this.ws.registry.tryMountFor(path)?.prefix ?? '/', {
+            uid: process.getuid?.() ?? 0,
+            gid: process.getgid?.() ?? 0,
+            unknownMs: this.born,
+        });
+        const kind = posix.mode & S_IFMT;
+        const mtime = new Date(posix.mtimeMs);
+        const atime = new Date(posix.atimeMs);
+        const kinds = {
+            isFile: () => kind === S_IFREG,
+            isDirectory: () => kind === S_IFDIR,
+            isBlockDevice: () => false,
+            isCharacterDevice: () => kind === S_IFCHR,
+            isSymbolicLink: () => kind === S_IFLNK,
+            isFIFO: () => false,
+            isSocket: () => false,
+        };
+        const dates = { atime, mtime, ctime: mtime, birthtime: mtime };
+        const fields = {
+            dev: posix.dev,
+            ino: posix.ino,
+            mode: posix.mode,
+            nlink: unlinked ? 0 : posix.nlink,
+            uid: posix.uid,
+            gid: posix.gid,
+            rdev: posix.rdev,
+            size: posix.size,
+            blksize: posix.blksize,
+            blocks: posix.blocks,
+            atimeMs: posix.atimeMs,
+            mtimeMs: posix.mtimeMs,
+            ctimeMs: posix.ctimeMs,
+            birthtimeMs: posix.mtimeMs,
+        };
+        if (fieldsOf(options).bigint !== true)
+            return { ...kinds, ...fields, ...dates };
+        // node's BigIntStats: every number a bigint, plus the stamps in ns.
+        const big = Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, BigInt(Math.trunc(v))]));
+        return {
+            ...kinds,
+            ...big,
+            atimeNs: ns(atime),
+            mtimeNs: ns(mtime),
+            ctimeNs: ns(mtime),
+            birthtimeNs: ns(mtime),
+            ...dates,
+        };
+    }
+    direntOf(directory, row) {
+        const kind = row.isLink === true ? S_IFLNK : row.isDir ? S_IFDIR : (row.mode ?? 0) & S_IFMT;
+        return {
+            name: entryName(row.path),
+            parentPath: directory,
+            path: directory,
+            isFile: () => kind === S_IFREG,
+            isDirectory: () => kind === S_IFDIR,
+            isBlockDevice: () => false,
+            isCharacterDevice: () => kind === S_IFCHR,
+            isSymbolicLink: () => kind === S_IFLNK,
+            isFIFO: () => false,
+            isSocket: () => false,
+        };
+    }
+    nativeCall(name, ...args) {
+        return this.native.promises[name](...args);
+    }
+    async access(path, mode = 0) {
+        const st = await this.files.stat(path);
+        // Write is the mount's mode, mirage's access control; a session's own
+        // narrower grant answers when the write happens, as POSIX leaves
+        // access(2) advisory. Execute is the one question the bits answer.
+        if (mode & W_OK && this.ws.registry.tryMountFor(path)?.mode === MountMode.READ) {
+            throw refusal('EACCES', 'access', path);
+        }
+        if (mode & X_OK && (st.mode & 0o111) === 0)
+            throw refusal('EACCES', 'access', path);
+    }
+    async appendFile(path, data, options) {
+        await this.put(path, data, options, 'a');
+    }
+    async chmod(path, mode) {
+        await this.files.setattr(path, { mode: typeof mode === 'string' ? parseInt(mode, 8) : mode });
+    }
+    async lchmod(path, mode) {
+        const bits = typeof mode === 'string' ? parseInt(mode, 8) : mode;
+        await this.files.setattr(path, { mode: bits, nofollow: true });
+    }
+    async chown(path, uid, gid, nofollow = false) {
+        // -1 is POSIX's "leave this one alone"; passing it on would store it.
+        const attrs = nofollow ? { nofollow: true } : {};
+        if (uid !== -1)
+            attrs.uid = uid;
+        if (gid !== -1)
+            attrs.gid = gid;
+        await this.files.setattr(path, attrs);
+    }
+    async lchown(path, uid, gid) {
+        await this.chown(path, uid, gid, true);
+    }
+    async copyFile(src, dst, mode = 0) {
+        // The stored bytes, as cp copies them: a rendering is what a read
+        // shows, not what the file holds.
+        const data = this.mounted(src)
+            ? await this.files.read(src, { raw: true })
+            : await this.nativeCall('readFile', src);
+        const exclusive = (mode & COPYFILE_EXCL) !== 0;
+        if (!this.mounted(dst)) {
+            // O_EXCL on the host: the write itself refuses a name already
+            // there, a dangling link included.
+            await this.nativeCall('writeFile', dst, data, exclusive ? { flag: 'wx' } : undefined);
+            return;
+        }
+        // A mount has no exclusive create, so the name is looked up as `wx`
+        // looks it up, the link itself rather than its target.
+        if (exclusive && (await this.files.statOrNull(dst, true)) !== null) {
+            throw refusal('EEXIST', 'copyfile', dst);
+        }
+        await this.files.write(dst, data);
+    }
+    async exists(path) {
+        if (!this.mounted(path)) {
+            return this.nativeCall('access', path).then(() => true, (err) => {
+                console.debug(`exists: ${String(err)}`);
+                return false;
+            });
+        }
+        // exists answers a boolean for any failure, as node's does.
+        try {
+            return (await this.files.statOrNull(path)) !== null;
+        }
+        catch (err) {
+            console.debug(`exists: ${path}: ${String(err)}`);
+            return false;
+        }
+    }
+    async lstat(path, options) {
+        return this.statsOf(path, await this.files.stat(path, true), options);
+    }
+    async lutimes(path, atime, mtime) {
+        await this.files.setattr(path, { atime: stampOf(atime), mtime: stampOf(mtime), nofollow: true });
+    }
+    async mkdir(path, options) {
+        if (fieldsOf(options).recursive !== true) {
+            await this.files.mkdir(path);
+            return undefined;
+        }
+        // Each missing ancestor in turn, stopping at the mount root, as
+        // python's makedirs does: a backend's mkdir is one level, and the
+        // mount root is the deployment's own and refused (EBUSY).
+        const root = (this.ws.registry.tryMountFor(path)?.prefix ?? '/').replace(/\/$/, '');
+        const missing = [];
+        for (let probe = path.replace(/\/$/, ''); probe !== '' && probe !== '/' && probe !== root;) {
+            const st = await this.files.statOrNull(probe);
+            if (st !== null) {
+                if (!st.isDir)
+                    throw refusal('ENOTDIR', 'mkdir', probe);
+                break;
+            }
+            missing.push(probe);
+            probe = posix.dirname(probe);
+        }
+        // node answers the first directory it made, undefined for none.
+        missing.reverse();
+        for (const dir of missing)
+            await this.files.mkdir(dir);
+        return missing[0];
+    }
+    async readFile(path, options) {
+        const bytes = Buffer.from(await this.files.read(path));
+        const encoding = encodingOf(options);
+        return encoding === undefined ? bytes : bytes.toString(encoding);
+    }
+    async readdir(path, options) {
+        const typed = fieldsOf(options).withFileTypes === true;
+        const recursive = fieldsOf(options).recursive === true;
+        const out = [];
+        const walk = async (directory, prefix) => {
+            for (const row of await this.files.readdir(directory, typed || recursive)) {
+                const name = entryName(row.path);
+                out.push(typed ? this.direntOf(directory, row) : prefix + name);
+                if (recursive && row.isDir && row.isLink !== true) {
+                    await walk(posix.join(directory, name), `${prefix}${name}/`);
+                }
+            }
+        };
+        await walk(path, '');
+        return out;
+    }
+    async readlink(path, options) {
+        const target = await this.files.readlink(path);
+        const encoding = encodingOf(options);
+        if (encoding === undefined || encoding === 'utf8')
+            return target;
+        const bytes = Buffer.from(target);
+        return encoding === 'buffer' ? bytes : bytes.toString(encoding);
+    }
+    async rename(src, dst) {
+        // A move between a mount and the host is EXDEV, the kernel's answer
+        // for two filesystems and the errno a mover retries as copy + delete.
+        if (!this.mounted(src) || !this.mounted(dst))
+            throw refusal('EXDEV', 'rename', src);
+        // Both ends as the walk names them before the rename, which may move a
+        // link the walk takes. A rename onto its own name changes nothing, its
+        // descriptors included.
+        const from = this.descriptors.walked(src, false);
+        const to = this.descriptors.walked(dst, false);
+        const held = from === to ? [] : await this.descriptors.hold(dst);
+        await this.files.rename(src, dst);
+        this.descriptors.keep(held);
+        this.descriptors.moved(from, to);
+    }
+    /** Remove a file, the descriptors open on it keeping the bytes it had. */
+    async removeFile(path) {
+        const held = await this.descriptors.hold(path);
+        await this.files.unlink(path);
+        this.descriptors.keep(held);
+    }
+    async rm(path, options) {
+        const force = fieldsOf(options).force === true;
+        const recursive = fieldsOf(options).recursive === true;
+        // A mount root is refused however it is spelled (`/data/.`), before
+        // the stat a backend may answer for that spelling or not.
+        if (this.ws.registry.isMountRoot(posix.normalize(path)))
+            throw refusal('EBUSY', 'rm', path);
+        let st;
+        try {
+            st = await this.files.stat(path, true);
+        }
+        catch (err) {
+            if (!force || !isMissingPath(err))
+                throw err;
+            console.debug(`rm: ${path} is already gone: ${String(err)}`);
+            return;
+        }
+        if (!st.isDir) {
+            await this.removeFile(path);
+            return;
+        }
+        if (!recursive)
+            throw refusal('EISDIR', 'rm', path);
+        const doomed = [];
+        await this.plan(path, true, doomed, path, this.ws.namespace.follow(path));
+        // A name another writer removed since the plan is already gone, as
+        // node's own recursive rm counts it.
+        for (const [name, isDir, where] of doomed) {
+            this.held(posix.dirname(name), posix.dirname(where));
+            try {
+                if (isDir)
+                    await this.files.rmdir(name);
+                else
+                    await this.removeFile(name);
+            }
+            catch (err) {
+                if (!isMissingPath(err) || name === path)
+                    throw err;
+                console.debug(`rm: ${name} went before its turn: ${String(err)}`);
+            }
+        }
+    }
+    /** Every name under `path` onto `out`, children before their directory,
+     * each with where it resolved when planned. The whole tree is planned
+     * before anything goes, as the agent adapters plan it, so a mount root
+     * anywhere in it refuses the call with nothing removed. */
+    async plan(path, isDir, out, top, where) {
+        if (this.ws.registry.isMountRoot(posix.normalize(path)))
+            throw refusal('EBUSY', 'rm', path);
+        if (isDir) {
+            this.held(path, where);
+            let rows;
+            try {
+                rows = await this.files.readdir(path);
+            }
+            catch (err) {
+                if (!isMissingPath(err) || path === top)
+                    throw err;
+                console.debug(`rm: ${path} went while the tree was planned: ${String(err)}`);
+                return;
+            }
+            for (const row of rows) {
+                const name = entryName(row.path);
+                const isChildDir = row.isDir && row.isLink !== true;
+                await this.plan(posix.join(path, name), isChildDir, out, top, posix.join(where, name));
+            }
+        }
+        out.push([path, isDir, where]);
+    }
+    /** Refuse to act in `directory` once it resolves elsewhere than `where`,
+     * where the plan found it: swapped for a link, or under an ancestor
+     * that was, a name in it would reach the link's target. A name is all
+     * a mount gives, so this check stands in for the descriptor a host
+     * walk would hold. */
+    held(directory, where) {
+        if (posix.normalize(this.ws.namespace.follow(directory)) !== posix.normalize(where)) {
+            throw refusal('ELOOP', 'rm', directory);
+        }
+    }
+    async rmdir(path) {
+        // rmdir(2) on a mount point is EBUSY. A mount root is the
+        // deployment's own, which the shell's rm refuses the same way.
+        if (this.ws.registry.isMountRoot(posix.normalize(path))) {
+            throw refusal('EBUSY', 'rmdir', path);
+        }
+        await this.files.rmdir(path);
+    }
+    async stat(path, options) {
+        return this.statsOf(path, await this.files.stat(path), options);
+    }
+    async symlink(target, path) {
+        await this.files.symlink(path, String(target));
+    }
+    async truncate(path, length = 0) {
+        // truncate(2) names a file that is there; the op creates a missing
+        // one, as GNU truncate does without -c.
+        await this.files.stat(path);
+        await this.descriptors.landPath(path);
+        await this.files.truncate(path, length);
+    }
+    async unlink(path) {
+        await this.removeFile(path);
+    }
+    async utimes(path, atime, mtime) {
+        // Writes a descriptor still owes land first, or landing them at its
+        // close would stamp over the times set here.
+        await this.descriptors.landPath(path);
+        await this.files.setattr(path, { atime: stampOf(atime), mtime: stampOf(mtime) });
+    }
+    async writeFile(path, data, options) {
+        await this.put(path, data, options, 'w');
+    }
+    /** readFile, writeFile or appendFile given a mounted descriptor or
+     * FileHandle: from and at its position, as node's are on a descriptor. */
+    async fileCall(name, target, rest) {
+        if (target instanceof MountedFileHandle && !target.live())
+            throw ebadf(String(target.fd));
+        const fd = target instanceof MountedFileHandle ? target.fd : target;
+        if (name === 'readFile') {
+            const read = () => readOn(this.descriptors.file(fd, true, false), -1);
+            const bytes = Buffer.from(await this.descriptors.serial(fd, read));
+            const encoding = encodingOf(rest[0]);
+            return encoding === undefined ? bytes : bytes.toString(encoding);
+        }
+        await this.fdWrite(fd, bytesOf(rest[0], rest[1]), null);
+        return undefined;
+    }
+    /** A mounted path's `FileHandle`, as `fs.promises.open` answers. */
+    async open(path, flags) {
+        try {
+            const fd = await this.descriptors.open(path, openFlags(flags));
+            return new MountedFileHandle(this, fd, this.descriptors.get(fd));
+        }
+        catch (error) {
+            throw fsError(error, 'open', path);
+        }
+    }
+    /** A read into `buffer` at `offset`, at `position` or, when null, at the
+     * descriptor's own position, advancing it. The caller holds its queue. */
+    async readInto(fd, buffer, offset, length, position) {
+        const handle = this.descriptors.file(fd, true, false);
+        const bytes = position === null ? await readOn(handle, length) : await readAt(handle, position, length);
+        buffer.set(bytes, offset);
+        return bytes.byteLength;
+    }
+    /** A write through a mounted descriptor, in its turn on the descriptor. */
+    fdWrite(fd, bytes, position) {
+        return this.descriptors.serial(fd, () => {
+            const handle = this.descriptors.file(fd, false, true);
+            // Linux appends a positioned write on an O_APPEND descriptor,
+            // whatever the position, and leaves the position where it was.
+            if (position === null)
+                handle.write(bytes.slice());
+            else
+                handle.pwrite(handle.append ? handle.size : position, bytes.slice());
+            return Promise.resolve(bytes.byteLength);
+        });
+    }
+    /** A descriptor call on a mounted descriptor, answered with what node's
+     * callback gets after its error slot. */
+    async descriptorCall(name, args) {
+        try {
+            const fd = args[0];
+            const rest = args.slice(1);
+            const desc = this.descriptors.get(fd);
+            if (desc === undefined)
+                throw ebadf(String(fd));
+            switch (name) {
+                case 'read': {
+                    const [buffer, offset, length, position, original] = readArgs(rest);
+                    const read = () => this.readInto(fd, buffer, offset, length, position);
+                    return [await this.descriptors.serial(fd, read), original];
+                }
+                case 'write': {
+                    const [bytes, position] = writeArgs(rest[0], rest.slice(1));
+                    return [await this.fdWrite(fd, bytes, position), rest[0]];
+                }
+                case 'readv':
+                    return await this.descriptors.serial(fd, async () => {
+                        const buffers = rest[0];
+                        let at = positionOf(rest[1]);
+                        let total = 0;
+                        for (const buffer of buffers) {
+                            const got = await this.readInto(fd, buffer, 0, buffer.byteLength, at);
+                            total += got;
+                            if (at !== null)
+                                at += got;
+                            if (got < buffer.byteLength)
+                                break;
+                        }
+                        return [total, buffers];
+                    });
+                case 'writev': {
+                    const buffers = rest[0];
+                    const position = positionOf(rest[1]);
+                    const joined = Buffer.concat(buffers.map((b) => bytesOf(b, null)));
+                    return [await this.fdWrite(fd, joined, position), buffers];
+                }
+                case 'fstat': {
+                    const st = desc.kept !== null && desc.stat !== null ? desc.stat : await this.files.stat(desc.path);
+                    const size = desc.handle?.size ?? st.size;
+                    return [
+                        this.statsOf(desc.opened, { ...st, size }, rest[0], desc.kept !== null),
+                    ];
+                }
+                case 'ftruncate':
+                    if (!desc.mode.writable)
+                        throw einval(desc.path);
+                    await this.descriptors.serial(fd, () => {
+                        this.descriptors.file(fd, false, true).truncate(Math.max(0, Number(rest[0] ?? 0)));
+                        return Promise.resolve();
+                    });
+                    return [];
+                case 'fsync':
+                case 'fdatasync':
+                    await this.descriptors.serial(fd, () => this.descriptors.land(desc));
+                    return [];
+                case 'close':
+                    await this.descriptors.close(fd);
+                    return [];
+                case 'fchmod':
+                    await this.chmod(desc.path, rest[0]);
+                    return [];
+                case 'fchown':
+                    await this.chown(desc.path, rest[0], rest[1]);
+                    return [];
+                case 'futimes':
+                    await this.utimes(desc.path, rest[0], rest[1]);
+                    return [];
+                default:
+                    throw new TypeError(`mirage.patchNodeFs: ${name} is not a descriptor call`);
+            }
+        }
+        catch (error) {
+            throw fsError(error, name);
+        }
+    }
+    /** writeFile and appendFile, which differ only in the flag they default
+     * to. An exclusive flag (`wx`, `ax`) refuses a name already there
+     * before anything is written. */
+    async put(path, data, options, fallback) {
+        const given = fieldsOf(options).flag;
+        const flag = typeof given === 'string' ? given : fallback;
+        const bytes = bytesOf(data, options);
+        if (flag.includes('x') && (await this.files.statOrNull(path, true)) !== null) {
+            throw refusal('EEXIST', 'open', path);
+        }
+        // What descriptors on the file still owe lands first, so their older
+        // writes never land over this one.
+        await this.descriptors.landPath(path);
+        if (flag.startsWith('a'))
+            await this.files.append(path, bytes);
+        else
+            await this.files.write(path, bytes);
+    }
+}
+/**
+ * Point node's own `fs` at the workspace for every mounted path.
+ *
+ * Each name in `constants.ts` is swapped on the CommonJS `fs` object
+ * and on `fs.promises`, in all the spellings node has: a routed call
+ * goes through the workspace, a refused one answers its condition, and
+ * a sync spelling refuses a mounted path, since the workspace answers
+ * asynchronously. A path no mount owns reaches node's own function in
+ * every spelling, so the rest of the process keeps its filesystem. ESM
+ * named imports of `node:fs/promises` keep node's functions: an ES
+ * module binds them at link time, which is also why a node backend's
+ * own host I/O never routes back into the workspace.
+ *
+ * Returns a `restore()` that puts every swapped function back.
+ */
+export function patchNodeFs(ws) {
+    const native = { ...fs, promises: { ...fs.promises } };
+    const host = new HostFs(ws, native);
+    const swapped = [];
+    const swap = (target, name, make) => {
+        const original = target[name];
+        if (typeof original !== 'function')
+            return;
+        swapped.push([target, name, original]);
+        const wrapped = make(original);
+        // node hangs helpers off a few functions (`realpath.native`, the
+        // promisify hooks), and they stay: a named one is swapped the same
+        // way, a symbol one is node's and calls back through `fs`.
+        for (const key of Reflect.ownKeys(original)) {
+            if (key === 'length' || key === 'name' || key === 'prototype')
+                continue;
+            const helper = Reflect.get(original, key);
+            const own = typeof key === 'string' && typeof helper === 'function';
+            Reflect.set(wrapped, key, own ? make(helper) : helper);
+        }
+        target[name] = wrapped;
+    };
+    // The paths a call names. glob names one per pattern, a relative one
+    // under its `cwd`.
+    const namedPaths = (name, args) => {
+        if (name !== 'glob')
+            return (PATH_ARGS[name] ?? [0]).map((index) => spelled(args[index]));
+        const cwd = spelled(fieldsOf(args[1]).cwd);
+        const patterns = Array.isArray(args[0]) ? args[0] : [args[0]];
+        return patterns.map((pattern) => {
+            const path = spelled(pattern);
+            if (path === null || cwd === null || posix.isAbsolute(path))
+                return path;
+            return posix.join(cwd, path);
+        });
+    };
+    // The mounted path a call names, or null when every path it takes is
+    // the host's, which leaves the call to node.
+    const mountedIn = (name, args) => namedPaths(name, args).find((path) => host.mounted(path)) ?? null;
+    const spellPaths = (name, args) => {
+        const positions = PATH_ARGS[name] ?? [0];
+        return args.map((arg, index) => (positions.includes(index) ? (spelled(arg) ?? arg) : arg));
+    };
+    // readFile, writeFile and appendFile take a descriptor or a FileHandle
+    // where they take a path: a mounted one of the patch's is answered here.
+    const byDescriptor = (name, args) => FILE_CALLS.has(name) &&
+        (host.descriptors.get(args[0]) !== undefined || args[0] instanceof MountedFileHandle);
+    for (const name of ROUTED_CALLS) {
+        const route = (args) => host[name].call(host, ...spellPaths(name, args));
+        swap(fs.promises, name, (original) => (...args) => {
+            if (byDescriptor(name, args))
+                return host.fileCall(name, args[0], args.slice(1));
+            return mountedIn(name, args) === null ? original(...args) : route(args);
+        });
+        swap(fs, name, (original) => (...args) => {
+            const done = args.at(-1);
+            const rest = args.slice(0, -1);
+            if (typeof done === 'function' && byDescriptor(name, rest)) {
+                answer(host.fileCall(name, rest[0], rest.slice(1)).then((v) => (v === undefined ? [] : [v])), done);
+                return undefined;
+            }
+            if (typeof done !== 'function' || mountedIn(name, rest) === null)
+                return original(...args);
+            const callback = done;
+            // `exists` is the one callback without an error slot.
+            route(rest).then((value) => {
+                if (name === 'exists')
+                    callback(value);
+                else
+                    callback(null, value);
+            }, (err) => {
+                if (name === 'exists')
+                    callback(false);
+                else
+                    callback(err);
+            });
+            return undefined;
+        });
+        swap(fs, `${name}Sync`, (original) => (...args) => {
+            const desc = host.descriptors.get(args[0]);
+            if (desc !== undefined && FILE_CALLS.has(name))
+                throw syncRefusal(`${name}Sync`, desc.path);
+            const path = mountedIn(name, args);
+            if (path === null)
+                return original(...args);
+            // existsSync answers false where it cannot look, as node's does for
+            // any path whose stat fails; a mount's root is the one name it
+            // knows is there without asking.
+            if (name === 'exists')
+                return ws.registry.isMountRoot(path);
+            throw syncRefusal(`${name}Sync`, path);
+        });
+    }
+    // open hands a mounted path a descriptor of the patch's own, which the
+    // descriptor calls below answer for; the promise spelling a FileHandle.
+    swap(fs.promises, 'open', (original) => (...args) => {
+        const path = mountedIn('open', args);
+        return path === null ? original(...args) : host.open(path, args[1]);
+    });
+    swap(fs, 'open', (original) => (...args) => {
+        const done = args.at(-1);
+        const rest = args.slice(0, -1);
+        const path = mountedIn('open', rest);
+        if (typeof done !== 'function' || path === null)
+            return original(...args);
+        answer(host.open(path, rest[1]).then((handle) => [handle.fd]), done);
+        return undefined;
+    });
+    swap(fs, 'openSync', (original) => (...args) => {
+        const path = mountedIn('open', args);
+        if (path !== null)
+            throw syncRefusal('openSync', path);
+        return original(...args);
+    });
+    for (const name of DESCRIPTOR_CALLS) {
+        swap(fs, name, (original) => (...args) => {
+            if (host.descriptors.get(args[0]) === undefined)
+                return original(...args);
+            const done = args.at(-1);
+            // fs.close is the one whose callback node lets a caller leave out;
+            // node throws an unhandled close error on the next turn.
+            const callback = typeof done === 'function'
+                ? done
+                : (err) => {
+                    if (err !== null)
+                        process.nextTick(() => {
+                            throw err instanceof Error ? err : new Error('close failed', { cause: err });
+                        });
+                };
+            answer(host.descriptorCall(name, typeof done === 'function' ? args.slice(0, -1) : args), callback);
+            return undefined;
+        });
+        swap(fs, `${name}Sync`, (original) => (...args) => {
+            const desc = host.descriptors.get(args[0]);
+            if (desc !== undefined)
+                throw syncRefusal(`${name}Sync`, desc.path);
+            return original(...args);
+        });
+    }
+    for (const [name, condition] of Object.entries(REFUSED_CALLS)) {
+        swap(fs.promises, name, (original) => {
+            const iterated = Object.prototype.toString.call(original) === '[object AsyncGeneratorFunction]';
+            return (...args) => {
+                const path = mountedIn(name, args);
+                if (path === null)
+                    return original(...args);
+                const err = refusal(condition, name, path);
+                return iterated ? refusedIterator(err) : Promise.reject(err);
+            };
+        });
+        swap(fs, name, (original) => (...args) => {
+            const path = mountedIn(name, args);
+            if (path === null)
+                return original(...args);
+            const err = refusal(condition, name, path);
+            const done = args.at(-1);
+            if (typeof done !== 'function' || LISTENED_CALLS.has(name))
+                throw err;
+            process.nextTick(done, err);
+            return undefined;
+        });
+        swap(fs, `${name}Sync`, (original) => (...args) => {
+            const path = mountedIn(name, args);
+            if (path !== null)
+                throw refusal(condition, `${name}Sync`, path);
+            return original(...args);
+        });
+    }
+    return function restore() {
+        for (const [target, name, original] of swapped.reverse())
+            target[name] = original;
+    };
+}
+//# sourceMappingURL=fs.js.map