diff --git a/AGENTS.md b/AGENTS.md index feefc84..64c0532 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,9 +26,10 @@ Anything else gets a qualified lowercase name, such as Rust's built-in test harn - Prefer types and compiler checks, then behavior tests. Gate on yes/no properties, never on a score threshold that ordinary work edits. - Behavior changes ship with tests in the same change. Preserve behavior tests during refactors. - The Plugin crate depends on `runvil-plugin-sdk` and outside libraries alone, and writes no `unsafe`. The SDK owns the C boundary. -- A tool reads files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every read goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. +- A tool reaches files only through `Source` (`crates/plugin-std/src/source.rs`), which the call's `ToolCall` implements, so every file operation goes through the Host and the run's policy applies to it. A test runs a tool's own code over the SDK's `testing::Files` tree, or over `FakeSource` (`crates/plugin-std/src/fake.rs`) for what that tree cannot hold. +- A tool that changes files says so with `ToolInfo::changes_files`, so the Host runs each of its calls by itself among the calls of one model reply. - A tool's description and parameter schema come from its JSON file under `crates/plugin-std/schemas`. `EDITS.md` beside them records every difference from Cursor's definition, and a change to a JSON file changes `EDITS.md` with it. -- A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories and every 2 MiB read, so that no step of its call works for long and the Host can abandon the call between two steps. +- A tool that does a long job awaits `next_step()` after each bounded slice of work, as Grep does every 32 files or directories, so that no step of its call works for long and the Host can abandon the call between two steps. - A Plugin shares its process with the Host, so nothing here installs process-global state, such as a panic hook (`clippy.toml` bans `std::panic::set_hook`), and nothing starts a thread that outlives the Plugin's unload. What every run shares lives in the Plugin instance and never in a `static`, so an unload frees it. - Comments explain a non-obvious constraint, ordering requirement, or workaround. A platform or external-bug workaround cites its upstream issue URL. diff --git a/Cargo.lock b/Cargo.lock index 2efd066..8ae599d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -154,16 +154,16 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" [[package]] name = "runvil-plugin-sdk" -version = "0.4.0" -source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2#03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2" +version = "0.5.0" +source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=52a4905aca0a9c945a93dc4ee7ea815db85612e4#52a4905aca0a9c945a93dc4ee7ea815db85612e4" dependencies = [ "runvil-plugin-sys", ] [[package]] name = "runvil-plugin-sys" -version = "0.4.0" -source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2#03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2" +version = "0.5.0" +source = "git+https://github.com/cppalliance/runvil-plugin-api?rev=52a4905aca0a9c945a93dc4ee7ea815db85612e4#52a4905aca0a9c945a93dc4ee7ea815db85612e4" [[package]] name = "rustix" diff --git a/Cargo.toml b/Cargo.toml index cb662bd..c182bf8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,9 +7,9 @@ edition = "2024" license = "BSL-1.0" [workspace.dependencies] -# The Plugin SDK at contract 0.4, pinned to a commit. A Host loads this +# The Plugin SDK at contract 0.5, pinned to a commit. A Host loads this # Plugin only when its Harness speaks the same contract version. -runvil-plugin-sdk = { version = "0.4.0", git = "https://github.com/cppalliance/runvil-plugin-api", rev = "03a9fa37d2fe690d42ee0aa5c7a8289173e8e0f2" } +runvil-plugin-sdk = { version = "0.5.0", git = "https://github.com/cppalliance/runvil-plugin-api", rev = "52a4905aca0a9c945a93dc4ee7ea815db85612e4" } # Each tool's definition is embedded JSON, and a call's arguments arrive # as JSON text. serde = { version = "1", features = ["derive"] } diff --git a/README.md b/README.md index 5dfd8b6..4eff52d 100644 --- a/README.md +++ b/README.md @@ -9,15 +9,18 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t | `std/read` | `Read` | Returns a window of a text file's lines, each with its line number | | `std/dir` | `ListDir` | Returns a bullet tree of a directory, listed breadth first | | `std/grep` | `Grep` | Searches the files under a path with a Rust regular expression | -| `std/write` | `Write` | A stub: answers that the tool is not implemented | -| `std/replace` | `StrReplace` | A stub | -| `std/rm` | `Delete` | A stub | -| `std/glob` | `Glob` | A stub | +| `std/write` | `Write` | Creates a file, or replaces the whole contents of one | +| `std/replace` | `StrReplace` | Replaces a text that occurs once in a file, or every occurrence of it | +| `std/rm` | `Delete` | Deletes a file or a link, and refuses a directory | +| `std/glob` | `Glob` | A stub: answers that the tool is not implemented | - Each tool's wire name, description, and parameter schema is a JSON file under `crates/plugin-std/schemas`, and `EDITS.md` beside them lists how each differs from Cursor's definition. -- Every file a tool reads goes through the Host, so the run's policy applies to each read. A read the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. -- File text and file names come back as untrusted output. The Host marks them before a model reads them. -- A search ends its step every 32 files or directories, or every 2 MiB read, so the Host can cancel it between two steps. +- Every file operation of a tool goes through the Host, so the run's policy applies to each one. An operation the policy denies fails the call with the policy's own reason. The one exception is an entry below the path a Grep call names, which Grep skips and counts. +- File text and file names come back as untrusted output. The Host marks them before a model reads them. The answer to a change holds fixed text and at most a count, so it is trusted output. +- Write, StrReplace, and Delete say to the Host that they change files. The Host runs a call of such a tool by itself among the calls of one model reply, so two changes of one reply happen in the order the reply lists them. +- StrReplace edits a file with a read and then a write, so a change that another task makes to the file between the two is lost. +- Delete asks what a path names and then asks for its removal, so a directory with no entries that another task puts at the path between the two is removed. +- A tool call ends its step at each file operation, and the Host performs the operation before the next step. A search also ends its step every 32 files or directories, so the Host can cancel a call between two steps. ## Building @@ -25,7 +28,7 @@ The Plugin inserts one Pack, `runvil/std`, which gives a run the standard file t cargo build -p plugin-std --release ``` -This writes `plugin_std.dll` (Windows), `libplugin_std.so` (Linux), or `libplugin_std.dylib` (macOS) to `target/release`. That one file goes in the Host's Plugin directory. +This writes `plugin_std.dll` (Windows), `libplugin_std.so` (Linux), or `libplugin_std.dylib` (macOS) to `target/release`. That one file goes in the Host's Plugin directory. The Plugin speaks contract 0.5, the version that the pin of `runvil-plugin-sdk` in `Cargo.toml` names, and a Host loads it only when its Harness speaks the same version. A Host can also link the crate in. It turns the `dll` feature off, so the crate exports no symbol, and passes `runvil_plugin_sdk::entry::` to the Harness's `insert_plugin`. diff --git a/crates/plugin-std/schemas/EDITS.md b/crates/plugin-std/schemas/EDITS.md index 5fe03ce..90c2126 100644 --- a/crates/plugin-std/schemas/EDITS.md +++ b/crates/plugin-std/schemas/EDITS.md @@ -16,15 +16,20 @@ Each file in this directory except `dir.json` is Cursor's definition of the tool ## write.json -- Cursor's `Write` description, which is about creating or overwriting a file. Reworded to name `StrReplace` for targeted changes and to require a read before overwriting, matching Cursor's own guidance. No behavior was added; only the wording is ours. +- Cursor's `Write` description, which is about creating or overwriting a file. Reworded to name `StrReplace` for targeted changes and to require a read before overwriting, matching Cursor's own guidance. The parameters, their types, and the `required` list are Cursor's. +- The reason the text gives for that read is that the model then knows what the write replaces. The text does not say that the read protects a change, because a write also replaces a change that another task made after the read. +- Added a `Usage` list that states what Write does: the directories on the way to the file are created, `contents` is written exactly as given and holds at most `{write_limit}` bytes, a path that names a directory fails, and the calls in one response that change files run one after another in the order listed. The placeholder is filled when the definition is built, from the SDK's limit on one write, which the code enforces, so the text and the limit cannot drift apart. ## replace.json - Cursor's `StrReplace` definition. The wording is ours; the parameters, their types, and the `required` list are Cursor's. +- Added a `Usage` list that states what StrReplace does: `old_string` is matched exactly, and the line number and the pipe that Read shows are not part of the file; a call fails with the count when `old_string` does not occur exactly once, and with `replace_all` the call needs at least one occurrence; where occurrences overlap, a call without `replace_all` fails and a call with it replaces the ones that do not overlap, from the start of the file; only UTF-8 text is edited, a file over `{file_ceiling}` bytes is refused, and so is an edit that would leave the file with more than `{write_limit}` bytes; and the calls in one response that change files run one after another in the order listed. The two placeholders are filled when the definition is built, from the constants the code enforces, so the text and the limits cannot drift apart. ## rm.json -- Verbatim. Cursor's `Delete` description and schema are kept exactly. +- Cursor's `Delete` description and schema, with two additions to the description. +- `The path is a directory` joined the list of failures, because Delete removes a file and refuses a directory. +- Added a `Usage` list that states that a link is deleted as a link, so what it leads to stays, and that the calls in one response that change files run one after another in the order listed. ## glob.json diff --git a/crates/plugin-std/schemas/replace.json b/crates/plugin-std/schemas/replace.json index aa7718e..c48a571 100644 --- a/crates/plugin-std/schemas/replace.json +++ b/crates/plugin-std/schemas/replace.json @@ -1,6 +1,6 @@ { "wire_name": "StrReplace", - "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.", + "description": "Replaces an exact string in a file with a new string. The old string must be unique in the file unless replace_all is true, so include enough surrounding context to identify the one occurrence you mean. Read the file first.\n\nUsage:\n- old_string is matched exactly, so whitespace, indentation, and line endings count. The line number and the pipe that Read shows are not part of the file.\n- When old_string does not occur exactly once, the call fails and says how many times it occurs. With replace_all set to true, the call replaces every occurrence and needs at least one. Where occurrences of old_string overlap, a call without replace_all fails, and a call with it replaces the ones that do not overlap, from the start of the file.\n- Only UTF-8 text is edited. A file over {file_ceiling} bytes is refused, and so is an edit that would leave the file with more than {write_limit} bytes.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/schemas/rm.json b/crates/plugin-std/schemas/rm.json index 5acd238..00063b5 100644 --- a/crates/plugin-std/schemas/rm.json +++ b/crates/plugin-std/schemas/rm.json @@ -1,6 +1,6 @@ { "wire_name": "Delete", - "description": "Deletes a file at the specified path. The operation will fail gracefully if:\n - The file doesn't exist\n - The operation is rejected for security reasons\n - The file cannot be deleted", + "description": "Deletes a file at the specified path. The operation will fail gracefully if:\n - The file doesn't exist\n - The path is a directory\n - The operation is rejected for security reasons\n - The file cannot be deleted\n\nUsage:\n- A link is deleted as a link, and what it leads to stays.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/schemas/write.json b/crates/plugin-std/schemas/write.json index e9ca390..aa1cf1f 100644 --- a/crates/plugin-std/schemas/write.json +++ b/crates/plugin-std/schemas/write.json @@ -1,6 +1,6 @@ { "wire_name": "Write", - "description": "Creates or overwrites a file at the specified path. Use this tool to create a new file or to replace the whole contents of an existing one. If the destination file already exists, you MUST first read it before writing, so a change you did not make is never overwritten. For a targeted change to an existing file, prefer StrReplace.", + "description": "Creates or overwrites a file at the specified path. Use this tool to create a new file or to replace the whole contents of an existing one. If the destination file already exists, you MUST first read it before writing, so that you know what the write replaces. For a targeted change to an existing file, prefer StrReplace.\n\nUsage:\n- The directories on the way to the file are created when they do not exist.\n- contents is written exactly as given, as the whole file. It holds at most {write_limit} bytes.\n- A path that names a directory fails.\n- The calls in one response that change files run one after another, in the order you list them.", "parameters": { "type": "object", "properties": { diff --git a/crates/plugin-std/src/dir.rs b/crates/plugin-std/src/dir.rs index 98a14cc..932f2e8 100644 --- a/crates/plugin-std/src/dir.rs +++ b/crates/plugin-std/src/dir.rs @@ -33,18 +33,18 @@ use self::args::Request; /// Returns an invalid-arguments [`ToolError`] naming the parameter for a /// bad argument, and a message error for any other failure, worded for a /// model to read. -pub(crate) fn call( +pub(crate) async fn call( source: &impl Source, definition: &Definition, args: &Value, ) -> Result { let request = args::parse(definition, args)?; - list_directory(source, &definition.wire_name, &request, BODY_CAP) + list_directory(source, &definition.wire_name, &request, BODY_CAP).await } /// Lists the directory `request` names, with at most `cap` bytes of tree /// lines. `tool` is the name the model called the tool by. -fn list_directory( +async fn list_directory( source: &impl Source, tool: &str, request: &Request<'_>, @@ -53,7 +53,7 @@ fn list_directory( let target = request.target; let message = |text: String| ToolError::new(ToolErrorKind::Other, text); let failed = |error: FileError| message(refusal(tool, target, &error)); - let stat = match source.stat(target) { + let stat = match source.stat(target).await { Ok(stat) => stat, Err(error) if error.kind() == FileErrorKind::NotFound => { return Err(message(missing_root(target))); @@ -61,7 +61,8 @@ fn list_directory( Err(error) => return Err(failed(error)), }; check_directory(target, stat.file_type).map_err(message)?; - let tree = walk::walk(target, &request.ignore, cap, |path| source.list(path)) + let tree = walk::walk(source, target, &request.ignore, cap) + .await .map_err(|failure| message(refusal(tool, &failure.path, &failure.error)))?; Ok(ToolOutput::untrusted(render::render(&tree))) } diff --git a/crates/plugin-std/src/dir/tests.rs b/crates/plugin-std/src/dir/tests.rs index 1f8a2fd..1bfcfd1 100644 --- a/crates/plugin-std/src/dir/tests.rs +++ b/crates/plugin-std/src/dir/tests.rs @@ -1,7 +1,7 @@ //! Unit tests for the `ListDir` tool. This file holds the helpers the -//! topic files share: a tree of files held in memory, and the two ways to +//! topic files share: a tree of files held in memory, the two ways to //! drive ListDir over it, through its arguments and through a lowered -//! byte cap. +//! byte cap, and a walk over listings a test writes out by hand. mod arguments; mod cap; @@ -9,10 +9,12 @@ mod ignore; mod tree; use runvil_plugin_sdk::testing::Files; -use runvil_plugin_sdk::{ToolError, ToolOutput}; +use runvil_plugin_sdk::{DirEntry, FileError, Stat, ToolError, ToolOutput}; use serde_json::Value; use super::args::Request; +use super::walk::{Failure, Tree, walk}; +use crate::fake::block_on; use crate::matcher::Matcher; use crate::source::Source; use crate::spec::{self, Definition}; @@ -38,7 +40,7 @@ fn definition() -> &'static Definition { fn list(files: &impl Source, args: &Value) -> Result { let definition = definition(); crate::check::check(&definition.wire_name, &definition.parameters, args)?; - super::call(files, definition, args) + block_on(super::call(files, definition, args)) } /// Lists `target`, leaving out `ignore`, under the byte cap `cap`. @@ -55,7 +57,53 @@ fn list_capped( .map(|pattern| Matcher::new(pattern).expect("the pattern is valid")) .collect(), }; - super::list_directory(files, "ListDir", &request, cap) + block_on(super::list_directory(files, "ListDir", &request, cap)) +} + +/// A [`Source`] whose listings a test writes out by hand: `list` answers +/// for each directory the walk enters, so a test can hold any kind of +/// entry, fail any listing, and panic on a directory that must not be +/// entered. The walk only lists, so every other operation panics. +struct Lister(F); + +#[expect( + clippy::unused_async_trait_impl, + reason = "the methods are async for a Host that answers in a later step, and a listing written by hand answers at once" +)] +impl Source for Lister +where + F: Fn(&str) -> Result, FileError>, +{ + async fn stat(&self, path: &str) -> Result { + panic!("the walk asked what {path} names") + } + + async fn list(&self, path: &str) -> Result, FileError> { + (self.0)(path) + } + + async fn read_prefix(&self, path: &str, _len: u64) -> Result, FileError> { + panic!("the walk read {path}") + } + + async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { + panic!("the walk wrote {path}") + } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + panic!("the walk removed {path}") + } +} + +/// Walks `target` over the listings `list` answers with, leaving out +/// `ignore`, under the byte cap `cap`. +fn walk_listed( + target: &str, + ignore: &[Matcher], + cap: usize, + list: impl Fn(&str) -> Result, FileError>, +) -> Result { + block_on(walk(&Lister(list), target, ignore, cap)) } /// The text of a successful listing, which must be untrusted output. diff --git a/crates/plugin-std/src/dir/tests/ignore.rs b/crates/plugin-std/src/dir/tests/ignore.rs index cada9fb..fc08ce4 100644 --- a/crates/plugin-std/src/dir/tests/ignore.rs +++ b/crates/plugin-std/src/dir/tests/ignore.rs @@ -4,8 +4,7 @@ use runvil_plugin_sdk::{DirEntry, FileError, FileType, Stat, ToolErrorKind}; use serde_json::json; -use super::{failure_of, list, seeded, text_of}; -use crate::dir::walk::walk; +use super::{failure_of, list, seeded, text_of, walk_listed}; use crate::matcher::Matcher; /// A tree with `node_modules`, `.log` files, and a `build` directory at @@ -97,7 +96,7 @@ fn a_matching_directory_is_not_entered() { } }; let ignore = [Matcher::new("node_modules").expect("the pattern is valid")]; - let tree = walk("/p", &ignore, 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &ignore, 15_000, lister).expect("the walk succeeds"); assert_eq!( crate::dir::render::render(&tree), "/p/\n - src/\n - a.rs" diff --git a/crates/plugin-std/src/dir/tests/tree.rs b/crates/plugin-std/src/dir/tests/tree.rs index ad516bf..bb2388b 100644 --- a/crates/plugin-std/src/dir/tests/tree.rs +++ b/crates/plugin-std/src/dir/tests/tree.rs @@ -5,10 +5,10 @@ use runvil_plugin_sdk::testing::Files; use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType, Stat}; use serde_json::json; -use super::{failure_of, list, seeded, text_of}; +use super::{failure_of, list, seeded, text_of, walk_listed}; use crate::dir::check_directory; use crate::dir::render::render; -use crate::dir::walk::{Failure, walk}; +use crate::dir::walk::Failure; use crate::fake::{FakeSource, Node}; use crate::matcher::Matcher; use crate::refusal::refusal; @@ -273,7 +273,7 @@ fn a_symlink_is_listed_by_name_without_a_slash_and_is_never_entered() { other => panic!("the walk entered {other}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!( render(&tree), "/p/\n - file\n - link\n - sub/\n - inner" @@ -288,7 +288,7 @@ fn every_other_kind_of_node_is_listed_as_a_plain_name() { entry("sock", FileType::Other), ]) }; - let tree = walk("/dev", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/dev", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!(render(&tree), "/dev/\n - fifo\n - sock"); } @@ -306,7 +306,7 @@ fn the_pack_sorts_each_listing_itself_because_list_promises_no_order() { other => panic!("the walk entered {other}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!( render(&tree), "/p/\n - B\n - a-b\n - a/\n - Z\n - z\n - b" @@ -321,7 +321,8 @@ fn a_failure_listing_the_root_is_returned_for_the_tool_to_word() { format!("not a directory: {path}"), )) }; - let failure = walk("/link/", &[], 15_000, lister).expect_err("the root cannot be listed"); + let failure = + walk_listed("/link/", &[], 15_000, lister).expect_err("the root cannot be listed"); assert_eq!( failure, Failure { @@ -350,7 +351,7 @@ fn a_subdirectory_that_is_gone_or_no_longer_a_directory_is_shown_without_childre other => panic!("the walk entered {other}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("an empty look at these is true"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("an empty look at these is true"); assert_eq!( render(&tree), "/p/\n - gone/\n - open/\n - a\n - swapped/" @@ -371,7 +372,7 @@ fn a_subdirectory_that_cannot_be_listed_for_any_other_reason_fails_the_walk() { other => panic!("the walk entered {other}"), } }; - let failure = walk("/p", &[], 15_000, lister).expect_err(label); + let failure = walk_listed("/p", &[], 15_000, lister).expect_err(label); assert_eq!( failure.path, "/p/locked", "{label}: the directory that failed" @@ -405,7 +406,8 @@ fn a_conflict_below_the_root_is_worded_for_the_directory_that_conflicted() { other => panic!("the walk entered {other}"), } }; - let failure = walk("notes", &[], 15_000, lister).expect_err("the conflict fails the walk"); + let failure = + walk_listed("notes", &[], 15_000, lister).expect_err("the conflict fails the walk"); assert_eq!( refusal("ListDir", &failure.path, &failure.error), "notes/locked was changed, or is being changed, by another call in this round, so it \ @@ -496,7 +498,7 @@ fn a_directory_with_a_control_character_in_its_name_is_never_entered() { other => panic!("the walk entered {other:?}"), } }; - let tree = walk("/p", &[], 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 15_000, lister).expect("the walk succeeds"); assert_eq!(tree.unprintable, 2, "one at each level"); assert_eq!( render(&tree), @@ -514,7 +516,7 @@ fn an_ignored_entry_and_dot_git_are_not_counted_whatever_their_names() { ]) }; let ignore = [Matcher::new("*.log").expect("the pattern is valid")]; - let tree = walk("/p", &ignore, 15_000, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &ignore, 15_000, lister).expect("the walk succeeds"); assert_eq!(tree.unprintable, 0); assert_eq!(render(&tree), "/p/\n - kept"); } @@ -529,7 +531,7 @@ fn the_note_for_names_follows_the_note_of_a_cut_listing() { ]) }; // The root line and the line of `a` fit, and the line of `b` does not. - let tree = walk("/p", &[], 10, lister).expect("the walk succeeds"); + let tree = walk_listed("/p", &[], 10, lister).expect("the walk succeeds"); assert!(tree.truncated); let text = render(&tree); assert!( diff --git a/crates/plugin-std/src/dir/walk.rs b/crates/plugin-std/src/dir/walk.rs index d8210c2..4bbf1c7 100644 --- a/crates/plugin-std/src/dir/walk.rs +++ b/crates/plugin-std/src/dir/walk.rs @@ -11,6 +11,7 @@ use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType}; use crate::matcher::Matcher; use crate::order::{GIT, has_control, sorted}; +use crate::source::Source; /// One line of the tree: a name under its parent. #[derive(Debug)] @@ -58,14 +59,14 @@ pub(super) struct Failure { struct Pending { /// Its index in the tree's nodes. node: usize, - /// The path the lister is given for it. + /// The path it is listed by. path: String, /// The depth of the entries under it: 1 for the root's. depth: usize, } -/// Walks the directory `target`, breadth first, calling `list` for each -/// directory it enters. +/// Walks the directory `target`, breadth first, listing each directory it +/// enters through `source`. /// /// `target` is the path as the model wrote it. `ignore` leaves out each /// entry whose absolute virtual path a pattern matches, and a left-out @@ -78,23 +79,20 @@ struct Pending { /// is marked. /// /// # Errors -/// Returns the lister's error, with the directory it was for, when the -/// root cannot be listed, and for a directory below the root when the +/// Returns the error of a listing, with the directory it was for, when +/// the root cannot be listed, and for a directory below the root when the /// failure is anything but the directory being gone or no longer a /// directory. A claim conflict or a refusal by policy is returned rather /// than shown as an empty directory, because the model would read /// `locked/` as empty when its contents were never seen. Only a directory /// that is gone, or is no longer a directory, is shown with no children, /// because an empty look at it is true. -pub(super) fn walk( +pub(super) async fn walk( + source: &impl Source, target: &str, ignore: &[Matcher], cap: usize, - mut list: F, -) -> Result -where - F: FnMut(&str) -> Result, FileError>, -{ +) -> Result { let root_line = root_line(target); let mut used = root_line.len() + 1; let mut nodes = vec![Node { @@ -111,7 +109,7 @@ where let mut truncated = false; let mut unprintable = 0; while let Some(pending) = queue.pop_front() { - let entries = match list(&pending.path) { + let entries = match source.list(&pending.path).await { Ok(entries) => entries, Err(error) if pending.node != 0 && is_gone(&error) => Vec::new(), Err(error) => { @@ -218,8 +216,8 @@ fn join(directory: &str, name: &str) -> String { } } -/// The path the lister is given for the root: the target as written, -/// without a trailing `/`, and `/` alone for the filesystem root. +/// The path the root is listed by: the target as written, without a +/// trailing `/`, and `/` alone for the filesystem root. fn directory_path(target: &str) -> String { let trimmed = target.trim_end_matches('/'); if trimmed.is_empty() { diff --git a/crates/plugin-std/src/fake.rs b/crates/plugin-std/src/fake.rs index bb0f300..c1ea50f 100644 --- a/crates/plugin-std/src/fake.rs +++ b/crates/plugin-std/src/fake.rs @@ -1,18 +1,42 @@ -//! A [`Source`] the tests of every tool build by hand, for what the fake -//! Host's tree cannot hold: a link to a directory or to a file, a pipe, a -//! file whose listed size differs from its bytes, and a directory or a -//! file that fails only when it is listed or read. A name may hold any +//! What the tests of every tool share: [`FakeSource`], a [`Source`] they +//! build by hand, and [`block_on`], which runs a tool's future to its +//! end. +//! +//! The fake holds what the fake Host's tree cannot: a link to a directory +//! or to a file, a pipe, a file whose listed size differs from its bytes, +//! a directory or a file that fails only when it is listed or read, and a +//! file that fails only a change. A name may hold any //! character, a control character among them. //! //! Every node sits directly under `/`, or under a [`Node::Link`], which -//! lists as a directory. +//! lists as a directory. The tree never changes: it fails every change, +//! with the error of a [`Node::Guarded`] where the path names one. +use std::cell::RefCell; use std::collections::BTreeMap; +use std::future::Future; +use std::pin::pin; +use std::task::{Context, Poll, Waker}; use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType, Stat}; use crate::source::Source; +/// Runs `future` to its output, polling it again after each `Pending`. +/// +/// A tool's future waits on no waker. Over a tree held in memory each +/// file operation answers at once, so the only `Pending` is a pause, +/// which the next poll ends. +pub(crate) fn block_on(future: F) -> F::Output { + let mut future = pin!(future); + let mut cx = Context::from_waker(Waker::noop()); + loop { + if let Poll::Ready(output) = future.as_mut().poll(&mut cx) { + return output; + } + } +} + /// One node of the fake tree. #[derive(Debug, Clone)] pub(crate) enum Node { @@ -34,6 +58,9 @@ pub(crate) enum Node { ListFails(FileError), /// A file whose read fails with this error. ReadFails(FileError), + /// A file with these bytes that fails each change with this error, as + /// a file that the run's policy lets a tool read and not change. + Guarded(Vec, FileError), } /// A tree of nodes by absolute path, with `/` always a directory. @@ -41,9 +68,17 @@ pub(crate) enum Node { pub(crate) struct FakeSource { /// Every node but the root. nodes: BTreeMap, + /// The most bytes that each read asked for, in the order of the reads. + asked: RefCell>, } impl FakeSource { + /// The most bytes that each read of the tree asked for, in the order + /// of the reads. + pub(crate) fn asked(&self) -> Vec { + self.asked.borrow().clone() + } + /// The tree with `node` added at `path`. pub(crate) fn with(mut self, path: &str, node: Node) -> FakeSource { self.nodes.insert(path.to_owned(), node); @@ -58,7 +93,9 @@ impl FakeSource { /// The metadata of `node`. fn stat_of(node: &Node) -> Stat { match node { - Node::File(bytes) => Stat::new(FileType::File, bytes.len() as u64), + Node::File(bytes) | Node::Guarded(bytes, _) => { + Stat::new(FileType::File, bytes.len() as u64) + } Node::Sized(size, _) => Stat::new(FileType::File, *size), Node::ReadFails(_) => Stat::new(FileType::File, 1), Node::ListFails(_) => Stat::new(FileType::Directory, 0), @@ -73,6 +110,37 @@ impl FakeSource { fn missing(path: &str) -> FileError { FileError::new(FileErrorKind::NotFound, format!("not found: {path}")) } + + /// Every byte of the file at `path`, as a read of the whole file + /// would give them. + fn bytes_at(&self, path: &str) -> Result, FileError> { + match self.nodes.get(path) { + Some( + Node::File(bytes) + | Node::Sized(_, bytes) + | Node::LinkToFile(bytes) + | Node::Guarded(bytes, _), + ) => Ok(bytes.clone()), + Some(Node::ReadFails(error) | Node::LinkFails(error)) => Err(error.clone()), + Some(Node::Link | Node::ListFails(_)) => Err(FileError::new( + FileErrorKind::IsADirectory, + format!("is a directory: {path}"), + )), + Some(Node::Pipe) | None => Err(Self::missing(path)), + } + } + + /// The error of a change to `path`, which the tree never takes: the + /// error of a [`Node::Guarded`], and a fixed one for any other path. + fn refused(&self, path: &str) -> FileError { + match self.nodes.get(path) { + Some(Node::Guarded(_, error)) => error.clone(), + _ => FileError::new( + FileErrorKind::Other, + format!("the fake tree takes no change: {path}"), + ), + } + } } /// The directory that holds `path`, and the name it has there. @@ -84,8 +152,12 @@ fn split(path: &str) -> (&str, &str) { } } +#[expect( + clippy::unused_async_trait_impl, + reason = "the methods are async for a Host that answers in a later step, and a tree held in memory answers at once" +)] impl Source for FakeSource { - fn stat(&self, path: &str) -> Result { + async fn stat(&self, path: &str) -> Result { if path == "/" { return Ok(Stat::new(FileType::Directory, 0)); } @@ -95,7 +167,7 @@ impl Source for FakeSource { .ok_or_else(|| Self::missing(path)) } - fn list(&self, path: &str) -> Result, FileError> { + async fn list(&self, path: &str) -> Result, FileError> { if path != "/" { match self.nodes.get(path) { None => return Err(Self::missing(path)), @@ -119,23 +191,18 @@ impl Source for FakeSource { .collect()) } - fn read(&self, path: &str) -> Result, FileError> { - match self.nodes.get(path) { - Some(Node::File(bytes) | Node::Sized(_, bytes) | Node::LinkToFile(bytes)) => { - Ok(bytes.clone()) - } - Some(Node::ReadFails(error) | Node::LinkFails(error)) => Err(error.clone()), - Some(Node::Link | Node::ListFails(_)) => Err(FileError::new( - FileErrorKind::IsADirectory, - format!("is a directory: {path}"), - )), - Some(Node::Pipe) | None => Err(Self::missing(path)), - } - } - - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { - let mut bytes = self.read(path)?; + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + self.asked.borrow_mut().push(len); + let mut bytes = self.bytes_at(path)?; bytes.truncate(usize::try_from(len).unwrap_or(usize::MAX)); Ok(bytes) } + + async fn write(&self, path: &str, _bytes: Vec) -> Result<(), FileError> { + Err(self.refused(path)) + } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + Err(self.refused(path)) + } } diff --git a/crates/plugin-std/src/grep.rs b/crates/plugin-std/src/grep.rs index f4603da..d8a466c 100644 --- a/crates/plugin-std/src/grep.rs +++ b/crates/plugin-std/src/grep.rs @@ -2,13 +2,14 @@ //! path. //! //! Grep walks the tree through the call's [`Source`], so the run's policy -//! applies, and reads each file whole, never more than 16 MiB of it. -//! Files come in path order, the order Glob uses. The lines of the answer -//! stop at 15,000 bytes, with the notes under them not counted, and every -//! call runs from the start, so a call with an `offset` pages through the -//! same result. An entry below the path the call names that cannot be -//! searched is skipped and counted, never a failure. The text of the -//! files is returned as untrusted output. +//! applies. It reads each file with one request, which asks for no more +//! than one byte past 16 MiB, so a longer file is skipped and never held +//! whole. Files come in path order, the order Glob uses. The lines of the +//! answer stop at 15,000 bytes, with the notes under them not counted, +//! and every call runs from the start, so a call with an `offset` pages +//! through the same result. An entry below the path the call names that +//! cannot be searched is skipped and counted, never a failure. The text +//! of the files is returned as untrusted output. mod args; mod collect; diff --git a/crates/plugin-std/src/grep/find.rs b/crates/plugin-std/src/grep/find.rs index 6146c5a..3ab4800 100644 --- a/crates/plugin-std/src/grep/find.rs +++ b/crates/plugin-std/src/grep/find.rs @@ -3,9 +3,8 @@ //! //! [`find`] is a pure function of its [`Source`]: it reads no clock, keeps //! nothing between calls, and returns what it found without writing any -//! text. It ends its step after every slice of entries or bytes its -//! [`Limits`] name, so the Host can abandon a running search between two -//! steps. +//! text. It ends its step after every slice of entries its [`Limits`] +//! name, so the Host can abandon a running search between two steps. use runvil_plugin_sdk::{DirEntry, FileError, FileErrorKind, FileType, next_step}; @@ -99,7 +98,7 @@ pub(super) async fn find( limits: &Limits, ) -> Result { let root = request.path.unwrap_or("/"); - let stat = match source.stat(root) { + let stat = match source.stat(root).await { Ok(stat) => stat, Err(error) if error.kind() == FileErrorKind::NotFound => return Err(missing_root(root)), Err(error) => return Err(refusal(tool, root, &error)), @@ -114,12 +113,11 @@ pub(super) async fn find( considered: 0, bytes: 0, since_entries: 0, - since_bytes: 0, finished: false, }; match stat.file_type { FileType::Directory => search.directory(root).await?, - FileType::File => search.root_file(root, Some(stat.len))?, + FileType::File => search.root_file(root, Some(stat.len)).await?, FileType::Symlink => search.link(root).await?, _ => return Err(neither_file_nor_directory(root)), } @@ -149,8 +147,6 @@ pub(super) struct Search<'a, 'r, S: Source> { /// The files considered and the directories listed since the last /// pause. since_entries: usize, - /// The bytes read since the last pause. - since_bytes: u64, /// Whether the search has everything it needs, or hit a limit. pub(super) finished: bool, } @@ -162,6 +158,7 @@ impl Search<'_, '_, S> { let entries = self .source .list(&node.access) + .await .map_err(|error| refusal(self.tool, root, &error))?; self.walk(node, entries).await; Ok(()) @@ -171,13 +168,13 @@ impl Search<'_, '_, S> { /// and as a file when it does not. async fn link(&mut self, root: &str) -> Result<(), String> { let node = Node::directory(root); - match self.source.list(&node.access) { + match self.source.list(&node.access).await { Ok(entries) => { self.walk(node, entries).await; Ok(()) } Err(error) if error.kind() == FileErrorKind::NotADirectory => { - self.root_file(root, None) + self.root_file(root, None).await } Err(error) => Err(refusal(self.tool, root, &error)), } @@ -187,30 +184,43 @@ impl Search<'_, '_, S> { /// type applies, because the model named it. /// /// `size` is the file's size when the stat gave it, and `None` for a - /// link, whose own size says nothing about its target. - fn root_file(&mut self, root: &str, size: Option) -> Result<(), String> { + /// link, whose own size says nothing about its target. A size over + /// the limit skips the file with no read. + async fn root_file(&mut self, root: &str, size: Option) -> Result<(), String> { let node = Node::file(root); self.considered += 1; - let bytes = if let Some(size) = size { - if size > self.limits.max_file_size { - self.skip(Reason::OverSize, Some(&node.shown)); - return Ok(()); - } - self.source.read(&node.access) - } else { - self.source - .read_prefix(&node.access, self.limits.max_file_size.saturating_add(1)) - } - .map_err(|error| refusal(self.tool, root, &error))?; - if size.is_none() && length(&bytes) > self.limits.max_file_size { + if size.is_some_and(|size| size > self.limits.max_file_size) { self.skip(Reason::OverSize, Some(&node.shown)); return Ok(()); } - self.bytes += length(&bytes); + let read = self + .read(&node.access) + .await + .map_err(|error| refusal(self.tool, root, &error))?; + let Some(bytes) = read else { + self.skip(Reason::OverSize, Some(&node.shown)); + return Ok(()); + }; self.consume(&node.shown, &bytes); Ok(()) } + /// The bytes of the file at `path`, or `None` for a file over the + /// largest size a search takes. The read asks for one byte past that + /// size and no more, so a file that is longer than its listing or its + /// stat said shows as over the size and is never held whole. Every + /// byte that the read brings counts toward the most a search reads, + /// the bytes of a file that is then skipped among them. + async fn read(&mut self, path: &str) -> Result>, FileError> { + let most = self.limits.max_file_size; + let bytes = self + .source + .read_prefix(path, most.saturating_add(1)) + .await?; + self.bytes += length(&bytes); + Ok((length(&bytes) <= most).then_some(bytes)) + } + /// Walks the directory `root`, whose `entries` are already listed, /// depth first. async fn walk(&mut self, root: Node, entries: Vec) { @@ -237,7 +247,7 @@ impl Search<'_, '_, S> { match entry.stat.file_type { FileType::Symlink => self.skip(Reason::SymbolicLink, Some(&child.shown)), FileType::Directory => { - match self.source.list(&child.access) { + match self.source.list(&child.access).await { Ok(entries) => stack.push(Frame { dir: child, entries: sorted(entries).into_iter(), @@ -250,7 +260,7 @@ impl Search<'_, '_, S> { self.pace().await; } FileType::File => { - self.visit(&child, &entry.name, entry.stat.len); + self.visit(&child, &entry.name, entry.stat.len).await; self.pace().await; } // A pipe, a socket, or a device is never opened: reading one @@ -262,7 +272,7 @@ impl Search<'_, '_, S> { /// Visits one file the walk met: counts it, applies the filters, /// reads it, and searches it. - fn visit(&mut self, node: &Node, name: &str, size: u64) { + async fn visit(&mut self, node: &Node, name: &str, size: u64) { if self.considered >= self.limits.max_files { self.finish(Stop::Files); return; @@ -287,25 +297,21 @@ impl Search<'_, '_, S> { self.finish(Stop::Bytes); return; } - match self.source.read(&node.access) { - Ok(bytes) => { - self.bytes += length(&bytes); - self.since_bytes += length(&bytes); - self.consume(&node.shown, &bytes); - } + match self.read(&node.access).await { + Ok(Some(bytes)) => self.consume(&node.shown, &bytes), + Ok(None) => self.skip(Reason::OverSize, Some(&node.shown)), Err(error) => self.skip(file_reason(&error), Some(&node.shown)), } } - /// Pauses when enough entries or bytes have gone by since the last - /// pause: ends the step, so that no step works for long and a cancel - /// or a stop can drop the future between two steps. + /// Pauses when enough entries have gone by since the last pause: ends + /// the step, so that no step works for long and a cancel or a stop + /// can drop the future between two steps. A listing or a read through + /// the Host ends the step too, so the pause is what bounds a run of + /// files that a filter leaves unread. async fn pace(&mut self) { - if self.since_entries >= self.limits.slice_entries - || self.since_bytes >= self.limits.slice_bytes - { + if self.since_entries >= self.limits.slice_entries { self.since_entries = 0; - self.since_bytes = 0; next_step().await; } } diff --git a/crates/plugin-std/src/grep/found.rs b/crates/plugin-std/src/grep/found.rs index 75786ad..199339b 100644 --- a/crates/plugin-std/src/grep/found.rs +++ b/crates/plugin-std/src/grep/found.rs @@ -18,9 +18,6 @@ const MAX_BYTES: u64 = 1_073_741_824; /// pauses. const SLICE_ENTRIES: usize = 32; -/// How many bytes are read between two pauses: 2 MiB. -const SLICE_BYTES: u64 = 2_097_152; - /// How many skipped paths the skip line names. const FIRST_KEPT: usize = 5; @@ -32,12 +29,12 @@ pub(super) struct Limits { pub(super) max_files: usize, /// The most bytes read before the search stops. pub(super) max_bytes: u64, - /// The largest file, by the size its listing gives, that is searched. + /// The largest file that is searched. A longer one is skipped by the + /// size its listing gives, and failing that by a read that stops one + /// byte past this size. pub(super) max_file_size: u64, /// The files considered and directories listed between two pauses. pub(super) slice_entries: usize, - /// The bytes read between two pauses. - pub(super) slice_bytes: u64, /// The most bytes of body in the answer. pub(super) body_cap: usize, /// How much of a long line is shown. @@ -51,7 +48,6 @@ impl Default for Limits { max_bytes: MAX_BYTES, max_file_size: MAX_FILE_BYTES, slice_entries: SLICE_ENTRIES, - slice_bytes: SLICE_BYTES, body_cap: BODY_CAP, window: Window::default(), } @@ -67,7 +63,7 @@ pub(super) enum Reason { UnreadableDirectory, /// A file that could not be read. UnreadableFile, - /// A file whose listed size is over the limit. + /// A file over the size limit, by its listed size or by its bytes. OverSize, /// A symbolic link, which is never entered or read. SymbolicLink, diff --git a/crates/plugin-std/src/grep/tests.rs b/crates/plugin-std/src/grep/tests.rs index 7d11f4d..89460c6 100644 --- a/crates/plugin-std/src/grep/tests.rs +++ b/crates/plugin-std/src/grep/tests.rs @@ -23,20 +23,10 @@ use serde_json::Value; use super::args; use super::found::Limits; +use crate::fake::block_on; use crate::source::Source; use crate::spec::{self, Definition}; -/// Drives a future to its output, polling again after each `Pending`. -fn block_on(future: F) -> F::Output { - let mut future = pin!(future); - let mut cx = Context::from_waker(Waker::noop()); - loop { - if let Poll::Ready(output) = future.as_mut().poll(&mut cx) { - return output; - } - } -} - /// Drives a future to its output and counts how many times it returned /// `Pending` on the way. fn count_pendings(future: F) -> (F::Output, usize) { diff --git a/crates/plugin-std/src/grep/tests/skips.rs b/crates/plugin-std/src/grep/tests/skips.rs index 9801e98..e36fa71 100644 --- a/crates/plugin-std/src/grep/tests/skips.rs +++ b/crates/plugin-std/src/grep/tests/skips.rs @@ -199,6 +199,83 @@ fn a_file_over_the_size_limit_is_skipped_before_any_read() { ); } +#[test] +fn a_file_that_is_longer_than_its_listing_said_is_skipped_and_not_searched() { + // The listing says 10 bytes, so the file passes the check before the + // read, and the read then finds more bytes than the limit. + let mut longer = b"NEEDLE\n".to_vec(); + longer.resize(500, b'a'); + let source = FakeSource::default() + .with("/grew.log", Node::Sized(10, longer)) + .file("/ok.txt", "NEEDLE\n"); + let output = text_of(grep_over( + &source, + &json!({ "pattern": "NEEDLE" }), + &small_files(), + )); + assert_eq!( + output, + "/ok.txt\n 1:NEEDLE\n\n[Skipped 1 entry: 1 file over 100 bytes. First: /grew.log]" + ); +} + +#[test] +fn each_read_asks_for_one_byte_past_the_size_limit_and_no_more() { + let source = FakeSource::default() + .with("/grew.log", Node::Sized(10, vec![b'a'; 500])) + .file("/ok.txt", "NEEDLE\n"); + // A walk reads both files, and the call after it reads the one file + // that it names, under the limit of 16 MiB that a real search has. + let walked = grep_over(&source, &json!({ "pattern": "NEEDLE" }), &small_files()); + assert!(walked.is_ok()); + let named = grep_over( + &source, + &json!({ "pattern": "NEEDLE", "path": "/ok.txt" }), + &Limits::default(), + ); + assert!(named.is_ok()); + assert_eq!(source.asked(), [101, 101, 16_777_217]); +} + +#[test] +fn a_read_that_turns_out_over_the_size_limit_counts_toward_the_byte_limit() { + // Each listing says 10 bytes, and each read brings 101, one more than + // the size limit. The second read brings the count to the byte limit, + // so the search stops before it reads the third file. + let grown = Node::Sized(10, vec![b'a'; 500]); + let source = FakeSource::default() + .with("/a.log", grown.clone()) + .with("/b.log", grown.clone()) + .with("/c.log", grown); + let limits = Limits { + max_bytes: 202, + ..small_files() + }; + let output = + grep_over(&source, &json!({ "pattern": "a" }), &limits).expect("the search succeeds"); + assert_eq!( + output.text(), + "No matches found. Searched 0 files.\n\n\ + [Skipped 2 entries: 2 files over 100 bytes. First: /a.log, /b.log]\n\ + [No ignore rules ran: .gitignore is not applied, and only entries named .git are \ + skipped.]\n\ + [Search stopped after reading 202 bytes. Narrow path, glob or type to search the rest.]" + ); +} + +#[test] +fn a_file_exactly_at_the_size_limit_is_searched() { + let mut edge = b"NEEDLE\n".to_vec(); + edge.resize(100, b'a'); + let source = FakeSource::default().with("/edge.txt", Node::File(edge)); + let output = text_of(grep_over( + &source, + &json!({ "pattern": "NEEDLE" }), + &small_files(), + )); + assert_eq!(output, "/edge.txt\n 1:NEEDLE"); +} + #[test] fn a_missing_path_fails_with_the_does_not_exist_text() { let source = FakeSource::default().file("/a.txt", "x\n"); @@ -269,6 +346,24 @@ fn a_named_file_over_the_size_limit_is_a_skip() { ); } +#[test] +fn a_named_file_that_is_longer_than_its_stat_said_is_a_skip() { + let source = FakeSource::default().with("/grew", Node::Sized(10, vec![b'a'; 500])); + let output = grep_over( + &source, + &json!({ "pattern": "a", "path": "/grew" }), + &small_files(), + ) + .expect("the search succeeds"); + assert!( + output + .text() + .starts_with("No matches found. Searched 0 files.\n\n[Skipped 1 entry: 1 file over 100 bytes. First: /grew]"), + "{}", + output.text() + ); +} + #[test] fn a_named_link_is_searched_through_as_a_directory_and_then_as_a_file() { let source = FakeSource::default() @@ -370,21 +465,27 @@ fn a_tree_of_directories_with_no_files_still_pauses_once_per_slice() { } #[test] -fn the_search_pauses_once_per_slice_of_bytes() { +fn a_run_of_files_that_a_filter_leaves_unread_still_pauses_once_per_slice() { let mut source = FakeSource::default(); for index in 0..10 { - source = source.file(&format!("/f{index}"), "0123456789"); + source = source.file(&format!("/f{index}.log"), "x\n"); } let limits = Limits { - slice_bytes: 25, + slice_entries: 3, ..Limits::default() }; let definition = definition(); - let args = json!({ "pattern": "x" }); + let args = json!({ "pattern": "x", "glob": "*.txt" }); let request = args::parse(definition, &args).expect("the arguments parse"); let (output, pending) = count_pendings(crate::grep::search(&source, "Grep", &request, &limits)); - assert!(output.is_ok()); - assert_eq!(pending, 3, "after files 3, 6, and 9, at 30 bytes each time"); + assert!( + output + .expect("the search succeeds") + .text() + .starts_with("No matches found. Searched 0 files."), + "no file passes the glob, so none is read" + ); + assert_eq!(pending, 3, "after files 3, 6, and 9"); } #[test] diff --git a/crates/plugin-std/src/lib.rs b/crates/plugin-std/src/lib.rs index 968b9c7..f9e73a3 100644 --- a/crates/plugin-std/src/lib.rs +++ b/crates/plugin-std/src/lib.rs @@ -63,27 +63,56 @@ //! not counted, a call with an `offset` pages through the same result, //! and a binary file, a link, an over-size file, and an entry that cannot //! be read are skipped and counted, never a failure. A search ends its -//! step every 32 files or directories, or every 2 MiB read, so a cancel -//! or a stop can drop it between two steps. File text comes back as -//! untrusted output. -//! -//! Write, StrReplace, Delete, and Glob are still stubs: a call with -//! arguments that match the schema answers [`NOT_IMPLEMENTED`]. For every -//! tool, a call whose arguments do not match fails with an -//! invalid-arguments [`ToolError`](runvil_plugin_sdk::ToolError) naming -//! the parameter. +//! step every 32 files or directories, so a cancel or a stop can drop it +//! between two steps. File text comes back as untrusted output. +//! +//! Write is real. It makes a file, or replaces the whole contents of one, +//! with one write, and the Host makes each directory on the way to the +//! file. It reads nothing first, so what was at the path is gone. It +//! refuses contents over 16 MiB, the most one write takes. Its answer is +//! the count of bytes written in fixed text, so it comes back as trusted +//! output. +//! +//! StrReplace is real. It reads a file as Read does, with the same +//! refusals of a directory, a special file, and a file over 16 MiB, and +//! it writes the file back with one text in place of another. The file +//! must hold UTF-8, and nothing outside the matches changes. The text to +//! replace must occur exactly once, unless `replace_all` is set, and a +//! failure states how many times it occurs. The edit is a read and then a +//! write, so a change that another task makes to the file between the two +//! is lost. Its answer is the count of replacements in fixed text, so it +//! comes back as trusted output. +//! +//! Delete is real. It asks what the path names and then asks for its +//! removal. It refuses a directory with a sentence, and it fails on a +//! path where nothing is. The delete is a stat and then a removal, so a +//! directory with no entries that another task puts at the path between +//! the two is removed. A link goes as a link, so what it leads to stays. +//! Its answer is fixed text, so it comes back as trusted output. +//! +//! Glob is still a stub: a call with arguments that match the schema +//! answers [`NOT_IMPLEMENTED`]. For every tool, a call whose arguments do +//! not match fails with an invalid-arguments +//! [`ToolError`](runvil_plugin_sdk::ToolError) naming the parameter. //! //! # Where the file access goes //! //! Every filesystem operation a tool performs goes through its //! [`ToolCall`](runvil_plugin_sdk::ToolCall), never the disk directly. -//! The Host answers each one under the run's policy, so a read the policy -//! denies fails without the Pack deciding anything. A tool reports the +//! Each one ends the step of its call: the Host performs the operation +//! under the run's policy, and a later step goes on with the answer. So +//! an operation the policy denies fails without the Pack deciding +//! anything. A tool reports the //! [`FileError`](runvil_plugin_sdk::FileError) for the path its call //! names as a tool error the model can read. Below that path, ListDir //! fails the same way on a directory that is there and cannot be listed, //! and Grep skips the entry and counts it. //! +//! A tool that changes files says so to the Host, as Write, StrReplace, +//! and Delete do. The Host runs a call of such a tool by itself among the +//! calls of one model reply, after the calls the reply lists before it, +//! so two changes of one reply happen in the order the reply lists them. +//! //! Shell is deliberately absent. An in-process shell over the same //! filesystem is a separate Pack, so a run that wants one declares it. //! @@ -111,9 +140,12 @@ //! arguments, so a model can tell a bad call from a missing //! implementation. //! - A key the schema does not declare is refused by name, with the -//! parameters listed, by the three real tools, Read, ListDir, and -//! Grep. The stubs let it through. Grep alone accepts `-n` when it is -//! `true`, because Cursor's definition once declared it. +//! parameters listed, by every real tool. Glob, the one stub, lets it +//! through. Grep alone accepts `-n` when it is `true`, because Cursor's +//! definition once declared it. +//! - A tool that changes files is flagged with +//! [`ToolInfo::changes_files`](runvil_plugin_sdk::ToolInfo::changes_files), +//! and a test holds the flags in place. mod check; mod dir; @@ -125,9 +157,12 @@ mod order; mod pack; mod read; mod refusal; +mod replace; +mod rm; mod source; mod spec; mod text; +mod write; use std::sync::Arc; diff --git a/crates/plugin-std/src/pack-tests.rs b/crates/plugin-std/src/pack-tests.rs index d4e2322..8d1605a 100644 --- a/crates/plugin-std/src/pack-tests.rs +++ b/crates/plugin-std/src/pack-tests.rs @@ -1,27 +1,20 @@ //! Unit tests for the `std` Pack's stub text, the definitions it builds -//! from, the arguments it parses, and the tool a call's name picks. +//! from, the arguments it parses, the tool a call's name picks, and the +//! tools it says change files. -use std::future::Future; -use std::pin::pin; use std::sync::Arc; -use std::task::{Context, Poll, Waker}; use runvil_plugin_sdk::testing::Files; use runvil_plugin_sdk::{ToolError, ToolErrorKind, ToolOutput}; use super::{INFO, NOT_IMPLEMENTED, StdPack, parse, run}; +use crate::fake::block_on; use crate::spec::{self, Definition}; /// Runs one call of the tool `name` with `arguments` over `files` to its -/// end, polling again after each `Pending`. +/// end. fn ran(name: &str, arguments: &str, files: &Files) -> Result { - let mut future = pin!(run(spec::all(), name, arguments, files)); - let mut cx = Context::from_waker(Waker::noop()); - loop { - if let Poll::Ready(result) = future.as_mut().poll(&mut cx) { - return result; - } - } + block_on(run(spec::all(), name, arguments, files)) } #[test] @@ -142,8 +135,35 @@ fn a_call_goes_to_the_tool_its_name_picks() { assert_eq!(dir.text(), "/p/\n - a.md\n - b.md"); let grep = ran("grep", r#"{"pattern":"needle"}"#, &files).expect("the tree searches"); assert_eq!(grep.text(), "/p/a.md\n 1:needle"); - let stub = ran("write", r#"{"path":"/p/c.md","contents":"x"}"#, &files) - .expect("a stub answers its text"); - assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "Write")); + let write = + ran("write", r#"{"path":"/p/c.md","contents":"x"}"#, &files).expect("the file is written"); + assert_eq!(write.text(), "Wrote 1 byte."); + assert_eq!(files.read("/p/c.md", 0, u64::MAX), Ok(b"x".to_vec())); + let replace = ran( + "replace", + r#"{"path":"/p/c.md","old_string":"x","new_string":"y"}"#, + &files, + ) + .expect("the file is edited"); + assert_eq!(replace.text(), "Made 1 replacement."); + assert_eq!(files.read("/p/c.md", 0, u64::MAX), Ok(b"y".to_vec())); + let rm = ran("rm", r#"{"path":"/p/c.md"}"#, &files).expect("the file is deleted"); + assert_eq!(rm.text(), "Deleted the file."); + assert!(files.stat("/p/c.md").is_err()); + let stub = + ran("glob", r#"{"glob_pattern":"*.md"}"#, &files).expect("the stub answers its text"); + assert_eq!(stub.text(), NOT_IMPLEMENTED.replace("", "Glob")); assert!(stub.is_trusted()); } + +#[test] +fn an_instance_flags_the_tools_that_change_files_and_no_other() { + let pack = StdPack::new(spec::load().expect("every definition parses").into()); + let flagged: Vec<&str> = pack + .tools + .iter() + .filter(|tool| tool.changes_files) + .map(|tool| tool.name.as_str()) + .collect(); + assert_eq!(flagged, ["write", "replace", "rm"]); +} diff --git a/crates/plugin-std/src/pack.rs b/crates/plugin-std/src/pack.rs index 913e1b4..af35275 100644 --- a/crates/plugin-std/src/pack.rs +++ b/crates/plugin-std/src/pack.rs @@ -1,7 +1,6 @@ //! The `std` Pack: its [`INFO`], [`StdPack`], one run's instance, which //! lists the Pack's tools and hands each call to its tool's module, and -//! the stub that every tool but Read, ListDir, and Grep still answers -//! with in this build. +//! the stub that Glob still answers with in this build. use std::sync::Arc; @@ -15,8 +14,8 @@ use crate::source::Source; use crate::spec::Definition; /// What a call to a tool that is still a stub answers in this build, when -/// its arguments match the schema. Read, ListDir, and Grep are real and -/// never answer this. +/// its arguments match the schema. Glob is the one stub, and every other +/// tool is real and never answers this. /// /// The text says the implementation is missing rather than that the call /// was wrong, because a model that reads it should stop calling the tool. @@ -44,23 +43,37 @@ pub(crate) struct StdPack { } impl StdPack { - /// Makes the instance, naming each tool by its definition's segment. + /// Makes the instance, naming each tool by its definition's segment + /// and saying which tools change files. pub(crate) fn new(definitions: Arc<[Definition]>) -> StdPack { let tools = definitions .iter() .map(|definition| { - ToolInfo::new( + let tool = ToolInfo::new( definition.segment, definition.description.clone(), definition.parameters.to_string(), ) - .wire_name(definition.wire_name.clone()) + .wire_name(definition.wire_name.clone()); + if changes_files(definition.segment) { + tool.changes_files() + } else { + tool + } }) .collect(); StdPack { definitions, tools } } } +/// Whether a call of the tool with the id segment `segment` changes files +/// of its run. The Host runs a call of such a tool by itself among the +/// calls of one model reply, after the calls the reply lists before it, +/// so two changes of one reply happen in the order the reply lists them. +fn changes_files(segment: &str) -> bool { + matches!(segment, "write" | "replace" | "rm") +} + /// The stub text for the tool the model calls `wire_name`. fn stub(wire_name: &str) -> String { NOT_IMPLEMENTED.replace("", wire_name) @@ -95,9 +108,12 @@ async fn run( let args = parse(&definition.wire_name, arguments)?; crate::check::check(&definition.wire_name, &definition.parameters, &args)?; match definition.segment { - "read" => crate::read::call(source, definition, &args), - "dir" => crate::dir::call(source, definition, &args), + "read" => crate::read::call(source, definition, &args).await, + "dir" => crate::dir::call(source, definition, &args).await, "grep" => crate::grep::call(source, definition, &args).await, + "write" => crate::write::call(source, definition, &args).await, + "replace" => crate::replace::call(source, definition, &args).await, + "rm" => crate::rm::call(source, definition, &args).await, _ => Ok(ToolOutput::trusted(stub(&definition.wire_name))), } } diff --git a/crates/plugin-std/src/read.rs b/crates/plugin-std/src/read.rs index 46007a0..4e5d025 100644 --- a/crates/plugin-std/src/read.rs +++ b/crates/plugin-std/src/read.rs @@ -17,7 +17,7 @@ use runvil_plugin_sdk::{FileError, FileType, ToolError, ToolErrorKind, ToolOutpu use serde_json::Value; use crate::check::plural; -use crate::refusal::{neither_file_nor_directory, refusal}; +use crate::refusal::{is_a_directory, neither_file_nor_directory, refusal}; use crate::source::Source; use crate::spec::Definition; use crate::text::{MAX_FILE_BYTES, decode, sniff_binary, split_lines}; @@ -35,19 +35,19 @@ pub(crate) const BYTE_CAP: usize = 100_000; /// Returns an invalid-arguments [`ToolError`] naming the parameter for a /// bad argument, and a message error for any other failure, worded for a /// model to read. -pub(crate) fn call( +pub(crate) async fn call( source: &impl Source, definition: &Definition, args: &Value, ) -> Result { let request = args::parse(definition, args)?; - read_file(source, &definition.wire_name, &request, BYTE_CAP) + read_file(source, &definition.wire_name, &request, BYTE_CAP).await } /// Reads the file `request` names, in the window it asks for, with at /// most `cap` bytes of numbered lines. `tool` is the name the model /// called the tool by. -fn read_file( +async fn read_file( source: &impl Source, tool: &str, request: &Request<'_>, @@ -55,17 +55,7 @@ fn read_file( ) -> Result { let path = request.path; let message = |text: String| ToolError::new(ToolErrorKind::Other, text); - let failed = |error: FileError| message(refusal(tool, path, &error)); - let stat = source.stat(path).map_err(failed)?; - check_type(path, stat.file_type).map_err(message)?; - let bytes = source - .read_prefix(path, MAX_FILE_BYTES + 1) - .map_err(failed)?; - if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > MAX_FILE_BYTES { - return Err(message(format!( - "File is too large to read: {path} is over the limit of {MAX_FILE_BYTES} bytes." - ))); - } + let bytes = load(source, tool, path).await.map_err(message)?; if sniff_binary(&bytes) { return Err(message(format!( "File content is binary data, not text: {path}" @@ -89,14 +79,43 @@ fn read_file( ))) } -/// Decides from the kind of node at `path` whether Read goes on: a file -/// or a link does, and anything else gets the sentence that says why not. +/// The bytes of the file at `path`, for a tool that works on a file's +/// text: Read, and StrReplace, which edits what Read shows. `tool` is the +/// name the model called the tool by. +/// +/// The stat comes first, so a directory and a special file are refused +/// and never opened. The read stops one byte past the ceiling, so a file +/// over it is refused and never held whole. +/// +/// # Errors +/// Returns the sentence a model reads when the path is missing, names a +/// directory or a special file, holds more than [`MAX_FILE_BYTES`] bytes, +/// or cannot be read. +pub(crate) async fn load(source: &impl Source, tool: &str, path: &str) -> Result, String> { + let failed = |error: FileError| refusal(tool, path, &error); + let stat = source.stat(path).await.map_err(failed)?; + check_type(path, stat.file_type)?; + let bytes = source + .read_prefix(path, MAX_FILE_BYTES + 1) + .await + .map_err(failed)?; + if u64::try_from(bytes.len()).unwrap_or(u64::MAX) > MAX_FILE_BYTES { + return Err(format!( + "File is too large to read: {path} is over the limit of {MAX_FILE_BYTES} bytes." + )); + } + Ok(bytes) +} + +/// Decides from the kind of node at `path` whether its bytes are read: a +/// file or a link is read, and anything else gets the sentence that says +/// why not. fn check_type(path: &str, file_type: FileType) -> Result<(), String> { match file_type { FileType::File | FileType::Symlink => Ok(()), - FileType::Directory => Err(format!("Path is a directory, not a file: {path}")), + FileType::Directory => Err(is_a_directory(path)), // A pipe, a socket, or a device, and any kind added later: none - // of them is text Read can window. + // of them holds text, and a read of one can block for good. _ => Err(neither_file_nor_directory(path)), } } diff --git a/crates/plugin-std/src/read/tests.rs b/crates/plugin-std/src/read/tests.rs index 6f24d1e..d5da8e3 100644 --- a/crates/plugin-std/src/read/tests.rs +++ b/crates/plugin-std/src/read/tests.rs @@ -13,6 +13,7 @@ use runvil_plugin_sdk::{ToolError, ToolOutput}; use serde_json::Value; use super::args::Request; +use crate::fake::block_on; use crate::source::Source; use crate::spec::{self, Definition}; @@ -34,7 +35,7 @@ fn definition() -> &'static Definition { fn read(files: &impl Source, args: &Value) -> Result { let definition = definition(); crate::check::check(&definition.wire_name, &definition.parameters, args)?; - super::call(files, definition, args) + block_on(super::call(files, definition, args)) } /// Reads `path` with the window `offset` and `limit` under the byte cap @@ -51,7 +52,7 @@ fn read_capped( offset, limit, }; - super::read_file(files, "Read", &request, cap) + block_on(super::read_file(files, "Read", &request, cap)) } /// The text of a successful read, which must be untrusted output. diff --git a/crates/plugin-std/src/refusal.rs b/crates/plugin-std/src/refusal.rs index cf08e87..0d0b5df 100644 --- a/crates/plugin-std/src/refusal.rs +++ b/crates/plugin-std/src/refusal.rs @@ -12,14 +12,14 @@ use runvil_plugin_sdk::{FileError, FileErrorKind}; /// The model-readable sentence for `error`, from the tool called `tool` /// (the name the model uses) on `path` (as the model wrote it). /// -/// A sentence names no tool other than `tool`. A read the run's policy -/// denies, and a failure the contract has no kind for, read as the Host's -/// own words alone. An I/O failure reads as the path and then the Host's -/// words. +/// A sentence names no tool other than `tool`. An operation the run's +/// policy denies, and a failure of a kind that has no sentence here, read +/// as the Host's own words alone. An I/O failure reads as the path and +/// then the Host's words. pub(crate) fn refusal(tool: &str, path: &str, error: &FileError) -> String { match error.kind() { FileErrorKind::NotFound => format!("File not found: {path}"), - FileErrorKind::IsADirectory => format!("Path is a directory, not a file: {path}"), + FileErrorKind::IsADirectory => is_a_directory(path), FileErrorKind::NotADirectory => not_a_directory(path), FileErrorKind::Conflict => format!( "{path} was changed, or is being changed, by another call in this round, so it \ @@ -30,6 +30,22 @@ pub(crate) fn refusal(tool: &str, path: &str, error: &FileError) -> String { } } +/// The model-readable sentence for `error`, from a write that the tool +/// called `tool` made to `path` (as the model wrote it). +/// +/// A write needs a directory only on the way to its file, so a failure +/// for something that is not a directory is about a parent of `path`, +/// where [`refusal`] would say that `path` itself is not a directory. +/// Every other failure reads as [`refusal`] words it. +pub(crate) fn write_refusal(tool: &str, path: &str, error: &FileError) -> String { + match error.kind() { + FileErrorKind::NotADirectory => { + format!("Path has a parent that is not a directory: {path}") + } + _ => refusal(tool, path, error), + } +} + /// The sentence for a root the model named that does not exist. /// /// A tool that starts from a directory words its own missing root, because @@ -38,6 +54,12 @@ pub(crate) fn missing_root(path: &str) -> String { format!("Path does not exist: {path}") } +/// The sentence for a path that names a directory where a file was +/// needed. +pub(crate) fn is_a_directory(path: &str) -> String { + format!("Path is a directory, not a file: {path}") +} + /// The sentence for a path that names something other than a directory /// where a directory was needed. pub(crate) fn not_a_directory(path: &str) -> String { diff --git a/crates/plugin-std/src/refusal/tests.rs b/crates/plugin-std/src/refusal/tests.rs index 336c5af..fef173c 100644 --- a/crates/plugin-std/src/refusal/tests.rs +++ b/crates/plugin-std/src/refusal/tests.rs @@ -3,7 +3,10 @@ use runvil_plugin_sdk::{FileError, FileErrorKind}; -use super::{missing_root, neither_file_nor_directory, not_a_directory, refusal}; +use super::{ + is_a_directory, missing_root, neither_file_nor_directory, not_a_directory, refusal, + write_refusal, +}; /// The path the model wrote, and the resolved path every error text /// below names, which differs so a test can tell which one a sentence @@ -95,6 +98,22 @@ fn a_failure_of_no_other_kind_reads_as_the_hosts_words() { } } +#[test] +fn a_failure_of_a_kind_that_only_a_change_has_reads_as_the_hosts_words() { + for (kind, text) in [ + ( + FileErrorKind::AlreadyExists, + "already exists: /resolved/a.md", + ), + ( + FileErrorKind::NotEmpty, + "directory not empty: /resolved/a.md", + ), + ] { + assert_eq!(say(&FileError::new(kind, text)), text, "{kind:?}"); + } +} + #[test] fn a_relative_path_is_echoed_as_written_and_never_as_the_resolved_one() { let error = FileError::new(FileErrorKind::NotFound, "not found: /notes/a.md"); @@ -123,6 +142,35 @@ fn no_message_names_a_tool_other_than_the_one_called() { assert!(!neither_file_nor_directory("p").contains("Shell")); } +#[test] +fn a_write_under_something_that_is_not_a_directory_says_that_a_parent_is_not_one() { + assert_eq!( + write_refusal("Write", WRITTEN, &error(FileErrorKind::NotADirectory)), + "Path has a parent that is not a directory: notes/a.md" + ); +} + +#[test] +fn every_other_failure_of_a_write_reads_as_the_shared_sentence() { + for kind in [ + FileErrorKind::NotFound, + FileErrorKind::IsADirectory, + FileErrorKind::Conflict, + FileErrorKind::Io, + FileErrorKind::Denied, + FileErrorKind::AlreadyExists, + FileErrorKind::NotEmpty, + FileErrorKind::Other, + ] { + let error = error(kind); + assert_eq!( + write_refusal("Write", WRITTEN, &error), + refusal("Write", WRITTEN, &error), + "{kind:?}" + ); + } +} + #[test] fn a_root_that_does_not_exist_says_the_path_does_not_exist() { assert_eq!( @@ -144,6 +192,18 @@ fn a_missing_root_is_worded_apart_from_a_missing_file() { assert_eq!(missing_root(WRITTEN), "Path does not exist: notes/a.md"); } +#[test] +fn the_is_a_directory_sentence_is_the_one_the_refusal_gives() { + assert_eq!( + say(&error(FileErrorKind::IsADirectory)), + is_a_directory(WRITTEN) + ); + assert_eq!( + is_a_directory("/a/b"), + "Path is a directory, not a file: /a/b" + ); +} + #[test] fn the_not_a_directory_sentence_is_the_one_the_refusal_gives() { assert_eq!( diff --git a/crates/plugin-std/src/replace-tests.rs b/crates/plugin-std/src/replace-tests.rs new file mode 100644 index 0000000..cc0f059 --- /dev/null +++ b/crates/plugin-std/src/replace-tests.rs @@ -0,0 +1,495 @@ +//! Unit tests for the `StrReplace` tool: what an edit leaves in the file, +//! what it answers, how it counts the text to replace, and what it +//! refuses before it reads and before it writes. + +use runvil_plugin_sdk::testing::Files; +use runvil_plugin_sdk::{ + FileError, FileErrorKind, FileType, Stat, ToolError, ToolErrorKind, ToolOutput, +}; +use serde_json::{Value, json}; + +use super::edited_len; +use crate::fake::{FakeSource, Node, block_on}; +use crate::source::Source; +use crate::spec::{self, Definition}; + +/// The `replace` definition the Pack builds the tool from. +fn definition() -> &'static Definition { + spec::all() + .iter() + .find(|definition| definition.segment == "replace") + .expect("the replace definition exists") +} + +/// Calls StrReplace over `files` with `args` as the Pack does: the schema +/// check first, then the tool. +fn replace(files: &impl Source, args: &Value) -> Result { + let definition = definition(); + crate::check::check(&definition.wire_name, &definition.parameters, args)?; + block_on(super::call(files, definition, args)) +} + +/// Replaces `old` with `new` in the file at `path`, where `old` must +/// occur once. +fn edit(files: &impl Source, path: &str, old: &str, new: &str) -> Result { + replace( + files, + &json!({ "path": path, "old_string": old, "new_string": new }), + ) +} + +/// Replaces every `old` with `new` in the file at `path`. +fn edit_all( + files: &impl Source, + path: &str, + old: &str, + new: &str, +) -> Result { + replace( + files, + &json!({ "path": path, "old_string": old, "new_string": new, "replace_all": true }), + ) +} + +/// The whole contents of the file at `path`. +fn contents(files: &Files, path: &str) -> Vec { + files.read(path, 0, u64::MAX).expect("the file is there") +} + +/// The text of a successful edit, which must be trusted output. +fn text_of(result: Result) -> String { + let output = result.expect("the edit succeeds"); + assert!(output.is_trusted(), "{}", output.text()); + output.text().to_owned() +} + +/// The message of a failed edit, which must not be an invalid-arguments +/// failure. +fn failure_of(result: Result) -> String { + match result { + Ok(output) => panic!("the edit fails, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::Other, "{error}"); + error.to_string() + } + } +} + +/// The message of an edit whose arguments are refused. +fn refused(result: Result) -> String { + match result { + Ok(output) => panic!("the call is refused, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments, "{error}"); + error.to_string() + } + } +} + +#[test] +fn the_new_text_takes_the_place_of_the_one_occurrence_and_the_rest_of_the_file_stays() { + let files = Files::new().file("/a.md", "one\ntwo\nthree\n"); + assert_eq!( + text_of(edit(&files, "/a.md", "two", "2")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/a.md"), b"one\n2\nthree\n"); +} + +#[test] +fn an_old_string_may_span_lines_and_the_new_string_may_be_empty() { + let files = Files::new().file("/a.md", "one\ntwo\nthree\n"); + assert!(edit(&files, "/a.md", "one\ntwo\n", "").is_ok()); + assert_eq!(contents(&files, "/a.md"), b"three\n"); +} + +#[test] +fn replace_all_replaces_every_occurrence_and_counts_them() { + let files = Files::new().file("/a.rs", "let x = x + x;\n"); + assert_eq!( + text_of(edit_all(&files, "/a.rs", "x", "total")), + "Made 3 replacements." + ); + assert_eq!(contents(&files, "/a.rs"), b"let total = total + total;\n"); +} + +#[test] +fn replace_all_with_one_occurrence_replaces_it() { + let files = Files::new().file("/a.md", "one two\n"); + assert_eq!( + text_of(edit_all(&files, "/a.md", "two", "2")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/a.md"), b"one 2\n"); +} + +#[test] +fn an_old_string_that_occurs_more_than_once_fails_with_the_count_and_changes_nothing() { + let files = Files::new().file("/a.rs", "let x = x + x;\n"); + let before = files.clone(); + assert_eq!( + failure_of(edit(&files, "/a.rs", "x", "total")), + "`old_string` occurs 3 times in /a.rs, and it must occur exactly once. Add text around \ + it until it names one occurrence, or set `replace_all` to replace every one." + ); + assert_eq!(files, before); +} + +#[test] +fn an_old_string_that_is_absent_fails_with_the_count_and_changes_nothing() { + let files = Files::new().file("/a.md", "one\ntwo\n"); + let before = files.clone(); + assert_eq!( + failure_of(edit(&files, "/a.md", "three", "3")), + "`old_string` occurs 0 times in /a.md, and it must occur exactly once. It is matched \ + exactly, so whitespace and line endings count." + ); + assert_eq!( + failure_of(edit_all(&files, "/a.md", "three", "3")), + "`old_string` occurs 0 times in /a.md, and it must occur at least once. It is matched \ + exactly, so whitespace and line endings count." + ); + assert_eq!(files, before); +} + +#[test] +fn replace_all_that_is_false_or_null_needs_one_occurrence() { + let files = Files::new().file("/a.md", "x x\n"); + for flag in [json!(false), json!(null)] { + let args = json!({ + "path": "/a.md", "old_string": "x", "new_string": "y", "replace_all": flag + }); + assert!( + failure_of(replace(&files, &args)).starts_with("`old_string` occurs 2 times"), + "{args}" + ); + } +} + +#[test] +fn the_match_is_exact_in_case_whitespace_and_line_endings() { + let files = Files::new().file("/a.txt", "Alpha\r\n beta\r\n"); + for miss in ["alpha", " beta\r\n ", "Alpha\n beta"] { + assert!( + failure_of(edit(&files, "/a.txt", miss, "x")) + .starts_with("`old_string` occurs 0 times"), + "{miss:?}" + ); + } + assert!(edit(&files, "/a.txt", "Alpha\r\n beta", "gamma").is_ok()); + assert_eq!(contents(&files, "/a.txt"), b"gamma\r\n"); +} + +#[test] +fn a_byte_order_mark_and_the_line_endings_stay_as_they_are() { + let files = Files::new().file("/a.txt", "\u{feff}one\r\ntwo\r\n"); + assert!(edit(&files, "/a.txt", "two", "2").is_ok()); + assert_eq!( + contents(&files, "/a.txt"), + "\u{feff}one\r\n2\r\n".as_bytes() + ); +} + +#[test] +fn the_text_put_in_is_not_searched_again() { + let files = Files::new().file("/a.txt", "a a"); + assert_eq!( + text_of(edit_all(&files, "/a.txt", "a", "aa")), + "Made 2 replacements." + ); + assert_eq!(contents(&files, "/a.txt"), b"aa aa"); +} + +#[test] +fn replace_all_replaces_the_occurrences_that_do_not_overlap_from_the_start_of_the_file() { + let files = Files::new() + .file("/a.txt", "aaaaa") + .file("/b.txt", "banana"); + assert_eq!( + text_of(edit_all(&files, "/a.txt", "aa", "b")), + "Made 2 replacements." + ); + assert_eq!(contents(&files, "/a.txt"), b"bba"); + assert_eq!( + text_of(edit_all(&files, "/b.txt", "ana", "X")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/b.txt"), b"bXna"); +} + +#[test] +fn an_old_string_that_starts_at_two_places_that_overlap_is_refused_and_changes_nothing() { + let files = Files::new() + .file("/a.txt", "aaa") + .file("/b.txt", "banana") + .file("/c.txt", "\u{e9}\u{e9}\u{e9}"); + let before = files.clone(); + for (path, old) in [ + ("/a.txt", "aa"), + ("/b.txt", "ana"), + ("/c.txt", "\u{e9}\u{e9}"), + ] { + assert_eq!( + failure_of(edit(&files, path, old, "X")), + format!( + "`old_string` starts at more than one place in {path}, in occurrences that \ + overlap, and it must occur exactly once. Add text around it until it names one \ + occurrence." + ), + "{old:?}" + ); + } + assert_eq!(files, before); +} + +#[test] +fn more_text_around_an_old_string_that_overlaps_itself_names_one_occurrence() { + let files = Files::new().file("/b.txt", "banana"); + assert_eq!( + text_of(edit(&files, "/b.txt", "bana", "X")), + "Made 1 replacement." + ); + assert_eq!(contents(&files, "/b.txt"), b"Xna"); +} + +#[test] +fn a_file_that_is_not_utf8_is_refused_and_stays_as_it_is() { + let mut utf16 = vec![0xFF, 0xFE]; + for unit in "one\n".encode_utf16() { + utf16.extend_from_slice(&unit.to_le_bytes()); + } + let files = Files::new() + .file("/latin.txt", b"caf\xE9 one\n") + .file("/utf16.txt", &utf16); + let before = files.clone(); + for path in ["/latin.txt", "/utf16.txt"] { + assert_eq!( + failure_of(edit(&files, path, "one", "1")), + format!("File is not UTF-8 text, so it cannot be edited: {path}") + ); + } + assert_eq!(files, before); +} + +#[test] +fn a_missing_file_and_a_directory_fail_as_they_do_for_a_read() { + let files = Files::new().file("/dir/a.md", "x\n"); + assert_eq!( + failure_of(edit(&files, "/nope.md", "x", "y")), + "File not found: /nope.md" + ); + assert_eq!( + failure_of(edit(&files, "notes/a.md", "x", "y")), + "File not found: notes/a.md" + ); + assert_eq!( + failure_of(edit(&files, "/dir", "x", "y")), + "Path is a directory, not a file: /dir" + ); +} + +#[test] +fn a_pipe_is_refused_by_its_stat_and_never_read() { + // The fake fails a read of the pipe as not found, so this text shows + // that the edit stopped at the stat. + let source = FakeSource::default().with("/pipe", Node::Pipe); + assert_eq!( + failure_of(edit(&source, "/pipe", "x", "y")), + "Path is neither a file nor a directory: /pipe" + ); +} + +#[test] +fn a_link_is_read_through_and_a_link_to_a_directory_is_a_directory() { + let source = FakeSource::default() + .with("/filelink", Node::LinkToFile(b"one two\n".to_vec())) + .with("/dirlink", Node::Link); + // The fake takes no change, so this text shows that the edit read + // the link's file, found its one match, and asked for the write. + assert_eq!( + failure_of(edit(&source, "/filelink", "two", "2")), + "the fake tree takes no change: /filelink" + ); + assert_eq!( + failure_of(edit(&source, "/dirlink", "two", "2")), + "Path is a directory, not a file: /dirlink" + ); +} + +#[test] +fn a_file_over_the_ceiling_is_refused_and_never_edited() { + let files = Files::new().file("/big.txt", vec![b'a'; 16_777_217]); + assert_eq!( + failure_of(edit_all(&files, "/big.txt", "a", "b")), + "File is too large to read: /big.txt is over the limit of 16777216 bytes." + ); + assert_eq!( + files.read("/big.txt", 0, 4), + Ok(b"aaaa".to_vec()), + "the file stays as it was" + ); +} + +#[test] +fn an_edit_that_grows_the_file_past_one_write_is_refused_and_one_at_the_limit_is_written() { + let mut text = String::from("X"); + text.push_str(&"a".repeat(16_777_215)); + let files = Files::new().file("/edge.txt", &text); + assert_eq!( + failure_of(edit(&files, "/edge.txt", "X", "XY")), + "The edit would leave /edge.txt with 16777217 bytes, and one write takes at most \ + 16777216 bytes." + ); + assert_eq!(files.read("/edge.txt", 0, 2), Ok(b"Xa".to_vec())); + assert!(edit(&files, "/edge.txt", "X", "Y").is_ok()); + assert_eq!(files.read("/edge.txt", 0, 2), Ok(b"Ya".to_vec())); + assert_eq!( + files.stat("/edge.txt"), + Ok(Stat::new(FileType::File, 16_777_216)) + ); +} + +#[test] +fn an_edit_far_past_one_write_is_refused_from_the_count_before_it_is_built() { + // Each of the 1 MiB of matches would become 16 MiB, which is 16 TiB + // in all. No machine holds a text of that length, so a call that + // built the edited text before it checked the length could not + // answer. + let files = Files::new().file("/wide.txt", "a".repeat(1_048_576)); + let wide = 1_048_576_usize.saturating_mul(16_777_216); + assert_eq!( + failure_of(edit_all(&files, "/wide.txt", "a", &"b".repeat(16_777_216))), + format!( + "The edit would leave /wide.txt with {wide} bytes, and one write takes at most \ + 16777216 bytes." + ) + ); + assert_eq!( + files.read("/wide.txt", 0, 4), + Ok(b"aaaa".to_vec()), + "the file stays as it was" + ); +} + +#[test] +fn the_length_of_an_edit_follows_from_the_count_of_its_matches() { + for (text, old, new) in [ + ("x x x", "x", "yy"), + ("x x x", "x ", ""), + ("aaa", "aa", "b"), + ("caf\u{e9} caf\u{e9}", "\u{e9}", "e"), + ] { + let count = text.matches(old).count(); + assert_eq!( + edited_len(text.len(), count, old.len(), new.len()), + text.replace(old, new).len(), + "{text:?}: {old:?} to {new:?}" + ); + } + assert_eq!( + edited_len(usize::MAX, usize::MAX, 1, usize::MAX), + usize::MAX, + "a length past the range of usize is its largest value" + ); +} + +#[test] +fn a_read_the_policy_denies_fails_with_the_policys_own_reason() { + let reason = "Mode::Plan allows only markdown paths, and /secret.rs is not one"; + let files = Files::new().fails("/secret.rs", FileError::new(FileErrorKind::Denied, reason)); + assert_eq!(failure_of(edit(&files, "/secret.rs", "x", "y")), reason); + let source = FakeSource::default().with( + "/late.rs", + Node::ReadFails(FileError::new(FileErrorKind::Denied, reason)), + ); + assert_eq!(failure_of(edit(&source, "/late.rs", "x", "y")), reason); +} + +#[test] +fn a_write_the_host_fails_after_the_read_succeeded_is_worded_by_its_kind() { + let guarded = + |kind, text: &str| Node::Guarded(b"one two\n".to_vec(), FileError::new(kind, text)); + let reason = "Mode::Ask allows no write of /ask.md"; + let source = FakeSource::default() + .with("/ask.md", guarded(FileErrorKind::Denied, reason)) + .with( + "/disk.md", + guarded(FileErrorKind::Io, "storage full: no space left"), + ); + assert_eq!(failure_of(edit(&source, "/ask.md", "two", "2")), reason); + assert_eq!( + failure_of(edit(&source, "/disk.md", "two", "2")), + "I/O failure on /disk.md: storage full: no space left" + ); +} + +#[test] +fn a_missing_parameter_or_one_of_the_wrong_type_names_the_parameter() { + let files = Files::new(); + assert_eq!( + refused(replace( + &files, + &json!({ "path": "/a.md", "old_string": "x" }) + )), + "std_StrReplace: `new_string` is required, and the call left it out" + ); + assert_eq!( + refused(replace( + &files, + &json!({ + "path": "/a.md", "old_string": "x", "new_string": "y", "replace_all": "yes" + }) + )), + "std_StrReplace: `replace_all` must be a JSON boolean, and the call passed \"yes\"" + ); +} + +#[test] +fn an_undeclared_key_is_refused_and_the_parameters_are_named() { + let files = Files::new(); + assert_eq!( + refused(replace( + &files, + &json!({ "path": "/a.md", "old_string": "x", "new_string": "y", "count": 2 }) + )), + "std_StrReplace: `count` is not a parameter of this tool. \ + The parameters are `new_string`, `old_string`, `path` and `replace_all`." + ); +} + +#[test] +fn an_empty_old_string_and_a_new_string_equal_to_it_are_refused_before_any_read() { + // No file is there, so a call that got as far as its read would say + // that the file was not found. + let files = Files::new(); + assert_eq!( + refused(edit(&files, "/a.md", "", "y")), + "std_StrReplace: `old_string` is empty. Pass the text to replace." + ); + assert_eq!( + refused(edit(&files, "/a.md", "same", "same")), + "std_StrReplace: `new_string` is the same as `old_string`, so the call would change \ + nothing" + ); +} + +#[test] +fn the_refusals_come_in_a_fixed_order() { + let files = Files::new(); + assert_eq!( + refused(replace( + &files, + &json!({ "path": " ", "old_string": "", "new_string": "", "all": true }) + )), + "std_StrReplace: `all` is not a parameter of this tool. \ + The parameters are `new_string`, `old_string`, `path` and `replace_all`." + ); + assert_eq!( + refused(edit(&files, " ", "", "")), + "std_StrReplace: `path` is empty or only whitespace, and the call passed \" \"" + ); + assert_eq!( + refused(edit(&files, "/a.md", "", "")), + "std_StrReplace: `old_string` is empty. Pass the text to replace." + ); +} diff --git a/crates/plugin-std/src/replace.rs b/crates/plugin-std/src/replace.rs new file mode 100644 index 0000000..6efed83 --- /dev/null +++ b/crates/plugin-std/src/replace.rs @@ -0,0 +1,193 @@ +//! The `StrReplace` tool: replaces a text in a file with another text. +//! +//! StrReplace reads the file as Read does, through the call's +//! [`Source`], so the run's policy applies and the same paths are +//! refused: a directory, a special file, and a file over 16 MiB. The file +//! must hold UTF-8. Nothing is decoded, and nothing outside the matches +//! changes, so a byte order mark and the line endings stay as they are. +//! The text to replace must occur exactly once, unless `replace_all` is +//! set, and a failure states how many times it occurs. A text that starts +//! at more than one place does not occur once, even where the places +//! overlap, and with `replace_all` the occurrences that do not overlap are +//! replaced, from the start of the file. An edit that would leave the file +//! longer than one write takes is refused from the count of matches, +//! before the edited text is built. +//! +//! The edit is a read and then a write, each a request to the Host of its +//! own. A change that another task makes to the file between the two is +//! lost, because the write holds the whole file as the read found it. +//! +//! The answer is fixed text and a count, so it is trusted output. + +use runvil_plugin_sdk::sys::RV_MAX_WRITE; +use runvil_plugin_sdk::{ToolError, ToolErrorKind, ToolOutput}; +use serde_json::Value; + +use crate::check::{make_invalid_arguments_error, plural, refuse_blank, refuse_unknown}; +use crate::refusal::write_refusal; +use crate::source::Source; +use crate::spec::Definition; + +/// What a call asks StrReplace for. +#[derive(Debug)] +struct Request<'a> { + /// The path as the model wrote it. + path: &'a str, + /// The text to replace, which is not empty. + old: &'a str, + /// The text that takes its place, which differs from `old`. + new: &'a str, + /// Whether the new text goes in at every occurrence. Otherwise the + /// text must occur exactly once. + all: bool, +} + +/// Runs one `StrReplace` call whose arguments already passed the shared +/// schema check. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter for a +/// bad argument, and a message error for any other failure, worded for a +/// model to read. Every refusal comes before the write, so it leaves the +/// file as it was. +pub(crate) async fn call( + source: &impl Source, + definition: &Definition, + args: &Value, +) -> Result { + let request = parse(definition, args)?; + let tool = definition.wire_name.as_str(); + let path = request.path; + let message = |text: String| ToolError::new(ToolErrorKind::Other, text); + let bytes = crate::read::load(source, tool, path) + .await + .map_err(message)?; + let Ok(text) = String::from_utf8(bytes) else { + return Err(message(format!( + "File is not UTF-8 text, so it cannot be edited: {path}" + ))); + }; + let count = text.matches(request.old).count(); + if count == 0 || (count > 1 && !request.all) { + return Err(message(miscount(path, count, request.all))); + } + // The count leaves out an occurrence that overlaps the one before + // it, so a text that is counted once can start at a second place. + if !request.all && starts_twice(&text, request.old) { + return Err(message(overlap(path))); + } + // The length of the edited text follows from the count, so an edit + // that is too long is refused before any of it is built. A call with + // `replace_all` could otherwise ask for far more memory than the + // file and its arguments hold. + let len = edited_len(text.len(), count, request.old.len(), request.new.len()); + if len > RV_MAX_WRITE { + return Err(message(format!( + "The edit would leave {path} with {len} bytes, and one write takes at most \ + {RV_MAX_WRITE} bytes." + ))); + } + let edited = text.replace(request.old, request.new); + source + .write(path, edited.into_bytes()) + .await + .map_err(|error| message(write_refusal(tool, path, &error)))?; + Ok(ToolOutput::trusted(format!( + "Made {}.", + plural(count, "replacement") + ))) +} + +/// Reads the call's arguments after the shared schema check. +/// +/// The order is fixed: an undeclared key, then a blank path, then an +/// empty `old_string`, then a `new_string` equal to it, so a call that +/// breaks two rules always hears about the same one. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter. +fn parse<'a>(definition: &Definition, args: &'a Value) -> Result, ToolError> { + let tool = definition.wire_name.as_str(); + refuse_unknown(tool, &definition.parameters, args)?; + let text = |name: &str| args.get(name).and_then(Value::as_str).unwrap_or_default(); + let path = text("path"); + refuse_blank(tool, "path", path)?; + let (old, new) = (text("old_string"), text("new_string")); + if old.is_empty() { + return Err(make_invalid_arguments_error( + tool, + "`old_string` is empty. Pass the text to replace.", + )); + } + if old == new { + return Err(make_invalid_arguments_error( + tool, + "`new_string` is the same as `old_string`, so the call would change nothing", + )); + } + let all = args + .get("replace_all") + .and_then(Value::as_bool) + .unwrap_or(false); + Ok(Request { + path, + old, + new, + all, + }) +} + +/// Whether `old` starts at more than one place in `text`. A second place +/// can lie inside the first occurrence, as `ana` starts at two places in +/// `banana`, and [`str::matches`] counts such a text once. +fn starts_twice(text: &str, old: &str) -> bool { + // The second search begins one character past the first place, so it + // also finds a place inside the first occurrence. + let step = old.chars().next().map_or(1, char::len_utf8); + text.find(old) + .and_then(|first| text.get(first + step..)) + .is_some_and(|rest| rest.contains(old)) +} + +/// The length in bytes of a text of `len` bytes once each of its `count` +/// matches, of `old` bytes, has given way to `new` bytes. The matches do +/// not overlap, so together they take up no more than `len` bytes. A +/// length past the range of `usize` is its largest value, which is over +/// every limit. +fn edited_len(len: usize, count: usize, old: usize, new: usize) -> usize { + len.saturating_sub(count.saturating_mul(old)) + .saturating_add(count.saturating_mul(new)) +} + +/// The sentence for a text to replace that occurs `count` times in the +/// file at `path`, where the call needs it once, or at least once when it +/// replaces `all`. +fn miscount(path: &str, count: usize, all: bool) -> String { + let occurs = format!("`old_string` occurs {} in {path}", plural(count, "time")); + if count == 0 { + let needed = if all { "at least once" } else { "exactly once" }; + format!( + "{occurs}, and it must occur {needed}. It is matched exactly, so whitespace and \ + line endings count." + ) + } else { + format!( + "{occurs}, and it must occur exactly once. Add text around it until it names one \ + occurrence, or set `replace_all` to replace every one." + ) + } +} + +/// The sentence for a text to replace that starts at more than one place +/// in the file at `path`, in occurrences that overlap, where the call +/// needs it once. +fn overlap(path: &str) -> String { + format!( + "`old_string` starts at more than one place in {path}, in occurrences that overlap, \ + and it must occur exactly once. Add text around it until it names one occurrence." + ) +} + +#[cfg(test)] +#[path = "replace-tests.rs"] +mod tests; diff --git a/crates/plugin-std/src/rm-tests.rs b/crates/plugin-std/src/rm-tests.rs new file mode 100644 index 0000000..6f78a38 --- /dev/null +++ b/crates/plugin-std/src/rm-tests.rs @@ -0,0 +1,209 @@ +//! Unit tests for the `Delete` tool: what a call removes, what it +//! refuses, what it answers, and how a failure of the Host reads. + +use runvil_plugin_sdk::testing::Files; +use runvil_plugin_sdk::{FileError, FileErrorKind, FileType, ToolError, ToolErrorKind, ToolOutput}; +use serde_json::{Value, json}; + +use super::deleted; +use crate::fake::{FakeSource, Node, block_on}; +use crate::source::Source; +use crate::spec::{self, Definition}; + +/// The `rm` definition the Pack builds the tool from. +fn definition() -> &'static Definition { + spec::all() + .iter() + .find(|definition| definition.segment == "rm") + .expect("the rm definition exists") +} + +/// Calls Delete over `files` with `args` as the Pack does: the schema +/// check first, then the tool. +fn delete(files: &impl Source, args: &Value) -> Result { + let definition = definition(); + crate::check::check(&definition.wire_name, &definition.parameters, args)?; + block_on(super::call(files, definition, args)) +} + +/// Deletes what is at `path` in `files`. +fn delete_at(files: &impl Source, path: &str) -> Result { + delete(files, &json!({ "path": path })) +} + +/// The text of a successful delete, which must be trusted output. +fn text_of(result: Result) -> String { + let output = result.expect("the delete succeeds"); + assert!(output.is_trusted(), "{}", output.text()); + output.text().to_owned() +} + +/// The message of a failed delete, which must not be an +/// invalid-arguments failure. +fn failure_of(result: Result) -> String { + match result { + Ok(output) => panic!("the delete fails, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::Other, "{error}"); + error.to_string() + } + } +} + +/// The message of a delete whose arguments are refused. +fn refused(result: Result) -> String { + match result { + Ok(output) => panic!("the call is refused, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments, "{error}"); + error.to_string() + } + } +} + +#[test] +fn a_delete_removes_the_file_and_leaves_what_is_beside_it() { + let files = Files::new() + .file("/notes/a.md", "one") + .file("/notes/b.md", "two"); + assert_eq!( + text_of(delete_at(&files, "/notes/a.md")), + "Deleted the file." + ); + assert_eq!(files, Files::new().file("/notes/b.md", "two")); +} + +#[test] +fn the_directory_that_held_the_file_stays() { + let files = Files::new().file("/notes/a.md", "one"); + assert!(delete_at(&files, "/notes/a.md").is_ok()); + assert_eq!(files, Files::new().dir("/notes")); +} + +#[test] +fn a_path_without_a_leading_slash_is_deleted_from_the_root() { + let files = Files::new().file("/notes/a.md", "one"); + assert!(delete_at(&files, "notes/a.md").is_ok()); + assert_eq!(files, Files::new().dir("/notes")); +} + +#[test] +fn a_missing_path_fails_with_the_not_found_text() { + let files = Files::new().file("/notes/a.md", "one"); + let before = files.clone(); + assert_eq!( + failure_of(delete_at(&files, "/nope.md")), + "File not found: /nope.md" + ); + assert_eq!( + failure_of(delete_at(&files, "notes/gone.md")), + "File not found: notes/gone.md" + ); + assert_eq!(files, before); +} + +#[test] +fn a_directory_is_refused_with_a_sentence_and_stays() { + let files = Files::new().file("/full/a.md", "one").dir("/empty"); + let before = files.clone(); + for directory in ["/full", "/empty", "empty", "/"] { + assert_eq!( + failure_of(delete_at(&files, directory)), + format!("Path is a directory, not a file: {directory}") + ); + } + assert_eq!(files, before); +} + +#[test] +fn a_file_a_link_and_a_pipe_all_get_as_far_as_the_removal() { + // The fake takes no change, so this text shows that the call passed + // the stat and asked for the removal. + let source = FakeSource::default() + .file("/file", "x") + .with("/filelink", Node::LinkToFile(b"x".to_vec())) + .with("/dirlink", Node::Link) + .with("/pipe", Node::Pipe); + for path in ["/file", "/filelink", "/dirlink", "/pipe"] { + assert_eq!( + failure_of(delete_at(&source, path)), + format!("the fake tree takes no change: {path}") + ); + } +} + +#[test] +fn the_answer_says_that_what_a_link_leads_to_stays() { + assert_eq!(deleted(FileType::File), "Deleted the file."); + assert_eq!(deleted(FileType::Other), "Deleted the file."); + assert_eq!( + deleted(FileType::Symlink), + "Deleted the link. What it leads to stays." + ); +} + +#[test] +fn a_stat_the_policy_denies_fails_with_the_policys_own_reason_and_removes_nothing() { + let reason = "Mode::Ask allows no change of /vault.md"; + let files = Files::new().fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let before = files.clone(); + assert_eq!(failure_of(delete_at(&files, "/vault.md")), reason); + assert_eq!(files, before); +} + +#[test] +fn a_removal_the_host_fails_after_the_stat_succeeded_is_worded_by_its_kind() { + let guarded = |kind, text: &str| Node::Guarded(b"x".to_vec(), FileError::new(kind, text)); + let reason = "Mode::Ask allows no change of /ask.md"; + let source = FakeSource::default() + .with("/ask.md", guarded(FileErrorKind::Denied, reason)) + .with( + "/disk.md", + guarded(FileErrorKind::Io, "permission denied: access denied"), + ) + .with( + "/gone.md", + guarded(FileErrorKind::NotFound, "not found: /gone.md"), + ); + assert_eq!(failure_of(delete_at(&source, "/ask.md")), reason); + assert_eq!( + failure_of(delete_at(&source, "/disk.md")), + "I/O failure on /disk.md: permission denied: access denied" + ); + assert_eq!( + failure_of(delete_at(&source, "/gone.md")), + "File not found: /gone.md" + ); +} + +#[test] +fn a_missing_path_argument_or_one_of_the_wrong_type_names_the_parameter() { + let files = Files::new(); + assert_eq!( + refused(delete(&files, &json!({}))), + "std_Delete: `path` is required, and the call left it out" + ); + assert_eq!( + refused(delete(&files, &json!({ "path": ["/a.md"] }))), + "std_Delete: `path` must be a JSON string, and the call passed [\"/a.md\"]" + ); +} + +#[test] +fn an_undeclared_key_is_refused_before_a_blank_path() { + let files = Files::new().file("/a.md", "one"); + let before = files.clone(); + assert_eq!( + refused(delete(&files, &json!({ "path": " ", "recursive": true }))), + "std_Delete: `recursive` is not a parameter of this tool. The parameters are `path`." + ); + for blank in ["", " ", "\t\n"] { + assert_eq!( + refused(delete_at(&files, blank)), + format!( + "std_Delete: `path` is empty or only whitespace, and the call passed \"{blank}\"" + ) + ); + } + assert_eq!(files, before); +} diff --git a/crates/plugin-std/src/rm.rs b/crates/plugin-std/src/rm.rs new file mode 100644 index 0000000..f40eeef --- /dev/null +++ b/crates/plugin-std/src/rm.rs @@ -0,0 +1,60 @@ +//! The `Delete` tool: removes one file. +//! +//! Delete asks what the path names and then asks for its removal, both +//! through the call's [`Source`], so the run's policy applies. The stat +//! comes first because the removal the Host offers also takes a +//! directory with no entries, and Delete removes no directory: it +//! refuses one with a sentence. The two are requests of their own, so a +//! directory with no entries that another task puts at the path between +//! them is removed. A link goes as a link, so what it leads to stays. The +//! answer is fixed text, so it is trusted output. + +use runvil_plugin_sdk::{FileError, FileType, ToolError, ToolErrorKind, ToolOutput}; +use serde_json::Value; + +use crate::check::{refuse_blank, refuse_unknown}; +use crate::refusal::{is_a_directory, refusal}; +use crate::source::Source; +use crate::spec::Definition; + +/// Runs one `Delete` call whose arguments already passed the shared +/// schema check. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter for a +/// bad argument, and a message error for any other failure, worded for a +/// model to read: nothing is at the path, the path names a directory, or +/// the Host fails the stat or the removal. +pub(crate) async fn call( + source: &impl Source, + definition: &Definition, + args: &Value, +) -> Result { + let tool = definition.wire_name.as_str(); + refuse_unknown(tool, &definition.parameters, args)?; + let path = args.get("path").and_then(Value::as_str).unwrap_or_default(); + refuse_blank(tool, "path", path)?; + let message = |text: String| ToolError::new(ToolErrorKind::Other, text); + let failed = |error: FileError| message(refusal(tool, path, &error)); + let stat = source.stat(path).await.map_err(failed)?; + if stat.file_type == FileType::Directory { + return Err(message(is_a_directory(path))); + } + source.remove(path).await.map_err(failed)?; + Ok(ToolOutput::trusted(deleted(stat.file_type))) +} + +/// What a call answers after it removed something of `file_type`. A link +/// goes as a link, so the answer says that what it leads to stays. A +/// pipe, a socket, or a device goes as a file does. +fn deleted(file_type: FileType) -> &'static str { + if file_type == FileType::Symlink { + "Deleted the link. What it leads to stays." + } else { + "Deleted the file." + } +} + +#[cfg(test)] +#[path = "rm-tests.rs"] +mod tests; diff --git a/crates/plugin-std/src/source.rs b/crates/plugin-std/src/source.rs index ca243f7..46f5c54 100644 --- a/crates/plugin-std/src/source.rs +++ b/crates/plugin-std/src/source.rs @@ -1,63 +1,86 @@ //! The file operations the tools need, behind a trait. //! //! The call's [`ToolCall`] implements it, so every operation a tool -//! performs goes through the Host, and the run's policy applies. The seam -//! exists so that a test can run a tool's own code over a tree it builds: -//! the SDK's `testing::Files`, or this crate's `FakeSource` for what that -//! tree cannot hold, such as a link, a pipe, and a read that fails after -//! the stat succeeded. +//! performs goes through the Host, and the run's policy applies. Each +//! method is async, because the Host answers a file operation in a later +//! step of the call: awaiting one ends the step. The seam exists so that +//! a test can run a tool's own code over a tree it builds: the SDK's +//! `testing::Files`, or this crate's `FakeSource` for what that tree +//! cannot hold, such as a link, a pipe, and a read that fails after the +//! stat succeeded. Both answer at once, so a test polls a tool's future +//! to its end with no Host around it. use runvil_plugin_sdk::{DirEntry, FileError, Stat, ToolCall}; -/// Where a tool reads the run's files from. +/// Where a tool reaches the run's files. pub(crate) trait Source { /// Metadata for `path`, without following a link. - fn stat(&self, path: &str) -> Result; + async fn stat(&self, path: &str) -> Result; /// The entries of the directory at `path`, in no promised order. - fn list(&self, path: &str) -> Result, FileError>; + async fn list(&self, path: &str) -> Result, FileError>; - /// The whole contents of the file at `path`. - fn read(&self, path: &str) -> Result, FileError>; + /// At most the first `len` bytes of the file at `path`. It is the one + /// read there is: a tool asks for one byte more than the largest file + /// it takes, so a longer file shows as such and is never held whole, + /// whatever a stat or a listing said of its size. + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError>; - /// At most the first `len` bytes of the file at `path`, for a path - /// whose size is not known beforehand. - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError>; + /// Writes `bytes` as the whole contents of the file at `path`. The + /// file is made when it is absent, with each directory on the way to + /// it. + async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError>; + + /// Removes what is at `path`: a file, a link, or a directory with no + /// entries. A link goes as a link, and what it leads to stays. + async fn remove(&self, path: &str) -> Result<(), FileError>; } impl Source for ToolCall<'_> { - fn stat(&self, path: &str) -> Result { - ToolCall::stat(self, path) + async fn stat(&self, path: &str) -> Result { + ToolCall::stat(self, path).await + } + + async fn list(&self, path: &str) -> Result, FileError> { + ToolCall::list(self, path).await } - fn list(&self, path: &str) -> Result, FileError> { - ToolCall::list(self, path) + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + ToolCall::read_range(self, path, 0, len).await } - fn read(&self, path: &str) -> Result, FileError> { - ToolCall::read(self, path) + async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError> { + ToolCall::write(self, path, bytes).await } - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { - ToolCall::read_range(self, path, 0, len) + async fn remove(&self, path: &str) -> Result<(), FileError> { + ToolCall::remove(self, path, false).await } } #[cfg(test)] +#[expect( + clippy::unused_async_trait_impl, + reason = "the methods are async for a Host that answers in a later step, and a tree held in memory answers at once" +)] impl Source for runvil_plugin_sdk::testing::Files { - fn stat(&self, path: &str) -> Result { + async fn stat(&self, path: &str) -> Result { runvil_plugin_sdk::testing::Files::stat(self, path) } - fn list(&self, path: &str) -> Result, FileError> { + async fn list(&self, path: &str) -> Result, FileError> { runvil_plugin_sdk::testing::Files::list(self, path) } - fn read(&self, path: &str) -> Result, FileError> { - runvil_plugin_sdk::testing::Files::read(self, path, 0, u64::MAX) + async fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { + runvil_plugin_sdk::testing::Files::read(self, path, 0, len) } - fn read_prefix(&self, path: &str, len: u64) -> Result, FileError> { - runvil_plugin_sdk::testing::Files::read(self, path, 0, len) + async fn write(&self, path: &str, bytes: Vec) -> Result<(), FileError> { + runvil_plugin_sdk::testing::Files::write(self, path, bytes) + } + + async fn remove(&self, path: &str) -> Result<(), FileError> { + runvil_plugin_sdk::testing::Files::remove(self, path, false) } } diff --git a/crates/plugin-std/src/spec-tests.rs b/crates/plugin-std/src/spec-tests.rs index 9c5761e..cf9ff28 100644 --- a/crates/plugin-std/src/spec-tests.rs +++ b/crates/plugin-std/src/spec-tests.rs @@ -141,6 +141,99 @@ fn the_read_description_holds_the_limits_the_code_uses_and_no_unfilled_placehold } } +#[test] +fn the_write_description_holds_the_limit_of_one_write_and_states_what_the_tool_does() { + let definitions = all(); + let write = definitions + .iter() + .find(|definition| definition.segment == "write") + .expect("the write definition exists"); + let text = &write.description; + assert!( + text.contains("at most 16777216 bytes"), + "the limit of one write is named: {text}" + ); + assert!( + !text.contains("{write_limit}"), + "{{write_limit}} is filled in: {text}" + ); + for phrase in [ + "directories on the way", + "exactly as given", + "names a directory fails", + "one after another", + "so that you know what the write replaces", + ] { + assert!( + text.contains(phrase), + "the description names {phrase}: {text}" + ); + } + assert!( + !text.contains("never overwritten"), + "a read before a write protects no change that comes after it: {text}" + ); +} + +#[test] +fn the_replace_description_holds_both_byte_limits_and_states_what_the_tool_does() { + let definitions = all(); + let replace = definitions + .iter() + .find(|definition| definition.segment == "replace") + .expect("the replace definition exists"); + let text = &replace.description; + assert!( + text.contains("A file over 16777216 bytes is refused"), + "the file ceiling is named: {text}" + ); + assert!( + text.contains("with more than 16777216 bytes"), + "the limit of one write is named for the edited file: {text}" + ); + for placeholder in ["{file_ceiling}", "{write_limit}"] { + assert!( + !text.contains(placeholder), + "{placeholder} is filled in: {text}" + ); + } + for phrase in [ + "matched exactly", + "line endings", + "how many times it occurs", + "replaces every occurrence and needs at least one", + "a call without replace_all fails", + "replaces the ones that do not overlap, from the start of the file", + "UTF-8", + "one after another", + ] { + assert!( + text.contains(phrase), + "the description names {phrase}: {text}" + ); + } +} + +#[test] +fn the_rm_description_says_that_a_directory_fails_and_that_a_link_goes_as_a_link() { + let definitions = all(); + let rm = definitions + .iter() + .find(|definition| definition.segment == "rm") + .expect("the rm definition exists"); + let text = &rm.description; + for phrase in [ + "The path is a directory", + "A link is deleted as a link", + "one after another", + ] { + assert!( + text.contains(phrase), + "the description names {phrase}: {text}" + ); + } +} + #[test] fn the_dir_description_holds_the_body_cap_and_no_unfilled_placeholder() { let definitions = all(); diff --git a/crates/plugin-std/src/spec.rs b/crates/plugin-std/src/spec.rs index aafa6af..53cd174 100644 --- a/crates/plugin-std/src/spec.rs +++ b/crates/plugin-std/src/spec.rs @@ -90,6 +90,16 @@ fn fill(segment: &str, description: &str) -> String { "read" => description .replace("{byte_cap}", &crate::read::BYTE_CAP.to_string()) .replace("{file_ceiling}", &crate::text::MAX_FILE_BYTES.to_string()), + "write" => description.replace( + "{write_limit}", + &runvil_plugin_sdk::sys::RV_MAX_WRITE.to_string(), + ), + "replace" => description + .replace("{file_ceiling}", &crate::text::MAX_FILE_BYTES.to_string()) + .replace( + "{write_limit}", + &runvil_plugin_sdk::sys::RV_MAX_WRITE.to_string(), + ), "dir" => description.replace("{body_cap}", &crate::text::BODY_CAP.to_string()), "grep" => description .replace("{body_cap}", &crate::text::BODY_CAP.to_string()) diff --git a/crates/plugin-std/src/write-tests.rs b/crates/plugin-std/src/write-tests.rs new file mode 100644 index 0000000..2b95ac1 --- /dev/null +++ b/crates/plugin-std/src/write-tests.rs @@ -0,0 +1,275 @@ +//! Unit tests for the `Write` tool: what a write leaves in the files, +//! what it answers, and what it refuses before and after it asks for the +//! write. + +use runvil_plugin_sdk::testing::Files; +use runvil_plugin_sdk::{ + FileError, FileErrorKind, FileType, Stat, ToolError, ToolErrorKind, ToolOutput, +}; +use serde_json::{Value, json}; + +use crate::fake::{FakeSource, block_on}; +use crate::source::Source; +use crate::spec::{self, Definition}; + +/// The `write` definition the Pack builds the tool from. +fn definition() -> &'static Definition { + spec::all() + .iter() + .find(|definition| definition.segment == "write") + .expect("the write definition exists") +} + +/// Calls Write over `files` with `args` as the Pack does: the schema +/// check first, then the tool. +fn write(files: &impl Source, args: &Value) -> Result { + let definition = definition(); + crate::check::check(&definition.wire_name, &definition.parameters, args)?; + block_on(super::call(files, definition, args)) +} + +/// Writes `contents` to `path` in `files`. +fn write_to(files: &impl Source, path: &str, contents: &str) -> Result { + write(files, &json!({ "path": path, "contents": contents })) +} + +/// The whole contents of the file at `path`. +fn contents(files: &Files, path: &str) -> Vec { + files.read(path, 0, u64::MAX).expect("the file is there") +} + +/// The text of a successful write, which must be trusted output. +fn text_of(result: Result) -> String { + let output = result.expect("the write succeeds"); + assert!(output.is_trusted(), "{}", output.text()); + output.text().to_owned() +} + +/// The message of a failed write, which must not be an +/// invalid-arguments failure. +fn failure_of(result: Result) -> String { + match result { + Ok(output) => panic!("the write fails, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::Other, "{error}"); + error.to_string() + } + } +} + +/// The message of a write whose arguments are refused. +fn refused(result: Result) -> String { + match result { + Ok(output) => panic!("the call is refused, but it answered {:?}", output.text()), + Err(error) => { + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments, "{error}"); + error.to_string() + } + } +} + +#[test] +fn a_write_makes_a_file_and_every_directory_on_the_way_to_it() { + let files = Files::new(); + assert_eq!( + text_of(write_to(&files, "/notes/deep/a.md", "one\ntwo\n")), + "Wrote 8 bytes." + ); + assert_eq!(contents(&files, "/notes/deep/a.md"), b"one\ntwo\n"); + assert_eq!( + files.stat("/notes/deep"), + Ok(Stat::new(FileType::Directory, 0)) + ); +} + +#[test] +fn a_write_replaces_the_whole_contents_of_a_file() { + let files = Files::new().file("/a.md", "a long first version\n"); + assert_eq!( + text_of(write_to(&files, "/a.md", "short")), + "Wrote 5 bytes." + ); + assert_eq!(contents(&files, "/a.md"), b"short"); +} + +#[test] +fn the_contents_are_written_exactly_as_given() { + let files = Files::new(); + let text = "caf\u{e9}\r\n\ttab, no final newline"; + assert!(write_to(&files, "/a.txt", text).is_ok()); + assert_eq!(contents(&files, "/a.txt"), text.as_bytes()); +} + +#[test] +fn the_answer_counts_the_bytes_written_and_not_the_characters() { + let files = Files::new(); + assert_eq!(text_of(write_to(&files, "/none", "")), "Wrote 0 bytes."); + assert_eq!(contents(&files, "/none"), b""); + assert_eq!(text_of(write_to(&files, "/one", "a")), "Wrote 1 byte."); + assert_eq!( + text_of(write_to(&files, "/two", "\u{e9}")), + "Wrote 2 bytes." + ); +} + +#[test] +fn a_path_without_a_leading_slash_is_written_from_the_root() { + let files = Files::new(); + assert!(write_to(&files, "notes/a.md", "x").is_ok()); + assert_eq!(contents(&files, "/notes/a.md"), b"x"); +} + +#[test] +fn contents_over_the_limit_of_one_write_are_refused_by_name_and_nothing_is_written() { + let files = Files::new(); + let over = "a".repeat(16_777_217); + assert_eq!( + refused(write_to(&files, "/big.txt", &over)), + "std_Write: `contents` is 16777217 bytes, and one write takes at most 16777216 bytes" + ); + assert_eq!(files, Files::new()); +} + +#[test] +fn contents_exactly_at_the_limit_are_written() { + let files = Files::new(); + let most = "a".repeat(16_777_216); + assert_eq!( + text_of(write_to(&files, "/edge.txt", &most)), + "Wrote 16777216 bytes." + ); + assert_eq!( + files.stat("/edge.txt"), + Ok(Stat::new(FileType::File, 16_777_216)) + ); +} + +#[test] +fn a_path_that_names_a_directory_fails_with_the_directory_text() { + let files = Files::new().file("/notes/a.md", "x"); + let before = files.clone(); + assert_eq!( + failure_of(write_to(&files, "/notes", "y")), + "Path is a directory, not a file: /notes" + ); + assert_eq!( + failure_of(write_to(&files, "/", "y")), + "Path is a directory, not a file: /" + ); + assert_eq!(files, before); +} + +#[test] +fn a_path_under_a_file_fails_saying_that_a_parent_is_not_a_directory() { + let files = Files::new().file("/a.md", "x"); + let before = files.clone(); + assert_eq!( + failure_of(write_to(&files, "/a.md/b.md", "y")), + "Path has a parent that is not a directory: /a.md/b.md" + ); + assert_eq!(files, before); +} + +#[test] +fn a_failure_echoes_the_path_as_the_model_wrote_it() { + let files = Files::new().file("/notes/a.md", "x"); + assert_eq!( + failure_of(write_to(&files, "notes", "y")), + "Path is a directory, not a file: notes" + ); + assert_eq!( + failure_of(write_to(&files, "notes/a.md/b", "y")), + "Path has a parent that is not a directory: notes/a.md/b" + ); +} + +#[test] +fn a_write_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no write of /vault.md"; + let files = Files::new().fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let before = files.clone(); + assert_eq!(failure_of(write_to(&files, "/vault.md", "x")), reason); + assert_eq!(failure_of(write_to(&files, "/vault.md/in", "x")), reason); + assert_eq!(files, before); +} + +#[test] +fn a_write_that_fails_for_another_reason_is_worded_by_its_kind() { + let files = Files::new().fails( + "/disk.md", + FileError::new(FileErrorKind::Io, "storage full: no space left"), + ); + assert_eq!( + failure_of(write_to(&files, "/disk.md", "x")), + "I/O failure on /disk.md: storage full: no space left" + ); + // A failure of no named kind reads as the words it came with. + assert_eq!( + failure_of(write_to(&FakeSource::default(), "/a.md", "x")), + "the fake tree takes no change: /a.md" + ); +} + +#[test] +fn a_missing_path_or_contents_names_the_parameter() { + let files = Files::new(); + assert_eq!( + refused(write(&files, &json!({ "contents": "x" }))), + "std_Write: `path` is required, and the call left it out" + ); + assert_eq!( + refused(write(&files, &json!({ "path": "/a.md" }))), + "std_Write: `contents` is required, and the call left it out" + ); + assert_eq!( + refused(write(&files, &json!({ "path": "/a.md", "contents": 7 }))), + "std_Write: `contents` must be a JSON string, and the call passed 7" + ); + assert_eq!(files, Files::new()); +} + +#[test] +fn an_undeclared_key_is_refused_and_the_parameters_are_named() { + let files = Files::new(); + assert_eq!( + refused(write( + &files, + &json!({ "path": "/a.md", "contents": "x", "append": true }) + )), + "std_Write: `append` is not a parameter of this tool. \ + The parameters are `contents` and `path`." + ); + assert_eq!(files, Files::new()); +} + +#[test] +fn a_blank_path_is_refused_before_anything_is_written() { + let files = Files::new(); + for blank in ["", " ", "\t\n"] { + assert_eq!( + refused(write_to(&files, blank, "x")), + format!( + "std_Write: `path` is empty or only whitespace, and the call passed \"{blank}\"" + ) + ); + } + assert_eq!(files, Files::new()); +} + +#[test] +fn the_refusals_come_in_a_fixed_order() { + let files = Files::new(); + let over = "a".repeat(16_777_217); + assert_eq!( + refused(write( + &files, + &json!({ "path": " ", "contents": over, "mode": 7 }) + )), + "std_Write: `mode` is not a parameter of this tool. \ + The parameters are `contents` and `path`." + ); + assert_eq!( + refused(write_to(&files, " ", &over)), + "std_Write: `path` is empty or only whitespace, and the call passed \" \"" + ); +} diff --git a/crates/plugin-std/src/write.rs b/crates/plugin-std/src/write.rs new file mode 100644 index 0000000..61126b5 --- /dev/null +++ b/crates/plugin-std/src/write.rs @@ -0,0 +1,66 @@ +//! The `Write` tool: makes a file, or replaces the whole contents of one. +//! +//! Write hands the call's contents to the Host as one write through the +//! call's [`Source`], so the run's policy applies. The Host makes the +//! file when it is absent, with each directory on the way to it. Write +//! asks for nothing else: it takes no stat and no read first, so what +//! was at the path is gone when the write succeeds. Contents over +//! [`RV_MAX_WRITE`] bytes, the most one write takes, are refused before +//! the Host is asked for anything. The answer is fixed text and a count, +//! so it is trusted output. + +use runvil_plugin_sdk::sys::RV_MAX_WRITE; +use runvil_plugin_sdk::{ToolError, ToolErrorKind, ToolOutput}; +use serde_json::Value; + +use crate::check::{make_invalid_arguments_error, plural, refuse_blank, refuse_unknown}; +use crate::refusal::write_refusal; +use crate::source::Source; +use crate::spec::Definition; + +/// Runs one `Write` call whose arguments already passed the shared schema +/// check. +/// +/// The order of the refusals is fixed: an undeclared key, then a blank +/// path, then contents over the limit, so a call that breaks two rules +/// always hears about the same one. +/// +/// # Errors +/// Returns an invalid-arguments [`ToolError`] naming the parameter for a +/// bad argument, and a message error for a write the Host fails, worded +/// for a model to read. +pub(crate) async fn call( + source: &impl Source, + definition: &Definition, + args: &Value, +) -> Result { + let tool = definition.wire_name.as_str(); + refuse_unknown(tool, &definition.parameters, args)?; + let path = args.get("path").and_then(Value::as_str).unwrap_or_default(); + refuse_blank(tool, "path", path)?; + let contents = args + .get("contents") + .and_then(Value::as_str) + .unwrap_or_default(); + if contents.len() > RV_MAX_WRITE { + return Err(make_invalid_arguments_error( + tool, + format!( + "`contents` is {} bytes, and one write takes at most {RV_MAX_WRITE} bytes", + contents.len() + ), + )); + } + source + .write(path, contents.as_bytes().to_vec()) + .await + .map_err(|error| ToolError::new(ToolErrorKind::Other, write_refusal(tool, path, &error)))?; + Ok(ToolOutput::trusted(format!( + "Wrote {}.", + plural(contents.len(), "byte") + ))) +} + +#[cfg(test)] +#[path = "write-tests.rs"] +mod tests; diff --git a/crates/plugin-std/tests/it/changes.rs b/crates/plugin-std/tests/it/changes.rs new file mode 100644 index 0000000..7c34502 --- /dev/null +++ b/crates/plugin-std/tests/it/changes.rs @@ -0,0 +1,408 @@ +//! The tools that change files, through the Plugin's entry point: which +//! tools say to the Host that they change files, what a call leaves in +//! the files of its run, what it answers, and what it asks the Host for, +//! step by step. + +use plugin_std::Std; +use runvil_plugin_sdk::testing::{self, Files}; +use runvil_plugin_sdk::{FileError, FileErrorKind, ToolError, ToolErrorKind, ToolOutput}; +use serde_json::{Value, json}; + +use crate::tools::PACK; + +/// Calls the tool `name` with `args` over `files`, and returns what the +/// call answered beside the files as the call left them. +fn change(files: Files, name: &str, args: &Value) -> (Result, Files) { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(files); + let result = pack + .call(name, &args.to_string()) + .expect("the call follows the contract"); + (result, pack.files().clone()) +} + +/// How many steps a call of the tool `name` with `args` over `files` +/// takes to its end. Each file request ends one step, so a call that +/// makes `n` requests takes `n + 1` steps. +fn steps(files: Files, name: &str, args: &Value) -> usize { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(files); + let mut call = pack.start(name, &args.to_string()); + let mut steps = 1; + while call + .step() + .expect("each step follows the contract") + .is_none() + { + steps += 1; + } + steps +} + +/// The whole contents of the file at `path` in `files`. +fn contents(files: &Files, path: &str) -> Result, FileError> { + files.read(path, 0, u64::MAX) +} + +#[test] +fn the_tools_that_change_files_say_so_to_the_host_and_no_other_tool_does() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let flagged: Vec<&str> = pack + .tools() + .iter() + .filter(|tool| tool.changes_files) + .map(|tool| tool.name.as_str()) + .collect(); + assert_eq!(flagged, ["write", "replace", "rm"]); +} + +#[test] +fn write_makes_a_file_and_answers_the_byte_count_as_trusted_output() { + let (result, files) = change( + Files::new(), + "write", + &json!({ "path": "/notes/a.md", "contents": "hello\n" }), + ); + let output = result.expect("the file is written"); + assert_eq!(output.text(), "Wrote 6 bytes."); + assert!(output.is_trusted()); + assert_eq!(contents(&files, "/notes/a.md"), Ok(b"hello\n".to_vec())); +} + +#[test] +fn write_replaces_the_whole_contents_of_a_file() { + let (result, files) = change( + Files::new().file("/a.md", "a long first version\n"), + "write", + &json!({ "path": "/a.md", "contents": "short" }), + ); + assert!(result.is_ok()); + assert_eq!(contents(&files, "/a.md"), Ok(b"short".to_vec())); +} + +#[test] +fn write_asks_the_host_for_one_write_and_nothing_else() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let args = json!({ "path": "/a.md", "contents": "x" }); + let mut call = pack.start("write", &args.to_string()); + // The first step ends at a request, which the Host has performed + // when the step returns: it is the write. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"x".to_vec())); + // The second step has the answer and ends the call. + assert_eq!( + call.step(), + Ok(Some(Ok(ToolOutput::trusted("Wrote 1 byte.")))) + ); +} + +#[test] +fn a_write_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no write of /vault.md"; + let before = Files::new() + .file("/a.md", "kept") + .fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let (result, after) = change( + before.clone(), + "write", + &json!({ "path": "/vault.md", "contents": "x" }), + ); + let error = result.expect_err("the policy denies the write"); + assert_eq!(error.message(), reason); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); +} + +#[test] +fn contents_over_the_limit_of_one_write_fail_naming_the_limit_before_the_host_is_asked() { + let args = json!({ "path": "/big.txt", "contents": "a".repeat(16_777_217) }); + let (result, files) = change(Files::new(), "write", &args); + let error = result.expect_err("the contents are over the limit"); + assert_eq!( + error.message(), + "std_Write: `contents` is 16777217 bytes, and one write takes at most 16777216 bytes" + ); + assert_eq!(error.kind(), ToolErrorKind::InvalidArguments); + assert_eq!(files, Files::new()); + assert_eq!(steps(Files::new(), "write", &args), 1); +} + +#[test] +fn a_path_longer_than_the_contract_takes_fails_before_the_host_is_asked() { + let args = json!({ "path": format!("/{}", "a".repeat(4096)), "contents": "x" }); + let (result, files) = change(Files::new(), "write", &args); + let error = result.expect_err("the path is over the limit"); + assert_eq!(error.message(), "the path is longer than 4096 bytes"); + assert_eq!(files, Files::new()); + assert_eq!(steps(Files::new(), "write", &args), 1); +} + +#[test] +fn a_later_call_of_the_run_reads_what_a_write_left() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let written = pack + .call( + "write", + &json!({ "path": "/notes/a.md", "contents": "one\ntwo\n" }).to_string(), + ) + .expect("the call follows the contract"); + assert!(written.is_ok()); + let read = pack + .call("read", r#"{"path":"/notes/a.md"}"#) + .expect("the call follows the contract") + .expect("the file reads"); + assert_eq!(read.text(), " 1|one\n 2|two\n"); +} + +#[test] +fn str_replace_edits_the_one_occurrence_and_answers_the_count_as_trusted_output() { + let (result, files) = change( + Files::new().file("/a.md", "one\ntwo\nthree\n"), + "replace", + &json!({ "path": "/a.md", "old_string": "two", "new_string": "2" }), + ); + let output = result.expect("the file is edited"); + assert_eq!(output.text(), "Made 1 replacement."); + assert!(output.is_trusted()); + assert_eq!(contents(&files, "/a.md"), Ok(b"one\n2\nthree\n".to_vec())); +} + +#[test] +fn str_replace_with_replace_all_edits_every_occurrence() { + let (result, files) = change( + Files::new().file("/a.rs", "let x = x + x;\n"), + "replace", + &json!({ + "path": "/a.rs", "old_string": "x", "new_string": "total", "replace_all": true + }), + ); + let output = result.expect("the file is edited"); + assert_eq!(output.text(), "Made 3 replacements."); + assert_eq!( + contents(&files, "/a.rs"), + Ok(b"let total = total + total;\n".to_vec()) + ); +} + +#[test] +fn str_replace_asks_the_host_for_a_stat_a_read_and_a_write() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/a.md", "one two\n")); + let args = json!({ "path": "/a.md", "old_string": "two", "new_string": "2" }); + let mut call = pack.start("replace", &args.to_string()); + // The first request changes nothing, and it reads none of the bytes + // that the edit works on: the test puts other bytes in the file once + // the Host has performed it, and the edit is made on those. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"one two\n".to_vec())); + pack.files() + .write("/a.md", "uno two\n") + .expect("the file is written"); + // The second request is the read, which changes nothing. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"uno two\n".to_vec())); + // The third request is the write of the edited text. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"uno 2\n".to_vec())); + // The fourth step has the answer and ends the call. + assert_eq!( + call.step(), + Ok(Some(Ok(ToolOutput::trusted("Made 1 replacement.")))) + ); +} + +#[test] +fn an_edit_whose_text_does_not_occur_once_fails_with_the_count_before_any_write() { + let before = Files::new().file("/a.rs", "let x = x + x;\n"); + let args = json!({ "path": "/a.rs", "old_string": "x", "new_string": "total" }); + let (result, after) = change(before.clone(), "replace", &args); + let error = result.expect_err("the text occurs three times"); + assert_eq!( + error.message(), + "`old_string` occurs 3 times in /a.rs, and it must occur exactly once. Add text around \ + it until it names one occurrence, or set `replace_all` to replace every one." + ); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); + assert_eq!(steps(before, "replace", &args), 3, "the stat and the read"); +} + +#[test] +fn an_edit_whose_text_overlaps_itself_fails_before_any_write_unless_it_replaces_all() { + let before = Files::new().file("/b.txt", "banana"); + let args = json!({ "path": "/b.txt", "old_string": "ana", "new_string": "X" }); + let (result, after) = change(before.clone(), "replace", &args); + let error = result.expect_err("the text starts at two places"); + assert_eq!( + error.message(), + "`old_string` starts at more than one place in /b.txt, in occurrences that overlap, and \ + it must occur exactly once. Add text around it until it names one occurrence." + ); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); + assert_eq!( + steps(before.clone(), "replace", &args), + 3, + "the stat and the read" + ); + let all = json!({ + "path": "/b.txt", "old_string": "ana", "new_string": "X", "replace_all": true + }); + let (result, after) = change(before, "replace", &all); + let output = result.expect("the occurrence that starts first is replaced"); + assert_eq!(output.text(), "Made 1 replacement."); + assert_eq!(contents(&after, "/b.txt"), Ok(b"bXna".to_vec())); +} + +#[test] +fn an_edit_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no read of /vault.md"; + let before = Files::new() + .file("/a.md", "kept") + .fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let (result, after) = change( + before.clone(), + "replace", + &json!({ "path": "/vault.md", "old_string": "a", "new_string": "b" }), + ); + let error = result.expect_err("the policy denies the edit"); + assert_eq!(error.message(), reason); + assert_eq!(after, before); +} + +#[test] +fn two_edits_of_one_file_in_a_run_both_apply() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/a.md", "one two three\n")); + for (old, new) in [("one", "1"), ("three", "3")] { + let args = json!({ "path": "/a.md", "old_string": old, "new_string": new }); + let edited = pack + .call("replace", &args.to_string()) + .expect("the call follows the contract"); + assert!(edited.is_ok(), "{old}"); + } + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"1 two 3\n".to_vec())); +} + +#[test] +fn delete_removes_a_file_and_answers_fixed_text_as_trusted_output() { + let (result, files) = change( + Files::new() + .file("/notes/a.md", "one") + .file("/notes/b.md", "two"), + "rm", + &json!({ "path": "/notes/a.md" }), + ); + let output = result.expect("the file is deleted"); + assert_eq!(output.text(), "Deleted the file."); + assert!(output.is_trusted()); + assert_eq!(files, Files::new().file("/notes/b.md", "two")); +} + +#[test] +fn delete_asks_the_host_for_a_stat_and_then_a_removal() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/a.md", "one")); + let mut call = pack.start("rm", &json!({ "path": "/a.md" }).to_string()); + // The first request is the stat, which removes nothing. + assert_eq!(call.step(), Ok(None)); + assert_eq!(contents(pack.files(), "/a.md"), Ok(b"one".to_vec())); + // The second request is the removal. + assert_eq!(call.step(), Ok(None)); + assert_eq!(pack.files(), &Files::new()); + // The third step has the answer and ends the call. + assert_eq!( + call.step(), + Ok(Some(Ok(ToolOutput::trusted("Deleted the file.")))) + ); +} + +#[test] +fn delete_refuses_a_directory_after_its_stat_and_removes_nothing() { + let before = Files::new().file("/notes/a.md", "one").dir("/empty"); + for directory in ["/notes", "/empty"] { + let args = json!({ "path": directory }); + let (result, after) = change(before.clone(), "rm", &args); + let error = result.expect_err("the path names a directory"); + assert_eq!( + error.message(), + format!("Path is a directory, not a file: {directory}") + ); + assert_eq!(error.kind(), ToolErrorKind::Other); + assert_eq!(after, before); + assert_eq!(steps(before.clone(), "rm", &args), 2, "the stat alone"); + } +} + +#[test] +fn delete_of_a_missing_path_fails_with_the_not_found_text() { + let args = json!({ "path": "/nope.md" }); + let (result, files) = change(Files::new(), "rm", &args); + let error = result.expect_err("nothing is at the path"); + assert_eq!(error.message(), "File not found: /nope.md"); + assert_eq!(files, Files::new()); + assert_eq!(steps(Files::new(), "rm", &args), 2, "the stat alone"); +} + +#[test] +fn a_delete_the_policy_denies_fails_with_the_policys_own_reason_and_changes_nothing() { + let reason = "Mode::Ask allows no change of /vault.md"; + let before = Files::new() + .file("/a.md", "kept") + .fails("/vault.md", FileError::new(FileErrorKind::Denied, reason)); + let (result, after) = change(before.clone(), "rm", &json!({ "path": "/vault.md" })); + let error = result.expect_err("the policy denies the delete"); + assert_eq!(error.message(), reason); + assert_eq!(after, before); +} + +#[test] +fn the_calls_of_one_run_write_edit_read_and_delete_one_file_in_turn() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded.new_pack(PACK).expect("the Pack instance is made"); + let call = |name: &str, args: Value| { + pack.call(name, &args.to_string()) + .expect("the call follows the contract") + }; + let answer = |name: &str, args: Value| { + let output = call(name, args).unwrap_or_else(|error| panic!("{name} fails: {error}")); + output.text().to_owned() + }; + let path = "/notes/a.md"; + assert_eq!( + answer("write", json!({ "path": path, "contents": "one\ntwo\n" })), + "Wrote 8 bytes." + ); + assert_eq!( + answer( + "replace", + json!({ "path": path, "old_string": "two", "new_string": "2" }) + ), + "Made 1 replacement." + ); + assert_eq!( + answer("read", json!({ "path": path })), + " 1|one\n 2|2\n" + ); + assert_eq!(answer("rm", json!({ "path": path })), "Deleted the file."); + let gone = call("read", json!({ "path": path })).expect_err("the file is gone"); + assert_eq!(gone.message(), "File not found: /notes/a.md"); +} diff --git a/crates/plugin-std/tests/it/grep.rs b/crates/plugin-std/tests/it/grep.rs index c66c48e..ad7eeba 100644 --- a/crates/plugin-std/tests/it/grep.rs +++ b/crates/plugin-std/tests/it/grep.rs @@ -1,6 +1,6 @@ -//! Grep's steps, seen from the Host's side of the contract: a search over -//! many files ends its step before it completes, so the Host can abandon -//! it, and an abandoned search leaves the Pack instance usable. +//! Grep's steps, seen from the Host's side of the contract: a search ends +//! its step at each file operation and at each pause, so the Host can +//! abandon it, and an abandoned search leaves the Pack instance usable. use plugin_std::Std; use runvil_plugin_sdk::testing::{self, Files}; @@ -25,7 +25,7 @@ fn args() -> String { } #[test] -fn a_search_over_a_thousand_files_takes_many_steps_before_it_completes() { +fn a_search_over_a_thousand_files_ends_a_step_at_each_file_operation_and_each_pause() { let loaded = testing::load::().expect("the Plugin loads"); let pack = loaded .new_pack(PACK) @@ -39,9 +39,11 @@ fn a_search_over_a_thousand_files_takes_many_steps_before_it_completes() { None => pending += 1, } }; - assert!( - pending >= 31, - "a step ends after each 32 of {FILES} files, and the search took {pending} extra steps" + assert_eq!( + pending, + 2 + FILES + FILES / 32, + "a step ends at the stat of the root, at its listing, at the read of each file, and \ + at the pause after each 32 files" ); let output = result.expect("the search completes with its result"); assert!(!output.is_trusted()); @@ -56,19 +58,60 @@ fn a_search_over_a_thousand_files_takes_many_steps_before_it_completes() { } #[test] -fn abandoning_a_search_after_its_first_step_leaves_the_instance_usable() { +fn a_file_that_grows_past_the_limit_after_its_listing_is_skipped_and_not_searched() { + let loaded = testing::load::().expect("the Plugin loads"); + let pack = loaded + .new_pack(PACK) + .expect("the Pack instance is made") + .with_files(Files::new().file("/grew.txt", "x\n")); + let mut call = pack.start("grep", &args()); + // The stat of the root, and then its listing, which says 2 bytes. + assert_eq!(call.step(), Ok(None)); + assert_eq!(call.step(), Ok(None)); + // Another task makes the file longer than a search takes, before the + // search asks for its bytes. + pack.files() + .write("/grew.txt", vec![b'x'; 16_777_218]) + .expect("the file is written"); + let result = loop { + if let Some(result) = call.step().expect("each step follows the contract") { + break result; + } + }; + let output = result.expect("the search completes with its result"); + assert_eq!( + output.text(), + "No matches found. Searched 0 files.\n\n\ + [Skipped 1 entry: 1 file over 16777216 bytes. First: /grew.txt]\n\ + [No ignore rules ran: .gitignore is not applied, and only entries named .git are \ + skipped.]" + ); +} + +/// How many steps a search of the seeded tree takes up to its first +/// pause: the stat of the root, its listing, the reads of 32 files, and +/// the step that ends at the pause. +const FIRST_PAUSE: usize = 2 + 32 + 1; + +#[test] +fn abandoning_a_search_at_a_request_or_at_its_first_pause_leaves_the_instance_usable() { let loaded = testing::load::().expect("the Plugin loads"); let pack = loaded .new_pack(PACK) .expect("the Pack instance is made") .with_files(seeded()); - { + // The search is abandoned at the stat of the root, then at the read + // of a file with some files searched, and then at its first pause, + // with 32 files searched and no request with the Host. + for steps in [1, 10, FIRST_PAUSE] { let mut abandoned = pack.start("grep", &args()); - assert_eq!( - abandoned.step(), - Ok(None), - "the search ends its first step before it can finish" - ); + for step in 1..=steps { + assert_eq!( + abandoned.step(), + Ok(None), + "step {step} of {steps} ends before the search can finish" + ); + } // Dropping the call sends `RV_TOOL_CANCEL`, as a canceled run does. } let read = pack diff --git a/crates/plugin-std/tests/it/main.rs b/crates/plugin-std/tests/it/main.rs index 1f84e29..7948306 100644 --- a/crates/plugin-std/tests/it/main.rs +++ b/crates/plugin-std/tests/it/main.rs @@ -1,11 +1,12 @@ //! Integration tests for `plugin-std`, through its entry point and the //! SDK's fake Host: the Pack the Plugin inserts, the tools one run's -//! instance adds, and what a call answers with arguments that match or -//! miss the schema. +//! instance adds, what a call answers with arguments that match or miss +//! the schema, and what a call that changes files leaves in its run. #![expect( clippy::expect_used, reason = "test helpers panic on setup failure, which is the desired behavior" )] +mod changes; mod grep; mod tools; diff --git a/crates/plugin-std/tests/it/tools.rs b/crates/plugin-std/tests/it/tools.rs index 7d099ce..5443426 100644 --- a/crates/plugin-std/tests/it/tools.rs +++ b/crates/plugin-std/tests/it/tools.rs @@ -71,26 +71,11 @@ fn each_run_gets_an_instance_of_its_own_with_the_same_tools() { } #[test] -fn every_stub_answers_the_not_implemented_text_naming_itself() { - for (name, wire_name, args) in [ - ( - "write", - "Write", - json!({ "path": "/notes.md", "contents": "hi" }), - ), - ( - "replace", - "StrReplace", - json!({ "path": "/notes.md", "old_string": "a", "new_string": "b" }), - ), - ("rm", "Delete", json!({ "path": "/notes.md" })), - ("glob", "Glob", json!({ "glob_pattern": "**/*.md" })), - ] { - let output = call(name, &args).expect("a matching call succeeds"); - let expected = NOT_IMPLEMENTED.replace("", wire_name); - assert_eq!(output.text(), expected, "{name}"); - assert!(output.is_trusted(), "{name}"); - } +fn glob_the_one_stub_answers_the_not_implemented_text_naming_itself() { + let output = + call("glob", &json!({ "glob_pattern": "**/*.md" })).expect("a matching call succeeds"); + assert_eq!(output.text(), NOT_IMPLEMENTED.replace("", "Glob")); + assert!(output.is_trusted()); } #[test] @@ -269,7 +254,7 @@ fn grep_of_a_missing_path_fails_with_the_does_not_exist_text() { } #[test] -fn grep_refuses_an_undeclared_key_by_name_while_the_stubs_let_it_through() { +fn grep_refuses_an_undeclared_key_by_name_while_the_stub_lets_it_through() { let error = call("grep", &json!({ "pattern": "x", "context": 3 })) .expect_err("context is not a parameter"); assert_eq!(error.kind(), ToolErrorKind::InvalidArguments);