@cruxy/cli 0.18.0 → 0.20.0

package/dist/errors/constructors.d.ts

@@ -150,6 +150,36 @@ export declare function memorySecretRefused(kind: string): CruxyError;
 export declare function memoryUntrusted(root: string): CruxyError;
 /** A malformed memory entry was rejected (C.29) — excluded, never eval'd. */
 export declare function memoryInvalid(detail: string): CruxyError;
+/**
+ * The local usage store (`~/.cruxy/usage/runs.json`) is corrupt or unreadable
+ * (C.22). Never fatal: usage accounting is best-effort, so the read is SKIPPED
+ * and this is surfaced. The fix is always to reset the file — its only content
+ * is your own local usage history, so deleting it loses nothing but history.
+ */
+export declare function usageRead(path: string, reason: string, underlying?: unknown): CruxyError;
+/**
+ * No language server is available for a query: either no server is configured
+ * for the file's language, or the configured/default binary is not installed.
+ * THE CORE HONESTY RULE for C.12: this is a coded, actionable failure — it must
+ * NEVER collapse into an empty result, because "no server" would then read as
+ * "no references found". `installHint` carries the concrete next step.
+ */
+export declare function lspServerNotFound(language: string, reason: "no-spec" | "binary-missing", detail?: {
+    command?: string;
+    installHint?: string;
+}): CruxyError;
+/**
+ * A language server's `initialize` handshake or a single request exceeded its
+ * timeout. The process is killed (startup) or the request rejected (per-request)
+ * — cruxy never hangs waiting on an unresponsive server.
+ */
+export declare function lspTimeout(language: string, phase: "startup" | "request", timeoutMs: number): CruxyError;
+/**
+ * A language server crashed (its process exited unexpectedly) and could not be
+ * recovered — the single automatic restart also died. Distinct from a server
+ * that answered with zero results (that is an ordinary, non-error outcome).
+ */
+export declare function lspCrashed(language: string, detail?: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -647,6 +647,92 @@ export function memoryInvalid(detail) {
         ],
     });
 }
+// ── usage telemetry (exit 2) — C.22 ───────────────────────────────────────────
+/**
+ * The local usage store (`~/.cruxy/usage/runs.json`) is corrupt or unreadable
+ * (C.22). Never fatal: usage accounting is best-effort, so the read is SKIPPED
+ * and this is surfaced. The fix is always to reset the file — its only content
+ * is your own local usage history, so deleting it loses nothing but history.
+ */
+export function usageRead(path, reason, underlying) {
+    return new CruxyError({
+        code: ErrorCode.UsageRead,
+        title: "could not read the local usage store",
+        cause: reason,
+        nextSteps: [
+            `delete ${path} to reset it (it holds only your local usage history)`,
+        ],
+        underlying,
+        meta: { path },
+    });
+}
+// ── per-language LSP (exit 15) — C.12 ─────────────────────────────────────────
+/**
+ * No language server is available for a query: either no server is configured
+ * for the file's language, or the configured/default binary is not installed.
+ * THE CORE HONESTY RULE for C.12: this is a coded, actionable failure — it must
+ * NEVER collapse into an empty result, because "no server" would then read as
+ * "no references found". `installHint` carries the concrete next step.
+ */
+export function lspServerNotFound(language, reason, detail) {
+    const noSpec = reason === "no-spec";
+    return new CruxyError({
+        code: ErrorCode.LspServerNotFound,
+        title: noSpec
+            ? `no language server configured for "${language}"`
+            : `the "${language}" language server (${detail?.command ?? "?"}) is not installed`,
+        cause: noSpec
+            ? "this file's language has no entry in the default server table or `lsp.servers`"
+            : `\`${detail?.command ?? language}\` was not found on PATH`,
+        nextSteps: noSpec
+            ? [
+                `set a server command, e.g. \`cruxy config set lsp.servers.${language} "<command> --stdio"\``,
+            ]
+            : [
+                detail?.installHint ?? `install the ${language} language server`,
+                `or point cruxy at an installed one: \`cruxy config set lsp.servers.${language} "<command>"\``,
+            ],
+        meta: { language, reason, command: detail?.command },
+    });
+}
+/**
+ * A language server's `initialize` handshake or a single request exceeded its
+ * timeout. The process is killed (startup) or the request rejected (per-request)
+ * — cruxy never hangs waiting on an unresponsive server.
+ */
+export function lspTimeout(language, phase, timeoutMs) {
+    return new CruxyError({
+        code: ErrorCode.LspTimeout,
+        title: phase === "startup"
+            ? `the "${language}" language server did not start within ${timeoutMs}ms`
+            : `the "${language}" language server did not respond within ${timeoutMs}ms`,
+        cause: phase === "startup"
+            ? "the initialize handshake timed out; the process was killed"
+            : "the request timed out; the server was left running for later calls",
+        nextSteps: [
+            `raise the bound if the server is just slow to start: \`cruxy config set lsp.${phase === "startup" ? "startupTimeout" : "requestTimeout"} ${timeoutMs * 2}\``,
+            "re-run with --verbose to see the server's stderr",
+        ],
+        meta: { language, phase, timeoutMs },
+    });
+}
+/**
+ * A language server crashed (its process exited unexpectedly) and could not be
+ * recovered — the single automatic restart also died. Distinct from a server
+ * that answered with zero results (that is an ordinary, non-error outcome).
+ */
+export function lspCrashed(language, detail) {
+    return new CruxyError({
+        code: ErrorCode.LspCrashed,
+        title: `the "${language}" language server crashed`,
+        cause: detail ?? "the server process exited unexpectedly and did not recover",
+        nextSteps: [
+            "re-run with --verbose to see the server's stderr",
+            `verify the server runs standalone (the command in \`lsp.servers.${language}\` or the default)`,
+        ],
+        meta: { language },
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -80,6 +80,19 @@ export declare const ErrorCode: {
     /** A memory write was refused because the content matched a secret shape —
      * secrets are never persisted (defense in depth over C.17). */
     readonly MemorySecret: "CRUXY_E_MEMORY_SECRET";
+    /** The local usage store is corrupt/unreadable — the read is SKIPPED and this
+     * is surfaced; never fatal to a run (usage display is best-effort). */
+    readonly UsageRead: "CRUXY_E_USAGE_READ";
+    /** A language server binary is not installed / not on PATH (or no server is
+     * configured for the file's language). Actionable, NEVER a silent empty
+     * result — "no server" must not read as "no references found". */
+    readonly LspServerNotFound: "CRUXY_E_LSP_SERVER_NOT_FOUND";
+    /** A server's `initialize` handshake or a single request exceeded its timeout
+     * — the process was killed / the request errored, never left to hang. */
+    readonly LspTimeout: "CRUXY_E_LSP_TIMEOUT";
+    /** A language server crashed (and, where applicable, a single restart also
+     * failed). Distinct from "server returned no results". */
+    readonly LspCrashed: "CRUXY_E_LSP_CRASHED";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -95,6 +95,21 @@ export const ErrorCode = {
     /** A memory write was refused because the content matched a secret shape —
      * secrets are never persisted (defense in depth over C.17). */
     MemorySecret: "CRUXY_E_MEMORY_SECRET",
+    // usage telemetry (exit 2) — C.22
+    /** The local usage store is corrupt/unreadable — the read is SKIPPED and this
+     * is surfaced; never fatal to a run (usage display is best-effort). */
+    UsageRead: "CRUXY_E_USAGE_READ",
+    // per-language LSP (exit 15) — C.12
+    /** A language server binary is not installed / not on PATH (or no server is
+     * configured for the file's language). Actionable, NEVER a silent empty
+     * result — "no server" must not read as "no references found". */
+    LspServerNotFound: "CRUXY_E_LSP_SERVER_NOT_FOUND",
+    /** A server's `initialize` handshake or a single request exceeded its timeout
+     * — the process was killed / the request errored, never left to hang. */
+    LspTimeout: "CRUXY_E_LSP_TIMEOUT",
+    /** A language server crashed (and, where applicable, a single restart also
+     * failed). Distinct from "server returned no results". */
+    LspCrashed: "CRUXY_E_LSP_CRASHED",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -162,6 +177,16 @@ const EXIT_CODES = {
     [ErrorCode.MemoryInvalid]: 14,
     [ErrorCode.MemoryUntrusted]: 14,
     [ErrorCode.MemorySecret]: 14,
+    // Usage telemetry (C.22). A corrupt store is a usage/data problem the user can
+    // fix (delete the file); it shares the usage exit code and is never fatal to a
+    // run — the aggregation just skips it.
+    [ErrorCode.UsageRead]: 2,
+    // Per-language LSP (C.12). A missing server / timeout / crash surfaces inside
+    // a tool result (the agent reads and reroutes) and only exits the process if
+    // thrown directly; grouped for a greppable exit code.
+    [ErrorCode.LspServerNotFound]: 15,
+    [ErrorCode.LspTimeout]: 15,
+    [ErrorCode.LspCrashed]: 15,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/lsp/client.d.ts

@@ -0,0 +1,25 @@
+import type { LspPool } from "./pool.js";
+import type { LspDiagnostic, LspHover, LspLocation } from "./types.js";
+/**
+ * Typed, normalized LSP queries over a {@link LspPool} (C.12). Its only real
+ * job beyond delegating is the availability discipline: it resolves a file's
+ * language and acquires a server, letting the pool's coded errors (no server /
+ * timeout / crash) propagate — while a server's genuine `[]`/`null` answer flows
+ * back untouched. That keeps "couldn't ask" and "asked, nothing found" distinct
+ * all the way up to the tool boundary. Callers pass ABSOLUTE, in-root paths
+ * (validated by the tool via `resolveInRoot`); the server relativizes results.
+ */
+export declare class LspClient {
+    private readonly pool;
+    constructor(pool: LspPool);
+    definition(file: string, line: number, col: number): Promise<LspLocation[]>;
+    references(file: string, line: number, col: number): Promise<LspLocation[]>;
+    hover(file: string, line: number, col: number): Promise<LspHover | null>;
+    diagnostics(file: string): Promise<LspDiagnostic[]>;
+    /**
+     * Resolve the file's language and hand back a live server. An unmapped
+     * extension is a coded, actionable failure (`no-spec`) — NOT an empty result,
+     * so "unknown language" can never read as "no references found".
+     */
+    private serverFor;
+}

package/dist/lsp/client.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { lspServerNotFound } from "../errors/index.js";
+import { languageForFile } from "./registry.js";
+/**
+ * Typed, normalized LSP queries over a {@link LspPool} (C.12). Its only real
+ * job beyond delegating is the availability discipline: it resolves a file's
+ * language and acquires a server, letting the pool's coded errors (no server /
+ * timeout / crash) propagate — while a server's genuine `[]`/`null` answer flows
+ * back untouched. That keeps "couldn't ask" and "asked, nothing found" distinct
+ * all the way up to the tool boundary. Callers pass ABSOLUTE, in-root paths
+ * (validated by the tool via `resolveInRoot`); the server relativizes results.
+ */
+export class LspClient {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async definition(file, line, col) {
+        return (await this.serverFor(file)).definition(file, line, col);
+    }
+    async references(file, line, col) {
+        return (await this.serverFor(file)).references(file, line, col);
+    }
+    async hover(file, line, col) {
+        return (await this.serverFor(file)).hover(file, line, col);
+    }
+    async diagnostics(file) {
+        return (await this.serverFor(file)).diagnostics(file);
+    }
+    /**
+     * Resolve the file's language and hand back a live server. An unmapped
+     * extension is a coded, actionable failure (`no-spec`) — NOT an empty result,
+     * so "unknown language" can never read as "no references found".
+     */
+    serverFor(file) {
+        const language = languageForFile(file);
+        if (!language) {
+            const ext = path.extname(file) || path.basename(file);
+            throw lspServerNotFound(ext, "no-spec");
+        }
+        return this.pool.acquire(language);
+    }
+}

package/dist/lsp/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { DEFAULT_SPECS, EXT_TO_LANGUAGE, LspRegistry, binaryOnPath, languageForFile, } from "./registry.js";
+export { StdioTransport, TransportTimeoutError, killTree, } from "./transport.js";
+export { Server, type ServerTimeouts } from "./server.js";
+export { LspPool, type PoolOptions, type PoolDeps } from "./pool.js";
+export { LspClient } from "./client.js";
+export { getLspService, resetLspServices, type LspService, type LspServiceDeps, } from "./service.js";
+export { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "./tools/index.js";

package/dist/lsp/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { DEFAULT_SPECS, EXT_TO_LANGUAGE, LspRegistry, binaryOnPath, languageForFile, } from "./registry.js";
+export { StdioTransport, TransportTimeoutError, killTree, } from "./transport.js";
+export { Server } from "./server.js";
+export { LspPool } from "./pool.js";
+export { LspClient } from "./client.js";
+export { getLspService, resetLspServices, } from "./service.js";
+export { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "./tools/index.js";

package/dist/lsp/pool.d.ts

@@ -0,0 +1,48 @@
+import { type ServerTimeouts } from "./server.js";
+import { LspRegistry } from "./registry.js";
+import type { LanguageServer, ServerSpec } from "./types.js";
+/** Pool bounds + timeouts, threaded from `lsp.*` config. */
+export interface PoolOptions extends ServerTimeouts {
+    maxServers: number;
+    idleTimeout: number;
+}
+/** Test seams: substitute the spawn+handshake and the clock. */
+export interface PoolDeps {
+    /** Build+initialize a server for a spec. Defaults to a real stdio process. */
+    startServer?: (spec: ServerSpec) => Promise<LanguageServer>;
+    /** Monotonic-ish clock for idle accounting; defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * A per-project pool of language servers (C.12): one server per language,
+ * spawned lazily on first use, reused across calls, evicted when idle or when
+ * the `maxServers` cap forces it, restarted ONCE on crash then surfaced as a
+ * coded error, and all shut down cleanly on teardown. Unavailability (no spec /
+ * missing binary) throws an actionable error — never a silent empty result.
+ */
+export declare class LspPool {
+    private readonly registry;
+    private readonly root;
+    private readonly options;
+    private readonly entries;
+    private readonly starting;
+    private readonly now;
+    private readonly startServer;
+    constructor(registry: LspRegistry, root: string, options: PoolOptions, deps?: PoolDeps);
+    /**
+     * Get a ready server for `language`, spawning lazily and reusing across calls.
+     * Throws `CRUXY_E_LSP_SERVER_NOT_FOUND` when unavailable, `CRUXY_E_LSP_TIMEOUT`
+     * on a startup timeout, or `CRUXY_E_LSP_CRASHED` when a crashed server cannot
+     * be recovered by its single automatic restart.
+     */
+    acquire(language: string): Promise<LanguageServer>;
+    /** Shut down every server idle beyond `idleTimeout` (called on each acquire). */
+    sweepIdle(): void;
+    /** Cleanly shut down all servers (session end / process teardown). */
+    shutdownAll(force?: boolean): Promise<void>;
+    /** Live server count — for tests asserting reuse and the maxServers bound. */
+    size(): number;
+    private startAndStore;
+    /** Evict least-recently-used servers until there is room under the cap. */
+    private evictToCap;
+}

package/dist/lsp/pool.js

@@ -0,0 +1,132 @@
+import { lspCrashed, lspServerNotFound } from "../errors/index.js";
+import { StdioTransport } from "./transport.js";
+import { Server } from "./server.js";
+/**
+ * A per-project pool of language servers (C.12): one server per language,
+ * spawned lazily on first use, reused across calls, evicted when idle or when
+ * the `maxServers` cap forces it, restarted ONCE on crash then surfaced as a
+ * coded error, and all shut down cleanly on teardown. Unavailability (no spec /
+ * missing binary) throws an actionable error — never a silent empty result.
+ */
+export class LspPool {
+    registry;
+    root;
+    options;
+    entries = new Map();
+    starting = new Map();
+    now;
+    startServer;
+    constructor(registry, root, options, deps = {}) {
+        this.registry = registry;
+        this.root = root;
+        this.options = options;
+        this.now = deps.now ?? (() => Date.now());
+        this.startServer =
+            deps.startServer ??
+                ((spec) => Server.start(new StdioTransport(spec, this.root), this.root, spec, {
+                    startupTimeout: options.startupTimeout,
+                    requestTimeout: options.requestTimeout,
+                }));
+    }
+    /**
+     * Get a ready server for `language`, spawning lazily and reusing across calls.
+     * Throws `CRUXY_E_LSP_SERVER_NOT_FOUND` when unavailable, `CRUXY_E_LSP_TIMEOUT`
+     * on a startup timeout, or `CRUXY_E_LSP_CRASHED` when a crashed server cannot
+     * be recovered by its single automatic restart.
+     */
+    async acquire(language) {
+        const resolution = this.registry.resolve(language);
+        if (!resolution.available) {
+            throw lspServerNotFound(language, resolution.reason, {
+                command: resolution.spec?.command,
+                installHint: resolution.spec?.installHint,
+            });
+        }
+        this.sweepIdle();
+        const existing = this.entries.get(language);
+        if (existing) {
+            if (existing.server.alive) {
+                existing.lastUsed = this.now();
+                existing.restarts = 0; // survived a live call — the crash budget resets
+                return existing.server;
+            }
+            // The server crashed. Allow exactly one automatic restart.
+            this.entries.delete(language);
+            await safeShutdown(existing.server, true);
+            if (existing.restarts >= 1) {
+                throw lspCrashed(language);
+            }
+            return this.startAndStore(resolution.spec, existing.restarts + 1);
+        }
+        return this.startAndStore(resolution.spec, 0);
+    }
+    /** Shut down every server idle beyond `idleTimeout` (called on each acquire). */
+    sweepIdle() {
+        const cutoff = this.now() - this.options.idleTimeout;
+        for (const [language, entry] of this.entries) {
+            if (entry.lastUsed <= cutoff) {
+                this.entries.delete(language);
+                void safeShutdown(entry.server, false);
+            }
+        }
+    }
+    /** Cleanly shut down all servers (session end / process teardown). */
+    async shutdownAll(force = false) {
+        const servers = [...this.entries.values()].map((e) => e.server);
+        this.entries.clear();
+        this.starting.clear();
+        await Promise.all(servers.map((s) => safeShutdown(s, force)));
+    }
+    /** Live server count — for tests asserting reuse and the maxServers bound. */
+    size() {
+        return this.entries.size;
+    }
+    async startAndStore(spec, restarts) {
+        const language = spec.language;
+        // Coalesce concurrent first-use so a language never double-spawns.
+        const inFlight = this.starting.get(language);
+        if (inFlight)
+            return inFlight;
+        const pending = (async () => {
+            this.evictToCap();
+            const server = await this.startServer(spec); // may throw lspTimeout
+            this.entries.set(language, { server, lastUsed: this.now(), restarts });
+            return server;
+        })();
+        this.starting.set(language, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            this.starting.delete(language);
+        }
+    }
+    /** Evict least-recently-used servers until there is room under the cap. */
+    evictToCap() {
+        while (this.entries.size >= this.options.maxServers &&
+            this.entries.size > 0) {
+            let oldestLang = null;
+            let oldest = Infinity;
+            for (const [language, entry] of this.entries) {
+                if (entry.lastUsed < oldest) {
+                    oldest = entry.lastUsed;
+                    oldestLang = language;
+                }
+            }
+            if (oldestLang === null)
+                return;
+            const evicted = this.entries.get(oldestLang);
+            this.entries.delete(oldestLang);
+            void safeShutdown(evicted.server, false);
+        }
+    }
+}
+/** Shut a server down without letting a teardown error escape. */
+async function safeShutdown(server, force) {
+    try {
+        await server.shutdown(force);
+    }
+    catch {
+        /* best-effort — the process is being torn down regardless */
+    }
+}

package/dist/lsp/registry.d.ts

@@ -0,0 +1,38 @@
+import type { BinaryPresent, LspConfig, ServerResolution, ServerSpec } from "./types.js";
+/**
+ * The default language → server table (C.12). Documented and overridable per
+ * language via `lsp.servers.<lang>`. cruxy never guesses a command: a language
+ * is served only if it appears here or in config, and the binary must actually
+ * be installed — otherwise the caller gets a coded, actionable failure.
+ */
+export declare const DEFAULT_SPECS: Record<string, Omit<ServerSpec, "language">>;
+/**
+ * File extension → language id. Extensions are matched case-insensitively and
+ * include the leading dot. A file whose extension is absent here has no server
+ * (the caller reports `no-spec`, distinct from a missing binary).
+ */
+export declare const EXT_TO_LANGUAGE: Record<string, string>;
+/** The language id for a file path, or `null` when its extension is unmapped. */
+export declare function languageForFile(filePath: string): string | null;
+/**
+ * Default binary-presence check: resolves `command` the way a shell would.
+ * An absolute/relative path is tested directly; a bare name is searched across
+ * `PATH` (with `PATHEXT` on win32). Pure filesystem probing — never spawns.
+ * Injectable via {@link LspRegistry} so tests can force present/absent.
+ */
+export declare const binaryOnPath: BinaryPresent;
+/**
+ * Resolves a language to a launchable {@link ServerSpec}, or an explicit
+ * "not available" verdict. Config overrides (`lsp.servers.<lang>`, a full
+ * command line split on whitespace) win over the default table; the resolved
+ * binary must be present or the verdict is `binary-missing`.
+ */
+export declare class LspRegistry {
+    private readonly config;
+    private readonly present;
+    constructor(config: LspConfig, present?: BinaryPresent);
+    /** The server spec for a language, from config override or the default table. */
+    specFor(language: string): ServerSpec | null;
+    /** Explicit availability verdict — never conflates "no spec" with "no binary". */
+    resolve(language: string): ServerResolution;
+}

package/dist/lsp/registry.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The default language → server table (C.12). Documented and overridable per
+ * language via `lsp.servers.<lang>`. cruxy never guesses a command: a language
+ * is served only if it appears here or in config, and the binary must actually
+ * be installed — otherwise the caller gets a coded, actionable failure.
+ */
+export const DEFAULT_SPECS = {
+    typescript: {
+        command: "typescript-language-server",
+        args: ["--stdio"],
+        installHint: "install it: `npm i -g typescript-language-server typescript`",
+    },
+    javascript: {
+        command: "typescript-language-server",
+        args: ["--stdio"],
+        installHint: "install it: `npm i -g typescript-language-server typescript`",
+    },
+    python: {
+        command: "pyright-langserver",
+        args: ["--stdio"],
+        installHint: "install it: `npm i -g pyright`",
+    },
+    go: {
+        command: "gopls",
+        args: [],
+        installHint: "install it: `go install golang.org/x/tools/gopls@latest`",
+    },
+    rust: {
+        command: "rust-analyzer",
+        args: [],
+        installHint: "install it: `rustup component add rust-analyzer`",
+    },
+};
+/**
+ * File extension → language id. Extensions are matched case-insensitively and
+ * include the leading dot. A file whose extension is absent here has no server
+ * (the caller reports `no-spec`, distinct from a missing binary).
+ */
+export const EXT_TO_LANGUAGE = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".py": "python",
+    ".pyi": "python",
+    ".go": "go",
+    ".rs": "rust",
+};
+/** The language id for a file path, or `null` when its extension is unmapped. */
+export function languageForFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return EXT_TO_LANGUAGE[ext] ?? null;
+}
+/**
+ * Default binary-presence check: resolves `command` the way a shell would.
+ * An absolute/relative path is tested directly; a bare name is searched across
+ * `PATH` (with `PATHEXT` on win32). Pure filesystem probing — never spawns.
+ * Injectable via {@link LspRegistry} so tests can force present/absent.
+ */
+export const binaryOnPath = (command) => {
+    if (command.includes(path.sep) || command.includes("/")) {
+        return isExecutable(command);
+    }
+    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const exts = process.platform === "win32"
+        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+        : [""];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            if (isExecutable(path.join(dir, command + ext)))
+                return true;
+        }
+    }
+    return false;
+};
+function isExecutable(candidate) {
+    try {
+        const stat = fs.statSync(candidate);
+        if (!stat.isFile())
+            return false;
+        // On POSIX, require an execute bit; on win32 existence is enough.
+        if (process.platform === "win32")
+            return true;
+        return (stat.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves a language to a launchable {@link ServerSpec}, or an explicit
+ * "not available" verdict. Config overrides (`lsp.servers.<lang>`, a full
+ * command line split on whitespace) win over the default table; the resolved
+ * binary must be present or the verdict is `binary-missing`.
+ */
+export class LspRegistry {
+    config;
+    present;
+    constructor(config, present = binaryOnPath) {
+        this.config = config;
+        this.present = present;
+    }
+    /** The server spec for a language, from config override or the default table. */
+    specFor(language) {
+        const override = this.config.servers[language];
+        if (override) {
+            const parts = override.trim().split(/\s+/);
+            const command = parts[0];
+            if (!command)
+                return null;
+            return { language, command, args: parts.slice(1) };
+        }
+        const def = DEFAULT_SPECS[language];
+        return def ? { language, ...def } : null;
+    }
+    /** Explicit availability verdict — never conflates "no spec" with "no binary". */
+    resolve(language) {
+        const spec = this.specFor(language);
+        if (!spec) {
+            return { available: false, language, spec: null, reason: "no-spec" };
+        }
+        if (!this.present(spec.command)) {
+            return { available: false, language, spec, reason: "binary-missing" };
+        }
+        return { available: true, spec };
+    }
+}