git-watchtower 1.6.0 → 1.7.0

package/src/telemetry/analytics.js

@@ -0,0 +1,142 @@
+/**
+ * PostHog analytics wrapper (singleton)
+ *
+ * All methods are safe no-ops when telemetry is disabled.
+ * Events are fire-and-forget — never blocks the TUI.
+ */
+
+const { isTelemetryEnabled, getOrCreateDistinctId } = require('./config');
+
+const POSTHOG_API_KEY = 'phc_fdGL8TVN5aFPXmQ4f1hI8y6sqnscD7dy9j5SM5gTylG';
+const POSTHOG_HOST = 'https://us.i.posthog.com';
+
+/** @type {import('posthog-node').PostHog | null} */
+let client = null;
+let distinctId = '';
+let appVersion = '';
+let enabled = false;
+
+/**
+ * Initialize the PostHog client if telemetry is enabled
+ * @param {{ version: string }} options
+ */
+function init({ version }) {
+  appVersion = version;
+
+  if (!isTelemetryEnabled()) {
+    enabled = false;
+    return;
+  }
+
+  try {
+    const { PostHog } = require('posthog-node');
+    distinctId = getOrCreateDistinctId();
+    client = new PostHog(POSTHOG_API_KEY, {
+      host: POSTHOG_HOST,
+      flushAt: 10,
+      flushInterval: 30000,
+      requestTimeout: 5000,
+      disableGeoip: true,
+    });
+    enabled = true;
+  } catch {
+    // If posthog-node fails to load, silently disable telemetry
+    enabled = false;
+    client = null;
+  }
+}
+
+/**
+ * Capture an analytics event (fire-and-forget)
+ * @param {string} event - Event name
+ * @param {Record<string, any>} [properties] - Event properties
+ */
+function capture(event, properties = {}) {
+  if (!enabled || !client) return;
+
+  try {
+    client.capture({
+      distinctId,
+      event,
+      properties: {
+        ...properties,
+        $lib: 'git-watchtower',
+        $lib_version: appVersion,
+      },
+    });
+  } catch {
+    // Never let telemetry errors affect the app
+  }
+}
+
+/**
+ * Capture an error for PostHog error tracking
+ * @param {Error} error
+ */
+function captureError(error) {
+  if (!enabled || !client) return;
+
+  try {
+    const errorType = error.constructor?.name || 'Error';
+    const errorCode = /** @type {any} */ (error).code || '';
+    const errorMessage = errorCode || (error.message || '').substring(0, 200);
+
+    /** @type {Record<string, any>} */
+    const properties = {
+      $exception_type: errorType,
+      $exception_message: errorMessage,
+      $exception_source: 'node',
+      $lib: 'git-watchtower',
+      $lib_version: appVersion,
+    };
+
+    // Include stack trace — contains only our package's file paths and
+    // line numbers, no user data. Required for PostHog error tracking
+    // to group, deduplicate, and show useful backtraces.
+    if (error.stack) {
+      properties.$exception_stack_trace_raw = error.stack;
+    }
+
+    client.capture({
+      distinctId,
+      event: '$exception',
+      properties,
+    });
+  } catch {
+    // Never let telemetry errors affect the app
+  }
+}
+
+/**
+ * Flush pending events and shutdown the PostHog client
+ * Call this before process exit to ensure events are sent.
+ * @returns {Promise<void>}
+ */
+async function shutdown() {
+  if (!enabled || !client) return;
+
+  try {
+    await client.shutdown();
+  } catch {
+    // Best-effort flush
+  } finally {
+    client = null;
+    enabled = false;
+  }
+}
+
+/**
+ * Check if telemetry is currently active
+ * @returns {boolean}
+ */
+function isEnabled() {
+  return enabled;
+}
+
+module.exports = {
+  init,
+  capture,
+  captureError,
+  shutdown,
+  isEnabled,
+};

package/src/telemetry/config.js

@@ -0,0 +1,123 @@
+/**
+ * Telemetry configuration management
+ *
+ * Stores telemetry preferences in ~/.git-watchtower/config.json
+ * (separate from per-project .watchtowerrc.json).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+const CONFIG_DIR_NAME = '.git-watchtower';
+const CONFIG_FILE_NAME = 'config.json';
+
+/**
+ * Get the telemetry config directory path
+ * @returns {string}
+ */
+function getConfigDir() {
+  return path.join(os.homedir(), CONFIG_DIR_NAME);
+}
+
+/**
+ * Get the telemetry config file path
+ * @returns {string}
+ */
+function getConfigPath() {
+  return path.join(getConfigDir(), CONFIG_FILE_NAME);
+}
+
+/**
+ * Load telemetry config from disk
+ * @returns {{ telemetryEnabled: boolean, distinctId: string, promptedAt: string } | null}
+ */
+function loadTelemetryConfig() {
+  try {
+    const data = fs.readFileSync(getConfigPath(), 'utf8');
+    const config = JSON.parse(data);
+    if (config && typeof config === 'object') {
+      return config;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save telemetry config to disk
+ * @param {{ telemetryEnabled: boolean, distinctId: string, promptedAt: string }} config
+ */
+function saveTelemetryConfig(config) {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Get existing distinctId or create a new one
+ * @returns {string}
+ */
+function getOrCreateDistinctId() {
+  const config = loadTelemetryConfig();
+  if (config && config.distinctId) {
+    return config.distinctId;
+  }
+  return crypto.randomUUID();
+}
+
+/**
+ * Check if telemetry is enabled
+ *
+ * Priority:
+ * 1. GIT_WATCHTOWER_TELEMETRY=false env var always disables (CI/corporate)
+ * 2. If no config file exists, telemetry is disabled (not yet prompted)
+ * 3. Otherwise, return the stored preference
+ *
+ * @returns {boolean}
+ */
+function isTelemetryEnabled() {
+  const envVar = process.env.GIT_WATCHTOWER_TELEMETRY;
+  if (envVar !== undefined && envVar.toLowerCase() === 'false') {
+    return false;
+  }
+
+  const config = loadTelemetryConfig();
+  if (!config) {
+    return false;
+  }
+
+  return config.telemetryEnabled === true;
+}
+
+/**
+ * Check if the user has already been prompted for telemetry
+ * @returns {boolean}
+ */
+function hasBeenPrompted() {
+  return loadTelemetryConfig() !== null;
+}
+
+/**
+ * Check if telemetry is force-disabled via environment variable
+ * @returns {boolean}
+ */
+function isEnvDisabled() {
+  const envVar = process.env.GIT_WATCHTOWER_TELEMETRY;
+  return envVar !== undefined && envVar.toLowerCase() === 'false';
+}
+
+module.exports = {
+  getConfigDir,
+  getConfigPath,
+  loadTelemetryConfig,
+  saveTelemetryConfig,
+  getOrCreateDistinctId,
+  isTelemetryEnabled,
+  hasBeenPrompted,
+  isEnvDisabled,
+};

package/src/telemetry/index.js

@@ -0,0 +1,93 @@
+/**
+ * Telemetry public API
+ *
+ * Usage:
+ *   const telemetry = require('../src/telemetry');
+ *   await telemetry.promptIfNeeded(promptYesNoFn);
+ *   telemetry.init({ version: '1.6.1' });
+ *   telemetry.capture('tool_launched', { os: 'linux' });
+ *   await telemetry.shutdown();
+ */
+
+const analytics = require('./analytics');
+const config = require('./config');
+
+/**
+ * Show opt-in telemetry prompt if the user hasn't been asked yet.
+ *
+ * Skips the prompt when:
+ * - Already prompted (config file exists)
+ * - Env var forces telemetry off
+ * - No TTY (non-interactive / CI)
+ *
+ * @param {(question: string, defaultValue?: boolean) => Promise<boolean>} promptYesNo
+ */
+async function promptIfNeeded(promptYesNo) {
+  // Already prompted — respect existing choice
+  if (config.hasBeenPrompted()) {
+    return;
+  }
+
+  // Env var forces off — no point asking
+  if (config.isEnvDisabled()) {
+    return;
+  }
+
+  // Non-interactive — default to disabled
+  if (!process.stdin.isTTY) {
+    return;
+  }
+
+  console.log('');
+  console.log('\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510');
+  console.log('\u2502  Help improve Git Watchtower                            \u2502');
+  console.log('\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524');
+  console.log('\u2502  We\'d love to collect anonymous usage data to improve    \u2502');
+  console.log('\u2502  Git Watchtower. This telemetry is used to improve the  \u2502');
+  console.log('\u2502  product. It includes:                                  \u2502');
+  console.log('\u2502    - Which features are used (not your code or data)    \u2502');
+  console.log('\u2502    - Error types encountered (not stack traces)         \u2502');
+  console.log('\u2502    - Session duration and OS/Node.js version            \u2502');
+  console.log('\u2502                                                         \u2502');
+  console.log('\u2502  No personal information, file contents, branch names,  \u2502');
+  console.log('\u2502  or repository data is ever collected.                  \u2502');
+  console.log('\u2502                                                         \u2502');
+  console.log('\u2502  You can change this anytime by editing:                \u2502');
+  console.log('\u2502    ~/.git-watchtower/config.json                        \u2502');
+  console.log('\u2502  Or set GIT_WATCHTOWER_TELEMETRY=false                  \u2502');
+  console.log('\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518');
+  console.log('');
+
+  const answer = await promptYesNo('Enable anonymous telemetry to help improve Git Watchtower?', false);
+
+  const distinctId = config.getOrCreateDistinctId();
+  config.saveTelemetryConfig({
+    telemetryEnabled: answer,
+    distinctId,
+    promptedAt: new Date().toISOString(),
+  });
+
+  if (answer) {
+    console.log('  Thank you! Telemetry enabled.\n');
+  } else {
+    console.log('  No problem! Telemetry disabled.\n');
+  }
+}
+
+module.exports = {
+  // Analytics
+  init: analytics.init,
+  capture: analytics.capture,
+  captureError: analytics.captureError,
+  shutdown: analytics.shutdown,
+  isEnabled: analytics.isEnabled,
+
+  // Prompt
+  promptIfNeeded,
+
+  // Config (for advanced use)
+  isTelemetryEnabled: config.isTelemetryEnabled,
+  hasBeenPrompted: config.hasBeenPrompted,
+  loadTelemetryConfig: config.loadTelemetryConfig,
+  saveTelemetryConfig: config.saveTelemetryConfig,
+};