@nimbus-sh/core 0.1.0 → 0.2.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-registry.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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. */
+    getEsbuild(): 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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"}