Struct Host 

pub struct Host { /* private fields */ }

The injectable side-effect seam (ADR-0008). Construct once per session, share behind an Arc; holds the jail root + policy and the exec/truncation limits.

Implementations

impl Host

pub async fn read_file( &self, cwd: &Path, path: &Path, ) -> Result<FileRead, FsError>

Read a file (jail-resolved), returning its lossy-UTF-8 contents + stat.

Errors

FsError::Path if the path escapes the jail; FsError::Io if the read fails.

pub async fn write_file( &self, cwd: &Path, path: &Path, contents: &str, ) -> Result<FileStat, FsError>

Create-or-overwrite a file (jail-resolved), returning its post-write stat.

Does not auto-create parent directories (a mistyped nested path silently creating dirs is a footgun); a missing parent surfaces as an IO error.

Errors

FsError::Path if the path escapes the jail; FsError::Io if the write fails.

pub async fn stat(&self, cwd: &Path, path: &Path) -> Result<FileStat, FsError>

Stat a file (jail-resolved).

Errors

FsError::Path if the path escapes the jail; FsError::Io if the stat fails.

pub async fn read_dir( &self, cwd: &Path, path: &Path, ) -> Result<Vec<DirEntry>, FsError>

List a directory’s immediate entries (jail-resolved), unsorted.

Errors

FsError::Path if the path escapes the jail; FsError::Io if it is not a readable directory.

impl Host

pub async fn resolve_in_jail( &self, cwd: &Path, candidate: &Path, ) -> Result<PathBuf, PathError>

Resolve candidate (absolute, or relative to cwd) to a concrete absolute path.

Under PathPolicy::Jailed the result is guaranteed to live under the workspace root — .., absolute, and symlink escapes are rejected — while paths whose leaf does not yet exist (create-new-file) are still allowed. Under PathPolicy::Unrestricted the path is only made absolute; nothing is rejected.

Errors

PathError::Escape if a jailed path escapes the root; PathError::Io if an ancestor cannot be canonicalized.

impl Host

pub async fn exec( &self, req: ExecRequest, cancel: &CancellationToken, ) -> Result<ExecOutput, ExecError>

Run req through the shell, capturing output under the host’s limits and honoring cooperative cancel.

A command that fails, times out, or is cancelled is a successful capture with the corresponding fields set — the pack decides how to present it.

Errors

ExecError::Spawn only if the shell process itself cannot be started.

pub async fn run_capture( &self, program: &Path, args: &[String], cwd: &Path, timeout: Option<Duration>, cancel: &CancellationToken, ) -> Result<ExecOutput, ExecError>

Run a resolved program with explicit argv (no shell — safe for untrusted args like a regex or glob), capturing output under the same limits/kill/cancel machinery as Host::exec. Used by rg-backed tools (Task 11).

Errors

ExecError::Spawn if the program cannot be started (e.g. rg not on PATH).

impl Host

pub fn new(config: HostConfig) -> Result<Self, PathError>

Build a host, canonicalizing workspace_root (the jail root must be a real, symlink-resolved absolute path).

Errors

PathError::InvalidRoot if workspace_root does not exist or cannot be canonicalized.

pub fn workspace_root(&self) -> &Path

The canonicalized jail root.

pub fn path_policy(&self) -> PathPolicy

The active path policy.

pub fn limits(&self) -> &ExecLimits

The shell execution limits.

Trait Implementations

impl Clone for Host

fn clone(&self) -> Host

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Host

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.