pi-lens 3.8.27 → 3.8.28

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [3.8.28] - 2026-04-19
+
+### Fixed
+- **Session startup no longer blocks the Node event loop** — tool availability probes (biome, ast-grep, ruff, knip, jscpd, madge) now run via async `ensureAvailable()` in a fire-and-forget IIFE instead of `setImmediate` + `spawnSync`, eliminating ~8–10 s of main-thread freeze on startup.
+- **Biome binary lookup extended** — `getBiomeBinary()` now checks `~/.pi-lens/tools/node_modules/.bin/biome` so the async probe finds the pre-installed binary without falling back to `npx`.
+- **CSS roots and Windows LSP shims tightened** — improved root resolution for CSS language server on Windows.
+- **Zig compile coverage kept active** — LSP availability check no longer incorrectly disables Zig compile diagnostics.
+- **Ruby LSP startup budgets relaxed** — reduced false-negative LSP attach failures on slower machines.
+- **Kotlin and Zig LSP availability improved** — more reliable server detection across platforms.
+- **Standalone Python and Ruby LSP roots fixed** — correct workspace root used when opening files outside a project directory.
+
 ## [3.8.27] - 2026-04-19
 
 ### Added

package/clients/biome-client.ts

@@ -9,6 +9,7 @@
  */
 
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { isFileKind } from "./file-kinds.js";
 import { safeSpawn, safeSpawnAsync } from "./safe-spawn.js";
@@ -60,16 +61,29 @@ export class BiomeClient {
 		if (this.localBinaryPath) return { cmd: this.localBinaryPath, args: [] };
 
 		// Walk up from cwd looking for node_modules/.bin/biome.
+		// Also check ~/.pi-lens/tools (where ensureTool("biome") auto-installs),
+		// so we avoid the ~1.5s `npx @biomejs/biome --version` fallback when
+		// the tool is already installed but not in the project's node_modules.
 		// On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
 		const isWin = process.platform === "win32";
+		const piLensBin = path.join(
+			os.homedir(),
+			".pi-lens",
+			"tools",
+			"node_modules",
+			".bin",
+		);
 		const candidates = isWin
 			? [
 					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
 					path.join(process.cwd(), "node_modules", ".bin", "biome"),
+					path.join(piLensBin, "biome.cmd"),
+					path.join(piLensBin, "biome"),
 				]
 			: [
 					path.join(process.cwd(), "node_modules", ".bin", "biome"),
 					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+					path.join(piLensBin, "biome"),
 				];
 		for (const p of candidates) {
 			if (fs.existsSync(p)) {

package/clients/installer/index.ts

@@ -524,6 +524,24 @@ const TOOLS: ToolDefinition[] = [
 			binaryInArchive: "terraform-ls",
 		},
 	},
+	{
+		id: "zls",
+		name: "zls",
+		checkCommand: "zls",
+		checkArgs: ["--version"],
+		installStrategy: "github",
+		binaryName: "zls",
+		github: {
+			repo: "zigtools/zls",
+			assetMatch: (platform, arch) => {
+				if (platform === "linux") return arch === "arm64" ? "aarch64-linux.tar.xz" : "x86_64-linux.tar.xz";
+				if (platform === "darwin") return arch === "arm64" ? "aarch64-macos.tar.xz" : "x86_64-macos.tar.xz";
+				if (platform === "win32") return arch === "arm64" ? "aarch64-windows.zip" : "x86_64-windows.zip";
+				return undefined;
+			},
+			binaryInArchive: "zls",
+		},
+	},
 ];
 
 const ensureInFlight = new Map<string, Promise<string | undefined>>();

package/clients/language-policy.ts

@@ -154,7 +154,7 @@ const PRIMARY_DISPATCH_GROUPS: Partial<Record<FileKind, RunnerGroup>> = {
 	swift: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["swift"] },
 	dart: { mode: "fallback", runnerIds: ["lsp", "dart-analyze"], filterKinds: ["dart"] },
 	lua: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["lua"] },
-	zig: { mode: "fallback", runnerIds: ["lsp", "zig-check"], filterKinds: ["zig"] },
+	zig: { mode: "all", runnerIds: ["lsp", "zig-check"], filterKinds: ["zig"] },
 	haskell: { mode: "fallback", runnerIds: ["lsp"], filterKinds: ["haskell"] },
 	elixir: { mode: "fallback", runnerIds: ["lsp", "elixir-check", "credo"], filterKinds: ["elixir"] },
 	gleam: { mode: "fallback", runnerIds: ["lsp", "gleam-check"], filterKinds: ["gleam"] },

package/clients/lsp/client.ts

@@ -561,10 +561,17 @@ export async function createLSPClient(options: {
 	process: LSPProcess;
 	root: string;
 	initialization?: Record<string, unknown>;
+	initializeTimeoutMs?: number;
 }): Promise<LSPClientInfo> {
 	installCrashGuard();
 
-	const { serverId, process: lspProcess, root, initialization } = options;
+	const {
+		serverId,
+		process: lspProcess,
+		root,
+		initialization,
+		initializeTimeoutMs = INITIALIZE_TIMEOUT_MS,
+	} = options;
 
 	const startupState: {
 		exitCode: number | null;
@@ -683,7 +690,7 @@ export async function createLSPClient(options: {
 				},
 				initializationOptions: initialization,
 			}),
-			INITIALIZE_TIMEOUT_MS,
+			initializeTimeoutMs,
 		);
 	} finally {
 		(lspProcess.stderr as NodeJS.ReadableStream).off("data", onStartupStderr);

package/clients/lsp/index.ts

@@ -133,8 +133,14 @@ export class LSPService {
 		filePath: string,
 		maxWaitMs?: number,
 	): Promise<SpawnedServer | undefined> {
-		const withBudget = async (): Promise<SpawnedServer | undefined> => {
 		const servers = getServersForFileWithConfig(filePath);
+		const serverWaitOverrideMs = servers.reduce(
+			(max, server) => Math.max(max, server.clientWaitTimeoutMs ?? 0),
+			0,
+		);
+		const effectiveMaxWaitMs = Math.max(maxWaitMs ?? 0, serverWaitOverrideMs);
+
+		const withBudget = async (): Promise<SpawnedServer | undefined> => {
 		if (servers.length === 0) return undefined;
 
 		// Try each matching server
@@ -169,14 +175,14 @@ export class LSPService {
 		return undefined;
 		};
 
-		if (!maxWaitMs || maxWaitMs <= 0) {
+		if (!effectiveMaxWaitMs || effectiveMaxWaitMs <= 0) {
 			return withBudget();
 		}
 
 		const timeoutResult = await Promise.race<SpawnedServer | undefined>([
 			withBudget(),
 			new Promise<undefined>((resolve) =>
-				setTimeout(() => resolve(undefined), maxWaitMs),
+				setTimeout(() => resolve(undefined), effectiveMaxWaitMs),
 			),
 		]);
 
@@ -185,9 +191,9 @@ export class LSPService {
 				type: "phase",
 				phase: "lsp_client_wait_timeout",
 				filePath,
-				durationMs: maxWaitMs,
+				durationMs: effectiveMaxWaitMs,
 				metadata: {
-					maxWaitMs,
+					maxWaitMs: effectiveMaxWaitMs,
 				},
 			});
 		}
@@ -315,6 +321,7 @@ export class LSPService {
 				process: spawned.process,
 				root,
 				initialization: spawned.initialization,
+				initializeTimeoutMs: server.initializeTimeoutMs,
 			});
 			const wsDiag =
 				typeof client.getWorkspaceDiagnosticsSupport === "function"

package/clients/lsp/server.ts

@@ -32,6 +32,17 @@ export interface LSPServerInfo {
 	name: string;
 	extensions: string[];
 	root: RootFunction;
+	/**
+	 * Optional per-server initialize timeout.
+	 * Useful for servers like Ruby LSP that do real project bootstrap work
+	 * before they can answer initialize.
+	 */
+	initializeTimeoutMs?: number;
+	/**
+	 * Optional per-server wait budget for navigation requests that need a client
+	 * to become ready first.
+	 */
+	clientWaitTimeoutMs?: number;
 	spawn(
 		root: string,
 		options?: LSPSpawnOptions,
@@ -285,15 +296,28 @@ function nodeBinCandidates(root: string, baseName: string): string[] {
 	if (process.platform === "win32") {
 		return [
 			`${localBase}.cmd`,
-			`${localBase}.ps1`,
 			`${localBase}.exe`,
-			localBase,
 			baseName,
 		];
 	}
 	return [localBase, baseName];
 }
 
+function normalizeRootKey(root: string): string {
+	return process.platform === "win32"
+		? path.resolve(root).toLowerCase()
+		: path.resolve(root);
+}
+
+function IgnoreHomeRoot(primary: RootFunction): RootFunction {
+	const homeKey = normalizeRootKey(os.homedir());
+	return async (file: string): Promise<string | undefined> => {
+		const root = await primary(file);
+		if (!root) return undefined;
+		return normalizeRootKey(root) === homeKey ? undefined : root;
+	};
+}
+
 function rubyBinCandidates(baseName: string): string[] {
 	const candidates: string[] = [];
 	const userProfile = process.env.USERPROFILE;
@@ -729,15 +753,17 @@ export const PythonServer: LSPServerInfo = {
 	id: "python",
 	name: "Pyright Language Server",
 	extensions: [".py", ".pyi"],
-	root: createRootDetector([
-		".git",
-		"pyproject.toml",
-		"setup.py",
-		"setup.cfg",
-		"requirements.txt",
-		"Pipfile",
-		"poetry.lock",
-	]),
+	root: RootWithFallback(
+		createRootDetector([
+			".git",
+			"pyproject.toml",
+			"setup.py",
+			"setup.cfg",
+			"requirements.txt",
+			"Pipfile",
+			"poetry.lock",
+		]),
+	),
 	async spawn(root, options) {
 		const path = await import("node:path");
 		const fs = await import("node:fs/promises");
@@ -838,15 +864,17 @@ export const PythonPylspServer: LSPServerInfo = {
 	id: "python-pylsp",
 	name: "Python LSP Server (pylsp)",
 	extensions: [".py", ".pyi"],
-	root: createRootDetector([
-		".git",
-		"pyproject.toml",
-		"setup.py",
-		"setup.cfg",
-		"requirements.txt",
-		"Pipfile",
-		"poetry.lock",
-	]),
+	root: RootWithFallback(
+		createRootDetector([
+			".git",
+			"pyproject.toml",
+			"setup.py",
+			"setup.cfg",
+			"requirements.txt",
+			"Pipfile",
+			"poetry.lock",
+		]),
+	),
 	async spawn(root) {
 		try {
 			const proc = await launchLSP("pylsp", [], { cwd: root });
@@ -909,7 +937,11 @@ export const RubyServer: LSPServerInfo = {
 	id: "ruby",
 	name: "Ruby LSP",
 	extensions: [".rb", ".rake", ".gemspec", ".ru"],
-	root: PriorityRoot([["Gemfile", ".ruby-version"], [".git"]]),
+	root: RootWithFallback(PriorityRoot([["Gemfile", ".ruby-version"], [".git"]])),
+	// Ruby LSP may need extra time to finish composed-bundle setup before it can
+	// answer initialize/documentSymbol on cold start.
+	initializeTimeoutMs: 30_000,
+	clientWaitTimeoutMs: 30_000,
 	async spawn(root, options) {
 		// Try ruby-lsp first, then solargraph, then rubocop --lsp
 		// Each has different args so we can't use a single resolveAndLaunch call
@@ -947,7 +979,7 @@ export const RubySolargraphServer: LSPServerInfo = {
 	id: "ruby-solargraph",
 	name: "Solargraph",
 	extensions: [".rb", ".rake", ".gemspec", ".ru"],
-	root: PriorityRoot([["Gemfile", ".ruby-version"], [".git"]]),
+	root: RootWithFallback(PriorityRoot([["Gemfile", ".ruby-version"], [".git"]])),
 	async spawn(root) {
 		for (const command of ["solargraph", ...rubyBinCandidates("solargraph")]) {
 			try {
@@ -1028,14 +1060,24 @@ export const JavaServer = createInteractiveServer({
 	command: () => process.env.JDTLS_PATH || "jdtls",
 });
 
-export const KotlinServer = createInteractiveServer({
+export const KotlinServer: LSPServerInfo = {
 	id: "kotlin",
 	name: "Kotlin Language Server",
 	extensions: [".kt", ".kts"],
 	root: RootWithFallback(createRootDetector(["build.gradle.kts", "build.gradle", "pom.xml"])),
-	language: "kotlin",
-	command: "kotlin-language-server",
-});
+	async spawn(root, options) {
+		// Prefer the newer official Kotlin LSP CLI when available, but keep
+		// compatibility with the older fwcd kotlin-language-server command.
+		return resolveAndLaunch(
+			{
+				candidates: ["kotlin-lsp", "kotlin-language-server"],
+				args: [],
+				cwd: root,
+			},
+			options?.allowInstall,
+		);
+	},
+};
 
 export const SwiftServer = createInteractiveServer({
 	id: "swift",
@@ -1080,14 +1122,23 @@ export const CppServer = createInteractiveServer({
 	args: ["--background-index"],
 });
 
-export const ZigServer = createInteractiveServer({
+export const ZigServer: LSPServerInfo = {
 	id: "zig",
 	name: "ZLS",
 	extensions: [".zig", ".zon"],
 	root: RootWithFallback(createRootDetector(["build.zig"])),
-	language: "zig",
-	command: "zls",
-});
+	spawn(root, options) {
+		return resolveAndLaunch(
+			{
+				candidates: ["zls"],
+				args: [],
+				cwd: root,
+				managedToolId: "zls",
+			},
+			options?.allowInstall,
+		);
+	},
+};
 
 export const HaskellServer = createInteractiveServer({
 	id: "haskell",
@@ -1230,7 +1281,9 @@ export const HtmlServer: LSPServerInfo = {
 	id: "html",
 	name: "VSCode HTML Language Server",
 	extensions: [".html", ".htm"],
-	root: PriorityRoot([["package.json", "index.html", "vite.config.ts"], [".git"]]),
+	root: RootWithFallback(
+		IgnoreHomeRoot(PriorityRoot([["package.json", "index.html", "vite.config.ts"]])),
+	),
 	spawn(root, options) {
 		return resolveAndLaunch(
 			{ candidates: nodeBinCandidates(root, "vscode-html-language-server"), args: ["--stdio"], cwd: root, managedToolId: "vscode-html-languageserver-bin" },
@@ -1334,7 +1387,11 @@ export const CssServer: LSPServerInfo = {
 	id: "css",
 	name: "CSS Language Server",
 	extensions: [".css", ".scss", ".sass", ".less"],
-	root: PriorityRoot([["package.json", "postcss.config.js", "tailwind.config.js", "vite.config.ts"], [".git"]]),
+	root: RootWithFallback(
+		IgnoreHomeRoot(
+			PriorityRoot([["package.json", "postcss.config.js", "tailwind.config.js", "vite.config.ts"]]),
+		),
+	),
 	spawn(root, options) {
 		return resolveAndLaunch(
 			{ candidates: nodeBinCandidates(root, "vscode-css-language-server"), args: ["--stdio"], cwd: root, managedToolId: "vscode-css-languageserver" },
@@ -1353,7 +1410,6 @@ export const LSP_SERVERS: LSPServerInfo[] = [
 	GoServer,
 	RustServer,
 	RubyServer,
-	RubySolargraphServer,
 	PHPServer,
 	// PowerShellServer — not included; no viable LSP binary, coverage notice fires instead
 	CSharpServer,

package/clients/runtime-session.ts

@@ -376,7 +376,9 @@ function runErrorDebtBaseline(
 		SessionStartDeps,
 		"testRunnerClient" | "cacheManager" | "notify" | "dbg" | "runtime"
 	>,
-	detectedRunner: ReturnType<SessionStartDeps["testRunnerClient"]["detectRunner"]>,
+	detectedRunner: ReturnType<
+		SessionStartDeps["testRunnerClient"]["detectRunner"]
+	>,
 	analysisRoot: string,
 	allowBootstrapTasks: boolean,
 	getFlag: SessionStartDeps["getFlag"],
@@ -499,20 +501,38 @@ export async function handleSessionStart(
 	const tools: string[] = [];
 	if (getFlag("lens-lsp") && !getFlag("no-lsp")) tools.push("LSP Service");
 
-	// Warm npm-based tool availability caches after startup returns. These sync
-	// subprocess calls (biome --version, npx knip --version, etc.) take ~500ms-2s
-	// each and were blocking the critical startup path with no functional benefit —
-	// each runner re-checks availability lazily when it first runs.
-	setImmediate(() => {
-		const b = biomeClient.isAvailable();
-		const a = astGrepClient.isAvailable();
-		const r = ruffClient.isAvailable();
-		knipClient.isAvailable();
-		depChecker.isAvailable();
-		jscpdClient.isAvailable();
-		typeCoverageClient.isAvailable();
-		dbg(`session_start tools (deferred probes complete): biome=${b} ast-grep=${a} ruff=${r}`);
-	});
+	// Warm tool availability caches off the critical startup path. The previous
+	// version used `setImmediate` + sync `isAvailable()`, which still blocked
+	// the Node event loop (each `isAvailable()` runs `spawnSync` — and six of
+	// the seven probes fall back to `npx <tool> --version` at ~1.5-2s each,
+	// summing to ~8-10s of main-thread freeze during session_start).
+	//
+	// We now run each probe through the client's async `ensureAvailable()`
+	// (which uses a fast bare-name PATH probe, falling back to `ensureTool`
+	// async install) inside a fire-and-forget IIFE. No main-thread blocking.
+	//
+	// Notes:
+	// - `typeCoverageClient` has no async probe and is only used by
+	//   `/lens-booboo`, so we let it probe lazily when first needed.
+	// - `ensureAvailable()` can auto-install missing tools into `~/.pi-lens/tools`.
+	//   This matches `firePreinstallDefaults`' existing behaviour for biome /
+	//   typescript-language-server.
+	void (async () => {
+		const warmStart = Date.now();
+		const [biomeReady, sgReady, ruffReady] = await Promise.all([
+			biomeClient.ensureAvailable().catch(() => false),
+			astGrepClient.ensureAvailable().catch(() => false),
+			ruffClient.ensureAvailable().catch(() => false),
+		]);
+		await Promise.allSettled([
+			knipClient.ensureAvailable().catch(() => false),
+			depChecker.ensureAvailable().catch(() => false),
+			jscpdClient.ensureAvailable().catch(() => false),
+		]);
+		dbg(
+			`session_start tools (deferred probes complete, ${Date.now() - warmStart}ms): biome=${biomeReady} ast-grep=${sgReady} ruff=${ruffReady}`,
+		);
+	})();
 
 	if (allowBootstrapTasks && getFlag("lens-lsp") && !getFlag("no-lsp")) {
 		const cleaned = cleanStaleTsBuildInfo(ctxCwd ?? process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "3.8.27",
+	"version": "3.8.28",
 	"type": "module",
 	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {