/** * Tool detection — AI-OS Phase 0. * * Detects which external AI tools (Claude Code, Cursor, Claude Desktop, …) * are installed on the user's machine. Returns a stable envelope * (`ToolDetectionResult` in @waggle/shared) consumed by: * * - the sidecar route GET /api/tools/detect (Phase 0) * - the launcher dock (Phase 2) * - the Mission Control inventory tile (Phase 4) * * Design notes: * * 1. All filesystem and exec calls are injected via `ToolDetectionDeps` * so tests run hermetically. The default implementations only * activate when the caller does not provide overrides (production * sidecar path). * 2. `pathFromEnv(name)` is a thin shim over PATH lookup. On POSIX it * resolves like `which`; on Windows like `where`. The shim takes * a logical name ('claude'), not a full path, so callers don't * need to know the per-platform extension (.cmd / .exe / none). * 3. Detector functions are pure (`(deps) => Promise`) * so they can be unit-tested individually and composed in parallel * by the orchestrator. */ import { access, constants } from 'node:fs/promises'; import { homedir, platform as osPlatform } from 'node:os'; import { posix as pathPosix, win32 as pathWin32 } from 'node:path'; import { execFile } from 'node:child_process'; import { promisify } from 'node:util'; /** * Platform-aware path join. The detection envelope's path strings * must reflect `deps.platform` (the *target* user's platform), not * the host's platform — otherwise tests that simulate macOS on a * Windows dev machine end up with mixed-separator paths. */ function joinForPlatform(platform: NodeJS.Platform, ...parts: string[]): string { return platform === 'win32' ? pathWin32.join(...parts) : pathPosix.join(...parts); } import { type DetectedTool, type ToolDetectionResult, type ToolManifest, } from '@waggle/shared'; import { resolveToolCommandInvocation } from './tool-command.js'; import { buildExternalProcessEnv } from './external-process-env.js'; import { getToolRegistry } from './tool-registry.js'; import type { ManifestLoaderDeps } from './tool-manifest-loader.js'; import { resolveShellEnv, resolvedShellPath, mergePathValue } from './shell-env.js'; const execFileAsync = promisify(execFile); const CODEX_WINDOWS_APPS_DIAGNOSTIC = 'Codex was found in WindowsApps, but Windows blocks command-line launch from that app alias. Install a PATH CLI build of Codex or launch Codex from Start, then refresh.'; const HERMES_WINDOWS_HEALTH_DIAGNOSTIC = 'Hermes is installed but failed its --version health check. Run "hermes doctor" or reinstall Hermes, then refresh.'; type WindowsAppExecutables = Readonly>; const EMPTY_WINDOWS_APP_EXECUTABLES: WindowsAppExecutables = {}; const WINDOWS_APPX_QUERY = [ "$ErrorActionPreference = 'Stop'", "$targets = @(@{ Id = 'claude-desktop'; Name = 'Claude' }, @{ Id = 'codex-desktop'; Name = 'OpenAI.Codex' })", '$result = @{}', 'foreach ($target in $targets) {', ' $paths = @()', ' Get-AppxPackage -Name $target.Name -ErrorAction SilentlyContinue | ForEach-Object {', ' $package = $_', ' $manifest = Get-AppxPackageManifest -Package $package.PackageFullName', ' foreach ($app in @($manifest.Package.Applications.Application)) {', ' $executable = [string]$app.Executable', ' if (-not [string]::IsNullOrWhiteSpace($executable)) {', ' $paths += [IO.Path]::GetFullPath((Join-Path $package.InstallLocation $executable))', ' }', ' }', ' }', ' $result[$target.Id] = @($paths)', '}', '$result | ConvertTo-Json -Compress -Depth 3', ].join('\n'); function isBlockedWindowsAppsCodexPath( id: string, platform: NodeJS.Platform, installedPath: string, ): boolean { if (id !== 'codex' || platform !== 'win32') return false; const normalized = installedPath.replace(/\//g, '\\').toLowerCase(); return ( normalized.includes('\\windowsapps\\openai.codex_') && ( normalized.endsWith('\\app\\resources\\codex.exe') || normalized.endsWith('\\app\\resources\\codex') ) ); } // ── Injectable deps ───────────────────────────────────────────────── export interface ToolDetectionDeps { /** Platform override (defaults to os.platform()). */ platform?: NodeJS.Platform; /** $HOME override (defaults to os.homedir()). */ home?: string; /** Environment override for platform-specific config roots. */ env?: NodeJS.ProcessEnv; /** Working directory override (defaults to process.cwd()). */ cwd?: string; /** * Existence probe. Returns true iff the given path exists and is * readable by the current process. Production implementation uses * `fs.access(p, F_OK)`. */ exists?: (p: string) => Promise; /** * Best-effort version reader. Spawns the binary with the given args * and returns trimmed stdout, or null on any failure (non-zero * exit, ENOENT, spawn error). The detector layers a fallback on * top — `null` here means "could not determine". */ execVersion?: (binary: string, args: string[]) => Promise; /** * PATH lookup shim. Given a logical binary name ('claude'), returns * the resolved absolute path or null. Production implementation uses * `where.exe` on win32 and `which` on POSIX. */ pathFromEnv?: (name: string) => string | Promise | null; /** * Registered Windows Store application executables, keyed by built-in tool * id. Injected so AppX discovery stays hermetic in tests. */ windowsAppExecutables?: () => WindowsAppExecutables | Promise; } // ── Default deps (production-only paths) ──────────────────────────── async function defaultExists(p: string): Promise { try { await access(p, constants.F_OK); return true; } catch { return false; } } export async function defaultExecVersion( binary: string, args: string[], ): Promise { try { const env = buildExternalProcessEnv(process.env); const invocation = resolveToolCommandInvocation( binary, args, process.platform, { env }, ); const { stdout } = await execFileAsync(invocation.binary, invocation.args, { timeout: 5000, env, // Don't allow shell expansion; binary paths must be literal. shell: false, windowsVerbatimArguments: invocation.windowsVerbatimArguments === true, }); const trimmed = stdout.trim(); return trimmed.length > 0 ? trimmed : null; } catch { return null; } } /** * Env for the `which`/`where` lookup. Fail closed to the non-secret external * process environment. On POSIX, merge the resolved login-shell * PATH (GUI-launched sidecars inherit a bare PATH) so `which claude` * can find CLIs installed behind shell-profile shims. */ export function pathLookupEnv( platform: NodeJS.Platform = process.platform, base: NodeJS.ProcessEnv = process.env, ): NodeJS.ProcessEnv { const env = buildExternalProcessEnv(base, {}, platform); if (platform === 'win32') return env; const shellPath = resolvedShellPath(); if (shellPath) env.PATH = mergePathValue(shellPath, env.PATH); return env; } function envValue(env: NodeJS.ProcessEnv, name: string): string | undefined { const match = Object.entries(env).find(([key]) => key.toUpperCase() === name); return match?.[1]; } export function pathLookupCommand( platform: NodeJS.Platform, env: NodeJS.ProcessEnv, ): string { if (platform !== 'win32') return 'which'; const windowsRoot = envValue(env, 'SYSTEMROOT') ?? envValue(env, 'WINDIR') ?? 'C:\\Windows'; return pathWin32.join(windowsRoot, 'System32', 'where.exe'); } export function pathLookupArgs( platform: NodeJS.Platform, name: string, ): string[] { // Windows `where.exe name` searches the current directory before PATH. The // $PATH: prefix confines lookup to PATH and prevents launch-cwd hijacks. return [platform === 'win32' ? `$PATH:${name}` : name]; } async function defaultPathFromEnv(name: string): Promise { const env = pathLookupEnv(process.platform); const cmd = pathLookupCommand(process.platform, env); try { const { stdout } = await execFileAsync(cmd, pathLookupArgs(process.platform, name), { timeout: 3000, shell: false, env, windowsHide: true, }); return selectPathLookupCandidate(stdout, process.platform); } catch { return null; } } async function defaultWindowsAppExecutables(): Promise { if (process.platform !== 'win32') return EMPTY_WINDOWS_APP_EXECUTABLES; const systemRoot = process.env.SystemRoot ?? process.env.WINDIR; if (!systemRoot) return EMPTY_WINDOWS_APP_EXECUTABLES; const powershell = pathWin32.join( systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe', ); try { const { stdout } = await execFileAsync( powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', WINDOWS_APPX_QUERY], { timeout: 5000, shell: false, windowsHide: true }, ); const parsed = JSON.parse(stdout) as unknown; if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { return EMPTY_WINDOWS_APP_EXECUTABLES; } const record = parsed as Record; const result: Record = {}; for (const id of ['claude-desktop', 'codex-desktop']) { const values = record[id]; result[id] = Array.isArray(values) ? values.filter( (value): value is string => typeof value === 'string' && pathWin32.isAbsolute(value), ) : []; } return result; } catch { return EMPTY_WINDOWS_APP_EXECUTABLES; } } export function selectPathLookupCandidate( stdout: string, platform: NodeJS.Platform = process.platform, ): string | null { const candidates = stdout .split(/\r?\n/) .map((line) => line.trim()) .filter((line) => line.length > 0); if (platform !== 'win32') return candidates[0] ?? null; return ( candidates.find((candidate) => /\.(?:exe|cmd|bat|com)$/i.test(candidate)) ?? candidates[0] ?? null ); } // ── Resolved deps (caller overrides + production defaults) ────────── interface ResolvedDeps { platform: NodeJS.Platform; home: string; env: NodeJS.ProcessEnv; cwd: string; exists: (p: string) => Promise; execVersion: (binary: string, args: string[]) => Promise; pathFromEnv: (name: string) => Promise; windowsAppExecutables: () => Promise; } function resolveDeps(opts: ToolDetectionDeps): ResolvedDeps { const pathFromEnvOpt = opts.pathFromEnv; let windowsAppExecutablesPromise: Promise | undefined; return { platform: opts.platform ?? osPlatform(), home: opts.home ?? homedir(), env: opts.env ?? process.env, cwd: opts.cwd ?? process.cwd(), exists: opts.exists ?? defaultExists, execVersion: opts.execVersion ?? defaultExecVersion, pathFromEnv: pathFromEnvOpt === undefined ? defaultPathFromEnv : async (name: string) => { const result = pathFromEnvOpt(name); return result instanceof Promise ? await result : result; }, windowsAppExecutables: () => { windowsAppExecutablesPromise ??= Promise.resolve() .then(() => opts.windowsAppExecutables?.() ?? defaultWindowsAppExecutables()) .catch(() => EMPTY_WINDOWS_APP_EXECUTABLES); return windowsAppExecutablesPromise; }, }; } // ── Platform roots ────────────────────────────────────────────────── function nonBlankEnv(deps: ResolvedDeps, name: string): string | null { const value = deps.env[name]?.trim(); return value ? value : null; } function localAppDataRoot(deps: ResolvedDeps): string { return nonBlankEnv(deps, 'LOCALAPPDATA') ?? joinForPlatform(deps.platform, deps.home, 'AppData', 'Local'); } function hermesHome(deps: ResolvedDeps): string { const configured = nonBlankEnv(deps, 'HERMES_HOME'); if (configured) { return deps.platform === 'win32' ? pathWin32.normalize(configured) : pathPosix.normalize(configured); } return deps.platform === 'win32' ? joinForPlatform(deps.platform, localAppDataRoot(deps), 'hermes') : joinForPlatform(deps.platform, deps.home, '.hermes'); } // ── Per-tool detectors ────────────────────────────────────────────── /** * Generic PATH-lookup detector for CLI-shaped tools. Mirrors the * claude-code detector but parameterised by binary name. Used by * codex, hermes, and openclaw — they all ship as CLIs reachable * via PATH (PATH installer or symlink). * * If --version exec fails the tool is still reported `installed` * with `diagnostic` set (some CLIs don't accept --version). */ async function detectByPath( id: string, binaryName: string, deps: ResolvedDeps, displayName: string, ): Promise { const base: DetectedTool = { id, displayName, installed: false, installedPath: null, version: null, }; const resolved = await deps.pathFromEnv(binaryName); if (!resolved) return base; if (!(await deps.exists(resolved))) return base; const versionRaw = await deps.execVersion(resolved, ['--version']); const blockedWindowsAppsCodex = versionRaw === null && isBlockedWindowsAppsCodexPath(id, deps.platform, resolved); return { ...base, installed: true, installedPath: resolved, version: versionRaw, launchable: blockedWindowsAppsCodex ? false : undefined, diagnostic: blockedWindowsAppsCodex ? CODEX_WINDOWS_APPS_DIAGNOSTIC : versionRaw ? undefined : '--version exec failed', }; } function hermesWindowsCandidatePaths(deps: ResolvedDeps): string[] { const base = hermesHome(deps); return [ joinForPlatform(deps.platform, base, 'bin', 'hermes.cmd'), joinForPlatform(deps.platform, base, 'hermes-agent', 'venv', 'Scripts', 'hermes.exe'), joinForPlatform(deps.platform, base, 'hermes-agent', 'venv', 'Scripts', 'hermes-agent.exe'), ]; } async function detectHealthyWindowsHermes( binaryName: string, deps: ResolvedDeps, displayName: string, ): Promise { const pathCandidate = await deps.pathFromEnv(binaryName); const candidates = [pathCandidate, ...hermesWindowsCandidatePaths(deps)] .filter((candidate): candidate is string => Boolean(candidate)); const uniqueCandidates = candidates.filter((candidate, index) => candidates.findIndex((value) => value.toLowerCase() === candidate.toLowerCase()) === index); let firstExisting: string | null = null; for (const candidate of uniqueCandidates) { if (!(await deps.exists(candidate))) continue; firstExisting ??= candidate; const version = await deps.execVersion(candidate, ['--version']); if (version) { return { id: 'hermes', displayName, installed: true, installedPath: candidate, version, }; } } return { id: 'hermes', displayName, installed: firstExisting !== null, installedPath: firstExisting, version: null, launchable: firstExisting ? false : undefined, diagnostic: firstExisting ? HERMES_WINDOWS_HEALTH_DIAGNOSTIC : undefined, }; } // ── Candidate-path helpers (per platform) ─────────────────────────── function cursorCandidatePaths(deps: ResolvedDeps): string[] { if (deps.platform === 'win32') { return [ joinForPlatform(deps.platform, deps.home, 'AppData', 'Local', 'Programs', 'cursor', 'Cursor.exe'), 'C:\\Program Files\\Cursor\\Cursor.exe', ]; } if (deps.platform === 'darwin') { return ['/Applications/Cursor.app/Contents/MacOS/Cursor']; } // Linux — AppImage is the common shape; users typically symlink. return [ joinForPlatform(deps.platform, deps.home, '.local', 'share', 'cursor', 'cursor'), '/usr/bin/cursor', '/usr/local/bin/cursor', ]; } async function claudeDesktopCandidatePaths(deps: ResolvedDeps): Promise { if (deps.platform === 'win32') { const registered = await deps.windowsAppExecutables(); return [ ...(registered['claude-desktop'] ?? []), joinForPlatform(deps.platform, deps.home, 'AppData', 'Local', 'AnthropicClaude', 'Claude.exe'), 'C:\\Program Files\\AnthropicClaude\\Claude.exe', ]; } if (deps.platform === 'darwin') { return ['/Applications/Claude.app/Contents/MacOS/Claude']; } // Linux — Anthropic does not ship an official Linux client at time // of writing (May 2026); we still surface the would-be path so a // user-installed AppImage at the expected location is detected. return [ joinForPlatform(deps.platform, deps.home, '.local', 'share', 'claude-desktop', 'claude'), '/usr/bin/claude-desktop', ]; } function hermesDesktopCandidatePaths(deps: ResolvedDeps): string[] { if (deps.platform === 'win32') { const localAppData = localAppDataRoot(deps); return [ joinForPlatform( deps.platform, hermesHome(deps), 'hermes-agent', 'apps', 'desktop', 'release', 'win-unpacked', 'Hermes.exe', ), joinForPlatform(deps.platform, localAppData, 'Programs', 'Hermes', 'Hermes.exe'), joinForPlatform(deps.platform, localAppData, 'Programs', 'hermes', 'Hermes.exe'), 'C:\\Program Files\\Hermes\\Hermes.exe', ]; } if (deps.platform === 'darwin') { return ['/Applications/Hermes.app/Contents/MacOS/Hermes']; } return [ joinForPlatform(deps.platform, deps.home, '.local', 'share', 'Hermes', 'Hermes'), '/opt/Hermes/Hermes', ]; } async function codexDesktopCandidatePaths(deps: ResolvedDeps): Promise { if (deps.platform === 'win32') { const registered = await deps.windowsAppExecutables(); const codexPath = await deps.pathFromEnv('codex'); const normalized = codexPath?.replace(/\//g, '\\') ?? ''; const storeDesktopPath = /\\WindowsApps\\OpenAI\.Codex_[^\\]+\\app\\resources\\codex(?:\.exe)?$/i.test(normalized) ? pathWin32.join(pathWin32.dirname(pathWin32.dirname(normalized)), 'ChatGPT.exe') : null; return [ ...(registered['codex-desktop'] ?? []), ...(storeDesktopPath ? [storeDesktopPath] : []), joinForPlatform(deps.platform, deps.home, 'AppData', 'Local', 'OpenAI', 'Codex.exe'), 'C:\\Program Files\\OpenAI\\Codex.exe', ]; } if (deps.platform === 'darwin') { return ['/Applications/Codex.app/Contents/MacOS/Codex']; } return [ joinForPlatform(deps.platform, deps.home, '.local', 'share', 'codex-desktop', 'codex'), '/usr/bin/codex-desktop', ]; } /** * Shared detector body for tools detected by candidate-path probing * (i.e. desktop apps that are NOT on the user's PATH). */ async function detectByCandidates( id: string, candidates: string[], deps: ResolvedDeps, withVersion: boolean, displayName: string, ): Promise { const base: DetectedTool = { id, displayName, installed: false, installedPath: null, version: null, }; for (const candidate of candidates) { if (await deps.exists(candidate)) { const versionRaw = withVersion ? await deps.execVersion(candidate, ['--version']) : null; return { ...base, installed: true, installedPath: candidate, version: versionRaw, diagnostic: withVersion && versionRaw === null ? '--version exec failed' : undefined, }; } } return base; } // ── Registry-driven detection ─────────────────────────────────────── /** * Built-in candidate-path resolvers (the escape hatch — GUI/desktop tools * whose paths are platform-branching code, not declarative data). Keyed by * built-in id; third-party adapters are PATH-only so never need an entry. */ const CANDIDATE_RESOLVERS: Record string[] | Promise> = { 'cursor': cursorCandidatePaths, 'claude-desktop': claudeDesktopCandidatePaths, 'codex-desktop': codexDesktopCandidatePaths, 'hermes-desktop': hermesDesktopCandidatePaths, }; function withManifestMetadata(tool: DetectedTool, manifest: ToolManifest): DetectedTool { return { ...tool, releaseStatus: manifest.releaseStatus, launchable: tool.launchable ?? manifest.launchable, builtin: manifest.builtin === true, acceptsInlinePrompt: Boolean(manifest.promptArgTemplate?.length), capabilities: manifest.capabilities, permissionModes: manifest.task?.permissionModes ?? [], }; } /** Detect one tool from its manifest: PATH lookup, or the candidate resolver. */ async function detectFromManifest(m: ToolManifest, deps: ResolvedDeps): Promise { if (m.detect.kind === 'path') { if (m.id === 'hermes' && deps.platform === 'win32') { return withManifestMetadata( await detectHealthyWindowsHermes(m.detect.binaryName, deps, m.displayName), m, ); } return withManifestMetadata( await detectByPath(m.id, m.detect.binaryName, deps, m.displayName), m, ); } const resolver = CANDIDATE_RESOLVERS[m.id]; const candidates = resolver ? await resolver(deps) : []; return withManifestMetadata( await detectByCandidates( m.id, candidates, deps, /* withVersion */ false, m.displayName, ), m, ); } /** * Run every registered tool's detector in parallel and assemble the envelope. * The registry = built-in manifests (source of truth in @waggle/shared) + * validated third-party adapters from ~/.waggle/adapters/*.json (#5). Order is * deterministic (registry order) so the UI doesn't shuffle between calls. */ export async function detectInstalledTools( opts: ToolDetectionDeps & { manifestLoader?: ManifestLoaderDeps } = {}, ): Promise { const deps = resolveDeps(opts); // POSIX GUI sidecars: wait for the login-shell PATH before the first lookup, // otherwise every probe runs against the bare PATH and misses shim-installed // CLIs (and callers cache that empty result). Cached after the first call. if (deps.platform !== 'win32') await resolveShellEnv(); const registry = getToolRegistry(opts.manifestLoader); const tools = await Promise.all(registry.map((m) => detectFromManifest(m, deps))); return { platform: deps.platform, detectedAt: new Date().toISOString(), tools, }; }