@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/src/watch.js

@@ -0,0 +1,229 @@
+/**
+ * Watch mode - monitors project for Claude Code config changes and re-audits.
+ * Uses Node.js fs.watch (zero dependencies) with a recursive-directory fallback
+ * on platforms where native recursive watch is not reliable.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { audit } = require('./audit');
+
+const COLORS = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[36m',
+};
+const c = (text, color) => `${COLORS[color] || ''}${text}${COLORS.reset}`;
+
+const FILE_WATCH_PATHS = [
+  'CLAUDE.md',
+  '.gitignore',
+  'package.json',
+  'tsconfig.json',
+];
+
+const DIRECTORY_WATCH_PATHS = [
+  '.claude',
+  '.github',
+];
+
+function supportsNativeRecursiveWatch(platform = process.platform) {
+  return platform === 'win32' || platform === 'darwin';
+}
+
+function statIfExists(fullPath) {
+  try {
+    return fs.statSync(fullPath);
+  } catch (e) {
+    return null;
+  }
+}
+
+function listRecursiveDirectories(dir) {
+  const directories = [dir];
+  let entries = [];
+
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return directories;
+  }
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      directories.push(...listRecursiveDirectories(path.join(dir, entry.name)));
+    }
+  }
+
+  return directories;
+}
+
+function buildWatchPlan(rootDir, platform = process.platform) {
+  const plan = [];
+  const seen = new Set();
+  const recursiveSupported = supportsNativeRecursiveWatch(platform);
+
+  const addTarget = (fullPath, recursive, source) => {
+    const resolved = path.resolve(fullPath);
+    const key = `${resolved}|${recursive}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    plan.push({ path: resolved, recursive, source });
+  };
+
+  addTarget(rootDir, false, 'repo-root');
+
+  for (const watchPath of FILE_WATCH_PATHS) {
+    const fullPath = path.join(rootDir, watchPath);
+    const stat = statIfExists(fullPath);
+    if (stat && stat.isFile()) {
+      addTarget(fullPath, false, watchPath);
+    }
+  }
+
+  for (const watchPath of DIRECTORY_WATCH_PATHS) {
+    const fullPath = path.join(rootDir, watchPath);
+    const stat = statIfExists(fullPath);
+    if (!stat || !stat.isDirectory()) continue;
+
+    if (recursiveSupported) {
+      addTarget(fullPath, true, watchPath);
+      continue;
+    }
+
+    for (const dir of listRecursiveDirectories(fullPath)) {
+      addTarget(dir, false, watchPath);
+    }
+  }
+
+  return plan;
+}
+
+function registerWatchers(rootDir, watchers, onChange, platform = process.platform) {
+  const plan = buildWatchPlan(rootDir, platform);
+
+  for (const item of plan) {
+    const key = `${item.path}|${item.recursive}`;
+    if (watchers.has(key)) continue;
+
+    try {
+      const watcher = fs.watch(item.path, { recursive: item.recursive }, (eventType, filename) => {
+        onChange(item, eventType, filename);
+      });
+      watchers.set(key, watcher);
+    } catch (e) {
+      // Ignore unsupported or transient watch registration failures.
+    }
+  }
+
+  return watchers.size;
+}
+
+function closeWatchers(watchers) {
+  for (const watcher of watchers.values()) {
+    try {
+      watcher.close();
+    } catch (e) {
+      // Ignore close errors during shutdown.
+    }
+  }
+  watchers.clear();
+}
+
+async function watch(options) {
+  const recursiveSupported = supportsNativeRecursiveWatch();
+
+  console.log('');
+  console.log(c('  nerviq watch mode', 'bold'));
+  console.log(c('  ═══════════════════════════════════════', 'dim'));
+  console.log(c(`  Watching: ${options.dir}`, 'dim'));
+  console.log(c(`  Mode: ${recursiveSupported ? 'native recursive directories' : 'expanded directory fallback (cross-platform safe)'}`, 'dim'));
+  console.log(c('  Press Ctrl+C to stop', 'dim'));
+  console.log('');
+
+  // Initial audit
+  let lastScore = null;
+  try {
+    const result = await audit({ ...options, silent: true });
+    lastScore = result.score;
+    console.log(`  ${c('Initial score:', 'bold')} ${scoreColor(result.score)}`);
+    console.log(`  ${result.passed} / ${result.passed + result.failed} checks passing`);
+    console.log('');
+  } catch (e) {
+    console.log(c(`  Initial audit failed: ${e.message}`, 'dim'));
+  }
+
+  // Watch relevant paths
+  const watchers = new Map();
+  let debounceTimer = null;
+  let shuttingDown = false;
+
+  const cleanupAndExit = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    clearTimeout(debounceTimer);
+    closeWatchers(watchers);
+    console.log('');
+    console.log(c('  Watch mode stopped.', 'dim'));
+    process.exit(0);
+  };
+
+  const handleChange = (item, eventType, filename) => {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(async () => {
+      const changedLabel = filename
+        ? String(filename)
+        : path.relative(options.dir, item.path) || path.basename(item.path);
+      const timestamp = new Date().toLocaleTimeString();
+
+      // Pick up newly created directories or newly materialized watch paths.
+      registerWatchers(options.dir, watchers, handleChange);
+
+      console.log(c(`  [${timestamp}] Change detected: ${changedLabel}`, 'dim'));
+
+      try {
+        const result = await audit({ ...options, silent: true });
+        const delta = lastScore !== null ? result.score - lastScore : 0;
+        const arrow = delta > 0 ? c(`+${delta}`, 'green') : delta < 0 ? c(String(delta), 'yellow') : '';
+
+        console.log(`  Score: ${scoreColor(result.score)} ${arrow}  (${result.passed}/${result.passed + result.failed} passing)`);
+
+        if (lastScore !== null && result.score > lastScore) {
+          console.log(c('  Nice improvement!', 'green'));
+        } else if (lastScore !== null && result.score < lastScore) {
+          console.log(c('  Score dropped - check what changed.', 'yellow'));
+        }
+        lastScore = result.score;
+        console.log('');
+      } catch (e) {
+        // Ignore transient errors during file saves.
+      }
+    }, 500);
+  };
+
+  registerWatchers(options.dir, watchers, handleChange);
+
+  if (watchers.size === 0) {
+    console.log(c('  Could not register any filesystem watchers in this environment.', 'yellow'));
+    return;
+  }
+
+  process.once('SIGINT', cleanupAndExit);
+  process.once('SIGTERM', cleanupAndExit);
+
+  console.log(c(`  Watching ${watchers.size} targets for changes...`, 'dim'));
+  console.log('');
+
+  // Keep alive
+  await new Promise(() => {});
+}
+
+function scoreColor(score) {
+  const color = score >= 70 ? 'green' : score >= 40 ? 'yellow' : 'dim';
+  return c(`${score}/100`, color);
+}
+
+module.exports = {
+  watch,
+  buildWatchPlan,
+  supportsNativeRecursiveWatch,
+};

package/src/windsurf/activity.js

@@ -0,0 +1,302 @@
+/**
+ * Windsurf Repeat-Usage Surfaces
+ *
+ * Adapts the shared activity/snapshot backend for Windsurf platform.
+ * Provides: history, compare, trend, feedback, insights.
+ *
+ * 6 repeat-usage surfaces filtered by platform='windsurf':
+ * 1. History — audit snapshot history
+ * 2. Compare — latest vs previous snapshot
+ * 3. Trend — score trend over time
+ * 4. Feedback — recommendation outcome tracking
+ * 5. Insights — pattern detection from history
+ * 6. Surface tracking — per-surface (rules/workflows/memories) progress
+ */
+
+const path = require('path');
+const {
+  readSnapshotIndex,
+  recordRecommendationOutcome,
+  readOutcomeIndex,
+  summarizeOutcomeEntries,
+} = require('../activity');
+const { version } = require('../../package.json');
+
+// --- History ---
+
+function getWindsurfHistory(dir, limit = 20) {
+  const entries = readSnapshotIndex(dir);
+  return entries
+    .filter(e => e.snapshotKind === 'audit' && (e.platform === 'windsurf' || e.summary?.platform === 'windsurf'))
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit);
+}
+
+function formatWindsurfHistory(dir) {
+  const history = getWindsurfHistory(dir, 10);
+  if (history.length === 0) {
+    return 'No Windsurf snapshots found. Run `npx nerviq --platform windsurf --snapshot` to save one.';
+  }
+
+  const lines = ['Windsurf Score History (most recent first):', ''];
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || 'unknown';
+    const score = entry.summary?.score ?? '?';
+    const passed = entry.summary?.passed ?? '?';
+    const total = entry.summary?.checkCount ?? '?';
+    const surfaces = entry.summary?.surfaces || {};
+    const surfaceStr = [
+      surfaces.foreground ? 'FG' : null,
+      surfaces.workflows ? 'WF' : null,
+      surfaces.memories ? 'Mem' : null,
+      surfaces.cascadeignore ? 'CI' : null,
+    ].filter(Boolean).join('+') || 'unknown';
+    lines.push(`  ${date}  ${score}/100  (${passed}/${total} passing)  [${surfaceStr}]`);
+  }
+
+  const comparison = compareWindsurfLatest(dir);
+  if (comparison) {
+    lines.push('');
+    const sign = comparison.delta.score >= 0 ? '+' : '';
+    lines.push(`  Trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous)`);
+    if (comparison.improvements.length > 0) lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
+    if (comparison.regressions.length > 0) lines.push(`  New gaps: ${comparison.regressions.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+// --- Compare ---
+
+function compareWindsurfLatest(dir) {
+  const audits = getWindsurfHistory(dir, 2);
+  if (audits.length < 2) return null;
+
+  const current = audits[0];
+  const previous = audits[1];
+
+  const delta = {
+    score: (current.summary?.score || 0) - (previous.summary?.score || 0),
+    organic: (current.summary?.organicScore || 0) - (previous.summary?.organicScore || 0),
+    passed: (current.summary?.passed || 0) - (previous.summary?.passed || 0),
+  };
+
+  const regressions = [];
+  const improvements = [];
+  const prevKeys = new Set(previous.summary?.topActionKeys || []);
+  const currKeys = new Set(current.summary?.topActionKeys || []);
+
+  for (const key of currKeys) { if (!prevKeys.has(key)) regressions.push(key); }
+  for (const key of prevKeys) { if (!currKeys.has(key)) improvements.push(key); }
+
+  return {
+    platform: 'windsurf',
+    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed },
+    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed },
+    delta,
+    regressions,
+    improvements,
+    trend: delta.score > 0 ? 'improving' : delta.score < 0 ? 'regressing' : 'stable',
+  };
+}
+
+// --- Trend ---
+
+function exportWindsurfTrendReport(dir) {
+  const history = getWindsurfHistory(dir, 50);
+  if (history.length === 0) return null;
+
+  const comparison = compareWindsurfLatest(dir);
+  const lines = [
+    '# Windsurf Setup Trend Report',
+    '',
+    `**Project:** ${path.basename(dir)}`,
+    `**Platform:** Windsurf (Cascade)`,
+    `**Generated:** ${new Date().toISOString().split('T')[0]}`,
+    `**Snapshots:** ${history.length}`,
+    '',
+    '## Score History',
+    '',
+    '| Date | Score | Passed | Checks | Surfaces |',
+    '|------|-------|--------|--------|----------|',
+  ];
+
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || '?';
+    const surfaces = entry.summary?.surfaces || {};
+    const surfaceStr = [surfaces.foreground ? 'FG' : null, surfaces.workflows ? 'WF' : null, surfaces.memories ? 'Mem' : null].filter(Boolean).join('+') || '?';
+    lines.push(`| ${date} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} | ${surfaceStr} |`);
+  }
+
+  if (comparison) {
+    lines.push('', '## Latest Comparison', '');
+    lines.push(`- **Previous:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
+    lines.push(`- **Current:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
+    lines.push(`- **Delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
+    lines.push(`- **Trend:** ${comparison.trend}`);
+    if (comparison.improvements.length > 0) lines.push(`- **Fixed:** ${comparison.improvements.join(', ')}`);
+    if (comparison.regressions.length > 0) lines.push(`- **New gaps:** ${comparison.regressions.join(', ')}`);
+  }
+
+  if (history.length >= 3) {
+    lines.push('', '## Trend Chart', '', '```');
+    const scores = history.slice().reverse().map(e => e.summary?.score ?? 0);
+    const max = Math.max(...scores, 100);
+    const chartHeight = 10;
+    for (let row = chartHeight; row >= 0; row--) {
+      const threshold = (row / chartHeight) * max;
+      const rowLabel = String(Math.round(threshold)).padStart(3);
+      const bar = scores.map(s => s >= threshold ? '#' : ' ').join('');
+      lines.push(`${rowLabel} |${bar}`);
+    }
+    lines.push(`    +${'─'.repeat(scores.length)}`);
+    lines.push('```');
+  }
+
+  lines.push('', '---', `*Generated by nerviq v${version} for Windsurf*`);
+  return lines.join('\n');
+}
+
+// --- Feedback ---
+
+function recordWindsurfFeedback(dir, payload) {
+  return recordRecommendationOutcome(dir, {
+    ...payload,
+    source: payload.source || 'windsurf',
+    platform: 'windsurf',
+  });
+}
+
+function getWindsurfFeedbackSummary(dir) {
+  const entries = readOutcomeIndex(dir)
+    .filter(e => e.source === 'windsurf' || e.platform === 'windsurf');
+  return summarizeOutcomeEntries(entries);
+}
+
+function formatWindsurfFeedback(dir) {
+  const summary = getWindsurfFeedbackSummary(dir);
+  if (!summary || Object.keys(summary).length === 0) {
+    return 'No Windsurf feedback recorded yet. Use `npx nerviq --platform windsurf feedback` to rate recommendations.';
+  }
+  const lines = ['Windsurf Recommendation Feedback:', ''];
+  const entries = Array.isArray(summary) ? summary : Object.values(summary);
+  for (const entry of entries) {
+    lines.push(`  ${entry.key || 'unknown'}: ${entry.accepted || 0} accepted, ${entry.rejected || 0} rejected (${entry.total || 0} total)`);
+  }
+  return lines.join('\n');
+}
+
+// --- Insights ---
+
+function generateWindsurfInsights(dir) {
+  const history = getWindsurfHistory(dir, 50);
+  const feedback = getWindsurfFeedbackSummary(dir);
+  const insights = [];
+
+  // Pattern 1: Persistent failures
+  if (history.length >= 3) {
+    const recentFailKeys = new Map();
+    for (const entry of history.slice(0, 5)) {
+      for (const key of (entry.summary?.topActionKeys || [])) {
+        recentFailKeys.set(key, (recentFailKeys.get(key) || 0) + 1);
+      }
+    }
+    for (const [key, count] of recentFailKeys) {
+      if (count >= 3) {
+        insights.push({ type: 'persistent-failure', severity: 'high', key, message: `Check ${key} has failed in ${count} of the last ${Math.min(history.length, 5)} audits.` });
+      }
+    }
+  }
+
+  // Pattern 2: Score regression
+  if (history.length >= 2) {
+    const scores = history.map(e => e.summary?.score ?? 0);
+    if (scores[0] < scores[1]) {
+      insights.push({ type: 'regression-pattern', severity: 'medium', message: `Score dropped from ${scores[1]} to ${scores[0]} in the most recent audit.`, delta: scores[0] - scores[1] });
+    }
+  }
+
+  // Pattern 3: Velocity stall
+  if (history.length >= 5) {
+    const recentScores = history.slice(0, 5).map(e => e.summary?.score ?? 0);
+    const range = Math.max(...recentScores) - Math.min(...recentScores);
+    if (range <= 2) {
+      insights.push({ type: 'velocity-stall', severity: 'low', message: `Score flat (range: ${range}) over last 5 audits.` });
+    }
+  }
+
+  // Windsurf-specific Pattern 4: Legacy .windsurfrules persistence
+  if (history.length >= 3) {
+    const legacyKeys = [];
+    for (const entry of history.slice(0, 5)) {
+      for (const key of (entry.summary?.topActionKeys || [])) {
+        if (key.includes('legacy') || key.includes('windsurfrules') || key === 'windsurfNoLegacyWindsurfrules') {
+          legacyKeys.push(key);
+        }
+      }
+    }
+    if (legacyKeys.length >= 2) {
+      insights.push({ type: 'legacy-migration-stall', severity: 'high', message: `Legacy .windsurfrules migration check has persisted across ${legacyKeys.length} audits. Migrate to .windsurf/rules/*.md.`, keys: [...new Set(legacyKeys)] });
+    }
+  }
+
+  // Windsurf-specific Pattern 5: Memories secrets risk
+  if (history.length >= 2) {
+    const latest = history[0];
+    const memoryKeys = (latest.summary?.topActionKeys || []).filter(k => k.includes('memor'));
+    if (memoryKeys.length >= 1) {
+      insights.push({ type: 'memories-secrets-risk', severity: 'high', message: `Memory-related checks failing. Memories sync across team — check for secrets/PII.`, keys: memoryKeys });
+    }
+  }
+
+  // Windsurf-specific Pattern 6: Missing cascadeignore
+  if (history.length >= 2) {
+    const latest = history[0];
+    const cascadeKeys = (latest.summary?.topActionKeys || []).filter(k => k.includes('cascade') || k.includes('ignore'));
+    if (cascadeKeys.length >= 1) {
+      insights.push({ type: 'cascadeignore-gap', severity: 'medium', message: `Cascadeignore checks failing. Use .cascadeignore to protect sensitive files.`, keys: cascadeKeys });
+    }
+  }
+
+  // Feedback signals
+  const feedbackEntries = Array.isArray(feedback) ? feedback : Object.values(feedback || {});
+  for (const entry of feedbackEntries) {
+    if (entry.rejected > entry.accepted && entry.total >= 2) {
+      insights.push({ type: 'feedback-signal', severity: 'medium', key: entry.key, message: `Recommendation ${entry.key} has been rejected more than accepted (${entry.rejected}/${entry.total}).` });
+    }
+  }
+
+  return {
+    platform: 'windsurf',
+    generatedAt: new Date().toISOString(),
+    snapshotCount: history.length,
+    feedbackCount: feedbackEntries.length,
+    insights,
+    summary: insights.length === 0
+      ? 'No actionable insights detected. Keep running audits to build pattern data.'
+      : `${insights.length} insight(s) detected across ${history.length} snapshots.`,
+  };
+}
+
+function formatWindsurfInsights(dir) {
+  const result = generateWindsurfInsights(dir);
+  if (result.insights.length === 0) return result.summary;
+  const lines = ['Windsurf Insights:', ''];
+  for (const insight of result.insights) {
+    lines.push(`  [${insight.severity.toUpperCase()}] ${insight.message}`);
+  }
+  lines.push('', result.summary);
+  return lines.join('\n');
+}
+
+module.exports = {
+  getWindsurfHistory,
+  formatWindsurfHistory,
+  compareWindsurfLatest,
+  exportWindsurfTrendReport,
+  recordWindsurfFeedback,
+  getWindsurfFeedbackSummary,
+  formatWindsurfFeedback,
+  generateWindsurfInsights,
+  formatWindsurfInsights,
+};