@nerviq/cli 1.10.0 → 1.11.0

package/src/audit.js

@@ -24,16 +24,18 @@ const { AiderProjectContext } = require('./aider/context');
 const { OPENCODE_TECHNIQUES } = require('./opencode/techniques');
 const { OpenCodeProjectContext } = require('./opencode/context');
 const { getBadgeMarkdown } = require('./badge');
-const { sendInsights, getLocalInsights } = require('./insights');
-const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
-const { getFeedbackSummary } = require('./feedback');
-const { formatSarif } = require('./formatters/sarif');
-const { formatOtelMetrics } = require('./formatters/otel');
-const { loadPlugins, mergePluginChecks } = require('./plugins');
-const { hasWorkspaceConfig, detectWorkspaceGlobs, detectWorkspaces } = require('./workspace');
-const { detectDeprecationWarnings } = require('./deprecation');
-const { version: packageVersion } = require('../package.json');
-const { t } = require('./i18n');
+const { sendInsights, getLocalInsights } = require('./insights');
+const { getRecommendationOutcomeSummary, getRecommendationAdjustment } = require('./activity');
+const { getFeedbackSummary } = require('./feedback');
+const { formatSarif } = require('./formatters/sarif');
+const { formatOtelMetrics } = require('./formatters/otel');
+const { collectAuditTerminology, formatTerminologyLines } = require('./terminology');
+const { loadPlugins, mergePluginChecks } = require('./plugins');
+const { hasWorkspaceConfig, detectWorkspaceGlobs, detectWorkspaces } = require('./workspace');
+const { detectDeprecationWarnings } = require('./deprecation');
+const { estimateTokenCount } = require('./token-estimate');
+const { version: packageVersion } = require('../package.json');
+const { t } = require('./i18n');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -64,8 +66,8 @@ function formatLocation(file, line) {
 
 const IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
 const WEIGHTS = { critical: 15, high: 10, medium: 5, low: 2 };
-const LARGE_INSTRUCTION_WARN_BYTES = 50 * 1024;
-const LARGE_INSTRUCTION_SKIP_BYTES = 1024 * 1024;
+const LARGE_INSTRUCTION_WARN_TOKENS = 12000;
+const LARGE_INSTRUCTION_SKIP_TOKENS = 240000;
 const CATEGORY_MODULES = {
   memory: 'CLAUDE.md',
   quality: 'verification',
@@ -358,9 +360,13 @@ function getAuditSpec(platform = 'claude') {
   };
 }
 
-function normalizeRelativePath(filePath) {
-  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
-}
+function normalizeRelativePath(filePath) {
+  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function formatCount(value) {
+  return Number(value || 0).toLocaleString('en-US');
+}
 
 function addPath(target, filePath) {
   if (!filePath || typeof filePath !== 'string') return;
@@ -454,25 +460,27 @@ function instructionFileCandidates(spec, ctx) {
   return [...candidates];
 }
 
-function inspectInstructionFiles(spec, ctx) {
-  const warnings = [];
-
-  for (const filePath of instructionFileCandidates(spec, ctx)) {
-    const byteCount = typeof ctx.fileSizeBytes === 'function' ? ctx.fileSizeBytes(filePath) : null;
-    if (!Number.isFinite(byteCount) || byteCount <= LARGE_INSTRUCTION_WARN_BYTES) continue;
-
-    const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(filePath) : null;
-    warnings.push({
-      file: normalizeRelativePath(filePath),
-      byteCount,
-      lineCount: typeof content === 'string' ? content.split(/\r?\n/).length : null,
-      skipped: byteCount > LARGE_INSTRUCTION_SKIP_BYTES,
-      severity: byteCount > LARGE_INSTRUCTION_SKIP_BYTES ? 'critical' : 'warning',
-      message: byteCount > LARGE_INSTRUCTION_SKIP_BYTES
-        ? 'Instruction file exceeds 1MB and will be skipped during audit.'
-        : 'Instruction file exceeds 50KB. Audit will continue, but this file may reduce runtime clarity.',
-    });
-  }
+function inspectInstructionFiles(spec, ctx) {
+  const warnings = [];
+
+  for (const filePath of instructionFileCandidates(spec, ctx)) {
+    const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(filePath) : null;
+    const byteCount = typeof ctx.fileSizeBytes === 'function' ? ctx.fileSizeBytes(filePath) : null;
+    const tokenCount = typeof content === 'string' ? estimateTokenCount(content) : null;
+    if (!Number.isFinite(tokenCount) || tokenCount <= LARGE_INSTRUCTION_WARN_TOKENS) continue;
+
+    warnings.push({
+      file: normalizeRelativePath(filePath),
+      byteCount,
+      tokenCount,
+      lineCount: typeof content === 'string' ? content.split(/\r?\n/).length : null,
+      skipped: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS,
+      severity: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS ? 'critical' : 'warning',
+      message: tokenCount > LARGE_INSTRUCTION_SKIP_TOKENS
+        ? 'Instruction file exceeds ~240,000 tokens and will be skipped during audit.'
+        : 'Instruction file exceeds ~12,000 tokens. Audit will continue, but this file may reduce runtime clarity.',
+    });
+  }
 
   return warnings;
 }
@@ -921,11 +929,11 @@ function printLiteAudit(result, dir) {
       console.log(colorize(`     - ${item.title}: ${item.message}`, 'dim'));
     });
   }
-  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
-    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
-      console.log(colorize(`  Large file: ${item.file} (${Math.round(item.byteCount / 1024)}KB)`, 'yellow'));
-    });
-  }
+  if (result.largeInstructionFiles && result.largeInstructionFiles.length > 0) {
+    result.largeInstructionFiles.slice(0, 2).forEach((item) => {
+      console.log(colorize(`  Large file: ${item.file} (~${formatCount(item.tokenCount)} tokens)`, 'yellow'));
+    });
+  }
   console.log('');
 
   if (result.failed === 0) {
@@ -957,15 +965,23 @@ function printLiteAudit(result, dir) {
   console.log('');
   let usagePatterns;
   try { usagePatterns = require('./usage-patterns'); } catch { usagePatterns = null; }
-  result.liteSummary.topNextActions.forEach((item, index) => {
-    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
-    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
-    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
-    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
-    console.log(colorize(`     ${item.fix}`, 'dim'));
-  });
-  console.log('');
-  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
+  result.liteSummary.topNextActions.forEach((item, index) => {
+    const tier = item.impact === 'critical' ? '🔴' : item.impact === 'high' ? '🟡' : '🔵';
+    const suppressed = usagePatterns && usagePatterns.getPriorityAdjustment(dir, item.key) === 'suppress';
+    const suffix = suppressed ? colorize(' (suppressed)', 'dim') : '';
+    console.log(`  ${index + 1}. ${tier} ${colorize(item.name, 'bold')}${suffix}`);
+    console.log(colorize(`     ${item.fix}`, 'dim'));
+  });
+  console.log('');
+  const liteTerminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (liteTerminology.length > 0) {
+    liteTerminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
   if (result.platform === 'codex') {
     console.log(colorize('  Note: Codex now supports no-write advisory flows via augment and suggest-only before setup/apply.', 'dim'));
   }
@@ -1054,12 +1070,12 @@ async function audit(options) {
       key: 'largeInstructionFile',
       id: null,
       name: 'Large instruction file warning',
-      category: 'performance',
-      impact: 'medium',
-      rating: null,
-      fix: 'Split oversized instruction files so they stay under 50KB, and keep any single instruction file below 1MB.',
-      sourceUrl: null,
-      confidence: 'high',
+      category: 'performance',
+      impact: 'medium',
+      rating: null,
+      fix: 'Split oversized instruction files so they stay under ~12,000 tokens, and keep any single instruction file below ~240,000 tokens.',
+      sourceUrl: null,
+      confidence: 'high',
       file: largeInstructionFiles[0].file,
       line: null,
       passed: null,
@@ -1127,12 +1143,13 @@ async function audit(options) {
     ...largeInstructionFiles.map((item) => ({
       kind: 'large-instruction-file',
       severity: item.severity,
-      message: item.message,
-      file: item.file,
-      lineCount: item.lineCount,
-      byteCount: item.byteCount,
-      skipped: item.skipped,
-    })),
+      message: item.message,
+      file: item.file,
+      lineCount: item.lineCount,
+      byteCount: item.byteCount,
+      tokenCount: item.tokenCount,
+      skipped: item.skipped,
+    })),
     ...deprecationWarnings.map((item) => ({
       kind: 'deprecated-feature',
       severity: 'warning',
@@ -1260,13 +1277,13 @@ async function audit(options) {
     console.log('');
   }
 
-  if (largeInstructionFiles.length > 0) {
-    console.log(colorize('  Large instruction files', 'yellow'));
-    for (const item of largeInstructionFiles) {
-      const sizeKb = Math.round(item.byteCount / 1024);
-      console.log(colorize(`     ${item.file} (${sizeKb}KB, ${item.lineCount || '?'} lines)`, 'bold'));
-      console.log(colorize(`     → ${item.message}`, 'dim'));
-    }
+  if (largeInstructionFiles.length > 0) {
+    console.log(colorize('  Large instruction files', 'yellow'));
+    for (const item of largeInstructionFiles) {
+      const sizeKb = Number.isFinite(item.byteCount) ? Math.round(item.byteCount / 1024) : '?';
+      console.log(colorize(`     ${item.file} (~${formatCount(item.tokenCount)} tokens, ${item.lineCount || '?'} lines, ${sizeKb}KB)`, 'bold'));
+      console.log(colorize(`     → ${item.message}`, 'dim'));
+    }
     console.log('');
   }
 
@@ -1366,8 +1383,8 @@ async function audit(options) {
   }
 
   // Top next actions
-  if (topNextActions.length > 0) {
-    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
+  if (topNextActions.length > 0) {
+    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
     for (let i = 0; i < topNextActions.length; i++) {
       const item = topNextActions[i];
       console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}`);
@@ -1383,11 +1400,20 @@ async function audit(options) {
         console.log(colorize(`        Feedback: accepted ${item.feedback.accepted}, rejected ${item.feedback.rejected}, positive ${item.feedback.positive}, negative ${item.feedback.negative}${avgDelta}`, 'dim'));
       }
       console.log(colorize(`        Fix: ${item.fix}`, 'dim'));
-    }
-    console.log('');
-  }
-
-  // Summary
+    }
+    console.log('');
+  }
+
+  const terminology = formatTerminologyLines(collectAuditTerminology(result));
+  if (terminology.length > 0) {
+    terminology.forEach((line) => {
+      const color = line.startsWith('  Terms used here:') ? 'blue' : 'dim';
+      console.log(colorize(line, color));
+    });
+    console.log('');
+  }
+
+  // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
   const deprecatedNote = deprecated.length > 0 ? colorize(`, ${deprecated.length} deprecated`, 'dim') : '';
   console.log(`  ${colorize(`${passed.length}/${applicable.length}`, 'bold')} checks passing${skipped.length > 0 ? colorize(` (${skipped.length} not applicable${deprecatedNote})`, 'dim') : (deprecatedNote ? colorize(` (${deprecatedNote})`, 'dim') : '')}`);

package/src/benchmark.js

@@ -2,11 +2,12 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const { version } = require('../package.json');
-const { audit } = require('./audit');
-const { setup } = require('./setup');
-const { analyzeProject } = require('./analyze');
-const { getGovernanceSummary } = require('./governance');
+const { version } = require('../package.json');
+const { audit } = require('./audit');
+const { setup } = require('./setup');
+const { analyzeProject } = require('./analyze');
+const { getGovernanceSummary } = require('./governance');
+const { formatTerminologyLines } = require('./terminology');
 
 function copyProject(sourceDir, targetDir) {
   fs.mkdirSync(targetDir, { recursive: true });
@@ -340,11 +341,15 @@ function printBenchmark(report, options = {}) {
   console.log(`  Baseline live audit:      organic ${report.before.organicScore}/100, total ${report.before.score}/100`);
   console.log(`  Projected after setup:    organic ${report.after.organicScore}/100, total ${report.after.score}/100`);
   console.log('');
-  console.log(`  ${report.executiveSummary.headline}`);
-  console.log(`  Recommendation: ${report.executiveSummary.decisionGuidance}`);
-  console.log(`  Workflow evidence: ${report.workflowEvidence.summary.passed}/${report.workflowEvidence.summary.total} tasks (${report.workflowEvidence.summary.coverageScore}%)`);
-  console.log('');
-}
+  console.log(`  ${report.executiveSummary.headline}`);
+  console.log(`  Recommendation: ${report.executiveSummary.decisionGuidance}`);
+  console.log(`  Workflow evidence: ${report.workflowEvidence.summary.passed}/${report.workflowEvidence.summary.total} tasks (${report.workflowEvidence.summary.coverageScore}%)`);
+  console.log('');
+  for (const line of formatTerminologyLines(['governance', 'hooks', 'mcp'])) {
+    console.log(line);
+  }
+  console.log('');
+}
 
 function writeBenchmarkReport(report, outFile) {
   fs.mkdirSync(path.dirname(outFile), { recursive: true });

package/src/governance.js

@@ -1,6 +1,7 @@
-const { DOMAIN_PACKS } = require('./domain-packs');
-const { MCP_PACKS, mergeMcpServers, normalizeMcpPackKeys } = require('./mcp-packs');
-const { getCodexGovernanceSummary } = require('./codex/governance');
+const { DOMAIN_PACKS } = require('./domain-packs');
+const { MCP_PACKS, mergeMcpServers, normalizeMcpPackKeys } = require('./mcp-packs');
+const { getCodexGovernanceSummary } = require('./codex/governance');
+const { formatTerminologyLines } = require('./terminology');
 
 const PERMISSION_PROFILES = [
   {
@@ -406,10 +407,15 @@ function printGovernanceSummary(summary, options = {}) {
   console.log('');
   console.log(`  nerviq ${summary.platformLabel.toLowerCase()} governance`);
   console.log('  ═══════════════════════════════════════');
-  console.log(`  Safe defaults, hook transparency, and pilot guidance for ${summary.platformLabel}.`);
-  console.log('');
-
-  console.log('  Permission Profiles');
+  console.log(`  Safe defaults, hook transparency, and pilot guidance for ${summary.platformLabel}.`);
+  console.log('');
+
+  for (const line of formatTerminologyLines(['governance', 'hooks', 'denyRules', 'mcp'])) {
+    console.log(line);
+  }
+  console.log('');
+
+  console.log('  Permission Profiles');
   for (const profile of summary.permissionProfiles) {
     console.log(`  - ${profile.label} [${profile.risk}]`);
     console.log(`    ${profile.useWhen}`);

package/src/index.js

@@ -88,7 +88,7 @@ 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');
+const { buildServeOpenApiSpec, createServer, startServer } = require('./server');
 
 module.exports = {
   audit,
@@ -101,6 +101,7 @@ module.exports = {
   detectPlatforms,
   getCatalog,
   synergyReport,
+  buildServeOpenApiSpec,
   createServer,
   startServer,
   DOMAIN_PACKS,

package/src/integrations.js

@@ -10,66 +10,113 @@
 
 'use strict';
 
-const https = require('https');
-const http = require('http');
-const { URL } = require('url');
-
-// ─── Webhook delivery ────────────────────────────────────────────────────────
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function sendWebhookOnce(parsed, body, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const customHeaders = opts.headers || {};
+    const headers = {
+      'User-Agent': `nerviq/${require('../package.json').version}`,
+      ...customHeaders,
+      'Content-Length': Buffer.byteLength(body),
+    };
+
+    const hasContentTypeHeader = Object.keys(headers).some((name) => name.toLowerCase() === 'content-type');
+    if (!hasContentTypeHeader) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    const options = {
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path: parsed.pathname + (parsed.search || ''),
+      method: 'POST',
+      headers,
+    };
+
+    const transport = parsed.protocol === 'https:' ? https : http;
+
+    const req = transport.request(options, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const respBody = Buffer.concat(chunks).toString('utf8');
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, body: respBody });
+      });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`Webhook request timed out after ${timeoutMs}ms`));
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ─── Webhook delivery ────────────────────────────────────────────────────────
 
 /**
  * POST JSON payload to a webhook URL.
  * @param {string} url  - Destination URL (http or https)
  * @param {object} payload - JSON-serialisable object
- * @param {object} [opts]
- * @param {number} [opts.timeoutMs=10000]
- * @param {object} [opts.headers]
- * @returns {Promise<{ ok: boolean, status: number, body: string }>}
- */
-function sendWebhook(url, payload, opts = {}) {
-  return new Promise((resolve, reject) => {
-    let parsed;
-    try {
-      parsed = new URL(url);
-    } catch {
-      return reject(new Error(`Invalid webhook URL: ${url}`));
-    }
-
-    const body = JSON.stringify(payload);
-    const timeoutMs = opts.timeoutMs ?? 10_000;
-
-    const options = {
-      hostname: parsed.hostname,
-      port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
-      path: parsed.pathname + (parsed.search || ''),
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(body),
-        'User-Agent': `nerviq/${require('../package.json').version}`,
-        ...(opts.headers || {}),
-      },
-    };
-
-    const transport = parsed.protocol === 'https:' ? https : http;
-
-    const req = transport.request(options, (res) => {
-      const chunks = [];
-      res.on('data', (c) => chunks.push(c));
-      res.on('end', () => {
-        const respBody = Buffer.concat(chunks).toString('utf8');
-        resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, body: respBody });
-      });
-    });
-
-    req.setTimeout(timeoutMs, () => {
-      req.destroy(new Error(`Webhook request timed out after ${timeoutMs}ms`));
-    });
-
-    req.on('error', reject);
-    req.write(body);
-    req.end();
-  });
-}
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=10000]
+ * @param {object} [opts.headers]
+ * @param {number} [opts.retries=2]
+ * @param {number} [opts.retryDelayMs=400]
+ * @returns {Promise<{ ok: boolean, status: number, body: string, attempts: number }>}
+ */
+async function sendWebhook(url, payload, opts = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid webhook URL: ${url}`);
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`Unsupported webhook protocol: ${parsed.protocol}`);
+  }
+
+  const body = JSON.stringify(payload);
+  const retries = Number.isInteger(opts.retries) && opts.retries >= 0 ? opts.retries : 2;
+  const retryDelayMs = Number.isFinite(opts.retryDelayMs) && opts.retryDelayMs >= 0 ? opts.retryDelayMs : 400;
+  const maxAttempts = retries + 1;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const response = await sendWebhookOnce(parsed, body, opts);
+      const enriched = { ...response, attempts: attempt };
+      const shouldRetry = RETRYABLE_STATUS_CODES.has(response.status) && attempt < maxAttempts;
+      if (!shouldRetry) {
+        return enriched;
+      }
+    } catch (error) {
+      error.attempts = attempt;
+      if (attempt >= maxAttempts) {
+        throw error;
+      }
+    }
+
+    const delayMs = retryDelayMs * attempt;
+    if (delayMs > 0) {
+      await wait(delayMs);
+    }
+  }
+
+  return { ok: false, status: 0, body: '', attempts: maxAttempts };
+}
 
 // ─── Slack formatting ─────────────────────────────────────────────────────────