stellavault 0.2.0 → 0.2.1

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

@@ -1,95 +0,0 @@
-// 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

@@ -1,72 +0,0 @@
-// 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

@@ -1,43 +0,0 @@
-// 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

@@ -1,130 +0,0 @@
-// 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

@@ -1,26 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,52 +0,0 @@
-// 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

@@ -1,20 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,98 +0,0 @@
-// 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'));
-}