@nerviq/cli 0.9.3 → 0.9.5

package/src/feedback.js

@@ -0,0 +1,173 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+let lastTimestamp = '';
+let counter = 0;
+
+function timestampId() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  if (ts === lastTimestamp) {
+    counter += 1;
+    return `${ts}-${counter}`;
+  }
+  lastTimestamp = ts;
+  counter = 0;
+  return ts;
+}
+
+function ensureFeedbackDir(dir) {
+  const feedbackDir = path.join(dir, '.claude', 'claudex-setup', 'feedback');
+  fs.mkdirSync(feedbackDir, { recursive: true });
+  return feedbackDir;
+}
+
+function writeJson(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf8');
+}
+
+function saveFeedback(dir, payload) {
+  const feedbackDir = ensureFeedbackDir(dir);
+  const id = timestampId();
+  const keySlug = String(payload.key || 'finding').replace(/[^a-z0-9_-]+/gi, '-').toLowerCase();
+  const filePath = path.join(feedbackDir, `${id}-${keySlug}.json`);
+  const envelope = {
+    schemaVersion: 1,
+    id,
+    createdAt: new Date().toISOString(),
+    ...payload,
+  };
+  writeJson(filePath, envelope);
+  return {
+    ...envelope,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+  };
+}
+
+function getFeedbackSummary(dir) {
+  const feedbackDir = ensureFeedbackDir(dir);
+  const files = fs.readdirSync(feedbackDir).filter((name) => name.endsWith('.json'));
+  const entries = [];
+
+  for (const file of files) {
+    const filePath = path.join(feedbackDir, file);
+    try {
+      entries.push(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+    } catch {
+      // Ignore malformed artifacts so one bad file does not break the summary.
+    }
+  }
+
+  const summary = {
+    totalEntries: entries.length,
+    helpful: 0,
+    unhelpful: 0,
+    byKey: {},
+    relativeDir: path.relative(dir, feedbackDir),
+  };
+
+  for (const entry of entries) {
+    const helpful = entry.helpful === true;
+    if (helpful) {
+      summary.helpful += 1;
+    } else if (entry.helpful === false) {
+      summary.unhelpful += 1;
+    }
+
+    const bucket = summary.byKey[entry.key] || { total: 0, helpful: 0, unhelpful: 0 };
+    bucket.total += 1;
+    if (helpful) {
+      bucket.helpful += 1;
+    } else if (entry.helpful === false) {
+      bucket.unhelpful += 1;
+    }
+    summary.byKey[entry.key] = bucket;
+  }
+
+  return summary;
+}
+
+function askQuestion(rl, prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
+async function collectFeedback(dir, options = {}) {
+  const findings = Array.isArray(options.findings) ? options.findings : [];
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+
+  if (findings.length === 0) {
+    return {
+      saved: 0,
+      skipped: 0,
+      helpful: 0,
+      unhelpful: 0,
+      entries: [],
+      relativeDir: path.relative(dir, ensureFeedbackDir(dir)),
+    };
+  }
+
+  if (!(stdin.isTTY && stdout.isTTY)) {
+    return {
+      mode: 'skipped-noninteractive',
+      saved: 0,
+      skipped: findings.length,
+      helpful: 0,
+      unhelpful: 0,
+      entries: [],
+      relativeDir: path.relative(dir, ensureFeedbackDir(dir)),
+    };
+  }
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const entries = [];
+
+  try {
+    for (const finding of findings) {
+      stdout.write(`\n  Feedback for ${finding.name} (${finding.key})\n`);
+      let answer = await askQuestion(rl, '  Was this helpful? (y/n) ');
+      answer = String(answer || '').trim().toLowerCase();
+
+      if (!['y', 'yes', 'n', 'no'].includes(answer)) {
+        continue;
+      }
+
+      entries.push(saveFeedback(dir, {
+        key: finding.key,
+        name: finding.name,
+        helpful: answer === 'y' || answer === 'yes',
+        platform: options.platform || null,
+        sourceCommand: options.sourceCommand || 'audit',
+        sourceUrl: finding.sourceUrl || null,
+        impact: finding.impact || null,
+        category: finding.category || null,
+        score: Number.isFinite(options.score) ? options.score : null,
+      }));
+    }
+  } finally {
+    rl.close();
+  }
+
+  const helpful = entries.filter((entry) => entry.helpful).length;
+  const unhelpful = entries.filter((entry) => entry.helpful === false).length;
+
+  return {
+    saved: entries.length,
+    skipped: findings.length - entries.length,
+    helpful,
+    unhelpful,
+    entries,
+    relativeDir: path.relative(dir, ensureFeedbackDir(dir)),
+    summary: getFeedbackSummary(dir),
+  };
+}
+
+module.exports = {
+  collectFeedback,
+  saveFeedback,
+  getFeedbackSummary,
+};

package/src/freshness.js

@@ -0,0 +1,177 @@
+/**
+ * Claude Code Freshness Operationalization
+ *
+ * Release gates, recurring probes, propagation checklists,
+ * and staleness blocking for Claude Code surfaces.
+ *
+ * P0 sources from docs.anthropic.com, propagation for CLAUDE.md format changes.
+ */
+
+const { version } = require('../package.json');
+
+/**
+ * P0 sources that must be fresh before any Claude Code release claim.
+ */
+const P0_SOURCES = [
+  {
+    key: 'claude-code-docs',
+    label: 'Claude Code Official Docs',
+    url: 'https://docs.anthropic.com/claude-code',
+    stalenessThresholdDays: 30,
+    verifiedAt: null,
+  },
+  {
+    key: 'claude-md-format',
+    label: 'CLAUDE.md Format Documentation',
+    url: 'https://docs.anthropic.com/claude-code/claude-md',
+    stalenessThresholdDays: 30,
+    verifiedAt: null,
+  },
+  {
+    key: 'claude-mcp-docs',
+    label: 'Claude Code MCP Documentation',
+    url: 'https://docs.anthropic.com/claude-code/mcp',
+    stalenessThresholdDays: 30,
+    verifiedAt: null,
+  },
+  {
+    key: 'claude-hooks-docs',
+    label: 'Claude Code Hooks Documentation',
+    url: 'https://docs.anthropic.com/claude-code/hooks',
+    stalenessThresholdDays: 14,
+    verifiedAt: null,
+  },
+  {
+    key: 'claude-security-docs',
+    label: 'Claude Code Security Documentation',
+    url: 'https://docs.anthropic.com/claude-code/security',
+    stalenessThresholdDays: 30,
+    verifiedAt: null,
+  },
+  {
+    key: 'claude-permissions-docs',
+    label: 'Claude Code Permissions Documentation',
+    url: 'https://docs.anthropic.com/claude-code/permissions',
+    stalenessThresholdDays: 14,
+    verifiedAt: null,
+  },
+  {
+    key: 'claude-settings-docs',
+    label: 'Claude Code Settings Documentation',
+    url: 'https://docs.anthropic.com/claude-code/settings',
+    stalenessThresholdDays: 30,
+    verifiedAt: null,
+  },
+  {
+    key: 'anthropic-changelog',
+    label: 'Anthropic Changelog',
+    url: 'https://docs.anthropic.com/changelog',
+    stalenessThresholdDays: 14,
+    verifiedAt: null,
+  },
+];
+
+/**
+ * Propagation checklist: when a Claude Code source changes, these must update.
+ */
+const PROPAGATION_CHECKLIST = [
+  {
+    trigger: 'CLAUDE.md format change (new fields, import syntax, hierarchy change)',
+    targets: [
+      'src/context.js — update ProjectContext parsing',
+      'src/techniques.js — update memory/context checks',
+      'src/setup.js — update CLAUDE.md template generation',
+    ],
+  },
+  {
+    trigger: 'Hooks system change (event types, exit codes, schema)',
+    targets: [
+      'src/governance.js — update hookRegistry',
+      'src/techniques.js — update hooks checks',
+    ],
+  },
+  {
+    trigger: 'MCP configuration format change',
+    targets: [
+      'src/techniques.js — update MCP checks',
+      'src/mcp-packs.js — update pack projections',
+      'src/context.js — update mcpConfig parsing',
+    ],
+  },
+  {
+    trigger: 'Permissions model change (allow/deny lists, operator/user split)',
+    targets: [
+      'src/governance.js — update permissionProfiles',
+      'src/techniques.js — update permission checks',
+    ],
+  },
+];
+
+/**
+ * Release gate: check if all P0 sources are within staleness threshold.
+ */
+function checkReleaseGate(sourceVerifications = {}) {
+  const now = new Date();
+  const results = P0_SOURCES.map(source => {
+    const verifiedAt = sourceVerifications[source.key]
+      ? new Date(sourceVerifications[source.key])
+      : source.verifiedAt ? new Date(source.verifiedAt) : null;
+
+    if (!verifiedAt) {
+      return { ...source, status: 'unverified', daysStale: null };
+    }
+
+    const daysSince = Math.floor((now - verifiedAt) / (1000 * 60 * 60 * 24));
+    const isStale = daysSince > source.stalenessThresholdDays;
+
+    return {
+      ...source,
+      verifiedAt: verifiedAt.toISOString(),
+      daysStale: daysSince,
+      status: isStale ? 'stale' : 'fresh',
+    };
+  });
+
+  return {
+    ready: results.every(r => r.status === 'fresh'),
+    stale: results.filter(r => r.status === 'stale' || r.status === 'unverified'),
+    fresh: results.filter(r => r.status === 'fresh'),
+    results,
+  };
+}
+
+function formatReleaseGate(gateResult) {
+  const lines = [
+    `Claude Code Freshness Gate (nerviq v${version})`,
+    '═══════════════════════════════════════',
+    '',
+    `Status: ${gateResult.ready ? 'READY' : 'BLOCKED'}`,
+    `Fresh: ${gateResult.fresh.length}/${gateResult.results.length}`,
+    '',
+  ];
+
+  for (const result of gateResult.results) {
+    const icon = result.status === 'fresh' ? '✓' : result.status === 'stale' ? '✗' : '?';
+    const age = result.daysStale !== null ? ` (${result.daysStale}d ago)` : ' (unverified)';
+    lines.push(`  ${icon} ${result.label}${age} — threshold: ${result.stalenessThresholdDays}d`);
+  }
+
+  if (!gateResult.ready) {
+    lines.push('', 'Action required: verify stale/unverified sources before claiming release freshness.');
+  }
+
+  return lines.join('\n');
+}
+
+function getPropagationTargets(triggerKeyword) {
+  const keyword = triggerKeyword.toLowerCase();
+  return PROPAGATION_CHECKLIST.filter(item => item.trigger.toLowerCase().includes(keyword));
+}
+
+module.exports = {
+  P0_SOURCES,
+  PROPAGATION_CHECKLIST,
+  checkReleaseGate,
+  formatReleaseGate,
+  getPropagationTargets,
+};

package/src/gemini/techniques.js

@@ -14,6 +14,7 @@ const os = require('os');
 const path = require('path');
 const { GeminiProjectContext } = require('./context');
 const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
 
 // ─── Shared helpers ─────────────────────────────────────────────────────────
 
@@ -2230,6 +2231,8 @@ const GEMINI_TECHNIQUES = {
   },
 };
 
+attachSourceUrls('gemini', GEMINI_TECHNIQUES);
+
 module.exports = {
   GEMINI_TECHNIQUES,
 };