sharjeenux 0.3.0

package/features/repl.js

@@ -0,0 +1,303 @@
+export default async function repl() {
+    const [{ create }, readline] = await Promise.all([
+        import("../index.js"),
+        import("node:readline"),
+    ]);
+
+    if (!process.stdin.isTTY) {
+        throw new Error("This REPL requires an interactive terminal.");
+    }
+
+    const vm = create({
+        networking: true,
+        commandTimeoutMs: 0,
+    });
+
+    let running = null;
+    let line = [];
+    let cursor = 0;
+    let historyIndex = 0;
+    let savedLine = [];
+    let outputNeedsNewline = false;
+    let closing = false;
+    const history = [];
+
+    function redraw() {
+        const value = line.join("");
+        process.stdout.write(`\r\x1b[2K$ ${value}`);
+
+        const distanceFromEnd = line.length - cursor;
+        if (distanceFromEnd > 0) {
+            process.stdout.write(`\x1b[${distanceFromEnd}D`);
+        }
+    }
+
+    function prompt() {
+        line = [];
+        cursor = 0;
+        historyIndex = history.length;
+        savedLine = [];
+        process.stdout.write("$ ");
+    }
+
+    function writeOutput(chunk) {
+        process.stdout.write(chunk);
+        outputNeedsNewline = chunk.length > 0 && !/[\r\n]$/.test(chunk);
+    }
+
+    function setLine(value) {
+        line = Array.from(value);
+        cursor = line.length;
+        redraw();
+    }
+
+    function previousWord() {
+        while (cursor > 0 && /\s/.test(line[cursor - 1])) cursor -= 1;
+        while (cursor > 0 && !/\s/.test(line[cursor - 1])) cursor -= 1;
+    }
+
+    function nextWord() {
+        while (cursor < line.length && !/\s/.test(line[cursor])) cursor += 1;
+        while (cursor < line.length && /\s/.test(line[cursor])) cursor += 1;
+    }
+
+    function historyUp() {
+        if (!history.length || historyIndex === 0) return;
+        if (historyIndex === history.length) savedLine = [...line];
+        historyIndex -= 1;
+        setLine(history[historyIndex]);
+    }
+
+    function historyDown() {
+        if (historyIndex >= history.length) return;
+        historyIndex += 1;
+        if (historyIndex === history.length) {
+            line = [...savedLine];
+            cursor = line.length;
+            redraw();
+        } else {
+            setLine(history[historyIndex]);
+        }
+    }
+
+    async function execute(command) {
+        if (!command.trim()) {
+            prompt();
+            return;
+        }
+
+        if (command === "exit" || command === "quit") {
+            await close();
+            return;
+        }
+
+        running = vm.spawn(command, {
+            timeoutMs: 0,
+            interactive: true,
+            onOutput: writeOutput,
+        });
+
+        try {
+            const result = await running.result;
+
+            if (outputNeedsNewline) process.stdout.write("\n");
+            if (result.exitCode !== 0) {
+                process.stdout.write(`[exit ${result.exitCode}]\n`);
+            }
+        } catch (error) {
+            if (outputNeedsNewline) process.stdout.write("\n");
+            if (error?.name !== "AbortError") {
+                process.stderr.write(`${error?.stack ?? error}\n`);
+            }
+        } finally {
+            running = null;
+            outputNeedsNewline = false;
+            if (!closing) prompt();
+        }
+    }
+
+    function submitLine() {
+        process.stdout.write("\n");
+        const command = line.join("");
+
+        if (command.trim() && history.at(-1) !== command) {
+            history.push(command);
+        }
+
+        line = [];
+        cursor = 0;
+        historyIndex = history.length;
+        void execute(command);
+    }
+
+    function handleIdleKeypress(character, key) {
+        const name = key?.name;
+
+        if (name === "return" || name === "enter") {
+            submitLine();
+            return;
+        }
+
+        if (name === "up" || (key?.ctrl && name === "p")) {
+            historyUp();
+            return;
+        }
+
+        if (name === "down" || (key?.ctrl && name === "n")) {
+            historyDown();
+            return;
+        }
+
+        if (name === "left") {
+            if (key?.ctrl || key?.meta) previousWord();
+            else if (cursor > 0) cursor -= 1;
+            redraw();
+            return;
+        }
+
+        if (name === "right") {
+            if (key?.ctrl || key?.meta) nextWord();
+            else if (cursor < line.length) cursor += 1;
+            redraw();
+            return;
+        }
+
+        if (name === "home" || (key?.ctrl && name === "a")) {
+            cursor = 0;
+            redraw();
+            return;
+        }
+
+        if (name === "end" || (key?.ctrl && name === "e")) {
+            cursor = line.length;
+            redraw();
+            return;
+        }
+
+        if (name === "backspace") {
+            if (cursor > 0) {
+                line.splice(cursor - 1, 1);
+                cursor -= 1;
+                redraw();
+            }
+            return;
+        }
+
+        if (name === "delete") {
+            if (cursor < line.length) {
+                line.splice(cursor, 1);
+                redraw();
+            }
+            return;
+        }
+
+        if (key?.ctrl && name === "u") {
+            line.splice(0, cursor);
+            cursor = 0;
+            redraw();
+            return;
+        }
+
+        if (key?.ctrl && name === "k") {
+            line.splice(cursor);
+            redraw();
+            return;
+        }
+
+        if (key?.ctrl && name === "w") {
+            const end = cursor;
+            previousWord();
+            line.splice(cursor, end - cursor);
+            redraw();
+            return;
+        }
+
+        if (key?.meta && name === "b") {
+            previousWord();
+            redraw();
+            return;
+        }
+
+        if (key?.meta && name === "f") {
+            nextWord();
+            redraw();
+            return;
+        }
+
+        if (key?.ctrl && name === "l") {
+            process.stdout.write("\x1b[2J\x1b[H");
+            redraw();
+            return;
+        }
+
+        if (key?.ctrl && name === "c") {
+            line = [];
+            cursor = 0;
+            process.stdout.write("^C\n");
+            prompt();
+            return;
+        }
+
+        if (key?.ctrl && name === "d") {
+            if (!line.length) void close();
+            else if (cursor < line.length) {
+                line.splice(cursor, 1);
+                redraw();
+            }
+            return;
+        }
+
+        if (name === "tab") {
+            process.stdout.write("\x07");
+            return;
+        }
+
+        if (character && !key?.ctrl && !key?.meta && character >= " ") {
+            const inserted = Array.from(character);
+            line.splice(cursor, 0, ...inserted);
+            cursor += inserted.length;
+            redraw();
+        }
+    }
+
+    function handleKeypress(character, key) {
+        if (running) {
+            // Preserve the exact terminal sequence for guest applications. This
+            // gives Node/Python REPLs and other TTY programs their own arrow keys,
+            // Ctrl+C, Ctrl+D, Home/End, Delete and function-key handling.
+            const sequence = key?.sequence ?? character;
+            if (sequence) running.write(sequence);
+            return;
+        }
+
+        handleIdleKeypress(character, key);
+    }
+
+    async function close(exitCode = 0) {
+        if (closing) return;
+        closing = true;
+
+        process.stdin.off("keypress", handleKeypress);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+
+        running?.kill();
+        await vm.shutdown();
+
+        process.stdout.write("\n");
+        process.exitCode = exitCode;
+    }
+
+    process.once("SIGTERM", () => void close(143));
+    process.once("SIGHUP", () => void close(129));
+
+    process.stdout.write("🔌 Booting Sharjeenux...\n");
+    await vm.initialize();
+
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on("keypress", handleKeypress);
+
+    prompt();
+}

package/index.cjs

@@ -0,0 +1,70 @@
+"use strict";
+
+let modulePromise;
+const load = () => modulePromise ||= import("./index.js");
+
+class CommandTimeoutError {
+  static [Symbol.hasInstance](value) {
+    return value?.name === "CommandTimeoutError";
+  }
+}
+
+class Sharjeenux {
+  constructor(options) {
+    this.ready = false;
+    this._instance = load().then(module => module.create(options));
+  }
+
+  async initialize() {
+    const instance = await this._instance;
+    await instance.initialize();
+    this.ready = true;
+    return this;
+  }
+
+  async send(...args) {
+    return (await this._instance).send(...args);
+  }
+
+  async exec(...args) {
+    return (await this._instance).exec(...args);
+  }
+
+  spawn(...args) {
+    const handle = this._instance.then(instance => instance.spawn(...args));
+    return {
+      result: handle.then(value => value.result),
+      exit: handle.then(value => value.exit),
+      write: data => void handle.then(value => value.write(data)),
+      kill: () => void handle.then(value => value.kill()),
+    };
+  }
+
+  write(data) {
+    void this._instance.then(instance => instance.write(data));
+  }
+
+  interrupt() {
+    void this._instance.then(instance => instance.interrupt());
+  }
+
+  on(...args) {
+    void this._instance.then(instance => instance.on(...args));
+    return this;
+  }
+
+  async shutdown() {
+    this.ready = false;
+    return (await this._instance).shutdown();
+  }
+}
+
+exports.CommandTimeoutError = CommandTimeoutError;
+exports.Sharjeenux = Sharjeenux;
+exports.create = options => new Sharjeenux(options);
+exports.initialize = (...args) => load().then(module => module.initialize(...args));
+exports.send = (...args) => load().then(module => module.send(...args));
+exports.exec = (...args) => load().then(module => module.exec(...args));
+exports.spawn = (...args) => load().then(module => module.spawn(...args));
+exports.write = (...args) => load().then(module => module.write(...args));
+exports.shutdown = (...args) => load().then(module => module.shutdown(...args));

package/index.d.ts

@@ -0,0 +1,66 @@
+export interface SharjeenuxOptions {
+  /** Guest RAM in MiB. Must be a power of two. Default: 2048. */
+  memoryMB?: number;
+  /** Maximum initialization time. Default: 180000. */
+  bootTimeoutMs?: number;
+  /** Default command timeout. Default: 1800000. Use 0 to disable. */
+  commandTimeoutMs?: number;
+  /** Configure the guest network through v86's fetch backend. Default: true. */
+  networking?: boolean;
+  /** "fetch" for HTTP-only outbound traffic, or a wisp(s) relay URL for arbitrary outbound TCP/HTTPS. Default: "fetch". */
+  networkRelayUrl?: string;
+  /** Hash-check decoded VM assets during initialization. Default: true. */
+  verifyAssets?: boolean;
+}
+
+export interface CommandOptions {
+  /** Override the instance command timeout. Use 0 to disable. */
+  timeoutMs?: number;
+  /** Receive command output as it arrives. */
+  onOutput?: (chunk: string) => void;
+  /** Abort the command. The guest receives Ctrl+C. */
+  signal?: AbortSignal;
+}
+
+export interface CommandResult {
+  command: string;
+  output: string;
+  exitCode: number;
+  durationMs: number;
+}
+
+export class RunningCommand {
+  readonly result: Promise<CommandResult>;
+  readonly exit: Promise<number>;
+  write(data: string): void;
+  kill(): void;
+}
+
+export class CommandTimeoutError extends Error {
+  readonly command: string;
+  readonly output: string;
+  readonly timeoutMs: number;
+}
+
+export class Sharjeenux {
+  constructor(options?: SharjeenuxOptions);
+  readonly ready: boolean;
+  initialize(): Promise<this>;
+  send(command: string, options?: CommandOptions): Promise<string>;
+  exec(command: string, options?: CommandOptions): Promise<CommandResult>;
+  spawn(command: string, options?: CommandOptions): RunningCommand;
+  write(data: string): void;
+  interrupt(): void;
+  shutdown(): Promise<void>;
+  on(event: "output", listener: (chunk: string) => void): this;
+  on(event: "ready", listener: () => void): this;
+  on(event: "shutdown", listener: () => void): this;
+}
+
+export function create(options?: SharjeenuxOptions): Sharjeenux;
+export function initialize(options?: SharjeenuxOptions): Promise<Sharjeenux>;
+export function send(command: string, options?: CommandOptions): Promise<string>;
+export function exec(command: string, options?: CommandOptions): Promise<CommandResult>;
+export function spawn(command: string, options?: CommandOptions): Promise<RunningCommand>;
+export function write(data: string): Promise<void>;
+export function shutdown(): Promise<void>;