claude-brain 0.3.0

package/src/config/watcher.ts

@@ -0,0 +1,86 @@
+import { watch, type FSWatcher } from 'node:fs'
+import { EventEmitter } from 'node:events'
+import { loadConfig, getConfigFilePath } from './loader'
+import type { Config } from './schema'
+
+export interface ConfigWatcherEvents {
+  change: (config: Config) => void
+  error: (error: Error) => void
+}
+
+/** Watches the config file for changes and emits events */
+export class ConfigWatcher extends EventEmitter {
+  private watcher: FSWatcher | null = null
+  private configPath: string
+  private currentConfig: Config | null = null
+  private debounceTimer: Timer | null = null
+  private readonly debounceMs = 100
+
+  constructor(basePath: string = process.cwd()) {
+    super()
+    this.configPath = getConfigFilePath(basePath)
+  }
+
+  /** Start watching the config file */
+  async start(): Promise<void> {
+    try {
+      this.currentConfig = await loadConfig()
+
+      this.watcher = watch(this.configPath, (eventType) => {
+        if (eventType === 'change') {
+          this.handleChange()
+        }
+      })
+
+      this.watcher.on('error', (error) => {
+        this.emit('error', error)
+      })
+    } catch (error) {
+      // Config file might not exist yet, that's ok
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error
+      }
+    }
+  }
+
+  /** Stop watching the config file */
+  stop(): void {
+    if (this.watcher) {
+      this.watcher.close()
+      this.watcher = null
+    }
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer)
+      this.debounceTimer = null
+    }
+  }
+
+  /** Get the current configuration */
+  getConfig(): Config | null {
+    return this.currentConfig
+  }
+
+  private handleChange(): void {
+    // Debounce rapid changes
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer)
+    }
+
+    this.debounceTimer = setTimeout(async () => {
+      try {
+        const newConfig = await loadConfig()
+        this.currentConfig = newConfig
+        this.emit('change', newConfig)
+      } catch (error) {
+        this.emit('error', error instanceof Error ? error : new Error(String(error)))
+      }
+    }, this.debounceMs)
+  }
+}
+
+/** Create and start a config watcher */
+export async function createConfigWatcher(basePath?: string): Promise<ConfigWatcher> {
+  const watcher = new ConfigWatcher(basePath)
+  await watcher.start()
+  return watcher
+}

package/src/context/assembler.ts

@@ -0,0 +1,398 @@
+/**
+ * Context Assembler
+ * Builds complete context from vault, memory, and metadata sources
+ */
+
+import type { Logger } from 'pino'
+import type { VaultManager } from '@/vault'
+import type { MemoryManager } from '@/memory'
+import type {
+  AssembledContext,
+  ProjectContext,
+  GlobalContext,
+  ContextOptions,
+  ProgressState,
+  CodeStandards
+} from './types'
+import { FallbackManager } from '@/utils'
+
+export class ContextAssembler {
+  private logger: Logger
+  private vault: VaultManager
+  private memory: MemoryManager
+  private fallbackManager: FallbackManager
+
+  constructor(
+    logger: Logger,
+    vault: VaultManager,
+    memory: MemoryManager
+  ) {
+    this.logger = logger.child({ component: 'context-assembler' })
+    this.vault = vault
+    this.memory = memory
+    this.fallbackManager = new FallbackManager(logger)
+  }
+
+  async assembleContext(
+    projectName: string,
+    options: ContextOptions = {
+      includeMemories: true,
+      includeProgress: true,
+      includeStandards: true,
+      maxTokens: 8000
+    }
+  ): Promise<AssembledContext> {
+    const startTime = Date.now()
+
+    try {
+      this.logger.info({ projectName }, 'Assembling context')
+
+      const projectContext = await this.loadProjectContext(projectName)
+      const globalContext = await this.loadGlobalContext()
+
+      const memories = options.includeMemories
+        ? await this.loadRelevantMemories(projectName, projectContext)
+        : []
+
+      const progress = options.includeProgress
+        ? await this.loadProgress(projectName)
+        : this.createEmptyProgress()
+
+      const standards = options.includeStandards
+        ? await this.loadStandards(projectName, globalContext)
+        : this.createEmptyStandards()
+
+      const assembled: AssembledContext = {
+        project: projectContext,
+        global: globalContext,
+        memories,
+        progress,
+        standards,
+        metadata: {
+          assembledAt: new Date(),
+          tokenCount: 0,
+          sources: this.getSources(projectName)
+        }
+      }
+
+      assembled.metadata.tokenCount = this.estimateTokens(assembled)
+
+      if (options.maxTokens && assembled.metadata.tokenCount > options.maxTokens) {
+        await this.applyTokenBudget(assembled, options.maxTokens)
+      }
+
+      const duration = Date.now() - startTime
+      this.logger.info(
+        { projectName, duration, tokens: assembled.metadata.tokenCount },
+        'Context assembled'
+      )
+
+      return assembled
+
+    } catch (error) {
+      this.logger.error({ error, projectName }, 'Failed to assemble context')
+      throw error
+    }
+  }
+
+  private async loadProjectContext(projectName: string): Promise<ProjectContext> {
+    const projectPaths = this.vault.getProjectPaths(projectName)
+
+    try {
+      const contextFile = await this.vault.reader.readMarkdownFile(projectPaths.context)
+
+      return {
+        name: projectName,
+        description: this.extractDescription(contextFile.content),
+        techStack: contextFile.frontmatter.tech_stack || [],
+        architecture: this.extractSection(contextFile.content, 'Architecture'),
+        goals: this.extractList(contextFile.content, 'Goals'),
+        constraints: this.extractList(contextFile.content, 'Constraints'),
+        currentPhase: contextFile.frontmatter.current_phase || 'unknown',
+        progress: this.createEmptyProgress(),
+        decisions: [],
+        standards: this.createEmptyStandards(),
+        teamPreferences: (contextFile.frontmatter.preferences as Record<string, unknown>) || {}
+      }
+    } catch {
+      return {
+        name: projectName,
+        description: '',
+        techStack: [],
+        architecture: '',
+        goals: [],
+        constraints: [],
+        currentPhase: 'unknown',
+        progress: this.createEmptyProgress(),
+        decisions: [],
+        standards: this.createEmptyStandards(),
+        teamPreferences: {}
+      }
+    }
+  }
+
+  private async loadGlobalContext(): Promise<GlobalContext> {
+    const globalPath = `${this.vault.paths.global}/standards.md`
+
+    try {
+      const globalFile = await this.vault.reader.readMarkdownFile(globalPath)
+
+      return {
+        standards: this.parseGlobalStandards(globalFile.content),
+        patterns: this.extractPatterns(globalFile.content),
+        bestPractices: this.extractBestPractices(globalFile.content),
+        commonPitfalls: this.extractPitfalls(globalFile.content)
+      }
+    } catch {
+      return {
+        standards: this.createEmptyStandards(),
+        patterns: {},
+        bestPractices: {},
+        commonPitfalls: []
+      }
+    }
+  }
+
+  private async loadRelevantMemories(
+    projectName: string,
+    projectContext: ProjectContext
+  ) {
+    const query = `${projectContext.description} ${projectContext.currentPhase}`
+
+    return this.fallbackManager.execute({
+      primary: async () => {
+        const results = await this.memory.searchRaw(query, {
+          project: projectName,
+          limit: 5,
+          minSimilarity: 0.6
+        })
+
+        return results.map(result => ({
+          content: result.memory.content,
+          similarity: result.similarity,
+          date: result.memory.createdAt,
+          tags: (result.memory.metadata?.tags as string[]) || []
+        }))
+      },
+      fallback: async () => {
+        this.logger.warn(
+          { projectName },
+          'Memory search unavailable, continuing without memories'
+        )
+        return []
+      }
+    })
+  }
+
+  private async loadProgress(projectName: string): Promise<ProgressState> {
+    const projectPaths = this.vault.getProjectPaths(projectName)
+
+    try {
+      const progressFile = await this.vault.reader.readMarkdownFile(projectPaths.progress)
+
+      return {
+        currentPhase: progressFile.frontmatter.current_phase || 'unknown',
+        completionPercentage: (progressFile.frontmatter.completion_percentage as number) || 0,
+        completedTasks: this.parseCompletedTasks(progressFile.content),
+        currentTasks: this.parseCurrentTasks(progressFile.content),
+        nextSteps: this.extractList(progressFile.content, 'Next Steps'),
+        blockers: this.parseBlockers(progressFile.content),
+        velocity: this.calculateVelocity(progressFile.content)
+      }
+    } catch {
+      return this.createEmptyProgress()
+    }
+  }
+
+  private async loadStandards(
+    projectName: string,
+    globalContext: GlobalContext
+  ): Promise<CodeStandards> {
+    const projectPaths = this.vault.getProjectPaths(projectName)
+
+    try {
+      const standardsFile = await this.vault.reader.readMarkdownFile(projectPaths.standards)
+      const projectStandards = this.parseProjectStandards(standardsFile.content)
+
+      return this.mergeStandards(globalContext.standards, projectStandards)
+    } catch {
+      return globalContext.standards
+    }
+  }
+
+  private async applyTokenBudget(
+    context: AssembledContext,
+    maxTokens: number
+  ): Promise<void> {
+    this.logger.info(
+      { current: context.metadata.tokenCount, max: maxTokens },
+      'Applying token budget'
+    )
+
+    if (context.memories.length > 3) {
+      context.memories = context.memories
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, 3)
+    }
+
+    context.metadata.tokenCount = this.estimateTokens(context)
+  }
+
+  private estimateTokens(context: AssembledContext): number {
+    const json = JSON.stringify(context)
+    return Math.ceil(json.length / 4)
+  }
+
+  private extractDescription(content: string): string {
+    const match = /##\s+Overview\s+(.+?)(?=\n##|$)/s.exec(content)
+    return match ? match[1].trim() : ''
+  }
+
+  private extractSection(content: string, sectionName: string): string {
+    const regex = new RegExp(`##\\s+${sectionName}\\s+(.+?)(?=\\n##|$)`, 's')
+    const match = regex.exec(content)
+    return match ? match[1].trim() : ''
+  }
+
+  private extractList(content: string, sectionName: string): string[] {
+    const section = this.extractSection(content, sectionName)
+    const listRegex = /^[-*]\s+(.+)$/gm
+    const items: string[] = []
+
+    let match
+    while ((match = listRegex.exec(section)) !== null) {
+      items.push(match[1].trim())
+    }
+
+    return items
+  }
+
+  private parseCompletedTasks(content: string): any[] {
+    const tasks: any[] = []
+    const completedRegex = /^[-*]\s+\[x\]\s+(.+?)(?:\(completed (.+?)\))?$/gim
+
+    let match
+    while ((match = completedRegex.exec(content)) !== null) {
+      tasks.push({
+        id: match[1].toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50),
+        title: match[1].trim(),
+        status: 'done',
+        completedAt: match[2] ? new Date(match[2]) : undefined
+      })
+    }
+
+    return tasks
+  }
+
+  private parseCurrentTasks(content: string): any[] {
+    const tasks: any[] = []
+    const currentRegex = /^[-*]\s+\[([ >])\]\s+(.+?)$/gim
+
+    let match
+    while ((match = currentRegex.exec(content)) !== null) {
+      const status = match[1] === '>' ? 'in-progress' : 'todo'
+      tasks.push({
+        id: match[2].toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50),
+        title: match[2].trim(),
+        status
+      })
+    }
+
+    return tasks
+  }
+
+  private parseBlockers(content: string): any[] {
+    const section = /##\s+Blockers\s+(.+?)(?=\n##|$)/is.exec(content)
+    if (!section) return []
+
+    const blockers: any[] = []
+    const blockerRegex = /^[-*]\s+\[(\w+)\]\s+(.+?)(?:\(since (.+?)\))?$/gim
+
+    let match
+    while ((match = blockerRegex.exec(section[1])) !== null) {
+      blockers.push({
+        description: match[2].trim(),
+        severity: match[1].toLowerCase(),
+        since: match[3] ? new Date(match[3]) : new Date()
+      })
+    }
+
+    return blockers
+  }
+
+  private calculateVelocity(content: string): number {
+    const completedTasks = this.parseCompletedTasks(content)
+
+    if (completedTasks.length === 0) return 0
+
+    const oneWeekAgo = new Date()
+    oneWeekAgo.setDate(oneWeekAgo.getDate() - 7)
+
+    const recentTasks = completedTasks.filter(task =>
+      task.completedAt && task.completedAt >= oneWeekAgo
+    )
+
+    return recentTasks.length
+  }
+
+  private parseGlobalStandards(content: string): CodeStandards {
+    return this.createEmptyStandards()
+  }
+
+  private parseProjectStandards(content: string): CodeStandards {
+    return this.createEmptyStandards()
+  }
+
+  private mergeStandards(
+    global: CodeStandards,
+    project: CodeStandards
+  ): CodeStandards {
+    return { ...global, ...project }
+  }
+
+  private extractPatterns(content: string): Record<string, unknown> {
+    return {}
+  }
+
+  private extractBestPractices(content: string): Record<string, unknown> {
+    return {}
+  }
+
+  private extractPitfalls(content: string): string[] {
+    return []
+  }
+
+  private getSources(projectName: string): string[] {
+    return [
+      `${projectName}/context.md`,
+      `${projectName}/progress.md`,
+      `${projectName}/standards.md`,
+      'Global/standards.md',
+      'Memory/decisions'
+    ]
+  }
+
+  private createEmptyProgress(): ProgressState {
+    return {
+      currentPhase: 'unknown',
+      completionPercentage: 0,
+      completedTasks: [],
+      currentTasks: [],
+      nextSteps: [],
+      blockers: [],
+      velocity: 0
+    }
+  }
+
+  private createEmptyStandards(): CodeStandards {
+    return {
+      languages: [],
+      frameworks: [],
+      naming: {} as any,
+      formatting: {} as any,
+      testing: {} as any,
+      documentation: {} as any,
+      security: {} as any
+    }
+  }
+}

package/src/context/cache-manager.ts

@@ -0,0 +1,101 @@
+/**
+ * Context Cache Manager
+ * Manages cached context with intelligent invalidation
+ */
+
+import type { Logger } from 'pino'
+import type { AssembledContext } from './types'
+
+interface CacheEntry {
+  context: AssembledContext
+  cachedAt: Date
+  ttl: number
+  dependencies: string[]
+}
+
+export class ContextCacheManager {
+  private cache: Map<string, CacheEntry>
+  private logger: Logger
+  private defaultTTL: number = 3600
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'context-cache' })
+    this.cache = new Map()
+  }
+
+  get(projectName: string): AssembledContext | null {
+    const entry = this.cache.get(projectName)
+
+    if (!entry) {
+      this.logger.debug({ projectName }, 'Cache miss')
+      return null
+    }
+
+    const age = Date.now() - entry.cachedAt.getTime()
+    if (age > entry.ttl * 1000) {
+      this.logger.debug({ projectName, age }, 'Cache expired')
+      this.cache.delete(projectName)
+      return null
+    }
+
+    this.logger.debug({ projectName }, 'Cache hit')
+    return entry.context
+  }
+
+  set(
+    projectName: string,
+    context: AssembledContext,
+    dependencies: string[],
+    ttl: number = this.defaultTTL
+  ): void {
+    this.cache.set(projectName, {
+      context,
+      cachedAt: new Date(),
+      ttl,
+      dependencies
+    })
+
+    this.logger.debug({ projectName, ttl }, 'Context cached')
+  }
+
+  invalidate(projectName: string): void {
+    this.cache.delete(projectName)
+    this.logger.info({ projectName }, 'Cache invalidated')
+  }
+
+  invalidateByFile(filePath: string): void {
+    let invalidatedCount = 0
+
+    for (const [projectName, entry] of this.cache) {
+      if (entry.dependencies.some(dep => filePath.includes(dep))) {
+        this.cache.delete(projectName)
+        invalidatedCount++
+      }
+    }
+
+    if (invalidatedCount > 0) {
+      this.logger.info(
+        { filePath, count: invalidatedCount },
+        'Cache invalidated by file change'
+      )
+    }
+  }
+
+  clear(): void {
+    this.cache.clear()
+    this.logger.info('All cache cleared')
+  }
+
+  getStats() {
+    const entries = Array.from(this.cache.values())
+    const now = Date.now()
+
+    return {
+      size: this.cache.size,
+      entries: Array.from(this.cache.keys()),
+      avgAge: entries.length > 0
+        ? entries.reduce((sum, e) => sum + (now - e.cachedAt.getTime()), 0) / entries.length / 1000
+        : 0
+    }
+  }
+}

package/src/context/formatter.ts

@@ -0,0 +1,84 @@
+/**
+ * Context Formatter
+ * Formats assembled context for Claude Code consumption
+ */
+
+import type { AssembledContext } from './types'
+
+export class ContextFormatter {
+  static format(context: AssembledContext): string {
+    let output = ''
+
+    output += `# Project: ${context.project.name}\n\n`
+    output += `${context.project.description}\n\n`
+
+    if (context.project.techStack.length > 0) {
+      output += `## Tech Stack\n`
+      output += context.project.techStack.map(tech => `- ${tech}`).join('\n')
+      output += '\n\n'
+    }
+
+    if (context.project.architecture) {
+      output += `## Architecture\n${context.project.architecture}\n\n`
+    }
+
+    output += `## Current Progress\n`
+    output += `**Phase:** ${context.progress.currentPhase}\n`
+    output += `**Completion:** ${context.progress.completionPercentage}%\n\n`
+
+    if (context.progress.currentTasks.length > 0) {
+      output += `**Current Tasks:**\n`
+      context.progress.currentTasks.forEach(task => {
+        output += `- ${task.title} (${task.status})\n`
+      })
+      output += '\n'
+    }
+
+    if (context.progress.nextSteps.length > 0) {
+      output += `**Next Steps:**\n`
+      context.progress.nextSteps.forEach(step => {
+        output += `- ${step}\n`
+      })
+      output += '\n'
+    }
+
+    if (context.progress.blockers.length > 0) {
+      output += `**Blockers:**\n`
+      context.progress.blockers.forEach(blocker => {
+        output += `- [${blocker.severity}] ${blocker.description}\n`
+      })
+      output += '\n'
+    }
+
+    if (context.memories.length > 0) {
+      output += `## Relevant Past Context\n\n`
+      context.memories.forEach((memory, i) => {
+        output += `### ${i + 1}. (${(memory.similarity * 100).toFixed(0)}% match)\n`
+        output += `${memory.content}\n\n`
+      })
+    }
+
+    if (context.standards.languages.length > 0) {
+      output += `## Coding Standards\n\n`
+      context.standards.languages.forEach(lang => {
+        output += `**${lang.language}:**\n`
+        if (lang.conventions.length > 0) {
+          output += `Conventions: ${lang.conventions.join(', ')}\n`
+        }
+        output += '\n'
+      })
+    }
+
+    return output
+  }
+
+  static formatJSON(context: AssembledContext): string {
+    return JSON.stringify(context, null, 2)
+  }
+
+  static formatConcise(context: AssembledContext): string {
+    return `${context.project.name} (${context.progress.currentPhase}, ${context.progress.completionPercentage}% complete)\n` +
+           `Tech: ${context.project.techStack.join(', ')}\n` +
+           `Next: ${context.progress.nextSteps.slice(0, 3).join(', ')}`
+  }
+}