one-code-extension 0.1.4 → 0.3.1

package/extensions/lsp/plugin-servers.ts

@@ -0,0 +1,331 @@
+/**
+ * Plugin-provided LSP server configs (pure).
+ *
+ * The way Claude Code supports language servers: a plugin ships either a
+ * `.lsp.json` in its root (`{"<server>": {command, extensionToLanguage, ...}}`)
+ * or an `lspServers` field in `.claude-plugin/plugin.json` (a relative path to
+ * such a JSON file, an inline record, or an array mixing both — manifest
+ * entries win on server-name collision). Servers are named
+ * `plugin:<plugin>:<server>` and routed by file extension via their required
+ * `extensionToLanguage` map; there is no root-marker walk for plugin servers
+ * (the built-in table in servers.ts keeps that) — they root at
+ * `workspaceFolder ?? cwd`.
+ *
+ * `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${VAR}` and
+ * `${VAR:-default}` are substituted in `command`, each `args` element, `env`
+ * values, and `workspaceFolder` — never inside `settings` or
+ * `initializationOptions`, which pass through verbatim. `${user_config.*}`
+ * (plugin user-config prompts) is not supported: a server using it is rejected
+ * with a named diagnostic rather than spawned with a live placeholder.
+ *
+ * Unsupported config fields are rejected loudly per repo convention:
+ * `transport: "socket"`, `shutdownTimeout`, `restartOnCrash`, `maxRestarts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { pathWithinBase, sanitizePathSegment } from "../lib/plugin-root.ts";
+
+export interface ResolvedPluginServer {
+	/** `plugin:<pluginName>:<serverName>` — the client-map key. */
+	key: string;
+	pluginName: string;
+	serverName: string;
+	/** Normalized `.ext` (lowercase, leading dot) → LSP languageId. */
+	languageByExtension: Record<string, string>;
+	command: string;
+	args: string[];
+	/** Fully substituted; includes CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA. */
+	env: Record<string, string>;
+	/** The `${CLAUDE_PLUGIN_DATA}` directory — wiring mkdirs it before spawn. */
+	dataDir: string;
+	workspaceFolder?: string;
+	initializationOptions?: unknown;
+	settings?: unknown;
+	startupTimeoutMs?: number;
+}
+
+export interface PluginServerSource {
+	name: string;
+	path: string;
+	/** Per-origin plugin-data base dir (Plugin.dataRoot from lib/plugins.ts). */
+	dataRoot: string;
+}
+
+export function pluginDataDir(dataRoot: string, pluginName: string): string {
+	return join(dataRoot, sanitizePathSegment(pluginName));
+}
+
+/** Resolve a manifest-declared relative path, or undefined when it escapes the plugin dir. */
+export function resolveWithinPlugin(pluginPath: string, relativePath: string): string | undefined {
+	return pathWithinBase(pluginPath, relativePath) ? resolve(pluginPath, relativePath) : undefined;
+}
+
+interface SubstitutionContext {
+	pluginRootDir: string;
+	dataDir: string;
+	env: Record<string, string | undefined>;
+}
+
+interface SubstitutionResult {
+	value: string;
+	/** `${user_config.*}` seen — the whole server must be rejected. */
+	userConfig: boolean;
+	/** Env vars that had no value and no default (left literal). */
+	missing: string[];
+}
+
+const PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_.]*)(?::-([^}]*))?\}/g;
+
+export function substitute(value: string, ctx: SubstitutionContext): SubstitutionResult {
+	let userConfig = false;
+	const missing: string[] = [];
+	const result = value.replace(PLACEHOLDER, (literal, name: string, fallback: string | undefined) => {
+		if (name === "CLAUDE_PLUGIN_ROOT") return ctx.pluginRootDir;
+		if (name === "CLAUDE_PLUGIN_DATA") return ctx.dataDir;
+		if (name.startsWith("user_config.")) {
+			userConfig = true;
+			return literal;
+		}
+		const env = ctx.env[name];
+		if (env !== undefined) return env;
+		if (fallback !== undefined) return fallback;
+		missing.push(name);
+		return literal;
+	});
+	return { value: result, userConfig, missing };
+}
+
+/** Raw server configs gathered from one plugin's sources, manifest winning. */
+export function collectRawServers(
+	plugin: Pick<PluginServerSource, "name" | "path">,
+	lspConfigPath: string | undefined,
+	manifestLspServers: unknown,
+	diagnostics: string[],
+): Record<string, unknown> {
+	const servers: Record<string, unknown> = {};
+
+	const mergeRecord = (raw: unknown, sourceLabel: string) => {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+			diagnostics.push(`${plugin.name}: ${sourceLabel} must be a JSON object mapping server names to configs`);
+			return;
+		}
+		Object.assign(servers, raw as Record<string, unknown>);
+	};
+
+	const mergeFile = (path: string, sourceLabel: string) => {
+		let raw: string;
+		try {
+			raw = readFileSync(path, "utf-8");
+		} catch (error) {
+			diagnostics.push(`${plugin.name}: could not read ${sourceLabel} (${(error as Error).message})`);
+			return;
+		}
+		try {
+			mergeRecord(JSON.parse(raw), sourceLabel);
+		} catch (error) {
+			diagnostics.push(`${plugin.name}: invalid JSON in ${sourceLabel} (${(error as Error).message})`);
+		}
+	};
+
+	if (lspConfigPath) mergeFile(lspConfigPath, ".lsp.json");
+
+	const mergeManifestEntry = (entry: unknown) => {
+		if (typeof entry === "string") {
+			const resolved = resolveWithinPlugin(plugin.path, entry);
+			if (!resolved) {
+				diagnostics.push(`${plugin.name}: manifest lspServers path "${entry}" escapes the plugin directory — rejected`);
+				return;
+			}
+			mergeFile(resolved, `manifest lspServers file "${entry}"`);
+			return;
+		}
+		mergeRecord(entry, "manifest lspServers");
+	};
+
+	if (manifestLspServers !== undefined) {
+		if (Array.isArray(manifestLspServers)) for (const entry of manifestLspServers) mergeManifestEntry(entry);
+		else mergeManifestEntry(manifestLspServers);
+	}
+
+	return servers;
+}
+
+/** The manifest's raw `lspServers` value, read directly off plugin.json. */
+export function readManifestLspServers(pluginPath: string): unknown {
+	let raw: string;
+	try {
+		raw = readFileSync(join(pluginPath, ".claude-plugin", "plugin.json"), "utf-8");
+	} catch {
+		return undefined;
+	}
+	try {
+		return (JSON.parse(raw) as { lspServers?: unknown }).lspServers;
+	} catch {
+		return undefined;
+	}
+}
+
+const UNSUPPORTED_FIELDS = ["shutdownTimeout", "restartOnCrash", "maxRestarts"] as const;
+
+/**
+ * Validate + substitute one server config. Returns undefined (with the reason
+ * pushed to `diagnostics`) rather than producing a spawnable-but-wrong config.
+ */
+export function resolveServerConfig(
+	plugin: PluginServerSource,
+	serverName: string,
+	raw: unknown,
+	env: Record<string, string | undefined>,
+	diagnostics: string[],
+): ResolvedPluginServer | undefined {
+	const label = `${plugin.name}:${serverName}`;
+	const reject = (reason: string): undefined => {
+		diagnostics.push(`${label}: ${reason} — server skipped`);
+		return undefined;
+	};
+
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return reject("config must be an object");
+	const config = raw as Record<string, unknown>;
+
+	for (const field of UNSUPPORTED_FIELDS) {
+		if (config[field] !== undefined) return reject(`"${field}" is not supported`);
+	}
+	if (config.transport !== undefined && config.transport !== "stdio") {
+		return reject(`transport "${String(config.transport)}" is not supported (stdio only)`);
+	}
+
+	if (typeof config.command !== "string" || config.command.length === 0) {
+		return reject('"command" must be a non-empty string');
+	}
+	if (config.command.includes(" ") && !config.command.startsWith("/")) {
+		return reject('"command" must not contain spaces — use the args array for arguments');
+	}
+
+	const extRaw = config.extensionToLanguage;
+	if (extRaw === null || typeof extRaw !== "object" || Array.isArray(extRaw)) {
+		return reject('"extensionToLanguage" (extension → language id map) is required');
+	}
+	const languageByExtension: Record<string, string> = {};
+	for (const [ext, languageId] of Object.entries(extRaw as Record<string, unknown>)) {
+		if (typeof languageId !== "string" || languageId.length === 0) {
+			return reject(`extensionToLanguage["${ext}"] must be a non-empty language id`);
+		}
+		const normalized = (ext.startsWith(".") ? ext : `.${ext}`).toLowerCase();
+		languageByExtension[normalized] = languageId;
+	}
+	if (Object.keys(languageByExtension).length === 0) {
+		return reject('"extensionToLanguage" must have at least one mapping');
+	}
+
+	if (config.args !== undefined && (!Array.isArray(config.args) || config.args.some((a) => typeof a !== "string"))) {
+		return reject('"args" must be an array of strings');
+	}
+	if (config.startupTimeout !== undefined && (typeof config.startupTimeout !== "number" || config.startupTimeout <= 0)) {
+		return reject('"startupTimeout" must be a positive number of milliseconds');
+	}
+	if (config.workspaceFolder !== undefined && typeof config.workspaceFolder !== "string") {
+		return reject('"workspaceFolder" must be a string');
+	}
+	if (
+		config.env !== undefined &&
+		(config.env === null || typeof config.env !== "object" || Array.isArray(config.env) ||
+			Object.values(config.env as Record<string, unknown>).some((v) => typeof v !== "string"))
+	) {
+		return reject('"env" must be a map of string values');
+	}
+
+	const dataDir = pluginDataDir(plugin.dataRoot, plugin.name);
+	const ctx: SubstitutionContext = { pluginRootDir: plugin.path, dataDir, env };
+	const missing = new Set<string>();
+	let sawUserConfig = false;
+	const sub = (value: string): string => {
+		const result = substitute(value, ctx);
+		if (result.userConfig) sawUserConfig = true;
+		for (const name of result.missing) missing.add(name);
+		return result.value;
+	};
+
+	const command = sub(config.command);
+	const args = ((config.args as string[] | undefined) ?? []).map(sub);
+	const substitutedEnv: Record<string, string> = {};
+	for (const [key, value] of Object.entries((config.env as Record<string, string> | undefined) ?? {})) {
+		substitutedEnv[key] = sub(value);
+	}
+	const workspaceFolder = typeof config.workspaceFolder === "string" ? sub(config.workspaceFolder) : undefined;
+
+	if (sawUserConfig) {
+		return reject("${user_config.*} placeholders are not supported (plugin user-config prompts are not implemented)");
+	}
+	if (missing.size > 0) {
+		diagnostics.push(`${label}: environment variable${missing.size === 1 ? "" : "s"} not set: ${[...missing].join(", ")} (left as-is)`);
+	}
+	if (command.includes("${")) {
+		return reject(`command still contains an unresolved placeholder after substitution ("${command}")`);
+	}
+
+	return {
+		key: `plugin:${plugin.name}:${serverName}`,
+		pluginName: plugin.name,
+		serverName,
+		languageByExtension,
+		command,
+		args,
+		env: { CLAUDE_PLUGIN_ROOT: plugin.path, CLAUDE_PLUGIN_DATA: dataDir, ...substitutedEnv },
+		dataDir,
+		workspaceFolder,
+		initializationOptions: config.initializationOptions,
+		settings: config.settings,
+		startupTimeoutMs: config.startupTimeout as number | undefined,
+	};
+}
+
+/** Everything one plugin contributes, resolved and substituted. */
+export function resolvePluginServers(
+	plugin: PluginServerSource,
+	lspConfigPath: string | undefined,
+	manifestLspServers: unknown,
+	env: Record<string, string | undefined>,
+): { servers: ResolvedPluginServer[]; diagnostics: string[] } {
+	const diagnostics: string[] = [];
+	const raw = collectRawServers(plugin, lspConfigPath, manifestLspServers, diagnostics);
+	const servers: ResolvedPluginServer[] = [];
+	for (const [serverName, config] of Object.entries(raw)) {
+		const resolved = resolveServerConfig(plugin, serverName, config, env, diagnostics);
+		if (resolved) servers.push(resolved);
+	}
+	return { servers, diagnostics };
+}
+
+export interface ExtensionRouting {
+	byExtension: Map<string, ResolvedPluginServer>;
+	collisions: string[];
+}
+
+/**
+ * Extension → server routing across all plugins. Deterministic on collision:
+ * servers sorted by plugin then server name, first claim wins, the loser is
+ * recorded for /lsp and a one-time notify.
+ */
+export function resolveExtensionRouting(servers: ResolvedPluginServer[]): ExtensionRouting {
+	const sorted = [...servers].sort((a, b) => a.key.localeCompare(b.key));
+	const byExtension = new Map<string, ResolvedPluginServer>();
+	const collisions: string[] = [];
+	for (const server of sorted) {
+		for (const ext of Object.keys(server.languageByExtension)) {
+			const holder = byExtension.get(ext);
+			if (holder) {
+				collisions.push(`${ext}: ${server.key} ignored (${holder.key} claimed it first)`);
+				continue;
+			}
+			byExtension.set(ext, server);
+		}
+	}
+	return { byExtension, collisions };
+}
+
+/** LanguageId a plugin server uses for a path (routing already matched it). */
+export function pluginLanguageId(server: ResolvedPluginServer, path: string): string {
+	const ext = extname(path).toLowerCase();
+	return server.languageByExtension[ext] ?? Object.values(server.languageByExtension)[0];
+}

package/extensions/lsp/watcher.ts

@@ -0,0 +1,157 @@
+/**
+ * Session-wide new-diagnostics delta (pure).
+ *
+ * The way Claude Code surfaces language-server feedback: every diagnostic the
+ * servers have published is diffed against a delivered-set, and only genuinely
+ * new ones are injected into the conversation — cross-file (an edit to one
+ * file surfaces the dependents it broke), all severities, deduplicated by
+ * content so an unchanged diagnostic is never repeated. Editing a file clears
+ * its delivered-set, so an issue that was fixed and reintroduced resurfaces.
+ *
+ * Caps match Claude Code's: 10 diagnostics per file, 30 total, 4000 chars,
+ * errors surviving truncation first; the delivered-set is bounded to the 500
+ * most-recently-touched files.
+ *
+ * One deliberate divergence: file headers are cwd-relative paths, not
+ * basenames — two files with the same basename would otherwise be
+ * indistinguishable in one block (docs/decisions/lsp.md).
+ */
+
+import { relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type LspDiagnostic, severitySymbol } from "./format.ts";
+
+export const MAX_PER_FILE = 10;
+export const MAX_TOTAL = 30;
+export const MAX_CHARS = 4000;
+const MAX_TRACKED_FILES = 500;
+
+/** Content identity of one diagnostic — stable across repeated publishes. */
+export function fingerprintDiagnostic(d: LspDiagnostic): string {
+	return JSON.stringify({
+		m: d.message,
+		s: d.severity ?? null,
+		r: d.range,
+		o: d.source ?? null,
+		c: d.code ?? null,
+	});
+}
+
+/**
+ * Per-file delivered fingerprints, LRU-bounded by file count. Insertion order
+ * doubles as recency: touching a file re-inserts it at the back.
+ */
+export class DeliveredTracker {
+	private files = new Map<string, Set<string>>();
+
+	constructor(private readonly maxFiles = MAX_TRACKED_FILES) {}
+
+	/** Forget a file (called when it is edited) so its issues can resurface. */
+	clear(uri: string): void {
+		this.files.delete(uri);
+	}
+
+	delivered(uri: string): Set<string> | undefined {
+		return this.files.get(uri);
+	}
+
+	markDelivered(uri: string, fingerprints: Iterable<string>): void {
+		const existing = this.files.get(uri) ?? new Set<string>();
+		this.files.delete(uri); // re-insert at the back = most recently touched
+		for (const fp of fingerprints) existing.add(fp);
+		this.files.set(uri, existing);
+		while (this.files.size > this.maxFiles) {
+			const oldest = this.files.keys().next().value;
+			if (oldest === undefined) break;
+			this.files.delete(oldest);
+		}
+	}
+}
+
+/**
+ * Diagnostics not yet delivered, per uri. Pure read — nothing is committed
+ * until `markDelivered(delta, tracker)` after a successful send.
+ */
+export function computeDelta(
+	all: Map<string, LspDiagnostic[]>,
+	tracker: DeliveredTracker,
+): Map<string, LspDiagnostic[]> {
+	const delta = new Map<string, LspDiagnostic[]>();
+	for (const [uri, diagnostics] of all) {
+		if (diagnostics.length === 0) continue;
+		const seen = tracker.delivered(uri);
+		const fresh = seen ? diagnostics.filter((d) => !seen.has(fingerprintDiagnostic(d))) : diagnostics;
+		if (fresh.length > 0) delta.set(uri, fresh);
+	}
+	return delta;
+}
+
+export function markDelivered(delta: Map<string, LspDiagnostic[]>, tracker: DeliveredTracker): void {
+	for (const [uri, diagnostics] of delta) {
+		tracker.markDelivered(uri, diagnostics.map(fingerprintDiagnostic));
+	}
+}
+
+function entryLine(d: LspDiagnostic): string {
+	const line = d.range.start.line + 1;
+	const column = d.range.start.character + 1;
+	const code = d.code !== undefined ? ` [${d.code}]` : "";
+	const source = d.source ? ` (${d.source})` : "";
+	return `  ${severitySymbol(d.severity)} [Line ${line}:${column}] ${d.message}${code}${source}`;
+}
+
+function displayPath(uri: string, cwd: string): string {
+	let path = uri;
+	try {
+		path = fileURLToPath(uri);
+	} catch {
+		// Not a file uri; show it verbatim.
+	}
+	return relative(cwd, path) || path;
+}
+
+/**
+ * The `<new-diagnostics>` block, or undefined for an empty delta. Layout:
+ * opening tag runs straight into the preamble, one blank line before the
+ * first file section and between sections, entries two-space indented.
+ */
+export function formatNewDiagnostics(delta: Map<string, LspDiagnostic[]>, cwd: string): string | undefined {
+	if (delta.size === 0) return undefined;
+
+	interface FileSection {
+		path: string;
+		diagnostics: LspDiagnostic[];
+		omitted: number;
+		worst: number;
+	}
+
+	const total = [...delta.values()].reduce((n, list) => n + list.length, 0);
+	const sections: FileSection[] = [...delta.entries()].map(([uri, list]) => {
+		const sorted = [...list].sort((a, b) => (a.severity ?? 1) - (b.severity ?? 1));
+		const kept = sorted.slice(0, MAX_PER_FILE);
+		return {
+			path: displayPath(uri, cwd),
+			diagnostics: kept,
+			omitted: sorted.length - kept.length,
+			worst: kept[0]?.severity ?? 1,
+		};
+	});
+	sections.sort((a, b) => a.worst - b.worst || a.path.localeCompare(b.path));
+
+	const parts: string[] = [];
+	let included = 0;
+	for (const section of sections) {
+		if (included >= MAX_TOTAL) break;
+		const room = MAX_TOTAL - included;
+		const kept = section.diagnostics.slice(0, room);
+		included += kept.length;
+		parts.push(`${section.path}:\n${kept.map(entryLine).join("\n")}`);
+	}
+	const omitted = total - included;
+	if (omitted > 0) parts.push(`… ${omitted} more`);
+
+	let body = parts.join("\n\n");
+	if (body.length > MAX_CHARS) body = `${body.slice(0, MAX_CHARS)}…[truncated]`;
+
+	return `<new-diagnostics>The following new diagnostic issues were detected:\n\n${body}\n</new-diagnostics>`;
+}

package/extensions/mcp/announce.ts

@@ -0,0 +1,99 @@
+/**
+ * What to tell the model when MCP state changes after the first request (pure).
+ *
+ * The MCP instructions and failed-servers reminders are `first-prepend` blocks
+ * on message 1. Before the first request they are simply (re)written; after it
+ * message 1 is part of every request's cached prefix, so they are FROZEN and
+ * changes ride one-shot notices where the model reads next (same rule as the
+ * deferred-tools listing, tool-search/announce.ts). `McpAnnounced` records what
+ * the model has been told; `mcpDelta` compares it with the live state.
+ */
+
+import { mcpFailuresReminder, mcpInstructionsReminder } from "./client.ts";
+
+export interface McpAnnounced {
+	/** Servers whose instructions the model has been given, with the text it saw. */
+	instructed: Map<string, string>;
+	/** Servers the model has been told failed, with the error it saw. */
+	failed: Map<string, string>;
+}
+
+export interface McpSnapshot {
+	connected: Array<{ name: string; instructions?: string }>;
+	failed: Array<{ name: string; error: string }>;
+}
+
+export interface McpDelta {
+	/** Connected servers whose instructions the model has not seen (a new server, or new text after a reconnect). */
+	newInstructions: Array<{ name: string; instructions: string }>;
+	/** Failures the model has not been told about (a new server, or a new error). */
+	newFailures: Array<{ name: string; error: string }>;
+	/** Servers the model was told had failed that are connected now. */
+	recovered: string[];
+	/** Servers whose instructions the model saw that are no longer connected and not reported failed. */
+	dropped: string[];
+}
+
+export function emptyAnnounced(): McpAnnounced {
+	return { instructed: new Map(), failed: new Map() };
+}
+
+/** What message 1 says after it was (re)written from `snapshot`, before the first request. */
+export function announcedFrom(snapshot: McpSnapshot): McpAnnounced {
+	return {
+		instructed: new Map(
+			snapshot.connected.filter((c) => c.instructions).map((c) => [c.name, c.instructions as string]),
+		),
+		failed: new Map(snapshot.failed.map((f) => [f.name, f.error])),
+	};
+}
+
+export function mcpDelta(announced: McpAnnounced, snapshot: McpSnapshot): McpDelta {
+	const connectedNames = new Set(snapshot.connected.map((c) => c.name));
+	const failedNames = new Set(snapshot.failed.map((f) => f.name));
+	return {
+		newInstructions: snapshot.connected
+			.filter((c) => c.instructions && announced.instructed.get(c.name) !== c.instructions)
+			.map((c) => ({ name: c.name, instructions: c.instructions as string })),
+		newFailures: snapshot.failed.filter((f) => announced.failed.get(f.name) !== f.error),
+		recovered: [...announced.failed.keys()].filter((name) => connectedNames.has(name)),
+		dropped: [...announced.instructed.keys()].filter((name) => !connectedNames.has(name) && !failedNames.has(name)),
+	};
+}
+
+export function applyMcpDelta(announced: McpAnnounced, delta: McpDelta): void {
+	for (const s of delta.newInstructions) announced.instructed.set(s.name, s.instructions);
+	for (const f of delta.newFailures) announced.failed.set(f.name, f.error);
+	for (const name of delta.recovered) announced.failed.delete(name);
+	for (const name of delta.dropped) announced.instructed.delete(name);
+}
+
+/** One-shot notice texts for a delta, in the order they should be queued. Empty when nothing changed. */
+export function mcpChangeNotices(delta: McpDelta): string[] {
+	const notices: string[] = [];
+	if (delta.recovered.length > 0) {
+		notices.push(
+			`MCP server${delta.recovered.length === 1 ? "" : "s"} ${delta.recovered.join(", ")} ` +
+				"connected after this conversation started (an earlier notice reported a connection failure). " +
+				"The server's tools are available as deferred tools — load them with tool_search.",
+		);
+	}
+	if (delta.newInstructions.length > 0) {
+		const names = delta.newInstructions.map((s) => s.name);
+		notices.push(
+			`MCP server${names.length === 1 ? "" : "s"} ${names.join(", ")} connected after this conversation started; ` +
+				"the tools are available as deferred tools (load with tool_search). Server instructions:\n\n" +
+				mcpInstructionsReminder(delta.newInstructions.map((s) => ({ server: { name: s.name }, instructions: s.instructions }))),
+		);
+	}
+	if (delta.newFailures.length > 0) {
+		notices.push(mcpFailuresReminder(delta.newFailures));
+	}
+	if (delta.dropped.length > 0) {
+		notices.push(
+			`MCP server${delta.dropped.length === 1 ? "" : "s"} ${delta.dropped.join(", ")} disconnected; ` +
+				'their tools answer "not connected" until the server is reconnected (the user can do that in /mcp).',
+		);
+	}
+	return notices;
+}