@cruxy/cli 0.19.0 → 0.20.0

package/dist/lsp/service.d.ts

@@ -0,0 +1,44 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { BinaryPresent, LspDiagnostic, LspHover, LspLocation, TransportFactory } from "./types.js";
+/** Logger surface the service reports through (matches the indexing service). */
+interface ServiceLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * A ready-to-use LSP facade for one project root (C.12): it owns the registry,
+ * pool, and client, exposes the four normalized queries, and shuts the whole
+ * server pool down on `close()`. Build one with {@link getLspService}, cached
+ * per cwd so servers are spawned at most once per project per process.
+ */
+export interface LspService {
+    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[]>;
+    /** Shut down every managed server (session end / process teardown). */
+    close(): Promise<void>;
+}
+/**
+ * Explicit dependency overrides, for tests only. Production callers (the LSP
+ * tools) never pass these, so they always go through the real stdio transport
+ * and PATH-based binary detection.
+ */
+export interface LspServiceDeps {
+    /** Substitute the JSON-RPC transport (a fake stdio peer — no real binary). */
+    transportFactory?: TransportFactory;
+    /** Substitute PATH-based binary detection (force present/absent). */
+    binaryPresent?: BinaryPresent;
+    /** Substitute the idle clock. */
+    now?: () => number;
+}
+/**
+ * Get (or build) the {@link LspService} for a project root, cached per resolved
+ * cwd so the pool is created at most once per process. No server spawns until
+ * the first query. `deps` is for explicit test injection only.
+ */
+export declare function getLspService(cwd: string, config: CruxyConfig, logger: ServiceLogger, deps?: LspServiceDeps): LspService;
+/** Drop all cached services (shutting them down). For tests and process teardown. */
+export declare function resetLspServices(): Promise<void>;
+export {};

package/dist/lsp/service.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { Server } from "./server.js";
+import { LspRegistry, binaryOnPath } from "./registry.js";
+import { LspPool } from "./pool.js";
+import { LspClient } from "./client.js";
+class LspServiceImpl {
+    pool;
+    logger;
+    client;
+    constructor(pool, logger) {
+        this.pool = pool;
+        this.logger = logger;
+        this.client = new LspClient(pool);
+    }
+    definition(file, line, col) {
+        return this.client.definition(file, line, col);
+    }
+    references(file, line, col) {
+        return this.client.references(file, line, col);
+    }
+    hover(file, line, col) {
+        return this.client.hover(file, line, col);
+    }
+    diagnostics(file) {
+        return this.client.diagnostics(file);
+    }
+    async close() {
+        this.logger.debug("shutting down LSP servers");
+        await this.pool.shutdownAll();
+    }
+}
+// ── per-cwd cache ──────────────────────────────────────────────────────────────
+const cache = new Map();
+/**
+ * Get (or build) the {@link LspService} for a project root, cached per resolved
+ * cwd so the pool is created at most once per process. No server spawns until
+ * the first query. `deps` is for explicit test injection only.
+ */
+export function getLspService(cwd, config, logger, deps) {
+    const root = path.resolve(cwd);
+    let service = cache.get(root);
+    if (!service) {
+        service = buildService(root, config, logger, deps);
+        cache.set(root, service);
+    }
+    return service;
+}
+/** Drop all cached services (shutting them down). For tests and process teardown. */
+export async function resetLspServices() {
+    const services = [...cache.values()];
+    cache.clear();
+    for (const service of services) {
+        try {
+            await service.close();
+        }
+        catch {
+            /* already closed or failed to build */
+        }
+    }
+}
+function buildService(root, config, logger, deps) {
+    const lsp = config.lsp;
+    const registry = new LspRegistry(lsp, deps?.binaryPresent ?? binaryOnPath);
+    const timeouts = {
+        startupTimeout: lsp.startupTimeout,
+        requestTimeout: lsp.requestTimeout,
+    };
+    const transportFactory = deps?.transportFactory;
+    const pool = new LspPool(registry, root, { ...timeouts, maxServers: lsp.maxServers, idleTimeout: lsp.idleTimeout }, {
+        now: deps?.now,
+        startServer: transportFactory
+            ? (spec) => Server.start(transportFactory(spec, root), root, spec, timeouts)
+            : undefined,
+    });
+    return new LspServiceImpl(pool, logger);
+}

package/dist/lsp/tools/common.d.ts

@@ -0,0 +1,23 @@
+import type { ToolContext, ToolResult } from "../../tools/types.js";
+import { type LspService } from "../service.js";
+import type { LspLocation } from "../types.js";
+/**
+ * The shared spine of every LSP tool (C.12): enforce the master switch, validate
+ * the target path stays in the project root, prove it exists, get the per-cwd
+ * service, and run `query`. Read-only throughout — no `ctx.requestApproval`, so
+ * these bypass the U.3 gate exactly like `search_codebase` and `grep_files`.
+ *
+ * Errors are surfaced as `{ ok:false }` text the agent can act on: a coded LSP
+ * failure (no server / timeout / crash) is rendered WITH its next step, so the
+ * agent can reroute (e.g. to grep) or the user can install the server. A genuine
+ * empty answer never reaches here as an error — `query` returns it as `ok:true`.
+ */
+export declare function runLspTool(ctx: ToolContext, file: string, query: (service: LspService, absFile: string) => Promise<ToolResult>): Promise<ToolResult>;
+/**
+ * Render up to `max` locations as `path:line:col-endLine:endCol`, one per line,
+ * with a trailing "N more" note when capped — the same bounded-honest pattern as
+ * grep_files and search_codebase (never silently drop the overflow).
+ */
+export declare function formatLocations(locations: LspLocation[], max: number): string;
+/** Relative label for a validated absolute path, for tool messages. */
+export declare function relLabel(cwd: string, absFile: string): string;

package/dist/lsp/tools/common.js

@@ -0,0 +1,75 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { CruxyError } from "../../errors/index.js";
+import { resolveInRoot } from "../../tools/file/paths.js";
+import { getLspService } from "../service.js";
+/**
+ * The shared spine of every LSP tool (C.12): enforce the master switch, validate
+ * the target path stays in the project root, prove it exists, get the per-cwd
+ * service, and run `query`. Read-only throughout — no `ctx.requestApproval`, so
+ * these bypass the U.3 gate exactly like `search_codebase` and `grep_files`.
+ *
+ * Errors are surfaced as `{ ok:false }` text the agent can act on: a coded LSP
+ * failure (no server / timeout / crash) is rendered WITH its next step, so the
+ * agent can reroute (e.g. to grep) or the user can install the server. A genuine
+ * empty answer never reaches here as an error — `query` returns it as `ok:true`.
+ */
+export async function runLspTool(ctx, file, query) {
+    if (!ctx.config.lsp.enabled) {
+        return {
+            ok: false,
+            error: "LSP tools are disabled (set lsp.enabled = true to use language-server features)",
+        };
+    }
+    let absFile;
+    try {
+        absFile = await resolveInRoot(ctx, file);
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+    try {
+        const stat = await fsp.stat(absFile);
+        if (!stat.isFile()) {
+            return { ok: false, error: `not a file: ${file}` };
+        }
+    }
+    catch {
+        return { ok: false, error: `file not found: ${file}` };
+    }
+    try {
+        const service = getLspService(ctx.cwd, ctx.config, ctx.logger);
+        return await query(service, absFile);
+    }
+    catch (err) {
+        return { ok: false, error: describeError(err) };
+    }
+}
+/** Render a coded LSP error with its actionable next step, for the model to read. */
+function describeError(err) {
+    if (CruxyError.is(err)) {
+        const cause = err.cause ? ` — ${err.cause}` : "";
+        const step = err.nextSteps[0] ? `\n→ ${err.nextSteps[0]}` : "";
+        return `[${err.code}] ${err.title}${cause}${step}`;
+    }
+    return err.message;
+}
+/**
+ * Render up to `max` locations as `path:line:col-endLine:endCol`, one per line,
+ * with a trailing "N more" note when capped — the same bounded-honest pattern as
+ * grep_files and search_codebase (never silently drop the overflow).
+ */
+export function formatLocations(locations, max) {
+    const shown = locations.slice(0, max);
+    const lines = shown.map((l) => `${l.path}:${l.startLine}:${l.startCol}-${l.endLine}:${l.endCol}`);
+    const omitted = locations.length - shown.length;
+    if (omitted > 0) {
+        lines.push(`… [${omitted} more location(s) omitted]`);
+    }
+    return lines.join("\n");
+}
+/** Relative label for a validated absolute path, for tool messages. */
+export function relLabel(cwd, absFile) {
+    const rel = path.relative(path.resolve(cwd), absFile);
+    return rel === "" ? absFile : rel.split(path.sep).join("/");
+}

package/dist/lsp/tools/find-definition.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+    column: number;
+}, {
+    file: string;
+    line: number;
+    column: number;
+}>;
+/**
+ * LSP go-to-definition (C.12). Read-only — no approval, like search_codebase.
+ * Returns the definition site(s) as `path:line:col-endLine:endCol`. A missing
+ * language server is a coded, actionable error (distinct from "no definition
+ * found", which is an honest empty result).
+ */
+export declare const findDefinitionTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/find-definition.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { formatLocations, runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol to resolve."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP go-to-definition (C.12). Read-only — no approval, like search_codebase.
+ * Returns the definition site(s) as `path:line:col-endLine:endCol`. A missing
+ * language server is a coded, actionable error (distinct from "no definition
+ * found", which is an honest empty result).
+ */
+export const findDefinitionTool = {
+    name: "find_definition",
+    description: "Resolve where a symbol is defined using the project's language server (go-to-definition). Give the file and the 1-based line/column of the identifier. Returns definition locations as 'path:line:col-endLine:endCol'. Read-only, no approval. Precise where grep is textual — prefer this to jump to a symbol's definition.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const locations = await service.definition(absFile, input.line, input.column);
+            if (locations.length === 0) {
+                return { ok: true, output: "(no definition found)" };
+            }
+            return {
+                ok: true,
+                output: formatLocations(locations, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};

package/dist/lsp/tools/find-references.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+    column: number;
+}, {
+    file: string;
+    line: number;
+    column: number;
+}>;
+/**
+ * LSP find-references (C.12). Read-only — no approval. Returns every use of the
+ * symbol (declaration included) as `path:line:col-endLine:endCol`, capped to
+ * `lsp.maxResults` with an "N more" note so a hot symbol can't flood the output.
+ * A missing server is a coded error, distinct from an honest "no references".
+ */
+export declare const findReferencesTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/find-references.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { formatLocations, runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP find-references (C.12). Read-only — no approval. Returns every use of the
+ * symbol (declaration included) as `path:line:col-endLine:endCol`, capped to
+ * `lsp.maxResults` with an "N more" note so a hot symbol can't flood the output.
+ * A missing server is a coded error, distinct from an honest "no references".
+ */
+export const findReferencesTool = {
+    name: "find_references",
+    description: "Find all references to a symbol using the project's language server. Give the file and the 1-based line/column of the identifier. Returns use sites as 'path:line:col-endLine:endCol' (capped, with an 'N more' note). Read-only, no approval. Precise where grep is textual — prefer this to see every caller/user of a symbol.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const locations = await service.references(absFile, input.line, input.column);
+            if (locations.length === 0) {
+                return { ok: true, output: "(no references found)" };
+            }
+            return {
+                ok: true,
+                output: formatLocations(locations, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};

package/dist/lsp/tools/get-diagnostics.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+}, {
+    file: string;
+}>;
+/**
+ * LSP diagnostics (C.12): the language server's errors/warnings for a file.
+ * Read-only — no approval. Returns each diagnostic as
+ * `severity path:line:col message [source]`, capped to `lsp.maxResults`. A
+ * missing server is a coded error; a clean file is an honest empty result.
+ */
+export declare const getDiagnosticsTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/get-diagnostics.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file to diagnose."),
+});
+/**
+ * LSP diagnostics (C.12): the language server's errors/warnings for a file.
+ * Read-only — no approval. Returns each diagnostic as
+ * `severity path:line:col message [source]`, capped to `lsp.maxResults`. A
+ * missing server is a coded error; a clean file is an honest empty result.
+ */
+export const getDiagnosticsTool = {
+    name: "get_diagnostics",
+    description: "Get the language server's diagnostics (errors, warnings) for a file. Give the project-relative path. Returns diagnostics as 'severity path:line:col message'. Read-only, no approval. Use this after an edit to see type errors the compiler/linter reports, without running a build.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const diagnostics = await service.diagnostics(absFile);
+            if (diagnostics.length === 0) {
+                return { ok: true, output: "(no diagnostics)" };
+            }
+            return {
+                ok: true,
+                output: formatDiagnostics(diagnostics, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};
+function formatDiagnostics(diagnostics, max) {
+    const shown = diagnostics.slice(0, max);
+    const lines = shown.map((d) => {
+        const src = d.source ? ` [${d.source}]` : "";
+        return `${d.severity} ${d.path}:${d.range.startLine}:${d.range.startCol} ${d.message}${src}`;
+    });
+    const omitted = diagnostics.length - shown.length;
+    if (omitted > 0) {
+        lines.push(`… [${omitted} more diagnostic(s) omitted]`);
+    }
+    return lines.join("\n");
+}

package/dist/lsp/tools/hover.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+    column: number;
+}, {
+    file: string;
+    line: number;
+    column: number;
+}>;
+/**
+ * LSP hover (C.12): type signature / documentation for the symbol at a position.
+ * Read-only — no approval. Returns the server's hover text (markup flattened to
+ * plain text). A missing server is a coded error; a symbol with no hover info is
+ * an honest empty result.
+ */
+export declare const hoverTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/hover.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP hover (C.12): type signature / documentation for the symbol at a position.
+ * Read-only — no approval. Returns the server's hover text (markup flattened to
+ * plain text). A missing server is a coded error; a symbol with no hover info is
+ * an honest empty result.
+ */
+export const hoverTool = {
+    name: "hover",
+    description: "Get type information and documentation for a symbol using the project's language server (hover). Give the file and the 1-based line/column of the identifier. Returns the symbol's type signature and docs. Read-only, no approval. Use this to learn a symbol's type without opening and reading its declaration.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const hover = await service.hover(absFile, input.line, input.column);
+            if (!hover) {
+                return { ok: true, output: "(no hover information)" };
+            }
+            return { ok: true, output: hover.contents };
+        });
+    },
+};

package/dist/lsp/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { findDefinitionTool } from "./find-definition.js";
+export { findReferencesTool } from "./find-references.js";
+export { getDiagnosticsTool } from "./get-diagnostics.js";
+export { hoverTool } from "./hover.js";

package/dist/lsp/tools/index.js

@@ -0,0 +1,4 @@
+export { findDefinitionTool } from "./find-definition.js";
+export { findReferencesTool } from "./find-references.js";
+export { getDiagnosticsTool } from "./get-diagnostics.js";
+export { hoverTool } from "./hover.js";

package/dist/lsp/transport.d.ts

@@ -0,0 +1,48 @@
+import type { LspTransport, ServerSpec } from "./types.js";
+export declare class StdioTransport implements LspTransport {
+    private readonly child;
+    private nextId;
+    private readonly pending;
+    private readonly notificationHandlers;
+    private crashHandler;
+    /** stdout parse buffer (header + body may arrive across chunks). */
+    private buffer;
+    private disposed;
+    /** Deregisters this process from the process-exit kill-tree backstop. */
+    private readonly unregisterCleanup;
+    constructor(spec: ServerSpec, root: string);
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    onNotification(method: string, handler: (params: unknown) => void): void;
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    dispose(force?: boolean): Promise<void>;
+    private send;
+    private onStdout;
+    private dispatch;
+    private onExit;
+    private onSpawnError;
+}
+/** A per-request timeout, distinguishable from an ordinary LSP error response. */
+export declare class TransportTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number);
+}
+/**
+ * Kill the process's entire group (POSIX negative-PID `SIGKILL`), same helper
+ * shape as run_command's `killTree`. Swallows errors — the process may be gone.
+ */
+export declare function killTree(pid: number | undefined): void;
+/**
+ * Force-kill the process group of every tracked-but-not-yet-shut-down server,
+ * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
+ * handlers run — the last line against orphaned language servers on a hard exit.
+ * Exported so it is directly testable (like `resetIndexServices`) without having
+ * to raise real process signals. Idempotent: a second call is a no-op.
+ */
+export declare function killTrackedServers(): void;
+/** Number of servers currently tracked by the exit backstop (for tests). */
+export declare function trackedServerCount(): number;