Primitives API Reference

Every public function, struct, and enum across the 6 tool primitive modules.

use cersei_tools::tool_primitives::{diff, fs, process, http, search, git};

diff

Pure text diffing functions. No I/O, no async. Built on the similar crate.

unified_diff

pub fn unified_diff(old: &str, new: &str, context_lines: usize) -> String

Produces a standard unified diff with @@ hunk headers. context_lines controls how many unchanged lines surround each hunk.

line_diff

pub fn line_diff(old: &str, new: &str) -> Vec<DiffLine>

Returns a structured per-line diff with old/new line numbers and change tags.

apply_patch

pub fn apply_patch(original: &str, patch: &str) -> Result<String, PatchError>

Applies a unified diff patch to original. Returns the patched text or an error if the patch doesn't apply cleanly.

fs

Async file operations. All functions use tokio::fs.

read_file

pub async fn read_file(path: &Path, offset: usize, limit: usize) -> Result<FileContent, io::Error>

Read a file with optional line offset and limit. Returns content with 1-based line numbers.

write_file

pub async fn write_file(path: &Path, content: &str) -> Result<(), io::Error>

Write content to a file. Creates parent directories automatically.

edit_file

pub async fn edit_file(
    path: &Path, old_text: &str, new_text: &str, replace_all: bool
) -> Result<EditResult, EditError>

String replacement in a file. Returns the number of replacements made.

Errors:

• EditError::NotFound — old_text not present in the file
• EditError::AmbiguousMatch { count } — old_text appears multiple times and replace_all is false
• EditError::Io(e) — file I/O failure

diff_file

pub async fn diff_file(path: &Path, new_content: &str, context_lines: usize) -> Result<String, io::Error>

Produce a unified diff between the file's current content and proposed new content.

patch_file

pub async fn patch_file(path: &Path, patch: &str) -> Result<(), PatchFileError>

Apply a unified diff patch to a file, writing the result back.

file_exists / file_size / file_metadata

pub async fn file_exists(path: &Path) -> bool
pub async fn file_size(path: &Path) -> Result<u64, io::Error>
pub async fn file_metadata(path: &Path) -> Result<FileMetadata, io::Error>

process

Async command execution. Stateless — no persistent cwd or env.

exec

pub async fn exec(command: &str, opts: ExecOptions) -> Result<ExecOutput, io::Error>

Execute a command through a shell. Returns when the command completes or times out.

ExecOptions

exec_streaming

pub fn exec_streaming(
    command: &str, opts: ExecOptions
) -> Result<(Receiver<OutputLine>, JoinHandle<ExecOutput>), io::Error>

Execute a command and stream output lines through a channel. The JoinHandle resolves to ExecOutput when the command finishes. OutputLine is either Stdout(String) or Stderr(String).

http

Async HTTP client built on reqwest.

get

pub async fn get(url: &str, opts: HttpOptions) -> Result<HttpResponse, HttpError>

post

pub async fn post(url: &str, body: &str, opts: HttpOptions) -> Result<HttpResponse, HttpError>

fetch_html

pub async fn fetch_html(url: &str, max_chars: usize, opts: HttpOptions) -> Result<String, HttpError>

Fetch a URL and convert HTML to readable plain text using html2text. Non-HTML content returned as-is. Truncated to max_chars.

HttpResponse

HttpOptions

HttpError

• RequestFailed(String) — network or protocol error
• Timeout — request timed out
• ClientBuild(String) — failed to construct the HTTP client

search

Structured file search — grep and glob.

grep

pub async fn grep(
    pattern: &str, path: &Path, opts: GrepOptions
) -> Result<Vec<SearchMatch>, SearchError>

Search file contents using a regex pattern. Uses ripgrep if available, falls back to system grep. Returns structured matches.

GrepOptions

glob

pub async fn glob(pattern: &str, base_dir: &Path) -> Result<Vec<PathBuf>, SearchError>

Find files matching a glob pattern. Returns sorted paths.

git

Async git CLI operations. All functions use tokio::process::Command.

Repository detection

pub async fn is_repo(path: &Path) -> bool
pub async fn repo_root(path: &Path) -> Option<PathBuf>
pub async fn current_branch(path: &Path) -> Option<String>

status

pub async fn status(path: &Path) -> Result<GitStatus, GitError>

diff

pub async fn diff(path: &Path, staged: bool) -> Result<String, GitError>

Get unified diff output. staged = true shows staged changes (--cached), false shows unstaged.

log

pub async fn log(path: &Path, n: usize) -> Result<Vec<GitLogEntry>, GitError>

diff_file_content / list_modified_files

pub async fn diff_file_content(path: &Path, file: &str) -> Result<String, GitError>
pub async fn list_modified_files(path: &Path) -> Result<Vec<String>, GitError>

GitError

• NotARepo — path is not inside a git repository
• CommandFailed(String) — git command returned an error
• IoError(io::Error) — process spawn failure