rig_tools/workspace.rs
1//! The [`Workspace`] the tools act on: the disk they read and write and
2//! where their commands run. [`Local`] is this machine; another, such as
3//! a [`Remote`](crate::remote::Remote) reached over SSH, is a type of its
4//! own that every tool and the shell then go through.
5
6use std::ffi::{OsStr, OsString};
7use std::fmt;
8use std::fs::{self, File};
9use std::io::{self, ErrorKind, Read as _};
10use std::path::{Component, Path, PathBuf};
11use std::sync::Arc;
12use std::time::SystemTime;
13
14use ignore::WalkBuilder;
15use ignore::overrides::OverrideBuilder;
16use rig_core::tool::{ContentHash, ToolExecutionError, content_hash};
17
18use crate::fs::{Previous, io_error, write_atomic};
19use crate::process::{Launcher, Process, Spawn};
20pub use crate::watch::Watch;
21use crate::{MAX_BYTES, MAX_FILE_BYTES, shell_path};
22
23/// The disk and the commands the tools act on: this machine's ([`Local`]),
24/// or another, such as one reached over SSH. Paths are the workspace's own:
25/// a tool's base, the paths it resolves and the facts it publishes
26/// ([`FilesRead`](rig_core::tool::FilesRead),
27/// [`FilesChanged`](rig_core::tool::FilesChanged)) name files in it.
28///
29/// Synchronous, as the rest of rig-tools: the tools call it inside
30/// [`blocking`](crate::blocking). Code on a thread that must not wait, such
31/// as an app's main thread, calls it inline only when [`host`](Self::host)
32/// is `None`, and otherwise off that thread.
33///
34/// A workspace of your own implements every method; [`Local`] is the
35/// reference for what each does.
36pub trait Workspace: Send + Sync + fmt::Debug + 'static {
37 /// Where it is when it is not this machine, such as `ssh://dev@box`;
38 /// `None` for this machine.
39 fn host(&self) -> Option<&str> {
40 None
41 }
42
43 /// What `path` is, its links followed: a file (its size, whether it is
44 /// read-only, when it was last changed), a directory, something else, or
45 /// nothing.
46 fn stat(&self, path: &Path) -> io::Result<Stat>;
47
48 /// Up to `limit` bytes of the regular file `path`, and its whole size.
49 /// Anything but a regular file is refused without being opened: opening
50 /// a FIFO or a device can block forever.
51 fn read(&self, path: &Path, limit: u64) -> io::Result<Contents>;
52
53 /// The whole content of each of `paths` that is a regular file of at
54 /// most `limit` bytes, in order: `None` for any other path, and for one
55 /// that could not be read. What a search reads; a workspace where each
56 /// call costs a round trip, such as a remote one, reads them in one.
57 fn read_files(&self, paths: &[PathBuf], limit: u64) -> Vec<Option<Vec<u8>>> {
58 paths
59 .iter()
60 .map(|path| read_file(self, path, limit))
61 .collect()
62 }
63
64 /// Lines `first` (from 1) on, at most `count` of them, of the regular
65 /// text file `path`, with how many lines it has and the hash of all of
66 /// it. Refused, as `read_text` refuses,
67 /// when it is no regular file, larger than [`MAX_FILE_BYTES`] (a
68 /// [`FileTooLarge`](ErrorKind::FileTooLarge) error) or not UTF-8 (an
69 /// [`InvalidData`](ErrorKind::InvalidData) error); a workspace that
70 /// sends only the lines asked of a file larger than
71 /// [`MAX_BYTES`], such as a remote one, checks only those for UTF-8.
72 ///
73 /// By default the whole file is [`read`](Self::read) and cut here.
74 fn excerpt(&self, path: &Path, first: usize, count: usize) -> io::Result<Excerpt> {
75 excerpt_of(self, path, first, count)
76 }
77
78 /// Replaces the file `path` with `bytes` in one step, creating its
79 /// directory, keeping its permissions, and refusing a read-only file or
80 /// anything but a regular file (see [`write_atomic`]).
81 fn write(&self, path: &Path, bytes: &[u8]) -> io::Result<()>;
82
83 /// [`write`](Self::write)s `bytes` to `path` and says what the file
84 /// held before, as [`read`](Self::read) with `limit` reads it: a
85 /// [`NotFound`](ErrorKind::NotFound) error when there was no file, the
86 /// file's own when it could not be read. What a tool that writes a
87 /// file diffs against; a workspace where each call costs a round trip,
88 /// such as a remote one, does both in one.
89 ///
90 /// By default it reads, then writes.
91 fn replace(&self, path: &Path, bytes: &[u8], limit: u64) -> io::Result<io::Result<Contents>> {
92 let before = self.read(path, limit);
93 self.write(path, bytes)?;
94 Ok(before)
95 }
96
97 /// [`write`](Self::write)s `bytes` to the regular file `path` only
98 /// while it holds the text whose [`content_hash`] is `held`: `None`
99 /// when it did. Otherwise nothing is written and it says what the file
100 /// holds instead, as [`read`](Self::read) with a limit of
101 /// [`MAX_FILE_BYTES`] reads it. What an edit made from text seen
102 /// before writes with; a workspace where each call costs a round trip,
103 /// such as a remote one, checks and writes in one.
104 ///
105 /// By default it reads, then writes.
106 fn write_if(
107 &self,
108 path: &Path,
109 bytes: &[u8],
110 held: &ContentHash,
111 ) -> io::Result<Option<Contents>> {
112 let now = self.read(path, MAX_FILE_BYTES)?;
113 if now.size > MAX_FILE_BYTES || content_hash(&now.bytes) != *held {
114 return Ok(Some(now));
115 }
116 self.write(path, bytes)?;
117 Ok(None)
118 }
119
120 /// Removes the file `path`; a directory is refused.
121 fn remove(&self, path: &Path) -> io::Result<()>;
122
123 /// Moves the file `from` to `to`, creating `to`'s directory and
124 /// replacing a file there.
125 fn rename(&self, from: &Path, to: &Path) -> io::Result<()>;
126
127 /// `path` made absolute, with the links of its longest existing part
128 /// followed (the file's own too, when it exists) and `..` folded, so two
129 /// spellings of one file come out alike. A footprint is made with it,
130 /// which may be on a thread that must not wait: a remote workspace may
131 /// answer from a cache, or fold `..` only.
132 fn canonical(&self, path: &Path) -> PathBuf;
133
134 /// `path` relative to `base`, as `resolve` joins them:
135 /// `base.join(path)`, so an absolute `path` stays as it is. A workspace
136 /// whose paths can name another machine, such as
137 /// [`Hosts`](crate::remote::Hosts), keeps such a path whole too. A
138 /// workspace with a home directory reads a first component `~` as that
139 /// home: [`Local`] does for `~`, `~/notes` and, on Windows, `~\notes`,
140 /// but not for `~bob` or `./~`.
141 fn join(&self, base: &Path, path: &Path) -> PathBuf {
142 base.join(path)
143 }
144
145 /// The regular files under `root` (or `root` itself when it is a file),
146 /// in walk order, as `root` joined with their path below it: those
147 /// `listing` keeps ([`Listing`]), and only those matching `glob`, such
148 /// as `*.rs`, when it is given. A malformed glob is an
149 /// [`InvalidInput`](ErrorKind::InvalidInput) error that says so.
150 fn files(&self, root: &Path, glob: Option<&str>, listing: Listing) -> io::Result<Vec<PathBuf>>;
151
152 /// Starts `program` with `args` in `dir` (`None`: the launcher's own
153 /// directory) under `launcher`'s policy: its wrapper and variables.
154 fn spawn(
155 &self,
156 launcher: &Launcher,
157 dir: Option<&Path>,
158 program: &OsStr,
159 args: &[OsString],
160 how: Spawn,
161 ) -> io::Result<Process>;
162
163 /// Watches `root`, a file or a directory (with `recursive`, every
164 /// directory under it too), from now on: a batch of the paths created,
165 /// changed or removed each time something changed, of the files
166 /// [`files`](Self::files) would list with `listing`.
167 /// Dropping the [`Watch`] stops it. To miss nothing, list the files
168 /// once after the watch has started.
169 ///
170 /// By default it looks at what [`files`](Self::files) lists every
171 /// second, on a thread of its own, comparing each file's
172 /// size and change time (its hash when [`stat`](Self::stat) cannot tell
173 /// the time). [`Local`] hears of changes from the system instead.
174 fn watch(self: Arc<Self>, root: &Path, recursive: bool, listing: Listing) -> io::Result<Watch> {
175 crate::watch::poll(self, root, recursive, listing)
176 }
177}
178
179/// Which files [`Workspace::files`] lists, and a watch reports.
180#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
181pub enum Listing {
182 /// What a person browsing the project sees, as ripgrep lists it: no
183 /// file the ignore rules (`.gitignore`, `.ignore`, the git excludes)
184 /// leave out, no hidden file or directory (named with a leading `.`),
185 /// no `target` directory.
186 #[default]
187 Visible,
188 /// Every file the ignore rules keep, hidden ones such as `.github/` and
189 /// `.env.example` included; `.git` left out.
190 Hidden,
191 /// Every regular file.
192 All,
193}
194
195impl Listing {
196 /// The listing of a tool call's `hidden` and `glob` arguments.
197 pub(crate) fn from_options(hidden: bool, glob: Option<&str>) -> Self {
198 match hidden {
199 true => Self::Hidden,
200 false => Self::Visible,
201 }
202 .for_glob(glob)
203 }
204
205 /// The listing a search or listing for `glob` uses: `Visible` becomes
206 /// `Hidden` when the glob names a hidden file or directory, such as
207 /// `.github/**` or `**/.env*`, so asking for one finds it.
208 pub fn for_glob(self, glob: Option<&str>) -> Self {
209 let names_hidden = glob.is_some_and(|glob| {
210 glob.split(['/', '\\'])
211 .any(|part| part.starts_with('.') && part != "." && part != "..")
212 });
213 match self {
214 Self::Visible if names_hidden => Self::Hidden,
215 other => other,
216 }
217 }
218
219 /// Whether this listing keeps `below`, a path below the listed root, by
220 /// its names alone (the ignore rules aside): `Visible` none of whose
221 /// parts is hidden or `target`, `Hidden` none of whose parts is `.git`.
222 pub fn keeps(self, below: &Path) -> bool {
223 let mut parts = below.iter();
224 match self {
225 Self::Visible => !parts.any(|part| part == "target" || is_hidden(Path::new(part))),
226 Self::Hidden => !parts.any(|part| part == ".git"),
227 Self::All => true,
228 }
229 }
230}
231
232/// What [`Workspace::read`] read.
233#[derive(Clone, Debug, Default, PartialEq, Eq)]
234pub struct Contents {
235 /// At most the asked number of bytes, from the file's start.
236 pub bytes: Vec<u8>,
237 /// The file's whole size, more than `bytes` holds when it was cut.
238 pub size: u64,
239}
240
241/// What [`Workspace::excerpt`] read.
242#[derive(Clone, Debug, PartialEq, Eq)]
243pub struct Excerpt {
244 /// The lines asked, each with its line end as in the file.
245 pub text: String,
246 /// How many lines the file has, as [`str::lines`] counts them.
247 pub total: usize,
248 /// The hash of the whole file.
249 pub hash: ContentHash,
250 /// The whole file's text, when it is at most [`MAX_BYTES`]: sending
251 /// that much costs about what a call does, and an edit after the read
252 /// starts from it instead of fetching the file.
253 pub whole: Option<String>,
254}
255
256impl Excerpt {
257 /// Lines `first` (from 1) on, at most `count` of them, of `text`, the
258 /// whole file, kept whole too when it is small.
259 pub fn of(text: &str, first: usize, count: usize) -> Self {
260 let start = text
261 .split_inclusive('\n')
262 .take(first.saturating_sub(1))
263 .map(str::len)
264 .sum();
265 let rest = text.get(start..).unwrap_or_default();
266 let len = rest.split_inclusive('\n').take(count).map(str::len).sum();
267 Self {
268 text: rest.get(..len).unwrap_or_default().to_owned(),
269 total: text.lines().count(),
270 hash: content_hash(text.as_bytes()),
271 whole: (text.len() <= MAX_BYTES).then(|| text.to_owned()),
272 }
273 }
274}
275
276/// What a path is, as [`Workspace::stat`] says.
277#[derive(Clone, Copy, Debug, PartialEq, Eq)]
278pub enum Stat {
279 /// A regular file.
280 File {
281 /// Its size in bytes.
282 size: u64,
283 /// Whether it may not be written.
284 read_only: bool,
285 /// When its content last changed, when the workspace can tell:
286 /// how a scan or a polling watch sees an edit that kept the size.
287 modified: Option<SystemTime>,
288 },
289 /// A directory.
290 Dir,
291 /// Something else, such as a FIFO or a device: the tools neither read
292 /// nor write it.
293 Other,
294 /// Nothing is there.
295 Missing,
296}
297
298impl dyn Workspace {
299 /// `path` as the file tools name it: [`join`](Workspace::join)ed onto
300 /// `base` (`None`: the working directory), then made
301 /// [`canonical`](Workspace::canonical).
302 pub fn resolve(&self, base: Option<&Path>, path: &str) -> PathBuf {
303 self.canonical(&self.join(base.unwrap_or(Path::new("")), path.as_ref()))
304 }
305
306 /// `path` `resolve`d against `base`, as a file tool
307 /// opens it; with `confine`, refused before any other I/O when it lies
308 /// outside `base` (`None`: the working directory).
309 ///
310 /// ```
311 /// use rig_tools::workspace::{Local, Workspace};
312 ///
313 /// let local: &dyn Workspace = &Local;
314 /// let base = std::fs::canonicalize(".")?;
315 /// assert_eq!(local.place(Some(&base), true, "src/../a.rs")?, base.join("a.rs"));
316 /// assert!(local.place(Some(&base), true, "../outside.rs").is_err());
317 /// assert!(local.place(Some(&base), false, "../outside.rs").is_ok());
318 /// # Ok::<(), Box<dyn std::error::Error>>(())
319 /// ```
320 pub fn place(
321 &self,
322 base: Option<&Path>,
323 confine: bool,
324 path: &str,
325 ) -> Result<PathBuf, ToolExecutionError> {
326 let resolved = self.resolve(base, path);
327 if confine {
328 let root = self.resolve(base, ".");
329 if !resolved.starts_with(&root) {
330 return Err(ToolExecutionError::permission_denied(format!(
331 "{path} is outside {}, the only directory this tool works in",
332 root.display()
333 )));
334 }
335 }
336 Ok(resolved)
337 }
338
339 /// The regular file `path` as text, in one [`read`](Workspace::read):
340 /// refused when it is no regular file or larger than
341 /// [`MAX_FILE_BYTES`].
342 pub fn read_text(&self, path: &Path) -> Result<String, ToolExecutionError> {
343 let shown = path.to_string_lossy();
344 self.read(path, MAX_FILE_BYTES)
345 .and_then(text_of)
346 .map_err(|error| text_error(&shown, error))
347 }
348
349 /// What the file `path` holds before a tool changes it, in one
350 /// [`read`](Workspace::read): `None` when there is none; empty, with
351 /// only its size, when it is too large to read; empty, with no state,
352 /// when it is no regular file or could not be read.
353 pub(crate) fn previous(&self, path: &Path) -> Option<Previous> {
354 Previous::read(self.read(path, MAX_FILE_BYTES))
355 }
356}
357
358/// The whole text of a file read with a limit of [`MAX_FILE_BYTES`]:
359/// refused when it is larger or not UTF-8.
360pub(crate) fn text_of(contents: Contents) -> io::Result<String> {
361 if contents.size > MAX_FILE_BYTES {
362 return Err(too_large(contents.size));
363 }
364 String::from_utf8(contents.bytes).map_err(|_| not_text())
365}
366
367/// The error for a file of `size` bytes, more than [`MAX_FILE_BYTES`].
368pub(crate) fn too_large(size: u64) -> io::Error {
369 io::Error::new(
370 ErrorKind::FileTooLarge,
371 format!(
372 "{} MB; the tools open files up to {} MB",
373 size / (1024 * 1024),
374 MAX_FILE_BYTES / (1024 * 1024)
375 ),
376 )
377}
378
379/// The error for bytes that are not UTF-8 text.
380pub(crate) fn not_text() -> io::Error {
381 io::Error::new(ErrorKind::InvalidData, "stream did not contain valid UTF-8")
382}
383
384/// A model-visible error for a failed text read of `shown`
385/// (`read_text`, [`Workspace::excerpt`]).
386pub(crate) fn text_error(shown: &str, error: io::Error) -> ToolExecutionError {
387 match error.kind() {
388 ErrorKind::NotFound => ToolExecutionError::not_found(format!("{shown}: no such file")),
389 ErrorKind::InvalidInput | ErrorKind::IsADirectory => {
390 ToolExecutionError::invalid_args(format!("{shown} is not a regular file"))
391 }
392 ErrorKind::FileTooLarge => ToolExecutionError::invalid_args(format!("{shown} is {error}")),
393 ErrorKind::InvalidData => ToolExecutionError::invalid_args(match shell_path(shown) {
394 Some(path) => format!(
395 "{shown} is not a text file (not UTF-8); `file {path}` in `shell` shows what it is"
396 ),
397 None => format!("{shown} is not a text file (not UTF-8)"),
398 }),
399 _ => io_error(shown, error),
400 }
401}
402
403/// [`Workspace::excerpt`] as it is by default: the whole file read and cut
404/// here.
405pub(crate) fn excerpt_of<W: Workspace + ?Sized>(
406 workspace: &W,
407 path: &Path,
408 first: usize,
409 count: usize,
410) -> io::Result<Excerpt> {
411 let text = text_of(workspace.read(path, MAX_FILE_BYTES)?)?;
412 Ok(Excerpt::of(&text, first, count))
413}
414
415/// `path`'s whole content when it is a regular file of at most `limit`
416/// bytes, as [`Workspace::read_files`] reads each by default.
417pub(crate) fn read_file<W: Workspace + ?Sized>(
418 workspace: &W,
419 path: &Path,
420 limit: u64,
421) -> Option<Vec<u8>> {
422 let small = matches!(workspace.stat(path), Ok(Stat::File { size, .. }) if size <= limit);
423 small
424 .then(|| workspace.read(path, limit).ok())
425 .flatten()
426 .map(|contents| contents.bytes)
427}
428
429/// `path` in this machine's home directory when its first component is
430/// `~`: `None` for any other path, and when the home is unknown.
431pub(crate) fn home_path(path: &Path) -> Option<PathBuf> {
432 let rest = path.strip_prefix("~").ok()?;
433 let home = std::env::home_dir()?;
434 Some(match rest.as_os_str().is_empty() {
435 true => home,
436 false => home.join(rest),
437 })
438}
439
440/// This machine: its file system and its processes.
441#[derive(Clone, Copy, Debug, Default)]
442pub struct Local;
443
444impl Workspace for Local {
445 fn stat(&self, path: &Path) -> io::Result<Stat> {
446 match fs::metadata(path) {
447 Ok(meta) if meta.is_file() => Ok(Stat::File {
448 size: meta.len(),
449 read_only: meta.permissions().readonly(),
450 modified: meta.modified().ok(),
451 }),
452 Ok(meta) if meta.is_dir() => Ok(Stat::Dir),
453 Ok(_) => Ok(Stat::Other),
454 Err(error) if error.kind() == ErrorKind::NotFound => Ok(Stat::Missing),
455 Err(error) => Err(error),
456 }
457 }
458
459 fn read(&self, path: &Path, limit: u64) -> io::Result<Contents> {
460 if !fs::metadata(path)?.is_file() {
461 return Err(io::Error::new(
462 ErrorKind::InvalidInput,
463 "not a regular file",
464 ));
465 }
466 let file = File::open(path)?;
467 let size = file.metadata()?.len();
468 let mut bytes = Vec::new();
469 file.take(limit).read_to_end(&mut bytes)?;
470 Ok(Contents { bytes, size })
471 }
472
473 fn write(&self, path: &Path, bytes: &[u8]) -> io::Result<()> {
474 write_atomic(path, bytes)
475 }
476
477 fn remove(&self, path: &Path) -> io::Result<()> {
478 fs::remove_file(path)
479 }
480
481 fn rename(&self, from: &Path, to: &Path) -> io::Result<()> {
482 if let Some(parent) = to.parent().filter(|parent| !parent.as_os_str().is_empty()) {
483 fs::create_dir_all(parent)?;
484 }
485 match fs::rename(from, to) {
486 Err(error) if error.kind() == ErrorKind::CrossesDevices => {
487 fs::copy(from, to)?;
488 fs::remove_file(from)
489 }
490 moved => moved,
491 }
492 }
493
494 /// `~` is this machine's home directory, when it is known.
495 fn join(&self, base: &Path, path: &Path) -> PathBuf {
496 home_path(path).unwrap_or_else(|| base.join(path))
497 }
498
499 fn canonical(&self, path: &Path) -> PathBuf {
500 let joined = std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf());
501 let real = joined.ancestors().find_map(|ancestor| {
502 let real = fs::canonicalize(ancestor).ok()?;
503 Some((real, joined.strip_prefix(ancestor).ok()?))
504 });
505 let (mut out, rest) = real.unwrap_or((PathBuf::new(), &joined));
506 for component in rest.components() {
507 match component {
508 Component::ParentDir => {
509 out.pop();
510 }
511 Component::CurDir => {}
512 other => out.push(other),
513 }
514 }
515 out
516 }
517
518 fn files(&self, root: &Path, glob: Option<&str>, listing: Listing) -> io::Result<Vec<PathBuf>> {
519 let mut walk = WalkBuilder::new(root);
520 match listing {
521 Listing::All => walk.standard_filters(false),
522 Listing::Visible | Listing::Hidden => walk.hidden(false).filter_entry(move |entry| {
523 entry.depth() == 0 || listing.keeps(Path::new(entry.file_name()))
524 }),
525 };
526 if let Some(glob) = glob {
527 let overrides = OverrideBuilder::new(root)
528 .add(glob)
529 .and_then(|builder| builder.build())
530 .map_err(|error| {
531 io::Error::new(ErrorKind::InvalidInput, format!("bad glob: {error}"))
532 })?;
533 walk.overrides(overrides);
534 }
535 // Only regular files: symbolic links are not followed.
536 Ok(walk
537 .build()
538 .flatten()
539 .filter(|entry| entry.file_type().is_some_and(|kind| kind.is_file()))
540 .map(ignore::DirEntry::into_path)
541 .collect())
542 }
543
544 fn spawn(
545 &self,
546 launcher: &Launcher,
547 dir: Option<&Path>,
548 program: &OsStr,
549 args: &[OsString],
550 how: Spawn,
551 ) -> io::Result<Process> {
552 match dir {
553 Some(dir) => launcher.clone().in_dir(dir).spawn(program, args, how),
554 None => launcher.spawn(program, args, how),
555 }
556 }
557
558 /// The system's file events under `root`, filtered as
559 /// [`files`](Workspace::files) lists with `listing`, gathered into a
560 /// batch until no event came for 50 ms. A `root` that does not exist
561 /// yet is looked at every second, as the default does.
562 fn watch(self: Arc<Self>, root: &Path, recursive: bool, listing: Listing) -> io::Result<Watch> {
563 crate::watch::notified(root, recursive, listing)
564 }
565}
566
567/// Whether `path` is hidden: its name starts with a `.`, such as `.env` or
568/// `.github/`.
569pub(crate) fn is_hidden(path: &Path) -> bool {
570 path.file_name()
571 .is_some_and(|name| name.as_encoded_bytes().starts_with(b"."))
572}
573
574#[cfg(test)]
575pub(crate) mod tests;