@nimbus-sh/core 0.1.0

package/dist/runtime/vfs-manifest.js

@@ -0,0 +1,141 @@
+/**
+ * Describe a VFS subtree without copying it.
+ *
+ * Same walk as snapshotVfs, but it records each file's SIZE instead of its
+ * bytes, so the result is a manifest the WASI layer treats as a cache index:
+ * content is demand-loaded through the supervisor on first read, and a path
+ * the manifest lacks is genuinely absent (the walk excludes nothing).
+ *
+ * That last property is why this cannot be a flag on snapshotVfs. snapshotVfs
+ * skips node_modules/.cache/.npm/.nimbus and unreadable files, so its output
+ * may not describe the subtree completely and must never claim to.
+ */
+export function manifestVfs(vfs, vfsRoot, opts = {}) {
+    const root = vfsRoot.replace(/^\/+/, '').replace(/\/+$/, '');
+    const roots = Array.from(new Set([
+        root,
+        ...Array.from(opts.extraRoots ?? []).map((r) => r.replace(/^\/+/, '').replace(/\/+$/, '')),
+    ].filter((r) => r !== undefined)));
+    const sizes = {};
+    const modes = {};
+    const dirsSet = new Set();
+    let totalBytes = 0;
+    let fileCount = 0;
+    const stack = [];
+    const addDirWithParents = (path, callerNamedRoot = false) => {
+        const clean = path.replace(/^\/+/, '').replace(/\/+$/, '');
+        if (!clean)
+            return;
+        const parts = clean.split('/').filter(Boolean);
+        for (let i = 1; i <= parts.length; i++) {
+            const ancestor = parts.slice(0, i).join('/');
+            dirsSet.add(ancestor);
+            if (modes[ancestor] === undefined) {
+                try {
+                    const st = vfs.stat(ancestor);
+                    modes[ancestor] = effectiveMode(st.mode, st.uid, st.gid, vfs.cred);
+                }
+                catch (error) {
+                    // Two different failures used to land here together, and only one of
+                    // them means "deny". An ancestor the caller may not read must stay
+                    // denied. But a root that does not exist YET — site-packages before
+                    // the first install — is a path the producer deliberately listed for
+                    // the guest to create, and leaving it modeless makes
+                    // __wasiEffectiveMode answer 0 for a path that `dirs` says exists:
+                    // deny everything, including traversal. The guest then cannot stat
+                    // its own target, os.path.isdir swallows the error and says False,
+                    // and makedirs(exist_ok=True) re-raises FileExistsError for a
+                    // directory it just created. It inherits its parent instead.
+                    // Only for a root the CALLER named. Those are paths a runtime has
+                    // declared it will use — site-packages, a gem home — and it may not
+                    // exist yet. Paths discovered by the walk are left alone: they came
+                    // from a readdir that already saw them, so a stat failure there is
+                    // genuinely unexpected and deny-by-default is right.
+                    if (!callerNamedRoot || hasErrorCode(error, 'EACCES'))
+                        continue;
+                    const parent = parts.slice(0, i - 1).join('/');
+                    modes[ancestor] = i === 1 ? 7 : (modes[parent] ?? 7);
+                }
+            }
+        }
+    };
+    for (const start of roots) {
+        addDirWithParents(start, true);
+        try {
+            if (!vfs.exists(start))
+                continue;
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EACCES'))
+                throw error;
+            modes[start] = 0;
+            continue;
+        }
+        const st = vfs.stat(start);
+        modes[start] = effectiveMode(st.mode, st.uid, st.gid, vfs.cred);
+        stack.push(start);
+    }
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = vfs.readdir(dir);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'EACCES'))
+                continue;
+            return { error: `runtime filesystem manifest incomplete: readdir ${dir}` };
+        }
+        for (const entry of entries) {
+            const childPath = `${dir}/${entry.name}`;
+            let st;
+            try {
+                st = vfs.stat(childPath);
+            }
+            catch (error) {
+                return { error: `runtime filesystem manifest incomplete: stat ${childPath}` };
+            }
+            const mode = effectiveMode(st.mode, st.uid, st.gid, vfs.cred);
+            modes[childPath] = mode;
+            if (entry.type === 'directory') {
+                addDirWithParents(childPath);
+                stack.push(childPath);
+                continue;
+            }
+            // Size comes from the inode, so a manifest costs no reads at all — this
+            // is the whole reason it has no byte cap and cannot fail a spawn.
+            const size = st.size;
+            sizes[childPath] = size;
+            totalBytes += size;
+            fileCount++;
+            addDirWithParents(dir);
+        }
+    }
+    return {
+        snapshot: {
+            root,
+            roots,
+            preopens: [],
+            files: {},
+            sizes,
+            dirs: Array.from(dirsSet).sort(),
+            modes,
+            enumeratedRoots: roots,
+            revision: opts.revision,
+        },
+        files: fileCount,
+        bytes: totalBytes,
+    };
+}
+export function effectiveMode(mode, uid, gid, cred) {
+    if (cred.uid === 0)
+        return 0o6 | ((mode & 0o111) !== 0 ? 0o1 : 0);
+    if (cred.uid === uid)
+        return (mode >> 6) & 0o7;
+    if (cred.gid === gid || cred.groups.includes(gid))
+        return (mode >> 3) & 0o7;
+    return mode & 0o7;
+}
+export function hasErrorCode(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}

package/dist/runtime/vfs-snapshot.d.ts

@@ -0,0 +1,75 @@
+/**
+ * vfs-snapshot.ts — the by-value filesystem bridge for the runtimes that still
+ * carry a private one.
+ *
+ * bash and python each implement their own filesystem inside their facet, so
+ * neither can demand-load or write through: they take a whole copy of the
+ * subtree at spawn and hand back a diff when they exit. That is the failure
+ * mode the shared WASI layer exists to remove — a resident process that never
+ * exits never persists anything — and this file is scheduled to die with the
+ * last of those two private implementations. Nothing new may be built on it.
+ */
+import type { WasiFsSnapshot } from './wasi-instance.js';
+import type { VfsLike } from './vfs-manifest.js';
+/**
+ * Mutations a private-filesystem runtime made, reported once at exit.
+ */
+export interface WasiFsDiff {
+    /** New or modified files, base64-encoded. */
+    filesWritten: Record<string, string>;
+    /** Unlinked files. */
+    filesDeleted: string[];
+    /** Created directories. */
+    dirsCreated: string[];
+    /** Removed directories, deepest first. */
+    dirsDeleted: string[];
+    /**
+     * vfsPath → permission bits requested via an in-facet chmod (busybox chmod
+     * through the nimbus_proc.chmod import). Applied durably by flushVfsDiff via
+     * vfs.chmod, where S2a ownership enforcement decides.
+     */
+    modesChanged?: Record<string, number>;
+    /**
+     * vfsPath → target string for symlinks created during the run. Stored
+     * verbatim: a symlink target is a string, not a resolved path, and is
+     * allowed to dangle. Without this channel a link created in-facet resolves
+     * for the rest of the run and then silently disappears at exit.
+     */
+    symlinksCreated?: Record<string, string>;
+}
+export interface VfsSnapshotCaps {
+    maxBytes?: number;
+    maxFiles?: number;
+    skipSubdirs?: Iterable<string>;
+    extraRoots?: Iterable<string>;
+}
+export interface VfsSnapshotResult {
+    snapshot: WasiFsSnapshot;
+    bytes: number;
+    files: number;
+}
+export declare function bytesToB64(bytes: Uint8Array): string;
+export declare function b64ToBytes(b64: string): Uint8Array;
+/**
+ * Snapshot a VFS subtree into a JSON-serializable WASI-shaped filesystem.
+ *
+ * The snapshot is intentionally bounded. Runtimes that need incremental or
+ * lazy file IO should add a streaming bridge; a single request payload is the
+ * right primitive only for normal source trees and small app state.
+ */
+export declare function snapshotVfs(vfs: VfsLike, vfsRoot: string, caps?: VfsSnapshotCaps): VfsSnapshotResult | {
+    error: string;
+};
+/**
+ * Apply a runtime-produced filesystem diff back into the supervisor VFS.
+ * Operations are independent so one bad path never loses the rest of a run.
+ */
+export declare function flushVfsDiff(vfs: VfsLike, diff: WasiFsDiff): {
+    written: number;
+    deleted: number;
+    mkdirs: number;
+    rmdirs: number;
+    chmods: number;
+    symlinks: number;
+};
+//# sourceMappingURL=vfs-snapshot.d.ts.map

package/dist/runtime/vfs-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs-snapshot.d.ts","sourceRoot":"","sources":["../../src/runtime/vfs-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sBAAsB;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAKlD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA6HvC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,UAAU,GACf;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CA2DxG"}

package/dist/runtime/vfs-snapshot.js

@@ -0,0 +1,220 @@
+import { effectiveMode, hasErrorCode } from './vfs-manifest.js';
+export function bytesToB64(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return btoa(s);
+}
+export function b64ToBytes(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Snapshot a VFS subtree into a JSON-serializable WASI-shaped filesystem.
+ *
+ * The snapshot is intentionally bounded. Runtimes that need incremental or
+ * lazy file IO should add a streaming bridge; a single request payload is the
+ * right primitive only for normal source trees and small app state.
+ */
+export function snapshotVfs(vfs, vfsRoot, caps = {}) {
+    const maxBytes = caps.maxBytes ?? 32 * 1024 * 1024;
+    const maxFiles = caps.maxFiles ?? 5000;
+    const skipSubdirs = new Set(caps.skipSubdirs ?? ['.nimbus', 'node_modules', '.cache', '.npm']);
+    const root = vfsRoot.replace(/^\/+/, '').replace(/\/+$/, '');
+    const roots = Array.from(new Set([
+        root,
+        ...Array.from(caps.extraRoots ?? []).map((r) => r.replace(/^\/+/, '').replace(/\/+$/, '')).filter(Boolean),
+    ].filter(Boolean)));
+    const files = {};
+    const modes = {};
+    const dirsSet = new Set();
+    let totalBytes = 0;
+    let fileCount = 0;
+    const stack = [];
+    const failures = [];
+    const addDirWithParents = (path) => {
+        const clean = path.replace(/^\/+/, '').replace(/\/+$/, '');
+        if (!clean)
+            return;
+        const parts = clean.split('/').filter(Boolean);
+        for (let i = 1; i <= parts.length; i++) {
+            const ancestor = parts.slice(0, i).join('/');
+            dirsSet.add(ancestor);
+            // Every ancestor directory needs an effective-mode entry: the WASI
+            // shim requires the search (x) bit on each path component to traverse
+            // into a leaf, and its default for an existing-but-unmapped inode is
+            // deny. An intermediate dir that is neither a root nor walked (e.g.
+            // the shared parent of the cwd and the gem home) would otherwise have
+            // no entry and block all traversal through it with EACCES. Statting
+            // it here grants exactly the caller's real access — no more, no less.
+            if (modes[ancestor] === undefined) {
+                try {
+                    const stat = vfs.stat(ancestor);
+                    modes[ancestor] = effectiveMode(stat.mode, stat.uid, stat.gid, vfs.cred);
+                }
+                catch {
+                    // Unreadable or absent ancestor: leave unmapped so the caller's
+                    // seeded preopen modes or the shim's deny-by-default apply.
+                }
+            }
+        }
+    };
+    for (const start of roots) {
+        addDirWithParents(start);
+        try {
+            if (!vfs.exists(start))
+                continue;
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EACCES'))
+                throw error;
+            modes[start] = 0;
+            continue;
+        }
+        const stat = vfs.stat(start);
+        modes[start] = effectiveMode(stat.mode, stat.uid, stat.gid, vfs.cred);
+        stack.push(start);
+    }
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = vfs.readdir(dir);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'EACCES'))
+                continue;
+            failures.push(`readdir ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        for (const entry of entries) {
+            const childPath = `${dir}/${entry.name}`;
+            if (entry.type === 'directory') {
+                if (skipSubdirs.has(entry.name))
+                    continue;
+                let stat;
+                try {
+                    stat = vfs.stat(childPath);
+                }
+                catch (error) {
+                    failures.push(`stat ${childPath}: ${error instanceof Error ? error.message : String(error)}`);
+                    continue;
+                }
+                modes[childPath] = effectiveMode(stat.mode, stat.uid, stat.gid, vfs.cred);
+                addDirWithParents(childPath);
+                stack.push(childPath);
+                continue;
+            }
+            let stat;
+            try {
+                stat = vfs.stat(childPath);
+            }
+            catch (error) {
+                failures.push(`stat ${childPath}: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const mode = effectiveMode(stat.mode, stat.uid, stat.gid, vfs.cred);
+            modes[childPath] = mode;
+            if ((mode & 0o4) === 0)
+                continue;
+            let bytes;
+            try {
+                bytes = vfs.readFile(childPath);
+            }
+            catch (error) {
+                failures.push(`readFile ${childPath}: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            totalBytes += bytes.length;
+            fileCount++;
+            if (totalBytes > maxBytes) {
+                return { error: `runtime filesystem snapshot exceeded ${(maxBytes / 1024 / 1024).toFixed(0)} MiB cap (current dir: ${dir})` };
+            }
+            if (fileCount > maxFiles) {
+                return { error: `runtime filesystem snapshot exceeded ${maxFiles} file cap` };
+            }
+            addDirWithParents(dir);
+            files[childPath] = bytesToB64(bytes);
+        }
+    }
+    if (failures.length > 0) {
+        return { error: `runtime filesystem snapshot incomplete: ${failures.join('; ')}` };
+    }
+    return {
+        snapshot: { root, roots, preopens: [], files, dirs: Array.from(dirsSet).sort(), modes },
+        bytes: totalBytes,
+        files: fileCount,
+    };
+}
+/**
+ * Apply a runtime-produced filesystem diff back into the supervisor VFS.
+ * Operations are independent so one bad path never loses the rest of a run.
+ */
+export function flushVfsDiff(vfs, diff) {
+    let written = 0;
+    let deleted = 0;
+    let mkdirs = 0;
+    let rmdirs = 0;
+    let chmods = 0;
+    let symlinks = 0;
+    for (const path of diff.dirsCreated) {
+        try {
+            vfs.mkdir(path, { recursive: true });
+            mkdirs++;
+        }
+        catch { }
+    }
+    for (const [path, b64] of Object.entries(diff.filesWritten)) {
+        try {
+            const lastSlash = path.lastIndexOf('/');
+            if (lastSlash > 0) {
+                try {
+                    vfs.mkdir(path.substring(0, lastSlash), { recursive: true });
+                }
+                catch { }
+            }
+            vfs.writeFile(path, b64ToBytes(b64));
+            written++;
+        }
+        catch { }
+    }
+    for (const path of diff.filesDeleted) {
+        try {
+            vfs.unlink(path);
+            deleted++;
+        }
+        catch { }
+    }
+    for (const path of diff.dirsDeleted) {
+        try {
+            vfs.rmdir(path);
+            rmdirs++;
+        }
+        catch { }
+    }
+    for (const [path, mode] of Object.entries(diff.modesChanged ?? {})) {
+        try {
+            vfs.chmod(path, mode);
+            chmods++;
+        }
+        catch { }
+    }
+    for (const [path, target] of Object.entries(diff.symlinksCreated ?? {})) {
+        try {
+            const lastSlash = path.lastIndexOf('/');
+            if (lastSlash > 0) {
+                try {
+                    vfs.mkdir(path.substring(0, lastSlash), { recursive: true });
+                }
+                catch { }
+            }
+            vfs.symlink(target, path);
+            symlinks++;
+        }
+        catch { }
+    }
+    return { written, deleted, mkdirs, rmdirs, chmods, symlinks };
+}