@nforma.ai/nforma 0.2.1

package/bin/ccr-secure-start.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// bin/ccr-secure-start.cjs
+// Wrapper script for claude-code-router that:
+//   1. Populates ~/.claude-code-router/config.json from keytar before starting CCR
+//   2. Spawns CCR with the provided args
+//   3. Wipes all provider api_key fields from config.json on exit or signal
+//
+// Usage: node bin/ccr-secure-start.cjs <ccr-binary> [args...]
+// Example: node bin/ccr-secure-start.cjs ccr start
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync, spawn } = require('child_process');
+
+const CONFIG_PATH = path.join(os.homedir(), '.claude-code-router', 'config.json');
+const SECURE_CONFIG = path.join(__dirname, 'ccr-secure-config.cjs');
+
+// Synchronously wipe all api_key fields in config.json to empty strings.
+// Called on exit and on signal to ensure keys are not left on disk.
+function wipeKeys() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const config = JSON.parse(raw);
+    if (Array.isArray(config.providers)) {
+      for (const provider of config.providers) {
+        provider.api_key = '';
+      }
+    }
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), { mode: 0o600 });
+  } catch (_) {
+    // Fail silently — config may not exist or may already be wiped
+  }
+}
+
+async function main() {
+  const ccrBin = process.argv[2];
+  const ccrArgs = process.argv.slice(3);
+
+  if (!ccrBin) {
+    process.stderr.write('Usage: node ccr-secure-start.cjs <ccr-binary> [args...]\n');
+    process.stderr.write('Example: node ccr-secure-start.cjs ccr start\n');
+    process.exit(1);
+  }
+
+  // Step 1: Populate config.json from keytar
+  try {
+    execFileSync(process.execPath, [SECURE_CONFIG], { stdio: 'inherit' });
+  } catch (e) {
+    process.stderr.write('[ccr-secure-start] Failed to populate CCR config: ' + e.message + '\n');
+    process.exit(1);
+  }
+
+  // Step 2: Spawn CCR
+  const child = spawn(ccrBin, ccrArgs, { stdio: 'inherit' });
+
+  // Step 3: Wipe keys on CCR exit
+  child.on('exit', (code) => {
+    wipeKeys();
+    process.exit(code ?? 0);
+  });
+
+  // Wipe keys on SIGTERM (e.g. systemd stop, kill)
+  process.on('SIGTERM', () => {
+    child.kill('SIGTERM');
+    wipeKeys();
+    process.exit(0);
+  });
+
+  // Wipe keys on SIGINT (Ctrl-C)
+  process.on('SIGINT', () => {
+    child.kill('SIGINT');
+    wipeKeys();
+    process.exit(0);
+  });
+}
+
+main().catch((e) => {
+  process.stderr.write('[ccr-secure-start] Unexpected error: ' + e.message + '\n');
+  process.exit(1);
+});

package/bin/check-bundled-sdks.cjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Forbidden SDK list — LLM SDKs that QGSD must not bundle (ARCH-10)
+// ---------------------------------------------------------------------------
+
+const FORBIDDEN_SDKS = [
+  '@anthropic-ai/sdk',
+  'anthropic',
+  'openai',
+  '@google/generative-ai',
+  'google-generativeai',
+  'cohere-ai',
+  '@azure/openai',
+];
+
+// ---------------------------------------------------------------------------
+// Import pattern builder
+// ---------------------------------------------------------------------------
+
+function buildImportPatterns() {
+  return FORBIDDEN_SDKS.map(sdk => {
+    // Escape special regex chars in SDK name (@ and /)
+    const escaped = sdk.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return {
+      sdk,
+      patterns: [
+        // CommonJS require
+        new RegExp(`require\\s*\\(\\s*['"]${escaped}['"]\\s*\\)`),
+        // require.resolve
+        new RegExp(`require\\.resolve\\s*\\(\\s*['"]${escaped}['"]\\s*\\)`),
+        // ESM import
+        new RegExp(`import\\s+.*\\s+from\\s+['"]${escaped}['"]`),
+      ],
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Scope filtering
+// ---------------------------------------------------------------------------
+
+function isInScope(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+
+  // Must be under bin/ or hooks/
+  const inScope = normalized.startsWith('bin/') || normalized.startsWith('hooks/') ||
+    normalized.includes('/bin/') || normalized.includes('/hooks/');
+  if (!inScope) return false;
+
+  // Must have .js, .cjs, or .mjs extension
+  if (!/\.(js|cjs|mjs)$/.test(normalized)) return false;
+
+  // Exclude test files
+  if (/\.test\.(js|cjs|mjs)$/.test(normalized)) return false;
+
+  // Exclude node_modules, docs, examples, .planning/formal
+  if (/node_modules|\/docs\/|\/examples\/|\.planning\/formal/.test(normalized)) return false;
+
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Line-level scanning
+// ---------------------------------------------------------------------------
+
+function scanFile(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    // Fail-open on read errors
+    return [];
+  }
+
+  const lines = content.split('\n');
+  const importPatterns = buildImportPatterns();
+  const violations = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trimStart();
+
+    // Skip single-line comments
+    if (trimmed.startsWith('//')) continue;
+
+    for (const { sdk, patterns } of importPatterns) {
+      for (const pattern of patterns) {
+        if (pattern.test(line)) {
+          violations.push({
+            file: filePath,
+            line: i + 1,
+            content: line.trim(),
+            sdk,
+            violation: 'SDK_IMPORT',
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// File walker
+// ---------------------------------------------------------------------------
+
+function getAllSourceFiles(dir) {
+  const results = [];
+  const skipDirs = new Set(['node_modules', '.git', 'dist', '.formal']);
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) {
+          walk(path.join(currentDir, entry.name));
+        }
+      } else if (entry.isFile() && /\.(js|cjs|mjs)$/.test(entry.name)) {
+        results.push(path.join(currentDir, entry.name));
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  console.log('[LINT] Architecture: SDK Bundling Check');
+
+  const allFiles = getAllSourceFiles('.');
+  const scopedFiles = allFiles
+    .map(f => f.startsWith('./') ? f.slice(2) : f)
+    .filter(isInScope);
+
+  console.log(`Scanned ${scopedFiles.length} files`);
+
+  const allViolations = [];
+  for (const file of scopedFiles) {
+    const violations = scanFile(file);
+    allViolations.push(...violations);
+  }
+
+  console.log(`Found ${allViolations.length} violations`);
+
+  for (const v of allViolations) {
+    console.log(`  ERROR: ${v.file}:${v.line}: ${v.content}`);
+  }
+
+  process.exit(allViolations.length > 0 ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Exports + CLI entry
+// ---------------------------------------------------------------------------
+
+module.exports = { FORBIDDEN_SDKS, buildImportPatterns, isInScope, scanFile, getAllSourceFiles };
+
+if (require.main === module) {
+  main();
+}

package/bin/check-coverage-guard.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+'use strict';
+// bin/check-coverage-guard.cjs
+// CI coverage guard — compares current traceability matrix coverage against
+// a saved baseline and warns when the drop exceeds a configurable threshold.
+//
+// Usage:
+//   node bin/check-coverage-guard.cjs                    # compare current vs baseline
+//   node bin/check-coverage-guard.cjs --save-baseline    # save current matrix as baseline
+//   node bin/check-coverage-guard.cjs --threshold 10     # override threshold (default: 15)
+//   node bin/check-coverage-guard.cjs --quiet            # suppress output (exit code only)
+//
+// Requirements: TRACE-05
+
+const fs   = require('fs');
+const path = require('path');
+
+const TAG = '[check-coverage-guard]';
+let ROOT = process.cwd();
+
+// Parse --project-root (overrides CWD-based ROOT for cross-repo usage)
+for (const arg of process.argv.slice(2)) {
+  if (arg.startsWith('--project-root=')) {
+    ROOT = path.resolve(arg.slice('--project-root='.length));
+  }
+}
+
+const MATRIX_PATH   = process.env.COVERAGE_GUARD_MATRIX_PATH || path.join(ROOT, '.planning', 'formal', 'traceability-matrix.json');
+const BASELINE_PATH = process.env.COVERAGE_GUARD_BASELINE_PATH || path.join(ROOT, '.planning', 'formal', 'traceability-matrix.baseline.json');
+
+// ── CLI flags ───────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const saveBaseline = args.includes('--save-baseline');
+const quietMode    = args.includes('--quiet');
+const thresholdIdx = args.indexOf('--threshold');
+const threshold    = thresholdIdx !== -1 ? parseFloat(args[thresholdIdx + 1]) : 15;
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function log(msg) {
+  if (!quietMode) {
+    process.stdout.write(TAG + ' ' + msg + '\n');
+  }
+}
+
+function loadJSON(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    return null;
+  }
+}
+
+// ── Save Baseline Mode ──────────────────────────────────────────────────────
+
+if (saveBaseline) {
+  const current = loadJSON(MATRIX_PATH);
+  if (!current) {
+    process.stderr.write(TAG + ' ERROR: Cannot read ' + MATRIX_PATH + '\n');
+    process.exit(1);
+  }
+  fs.writeFileSync(BASELINE_PATH, JSON.stringify(current, null, 2) + '\n', 'utf8');
+  const cs = current.coverage_summary || {};
+  log('Baseline saved: ' + (cs.coverage_percentage || 0) + '% coverage (' + (cs.covered_count || 0) + '/' + (cs.total_requirements || 0) + ' requirements)');
+  process.exit(0);
+}
+
+// ── Comparison Mode ─────────────────────────────────────────────────────────
+
+const current = loadJSON(MATRIX_PATH);
+if (!current) {
+  process.stderr.write(TAG + ' ERROR: Cannot read current matrix at ' + MATRIX_PATH + '\n');
+  process.exit(1);
+}
+
+let baseline = loadJSON(BASELINE_PATH);
+
+if (!baseline) {
+  // Auto-create baseline from current matrix
+  fs.writeFileSync(BASELINE_PATH, JSON.stringify(current, null, 2) + '\n', 'utf8');
+  const cs = current.coverage_summary || {};
+  log('No baseline found — creating from current matrix (' + (cs.coverage_percentage || 0) + '%)');
+  log('PASS: No regression (baseline just created)');
+  process.exit(0);
+}
+
+// Extract coverage percentages
+const currentCs  = current.coverage_summary || {};
+const baselineCs = baseline.coverage_summary || {};
+const currentPct  = currentCs.coverage_percentage || 0;
+const baselinePct = baselineCs.coverage_percentage || 0;
+const drop = Math.round((baselinePct - currentPct) * 10) / 10;
+
+if (drop > threshold) {
+  // Coverage regression exceeds threshold
+  log('WARN: Coverage regression detected');
+  log('  Baseline: ' + baselinePct + '% (' + (baselineCs.covered_count || 0) + '/' + (baselineCs.total_requirements || 0) + ')');
+  log('  Current:  ' + currentPct + '% (' + (currentCs.covered_count || 0) + '/' + (currentCs.total_requirements || 0) + ')');
+  log('  Drop:     ' + drop + ' percentage points (threshold: ' + threshold + 'pp)');
+  log('  To update baseline: node bin/check-coverage-guard.cjs --save-baseline');
+  process.exit(1);
+} else if (drop > 0) {
+  // Minor drop within threshold
+  log('PASS: Minor coverage change (' + drop + 'pp drop, within ' + threshold + 'pp threshold)');
+  log('  Baseline: ' + baselinePct + '% → Current: ' + currentPct + '%');
+  process.exit(0);
+} else {
+  // No regression or improved
+  log('PASS: No regression (baseline: ' + baselinePct + '% → current: ' + currentPct + '%)');
+  process.exit(0);
+}

package/bin/check-liveness-fairness.cjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+'use strict';
+// bin/check-liveness-fairness.cjs
+// CI step: scan all TLA+ MC*.cfg files for liveness properties lacking fairness declarations.
+// Emits result='pass' if all fairness declarations found; result='inconclusive' if any missing.
+// Always exits 0 (inconclusive is not a build failure).
+// Requirements: LIVE-01, LIVE-02
+
+const fs   = require('fs');
+const path = require('path');
+const { detectLivenessProperties } = require('./run-tlc.cjs');
+const { writeCheckResult }         = require('./write-check-result.cjs');
+const { getRequirementIds }        = require('./requirement-map.cjs');
+
+const TAG = '[check-liveness-fairness]';
+
+// Allow env var overrides for testing (injected by test scaffold)
+const FORMAL_TLA_DIR  = process.env.FORMAL_TLA_DIR  || path.join(__dirname, '..', '.planning', 'formal', 'tla');
+const FORMAL_SPEC_DIR = process.env.FORMAL_SPEC_DIR || path.join(__dirname, '..', '.planning', 'formal', 'spec');
+
+const startMs = Date.now();
+
+// 1. Discover all MC*.cfg files dynamically
+let cfgFiles;
+try {
+  cfgFiles = fs.readdirSync(FORMAL_TLA_DIR)
+    .filter(f => /^MC.*\.cfg$/.test(f))
+    .map(f => ({ name: f.replace(/\.cfg$/, ''), path: path.join(FORMAL_TLA_DIR, f) }));
+} catch (e) {
+  process.stderr.write(TAG + ' Warning: cannot read .planning/formal/tla dir: ' + e.message + '\n');
+  cfgFiles = [];
+}
+
+// 2. For each config, detect liveness properties without fairness declarations
+const allMissing = [];      // { config, properties: string[] }
+let configsChecked = 0;
+
+for (const { name, path: cfgPath } of cfgFiles) {
+  const missing = detectLivenessProperties(name, cfgPath, FORMAL_SPEC_DIR);
+  configsChecked++;
+  if (missing.length > 0) {
+    allMissing.push({ config: name, properties: missing });
+  }
+}
+
+// 3. Aggregate results
+const runtimeMs = Date.now() - startMs;
+const hasMissing = allMissing.length > 0;
+const result = hasMissing ? 'inconclusive' : 'pass';
+
+const missingList = allMissing
+  .map(({ config, properties }) => config + ': ' + properties.join(', '))
+  .join('; ');
+
+const summaryText = hasMissing
+  ? 'inconclusive: fairness declarations missing — ' + missingList
+  : 'pass: all liveness properties have fairness declarations (' + configsChecked + ' configs checked)';
+
+// 4. Write v2.1 check result
+try {
+  writeCheckResult({
+    tool: 'check-liveness-fairness',
+    formalism: 'tla',
+    result,
+    check_id:   'ci:liveness-fairness-lint',
+    surface:    'ci',
+    property:   'Liveness fairness declarations — all TLA+ liveness properties documented with WF/SF rationale',
+    runtime_ms: runtimeMs,
+    summary:    summaryText,
+    triage_tags: hasMissing ? ['needs-fairness'] : [],
+    requirement_ids: getRequirementIds('ci:liveness-fairness-lint'),
+    metadata: {
+      configs_checked: configsChecked,
+      configs_missing: allMissing.length,
+      missing_detail:  allMissing,
+    },
+  });
+} catch (e) {
+  process.stderr.write(TAG + ' Warning: failed to write check result: ' + e.message + '\n');
+}
+
+// 5. Print summary
+process.stdout.write(TAG + ' Result: ' + result + '\n');
+if (hasMissing) {
+  process.stdout.write(TAG + ' Missing fairness declarations:\n');
+  for (const { config, properties } of allMissing) {
+    process.stdout.write('  ' + config + ': ' + properties.join(', ') + '\n');
+  }
+  process.stdout.write(TAG + ' Add ## <PropertyName> sections to the matching .planning/formal/spec/<spec>/invariants.md\n');
+} else {
+  process.stdout.write(TAG + ' All ' + configsChecked + ' configs have fairness declarations.\n');
+}
+
+// Always exit 0 — inconclusive is not a build failure
+process.exit(0);

package/bin/check-mcp-health.cjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * check-mcp-health.cjs
+ *
+ * Pre-flight health check for all claude-mcp-server instances.
+ * Reads ~/.claude.json to find configured MCP servers, then calls
+ * health_check on each one sequentially. Exits non-zero if any
+ * configured server is unhealthy.
+ *
+ * Usage:
+ *   node bin/check-mcp-health.cjs [--timeout-ms N] [--json]
+ *
+ * Designed to be called at the start of /qgsd:quorum to skip
+ * unresponsive servers before making full inference calls.
+ */
+
+const { execFileSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const args       = process.argv.slice(2);
+const getArg     = (f) => { const i = args.indexOf(f); return i !== -1 && args[i+1] ? args[i+1] : null; };
+const hasFlag    = (f) => args.includes(f);
+const TIMEOUT_MS = parseInt(getArg('--timeout-ms') ?? '12000', 10);
+const JSON_OUT   = hasFlag('--json');
+
+// ─── Load MCP server list from ~/.claude.json ─────────────────────────────────
+let mcpServers = {};
+try {
+  const raw = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf8'));
+  mcpServers = raw.mcpServers ?? {};
+} catch (e) {
+  console.error('Could not read ~/.claude.json:', e.message);
+  process.exit(1);
+}
+
+// Filter to claude-mcp-server instances (those using our dist/index.js)
+const targets = Object.entries(mcpServers)
+  .filter(([, v]) => v.args?.some(a => a.includes('claude-mcp-server')))
+  .map(([name, cfg]) => ({ name, env: cfg.env ?? {} }));
+
+if (targets.length === 0) {
+  console.log('No claude-mcp-server instances found in ~/.claude.json');
+  process.exit(0);
+}
+
+// ─── Run health check via MCP JSON-RPC over stdio ────────────────────────────
+// We can't easily spawn MCP servers here — instead, we proxy through the
+// installed `claude` CLI by calling each server's health_check tool
+// via a one-shot claude -p call with the right env overrides.
+
+const results = [];
+
+for (const { name, env } of targets) {
+  const start = Date.now();
+  let healthy = false;
+  let error   = null;
+  let latencyMs = 0;
+
+  const prompt = JSON.stringify({
+    method: 'health_check_proxy',
+    server: name,
+  });
+
+  // We use a simpler proxy: just call claude with the env overrides directly.
+  // This tests the same path that the MCP tool would use.
+  try {
+    const envForCall = { ...process.env, ...env };
+    const result = execFileSync('claude', [
+      '-p', 'Reply with exactly one word: ok',
+      '--output-format', 'json',
+      '--max-turns', '1',
+    ], {
+      env: envForCall,
+      timeout: TIMEOUT_MS,
+      encoding: 'utf8',
+    });
+    latencyMs = Date.now() - start;
+    const parsed = JSON.parse(result);
+    healthy = !!(parsed.result || parsed.type === 'result');
+  } catch (e) {
+    latencyMs = Date.now() - start;
+    error = e.code === 'ETIMEDOUT'
+      ? `Timed out after ${TIMEOUT_MS}ms`
+      : (e.message ?? String(e)).split('\n')[0].slice(0, 120);
+  }
+
+  results.push({ name, healthy, latencyMs, error });
+}
+
+// ─── Output ───────────────────────────────────────────────────────────────────
+if (JSON_OUT) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  const green = (s) => `\x1b[32m${s}\x1b[0m`;
+  const red   = (s) => `\x1b[31m${s}\x1b[0m`;
+  const dim   = (s) => `\x1b[2m${s}\x1b[0m`;
+  const bold  = (s) => `\x1b[1m${s}\x1b[0m`;
+
+  console.log(`\n${bold('━━━ MCP ENDPOINT HEALTH CHECK ━━━')}`);
+  for (const r of results) {
+    const icon    = r.healthy ? green('✓') : red('✗');
+    const latency = `${r.latencyMs}ms`;
+    const status  = r.healthy ? green('OK') : red('FAIL');
+    const detail  = r.error ? dim(`  ${r.error}`) : '';
+    console.log(`  ${icon}  ${r.name.padEnd(22)} ${status.padEnd(14)} ${dim(latency)}${detail}`);
+  }
+  console.log();
+
+  const unhealthy = results.filter(r => !r.healthy);
+  if (unhealthy.length > 0) {
+    console.log(red(`${unhealthy.length}/${results.length} servers unhealthy — skip these in quorum:`));
+    unhealthy.forEach(r => console.log(`  • ${r.name}`));
+    console.log();
+  }
+}
+
+// Exit 1 if any server is unhealthy (useful for scripting)
+const anyUnhealthy = results.some(r => !r.healthy);
+process.exit(anyUnhealthy ? 1 : 0);