test: add CLI resolution tests for cursor-agent/agent detection

Extract CLI resolution logic into separate testable module:
- commandExists(): checks if CLI command is in PATH
- detectCursorCli(): auto-detects 'agent' vs 'cursor-agent'
- resolveCli(): maps provider names to actual CLI commands

23 unit tests covering:
- Command existence checking (cross-platform)
- Cursor CLI detection with caching
- CLI resolution for cursor, google->gemini mappings
- Integration scenarios for older/newer Cursor versions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: khaliqgant

packages/bridge/src/cli-resolution.test.ts

@@ -0,0 +1,225 @@
+/**
+ * Unit tests for CLI Resolution Utilities
+ *
+ * Tests the detection and resolution of CLI commands for different providers,
+ * particularly the Cursor CLI which has two names: 'agent' (newer) and 'cursor-agent' (older).
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { execSync } from 'node:child_process';
+import {
+  commandExists,
+  detectCursorCli,
+  resolveCli,
+  resetCursorCliCache,
+  CLI_COMMAND_MAP,
+} from './cli-resolution.js';
+
+// Mock child_process module
+vi.mock('node:child_process', () => ({
+  execSync: vi.fn(),
+}));
+
+const mockedExecSync = vi.mocked(execSync);
+
+describe('CLI Resolution', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resetCursorCliCache();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('commandExists', () => {
+    it('returns true when command exists', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+      expect(commandExists('agent')).toBe(true);
+      expect(mockedExecSync).toHaveBeenCalledWith('which agent', { stdio: 'ignore' });
+    });
+
+    it('returns false when command does not exist', () => {
+      mockedExecSync.mockImplementation(() => {
+        throw new Error('Command not found');
+      });
+      expect(commandExists('nonexistent-cmd')).toBe(false);
+    });
+
+    it('uses "where" on Windows', () => {
+      const originalPlatform = process.platform;
+      Object.defineProperty(process, 'platform', { value: 'win32' });
+
+      mockedExecSync.mockReturnValue(Buffer.from('C:\\Path\\agent.exe'));
+      commandExists('agent');
+      expect(mockedExecSync).toHaveBeenCalledWith('where agent', { stdio: 'ignore' });
+
+      Object.defineProperty(process, 'platform', { value: originalPlatform });
+    });
+  });
+
+  describe('detectCursorCli', () => {
+    it('returns "agent" when agent command exists', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+      expect(detectCursorCli()).toBe('agent');
+    });
+
+    it('returns "cursor-agent" when only cursor-agent exists', () => {
+      mockedExecSync.mockImplementation((cmd: string) => {
+        if (cmd === 'which agent') {
+          throw new Error('not found');
+        }
+        return Buffer.from('/usr/bin/cursor-agent');
+      });
+      expect(detectCursorCli()).toBe('cursor-agent');
+    });
+
+    it('returns null when neither command exists', () => {
+      mockedExecSync.mockImplementation(() => {
+        throw new Error('not found');
+      });
+      expect(detectCursorCli()).toBeNull();
+    });
+
+    it('caches the detected CLI', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+
+      // First call detects
+      expect(detectCursorCli()).toBe('agent');
+      expect(mockedExecSync).toHaveBeenCalledTimes(1);
+
+      // Second call uses cache
+      expect(detectCursorCli()).toBe('agent');
+      expect(mockedExecSync).toHaveBeenCalledTimes(1); // Still 1
+    });
+
+    it('cache can be reset', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+
+      detectCursorCli();
+      expect(mockedExecSync).toHaveBeenCalledTimes(1);
+
+      resetCursorCliCache();
+
+      detectCursorCli();
+      expect(mockedExecSync).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('resolveCli', () => {
+    it('resolves "cursor" to detected CLI (agent)', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+      expect(resolveCli('cursor')).toBe('agent');
+    });
+
+    it('resolves "cursor" to detected CLI (cursor-agent)', () => {
+      mockedExecSync.mockImplementation((cmd: string) => {
+        if (cmd === 'which agent') {
+          throw new Error('not found');
+        }
+        return Buffer.from('/usr/bin/cursor-agent');
+      });
+      expect(resolveCli('cursor')).toBe('cursor-agent');
+    });
+
+    it('resolves "cursor-agent" input to detected CLI', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+      expect(resolveCli('cursor-agent')).toBe('agent');
+    });
+
+    it('falls back to "agent" when cursor CLI not detected', () => {
+      mockedExecSync.mockImplementation(() => {
+        throw new Error('not found');
+      });
+      expect(resolveCli('cursor')).toBe('agent');
+    });
+
+    it('is case insensitive for cursor', () => {
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+      expect(resolveCli('CURSOR')).toBe('agent');
+      expect(resolveCli('Cursor')).toBe('agent');
+    });
+
+    it('resolves "google" to "gemini"', () => {
+      expect(resolveCli('google')).toBe('gemini');
+      expect(resolveCli('Google')).toBe('gemini');
+    });
+
+    it('returns other commands unchanged', () => {
+      expect(resolveCli('claude')).toBe('claude');
+      expect(resolveCli('codex')).toBe('codex');
+      expect(resolveCli('gemini')).toBe('gemini');
+      expect(resolveCli('opencode')).toBe('opencode');
+    });
+
+    it('preserves case for unknown commands', () => {
+      expect(resolveCli('MyCustomCli')).toBe('MyCustomCli');
+    });
+  });
+
+  describe('CLI_COMMAND_MAP', () => {
+    it('maps cursor to agent', () => {
+      expect(CLI_COMMAND_MAP['cursor']).toBe('agent');
+    });
+
+    it('maps cursor-agent to agent', () => {
+      expect(CLI_COMMAND_MAP['cursor-agent']).toBe('agent');
+    });
+
+    it('maps google to gemini', () => {
+      expect(CLI_COMMAND_MAP['google']).toBe('gemini');
+    });
+  });
+});
+
+describe('CLI Resolution Integration', () => {
+  describe('Cursor CLI scenarios', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+      resetCursorCliCache();
+    });
+
+    it('handles user with newer Cursor (agent available)', () => {
+      // User has Cursor v0.50+ with "agent" CLI
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+
+      const resolved = resolveCli('cursor');
+      expect(resolved).toBe('agent');
+    });
+
+    it('handles user with older Cursor (cursor-agent available)', () => {
+      // User has older Cursor with "cursor-agent" CLI
+      mockedExecSync.mockImplementation((cmd: string) => {
+        if (cmd === 'which agent') {
+          throw new Error('not found');
+        }
+        return Buffer.from('/usr/bin/cursor-agent');
+      });
+
+      const resolved = resolveCli('cursor');
+      expect(resolved).toBe('cursor-agent');
+    });
+
+    it('handles team spawn request with cursor CLI', () => {
+      // Lead agent spawns worker with "cursor" - should resolve to available CLI
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+
+      // Simulate spawn request parsing
+      const cli = 'cursor';
+      const cliParts = cli.split(' ');
+      const rawCommand = cliParts[0];
+      const resolved = resolveCli(rawCommand);
+
+      expect(resolved).toBe('agent');
+    });
+
+    it('handles explicit cursor-agent in spawn request', () => {
+      // User explicitly requests cursor-agent - should still check availability
+      mockedExecSync.mockReturnValue(Buffer.from('/usr/bin/agent'));
+
+      const resolved = resolveCli('cursor-agent');
+      // Even when asking for cursor-agent, if agent is available, use agent
+      expect(resolved).toBe('agent');
+    });
+  });
+});

packages/bridge/src/cli-resolution.ts

@@ -0,0 +1,100 @@
+/**
+ * CLI Resolution Utilities
+ *
+ * Handles mapping and detection of CLI commands for different providers.
+ * Cursor has two CLI names: 'agent' (newer) and 'cursor-agent' (older).
+ */
+
+import { execSync } from 'node:child_process';
+import { createLogger } from '@agent-relay/utils/logger';
+
+const log = createLogger('cli-resolution');
+
+/**
+ * Check if a command exists in PATH
+ */
+export function commandExists(cmd: string): boolean {
+  try {
+    const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+    execSync(`${whichCmd} ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Cache for detected Cursor CLI command
+let detectedCursorCli: string | null = null;
+
+/**
+ * Reset the Cursor CLI detection cache.
+ * Useful for testing.
+ */
+export function resetCursorCliCache(): void {
+  detectedCursorCli = null;
+}
+
+/**
+ * Detect which Cursor CLI command is available.
+ * Newer versions use 'agent', older versions use 'cursor-agent'.
+ * Returns null if neither is found.
+ */
+export function detectCursorCli(): string | null {
+  if (detectedCursorCli !== null) {
+    return detectedCursorCli;
+  }
+
+  // Try newer 'agent' command first
+  if (commandExists('agent')) {
+    detectedCursorCli = 'agent';
+    log.debug('Detected Cursor CLI: agent (newer version)');
+    return 'agent';
+  }
+
+  // Fall back to older 'cursor-agent' command
+  if (commandExists('cursor-agent')) {
+    detectedCursorCli = 'cursor-agent';
+    log.debug('Detected Cursor CLI: cursor-agent (older version)');
+    return 'cursor-agent';
+  }
+
+  log.debug('Cursor CLI not found (neither agent nor cursor-agent)');
+  return null;
+}
+
+/**
+ * Resolve CLI command for a provider.
+ * For cursor, detects whether 'agent' or 'cursor-agent' is available.
+ */
+export function resolveCli(rawCommand: string): string {
+  const cmdLower = rawCommand.toLowerCase();
+
+  // Handle cursor specially - detect which CLI is installed
+  if (cmdLower === 'cursor' || cmdLower === 'cursor-agent') {
+    const cursorCli = detectCursorCli();
+    if (cursorCli) {
+      return cursorCli;
+    }
+    // Fall back to 'agent' if detection fails (let it fail at spawn time)
+    return 'agent';
+  }
+
+  // Handle other mappings
+  if (cmdLower === 'google') {
+    return 'gemini';
+  }
+
+  // Return as-is for other commands
+  return rawCommand;
+}
+
+/**
+ * CLI command mapping for providers (kept for reference, resolveCli handles logic)
+ * Maps provider names to actual CLI command names
+ */
+export const CLI_COMMAND_MAP: Record<string, string> = {
+  cursor: 'agent', // Cursor CLI installs as 'agent' (newer versions)
+  'cursor-agent': 'agent', // Cursor CLI older name, also maps to 'agent'
+  google: 'gemini', // Google provider uses 'gemini' CLI
+  // Other providers use their name as the command (claude, codex, etc.)
+};

packages/bridge/src/index.ts

@@ -13,6 +13,15 @@ export {
   type ShadowCliSelection,
 } from './shadow-cli.js';
 
+// CLI resolution utilities
+export {
+  commandExists,
+  detectCursorCli,
+  resolveCli,
+  resetCursorCliCache,
+  CLI_COMMAND_MAP,
+} from './cli-resolution.js';
+
 // Agent spawner
 export {
   AgentSpawner,