@nerviq/cli 0.9.2 → 0.9.4

package/src/cursor/techniques.js

@@ -1,11 +1,12 @@
 /**
  * Cursor techniques module — CHECK CATALOG
  *
- * 82 checks across 16 categories:
- *   v0.1 (40): A. Rules(9), B. Config(7), C. Trust & Safety(9), D. Agent Mode(5), E. MCP(5), F. Instructions Quality(5)
- *   v0.5 (55): G. Background Agents(5), H. Automations(5), I. Enterprise(5)
+ * 88 checks across 16 categories:
+ *   v0.1 (40): A. Rules(9), B. Config(8), C. Trust & Safety(11), D. Agent Mode(5), E. MCP(5), F. Instructions Quality(5)
+ *   v0.5 (55): G. Background Agents(5), H. Automations(6), I. Enterprise(5)
  *   v1.0 (70): J. BugBot & Code Review(4), K. Cross-Surface(4), L. Quality Deep(7)
  *   CP-08 (82): M. Advisory(4), N. Pack(4), O. Repeat(3), P. Freshness(3)
+ *   Exp-fixes (88): +4 new checks from experiment findings
  *
  * Each check: { id, name, check(ctx), impact, rating, category, fix, template, file(), line() }
  */
@@ -14,6 +15,7 @@ const os = require('os');
 const path = require('path');
 const { CursorProjectContext } = require('./context');
 const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
 const { validateMdcFrontmatter, validateMcpEnvVars } = require('./config-parser');
 
 // ─── Shared helpers ─────────────────────────────────────────────────────────
@@ -180,7 +182,7 @@ const CURSOR_TECHNIQUES = {
     impact: 'critical',
     rating: 5,
     category: 'rules',
-    fix: 'Migrate .cursorrules to .cursor/rules/*.mdc with proper frontmatter. AGENT MODE IGNORES .cursorrules completely!',
+    fix: 'Migrate .cursorrules to .cursor/rules/*.mdc with alwaysApply: true. AGENT MODE COMPLETELY IGNORES .cursorrules (confirmed by direct observation). 82% of projects have broken rules because of this — cursor-doctor audit.',
     template: 'cursor-legacy-migration',
     file: () => '.cursorrules',
     line: () => 1,
@@ -215,10 +217,10 @@ const CURSOR_TECHNIQUES = {
         return validation.valid;
       });
     },
-    impact: 'high',
-    rating: 4,
+    impact: 'critical',
+    rating: 5,
     category: 'rules',
-    fix: 'Fix YAML frontmatter in .mdc files. Use only: description, globs, alwaysApply fields.',
+    fix: 'Fix YAML frontmatter in .mdc files. Invalid YAML silently skips the entire rule file — no error, no warning. Only 3 fields recognized: description, globs, alwaysApply. 82% of audited projects have broken rules from this issue.',
     template: null,
     file: () => '.cursor/rules/',
     line: () => 1,
@@ -476,8 +478,28 @@ const CURSOR_TECHNIQUES = {
     line: () => null,
   },
 
+  cursorMcpServersRootKey: {
+    id: 'CU-B08',
+    name: 'MCP config has required mcpServers root key',
+    check: (ctx) => {
+      const raw = mcpJsonRaw(ctx);
+      if (!raw) return null;
+      const data = mcpJsonData(ctx);
+      if (!data) return null;
+      // Must have mcpServers key at root — any other key causes silent failure
+      return Object.prototype.hasOwnProperty.call(data, 'mcpServers');
+    },
+    impact: 'critical',
+    rating: 5,
+    category: 'config',
+    fix: 'Ensure .cursor/mcp.json has the "mcpServers" root key. Using "servers" or any other key causes silent failure — zero tools load with no error shown (confirmed by experiment).',
+    template: null,
+    file: () => '.cursor/mcp.json',
+    line: () => 1,
+  },
+
   // =============================================
-  // C. Trust & Safety (9 checks) — CU-C01..CU-C09
+  // C. Trust & Safety (11 checks) — CU-C01..CU-C11
   // =============================================
 
   cursorPrivacyMode: {
@@ -489,10 +511,10 @@ const CURSOR_TECHNIQUES = {
       const docs = docsBundle(ctx);
       return /privacy mode|zero.?retention|data retention|privacy.*enabled/i.test(docs);
     },
-    impact: 'high',
+    impact: 'critical',
     rating: 5,
     category: 'trust',
-    fix: 'Enable Privacy Mode in Cursor Settings for zero data retention, or document why it is disabled.',
+    fix: 'Privacy Mode is OFF by default — code is sent to all third-party providers (OpenAI, Anthropic, etc.) unless explicitly enabled. Enable in Cursor Settings → Privacy → Privacy Mode, or document the deliberate decision to keep it off.',
     template: null,
     file: () => '.cursor/rules/',
     line: () => null,
@@ -656,6 +678,44 @@ const CURSOR_TECHNIQUES = {
     line: () => null,
   },
 
+  cursorBackgroundAgentHomeDir: {
+    id: 'CU-C10',
+    name: 'Background agent home directory exposure documented',
+    check: (ctx) => {
+      const env = envJsonData(ctx);
+      if (!env) return null;
+      // If background agents are configured, check that the security risk is documented
+      const docs = docsBundle(ctx);
+      return /home.?dir|npmrc|aws.?credentials|ssh.*key|credential.*exposure|home.*access/i.test(docs);
+    },
+    impact: 'critical',
+    rating: 5,
+    category: 'trust',
+    fix: 'Background agents have FULL READ access to ~/.npmrc, ~/.aws/credentials, ~/.ssh/ (open security issue since Nov 2025). Document this risk and remove sensitive credentials from home directory before using background agents, or use environment variable references instead.',
+    template: null,
+    file: () => '.cursor/environment.json',
+    line: () => null,
+  },
+
+  cursorCursorignoreShellBypass: {
+    id: 'CU-C11',
+    name: '.cursorignore does not protect against shell command access',
+    check: (ctx) => {
+      const hasIgnore = Boolean(ctx.fileContent('.cursorignore'));
+      if (!hasIgnore) return null;
+      // If .cursorignore exists, check that docs acknowledge shell bypass gap
+      const docs = docsBundle(ctx);
+      return /cursorignore.*shell|shell.*bypass|terminal.*ignore|ignore.*terminal/i.test(docs);
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'trust',
+    fix: '.cursorignore only protects files from @Codebase direct reads — agents can still access ignored files via terminal commands (cat, head, etc.). Do not rely on .cursorignore for security. Use proper OS-level file permissions for truly sensitive files.',
+    template: null,
+    file: () => '.cursorignore',
+    line: () => null,
+  },
+
   // =============================================
   // D. Agent Mode (5 checks) — CU-D01..CU-D05
   // =============================================
@@ -1140,6 +1200,27 @@ const CURSOR_TECHNIQUES = {
     line: () => null,
   },
 
+  cursorAutomationFileSaveDebounce: {
+    id: 'CU-H06',
+    name: 'file_save automation triggers have debounce_ms set',
+    check: (ctx) => {
+      const configs = ctx.automationsConfig ? ctx.automationsConfig() : [];
+      if (configs.length === 0) return null;
+      const combined = configs.map(c => c.content).join('\n');
+      // Only relevant if file_save trigger is used
+      if (!/type:\s*file_save|file[_-]save/i.test(combined)) return null;
+      // Must have debounce_ms set to avoid infinite loop
+      return /debounce_ms|debounce-ms/i.test(combined);
+    },
+    impact: 'critical',
+    rating: 5,
+    category: 'automations',
+    fix: 'Add debounce_ms: 30000 (minimum) to all file_save automation triggers. Without debounce, the automation saves a file → triggers itself → infinite loop that consumes your entire automation quota.',
+    template: null,
+    file: () => '.cursor/automations/',
+    line: () => null,
+  },
+
   // =============================================
   // I. Enterprise (5 checks) — CU-I01..CU-I05
   // =============================================
@@ -1781,6 +1862,8 @@ const CURSOR_TECHNIQUES = {
   },
 };
 
+attachSourceUrls('cursor', CURSOR_TECHNIQUES);
+
 module.exports = {
   CURSOR_TECHNIQUES,
 };

package/src/doctor.js

@@ -0,0 +1,253 @@
+/**
+ * Nerviq Doctor
+ *
+ * Self-diagnostics for the nerviq CLI and the current project environment.
+ * Checks: Node version, dependencies, platform detection, freshness gates.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { version } = require('../package.json');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m',
+};
+
+function c(text, color) {
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+const PLATFORM_SIGNALS = {
+  claude:    ['CLAUDE.md', '.claude/CLAUDE.md', '.claude/settings.json'],
+  codex:     ['AGENTS.md', '.codex/', '.codex/config.toml'],
+  cursor:    ['.cursor/rules/', '.cursor/mcp.json', '.cursorrules'],
+  copilot:   ['.github/copilot-instructions.md', '.github/'],
+  gemini:    ['GEMINI.md', '.gemini/', '.gemini/settings.json'],
+  windsurf:  ['.windsurf/', '.windsurfrules', '.windsurf/rules/'],
+  aider:     ['.aider.conf.yml', '.aider.model.settings.yml'],
+  opencode:  ['opencode.json', '.opencode/'],
+};
+
+const FRESHNESS_MODULES = {
+  claude:   './freshness',
+  codex:    './codex/freshness',
+  cursor:   './cursor/freshness',
+  copilot:  './copilot/freshness',
+  gemini:   './gemini/freshness',
+  windsurf: './windsurf/freshness',
+  aider:    './aider/freshness',
+  opencode: './opencode/freshness',
+};
+
+// ─── Individual checks ───────────────────────────────────────────────────────
+
+function checkNodeVersion() {
+  const raw = process.version.replace('v', '');
+  const [major] = raw.split('.').map(Number);
+  const ok = major >= 18;
+  return {
+    label: 'Node.js version',
+    status: ok ? 'pass' : 'fail',
+    detail: `${process.version} (${ok ? 'meets' : 'below'} minimum v18)`,
+    fix: ok ? null : 'Upgrade Node.js to v18 or later: https://nodejs.org',
+  };
+}
+
+function checkDeps() {
+  const pkgPath = path.join(__dirname, '..', 'node_modules');
+  const exists = fs.existsSync(pkgPath);
+  return {
+    label: 'node_modules installed',
+    status: exists ? 'pass' : 'fail',
+    detail: exists ? `${pkgPath}` : 'node_modules missing',
+    fix: exists ? null : 'Run: npm install',
+  };
+}
+
+function checkJestInstalled() {
+  const jestPath = path.join(__dirname, '..', 'node_modules', 'jest', 'package.json');
+  const exists = fs.existsSync(jestPath);
+  let jestVersion = null;
+  if (exists) {
+    try {
+      jestVersion = require(jestPath).version;
+    } catch {}
+  }
+  return {
+    label: 'Jest test runner',
+    status: exists ? 'pass' : 'warn',
+    detail: exists ? `jest@${jestVersion}` : 'jest not found in node_modules',
+    fix: exists ? null : 'Run: npm install --save-dev jest',
+  };
+}
+
+function checkPlatformDetection(dir) {
+  const detected = [];
+  for (const [platform, signals] of Object.entries(PLATFORM_SIGNALS)) {
+    for (const signal of signals) {
+      const signalPath = path.join(dir, signal);
+      if (fs.existsSync(signalPath)) {
+        detected.push(platform);
+        break;
+      }
+    }
+  }
+
+  return {
+    label: 'Platform detection',
+    status: detected.length > 0 ? 'pass' : 'warn',
+    detail: detected.length > 0
+      ? `Detected: ${detected.join(', ')}`
+      : 'No platform config files found in current directory',
+    detected,
+    fix: detected.length === 0
+      ? 'Run `nerviq setup` to generate baseline config files for your platform'
+      : null,
+  };
+}
+
+function checkFreshnessGates() {
+  const results = [];
+  for (const [platform, modulePath] of Object.entries(FRESHNESS_MODULES)) {
+    try {
+      const freshness = require(modulePath);
+      const gate = freshness.checkReleaseGate({});
+      results.push({
+        platform,
+        status: gate.stale.length === 0 ? 'pass' : 'warn',
+        fresh: gate.fresh.length,
+        total: gate.results.length,
+        stale: gate.stale.length,
+        detail: gate.stale.length === 0
+          ? `All ${gate.results.length} P0 sources fresh`
+          : `${gate.stale.length}/${gate.results.length} P0 sources unverified/stale`,
+      });
+    } catch (e) {
+      results.push({ platform, status: 'error', detail: e.message });
+    }
+  }
+  return results;
+}
+
+function checkCliPermissions() {
+  const cliBin = path.join(__dirname, '..', 'bin', 'cli.js');
+  const exists = fs.existsSync(cliBin);
+  if (!exists) {
+    return { label: 'CLI binary (bin/cli.js)', status: 'fail', detail: 'bin/cli.js not found', fix: null };
+  }
+  return { label: 'CLI binary (bin/cli.js)', status: 'pass', detail: cliBin, fix: null };
+}
+
+function checkGitRepo(dir) {
+  const gitPath = path.join(dir, '.git');
+  const exists = fs.existsSync(gitPath);
+  return {
+    label: 'Git repository',
+    status: exists ? 'pass' : 'warn',
+    detail: exists ? '.git/ found' : 'Not a git repository',
+    fix: exists ? null : 'Run: git init (recommended for safety)',
+  };
+}
+
+// ─── Main doctor function ────────────────────────────────────────────────────
+
+async function runDoctor({ dir = process.cwd(), json = false, verbose = false } = {}) {
+  const startMs = Date.now();
+
+  const checks = [
+    checkNodeVersion(),
+    checkDeps(),
+    checkJestInstalled(),
+    checkCliPermissions(),
+    checkGitRepo(dir),
+    checkPlatformDetection(dir),
+  ];
+
+  const freshnessChecks = checkFreshnessGates();
+
+  const totalPass = checks.filter(c => c.status === 'pass').length;
+  const totalWarn = checks.filter(c => c.status === 'warn').length;
+  const totalFail = checks.filter(c => c.status === 'fail').length;
+
+  const freshPass = freshnessChecks.filter(f => f.status === 'pass').length;
+  const freshWarn = freshnessChecks.filter(f => f.status !== 'pass').length;
+
+  const overallOk = totalFail === 0;
+  const elapsed = Date.now() - startMs;
+
+  if (json) {
+    return JSON.stringify({
+      nerviq: version,
+      node: process.version,
+      dir,
+      overallOk,
+      checks,
+      freshnessChecks,
+      totalPass,
+      totalWarn,
+      totalFail,
+      freshPass,
+      freshWarn,
+      elapsed,
+    }, null, 2);
+  }
+
+  const lines = [''];
+  lines.push(c(`  nerviq doctor  v${version}`, 'bold'));
+  lines.push(c('  ═══════════════════════════════════════', 'dim'));
+  lines.push('');
+
+  // Environment checks
+  lines.push(c('  Environment', 'bold'));
+  for (const chk of checks) {
+    const icon = chk.status === 'pass' ? c('✓', 'green') : chk.status === 'warn' ? c('⚠', 'yellow') : c('✗', 'red');
+    lines.push(`    ${icon}  ${chk.label.padEnd(32)} ${c(chk.detail, chk.status === 'pass' ? 'dim' : 'reset')}`);
+    if (chk.fix && (verbose || chk.status === 'fail')) {
+      lines.push(c(`         Fix: ${chk.fix}`, 'yellow'));
+    }
+  }
+
+  // Platform detection detail
+  const detectedPlatforms = (checks.find(c => c.detected) || {}).detected || [];
+  if (detectedPlatforms.length > 0) {
+    lines.push('');
+    lines.push(c('  Detected Platforms', 'bold'));
+    for (const p of detectedPlatforms) {
+      lines.push(`    ${c('✓', 'green')}  ${p}`);
+    }
+  }
+
+  // Freshness
+  lines.push('');
+  lines.push(c('  Freshness Gates', 'bold'));
+  for (const f of freshnessChecks) {
+    const icon = f.status === 'pass' ? c('✓', 'green') : c('⚠', 'yellow');
+    const label = f.platform.padEnd(12);
+    lines.push(`    ${icon}  ${label}  ${c(f.detail || f.status, f.status === 'pass' ? 'dim' : 'yellow')}`);
+  }
+
+  lines.push('');
+  lines.push(c('  Summary', 'bold'));
+  lines.push(`    Checks:    ${c(String(totalPass), 'green')} pass  ${totalWarn > 0 ? c(String(totalWarn), 'yellow') + ' warn  ' : ''}${totalFail > 0 ? c(String(totalFail), 'red') + ' fail' : ''}`);
+  lines.push(`    Freshness: ${c(String(freshPass), 'green')} fresh  ${freshWarn > 0 ? c(String(freshWarn), 'yellow') + ' stale/unverified' : ''}`);
+  lines.push(`    Status:    ${overallOk ? c('✓ Healthy', 'green') : c('✗ Issues found', 'red')}`);
+  lines.push(`    Duration:  ${elapsed}ms`);
+  lines.push('');
+
+  if (!overallOk) {
+    lines.push(c('  Run with --verbose for fix suggestions.', 'dim'));
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { runDoctor };

package/src/feedback.js

@@ -0,0 +1,173 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+let lastTimestamp = '';
+let counter = 0;
+
+function timestampId() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  if (ts === lastTimestamp) {
+    counter += 1;
+    return `${ts}-${counter}`;
+  }
+  lastTimestamp = ts;
+  counter = 0;
+  return ts;
+}
+
+function ensureFeedbackDir(dir) {
+  const feedbackDir = path.join(dir, '.claude', 'claudex-setup', 'feedback');
+  fs.mkdirSync(feedbackDir, { recursive: true });
+  return feedbackDir;
+}
+
+function writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf8');
+}
+
+function saveFeedback(dir, payload) {
+  const feedbackDir = ensureFeedbackDir(dir);
+  const id = timestampId();
+  const keySlug = String(payload.key || 'finding').replace(/[^a-z0-9_-]+/gi, '-').toLowerCase();
+  const filePath = path.join(feedbackDir, `${id}-${keySlug}.json`);
+  const envelope = {
+    schemaVersion: 1,
+    id,
+    createdAt: new Date().toISOString(),
+    ...payload,
+  };
+  writeJson(filePath, envelope);
+  return {
+    ...envelope,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+  };
+}
+
+function getFeedbackSummary(dir) {
+  const feedbackDir = ensureFeedbackDir(dir);
+  const files = fs.readdirSync(feedbackDir).filter((name) => name.endsWith('.json'));
+  const entries = [];
+
+  for (const file of files) {
+    const filePath = path.join(feedbackDir, file);
+    try {
+      entries.push(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+    } catch {
+      // Ignore malformed artifacts so one bad file does not break the summary.
+    }
+  }
+
+  const summary = {
+    totalEntries: entries.length,
+    helpful: 0,
+    unhelpful: 0,
+    byKey: {},
+    relativeDir: path.relative(dir, feedbackDir),
+  };
+
+  for (const entry of entries) {
+    const helpful = entry.helpful === true;
+    if (helpful) {
+      summary.helpful += 1;
+    } else if (entry.helpful === false) {
+      summary.unhelpful += 1;
+    }
+
+    const bucket = summary.byKey[entry.key] || { total: 0, helpful: 0, unhelpful: 0 };
+    bucket.total += 1;
+    if (helpful) {
+      bucket.helpful += 1;
+    } else if (entry.helpful === false) {
+      bucket.unhelpful += 1;
+    }
+    summary.byKey[entry.key] = bucket;
+  }
+
+  return summary;
+}
+
+function askQuestion(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
+async function collectFeedback(dir, options = {}) {
+  const findings = Array.isArray(options.findings) ? options.findings : [];
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+
+  if (findings.length === 0) {
+    return {
+      saved: 0,
+      skipped: 0,
+      helpful: 0,
+      unhelpful: 0,
+      entries: [],
+      relativeDir: path.relative(dir, ensureFeedbackDir(dir)),
+    };
+  }
+
+  if (!(stdin.isTTY && stdout.isTTY)) {
+    return {
+      mode: 'skipped-noninteractive',
+      saved: 0,
+      skipped: findings.length,
+      helpful: 0,
+      unhelpful: 0,
+      entries: [],
+      relativeDir: path.relative(dir, ensureFeedbackDir(dir)),
+    };
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const entries = [];
+
+  try {
+    for (const finding of findings) {
+      stdout.write(`\n  Feedback for ${finding.name} (${finding.key})\n`);
+      let answer = await askQuestion(rl, '  Was this helpful? (y/n) ');
+      answer = String(answer || '').trim().toLowerCase();
+
+      if (!['y', 'yes', 'n', 'no'].includes(answer)) {
+        continue;
+      }
+
+      entries.push(saveFeedback(dir, {
+        key: finding.key,
+        name: finding.name,
+        helpful: answer === 'y' || answer === 'yes',
+        platform: options.platform || null,
+        sourceCommand: options.sourceCommand || 'audit',
+        sourceUrl: finding.sourceUrl || null,
+        impact: finding.impact || null,
+        category: finding.category || null,
+        score: Number.isFinite(options.score) ? options.score : null,
+      }));
+    }
+  } finally {
+    rl.close();
+  }
+
+  const helpful = entries.filter((entry) => entry.helpful).length;
+  const unhelpful = entries.filter((entry) => entry.helpful === false).length;
+
+  return {
+    saved: entries.length,
+    skipped: findings.length - entries.length,
+    helpful,
+    unhelpful,
+    entries,
+    relativeDir: path.relative(dir, ensureFeedbackDir(dir)),
+    summary: getFeedbackSummary(dir),
+  };
+}
+
+module.exports = {
+  collectFeedback,
+  saveFeedback,
+  getFeedbackSummary,
+};