pi-lens 3.1.2 → 3.2.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [3.2.0] - 2026-04-02
+
+### Fixed
+- **LSP server initialization errors** — Fixed `workspaceFolders` capability format that caused gopls and rust-analyzer to crash with JSON RPC parse errors. Changed from object `{supported: true, changeNotifications: true}` to simple boolean `true` for broader compatibility.
+- **Formatter cwd not passed** — `formatFile` now passes `cwd` to `safeSpawn`, fixing Biome's "nested root configuration" error when formatting files in subdirectories.
+- **LSP runner error handling** — Added try-catch around LSP operations to properly detect and report server spawn/connection failures instead of silently returning empty success.
+
+### Changed
+- **Go/Rust LSP initialization** — Added server-specific initialization options for better compatibility.
+
+---
+
+## [3.1.3] - 2026-04-02
+
+### Fixed
+- **Biome autofix: removed `--unsafe` flag** — `--unsafe` silently deleted unused variables
+  and interfaces, removing code the agent was mid-way through writing (e.g. a new interface
+  not yet wired up). Only safe fixes (`--write`) are now applied automatically on every write.
+  Unsafe fixes require explicit opt-in.
+- **Tree-sitter WASM crash on concurrent writes** — The tree-sitter runner was creating a
+  `new TreeSitterClient()` on every post-write event. Each construction re-invoked
+  `Parser.init()` → `C._ts_init()`, which resets the module-level `TRANSFER_BUFFER` pointer
+  used by all active WASM operations. Concurrent writes (fast multi-file edits) raced on
+  `_ts_init()` and corrupted shared WASM state → process crash. Fixed with a module-level
+  singleton (`getSharedClient()`). Also fixes the secondary bug where each fresh client had
+  an empty internal `queryLoader`, making the tree-sitter runner a silent no-op.
+- **`blockingOnly` missing in bus/effect dispatchers** — `dispatchLintWithBus` and
+  `dispatchLintWithEffect` were not passing `blockingOnly: true` to `createDispatchContext`,
+  causing warning-level runners to execute on every write when `--lens-bus` or `--lens-effect`
+  was active. Now consistent with the standard `dispatchLint` behaviour.
+- **Async `when` condition silently ignored in bus dispatcher** — `dispatchConcurrent` was
+  filtering runners with `.filter(r => r.when ? r.when(ctx) : true)`. Since `r.when(ctx)`
+  returns `Promise<boolean>`, a truthy promise object was always passing the filter regardless
+  of the actual condition. The check is now awaited properly inside `runRunner()`.
+
+### Performance
+- **Biome: local binary instead of npx** — `BiomeClient` now resolves
+  `node_modules/.bin/biome.cmd` (Windows) or `node_modules/.bin/biome` before falling back
+  to `npx @biomejs/biome`. Eliminates ~1 s npx startup overhead per invocation.
+  Result: `checkFile` 1029 ms → **176 ms**, `fixFile` 2012 ms → **158 ms**.
+- **Biome: eliminated redundant pre-flight `checkFile` in `fixFile`** — `fixFile` was calling
+  `checkFile` (a full `biome check --reporter=json`) solely to count fixable issues for
+  logging, then running `biome check --write` anyway. The count is now derived from the
+  content diff (`changed ? 1 : 0`), saving one full biome invocation per write.
+  Combined with the format phase, biome now runs at most **2×** per write (format + fix)
+  instead of 3×.
+- **TypeScript pre-write check: halved `getSemanticDiagnostics` calls** — `getAllCodeFixes()`
+  was calling `getDiagnostics()` internally, but `index.ts` also called `getDiagnostics()`
+  immediately before it — running the full TypeScript semantic analysis twice per pre-write
+  event (~1.2 s each on a 1700-line file). `getAllCodeFixes` now accepts an optional
+  `precomputedDiags` parameter; `index.ts` passes the already-computed result.
+  `ts_pre_check` latency: ~2400 ms → **~1200 ms**.
+
+---
+
 ## [3.1.1] - 2026-04-01
 
 ### Added

package/README.md

@@ -205,8 +205,8 @@ pi-lens uses a **dispatcher-runner architecture** for extensible multi-language
 | **biome** | TS/JS | 10 | Warning | Linting issues (delta-tracked) |
 | **ruff** | Python | 10 | Warning | Python linting (delta-tracked) |
 | **oxlint** | TS/JS | 12 | Warning | Fast Rust-based JS/TS linter |
-| **tree-sitter** | TS/JS, Python | 14 | Mixed | AST-based structural analysis (17 patterns) |
-| **ast-grep-napi** | TS/JS | 15 | Warning | **Unified structural analysis** (104 rules) — ⚠️ Temporarily disabled for debugging |
+| **tree-sitter** | TS/JS, Python | 14 | Mixed | AST-based structural analysis (21 patterns) — **singleton WASM client** |
+| **ast-grep-napi** | TS/JS | 15 | — | **Disabled by default** — heavy; use `/lens-booboo` for full analysis |
 | **type-safety** | TS | 20 | Mixed | Switch exhaustiveness (blocking), other (warning) |
 | **shellcheck** | Shell | 20 | Warning | Bash/sh/zsh/fish linting |
 | **python-slop** | Python | 25 | Warning | AI slop detection (~40 patterns) |
@@ -228,13 +228,17 @@ pi-lens uses a **dispatcher-runner architecture** for extensible multi-language
 - **Warning** — Shown in `/lens-booboo`, not inline (noise reduction)
 - **Silent** — Tracked in metrics only, never shown
 
-**Consolidated runners:** `ast-grep` (CLI) and `ts-slop` merged into `ast-grep-napi` — unified 104-rule set
+**Consolidated runners:** `ts-slop` merged into `ast-grep-napi` (disabled by default) — CLI ast-grep used for full linter only
 
 **Tree-sitter runner patterns** (priority 14, AST-based structural analysis):
 
-TypeScript/JavaScript (12 patterns):
+TypeScript/JavaScript (13 patterns):
 - 🔴 **Error**: empty-catch, hardcoded-secrets, eval
-- 🟡 **Warning**: debugger, await-in-loop, console-statement, long-parameter-list, nested-ternary, deep-promise-chain, mixed-async-styles, deep-nesting
+- 🟡 **Warning**: debugger, await-in-loop, console-statement, long-parameter-list, nested-ternary, deep-promise-chain, mixed-async-styles, deep-nesting, constructor-super, no-dupe-class-members
+
+TSX (2 patterns):
+- 🔴 **Error**: dangerously-set-inner-html
+- 🟡 **Warning**: no-nested-links
 
 Python (6 patterns):
 - 🔴 **Error**: bare-except, mutable-default-arg, eval-exec, unreachable-except  
@@ -244,7 +248,7 @@ Python (6 patterns):
 
 **AI Slop Detection:** 
 - `python-slop` runner (priority 25): ~40 patterns for Python code quality
-- `ast-grep-napi` runner (priority 15): 33 slop patterns + 71 security/architecture rules for TypeScript/JavaScript
+- `ast-grep-napi` runner (priority 15): 33 slop patterns + 68 security/architecture rules for TypeScript/JavaScript (disabled by default — use `/lens-booboo` for full ast-grep analysis via CLI)
 
 ---
 
@@ -429,7 +433,7 @@ pi-lens works out of the box for TypeScript/JavaScript. For full language suppor
 | `knip` | `npm i -D knip` | Dead code / unused exports |
 | `jscpd` | `npm i -D jscpd` | Copy-paste detection |
 | `type-coverage` | `npm i -D type-coverage` | TypeScript `any` coverage % |
-| `@ast-grep/napi` | `npm i -D @ast-grep/napi` | Fast structural analysis (TS/JS) |
+| `@ast-grep/napi` | `npm i -D @ast-grep/napi` | Fast structural analysis (TS/JS) — currently disabled in realtime |
 | `@ast-grep/cli` | `npm i -D @ast-grep/cli` | Structural pattern matching (all languages) |
 | `typos-cli` | `cargo install typos-cli` | Spellcheck for Markdown |
 
@@ -487,7 +491,7 @@ pi-lens works out of the box for TypeScript/JavaScript. For full language suppor
 | `--lens-effect` | Run all runners **concurrently** (faster) instead of sequentially (Experimental) |
 | `--lens-verbose` | Enable detailed console logging |
 | `--no-autoformat` | Disable automatic formatting (formatting is **enabled by default**) |
-| `--no-autofix` | Disable all auto-fixing (Biome + Ruff autofix is **enabled by default**) |
+| `--no-autofix` | Disable all auto-fixing (Biome safe fixes + Ruff autofix **enabled by default**). Unsafe fixes (e.g. removing unused vars) are never applied automatically — use `/lens-booboo` with explicit confirmation. |
 | `--no-autofix-biome` | Disable Biome auto-fix only |
 | `--no-autofix-ruff` | Disable Ruff auto-fix only |
 | `--no-oxlint` | Skip Oxlint linting |
@@ -640,7 +644,7 @@ Tracks which files were edited in the current agent turn for:
 
 | Runner | Cache | Notes |
 |--------|-------|-------|
-| `ast-grep-napi` | Rule descriptions | Loaded once per session |
+| `ast-grep-napi` | Rule descriptions | Loaded once per session (disabled by default) |
 | `biome` | Tool availability | Checked once, cached |
 | `pyright` | Command path | Venv lookup cached |
 | `ruff` | Command path | Venv lookup cached |
@@ -659,7 +663,7 @@ pi-lens/
 │   ├── dispatch/         # Dispatcher and runners
 │   │   ├── dispatcher.ts
 │   │   └── runners/      # Individual runners
-│   │       ├── ast-grep-napi.ts      # Fast TS/JS runner
+│   │       ├── ast-grep-napi.ts      # Fast TS/JS runner (disabled by default)
 │   │       ├── python-slop.ts        # Python slop detection
 │   │       ├── ts-lsp.ts             # TS type checking
 │   │       ├── biome.ts
@@ -702,8 +706,8 @@ See [CHANGELOG.md](CHANGELOG.md) for full history.
 
 - **LSP Support:** 31 Language Server Protocol clients (4 core auto-installed, others via npx or manual)
 - **Concurrent Execution:** Effect-TS-based parallel runner execution with `--lens-effect`
-- **NAPI Runner:** 100x faster TypeScript/JavaScript structural analysis (~9ms vs ~1200ms)
-- **Slop Detection:** 30+ TypeScript and 40+ Python patterns for AI-generated code quality issues
+- **NAPI Runner:** 100x faster TypeScript/JavaScript structural analysis (~9ms vs ~1200ms) — currently disabled in realtime due to stability
+- **Slop Detection:** 33+ TypeScript and 40+ Python patterns for AI-generated code quality issues
 
 ---
 

package/clients/ast-grep-client.js

@@ -31,7 +31,14 @@ export class AstGrepClient {
         this.runner = new SgRunner(verbose);
     }
     /**
-     * Check if ast-grep CLI is available
+     * Check if ast-grep CLI is available, auto-install if not
+     */
+    async ensureAvailable() {
+        return this.runner.ensureAvailable();
+    }
+    /**
+     * Check if ast-grep CLI is available (legacy sync method)
+     * Prefer ensureAvailable() for auto-install behavior
      */
     isAvailable() {
         if (this.available !== null)

package/clients/ast-grep-client.ts

@@ -47,7 +47,15 @@ export class AstGrepClient {
 	}
 
 	/**
-	 * Check if ast-grep CLI is available
+	 * Check if ast-grep CLI is available, auto-install if not
+	 */
+	async ensureAvailable(): Promise<boolean> {
+		return this.runner.ensureAvailable();
+	}
+
+	/**
+	 * Check if ast-grep CLI is available (legacy sync method)
+	 * Prefer ensureAvailable() for auto-install behavior
 	 */
 	isAvailable(): boolean {
 		if (this.available !== null) return this.available;

package/clients/biome-client.js

@@ -15,20 +15,54 @@ import { safeSpawn } from "./safe-spawn.js";
 export class BiomeClient {
     constructor(verbose = false) {
         this.biomeAvailable = null;
+        this.localBinaryPath = null;
         this.log = verbose
             ? (msg) => console.error(`[biome] ${msg}`)
             : () => { };
     }
+    /**
+     * Resolve the fastest available biome binary.
+     * Prefers local node_modules/.bin/biome (skip npx overhead ~1s).
+     * Falls back to global biome, then npx.
+     */
+    getBiomeBinary() {
+        if (this.localBinaryPath)
+            return { cmd: this.localBinaryPath, args: [] };
+        // Walk up from cwd looking for node_modules/.bin/biome.
+        // On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
+        const isWin = process.platform === "win32";
+        const candidates = isWin
+            ? [
+                path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+                path.join(process.cwd(), "node_modules", ".bin", "biome"),
+            ]
+            : [
+                path.join(process.cwd(), "node_modules", ".bin", "biome"),
+                path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+            ];
+        for (const p of candidates) {
+            if (fs.existsSync(p)) {
+                this.localBinaryPath = p;
+                return { cmd: p, args: [] };
+            }
+        }
+        // Fallback: npx (slower but works anywhere)
+        return { cmd: "npx", args: ["@biomejs/biome"] };
+    }
+    /**
+     * Spawn biome with the fastest available binary.
+     */
+    spawnBiome(args, timeout = 15000) {
+        const { cmd, args: prefix } = this.getBiomeBinary();
+        return safeSpawn(cmd, [...prefix, ...args], { timeout });
+    }
     /**
      * Check if biome CLI is available
      */
     isAvailable() {
         if (this.biomeAvailable !== null)
             return this.biomeAvailable;
-        // Try npx biome first (works without global install)
-        const result = safeSpawn("npx", ["@biomejs/biome", "--version"], {
-            timeout: 10000,
-        });
+        const result = this.spawnBiome(["--version"], 10000);
         this.biomeAvailable = !result.error && result.status === 0;
         if (this.biomeAvailable) {
             const version = result.stdout?.trim() || "unknown";
@@ -65,15 +99,12 @@ export class BiomeClient {
         if (!absolutePath)
             return [];
         try {
-            const result = safeSpawn("npx", [
-                "@biomejs/biome",
+            const result = this.spawnBiome([
                 "check",
                 "--reporter=json",
                 "--max-diagnostics=50",
                 absolutePath,
-            ], {
-                timeout: 15000,
-            });
+            ]);
             // Biome exits 0 on success, 1 on issues found
             const output = result.stdout || "";
             if (!output.trim())
@@ -98,9 +129,7 @@ export class BiomeClient {
             };
         const content = fs.readFileSync(absolutePath, "utf-8");
         try {
-            const result = safeSpawn("npx", ["@biomejs/biome", "format", "--write", absolutePath], {
-                timeout: 15000,
-            });
+            const result = this.spawnBiome(["format", "--write", absolutePath]);
             if (result.error) {
                 return { success: false, changed: false, error: result.error.message };
             }
@@ -134,19 +163,9 @@ export class BiomeClient {
             };
         const content = fs.readFileSync(absolutePath, "utf-8");
         try {
-            // First, count issues before fixing
-            const beforeDiags = this.checkFile(filePath);
-            const fixableCount = beforeDiags.filter((d) => d.fixable).length;
-            // Apply fixes
-            const result = safeSpawn("npx", [
-                "@biomejs/biome",
-                "check",
-                "--write",
-                "--unsafe", // Apply unsafe fixes too
-                absolutePath,
-            ], {
-                timeout: 15000,
-            });
+            // Single invocation: check --write applies safe formatting + lint fixes.
+            // No pre-flight checkFile() needed — content diff tells us if anything changed.
+            const result = this.spawnBiome(["check", "--write", absolutePath]);
             if (result.error) {
                 return {
                     success: false,
@@ -158,9 +177,9 @@ export class BiomeClient {
             const fixed = fs.readFileSync(absolutePath, "utf-8");
             const changed = content !== fixed;
             if (changed) {
-                this.log(`Fixed ${fixableCount} issue(s) in ${path.basename(filePath)}`);
+                this.log(`Fixed issue(s) in ${path.basename(filePath)}`);
             }
-            return { success: true, changed, fixed: fixableCount };
+            return { success: true, changed, fixed: changed ? 1 : 0 };
         }
         catch (err) {
             return {
@@ -185,8 +204,8 @@ export class BiomeClient {
         }
         // Filter to existing files
         const validFiles = filePaths
-            .map(f => path.resolve(f))
-            .filter(f => fs.existsSync(f));
+            .map((f) => path.resolve(f))
+            .filter((f) => fs.existsSync(f));
         if (validFiles.length === 0) {
             return { success: true, fixed: 0, changed: 0 };
         }
@@ -195,16 +214,10 @@ export class BiomeClient {
             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 biome once on all files - much faster than npx per file
-            const result = safeSpawn("npx", [
-                "@biomejs/biome",
-                "check",
-                "--write",
-                "--unsafe",
-                ...validFiles,
-            ], {
+            const result = safeSpawn("npx", ["@biomejs/biome", "check", "--write", "--unsafe", ...validFiles], {
                 timeout: 60000, // Longer timeout for batch
             });
             if (result.error) {
@@ -217,7 +230,7 @@ export class BiomeClient {
             }
             // Count how many files actually changed
             let changedCount = 0;
-            for (const file of validFiles) {
+            for (const _file of validFiles) {
                 // We don't know exactly which files changed without re-reading,
                 // so we report total files processed
                 changedCount++;

package/clients/biome-client.ts

@@ -42,6 +42,7 @@ interface BiomeJsonDiagnostic {
 
 export class BiomeClient {
 	private biomeAvailable: boolean | null = null;
+	private localBinaryPath: string | null = null;
 	private log: (msg: string) => void;
 
 	constructor(verbose = false) {
@@ -50,16 +51,51 @@ export class BiomeClient {
 			: () => {};
 	}
 
+	/**
+	 * Resolve the fastest available biome binary.
+	 * Prefers local node_modules/.bin/biome (skip npx overhead ~1s).
+	 * Falls back to global biome, then npx.
+	 */
+	private getBiomeBinary(): { cmd: string; args: string[] } {
+		if (this.localBinaryPath) return { cmd: this.localBinaryPath, args: [] };
+
+		// Walk up from cwd looking for node_modules/.bin/biome.
+		// On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
+		const isWin = process.platform === "win32";
+		const candidates = isWin
+			? [
+					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+					path.join(process.cwd(), "node_modules", ".bin", "biome"),
+				]
+			: [
+					path.join(process.cwd(), "node_modules", ".bin", "biome"),
+					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+				];
+		for (const p of candidates) {
+			if (fs.existsSync(p)) {
+				this.localBinaryPath = p;
+				return { cmd: p, args: [] };
+			}
+		}
+		// Fallback: npx (slower but works anywhere)
+		return { cmd: "npx", args: ["@biomejs/biome"] };
+	}
+
+	/**
+	 * Spawn biome with the fastest available binary.
+	 */
+	private spawnBiome(args: string[], timeout = 15000) {
+		const { cmd, args: prefix } = this.getBiomeBinary();
+		return safeSpawn(cmd, [...prefix, ...args], { timeout });
+	}
+
 	/**
 	 * Check if biome CLI is available
 	 */
 	isAvailable(): boolean {
 		if (this.biomeAvailable !== null) return this.biomeAvailable;
 
-		// Try npx biome first (works without global install)
-		const result = safeSpawn("npx", ["@biomejs/biome", "--version"], {
-			timeout: 10000,
-		});
+		const result = this.spawnBiome(["--version"], 10000);
 
 		this.biomeAvailable = !result.error && result.status === 0;
 		if (this.biomeAvailable) {
@@ -103,19 +139,12 @@ export class BiomeClient {
 		if (!absolutePath) return [];
 
 		try {
-			const result = safeSpawn(
-				"npx",
-				[
-					"@biomejs/biome",
-					"check",
-					"--reporter=json",
-					"--max-diagnostics=50",
-					absolutePath,
-				],
-				{
-					timeout: 15000,
-				},
-			);
+			const result = this.spawnBiome([
+				"check",
+				"--reporter=json",
+				"--max-diagnostics=50",
+				absolutePath,
+			]);
 
 			// Biome exits 0 on success, 1 on issues found
 			const output = result.stdout || "";
@@ -149,13 +178,7 @@ export class BiomeClient {
 		const content = fs.readFileSync(absolutePath, "utf-8");
 
 		try {
-			const result = safeSpawn(
-				"npx",
-				["@biomejs/biome", "format", "--write", absolutePath],
-				{
-					timeout: 15000,
-				},
-			);
+			const result = this.spawnBiome(["format", "--write", absolutePath]);
 
 			if (result.error) {
 				return { success: false, changed: false, error: result.error.message };
@@ -200,24 +223,9 @@ export class BiomeClient {
 		const content = fs.readFileSync(absolutePath, "utf-8");
 
 		try {
-			// First, count issues before fixing
-			const beforeDiags = this.checkFile(filePath);
-			const fixableCount = beforeDiags.filter((d) => d.fixable).length;
-
-			// Apply fixes
-			const result = safeSpawn(
-				"npx",
-				[
-					"@biomejs/biome",
-					"check",
-					"--write",
-					"--unsafe", // Apply unsafe fixes too
-					absolutePath,
-				],
-				{
-					timeout: 15000,
-				},
-			);
+			// Single invocation: check --write applies safe formatting + lint fixes.
+			// No pre-flight checkFile() needed — content diff tells us if anything changed.
+			const result = this.spawnBiome(["check", "--write", absolutePath]);
 
 			if (result.error) {
 				return {
@@ -232,12 +240,10 @@ export class BiomeClient {
 			const changed = content !== fixed;
 
 			if (changed) {
-				this.log(
-					`Fixed ${fixableCount} issue(s) in ${path.basename(filePath)}`,
-				);
+				this.log(`Fixed issue(s) in ${path.basename(filePath)}`);
 			}
 
-			return { success: true, changed, fixed: fixableCount };
+			return { success: true, changed, fixed: changed ? 1 : 0 };
 		} catch (err) {
 			return {
 				success: false,
@@ -268,8 +274,8 @@ export class BiomeClient {
 
 		// Filter to existing files
 		const validFiles = filePaths
-			.map(f => path.resolve(f))
-			.filter(f => fs.existsSync(f));
+			.map((f) => path.resolve(f))
+			.filter((f) => fs.existsSync(f));
 
 		if (validFiles.length === 0) {
 			return { success: true, fixed: 0, changed: 0 };
@@ -280,19 +286,13 @@ export class BiomeClient {
 			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 biome once on all files - much faster than npx per file
 			const result = safeSpawn(
 				"npx",
-				[
-					"@biomejs/biome",
-					"check",
-					"--write",
-					"--unsafe",
-					...validFiles,
-				],
+				["@biomejs/biome", "check", "--write", "--unsafe", ...validFiles],
 				{
 					timeout: 60000, // Longer timeout for batch
 				},
@@ -309,13 +309,15 @@ export class BiomeClient {
 
 			// Count how many files actually changed
 			let changedCount = 0;
-			for (const file of validFiles) {
+			for (const _file of validFiles) {
 				// We don't know exactly which files changed without re-reading,
 				// so we report total files processed
 				changedCount++;
 			}
 
-			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: changedCount };
 		} catch (err) {

package/clients/dependency-checker.js

@@ -26,7 +26,36 @@ export class DependencyChecker {
             : () => { };
     }
     /**
-     * Check if madge is available
+     * Check if madge is available, auto-install if not
+     */
+    async ensureAvailable() {
+        // Fast path: already checked
+        if (this.available !== null)
+            return this.available;
+        // Check if available in PATH
+        const result = safeSpawn("madge", ["--version"], {
+            timeout: 5000,
+        });
+        this.available = !result.error && result.status === 0;
+        if (this.available) {
+            this.log(`Madge found: ${result.stdout?.trim()}`);
+            return true;
+        }
+        // Auto-install via pi-lens installer
+        this.log("Madge not found, attempting auto-install...");
+        const { ensureTool } = await import("./installer/index.js");
+        const installedPath = await ensureTool("madge");
+        if (installedPath) {
+            this.log(`Madge auto-installed: ${installedPath}`);
+            this.available = true;
+            return true;
+        }
+        this.log("Madge auto-install failed");
+        return false;
+    }
+    /**
+     * Check if madge is available (legacy sync method)
+     * Prefer ensureAvailable() for auto-install behavior
      */
     isAvailable() {
         if (this.available !== null)

package/clients/dependency-checker.ts

@@ -56,7 +56,41 @@ export class DependencyChecker {
 	}
 
 	/**
-	 * Check if madge is available
+	 * Check if madge is available, auto-install if not
+	 */
+	async ensureAvailable(): Promise<boolean> {
+		// Fast path: already checked
+		if (this.available !== null) return this.available;
+
+		// Check if available in PATH
+		const result = safeSpawn("madge", ["--version"], {
+			timeout: 5000,
+		});
+		this.available = !result.error && result.status === 0;
+
+		if (this.available) {
+			this.log(`Madge found: ${result.stdout?.trim()}`);
+			return true;
+		}
+
+		// Auto-install via pi-lens installer
+		this.log("Madge not found, attempting auto-install...");
+		const { ensureTool } = await import("./installer/index.js");
+		const installedPath = await ensureTool("madge");
+
+		if (installedPath) {
+			this.log(`Madge auto-installed: ${installedPath}`);
+			this.available = true;
+			return true;
+		}
+
+		this.log("Madge auto-install failed");
+		return false;
+	}
+
+	/**
+	 * Check if madge is available (legacy sync method)
+	 * Prefer ensureAvailable() for auto-install behavior
 	 */
 	isAvailable(): boolean {
 		if (this.available !== null) return this.available;