@mcp-graph-workflow/mcp-graph 3.0.0

package/dist/core/context/context-assembler.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Context Assembler — combines graph context + knowledge + Serena + docs
+ * with token accounting per section. Produces a structured, budgeted context
+ * suitable for LLM consumption.
+ */
+import type { SqliteStore } from "../store/sqlite-store.js";
+import { type ContextTier } from "./tiered-context.js";
+export interface AssembledContext {
+    /** The query used to assemble context */
+    query: string;
+    /** Tier used for node context */
+    tier: ContextTier;
+    /** Assembled sections with token accounting */
+    sections: ContextSection[];
+    /** Token usage breakdown */
+    tokenUsage: {
+        budget: number;
+        used: number;
+        remaining: number;
+        breakdown: Record<string, number>;
+    };
+}
+export interface ContextSection {
+    name: string;
+    source: string;
+    content: string;
+    tokens: number;
+}
+export interface AssemblerOptions {
+    /** Total token budget (default: 4000) */
+    tokenBudget?: number;
+    /** Context tier (default: "standard") */
+    tier?: ContextTier;
+    /** Node IDs to include (if empty, uses FTS search) */
+    nodeIds?: string[];
+    /** Max knowledge chunks to include (default: 5) */
+    maxKnowledgeChunks?: number;
+}
+/**
+ * Assemble a multi-source context with token budgeting.
+ */
+export declare function assembleContext(store: SqliteStore, query: string, options?: AssemblerOptions): AssembledContext;
+//# sourceMappingURL=context-assembler.d.ts.map

package/dist/core/context/context-assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-assembler.d.ts","sourceRoot":"","sources":["../../../src/core/context/context-assembler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAsB,KAAK,WAAW,EAAsB,MAAM,qBAAqB,CAAC;AAK/F,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4BAA4B;IAC5B,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACnC,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,GACzB,gBAAgB,CAuGlB"}

package/dist/core/context/context-assembler.js

@@ -0,0 +1,113 @@
+/**
+ * Context Assembler — combines graph context + knowledge + Serena + docs
+ * with token accounting per section. Produces a structured, budgeted context
+ * suitable for LLM consumption.
+ */
+import { KnowledgeStore } from "../store/knowledge-store.js";
+import { buildTieredContext } from "./tiered-context.js";
+import { compressWithBm25 } from "./bm25-compressor.js";
+import { estimateTokens } from "./token-estimator.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Assemble a multi-source context with token budgeting.
+ */
+export function assembleContext(store, query, options) {
+    const tokenBudget = options?.tokenBudget ?? 4000;
+    const tier = options?.tier ?? "standard";
+    const maxKnowledgeChunks = options?.maxKnowledgeChunks ?? 5;
+    const sections = [];
+    const breakdown = {};
+    let tokensUsed = 0;
+    // Budget allocation: 60% graph, 30% knowledge, 10% header
+    const graphBudget = Math.floor(tokenBudget * 0.6);
+    const knowledgeBudget = Math.floor(tokenBudget * 0.3);
+    // Section 1: Graph context for specified or searched nodes
+    const nodeIds = options?.nodeIds ?? findRelevantNodeIds(store, query);
+    for (const nodeId of nodeIds) {
+        if (tokensUsed >= graphBudget)
+            break;
+        const ctx = buildTieredContext(store, nodeId, tier);
+        if (!ctx)
+            continue;
+        if (tokensUsed + ctx.estimatedTokens > graphBudget && sections.length > 0)
+            break;
+        const content = JSON.stringify(ctx, null, 0);
+        const tokens = estimateTokens(content);
+        sections.push({
+            name: `node:${ctx.summary.title}`,
+            source: "graph",
+            content,
+            tokens,
+        });
+        tokensUsed += tokens;
+    }
+    breakdown.graph = tokensUsed;
+    // Section 2: Knowledge context (BM25-compressed)
+    const knowledgeTokensBefore = tokensUsed;
+    try {
+        const knowledgeStore = new KnowledgeStore(store.getDb());
+        const kResults = knowledgeStore.search(query, maxKnowledgeChunks * 2);
+        if (kResults.length > 0) {
+            const chunks = kResults.map((r) => `[${r.sourceType}] ${r.title}: ${r.content}`);
+            const compressed = compressWithBm25(chunks, query, knowledgeBudget);
+            for (const chunk of compressed) {
+                if (tokensUsed + chunk.tokens > tokenBudget && sections.length > 0)
+                    break;
+                sections.push({
+                    name: `knowledge:${chunk.content.slice(0, 40)}...`,
+                    source: "knowledge",
+                    content: chunk.content,
+                    tokens: chunk.tokens,
+                });
+                tokensUsed += chunk.tokens;
+            }
+        }
+    }
+    catch {
+        logger.debug("Knowledge search unavailable during assembly");
+    }
+    breakdown.knowledge = tokensUsed - knowledgeTokensBefore;
+    logger.debug("context:breakdown", {
+        graphTokens: breakdown.graph,
+        knowledgeTokens: breakdown.knowledge,
+        sections: sections.map((s) => `${s.name}:${s.tokens}`).join(", "),
+    });
+    if (tokensUsed > tokenBudget) {
+        logger.warn("context:budget-exceeded", { tokensUsed, tokenBudget, overage: tokensUsed - tokenBudget });
+    }
+    const truncatedSections = nodeIds.length - sections.filter((s) => s.source === "graph").length;
+    if (truncatedSections > 0) {
+        logger.warn("context:sections-truncated", { truncatedSections, reason: "token budget" });
+    }
+    logger.info("Context assembled", {
+        query: query.slice(0, 50),
+        tier,
+        sections: sections.length,
+        tokensUsed,
+        budget: tokenBudget,
+    });
+    return {
+        query,
+        tier,
+        sections,
+        tokenUsage: {
+            budget: tokenBudget,
+            used: tokensUsed,
+            remaining: Math.max(0, tokenBudget - tokensUsed),
+            breakdown,
+        },
+    };
+}
+/**
+ * Find relevant node IDs via FTS search.
+ */
+function findRelevantNodeIds(store, query) {
+    try {
+        const results = store.searchNodes(query, 5);
+        return results.map((r) => r.id);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=context-assembler.js.map

package/dist/core/context/context-assembler.js.map

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

package/dist/core/context/rag-context.d.ts

@@ -0,0 +1,44 @@
+/**
+ * RAG Context Builder — builds a compact context from search results
+ * suitable for LLM consumption with token budget management.
+ */
+import type { SqliteStore } from "../store/sqlite-store.js";
+import { type TaskContext } from "./compact-context.js";
+export interface KnowledgeSummary {
+    id: string;
+    sourceType: string;
+    title: string;
+    content: string;
+    score: number;
+}
+export interface RagContext {
+    query: string;
+    relevantNodes: RagNodeSummary[];
+    knowledgeResults: KnowledgeSummary[];
+    expandedContexts: TaskContext[];
+    tokenUsage: {
+        budget: number;
+        used: number;
+        remaining: number;
+    };
+}
+interface RagNodeSummary {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    priority: number;
+    description?: string;
+    tags?: string[];
+    score: number;
+}
+/**
+ * Build a RAG context from a natural language query.
+ *
+ * 1. Search for relevant nodes via FTS5
+ * 2. Expand subgraph context for top results via buildTaskContext
+ * 3. Manage token budget to stay within limits
+ */
+export declare function ragBuildContext(store: SqliteStore, query: string, tokenBudget?: number): RagContext;
+export {};
+//# sourceMappingURL=rag-context.d.ts.map

package/dist/core/context/rag-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-context.d.ts","sourceRoot":"","sources":["../../../src/core/context/rag-context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAI1E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;IACrC,gBAAgB,EAAE,WAAW,EAAE,CAAC;IAChC,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,MAAM,EACb,WAAW,GAAE,MAAa,GACzB,UAAU,CAmFZ"}

package/dist/core/context/rag-context.js

@@ -0,0 +1,93 @@
+/**
+ * RAG Context Builder — builds a compact context from search results
+ * suitable for LLM consumption with token budget management.
+ */
+import { KnowledgeStore } from "../store/knowledge-store.js";
+import { searchNodes } from "../search/fts-search.js";
+import { buildTaskContext } from "./compact-context.js";
+import { estimateTokens } from "./token-estimator.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Build a RAG context from a natural language query.
+ *
+ * 1. Search for relevant nodes via FTS5
+ * 2. Expand subgraph context for top results via buildTaskContext
+ * 3. Manage token budget to stay within limits
+ */
+export function ragBuildContext(store, query, tokenBudget = 4000) {
+    logger.info(`RAG context: query="${query}", budget=${tokenBudget} tokens`);
+    // Stage 1: Search for relevant nodes with TF-IDF reranking
+    const searchResults = searchNodes(store, query, { limit: 10, rerank: true });
+    const relevantNodes = searchResults.map((r) => {
+        const summary = {
+            id: r.node.id,
+            type: r.node.type,
+            title: r.node.title,
+            status: r.node.status,
+            priority: r.node.priority,
+            score: Math.round(r.score * 1000) / 1000,
+        };
+        if (r.node.description)
+            summary.description = r.node.description;
+        if (r.node.tags?.length)
+            summary.tags = r.node.tags;
+        return summary;
+    });
+    // Stage 2: Search knowledge store for additional context
+    const knowledgeStore = new KnowledgeStore(store.getDb());
+    let knowledgeResults = [];
+    try {
+        const kResults = knowledgeStore.search(query, 5);
+        knowledgeResults = kResults.map((r) => ({
+            id: r.id,
+            sourceType: r.sourceType,
+            title: r.title,
+            content: r.content.length > 500 ? r.content.slice(0, 500) + "..." : r.content,
+            score: Math.round(r.score * 1000) / 1000,
+        }));
+    }
+    catch {
+        // Knowledge search may fail if no knowledge docs exist — that's OK
+        logger.debug("Knowledge FTS search returned no results or errored");
+    }
+    // Stage 3: Expand context for top results within budget
+    const expandedContexts = [];
+    const basePayload = JSON.stringify({ query, relevantNodes, knowledgeResults });
+    let tokensUsed = estimateTokens(basePayload);
+    // If the base payload already exceeds budget, cap it and skip expansion
+    if (tokensUsed < tokenBudget) {
+        for (const result of searchResults) {
+            if (tokensUsed >= tokenBudget)
+                break;
+            const ctx = buildTaskContext(store, result.node.id);
+            if (!ctx)
+                continue;
+            const ctxTokens = ctx.metrics.estimatedTokens;
+            if (tokensUsed + ctxTokens > tokenBudget) {
+                // Always include at least one expanded context even if over budget
+                if (expandedContexts.length === 0) {
+                    expandedContexts.push(ctx);
+                    tokensUsed += ctxTokens;
+                }
+                break;
+            }
+            expandedContexts.push(ctx);
+            tokensUsed += ctxTokens;
+        }
+    }
+    // Enforce hard cap: used never exceeds budget in the reported metrics
+    const reportedUsed = Math.min(tokensUsed, tokenBudget);
+    logger.info(`RAG context built: ${relevantNodes.length} nodes, ${knowledgeResults.length} knowledge, ${expandedContexts.length} expanded, ${tokensUsed}/${tokenBudget} tokens`);
+    return {
+        query,
+        relevantNodes,
+        knowledgeResults,
+        expandedContexts,
+        tokenUsage: {
+            budget: tokenBudget,
+            used: reportedUsed,
+            remaining: tokenBudget - reportedUsed,
+        },
+    };
+}
+//# sourceMappingURL=rag-context.js.map

package/dist/core/context/rag-context.js.map

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

package/dist/core/context/tiered-context.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tiered Context Builder — provides 3 levels of detail for node context.
+ *
+ * Tier 1 (summary):  ~20 tok/node  — title + status + type
+ * Tier 2 (standard): ~150 tok/node — compact TaskContext
+ * Tier 3 (deep):     ~500+ tok/node — full context + knowledge docs
+ */
+import type { SqliteStore } from "../store/sqlite-store.js";
+import { type TaskContext } from "./compact-context.js";
+export type ContextTier = "summary" | "standard" | "deep";
+export interface TieredNodeSummary {
+    id: string;
+    type: string;
+    title: string;
+    status: string;
+    priority: number;
+}
+export interface TieredContext {
+    tier: ContextTier;
+    nodeId: string;
+    summary: TieredNodeSummary;
+    taskContext?: TaskContext;
+    knowledgeSnippets?: Array<{
+        title: string;
+        content: string;
+        sourceType: string;
+        score: number;
+    }>;
+    estimatedTokens: number;
+}
+/**
+ * Build context at the specified tier level.
+ */
+export declare function buildTieredContext(store: SqliteStore, nodeId: string, tier?: ContextTier): TieredContext | null;
+//# sourceMappingURL=tiered-context.d.ts.map

package/dist/core/context/tiered-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiered-context.d.ts","sourceRoot":"","sources":["../../../src/core/context/tiered-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAI1E,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,iBAAiB,CAAC,EAAE,KAAK,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,WAAwB,GAC7B,aAAa,GAAG,IAAI,CAyDtB"}

package/dist/core/context/tiered-context.js

@@ -0,0 +1,92 @@
+/**
+ * Tiered Context Builder — provides 3 levels of detail for node context.
+ *
+ * Tier 1 (summary):  ~20 tok/node  — title + status + type
+ * Tier 2 (standard): ~150 tok/node — compact TaskContext
+ * Tier 3 (deep):     ~500+ tok/node — full context + knowledge docs
+ */
+import { KnowledgeStore } from "../store/knowledge-store.js";
+import { buildTaskContext } from "./compact-context.js";
+import { estimateTokens } from "./token-estimator.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Build context at the specified tier level.
+ */
+export function buildTieredContext(store, nodeId, tier = "standard") {
+    const node = store.getNodeById(nodeId);
+    if (!node)
+        return null;
+    const summary = {
+        id: node.id,
+        type: node.type,
+        title: node.title,
+        status: node.status,
+        priority: node.priority,
+    };
+    if (tier === "summary") {
+        const text = JSON.stringify(summary);
+        return {
+            tier,
+            nodeId,
+            summary,
+            estimatedTokens: estimateTokens(text),
+        };
+    }
+    if (tier === "standard") {
+        const taskContext = buildTaskContext(store, nodeId);
+        if (!taskContext)
+            return null;
+        return {
+            tier,
+            nodeId,
+            summary,
+            taskContext,
+            estimatedTokens: taskContext.metrics.estimatedTokens,
+        };
+    }
+    // tier === "deep"
+    const taskContext = buildTaskContext(store, nodeId);
+    if (!taskContext)
+        return null;
+    // Include relevant knowledge docs
+    const knowledgeSnippets = findRelevantKnowledge(store, node);
+    const deepPayload = {
+        tier,
+        nodeId,
+        summary,
+        taskContext,
+        knowledgeSnippets: knowledgeSnippets.length > 0 ? knowledgeSnippets : undefined,
+        estimatedTokens: 0,
+    };
+    const text = JSON.stringify(deepPayload);
+    deepPayload.estimatedTokens = estimateTokens(text);
+    logger.debug("Tiered context built", { nodeId, tier, tokens: deepPayload.estimatedTokens });
+    return deepPayload;
+}
+/**
+ * Find knowledge documents relevant to a node.
+ */
+function findRelevantKnowledge(store, node) {
+    try {
+        const knowledgeStore = new KnowledgeStore(store.getDb());
+        // Build search terms: title words + tags, joined with OR for broader matching
+        const terms = [
+            ...node.title.split(/\s+/).filter((w) => w.length > 2),
+            ...(node.tags ?? []),
+        ];
+        const query = terms.join(" OR ");
+        if (!query.trim())
+            return [];
+        const results = knowledgeStore.search(query, 3);
+        return results.map((r) => ({
+            title: r.title,
+            content: r.content.length > 500 ? r.content.slice(0, 500) + "..." : r.content,
+            sourceType: r.sourceType,
+            score: Math.round(r.score * 1000) / 1000,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=tiered-context.js.map

package/dist/core/context/tiered-context.js.map

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

package/dist/core/context/token-estimator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Lightweight token estimation using the ~4 chars/token heuristic.
+ * This matches the industry-standard approximation used by OpenAI/Anthropic tokenizers
+ * for English text. Good enough for budget estimation without a full tokenizer dependency.
+ */
+export declare function estimateTokens(text: string): number;
+//# sourceMappingURL=token-estimator.d.ts.map

package/dist/core/context/token-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.d.ts","sourceRoot":"","sources":["../../../src/core/context/token-estimator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/core/context/token-estimator.js

@@ -0,0 +1,9 @@
+/**
+ * Lightweight token estimation using the ~4 chars/token heuristic.
+ * This matches the industry-standard approximation used by OpenAI/Anthropic tokenizers
+ * for English text. Good enough for budget estimation without a full tokenizer dependency.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+//# sourceMappingURL=token-estimator.js.map

package/dist/core/context/token-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.js","sourceRoot":"","sources":["../../../src/core/context/token-estimator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC"}

package/dist/core/docs/docs-cache-store.d.ts

@@ -0,0 +1,24 @@
+import type Database from "better-sqlite3";
+export interface CachedDoc {
+    id: number;
+    libId: string;
+    libName: string;
+    version: string | null;
+    content: string;
+    fetchedAt: string;
+}
+export declare class DocsCacheStore {
+    private db;
+    constructor(db: Database.Database);
+    upsertDoc(doc: {
+        libId: string;
+        libName: string;
+        version?: string;
+        content: string;
+    }): CachedDoc;
+    getDoc(libId: string): CachedDoc | null;
+    searchDocs(query: string, limit?: number): CachedDoc[];
+    listCached(): CachedDoc[];
+    getStaleLibs(maxAgeMs: number): CachedDoc[];
+}
+//# sourceMappingURL=docs-cache-store.d.ts.map

package/dist/core/docs/docs-cache-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-cache-store.d.ts","sourceRoot":"","sources":["../../../src/core/docs/docs-cache-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAsBD,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAoB;gBAElB,EAAE,EAAE,QAAQ,CAAC,QAAQ;IAIjC,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,SAAS;IAmBb,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAOvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,SAAS,EAAE;IAa1D,UAAU,IAAI,SAAS,EAAE;IAOzB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE;CAO5C"}

package/dist/core/docs/docs-cache-store.js

@@ -0,0 +1,61 @@
+import { logger } from "../utils/logger.js";
+function rowToDoc(row) {
+    return {
+        id: row.id,
+        libId: row.lib_id,
+        libName: row.lib_name,
+        version: row.version,
+        content: row.content,
+        fetchedAt: row.fetched_at,
+    };
+}
+export class DocsCacheStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    upsertDoc(doc) {
+        const fetchedAt = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO docs_cache (lib_id, lib_name, version, content, fetched_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(lib_id) DO UPDATE SET
+           lib_name = excluded.lib_name,
+           version = excluded.version,
+           content = excluded.content,
+           fetched_at = excluded.fetched_at`)
+            .run(doc.libId, doc.libName, doc.version ?? null, doc.content, fetchedAt);
+        logger.info(`Docs cache upserted: ${doc.libName} (${doc.libId})`);
+        return this.getDoc(doc.libId);
+    }
+    getDoc(libId) {
+        const row = this.db
+            .prepare("SELECT * FROM docs_cache WHERE lib_id = ?")
+            .get(libId);
+        return row ? rowToDoc(row) : null;
+    }
+    searchDocs(query, limit = 20) {
+        const rows = this.db
+            .prepare(`SELECT d.*
+         FROM docs_fts fts
+         JOIN docs_cache d ON d.id = fts.rowid
+         WHERE docs_fts MATCH ?
+         LIMIT ?`)
+            .all(query, limit);
+        return rows.map(rowToDoc);
+    }
+    listCached() {
+        const rows = this.db
+            .prepare("SELECT * FROM docs_cache ORDER BY fetched_at DESC")
+            .all();
+        return rows.map(rowToDoc);
+    }
+    getStaleLibs(maxAgeMs) {
+        const cutoff = new Date(Date.now() - maxAgeMs).toISOString();
+        const rows = this.db
+            .prepare("SELECT * FROM docs_cache WHERE fetched_at < ? ORDER BY fetched_at ASC")
+            .all(cutoff);
+        return rows.map(rowToDoc);
+    }
+}
+//# sourceMappingURL=docs-cache-store.js.map

package/dist/core/docs/docs-cache-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-cache-store.js","sourceRoot":"","sources":["../../../src/core/docs/docs-cache-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAoB5C,SAAS,QAAQ,CAAC,GAAW;IAC3B,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,MAAM;QACjB,OAAO,EAAE,GAAG,CAAC,QAAQ;QACrB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,cAAc;IACjB,EAAE,CAAoB;IAE9B,YAAY,EAAqB;QAC/B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,SAAS,CAAC,GAKT;QACC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAE3C,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;;;;;;4CAMoC,CACrC;aACA,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAE5E,MAAM,CAAC,IAAI,CAAC,wBAAwB,GAAG,CAAC,OAAO,KAAK,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CAAC,2CAA2C,CAAC;aACpD,GAAG,CAAC,KAAK,CAAuB,CAAC;QACpC,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IAED,UAAU,CAAC,KAAa,EAAE,QAAgB,EAAE;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;;;;iBAIS,CACV;aACA,GAAG,CAAC,KAAK,EAAE,KAAK,CAAa,CAAC;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,UAAU;QACR,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CAAC,mDAAmD,CAAC;aAC5D,GAAG,EAAc,CAAC;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,YAAY,CAAC,QAAgB;QAC3B,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CAAC,uEAAuE,CAAC;aAChF,GAAG,CAAC,MAAM,CAAa,CAAC;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/core/docs/docs-syncer.d.ts

@@ -0,0 +1,13 @@
+import type { DocsCacheStore, CachedDoc } from "./docs-cache-store.js";
+export interface Context7Fetcher {
+    resolveLibraryId(name: string): Promise<string>;
+    queryDocs(libId: string): Promise<string>;
+}
+export declare class DocsSyncer {
+    private cacheStore;
+    private fetcher;
+    constructor(cacheStore: DocsCacheStore, fetcher: Context7Fetcher);
+    syncLib(libName: string): Promise<CachedDoc>;
+    syncAll(): Promise<CachedDoc[]>;
+}
+//# sourceMappingURL=docs-syncer.d.ts.map

package/dist/core/docs/docs-syncer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-syncer.d.ts","sourceRoot":"","sources":["../../../src/core/docs/docs-syncer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvE,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,OAAO,CAAkB;gBAErB,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe;IAK1D,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAa5C,OAAO,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;CAqBtC"}

package/dist/core/docs/docs-syncer.js

@@ -0,0 +1,38 @@
+import { logger } from "../utils/logger.js";
+export class DocsSyncer {
+    cacheStore;
+    fetcher;
+    constructor(cacheStore, fetcher) {
+        this.cacheStore = cacheStore;
+        this.fetcher = fetcher;
+    }
+    async syncLib(libName) {
+        logger.info(`Syncing docs for: ${libName}`);
+        const libId = await this.fetcher.resolveLibraryId(libName);
+        const content = await this.fetcher.queryDocs(libId);
+        return this.cacheStore.upsertDoc({
+            libId,
+            libName,
+            content,
+        });
+    }
+    async syncAll() {
+        const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+        const staleLibs = this.cacheStore.getStaleLibs(ONE_DAY_MS);
+        logger.info(`Syncing ${staleLibs.length} stale libs`);
+        const results = [];
+        for (const lib of staleLibs) {
+            try {
+                const doc = await this.syncLib(lib.libName);
+                results.push(doc);
+            }
+            catch (err) {
+                logger.error(`Failed to sync ${lib.libName}`, {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=docs-syncer.js.map

package/dist/core/docs/docs-syncer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-syncer.js","sourceRoot":"","sources":["../../../src/core/docs/docs-syncer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAO5C,MAAM,OAAO,UAAU;IACb,UAAU,CAAiB;IAC3B,OAAO,CAAkB;IAEjC,YAAY,UAA0B,EAAE,OAAwB;QAC9D,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAe;QAC3B,MAAM,CAAC,IAAI,CAAC,qBAAqB,OAAO,EAAE,CAAC,CAAC;QAE5C,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAEpD,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAC/B,KAAK;YACL,OAAO;YACP,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QAE3D,MAAM,CAAC,IAAI,CAAC,WAAW,SAAS,CAAC,MAAM,aAAa,CAAC,CAAC;QAEtD,MAAM,OAAO,GAAgB,EAAE,CAAC;QAEhC,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC5C,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,KAAK,CAAC,kBAAkB,GAAG,CAAC,OAAO,EAAE,EAAE;oBAC5C,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACxD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}