stellavault 0.1.0

package/packages/core/src/mcp/tools/decision-journal.ts

@@ -0,0 +1,95 @@
+// Design Ref: §12.1 F14 — 결정 저널 (기술 결정 자동 기록)
+
+import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { SearchEngine } from '../../search/index.js';
+
+export const logDecisionToolDef = {
+  name: 'log-decision',
+  description: '기술적 결정을 구조화하여 기록합니다. 나중에 "왜 이 선택을 했지?"에 답변할 수 있습니다.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      title: { type: 'string', description: '결정 제목 (예: Zustand 대신 Jotai 선택)' },
+      context: { type: 'string', description: '결정 배경/상황' },
+      decision: { type: 'string', description: '선택한 내용' },
+      alternatives: { type: 'array', items: { type: 'string' }, description: '고려한 대안들' },
+      reasoning: { type: 'string', description: '선택 이유' },
+      project: { type: 'string', description: '관련 프로젝트명' },
+    },
+    required: ['title', 'decision', 'reasoning'],
+  },
+};
+
+export const findDecisionsToolDef = {
+  name: 'find-decisions',
+  description: '과거 기술 결정을 검색합니다.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      query: { type: 'string', description: '검색 쿼리' },
+    },
+    required: ['query'],
+  },
+};
+
+export async function handleLogDecision(
+  vaultPath: string,
+  args: {
+    title: string; context?: string; decision: string;
+    alternatives?: string[]; reasoning: string; project?: string;
+  },
+) {
+  const decisionsDir = join(vaultPath, 'decisions');
+  mkdirSync(decisionsDir, { recursive: true });
+
+  const date = new Date().toISOString().slice(0, 10);
+  const slug = args.title.replace(/[^a-zA-Z가-힣0-9\s-]/g, '').replace(/\s+/g, '-').slice(0, 50);
+  if (!slug) throw new Error('Invalid decision title');
+  const fileName = `${date}-${slug}.md`;
+
+  const content = [
+    '---',
+    `title: "${args.title}"`,
+    `date: ${date}`,
+    `project: "${args.project ?? ''}"`,
+    'type: decision',
+    '---',
+    '',
+    `# ${args.title}`,
+    '',
+    args.context ? `## 배경\n\n${args.context}\n` : '',
+    `## 결정\n\n${args.decision}\n`,
+    args.alternatives?.length
+      ? `## 고려한 대안\n\n${args.alternatives.map(a => `- ${a}`).join('\n')}\n`
+      : '',
+    `## 이유\n\n${args.reasoning}\n`,
+  ].filter(Boolean).join('\n');
+
+  const filePath = resolve(decisionsDir, fileName);
+  if (!filePath.startsWith(resolve(decisionsDir))) {
+    throw new Error('Path traversal detected');
+  }
+  writeFileSync(filePath, content, 'utf-8');
+
+  return { saved: filePath, fileName };
+}
+
+export async function handleFindDecisions(vaultPath: string, args: { query: string }) {
+  const decisionsDir = join(vaultPath, 'decisions');
+  if (!existsSync(decisionsDir)) return { decisions: [], message: 'No decisions directory' };
+
+  const files = readdirSync(decisionsDir).filter(f => f.endsWith('.md'));
+  const query = args.query.toLowerCase();
+
+  const matches = files
+    .map(f => {
+      const content = readFileSync(join(decisionsDir, f), 'utf-8');
+      const score = content.toLowerCase().includes(query) ? 1 : 0;
+      return { file: f, content: content.slice(0, 300), score };
+    })
+    .filter(m => m.score > 0)
+    .slice(0, 10);
+
+  return { decisions: matches, total: files.length };
+}

package/packages/core/src/mcp/tools/export.ts

@@ -0,0 +1,72 @@
+// Design Ref: §12.1 F20 — 지식 내보내기 포맷 (락인 방지)
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import type { VectorStore } from '../../store/types.js';
+
+const ALLOWED_EXPORT_DIRS = [
+  resolve(homedir(), '.stellavault'),
+  resolve('.'),
+];
+
+function validateExportPath(outputPath: string): string {
+  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' as const,
+    properties: {
+      outputPath: { type: 'string', description: '출력 파일 경로 (예: ./export.json)' },
+      format: { type: 'string', enum: ['json', 'csv'], description: '출력 포맷 (기본: json)' },
+    },
+    required: ['outputPath'],
+  },
+};
+
+export async function handleExport(
+  store: VectorStore,
+  args: { outputPath: string; format?: string },
+) {
+  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' };
+}

package/packages/core/src/mcp/tools/federated-search.ts

@@ -0,0 +1,43 @@
+// MCP Tool: federated-search (Federation Phase 1b)
+// AI 에이전트가 연합 네트워크를 검색
+
+import type { FederatedSearch } from '../../federation/search.js';
+
+export function createFederatedSearchTool(federatedSearch: FederatedSearch | null) {
+  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' as const,
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        limit: { type: 'number', description: 'Max results per peer (default: 5)' },
+      },
+      required: ['query'],
+    },
+    async handler(args: { query: string; limit?: number }) {
+      if (!federatedSearch) {
+        return { content: [{ type: 'text' as const, 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' as const, 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' as const, text: lines.join('\n') }] };
+    },
+  };
+}

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

@@ -0,0 +1,130 @@
+// Design Ref: §12.1 F13 — CLAUDE.md 자동 생성기 (킬러 유스케이스)
+
+import type { SearchEngine } from '../../search/index.js';
+import type { VectorStore } from '../../store/types.js';
+
+export const generateClaudeMdToolDef = {
+  name: 'generate-claude-md',
+  description: '프로젝트명을 기반으로 관련 지식(아키텍처, 패턴, 교훈, 결정사항)을 검색하여 CLAUDE.md 초안을 자동 생성합니다.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      projectName: { type: 'string', description: '프로젝트명 또는 주요 키워드' },
+      topics: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '추가 검색할 토픽 (예: ["인증", "배포", "성능"])',
+      },
+    },
+    required: ['projectName'],
+  },
+};
+
+export async function handleGenerateClaudeMd(
+  searchEngine: SearchEngine,
+  store: VectorStore,
+  args: { projectName: string; topics?: string[] },
+) {
+  const { projectName, topics = [] } = args;
+
+  // 프로젝트 관련 지식 검색 (여러 관점)
+  const queries = [
+    `${projectName} 아키텍처 설계`,
+    `${projectName} 패턴 컨벤션`,
+    `${projectName} 교훈 실수 주의사항`,
+    `${projectName} 기술 스택 의존성`,
+    ...topics.map(t => `${projectName} ${t}`),
+  ];
+
+  const allResults = new Map<string, { title: string; content: string; score: number; category: string }>();
+
+  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: string[] = [];
+  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
+      ),
+    },
+  };
+}

package/packages/core/src/mcp/tools/get-document.ts

@@ -0,0 +1,26 @@
+import type { VectorStore } from '../../store/types.js';
+
+export const getDocumentToolDef = {
+  name: 'get-document',
+  description: '문서 ID 또는 파일 경로로 전체 문서 내용을 가져옵니다.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      id: { type: 'string', description: '문서 ID 또는 파일 경로' },
+    },
+    required: ['id'],
+  },
+};
+
+export async function handleGetDocument(store: VectorStore, args: { id: string }) {
+  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,
+  };
+}

package/packages/core/src/mcp/tools/get-related.ts

@@ -0,0 +1,41 @@
+import type { SearchEngine } from '../../search/index.js';
+import type { VectorStore } from '../../store/types.js';
+
+export const getRelatedToolDef = {
+  name: 'get-related',
+  description: '특정 문서와 의미적으로 관련된 문서들을 반환합니다.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      id: { type: 'string', description: '기준 문서 ID 또는 파일 경로' },
+      limit: { type: 'number', description: '반환할 관련 문서 수 (기본: 5)' },
+    },
+    required: ['id'],
+  },
+};
+
+export async function handleGetRelated(
+  store: VectorStore,
+  searchEngine: SearchEngine,
+  args: { id: string; limit?: number },
+) {
+  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,
+    }));
+}

package/packages/core/src/mcp/tools/learning-path.ts

@@ -0,0 +1,52 @@
+// MCP Tool: get-learning-path (F-A11)
+
+import type { VectorStore } from '../../store/types.js';
+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: VectorStore) {
+  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' as const,
+      properties: {
+        limit: { type: 'number', description: 'Max items to return (default: 10)' },
+      },
+    },
+    async handler(args: { limit?: number }) {
+      const limit = args.limit ?? 10;
+      const db = store.getDb() as any;
+      if (!db) return { content: [{ type: 'text' as const, text: 'Database not available' }] };
+
+      const decayEngine = new DecayEngine(db);
+      const decayReport = await decayEngine.computeAll();
+
+      let gaps: any[] = [];
+      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' as const, text: lines.join('\n') }] };
+    },
+  };
+}

package/packages/core/src/mcp/tools/list-topics.ts

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

package/packages/core/src/mcp/tools/search.ts

@@ -0,0 +1,35 @@
+import type { SearchEngine } from '../../search/index.js';
+
+export const searchToolDef = {
+  name: 'search',
+  description: '개인 지식 베이스에서 관련 문서/청크를 검색합니다. 자연어 쿼리와 키워드 모두 지원합니다.',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      query: { type: 'string', description: '검색 쿼리 (자연어 또는 키워드)' },
+      limit: { type: 'number', description: '반환할 결과 수 (기본: 5)' },
+      tags: { type: 'array', items: { type: 'string' }, description: '태그 필터' },
+    },
+    required: ['query'],
+  },
+};
+
+export async function handleSearch(
+  searchEngine: SearchEngine,
+  args: { query: string; limit?: number; tags?: string[] },
+) {
+  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,
+  }));
+}

package/packages/core/src/mcp/tools/snapshot.ts

@@ -0,0 +1,98 @@
+// Design Ref: §12.1 F10 — 컨텍스트 스냅샷 (프로젝트별 지식 묶음)
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+import { homedir } from 'node:os';
+import type { SearchEngine } from '../../search/index.js';
+
+const SNAPSHOT_DIR = join(homedir(), '.stellavault', 'snapshots');
+
+function sanitizeName(name: string): string {
+  const sanitized = name.replace(/[^a-zA-Z0-9가-힣_-]/g, '');
+  if (!sanitized) throw new Error('Invalid snapshot name');
+  return sanitized;
+}
+
+function ensureWithinDir(dir: string, filePath: string): string {
+  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' as const,
+    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' as const,
+    properties: {
+      name: { type: 'string', description: '스냅샷 이름' },
+    },
+    required: ['name'],
+  },
+};
+
+export async function handleCreateSnapshot(
+  searchEngine: SearchEngine,
+  args: { name: string; queries: string[] },
+) {
+  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<string>();
+  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: { name: string }) {
+  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'));
+}