sharjeenux 0.3.0

package/index.js

@@ -0,0 +1,465 @@
+import { createHash, randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { V86 } from "v86";
+
+const ASSETS_URL = new URL("./assets/", import.meta.url);
+const CACHE_ROOT = path.join(tmpdir(), "sharjeenux", "decoded-assets-v1");
+const ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+const DEFAULTS = Object.freeze({
+  memoryMB: 2048,
+  bootTimeoutMs: 180_000,
+  commandTimeoutMs: 1_800_000,
+  networking: true,
+  networkRelayUrl: "fetch",
+  verifyAssets: true,
+});
+
+let defaultInstance;
+let manifestPromise;
+
+export class CommandTimeoutError extends Error {
+  constructor(command, output, timeoutMs) {
+    super(`Command timed out after ${timeoutMs} ms: ${command}`);
+    this.name = "CommandTimeoutError";
+    this.command = command;
+    this.output = output;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function cleanOutput(value) {
+  return value
+    .replace(/\r/g, "")
+    .replace(ANSI_PATTERN, "")
+    .replace(/[\t ]+\n/g, "\n")
+    .replace(/^\n+|\n+$/g, "");
+}
+
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function toArrayBuffer(buffer) {
+  return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+}
+
+async function getManifest() {
+  manifestPromise ||= readFile(new URL("manifest.json", ASSETS_URL), "utf8").then(JSON.parse);
+  return manifestPromise;
+}
+
+async function loadImage(name, verify) {
+  const manifest = await getManifest();
+  const image = manifest.images[name];
+  if (!image) throw new Error(`Image is missing from asset manifest: ${name}`);
+
+  const cachePath = path.join(CACHE_ROOT, `${name}-${image.sha256}.bin`);
+  try {
+    const cached = await readFile(cachePath);
+    if (cached.length === image.bytes) {
+      if (!verify || createHash("sha256").update(cached).digest("hex") === image.sha256) {
+        return toArrayBuffer(cached);
+      }
+    }
+  } catch {
+    // A cold or read-only cache is valid; chunks remain the source of truth.
+  }
+
+  const output = Buffer.allocUnsafe(image.bytes);
+  let cursor = 0;
+  const concurrency = 256;
+
+  for (let start = 0; start < image.chunks; start += concurrency) {
+    const end = Math.min(image.chunks, start + concurrency);
+    const parts = await Promise.all(Array.from({ length: end - start }, (_, offset) => {
+      const serial = String(start + offset).padStart(6, "0");
+      return readFile(new URL(`chunks/${name}/${serial.slice(0, 3)}/${serial}.b64`, ASSETS_URL), "ascii");
+    }));
+
+    for (const part of parts) {
+      const decoded = Buffer.from(part, "base64");
+      decoded.copy(output, cursor);
+      cursor += decoded.length;
+    }
+  }
+
+  if (cursor !== image.bytes) {
+    throw new Error(`Decoded ${name} size mismatch: expected ${image.bytes}, received ${cursor}`);
+  }
+  if (verify) {
+    const digest = createHash("sha256").update(output).digest("hex");
+    if (digest !== image.sha256) throw new Error(`SHA-256 mismatch for ${name}`);
+  }
+  try {
+    await mkdir(CACHE_ROOT, { recursive: true });
+    await writeFile(cachePath, output);
+  } catch {
+    // Cache writes are an optimization and must not prevent booting.
+  }
+  return toArrayBuffer(output);
+}
+
+function validateOptions(options) {
+  const value = { ...DEFAULTS, ...options };
+  if (!Number.isInteger(value.memoryMB) || value.memoryMB < 128 || (value.memoryMB & (value.memoryMB - 1)) !== 0) {
+    throw new TypeError("memoryMB must be a power-of-two integer of at least 128");
+  }
+  for (const name of ["bootTimeoutMs", "commandTimeoutMs"]) {
+    if (!Number.isFinite(value[name]) || value[name] < 0) throw new TypeError(`${name} must be a non-negative number`);
+  }
+  if (typeof value.networkRelayUrl !== "string" || !/^(?:fetch|wisps?:\/\/)/.test(value.networkRelayUrl)) {
+    throw new TypeError('networkRelayUrl must be "fetch" or a wisp:// / wisps:// URL');
+  }
+  return value;
+}
+
+export class Sharjeenux extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = validateOptions(options);
+    this.ready = false;
+    this._emulator = null;
+    this._initializePromise = null;
+    this._phase = "idle";
+    this._serial = "";
+    this._active = null;
+    this._queue = Promise.resolve();
+    this._serialListener = byte => this._onSerialByte(byte);
+  }
+
+  initialize() {
+    this._initializePromise ||= this._initialize();
+    return this._initializePromise;
+  }
+
+  async _initialize() {
+    this._phase = "loading";
+    if (this.options.networkRelayUrl !== "fetch" && typeof globalThis.WebSocket === "undefined") {
+      const { WebSocket } = await import("ws");
+      globalThis.WebSocket = WebSocket;
+    }
+    const manifest = await getManifest();
+    const [bios, vgabios, kernel, initrd] = await Promise.all([
+      loadImage("bios", this.options.verifyAssets),
+      loadImage("vgabios", this.options.verifyAssets),
+      loadImage("kernel", this.options.verifyAssets),
+      manifest.images.initrd ? loadImage("initrd", this.options.verifyAssets) : undefined,
+    ]);
+
+    const wasmPath = fileURLToPath(import.meta.resolve("v86/build/v86.wasm"));
+    const boot = deferred();
+    this._boot = boot;
+    this._phase = "booting";
+
+    const emulatorOptions = {
+      wasm_path: wasmPath,
+      bios: { buffer: bios },
+      vga_bios: { buffer: vgabios },
+      bzimage: { buffer: kernel },
+      memory_size: this.options.memoryMB * 1024 * 1024,
+      filesystem: {},
+      net_device: this.options.networking ? {
+        type: "virtio",
+        relay_url: this.options.networkRelayUrl,
+        mtu: 1500,
+      } : undefined,
+      cmdline: "console=ttyS0 rootfstype=ramfs tsc=reliable mitigations=off random.trust_cpu=on",
+      autostart: true,
+      disable_keyboard: true,
+      disable_mouse: true,
+      disable_speaker: true,
+    };
+    if (initrd) emulatorOptions.initrd = { buffer: initrd };
+    this._emulator = new V86(emulatorOptions);
+    this._emulator.add_listener("serial0-output-byte", this._serialListener);
+
+    const timer = setTimeout(() => {
+      boot.reject(new Error(`Sharjeenux did not boot within ${this.options.bootTimeoutMs} ms`));
+    }, this.options.bootTimeoutMs);
+
+    try {
+      await boot.promise;
+      this.ready = true;
+      this._phase = "ready";
+      this._serial = "";
+      this.emit("ready");
+      return this;
+    } catch (error) {
+      await this.shutdown();
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      this._boot = null;
+    }
+  }
+
+  _onSerialByte(byte) {
+    const character = String.fromCharCode(byte);
+    this._serial = (this._serial + character).slice(-1_000_000);
+
+    if (this._phase === "booting" && /(?:^|\n)[^\n]*%\s*$/.test(this._serial.replace(/\r/g, ""))) {
+      this._phase = "setup";
+      const network = this.options.networking ? "udhcpc -q >/dev/null 2>&1 || true;" : "";
+      this._emulator.serial0_send(
+        `stty -echo rows 24 cols 80; export PATH=/usr/local/bin:/opt/maven/bin:/usr/bin:/bin:/usr/sbin:/sbin HOME=/mnt/home TMPDIR=/mnt/tmp TERM=xterm NO_COLOR=1 CI=1 ` +
+        `NODE_OPTIONS=--max-old-space-size=512 JAVA_HOME=/usr/lib/jvm MAVEN_HOME=/opt/maven ` +
+        `MAVEN_ARGS='--settings /etc/maven-settings.xml' PIP_CACHE_DIR=/mnt/pip-cache; ` +
+        `export npm_config_progress=false npm_config_color=false npm_config_update_notifier=false ` +
+        `npm_config_yes=true npm_config_audit=false npm_config_fund=false ` +
+        `npm_config_cache=/mnt/npm-cache npm_config_registry=http://registry.npmjs.org/ npm_config_replace_registry_host=always ` +
+        `npm_config_fetch_retries=5 npm_config_fetch_retry_mintimeout=10000 npm_config_fetch_retry_maxtimeout=120000 ` +
+        `npm_config_fetch_timeout=600000 npm_config_maxsockets=6; ` +
+        `mkdir -p /mnt/workspace /mnt/home /mnt/tmp /mnt/npm-cache /mnt/pip-cache /mnt/home/.m2/repository; cd /mnt/workspace; ` +
+        `PS1='__SHARJEENUX_PROMPT__ '; ${network} printf '\n__SHARJEENUX_READY__\n'\n`,
+      );
+      return;
+    }
+
+    if (this._phase === "setup" && /\n__SHARJEENUX_READY__\r?\n__SHARJEENUX_PROMPT__ $/.test(this._serial)) {
+      this._boot.resolve();
+      return;
+    }
+
+    if (this._phase !== "ready" || !this._active) return;
+    this._consumeActiveOutput();
+  }
+
+  _consumeActiveOutput() {
+    const active = this._active;
+    if (!active) return;
+    const text = this._serial.replace(/\r/g, "");
+    const begin = `${active.begin}\n`;
+    const beginIndex = text.indexOf(begin);
+    if (beginIndex < 0) return;
+
+    const bodyStart = beginIndex + begin.length;
+    const endPrefix = `\n${active.end}:`;
+    const endIndex = text.indexOf(endPrefix, bodyStart);
+    let streamEnd = endIndex >= 0 ? endIndex : text.length;
+    if (endIndex < 0) {
+      // Hold only a suffix that could actually become the private end marker.
+      // Holding the marker's full length would hide short interactive prompts
+      // (for example Node's `> `) until more output happened to arrive.
+      const body = text.slice(bodyStart);
+      const maximum = Math.min(endPrefix.length - 1, body.length);
+      for (let length = maximum; length > 0; length -= 1) {
+        if (body.endsWith(endPrefix.slice(0, length))) {
+          streamEnd -= length;
+          break;
+        }
+      }
+    }
+    const available = text.slice(bodyStart, streamEnd);
+
+    if (available.length > active.streamed) {
+      const chunk = available.slice(active.streamed);
+      active.streamed = available.length;
+      active.options.onOutput?.(chunk);
+      this.emit("output", chunk);
+    }
+
+    if (endIndex < 0) return;
+    const codeStart = endIndex + endPrefix.length;
+    const codeEnd = text.indexOf("\n", codeStart);
+    if (codeEnd < 0 || !text.slice(codeEnd + 1).includes("__SHARJEENUX_PROMPT__ ")) return;
+
+    const exitCode = Number.parseInt(text.slice(codeStart, codeEnd), 10);
+    const output = cleanOutput(text.slice(bodyStart, endIndex));
+    const result = {
+      command: active.command,
+      output,
+      exitCode: Number.isNaN(exitCode) ? 255 : exitCode,
+      durationMs: Date.now() - active.startedAt,
+    };
+
+    clearTimeout(active.timer);
+    clearTimeout(active.cancelTimer);
+    active.options.signal?.removeEventListener("abort", active.abortListener);
+    this._active = null;
+    this._serial = "";
+    if (active.cancelError) {
+      active.cancelError.output = output;
+      active.reject(active.cancelError);
+    } else {
+      active.resolve(result);
+    }
+  }
+
+  async exec(command, options = {}) {
+    if (typeof command !== "string" || command.includes("\0")) throw new TypeError("command must be a string without NUL bytes");
+    if (!command.trim()) return { command, output: "", exitCode: 0, durationMs: 0 };
+    await this.initialize();
+
+    const task = this._queue.then(() => this._execute(command, options));
+    this._queue = task.catch(() => undefined);
+    return task;
+  }
+
+  async send(command, options = {}) {
+    return (await this.exec(command, options)).output;
+  }
+
+  spawn(command, options = {}) {
+    return new RunningCommand(this, command, options);
+  }
+
+  write(data) {
+    if (!this._emulator || !this.ready) throw new Error("Sharjeenux is not ready");
+    if (typeof data !== "string") throw new TypeError("input must be a string");
+    this._emulator.serial0_send(data);
+  }
+
+  _execute(command, options) {
+    if (options.signal?.aborted) {
+      const error = new Error(`Command aborted: ${command}`);
+      error.name = "AbortError";
+      return Promise.reject(error);
+    }
+    const request = deferred();
+    const id = randomBytes(12).toString("hex");
+    const timeoutMs = options.timeoutMs ?? this.options.commandTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new TypeError("timeoutMs must be a non-negative number");
+
+    const active = {
+      command,
+      options,
+      resolve: request.resolve,
+      reject: request.reject,
+      begin: `__SHAZINUX_BEGIN_${id}__`,
+      end: `__SHAZINUX_END_${id}__`,
+      streamed: 0,
+      startedAt: Date.now(),
+      timer: null,
+      cancelTimer: null,
+      abortListener: null,
+      cancelError: null,
+    };
+    this._active = active;
+    this._serial = "";
+
+    const cancel = error => {
+      if (this._active !== active || active.cancelError) return;
+      active.cancelError = error;
+      this.interrupt();
+      active.cancelTimer = setTimeout(() => {
+        if (this._active !== active) return;
+        this._active = null;
+        this._serial = "";
+        this._emulator.serial0_send("\x03\n");
+        error.output = "";
+        active.reject(error);
+      }, 5_000);
+    };
+    active.abortListener = () => {
+      const error = new Error(`Command aborted: ${command}`);
+      error.name = "AbortError";
+      cancel(error);
+    };
+
+    options.signal?.addEventListener("abort", active.abortListener, { once: true });
+    if (timeoutMs > 0) {
+      active.timer = setTimeout(() => cancel(new CommandTimeoutError(command, "", timeoutMs)), timeoutMs);
+    }
+
+    const encoded = shellQuote(command);
+    const interactiveStart = options.interactive ? "stty echo; " : "";
+    const interactiveEnd = options.interactive ? "stty -echo; " : "";
+    this._emulator.serial0_send(
+      `__shazinux_cmd=${encoded}; printf '\n${active.begin}\n'; ${interactiveStart}eval "$__shazinux_cmd"; ` +
+      `__shazinux_code=$?; ${interactiveEnd}printf '\n${active.end}:%s\n' "$__shazinux_code"\n`,
+    );
+    return request.promise;
+  }
+
+  interrupt() {
+    this._emulator?.serial0_send("\x03");
+  }
+
+  async shutdown() {
+    this.ready = false;
+    this._phase = "shutdown";
+    if (this._active) {
+      clearTimeout(this._active.timer);
+      clearTimeout(this._active.cancelTimer);
+      this._active.reject(new Error("Sharjeenux shut down while a command was running"));
+      this._active = null;
+    }
+    if (this._emulator) {
+      this._emulator.remove_listener("serial0-output-byte", this._serialListener);
+      await this._emulator.destroy();
+      this._emulator = null;
+    }
+    this.emit("shutdown");
+  }
+}
+
+export class RunningCommand {
+  constructor(vm, command, options) {
+    this._vm = vm;
+    this._controller = new AbortController();
+    if (options.signal) {
+      if (options.signal.aborted) this._controller.abort();
+      else options.signal.addEventListener("abort", () => this._controller.abort(), { once: true });
+    }
+    this.result = vm.exec(command, { ...options, signal: this._controller.signal });
+    this.exit = this.result.then(
+      result => result.exitCode,
+      error => error?.name === "AbortError" ? 130 : error?.name === "CommandTimeoutError" ? 124 : 255,
+    );
+  }
+
+  write(data) {
+    this._vm.write(data);
+  }
+
+  kill() {
+    this._controller.abort();
+  }
+}
+
+export function create(options) {
+  return new Sharjeenux(options);
+}
+
+export async function initialize(options) {
+  defaultInstance ||= create(options);
+  await defaultInstance.initialize();
+  return defaultInstance;
+}
+
+export async function exec(command, options) {
+  return (await initialize()).exec(command, options);
+}
+
+export async function send(command, options) {
+  return (await initialize()).send(command, options);
+}
+
+export async function spawn(command, options) {
+  return (await initialize()).spawn(command, options);
+}
+
+export async function write(data) {
+  (await initialize()).write(data);
+}
+
+export async function shutdown() {
+  if (!defaultInstance) return;
+  const instance = defaultInstance;
+  defaultInstance = undefined;
+  await instance.shutdown();
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "sharjeenux",
+  "version": "0.3.0",
+  "description": "A headless Buildroot Linux VM with Node.js, Python, Java, package managers, and development tools, controlled from JavaScript.",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    },
+    "./features/*": "./features/*.js"
+  },
+  "files": [
+    "features/",
+    "index.cjs",
+    "index.d.ts",
+    "index.js",
+    "LICENSE",
+    "README.md",
+    "SOURCE_OFFER.md",
+    "compliance/",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "test:toolchain": "node test/toolchain.mjs",
+    "test:network": "node test/network.mjs",
+    "test:vite": "node test/vite.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "buildroot",
+    "linux",
+    "virtual-machine",
+    "v86",
+    "nodejs",
+    "npm",
+    "typescript",
+    "python",
+    "java",
+    "git",
+    "curl"
+  ],
+  "engines": {
+    "node": ">=20.6"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Sharjeel Baig",
+    "email": "dr.sharjeel.6@gmail.com"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "v86": "0.5.420",
+    "ws": "8.21.0"
+  }
+}