content-grade 1.0.0

package/bin/telemetry.js

@@ -0,0 +1,230 @@
+/**
+ * ContentGrade Telemetry
+ *
+ * Privacy-first, anonymous usage tracking.
+ * - No file contents, no PII, no account info
+ * - Stored locally at ~/.content-grade/events.jsonl
+ * - Opt out: --no-telemetry flag, CONTENT_GRADE_NO_TELEMETRY=1, or run: content-grade telemetry off
+ * - Remote endpoint: set CONTENT_GRADE_TELEMETRY_URL to forward events
+ */
+
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { createHash } from 'crypto';
+
+const CONFIG_DIR   = join(homedir(), '.content-grade');
+const CONFIG_FILE  = join(CONFIG_DIR, 'config.json');
+const EVENTS_FILE  = join(CONFIG_DIR, 'events.jsonl');
+
+// Telemetry endpoint: set CONTENT_GRADE_TELEMETRY_URL to enable remote reporting
+const REMOTE_URL = process.env.CONTENT_GRADE_TELEMETRY_URL || null;
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function ensureDir() {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+}
+
+function loadConfig() {
+  try { return JSON.parse(readFileSync(CONFIG_FILE, 'utf8')); }
+  catch { return null; }
+}
+
+function saveConfig(cfg) {
+  ensureDir();
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
+}
+
+function generateId() {
+  return createHash('sha256')
+    .update(`${Date.now()}-${Math.random()}-${process.pid}-${homedir()}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Check if telemetry is disabled.
+ * Order of precedence: CLI flag > env var > config file.
+ */
+export function isOptedOut() {
+  if (process.argv.includes('--no-telemetry')) return true;
+  if (process.env.CONTENT_GRADE_NO_TELEMETRY === '1') return true;
+  const cfg = loadConfig();
+  return cfg?.telemetryEnabled === false;
+}
+
+/**
+ * Initialise telemetry on CLI startup.
+ * Returns { installId, isNew, optedOut }.
+ * isNew=true means this is the first time the CLI has run — show the notice.
+ */
+export function initTelemetry() {
+  if (isOptedOut()) return { installId: null, isNew: false, optedOut: true };
+
+  const cfg = loadConfig();
+
+  if (cfg?.installId) {
+    return { installId: cfg.installId, isNew: false, optedOut: false };
+  }
+
+  // First run — generate anonymous install ID
+  const installId = generateId();
+  saveConfig({
+    installId,
+    installedAt: new Date().toISOString(),
+    telemetryEnabled: true,
+  });
+
+  // Record install event
+  _write({ event: 'install', installId, platform: process.platform, nodeVersion: process.version });
+
+  return { installId, isNew: true, optedOut: false };
+}
+
+/**
+ * Record a usage event.
+ * Safe to call from anywhere — never throws, never blocks CLI.
+ *
+ * Tracked fields (safe, no PII):
+ *   event         — 'command'
+ *   command       — 'analyze' | 'headline' | 'demo' | 'start' | 'init' | 'help'
+ *   duration_ms   — wall time
+ *   success       — boolean
+ *   exit_code     — process exit code (set by trackCommand)
+ *   score         — numeric score if available (analyze/headline result)
+ *   content_type  — content category if available (analyze result)
+ *   version       — CLI version
+ */
+export function recordEvent(data) {
+  if (isOptedOut()) return;
+
+  const cfg = loadConfig();
+  const installId = cfg?.installId;
+  if (!installId) return; // shouldn't happen after initTelemetry, but guard
+
+  const event = {
+    ...data,
+    installId,
+    timestamp: new Date().toISOString(),
+  };
+
+  _write(event);
+
+  if (REMOTE_URL) {
+    _sendRemote(event); // fire-and-forget
+  }
+}
+
+/**
+ * Wrap a command handler to automatically record timing, success, and result metadata.
+ *
+ * The wrapped fn can return an optional { score, content_type } for richer tracking.
+ */
+export function trackCommand(command, fn) {
+  return async (...args) => {
+    const start = Date.now();
+    let success = false;
+    let meta = {};
+
+    // Register exit handler so we capture exit(1) paths too
+    process.once('exit', (code) => {
+      if (!success) {
+        recordEvent({
+          event: 'command',
+          command,
+          duration_ms: Date.now() - start,
+          success: code === 0,
+          exit_code: code,
+          ...meta,
+        });
+      }
+    });
+
+    try {
+      const result = await fn(...args);
+      success = true;
+      if (result?.score != null) meta.score = result.score;
+      if (result?.content_type) meta.content_type = result.content_type;
+
+      recordEvent({
+        event: 'command',
+        command,
+        duration_ms: Date.now() - start,
+        success: true,
+        exit_code: 0,
+        ...meta,
+      });
+
+      return result;
+    } catch (err) {
+      // re-throw — the exit handler will record failure
+      throw err;
+    }
+  };
+}
+
+/**
+ * Disable telemetry and persist to config.
+ * Called by: content-grade telemetry off
+ */
+export function disableTelemetry() {
+  const cfg = loadConfig() || {};
+  cfg.telemetryEnabled = false;
+  saveConfig(cfg);
+}
+
+/**
+ * Enable telemetry (undo opt-out).
+ * Called by: content-grade telemetry on
+ */
+export function enableTelemetry() {
+  const cfg = loadConfig() || {};
+  cfg.telemetryEnabled = true;
+  if (!cfg.installId) cfg.installId = generateId();
+  saveConfig(cfg);
+}
+
+/**
+ * Show telemetry status.
+ */
+export function telemetryStatus() {
+  const optedOut = isOptedOut();
+  const cfg = loadConfig();
+  return {
+    enabled: !optedOut,
+    installId: cfg?.installId || null,
+    eventsFile: EVENTS_FILE,
+    remoteUrl: REMOTE_URL || '(none — local only)',
+  };
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────────
+
+function _write(event) {
+  try {
+    ensureDir();
+    appendFileSync(EVENTS_FILE, JSON.stringify(event) + '\n');
+  } catch {
+    // Never fail silently vs crashing the CLI
+  }
+}
+
+async function _sendRemote(event) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 3000);
+  try {
+    await fetch(REMOTE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(event),
+      signal: controller.signal,
+    });
+  } catch {
+    // Network failure — silently ignore, never interrupt the CLI
+  } finally {
+    clearTimeout(timer);
+  }
+}