git-watchtower 2.1.17 → 2.2.0

package/bin/git-watchtower.js

@@ -76,6 +76,7 @@ const { openInBrowser: openUrl } = require('../src/utils/browser');
 const { playSound: playSoundEffect } = require('../src/utils/sound');
 const { parseArgs: parseCliArgs, applyCliArgsToConfig: mergeCliArgs, getHelpText, PACKAGE_VERSION } = require('../src/cli/args');
 const { checkForUpdate, startPeriodicUpdateCheck } = require('../src/utils/version-check');
+const { detectInstallSource, getUpdateCommand } = require('../src/utils/install-source');
 const { parseRemoteUrl, buildBranchUrl, detectPlatform, buildWebUrl, extractSessionUrl } = require('../src/git/remote');
 const { parseGitHubPr, parseGitLabMr, parseGitHubPrList, parseGitLabMrList, isBaseBranch } = require('../src/git/pr');
 
@@ -846,7 +847,7 @@ async function restartServerProcess() {
   // new process tried to bind a port the old one still held.
   try {
     await stopServerProcess();
-  } catch (_) { /* stopServerProcess never rejects in practice; best-effort */ }
+  } catch (_) {}
   if (isShuttingDown) return;
   startServerProcess();
   render();
@@ -2828,12 +2829,24 @@ function setupKeyboardInput() {
       }
       if (key === '\r' || key === '\n') {
         const selectedIdx = store.get('updateModalSelectedIndex') || 0;
+        const installSource = detectInstallSource();
+        const updateCmd = getUpdateCommand(installSource);
         if (selectedIdx === 0) {
-          // Update & restart — run npm i -g git-watchtower, then re-exec
+          // Update & restart — for npm/homebrew we shell out to the matching
+          // package manager, then re-exec. For source/unknown installs there
+          // is no automated upgrade, so degrade to surfacing the command.
+          if (installSource !== 'npm' && installSource !== 'homebrew') {
+            store.setState({ updateModalVisible: false, updateModalSelectedIndex: 0 });
+            showFlash(`Run: ${updateCmd}`);
+            return;
+          }
+          const [cmdBin, ...cmdArgs] = installSource === 'homebrew'
+            ? ['brew', 'upgrade', 'git-watchtower']
+            : ['npm', 'i', '-g', 'git-watchtower'];
           store.setState({ updateInProgress: true });
           render();
           const { spawn } = require('child_process');
-          const child = spawn('npm', ['i', '-g', 'git-watchtower'], {
+          const child = spawn(cmdBin, cmdArgs, {
             stdio: 'ignore',
             detached: false,
             shell: process.platform === 'win32',
@@ -2845,21 +2858,21 @@ function setupKeyboardInput() {
               addLog('Successfully updated git-watchtower! Restarting...', 'update');
               restartProcess();
             } else {
-              addLog(`Update failed (exit code ${code}). Run manually: npm i -g git-watchtower`, 'error');
-              showFlash('Update failed. Try manually: npm i -g git-watchtower');
+              addLog(`Update failed (exit code ${code}). Run manually: ${updateCmd}`, 'error');
+              showFlash(`Update failed. Try manually: ${updateCmd}`);
             }
             render();
           });
           child.on('error', (err) => {
             store.setState({ updateInProgress: false, updateModalVisible: false, updateModalSelectedIndex: 0 });
-            addLog(`Update failed: ${err.message}. Run manually: npm i -g git-watchtower`, 'error');
-            showFlash('Update failed. Try manually: npm i -g git-watchtower');
+            addLog(`Update failed: ${err.message}. Run manually: ${updateCmd}`, 'error');
+            showFlash(`Update failed. Try manually: ${updateCmd}`);
             render();
           });
         } else {
           // Show update command — dismiss modal with flash showing the command
           store.setState({ updateModalVisible: false, updateModalSelectedIndex: 0 });
-          showFlash('Run: npm i -g git-watchtower');
+          showFlash(`Run: ${updateCmd}`);
         }
         return;
       }
@@ -3289,10 +3302,20 @@ async function handleWebAction(action, payload) {
         break;
       case 'checkUpdate':
         if (payload && payload.install) {
+          const installSrc = detectInstallSource();
+          const updateCmdStr = getUpdateCommand(installSrc);
+          if (installSrc !== 'npm' && installSrc !== 'homebrew') {
+            sendResult(false, `Auto-update unavailable. Run: ${updateCmdStr}`);
+            addLog(`Auto-update unavailable for ${installSrc} install. Run manually: ${updateCmdStr}`, 'update');
+            break;
+          }
           store.setState({ updateInProgress: true });
           render();
           const { spawn: spawnUpdate } = require('child_process');
-          const updateChild = spawnUpdate('npm', ['i', '-g', 'git-watchtower'], {
+          const [updBin, ...updArgs] = installSrc === 'homebrew'
+            ? ['brew', 'upgrade', 'git-watchtower']
+            : ['npm', 'i', '-g', 'git-watchtower'];
+          const updateChild = spawnUpdate(updBin, updArgs, {
             stdio: 'ignore',
             detached: false,
           });
@@ -3305,7 +3328,7 @@ async function handleWebAction(action, payload) {
               restartProcess();
             } else {
               sendResult(false, `Update failed (exit code ${code})`);
-              addLog(`Update failed (exit code ${code}). Run manually: npm i -g git-watchtower`, 'error');
+              addLog(`Update failed (exit code ${code}). Run manually: ${updateCmdStr}`, 'error');
               render();
             }
           });
@@ -3517,10 +3540,10 @@ async function startWebDashboard(openBrowser) {
       webStateInterval = null;
     }
     if (webDashboard) {
-      try { webDashboard.stop(); } catch (_) { /* web server may not have bound yet — nothing to stop */ }
+      try { webDashboard.stop(); } catch (_) {}
     }
     if (coordinator) {
-      try { coordinator.stop(); } catch (_) { /* coordinator may not have started its IPC server */ }
+      try { coordinator.stop(); } catch (_) {}
     }
     removeLock();
     removeSocket();
@@ -3578,25 +3601,25 @@ function restartProcess() {
   // stdio is inherited — so any stray listener here will race with the child
   // (keystrokes consumed twice, render() drawing frames on top of the child's
   // UI, Ctrl+C intercepted by both, etc.).
-  try { process.stdin.removeAllListeners('data'); } catch (_) { /* stdin may be detached */ }
-  try { process.stdin.pause(); } catch (_) { /* stdin may already be paused */ }
-  try { process.stdout.removeAllListeners('resize'); } catch (_) { /* stdout may be detached */ }
-  try { process.removeAllListeners('SIGWINCH'); } catch (_) { /* no SIGWINCH handler registered */ }
-  try { process.removeAllListeners('SIGINT'); } catch (_) { /* no SIGINT handler registered */ }
-  try { process.removeAllListeners('SIGTERM'); } catch (_) { /* no SIGTERM handler registered */ }
+  try { process.stdin.removeAllListeners('data'); } catch (_) {}
+  try { process.stdin.pause(); } catch (_) {}
+  try { process.stdout.removeAllListeners('resize'); } catch (_) {}
+  try { process.removeAllListeners('SIGWINCH'); } catch (_) {}
+  try { process.removeAllListeners('SIGINT'); } catch (_) {}
+  try { process.removeAllListeners('SIGTERM'); } catch (_) {}
 
   // Stop every scheduler that can trigger a render while we're waiting on the
   // child. periodicUpdateCheck in particular will fire render() on completion
   // and would draw over the replacement's frames.
   if (pollIntervalId) {
-    try { clearTimeout(pollIntervalId); } catch (_) { /* defensive */ }
+    try { clearTimeout(pollIntervalId); } catch (_) {}
     pollIntervalId = null;
   }
   if (periodicUpdateCheck) {
-    try { periodicUpdateCheck.stop(); } catch (_) { /* interval may already be cleared */ }
+    try { periodicUpdateCheck.stop(); } catch (_) {}
   }
   if (fileWatcher) {
-    try { fileWatcher.close(); } catch (_) { /* watcher may already be closed */ }
+    try { fileWatcher.close(); } catch (_) {}
     fileWatcher = null;
   }
 
@@ -3612,7 +3635,7 @@ function restartProcess() {
   // child can acquire it. The parent stays alive waiting on child.on('close'),
   // so without this the child sees the parent as an active owner and refuses.
   if (monitorLockFile) {
-    try { monitorLock.release(monitorLockFile); } catch (_) { /* lock file may have already been unlinked */ }
+    try { monitorLock.release(monitorLockFile); } catch (_) {}
     monitorLockFile = null;
   }
 
@@ -3669,23 +3692,23 @@ function cleanupResources() {
 
   // Restore terminal first so the user sees a clean prompt even if a
   // later step throws.
-  try { write(ansi.showCursor); } catch (_) { /* stdout may be closed during crash cleanup */ }
-  try { write(ansi.restoreScreen); } catch (_) { /* stdout may be closed during crash cleanup */ }
-  try { restoreTerminalTitle(); } catch (_) { /* stdout may be closed during crash cleanup */ }
-  try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch (_) { /* stdin may already be unraw or detached */ }
-  try { process.stdin.pause(); } catch (_) { /* stdin may already be paused or destroyed */ }
+  try { write(ansi.showCursor); } catch (_) {}
+  try { write(ansi.restoreScreen); } catch (_) {}
+  try { restoreTerminalTitle(); } catch (_) {}
+  try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch (_) {}
+  try { process.stdin.pause(); } catch (_) {}
 
   if (pollIntervalId) {
-    try { clearTimeout(pollIntervalId); } catch (_) { /* defensive — clearTimeout normally won't throw */ }
+    try { clearTimeout(pollIntervalId); } catch (_) {}
     pollIntervalId = null;
   }
 
   if (periodicUpdateCheck) {
-    try { periodicUpdateCheck.stop(); } catch (_) { /* interval handle may already be cleared */ }
+    try { periodicUpdateCheck.stop(); } catch (_) {}
   }
 
   if (fileWatcher) {
-    try { fileWatcher.close(); } catch (_) { /* watcher may already be closed by OS or previous cleanup */ }
+    try { fileWatcher.close(); } catch (_) {}
     fileWatcher = null;
   }
 
@@ -3693,10 +3716,10 @@ function cleanupResources() {
   if (SERVER_MODE === 'static') {
     try {
       clients.forEach((client) => {
-        try { client.end(); } catch (_) { /* SSE client socket already closed */ }
+        try { client.end(); } catch (_) {}
       });
       clients.clear();
-    } catch (_) { /* clients set may have mutated mid-iteration during shutdown */ }
+    } catch (_) {}
   }
 
   // User's dev-server process (command mode). Capture the close promise so
@@ -3706,16 +3729,16 @@ function cleanupResources() {
   // orphan (it was spawned in its own process group on Unix).
   let serverStopPromise = Promise.resolve();
   if (SERVER_MODE === 'command') {
-    try { serverStopPromise = stopServerProcess(); } catch (_) { /* dev-server child may already be gone */ }
+    try { serverStopPromise = stopServerProcess(); } catch (_) {}
   }
 
   // Web dashboard + worker/coordinator (unlinks lock file + IPC socket)
-  try { stopWebDashboard(); } catch (_) { /* web dashboard may never have been started */ }
+  try { stopWebDashboard(); } catch (_) {}
 
   // Per-repo monitor lock — release last so the slot stays reserved for the
   // entire lifetime of this process, including any errors in the steps above.
   if (monitorLockFile) {
-    try { monitorLock.release(monitorLockFile); } catch (_) { /* lock file may have been unlinked externally */ }
+    try { monitorLock.release(monitorLockFile); } catch (_) {}
     monitorLockFile = null;
   }
 
@@ -3742,7 +3765,7 @@ async function shutdown() {
   // FORCE_KILL_GRACE_MS SIGKILL escalation inside stopServerProcess).
   // Without this the escalation timer gets dropped by process.exit() below
   // and a dev server that ignored SIGTERM survives as a detached orphan.
-  try { await serverStopPromise; } catch (_) { /* best-effort */ }
+  try { await serverStopPromise; } catch (_) {}
 
   // Flush telemetry
   telemetry.capture('session_ended', {
@@ -3774,7 +3797,7 @@ process.on('exit', () => {
 const stdioPipeErrorHandler = createPipeErrorHandler({
   onEpipe: () => {
     isShuttingDown = true;
-    try { cleanupResources(); } catch (_) { /* best-effort during pipe-close */ }
+    try { cleanupResources(); } catch (_) {}
     process.exit(0);
   },
   onOther: (err) => {
@@ -3793,12 +3816,12 @@ process.on('uncaughtException', async (err) => {
   // if telemetry shutdown hangs or throws.
   const serverStopPromise = cleanupResources();
 
-  try { telemetry.captureError(err); } catch (_) { /* telemetry must never prevent crash cleanup */ }
+  try { telemetry.captureError(err); } catch (_) {}
   console.error('Uncaught exception:', err);
-  try { await telemetry.shutdown(); } catch (_) { /* telemetry must never prevent crash cleanup */ }
+  try { await telemetry.shutdown(); } catch (_) {}
   // Wait for the dev-server SIGKILL escalation before exiting — otherwise
   // process.exit() drops the pending timer and a stuck server orphans.
-  try { await serverStopPromise; } catch (_) { /* best-effort */ }
+  try { await serverStopPromise; } catch (_) {}
   process.exit(1);
 });
 
@@ -3813,12 +3836,12 @@ process.on('unhandledRejection', async (reason) => {
   const serverStopPromise = cleanupResources();
 
   const err = reason instanceof Error ? reason : new Error(String(reason));
-  try { telemetry.captureError(err); } catch (_) { /* telemetry must never prevent crash cleanup */ }
+  try { telemetry.captureError(err); } catch (_) {}
   console.error('Unhandled rejection:', reason);
-  try { await telemetry.shutdown(); } catch (_) { /* telemetry must never prevent crash cleanup */ }
+  try { await telemetry.shutdown(); } catch (_) {}
   // Wait for the dev-server SIGKILL escalation before exiting — otherwise
   // process.exit() drops the pending timer and a stuck server orphans.
-  try { await serverStopPromise; } catch (_) { /* best-effort */ }
+  try { await serverStopPromise; } catch (_) {}
   process.exit(1);
 });
 
@@ -3892,7 +3915,10 @@ async function start() {
   const config = await ensureConfig(cliArgs);
   applyConfig(config);
 
-  // Telemetry: set version early so consent events include $lib_version
+  // Telemetry: set version early so consent events include $lib_version.
+  // Warm the install-source detector so the result is cached before any
+  // events fire — every subsequent queueEvent() call reuses it.
+  const installSource = detectInstallSource();
   telemetry.setVersion(PACKAGE_VERSION);
   await telemetry.promptIfNeeded(promptYesNo);
   telemetry.init({ version: PACKAGE_VERSION });
@@ -3904,6 +3930,7 @@ async function start() {
     server_mode: SERVER_MODE,
     has_config: !!loadConfig(),
     casino_mode: config.casinoMode || false,
+    install_source: installSource,
   });
 
   // Set up casino mode render callback for animations
@@ -4040,8 +4067,14 @@ async function start() {
   // Check for newer version on npm (non-blocking, silent on failure)
   checkForUpdate().then((latestVersion) => {
     if (latestVersion) {
-      store.setState({ updateAvailable: latestVersion, updateModalVisible: true });
-      addLog(`New version available: ${latestVersion} \u2192 npm i -g git-watchtower`, 'update');
+      const lastSeen = telemetry.getLastSeenUpdateVersion();
+      const shouldAutoPop = lastSeen !== latestVersion;
+      const upgradeCmd = getUpdateCommand(detectInstallSource());
+      store.setState({ updateAvailable: latestVersion, updateModalVisible: shouldAutoPop });
+      if (shouldAutoPop) {
+        try { telemetry.setLastSeenUpdateVersion(latestVersion); } catch (_) { /* persistence is best-effort */ }
+      }
+      addLog(`New version available: ${latestVersion} \u2192 ${upgradeCmd}`, 'update');
       render();
     }
   }).catch(() => { /* npm registry unreachable — periodic check will try again in 4h */ });
@@ -4053,8 +4086,10 @@ async function start() {
     store.setState({ updateAvailable: latestVersion });
     if (!alreadyKnown) {
       // First time discovering an update during this session — show modal
+      const upgradeCmd = getUpdateCommand(detectInstallSource());
       store.setState({ updateModalVisible: true });
-      addLog(`New version available: ${latestVersion} \u2192 npm i -g git-watchtower`, 'update');
+      try { telemetry.setLastSeenUpdateVersion(latestVersion); } catch (_) { /* persistence is best-effort */ }
+      addLog(`New version available: ${latestVersion} \u2192 ${upgradeCmd}`, 'update');
     }
     render();
   });

package/package.json

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

package/src/git/commands.js

@@ -100,18 +100,14 @@ async function execGit(args, options = {}) {
 }
 
 /**
- * Execute a git command, collapsing any failure into a null result.
- *
- * Callers use this when they want "the output, or nothing": the fallback
- * pattern `execGitOptional(A) || execGitOptional(B)` relies on this, as does
- * every caller that treats a missing result as "no data to show." This does
- * conflate "branch has no commits" (empty stdout, non-null result) with
- * "git errored" (null result) — if you need to distinguish those, use
- * execGit() and handle the throw yourself.
+ * Like execGit but returns null instead of throwing on failure. Use for
+ * the `execGitOptional(A) || execGitOptional(B)` fallback pattern. Note
+ * this conflates "command succeeded with empty stdout" (non-null result)
+ * with "command errored" (null) — use execGit if you need to distinguish.
  *
  * @param {string[]} command - Git arguments
  * @param {Object} [options] - Execution options
- * @returns {Promise<{stdout: string, stderr: string}|null>} Result, or null if git failed
+ * @returns {Promise<{stdout: string, stderr: string}|null>}
  */
 async function execGitOptional(command, options = {}) {
   try {

package/src/telemetry/analytics.js

@@ -7,6 +7,7 @@
 
 const https = require('https');
 const { isTelemetryEnabled, getOrCreateDistinctId } = require('./config');
+const { detectInstallSource } = require('../utils/install-source');
 
 const POSTHOG_API_KEY = 'phc_fdGL8TVN5aFPXmQ4f1hI8y6sqnscD7dy9j5SM5gTylG';
 const POSTHOG_HOST = 'us.i.posthog.com';
@@ -78,6 +79,7 @@ function queueEvent(event, properties, overrideDistinctId) {
       ...properties,
       $lib: 'git-watchtower',
       $lib_version: appVersion,
+      install_source: detectInstallSource(),
     },
     timestamp: new Date().toISOString(),
   });
@@ -179,6 +181,7 @@ function captureAlways(event, userDistinctId, properties = {}) {
           ...properties,
           $lib: 'git-watchtower',
           $lib_version: appVersion,
+          install_source: detectInstallSource(),
         },
         timestamp: new Date().toISOString(),
       }],

package/src/telemetry/config.js

@@ -30,8 +30,18 @@ function getConfigPath() {
 }
 
 /**
- * Load telemetry config from disk
- * @returns {{ telemetryEnabled: boolean, distinctId?: string, promptedAt: string } | null}
+ * @typedef {object} UserConfig
+ * @property {boolean} [telemetryEnabled]
+ * @property {string} [distinctId]
+ * @property {string} [promptedAt]
+ * @property {string} [lastSeenUpdateVersion]
+ */
+
+/**
+ * Load user config from disk. The same file persists telemetry preferences
+ * and update-modal state — fields are individually optional because the
+ * file may exist before the telemetry consent prompt has run.
+ * @returns {UserConfig | null}
  */
 function loadTelemetryConfig() {
   try {
@@ -55,7 +65,7 @@ function loadTelemetryConfig() {
  * handles the missing case by minting a fresh UUID if the user later
  * opts in.
  *
- * @param {{ telemetryEnabled: boolean, distinctId?: string, promptedAt: string }} config
+ * @param {UserConfig} config
  */
 function saveTelemetryConfig(config) {
   const dir = getConfigDir();
@@ -102,11 +112,15 @@ function isTelemetryEnabled() {
 }
 
 /**
- * Check if the user has already been prompted for telemetry
+ * Check if the user has already been prompted for telemetry.
+ * Looks specifically at `promptedAt` rather than config existence — the
+ * same file also stores non-telemetry preferences (e.g. lastSeenUpdateVersion),
+ * so a present file does not on its own mean the consent prompt has run.
  * @returns {boolean}
  */
 function hasBeenPrompted() {
-  return loadTelemetryConfig() !== null;
+  const config = loadTelemetryConfig();
+  return !!(config && typeof config.promptedAt === 'string');
 }
 
 /**
@@ -118,6 +132,33 @@ function isEnvDisabled() {
   return envVar !== undefined && envVar.toLowerCase() === 'false';
 }
 
+/**
+ * Get the last update version the user has been notified about.
+ * Used to suppress re-popping the update modal on subsequent launches
+ * for a version they've already seen.
+ * @returns {string | null}
+ */
+function getLastSeenUpdateVersion() {
+  const config = loadTelemetryConfig();
+  if (config && typeof config.lastSeenUpdateVersion === 'string') {
+    return config.lastSeenUpdateVersion;
+  }
+  return null;
+}
+
+/**
+ * Persist the version the user has just been notified about. Merges into
+ * the existing user-config file so telemetry preferences are preserved.
+ * @param {string} version
+ */
+function setLastSeenUpdateVersion(version) {
+  const existing = loadTelemetryConfig() || {};
+  saveTelemetryConfig({
+    ...existing,
+    lastSeenUpdateVersion: version,
+  });
+}
+
 module.exports = {
   getConfigDir,
   getConfigPath,
@@ -127,4 +168,6 @@ module.exports = {
   isTelemetryEnabled,
   hasBeenPrompted,
   isEnvDisabled,
+  getLastSeenUpdateVersion,
+  setLastSeenUpdateVersion,
 };

package/src/telemetry/index.js

@@ -104,4 +104,6 @@ module.exports = {
   hasBeenPrompted: config.hasBeenPrompted,
   loadTelemetryConfig: config.loadTelemetryConfig,
   saveTelemetryConfig: config.saveTelemetryConfig,
+  getLastSeenUpdateVersion: config.getLastSeenUpdateVersion,
+  setLastSeenUpdateVersion: config.setLastSeenUpdateVersion,
 };

package/src/ui/renderer.js

@@ -23,6 +23,7 @@ const {
 } = require('../ui/ansi');
 const { formatTimeAgo, formatTimeCompact } = require('../utils/time');
 const { isBaseBranch } = require('../git/pr');
+const { detectInstallSource, getUpdateCommand } = require('../utils/install-source');
 const { version: PACKAGE_VERSION } = require('../../package.json');
 
 // ---------------------------------------------------------------------------
@@ -1482,7 +1483,7 @@ function renderUpdateModal(state, write) {
 
   const latestVersion = state.updateAvailable;
   const currentVer = PACKAGE_VERSION;
-  const updateCmd = 'npm i -g git-watchtower';
+  const updateCmd = getUpdateCommand(detectInstallSource());
 
   const options = [
     'Update & restart',
@@ -1500,12 +1501,13 @@ function renderUpdateModal(state, write) {
   lines.push(`Current version:  v${currentVer}`);
   lines.push(`Latest version:   v${latestVersion}`);
   lines.push('');
+  // Command on its own plaintext line so a triple-click selects it cleanly.
+  lines.push(updateCmd);
+  lines.push('');
 
   if (state.updateInProgress) {
     lines.push('Updating...');
     lines.push('');
-    lines.push(`  ${updateCmd}`);
-    lines.push('');
     lines.push('Please wait...');
   } else {
     // Option lines
@@ -1517,7 +1519,7 @@ function renderUpdateModal(state, write) {
     lines.push('[Enter] Select  [Esc] Dismiss');
   }
 
-  const optionStartIdx = state.updateInProgress ? -1 : 5;
+  const optionStartIdx = state.updateInProgress ? -1 : 7;
   const height = lines.length + 2;
 
   // Draw magenta double-border box

package/src/utils/install-source.js

@@ -0,0 +1,87 @@
+/**
+ * Install source detection — figures out how the running CLI was installed
+ * (homebrew, npm global, source checkout) so the update flow can show the
+ * correct upgrade command instead of hardcoding `npm i -g git-watchtower`.
+ *
+ * Result is memoized for the life of the process — install source can't
+ * change between calls in the same run.
+ *
+ * @module utils/install-source
+ */
+
+const fs = require('fs');
+
+/** @typedef {'homebrew' | 'npm' | 'source' | 'unknown'} InstallSource */
+
+/** @type {InstallSource | null} */
+let _cached = null;
+let _detected = false;
+
+/**
+ * Classify a resolved entry-script path. Exposed for tests so they can
+ * exercise every branch with a synthetic path string.
+ *
+ * Order matters: homebrew installs ship via npm under the hood, so the
+ * resolved path contains both `Cellar` AND `node_modules`. Check Cellar
+ * first or homebrew users get classified as npm.
+ *
+ * @param {string} resolvedPath - Result of fs.realpathSync on the entry script
+ * @returns {InstallSource}
+ */
+function classifyPath(resolvedPath) {
+  const segments = resolvedPath.split(/[\\/]+/).map((s) => s.toLowerCase());
+  if (segments.includes('cellar') || segments.includes('homebrew')) return 'homebrew';
+  if (segments.includes('node_modules')) return 'npm';
+  return 'source';
+}
+
+/**
+ * Detect how the currently-running CLI was installed.
+ * Memoized — subsequent calls return the cached result.
+ * @returns {InstallSource}
+ */
+function detectInstallSource() {
+  if (_detected) return /** @type {InstallSource} */ (_cached);
+  _detected = true;
+  try {
+    const entry = process.argv[1] || (require.main && require.main.filename);
+    if (!entry) {
+      _cached = 'unknown';
+      return _cached;
+    }
+    _cached = classifyPath(fs.realpathSync(entry));
+  } catch {
+    _cached = 'unknown';
+  }
+  return _cached;
+}
+
+/**
+ * Get the user-facing upgrade command for a given install source.
+ * @param {InstallSource} source
+ * @returns {string}
+ */
+function getUpdateCommand(source) {
+  switch (source) {
+    case 'homebrew': return 'brew upgrade git-watchtower';
+    case 'npm':      return 'npm i -g git-watchtower';
+    case 'source':   return 'git pull && npm install';
+    default:         return 'npm i -g git-watchtower';
+  }
+}
+
+/**
+ * Reset the memoized result. Tests only — not part of the public API.
+ * @private
+ */
+function _resetForTests() {
+  _cached = null;
+  _detected = false;
+}
+
+module.exports = {
+  detectInstallSource,
+  getUpdateCommand,
+  classifyPath,
+  _resetForTests,
+};