stellavault 0.1.0

package/packages/core/src/multi-vault/index.ts

@@ -0,0 +1,118 @@
+// Cross-Vault Federation (P3-F24)
+// 한 사람의 여러 vault를 통합 검색
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { VectorStore } from '../store/types.js';
+import type { Embedder } from '../indexer/embedder.js';
+import type { ScoredChunk } from '../types/chunk.js';
+
+export interface VaultEntry {
+  id: string;          // short alias
+  name: string;        // display name
+  path: string;        // vault path
+  dbPath: string;      // index.db path
+  shared: boolean;     // 공유 허용 여부 (Federation에서)
+  addedAt: string;
+}
+
+export interface CrossVaultSearchResult {
+  vaultId: string;
+  vaultName: string;
+  title: string;
+  score: number;
+  snippet: string;
+  filePath: string;
+}
+
+const VAULTS_FILE = join(homedir(), '.stellavault', 'vaults.json');
+
+function loadVaults(): VaultEntry[] {
+  if (!existsSync(VAULTS_FILE)) return [];
+  return JSON.parse(readFileSync(VAULTS_FILE, 'utf-8'));
+}
+
+function saveVaults(vaults: VaultEntry[]): void {
+  mkdirSync(join(homedir(), '.stellavault'), { recursive: true });
+  writeFileSync(VAULTS_FILE, JSON.stringify(vaults, null, 2), 'utf-8');
+}
+
+export function addVault(id: string, name: string, vaultPath: string, dbPath: string, shared = false): VaultEntry {
+  const vaults = loadVaults();
+  if (vaults.some(v => v.id === id)) {
+    throw new Error(`Vault "${id}" already exists`);
+  }
+  const entry: VaultEntry = { id, name, path: vaultPath, dbPath, shared, addedAt: new Date().toISOString() };
+  vaults.push(entry);
+  saveVaults(vaults);
+  return entry;
+}
+
+export function removeVault(id: string): boolean {
+  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(): VaultEntry[] {
+  return loadVaults();
+}
+
+export function getVault(id: string): VaultEntry | undefined {
+  return loadVaults().find(v => v.id === id);
+}
+
+// 모든 vault를 통합 검색
+export async function searchAllVaults(
+  query: string,
+  embedder: Embedder,
+  createStore: (dbPath: string) => VectorStore,
+  options: { limit?: number } = {},
+): Promise<CrossVaultSearchResult[]> {
+  const { limit = 10 } = options;
+  const vaults = loadVaults();
+  const results: CrossVaultSearchResult[] = [];
+
+  // 쿼리 임베딩 (한 번만)
+  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);
+}

package/packages/core/src/pack/creator.ts

@@ -0,0 +1,127 @@
+// Design Ref: Phase 3 FR-01~03 — 검색/클러스터 기반 팩 생성
+
+import type { VectorStore } from '../store/types.js';
+import type { SearchEngine } from '../search/index.js';
+import type { Embedder } from '../indexer/embedder.js';
+import type { KnowledgePack, PackChunk } from './types.js';
+import { maskPII } from './pii-masker.js';
+
+export interface CreatePackOptions {
+  name: string;
+  author?: string;
+  license?: string;
+  description?: string;
+  fromSearch?: string;
+  fromCluster?: number;
+  limit?: number;
+}
+
+export async function createPack(
+  store: VectorStore,
+  searchEngine: SearchEngine,
+  embedder: Embedder,
+  options: CreatePackOptions,
+): Promise<{ pack: KnowledgePack; piiReport: { redactedCount: number; types: string[] } }> {
+  const { name, author = 'anonymous', license = 'CC-BY-4.0', description = '', limit = 100 } = options;
+
+  let chunkIds: string[] = [];
+
+  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: PackChunk[] = [];
+  let totalRedacted = 0;
+  const allTypes = new Set<string>();
+
+  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: KnowledgePack = {
+    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: string, content: string): string {
+  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: string): string | undefined {
+  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: PackChunk[]): string[] {
+  const wordCounts = new Map<string, number>();
+  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);
+}

package/packages/core/src/pack/exporter.ts

@@ -0,0 +1,21 @@
+// Design Ref: Phase 3 FR-05 — .sv-pack 파일 내보내기
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { KnowledgePack } from './types.js';
+
+export function exportPack(pack: KnowledgePack, outputPath: string): void {
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, JSON.stringify(pack, null, 2), 'utf-8');
+}
+
+export function packToSummary(pack: KnowledgePack): string {
+  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');
+}

package/packages/core/src/pack/importer.ts

@@ -0,0 +1,82 @@
+// Design Ref: Phase 3 FR-06~07 — .sv-pack 가져오기 + 벡터 DB 병합
+
+import { readFileSync } from 'node:fs';
+import type { VectorStore } from '../store/types.js';
+import type { Embedder } from '../indexer/embedder.js';
+import type { KnowledgePack } from './types.js';
+
+export interface ImportResult {
+  imported: number;
+  skipped: number;
+  reEmbedded: number;
+  modelMismatch: boolean;
+}
+
+export async function importPack(
+  store: VectorStore,
+  embedder: Embedder,
+  filePath: string,
+): Promise<ImportResult> {
+  const raw = readFileSync(filePath, 'utf-8');
+  const pack: KnowledgePack = 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 };
+}

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

@@ -0,0 +1,5 @@
+export type { KnowledgePack, PackChunk, PackInfo } from './types.js';
+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';

package/packages/core/src/pack/marketplace.ts

@@ -0,0 +1,103 @@
+// Pack Marketplace (F-A07) — npm registry + GitHub Releases 기반
+// 서버 불필요: npm/GitHub를 마켓플레이스로 활용
+
+export interface PackListing {
+  name: string;
+  version: string;
+  description: string;
+  author: string;
+  downloads?: number;
+  tags: string[];
+  source: 'npm' | 'github';
+  installCommand: string;
+}
+
+// npm에서 @stellavault/pack-* 패키지 검색
+export async function searchMarketplace(query: string, limit = 10): Promise<PackListing[]> {
+  const results: PackListing[] = [];
+
+  try {
+    // npm registry search
+    const safeLimit = Math.min(limit, 20); // MED: 최대 20개 제한
+    const npmUrl = `https://registry.npmjs.org/-/v1/search?text=stellavault-pack+${encodeURIComponent(query)}&size=${safeLimit}`;
+    const res = await fetch(npmUrl, { signal: AbortSignal.timeout(5000) });
+    if (res.ok) {
+      const data = await res.json() as any;
+      for (const pkg of data.objects ?? []) {
+        results.push({
+          name: pkg.package.name,
+          version: pkg.package.version,
+          description: pkg.package.description ?? '',
+          author: pkg.package.author?.name ?? pkg.package.publisher?.username ?? 'unknown',
+          downloads: pkg.downloads?.weekly ?? 0,
+          tags: pkg.package.keywords ?? [],
+          source: 'npm',
+          installCommand: `npm install ${pkg.package.name}`,
+        });
+      }
+    }
+  } catch { /* npm search failed — continue */ }
+
+  try {
+    // GitHub search for stellavault-pack repos
+    const ghUrl = `https://api.github.com/search/repositories?q=stellavault-pack+${encodeURIComponent(query)}&per_page=${limit}`;
+    const res = await fetch(ghUrl, {
+      headers: { 'Accept': 'application/vnd.github.v3+json', 'User-Agent': 'stellavault-marketplace' },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.ok) {
+      const data = await res.json() as any;
+      for (const repo of data.items ?? []) {
+        // npm과 중복 방지
+        if (results.some(r => r.name === repo.name)) continue;
+        results.push({
+          name: repo.full_name,
+          version: 'latest',
+          description: repo.description ?? '',
+          author: repo.owner?.login ?? 'unknown',
+          downloads: repo.stargazers_count,
+          tags: repo.topics ?? [],
+          source: 'github',
+          installCommand: `sv pack import <(curl -sL ${repo.html_url}/releases/latest/download/pack.sv-pack)`,
+        });
+      }
+    }
+  } catch { /* GitHub search failed — continue */ }
+
+  return results;
+}
+
+// sv-pack 파일을 npm에 publish할 수 있도록 패키지 생성
+export function createPackageJson(packName: string, description: string, author: string, version = '1.0.0'): string {
+  return JSON.stringify({
+    name: `stellavault-pack-${packName}`,
+    version,
+    description,
+    author,
+    license: 'CC-BY-4.0',
+    keywords: ['stellavault', 'knowledge-pack', packName],
+    files: ['*.sv-pack', 'README.md'],
+    stellavault: { type: 'knowledge-pack' },
+  }, null, 2);
+}
+
+// GitHub Release로 pack 배포용 명령어 생성
+export function getPublishInstructions(packName: string): string {
+  return `
+To publish your Knowledge Pack:
+
+Option A: npm
+  1. cd your-pack-directory/
+  2. npm init (or use: sv pack prepare ${packName})
+  3. npm publish
+
+Option B: GitHub Release
+  1. Create a GitHub repo: stellavault-pack-${packName}
+  2. Add your .sv-pack file
+  3. Create a release with the .sv-pack as an asset
+
+Users install with:
+  npm: sv pack install stellavault-pack-${packName}
+  GitHub: sv pack import <url-to-sv-pack-file>
+`.trim();
+}

package/packages/core/src/pack/pii-masker.ts

@@ -0,0 +1,38 @@
+// Design Ref: Phase 3 FR-04 — PII 감지 + 마스킹
+
+const PII_PATTERNS: Array<{ name: string; regex: RegExp }> = [
+  { name: 'email', regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g },
+  { name: 'api_key', regex: /(?:sk|pk|api|key|token|secret|password)[_\-a-zA-Z]*[_\-][a-zA-Z0-9]{16,}/gi },
+  { name: 'aws_key', regex: /AKIA[0-9A-Z]{16}/g },
+  { name: 'url_with_auth', regex: /https?:\/\/[^:]+:[^@]+@[^\s]+/g },
+  { name: 'ip_address', regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g },
+  { name: 'phone', regex: /\b0\d{1,2}[-.\s]?\d{3,4}[-.\s]?\d{4}\b/g },
+  { name: 'jwt', regex: /eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}/g },
+];
+
+export interface MaskResult {
+  masked: string;
+  redactedCount: number;
+  redactedTypes: string[];
+}
+
+export function maskPII(text: string): MaskResult {
+  let masked = text;
+  let redactedCount = 0;
+  const redactedTypes = new Set<string>();
+
+  for (const { name, regex } of PII_PATTERNS) {
+    const matches = masked.match(regex);
+    if (matches) {
+      redactedCount += matches.length;
+      redactedTypes.add(name);
+      masked = masked.replace(regex, `[REDACTED:${name}]`);
+    }
+  }
+
+  return {
+    masked,
+    redactedCount,
+    redactedTypes: [...redactedTypes],
+  };
+}

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

@@ -0,0 +1,39 @@
+// Design Ref: Phase 3 §1 — .sv-pack.json 표준 포맷
+
+export interface KnowledgePack {
+  name: string;
+  version: string;
+  author: string;
+  license: string;
+  description: string;
+  tags: string[];
+  embeddingModel: string;
+  embeddingDimensions: number;
+  schemaVersion: string;
+  chunks: PackChunk[];
+  createdAt: string;
+}
+
+export interface PackChunk {
+  id: string;
+  content: string;
+  heading: string;
+  embedding: number[];
+  metadata: {
+    sourceFile: string;
+    category: string;
+    language?: string;
+    framework?: string;
+  };
+}
+
+export interface PackInfo {
+  name: string;
+  version: string;
+  author: string;
+  license: string;
+  description: string;
+  chunkCount: number;
+  embeddingModel: string;
+  createdAt: string;
+}

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

@@ -0,0 +1,100 @@
+// Plugin SDK (F-A15) — Event-driven plugin system
+
+export interface PluginContext {
+  store: {
+    search(query: string, limit?: number): Promise<any[]>;
+    getDocument(id: string): Promise<any>;
+    getStats(): Promise<any>;
+  };
+  config: Record<string, unknown>;
+  log: (message: string) => void;
+}
+
+export type PluginEvent =
+  | 'onIndex'       // After a document is indexed
+  | 'onSearch'      // After a search is performed
+  | 'onDecay'       // When decay check runs
+  | 'onGapDetected' // When a knowledge gap is found
+  | 'onStartup'     // When stellavault starts
+  | 'onShutdown';   // When stellavault stops
+
+export interface PluginManifest {
+  name: string;
+  version: string;
+  description: string;
+  author?: string;
+  events: PluginEvent[];
+}
+
+export interface StellavaultPlugin {
+  manifest: PluginManifest;
+  activate(context: PluginContext): Promise<void>;
+  deactivate?(): Promise<void>;
+  onEvent?(event: PluginEvent, data: unknown): Promise<void>;
+}
+
+type EventHandler = (data: unknown) => Promise<void>;
+
+export class PluginManager {
+  private plugins = new Map<string, StellavaultPlugin>();
+  private handlers = new Map<PluginEvent, Array<{ pluginName: string; handler: EventHandler }>>();
+  private context: PluginContext;
+
+  constructor(context: PluginContext) {
+    this.context = context;
+  }
+
+  async register(plugin: StellavaultPlugin): Promise<void> {
+    if (this.plugins.has(plugin.manifest.name)) {
+      throw new Error(`Plugin "${plugin.manifest.name}" is already registered`);
+    }
+
+    this.plugins.set(plugin.manifest.name, plugin);
+
+    // Register event handlers (MED fix: track by plugin name for proper unregister)
+    for (const event of plugin.manifest.events) {
+      if (!this.handlers.has(event)) this.handlers.set(event, []);
+      if (plugin.onEvent) {
+        this.handlers.get(event)!.push({
+          pluginName: plugin.manifest.name,
+          handler: (data) => plugin.onEvent!(event, data),
+        });
+      }
+    }
+
+    await plugin.activate(this.context);
+    this.context.log(`Plugin "${plugin.manifest.name}" v${plugin.manifest.version} activated`);
+  }
+
+  async unregister(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return;
+
+    await plugin.deactivate?.();
+    this.plugins.delete(name);
+
+    // MED fix: properly remove handlers by plugin name
+    for (const [event, entries] of this.handlers) {
+      this.handlers.set(event, entries.filter(e => e.pluginName !== name));
+    }
+  }
+
+  async emit(event: PluginEvent, data: unknown): Promise<void> {
+    const entries = this.handlers.get(event) ?? [];
+    for (const { handler } of entries) {
+      try {
+        await handler(data);
+      } catch (err) {
+        this.context.log(`Plugin error on ${event}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+
+  listPlugins(): PluginManifest[] {
+    return [...this.plugins.values()].map(p => p.manifest);
+  }
+
+  getPlugin(name: string): StellavaultPlugin | undefined {
+    return this.plugins.get(name);
+  }
+}