@octocodeai/octocode-engine 16.6.0 → 16.7.0

package/dist/lsp/manager.js

@@ -1,29 +1,57 @@
 import { LSPClient } from './client.js';
-import { getLanguageServerForFile } from './config.js';
-import { LspClientPool } from './lspClientPool.js';
-import { nativeBinding } from './native.js';
+import { getLanguageServerForFile, resolveServerForFile, } from './config.js';
+import { LspClientPool, serializeKey } from './lspClientPool.js';
+import { manifestInstallHint } from './serverManifest.js';
 import { resolveWorkspaceRootForFile } from './workspaceRoot.js';
 export async function isLanguageServerAvailable(filePath, workspaceRoot) {
-    const serverConfig = await getLanguageServerForFile(filePath, workspaceRoot ?? process.cwd());
-    if (!serverConfig)
-        return false;
-    return nativeBinding.isCommandAvailable(serverConfig.command);
+    const resolution = await resolveServerForFile(filePath, workspaceRoot ?? process.cwd());
+    return resolution != null && resolution.source !== 'unavailable';
 }
 export const LSP_UNAVAILABLE_HINT = 'No language server is available for this file, so no semantic results were returned. Install a matching language server or set the relevant OCTOCODE_*_SERVER_PATH environment variable. For a text-based search meanwhile, use localSearchCode.';
+export const TOOLCHAIN_SERVERS = [
+    {
+        server: 'gopls',
+        languageId: 'go',
+        hint: 'Install Go, then `go install golang.org/x/tools/gopls@latest` (gopls needs the Go toolchain at runtime).',
+    },
+    {
+        server: 'jdtls',
+        languageId: 'java',
+        hint: 'Install a JDK/JRE 21+ and Eclipse JDT LS (https://download.eclipse.org/jdtls/).',
+    },
+    {
+        server: 'sourcekit-lsp',
+        languageId: 'swift',
+        hint: 'Install Xcode or Xcode Command Line Tools (`xcode-select --install`); sourcekit-lsp ships at /usr/bin/sourcekit-lsp on macOS.',
+    },
+    {
+        server: 'csharp-ls',
+        languageId: 'csharp',
+        hint: 'Install .NET SDK, then `dotnet tool install -g csharp-ls` (adds csharp-ls to ~/.dotnet/tools).',
+    },
+];
+const TOOLCHAIN_INSTALL_HINTS = Object.fromEntries(TOOLCHAIN_SERVERS.map(t => [t.languageId, t.hint]));
+/** Honest, actionable guidance for a file whose server did not resolve. */
+export function unavailableHintFor(languageId, command) {
+    const toolchain = languageId ? TOOLCHAIN_INSTALL_HINTS[languageId] : undefined;
+    if (toolchain)
+        return toolchain;
+    const manifest = command ? manifestInstallHint(command) : null;
+    if (manifest)
+        return manifest;
+    return LSP_UNAVAILABLE_HINT;
+}
 const POOL_IDLE_TIMEOUT_MS = parseInt(process.env.OCTOCODE_LSP_POOL_IDLE_MS || '60000', 10);
 // Languages whose servers emit $/progress notifications and need waitForReady.
-// TypeScript, Python, C/C++, and data-format servers (JSON/YAML/TOML/HTML/CSS)
+// TypeScript, Python, C/C++, and data-format servers (JSON/YAML/HTML/CSS)
 // answer queries immediately after the LSP handshake — skipping waitForReady
 // avoids burning the 2-second SETTLE_MS window for them.
 const PROGRESS_LANGUAGES = new Set([
     'go',
     'rust',
     'java',
-    'kotlin',
-    'swift',
     'csharp',
-    'elixir',
-    'erlang',
+    'swift',
 ]);
 // Per-language upper bound for $/progress drain (ms).
 // These are ceilings — waitForReady returns as soon as the server goes idle.
@@ -31,20 +59,31 @@ const SERVER_READY_TIMEOUT_MS = {
     go: 15_000,
     rust: 60_000,
     java: 120_000,
-    kotlin: 60_000,
-    swift: 30_000,
     csharp: 30_000,
-    elixir: 30_000,
-    erlang: 30_000,
+    swift: 30_000,
 };
 const DEFAULT_READY_TIMEOUT_MS = 30_000;
 function readyTimeoutForLanguage(languageId) {
     return SERVER_READY_TIMEOUT_MS[languageId] ?? DEFAULT_READY_TIMEOUT_MS;
 }
+// Eliminates the double getLanguageServerForFile call that would otherwise
+// happen once in poolKeyForFile (to build the key) and again inside the factory
+// (to create the client). poolKeyForFile deposits the already-resolved config
+// here before calling sharedPool.acquire; the factory reads and clears it.
+//
+// The deposit is conditional: when sharedPool already has an entry or an
+// inflight promise for this key, acquire() returns the cached client or the
+// existing promise WITHOUT invoking the factory — so depositing again here
+// would never be read or cleared and would leak the entry forever. Key format
+// is the shared serializeKey from lspClientPool.ts.
+const _pendingConfigs = new Map();
 const sharedPool = new LspClientPool({
     idleTimeoutMs: POOL_IDLE_TIMEOUT_MS,
     factory: async (key) => {
-        const serverConfig = await getLanguageServerForFile(synthesizeFilePathForKey(key), key.workspaceRoot);
+        const cacheKey = serializeKey(key);
+        const serverConfig = _pendingConfigs.get(cacheKey) ??
+            (await getLanguageServerForFile(synthesizeFilePathForKey(key), key.workspaceRoot));
+        _pendingConfigs.delete(cacheKey);
         if (!serverConfig)
             return null;
         const client = new LSPClient(serverConfig);
@@ -96,20 +135,20 @@ export async function getLspStatus(input = {}) {
         };
     }
     const workspaceRoot = input.workspaceRoot ?? (await resolveWorkspaceRootForFile(input.filePath));
-    const serverConfig = await getLanguageServerForFile(input.filePath, workspaceRoot);
-    const languageId = serverConfig?.languageId;
-    const serverAvailable = serverConfig
-        ? nativeBinding.isCommandAvailable(serverConfig.command)
-        : false;
+    const resolution = await resolveServerForFile(input.filePath, workspaceRoot);
+    const languageId = resolution?.config.languageId;
+    const serverSource = resolution?.source ?? 'unavailable';
+    const serverAvailable = serverSource !== 'unavailable';
     return {
         ...base,
         filePath: input.filePath,
         workspaceRoot,
         languageId,
         serverAvailable,
+        serverSource,
         hints: serverAvailable
-            ? ['Language server appears available for this file.']
-            : [LSP_UNAVAILABLE_HINT],
+            ? [`Language server resolved for this file (source: ${serverSource}).`]
+            : [unavailableHintFor(languageId, resolution?.config.command)],
     };
 }
 export function pooledClientCount() {
@@ -122,10 +161,18 @@ async function poolKeyForFile(workspaceRoot, filePath) {
     const serverConfig = await getLanguageServerForFile(filePath, workspaceRoot);
     if (!serverConfig)
         return null;
-    return {
+    const key = {
         workspaceRoot,
         filePath,
         languageId: serverConfig.languageId ?? 'unknown',
         serverId: `${serverConfig.command} ${(serverConfig.args ?? []).join(' ')}`.trim(),
     };
+    const serialized = serializeKey(key);
+    // Only deposit when the pool will actually call the factory for this key.
+    // If there's already an entry or inflight, acquire() won't start a new factory
+    // run — so depositing here would permanently leak the entry.
+    if (!sharedPool.has(key)) {
+        _pendingConfigs.set(serialized, serverConfig);
+    }
+    return key;
 }

package/dist/lsp/native.d.ts

@@ -1,7 +1,8 @@
+import type { LspReadiness } from './types.js';
 export type NativeLspClientBinding = {
     start(): Promise<void>;
     stop(): Promise<void>;
-    waitForReady(timeoutMs?: number): Promise<void>;
+    waitForReady(timeoutMs?: number): Promise<LspReadiness | undefined>;
     hasCapability?(capability: string): boolean;
     getRecentStderr?(): string[];
     openDocument(filePath: string, content: string): Promise<void>;

package/dist/lsp/platform.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical `{os}-{arch}[-musl]` platform identifier, matching the npm
+ * native-addon convention (the same keys esbuild / swc / the engine's own
+ * optionalDependencies use): `darwin-arm64`, `darwin-x64`, `linux-x64`,
+ * `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`,
+ * `win32-arm64`. This is the key the server download manifest is keyed on.
+ */
+export type PlatformId = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64' | 'linux-x64-musl' | 'linux-arm64-musl' | 'win32-x64' | 'win32-arm64';
+/** True when the current Linux runtime links musl libc (Alpine etc.). */
+export declare function isMuslLinux(): boolean;
+/** Resolve (and cache) the canonical platform id for this machine. */
+export declare function detectPlatformId(): PlatformId;
+/**
+ * Executable file-name candidates for a bare command on this OS. On Windows a
+ * server may exist only as `gopls.exe` / `pyright.cmd`, so we expand against
+ * `PATHEXT`; on POSIX the bare name is the only candidate.
+ */
+export declare function executableNames(command: string): string[];
+/** First existing path among `dir/<name>` for every executable-name candidate. */
+export declare function firstExecutableIn(dir: string, command: string, join: (dir: string, name: string) => string): string | null;

package/dist/lsp/platform.js

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync } from 'node:fs';
+let cachedPlatformId;
+/** True when the current Linux runtime links musl libc (Alpine etc.). */
+export function isMuslLinux() {
+    if (process.platform !== 'linux')
+        return false;
+    // 1) Fastest, in-process: glibc runtime version is absent on musl.
+    try {
+        const report = process.report?.getReport();
+        if (report?.header) {
+            return report.header.glibcVersionRuntime == null;
+        }
+    }
+    catch {
+        // process.report unavailable — fall through to the loader probe.
+    }
+    // 2) Dynamic-loader probe: musl ships `/lib/ld-musl-*.so.1`.
+    try {
+        return readdirSync('/lib').some(name => name.startsWith('ld-musl-'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve (and cache) the canonical platform id for this machine. */
+export function detectPlatformId() {
+    if (cachedPlatformId)
+        return cachedPlatformId;
+    const arch = process.arch === 'x64' ? 'x64' : 'arm64';
+    if (process.platform === 'darwin') {
+        cachedPlatformId = `darwin-${arch}`;
+    }
+    else if (process.platform === 'win32') {
+        cachedPlatformId = `win32-${arch}`;
+    }
+    else {
+        const suffix = isMuslLinux() ? '-musl' : '';
+        cachedPlatformId = `linux-${arch}${suffix}`;
+    }
+    return cachedPlatformId;
+}
+/**
+ * Executable file-name candidates for a bare command on this OS. On Windows a
+ * server may exist only as `gopls.exe` / `pyright.cmd`, so we expand against
+ * `PATHEXT`; on POSIX the bare name is the only candidate.
+ */
+export function executableNames(command) {
+    if (process.platform !== 'win32')
+        return [command];
+    const pathext = (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM')
+        .split(';')
+        .map(ext => ext.trim().toLowerCase())
+        .filter(Boolean);
+    return [command, ...pathext.map(ext => `${command}${ext}`)];
+}
+/** First existing path among `dir/<name>` for every executable-name candidate. */
+export function firstExecutableIn(dir, command, join) {
+    for (const name of executableNames(command)) {
+        const candidate = join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}

package/dist/lsp/resolver.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { access, constants, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { nativeBinding } from './native.js';
 export class SymbolResolutionError extends Error {
@@ -7,7 +7,7 @@ export class SymbolResolutionError extends Error {
     reason;
     searchRadius;
     constructor(symbolName, lineHint, reason, searchRadius = 5) {
-        super(`Could not find symbol '${symbolName}' at or near line ${lineHint}. ${reason}`);
+        super(`Could not find symbol '${symbolName}' at or near line ${lineHint}.${reason ? ` ${reason}` : ''}`);
         this.symbolName = symbolName;
         this.lineHint = lineHint;
         this.reason = reason;
@@ -27,7 +27,13 @@ function normalizeResolvedSymbol(value) {
 function toSymbolResolutionError(error, fuzzy, searchRadius = 5) {
     if (error instanceof SymbolResolutionError)
         return error;
-    const reason = error instanceof Error ? error.message : String(error);
+    const raw = error instanceof Error ? error.message : String(error);
+    // The native resolver already emits the canonical "Could not find symbol …"
+    // sentence; strip it so the wrapper message doesn't repeat it.
+    const prefix = `Could not find symbol '${fuzzy.symbolName}' at or near line ${fuzzy.lineHint ?? 0}`;
+    const reason = raw.startsWith(prefix)
+        ? raw.slice(prefix.length).replace(/^[.\s]+/, '')
+        : raw;
     return new SymbolResolutionError(fuzzy.symbolName, fuzzy.lineHint ?? 0, reason, searchRadius);
 }
 export function resolveSymbolPosition(fileOrContent, fuzzyOrSymbolName, lineHint, orderHint) {
@@ -152,7 +158,7 @@ async function resolveLocalModulePath(importerPath, moduleSpecifier) {
     ];
     for (const candidate of candidates) {
         try {
-            await readFile(candidate, 'utf-8');
+            await access(candidate, constants.R_OK);
             return candidate;
         }
         catch {

package/dist/lsp/serverDiscovery.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Platformized language-server discovery.
+ *
+ * The native layer (`config.rs`) already resolves explicit overrides
+ * (`OCTOCODE_*_SERVER_PATH`, `.octocode/lsp-servers.json`) and anything on
+ * `PATH` via `which`. This module covers the gap that bites in production: a
+ * server IS installed, but in a per-ecosystem directory that a GUI-launched
+ * IDE's (or a bare `spawn`'s) impoverished `PATH` never sees — `~/.cargo/bin`,
+ * `~/go/bin`, `~/.local/bin`, the npm/pnpm global prefixes, the Neovim `mason`
+ * dir, the Homebrew prefix, version-manager shims, and the per-OS Windows
+ * shim dirs.
+ *
+ * ## Performance (CLI-critical)
+ *
+ * `lsp-server list` calls `discoverServer` for every known server with the
+ * same workspaceRoot, so cold-start cost matters. Three caches work together:
+ *
+ *   1. `_discoveryCache`     — result per `(command, workspaceRoot)`. After the
+ *      first call, every subsequent call for the same pair is O(1): zero fs ops.
+ *
+ *   2. `_existingEcoDirs`    — ecosystem dirs filtered to only those that
+ *      exist on disk. Computed once per process (or after `clearDiscoveryCache`).
+ *      Turns ~15 dirs × N servers into ~15 stats once + only real-dir probes.
+ *
+ *   3. `_projectLocalDirs`   — resolved project-local path lists per workspace
+ *      root (avoids re-walking the directory tree).
+ *
+ * Call `clearDiscoveryCache()` after installing a server mid-session.
+ *
+ * Search order (first hit wins): project-local → known ecosystem dirs →
+ * IDE-bundled extension servers. Returns an absolute path plus a provenance
+ * label, or `null` if nothing on the machine provides the command.
+ */
+export type DiscoverySource = 'project-local' | `ecosystem:${string}` | 'ide-bundled';
+export interface DiscoveredServer {
+    command: string;
+    source: DiscoverySource;
+}
+/**
+ * Invalidate all discovery caches. Call after programmatically installing a
+ * server (e.g. `provisionServer`) or in tests between scenarios.
+ */
+export declare function clearDiscoveryCache(): void;
+/**
+ * Locate `command` on this machine outside of `PATH`. `command` is the bare
+ * server name (e.g. `rust-analyzer`, `gopls`); absolute commands are returned
+ * by the caller before this is reached.
+ *
+ * Results are memoised for the process lifetime. Call `clearDiscoveryCache()`
+ * after installing a server mid-session.
+ */
+export declare function discoverServer(command: string, workspaceRoot: string): DiscoveredServer | null;
+/**
+ * Discover multiple servers in one call, sharing the ecosystem-dir pre-filter
+ * and project-local dir computation across all commands. Results are written
+ * into the shared cache, so subsequent `discoverServer` calls for the same
+ * `(command, workspaceRoot)` pair are O(1).
+ *
+ * Equivalent to calling `discoverServer` for each command individually, but
+ * avoids redundant work when the caller needs results for many commands against
+ * the same workspace (e.g. the `lsp-server list` CLI command).
+ */
+export declare function discoverServerBatch(commands: string[], workspaceRoot: string): Record<string, DiscoveredServer | null>;

package/dist/lsp/serverDiscovery.js

@@ -0,0 +1,226 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { detectIdeContext } from './ideContext.js';
+import { firstExecutableIn } from './platform.js';
+/** Per-command-per-workspace result. `undefined` = not yet looked up. */
+const _discoveryCache = new Map();
+/** Ecosystem dirs that actually exist; `null` = not yet computed. */
+let _existingEcoDirs = null;
+/** Project-local dir lists per resolved workspace root. */
+const _projectLocalDirs = new Map();
+/**
+ * Invalidate all discovery caches. Call after programmatically installing a
+ * server (e.g. `provisionServer`) or in tests between scenarios.
+ */
+export function clearDiscoveryCache() {
+    _discoveryCache.clear();
+    _existingEcoDirs = null;
+    _projectLocalDirs.clear();
+}
+const HOME = homedir();
+const join = path.join;
+function envPath(...segments) {
+    return join(...segments);
+}
+/**
+ * Every ecosystem `bin` directory worth probing on this OS, paired with a
+ * label for provenance. Computed from env vars + canonical defaults — no
+ * subprocess spawning, so it stays cheap to call per resolution.
+ */
+function ecosystemBinDirs() {
+    const env = process.env;
+    const out = [];
+    const add = (dir, label) => {
+        if (dir)
+            out.push({ dir, label });
+    };
+    if (process.platform === 'win32') {
+        const appData = env.APPDATA;
+        const localAppData = env.LOCALAPPDATA;
+        add(env.USERPROFILE && envPath(env.USERPROFILE, '.cargo', 'bin'), 'cargo');
+        add(env.USERPROFILE && envPath(env.USERPROFILE, 'go', 'bin'), 'go');
+        // Go Windows installer default: C:\Go\bin (distinct from %USERPROFILE%\go\bin)
+        add('C:\\Go\\bin', 'go');
+        // LLVM/clangd: official Windows installer defaults
+        add('C:\\Program Files\\LLVM\\bin', 'llvm');
+        add('C:\\Program Files (x86)\\LLVM\\bin', 'llvm');
+        // .NET global tools (csharp-ls, OmniSharp, etc.)
+        add(env.USERPROFILE && envPath(env.USERPROFILE, '.dotnet', 'tools'), 'dotnet');
+        add(appData && envPath(appData, 'npm'), 'npm-global');
+        add(localAppData && envPath(localAppData, 'pnpm'), 'pnpm');
+        add(env.USERPROFILE && envPath(env.USERPROFILE, 'scoop', 'shims'), 'scoop');
+        add(env.ProgramData && envPath(env.ProgramData, 'chocolatey', 'bin'), 'choco');
+        add(localAppData && envPath(localAppData, 'Microsoft', 'WinGet', 'Links'), 'winget');
+        add(localAppData && envPath(localAppData, 'nvim-data', 'mason', 'bin'), 'mason');
+        return out;
+    }
+    // Rust
+    add(envPath(HOME, '.cargo', 'bin'), 'cargo');
+    // Go
+    add(env.GOBIN, 'go');
+    add(env.GOPATH ? envPath(env.GOPATH, 'bin') : undefined, 'go');
+    add(envPath(HOME, 'go', 'bin'), 'go');
+    // Python user installs
+    add(envPath(HOME, '.local', 'bin'), 'python-user');
+    // Node global (env-driven prefixes + canonical defaults)
+    add(env.npm_config_prefix ? envPath(env.npm_config_prefix, 'bin') : undefined, 'npm-global');
+    add(env.PNPM_HOME, 'pnpm');
+    add(envPath(HOME, '.volta', 'bin'), 'volta');
+    add(envPath(HOME, '.asdf', 'shims'), 'asdf');
+    add(envPath(HOME, '.local', 'share', 'mise', 'shims'), 'mise');
+    // Neovim mason (high-value on dev machines)
+    add(envPath(HOME, '.local', 'share', 'nvim', 'mason', 'bin'), 'mason');
+    // Homebrew (Apple Silicon first — the #1 "installed but not found" cause)
+    add('/opt/homebrew/bin', 'homebrew');
+    add('/usr/local/bin', 'homebrew');
+    add('/home/linuxbrew/.linuxbrew/bin', 'homebrew');
+    // System binary dirs: clangd ships in /usr/bin on macOS (Xcode CLI tools) and
+    // on Linux distros that install it via the package manager. Check after homebrew
+    // so a homebrew-managed version takes precedence over the system one.
+    add('/usr/bin', 'system');
+    // macOS framework Python: ~/Library/Python/<X.Y>/bin
+    if (process.platform === 'darwin') {
+        add(envPath(HOME, 'Library', 'Python'), 'python-framework');
+    }
+    // .NET global tools (csharp-ls, OmniSharp, etc.)
+    add(envPath(HOME, '.dotnet', 'tools'), 'dotnet');
+    // Active virtualenv / conda
+    add(env.VIRTUAL_ENV ? envPath(env.VIRTUAL_ENV, 'bin') : undefined, 'venv');
+    add(env.CONDA_PREFIX ? envPath(env.CONDA_PREFIX, 'bin') : undefined, 'conda');
+    return out;
+}
+/**
+ * Ecosystem dirs that exist on this machine, cached for the process lifetime.
+ * Pre-filtering eliminates stat calls for non-existent dirs on every lookup —
+ * on a typical dev machine this shrinks the probe list from ~15 to ~5.
+ */
+function existingEcoDirs() {
+    if (!_existingEcoDirs) {
+        _existingEcoDirs = ecosystemBinDirs().filter(({ dir }) => existsSync(dir));
+    }
+    return _existingEcoDirs;
+}
+/** Project-local server dirs, walking up from the workspace root. */
+function buildProjectLocalDirs(workspaceRoot) {
+    const dirs = [];
+    let current = workspaceRoot; // already resolved by callers
+    for (;;) {
+        dirs.push(join(current, 'node_modules', '.bin'));
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    const venvBin = process.platform === 'win32' ? 'Scripts' : 'bin';
+    dirs.push(join(workspaceRoot, '.venv', venvBin));
+    if (process.env.VIRTUAL_ENV)
+        dirs.push(join(process.env.VIRTUAL_ENV, venvBin));
+    return dirs;
+}
+function cachedProjectLocalDirs(resolvedRoot) {
+    let dirs = _projectLocalDirs.get(resolvedRoot);
+    if (!dirs) {
+        dirs = buildProjectLocalDirs(resolvedRoot);
+        _projectLocalDirs.set(resolvedRoot, dirs);
+    }
+    return dirs;
+}
+/**
+ * VS Code (and fork) extension roots whose `<ext>/server/` dirs may hold a
+ * reusable server. Skipped unless we detect an IDE host.
+ */
+function ideExtensionRoots() {
+    const { isIde, host } = detectIdeContext();
+    if (!isIde)
+        return [];
+    const roots = {
+        vscode: join(HOME, '.vscode', 'extensions'),
+        cursor: join(HOME, '.cursor', 'extensions'),
+        windsurf: join(HOME, '.windsurf', 'extensions'),
+    };
+    const candidates = [roots[host], join(HOME, '.vscode-server', 'extensions')].filter((dir) => Boolean(dir));
+    return candidates.filter(existsSync);
+}
+function resolveCommand(command) {
+    return path.basename(command);
+}
+function resolveRoot(workspaceRoot) {
+    return path.resolve(workspaceRoot);
+}
+function cacheKey(command, resolvedRoot) {
+    return `${command}\0${resolvedRoot}`;
+}
+/**
+ * Core lookup — runs only on cache miss. Assumes `command` is a basename and
+ * `resolvedRoot` is an absolute path.
+ */
+function scan(command, resolvedRoot) {
+    if (!command)
+        return null;
+    // 1) Project-local — matches the project's pinned toolchain.
+    for (const dir of cachedProjectLocalDirs(resolvedRoot)) {
+        const hit = firstExecutableIn(dir, command, join);
+        if (hit)
+            return { command: hit, source: 'project-local' };
+    }
+    // 2) Known ecosystem dirs (pre-filtered to existing).
+    for (const { dir, label } of existingEcoDirs()) {
+        const hit = firstExecutableIn(dir, command, join);
+        if (hit)
+            return { command: hit, source: `ecosystem:${label}` };
+    }
+    // 3) IDE-bundled extension servers (only when hosted in an IDE).
+    for (const root of ideExtensionRoots()) {
+        if (existsSync(root)) {
+            // No safe generic launch — see LSP_GUIDE.md "IDE reuse".
+            break;
+        }
+    }
+    return null;
+}
+/**
+ * Locate `command` on this machine outside of `PATH`. `command` is the bare
+ * server name (e.g. `rust-analyzer`, `gopls`); absolute commands are returned
+ * by the caller before this is reached.
+ *
+ * Results are memoised for the process lifetime. Call `clearDiscoveryCache()`
+ * after installing a server mid-session.
+ */
+export function discoverServer(command, workspaceRoot) {
+    const base = resolveCommand(command);
+    const resolved = resolveRoot(workspaceRoot);
+    const key = cacheKey(base, resolved);
+    if (_discoveryCache.has(key)) {
+        return _discoveryCache.get(key) ?? null;
+    }
+    const result = scan(base, resolved);
+    _discoveryCache.set(key, result);
+    return result;
+}
+/**
+ * Discover multiple servers in one call, sharing the ecosystem-dir pre-filter
+ * and project-local dir computation across all commands. Results are written
+ * into the shared cache, so subsequent `discoverServer` calls for the same
+ * `(command, workspaceRoot)` pair are O(1).
+ *
+ * Equivalent to calling `discoverServer` for each command individually, but
+ * avoids redundant work when the caller needs results for many commands against
+ * the same workspace (e.g. the `lsp-server list` CLI command).
+ */
+export function discoverServerBatch(commands, workspaceRoot) {
+    const resolved = resolveRoot(workspaceRoot);
+    const results = {};
+    for (const command of commands) {
+        const base = resolveCommand(command);
+        const key = cacheKey(base, resolved);
+        if (_discoveryCache.has(key)) {
+            results[command] = _discoveryCache.get(key) ?? null;
+            continue;
+        }
+        const result = scan(base, resolved);
+        _discoveryCache.set(key, result);
+        results[command] = result;
+    }
+    return results;
+}

package/dist/lsp/serverManifest.d.ts

@@ -0,0 +1,71 @@
+import { type PlatformId } from './platform.js';
+/**
+ * Download manifest for portable, toolchain-free language servers (the
+ * AUTO-DOWNLOAD-OK class). `serverManifest.json` is the human-authored source;
+ * `serverManifestData.ts` mirrors it as a TS module so the compiled dist needs
+ * no JSON-copy step. This module is the typed loader + per-platform selector +
+ * managed-cache locator.
+ *
+ * Provisioning policy (see docs/context/LSP_GUIDE.md):
+ *   OCTOCODE_LSP_AUTO_INSTALL = prompt (default) | off | auto
+ * Live network download is gated and requires a pinned `sha256` per asset.
+ * Until SHAs are pinned the manifest still drives (a) honest detect-and-instruct
+ * guidance and (b) reuse of a server a user/CI has pre-populated into the
+ * managed cache `~/.octocode/lsp/<server>/<releaseTag>/<binName>`.
+ */
+export type ArchiveKind = 'none' | 'gz' | 'zip' | 'tar.gz' | 'tar.xz';
+export interface ManifestAsset {
+    url: string;
+    archive: ArchiveKind;
+    binName: string;
+    /** Path of the executable inside the archive (zip/tar); absent for gz/none. */
+    binPath?: string;
+    /** SHA-256 of the downloaded asset; download is refused while this is null. */
+    sha256: string | null;
+}
+export interface ManifestServer {
+    languageId: string;
+    repo: string;
+    releaseTag: string;
+    launchArgs?: string[];
+    downloadHost?: string;
+    platforms: Partial<Record<PlatformId, ManifestAsset>>;
+    unsupportedPlatforms?: Partial<Record<PlatformId, string>>;
+}
+export interface ManifestFile {
+    $comment?: string;
+    version: number;
+    servers: Record<string, ManifestServer>;
+}
+export type ProvisionMode = 'off' | 'prompt' | 'auto';
+/** The configured auto-install policy. Defaults to `prompt` when unset (asks before downloading). Set OCTOCODE_LSP_AUTO_INSTALL=off to disable all downloads, or =auto to skip the prompt. */
+export declare function provisionMode(env?: NodeJS.ProcessEnv): ProvisionMode;
+/** The manifest entry for a server, keyed by its bare command name. */
+export declare function manifestServer(serverName: string): ManifestServer | null;
+/** Every auto-downloadable server in the manifest (for `lsp-server list`). */
+export declare function listManifestServers(): Array<{
+    name: string;
+    languageId: string;
+    releaseTag: string;
+}>;
+/** Whether the manifest can, in principle, auto-provide this server. */
+export declare function isAutoDownloadable(serverName: string): boolean;
+/**
+ * Root of the managed server cache. Defaults to `~/.octocode/lsp` (consistent
+ * with the rest of octocode's home), overridable via `OCTOCODE_LSP_CACHE_DIR`
+ * for read-only/ephemeral sandbox HOMEs or to point at a pre-baked image path.
+ */
+export declare function managedCacheRoot(env?: NodeJS.ProcessEnv): string;
+/** Where a provisioned binary lives once installed/extracted. */
+export declare function cachedServerBinPath(serverName: string, platformId?: PlatformId): string | null;
+/**
+ * If a managed binary is already present AND verified in the cache (downloaded
+ * by a prior run, by CI, or pre-baked), return its absolute path. A binary is
+ * only trusted when its sibling `<binName>.ok` completion marker contains the
+ * current binary's SHA-256 and size. A half-written or tampered binary from an
+ * interrupted install has no matching marker and is ignored, so it never
+ * resolves as "installed". Read-only — always safe to call.
+ */
+export declare function resolveCachedServer(serverName: string, platformId?: PlatformId): string | null;
+/** Human-readable provisioning guidance for a server with no resolved binary. */
+export declare function manifestInstallHint(serverName: string): string | null;