stellavault 0.2.0 → 0.2.1

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-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

package/packages/core/dist/mcp/tools/list-topics.d.ts

@@ -0,0 +1,15 @@
+import type { VectorStore } from '../../store/types.js';
+export declare const listTopicsToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+export declare function handleListTopics(store: VectorStore): Promise<{
+    topics: import("../../index.js").TopicInfo[];
+    totalDocuments: number;
+    totalChunks: number;
+}>;
+//# sourceMappingURL=list-topics.d.ts.map

package/packages/core/dist/mcp/tools/list-topics.js

@@ -0,0 +1,18 @@
+export const listTopicsToolDef = {
+    name: 'list-topics',
+    description: '지식 베이스의 전체 토픽/태그 목록과 문서 수를 반환합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+};
+export async function handleListTopics(store) {
+    const topics = await store.getTopics();
+    const stats = await store.getStats();
+    return {
+        topics,
+        totalDocuments: stats.documentCount,
+        totalChunks: stats.chunkCount,
+    };
+}
+//# sourceMappingURL=list-topics.js.map

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

@@ -0,0 +1,39 @@
+import type { SearchEngine } from '../../search/index.js';
+export declare const searchToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleSearch(searchEngine: SearchEngine, args: {
+    query: string;
+    limit?: number;
+    tags?: string[];
+}): Promise<{
+    title: string;
+    filePath: string;
+    heading: string;
+    content: string;
+    score: number;
+    tags: string[];
+}[]>;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1,29 @@
+export const searchToolDef = {
+    name: 'search',
+    description: '개인 지식 베이스에서 관련 문서/청크를 검색합니다. 자연어 쿼리와 키워드 모두 지원합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: '검색 쿼리 (자연어 또는 키워드)' },
+            limit: { type: 'number', description: '반환할 결과 수 (기본: 5)' },
+            tags: { type: 'array', items: { type: 'string' }, description: '태그 필터' },
+        },
+        required: ['query'],
+    },
+};
+export async function handleSearch(searchEngine, args) {
+    const results = await searchEngine.search({
+        query: args.query,
+        limit: args.limit ?? 5,
+        tags: args.tags,
+    });
+    return results.map(r => ({
+        title: r.document.title,
+        filePath: r.document.filePath,
+        heading: r.chunk.heading,
+        content: r.chunk.content,
+        score: Math.round(r.score * 1000) / 1000,
+        tags: r.document.tags,
+    }));
+}
+//# sourceMappingURL=search.js.map

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

@@ -0,0 +1,47 @@
+import type { SearchEngine } from '../../search/index.js';
+export declare const createSnapshotToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            queries: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const loadSnapshotToolDef: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleCreateSnapshot(searchEngine: SearchEngine, args: {
+    name: string;
+    queries: string[];
+}): Promise<{
+    saved: string;
+    resultCount: number;
+}>;
+export declare function handleLoadSnapshot(args: {
+    name: string;
+}): Promise<any>;
+//# sourceMappingURL=snapshot.d.ts.map

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

@@ -0,0 +1,84 @@
+// Design Ref: §12.1 F10 — 컨텍스트 스냅샷 (프로젝트별 지식 묶음)
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+const SNAPSHOT_DIR = join(homedir(), '.stellavault', 'snapshots');
+function sanitizeName(name) {
+    const sanitized = name.replace(/[^a-zA-Z0-9가-힣_-]/g, '');
+    if (!sanitized)
+        throw new Error('Invalid snapshot name');
+    return sanitized;
+}
+function ensureWithinDir(dir, filePath) {
+    const resolved = resolve(dir, filePath);
+    if (!resolved.startsWith(resolve(dir))) {
+        throw new Error('Path traversal detected');
+    }
+    return resolved;
+}
+export const createSnapshotToolDef = {
+    name: 'create-snapshot',
+    description: '현재 프로젝트 관련 지식을 스냅샷으로 저장합니다. 나중에 load-snapshot으로 즉시 컨텍스트 복원.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: '스냅샷 이름 (예: my-project-v1)' },
+            queries: { type: 'array', items: { type: 'string' }, description: '관련 지식 검색 쿼리들' },
+        },
+        required: ['name', 'queries'],
+    },
+};
+export const loadSnapshotToolDef = {
+    name: 'load-snapshot',
+    description: '저장된 스냅샷을 로드하여 프로젝트 컨텍스트를 즉시 복원합니다.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: '스냅샷 이름' },
+        },
+        required: ['name'],
+    },
+};
+export async function handleCreateSnapshot(searchEngine, args) {
+    mkdirSync(SNAPSHOT_DIR, { recursive: true });
+    const results = [];
+    for (const query of args.queries) {
+        const hits = await searchEngine.search({ query, limit: 5 });
+        results.push(...hits.map(r => ({
+            query,
+            title: r.document.title,
+            filePath: r.document.filePath,
+            heading: r.chunk.heading,
+            content: r.chunk.content.slice(0, 500),
+            score: r.score,
+        })));
+    }
+    // 중복 제거
+    const seen = new Set();
+    const unique = results.filter(r => {
+        const key = `${r.filePath}:${r.heading}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const snapshot = {
+        name: args.name,
+        createdAt: new Date().toISOString(),
+        queries: args.queries,
+        results: unique,
+    };
+    const safeName = sanitizeName(args.name);
+    const filePath = ensureWithinDir(SNAPSHOT_DIR, `${safeName}.json`);
+    writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+    return { saved: filePath, resultCount: unique.length };
+}
+export async function handleLoadSnapshot(args) {
+    const safeName = sanitizeName(args.name);
+    const filePath = ensureWithinDir(SNAPSHOT_DIR, `${safeName}.json`);
+    if (!existsSync(filePath)) {
+        return { error: `Snapshot not found: ${args.name}` };
+    }
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+//# sourceMappingURL=snapshot.js.map

package/packages/core/dist/multi-vault/index.d.ts

@@ -0,0 +1,26 @@
+import type { VectorStore } from '../store/types.js';
+import type { Embedder } from '../indexer/embedder.js';
+export interface VaultEntry {
+    id: string;
+    name: string;
+    path: string;
+    dbPath: string;
+    shared: boolean;
+    addedAt: string;
+}
+export interface CrossVaultSearchResult {
+    vaultId: string;
+    vaultName: string;
+    title: string;
+    score: number;
+    snippet: string;
+    filePath: string;
+}
+export declare function addVault(id: string, name: string, vaultPath: string, dbPath: string, shared?: boolean): VaultEntry;
+export declare function removeVault(id: string): boolean;
+export declare function listVaults(): VaultEntry[];
+export declare function getVault(id: string): VaultEntry | undefined;
+export declare function searchAllVaults(query: string, embedder: Embedder, createStore: (dbPath: string) => VectorStore, options?: {
+    limit?: number;
+}): Promise<CrossVaultSearchResult[]>;
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/multi-vault/index.js

@@ -0,0 +1,80 @@
+// Cross-Vault Federation (P3-F24)
+// 한 사람의 여러 vault를 통합 검색
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const VAULTS_FILE = join(homedir(), '.stellavault', 'vaults.json');
+function loadVaults() {
+    if (!existsSync(VAULTS_FILE))
+        return [];
+    return JSON.parse(readFileSync(VAULTS_FILE, 'utf-8'));
+}
+function saveVaults(vaults) {
+    mkdirSync(join(homedir(), '.stellavault'), { recursive: true });
+    writeFileSync(VAULTS_FILE, JSON.stringify(vaults, null, 2), 'utf-8');
+}
+export function addVault(id, name, vaultPath, dbPath, shared = false) {
+    const vaults = loadVaults();
+    if (vaults.some(v => v.id === id)) {
+        throw new Error(`Vault "${id}" already exists`);
+    }
+    const entry = { id, name, path: vaultPath, dbPath, shared, addedAt: new Date().toISOString() };
+    vaults.push(entry);
+    saveVaults(vaults);
+    return entry;
+}
+export function removeVault(id) {
+    const vaults = loadVaults();
+    const filtered = vaults.filter(v => v.id !== id);
+    if (filtered.length === vaults.length)
+        return false;
+    saveVaults(filtered);
+    return true;
+}
+export function listVaults() {
+    return loadVaults();
+}
+export function getVault(id) {
+    return loadVaults().find(v => v.id === id);
+}
+// 모든 vault를 통합 검색
+export async function searchAllVaults(query, embedder, createStore, options = {}) {
+    const { limit = 10 } = options;
+    const vaults = loadVaults();
+    const results = [];
+    // 쿼리 임베딩 (한 번만)
+    const embedding = await embedder.embed(query);
+    // 각 vault에서 병렬 검색
+    const searches = vaults.map(async (vault) => {
+        try {
+            if (!existsSync(vault.dbPath))
+                return;
+            const store = createStore(vault.dbPath);
+            await store.initialize();
+            const scored = await store.searchSemantic(embedding, limit);
+            for (const s of scored) {
+                const chunk = await store.getChunk(s.chunkId);
+                if (!chunk)
+                    continue;
+                const doc = await store.getDocument(chunk.documentId);
+                results.push({
+                    vaultId: vault.id,
+                    vaultName: vault.name,
+                    title: doc?.title ?? 'Untitled',
+                    score: s.score,
+                    snippet: chunk.content.slice(0, 80),
+                    filePath: doc?.filePath ?? '',
+                });
+            }
+            await store.close();
+        }
+        catch {
+            // vault 접근 실패 시 건너뜀
+        }
+    });
+    await Promise.allSettled(searches);
+    return results
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}
+//# sourceMappingURL=index.js.map

package/packages/core/dist/pack/creator.d.ts

@@ -0,0 +1,21 @@
+import type { VectorStore } from '../store/types.js';
+import type { SearchEngine } from '../search/index.js';
+import type { Embedder } from '../indexer/embedder.js';
+import type { KnowledgePack } from './types.js';
+export interface CreatePackOptions {
+    name: string;
+    author?: string;
+    license?: string;
+    description?: string;
+    fromSearch?: string;
+    fromCluster?: number;
+    limit?: number;
+}
+export declare function createPack(store: VectorStore, searchEngine: SearchEngine, embedder: Embedder, options: CreatePackOptions): Promise<{
+    pack: KnowledgePack;
+    piiReport: {
+        redactedCount: number;
+        types: string[];
+    };
+}>;
+//# sourceMappingURL=creator.d.ts.map