refactor(file): effectify FileService as scoped service (#17845)

2026-03-16 16:18:39 -04:00
parent df6508530f
commit 69381f6aea
3 changed files with 1098 additions and 557 deletions
@@ -8,6 +8,7 @@ import { FileWatcherService } from "@/file/watcher"
 import { VcsService } from "@/project/vcs"
 import { FileTimeService } from "@/file/time"
 import { FormatService } from "@/format"
+import { FileService } from "@/file"
 import { Instance } from "@/project/instance"

 export { InstanceContext } from "./instance-context"
@@ -20,6 +21,7 @@ export type InstanceServices =
  | VcsService
  | FileTimeService
  | FormatService
+  | FileService

 function lookup(directory: string) {
  const project = Instance.project
@@ -32,6 +34,7 @@ function lookup(directory: string) {
    Layer.fresh(VcsService.layer),
    Layer.fresh(FileTimeService.layer).pipe(Layer.orDie),
    Layer.fresh(FormatService.layer),
+    Layer.fresh(FileService.layer),
  ).pipe(Layer.provide(ctx))
 }

@@ -12,68 +12,13 @@ import fuzzysort from "fuzzysort"
 import { Global } from "../global"
 import { git } from "@/util/git"
 import { Protected } from "./protected"
+import { InstanceContext } from "@/effect/instance-context"
+import { Effect, Layer, ServiceMap } from "effect"
+import { runPromiseInstance } from "@/effect/runtime"

-export namespace File {
-  const log = Log.create({ service: "file" })
+const log = Log.create({ service: "file" })

-  export const Info = z
-    .object({
-      path: z.string(),
-      added: z.number().int(),
-      removed: z.number().int(),
-      status: z.enum(["added", "deleted", "modified"]),
-    })
-    .meta({
-      ref: "File",
-    })
-
-  export type Info = z.infer<typeof Info>
-
-  export const Node = z
-    .object({
-      name: z.string(),
-      path: z.string(),
-      absolute: z.string(),
-      type: z.enum(["file", "directory"]),
-      ignored: z.boolean(),
-    })
-    .meta({
-      ref: "FileNode",
-    })
-  export type Node = z.infer<typeof Node>
-
-  export const Content = z
-    .object({
-      type: z.enum(["text", "binary"]),
-      content: z.string(),
-      diff: z.string().optional(),
-      patch: z
-        .object({
-          oldFileName: z.string(),
-          newFileName: z.string(),
-          oldHeader: z.string().optional(),
-          newHeader: z.string().optional(),
-          hunks: z.array(
-            z.object({
-              oldStart: z.number(),
-              oldLines: z.number(),
-              newStart: z.number(),
-              newLines: z.number(),
-              lines: z.array(z.string()),
-            }),
-          ),
-          index: z.string().optional(),
-        })
-        .optional(),
-      encoding: z.literal("base64").optional(),
-      mimeType: z.string().optional(),
-    })
-    .meta({
-      ref: "FileContent",
-    })
-  export type Content = z.infer<typeof Content>
-
-  const binaryExtensions = new Set([
+const binaryExtensions = new Set([
  "exe",
  "dll",
  "pdb",
@@ -173,9 +118,9 @@ export namespace File {
  "bash",
  "zsh",
  "fish",
-  ])
+])

-  const imageExtensions = new Set([
+const imageExtensions = new Set([
  "png",
  "jpg",
  "jpeg",
@@ -201,9 +146,9 @@ export namespace File {
  "raf",
  "pef",
  "x3f",
-  ])
+])

-  const textExtensions = new Set([
+const textExtensions = new Set([
  "ts",
  "tsx",
  "mts",
@@ -245,9 +190,9 @@ export namespace File {
  "cfg",
  "conf",
  "env",
-  ])
+])

-  const textNames = new Set([
+const textNames = new Set([
  "dockerfile",
  "makefile",
  ".gitignore",
@@ -257,24 +202,24 @@ export namespace File {
  ".nvmrc",
  ".prettierrc",
  ".eslintrc",
-  ])
+])

-  function isImageByExtension(filepath: string): boolean {
+function isImageByExtension(filepath: string): boolean {
  const ext = path.extname(filepath).toLowerCase().slice(1)
  return imageExtensions.has(ext)
-  }
+}

-  function isTextByExtension(filepath: string): boolean {
+function isTextByExtension(filepath: string): boolean {
  const ext = path.extname(filepath).toLowerCase().slice(1)
  return textExtensions.has(ext)
-  }
+}

-  function isTextByName(filepath: string): boolean {
+function isTextByName(filepath: string): boolean {
  const name = path.basename(filepath).toLowerCase()
  return textNames.has(name)
-  }
+}

-  function getImageMimeType(filepath: string): string {
+function getImageMimeType(filepath: string): string {
  const ext = path.extname(filepath).toLowerCase().slice(1)
  const mimeTypes: Record<string, string> = {
    png: "image/png",
@@ -295,18 +240,18 @@ export namespace File {
    heif: "image/heif",
  }
  return mimeTypes[ext] || "image/" + ext
-  }
+}

-  function isBinaryByExtension(filepath: string): boolean {
+function isBinaryByExtension(filepath: string): boolean {
  const ext = path.extname(filepath).toLowerCase().slice(1)
  return binaryExtensions.has(ext)
-  }
+}

-  function isImage(mimeType: string): boolean {
+function isImage(mimeType: string): boolean {
  return mimeType.startsWith("image/")
-  }
+}

-  async function shouldEncode(mimeType: string): Promise<boolean> {
+function shouldEncode(mimeType: string): boolean {
  const type = mimeType.toLowerCase()
  log.info("shouldEncode", { type })
  if (!type) return false
@@ -321,7 +266,65 @@ export namespace File {
  if (tops.includes(top)) return true

  return false
-  }
+}
+
+export namespace File {
+  export const Info = z
+    .object({
+      path: z.string(),
+      added: z.number().int(),
+      removed: z.number().int(),
+      status: z.enum(["added", "deleted", "modified"]),
+    })
+    .meta({
+      ref: "File",
+    })
+
+  export type Info = z.infer<typeof Info>
+
+  export const Node = z
+    .object({
+      name: z.string(),
+      path: z.string(),
+      absolute: z.string(),
+      type: z.enum(["file", "directory"]),
+      ignored: z.boolean(),
+    })
+    .meta({
+      ref: "FileNode",
+    })
+  export type Node = z.infer<typeof Node>
+
+  export const Content = z
+    .object({
+      type: z.enum(["text", "binary"]),
+      content: z.string(),
+      diff: z.string().optional(),
+      patch: z
+        .object({
+          oldFileName: z.string(),
+          newFileName: z.string(),
+          oldHeader: z.string().optional(),
+          newHeader: z.string().optional(),
+          hunks: z.array(
+            z.object({
+              oldStart: z.number(),
+              oldLines: z.number(),
+              newStart: z.number(),
+              newLines: z.number(),
+              lines: z.array(z.string()),
+            }),
+          ),
+          index: z.string().optional(),
+        })
+        .optional(),
+      encoding: z.literal("base64").optional(),
+      mimeType: z.string().optional(),
+    })
+    .meta({
+      ref: "FileContent",
+    })
+  export type Content = z.infer<typeof Content>

  export const Event = {
    Edited: BusEvent.define(
@@ -332,37 +335,83 @@ export namespace File {
    ),
  }

-  const state = Instance.state(async () => {
+  export function init() {
+    return runPromiseInstance(FileService.use((s) => s.init()))
+  }
+
+  export async function status() {
+    return runPromiseInstance(FileService.use((s) => s.status()))
+  }
+
+  export async function read(file: string): Promise<Content> {
+    return runPromiseInstance(FileService.use((s) => s.read(file)))
+  }
+
+  export async function list(dir?: string) {
+    return runPromiseInstance(FileService.use((s) => s.list(dir)))
+  }
+
+  export async function search(input: { query: string; limit?: number; dirs?: boolean; type?: "file" | "directory" }) {
+    return runPromiseInstance(FileService.use((s) => s.search(input)))
+  }
+}
+
+export namespace FileService {
+  export interface Service {
+    readonly init: () => Effect.Effect<void>
+    readonly status: () => Effect.Effect<File.Info[]>
+    readonly read: (file: string) => Effect.Effect<File.Content>
+    readonly list: (dir?: string) => Effect.Effect<File.Node[]>
+    readonly search: (input: {
+      query: string
+      limit?: number
+      dirs?: boolean
+      type?: "file" | "directory"
+    }) => Effect.Effect<string[]>
+  }
+}
+
+export class FileService extends ServiceMap.Service<FileService, FileService.Service>()("@opencode/File") {
+  static readonly layer = Layer.effect(
+    FileService,
+    Effect.gen(function* () {
+      const instance = yield* InstanceContext
+
+      // File cache state
      type Entry = { files: string[]; dirs: string[] }
      let cache: Entry = { files: [], dirs: [] }
-    let fetching = false
+      let task: Promise<void> | undefined

-    const isGlobalHome = Instance.directory === Global.Path.home && Instance.project.id === "global"
+      const isGlobalHome = instance.directory === Global.Path.home && instance.project.id === "global"

-    const fn = async (result: Entry) => {
+      function kick() {
+        if (task) return task
+        task = (async () => {
          // Disable scanning if in root of file system
-      if (Instance.directory === path.parse(Instance.directory).root) return
-      fetching = true
-
+          if (instance.directory === path.parse(instance.directory).root) return
+          const next: Entry = { files: [], dirs: [] }
+          try {
            if (isGlobalHome) {
              const dirs = new Set<string>()
-        const ignore = Protected.names()
+              const protectedNames = Protected.names()

              const ignoreNested = new Set(["node_modules", "dist", "build", "target", "vendor"])
-        const shouldIgnore = (name: string) => name.startsWith(".") || ignore.has(name)
+              const shouldIgnoreName = (name: string) => name.startsWith(".") || protectedNames.has(name)
              const shouldIgnoreNested = (name: string) => name.startsWith(".") || ignoreNested.has(name)

              const top = await fs.promises
-          .readdir(Instance.directory, { withFileTypes: true })
+                .readdir(instance.directory, { withFileTypes: true })
                .catch(() => [] as fs.Dirent[])

              for (const entry of top) {
                if (!entry.isDirectory()) continue
-          if (shouldIgnore(entry.name)) continue
+                if (shouldIgnoreName(entry.name)) continue
                dirs.add(entry.name + "/")

-          const base = path.join(Instance.directory, entry.name)
-          const children = await fs.promises.readdir(base, { withFileTypes: true }).catch(() => [] as fs.Dirent[])
+                const base = path.join(instance.directory, entry.name)
+                const children = await fs.promises
+                  .readdir(base, { withFileTypes: true })
+                  .catch(() => [] as fs.Dirent[])
                for (const child of children) {
                  if (!child.isDirectory()) continue
                  if (shouldIgnoreNested(child.name)) continue
@@ -370,15 +419,11 @@ export namespace File {
                }
              }

-        result.dirs = Array.from(dirs).toSorted()
-        cache = result
-        fetching = false
-        return
-      }
-
+              next.dirs = Array.from(dirs).toSorted()
+            } else {
              const set = new Set<string>()
-      for await (const file of Ripgrep.files({ cwd: Instance.directory })) {
-        result.files.push(file)
+              for await (const file of Ripgrep.files({ cwd: instance.directory })) {
+                next.files.push(file)
                let current = file
                while (true) {
                  const dir = path.dirname(current)
@@ -387,42 +432,38 @@ export namespace File {
                  current = dir
                  if (set.has(dir)) continue
                  set.add(dir)
-          result.dirs.push(dir + "/")
+                  next.dirs.push(dir + "/")
                }
              }
-      cache = result
-      fetching = false
            }
-    fn(cache)
+            cache = next
+          } finally {
+            task = undefined
+          }
+        })()
+        return task
+      }

-    return {
-      async files() {
-        if (!fetching) {
-          fn({
-            files: [],
-            dirs: [],
-          })
-        }
+      const getFiles = async () => {
+        void kick()
        return cache
-      },
      }
+
+      const init = Effect.fn("FileService.init")(function* () {
+        void kick()
      })

-  export function init() {
-    state()
-  }
-
-  export async function status() {
-    const project = Instance.project
-    if (project.vcs !== "git") return []
+      const status = Effect.fn("FileService.status")(function* () {
+        if (instance.project.vcs !== "git") return []

+        return yield* Effect.promise(async () => {
          const diffOutput = (
            await git(["-c", "core.fsmonitor=false", "-c", "core.quotepath=false", "diff", "--numstat", "HEAD"], {
-        cwd: Instance.directory,
+              cwd: instance.directory,
            })
          ).text()

-    const changedFiles: Info[] = []
+          const changedFiles: File.Info[] = []

          if (diffOutput.trim()) {
            const lines = diffOutput.trim().split("\n")
@@ -439,9 +480,17 @@ export namespace File {

          const untrackedOutput = (
            await git(
-        ["-c", "core.fsmonitor=false", "-c", "core.quotepath=false", "ls-files", "--others", "--exclude-standard"],
+              [
+                "-c",
+                "core.fsmonitor=false",
+                "-c",
+                "core.quotepath=false",
+                "ls-files",
+                "--others",
+                "--exclude-standard",
+              ],
              {
-          cwd: Instance.directory,
+                cwd: instance.directory,
              },
            )
          ).text()
@@ -450,7 +499,7 @@ export namespace File {
            const untrackedFiles = untrackedOutput.trim().split("\n")
            for (const filepath of untrackedFiles) {
              try {
-          const content = await Filesystem.readText(path.join(Instance.directory, filepath))
+                const content = await Filesystem.readText(path.join(instance.directory, filepath))
                const lines = content.split("\n").length
                changedFiles.push({
                  path: filepath,
@@ -467,9 +516,18 @@ export namespace File {
          // Get deleted files
          const deletedOutput = (
            await git(
-        ["-c", "core.fsmonitor=false", "-c", "core.quotepath=false", "diff", "--name-only", "--diff-filter=D", "HEAD"],
+              [
+                "-c",
+                "core.fsmonitor=false",
+                "-c",
+                "core.quotepath=false",
+                "diff",
+                "--name-only",
+                "--diff-filter=D",
+                "HEAD",
+              ],
              {
-          cwd: Instance.directory,
+                cwd: instance.directory,
              },
            )
          ).text()
@@ -487,21 +545,20 @@ export namespace File {
          }

          return changedFiles.map((x) => {
-      const full = path.isAbsolute(x.path) ? x.path : path.join(Instance.directory, x.path)
+            const full = path.isAbsolute(x.path) ? x.path : path.join(instance.directory, x.path)
            return {
              ...x,
-        path: path.relative(Instance.directory, full),
+              path: path.relative(instance.directory, full),
            }
          })
-  }
+        })
+      })

-  export async function read(file: string): Promise<Content> {
+      const read = Effect.fn("FileService.read")(function* (file: string) {
+        return yield* Effect.promise(async (): Promise<File.Content> => {
          using _ = log.time("read", { file })
-    const project = Instance.project
-    const full = path.join(Instance.directory, file)
+          const full = path.join(instance.directory, file)

-    // TODO: Filesystem.contains is lexical only - symlinks inside the project can escape.
-    // TODO: On Windows, cross-drive paths bypass this check. Consider realpath canonicalization.
          if (!Instance.containsPath(full)) {
            throw new Error(`Access denied: path escapes project directory`)
          }
@@ -528,7 +585,7 @@ export namespace File {
          }

          const mimeType = Filesystem.mimeType(full)
-    const encode = text ? false : await shouldEncode(mimeType)
+          const encode = text ? false : shouldEncode(mimeType)

          if (encode && !isImage(mimeType)) {
            return { type: "binary", content: "", mimeType }
@@ -542,15 +599,17 @@ export namespace File {

          const content = (await Filesystem.readText(full).catch(() => "")).trim()

-    if (project.vcs === "git") {
-      let diff = (await git(["-c", "core.fsmonitor=false", "diff", "--", file], { cwd: Instance.directory })).text()
+          if (instance.project.vcs === "git") {
+            let diff = (
+              await git(["-c", "core.fsmonitor=false", "diff", "--", file], { cwd: instance.directory })
+            ).text()
            if (!diff.trim()) {
              diff = (
-          await git(["-c", "core.fsmonitor=false", "diff", "--staged", "--", file], { cwd: Instance.directory })
+                await git(["-c", "core.fsmonitor=false", "diff", "--staged", "--", file], { cwd: instance.directory })
              ).text()
            }
            if (diff.trim()) {
-        const original = (await git(["show", `HEAD:${file}`], { cwd: Instance.directory })).text()
+              const original = (await git(["show", `HEAD:${file}`], { cwd: instance.directory })).text()
              const patch = structuredPatch(file, file, original, content, "old", "new", {
                context: Infinity,
                ignoreWhitespace: true,
@@ -560,33 +619,32 @@ export namespace File {
            }
          }
          return { type: "text", content }
-  }
+        })
+      })

-  export async function list(dir?: string) {
+      const list = Effect.fn("FileService.list")(function* (dir?: string) {
+        return yield* Effect.promise(async () => {
          const exclude = [".git", ".DS_Store"]
-    const project = Instance.project
          let ignored = (_: string) => false
-    if (project.vcs === "git") {
+          if (instance.project.vcs === "git") {
            const ig = ignore()
-      const gitignorePath = path.join(Instance.worktree, ".gitignore")
+            const gitignorePath = path.join(instance.project.worktree, ".gitignore")
            if (await Filesystem.exists(gitignorePath)) {
              ig.add(await Filesystem.readText(gitignorePath))
            }
-      const ignorePath = path.join(Instance.worktree, ".ignore")
+            const ignorePath = path.join(instance.project.worktree, ".ignore")
            if (await Filesystem.exists(ignorePath)) {
              ig.add(await Filesystem.readText(ignorePath))
            }
            ignored = ig.ignores.bind(ig)
          }
-    const resolved = dir ? path.join(Instance.directory, dir) : Instance.directory
+          const resolved = dir ? path.join(instance.directory, dir) : instance.directory

-    // TODO: Filesystem.contains is lexical only - symlinks inside the project can escape.
-    // TODO: On Windows, cross-drive paths bypass this check. Consider realpath canonicalization.
          if (!Instance.containsPath(resolved)) {
            throw new Error(`Access denied: path escapes project directory`)
          }

-    const nodes: Node[] = []
+          const nodes: File.Node[] = []
          for (const entry of await fs.promises
            .readdir(resolved, {
              withFileTypes: true,
@@ -594,7 +652,7 @@ export namespace File {
            .catch(() => [])) {
            if (exclude.includes(entry.name)) continue
            const fullPath = path.join(resolved, entry.name)
-      const relativePath = path.relative(Instance.directory, fullPath)
+            const relativePath = path.relative(instance.directory, fullPath)
            const type = entry.isDirectory() ? "directory" : "file"
            nodes.push({
              name: entry.name,
@@ -610,15 +668,22 @@ export namespace File {
            }
            return a.name.localeCompare(b.name)
          })
-  }
+        })
+      })

-  export async function search(input: { query: string; limit?: number; dirs?: boolean; type?: "file" | "directory" }) {
+      const search = Effect.fn("FileService.search")(function* (input: {
+        query: string
+        limit?: number
+        dirs?: boolean
+        type?: "file" | "directory"
+      }) {
+        return yield* Effect.promise(async () => {
          const query = input.query.trim()
          const limit = input.limit ?? 100
          const kind = input.type ?? (input.dirs === false ? "file" : "all")
          log.info("search", { query, kind })

-    const result = await state().then((x) => x.files())
+          const result = await getFiles()

          const hidden = (item: string) => {
            const normalized = item.replaceAll("\\", "/").replace(/\/+$/, "")
@@ -650,5 +715,12 @@ export namespace File {

          log.info("search", { query, kind, results: output.length })
          return output
-  }
+        })
+      })
+
+      log.info("init")
+
+      return FileService.of({ init, status, read, list, search })
+    }),
+  )
 }
@@ -1,4 +1,5 @@
 import { describe, test, expect } from "bun:test"
+import { $ } from "bun"
 import path from "path"
 import fs from "fs/promises"
 import { File } from "../../src/file"
@@ -391,4 +392,469 @@ describe("file/index Filesystem patterns", () => {
      })
    })
  })
+
+  describe("File.status()", () => {
+    test("detects modified file", async () => {
+      await using tmp = await tmpdir({ git: true })
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "original\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "add file"`.cwd(tmp.path).quiet()
+      await fs.writeFile(filepath, "modified\nextra line\n", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          const entry = result.find((f) => f.path === "file.txt")
+          expect(entry).toBeDefined()
+          expect(entry!.status).toBe("modified")
+          expect(entry!.added).toBeGreaterThan(0)
+          expect(entry!.removed).toBeGreaterThan(0)
+        },
+      })
+    })
+
+    test("detects untracked file as added", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.writeFile(path.join(tmp.path, "new.txt"), "line1\nline2\nline3\n", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          const entry = result.find((f) => f.path === "new.txt")
+          expect(entry).toBeDefined()
+          expect(entry!.status).toBe("added")
+          expect(entry!.added).toBe(4) // 3 lines + trailing newline splits to 4
+          expect(entry!.removed).toBe(0)
+        },
+      })
+    })
+
+    test("detects deleted file", async () => {
+      await using tmp = await tmpdir({ git: true })
+      const filepath = path.join(tmp.path, "gone.txt")
+      await fs.writeFile(filepath, "content\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "add file"`.cwd(tmp.path).quiet()
+      await fs.rm(filepath)
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          // Deleted files appear in both numstat (as "modified") and diff-filter=D (as "deleted")
+          const entries = result.filter((f) => f.path === "gone.txt")
+          expect(entries.some((e) => e.status === "deleted")).toBe(true)
+        },
+      })
+    })
+
+    test("detects mixed changes", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.writeFile(path.join(tmp.path, "keep.txt"), "keep\n", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "remove.txt"), "remove\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "initial"`.cwd(tmp.path).quiet()
+
+      // Modify one, delete one, add one
+      await fs.writeFile(path.join(tmp.path, "keep.txt"), "changed\n", "utf-8")
+      await fs.rm(path.join(tmp.path, "remove.txt"))
+      await fs.writeFile(path.join(tmp.path, "brand-new.txt"), "hello\n", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          expect(result.some((f) => f.path === "keep.txt" && f.status === "modified")).toBe(true)
+          expect(result.some((f) => f.path === "remove.txt" && f.status === "deleted")).toBe(true)
+          expect(result.some((f) => f.path === "brand-new.txt" && f.status === "added")).toBe(true)
+        },
+      })
+    })
+
+    test("returns empty for non-git project", async () => {
+      await using tmp = await tmpdir()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          expect(result).toEqual([])
+        },
+      })
+    })
+
+    test("returns empty for clean repo", async () => {
+      await using tmp = await tmpdir({ git: true })
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          expect(result).toEqual([])
+        },
+      })
+    })
+
+    test("parses binary numstat as 0", async () => {
+      await using tmp = await tmpdir({ git: true })
+      const filepath = path.join(tmp.path, "data.bin")
+      // Write content with null bytes so git treats it as binary
+      const binaryData = Buffer.alloc(256)
+      for (let i = 0; i < 256; i++) binaryData[i] = i
+      await fs.writeFile(filepath, binaryData)
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "add binary"`.cwd(tmp.path).quiet()
+      // Modify the binary
+      const modified = Buffer.alloc(512)
+      for (let i = 0; i < 512; i++) modified[i] = i % 256
+      await fs.writeFile(filepath, modified)
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.status()
+          const entry = result.find((f) => f.path === "data.bin")
+          expect(entry).toBeDefined()
+          expect(entry!.status).toBe("modified")
+          expect(entry!.added).toBe(0)
+          expect(entry!.removed).toBe(0)
+        },
+      })
+    })
+  })
+
+  describe("File.list()", () => {
+    test("returns files and directories with correct shape", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.mkdir(path.join(tmp.path, "subdir"))
+      await fs.writeFile(path.join(tmp.path, "file.txt"), "content", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "subdir", "nested.txt"), "nested", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const nodes = await File.list()
+          expect(nodes.length).toBeGreaterThanOrEqual(2)
+          for (const node of nodes) {
+            expect(node).toHaveProperty("name")
+            expect(node).toHaveProperty("path")
+            expect(node).toHaveProperty("absolute")
+            expect(node).toHaveProperty("type")
+            expect(node).toHaveProperty("ignored")
+            expect(["file", "directory"]).toContain(node.type)
+          }
+        },
+      })
+    })
+
+    test("sorts directories before files, alphabetical within each", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.mkdir(path.join(tmp.path, "beta"))
+      await fs.mkdir(path.join(tmp.path, "alpha"))
+      await fs.writeFile(path.join(tmp.path, "zz.txt"), "", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "aa.txt"), "", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const nodes = await File.list()
+          const dirs = nodes.filter((n) => n.type === "directory")
+          const files = nodes.filter((n) => n.type === "file")
+          // Dirs come first
+          const firstFile = nodes.findIndex((n) => n.type === "file")
+          const lastDir = nodes.findLastIndex((n) => n.type === "directory")
+          if (lastDir >= 0 && firstFile >= 0) {
+            expect(lastDir).toBeLessThan(firstFile)
+          }
+          // Alphabetical within dirs
+          expect(dirs.map((d) => d.name)).toEqual(dirs.map((d) => d.name).toSorted())
+          // Alphabetical within files
+          expect(files.map((f) => f.name)).toEqual(files.map((f) => f.name).toSorted())
+        },
+      })
+    })
+
+    test("excludes .git and .DS_Store", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.writeFile(path.join(tmp.path, ".DS_Store"), "", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "visible.txt"), "", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const nodes = await File.list()
+          const names = nodes.map((n) => n.name)
+          expect(names).not.toContain(".git")
+          expect(names).not.toContain(".DS_Store")
+          expect(names).toContain("visible.txt")
+        },
+      })
+    })
+
+    test("marks gitignored files as ignored", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.writeFile(path.join(tmp.path, ".gitignore"), "*.log\nbuild/\n", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "app.log"), "log data", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "main.ts"), "code", "utf-8")
+      await fs.mkdir(path.join(tmp.path, "build"))
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const nodes = await File.list()
+          const logNode = nodes.find((n) => n.name === "app.log")
+          const tsNode = nodes.find((n) => n.name === "main.ts")
+          const buildNode = nodes.find((n) => n.name === "build")
+          expect(logNode?.ignored).toBe(true)
+          expect(tsNode?.ignored).toBe(false)
+          expect(buildNode?.ignored).toBe(true)
+        },
+      })
+    })
+
+    test("lists subdirectory contents", async () => {
+      await using tmp = await tmpdir({ git: true })
+      await fs.mkdir(path.join(tmp.path, "sub"))
+      await fs.writeFile(path.join(tmp.path, "sub", "a.txt"), "", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "sub", "b.txt"), "", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const nodes = await File.list("sub")
+          expect(nodes.length).toBe(2)
+          expect(nodes.map((n) => n.name).sort()).toEqual(["a.txt", "b.txt"])
+          // Paths should be relative to project root (normalize for Windows)
+          expect(nodes[0].path.replaceAll("\\", "/").startsWith("sub/")).toBe(true)
+        },
+      })
+    })
+
+    test("throws for paths outside project directory", async () => {
+      await using tmp = await tmpdir({ git: true })
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          await expect(File.list("../outside")).rejects.toThrow("Access denied")
+        },
+      })
+    })
+
+    test("works without git", async () => {
+      await using tmp = await tmpdir()
+      await fs.writeFile(path.join(tmp.path, "file.txt"), "hi", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const nodes = await File.list()
+          expect(nodes.length).toBeGreaterThanOrEqual(1)
+          // Without git, ignored should be false for all
+          for (const node of nodes) {
+            expect(node.ignored).toBe(false)
+          }
+        },
+      })
+    })
+  })
+
+  describe("File.search()", () => {
+    async function setupSearchableRepo() {
+      const tmp = await tmpdir({ git: true })
+      await fs.writeFile(path.join(tmp.path, "index.ts"), "code", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "utils.ts"), "utils", "utf-8")
+      await fs.writeFile(path.join(tmp.path, "readme.md"), "readme", "utf-8")
+      await fs.mkdir(path.join(tmp.path, "src"))
+      await fs.mkdir(path.join(tmp.path, ".hidden"))
+      await fs.writeFile(path.join(tmp.path, "src", "main.ts"), "main", "utf-8")
+      await fs.writeFile(path.join(tmp.path, ".hidden", "secret.ts"), "secret", "utf-8")
+      return tmp
+    }
+
+    test("empty query returns files", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          // Give the background scan time to populate
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: "", type: "file" })
+          expect(result.length).toBeGreaterThan(0)
+        },
+      })
+    })
+
+    test("empty query returns dirs sorted with hidden last", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: "", type: "directory" })
+          expect(result.length).toBeGreaterThan(0)
+          // Find first hidden dir index
+          const firstHidden = result.findIndex((d) => d.split("/").some((p) => p.startsWith(".") && p.length > 1))
+          const lastVisible = result.findLastIndex((d) => !d.split("/").some((p) => p.startsWith(".") && p.length > 1))
+          if (firstHidden >= 0 && lastVisible >= 0) {
+            expect(firstHidden).toBeGreaterThan(lastVisible)
+          }
+        },
+      })
+    })
+
+    test("fuzzy matches file names", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: "main", type: "file" })
+          expect(result.some((f) => f.includes("main"))).toBe(true)
+        },
+      })
+    })
+
+    test("type filter returns only files", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: "", type: "file" })
+          // Files don't end with /
+          for (const f of result) {
+            expect(f.endsWith("/")).toBe(false)
+          }
+        },
+      })
+    })
+
+    test("type filter returns only directories", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: "", type: "directory" })
+          // Directories end with /
+          for (const d of result) {
+            expect(d.endsWith("/")).toBe(true)
+          }
+        },
+      })
+    })
+
+    test("respects limit", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: "", type: "file", limit: 2 })
+          expect(result.length).toBeLessThanOrEqual(2)
+        },
+      })
+    })
+
+    test("query starting with dot prefers hidden files", async () => {
+      await using tmp = await setupSearchableRepo()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          File.init()
+          await new Promise((r) => setTimeout(r, 500))
+
+          const result = await File.search({ query: ".hidden", type: "directory" })
+          expect(result.length).toBeGreaterThan(0)
+          expect(result[0]).toContain(".hidden")
+        },
+      })
+    })
+  })
+
+  describe("File.read() - diff/patch", () => {
+    test("returns diff and patch for modified tracked file", async () => {
+      await using tmp = await tmpdir({ git: true })
+      const filepath = path.join(tmp.path, "file.txt")
+      await fs.writeFile(filepath, "original content\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "add file"`.cwd(tmp.path).quiet()
+      await fs.writeFile(filepath, "modified content\n", "utf-8")
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.read("file.txt")
+          expect(result.type).toBe("text")
+          expect(result.content).toBe("modified content")
+          expect(result.diff).toBeDefined()
+          expect(result.diff).toContain("original content")
+          expect(result.diff).toContain("modified content")
+          expect(result.patch).toBeDefined()
+          expect(result.patch!.hunks.length).toBeGreaterThan(0)
+        },
+      })
+    })
+
+    test("returns diff for staged changes", async () => {
+      await using tmp = await tmpdir({ git: true })
+      const filepath = path.join(tmp.path, "staged.txt")
+      await fs.writeFile(filepath, "before\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "add file"`.cwd(tmp.path).quiet()
+      await fs.writeFile(filepath, "after\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.read("staged.txt")
+          expect(result.diff).toBeDefined()
+          expect(result.patch).toBeDefined()
+        },
+      })
+    })
+
+    test("returns no diff for unmodified file", async () => {
+      await using tmp = await tmpdir({ git: true })
+      const filepath = path.join(tmp.path, "clean.txt")
+      await fs.writeFile(filepath, "unchanged\n", "utf-8")
+      await $`git add .`.cwd(tmp.path).quiet()
+      await $`git commit --no-gpg-sign -m "add file"`.cwd(tmp.path).quiet()
+
+      await Instance.provide({
+        directory: tmp.path,
+        fn: async () => {
+          const result = await File.read("clean.txt")
+          expect(result.type).toBe("text")
+          expect(result.content).toBe("unchanged")
+          expect(result.diff).toBeUndefined()
+          expect(result.patch).toBeUndefined()
+        },
+      })
+    })
+  })
 })