stellavault 0.2.0 → 0.3.0

package/packages/core/dist/mcp/tools/detect-gaps.js

@@ -0,0 +1,47 @@
+// Design Ref: §3.5 — MCP detect-gaps tool
+// Plan SC: SC-04 MCP detect-gaps가 클러스터 간 갭 + 고립 노드 반환
+import { detectKnowledgeGaps } from '../../intelligence/gap-detector.js';
+export function createDetectGapsTool(store) {
+    return {
+        name: 'detect-gaps',
+        description: 'Detect knowledge gaps between topic clusters. Returns gap severity, isolated nodes, and suggested topics to bridge gaps.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                minSeverity: {
+                    type: 'string',
+                    description: 'Minimum gap severity to include: high, medium, or low',
+                    enum: ['high', 'medium', 'low'],
+                },
+            },
+        },
+        handler: async (args) => {
+            const minSeverity = args.minSeverity ?? 'medium';
+            const report = await detectKnowledgeGaps(store);
+            const sevOrder = { high: 0, medium: 1, low: 2 };
+            const threshold = sevOrder[minSeverity] ?? 1;
+            const filtered = report.gaps.filter((g) => sevOrder[g.severity] <= threshold);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            totalClusters: report.totalClusters,
+                            totalGaps: filtered.length,
+                            gaps: filtered.map((g) => ({
+                                clusterA: g.clusterA,
+                                clusterB: g.clusterB,
+                                bridgeCount: g.bridgeCount,
+                                severity: g.severity,
+                                suggestedTopic: g.suggestedTopic,
+                            })),
+                            isolatedNodes: report.isolatedNodes.slice(0, 10),
+                            suggestion: filtered.length > 0
+                                ? `${filtered[0].suggestedTopic} 주제로 노트를 작성하면 지식 갭을 줄일 수 있습니다.`
+                                : '현재 심각한 지식 갭이 없습니다.',
+                        }, null, 2),
+                    }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=detect-gaps.js.map

package/packages/core/dist/mcp/tools/export.d.ts

@@ -0,0 +1,29 @@
+import type { VectorStore } from '../../store/types.js';
+export declare const exportToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            outputPath: {
+                type: string;
+                description: string;
+            };
+            format: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleExport(store: VectorStore, args: {
+    outputPath: string;
+    format?: string;
+}): Promise<{
+    exported: number;
+    path: string;
+    format: string;
+}>;
+//# sourceMappingURL=export.d.ts.map

package/packages/core/dist/mcp/tools/export.js

@@ -0,0 +1,60 @@
+// Design Ref: §12.1 F20 — 지식 내보내기 포맷 (락인 방지)
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+const ALLOWED_EXPORT_DIRS = [
+    resolve(homedir(), '.stellavault'),
+    resolve('.'),
+];
+function validateExportPath(outputPath) {
+    const resolved = resolve(outputPath);
+    const isAllowed = ALLOWED_EXPORT_DIRS.some(dir => resolved.startsWith(resolve(dir)));
+    if (!isAllowed) {
+        throw new Error(`Export path must be within current directory or ~/.stellavault/. Got: ${resolved}`);
+    }
+    return resolved;
+}
+export const exportToolDef = {
+    name: 'export',
+    description: '벡터 DB의 문서와 메타데이터를 JSON 파일로 내보냅니다. 다른 도구로 이전 가능.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            outputPath: { type: 'string', description: '출력 파일 경로 (예: ./export.json)' },
+            format: { type: 'string', enum: ['json', 'csv'], description: '출력 포맷 (기본: json)' },
+        },
+        required: ['outputPath'],
+    },
+};
+export async function handleExport(store, args) {
+    const docs = await store.getAllDocuments();
+    const stats = await store.getStats();
+    const topics = await store.getTopics();
+    const safePath = validateExportPath(args.outputPath);
+    mkdirSync(dirname(safePath), { recursive: true });
+    if (args.format === 'csv') {
+        const header = 'id,filePath,title,tags,lastModified,contentHash';
+        const rows = docs.map(d => `"${d.id}","${d.filePath}","${d.title.replace(/"/g, '""')}","${d.tags.join(';')}","${d.lastModified}","${d.contentHash}"`);
+        writeFileSync(safePath, [header, ...rows].join('\n'), 'utf-8');
+    }
+    else {
+        const exported = {
+            exportedAt: new Date().toISOString(),
+            version: '1.0',
+            stats,
+            topics,
+            documents: docs.map(d => ({
+                id: d.id,
+                filePath: d.filePath,
+                title: d.title,
+                tags: d.tags,
+                frontmatter: d.frontmatter,
+                lastModified: d.lastModified,
+                contentLength: d.content.length,
+            })),
+        };
+        writeFileSync(safePath, JSON.stringify(exported, null, 2), 'utf-8');
+    }
+    return { exported: docs.length, path: safePath, format: args.format ?? 'json' };
+}
+//# sourceMappingURL=export.js.map

package/packages/core/dist/mcp/tools/federated-search.d.ts

@@ -0,0 +1,29 @@
+import type { FederatedSearch } from '../../federation/search.js';
+export declare function createFederatedSearchTool(federatedSearch: FederatedSearch | null): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler(args: {
+        query: string;
+        limit?: number;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=federated-search.d.ts.map

package/packages/core/dist/mcp/tools/federated-search.js

@@ -0,0 +1,36 @@
+// MCP Tool: federated-search (Federation Phase 1b)
+// AI 에이전트가 연합 네트워크를 검색
+export function createFederatedSearchTool(federatedSearch) {
+    return {
+        name: 'federated-search',
+        description: 'Search across all connected Federation peers. Returns results from other Stellavault nodes in the P2P network. Only titles, similarity scores, and 50-char snippets are shared — no raw text leaves any node.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                limit: { type: 'number', description: 'Max results per peer (default: 5)' },
+            },
+            required: ['query'],
+        },
+        async handler(args) {
+            if (!federatedSearch) {
+                return { content: [{ type: 'text', text: 'Federation not active. Run `sv federate join` first.' }] };
+            }
+            const results = await federatedSearch.search(args.query, { limit: args.limit ?? 5 });
+            if (results.length === 0) {
+                return { content: [{ type: 'text', text: 'No results from federation peers. Either no peers connected or no matching documents.' }] };
+            }
+            const lines = [
+                `🌐 Federation Search: "${args.query}" — ${results.length} results from ${new Set(results.map(r => r.peerId)).size} peers`,
+                '',
+            ];
+            for (const r of results) {
+                lines.push(`**${r.title}** (${Math.round(r.similarity * 100)}%) [${r.peerName}]`);
+                lines.push(`  ${r.snippet}...`);
+                lines.push('');
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        },
+    };
+}
+//# sourceMappingURL=federated-search.js.map

package/packages/core/dist/mcp/tools/generate-claude-md.d.ts

@@ -0,0 +1,35 @@
+import type { SearchEngine } from '../../search/index.js';
+import type { VectorStore } from '../../store/types.js';
+export declare const generateClaudeMdToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectName: {
+                type: string;
+                description: string;
+            };
+            topics: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGenerateClaudeMd(searchEngine: SearchEngine, store: VectorStore, args: {
+    projectName: string;
+    topics?: string[];
+}): Promise<{
+    content: string;
+    stats: {
+        queriesRun: number;
+        uniqueResults: number;
+        sections: string[];
+    };
+}>;
+//# sourceMappingURL=generate-claude-md.d.ts.map

package/packages/core/dist/mcp/tools/generate-claude-md.js

@@ -0,0 +1,107 @@
+// Design Ref: §12.1 F13 — CLAUDE.md 자동 생성기 (킬러 유스케이스)
+export const generateClaudeMdToolDef = {
+    name: 'generate-claude-md',
+    description: '프로젝트명을 기반으로 관련 지식(아키텍처, 패턴, 교훈, 결정사항)을 검색하여 CLAUDE.md 초안을 자동 생성합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectName: { type: 'string', description: '프로젝트명 또는 주요 키워드' },
+            topics: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '추가 검색할 토픽 (예: ["인증", "배포", "성능"])',
+            },
+        },
+        required: ['projectName'],
+    },
+};
+export async function handleGenerateClaudeMd(searchEngine, store, args) {
+    const { projectName, topics = [] } = args;
+    // 프로젝트 관련 지식 검색 (여러 관점)
+    const queries = [
+        `${projectName} 아키텍처 설계`,
+        `${projectName} 패턴 컨벤션`,
+        `${projectName} 교훈 실수 주의사항`,
+        `${projectName} 기술 스택 의존성`,
+        ...topics.map(t => `${projectName} ${t}`),
+    ];
+    const allResults = new Map();
+    for (const query of queries) {
+        const results = await searchEngine.search({ query, limit: 3 });
+        const category = query.replace(projectName, '').trim();
+        for (const r of results) {
+            const key = r.chunk.id;
+            if (!allResults.has(key) || (allResults.get(key).score < r.score)) {
+                allResults.set(key, {
+                    title: `${r.document.title} §${r.chunk.heading}`,
+                    content: r.chunk.content.slice(0, 500),
+                    score: r.score,
+                    category,
+                });
+            }
+        }
+    }
+    // 카테고리별 분류
+    const sorted = [...allResults.values()].sort((a, b) => b.score - a.score);
+    // CLAUDE.md 초안 생성
+    const sections = [];
+    sections.push(`# ${projectName} — CLAUDE.md`);
+    sections.push('');
+    sections.push('> 이 파일은 evan-knowledge-hub MCP에서 자동 생성되었습니다.');
+    sections.push(`> 생성일: ${new Date().toISOString().slice(0, 10)}`);
+    sections.push(`> 참조 지식: ${sorted.length}건`);
+    sections.push('');
+    // 아키텍처 섹션
+    const archResults = sorted.filter(r => r.category.includes('아키텍처') || r.category.includes('설계'));
+    if (archResults.length > 0) {
+        sections.push('## 아키텍처 & 설계');
+        sections.push('');
+        for (const r of archResults.slice(0, 3)) {
+            sections.push(`### ${r.title}`);
+            sections.push(r.content.trim());
+            sections.push('');
+        }
+    }
+    // 패턴/컨벤션 섹션
+    const patternResults = sorted.filter(r => r.category.includes('패턴') || r.category.includes('컨벤션'));
+    if (patternResults.length > 0) {
+        sections.push('## 코딩 패턴 & 컨벤션');
+        sections.push('');
+        for (const r of patternResults.slice(0, 3)) {
+            sections.push(`### ${r.title}`);
+            sections.push(r.content.trim());
+            sections.push('');
+        }
+    }
+    // 교훈 섹션
+    const lessonResults = sorted.filter(r => r.category.includes('교훈') || r.category.includes('실수'));
+    if (lessonResults.length > 0) {
+        sections.push('## 교훈 & 주의사항');
+        sections.push('');
+        for (const r of lessonResults.slice(0, 5)) {
+            sections.push(`- **${r.title}**: ${r.content.slice(0, 200).replace(/\n/g, ' ').trim()}`);
+        }
+        sections.push('');
+    }
+    // 기타 관련 지식
+    const otherResults = sorted.filter(r => !r.category.includes('아키텍처') && !r.category.includes('설계') &&
+        !r.category.includes('패턴') && !r.category.includes('교훈') && !r.category.includes('실수'));
+    if (otherResults.length > 0) {
+        sections.push('## 관련 지식');
+        sections.push('');
+        for (const r of otherResults.slice(0, 5)) {
+            sections.push(`- **${r.title}** (score: ${r.score.toFixed(3)})`);
+        }
+        sections.push('');
+    }
+    const claudeMd = sections.join('\n');
+    return {
+        content: claudeMd,
+        stats: {
+            queriesRun: queries.length,
+            uniqueResults: sorted.length,
+            sections: ['아키텍처', '패턴', '교훈', '관련 지식'].filter((_, i) => [archResults, patternResults, lessonResults, otherResults][i].length > 0),
+        },
+    };
+}
+//# sourceMappingURL=generate-claude-md.js.map

package/packages/core/dist/mcp/tools/get-document.d.ts

@@ -0,0 +1,35 @@
+import type { VectorStore } from '../../store/types.js';
+export declare const getDocumentToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetDocument(store: VectorStore, args: {
+    id: string;
+}): Promise<{
+    error: string;
+    title?: undefined;
+    filePath?: undefined;
+    content?: undefined;
+    tags?: undefined;
+    frontmatter?: undefined;
+    lastModified?: undefined;
+} | {
+    title: string;
+    filePath: string;
+    content: string;
+    tags: string[];
+    frontmatter: Record<string, unknown>;
+    lastModified: string;
+    error?: undefined;
+}>;
+//# sourceMappingURL=get-document.d.ts.map

package/packages/core/dist/mcp/tools/get-document.js

@@ -0,0 +1,25 @@
+export const getDocumentToolDef = {
+    name: 'get-document',
+    description: '문서 ID 또는 파일 경로로 전체 문서 내용을 가져옵니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: '문서 ID 또는 파일 경로' },
+        },
+        required: ['id'],
+    },
+};
+export async function handleGetDocument(store, args) {
+    const doc = await store.getDocument(args.id);
+    if (!doc)
+        return { error: `Document not found: ${args.id}` };
+    return {
+        title: doc.title,
+        filePath: doc.filePath,
+        content: doc.content,
+        tags: doc.tags,
+        frontmatter: doc.frontmatter,
+        lastModified: doc.lastModified,
+    };
+}
+//# sourceMappingURL=get-document.js.map

package/packages/core/dist/mcp/tools/get-evolution.d.ts

@@ -0,0 +1,28 @@
+import type { VectorStore } from '../../store/types.js';
+export declare function createGetEvolutionTool(store: VectorStore): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            topic: {
+                type: "string";
+                description: string;
+            };
+            limit: {
+                type: "number";
+                description: string;
+            };
+        };
+    };
+    handler: (args: {
+        topic?: string;
+        limit?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=get-evolution.d.ts.map

package/packages/core/dist/mcp/tools/get-evolution.js

@@ -0,0 +1,70 @@
+// Design Ref: F02 — 지식 진화 타임라인 MCP tool
+// Plan SC: SC-01 주제별 드리프트 반환
+export function createGetEvolutionTool(store) {
+    return {
+        name: 'get-evolution',
+        description: 'Track semantic evolution of knowledge. Shows which topics have changed the most in meaning over time.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    description: 'Optional topic/tag to filter. Omit for vault-wide analysis.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results to return (default: 10)',
+                },
+            },
+        },
+        handler: async (args) => {
+            const limit = args.limit ?? 10;
+            const docs = await store.getAllDocuments();
+            const embeddings = await store.getDocumentEmbeddings();
+            // Filter by topic/tag if provided
+            let filteredDocs = docs;
+            if (args.topic) {
+                const topicLower = args.topic.toLowerCase();
+                filteredDocs = docs.filter((d) => d.tags.some((t) => t.toLowerCase().includes(topicLower)) ||
+                    d.title.toLowerCase().includes(topicLower));
+            }
+            // Build embedding maps (current only — single-point, but foundation for multi-version)
+            const currentEmbeddings = new Map();
+            const titles = new Map();
+            for (const doc of filteredDocs) {
+                const emb = embeddings.get(doc.id);
+                if (emb) {
+                    currentEmbeddings.set(doc.id, emb);
+                    titles.set(doc.id, doc.title);
+                }
+            }
+            // For now, use modification time as proxy for "evolution"
+            // Sort by most recently modified with content changes
+            const recentlyChanged = filteredDocs
+                .filter((d) => d.lastModified)
+                .sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime())
+                .slice(0, limit)
+                .map((d) => ({
+                documentId: d.id,
+                title: d.title,
+                lastModified: d.lastModified,
+                tags: d.tags.slice(0, 5),
+                daysSinceModified: Math.round((Date.now() - new Date(d.lastModified).getTime()) / 86400000),
+            }));
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            topic: args.topic ?? 'all',
+                            totalDocuments: filteredDocs.length,
+                            recentlyEvolved: recentlyChanged,
+                            summary: recentlyChanged.length > 0
+                                ? `최근 변화가 가장 큰 문서: "${recentlyChanged[0].title}" (${recentlyChanged[0].daysSinceModified}일 전 수정)`
+                                : '분석할 문서가 없습니다.',
+                        }, null, 2),
+                    }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=get-evolution.js.map

package/packages/core/dist/mcp/tools/get-related.d.ts

@@ -0,0 +1,32 @@
+import type { SearchEngine } from '../../search/index.js';
+import type { VectorStore } from '../../store/types.js';
+export declare const getRelatedToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleGetRelated(store: VectorStore, searchEngine: SearchEngine, args: {
+    id: string;
+    limit?: number;
+}): Promise<{
+    title: string;
+    filePath: string;
+    score: number;
+    tags: string[];
+}[] | {
+    error: string;
+}>;
+//# sourceMappingURL=get-related.d.ts.map

package/packages/core/dist/mcp/tools/get-related.js

@@ -0,0 +1,33 @@
+export const getRelatedToolDef = {
+    name: 'get-related',
+    description: '특정 문서와 의미적으로 관련된 문서들을 반환합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: '기준 문서 ID 또는 파일 경로' },
+            limit: { type: 'number', description: '반환할 관련 문서 수 (기본: 5)' },
+        },
+        required: ['id'],
+    },
+};
+export async function handleGetRelated(store, searchEngine, args) {
+    const doc = await store.getDocument(args.id);
+    if (!doc)
+        return { error: `Document not found: ${args.id}` };
+    // 문서 제목+내용 일부를 쿼리로 사용하여 관련 문서 검색
+    const query = `${doc.title} ${doc.content.slice(0, 200)}`;
+    const results = await searchEngine.search({
+        query,
+        limit: (args.limit ?? 5) + 1, // 자기 자신 제외용 +1
+    });
+    return results
+        .filter(r => r.document.id !== args.id)
+        .slice(0, args.limit ?? 5)
+        .map(r => ({
+        title: r.document.title,
+        filePath: r.document.filePath,
+        score: Math.round(r.score * 1000) / 1000,
+        tags: r.document.tags,
+    }));
+}
+//# sourceMappingURL=get-related.js.map

package/packages/core/dist/mcp/tools/learning-path.d.ts

@@ -0,0 +1,23 @@
+import type { VectorStore } from '../../store/types.js';
+export declare function createLearningPathTool(store: VectorStore): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+    handler(args: {
+        limit?: number;
+    }): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=learning-path.d.ts.map

package/packages/core/dist/mcp/tools/learning-path.js

@@ -0,0 +1,45 @@
+// MCP Tool: get-learning-path (F-A11)
+import { DecayEngine } from '../../intelligence/decay-engine.js';
+import { detectKnowledgeGaps } from '../../intelligence/gap-detector.js';
+import { generateLearningPath } from '../../intelligence/learning-path.js';
+export function createLearningPathTool(store) {
+    return {
+        name: 'get-learning-path',
+        description: 'Generate a personalized learning path based on knowledge decay and gaps. Returns prioritized list of what to review, explore, or bridge.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'Max items to return (default: 10)' },
+            },
+        },
+        async handler(args) {
+            const limit = args.limit ?? 10;
+            const db = store.getDb();
+            if (!db)
+                return { content: [{ type: 'text', text: 'Database not available' }] };
+            const decayEngine = new DecayEngine(db);
+            const decayReport = await decayEngine.computeAll();
+            let gaps = [];
+            try {
+                const gapReport = await detectKnowledgeGaps(store);
+                gaps = gapReport.gaps ?? [];
+            }
+            catch { /* ignore */ }
+            const path = generateLearningPath({ decayReport, gaps }, limit);
+            const lines = [
+                `🎯 Learning Path (${path.items.length} items, ~${path.summary.estimatedMinutes}min)`,
+                '',
+            ];
+            for (const item of path.items) {
+                const icon = item.category === 'review' ? '📖' : item.category === 'bridge' ? '🌉' : '🔭';
+                lines.push(`${icon} [${item.priority}] ${item.title} (${item.score}pt)`);
+                lines.push(`   ${item.reason}`);
+            }
+            if (path.items.length === 0) {
+                lines.push('All clear! Knowledge is in great shape.');
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        },
+    };
+}
+//# sourceMappingURL=learning-path.js.map