feat: bare command PATH resolution via node_modules/.bin

Node runtime's tryResolve() now resolves bare commands (e.g. 'pi') by
checking node_modules/.bin on the host filesystem. Supports both pnpm
shell wrappers and npm/yarn direct Node.js scripts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

packages/nodejs/src/kernel-runtime.ts

@@ -8,7 +8,7 @@
  * or other mounted runtimes.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import * as fsPromises from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import type {
@@ -404,9 +404,56 @@ class NodeRuntimeDriver implements RuntimeDriver {
   tryResolve(command: string): boolean {
     // Handle .js/.mjs/.cjs file paths as node scripts
     if (/\.[cm]?js$/.test(command)) return true;
+    // Handle bare commands resolvable via node_modules/.bin
+    if (this._resolveBinCommand(command) !== null) return true;
     return false;
   }
 
+  /**
+   * Resolve a bare command name (e.g. 'pi') to a JS entry point via
+   * node_modules/.bin on the host filesystem. Returns the VFS path
+   * (e.g. '/root/node_modules/@pkg/dist/cli.js') or null if not found.
+   *
+   * Handles two formats:
+   * 1. pnpm shell wrappers: parse `"$basedir/<relative-path>.js"` from the script
+   * 2. npm/yarn symlinks or direct JS files: follow to the .js target
+   */
+  private _resolveBinCommand(command: string): string | null {
+    if (!this._moduleAccessCwd) return null;
+    const binPath = join(this._moduleAccessCwd, 'node_modules', '.bin', command);
+    try {
+      const content = readFileSync(binPath, 'utf-8');
+      // Direct Node.js script (#!/usr/bin/env node or #!/path/to/node)
+      if (/^#!.*\bnode\b/.test(content)) {
+        // The .bin file itself is a JS entry — resolve its real path
+        // in case it's a symlink (npm/yarn), then map to VFS path
+        const realPath = realpathSync(binPath);
+        const nmDir = join(this._moduleAccessCwd, 'node_modules');
+        if (realPath.startsWith(nmDir)) {
+          return '/root/node_modules/' + realPath.slice(nmDir.length + 1);
+        }
+        // Fallback: use the .bin path itself
+        return `/root/node_modules/.bin/${command}`;
+      }
+      // pnpm/yarn shell wrapper — extract JS path from: "$basedir/<path>.{js,mjs,cjs}"
+      const match = content.match(/"\$basedir\/([^"]+\.[cm]?js)"/);
+      if (match) {
+        // Resolve relative to node_modules/.bin/ on host
+        const resolved = resolve(
+          join(this._moduleAccessCwd, 'node_modules', '.bin'),
+          match[1],
+        );
+        const nmDir = join(this._moduleAccessCwd, 'node_modules');
+        if (resolved.startsWith(nmDir)) {
+          return '/root/node_modules/' + resolved.slice(nmDir.length + 1);
+        }
+      }
+    } catch {
+      // File doesn't exist or isn't readable
+    }
+    return null;
+  }
+
   spawn(command: string, args: string[], ctx: ProcessContext): DriverProcess {
     const kernel = this._kernel;
     if (!kernel) throw new Error('Node driver not initialized');
@@ -763,6 +810,12 @@ class NodeRuntimeDriver implements RuntimeDriver {
       return this._resolveNodeArgs([command, ...args], kernel);
     }
 
+    // Bare command — resolve from node_modules/.bin (e.g. 'pi' → '/root/node_modules/.../cli.js')
+    const binEntry = this._resolveBinCommand(command);
+    if (binEntry) {
+      return this._resolveNodeArgs([binEntry, ...args], kernel);
+    }
+
     // 'node' command — parse args to find code/script
     return this._resolveNodeArgs(args, kernel);
   }

packages/nodejs/test/kernel-runtime.test.ts

@@ -7,6 +7,9 @@
  */
 
 import { describe, it, expect, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { createNodeRuntime } from '../src/kernel-runtime.ts';
 import type { NodeRuntimeOptions } from '../src/kernel-runtime.ts';
 import { createKernel } from '@secure-exec/core';
@@ -766,4 +769,115 @@ describe('Node RuntimeDriver', () => {
       expect(output).toContain('STEP:3');
     });
   });
+
+  describe('bare command resolution from node_modules/.bin', () => {
+    let kernel: Kernel;
+    let tmpDir: string;
+
+    function createMockBinDir() {
+      tmpDir = join(tmpdir(), `se-bin-test-${Date.now()}`);
+      const binDir = join(tmpDir, 'node_modules', '.bin');
+      const pkgDir = join(tmpDir, 'node_modules', 'my-tool', 'dist');
+      mkdirSync(binDir, { recursive: true });
+      mkdirSync(pkgDir, { recursive: true });
+      // Create a real JS entry file
+      writeFileSync(
+        join(pkgDir, 'cli.js'),
+        'console.log("hello from bare command");',
+      );
+      // Create a pnpm-style shell wrapper in .bin
+      writeFileSync(
+        join(binDir, 'my-tool'),
+        [
+          '#!/bin/sh',
+          'basedir=$(dirname "$(echo "$0" | sed -e \'s,\\\\,/,g\')")',
+          'exec node  "$basedir/../my-tool/dist/cli.js" "$@"',
+        ].join('\n'),
+        { mode: 0o755 },
+      );
+      return tmpDir;
+    }
+
+    afterEach(async () => {
+      await kernel?.dispose();
+      if (tmpDir) {
+        try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+      }
+    });
+
+    it('tryResolve returns true for bare command in node_modules/.bin', () => {
+      createMockBinDir();
+      const driver = createNodeRuntime({ moduleAccessCwd: tmpDir });
+      expect(driver.tryResolve!('my-tool')).toBe(true);
+    });
+
+    it('tryResolve returns false for unknown bare command', () => {
+      createMockBinDir();
+      const driver = createNodeRuntime({ moduleAccessCwd: tmpDir });
+      expect(driver.tryResolve!('nonexistent-tool')).toBe(false);
+    });
+
+    it('tryResolve returns false when moduleAccessCwd is not set', () => {
+      const driver = createNodeRuntime();
+      expect(driver.tryResolve!('my-tool')).toBe(false);
+    });
+
+    it('bare command executes the resolved JS entry point', async () => {
+      createMockBinDir();
+      const vfs = new SimpleVFS();
+      kernel = createKernel({ filesystem: vfs as any });
+      await kernel.mount(createNodeRuntime({ moduleAccessCwd: tmpDir }));
+
+      const chunks: Uint8Array[] = [];
+      const proc = kernel.spawn('my-tool', [], {
+        onStdout: (data) => chunks.push(data),
+      });
+      const code = await proc.wait();
+      expect(code).toBe(0);
+
+      const output = chunks.map(c => new TextDecoder().decode(c)).join('');
+      expect(output).toContain('hello from bare command');
+    });
+
+    it('bare command runs successfully even when args are passed', async () => {
+      createMockBinDir();
+      const vfs = new SimpleVFS();
+      kernel = createKernel({ filesystem: vfs as any });
+      await kernel.mount(createNodeRuntime({ moduleAccessCwd: tmpDir }));
+
+      // Spawn with extra args — should not crash
+      const chunks: Uint8Array[] = [];
+      const proc = kernel.spawn('my-tool', ['--flag', 'value'], {
+        onStdout: (data) => chunks.push(data),
+      });
+      const code = await proc.wait();
+      expect(code).toBe(0);
+
+      const output = chunks.map(c => new TextDecoder().decode(c)).join('');
+      expect(output).toContain('hello from bare command');
+    });
+
+    it('handles direct node shebang scripts (npm/yarn symlink style)', async () => {
+      createMockBinDir();
+      // Replace the shell wrapper with a direct node script
+      writeFileSync(
+        join(tmpDir, 'node_modules', '.bin', 'my-tool'),
+        '#!/usr/bin/env node\nconsole.log("direct node script");',
+        { mode: 0o755 },
+      );
+      const vfs = new SimpleVFS();
+      kernel = createKernel({ filesystem: vfs as any });
+      await kernel.mount(createNodeRuntime({ moduleAccessCwd: tmpDir }));
+
+      const chunks: Uint8Array[] = [];
+      const proc = kernel.spawn('my-tool', [], {
+        onStdout: (data) => chunks.push(data),
+      });
+      const code = await proc.wait();
+      expect(code).toBe(0);
+
+      const output = chunks.map(c => new TextDecoder().decode(c)).join('');
+      expect(output).toContain('direct node script');
+    });
+  });
 });