@cruxy/cli 0.19.0 → 0.20.0

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 };
+    }
+}

package/dist/lsp/server.d.ts

@@ -0,0 +1,48 @@
+import type { LanguageServer, LspDiagnostic, LspHover, LspLocation, LspTransport, ServerSpec } from "./types.js";
+/** Bounds threaded from `lsp.*` config into a server. */
+export interface ServerTimeouts {
+    startupTimeout: number;
+    requestTimeout: number;
+}
+/**
+ * An initialized {@link LanguageServer} over an {@link LspTransport} (C.12).
+ * Owns the LSP handshake, lazily opens documents (servers answer only for open
+ * files), converts LSP's 0-based positions / `file://` URIs to normalized
+ * 1-based / path results, and shuts down cleanly. A missing/timed-out/crashed
+ * server surfaces as a coded error; an empty answer stays an honest `[]`/`null`.
+ */
+export declare class Server implements LanguageServer {
+    private readonly transport;
+    private readonly root;
+    private readonly timeouts;
+    readonly language: string;
+    private _alive;
+    private readonly openDocs;
+    private readonly diagnosticsByUri;
+    private readonly diagnosticsWaiters;
+    private constructor();
+    get alive(): boolean;
+    /**
+     * Spawn+handshake a server: `initialize` (bounded by `startupTimeout`) then
+     * the `initialized` notification. A startup timeout throws a coded error after
+     * the transport is force-disposed — never a hang.
+     */
+    static start(transport: LspTransport, root: string, spec: ServerSpec, timeouts: ServerTimeouts): Promise<Server>;
+    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[]>;
+    shutdown(force?: boolean): Promise<void>;
+    private uri;
+    private ensureOpen;
+    private query;
+    /** One request with per-request timeout + coded-error mapping (timeout/crash). */
+    private request;
+    private onPublishDiagnostics;
+    private waitForDiagnostics;
+    private toLocations;
+    private toLocation;
+    private toDiagnostic;
+    /** `file://` URI → project-relative path (falls back to the fs path on error). */
+    private relativize;
+}

package/dist/lsp/server.js

@@ -0,0 +1,264 @@
+import { promises as fsp } from "node:fs";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { lspCrashed, lspTimeout } from "../errors/index.js";
+import { TransportTimeoutError } from "./transport.js";
+/**
+ * An initialized {@link LanguageServer} over an {@link LspTransport} (C.12).
+ * Owns the LSP handshake, lazily opens documents (servers answer only for open
+ * files), converts LSP's 0-based positions / `file://` URIs to normalized
+ * 1-based / path results, and shuts down cleanly. A missing/timed-out/crashed
+ * server surfaces as a coded error; an empty answer stays an honest `[]`/`null`.
+ */
+export class Server {
+    transport;
+    root;
+    timeouts;
+    language;
+    _alive = true;
+    openDocs = new Set();
+    diagnosticsByUri = new Map();
+    diagnosticsWaiters = new Map();
+    constructor(transport, root, spec, timeouts) {
+        this.transport = transport;
+        this.root = root;
+        this.timeouts = timeouts;
+        this.language = spec.language;
+        this.transport.onCrash(() => {
+            this._alive = false;
+        });
+        this.transport.onNotification("textDocument/publishDiagnostics", (params) => this.onPublishDiagnostics(params));
+    }
+    get alive() {
+        return this._alive;
+    }
+    /**
+     * Spawn+handshake a server: `initialize` (bounded by `startupTimeout`) then
+     * the `initialized` notification. A startup timeout throws a coded error after
+     * the transport is force-disposed — never a hang.
+     */
+    static async start(transport, root, spec, timeouts) {
+        const server = new Server(transport, root, spec, timeouts);
+        const rootUri = pathToFileURL(root).toString();
+        try {
+            await transport.request("initialize", {
+                processId: process.pid,
+                rootUri,
+                workspaceFolders: [{ uri: rootUri, name: "root" }],
+                capabilities: {
+                    textDocument: {
+                        synchronization: { dynamicRegistration: false },
+                        definition: { dynamicRegistration: false },
+                        references: { dynamicRegistration: false },
+                        hover: { contentFormat: ["markdown", "plaintext"] },
+                        publishDiagnostics: {},
+                    },
+                },
+            }, timeouts.startupTimeout);
+        }
+        catch (err) {
+            await transport.dispose(true);
+            if (err instanceof TransportTimeoutError) {
+                throw lspTimeout(spec.language, "startup", timeouts.startupTimeout);
+            }
+            throw err;
+        }
+        transport.notify("initialized", {});
+        return server;
+    }
+    async definition(file, line, col) {
+        await this.ensureOpen(file);
+        const result = await this.query("textDocument/definition", file, line, col);
+        return this.toLocations(result);
+    }
+    async references(file, line, col) {
+        await this.ensureOpen(file);
+        const result = await this.request("textDocument/references", {
+            textDocument: { uri: this.uri(file) },
+            position: toPosition(line, col),
+            context: { includeDeclaration: true },
+        });
+        return this.toLocations(result);
+    }
+    async hover(file, line, col) {
+        await this.ensureOpen(file);
+        const result = (await this.query("textDocument/hover", file, line, col));
+        if (!result || result.contents == null)
+            return null;
+        const contents = flattenHover(result.contents).trim();
+        if (!contents)
+            return null;
+        return {
+            contents,
+            range: result.range
+                ? this.toLocation(this.uri(file), result.range)
+                : undefined,
+        };
+    }
+    async diagnostics(file) {
+        const uri = this.uri(file);
+        const fresh = !this.openDocs.has(uri);
+        await this.ensureOpen(file);
+        // Most servers PUSH diagnostics via publishDiagnostics after didOpen. If a
+        // push already arrived (reused doc), return it; otherwise wait one bounded
+        // window for the first push, then honestly return whatever we have ([] is a
+        // real "no diagnostics", never conflated with "server unavailable").
+        if (!fresh && this.diagnosticsByUri.has(uri)) {
+            return this.diagnosticsByUri.get(uri) ?? [];
+        }
+        await this.waitForDiagnostics(uri, this.timeouts.requestTimeout);
+        return this.diagnosticsByUri.get(uri) ?? [];
+    }
+    async shutdown(force = false) {
+        if (this._alive && !force) {
+            try {
+                await this.request("shutdown", null);
+                this.transport.notify("exit", null);
+            }
+            catch {
+                // A server that won't answer shutdown gets force-killed below anyway.
+            }
+        }
+        this._alive = false;
+        await this.transport.dispose(force);
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    uri(file) {
+        return pathToFileURL(file).toString();
+    }
+    async ensureOpen(file) {
+        const uri = this.uri(file);
+        if (this.openDocs.has(uri))
+            return;
+        const text = await fsp.readFile(file, "utf8");
+        this.transport.notify("textDocument/didOpen", {
+            textDocument: { uri, languageId: this.language, version: 1, text },
+        });
+        this.openDocs.add(uri);
+    }
+    query(method, file, line, col) {
+        return this.request(method, {
+            textDocument: { uri: this.uri(file) },
+            position: toPosition(line, col),
+        });
+    }
+    /** One request with per-request timeout + coded-error mapping (timeout/crash). */
+    async request(method, params) {
+        try {
+            return await this.transport.request(method, params, this.timeouts.requestTimeout);
+        }
+        catch (err) {
+            if (err instanceof TransportTimeoutError) {
+                throw lspTimeout(this.language, "request", this.timeouts.requestTimeout);
+            }
+            if (!this._alive) {
+                throw lspCrashed(this.language, err.message);
+            }
+            throw err;
+        }
+    }
+    onPublishDiagnostics(params) {
+        const p = params;
+        if (!p?.uri)
+            return;
+        const list = (p.diagnostics ?? []).map((d) => this.toDiagnostic(p.uri, d));
+        this.diagnosticsByUri.set(p.uri, list);
+        const waiters = this.diagnosticsWaiters.get(p.uri);
+        if (waiters) {
+            this.diagnosticsWaiters.delete(p.uri);
+            for (const w of waiters)
+                w();
+        }
+    }
+    waitForDiagnostics(uri, timeoutMs) {
+        if (this.diagnosticsByUri.has(uri))
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const waiters = this.diagnosticsWaiters.get(uri) ?? [];
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                resolve();
+            };
+            waiters.push(finish);
+            this.diagnosticsWaiters.set(uri, waiters);
+            const timer = setTimeout(finish, timeoutMs);
+            timer.unref?.();
+        });
+    }
+    // ── normalization (LSP → normalized) ────────────────────────────────────────
+    toLocations(result) {
+        if (result == null)
+            return [];
+        const raw = Array.isArray(result) ? result : [result];
+        const out = [];
+        for (const item of raw) {
+            // Plain Location: { uri, range }. LocationLink: { targetUri, targetRange }.
+            const loc = item;
+            const uri = loc.uri ?? loc.targetUri;
+            const range = loc.range ?? loc.targetRange;
+            if (uri && range)
+                out.push(this.toLocation(uri, range));
+        }
+        return out;
+    }
+    toLocation(uri, range) {
+        return {
+            path: this.relativize(uri),
+            startLine: range.start.line + 1,
+            startCol: range.start.character + 1,
+            endLine: range.end.line + 1,
+            endCol: range.end.character + 1,
+        };
+    }
+    toDiagnostic(uri, d) {
+        return {
+            path: this.relativize(uri),
+            range: this.toLocation(uri, d.range),
+            severity: SEVERITY[d.severity ?? 1] ?? "error",
+            message: d.message,
+            source: d.source,
+        };
+    }
+    /** `file://` URI → project-relative path (falls back to the fs path on error). */
+    relativize(uri) {
+        let abs;
+        try {
+            abs = fileURLToPath(uri);
+        }
+        catch {
+            return uri;
+        }
+        const rel = relativePath(this.root, abs);
+        return rel;
+    }
+}
+const SEVERITY = {
+    1: "error",
+    2: "warning",
+    3: "info",
+    4: "hint",
+};
+function toPosition(line, col) {
+    // Tool inputs are 1-based; LSP is 0-based. Clamp at 0 defensively.
+    return { line: Math.max(0, line - 1), character: Math.max(0, col - 1) };
+}
+/** Flatten every hover-content shape (string / MarkedString / MarkupContent) to text. */
+function flattenHover(contents) {
+    if (typeof contents === "string")
+        return contents;
+    if (Array.isArray(contents)) {
+        return contents
+            .map((c) => (typeof c === "string" ? c : c.value))
+            .join("\n");
+    }
+    return contents.value;
+}
+/** POSIX-normalized project-relative path (kept in one place for display). */
+function relativePath(root, abs) {
+    const path = abs.startsWith(root)
+        ? abs.slice(root.length).replace(/^[/\\]+/, "")
+        : abs;
+    return path.split("\\").join("/");
+}