@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/src/cursor/activity.js

@@ -0,0 +1,301 @@
+/**
+ * Cursor Repeat-Usage Surfaces
+ *
+ * Adapts the shared activity/snapshot backend for Cursor platform.
+ * Provides: history, compare, trend, feedback, insights.
+ *
+ * 6 repeat-usage surfaces filtered by platform='cursor':
+ * 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 (foreground/background/automations) progress
+ */
+
+const path = require('path');
+const {
+  readSnapshotIndex,
+  recordRecommendationOutcome,
+  readOutcomeIndex,
+  summarizeOutcomeEntries,
+} = require('../activity');
+const { version } = require('../../package.json');
+
+// --- History ---
+
+function getCursorHistory(dir, limit = 20) {
+  const entries = readSnapshotIndex(dir);
+  return entries
+    .filter(e => e.snapshotKind === 'audit' && (e.platform === 'cursor' || e.summary?.platform === 'cursor'))
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit);
+}
+
+function formatCursorHistory(dir) {
+  const history = getCursorHistory(dir, 10);
+  if (history.length === 0) {
+    return 'No Cursor snapshots found. Run `npx nerviq --platform cursor --snapshot` to save one.';
+  }
+
+  const lines = ['Cursor 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.background ? 'BG' : null,
+      surfaces.automations ? 'Auto' : null,
+    ].filter(Boolean).join('+') || 'unknown';
+    lines.push(`  ${date}  ${score}/100  (${passed}/${total} passing)  [${surfaceStr}]`);
+  }
+
+  const comparison = compareCursorLatest(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 compareCursorLatest(dir) {
+  const audits = getCursorHistory(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: 'cursor',
+    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 exportCursorTrendReport(dir) {
+  const history = getCursorHistory(dir, 50);
+  if (history.length === 0) return null;
+
+  const comparison = compareCursorLatest(dir);
+  const lines = [
+    '# Cursor Setup Trend Report',
+    '',
+    `**Project:** ${path.basename(dir)}`,
+    `**Platform:** Cursor AI`,
+    `**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.background ? 'BG' : null, surfaces.automations ? 'Auto' : 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 Cursor*`);
+  return lines.join('\n');
+}
+
+// --- Feedback ---
+
+function recordCursorFeedback(dir, payload) {
+  return recordRecommendationOutcome(dir, {
+    ...payload,
+    source: payload.source || 'cursor',
+    platform: 'cursor',
+  });
+}
+
+function getCursorFeedbackSummary(dir) {
+  const entries = readOutcomeIndex(dir)
+    .filter(e => e.source === 'cursor' || e.platform === 'cursor');
+  return summarizeOutcomeEntries(entries);
+}
+
+function formatCursorFeedback(dir) {
+  const summary = getCursorFeedbackSummary(dir);
+  if (!summary || Object.keys(summary).length === 0) {
+    return 'No Cursor feedback recorded yet. Use `npx nerviq --platform cursor feedback` to rate recommendations.';
+  }
+  const lines = ['Cursor 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 generateCursorInsights(dir) {
+  const history = getCursorHistory(dir, 50);
+  const feedback = getCursorFeedbackSummary(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.` });
+    }
+  }
+
+  // Cursor-specific Pattern 4: Legacy .cursorrules 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('cursorrules') || key === 'cursorNoLegacyCursorrules') {
+          legacyKeys.push(key);
+        }
+      }
+    }
+    if (legacyKeys.length >= 2) {
+      insights.push({ type: 'legacy-migration-stall', severity: 'high', message: `Legacy .cursorrules migration check has persisted across ${legacyKeys.length} audits. Migrate to .cursor/rules/*.mdc.`, keys: [...new Set(legacyKeys)] });
+    }
+  }
+
+  // Cursor-specific Pattern 5: MCP tool limit approaching
+  if (history.length >= 2) {
+    const latest = history[0];
+    const mcpKeys = (latest.summary?.topActionKeys || []).filter(k => k.includes('mcp') || k.includes('tool'));
+    if (mcpKeys.length >= 1) {
+      insights.push({ type: 'mcp-tool-limit-risk', severity: 'medium', message: `MCP-related checks failing. Cursor has a hard ~40 tool limit that silently drops tools.`, keys: mcpKeys });
+    }
+  }
+
+  // Cursor-specific Pattern 6: Privacy Mode gap
+  if (history.length >= 2) {
+    const latest = history[0];
+    const privacyKeys = (latest.summary?.topActionKeys || []).filter(k => k.includes('privacy'));
+    if (privacyKeys.length >= 1) {
+      insights.push({ type: 'privacy-mode-gap', severity: 'high', message: `Privacy Mode check failing. Privacy Mode is OFF by default — code sent to providers.`, keys: privacyKeys });
+    }
+  }
+
+  // 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: 'cursor',
+    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 formatCursorInsights(dir) {
+  const result = generateCursorInsights(dir);
+  if (result.insights.length === 0) return result.summary;
+  const lines = ['Cursor Insights:', ''];
+  for (const insight of result.insights) {
+    lines.push(`  [${insight.severity.toUpperCase()}] ${insight.message}`);
+  }
+  lines.push('', result.summary);
+  return lines.join('\n');
+}
+
+module.exports = {
+  getCursorHistory,
+  formatCursorHistory,
+  compareCursorLatest,
+  exportCursorTrendReport,
+  recordCursorFeedback,
+  getCursorFeedbackSummary,
+  formatCursorFeedback,
+  generateCursorInsights,
+  formatCursorInsights,
+};

package/src/cursor/config-parser.js

@@ -0,0 +1,265 @@
+/**
+ * Cursor config parser.
+ *
+ * Cursor uses MDC format (.cursor/rules/*.mdc = YAML frontmatter + Markdown body),
+ * and JSON for .cursor/mcp.json and .cursor/environment.json.
+ * This module handles both formats with unified value extraction.
+ */
+
+// ─── JSON parsing ────────────────────────────────────────────────────────────
+
+function tryParseJson(content) {
+  try {
+    const data = JSON.parse(content);
+    return { ok: true, data, error: null };
+  } catch (error) {
+    return { ok: false, data: null, error: error.message };
+  }
+}
+
+// ─── MDC parsing (YAML frontmatter + Markdown body) ─────────────────────────
+
+/**
+ * Parse an MDC file (YAML frontmatter delimited by --- + Markdown body).
+ * Returns { frontmatter: object|null, body: string, raw: string|null }
+ */
+function parseMdc(content) {
+  if (!content || typeof content !== 'string') {
+    return { frontmatter: null, body: content || '', raw: null };
+  }
+
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith('---')) {
+    return { frontmatter: null, body: content, raw: null };
+  }
+
+  const endIdx = trimmed.indexOf('---', 3);
+  if (endIdx === -1) {
+    return { frontmatter: null, body: content, raw: null };
+  }
+
+  const raw = trimmed.slice(3, endIdx).trim();
+  const body = trimmed.slice(endIdx + 3).trim();
+  const frontmatter = parseSimpleYaml(raw);
+
+  return { frontmatter, body, raw };
+}
+
+/**
+ * Minimal YAML parser for MDC frontmatter fields.
+ * Handles: key: value, key: [item1, item2], key: "quoted", booleans, numbers.
+ * Also handles multi-line array syntax (indented with -).
+ */
+function parseSimpleYaml(yamlStr) {
+  if (!yamlStr || typeof yamlStr !== 'string') return {};
+
+  const result = {};
+  const lines = yamlStr.split(/\r?\n/);
+  let currentKey = null;
+  let currentArray = null;
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine || trimmedLine.startsWith('#')) continue;
+
+    // Check for multi-line array item (  - "value")
+    if (currentKey && currentArray !== null && /^\s*-\s+/.test(line)) {
+      const itemValue = trimmedLine.slice(1).trim();
+      currentArray.push(stripQuotes(itemValue));
+      continue;
+    }
+
+    // If we were collecting an array, commit it
+    if (currentKey && currentArray !== null) {
+      result[currentKey] = currentArray;
+      currentKey = null;
+      currentArray = null;
+    }
+
+    const colonIdx = trimmedLine.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const key = trimmedLine.slice(0, colonIdx).trim();
+    let value = trimmedLine.slice(colonIdx + 1).trim();
+
+    if (!key) continue;
+
+    // Parse value
+    if (value === '') {
+      // Could be start of multi-line array
+      currentKey = key;
+      currentArray = [];
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      // Inline array: [item1, item2]
+      const inner = value.slice(1, -1).trim();
+      if (!inner) {
+        result[key] = [];
+      } else {
+        result[key] = inner.split(',').map(item => {
+          const t = item.trim();
+          return stripQuotes(t);
+        });
+      }
+    } else if ((value.startsWith('"') && value.endsWith('"')) ||
+               (value.startsWith("'") && value.endsWith("'"))) {
+      result[key] = value.slice(1, -1);
+    } else if (value === 'true') {
+      result[key] = true;
+    } else if (value === 'false') {
+      result[key] = false;
+    } else if (/^-?\d+$/.test(value)) {
+      result[key] = parseInt(value, 10);
+    } else if (/^-?\d+\.\d+$/.test(value)) {
+      result[key] = parseFloat(value);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  // Commit any remaining array
+  if (currentKey && currentArray !== null) {
+    result[currentKey] = currentArray;
+  }
+
+  return result;
+}
+
+function stripQuotes(str) {
+  if ((str.startsWith('"') && str.endsWith('"')) ||
+      (str.startsWith("'") && str.endsWith("'"))) {
+    return str.slice(1, -1);
+  }
+  return str;
+}
+
+// ─── MDC rule type detection ─────────────────────────────────────────────────
+
+/**
+ * Determine the MDC rule type from frontmatter fields.
+ *
+ * Truth table:
+ *   Always:           alwaysApply=true, globs=any, description=any
+ *   Auto Attached:    alwaysApply=false, globs=set, description=optional
+ *   Agent Requested:  alwaysApply=false, globs=empty, description=set
+ *   Manual:           alwaysApply=false, globs=empty, description=empty
+ */
+function detectRuleType(frontmatter) {
+  if (!frontmatter) return 'manual';
+
+  const alwaysApply = frontmatter.alwaysApply === true;
+  const hasGlobs = Array.isArray(frontmatter.globs)
+    ? frontmatter.globs.length > 0
+    : Boolean(frontmatter.globs);
+  const hasDescription = Boolean(frontmatter.description && String(frontmatter.description).trim());
+
+  if (alwaysApply) return 'always';
+  if (hasGlobs) return 'auto-attached';
+  if (hasDescription) return 'agent-requested';
+  return 'manual';
+}
+
+// ─── Value extraction ────────────────────────────────────────────────────────
+
+function getValueByPath(obj, dottedPath) {
+  if (!obj) return undefined;
+  const parts = dottedPath.split('.').filter(Boolean);
+  let cursor = obj;
+  for (const part of parts) {
+    if (cursor == null || typeof cursor !== 'object' || !(part in cursor)) {
+      return undefined;
+    }
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+
+// ─── MDC frontmatter validation ──────────────────────────────────────────────
+
+const VALID_MDC_FIELDS = new Set(['description', 'globs', 'alwaysApply']);
+
+/**
+ * Validate MDC rule file frontmatter.
+ * Returns { valid, errors, ruleType }.
+ */
+function validateMdcFrontmatter(frontmatter) {
+  if (!frontmatter) return { valid: false, errors: ['No frontmatter found'], ruleType: 'manual' };
+
+  const errors = [];
+
+  for (const key of Object.keys(frontmatter)) {
+    if (!VALID_MDC_FIELDS.has(key)) {
+      errors.push(`Unknown MDC frontmatter field: "${key}"`);
+    }
+  }
+
+  // Validate globs is an array if present
+  if (frontmatter.globs !== undefined && !Array.isArray(frontmatter.globs) && typeof frontmatter.globs !== 'string') {
+    errors.push('globs must be a string or array of strings');
+  }
+
+  // Validate alwaysApply is boolean if present
+  if (frontmatter.alwaysApply !== undefined && typeof frontmatter.alwaysApply !== 'boolean') {
+    errors.push('alwaysApply must be a boolean (true or false)');
+  }
+
+  // Warn if globs + description combined (creates ambiguity)
+  const hasGlobs = Array.isArray(frontmatter.globs)
+    ? frontmatter.globs.length > 0
+    : Boolean(frontmatter.globs);
+  const hasDescription = Boolean(frontmatter.description && String(frontmatter.description).trim());
+  if (hasGlobs && hasDescription && frontmatter.alwaysApply !== true) {
+    errors.push('Combining globs + description creates ambiguity — use one or the other');
+  }
+
+  const ruleType = detectRuleType(frontmatter);
+
+  return { valid: errors.length === 0, errors, ruleType };
+}
+
+// ─── MCP config validation ───────────────────────────────────────────────────
+
+/**
+ * Count total MCP tools across all servers.
+ * Cursor has a hard limit of ~40 tools.
+ */
+function countMcpTools(mcpData) {
+  if (!mcpData || !mcpData.mcpServers) return 0;
+
+  let total = 0;
+  for (const server of Object.values(mcpData.mcpServers)) {
+    // Each server exposes tools; estimate ~5 per server if no explicit count
+    const toolCount = server.tools ? Object.keys(server.tools).length : 5;
+    total += toolCount;
+  }
+  return total;
+}
+
+/**
+ * Validate MCP env vars use ${env:VAR} syntax (not hardcoded secrets).
+ */
+function validateMcpEnvVars(mcpData) {
+  if (!mcpData || !mcpData.mcpServers) return { valid: true, hardcodedVars: [] };
+
+  const hardcodedVars = [];
+  for (const [serverName, config] of Object.entries(mcpData.mcpServers)) {
+    if (!config.env) continue;
+    for (const [key, value] of Object.entries(config.env)) {
+      if (typeof value === 'string' && !value.startsWith('${env:') && /key|token|secret|password|api/i.test(key)) {
+        hardcodedVars.push({ server: serverName, key, value: '[REDACTED]' });
+      }
+    }
+  }
+
+  return { valid: hardcodedVars.length === 0, hardcodedVars };
+}
+
+module.exports = {
+  tryParseJson,
+  parseMdc,
+  parseSimpleYaml,
+  detectRuleType,
+  getValueByPath,
+  validateMdcFrontmatter,
+  countMcpTools,
+  validateMcpEnvVars,
+};