Trait FileSystemService

Source

pub trait FileSystemService: Send + Sync {
    // Required methods
    fn read_dir(&self, path: &Path) -> FsResult<Vec<DirEntryInfo>>;
    fn read_file(&self, path: &Path) -> FsResult<Vec<u8>>;
    fn create_file(&self, path: &Path) -> FsResult<()>;
    fn write_file(&self, path: &Path, contents: &[u8]) -> FsResult<()>;
    fn create_dir(&self, path: &Path) -> FsResult<()>;
    fn rename(&self, from: &Path, to: &Path) -> FsResult<()>;
    fn remove_file(&self, path: &Path) -> FsResult<()>;
    fn remove_dir_all(&self, path: &Path) -> FsResult<()>;
    fn canonicalize(&self, path: &Path) -> FsResult<PathBuf>;
}

Expand description

Read and mutate the filesystem. Widgets and the agent reach the OS only through this (CONTRIBUTING.md invariants, ARCHITECTURE.md §7.4) — never std::fs directly.

Every write method is a permission-gate chokepoint for the agent’s future file.create / file.rename tool calls, which is why they live behind one trait.

Required Methods§

Source

fn read_dir(&self, path: &Path) -> FsResult<Vec<DirEntryInfo>>

List one directory level. Does not recurse — the tree is lazy (ADR-0005 §2).

Contract: entries come back sorted, directories first, then by name case-insensitively. Ordering is part of the contract rather than left to the caller so the real and fake implementations are interchangeable in tests.

Source

fn read_file(&self, path: &Path) -> FsResult<Vec<u8>>

Source

fn create_file(&self, path: &Path) -> FsResult<()>

Create an empty file. Errors with FsError::AlreadyExists rather than truncating.

Source

fn write_file(&self, path: &Path, contents: &[u8]) -> FsResult<()>

Replace a file’s contents, creating it if absent.

Distinct from Self::create_file on purpose: creating is a user gesture that must not clobber, whereas writing is a deliberate overwrite. Phase 03’s buffer save lands here too.

Source