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

package/dist/fuse/mount.js

@@ -0,0 +1,180 @@
+// ========= 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 { execSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { MountBackend } from '@struktoai/mirage-core/types';
+import { loadOptionalPeer } from "../optional_peer.js";
+import { checkMountpoint, FSKIT_MOUNT_ROOT, prepareBackend } from "./backend.js";
+import { MirageFS } from "./fs.js";
+/**
+ * Append raw libfuse options to the mount option string.
+ * `@zkochan/fuse-native` serializes a fixed allowlist of options in
+ * `_fuseOptions()`, so anything outside it (`direct_io`, `backend`,
+ * `volname`) is appended by wrapping the serializer at runtime — this
+ * ships to consumers, unlike a pnpm patch, which would only apply inside
+ * this repository.
+ */
+export function appendMountOptions(fuse, extras) {
+    const orig = fuse._fuseOptions?.bind(fuse);
+    if (orig === undefined) {
+        throw new Error('@zkochan/fuse-native no longer exposes _fuseOptions(); extra mount ' +
+            'options cannot be applied. Update appendMountOptions in mount.ts ' +
+            'for the new fuse-native version.');
+    }
+    fuse._fuseOptions = () => {
+        const serialized = orig();
+        const missing = extras.filter((opt) => !serialized.includes(opt));
+        if (missing.length === 0)
+            return serialized;
+        if (serialized === '')
+            return `-o${missing.join(',')}`;
+        return `${serialized},${missing.join(',')}`;
+    };
+}
+/**
+ * Append libfuse's `direct_io`. Load-bearing for size-unknown API files:
+ * getattr reports 0 pre-open and the kernel must read to EOF regardless
+ * (verified on the macOS kext: without it, `cat` reads 0 bytes; see the
+ * CLAUDE.md FUSE section).
+ */
+export function appendDirectIO(fuse) {
+    appendMountOptions(fuse, ['direct_io']);
+}
+/**
+ * What to install when the binding will not load, for the platform it did
+ * not load on. Only macOS and Linux have an answer: fuse-native's legacy
+ * Windows path builds against the unmaintained Dokany-based
+ * `fuse-shared-library-win32` rather than WinFsp, so naming a Windows
+ * driver would send the reader after something that cannot fix it. Python
+ * is the one that mounts FUSE on Windows.
+ */
+export function driverHint(platform = process.platform) {
+    if (platform === 'darwin')
+        return 'FUSE also needs the macFUSE driver, installed separately.';
+    if (platform === 'linux')
+        return 'FUSE also needs libfuse3, from the fuse3 package.';
+    return ('TypeScript FUSE mounts run on macOS and Linux only: @zkochan/fuse-native ' +
+        'does not support WinFsp. Python mounts FUSE on Windows experimentally.');
+}
+async function loadFuse() {
+    const mod = await loadOptionalPeer(() => import('@zkochan/fuse-native'), {
+        feature: 'FUSE support',
+        packageName: '@zkochan/fuse-native',
+        docsUrl: 'https://mirage.dev/typescript/setup/fuse',
+        // fuse-native dlopens its binding against libfuse as it loads, so a
+        // machine with the package and no driver fails here, not at
+        // resolution (ERR_DLOPEN_FAILED, or no prebuild for the platform).
+        systemHint: driverHint(),
+    });
+    const Fuse = (mod.default ?? mod);
+    if (typeof Fuse !== 'function') {
+        throw new Error('@zkochan/fuse-native did not export a constructor');
+    }
+    return Fuse;
+}
+/** Fallback unmount via platform tools — mirrors Python's SIGINT handler. */
+export function forceUnmount(mountpoint) {
+    try {
+        if (process.platform === 'darwin') {
+            execSync(`diskutil unmount force ${JSON.stringify(mountpoint)}`, { stdio: 'ignore' });
+        }
+        else {
+            execSync(`fusermount -u ${JSON.stringify(mountpoint)}`, { stdio: 'ignore' });
+        }
+    }
+    catch {
+        // best-effort; caller already tried the clean path
+    }
+}
+export async function mount(ws, options = {}) {
+    const backend = prepareBackend(options.backend ?? MountBackend.FUSE, ws, undefined, options.rootPrefix ?? '');
+    const Fuse = await loadFuse();
+    const isFskit = backend === MountBackend.FSKIT;
+    let mountpoint;
+    let ownsMountpoint = false;
+    if (options.mountpoint !== undefined) {
+        checkMountpoint(backend, options.mountpoint);
+        // Pinned path: create if missing, but keep ownership with the caller.
+        // An FSKit mountpoint is NAMED, never created: /Volumes is root-owned
+        // (mkdir there is EACCES for a normal user), and the volume directory
+        // is the system's to create when the filesystem goes live.
+        if (!isFskit)
+            mkdirSync(options.mountpoint, { recursive: true });
+        mountpoint = options.mountpoint;
+    }
+    else if (isFskit) {
+        mountpoint = `${FSKIT_MOUNT_ROOT}/mirage-${randomBytes(4).toString('hex')}`;
+        // The /Volumes entry is created and removed by the system, not ours to
+        // rmdir (nor could we: /Volumes is root-owned).
+    }
+    else {
+        mountpoint = mkdtempSync(join(tmpdir(), 'mirage-fuse-'));
+        ownsMountpoint = true;
+    }
+    const mfs = new MirageFS(ws.fs, {
+        ...(options.rootPrefix !== undefined ? { rootPrefix: options.rootPrefix } : {}),
+        ...(options.session !== undefined ? { session: options.session } : {}),
+    });
+    const autoUnmount = options.autoUnmount ?? process.platform === 'linux';
+    // Size-unknown recipe, mirroring Python's mount.py: direct_io (appended
+    // below) makes the kernel read to EOF even though getattr reports 0
+    // pre-open, and attrTimeout '0' (string: the option serializer drops falsy
+    // values) keeps the kernel from caching that 0, so the post-open fstat
+    // reaches fgetattr, which answers with the prefetched real size. Both are
+    // load-bearing on the macOS kext; see the CLAUDE.md FUSE section.
+    const fuseOpts = {
+        force: true,
+        mkdir: true,
+        attrTimeout: '0',
+        ...(autoUnmount ? { autoUnmount: true } : {}),
+        ...(options.fuseOptions ?? {}),
+    };
+    const fuse = new Fuse(mountpoint, mfs.ops(), fuseOpts);
+    if (isFskit) {
+        // Issue #82's verified recipe: backend=fskit + volname, direct_io
+        // omitted (FSKit has no direct_io; reads are driven by reported size,
+        // which checkSizes guarantees is exact). Mirrors Python's _run_fuse.
+        appendMountOptions(fuse, ['backend=fskit', `volname=${basename(mountpoint)}`]);
+    }
+    else if (fuseOpts.directIO !== false) {
+        appendDirectIO(fuse);
+    }
+    await new Promise((resolve, reject) => {
+        fuse.mount((err) => {
+            if (err === null)
+                resolve();
+            else
+                reject(err);
+        });
+    });
+    return {
+        mountpoint,
+        ownsMountpoint,
+        unmount: () => new Promise((resolve, reject) => {
+            fuse.unmount((err) => {
+                if (err === null)
+                    resolve();
+                else
+                    reject(err);
+            });
+        }),
+    };
+}
+export function mountBackground(ws, options = {}) {
+    return mount(ws, options);
+}
+//# sourceMappingURL=mount.js.map

package/dist/fuse/mount.js.map

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

package/dist/fuse/platform/macos.d.ts

@@ -0,0 +1,2 @@
+export declare function isMacosMetadata(name: string): boolean;
+//# sourceMappingURL=macos.d.ts.map

package/dist/fuse/platform/macos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macos.d.ts","sourceRoot":"","sources":["../../../src/fuse/platform/macos.ts"],"names":[],"mappings":"AAqBA,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/fuse/platform/macos.js

@@ -0,0 +1,23 @@
+// ========= 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. =========
+const MACOS_METADATA = new Set([
+    '.DS_Store',
+    '.Spotlight-V100',
+    '.fseventsd',
+    '.Trashes',
+]);
+export function isMacosMetadata(name) {
+    return MACOS_METADATA.has(name) || name.startsWith('._');
+}
+//# sourceMappingURL=macos.js.map

package/dist/fuse/platform/macos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"macos.js","sourceRoot":"","sources":["../../../src/fuse/platform/macos.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,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,WAAW;IACX,iBAAiB;IACjB,YAAY;IACZ,UAAU;CACX,CAAC,CAAA;AAEF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAC1D,CAAC"}