carto-md 2.0.8 → 2.1.0

package/src/cli/status.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `carto status` — one-screen health view of the index.
+ *
+ * Different from `carto inspect`:
+ *   - `inspect` is a deep diagnostic dump (paths, sizes, mtimes,
+ *     bitmap shape, top-impact, extraction errors). For debugging.
+ *   - `status` is the quick "is my index in good shape right now?"
+ *     answer. Single screen. Designed to be read in <2 seconds.
+ *
+ * Layout:
+ *
+ *   carto · my-project · 847 files · 5 domains
+ *   ──────────────────────────────────────────
+ *   Index   ✓ healthy
+ *   Synced  2m ago (147 files, 5 domains, 1,204 imports)
+ *   Bitmap  ✓ fresh
+ *   Schema  v3
+ *   Errors  0 extraction breadcrumbs
+ *
+ *   Top domains:
+ *     CORE     (677 files)
+ *     DATABASE  (67 files)
+ *     ...
+ *
+ * Use `carto inspect` for the full breakdown.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SQLiteStore } = require('../store/sqlite-store');
+const { BITMAP_FILENAME } = require('../bitmap/sidecar');
+
+function formatAge(ts) {
+  if (!ts) return 'never';
+  const ageSec = Math.max(0, Math.round((Date.now() - ts) / 1000));
+  if (ageSec < 60) return `${ageSec}s ago`;
+  if (ageSec < 3600) return `${Math.round(ageSec / 60)}m ago`;
+  if (ageSec < 86400) return `${Math.round(ageSec / 3600)}h ago`;
+  return `${Math.round(ageSec / 86400)}d ago`;
+}
+
+/**
+ * collect(projectRoot) → status snapshot object
+ *   {
+ *     healthy: bool,
+ *     issues: string[],         // human-readable issue lines
+ *     dbExists, dbMtime, schemaVersion,
+ *     bitmapExists, bitmapStale,
+ *     totalFiles, totalRoutes, totalImportEdges,
+ *     domains: [{ name, fileCount }, ...],
+ *     extractionErrors,
+ *     projectName,
+ *   }
+ *
+ * Pure — no I/O on stdout. The renderer (and tests) consumes this.
+ */
+function collect(projectRoot) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  const bitmapPath = path.join(cartoDir, BITMAP_FILENAME);
+  const issues = [];
+
+  const dbStat = (() => { try { return fs.statSync(dbPath); } catch { return null; } })();
+  const bmStat = (() => { try { return fs.statSync(bitmapPath); } catch { return null; } })();
+
+  const snapshot = {
+    projectName: path.basename(projectRoot),
+    healthy: true,
+    issues,
+    dbExists: !!dbStat,
+    dbMtime: dbStat ? dbStat.mtimeMs : null,
+    dbSize: dbStat ? dbStat.size : null,
+    bitmapExists: !!bmStat,
+    bitmapMtime: bmStat ? bmStat.mtimeMs : null,
+    bitmapStale: false,
+    schemaVersion: null,
+    totalFiles: 0,
+    totalRoutes: 0,
+    totalImportEdges: 0,
+    domains: [],
+    extractionErrors: 0,
+  };
+
+  if (!snapshot.dbExists) {
+    snapshot.healthy = false;
+    issues.push(`No index at ${dbPath} — run \`carto init\`.`);
+    return snapshot;
+  }
+
+  // bitmap freshness — stale if missing or older than the DB. This is
+  // a *warning* (surfaced under issues), not a `healthy=false` trigger,
+  // because lazy-rebuild on next MCP query is the documented design —
+  // a missing/stale bitmap doesn't break anything, just costs the first
+  // query a few extra ms.
+  if (!snapshot.bitmapExists) {
+    snapshot.bitmapStale = true;
+    issues.push('Bitmap sidecar missing — will rebuild on next MCP query.');
+  } else if (snapshot.bitmapMtime < snapshot.dbMtime) {
+    snapshot.bitmapStale = true;
+    issues.push('Bitmap sidecar older than DB — will rebuild on next MCP query.');
+  }
+
+  // Open SQLite readonly to harvest the rest.
+  let storeOpenFailed = false;
+  let store;
+  try {
+    store = new SQLiteStore(projectRoot);
+    store.open({ readonly: true });
+    const structure = store.getStructure();
+    // Schema version is a row in the `meta` table, not part of getStructure().
+    const sv = store.getMeta && store.getMeta('schema_version');
+    snapshot.schemaVersion = sv ? parseInt(sv, 10) : null;
+    snapshot.totalFiles = (structure.meta && structure.meta.totalFiles) || 0;
+    snapshot.totalRoutes = (structure.meta && structure.meta.totalRoutes) || 0;
+    snapshot.totalImportEdges = (structure.meta && structure.meta.totalImportEdges) || 0;
+    snapshot.domains = (store.getDomainsList() || []).map((d) => ({
+      name: d.name,
+      fileCount: d.fileCount,
+    }));
+    // Extraction errors — older DBs don't have the table; tolerate it.
+    try {
+      const row = store.db.prepare('SELECT COUNT(*) AS c FROM extraction_errors').get();
+      snapshot.extractionErrors = row.c || 0;
+      if (snapshot.extractionErrors > 0) {
+        issues.push(`${snapshot.extractionErrors} files had extractor errors — run \`carto inspect\`.`);
+      }
+    } catch { /* pre-v2 schema */ }
+  } catch (err) {
+    storeOpenFailed = true;
+    issues.push(`Could not open index: ${err.message}`);
+  } finally {
+    try { store && store.close(); } catch {}
+  }
+
+  // healthy=false only when something actually broken — DB missing or
+  // open failed. Warnings (bitmap stale, extraction errors) live in
+  // `issues` for visibility without flipping the healthy flag.
+  if (storeOpenFailed) snapshot.healthy = false;
+  return snapshot;
+}
+
+function render(snapshot) {
+  const lines = [];
+  const head = `carto · ${snapshot.projectName} · ${snapshot.totalFiles} files · ${snapshot.domains.length} domains`;
+  lines.push(head);
+  lines.push('─'.repeat(Math.min(head.length, 60)));
+
+  const ok = (b) => b ? '✓' : '✗';
+  if (!snapshot.dbExists) {
+    lines.push('Index   ✗ missing — run `carto init`');
+    return lines.join('\n');
+  }
+  lines.push(`Index   ${ok(snapshot.healthy)} ${snapshot.healthy ? 'healthy' : 'has issues'}`);
+  lines.push(`Synced  ${formatAge(snapshot.dbMtime)}  (${snapshot.totalFiles} files, ${snapshot.totalRoutes} routes, ${snapshot.totalImportEdges} imports)`);
+  lines.push(`Bitmap  ${snapshot.bitmapStale ? '⚠ stale (rebuilds on next query)' : '✓ fresh'}`);
+  if (snapshot.schemaVersion !== null) {
+    lines.push(`Schema  v${snapshot.schemaVersion}`);
+  }
+  lines.push(`Errors  ${snapshot.extractionErrors} extraction breadcrumb${snapshot.extractionErrors === 1 ? '' : 's'}`);
+
+  if (snapshot.domains.length > 0) {
+    lines.push('');
+    lines.push('Top domains:');
+    const top = snapshot.domains.slice().sort((a, b) => b.fileCount - a.fileCount).slice(0, 6);
+    const widest = Math.max(...top.map((d) => d.name.length), 6);
+    for (const d of top) {
+      lines.push(`  ${d.name.padEnd(widest)}  (${d.fileCount} file${d.fileCount === 1 ? '' : 's'})`);
+    }
+  }
+
+  if (snapshot.issues.length > 0) {
+    lines.push('');
+    lines.push('Issues:');
+    for (const i of snapshot.issues) lines.push(`  • ${i}`);
+  }
+
+  lines.push('');
+  lines.push('Use `carto inspect` for the full breakdown.');
+  return lines.join('\n');
+}
+
+function run({ argv, stdout, stderr, projectRoot } = {}) {
+  argv = argv || process.argv.slice(3);
+  stdout = stdout || process.stdout;
+  stderr = stderr || process.stderr;
+  projectRoot = projectRoot || process.cwd();
+
+  const json = argv.includes('--json');
+  const help = argv.includes('--help') || argv.includes('-h');
+  if (help) {
+    stdout.write(`\nUsage: carto status [--json]\n\nQuick one-screen health view of the carto index.\nUse \`carto inspect\` for deeper diagnostics.\n\n`);
+    return 0;
+  }
+
+  let snapshot;
+  try { snapshot = collect(projectRoot); }
+  catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  if (json) stdout.write(JSON.stringify(snapshot, null, 2) + '\n');
+  else stdout.write(render(snapshot) + '\n');
+  return snapshot.healthy ? 0 : 1;
+}
+
+module.exports = { run, collect, render };
+
+if (require.main === module) process.exit(run());

package/src/cli/sync.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { runSyncV2 } = require('../store/sync-v2');
+const { runSync } = require('../store/sync');
 const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
@@ -20,7 +20,7 @@ async function run(projectRoot) {
     process.exit(1);
   }
 
-  await runSyncV2({
+  await runSync({
     projectRoot,
     output: path.resolve(projectRoot, config.output || 'AGENTS.md')
   });

package/src/cli/temporal.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * `carto temporal` — temporal-layer CLI commands.
+ *
+ * Subcommands:
+ *   carto temporal init        — backfill from git history
+ *   carto temporal status      — show snapshot + commit + event counts
+ *   carto temporal events      — list recent architectural events
+ *
+ * The temporal store is auto-captured on every `carto sync` once initialized.
+ * `init` is one-time bootstrap to populate `file_churn` from git history.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { TemporalStore } = require('../temporal/store');
+const { backfillFromGit } = require('../temporal/backfill');
+
+async function runInit({ since = null, maxCommits = 2000, projectRoot = process.cwd() } = {}) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  if (!fs.existsSync(cartoDir)) {
+    console.error('[CARTO] No .carto/ found. Run `carto init` first.');
+    process.exit(2);
+  }
+  console.log('[CARTO] Backfilling temporal data from git history...');
+  const result = await backfillFromGit({
+    projectRoot,
+    maxCommits,
+    since,
+    onProgress: ({ done, files }) => {
+      process.stdout.write(`\r[CARTO]   ${done} commits, ${files} file touches`);
+    },
+  });
+  if (result.errors.length > 0) process.stdout.write('\n');
+  else process.stdout.write('\n');
+  console.log(
+    `[CARTO] Backfill complete: ${result.commits} commits, ${result.files} file touches in ${result.elapsedMs}ms.`
+  );
+  if (result.errors.length > 0) {
+    for (const e of result.errors) console.warn(`[CARTO]   ⚠ ${e}`);
+  }
+  return result;
+}
+
+function runStatus({ projectRoot = process.cwd() } = {}) {
+  const temporal = TemporalStore.openIfExists(projectRoot, { readonly: true });
+  if (!temporal) {
+    console.log('[CARTO] No temporal database yet. Run `carto temporal init` to start.');
+    return { healthy: false, reason: 'missing' };
+  }
+  try {
+    const snaps = temporal.countSnapshots();
+    const commits = temporal.countCommits();
+    const recent = temporal.getMostRecentSnapshot();
+    const lastBackfill = temporal.getMeta('last_backfill_at');
+    const events = temporal.getArchEvents({ limit: 5 });
+    console.log(`# Carto Temporal Status\n`);
+    console.log(`- **Snapshots:** ${snaps}`);
+    console.log(`- **Commits:** ${commits}`);
+    if (recent) {
+      const when = new Date(recent.ts).toISOString();
+      console.log(`- **Latest:** ${when} (${recent.source})`);
+    }
+    if (lastBackfill) {
+      const when = new Date(parseInt(lastBackfill, 10)).toISOString();
+      console.log(`- **Last backfill:** ${when}`);
+    }
+    if (events.length > 0) {
+      console.log(`\n## Recent events`);
+      for (const e of events) {
+        const when = new Date(e.ts).toISOString();
+        const target = e.domain || e.file_path || '';
+        console.log(`- ${when} · ${e.severity} · ${e.kind}${target ? ` · ${target}` : ''}`);
+      }
+    }
+    return { healthy: true, snapshots: snaps, commits, events: events.length };
+  } finally {
+    temporal.close();
+  }
+}
+
+function runEvents({ projectRoot = process.cwd(), severity = null, kind = null, timeRange = '90d', limit = 50 } = {}) {
+  const temporal = TemporalStore.openIfExists(projectRoot, { readonly: true });
+  if (!temporal) {
+    console.log('[CARTO] No temporal database. Run `carto temporal init`.');
+    return { events: [] };
+  }
+  try {
+    const { getArchEvents } = require('../temporal/queries');
+    const { events } = getArchEvents(temporal, { severity, kind, timeRange, limit });
+    if (events.length === 0) {
+      console.log(`No events in the last ${timeRange}.`);
+      return { events };
+    }
+    console.log(`# Architectural Events (${timeRange})\n`);
+    console.log(`| When | Severity | Kind | Target | Detail |`);
+    console.log(`|------|----------|------|--------|--------|`);
+    for (const e of events) {
+      const when = new Date(e.ts).toISOString();
+      const target = e.domain || e.file_path || '';
+      let detail = '';
+      if (e.detail_json) {
+        try {
+          const parsed = JSON.parse(e.detail_json);
+          detail = Object.entries(parsed).slice(0, 3).map(([k, v]) => `${k}=${v}`).join(', ');
+        } catch {}
+      }
+      console.log(`| ${when} | ${e.severity} | ${e.kind} | ${target} | ${detail} |`);
+    }
+    return { events };
+  } finally {
+    temporal.close();
+  }
+}
+
+function help() {
+  console.log(`carto temporal <subcommand>
+
+Subcommands:
+  init [--since <range>] [--max-commits N]
+                              Backfill from git history.
+  status                      Show snapshot/commit counts + recent events.
+  events [--severity LEVEL] [--kind KIND] [--time-range RANGE]
+                              List architectural events.
+
+Examples:
+  carto temporal init
+  carto temporal init --since "1 year ago"
+  carto temporal init --max-commits 500
+  carto temporal status
+  carto temporal events --severity critical
+`);
+}
+
+async function main(args) {
+  const sub = args[0];
+  if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+    help();
+    return;
+  }
+
+  const opts = parseFlags(args.slice(1));
+
+  if (sub === 'init') {
+    await runInit({
+      since: opts['since'] || null,
+      maxCommits: opts['max-commits'] ? parseInt(opts['max-commits'], 10) : 2000,
+    });
+    return;
+  }
+  if (sub === 'status') {
+    runStatus({});
+    return;
+  }
+  if (sub === 'events') {
+    runEvents({
+      severity: opts['severity'] || null,
+      kind: opts['kind'] || null,
+      timeRange: opts['time-range'] || '90d',
+      limit: opts['limit'] ? parseInt(opts['limit'], 10) : 50,
+    });
+    return;
+  }
+  console.error(`Unknown subcommand: ${sub}`);
+  help();
+  process.exit(2);
+}
+
+function parseFlags(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith('--')) {
+        out[key] = next;
+        i++;
+      } else {
+        out[key] = true;
+      }
+    }
+  }
+  return out;
+}
+
+module.exports = { main, runInit, runStatus, runEvents };

package/src/cli/validate.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `carto validate` — diff-shaped validation CLI.
+ *
+ * Reads a unified diff from stdin (or `--diff-file <path>`) and prints
+ * the JSON result of `validateDiff()` to stdout. Designed for IDE
+ * extensions and middleware proxies that already speak diffs but don't
+ * want to import Carto internals.
+ *
+ * Contract:
+ *
+ *   Input  — unified diff text on stdin.
+ *   Output — single JSON object on stdout (per `validateDiff()` shape).
+ *   Exit   — 0 on success regardless of risk, 1 on error (no index, bad
+ *            input, etc.), 2 when `--fail-on <severity>` trips.
+ *
+ * Read-only: opens the SQLite store with readonly=true and never
+ * records side-effects to the episodic-memory tables. That persistence
+ * is owned by the MCP `validate_diff` tool — the IDE/middleware paths
+ * are inherently read-only consumers.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { SQLiteStore } = require('../store/sqlite-store');
+const { ensureBitmapFresh } = require('../bitmap/index');
+const { validateDiff } = require('../mcp/validate');
+
+const RISK_RANK = { SAFE: 0, LOW: 1, MEDIUM: 2, HIGH: 3 };
+
+function parseArgs(argv) {
+  const args = {
+    diffFile: null,
+    projectRoot: process.cwd(),
+    failOn: null,
+    pretty: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--diff-file':  args.diffFile = argv[++i]; break;
+      case '--project':    args.projectRoot = path.resolve(argv[++i]); break;
+      case '--fail-on':    args.failOn = (argv[++i] || '').toUpperCase(); break;
+      case '--pretty':     args.pretty = true; break;
+      case '--help':
+      case '-h':           args.help = true; break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown flag: ${a}`);
+    }
+  }
+  if (args.failOn && !['HIGH', 'MEDIUM', 'LOW'].includes(args.failOn)) {
+    throw new Error(`--fail-on must be HIGH | MEDIUM | LOW (got '${args.failOn}')`);
+  }
+  return args;
+}
+
+function printUsage(stream) {
+  (stream || process.stdout).write(`
+Usage: carto validate [options]
+
+Reads a unified diff from stdin (or --diff-file) and prints the
+validateDiff() JSON result to stdout. Used by carto's MCP middleware,
+the VS Code extension, and any custom IDE integration.
+
+Options:
+  --diff-file <path>    Read diff from a file instead of stdin
+  --project <path>      Project root (default: cwd)
+  --fail-on <severity>  Exit 2 if risk >= severity (HIGH | MEDIUM | LOW)
+  --pretty              Pretty-print the JSON output (default: compact)
+  --help, -h            Show this help
+
+Exit codes:
+  0  Normal — JSON written to stdout.
+  1  Misuse, missing index, or read error.
+  2  --fail-on threshold tripped.
+
+JSON shape:
+  { diff, blast_radius, violations, suggestions, risk }
+  See src/mcp/validate.js for full field documentation.
+
+`);
+}
+
+/**
+ * readStdin() → Promise<string>
+ *
+ * Collect stdin until EOF. Done as a one-shot because validate is a
+ * batch operation — IDEs / middleware build a complete diff before
+ * shelling out, they don't stream.
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+/**
+ * computeValidation(projectRoot, diffText) → result
+ *
+ * Pure function over a project root + diff. Opens the SQLite store
+ * read-only, builds (or reuses) the bitmap sidecar, runs validateDiff,
+ * closes the store, returns.
+ *
+ * If the bitmap can't be built (no index, schema mismatch, etc.), we
+ * fall through with sidecar=null — validateDiff degrades gracefully to
+ * no-blast-radius output rather than crashing.
+ */
+function computeValidation(projectRoot, diffText) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(
+      `No carto index at ${dbPath}. Run \`carto init\` first.`
+    );
+  }
+  const store = new SQLiteStore(projectRoot);
+  store.open({ readonly: true });
+  let sidecar = null;
+  try {
+    sidecar = ensureBitmapFresh(cartoDir, store);
+  } catch {
+    // No bitmap → no blast radius, but the diff parser + cross-domain
+    // rules still produce useful output.
+  }
+  try {
+    return validateDiff(store, sidecar, diffText);
+  } finally {
+    store.close();
+  }
+}
+
+/**
+ * run({ argv, stdout, stderr, stdin }) → Promise<exitCode>
+ *
+ * Pure-ish entry point so tests can pass synthetic streams + capture
+ * stdout. Caller decides whether to `process.exit(code)`.
+ */
+async function run({ argv, stdout, stderr, stdin } = {}) {
+  argv = argv || process.argv.slice(3);
+  stdout = stdout || process.stdout;
+  stderr = stderr || process.stderr;
+
+  let args;
+  try { args = parseArgs(argv); }
+  catch (err) { stderr.write(`[CARTO] ${err.message}\n`); return 1; }
+
+  if (args.help) { printUsage(stdout); return 0; }
+
+  let diffText;
+  try {
+    if (args.diffFile) {
+      diffText = fs.readFileSync(args.diffFile, 'utf8');
+    } else if (stdin && typeof stdin.read === 'function' && stdin.isString) {
+      // Test path: caller passed a synthetic stdin shim with a string.
+      diffText = stdin.read();
+    } else {
+      diffText = await readStdin();
+    }
+  } catch (err) {
+    stderr.write(`[CARTO] failed to read diff: ${err.message}\n`);
+    return 1;
+  }
+
+  let result;
+  try {
+    result = computeValidation(args.projectRoot, diffText);
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+
+  const out = args.pretty
+    ? JSON.stringify(result, null, 2) + '\n'
+    : JSON.stringify(result) + '\n';
+  stdout.write(out);
+
+  if (args.failOn && RISK_RANK[result.risk] >= RISK_RANK[args.failOn]) return 2;
+  return 0;
+}
+
+module.exports = {
+  run,
+  parseArgs,
+  computeValidation,
+  RISK_RANK,
+};
+
+if (require.main === module) {
+  run().then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`[CARTO] Fatal: ${err.message}\n`);
+      process.exit(1);
+    });
+}

package/src/cli/watch.js

@@ -4,8 +4,8 @@ const fs = require('fs');
 const path = require('path');
 const chokidar = require('chokidar');
 const { SQLiteStore } = require('../store/sqlite-store');
-const { discoverFiles, generateOutputs, buildRoutesByFile, detectLanguage } = require('../store/sync-v2');
-const { runSyncV2 } = require('../store/sync-v2');
+const { discoverFiles, generateOutputs, buildRoutesByFile, detectLanguage } = require('../store/sync');
+const { runSync } = require('../store/sync');
 const { detectChangedFiles, hashFile, hashContent } = require('../store/change-detector');
 const { loadLanguagePlugins, getPluginForFile } = require('../extractors/loader');
 const { extractImports } = require('../extractors/imports');
@@ -177,7 +177,7 @@ async function run(projectRoot) {
 
   // Initial full sync using V2
   console.log('[CARTO] Starting initial sync...');
-  await runSyncV2({
+  await runSync({
     projectRoot,
     output: path.join(projectRoot, 'AGENTS.md')
   });
@@ -222,7 +222,7 @@ async function run(projectRoot) {
       domainsDirty = false;
       console.log('[CARTO] Idle 5min — reclustering domains...');
       try {
-        await runSyncV2({ projectRoot, output: path.join(projectRoot, 'AGENTS.md') });
+        await runSync({ projectRoot, output: path.join(projectRoot, 'AGENTS.md') });
         console.log('[CARTO] Domain recluster complete.');
       } catch (err) {
         console.error(`[CARTO] Recluster error: ${err.message}`);