@jitsusama/agentic-harness.core 0.1.0

package/dist/lsp/standalone/backend.js

@@ -0,0 +1,150 @@
+/**
+ * The standalone backend: routing plus a live server pool.
+ *
+ * Every operation carries a file, so the file is the routing
+ * key. The backend resolves the file's candidate servers,
+ * walks up to each server's project root, resolves its binary
+ * local-bin-first then on PATH, and reuses or spawns one
+ * server per (serverName, root). Type-intelligence operations
+ * route to the single non-linter server for the root, while
+ * diagnostics aggregate across every server attached to the
+ * file. When nothing resolves, it fails with a clear message
+ * rather than a cryptic one.
+ *
+ * The live server pool lives in this closure's memory for the
+ * life of the process that constructs it. A stateless-per-call
+ * CLI adapter that wants warm servers across invocations needs
+ * its own keep-alive design on top of this (the same shape as
+ * quest's on-disk state file, or core/browser's file-backed
+ * session registry) -- not something this module does itself.
+ */
+import { DEFAULT_SERVERS, resolveBinary, resolveRoot, serversForFile, } from "../config.js";
+import { StandaloneServer } from "./server.js";
+/** Raised when no server can serve a file, with why per candidate. */
+export class MissingServerError extends Error {
+    constructor(filePath, reasons) {
+        super(`No language server available for ${filePath}. ${reasons.join("; ")}. ` +
+            "Provision a server as a project dev-dependency, in a devshell, or on PATH.");
+        this.name = "MissingServerError";
+    }
+}
+/** Construct a standalone backend over the given (or default) server map. */
+export function createStandaloneBackend(options = {}) {
+    const servers = options.servers ?? DEFAULT_SERVERS;
+    const env = options.env ?? process.env;
+    const pool = new Map();
+    const poolKey = (name, root) => `${name}|${root}`;
+    const instanceFor = (server, root, binary) => {
+        const key = poolKey(server.name, root);
+        const existing = pool.get(key);
+        if (existing)
+            return existing;
+        const started = StandaloneServer.start(server, root, binary);
+        pool.set(key, started);
+        return started;
+    };
+    // Resolve a server's effective command and args for a root. A
+    // server with a `resolve` hook picks its binary per project (the
+    // TypeScript entry chooses the native LSP or the classic wrapper
+    // by version); a null result means nothing compatible is present.
+    const effectiveServer = (server, root) => {
+        const resolved = server.resolve
+            ? server.resolve(root, env)
+            : { command: server.command, args: server.args };
+        if (!resolved) {
+            return {
+                reason: `${server.name}: no compatible server for this project's TypeScript version`,
+            };
+        }
+        const binary = resolveBinary(resolved.command, root, env);
+        if (!binary) {
+            return { reason: `${server.name}: binary ${resolved.command} not found` };
+        }
+        return {
+            config: { ...server, command: resolved.command, args: resolved.args },
+            binary,
+        };
+    };
+    const resolveInstances = async (filePath, typeOnly) => {
+        const candidates = serversForFile(filePath, servers).filter((server) => !typeOnly || !server.isLinter);
+        const instances = [];
+        const reasons = [];
+        for (const server of candidates) {
+            const root = resolveRoot(filePath, server.rootMarkers);
+            if (!root) {
+                reasons.push(`${server.name}: no project root marker found`);
+                continue;
+            }
+            const eff = effectiveServer(server, root);
+            if ("reason" in eff) {
+                reasons.push(eff.reason);
+                continue;
+            }
+            instances.push(await instanceFor(eff.config, root, eff.binary));
+            if (typeOnly)
+                break;
+        }
+        if (instances.length === 0) {
+            if (candidates.length === 0) {
+                reasons.push("no server handles this file type");
+            }
+            throw new MissingServerError(filePath, reasons);
+        }
+        return instances;
+    };
+    return {
+        name: "standalone",
+        async diagnostics(path) {
+            const instances = await resolveInstances(path, false);
+            const results = await Promise.all(instances.map((s) => s.diagnose(path)));
+            return results.flat();
+        },
+        async definition(target) {
+            const [server] = await resolveInstances(target.path, true);
+            return server.definition(target);
+        },
+        async references(target) {
+            const [server] = await resolveInstances(target.path, true);
+            return server.references(target);
+        },
+        async hover(target) {
+            const [server] = await resolveInstances(target.path, true);
+            return server.hover(target);
+        },
+        async documentSymbols(path) {
+            const [server] = await resolveInstances(path, true);
+            return server.documentSymbols(path);
+        },
+        async workspaceSymbols(query) {
+            // Workspace symbols carry no file, so they search every
+            // server already running; nothing is spawned on demand.
+            const live = await Promise.all([...pool.values()]);
+            const results = await Promise.all(live.map((server) => server.workspaceSymbols(query)));
+            return results.flat();
+        },
+        async rename(target, newName) {
+            const [server] = await resolveInstances(target.path, true);
+            return server.rename(target, newName);
+        },
+        async codeActions(path, range) {
+            const [server] = await resolveInstances(path, true);
+            return server.codeActions(path, range);
+        },
+        syncDocument(path, text) {
+            for (const started of pool.values()) {
+                void started.then((server) => {
+                    if (path.startsWith(server.root))
+                        server.syncDocument(path, text);
+                });
+            }
+        },
+        serverCount() {
+            return pool.size;
+        },
+        async dispose() {
+            const started = [...pool.values()];
+            pool.clear();
+            await Promise.all(started.map((s) => s.then((server) => server.dispose())));
+        },
+    };
+}

package/dist/lsp/standalone/document.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Document helpers for the standalone backend: file URIs,
+ * language ids, and the position mapping between the tool's
+ * 1-indexed line plus 0-indexed byte column and LSP's
+ * 0-indexed line plus 0-indexed UTF-16 column.
+ */
+import type { LspPosition, LspRange } from "../types.js";
+/** A position in LSP's own coordinates: 0-indexed line, 0-indexed UTF-16 column. */
+export interface LspProtocolPosition {
+    readonly line: number;
+    readonly character: number;
+}
+/** A range in LSP's own coordinates. */
+export interface LspProtocolRange {
+    readonly start: LspProtocolPosition;
+    readonly end: LspProtocolPosition;
+}
+/** Absolute file path to a `file://` URI. */
+export declare function fileToUri(filePath: string): string;
+/** `file://` URI back to an absolute file path. */
+export declare function uriToFile(uri: string): string;
+/** The LSP languageId for a file, defaulting to plaintext. */
+export declare function languageIdFor(filePath: string): string;
+/** Split file text into lines, dropping line terminators. */
+export declare function toLines(text: string): string[];
+/** Map a tool position to LSP protocol coordinates using the file's lines. */
+export declare function toProtocolPosition(lines: readonly string[], pos: LspPosition): LspProtocolPosition;
+/** Map an LSP protocol position back to a tool position using the file's lines. */
+export declare function fromProtocolPosition(lines: readonly string[], pos: LspProtocolPosition): LspPosition;
+/** Map an LSP protocol range back to a tool range using the file's lines. */
+export declare function fromProtocolRange(lines: readonly string[], range: LspProtocolRange): LspRange;
+/** A protocol text edit: a UTF-16 range and its replacement. */
+export interface LspProtocolTextEdit {
+    readonly range: LspProtocolRange;
+    readonly newText: string;
+}
+/**
+ * Apply LSP protocol edits to a document's text. Protocol
+ * positions are UTF-16 offsets, which match a JavaScript
+ * string's own indexing, so an edit's absolute offset is the
+ * line's start offset plus its character. Edits apply from
+ * the end backwards so earlier splices never shift later
+ * offsets.
+ */
+export declare function applyProtocolEdits(text: string, edits: readonly LspProtocolTextEdit[]): string;

package/dist/lsp/standalone/document.js

@@ -0,0 +1,81 @@
+/**
+ * Document helpers for the standalone backend: file URIs,
+ * language ids, and the position mapping between the tool's
+ * 1-indexed line plus 0-indexed byte column and LSP's
+ * 0-indexed line plus 0-indexed UTF-16 column.
+ */
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { byteToUtf16, utf16ToByte } from "../offsets.js";
+/** Absolute file path to a `file://` URI. */
+export function fileToUri(filePath) {
+    return pathToFileURL(filePath).toString();
+}
+/** `file://` URI back to an absolute file path. */
+export function uriToFile(uri) {
+    return fileURLToPath(uri);
+}
+const LANGUAGE_BY_EXT = {
+    ".ts": "typescript",
+    ".tsx": "typescriptreact",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascriptreact",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+};
+/** The LSP languageId for a file, defaulting to plaintext. */
+export function languageIdFor(filePath) {
+    const dot = filePath.lastIndexOf(".");
+    const ext = dot < 0 ? "" : filePath.slice(dot);
+    return LANGUAGE_BY_EXT[ext] ?? "plaintext";
+}
+/** Split file text into lines, dropping line terminators. */
+export function toLines(text) {
+    return text.split(/\r\n|\r|\n/);
+}
+/** Map a tool position to LSP protocol coordinates using the file's lines. */
+export function toProtocolPosition(lines, pos) {
+    const line = pos.line - 1;
+    const lineText = lines[line] ?? "";
+    return { line, character: byteToUtf16(lineText, pos.character) };
+}
+/** Map an LSP protocol position back to a tool position using the file's lines. */
+export function fromProtocolPosition(lines, pos) {
+    const lineText = lines[pos.line] ?? "";
+    return {
+        line: pos.line + 1,
+        character: utf16ToByte(lineText, pos.character),
+    };
+}
+/** Map an LSP protocol range back to a tool range using the file's lines. */
+export function fromProtocolRange(lines, range) {
+    return {
+        start: fromProtocolPosition(lines, range.start),
+        end: fromProtocolPosition(lines, range.end),
+    };
+}
+/**
+ * Apply LSP protocol edits to a document's text. Protocol
+ * positions are UTF-16 offsets, which match a JavaScript
+ * string's own indexing, so an edit's absolute offset is the
+ * line's start offset plus its character. Edits apply from
+ * the end backwards so earlier splices never shift later
+ * offsets.
+ */
+export function applyProtocolEdits(text, edits) {
+    const lineStarts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\n")
+            lineStarts.push(i + 1);
+    }
+    const offsetOf = (pos) => (lineStarts[pos.line] ?? text.length) + pos.character;
+    const ordered = [...edits].sort((a, b) => offsetOf(b.range.start) - offsetOf(a.range.start));
+    let result = text;
+    for (const edit of ordered) {
+        const start = offsetOf(edit.range.start);
+        const end = offsetOf(edit.range.end);
+        result = result.slice(0, start) + edit.newText + result.slice(end);
+    }
+    return result;
+}

package/dist/lsp/standalone/server.d.ts

@@ -0,0 +1,84 @@
+/**
+ * One language server, spawned and supervised over stdio.
+ *
+ * Owns the JSON-RPC connection, the initialize handshake and
+ * the open-document set, and pulls diagnostics on demand.
+ * Positions cross the boundary here: the tool's
+ * byte columns convert to LSP's UTF-16 columns on the way in
+ * and back on the way out.
+ */
+import type { ServerConfig } from "../config.js";
+import type { CodeAction, Diagnostic, HoverInfo, LspLocation, LspRange, LspTarget, SymbolInfo, WorkspaceEdit } from "../types.js";
+/** A live server connection rooted at one project directory. */
+export declare class StandaloneServer {
+    readonly serverName: string;
+    readonly root: string;
+    private readonly child;
+    private readonly connection;
+    private readonly openDocs;
+    private readonly lineCache;
+    private readonly diagnostics;
+    private readonly diagWaiters;
+    private pullSupported;
+    private version;
+    private constructor();
+    /** Spawn a server, run the initialize handshake and return it ready. */
+    static start(config: ServerConfig, root: string, binaryPath: string): Promise<StandaloneServer>;
+    /** Problems the server reports against the file's current bytes. */
+    diagnose(path: string): Promise<Diagnostic[]>;
+    /** Where the symbol under the target is defined. */
+    definition(target: LspTarget): Promise<LspLocation[]>;
+    /** Every reference to the symbol under the target. */
+    references(target: LspTarget): Promise<LspLocation[]>;
+    /** Documentation for the symbol under the target, or null. */
+    hover(target: LspTarget): Promise<HoverInfo | null>;
+    /** Symbols declared in one file. */
+    documentSymbols(path: string): Promise<SymbolInfo[]>;
+    /** Symbols across the project matching a query. */
+    workspaceSymbols(query: string): Promise<SymbolInfo[]>;
+    /** Rename the symbol under the target and apply the edits. */
+    rename(target: LspTarget, newName: string): Promise<WorkspaceEdit>;
+    /** Code actions the server offers for a file, optionally at a range. */
+    codeActions(path: string, range?: LspRange): Promise<CodeAction[]>;
+    /** Re-sync a document after the caller edited it, so diagnostics stay current. */
+    syncDocument(path: string, text: string): void;
+    /** Release the connection and kill the server process. */
+    dispose(): Promise<void>;
+    /**
+     * Open the target and wait for the server to finish building
+     * the project's program before a type-intelligence request.
+     * The server answers references and definition only across
+     * files in the loaded program. Both diagnostics modes signal
+     * that build: a pull resolves once the program is ready, and a
+     * push server publishes the file's first diagnostics then.
+     * Cached per file so warm requests skip the wait.
+     */
+    private ensureReady;
+    /**
+     * Pull the current diagnostics for a file. TypeScript 7's native
+     * LSP computes them on request and resolves once the program is
+     * built, so this both reports problems and gates readiness.
+     */
+    private pullDiagnostics;
+    /** Read the diagnostics a push server published, waiting for them to settle. */
+    private pushedDiagnostics;
+    /**
+     * Resolve once a push server's diagnostics for `uri` have gone
+     * quiet, or the hard timeout fires. The quiet window only starts
+     * after the first publish, so a server slower than the window is
+     * still caught, while the timeout bounds one that never speaks.
+     */
+    private settleDiagnostics;
+    private ensureOpen;
+    private linesFor;
+    private toDiagnostic;
+    /**
+     * Apply a protocol workspace edit to disk, updating caches
+     * and re-syncing open documents, and return what changed in
+     * tool coordinates.
+     */
+    private applyWorkspaceEdit;
+    private fromSymbolInformation;
+    private flattenDocumentSymbol;
+    private toLocations;
+}