@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/src/activity.js

@@ -0,0 +1,529 @@
+const fs = require('fs');
+const path = require('path');
+const { version } = require('../package.json');
+
+let _lastTimestamp = '';
+let _counter = 0;
+
+function timestampId() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  if (ts === _lastTimestamp) {
+    _counter++;
+    return `${ts}-${_counter}`;
+  }
+  _lastTimestamp = ts;
+  _counter = 0;
+  return ts;
+}
+
+function ensureArtifactDirs(dir) {
+  const root = path.join(dir, '.claude', 'claudex-setup');
+  const activityDir = path.join(root, 'activity');
+  const rollbackDir = path.join(root, 'rollbacks');
+  const snapshotDir = path.join(root, 'snapshots');
+  const outcomesDir = path.join(root, 'outcomes');
+  fs.mkdirSync(activityDir, { recursive: true });
+  fs.mkdirSync(rollbackDir, { recursive: true });
+  fs.mkdirSync(snapshotDir, { recursive: true });
+  fs.mkdirSync(outcomesDir, { recursive: true });
+  return { root, activityDir, rollbackDir, snapshotDir, outcomesDir };
+}
+
+function writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf8');
+}
+
+function writeActivityArtifact(dir, type, payload) {
+  const id = timestampId();
+  const { activityDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(activityDir, `${id}-${type}.json`);
+  writeJson(filePath, {
+    id,
+    type,
+    createdAt: new Date().toISOString(),
+    ...payload,
+  });
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+  };
+}
+
+function writeRollbackArtifact(dir, payload) {
+  const id = timestampId();
+  const { rollbackDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(rollbackDir, `${id}.json`);
+  writeJson(filePath, {
+    id,
+    createdAt: new Date().toISOString(),
+    rollbackType: 'delete-created-files',
+    ...payload,
+  });
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+  };
+}
+
+function summarizeSnapshot(snapshotKind, payload) {
+  if (snapshotKind === 'audit') {
+    return {
+      score: payload.score,
+      organicScore: payload.organicScore,
+      passed: payload.passed,
+      failed: payload.failed,
+      checkCount: payload.checkCount,
+      suggestedNextCommand: payload.suggestedNextCommand,
+      topActionKeys: Array.isArray(payload.topNextActions)
+        ? payload.topNextActions.slice(0, 3).map(item => item.key)
+        : [],
+    };
+  }
+
+  if (snapshotKind === 'augment' || snapshotKind === 'suggest-only') {
+    return {
+      score: payload.projectSummary?.score,
+      organicScore: payload.projectSummary?.organicScore,
+      maturity: payload.projectSummary?.maturity,
+      domains: payload.projectSummary?.domains || [],
+      topActionKeys: Array.isArray(payload.topNextActions)
+        ? payload.topNextActions.slice(0, 3).map(item => item.key)
+        : [],
+    };
+  }
+
+  if (snapshotKind === 'benchmark') {
+    return {
+      beforeScore: payload.before?.score,
+      afterScore: payload.after?.score,
+      scoreDelta: payload.delta?.score,
+      organicDelta: payload.delta?.organicScore,
+      decisionGuidance: payload.executiveSummary?.decisionGuidance || null,
+    };
+  }
+
+  if (snapshotKind === 'governance') {
+    return {
+      permissionProfiles: Array.isArray(payload.permissionProfiles) ? payload.permissionProfiles.length : 0,
+      hooks: Array.isArray(payload.hookRegistry) ? payload.hookRegistry.length : 0,
+      policyPacks: Array.isArray(payload.policyPacks) ? payload.policyPacks.length : 0,
+      domainPacks: Array.isArray(payload.domainPacks) ? payload.domainPacks.length : 0,
+      mcpPacks: Array.isArray(payload.mcpPacks) ? payload.mcpPacks.length : 0,
+    };
+  }
+
+  return {};
+}
+
+function updateSnapshotIndex(snapshotDir, record) {
+  const indexPath = path.join(snapshotDir, 'index.json');
+  let entries = [];
+
+  if (fs.existsSync(indexPath)) {
+    try {
+      entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+      if (!Array.isArray(entries)) {
+        entries = [];
+      }
+    } catch {
+      entries = [];
+    }
+  }
+
+  entries.push(record);
+  // Prune to keep last 200 entries
+  const MAX_INDEX_ENTRIES = 200;
+  if (entries.length > MAX_INDEX_ENTRIES) {
+    entries = entries.slice(entries.length - MAX_INDEX_ENTRIES);
+  }
+  fs.writeFileSync(indexPath, JSON.stringify(entries, null, 2), 'utf8');
+}
+
+/**
+ * Write a normalized snapshot artifact to .claude/claudex-setup/snapshots/ and update the index.
+ * @param {string} dir - Project root directory.
+ * @param {string} snapshotKind - Snapshot type ('audit', 'benchmark', 'governance', 'augment', 'suggest-only').
+ * @param {Object} payload - Full result payload to persist.
+ * @param {Object} [meta={}] - Optional metadata fields merged into the envelope.
+ * @returns {Object} Artifact record with id, filePath, relativePath, indexPath, and summary.
+ */
+function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
+  const id = timestampId();
+  const { snapshotDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(snapshotDir, `${id}-${snapshotKind}.json`);
+  const summary = summarizeSnapshot(snapshotKind, payload);
+  const envelope = {
+    schemaVersion: 1,
+    artifactType: 'snapshot',
+    snapshotKind,
+    id,
+    createdAt: new Date().toISOString(),
+    generatedBy: `nerviq@${version}`,
+    directory: dir,
+    summary,
+    ...meta,
+    payload,
+  };
+
+  writeJson(filePath, envelope);
+
+  const record = {
+    id,
+    snapshotKind,
+    createdAt: envelope.createdAt,
+    relativePath: path.relative(dir, filePath),
+    summary,
+  };
+  updateSnapshotIndex(snapshotDir, record);
+
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+    indexPath: path.relative(dir, path.join(snapshotDir, 'index.json')),
+    summary,
+  };
+}
+
+function readSnapshotIndex(dir) {
+  const indexPath = path.join(dir, '.claude', 'claudex-setup', 'snapshots', 'index.json');
+  if (!fs.existsSync(indexPath)) return [];
+  try {
+    const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get the audit score history from saved snapshots, most recent first.
+ * @param {string} dir - Project root directory.
+ * @param {number} [limit=20] - Maximum number of entries to return.
+ * @returns {Object[]} Array of snapshot index entries for audit snapshots.
+ */
+function getHistory(dir, limit = 20) {
+  const entries = readSnapshotIndex(dir);
+  return entries
+    .filter(e => e.snapshotKind === 'audit')
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit);
+}
+
+/**
+ * Compare the two most recent audit snapshots and return the delta.
+ * @param {string} dir - Project root directory.
+ * @returns {Object|null} Comparison with current/previous scores, delta, regressions, improvements, and trend. Null if fewer than 2 snapshots.
+ */
+function compareLatest(dir) {
+  const audits = getHistory(dir, 2);
+  if (audits.length < 2) return null;
+
+  const current = audits[0];
+  const previous = audits[1];
+
+  const delta = {
+    score: (current.summary?.score || 0) - (previous.summary?.score || 0),
+    organic: (current.summary?.organicScore || 0) - (previous.summary?.organicScore || 0),
+    passed: (current.summary?.passed || 0) - (previous.summary?.passed || 0),
+  };
+
+  const regressions = [];
+  const improvements = [];
+
+  const prevKeys = new Set(previous.summary?.topActionKeys || []);
+  const currKeys = new Set(current.summary?.topActionKeys || []);
+
+  for (const key of currKeys) {
+    if (!prevKeys.has(key)) regressions.push(key);
+  }
+  for (const key of prevKeys) {
+    if (!currKeys.has(key)) improvements.push(key);
+  }
+
+  return {
+    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed },
+    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed },
+    delta,
+    regressions,
+    improvements,
+    trend: delta.score > 0 ? 'improving' : delta.score < 0 ? 'regressing' : 'stable',
+  };
+}
+
+function formatHistory(dir) {
+  const history = getHistory(dir, 10);
+  if (history.length === 0) return 'No snapshots found. Run `npx nerviq --snapshot` to save one.';
+
+  const lines = ['Score history (most recent first):', ''];
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || 'unknown';
+    const score = entry.summary?.score ?? '?';
+    const passed = entry.summary?.passed ?? '?';
+    const total = entry.summary?.checkCount ?? '?';
+    lines.push(`  ${date}  ${score}/100  (${passed}/${total} passing)`);
+  }
+
+  const comparison = compareLatest(dir);
+  if (comparison) {
+    lines.push('');
+    const sign = comparison.delta.score >= 0 ? '+' : '';
+    lines.push(`  Trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous)`);
+    if (comparison.improvements.length > 0) {
+      lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
+    }
+    if (comparison.regressions.length > 0) {
+      lines.push(`  New gaps: ${comparison.regressions.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function exportTrendReport(dir) {
+  const history = getHistory(dir, 50);
+  if (history.length === 0) return null;
+
+  const comparison = compareLatest(dir);
+  const lines = [
+    '# Claude Code Setup Trend Report',
+    '',
+    `**Project:** ${path.basename(dir)}`,
+    `**Generated:** ${new Date().toISOString().split('T')[0]}`,
+    `**Snapshots:** ${history.length}`,
+    '',
+    '## Score History',
+    '',
+    '| Date | Score | Passed | Checks |',
+    '|------|-------|--------|--------|',
+  ];
+
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || '?';
+    lines.push(`| ${date} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} |`);
+  }
+
+  if (comparison) {
+    lines.push('');
+    lines.push('## Latest Comparison');
+    lines.push('');
+    lines.push(`- **Previous:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
+    lines.push(`- **Current:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
+    lines.push(`- **Delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
+    lines.push(`- **Trend:** ${comparison.trend}`);
+    if (comparison.improvements.length > 0) lines.push(`- **Fixed:** ${comparison.improvements.join(', ')}`);
+    if (comparison.regressions.length > 0) lines.push(`- **New gaps:** ${comparison.regressions.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push(`---`);
+  lines.push(`*Generated by nerviq v${version}*`);
+  return lines.join('\n');
+}
+
+function readOutcomeIndex(dir) {
+  const indexPath = path.join(dir, '.claude', 'claudex-setup', 'outcomes', 'index.json');
+  if (!fs.existsSync(indexPath)) return [];
+  try {
+    const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+
+function updateOutcomeIndex(outcomesDir, record) {
+  const indexPath = path.join(outcomesDir, 'index.json');
+  let entries = [];
+
+  if (fs.existsSync(indexPath)) {
+    try {
+      entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+      if (!Array.isArray(entries)) entries = [];
+    } catch {
+      entries = [];
+    }
+  }
+
+  entries.push(record);
+  const MAX_INDEX_ENTRIES = 500;
+  if (entries.length > MAX_INDEX_ENTRIES) {
+    entries = entries.slice(entries.length - MAX_INDEX_ENTRIES);
+  }
+  fs.writeFileSync(indexPath, JSON.stringify(entries, null, 2), 'utf8');
+}
+
+function normalizeOutcomeStatus(value) {
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  if (!['accepted', 'rejected', 'deferred'].includes(normalized)) {
+    throw new Error('feedback status must be one of: accepted, rejected, deferred');
+  }
+  return normalized;
+}
+
+function normalizeOutcomeEffect(value) {
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  if (!['positive', 'neutral', 'negative'].includes(normalized)) {
+    throw new Error('feedback effect must be one of: positive, neutral, negative');
+  }
+  return normalized;
+}
+
+function recordRecommendationOutcome(dir, payload) {
+  const key = `${payload.key || ''}`.trim();
+  if (!key) {
+    throw new Error('feedback requires a recommendation key');
+  }
+
+  const status = normalizeOutcomeStatus(payload.status);
+  const effect = normalizeOutcomeEffect(payload.effect || 'neutral');
+  const scoreDelta = Number.isFinite(payload.scoreDelta) ? payload.scoreDelta : (
+    payload.scoreDelta === null || payload.scoreDelta === undefined || payload.scoreDelta === ''
+      ? null
+      : Number(payload.scoreDelta)
+  );
+
+  if (scoreDelta !== null && !Number.isFinite(scoreDelta)) {
+    throw new Error('feedback scoreDelta must be a number when provided');
+  }
+
+  const id = timestampId();
+  const { outcomesDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(outcomesDir, `${id}.json`);
+  const record = {
+    id,
+    createdAt: new Date().toISOString(),
+    key,
+    status,
+    effect,
+    source: `${payload.source || 'manual-cli'}`.trim() || 'manual-cli',
+    notes: `${payload.notes || ''}`.trim(),
+    scoreDelta,
+  };
+
+  writeJson(filePath, record);
+  updateOutcomeIndex(outcomesDir, {
+    ...record,
+    relativePath: path.relative(dir, filePath),
+  });
+
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+    record,
+  };
+}
+
+function summarizeOutcomeEntries(entries = []) {
+  const byKey = {};
+
+  for (const entry of entries) {
+    if (!entry || !entry.key) continue;
+    const bucket = byKey[entry.key] || {
+      key: entry.key,
+      total: 0,
+      accepted: 0,
+      rejected: 0,
+      deferred: 0,
+      positive: 0,
+      neutral: 0,
+      negative: 0,
+      scoreDeltaTotal: 0,
+      scoreDeltaCount: 0,
+      latestAt: null,
+    };
+
+    bucket.total += 1;
+    if (bucket[entry.status] !== undefined) bucket[entry.status] += 1;
+    if (bucket[entry.effect] !== undefined) bucket[entry.effect] += 1;
+    if (Number.isFinite(entry.scoreDelta)) {
+      bucket.scoreDeltaTotal += entry.scoreDelta;
+      bucket.scoreDeltaCount += 1;
+    }
+    if (!bucket.latestAt || new Date(entry.createdAt) > new Date(bucket.latestAt)) {
+      bucket.latestAt = entry.createdAt;
+    }
+
+    byKey[entry.key] = bucket;
+  }
+
+  for (const bucket of Object.values(byKey)) {
+    bucket.avgScoreDelta = bucket.scoreDeltaCount > 0
+      ? Number((bucket.scoreDeltaTotal / bucket.scoreDeltaCount).toFixed(2))
+      : null;
+    bucket.evidenceClass = bucket.total > 0 ? 'measured' : 'estimated';
+  }
+
+  return {
+    totalEntries: entries.length,
+    byKey,
+    keys: Object.keys(byKey).sort(),
+  };
+}
+
+function getRecommendationOutcomeSummary(dir) {
+  return summarizeOutcomeEntries(readOutcomeIndex(dir));
+}
+
+function getRecommendationAdjustment(summaryByKey, key) {
+  const bucket = summaryByKey && summaryByKey[key];
+  if (!bucket) return 0;
+
+  let adjustment = 0;
+  adjustment += bucket.accepted * 2;
+  adjustment += bucket.positive * 3;
+  adjustment -= bucket.rejected * 3;
+  adjustment -= bucket.negative * 4;
+
+  if (Number.isFinite(bucket.avgScoreDelta)) {
+    if (bucket.avgScoreDelta > 0) adjustment += Math.min(4, Math.round(bucket.avgScoreDelta / 4));
+    if (bucket.avgScoreDelta < 0) adjustment -= Math.min(4, Math.round(Math.abs(bucket.avgScoreDelta) / 4));
+  }
+
+  if (adjustment > 8) return 8;
+  if (adjustment < -8) return -8;
+  return adjustment;
+}
+
+function formatRecommendationOutcomeSummary(dir) {
+  const summary = getRecommendationOutcomeSummary(dir);
+  if (summary.totalEntries === 0) {
+    return 'No recommendation outcomes recorded yet. Use `npx nerviq feedback --key permissionDeny --status accepted --effect positive` after a real run.';
+  }
+
+  const lines = [
+    'Recommendation outcome summary:',
+    '',
+  ];
+
+  for (const key of summary.keys) {
+    const bucket = summary.byKey[key];
+    const avg = Number.isFinite(bucket.avgScoreDelta) ? ` | avg score delta ${bucket.avgScoreDelta >= 0 ? '+' : ''}${bucket.avgScoreDelta}` : '';
+    const adjustment = getRecommendationAdjustment(summary.byKey, key);
+    lines.push(`  ${key}: total ${bucket.total} | accepted ${bucket.accepted} | rejected ${bucket.rejected} | deferred ${bucket.deferred} | positive ${bucket.positive} | negative ${bucket.negative}${avg} | ranking ${adjustment >= 0 ? '+' : ''}${adjustment}`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  ensureArtifactDirs,
+  writeActivityArtifact,
+  writeRollbackArtifact,
+  writeSnapshotArtifact,
+  readSnapshotIndex,
+  getHistory,
+  compareLatest,
+  formatHistory,
+  exportTrendReport,
+  readOutcomeIndex,
+  recordRecommendationOutcome,
+  summarizeOutcomeEntries,
+  getRecommendationOutcomeSummary,
+  getRecommendationAdjustment,
+  formatRecommendationOutcomeSummary,
+};