sandboxedjs 0.2.11 → 0.2.12

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="assets/logo.png" alt="SandboxedJS" width="140" />
+<img src="https://cdn.jsdelivr.net/npm/sandboxedjs@latest/assets/logo.png" alt="SandboxedJS" width="140" />
 
 # SandboxedJS
 
@@ -117,7 +117,9 @@ terminal.start();
 This is the case most people arrive for: a Vite frontend and a Python backend, in one container, in
 a tab — the frontend calling `http://localhost:8000`, the backend calling a real API.
 
-Two different problems hide in that sentence, and SandboxedJS solves them in two different ways.
+The frontend-to-backend hop and the backend-to-internet hop have different requirements.
+See the [full-stack deployment guide](docs/fullstack-deployment.md) for production asset staging,
+Cloudflare Pages, Vercel, Node/serverless lifetimes, and troubleshooting.
 
 ### 1. Frontend → backend: nothing to configure
 
@@ -149,10 +151,14 @@ await box.exec("npm install", { cwd: "/app/frontend", timeoutMs: 600_000 });
 
 box.spawn("fastapi run", { cwd: "/app/backend" });
 box.spawn("npm run dev", { cwd: "/app/frontend" });
-await box.waitForPort(3000, { timeoutMs: 60_000 });
-
-const preview = await createPreview(box); // null where service workers are unavailable
-iframe.src = preview!.urlFor(3000);
+if (!(await box.waitForPort(8000, { timeoutMs: 60_000 })) ||
+    !(await box.waitForPort(3000, { timeoutMs: 60_000 }))) {
+  throw new Error("Check backend and frontend startup logs");
+}
+
+const preview = await createPreview(box);
+if (!preview) throw new Error("Preview requires a working service worker");
+iframe.src = preview.urlFor(3000);
 ```
 
 It works between preview pages and from another tab of the same browser while the owner page is
@@ -172,13 +178,14 @@ browser's rule about _pages_, not a container limit, and the only way through it
 somewhere a page is not. So add one to the project you already deploy:
 
 ```bash
-npx sandboxedjs-egress init --allow ollama.com,api.openai.com
+npx sandboxedjs-egress init --target cloudflare --allow ollama.com,api.openai.com
 ```
 
 That writes a single function file at the path your host serves — Cloudflare Pages, Vercel and
 Netlify are detected, `--target` names one. Nothing else changes: a container in a browser probes
-its own origin for that proxy before giving up, so **no project passes a `proxy` option and no
-project is configured twice.**
+its own origin for that proxy before giving up. The guest project needs no proxy setting;
+the host must deploy the generated function. For a separate relay, set `network.proxy`.
+A host serving only static files cannot relay APIs that reject browser requests.
 
 | Where you are                     | What to do                                                                          |
 | --------------------------------- | ----------------------------------------------------------------------------------- |

package/bin/sandboxedjs-egress.mjs

@@ -45,7 +45,7 @@ const TARGETS = {
 ${allow}
 /* Cloudflare Pages serves this file at /__sandboxedjs__/egress, which is where
  * a container in this site's pages looks for its way out. */
-export const onRequest = ({ request }) => handleEgressRequest(request, options);
+export const onRequest = ({ request }: { request: Request }) => handleEgressRequest(request, options);
 `,
   },
   vercel: {
@@ -57,7 +57,7 @@ export const config = { runtime: "edge" };
 
 /* Vercel serves this file at /api/__sandboxedjs__/egress, which is one of the
  * paths a container in this site's pages probes for its way out. */
-export default (request) => handleEgressRequest(request, options);
+export default (request: Request) => handleEgressRequest(request, options);
 `,
   },
   netlify: {
@@ -67,7 +67,7 @@ export default (request) => handleEgressRequest(request, options);
 ${allow}
 export const config = { path: "/.netlify/functions/sandboxedjs-egress" };
 
-export default (request) => handleEgressRequest(request, options);
+export default (request: Request) => handleEgressRequest(request, options);
 `,
   },
 };
@@ -90,13 +90,28 @@ async function detectTarget(root) {
 }
 
 async function init(argv) {
-  const root = argv.find((a) => !a.startsWith("-")) ?? process.cwd();
-  const at = argv.indexOf("--target");
-  const allowAt = argv.indexOf("--allow");
-  const allowed = allowAt === -1
-    ? null
-    : (argv[allowAt + 1] ?? "").split(",").map((h) => h.trim()).filter(Boolean);
-  const name = at === -1 ? await detectTarget(root) : argv[at + 1];
+  let directory;
+  let targetName;
+  let allowed = null;
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === "--target" || argument === "--allow") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) {
+        console.error(`sandboxedjs-egress init: ${argument} requires a value`);
+        process.exitCode = 1;
+        return;
+      }
+      if (argument === "--target") targetName = value;
+      else allowed = value.split(",").map((host) => host.trim()).filter(Boolean);
+    } else if (argument.startsWith("-") || directory !== undefined) {
+      console.error(`sandboxedjs-egress init: unexpected argument ${argument}`);
+      process.exitCode = 1;
+      return;
+    } else directory = argument;
+  }
+  const root = directory ?? process.cwd();
+  const name = targetName ?? await detectTarget(root);
   if (!name || !TARGETS[name]) {
     console.error(
       name

package/dist/index.cjs

@@ -21103,7 +21103,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.11"};
+  version: "0.2.12"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/dist/index.js

@@ -21086,7 +21086,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.11"};
+  version: "0.2.12"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/dist/service-worker.js

@@ -530,7 +530,8 @@ var PreviewRouter = class {
       this.options.onStale?.(clientId);
     }
     const headers = new Headers(result.headers);
-    const body = this.options.injectSockets === false ? result.body : withSockets(result.body, headers);
+    const bodyless = request.method === "HEAD" || [204, 205, 304].includes(result.status);
+    const body = bodyless ? null : this.options.injectSockets === false ? result.body : withSockets(result.body, headers);
     headers.set("Cross-Origin-Resource-Policy", "cross-origin");
     headers.set("Cross-Origin-Embedder-Policy", "require-corp");
     return new Response(body, { status: result.status, statusText: result.statusText, headers });
@@ -656,7 +657,7 @@ worker.addEventListener("fetch", (event) => {
   const claimed = router.claimedPort(url.pathname);
   if (claimed !== null && event.request.mode === "navigate") {
     router.bind(event.resultingClientId || event.clientId, claimed);
-    event.respondWith(router.fetch(claimed, "/", event.request, event.resultingClientId || event.clientId));
+    event.respondWith(router.fetch(claimed, router.containerPath(url.pathname, url.search), event.request, event.resultingClientId || event.clientId));
     return;
   }
   const port = router.portForRequest(url.pathname, event.clientId);

package/docs/agent/COMMANDS.md

@@ -0,0 +1,85 @@
+# Command catalog
+
+Run commands from `/Users/shazi/Projects/SandboxedJs` unless stated otherwise.
+Use focused commands first. Keep long logs out of model context:
+
+```sh
+some-command > /tmp/sbx-native-build.log 2>&1
+tail -n 120 /tmp/sbx-native-build.log
+```
+
+Do not use the redirection form when editing source files; it is for disposable
+logs only.
+
+## Cheap inspection
+
+```sh
+git status --short
+git diff --cached --check
+git diff --cached --stat
+python3 -m json.tool python-runtime/abi/extension-abi.json >/dev/null
+```
+
+## Build prerequisites and runtime
+
+```sh
+make -C python-runtime doctor
+make -C python-runtime python PROFILE=dynamic
+make -C python-runtime package PROFILE=dynamic
+npm run build
+```
+
+Do not rebuild CPython when the runtime and ABI inputs have not changed and the
+required output already exists.
+
+## Extension fixtures and index
+
+```sh
+python3 python-runtime/scripts/build_extension.py \
+  python-runtime/fixtures/sbx_setuptools_probe/recipe.json
+python3 python-runtime/scripts/build_extension.py \
+  python-runtime/fixtures/sbx_cython_probe/recipe.json
+python3 python-runtime/scripts/build_extension.py \
+  python-runtime/fixtures/sbx_rust_probe/recipe.json
+python3 python-runtime/scripts/build_index.py
+```
+
+If a wheel changes, rebuild `index.json` before runtime tests or its digest will
+correctly be stale.
+
+## Focused tests
+
+```sh
+npx vitest run test/python-runtime/extensions.test.ts
+npx vitest run test/python-runtime/resolver.test.ts
+npx vitest run test/python-runtime/extension-abi.test.ts
+npm run typecheck
+```
+
+Run `npm run check` only at milestone gates. Network-enabled suites are not a
+default native-package check.
+
+## Wheel inspection
+
+```sh
+python3 -m zipfile -l path/to/package.whl
+python3 python-runtime/scripts/build_index.py --wheels path/to/wheel-directory
+```
+
+Prefer adding a small reusable inspection script over repeatedly embedding
+complex Python in shell commands.
+
+## Logs
+
+Use one log per active failure under `/tmp`, named with the task and package.
+Keep only:
+
+- the exact command;
+- toolchain versions when relevant;
+- first causal error;
+- final 80-150 lines;
+- exit code.
+
+Warnings are not tasks unless they identify incorrect output or a future
+failure covered by the current milestone.
+

package/docs/agent/DECISION-TREE.md

@@ -0,0 +1,84 @@
+# Failure classification and decisions
+
+Classify an observed failure by its earliest decisive symptom.
+
+## Resolver says no usable distribution
+
+1. Inspect candidate filenames and tags.
+2. If a pure wheel exists, fix resolver/tag/metadata behavior; do not compile.
+3. If a matching SandboxedJS wheel exists, inspect index `abiId`, digest, and
+   dependency metadata.
+4. If only an sdist or host-native wheels exist, route to the external
+   cross-builder. Do not let the runtime installer build source yet.
+
+## Build frontend cannot start
+
+- Missing host Python module: classify as a build requirement.
+- Unpinned requirement: add an exact version and hash acquisition path.
+- Unsupported backend: add a backend adapter, not a package conditional.
+- Network failure: preserve the command and request network approval; do not
+  substitute an unverified archive.
+
+## Compiler uses host headers or compiler
+
+- Inspect generated cross-sysconfig and command line.
+- Fix host/target environment separation.
+- Never solve this by renaming a produced artifact.
+
+## Header or library not found
+
+1. Determine whether it is a Python dependency or a native target library.
+2. For a target library, require a declared, pinned native dependency.
+3. Build it into the ABI/profile-specific sysroot.
+4. Expose sysroot include/library paths through the cross environment.
+5. Add a reduced fixture proving the dependency mechanism before retrying a
+   large real package.
+
+## Configure test compiles, then tries to execute
+
+This is a cross-compilation probe problem. Prefer, in order:
+
+1. upstream-supported cross-file/cache variables;
+2. a generic build-backend cross configuration;
+3. a visible package patch providing the target fact.
+
+Never execute target WebAssembly as if it were a host binary. If executing a
+probe under a controlled runner is proposed, stop for architectural review.
+
+## Linker failure
+
+- Missing `Py*` symbols can remain unresolved in a side module if supplied by
+  the main module; confirm rather than blindly adding `-lpython`.
+- Missing native-library symbols require target dependency/link-order work.
+- Shared-memory, PIC, exception, relocation, or atomics errors are ABI issues;
+  inspect `INVARIANTS.md` and escalate before changing flags.
+- Duplicate symbols often indicate a static library linked twice; inspect the
+  complete link line.
+
+## Wheel builds but validation fails
+
+- Not `\0asm`: host compiler leakage.
+- No `dylink`: side-module link mode was lost.
+- Missing `PyInit_*`: module naming/export problem.
+- Wrong tag or ABI: wheel construction problem. Rebuild; never retag.
+
+## Install succeeds but import fails
+
+- Missing Python wrapper files: wheel assembly/layout defect.
+- Missing dependent shared/static symbols: target dependency closure defect.
+- Init symbol mismatch: derive the module name from installed path.
+- Trap, memory corruption, or exception failure: ABI mismatch until disproven.
+
+## Import succeeds but behavior fails
+
+Classify whether the package needs an unavailable OS capability, contains a
+32-bit assumption, exceeds memory, or has a package defect. Record an honest
+compatibility limitation when the platform capability is genuinely absent.
+
+## Test hangs
+
+Do not immediately increase timeouts. Determine whether the process is waiting
+on input, network, a child process, a pthread, or a host ABI response. Capture a
+bounded stack/process snapshot where possible. Kill only the exact process you
+started.
+

package/docs/agent/INVARIANTS.md

@@ -0,0 +1,40 @@
+# Non-negotiable invariants
+
+Read this before changing ABI, wheel, resolver, or compiler behavior.
+
+1. `python-runtime/abi/extension-abi.json` is the source of truth for target
+   identity and compile/link compatibility. Recipes cannot override ABI flags.
+2. A host-native ELF, Mach-O, `.node`, or other binary is never accepted or
+   relabeled as WebAssembly.
+3. A native wheel must match both its Python wheel tag and SandboxedJS
+   `abiId`.
+4. Build tools run on the build machine. Target code and target libraries are
+   compiled for wasm32. Never put target artifacts on the host interpreter's
+   import path.
+5. Build, host, Python-runtime, and native-target dependencies are separate
+   concepts and must be represented separately.
+6. Sources and build-tool artifacts are version-pinned and hash-verifiable.
+7. Generic behavior lives in generic machinery. Package-specific behavior is
+   visible in a recipe and/or patch, never hidden behind `if package == ...`.
+8. The package's own metadata is authoritative. Recipes may constrain or add
+   target facts, but must not silently duplicate drifting `Requires-Dist` data.
+9. Installer operations remain transactional. Failed resolution, download, or
+   installation must not leave a partial environment.
+10. A build is supported only after the wheel installs and its compiled module
+    executes under the owned SandboxedJS CPython runtime.
+11. Browser compatibility remains mandatory. Runtime TypeScript must not gain
+    unconditional Node builtin imports.
+12. Unsupported operating-system capabilities fail honestly. Package success
+    must not be manufactured by fake sockets, fake processes, or silent skips.
+
+## Forbidden shortcuts
+
+- Weakening `verify_side_module` or ABI checks to make a fixture pass.
+- Adding arbitrary recipe compiler/link flags.
+- Copying metadata solely from a handwritten recipe when upstream metadata can
+  be generated.
+- Installing unpinned build requirements from the network in a release build.
+- Treating "wheel file exists" as an acceptance result.
+- Starting with NumPy-specific branches in the generic pipeline.
+- Running full tests repeatedly when a focused test identifies the defect.
+

package/docs/agent/LAUNCH-PROMPT.md

@@ -0,0 +1,37 @@
+# Prompt to launch or resume Claude Opus
+
+Copy the text below into the coding task. Do not paste the rest of this folder
+into the prompt; the agent should read files on demand.
+
+```text
+You are the sole implementation agent for the SandboxedJS native Python
+package platform. The project controller is:
+
+agent-projects/python-package-platform/README.md
+
+Begin by reading only README.md, STATE.md, and the current task named in
+STATE.md. Follow LOOP.md. Execute commands and make decisions from their actual
+outputs. Continue through tasks while gates pass and context remains healthy.
+Keep STATE.md current so another task can resume without chat history.
+
+Preserve all pre-existing and staged work. Do not commit, publish, deploy,
+discard changes, weaken ABI validation, or change the ABI contract unless I
+explicitly authorize it. Use focused tests before broad suites. Keep long build
+logs in /tmp and bring only decisive excerpts into context.
+
+If a stop condition in LOOP.md occurs, stop with a compact escalation packet.
+The goal is a general package platform; NumPy is a later acceptance case, not a
+package-specific architecture target.
+
+Do not merely review or propose a plan. Work autonomously: inspect, edit,
+execute focused commands, diagnose their outputs, verify exit gates, update
+STATE.md, and advance to the next task. Do not ask for confirmation between
+ordinary in-scope steps. Continue until a documented stop condition requires my
+decision or all roadmap gates are complete.
+```
+
+## Execution policy
+
+This workflow assumes one Claude Opus agent. Do not delegate work to other
+models or create subagents. Use the stop conditions and ask the user for one
+concrete decision only when necessary.

package/docs/agent/LOOP.md

@@ -0,0 +1,84 @@
+# Agent execution loop
+
+Use this loop exactly. It is designed for a smaller model that can act well
+when each decision is grounded in the previous command's output.
+
+## 1. Orient
+
+Read `README.md`, `STATE.md`, and the current task only. Inspect `git status
+--short` before editing. Treat all pre-existing changes as user-owned.
+
+State the current hypothesis in one sentence. A hypothesis must predict an
+observable result, for example: "the linker cannot find `libxml2` because the
+dynamic sysroot is absent from target link flags."
+
+## 2. Choose the cheapest discriminating command
+
+Run the smallest command that can disprove the hypothesis. Prefer, in order:
+
+1. static inspection of one relevant file;
+2. one unit test or one fixture build;
+3. one runtime import test;
+4. the focused suite;
+5. the full suite only at a milestone gate.
+
+Never rerun a long build unchanged. If a command failed, inspect its decisive
+error first and change either the hypothesis or the implementation.
+
+## 3. Classify the result
+
+Use `DECISION-TREE.md`. Every failure must be classified before code changes.
+If there is not enough evidence, gather more evidence rather than guessing.
+
+## 4. Make one coherent change
+
+Change the smallest architectural seam that removes the demonstrated failure
+class. Do not add a package-name conditional to the generic builder. A package
+patch belongs in an explicit recipe patch directory, with a comment explaining
+the upstream assumption it replaces.
+
+Use `apply_patch` for hand edits. Do not overwrite files with shell redirects.
+Do not alter generated ABI files directly.
+
+## 5. Verify in layers
+
+Run the focused check that failed. If it passes, run the task's exit gate.
+Compilation is never the final gate for an extension: install and import it in
+the owned CPython runtime and exercise at least one native behavior.
+
+## 6. Record and advance
+
+Update `STATE.md` with compact evidence. If the task exit gate passes, set its
+checkboxes, point `Current task` to the next task in `ROADMAP.md`, and continue
+if budget remains.
+
+## Stop conditions
+
+Stop and request a user decision when:
+
+- the next action requires credentials, deployment, paid infrastructure, or
+  publishing outside the repository;
+- fulfilling the task requires changing the ABI contract rather than fixing a
+  consumer of it;
+- an upstream license is unclear or incompatible;
+- a destructive action, history rewrite, or discard of existing work appears
+  necessary;
+- the same failure class survives three evidence-driven attempts;
+- a design choice changes public API or materially increases shipped runtime
+  size without an already-stated budget.
+
+When stopping, preserve logs and state the smallest exact decision needed.
+
+## Escalation packet for the user
+
+When a stop condition is reached, prepare a compact packet containing:
+
+- intended invariant;
+- exact command;
+- final 80-150 relevant log lines;
+- files and functions involved;
+- three attempted hypotheses and what disproved each;
+- the decision required.
+
+Do not send entire build logs or the full repository history. Wait for the
+user's decision, record it in `STATE.md`, and then resume this same loop.

package/docs/agent/README.md

@@ -0,0 +1,77 @@
+# SandboxedJS native Python package platform
+
+This folder is an executable work specification for a coding agent. Its goal is
+not to port NumPy. Its goal is to make native Python packages a platform
+capability of SandboxedJS, with NumPy eventually serving as one demanding
+acceptance case.
+
+## Start here
+
+At the beginning of every turn, read only these files:
+
+1. `README.md` (this file).
+2. `STATE.md`.
+3. The one task file named by `STATE.md`.
+
+Do not reread every document on every turn. Open `INVARIANTS.md`,
+`DECISION-TREE.md`, or `COMMANDS.md` only when the current task points to them
+or an observed failure requires them. This is intentional: the folder is also
+a context and token budget.
+
+Then execute the loop in `LOOP.md`. Continue until the current task's exit gate
+passes or a stop condition requires the user or a stronger model.
+
+## Product objective
+
+The eventual user experience is:
+
+```sh
+pip install some-package
+```
+
+The implementation may obtain a pure wheel, install an already-built
+SandboxedJS wheel, or ask an external build system to create and cache a wheel.
+It must never install a host-native artifact by relabeling it, silently omit a
+dependency, or claim support because compilation alone succeeded.
+
+## Current baseline
+
+The working tree already contains staged, uncommitted work produced in an
+earlier session:
+
+- a generic setuptools cross environment;
+- package-owned `setup.py` and `pyproject.toml` builds;
+- C and Cython fixtures;
+- the existing PyO3 path;
+- side-module validation and runtime import tests;
+- `docs/python/cross-build.md`, which records ten known assumptions.
+
+Preserve those staged changes. Do not unstage, discard, rewrite wholesale, or
+commit them unless the user explicitly requests it. First verify them and
+record the result in `STATE.md`.
+
+## Scope boundary
+
+This project owns:
+
+- reproducible cross-build inputs;
+- build/host/target dependency separation;
+- package build-backend execution;
+- ABI-valid wheel construction and metadata;
+- wheel indexing, resolution, installation, and runtime verification;
+- explicit recipes and patches for irreducibly package-specific behavior;
+- compatibility evidence.
+
+This project does not own, unless the user separately authorizes it:
+
+- a hosted public build service;
+- cloud accounts, deployment, billing, or package signing infrastructure;
+- pretending raw sockets, subprocesses, GPU APIs, or unavailable operating
+  system capabilities exist;
+- broad unrelated cleanup of SandboxedJS.
+
+## Definition of success
+
+Success is a general pipeline demonstrated by several independent package
+shapes, not one famous package. The final gate is described in `ROADMAP.md`.
+

package/docs/agent/ROADMAP.md

@@ -0,0 +1,37 @@
+# Capability roadmap
+
+Advance only when the current task's exit gate passes. Each task must leave a
+focused regression test.
+
+| Order | Task | Capability produced |
+| --- | --- | --- |
+| 00 | `tasks/00-verify-inherited-work.md` | trusted baseline for the staged generic builder |
+| 01 | `tasks/01-authoritative-metadata.md` | wheel metadata derived from the package |
+| 02 | `tasks/02-native-dependencies.md` | declared target libraries and profile sysroot |
+| 03 | `tasks/03-reproducible-inputs.md` | hashed sources, build tools, patches, provenance |
+| 04 | `tasks/04-build-frontends.md` | explicit backend interface beyond setuptools/PyO3 |
+| 05 | `tasks/05-registry-integration.md` | reproducible build output consumable by `pip` |
+| 06 | `tasks/06-package-cohorts.md` | evidence across independent package shapes |
+| 07 | `tasks/07-build-on-miss-boundary.md` | local protocol/spec for an eventual build service |
+
+## Platform completion gate
+
+The platform milestone is complete when all of the following are true:
+
+- Pure wheels continue to install directly and transactionally.
+- Three native language/build shapes work without package-name branches.
+- At least one extension links a separately built native target library.
+- At least one package needs and cleanly carries a visible target patch.
+- Wheel metadata and dependency resolution come from authoritative package
+  metadata plus explicit target constraints.
+- Every indexed artifact is source-pinned, hash-verifiable, ABI-identified,
+  installable, importable, and behavior-tested in the owned runtime.
+- A compatibility report distinguishes supported, recipe-required,
+  platform-blocked, and not-yet-attempted packages.
+- The external build-on-miss interface is specified without embedding a
+  compiler toolchain in the browser runtime.
+
+NumPy may be attempted after tasks 00-05. It is evidence for native dependency,
+build-probe, memory, and scientific-stack behavior; it is not itself the
+definition of platform completion.
+