@activemind/scd 1.4.0

package/lib/push-queue.js

@@ -0,0 +1,322 @@
+/**
+ * push-queue.js
+ * Offline-first push queue for scd events → scd-server.
+ *
+ * Events are always written to audit.log first (existing behaviour).
+ * When a central URL is configured, events are also queued here and
+ * flushed to the server on every scd command (non-blocking).
+ *
+ * Queue file: ~/.scd/push-queue.jsonl  (one JSON object per line)
+ *
+ * Each entry:
+ *   { id, ts, attempts, lastAttempt, event: { ...audit event } }
+ *
+ * Flush behaviour:
+ *   - Sends all pending events as a single POST /api/v1/events/batch
+ *   - On success: removes sent entries from queue
+ *   - On failure: increments attempts, updates lastAttempt, keeps entry
+ *   - Silent on network errors – never blocks the CLI
+ *
+ * Stale threshold: entries with attempts >= 10 are considered stale.
+ * scd doctor reports stale count; scd repo --verify --clean can purge.
+ * TODO: scd store/repo --verify --clean is currently per-repo but the push queue
+ * lives globally at ~/.scd — consider a global scd verify --clean command.
+ *
+ * Grace period: if all events are older than 7 days the user is warned
+ * by scd doctor (not by the push worker itself).
+ */
+
+'use strict';
+const { DIM } = require('./output-constants');
+
+const fs     = require('fs');
+const path   = require('path');
+const os     = require('os');
+const crypto = require('crypto');
+
+const QUEUE_PATH      = path.join(os.homedir(), '.scd', 'push-queue.jsonl');
+// Stale threshold: entries older than STALE_DAYS with at least one permanent failure
+// are considered stale. Transient failures (network down, server unreachable) do NOT
+// increment attempts and never cause entries to go stale.
+const STALE_DAYS      = 30;
+const STALE_ATTEMPTS  = 10;  // kept for backwards compat with existing queue entries
+const GRACE_DAYS      = 7;
+const BATCH_ENDPOINT  = '/api/v1/events/batch';
+
+// ── Machine fingerprint ──────────────────────────────────────────────────
+const { getMachineFingerprint } = require('./store');
+
+/**
+ * Build the meta object sent alongside events.
+ * Includes installation identity and repo context.
+ * repoRoot is optional — omitted when flush is called outside a repo context.
+ */
+function buildMeta(repoRoot) {
+  const meta = {
+    installationId: getMachineFingerprint(),
+    hostname:       os.hostname(),
+    platform:       os.platform(),
+    scdVersion:     (() => {
+      try { return require('../package.json').version; } catch { return null; }
+    })(),
+  };
+
+  if (repoRoot) {
+    try {
+      const store = require('./store');
+      meta.repoId     = store.getRepoId(repoRoot);
+      meta.repoName   = path.basename(path.resolve(repoRoot));
+      // Include remote URL if available
+      const identity = store.getRepoIdentity ? store.getRepoIdentity(repoRoot) : null;
+      if (identity && identity.type === 'remote') {
+        meta.repoRemote = identity.identifier;
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  return meta;
+}
+
+// ── Queue file helpers ────────────────────────────────────────────────────
+
+function readQueue() {
+  if (!fs.existsSync(QUEUE_PATH)) return [];
+  try {
+    return fs.readFileSync(QUEUE_PATH, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(line => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(entries) {
+  try {
+    const dir = path.dirname(QUEUE_PATH);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const content = entries.map(e => JSON.stringify(e)).join('\n');
+    fs.writeFileSync(QUEUE_PATH, content ? content + '\n' : '', { encoding: 'utf8', mode: 0o600 });
+  } catch {
+    // Queue write failure is non-fatal — audit.log is the source of truth
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Add an audit event to the push queue.
+ * Called from audit.js whenever a scan completes.
+ */
+function enqueue(auditEvent) {
+  try {
+    const entry = {
+      id:          `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      ts:          new Date().toISOString(),
+      attempts:    0,
+      lastAttempt: null,
+      event:       auditEvent,
+    };
+    const dir = path.dirname(QUEUE_PATH);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.appendFileSync(QUEUE_PATH, JSON.stringify(entry) + '\n', { encoding: 'utf8', mode: 0o600 });
+  } catch {
+    // Non-fatal
+  }
+}
+
+/**
+ * Flush pending events to scd-server.
+ * Returns a status string for optional display: 'sent', 'unreachable', 'empty', 'error'.
+ * Always resolves — never rejects.
+ *
+ * @param {string} centralUrl  e.g. 'https://security.company.internal:3000'
+ * @param {object} opts
+ * @param {boolean} opts.verbose  print result to terminal
+ */
+async function flush(centralUrl, opts = {}) {
+  const entries = readQueue();
+  const pending = entries.filter(e => !isStale(e));
+
+  if (pending.length === 0) return 'empty';
+
+  const url   = centralUrl.replace(/\/$/, '') + BATCH_ENDPOINT;
+  const now   = new Date().toISOString();
+  const token = opts.token || (() => {
+    try { return require('./global-config').getCentralToken(); } catch { return null; }
+  })();
+
+  try {
+    const http  = url.startsWith('https') ? require('https') : require('http');
+    const meta  = buildMeta(opts.repoRoot || null);
+    const body  = JSON.stringify({ events: pending.map(e => e.event), meta });
+
+    const response = await httpPost(http, url, body, token);
+
+    if (response.status >= 200 && response.status < 300) {
+      // Remove successfully sent entries, keep stale ones
+      const sentIds  = new Set(pending.map(e => e.id));
+      const remaining = entries.filter(e => !sentIds.has(e.id));
+      writeQueue(remaining);
+
+      // Cache server version info for CLI version warning
+      try {
+        const parsed = JSON.parse(response.body);
+        if (parsed.server_version || parsed.min_cli_version) {
+          require('./global-config').setServerVersionInfo(
+            parsed.server_version || null,
+            parsed.min_cli_version || null
+          );
+        }
+      } catch { /* non-fatal */ }
+
+      if (opts.verbose) {
+        console.log(`${DIM}  ↑ Synced ${pending.length} queued event(s) to central${RESET}`);
+      }
+      return 'sent';
+    } else if (response.status === 503) {
+      // Server license invalid — do NOT bump attempts, keep events intact for retry
+      // Data is safe in queue and will sync automatically when license is restored
+      let isLicenseInvalid = false;
+      try {
+        const parsed = JSON.parse(response.body);
+        isLicenseInvalid = parsed.error === 'License invalid';
+      } catch { /* ignore parse error */ }
+
+      if (isLicenseInvalid) {
+        if (opts.verbose) {
+          console.log(`${DIM}  ↑ Server license invalid – ${pending.length} event(s) held in queue${RESET}`);
+        }
+        return 'license_invalid';
+      }
+      // Other 503 — server temporarily unavailable, do NOT bump attempts
+      if (opts.verbose) {
+        console.log(`${DIM}  ↑ Central unavailable (503) – ${pending.length} event(s) held in queue${RESET}`);
+      }
+      return 'unreachable';
+    } else {
+      // Server reachable but returned error — increment attempts
+      bumpAttempts(entries, pending, now);
+      if (opts.verbose) {
+        console.log(`${DIM}  ↑ Central returned ${response.status} – ${pending.length} event(s) queued for next sync${RESET}`);
+      }
+      return 'error';
+    }
+  } catch {
+    // Network error — server unreachable (connection refused, DNS failure, timeout)
+    // Do NOT bump attempts — this is a transient failure, not a permanent error.
+    // Events stay in queue and will sync when server comes back online.
+    if (opts.verbose) {
+      console.log(`${DIM}  ↑ Central unreachable – ${pending.length} event(s) held in queue${RESET}`);
+    }
+    return 'unreachable';
+  }
+}
+
+function bumpAttempts(allEntries, pendingEntries, now) {
+  const pendingIds = new Set(pendingEntries.map(e => e.id));
+  const updated = allEntries.map(e => {
+    if (!pendingIds.has(e.id)) return e;
+    return { ...e, attempts: e.attempts + 1, lastAttempt: now };
+  });
+  writeQueue(updated);
+}
+
+/**
+ * Determine if a queue entry is stale.
+ * An entry is stale if:
+ *   - It has >= STALE_ATTEMPTS permanent failures (backwards compat), OR
+ *   - It is older than STALE_DAYS days
+ * Transient failures (unreachable) do not increment attempts and are never stale
+ * unless they are very old.
+ */
+function isStale(entry) {
+  if (entry.attempts >= STALE_ATTEMPTS) return true;
+  const ageMs = Date.now() - new Date(entry.ts).getTime();
+  return ageMs > STALE_DAYS * 24 * 60 * 60 * 1000;
+}
+
+/**
+ * Number of events currently in queue (excluding stale).
+ */
+function queueSize() {
+  return readQueue().filter(e => !isStale(e)).length;
+}
+
+/**
+ * Number of stale events (attempts >= STALE_ATTEMPTS).
+ */
+function staleCount() {
+  return readQueue().filter(e => isStale(e)).length;
+}
+
+/**
+ * Whether all pending events are older than the grace period.
+ * Returns false if queue is empty.
+ */
+function isPastGrace() {
+  const pending = readQueue().filter(e => e.attempts < STALE_ATTEMPTS);
+  if (pending.length === 0) return false;
+  const oldest = pending.reduce((min, e) => e.ts < min ? e.ts : min, pending[0].ts);
+  const ageMs  = Date.now() - new Date(oldest).getTime();
+  return ageMs > GRACE_DAYS * 24 * 60 * 60 * 1000;
+}
+
+/**
+ * Remove all stale entries from queue.
+ * Returns number of entries removed.
+ */
+function purgeStale() {
+  const entries = readQueue();
+  const clean   = entries.filter(e => !isStale(e));
+  writeQueue(clean);
+  return entries.length - clean.length;
+}
+
+// ── HTTP helper (no external deps) ───────────────────────────────────────
+
+function httpPost(http, urlStr, body, token = null) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(urlStr);
+    const headers = {
+      'Content-Type':   'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'User-Agent':     'scd-cli/1',
+    };
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+    const { getServerTimeout } = require('./global-config');
+    const options = {
+      hostname: u.hostname,
+      port:     u.port || (u.protocol === 'https:' ? 443 : 80),
+      path:     u.pathname + u.search,
+      method:   'POST',
+      headers,
+      timeout: getServerTimeout(),
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end',  () => resolve({ status: res.statusCode, body: data }));
+    });
+
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    req.on('error',   reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = {
+  enqueue,
+  flush,
+  queueSize,
+  staleCount,
+  isPastGrace,
+  purgeStale,
+  getMachineFingerprint,
+  buildMeta,
+  QUEUE_PATH,
+  STALE_ATTEMPTS,
+  GRACE_DAYS,
+};

package/lib/remove-repo.js

@@ -0,0 +1,108 @@
+/**
+ * remove-repo.js
+ * Removes scd integration from the current repo.
+ *
+ * Hooks are global (shared across all repos via core.hooksPath) so they
+ * are NOT removed — removing them would break all other repos on this machine.
+ * Instead, the repo is marked as inactive in the store.
+ *
+ * Scan history in ~/.scd/repos/{repoId}/ is kept by default.
+ * The user must explicitly type "yes" to delete it.
+ */
+
+'use strict';
+const { RESET, BOLD, DIM, RED, GREEN, YELLOW, CYAN } = require('./output-constants');
+
+const fs   = require('fs');
+const path = require('path');
+
+async function removeRepo(repoRoot) {
+  const store = require('./store');
+
+
+  const repoId   = store.getRepoId(repoRoot);
+  const storePath = store.storeDir(repoRoot);
+  const meta      = store.readMeta(repoRoot);
+  const repoName  = meta?.name || path.basename(repoRoot);
+
+  console.log('\n' + BOLD + 'scd remove' + RESET);
+  console.log(DIM + '  Repository: ' + repoName + RESET);
+  console.log(DIM + '  Store ID:   ' + repoId + RESET);
+  console.log(DIM + '  Path:       ' + repoRoot + RESET);
+  console.log('');
+
+  // Disable hooks for this repo on removal — repo is no longer under scd management.
+  // Sets local core.hooksPath to /dev/null so git hooks stop triggering,
+  // regardless of global config or any previous local override.
+  const { disableHooks } = require('./hooks-manager');
+  try {
+    disableHooks(repoRoot);
+    console.log(GREEN + '  ✓ Git hooks disabled for this repo' + RESET);
+    console.log(DIM   + '    Run scd init to re-enable scanning and hooks' + RESET);
+  } catch {
+    console.log(DIM + '  Note: Could not disable hooks — run manually:' + RESET);
+    const nullDev = process.platform === 'win32' ? 'NUL' : '/dev/null';
+    console.log(DIM + '    git config --local core.hooksPath ' + nullDev + RESET);
+  }
+  console.log('');
+
+  // Mark as inactive in store
+  try {
+    const metaPath = path.join(storePath, 'meta.json');
+    let existing = {};
+    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch {}
+    existing.removed   = true;
+    existing.removedAt = new Date().toISOString();
+    fs.writeFileSync(metaPath, JSON.stringify(existing, null, 2), 'utf8');
+    console.log(GREEN + '  ✓ Repository marked as inactive' + RESET);
+  } catch (err) {
+    console.log(YELLOW + '  ⚠ Could not update store: ' + err.message + RESET);
+  }
+
+  // Ask about scan history
+  console.log('');
+  console.log('  Scan history is stored in:');
+  console.log(DIM + '  ' + storePath + RESET);
+  console.log('');
+  console.log(DIM + '  Keeping history lets you run ' + CYAN + 'scd init' + DIM + ' again and continue' + RESET);
+  console.log(DIM + '  from where you left off. You can also clean up later with:' + RESET);
+  console.log(DIM + '    scd repo --verify --clean' + RESET);
+  console.log('');
+
+  const answer = await promptLine(
+    YELLOW + '  Delete scan history? Type "yes" to confirm, or press Enter to keep: ' + RESET
+  );
+
+  if (answer.trim().toLowerCase() === 'yes') {
+    try {
+      fs.rmSync(storePath, { recursive: true, force: true });
+      console.log('');
+      console.log(RED + '  ✓ Scan history deleted' + RESET);
+    } catch (err) {
+      console.log(RED + '  ✗ Could not delete history: ' + err.message + RESET);
+    }
+  } else {
+    console.log('');
+    console.log(DIM + '  ✓ Scan history kept' + RESET);
+  }
+
+  console.log('');
+  console.log(GREEN + BOLD + '  Done.' + RESET);
+  console.log(DIM + '  Run ' + CYAN + 'scd init' + DIM + ' to re-register this repo.' + RESET);
+  console.log(DIM + '  Run ' + CYAN + 'scd repo --verify --clean' + DIM + ' to manage inactive repos.' + RESET);
+  console.log('');
+}
+
+function promptLine(question) {
+  return new Promise(resolve => {
+    process.stdout.write(question);
+    process.stdin.setEncoding('utf8');
+    process.stdin.resume();
+    process.stdin.once('data', data => {
+      process.stdin.pause();
+      resolve(data.toString().trim());
+    });
+  });
+}
+
+module.exports = { removeRepo };

package/lib/repo-context.js

@@ -0,0 +1,187 @@
+'use strict';
+
+/**
+ * lib/repo-context.js
+ *
+ * Reads project manifest files to build a repo context snapshot.
+ * Context is used locally for smarter rule targeting and sent to
+ * scd-server for dependency tracking, compliance reports, and
+ * future intel (CVE matching) features.
+ *
+ * Supported manifests:
+ *   JavaScript/TypeScript: package.json
+ *   Python:               requirements.txt, pyproject.toml
+ *   PHP:                  composer.json
+ *   .NET:                 *.csproj
+ *
+ * Storage: ~/.scd/repos/{repoId}/repo-context.json
+ * Updated: at each scan, only if content changed.
+ * Server:  sent as repo_context event via push-queue after scan.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+function parsePackageJson(filePath) {
+  try {
+    const pkg  = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const deps = {};
+    for (const [n, v] of Object.entries(pkg.dependencies    || {})) deps[n] = { version: v, dev: false };
+    for (const [n, v] of Object.entries(pkg.devDependencies || {})) deps[n] = { version: v, dev: true  };
+
+    const keys = Object.keys(pkg.dependencies || {});
+    const frameworks = [];
+    if (keys.includes('express'))    frameworks.push('express');
+    if (keys.includes('fastify'))    frameworks.push('fastify');
+    if (keys.includes('koa'))        frameworks.push('koa');
+    if (keys.includes('next'))       frameworks.push('next');
+    if (keys.includes('react'))      frameworks.push('react');
+    if (keys.includes('vue'))        frameworks.push('vue');
+    if (keys.some(k => k.startsWith('@nestjs'))) frameworks.push('nestjs');
+    if (keys.includes('typeorm'))    frameworks.push('typeorm');
+    if (keys.includes('sequelize'))  frameworks.push('sequelize');
+    if (keys.includes('mongoose'))   frameworks.push('mongoose');
+    if (keys.includes('jsonwebtoken')) frameworks.push('jsonwebtoken');
+
+    return { language: 'javascript', manifest: 'package.json',
+             name: pkg.name || null, version: pkg.version || null, frameworks, dependencies: deps };
+  } catch { return null; }
+}
+
+function parseRequirementsTxt(filePath) {
+  try {
+    const deps = {};
+    for (const line of fs.readFileSync(filePath, 'utf8').split('\n')) {
+      const t = line.trim();
+      if (!t || t.startsWith('#') || t.startsWith('-')) continue;
+      const m = t.match(/^([A-Za-z0-9_.-]+)\s*([><=!~]+\s*[\d.*]+)?/);
+      if (m) deps[m[1].toLowerCase()] = { version: m[2]?.trim() || '*', dev: false };
+    }
+    const keys = Object.keys(deps);
+    const frameworks = [];
+    if (keys.includes('flask'))      frameworks.push('flask');
+    if (keys.includes('django'))     frameworks.push('django');
+    if (keys.includes('fastapi'))    frameworks.push('fastapi');
+    if (keys.includes('sqlalchemy')) frameworks.push('sqlalchemy');
+    if (keys.includes('pyjwt'))      frameworks.push('pyjwt');
+    return { language: 'python', manifest: 'requirements.txt', frameworks, dependencies: deps };
+  } catch { return null; }
+}
+
+function parsePyprojectToml(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const deps    = {};
+    const sec = content.match(/\[(?:project\.dependencies|tool\.poetry\.dependencies)\]([\s\S]*?)(?=\[|$)/);
+    if (sec) {
+      for (const line of sec[1].split('\n')) {
+        const m = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*["']?([^"'\n]+)["']?/);
+        if (m) deps[m[1].toLowerCase()] = { version: m[2].trim(), dev: false };
+        const am = line.match(/["']([A-Za-z0-9_.-]+)\s*([><=!~]+\s*[\d.*]+)?["']/);
+        if (am && !m) deps[am[1].toLowerCase()] = { version: am[2]?.trim() || '*', dev: false };
+      }
+    }
+    if (!Object.keys(deps).length) return null;
+    const keys = Object.keys(deps);
+    const frameworks = ['flask','django','fastapi','sqlalchemy','pyjwt'].filter(f => keys.includes(f));
+    return { language: 'python', manifest: 'pyproject.toml', frameworks, dependencies: deps };
+  } catch { return null; }
+}
+
+function parseComposerJson(filePath) {
+  try {
+    const pkg  = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const deps = {};
+    for (const [n, v] of Object.entries(pkg.require      || {})) { if (n !== 'php') deps[n] = { version: v, dev: false }; }
+    for (const [n, v] of Object.entries(pkg['require-dev'] || {})) deps[n] = { version: v, dev: true };
+    const keys = Object.keys(deps);
+    const frameworks = [];
+    if (keys.some(k => k.startsWith('laravel/')))  frameworks.push('laravel');
+    if (keys.some(k => k.startsWith('symfony/')))  frameworks.push('symfony');
+    if (keys.includes('slim/slim'))                frameworks.push('slim');
+    if (keys.includes('doctrine/orm'))             frameworks.push('doctrine');
+    return { language: 'php', manifest: 'composer.json', name: pkg.name || null, frameworks, dependencies: deps };
+  } catch { return null; }
+}
+
+function parseCsproj(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const deps    = {};
+    for (const [, n, v] of content.matchAll(/<PackageReference\s+Include="([^"]+)"\s+Version="([^"]+)"/gi))
+      deps[n.toLowerCase()] = { version: v, dev: false };
+    if (!Object.keys(deps).length) return null;
+    const keys = Object.keys(deps);
+    const frameworks = [];
+    if (keys.some(k => k.includes('aspnetcore')))      frameworks.push('aspnetcore');
+    if (keys.some(k => k.includes('entityframework'))) frameworks.push('entityframework');
+    const tfm = content.match(/<TargetFramework[s]?>([^<]+)<\/TargetFramework[s]?>/i);
+    return { language: 'csharp', manifest: path.basename(filePath),
+             targetFramework: tfm ? tfm[1].trim() : null, frameworks, dependencies: deps };
+  } catch { return null; }
+}
+
+function parseRepoContext(repoRoot) {
+  const results = [];
+  function add(r) { if (r) results.push(r); }
+
+  add(parsePackageJson(path.join(repoRoot, 'package.json')));
+  const hasReqTxt = fs.existsSync(path.join(repoRoot, 'requirements.txt'));
+  if (hasReqTxt) add(parseRequirementsTxt(path.join(repoRoot, 'requirements.txt')));
+  else           add(parsePyprojectToml(path.join(repoRoot, 'pyproject.toml')));
+  add(parseComposerJson(path.join(repoRoot, 'composer.json')));
+
+  try {
+    const csproj = fs.readdirSync(repoRoot).find(e => e.endsWith('.csproj'));
+    if (csproj) add(parseCsproj(path.join(repoRoot, csproj)));
+  } catch { /* ignore */ }
+
+  if (!results.length) return null;
+
+  const languages  = [...new Set(results.map(r => r.language))];
+  const frameworks = [...new Set(results.flatMap(r => r.frameworks || []))];
+  const manifests  = results.map(r => r.manifest);
+
+  const dependencies = {};
+  for (const r of results)
+    for (const [n, info] of Object.entries(r.dependencies || {}))
+      dependencies[`${r.language}:${n}`] = { ...info, language: r.language };
+
+  return {
+    scannedAt: new Date().toISOString(),
+    languages,
+    frameworks,
+    manifestFiles: manifests,
+    manifests: results.map(r => ({
+      language:        r.language,
+      manifest:        r.manifest,
+      name:            r.name            || null,
+      version:         r.version         || null,
+      frameworks:      r.frameworks      || [],
+      targetFramework: r.targetFramework || null,
+      dependencyCount: Object.keys(r.dependencies || {}).length,
+    })),
+    dependencies,
+  };
+}
+
+function loadRepoContext(repoRoot) {
+  try {
+    const { storeDir } = require('./store');
+    const p = path.join(storeDir(repoRoot), 'repo-context.json');
+    return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null;
+  } catch { return null; }
+}
+
+function saveRepoContext(repoRoot, context) {
+  try {
+    const { storeDir } = require('./store');
+    const p = path.join(storeDir(repoRoot), 'repo-context.json');
+    const existing = loadRepoContext(repoRoot);
+    const sig = c => JSON.stringify({ languages: c.languages, frameworks: c.frameworks, dependencies: c.dependencies });
+    fs.writeFileSync(p, JSON.stringify(context, null, 2), 'utf8');
+    return !existing || sig(existing) !== sig(context);
+  } catch { return false; }
+}
+
+module.exports = { parseRepoContext, loadRepoContext, saveRepoContext };