@opensip-cli/mcp 0.1.15

package/dist/sqlite-graph-read-port.js

@@ -0,0 +1,304 @@
+/**
+ * SQLite-backed {@link GraphReadPort} (ADR-0084).
+ *
+ * Reads the persisted catalog through the graph engine's `CatalogRepo`
+ * (internal surface) and derives adjacency via `buildIndexes` — it NEVER invents
+ * a parallel catalog table or raw-queries `DataStore.db`. Freshness reuses
+ * `classifyCatalog`; dead code reuses `orphanSubtreeRule`; blast reuses the
+ * single canonical `buildFeatures(['blast'])` scoring site (no ad-hoc BFS). The
+ * generic bounded adjacency walks for callers/callees/trace are MCP-local.
+ *
+ * Constructed from an injected `DataStore` (+ optional freshness-context and
+ * rebuild providers, wired in Phases 3/4) — it NEVER reads `currentScope()`.
+ * Reads return `Result<McpToolResult<T>, McpReadError>`; a missing catalog is
+ * NOT an error — it surfaces as `freshness.fresh === false` with empty data and
+ * no auto-build. `throw` is reserved for the SQLite/Drizzle boundary (a failing
+ * `CatalogRepo.loadFullCatalog`) and the `runGraph` rebuild.
+ */
+import { err, ok } from '@opensip-cli/core';
+import { buildFeatures, CatalogRepo, orphanSubtreeRule } from '@opensip-cli/graph/internal';
+import { createGeneration } from './catalog-generation.js';
+import { classifyFreshness, missingFreshness, unverifiedFreshness } from './freshness.js';
+import { readError } from './mcp-error.js';
+/** Default search-result cap. */
+const DEFAULT_SEARCH_LIMIT = 50;
+/** Shared empty adjacency for the no-catalog case (avoids per-call allocation). */
+const EMPTY_EDGES = new Map();
+/** Default architecture package-row cap. */
+const DEFAULT_ARCH_LIMIT = 25;
+export class SqliteGraphReadPort {
+    deps;
+    store;
+    config;
+    generation;
+    loaded = false;
+    // Per-generation memoized derivations (reset on (re)load / refresh). Freshness
+    // is deliberately NOT memoized: a long-lived server must re-verify the working
+    // tree on each read so a mid-session file mutation flips `fresh` to false.
+    blastCache;
+    /** In-flight rebuild — serializes concurrent `refresh()` to a single build. */
+    inFlightRefresh;
+    constructor(deps) {
+        this.deps = deps;
+        this.store = deps.store;
+        this.config = deps.config ?? {};
+    }
+    // ── generation lifecycle ──────────────────────────────────────────
+    /** Lazily load + pin the current generation from the persisted catalog. */
+    current() {
+        if (!this.loaded) {
+            // CatalogRepo throws only on a genuine SQLite/Drizzle failure (sanctioned
+            // infra boundary); a missing catalog returns null → no generation.
+            const catalog = new CatalogRepo(this.store).loadFullCatalog();
+            this.generation = catalog === null ? undefined : createGeneration(catalog);
+            this.loaded = true;
+            this.invalidateDerived();
+        }
+        return this.generation;
+    }
+    invalidateDerived() {
+        this.blastCache = undefined;
+    }
+    freshness() {
+        const gen = this.current();
+        return gen === undefined ? missingFreshness() : this.classify(gen);
+    }
+    classify(gen) {
+        const ctx = this.deps.freshnessContext?.(gen.catalog);
+        if (ctx === undefined)
+            return unverifiedFreshness(gen.builtAt);
+        return classifyFreshness(gen.catalog, ctx);
+    }
+    /** Wrap data in the shared `{ data, freshness, truncated? }` envelope. */
+    wrap(data, truncated) {
+        return {
+            data,
+            freshness: this.freshness(),
+            ...(truncated ? { truncated: true } : {}),
+        };
+    }
+    /** The empty (no-data) envelope for an absent catalog / unresolved symbol. */
+    empty() {
+        return { data: undefined, freshness: this.freshness() };
+    }
+    // ── reads ─────────────────────────────────────────────────────────
+    getGeneration() {
+        const gen = this.current();
+        return ok(this.wrap(gen === undefined ? undefined : { builtAt: gen.builtAt }));
+    }
+    resolveSymbolId(symbolId) {
+        const gen = this.current();
+        if (gen === undefined)
+            return ok(this.empty());
+        const occ = gen.indexes.byOccId.get(symbolId);
+        return ok(this.wrap(occ === undefined ? undefined : toSymbolRef(occ)));
+    }
+    searchSymbols(query, opts) {
+        const gen = this.current();
+        if (gen === undefined)
+            return ok(this.wrap([]));
+        const limit = clampLimit(opts?.limit, DEFAULT_SEARCH_LIMIT);
+        const needle = query.toLowerCase();
+        const matches = [];
+        let truncated = false;
+        for (const occ of gen.indexes.byOccId.values()) {
+            if (occ.kind === 'module-init')
+                continue;
+            if (!occ.simpleName.toLowerCase().includes(needle))
+                continue;
+            if (matches.length >= limit) {
+                truncated = true;
+                break;
+            }
+            matches.push(toSymbolRef(occ));
+        }
+        return ok(this.wrap(matches, truncated));
+    }
+    findBySpan(file, line) {
+        const gen = this.current();
+        if (gen === undefined)
+            return ok(this.wrap([]));
+        const out = [];
+        for (const occ of gen.indexes.byOccId.values()) {
+            if (occ.filePath === file && occ.line <= line && line <= occ.endLine) {
+                out.push(toSymbolRef(occ));
+            }
+        }
+        return ok(this.wrap(out));
+    }
+    callerGraph() {
+        return ok(this.wrap(this.adjacency((gen) => gen.indexes.callers)));
+    }
+    calleeGraph() {
+        return ok(this.wrap(this.adjacency((gen) => gen.indexes.callees)));
+    }
+    /**
+     * Project one direction's body-hash adjacency into a walkable
+     * {@link AdjacencySnapshot}. The map IS the engine's `Indexes.callers`/
+     * `callees` (no copy); the resolver closes over `byBodyHash`. The bounded
+     * walk itself lives in MCP's `boundedBfs` (rule of three) — the port never
+     * re-implements a BFS.
+     */
+    adjacency(pick) {
+        const gen = this.current();
+        const edges = gen === undefined ? EMPTY_EDGES : pick(gen);
+        const byBodyHash = gen?.indexes.byBodyHash;
+        return {
+            edges,
+            resolve: (bodyHash) => {
+                const occ = byBodyHash?.get(bodyHash);
+                return occ === undefined ? undefined : toSymbolRef(occ);
+            },
+        };
+    }
+    blast(symbolId) {
+        const gen = this.current();
+        if (gen === undefined)
+            return ok(this.empty());
+        const occ = gen.indexes.byOccId.get(symbolId);
+        if (occ === undefined)
+            return ok(this.empty());
+        const score = this.blastScores(gen).get(occ.bodyHash);
+        if (score === undefined)
+            return ok(this.empty());
+        return ok(this.wrap({ symbol: toSymbolRef(occ), ...score }));
+    }
+    /** Memoized blast table — the canonical `buildFeatures(['blast'])` scoring. */
+    blastScores(gen) {
+        if (this.blastCache !== undefined)
+            return this.blastCache;
+        const columns = ['blast'];
+        const features = buildFeatures(gen.catalog, gen.indexes, this.config, columns);
+        const out = new Map();
+        for (const [hash, row] of features.function) {
+            if (row.blast !== undefined) {
+                out.set(hash, {
+                    direct: row.blast.direct,
+                    transitive: row.blast.transitive,
+                    score: row.blast.score,
+                });
+            }
+        }
+        this.blastCache = out;
+        return out;
+    }
+    deadCode(limit) {
+        const gen = this.current();
+        if (gen === undefined)
+            return ok(this.wrap([]));
+        const columns = ['reachableFromEntry'];
+        const features = buildFeatures(gen.catalog, gen.indexes, this.config, columns);
+        const signals = orphanSubtreeRule.evaluate(gen.catalog, gen.indexes, this.config, undefined, features);
+        const entries = [];
+        let truncated = false;
+        for (const signal of signals) {
+            if (limit !== undefined && entries.length >= limit) {
+                truncated = true;
+                break;
+            }
+            const dto = toDeadCodeDto(signal, gen.indexes);
+            if (dto !== undefined)
+                entries.push(dto);
+        }
+        return ok(this.wrap(entries, truncated));
+    }
+    architectureSummary(limit) {
+        const gen = this.current();
+        if (gen === undefined) {
+            return ok(this.wrap({ functionCount: 0, edgeCount: 0, languages: [], packages: [], hotspots: [] }));
+        }
+        const columns = ['packageCoupling'];
+        const features = buildFeatures(gen.catalog, gen.indexes, this.config, columns);
+        const cap = clampLimit(limit, DEFAULT_ARCH_LIMIT);
+        const rows = [];
+        for (const [name, row] of features.package) {
+            rows.push({ name, couplingOut: row.couplingOut, couplingIn: row.couplingIn });
+        }
+        rows.sort((a, b) => b.couplingOut + b.couplingIn - (a.couplingOut + a.couplingIn));
+        const packages = rows.slice(0, cap);
+        const hotspots = this.topHotspots(gen, cap);
+        return ok(this.wrap({
+            functionCount: gen.indexes.byBodyHash.size,
+            edgeCount: edgeCount(gen.indexes),
+            languages: [gen.catalog.language],
+            packages,
+            hotspots,
+        }, packages.length < rows.length));
+    }
+    /** The `cap` highest-blast symbols (graph's canonical scoring; reused, not reinvented). */
+    topHotspots(gen, cap) {
+        const scores = this.blastScores(gen);
+        const ranked = [];
+        for (const [hash, score] of scores) {
+            const occ = gen.indexes.byBodyHash.get(hash);
+            if (occ !== undefined)
+                ranked.push({ symbol: toSymbolRef(occ), ...score });
+        }
+        ranked.sort((a, b) => b.score - a.score);
+        return ranked.slice(0, cap);
+    }
+    async refresh() {
+        const rebuild = this.deps.rebuild;
+        if (rebuild === undefined) {
+            return err(readError('refresh-unavailable', 'graph refresh is not wired (the rebuild provider is supplied by the host command).'));
+        }
+        // Serialize concurrent refreshes to ONE rebuild: a second caller awaits the
+        // in-flight build rather than launching a duplicate. In-flight reads keep the
+        // prior generation until the swap completes (TOCTOU-safe; catalog-generation.ts).
+        this.inFlightRefresh ??= this.runRebuild(rebuild);
+        try {
+            return await this.inFlightRefresh;
+        }
+        finally {
+            this.inFlightRefresh = undefined;
+        }
+    }
+    /** One rebuild: runs the provider, then swaps the generation atomically on success. */
+    async runRebuild(rebuild) {
+        // The rebuild runs `runGraph` at a genuine infra boundary; its throw (child
+        // build failure) propagates to the caller (the tool logs the decision point).
+        const catalog = await rebuild();
+        this.generation = createGeneration(catalog);
+        this.loaded = true;
+        this.invalidateDerived();
+        return ok(this.wrap({ builtAt: this.generation.builtAt }));
+    }
+}
+// ── pure helpers ────────────────────────────────────────────────────
+function toSymbolRef(occ) {
+    return {
+        symbolId: `${occ.filePath}:${String(occ.line)}:${String(occ.column)}`,
+        bodyHash: occ.bodyHash,
+        qualifiedName: occ.qualifiedName,
+        filePath: occ.filePath,
+        line: occ.line,
+        column: occ.column,
+        kind: occ.kind,
+        visibility: occ.visibility,
+    };
+}
+/** Map an `graph:orphan-subtree` signal to a {@link DeadCodeDto} (no FS reads). */
+function toDeadCodeDto(signal, indexes) {
+    const code = signal.code;
+    if (code?.file === undefined || code.line === undefined || code.column === undefined) {
+        return undefined;
+    }
+    const occ = indexes.byOccId.get(`${code.file}:${String(code.line)}:${String(code.column)}`);
+    if (occ === undefined)
+        return undefined;
+    return { symbol: toSymbolRef(occ), message: signal.message };
+}
+/** Total out-edge count across the callees adjacency. */
+function edgeCount(indexes) {
+    let total = 0;
+    for (const targets of indexes.callees.values())
+        total += targets.length;
+    return total;
+}
+/** Clamp a caller-supplied limit to a positive integer, defaulting when absent. */
+function clampLimit(limit, fallback) {
+    if (limit === undefined || !Number.isFinite(limit) || limit <= 0)
+        return fallback;
+    return Math.trunc(limit);
+}
+//# sourceMappingURL=sqlite-graph-read-port.js.map

package/dist/sqlite-graph-read-port.js.map

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

package/dist/symbol-dto.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Symbol + freshness DTOs for the MCP read ports (ADR-0084).
+ *
+ * These are the *only* graph shapes that cross the {@link GraphReadPort}
+ * boundary — the SQLite impl never leaks `Catalog` / `Indexes` to handlers
+ * (SaaS parity: an alternate storage backend can substitute behind the same
+ * narrow port). DTOs carry symbol METADATA only (qualified name, path, span,
+ * kind, visibility, `bodyHash`) — never raw file bodies (`bodyHash` is a hash,
+ * not source).
+ */
+/**
+ * A single resolved symbol occurrence. `symbolId` is the stable identity
+ * downstream tools accept (never a bare name): `"${filePath}:${line}:${column}"`.
+ */
+export interface SymbolRef {
+    /** Stable identity: `"${filePath}:${line}:${column}"`. */
+    readonly symbolId: string;
+    /** sha256(normalized body) — the graph's content identifier. */
+    readonly bodyHash: string;
+    /** Human-display qualified name (e.g. `"fitness/engine/src/gate.saveBaseline"`). */
+    readonly qualifiedName: string;
+    /** Project-relative path. */
+    readonly filePath: string;
+    /** 1-based line where the declaration begins. */
+    readonly line: number;
+    /** 0-based column. */
+    readonly column: number;
+    /** Function kind (`'function'`, `'method'`, `'arrow'`, …). */
+    readonly kind: string;
+    /** Visibility (`'exported'`, `'private'`, …). */
+    readonly visibility: string;
+}
+/**
+ * Freshness verdict for the served catalog generation. Derived from the graph
+ * engine's `classifyCatalog` (never a filesystem mtime heuristic outside the
+ * engine). A missing catalog ⇒ `fresh: false` with empty data — never a silent
+ * auto-build.
+ */
+export interface Freshness {
+    /** `true` only when the persisted catalog matches the current file set. */
+    readonly fresh: boolean;
+    /** ISO timestamp the served generation was built at (absent when missing). */
+    readonly builtAt?: string;
+    /** Why the catalog is stale/missing (`'missing'`, `'language-changed'`, …). */
+    readonly reason?: string;
+}
+/**
+ * The shared graph-read envelope: every {@link GraphReadPort} read carries
+ * `{ data, freshness }` so an agent always sees whether the answer came from a
+ * fresh, stale, or missing catalog. `truncated` is set when a bounded walk or
+ * search hit its node/result cap.
+ */
+export interface McpToolResult<T> {
+    readonly data: T;
+    readonly freshness: Freshness;
+    readonly truncated?: boolean;
+}
+//# sourceMappingURL=symbol-dto.d.ts.map

package/dist/symbol-dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-dto.d.ts","sourceRoot":"","sources":["../src/symbol-dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/symbol-dto.js

@@ -0,0 +1,12 @@
+/**
+ * Symbol + freshness DTOs for the MCP read ports (ADR-0084).
+ *
+ * These are the *only* graph shapes that cross the {@link GraphReadPort}
+ * boundary — the SQLite impl never leaks `Catalog` / `Indexes` to handlers
+ * (SaaS parity: an alternate storage backend can substitute behind the same
+ * narrow port). DTOs carry symbol METADATA only (qualified name, path, span,
+ * kind, visibility, `bodyHash`) — never raw file bodies (`bodyHash` is a hash,
+ * not source).
+ */
+export {};
+//# sourceMappingURL=symbol-dto.js.map

package/dist/symbol-dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-dto.js","sourceRoot":"","sources":["../src/symbol-dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/tool.d.ts

@@ -0,0 +1,6 @@
+import type { Tool, ToolIdentity } from '@opensip-cli/core';
+export declare const MCP_IDENTITY: ToolIdentity;
+/** Stable UUID identity (ADR-0048); mirrors `opensipTools.stableId` in package.json. */
+export declare const MCP_STABLE_ID = "f313c020-5b48-4e17-a579-e303907b6392";
+export declare const mcpTool: Tool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE5D,eAAO,MAAM,YAAY,EAAE,YAE1B,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,aAAa,yCAAyC,CAAC;AAEpE,eAAO,MAAM,OAAO,EAAE,IAWpB,CAAC"}

package/dist/tool.js

@@ -0,0 +1,33 @@
+/**
+ * `@opensip-cli/mcp` Tool descriptor (ADR-0084).
+ *
+ * A bundled, first-party tool that serves the OpenSIP call graph + stored run
+ * results to MCP-capable coding agents over stdio. The single `mcp` command is
+ * declarative and mounted by the host (added in plan Phase 3); this descriptor
+ * also declares the `mcp-graph-adapter` capability domain so the bundled `graph-*`
+ * adapter packs load under `opensip mcp` and route through MCP's own registrar.
+ *
+ * This module does NOT import from `@opensip-cli/cli` — a tool engine (layer 4)
+ * never depends on the composition root.
+ */
+import { defineTool, readPackageVersion } from '@opensip-cli/core';
+import { mcpCommandSpec } from './command.js';
+import { registerMcpGraphAdapter } from './register-mcp-graph-adapters.js';
+export const MCP_IDENTITY = {
+    name: 'mcp',
+};
+/** Stable UUID identity (ADR-0048); mirrors `opensipTools.stableId` in package.json. */
+export const MCP_STABLE_ID = 'f313c020-5b48-4e17-a579-e303907b6392';
+export const mcpTool = defineTool({
+    identity: MCP_IDENTITY,
+    metadata: {
+        id: MCP_STABLE_ID,
+        version: readPackageVersion(import.meta.url),
+        description: 'MCP server for the OpenSIP call graph and stored results',
+    },
+    commandSpecs: [mcpCommandSpec],
+    extensionPoints: {
+        capabilityRegistrars: { 'mcp-graph-adapter': registerMcpGraphAdapter },
+    },
+});
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAI3E,MAAM,CAAC,MAAM,YAAY,GAAiB;IACxC,IAAI,EAAE,KAAK;CACZ,CAAC;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,aAAa,GAAG,sCAAsC,CAAC;AAEpE,MAAM,CAAC,MAAM,OAAO,GAAS,UAAU,CAAC;IACtC,QAAQ,EAAE,YAAY;IACtB,QAAQ,EAAE;QACR,EAAE,EAAE,aAAa;QACjB,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAC5C,WAAW,EAAE,0DAA0D;KACxE;IACD,YAAY,EAAE,CAAC,cAAc,CAAC;IAC9B,eAAe,EAAE;QACf,oBAAoB,EAAE,EAAE,mBAAmB,EAAE,uBAAuB,EAAE;KACvE;CACF,CAAC,CAAC"}

package/dist/tools/__tests__/graph-handlers.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Graph tool handlers vs. a FAKE `GraphReadPort` (Task 6.1 steps 1–3).
+ *
+ * Each handler is registered through a capturing fake server, then invoked
+ * directly with already-valid args (Zod boundary validation is covered in
+ * schemas.test.ts). Asserts freshness stamping, `truncated` metadata, symbolId
+ * resolution errors (unknown id → structured error), `get_symbol` span/ambiguity
+ * behavior, and that no DTO carries a raw file body (metadata + bodyHash only).
+ */
+export {};
+//# sourceMappingURL=graph-handlers.test.d.ts.map

package/dist/tools/__tests__/graph-handlers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-handlers.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/graph-handlers.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}