claude-brain 0.5.1 → 0.8.0

package/src/packs/manager.ts

@@ -0,0 +1,204 @@
+/**
+ * Phase 18: Pack Manager
+ * Handles discovery, loading, and manifest tracking for knowledge packs
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import type { Logger } from 'pino'
+import type { PacksConfig } from '@/config/schema'
+import { KnowledgePackSchema, type KnowledgePack, type PackManifest } from './types'
+
+/** Maps tech stack names to relevant pack IDs */
+const STACK_MAP: Record<string, string[]> = {
+  // Languages
+  typescript: ['core/typescript'],
+  javascript: ['core/javascript'],
+
+  // Frontend frameworks
+  react: ['frontend/react'],
+  vue: ['frontend/react'], // reuse performance patterns; will add vue pack later
+  angular: ['frontend/react'],
+  svelte: ['frontend/react'],
+  'next.js': ['frontend/react'],
+  nuxt: ['frontend/react'],
+  remix: ['frontend/react'],
+  gatsby: ['frontend/react'],
+
+  // Backend
+  node: ['backend/node'],
+  express: ['backend/node'],
+  fastify: ['backend/node'],
+  hono: ['backend/node'],
+  elysia: ['backend/node'],
+  nestjs: ['backend/node'],
+  bun: ['backend/node'],
+
+  // Meta
+  jest: ['meta/testing'],
+  vitest: ['meta/testing'],
+  mocha: ['meta/testing'],
+  'bun:test': ['meta/testing'],
+  testing: ['meta/testing']
+}
+
+export class PackManager {
+  private logger: Logger
+  private config: PacksConfig
+  private packageRoot: string
+  private dataDir: string
+
+  constructor(logger: Logger, config: PacksConfig, packageRoot: string, dataDir: string) {
+    this.logger = logger.child({ component: 'pack-manager' })
+    this.config = config
+    this.packageRoot = packageRoot
+    this.dataDir = dataDir
+  }
+
+  /** Find pack IDs relevant to a given tech stack */
+  findRelevantPacks(techStack: string[]): string[] {
+    const packIds = new Set<string>()
+
+    // Always include core and meta packs when configured
+    if (this.config.alwaysLoadCore) {
+      packIds.add('core/typescript')
+      packIds.add('core/javascript')
+    }
+    if (this.config.alwaysLoadMeta) {
+      packIds.add('meta/testing')
+    }
+
+    // Add tech-stack specific packs
+    for (const tech of techStack) {
+      const normalizedTech = tech.toLowerCase()
+      const mapped = STACK_MAP[normalizedTech]
+      if (mapped) {
+        for (const packId of mapped) {
+          packIds.add(packId)
+        }
+      }
+    }
+
+    return Array.from(packIds)
+  }
+
+  /** Load and validate a pack from the packs directory */
+  async loadPack(packId: string): Promise<KnowledgePack> {
+    const packPath = path.join(this.packageRoot, this.config.packsDir, `${packId}.json`)
+
+    try {
+      const content = await fs.readFile(packPath, 'utf-8')
+      const raw = JSON.parse(content)
+      const pack = KnowledgePackSchema.parse(raw)
+      this.logger.debug({ packId, entries: pack.entries.length }, 'Pack loaded and validated')
+      return pack
+    } catch (error) {
+      this.logger.error({ error, packId, packPath }, 'Failed to load pack')
+      throw new Error(`Failed to load pack "${packId}": ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  /** Get the manifest for a project (tracks which packs are loaded) */
+  async getManifest(project: string): Promise<PackManifest> {
+    const manifestPath = this.getManifestPath(project)
+
+    try {
+      const content = await fs.readFile(manifestPath, 'utf-8')
+      return JSON.parse(content) as PackManifest
+    } catch {
+      // No manifest yet — return empty
+      return {
+        project,
+        packs: [],
+        lastUpdated: new Date().toISOString()
+      }
+    }
+  }
+
+  /** Save manifest after loading packs */
+  async saveManifest(manifest: PackManifest): Promise<void> {
+    const manifestPath = this.getManifestPath(manifest.project)
+    const manifestDir = path.dirname(manifestPath)
+
+    await fs.mkdir(manifestDir, { recursive: true })
+    manifest.lastUpdated = new Date().toISOString()
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8')
+
+    this.logger.debug({ project: manifest.project, packs: manifest.packs.length }, 'Manifest saved')
+  }
+
+  /** Delete manifest for a project (used by reload) */
+  async deleteManifest(project: string): Promise<void> {
+    const manifestPath = this.getManifestPath(project)
+    try {
+      await fs.unlink(manifestPath)
+    } catch {
+      // File didn't exist, that's fine
+    }
+  }
+
+  /** Check if a pack version is already loaded */
+  isPackLoaded(manifest: PackManifest, packId: string, version: string): boolean {
+    return manifest.packs.some(p => p.packId === packId && p.version === version)
+  }
+
+  /** List all available packs in the packs directory */
+  async listAvailablePacks(): Promise<Array<{ id: string; name: string; description: string; entries: number; version: string }>> {
+    const packsDir = path.join(this.packageRoot, this.config.packsDir)
+    const packs: Array<{ id: string; name: string; description: string; entries: number; version: string }> = []
+
+    try {
+      await this.scanPacksDir(packsDir, '', packs)
+    } catch (error) {
+      this.logger.warn({ error, packsDir }, 'Failed to scan packs directory')
+    }
+
+    return packs
+  }
+
+  private async scanPacksDir(
+    dir: string,
+    prefix: string,
+    result: Array<{ id: string; name: string; description: string; entries: number; version: string }>
+  ): Promise<void> {
+    let entries: import('fs').Dirent[]
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await this.scanPacksDir(
+          path.join(dir, entry.name),
+          prefix ? `${prefix}/${entry.name}` : entry.name,
+          result
+        )
+      } else if (entry.name.endsWith('.json')) {
+        const packId = prefix
+          ? `${prefix}/${entry.name.replace('.json', '')}`
+          : entry.name.replace('.json', '')
+
+        try {
+          const content = await fs.readFile(path.join(dir, entry.name), 'utf-8')
+          const raw = JSON.parse(content)
+          const pack = KnowledgePackSchema.parse(raw)
+          result.push({
+            id: packId,
+            name: pack.name,
+            description: pack.description,
+            entries: pack.entries.length,
+            version: pack.version
+          })
+        } catch (error) {
+          this.logger.warn({ error, packId }, 'Skipping invalid pack file')
+        }
+      }
+    }
+  }
+
+  private getManifestPath(project: string): string {
+    return path.join(this.dataDir, 'pack-manifests', `${project}.json`)
+  }
+}

package/src/packs/ranker.ts

@@ -0,0 +1,78 @@
+/**
+ * Phase 18: Knowledge Ranker
+ * Post-processing layer for search results that boosts personal entries
+ * over community (pack) entries
+ */
+
+import type { PacksConfig } from '@/config/schema'
+
+export interface RankedResult {
+  id: string
+  content: string
+  metadata: Record<string, any>
+  similarity: number
+  adjustedScore: number
+  badge: 'personal' | 'community'
+}
+
+export class KnowledgeRanker {
+  private personalBoost: number
+  private projectBoost: number
+
+  constructor(config: PacksConfig) {
+    this.personalBoost = config.personalBoost
+    this.projectBoost = config.projectBoost
+  }
+
+  /** Adjust similarity scores based on entry source */
+  rank(
+    results: Array<{ id: string; content: string; metadata: Record<string, any>; similarity: number }>,
+    currentProject?: string
+  ): RankedResult[] {
+    const ranked = results.map(result => {
+      const isCommunity = this.isCommunityEntry(result.metadata)
+      let adjustedScore = result.similarity
+
+      if (!isCommunity) {
+        // Personal entries get a boost
+        adjustedScore *= this.personalBoost
+
+        // Project-specific entries get an additional boost
+        if (currentProject && result.metadata.project === currentProject) {
+          adjustedScore *= this.projectBoost
+        }
+      }
+      // Community entries: no boost (effectively ranked lower)
+
+      // Cap at 1.0
+      adjustedScore = Math.min(adjustedScore, 1.0)
+
+      return {
+        id: result.id,
+        content: result.content,
+        metadata: result.metadata,
+        similarity: result.similarity,
+        adjustedScore,
+        badge: isCommunity ? 'community' as const : 'personal' as const
+      }
+    })
+
+    // Sort by adjusted score descending
+    return ranked.sort((a, b) => b.adjustedScore - a.adjustedScore)
+  }
+
+  /** Detect if a search result is from a community pack */
+  isCommunityEntry(metadata: Record<string, any>): boolean {
+    // Check source field
+    if (typeof metadata.source === 'string' && metadata.source.startsWith('pack:')) {
+      return true
+    }
+
+    // Check context field for community marker
+    if (typeof metadata.context === 'string' && metadata.context.includes('[community:pack:')) {
+      return true
+    }
+
+    return false
+  }
+}

package/src/packs/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Phase 18: Knowledge Pack Types & Schemas
+ * Defines the format for pre-seeded knowledge packs
+ */
+
+import { z } from 'zod'
+
+/** Valid entry types in a knowledge pack */
+export const PackEntryTypeSchema = z.enum([
+  'pattern',
+  'anti-pattern',
+  'best-practice',
+  'common-issue',
+  'decision-template'
+])
+
+export type PackEntryType = z.infer<typeof PackEntryTypeSchema>
+
+/** A single entry in a knowledge pack */
+export const PackEntrySchema = z.object({
+  type: PackEntryTypeSchema,
+  category: z.string().min(1),
+  title: z.string().min(1),
+  content: z.string().min(1),
+  confidence: z.number().min(0).max(1).default(0.85),
+  tags: z.array(z.string()).default([]),
+  example: z.string().optional()
+})
+
+export type PackEntry = z.infer<typeof PackEntrySchema>
+
+/** A complete knowledge pack with metadata */
+export const KnowledgePackSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semver'),
+  stack: z.array(z.string()).min(1),
+  description: z.string().min(1),
+  author: z.string().default('claude-brain'),
+  entries: z.array(PackEntrySchema).min(1),
+  metadata: z.record(z.string(), z.unknown()).optional()
+})
+
+export type KnowledgePack = z.infer<typeof KnowledgePackSchema>
+
+/** Tracks which packs have been loaded for a project */
+export interface PackManifestEntry {
+  packId: string
+  version: string
+  entriesLoaded: number
+  loadedAt: string
+}
+
+export interface PackManifest {
+  project: string
+  packs: PackManifestEntry[]
+  lastUpdated: string
+}
+
+/** Result of loading packs for a project */
+export interface PackLoadResult {
+  packsLoaded: number
+  entriesLoaded: number
+  packDetails: Array<{
+    packId: string
+    name: string
+    entriesLoaded: number
+  }>
+  skipped: Array<{
+    packId: string
+    reason: string
+  }>
+}
+
+/** Maps pack entry types to the storage pattern_type values */
+export const ENTRY_TYPE_TO_PATTERN_TYPE: Record<string, 'solution' | 'anti-pattern' | 'best-practice' | 'common-issue'> = {
+  'pattern': 'solution',
+  'anti-pattern': 'anti-pattern',
+  'best-practice': 'best-practice',
+  'common-issue': 'common-issue'
+}