stellavault 0.1.0

package/packages/core/src/team/index.ts

@@ -0,0 +1,126 @@
+// Team Vault (F-A06) — Bearer 토큰 인증 + RBAC
+// MCP Streamable HTTP에 인증 레이어 추가
+
+import { randomBytes, createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export type TeamRole = 'admin' | 'editor' | 'viewer';
+
+export interface TeamMember {
+  token: string;        // Bearer token (SHA256 hash stored)
+  tokenHash: string;    // stored version
+  displayName: string;
+  role: TeamRole;
+  createdAt: string;
+  lastAccess?: string;
+}
+
+export interface TeamConfig {
+  teamName: string;
+  members: TeamMember[];
+}
+
+const TEAM_DIR = join(homedir(), '.stellavault', 'team');
+const TEAM_FILE = join(TEAM_DIR, 'team.json');
+
+export function loadTeamConfig(): TeamConfig {
+  if (existsSync(TEAM_FILE)) {
+    return JSON.parse(readFileSync(TEAM_FILE, 'utf-8'));
+  }
+  return { teamName: 'My Team', members: [] };
+}
+
+function saveTeamConfig(config: TeamConfig): void {
+  mkdirSync(TEAM_DIR, { recursive: true });
+  writeFileSync(TEAM_FILE, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+// 토큰 생성
+export function generateToken(): string {
+  return `sv_${randomBytes(24).toString('hex')}`;
+}
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+// 멤버 초대 → 토큰 반환
+export function inviteMember(displayName: string, role: TeamRole = 'viewer'): { token: string; member: TeamMember } {
+  const config = loadTeamConfig();
+  const token = generateToken();
+  const member: TeamMember = {
+    token: '', // 클리어 토큰은 저장 안 함
+    tokenHash: hashToken(token),
+    displayName,
+    role,
+    createdAt: new Date().toISOString(),
+  };
+  config.members.push(member);
+  saveTeamConfig(config);
+  return { token, member }; // 토큰은 이때만 보여줌
+}
+
+// 토큰으로 멤버 인증
+export function authenticateMember(token: string): TeamMember | null {
+  const config = loadTeamConfig();
+  const hash = hashToken(token);
+  const member = config.members.find(m => m.tokenHash === hash);
+  if (member) {
+    member.lastAccess = new Date().toISOString();
+    saveTeamConfig(config);
+  }
+  return member ?? null;
+}
+
+// RBAC 권한 확인
+export function hasPermission(member: TeamMember, action: 'read' | 'write' | 'admin'): boolean {
+  switch (action) {
+    case 'read': return true; // 모든 역할 읽기 가능
+    case 'write': return member.role === 'admin' || member.role === 'editor';
+    case 'admin': return member.role === 'admin';
+  }
+}
+
+// 멤버 목록
+export function listMembers(): TeamMember[] {
+  return loadTeamConfig().members;
+}
+
+// 멤버 제거
+export function removeMember(displayName: string): boolean {
+  const config = loadTeamConfig();
+  const before = config.members.length;
+  config.members = config.members.filter(m => m.displayName !== displayName);
+  if (config.members.length < before) {
+    saveTeamConfig(config);
+    return true;
+  }
+  return false;
+}
+
+// Express 미들웨어: Bearer 토큰 인증
+export function createAuthMiddleware() {
+  return (req: any, res: any, next: any) => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader?.startsWith('Bearer ')) {
+      // HIGH-01: localhost는 editor 권한만 (admin은 토큰 필수)
+      const ip = req.ip || req.connection?.remoteAddress;
+      if (ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1') {
+        req.teamMember = { displayName: 'local', role: 'editor' } as TeamMember;
+        return next();
+      }
+      return res.status(401).json({ error: 'Bearer token required' });
+    }
+
+    const token = authHeader.slice(7);
+    const member = authenticateMember(token);
+    if (!member) {
+      return res.status(403).json({ error: 'Invalid token' });
+    }
+
+    req.teamMember = member;
+    next();
+  };
+}

package/packages/core/src/types/chunk.ts

@@ -0,0 +1,25 @@
+// Design Ref: §3.1 — Core Types (Chunk)
+
+export interface Chunk {
+  /** document.id + "#" + chunkIndex */
+  id: string;
+  /** 소속 문서 ID */
+  documentId: string;
+  /** 청크 텍스트 */
+  content: string;
+  /** 소속 heading (## 제목) */
+  heading: string;
+  /** 원문 시작 줄 번호 */
+  startLine: number;
+  /** 원문 끝 줄 번호 */
+  endLine: number;
+  /** 토큰 수 */
+  tokenCount: number;
+  /** 768차원 벡터 (로딩 시 선택적) */
+  embedding?: number[];
+}
+
+export interface ScoredChunk {
+  chunkId: string;
+  score: number;
+}

package/packages/core/src/types/document.ts

@@ -0,0 +1,24 @@
+// Design Ref: §3.1 — Core Types (Document)
+
+export interface Document {
+  /** SHA-256 hash of file path */
+  id: string;
+  /** vault 기준 상대 경로 */
+  filePath: string;
+  /** frontmatter title 또는 첫 heading */
+  title: string;
+  /** 전체 마크다운 텍스트 */
+  content: string;
+  /** YAML frontmatter */
+  frontmatter: Record<string, unknown>;
+  /** #태그 목록 */
+  tags: string[];
+  /** ISO 8601 */
+  lastModified: string;
+  /** SHA-256 of content (증분 인덱싱용) */
+  contentHash: string;
+  /** 출처: local | notion | clip | bridge | pack */
+  source?: string;
+  /** 노트 유형: note | clip | sync | bridge | decision | snapshot */
+  type?: string;
+}

package/packages/core/src/types/graph.ts

@@ -0,0 +1,44 @@
+// Design Ref: §3.1 — Graph Data Types
+
+export interface GraphNode {
+  id: string;
+  label: string;
+  filePath: string;
+  tags: string[];
+  clusterId: number;
+  position?: [number, number, number];
+  size: number;
+  source?: string;
+  type?: string;
+  lastModified?: string;
+}
+
+export interface GraphEdge {
+  source: string;
+  target: string;
+  weight: number;
+}
+
+export interface Cluster {
+  id: number;
+  label: string;
+  color: string;
+  nodeCount: number;
+}
+
+export interface GraphData {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  clusters: Cluster[];
+  stats: {
+    nodeCount: number;
+    edgeCount: number;
+    clusterCount: number;
+  };
+}
+
+export interface GraphResponse {
+  data: GraphData;
+  generatedAt: string;
+  cacheKey: string;
+}

package/packages/core/src/types/index.ts

@@ -0,0 +1,15 @@
+export type { Document } from './document.js';
+export type { Chunk, ScoredChunk } from './chunk.js';
+export type {
+  SearchResult,
+  SearchOptions,
+  TopicInfo,
+  StoreStats,
+} from './search.js';
+export type {
+  GraphNode,
+  GraphEdge,
+  Cluster,
+  GraphData,
+  GraphResponse,
+} from './graph.js';

package/packages/core/src/types/search.ts

@@ -0,0 +1,38 @@
+// Design Ref: §3.1 — Core Types (Search)
+
+import type { Chunk } from './chunk.js';
+import type { Document } from './document.js';
+
+export interface SearchResult {
+  chunk: Chunk;
+  document: Document;
+  /** RRF 통합 점수 (0~1) */
+  score: number;
+  /** 매칭 부분 하이라이트 */
+  highlights: string[];
+}
+
+export interface SearchOptions {
+  query: string;
+  /** default: 10 */
+  limit?: number;
+  /** minimum score, default: 0.1 */
+  threshold?: number;
+  /** 태그 필터 */
+  tags?: string[];
+  /** 날짜 범위 필터 */
+  dateRange?: { from?: string; to?: string };
+}
+
+export interface TopicInfo {
+  topic: string;
+  count: number;
+  recentDocuments: Array<{ id: string; title: string }>;
+}
+
+export interface StoreStats {
+  documentCount: number;
+  chunkCount: number;
+  dbSizeBytes: number;
+  lastIndexed: string | null;
+}

package/packages/core/src/utils/retry.ts

@@ -0,0 +1,85 @@
+// Error Recovery System (F-A02) — retry with exponential backoff + meaningful messages
+
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  onRetry?: (error: Error, attempt: number, maxRetries: number) => void;
+}
+
+const DEFAULT_OPTIONS: Required<Pick<RetryOptions, 'maxRetries' | 'baseDelayMs' | 'maxDelayMs'>> = {
+  maxRetries: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 10000,
+};
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const { maxRetries, baseDelayMs, maxDelayMs } = { ...DEFAULT_OPTIONS, ...options };
+
+  let lastError: Error | undefined;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt >= maxRetries) break;
+
+      const delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+      options.onRetry?.(lastError, attempt + 1, maxRetries);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+
+  throw lastError!;
+}
+
+export class StellavaultError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly suggestion?: string,
+    public readonly cause?: Error,
+  ) {
+    super(message);
+    this.name = 'StellavaultError';
+  }
+
+  format(): string {
+    const lines = [`Error [${this.code}]: ${this.message}`];
+    if (this.suggestion) lines.push(`  Fix: ${this.suggestion}`);
+    if (this.cause) lines.push(`  Cause: ${this.cause.message}`);
+    return lines.join('\n');
+  }
+}
+
+export function wrapError(err: unknown, code: string, suggestion?: string): StellavaultError {
+  const cause = err instanceof Error ? err : new Error(String(err));
+  return new StellavaultError(cause.message, code, suggestion, cause);
+}
+
+// Common error factories
+export const errors = {
+  vaultNotFound: (path: string) =>
+    new StellavaultError(`Vault not found: ${path}`, 'VAULT_NOT_FOUND', 'Check the path exists and contains .md files'),
+
+  dbInitFailed: (err: unknown) =>
+    wrapError(err, 'DB_INIT_FAILED', 'Delete ~/.stellavault/index.db and re-index'),
+
+  embedderFailed: (err: unknown) =>
+    wrapError(err, 'EMBEDDER_FAILED', 'Check disk space and try again. The model downloads on first run (~80MB)'),
+
+  indexingFailed: (file: string, err: unknown) =>
+    wrapError(err, 'INDEX_FAILED', `Skipping "${file}". Re-run indexing to retry failed files`),
+
+  searchFailed: (err: unknown) =>
+    wrapError(err, 'SEARCH_FAILED', 'Re-index your vault: stellavault index <path>'),
+
+  configInvalid: (field: string) =>
+    new StellavaultError(`Invalid config: ${field}`, 'CONFIG_INVALID', 'Check ~/.stellavault.json format'),
+
+  apiServerFailed: (port: number, err: unknown) =>
+    wrapError(err, 'API_SERVER_FAILED', `Port ${port} may be in use. Try: stellavault graph --port ${port + 1}`),
+};

package/packages/core/tests/api-card.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createSqliteVecStore } from '../src/store/sqlite-vec.js';
+import { createSearchEngine } from '../src/search/index.js';
+import { createApiServer } from '../src/api/server.js';
+import type { VectorStore } from '../src/store/types.js';
+
+const DIMS = 4;
+const PORT = 13334;
+let store: VectorStore;
+
+beforeAll(async () => {
+  store = createSqliteVecStore(':memory:', DIMS);
+  await store.initialize();
+  await store.upsertDocument({
+    id: 'doc1', filePath: 'test.md', title: 'Test',
+    content: 'Content', frontmatter: {}, tags: ['test'],
+    lastModified: '2026-01-01', contentHash: 'h1',
+  });
+  await store.upsertChunks([{
+    id: 'doc1#0', documentId: 'doc1', content: 'Content',
+    heading: 'Test', startLine: 1, endLine: 1, tokenCount: 2,
+    embedding: [1, 0, 0, 0],
+  }]);
+
+  const embedder = {
+    dimensions: DIMS, modelName: 'test',
+    initialize: async () => {},
+    embed: async () => [0.5, 0.5, 0.5, 0.5],
+    embedBatch: async (t: string[]) => t.map(() => [0.5, 0.5, 0.5, 0.5]),
+  };
+  const searchEngine = createSearchEngine({ store, embedder });
+  const server = createApiServer({ store, searchEngine, port: PORT });
+  await server.start();
+});
+
+afterAll(async () => { await store.close(); });
+
+describe('GET /api/profile-card', () => {
+  it('SVG 반환', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/profile-card`);
+    expect(res.ok).toBe(true);
+    expect(res.headers.get('content-type')).toContain('image/svg+xml');
+    const text = await res.text();
+    expect(text).toContain('<svg');
+    expect(text).toContain('</svg>');
+  });
+
+  it('문서 수 포함', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/profile-card`);
+    const text = await res.text();
+    expect(text).toContain('1 docs');
+  });
+
+  it('mode=folder 지원', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/profile-card?mode=folder`);
+    expect(res.ok).toBe(true);
+    const text = await res.text();
+    expect(text).toContain('<svg');
+  });
+});

package/packages/core/tests/api-routes.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createSqliteVecStore } from '../src/store/sqlite-vec.js';
+import { createSearchEngine } from '../src/search/index.js';
+import { createApiServer } from '../src/api/server.js';
+import type { VectorStore } from '../src/store/types.js';
+import type { Embedder } from '../src/indexer/embedder.js';
+
+const DIMS = 4;
+let store: VectorStore;
+let server: ReturnType<typeof createApiServer>;
+const PORT = 13333; // 테스트용 포트
+
+function mockEmbedder(): Embedder {
+  return {
+    dimensions: DIMS, modelName: 'test',
+    initialize: async () => {},
+    embed: async () => [0.5, 0.5, 0.5, 0.5],
+    embedBatch: async (texts) => texts.map(() => [0.5, 0.5, 0.5, 0.5]),
+  };
+}
+
+beforeAll(async () => {
+  store = createSqliteVecStore(':memory:', DIMS);
+  await store.initialize();
+
+  await store.upsertDocument({
+    id: 'doc1', filePath: 'test.md', title: 'Test Doc',
+    content: 'OAuth authentication patterns', frontmatter: {}, tags: ['auth'],
+    lastModified: '2026-01-01', contentHash: 'h1',
+  });
+  await store.upsertChunks([{
+    id: 'doc1#0', documentId: 'doc1', content: 'OAuth authentication patterns',
+    heading: 'Auth', startLine: 1, endLine: 1, tokenCount: 3,
+    embedding: [1, 0, 0, 0],
+  }]);
+
+  const embedder = mockEmbedder();
+  const searchEngine = createSearchEngine({ store, embedder });
+  server = createApiServer({ store, searchEngine, port: PORT });
+  await server.start();
+});
+
+afterAll(async () => { await store.close(); });
+
+describe('API Routes', () => {
+  it('GET /api/stats', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/stats`);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data.documentCount).toBe(1);
+    expect(data.chunkCount).toBe(1);
+  });
+
+  it('GET /api/graph', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/graph`);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data.data.nodes.length).toBe(1);
+    expect(data.data.stats.nodeCount).toBe(1);
+  });
+
+  it('GET /api/graph?mode=folder', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/graph?mode=folder`);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data.data.clusters.length).toBeGreaterThan(0);
+  });
+
+  it('GET /api/search?q=OAuth', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/search?q=OAuth`);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data.query).toBe('OAuth');
+    expect(data.results.length).toBeGreaterThan(0);
+    expect(data.results[0].documentId).toBe('doc1');
+  });
+
+  it('GET /api/search 빈 쿼리', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/search?q=`);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data.results).toEqual([]);
+  });
+
+  it('GET /api/document/:id 존재', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/document/doc1`);
+    expect(res.ok).toBe(true);
+    const data = await res.json();
+    expect(data.title).toBe('Test Doc');
+    expect(data.content).toContain('OAuth');
+    expect(data.related).toBeDefined();
+  });
+
+  it('GET /api/document/:id 미존재 → 404', async () => {
+    const res = await fetch(`http://127.0.0.1:${PORT}/api/document/nonexistent`);
+    expect(res.status).toBe(404);
+  });
+});

package/packages/core/tests/bm25.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { searchBm25 } from '../src/search/bm25.js';
+import type { VectorStore } from '../src/store/types.js';
+import type { ScoredChunk } from '../src/types/chunk.js';
+
+// FTS5 검색을 시뮬레이션하는 mock store
+function createMockStore(keywordResults: ScoredChunk[] = []): VectorStore {
+  return {
+    searchKeyword: async (_query: string, _limit: number) => keywordResults,
+    // 사용하지 않는 메서드 stub
+    initialize: async () => {},
+    close: async () => {},
+    upsertDocument: async () => {},
+    upsertChunks: async () => {},
+    deleteByDocumentId: async () => {},
+    getDocument: async () => null,
+    getChunk: async () => null,
+    searchSemantic: async () => [],
+    getTopics: async () => [],
+    getStats: async () => ({ documentCount: 0, chunkCount: 0, dbSizeBytes: 0, lastIndexed: null }),
+    getAllDocumentHashes: async () => new Map(),
+  } as VectorStore;
+}
+
+describe('searchBm25', () => {
+  it('빈 쿼리는 빈 결과 반환', async () => {
+    const store = createMockStore();
+    const results = await searchBm25(store, '', 10);
+    expect(results).toEqual([]);
+  });
+
+  it('특수문자만 있는 쿼리는 빈 결과 반환', async () => {
+    const store = createMockStore();
+    const results = await searchBm25(store, '!@#$%^&*()', 10);
+    expect(results).toEqual([]);
+  });
+
+  it('일반 영문 쿼리 OR 조합 생성', async () => {
+    let capturedQuery = '';
+    const store = createMockStore();
+    store.searchKeyword = async (query: string, _limit: number) => {
+      capturedQuery = query;
+      return [];
+    };
+
+    await searchBm25(store, 'React state management', 10);
+    expect(capturedQuery).toBe('React OR state OR management');
+  });
+
+  it('한국어 쿼리 처리', async () => {
+    let capturedQuery = '';
+    const store = createMockStore();
+    store.searchKeyword = async (query: string, _limit: number) => {
+      capturedQuery = query;
+      return [];
+    };
+
+    await searchBm25(store, '리액트 상태관리', 10);
+    expect(capturedQuery).toBe('리액트 OR 상태관리');
+  });
+
+  it('특수문자 제거 후 정상 검색', async () => {
+    let capturedQuery = '';
+    const store = createMockStore();
+    store.searchKeyword = async (query: string, _limit: number) => {
+      capturedQuery = query;
+      return [];
+    };
+
+    await searchBm25(store, 'OAuth2.0 인증/설계', 10);
+    // 특수문자(., /) 제거 후 단어 추출
+    expect(capturedQuery).toContain('OR');
+    expect(capturedQuery).not.toContain('.');
+    expect(capturedQuery).not.toContain('/');
+  });
+
+  it('결과를 그대로 반환', async () => {
+    const mockResults: ScoredChunk[] = [
+      { chunkId: 'doc1#0', score: 0.9 },
+      { chunkId: 'doc2#1', score: 0.5 },
+    ];
+    const store = createMockStore(mockResults);
+    const results = await searchBm25(store, 'test query', 10);
+    expect(results).toEqual(mockResults);
+    expect(results.length).toBe(2);
+  });
+});

package/packages/core/tests/chunker.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { chunkDocument, estimateTokens } from '../src/indexer/chunker.js';
+
+describe('estimateTokens', () => {
+  it('영문 토큰 추정', () => {
+    expect(estimateTokens('hello world')).toBe(3);
+  });
+
+  it('한국어 토큰 추정', () => {
+    expect(estimateTokens('안녕하세요')).toBe(3);
+  });
+
+  it('빈 문자열', () => {
+    expect(estimateTokens('')).toBe(0);
+  });
+});
+
+describe('chunkDocument', () => {
+  it('짧은 문서는 1개 청크', () => {
+    const chunks = chunkDocument('doc1', '# Title\n\nShort content.');
+    expect(chunks.length).toBe(1);
+    expect(chunks[0].documentId).toBe('doc1');
+    expect(chunks[0].id).toBe('doc1#0');
+  });
+
+  it('heading으로 분할', () => {
+    const md = '# Title\n\nIntro.\n\n## A\n\n' + 'Content A. '.repeat(50) + '\n\n## B\n\n' + 'Content B. '.repeat(50);
+    const chunks = chunkDocument('doc2', md);
+    expect(chunks.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('빈 문서는 빈 배열', () => {
+    const chunks = chunkDocument('doc3', '');
+    expect(chunks).toEqual([]);
+  });
+
+  it('heading 없는 문서도 처리', () => {
+    const chunks = chunkDocument('doc4', 'Just plain text without headings.');
+    expect(chunks.length).toBe(1);
+  });
+
+  it('짧은 청크 병합', () => {
+    const md = '## A\n\nHi\n\n## B\n\nBye';
+    const chunks = chunkDocument('doc5', md, { minTokens: 50 });
+    // 둘 다 50 토큰 미만이므로 병합됨
+    expect(chunks.length).toBe(1);
+  });
+});