@struktoai/mirage-node 0.0.5 → 0.0.7-alpha.1

package/dist/core/ssh/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../../src/core/ssh/watch.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oCAAoC,CAAA;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AA2ExD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAG/D"}

package/dist/core/ssh/watch.js

@@ -0,0 +1,89 @@
+// ========= 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 {} from '@struktoai/mirage-core/types';
+import { mountPrefixOf } from '@struktoai/mirage-core/utils/key_prefix';
+import { stripSlash } from '@struktoai/mirage-core/utils/slash';
+import { ListingDeltaHook, statFingerprint, } from '@struktoai/mirage-core/watch/index';
+import { isNoSuchFile, joinRoot } from "./utils.js";
+function listDir(sftp, remote) {
+    return new Promise((resolveFn, rejectFn) => {
+        sftp.readdir(remote, (err, entries) => {
+            // A directory that vanished mid-walk is not an error: the next
+            // pull reports the DELETE from the snapshot diff.
+            if (err !== undefined) {
+                if (isNoSuchFile(err))
+                    resolveFn([]);
+                else
+                    rejectFn(err);
+                return;
+            }
+            resolveFn(entries);
+        });
+    });
+}
+async function* descend(sftp, root, relative) {
+    const entries = await listDir(sftp, joinRoot(root, relative));
+    for (const entry of entries) {
+        if (entry.filename === '.' || entry.filename === '..')
+            continue;
+        const base = relative === '/' ? '' : relative;
+        const child = `${base}/${entry.filename}`;
+        if (entry.attrs.isDirectory()) {
+            yield { virtual: child, isDir: true, fingerprint: null };
+            yield* descend(sftp, root, child);
+            continue;
+        }
+        const modified = new Date(entry.attrs.mtime * 1000).toISOString();
+        yield {
+            virtual: child,
+            isDir: false,
+            fingerprint: statFingerprint(null, modified, entry.attrs.size),
+            size: entry.attrs.size,
+            modified,
+        };
+    }
+}
+/**
+ * Recursive SFTP descent feeding the generic listing differ.
+ *
+ * Reads the remote host directly, never through mirage's caches, as the
+ * DeltaHook contract requires. Fingerprints on mtime, the same value `ssh` stat
+ * reports.
+ *
+ * Unlike the object stores, this costs one round trip per directory, because
+ * SFTP has no recursive listing to ask for. Poll cadence should account for the
+ * shape of the tree.
+ */
+class SSHWalk {
+    accessor;
+    constructor(accessor) {
+        this.accessor = accessor;
+    }
+    async *walk(root) {
+        const prefix = mountPrefixOf(root.virtual, root.resourcePath);
+        const sftp = await this.accessor.sftp();
+        const start = `/${stripSlash(root.mountPath)}`;
+        for await (const entry of descend(sftp, this.accessor.config.root ?? '/', start)) {
+            yield {
+                ...entry,
+                virtual: prefix !== '' ? `${prefix}${entry.virtual}` : entry.virtual,
+            };
+        }
+    }
+}
+export function buildDeltaHook(accessor) {
+    const walk = new SSHWalk(accessor);
+    return new ListingDeltaHook(walk.walk.bind(walk));
+}
+//# sourceMappingURL=watch.js.map

package/dist/core/ssh/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../../src/core/ssh/watch.ts"],"names":[],"mappings":"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"}

package/dist/core/ssh/write.d.ts

@@ -0,0 +1,4 @@
+import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { SSHAccessor } from '../../accessor/ssh.ts';
+export declare function writeBytes(accessor: SSHAccessor, p: PathSpec, data: Uint8Array): Promise<void>;
+//# sourceMappingURL=write.d.ts.map

package/dist/core/ssh/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/core/ssh/write.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAGxD,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,WAAW,EACrB,CAAC,EAAE,QAAQ,EACX,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/core/ssh/write.js

@@ -0,0 +1,34 @@
+// ========= 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 { invalidateAfterWrite } from '@struktoai/mirage-core/cache/context';
+import { record, startOp } from '@struktoai/mirage-core/observe/context';
+import { ResourceName } from '@struktoai/mirage-core/types';
+import { joinRoot, stripPrefix } from "./utils.js";
+export async function writeBytes(accessor, p, data) {
+    const timer = startOp();
+    const sftp = await accessor.sftp();
+    const virtual = stripPrefix(p);
+    const remote = joinRoot(accessor.config.root ?? '/', virtual);
+    await new Promise((resolveFn, rejectFn) => {
+        sftp.writeFile(remote, Buffer.from(data), (err) => {
+            if (err)
+                rejectFn(err);
+            else
+                resolveFn();
+        });
+    });
+    record('write', virtual, ResourceName.SSH, data.byteLength, timer);
+    await invalidateAfterWrite(p);
+}
+//# sourceMappingURL=write.js.map

package/dist/core/ssh/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../src/core/ssh/write.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAA;AAC3E,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAA;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAG3D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAElD,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,QAAqB,EACrB,CAAW,EACX,IAAgB;IAEhB,MAAM,KAAK,GAAG,OAAO,EAAE,CAAA;IACvB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAA;IAClC,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;IAC9B,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,GAAG,EAAE,OAAO,CAAC,CAAA;IAC7D,MAAM,IAAI,OAAO,CAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;QAC9C,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE;YAChD,IAAI,GAAG;gBAAE,QAAQ,CAAC,GAAG,CAAC,CAAA;;gBACjB,SAAS,EAAE,CAAA;QAClB,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IACF,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;IAClE,MAAM,oBAAoB,CAAC,CAAC,CAAC,CAAA;AAC/B,CAAC"}

package/dist/fs_monkey.d.ts

@@ -0,0 +1,11 @@
+import type { Workspace } from '@struktoai/mirage-core/workspace/workspace/workspace';
+/**
+ * Monkey-patch Node's `fs` module so that paths under any mirage mount
+ * route through the workspace. Paths NOT under a mount fall through to
+ * the real native fs. CJS-friendly; for ESM code you still need to use
+ * `ws.fs.*` directly since ESM bindings are frozen.
+ *
+ * Returns a `restore()` function that undoes the patch.
+ */
+export declare function patchNodeFs(ws: Workspace): () => void;
+//# sourceMappingURL=fs_monkey.d.ts.map

package/dist/fs_monkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs_monkey.d.ts","sourceRoot":"","sources":["../src/fs_monkey.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sDAAsD,CAAA;AAyDrF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,IAAI,CAuHrD"}

package/dist/fs_monkey.js

@@ -0,0 +1,187 @@
+// ========= 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 { createRequire } from 'node:module';
+import { FileType } from '@struktoai/mirage-core/types';
+const requireCjs = createRequire(import.meta.url);
+const fs = requireCjs('node:fs');
+// fs-monkey ships no types
+const fsMonkey = requireCjs('fs-monkey');
+const { patchFs } = fsMonkey;
+function mountedPath(ws, p) {
+    const m = ws.registry.tryMountFor(p);
+    if (m === null)
+        return false;
+    // The synthetic root anchor is an empty internal mount that matches every
+    // path; it does not back real files, so paths caught only by it fall
+    // through to the native fs. A user-provided `/` mount is honored.
+    if (ws.syntheticRoot && m === ws.registry.rootMount)
+        return false;
+    return true;
+}
+async function mirageStat(ws, p) {
+    const s = await ws.fs.stat(p);
+    const isDir = s.type === FileType.DIRECTORY;
+    const mtime = s.modified !== null ? new Date(s.modified) : new Date(0);
+    return {
+        isFile: () => !isDir,
+        isDirectory: () => isDir,
+        isBlockDevice: () => false,
+        isCharacterDevice: () => false,
+        isSymbolicLink: () => false,
+        isFIFO: () => false,
+        isSocket: () => false,
+        size: s.size ?? 0,
+        mtime,
+        mtimeMs: mtime.getTime(),
+        atime: mtime,
+        atimeMs: mtime.getTime(),
+        ctime: mtime,
+        ctimeMs: mtime.getTime(),
+        birthtime: mtime,
+        birthtimeMs: mtime.getTime(),
+        mode: 0,
+        nlink: 1,
+        uid: 0,
+        gid: 0,
+        rdev: 0,
+        blksize: 0,
+        blocks: 0,
+        dev: 0,
+        ino: 0,
+    };
+}
+/**
+ * Monkey-patch Node's `fs` module so that paths under any mirage mount
+ * route through the workspace. Paths NOT under a mount fall through to
+ * the real native fs. CJS-friendly; for ESM code you still need to use
+ * `ws.fs.*` directly since ESM bindings are frozen.
+ *
+ * Returns a `restore()` function that undoes the patch.
+ */
+export function patchNodeFs(ws) {
+    const originalFs = { ...fs };
+    const vol = {
+        promises: {
+            readFile: async (p, opts) => {
+                if (mountedPath(ws, p)) {
+                    const bytes = await ws.fs.readFile(p);
+                    const encoding = typeof opts === 'string' ? opts : opts?.encoding;
+                    if (encoding !== undefined)
+                        return Buffer.from(bytes).toString(encoding);
+                    return Buffer.from(bytes);
+                }
+                const native = originalFs.promises.readFile;
+                return native(p, opts);
+            },
+            writeFile: async (p, data) => {
+                if (mountedPath(ws, p)) {
+                    await ws.fs.writeFile(p, typeof data === 'string' ? data : data);
+                    return;
+                }
+                const native = originalFs.promises.writeFile;
+                await native(p, data);
+            },
+            readdir: async (p) => {
+                if (mountedPath(ws, p)) {
+                    // Workspace returns full paths; Node's fs.promises.readdir returns basenames.
+                    // Strip trailing slash on directory entries before slicing so dirs
+                    // don't collapse to ''.
+                    const entries = await ws.fs.readdir(p);
+                    return entries.map((e) => {
+                        const trimmed = e.endsWith('/') ? e.slice(0, -1) : e;
+                        return trimmed.slice(trimmed.lastIndexOf('/') + 1);
+                    });
+                }
+                const native = originalFs.promises.readdir;
+                return native(p);
+            },
+            stat: async (p) => {
+                if (mountedPath(ws, p))
+                    return mirageStat(ws, p);
+                const native = originalFs.promises.stat;
+                return native(p);
+            },
+            unlink: async (p) => {
+                if (mountedPath(ws, p))
+                    return ws.fs.unlink(p);
+                const native = originalFs.promises.unlink;
+                await native(p);
+            },
+            mkdir: async (p) => {
+                if (mountedPath(ws, p))
+                    return ws.fs.mkdir(p);
+                const native = originalFs.promises.mkdir;
+                await native(p);
+            },
+            rmdir: async (p) => {
+                if (mountedPath(ws, p))
+                    return ws.fs.rmdir(p);
+                const native = originalFs.promises.rmdir;
+                await native(p);
+            },
+        },
+        readFileSync: () => {
+            throw new Error('mirage.patchNodeFs: sync fs methods not supported — use fs.promises.*');
+        },
+        readFile: (p, cb) => {
+            if (mountedPath(ws, p)) {
+                ws.fs
+                    .readFile(p)
+                    .then((data) => {
+                    cb(null, Buffer.from(data));
+                })
+                    .catch((err) => {
+                    cb(err);
+                });
+                return;
+            }
+            const native = originalFs.readFile;
+            native(p, cb);
+        },
+        readdir: (p, cb) => {
+            if (mountedPath(ws, p)) {
+                ws.fs
+                    .readdir(p)
+                    .then((entries) => {
+                    cb(null, entries.map((e) => {
+                        const trimmed = e.endsWith('/') ? e.slice(0, -1) : e;
+                        return trimmed.slice(trimmed.lastIndexOf('/') + 1);
+                    }));
+                })
+                    .catch((err) => {
+                    cb(err);
+                });
+                return;
+            }
+            const native = originalFs.readdir;
+            native(p, cb);
+        },
+    };
+    patchFs(vol, fs);
+    return function restore() {
+        for (const [k, v] of Object.entries(originalFs)) {
+            const desc = Object.getOwnPropertyDescriptor(fs, k);
+            if (desc?.writable === false && desc.set === undefined)
+                continue;
+            try {
+                fs[k] = v;
+            }
+            catch {
+                // some fs properties are accessor-only and can't be reassigned; skip
+            }
+        }
+    };
+}
+//# sourceMappingURL=fs_monkey.js.map

package/dist/fs_monkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs_monkey.js","sourceRoot":"","sources":["../src/fs_monkey.ts"],"names":[],"mappings":"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"}

package/dist/fuse/backend.d.ts

@@ -0,0 +1,73 @@
+import { MountBackend } from '@struktoai/mirage-core/types';
+import type { Workspace } from '@struktoai/mirage-core/workspace/workspace/workspace';
+/**
+ * FSKit mounts only under /Volumes. Anywhere else the mount fails with an
+ * opaque driver error, so the rule is enforced up front rather than
+ * discovered at run time (github.com/strukto-ai/mirage#82).
+ */
+export declare const FSKIT_MOUNT_ROOT = "/Volumes";
+/**
+ * Coerce a user-supplied backend name into a MountBackend.
+ *
+ * Missing means vfs, everywhere: an absent `backend` in YAML, `undefined`
+ * here, and the `MountSpecOptions` default all resolve to the same thing.
+ * Callers that need a kernel mount say so explicitly rather than relying on
+ * this function to reinterpret an absent value.
+ */
+export declare function resolveBackend(value?: string | null): MountBackend;
+/** Reject a backend that registers nothing with the kernel. */
+export declare function requireKernelBackend(backend: MountBackend): void;
+/**
+ * Reject a backend the current platform cannot serve.
+ *
+ * FSKit works from TypeScript: `fuse.node` links `/usr/local/lib/
+ * libfuse.2.dylib` by absolute path (the `libosxfuse.2.dylib` it ships is a
+ * stub with that install name), so on a machine with macFUSE 5.x the
+ * `backend=fskit` option reaches the same libfuse Python uses. Verified
+ * with a live mount; see examples/typescript/fuse/fskit.ts.
+ */
+export declare function checkPlatform(backend: MountBackend): void;
+/** Reject a mountpoint the backend cannot mount on. */
+export declare function checkMountpoint(backend: MountBackend, mountpoint: string): void;
+/**
+ * Mounts under `rootPrefix` whose files cannot be sized without reading
+ * them. Mirrors Python's `Ops.unsized_mounts`.
+ */
+export declare function unsizedMounts(ws: Workspace, rootPrefix?: string): [string, string][];
+/**
+ * Warn when an fskit mount will serve size-unknown files as empty.
+ *
+ * FSKit drives reads from the size the filesystem reports and has no
+ * `direct_io` escape hatch, so a resource that cannot size a file without
+ * fetching it reports 0, the kernel issues no reads, and every such file
+ * comes back empty with exit code 0 (verified on a live fskit mount: the
+ * read clamp is pinned at lookup-time size and never refreshed). The mount
+ * proceeds anyway: per-backend size push-down is closing this gap, so the
+ * degraded mounts are named loudly here rather than refused.
+ */
+export declare function checkSizes(backend: MountBackend, ws: Workspace, rootPrefix?: string): void;
+/**
+ * Mounts that accept writes, in mount resolution order. Mirrors Python's
+ * `Ops.writable_mounts`.
+ */
+export declare function writableMounts(ws: Workspace, rootPrefix?: string): [string, string][];
+/**
+ * Warn when an fskit mount accepts writes the shim may corrupt.
+ *
+ * Measured on live fskit mounts and pinned in `integ/fuse/truth_fskit.json`: the
+ * macFUSE FSKit shim flushes pages a file did not already have (a new file,
+ * an empty file, a truncate-then-write) as NUL bytes of the right length,
+ * and appended regions arrive intact or zeroed depending on cache state.
+ * Metadata ops (create, mkdir, rename, unlink) are reliable. The writer sees
+ * no error either way, so the corruption is silent; the mount proceeds with
+ * a warning naming the writable mounts.
+ */
+export declare function checkWrites(backend: MountBackend, ws: Workspace, rootPrefix?: string): void;
+/**
+ * Resolve a backend for a kernel mount and run every guard it implies.
+ *
+ * One entry point, so a new mount path cannot pick up fskit support while
+ * silently skipping the macOS, /Volumes, or size checks.
+ */
+export declare function prepareBackend(value: string | undefined, ws?: Workspace, mountpoint?: string, rootPrefix?: string): MountBackend;
+//# sourceMappingURL=backend.d.ts.map

package/dist/fuse/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/fuse/backend.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAmB,YAAY,EAAa,MAAM,8BAA8B,CAAA;AAEvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sDAAsD,CAAA;AAErF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,aAAa,CAAA;AAE1C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAWlE;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAOhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAOzD;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAQ/E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,SAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAShF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,UAAU,SAAK,GAAG,IAAI,CAWtF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,SAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CASjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,UAAU,SAAK,GAAG,IAAI,CAcvF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,EAAE,CAAC,EAAE,SAAS,EACd,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,SAAK,GACd,YAAY,CAUd"}

package/dist/fuse/backend.js

@@ -0,0 +1,170 @@
+// ========= 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 { posix } from 'node:path';
+import { sizesAlwaysKnown } from '@struktoai/mirage-core/resource/base';
+import { KERNEL_BACKENDS, MountBackend, MountMode } from '@struktoai/mirage-core/types';
+import { rstripSlash } from '@struktoai/mirage-core/utils/slash';
+/**
+ * FSKit mounts only under /Volumes. Anywhere else the mount fails with an
+ * opaque driver error, so the rule is enforced up front rather than
+ * discovered at run time (github.com/strukto-ai/mirage#82).
+ */
+export const FSKIT_MOUNT_ROOT = '/Volumes';
+/**
+ * Coerce a user-supplied backend name into a MountBackend.
+ *
+ * Missing means vfs, everywhere: an absent `backend` in YAML, `undefined`
+ * here, and the `MountSpecOptions` default all resolve to the same thing.
+ * Callers that need a kernel mount say so explicitly rather than relying on
+ * this function to reinterpret an absent value.
+ */
+export function resolveBackend(value) {
+    if (value === undefined || value === null || value === '')
+        return MountBackend.VFS;
+    const lowered = value.toLowerCase();
+    if (!Object.values(MountBackend).includes(lowered)) {
+        throw new Error(`unknown mount backend ${JSON.stringify(value)}; expected one of: ${Object.values(MountBackend).join(', ')}`);
+    }
+    return lowered;
+}
+/** Reject a backend that registers nothing with the kernel. */
+export function requireKernelBackend(backend) {
+    if (!KERNEL_BACKENDS.includes(backend)) {
+        throw new Error(`backend ${JSON.stringify(backend)} does not register a mountpoint; it is served inside ` +
+            "mirage's own filesystem, so there is nothing to mount");
+    }
+}
+/**
+ * Reject a backend the current platform cannot serve.
+ *
+ * FSKit works from TypeScript: `fuse.node` links `/usr/local/lib/
+ * libfuse.2.dylib` by absolute path (the `libosxfuse.2.dylib` it ships is a
+ * stub with that install name), so on a machine with macFUSE 5.x the
+ * `backend=fskit` option reaches the same libfuse Python uses. Verified
+ * with a live mount; see examples/typescript/fuse/fskit.ts.
+ */
+export function checkPlatform(backend) {
+    if (backend !== MountBackend.FSKIT)
+        return;
+    if (process.platform !== 'darwin') {
+        throw new Error(`the fskit mount backend is macOS-only (running on ${process.platform}); use backend 'fuse'`);
+    }
+}
+/** Reject a mountpoint the backend cannot mount on. */
+export function checkMountpoint(backend, mountpoint) {
+    if (backend !== MountBackend.FSKIT)
+        return;
+    const resolved = posix.normalize(mountpoint);
+    if (resolved !== FSKIT_MOUNT_ROOT && !resolved.startsWith(FSKIT_MOUNT_ROOT + '/')) {
+        throw new Error(`the fskit mount backend only mounts under ${FSKIT_MOUNT_ROOT}; got ${JSON.stringify(mountpoint)}`);
+    }
+}
+/**
+ * Mounts under `rootPrefix` whose files cannot be sized without reading
+ * them. Mirrors Python's `Ops.unsized_mounts`.
+ */
+export function unsizedMounts(ws, rootPrefix = '') {
+    const root = rstripSlash(rootPrefix);
+    const found = [];
+    for (const m of ws.mounts()) {
+        const bare = rstripSlash(m.prefix);
+        if (root !== '' && bare !== root && !m.prefix.startsWith(root + '/'))
+            continue;
+        if (!sizesAlwaysKnown(m.resource))
+            found.push([m.prefix, m.resource.kind]);
+    }
+    return found;
+}
+/**
+ * Warn when an fskit mount will serve size-unknown files as empty.
+ *
+ * FSKit drives reads from the size the filesystem reports and has no
+ * `direct_io` escape hatch, so a resource that cannot size a file without
+ * fetching it reports 0, the kernel issues no reads, and every such file
+ * comes back empty with exit code 0 (verified on a live fskit mount: the
+ * read clamp is pinned at lookup-time size and never refreshed). The mount
+ * proceeds anyway: per-backend size push-down is closing this gap, so the
+ * degraded mounts are named loudly here rather than refused.
+ */
+export function checkSizes(backend, ws, rootPrefix = '') {
+    if (backend !== MountBackend.FSKIT)
+        return;
+    const offenders = unsizedMounts(ws, rootPrefix);
+    if (offenders.length === 0)
+        return;
+    const listed = offenders.map(([prefix, kind]) => `${prefix} (${kind})`).join(', ');
+    console.warn('mirage: the fskit mount backend cannot serve resources whose file sizes are only known ' +
+        `after a read; size-unknown files under these mounts will read as empty: ${listed}. ` +
+        "Mount them with backend 'fuse', or scope the fskit mount to a byte-store resource " +
+        '(ram, disk, redis, s3, gridfs).');
+}
+/**
+ * Mounts that accept writes, in mount resolution order. Mirrors Python's
+ * `Ops.writable_mounts`.
+ */
+export function writableMounts(ws, rootPrefix = '') {
+    const root = rstripSlash(rootPrefix);
+    const found = [];
+    for (const m of ws.mounts()) {
+        const bare = rstripSlash(m.prefix);
+        if (root !== '' && bare !== root && !m.prefix.startsWith(root + '/'))
+            continue;
+        if (m.mode !== MountMode.READ)
+            found.push([m.prefix, m.resource.kind]);
+    }
+    return found;
+}
+/**
+ * Warn when an fskit mount accepts writes the shim may corrupt.
+ *
+ * Measured on live fskit mounts and pinned in `integ/fuse/truth_fskit.json`: the
+ * macFUSE FSKit shim flushes pages a file did not already have (a new file,
+ * an empty file, a truncate-then-write) as NUL bytes of the right length,
+ * and appended regions arrive intact or zeroed depending on cache state.
+ * Metadata ops (create, mkdir, rename, unlink) are reliable. The writer sees
+ * no error either way, so the corruption is silent; the mount proceeds with
+ * a warning naming the writable mounts.
+ */
+export function checkWrites(backend, ws, rootPrefix = '') {
+    if (backend !== MountBackend.FSKIT)
+        return;
+    // /dev is mounted writable into every workspace, and a zeroed flush
+    // cannot corrupt a discard/byte-source device, so it never warns.
+    const offenders = writableMounts(ws, rootPrefix).filter(([prefix]) => rstripSlash(prefix) !== '/dev');
+    if (offenders.length === 0)
+        return;
+    const listed = offenders.map(([prefix, kind]) => `${prefix} (${kind})`).join(', ');
+    console.warn('mirage: file data written through an fskit mount may be flushed by the macFUSE FSKit ' +
+        `shim as zeroed pages (metadata ops are reliable; the writer sees no error): ${listed}. ` +
+        "Mount them read-only, or use backend 'fuse' for writes.");
+}
+/**
+ * Resolve a backend for a kernel mount and run every guard it implies.
+ *
+ * One entry point, so a new mount path cannot pick up fskit support while
+ * silently skipping the macOS, /Volumes, or size checks.
+ */
+export function prepareBackend(value, ws, mountpoint, rootPrefix = '') {
+    const backend = resolveBackend(value);
+    requireKernelBackend(backend);
+    checkPlatform(backend);
+    if (mountpoint !== undefined)
+        checkMountpoint(backend, mountpoint);
+    if (ws !== undefined) {
+        checkSizes(backend, ws, rootPrefix);
+        checkWrites(backend, ws, rootPrefix);
+    }
+    return backend;
+}
+//# sourceMappingURL=backend.js.map

package/dist/fuse/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/fuse/backend.ts"],"names":[],"mappings":"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"}