@elkindev/dbgraph 1.0.0

package/dist/cli.js

@@ -0,0 +1,1827 @@
+#!/usr/bin/env node
+import {
+  DBGRAPH_VERSION,
+  NODE_KINDS,
+  capabilitiesFor,
+  formatDoctor,
+  formatExplore,
+  formatObject,
+  formatOutcome,
+  formatPrecheck,
+  getNeighbors,
+  noopLogger,
+  normalizeCatalog,
+  openConnections,
+  resolveProfile,
+  runPrecheck,
+  search
+} from "./chunk-PQBJ4PR5.js";
+import "./chunk-JN26WCE7.js";
+import {
+  ConfigError,
+  ConnectionError,
+  ConnectivityUnavailableError,
+  DbgraphError,
+  NotFoundError,
+  PermissionError,
+  UnsupportedDialectError
+} from "./chunk-TH4OVS4W.js";
+import "./chunk-CK6XTW3E.js";
+import "./chunk-2ESYSVXG.js";
+
+// src/cli/parse/args.ts
+var BOOLEAN_LONG_FLAGS = /* @__PURE__ */ new Set(["json", "full", "last", "quiet", "project"]);
+function parseArgv(argv) {
+  if (argv.length === 0) {
+    return { command: "", positionals: [], flags: {} };
+  }
+  const [commandToken, ...rest] = argv;
+  const command = commandToken ?? "";
+  const positionals = [];
+  const flags = {};
+  let i = 0;
+  while (i < rest.length) {
+    const token = rest[i];
+    if (token === void 0) {
+      i++;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const withoutDashes = token.slice(2);
+      const eqIdx = withoutDashes.indexOf("=");
+      if (eqIdx !== -1) {
+        const key = withoutDashes.slice(0, eqIdx);
+        const value = withoutDashes.slice(eqIdx + 1);
+        flags[key] = value;
+      } else if (BOOLEAN_LONG_FLAGS.has(withoutDashes)) {
+        flags[withoutDashes] = true;
+      } else {
+        const next = rest[i + 1];
+        if (next !== void 0 && !next.startsWith("-")) {
+          flags[withoutDashes] = next;
+          i++;
+        } else {
+          flags[withoutDashes] = true;
+        }
+      }
+    } else if (token.startsWith("-") && token.length === 2) {
+      const key = token.slice(1);
+      flags[key] = true;
+    } else {
+      positionals.push(token);
+    }
+    i++;
+  }
+  return { command, positionals, flags };
+}
+
+// src/cli/parse/detail.ts
+function parseDetail(raw) {
+  if (raw === void 0) {
+    return "normal";
+  }
+  if (raw === "brief" || raw === "normal" || raw === "full") {
+    return raw;
+  }
+  throw new ConfigError(
+    `explore: "detail" must be one of brief|normal|full (got "${String(raw)}")`
+  );
+}
+
+// src/cli/commands/init.ts
+import { writeFileSync, readFileSync, existsSync, appendFileSync } from "fs";
+import { join } from "path";
+
+// src/cli/config/build-config.ts
+var ENV_REF_RE = /^\$\{env:[A-Z_][A-Z0-9_]*\}$/;
+function isEnvRef(value) {
+  return ENV_REF_RE.test(value);
+}
+function requireEnvRef(field, value) {
+  if (!isEnvRef(value)) {
+    throw new ConfigError(
+      `Config: field "${field}" must be a \${env:VAR} reference, not a literal value. Use a generic variable name such as DBGRAPH_DB_${field.toUpperCase()}.`
+    );
+  }
+}
+function buildConfig(input) {
+  switch (input.dialect) {
+    case "sqlite": {
+      const source = { file: input.file };
+      const base = input.driver !== void 0 ? { dialect: "sqlite", source, driver: input.driver } : { dialect: "sqlite", source };
+      return base;
+    }
+    case "mssql": {
+      requireEnvRef("server", input.server);
+      requireEnvRef("database", input.database);
+      requireEnvRef("user", input.user);
+      requireEnvRef("password", input.password);
+      if (input.port !== void 0) requireEnvRef("port", input.port);
+      if (input.domain !== void 0) requireEnvRef("domain", input.domain);
+      const source = {
+        server: input.server,
+        database: input.database,
+        user: input.user,
+        password: input.password
+      };
+      if (input.port !== void 0) source.port = input.port;
+      if (input.domain !== void 0) source.domain = input.domain;
+      const cfg = { dialect: "mssql", source };
+      return cfg;
+    }
+  }
+}
+function writeConfig(cfg) {
+  const ordered = {
+    dialect: cfg.dialect,
+    source: buildOrderedSource(cfg)
+  };
+  if (cfg.levels !== void 0) {
+    ordered["levels"] = cfg.levels;
+  }
+  if (cfg.dialect === "sqlite" && cfg.driver !== void 0) {
+    ordered["driver"] = cfg.driver;
+  }
+  return JSON.stringify(ordered, null, 2) + "\n";
+}
+function buildOrderedSource(cfg) {
+  if (cfg.dialect === "sqlite") {
+    return { file: cfg.source.file };
+  }
+  if (cfg.dialect === "pg") {
+    const src2 = cfg.source;
+    const ordered2 = {
+      host: src2.host,
+      database: src2.database,
+      user: src2.user,
+      password: src2.password
+    };
+    if (src2.port !== void 0) ordered2["port"] = src2.port;
+    if (src2.ssl !== void 0) ordered2["ssl"] = src2.ssl;
+    if (src2.schema !== void 0) ordered2["schema"] = src2.schema;
+    return ordered2;
+  }
+  if (cfg.dialect === "mysql") {
+    const src2 = cfg.source;
+    const ordered2 = {
+      host: src2.host,
+      database: src2.database,
+      user: src2.user,
+      password: src2.password
+    };
+    if (src2.port !== void 0) ordered2["port"] = src2.port;
+    if (src2.ssl !== void 0) ordered2["ssl"] = src2.ssl;
+    return ordered2;
+  }
+  if (cfg.dialect === "mongodb") {
+    const src2 = cfg.source;
+    const ordered2 = {
+      uri: src2.uri,
+      database: src2.database
+    };
+    if (src2.sampleSize !== void 0) ordered2["sampleSize"] = src2.sampleSize;
+    if (src2.tls !== void 0) ordered2["tls"] = src2.tls;
+    return ordered2;
+  }
+  const src = cfg.source;
+  const ordered = {
+    server: src.server,
+    database: src.database,
+    user: src.user,
+    password: src.password
+  };
+  if (src.port !== void 0) ordered["port"] = src.port;
+  if (src.domain !== void 0) ordered["domain"] = src.domain;
+  return ordered;
+}
+
+// src/cli/init/wizard.ts
+import * as readline from "readline";
+var ENV_REF_RE2 = /^\$\{env:[A-Z_][A-Z0-9_]*\}$/;
+function isEnvRef2(value) {
+  return ENV_REF_RE2.test(value);
+}
+var LineReader = class {
+  _iter;
+  _out;
+  constructor(rl, out) {
+    this._iter = rl[Symbol.asyncIterator]();
+    this._out = out;
+  }
+  /** Write a prompt to the output writable */
+  prompt(text) {
+    this._out.write(text);
+  }
+  /**
+   * Read the next line from the underlying stream.
+   * Returns null when the stream ends (EOF).
+   */
+  async nextLine() {
+    const { value, done } = await this._iter.next();
+    if (done === true || value === void 0) {
+      return null;
+    }
+    return value.trim();
+  }
+  /**
+   * Ask a question: write the prompt label then read the next line.
+   */
+  async ask(label) {
+    this.prompt(label);
+    const line = await this.nextLine();
+    return line ?? "";
+  }
+  /**
+   * Ask for a connection-identity field that MUST be a ${env:VAR} reference.
+   * Re-prompts on literal values with a rejection message.
+   * When isSecret is true, the prompt label is written but NO echo happens
+   * (readline was created with terminal:false, so readline itself never echoes).
+   */
+  async askEnvRef(field, exampleVar, isSecret = false) {
+    while (true) {
+      const label = isSecret ? `  ${field} [hidden, enter \${env:VAR}]: ` : `  ${field} (e.g. \${env:${exampleVar}}): `;
+      this.prompt(label);
+      const line = await this.nextLine();
+      const value = line ?? "";
+      if (isEnvRef2(value)) {
+        if (isSecret) {
+          this.prompt("\n");
+        }
+        return value;
+      }
+      this.prompt(
+        `  [!] "${field}" must be a \${env:VAR} reference, not a literal value.
+      Example: \${env:${exampleVar}}
+`
+      );
+    }
+  }
+  /**
+   * Ask whether to include an object type and at what level.
+   * Returns null when user declines. Defaults to 'full' on empty/invalid input.
+   */
+  async askLevel(kind) {
+    const include = await this.ask(`  Include "${kind}" objects? [y/n]: `);
+    if (include.toLowerCase().startsWith("n")) {
+      return null;
+    }
+    const levelRaw = await this.ask(
+      `  Level for "${kind}" [off/metadata/full, default: full]: `
+    );
+    const level = levelRaw === "" ? "full" : levelRaw;
+    if (level === "off" || level === "metadata" || level === "full") {
+      return level;
+    }
+    return "full";
+  }
+};
+async function runWizard(options = {}) {
+  const inputStream = options.input ?? process.stdin;
+  const outputStream = options.output ?? process.stdout;
+  const rl = readline.createInterface({
+    input: inputStream,
+    output: outputStream,
+    terminal: false
+  });
+  const reader = new LineReader(rl, outputStream);
+  try {
+    reader.prompt("dbgraph interactive init\n\n");
+    const dialectRaw = await reader.ask("Dialect [sqlite/mssql]: ");
+    const dialect = dialectRaw.toLowerCase();
+    if (dialect !== "sqlite" && dialect !== "mssql") {
+      throw new Error(`Unknown dialect: "${dialectRaw}". Supported: sqlite, mssql.`);
+    }
+    const matrix = options.capabilitiesOverride ?? capabilitiesFor(dialect);
+    const supportedKinds = [...matrix.supported];
+    if (dialect === "sqlite") {
+      const file = await reader.ask("SQLite file path: ");
+      reader.prompt("\nObject types (based on SQLite capabilities):\n");
+      const levels = {};
+      for (const kind of supportedKinds) {
+        const level = await reader.askLevel(kind);
+        if (level !== null) {
+          levels[kind] = level;
+        }
+      }
+      return {
+        dialect: "sqlite",
+        file,
+        offeredKinds: supportedKinds,
+        levels
+      };
+    } else {
+      reader.prompt("\nMSSQL connection (all fields must be ${env:VAR} references):\n");
+      const server = await reader.askEnvRef("server", "DBGRAPH_DB_SERVER");
+      const database = await reader.askEnvRef("database", "DBGRAPH_DB_NAME");
+      const user = await reader.askEnvRef("user", "DBGRAPH_DB_USER");
+      const password = await reader.askEnvRef("password", "DBGRAPH_DB_PASSWORD", true);
+      const portRaw = await reader.ask("  port (leave empty to skip): ");
+      const port = portRaw === "" ? void 0 : portRaw;
+      const domainRaw = await reader.ask("  domain (leave empty to skip): ");
+      const domain = domainRaw === "" ? void 0 : domainRaw;
+      reader.prompt("\nObject types (based on MSSQL capabilities):\n");
+      const levels = {};
+      for (const kind of supportedKinds) {
+        const level = await reader.askLevel(kind);
+        if (level !== null) {
+          levels[kind] = level;
+        }
+      }
+      const result = {
+        dialect: "mssql",
+        server,
+        database,
+        user,
+        password,
+        offeredKinds: supportedKinds,
+        levels
+      };
+      if (port !== void 0) result.port = port;
+      if (domain !== void 0) result.domain = domain;
+      return result;
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// src/cli/sync/incremental.ts
+function computeDelta(existing, fresh) {
+  const existingById = /* @__PURE__ */ new Map();
+  for (const node of existing) {
+    existingById.set(node.id, node.bodyHash);
+  }
+  const freshIds = /* @__PURE__ */ new Set();
+  const toUpsert = [];
+  for (const node of fresh) {
+    freshIds.add(node.id);
+    const existingHash = existingById.get(node.id);
+    if (existingHash === void 0) {
+      toUpsert.push(node);
+    } else if (existingHash !== node.bodyHash) {
+      toUpsert.push(node);
+    }
+  }
+  const toDelete = [];
+  for (const [id] of existingById) {
+    if (!freshIds.has(id)) {
+      toDelete.push(id);
+    }
+  }
+  return { toDelete, toUpsert };
+}
+
+// src/cli/commands/sync.ts
+import { randomUUID } from "crypto";
+async function runSync(options) {
+  const { adapter, store, full } = options;
+  const logger = options.logger ?? noopLogger;
+  const liveFingerprint = await adapter.fingerprint();
+  const snapshots = await store.listSnapshots();
+  const lastSnapshot = snapshots.length > 0 ? snapshots[0] : null;
+  const storedFingerprint = lastSnapshot?.fingerprint ?? null;
+  if (!full && storedFingerprint !== null && storedFingerprint === liveFingerprint) {
+    logger.info("extraction skipped");
+    return {
+      mode: "skipped",
+      counts: {},
+      upserted: 0,
+      deleted: 0,
+      hasDrift: false,
+      snapshotId: "",
+      fingerprint: liveFingerprint
+    };
+  }
+  const hasDrift = storedFingerprint !== null && storedFingerprint !== liveFingerprint;
+  logger.info("extract started");
+  const scope = {
+    levels: adapter.capabilities.defaultLevels
+  };
+  const rawCatalog = await adapter.extract(scope);
+  const normResult = normalizeCatalog(rawCatalog, scope);
+  const freshNodes = normResult.graph.nodes;
+  const existingNodes = await getAllNodes(store);
+  const delta = computeDelta(existingNodes, freshNodes);
+  const upserted = delta.toUpsert.length;
+  const deleted = delta.toDelete.length;
+  if (delta.toDelete.length > 0) {
+    await store.deleteNodes(delta.toDelete);
+  }
+  if (delta.toUpsert.length > 0) {
+    await store.upsertGraph({
+      nodes: delta.toUpsert,
+      edges: normResult.graph.edges
+    });
+  }
+  logger.info("delta computed", { upserted, deleted });
+  const counts = buildCounts(freshNodes);
+  const snapshot = {
+    id: randomUUID(),
+    takenAt: (/* @__PURE__ */ new Date()).toISOString(),
+    engine: adapter.dialect,
+    fingerprint: liveFingerprint,
+    counts
+  };
+  await store.putSnapshot(snapshot);
+  logger.info("snapshot written", { id: snapshot.id });
+  return {
+    mode: full ? "full" : "incremental",
+    counts,
+    upserted,
+    deleted,
+    hasDrift,
+    snapshotId: snapshot.id,
+    fingerprint: liveFingerprint
+  };
+}
+async function getAllNodes(store) {
+  const results = await Promise.all(
+    NODE_KINDS.map((kind) => store.getNodesByKind(kind))
+  );
+  return results.flatMap((arr) => arr);
+}
+function buildCounts(nodes) {
+  const counts = {};
+  for (const node of nodes) {
+    counts[node.kind] = (counts[node.kind] ?? 0) + 1;
+  }
+  return counts;
+}
+
+// src/cli/log/console-logger.ts
+var LEVEL_RANK = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+function createConsoleLogger(opts) {
+  const write = opts?.write ?? ((t) => {
+    process.stderr.write(t);
+  });
+  const minLevel = opts?.level ?? "info";
+  const minRank = LEVEL_RANK[minLevel];
+  function emit(level, msg, meta) {
+    if (LEVEL_RANK[level] < minRank) return;
+    const metaPart = meta !== void 0 ? ` ${JSON.stringify(meta)}` : "";
+    write(`[${level}] ${msg}${metaPart}
+`);
+  }
+  return {
+    debug: (msg, meta) => emit("debug", msg, meta),
+    info: (msg, meta) => emit("info", msg, meta),
+    warn: (msg, meta) => emit("warn", msg, meta),
+    error: (msg, meta) => emit("error", msg, meta)
+  };
+}
+
+// src/cli/format/sync.ts
+var LABEL_WIDTH = 13;
+var KIND_WIDTH = 12;
+function formatSyncSummary(view) {
+  const lines = [];
+  lines.push("Sync Summary");
+  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  if (view.mode === "skipped") {
+    lines.push("  already up to date \u2014 no changes since last snapshot");
+    lines.push(`  ${"fingerprint".padEnd(LABEL_WIDTH)}${view.fingerprint}`);
+    lines.push("");
+    return lines.join("\n") + "\n";
+  }
+  lines.push(`  ${"mode".padEnd(LABEL_WIDTH)}${view.mode}`);
+  lines.push("  counts:");
+  const kinds = Object.keys(view.counts).sort();
+  if (kinds.length === 0) {
+    lines.push("    (none)");
+  } else {
+    for (const kind of kinds) {
+      const count = view.counts[kind] ?? 0;
+      lines.push(`    ${kind.padEnd(KIND_WIDTH)} ${count}`);
+    }
+  }
+  lines.push(`  ${"upserted".padEnd(LABEL_WIDTH)}${view.upserted}`);
+  lines.push(`  ${"deleted".padEnd(LABEL_WIDTH)}${view.deleted}`);
+  lines.push(`  ${"snapshot".padEnd(LABEL_WIDTH)}${view.snapshotId}`);
+  lines.push(`  ${"fingerprint".padEnd(LABEL_WIDTH)}${view.fingerprint}`);
+  lines.push("");
+  if (view.hasDrift) {
+    lines.push("DRIFT RESOLVED \u2014 source schema had changed since the previous snapshot.");
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+
+// src/cli/commands/init.ts
+var GITIGNORE_ENTRY = ".dbgraph/";
+function ensureGitignored(projectRoot) {
+  const gitignorePath = join(projectRoot, ".gitignore");
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    const lines = content.split("\n").map((l) => l.trim());
+    if (lines.includes(GITIGNORE_ENTRY)) {
+      return;
+    }
+    const suffix = content.endsWith("\n") ? "" : "\n";
+    appendFileSync(gitignorePath, `${suffix}${GITIGNORE_ENTRY}
+`, "utf-8");
+  } else {
+    writeFileSync(gitignorePath, `${GITIGNORE_ENTRY}
+`, "utf-8");
+  }
+}
+async function syncAfterInit(projectRoot) {
+  const logger = createConsoleLogger({ level: "info" });
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const summary = await runSync({ adapter, store, full: false, logger });
+    process.stdout.write(formatSyncSummary(summary));
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+function wizardResultToBuildInput(result) {
+  if (result.dialect === "sqlite") {
+    return { dialect: "sqlite", file: result.file };
+  }
+  const base = {
+    dialect: "mssql",
+    server: result.server,
+    database: result.database,
+    user: result.user,
+    password: result.password
+  };
+  const mssql = base;
+  if (result.port !== void 0) mssql.port = result.port;
+  if (result.domain !== void 0) mssql.domain = result.domain;
+  return mssql;
+}
+async function runInit(options) {
+  const { projectRoot } = options;
+  let buildInput;
+  if ("interactive" in options && options.interactive === true) {
+    const wizardOpts = {};
+    if (options.wizardInput !== void 0) wizardOpts.input = options.wizardInput;
+    if (options.wizardOutput !== void 0) wizardOpts.output = options.wizardOutput;
+    if (options.capabilitiesOverride !== void 0) {
+      wizardOpts.capabilitiesOverride = options.capabilitiesOverride;
+    }
+    const wizardResult = await runWizard(wizardOpts);
+    buildInput = wizardResultToBuildInput(wizardResult);
+  } else {
+    const opts = options;
+    if (opts.dialect === "sqlite") {
+      buildInput = {
+        dialect: "sqlite",
+        file: opts.file,
+        ...opts.driver !== void 0 ? { driver: opts.driver } : {}
+      };
+    } else {
+      buildInput = {
+        dialect: "mssql",
+        server: opts.server,
+        database: opts.database,
+        user: opts.user,
+        password: opts.password,
+        ...opts.port !== void 0 ? { port: opts.port } : {},
+        ...opts.domain !== void 0 ? { domain: opts.domain } : {}
+      };
+    }
+  }
+  const config = buildConfig(buildInput);
+  const configString = writeConfig(config);
+  const configPath = join(projectRoot, "dbgraph.config.json");
+  writeFileSync(configPath, configString, "utf-8");
+  ensureGitignored(projectRoot);
+  const syncFn = options._syncFn ?? syncAfterInit;
+  await syncFn(projectRoot);
+  return { type: "success" };
+}
+
+// src/cli/format/status.ts
+function formatStatus(view) {
+  const lines = [];
+  lines.push("Graph");
+  lines.push("\u2500\u2500\u2500\u2500\u2500");
+  const kinds = Object.keys(view.kindCounts).sort();
+  if (kinds.length === 0) {
+    lines.push("  (empty \u2014 run sync first)");
+  } else {
+    for (const kind of kinds) {
+      const count = view.kindCounts[kind] ?? 0;
+      lines.push(`  ${kind.padEnd(14)} ${count}`);
+    }
+  }
+  if (view.excludedCount > 0) {
+    lines.push(`  excluded        ${view.excludedCount}`);
+  }
+  lines.push("");
+  lines.push("Last Snapshot");
+  lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  if (view.lastSnapshot === null) {
+    lines.push("  never synced \u2014 run: dbgraph sync");
+  } else {
+    const snap = view.lastSnapshot;
+    lines.push(`  taken        ${snap.takenAt}`);
+    lines.push(`  engine       ${snap.engine}`);
+    lines.push(`  fingerprint  ${snap.fingerprint}`);
+    const snapKinds = Object.keys(snap.counts).sort();
+    if (snapKinds.length > 0) {
+      lines.push("  counts:");
+      for (const kind of snapKinds) {
+        const count = snap.counts[kind] ?? 0;
+        lines.push(`    ${kind.padEnd(12)} ${count}`);
+      }
+    }
+  }
+  lines.push("");
+  if (view.hasDrift) {
+    lines.push("DRIFT DETECTED \u2014 source schema has changed since last sync.");
+    lines.push("  Run: dbgraph sync");
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+
+// src/cli/commands/status.ts
+async function runStatus(options) {
+  const { adapter, store } = options;
+  const allNodeArrays = await Promise.all(
+    NODE_KINDS.map((kind) => store.getNodesByKind(kind))
+  );
+  const allNodes = allNodeArrays.flatMap((arr) => arr);
+  const kindCounts = {};
+  let excludedCount = 0;
+  for (const node of allNodes) {
+    if (node.missing || node.excluded) {
+      excludedCount++;
+    } else {
+      kindCounts[node.kind] = (kindCounts[node.kind] ?? 0) + 1;
+    }
+  }
+  const snapshots = await store.listSnapshots();
+  const lastSnapshot = snapshots.length > 0 ? snapshots[0] ?? null : null;
+  const liveFp = await adapter.fingerprint();
+  const hasDrift = lastSnapshot !== null && liveFp !== lastSnapshot.fingerprint;
+  const view = {
+    kindCounts,
+    lastSnapshot,
+    excludedCount,
+    hasDrift
+  };
+  const output = formatStatus(view);
+  return { type: "success", output };
+}
+
+// src/cli/format/query.ts
+function formatQueryText(view) {
+  const lines = [];
+  if (view.hits.length === 0) {
+    lines.push(`No results for "${view.term}".`);
+  } else {
+    lines.push(`Results for "${view.term}" (${view.total} found):`);
+    lines.push("");
+    for (const hit of view.hits) {
+      lines.push(`  ${hit.kind.padEnd(14)} ${hit.qname}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n") + "\n";
+}
+function formatQueryJson(view) {
+  const payload = {
+    term: view.term,
+    total: view.total,
+    hits: view.hits.map((h) => ({
+      kind: h.kind,
+      qname: h.qname,
+      id: h.id,
+      score: h.score
+    }))
+  };
+  return JSON.stringify(payload, null, 2) + "\n";
+}
+
+// src/cli/commands/query.ts
+async function runQuery(options) {
+  const { store, term, json } = options;
+  const result = await search(store, { term });
+  const view = {
+    term,
+    hits: result.hits,
+    total: result.total
+  };
+  const output = json ? formatQueryJson(view) : formatQueryText(view);
+  if (result.hits.length === 0) {
+    return { type: "negative", output };
+  }
+  return { type: "success", output };
+}
+
+// src/cli/commands/explore.ts
+async function runExplore(options) {
+  const { store, qname, detail } = options;
+  const matches = [];
+  for (const kind of NODE_KINDS) {
+    const found = await store.getNodeByQName(kind, qname);
+    if (found !== null) matches.push(found);
+  }
+  const real = matches.filter((n) => !n.missing);
+  const effective = real.length > 0 ? real : matches;
+  const node = effective[0] ?? null;
+  if (node === null) {
+    throw new NotFoundError("entity", qname);
+  }
+  const neighbors = await getNeighbors(store, { nodeId: node.id });
+  const view = { node, neighbors };
+  const output = formatExplore(view, detail);
+  return { type: "success", output };
+}
+
+// src/cli/commands/object.ts
+async function runObject(options) {
+  const { store, qname, detail } = options;
+  const matches = [];
+  for (const kind of NODE_KINDS) {
+    const found = await store.getNodeByQName(kind, qname);
+    if (found !== null) matches.push(found);
+  }
+  const real = matches.filter((n) => !n.missing);
+  const effective = real.length > 0 ? real : matches;
+  const node = effective[0] ?? null;
+  if (node === null) {
+    throw new NotFoundError("entity", qname);
+  }
+  const neighbors = await getNeighbors(store, { nodeId: node.id });
+  const view = { node, neighbors };
+  const output = formatObject(view, detail);
+  return { type: "success", output };
+}
+
+// src/cli/diff/engine.ts
+function diffManifests(a, b) {
+  const mapA = /* @__PURE__ */ new Map();
+  for (const row of a) {
+    mapA.set(row.nodeId, row);
+  }
+  const mapB = /* @__PURE__ */ new Map();
+  for (const row of b) {
+    mapB.set(row.nodeId, row);
+  }
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [nodeId, rowB] of mapB) {
+    const rowA = mapA.get(nodeId);
+    if (rowA === void 0) {
+      added.push({
+        nodeId,
+        kind: rowB.kind,
+        qname: rowB.qname,
+        bodyHash: rowB.bodyHash
+      });
+    } else if (rowA.bodyHash !== rowB.bodyHash) {
+      changed.push({
+        nodeId,
+        kind: rowB.kind,
+        qname: rowB.qname,
+        oldBodyHash: rowA.bodyHash,
+        newBodyHash: rowB.bodyHash
+      });
+    }
+  }
+  for (const [nodeId, rowA] of mapA) {
+    if (!mapB.has(nodeId)) {
+      removed.push({
+        nodeId,
+        kind: rowA.kind,
+        qname: rowA.qname,
+        bodyHash: rowA.bodyHash
+      });
+    }
+  }
+  return { added, removed, changed };
+}
+
+// src/cli/format/diff.ts
+function formatDiff(result) {
+  const { added, removed, changed } = result;
+  if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+    return "No changes detected.\n";
+  }
+  const lines = [];
+  if (added.length > 0) {
+    lines.push("ADDED");
+    lines.push("\u2500\u2500\u2500\u2500\u2500");
+    const sorted = [...added].sort(compareByKindThenQname);
+    for (const row of sorted) {
+      lines.push(`  + ${row.kind.padEnd(14)} ${row.qname}`);
+    }
+    lines.push("");
+  }
+  if (removed.length > 0) {
+    lines.push("REMOVED");
+    lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    const sorted = [...removed].sort(compareByKindThenQname);
+    for (const row of sorted) {
+      lines.push(`  - ${row.kind.padEnd(14)} ${row.qname}`);
+    }
+    lines.push("");
+  }
+  if (changed.length > 0) {
+    lines.push("MODIFIED");
+    lines.push("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    const sorted = [...changed].sort(compareByKindThenQname);
+    for (const row of sorted) {
+      const what = describeChange(row);
+      lines.push(`  ~ ${row.kind.padEnd(14)} ${row.qname}`);
+      lines.push(`      ${what}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n") + "\n";
+}
+function formatDiffNoManifest(snapA, snapB) {
+  return `No per-object manifest found for snapshots "${snapA}" / "${snapB}".
+These snapshots were recorded before the v2 schema index.
+Run: dbgraph sync to record a new snapshot, then diff again.
+`;
+}
+function compareByKindThenQname(a, b) {
+  const kindCmp = a.kind.localeCompare(b.kind);
+  return kindCmp !== 0 ? kindCmp : a.qname.localeCompare(b.qname);
+}
+function describeChange(row) {
+  const oldHash = row.oldBodyHash ?? "(null)";
+  const newHash = row.newBodyHash ?? "(null)";
+  return `definition changed (hash: ${oldHash.slice(0, 8)}\u2026 \u2192 ${newHash.slice(0, 8)}\u2026)`;
+}
+
+// src/cli/commands/diff.ts
+async function runDiff(options) {
+  const { store, last } = options;
+  let snapAId;
+  let snapBId;
+  if (last === true) {
+    const snapshots = await store.listSnapshots();
+    if (snapshots.length < 2) {
+      return {
+        type: "negative",
+        output: "Not enough snapshots for diff. Need at least two syncs.\n"
+      };
+    }
+    const len = snapshots.length;
+    snapAId = snapshots[len - 2].id;
+    snapBId = snapshots[len - 1].id;
+  } else {
+    if (options.snapA === void 0 || options.snapB === void 0) {
+      return {
+        type: "negative",
+        output: "Usage: dbgraph diff <snapA> <snapB>  |  dbgraph diff --last\n"
+      };
+    }
+    snapAId = options.snapA;
+    snapBId = options.snapB;
+  }
+  const [manifestA, manifestB] = await Promise.all([
+    store.getSnapshotObjects(snapAId),
+    store.getSnapshotObjects(snapBId)
+  ]);
+  if (manifestA.length === 0 || manifestB.length === 0) {
+    return {
+      type: "negative",
+      output: formatDiffNoManifest(snapAId, snapBId)
+    };
+  }
+  const diffResult = diffManifests(manifestA, manifestB);
+  const hasChanges = diffResult.added.length > 0 || diffResult.removed.length > 0 || diffResult.changed.length > 0;
+  const output = formatDiff(diffResult);
+  return {
+    type: hasChanges ? "negative" : "success",
+    output
+  };
+}
+
+// src/cli/commands/affected.ts
+import { readFileSync as readFileSync2 } from "fs";
+async function runAffected(options) {
+  const { store, sqlFile, json = false } = options;
+  const detail = options.detail ?? "normal";
+  const ddl = readFileSync2(sqlFile, "utf-8");
+  const view = await runPrecheck(store, ddl);
+  const hasImpact = view.matchedObjects.length > 0;
+  const outcomeType = hasImpact ? "negative" : "success";
+  let output;
+  if (json) {
+    output = JSON.stringify(view, null, 2) + "\n";
+  } else {
+    output = formatPrecheck(view, detail);
+  }
+  return { type: outcomeType, output };
+}
+
+// src/cli/commands/install.ts
+import { win32 as pathWin32, posix as pathPosix } from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync } from "fs";
+import { dirname } from "path";
+var realFsSeam = {
+  readFile(path) {
+    return readFileSync3(path, "utf-8");
+  },
+  writeFile(path, content) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync2(path, content, "utf-8");
+  },
+  exists(path) {
+    return existsSync2(path);
+  }
+};
+var MCP_ENTRY_NAME = "dbgraph-mcp";
+var CLAUDE_CONFIG_FILE = "claude_desktop_config.json";
+function resolveConfigPath(platform, env) {
+  if (platform === "win32") {
+    const appData = env["APPDATA"];
+    if (appData === void 0 || appData === "") return void 0;
+    return pathWin32.join(appData, "Claude", CLAUDE_CONFIG_FILE);
+  }
+  const home = env["HOME"];
+  if (home === void 0 || home === "") return void 0;
+  return pathPosix.join(home, ".config", "Claude", CLAUDE_CONFIG_FILE);
+}
+function resolveProjectConfigPath(platform, cwd, segs) {
+  return platform === "win32" ? pathWin32.join(cwd, ...segs) : pathPosix.join(cwd, ...segs);
+}
+function mergeMcpConfig(config, entry) {
+  const existing = config;
+  const servers = existing.mcpServers ?? {};
+  const current = servers[MCP_ENTRY_NAME];
+  if (current !== void 0 && current.command === entry.command && JSON.stringify(current.args) === JSON.stringify(entry.args)) {
+    return config;
+  }
+  return {
+    ...existing,
+    mcpServers: {
+      ...servers,
+      [MCP_ENTRY_NAME]: entry
+    }
+  };
+}
+function removeMcpConfig(config) {
+  const existing = config;
+  const servers = existing.mcpServers;
+  if (servers === void 0 || servers[MCP_ENTRY_NAME] === void 0) {
+    return config;
+  }
+  const { [MCP_ENTRY_NAME]: _removed, ...remaining } = servers;
+  void _removed;
+  return {
+    ...existing,
+    mcpServers: Object.keys(remaining).length === 0 ? void 0 : remaining
+  };
+}
+function homeRoot(platform, env) {
+  if (platform === "win32") {
+    const up = env["USERPROFILE"];
+    if (up === void 0 || up === "") return void 0;
+    return up;
+  }
+  const home = env["HOME"];
+  if (home === void 0 || home === "") return void 0;
+  return home;
+}
+function mergeMcpText(content, entry) {
+  let config;
+  try {
+    config = JSON.parse(content);
+  } catch {
+    config = {};
+  }
+  const updated = mergeMcpConfig(config, entry);
+  if (updated === config) return content;
+  return JSON.stringify(updated, null, 2) + "\n";
+}
+function removeMcpText(content) {
+  let config;
+  try {
+    config = JSON.parse(content);
+  } catch {
+    config = {};
+  }
+  const updated = removeMcpConfig(config);
+  if (updated === config) return content;
+  return JSON.stringify(updated, null, 2) + "\n";
+}
+function mergeVsCodeConfig(config, entry) {
+  const existing = config;
+  const servers = existing.servers ?? {};
+  const current = servers[MCP_ENTRY_NAME];
+  if (current !== void 0 && current.type === "stdio" && current.command === entry.command && JSON.stringify(current.args) === JSON.stringify(entry.args)) {
+    return config;
+  }
+  return {
+    ...existing,
+    servers: {
+      ...servers,
+      [MCP_ENTRY_NAME]: { type: "stdio", command: entry.command, args: entry.args }
+    }
+  };
+}
+function removeVsCodeConfig(config) {
+  const existing = config;
+  const servers = existing.servers;
+  if (servers === void 0 || servers[MCP_ENTRY_NAME] === void 0) {
+    return config;
+  }
+  const { [MCP_ENTRY_NAME]: _removed, ...remaining } = servers;
+  void _removed;
+  return {
+    ...existing,
+    servers: Object.keys(remaining).length === 0 ? void 0 : remaining
+  };
+}
+function mergeVsCodeText(content, entry) {
+  let config;
+  try {
+    config = JSON.parse(content);
+  } catch {
+    config = {};
+  }
+  const updated = mergeVsCodeConfig(config, entry);
+  if (updated === config) return content;
+  return JSON.stringify(updated, null, 2) + "\n";
+}
+function removeVsCodeText(content) {
+  let config;
+  try {
+    config = JSON.parse(content);
+  } catch {
+    config = {};
+  }
+  const updated = removeVsCodeConfig(config);
+  if (updated === config) return content;
+  return JSON.stringify(updated, null, 2) + "\n";
+}
+function mergeOpenCodeConfig(config, entry) {
+  const existing = config;
+  const mcp = existing.mcp ?? {};
+  const derivedCommand = [entry.command, ...entry.args];
+  const current = mcp[MCP_ENTRY_NAME];
+  if (current !== void 0 && current.type === "local" && JSON.stringify(current.command) === JSON.stringify(derivedCommand)) {
+    return config;
+  }
+  return {
+    ...existing,
+    mcp: {
+      ...mcp,
+      [MCP_ENTRY_NAME]: { type: "local", command: derivedCommand }
+    }
+  };
+}
+function removeOpenCodeConfig(config) {
+  const existing = config;
+  const mcp = existing.mcp;
+  if (mcp === void 0 || mcp[MCP_ENTRY_NAME] === void 0) {
+    return config;
+  }
+  const { [MCP_ENTRY_NAME]: _removed, ...remaining } = mcp;
+  void _removed;
+  return {
+    ...existing,
+    mcp: Object.keys(remaining).length === 0 ? void 0 : remaining
+  };
+}
+function mergeOpenCodeText(content, entry) {
+  let config;
+  try {
+    config = JSON.parse(content);
+  } catch {
+    config = {};
+  }
+  const updated = mergeOpenCodeConfig(config, entry);
+  if (updated === config) return content;
+  return JSON.stringify(updated, null, 2) + "\n";
+}
+function removeOpenCodeText(content) {
+  let config;
+  try {
+    config = JSON.parse(content);
+  } catch {
+    config = {};
+  }
+  const updated = removeOpenCodeConfig(config);
+  if (updated === config) return content;
+  return JSON.stringify(updated, null, 2) + "\n";
+}
+var CODEX_RENDER = '[mcp_servers.dbgraph-mcp]\ncommand = "npx"\nargs = ["-y", "dbgraph-mcp"]';
+var CODEX_HEADER = "[mcp_servers.dbgraph-mcp]";
+function findCodexHeaderLine(lines) {
+  return lines.findIndex((l) => l === CODEX_HEADER);
+}
+function findCodexBlockEnd(lines, headerIdx) {
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (/^\s*\[/.test(line)) {
+      return i;
+    }
+  }
+  return lines.length;
+}
+function mergeCodexToml(content) {
+  const lines = content.split("\n");
+  const hadTrailingNewline = content.endsWith("\n") || content === "";
+  const workLines = hadTrailingNewline && lines[lines.length - 1] === "" ? lines.slice(0, -1) : [...lines];
+  const headerIdx = findCodexHeaderLine(workLines);
+  if (headerIdx === -1) {
+    const renderLines2 = CODEX_RENDER.split("\n");
+    if (workLines.length === 0 || workLines.length === 1 && workLines[0] === "") {
+      return CODEX_RENDER + "\n";
+    }
+    const result2 = [...workLines, "", ...renderLines2, ""];
+    return result2.join("\n");
+  }
+  const blockEndIdx = findCodexBlockEnd(workLines, headerIdx);
+  const blockLines = workLines.slice(headerIdx, blockEndIdx);
+  const currentBlock = blockLines.join("\n");
+  if (currentBlock === CODEX_RENDER) {
+    return content;
+  }
+  const renderLines = CODEX_RENDER.split("\n");
+  const before = workLines.slice(0, headerIdx);
+  const after = workLines.slice(blockEndIdx);
+  const result = [...before, ...renderLines, ...after, ""];
+  return result.join("\n");
+}
+function removeCodexToml(content) {
+  if (content === "") return "";
+  const lines = content.split("\n");
+  const hadTrailingNewline = content.endsWith("\n");
+  const workLines = hadTrailingNewline && lines[lines.length - 1] === "" ? lines.slice(0, -1) : [...lines];
+  const headerIdx = findCodexHeaderLine(workLines);
+  if (headerIdx === -1) {
+    return content;
+  }
+  const blockEndIdx = findCodexBlockEnd(workLines, headerIdx);
+  const before = workLines.slice(0, headerIdx);
+  const after = workLines.slice(blockEndIdx);
+  const combined = [...before, ...after];
+  const collapsed = [];
+  let prevBlank = false;
+  for (const line of combined) {
+    const isBlank = line.trim() === "";
+    if (isBlank && prevBlank) continue;
+    collapsed.push(line);
+    prevBlank = isBlank;
+  }
+  while (collapsed.length > 0 && (collapsed[0] ?? "").trim() === "") {
+    collapsed.shift();
+  }
+  if (collapsed.length === 0) {
+    return "\n";
+  }
+  while (collapsed.length > 0 && (collapsed[collapsed.length - 1] ?? "").trim() === "") {
+    collapsed.pop();
+  }
+  return collapsed.join("\n") + "\n";
+}
+var AGENT_TABLE = [
+  {
+    id: "claude-code",
+    displayName: "Claude Code",
+    format: "mcpServers",
+    // Project scope (US-038): <cwd>/.mcp.json — LIVE-verified 2026-07-06.
+    projectPath: [".mcp.json"],
+    resolvePath(platform, env) {
+      return resolveConfigPath(platform, env);
+    },
+    merge(content, entry) {
+      return mergeMcpText(content, entry);
+    },
+    remove(content) {
+      return removeMcpText(content);
+    }
+  },
+  {
+    id: "cursor",
+    displayName: "Cursor",
+    format: "mcpServers",
+    // Project scope (US-038): <cwd>/.cursor/mcp.json — LIVE-verified 2026-07-06.
+    projectPath: [".cursor", "mcp.json"],
+    resolvePath(platform, env) {
+      const root = homeRoot(platform, env);
+      if (root === void 0) return void 0;
+      return platform === "win32" ? pathWin32.join(root, ".cursor", "mcp.json") : pathPosix.join(root, ".cursor", "mcp.json");
+    },
+    merge(content, entry) {
+      return mergeMcpText(content, entry);
+    },
+    remove(content) {
+      return removeMcpText(content);
+    }
+  },
+  {
+    id: "gemini",
+    displayName: "Gemini CLI",
+    format: "mcpServers",
+    // Project scope (US-038): <cwd>/.gemini/settings.json — LIVE-verified 2026-07-06.
+    projectPath: [".gemini", "settings.json"],
+    resolvePath(platform, env) {
+      const root = homeRoot(platform, env);
+      if (root === void 0) return void 0;
+      return platform === "win32" ? pathWin32.join(root, ".gemini", "settings.json") : pathPosix.join(root, ".gemini", "settings.json");
+    },
+    merge(content, entry) {
+      return mergeMcpText(content, entry);
+    },
+    remove(content) {
+      return removeMcpText(content);
+    }
+  },
+  {
+    id: "vscode",
+    displayName: "VS Code",
+    format: "vscode",
+    // Project scope (US-038): <cwd>/.vscode/mcp.json — LIVE-verified 2026-07-06.
+    projectPath: [".vscode", "mcp.json"],
+    resolvePath(platform, env) {
+      const root = homeRoot(platform, env);
+      if (root === void 0) return void 0;
+      return platform === "win32" ? pathWin32.join(root, ".vscode", "mcp.json") : pathPosix.join(root, ".vscode", "mcp.json");
+    },
+    merge(content, entry) {
+      return mergeVsCodeText(content, entry);
+    },
+    remove(content) {
+      return removeVsCodeText(content);
+    }
+  },
+  {
+    id: "opencode",
+    displayName: "opencode",
+    format: "opencode",
+    // Project scope (US-038): <cwd>/opencode.json — LIVE-verified 2026-07-06.
+    // NOTE: project location is the repo-root opencode.json (NOT ~/.config/opencode).
+    projectPath: ["opencode.json"],
+    resolvePath(platform, env) {
+      const root = homeRoot(platform, env);
+      if (root === void 0) return void 0;
+      return platform === "win32" ? pathWin32.join(root, ".config", "opencode", "opencode.json") : pathPosix.join(root, ".config", "opencode", "opencode.json");
+    },
+    merge(content, entry) {
+      return mergeOpenCodeText(content, entry);
+    },
+    remove(content) {
+      return removeOpenCodeText(content);
+    }
+  },
+  {
+    id: "codex",
+    displayName: "Codex CLI",
+    format: "codex-toml",
+    // Project scope (US-038, Decision #5): <cwd>/.codex/config.toml — LIVE-verified
+    // 2026-07-06. Reuses the SAME mergeCodexToml writer as global; the project file is
+    // TRUST-GATED (the project must be trusted in ~/.codex/config.toml), so the codex
+    // summary line carries a trust-caveat suffix (see runInstall project branch).
+    projectPath: [".codex", "config.toml"],
+    resolvePath(platform, env) {
+      const root = homeRoot(platform, env);
+      if (root === void 0) return void 0;
+      return platform === "win32" ? pathWin32.join(root, ".codex", "config.toml") : pathPosix.join(root, ".codex", "config.toml");
+    },
+    merge(content, entry) {
+      void entry;
+      return mergeCodexToml(content);
+    },
+    remove(content) {
+      return removeCodexToml(content);
+    }
+  }
+];
+var MANUAL_SNIPPET = `No supported MCP agent config was detected.
+
+Supported agents: Claude Code, Cursor, Gemini CLI, VS Code, opencode, Codex CLI.
+
+To install dbgraph manually, add the following to your agent's MCP configuration:
+
+  For Claude Code, Cursor, and Gemini CLI (mcpServers JSON):
+  {
+    "mcpServers": {
+      "dbgraph-mcp": {
+        "command": "npx",
+        "args": ["-y", "dbgraph-mcp"]
+      }
+    }
+  }
+
+  For VS Code (servers JSON):
+  {
+    "servers": {
+      "dbgraph-mcp": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "dbgraph-mcp"]
+      }
+    }
+  }
+
+  For opencode (mcp JSON):
+  {
+    "mcp": {
+      "dbgraph-mcp": {
+        "type": "local",
+        "command": ["npx", "-y", "dbgraph-mcp"]
+      }
+    }
+  }
+
+  For Codex CLI (TOML, ~/.codex/config.toml):
+  [mcp_servers.dbgraph-mcp]
+  command = "npx"
+  args = ["-y", "dbgraph-mcp"]
+
+Config file locations:
+  Claude Code  \u2014 Windows: %APPDATA%\\Claude\\claude_desktop_config.json
+                 Linux/macOS: ~/.config/Claude/claude_desktop_config.json
+  Cursor       \u2014 ~/.cursor/mcp.json
+  Gemini CLI   \u2014 ~/.gemini/settings.json
+  VS Code      \u2014 ~/.vscode/mcp.json
+  opencode     \u2014 ~/.config/opencode/opencode.json
+  Codex CLI    \u2014 ~/.codex/config.toml
+`;
+var DEFAULT_MCP_ENTRY = {
+  command: "npx",
+  args: ["-y", "dbgraph-mcp"]
+};
+var CODEX_PROJECT_TRUST_SUFFIX = " (requires trusted project: set trust_level in ~/.codex/config.toml)";
+function projectSummaryLine(id, action) {
+  if (action === "unsupported") {
+    return `${id} \u2192 not supported with --project
+`;
+  }
+  const verb = action === "installed" ? "written" : action === "removed" ? "removed" : action === "already" ? "already present" : "absent";
+  const suffix = id === "codex" && action === "installed" ? CODEX_PROJECT_TRUST_SUFFIX : "";
+  return `${id} \u2192 ${verb}${suffix}
+`;
+}
+async function runInstall(options = {}) {
+  const {
+    remove = false,
+    project = false,
+    cwd = process.cwd(),
+    fs: fsSeam = realFsSeam,
+    platform = process.platform,
+    env = process.env,
+    write = (text) => process.stdout.write(text),
+    agents = AGENT_TABLE
+  } = options;
+  const results = [];
+  for (const row of agents) {
+    if (project) {
+      if (row.projectPath === void 0) {
+        results.push({ agent: row.id, action: "unsupported" });
+        continue;
+      }
+      const configPath = resolveProjectConfigPath(platform, cwd, row.projectPath);
+      const fileExists = fsSeam.exists(configPath);
+      if (!fileExists && remove) {
+        results.push({ agent: row.id, action: "absent", path: configPath });
+        continue;
+      }
+      let raw;
+      if (!fileExists) {
+        raw = "";
+      } else {
+        try {
+          raw = fsSeam.readFile(configPath);
+        } catch {
+          raw = row.format === "codex-toml" ? "" : "{}";
+        }
+      }
+      const next = remove ? row.remove(raw) : row.merge(raw, DEFAULT_MCP_ENTRY);
+      if (next === raw) {
+        results.push({ agent: row.id, action: remove ? "absent" : "already", path: configPath });
+      } else {
+        fsSeam.writeFile(configPath, next);
+        results.push({ agent: row.id, action: remove ? "removed" : "installed", path: configPath });
+      }
+    } else {
+      const configPath = row.resolvePath(platform, env);
+      if (configPath === void 0) {
+        results.push({ agent: row.id, action: "skipped" });
+        continue;
+      }
+      if (!fsSeam.exists(configPath)) {
+        results.push({ agent: row.id, action: "absent" });
+        continue;
+      }
+      let raw;
+      try {
+        raw = fsSeam.readFile(configPath);
+      } catch {
+        raw = row.format === "codex-toml" ? "" : "{}";
+      }
+      const next = remove ? row.remove(raw) : row.merge(raw, DEFAULT_MCP_ENTRY);
+      if (next === raw) {
+        results.push({ agent: row.id, action: remove ? "absent" : "already", path: configPath });
+      } else {
+        fsSeam.writeFile(configPath, next);
+        results.push({ agent: row.id, action: remove ? "removed" : "installed", path: configPath });
+      }
+    }
+  }
+  if (project) {
+    for (const r of results) {
+      write(projectSummaryLine(r.agent, r.action));
+    }
+  } else {
+    const allSkippedOrAbsent = results.every(
+      (r) => r.action === "skipped" || r.action === "absent"
+    );
+    if (allSkippedOrAbsent) {
+      write(MANUAL_SNIPPET);
+    } else {
+      for (const r of results) {
+        if (r.action !== "skipped" && r.action !== "absent") {
+          const row = agents.find((t) => t.id === r.agent);
+          const name = row?.displayName ?? r.agent;
+          write(`${name} \u2192 ${r.action}${r.path !== void 0 ? ` (${r.path})` : ""}
+`);
+        }
+      }
+    }
+  }
+  return { type: "success" };
+}
+
+// src/cli/commands/doctor.ts
+var UNAVAILABLE_PROBE = {
+  nativeDriver: false,
+  cliTools: [],
+  odbc: false
+};
+async function runDoctor(deps) {
+  const { engine, probe } = deps;
+  let probeResult;
+  try {
+    probeResult = await probe();
+  } catch {
+    probeResult = UNAVAILABLE_PROBE;
+  }
+  const { resolvedProfile, chosenStrategy } = resolveProfileAndStrategy(engine, probeResult);
+  const view = {
+    engine,
+    nativeDriver: probeResult.nativeDriver,
+    cliTools: probeResult.cliTools,
+    odbc: probeResult.odbc,
+    resolvedProfile,
+    chosenStrategy
+  };
+  return formatDoctor(view);
+}
+function resolveProfileAndStrategy(engine, probe) {
+  if (engine === "mssql") {
+    const profile = resolveProfile(probe);
+    const profileName = `${profile.variant}@${profile.versionRange}`;
+    let chosenStrategy;
+    const sqlcmdTool = probe.cliTools.find((t) => t.tool === "sqlcmd");
+    if (sqlcmdTool?.path !== null && sqlcmdTool?.path !== void 0) {
+      chosenStrategy = "sqlcmd";
+    } else if (probe.odbc) {
+      chosenStrategy = "odbc";
+    } else if (probe.nativeDriver) {
+      chosenStrategy = "native-tedious";
+    } else {
+      chosenStrategy = "unavailable";
+    }
+    return { resolvedProfile: profileName, chosenStrategy };
+  }
+  if (engine === "pg") {
+    const chosenStrategy = probe.nativeDriver ? "native-pg" : "unavailable";
+    return { resolvedProfile: "n/a", chosenStrategy };
+  }
+  if (engine === "mysql") {
+    const chosenStrategy = probe.nativeDriver ? "native-mysql2" : "unavailable";
+    return { resolvedProfile: "n/a", chosenStrategy };
+  }
+  if (engine === "sqlite") {
+    const chosenStrategy = probe.nativeDriver ? "native-sqlite" : "unavailable";
+    return { resolvedProfile: "n/a", chosenStrategy };
+  }
+  return { resolvedProfile: "unknown@any", chosenStrategy: "unavailable" };
+}
+
+// src/cli/dispatch.ts
+function buildLogger(args) {
+  const quiet = args.flags["quiet"] === true || args.flags["q"] === true;
+  return createConsoleLogger({ level: quiet ? "warn" : "info" });
+}
+async function handleInit(args) {
+  const projectRoot = process.cwd();
+  if (args.flags["i"] === true || args.flags["interactive"] === true) {
+    return runInit({ projectRoot, interactive: true });
+  }
+  const dialect = typeof args.flags["dialect"] === "string" ? args.flags["dialect"] : "";
+  if (dialect === "sqlite") {
+    const file = typeof args.flags["file"] === "string" ? args.flags["file"] : "";
+    const driver = args.flags["driver"];
+    return runInit({
+      projectRoot,
+      dialect: "sqlite",
+      file,
+      ...driver === "better-sqlite3" || driver === "node:sqlite" ? { driver } : {}
+    });
+  }
+  if (dialect === "mssql") {
+    const server = typeof args.flags["server"] === "string" ? args.flags["server"] : "";
+    const database = typeof args.flags["database"] === "string" ? args.flags["database"] : "";
+    const user = typeof args.flags["user"] === "string" ? args.flags["user"] : "";
+    const password = typeof args.flags["password"] === "string" ? args.flags["password"] : "";
+    const port = typeof args.flags["port"] === "string" ? args.flags["port"] : void 0;
+    const domain = typeof args.flags["domain"] === "string" ? args.flags["domain"] : void 0;
+    return runInit({
+      projectRoot,
+      dialect: "mssql",
+      server,
+      database,
+      user,
+      password,
+      ...port !== void 0 ? { port } : {},
+      ...domain !== void 0 ? { domain } : {}
+    });
+  }
+  return runInit({ projectRoot, interactive: true });
+}
+async function handleSync(args) {
+  const full = args.flags["full"] === true;
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const summary = await runSync({ adapter, store, full, logger });
+    process.stdout.write(formatSyncSummary(summary));
+    return { type: "success" };
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+async function handleStatus(args) {
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const result = await runStatus({ adapter, store });
+    process.stdout.write(result.output);
+    return { type: "success" };
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+async function handleQuery(args) {
+  const term = args.positionals[0] ?? "";
+  const json = args.flags["json"] === true;
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const result = await runQuery({ store, term, json });
+    process.stdout.write(result.output);
+    return result;
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+async function handleExplore(args) {
+  const qname = args.positionals[0] ?? "";
+  const detail = parseDetail(args.flags["detail"]);
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const result = await runExplore({ store, qname, detail });
+    process.stdout.write(result.output);
+    return { type: "success" };
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+async function handleObject(args) {
+  const qname = args.positionals[0] ?? "";
+  const detail = parseDetail(args.flags["detail"]);
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const result = await runObject({ store, qname, detail });
+    process.stdout.write(result.output);
+    return { type: "success" };
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+async function handleAffected(args) {
+  const sqlFile = args.positionals[0] ?? "";
+  if (sqlFile === "") {
+    throw new Error("dbgraph affected: <script.sql> argument is required");
+  }
+  const json = args.flags["json"] === true;
+  const detail = parseDetail(args.flags["detail"]);
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    const result = await runAffected({ store, sqlFile, json, detail });
+    process.stdout.write(result.output);
+    return result;
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+async function handleInstall(args) {
+  const remove = args.flags["remove"] === true;
+  const project = args.flags["project"] === true;
+  await runInstall({ remove, project, cwd: process.cwd(), fs: realFsSeam });
+  return { type: "success" };
+}
+async function handleDoctor(_args) {
+  const projectRoot = process.cwd();
+  let engine = "mssql";
+  try {
+    const { readFileSync: readFileSync4 } = await import("fs");
+    const { join: join2 } = await import("path");
+    const { parseConfig } = await import("./parse-config-5TLAZCR3.js");
+    const configPath = join2(projectRoot, "dbgraph.config.json");
+    const rawJson = JSON.parse(readFileSync4(configPath, "utf-8"));
+    const cfg = parseConfig(rawJson);
+    engine = cfg.dialect;
+  } catch {
+  }
+  const probe = await buildProbe(engine);
+  const output = await runDoctor({ engine, probe });
+  process.stdout.write(output);
+  return { type: "success" };
+}
+async function buildProbe(engine) {
+  try {
+    const barrel = await import("./src-5YCYYWGV.js");
+    if (engine === "mssql") {
+      const probe = new barrel.MssqlCapabilityProbe();
+      return () => probe.probe();
+    }
+    if (engine === "pg") {
+      const probe = new barrel.PgCapabilityProbe();
+      return () => probe.probe();
+    }
+    if (engine === "mysql") {
+      const probe = new barrel.MysqlCapabilityProbe();
+      return () => probe.probe();
+    }
+    if (engine === "sqlite") {
+      const probe = new barrel.SqliteCapabilityProbe();
+      return () => probe.probe();
+    }
+  } catch {
+  }
+  return async () => ({
+    nativeDriver: false,
+    cliTools: [],
+    odbc: false
+  });
+}
+async function handleDiff(args) {
+  const last = args.flags["last"] === true;
+  const projectRoot = process.cwd();
+  const logger = buildLogger(args);
+  const { adapter, store } = await openConnections(projectRoot, logger);
+  try {
+    let result;
+    if (last) {
+      result = await runDiff({ store, last: true });
+    } else {
+      const snapA = args.positionals[0] ?? "";
+      const snapB = args.positionals[1] ?? "";
+      result = await runDiff({ store, snapA, snapB });
+    }
+    process.stdout.write(result.output);
+    return result;
+  } finally {
+    await adapter.close();
+    await store.close();
+  }
+}
+var COMMAND_TABLE = {
+  init: handleInit,
+  sync: handleSync,
+  status: handleStatus,
+  query: handleQuery,
+  explore: handleExplore,
+  object: handleObject,
+  diff: handleDiff,
+  affected: handleAffected,
+  install: handleInstall,
+  doctor: handleDoctor
+};
+function dispatch(command) {
+  const handler = COMMAND_TABLE[command];
+  if (handler !== void 0) {
+    return { type: "handler", handler };
+  }
+  return { type: "unknown", command };
+}
+
+// src/cli/exit-code.ts
+function exitCodeFor(input) {
+  if (input instanceof DbgraphError) {
+    if (input instanceof PermissionError) return 3;
+    if (input instanceof UnsupportedDialectError) return 4;
+    if (input instanceof ConnectionError) return 2;
+    return 2;
+  }
+  const typed = input;
+  switch (typed.type) {
+    case "success":
+      return 0;
+    case "negative":
+      return 1;
+    case "unknownCommand":
+      return 2;
+  }
+}
+
+// src/cli/cli.ts
+import { pathToFileURL } from "url";
+var USAGE_TEXT = `
+dbgraph \u2014 database schema graph indexer
+
+Usage: dbgraph <command> [options]
+
+Commands:
+  init      Initialize the graph index for a database
+  sync      Synchronize the graph index with the database
+  status    Show the current state of the graph index
+  query     Search the graph index for a term
+  explore   Explore a node and its neighbors in the graph
+  object    Show one object in full (columns, constraints, indexes, triggers)
+  diff      Compare two snapshots of the graph index
+  affected  Analyze DDL to show impacted objects (--json for machine output)
+  install   Wire dbgraph-mcp into supported MCP agents (--project for project scope, --remove to undo)
+  doctor    Run a content-free connectivity self-test (safe to share)
+  mcp       Serve the MCP tools over stdio (default) or Streamable HTTP (--http)
+
+Options:
+  --help, -h       Show this help text
+  --version, -v    Print the dbgraph version and exit
+
+Run "dbgraph <command> --help" for command-specific options.
+`.trim();
+async function runCli(argv) {
+  const parsed = parseArgv(argv);
+  if (parsed.command === "--help" || parsed.command === "-h" || parsed.flags["help"] === true || parsed.flags["h"] === true) {
+    process.stdout.write(USAGE_TEXT + "\n");
+    return 0;
+  }
+  if (parsed.command === "--version" || parsed.command === "-v" || parsed.flags["version"] === true || parsed.flags["v"] === true) {
+    process.stdout.write((process.env["DBGRAPH_BUILD_VERSION"] ?? DBGRAPH_VERSION) + "\n");
+    return 0;
+  }
+  const dispatchResult = dispatch(parsed.command);
+  if (dispatchResult.type === "unknown") {
+    process.stderr.write(`Unknown command: "${parsed.command}"
+
+${USAGE_TEXT}
+`);
+    return exitCodeFor({ type: "unknownCommand", command: parsed.command });
+  }
+  try {
+    const outcome = await dispatchResult.handler(parsed);
+    return exitCodeFor(outcome);
+  } catch (err) {
+    if (err instanceof ConnectivityUnavailableError) {
+      process.stderr.write(formatOutcome(err.outcome) + "\n");
+      return exitCodeFor(err);
+    }
+    if (err instanceof DbgraphError) {
+      process.stderr.write(`Error: ${err.message}
+`);
+      return exitCodeFor(err);
+    }
+    throw err;
+  }
+}
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  runCli(process.argv.slice(2)).then((code) => {
+    process.exit(code);
+  }).catch((err) => {
+    console.error("Unexpected error:", err);
+    process.exit(2);
+  });
+}
+export {
+  USAGE_TEXT,
+  runCli
+};