claude-brain 0.30.2 → 0.30.3

package/src/utils/timing.ts

@@ -1,47 +1,47 @@
-/**
- * Timing Utility
- * Phase 22: Wraps async operations with performance timing.
- * Logs warnings for operations exceeding 200ms.
- */
-
-const SLOW_THRESHOLD_MS = 200
-
-/**
- * Wrap an async operation with timing instrumentation.
- * Logs a warning if the operation exceeds 200ms.
- */
-export async function timed<T>(label: string, fn: () => Promise<T>): Promise<T> {
-  const start = performance.now()
-  try {
-    const result = await fn()
-    const elapsed = performance.now() - start
-    if (elapsed > SLOW_THRESHOLD_MS) {
-      // Use console.error to avoid interfering with MCP stdio
-      console.error(`[SLOW] ${label}: ${Math.round(elapsed)}ms (budget: ${SLOW_THRESHOLD_MS}ms)`)
-    }
-    return result
-  } catch (error) {
-    const elapsed = performance.now() - start
-    console.error(`[ERROR] ${label}: ${Math.round(elapsed)}ms — ${error instanceof Error ? error.message : 'unknown'}`)
-    throw error
-  }
-}
-
-/**
- * Synchronous version for non-async operations.
- */
-export function timedSync<T>(label: string, fn: () => T): T {
-  const start = performance.now()
-  try {
-    const result = fn()
-    const elapsed = performance.now() - start
-    if (elapsed > SLOW_THRESHOLD_MS) {
-      console.error(`[SLOW] ${label}: ${Math.round(elapsed)}ms (budget: ${SLOW_THRESHOLD_MS}ms)`)
-    }
-    return result
-  } catch (error) {
-    const elapsed = performance.now() - start
-    console.error(`[ERROR] ${label}: ${Math.round(elapsed)}ms — ${error instanceof Error ? error.message : 'unknown'}`)
-    throw error
-  }
-}
+/**
+ * Timing Utility
+ * Phase 22: Wraps async operations with performance timing.
+ * Logs warnings for operations exceeding 200ms.
+ */
+
+const SLOW_THRESHOLD_MS = 200
+
+/**
+ * Wrap an async operation with timing instrumentation.
+ * Logs a warning if the operation exceeds 200ms.
+ */
+export async function timed<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  const start = performance.now()
+  try {
+    const result = await fn()
+    const elapsed = performance.now() - start
+    if (elapsed > SLOW_THRESHOLD_MS) {
+      // Use console.error to avoid interfering with MCP stdio
+      console.error(`[SLOW] ${label}: ${Math.round(elapsed)}ms (budget: ${SLOW_THRESHOLD_MS}ms)`)
+    }
+    return result
+  } catch (error) {
+    const elapsed = performance.now() - start
+    console.error(`[ERROR] ${label}: ${Math.round(elapsed)}ms — ${error instanceof Error ? error.message : 'unknown'}`)
+    throw error
+  }
+}
+
+/**
+ * Synchronous version for non-async operations.
+ */
+export function timedSync<T>(label: string, fn: () => T): T {
+  const start = performance.now()
+  try {
+    const result = fn()
+    const elapsed = performance.now() - start
+    if (elapsed > SLOW_THRESHOLD_MS) {
+      console.error(`[SLOW] ${label}: ${Math.round(elapsed)}ms (budget: ${SLOW_THRESHOLD_MS}ms)`)
+    }
+    return result
+  } catch (error) {
+    const elapsed = performance.now() - start
+    console.error(`[ERROR] ${label}: ${Math.round(elapsed)}ms — ${error instanceof Error ? error.message : 'unknown'}`)
+    throw error
+  }
+}

package/src/utils/transaction.ts

@@ -1,63 +1,63 @@
-import type { Logger } from 'pino'
-
-export class TransactionManager {
-  private logger: Logger
-  private operations: Array<() => Promise<void>> = []
-  private rollbacks: Array<() => Promise<void>> = []
-
-  constructor(logger: Logger) {
-    this.logger = logger.child({ component: 'transaction-manager' })
-  }
-
-  add(
-    operation: () => Promise<void>,
-    rollback: () => Promise<void>
-  ): void {
-    this.operations.push(operation)
-    this.rollbacks.unshift(rollback)
-  }
-
-  async execute(): Promise<void> {
-    const executedCount = 0
-
-    try {
-      for (let i = 0; i < this.operations.length; i++) {
-        await this.operations[i]!()
-      }
-
-      this.logger.info(
-        { operationCount: this.operations.length },
-        'Transaction completed successfully'
-      )
-
-    } catch (error) {
-      this.logger.error(
-        { error, executedCount },
-        'Transaction failed, rolling back'
-      )
-
-      await this.rollback()
-      throw error
-    }
-  }
-
-  private async rollback(): Promise<void> {
-    for (const rollback of this.rollbacks) {
-      try {
-        await rollback()
-      } catch (error) {
-        this.logger.error(
-          { error },
-          'Rollback operation failed'
-        )
-      }
-    }
-
-    this.logger.info('Rollback completed')
-  }
-
-  clear(): void {
-    this.operations = []
-    this.rollbacks = []
-  }
-}
+import type { Logger } from 'pino'
+
+export class TransactionManager {
+  private logger: Logger
+  private operations: Array<() => Promise<void>> = []
+  private rollbacks: Array<() => Promise<void>> = []
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'transaction-manager' })
+  }
+
+  add(
+    operation: () => Promise<void>,
+    rollback: () => Promise<void>
+  ): void {
+    this.operations.push(operation)
+    this.rollbacks.unshift(rollback)
+  }
+
+  async execute(): Promise<void> {
+    const executedCount = 0
+
+    try {
+      for (let i = 0; i < this.operations.length; i++) {
+        await this.operations[i]!()
+      }
+
+      this.logger.info(
+        { operationCount: this.operations.length },
+        'Transaction completed successfully'
+      )
+
+    } catch (error) {
+      this.logger.error(
+        { error, executedCount },
+        'Transaction failed, rolling back'
+      )
+
+      await this.rollback()
+      throw error
+    }
+  }
+
+  private async rollback(): Promise<void> {
+    for (const rollback of this.rollbacks) {
+      try {
+        await rollback()
+      } catch (error) {
+        this.logger.error(
+          { error },
+          'Rollback operation failed'
+        )
+      }
+    }
+
+    this.logger.info('Rollback completed')
+  }
+
+  clear(): void {
+    this.operations = []
+    this.rollbacks = []
+  }
+}

package/src/vault/index.ts

@@ -52,10 +52,11 @@ export class VaultManager {
     this.paths = VaultPathUtils.getVaultPaths(vaultRoot)
     this.reader = new VaultReader(logger, {
       maxCacheSize: 100,
-      cacheMaxAge: 5 * 60 * 1000
+      cacheMaxAge: 5 * 60 * 1000,
+      baseDir: vaultRoot
     })
-    this.writer = new VaultWriter(logger, this.config.backupDir)
-    this.watcher = new VaultWatcher(logger, this.config.debounceMs)
+    this.writer = new VaultWriter(logger, this.config.backupDir, vaultRoot)
+    this.watcher = new VaultWatcher(logger, this.config.debounceMs, vaultRoot)
     this.query = new VaultQuery(this.reader, logger)
 
     // Wire up watcher to invalidate cache on file changes

package/src/vault/paths.ts

@@ -1,106 +1,106 @@
-/**
- * Vault Path Utilities
- * Utilities for working with vault directory structure and paths
- */
-
-import path from 'path'
-import type { VaultPaths, ProjectPaths } from './types'
-
-export class VaultPathUtils {
-  /**
-   * Get all vault paths from root
-   */
-  static getVaultPaths(vaultRoot: string): VaultPaths {
-    return {
-      root: vaultRoot,
-      projects: path.join(vaultRoot, 'Projects'),
-      global: path.join(vaultRoot, 'Global'),
-      templates: path.join(vaultRoot, 'Templates'),
-      memory: path.join(vaultRoot, 'Memory')
-    }
-  }
-
-  /**
-   * Get all paths for a specific project
-   */
-  static getProjectPaths(
-    vaultRoot: string,
-    projectName: string
-  ): ProjectPaths {
-    const projectRoot = path.join(vaultRoot, 'Projects', projectName)
-    return {
-      root: projectRoot,
-      context: path.join(projectRoot, 'context.md'),
-      decisions: path.join(projectRoot, 'decisions.md'),
-      progress: path.join(projectRoot, 'progress.md'),
-      standards: path.join(projectRoot, 'standards.md'),
-      patterns: path.join(projectRoot, 'patterns.md'),
-      corrections: path.join(projectRoot, 'corrections.md')
-    }
-  }
-
-  /**
-   * Validate project name (kebab-case, no special chars)
-   */
-  static isValidProjectName(name: string): boolean {
-    return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)
-  }
-
-  /**
-   * Normalize project name to kebab-case
-   */
-  static normalizeProjectName(name: string): string {
-    return name
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-  }
-
-  /**
-   * Extract project name from a file path
-   */
-  static extractProjectName(filePath: string, vaultRoot: string): string | null {
-    const projectsPath = path.join(vaultRoot, 'Projects')
-    const relativePath = path.relative(projectsPath, filePath)
-
-    if (relativePath.startsWith('..')) {
-      return null // File is not inside Projects directory
-    }
-
-    const parts = relativePath.split(path.sep)
-    const projectName = parts[0]
-    return projectName !== undefined && projectName !== '' ? projectName : null
-  }
-
-  /**
-   * Check if a path is inside the vault
-   */
-  static isInsideVault(filePath: string, vaultRoot: string): boolean {
-    const resolvedPath = path.resolve(filePath)
-    const resolvedRoot = path.resolve(vaultRoot)
-    // Ensure the vault root ends with separator for proper prefix matching
-    // This prevents /vault matching /vaultx
-    const normalizedRoot = resolvedRoot.endsWith(path.sep)
-      ? resolvedRoot
-      : resolvedRoot + path.sep
-    return resolvedPath === resolvedRoot || resolvedPath.startsWith(normalizedRoot)
-  }
-
-  /**
-   * Get the relative path from vault root
-   */
-  static getRelativePath(filePath: string, vaultRoot: string): string {
-    return path.relative(vaultRoot, filePath)
-  }
-
-  /**
-   * Join paths safely within the vault
-   */
-  static joinVaultPath(vaultRoot: string, ...segments: string[]): string {
-    const joined = path.join(vaultRoot, ...segments)
-    if (!VaultPathUtils.isInsideVault(joined, vaultRoot)) {
-      throw new Error('Path traversal detected: path escapes vault root')
-    }
-    return joined
-  }
-}
+/**
+ * Vault Path Utilities
+ * Utilities for working with vault directory structure and paths
+ */
+
+import path from 'path'
+import type { VaultPaths, ProjectPaths } from './types'
+
+export class VaultPathUtils {
+  /**
+   * Get all vault paths from root
+   */
+  static getVaultPaths(vaultRoot: string): VaultPaths {
+    return {
+      root: vaultRoot,
+      projects: path.join(vaultRoot, 'Projects'),
+      global: path.join(vaultRoot, 'Global'),
+      templates: path.join(vaultRoot, 'Templates'),
+      memory: path.join(vaultRoot, 'Memory')
+    }
+  }
+
+  /**
+   * Get all paths for a specific project
+   */
+  static getProjectPaths(
+    vaultRoot: string,
+    projectName: string
+  ): ProjectPaths {
+    const projectRoot = path.join(vaultRoot, 'Projects', projectName)
+    return {
+      root: projectRoot,
+      context: path.join(projectRoot, 'context.md'),
+      decisions: path.join(projectRoot, 'decisions.md'),
+      progress: path.join(projectRoot, 'progress.md'),
+      standards: path.join(projectRoot, 'standards.md'),
+      patterns: path.join(projectRoot, 'patterns.md'),
+      corrections: path.join(projectRoot, 'corrections.md')
+    }
+  }
+
+  /**
+   * Validate project name (kebab-case, no special chars)
+   */
+  static isValidProjectName(name: string): boolean {
+    return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)
+  }
+
+  /**
+   * Normalize project name to kebab-case
+   */
+  static normalizeProjectName(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+  }
+
+  /**
+   * Extract project name from a file path
+   */
+  static extractProjectName(filePath: string, vaultRoot: string): string | null {
+    const projectsPath = path.join(vaultRoot, 'Projects')
+    const relativePath = path.relative(projectsPath, filePath)
+
+    if (relativePath.startsWith('..')) {
+      return null // File is not inside Projects directory
+    }
+
+    const parts = relativePath.split(path.sep)
+    const projectName = parts[0]
+    return projectName !== undefined && projectName !== '' ? projectName : null
+  }
+
+  /**
+   * Check if a path is inside the vault
+   */
+  static isInsideVault(filePath: string, vaultRoot: string): boolean {
+    const resolvedPath = path.resolve(filePath)
+    const resolvedRoot = path.resolve(vaultRoot)
+    // Ensure the vault root ends with separator for proper prefix matching
+    // This prevents /vault matching /vaultx
+    const normalizedRoot = resolvedRoot.endsWith(path.sep)
+      ? resolvedRoot
+      : resolvedRoot + path.sep
+    return resolvedPath === resolvedRoot || resolvedPath.startsWith(normalizedRoot)
+  }
+
+  /**
+   * Get the relative path from vault root
+   */
+  static getRelativePath(filePath: string, vaultRoot: string): string {
+    return path.relative(vaultRoot, filePath)
+  }
+
+  /**
+   * Join paths safely within the vault
+   */
+  static joinVaultPath(vaultRoot: string, ...segments: string[]): string {
+    const joined = path.join(vaultRoot, ...segments)
+    if (!VaultPathUtils.isInsideVault(joined, vaultRoot)) {
+      throw new Error('Path traversal detected: path escapes vault root')
+    }
+    return joined
+  }
+}

package/src/vault/query.ts

@@ -71,7 +71,10 @@ export class VaultQuery {
       // Read all files
       const markdownFiles = await Promise.all(
         allFiles.map(f =>
-          this.reader.readMarkdownFile(f).catch(() => null)
+          this.reader.readMarkdownFile(f).catch((error) => {
+            this.logger.warn({ error, file: f }, 'Failed to read markdown file')
+            return null
+          })
         )
       )
 

package/src/vault/reader.ts

@@ -8,6 +8,7 @@ import path from 'path'
 import matter from 'gray-matter'
 import type { Logger } from 'pino'
 import type { MarkdownFile, Frontmatter } from './types'
+import { validatePath } from '@/utils/safe-path'
 
 export interface CacheStats {
   size: number
@@ -20,16 +21,18 @@ export class VaultReader {
   private logger: Logger
   private maxCacheSize: number
   private cacheMaxAge: number // milliseconds
+  private baseDir: string
 
   constructor(
     logger: Logger,
-    options: { maxCacheSize?: number; cacheMaxAge?: number } = {}
+    options: { maxCacheSize?: number; cacheMaxAge?: number; baseDir?: string } = {}
   ) {
     this.logger = logger.child({ component: 'vault-reader' })
     this.cache = new Map()
     this.cacheTimestamps = new Map()
     this.maxCacheSize = options.maxCacheSize ?? 100
     this.cacheMaxAge = options.cacheMaxAge ?? 5 * 60 * 1000 // 5 minutes default
+    this.baseDir = options.baseDir ?? ''
   }
 
   /**
@@ -39,6 +42,16 @@ export class VaultReader {
     filePath: string,
     useCache: boolean = true
   ): Promise<MarkdownFile> {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(filePath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, filePath, baseDir: this.baseDir }, 'Path traversal blocked in readMarkdownFile')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
     // Check cache first
     if (useCache && this.isCacheValid(filePath)) {
       this.logger.debug({ filePath }, 'Cache hit')
@@ -104,6 +117,16 @@ export class VaultReader {
     dirPath: string,
     recursive: boolean = false
   ): Promise<string[]> {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(dirPath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, dirPath, baseDir: this.baseDir }, 'Path traversal blocked in readDirectory')
+        throw new Error(`Path validation failed for ${dirPath}: ${error}`)
+      }
+    }
+
     try {
       const entries = await fs.readdir(dirPath, { withFileTypes: true })
       let files: string[] = []
@@ -130,6 +153,16 @@ export class VaultReader {
    * Get all project directories
    */
   async getProjectDirectories(projectsPath: string): Promise<string[]> {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(projectsPath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, projectsPath, baseDir: this.baseDir }, 'Path traversal blocked in getProjectDirectories')
+        throw new Error(`Path validation failed for ${projectsPath}: ${error}`)
+      }
+    }
+
     try {
       const entries = await fs.readdir(projectsPath, { withFileTypes: true })
       return entries
@@ -149,6 +182,16 @@ export class VaultReader {
     created: Date
     modified: Date
   } | null> {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(filePath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, filePath, baseDir: this.baseDir }, 'Path traversal blocked in getFileStats')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
     try {
       const stats = await fs.stat(filePath)
       return {

package/src/vault/watcher.ts

@@ -8,6 +8,7 @@ import fs from 'fs/promises'
 import path from 'path'
 import { EventEmitter } from 'events'
 import type { Logger } from 'pino'
+import { validatePath } from '@/utils/safe-path'
 
 export type FileChangeType = 'created' | 'modified' | 'deleted'
 
@@ -36,14 +37,16 @@ export class VaultWatcher extends EventEmitter {
   private debounceTimers: Map<string, NodeJS.Timeout>
   private debounceMs: number
   private fileStates: Map<string, boolean> // Track if file exists
+  private baseDir: string
 
-  constructor(logger: Logger, debounceMs: number = 500) {
+  constructor(logger: Logger, debounceMs: number = 500, baseDir: string = '') {
     super()
     this.logger = logger.child({ component: 'vault-watcher' })
     this.watchers = new Map()
     this.debounceTimers = new Map()
     this.debounceMs = debounceMs
     this.fileStates = new Map()
+    this.baseDir = baseDir
   }
 
   /**
@@ -70,6 +73,16 @@ export class VaultWatcher extends EventEmitter {
    * Start watching a directory
    */
   watch(dirPath: string, recursive: boolean = true): void {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(dirPath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, dirPath, baseDir: this.baseDir }, 'Path traversal blocked in watch')
+        throw new Error(`Path validation failed for ${dirPath}: ${error}`)
+      }
+    }
+
     if (this.watchers.has(dirPath)) {
       this.logger.warn({ dirPath }, 'Already watching directory')
       return
@@ -105,6 +118,16 @@ export class VaultWatcher extends EventEmitter {
    * Stop watching a directory
    */
   unwatch(dirPath: string): void {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(dirPath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, dirPath, baseDir: this.baseDir }, 'Path traversal blocked in unwatch')
+        throw new Error(`Path validation failed for ${dirPath}: ${error}`)
+      }
+    }
+
     const watcher = this.watchers.get(dirPath)
     if (watcher) {
       watcher.close()