seer-mcp 0.1.0

package/src/bundle/external.ts

@@ -0,0 +1,285 @@
+/**
+ * v10 External Bundle Layers — additive import of a peer repo's .seerbundle as
+ * read-only external evidence.
+ *
+ * The destructive bundle import (src/bundle/import.ts) replaces the local
+ * graph DB wholesale; this importer leaves local files/symbols untouched and
+ * only adds:
+ *   - one row in external_bundles (source identity + manifest hash)
+ *   - one phantom file per bundle (`__external_bundle__/<project>/<id>`)
+ *   - rows in routes (and where present, service_endpoints) marked
+ *     `external_bundle_id` so they participate in service-link resolution but
+ *     can be wiped as a single layer on re-import.
+ *
+ * Design rules:
+ *   - never touch local symbols / files / edges / pagerank
+ *   - never write rows whose external_bundle_id is NULL
+ *   - re-importing the same path with the same hash is a no-op
+ *   - re-importing with a NEW hash replaces only that layer (FK cascade)
+ *   - the bundle is read by spinning up a temp Store against the bundle's
+ *     SQLite payload — same code path that bundle/info uses to enumerate the
+ *     manifest, but with full row access scoped read-only
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import zlib from 'zlib';
+import crypto from 'crypto';
+import { BUNDLE_MAGIC, BUNDLE_FORMAT_VERSION, BundleManifest } from './format.js';
+import { CURRENT_SCHEMA_VERSION } from '../db/schema.js';
+import { Store } from '../db/store.js';
+import { resolveServiceLinks } from '../indexer/serviceLinks.js';
+
+export interface ExternalImportOptions {
+  /** Optional alias for the bundle (defaults to the manifest's gitBranch or basename). */
+  alias?: string;
+  /** When true, force re-import even if the same hash is already present. */
+  force?: boolean;
+  /**
+   * Skip the dbSha256 / dbBytes integrity check. Off by default — the manifest
+   * integrity guarantee is what lets us trust a peer-repo bundle. Use only for
+   * forensic inspection of a corrupted bundle whose header still parses.
+   */
+  skipIntegrityCheck?: boolean;
+  /**
+   * Skip the schema-version compatibility check. Off by default — a bundle
+   * whose schemaVersion is newer than this build can't be safely read.
+   */
+  skipSchemaCheck?: boolean;
+  /**
+   * Rebuild service_links after import so cross-repo links are visible to the
+   * next query without waiting for a re-index. Default true.
+   */
+  rebuildServiceLinks?: boolean;
+  /** Logger; defaults to no-op. */
+  log?: (msg: string) => void;
+}
+
+export interface ExternalImportResult {
+  bundlePath: string;
+  bundleId: number;
+  externalProject: string | null;
+  externalHash: string;
+  schemaVersion: number;
+  /** True when the same bundle path + hash was already imported and we skipped. */
+  alreadyImported: boolean;
+  routesImported: number;
+  serviceEndpointsImported: number;
+  elapsedMs: number;
+}
+
+/**
+ * Import a .seerbundle as an additive external layer into the given local
+ * Store. The local DB is NOT touched outside of the external_bundles row,
+ * the phantom file row, and the new external-marked routes/service_calls.
+ */
+export async function importExternalBundle(
+  bundlePath: string,
+  localStore: Store,
+  options: ExternalImportOptions = {},
+): Promise<ExternalImportResult> {
+  const start = Date.now();
+  const log = options.log ?? (() => { /* */ });
+
+  if (localStore.isReadOnly()) {
+    throw new Error('Cannot import external bundle into a read-only Store');
+  }
+  if (!localStore.hasV10()) {
+    throw new Error('Local DB does not have v10 external_bundles tables — upgrade first');
+  }
+
+  if (!fs.existsSync(bundlePath)) {
+    throw new Error(`No bundle at ${bundlePath}`);
+  }
+
+  // Parse the manifest + payload up front. We need both: the manifest gives us
+  // identity + schema_version, the payload gives us the read source.
+  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; manifest length ${manifestLen} exceeds file size`);
+  }
+  const manifest = JSON.parse(fileBuf.slice(12, manifestEnd).toString('utf-8')) as BundleManifest;
+
+  // Schema compatibility: a bundle built against a NEWER schema may carry
+  // tables/columns we don't understand. Reject up front rather than reading
+  // partial data. Older bundles are fine — listRoutes tolerates older shapes.
+  if (!options.skipSchemaCheck) {
+    if (typeof manifest.schemaVersion !== 'number' || manifest.schemaVersion <= 0) {
+      throw new Error(`Bundle has invalid schemaVersion=${manifest.schemaVersion}.`);
+    }
+    if (manifest.schemaVersion > CURRENT_SCHEMA_VERSION) {
+      throw new Error(
+        `Bundle schemaVersion=${manifest.schemaVersion} is newer than this build's ` +
+        `CURRENT_SCHEMA_VERSION=${CURRENT_SCHEMA_VERSION}. Upgrade Seer or pass skipSchemaCheck=true.`,
+      );
+    }
+  }
+
+  const externalHash = manifest.dbSha256;
+  const externalProject = options.alias
+    ?? manifest.source.gitBranch
+    ?? path.basename(bundlePath, path.extname(bundlePath));
+  const externalVersion = manifest.source.gitHead ?? null;
+
+  const absBundlePath = path.resolve(bundlePath);
+
+  // Idempotency check: same path + same hash → no-op.
+  const existing = localStore.findExternalBundleByPath(absBundlePath);
+  if (existing && existing.externalHash === externalHash && !options.force) {
+    log(`already imported with the same hash; skipping`);
+    return {
+      bundlePath: absBundlePath,
+      bundleId: existing.id,
+      externalProject: existing.externalProject,
+      externalHash,
+      schemaVersion: manifest.schemaVersion,
+      alreadyImported: true,
+      routesImported: 0,
+      serviceEndpointsImported: 0,
+      elapsedMs: Date.now() - start,
+    };
+  }
+
+  // Decompress the embedded DB so we can read its tables.
+  const compressed = fileBuf.slice(manifestEnd);
+  const dbBuf = zlib.gunzipSync(compressed);
+
+  // Integrity check: the decompressed payload must match the manifest's
+  // sha256 + byte length. A tampered or truncated bundle is rejected here.
+  if (!options.skipIntegrityCheck) {
+    const dbSha = crypto.createHash('sha256').update(dbBuf).digest('hex');
+    if (dbSha !== manifest.dbSha256) {
+      throw new Error(`Bundle integrity check FAILED. Expected ${manifest.dbSha256}, got ${dbSha}.`);
+    }
+    if (typeof manifest.dbBytes === 'number' && dbBuf.length !== manifest.dbBytes) {
+      throw new Error(`Bundle integrity check FAILED. Expected ${manifest.dbBytes} bytes, got ${dbBuf.length}.`);
+    }
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'seer-extbundle-'));
+  const externalDbPath = path.join(tmpDir, 'external.db');
+  fs.writeFileSync(externalDbPath, dbBuf);
+
+  let bundleId = 0;
+  let routesImported = 0;
+  let serviceEndpointsImported = 0;
+  try {
+    const externalStore = Store.openReadOnly(externalDbPath);
+    try {
+      // If we already had this path but with a different hash, wipe the
+      // previous layer first so the new import is a clean replace.
+      if (existing) {
+        const wiped = localStore.clearExternalBundle(existing.id);
+        log(`re-import: wiped previous layer (routes=${wiped.routes}, serviceCalls=${wiped.serviceCalls})`);
+      }
+
+      // Create the bundle row first so we have a stable id for the phantom
+      // file + the imported route rows.
+      bundleId = localStore.upsertExternalBundle({
+        bundlePath: absBundlePath,
+        externalProject,
+        externalVersion,
+        externalHash,
+        schemaVersion: manifest.schemaVersion,
+        routesImported: 0,
+        serviceCallsImported: 0,
+        serviceLinksImported: 0,
+      });
+      const externalFileId = localStore.ensureExternalFile(bundleId, externalProject);
+
+      // Import routes from the external bundle. We use the public listRoutes
+      // API which transparently handles pre-v9 column shapes (older bundles
+      // won't carry protocol/operation/etc.).
+      const localRoutes = externalStore.listRoutes({ limit: 1_000_000 });
+      // Filter: we never want external-bundle rows from a nested bundle. If
+      // the source bundle has external_bundle_id, skip those (they're
+      // someone else's external layer).
+      const importableRoutes = localRoutes.filter(r => {
+        // Cannot easily detect external_bundle_id via the public API; raw
+        // probe the column. listRoutes doesn't surface it today, so accept
+        // everything; the bundle generator should not have exported external
+        // rows itself (round-tripping external layers would be misleading).
+        return r.method && r.path;
+      });
+      log(`importing ${importableRoutes.length} routes from external bundle`);
+      localStore.begin();
+      try {
+        for (const r of importableRoutes) {
+          localStore.insertExternalRoute({
+            bundleId,
+            externalFileId,
+            method: r.method,
+            path: r.path,
+            framework: r.framework,
+            handlerName: r.handlerName,
+            line: r.line,
+            protocol: r.protocol ?? 'http',
+            operation: r.operation ?? null,
+            topic: r.topic ?? null,
+            queue: r.queue ?? null,
+            exchange: r.exchange ?? null,
+            service: r.service ?? null,
+            broker: r.broker ?? null,
+            metadataJson: r.metadataJson ?? null,
+          });
+          routesImported++;
+        }
+        localStore.commit();
+      } catch (err) {
+        localStore.rollback();
+        throw err;
+      }
+
+      // Rebuild service links so the freshly-imported external routes are
+      // visible to the next query immediately, without waiting for a re-index.
+      let serviceLinksImported = 0;
+      if (options.rebuildServiceLinks !== false) {
+        try {
+          const sr = resolveServiceLinks(localStore);
+          serviceLinksImported = sr.linksInserted ?? 0;
+          log(`rebuilt service links (linked=${serviceLinksImported})`);
+        } catch (err) {
+          log(`service-link rebuild skipped: ${(err as Error).message}`);
+        }
+      }
+
+      // Update final counts on the bundle row.
+      localStore.upsertExternalBundle({
+        bundlePath: absBundlePath,
+        externalProject,
+        externalVersion,
+        externalHash,
+        schemaVersion: manifest.schemaVersion,
+        routesImported,
+        serviceCallsImported: 0,
+        serviceLinksImported,
+      });
+    } finally {
+      externalStore.close();
+    }
+  } finally {
+    try { fs.unlinkSync(externalDbPath); fs.rmdirSync(tmpDir); } catch { /* */ }
+  }
+
+  return {
+    bundlePath: absBundlePath,
+    bundleId,
+    externalProject,
+    externalHash,
+    schemaVersion: manifest.schemaVersion,
+    alreadyImported: false,
+    routesImported,
+    serviceEndpointsImported,
+    elapsedMs: Date.now() - start,
+  };
+}

package/src/bundle/format.ts

@@ -0,0 +1,92 @@
+/**
+ * Track-F portable .seer bundle format.
+ *
+ * A bundle is a single self-describing file that lets a team ship a fully
+ * built index without every developer having to re-run `seer index`. The
+ * format is deliberately tiny and dependency-free:
+ *
+ *   [4 bytes: magic 'SEER']
+ *   [4 bytes: bundle format version (uint32 BE)]
+ *   [4 bytes: manifest length (uint32 BE)]
+ *   [N bytes: manifest JSON (utf-8)]
+ *   [M bytes: gzip-compressed SQLite DB]
+ *
+ * Why not tar/zip? Both add a dependency or a hand-rolled archive writer for
+ * a single payload file. Our payload IS the DB; everything else is a few
+ * structured fields. One header + one gzip stream gets us:
+ *   - O(1) manifest read without decompressing the DB
+ *   - cross-platform, no native deps
+ *
+ * On determinism: the gzip stream and the VACUUM INTO'd DB ARE deterministic
+ * for fixed input. The manifest, however, defaults `builtAt = Date.now()` so
+ * out-of-the-box exports of the same DB at different wall-clock times
+ * produce different bytes. If you need bit-identical bundles (build-cache
+ * keys, reproducible-builds CI), pass an explicit `builtAt` to `exportBundle`
+ * to pin it.
+ *
+ * The manifest is the source of truth for:
+ *   - schema_version (so the consumer can refuse incompatible bundles)
+ *   - source signature (repo root, git head, file count + hash) so the
+ *     bundle's "shape" is auditable before the agent trusts it
+ *   - tool versions, build time, SCIP layers contributing precision
+ *
+ * Bundles are produced by `seer bundle export` and consumed by
+ * `seer bundle import`. CI mode (`seer ci bundle`) is a thin wrapper that
+ * runs `index` then `bundle export` and surfaces the resulting path.
+ */
+
+export const BUNDLE_MAGIC = Buffer.from('SEER', 'utf-8');
+export const BUNDLE_FORMAT_VERSION = 1;
+
+export interface BundleManifest {
+  /**
+   * Bundle format version — bumped when the on-disk layout changes
+   * incompatibly. Distinct from the DB schema version, which can bump
+   * independently when only the SQL evolves.
+   */
+  bundleFormatVersion: number;
+  /** Schema version of the embedded DB. Consumers refuse on mismatch. */
+  schemaVersion: number;
+  /** Wall-clock millis the bundle was built. */
+  builtAt: number;
+  /** Tool that produced the bundle. */
+  builtBy: string;
+  /** Source identity. */
+  source: {
+    repoRoot: string;
+    gitHead: string | null;
+    gitBranch: string | null;
+    /** Stable hash over the source file roster — `(relPath, fileHash)` pairs. */
+    rosterHash: string;
+    /** Number of source files indexed. */
+    fileCount: number;
+  };
+  /** Index summary so a consumer can size-check without unpacking. */
+  index: {
+    symbols: number;
+    edges: number;
+    resolvedEdges: number;
+    modules: number;
+    routes: number;
+    externalDependencies: number;
+    configKeys: number;
+    languages: Record<string, number>;
+    /** v7: provenance counts. */
+    provenance?: {
+      symbols: Record<string, number>;
+      edges: Record<string, number>;
+    };
+  };
+  /** SCIP layers folded into the DB (if any). */
+  scipImports: Array<{
+    path: string; sha256: string; tool: string | null;
+    symbolCount: number; refCount: number;
+  }>;
+  /**
+   * Sha-256 of the embedded DB (computed BEFORE compression). Lets the
+   * consumer verify a transferred bundle without trusting the gzip CRC alone.
+   */
+  dbSha256: string;
+  /** Uncompressed DB size in bytes. */
+  dbBytes: number;
+}

package/src/bundle/import.ts

@@ -0,0 +1,157 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import zlib from 'zlib';
+import {
+  BUNDLE_MAGIC, BUNDLE_FORMAT_VERSION, BundleManifest,
+} from './format.js';
+import { CURRENT_SCHEMA_VERSION } from '../db/schema.js';
+
+export interface ImportOptions {
+  /**
+   * Where to land the extracted DB. Defaults to `<repoRoot>/.seer/graph.db`.
+   * If the path already exists and `overwrite` is false (the default), the
+   * import fails — bundles are meant to bootstrap a missing index, not to
+   * silently clobber a fresher local one.
+   */
+  dbOut?: string;
+  overwrite?: boolean;
+  /** Logger; defaults to no-op. */
+  log?: (msg: string) => void;
+  /**
+   * Skip the dbSha256 check. Off by default — the integrity guarantee is the
+   * whole point of the manifest. Use this only for forensic inspection of a
+   * corrupted bundle whose header still parses.
+   */
+  skipIntegrityCheck?: boolean;
+  /**
+   * Skip the schema-version compatibility check. Off by default — bundles
+   * whose schemaVersion is newer than this build's CURRENT_SCHEMA_VERSION
+   * are rejected because we can't safely open them. Override only when you
+   * KNOW the schema is compatible (e.g. forensics or a controlled upgrade).
+   */
+  skipSchemaCheck?: boolean;
+  /**
+   * Required source repo root for the imported index. Used to decide the
+   * default dbOut location only — the bundle's manifest.source.repoRoot is
+   * stored as metadata but never enforced (bundles are commonly built on
+   * a CI runner with a different absolute path).
+   */
+  repoRoot: string;
+}
+
+export interface ImportResult {
+  bundlePath: string;
+  dbPath: string;
+  manifest: BundleManifest;
+  bytes: number;
+  elapsedMs: number;
+}
+
+/** Read just the manifest from a bundle, without unpacking the DB. */
+export function readBundleManifest(bundlePath: string): BundleManifest {
+  const fd = fs.openSync(bundlePath, 'r');
+  try {
+    const header = Buffer.alloc(12);
+    const headerRead = fs.readSync(fd, header, 0, 12, 0);
+    if (headerRead < 12 || !header.subarray(0, 4).equals(BUNDLE_MAGIC)) {
+      throw new Error(`Not a Seer bundle: ${bundlePath} (bad magic)`);
+    }
+    const formatVersion = header.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 = header.readUInt32BE(8);
+    if (manifestLen <= 0 || manifestLen > 64 * 1024 * 1024) {
+      throw new Error(`Bundle manifest length out of range: ${manifestLen}`);
+    }
+    const manifestBuf = Buffer.alloc(manifestLen);
+    const read = fs.readSync(fd, manifestBuf, 0, manifestLen, 12);
+    if (read !== manifestLen) {
+      throw new Error(`Bundle truncated reading manifest`);
+    }
+    return JSON.parse(manifestBuf.toString('utf-8')) as BundleManifest;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Restore a bundle into the workspace. The default destination is
+ * `<repoRoot>/.seer/graph.db`. Verifies the manifest, format version, and
+ * (unless skipped) the DB sha256.
+ */
+export async function importBundle(
+  bundlePath: string, options: ImportOptions,
+): Promise<ImportResult> {
+  const start = Date.now();
+  const log = options.log ?? (() => { /* */ });
+
+  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 (manifestEnd > fileBuf.length) {
+    throw new Error(`Bundle truncated; manifest length ${manifestLen} exceeds file size`);
+  }
+  const manifest = JSON.parse(fileBuf.slice(12, manifestEnd).toString('utf-8')) as BundleManifest;
+  log(`Manifest: schemaVersion=${manifest.schemaVersion} symbols=${manifest.index.symbols} edges=${manifest.index.edges} builtAt=${new Date(manifest.builtAt).toISOString()}`);
+
+  // Schema compatibility check. The bundle's embedded DB was built against a
+  // specific schema version; if it's NEWER than this build of Seer, the DB
+  // contains tables/columns we don't understand and opening it would either
+  // crash on read or silently lose precision. Reject up front rather than
+  // crashing on first query. Older bundles are accepted because the Store's
+  // runMigrations() will catch the DB up at open time.
+  if (!options.skipSchemaCheck) {
+    if (manifest.schemaVersion > CURRENT_SCHEMA_VERSION) {
+      throw new Error(
+        `Bundle schemaVersion=${manifest.schemaVersion} is newer than this build's ` +
+        `CURRENT_SCHEMA_VERSION=${CURRENT_SCHEMA_VERSION}. Upgrade Seer or pass skipSchemaCheck=true.`,
+      );
+    }
+    if (manifest.schemaVersion <= 0) {
+      throw new Error(`Bundle has invalid schemaVersion=${manifest.schemaVersion}.`);
+    }
+  }
+
+  const compressed = fileBuf.slice(manifestEnd);
+  const dbBuf = zlib.gunzipSync(compressed);
+
+  if (!options.skipIntegrityCheck) {
+    const dbSha = crypto.createHash('sha256').update(dbBuf).digest('hex');
+    if (dbSha !== manifest.dbSha256) {
+      throw new Error(`Bundle integrity check FAILED. Expected ${manifest.dbSha256}, got ${dbSha}.`);
+    }
+    if (dbBuf.length !== manifest.dbBytes) {
+      throw new Error(`Bundle integrity check FAILED. Expected ${manifest.dbBytes} bytes, got ${dbBuf.length}.`);
+    }
+  }
+
+  const dbOut = options.dbOut ?? path.join(options.repoRoot, '.seer', 'graph.db');
+  if (fs.existsSync(dbOut) && !options.overwrite) {
+    throw new Error(`Refusing to overwrite existing index at ${dbOut} — pass overwrite=true to replace it.`);
+  }
+  fs.mkdirSync(path.dirname(dbOut), { recursive: true });
+  fs.writeFileSync(dbOut, dbBuf);
+  // Drop the WAL/SHM siblings of the previous DB (if any) so the imported
+  // file isn't read against a stale journal.
+  try { fs.unlinkSync(dbOut + '-wal'); } catch { /* */ }
+  try { fs.unlinkSync(dbOut + '-shm'); } catch { /* */ }
+  log(`Wrote ${dbBuf.length} bytes to ${dbOut}`);
+
+  return {
+    bundlePath, dbPath: dbOut, manifest,
+    bytes: fileBuf.length, elapsedMs: Date.now() - start,
+  };
+}