git-watchtower 1.14.15 → 1.14.16

package/bin/git-watchtower.js

@@ -104,6 +104,7 @@ const { WebDashboardServer } = require('../src/server/web');
 const { Coordinator, Worker, generateProjectId, getActiveCoordinator, tryAcquireLock, finalizeLock, removeLock, removeSocket, isProcessAlive } = require('../src/server/coordinator');
 const monitorLock = require('../src/utils/monitor-lock');
 const { createPipeErrorHandler } = require('../src/utils/pipe-error');
+const { getRecursiveWatchSupport } = require('../src/utils/fs-watch');
 
 const PROJECT_ROOT = process.cwd();
 
@@ -2290,6 +2291,21 @@ function setupFileWatcher() {
     addLog(`Loaded ${ignorePatterns.length} ignore patterns from .gitignore`, 'info');
   }
 
+  // Before calling fs.watch, surface any known incompatibility explicitly —
+  // the generic catch below would otherwise report a confusing
+  // "Could not set up file watcher: ..." for the well-known case of a
+  // forced install on Node <20 Linux, where recursive watching is
+  // unreliable. A clear message points the user at the real fix
+  // (upgrade Node) instead of making them debug a live-reload that
+  // appears to work but silently ignores subdirectory edits.
+  const support = getRecursiveWatchSupport();
+  if (!support.supported) {
+    addLog(
+      `Live reload may miss nested file changes: ${support.reason}`,
+      'error',
+    );
+  }
+
   try {
     fileWatcher = fs.watch(STATIC_DIR, { recursive: true }, (eventType, filename) => {
       if (!filename) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-watchtower",
-  "version": "1.14.15",
+  "version": "1.14.16",
   "description": "Terminal-based Git branch monitor with activity sparklines and optional dev server with live reload",
   "main": "bin/git-watchtower.js",
   "bin": {

package/src/utils/fs-watch.js

@@ -0,0 +1,84 @@
+/**
+ * fs.watch recursive-option support detection.
+ *
+ * `fs.watch(..., { recursive: true })` was not reliable on Linux before
+ * Node 20 — depending on the point release it either threw
+ * ERR_FEATURE_UNAVAILABLE_ON_PLATFORM or silently ignored the flag and
+ * watched only the top-level directory, leaving subdirectory changes
+ * undetected. macOS and Windows have supported recursive watching for
+ * much longer.
+ *
+ * git-watchtower declares engines.node >=20 in package.json, but users
+ * can bypass that with `npm install --force`. When they do, the static-
+ * server live-reload watcher needs to warn clearly rather than appear
+ * to work but silently miss edits in nested directories.
+ *
+ * @module utils/fs-watch
+ */
+
+'use strict';
+
+/**
+ * Parse `process.version` ("v20.11.1") into a numeric major version.
+ * Exported so tests can drive edge cases (malformed strings, pre-releases).
+ *
+ * @param {string} versionString
+ * @returns {number} major version, or NaN if unparseable
+ */
+function parseMajor(versionString) {
+  if (typeof versionString !== 'string') return NaN;
+  const match = /^v?(\d+)\./.exec(versionString);
+  if (!match) return NaN;
+  return parseInt(match[1], 10);
+}
+
+/**
+ * Decide whether fs.watch recursive mode is reliably supported on the
+ * current Node/platform combination.
+ *
+ * @param {Object} [env] - Injected for tests.
+ * @param {string} [env.version] - e.g. process.version
+ * @param {string} [env.platform] - e.g. process.platform
+ * @returns {{ supported: boolean, reason: string | null }}
+ *   reason is a short, user-facing explanation when !supported.
+ */
+function getRecursiveWatchSupport(env = {}) {
+  const version = env.version !== undefined ? env.version : process.version;
+  const platform = env.platform !== undefined ? env.platform : process.platform;
+
+  // macOS and Windows have supported recursive watching since well before
+  // any Node version we care about.
+  if (platform === 'darwin' || platform === 'win32') {
+    return { supported: true, reason: null };
+  }
+
+  if (platform === 'linux') {
+    const major = parseMajor(version);
+    if (Number.isNaN(major)) {
+      return {
+        supported: false,
+        reason: `could not parse Node version "${version}"`,
+      };
+    }
+    if (major < 20) {
+      return {
+        supported: false,
+        reason:
+          `Node ${version} on Linux does not reliably support fs.watch({ recursive: true }); ` +
+          'upgrade to Node >=20 (see package.json engines).',
+      };
+    }
+    return { supported: true, reason: null };
+  }
+
+  // Unknown platform (AIX, FreeBSD, etc.). Don't claim support we can't verify.
+  return {
+    supported: false,
+    reason: `recursive fs.watch support is not verified on platform "${platform}"`,
+  };
+}
+
+module.exports = {
+  parseMajor,
+  getRecursiveWatchSupport,
+};