one-code-extension 0.1.0

package/extensions/lsp/client.ts

@@ -0,0 +1,278 @@
+/**
+ * Minimal LSP client: spawn a server, sync file contents, collect diagnostics.
+ *
+ * Deliberately small — this exists to answer one question ("what does the
+ * language server say about this file right now?"), not to expose LSP.
+ *
+ * Design points that address the fragility of the package this replaces:
+ * - No dependencies, so no transitive protocol-version conflicts.
+ * - Content is pushed with didOpen/didChange before every diagnostics read, so
+ *   the answer reflects the file on disk even if the edit was the session's
+ *   first action.
+ * - `waitForDiagnostics` awaits the next publish for that document instead of
+ *   sleeping a fixed interval, with a timeout and a last-known fallback.
+ * - Child handles are unref'd and shut down explicitly, so a one-shot `pi -p`
+ *   run still exits.
+ */
+
+import { type ChildProcess, spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import type { LspDiagnostic } from "./format.ts";
+import { createReaderState, encodeMessage, type JsonRpcMessage, readMessages } from "./protocol.ts";
+import type { ServerConfig } from "./servers.ts";
+
+const INITIALIZE_TIMEOUT_MS = 15_000;
+const DIAGNOSTICS_TIMEOUT_MS = 6_000;
+
+export function pathToUri(path: string): string {
+	return pathToFileURL(path).toString();
+}
+
+function unrefStream(stream: unknown): void {
+	(stream as { unref?: () => void } | null | undefined)?.unref?.();
+}
+
+interface OpenDocument {
+	version: number;
+	text: string;
+}
+
+export class LspClient {
+	private child?: ChildProcess;
+	private reader = createReaderState();
+	private nextId = 1;
+	private pending = new Map<number, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+	private diagnostics = new Map<string, LspDiagnostic[]>();
+	private waiters = new Map<string, Array<() => void>>();
+	private open = new Map<string, OpenDocument>();
+	private ready = false;
+	private failure?: string;
+
+	constructor(
+		readonly languageId: string,
+		private readonly config: ServerConfig,
+		private readonly root: string,
+	) {}
+
+	get isRunning(): boolean {
+		return this.ready && !!this.child && this.child.exitCode === null;
+	}
+
+	get error(): string | undefined {
+		return this.failure;
+	}
+
+	get diagnosticsCount(): number {
+		let total = 0;
+		for (const list of this.diagnostics.values()) total += list.length;
+		return total;
+	}
+
+	async start(): Promise<void> {
+		if (this.child) return;
+
+		const child = spawn(this.config.command, this.config.args, {
+			cwd: this.root,
+			stdio: ["pipe", "pipe", "pipe"],
+			env: process.env,
+		});
+		this.child = child;
+
+		// Don't hold the event loop open once the agent is done. The stdio pipes
+		// are sockets at runtime, so they carry unref() even though the stream
+		// types don't declare it.
+		child.unref();
+		unrefStream(child.stdout);
+		unrefStream(child.stderr);
+		unrefStream(child.stdin);
+
+		let stderr = "";
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr = (stderr + chunk.toString()).slice(-2000);
+		});
+		child.stdout?.on("data", (chunk: Buffer) => {
+			for (const message of readMessages(this.reader, chunk)) this.handle(message);
+		});
+		child.on("error", (error) => {
+			this.failure = `Could not start ${this.config.command}: ${error.message}`;
+			this.rejectAll(new Error(this.failure));
+		});
+		child.on("exit", (code, signal) => {
+			this.ready = false;
+			if (!this.failure && code !== 0) {
+				const detail = stderr.trim().split("\n").slice(-3).join(" ");
+				this.failure = `${this.config.command} exited (${signal ?? `code ${code}`})${detail ? `: ${detail}` : ""}`;
+			}
+			this.rejectAll(new Error(this.failure ?? "language server exited"));
+		});
+
+		await this.request(
+			"initialize",
+			{
+				processId: process.pid,
+				rootUri: pathToUri(this.root),
+				workspaceFolders: [{ uri: pathToUri(this.root), name: "workspace" }],
+				capabilities: {
+					textDocument: {
+						synchronization: { dynamicRegistration: false, didSave: false },
+						publishDiagnostics: { relatedInformation: false },
+					},
+					workspace: { workspaceFolders: true, configuration: true },
+				},
+			},
+			INITIALIZE_TIMEOUT_MS,
+		);
+
+		this.notify("initialized", {});
+		this.ready = true;
+	}
+
+	private handle(message: JsonRpcMessage): void {
+		if (message.method === "textDocument/publishDiagnostics") {
+			const params = message.params as { uri: string; diagnostics: LspDiagnostic[] };
+			this.diagnostics.set(params.uri, params.diagnostics ?? []);
+			const waiting = this.waiters.get(params.uri);
+			if (waiting) {
+				this.waiters.delete(params.uri);
+				for (const resolve of waiting) resolve();
+			}
+			return;
+		}
+
+		// Requests from the server: answer the ones that block startup.
+		if (message.id !== undefined && message.method) {
+			const result = message.method === "workspace/configuration" ? [{}] : null;
+			this.send({ id: message.id, result });
+			return;
+		}
+
+		if (message.id !== undefined) {
+			const entry = this.pending.get(Number(message.id));
+			if (!entry) return;
+			this.pending.delete(Number(message.id));
+			if (message.error) entry.reject(new Error(message.error.message));
+			else entry.resolve(message.result);
+		}
+	}
+
+	private send(payload: Record<string, unknown>): void {
+		this.child?.stdin?.write(encodeMessage(payload));
+	}
+
+	private notify(method: string, params: unknown): void {
+		this.send({ method, params });
+	}
+
+	request(method: string, params: unknown, timeoutMs = DIAGNOSTICS_TIMEOUT_MS): Promise<unknown> {
+		const id = this.nextId++;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
+			timer.unref?.();
+			this.pending.set(id, {
+				resolve: (value) => {
+					clearTimeout(timer);
+					resolve(value);
+				},
+				reject: (error) => {
+					clearTimeout(timer);
+					reject(error);
+				},
+			});
+			this.send({ id, method, params });
+		});
+	}
+
+	private rejectAll(error: Error): void {
+		for (const [, entry] of this.pending) entry.reject(error);
+		this.pending.clear();
+		for (const [, waiting] of this.waiters) for (const resolve of waiting) resolve();
+		this.waiters.clear();
+	}
+
+	/** Push the file's current on-disk content and return its uri. */
+	syncFile(path: string): string {
+		const uri = pathToUri(path);
+		let text: string;
+		try {
+			text = readFileSync(path, "utf-8");
+		} catch {
+			return uri;
+		}
+
+		const existing = this.open.get(uri);
+		if (!existing) {
+			this.open.set(uri, { version: 1, text });
+			this.notify("textDocument/didOpen", {
+				textDocument: { uri, languageId: this.languageId, version: 1, text },
+			});
+		} else if (existing.text !== text) {
+			const version = existing.version + 1;
+			this.open.set(uri, { version, text });
+			this.notify("textDocument/didChange", {
+				textDocument: { uri, version },
+				contentChanges: [{ text }],
+			});
+		}
+		return uri;
+	}
+
+	/** Wait for the next publish for `uri`; resolves early if one already arrived. */
+	private waitForPublish(uri: string, timeoutMs: number): Promise<void> {
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => resolve(), timeoutMs);
+			timer.unref?.();
+			const list = this.waiters.get(uri) ?? [];
+			list.push(() => {
+				clearTimeout(timer);
+				resolve();
+			});
+			this.waiters.set(uri, list);
+		});
+	}
+
+	/**
+	 * Syncs the file, waits for the server's next diagnostics publication, and
+	 * returns what it reported. Servers publish asynchronously and some republish
+	 * nothing when a file is unchanged, hence the timeout plus last-known
+	 * fallback.
+	 */
+	async getDiagnostics(path: string, timeoutMs = DIAGNOSTICS_TIMEOUT_MS): Promise<LspDiagnostic[]> {
+		const uri = pathToUri(path);
+		const hadContent = this.open.get(uri)?.text;
+		const synced = this.syncFile(path);
+		const changed = this.open.get(uri)?.text !== hadContent;
+
+		if (changed || !this.diagnostics.has(synced)) {
+			await this.waitForPublish(synced, timeoutMs);
+		}
+		return this.diagnostics.get(synced) ?? [];
+	}
+
+	async stop(): Promise<void> {
+		const child = this.child;
+		if (!child) return;
+		this.child = undefined;
+		this.ready = false;
+		try {
+			this.send({ id: this.nextId++, method: "shutdown", params: null });
+			this.notify("exit", null);
+		} catch {
+			// Server may already be gone.
+		}
+		await new Promise<void>((resolve) => {
+			const timer = setTimeout(() => {
+				child.kill("SIGKILL");
+				resolve();
+			}, 1000);
+			timer.unref?.();
+			child.once("exit", () => {
+				clearTimeout(timer);
+				resolve();
+			});
+		});
+	}
+}

package/extensions/lsp/format.ts

@@ -0,0 +1,46 @@
+/**
+ * Diagnostic shaping for the model (pure).
+ */
+
+export interface LspDiagnostic {
+	range: { start: { line: number; character: number }; end?: { line: number; character: number } };
+	severity?: number;
+	code?: string | number;
+	source?: string;
+	message: string;
+}
+
+export type SeverityFilter = "error" | "warning" | "all";
+
+const SEVERITY_NAMES: Record<number, string> = { 1: "error", 2: "warning", 3: "info", 4: "hint" };
+
+export function severityName(severity: number | undefined): string {
+	return SEVERITY_NAMES[severity ?? 1] ?? "error";
+}
+
+export function filterDiagnostics(diagnostics: LspDiagnostic[], filter: SeverityFilter): LspDiagnostic[] {
+	if (filter === "all") return diagnostics;
+	const max = filter === "error" ? 1 : 2;
+	return diagnostics.filter((d) => (d.severity ?? 1) <= max);
+}
+
+/** One diagnostic as `path:line:col severity: message (code) [source]`, 1-indexed. */
+export function formatDiagnostic(relPath: string, diagnostic: LspDiagnostic): string {
+	const line = diagnostic.range.start.line + 1;
+	const column = diagnostic.range.start.character + 1;
+	const code = diagnostic.code !== undefined ? ` (${diagnostic.code})` : "";
+	const source = diagnostic.source ? ` [${diagnostic.source}]` : "";
+	return `${relPath}:${line}:${column} ${severityName(diagnostic.severity)}: ${diagnostic.message}${code}${source}`;
+}
+
+export function formatDiagnostics(relPath: string, diagnostics: LspDiagnostic[], limit = 20): string {
+	if (diagnostics.length === 0) return "No diagnostics.";
+	const shown = diagnostics.slice(0, limit).map((d) => formatDiagnostic(relPath, d));
+	const errors = diagnostics.filter((d) => (d.severity ?? 1) === 1).length;
+	const warnings = diagnostics.filter((d) => d.severity === 2).length;
+	const counts = [errors ? `${errors} error${errors === 1 ? "" : "s"}` : "", warnings ? `${warnings} warning${warnings === 1 ? "" : "s"}` : ""]
+		.filter(Boolean)
+		.join(", ");
+	const omitted = diagnostics.length > limit ? `\n… ${diagnostics.length - limit} more` : "";
+	return `${counts || `${diagnostics.length} diagnostics`}\n\n${shown.join("\n")}${omitted}`;
+}

package/extensions/lsp/index.ts

@@ -0,0 +1,193 @@
+/**
+ * lsp extension — Claude Code's post-edit diagnostics.
+ *
+ * Two behaviors, no more:
+ *  1. After a successful `edit` or `write`, error diagnostics for that file are
+ *     appended to the tool result, so the model immediately sees what it broke.
+ *  2. An `lsp_diagnostics` tool (deferred behind `tool_search`) for asking about
+ *     a file on demand.
+ *
+ * Claude Code has no other LSP tools; navigation goes through grep/find. Adding
+ * hover or definition later is a small `client.request(...)` call each, if the
+ * need appears.
+ */
+
+import { relative } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { DEFER_CHANNEL } from "../lib/deferred.ts";
+import { ccToolRenderers } from "../lib/tui-render.ts";
+import { LspClient } from "./client.ts";
+import { filterDiagnostics, formatDiagnostics, type SeverityFilter } from "./format.ts";
+import { findProjectRoot, serverForPath, typescriptPreflight } from "./servers.ts";
+
+/** Only errors are pushed unasked; warnings would be noise on every edit. */
+const AUTO_APPEND_LIMIT = 10;
+
+/** The (match, project root, client-map key) triple every entry point needs; undefined when the path has no configured server. */
+function resolveServer(
+	path: string,
+	cwd: string,
+): { match: NonNullable<ReturnType<typeof serverForPath>>; root: string; key: string } | undefined {
+	const match = serverForPath(path);
+	if (!match) return undefined;
+	const root = findProjectRoot(path, match.config.rootMarkers, cwd);
+	const key = `${match.languageId}:${root}`;
+	return { match, root, key };
+}
+
+export default function lspExtension(pi: ExtensionAPI) {
+	const clients = new Map<string, LspClient>();
+	const startFailures = new Map<string, string>();
+	const warned = new Set<string>();
+
+	const clientFor = async (path: string, cwd: string): Promise<LspClient | undefined> => {
+		const resolved = resolveServer(path, cwd);
+		if (!resolved) return undefined;
+		const { match, root, key } = resolved;
+
+		const failure = startFailures.get(key);
+		if (failure) return undefined;
+
+		const existing = clients.get(key);
+		if (existing?.isRunning) return existing;
+		if (existing) {
+			// Crashed mid-session. Record why so downstream reports the real cause
+			// (a server that was running and died) instead of falling through to
+			// "install <command>" advice for an already-installed server — and so
+			// the one-time post-edit warning still fires. Don't respawn in a loop.
+			startFailures.set(key, existing.error ?? "language server stopped unexpectedly");
+			return undefined;
+		}
+
+		if (match.languageId.startsWith("typescript") || match.languageId.startsWith("javascript")) {
+			const problem = typescriptPreflight(root);
+			if (problem) {
+				startFailures.set(key, problem);
+				return undefined;
+			}
+		}
+
+		const client = new LspClient(match.languageId, match.config, root);
+		clients.set(key, client);
+		try {
+			await client.start();
+			return client;
+		} catch (error) {
+			startFailures.set(key, client.error ?? (error as Error).message);
+			return undefined;
+		}
+	};
+
+	/** One-time notice per root so a missing server doesn't degrade silently. */
+	const reportFailureOnce = (path: string, cwd: string, notify: (message: string) => void) => {
+		const resolved = resolveServer(path, cwd);
+		if (!resolved) return;
+		const { match, key } = resolved;
+		const failure = startFailures.get(key);
+		if (failure && !warned.has(key)) {
+			warned.add(key);
+			// Server errors run to paragraphs; the transcript gets one line and
+			// /lsp keeps the full status.
+			const brief = failure.split("\n")[0].replace(/\s+/g, " ").trim();
+			const capped = brief.length > 100 ? `${brief.slice(0, 99)}…` : brief;
+			notify(`LSP unavailable for ${match.languageId}: ${capped} (/lsp for status)`);
+		}
+	};
+
+	pi.on("tool_result", async (event, ctx) => {
+		if (event.isError) return;
+		if (event.toolName !== "edit" && event.toolName !== "write") return;
+
+		const path = (event.input as { path?: unknown }).path;
+		if (typeof path !== "string") return;
+
+		const client = await clientFor(path, ctx.cwd);
+		if (!client) {
+			reportFailureOnce(path, ctx.cwd, (message) => {
+				if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			});
+			return;
+		}
+
+		const errors = filterDiagnostics(await client.getDiagnostics(path), "error");
+		if (errors.length === 0) return;
+
+		const relPath = relative(ctx.cwd, path) || path;
+		const summary = formatDiagnostics(relPath, errors, AUTO_APPEND_LIMIT);
+		const existing = event.content ?? [];
+		return {
+			content: [...existing, { type: "text", text: `\n<diagnostics>\n${summary}\n</diagnostics>` }],
+		};
+	});
+
+	pi.registerTool({
+		name: "lsp_diagnostics",
+		label: "Diagnostics",
+		...ccToolRenderers("Diagnostics"),
+		description:
+			"Ask the language server for diagnostics (type errors, warnings) on a file. Reflects the file's current contents. Supported: TypeScript/JavaScript, Python, Go, Rust, Java — when that language's server is installed.",
+		parameters: Type.Object({
+			path: Type.String({ description: "File to analyse (absolute or workspace-relative)" }),
+			severity: Type.Optional(
+				StringEnum(["error", "warning", "all"] as const, { description: "Minimum severity (default: all)" }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const path = params.path.startsWith("/") ? params.path : `${ctx.cwd}/${params.path}`;
+			const client = await clientFor(path, ctx.cwd);
+			if (!client) {
+				const resolved = resolveServer(path, ctx.cwd);
+				const match = resolved?.match;
+				const failure = resolved ? startFailures.get(resolved.key) : undefined;
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								failure ??
+								(match
+									? `No language server available for ${match.languageId}. Install ${match.config.command}.`
+									: `No language server is configured for this file type.`),
+						},
+					],
+					details: { available: false },
+					// A language was recognised but its server is unavailable/failed —
+					// that is an error, not a clean "no diagnostics". Only a genuinely
+					// unsupported filetype (no match) is a non-error outcome.
+					isError: Boolean(match),
+				};
+			}
+
+			const all = await client.getDiagnostics(path);
+			const filtered = filterDiagnostics(all, (params.severity ?? "all") as SeverityFilter);
+			const relPath = relative(ctx.cwd, path) || path;
+			return {
+				content: [{ type: "text", text: formatDiagnostics(relPath, filtered) }],
+				details: { count: filtered.length, languageId: client.languageId },
+			};
+		},
+	});
+
+	pi.registerCommand("lsp", {
+		description: "Show language server status",
+		handler: async (_args, ctx) => {
+			const lines = [...clients.entries()].map(
+				([key, client]) => `${client.isRunning ? "running" : "stopped"} ${key} (${client.diagnosticsCount} diagnostics)`,
+			);
+			for (const [key, failure] of startFailures) lines.push(`failed  ${key}: ${failure}`);
+			ctx.ui.notify(lines.length ? lines.join("\n") : "No language servers started.", "info");
+		},
+	});
+
+	pi.on("session_shutdown", async () => {
+		await Promise.all([...clients.values()].map((client) => client.stop()));
+		clients.clear();
+	});
+
+	pi.events.emit(DEFER_CHANNEL, {
+		name: "lsp_diagnostics",
+		keywords: ["diagnostics", "errors", "type error", "typecheck", "compile", "lint", "lsp"],
+	});
+}

package/extensions/lsp/protocol.ts

@@ -0,0 +1,64 @@
+/**
+ * LSP base protocol framing (pure).
+ *
+ * Messages are `Content-Length: <n>\r\n\r\n<n bytes of JSON>`. One chunk from a
+ * server's stdout may contain several messages, or half of one, so the reader
+ * keeps a buffer across calls.
+ */
+
+export interface JsonRpcMessage {
+	jsonrpc: "2.0";
+	id?: number | string;
+	method?: string;
+	params?: unknown;
+	result?: unknown;
+	error?: { code: number; message: string };
+}
+
+export function encodeMessage(message: Record<string, unknown>): Buffer {
+	const body = Buffer.from(JSON.stringify({ jsonrpc: "2.0", ...message }), "utf-8");
+	return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii"), body]);
+}
+
+export interface ReaderState {
+	buffer: Buffer;
+}
+
+export function createReaderState(): ReaderState {
+	return { buffer: Buffer.alloc(0) };
+}
+
+/**
+ * Appends a chunk and returns every complete message now available. Malformed
+ * headers are skipped rather than throwing, so one bad frame cannot wedge the
+ * stream.
+ */
+export function readMessages(state: ReaderState, chunk: Buffer): JsonRpcMessage[] {
+	state.buffer = state.buffer.length === 0 ? chunk : Buffer.concat([state.buffer, chunk]);
+	const messages: JsonRpcMessage[] = [];
+
+	while (true) {
+		const headerEnd = state.buffer.indexOf("\r\n\r\n");
+		if (headerEnd === -1) return messages;
+
+		const header = state.buffer.subarray(0, headerEnd).toString("ascii");
+		const match = header.match(/content-length:\s*(\d+)/i);
+		if (!match) {
+			// Unparseable header: drop it and resynchronise.
+			state.buffer = state.buffer.subarray(headerEnd + 4);
+			continue;
+		}
+
+		const length = Number(match[1]);
+		const bodyStart = headerEnd + 4;
+		if (state.buffer.length < bodyStart + length) return messages;
+
+		const body = state.buffer.subarray(bodyStart, bodyStart + length).toString("utf-8");
+		state.buffer = state.buffer.subarray(bodyStart + length);
+		try {
+			messages.push(JSON.parse(body) as JsonRpcMessage);
+		} catch {
+			// Ignore a body that isn't JSON; the stream stays aligned.
+		}
+	}
+}

package/extensions/lsp/servers.ts

@@ -0,0 +1,79 @@
+/**
+ * Language and server detection (pure).
+ *
+ * The server command table follows the one in the MIT-licensed
+ * `pi-lsp-extension` package, which is a good curated starting point.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+
+export interface ServerConfig {
+	command: string;
+	args: string[];
+	/** Files that mark the project root for this language. */
+	rootMarkers: string[];
+}
+
+const LANGUAGE_BY_EXTENSION: Record<string, string> = {
+	".ts": "typescript",
+	".tsx": "typescriptreact",
+	".mts": "typescript",
+	".cts": "typescript",
+	".js": "javascript",
+	".jsx": "javascriptreact",
+	".mjs": "javascript",
+	".cjs": "javascript",
+	".py": "python",
+	".pyi": "python",
+	".go": "go",
+	".rs": "rust",
+	".java": "java",
+};
+
+const TS_MARKERS = ["tsconfig.json", "jsconfig.json", "package.json"];
+
+export const SERVERS: Record<string, ServerConfig> = {
+	typescript: { command: "typescript-language-server", args: ["--stdio"], rootMarkers: TS_MARKERS },
+	typescriptreact: { command: "typescript-language-server", args: ["--stdio"], rootMarkers: TS_MARKERS },
+	javascript: { command: "typescript-language-server", args: ["--stdio"], rootMarkers: TS_MARKERS },
+	javascriptreact: { command: "typescript-language-server", args: ["--stdio"], rootMarkers: TS_MARKERS },
+	python: { command: "pyright-langserver", args: ["--stdio"], rootMarkers: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt"] },
+	go: { command: "gopls", args: ["serve"], rootMarkers: ["go.mod", "go.work"] },
+	rust: { command: "rust-analyzer", args: [], rootMarkers: ["Cargo.toml"] },
+	java: { command: "jdtls", args: [], rootMarkers: ["pom.xml", "build.gradle", "build.gradle.kts"] },
+};
+
+export function languageIdForPath(path: string): string | undefined {
+	return LANGUAGE_BY_EXTENSION[extname(path).toLowerCase()];
+}
+
+export function serverForPath(path: string): { languageId: string; config: ServerConfig } | undefined {
+	const languageId = languageIdForPath(path);
+	if (!languageId) return undefined;
+	const config = SERVERS[languageId];
+	return config ? { languageId, config } : undefined;
+}
+
+/** Nearest ancestor directory containing one of the language's root markers. */
+export function findProjectRoot(startPath: string, markers: string[], fallback: string): string {
+	let dir = dirname(startPath);
+	while (true) {
+		if (markers.some((marker) => existsSync(join(dir, marker)))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return fallback;
+		dir = parent;
+	}
+}
+
+/**
+ * TypeScript 7's native compiler dropped `lib/tsserver.js`, which
+ * typescript-language-server requires. Detect that up front so we can say so
+ * instead of reporting a mystery server failure.
+ */
+export function typescriptPreflight(root: string): string | undefined {
+	const localTypescript = join(root, "node_modules", "typescript");
+	if (!existsSync(localTypescript)) return undefined;
+	if (existsSync(join(localTypescript, "lib", "tsserver.js"))) return undefined;
+	return "The project's local TypeScript has no lib/tsserver.js (TypeScript 7's native compiler removed it), so typescript-language-server cannot analyse this project. Install typescript 5.x as a dev dependency for LSP diagnostics.";
+}