sharjeenux 0.3.0 → 1.0.0

package/README.md

@@ -4,36 +4,57 @@ Sharjeenux is a headless, in-memory Buildroot Linux VM controlled from Node.js.
 It boots an i686 Linux image through v86 and exposes one persistent serial shell
 as an async JavaScript API.
 
-The guest includes:
+## Modular Architecture
 
-- Node.js 20.20, npm, npx, TypeScript (`tsc` and `tsserver`)
-- Python 3 and pip
-- OpenJDK 21 (`java`, `javac`) and Apache Maven
+Sharjeenux uses a plugin-based architecture. The core package ships a minimal
+Linux base system, and language runtimes are installed as separate packages:
+
+| Package | What it adds | Install |
+|---|---|---|
+| `sharjeenux` | Base Linux (BusyBox, networking, archive tools) | `npm install sharjeenux` |
+| `@sharjeenux/node` | Node.js 20, npm, npx, TypeScript | `npm install @sharjeenux/node` |
+| `@sharjeenux/python` | Python 3, pip | `npm install @sharjeenux/python` |
+| `@sharjeenux/java` | OpenJDK 21, javac, Apache Maven | `npm install @sharjeenux/java` |
+
+The base system always includes:
+
+- BusyBox coreutils, shell, and init
 - Git, curl, GNU wget, OpenSSL, and CA certificates
 - Common archive tools: tar, gzip, bzip2, xz, zip, and unzip
+- Outbound networking via v86's fetch transport or a Wisp relay
 
 It has no desktop, display server, SSH server, or host port-forwarding layer.
 
-## Install
+## Quick Start
+
+### Minimal (base Linux only)
 
 ```sh
 npm install sharjeenux
 ```
 
-To test the generated package before registry publication:
+```js
+import { initialize, send, shutdown } from "sharjeenux";
 
-```sh
-npm install ./sharjeenux-0.3.0.tgz
+await initialize();
+console.log(await send("uname -a"));
+console.log(await send("ls -la"));
+console.log(await send("curl --version"));
+await shutdown();
 ```
 
-## Use
+### Full Stack (Node.js + Python + Java)
+
+```sh
+npm install sharjeenux @sharjeenux/node @sharjeenux/python @sharjeenux/java
+```
 
 ```js
 import { initialize, send, exec, shutdown } from "sharjeenux";
 
 await initialize();
 
-console.log(await send("ls -la"));
+// All runtimes are available automatically
 console.log(await send("node -e 'console.log(6 * 7)'"));
 console.log(await send("python3 -c 'print(6 * 7)'"));
 console.log(await send("java --version"));
@@ -45,7 +66,23 @@ console.log(result.output, result.exitCode, result.durationMs);
 await shutdown();
 ```
 
-CommonJS is supported:
+### Pick Only What You Need
+
+```sh
+# Just Node.js
+npm install sharjeenux @sharjeenux/node
+
+# Just Python
+npm install sharjeenux @sharjeenux/python
+
+# Node.js + Java (no Python)
+npm install sharjeenux @sharjeenux/node @sharjeenux/java
+```
+
+Plugins are detected automatically from your `package.json` dependencies. No
+extra configuration is needed — just install and go.
+
+CommonJS is also supported:
 
 ```js
 const { initialize, send, shutdown } = require("sharjeenux");
@@ -55,18 +92,93 @@ console.log(await send("uname -a"));
 await shutdown();
 ```
 
-Commands execute sequentially in one persistent shell rooted at
-`/mnt/workspace`. Directory changes, environment variables, and installed
-language packages remain available until `shutdown()`.
+## How It Works
+
+Under the hood, Sharjeenux leverages Linux's **composite initramfs** feature.
+Each plugin package ships a compressed CPIO archive containing its runtime
+binaries. At boot, the base initrd and all plugin initrds are concatenated
+into a single buffer. The Linux kernel extracts them sequentially, overlaying
+each archive onto the root filesystem. The result is a unified system with all
+your chosen runtimes available in `$PATH`.
+
+```
+sharjeenux (base)          → /bin, /sbin, /usr (BusyBox, git, curl…)
+@sharjeenux/node (plugin)  → /usr/local/bin/node, /usr/local/bin/npm…
+@sharjeenux/python (plugin)→ /usr/bin/python3, /usr/bin/pip3…
+@sharjeenux/java (plugin)  → /usr/lib/jvm/…, /opt/maven/…
+```
+
+## API
 
-## Package managers
+### `initialize(options?)`
+
+Boots the VM and returns the `Sharjeenux` instance. Subsequent calls return the
+same instance.
+
+```js
+const vm = await initialize({
+  memoryMB: 2048,           // Guest RAM (power of 2, min 128)
+  bootTimeoutMs: 180_000,   // Max time to wait for boot
+  commandTimeoutMs: 1_800_000, // Default per-command timeout
+  networking: true,         // Enable outbound networking
+  networkRelayUrl: "fetch", // Or "wisps://your-relay.example/"
+  plugins: [],              // Explicit plugin package names (auto-detected by default)
+});
+```
+
+### `send(command, options?)`
+
+Runs a shell command and returns its stdout as a string.
+
+```js
+const output = await send("ls -la");
+```
+
+### `exec(command, options?)`
+
+Runs a shell command and returns a result object:
+
+```js
+const { output, exitCode, durationMs } = await exec("npm install lodash");
+```
+
+### `spawn(command, options?)`
+
+Starts a long-running command without waiting for it to exit:
+
+```js
+const dev = vm.spawn("npm run dev -- --host 0.0.0.0", {
+  timeoutMs: 0,
+  onOutput: chunk => process.stdout.write(chunk),
+});
+
+// Later...
+dev.kill();
+await dev.exit;
+```
+
+### `shutdown()`
+
+Destroys the VM and releases all resources.
+
+### Streaming Output
+
+Both `exec()` and `send()` accept an `onOutput` callback for real-time output:
+
+```js
+await send("npm install express", {
+  onOutput: chunk => process.stdout.write(chunk),
+});
+```
+
+## Package Managers
 
 Use npm/npx for JavaScript and TypeScript, pip for Python, and Maven for Java:
 
 ```js
-await send("npm install lodash");
-await send("pip3 install requests");
-await send("mvn --version");
+await send("npm install lodash");    // requires @sharjeenux/node
+await send("pip3 install requests"); // requires @sharjeenux/python
+await send("mvn --version");        // requires @sharjeenux/java
 ```
 
 Buildroot images are intentionally assembled at build time and do not have a
@@ -79,7 +191,7 @@ compile native C/C++ extensions inside the guest are not guaranteed because
 this image does not ship an on-target C/C++ compiler toolchain. Java source is
 supported through `javac`.
 
-## Long-running commands
+## Long-Running Commands
 
 `send()` resolves only when a command exits. Use `spawn()` for a development
 server or another long-lived process:
@@ -109,7 +221,7 @@ Sharjeenux deliberately does not map guest listening ports to the host. A Vite
 server can run inside Linux, but its URL is not exposed to the host, browser,
 or public network.
 
-## Outbound networking
+## Outbound Networking
 
 The default is v86's fetch transport:
 
@@ -136,7 +248,20 @@ The fetch transport is much slower and less reliable for large dependency
 graphs than normal TCP. Sharjeenux configures npm retries and conservative
 parallelism, but a trusted Wisp relay is recommended for large installs.
 
-## Sandbox requirements
+## Creating a Plugin Package
+
+Want to add your own runtime to Sharjeenux? Create an npm package that ships a
+CPIO archive:
+
+1. Build a `plugin.cpio.xz` (or `.cpio.gz` / `.cpio`) containing the files you
+   want overlaid onto the root filesystem
+2. Set `"main": "plugin.cpio.xz"` in your plugin's `package.json`
+3. Include `plugin.cpio.xz` in the `"files"` array
+4. Name your package `@sharjeenux/<name>` or `sharjeenux-<name>`
+
+The archive will be automatically detected and loaded at boot.
+
+## Sandbox Requirements
 
 Sharjeenux works in Node.js sandboxes that permit:
 
@@ -150,7 +275,7 @@ It is not a browser package: its host wrapper imports Node.js APIs. Serverless
 and edge runtimes with short CPU limits, no writable temporary storage, or no
 WebAssembly support are not compatible.
 
-## Performance and Base64 assets
+## Performance and Base64 Assets
 
 Every embedded binary is stored as Base64 text files of at most 1 KiB each.
 The first initialization must open and decode those files. Decoded images are
@@ -162,7 +287,7 @@ slower than native Node.js or StackBlitz WebContainers, whose architecture is
 designed specifically around browser-native execution. Streaming output with
 `onOutput` makes long installs observable but does not remove emulation cost.
 
-## Licensing and corresponding source
+## Licensing and Corresponding Source
 
 The JavaScript wrapper is MIT-licensed. The Linux image contains components
 under their own licenses, including GPLv2 BusyBox and the Linux kernel. See

package/compliance/buildroot.config

@@ -446,10 +446,10 @@ BR2_STRIP_EXCLUDE_FILES=""
 BR2_STRIP_EXCLUDE_DIRS=""
 # BR2_OPTIMIZE_0 is not set
 # BR2_OPTIMIZE_1 is not set
-BR2_OPTIMIZE_2=y
+# BR2_OPTIMIZE_2 is not set
 # BR2_OPTIMIZE_3 is not set
 # BR2_OPTIMIZE_G is not set
-# BR2_OPTIMIZE_S is not set
+BR2_OPTIMIZE_S=y
 # BR2_OPTIMIZE_FAST is not set
 # BR2_ENABLE_LTO is not set
 # BR2_GOOGLE_BREAKPAD_ENABLE is not set
@@ -3811,12 +3811,12 @@ BR2_TARGET_ROOTFS_CPIO=y
 BR2_TARGET_ROOTFS_CPIO_FULL=y
 # BR2_TARGET_ROOTFS_CPIO_DRACUT is not set
 # BR2_TARGET_ROOTFS_CPIO_NONE is not set
-BR2_TARGET_ROOTFS_CPIO_GZIP=y
+# BR2_TARGET_ROOTFS_CPIO_GZIP is not set
 # BR2_TARGET_ROOTFS_CPIO_BZIP2 is not set
 # BR2_TARGET_ROOTFS_CPIO_LZ4 is not set
 # BR2_TARGET_ROOTFS_CPIO_LZMA is not set
 # BR2_TARGET_ROOTFS_CPIO_LZO is not set
-# BR2_TARGET_ROOTFS_CPIO_XZ is not set
+BR2_TARGET_ROOTFS_CPIO_XZ=y
 # BR2_TARGET_ROOTFS_CPIO_ZSTD is not set
 # BR2_TARGET_ROOTFS_CPIO_UIMAGE is not set
 # BR2_TARGET_ROOTFS_CRAMFS is not set

package/compliance/linux.config

@@ -186,7 +186,7 @@ CONFIG_NET_NS=y
 # CONFIG_SCHED_AUTOGROUP is not set
 # CONFIG_RELAY is not set
 CONFIG_BLK_DEV_INITRD=y
-CONFIG_INITRAMFS_SOURCE="${BR_BINARIES_DIR}/rootfs.cpio"
+CONFIG_INITRAMFS_SOURCE=""
 CONFIG_INITRAMFS_ROOT_UID=0
 CONFIG_INITRAMFS_ROOT_GID=0
 CONFIG_RD_GZIP=y
@@ -196,18 +196,18 @@ CONFIG_RD_XZ=y
 CONFIG_RD_LZO=y
 CONFIG_RD_LZ4=y
 CONFIG_RD_ZSTD=y
-CONFIG_INITRAMFS_COMPRESSION_GZIP=y
+# CONFIG_INITRAMFS_COMPRESSION_GZIP is not set
 # CONFIG_INITRAMFS_COMPRESSION_BZIP2 is not set
 # CONFIG_INITRAMFS_COMPRESSION_LZMA is not set
-# CONFIG_INITRAMFS_COMPRESSION_XZ is not set
+CONFIG_INITRAMFS_COMPRESSION_XZ=y
 # CONFIG_INITRAMFS_COMPRESSION_LZO is not set
 # CONFIG_INITRAMFS_COMPRESSION_LZ4 is not set
 # CONFIG_INITRAMFS_COMPRESSION_ZSTD is not set
 # CONFIG_INITRAMFS_COMPRESSION_NONE is not set
 # CONFIG_BOOT_CONFIG is not set
 CONFIG_INITRAMFS_PRESERVE_MTIME=y
-CONFIG_CC_OPTIMIZE_FOR_PERFORMANCE=y
-# CONFIG_CC_OPTIMIZE_FOR_SIZE is not set
+# CONFIG_CC_OPTIMIZE_FOR_PERFORMANCE is not set
+CONFIG_CC_OPTIMIZE_FOR_SIZE=y
 CONFIG_LD_ORPHAN_WARN=y
 CONFIG_LD_ORPHAN_WARN_LEVEL="warn"
 CONFIG_SYSCTL=y

package/index.d.ts

@@ -11,6 +11,8 @@ export interface SharjeenuxOptions {
   networkRelayUrl?: string;
   /** Hash-check decoded VM assets during initialization. Default: true. */
   verifyAssets?: boolean;
+  /** Explicit list of plugin package names to load (e.g. ["@sharjeenux/node"]). By default, plugins are auto-detected from package.json dependencies. */
+  plugins?: string[];
 }
 
 export interface CommandOptions {

package/index.js

@@ -4,6 +4,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import { V86 } from "v86";
 
 const ASSETS_URL = new URL("./assets/", import.meta.url);
@@ -16,6 +17,7 @@ const DEFAULTS = Object.freeze({
   networking: true,
   networkRelayUrl: "fetch",
   verifyAssets: true,
+  plugins: [],
 });
 
 let defaultInstance;
@@ -57,6 +59,56 @@ function toArrayBuffer(buffer) {
   return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
 }
 
+
+function concatArrayBuffers(buffers) {
+  const totalLength = buffers.reduce((acc, b) => acc + b.byteLength, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const b of buffers) {
+    result.set(new Uint8Array(b), offset);
+    offset += b.byteLength;
+  }
+  return result.buffer;
+}
+
+async function loadPlugins(explicitPlugins = []) {
+  const plugins = [];
+  const require = createRequire(process.cwd() + "/");
+  const depsToTry = new Set(explicitPlugins);
+  
+  try {
+    const pkgPath = path.resolve(process.cwd(), "package.json");
+    const pkgText = await readFile(pkgPath, "utf8");
+    const pkg = JSON.parse(pkgText);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    for (const dep of Object.keys(deps)) {
+      if ((dep.startsWith("sharjeenux-") || dep.startsWith("@sharjeenux/")) && dep !== "sharjeenux") {
+        depsToTry.add(dep);
+      }
+    }
+  } catch (e) {}
+
+  for (const dep of depsToTry) {
+    try {
+      let depPath;
+      try {
+        depPath = require.resolve(`${dep}/plugin.cpio.xz`);
+      } catch (e) {
+        try {
+          depPath = require.resolve(`${dep}/plugin.cpio.gz`);
+        } catch (e2) {
+          depPath = require.resolve(`${dep}/plugin.cpio`);
+        }
+      }
+      const buffer = await readFile(depPath);
+      plugins.push(toArrayBuffer(buffer));
+    } catch (e) {
+      console.warn(`[Sharjeenux] Failed to load plugin ${dep}: ${e.message}`);
+    }
+  }
+  return plugins;
+}
+
 async function getManifest() {
   manifestPromise ||= readFile(new URL("manifest.json", ASSETS_URL), "utf8").then(JSON.parse);
   return manifestPromise;
@@ -153,13 +205,23 @@ export class Sharjeenux extends EventEmitter {
       globalThis.WebSocket = WebSocket;
     }
     const manifest = await getManifest();
-    const [bios, vgabios, kernel, initrd] = await Promise.all([
+    const [bios, vgabios, kernel, baseInitrd, plugins] = 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,
+      manifest.images.initrd ? loadImage("initrd", this.options.verifyAssets) : Promise.resolve(null),
+      loadPlugins(this.options.plugins)
     ]);
 
+    let finalInitrd;
+    const initrdBuffers = [];
+    if (baseInitrd) initrdBuffers.push(baseInitrd);
+    if (plugins.length > 0) initrdBuffers.push(...plugins);
+    
+    if (initrdBuffers.length > 0) {
+      finalInitrd = concatArrayBuffers(initrdBuffers);
+    }
+
     const wasmPath = fileURLToPath(import.meta.resolve("v86/build/v86.wasm"));
     const boot = deferred();
     this._boot = boot;
@@ -183,7 +245,7 @@ export class Sharjeenux extends EventEmitter {
       disable_mouse: true,
       disable_speaker: true,
     };
-    if (initrd) emulatorOptions.initrd = { buffer: initrd };
+    if (finalInitrd) emulatorOptions.initrd = { buffer: finalInitrd };
     this._emulator = new V86(emulatorOptions);
     this._emulator.add_listener("serial0-output-byte", this._serialListener);
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "1.0.0",
+  "description": "A modular, headless Buildroot Linux VM controlled from JavaScript. Install language runtimes as plugins: @sharjeenux/node, @sharjeenux/python, @sharjeenux/java.",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",