Struct Fs 

pub struct Fs {
    pub description_read: ToolDescription,
    pub description_write: ToolDescription,
    pub description_edit: ToolDescription,
    pub description_edit_lines: ToolDescription,
    pub description_ast_edit: ToolDescription,
    pub description_rollback: ToolDescription,
    /* private fields */
}

Shared-state wrapper for file-system tool operations.

Use the builder methods after new to configure the project root and scope guards, then call the operation methods directly.

Fields

description_read: ToolDescription

MCP Tool description for read.

description_write: ToolDescription

MCP Tool description for write.

description_edit: ToolDescription

MCP Tool description for edit (content replace).

description_edit_lines: ToolDescription

MCP Tool description for fs_edit_lines (hashline replace).

description_ast_edit: ToolDescription

MCP Tool description for fs_ast_edit (AST structural).

description_rollback: ToolDescription

MCP Tool description for rollback.

Implementations

impl Fs

pub fn new() -> Self

Create a new Fs with no root path set.

All paths are denied until cwd is called.

pub fn with_lsp(self, lsp: Arc<Lsp>) -> Self

Attach the language-server engine. Its presence is the toggle: every mutating operation (write/edit/rollback) then reports passive LSP diagnostics on the touched files, and reads warm the servers up.

pub fn without_lsp(&self) -> FsCall<'_>

Suppress passive LSP feedback for the chained call only — the Fs keeps its default behavior for later calls.

pub fn warnings(&self) -> FsCall<'_>

Include warnings (not just errors) in the chained call’s passive LSP feedback only — the Fs keeps its default behavior for later calls.

pub fn cwd(self, path: impl Into<PathBuf>) -> Self

Set the project root directory (used for path-validation guards).

pub fn allowlist( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set the explicit write-path allowlist.

pub fn blocklist( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set the explicit write-path blocklist.

pub fn read_allowlist( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set the read-only path allowlist (falls back to allowlist when None).

pub fn read_blocklist( self, paths: impl IntoIterator<Item = impl Into<PathBuf>>, ) -> Self

Set the read-only path blocklist (falls back to blocklist when None).

pub async fn read(&self, targets: Vec<Target>) -> Vec<ReadResult>

Read one or more files / symbols.

See [read] for details. With Fs::with_lsp configured, each read warms the file’s language servers up (no diagnostics attached).

pub async fn write( &self, targets: Vec<TargetFile>, ) -> Result<Vec<WriteResult>, String>

Write content to one or more files.

See [write] for details.

Errors

Returns an error if the allowlist/blocklist configuration is invalid.

pub async fn edit(&self, args: Value) -> Result<Vec<EditResult>, String>

Apply content-anchored replacements (the fs_edit wrapper over the content replace engine). Each edit replaces an exact, uniquely-matching old_string with new_string, anchored on the file’s content-hash snapshot tag.

Errors

Returns an error when a tag is missing/unknown, old_string does not match exactly or is ambiguous, or the underlying edit fails.

pub async fn edit_lines(&self, args: Value) -> Result<Vec<EditResult>, String>

Edit lines from the fs_edit_lines wrapper over the hashline replace engine (the legacy targets/edit core entry point).

Accepts the advertised flat {path, file_hash, ops} object or the legacy {targets: [...]} batch form (kept for benchmarks; not advertised by the schema).

Errors

Returns an error when the arguments do not match either accepted shape, or when the engine fails.

pub async fn edit_ast(&self, args: Value) -> Result<Vec<EditResult>, String>

Structural syntax-tree rewrite from the fs_edit_ast wrapper over the AST engine. Accepts the advertised flat {path, ops: [{pat, out}]} object or the legacy {ast: {...}} / {paths: [...]} batch forms (kept for codemods/benchmarks; not advertised by the schema).

Errors

Returns an error when the arguments do not match either accepted shape, or when the engine fails.

pub async fn replace_edits( &self, edits: Vec<ReplaceEdit>, ) -> Result<Vec<EditResult>, String>

Apply content-anchored replacements (the typed form of the edits argument of the legacy batch API). Each edit replaces an exact, uniquely-matching old_string with new_string, anchored on the file’s content-hash snapshot tag.

Errors

Returns an error when a tag is missing/unknown, old_string does not match exactly or is ambiguous, or the underlying edit fails.

pub async fn rollback( &self, path: &str, hash: &str, ) -> Result<RollbackResult, String>

Roll back a file to a previously recorded session version.

See [rollback] for details.

Errors

Returns an error if write permission is denied or the path has no rollback history.

pub const fn root(&self) -> &PathBuf

Get the project root path.

pub fn allowlist_ref(&self) -> Option<&[PathBuf]>

Get the write allowlist (read-only reference).

pub fn blocklist_ref(&self) -> Option<&[PathBuf]>

Get the write blocklist (read-only reference).

pub fn add_allowlist_path(&mut self, path: PathBuf)

Add a path to the write allowlist.

If the allowlist is None, it is created. Duplicate paths are ignored.

pub fn remove_allowlist_path(&mut self, path: &Path)

Remove a path from the write allowlist (for AllowOnce cleanup).

If the path is not in the allowlist, this is a no-op.

Trait Implementations

impl Default for Fs

fn default() -> Self

Returns the “default value” for a type.