@nerviq/cli 1.11.0 → 1.13.0

package/src/doctor.js

@@ -5,11 +5,13 @@
  * Checks: Node version, dependencies, platform detection, freshness gates.
  */
 
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { version } = require('../package.json');
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { version } = require('../package.json');
+const { validateDeclaredMcpServers } = require('./mcp-validation');
+const { validateDeclaredHooks } = require('./hook-validation');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -25,11 +27,11 @@ 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/'],
+const PLATFORM_SIGNALS = {
+  claude:    ['CLAUDE.md', '.claude/CLAUDE.md', '.claude/settings.json', '.mcp.json'],
+  codex:     ['AGENTS.md', '.codex/', '.codex/config.toml'],
+  cursor:    ['.cursor/rules/', '.cursor/mcp.json', '.cursorrules'],
+  copilot:   ['.github/copilot-instructions.md', '.github/', '.vscode/mcp.json'],
   gemini:    ['GEMINI.md', '.gemini/', '.gemini/settings.json'],
   windsurf:  ['.windsurf/', '.windsurfrules', '.windsurf/rules/'],
   aider:     ['.aider.conf.yml', '.aider.model.settings.yml'],
@@ -162,46 +164,59 @@ function checkGitRepo(dir) {
 
 // ─── Main doctor function ────────────────────────────────────────────────────
 
-async function runDoctor({ dir = process.cwd(), json = false, verbose = false } = {}) {
-  const startMs = Date.now();
-
-  const checks = [
+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;
+  ];
+
+  const detectedPlatforms = (checks.find(c => c.detected) || {}).detected || [];
+  const freshnessChecks = checkFreshnessGates();
+  const mcpSummary = await validateDeclaredMcpServers({ dir, detectedPlatforms });
+  const hookSummary = validateDeclaredHooks({ dir, detectedPlatforms });
+
+  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;
 
-  if (json) {
-    return JSON.stringify({
-      nerviq: version,
+  const freshPass = freshnessChecks.filter(f => f.status === 'pass').length;
+  const freshWarn = freshnessChecks.filter(f => f.status !== 'pass').length;
+
+  const overallOk = totalFail === 0 && mcpSummary.fail === 0 && hookSummary.fail === 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);
-  }
+      freshnessChecks,
+      mcpChecks: mcpSummary.checks,
+      hookChecks: hookSummary.checks,
+      totalPass,
+      totalWarn,
+      totalFail,
+      freshPass,
+      freshWarn,
+      mcpDeclared: mcpSummary.declared,
+      mcpPass: mcpSummary.pass,
+      mcpWarn: mcpSummary.warn,
+      mcpFail: mcpSummary.fail,
+      hookDeclared: hookSummary.declared,
+      hookPass: hookSummary.pass,
+      hookWarn: hookSummary.warn,
+      hookFail: hookSummary.fail,
+      elapsed,
+    }, null, 2);
+  }
 
   const lines = [''];
   lines.push(c(`  nerviq doctor  v${version}`, 'bold'));
@@ -219,10 +234,9 @@ async function runDoctor({ dir = process.cwd(), json = false, verbose = false }
   }
 
   // Platform detection detail
-  const detectedPlatforms = (checks.find(c => c.detected) || {}).detected || [];
-  if (detectedPlatforms.length > 0) {
-    lines.push('');
-    lines.push(c('  Detected Platforms', 'bold'));
+  if (detectedPlatforms.length > 0) {
+    lines.push('');
+    lines.push(c('  Detected Platforms', 'bold'));
     for (const p of detectedPlatforms) {
       lines.push(`    ${c('✓', 'green')}  ${p}`);
     }
@@ -231,18 +245,67 @@ async function runDoctor({ dir = process.cwd(), json = false, verbose = false }
   // 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`);
+  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('  MCP Servers', 'bold'));
+  if (mcpSummary.checks.length === 0) {
+    lines.push(c('    No declared MCP servers found in the detected project surfaces.', 'dim'));
+  } else {
+    for (const item of mcpSummary.checks) {
+      const icon = item.status === 'pass'
+        ? c('✓', 'green')
+        : item.status === 'warn'
+          ? c('⚠', 'yellow')
+          : c('✗', 'red');
+      const label = `${item.platform}/${item.scope}`.padEnd(16);
+      lines.push(`    ${icon}  ${label} ${item.serverName}  ${c(item.detail, item.status === 'pass' ? 'dim' : item.status === 'warn' ? 'yellow' : 'red')}`);
+      if (verbose && item.source) {
+        lines.push(c(`         Source: ${item.source}`, 'dim'));
+      }
+      if (item.fix && (verbose || item.status === 'fail')) {
+        lines.push(c(`         Fix: ${item.fix}`, item.status === 'fail' ? 'yellow' : 'dim'));
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push(c('  Hook Runtime', 'bold'));
+  if (hookSummary.checks.length === 0) {
+    lines.push(c('    No declared hooks found in the detected project surfaces.', 'dim'));
+  } else {
+    for (const item of hookSummary.checks) {
+      const icon = item.status === 'pass'
+        ? c('✓', 'green')
+        : item.status === 'warn'
+          ? c('⚠', 'yellow')
+          : c('✗', 'red');
+      const label = `${item.platform}/${item.validationMode}`.padEnd(16);
+      lines.push(`    ${icon}  ${label} ${item.label}  ${c(item.detail, item.status === 'pass' ? 'dim' : item.status === 'warn' ? 'yellow' : 'red')}`);
+      if (verbose && item.script) {
+        lines.push(c(`         Script: ${item.script}`, 'dim'));
+      }
+      if (verbose && item.executable) {
+        lines.push(c(`         Runtime: ${item.executable}`, 'dim'));
+      }
+      if (item.fix && (verbose || item.status === 'fail')) {
+        lines.push(c(`         Fix: ${item.fix}`, item.status === 'fail' ? 'yellow' : 'dim'));
+      }
+    }
+  }
+
+  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(`    MCP:       ${c(String(mcpSummary.pass), 'green')} pass  ${mcpSummary.warn > 0 ? c(String(mcpSummary.warn), 'yellow') + ' warn  ' : ''}${mcpSummary.fail > 0 ? c(String(mcpSummary.fail), 'red') + ' fail' : ''}${c(`(${mcpSummary.declared} declared)`, 'dim')}`);
+  lines.push(`    Hooks:     ${c(String(hookSummary.pass), 'green')} pass  ${hookSummary.warn > 0 ? c(String(hookSummary.warn), 'yellow') + ' warn  ' : ''}${hookSummary.fail > 0 ? c(String(hookSummary.fail), 'red') + ' fail' : ''}${c(`(${hookSummary.declared} declared)`, 'dim')}`);
+  lines.push(`    Status:    ${overallOk ? c('✓ Healthy', 'green') : c('✗ Issues found', 'red')}`);
+  lines.push(`    Duration:  ${elapsed}ms`);
   lines.push('');
 
   if (!overallOk) {

package/src/freshness.js

@@ -4,7 +4,8 @@
  * Release gates, recurring probes, propagation checklists,
  * and staleness blocking for Claude Code surfaces.
  *
- * P0 sources from code.claude.com/docs, propagation for CLAUDE.md format changes.
+ * P0 sources from code.claude.com/docs and official Anthropic launch posts,
+ * with propagation for CLAUDE.md, output style, and agent harness changes.
  */
 
 const { version } = require('../package.json');
@@ -55,18 +56,46 @@ const P0_SOURCES = [
     stalenessThresholdDays: 14,
     verifiedAt: '2026-04-07',
   },
-  {
-    key: 'claude-settings-docs',
-    label: 'Claude Code Settings Documentation',
-    url: 'https://code.claude.com/docs/en/settings',
-    stalenessThresholdDays: 30,
-    verifiedAt: '2026-04-07',
-  },
-  {
-    key: 'anthropic-changelog',
-    label: 'Claude Code Changelog',
-    url: 'https://code.claude.com/docs/en/changelog',
-    stalenessThresholdDays: 14,
+  {
+    key: 'claude-settings-docs',
+    label: 'Claude Code Settings Documentation',
+    url: 'https://code.claude.com/docs/en/settings',
+    stalenessThresholdDays: 30,
+    verifiedAt: '2026-04-07',
+  },
+  {
+    key: 'claude-output-styles-docs',
+    label: 'Claude Code Output Styles / Insights',
+    url: 'https://code.claude.com/docs/en/output-styles',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'claude-best-practices-docs',
+    label: 'Claude Code Best Practices / Auto Mode',
+    url: 'https://code.claude.com/docs/en/best-practices',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'claude-agent-sdk-docs',
+    label: 'Claude Agent SDK Overview',
+    url: 'https://code.claude.com/docs/en/agent-sdk/overview',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'claude-xcode-agent-sdk',
+    label: 'Anthropic Xcode Agent SDK Launch',
+    url: 'https://www.anthropic.com/news/apple-xcode-claude-agent-sdk',
+    stalenessThresholdDays: 30,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'anthropic-changelog',
+    label: 'Claude Code Changelog',
+    url: 'https://code.claude.com/docs/en/changelog',
+    stalenessThresholdDays: 14,
     verifiedAt: '2026-04-07',
   },
 ];
@@ -98,14 +127,38 @@ const PROPAGATION_CHECKLIST = [
       'src/context.js — update mcpConfig parsing',
     ],
   },
-  {
-    trigger: 'Permissions model change (allow/deny lists, operator/user split)',
-    targets: [
-      'src/governance.js — update permissionProfiles',
-      'src/techniques.js — update permission checks',
-    ],
-  },
-];
+  {
+    trigger: 'Permissions model change (allow/deny lists, operator/user split)',
+    targets: [
+      'src/governance.js — update permissionProfiles',
+      'src/techniques.js — update permission checks',
+    ],
+  },
+  {
+    trigger: 'Output style / Insights change (system prompt layering, outputStyle storage, learning mode behavior)',
+    targets: [
+      'src/techniques.js — update Claude settings and instruction-surface checks that depend on system-prompt-adjacent behavior',
+      'src/setup.js — update Claude settings starter templates if outputStyle guidance changes',
+      'src/source-urls.js — refresh Claude feature source mappings when output style docs move or split',
+    ],
+  },
+  {
+    trigger: 'Best-practices or auto mode change (permission classifier, unattended mode, safety fallback behavior)',
+    targets: [
+      'src/governance.js — update permission mode caveats and policy guidance',
+      'src/techniques.js — update Claude trust/verification checks tied to auto mode or unattended workflows',
+      'src/source-urls.js — refresh Claude best-practice source mappings if guidance moves',
+    ],
+  },
+  {
+    trigger: 'Agent SDK / harness or native integration change (SDK surfaces, subagents, background tasks, Xcode bridge)',
+    targets: [
+      'src/techniques.js — update Claude modern-capability checks and cross-surface expectations',
+      'src/mcp-packs.js — revisit pack assumptions when native integrations change MCP usage',
+      'src/source-urls.js — refresh Claude source mappings for SDK and integration surfaces',
+    ],
+  },
+];
 
 /**
  * Release gate: check if all P0 sources are within staleness threshold.

package/src/gemini/freshness.js

@@ -27,18 +27,39 @@ const P0_SOURCES = [
     stalenessThresholdDays: 30,
     verifiedAt: '2026-04-07',
   },
-  {
-    key: 'gemini-md-guide',
-    label: 'GEMINI.md Guide',
-    url: 'https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html',
-    stalenessThresholdDays: 30,
-    verifiedAt: '2026-04-07',
-  },
-  {
-    key: 'gemini-hooks-docs',
-    label: 'Gemini Hooks Documentation',
-    url: 'https://google-gemini.github.io/gemini-cli/docs/hooks/',
-    stalenessThresholdDays: 30,
+  {
+    key: 'gemini-md-guide',
+    label: 'GEMINI.md Guide',
+    url: 'https://google-gemini.github.io/gemini-cli/docs/cli/gemini-md.html',
+    stalenessThresholdDays: 30,
+    verifiedAt: '2026-04-07',
+  },
+  {
+    key: 'gemini-trusted-folders-docs',
+    label: 'Gemini Trusted Folders',
+    url: 'https://google-gemini.github.io/gemini-cli/docs/cli/trusted-folders.html',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'gemini-ide-integration-docs',
+    label: 'Gemini IDE Integration',
+    url: 'https://google-gemini.github.io/gemini-cli/docs/ide-integration.html',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'gemini-architecture-docs',
+    label: 'Gemini Architecture Overview',
+    url: 'https://google-gemini.github.io/gemini-cli/docs/architecture.html',
+    stalenessThresholdDays: 30,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'gemini-hooks-docs',
+    label: 'Gemini Hooks Documentation',
+    url: 'https://google-gemini.github.io/gemini-cli/docs/hooks/',
+    stalenessThresholdDays: 30,
     verifiedAt: '2026-04-07',
   },
   {
@@ -114,15 +135,39 @@ const PROPAGATION_CHECKLIST = [
       'src/gemini/setup.js — update sandbox starter template',
     ],
   },
-  {
-    trigger: 'Policy engine syntax or rule format change',
-    targets: [
-      'src/gemini/techniques.js — update policy validation checks',
-      'src/gemini/governance.js — update policy templates and caveats',
-      'src/gemini/config-parser.js — update policy parsing rules',
-    ],
-  },
-];
+  {
+    trigger: 'Policy engine syntax or rule format change',
+    targets: [
+      'src/gemini/techniques.js — update policy validation checks',
+      'src/gemini/governance.js — update policy templates and caveats',
+      'src/gemini/config-parser.js — update policy parsing rules',
+    ],
+  },
+  {
+    trigger: 'Trusted-folder or safe-mode behavior change',
+    targets: [
+      'src/gemini/techniques.js — update trust/safe-mode checks',
+      'src/gemini/governance.js — update trusted-folder caveats and permission guidance',
+      'src/source-urls.js — refresh Gemini trust source mappings',
+    ],
+  },
+  {
+    trigger: 'IDE integration change (workspace context, diffing, companion extension behavior)',
+    targets: [
+      'src/gemini/techniques.js — update IDE-assist and context-surface checks',
+      'src/gemini/setup.js — update IDE integration starter guidance',
+      'src/source-urls.js — refresh Gemini IDE source mappings',
+    ],
+  },
+  {
+    trigger: 'Architecture or orchestration change (packages/core, tool flow, approval path)',
+    targets: [
+      'src/gemini/context.js — revisit assumptions tied to tool and session orchestration',
+      'src/gemini/techniques.js — update modern-feature and tool-flow checks',
+      'src/source-urls.js — refresh Gemini architecture source mappings',
+    ],
+  },
+];
 
 /**
  * Release gate: check if all P0 sources are within staleness threshold.

package/src/governance.js

@@ -104,19 +104,19 @@ const HOOK_REGISTRY = [
     dryRunExample: 'Edit a catalog file and verify duplicate check runs without blocking.',
     rollbackPath: 'Remove the PostToolUse hook entry from settings.',
   },
-  {
-    key: 'injection-defense',
-    file: '.claude/hooks/injection-defense.sh',
-    triggerPoint: 'PostToolUse',
-    matcher: 'WebFetch|WebSearch',
-    purpose: 'Scans web tool outputs for common prompt injection patterns.',
-    filesTouched: ['tools/failure-log.txt'],
-    sideEffects: ['Logs alerts to failure log.', 'Returns a systemMessage warning if patterns detected.'],
-    risk: 'low',
-    riskLevel: 'low',
-    dryRunExample: 'Run a WebFetch and verify output is scanned for injection patterns.',
-    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
-  },
+  {
+    key: 'injection-defense',
+    file: '.claude/hooks/injection-defense.js',
+    triggerPoint: 'PostToolUse',
+    matcher: 'WebFetch|WebSearch|Read|Grep|Glob|mcp__.*',
+    purpose: 'Scans external content flows for common prompt injection patterns and logs suspicious findings.',
+    filesTouched: ['.claude/logs/prompt-injection-alerts.log'],
+    sideEffects: ['Appends an alert line when suspicious external content is detected.'],
+    risk: 'low',
+    riskLevel: 'low',
+    dryRunExample: 'Run a WebFetch or MCP-backed tool call and verify suspicious content is logged for review.',
+    rollbackPath: 'Remove the PostToolUse hook entry from settings.',
+  },
   {
     key: 'trust-drift-check',
     file: '.claude/hooks/trust-drift-check.sh',
@@ -299,23 +299,24 @@ function buildHookConfig(hookFiles, profileKey) {
     return {};
   }
 
-  // Detect hook runtime: .js files use node, .sh files use bash
-  const hookCommand = (file) => {
-    if (file.endsWith('.js')) return `node .claude/hooks/${file}`;
-    return `bash .claude/hooks/${file}`;
-  };
-  const isSecrets = (f) => f === 'protect-secrets.sh' || f === 'protect-secrets.js';
-  const isSession = (f) => f === 'session-start.sh' || f === 'session-start.js';
-
-  const hookConfig = {
-    PostToolUse: [{
-      matcher: 'Write|Edit',
-      hooks: uniqueFiles
-        .filter(file => !isSecrets(file) && !isSession(file))
-        .map(file => ({
-          type: 'command',
-          command: hookCommand(file),
-          timeout: 10,
+  // Detect hook runtime: .js files use node, .sh files use bash
+  const hookCommand = (file) => {
+    if (file.endsWith('.js')) return `node .claude/hooks/${file}`;
+    return `bash .claude/hooks/${file}`;
+  };
+  const isSecrets = (f) => f === 'protect-secrets.sh' || f === 'protect-secrets.js';
+  const isSession = (f) => f === 'session-start.sh' || f === 'session-start.js';
+  const isInjection = (f) => f === 'injection-defense.sh' || f === 'injection-defense.js';
+
+  const hookConfig = {
+    PostToolUse: [{
+      matcher: 'Write|Edit',
+      hooks: uniqueFiles
+        .filter(file => !isSecrets(file) && !isSession(file) && !isInjection(file))
+        .map(file => ({
+          type: 'command',
+          command: hookCommand(file),
+          timeout: 10,
         })),
     }],
   };
@@ -333,16 +334,29 @@ function buildHookConfig(hookFiles, profileKey) {
   }
 
   const sessionFile = uniqueFiles.find(isSession);
-  if (sessionFile) {
-    hookConfig.SessionStart = [{
-      matcher: '*',
-      hooks: [{
-        type: 'command',
+  if (sessionFile) {
+    hookConfig.SessionStart = [{
+      matcher: '*',
+      hooks: [{
+        type: 'command',
         command: hookCommand(sessionFile),
         timeout: 5,
-      }],
-    }];
-  }
+      }],
+    }];
+  }
+
+  const injectionFile = uniqueFiles.find(isInjection);
+  if (injectionFile) {
+    hookConfig.PostToolUse = hookConfig.PostToolUse || [];
+    hookConfig.PostToolUse.push({
+      matcher: 'WebFetch|WebSearch|Read|Grep|Glob|mcp__.*',
+      hooks: [{
+        type: 'command',
+        command: hookCommand(injectionFile),
+        timeout: 5,
+      }],
+    });
+  }
 
   if ((hookConfig.PostToolUse[0].hooks || []).length === 0) {
     delete hookConfig.PostToolUse;
@@ -576,11 +590,13 @@ function renderGovernanceMarkdown(summary) {
   return lines.join('\n');
 }
 
-module.exports = {
-  PERMISSION_PROFILES,
-  getPermissionProfile,
-  isWritableProfile,
-  ensureWritableProfile,
+module.exports = {
+  PERMISSION_PROFILES,
+  HOOK_REGISTRY,
+  POLICY_PACKS,
+  getPermissionProfile,
+  isWritableProfile,
+  ensureWritableProfile,
   buildSettingsForProfile,
   getGovernanceSummary,
   printGovernanceSummary,