@secure-exec/core 0.0.0-nathan-docs-sdk-expansion.c9c2e4e → 0.0.0-nathan-publish-sidecar-browser.8f8dad1

package/dist/node-runtime.d.ts

@@ -36,8 +36,10 @@ export interface NodeRuntimeCreateOptions {
     permissions?: Permissions;
     /**
      * Override the directory containing the WASM command binaries (the source of
-     * the guest `sh`). Defaults to the in-repo build output, or the
-     * `SECURE_EXEC_WASM_COMMANDS_DIR` environment variable when set.
+     * the guest `sh`). When unset, resolution falls back through the
+     * `SECURE_EXEC_WASM_COMMANDS_DIR` environment variable, the in-repo build
+     * output (developer checkouts), then the commands vendored into the installed
+     * `@secure-exec/core` package (published installs).
      */
     commandsDir?: string;
     /**
@@ -76,6 +78,38 @@ export interface NodeRuntimeCreateOptions {
      * ```
      */
     mounts?: HostDirectoryMount[];
+    /**
+     * Mount a host `node_modules` directory into the VM in one call so guest
+     * `import`/`require` resolve real, host-installed npm packages.
+     *
+     * Pass the absolute host path to a `node_modules` directory (or an object
+     * with that path and an explicit guest location). The whole directory is
+     * projected lazily, Docker-style, at a guest `node_modules` on the resolution
+     * path, so any package inside it resolves the way Node would over a real
+     * filesystem (ancestor `node_modules` walk, `exports`/conditions, symlinks).
+     * This is the ergonomic alternative to wiring up individual `mounts` entries
+     * per package.
+     *
+     * By default the directory is mounted at `/tmp/node_modules`, which is where
+     * the resolution walk for a program run by {@link NodeRuntime.exec} /
+     * {@link NodeRuntime.run} begins (each program is written under `/tmp`). Pass
+     * the object form with `guestPath` to mount it elsewhere on a different
+     * module's resolution path.
+     *
+     * ```ts
+     * const rt = await NodeRuntime.create({
+     *   nodeModules: "/abs/path/to/project/node_modules",
+     * });
+     * await rt.exec(`
+     *   import isNumber from "is-number";
+     *   console.log(isNumber(42));
+     * `);
+     * ```
+     *
+     * The host filesystem is never exposed beyond the mounted `node_modules`
+     * subtree. The mount is read-only.
+     */
+    nodeModules?: string | NodeModulesMount;
     /**
      * Host-side tools the guest can invoke as shell commands. Each entry is
      * registered as a named guest command; when the guest runs it, the
@@ -138,6 +172,21 @@ export interface HostDirectoryMount {
     /** Mount read-only (the default). Pass `false` to allow guest writes. */
     readOnly?: boolean;
 }
+/**
+ * Object form of the `nodeModules` create option: a host `node_modules`
+ * directory to project, optionally at an explicit guest path. The string form
+ * (`nodeModules: "/abs/node_modules"`) is shorthand for `{ hostPath }`.
+ */
+export interface NodeModulesMount {
+    /** Absolute host `node_modules` directory to project (read lazily). */
+    hostPath: string;
+    /**
+     * Absolute guest path to mount it at. Defaults to `/tmp/node_modules`, where
+     * the resolution walk for {@link NodeRuntime.exec} / {@link NodeRuntime.run}
+     * programs begins. Override to put it on a different module's resolution path.
+     */
+    guestPath?: string;
+}
 /** Result of {@link NodeRuntime.exec}. */
 export interface NodeRuntimeExecResult {
     stdout: string;

package/dist/node-runtime.js

@@ -17,17 +17,53 @@
  * isolation boundary — no host escapes, no real Node.js builtins for guest
  * work.
  */
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createInMemoryFileSystem, createKernel, createNodeRuntime, createWasmVmRuntime, NodeFileSystem, } from "./test-runtime.js";
-/** Repository root, used to locate the bundled WASM command binaries. */
+/** Repository root, used to locate the in-repo WASM command build output. */
 const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
 /**
- * Directory containing the WASM coreutils/shell command binaries that provide
- * the guest `sh` the kernel needs to drive `exec()`. Built from the in-repo
- * Rust command sources.
+ * In-repo build output for the WASM coreutils/shell command binaries, produced
+ * by the Rust command build (`make -C registry/native wasm`). Only present in a
+ * developer checkout; preferred when it exists so local edits are picked up
+ * without re-vendoring.
  */
-const DEFAULT_COMMANDS_DIR = path.join(REPO_ROOT, "registry/native/target/wasm32-wasip1/release/commands");
+const REPO_COMMANDS_DIR = path.join(REPO_ROOT, "registry/native/target/wasm32-wasip1/release/commands");
+/**
+ * Commands vendored into the published `@secure-exec/core` package by
+ * `scripts/copy-wasm-commands.mjs` (listed in `files` as `commands`). This is
+ * the directory a real `npm install secure-exec` resolves: from the compiled
+ * `dist/node-runtime.js` it sits at `<package>/commands`. This is the analogue
+ * of how the sidecar binary ships inside `@secure-exec/sidecar`.
+ */
+const BUNDLED_COMMANDS_DIR = fileURLToPath(new URL("../commands", import.meta.url));
+/**
+ * Resolve the directory holding the WASM command binaries (the source of the
+ * guest `sh` the kernel needs to spawn any process). Precedence:
+ *
+ *   1. explicit `commandsDir` option,
+ *   2. `SECURE_EXEC_WASM_COMMANDS_DIR` env var,
+ *   3. the in-repo build output (developer checkout), when present,
+ *   4. the commands vendored into the installed package (published installs).
+ *
+ * The in-repo path wins over the bundled copy so local development picks up
+ * freshly built commands without re-vendoring. A fresh `npm install` has no
+ * in-repo path, so it falls through to the bundled copy.
+ */
+function resolveCommandsDir(explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    const fromEnv = process.env.SECURE_EXEC_WASM_COMMANDS_DIR;
+    if (fromEnv) {
+        return fromEnv;
+    }
+    if (existsSync(REPO_COMMANDS_DIR)) {
+        return REPO_COMMANDS_DIR;
+    }
+    return BUNDLED_COMMANDS_DIR;
+}
 /**
  * Secure-by-default permission policy applied when the caller passes no
  * `permissions`. Outward-facing capabilities are denied: there is **no network
@@ -45,6 +81,8 @@ const DEFAULT_PERMISSIONS = {
     env: "allow",
     network: "deny",
 };
+/** Guest path a `nodeModules` mount is projected at by default. */
+const DEFAULT_NODE_MODULES_GUEST_PATH = "/tmp/node_modules";
 let nextProgramId = 0;
 /**
  * Ergonomic, batteries-included runtime for executing guest JavaScript.
@@ -65,9 +103,7 @@ export class NodeRuntime {
      * shell and Node runtimes, and waits for the VM to report ready.
      */
     static async create(options = {}) {
-        const commandsDir = options.commandsDir ??
-            process.env.SECURE_EXEC_WASM_COMMANDS_DIR ??
-            DEFAULT_COMMANDS_DIR;
+        const commandsDir = resolveCommandsDir(options.commandsDir);
         // Seed caller-provided files into the VM's in-memory filesystem before
         // boot so they are part of the root filesystem snapshot the guest sees
         // (e.g. projected npm packages or fixtures). The host filesystem is
@@ -81,7 +117,21 @@ export class NodeRuntime {
         // Project host directories into the VM, Docker-style. NodeFileSystem
         // reads lazily through the VFS so large trees never traverse the
         // protocol frame as a single blob.
-        const mounts = (options.mounts ?? []).map((mount) => ({
+        const hostMounts = [...(options.mounts ?? [])];
+        // The `nodeModules` helper is sugar over a single host directory mount:
+        // project the whole host `node_modules` at a guest `node_modules` on the
+        // resolution path so any package inside resolves like real Node would.
+        if (options.nodeModules !== undefined) {
+            const nodeModules = typeof options.nodeModules === "string"
+                ? { hostPath: options.nodeModules }
+                : options.nodeModules;
+            hostMounts.push({
+                guestPath: nodeModules.guestPath ?? DEFAULT_NODE_MODULES_GUEST_PATH,
+                hostPath: nodeModules.hostPath,
+                readOnly: true,
+            });
+        }
+        const mounts = hostMounts.map((mount) => ({
             path: mount.guestPath,
             fs: new NodeFileSystem({ root: mount.hostPath }),
             readOnly: mount.readOnly ?? true,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secure-exec/core",
-	"version": "0.0.0-nathan-docs-sdk-expansion.c9c2e4e",
+	"version": "0.0.0-nathan-publish-sidecar-browser.8f8dad1",
 	"type": "module",
 	"license": "Apache-2.0",
 	"main": "./dist/index.js",
@@ -8,6 +8,7 @@
 	"files": [
 		"dist",
 		"fixtures",
+		"commands",
 		"README.md"
 	],
 	"exports": {
@@ -178,12 +179,14 @@
 	"scripts": {
 		"build:protocol": "pnpm --dir ../build-tools build:protocol",
 		"build:vm-config": "cargo test -p secure-exec-vm-config --quiet",
+		"copy-commands": "node scripts/copy-wasm-commands.mjs",
 		"check-types": "pnpm run build:protocol && pnpm run build:vm-config && tsc --noEmit",
-		"build": "pnpm run build:protocol && pnpm run build:vm-config && tsc",
+		"build": "pnpm run build:protocol && pnpm run build:vm-config && tsc && pnpm run copy-commands",
+		"prepack": "node scripts/copy-wasm-commands.mjs --require",
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@secure-exec/sidecar": "0.0.0-nathan-docs-sdk-expansion.c9c2e4e",
+		"@secure-exec/sidecar": "0.0.0-nathan-publish-sidecar-browser.8f8dad1",
 		"@rivetkit/bare-ts": "^0.6.2"
 	},
 	"devDependencies": {