claude-brain 0.30.2 → 0.30.3

package/src/vault/writer.ts

@@ -1,413 +1,487 @@
-/**
- * Vault File Writer
- * Utilities for safely updating vault content with atomic writes and backups
- */
-
-import fs from 'fs/promises'
-import path from 'path'
-import matter from 'gray-matter'
-import type { Logger } from 'pino'
-import type { Frontmatter } from './types'
-import { TEMPLATES, renderTemplate, createProjectVariables, getTodayDate } from './templates'
-import { RetryManager } from '@/utils'
-
-export interface WriteOptions {
-  createBackup?: boolean
-  ensureDirectory?: boolean
-}
-
-export class VaultWriter {
-  private logger: Logger
-  private backupDir: string
-  private retryManager: RetryManager
-
-  constructor(logger: Logger, backupDir: string) {
-    this.logger = logger.child({ component: 'vault-writer' })
-    this.backupDir = backupDir
-    this.retryManager = new RetryManager(logger)
-  }
-
-  /**
-   * Write markdown file with frontmatter atomically
-   * Falls back to direct write if rename fails (e.g., Obsidian has file open)
-   */
-  async writeMarkdownFile(
-    filePath: string,
-    frontmatter: Frontmatter,
-    content: string,
-    options: WriteOptions = {}
-  ): Promise<void> {
-    return this.retryManager.execute(
-      async () => {
-        const { createBackup = true, ensureDirectory = true } = options
-
-        try {
-          if (createBackup && (await this.fileExists(filePath))) {
-            await this.createBackup(filePath)
-          }
-
-          const fileContent = matter.stringify(content, frontmatter)
-
-          if (ensureDirectory) {
-            await fs.mkdir(path.dirname(filePath), { recursive: true })
-          }
-
-          // Try atomic write first (temp file + rename)
-          const tempPath = `${filePath}.tmp`
-          try {
-            await fs.writeFile(tempPath, fileContent, 'utf-8')
-            await fs.rename(tempPath, filePath)
-          } catch (renameError) {
-            // If rename fails (EPERM - file locked by Obsidian), write directly
-            const isPermError = (renameError as NodeJS.ErrnoException).code === 'EPERM'
-            if (isPermError) {
-              this.logger.warn({ filePath }, 'Atomic write failed (file locked), using direct write')
-              await fs.writeFile(filePath, fileContent, 'utf-8')
-              // Clean up temp file
-              try {
-                await fs.unlink(tempPath)
-              } catch {}
-            } else {
-              throw renameError
-            }
-          }
-
-          this.logger.info({ filePath }, 'File written successfully')
-        } catch (error) {
-          try {
-            await fs.unlink(`${filePath}.tmp`)
-          } catch {
-          }
-
-          this.logger.error({ error, filePath }, 'Failed to write file')
-          throw new Error(`Failed to write file ${filePath}: ${error}`)
-        }
-      },
-      {
-        maxRetries: 3,
-        retryCondition: RetryManager.isRetryableError,
-        onRetry: (error, attempt) => {
-          this.logger.warn(
-            { error: error.message, attempt, filePath },
-            'Retrying file write'
-          )
-        }
-      }
-    )
-  }
-
-  /**
-   * Update only the frontmatter of a file
-   */
-  async updateFrontmatter(
-    filePath: string,
-    updates: Partial<Frontmatter>
-  ): Promise<void> {
-    try {
-      // Read existing file
-      const rawContent = await fs.readFile(filePath, 'utf-8')
-      const { data, content } = matter(rawContent)
-
-      // Merge updates and update timestamp
-      const newFrontmatter: Frontmatter = {
-        ...(data as Frontmatter),
-        ...updates,
-        updated: getTodayDate()
-      }
-
-      // Write back
-      await this.writeMarkdownFile(filePath, newFrontmatter, content, {
-        createBackup: true
-      })
-
-      this.logger.info({ filePath, updates }, 'Frontmatter updated')
-    } catch (error) {
-      this.logger.error({ error, filePath }, 'Failed to update frontmatter')
-      throw error
-    }
-  }
-
-  /**
-   * Append content to a file
-   * Creates the file (and parent directories) if it doesn't exist
-   */
-  async appendContent(
-    filePath: string,
-    newContent: string,
-    separator: string = '\n\n'
-  ): Promise<void> {
-    try {
-      let rawContent: string
-      try {
-        rawContent = await fs.readFile(filePath, 'utf-8')
-      } catch (readError: any) {
-        if (readError.code === 'ENOENT') {
-          // File doesn't exist — create it with the new content
-          const today = getTodayDate()
-          const frontmatter: Frontmatter = {
-            created: today,
-            updated: today
-          }
-          await this.writeMarkdownFile(filePath, frontmatter, newContent, {
-            createBackup: false,
-            ensureDirectory: true
-          })
-          this.logger.info({ filePath }, 'File created with initial content')
-          return
-        }
-        throw readError
-      }
-
-      const { data, content } = matter(rawContent)
-
-      // Append new content
-      const updatedContent = content.trim() + separator + newContent
-
-      // Update timestamp in frontmatter
-      const today = getTodayDate()
-      const updatedFrontmatter: Frontmatter = {
-        ...(data as Frontmatter),
-        updated: today,
-        last_updated: today
-      }
-
-      // Write back
-      await this.writeMarkdownFile(filePath, updatedFrontmatter, updatedContent, {
-        createBackup: true
-      })
-
-      this.logger.info({ filePath }, 'Content appended')
-    } catch (error) {
-      this.logger.error({ error, filePath }, 'Failed to append content')
-      throw error
-    }
-  }
-
-  /**
-   * Prepend content to a file (after frontmatter)
-   */
-  async prependContent(
-    filePath: string,
-    newContent: string,
-    separator: string = '\n\n'
-  ): Promise<void> {
-    try {
-      // Read existing file
-      const rawContent = await fs.readFile(filePath, 'utf-8')
-      const { data, content } = matter(rawContent)
-
-      // Prepend new content
-      const updatedContent = newContent + separator + content.trim()
-
-      // Update timestamp in frontmatter
-      const updatedFrontmatter: Frontmatter = {
-        ...(data as Frontmatter),
-        updated: getTodayDate()
-      }
-
-      // Write back
-      await this.writeMarkdownFile(filePath, updatedFrontmatter, updatedContent, {
-        createBackup: true
-      })
-
-      this.logger.info({ filePath }, 'Content prepended')
-    } catch (error) {
-      this.logger.error({ error, filePath }, 'Failed to prepend content')
-      throw error
-    }
-  }
-
-  /**
-   * Replace a section in a file by header
-   */
-  async replaceSection(
-    filePath: string,
-    sectionHeader: string,
-    newSectionContent: string
-  ): Promise<boolean> {
-    try {
-      const rawContent = await fs.readFile(filePath, 'utf-8')
-      const { data, content } = matter(rawContent)
-
-      // Find the section using regex
-      const headerPattern = new RegExp(
-        `(^|\\n)(#{1,6}\\s*${this.escapeRegex(sectionHeader)}\\s*\\n)`,
-        'i'
-      )
-      const match = content.match(headerPattern)
-
-      if (!match || !match[1] || !match[2]) {
-        this.logger.warn({ filePath, sectionHeader }, 'Section not found')
-        return false
-      }
-
-      // Find the end of the section (next header of same or higher level)
-      const headerMatch = match[2].match(/^#+/)
-      const headerLevel = headerMatch?.[0]?.length ?? 1
-      const startIndex = (match.index ?? 0) + match[0].length
-      const remainingContent = content.substring(startIndex)
-
-      const nextHeaderPattern = new RegExp(`\\n#{1,${headerLevel}}\\s+`)
-      const nextMatch = remainingContent.match(nextHeaderPattern)
-      const endIndex = nextMatch
-        ? startIndex + (nextMatch.index ?? 0)
-        : content.length
-
-      // Build new content
-      const before = content.substring(0, (match.index ?? 0) + match[1].length)
-      const sectionTitle = match[2]
-      const after = content.substring(endIndex)
-      const updatedContent = before + sectionTitle + newSectionContent + after
-
-      // Update frontmatter timestamp
-      const updatedFrontmatter: Frontmatter = {
-        ...(data as Frontmatter),
-        updated: getTodayDate()
-      }
-
-      await this.writeMarkdownFile(filePath, updatedFrontmatter, updatedContent, {
-        createBackup: true
-      })
-
-      this.logger.info({ filePath, sectionHeader }, 'Section replaced')
-      return true
-    } catch (error) {
-      this.logger.error({ error, filePath }, 'Failed to replace section')
-      throw error
-    }
-  }
-
-  /**
-   * Create a backup of a file
-   */
-  private async createBackup(filePath: string): Promise<string | null> {
-    try {
-      const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
-      const basename = path.basename(filePath)
-      const backupPath = path.join(this.backupDir, `${basename}.${timestamp}.bak`)
-
-      await fs.mkdir(this.backupDir, { recursive: true })
-      await fs.copyFile(filePath, backupPath)
-
-      this.logger.debug({ filePath, backupPath }, 'Backup created')
-      return backupPath
-    } catch (error) {
-      this.logger.warn({ error, filePath }, 'Failed to create backup')
-      // Don't throw - backup failure shouldn't prevent write
-      return null
-    }
-  }
-
-  /**
-   * Check if file exists
-   */
-  private async fileExists(filePath: string): Promise<boolean> {
-    try {
-      await fs.access(filePath)
-      return true
-    } catch {
-      return false
-    }
-  }
-
-  /**
-   * Delete a file
-   */
-  async deleteFile(
-    filePath: string,
-    createBackup: boolean = true
-  ): Promise<void> {
-    try {
-      if (createBackup) {
-        await this.createBackup(filePath)
-      }
-
-      await fs.unlink(filePath)
-      this.logger.info({ filePath }, 'File deleted')
-    } catch (error) {
-      this.logger.error({ error, filePath }, 'Failed to delete file')
-      throw error
-    }
-  }
-
-  /**
-   * Create directory structure for a new project
-   */
-  async createProjectStructure(
-    projectPath: string,
-    projectName: string
-  ): Promise<void> {
-    try {
-      await fs.mkdir(projectPath, { recursive: true })
-
-      const variables = createProjectVariables(projectName)
-
-      // Create each file from template
-      const files = [
-        { name: 'context.md', template: TEMPLATES.PROJECT_CONTEXT },
-        { name: 'decisions.md', template: TEMPLATES.DECISIONS_LOG },
-        { name: 'progress.md', template: TEMPLATES.PROGRESS_TRACKER },
-        { name: 'standards.md', template: TEMPLATES.CODING_STANDARDS },
-        { name: 'patterns.md', template: TEMPLATES.PATTERNS_LOG },
-        { name: 'corrections.md', template: TEMPLATES.CORRECTIONS_LOG }
-      ]
-
-      for (const file of files) {
-        const content = renderTemplate(file.template, variables)
-        const filePath = path.join(projectPath, file.name)
-
-        // Parse the rendered template to separate frontmatter and content
-        const { data, content: body } = matter(content)
-
-        await this.writeMarkdownFile(filePath, data as Frontmatter, body, {
-          createBackup: false,
-          ensureDirectory: false
-        })
-      }
-
-      this.logger.info({ projectPath, projectName }, 'Project structure created')
-    } catch (error) {
-      this.logger.error({ error, projectPath }, 'Failed to create project')
-      throw error
-    }
-  }
-
-  /**
-   * Clean old backups (keep only recent ones)
-   */
-  async cleanOldBackups(maxAge: number = 7 * 24 * 60 * 60 * 1000): Promise<number> {
-    try {
-      const entries = await fs.readdir(this.backupDir, { withFileTypes: true })
-      const now = Date.now()
-      let cleaned = 0
-
-      for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.bak')) continue
-
-        const filePath = path.join(this.backupDir, entry.name)
-        const stats = await fs.stat(filePath)
-
-        if (now - stats.mtimeMs > maxAge) {
-          await fs.unlink(filePath)
-          cleaned++
-        }
-      }
-
-      if (cleaned > 0) {
-        this.logger.info({ cleaned }, 'Old backups cleaned')
-      }
-
-      return cleaned
-    } catch (error) {
-      this.logger.warn({ error }, 'Failed to clean old backups')
-      return 0
-    }
-  }
-
-  /**
-   * Escape special regex characters
-   */
-  private escapeRegex(str: string): string {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-  }
-}
+/**
+ * Vault File Writer
+ * Utilities for safely updating vault content with atomic writes and backups
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import type { Logger } from 'pino'
+import type { Frontmatter } from './types'
+import { TEMPLATES, renderTemplate, createProjectVariables, getTodayDate } from './templates'
+import { RetryManager } from '@/utils'
+import { validatePath } from '@/utils/safe-path'
+
+export interface WriteOptions {
+  createBackup?: boolean
+  ensureDirectory?: boolean
+}
+
+export class VaultWriter {
+  private logger: Logger
+  private backupDir: string
+  private retryManager: RetryManager
+  private baseDir: string
+
+  constructor(logger: Logger, backupDir: string, baseDir: string = '') {
+    this.logger = logger.child({ component: 'vault-writer' })
+    this.backupDir = backupDir
+    this.baseDir = baseDir
+    this.retryManager = new RetryManager(logger)
+  }
+
+  /**
+   * Write markdown file with frontmatter atomically
+   * Falls back to direct write if rename fails (e.g., Obsidian has file open)
+   */
+  async writeMarkdownFile(
+    filePath: string,
+    frontmatter: Frontmatter,
+    content: string,
+    options: WriteOptions = {}
+  ): Promise<void> {
+    // 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 writeMarkdownFile')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
+    return this.retryManager.execute(
+      async () => {
+        const { createBackup = true, ensureDirectory = true } = options
+
+        try {
+          if (createBackup && (await this.fileExists(filePath))) {
+            await this.createBackup(filePath)
+          }
+
+          const fileContent = matter.stringify(content, frontmatter)
+
+          if (ensureDirectory) {
+            await fs.mkdir(path.dirname(filePath), { recursive: true })
+          }
+
+          // Try atomic write first (temp file + rename)
+          const tempPath = `${filePath}.tmp`
+          try {
+            await fs.writeFile(tempPath, fileContent, 'utf-8')
+            await fs.rename(tempPath, filePath)
+          } catch (renameError) {
+            // If rename fails (EPERM - file locked by Obsidian), write directly
+            const isPermError = (renameError as NodeJS.ErrnoException).code === 'EPERM'
+            if (isPermError) {
+              this.logger.warn({ filePath }, 'Atomic write failed (file locked), using direct write')
+              await fs.writeFile(filePath, fileContent, 'utf-8')
+              // Clean up temp file
+              try {
+                await fs.unlink(tempPath)
+              } catch {}
+            } else {
+              throw renameError
+            }
+          }
+
+          this.logger.info({ filePath }, 'File written successfully')
+        } catch (error) {
+          try {
+            await fs.unlink(`${filePath}.tmp`)
+          } catch {
+            // Temp file cleanup — safe to ignore if already removed
+          }
+
+          this.logger.error({ error, filePath }, 'Failed to write file')
+          throw new Error(`Failed to write file ${filePath}: ${error}`)
+        }
+      },
+      {
+        maxRetries: 3,
+        retryCondition: RetryManager.isRetryableError,
+        onRetry: (error, attempt) => {
+          this.logger.warn(
+            { error: error.message, attempt, filePath },
+            'Retrying file write'
+          )
+        }
+      }
+    )
+  }
+
+  /**
+   * Update only the frontmatter of a file
+   */
+  async updateFrontmatter(
+    filePath: string,
+    updates: Partial<Frontmatter>
+  ): Promise<void> {
+    // 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 updateFrontmatter')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
+    try {
+      // Read existing file
+      const rawContent = await fs.readFile(filePath, 'utf-8')
+      const { data, content } = matter(rawContent)
+
+      // Merge updates and update timestamp
+      const newFrontmatter: Frontmatter = {
+        ...(data as Frontmatter),
+        ...updates,
+        updated: getTodayDate()
+      }
+
+      // Write back
+      await this.writeMarkdownFile(filePath, newFrontmatter, content, {
+        createBackup: true
+      })
+
+      this.logger.info({ filePath, updates }, 'Frontmatter updated')
+    } catch (error) {
+      this.logger.error({ error, filePath }, 'Failed to update frontmatter')
+      throw error
+    }
+  }
+
+  /**
+   * Append content to a file
+   * Creates the file (and parent directories) if it doesn't exist
+   */
+  async appendContent(
+    filePath: string,
+    newContent: string,
+    separator: string = '\n\n'
+  ): Promise<void> {
+    // 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 appendContent')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
+    try {
+      let rawContent: string
+      try {
+        rawContent = await fs.readFile(filePath, 'utf-8')
+      } catch (readError: unknown) {
+        if ((readError as Record<string, unknown>)?.code === 'ENOENT') {
+          // File doesn't exist — create it with the new content
+          const today = getTodayDate()
+          const frontmatter: Frontmatter = {
+            created: today,
+            updated: today
+          }
+          await this.writeMarkdownFile(filePath, frontmatter, newContent, {
+            createBackup: false,
+            ensureDirectory: true
+          })
+          this.logger.info({ filePath }, 'File created with initial content')
+          return
+        }
+        throw readError
+      }
+
+      const { data, content } = matter(rawContent)
+
+      // Append new content
+      const updatedContent = content.trim() + separator + newContent
+
+      // Update timestamp in frontmatter
+      const today = getTodayDate()
+      const updatedFrontmatter: Frontmatter = {
+        ...(data as Frontmatter),
+        updated: today,
+        last_updated: today
+      }
+
+      // Write back
+      await this.writeMarkdownFile(filePath, updatedFrontmatter, updatedContent, {
+        createBackup: true
+      })
+
+      this.logger.info({ filePath }, 'Content appended')
+    } catch (error) {
+      this.logger.error({ error, filePath }, 'Failed to append content')
+      throw error
+    }
+  }
+
+  /**
+   * Prepend content to a file (after frontmatter)
+   */
+  async prependContent(
+    filePath: string,
+    newContent: string,
+    separator: string = '\n\n'
+  ): Promise<void> {
+    // 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 prependContent')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
+    try {
+      // Read existing file
+      const rawContent = await fs.readFile(filePath, 'utf-8')
+      const { data, content } = matter(rawContent)
+
+      // Prepend new content
+      const updatedContent = newContent + separator + content.trim()
+
+      // Update timestamp in frontmatter
+      const updatedFrontmatter: Frontmatter = {
+        ...(data as Frontmatter),
+        updated: getTodayDate()
+      }
+
+      // Write back
+      await this.writeMarkdownFile(filePath, updatedFrontmatter, updatedContent, {
+        createBackup: true
+      })
+
+      this.logger.info({ filePath }, 'Content prepended')
+    } catch (error) {
+      this.logger.error({ error, filePath }, 'Failed to prepend content')
+      throw error
+    }
+  }
+
+  /**
+   * Replace a section in a file by header
+   */
+  async replaceSection(
+    filePath: string,
+    sectionHeader: string,
+    newSectionContent: string
+  ): Promise<boolean> {
+    // 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 replaceSection')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
+    try {
+      const rawContent = await fs.readFile(filePath, 'utf-8')
+      const { data, content } = matter(rawContent)
+
+      // Find the section using regex
+      const headerPattern = new RegExp(
+        `(^|\\n)(#{1,6}\\s*${this.escapeRegex(sectionHeader)}\\s*\\n)`,
+        'i'
+      )
+      const match = content.match(headerPattern)
+
+      if (!match || !match[1] || !match[2]) {
+        this.logger.warn({ filePath, sectionHeader }, 'Section not found')
+        return false
+      }
+
+      // Find the end of the section (next header of same or higher level)
+      const headerMatch = match[2].match(/^#+/)
+      const headerLevel = headerMatch?.[0]?.length ?? 1
+      const startIndex = (match.index ?? 0) + match[0].length
+      const remainingContent = content.substring(startIndex)
+
+      const nextHeaderPattern = new RegExp(`\\n#{1,${headerLevel}}\\s+`)
+      const nextMatch = remainingContent.match(nextHeaderPattern)
+      const endIndex = nextMatch
+        ? startIndex + (nextMatch.index ?? 0)
+        : content.length
+
+      // Build new content
+      const before = content.substring(0, (match.index ?? 0) + match[1].length)
+      const sectionTitle = match[2]
+      const after = content.substring(endIndex)
+      const updatedContent = before + sectionTitle + newSectionContent + after
+
+      // Update frontmatter timestamp
+      const updatedFrontmatter: Frontmatter = {
+        ...(data as Frontmatter),
+        updated: getTodayDate()
+      }
+
+      await this.writeMarkdownFile(filePath, updatedFrontmatter, updatedContent, {
+        createBackup: true
+      })
+
+      this.logger.info({ filePath, sectionHeader }, 'Section replaced')
+      return true
+    } catch (error) {
+      this.logger.error({ error, filePath }, 'Failed to replace section')
+      throw error
+    }
+  }
+
+  /**
+   * Create a backup of a file
+   */
+  private async createBackup(filePath: string): Promise<string | null> {
+    try {
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+      const basename = path.basename(filePath)
+      const backupPath = path.join(this.backupDir, `${basename}.${timestamp}.bak`)
+
+      await fs.mkdir(this.backupDir, { recursive: true })
+      await fs.copyFile(filePath, backupPath)
+
+      this.logger.debug({ filePath, backupPath }, 'Backup created')
+      return backupPath
+    } catch (error) {
+      this.logger.warn({ error, filePath }, 'Failed to create backup')
+      // Don't throw - backup failure shouldn't prevent write
+      return null
+    }
+  }
+
+  /**
+   * Check if file exists
+   */
+  private async fileExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Delete a file
+   */
+  async deleteFile(
+    filePath: string,
+    createBackup: boolean = true
+  ): Promise<void> {
+    // 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 deleteFile')
+        throw new Error(`Path validation failed for ${filePath}: ${error}`)
+      }
+    }
+
+    try {
+      if (createBackup) {
+        await this.createBackup(filePath)
+      }
+
+      await fs.unlink(filePath)
+      this.logger.info({ filePath }, 'File deleted')
+    } catch (error) {
+      this.logger.error({ error, filePath }, 'Failed to delete file')
+      throw error
+    }
+  }
+
+  /**
+   * Create directory structure for a new project
+   */
+  async createProjectStructure(
+    projectPath: string,
+    projectName: string
+  ): Promise<void> {
+    // Validate path against base directory
+    if (this.baseDir) {
+      try {
+        validatePath(projectPath, this.baseDir)
+      } catch (error) {
+        this.logger.error({ error, projectPath, baseDir: this.baseDir }, 'Path traversal blocked in createProjectStructure')
+        throw new Error(`Path validation failed for ${projectPath}: ${error}`)
+      }
+    }
+
+    try {
+      await fs.mkdir(projectPath, { recursive: true })
+
+      const variables = createProjectVariables(projectName)
+
+      // Create each file from template
+      const files = [
+        { name: 'context.md', template: TEMPLATES.PROJECT_CONTEXT },
+        { name: 'decisions.md', template: TEMPLATES.DECISIONS_LOG },
+        { name: 'progress.md', template: TEMPLATES.PROGRESS_TRACKER },
+        { name: 'standards.md', template: TEMPLATES.CODING_STANDARDS },
+        { name: 'patterns.md', template: TEMPLATES.PATTERNS_LOG },
+        { name: 'corrections.md', template: TEMPLATES.CORRECTIONS_LOG }
+      ]
+
+      for (const file of files) {
+        const content = renderTemplate(file.template, variables)
+        const filePath = path.join(projectPath, file.name)
+
+        // Parse the rendered template to separate frontmatter and content
+        const { data, content: body } = matter(content)
+
+        await this.writeMarkdownFile(filePath, data as Frontmatter, body, {
+          createBackup: false,
+          ensureDirectory: false
+        })
+      }
+
+      this.logger.info({ projectPath, projectName }, 'Project structure created')
+    } catch (error) {
+      this.logger.error({ error, projectPath }, 'Failed to create project')
+      throw error
+    }
+  }
+
+  /**
+   * Clean old backups (keep only recent ones)
+   */
+  async cleanOldBackups(maxAge: number = 7 * 24 * 60 * 60 * 1000): Promise<number> {
+    try {
+      const entries = await fs.readdir(this.backupDir, { withFileTypes: true })
+      const now = Date.now()
+      let cleaned = 0
+
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.bak')) continue
+
+        const filePath = path.join(this.backupDir, entry.name)
+        const stats = await fs.stat(filePath)
+
+        if (now - stats.mtimeMs > maxAge) {
+          await fs.unlink(filePath)
+          cleaned++
+        }
+      }
+
+      if (cleaned > 0) {
+        this.logger.info({ cleaned }, 'Old backups cleaned')
+      }
+
+      return cleaned
+    } catch (error) {
+      this.logger.warn({ error }, 'Failed to clean old backups')
+      return 0
+    }
+  }
+
+  /**
+   * Escape special regex characters
+   */
+  private escapeRegex(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  }
+}