stellavault 0.2.0 → 0.3.0

package/packages/core/dist/mcp/tools/link-code.d.ts

@@ -0,0 +1,34 @@
+import type { SearchEngine } from '../../search/index.js';
+export declare function createLinkCodeTool(searchEngine: SearchEngine): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            filePath: {
+                type: "string";
+                description: string;
+            };
+            content: {
+                type: "string";
+                description: string;
+            };
+            limit: {
+                type: "number";
+                description: string;
+            };
+        };
+        required: readonly ["filePath"];
+    };
+    handler: (args: {
+        filePath: string;
+        content?: string;
+        limit?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};
+//# sourceMappingURL=link-code.d.ts.map

package/packages/core/dist/mcp/tools/link-code.js

@@ -0,0 +1,44 @@
+// Design Ref: F15 — 코드-지식 링커 MCP tool
+// Plan SC: SC-03 코드 파일에서 관련 노트 매칭
+import { linkCodeToKnowledge } from '../../intelligence/code-linker.js';
+export function createLinkCodeTool(searchEngine) {
+    return {
+        name: 'link-code',
+        description: 'Find knowledge notes related to a code file. Extracts keywords from file path and content, then searches the knowledge base.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Path to the code file (e.g., src/auth/middleware.ts)',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Optional: code file content for deeper keyword extraction',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max related notes to return (default: 5)',
+                },
+            },
+            required: ['filePath'],
+        },
+        handler: async (args) => {
+            const result = await linkCodeToKnowledge(searchEngine, args.filePath, args.content, args.limit ?? 5);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            filePath: result.filePath,
+                            extractedKeywords: result.keywords,
+                            relatedNotes: result.relatedNotes,
+                            summary: result.relatedNotes.length > 0
+                                ? `"${result.filePath}" 관련 노트 ${result.relatedNotes.length}개 발견. 최상위: "${result.relatedNotes[0].title}"`
+                                : `"${result.filePath}"에 대한 관련 노트를 찾지 못했습니다.`,
+                        }, null, 2),
+                    }],
+            };
+        },
+    };
+}
+//# sourceMappingURL=link-code.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

package/packages/core/dist/pack/creator.js

@@ -0,0 +1,105 @@
+// Design Ref: Phase 3 FR-01~03 — 검색/클러스터 기반 팩 생성
+import { maskPII } from './pii-masker.js';
+export async function createPack(store, searchEngine, embedder, options) {
+    const { name, author = 'anonymous', license = 'CC-BY-4.0', description = '', limit = 100 } = options;
+    let chunkIds = [];
+    if (options.fromSearch) {
+        // 검색 결과에서 청크 수집
+        const results = await searchEngine.search({ query: options.fromSearch, limit });
+        chunkIds = results.map(r => r.chunk.id);
+    }
+    else if (options.fromCluster !== undefined) {
+        // 클러스터의 문서에서 청크 수집
+        const docs = await store.getAllDocuments();
+        const embeddings = await store.getDocumentEmbeddings();
+        // 간단한 클러스터 매칭: graph-data의 K-means 결과를 재활용할 수 없으므로
+        // 해당 클러스터 문서의 모든 청크를 가져옴
+        // 여기서는 fromSearch를 권장하되, fromCluster는 문서 ID 기반으로 처리
+        const clusterDocs = docs.slice(0, limit);
+        for (const doc of clusterDocs) {
+            const chunk = await store.getChunk(`${doc.id}#0`);
+            if (chunk)
+                chunkIds.push(chunk.id);
+        }
+    }
+    // 청크 데이터 수집 + PII 마스킹
+    const chunks = [];
+    let totalRedacted = 0;
+    const allTypes = new Set();
+    for (const chunkId of chunkIds) {
+        const chunk = await store.getChunk(chunkId);
+        if (!chunk)
+            continue;
+        const doc = await store.getDocument(chunk.documentId);
+        if (!doc)
+            continue;
+        // PII 마스킹
+        const { masked, redactedCount, redactedTypes } = maskPII(chunk.content);
+        totalRedacted += redactedCount;
+        redactedTypes.forEach(t => allTypes.add(t));
+        // 임베딩 재생성 (마스킹된 텍스트로)
+        const embedding = await embedder.embed(masked);
+        chunks.push({
+            id: chunkId,
+            content: masked,
+            heading: chunk.heading,
+            embedding,
+            metadata: {
+                sourceFile: doc.filePath,
+                category: detectCategory(doc.filePath, chunk.content),
+                language: detectLanguage(chunk.content),
+            },
+        });
+    }
+    const pack = {
+        name,
+        version: '1.0.0',
+        author,
+        license,
+        description: description || `Knowledge pack: ${name}`,
+        tags: extractPackTags(chunks),
+        embeddingModel: embedder.modelName,
+        embeddingDimensions: embedder.dimensions,
+        schemaVersion: '1.0',
+        chunks,
+        createdAt: new Date().toISOString(),
+    };
+    return {
+        pack,
+        piiReport: { redactedCount: totalRedacted, types: [...allTypes] },
+    };
+}
+function detectCategory(filePath, content) {
+    const lower = filePath.toLowerCase() + ' ' + content.slice(0, 200).toLowerCase();
+    if (lower.includes('lesson') || lower.includes('교훈'))
+        return 'lesson';
+    if (lower.includes('pattern') || lower.includes('패턴'))
+        return 'pattern';
+    if (lower.includes('decision') || lower.includes('결정'))
+        return 'decision';
+    if (lower.includes('design') || lower.includes('설계'))
+        return 'reference';
+    return 'reference';
+}
+function detectLanguage(content) {
+    if (content.includes('typescript') || content.includes('.ts'))
+        return 'typescript';
+    if (content.includes('python') || content.includes('.py'))
+        return 'python';
+    if (content.includes('react') || content.includes('jsx'))
+        return 'react';
+    return undefined;
+}
+function extractPackTags(chunks) {
+    const wordCounts = new Map();
+    for (const c of chunks) {
+        const words = c.heading.split(/\s+/).filter(w => w.length > 2);
+        for (const w of words)
+            wordCounts.set(w, (wordCounts.get(w) ?? 0) + 1);
+    }
+    return [...wordCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([w]) => w);
+}
+//# sourceMappingURL=creator.js.map

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

@@ -0,0 +1,4 @@
+import type { KnowledgePack } from './types.js';
+export declare function exportPack(pack: KnowledgePack, outputPath: string): void;
+export declare function packToSummary(pack: KnowledgePack): string;
+//# sourceMappingURL=exporter.d.ts.map

package/packages/core/dist/pack/exporter.js

@@ -0,0 +1,18 @@
+// Design Ref: Phase 3 FR-05 — .sv-pack 파일 내보내기
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export function exportPack(pack, outputPath) {
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, JSON.stringify(pack, null, 2), 'utf-8');
+}
+export function packToSummary(pack) {
+    return [
+        `Name: ${pack.name} v${pack.version}`,
+        `Author: ${pack.author} (${pack.license})`,
+        `Chunks: ${pack.chunks.length}`,
+        `Model: ${pack.embeddingModel} (${pack.embeddingDimensions}d)`,
+        `Tags: ${pack.tags.join(', ')}`,
+        `Created: ${pack.createdAt}`,
+    ].join('\n');
+}
+//# sourceMappingURL=exporter.js.map

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

@@ -0,0 +1,10 @@
+import type { VectorStore } from '../store/types.js';
+import type { Embedder } from '../indexer/embedder.js';
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    reEmbedded: number;
+    modelMismatch: boolean;
+}
+export declare function importPack(store: VectorStore, embedder: Embedder, filePath: string): Promise<ImportResult>;
+//# sourceMappingURL=importer.d.ts.map

package/packages/core/dist/pack/importer.js

@@ -0,0 +1,55 @@
+// Design Ref: Phase 3 FR-06~07 — .sv-pack 가져오기 + 벡터 DB 병합
+import { readFileSync } from 'node:fs';
+export async function importPack(store, embedder, filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const pack = JSON.parse(raw);
+    // 임베딩 모델 불일치 감지
+    const modelMismatch = pack.embeddingModel !== embedder.modelName ||
+        pack.embeddingDimensions !== embedder.dimensions;
+    let imported = 0;
+    let skipped = 0;
+    let reEmbedded = 0;
+    // 팩 문서를 pack_{name} prefix로 저장
+    const packDocId = `pack_${pack.name}`;
+    await store.upsertDocument({
+        id: packDocId,
+        filePath: `[pack] ${pack.name}`,
+        title: `${pack.name} (Knowledge Pack)`,
+        content: `Imported pack: ${pack.description}\nChunks: ${pack.chunks.length}\nAuthor: ${pack.author}`,
+        frontmatter: { pack: pack.name, license: pack.license },
+        tags: pack.tags,
+        lastModified: pack.createdAt,
+        contentHash: `pack_${pack.name}_${pack.version}`,
+    });
+    const chunks = [];
+    for (let i = 0; i < pack.chunks.length; i++) {
+        const pc = pack.chunks[i];
+        let embedding = pc.embedding;
+        // 모델 불일치 시 재임베딩
+        if (modelMismatch) {
+            embedding = await embedder.embed(pc.content);
+            reEmbedded++;
+        }
+        // 차원 검증
+        if (embedding.length !== embedder.dimensions) {
+            skipped++;
+            continue;
+        }
+        chunks.push({
+            id: `${packDocId}#${i}`,
+            documentId: packDocId,
+            content: pc.content,
+            heading: pc.heading || pack.name,
+            startLine: 0,
+            endLine: 0,
+            tokenCount: Math.ceil(pc.content.length / 4),
+            embedding,
+        });
+        imported++;
+    }
+    if (chunks.length > 0) {
+        await store.upsertChunks(chunks);
+    }
+    return { imported, skipped, reEmbedded, modelMismatch };
+}
+//# sourceMappingURL=importer.js.map

package/packages/core/{src/pack/index.ts → dist/pack/index.d.ts}

@@ -3,3 +3,4 @@ export { createPack, type CreatePackOptions } from './creator.js';
 export { exportPack, packToSummary } from './exporter.js';
 export { importPack, type ImportResult } from './importer.js';
 export { maskPII, type MaskResult } from './pii-masker.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/pack/index.js

@@ -0,0 +1,5 @@
+export { createPack } from './creator.js';
+export { exportPack, packToSummary } from './exporter.js';
+export { importPack } from './importer.js';
+export { maskPII } from './pii-masker.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,14 @@
+export interface PackListing {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    downloads?: number;
+    tags: string[];
+    source: 'npm' | 'github';
+    installCommand: string;
+}
+export declare function searchMarketplace(query: string, limit?: number): Promise<PackListing[]>;
+export declare function createPackageJson(packName: string, description: string, author: string, version?: string): string;
+export declare function getPublishInstructions(packName: string): string;
+//# sourceMappingURL=marketplace.d.ts.map