switchman-dev 0.1.5 → 0.1.6

package/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}

package/README.md

@@ -131,6 +131,7 @@ More help:
 - [Status and recovery](docs/status-and-recovery.md)
 - [Merge queue](docs/merge-queue.md)
 - [Stale lease policy](docs/stale-lease-policy.md)
+- [Telemetry](docs/telemetry.md)
 
 ## More docs
 
@@ -138,6 +139,7 @@ More help:
 - [Pipelines and PRs](docs/pipelines.md)
 - [Stale lease policy](docs/stale-lease-policy.md)
 - [MCP tools](docs/mcp-tools.md)
+- [Telemetry](docs/telemetry.md)
 - [Command reference](docs/command-reference.md)
 
 ## Feedback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchman-dev",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Project manager for AI coding assistants running safely on one codebase",
   "type": "module",
   "main": "src/index.js",

package/src/cli/index.js

@@ -44,6 +44,16 @@ import { installGitHubActionsWorkflow, resolveGitHubOutputTargets, writeGitHubCi
 import { importCodeObjectsToStore, listCodeObjects, materializeCodeObjects, materializeSemanticIndex, updateCodeObjectSource } from '../core/semantic.js';
 import { buildQueueStatusSummary, runMergeQueue } from '../core/queue.js';
 import { DEFAULT_LEASE_POLICY, loadLeasePolicy, writeLeasePolicy } from '../core/policy.js';
+import {
+  captureTelemetryEvent,
+  disableTelemetry,
+  enableTelemetry,
+  getTelemetryConfigPath,
+  getTelemetryRuntimeConfig,
+  loadTelemetryConfig,
+  maybePromptForTelemetry,
+  sendTelemetryEvent,
+} from '../core/telemetry.js';
 
 function installMcpConfig(targetDirs) {
   return targetDirs.flatMap((targetDir) => upsertAllProjectMcpConfigs(targetDir));
@@ -224,6 +234,20 @@ function printErrorWithNext(message, nextCommand = null) {
   }
 }
 
+async function maybeCaptureTelemetry(event, properties = {}, { homeDir = null } = {}) {
+  try {
+    await maybePromptForTelemetry({ homeDir: homeDir || undefined });
+    await captureTelemetryEvent(event, {
+      app_version: program.version(),
+      os: process.platform,
+      node_version: process.version,
+      ...properties,
+    }, { homeDir: homeDir || undefined });
+  } catch {
+    // Telemetry must never block CLI usage.
+  }
+}
+
 function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
   const dbPath = join(repoRoot, '.switchman', 'switchman.db');
   const rootMcpPath = join(repoRoot, '.mcp.json');
@@ -1133,7 +1157,7 @@ Examples:
   switchman setup --agents 5
   switchman setup --agents 3 --prefix team
 `)
-  .action((opts) => {
+  .action(async (opts) => {
     const agentCount = parseInt(opts.agents);
 
     if (isNaN(agentCount) || agentCount < 1 || agentCount > 10) {
@@ -1217,6 +1241,10 @@ Examples:
 
       const verification = collectSetupVerification(repoRoot);
       renderSetupVerification(verification, { compact: true });
+      await maybeCaptureTelemetry('setup_completed', {
+        agent_count: agentCount,
+        verification_ok: verification.ok,
+      });
 
     } catch (err) {
       spinner.fail(err.message);
@@ -1236,7 +1264,7 @@ Examples:
 
 Use this after setup or whenever editor/config wiring feels off.
 `)
-  .action((opts) => {
+  .action(async (opts) => {
     const repoRoot = getRepo();
     const report = collectSetupVerification(repoRoot, { homeDir: opts.home || null });
 
@@ -1247,6 +1275,10 @@ Use this after setup or whenever editor/config wiring feels off.
     }
 
     renderSetupVerification(report);
+    await maybeCaptureTelemetry(report.ok ? 'verify_setup_passed' : 'verify_setup_failed', {
+      check_count: report.checks.length,
+      next_step_count: report.next_steps.length,
+    }, { homeDir: opts.home || null });
     if (!report.ok) process.exitCode = 1;
   });
 
@@ -1254,6 +1286,101 @@ Use this after setup or whenever editor/config wiring feels off.
 // ── mcp ───────────────────────────────────────────────────────────────────────
 
 const mcpCmd = program.command('mcp').description('Manage editor connections for Switchman');
+const telemetryCmd = program.command('telemetry').description('Control anonymous opt-in telemetry for Switchman');
+
+telemetryCmd
+  .command('status')
+  .description('Show whether telemetry is enabled and where events would be sent')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const config = loadTelemetryConfig(opts.home || undefined);
+    const runtime = getTelemetryRuntimeConfig();
+    const payload = {
+      enabled: config.telemetry_enabled === true,
+      configured: Boolean(runtime.apiKey) && !runtime.disabled,
+      install_id: config.telemetry_install_id,
+      destination: runtime.apiKey && !runtime.disabled ? runtime.host : null,
+      config_path: getTelemetryConfigPath(opts.home || undefined),
+    };
+
+    if (opts.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    console.log(`Telemetry: ${payload.enabled ? chalk.green('enabled') : chalk.yellow('disabled')}`);
+    console.log(`Configured destination: ${payload.configured ? chalk.cyan(payload.destination) : chalk.dim('not configured')}`);
+    console.log(`Config file: ${chalk.dim(payload.config_path)}`);
+    if (payload.install_id) {
+      console.log(`Install ID: ${chalk.dim(payload.install_id)}`);
+    }
+  });
+
+telemetryCmd
+  .command('enable')
+  .description('Enable anonymous telemetry for setup and operator workflows')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .action((opts) => {
+    const runtime = getTelemetryRuntimeConfig();
+    if (!runtime.apiKey || runtime.disabled) {
+      printErrorWithNext('Telemetry destination is not configured. Set SWITCHMAN_TELEMETRY_API_KEY first.', 'switchman telemetry status');
+      process.exitCode = 1;
+      return;
+    }
+    const result = enableTelemetry(opts.home || undefined);
+    console.log(`${chalk.green('✓')} Telemetry enabled`);
+    console.log(`  ${chalk.dim(result.path)}`);
+  });
+
+telemetryCmd
+  .command('disable')
+  .description('Disable anonymous telemetry')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .action((opts) => {
+    const result = disableTelemetry(opts.home || undefined);
+    console.log(`${chalk.green('✓')} Telemetry disabled`);
+    console.log(`  ${chalk.dim(result.path)}`);
+  });
+
+telemetryCmd
+  .command('test')
+  .description('Send one test telemetry event and report whether delivery succeeded')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const result = await sendTelemetryEvent('telemetry_test', {
+      app_version: program.version(),
+      os: process.platform,
+      node_version: process.version,
+      source: 'switchman-cli-test',
+    }, { homeDir: opts.home || undefined });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+
+    if (result.ok) {
+      console.log(`${chalk.green('✓')} Telemetry test event delivered`);
+      console.log(`  ${chalk.dim('destination:')} ${chalk.cyan(result.destination)}`);
+      if (result.status) {
+        console.log(`  ${chalk.dim('status:')} ${result.status}`);
+      }
+      return;
+    }
+
+    printErrorWithNext(`Telemetry test failed (${result.reason || 'unknown_error'}).`, 'switchman telemetry status');
+    console.log(`  ${chalk.dim('destination:')} ${result.destination || 'unknown'}`);
+    if (result.status) {
+      console.log(`  ${chalk.dim('status:')} ${result.status}`);
+    }
+    if (result.error) {
+      console.log(`  ${chalk.dim('error:')} ${result.error}`);
+    }
+    process.exitCode = 1;
+  });
 
 mcpCmd
   .command('install')
@@ -1714,6 +1841,13 @@ Examples:
 
       if (aggregate.processed.length === 0) {
         console.log(chalk.dim('No queued merge items.'));
+        await maybeCaptureTelemetry('queue_used', {
+          watch,
+          cycles: aggregate.cycles,
+          processed_count: 0,
+          merged_count: 0,
+          blocked_count: 0,
+        });
         return;
       }
 
@@ -1728,6 +1862,14 @@ Examples:
           if (item.next_action) console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
         }
       }
+
+      await maybeCaptureTelemetry('queue_used', {
+        watch,
+        cycles: aggregate.cycles,
+        processed_count: aggregate.processed.length,
+        merged_count: aggregate.processed.filter((entry) => entry.status === 'merged').length,
+        blocked_count: aggregate.processed.filter((entry) => entry.status !== 'merged').length,
+      });
     } catch (err) {
       console.error(chalk.red(err.message));
       process.exitCode = 1;
@@ -2834,6 +2976,13 @@ Use this first when the repo feels stuck.
       if (opts.json) break;
       sleepSync(watchIntervalMs);
     }
+
+    if (watch) {
+      await maybeCaptureTelemetry('status_watch_used', {
+        cycles,
+        interval_ms: watchIntervalMs,
+      });
+    }
   });
 
 program
@@ -3145,6 +3294,15 @@ gateCmd
       }
     }
 
+    await maybeCaptureTelemetry(ok ? 'gate_ci_passed' : 'gate_ci_failed', {
+      worktree_count: report.worktrees.length,
+      unclaimed_change_count: result.unclaimed_changes.length,
+      file_conflict_count: result.file_conflicts.length,
+      ownership_conflict_count: result.ownership_conflicts.length,
+      semantic_conflict_count: result.semantic_conflicts.length,
+      branch_conflict_count: result.branch_conflicts.length,
+    });
+
     if (!ok) process.exitCode = 1;
   });
 

package/src/core/telemetry.js

@@ -0,0 +1,210 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { randomUUID } from 'crypto';
+import readline from 'readline/promises';
+
+export const DEFAULT_TELEMETRY_HOST = 'https://us.i.posthog.com';
+
+function normalizeBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value !== 'string') return null;
+  const lowered = value.trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(lowered)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(lowered)) return false;
+  return null;
+}
+
+export function getTelemetryConfigPath(homeDir = homedir()) {
+  return join(homeDir, '.switchman', 'config.json');
+}
+
+export function getTelemetryRuntimeConfig(env = process.env) {
+  return {
+    apiKey: env.SWITCHMAN_TELEMETRY_API_KEY || env.POSTHOG_API_KEY || null,
+    host: env.SWITCHMAN_TELEMETRY_HOST || env.POSTHOG_HOST || DEFAULT_TELEMETRY_HOST,
+    disabled: normalizeBoolean(env.SWITCHMAN_TELEMETRY_DISABLED) === true,
+  };
+}
+
+export function loadTelemetryConfig(homeDir = homedir()) {
+  const configPath = getTelemetryConfigPath(homeDir);
+  if (!existsSync(configPath)) {
+    return {
+      telemetry_enabled: null,
+      telemetry_install_id: null,
+      telemetry_prompted_at: null,
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+    return {
+      telemetry_enabled: typeof parsed?.telemetry_enabled === 'boolean' ? parsed.telemetry_enabled : null,
+      telemetry_install_id: typeof parsed?.telemetry_install_id === 'string' ? parsed.telemetry_install_id : null,
+      telemetry_prompted_at: typeof parsed?.telemetry_prompted_at === 'string' ? parsed.telemetry_prompted_at : null,
+    };
+  } catch {
+    return {
+      telemetry_enabled: null,
+      telemetry_install_id: null,
+      telemetry_prompted_at: null,
+    };
+  }
+}
+
+export function writeTelemetryConfig(homeDir = homedir(), config = {}) {
+  const configPath = getTelemetryConfigPath(homeDir);
+  mkdirSync(dirname(configPath), { recursive: true });
+  const normalized = {
+    telemetry_enabled: typeof config.telemetry_enabled === 'boolean' ? config.telemetry_enabled : null,
+    telemetry_install_id: typeof config.telemetry_install_id === 'string' ? config.telemetry_install_id : (config.telemetry_enabled ? randomUUID() : null),
+    telemetry_prompted_at: typeof config.telemetry_prompted_at === 'string' ? config.telemetry_prompted_at : null,
+  };
+  writeFileSync(configPath, `${JSON.stringify(normalized, null, 2)}\n`);
+  return { path: configPath, config: normalized };
+}
+
+export function enableTelemetry(homeDir = homedir()) {
+  const current = loadTelemetryConfig(homeDir);
+  return writeTelemetryConfig(homeDir, {
+    ...current,
+    telemetry_enabled: true,
+    telemetry_install_id: current.telemetry_install_id || randomUUID(),
+    telemetry_prompted_at: new Date().toISOString(),
+  });
+}
+
+export function disableTelemetry(homeDir = homedir()) {
+  const current = loadTelemetryConfig(homeDir);
+  return writeTelemetryConfig(homeDir, {
+    ...current,
+    telemetry_enabled: false,
+    telemetry_install_id: current.telemetry_install_id || randomUUID(),
+    telemetry_prompted_at: new Date().toISOString(),
+  });
+}
+
+export async function maybePromptForTelemetry({ homeDir = homedir(), stdin = process.stdin, stdout = process.stdout, env = process.env } = {}) {
+  const runtime = getTelemetryRuntimeConfig(env);
+  if (!runtime.apiKey || runtime.disabled) {
+    return { prompted: false, enabled: false, available: Boolean(runtime.apiKey) && !runtime.disabled };
+  }
+
+  const current = loadTelemetryConfig(homeDir);
+  if (typeof current.telemetry_enabled === 'boolean') {
+    return { prompted: false, enabled: current.telemetry_enabled, available: true };
+  }
+
+  if (!stdin?.isTTY || !stdout?.isTTY) {
+    return { prompted: false, enabled: false, available: true };
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    stdout.write('\nHelp improve Switchman?\n');
+    stdout.write('If you opt in, Switchman will send anonymous usage events like setup success,\n');
+    stdout.write('verify-setup pass, status --watch, queue usage, and gate outcomes.\n');
+    stdout.write('No code, prompts, file contents, repo names, or secrets are collected.\n\n');
+    const answer = await rl.question('Enable telemetry? [y/N] ');
+    const enabled = ['y', 'yes'].includes(String(answer || '').trim().toLowerCase());
+    if (enabled) {
+      enableTelemetry(homeDir);
+    } else {
+      disableTelemetry(homeDir);
+    }
+    return { prompted: true, enabled, available: true };
+  } finally {
+    rl.close();
+  }
+}
+
+export async function captureTelemetryEvent(event, properties = {}, {
+  homeDir = homedir(),
+  env = process.env,
+  timeoutMs = 1500,
+} = {}) {
+  const result = await sendTelemetryEvent(event, properties, {
+    homeDir,
+    env,
+    timeoutMs,
+  });
+  return result.ok;
+}
+
+export async function sendTelemetryEvent(event, properties = {}, {
+  homeDir = homedir(),
+  env = process.env,
+  timeoutMs = 1500,
+} = {}) {
+  const runtime = getTelemetryRuntimeConfig(env);
+  if (!runtime.apiKey) {
+    return {
+      ok: false,
+      reason: 'not_configured',
+      status: null,
+      destination: runtime.host,
+    };
+  }
+  if (runtime.disabled) {
+    return {
+      ok: false,
+      reason: 'disabled_by_env',
+      status: null,
+      destination: runtime.host,
+    };
+  }
+  if (typeof fetch !== 'function') {
+    return {
+      ok: false,
+      reason: 'fetch_unavailable',
+      status: null,
+      destination: runtime.host,
+    };
+  }
+
+  const config = loadTelemetryConfig(homeDir);
+  if (config.telemetry_enabled !== true || !config.telemetry_install_id) {
+    return {
+      ok: false,
+      reason: 'not_enabled',
+      status: null,
+      destination: runtime.host,
+    };
+  }
+
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const response = await fetch(`${runtime.host.replace(/\/$/, '')}/capture/`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        api_key: runtime.apiKey,
+        event,
+        distinct_id: config.telemetry_install_id,
+        properties: {
+          source: 'switchman-cli',
+          ...properties,
+        },
+        timestamp: new Date().toISOString(),
+      }),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    return {
+      ok: response.ok,
+      reason: response.ok ? null : 'http_error',
+      status: response.status,
+      destination: runtime.host,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: err?.name === 'AbortError' ? 'timeout' : 'network_error',
+      status: null,
+      destination: runtime.host,
+      error: String(err?.message || err),
+    };
+  }
+}