boxsh.js 0.1.0

package/README.md

@@ -0,0 +1,238 @@
+# boxsh.js
+
+Node.js SDK for [boxsh](../../README.md) — a sandboxed POSIX shell with Linux namespace isolation and copy-on-write overlay filesystem.
+
+boxsh.js lets you drive a long-lived boxsh instance from Node.js: execute shell commands, read/write files, and perform search-and-replace edits — all inside an isolated sandbox.
+
+**Requirements:** Node.js ≥ 18, Linux, `boxsh` binary on `$PATH` (or set `BOXSH` env var).
+
+## Install
+
+```sh
+npm install ./sdk/js
+```
+
+---
+
+## Quick start
+
+Simplest form — no sandbox, just run a command:
+
+```js
+import { BoxshClient } from 'boxsh.js';
+
+const client = new BoxshClient();
+
+const { exitCode, stdout } = await client.exec('echo hello');
+console.log(stdout);  // "hello\n"
+
+await client.close();
+```
+
+---
+
+## Running shell commands
+
+`exec(cmd, cwd?, timeout?)` runs a shell command in a boxsh worker, returning the exit code, stdout, and stderr.
+
+```js
+// Specify a working directory
+const result = await client.exec('ls -la', '/workspace');
+console.log(result.exitCode);  // 0
+console.log(result.stdout);    // file listing
+
+// Set a timeout (seconds) — the worker is killed via SIGALRM when it expires
+const result2 = await client.exec('sleep 100', '/workspace', 5);
+```
+
+Multiple `exec` calls can run concurrently. BoxshClient dispatches them across workers and resolves responses in completion order:
+
+```js
+const client = new BoxshClient({ workers: 4 });
+
+const [a, b, c] = await Promise.all([
+    client.exec('make build',  '/workspace'),
+    client.exec('make lint',   '/workspace'),
+    client.exec('make test',   '/workspace'),
+]);
+```
+
+---
+
+## File operations
+
+boxsh has three built-in file tools — `read`, `write`, and `edit`. They run on background threads and never block the RPC event loop.
+
+```js
+// Read a file — optionally specify a start line and line limit
+const content = await client.read('/workspace/src/main.cpp');
+const first50 = await client.read('/workspace/src/main.cpp', 1, 50);
+
+// Write a file — full replacement
+await client.write('/workspace/output.txt', 'hello\n');
+
+// Edit a file — search-and-replace; each oldText must appear exactly once
+const { diff, firstChangedLine } = await client.edit('/workspace/output.txt', [
+    { oldText: 'hello', newText: 'world' },
+]);
+console.log(diff);  // unified diff format
+```
+
+---
+
+## Sandbox isolation
+
+With `sandbox` enabled, commands run inside isolated Linux namespaces (user, mount), separated from the host. You can further isolate the network and PID tree:
+
+```js
+const client = new BoxshClient({
+    sandbox:  true,
+    newNetNs: true,   // Isolated network namespace (no external access)
+    newPidNs: true,   // Isolated PID namespace
+});
+```
+
+---
+
+## Overlay filesystem
+
+Overlay is the primary usage pattern for boxsh: mount a read-only base directory as a copy-on-write workspace. Commands can read and write freely, but all modifications land in the upper directory while the base remains untouched.
+
+```
+Overlay parameters:
+  lower  Read-only base directory (your project/repository)
+  upper  Writable upper directory (all modifications go here)
+  work   Working directory required by overlayfs (must be on the same filesystem as upper)
+  dst    Mount point (the path visible inside the sandbox)
+```
+
+```js
+import { BoxshClient } from 'boxsh.js';
+import fs from 'node:fs';
+
+// Prepare overlay directories
+const upper = '/tmp/sandbox/upper';
+const work  = '/tmp/sandbox/work';
+const mnt   = '/tmp/sandbox/mnt';
+fs.mkdirSync(upper, { recursive: true });
+fs.mkdirSync(work,  { recursive: true });
+fs.mkdirSync(mnt,   { recursive: true });
+
+const client = new BoxshClient({
+    sandbox: true,
+    overlay: {
+        lower: '/home/user/myproject',   // read-only base
+        upper,                            // modifications land here
+        work,
+        dst: mnt,                         // mount point inside the sandbox
+    },
+});
+
+// Inside the sandbox, /tmp/sandbox/mnt is a COW copy of myproject
+await client.exec('npm install', mnt);
+
+// Read/write files via built-in tools (RPC, no shell round-trip needed)
+const pkg = await client.read(`${mnt}/package.json`);
+await client.write(`${mnt}/result.txt`, 'done\n');
+
+await client.close();
+
+// At this point upper/ contains all modifications; base is completely untouched.
+// You can commit, archive, or simply delete upper/ to discard changes.
+```
+
+The upper directory persists across sessions. To resume a previous session, create a new BoxshClient pointing at the same `upper`/`work`/`mnt` directories.
+
+---
+
+## Inspecting changes
+
+`getChanges` scans the overlay's upper directory against the base and returns all added, modified, and deleted files. `formatChanges` formats the result as human-readable text.
+
+Both functions run on the host side (inside the Node.js process) and do not require a running boxsh instance.
+
+```js
+import { getChanges, formatChanges } from 'boxsh.js';
+
+const changes = getChanges({
+    upper: '/tmp/sandbox/upper',
+    base:  '/home/user/myproject',
+});
+// [{ path: 'package-lock.json', type: 'modified' },
+//  { path: 'result.txt',        type: 'added' }]
+
+console.log(formatChanges(changes));
+// M	package-lock.json
+// A	result.txt
+```
+
+Deletions are tracked via whiteout files (`.wh.<name>`), which `getChanges` detects automatically.
+
+---
+
+## `shellQuote`
+
+POSIX single-quote escaping for safely interpolating variables into shell commands:
+
+```js
+import { shellQuote } from 'boxsh.js';
+
+const userInput = "hello'world";
+await client.exec(`echo ${shellQuote(userInput)}`);
+// Executed safely — no injection
+```
+
+---
+
+## API reference
+
+### `new BoxshClient(options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `boxshPath` | `string` | `$BOXSH` → `'boxsh'` | Path to the boxsh binary |
+| `workers` | `number` | `1` | Number of pre-forked workers |
+| `sandbox` | `boolean` | `false` | Enable namespace sandbox |
+| `newNetNs` | `boolean` | `false` | Isolate network |
+| `newPidNs` | `boolean` | `false` | Isolate PID tree |
+| `overlay` | `{ lower, upper, work, dst }` | — | Overlay mount configuration |
+
+### `client.exec(cmd, cwd?, timeout?) → Promise<{ exitCode, stdout, stderr }>`
+
+Execute a shell command. `timeout` is in seconds.
+
+### `client.read(path, offset?, limit?) → Promise<string>`
+
+Read file contents. `offset` is the 1-based start line; `limit` is the maximum number of lines.
+
+### `client.write(path, content) → Promise<void>`
+
+Write a file (full replacement).
+
+### `client.edit(path, edits) → Promise<{ diff, firstChangedLine }>`
+
+Apply search-and-replace edits. `edits` is an array of `{ oldText, newText }`. Each `oldText` must appear exactly once in the file. All edits match against the original file content (not the result of a previous edit). Returns a unified diff and the first changed line number.
+
+### `client.close() → Promise<void>`
+
+Close stdin and wait for the boxsh process to exit.
+
+### `client.terminate() → void`
+
+Send SIGTERM immediately.
+
+### `getChanges({ upper, base }) → Array<{ path, type }>`
+
+Scan the upper directory and return a list of changes relative to base. `type` is `'added'`, `'modified'`, or `'deleted'`.
+
+### `formatChanges(changes) → string`
+
+Format a change list as `A/M/D\tpath` text.
+
+---
+
+## Testing
+
+```sh
+node --test test/all.test.mjs
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "boxsh.js",
+  "version": "0.1.0",
+  "description": "Node.js SDK for boxsh — sandboxed shell execution with overlay copy-on-write and JSON-line RPC",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/all.test.mjs"
+  },
+  "keywords": [
+    "boxsh",
+    "sandbox",
+    "shell",
+    "overlayfs",
+    "namespace",
+    "rpc",
+    "linux",
+    "isolation"
+  ],
+  "license": "MIT",
+  "author": "xicilion",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/xicilion/boxsh.git",
+    "directory": "sdk/js"
+  },
+  "bugs": {
+    "url": "https://github.com/xicilion/boxsh/issues"
+  },
+  "homepage": "https://github.com/xicilion/boxsh#readme",
+  "os": [
+    "linux"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/"
+  ]
+}

package/src/changes.mjs

@@ -0,0 +1,99 @@
+/**
+ * Changes detection: scan the upper directory to extract file modifications
+ * relative to the base layer.
+ *
+ * Detects:
+ *   - Added   files (in upper, not in base)
+ *   - Modified files (in both layers)
+ *   - Deleted  files (whiteout markers in upper)
+ *
+ * Supports both host-side whiteout format (.wh.<name> files) and
+ * kernel overlay whiteout format (char device 0/0).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WH_PREFIX = '.wh.';
+
+/**
+ * Scan the upper directory and return a list of all changes relative to base.
+ *
+ * @param {{ upper: string, base: string }} options
+ * @returns {Array<{ path: string, type: 'added'|'modified'|'deleted' }>}
+ */
+export function getChanges(options) {
+    const changes = [];
+    _scanChanges(options.upper, options.base, '.', changes);
+    return changes.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * @param {string} upperRoot
+ * @param {string} baseRoot
+ * @param {string} rel
+ * @param {Array<object>} changes
+ */
+function _scanChanges(upperRoot, baseRoot, rel, changes) {
+    const upperDir = path.join(upperRoot, rel);
+    if (!fs.existsSync(upperDir) || !fs.statSync(upperDir).isDirectory()) return;
+
+    for (const name of fs.readdirSync(upperDir)) {
+        const childRel  = rel === '.' ? name : path.join(rel, name);
+        const upperPath = path.join(upperRoot, childRel);
+
+        // Host-side whiteout (.wh.<name>)
+        if (name.startsWith(WH_PREFIX)) {
+            const targetName = name.slice(WH_PREFIX.length);
+            const targetRel  = rel === '.' ? targetName : path.join(rel, targetName);
+            changes.push({ path: targetRel, type: 'deleted' });
+            continue;
+        }
+
+        // Kernel overlay whiteout (char device 0/0)
+        if (_isKernelWhiteout(upperPath)) {
+            changes.push({ path: childRel, type: 'deleted' });
+            continue;
+        }
+
+        const st = fs.statSync(upperPath);
+
+        if (st.isDirectory()) {
+            const basePath = path.join(baseRoot, childRel);
+            if (!fs.existsSync(basePath)) {
+                changes.push({ path: childRel, type: 'added' });
+            }
+            _scanChanges(upperRoot, baseRoot, childRel, changes);
+        } else if (st.isFile()) {
+            const basePath = path.join(baseRoot, childRel);
+            changes.push({ path: childRel, type: fs.existsSync(basePath) ? 'modified' : 'added' });
+        }
+    }
+}
+
+/**
+ * Detect kernel overlay whiteout: character device with rdev 0.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function _isKernelWhiteout(filePath) {
+    try {
+        const st = fs.lstatSync(filePath);
+        return st.isCharacterDevice?.() && st.rdev === 0;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Format a list of changes as a human-readable summary.
+ *
+ * @param {Array<{ path: string, type: 'added'|'modified'|'deleted' }>} changes
+ * @returns {string}
+ */
+export function formatChanges(changes) {
+    if (changes.length === 0) return 'No changes detected.\n';
+    return changes
+        .map(c => `${c.type === 'added' ? 'A' : c.type === 'modified' ? 'M' : 'D'}\t${c.path}`)
+        .join('\n') + '\n';
+}

package/src/client.mjs

@@ -0,0 +1,204 @@
+/**
+ * BoxshClient — manages a long-lived boxsh RPC process.
+ *
+ * Spawns boxsh with --rpc and optional --sandbox/--overlay flags.
+ * All commands and tool calls are sent as JSON lines to stdin and
+ * responses are read back as JSON lines from stdout.
+ *
+ * Protocol (request):
+ *   shell:  { id, cmd, timeout? }
+ *   tool:   { id, tool: "read|write", path, ...opts }
+ *
+ * Protocol (response):
+ *   shell:  { id, exit_code, stdout, stderr, duration_ms }
+ *   tool:   { id, content: [{ text }] }  or  { id, error }
+ */
+
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+/**
+ * POSIX single-quote escaping.
+ * @param {string} s
+ * @returns {string}
+ */
+export function shellQuote(s) {
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+export class BoxshClient {
+    /** @type {import('node:child_process').ChildProcess} */
+    #proc;
+    /** @type {Map<string, { resolve: Function, reject: Function }>} */
+    #pending = new Map();
+    #idCounter = 0;
+    #closed = false;
+
+    /**
+     * @param {object} [options]
+     * @param {string}  [options.boxshPath]   Path to boxsh binary (default: BOXSH env var → 'boxsh')
+     * @param {number}  [options.workers]     Worker count (default: 1)
+     * @param {boolean} [options.sandbox]     Enable --sandbox flag
+     * @param {boolean} [options.newNetNs]    Enable --new-net-ns flag
+     * @param {boolean} [options.newPidNs]    Enable --new-pid-ns flag
+     * @param {{ lower: string, upper: string, work: string, dst: string }} [options.overlay]
+     */
+    constructor(options = {}) {
+        const boxsh = options.boxshPath ?? process.env['BOXSH'] ?? 'boxsh';
+        const args = ['--rpc', '--workers', String(options.workers ?? 1)];
+
+        if (options.sandbox) args.push('--sandbox');
+        if (options.newNetNs) args.push('--new-net-ns');
+        if (options.newPidNs) args.push('--new-pid-ns');
+        if (options.overlay) {
+            const { lower, upper, work, dst } = options.overlay;
+            args.push('--overlay', `${lower}:${upper}:${work}:${dst}`);
+        }
+
+        this.#proc = spawn(boxsh, args, { stdio: ['pipe', 'pipe', 'inherit'] });
+
+        createInterface({ input: this.#proc.stdout }).on('line', (line) => {
+            const trimmed = line.trim();
+            if (!trimmed) return;
+            /** @type {Record<string, unknown>} */
+            let resp;
+            try {
+                resp = JSON.parse(trimmed);
+            } catch {
+                return;
+            }
+            const id = String(resp.id ?? '');
+            const entry = this.#pending.get(id);
+            if (!entry) return;
+            this.#pending.delete(id);
+            entry.resolve(resp);
+        });
+
+        this.#proc.on('error', (err) => this.#failAll(err));
+        this.#proc.on('exit', () => {
+            if (!this.#closed) {
+                this.#failAll(new Error('boxsh process exited unexpectedly'));
+            }
+        });
+    }
+
+    #failAll(err) {
+        for (const entry of this.#pending.values()) entry.reject(err);
+        this.#pending.clear();
+    }
+
+    #nextId() {
+        return String(++this.#idCounter);
+    }
+
+    /**
+     * Send a raw request and return the parsed response.
+     * @param {Record<string, unknown>} req
+     * @returns {Promise<Record<string, unknown>>}
+     */
+    #send(req) {
+        return new Promise((resolve, reject) => {
+            if (this.#closed) {
+                reject(new Error('BoxshClient is closed'));
+                return;
+            }
+            const id = this.#nextId();
+            this.#pending.set(id, { resolve, reject });
+            this.#proc.stdin.write(JSON.stringify({ ...req, id }) + '\n');
+        });
+    }
+
+    /**
+     * Execute a shell command.
+     *
+     * @param {string} cmd          Shell command (passed to dash -c)
+     * @param {string} [cwd]        Working directory inside the sandbox
+     * @param {number} [timeout]    Timeout in seconds (0 or undefined = none)
+     * @returns {Promise<{ exitCode: number|null, stdout: string, stderr: string }>}
+     */
+    async exec(cmd, cwd, timeout) {
+        const command = cwd ? `(cd ${shellQuote(cwd)} && ${cmd})` : cmd;
+        const req = { cmd: command };
+        if (timeout !== undefined && timeout > 0) req.timeout = timeout;
+
+        const resp = await this.#send(req);
+        return {
+            exitCode: typeof resp.exit_code === 'number' ? resp.exit_code : null,
+            stdout:   typeof resp.stdout    === 'string' ? resp.stdout    : '',
+            stderr:   typeof resp.stderr    === 'string' ? resp.stderr    : '',
+        };
+    }
+
+    /**
+     * Read a file using boxsh's built-in read tool.
+     *
+     * @param {string} filePath    Absolute path to the file
+     * @param {number} [offset]   1-based line number to start reading from
+     * @param {number} [limit]    Maximum number of lines to return
+     * @returns {Promise<string>}
+     */
+    async read(filePath, offset, limit) {
+        const req = { tool: 'read', path: filePath };
+        if (offset !== undefined) req.offset = offset;
+        if (limit  !== undefined) req.limit  = limit;
+
+        const resp = await this.#send(req);
+        if (resp.error) throw new Error(String(resp.error));
+        return resp.content[0].text;
+    }
+
+    /**
+     * Write a file using boxsh's built-in write tool.
+     *
+     * @param {string} filePath   Absolute path to the file
+     * @param {string} content    Full file content to write
+     */
+    async write(filePath, content) {
+        const resp = await this.#send({ tool: 'write', path: filePath, content });
+        if (resp.error) throw new Error(String(resp.error));
+    }
+
+    /**
+     * Edit a file using boxsh's built-in edit tool.
+     *
+     * Each edit is matched against the original file content (not the result
+     * of previous edits), and oldText must be unique in the file.
+     *
+     * @param {string} filePath   Absolute path to the file
+     * @param {Array<{ oldText: string, newText: string }>} edits
+     * @returns {Promise<{ diff: string, firstChangedLine: number }>}
+     */
+    async edit(filePath, edits) {
+        const resp = await this.#send({ tool: 'edit', path: filePath, edits });
+        if (resp.error) throw new Error(String(resp.error));
+        return {
+            diff:             resp.details?.diff ?? '',
+            firstChangedLine: resp.details?.firstChangedLine ?? 0,
+        };
+    }
+
+    /**
+     * Close stdin and wait for the boxsh process to exit.
+     * @returns {Promise<void>}
+     */
+    close() {
+        this.#closed = true;
+        this.#proc.stdin.end();
+        return new Promise((resolve) => {
+            if (this.#proc.exitCode !== null) {
+                resolve();
+            } else {
+                this.#proc.once('exit', () => resolve());
+            }
+        });
+    }
+
+    /**
+     * Kill the boxsh process immediately.
+     */
+    terminate() {
+        this.#closed = true;
+        this.#failAll(new Error('BoxshClient terminated'));
+        this.#proc.kill('SIGTERM');
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,69 @@
+export interface BoxshOverlayOptions {
+    lower: string;
+    upper: string;
+    work: string;
+    dst: string;
+}
+
+export interface BoxshClientOptions {
+    boxshPath?: string;
+    workers?: number;
+    sandbox?: boolean;
+    newNetNs?: boolean;
+    newPidNs?: boolean;
+    overlay?: BoxshOverlayOptions;
+}
+
+export interface ExecResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+
+export interface EditOperation {
+    oldText: string;
+    newText: string;
+}
+
+export interface EditResult {
+    diff: string;
+    firstChangedLine: number;
+}
+
+export interface Change {
+    path: string;
+    type: 'added' | 'modified' | 'deleted';
+}
+
+export class BoxshClient {
+    constructor(options?: BoxshClientOptions);
+    exec(cmd: string, cwd?: string, timeout?: number): Promise<ExecResult>;
+    read(filePath: string, offset?: number, limit?: number): Promise<string>;
+    write(filePath: string, content: string): Promise<void>;
+    edit(filePath: string, edits: EditOperation[]): Promise<EditResult>;
+    close(): Promise<void>;
+    terminate(): void;
+}
+
+export function shellQuote(s: string): string;
+
+export function getChanges(options: { upper: string; base: string }): Change[];
+
+export function formatChanges(changes: Change[]): string;
+
+export interface BashExecOptions {
+    onData?: (data: Buffer) => void;
+    signal?: AbortSignal;
+    timeout?: number;
+}
+
+export interface BashOperations {
+    exec(command: string, cwd: string, options: BashExecOptions): Promise<{ exitCode: number | null }>;
+}
+
+export interface CreateBashOperationsOptions {
+    sandbox?: boolean;
+    fallback?: BashOperations;
+}
+
+export function createBashOperations(options?: CreateBashOperationsOptions): BashOperations;

package/src/index.mjs

@@ -0,0 +1,47 @@
+/**
+ * @boxsh/sdk — public API
+ */
+
+// Core RPC client
+export { BoxshClient, shellQuote } from './client.mjs';
+
+// Change detection (diff upper vs base on the host filesystem)
+export { getChanges, formatChanges } from './changes.mjs';
+
+/**
+ * Create a BashOperations adapter backed by BoxshClient.
+ * If the boxsh binary is unavailable, returns the provided fallback.
+ *
+ * @param {object}  [options]
+ * @param {boolean} [options.sandbox]  Enable sandbox (default: true)
+ * @param {object}  [options.fallback] Fallback BashOperations when boxsh is not found
+ * @returns {object} BashOperations-compatible object
+ */
+export function createBashOperations(options = {}) {
+    const { sandbox = true, fallback } = options;
+    let client;
+    try {
+        client = new BoxshClient({ sandbox });
+    } catch {
+        if (fallback) {
+            console.warn('[boxsh] binary not available, using fallback');
+            return fallback;
+        }
+        throw new Error('boxsh binary not found and no fallback provided');
+    }
+
+    return {
+        async exec(command, cwd, { onData, signal, timeout } = {}) {
+            if (signal?.aborted) throw new Error('aborted');
+
+            const result = await client.exec(command, cwd, timeout);
+
+            const output = result.stdout + result.stderr;
+            if (output && onData) {
+                onData(Buffer.from(output));
+            }
+
+            return { exitCode: result.exitCode };
+        },
+    };
+}