carto-md 2.0.5 → 2.0.7

package/src/cli/init.js

@@ -54,8 +54,6 @@ async function run(projectRoot) {
   installGitHook(projectRoot);
 
   // Run first sync — V2 SQLite-backed indexer.
-  // (Previously: V1 runFullSync with empty file lists from resolveConfig — produced
-  // a 23ms no-op that left .carto/carto.db missing and AGENTS.md unpopulated.)
   await runSyncV2({
     projectRoot,
     output: path.resolve(projectRoot, config.output || 'AGENTS.md')
@@ -67,22 +65,6 @@ async function run(projectRoot) {
   console.log('[CARTO] AGENTS.md generated. Carto will sync on every git commit.');
 }
 
-/**
- * Resolves config paths to absolute paths.
- * V2: no watch file lists — sync-v2 discovers files itself.
- */
-function resolveConfig(projectRoot, config) {
-  return {
-    watch: {
-      routeFiles: (config.watch && config.watch.routeFiles || []).map(f => path.resolve(projectRoot, f)),
-      modelFiles: (config.watch && config.watch.modelFiles || []).map(f => path.resolve(projectRoot, f)),
-      frontendFiles: (config.watch && config.watch.frontendFiles || []).map(f => path.resolve(projectRoot, f))
-    },
-    output: path.resolve(projectRoot, config.output || 'AGENTS.md'),
-    projectRoot
-  };
-}
-
 function installGitHook(projectRoot) {
   const gitDir = path.join(projectRoot, '.git');
   if (!fs.existsSync(gitDir)) return;
@@ -113,6 +95,21 @@ function wireIDEs(projectRoot) {
   const home = os.homedir();
   const wired = [];
 
+  // Claude Code (project-scoped). Spec 7: write .mcp.json at the project root.
+  // Claude Code reads this file automatically when opened in the project — no
+  // host-level config needed, and no detection required (it's a project-local
+  // file that only takes effect when the user actually uses Claude Code here).
+  try {
+    const mcpJsonPath = path.join(projectRoot, '.mcp.json');
+    const config = fs.existsSync(mcpJsonPath)
+      ? JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'))
+      : { mcpServers: {} };
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers.carto = { command: 'carto', args: ['serve'] };
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    wired.push('Claude Code');
+  } catch {}
+
   // Kiro
   const kiroDir = path.join(home, '.kiro', 'settings');
   if (fs.existsSync(path.join(home, '.kiro'))) {
@@ -163,4 +160,4 @@ function wireIDEs(projectRoot) {
   }
 }
 
-module.exports = { run, resolveConfig };
+module.exports = { run };

package/src/cli/serve.js

@@ -4,22 +4,21 @@ const { checkForUpdate } = require('./update-check');
 
 function run(projectRoot) {
   checkForUpdate(); // fire and forget
-  // Prefer V2 SQLite-backed server
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
-  if (fs.existsSync(dbPath)) {
-    console.error('[CARTO] MCP server starting (V2 SQLite)...');
-    require('../mcp/server-v2');
-    return;
-  }
 
-  // Fallback to V1 if no SQLite DB exists
-  const mapPath = path.join(projectRoot, '.carto', 'map.json');
-  if (!fs.existsSync(mapPath)) {
-    console.error('[CARTO] No index found. Run `carto sync` first.');
+  if (!fs.existsSync(dbPath)) {
+    // Could be pre-2.0.4 install with only map.json, or never initialized.
+    const mapPath = path.join(projectRoot, '.carto', 'map.json');
+    if (fs.existsSync(mapPath)) {
+      console.error('[CARTO] Legacy index found (map.json) but no SQLite DB. Run `carto init` to upgrade your index.');
+    } else {
+      console.error('[CARTO] No index found. Run `carto init` first.');
+    }
     process.exit(1);
   }
-  console.error('[CARTO] MCP server starting (V1 compat)...');
-  require('../mcp/server');
+
+  console.error('[CARTO] MCP server starting...');
+  require('../mcp/server-v2');
 }
 
 module.exports = { run };

package/src/cli/sync.js

@@ -1,8 +1,6 @@
 const fs = require('fs');
 const path = require('path');
 const { runSyncV2 } = require('../store/sync-v2');
-const { runFullSync } = require('../sync');
-const { resolveConfig } = require('./init');
 const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot) {
@@ -22,20 +20,10 @@ async function run(projectRoot) {
     process.exit(1);
   }
 
-  // Use V2 SQLite-backed sync
-  const v2Config = {
+  await runSyncV2({
     projectRoot,
     output: path.resolve(projectRoot, config.output || 'AGENTS.md')
-  };
-
-  try {
-    await runSyncV2(v2Config);
-  } catch (err) {
-    // Fallback to V1 if V2 fails (e.g., better-sqlite3 not available)
-    console.warn(`[CARTO] V2 sync failed (${err.message}), falling back to V1`);
-    const resolved = resolveConfig(projectRoot, config);
-    await runFullSync(resolved);
-  }
+  });
 
   console.log('[CARTO] Sync complete.');
 }

package/src/extractors/imports.js

@@ -36,7 +36,11 @@ function extractImports(content, filePath, projectRoot) {
   if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
     rawImports = extractJSImports(content);
   } else if (ext === '.py') {
-    rawImports = extractPythonImports(content, filePath, projectRoot);
+    // Python returns absolute paths from resolvePythonRelativeImport / tryResolvePythonModule.
+    // Relativize to project root and return early — the JS-style dedup loop below only handles
+    // `./` and `@/~/#` prefixed strings, so falling through silently drops every Python edge.
+    const abs = extractPythonImports(content, filePath, projectRoot);
+    return [...new Set(abs.map(p => path.relative(projectRoot, p)))].sort();
   } else if (ext === '.r') {
     return extractRImports(content, filePath, projectRoot);
   } else if (ext === '.go') {

package/src/mcp/server-v2.js

@@ -7,9 +7,22 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
 const { SQLiteStore } = require('../store/sqlite-store');
+const { normalizeFileArg } = require('../store/path-utils');
 
 const projectRoot = process.cwd();
 
+// Process-level safety nets — Spec 7 Bug 5c. Without these, any error that
+// escapes the request handler (very rare, but possible from native bindings
+// or async stack frames) takes the whole MCP server down, and Claude Code /
+// Kiro surface `-32000 Failed to reconnect`. We log to stderr (which the
+// host logs but never terminates the JSON-RPC channel) and stay alive.
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[CARTO MCP] Uncaught exception: ${err && err.stack ? err.stack : err}\n`);
+});
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[CARTO MCP] Unhandled rejection: ${reason && reason.stack ? reason.stack : reason}\n`);
+});
+
 // Open SQLite directly — no re-indexing, instant startup
 let store = null;
 
@@ -17,8 +30,13 @@ function getStore() {
   if (store) return store;
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
   if (!fs.existsSync(dbPath)) return null;
-  store = new SQLiteStore(projectRoot);
-  store.open();
+  // Open BEFORE assigning to the module-scoped `store` so that if open()
+  // throws (corrupt DB, locked file, schema mismatch) we don't poison the
+  // cache with a broken instance — every subsequent call would otherwise
+  // return the broken object and never recover.
+  const s = new SQLiteStore(projectRoot);
+  s.open({ readonly: true }); // Spec 8 — defense in depth: MCP tools never write
+  store = s;
   return store;
 }
 
@@ -62,8 +80,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
-  const s = getStore();
-  if (!s) return notIndexed();
+  // Normalize file-arg tools to the canonical SQLite-stored form so
+  // `./lib/x.js`, absolute paths, and Windows separators all resolve.
+  // Tools that don't take a `file` arg are unaffected.
+  if (args && typeof args.file === 'string') {
+    args.file = normalizeFileArg(projectRoot, args.file);
+  }
+  // Wrap entire handler body so any tool error (SQLite, null deref, bad
+  // input) returns a structured error response instead of crashing the
+  // MCP transport — Spec 7 Bug 5 fix. Pre-2.0.7, an unhandled throw here
+  // killed the stdio connection and Claude Code/Kiro would surface
+  // `-32000 Failed to reconnect`.
+  try {
+    const s = getStore();
+    if (!s) return notIndexed();
 
   if (name === 'get_routes') {
     const routes = s.getRoutes();
@@ -105,6 +135,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_domain') {
+    // Guard: AI clients sometimes call this with no/empty `domain` arg.
+    // Pre-2.0.7 we'd then call args.domain.toUpperCase() on undefined and crash.
+    if (!args.domain || typeof args.domain !== 'string') {
+      return text('Missing required argument: domain. Use get_domains_list to see available domains.');
+    }
     const domain = s.getDomain(args.domain);
     if (!domain) return text(`Domain not found: ${args.domain}. Use get_domains_list to see available domains.`);
 
@@ -133,7 +168,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       models: domain.models.map(m => ({
         ...m,
         className: m.name,
-        fields: m.fields_json ? JSON.parse(m.fields_json) : []
+        // Wrap parse so one corrupt row doesn't take down the whole tool call.
+        fields: (() => {
+          if (!m.fields_json) return [];
+          try { return JSON.parse(m.fields_json); } catch { return []; }
+        })()
       })),
       functions: {},
       envVars: [],
@@ -446,6 +485,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   return text(`Unknown tool: ${name}`);
+  } catch (err) {
+    process.stderr.write(`[CARTO MCP] Tool "${name}" error: ${err.stack || err.message || err}\n`);
+    return {
+      content: [{ type: 'text', text: `Error in ${name}: ${err.message || String(err)}` }],
+      isError: true,
+    };
+  }
 });
 
 async function main() {

package/src/security/ignore.js

@@ -2,8 +2,11 @@ const fs = require('fs');
 const path = require('path');
 
 const DEFAULT_IGNORE_PATTERNS = [
+  // Env files
   '.env',
   '.env.*',
+
+  // Generic secret/credential name globs
   '*secret*',
   '*SECRET*',
   '*password*',
@@ -12,8 +15,60 @@ const DEFAULT_IGNORE_PATTERNS = [
   '*CREDENTIAL*',
   '*private_key*',
   '*PRIVATE_KEY*',
+
+  // Generic key/cert extensions
   '*.pem',
-  '*.key'
+  '*.key',
+
+  // SSH keys (no extension, won't be caught by *.key)
+  'id_rsa',
+  'id_rsa.pub',
+  'id_ed25519',
+  'id_ed25519.pub',
+  'id_ecdsa',
+  'id_ecdsa.pub',
+  'id_dsa',
+  'id_dsa.pub',
+  'authorized_keys',
+  'known_hosts',
+
+  // Package registry credentials
+  '.npmrc',
+  '.pypirc',
+  '.netrc',
+  '.pip/pip.conf',
+  '.gem/credentials',
+  '.cargo/credentials.toml',
+
+  // Cloud / K8s / Docker
+  'kubeconfig',
+  '*.kubeconfig',
+  '.docker/config.json',
+  '.dockercfg',
+  '*service-account*.json',
+  '*service_account*.json',
+  '*-credentials.json',
+  '.aws/credentials',
+  '.aws/config',
+  '.gcp/*',
+  '.gnupg/*',
+
+  // Cert / keystore formats (defense in depth — already excluded by CODE_EXTS today)
+  '*.crt',
+  '*.cer',
+  '*.p12',
+  '*.pfx',
+  '*.jks',
+  '*.keystore',
+  '*.pkcs12'
+
+  // NOTE: deliberately NOT including `*api_key*` / `*api-key*` globs.
+  // Real SaaS projects (cal.com, supabase, fastapi, zed) ship legitimate
+  // feature code under these filenames — `api_key.py`, `api-keys-service.ts`,
+  // `language_model/src/api_key.rs` — and a broad glob would silently delete
+  // 17+ files per repo from the import graph. Raw-credential files literally
+  // named `api_key.txt` are unusual; the realistic threat surface (.env,
+  // *credentials.json, .npmrc, id_rsa, kubeconfig, *secret*) is covered above.
 ];
 
 /**

package/src/store/path-utils.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * normalizeFileArg(projectRoot, fileArg) → string
+ *
+ * Convert a user-provided file path into the canonical form stored in the
+ * SQLite `files.path` column: relative-to-project-root, forward-slashed,
+ * no leading `./`.
+ *
+ * Handles every form a user / IDE / shell tab-completion realistically
+ * produces:
+ *   - relative form already correct          ("lib/application.js"   → "lib/application.js")
+ *   - leading "./"                           ("./lib/application.js" → "lib/application.js")
+ *   - leading "/" absolute under projectRoot ("/abs/.../lib/application.js" → "lib/application.js")
+ *   - Windows backslashes                    ("lib\\application.js"  → "lib/application.js")
+ *   - paths containing "../" (e.g. typed from a sibling dir) — resolved.
+ *
+ * Falsy / empty input returns the input unchanged so the caller's
+ * "missing argument" check still fires the same way.
+ */
+function normalizeFileArg(projectRoot, fileArg) {
+  if (typeof fileArg !== 'string' || fileArg.length === 0) return fileArg;
+
+  let p = fileArg;
+
+  // Normalize separators first so the absolute-path check works on Windows.
+  p = p.split('\\').join('/');
+
+  // Absolute → relative-to-project-root
+  if (path.isAbsolute(p) || /^[a-zA-Z]:\//.test(p)) {
+    p = path.relative(projectRoot, p);
+    p = p.split(path.sep).join('/');
+  }
+
+  // Strip leading "./" (or repeated "./././")
+  while (p.startsWith('./')) p = p.slice(2);
+
+  // Resolve any embedded "../" segments without going absolute.
+  // e.g. "src/foo/../bar.js" → "src/bar.js"
+  if (p.includes('/../') || p.startsWith('../')) {
+    const abs = path.resolve(projectRoot, p);
+    p = path.relative(projectRoot, abs).split(path.sep).join('/');
+  }
+
+  return p;
+}
+
+module.exports = { normalizeFileArg };

package/src/store/sqlite-store.js

@@ -6,6 +6,34 @@ const fs = require('fs');
 
 const SCHEMA_VERSION = '1';
 
+/**
+ * normalizePath(p) — Canonicalize a relative path for storage and query.
+ *
+ * Converts backslashes to forward slashes (Windows → POSIX), strips leading
+ * './', and rejects absolute paths (callers must `path.relative(projectRoot, p)`
+ * before passing in).
+ *
+ * Single-source-of-truth for "what does a row in `files.path` look like?".
+ * Apply this at every boundary that writes or queries the column, and every
+ * downstream join (imports.from_file_id → files.path) stays consistent.
+ *
+ * Cross-platform invariant: same code, same DB, same query results on macOS,
+ * Linux, and Windows. Closes Bug 2 (carto impact path normalization) and the
+ * Windows-only "0 dependents" failures in the Store adapter test suite.
+ */
+function normalizePath(p) {
+  if (typeof p !== 'string' || p.length === 0) return p;
+  let out = p;
+  // Backslash → forward slash (Windows → POSIX). path.sep is '\\' on Windows.
+  if (path.sep !== '/') out = out.split(path.sep).join('/');
+  // Some inputs may already use mixed separators (e.g., `src\utils/foo.js`).
+  // Normalize aggressively.
+  out = out.replace(/\\/g, '/');
+  // Strip leading './'
+  if (out.startsWith('./')) out = out.slice(2);
+  return out;
+}
+
 class SQLiteStore {
   constructor(projectRoot) {
     this._projectRoot = projectRoot;
@@ -13,14 +41,35 @@ class SQLiteStore {
   }
 
   /**
-   * open() — Opens or creates the database. Applies pragmas and schema.
+   * open(opts) — Opens or creates the database. Applies pragmas and schema.
+   *
+   * Options:
+   *   readonly  — Open the DB in read-only mode. Used by the MCP server
+   *               (`carto serve`) so a malformed/buggy tool can never write
+   *               through the SQLite layer. Skips mkdir, schema bootstrap, and
+   *               WAL pragma (WAL needs write capability and would otherwise
+   *               create `carto.db-wal`/`carto.db-shm` in repos that only run
+   *               the MCP server). Sets `fileMustExist: true` so a missing DB
+   *               returns a clear SQLite error instead of silently creating an
+   *               empty file in the wrong location.
    */
-  open() {
+  open(opts = {}) {
     const cartoDir = path.join(this._projectRoot, '.carto');
-    fs.mkdirSync(cartoDir, { recursive: true });
-
     const dbPath = path.join(cartoDir, 'carto.db');
 
+    if (opts.readonly) {
+      // Read-only path: dir must already exist (a writer process — `carto sync`
+      // or `carto init` — created the DB). Don't mkdir, don't ensure schema,
+      // don't apply write-only pragmas.
+      this._db = new Database(dbPath, { readonly: true, fileMustExist: true });
+      // Read-only safe pragmas only:
+      this._db.pragma('busy_timeout = 5000');
+      this._db.pragma('cache_size = -64000'); // 64MB cache
+      return this;
+    }
+
+    fs.mkdirSync(cartoDir, { recursive: true });
+
     try {
       this._db = new Database(dbPath);
     } catch (err) {
@@ -213,7 +262,7 @@ class SQLiteStore {
   // ─── File operations ───────────────────────────────────────────────────
 
   getFileByPath(relPath) {
-    return this._db.prepare('SELECT * FROM files WHERE path = ?').get(relPath);
+    return this._db.prepare('SELECT * FROM files WHERE path = ?').get(normalizePath(relPath));
   }
 
   getFileById(id) {
@@ -230,7 +279,8 @@ class SQLiteStore {
   }
 
   upsertFile(relPath, { language, hash, mtime, size }) {
-    const existing = this.getFileByPath(relPath);
+    const norm = normalizePath(relPath);
+    const existing = this.getFileByPath(norm);
     if (existing) {
       this._db.prepare(
         'UPDATE files SET language=?, hash=?, mtime=?, size=?, last_indexed_at=? WHERE id=?'
@@ -239,18 +289,18 @@ class SQLiteStore {
     }
     const info = this._db.prepare(
       'INSERT INTO files (path, language, hash, mtime, size, last_indexed_at) VALUES (?,?,?,?,?,?)'
-    ).run(relPath, language, hash, mtime, size, Date.now());
+    ).run(norm, language, hash, mtime, size, Date.now());
     return info.lastInsertRowid;
   }
 
   updateFileMtime(relPath, mtime, size) {
     this._db.prepare(
       'UPDATE files SET mtime=?, size=? WHERE path=?'
-    ).run(mtime, size, relPath);
+    ).run(mtime, size, normalizePath(relPath));
   }
 
   removeFile(relPath) {
-    this._db.prepare('DELETE FROM files WHERE path = ?').run(relPath);
+    this._db.prepare('DELETE FROM files WHERE path = ?').run(normalizePath(relPath));
   }
 
   removeStaleFiles(currentPaths) {
@@ -589,7 +639,12 @@ class SQLiteStore {
       },
       entryPoints,
       highImpact,
-      stack: stack ? JSON.parse(stack) : [],
+      // Defensive parse — a corrupt stack_json row must never crash callers.
+      // Spec 7 Bug 5f.
+      stack: (() => {
+        if (!stack) return [];
+        try { return JSON.parse(stack); } catch { return []; }
+      })(),
       domains
     };
   }
@@ -744,4 +799,4 @@ class SQLiteStore {
   }
 }
 
-module.exports = { SQLiteStore };
+module.exports = { SQLiteStore, normalizePath };

package/src/store/store-adapter.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { SQLiteStore } = require('./sqlite-store');
+const { runSyncV2 } = require('./sync-v2');
+
+/**
+ * StoreAdapter — V1-compatible API wrapping SQLiteStore.
+ * Drop-in replacement for the V1 Carto class in acp/session.js.
+ * tools.js calls the same methods with the same shapes.
+ */
+class StoreAdapter {
+  constructor() {
+    this._store = null;
+    this._projectRoot = null;
+  }
+
+  /**
+   * index(projectRoot, opts?)
+   * Opens the SQLite DB; runs runSyncV2 if DB is missing.
+   * opts.force — re-extract all files
+   * opts.writeOutputs — if false, skip AGENTS.md + context file generation (default: false)
+   */
+  async index(projectRoot, opts = {}) {
+    this._projectRoot = projectRoot;
+    const dbPath = path.join(projectRoot, '.carto', 'carto.db');
+    const dbExists = fs.existsSync(dbPath);
+
+    if (!dbExists || opts.force) {
+      await runSyncV2({
+        projectRoot,
+        output: opts.writeOutputs ? path.resolve(projectRoot, 'AGENTS.md') : null,
+      });
+    }
+
+    this._store = new SQLiteStore(projectRoot);
+    this._store.open();
+    return this.getMeta();
+  }
+
+  // ─── V1-shaped query API ────────────────────────────────────────────────
+
+  getMeta() {
+    const s = this._store.getStructure();
+    return s.meta || { totalFiles: 0, totalRoutes: 0, totalImportEdges: 0 };
+  }
+
+  getRoutes()           { return this._store.getRoutes(); }
+  searchRoutes(q)       { return this._store.searchRoutes(q); }
+  getModels(domain)     { return this._store.getModels(domain); }
+  getDomainsList()      { return this._store.getDomainsList(); }
+  getDomain(name)       { return this._store.getDomain(name); }
+  getCrossDomainDeps()  { return this._store.getCrossDomainDeps(); }
+  getHighImpactFiles(n) { return this._store.getHighImpactFiles(n); }
+
+  getStructure() {
+    return this._store.getStructure();
+  }
+
+  getNeighbors(file, hops = 1) {
+    return this._store.getNeighbors(file, hops);
+  }
+
+  /**
+   * getBlastRadius(file) — V1 rich shape:
+   *   { file, risk, directlyAffected, potentiallyAffected,
+   *     routesImpacted, domainsImpacted, dependentFiles }
+   */
+  getBlastRadius(file) {
+    const radius = this._store.getBlastRadius(file, 5);
+    if (!radius) return null;
+
+    const directDeps = radius.filter(r => r.hop_distance === 1).map(r => r.file);
+    const allDepFiles = radius.map(r => r.file);
+
+    // Routes impacted
+    const allRoutes = this._store.getRoutes();
+    const affectedSet = new Set([file, ...allDepFiles]);
+    const routesImpacted = allRoutes
+      .filter(r => affectedSet.has(r.file))
+      .map(r => {
+        const isAuth = /auth|login|session/i.test(r.path);
+        const isPay = /billing|payment|checkout/i.test(r.path);
+        const riskLevel = isAuth || isPay ? 'HIGH'
+          : directDeps.length >= 3 ? 'HIGH'
+          : directDeps.length >= 2 ? 'MEDIUM' : 'LOW';
+        return { method: r.method, path: r.path, risk: riskLevel };
+      });
+
+    // Domains impacted
+    const domainsImpacted = new Set();
+    const fileDomain = this._store.getDomainForFile(file);
+    if (fileDomain) domainsImpacted.add(fileDomain);
+    for (const f of allDepFiles) {
+      const d = this._store.getDomainForFile(f);
+      if (d) domainsImpacted.add(d);
+    }
+
+    const depCount = directDeps.length;
+    const risk = depCount >= 5 ? 'HIGH'
+      : depCount >= 3 ? 'HIGH'
+      : depCount >= 2 ? 'MEDIUM'
+      : depCount >= 1 ? 'LOW' : 'SAFE';
+
+    return {
+      file,
+      risk,
+      directlyAffected: { files: directDeps.length, domains: domainsImpacted.size },
+      potentiallyAffected: { files: allDepFiles.length, domains: domainsImpacted.size },
+      routesImpacted,
+      domainsImpacted: [...domainsImpacted],
+      dependentFiles: allDepFiles,
+    };
+  }
+
+  /**
+   * getContextForFile(file) — composed context matching V1 shape.
+   */
+  getContextForFile(file) {
+    const fileRow = this._store.getFileByPath(file);
+    if (!fileRow) return null;
+
+    const domain = this._store.getDomainForFile(file) || 'CORE';
+    const routes = this._store.getRoutes().filter(r => r.file === file).map(r => `${r.method} ${r.path}`);
+    const models = this._store.getModels().filter(m => m.file === file).map(m => m.name);
+    const blastRadius = this.getBlastRadius(file);
+    const neighbors = this.getNeighbors(file, 2);
+    const crossDomain = this._store.getCrossDomainDeps().filter(d => d.from === file || d.to === file);
+
+    let domainContext = null;
+    if (domain && this._projectRoot) {
+      const ctxPath = path.join(this._projectRoot, '.carto', 'context', `${domain}.md`);
+      try { domainContext = fs.readFileSync(ctxPath, 'utf-8'); } catch {}
+    }
+
+    return {
+      file,
+      domain,
+      routes,
+      models,
+      functions: [],
+      envVars: [],
+      blastRadius,
+      neighbors,
+      crossDomainDeps: crossDomain,
+      domainContext,
+      meta: {
+        importCount: 0,
+        dependentCount: blastRadius ? blastRadius.directlyAffected.files : 0,
+      },
+    };
+  }
+
+  close() {
+    if (this._store) { this._store.close(); this._store = null; }
+  }
+
+  /**
+   * terminate() — alias for close().
+   * Kept so the V1-style `Carto` export from index.js (which is now an alias
+   * for StoreAdapter) remains fully API-compatible. The V1 Carto class
+   * exposed terminate(); legacy programmatic users may still call it.
+   * Safe to remove in 3.0.0 along with the Carto alias.
+   */
+  terminate() { return this.close(); }
+}
+
+module.exports = { StoreAdapter };