seer-mcp 0.1.0

package/dist/bundle/format.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLE_FORMAT_VERSION = exports.BUNDLE_MAGIC = void 0;
+exports.BUNDLE_MAGIC = Buffer.from('SEER', 'utf-8');
+exports.BUNDLE_FORMAT_VERSION = 1;
+//# sourceMappingURL=format.js.map

package/dist/bundle/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/bundle/format.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;;AAEU,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,QAAA,qBAAqB,GAAG,CAAC,CAAC"}

package/dist/bundle/import.d.ts

@@ -0,0 +1,49 @@
+import { BundleManifest } from './format.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 declare function readBundleManifest(bundlePath: string): BundleManifest;
+/**
+ * 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 declare function importBundle(bundlePath: string, options: ImportOptions): Promise<ImportResult>;
+//# sourceMappingURL=import.d.ts.map

package/dist/bundle/import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/bundle/import.ts"],"names":[],"mappings":"AAIA,OAAO,EACgC,cAAc,EACpD,MAAM,aAAa,CAAC;AAGrB,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iCAAiC;IACjC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAyBrE;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GACzC,OAAO,CAAC,YAAY,CAAC,CAuEvB"}

package/dist/bundle/import.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBundleManifest = readBundleManifest;
+exports.importBundle = importBundle;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const zlib_1 = __importDefault(require("zlib"));
+const format_js_1 = require("./format.js");
+const schema_js_1 = require("../db/schema.js");
+/** Read just the manifest from a bundle, without unpacking the DB. */
+function readBundleManifest(bundlePath) {
+    const fd = fs_1.default.openSync(bundlePath, 'r');
+    try {
+        const header = Buffer.alloc(12);
+        const headerRead = fs_1.default.readSync(fd, header, 0, 12, 0);
+        if (headerRead < 12 || !header.subarray(0, 4).equals(format_js_1.BUNDLE_MAGIC)) {
+            throw new Error(`Not a Seer bundle: ${bundlePath} (bad magic)`);
+        }
+        const formatVersion = header.readUInt32BE(4);
+        if (formatVersion > format_js_1.BUNDLE_FORMAT_VERSION) {
+            throw new Error(`Bundle format v${formatVersion} is newer than this build (v${format_js_1.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_1.default.readSync(fd, manifestBuf, 0, manifestLen, 12);
+        if (read !== manifestLen) {
+            throw new Error(`Bundle truncated reading manifest`);
+        }
+        return JSON.parse(manifestBuf.toString('utf-8'));
+    }
+    finally {
+        fs_1.default.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.
+ */
+async function importBundle(bundlePath, options) {
+    const start = Date.now();
+    const log = options.log ?? (() => { });
+    if (!fs_1.default.existsSync(bundlePath)) {
+        throw new Error(`No bundle at ${bundlePath}`);
+    }
+    const fileBuf = fs_1.default.readFileSync(bundlePath);
+    if (fileBuf.length < 12 || !fileBuf.subarray(0, 4).equals(format_js_1.BUNDLE_MAGIC)) {
+        throw new Error(`Not a Seer bundle: ${bundlePath} (bad magic)`);
+    }
+    const formatVersion = fileBuf.readUInt32BE(4);
+    if (formatVersion > format_js_1.BUNDLE_FORMAT_VERSION) {
+        throw new Error(`Bundle format v${formatVersion} is newer than this build (v${format_js_1.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'));
+    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 > schema_js_1.CURRENT_SCHEMA_VERSION) {
+            throw new Error(`Bundle schemaVersion=${manifest.schemaVersion} is newer than this build's ` +
+                `CURRENT_SCHEMA_VERSION=${schema_js_1.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_1.default.gunzipSync(compressed);
+    if (!options.skipIntegrityCheck) {
+        const dbSha = crypto_1.default.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_1.default.join(options.repoRoot, '.seer', 'graph.db');
+    if (fs_1.default.existsSync(dbOut) && !options.overwrite) {
+        throw new Error(`Refusing to overwrite existing index at ${dbOut} — pass overwrite=true to replace it.`);
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(dbOut), { recursive: true });
+    fs_1.default.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_1.default.unlinkSync(dbOut + '-wal');
+    }
+    catch { /* */ }
+    try {
+        fs_1.default.unlinkSync(dbOut + '-shm');
+    }
+    catch { /* */ }
+    log(`Wrote ${dbBuf.length} bytes to ${dbOut}`);
+    return {
+        bundlePath, dbPath: dbOut, manifest,
+        bytes: fileBuf.length, elapsedMs: Date.now() - start,
+    };
+}
+//# sourceMappingURL=import.js.map

package/dist/bundle/import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.js","sourceRoot":"","sources":["../../src/bundle/import.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}