@nimbus-sh/core 0.1.0 → 0.3.0

package/dist/runtime/runtime-manifest.d.ts

@@ -0,0 +1,86 @@
+/**
+ * runtime-manifest.ts — what an installed language runtime IS.
+ *
+ * A manifest names the files a runtime is made of, the shell commands it
+ * provides, and the runner that answers them. `nimbus install <name>` writes
+ * one into `~/.nimbus/runtimes/<name>/<version>/manifest.json`; every runner
+ * reads its own out of the session filesystem from there.
+ *
+ * The data contract only. Where the bytes come FROM is the publisher's
+ * problem, and the Cloudflare deployment's answer to it — an R2 bucket, a
+ * per-colo cache, and a digest chain rooted at a build-time pin — lives in
+ * `@nimbus-sh/worker`'s `runtime/runtime-catalog.ts`. A runtime that has been
+ * installed is the same runtime whichever tier fetched it, so nothing below
+ * this point knows there were tiers.
+ */
+import { z } from 'zod/v4';
+import { PYODIDE_PACKAGE_ABI } from './os-contracts.js';
+export interface ManifestFile {
+    /** VFS path relative to ~/.nimbus/runtimes/<name>/<version>/. */
+    path: string;
+    /** Publisher-side key for the content blob. */
+    content: string;
+    /** Hex sha256 of the content blob bytes. */
+    sha256: string;
+    /** Byte size. */
+    size: number;
+    /** Optional file mode hint ("exec" → registered as a shell bin). */
+    mode?: 'exec';
+}
+export interface ManifestEntrypoint {
+    /** Shell command name. */
+    binName: string;
+    /** Runner key (e.g. "clang-runner") — package manager dispatches to
+     *  the right runner factory by this. */
+    runner: string;
+    /** Default args prepended to user args at invocation. */
+    args: string[];
+    /** Optional secondary classification (e.g. "linker" for wasm-ld). */
+    kind?: string;
+}
+export interface RuntimeArtifactMetadata {
+    path: string;
+    kind: string;
+    id: string;
+    source_sha256?: string;
+    sha256: string;
+}
+export type RuntimePythonPackageAbi = typeof PYODIDE_PACKAGE_ABI;
+export interface RuntimePythonExtensionModuleMetadata {
+    /** Path inside Python site-packages, as stored in the wheel. */
+    path: string;
+    /** Path inside the installed Nimbus runtime root. */
+    runtimePath: string;
+    sha256: string;
+}
+export interface RuntimePythonPackageArtifactMetadata extends RuntimeArtifactMetadata {
+    kind: 'python-package';
+    language: 'python';
+    packageName: string;
+    version: string;
+    abi: RuntimePythonPackageAbi;
+    pyodideVersion: string;
+    pythonVersion: string;
+    wheelFileName: string;
+    wheelSha256: string;
+    loadMode: 'startup-module';
+    imports: string[];
+    dependencies: string[];
+    extensionModules: RuntimePythonExtensionModuleMetadata[];
+}
+export interface RuntimeManifest {
+    name: string;
+    version: string;
+    license: string;
+    /** Which WASI namespace the binaries import — `wasi_unstable` for
+     *  binji clang. `null` for non-WASI runtimes (e.g. Pyodide). */
+    wasi_namespace: string | null;
+    files: ManifestFile[];
+    entrypoints: ManifestEntrypoint[];
+    runtime_artifacts?: RuntimeArtifactMetadata[];
+}
+export declare const HexSha256Schema: z.ZodString;
+export declare const RuntimePythonPackageArtifactMetadataSchema: z.ZodType<RuntimePythonPackageArtifactMetadata>;
+export declare function parseRuntimeManifest(value: unknown): RuntimeManifest;
+export declare function isRuntimePythonPackageArtifactMetadata(artifact: RuntimeArtifactMetadata): artifact is RuntimePythonPackageArtifactMetadata;
+//# sourceMappingURL=runtime-manifest.d.ts.map

package/dist/runtime/runtime-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-manifest.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB;4CACwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,uBAAuB,GAAG,OAAO,mBAAmB,CAAC;AAEjE,MAAM,WAAW,oCAAoC;IACnD,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oCAAqC,SAAQ,uBAAuB;IACnF,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,uBAAuB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,gBAAgB,EAAE,oCAAoC,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;oEACgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,iBAAiB,CAAC,EAAE,uBAAuB,EAAE,CAAC;CAC/C;AAED,eAAO,MAAM,eAAe,aAAqC,CAAC;AAyBlE,eAAO,MAAM,0CAA0C,EAAE,CAAC,CAAC,OAAO,CAAC,oCAAoC,CAmBlG,CAAC;AAYN,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAEpE;AAED,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,uBAAuB,GAChC,QAAQ,IAAI,oCAAoC,CAElD"}

package/dist/runtime/runtime-manifest.js

@@ -0,0 +1,72 @@
+/**
+ * runtime-manifest.ts — what an installed language runtime IS.
+ *
+ * A manifest names the files a runtime is made of, the shell commands it
+ * provides, and the runner that answers them. `nimbus install <name>` writes
+ * one into `~/.nimbus/runtimes/<name>/<version>/manifest.json`; every runner
+ * reads its own out of the session filesystem from there.
+ *
+ * The data contract only. Where the bytes come FROM is the publisher's
+ * problem, and the Cloudflare deployment's answer to it — an R2 bucket, a
+ * per-colo cache, and a digest chain rooted at a build-time pin — lives in
+ * `@nimbus-sh/worker`'s `runtime/runtime-catalog.ts`. A runtime that has been
+ * installed is the same runtime whichever tier fetched it, so nothing below
+ * this point knows there were tiers.
+ */
+import { z } from 'zod/v4';
+import { PYODIDE_PACKAGE_ABI } from './os-contracts.js';
+export const HexSha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const ManifestFileSchema = z.object({
+    path: z.string().min(1),
+    content: z.string().min(1),
+    sha256: HexSha256Schema,
+    size: z.number().int().nonnegative(),
+    mode: z.literal('exec').optional(),
+});
+const ManifestEntrypointSchema = z.object({
+    binName: z.string().min(1),
+    runner: z.string().min(1),
+    args: z.array(z.string()),
+    kind: z.string().optional(),
+});
+const RuntimeArtifactMetadataSchema = z.object({
+    path: z.string().min(1),
+    kind: z.string().min(1),
+    id: z.string().min(1),
+    source_sha256: HexSha256Schema.optional(),
+    sha256: HexSha256Schema,
+}).passthrough();
+export const RuntimePythonPackageArtifactMetadataSchema = RuntimeArtifactMetadataSchema.and(z.object({
+    kind: z.literal('python-package'),
+    language: z.literal('python'),
+    packageName: z.string().min(1),
+    version: z.string().min(1),
+    abi: z.literal(PYODIDE_PACKAGE_ABI),
+    pyodideVersion: z.string().min(1),
+    pythonVersion: z.string().min(1),
+    wheelFileName: z.string().min(1),
+    wheelSha256: HexSha256Schema,
+    loadMode: z.literal('startup-module'),
+    imports: z.array(z.string()),
+    dependencies: z.array(z.string()),
+    extensionModules: z.array(z.object({
+        path: z.string().min(1),
+        runtimePath: z.string().min(1),
+        sha256: HexSha256Schema,
+    })),
+}));
+const RuntimeManifestSchema = z.object({
+    name: z.string().min(1),
+    version: z.string().min(1),
+    license: z.string(),
+    wasi_namespace: z.string().nullable(),
+    files: z.array(ManifestFileSchema),
+    entrypoints: z.array(ManifestEntrypointSchema),
+    runtime_artifacts: z.array(RuntimeArtifactMetadataSchema).optional(),
+});
+export function parseRuntimeManifest(value) {
+    return RuntimeManifestSchema.parse(value);
+}
+export function isRuntimePythonPackageArtifactMetadata(artifact) {
+    return RuntimePythonPackageArtifactMetadataSchema.safeParse(artifact).success;
+}

package/dist/runtime/runtime-package.d.ts

@@ -0,0 +1,63 @@
+/**
+ * runtime-package.ts — a runtime that arrived with the code, rather than over
+ * the network.
+ *
+ * `nimbus install <name>` reads a catalog out of R2 and writes the result into
+ * `~/.nimbus/runtimes/<name>/<version>/`. That is the Cloudflare deployment's
+ * answer to "where do the bytes come from", and it needs a bucket, a binding
+ * and a colo cache. An embedder who ran `npm i @nimbus-sh/runtime-bash` has
+ * already answered the same question: the bytes are on disk beside their
+ * manifest, fetched and integrity-checked by npm before any of this ran.
+ *
+ * So this is the second publisher, not the second package manager. It writes
+ * the SAME tree at the SAME path from the SAME manifest — `installRoot()`,
+ * `parseRuntimeManifest()`, one file per `manifest.files` entry — so
+ * `listInstalledManifests` and `rehydrateInstalledRuntimes` cannot tell which
+ * one ran, and a workspace behaves identically either way.
+ *
+ * Trust: R2 is verified against a digest chain rooted in a build-time pin
+ * because `caches.default` is shared across tenants and R2 keys are not
+ * content-addressed. A runtime package's root of trust is npm's own tarball
+ * integrity, which the install already checked; from there the manifest's
+ * per-file digests are re-verified here for exactly the reason the R2 path
+ * verifies them — these blobs are interpreters, so bytes that reach the
+ * filesystem are bytes that execute.
+ */
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+import { type ManifestFile, type RuntimeManifest } from './runtime-manifest.js';
+/**
+ * An installed npm package holding one runtime.
+ *
+ * The published packages (`@nimbus-sh/runtime-bash`,
+ * `@nimbus-sh/runtime-cpython`) are the implementations; each is a manifest,
+ * the content-addressed blobs it names, and the eight lines of `node:fs` that
+ * read them. The port is here rather than in those packages because the
+ * FILESYSTEM is what a runtime is, and this is the half that knows it.
+ *
+ * `readBlob` takes the whole manifest entry rather than a bare key, mirroring
+ * `fetchBlob` in the Cloudflare catalog: a key and the digest that vouches for
+ * it never travel as separate arguments, so there is no call in which they can
+ * disagree.
+ */
+export interface RuntimePackage {
+    readonly manifest: RuntimeManifest;
+    readBlob(file: ManifestFile): Uint8Array | Promise<Uint8Array>;
+}
+export interface SeededRuntime {
+    readonly name: string;
+    readonly version: string;
+    /** VFS path of the install root, e.g. `home/user/.nimbus/runtimes/bash/5.2.37`. */
+    readonly root: string;
+    /** False when the runtime was already installed at `root` and nothing was written. */
+    readonly written: boolean;
+}
+/**
+ * Write a runtime package into the filesystem as an install.
+ *
+ * Idempotent on the same rule the package manager uses: a `manifest.json`
+ * already at the install root means the install completed, and the root
+ * carries the version, so a package upgrade lands beside its predecessor
+ * rather than half over it.
+ */
+export declare function seedRuntimePackage(vfs: CredentialedVfs, homeDir: string, runtimePackage: RuntimePackage): Promise<SeededRuntime>;
+//# sourceMappingURL=runtime-package.d.ts.map

package/dist/runtime/runtime-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-package.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,cAAc,GAC7B,OAAO,CAAC,aAAa,CAAC,CAsBxB"}

package/dist/runtime/runtime-package.js

@@ -0,0 +1,66 @@
+/**
+ * runtime-package.ts — a runtime that arrived with the code, rather than over
+ * the network.
+ *
+ * `nimbus install <name>` reads a catalog out of R2 and writes the result into
+ * `~/.nimbus/runtimes/<name>/<version>/`. That is the Cloudflare deployment's
+ * answer to "where do the bytes come from", and it needs a bucket, a binding
+ * and a colo cache. An embedder who ran `npm i @nimbus-sh/runtime-bash` has
+ * already answered the same question: the bytes are on disk beside their
+ * manifest, fetched and integrity-checked by npm before any of this ran.
+ *
+ * So this is the second publisher, not the second package manager. It writes
+ * the SAME tree at the SAME path from the SAME manifest — `installRoot()`,
+ * `parseRuntimeManifest()`, one file per `manifest.files` entry — so
+ * `listInstalledManifests` and `rehydrateInstalledRuntimes` cannot tell which
+ * one ran, and a workspace behaves identically either way.
+ *
+ * Trust: R2 is verified against a digest chain rooted in a build-time pin
+ * because `caches.default` is shared across tenants and R2 keys are not
+ * content-addressed. A runtime package's root of trust is npm's own tarball
+ * integrity, which the install already checked; from there the manifest's
+ * per-file digests are re-verified here for exactly the reason the R2 path
+ * verifies them — these blobs are interpreters, so bytes that reach the
+ * filesystem are bytes that execute.
+ */
+import { sha256Hex } from '../_shared/crypto.js';
+import { installRoot } from './installed-runtimes.js';
+import { parseRuntimeManifest, } from './runtime-manifest.js';
+/**
+ * Write a runtime package into the filesystem as an install.
+ *
+ * Idempotent on the same rule the package manager uses: a `manifest.json`
+ * already at the install root means the install completed, and the root
+ * carries the version, so a package upgrade lands beside its predecessor
+ * rather than half over it.
+ */
+export async function seedRuntimePackage(vfs, homeDir, runtimePackage) {
+    const manifest = parseRuntimeManifest(runtimePackage.manifest);
+    const root = installRoot(homeDir, manifest.name, manifest.version);
+    if (vfs.exists(`${root}/manifest.json`)) {
+        return { name: manifest.name, version: manifest.version, root, written: false };
+    }
+    vfs.mkdir(root, { recursive: true });
+    for (const file of manifest.files) {
+        const target = `${root}/${file.path}`;
+        const parent = target.slice(0, target.lastIndexOf('/'));
+        if (!vfs.exists(parent))
+            vfs.mkdir(parent, { recursive: true });
+        vfs.writeFile(target, await verifiedBlob(manifest, runtimePackage, file));
+    }
+    // Last, where the R2 installer writes it first: that one has `--reinstall`
+    // to force a redo, and this one has no verb at all, so a manifest sitting
+    // beside a half-written tree would report a broken runtime as installed for
+    // the life of the filesystem.
+    vfs.writeFile(`${root}/manifest.json`, JSON.stringify(manifest, null, 2));
+    return { name: manifest.name, version: manifest.version, root, written: true };
+}
+async function verifiedBlob(manifest, runtimePackage, file) {
+    const bytes = await runtimePackage.readBlob(file);
+    const actual = await sha256Hex(bytes);
+    if (actual !== file.sha256) {
+        throw new Error(`${manifest.name}@${manifest.version}: sha256 mismatch for ${file.path} — manifest expects `
+            + `${file.sha256}, ${file.content} holds ${actual}`);
+    }
+    return bytes;
+}

package/dist/runtime/runtime-registry.d.ts

@@ -0,0 +1,162 @@
+/**
+ * runtime-registry.ts — shared shell-command factory for runtime
+ * dispatchers (node, bun, and future native-WASM / Python / Ruby /
+ * AssemblyScript runtimes).
+ *
+ * Why this exists
+ * ───────────────
+ * `node` and `bun` shell-command handlers in src/session/init.ts
+ * shared ~85% of their code: argv parsing for --version / --help /
+ * -e / script-path, VFS lookup, shebang strip, esbuild transform for
+ * .ts/.tsx/.jsx, dispatch to the runner. The duplication had drifted
+ * — only `node` had the primitive #1 nodeFlagSpan fix
+ * (init.ts:233-243), only `node` had primitive-#2 binSpawn ctx
+ * propagation (init.ts:391-403), only `bun` had install / run
+ * subcommand routing.
+ *
+ * `buildRuntimeHandler` returns a single shell-handler function that
+ * encodes the shared contract. Per-runtime variation is supplied
+ * via the `RuntimeSpec` parameter:
+ *
+ *   - name + version + helpText
+ *   - run(): runner fn (runFresh / runBunScript / wasm-runner)
+ *   - subcommands: optional map of `<verb> → handler` for
+ *     bun-style `bun install`, `bun run` (node has none today)
+ *   - transform(): optional code rewriter (bun prepends BUN_SHIM_PREAMBLE)
+ *   - supportsBinSpawn: true for node (the .bin handler propagates
+ *     a callerPid); other runtimes use a plain spawn flow.
+ *
+ * Anti-requirements observed
+ * ──────────────────────────
+ *   - NO setTimeout / NO retry / NO defensive-catch added.
+ *   - NO behavioral change vs the pre-refactor handlers — every
+ *     runtime-specific quirk is preserved exactly.
+ *   - Per-runtime test parity: existing runtime-primitives probes
+ *     (#1 npx / #2 .bin) and runtime-pkg probes (G1-G4) MUST still
+ *     pass against the refactored handlers — the contract is
+ *     observable behaviour, not implementation shape.
+ */
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import { type VfsCred } from './os-contracts.js';
+import type { EsbuildService } from './esbuild-service.js';
+import { type FacetBundleProfile } from './bundle-profile.js';
+/**
+ * Result shape that runtime-registry expects from a runner. Mirrors
+ * the existing RunFreshResult / RunBunResult shapes — kept narrow so
+ * future runtimes don't have to plumb runtime-internal state.
+ */
+export interface RuntimeRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Options the handler passes to the runner. Mirrors RunFreshOpts.
+ */
+export interface RuntimeRunOpts {
+    argv: string[];
+    env: Record<string, string> | undefined;
+    cwd: string | undefined;
+    filename: string;
+    dirname: string;
+    command: string;
+    /** Primitive #1/G4 hooks. node-runner consumes these; other
+     *  runtimes ignore them safely. */
+    skipSpawn?: boolean;
+    callerPid?: number;
+    /** Capture stdout/stderr in the result instead of streaming to the
+     *  terminal supervisor. Used by child_process pipe semantics. */
+    captureOutput?: boolean;
+    forceLongRunning?: boolean;
+    attachedTty?: boolean;
+    bundleProfile?: FacetBundleProfile;
+    /** Invoking process credentials for credential-bound runtime snapshots. */
+    cred?: VfsCred;
+}
+/** The VFS surface script resolution needs. */
+export interface ScriptResolutionFs {
+    isFile(path: string): boolean;
+    readFileString(path: string): string;
+}
+/**
+ * Resolve a runtime target — `./cli.ts`, `sub/x`, `.`, or a bare name — to a
+ * canonical VFS key, or null when nothing runnable sits there.
+ *
+ * A directory never resolves to itself: it falls through to the index
+ * candidates, so `bun ./tools` finds `tools/index.js` the way real bun does
+ * rather than trying to read the directory as source.
+ */
+export declare function resolveRuntimeScriptPath(fs: ScriptResolutionFs, cwd: string, target: string, opts?: {
+    preferModuleField?: boolean;
+}): string | null;
+/**
+ * A subcommand handler. `runAsRuntime` re-enters the standard flow — flag
+ * span, script resolution, transform, exec — with a rewritten argv, as if
+ * the verb had never been typed. `bun run <file>` uses it to hand a path
+ * to the very same execution path `bun <file>` takes, rather than growing
+ * a second one.
+ */
+export type RuntimeSubcommand = (ctx: any, registry: ShellRegistry, runAsRuntime: (args: string[]) => Promise<number>) => Promise<number>;
+export interface RuntimeSpec {
+    /** Shell-command name: 'node' / 'bun' / 'wasm-runner' / 'python'. */
+    name: string;
+    /** Output of `<name> --version`. Includes the leading 'v' if the
+     *  runtime convention does (Node: 'v20.0.0'; Bun: '1.1.42'). */
+    version: string;
+    /** Multi-line help text for `<name> --help`. */
+    helpText: string;
+    /**
+     * Runner function. Closes over whatever substrate the runtime executes on —
+     * a FacetManager for node and bun, a {@link ./facet-host.js FacetHost} for
+     * wasm-runner — because this factory never inspects it. It used to travel
+     * through here as a first parameter, which is the only thing that tied the
+     * shared handler to a Durable Object.
+     */
+    run(code: string, opts: RuntimeRunOpts): Promise<RuntimeRunResult>;
+    /**
+     * Subcommand router. When the first positional arg is a key in
+     * this map, the handler is invoked instead of the standard
+     * script-execution flow. Used by `bun install`, `bun run <script>`.
+     */
+    subcommands?: Record<string, RuntimeSubcommand>;
+    /**
+     * When true, the runtime treats the args list as a binary file
+     * path (NOT a JS script). Used by `wasm-runner` — the args[0] is a
+     * .wasm path, args[1+] are the function name + integer args.
+     * The handler skips the read-and-transform-script flow and calls
+     * `run()` with a synthetic empty `code` — runtimes that set this
+     * flag implement the actual bytes-load inside their runner.
+     */
+    bypassesScriptRead?: boolean;
+    /**
+     * Primitive #1 / G4 — when true, the script-execution branch
+     * propagates `ctx.__nimbusBinSpawn` into RuntimeRunOpts. Only
+     * `node` enables this; bun's runFresh chain doesn't share PID
+     * state with the .bin handler today. Future runtimes set this
+     * iff they share the runFresh contract.
+     */
+    supportsBinSpawn?: boolean;
+}
+/**
+ * Minimal registry shape we depend on. Avoids importing the full vendored
+ * shell registry type tree when the runtime path only needs resolve().
+ */
+export interface ShellRegistry {
+    resolve(name: string): Promise<any> | any;
+}
+/**
+ * Build a shell-handler function for a runtime. The returned function
+ * is the value passed to `registry.register('<name>', handler)`.
+ *
+ * Captures `vfs`, `getEsbuild` (for lazy init) + the spec. The same factory is used for every runtime; the only
+ * runtime-specific code lives in `spec`.
+ */
+export declare function buildRuntimeHandler(spec: RuntimeSpec, ctx0: {
+    vfs: SqliteVFS;
+    /** Lazy esbuild initialiser. Called once per first .ts/.tsx/.jsx
+     *  invocation — the host owns the init lifecycle, including whether
+     *  the module is loaded eagerly or on this call. */
+    getEsbuild(): EsbuildService | Promise<EsbuildService>;
+    registry: ShellRegistry;
+}): (ctx: any) => Promise<number>;
+//# sourceMappingURL=runtime-registry.d.ts.map

package/dist/runtime/runtime-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/runtime-registry.ts"],"names":[],"mappings":"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"}