@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/src/harmony/advisor.js

@@ -0,0 +1,383 @@
+/**
+ * H5. Strategic Project Advisor
+ *
+ * The strategic brain that understands a project holistically and recommends
+ * which platform to use for which task type, configuration improvements,
+ * and cross-platform update actions.
+ *
+ * Zero external dependencies - imports only from sibling/parent modules.
+ */
+
+// ─── Platform Strength Matrix (from CLAUDEX research) ─────────────────────────
+
+const PLATFORM_STRENGTHS = {
+  claude: {
+    label: 'Claude Code',
+    reasoning: 5,
+    refactoring: 5,
+    ci: 2,
+    ide: 2,
+    sandbox: 3,
+    inline: 3,
+    context: 4,
+    automation: 4,
+  },
+  codex: {
+    label: 'Codex',
+    reasoning: 4,
+    ci: 5,
+    cloud: 5,
+    ide: 3,
+    sandbox: 4,
+    refactoring: 4,
+    inline: 2,
+    context: 3,
+    automation: 4,
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    reasoning: 4,
+    context: 5,
+    sandbox: 5,
+    ci: 3,
+    ide: 3,
+    refactoring: 3,
+    inline: 2,
+    cloud: 4,
+    automation: 3,
+  },
+  copilot: {
+    label: 'GitHub Copilot',
+    inline: 5,
+    'cloud-agent': 4,
+    ide: 4,
+    ci: 4,
+    governance: 3,
+    reasoning: 3,
+    refactoring: 3,
+    context: 3,
+    automation: 3,
+  },
+  cursor: {
+    label: 'Cursor',
+    ide: 5,
+    ui: 5,
+    background: 4,
+    automation: 4,
+    reasoning: 3,
+    refactoring: 3,
+    inline: 4,
+    context: 3,
+    ci: 2,
+  },
+};
+
+// ─── Task-type to platform-strength mapping ───────────────────────────────────
+
+const TASK_TYPE_PROFILES = {
+  'bug-fix': {
+    label: 'Bug Fixing',
+    requiredStrengths: { reasoning: 0.5, refactoring: 0.3, context: 0.2 },
+    description: 'Deep reasoning and code understanding for root cause analysis.',
+  },
+  'ci-review': {
+    label: 'CI / Async Review',
+    requiredStrengths: { ci: 0.5, cloud: 0.3, automation: 0.2 },
+    description: 'Asynchronous code review and CI-integrated workflows.',
+  },
+  'ui-work': {
+    label: 'UI Development',
+    requiredStrengths: { ide: 0.4, ui: 0.3, inline: 0.3 },
+    description: 'Interactive UI work with live preview and visual feedback.',
+  },
+  'quick-edit': {
+    label: 'Quick Edits',
+    requiredStrengths: { inline: 0.5, ide: 0.3, automation: 0.2 },
+    description: 'Small, fast inline edits and completions.',
+  },
+  'infrastructure': {
+    label: 'Infrastructure',
+    requiredStrengths: { sandbox: 0.4, cloud: 0.3, reasoning: 0.3 },
+    description: 'Infrastructure, DevOps, and sandbox-heavy workflows.',
+  },
+  'refactoring': {
+    label: 'Large Refactoring',
+    requiredStrengths: { refactoring: 0.4, reasoning: 0.3, context: 0.3 },
+    description: 'Cross-file refactoring with deep codebase understanding.',
+  },
+  'code-review': {
+    label: 'Code Review',
+    requiredStrengths: { reasoning: 0.4, governance: 0.3, ci: 0.3 },
+    description: 'Thorough review with governance and standards enforcement.',
+  },
+  'greenfield': {
+    label: 'Greenfield / Scaffolding',
+    requiredStrengths: { reasoning: 0.3, automation: 0.3, ide: 0.2, refactoring: 0.2 },
+    description: 'Starting new projects or major new features from scratch.',
+  },
+};
+
+// ─── Scoring ──────────────────────────────────────────────────────────────────
+
+/**
+ * Score a platform against a task type profile.
+ * Returns a 0-5 weighted score.
+ */
+function scorePlatformForTask(platformKey, taskProfile) {
+  const strengths = PLATFORM_STRENGTHS[platformKey];
+  if (!strengths) return 0;
+
+  let score = 0;
+  for (const [dimension, weight] of Object.entries(taskProfile.requiredStrengths)) {
+    const platformScore = strengths[dimension] || 0;
+    score += platformScore * weight;
+  }
+  return Math.round(score * 100) / 100;
+}
+
+/**
+ * Rank all platforms for a given task type.
+ */
+function rankPlatformsForTask(taskType) {
+  const profile = TASK_TYPE_PROFILES[taskType];
+  if (!profile) return [];
+
+  const rankings = Object.keys(PLATFORM_STRENGTHS).map(platformKey => ({
+    platform: platformKey,
+    label: PLATFORM_STRENGTHS[platformKey].label,
+    score: scorePlatformForTask(platformKey, profile),
+  }));
+
+  rankings.sort((a, b) => b.score - a.score);
+  return rankings;
+}
+
+/**
+ * Compute a confidence level from the score gap between #1 and #2.
+ */
+function computeConfidence(rankings) {
+  if (rankings.length < 2) return 'high';
+  const gap = rankings[0].score - rankings[1].score;
+  if (gap >= 1.0) return 'high';
+  if (gap >= 0.4) return 'medium';
+  return 'low';
+}
+
+// ─── Task Routing ─────────────────────────────────────────────────────────────
+
+/**
+ * Generate task routing recommendations for all known task types.
+ * Optionally filter to only platforms present in platformAudits.
+ */
+function generateTaskRouting(platformAudits) {
+  const availablePlatforms = platformAudits
+    ? new Set(platformAudits.map(a => a.platform))
+    : null;
+
+  const routing = [];
+
+  for (const [taskType, profile] of Object.entries(TASK_TYPE_PROFILES)) {
+    let rankings = rankPlatformsForTask(taskType);
+
+    if (availablePlatforms) {
+      rankings = rankings.filter(r => availablePlatforms.has(r.platform));
+    }
+
+    if (rankings.length === 0) continue;
+
+    const best = rankings[0];
+    routing.push({
+      taskType,
+      taskLabel: profile.label,
+      recommendedPlatform: best.platform,
+      recommendedLabel: best.label,
+      score: best.score,
+      confidence: computeConfidence(rankings),
+      reasoning: profile.description,
+      alternatives: rankings.slice(1, 3).map(r => ({
+        platform: r.platform,
+        label: r.label,
+        score: r.score,
+      })),
+    });
+  }
+
+  return routing;
+}
+
+// ─── Config Recommendations ───────────────────────────────────────────────────
+
+/**
+ * Detect configuration improvement opportunities from platform audits.
+ */
+function generateConfigRecommendations(canonicalModel, platformAudits) {
+  const recommendations = [];
+
+  if (!platformAudits || platformAudits.length === 0) return recommendations;
+
+  for (const auditResult of platformAudits) {
+    const platform = auditResult.platform;
+    const score = auditResult.score || 0;
+
+    // Low score platforms need attention
+    if (score < 40) {
+      recommendations.push({
+        platform,
+        recommendation: `Platform "${platform}" scores ${score}/100. Run setup to bootstrap baseline configuration.`,
+        impact: 'high',
+        category: 'bootstrap',
+      });
+    }
+
+    // Missing canonical sections
+    if (canonicalModel && canonicalModel.sections) {
+      const auditSections = new Set((auditResult.sections || []).map(s => s.key || s));
+      for (const section of canonicalModel.sections) {
+        if (!auditSections.has(section.key)) {
+          recommendations.push({
+            platform,
+            recommendation: `Missing canonical section "${section.key}" (${section.label || section.key}). Add to align with cross-platform standard.`,
+            impact: 'medium',
+            category: 'alignment',
+          });
+        }
+      }
+    }
+
+    // Permission/governance gaps
+    if (auditResult.governance) {
+      const gov = auditResult.governance;
+      if (!gov.hasPermissions) {
+        recommendations.push({
+          platform,
+          recommendation: 'No explicit permission configuration detected. Add permission boundaries for safer operation.',
+          impact: 'high',
+          category: 'security',
+        });
+      }
+      if (!gov.hasSecretProtection) {
+        recommendations.push({
+          platform,
+          recommendation: 'No secret protection hook found. Add protection to prevent credential exposure.',
+          impact: 'high',
+          category: 'security',
+        });
+      }
+    }
+  }
+
+  // Sort by impact
+  const impactOrder = { high: 0, medium: 1, low: 2 };
+  recommendations.sort((a, b) => (impactOrder[a.impact] || 2) - (impactOrder[b.impact] || 2));
+
+  return recommendations;
+}
+
+// ─── Cross-Platform Actions ───────────────────────────────────────────────────
+
+/**
+ * Detect when project changes need cross-platform updates.
+ * Prioritize by how many platforms are affected.
+ */
+function generateCrossPlatformActions(canonicalModel, platformAudits) {
+  const actions = [];
+
+  if (!platformAudits || platformAudits.length < 2) return actions;
+
+  const platforms = platformAudits.map(a => a.platform);
+
+  // Detect instruction drift: if one platform has instructions another lacks
+  if (canonicalModel && canonicalModel.sections) {
+    const sectionCoverage = {};
+    for (const section of canonicalModel.sections) {
+      sectionCoverage[section.key] = [];
+    }
+
+    for (const auditResult of platformAudits) {
+      for (const section of (auditResult.sections || [])) {
+        const key = section.key || section;
+        if (sectionCoverage[key]) {
+          sectionCoverage[key].push(auditResult.platform);
+        }
+      }
+    }
+
+    for (const [sectionKey, coveredPlatforms] of Object.entries(sectionCoverage)) {
+      if (coveredPlatforms.length > 0 && coveredPlatforms.length < platforms.length) {
+        const missing = platforms.filter(p => !coveredPlatforms.includes(p));
+        actions.push({
+          action: `Sync section "${sectionKey}" to missing platforms`,
+          affectedPlatforms: missing,
+          sourcePlatforms: coveredPlatforms,
+          priority: missing.length >= platforms.length / 2 ? 'high' : 'medium',
+          type: 'instruction-sync',
+        });
+      }
+    }
+  }
+
+  // Detect MCP server alignment gaps
+  const mcpByPlatform = {};
+  for (const auditResult of platformAudits) {
+    mcpByPlatform[auditResult.platform] = new Set(auditResult.mcpServers || []);
+  }
+
+  const allMcpServers = new Set();
+  for (const servers of Object.values(mcpByPlatform)) {
+    for (const s of servers) allMcpServers.add(s);
+  }
+
+  for (const server of allMcpServers) {
+    const hasPlatforms = platforms.filter(p => mcpByPlatform[p] && mcpByPlatform[p].has(server));
+    const missingPlatforms = platforms.filter(p => !mcpByPlatform[p] || !mcpByPlatform[p].has(server));
+
+    if (hasPlatforms.length > 0 && missingPlatforms.length > 0) {
+      actions.push({
+        action: `Add MCP server "${server}" to platforms that lack it`,
+        affectedPlatforms: missingPlatforms,
+        sourcePlatforms: hasPlatforms,
+        priority: missingPlatforms.length > hasPlatforms.length ? 'medium' : 'low',
+        type: 'mcp-sync',
+      });
+    }
+  }
+
+  // Sort by priority then by affected platform count
+  const priorityOrder = { high: 0, medium: 1, low: 2 };
+  actions.sort((a, b) => {
+    const pDiff = (priorityOrder[a.priority] || 2) - (priorityOrder[b.priority] || 2);
+    if (pDiff !== 0) return pDiff;
+    return b.affectedPlatforms.length - a.affectedPlatforms.length;
+  });
+
+  return actions;
+}
+
+// ─── Main Entry ───────────────────────────────────────────────────────────────
+
+/**
+ * Generate a complete strategic advice package.
+ *
+ * @param {Object|null} canonicalModel - The canonical model from canon.js
+ * @param {Array} platformAudits - Array of per-platform audit results
+ * @returns {Object} { taskRouting, configRecommendations, crossPlatformActions }
+ */
+function generateStrategicAdvice(canonicalModel, platformAudits) {
+  return {
+    taskRouting: generateTaskRouting(platformAudits),
+    configRecommendations: generateConfigRecommendations(canonicalModel, platformAudits),
+    crossPlatformActions: generateCrossPlatformActions(canonicalModel, platformAudits),
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+module.exports = {
+  generateStrategicAdvice,
+  PLATFORM_STRENGTHS,
+  TASK_TYPE_PROFILES,
+  scorePlatformForTask,
+  rankPlatformsForTask,
+  generateTaskRouting,
+  generateConfigRecommendations,
+  generateCrossPlatformActions,
+};

package/src/harmony/audit.js

@@ -0,0 +1,303 @@
+/**
+ * Harmony Audit — Cross-Platform DX Audit
+ *
+ * Runs AFTER per-platform audits and evaluates how well the project's
+ * AI coding platforms are aligned with each other.
+ *
+ * Produces a harmony score (0-100), per-platform scores, drift analysis,
+ * and cross-platform recommendations.
+ */
+
+const { buildCanonicalModel, detectActivePlatforms } = require('./canon');
+const { detectDrift, formatDriftReport } = require('./drift');
+const { audit: platformAudit } = require('../audit');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+function colorize(text, color) {
+  return `${COLORS[color] || ''}${text}${COLORS.reset}`;
+}
+
+function progressBar(score, max = 100, width = 20) {
+  const filled = Math.round((score / max) * width);
+  const empty = width - filled;
+  const color = score >= 70 ? 'green' : score >= 40 ? 'yellow' : 'red';
+  return colorize('\u2588'.repeat(filled), color) + colorize('\u2591'.repeat(empty), 'dim');
+}
+
+// ─── Platform key to audit platform name mapping ────────────────────────────
+
+const PLATFORM_AUDIT_MAP = {
+  claude: 'claude',
+  codex: 'codex',
+  gemini: 'gemini',
+  copilot: 'copilot',
+  cursor: 'cursor',
+};
+
+// ─── Cross-platform recommendations ────────────────────────────────────────
+
+function generateRecommendations(model, drift, platformScores) {
+  const recommendations = [];
+  const platforms = model.activePlatforms.map(p => p.platform);
+
+  // 1. If only one platform detected, recommend adding another
+  if (platforms.length === 1) {
+    recommendations.push({
+      priority: 'medium',
+      category: 'expansion',
+      message: `Only ${platforms[0]} is configured. Consider adding a second platform for redundancy and team flexibility.`,
+    });
+  }
+
+  // 2. If any platform scores below 40, flag it
+  for (const [platform, score] of Object.entries(platformScores)) {
+    if (score !== null && score < 40) {
+      recommendations.push({
+        priority: 'high',
+        category: 'quality',
+        message: `${platform} scores ${score}/100. Run \`nerviq audit --platform ${platform}\` and address critical gaps.`,
+      });
+    }
+  }
+
+  // 3. If trust drift is critical, recommend alignment
+  const trustDrifts = drift.drifts.filter(d => d.type === 'trust-drift' && d.severity === 'critical');
+  if (trustDrifts.length > 0) {
+    recommendations.push({
+      priority: 'critical',
+      category: 'security',
+      message: 'Critical trust posture mismatch. One platform has full autonomy while another is restricted. Align before production use.',
+    });
+  }
+
+  // 4. Recommend shared MCP servers
+  const mcpDrifts = drift.drifts.filter(d => d.type === 'mcp-drift');
+  if (mcpDrifts.length > 2) {
+    recommendations.push({
+      priority: 'medium',
+      category: 'tooling',
+      message: `${mcpDrifts.length} MCP alignment issues. Use \`nerviq harmony sync\` to propagate MCP servers across platforms.`,
+    });
+  }
+
+  // 5. Coverage gap recommendations
+  const coverageGaps = drift.drifts.filter(d => d.type === 'coverage-gap' && d.severity === 'high');
+  for (const gap of coverageGaps) {
+    recommendations.push({
+      priority: 'high',
+      category: 'coverage',
+      message: gap.description + '. ' + gap.recommendation,
+    });
+  }
+
+  // 6. If harmony score is high and all platforms score well, celebrate
+  if (drift.harmonyScore >= 90 && Object.values(platformScores).every(s => s === null || s >= 70)) {
+    recommendations.push({
+      priority: 'low',
+      category: 'status',
+      message: 'Excellent cross-platform alignment. All platforms are well-configured and consistent.',
+    });
+  }
+
+  // Sort: critical > high > medium > low
+  const priorityOrder = { critical: 3, high: 2, medium: 1, low: 0 };
+  recommendations.sort((a, b) => (priorityOrder[b.priority] || 0) - (priorityOrder[a.priority] || 0));
+
+  return recommendations;
+}
+
+// ─── Main audit function ────────────────────────────────────────────────────
+
+/**
+ * Run a cross-platform harmony audit.
+ *
+ * Builds a canonical model, runs per-platform audits, detects drift,
+ * and generates cross-platform recommendations.
+ *
+ * @param {object} options - { dir: string, silent?: boolean, verbose?: boolean }
+ * @returns {object} Harmony audit result
+ */
+async function harmonyAudit(options) {
+  const { dir, silent = false, verbose = false } = options;
+
+  // 1. Build canonical model
+  const model = buildCanonicalModel(dir);
+  const platformKeys = model.activePlatforms.map(p => p.platform);
+
+  if (platformKeys.length === 0) {
+    return {
+      harmonyScore: 0,
+      platformScores: {},
+      drift: { drifts: [], summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }, harmonyScore: 0 },
+      recommendations: [{
+        priority: 'high',
+        category: 'coverage',
+        message: 'No AI coding platforms detected. Run `nerviq init` to set up Claude, or add another platform.',
+      }],
+      activePlatforms: [],
+      model,
+    };
+  }
+
+  // 2. Run per-platform audits (silent mode to avoid console noise)
+  const platformScores = {};
+  const platformResults = {};
+  for (const key of platformKeys) {
+    const auditPlatform = PLATFORM_AUDIT_MAP[key];
+    if (auditPlatform) {
+      try {
+        const result = await platformAudit({ dir, platform: auditPlatform, silent: true });
+        platformScores[key] = result.score;
+        platformResults[key] = result;
+      } catch {
+        platformScores[key] = null;
+        platformResults[key] = null;
+      }
+    } else {
+      platformScores[key] = null;
+    }
+  }
+
+  // 3. Detect drift
+  const drift = detectDrift(model);
+
+  // 4. Calculate overall harmony score
+  // Blend of drift harmony score and average platform scores
+  const validScores = Object.values(platformScores).filter(s => s !== null);
+  const avgPlatformScore = validScores.length > 0
+    ? Math.round(validScores.reduce((a, b) => a + b, 0) / validScores.length)
+    : 0;
+
+  // Harmony = 60% drift alignment + 40% average platform quality
+  const harmonyScore = Math.round(drift.harmonyScore * 0.6 + avgPlatformScore * 0.4);
+
+  // 5. Generate recommendations
+  const recommendations = generateRecommendations(model, drift, platformScores);
+
+  const result = {
+    harmonyScore,
+    platformScores,
+    platformResults,
+    drift,
+    recommendations,
+    activePlatforms: model.activePlatforms,
+    model,
+  };
+
+  // 6. Print report if not silent
+  if (!silent) {
+    printHarmonyReport(result, { verbose });
+  }
+
+  return result;
+}
+
+// ─── Report printer ─────────────────────────────────────────────────────────
+
+function printHarmonyReport(result, options = {}) {
+  const { verbose = false } = options;
+  const c = colorize;
+
+  console.log('');
+  console.log(c('  ══════════════════════════════════════════════════════', 'dim'));
+  console.log(c('  HARMONY AUDIT — Cross-Platform DX Report', 'bold'));
+  console.log(c('  ══════════════════════════════════════════════════════', 'dim'));
+  console.log('');
+
+  // Active platforms
+  console.log(c('  Active platforms:', 'bold'));
+  for (const ap of result.activePlatforms) {
+    const score = result.platformScores[ap.platform];
+    const scoreStr = score !== null ? `${score}/100` : 'n/a';
+    const scoreColor = score >= 70 ? 'green' : score >= 40 ? 'yellow' : 'red';
+    console.log(`    ${ap.label}: ${c(scoreStr, score !== null ? scoreColor : 'dim')}`);
+  }
+  console.log('');
+
+  // Harmony score
+  const hs = result.harmonyScore;
+  const hsColor = hs >= 80 ? 'green' : hs >= 50 ? 'yellow' : 'red';
+  console.log(`  Harmony Score: ${progressBar(hs)} ${c(hs + '/100', hsColor)}`);
+  console.log('');
+
+  // Drift summary
+  if (result.drift.drifts.length > 0) {
+    console.log(formatDriftReport(result.drift, { color: true, verbose }));
+  } else {
+    console.log(c('  No cross-platform drift detected.', 'green'));
+    console.log('');
+  }
+
+  // Recommendations
+  if (result.recommendations.length > 0) {
+    console.log(c('  Recommendations:', 'bold'));
+    const priorityIcons = { critical: '\u2718', high: '!', medium: '~', low: '\u2713' };
+    const priorityColors = { critical: 'red', high: 'yellow', medium: 'blue', low: 'green' };
+
+    for (const rec of result.recommendations) {
+      const icon = priorityIcons[rec.priority] || '-';
+      const pColor = priorityColors[rec.priority] || 'dim';
+      console.log(`  ${c(icon, pColor)} [${rec.category}] ${rec.message}`);
+    }
+    console.log('');
+  }
+
+  console.log(c('  Powered by CLAUDEX cross-platform intelligence', 'dim'));
+  console.log(c('  https://github.com/nerviq/nerviq', 'dim'));
+  console.log('');
+}
+
+/**
+ * Format the harmony audit result as a structured report string (no ANSI colors).
+ *
+ * @param {object} result - Output of harmonyAudit()
+ * @returns {string} Plain-text report
+ */
+function formatHarmonyAuditReport(result) {
+  const lines = [];
+
+  lines.push('HARMONY AUDIT — Cross-Platform DX Report');
+  lines.push('========================================');
+  lines.push('');
+
+  lines.push('Active platforms:');
+  for (const ap of result.activePlatforms) {
+    const score = result.platformScores[ap.platform];
+    lines.push(`  ${ap.label}: ${score !== null ? score + '/100' : 'n/a'}`);
+  }
+  lines.push('');
+
+  lines.push(`Harmony Score: ${result.harmonyScore}/100`);
+  lines.push('');
+
+  if (result.drift.drifts.length > 0) {
+    lines.push(formatDriftReport(result.drift, { color: false, verbose: true }));
+  } else {
+    lines.push('No cross-platform drift detected.');
+  }
+  lines.push('');
+
+  if (result.recommendations.length > 0) {
+    lines.push('Recommendations:');
+    for (const rec of result.recommendations) {
+      lines.push(`  [${rec.priority.toUpperCase()}] [${rec.category}] ${rec.message}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  harmonyAudit,
+  formatHarmonyAuditReport,
+};