pi-lens 3.1.2 → 3.2.0

package/clients/path-utils.js

@@ -0,0 +1,142 @@
+/**
+ * Path utilities for pi-lens
+ *
+ * Handles cross-platform path normalization, particularly
+ * Windows case-insensitivity issues when using paths as Map keys.
+ *
+ * Approach (inspired by OpenCode's Filesystem.normalizePath):
+ * - On Windows: try realpathSync.native() for canonical casing
+ * - Falls back to lowercase for files that don't exist yet
+ * - On non-Windows: return path as-is (case-sensitive filesystem)
+ * - Always convert backslashes to forward slashes for Map key consistency
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+/**
+ * Detect if a path is a Windows path (has drive letter or UNC prefix).
+ */
+function isWindowsPath(filePath) {
+    return /^[A-Za-z]:/.test(filePath) || filePath.startsWith("\\\\");
+}
+/**
+ * Normalize a file path for consistent Map key usage.
+ *
+ * On Windows:
+ * - If the file exists: uses realpathSync.native() to get the canonical
+ *   filesystem path (actual casing, resolved symlinks)
+ * - If the file doesn't exist: resolves the path and lowercases
+ *   (needed for new files where we haven't written yet)
+ *
+ * On non-Windows: returns path as-is (case-sensitive filesystem).
+ *
+ * Always converts backslashes to forward slashes for consistent Map keys.
+ */
+export function normalizeFilePath(filePath) {
+    // Convert backslashes to forward slashes first
+    const normalized = filePath.replace(/\\/g, "/");
+    if (process.platform !== "win32" && !isWindowsPath(normalized)) {
+        return normalized;
+    }
+    // Windows: try realpathSync.native() for canonical casing
+    // This resolves symlinks and returns the actual filesystem casing
+    try {
+        const canonical = realpathSync.native(filePath);
+        return canonical.replace(/\\/g, "/");
+    }
+    catch {
+        // File doesn't exist yet (new file) — resolve path and lowercase
+        // We need to walk up the directory tree to find the nearest existing
+        // parent, resolve its casing, then append the non-existent parts
+        try {
+            return resolveNonExisting(filePath);
+        }
+        catch {
+            // Last resort: just lowercase the resolved path
+            const resolved = win32.normalize(win32.resolve(filePath));
+            return resolved.replace(/\\/g, "/").toLowerCase();
+        }
+    }
+}
+/**
+ * Resolve a non-existing path by finding the nearest existing parent,
+ * getting its canonical casing, then appending the non-existent parts lowercased.
+ *
+ * Example: C:\Users\Foo\newdir\file.ts
+ * - C:\Users\Foo exists → realpathSync gives C:\Users\Foo
+ * - newdir\file.ts doesn't exist → lowercased
+ * - Result: C:/Users/Foo/newdir/file.ts
+ */
+function resolveNonExisting(filePath) {
+    const resolved = win32.resolve(filePath);
+    let current = resolved;
+    const nonExistentParts = [];
+    // Walk up until we find an existing directory
+    while (true) {
+        if (existsSync(current)) {
+            // Found existing ancestor — get its canonical casing
+            const canonical = realpathSync.native(current);
+            if (nonExistentParts.length === 0) {
+                return canonical.replace(/\\/g, "/");
+            }
+            // Append non-existent parts (lowercased for consistency)
+            const tail = nonExistentParts.reverse().join("/").toLowerCase();
+            const base = canonical.replace(/\\/g, "/");
+            return base.endsWith("/") ? base + tail : `${base}/${tail}`;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            // Reached filesystem root without finding existing dir
+            // Fall back to full lowercase
+            throw new Error("No existing parent found");
+        }
+        nonExistentParts.push(win32.basename(current));
+        current = parent;
+    }
+}
+/**
+ * Convert a file:// URI to a normalized path.
+ * Handles URL decoding and Windows drive letter normalization.
+ */
+export function uriToPath(uri) {
+    try {
+        const filePath = fileURLToPath(uri);
+        return normalizeFilePath(filePath);
+    }
+    catch {
+        // Not a valid file:// URI, treat as plain path
+        return normalizeFilePath(uri);
+    }
+}
+/**
+ * Convert a path to a file:// URI.
+ * Does NOT normalize the path - URIs preserve original casing.
+ */
+export function pathToUri(filePath) {
+    return pathToFileURL(filePath).href;
+}
+/**
+ * Normalize a Map key lookup for file paths.
+ * Use this when getting/setting values in Maps that use file paths as keys.
+ */
+export function normalizeMapKey(filePath) {
+    return normalizeFilePath(filePath);
+}
+/**
+ * Compare two file paths for equality, handling Windows case-insensitivity
+ * and mixed separators (backslash vs forward slash).
+ */
+export function pathsEqual(a, b) {
+    return normalizeFilePath(a) === normalizeFilePath(b);
+}
+/**
+ * Check if `child` is under `parent` directory.
+ * Separator-agnostic and case-insensitive on Windows.
+ */
+export function isUnderDir(child, parent) {
+    const normChild = normalizeFilePath(child);
+    const normParent = normalizeFilePath(parent);
+    // Ensure parent ends with / for prefix matching
+    const parentPrefix = normParent.endsWith("/") ? normParent : `${normParent}/`;
+    return normChild === normParent || normChild.startsWith(parentPrefix);
+}

package/clients/path-utils.ts

@@ -0,0 +1,153 @@
+/**
+ * Path utilities for pi-lens
+ *
+ * Handles cross-platform path normalization, particularly
+ * Windows case-insensitivity issues when using paths as Map keys.
+ *
+ * Approach (inspired by OpenCode's Filesystem.normalizePath):
+ * - On Windows: try realpathSync.native() for canonical casing
+ * - Falls back to lowercase for files that don't exist yet
+ * - On non-Windows: return path as-is (case-sensitive filesystem)
+ * - Always convert backslashes to forward slashes for Map key consistency
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * Detect if a path is a Windows path (has drive letter or UNC prefix).
+ */
+function isWindowsPath(filePath: string): boolean {
+	return /^[A-Za-z]:/.test(filePath) || filePath.startsWith("\\\\");
+}
+
+/**
+ * Normalize a file path for consistent Map key usage.
+ *
+ * On Windows:
+ * - If the file exists: uses realpathSync.native() to get the canonical
+ *   filesystem path (actual casing, resolved symlinks)
+ * - If the file doesn't exist: resolves the path and lowercases
+ *   (needed for new files where we haven't written yet)
+ *
+ * On non-Windows: returns path as-is (case-sensitive filesystem).
+ *
+ * Always converts backslashes to forward slashes for consistent Map keys.
+ */
+export function normalizeFilePath(filePath: string): string {
+	// Convert backslashes to forward slashes first
+	const normalized = filePath.replace(/\\/g, "/");
+
+	if (process.platform !== "win32" && !isWindowsPath(normalized)) {
+		return normalized;
+	}
+
+	// Windows: try realpathSync.native() for canonical casing
+	// This resolves symlinks and returns the actual filesystem casing
+	try {
+		const canonical = realpathSync.native(filePath);
+		return canonical.replace(/\\/g, "/");
+	} catch {
+		// File doesn't exist yet (new file) — resolve path and lowercase
+		// We need to walk up the directory tree to find the nearest existing
+		// parent, resolve its casing, then append the non-existent parts
+		try {
+			return resolveNonExisting(filePath);
+		} catch {
+			// Last resort: just lowercase the resolved path
+			const resolved = win32.normalize(win32.resolve(filePath));
+			return resolved.replace(/\\/g, "/").toLowerCase();
+		}
+	}
+}
+
+/**
+ * Resolve a non-existing path by finding the nearest existing parent,
+ * getting its canonical casing, then appending the non-existent parts lowercased.
+ *
+ * Example: C:\Users\Foo\newdir\file.ts
+ * - C:\Users\Foo exists → realpathSync gives C:\Users\Foo
+ * - newdir\file.ts doesn't exist → lowercased
+ * - Result: C:/Users/Foo/newdir/file.ts
+ */
+function resolveNonExisting(filePath: string): string {
+	const resolved = win32.resolve(filePath);
+	let current = resolved;
+	const nonExistentParts: string[] = [];
+
+	// Walk up until we find an existing directory
+	while (true) {
+		if (existsSync(current)) {
+			// Found existing ancestor — get its canonical casing
+			const canonical = realpathSync.native(current);
+			if (nonExistentParts.length === 0) {
+				return canonical.replace(/\\/g, "/");
+			}
+			// Append non-existent parts (lowercased for consistency)
+			const tail = nonExistentParts.reverse().join("/").toLowerCase();
+			const base = canonical.replace(/\\/g, "/");
+			return base.endsWith("/") ? base + tail : `${base}/${tail}`;
+		}
+
+		const parent = dirname(current);
+		if (parent === current) {
+			// Reached filesystem root without finding existing dir
+			// Fall back to full lowercase
+			throw new Error("No existing parent found");
+		}
+
+		nonExistentParts.push(win32.basename(current));
+		current = parent;
+	}
+}
+
+/**
+ * Convert a file:// URI to a normalized path.
+ * Handles URL decoding and Windows drive letter normalization.
+ */
+export function uriToPath(uri: string): string {
+	try {
+		const filePath = fileURLToPath(uri);
+		return normalizeFilePath(filePath);
+	} catch {
+		// Not a valid file:// URI, treat as plain path
+		return normalizeFilePath(uri);
+	}
+}
+
+/**
+ * Convert a path to a file:// URI.
+ * Does NOT normalize the path - URIs preserve original casing.
+ */
+export function pathToUri(filePath: string): string {
+	return pathToFileURL(filePath).href;
+}
+
+/**
+ * Normalize a Map key lookup for file paths.
+ * Use this when getting/setting values in Maps that use file paths as keys.
+ */
+export function normalizeMapKey(filePath: string): string {
+	return normalizeFilePath(filePath);
+}
+
+/**
+ * Compare two file paths for equality, handling Windows case-insensitivity
+ * and mixed separators (backslash vs forward slash).
+ */
+export function pathsEqual(a: string, b: string): boolean {
+	return normalizeFilePath(a) === normalizeFilePath(b);
+}
+
+/**
+ * Check if `child` is under `parent` directory.
+ * Separator-agnostic and case-insensitive on Windows.
+ */
+export function isUnderDir(child: string, parent: string): boolean {
+	const normChild = normalizeFilePath(child);
+	const normParent = normalizeFilePath(parent);
+	// Ensure parent ends with / for prefix matching
+	const parentPrefix = normParent.endsWith("/") ? normParent : `${normParent}/`;
+	return normChild === normParent || normChild.startsWith(parentPrefix);
+}

package/clients/ruff-client.js

@@ -20,7 +20,36 @@ export class RuffClient {
             : () => { };
     }
     /**
-     * Check if ruff CLI is available
+     * Check if ruff CLI is available, auto-install if not
+     */
+    async ensureAvailable() {
+        // Fast path: already checked
+        if (this.ruffAvailable !== null)
+            return this.ruffAvailable;
+        // Check if available in PATH
+        const result = safeSpawn("ruff", ["--version"], {
+            timeout: 5000,
+        });
+        this.ruffAvailable = !result.error && result.status === 0;
+        if (this.ruffAvailable) {
+            this.log(`Ruff found: ${result.stdout.trim()}`);
+            return true;
+        }
+        // Auto-install via pi-lens installer
+        this.log("Ruff not found, attempting auto-install...");
+        const { ensureTool } = await import("./installer/index.js");
+        const installedPath = await ensureTool("ruff");
+        if (installedPath) {
+            this.log(`Ruff auto-installed: ${installedPath}`);
+            this.ruffAvailable = true;
+            return true;
+        }
+        this.log("Ruff auto-install failed");
+        return false;
+    }
+    /**
+     * Check if ruff CLI is available (legacy sync method)
+     * Prefer ensureAvailable() for auto-install behavior
      */
     isAvailable() {
         if (this.ruffAvailable !== null)
@@ -166,8 +195,8 @@ export class RuffClient {
         }
         // Filter to existing Python files
         const validFiles = filePaths
-            .map(f => path.resolve(f))
-            .filter(f => fs.existsSync(f) && f.endsWith(".py"));
+            .map((f) => path.resolve(f))
+            .filter((f) => fs.existsSync(f) && f.endsWith(".py"));
         if (validFiles.length === 0) {
             return { success: true, fixed: 0, changed: 0 };
         }
@@ -176,7 +205,7 @@ export class RuffClient {
             let totalFixable = 0;
             for (const file of validFiles) {
                 const diags = this.checkFile(file);
-                totalFixable += diags.filter(d => d.fixable).length;
+                totalFixable += diags.filter((d) => d.fixable).length;
             }
             // Run ruff once on all files - much faster than per file
             const result = safeSpawn("ruff", ["check", "--fix", ...validFiles], {

package/clients/ruff-client.ts

@@ -8,7 +8,6 @@
  * Docs: https://docs.astral.sh/ruff/
  */
 
-import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { isFileKind } from "./file-kinds.js";
@@ -51,7 +50,41 @@ export class RuffClient {
 	}
 
 	/**
-	 * Check if ruff CLI is available
+	 * Check if ruff CLI is available, auto-install if not
+	 */
+	async ensureAvailable(): Promise<boolean> {
+		// Fast path: already checked
+		if (this.ruffAvailable !== null) return this.ruffAvailable;
+
+		// Check if available in PATH
+		const result = safeSpawn("ruff", ["--version"], {
+			timeout: 5000,
+		});
+		this.ruffAvailable = !result.error && result.status === 0;
+
+		if (this.ruffAvailable) {
+			this.log(`Ruff found: ${result.stdout.trim()}`);
+			return true;
+		}
+
+		// Auto-install via pi-lens installer
+		this.log("Ruff not found, attempting auto-install...");
+		const { ensureTool } = await import("./installer/index.js");
+		const installedPath = await ensureTool("ruff");
+
+		if (installedPath) {
+			this.log(`Ruff auto-installed: ${installedPath}`);
+			this.ruffAvailable = true;
+			return true;
+		}
+
+		this.log("Ruff auto-install failed");
+		return false;
+	}
+
+	/**
+	 * Check if ruff CLI is available (legacy sync method)
+	 * Prefer ensureAvailable() for auto-install behavior
 	 */
 	isAvailable(): boolean {
 		if (this.ruffAvailable !== null) return this.ruffAvailable;
@@ -230,8 +263,8 @@ export class RuffClient {
 
 		// Filter to existing Python files
 		const validFiles = filePaths
-			.map(f => path.resolve(f))
-			.filter(f => fs.existsSync(f) && f.endsWith(".py"));
+			.map((f) => path.resolve(f))
+			.filter((f) => fs.existsSync(f) && f.endsWith(".py"));
 
 		if (validFiles.length === 0) {
 			return { success: true, fixed: 0, changed: 0 };
@@ -242,17 +275,13 @@ export class RuffClient {
 			let totalFixable = 0;
 			for (const file of validFiles) {
 				const diags = this.checkFile(file);
-				totalFixable += diags.filter(d => d.fixable).length;
+				totalFixable += diags.filter((d) => d.fixable).length;
 			}
 
 			// Run ruff once on all files - much faster than per file
-			const result = safeSpawn(
-				"ruff",
-				["check", "--fix", ...validFiles],
-				{
-					timeout: 60000, // Longer timeout for batch
-				},
-			);
+			const result = safeSpawn("ruff", ["check", "--fix", ...validFiles], {
+				timeout: 60000, // Longer timeout for batch
+			});
 
 			if (result.error) {
 				return {
@@ -263,7 +292,9 @@ export class RuffClient {
 				};
 			}
 
-			this.log(`Fixed ${totalFixable} issue(s) in ${validFiles.length} file(s)`);
+			this.log(
+				`Fixed ${totalFixable} issue(s) in ${validFiles.length} file(s)`,
+			);
 
 			return { success: true, fixed: totalFixable, changed: validFiles.length };
 		} catch (err: any) {

package/clients/safe-spawn.js

@@ -48,11 +48,13 @@ export async function safeSpawnAsync(command, args, options) {
         let timedOut = false;
         let killed = false;
         // Spawn the process (non-blocking)
+        // On Windows, use shell mode for .cmd files (like pyright, biome)
+        const isWindows = process.platform === "win32";
         const child = spawn(command, args, {
             cwd: options?.cwd,
             env: { ...process.env, ...options?.env },
             windowsHide: true,
-            shell: false,
+            shell: isWindows,
         });
         // Handle abort signal
         const onAbort = () => {

package/clients/safe-spawn.ts

@@ -72,11 +72,13 @@ export async function safeSpawnAsync(
 		let killed = false;
 
 		// Spawn the process (non-blocking)
+		// On Windows, use shell mode for .cmd files (like pyright, biome)
+		const isWindows = process.platform === "win32";
 		const child = spawn(command, args, {
 			cwd: options?.cwd,
 			env: { ...process.env, ...options?.env },
 			windowsHide: true,
-			shell: false,
+			shell: isWindows,
 		});
 
 		// Handle abort signal

package/clients/services/effect-integration.js

@@ -9,9 +9,9 @@
  * - Graceful error recovery
  * - Bus event integration
  */
-import { runRunnersConcurrent, executeEffect, } from "./runner-service.js";
-import { DiagnosticFound, RunnerStarted, RunnerCompleted, FileModified, } from "../bus/events.js";
+import { DiagnosticFound, FileModified, RunnerCompleted, RunnerStarted, } from "../bus/events.js";
 import { formatDiagnostics } from "../dispatch/utils/format-utils.js";
+import { executeEffect, runRunnersConcurrent, } from "./runner-service.js";
 // Import runners to register them in the dispatcher
 import "../dispatch/runners/index.js";
 // --- Core Functions ---
@@ -20,11 +20,10 @@ import "../dispatch/runners/index.js";
  */
 async function runGroupConcurrent(ctx, group) {
     const { getRunner, getRunnersForKind } = await import("../dispatch/dispatcher.js");
-    const startTime = Date.now();
+    const _startTime = Date.now();
     // Get runner definitions
     const runnerDefs = group.filterKinds
-        ? group.runnerIds
-            .filter((id) => {
+        ? group.runnerIds.filter((id) => {
             const runner = getRunner(id);
             return runner && ctx.kind && group.filterKinds?.includes(ctx.kind);
         })
@@ -59,7 +58,11 @@ async function runGroupConcurrent(ctx, group) {
                 filePath: ctx.filePath,
                 line: d.line,
                 column: d.column,
-                severity: d.severity === "error" ? "error" : d.severity === "warning" ? "warning" : "info",
+                severity: d.severity === "error"
+                    ? "error"
+                    : d.severity === "warning"
+                        ? "warning"
+                        : "info",
                 semantic: d.semantic ?? result.semantic ?? "warning",
                 tool: runnerId,
                 rule: d.rule,
@@ -182,7 +185,8 @@ export async function dispatchWithEffect(ctx, groups) {
 export async function dispatchLintWithEffect(filePath, cwd, pi) {
     const { createDispatchContext } = await import("../dispatch/dispatcher.js");
     const { TOOL_PLANS } = await import("../dispatch/plan.js");
-    const ctx = createDispatchContext(filePath, cwd, pi);
+    // blockingOnly=true: post-write dispatch only reports blocking errors (same as standard dispatchLint)
+    const ctx = createDispatchContext(filePath, cwd, pi, undefined, true);
     const kind = ctx.kind;
     if (!kind)
         return "";

package/clients/services/effect-integration.ts

@@ -1,8 +1,8 @@
 /**
  * Effect-TS Integration for pi-lens Dispatch
- * 
+ *
  * Bridges the Effect service layer with the existing dispatch system.
- * 
+ *
  * This provides:
  * - Concurrent runner execution with Effect.all
  * - Timeout handling for slow runners
@@ -11,21 +11,19 @@
  */
 
 import {
-	runRunnersConcurrent,
-	executeEffect,
-	formatError,
-	type RunnerResult,
-	type ConcurrentRunnerResult,
-} from "./runner-service.js";
-
-import {
+	type Diagnostic,
 	DiagnosticFound,
-	RunnerStarted,
-	RunnerCompleted,
 	FileModified,
-	type Diagnostic,
+	RunnerCompleted,
+	RunnerStarted,
 } from "../bus/events.js";
-import { formatDiagnostic, formatDiagnostics } from "../dispatch/utils/format-utils.js";
+import { formatDiagnostics } from "../dispatch/utils/format-utils.js";
+import {
+	type ConcurrentRunnerResult,
+	executeEffect,
+	type RunnerResult,
+	runRunnersConcurrent,
+} from "./runner-service.js";
 // Import runners to register them in the dispatcher
 import "../dispatch/runners/index.js";
 
@@ -54,16 +52,17 @@ async function runGroupConcurrent(
 	ctx: DispatchContext,
 	group: RunnerGroup,
 ): Promise<{ results: ConcurrentRunnerResult[]; diagnostics: Diagnostic[] }> {
-	const { getRunner, getRunnersForKind } = await import("../dispatch/dispatcher.js");
-	const startTime = Date.now();
+	const { getRunner, getRunnersForKind } = await import(
+		"../dispatch/dispatcher.js"
+	);
+	const _startTime = Date.now();
 
 	// Get runner definitions
 	const runnerDefs = group.filterKinds
-		? group.runnerIds
-				.filter((id) => {
-					const runner = getRunner(id);
-					return runner && ctx.kind && group.filterKinds?.includes(ctx.kind);
-				})
+		? group.runnerIds.filter((id) => {
+				const runner = getRunner(id);
+				return runner && ctx.kind && group.filterKinds?.includes(ctx.kind);
+			})
 		: group.runnerIds;
 
 	const runners = runnerDefs
@@ -76,7 +75,10 @@ async function runGroupConcurrent(
 	}
 
 	// Build the single runner execution function
-	const runSingle = async (filePath: string, runnerId: string): Promise<RunnerResult> => {
+	const runSingle = async (
+		filePath: string,
+		runnerId: string,
+	): Promise<RunnerResult> => {
 		const runner = getRunner(runnerId);
 		if (!runner) {
 			return { diagnostics: [], durationMs: 0 };
@@ -101,7 +103,12 @@ async function runGroupConcurrent(
 				filePath: ctx.filePath,
 				line: d.line,
 				column: d.column,
-				severity: d.severity === "error" ? "error" : d.severity === "warning" ? "warning" : "info",
+				severity:
+					d.severity === "error"
+						? "error"
+						: d.severity === "warning"
+							? "warning"
+							: "info",
 				semantic: d.semantic ?? result.semantic ?? "warning",
 				tool: runnerId,
 				rule: d.rule,
@@ -150,7 +157,7 @@ async function runGroupConcurrent(
 	// Run all runners concurrently using Effect
 	const runnerIds = runners.map((r) => r.id);
 	const concurrentResults = await executeEffect(
-		runRunnersConcurrent(ctx.filePath, runnerIds, runSingle, 30_000)
+		runRunnersConcurrent(ctx.filePath, runnerIds, runSingle, 30_000),
 	);
 
 	// Collect all diagnostics
@@ -165,7 +172,7 @@ async function runGroupConcurrent(
 					severity: d.severity,
 					semantic: d.semantic ?? group.semantic ?? "warning",
 					tool: result.runnerId,
-				}))
+				})),
 			);
 		}
 	}
@@ -255,7 +262,8 @@ export async function dispatchLintWithEffect(
 	const { createDispatchContext } = await import("../dispatch/dispatcher.js");
 	const { TOOL_PLANS } = await import("../dispatch/plan.js");
 
-	const ctx = createDispatchContext(filePath, cwd, pi);
+	// blockingOnly=true: post-write dispatch only reports blocking errors (same as standard dispatchLint)
+	const ctx = createDispatchContext(filePath, cwd, pi, undefined, true);
 
 	const kind = ctx.kind;
 	if (!kind) return "";