Use this when

• Editing file I/O or scans in packages/opencode

• Handling directory operations or external tools

Bun file APIs (from Bun docs)

• Bun.file(path) is lazy; call text , json , stream , arrayBuffer , bytes , exists to read.

• Metadata: file.size , file.type , file.name .

• Bun.write(dest, input) writes strings, buffers, Blobs, Responses, or files.

• Bun.file(...).delete() deletes a file.

• file.writer() returns a FileSink for incremental writes.

• Bun.Glob

• Array.fromAsync(glob.scan({ cwd, absolute, onlyFiles, dot })) for scans.

• Use Bun.which to find a binary, then Bun.spawn to run it.

• Bun.readableStreamToText/Bytes/JSON for stream output.

When to use node:fs

• Use node:fs/promises for directories (mkdir , readdir , recursive operations).

Repo patterns

• Prefer Bun APIs over Node fs for file access.

• Check Bun.file(...).exists() before reading.

• For binary/large files use arrayBuffer() and MIME checks via file.type .

• Use Bun.Glob

• Array.fromAsync for scans.

• Decode tool stderr with Bun.readableStreamToText .

• For large writes, use Bun.write(Bun.file(path), text) .

NOTE: Bun.file(...).exists() will return false if the value is a directory. Use Filesystem.exists(...) instead if path can be file or directory

Quick checklist

• Use Bun APIs first.

• Use path.join /path.resolve for paths.

• Prefer promise .catch(...) over try/catch when possible.