ralph-hero-knowledge-index 0.1.13 → 0.1.15

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-knowledge",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Knowledge graph for ralph-hero: semantic search, relationship traversal, and document indexing across thoughts/ documents. Optional companion to ralph-hero.",
   "author": {
     "name": "Chad Dubiel",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "ralph-knowledge": {
       "command": "npx",
-      "args": ["-y", "ralph-hero-knowledge-index@0.1.13"]
+      "args": ["-y", "ralph-hero-knowledge-index@0.1.15"]
     }
   }
 }

package/dist/db.d.ts

@@ -1,30 +1,116 @@
 import type { Database as DatabaseType } from "better-sqlite3";
 export interface DocumentRow {
     id: string;
-    path: string;
+    path: string | null;
     title: string;
     date: string | null;
     type: string | null;
     status: string | null;
     githubIssue: number | null;
     content: string;
+    isStub: number;
 }
 export interface RelationshipRow {
     sourceId: string;
     targetId: string;
     type: string;
+    context: string | null;
+}
+export interface OutcomeEventInput {
+    eventType: string;
+    issueNumber: number;
+    sessionId?: string;
+    durationMs?: number;
+    verdict?: string;
+    componentArea?: string;
+    estimate?: string;
+    driftCount?: number;
+    model?: string;
+    agentType?: string;
+    iterationCount?: number;
+    payload?: Record<string, unknown>;
+}
+export interface OutcomeEventRow {
+    id: string;
+    eventType: string;
+    issueNumber: number;
+    sessionId: string | null;
+    timestamp: string;
+    durationMs: number | null;
+    verdict: string | null;
+    componentArea: string | null;
+    estimate: string | null;
+    driftCount: number | null;
+    model: string | null;
+    agentType: string | null;
+    iterationCount: number | null;
+    payload: string;
+}
+export interface SyncRecord {
+    path: string;
+    mtime: number;
+    indexed_at: number;
+}
+export interface OutcomeQueryParams {
+    issueNumber?: number;
+    eventType?: string;
+    componentArea?: string;
+    estimate?: string;
+    verdict?: string;
+    sessionId?: string;
+    since?: string;
+    limit?: number;
+}
+export interface OutcomeAggregate {
+    count: number;
+    avgDriftCount: number | null;
+    avgIterationCount: number | null;
+    verdictDistribution: Record<string, number>;
+    eventTypeDistribution: Record<string, number>;
+    topComponentAreas: Array<{
+        area: string;
+        count: number;
+    }>;
+}
+export interface OutcomeSummary {
+    totalEvents: number;
+    latestVerdict: string | null;
+    driftCount: number;
+    blockers: number;
+    eventsByType: Record<string, number>;
 }
 export declare class KnowledgeDB {
     readonly db: DatabaseType;
     constructor(dbPath: string);
     private createSchema;
-    upsertDocument(doc: DocumentRow): void;
+    upsertDocument(doc: Omit<DocumentRow, "isStub"> & {
+        isStub?: number;
+    }): void;
+    /**
+     * Creates a stub document for an unresolved wikilink target.
+     * Uses INSERT OR IGNORE so it never overwrites a real document.
+     */
+    upsertStubDocument(id: string): void;
     getDocument(id: string): DocumentRow | undefined;
     setTags(docId: string, tags: string[]): void;
     getTags(docId: string): string[];
-    addRelationship(sourceId: string, targetId: string, type: string): void;
+    addRelationship(sourceId: string, targetId: string, type: string, context?: string): void;
     getRelationshipsFrom(sourceId: string): RelationshipRow[];
     getRelationshipsTo(targetId: string): RelationshipRow[];
+    insertOutcomeEvent(input: OutcomeEventInput): {
+        id: string;
+        eventType: string;
+        issueNumber: number;
+        timestamp: string;
+    };
+    queryOutcomeEvents(params?: OutcomeQueryParams): OutcomeEventRow[];
+    aggregateOutcomeEvents(params?: OutcomeQueryParams): OutcomeAggregate;
+    getOutcomeSummary(issueNumber: number): OutcomeSummary | null;
+    getSyncRecord(path: string): SyncRecord | undefined;
+    upsertSyncRecord(path: string, mtime: number): void;
+    deleteSyncRecord(path: string): void;
+    getAllSyncPaths(): string[];
+    deleteDocument(id: string): void;
     clearAll(): void;
     close(): void;
 }

package/dist/db.js

@@ -1,4 +1,5 @@
 import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 export class KnowledgeDB {
@@ -13,13 +14,14 @@ export class KnowledgeDB {
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS documents (
         id TEXT PRIMARY KEY,
-        path TEXT NOT NULL,
+        path TEXT,
         title TEXT,
         date TEXT,
         type TEXT,
         status TEXT,
         github_issue INTEGER,
-        content TEXT
+        content TEXT,
+        is_stub INTEGER DEFAULT 0
       );
       CREATE TABLE IF NOT EXISTS tags (
         doc_id TEXT REFERENCES documents(id) ON DELETE CASCADE,
@@ -28,25 +30,65 @@ export class KnowledgeDB {
       );
       CREATE TABLE IF NOT EXISTS relationships (
         source_id TEXT REFERENCES documents(id) ON DELETE CASCADE,
-        target_id TEXT,
-        type TEXT CHECK(type IN ('builds_on', 'tensions', 'superseded_by')),
+        target_id TEXT REFERENCES documents(id) ON DELETE CASCADE,
+        type TEXT CHECK(type IN ('builds_on', 'tensions', 'superseded_by', 'post_mortem', 'untyped')),
+        context TEXT,
         PRIMARY KEY (source_id, target_id, type)
       );
       CREATE INDEX IF NOT EXISTS idx_rel_target ON relationships(target_id, type);
       CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);
+
+      CREATE TABLE IF NOT EXISTS outcome_events (
+        id TEXT PRIMARY KEY,
+        event_type TEXT NOT NULL,
+        issue_number INTEGER NOT NULL,
+        session_id TEXT,
+        timestamp TEXT NOT NULL,
+        duration_ms INTEGER,
+        verdict TEXT,
+        component_area TEXT,
+        estimate TEXT,
+        drift_count INTEGER,
+        model TEXT,
+        agent_type TEXT,
+        iteration_count INTEGER,
+        payload TEXT DEFAULT '{}'
+      );
+      CREATE INDEX IF NOT EXISTS idx_oe_type ON outcome_events(event_type);
+      CREATE INDEX IF NOT EXISTS idx_oe_issue ON outcome_events(issue_number);
+      CREATE INDEX IF NOT EXISTS idx_oe_component ON outcome_events(component_area);
+      CREATE INDEX IF NOT EXISTS idx_oe_timestamp ON outcome_events(timestamp);
+      CREATE INDEX IF NOT EXISTS idx_oe_session ON outcome_events(session_id);
+      CREATE INDEX IF NOT EXISTS idx_oe_type_component ON outcome_events(event_type, component_area);
+
+      CREATE TABLE IF NOT EXISTS sync (
+        path TEXT PRIMARY KEY,
+        mtime INTEGER NOT NULL,
+        indexed_at INTEGER NOT NULL
+      );
     `);
     }
     upsertDocument(doc) {
         this.db.prepare(`
-      INSERT INTO documents (id, path, title, date, type, status, github_issue, content)
-      VALUES (@id, @path, @title, @date, @type, @status, @githubIssue, @content)
+      INSERT INTO documents (id, path, title, date, type, status, github_issue, content, is_stub)
+      VALUES (@id, @path, @title, @date, @type, @status, @githubIssue, @content, 0)
       ON CONFLICT(id) DO UPDATE SET
         path = @path, title = @title, date = @date, type = @type,
-        status = @status, github_issue = @githubIssue, content = @content
+        status = @status, github_issue = @githubIssue, content = @content, is_stub = 0
     `).run(doc);
     }
+    /**
+     * Creates a stub document for an unresolved wikilink target.
+     * Uses INSERT OR IGNORE so it never overwrites a real document.
+     */
+    upsertStubDocument(id) {
+        this.db.prepare(`
+      INSERT OR IGNORE INTO documents (id, path, title, date, type, status, github_issue, content, is_stub)
+      VALUES (?, NULL, ?, NULL, NULL, NULL, NULL, '', 1)
+    `).run(id, id);
+    }
     getDocument(id) {
-        return this.db.prepare(`SELECT id, path, title, date, type, status, github_issue AS githubIssue, content FROM documents WHERE id = ?`).get(id);
+        return this.db.prepare(`SELECT id, path, title, date, type, status, github_issue AS githubIssue, content, is_stub AS isStub FROM documents WHERE id = ?`).get(id);
     }
     setTags(docId, tags) {
         this.db.prepare("DELETE FROM tags WHERE doc_id = ?").run(docId);
@@ -57,17 +99,164 @@ export class KnowledgeDB {
     getTags(docId) {
         return this.db.prepare("SELECT tag FROM tags WHERE doc_id = ? ORDER BY tag").all(docId).map(r => r.tag);
     }
-    addRelationship(sourceId, targetId, type) {
-        this.db.prepare("INSERT OR IGNORE INTO relationships (source_id, target_id, type) VALUES (?, ?, ?)").run(sourceId, targetId, type);
+    addRelationship(sourceId, targetId, type, context) {
+        this.db.prepare("INSERT OR IGNORE INTO relationships (source_id, target_id, type, context) VALUES (?, ?, ?, ?)").run(sourceId, targetId, type, context ?? null);
     }
     getRelationshipsFrom(sourceId) {
-        return this.db.prepare("SELECT source_id AS sourceId, target_id AS targetId, type FROM relationships WHERE source_id = ?").all(sourceId);
+        return this.db.prepare("SELECT source_id AS sourceId, target_id AS targetId, type, context FROM relationships WHERE source_id = ?").all(sourceId);
     }
     getRelationshipsTo(targetId) {
-        return this.db.prepare("SELECT source_id AS sourceId, target_id AS targetId, type FROM relationships WHERE target_id = ?").all(targetId);
+        return this.db.prepare("SELECT source_id AS sourceId, target_id AS targetId, type, context FROM relationships WHERE target_id = ?").all(targetId);
+    }
+    insertOutcomeEvent(input) {
+        const id = randomUUID();
+        const timestamp = new Date().toISOString();
+        const payload = JSON.stringify(input.payload ?? {});
+        this.db.prepare(`
+      INSERT INTO outcome_events (id, event_type, issue_number, session_id, timestamp, duration_ms, verdict, component_area, estimate, drift_count, model, agent_type, iteration_count, payload)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.eventType, input.issueNumber, input.sessionId ?? null, timestamp, input.durationMs ?? null, input.verdict ?? null, input.componentArea ?? null, input.estimate ?? null, input.driftCount ?? null, input.model ?? null, input.agentType ?? null, input.iterationCount ?? null, payload);
+        return { id, eventType: input.eventType, issueNumber: input.issueNumber, timestamp };
+    }
+    queryOutcomeEvents(params = {}) {
+        const conditions = [];
+        const values = [];
+        if (params.issueNumber !== undefined) {
+            conditions.push("issue_number = ?");
+            values.push(params.issueNumber);
+        }
+        if (params.eventType !== undefined) {
+            conditions.push("event_type = ?");
+            values.push(params.eventType);
+        }
+        if (params.componentArea !== undefined) {
+            conditions.push("component_area LIKE ?");
+            values.push(`${params.componentArea}%`);
+        }
+        if (params.estimate !== undefined) {
+            conditions.push("estimate = ?");
+            values.push(params.estimate);
+        }
+        if (params.verdict !== undefined) {
+            conditions.push("verdict = ?");
+            values.push(params.verdict);
+        }
+        if (params.sessionId !== undefined) {
+            conditions.push("session_id = ?");
+            values.push(params.sessionId);
+        }
+        if (params.since !== undefined) {
+            conditions.push("timestamp >= ?");
+            values.push(params.since);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const limit = params.limit ?? 50;
+        const sql = `
+      SELECT id, event_type AS eventType, issue_number AS issueNumber, session_id AS sessionId,
+             timestamp, duration_ms AS durationMs, verdict, component_area AS componentArea,
+             estimate, drift_count AS driftCount, model, agent_type AS agentType,
+             iteration_count AS iterationCount, payload
+      FROM outcome_events ${where}
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `;
+        return this.db.prepare(sql).all(...values, limit);
+    }
+    aggregateOutcomeEvents(params = {}) {
+        // Override limit to aggregate over all matching events, not just the caller's limit
+        const rows = this.queryOutcomeEvents({ ...params, limit: undefined });
+        const verdictDistribution = {};
+        const eventTypeDistribution = {};
+        const componentCounts = {};
+        let driftSum = 0;
+        let driftCount = 0;
+        let iterSum = 0;
+        let iterCount = 0;
+        for (const row of rows) {
+            if (row.verdict !== null) {
+                verdictDistribution[row.verdict] = (verdictDistribution[row.verdict] ?? 0) + 1;
+            }
+            eventTypeDistribution[row.eventType] = (eventTypeDistribution[row.eventType] ?? 0) + 1;
+            if (row.componentArea !== null) {
+                componentCounts[row.componentArea] = (componentCounts[row.componentArea] ?? 0) + 1;
+            }
+            if (row.driftCount !== null) {
+                driftSum += row.driftCount;
+                driftCount++;
+            }
+            if (row.iterationCount !== null) {
+                iterSum += row.iterationCount;
+                iterCount++;
+            }
+        }
+        const topComponentAreas = Object.entries(componentCounts)
+            .map(([area, count]) => ({ area, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 10);
+        return {
+            count: rows.length,
+            avgDriftCount: driftCount > 0 ? driftSum / driftCount : null,
+            avgIterationCount: iterCount > 0 ? iterSum / iterCount : null,
+            verdictDistribution,
+            eventTypeDistribution,
+            topComponentAreas,
+        };
+    }
+    getOutcomeSummary(issueNumber) {
+        const rows = this.queryOutcomeEvents({ issueNumber, limit: 10000 });
+        if (rows.length === 0)
+            return null;
+        const eventsByType = {};
+        let driftCount = 0;
+        let blockers = 0;
+        let latestVerdict = null;
+        for (const row of rows) {
+            eventsByType[row.eventType] = (eventsByType[row.eventType] ?? 0) + 1;
+            if (row.driftCount !== null) {
+                driftCount += row.driftCount;
+            }
+            if (row.eventType === "blocker_recorded") {
+                blockers++;
+            }
+        }
+        // Rows are ordered by timestamp DESC, so first row has the latest verdict
+        for (const row of rows) {
+            if (row.verdict !== null) {
+                latestVerdict = row.verdict;
+                break;
+            }
+        }
+        return {
+            totalEvents: rows.length,
+            latestVerdict,
+            driftCount,
+            blockers,
+            eventsByType,
+        };
+    }
+    getSyncRecord(path) {
+        return this.db.prepare("SELECT path, mtime, indexed_at AS indexed_at FROM sync WHERE path = ?").get(path);
+    }
+    upsertSyncRecord(path, mtime) {
+        const indexedAt = Date.now();
+        this.db.prepare(`
+      INSERT INTO sync (path, mtime, indexed_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET mtime = ?, indexed_at = ?
+    `).run(path, mtime, indexedAt, mtime, indexedAt);
+    }
+    deleteSyncRecord(path) {
+        this.db.prepare("DELETE FROM sync WHERE path = ?").run(path);
+    }
+    getAllSyncPaths() {
+        return this.db.prepare("SELECT path FROM sync").all().map(r => r.path);
+    }
+    deleteDocument(id) {
+        this.db.prepare("DELETE FROM documents WHERE id = ?").run(id);
     }
     clearAll() {
-        this.db.exec("DELETE FROM relationships; DELETE FROM tags; DELETE FROM documents;");
+        // outcome_events is intentionally NOT cleared — outcome data is preserved across rebuilds
+        this.db.exec("DELETE FROM relationships; DELETE FROM tags; DELETE FROM documents; DELETE FROM sync;");
     }
     close() {
         this.db.close();

package/dist/db.js.map

@@ -1 +1 @@
-{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,MAAM,OAAO,WAAW;IACb,EAAE,CAAe;IAE1B,YAAY,MAAc;QACxB,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACrC,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;KAwBZ,CAAC,CAAC;IACL,CAAC;IAED,cAAc,CAAC,GAAgB;QAC7B,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;;;;KAMf,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACd,CAAC;IAED,WAAW,CAAC,EAAU;QACpB,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CACpB,8GAA8G,CAC/G,CAAC,GAAG,CAAC,EAAE,CAA4B,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,KAAa,EAAE,IAAc;QACnC,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,mCAAmC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,8CAA8C,CAAC,CAAC;QAC/E,KAAK,MAAM,GAAG,IAAI,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,CAAC,KAAa;QACnB,OAAQ,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,oDAAoD,CAAC,CAAC,GAAG,CAAC,KAAK,CAA4B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtI,CAAC;IAED,eAAe,CAAC,QAAgB,EAAE,QAAgB,EAAE,IAAY;QAC9D,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,mFAAmF,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACrI,CAAC;IAED,oBAAoB,CAAC,QAAgB;QACnC,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,kGAAkG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAsB,CAAC;IAChK,CAAC;IAED,kBAAkB,CAAC,QAAgB;QACjC,OAAO,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,kGAAkG,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAsB,CAAC;IAChK,CAAC;IAED,QAAQ;QACN,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IACtF,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"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"}

package/dist/format.d.ts

@@ -0,0 +1,39 @@
+import type { SearchResult } from "./search.js";
+import type { TraverseResult } from "./traverse.js";
+export interface EnrichedSearchResult extends SearchResult {
+    tags: string[];
+    outcomes_summary?: unknown;
+}
+export interface BriefSearchResult {
+    id: string;
+    title: string;
+    type: string | null;
+    date: string | null;
+    tags: string[];
+    score: number;
+}
+export interface BriefTraverseResult {
+    sourceId: string;
+    targetId: string;
+    type: string;
+    depth: number;
+    doc: {
+        title: string;
+    } | null;
+    tags: string[];
+}
+/**
+ * Format search results for return to the caller.
+ *
+ * brief=false (default): Returns the full enriched result objects unchanged.
+ * brief=true: Returns lightweight objects with id, title, type, date, tags, score only.
+ *             Strips snippet, path, status, and outcomes_summary.
+ */
+export declare function formatSearchResults(results: EnrichedSearchResult[], brief: boolean): EnrichedSearchResult[] | BriefSearchResult[];
+/**
+ * Format traverse results for return to the caller.
+ *
+ * brief=false (default): Returns the original TraverseResult objects unchanged (no tags added).
+ * brief=true: Strips doc to { title } only and adds tags array per hop target.
+ */
+export declare function formatTraverseResults(results: TraverseResult[], getTagsFn: (id: string) => string[], brief: boolean): TraverseResult[] | BriefTraverseResult[];

package/dist/format.js

@@ -0,0 +1,40 @@
+/**
+ * Format search results for return to the caller.
+ *
+ * brief=false (default): Returns the full enriched result objects unchanged.
+ * brief=true: Returns lightweight objects with id, title, type, date, tags, score only.
+ *             Strips snippet, path, status, and outcomes_summary.
+ */
+export function formatSearchResults(results, brief) {
+    if (!brief) {
+        return results;
+    }
+    return results.map((r) => ({
+        id: r.id,
+        title: r.title,
+        type: r.type,
+        date: r.date,
+        tags: r.tags,
+        score: r.score,
+    }));
+}
+/**
+ * Format traverse results for return to the caller.
+ *
+ * brief=false (default): Returns the original TraverseResult objects unchanged (no tags added).
+ * brief=true: Strips doc to { title } only and adds tags array per hop target.
+ */
+export function formatTraverseResults(results, getTagsFn, brief) {
+    if (!brief) {
+        return results;
+    }
+    return results.map((r) => ({
+        sourceId: r.sourceId,
+        targetId: r.targetId,
+        type: r.type,
+        depth: r.depth,
+        doc: r.doc != null ? { title: r.doc.title } : null,
+        tags: getTagsFn(r.targetId),
+    }));
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AA0BA;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA+B,EAC/B,KAAc;IAEd,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC;QAC5C,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAyB,EACzB,SAAmC,EACnC,KAAc;IAEd,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAuB,EAAE,CAAC,CAAC;QAC9C,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI;QAClD,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;KAC5B,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/graph-builder.d.ts

@@ -0,0 +1,17 @@
+import { MultiDirectedGraph } from "graphology";
+import type { KnowledgeDB } from "./db.js";
+export interface NodeAttributes {
+    title: string;
+    type: string | null;
+    date: string | null;
+    status: string | null;
+}
+export interface EdgeAttributes {
+    type: string;
+}
+export type KnowledgeGraph = MultiDirectedGraph<NodeAttributes, EdgeAttributes>;
+export declare class GraphBuilder {
+    private readonly db;
+    constructor(db: KnowledgeDB);
+    buildGraph(): KnowledgeGraph;
+}

package/dist/graph-builder.js

@@ -0,0 +1,35 @@
+import { MultiDirectedGraph } from "graphology";
+export class GraphBuilder {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    buildGraph() {
+        const graph = new MultiDirectedGraph();
+        // Load all documents and add as nodes
+        const docs = this.db.db
+            .prepare("SELECT id, title, date, type, status FROM documents WHERE is_stub = 0 OR is_stub IS NULL")
+            .all();
+        for (const doc of docs) {
+            graph.addNode(doc.id, {
+                title: doc.title,
+                type: doc.type,
+                date: doc.date,
+                status: doc.status,
+            });
+        }
+        // Load all relationships and add as directed edges
+        const rels = this.db.db
+            .prepare("SELECT source_id, target_id, type FROM relationships")
+            .all();
+        for (const rel of rels) {
+            // Defensively skip edges where source or target node does not exist
+            if (!graph.hasNode(rel.source_id) || !graph.hasNode(rel.target_id)) {
+                continue;
+            }
+            graph.addDirectedEdge(rel.source_id, rel.target_id, { type: rel.type });
+        }
+        return graph;
+    }
+}
+//# sourceMappingURL=graph-builder.js.map

package/dist/graph-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-builder.js","sourceRoot":"","sources":["../src/graph-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAgBhD,MAAM,OAAO,YAAY;IACN,EAAE,CAAc;IAEjC,YAAY,EAAe;QACzB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,UAAU;QACR,MAAM,KAAK,GAAmB,IAAI,kBAAkB,EAAkC,CAAC;QAEvF,sCAAsC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE;aACpB,OAAO,CAAC,0FAA0F,CAAC;aACnG,GAAG,EAMJ,CAAC;QAEH,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE;gBACpB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC;QACL,CAAC;QAED,mDAAmD;QACnD,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE;aACpB,OAAO,CAAC,sDAAsD,CAAC;aAC/D,GAAG,EAIJ,CAAC;QAEH,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,oEAAoE;YACpE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBACnE,SAAS;YACX,CAAC;YACD,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/graph-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { KnowledgeDB } from "./db.js";
+export declare function registerGraphTools(server: McpServer, db: KnowledgeDB): void;