shopify-ai-backup/opencode/specs/13-file-context-domain-split.md

File context domain split

Refactor context/file.tsx into focused modules with unchanged API.

---

Summary

packages/app/src/context/file.tsx still combines path normalization, file-content caching/eviction, file-tree loading, watcher event handling, and file-view persistence orchestration. Recent refactoring extracted generic scoped-cache primitives to packages/app/src/utils/scoped-cache.ts, but most file-domain behavior remains in one module. This spec separates those concerns while preserving the existing useFile() interface.

---

Goals

• Keep useFile() API stable for all callers.
• Extract independent domains into dedicated modules.
• Improve readability and lower risk for future file-tree/perf changes.
• Preserve current caching and watcher semantics.

---

Non-goals

• No redesign of file tree UI.
• No change to backend file APIs.
• No simultaneous refactor of components/file-tree.tsx in this workstream.

---

Parallel ownership (important)

This workstream owns:

• packages/app/src/context/file.tsx
• New files under packages/app/src/context/file/**
• packages/app/src/utils/scoped-cache.ts (only when required for file-view cache extraction)

This workstream must not edit:

• packages/app/src/context/global-sync.tsx (spec 12)
• packages/app/src/pages/session.tsx (spec 09)
• packages/app/src/components/prompt-input.tsx (spec 11)

---

Current state

• File size: ~751 LOC.
• packages/app/src/utils/scoped-cache.ts now exists as a shared cache primitive used by file view persistence.
• Multiple domains in one module:
  • path normalization/parsing
  • LRU content memory management
  • tree node/directory state management
  • event-driven watcher invalidation
  • per-session view cache bootstrapping

---

Proposed module split

Create packages/app/src/context/file/ modules such as:

• path.ts - normalize/strip helpers.
• content-cache.ts - content LRU + byte caps.
• view-cache.ts - per-session file view persistence cache (building on createScopedCache).
• tree-store.ts - directory/node store and list/expand/collapse actions.
• watcher.ts - watcher event handling and invalidation routines.

file.tsx remains the provider entry that composes these modules.

---

Phased steps

1. Extract path helper functions with no behavior changes.
2. Extract content cache and eviction logic.
3. Extract file-specific view-cache loading/pruning logic on top of createScopedCache.
4. Extract tree-store list/refresh/toggle actions.
5. Extract watcher update handler and wire cleanup.
6. Keep useFile() return shape unchanged.

---

Acceptance criteria

• useFile() API remains backward compatible.
• context/file.tsx is reduced significantly (target: under 350 LOC).
• Tree loading/refresh and content eviction behavior remain unchanged.
• Watcher-driven reload behavior still works for changed/added/deleted files.

---

Validation plan

• Typecheck: bun run typecheck (from packages/app).
• Targeted e2e checks:
  • e2e/files/file-tree.spec.ts
  • e2e/files/file-viewer.spec.ts
  • e2e/files/file-open.spec.ts
• Manual checks:
  • directory expand/collapse and refresh
  • large file navigation and cache reuse
  • watcher-driven updates in active file tabs

---

Handoff notes

• Keep tree/data stores colocated with their mutation helpers.
• Avoid changing persisted key names or cache key shapes in this pass.
• Save broader API cleanups for a follow-up once modules are stable.