The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
//! What the file manager does to files, and how it describes them: new files and folders, a
//! rename, copies and moves named as Finder and Nautilus name them ("name copy", "name copy 2"),
//! the Trash as freedesktop.org's spec has it, and a size, a date and a kind for the list view.
use std::fs;
use std::io::{self, Write};
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};
use super::name_of;
/// Whether [name] can be given to a new thing in [dir] (or to the thing called [was] there): not
/// empty, no `/`, not `.` or `..`, nothing there by that name already.
pub(super) fn check_name(dir: &Path, name: &str, was: Option<&str>) -> Result<(), String> {
if name.trim().is_empty() { return Err("A name is needed".into()) }
if name.contains('/') { return Err("A name can't contain /".into()) }
if name == "." || name == ".." { return Err(format!("'{name}' can't be a name")) }
if Some(name) != was && dir.join(name).symlink_metadata().is_ok() { return Err(format!("'{name}' is already here")) }
Ok(())
}
pub(super) fn new_file(dir: &Path, name: &str) -> io::Result<()> {
fs::OpenOptions::new().write(true).create_new(true).open(dir.join(name)).map(|_| ())
}
pub(super) fn new_folder(dir: &Path, name: &str) -> io::Result<()> { fs::create_dir(dir.join(name)) }
/// [from] called [name] in its folder; where it is now.
pub(super) fn rename(from: &Path, name: &str) -> io::Result<PathBuf> {
let to = from.with_file_name(name);
fs::rename(from, &to)?;
Ok(to)
}
/// [name] in [dir] if nothing has it, else Finder's copy names: `stem copy.ext`, `stem copy 2.ext`…
/// (a folder's whole name is its stem).
pub(super) fn free_name(dir: &Path, name: &str, folder: bool) -> String {
if dir.join(name).symlink_metadata().is_err() { return name.to_string() }
let (stem, ext) = match name.rfind('.') { Some(i) if i > 0 && !folder => name.split_at(i), _ => (name, "") };
(1..).map(|n| if n == 1 { format!("{stem} copy{ext}") } else { format!("{stem} copy {n}{ext}") })
.find(|c| dir.join(c).symlink_metadata().is_err()).unwrap_or_default()
}
/// A link at [to] saying what [from] said. On Windows a link says whether it leads to a folder.
fn link_to(target: &Path, from: &Path, to: &Path) -> io::Result<()> {
#[cfg(unix)]
{ let _ = from; std::os::unix::fs::symlink(target, to) }
#[cfg(windows)]
{
if fs::metadata(from).is_ok_and(|m| m.is_dir()) { std::os::windows::fs::symlink_dir(target, to) } else { std::os::windows::fs::symlink_file(target, to) }
}
}
/// [from] copied to [to], a folder with all it holds (a link as a link).
pub(super) fn copy_all(from: &Path, to: &Path) -> io::Result<()> {
let meta = fs::symlink_metadata(from)?;
if meta.file_type().is_symlink() { return link_to(&fs::read_link(from)?, from, to) }
if !meta.is_dir() { return fs::copy(from, to).map(|_| ()) }
fs::create_dir(to)?;
for e in fs::read_dir(from)? { let e = e?; copy_all(&e.path(), &to.join(e.file_name()))? }
fs::set_permissions(to, meta.permissions())
}
/// [path] gone for good (a folder with all it holds; a link, not what it points to).
pub(super) fn remove_all(path: &Path) -> io::Result<()> {
if fs::symlink_metadata(path)?.is_dir() { fs::remove_dir_all(path) } else { fs::remove_file(path) }
}
fn cross_device(e: &io::Error) -> bool { e.raw_os_error() == Some(libc::EXDEV) }
/// [from] moved to [to]: renamed, or across file systems copied and then removed.
pub(super) fn move_to(from: &Path, to: &Path) -> io::Result<()> {
match fs::rename(from, to) {
Err(e) if cross_device(&e) => { copy_all(from, to)?; remove_all(from) }
r => r,
}
}
/// Paste: [paths] copied (moved, [cut]) into [dest], each under a free name. The names they have
/// there, and what went wrong with the others.
pub(super) fn paste(paths: &[PathBuf], cut: bool, dest: &Path) -> (Vec<String>, Vec<String>) {
let (mut done, mut failed) = (Vec::new(), Vec::new());
for p in paths {
let name = name_of(p);
let folder = p.is_dir();
if folder && dest.starts_with(p) { failed.push(format!("'{name}' can't go inside itself")); continue }
// (Cut and pasted where it is: it stays.)
if cut && p.parent() == Some(dest) { done.push(name); continue }
let to = free_name(dest, &name, folder);
let r = if cut { move_to(p, &dest.join(&to)) } else { copy_all(p, &dest.join(&to)) };
match r { Ok(()) => done.push(to), Err(e) => failed.push(format!("'{name}': {e}")) }
}
(done, failed)
}
// ── the Trash ────────────────────────────────────────────────────────────────
/// What a person calls it here, in what the file manager says.
pub(super) const TRASH_NAME: &str = if cfg!(windows) { "Recycle Bin" } else { "Trash" };
/// The home Trash: $XDG_DATA_HOME/Trash, else ~/.local/share/Trash. On Windows nothing: the Recycle Bin has no folder to name.
pub(super) fn trash_home() -> PathBuf {
if cfg!(windows) { return PathBuf::new() }
let data = std::env::var_os("XDG_DATA_HOME").map(PathBuf::from).filter(|p| p.is_absolute())
.unwrap_or_else(|| super::home().join(".local/share"));
data.join("Trash")
}
/// [path] (absolute) into the Recycle Bin, with no dialog of Windows' own: hn has asked already. The one exception is a drive with
/// no Recycle Bin (a network share), where FOF_ALLOWUNDO alone would delete it for good: FOF_WANTNUKEWARNING has Windows ask first,
/// and a no comes back as aborted, which hn's own question to delete it for good then follows.
#[cfg(windows)]
fn recycle(path: &Path) -> io::Result<()> {
use std::os::windows::ffi::OsStrExt;
use windows_sys::Win32::UI::Shell::{FO_DELETE, FOF_ALLOWUNDO, FOF_NOCONFIRMATION, FOF_NOERRORUI, FOF_SILENT, FOF_WANTNUKEWARNING, SHFILEOPSTRUCTW, SHFileOperationW};
// A list ended by two NULs, as the call reads it.
let from: Vec<u16> = path.as_os_str().encode_wide().chain([0, 0]).collect();
// SAFETY: the list outlives the call, and every other field is zero, which the call allows.
let (result, aborted) = unsafe {
let mut operation: SHFILEOPSTRUCTW = std::mem::zeroed();
operation.wFunc = FO_DELETE;
operation.pFrom = from.as_ptr();
operation.fFlags = (FOF_ALLOWUNDO | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_SILENT | FOF_WANTNUKEWARNING) as u16;
(SHFileOperationW(&mut operation), operation.fAnyOperationsAborted != 0)
};
if result != 0 { return Err(io::Error::other(format!("Windows could not move it to the Recycle Bin (code {result})"))) }
if aborted { return Err(io::Error::other("it cannot go to the Recycle Bin")) }
Ok(())
}
/// Why something could not go to the Trash: across file systems (it would be copied), or another.
pub(super) enum TrashError { CrossDevice, Other(io::Error) }
impl std::fmt::Display for TrashError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self { TrashError::CrossDevice => write!(f, "it is on another drive"), TrashError::Other(e) => write!(f, "{e}") }
}
}
/// [path] (absolute) into the Trash at [trash], as the freedesktop.org Trash spec has it: its
/// `info/NAME.trashinfo` (its Path, URL-escaped, and DeletionDate) made first and exclusively, then
/// it renamed into `files/NAME` — NAME its name, or `stem.2.ext`… when that is taken. Where it is.
pub(super) fn trash(path: &Path, trash: &Path) -> Result<PathBuf, TrashError> {
#[cfg(windows)]
if trash.as_os_str().is_empty() { return recycle(path).map(|()| PathBuf::new()).map_err(TrashError::Other) }
let other = TrashError::Other;
let (files, info) = (trash.join("files"), trash.join("info"));
let new = !trash.exists();
fs::create_dir_all(&files).and_then(|_| fs::create_dir_all(&info)).map_err(other)?;
#[cfg(unix)]
if new { use std::os::unix::fs::PermissionsExt; let _ = fs::set_permissions(trash, fs::Permissions::from_mode(0o700)); }
#[cfg(windows)]
let _ = new;
let name = name_of(path);
let body = format!("[Trash Info]\nPath={}\nDeletionDate={}\n", escape(path), iso_now());
let (stem, ext) = match name.rfind('.') { Some(i) if i > 0 => name.split_at(i), _ => (name.as_str(), "") };
for n in 1.. {
let candidate = if n == 1 { name.clone() } else { format!("{stem}.{n}{ext}") };
let info_path = info.join(format!("{candidate}.trashinfo"));
let mut f = match fs::OpenOptions::new().write(true).create_new(true).open(&info_path) {
Ok(f) => f,
Err(e) if e.kind() == io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(other(e)),
};
// (A file there with no info of its own: another name.)
let to = files.join(&candidate);
if to.symlink_metadata().is_ok() { drop(f); let _ = fs::remove_file(&info_path); continue }
if let Err(e) = f.write_all(body.as_bytes()) { let _ = fs::remove_file(&info_path); return Err(other(e)) }
return match fs::rename(path, &to) {
Ok(()) => Ok(to),
Err(e) => { let _ = fs::remove_file(&info_path); Err(if cross_device(&e) { TrashError::CrossDevice } else { other(e) }) }
};
}
unreachable!()
}
/// A path as the spec's Path= key has it: URL-escaped, its slashes kept.
fn escape(path: &Path) -> String {
let mut out = String::new();
for &b in path.as_os_str().as_encoded_bytes() {
if b.is_ascii_alphanumeric() || b"/-_.~".contains(&b) { out.push(b as char) } else { out.push_str(&format!("%{b:02X}")) }
}
out
}
fn secs(t: SystemTime) -> i64 { t.duration_since(UNIX_EPOCH).map(|d| d.as_secs() as i64).unwrap_or(0) }
/// Now as DeletionDate has it: local time, YYYY-MM-DDThh:mm:ss.
fn iso_now() -> String {
let tm = crate::format::local_tm(secs(SystemTime::now()));
format!("{:04}-{:02}-{:02}T{:02}:{:02}:{:02}", tm.tm_year + 1900, tm.tm_mon + 1, tm.tm_mday, tm.tm_hour, tm.tm_min, tm.tm_sec)
}
// ── what the list view says ──────────────────────────────────────────────────
/// A size as a file manager says it (1000s, as Nautilus and Finder count): 512 B, 4.2 KB, 120 KB.
pub(super) fn human_size(n: u64) -> String {
if n < 1000 { return format!("{n} B") }
let mut v = n as f64;
for unit in ["KB", "MB", "GB", "TB", "PB"] {
v /= 1000.0;
if v < 1000.0 || unit == "PB" { return if v < 10.0 { format!("{v:.1} {unit}") } else { format!("{v:.0} {unit}") } }
}
unreachable!()
}
/// When a thing was changed, as Finder says it: `Today 10:42` the same day, `Oct 3` the same year,
/// else `2025-11-02`.
pub(super) fn when(t: SystemTime, now: SystemTime) -> String {
let (a, b) = (crate::format::local_tm(secs(t)), crate::format::local_tm(secs(now)));
const MONTHS: [&str; 12] = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
if (a.tm_year, a.tm_yday) == (b.tm_year, b.tm_yday) { format!("Today {:02}:{:02}", a.tm_hour, a.tm_min) }
else if a.tm_year == b.tm_year { format!("{} {}", MONTHS[a.tm_mon.clamp(0, 11) as usize], a.tm_mday) }
else { format!("{:04}-{:02}-{:02}", a.tm_year + 1900, a.tm_mon + 1, a.tm_mday) }
}
/// What kind of thing a name is, by its extension.
pub(super) fn kind(name: &str, folder: bool) -> String {
if folder { return "Folder".into() }
let ext = name.rsplit_once('.').filter(|(s, _)| !s.is_empty()).map(|(_, x)| x.to_ascii_lowercase()).unwrap_or_default();
let known = match ext.as_str() {
"rs" => "Rust source", "py" => "Python script", "js" | "mjs" | "cjs" | "jsx" => "JavaScript", "ts" | "tsx" => "TypeScript",
"go" => "Go source", "c" | "h" => "C source", "cpp" | "cc" | "hpp" => "C++ source", "sh" | "bash" | "zsh" | "fish" => "Shell script",
"md" => "Markdown", "txt" => "Plain text", "log" => "Log", "json" => "JSON", "toml" => "TOML", "yaml" | "yml" => "YAML",
"html" | "htm" => "HTML", "css" => "CSS", "pdf" => "PDF document", "csv" => "CSV",
"png" | "jpg" | "jpeg" | "gif" | "svg" | "webp" | "bmp" | "ico" => "Image",
"zip" | "tar" | "gz" | "tgz" | "xz" | "bz2" | "zst" | "7z" | "rar" => "Archive",
"mp3" | "wav" | "flac" | "ogg" | "m4a" => "Audio", "mp4" | "mkv" | "webm" | "mov" | "avi" => "Video",
"" => "File",
_ => return format!("{} file", ext.to_uppercase()),
};
known.into()
}
#[cfg(test)]
mod tests {
use super::*;
use std::time::Duration;
fn scratch() -> PathBuf {
let d = std::env::temp_dir().join(format!("hn-files-ops-{}", uuid::Uuid::new_v4()));
fs::create_dir_all(&d).unwrap();
d
}
#[test]
fn copies_are_named_as_finder_names_them() {
let d = scratch();
fs::write(d.join("a.txt"), "x").unwrap();
fs::create_dir(d.join("dir.d")).unwrap();
assert_eq!(free_name(&d, "b.txt", false), "b.txt");
assert_eq!(free_name(&d, "a.txt", false), "a copy.txt");
fs::write(d.join("a copy.txt"), "").unwrap();
assert_eq!(free_name(&d, "a.txt", false), "a copy 2.txt");
assert_eq!(free_name(&d, "dir.d", true), "dir.d copy");
// Pasted where they are: copies, the folder with what it holds.
fs::write(d.join("dir.d/in"), "y").unwrap();
let (done, failed) = paste(&[d.join("a.txt"), d.join("dir.d")], false, &d);
assert_eq!((done, failed.len()), (vec!["a copy 2.txt".to_string(), "dir.d copy".to_string()], 0));
assert_eq!(fs::read_to_string(d.join("dir.d copy/in")).unwrap(), "y");
// Into itself: refused.
let (_, failed) = paste(&[d.join("dir.d")], false, &d.join("dir.d"));
assert_eq!(failed.len(), 1);
let _ = fs::remove_dir_all(&d);
}
#[test]
fn cut_and_paste_moves_and_clashes_get_a_copy_name() {
let d = scratch();
fs::create_dir(d.join("to")).unwrap();
fs::write(d.join("x.txt"), "1").unwrap();
fs::write(d.join("to/x.txt"), "2").unwrap();
let (done, _) = paste(&[d.join("x.txt")], true, &d.join("to"));
assert_eq!(done, ["x copy.txt"]);
assert!(!d.join("x.txt").exists());
assert_eq!(fs::read_to_string(d.join("to/x copy.txt")).unwrap(), "1");
assert_eq!(fs::read_to_string(d.join("to/x.txt")).unwrap(), "2", "nothing overwritten");
let _ = fs::remove_dir_all(&d);
}
#[test]
fn the_trash_gets_the_file_and_its_info() {
let d = scratch();
let t = d.join("Trash");
fs::write(d.join("my file.txt"), "x").unwrap();
let to = trash(&d.join("my file.txt"), &t).ok().unwrap();
assert_eq!(to, t.join("files/my file.txt"));
assert!(!d.join("my file.txt").exists());
let info = fs::read_to_string(t.join("info/my file.txt.trashinfo")).unwrap();
assert!(info.starts_with("[Trash Info]\nPath="), "{info}");
assert!(info.contains("my%20file.txt\n") && info.contains("DeletionDate=2"), "{info}");
// A second of the same name: its own.
fs::write(d.join("my file.txt"), "y").unwrap();
assert_eq!(trash(&d.join("my file.txt"), &t).ok().unwrap(), t.join("files/my file.2.txt"));
assert!(t.join("info/my file.2.txt.trashinfo").exists());
let _ = fs::remove_dir_all(&d);
}
#[test]
fn names_are_checked() {
let d = scratch();
fs::write(d.join("here"), "").unwrap();
assert!(check_name(&d, "", None).is_err() && check_name(&d, " ", None).is_err());
assert!(check_name(&d, "a/b", None).is_err() && check_name(&d, "..", None).is_err());
assert_eq!(check_name(&d, "here", None), Err("'here' is already here".into()));
assert!(check_name(&d, "here", Some("here")).is_ok() && check_name(&d, "new", None).is_ok());
let _ = fs::remove_dir_all(&d);
}
#[test]
fn sizes_dates_and_kinds_read_as_a_file_manager_says_them() {
assert_eq!((human_size(512), human_size(4200), human_size(120_000), human_size(1_300_000)), ("512 B".into(), "4.2 KB".into(), "120 KB".into(), "1.3 MB".into()));
let now = SystemTime::now();
assert!(when(now, now).starts_with("Today "));
let old = when(now - Duration::from_secs(400 * 86400), now);
assert!(old.len() == 10 && old.as_bytes()[4] == b'-', "{old}");
assert_eq!((kind("a.rs", false), kind("x", true), kind("a.xyz", false), kind("Makefile", false)), ("Rust source".into(), "Folder".into(), "XYZ file".into(), "File".into()));
}
}