seer-mcp 0.1.0

package/src/bundle/ci.ts

@@ -0,0 +1,141 @@
+import fs from 'fs';
+import path from 'path';
+import { Store } from '../db/store.js';
+import { Indexer } from '../indexer/index.js';
+import { exportBundle, ExportResult } from './export.js';
+import type { DiscoveryMode } from '../indexer/discovery.js';
+
+export interface CiBuildOptions {
+  /** Repo root to index. Required. */
+  repoRoot: string;
+  /** Where to write the bundle. Defaults to `<repoRoot>/.seer/index.seerbundle`. */
+  out?: string;
+  /** Discovery mode for the index pass. CI defaults to `'standard'`. */
+  mode?: DiscoveryMode;
+  /** Wipe any existing DB before the indexing pass. CI defaults to `true`. */
+  reset?: boolean;
+  /** Pass through to the indexer's `parallel` toggle. */
+  parallel?: boolean;
+  /** Optional gitHead/gitBranch overrides (CI runners frequently know them). */
+  gitHead?: string;
+  gitBranch?: string;
+  /** Pin manifest.builtAt for reproducible bundles (defaults to Date.now()). */
+  builtAt?: number;
+  /** Logger. */
+  log?: (msg: string) => void;
+}
+
+export interface CiBuildResult {
+  /** Result of the indexing pass (file/symbol counts). */
+  index: {
+    filesIndexed: number;
+    symbols: number;
+    edges: number;
+    elapsedMs: number;
+  };
+  /** Result of the bundle export. */
+  bundle: ExportResult;
+  totalElapsedMs: number;
+}
+
+/**
+ * One-call CI pipeline: fresh-index a repo, export the result as a portable
+ * bundle, and report both phases. Exits with a non-zero status if either
+ * phase fails — wired up in the CLI command's caller.
+ */
+export async function buildCiBundle(options: CiBuildOptions): Promise<CiBuildResult> {
+  const start = Date.now();
+  const log = options.log ?? ((msg: string) => process.stdout.write(`${msg}\n`));
+  const repoRoot = path.resolve(options.repoRoot);
+  if (!fs.existsSync(repoRoot)) {
+    throw new Error(`Repo not found: ${repoRoot}`);
+  }
+  const dbPath = path.join(repoRoot, '.seer', 'graph.db');
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+
+  // CI mode wipes the DB by default — every pipeline run should be a clean
+  // snapshot, not an incremental update over whatever junk was on the runner.
+  const reset = options.reset ?? true;
+  if (reset && fs.existsSync(dbPath)) {
+    fs.unlinkSync(dbPath);
+    for (const sfx of ['-wal', '-shm']) {
+      try { fs.unlinkSync(dbPath + sfx); } catch { /* */ }
+    }
+  }
+
+  log(`[ci] Indexing ${repoRoot}...`);
+  const store = new Store(dbPath);
+  const indexer = new Indexer(store);
+  let indexResult;
+  try {
+    indexResult = await indexer.indexDirectory(repoRoot, {
+      mode: options.mode ?? 'standard',
+      parallel: options.parallel,
+      quiet: true,
+    });
+  } finally {
+    store.close();
+  }
+  log(`[ci] Indexed ${indexResult.filesIndexed} files, ${indexResult.symbols} symbols, ${indexResult.edges} edges in ${indexResult.elapsedMs}ms`);
+
+  log(`[ci] Exporting bundle...`);
+  const bundle = await exportBundle(dbPath, repoRoot, {
+    out: options.out,
+    log: (m) => log(`  ${m}`),
+    gitHead: options.gitHead,
+    gitBranch: options.gitBranch,
+    builtAt: options.builtAt,
+  });
+  log(`[ci] Wrote ${bundle.bundlePath} (${bundle.bytes.toLocaleString()} bytes) in ${bundle.elapsedMs}ms`);
+
+  return {
+    index: {
+      filesIndexed: indexResult.filesIndexed,
+      symbols: indexResult.symbols,
+      edges: indexResult.edges,
+      elapsedMs: indexResult.elapsedMs,
+    },
+    bundle,
+    totalElapsedMs: Date.now() - start,
+  };
+}
+
+/**
+ * Emit a ready-to-paste GitHub Actions workflow that runs the CI bundle
+ * pipeline on every push to main and uploads the resulting bundle as a
+ * build artifact. The workflow is self-contained — no per-repo edits
+ * required beyond dropping it at `.github/workflows/seer-bundle.yml`.
+ */
+export function workflowTemplate(): string {
+  return [
+    "name: Seer bundle",
+    "",
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "  workflow_dispatch:",
+    "",
+    "jobs:",
+    "  build:",
+    "    runs-on: ubuntu-latest",
+    "    permissions:",
+    "      contents: read",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0   # full history so symbol-history pass works",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: '22'",
+    "      - run: npm ci",
+    "      - run: npm run build",
+    "      - name: Build Seer bundle",
+    "        run: node dist/cli/index.js ci bundle --workspace ${{ github.workspace }} --out seer-index.seerbundle",
+    "      - uses: actions/upload-artifact@v4",
+    "        with:",
+    "          name: seer-index",
+    "          path: seer-index.seerbundle",
+    "          if-no-files-found: error",
+    "",
+  ].join('\n');
+}

package/src/bundle/contract.ts

@@ -0,0 +1,387 @@
+/**
+ * v10 — Contract Diff between two `.seerbundle` artifacts.
+ *
+ * Goal: deterministically compute the change set in the API/service surface
+ * exposed by an indexed repo, treating the bundle as the source of truth.
+ * The diff is ADVISORY — exit code is always 0 even when breaking changes
+ * appear. Seer-Core does not gate CI.
+ *
+ * Comparison happens at the protocol-aware "endpoint" level:
+ *   - HTTP: key = `${method}|${path}`, framework recorded
+ *   - tRPC: key = `trpc|${operation}` (method = 'query' / 'mutation' / 'subscription')
+ *   - GraphQL: key = `graphql|${operation}`
+ *   - gRPC: key = `grpc|${service}.${operation}`
+ *   - Messaging (kafka/sqs/sns/rabbitmq/nats/redis_pubsub):
+ *       key = `${protocol}|${topic|queue|exchange}`
+ *
+ * Output:
+ *   - added[]
+ *   - removed[]
+ *   - changed[] (key matched; surfaced field differs — handler, framework,
+ *     metadata, service)
+ *   - optionally affectedCallers[] when both bundles include service-link
+ *     evidence (caller symbol qualifiedName / file).
+ *
+ * Deterministic ordering: every list is sorted by (protocol, key) ASC.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import zlib from 'zlib';
+import { BUNDLE_MAGIC, BUNDLE_FORMAT_VERSION, BundleManifest } from './format.js';
+import { Store } from '../db/store.js';
+
+export interface ContractEndpoint {
+  protocol: string;
+  /** Stable identity key for this endpoint within its protocol. */
+  key: string;
+  method: string | null;
+  path: string | null;
+  framework: string | null;
+  handlerName: string | null;
+  operation: string | null;
+  topic: string | null;
+  queue: string | null;
+  exchange: string | null;
+  service: string | null;
+}
+
+export interface AffectedCaller {
+  callerQualifiedName: string | null;
+  callerFile: string | null;
+  callerLine: number | null;
+  /** Where the caller is referenced — either 'old' or 'new' bundle. */
+  source: 'old' | 'new';
+}
+
+export interface ContractChange {
+  protocol: string;
+  key: string;
+  before: ContractEndpoint;
+  after: ContractEndpoint;
+  /** Field names whose value differs between before/after. */
+  changedFields: string[];
+}
+
+export interface ContractDiff {
+  oldBundle: { path: string; gitHead: string | null; rosterHash: string };
+  newBundle: { path: string; gitHead: string | null; rosterHash: string };
+  /** Per-protocol totals on both sides, for sanity. */
+  totals: {
+    old: number;
+    new: number;
+    added: number;
+    removed: number;
+    changed: number;
+  };
+  added: Array<ContractEndpoint & { affectedCallers?: AffectedCaller[] }>;
+  removed: Array<ContractEndpoint & { affectedCallers?: AffectedCaller[] }>;
+  changed: Array<ContractChange & { affectedCallers?: AffectedCaller[] }>;
+  /** True when the affected-callers section is non-empty for at least one row. */
+  affectedCallersAvailable: boolean;
+}
+
+/**
+ * Open a bundle's payload as a read-only Store (decompressed to a temp file).
+ * Returns the Store plus a cleanup() function the caller MUST invoke.
+ */
+async function openBundleStore(bundlePath: string): Promise<{
+  store: Store; manifest: BundleManifest; cleanup: () => void;
+}> {
+  if (!fs.existsSync(bundlePath)) {
+    throw new Error(`No bundle at ${bundlePath}`);
+  }
+  const fileBuf = fs.readFileSync(bundlePath);
+  if (fileBuf.length < 12 || !fileBuf.subarray(0, 4).equals(BUNDLE_MAGIC)) {
+    throw new Error(`Not a Seer bundle: ${bundlePath} (bad magic)`);
+  }
+  const formatVersion = fileBuf.readUInt32BE(4);
+  if (formatVersion > BUNDLE_FORMAT_VERSION) {
+    throw new Error(`Bundle format v${formatVersion} is newer than this build (v${BUNDLE_FORMAT_VERSION}). Upgrade Seer.`);
+  }
+  const manifestLen = fileBuf.readUInt32BE(8);
+  const manifestEnd = 12 + manifestLen;
+  if (manifestLen <= 0 || manifestEnd > fileBuf.length) {
+    throw new Error(`Bundle truncated: ${bundlePath} (manifest length ${manifestLen} exceeds file size)`);
+  }
+  const manifest = JSON.parse(fileBuf.slice(12, manifestEnd).toString('utf-8')) as BundleManifest;
+  const dbBuf = zlib.gunzipSync(fileBuf.slice(manifestEnd));
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'seer-contractdiff-'));
+  const dbPath = path.join(tmpDir, 'bundle.db');
+  fs.writeFileSync(dbPath, dbBuf);
+  const store = Store.openReadOnly(dbPath);
+  return {
+    store, manifest,
+    cleanup: () => {
+      try { store.close(); } catch { /* */ }
+      try { fs.unlinkSync(dbPath); fs.rmdirSync(tmpDir); } catch { /* */ }
+    },
+  };
+}
+
+/**
+ * Build the "contract surface" — one entry per route — from a bundle Store.
+ * Stable key:
+ *   - HTTP    → `http|${method}|${path}`
+ *   - tRPC    → `trpc|${operation}`
+ *   - GraphQL → `graphql|${operation}`
+ *   - gRPC    → `grpc|${service}.${operation}`
+ *   - Messaging → `${protocol}|${topic|queue|exchange}`
+ */
+export function collectContractSurface(store: Store): Map<string, ContractEndpoint> {
+  const surface = new Map<string, ContractEndpoint>();
+  const rows = store.listRoutes({ limit: 1_000_000 });
+  for (const r of rows) {
+    const protocol = r.protocol ?? 'http';
+    const key = endpointKey(protocol, r);
+    if (key == null) continue;
+    surface.set(key, {
+      protocol,
+      key,
+      method: r.method ?? null,
+      path: r.path ?? null,
+      framework: r.framework ?? null,
+      handlerName: r.handlerName ?? null,
+      operation: r.operation ?? null,
+      topic: r.topic ?? null,
+      queue: r.queue ?? null,
+      exchange: r.exchange ?? null,
+      service: r.service ?? null,
+    });
+  }
+  return surface;
+}
+
+function endpointKey(protocol: string, r: {
+  method?: string | null; path?: string | null;
+  operation?: string | null; topic?: string | null;
+  queue?: string | null; exchange?: string | null;
+  service?: string | null;
+}): string | null {
+  if (protocol === 'http') {
+    if (!r.path) return null;
+    return `http|${(r.method ?? 'ANY').toUpperCase()}|${r.path}`;
+  }
+  if (protocol === 'trpc') {
+    if (!r.operation) return null;
+    return `trpc|${r.operation}`;
+  }
+  if (protocol === 'graphql') {
+    if (!r.operation) return null;
+    return `graphql|${r.operation}`;
+  }
+  if (protocol === 'grpc') {
+    if (!r.operation) return null;
+    const svc = r.service ?? '';
+    return `grpc|${svc}.${r.operation}`;
+  }
+  if (protocol === 'kafka' || protocol === 'redis_pubsub' || protocol === 'nats' || protocol === 'sns') {
+    if (!r.topic) return null;
+    return `${protocol}|${r.topic}`;
+  }
+  if (protocol === 'sqs' || protocol === 'rabbitmq') {
+    const key = r.queue ?? r.exchange;
+    if (!key) return null;
+    return `${protocol}|${key}`;
+  }
+  return null;
+}
+
+/**
+ * Diff two bundles' contract surfaces. Both bundles are opened read-only,
+ * the surfaces are collected, and the diff is computed without importing
+ * either bundle into a workspace.
+ */
+export async function contractDiff(
+  oldBundlePath: string,
+  newBundlePath: string,
+  options: { includeAffectedCallers?: boolean } = {},
+): Promise<ContractDiff> {
+  const oldH = await openBundleStore(oldBundlePath);
+  const newH = await openBundleStore(newBundlePath);
+  try {
+    const oldSurface = collectContractSurface(oldH.store);
+    const newSurface = collectContractSurface(newH.store);
+
+    const added: ContractEndpoint[] = [];
+    const removed: ContractEndpoint[] = [];
+    const changed: ContractChange[] = [];
+
+    for (const [key, before] of oldSurface) {
+      const after = newSurface.get(key);
+      if (!after) { removed.push(before); continue; }
+      const fields = diffEndpointFields(before, after);
+      if (fields.length > 0) {
+        changed.push({ protocol: before.protocol, key, before, after, changedFields: fields });
+      }
+    }
+    for (const [key, after] of newSurface) {
+      if (!oldSurface.has(key)) added.push(after);
+    }
+
+    sortByProtocolKey(added);
+    sortByProtocolKey(removed);
+    changed.sort((a, b) =>
+      a.protocol < b.protocol ? -1 :
+      a.protocol > b.protocol ? 1 :
+      a.key < b.key ? -1 :
+      a.key > b.key ? 1 : 0);
+
+    let affectedCallersAvailable = false;
+    let augmented = false;
+    if (options.includeAffectedCallers) {
+      augmented = true;
+      const oldCallersByRouteKey = collectCallersByRouteKey(oldH.store);
+      const newCallersByRouteKey = collectCallersByRouteKey(newH.store);
+
+      const attach = (item: ContractEndpoint & { affectedCallers?: AffectedCaller[] },
+                      side: 'old' | 'new'): void => {
+        const src = side === 'old' ? oldCallersByRouteKey : newCallersByRouteKey;
+        const callers = src.get(item.key);
+        if (callers && callers.length > 0) {
+          item.affectedCallers = callers.map(c => ({ ...c, source: side }));
+          affectedCallersAvailable = true;
+        }
+      };
+      for (const item of added)   attach(item as any, 'new');
+      for (const item of removed) attach(item as any, 'old');
+      for (const item of changed) {
+        const sideOld = oldCallersByRouteKey.get(item.key);
+        const sideNew = newCallersByRouteKey.get(item.key);
+        const callers: AffectedCaller[] = [];
+        if (sideOld) for (const c of sideOld) callers.push({ ...c, source: 'old' });
+        if (sideNew) for (const c of sideNew) callers.push({ ...c, source: 'new' });
+        if (callers.length > 0) {
+          (item as any).affectedCallers = callers;
+          affectedCallersAvailable = true;
+        }
+      }
+      void augmented;
+    }
+
+    return {
+      oldBundle: {
+        path: path.resolve(oldBundlePath),
+        gitHead: oldH.manifest.source.gitHead,
+        rosterHash: oldH.manifest.source.rosterHash,
+      },
+      newBundle: {
+        path: path.resolve(newBundlePath),
+        gitHead: newH.manifest.source.gitHead,
+        rosterHash: newH.manifest.source.rosterHash,
+      },
+      totals: {
+        old: oldSurface.size,
+        new: newSurface.size,
+        added: added.length,
+        removed: removed.length,
+        changed: changed.length,
+      },
+      added,
+      removed,
+      changed,
+      affectedCallersAvailable,
+    };
+  } finally {
+    oldH.cleanup();
+    newH.cleanup();
+  }
+}
+
+function sortByProtocolKey(items: ContractEndpoint[]): void {
+  items.sort((a, b) =>
+    a.protocol < b.protocol ? -1 :
+    a.protocol > b.protocol ? 1 :
+    a.key < b.key ? -1 :
+    a.key > b.key ? 1 : 0);
+}
+
+function diffEndpointFields(a: ContractEndpoint, b: ContractEndpoint): string[] {
+  const fields: string[] = [];
+  const keys: Array<keyof ContractEndpoint> = [
+    'method', 'path', 'framework', 'handlerName',
+    'operation', 'topic', 'queue', 'exchange', 'service',
+  ];
+  for (const k of keys) {
+    if ((a as any)[k] !== (b as any)[k]) fields.push(k);
+  }
+  return fields;
+}
+
+/**
+ * For each route in the bundle, build a list of caller previews using
+ * service_links + service_calls when present. Lets the diff report
+ * affectedCallers without importing the bundle.
+ */
+function collectCallersByRouteKey(store: Store): Map<string, AffectedCaller[]> {
+  const out = new Map<string, AffectedCaller[]>();
+  try {
+    const links = store.listServiceLinks({ limit: 1_000_000 });
+    const routesById = new Map<number, ContractEndpoint>();
+    for (const r of store.listRoutes({ limit: 1_000_000 })) {
+      const protocol = r.protocol ?? 'http';
+      const key = endpointKey(protocol, r);
+      if (!key) continue;
+      routesById.set(r.id, {
+        protocol, key,
+        method: r.method, path: r.path, framework: r.framework,
+        handlerName: r.handlerName,
+        operation: r.operation ?? null, topic: r.topic ?? null,
+        queue: r.queue ?? null, exchange: r.exchange ?? null,
+        service: r.service ?? null,
+      });
+    }
+    for (const l of links) {
+      if (l.routeId == null) continue;
+      const ep = routesById.get(l.routeId);
+      if (!ep) continue;
+      const list = out.get(ep.key) ?? [];
+      list.push({
+        callerQualifiedName: l.callerQualifiedName ?? l.callerName ?? null,
+        callerFile: l.callerFile,
+        callerLine: l.callerLine ?? null,
+        source: 'old',
+      });
+      out.set(ep.key, list);
+    }
+  } catch { /* */ }
+  return out;
+}
+
+/**
+ * Convenience: format the diff as a compact human-readable table.
+ * Deterministic ordering by protocol + key.
+ */
+export function formatContractDiffTable(diff: ContractDiff): string {
+  const lines: string[] = [];
+  lines.push(`Contract diff ${diff.oldBundle.path} → ${diff.newBundle.path}`);
+  lines.push(`  old endpoints: ${diff.totals.old}  new: ${diff.totals.new}  ` +
+    `added: ${diff.totals.added}  removed: ${diff.totals.removed}  changed: ${diff.totals.changed}`);
+  if (diff.added.length > 0) {
+    lines.push('');
+    lines.push('  Added:');
+    for (const a of diff.added) lines.push(`    + [${a.protocol}] ${labelEndpoint(a)}`);
+  }
+  if (diff.removed.length > 0) {
+    lines.push('');
+    lines.push('  Removed:');
+    for (const r of diff.removed) lines.push(`    - [${r.protocol}] ${labelEndpoint(r)}`);
+  }
+  if (diff.changed.length > 0) {
+    lines.push('');
+    lines.push('  Changed:');
+    for (const c of diff.changed) {
+      lines.push(`    ~ [${c.protocol}] ${labelEndpoint(c.before)} (${c.changedFields.join(', ')})`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function labelEndpoint(e: ContractEndpoint): string {
+  if (e.protocol === 'http')   return `${e.method ?? 'ANY'} ${e.path ?? ''} (${e.framework ?? '?'})`;
+  if (e.protocol === 'trpc')   return `${e.operation ?? ''}`;
+  if (e.protocol === 'graphql')return `${e.operation ?? ''}`;
+  if (e.protocol === 'grpc')   return `${e.service ?? ''}.${e.operation ?? ''}`;
+  return e.topic ?? e.queue ?? e.exchange ?? '?';
+}

package/src/bundle/export.ts

@@ -0,0 +1,175 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import zlib from 'zlib';
+import { execFileSync } from 'child_process';
+import { Store } from '../db/store.js';
+import {
+  BUNDLE_MAGIC, BUNDLE_FORMAT_VERSION, BundleManifest,
+} from './format.js';
+
+export interface ExportOptions {
+  /** Where to write the bundle. Defaults to `<repoRoot>/.seer/index.seerbundle`. */
+  out?: string;
+  /** Gzip level (0-9). Defaults to 6 (zlib's standard balance). */
+  compressionLevel?: number;
+  /** Logger; defaults to no-op. */
+  log?: (msg: string) => void;
+  /** Override the gitHead recorded in the manifest (CI sometimes wants this). */
+  gitHead?: string;
+  /** Override the gitBranch recorded in the manifest. */
+  gitBranch?: string;
+  /**
+   * Pin the manifest's `builtAt` (Unix-millis). Defaults to `Date.now()`,
+   * which makes successive exports of the same DB byte-different. Override
+   * to a stable value (e.g. the source repo's HEAD commit time) when you
+   * need reproducible bundle bytes for build-cache keys.
+   */
+  builtAt?: number;
+}
+
+export interface ExportResult {
+  bundlePath: string;
+  bytes: number;
+  manifest: BundleManifest;
+  elapsedMs: number;
+}
+
+/**
+ * Bundle an existing `.seer/graph.db` into a portable single-file artifact.
+ *
+ * The DB is first VACUUM INTO'd to a temp file so we ship a tightly packed
+ * copy (no WAL, no free pages). The packed DB is hashed, then gzip-compressed
+ * and concatenated after the manifest header. The result is deterministic for
+ * a given DB content + manifest input.
+ */
+export async function exportBundle(
+  dbPath: string, repoRoot: string, options: ExportOptions = {},
+): Promise<ExportResult> {
+  const start = Date.now();
+  const log = options.log ?? (() => { /* */ });
+
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`No index at ${dbPath} — run \`seer index\` first.`);
+  }
+
+  // Open the source DB read-only and harvest the manifest data BEFORE we
+  // start the vacuum (vacuum closes implicit locks on its own connection but
+  // the source connection stays compatible since we re-open it here).
+  const srcStore = Store.openReadOnly(dbPath);
+  let manifest: BundleManifest;
+  try {
+    const stats = srcStore.getStats();
+    const scipImports = srcStore.listScipImports();
+    const files = srcStore.listFiles();
+    const roster = files
+      .map(f => ({ relPath: f.relPath, hash: f.hash }))
+      .sort((a, b) => a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0);
+    const rosterHash = crypto.createHash('sha256')
+      .update(roster.map(r => `${r.relPath}\t${r.hash}`).join('\n'))
+      .digest('hex');
+    const schemaVersion = srcStore.schemaInfo().dbVersion;
+
+    manifest = {
+      bundleFormatVersion: BUNDLE_FORMAT_VERSION,
+      schemaVersion,
+      builtAt: options.builtAt ?? Date.now(),
+      builtBy: `seer/${BUNDLE_FORMAT_VERSION}`,
+      source: {
+        repoRoot: path.resolve(repoRoot),
+        gitHead: options.gitHead ?? detectGitHead(repoRoot),
+        gitBranch: options.gitBranch ?? detectGitBranch(repoRoot),
+        rosterHash,
+        fileCount: files.length,
+      },
+      index: {
+        symbols: stats.symbols,
+        edges: stats.edges,
+        resolvedEdges: stats.resolvedEdges,
+        modules: stats.modules ?? 0,
+        routes: stats.routes ?? 0,
+        externalDependencies: stats.externalDependencies ?? 0,
+        configKeys: stats.configKeys ?? 0,
+        languages: stats.languages,
+        provenance: stats.provenance,
+      },
+      scipImports: scipImports.map(s => ({
+        path: s.path, sha256: s.sha256, tool: s.tool,
+        symbolCount: s.symbolCount, refCount: s.refCount,
+      })),
+      dbSha256: '',  // filled in after we hash the packed DB
+      dbBytes: 0,
+    };
+  } finally {
+    srcStore.close();
+  }
+
+  // VACUUM INTO produces a fresh, tightly packed DB — fast on small repos,
+  // O(rows) on huge ones. We write to a temp file so the source DB stays
+  // untouched and aborted exports leave nothing behind.
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'seer-bundle-'));
+  const packedDb = path.join(tmpDir, 'graph.packed.db');
+  log(`Vacuuming index into ${packedDb}...`);
+  const packStore = new Store(dbPath);
+  try {
+    packStore.rawDb().exec(`VACUUM INTO '${packedDb.replace(/'/g, "''")}'`);
+  } finally {
+    packStore.close();
+  }
+
+  const dbBuf = fs.readFileSync(packedDb);
+  const dbSha = crypto.createHash('sha256').update(dbBuf).digest('hex');
+  manifest.dbSha256 = dbSha;
+  manifest.dbBytes = dbBuf.length;
+  log(`Packed DB: ${dbBuf.length} bytes, sha256 ${dbSha.slice(0, 12)}...`);
+
+  const manifestJson = Buffer.from(JSON.stringify(manifest, null, 2), 'utf-8');
+  // Gzip the DB. Level 6 is the zlib default; bumpable for CI artifacts.
+  const compressed = zlib.gzipSync(dbBuf, {
+    level: options.compressionLevel ?? 6,
+  });
+  log(`Compressed DB: ${compressed.length} bytes (${(compressed.length / dbBuf.length * 100).toFixed(1)}% of raw)`);
+
+  const header = Buffer.alloc(4 + 4 + 4);
+  BUNDLE_MAGIC.copy(header, 0);
+  header.writeUInt32BE(BUNDLE_FORMAT_VERSION, 4);
+  header.writeUInt32BE(manifestJson.length, 8);
+
+  const outPath = options.out ?? path.join(repoRoot, '.seer', 'index.seerbundle');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  const fd = fs.openSync(outPath, 'w');
+  try {
+    fs.writeSync(fd, header);
+    fs.writeSync(fd, manifestJson);
+    fs.writeSync(fd, compressed);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try { fs.unlinkSync(packedDb); fs.rmdirSync(tmpDir); } catch { /* */ }
+
+  return {
+    bundlePath: outPath,
+    bytes: header.length + manifestJson.length + compressed.length,
+    manifest,
+    elapsedMs: Date.now() - start,
+  };
+}
+
+function detectGitHead(repoRoot: string): string | null {
+  try {
+    const sha = execFileSync('git', ['-C', repoRoot, 'rev-parse', 'HEAD'], {
+      encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return sha.length > 0 ? sha : null;
+  } catch { return null; }
+}
+
+function detectGitBranch(repoRoot: string): string | null {
+  try {
+    const branch = execFileSync('git', ['-C', repoRoot, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return branch.length > 0 && branch !== 'HEAD' ? branch : null;
+  } catch { return null; }
+}