Crate rig_tools 

Coding tools for Rig agents: Read, Write, Edit, Search, List, Shell, Delete and Move.

• Each says in its description when to pick it, and what it may touch (footprint): read, search and list read the path they name, the other file tools write theirs, and shell may change anything, so a host runs calls on different files side by side.
• Each publishes what it did beside its text: files read (FilesRead), SearchHits, FilesListed, files changed with their diffs (FilesChanged), how a command ended (ExitStatus).
• Each acts on a Workspace: this machine (Local, the default) or another. The file tools resolve paths from an optional base directory they can be confined to.
• shell reports its output as it comes to a Live. Arguments are plain data with public fields.

Also the pieces they are made of, for tools of your own:

• edit::apply: what edit makes of a file’s text, without the file, and ReadArgs::show: what read shows of it;
• workspace: the disk and the commands the tools act on, overlay: one that keeps the tools’ writes from the disk, to preview them, and remote: another machine reached through a transport such as ssh, and paths written HOST:PATH that reach it;
• attach: the files a message names as @path, read to go with it;
• checkpoint: the files under a root at one moment, what changed by a later one, and a handler that reports what any call changed;
• clipboard: the system clipboard’s text and images;
• fs: an atomic file write and capped text reads on this machine;
• show_lines: some lines of a text, the way read shows a file;
• Spill: where output a tool cut is kept whole, and OutputLimit: how much of a long output is kept;
• process: child processes in a process group of their own, the Launcher that says how tools start them, and the Process it spawns: input in, output line by line, stopped gently or killed with its group;
• blocking: blocking work on a thread of its own, so no async executor thread blocks.

Native only: the tools use the file system and processes.

Re-exports

pub use edit::Edit;

pub use edit::EditArgs;

pub use edit::Replacement;

Modules

attach

Files a message names as @path, read to go with it: an image as an image, any other file as its text, capped the way read shows it, so the model needs no read call for it.

checkpoint

Checkpoints: the files under a root at one moment (snapshot), to learn what changed by a later one (Snapshot::changes_since), and Checkpointed, a handler that reports what any call changed, such as a shell call’s, as the file tools report their own.

clipboard

The system clipboard, read and written by the programs that own it on this machine: wl-paste/wl-copy on Wayland, xclip on X11, and pbpaste/pbcopy (pngpaste for images) on macOS. Each is started as a Launcher says, such as one that keeps the session’s secrets from it. Blocking: call these off a thread that must not wait.

edit

The edit tool: several replacements in one file per call, applied in order, each to the text the ones before it left, and all of them or none. A byte-order mark and CRLF line endings are kept. Text that does not match exactly may still match line by line once trailing whitespace and typographic quotes, dashes and spaces are evened out, but only where exactly one place in the file matches. The result names the lines that now hold the changed text and shows them, with a few lines around each, as the file now holds them; a failure says what to send instead, with the closest text to an old_text that was not found.

fs

File helpers the tools share: an atomic write, capped text reads, JSON files, and the FileChange a tool that writes publishes. The reads and the path rules here are this machine’s (Local); a tool reads through its Workspace.

overlay

Overlay: a workspace that keeps its writes to itself, to learn what a tool would leave on disk without changing it.

process

Child processes started in a session of their own, such as shell commands, so they never read the terminal and are killed as a group, and the Launcher that says how every tool starts them. A Process it spawns takes its input, hands its output over line by line, and is stopped gently or killed with its whole group.

remote

Workspaces on other machines: Remote, one machine reached through a transport, and Hosts, which sends each path written HOST:PATH to that host’s Remote and every other path to the workspace it wraps.

workspace

The Workspace the tools act on: the disk they read and write and where their commands run. Local is this machine; another, such as a Remote reached over SSH, is a type of its own that every tool and the shell then go through.

Structs

Delete

Deletes a file; a directory is refused. Publishes the file it deleted (FilesChanged): its resolved path, and how many lines it had.

DeleteArgs

Arguments of Delete.

FilesListed

What a List call listed, as it published it beside the text.

Found

What a search found.

Hit

One line a search matched.

List

Lists the files under a directory, as far down as asked, honouring .gitignore (Listing::Visible, or Listing::Hidden when asked or when the glob names a hidden path): one path per line below the listed directory, and each directory deeper than the listing goes once, as dir/. Publishes what it listed (FilesListed) and, when the list was cut, OutputCut.

ListArgs

Arguments of List.

Live

Where a running tool reports output as it comes, such as Shell’s lines. Cloning shares the sink.

Move

Moves or renames a file, creating the new path’s directory; a directory is refused, and so is an existing file at the new path unless the call says to overwrite it. Publishes the files it changed (FilesChanged), by their resolved paths: the old one deleted, and the new one created (or, overwritten, changed) with its hunks.

MoveArgs

Arguments of Move.

OutputLimit

How much of a long output a tool keeps: at most lines lines and bytes bytes, of whole lines. tail keeps the last ones; Shell keeps a quarter for the first lines, a quarter for the errors and failures from between, and the rest for the last lines.

Read

Reads a text file’s lines as they are. Publishes the file it read (FilesRead), by its resolved path, with the hash of the bytes it read and the lines it showed, and, when lines after those were left out, OutputCut.

ReadArgs

Arguments of Read.

Search

Searches file contents with a regular expression, honouring .gitignore, or lists the files with a match, or every file. Shows each path as read takes it from the same base: below the base when the searched path is relative or not given, absolute when it is absolute. Publishes what it found (SearchHits) and the files it found matches in (FilesRead), by their resolved paths.

SearchArgs

Arguments of Search.

SearchHits

What a Search call found, as it published it beside the text.

Seen

The hash (content_hash) of each file’s text as Read last showed it or Edit or Write last left it, by resolved path; shared by its clones. With it, an edit whose old_text is not found says whether the file changed since, and so needs reading again.

Shell

Runs a command with sh -c in its own session and process group, in its Workspace, as its Launcher starts processes. Its stdout and stderr come back interleaved line by line, as each line ends, without terminal escape sequences such as colours; output past the OutputLimit keeps its first and last lines and the first and last errors and failures from between. Publishes how the command ended (ExitStatus) beside its output, and how the output was cut (OutputCut) when it was, and reports the output as it comes to its Live, if it has one.

ShellArgs

Arguments of Shell.

ShellRun

What a command printed and how it ended.

Spill

The directory where tools keep output they cut, each in a file of its own whose path, the handle, the cut output names.

Write

Writes a whole file, creating its parent directories. Publishes the file it changed (FilesChanged): its resolved path, and the diff. The text it wrote counts as Seen whole, so an edit of the file starts from it; a write that failed forgets the file.

WriteArgs

Arguments of Write.

Constants

MAX_BYTES

Most bytes a tool returns.

MAX_FILES

Most files a search for file names (SearchArgs::files) returns.

MAX_FILE_BYTES

The largest file read and edit load whole, and search scans.

MAX_LINES

Most lines a tool returns.

MAX_MATCHES

Most matches a search returns.

Functions

ago

How long ago elapsed was, roughly, for a list a person reads: just now, 3m ago, 5h ago, 2d ago.

blocking

Run work on a new thread and await its answer. A panic in work becomes an error.

clip

line cut to its first limit characters.

find

Searches as Search does, in workspace, and returns the matches as data: the files under the searched path that its listing keeps, each of at most MAX_FILE_BYTES and read as UTF-8; a search for file names with an empty pattern reads none and keeps them all. Blocks: run it on a thread of its own (blocking).

render

found as Search shows it: a path:line: text line per hit, or a path per file of a search for file names, and a last line when it stopped at MAX_MATCHES or MAX_FILES.

shorten

text cut to fit in width terminal columns, ending in … when cut: a wide character, such as most CJK ones, takes two columns.

show_lines

text’s lines from line first (counted from 1) as Read shows them: as they are, at most limit lines and about max_bytes bytes, and a last line saying how many lines were left out and the offset to read on from, or that first is past the end. Lines longer than a width are cut, marked […], and counted in a note: 2000 characters, or less when that lets the asked lines fit max_bytes, as in a file of long lines, but never below 100 characters.

split_status

Splits a shell call’s output (ShellRun::output) into what the command printed, each line with its \n, and the line after it saying how the command ended; text whole and None when it does not end in such a line. A command’s own output never ends the text, so a line it printed that reads like one is kept as printed.