@nerviq/cli 1.29.0 → 1.30.0

package/src/telemetry.js

@@ -1,160 +1,160 @@
-/**
- * Nerviq Opt-In Telemetry Foundation
- *
- * Collects anonymous usage events ONLY when NERVIQ_TELEMETRY=1 is set.
- * No PII, no file contents, no absolute paths are ever stored.
- * Events are stored locally in <projectDir>/.nerviq/telemetry.json.
- *
- * This module is the foundation layer — actual transmission to a dashboard
- * is an explicit opt-in step configured separately.
- *
- * Privacy guarantees:
- *   - No usernames, emails, or identifiers
- *   - No file contents or code
- *   - No absolute paths (only hashed project fingerprint)
- *   - Stored only on local disk
- *   - Never sent anywhere without additional explicit configuration
- */
-
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const crypto = require('crypto');
-
-const TELEMETRY_FILE = path.join(os.homedir(), '.nerviq', 'telemetry.json');
-const MAX_EVENTS = 500; // cap file size at ~500 events
-
-// ─── Opt-in check ─────────────────────────────────────────────────────────────
-
-/**
- * Returns true only when the user has explicitly set NERVIQ_TELEMETRY=1.
- * Telemetry is opt-IN, not opt-out.
- * @returns {boolean}
- */
-function shouldCollectTelemetry() {
-  return process.env.NERVIQ_TELEMETRY === '1';
-}
-
-// ─── Anonymous fingerprinting ─────────────────────────────────────────────────
-
-/**
- * Creates a one-way hash of the project directory.
- * This allows grouping events by project without exposing the path.
- * @param {string} dir
- * @returns {string} 8-char hex fingerprint
- */
-function hashProject(dir) {
-  try {
-    return crypto.createHash('sha256').update(dir).digest('hex').slice(0, 8);
-  } catch {
-    return 'unknown';
-  }
-}
-
-// ─── Event collection ────────────────────────────────────────────────────────
-
-/**
- * Collect an anonymous usage event and append it to the local telemetry file.
- * Does nothing unless shouldCollectTelemetry() returns true.
- *
- * @param {string} event - Event name (e.g. 'audit', 'setup', 'convert')
- * @param {object} [data] - Additional anonymous data
- * @param {string} [data.platform] - Platform name (claude, codex, etc.)
- * @param {number} [data.score] - Audit score
- * @param {number} [data.checkCount] - Total checks evaluated
- * @param {number} [data.durationMs] - Execution time in ms
- * @param {string} [data.dir] - Project dir (hashed before storage)
- * @returns {object|null} The recorded event object, or null if telemetry is off
- */
-function collectAnonymousEvent(event, data = {}) {
-  if (!shouldCollectTelemetry()) return null;
-
-  const record = {
-    event: String(event),
-    platform: data.platform || null,
-    score: typeof data.score === 'number' ? data.score : null,
-    checkCount: typeof data.checkCount === 'number' ? data.checkCount : null,
-    durationMs: typeof data.durationMs === 'number' ? Math.round(data.durationMs) : null,
-    timestamp: new Date().toISOString(),
-    nodeVersion: process.version,
-    os: `${os.platform()}-${os.arch()}`,
-    projectFingerprint: data.dir ? hashProject(data.dir) : null,
-    // Explicitly omit: paths, file contents, usernames, email, tokens
-  };
-
-  try {
-    const telemetryDir = path.dirname(TELEMETRY_FILE);
-    fs.mkdirSync(telemetryDir, { recursive: true });
-
-    let events = [];
-    if (fs.existsSync(TELEMETRY_FILE)) {
-      try {
-        const raw = fs.readFileSync(TELEMETRY_FILE, 'utf8');
-        const parsed = JSON.parse(raw);
-        events = Array.isArray(parsed.events) ? parsed.events : [];
-      } catch {
-        events = [];
-      }
-    }
-
-    events.push(record);
-
-    // Cap at MAX_EVENTS to prevent unbounded growth
-    if (events.length > MAX_EVENTS) {
-      events = events.slice(events.length - MAX_EVENTS);
-    }
-
-    const payload = {
-      version: 1,
-      telemetryOptIn: true,
-      note: 'Local telemetry only. Set NERVIQ_TELEMETRY=0 or unset to disable.',
-      events,
-    };
-
-    fs.writeFileSync(TELEMETRY_FILE, JSON.stringify(payload, null, 2), 'utf8');
-  } catch {
-    // Telemetry failures are always silent — never block main flow
-  }
-
-  return record;
-}
-
-// ─── Read local telemetry ─────────────────────────────────────────────────────
-
-/**
- * Read the local telemetry file.
- * @returns {{ version: number, events: object[] } | null}
- */
-function readLocalTelemetry() {
-  try {
-    if (!fs.existsSync(TELEMETRY_FILE)) return null;
-    return JSON.parse(fs.readFileSync(TELEMETRY_FILE, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Clear all local telemetry events.
- * @returns {boolean} true if cleared successfully
- */
-function clearLocalTelemetry() {
-  try {
-    if (fs.existsSync(TELEMETRY_FILE)) {
-      fs.writeFileSync(TELEMETRY_FILE, JSON.stringify({ version: 1, events: [] }, null, 2), 'utf8');
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-module.exports = {
-  shouldCollectTelemetry,
-  collectAnonymousEvent,
-  readLocalTelemetry,
-  clearLocalTelemetry,
-  TELEMETRY_FILE,
-};
+/**
+ * Nerviq Opt-In Telemetry Foundation
+ *
+ * Collects anonymous usage events ONLY when NERVIQ_TELEMETRY=1 is set.
+ * No PII, no file contents, no absolute paths are ever stored.
+ * Events are stored locally in <projectDir>/.nerviq/telemetry.json.
+ *
+ * This module is the foundation layer — actual transmission to a dashboard
+ * is an explicit opt-in step configured separately.
+ *
+ * Privacy guarantees:
+ *   - No usernames, emails, or identifiers
+ *   - No file contents or code
+ *   - No absolute paths (only hashed project fingerprint)
+ *   - Stored only on local disk
+ *   - Never sent anywhere without additional explicit configuration
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const TELEMETRY_FILE = path.join(os.homedir(), '.nerviq', 'telemetry.json');
+const MAX_EVENTS = 500; // cap file size at ~500 events
+
+// ─── Opt-in check ─────────────────────────────────────────────────────────────
+
+/**
+ * Returns true only when the user has explicitly set NERVIQ_TELEMETRY=1.
+ * Telemetry is opt-IN, not opt-out.
+ * @returns {boolean}
+ */
+function shouldCollectTelemetry() {
+  return process.env.NERVIQ_TELEMETRY === '1';
+}
+
+// ─── Anonymous fingerprinting ─────────────────────────────────────────────────
+
+/**
+ * Creates a one-way hash of the project directory.
+ * This allows grouping events by project without exposing the path.
+ * @param {string} dir
+ * @returns {string} 8-char hex fingerprint
+ */
+function hashProject(dir) {
+  try {
+    return crypto.createHash('sha256').update(dir).digest('hex').slice(0, 8);
+  } catch {
+    return 'unknown';
+  }
+}
+
+// ─── Event collection ────────────────────────────────────────────────────────
+
+/**
+ * Collect an anonymous usage event and append it to the local telemetry file.
+ * Does nothing unless shouldCollectTelemetry() returns true.
+ *
+ * @param {string} event - Event name (e.g. 'audit', 'setup', 'convert')
+ * @param {object} [data] - Additional anonymous data
+ * @param {string} [data.platform] - Platform name (claude, codex, etc.)
+ * @param {number} [data.score] - Audit score
+ * @param {number} [data.checkCount] - Total checks evaluated
+ * @param {number} [data.durationMs] - Execution time in ms
+ * @param {string} [data.dir] - Project dir (hashed before storage)
+ * @returns {object|null} The recorded event object, or null if telemetry is off
+ */
+function collectAnonymousEvent(event, data = {}) {
+  if (!shouldCollectTelemetry()) return null;
+
+  const record = {
+    event: String(event),
+    platform: data.platform || null,
+    score: typeof data.score === 'number' ? data.score : null,
+    checkCount: typeof data.checkCount === 'number' ? data.checkCount : null,
+    durationMs: typeof data.durationMs === 'number' ? Math.round(data.durationMs) : null,
+    timestamp: new Date().toISOString(),
+    nodeVersion: process.version,
+    os: `${os.platform()}-${os.arch()}`,
+    projectFingerprint: data.dir ? hashProject(data.dir) : null,
+    // Explicitly omit: paths, file contents, usernames, email, tokens
+  };
+
+  try {
+    const telemetryDir = path.dirname(TELEMETRY_FILE);
+    fs.mkdirSync(telemetryDir, { recursive: true });
+
+    let events = [];
+    if (fs.existsSync(TELEMETRY_FILE)) {
+      try {
+        const raw = fs.readFileSync(TELEMETRY_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        events = Array.isArray(parsed.events) ? parsed.events : [];
+      } catch {
+        events = [];
+      }
+    }
+
+    events.push(record);
+
+    // Cap at MAX_EVENTS to prevent unbounded growth
+    if (events.length > MAX_EVENTS) {
+      events = events.slice(events.length - MAX_EVENTS);
+    }
+
+    const payload = {
+      version: 1,
+      telemetryOptIn: true,
+      note: 'Local telemetry only. Set NERVIQ_TELEMETRY=0 or unset to disable.',
+      events,
+    };
+
+    fs.writeFileSync(TELEMETRY_FILE, JSON.stringify(payload, null, 2), 'utf8');
+  } catch {
+    // Telemetry failures are always silent — never block main flow
+  }
+
+  return record;
+}
+
+// ─── Read local telemetry ─────────────────────────────────────────────────────
+
+/**
+ * Read the local telemetry file.
+ * @returns {{ version: number, events: object[] } | null}
+ */
+function readLocalTelemetry() {
+  try {
+    if (!fs.existsSync(TELEMETRY_FILE)) return null;
+    return JSON.parse(fs.readFileSync(TELEMETRY_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear all local telemetry events.
+ * @returns {boolean} true if cleared successfully
+ */
+function clearLocalTelemetry() {
+  try {
+    if (fs.existsSync(TELEMETRY_FILE)) {
+      fs.writeFileSync(TELEMETRY_FILE, JSON.stringify({ version: 1, events: [] }, null, 2), 'utf8');
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  shouldCollectTelemetry,
+  collectAnonymousEvent,
+  readLocalTelemetry,
+  clearLocalTelemetry,
+  TELEMETRY_FILE,
+};

package/src/watch.js

@@ -144,6 +144,40 @@ async function watch(options) {
   console.log(c('  Press Ctrl+C to stop', 'dim'));
   console.log('');
 
+  // LOOP-01: alert state — track which named alerts fired last cycle so we
+  // can emit "new alert / cleared alert" lines per change rather than the
+  // full list every save. The user-lab's "spellcheck for prompts" framing
+  // wants action-on-change, not score-deltas alone.
+  const alertsEnabled = options.alerts !== false; // default-on; pass --no-alerts to disable
+  const lastAlerts = new Set();
+  function buildAlertSet(result) {
+    const set = new Set();
+    if (result && result.staleReferences && result.staleReferences.byKey) {
+      for (const [key, count] of Object.entries(result.staleReferences.byKey)) {
+        set.add(`stale:${key}:${count}`);
+      }
+    }
+    if (Array.isArray(result && result.shallowRiskHints)) {
+      for (const h of result.shallowRiskHints) {
+        if (h && h.key && h.severity === 'critical') {
+          set.add(`critical:${h.key}:${h.file || ''}`);
+        }
+      }
+    }
+    return set;
+  }
+  function emitAlertDiff(prev, curr) {
+    if (!alertsEnabled) return;
+    const newAlerts = [...curr].filter((a) => !prev.has(a));
+    const cleared = [...prev].filter((a) => !curr.has(a));
+    for (const a of newAlerts) {
+      console.log(c(`  🔔 NEW: ${a}`, 'yellow'));
+    }
+    for (const a of cleared) {
+      console.log(c(`  ✓ CLEARED: ${a}`, 'green'));
+    }
+  }
+
   // Initial audit
   let lastScore = null;
   try {
@@ -151,6 +185,9 @@ async function watch(options) {
     lastScore = result.score;
     console.log(`  ${c('Initial score:', 'bold')} ${scoreColor(result.score)}`);
     console.log(`  ${result.passed} / ${result.passed + result.failed} checks passing`);
+    if (alertsEnabled && result.staleReferences && result.staleReferences.count > 0) {
+      console.log(c(`  📌 Initial alerts: ${result.staleReferences.count} stale reference(s)`, 'yellow'));
+    }
     const continuousStatus = buildContinuousStatus({
       dir: options.dir,
       auditResult: result,
@@ -159,6 +196,8 @@ async function watch(options) {
     });
     console.log(formatContinuousStatus(continuousStatus, { compact: true }));
     console.log('');
+    const initialAlerts = buildAlertSet(result);
+    for (const a of initialAlerts) lastAlerts.add(a);
   } catch (e) {
     console.log(c(`  Initial audit failed: ${e.message}`, 'dim'));
   }
@@ -205,6 +244,13 @@ async function watch(options) {
         console.log(`  Score: ${scoreColor(result.score)} ${arrow}  (${result.passed}/${result.passed + result.failed} passing)`);
         console.log(formatContinuousStatus(continuousStatus, { compact: true }));
 
+        // LOOP-01: emit named alert diff (NEW / CLEARED) per change, so the
+        // developer gets action-on-change feedback, not just score deltas.
+        const currentAlerts = buildAlertSet(result);
+        emitAlertDiff(lastAlerts, currentAlerts);
+        lastAlerts.clear();
+        for (const a of currentAlerts) lastAlerts.add(a);
+
         if (lastScore !== null && result.score > lastScore) {
           console.log(c('  Nice improvement!', 'green'));
         } else if (lastScore !== null && result.score < lastScore) {