sandboxedjs 0.1.0 → 0.1.2

package/README.md

@@ -130,12 +130,111 @@ console.log(bridge.url); // http://127.0.0.1:54321
 await bridge.close();
 ```
 
-### npm
+### Showing a live preview in an IDE
+
+This is the StackBlitz/CodeSandbox preview pane: the user runs a dev server inside the
+container, and sees the rendered page, not just logs.
+
+**It works today, as an `<iframe>` — not as a `<div>`.** A `<div>` cannot host it: the preview
+is a whole HTML document with its own scripts, styles, `<base>` and routing, and it must not be
+able to reach into your IDE's DOM. An iframe on its own origin is exactly the isolation you
+want, and it is what StackBlitz and CodeSandbox use too.
+
+`expose(port)` gives you a real, browser-loadable URL:
+
+```ts
+box.spawn("npm run dev", { cwd: "/app" });
+await box.waitForPort(5173);
+
+const preview = await box.expose(5173);
+document.querySelector("#preview").src = preview.url; // an <iframe>
+```
+
+A minimal IDE preview pane, in React:
+
+```tsx
+function PreviewPane({ box, port }) {
+  const [url, setUrl] = useState(null);
+  const frame = useRef(null);
+
+  useEffect(() => {
+    let bridge;
+    let cancelled = false;
+
+    (async () => {
+      if (!(await box.waitForPort(port, { timeoutMs: 60_000 }))) return;
+      bridge = await box.expose(port);
+      if (!cancelled) setUrl(bridge.url);
+    })();
+
+    return () => {
+      cancelled = true;
+      void bridge?.close();
+    };
+  }, [box, port]);
+
+  // Call this after a rebuild to refresh the pane.
+  const reload = () => {
+    if (frame.current) frame.current.src = frame.current.src;
+  };
+
+  if (!url) return <div>starting…</div>;
+  return <iframe ref={frame} src={url} style={{ width: "100%", height: "100%", border: 0 }} />;
+}
+```
+
+Pin the port if you want a stable URL across restarts:
+
+```ts
+const preview = await box.expose(5173, { hostPort: 5173 }); // http://127.0.0.1:5173
+```
+
+Serve several ports by exposing each one; every call gets its own host port.
+
+#### Refreshing on change
+
+**`expose()` proxies HTTP, not WebSockets.** A dev server's hot-reload channel is a WebSocket,
+so HMR and live-reload overlays will not reach the iframe. Drive the refresh from your IDE
+instead — which you need to do anyway if you are compiling on save:
+
+```ts
+// after writing the user's edit and rebuilding
+await box.fs.writeFile("/app/src/App.jsx", nextSource);
+await box.exec("npm run build", { cwd: "/app" });
+frame.current.src = frame.current.src; // reload the pane
+```
+
+That is a full reload rather than hot module replacement: state in the page is lost. For most
+IDE previews that is acceptable; if you need true HMR, the WebSocket proxy is the missing piece.
+
+#### What the IDE can and cannot do with the frame
+
+The iframe is cross-origin, so your IDE cannot read its DOM. You can still:
+
+- `postMessage` to it, if the app inside cooperates;
+- watch `/app/**` through the container to know when to rebuild;
+- read the dev server's stdout from `spawn()` for a log pane.
+
+#### In a pure browser IDE
+
+`expose()` opens a real `node:http` listener, so it needs a Node host — an Electron app, or a web
+IDE with a Node backend. With no backend at all, the preview goes through Nodepod's service
+worker instead of this package: boot Nodepod's browser build, pass it in with
+`createContainer({ pod })`, and use Nodepod's own preview iframe support. I have not verified
+that path; see [Running in a browser](#running-in-a-browser).
+
+### npm and npx
+
+> **Anything that downloads needs `network: { allowOutbound: true }`.**
+> Outbound access is off by default, so a fresh container cannot reach
+> registry.npmjs.org. `npm install` and `npx <not-yet-installed>` will fail
+> until you turn it on. This is the single most common surprise — if a package
+> command is failing, check this first.
 
 ```ts
 const box = await createContainer({
   cwd: "/app",
-  network: { allowOutbound: true }, // required to reach the registry
+  network: { allowOutbound: true }, // ← without this, npm/npx cannot install
   files: {
     "/app/package.json": JSON.stringify({
       name: "api",
@@ -156,8 +255,151 @@ box.spawn("npm start", { cwd: "/app" });
 await box.waitForPort(3000);
 ```
 
-`npx`, `yarn` and `pnpm` map onto the same installer. `apt`/`apt-get` reports the built-in
-package set rather than pretending to download Debian archives.
+`yarn` and `pnpm` map onto the same installer. `apt`/`apt-get` reports the built-in package set
+rather than pretending to download Debian archives.
+
+#### npx
+
+`npx` works the way you expect: it runs a local binary if there is one, and otherwise installs
+the package first.
+
+```ts
+const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
+
+await box.exec("npx cowsay hello");         // installs cowsay, then runs it
+await box.exec("npx cowsay hello");         // second time: instant, already installed
+await box.exec("npx sharjeelbaig");         // any package with a bin works
+await box.exec("npx -p typescript tsc -v"); // package name ≠ command name
+await box.exec("npx prettier@3.3.3 --check ."); // pin a version
+await box.exec("npx --no-install eslint");  // fail instead of installing
+```
+
+Install progress goes to stderr, so `npx cowsay moo | head -3` pipes cleanly.
+
+Without `allowOutbound`, a *not-yet-installed* command fails with a message that names the real
+problem:
+
+```
+npx: could not determine executable to run: cowsay
+npx: 'cowsay' is not installed, and installing it needs network access.
+npx: Outbound network access is disabled for this container.
+npx: Enable it with createContainer({ network: { allowOutbound: true } }).
+```
+
+Commands already present — anything in `node_modules/.bin` or on `$PATH` — still run offline.
+
+### Walkthrough: Hello React, in your browser
+
+End to end — build a React app inside the container and open it in your own browser. Copy this
+into `hello-react.mjs` and run `node hello-react.mjs`.
+
+React itself comes from a CDN through an import map, so there is no bundler to configure; the
+container only has to compile JSX and serve files.
+
+```js
+import { createContainer } from "sandboxedjs";
+
+const box = await createContainer({
+  cwd: "/app",
+  network: { allowOutbound: true }, // needed to install the JSX compiler
+  files: {
+    // 1. The React component, in real JSX.
+    "/app/src/App.jsx": `
+      import { useState } from 'react';
+
+      export default function App() {
+        const [name, setName] = useState('world');
+        return (
+          <main style={{ fontFamily: 'system-ui', padding: '3rem' }}>
+            <h1>Hello, {name}!</h1>
+            <input value={name} onChange={(e) => setName(e.target.value)} />
+          </main>
+        );
+      }
+    `,
+    "/app/src/main.jsx": `
+      import { createRoot } from 'react-dom/client';
+      import App from './App.js';
+      createRoot(document.getElementById('root')).render(<App />);
+    `,
+
+    // 2. The page. React comes from a CDN via an import map.
+    "/app/public/index.html": `<!doctype html>
+      <html>
+        <head>
+          <meta charset="utf-8" />
+          <title>Hello React</title>
+          <script type="importmap">
+            {"imports": {
+              "react": "https://esm.sh/react@18.3.1",
+              "react/jsx-runtime": "https://esm.sh/react@18.3.1/jsx-runtime",
+              "react-dom/client": "https://esm.sh/react-dom@18.3.1/client"
+            }}
+          </script>
+        </head>
+        <body>
+          <div id="root"></div>
+          <script type="module" src="/main.js"></script>
+        </body>
+      </html>`,
+
+    // 3. Compile every .jsx in src/ to plain ES modules in public/.
+    "/app/build.js": `
+      const Babel = require('@babel/standalone');
+      const fs = require('fs');
+
+      for (const file of fs.readdirSync('/app/src')) {
+        if (!file.endsWith('.jsx')) continue;
+        const { code } = Babel.transform(fs.readFileSync('/app/src/' + file, 'utf8'), {
+          filename: file,
+          presets: [['react', { runtime: 'automatic' }]],
+          sourceType: 'module',
+        });
+        fs.writeFileSync('/app/public/' + file.replace('.jsx', '.js'), code);
+        console.log('compiled', file);
+      }
+    `,
+
+    // 4. A plain static server.
+    "/app/server.js": `
+      const http = require('http');
+      const fs = require('fs');
+      const path = require('path');
+
+      http.createServer((req, res) => {
+        const url = req.url === '/' ? '/index.html' : req.url;
+        const file = path.join('/app/public', url);
+        if (!fs.existsSync(file)) { res.writeHead(404); res.end('not found'); return; }
+        const type = url.endsWith('.html') ? 'text/html' : 'text/javascript';
+        res.writeHead(200, { 'Content-Type': type });
+        res.end(fs.readFileSync(file));
+      }).listen(5173, () => console.log('listening on 5173'));
+    `,
+  },
+});
+
+// Install the compiler, compile, serve.
+await box.exec("npm install @babel/standalone", { cwd: "/app", timeoutMs: 600_000 });
+console.log((await box.exec("node build.js", { cwd: "/app" })).output);
+box.spawn("node server.js", { cwd: "/app" });
+await box.waitForPort(5173);
+
+// Publish it on a real host port and open that URL in your browser.
+const bridge = await box.expose(5173, { hostPort: 5173 });
+console.log(`open ${bridge.url}`);
+```
+
+```
+compiled App.jsx
+compiled main.jsx
+open http://127.0.0.1:5173
+```
+
+Open that URL and you get a working React app — typing in the input updates the heading. The
+JSX was compiled inside the container, the files live only in memory, and nothing was written to
+your disk.
+
+`examples/03-react-app.mjs` is the same idea with a nicer component and a `SIGINT` handler.
 
 ### Python
 
@@ -266,19 +508,103 @@ Everything runs in your Node process, so a true sandbox escape is a JavaScript-e
 This is isolation from mistakes and from ordinary untrusted programs — not a substitute for a
 VM or a real container when facing a determined attacker.
 
+## Troubleshooting
+
+**`npm install` or `npx <tool>` fails immediately.**
+You almost certainly did not pass `network: { allowOutbound: true }`. It is off by default, so
+the container cannot reach registry.npmjs.org. This is the most common surprise by far.
+
+```ts
+const box = await createContainer({ network: { allowOutbound: true } });
+```
+
+Narrow it if you like: `network: { allowOutbound: true, allowedHosts: ["registry.npmjs.org"] }`.
+
+**`command not found` for something you installed.**
+Check where it landed. `npm install` installs into the nearest `package.json` directory, so run
+it with the right `cwd`:
+
+```ts
+await box.exec("npm install express", { cwd: "/app" });
+await box.exec("ls node_modules/.bin", { cwd: "/app" });
+```
+
+**A server started with `spawn` never answers.**
+Wait for it rather than racing it:
+
+```ts
+box.spawn("node server.js", { cwd: "/app" });
+await box.waitForPort(3000, { timeoutMs: 60_000 });
+```
+
+**`exec` hangs on a command that reads stdin.**
+`exec` gives a command an empty stdin unless you pass some. `box.exec("cat")` with no `stdin`
+returns immediately; `box.spawn("cat")` gives you a live pipe to write into.
+
+**Output looks wrong when piping.**
+Pass `tty: true` only when you want terminal behaviour (colour, column layout). Without it,
+`ls` emits one name per line, like a real pipe.
+
+**A command runs forever.**
+Set `timeoutMs`, per call or as a container default. `exec` settles even if the process ignores
+its kill signal.
+
+## Running in a browser
+
+This package targets Node today, and that is what is tested. If your goal is a browser IDE, here
+is exactly where things stand.
+
+**Done — the package no longer hard-depends on Node at import time.** Compression and hashing
+resolve their implementation at call time (`node:zlib`/`node:crypto` on Node,
+`CompressionStream`/`crypto.subtle` plus a JS MD5 in a browser), so nothing pulls a `node:`
+builtin in when the module loads and a bundler will not fail on it.
+
+**You supply the pod.** The default boot path uses `@scelar/nodepod/headless`, which installs a
+`worker_threads` host. In a browser you boot Nodepod's browser build yourself — it needs a
+service worker, per Nodepod's own setup docs — and hand the instance over:
+
+```ts
+import { Nodepod } from "@scelar/nodepod";
+import { createContainer } from "sandboxedjs";
+
+const pod = await Nodepod.boot({ /* your service-worker setup */ });
+const box = await createContainer({ pod });
+
+await box.exec("ls -la /");      // shell + coreutils
+await box.exec("node app.js");   // Node, through Nodepod's browser engine
+```
+
+**What will not work in a browser:**
+
+- `copyIn()` / `copyOut()` — they read and write the host filesystem, which does not exist.
+- `expose()` — it opens a real `node:http` listener. In a browser you use Nodepod's service
+  worker and preview iframe to reach an in-container server instead of a host port.
+- The `sandboxedjs` CLI, obviously.
+
+Those three use dynamic imports, so they only fail if you call them.
+
+**Not yet verified.** I have not run this in a browser end to end. The Node-side blockers are
+removed and the seam is there, but treat browser support as "should work, unproven" rather than
+a tested claim.
+
 ## Known limits
 
 Honest list of what does not work:
 
-- **Vite's dev server** starts but fails resolving its own package metadata, because Nodepod's
-  ESM layer does not give bundled chunks a correct `import.meta.url`. Express, Koa, Fastify-style
-  apps and plain `http` servers work. See `examples/react-app` for a React setup that runs.
+- **Vite's dev server** loads and reads its config, then stops when esbuild starts: Nodepod
+  initialises esbuild by importing it from a CDN over `https:`, which the Node ESM loader
+  refuses. Anything that needs esbuild — Vite, and tools built on it — is therefore unavailable
+  under Node. Express, Koa, Fastify-style apps and plain `http` servers work. See
+  `examples/react-app` for a React setup that runs.
 - **Python is MicroPython**, so C extensions (`numpy`, `pandas`, `cryptography`) are unavailable.
 - **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.
 - **`chroot` does not isolate**; it runs the command with its cwd inside the target.
 - **`awk`'s `system()`** does not block on the child.
+- **`expose()` does not proxy WebSockets**, so dev-server HMR and live-reload do not reach a
+  preview iframe. Reload the frame from your IDE after a rebuild instead — see
+  [Showing a live preview in an IDE](#showing-a-live-preview-in-an-ide).
 
 ## API reference
 
@@ -314,6 +640,7 @@ Honest list of what does not work:
 | `expose(port, opts?)` | Bridge to a real host port |
 | `snapshot()` / `restore(s)` | Filesystem persistence |
 | `kernel`, `pod`, `net` | Escape hatches to the internals |
+| `hostname`, `user`, `cwd`, `env` | What the container was booted with |
 | `dispose()` | Tear everything down |
 
 Lower-level pieces — `Kernel`, `Vfs`, `Shell`, `Terminal`, `NetworkStack`, `defineCommand` — are