@nimbus-sh/core 0.1.0

package/dist/substrate/lifo/pkg/lifo-runtime.js

@@ -0,0 +1,372 @@
+/**
+ * Lifo Runtime -- enhanced execution context for lifo-native packages.
+ *
+ * Packages with a "lifo" field in package.json get this runtime instead of
+ * the plain CJS node runner.  It provides:
+ *   - lifo.import()   – load ESM modules from a configurable CDN (default esm.sh)
+ *   - lifo.loadWasm() – load startup-registered WebAssembly modules
+ *   - lifo.resolve()  – resolve a path relative to cwd
+ */
+import { resolve, dirname, join } from '../utils/path.js';
+import { createProcess } from '../node-compat/process.js';
+import { createConsole } from '../node-compat/console.js';
+import { Buffer } from '../node-compat/buffer.js';
+import { createModuleMap } from '../node-compat/index.js';
+import { ProcessExitError } from '../node-compat/index.js';
+// ─── CDN + WASM module registry ───
+const DEFAULT_CDN = 'https://esm.sh';
+/** In-memory cache for CDN imports (survives across command invocations). */
+const esmCache = new Map();
+const wasmModules = new Map();
+export function registerLifoWasmModule(url, module) {
+    wasmModules.set(url, module);
+}
+function getCdn(env) {
+    return env.LIFO_CDN || DEFAULT_CDN;
+}
+function createLifoAPI(ctx) {
+    const cdn = getCdn(ctx.env);
+    return {
+        cdn,
+        async import(specifier) {
+            // Allow full URLs to pass through
+            const url = specifier.startsWith('http://') || specifier.startsWith('https://')
+                ? specifier
+                : `${cdn}/${specifier}`;
+            const cached = esmCache.get(url);
+            if (cached)
+                return cached;
+            const mod = await import(/* @vite-ignore */ url);
+            esmCache.set(url, mod);
+            return mod;
+        },
+        async loadWasm(url) {
+            const module = wasmModules.get(url);
+            if (module)
+                return module;
+            throw new Error(`lifo.loadWasm("${url}") requires a startup-registered WebAssembly module; ` +
+                'Workers do not allow compiling fetched WebAssembly bytes during request handling.');
+        },
+        resolve(path) {
+            return resolve(ctx.cwd, path);
+        },
+    };
+}
+// ─── Command loader ───
+/** Strip shebang line, preserve line numbers. */
+function stripShebang(src) {
+    if (src.charCodeAt(0) === 0x23 && src.charCodeAt(1) === 0x21) {
+        const nl = src.indexOf('\n');
+        if (nl === -1)
+            return '';
+        return '\n' + src.slice(nl + 1);
+    }
+    return src;
+}
+// ─── ESM detection & rewriting ───
+/** Quick check: does the source use ESM syntax (import/export at top level)? */
+function isEsmSource(source) {
+    // Match import/export at the start of a line (not inside strings)
+    return /(?:^|\n)\s*(?:import\s|export\s)/m.test(source);
+}
+/**
+ * Rewrite bare specifier imports/exports to CDN URLs so the module
+ * can be loaded via blob URL + import().
+ *
+ *   import { X } from 'foo'  →  import { X } from 'https://esm.sh/foo'
+ *   import('foo')             →  import('https://esm.sh/foo')
+ */
+function rewriteImportsToCdn(source, cdn) {
+    // Static imports/re-exports: from 'specifier' or from "specifier"
+    let result = source.replace(/(from\s+)(["'])([^"'./][^"']*)\2/g, (_, prefix, quote, spec) => `${prefix}${quote}${cdn}/${spec}${quote}`);
+    // Dynamic import(): import('specifier') or import("specifier")
+    result = result.replace(/(import\s*\(\s*)(["'])([^"'./][^"']*)\2(\s*\))/g, (_, prefix, quote, spec, suffix) => `${prefix}${quote}${cdn}/${spec}${quote}${suffix}`);
+    return result;
+}
+/**
+ * Create a Command that executes a lifo-native package entry.
+ *
+ * Supports two module formats:
+ *   - ESM: import/export syntax → loaded through a data URL module
+ *   - CJS: module.exports = async function(ctx, lifo) { ... }
+ */
+export function createLifoCommand(entryPath, vfs) {
+    return async (ctx) => {
+        const source = vfs.readFileString(entryPath);
+        const lifo = createLifoAPI(ctx);
+        // ── ESM path: rewrite imports to CDN, load through a data URL ──
+        if (isEsmSource(source)) {
+            return executeEsmCommand(source, ctx, lifo);
+        }
+        // ── CJS path: wrap in new Function() ──
+        return executeCjsCommand(source, entryPath, vfs, ctx, lifo);
+    };
+}
+async function executeEsmCommand(source, ctx, lifo) {
+    const cdn = getCdn(ctx.env);
+    const rewritten = rewriteImportsToCdn(source, cdn);
+    const encoded = Buffer.from(rewritten, 'utf-8').toString('base64');
+    const url = `data:text/javascript;base64,${encoded}`;
+    try {
+        const mod = await import(/* @vite-ignore */ url);
+        const handler = mod.default;
+        if (typeof handler !== 'function') {
+            ctx.stderr.write('lifo: ESM module does not export a default command function\n');
+            return 1;
+        }
+        const exitCode = await handler(ctx, lifo);
+        return typeof exitCode === 'number' ? exitCode : 0;
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            ctx.stderr.write(`${e.stack || e.message}\n`);
+        }
+        else {
+            ctx.stderr.write(`${String(e)}\n`);
+        }
+        return 1;
+    }
+}
+function executeCjsCommand(source, entryPath, vfs, ctx, lifo) {
+    const entryDir = dirname(entryPath);
+    // Build a node-compat context for require()
+    const nodeCtx = {
+        vfs: ctx.vfs,
+        cwd: ctx.cwd,
+        env: ctx.env,
+        stdout: ctx.stdout,
+        stderr: ctx.stderr,
+        argv: [entryPath, ...ctx.args],
+        filename: entryPath,
+        dirname: entryDir,
+        signal: ctx.signal,
+    };
+    const moduleMap = createModuleMap(nodeCtx);
+    const moduleCache = new Map();
+    // Minimal require for lifo commands
+    function lifoRequire(name) {
+        if (moduleCache.has(name))
+            return moduleCache.get(name);
+        // Built-in modules
+        if (moduleMap[name]) {
+            const mod = moduleMap[name]();
+            moduleCache.set(name, mod);
+            return mod;
+        }
+        // Relative files
+        if (name.startsWith('./') || name.startsWith('../') || name.startsWith('/')) {
+            const absPath = resolve(entryDir, name);
+            const candidates = [absPath, absPath + '.js', absPath + '.json'];
+            for (const p of candidates) {
+                if (vfs.exists(p)) {
+                    if (p.endsWith('.json')) {
+                        const parsed = JSON.parse(vfs.readFileString(p));
+                        moduleCache.set(name, parsed);
+                        return parsed;
+                    }
+                    const childSrc = vfs.readFileString(p);
+                    const childMod = executeModule(childSrc, p);
+                    moduleCache.set(name, childMod);
+                    return childMod;
+                }
+            }
+            // Try directory with index.js
+            const indexPath = join(absPath, 'index.js');
+            if (vfs.exists(indexPath)) {
+                const childSrc = vfs.readFileString(indexPath);
+                const childMod = executeModule(childSrc, indexPath);
+                moduleCache.set(name, childMod);
+                return childMod;
+            }
+            throw new Error(`Cannot find module '${name}'`);
+        }
+        // node_modules resolution (walk up)
+        const resolved = resolveNodeModule(name, entryDir);
+        if (resolved) {
+            if (moduleCache.has(resolved))
+                return moduleCache.get(resolved);
+            if (resolved.endsWith('.json')) {
+                const parsed = JSON.parse(vfs.readFileString(resolved));
+                moduleCache.set(resolved, parsed);
+                return parsed;
+            }
+            const childSrc = vfs.readFileString(resolved);
+            const childMod = executeModule(childSrc, resolved);
+            moduleCache.set(resolved, childMod);
+            return childMod;
+        }
+        throw new Error(`Cannot find module '${name}'`);
+    }
+    function resolveNodeModule(name, fromDir) {
+        let pkgName;
+        let subpath = null;
+        if (name.startsWith('@')) {
+            const parts = name.split('/');
+            if (parts.length < 2)
+                return null;
+            pkgName = parts[0] + '/' + parts[1];
+            if (parts.length > 2)
+                subpath = parts.slice(2).join('/');
+        }
+        else {
+            const idx = name.indexOf('/');
+            if (idx !== -1) {
+                pkgName = name.slice(0, idx);
+                subpath = name.slice(idx + 1);
+            }
+            else {
+                pkgName = name;
+            }
+        }
+        // Walk up
+        let cur = fromDir;
+        for (;;) {
+            const candidate = join(cur, 'node_modules', pkgName);
+            if (vfs.exists(candidate)) {
+                return resolvePackageEntry(candidate, subpath);
+            }
+            const parent = dirname(cur);
+            if (parent === cur)
+                break;
+            cur = parent;
+        }
+        // Global + legacy
+        for (const base of ['/usr/lib/node_modules', '/usr/share/pkg/node_modules']) {
+            const candidate = join(base, pkgName);
+            if (vfs.exists(candidate)) {
+                return resolvePackageEntry(candidate, subpath);
+            }
+        }
+        return null;
+    }
+    function resolvePackageEntry(pkgDir, subpath) {
+        if (subpath) {
+            const abs = resolve(pkgDir, subpath);
+            for (const p of [abs, abs + '.js', abs + '.json']) {
+                if (vfs.exists(p))
+                    return p;
+            }
+            const idx = join(abs, 'index.js');
+            if (vfs.exists(idx))
+                return idx;
+            return null;
+        }
+        const pkgJsonPath = join(pkgDir, 'package.json');
+        if (vfs.exists(pkgJsonPath)) {
+            try {
+                const pkg = JSON.parse(vfs.readFileString(pkgJsonPath));
+                if (pkg.main) {
+                    const mainPath = resolve(pkgDir, pkg.main);
+                    for (const p of [mainPath, mainPath + '.js']) {
+                        if (vfs.exists(p))
+                            return p;
+                    }
+                }
+            }
+            catch { /* ignore */ }
+        }
+        const indexPath = join(pkgDir, 'index.js');
+        if (vfs.exists(indexPath))
+            return indexPath;
+        return null;
+    }
+    function executeModule(modSource, modFilename) {
+        const modDir = dirname(modFilename);
+        const modModule = { exports: {} };
+        const modExports = modModule.exports;
+        const modProcess = createProcess({
+            argv: nodeCtx.argv,
+            env: nodeCtx.env,
+            cwd: nodeCtx.cwd,
+            stdout: ctx.stdout,
+            stderr: ctx.stderr,
+        });
+        const modConsole = createConsole(ctx.stdout, ctx.stderr);
+        function modRequire(n) {
+            // Update resolution base to this module's directory
+            if (n.startsWith('./') || n.startsWith('../')) {
+                const abs = resolve(modDir, n);
+                const candidates = [abs, abs + '.js', abs + '.json'];
+                for (const p of candidates) {
+                    if (vfs.exists(p)) {
+                        if (moduleCache.has(p))
+                            return moduleCache.get(p);
+                        if (p.endsWith('.json')) {
+                            const parsed = JSON.parse(vfs.readFileString(p));
+                            moduleCache.set(p, parsed);
+                            return parsed;
+                        }
+                        const src = vfs.readFileString(p);
+                        return executeModule(src, p);
+                    }
+                }
+                const idx = join(abs, 'index.js');
+                if (vfs.exists(idx)) {
+                    if (moduleCache.has(idx))
+                        return moduleCache.get(idx);
+                    const src = vfs.readFileString(idx);
+                    return executeModule(src, idx);
+                }
+                throw new Error(`Cannot find module '${n}'`);
+            }
+            return lifoRequire(n);
+        }
+        const clean = stripShebang(modSource);
+        const wrapped = `(function(exports,require,module,__filename,__dirname,console,process,Buffer,setTimeout,setInterval,clearTimeout,clearInterval,global){\n${clean}\n})`;
+        const fn = new Function('return ' + wrapped)();
+        fn(modExports, modRequire, modModule, modFilename, modDir, modConsole, modProcess, Buffer, globalThis.setTimeout, globalThis.setInterval, globalThis.clearTimeout, globalThis.clearInterval, {});
+        return modModule.exports !== modExports ? modModule.exports : modExports;
+    }
+    // ── Execute the CJS entry ──
+    const cjsProcess = createProcess({
+        argv: nodeCtx.argv,
+        env: nodeCtx.env,
+        cwd: nodeCtx.cwd,
+        stdout: ctx.stdout,
+        stderr: ctx.stderr,
+    });
+    const nodeConsole = createConsole(ctx.stdout, ctx.stderr);
+    const module = { exports: {} };
+    const exports = module.exports;
+    const cleanSource = stripShebang(source);
+    const wrapped = `(function(exports,require,module,__filename,__dirname,console,process,Buffer,setTimeout,setInterval,clearTimeout,clearInterval,global){\n${cleanSource}\n})`;
+    try {
+        const fn = new Function('return ' + wrapped)();
+        fn(exports, lifoRequire, module, entryPath, entryDir, nodeConsole, cjsProcess, Buffer, globalThis.setTimeout, globalThis.setInterval, globalThis.clearTimeout, globalThis.clearInterval, {});
+        // The entry should export a function: module.exports = async function(ctx, lifo) { ... }
+        const handler = typeof module.exports === 'function'
+            ? module.exports
+            : module.exports.default;
+        if (typeof handler !== 'function') {
+            ctx.stderr.write(`lifo: ${entryPath} does not export a command function\n`);
+            return Promise.resolve(1);
+        }
+        return handler(ctx, lifo)
+            .then(code => typeof code === 'number' ? code : 0);
+    }
+    catch (e) {
+        if (e instanceof ProcessExitError) {
+            return Promise.resolve(e.exitCode);
+        }
+        if (e instanceof Error) {
+            ctx.stderr.write(`${e.stack || e.message}\n`);
+        }
+        else {
+            ctx.stderr.write(`${String(e)}\n`);
+        }
+        return Promise.resolve(1);
+    }
+}
+/**
+ * Read a package.json and return the lifo manifest if present.
+ */
+export function readLifoManifest(vfs, pkgDir) {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    try {
+        const pkg = JSON.parse(vfs.readFileString(pkgJsonPath));
+        return pkg.lifo || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/substrate/lifo/pkg/loader.d.ts

@@ -0,0 +1,4 @@
+import type { VFS } from '../kernel/vfs/index.js';
+import type { CommandRegistry } from '../commands/registry.js';
+export declare function loadInstalledPackages(vfs: VFS, registry: CommandRegistry): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/substrate/lifo/pkg/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../src/substrate/lifo/pkg/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAM/D,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAyB/E"}

package/dist/substrate/lifo/pkg/loader.js

@@ -0,0 +1,24 @@
+const METADATA_FILE = '/usr/share/pkg/packages.json';
+const MODULES_DIR = '/usr/share/pkg/node_modules';
+export function loadInstalledPackages(vfs, registry) {
+    let meta;
+    try {
+        const content = vfs.readFileString(METADATA_FILE);
+        meta = JSON.parse(content);
+    }
+    catch {
+        return; // No packages installed
+    }
+    for (const name of Object.keys(meta.packages)) {
+        const scriptPath = `${MODULES_DIR}/${name}/index.js`;
+        if (!vfs.exists(scriptPath))
+            continue;
+        // Register as a lazy command that invokes `node <script>`
+        registry.registerLazy(name, () => import('../commands/system/node.js').then((mod) => ({
+            default: ((ctx) => mod.default({
+                ...ctx,
+                args: [scriptPath, ...ctx.args],
+            })),
+        })));
+    }
+}

package/dist/substrate/lifo/sandbox/HeadlessTerminal.d.ts

@@ -0,0 +1,18 @@
+import type { ITerminal } from '../terminal/ITerminal.js';
+/**
+ * A Terminal-shaped class that captures output without xterm.js.
+ * Used for headless/programmatic Sandbox usage (AI agents, tests, etc.)
+ */
+export declare class HeadlessTerminal implements ITerminal {
+    private dataCallback;
+    write(_data: string): void;
+    writeln(_data: string): void;
+    onData(cb: (data: string) => void): void;
+    get cols(): number;
+    get rows(): number;
+    focus(): void;
+    clear(): void;
+    /** Send data as if typed on keyboard (used internally for stdin) */
+    sendData(data: string): void;
+}
+//# sourceMappingURL=HeadlessTerminal.d.ts.map

package/dist/substrate/lifo/sandbox/HeadlessTerminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeadlessTerminal.d.ts","sourceRoot":"","sources":["../../../../src/substrate/lifo/sandbox/HeadlessTerminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,YAAY,CAAyC;IAE7D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI1B,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI5B,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAIxC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,IAAI,IAAI;IAEb,KAAK,IAAI,IAAI;IAEb,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAG7B"}

package/dist/substrate/lifo/sandbox/HeadlessTerminal.js

@@ -0,0 +1,28 @@
+/**
+ * A Terminal-shaped class that captures output without xterm.js.
+ * Used for headless/programmatic Sandbox usage (AI agents, tests, etc.)
+ */
+export class HeadlessTerminal {
+    dataCallback = null;
+    write(_data) {
+        // Headless mode: discard visual output
+    }
+    writeln(_data) {
+        // Headless mode: discard visual output
+    }
+    onData(cb) {
+        this.dataCallback = cb;
+    }
+    get cols() {
+        return 80;
+    }
+    get rows() {
+        return 24;
+    }
+    focus() { }
+    clear() { }
+    /** Send data as if typed on keyboard (used internally for stdin) */
+    sendData(data) {
+        this.dataCallback?.(data);
+    }
+}

package/dist/substrate/lifo/sandbox/Sandbox.d.ts

@@ -0,0 +1,59 @@
+import { Kernel } from '../kernel/index.js';
+import { Shell } from '../shell/Shell.js';
+import type { NativeFsModule } from '../kernel/vfs/providers/NativeFsProvider.js';
+import type { SandboxOptions, SandboxCommands, SandboxFs } from './types.js';
+export declare class Sandbox {
+    /** Programmatic command execution */
+    readonly commands: SandboxCommands;
+    /** Filesystem operations */
+    readonly fs: SandboxFs;
+    /** Environment variables */
+    readonly env: Record<string, string>;
+    readonly kernel: Kernel;
+    readonly shell: Shell;
+    private _destroyed;
+    private constructor();
+    /** Current working directory */
+    get cwd(): string;
+    set cwd(path: string);
+    /**
+     * Create a new Sandbox instance.
+     * Orchestrates all boot steps: Kernel, VFS, Registry, Shell, config sourcing.
+     */
+    static create(options?: SandboxOptions): Promise<Sandbox>;
+    /**
+     * Mount a native filesystem directory into the virtual filesystem.
+     * Only works in Node.js environments (or when a custom fsModule is provided).
+     *
+     * Once mounted, all VFS operations (and therefore the node-compat fs shim)
+     * on paths under `virtualPath` will be delegated through the VFS mount system
+     * to the NativeFsProvider, which in turn delegates to the real node:fs module.
+     *
+     * @param virtualPath - Path inside the virtual filesystem (e.g. "/mnt/project")
+     * @param hostPath - Host filesystem path to mount (e.g. "/home/user/my-project")
+     * @param options - Optional settings: readOnly, fsModule
+     */
+    mountNative(virtualPath: string, hostPath: string, options?: {
+        readOnly?: boolean;
+        fsModule?: NativeFsModule;
+    }): void;
+    /**
+     * Unmount a previously mounted filesystem.
+     *
+     * @param virtualPath - The virtual path that was passed to mountNative()
+     */
+    unmountNative(virtualPath: string): void;
+    /**
+     * Export the entire VFS as a tar.gz snapshot.
+     */
+    exportSnapshot(): Promise<Uint8Array>;
+    /**
+     * Restore VFS from a tar.gz snapshot.
+     */
+    importSnapshot(data: Uint8Array): Promise<void>;
+    /**
+     * Destroy the sandbox, releasing all resources.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=Sandbox.d.ts.map

package/dist/substrate/lifo/sandbox/Sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sandbox.d.ts","sourceRoot":"","sources":["../../../../src/substrate/lifo/sandbox/Sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAsB1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAElF,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK7E,qBAAa,OAAO;IACnB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO;IAcP,gCAAgC;IAChC,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,EAEnB;IAED;;;OAGG;WACU,MAAM,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAuH/D;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAgCrH;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAKxC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC;IAI3C;;OAEG;IACG,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD;;OAEG;IACH,OAAO,IAAI,IAAI;CAGf"}