@jafreck/lore 0.1.0

package/dist/kb-server/server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module kb-server/server
+ *
+ * Knowledge-base MCP server.
+ *
+ * Exports `createKbMcpServer()` for use by `KbServerProcess` (HTTP transport)
+ * and retains a standalone CLI entry point for development/debugging.
+ *
+ * MCP tools exposed:
+ *   kb_lookup    — symbol / file lookup
+ *   kb_graph     — call / import graph queries
+ *   kb_search    — structural, semantic, and fused search
+ *   kb_test_map  — source-file to mapped-test lookup
+ *   kb_snippet   — source-code snippet extraction
+ *   kb_blame     — git blame metadata for file lines
+ *   kb_metrics   — aggregate code metrics
+ *   kb_writeback — LLM summary write-back
+ *   kb_history   — git commit history queries
+ *
+ * Standalone usage:
+ *   node dist/kb-server/server.js --db <path-to-kb.db>
+ *   tsx src/kb-server/server.ts --db <path-to-kb.db>
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Database } from './db.js';
+import { type EmbeddingProvider } from '../indexer/embedder.js';
+/**
+ * Create and return a fully-configured `McpServer` with all KB tools registered.
+ *
+ * @param db      Read-only SQLite connection to the knowledge-base.
+ * @param dbPath  Path to the DB file, needed by `kb_writeback` for write access.
+ * @param embedder Optional live embedding provider for semantic/fused search.
+ */
+export declare function createKbMcpServer(db: Database.Database, dbPath: string, embedder?: EmbeddingProvider): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/kb-server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/kb-server/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EASL,KAAK,QAAQ,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAgC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA6D9F;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,SAAS,CAkLX"}

package/dist/kb-server/server.js

@@ -0,0 +1,240 @@
+/**
+ * @module kb-server/server
+ *
+ * Knowledge-base MCP server.
+ *
+ * Exports `createKbMcpServer()` for use by `KbServerProcess` (HTTP transport)
+ * and retains a standalone CLI entry point for development/debugging.
+ *
+ * MCP tools exposed:
+ *   kb_lookup    — symbol / file lookup
+ *   kb_graph     — call / import graph queries
+ *   kb_search    — structural, semantic, and fused search
+ *   kb_test_map  — source-file to mapped-test lookup
+ *   kb_snippet   — source-code snippet extraction
+ *   kb_blame     — git blame metadata for file lines
+ *   kb_metrics   — aggregate code metrics
+ *   kb_writeback — LLM summary write-back
+ *   kb_history   — git commit history queries
+ *
+ * Standalone usage:
+ *   node dist/kb-server/server.js --db <path-to-kb.db>
+ *   tsx src/kb-server/server.ts --db <path-to-kb.db>
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { fileURLToPath } from 'url';
+import { listCommitAuthorStats, listCommitBranchActivity, listCommitCadence, listCommitChurnByFile, listCommitMessagePrefixes, listCommitSchedule, listCommitSizes, openReadOnly, } from './db.js';
+import { getKbMeta } from '../indexer/db.js';
+import { SentenceTransformersProvider } from '../indexer/embedder.js';
+import * as lookup from './tools/lookup.js';
+import * as graph from './tools/graph.js';
+import * as search from './tools/search.js';
+import * as testMap from './tools/test-map.js';
+import * as snippet from './tools/snippet.js';
+import * as blame from './tools/blame.js';
+import * as metrics from './tools/metrics.js';
+import * as coverage from './tools/coverage.js';
+import * as writeback from './tools/writeback.js';
+import * as history from './tools/history.js';
+function handleCommitStats(db, args) {
+    const filters = {
+        limit: args.limit,
+        since: args.since,
+        until: args.until,
+        author: args.author,
+    };
+    switch (args.metric) {
+        case 'cadence':
+            return {
+                metric: args.metric,
+                day: listCommitCadence(db, 'day', filters),
+                week: listCommitCadence(db, 'week', filters),
+                month: listCommitCadence(db, 'month', filters),
+            };
+        case 'size':
+            return { metric: args.metric, commits: listCommitSizes(db, filters) };
+        case 'churn':
+            return { metric: args.metric, files: listCommitChurnByFile(db, filters) };
+        case 'authors':
+            return { metric: args.metric, authors: listCommitAuthorStats(db, filters) };
+        case 'messages':
+            return { metric: args.metric, prefixes: listCommitMessagePrefixes(db, filters) };
+        case 'schedule':
+            return { metric: args.metric, buckets: listCommitSchedule(db, filters) };
+        case 'branches':
+            return { metric: args.metric, refs: listCommitBranchActivity(db, filters) };
+    }
+}
+// ─── Server factory ───────────────────────────────────────────────────────────
+/**
+ * Create and return a fully-configured `McpServer` with all KB tools registered.
+ *
+ * @param db      Read-only SQLite connection to the knowledge-base.
+ * @param dbPath  Path to the DB file, needed by `kb_writeback` for write access.
+ * @param embedder Optional live embedding provider for semantic/fused search.
+ */
+export function createKbMcpServer(db, dbPath, embedder) {
+    const server = new McpServer({ name: 'lore-kb-server', version: '0.1.0' }, { capabilities: { tools: {} } });
+    // ── kb_lookup ──────────────────────────────────────────────────────────────
+    server.tool(lookup.toolDef.name, lookup.toolDef.description, {
+        kind: z.enum(['symbol', 'file']).describe('Whether to look up a symbol or a file.'),
+        query: z.string().describe('Symbol name or file path to look up.'),
+        branch: z.string().optional().describe('Optional branch to filter results.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(lookup.handler(db, args)) }],
+    }));
+    // ── kb_graph ───────────────────────────────────────────────────────────────
+    server.tool(graph.toolDef.name, graph.toolDef.description, {
+        kind: z
+            .enum(['call', 'import', 'module', 'inheritance'])
+            .describe('"call", "import", "module", or "inheritance" graph edges.'),
+        source_id: z.number().optional().describe('Filter edges by source node id.'),
+        limit: z.number().optional().describe('Max edges to return (default 200).'),
+        branch: z.string().optional().describe('Optional branch to filter edges.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(graph.handler(db, args)) }],
+    }));
+    // ── kb_search ──────────────────────────────────────────────────────────────
+    server.tool(search.toolDef.name, search.toolDef.description, {
+        query: z.string().describe('Search query.'),
+        mode: z
+            .enum(['structural', 'semantic', 'fused'])
+            .optional()
+            .describe('Search mode (default: structural).'),
+        limit: z.number().optional().describe('Max results (default 20).'),
+        branch: z.string().optional().describe('Optional branch to filter results.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(await search.handler(db, args, embedder)) }],
+    }));
+    // ── kb_test_map ─────────────────────────────────────────────────────────────
+    server.tool(testMap.toolDef.name, testMap.toolDef.description, {
+        source_path: z.string().describe('Source file path to resolve mapped test files for.'),
+        branch: z.string().optional().describe('Optional branch to constrain mappings.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(testMap.handler(db, args)) }],
+    }));
+    // ── kb_snippet ─────────────────────────────────────────────────────────────
+    server.tool(snippet.toolDef.name, snippet.toolDef.description, {
+        path: z.string().describe('Absolute file path as stored in the index.'),
+        start_line: z.number().optional().describe('First line (1-based, inclusive).'),
+        end_line: z.number().optional().describe('Last line (1-based, inclusive).'),
+        branch: z.string().optional().describe('Optional branch to disambiguate the file path.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(snippet.handler(db, args)) }],
+    }));
+    // ── kb_metrics ─────────────────────────────────────────────────────────────
+    server.tool(metrics.toolDef.name, metrics.toolDef.description, {}, async (_args) => ({
+        content: [{ type: 'text', text: JSON.stringify(metrics.handler(db, {})) }],
+    }));
+    // ── kb_coverage ────────────────────────────────────────────────────────────
+    server.tool(coverage.toolDef.name, coverage.toolDef.description, {
+        symbol_id: z.number().optional().describe('Optional symbol id to fetch exact coverage for.'),
+        symbol_name: z.string().optional().describe('Optional symbol name filter (case-insensitive).'),
+        path: z.string().optional().describe('Optional file path filter.'),
+        branch: z.string().optional().describe('Optional branch filter.'),
+        limit: z.number().optional().describe('Maximum symbols to return (default 50).'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(coverage.handler(db, args)) }],
+    }));
+    // ── kb_blame ───────────────────────────────────────────────────────────────
+    server.tool(blame.toolDef.name, blame.toolDef.description, {
+        path: z.string().describe('Absolute file path as stored in the index.'),
+        line: z.number().optional().describe('Single line to blame (1-based).'),
+        start_line: z.number().optional().describe('Range start line (1-based).'),
+        end_line: z.number().optional().describe('Range end line (1-based).'),
+        ref: z.string().optional().describe('Git ref to blame against (default HEAD).'),
+        branch: z.string().optional().describe('Optional branch to disambiguate indexed file path.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(blame.handler(db, args)) }],
+    }));
+    // ── kb_writeback ───────────────────────────────────────────────────────────
+    server.tool(writeback.toolDef.name, writeback.toolDef.description, {
+        symbol_id: z.number().describe('Symbol id to attach the summary to.'),
+        summary: z.string().describe('Natural-language summary text.'),
+        model: z.string().describe('Model identifier that generated the summary.'),
+        branch: z.string().optional().describe('Optional branch to validate the symbol belongs to.'),
+    }, async (args) => ({
+        content: [
+            { type: 'text', text: JSON.stringify(writeback.handler(dbPath, args)) },
+        ],
+    }));
+    // ── kb_history ─────────────────────────────────────────────────────────────
+    server.tool(history.toolDef.name, history.toolDef.description, {
+        mode: z
+            .enum(['file', 'commit', 'author', 'ref', 'recent'])
+            .describe('Query mode: file, commit, author, ref, or recent.'),
+        query: z.string().optional().describe('File path, commit SHA, author name/email, or ref.'),
+        limit: z.number().optional().describe('Max results (default 20, max 200).'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(history.handler(db, args)) }],
+    }));
+    // ── kb_commit_stats ────────────────────────────────────────────────────────
+    server.tool('kb_commit_stats', 'Return git commit analytics for a selected metric.', {
+        metric: z
+            .enum(['cadence', 'size', 'churn', 'authors', 'messages', 'schedule', 'branches'])
+            .describe('Analytics metric to compute.'),
+        limit: z.number().optional().describe('Max rows for top-N metrics (default 20, max 200).'),
+        since: z.string().optional().describe('Optional ISO date lower bound (inclusive).'),
+        until: z.string().optional().describe('Optional ISO date upper bound (inclusive).'),
+        author: z.string().optional().describe('Optional author name/email substring filter.'),
+    }, async (args) => ({
+        content: [{ type: 'text', text: JSON.stringify(handleCommitStats(db, args)) }],
+    }));
+    return server;
+}
+// ─── Embedding helper ─────────────────────────────────────────────────────────
+/**
+ * Read the embedding model stored in `kb_meta` at index time and spin up a
+ * `SentenceTransformersProvider` instance for it.  Returns `undefined` when no
+ * embedding model is recorded in the database.
+ */
+async function buildEmbedder(db) {
+    const modelName = getKbMeta(db, 'embedding_model');
+    if (!modelName)
+        return undefined;
+    const provider = new SentenceTransformersProvider(modelName);
+    try {
+        await provider.init();
+        return provider;
+    }
+    catch {
+        // Model not available — fall back to structural search only.
+        try {
+            await provider.dispose();
+        }
+        catch { /* ignore */ }
+        return undefined;
+    }
+}
+// ─── CLI argument parsing ─────────────────────────────────────────────────────
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const dbIdx = args.indexOf('--db');
+    if (dbIdx === -1 || !args[dbIdx + 1]) {
+        console.error('Usage: kb-server --db <path>');
+        process.exit(1);
+    }
+    return { dbPath: args[dbIdx + 1] };
+}
+// ─── Main (standalone CLI) ────────────────────────────────────────────────────
+async function main() {
+    const { dbPath } = parseArgs();
+    const db = openReadOnly(dbPath);
+    const embedder = await buildEmbedder(db);
+    const server = createKbMcpServer(db, dbPath, embedder);
+    // Connect via stdio transport (standalone/debug mode).
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Signal readiness to the parent process over stderr.
+    process.stderr.write('READY\n');
+}
+// Only run when executed as a standalone script, not when imported as a module.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((err) => {
+        console.error('KB server fatal error:', err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/kb-server/server.js.map

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

package/dist/kb-server/tools/annotations.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module kb-server/tools/annotations
+ *
+ * MCP tool: return indexed source-code annotations by kind.
+ */
+import type { Database } from '../db.js';
+import { listAnnotations } from '../db.js';
+export declare const toolDef: {
+    readonly name: "kb_annotations";
+    readonly description: "Return indexed annotations (TODO/FIXME/etc.) by kind, with optional file path filter and result limit.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["TODO", "FIXME", "HACK", "XXX", "NOTE", "BUG", "OPTIMIZE"];
+                readonly description: "Annotation kind/tag to filter by.";
+            };
+            readonly path: {
+                readonly type: "string";
+                readonly description: "Optional exact file path filter.";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "Maximum number of results to return (default 20).";
+            };
+        };
+        readonly required: readonly ["kind"];
+    };
+};
+export interface AnnotationsArgs {
+    kind: 'TODO' | 'FIXME' | 'HACK' | 'XXX' | 'NOTE' | 'BUG' | 'OPTIMIZE';
+    path?: string;
+    limit?: number;
+}
+export interface AnnotationsResult {
+    results: ReturnType<typeof listAnnotations>;
+}
+export declare function handler(db: Database.Database, args: AnnotationsArgs): AnnotationsResult;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/kb-server/tools/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../../src/kb-server/tools/annotations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;CAuBV,CAAC;AAEX,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;CAC7C;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,eAAe,GAAG,iBAAiB,CAIvF"}

package/dist/kb-server/tools/annotations.js

@@ -0,0 +1,35 @@
+/**
+ * @module kb-server/tools/annotations
+ *
+ * MCP tool: return indexed source-code annotations by kind.
+ */
+import { listAnnotations } from '../db.js';
+export const toolDef = {
+    name: 'kb_annotations',
+    description: 'Return indexed annotations (TODO/FIXME/etc.) by kind, with optional file path filter and result limit.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            kind: {
+                type: 'string',
+                enum: ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE', 'BUG', 'OPTIMIZE'],
+                description: 'Annotation kind/tag to filter by.',
+            },
+            path: {
+                type: 'string',
+                description: 'Optional exact file path filter.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of results to return (default 20).',
+            },
+        },
+        required: ['kind'],
+    },
+};
+export function handler(db, args) {
+    return {
+        results: listAnnotations(db, args.kind, args.path, args.limit ?? 20),
+    };
+}
+//# sourceMappingURL=annotations.js.map

package/dist/kb-server/tools/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../../src/kb-server/tools/annotations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,IAAI,EAAE,gBAAgB;IACtB,WAAW,EACT,wGAAwG;IAC1G,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC;gBACjE,WAAW,EAAE,mCAAmC;aACjD;YACD,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,kCAAkC;aAChD;YACD,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,mDAAmD;aACjE;SACF;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACnB;CACO,CAAC;AAYX,MAAM,UAAU,OAAO,CAAC,EAAqB,EAAE,IAAqB;IAClE,OAAO;QACL,OAAO,EAAE,eAAe,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;KACrE,CAAC;AACJ,CAAC"}

package/dist/kb-server/tools/architecture.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module kb-server/tools/architecture
+ *
+ * MCP tool: return a high-level architecture view grouped by path depth.
+ */
+import type { Database } from '../db.js';
+export declare const toolDef: {
+    readonly name: "kb_architecture";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly depth: {
+                readonly type: "number";
+                readonly description: "Optional path depth used to group files into components (default 2).";
+            };
+            readonly branch: {
+                readonly type: "string";
+                readonly description: "Optional branch name to filter architecture output.";
+            };
+        };
+        readonly required: readonly [];
+    };
+};
+export interface ArchitectureArgs {
+    depth?: number;
+    branch?: string;
+}
+export interface ArchitectureComponent {
+    component: string;
+    branch: string;
+    file_count: number;
+    symbol_count: number;
+    module_count: number;
+}
+export interface ArchitectureEdge {
+    source_component: string;
+    target_component: string;
+    branch: string;
+    edge_count: number;
+}
+export interface ArchitectureNode {
+    component: string;
+    branch: string;
+}
+export interface ArchitectureExternalDep {
+    component: string;
+    branch: string;
+    package: string;
+    file_count: number;
+}
+export interface ArchitectureResult {
+    components: ArchitectureComponent[];
+    edges: ArchitectureEdge[];
+    entry_points: ArchitectureNode[];
+    leaf_nodes: ArchitectureNode[];
+    external_deps: ArchitectureExternalDep[];
+}
+export declare function handler(db: Database.Database, args: ArchitectureArgs): ArchitectureResult;
+//# sourceMappingURL=architecture.d.ts.map

package/dist/kb-server/tools/architecture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture.d.ts","sourceRoot":"","sources":["../../../src/kb-server/tools/architecture.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;CAmBV,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,aAAa,EAAE,uBAAuB,EAAE,CAAC;CAC1C;AAUD,wBAAgB,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,CAsKzF"}

package/dist/kb-server/tools/architecture.js

@@ -0,0 +1,174 @@
+/**
+ * @module kb-server/tools/architecture
+ *
+ * MCP tool: return a high-level architecture view grouped by path depth.
+ */
+export const toolDef = {
+    name: 'kb_architecture',
+    description: 'Return an architecture overview grouped by path prefix, including component summaries, ' +
+        'inter-component edges, entry points, leaf nodes, and external dependency usage.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            depth: {
+                type: 'number',
+                description: 'Optional path depth used to group files into components (default 2).',
+            },
+            branch: {
+                type: 'string',
+                description: 'Optional branch name to filter architecture output.',
+            },
+        },
+        required: [],
+    },
+};
+function toComponent(path, depth) {
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length === 0) {
+        return '.';
+    }
+    return parts.slice(0, depth).join('/');
+}
+export function handler(db, args) {
+    const depth = Math.max(1, Math.floor(args.depth ?? 2));
+    const fileRows = (args.branch !== undefined
+        ? db
+            .prepare(`SELECT f.id,
+                    f.path,
+                    f.branch,
+                    COUNT(DISTINCT s.id) AS symbol_count,
+                    COUNT(DISTINCT m.id) AS module_count
+               FROM files f
+               LEFT JOIN symbols s ON s.file_id = f.id
+               LEFT JOIN file_modules fm ON fm.file_id = f.id
+               LEFT JOIN modules m ON m.id = fm.module_id
+              WHERE f.branch = ?
+              GROUP BY f.id, f.path, f.branch`)
+            .all(args.branch)
+        : db
+            .prepare(`SELECT f.id,
+                    f.path,
+                    f.branch,
+                    COUNT(DISTINCT s.id) AS symbol_count,
+                    COUNT(DISTINCT m.id) AS module_count
+               FROM files f
+               LEFT JOIN symbols s ON s.file_id = f.id
+               LEFT JOIN file_modules fm ON fm.file_id = f.id
+               LEFT JOIN modules m ON m.id = fm.module_id
+              GROUP BY f.id, f.path, f.branch`)
+            .all());
+    const filesById = new Map(fileRows.map((row) => [row.id, row]));
+    const componentsMap = new Map();
+    for (const row of fileRows) {
+        const component = toComponent(row.path, depth);
+        const key = `${row.branch}\u0000${component}`;
+        const existing = componentsMap.get(key);
+        if (existing !== undefined) {
+            existing.file_count += 1;
+            existing.symbol_count += row.symbol_count;
+            existing.module_count += row.module_count;
+            continue;
+        }
+        componentsMap.set(key, {
+            component,
+            branch: row.branch,
+            file_count: 1,
+            symbol_count: row.symbol_count,
+            module_count: row.module_count,
+        });
+    }
+    const importRows = (args.branch !== undefined
+        ? db
+            .prepare(`SELECT fi.file_id, fi.resolved_id, f_src.branch
+               FROM file_imports fi
+               JOIN files f_src ON f_src.id = fi.file_id
+              WHERE f_src.branch = ?`)
+            .all(args.branch)
+        : db
+            .prepare(`SELECT fi.file_id, fi.resolved_id, f_src.branch
+               FROM file_imports fi
+               JOIN files f_src ON f_src.id = fi.file_id`)
+            .all());
+    const edgesMap = new Map();
+    const inboundByNode = new Map();
+    const outboundByNode = new Map();
+    for (const row of importRows) {
+        if (row.resolved_id === null) {
+            continue;
+        }
+        const srcFile = filesById.get(row.file_id);
+        const dstFile = filesById.get(row.resolved_id);
+        if (srcFile === undefined || dstFile === undefined || srcFile.branch !== dstFile.branch) {
+            continue;
+        }
+        const sourceComponent = toComponent(srcFile.path, depth);
+        const targetComponent = toComponent(dstFile.path, depth);
+        const edgeKey = `${row.branch}\u0000${sourceComponent}\u0000${targetComponent}`;
+        const existing = edgesMap.get(edgeKey);
+        if (existing !== undefined) {
+            existing.edge_count += 1;
+        }
+        else {
+            edgesMap.set(edgeKey, {
+                source_component: sourceComponent,
+                target_component: targetComponent,
+                branch: row.branch,
+                edge_count: 1,
+            });
+        }
+        const sourceNodeKey = `${row.branch}\u0000${sourceComponent}`;
+        const targetNodeKey = `${row.branch}\u0000${targetComponent}`;
+        outboundByNode.set(sourceNodeKey, (outboundByNode.get(sourceNodeKey) ?? 0) + 1);
+        inboundByNode.set(targetNodeKey, (inboundByNode.get(targetNodeKey) ?? 0) + 1);
+    }
+    const entryPoints = [];
+    const leafNodes = [];
+    for (const component of componentsMap.values()) {
+        const nodeKey = `${component.branch}\u0000${component.component}`;
+        if ((inboundByNode.get(nodeKey) ?? 0) === 0) {
+            entryPoints.push({ branch: component.branch, component: component.component });
+        }
+        if ((outboundByNode.get(nodeKey) ?? 0) === 0) {
+            leafNodes.push({ branch: component.branch, component: component.component });
+        }
+    }
+    const externalDepsRows = (args.branch !== undefined
+        ? db
+            .prepare(`SELECT f.path, f.branch, ed.package, COUNT(DISTINCT f.id) AS file_count
+               FROM external_deps ed
+               JOIN files f ON f.id = ed.file_id
+              WHERE f.branch = ?
+              GROUP BY f.path, f.branch, ed.package`)
+            .all(args.branch)
+        : db
+            .prepare(`SELECT f.path, f.branch, ed.package, COUNT(DISTINCT f.id) AS file_count
+               FROM external_deps ed
+               JOIN files f ON f.id = ed.file_id
+              GROUP BY f.path, f.branch, ed.package`)
+            .all());
+    const externalDepsMap = new Map();
+    for (const row of externalDepsRows) {
+        const component = toComponent(row.path, depth);
+        const depKey = `${row.branch}\u0000${component}\u0000${row.package}`;
+        const existing = externalDepsMap.get(depKey);
+        if (existing !== undefined) {
+            existing.file_count += row.file_count;
+        }
+        else {
+            externalDepsMap.set(depKey, {
+                component,
+                branch: row.branch,
+                package: row.package,
+                file_count: row.file_count,
+            });
+        }
+    }
+    return {
+        components: Array.from(componentsMap.values()),
+        edges: Array.from(edgesMap.values()),
+        entry_points: entryPoints,
+        leaf_nodes: leafNodes,
+        external_deps: Array.from(externalDepsMap.values()),
+    };
+}
+//# sourceMappingURL=architecture.js.map

package/dist/kb-server/tools/architecture.js.map

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