@nerviq/cli 0.9.5 → 0.9.6

package/bin/cli.js

@@ -8,6 +8,7 @@ const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, ren
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
 const { writeSnapshotArtifact, recordRecommendationOutcome, formatRecommendationOutcomeSummary, getRecommendationOutcomeSummary } = require('../src/activity');
 const { collectFeedback } = require('../src/feedback');
+const { startServer } = require('../src/server');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -21,7 +22,7 @@ const COMMAND_ALIASES = {
   gov: 'governance',
   outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'serve', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -72,6 +73,7 @@ function parseArgs(rawArgs) {
   let feedbackScoreDelta = null;
   let platform = 'claude';
   let format = null;
+  let port = null;
   let commandSet = false;
   let extraArgs = [];
   let convertFrom = null;
@@ -82,7 +84,7 @@ function parseArgs(rawArgs) {
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to') {
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta' || arg === '--platform' || arg === '--format' || arg === '--from' || arg === '--to' || arg === '--port') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -104,6 +106,7 @@ function parseArgs(rawArgs) {
       if (arg === '--format') format = value.trim().toLowerCase();
       if (arg === '--from') { convertFrom = value.trim(); migrateFrom = value.trim(); }
       if (arg === '--to') { convertTo = value.trim(); migrateTo = value.trim(); }
+      if (arg === '--port') port = value.trim();
       i++;
       continue;
     }
@@ -183,6 +186,11 @@ function parseArgs(rawArgs) {
       continue;
     }
 
+    if (arg.startsWith('--port=')) {
+      port = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
     if (arg.startsWith('--')) {
       flags.push(arg);
       continue;
@@ -198,7 +206,7 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, platform, format, port, extraArgs, convertFrom, convertTo, migrateFrom, migrateTo };
 }
 
 const HELP = `
@@ -234,6 +242,7 @@ const HELP = `
     npx nerviq deep-review      AI-powered config review (opt-in, uses API)
     npx nerviq interactive      Step-by-step guided wizard
     npx nerviq watch            Live monitoring on config changes with cross-platform watch fallback
+    npx nerviq serve --port 3000 Start the local Nerviq HTTP API
     npx nerviq badge            Generate shields.io badge markdown
     npx nerviq feedback         Record recommendation outcomes or show local outcome summary
 
@@ -263,6 +272,7 @@ const HELP = `
     --score-delta N Optional observed score delta tied to the outcome
     --platform NAME Choose platform surface (claude default, codex advisory/build preview)
     --format NAME   Output format for audit results (json, sarif)
+    --port N        Port for \`serve\` (default: 3000)
     --feedback      After audit output, prompt "Was this helpful? (y/n)" for each displayed top action and save answers locally
     --snapshot      Save a normalized snapshot artifact under .claude/nerviq/snapshots/
     --lite          Show a short top-3 quick scan with one clear next command
@@ -298,6 +308,7 @@ const HELP = `
     npx nerviq benchmark --out benchmark.md
     npx nerviq feedback
     npx nerviq feedback --key permissionDeny --status accepted --effect positive --score-delta 12
+    npx nerviq serve --port 3000
     npx nerviq --json --threshold 60
     npx nerviq setup --auto
     npx nerviq interactive
@@ -345,6 +356,7 @@ async function main() {
     require: parsed.requireChecks,
     platform: parsed.platform || 'claude',
     format: parsed.format || null,
+    port: parsed.port !== null ? Number(parsed.port) : null,
     dir: process.cwd()
   };
 
@@ -358,6 +370,11 @@ async function main() {
     process.exit(1);
   }
 
+  if (options.port !== null && (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535)) {
+    console.error('\n  Error: --port must be an integer between 0 and 65535.\n');
+    process.exit(1);
+  }
+
   if (options.threshold !== null && (!Number.isFinite(options.threshold) || options.threshold < 0 || options.threshold > 100)) {
     console.error('\n  Error: --threshold must be a number between 0 and 100.\n');
     process.exit(1);
@@ -396,7 +413,7 @@ async function main() {
     const FULL_COMMAND_SET = new Set([
       'audit', 'scan', 'badge', 'augment', 'suggest-only', 'setup', 'plan', 'apply',
       'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'insights',
-      'history', 'compare', 'trend', 'feedback', 'catalog', 'help', 'version',
+      'history', 'compare', 'trend', 'feedback', 'catalog', 'serve', 'help', 'version',
       // Harmony + Synergy (cross-platform)
       'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise',
       'harmony-watch', 'harmony-governance', 'synergy-report',
@@ -751,6 +768,25 @@ async function main() {
         }
       }
       process.exit(0);
+    } else if (normalizedCommand === 'serve') {
+      const server = await startServer({
+        port: options.port == null ? 3000 : options.port,
+        baseDir: options.dir,
+      });
+      const address = server.address();
+      const resolvedPort = address && typeof address === 'object' ? address.port : options.port;
+      console.log('');
+      console.log(`  nerviq API listening on http://127.0.0.1:${resolvedPort}`);
+      console.log('  Endpoints: /api/health, /api/catalog, /api/audit, /api/harmony');
+      console.log('');
+
+      const closeServer = () => {
+        server.close(() => process.exit(0));
+      };
+
+      process.on('SIGINT', closeServer);
+      process.on('SIGTERM', closeServer);
+      return;
     } else if (normalizedCommand === 'doctor') {
       const { runDoctor } = require('../src/doctor');
       const output = await runDoctor({ dir: options.dir, json: options.json, verbose: options.verbose });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.",
   "main": "src/index.js",
   "bin": {
@@ -20,7 +20,7 @@
     "test": "node test/run.js",
     "test:jest": "jest",
     "test:coverage": "jest --coverage",
-    "test:all": "node test/run.js && node test/check-matrix.js && node test/codex-check-matrix.js && node test/golden-matrix.js && node test/codex-golden-matrix.js && node test/security-tests.js && jest",
+    "test:all": "node test/run.js && node test/check-matrix.js && node test/codex-check-matrix.js && node test/golden-matrix.js && node test/codex-golden-matrix.js && node test/gemini-check-matrix.js && node test/gemini-golden-matrix.js && node test/copilot-check-matrix.js && node test/copilot-golden-matrix.js && node test/cursor-check-matrix.js && node test/cursor-golden-matrix.js && node test/security-tests.js && jest",
     "benchmark:perf": "node tools/benchmark.js",
     "catalog": "node -e \"const {generateCatalog}=require('./src/catalog');console.log(JSON.stringify(generateCatalog(),null,2))\""
   },

package/src/audit.js

@@ -26,6 +26,7 @@ const { getBadgeMarkdown } = require('./badge');
 const { sendInsights, getLocalInsights } = require('./insights');
 const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
 const { formatSarif } = require('./formatters/sarif');
+const { loadPlugins, mergePluginChecks } = require('./plugins');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -728,8 +729,14 @@ async function audit(options) {
   const results = [];
   const outcomeSummary = getRecommendationOutcomeSummary(options.dir);
 
+  // Load and merge plugin checks
+  const plugins = loadPlugins(options.dir);
+  const techniques = plugins.length > 0
+    ? mergePluginChecks(spec.techniques, plugins)
+    : spec.techniques;
+
   // Run all technique checks
-  for (const [key, technique] of Object.entries(spec.techniques)) {
+  for (const [key, technique] of Object.entries(techniques)) {
     const passed = technique.check(ctx);
     const file = typeof technique.file === 'function' ? (technique.file(ctx) ?? null) : (technique.file ?? null);
     const line = typeof technique.line === 'function' ? (technique.line(ctx) ?? null) : (technique.line ?? null);

package/src/index.js

@@ -87,6 +87,8 @@ const { setupOpenCode } = require('./opencode/setup');
 const { getOpenCodeGovernanceSummary } = require('./opencode/governance');
 const { runOpenCodeDeepReview } = require('./opencode/deep-review');
 const { opencodeInteractive } = require('./opencode/interactive');
+const { detectPlatforms, getCatalog, synergyReport } = require('./public-api');
+const { createServer, startServer } = require('./server');
 
 module.exports = {
   audit,
@@ -96,6 +98,11 @@ module.exports = {
   applyProposalBundle,
   getGovernanceSummary,
   runBenchmark,
+  detectPlatforms,
+  getCatalog,
+  synergyReport,
+  createServer,
+  startServer,
   DOMAIN_PACKS,
   detectDomainPacks,
   MCP_PACKS,

package/src/plugins.js

@@ -0,0 +1,110 @@
+/**
+ * Plugin system for Nerviq.
+ * Allows users to extend audits with custom checks via nerviq.config.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_CHECK_FIELDS = ['id', 'name', 'check', 'impact', 'category', 'fix'];
+const VALID_IMPACTS = ['critical', 'high', 'medium', 'low'];
+
+/**
+ * Validate a single plugin object.
+ * Returns { valid: true } or { valid: false, errors: [...] }.
+ */
+function validatePlugin(plugin) {
+  const errors = [];
+
+  if (!plugin || typeof plugin !== 'object') {
+    return { valid: false, errors: ['Plugin must be a non-null object'] };
+  }
+
+  if (!plugin.name || typeof plugin.name !== 'string') {
+    errors.push('Plugin must have a non-empty string "name" field');
+  }
+
+  if (!plugin.checks || typeof plugin.checks !== 'object' || Array.isArray(plugin.checks)) {
+    errors.push('Plugin must have a "checks" object');
+    return { valid: false, errors };
+  }
+
+  for (const [key, check] of Object.entries(plugin.checks)) {
+    for (const field of REQUIRED_CHECK_FIELDS) {
+      if (check[field] === undefined || check[field] === null) {
+        errors.push(`Check "${key}" is missing required field "${field}"`);
+      }
+    }
+
+    if (typeof check.check !== 'function') {
+      errors.push(`Check "${key}" field "check" must be a function`);
+    }
+
+    if (check.impact && !VALID_IMPACTS.includes(check.impact)) {
+      errors.push(`Check "${key}" has invalid impact "${check.impact}". Must be one of: ${VALID_IMPACTS.join(', ')}`);
+    }
+  }
+
+  return errors.length > 0 ? { valid: false, errors } : { valid: true };
+}
+
+/**
+ * Load plugins from nerviq.config.js in the given directory.
+ * Returns an array of plugin objects, or [] if no config file exists.
+ */
+function loadPlugins(dir) {
+  const configPath = path.join(dir, 'nerviq.config.js');
+
+  if (!fs.existsSync(configPath)) {
+    return [];
+  }
+
+  let config;
+  try {
+    config = require(configPath);
+  } catch (err) {
+    console.error(`Failed to load nerviq.config.js: ${err.message}`);
+    return [];
+  }
+
+  if (!config || !Array.isArray(config.plugins)) {
+    return [];
+  }
+
+  const validPlugins = [];
+  for (const plugin of config.plugins) {
+    const result = validatePlugin(plugin);
+    if (result.valid) {
+      validPlugins.push(plugin);
+    } else {
+      console.error(`Plugin "${plugin && plugin.name || 'unknown'}" is invalid: ${result.errors.join('; ')}`);
+    }
+  }
+
+  return validPlugins;
+}
+
+/**
+ * Merge plugin checks into the existing techniques object.
+ * Plugin checks are prefixed with "plugin:" to avoid key collisions.
+ * Returns a new merged techniques object (does not mutate the original).
+ */
+function mergePluginChecks(techniques, plugins) {
+  const merged = { ...techniques };
+
+  for (const plugin of plugins) {
+    for (const [key, check] of Object.entries(plugin.checks)) {
+      const prefixedKey = `plugin:${plugin.name}:${key}`;
+      merged[prefixedKey] = {
+        ...check,
+        pluginName: plugin.name,
+        sourceUrl: check.sourceUrl || null,
+        confidence: check.confidence !== undefined ? check.confidence : 0.5,
+      };
+    }
+  }
+
+  return merged;
+}
+
+module.exports = { loadPlugins, mergePluginChecks, validatePlugin };

package/src/public-api.js

@@ -0,0 +1,173 @@
+const fs = require('fs');
+const path = require('path');
+const { audit } = require('./audit');
+const { harmonyAudit } = require('./harmony/audit');
+const { generateCatalog } = require('./catalog');
+const { compoundAudit, calculateAmplification } = require('./synergy/evidence');
+const { analyzeCompensation } = require('./synergy/compensation');
+const { discoverPatterns } = require('./synergy/patterns');
+const { rankRecommendations } = require('./synergy/ranking');
+const { generateSynergyReport } = require('./synergy/report');
+const { routeTask } = require('./synergy/routing');
+const { CodexProjectContext } = require('./codex/context');
+const { GeminiProjectContext } = require('./gemini/context');
+const { CopilotProjectContext } = require('./copilot/context');
+const { CursorProjectContext } = require('./cursor/context');
+const { WindsurfProjectContext } = require('./windsurf/context');
+const { AiderProjectContext } = require('./aider/context');
+const { OpenCodeProjectContext } = require('./opencode/context');
+
+const PLATFORM_ORDER = [
+  'claude',
+  'codex',
+  'gemini',
+  'copilot',
+  'cursor',
+  'windsurf',
+  'aider',
+  'opencode',
+];
+
+const PLATFORM_DETECTORS = {
+  claude: (dir) => exists(path.join(dir, 'CLAUDE.md')) || exists(path.join(dir, '.claude')),
+  codex: (dir) => CodexProjectContext.isCodexRepo(dir),
+  gemini: (dir) => GeminiProjectContext.isGeminiRepo(dir),
+  copilot: (dir) => CopilotProjectContext.isCopilotRepo(dir),
+  cursor: (dir) => CursorProjectContext.isCursorRepo(dir),
+  windsurf: (dir) => WindsurfProjectContext.isWindsurfRepo(dir),
+  aider: (dir) => AiderProjectContext.isAiderRepo(dir),
+  opencode: (dir) => OpenCodeProjectContext.isOpenCodeRepo(dir),
+};
+
+const IMPACT_SCORES = {
+  critical: 5,
+  high: 4,
+  medium: 3,
+  low: 2,
+};
+
+function exists(targetPath) {
+  try {
+    return fs.existsSync(targetPath);
+  } catch {
+    return false;
+  }
+}
+
+function resolveDir(dir) {
+  return path.resolve(dir || '.');
+}
+
+function detectPlatforms(dir) {
+  const resolvedDir = resolveDir(dir);
+  return PLATFORM_ORDER.filter((platform) => {
+    const detect = PLATFORM_DETECTORS[platform];
+    return typeof detect === 'function' ? detect(resolvedDir) : false;
+  });
+}
+
+function getCatalog() {
+  return generateCatalog();
+}
+
+function buildPatternHistory(dir, platformAudits) {
+  const timestamp = new Date().toISOString();
+  return Object.entries(platformAudits).map(([platform, result]) => ({
+    dir,
+    platform,
+    score: result.score,
+    findings: result.results || [],
+    timestamp,
+  }));
+}
+
+function buildRecommendationPool(platformAudits, compensation) {
+  const recommendations = [];
+
+  for (const [platform, result] of Object.entries(platformAudits)) {
+    const topActions = Array.isArray(result.topNextActions) ? result.topNextActions : [];
+    for (const action of topActions) {
+      recommendations.push({
+        key: action.key,
+        name: action.name,
+        description: action.fix,
+        impact: action.impact,
+        sourcePlatform: platform,
+        applicablePlatforms: [platform],
+        validatedOn: [platform],
+        baseScore: IMPACT_SCORES[action.impact] || 1,
+      });
+    }
+  }
+
+  for (const addition of compensation.recommendedAdditions || []) {
+    recommendations.push({
+      key: `add-${addition.platform}`,
+      name: `Add ${addition.platform}`,
+      description: `Covers ${addition.wouldCover.map((item) => item.label).join(', ')}`,
+      impact: addition.wouldCover.length >= 2 ? 'high' : 'medium',
+      sourcePlatform: addition.platform,
+      applicablePlatforms: [addition.platform],
+      validatedOn: [],
+      fillsGap: true,
+      baseScore: Math.max(2, Math.min(5, Math.round(addition.estimatedBenefit / Math.max(1, addition.wouldCover.length)))),
+    });
+  }
+
+  return recommendations;
+}
+
+async function synergyReport(dir) {
+  const resolvedDir = resolveDir(dir);
+  const activePlatforms = detectPlatforms(resolvedDir);
+  const platformAudits = {};
+  const errors = [];
+
+  for (const platform of activePlatforms) {
+    try {
+      platformAudits[platform] = await audit({
+        dir: resolvedDir,
+        platform,
+        silent: true,
+      });
+    } catch (error) {
+      errors.push({ platform, message: error.message });
+    }
+  }
+
+  const compound = compoundAudit(platformAudits);
+  const amplification = calculateAmplification(platformAudits);
+  const compensation = analyzeCompensation(activePlatforms, platformAudits);
+  const patterns = discoverPatterns(buildPatternHistory(resolvedDir, platformAudits)).patterns;
+  const recommendations = rankRecommendations(
+    buildRecommendationPool(platformAudits, compensation),
+    activePlatforms
+  );
+  const report = generateSynergyReport({
+    platformAudits,
+    activePlatforms,
+    recommendations,
+  });
+
+  return {
+    dir: resolvedDir,
+    activePlatforms,
+    platformAudits,
+    compound,
+    amplification,
+    compensation,
+    patterns,
+    recommendations,
+    errors,
+    report,
+  };
+}
+
+module.exports = {
+  audit,
+  harmonyAudit,
+  detectPlatforms,
+  getCatalog,
+  routeTask,
+  synergyReport,
+};

package/src/server.js

@@ -0,0 +1,123 @@
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { URL } = require('url');
+const { version } = require('../package.json');
+const { audit } = require('./audit');
+const { harmonyAudit } = require('./harmony/audit');
+const { getCatalog } = require('./public-api');
+
+const SUPPORTED_PLATFORMS = new Set([
+  'claude',
+  'codex',
+  'gemini',
+  'copilot',
+  'cursor',
+  'windsurf',
+  'aider',
+  'opencode',
+]);
+
+function sendJson(res, statusCode, payload) {
+  const body = JSON.stringify(payload, null, 2);
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(body),
+    'Cache-Control': 'no-store',
+  });
+  res.end(body);
+}
+
+function resolveRequestDir(baseDir, rawDir) {
+  const requested = rawDir || '.';
+  const resolved = path.isAbsolute(requested)
+    ? requested
+    : path.resolve(baseDir, requested);
+
+  if (!fs.existsSync(resolved)) {
+    const error = new Error(`Directory not found: ${resolved}`);
+    error.statusCode = 400;
+    throw error;
+  }
+
+  return resolved;
+}
+
+function normalizePlatform(rawPlatform) {
+  const platform = (rawPlatform || 'claude').toLowerCase();
+  if (!SUPPORTED_PLATFORMS.has(platform)) {
+    const error = new Error(`Unsupported platform '${rawPlatform}'.`);
+    error.statusCode = 400;
+    throw error;
+  }
+  return platform;
+}
+
+function createServer(options = {}) {
+  const baseDir = path.resolve(options.baseDir || process.cwd());
+
+  return http.createServer(async (req, res) => {
+    const requestUrl = new URL(req.url || '/', 'http://127.0.0.1');
+
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { error: 'Method not allowed' });
+      return;
+    }
+
+    try {
+      if (requestUrl.pathname === '/api/health') {
+        sendJson(res, 200, {
+          status: 'ok',
+          version,
+          checks: getCatalog().length,
+        });
+        return;
+      }
+
+      if (requestUrl.pathname === '/api/catalog') {
+        sendJson(res, 200, getCatalog());
+        return;
+      }
+
+      if (requestUrl.pathname === '/api/audit') {
+        const dir = resolveRequestDir(baseDir, requestUrl.searchParams.get('dir'));
+        const platform = normalizePlatform(requestUrl.searchParams.get('platform'));
+        const result = await audit({ dir, platform, silent: true });
+        sendJson(res, 200, result);
+        return;
+      }
+
+      if (requestUrl.pathname === '/api/harmony') {
+        const dir = resolveRequestDir(baseDir, requestUrl.searchParams.get('dir'));
+        const result = await harmonyAudit({ dir, silent: true });
+        sendJson(res, 200, result);
+        return;
+      }
+
+      sendJson(res, 404, { error: 'Not found' });
+    } catch (error) {
+      sendJson(res, error.statusCode || 500, {
+        error: error.message,
+      });
+    }
+  });
+}
+
+function startServer(options = {}) {
+  const port = options.port == null ? 3000 : Number(options.port);
+  const host = options.host || '127.0.0.1';
+  const server = createServer(options);
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve(server);
+    });
+  });
+}
+
+module.exports = {
+  createServer,
+  startServer,
+};