@planu/cli 4.1.2 → 4.1.3

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [4.1.3] - 2026-05-21
+
+### Bug Fixes
+- Make the TypeScript file watcher fallback portable across operating systems by avoiding non-portable recursive `fs.watch` mode.
+- Keep the native-core fallback path non-fatal when a platform-specific binary is unavailable.
+
+### Tests
+- Add coverage to prevent reintroducing recursive watcher mode in the portable fallback.
+
+
 ## [4.1.2] - 2026-05-21
 
 ### Bug Fixes

package/dist/engine/core-bridge.js

@@ -180,6 +180,7 @@ const getNative = () => process.env.DISABLE_NATIVE_CORE === '1' ? null : nativeM
 const PROJECT_ID_RE = /^[a-f0-9]{16,64}$/;
 const SPEC_ANNOTATION_RE = /@spec\s+(SPEC-\d+)(?:\s+AC:([\d,]+))?(?:\s+(.*))?/;
 const SCANNABLE_EXTS = new Set(['.ts', '.js', '.tsx', '.jsx', '.rs', '.py', '.go']);
+const MAX_TS_WATCHERS = 128;
 const IGNORED_DIRS = new Set([
     'node_modules',
     '.git',
@@ -671,11 +672,41 @@ export function startNativeWatcher(rootPath, callback) {
         n.startProjectWatcher(rootPath, callback);
         return;
     }
-    // TS fallback: chokidar would be heavy; use fs.watch lazily.
+    // TS fallback: watch each existing directory. Node's `recursive: true` is not
+    // portable across all OS/libc combinations, and unsupported platforms must not
+    // crash the MCP server when the native watcher is unavailable.
     const fs = nodeFs;
-    fs.watch(rootPath, { recursive: true }, (event, filename) => {
-        callback(null, `${event}:${filename ?? ''}`);
-    });
+    let watcherCount = 0;
+    const watchDir = (absDir, relDir) => {
+        if (watcherCount >= MAX_TS_WATCHERS) {
+            return;
+        }
+        const watcher = fs.watch(absDir, {}, (event, filename) => {
+            callback(null, `${event}:${join(relDir, filename?.toString() ?? '')}`);
+        });
+        watcherCount++;
+        watcher.on('error', (err) => {
+            callback(err, '');
+        });
+    };
+    const walkDirs = (absDir, relDir) => {
+        watchDir(absDir, relDir);
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || IGNORED_DIRS.has(entry.name)) {
+                continue;
+            }
+            const childRel = join(relDir, entry.name);
+            walkDirs(join(absDir, entry.name), childRel);
+        }
+    };
+    walkDirs(rootPath, '');
 }
 export const isNativeActive = () => nativeModule !== null && process.env.DISABLE_NATIVE_CORE !== '1';
 export const nativeLoadDiagnostic = () => loadDiagnostic;

package/dist/engine/hooks/file-watcher.d.ts

@@ -18,9 +18,11 @@ export declare function matchesGlobPattern(filePath: string, pattern: string): b
 export declare function matchesPatterns(filePath: string, include?: string[], exclude?: string[]): boolean;
 export declare class FileWatcher extends EventEmitter {
     private watcher;
+    private readonly watchers;
     private readonly rootDir;
     private readonly include;
     private readonly exclude;
+    private readonly maxWatchers;
     /** Track known files to distinguish create vs modify */
     private readonly knownFiles;
     private closed;
@@ -42,6 +44,10 @@ export declare class FileWatcher extends EventEmitter {
      * Graceful shutdown: release all handles.
      */
     close(): void;
+    private startTypeScriptWatcher;
+    private watchDirectory;
+    private watchSubdirectories;
+    private emitWatcherError;
     private handleFsEvent;
     private determineEventType;
 }

package/dist/engine/hooks/file-watcher.js

@@ -1,6 +1,6 @@
 // engine/hooks/file-watcher.ts — File system watcher with normalized events (SPEC-129)
 import { EventEmitter } from 'node:events';
-import { watch } from 'node:fs';
+import { readdirSync, watch } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { normalize, join } from 'node:path';
 // ---------------------------------------------------------------------------
@@ -73,15 +73,22 @@ export function matchesPatterns(filePath, include, exclude) {
 // Default excludes
 // ---------------------------------------------------------------------------
 const DEFAULT_EXCLUDES = ['data/**', 'node_modules/**', '.git/**'];
+const DEFAULT_MAX_TS_WATCHERS = 128;
+function maxTypeScriptWatchers() {
+    const raw = Number(process.env.PLANU_MAX_TS_WATCHERS ?? DEFAULT_MAX_TS_WATCHERS);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_MAX_TS_WATCHERS;
+}
 // ---------------------------------------------------------------------------
 // FileWatcher
 // ---------------------------------------------------------------------------
 import { isNativeActive, startNativeWatcher } from '../core-bridge.js';
 export class FileWatcher extends EventEmitter {
     watcher = null;
+    watchers = new Set();
     rootDir;
     include;
     exclude;
+    maxWatchers = maxTypeScriptWatchers();
     /** Track known files to distinguish create vs modify */
     knownFiles = new Set();
     closed = false;
@@ -112,21 +119,11 @@ export class FileWatcher extends EventEmitter {
                 });
             }
             else {
-                this.watcher = watch(this.rootDir, { recursive: true }, (_eventType, filename) => {
-                    if (!filename || this.closed) {
-                        return;
-                    }
-                    // Normalize path separator
-                    const relPath = filename.replace(/\\/g, '/');
-                    void this.handleFsEvent(relPath);
-                });
-                this.watcher.on('error', (err) => {
-                    this.emit('error', err);
-                });
+                this.startTypeScriptWatcher();
             }
         }
         catch (err) {
-            this.emit('error', err);
+            this.emitWatcherError(err);
         }
     }
     /**
@@ -148,15 +145,71 @@ export class FileWatcher extends EventEmitter {
      */
     close() {
         this.closed = true;
-        if (this.watcher) {
-            this.watcher.close();
-            this.watcher = null;
+        for (const watcher of this.watchers) {
+            watcher.close();
         }
+        this.watchers.clear();
+        this.watcher = null;
         this.removeAllListeners();
     }
     // ---------------------------------------------------------------------------
     // Private
     // ---------------------------------------------------------------------------
+    startTypeScriptWatcher() {
+        this.watchDirectory(this.rootDir, '');
+        this.watchSubdirectories(this.rootDir, '');
+    }
+    watchDirectory(absDir, relDir) {
+        const watcher = watch(absDir, {}, (_eventType, filename) => {
+            if (!filename || this.closed) {
+                return;
+            }
+            const relPath = join(relDir, filename).replace(/\\/g, '/');
+            void this.handleFsEvent(relPath);
+        });
+        watcher.on('error', (err) => {
+            this.emitWatcherError(err);
+        });
+        this.watchers.add(watcher);
+        this.watcher ??= watcher;
+    }
+    watchSubdirectories(absDir, relDir) {
+        if (this.watchers.size >= this.maxWatchers) {
+            return;
+        }
+        let entries;
+        try {
+            entries = readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const childRel = join(relDir, entry.name).replace(/\\/g, '/');
+            if (this.exclude.some((p) => matchesGlobPattern(childRel, p))) {
+                continue;
+            }
+            const childAbs = join(absDir, entry.name);
+            try {
+                this.watchDirectory(childAbs, childRel);
+            }
+            catch {
+                continue;
+            }
+            if (this.watchers.size >= this.maxWatchers) {
+                return;
+            }
+            this.watchSubdirectories(childAbs, childRel);
+        }
+    }
+    emitWatcherError(err) {
+        if (this.listenerCount('error') > 0) {
+            this.emit('error', err);
+        }
+    }
     async handleFsEvent(relPath) {
         try {
             // Check exclude patterns first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +32,12 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.1.2",
-    "@planu/core-darwin-x64": "4.1.2",
-    "@planu/core-linux-arm64-gnu": "4.1.2",
-    "@planu/core-linux-arm64-musl": "4.1.2",
-    "@planu/core-linux-x64-gnu": "4.1.2",
-    "@planu/core-linux-x64-musl": "4.1.2"
+    "@planu/core-darwin-arm64": "4.1.3",
+    "@planu/core-darwin-x64": "4.1.3",
+    "@planu/core-linux-arm64-gnu": "4.1.3",
+    "@planu/core-linux-arm64-musl": "4.1.3",
+    "@planu/core-linux-x64-gnu": "4.1.3",
+    "@planu/core-linux-x64-musl": "4.1.3"
   },
   "engines": {
     "node": ">=24.0.0"