sandboxedjs 0.1.16 → 0.1.17

package/README.md

@@ -44,7 +44,7 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **Shell** | POSIX `sh` (54 builtins) — pipelines, redirection, here-docs, globbing, brace/parameter/arithmetic/command expansion, functions, `if`/`for`/`while`/`case`/`select`, job control, traps, arrays, `[[ ]]`, `(( ))` |
 | **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** | Real Node semantics via Nodepod — `require`, npm packages, `http`, `fs`, streams, `worker_threads` |
-| **Python** | MicroPython on WebAssembly, mounted on the *same* filesystem |
+| **Python** | CPython 3.13 (Pyodide) on the *same* filesystem, with the real standard library |
 | **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 |
@@ -404,7 +404,7 @@ your disk.
 
 ### Python
 
-Python is MicroPython compiled to WebAssembly, mounted on the container's filesystem:
+Python is CPython 3.13, via Pyodide, mounted on the container's filesystem:
 
 ```ts
 await box.exec("python3 -c \"print(open('/etc/hostname').read())\"");
@@ -414,7 +414,7 @@ await box.exec("echo '1 2 3' | python3 -c \"import sys; print(sum(map(int, sys.s
 
 The bundled standard library includes `json`, `re`, `os`, `sys`, `math`, `random`, `hashlib`,
 `binascii`, `struct`, `time`, `collections`, `itertools`, `functools`, `asyncio` and more. It is
-MicroPython, not CPython — there is no `numpy`, and `pip` can install pure-Python wheels only
+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).
 
 ### Filesystem from the host
@@ -478,7 +478,7 @@ line is measured on the spot rather than claimed, so a runtime that is missing s
 sandboxedjs — a Linux-like container inside Node.js
 
   node      v22.12.0      npm, require, http servers
-  python3   MicroPython   no C extensions (numpy, pandas)
+  python3   CPython 3.13  only WebAssembly-built C extensions
   ffmpeg    5.1.4         video and audio
   network   on            npm install reaches the real registry
 ```
@@ -633,33 +633,35 @@ Those use dynamic imports, so they only fail if you call them.
 
 ### Python in a browser
 
-MicroPython does not currently start in a browser. Two separate things are involved.
-
-The first is ours and is fixed: Emscripten resolves `micropython.wasm` against the loader's own
-directory, which is right in Node and wrong once a bundler has rewritten the loader into a hashed
-chunk — the guess lands on a path the dev server answers with `index.html`, and instantiation
-dies on `expected magic word 00 61 73 6d, found 3c 21 64 6f` (the first bytes of `<!doctype`).
-Pass the real URL and that goes away:
+Node resolves Pyodide from the installed package. A browser cannot resolve it by name, so tell it
+where the module and the assets are — a CDN is fine:
 
 ```ts
-import wasm from "@micropython/micropython-webassembly-pyscript/micropython.wasm?url";
+import { configurePython, createContainer } from "sandboxedjs";
+
+configurePython({
+  engine: "cpython",
+  pyodideURL: "https://cdn.jsdelivr.net/pyodide/v0.28.3/full/pyodide.mjs",
+  indexURL: "https://cdn.jsdelivr.net/pyodide/v0.28.3/full/",
+});
 
-await createContainer({ pod, python: { wasmUrl: wasm } });
+const box = await createContainer();
+await box.exec("python3 -c 'import sqlite3; print(sqlite3.sqlite_version)'");
 ```
 
-`?url` is Vite's spelling; every bundler has its own. `configurePython({ wasmUrl })` does the
-same thing outside a container.
+Without that, `engine: "auto"` finds no interpreter and falls back to MicroPython, which is why a
+browser build of this package carries no Python runtime it was not asked for.
 
-The second is upstream and is not fixed. With the correct binary loaded, instantiation fails on
+**MicroPython in a browser still does not start**, and that part is upstream. With the correct
+`.wasm` loaded — see `configurePython({ wasmUrl })` — instantiation fails on
 
 ```
 LinkError: Import #45 "env" "__syscall_poll_nonblocking": function import requires a callable
 ```
 
 The symbol appears nowhere in the shipped `micropython.mjs`, so the published glue and `.wasm`
-disagree about their import table. Node is unaffected — the Python tests pass there — and nothing
-in this package can supply a symbol the loader never declares. Treat `python3` as Node-only until
-the upstream package ships a matching pair.
+disagree about their import table. Node is unaffected. Since CPython is now the default engine,
+this only matters if you have deliberately pinned `engine: "micropython"` in a browser.
 
 ## Uploading files
 
@@ -744,7 +746,13 @@ Honest list of what does not work:
   This affects older toolchains — Vite 4 and its contemporaries. Current Vite ships its Rust
   pipeline as WebAssembly and runs fine, dev server included, as do Express, Koa, Fastify-style
   apps and plain `http` servers.
-- **Python is MicroPython**, so C extensions (`numpy`, `pandas`, `cryptography`) are unavailable.
+- **Python is CPython via Pyodide.** The standard library is the real one. A C
+  extension works only if it has been built for WebAssembly — Pyodide ships
+  many, including `numpy`, but an arbitrary wheel from PyPI will not install.
+  Starting an interpreter costs about a second and a half; one is kept per
+  container, and each program runs in its own namespace.
+- **MicroPython is still there** for hosts that would rather not carry a 13 MB
+  interpreter: `configurePython({ engine: "micropython" })`.
 - **No real sockets.** HTTP servers work through the request proxy; raw TCP/UDP does not.
 - **No real processes.** Processes are cooperative async tasks: `kill -9` cannot interrupt a
   tight synchronous loop, and `SIGSTOP` only marks state.

package/dist/index.cjs

@@ -21941,6 +21941,7 @@ function mountContainerFs(FS, opts) {
     if (isSysError(e)) return throwErrno(e.code);
     throw new FS.ErrnoError(emErrno("EIO"));
   };
+  const mountRoot = opts.mountAt ? normalize(opts.mountAt) : "/";
   const backend = {
     /** Absolute container path for a node. */
     realPath(node2) {
@@ -21950,7 +21951,9 @@ function mountContainerFs(FS, opts) {
         parts.unshift(current.name);
         current = current.parent;
       }
-      return "/" + parts.join("/");
+      const relative2 = parts.join("/");
+      if (mountRoot === "/") return "/" + relative2;
+      return relative2 ? join(mountRoot, relative2) : mountRoot;
     },
     mount(_mount) {
       return backend.createNode(null, "/", 16877 | 0, 0);
@@ -22140,6 +22143,14 @@ function mountContainerFs(FS, opts) {
       return position;
     }
   };
+  if (opts.mountAt) {
+    try {
+      FS.mkdir(mountRoot);
+    } catch {
+    }
+    FS.mount(backend, {}, mountRoot);
+    return;
+  }
   FS.root = null;
   FS.mount(backend, {}, "/");
   try {
@@ -22148,13 +22159,286 @@ function mountContainerFs(FS, opts) {
   }
 }
 
+// src/runtime/cpython.ts
+var RESERVED_FOR_INTERPRETER = /* @__PURE__ */ new Set(["lib", "dev", "proc"]);
+var pyodideModule = null;
+var indexUrl;
+var moduleUrl;
+function configureCPython(options = {}) {
+  if (options.indexURL !== void 0) indexUrl = options.indexURL;
+  if (options.moduleURL !== void 0) {
+    moduleUrl = options.moduleURL;
+    pyodideModule = null;
+  }
+}
+function importPyodide() {
+  if (!pyodideModule) {
+    const specifier = moduleUrl ?? ["py", "odide"].join("");
+    pyodideModule = import(
+      /* @vite-ignore */
+      /* webpackIgnore: true */
+      specifier
+    );
+  }
+  return pyodideModule;
+}
+var isNode2 = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+async function resolveIndexUrl() {
+  if (indexUrl) return indexUrl;
+  if (!isNode2) return void 0;
+  try {
+    const { createRequire } = await nodeBuiltin("module");
+    const path = await nodeBuiltin("path");
+    const require2 = createRequire(path.join(process.cwd(), "index.js"));
+    return `${path.dirname(require2.resolve("pyodide/package.json"))}/`;
+  } catch {
+    return void 0;
+  }
+}
+async function isCPythonAvailable() {
+  try {
+    await importPyodide();
+    return true;
+  } catch {
+    return false;
+  }
+}
+var interpreters = /* @__PURE__ */ new WeakMap();
+async function interpreterFor(ctx) {
+  const existing = interpreters.get(ctx.vfs);
+  if (existing) return existing;
+  const starting = (async () => {
+    const { loadPyodide } = await importPyodide();
+    const resolved = await resolveIndexUrl();
+    const py = await loadPyodide({
+      ...resolved ? { indexURL: resolved } : {},
+      /* Output is rebound per program; these only catch anything printed
+       * while the interpreter is still starting. */
+      stdout: () => {
+      },
+      stderr: () => {
+      }
+    });
+    mountContainerDirs(py, ctx);
+    installRunner(py);
+    return py;
+  })();
+  interpreters.set(ctx.vfs, starting);
+  try {
+    return await starting;
+  } catch (error) {
+    interpreters.delete(ctx.vfs);
+    throw error;
+  }
+}
+function installRunner(py) {
+  py.__sbxRun = py.runPython(`
+from pyodide.code import eval_code_async
+
+async def __sbx_run(source, scope):
+    try:
+        await eval_code_async(source, globals=scope)
+        return 0
+    except SystemExit as exit:
+        code = exit.code
+        if code is None:
+            return 0
+        return code if isinstance(code, int) else 1
+
+__sbx_run
+`);
+}
+function mountContainerDirs(py, ctx) {
+  const mounted = py.__sbxMounted ??= /* @__PURE__ */ new Set();
+  let entries;
+  try {
+    entries = ctx.vfs.readdirWithTypes("/", ctx.cred);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.kind !== "directory") continue;
+    if (RESERVED_FOR_INTERPRETER.has(entry.name)) continue;
+    if (mounted.has(entry.name)) continue;
+    try {
+      mountContainerFs(py.FS, {
+        vfs: ctx.vfs,
+        cred: ctx.cred,
+        mountAt: `/${entry.name}`
+      });
+      mounted.add(entry.name);
+    } catch {
+    }
+  }
+}
+function bootstrap(py, ctx, argv, scriptDir) {
+  const paths = [
+    ...scriptDir ? [scriptDir] : [""],
+    "/usr/lib/python3",
+    "/usr/lib/python3/site-packages",
+    "/usr/local/lib/python3/site-packages"
+  ];
+  py.runPython(`
+import sys, os
+sys.argv[:] = ${JSON.stringify(argv)}
+for __p in reversed(${JSON.stringify(paths)}):
+    if __p and __p not in sys.path:
+        sys.path.insert(0, __p)
+    elif __p == "" and "" not in sys.path:
+        sys.path.insert(0, "")
+try:
+    del __p
+except NameError:
+    pass
+os.environ.clear()
+os.environ.update(${JSON.stringify(ctx.env)})
+`);
+  try {
+    py.FS.chdir(ctx.cwd);
+  } catch {
+  }
+}
+function reportError(ctx, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const systemExit = /SystemExit:?\s*(-?\d+)?/.exec(message);
+  if (systemExit) {
+    return systemExit[1] !== void 0 ? Number(systemExit[1]) & 255 : 0;
+  }
+  if (/KeyboardInterrupt/.test(message)) {
+    ctx.stderr.write("KeyboardInterrupt\n");
+    return 130;
+  }
+  const text = message.replace(/^PythonError:\s*/, "");
+  ctx.stderr.write(text.endsWith("\n") ? text : `${text}
+`);
+  return 1;
+}
+async function runCPythonProgram(ctx, source, argv, scriptDir, stdinText) {
+  let py;
+  try {
+    py = await interpreterFor(ctx);
+  } catch (error) {
+    ctx.stderr.write(
+      `python3: CPython is unavailable in this host (${error instanceof Error ? error.message : String(error)})
+`
+    );
+    return { exitCode: 127 };
+  }
+  mountContainerDirs(py, ctx);
+  try {
+    await py.loadPackagesFromImports(source, {
+      messageCallback: () => {
+      },
+      errorCallback: () => {
+      }
+    });
+  } catch {
+  }
+  const encoder6 = new TextEncoder();
+  const decoder7 = new TextDecoder();
+  py.setStdout({
+    write: (buffer) => {
+      ctx.write(decoder7.decode(buffer));
+      return buffer.length;
+    }
+  });
+  py.setStderr({
+    write: (buffer) => {
+      ctx.stderr.write(decoder7.decode(buffer));
+      return buffer.length;
+    }
+  });
+  if (stdinText !== null) {
+    const bytes = encoder6.encode(stdinText);
+    let offset = 0;
+    py.setStdin({
+      read: (buffer) => {
+        const take = Math.min(buffer.length, bytes.length - offset);
+        buffer.set(bytes.subarray(offset, offset + take));
+        offset += take;
+        return take;
+      }
+    });
+  } else {
+    py.setStdin({ read: () => 0 });
+  }
+  try {
+    bootstrap(py, ctx, argv, scriptDir);
+  } catch (error) {
+    return { exitCode: reportError(ctx, error) };
+  }
+  const globals = py.globals.get("dict")();
+  try {
+    globals.set("__name__", "__main__");
+    const exitCode = await py.__sbxRun(source, globals);
+    return { exitCode: Number(exitCode) & 255 };
+  } catch (error) {
+    return { exitCode: reportError(ctx, error) };
+  } finally {
+    try {
+      globals.destroy();
+    } catch {
+    }
+  }
+}
+var micropip = defineCommand({
+  name: "micropip",
+  path: "/usr/bin/micropip",
+  summary: "install Python packages into the running interpreter",
+  usage: "micropip install <package>...",
+  async run(ctx) {
+    const [action, ...packages] = ctx.args;
+    if (action !== "install" || packages.length === 0) {
+      ctx.line("usage: micropip install <package>...");
+      return action === void 0 ? 1 : 0;
+    }
+    let py;
+    try {
+      py = await interpreterFor(ctx);
+    } catch {
+      ctx.stderr.write("micropip: CPython is unavailable in this host\n");
+      return 127;
+    }
+    try {
+      await py.loadPackage("micropip");
+      const micropipModule = py.pyimport("micropip");
+      for (const name of packages) {
+        ctx.line(`Collecting ${name}`);
+        await micropipModule.install(name);
+        ctx.line(`Successfully installed ${name}`);
+      }
+      return 0;
+    } catch (error) {
+      ctx.stderr.write(
+        `micropip: ${error instanceof Error ? error.message : String(error)}
+`
+      );
+      return 1;
+    }
+  }
+});
+
 // src/runtime/python.ts
 init_path();
 var PYTHON_VERSION = "3.4.0";
 var MICROPYTHON_BANNER = "MicroPython v1.28.0 on 2026-04-06; SandboxedJS with Emscripten";
 var loaderPromise = null;
 var wasmUrl;
+var engine = "auto";
+var cpythonUsable = null;
+async function useCPython() {
+  if (engine === "micropython") return false;
+  if (engine === "cpython") return true;
+  cpythonUsable ??= isCPythonAvailable();
+  return cpythonUsable;
+}
 function configurePython(options = {}) {
+  if (options.engine !== void 0) {
+    engine = options.engine;
+    cpythonUsable = null;
+  }
+  if (options.indexURL !== void 0) configureCPython({ indexURL: options.indexURL });
+  if (options.pyodideURL !== void 0) configureCPython({ moduleURL: options.pyodideURL });
   if (options.wasmUrl !== void 0) wasmUrl = options.wasmUrl;
 }
 async function getLoader() {
@@ -22229,6 +22513,9 @@ function reportPythonError(ctx, e) {
   return 1;
 }
 async function runProgram(ctx, source, argv, scriptDir, stdinText) {
+  if (await useCPython()) {
+    return runCPythonProgram(ctx, source, argv, scriptDir, stdinText);
+  }
   let stdinOffset = 0;
   const stdinBytes = stdinText === null ? new Uint8Array(0) : new TextEncoder().encode(stdinText);
   const mp = await createInterpreter(ctx, {
@@ -22551,7 +22838,7 @@ async function readZip(data) {
   return entries;
 }
 function pythonCommands() {
-  return [python, pip];
+  return [python, pip, micropip];
 }
 
 // src/runtime/ffmpeg.ts
@@ -22780,8 +23067,8 @@ function renameShadowedExports(source) {
     for (const [key, value] of Object.entries(node2)) {
       if (key === "type" || key === "start" || key === "end" || skip.includes(key)) continue;
       if (Array.isArray(value)) {
-        for (const item of value) if (isNode2(item)) visit(item, childScope);
-      } else if (isNode2(value)) {
+        for (const item of value) if (isNode3(item)) visit(item, childScope);
+      } else if (isNode3(value)) {
         visit(value, childScope);
       }
     }
@@ -22805,9 +23092,9 @@ function blockNames(body) {
       for (const declarator of node2.declarations) {
         collectPattern(declarator.id, names);
       }
-    } else if (node2.type === "ClassDeclaration" && isNode2(node2.id)) {
+    } else if (node2.type === "ClassDeclaration" && isNode3(node2.id)) {
       names.add(node2.id.name);
-    } else if (node2.type === "FunctionDeclaration" && isNode2(node2.id)) {
+    } else if (node2.type === "FunctionDeclaration" && isNode3(node2.id)) {
       names.add(node2.id.name);
     }
   }
@@ -22818,10 +23105,10 @@ function collectVars(nodes, names) {
     for (const item of nodes) collectVars(item, names);
     return;
   }
-  if (!isNode2(nodes)) return;
+  if (!isNode3(nodes)) return;
   const node2 = nodes;
   if (node2.type === "FunctionDeclaration" || node2.type === "FunctionExpression" || node2.type === "ArrowFunctionExpression") {
-    if (isNode2(node2.id)) names.add(node2.id.name);
+    if (isNode3(node2.id)) names.add(node2.id.name);
     return;
   }
   if (node2.type === "VariableDeclaration" && node2.kind === "var") {
@@ -22835,7 +23122,7 @@ function collectVars(nodes, names) {
   }
 }
 function collectPattern(node2, names) {
-  if (!isNode2(node2)) return;
+  if (!isNode3(node2)) return;
   switch (node2.type) {
     case "Identifier":
       names.add(node2.name);
@@ -22859,7 +23146,7 @@ function collectPattern(node2, names) {
   }
 }
 function isExports(value) {
-  return isNode2(value) && value.type === "Identifier" && value.name === NAME;
+  return isNode3(value) && value.type === "Identifier" && value.name === NAME;
 }
 function freshName(source) {
   let name = "__sandboxedjs_exports";
@@ -22867,7 +23154,7 @@ function freshName(source) {
   while (source.includes(name)) name = `__sandboxedjs_exports${++suffix}`;
   return name;
 }
-function isNode2(value) {
+function isNode3(value) {
   return typeof value === "object" && value !== null && typeof value.type === "string";
 }
 var NOTHING = [];
@@ -24818,6 +25105,7 @@ exports.braceExpand = braceExpand;
 exports.buildRootfs = buildRootfs;
 exports.builtinNames = builtinNames;
 exports.captureStdio = captureStdio;
+exports.configureCPython = configureCPython;
 exports.configurePython = configurePython;
 exports.createContainer = createContainer;
 exports.createContext = createContext;
@@ -24836,6 +25124,7 @@ exports.globToRegex = globToRegex;
 exports.hasMagic = hasMagic;
 exports.installUserland = installUserland;
 exports.isBuiltinName = isBuiltinName;
+exports.isCPythonAvailable = isCPythonAvailable;
 exports.isPythonAvailable = isPythonAvailable;
 exports.isSysError = isSysError;
 exports.makeCred = makeCred;