@comfanion/usethis_search 3.0.1 → 4.1.0-dev.1

package/cache/manager.ts

@@ -0,0 +1,751 @@
+/**
+ * Workspace Cache Manager
+ *
+ * In-memory cache of files attached to the AI's workspace context.
+ * search() attaches top results + graph relations here.
+ * message.before hook injects cached content into every LLM request.
+ *
+ * Persistence:
+ *   .opencode/.workspace/{sessionId}.json   — per-session workspace state
+ *   .opencode/.workspace/latest.json        — fallback (current session)
+ *
+ *   Only metadata + paths are saved. Content is re-read from disk on restore.
+ *
+ * Lifecycle:
+ *   search("auth") -> attach top N main files + graph relations
+ *   message.before -> inject all cached files into user message
+ *   workspace.detach / workspace.clear -> manual cleanup
+ *   ensureBudget() -> auto-evict oldest low-score files when over limit
+ *   save() / restore() -> persist to / load from .opencode/.workspace/
+ */
+
+import path from "path"
+import fs from "fs/promises"
+import crypto from "crypto"
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface WorkspaceEntry {
+  /** Relative file path (e.g. "src/auth/login.ts") */
+  path: string
+  /** Full file content (loaded in memory, NOT persisted to JSON) */
+  content: string
+  /** Estimated token count (~content.length / 4) */
+  tokens: number
+  /** MD5 hash of content — used by freshen() to detect disk changes */
+  contentHash: string
+  /** How this file got into workspace */
+  role: "search-main" | "search-graph" | "manual"
+  /** Timestamp when attached */
+  attachedAt: number
+  /** Search query or "manual" */
+  attachedBy: string
+  /** Search relevance score (0-1) */
+  score?: number
+  /** File metadata from search results */
+  metadata?: {
+    language?: string
+    function_name?: string
+    class_name?: string
+    heading_context?: string
+    /** Graph relation type (for role=search-graph) */
+    relation?: string
+    /** Which main file pulled this graph file in */
+    mainFile?: string
+  }
+}
+
+/** Serialized entry — content included only when persistContent=true */
+interface PersistedEntry {
+  path: string
+  tokens: number
+  role: WorkspaceEntry["role"]
+  attachedAt: number
+  attachedBy: string
+  score?: number
+  metadata?: WorkspaceEntry["metadata"]
+  /** Only present when config.persistContent=true (debug mode) */
+  content?: string
+}
+
+/** On-disk workspace snapshot */
+interface WorkspaceSnapshot {
+  sessionId: string
+  savedAt: string
+  totalTokens: number
+  fileCount: number
+  /** true if content is included in entries */
+  debug: boolean
+  entries: PersistedEntry[]
+}
+
+export interface WorkspaceConfig {
+  /** Max total tokens across all files (default: 50000) */
+  maxTokens: number
+  /** Max number of files (default: 30) */
+  maxFiles: number
+  /** How many top search results to attach (default: 5) */
+  attachTopN: number
+  /** Max graph relations per main file (default: 3) */
+  attachRelatedPerFile: number
+  /** Min score for main files to be attached (default: 0.65) */
+  minScoreMain: number
+  /** Min score for graph relations to be attached (default: 0.5) */
+  minScoreRelated: number
+  /**
+   * Save full file content in workspace snapshots (default: false).
+   * When true: .workspace/{sessionId}.json includes content for every file.
+   * Useful for debugging — see exactly what the AI saw.
+   * Warning: snapshots can be 10-50MB+ with content enabled.
+   */
+  persistContent: boolean
+  /**
+   * Auto-prune old search tool outputs from chat history (default: true).
+   * When true: message.before hook replaces old search outputs with 1-line summaries.
+   * Files are already in workspace injection — keeping big outputs wastes tokens.
+   */
+  autoPruneSearch: boolean
+  /**
+   * Substitute tool outputs when files are in workspace (default: true).
+   * When true: read(), grep(), glob() outputs are replaced with compact messages
+   * if all matched files are in workspace cache.
+   * Saves tokens since files are already visible in workspace injection.
+   */
+  substituteToolOutputs: boolean
+}
+
+export const DEFAULT_WORKSPACE_CONFIG: WorkspaceConfig = {
+  maxTokens: 50_000,
+  maxFiles: 30,
+  attachTopN: 5,
+  attachRelatedPerFile: 3,
+  minScoreMain: 0.65,
+  minScoreRelated: 0.5,
+  persistContent: false,
+  autoPruneSearch: true,
+  substituteToolOutputs: true,
+}
+
+// ── Implementation ──────────────────────────────────────────────────────────
+
+class WorkspaceCache {
+  private entries = new Map<string, WorkspaceEntry>()
+  private _totalTokens = 0
+  private config: WorkspaceConfig
+
+  /** Project root directory (set on init/restore) */
+  private projectRoot: string | null = null
+  /** Current session ID */
+  private sessionId: string | null = null
+  /** Auto-save debounce timer */
+  private _saveTimer: ReturnType<typeof setTimeout> | null = null
+  /** Debounce delay in ms */
+  private _saveDebounceMs = 2000
+  /** Files modified by edit/write since last freshen() — bypass substitution */
+  private dirtyFiles = new Set<string>()
+
+  constructor(config?: Partial<WorkspaceConfig>) {
+    this.config = { ...DEFAULT_WORKSPACE_CONFIG, ...config }
+  }
+
+  // ── Persistence ─────────────────────────────────────────────────────────
+
+  /**
+   * Directory where workspace snapshots are stored.
+   */
+  private getWorkspaceDir(): string | null {
+    if (!this.projectRoot) return null
+    return path.join(this.projectRoot, ".opencode", ".workspace")
+  }
+
+  /**
+   * Initialize workspace with project root and optional session ID.
+   * If a saved workspace exists for this session, it will be restored.
+   *
+   * Safe to call multiple times — second call with a different sessionId
+   * will save current state, then restore for the new session.
+   */
+  async init(projectRoot: string, sessionId?: string): Promise<void> {
+    // If re-initializing with a new session — flush current state first
+    if (this.projectRoot && this.sessionId && sessionId && sessionId !== this.sessionId) {
+      await this.save()
+    }
+
+    this.projectRoot = projectRoot
+    this.sessionId = sessionId || `session-${Date.now()}`
+
+    // Try to restore existing workspace for this session
+    const restored = await this.restore(this.sessionId)
+    if (restored) {
+      console.log(`[workspace] Restored session ${this.sessionId} (${this.entries.size} files, ${this._totalTokens} tokens)`)
+    } else if (!sessionId) {
+      // Only fall back to latest.json when no specific session requested
+      // (avoids clobbering a fresh session with stale data)
+      const restoredLatest = await this.restore("latest")
+      if (restoredLatest) {
+        console.log(`[workspace] Restored from latest (${this.entries.size} files, ${this._totalTokens} tokens)`)
+      }
+    }
+
+    // Register process exit handler (once)
+    this.registerShutdownHook()
+  }
+
+  /** Whether shutdown hook is registered */
+  private _shutdownRegistered = false
+
+  /**
+   * Register a graceful shutdown hook to flush workspace to disk.
+   * Prevents data loss on process exit / SIGTERM / SIGINT.
+   */
+  private registerShutdownHook(): void {
+    if (this._shutdownRegistered) return
+    this._shutdownRegistered = true
+
+    const flush = () => {
+      // Synchronous-ish flush — best effort
+      // Node process is exiting, so we can't await.
+      // Use writeFileSync as last resort.
+      try {
+        const dir = this.getWorkspaceDir()
+        if (!dir || this.entries.size === 0) return
+
+        const id = this.sessionId || "latest"
+        const includeContent = this.config.persistContent
+
+        const snapshot = {
+          sessionId: id,
+          savedAt: new Date().toISOString(),
+          totalTokens: this._totalTokens,
+          fileCount: this.entries.size,
+          debug: includeContent,
+          entries: Array.from(this.entries.values()).map(e => {
+            const p: any = {
+              path: e.path,
+              tokens: e.tokens,
+              role: e.role,
+              attachedAt: e.attachedAt,
+              attachedBy: e.attachedBy,
+              score: e.score,
+              metadata: e.metadata,
+            }
+            if (includeContent) p.content = e.content
+            return p
+          }),
+        }
+
+        const data = JSON.stringify(snapshot, null, 2)
+        const fsSync = require("fs")
+
+        fsSync.mkdirSync(dir, { recursive: true })
+        fsSync.writeFileSync(path.join(dir, `${id}.json`), data, "utf-8")
+        fsSync.writeFileSync(path.join(dir, "latest.json"), data, "utf-8")
+      } catch {
+        // Best effort — process is dying
+      }
+    }
+
+    process.on("exit", flush)
+    process.on("SIGINT", () => { flush(); process.exit(0) })
+    process.on("SIGTERM", () => { flush(); process.exit(0) })
+  }
+
+  /**
+   * Save workspace metadata to disk (debounced).
+   * Content is NOT saved — only paths + metadata.
+   */
+  scheduleSave(): void {
+    if (this._saveTimer) clearTimeout(this._saveTimer)
+    this._saveTimer = setTimeout(() => {
+      this.save().catch(err => {
+        console.error("[workspace] Save failed:", err)
+      })
+    }, this._saveDebounceMs)
+    // Don't keep the process alive just for a debounced save —
+    // the shutdown hook handles final flush synchronously.
+    if (this._saveTimer && typeof this._saveTimer === "object" && "unref" in this._saveTimer) {
+      ;(this._saveTimer as NodeJS.Timeout).unref()
+    }
+  }
+
+  /**
+   * Save workspace metadata to disk immediately.
+   */
+  async save(snapshotId?: string): Promise<void> {
+    const dir = this.getWorkspaceDir()
+    if (!dir) return
+
+    const id = snapshotId || this.sessionId || "latest"
+
+    const includeContent = this.config.persistContent
+
+    const snapshot: WorkspaceSnapshot = {
+      sessionId: id,
+      savedAt: new Date().toISOString(),
+      totalTokens: this._totalTokens,
+      fileCount: this.entries.size,
+      debug: includeContent,
+      entries: Array.from(this.entries.values()).map(e => {
+        const persisted: PersistedEntry = {
+          path: e.path,
+          tokens: e.tokens,
+          role: e.role,
+          attachedAt: e.attachedAt,
+          attachedBy: e.attachedBy,
+          score: e.score,
+          metadata: e.metadata,
+        }
+        if (includeContent) {
+          persisted.content = e.content
+        }
+        return persisted
+      }),
+    }
+
+    try {
+      await fs.mkdir(dir, { recursive: true })
+
+      // Save session-specific file
+      const sessionFile = path.join(dir, `${id}.json`)
+      await fs.writeFile(sessionFile, JSON.stringify(snapshot, null, 2), "utf-8")
+
+      // Also save as latest.json (always keep current state accessible)
+      const latestFile = path.join(dir, "latest.json")
+      await fs.writeFile(latestFile, JSON.stringify(snapshot, null, 2), "utf-8")
+    } catch (error) {
+      console.error("[workspace] Failed to save:", error)
+    }
+  }
+
+  /**
+   * Restore workspace from disk.
+   * Re-reads file content from project files (NOT from snapshot).
+   * Files that no longer exist on disk are skipped.
+   *
+   * Returns true if snapshot was found and loaded.
+   */
+  async restore(snapshotId?: string): Promise<boolean> {
+    const dir = this.getWorkspaceDir()
+    if (!dir || !this.projectRoot) return false
+
+    const id = snapshotId || this.sessionId || "latest"
+    const snapshotFile = path.join(dir, `${id}.json`)
+
+    let snapshot: WorkspaceSnapshot
+    try {
+      const raw = await fs.readFile(snapshotFile, "utf-8")
+      snapshot = JSON.parse(raw)
+    } catch {
+      return false // No snapshot found
+    }
+
+    // Clear current state
+    this.entries.clear()
+    this._totalTokens = 0
+
+    // Re-read file content from disk (or use saved content in debug mode)
+    let loaded = 0
+    let skipped = 0
+
+    for (const entry of snapshot.entries) {
+      let content: string | null = null
+
+      // If snapshot has content (debug mode) — use it directly
+      if (entry.content) {
+        content = entry.content
+      } else {
+        // Otherwise re-read from disk
+        try {
+          const fullPath = path.join(this.projectRoot, entry.path)
+          content = await fs.readFile(fullPath, "utf-8")
+        } catch {
+          // File no longer exists or unreadable
+        }
+      }
+
+      if (content === null) {
+        skipped++
+        continue
+      }
+
+      const tokens = this.countTokens(content)
+
+      this.entries.set(entry.path, {
+        path: entry.path,
+        content,
+        tokens,
+        contentHash: this.hashContent(content),
+        role: entry.role,
+        attachedAt: entry.attachedAt,
+        attachedBy: entry.attachedBy,
+        score: entry.score,
+        metadata: entry.metadata,
+      })
+      this._totalTokens += tokens
+      loaded++
+    }
+
+    if (skipped > 0) {
+      console.log(`[workspace] Restore: ${loaded} loaded, ${skipped} skipped (files missing)`)
+    }
+
+    return loaded > 0
+  }
+
+  /**
+   * List all saved workspace snapshots.
+   */
+  async listSnapshots(): Promise<{ id: string; savedAt: string; fileCount: number; totalTokens: number }[]> {
+    const dir = this.getWorkspaceDir()
+    if (!dir) return []
+
+    try {
+      const files = await fs.readdir(dir)
+      const snapshots: { id: string; savedAt: string; fileCount: number; totalTokens: number }[] = []
+
+      for (const file of files) {
+        if (!file.endsWith(".json") || file === "latest.json") continue
+
+        try {
+          const raw = await fs.readFile(path.join(dir, file), "utf-8")
+          const snap: WorkspaceSnapshot = JSON.parse(raw)
+          snapshots.push({
+            id: snap.sessionId,
+            savedAt: snap.savedAt,
+            fileCount: snap.fileCount,
+            totalTokens: snap.totalTokens,
+          })
+        } catch {
+          // Corrupt file — skip
+        }
+      }
+
+      // Sort by savedAt descending
+      snapshots.sort((a, b) => b.savedAt.localeCompare(a.savedAt))
+      return snapshots
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Delete a saved snapshot.
+   */
+  async deleteSnapshot(snapshotId: string): Promise<boolean> {
+    const dir = this.getWorkspaceDir()
+    if (!dir) return false
+
+    try {
+      await fs.unlink(path.join(dir, `${snapshotId}.json`))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // ── Core operations ─────────────────────────────────────────────────────
+
+  /**
+   * Attach a file to workspace.
+   * If file already exists, updates it (replaces content/score).
+   * Auto-saves to disk (debounced).
+   */
+  attach(entry: Omit<WorkspaceEntry, "tokens" | "contentHash">): void {
+    const tokens = this.countTokens(entry.content)
+    const contentHash = this.hashContent(entry.content)
+
+    // Update existing — subtract old tokens first
+    const existing = this.entries.get(entry.path)
+    if (existing) {
+      this._totalTokens -= existing.tokens
+    }
+
+    this.entries.set(entry.path, { ...entry, tokens, contentHash })
+    this._totalTokens += tokens
+
+    // Auto-evict if over budget
+    this.ensureBudget()
+
+    // Auto-save (debounced)
+    this.scheduleSave()
+  }
+
+  /**
+   * Remove a single file from workspace.
+   * Returns true if file was found and removed.
+   */
+  detach(filePath: string): boolean {
+    const entry = this.entries.get(filePath)
+    if (!entry) return false
+
+    this.entries.delete(filePath)
+    this._totalTokens -= entry.tokens
+
+    // Auto-save (debounced)
+    this.scheduleSave()
+    return true
+  }
+
+  /**
+   * Remove all files older than `ms` milliseconds.
+   * Returns number of files removed.
+   */
+  detachOlderThan(ms: number): number {
+    const cutoff = Date.now() - ms
+    let removed = 0
+
+    for (const [filePath, entry] of this.entries) {
+      if (entry.attachedAt < cutoff) {
+        this.entries.delete(filePath)
+        this._totalTokens -= entry.tokens
+        removed++
+      }
+    }
+
+    if (removed > 0) this.scheduleSave()
+    return removed
+  }
+
+  /**
+   * Remove all files that were attached by a specific search query.
+   * Returns number of files removed.
+   */
+  detachByQuery(query: string): number {
+    let removed = 0
+
+    for (const [filePath, entry] of this.entries) {
+      if (entry.attachedBy === query || entry.attachedBy.startsWith(`${query} (`)) {
+        this.entries.delete(filePath)
+        this._totalTokens -= entry.tokens
+        removed++
+      }
+    }
+
+    if (removed > 0) this.scheduleSave()
+    return removed
+  }
+
+  /**
+   * Get all entries sorted by: search-main first (by score desc), then search-graph, then manual.
+   */
+  getAll(): WorkspaceEntry[] {
+    return Array.from(this.entries.values()).sort((a, b) => {
+      // Main files first
+      const roleOrder = { "search-main": 0, "search-graph": 1, manual: 2 }
+      const ra = roleOrder[a.role] ?? 2
+      const rb = roleOrder[b.role] ?? 2
+      if (ra !== rb) return ra - rb
+
+      // Within same role: higher score first
+      if (a.score !== undefined && b.score !== undefined) {
+        return b.score - a.score
+      }
+
+      // Fallback: alphabetical
+      return a.path.localeCompare(b.path)
+    })
+  }
+
+  /**
+   * Check if a file is in workspace.
+   */
+  has(filePath: string): boolean {
+    return this.entries.has(filePath)
+  }
+
+  /**
+   * Get a single entry by path.
+   */
+  get(filePath: string): WorkspaceEntry | undefined {
+    return this.entries.get(filePath)
+  }
+
+  /**
+   * Remove all files from workspace.
+   */
+  clear(): void {
+    this.entries.clear()
+    this._totalTokens = 0
+    this.scheduleSave()
+  }
+
+  /**
+   * Total tokens across all cached files.
+   */
+  get totalTokens(): number {
+    return this._totalTokens
+  }
+
+  /**
+   * Number of files in workspace.
+   */
+  get size(): number {
+    return this.entries.size
+  }
+
+  /**
+   * Current session ID.
+   */
+  getSessionId(): string | null {
+    return this.sessionId
+  }
+
+  /**
+   * Current config (read-only).
+   */
+  getConfig(): Readonly<WorkspaceConfig> {
+    return this.config
+  }
+
+  /**
+   * Update config at runtime.
+   */
+  updateConfig(partial: Partial<WorkspaceConfig>): void {
+    Object.assign(this.config, partial)
+    this.ensureBudget()
+  }
+
+  /**
+   * Mark file as dirty (modified by edit/write tool).
+   * Dirty files bypass read() substitution until next freshen().
+   */
+  markDirty(filePath: string): void {
+    this.dirtyFiles.add(filePath)
+  }
+
+  /**
+   * Check if file is dirty (modified since last freshen).
+   */
+  isDirty(filePath: string): boolean {
+    return this.dirtyFiles.has(filePath)
+  }
+
+  /**
+   * Clear all dirty flags (called by freshen after re-reading files).
+   */
+  clearDirty(): void {
+    this.dirtyFiles.clear()
+  }
+
+  // ── Freshness ────────────────────────────────────────────────────────────
+
+  /**
+   * Re-read workspace files from disk if they changed.
+   * Compares stored contentHash with current file hash.
+   * Removes entries whose files no longer exist on disk.
+   *
+   * Called by message.before hook — ensures AI always sees fresh content.
+   * Cost: ~2ms for 30 files (stat + optional readFile).
+   *
+   * Returns { updated, removed } counts.
+   */
+  async freshen(): Promise<{ updated: number; removed: number }> {
+    if (!this.projectRoot) return { updated: 0, removed: 0 }
+
+    let updated = 0
+    let removed = 0
+
+    for (const [filePath, entry] of this.entries) {
+      try {
+        const fullPath = path.join(this.projectRoot, filePath)
+        const content = await fs.readFile(fullPath, "utf-8")
+        const newHash = this.hashContent(content)
+
+        if (newHash !== entry.contentHash) {
+          // File changed on disk — update in-memory
+          const oldTokens = entry.tokens
+          const newTokens = this.countTokens(content)
+
+          entry.content = content
+          entry.contentHash = newHash
+          entry.tokens = newTokens
+          this._totalTokens += newTokens - oldTokens
+
+          updated++
+        }
+      } catch {
+        // File no longer exists — remove from workspace
+        this.entries.delete(filePath)
+        this._totalTokens -= entry.tokens
+        removed++
+      }
+    }
+
+    if (updated > 0 || removed > 0) {
+      this.scheduleSave()
+    }
+
+    // Clear dirty flags — all files are now fresh from disk
+    this.clearDirty()
+
+    return { updated, removed }
+  }
+
+  // ── Budget management ───────────────────────────────────────────────────
+
+  /**
+   * Evict oldest / lowest-score files until within budget.
+   * Priority: evict search-graph first, then search-main, then manual.
+   * Within same role: lowest score first, then oldest first.
+   */
+  private ensureBudget(): void {
+    // Check both token and file count limits
+    if (
+      this._totalTokens <= this.config.maxTokens &&
+      this.entries.size <= this.config.maxFiles
+    ) {
+      return
+    }
+
+    // Build eviction priority list
+    const candidates = Array.from(this.entries.values()).sort((a, b) => {
+      // Evict graph files before main files before manual files
+      const roleOrder = { "search-graph": 0, "search-main": 1, manual: 2 }
+      const ra = roleOrder[a.role] ?? 2
+      const rb = roleOrder[b.role] ?? 2
+      if (ra !== rb) return ra - rb
+
+      // Within same role: lowest score first
+      const sa = a.score ?? 0
+      const sb = b.score ?? 0
+      if (sa !== sb) return sa - sb
+
+      // Then oldest first
+      return a.attachedAt - b.attachedAt
+    })
+
+    for (const entry of candidates) {
+      if (
+        this._totalTokens <= this.config.maxTokens &&
+        this.entries.size <= this.config.maxFiles
+      ) {
+        break
+      }
+
+      this.entries.delete(entry.path)
+      this._totalTokens -= entry.tokens
+    }
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────
+
+  /**
+   * Rough token count: ~4 chars per token.
+   */
+  private countTokens(content: string): number {
+    return Math.ceil(content.length / 4)
+  }
+
+  /**
+   * MD5 hash of content for change detection.
+   */
+  private hashContent(content: string): string {
+    return crypto.createHash("md5").update(content).digest("hex")
+  }
+}
+
+// ── Singleton ───────────────────────────────────────────────────────────────
+
+export const workspaceCache = new WorkspaceCache()
+
+export { WorkspaceCache }