sandboxedjs 0.1.34 → 0.1.35

package/README.md

@@ -46,6 +46,7 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **Coreutils** | 154 programs — `ls cat cp mv rm mkdir grep sed awk find head tail sort uniq wc cut tr tee xargs chmod chown ln du df ps tar gzip base64 sha256sum diff curl wget` and the rest — plus 54 shell builtins |
 | **Node.js** | Its own module engine — `require` *and* `import`, live bindings, `exports` maps, top-level `await`, npm packages, `http`, `fs`, streams, `child_process` |
 | **Python** | CPython 3.13 (Pyodide) on the *same* filesystem, with the real standard library |
+| **WebAssembly** | A WASI (`preview1`) host — run any `wasm32-wasi` binary from clang, Rust, Zig or TinyGo as an ordinary process, on the same filesystem |
 | **FFmpeg** | `ffmpeg` and `ffprobe` (FFmpeg 5.1) reading and writing container files directly — [optional install](#video-and-audio) |
 | **`/proc`** | Live and synthesised — `ps`, `top`, `free` and `uptime` all read the same source |
 | **Networking** | Virtual interfaces, `/etc/hosts` resolution, in-container HTTP servers, an optional bridge to a real host port |
@@ -359,6 +360,46 @@ The bundled standard library includes `json`, `re`, `os`, `sys`, `math`, `random
 Real CPython, so `sqlite3`, `dataclasses`, `decimal` and `typing` all work. Packages must be built for WebAssembly: `micropip` installs pure-Python wheels, and Pyodide's own distribution covers the rest
 (and only with outbound networking enabled).
 
+### WebAssembly binaries
+
+Anything compiled to `wasm32-wasi` runs as a normal container process — same filesystem, same
+environment, same pipes:
+
+```ts
+await box.fs.writeFile("/usr/local/bin/tool", await readFile("tool.wasm"), { mode: 0o755 });
+await box.exec("tool --version");
+await box.exec("cat data.csv | tool summarise | sort");
+```
+
+An executable `.wasm` file is dispatched automatically, the way a `#!` script is — `./tool.wasm`
+runs without naming an interpreter, and a binary installed into `$PATH` under a bare name is
+found by its magic number. You can also invoke the interpreter directly:
+
+```
+wasi [--dir PATH] [--mapdir GUEST=PATH] [--env K=V] MODULE.wasm [args...]
+```
+
+By default the module sees the whole filesystem. `--dir` and `--mapdir` replace that with exactly
+what you list, and a path that climbs out of a preopened directory is refused with `ENOTCAPABLE`.
+
+Building one, with any wasi-sdk clang:
+
+```bash
+clang --target=wasm32-wasip1 --sysroot="$WASI_SYSROOT" -O2 tool.c -o tool.wasm
+```
+
+Two things to know, both of which match how `wasmtime` behaves:
+
+- **A WASI program has no working directory.** wasi-libc fixes its own at `/`, so a guest's
+  relative path resolves from the root. Pass absolute paths.
+- **Sockets report `ENOTSUP`.** This container's network is an HTTP router rather than a packet
+  path, so a guest that wants to `bind()` cannot. Files, clocks, randomness, arguments,
+  environment and standard I/O all work.
+
+Standard input is drained before the module starts, because WASI's `fd_read` is synchronous and
+the container's streams are not — so piping and redirection work, but a wasm program reading a
+live terminal sees end-of-file.
+
 ### Filesystem from the host
 
 ```ts
@@ -422,6 +463,7 @@ sandboxedjs — a Linux-like container inside Node.js
   node      v22.12.0      npm, require, http servers
   python3   CPython 3.13  only WebAssembly-built C extensions
   ffmpeg    5.1.4         video and audio
+  wasi      preview1      run wasm32-wasi binaries; ./tool.wasm works
   network   on            npm install reaches the real registry
 ```
 

package/bin/sandboxedjs.mjs

@@ -171,10 +171,11 @@ async function printReplBanner(box, opts) {
     }
   };
 
-  const [node, python, ffmpeg] = await Promise.all([
+  const [node, python, ffmpeg, wasi] = await Promise.all([
     probe("node -v", (out) => out.match(/v[\d.]+/)?.[0]),
     probe("python3 -c \"import sys; print(sys.version.split()[0])\"", (out) => out),
     probe("ffmpeg -version", (out) => out.match(/ffmpeg version (\S+)/)?.[1]),
+    probe("which wasi", () => "preview1"),
   ]);
 
   const row = (name, value, note) =>
@@ -187,6 +188,7 @@ async function printReplBanner(box, opts) {
     row("node", node, "npm, require, http servers"),
     row("python3", python, "CPython via Pyodide; WebAssembly wheels only"),
     row("ffmpeg", ffmpeg, ffmpeg ? "video and audio" : "npm install @ffmpeg/core"),
+    row("wasi", wasi, "run wasm32-wasi binaries; ./tool.wasm works"),
     row(
       "network",
       opts.network ? "on" : "off",