@nerviq/cli 1.12.0 → 1.14.0

package/src/harmony/cli.js

@@ -346,6 +346,237 @@ async function runHarmonyGovernance(options) {
   return summary;
 }
 
+// ─── Command: harmony score ──────────────────────────────────────────────────
+
+/**
+ * Output a standalone Harmony Score (0-100) with optional badge and CI threshold.
+ *
+ * Options:
+ *   --json          JSON output
+ *   --badge         Print shields.io badge markdown
+ *   --threshold N   Exit with code 1 if score < N (for CI gates)
+ *   --quiet         Score number only (for piping)
+ */
+async function runHarmonyScore(options) {
+  const dir = resolveDir(options);
+  const { harmonyAudit } = require('./audit');
+  const result = await harmonyAudit({ dir, silent: true });
+
+  const score = result.harmonyScore;
+  const threshold = parseInt(options.threshold, 10) || 0;
+  const pass = score >= threshold;
+
+  if (options.json) {
+    const output = {
+      harmonyScore: score,
+      platforms: result.platformScores,
+      activePlatforms: result.activePlatforms.map(p => p.platform),
+      driftCount: result.drift.drifts.length,
+      threshold: threshold || null,
+      pass,
+    };
+    if (options.badge) {
+      output.badge = getHarmonyBadgeMarkdown(score);
+      output.badgeUrl = getHarmonyBadgeUrl(score);
+    }
+    console.log(JSON.stringify(output, null, 2));
+    return output;
+  }
+
+  if (options.quiet) {
+    console.log(score);
+    return { score, pass };
+  }
+
+  console.log('');
+  console.log(c('  Harmony Score', 'bold'));
+  console.log(c('  ═══════════════════════════════════════', 'dim'));
+  console.log('');
+
+  // Score with color bar
+  const barWidth = 30;
+  const filled = Math.round((score / 100) * barWidth);
+  const empty = barWidth - filled;
+  const scoreColor = score >= 80 ? 'green' : score >= 50 ? 'yellow' : 'red';
+  const bar = c('\u2588'.repeat(filled), scoreColor) + c('\u2591'.repeat(empty), 'dim');
+  console.log(`  ${bar} ${c(`${score}/100`, scoreColor)}`);
+  console.log('');
+
+  // Per-platform breakdown
+  for (const ap of result.activePlatforms) {
+    const ps = result.platformScores[ap.platform];
+    const psColor = ps >= 70 ? 'green' : ps >= 40 ? 'yellow' : 'red';
+    console.log(`  ${ap.platform.padEnd(12)} ${ps !== null ? c(`${ps}/100`, psColor) : c('n/a', 'dim')}`);
+  }
+  console.log('');
+
+  // Drift summary
+  const driftCount = result.drift.drifts.length;
+  if (driftCount > 0) {
+    const critical = result.drift.drifts.filter(d => d.severity === 'critical').length;
+    const high = result.drift.drifts.filter(d => d.severity === 'high').length;
+    let driftMsg = `  ${driftCount} drift issue${driftCount !== 1 ? 's' : ''}`;
+    if (critical > 0) driftMsg += c(` (${critical} critical)`, 'red');
+    else if (high > 0) driftMsg += c(` (${high} high)`, 'yellow');
+    console.log(driftMsg);
+    console.log(c('  Run "nerviq harmony-audit" for details.', 'dim'));
+    console.log('');
+  }
+
+  // Badge output
+  if (options.badge) {
+    console.log(c('  Badge:', 'bold'));
+    console.log(`  ${getHarmonyBadgeMarkdown(score)}`);
+    console.log('');
+  }
+
+  // Threshold check
+  if (threshold > 0) {
+    if (pass) {
+      console.log(c(`  Threshold: ${score} >= ${threshold} PASS`, 'green'));
+    } else {
+      console.log(c(`  Threshold: ${score} < ${threshold} FAIL`, 'red'));
+    }
+    console.log('');
+  }
+
+  return { score, pass, platforms: result.platformScores };
+}
+
+// ─── Harmony Badge helpers ───────────────────────────────────────────────────
+
+function getHarmonyBadgeUrl(score) {
+  const color = score >= 80 ? 'brightgreen' : score >= 60 ? 'yellow' : score >= 40 ? 'orange' : 'red';
+  const label = encodeURIComponent('Harmony Score');
+  const message = encodeURIComponent(`${score}/100`);
+  return `https://img.shields.io/badge/${label}-${message}-${color}`;
+}
+
+function getHarmonyBadgeMarkdown(score) {
+  const url = getHarmonyBadgeUrl(score);
+  return `[![Harmony Score](${url})](https://github.com/nerviq/nerviq)`;
+}
+
+// ─── Command: harmony demo ──────────────────────────────────────────────────
+
+/**
+ * Zero-setup demo: creates a temporary multi-platform project, runs harmony
+ * audit on it, and shows how Nerviq detects cross-platform drift.
+ *
+ * This lets new users see Harmony's value instantly without configuring anything.
+ */
+async function runHarmonyDemo(options) {
+  const fs = require('fs');
+  const os = require('os');
+  const { harmonyAudit } = require('./audit');
+
+  console.log('');
+  console.log(c('  Harmony Demo — Zero-Setup Cross-Platform Drift Detection', 'bold'));
+  console.log(c('  ═══════════════════════════════════════════════════════', 'dim'));
+  console.log('');
+  console.log(c('  Creating a sample multi-platform project...', 'dim'));
+  console.log('');
+
+  // Create temp directory with realistic multi-platform configs
+  const demoDir = path.join(os.tmpdir(), `nerviq-harmony-demo-${Date.now()}`);
+  fs.mkdirSync(demoDir, { recursive: true });
+  fs.mkdirSync(path.join(demoDir, '.claude'), { recursive: true });
+  fs.mkdirSync(path.join(demoDir, '.cursor'), { recursive: true });
+  fs.mkdirSync(path.join(demoDir, '.github'), { recursive: true });
+
+  // Claude config — well-configured
+  fs.writeFileSync(path.join(demoDir, 'CLAUDE.md'), [
+    '# Project Instructions',
+    '',
+    '## Architecture',
+    'This is a Node.js API with PostgreSQL. Use Express for routing.',
+    '',
+    '## Testing',
+    'Run tests with `npm test`. All PRs require passing tests.',
+    '',
+    '## Security',
+    '- Never commit .env files',
+    '- Use parameterized queries for all database access',
+    '- Validate all user input',
+    '',
+    '## Code Style',
+    '- Use ESLint with the project config',
+    '- Prefer async/await over callbacks',
+    '- Add JSDoc comments for public functions',
+  ].join('\n'));
+
+  fs.writeFileSync(path.join(demoDir, '.claude', 'settings.json'), JSON.stringify({
+    permissions: {
+      allow: ['Read', 'Glob', 'Grep'],
+      deny: ['Bash(rm -rf *)'],
+    },
+    model: 'claude-sonnet-4-6',
+  }, null, 2));
+
+  // Cursor config — intentionally drifted (different rules, less security)
+  fs.writeFileSync(path.join(demoDir, '.cursorrules'), [
+    'You are a helpful coding assistant.',
+    'This is a Node.js project using Express.',
+    'Write clean, readable code.',
+    // Missing: security rules, testing rules, architecture details
+  ].join('\n'));
+
+  // Copilot config — partial coverage
+  fs.writeFileSync(path.join(demoDir, '.github', 'copilot-instructions.md'), [
+    '# Copilot Instructions',
+    '',
+    'This is a Node.js Express API project.',
+    'Use TypeScript-style JSDoc annotations.',
+    'Follow RESTful conventions for API endpoints.',
+    // Missing: security, testing, architecture details
+  ].join('\n'));
+
+  // Add a package.json for realism
+  fs.writeFileSync(path.join(demoDir, 'package.json'), JSON.stringify({
+    name: 'harmony-demo-project',
+    version: '1.0.0',
+    scripts: { test: 'jest' },
+  }, null, 2));
+
+  console.log(c('  Demo project created with 3 platforms:', 'bold'));
+  console.log(`    ${c('Claude', 'green')}   — Well-configured (CLAUDE.md + settings.json)`);
+  console.log(`    ${c('Cursor', 'yellow')}   — Basic rules only (.cursorrules)`);
+  console.log(`    ${c('Copilot', 'yellow')}  — Partial coverage (copilot-instructions.md)`);
+  console.log('');
+  console.log(c('  Intentional drift injected:', 'bold'));
+  console.log(`    ${c('\u2718', 'red')} Security rules only in Claude, missing from Cursor & Copilot`);
+  console.log(`    ${c('\u2718', 'red')} Testing instructions only in Claude`);
+  console.log(`    ${c('\u2718', 'red')} Architecture details inconsistent across platforms`);
+  console.log(`    ${c('\u2718', 'red')} Trust posture differs (Claude has explicit permissions)`);
+  console.log('');
+  console.log(c('  Running Harmony Audit...', 'dim'));
+  console.log('');
+
+  // Run the actual harmony audit on the demo project
+  const result = await harmonyAudit({ dir: demoDir, silent: false, verbose: !!options.verbose });
+
+  console.log('');
+  console.log(c('  ═══════════════════════════════════════════════════════', 'dim'));
+  console.log(c('  What you just saw:', 'bold'));
+  console.log('');
+  console.log('  Nerviq Harmony detected real configuration drift between');
+  console.log('  3 AI coding platforms in your project — differences in');
+  console.log('  instructions, security posture, and tool coverage that');
+  console.log('  cause inconsistent AI behavior.');
+  console.log('');
+  console.log(c('  Try it on your own project:', 'bold'));
+  console.log(`    ${c('npx @nerviq/cli harmony-audit', 'blue')}`);
+  console.log(`    ${c('npx @nerviq/cli harmony-score --threshold 70', 'blue')}`);
+  console.log('');
+
+  // Clean up
+  try {
+    fs.rmSync(demoDir, { recursive: true, force: true });
+  } catch (_e) { /* cleanup optional */ }
+
+  return result;
+}
+
 module.exports = {
   runHarmonyAudit,
   runHarmonySync,
@@ -353,4 +584,8 @@ module.exports = {
   runHarmonyAdvise,
   runHarmonyWatch,
   runHarmonyGovernance,
+  runHarmonyScore,
+  runHarmonyDemo,
+  getHarmonyBadgeUrl,
+  getHarmonyBadgeMarkdown,
 };

package/src/index.js

@@ -240,6 +240,7 @@ module.exports = {
     const { startHarmonyWatch } = require('./harmony/watch');
     const { saveHarmonyState, loadHarmonyState, getHarmonyHistory } = require('./harmony/memory');
     const { getHarmonyGovernanceSummary, formatHarmonyGovernanceReport } = require('./harmony/governance');
+    const { getHarmonyBadgeUrl, getHarmonyBadgeMarkdown } = require('./harmony/cli');
     return {
       buildCanonicalModel, detectActivePlatforms, detectDrift, formatDriftReport,
       harmonyAudit, formatHarmonyAuditReport,
@@ -247,6 +248,7 @@ module.exports = {
       generateStrategicAdvice, PLATFORM_STRENGTHS,
       startHarmonyWatch, saveHarmonyState, loadHarmonyState, getHarmonyHistory,
       getHarmonyGovernanceSummary, formatHarmonyGovernanceReport,
+      getHarmonyBadgeUrl, getHarmonyBadgeMarkdown,
     };
   })(),
   // Synergy (cross-platform amplification)

package/src/mcp-server.js

@@ -29,7 +29,78 @@
 
 'use strict';
 
-const { version } = require('../package.json');
+const { version } = require('../package.json');
+
+function buildMcpAuditPayload(result, options = {}) {
+  const verbose = Boolean(options.verbose);
+  const normalizedCheckCount = typeof result.checkCount === 'number'
+    ? result.checkCount
+    : typeof result.total === 'number'
+      ? result.total
+      : 0;
+
+  const payload = {
+    platform: result.platform,
+    score: result.score,
+    passed: result.passed,
+    failed: result.failed,
+    total: normalizedCheckCount,
+    checkCount: normalizedCheckCount,
+    scoreType: result.scoreType || 'live-audit-score',
+    grade: result.score >= 80 ? 'A' : result.score >= 60 ? 'B' : result.score >= 40 ? 'C' : 'D',
+    criticalFailures: (result.results || [])
+      .filter(r => r.passed === false && r.impact === 'critical')
+      .map(r => ({ key: r.key, id: r.id, name: r.name, fix: r.fix })),
+    highFailures: (result.results || [])
+      .filter(r => r.passed === false && r.impact === 'high')
+      .map(r => ({ key: r.key, id: r.id, name: r.name, fix: r.fix })),
+    topNextActions: (result.topNextActions || []).slice(0, 3).map((item) => ({
+      key: item.key,
+      name: item.name,
+      impact: item.impact,
+      fix: item.fix,
+    })),
+    suggestedNextCommand: result.suggestedNextCommand || null,
+  };
+
+  if (verbose) {
+    payload.results = (result.results || []).map(r => ({
+      key: r.key,
+      id: r.id,
+      name: r.name,
+      passed: r.passed,
+      impact: r.impact,
+      fix: r.passed === false ? r.fix : undefined,
+    }));
+  }
+
+  return payload;
+}
+
+function buildMcpHarmonyPayload(result, options = {}) {
+  const verbose = Boolean(options.verbose);
+  const payload = {
+    harmonyScore: result.harmonyScore,
+    activePlatforms: result.activePlatforms || [],
+    platformScores: result.platformScores || {},
+    driftCount: result.driftCount || (result.drifts || []).length || 0,
+    criticalDrifts: (result.drifts || [])
+      .filter(d => d.severity === 'critical')
+      .map(d => ({ type: d.type, description: d.description, recommendation: d.recommendation })),
+    recommendations: (result.recommendations || []).slice(0, 5),
+  };
+
+  if (verbose) {
+    payload.allDrifts = (result.drifts || []).map(d => ({
+      type: d.type,
+      severity: d.severity,
+      description: d.description,
+      recommendation: d.recommendation,
+    }));
+  }
+
+  return payload;
+}
 
 // ─── Tool definitions ────────────────────────────────────────────────────────
 
@@ -132,74 +203,26 @@ const TOOLS = [
 
 // ─── Tool handlers ───────────────────────────────────────────────────────────
 
-async function handleAudit(input) {
+async function handleAudit(input) {
   const { audit } = require('./audit');
   const dir = input.dir || process.cwd();
   const platform = input.platform || 'claude';
   const verbose = Boolean(input.verbose);
 
-  const result = await audit({ dir, platform, silent: true, verbose });
-
-  // Return clean JSON without ANSI codes
-  const clean = {
-    platform: result.platform,
-    score: result.score,
-    passed: result.passed,
-    failed: result.failed,
-    total: result.total,
-    grade: result.score >= 80 ? 'A' : result.score >= 60 ? 'B' : result.score >= 40 ? 'C' : 'D',
-    criticalFailures: (result.results || [])
-      .filter(r => r.passed === false && r.impact === 'critical')
-      .map(r => ({ key: r.key, id: r.id, name: r.name, fix: r.fix })),
-    highFailures: (result.results || [])
-      .filter(r => r.passed === false && r.impact === 'high')
-      .map(r => ({ key: r.key, id: r.id, name: r.name, fix: r.fix })),
-    suggestedNextCommand: result.suggestedNextCommand || null,
-  };
-
-  if (verbose) {
-    clean.allResults = (result.results || []).map(r => ({
-      key: r.key,
-      id: r.id,
-      name: r.name,
-      passed: r.passed,
-      impact: r.impact,
-      fix: r.passed === false ? r.fix : undefined,
-    }));
-  }
-
-  return { content: [{ type: 'text', text: JSON.stringify(clean, null, 2) }] };
-}
+  const result = await audit({ dir, platform, silent: true, verbose });
+  const clean = buildMcpAuditPayload(result, { verbose });
+  return { content: [{ type: 'text', text: JSON.stringify(clean, null, 2) }] };
+}
 
 async function handleHarmony(input) {
   const { harmonyAudit } = require('./harmony/audit');
   const dir = input.dir || process.cwd();
   const verbose = Boolean(input.verbose);
 
-  const result = await harmonyAudit({ dir, silent: true });
-
-  const clean = {
-    harmonyScore: result.harmonyScore,
-    activePlatforms: result.activePlatforms || [],
-    platformScores: result.platformScores || {},
-    driftCount: result.driftCount || 0,
-    criticalDrifts: (result.drifts || [])
-      .filter(d => d.severity === 'critical')
-      .map(d => ({ type: d.type, description: d.description, recommendation: d.recommendation })),
-    recommendations: (result.recommendations || []).slice(0, 5),
-  };
-
-  if (verbose) {
-    clean.allDrifts = (result.drifts || []).map(d => ({
-      type: d.type,
-      severity: d.severity,
-      description: d.description,
-      recommendation: d.recommendation,
-    }));
-  }
-
-  return { content: [{ type: 'text', text: JSON.stringify(clean, null, 2) }] };
-}
+  const result = await harmonyAudit({ dir, silent: true });
+  const clean = buildMcpHarmonyPayload(result, { verbose });
+  return { content: [{ type: 'text', text: JSON.stringify(clean, null, 2) }] };
+}
 
 async function handleSetup(input) {
   const { setup } = require('./setup');
@@ -370,4 +393,17 @@ function main() {
   });
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  TOOLS,
+  buildMcpAuditPayload,
+  buildMcpHarmonyPayload,
+  handleAudit,
+  handleHarmony,
+  handleSetup,
+  handleDrift,
+  main,
+};

package/src/opencode/freshness.js

@@ -29,18 +29,39 @@ const P0_SOURCES = [
     stalenessThresholdDays: 14,
     verifiedAt: '2026-04-07',
   },
-  {
-    key: 'opencode-plugin-api',
-    label: 'OpenCode Plugin API',
-    url: 'https://opencode.ai/docs/plugins/',
-    stalenessThresholdDays: 30,
-    verifiedAt: '2026-04-07',
-  },
-  {
-    key: 'opencode-permissions-docs',
-    label: 'OpenCode Permissions Documentation',
-    url: 'https://opencode.ai/docs/permissions/',
-    stalenessThresholdDays: 30,
+  {
+    key: 'opencode-plugin-api',
+    label: 'OpenCode Plugin API',
+    url: 'https://opencode.ai/docs/plugins/',
+    stalenessThresholdDays: 30,
+    verifiedAt: '2026-04-07',
+  },
+  {
+    key: 'opencode-agents-docs',
+    label: 'OpenCode Agents',
+    url: 'https://opencode.ai/docs/agents/',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'opencode-models-docs',
+    label: 'OpenCode Models',
+    url: 'https://opencode.ai/docs/models',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'opencode-github-docs',
+    label: 'OpenCode GitHub Integration',
+    url: 'https://opencode.ai/docs/github/',
+    stalenessThresholdDays: 14,
+    verifiedAt: '2026-04-10',
+  },
+  {
+    key: 'opencode-permissions-docs',
+    label: 'OpenCode Permissions Documentation',
+    url: 'https://opencode.ai/docs/permissions/',
+    stalenessThresholdDays: 30,
     verifiedAt: '2026-04-07',
   },
 ];
@@ -78,15 +99,39 @@ const PROPAGATION_CHECKLIST = [
       'src/opencode/techniques.js — update MCP checks',
     ],
   },
-  {
-    trigger: 'Known security bug fixed or new bug reported',
-    targets: [
-      'src/opencode/techniques.js — update security checks (E02, E03, D05)',
-      'src/opencode/governance.js — update platformCaveats',
-      'src/opencode/freshness.js — verify against latest release',
-    ],
-  },
-];
+  {
+    trigger: 'Known security bug fixed or new bug reported',
+    targets: [
+      'src/opencode/techniques.js — update security checks (E02, E03, D05)',
+      'src/opencode/governance.js — update platformCaveats',
+      'src/opencode/freshness.js — verify against latest release',
+    ],
+  },
+  {
+    trigger: 'OpenCode agent or subagent behavior change',
+    targets: [
+      'src/opencode/techniques.js — update agent and multi-session checks',
+      'src/opencode/governance.js — update permission guidance for plan/build/agent surfaces',
+      'src/source-urls.js — refresh OpenCode agent source mappings',
+    ],
+  },
+  {
+    trigger: 'OpenCode model catalog or provider-option change',
+    targets: [
+      'src/opencode/techniques.js — update model-awareness and provider-option assumptions',
+      'src/opencode/setup.js — update starter config guidance for model selection',
+      'src/source-urls.js — refresh OpenCode model source mappings',
+    ],
+  },
+  {
+    trigger: 'OpenCode GitHub integration or workflow contract change',
+    targets: [
+      'src/opencode/techniques.js — update GitHub/workflow checks',
+      'src/opencode/setup.js — update GitHub starter guidance',
+      'src/source-urls.js — refresh OpenCode GitHub source mappings',
+    ],
+  },
+];
 
 function checkReleaseGate(sourceVerifications = {}) {
   const now = new Date();