agent-relay 2.1.0 → 2.1.1

package/packages/utils/src/relay-pty-path.ts

@@ -5,17 +5,34 @@
  * - packages/bridge/src/spawner.ts (AgentSpawner)
  * - packages/wrapper/src/relay-pty-orchestrator.ts (RelayPtyOrchestrator)
  *
- * The search order handles multiple installation scenarios:
- * 1. Development (local Rust build)
- * 2. Local npm install (node_modules/agent-relay)
- * 3. Global npm install via nvm
- * 4. System-wide installs (/usr/local/bin)
+ * Supports all installation scenarios:
+ * - npx agent-relay (no postinstall, uses platform-specific binary)
+ * - npm install -g agent-relay (nvm, volta, fnm, n, asdf, Homebrew, system)
+ * - npm install agent-relay (local project)
+ * - pnpm/yarn global
+ * - Development (monorepo with Rust builds)
+ * - Docker containers
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+/**
+ * Supported platforms and their binary names.
+ * Windows is not supported (relay-pty requires PTY which doesn't work on Windows).
+ */
+const SUPPORTED_PLATFORMS: Record<string, Record<string, string>> = {
+  darwin: {
+    arm64: 'relay-pty-darwin-arm64',
+    x64: 'relay-pty-darwin-x64',
+  },
+  linux: {
+    arm64: 'relay-pty-linux-arm64',
+    x64: 'relay-pty-linux-x64',
+  },
+};
+
 /**
  * Get the platform-specific binary name for the current system.
  * Returns null if the platform is not supported.
@@ -24,13 +41,29 @@ function getPlatformBinaryName(): string | null {
   const platform = os.platform();
   const arch = os.arch();
 
-  // Map to supported platforms
-  if (platform === 'darwin' && arch === 'arm64') return 'relay-pty-darwin-arm64';
-  if (platform === 'darwin' && arch === 'x64') return 'relay-pty-darwin-x64';
-  if (platform === 'linux' && arch === 'arm64') return 'relay-pty-linux-arm64';
-  if (platform === 'linux' && arch === 'x64') return 'relay-pty-linux-x64';
+  return SUPPORTED_PLATFORMS[platform]?.[arch] ?? null;
+}
 
-  return null;
+/**
+ * Check if the current platform is supported.
+ */
+export function isPlatformSupported(): boolean {
+  const platform = os.platform();
+  const arch = os.arch();
+  return SUPPORTED_PLATFORMS[platform]?.[arch] !== undefined;
+}
+
+/**
+ * Get a human-readable description of supported platforms.
+ */
+export function getSupportedPlatforms(): string {
+  const platforms: string[] = [];
+  for (const [os, archs] of Object.entries(SUPPORTED_PLATFORMS)) {
+    for (const arch of Object.keys(archs)) {
+      platforms.push(`${os}-${arch}`);
+    }
+  }
+  return platforms.join(', ');
 }
 
 /** Cached result of relay-pty binary check */
@@ -51,13 +84,8 @@ export function getLastSearchPaths(): string[] {
 /**
  * Find the relay-pty binary.
  *
- * Search order:
- * 1. RELAY_PTY_BINARY environment variable (explicit override)
- * 2. bin/relay-pty in package root (installed by postinstall)
- * 3. relay-pty/target/release/relay-pty (local Rust build)
- * 4. /usr/local/bin/relay-pty (global install)
- * 5. In node_modules when installed as dependency
- * 6. Global npm installs (nvm) - both scoped and root packages
+ * Search order prioritizes platform-specific binaries FIRST because npx doesn't run postinstall.
+ * This ensures `npx agent-relay up` works without requiring global installation.
  *
  * @param callerDirname - The __dirname of the calling module (needed to resolve relative paths)
  * @returns Path to relay-pty binary, or null if not found
@@ -65,99 +93,149 @@ export function getLastSearchPaths(): string[] {
 export function findRelayPtyBinary(callerDirname: string): string | null {
   // Check for explicit environment variable override first
   const envOverride = process.env.RELAY_PTY_BINARY;
-  if (envOverride && fs.existsSync(envOverride)) {
+  if (envOverride && isExecutable(envOverride)) {
     lastSearchPaths = [envOverride];
     return envOverride;
   }
-  // Determine the agent-relay package root
-  // This code runs from either:
-  // - packages/{package}/dist/ (development/workspace)
-  // - node_modules/@agent-relay/{package}/dist/ (npm install)
-  //
-  // We need to find the agent-relay package root where bin/relay-pty lives
-  let packageRoot: string;
-
-  // Check if we're inside node_modules/@agent-relay/*/
-  if (callerDirname.includes('node_modules/@agent-relay/')) {
-    // Go from node_modules/@agent-relay/{package}/dist/ to agent-relay/
-    // dist/ -> {package}/ -> @agent-relay/ -> node_modules/ -> agent-relay/
-    packageRoot = path.join(callerDirname, '..', '..', '..', '..');
-  } else if (callerDirname.includes('node_modules/agent-relay')) {
-    // Direct dependency: node_modules/agent-relay/packages/{package}/dist/
-    // dist/ -> {package}/ -> packages/ -> agent-relay/
-    packageRoot = path.join(callerDirname, '..', '..', '..');
-  } else {
-    // Development: packages/{package}/dist/ -> packages/ -> project root
-    packageRoot = path.join(callerDirname, '..', '..', '..');
+
+  // Get platform-specific binary name (critical for npx where postinstall doesn't run)
+  const platformBinary = getPlatformBinaryName();
+
+  // Normalize path separators for cross-platform regex matching
+  const normalizedCaller = callerDirname.replace(/\\/g, '/');
+
+  // Collect all possible package root locations
+  const packageRoots: string[] = [];
+
+  // Find node_modules root from caller path
+  // Matches: /path/to/node_modules/@agent-relay/bridge/dist/
+  // Or: /path/to/node_modules/agent-relay/dist/src/cli/
+  const scopedMatch = normalizedCaller.match(/^(.+?\/node_modules)\/@agent-relay\//);
+  const directMatch = normalizedCaller.match(/^(.+?\/node_modules\/agent-relay)/);
+
+  if (scopedMatch) {
+    // Running from @agent-relay/* package - binary is in sibling agent-relay package
+    packageRoots.push(path.join(scopedMatch[1], 'agent-relay'));
   }
 
-  // Find the node_modules root for global installs
-  // When running from node_modules/@agent-relay/dashboard/node_modules/@agent-relay/wrapper/dist/
-  // we need to look for agent-relay at node_modules/agent-relay
-  // Use non-greedy match (.+?) to get the FIRST node_modules, not the last
-  let nodeModulesRoot: string | null = null;
-  const nodeModulesMatch = callerDirname.match(/^(.+?\/node_modules)\/@agent-relay\//);
-  if (nodeModulesMatch) {
-    nodeModulesRoot = nodeModulesMatch[1];
+  if (directMatch) {
+    // Running from agent-relay package directly
+    packageRoots.push(directMatch[1]);
   }
 
-  // Get platform-specific binary name as fallback (in case postinstall didn't run)
-  const platformBinary = getPlatformBinaryName();
+  // Development: packages/{package}/dist/ -> project root
+  if (!normalizedCaller.includes('node_modules')) {
+    packageRoots.push(path.join(callerDirname, '..', '..', '..'));
+  }
 
-  const candidates = [
-    // Primary: installed by postinstall from platform-specific binary
-    path.join(packageRoot, 'bin', 'relay-pty'),
-    // Development: local Rust build
-    path.join(packageRoot, 'relay-pty', 'target', 'release', 'relay-pty'),
-    path.join(packageRoot, 'relay-pty', 'target', 'debug', 'relay-pty'),
-    // Local build in cwd (for development)
-    path.join(process.cwd(), 'relay-pty', 'target', 'release', 'relay-pty'),
-    // Docker container (CI tests)
-    '/app/bin/relay-pty',
-    // Installed globally
-    '/usr/local/bin/relay-pty',
-    // In node_modules (when installed as local dependency)
-    path.join(process.cwd(), 'node_modules', 'agent-relay', 'bin', 'relay-pty'),
-    // Global npm install (nvm) - root package
-    path.join(process.env.HOME || '', '.nvm', 'versions', 'node', process.version, 'lib', 'node_modules', 'agent-relay', 'bin', 'relay-pty'),
-  ];
-
-  // Add candidate for root agent-relay package when running from scoped @agent-relay/* packages
-  if (nodeModulesRoot) {
-    candidates.push(path.join(nodeModulesRoot, 'agent-relay', 'bin', 'relay-pty'));
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+
+  // npx cache locations - npm stores packages here when running via npx
+  if (home) {
+    const npxCacheBase = path.join(home, '.npm', '_npx');
+    if (fs.existsSync(npxCacheBase)) {
+      try {
+        const entries = fs.readdirSync(npxCacheBase);
+        for (const entry of entries) {
+          const npxPackage = path.join(npxCacheBase, entry, 'node_modules', 'agent-relay');
+          if (fs.existsSync(npxPackage)) {
+            packageRoots.push(npxPackage);
+          }
+        }
+      } catch {
+        // Ignore read errors
+      }
+    }
   }
 
-  // Try common global npm paths
-  if (process.env.HOME) {
-    // Homebrew npm (macOS)
-    candidates.push(path.join('/usr/local/lib/node_modules', 'agent-relay', 'bin', 'relay-pty'));
-    candidates.push(path.join('/opt/homebrew/lib/node_modules', 'agent-relay', 'bin', 'relay-pty'));
+  // Add cwd-based paths for local installs
+  packageRoots.push(path.join(process.cwd(), 'node_modules', 'agent-relay'));
+
+  // Global install locations - support ALL major Node version managers
+  if (home) {
+    // nvm (most common)
+    packageRoots.push(
+      path.join(home, '.nvm', 'versions', 'node', process.version, 'lib', 'node_modules', 'agent-relay')
+    );
+
+    // volta (increasingly popular)
+    packageRoots.push(
+      path.join(home, '.volta', 'tools', 'image', 'packages', 'agent-relay', 'lib', 'node_modules', 'agent-relay')
+    );
+
+    // fnm (fast Node manager)
+    packageRoots.push(
+      path.join(home, '.fnm', 'node-versions', process.version, 'installation', 'lib', 'node_modules', 'agent-relay')
+    );
+
+    // n (simple Node version manager)
+    packageRoots.push(
+      path.join(home, 'n', 'lib', 'node_modules', 'agent-relay')
+    );
+
+    // asdf (universal version manager)
+    packageRoots.push(
+      path.join(home, '.asdf', 'installs', 'nodejs', process.version.replace('v', ''), 'lib', 'node_modules', 'agent-relay')
+    );
+
     // pnpm global
-    candidates.push(path.join(process.env.HOME, '.local', 'share', 'pnpm', 'global', 'node_modules', 'agent-relay', 'bin', 'relay-pty'));
+    packageRoots.push(
+      path.join(home, '.local', 'share', 'pnpm', 'global', 'node_modules', 'agent-relay')
+    );
+
+    // yarn global (yarn 1.x)
+    packageRoots.push(
+      path.join(home, '.config', 'yarn', 'global', 'node_modules', 'agent-relay')
+    );
+
+    // yarn global (alternative location)
+    packageRoots.push(
+      path.join(home, '.yarn', 'global', 'node_modules', 'agent-relay')
+    );
   }
 
-  // FALLBACK: If postinstall didn't run, try platform-specific binaries directly
-  // This handles cases where better-sqlite3 rebuild failed and blocked postinstall.js
-  if (platformBinary) {
-    // Add platform-specific binary candidates for all the same locations
-    candidates.push(path.join(packageRoot, 'bin', platformBinary));
-    candidates.push(path.join(process.cwd(), 'node_modules', 'agent-relay', 'bin', platformBinary));
-    candidates.push(path.join(process.env.HOME || '', '.nvm', 'versions', 'node', process.version, 'lib', 'node_modules', 'agent-relay', 'bin', platformBinary));
-    if (nodeModulesRoot) {
-      candidates.push(path.join(nodeModulesRoot, 'agent-relay', 'bin', platformBinary));
-    }
-    if (process.env.HOME) {
-      candidates.push(path.join('/usr/local/lib/node_modules', 'agent-relay', 'bin', platformBinary));
-      candidates.push(path.join('/opt/homebrew/lib/node_modules', 'agent-relay', 'bin', platformBinary));
-      candidates.push(path.join(process.env.HOME, '.local', 'share', 'pnpm', 'global', 'node_modules', 'agent-relay', 'bin', platformBinary));
+  // Homebrew npm (macOS)
+  packageRoots.push('/usr/local/lib/node_modules/agent-relay');
+  packageRoots.push('/opt/homebrew/lib/node_modules/agent-relay');
+
+  // Linux system-wide npm
+  packageRoots.push('/usr/lib/node_modules/agent-relay');
+
+  // Build candidates list - PRIORITIZE platform-specific binaries
+  // This is critical for npx since postinstall doesn't run
+  const candidates: string[] = [];
+
+  for (const root of packageRoots) {
+    // Platform-specific binary FIRST (works without postinstall)
+    if (platformBinary) {
+      candidates.push(path.join(root, 'bin', platformBinary));
     }
+    // Generic binary (requires postinstall to have run)
+    candidates.push(path.join(root, 'bin', 'relay-pty'));
+  }
+
+  // Development: local Rust builds
+  const devRoot = normalizedCaller.includes('node_modules')
+    ? null
+    : path.join(callerDirname, '..', '..', '..');
+  if (devRoot) {
+    candidates.push(path.join(devRoot, 'relay-pty', 'target', 'release', 'relay-pty'));
+    candidates.push(path.join(devRoot, 'relay-pty', 'target', 'debug', 'relay-pty'));
   }
+  candidates.push(path.join(process.cwd(), 'relay-pty', 'target', 'release', 'relay-pty'));
+
+  // Docker container (CI tests)
+  candidates.push('/app/bin/relay-pty');
+
+  // System-wide installs
+  candidates.push('/usr/local/bin/relay-pty');
+  candidates.push('/usr/bin/relay-pty');
 
   // Store search paths for debugging
   lastSearchPaths = candidates;
 
   for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
+    if (isExecutable(candidate)) {
       return candidate;
     }
   }
@@ -165,6 +243,19 @@ export function findRelayPtyBinary(callerDirname: string): string | null {
   return null;
 }
 
+/**
+ * Check if a file exists and is executable.
+ */
+function isExecutable(filePath: string): boolean {
+  try {
+    fs.accessSync(filePath, fs.constants.X_OK);
+    return true;
+  } catch {
+    // File doesn't exist or isn't executable
+    return false;
+  }
+}
+
 /**
  * Check if relay-pty binary is available (cached).
  * Returns true if the binary exists, false otherwise.

package/packages/wrapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/wrapper",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "CLI agent wrappers for Agent Relay - tmux, pty integration",
   "type": "module",
   "main": "dist/index.js",
@@ -30,11 +30,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-relay/api-types": "2.1.0",
-    "@agent-relay/protocol": "2.1.0",
-    "@agent-relay/config": "2.1.0",
-    "@agent-relay/continuity": "2.1.0",
-    "@agent-relay/resiliency": "2.1.0",
+    "@agent-relay/api-types": "2.1.1",
+    "@agent-relay/protocol": "2.1.1",
+    "@agent-relay/config": "2.1.1",
+    "@agent-relay/continuity": "2.1.1",
+    "@agent-relay/resiliency": "2.1.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {