@nimbus-sh/core 0.1.0

package/src/substrate/lifo/sandbox/Sandbox.ts

@@ -0,0 +1,279 @@
+import { Kernel } from '../kernel/index.js';
+import { Shell } from '../shell/Shell.js';
+import {
+	createDefaultRegistry,
+} from '../commands/registry.js';
+import { createPsCommand } from '../commands/system/ps.js';
+import { createTopCommand } from '../commands/system/top.js';
+import { createKillCommand } from '../commands/system/kill.js';
+import { createWatchCommand } from '../commands/system/watch.js';
+import { createHelpCommand } from '../commands/system/help.js';
+import { createNodeCommand } from '../commands/system/node.js';
+import { createCurlCommand } from '../commands/net/curl.js';
+import { createTunnelCommandV2 } from '../commands/net/tunnel-v2.js';
+import { createIfconfigCommand } from '../commands/net/ifconfig.js';
+import { createRouteCommand } from '../commands/net/route.js';
+import { createNetstatCommand } from '../commands/net/netstat.js';
+import { createHostCommand } from '../commands/net/host.js';
+import { createIPCommand } from '../commands/net/ip.js';
+import { createNpmCommand, createNpxCommand } from '../commands/system/npm.js';
+import { createLifoPkgCommand, bootLifoPackages } from '../commands/system/lifo.js';
+import { createSystemctlCommand } from '../commands/system/systemctl.js';
+import type { VFS } from '../kernel/vfs/index.js';
+import { NativeFsProvider } from '../kernel/vfs/providers/NativeFsProvider.js';
+import type { NativeFsModule } from '../kernel/vfs/providers/NativeFsProvider.js';
+import type { ITerminal } from '../terminal/ITerminal.js';
+import type { SandboxOptions, SandboxCommands, SandboxFs } from './types.js';
+import { SandboxFsImpl } from './SandboxFs.js';
+import { SandboxCommandsImpl } from './SandboxCommands.js';
+import { HeadlessTerminal } from './HeadlessTerminal.js';
+
+export class Sandbox {
+	/** Programmatic command execution */
+	readonly commands: SandboxCommands;
+	/** Filesystem operations */
+	readonly fs: SandboxFs;
+	/** Environment variables */
+	readonly env: Record<string, string>;
+
+	// Power-user escape hatches
+	readonly kernel: Kernel;
+	readonly shell: Shell;
+
+	private _destroyed = false;
+
+	private constructor(
+		kernel: Kernel,
+		shell: Shell,
+		commands: SandboxCommands,
+		fs: SandboxFs,
+		env: Record<string, string>,
+	) {
+		this.kernel = kernel;
+		this.shell = shell;
+		this.commands = commands;
+		this.fs = fs;
+		this.env = env;
+	}
+
+	/** Current working directory */
+	get cwd(): string {
+		return this.shell.getCwd();
+	}
+
+	set cwd(path: string) {
+		this.shell.setCwd(path);
+	}
+
+	/**
+	 * Create a new Sandbox instance.
+	 * Orchestrates all boot steps: Kernel, VFS, Registry, Shell, config sourcing.
+	 */
+	static async create(options?: SandboxOptions): Promise<Sandbox> {
+		// 1. Create and boot kernel
+		const kernel = new Kernel();
+		await kernel.boot({ persist: options?.persist ?? false });
+
+		// 1b. Provider-backed directories, before anything reads the filesystem.
+		// `initFilesystem` has already seeded the in-memory tree; mounting after
+		// it is what keeps a durable /etc from being overwritten by the defaults
+		// on every boot, and mounting before step 8 is what lets the profile
+		// sourced there be the durable one.
+		for (const mount of options?.providerMounts ?? []) {
+			kernel.vfs.mount(mount.virtualPath, mount.provider);
+		}
+
+		// 2. Create command registry
+		const registry = createDefaultRegistry();
+		bootLifoPackages(kernel.vfs, registry);
+
+		// 3. Pre-populate files if provided
+		if (options?.files) {
+			for (const [path, content] of Object.entries(options.files)) {
+				ensureParentDirs(kernel.vfs, path);
+				kernel.vfs.writeFile(path, content);
+			}
+		}
+
+		// 4. Set up environment
+		const defaultEnv = kernel.getDefaultEnv();
+		const env = { ...defaultEnv, ...options?.env };
+		if (options?.cwd) {
+			env.PWD = options.cwd;
+		}
+
+		// 5. Create terminal
+		let shellTerminal: ITerminal;
+		let isVisual = false;
+
+		if (options?.terminal) {
+			shellTerminal = options.terminal;
+			isVisual = true;
+		} else {
+			shellTerminal = new HeadlessTerminal();
+		}
+
+		// 6. Create shell
+		const shell = new Shell(shellTerminal, kernel.vfs, registry, env, kernel.processRegistry);
+
+		// 7. Register factory commands
+		const processRegistry = shell.getProcessRegistry();
+		registry.register('ps', createPsCommand(processRegistry));
+		registry.register('top', createTopCommand(processRegistry));
+		registry.register('kill', createKillCommand(processRegistry));
+		registry.register('watch', createWatchCommand(registry));
+		registry.register('help', createHelpCommand(registry));
+		registry.register('node', createNodeCommand(kernel));
+		registry.register('curl', createCurlCommand(kernel));
+		registry.register('tunnel', createTunnelCommandV2(kernel));
+
+		// Register network commands
+		registry.register('ifconfig', createIfconfigCommand(kernel));
+		registry.register('route', createRouteCommand(kernel));
+		registry.register('netstat', createNetstatCommand(kernel));
+		registry.register('host', createHostCommand(kernel));
+		registry.register('ip', createIPCommand(kernel));
+
+		// Register npm with shell execution support
+		const npmShellExecute = async (cmd: string, cmdCtx: { cwd: string; env: Record<string, string>; stdout: { write: (s: string) => void }; stderr: { write: (s: string) => void } }) => {
+			const result = await shell.execute(cmd, {
+				cwd: cmdCtx.cwd,
+				env: cmdCtx.env,
+				onStdout: (data: string) => cmdCtx.stdout.write(data),
+				onStderr: (data: string) => cmdCtx.stderr.write(data),
+			});
+			return result.exitCode;
+		};
+		registry.register('npm', createNpmCommand(registry, npmShellExecute, kernel));
+		registry.register('npx', createNpxCommand(registry, npmShellExecute));
+		registry.register('lifo', createLifoPkgCommand(registry, npmShellExecute, kernel));
+		// 7b. Service manager & systemctl
+		kernel.initServiceManager(registry, env);
+		registry.register('systemctl', createSystemctlCommand(kernel));
+
+		// 8. Source config files
+		await shell.sourceFile('/etc/profile');
+		await shell.sourceFile(env.HOME + '/.bashrc');
+
+		// 9. Set initial cwd if provided
+		if (options?.cwd) {
+			shell.setCwd(options.cwd);
+		}
+		// 9b. Boot enabled services
+		await kernel.bootServices();
+
+		// 10. Start shell (for visual mode, enables interactive input)
+		if (isVisual) {
+			shell.start();
+			shellTerminal.focus();
+		}
+
+		// 11. Build the Sandbox
+		const getCwd = () => shell.getCwd();
+		const sandboxFs = new SandboxFsImpl(kernel.vfs, getCwd);
+		const sandboxCommands = new SandboxCommandsImpl(shell, registry);
+
+		const sandbox = new Sandbox(kernel, shell, sandboxCommands, sandboxFs, env);
+
+		// 12. Mount native filesystems if specified in options
+		if (options?.mounts) {
+			for (const mount of options.mounts) {
+				sandbox.mountNative(mount.virtualPath, mount.hostPath, {
+					readOnly: mount.readOnly,
+					fsModule: mount.fsModule,
+				});
+			}
+		}
+
+		return 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 {
+		if (this._destroyed) throw new Error('Sandbox is destroyed');
+
+		let fsModule = options?.fsModule;
+
+		if (!fsModule) {
+			// Try to get the native fs module. This only works in Node.js environments.
+			// We use a dynamic require pattern that works at runtime but avoids
+			// static analysis by bundlers.
+			try {
+				// eslint-disable-next-line @typescript-eslint/no-require-imports
+				const mod = 'node:fs';
+				fsModule = (globalThis as unknown as Record<string, Function>).require?.(mod) as NativeFsModule | undefined;
+			} catch {
+				// globalThis.require may not exist
+			}
+
+			if (!fsModule) {
+				throw new Error(
+					'mountNative requires a Node.js environment or a custom fsModule. ' +
+					'Pass { fsModule: require("node:fs") } in a Node.js environment, ' +
+					'or provide a compatible NativeFsModule implementation.'
+				);
+			}
+		}
+
+		const provider = new NativeFsProvider(hostPath, fsModule, {
+			readOnly: options?.readOnly ?? false,
+		});
+		this.kernel.vfs.mount(virtualPath, provider);
+	}
+
+	/**
+	 * Unmount a previously mounted filesystem.
+	 *
+	 * @param virtualPath - The virtual path that was passed to mountNative()
+	 */
+	unmountNative(virtualPath: string): void {
+		if (this._destroyed) throw new Error('Sandbox is destroyed');
+		this.kernel.vfs.unmount(virtualPath);
+	}
+
+	/**
+	 * Export the entire VFS as a tar.gz snapshot.
+	 */
+	async exportSnapshot(): Promise<Uint8Array> {
+		return this.fs.exportSnapshot();
+	}
+
+	/**
+	 * Restore VFS from a tar.gz snapshot.
+	 */
+	async importSnapshot(data: Uint8Array): Promise<void> {
+		return this.fs.importSnapshot(data);
+	}
+
+	/**
+	 * Destroy the sandbox, releasing all resources.
+	 */
+	destroy(): void {
+		this._destroyed = true;
+	}
+}
+
+// ─── Helpers ───
+
+function ensureParentDirs(vfs: VFS, filePath: string): void {
+	const parts = filePath.split('/').filter(Boolean);
+	parts.pop(); // remove filename
+	let current = '';
+	for (const part of parts) {
+		current += '/' + part;
+		if (!vfs.exists(current)) {
+			vfs.mkdir(current, { recursive: true });
+		}
+	}
+}

package/src/substrate/lifo/sandbox/SandboxCommands.ts

@@ -0,0 +1,74 @@
+import type { Shell } from '../shell/Shell.js';
+import type { CommandRegistry } from '../commands/registry.js';
+import type { Command } from '../commands/types.js';
+import type { SandboxCommands as ISandboxCommands, RunOptions, CommandResult } from './types.js';
+
+/**
+ * Wraps Shell.execute() and serializes concurrent calls.
+ * Concurrent commands.run() calls are queued (matches real shell behavior).
+ */
+export class SandboxCommandsImpl implements ISandboxCommands {
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(
+    private shell: Shell,
+    readonly registry: CommandRegistry,
+  ) {}
+
+  run(cmd: string, options?: RunOptions): Promise<CommandResult> {
+    // Serialize execution: queue each call so they run one at a time
+    const result = new Promise<CommandResult>((resolve, reject) => {
+      this.queue = this.queue.then(async () => {
+        try {
+          const res = await this.executeWithOptions(cmd, options);
+          resolve(res);
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+    return result;
+  }
+
+  register(name: string, handler: Command): void {
+    this.registry.register(name, handler);
+  }
+
+  private async executeWithOptions(cmd: string, options?: RunOptions): Promise<CommandResult> {
+    // Handle timeout + abort signal
+    let abortController: AbortController | undefined;
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    if (options?.timeout || options?.signal) {
+      abortController = new AbortController();
+
+      if (options.signal) {
+        // Forward external signal
+        if (options.signal.aborted) {
+          return { stdout: '', stderr: '', exitCode: 130 };
+        }
+        options.signal.addEventListener('abort', () => abortController!.abort(), { once: true });
+      }
+
+      if (options.timeout) {
+        timeoutId = setTimeout(() => abortController!.abort(), options.timeout);
+      }
+    }
+
+    try {
+      const result = await this.shell.execute(cmd, {
+        cwd: options?.cwd,
+        env: options?.env,
+        onStdout: options?.onStdout,
+        onStderr: options?.onStderr,
+        stdin: options?.stdin,
+      });
+
+      return result;
+    } finally {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+}

package/src/substrate/lifo/sandbox/SandboxFs.ts

@@ -0,0 +1,160 @@
+import type { VFS } from '../kernel/vfs/index.js';
+import type { SandboxFs as ISandboxFs } from './types.js';
+import type { FileType } from '../kernel/vfs/types.js';
+import { resolve, dirname } from '../utils/path.js';
+import { createTar, parseTar, compressGzip, decompressGzip } from '../utils/archive.js';
+import type { TarEntry } from '../utils/archive.js';
+
+/**
+ * Async wrapper around VFS that matches the industry-standard filesystem API.
+ * Sync VFS behind async interface future-proofs for async persistence.
+ */
+export class SandboxFsImpl implements ISandboxFs {
+  constructor(
+    private vfs: VFS,
+    private getCwd: () => string,
+  ) {}
+
+  private resolvePath(path: string): string {
+    return resolve(this.getCwd(), path);
+  }
+
+  readFile(path: string): Promise<string>;
+  readFile(path: string, encoding: null): Promise<Uint8Array>;
+  readFile(path: string, encoding?: null): Promise<string | Uint8Array> {
+    const abs = this.resolvePath(path);
+    if (encoding === null) {
+      return Promise.resolve(this.vfs.readFile(abs));
+    }
+    return Promise.resolve(this.vfs.readFileString(abs));
+  }
+
+  async writeFile(path: string, content: string | Uint8Array): Promise<void> {
+    const abs = this.resolvePath(path);
+    this.vfs.writeFile(abs, content);
+  }
+
+  async readdir(path: string): Promise<Array<{ name: string; type: FileType }>> {
+    const abs = this.resolvePath(path);
+    return this.vfs.readdir(abs);
+  }
+
+  async stat(path: string): Promise<{ type: FileType; size: number; mtime: number }> {
+    const abs = this.resolvePath(path);
+    const s = this.vfs.stat(abs);
+    return { type: s.type, size: s.size, mtime: s.mtime };
+  }
+
+  async mkdir(path: string, options?: { recursive?: boolean }): Promise<void> {
+    const abs = this.resolvePath(path);
+    this.vfs.mkdir(abs, options);
+  }
+
+  async rm(path: string, options?: { recursive?: boolean }): Promise<void> {
+    const abs = this.resolvePath(path);
+    const s = this.vfs.stat(abs);
+    if (s.type === 'directory') {
+      if (options?.recursive) {
+        this.vfs.rmdirRecursive(abs);
+      } else {
+        this.vfs.rmdir(abs);
+      }
+    } else {
+      this.vfs.unlink(abs);
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    const abs = this.resolvePath(path);
+    return this.vfs.exists(abs);
+  }
+
+  async rename(oldPath: string, newPath: string): Promise<void> {
+    const absOld = this.resolvePath(oldPath);
+    const absNew = this.resolvePath(newPath);
+    this.vfs.rename(absOld, absNew);
+  }
+
+  async cp(src: string, dest: string): Promise<void> {
+    const absSrc = this.resolvePath(src);
+    const absDest = this.resolvePath(dest);
+    this.vfs.copyFile(absSrc, absDest);
+  }
+
+  async writeFiles(files: Array<{ path: string; content: string | Uint8Array }>): Promise<void> {
+    for (const { path, content } of files) {
+      await this.writeFile(path, content);
+    }
+  }
+
+  /** Directories to skip during export (virtual providers) */
+  private static SKIP_DIRS = new Set(['/proc', '/dev']);
+
+  async exportSnapshot(): Promise<Uint8Array> {
+    const entries: TarEntry[] = [];
+
+    const walk = (absPath: string): void => {
+      if (SandboxFsImpl.SKIP_DIRS.has(absPath)) return;
+
+      const stat = this.vfs.stat(absPath);
+
+      if (stat.type === 'directory') {
+        // Add directory entry (skip root itself)
+        if (absPath !== '/') {
+          entries.push({
+            path: absPath,
+            data: new Uint8Array(0),
+            type: 'directory',
+            mode: stat.mode,
+            mtime: stat.mtime,
+          });
+        }
+
+        const children = this.vfs.readdir(absPath);
+        for (const child of children) {
+          const childPath = absPath === '/' ? `/${child.name}` : `${absPath}/${child.name}`;
+          walk(childPath);
+        }
+      } else {
+        entries.push({
+          path: absPath,
+          data: this.vfs.readFile(absPath),
+          type: 'file',
+          mode: stat.mode,
+          mtime: stat.mtime,
+        });
+      }
+    };
+
+    walk('/');
+
+    const tar = createTar(entries);
+    return compressGzip(tar);
+  }
+
+  async importSnapshot(data: Uint8Array): Promise<void> {
+    const tar = await decompressGzip(data);
+    const entries = parseTar(tar);
+
+    // Process directories first, then files, to ensure parents exist
+    const dirs = entries.filter((e) => e.type === 'directory');
+    const files = entries.filter((e) => e.type === 'file');
+
+    for (const entry of dirs) {
+      const path = entry.path.startsWith('/') ? entry.path : '/' + entry.path;
+      if (!this.vfs.exists(path)) {
+        this.vfs.mkdir(path, { recursive: true });
+      }
+    }
+
+    for (const entry of files) {
+      const path = entry.path.startsWith('/') ? entry.path : '/' + entry.path;
+      // Ensure parent directory exists
+      const parent = dirname(path);
+      if (parent !== '/' && !this.vfs.exists(parent)) {
+        this.vfs.mkdir(parent, { recursive: true });
+      }
+      this.vfs.writeFile(path, entry.data);
+    }
+  }
+}

package/src/substrate/lifo/sandbox/index.ts

@@ -0,0 +1,8 @@
+export { Sandbox } from './Sandbox.js';
+export type {
+  SandboxOptions,
+  RunOptions,
+  CommandResult,
+  SandboxCommands,
+  SandboxFs,
+} from './types.js';

package/src/substrate/lifo/sandbox/types.ts

@@ -0,0 +1,117 @@
+import type { Command } from '../commands/types.js';
+import type { CommandRegistry } from '../commands/registry.js';
+import type { Kernel } from '../kernel/index.js';
+import type { Shell } from '../shell/Shell.js';
+import type { ITerminal } from '../terminal/ITerminal.js';
+import type { NativeFsModule } from '../kernel/vfs/providers/NativeFsProvider.js';
+import type { FileType, MountProvider } from '../kernel/vfs/types.js';
+
+// ─── Sandbox Options ───
+
+export interface SandboxOptions {
+  /** Enable kernel persistence through the configured backend (default: false). */
+  persist?: boolean;
+  /** Extra environment variables (merged with defaults) */
+  env?: Record<string, string>;
+  /** Initial working directory (default: /home/user) */
+  cwd?: string;
+  /** Pre-populate files: path → content */
+  files?: Record<string, string | Uint8Array>;
+  /** Attach a pre-created ITerminal for visual mode */
+  terminal?: ITerminal;
+  /**
+   * Mount native filesystem directories into the virtual filesystem at boot time.
+   * Only works in Node.js environments (or when a custom fsModule is provided).
+   */
+  mounts?: Array<{
+    /** Path inside the virtual filesystem where the mount will appear */
+    virtualPath: string;
+    /** Host filesystem path to mount */
+    hostPath: string;
+    /** If true, the mount is read-only (default: false) */
+    readOnly?: boolean;
+    /** Custom fs module implementing NativeFsModule. If omitted, node:fs is used. */
+    fsModule?: NativeFsModule;
+  }>;
+  /**
+   * Directories whose storage comes from a provider rather than from the
+   * in-memory tree — a durable filesystem, for instance.
+   *
+   * Applied before anything reads the filesystem, because boot reads it:
+   * `create` sources `/etc/profile`, and a provider that arrived afterwards
+   * would have been invisible to it. Native `mounts` overlay an already-booted
+   * sandbox and keep their existing position.
+   */
+  providerMounts?: Array<{
+    /** Path inside the virtual filesystem where the mount will appear. */
+    virtualPath: string;
+    /** Supplies every operation under `virtualPath`. */
+    provider: MountProvider;
+  }>;
+}
+
+// ─── Command Execution ───
+
+export interface RunOptions {
+  /** Working directory for this command */
+  cwd?: string;
+  /** Extra environment variables for this command */
+  env?: Record<string, string>;
+  /** Abort signal to cancel the command */
+  signal?: AbortSignal;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Streaming stdout callback */
+  onStdout?: (data: string) => void;
+  /** Streaming stderr callback */
+  onStderr?: (data: string) => void;
+  /** Provide stdin content */
+  stdin?: string;
+}
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+// ─── SandboxCommands ───
+
+export interface SandboxCommands {
+  run(cmd: string, options?: RunOptions): Promise<CommandResult>;
+  register(name: string, handler: Command): void;
+  /**
+   * The command table itself, for layering a command set over the defaults.
+   * Public because composing a workspace means replacing builtins wholesale —
+   * the durable-filesystem coreutils override ~25 of them — and every caller
+   * that needed it was already reaching through the private field.
+   */
+  readonly registry: CommandRegistry;
+}
+
+// ─── SandboxFs ───
+
+export interface SandboxFs {
+  readFile(path: string): Promise<string>;
+  readFile(path: string, encoding: null): Promise<Uint8Array>;
+  writeFile(path: string, content: string | Uint8Array): Promise<void>;
+  readdir(path: string): Promise<Array<{ name: string; type: FileType }>>;
+  stat(path: string): Promise<{ type: FileType; size: number; mtime: number }>;
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+  rm(path: string, options?: { recursive?: boolean }): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  rename(oldPath: string, newPath: string): Promise<void>;
+  cp(src: string, dest: string): Promise<void>;
+  writeFiles(files: Array<{ path: string; content: string | Uint8Array }>): Promise<void>;
+  /** Export entire VFS as a tar.gz snapshot */
+  exportSnapshot(): Promise<Uint8Array>;
+  /** Restore VFS from a tar.gz snapshot */
+  importSnapshot(data: Uint8Array): Promise<void>;
+}
+
+// ─── Internal types for Sandbox internals ───
+
+export interface SandboxInternals {
+  kernel: Kernel;
+  shell: Shell;
+}