# Optional developer tools and binary backends

This is an extension mechanism and two limited developer-tool adapters, not
universal Linux compatibility. The core has no new third-party dependencies,
paid endpoint, account requirement, or automatic downloads.

## Working developer tools

Install engines in the **host application**, then pass them to the adapters:

```sh
npm install sandboxedjs isomorphic-git @electric-sql/pglite
```

```js
import git from 'isomorphic-git';
import { PGlite } from '@electric-sql/pglite';
import { createContainer, createGitCommand, createSqlCommand } from 'sandboxedjs';

const box = await createContainer({ cwd: '/app' });
const db = new PGlite();
box.kernel.installCommand(createGitCommand(git));
box.kernel.installCommand(createSqlCommand(db));

await box.exec('git init');
await box.fs.writeFile('/app/hello.txt', 'hello');
await box.exec('git add hello.txt');
await box.exec('git commit -m first', {
  env: { GIT_AUTHOR_NAME: 'Your Name', GIT_AUTHOR_EMAIL: 'you@example.com' },
});
console.log(await box.exec('git log'));
console.log(await box.exec('sql -c "SELECT 42 AS answer"'));

// The application owns the database lifetime and persistence configuration.
await db.close();
box.dispose();
```

Git supports `init`, `add PATH...`, `commit -m MESSAGE`, `status`, and `log`.
These are local operations backed by isomorphic-git and the credential-aware
container filesystem. Clone, fetch, push, branches, checkout and full Git CLI
compatibility are not implemented. No CORS proxy is configured implicitly.

`sql -c SQL` and `sql -f FILE` print result rows as JSON. This is an embedded
SQL adapter, not `psql`, a PostgreSQL server, or a TCP endpoint for `pg` clients.
Database storage belongs to PGlite, separately from the container filesystem.
Use its persistence options in the host; container snapshots do not capture it.
The supplied database API does not provide hard query cancellation; a timeout
is not a transaction rollback. Do not share the same database across tenants.

Both adapters are trusted host integrations. This pass validated real Git
commits with isomorphic-git 1.42.2 and real SQL with PGlite 0.5.8 on Node,
not a browser UI. Their upstream engines
support browsers; host asset loading must still be configured and verified.

## Precompiled command packs

Packs live outside the core. A host can load their manifests and artifact bytes
from its own storage and call:

```js
import { installWasmCommands } from 'sandboxedjs';
installWasmCommands(box.kernel, [
  { name: 'my-tool', bytes: wasmBytes, sha256: trustedManifest.sha256 },
]);
await box.exec('my-tool --help');
```

Supply a wasm32-wasi command compatible with this runtime's WASI preview1 host.
Hashes detect changed artifact bytes; trust in the manifest comes from the host.
Names, collisions, hashes and Wasm validity are checked before commands are
installed. No network fetch, registry, package archive or license acceptance is
hidden in this API. WASI imports and behaviors still need compatibility checks;
valid Wasm alone does not prove that a command can execute here.

## ELF execution and fallback

The kernel now recognizes executable ELF files instead of treating them as
shell scripts. It consults `box.kernel.binaries` in this order:

1. `compatibility`: exact binary hashes mapped to tested ports.
2. `translation`: a supplied compiler producing compatible WASI commands.
3. `emulation`: a supplied emulator backend.

`createWasmCompatibilityBackend(id, entries)` registers mappings of
`{ elfSha256, wasm: { name, bytes, sha256 } }`. Matching content rather than a
command name prevents silently substituting a port for a different version.

`createTranslationBackend(translator, maxCacheBytes?)` wraps a compiler with a
32 MiB default in-memory LRU output cache. The compiler supplies `id`,
`supports(info)` and `translate(request, signal)`. Give it a versioned identity.
Return null only when the input is unsupported. Thrown errors are surfaced.
This wrapper **does not contain an ELF compiler**. Its checks use a fixture
translator, not a claim that native instructions were translated in the test.
Ordinary elfconv/Emscripten output cannot be assumed to match our WASI ABI.

An emulator implements `BinaryBackend`, with `tier: 'emulation'` and
`prepare(request, signal)`. Register it with `box.kernel.binaries.register()`;
the returned function unregisters it. `list()` reports installed providers.
An original experimental x86-64 translator and interpreter are now available
through `createOriginalX64Backends()`. They support a small freestanding subset;
see [Original engines](original-x64.md). No Linux image is shipped.

Preparation returns either `{ supported: false, reason }` or
`{ supported: true, program: { run(ctx) } }`. Preparation must not execute guest
code or modify guest files. Backends receive an AbortSignal and must honor it.
After `run()` starts, its exit code is final: retrying on another backend could
duplicate writes or other effects. A native program with no supported backend
exits 126 with a diagnostic. Hard interruption requires a backend worker; the
existing in-realm WASI runner cannot interrupt a tight compute loop.

## Package priorities

| Priority | Tools | Approach and current status |
| --- | --- | --- |
| 1 | Git | Optional isomorphic-git adapter; local subset implemented |
| 1 | PostgreSQL SQL | Optional PGlite adapter implemented; embedded SQL only |
| 2 | jq, ripgrep, SQLite CLI, diff/patch | Candidate separate WASI packs; not bundled or validated here |
| 3 | C/C++ compiler and build tools | Separate large toolchain pack; compilation and subprocess support need work |
| Later | Redis-compatible services | Evaluate a separate engine and exact protocol/command coverage |
| Separate project | Docker Engine | Requires Linux kernel facilities; not a small WASI shim |

Broad binary translation and emulation coverage remain substantive follow-up work.
Do not advertise arbitrary ELF, Docker, complete PostgreSQL service compatibility,
or WebContainer performance parity based on this extension layer.

## Cost and licensing

SandboxedJs remains MIT. Upstream PGlite and isomorphic-git publish permissive
licenses, but retain the notices and check the specific versions you distribute.
A compatibility layer does not remove a tool's license obligations or make
enterprise software free. Host-supplied packs let users choose their own tools
and licenses. Hosting, compilation and network services have real resource costs;
this API does not require a paid provider or promise free third-party hosting.