farhand_core/

config.rs

//! Configuration: where the remote is, what the local side may touch, and the
//! limits every operation runs under.
//!
//! Resolution order (first hit wins):
//! 1. an explicit path (`--config`),
//! 2. `$FARHAND_CONFIG`,
//! 3. `.farhand.toml` in the working directory or the nearest folder above
//!    it, short of the home directory and the filesystem root,
//! 4. `~/.config/farhand/config.toml`.
//!
//! Whether FarHand is *active* in a directory — takes the agent's local
//! tools away and puts its remote ones in — depends on where the config
//! came from: a project file, an explicit path or the environment always
//! activate; the global file activates only when its `activation` is
//! `"always"` rather than the default `"project"`.
//!
//! A project file (any file named `.farhand.toml`, however it was found:
//! by directory, `--config` or `$FARHAND_CONFIG`) can arrive with a cloned
//! repository, so it may only tighten what the global config allows: it
//! cannot loosen `[approval]`, allow local folders outside its own
//! directory, or move the audit log. Such settings are ignored and reported
//! in [`Loaded::notices`]. A file under any other name, passed with
//! `--config` or `$FARHAND_CONFIG`, is the user's own choice and is trusted
//! like the global config.
//!
//! The global config may leave out `[remote]`: with the default
//! `activation = "project"` it is only the floor project files are measured
//! against and the source of the user's deny lists.

use std::collections::BTreeMap;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::error::{Error, Result};

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Config {
    /// When the global config alone should make a session remote.
    #[serde(default)]
    pub activation: ActivationMode,
    /// Required everywhere except in the global config, which needs it only
    /// for `activation = "always"`.
    #[serde(default)]
    pub remote: Option<RemoteConfig>,
    #[serde(default)]
    pub local: LocalConfig,
    #[serde(default)]
    pub limits: Limits,
    #[serde(default)]
    pub audit: AuditConfig,
    #[serde(default)]
    pub guard: GuardConfig,
    #[serde(default)]
    pub approval: ApprovalConfig,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RemoteConfig {
    /// SSH destination: an alias from `~/.ssh/config`, or `user@host`.
    /// Authentication, jump hosts, ports and keys all come from the user's
    /// own OpenSSH configuration; FarHand never handles credentials itself.
    pub host: String,
    /// Directory relative paths resolve against and commands start in.
    /// Absolute (`/srv/app`, `C:\\work`), or `~` / `~/...` for the remote
    /// user's home.
    pub workdir: String,
    /// What the remote runs. Detected on connect from the SFTP root, so
    /// `auto` is fine; set it explicitly so the model is told before the
    /// first command which shell it is writing for.
    #[serde(default)]
    pub os: Os,
    /// Shell that runs every command, as argv. On a POSIX remote the
    /// command text is appended as one final argument, so the last element
    /// must accept a script (`-c`, `-lc`, ...). On Windows only the first
    /// element is used, as the PowerShell executable (`powershell.exe` by
    /// default; set `["pwsh"]` for PowerShell 7).
    #[serde(default = "default_shell")]
    pub shell: Vec<String>,
    #[serde(default = "default_connect_timeout")]
    pub connect_timeout_secs: u64,
    /// Passed to ssh as `ServerAliveInterval`; keeps NAT tables warm.
    #[serde(default = "default_alive_interval")]
    pub server_alive_interval_secs: u64,
}

impl RemoteConfig {
    fn validate(&mut self) -> Result<()> {
        if self.host.trim().is_empty() {
            return Err(Error::Config("remote.host is empty".into()));
        }
        if self.host.starts_with('-') {
            return Err(Error::Config("remote.host may not start with '-'".into()));
        }
        let raw = self.workdir.trim();
        let w = raw.trim_end_matches(['/', '\\']);
        let w = if w.is_empty() && raw.starts_with('/') {
            "/".to_string()
        } else if is_drive_root(raw) {
            // `C:\` keeps its separator; `C:` alone would be drive-relative.
            format!("{}\\", &raw[..2])
        } else {
            w.to_string()
        };
        let windows_abs = w.len() >= 3
            && w.as_bytes()[0].is_ascii_alphabetic()
            && w.as_bytes()[1] == b':'
            && (w.as_bytes()[2] == b'\\' || w.as_bytes()[2] == b'/');
        if !(w.starts_with('/')
            || w == "~"
            || w.starts_with("~/")
            || w.starts_with("~\\")
            || windows_abs)
        {
            return Err(Error::Config(
                "remote.workdir must be an absolute path (`/srv/app`, `C:\\work`) or start with `~` \
                 (the remote home)"
                    .into(),
            ));
        }
        self.workdir = w;
        if self.shell.is_empty() {
            return Err(Error::Config("remote.shell is empty".into()));
        }
        Ok(())
    }
}

pub fn default_shell() -> Vec<String> {
    vec!["bash".into(), "-lc".into()]
}

/// The remote operating system family.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Os {
    #[default]
    Auto,
    /// Linux, macOS, BSD: a POSIX shell, `timeout(1)`, `base64(1)`.
    Posix,
    /// Windows with OpenSSH Server: commands run in PowerShell.
    Windows,
}
fn default_connect_timeout() -> u64 {
    20
}
fn default_alive_interval() -> u64 {
    30
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct LocalConfig {
    /// The only local directories the model may list, read, upload from or
    /// download into. Empty means the local filesystem is fully closed.
    #[serde(default)]
    pub allowed_dirs: Vec<PathBuf>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Limits {
    #[serde(default = "default_command_timeout")]
    pub command_timeout_secs: u64,
    #[serde(default = "default_max_command_timeout")]
    pub max_command_timeout_secs: u64,
    #[serde(default = "default_max_output_bytes")]
    pub max_output_bytes: usize,
    #[serde(default = "default_max_read_bytes")]
    pub max_read_bytes: usize,
    #[serde(default = "default_max_transfer_bytes")]
    pub max_transfer_bytes: u64,
    #[serde(default = "default_max_transfer_files")]
    pub max_transfer_files: usize,
}

fn default_command_timeout() -> u64 {
    120
}
fn default_max_command_timeout() -> u64 {
    1800
}
fn default_max_output_bytes() -> usize {
    100 * 1024
}
fn default_max_read_bytes() -> usize {
    512 * 1024
}
fn default_max_transfer_bytes() -> u64 {
    1024 * 1024 * 1024
}
fn default_max_transfer_files() -> usize {
    5000
}

impl Default for Limits {
    fn default() -> Self {
        Self {
            command_timeout_secs: default_command_timeout(),
            max_command_timeout_secs: default_max_command_timeout(),
            max_output_bytes: default_max_output_bytes(),
            max_read_bytes: default_max_read_bytes(),
            max_transfer_bytes: default_max_transfer_bytes(),
            max_transfer_files: default_max_transfer_files(),
        }
    }
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AuditConfig {
    /// Directory for the JSONL audit log. Defaults to
    /// `~/.local/share/farhand/audit`. There is deliberately no way to turn
    /// the log off: every remote action is recorded.
    pub log_dir: Option<PathBuf>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GuardConfig {
    /// Extra glob patterns (matched against the full local path and the
    /// basename) that may never be uploaded. Added to the built-in list.
    #[serde(default)]
    pub deny_globs: Vec<String>,
    /// Extra regular expressions that mark content as secret.
    #[serde(default)]
    pub deny_content: Vec<String>,
}

/// Whether the global config turns every session remote, or only the
/// projects that carry their own `.farhand.toml`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ActivationMode {
    /// Every session is remote.
    Always,
    /// Only directories with a `.farhand.toml` are remote; everywhere else
    /// the agent keeps its local tools and FarHand offers none. The
    /// default: installing FarHand must not take a machine's local tools
    /// away by surprise.
    #[default]
    Project,
}

/// Where a loaded config came from.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Source {
    Explicit,
    Env,
    Project,
    Global,
}

impl Source {
    /// A path handed over by `--config` or `$FARHAND_CONFIG` is a project
    /// file when it is named like one: it gets no more trust for having
    /// been passed by path.
    fn by_name(path: &Path, otherwise: Source) -> Source {
        if path.file_name() == Some(".farhand.toml".as_ref()) {
            Source::Project
        } else {
            otherwise
        }
    }

    pub fn as_str(self) -> &'static str {
        match self {
            Source::Explicit => "explicit",
            Source::Env => "env",
            Source::Project => "project",
            Source::Global => "global",
        }
    }

    /// `"project"` for a file that may only tighten the global config,
    /// `"global"` for one trusted like the global config itself.
    pub fn trust(self) -> &'static str {
        match self {
            Source::Project => "project",
            Source::Explicit | Source::Env | Source::Global => "global",
        }
    }
}

/// A config together with where it was found and whether it activates
/// FarHand in the directory it was resolved for.
#[derive(Debug, Clone)]
pub struct Loaded {
    pub config: Config,
    pub path: PathBuf,
    pub source: Source,
    /// Settings a project file tried and was not allowed to make, in words
    /// for the user. Empty for every other source.
    pub notices: Vec<String>,
}

impl Loaded {
    pub fn active(&self) -> bool {
        match self.source {
            Source::Explicit | Source::Env | Source::Project => true,
            Source::Global => {
                self.config.activation == ActivationMode::Always && self.config.remote.is_some()
            }
        }
    }
}

/// Whether an agent should stop and ask the user before a mutating tool
/// runs. FarHand itself has no UI; this is the one knob every agent entry
/// translates into that agent's own permission system.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ApprovalMode {
    /// Prompt before every mutating tool; read-only tools run freely.
    /// The default.
    Ask,
    /// Run everything without prompting; the audit log is the only record.
    Auto,
    /// Prompt before every tool, read-only ones included.
    Strict,
}

impl ApprovalMode {
    pub fn as_str(self) -> &'static str {
        match self {
            ApprovalMode::Ask => "ask",
            ApprovalMode::Auto => "auto",
            ApprovalMode::Strict => "strict",
        }
    }
}

/// The tools that change something on the remote or in the outbox.
pub const MUTATING_TOOLS: &[&str] = &[
    "remote_shell",
    "remote_spawn",
    "remote_kill",
    "remote_write",
    "remote_edit",
    "upload",
    "download",
];

/// The tools that only look.
pub const READ_ONLY_TOOLS: &[&str] = &[
    "remote_read",
    "remote_ls",
    "remote_glob",
    "remote_grep",
    "remote_jobs",
    "local_ls",
    "local_read",
    "remote_info",
];

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ApprovalConfig {
    /// Default for every mutating tool.
    #[serde(default = "default_approval")]
    pub mode: ApprovalMode,
    /// Per-tool overrides, keyed by tool name; `ask` or `auto` only.
    #[serde(default)]
    pub tools: BTreeMap<String, ApprovalMode>,
}

fn default_approval() -> ApprovalMode {
    ApprovalMode::Ask
}

impl Default for ApprovalConfig {
    fn default() -> Self {
        Self {
            mode: default_approval(),
            tools: BTreeMap::new(),
        }
    }
}

impl ApprovalConfig {
    /// For every tool, whether it prompts (`Ask`) or runs (`Auto`),
    /// overrides applied. `Strict` never appears in the result.
    pub fn effective(&self) -> BTreeMap<&'static str, ApprovalMode> {
        let mutating = match self.mode {
            ApprovalMode::Auto => ApprovalMode::Auto,
            ApprovalMode::Ask | ApprovalMode::Strict => ApprovalMode::Ask,
        };
        let read_only = match self.mode {
            ApprovalMode::Strict => ApprovalMode::Ask,
            ApprovalMode::Ask | ApprovalMode::Auto => ApprovalMode::Auto,
        };
        MUTATING_TOOLS
            .iter()
            .map(|t| (*t, mutating))
            .chain(READ_ONLY_TOOLS.iter().map(|t| (*t, read_only)))
            .map(|(t, m)| (t, self.tools.get(t).copied().unwrap_or(m)))
            .collect()
    }
}

impl Config {
    pub fn example() -> &'static str {
        EXAMPLE
    }

    /// Load following the resolution order in the module docs, with the
    /// project file looked for in the process's working directory.
    pub fn load(explicit: Option<&Path>) -> Result<(Self, PathBuf)> {
        let l = Self::load_in(None, explicit)?;
        Ok((l.config, l.path))
    }

    /// Load following the resolution order, with the project file looked
    /// for in `cwd` (default: the process's working directory).
    pub fn load_in(cwd: Option<&Path>, explicit: Option<&Path>) -> Result<Loaded> {
        let (path, source) = match explicit {
            // An agent entry may hand the project file over by path.
            Some(p) => (p.to_path_buf(), Source::by_name(p, Source::Explicit)),
            None => Self::locate(cwd)?,
        };
        let text = std::fs::read_to_string(&path)
            .map_err(|e| Error::Config(format!("cannot read {}: {e}", path.display())))?;
        // Relative `allowed_dirs` entries are resolved against the file's own
        // directory, but only for a per-project file: the global config
        // belongs to no directory, so `"."` would mean nothing there.
        let base = match source {
            Source::Global => None,
            _ => path.parent().map(Path::to_path_buf),
        };
        let (config, notices) = if source == Source::Project {
            let baseline = Self::load_global()?;
            Self::parse_project(&text, base.as_deref(), baseline.as_ref())?
        } else {
            (Self::parse_at(&text, base.as_deref())?, Vec::new())
        };
        Ok(Loaded {
            config,
            path,
            source,
            notices,
        })
    }

    /// The global config, if there is one. It is the floor a project file
    /// is measured against and the source of the user's own deny lists, so
    /// one that exists but does not load is an error: falling back to the
    /// defaults would quietly drop both.
    pub fn load_global() -> Result<Option<Self>> {
        let global = Self::global_path();
        if global.symlink_metadata().is_err() {
            return Ok(None);
        }
        std::fs::read_to_string(&global)
            .map_err(Error::from)
            .and_then(|t| Self::parse(&t))
            .map(Some)
            .map_err(|e| {
                Error::Config(format!(
                    "the global config {} does not load ({e}); fix or remove it",
                    global.display()
                ))
            })
    }

    /// Parse a project file living in `base`, measured against `baseline`
    /// (the global config, if there is one): settings that would loosen it
    /// are dropped, and each drop is described in the returned notices.
    pub fn parse_project(
        text: &str,
        base: Option<&Path>,
        baseline: Option<&Config>,
    ) -> Result<(Self, Vec<String>)> {
        let mut cfg: Config = toml::from_str(text).map_err(|e| Error::Config(e.to_string()))?;
        let mut notices = Vec::new();
        let requested = std::mem::take(&mut cfg.local.allowed_dirs);
        for d in requested {
            if d.is_absolute() || d.to_string_lossy().starts_with('~') {
                notices.push(format!(
                    "local.allowed_dirs entry `{}` ignored: a project .farhand.toml may only \
                     allow folders inside its own directory (`\".\"`, `\"assets\"`); put other \
                     folders in the global config",
                    d.display()
                ));
            } else {
                cfg.local.allowed_dirs.push(d);
            }
        }
        if let Some(d) = cfg.audit.log_dir.take() {
            notices.push(format!(
                "audit.log_dir `{}` ignored: only the global config may move the audit log",
                d.display()
            ));
        }
        cfg.validate(base)?;
        // A relative entry is only inside the project as written. A cloned
        // repository can carry `assets -> ~/Documents` next to its
        // `.farhand.toml`, so each entry must still be inside the project
        // folder once symlinks are resolved, and it is kept in that resolved
        // form so a link swapped in later changes nothing.
        let project = base
            .map(|b| {
                if b.as_os_str().is_empty() {
                    Path::new(".")
                } else {
                    b
                }
            })
            .and_then(|b| b.canonicalize().ok());
        for d in std::mem::take(&mut cfg.local.allowed_dirs) {
            match (d.canonicalize(), &project) {
                (Ok(c), Some(p)) if c.starts_with(p) && c.is_dir() => {
                    cfg.local.allowed_dirs.push(c)
                }
                (Ok(_), _) => notices.push(format!(
                    "local.allowed_dirs entry `{}` ignored: it is not a folder inside the \
                     project directory once symlinks are resolved",
                    d.display()
                )),
                (Err(e), _) => notices.push(format!(
                    "local.allowed_dirs entry `{}` ignored: {e}",
                    d.display()
                )),
            }
        }
        cfg.audit.log_dir = baseline.and_then(|b| b.audit.log_dir.clone());

        let floor = baseline.map(|b| b.approval.clone()).unwrap_or_default();
        let floor = floor.effective();
        let mut loosened = Vec::new();
        let mut tools = BTreeMap::new();
        for (tool, mode) in cfg.approval.effective() {
            let mode = if mode == ApprovalMode::Auto && floor[tool] == ApprovalMode::Ask {
                loosened.push(tool);
                ApprovalMode::Ask
            } else {
                mode
            };
            tools.insert(tool.to_string(), mode);
        }
        if !loosened.is_empty() {
            notices.push(format!(
                "[approval] `auto` ignored for {}: a project .farhand.toml may make approval \
                 stricter, not looser; set it in the global config",
                loosened.join(", ")
            ));
            // Every tool spelled out, so `effective()` no longer depends
            // on the mode.
            cfg.approval.tools = tools;
        }

        // The global deny lists stay in force; a project can only add.
        if let Some(b) = baseline {
            for g in &b.guard.deny_globs {
                if !cfg.guard.deny_globs.contains(g) {
                    cfg.guard.deny_globs.push(g.clone());
                }
            }
            for r in &b.guard.deny_content {
                if !cfg.guard.deny_content.contains(r) {
                    cfg.guard.deny_content.push(r.clone());
                }
            }
        }
        Ok((cfg, notices))
    }

    /// Parse the global config, which belongs to no directory:
    /// `allowed_dirs` entries must be absolute or `~/...`, and `[remote]`
    /// is needed only for `activation = "always"`.
    pub fn parse(text: &str) -> Result<Self> {
        Self::parse_at(text, None)
    }

    /// Parse a config file that lives in `base`; relative `allowed_dirs`
    /// entries (`"."`, `"assets"`) are resolved against it. With `base`
    /// `None` this is the global config (see [`Config::parse`]).
    pub fn parse_at(text: &str, base: Option<&Path>) -> Result<Self> {
        let mut cfg: Config = toml::from_str(text).map_err(|e| Error::Config(e.to_string()))?;
        cfg.validate(base)?;
        Ok(cfg)
    }

    fn locate(cwd: Option<&Path>) -> Result<(PathBuf, Source)> {
        if let Some(p) = std::env::var_os("FARHAND_CONFIG") {
            let p = PathBuf::from(p);
            let source = Source::by_name(&p, Source::Env);
            return Ok((p, source));
        }
        let start = match cwd {
            Some(d) => std::path::absolute(d)?,
            None => std::env::current_dir()?,
        };
        if let Some(local) = find_project_file(&start, dirs::home_dir().as_deref()) {
            return Ok((local, Source::Project));
        }
        let p = Self::global_path();
        if p.is_file() {
            return Ok((p, Source::Global));
        }
        Err(Error::NoConfig)
    }

    pub fn global_path() -> PathBuf {
        xdg_dir("XDG_CONFIG_HOME", ".config")
            .join("farhand")
            .join("config.toml")
    }

    /// `base` is the folder the file lives in; `None` means the global
    /// config, which belongs to no folder.
    fn validate(&mut self, base: Option<&Path>) -> Result<()> {
        match &mut self.remote {
            Some(r) => r.validate()?,
            None if base.is_some() => {
                return Err(Error::Config(
                    "[remote] is missing; only the global config may leave it out".into(),
                ))
            }
            None if self.activation == ActivationMode::Always => {
                return Err(Error::Config(
                    "activation = \"always\" needs a [remote] section".into(),
                ))
            }
            None => {}
        }
        if self.limits.command_timeout_secs == 0 || self.limits.max_command_timeout_secs == 0 {
            return Err(Error::Config("timeouts must be positive".into()));
        }
        let mut dirs = Vec::with_capacity(self.local.allowed_dirs.len());
        let home = dirs::home_dir();
        let home_canon = home.as_deref().and_then(|h| h.canonicalize().ok());
        for d in &self.local.allowed_dirs {
            let mut expanded = expand_home(d);
            // `..` would let an entry reach above what it names: above the
            // project folder for a relative entry, anywhere for `~/../x`.
            if expanded
                .components()
                .any(|c| matches!(c, std::path::Component::ParentDir))
            {
                return Err(Error::Config(format!(
                    "local.allowed_dirs entry `{}` may not contain `..`",
                    d.display()
                )));
            }
            if !expanded.is_absolute() {
                // A relative entry names the project folder itself or
                // something inside it.
                let Some(base) = base else {
                    return Err(Error::Config(format!(
                        "local.allowed_dirs entry `{}` is relative, but the global config \
                         belongs to no folder: use an absolute or `~/...` path here (relative \
                         entries belong in a .farhand.toml or a file passed with --config)",
                        d.display()
                    )));
                };
                expanded = base.join(expanded);
            }
            // The allowlist is for a folder the user set aside, never the
            // home directory or anything above it: that would hand every
            // non-credential file to the model.
            let canon = expanded.canonicalize().ok();
            let covers_home = |h: &Path| {
                h.starts_with(&expanded) || canon.as_deref().is_some_and(|c| h.starts_with(c))
            };
            if expanded.parent().is_none()
                || home.as_deref().is_some_and(covers_home)
                || home_canon.as_deref().is_some_and(covers_home)
            {
                return Err(Error::Config(format!(
                    "local.allowed_dirs may not contain `/`, the home directory or a folder \
                     above it ({}); allow a specific folder instead",
                    d.display()
                )));
            }
            dirs.push(expanded);
        }
        self.local.allowed_dirs = dirs;
        if let Some(d) = &self.audit.log_dir {
            self.audit.log_dir = Some(expand_home(d));
        }
        for (t, m) in &self.approval.tools {
            if t == "remote_bash" {
                return Err(Error::Config(
                    "approval.tools: `remote_bash` was renamed to `remote_shell` in 0.2.1".into(),
                ));
            }
            if !MUTATING_TOOLS.contains(&t.as_str()) && !READ_ONLY_TOOLS.contains(&t.as_str()) {
                return Err(Error::Config(format!(
                    "approval.tools: `{t}` is not a tool (one of {}, {})",
                    MUTATING_TOOLS.join(", "),
                    READ_ONLY_TOOLS.join(", ")
                )));
            }
            if *m == ApprovalMode::Strict {
                return Err(Error::Config(format!(
                    "approval.tools.{t}: use `ask` or `auto` (`strict` is a global mode)"
                )));
            }
        }
        Ok(())
    }

    pub fn audit_dir(&self) -> PathBuf {
        self.audit.log_dir.clone().unwrap_or_else(|| {
            xdg_dir("XDG_DATA_HOME", ".local/share")
                .join("farhand")
                .join("audit")
        })
    }
}

/// The `.farhand.toml` in `start` or the nearest folder above it, so a
/// session started in a subfolder or a worktree of the project is still
/// the project's. Folders above `start` stop short of `home` and the
/// filesystem root: a stray file there would claim every folder below it.
fn find_project_file(start: &Path, home: Option<&Path>) -> Option<PathBuf> {
    let here = start.join(".farhand.toml");
    if here.is_file() {
        return Some(here);
    }
    start
        .ancestors()
        .skip(1)
        .take_while(|d| d.parent().is_some() && Some(*d) != home)
        .map(|d| d.join(".farhand.toml"))
        .find(|f| f.is_file())
}

/// `$VAR` if set, else `~/<fallback>`. The XDG layout is used on every
/// platform so the documented paths (`~/.config/farhand`,
/// `~/.local/share/farhand`) are the real ones on macOS too.
fn xdg_dir(var: &str, fallback: &str) -> PathBuf {
    if let Some(v) = std::env::var_os(var) {
        if !v.is_empty() {
            return PathBuf::from(v);
        }
    }
    dirs::home_dir()
        .unwrap_or_else(|| PathBuf::from("."))
        .join(fallback)
}

/// `~` and `~/x` expand to the home directory; anything else is returned as-is.
/// `C:\`, `C:/` or `C:` — a Windows drive root, with or without separator.
fn is_drive_root(s: &str) -> bool {
    let b = s.as_bytes();
    (b.len() == 2 || b.len() == 3)
        && b[0].is_ascii_alphabetic()
        && b[1] == b':'
        && (b.len() == 2 || b[2] == b'\\' || b[2] == b'/')
}

pub fn expand_home(p: &Path) -> PathBuf {
    let s = p.to_string_lossy();
    if s == "~" {
        return dirs::home_dir().unwrap_or_else(|| p.to_path_buf());
    }
    if let Some(rest) = s.strip_prefix("~/") {
        if let Some(home) = dirs::home_dir() {
            return home.join(rest);
        }
    }
    p.to_path_buf()
}

const EXAMPLE: &str = r#"# FarHand configuration.
# As .farhand.toml in a project root, it makes that project remote.
# As ~/.config/farhand/config.toml it is optional: it is the ceiling every
# project file is held to, and with activation = "always" it makes every
# directory remote. Without "always" it may leave out [remote].
# Trust follows the name: a file named .farhand.toml is a project file however
# it is reached; any other file passed with --config / FARHAND_CONFIG is
# trusted like the global config.

# "project" (default): only directories that carry a .farhand.toml are
#            remote; anywhere else the agent keeps its local tools and FarHand
#            stays out of the way.
# "always":  every agent session on this machine is remote, using the
#            [remote] section below.
# Only meaningful in this global file; a project's .farhand.toml is always
# active in its own directory.
# activation = "project"

[remote]
# An alias from ~/.ssh/config or user@host. Keys, ports, jump hosts and
# agent forwarding all come from your OpenSSH config.
host = "devbox"
# Directory on the remote where every command starts and relative paths
# resolve. Absolute, or `~/...` for the remote user's home. Created on
# first connection if it does not exist.
workdir = "~/project"
# os = "auto"              # "posix" or "windows"; detected on connect, but set it so
#                          # the model knows which shell it is writing for
# shell = ["bash", "-lc"]  # Windows: ["powershell"] (default) or ["pwsh"]
# connect_timeout_secs = 20
# server_alive_interval_secs = 30

[local]
# The only local directories the model may list, read from, upload from or
# download into. Leave empty to close the local filesystem completely.
# In a project .farhand.toml, "." means this folder: drop files here to
# upload them, and downloads land here. A project file may only name this
# folder or folders inside it; absolute and `~` entries belong in the
# global config. Never allow your home directory or anything above it.
allowed_dirs = ["."]

[limits]
# command_timeout_secs = 120
# max_command_timeout_secs = 1800
# max_output_bytes = 102400
# max_read_bytes = 524288
# max_transfer_bytes = 1073741824
# max_transfer_files = 5000

[audit]
# Global config only; a project file cannot move the log.
# log_dir = "~/.local/share/farhand/audit"

[guard]
# Extra globs that may never leave this machine (added to the built-in list).
# deny_globs = ["*.internal"]
# Extra regexes that mark content as secret.
# deny_content = ["ACME-[0-9]{12}"]

[approval]
# "ask":    the agent prompts you before remote_shell, remote_write,
#           remote_edit, remote_spawn, remote_kill, upload and download;
#           read-only tools run freely.
# "auto":   nothing prompts; the audit log is your record.
# "strict": every tool prompts, reads and searches included.
# A project .farhand.toml can make this stricter than the global config,
# never looser: `auto` there only holds where the global config allows it.
# The global mode is a ceiling, not a default: a project without its own
# [approval] asks.
mode = "ask"
# Per-tool overrides (`ask` or `auto`), any tool name:
# tools = { remote_write = "auto", remote_edit = "auto", remote_read = "ask" }
"#;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn example_parses() {
        // `farhand init` writes the example as a project file; its `"."`
        // is that file's folder, and is meaningless in the global config.
        let cfg = Config::parse_at(Config::example(), Some(Path::new("/proj"))).unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().host, "devbox");
        assert_eq!(cfg.remote.as_ref().unwrap().shell, vec!["bash", "-lc"]);
        assert_eq!(cfg.local.allowed_dirs, vec![PathBuf::from("/proj")]);
        assert!(Config::parse(Config::example()).is_err());
    }

    #[test]
    fn project_file_is_found_above_the_working_directory() {
        let home = tempfile::tempdir().unwrap();
        let proj = home.path().join("proj");
        let deep = proj.join(".claude/worktrees/w1/src");
        std::fs::create_dir_all(&deep).unwrap();
        let file = proj.join(".farhand.toml");
        std::fs::write(&file, "").unwrap();
        let h = Some(home.path());
        assert_eq!(find_project_file(&deep, h), Some(file.clone()));
        assert_eq!(find_project_file(&proj, h), Some(file));
        // The nearest file wins.
        let inner = deep.join(".farhand.toml");
        std::fs::write(&inner, "").unwrap();
        assert_eq!(find_project_file(&deep, h), Some(inner));
    }

    #[test]
    fn project_file_search_stops_below_home() {
        let home = tempfile::tempdir().unwrap();
        let sub = home.path().join("a/b");
        std::fs::create_dir_all(&sub).unwrap();
        std::fs::write(home.path().join(".farhand.toml"), "").unwrap();
        assert_eq!(find_project_file(&sub, Some(home.path())), None);
        // A session started in the home folder itself still finds it.
        assert!(find_project_file(home.path(), Some(home.path())).is_some());
    }

    #[test]
    fn rejects_home_and_root_as_allowed_dirs() {
        for d in ["/", "~"] {
            let err = Config::parse(&format!(
                "[remote]\nhost='h'\nworkdir='/w'\n[local]\nallowed_dirs=['{d}']"
            ))
            .unwrap_err();
            assert!(err.to_string().contains("home directory"), "{d}: {err}");
        }
        assert!(
            Config::parse("[remote]\nhost='h'\nworkdir='/w'\n[local]\nallowed_dirs=['~/out']")
                .is_ok()
        );
    }

    #[test]
    fn relative_allowed_dirs_resolve_against_the_project_file() {
        let text = "[remote]\nhost='h'\nworkdir='/w'\n[local]\nallowed_dirs=['.', 'assets']";
        let err = Config::parse(text).unwrap_err();
        assert!(err.to_string().contains("relative"), "{err}");
        let cfg = Config::parse_at(text, Some(Path::new("/proj"))).unwrap();
        assert_eq!(
            cfg.local.allowed_dirs,
            vec![PathBuf::from("/proj"), PathBuf::from("/proj/assets")]
        );
        let err = Config::parse_at(
            "[remote]\nhost='h'\nworkdir='/w'\n[local]\nallowed_dirs=['../x']",
            Some(Path::new("/proj")),
        )
        .unwrap_err();
        assert!(err.to_string().contains(".."), "{err}");
    }

    #[test]
    fn old_tool_name_points_at_the_new_one() {
        let err = Config::parse(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\ntools={ remote_bash='ask' }",
        )
        .unwrap_err();
        assert!(
            err.to_string().contains("renamed to `remote_shell`"),
            "{err}"
        );
    }

    #[test]
    fn rejects_relative_workdir() {
        let err = Config::parse("[remote]\nhost='h'\nworkdir='rel'").unwrap_err();
        assert!(err.to_string().contains("absolute"));
        let cfg = Config::parse("[remote]\nhost='h'\nworkdir='~/'").unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().workdir, "~");
        let cfg = Config::parse("[remote]\nhost='h'\nworkdir='/srv/app/'").unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().workdir, "/srv/app");
        let cfg = Config::parse("[remote]\nhost='h'\nworkdir='C:\\work\\'").unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().workdir, "C:\\work");
        let cfg = Config::parse("[remote]\nhost='h'\nworkdir='D:/'").unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().workdir, "D:\\");
        let cfg = Config::parse("[remote]\nhost='h'\nworkdir='C:'").unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().workdir, "C:\\");
        assert!(Config::parse("[remote]\nhost='h'\nworkdir='work'").is_err());
        let cfg = Config::parse("[remote]\nhost='h'\nworkdir='/'\nos='windows'").unwrap();
        assert_eq!(cfg.remote.as_ref().unwrap().os, Os::Windows);
    }

    #[test]
    fn approval_overrides_apply() {
        let cfg = Config::parse(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\nmode='auto'\ntools={ remote_shell='ask' }",
        )
        .unwrap();
        let e = cfg.approval.effective();
        assert_eq!(e["remote_shell"], ApprovalMode::Ask);
        assert_eq!(e["remote_write"], ApprovalMode::Auto);
        assert_eq!(e["remote_read"], ApprovalMode::Auto);
        assert_eq!(e.len(), MUTATING_TOOLS.len() + READ_ONLY_TOOLS.len());

        let strict = Config::parse(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\nmode='strict'\ntools={ remote_info='auto' }",
        )
        .unwrap();
        let e = strict.approval.effective();
        assert_eq!(e["remote_read"], ApprovalMode::Ask);
        assert_eq!(e["remote_shell"], ApprovalMode::Ask);
        assert_eq!(e["remote_info"], ApprovalMode::Auto);

        let default = Config::parse("[remote]\nhost='h'\nworkdir='/'").unwrap();
        assert_eq!(
            default.approval.effective()["remote_read"],
            ApprovalMode::Auto
        );
        assert!(Config::parse(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\ntools={ nope='auto' }"
        )
        .is_err());
        assert!(Config::parse(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\ntools={ upload='strict' }"
        )
        .is_err());
    }

    #[test]
    fn activation_depends_on_source() {
        let mk = |activation: &str, source: Source| Loaded {
            config: Config::parse(&format!(
                "activation='{activation}'\n[remote]\nhost='h'\nworkdir='/'"
            ))
            .unwrap(),
            path: PathBuf::new(),
            source,
            notices: Vec::new(),
        };
        assert!(mk("always", Source::Global).active());
        assert!(!mk("project", Source::Global).active());
        assert!(mk("project", Source::Project).active());
        assert!(mk("project", Source::Explicit).active());
        assert_eq!(
            Config::parse("[remote]\nhost='h'\nworkdir='/'")
                .unwrap()
                .activation,
            ActivationMode::Project
        );
    }

    #[test]
    fn allowed_dirs_refuse_home_ancestors_and_dotdot() {
        let home = dirs::home_dir().unwrap();
        let parent = home.parent().unwrap().display().to_string();
        for d in [parent.as_str(), "~/..", "~/../x", "/tmp/../etc"] {
            let err = Config::parse(&format!(
                "[remote]\nhost='h'\nworkdir='/w'\n[local]\nallowed_dirs=['{d}']"
            ))
            .unwrap_err();
            assert!(err.to_string().contains("allowed_dirs"), "{d}: {err}");
        }
    }

    /// Parse `text` as the `.farhand.toml` of a fresh project folder.
    fn project(text: &str, baseline: Option<&str>) -> (Config, Vec<String>, tempfile::TempDir) {
        let d = tempfile::tempdir().unwrap();
        let baseline = baseline.map(|b| Config::parse(b).unwrap());
        let (cfg, notes) = Config::parse_project(text, Some(d.path()), baseline.as_ref()).unwrap();
        (cfg, notes, d)
    }

    #[test]
    fn project_file_cannot_loosen_approval() {
        let (cfg, notes, _d) = project(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\nmode='auto'",
            None,
        );
        let e = cfg.approval.effective();
        assert_eq!(e["remote_shell"], ApprovalMode::Ask);
        assert_eq!(e["upload"], ApprovalMode::Ask);
        assert_eq!(e["remote_read"], ApprovalMode::Auto);
        assert_eq!(notes.len(), 1);
        assert!(notes[0].contains("remote_shell"), "{notes:?}");

        // The global config sets the floor: what it allows, a project may use.
        let global = "[remote]\nhost='g'\nworkdir='/'\n[approval]\nmode='auto'";
        let (cfg, notes, _d) = project(
            "[remote]\nhost='h'\nworkdir='/'\n[approval]\nmode='auto'\ntools={ upload='ask' }",
            Some(global),
        );
        assert!(notes.is_empty(), "{notes:?}");
        assert_eq!(cfg.approval.effective()["remote_shell"], ApprovalMode::Auto);
        assert_eq!(cfg.approval.effective()["upload"], ApprovalMode::Ask);

        // Tightening is always fine; loosening strict reads is not.
        let strict = "[remote]\nhost='g'\nworkdir='/'\n[approval]\nmode='strict'";
        let (cfg, notes, _d) = project("[remote]\nhost='h'\nworkdir='/'", Some(strict));
        assert_eq!(cfg.approval.effective()["remote_read"], ApprovalMode::Ask);
        assert!(notes[0].contains("remote_read"), "{notes:?}");
    }

    #[test]
    fn project_file_keeps_to_its_own_folder_and_the_global_log() {
        let (cfg, notes, d) = project(
            "[remote]\nhost='h'\nworkdir='/'\n[local]\nallowed_dirs=['.', '/Users', '~/x']\n\
             [audit]\nlog_dir='/dev'",
            Some("[remote]\nhost='g'\nworkdir='/'\n[audit]\nlog_dir='/var/log/fh'\n[guard]\ndeny_globs=['*.corp']"),
        );
        assert_eq!(
            cfg.local.allowed_dirs,
            vec![d.path().canonicalize().unwrap()]
        );
        assert_eq!(cfg.audit.log_dir, Some(PathBuf::from("/var/log/fh")));
        assert_eq!(cfg.guard.deny_globs, vec!["*.corp".to_string()]);
        assert_eq!(notes.len(), 3, "{notes:?}");
        let err = Config::parse_project(
            "[remote]\nhost='h'\nworkdir='/'\n[local]\nallowed_dirs=['../x']",
            Some(Path::new("/proj")),
            None,
        )
        .unwrap_err();
        assert!(err.to_string().contains(".."), "{err}");
    }

    #[cfg(unix)]
    #[test]
    fn project_folders_may_not_leave_the_project_through_a_symlink() {
        let d = tempfile::tempdir().unwrap();
        let proj = d.path().join("proj");
        let outside = d.path().join("outside");
        std::fs::create_dir_all(proj.join("real/sub")).unwrap();
        std::fs::create_dir_all(&outside).unwrap();
        std::os::unix::fs::symlink(&outside, proj.join("assets")).unwrap();
        std::os::unix::fs::symlink(proj.join("real/sub"), proj.join("inner")).unwrap();
        let (cfg, notes) = Config::parse_project(
            "[remote]\nhost='h'\nworkdir='/'\n[local]\nallowed_dirs=['assets', 'inner', 'missing', 'real']",
            Some(&proj),
            None,
        )
        .unwrap();
        let real = proj.join("real").canonicalize().unwrap();
        assert_eq!(cfg.local.allowed_dirs, vec![real.join("sub"), real]);
        assert_eq!(notes.len(), 2, "{notes:?}");
        assert!(notes[0].contains("/assets`"), "{notes:?}");
        assert!(notes[1].contains("/missing`"), "{notes:?}");
    }

    #[test]
    fn a_farhand_toml_passed_by_path_is_still_a_project_file() {
        let d = tempfile::tempdir().unwrap();
        let p = d.path().join(".farhand.toml");
        std::fs::write(
            &p,
            "[remote]\nhost='h'\nworkdir='/'\n[audit]\nlog_dir='/dev'",
        )
        .unwrap();
        let l = Config::load_in(None, Some(&p)).unwrap();
        assert_eq!(l.source, Source::Project);
        assert!(
            l.notices.iter().any(|n| n.contains("log_dir")),
            "{:?}",
            l.notices
        );
        let other = d.path().join("fh.toml");
        std::fs::copy(&p, &other).unwrap();
        let l = Config::load_in(None, Some(&other)).unwrap();
        assert_eq!(l.source, Source::Explicit);
        assert_eq!(l.config.audit.log_dir, Some(PathBuf::from("/dev")));
    }

    #[test]
    fn a_path_is_a_project_file_by_name_whichever_way_it_came() {
        for otherwise in [Source::Explicit, Source::Env] {
            let p = Path::new("/repo/.farhand.toml");
            assert_eq!(Source::by_name(p, otherwise), Source::Project);
            let p = Path::new("/repo/farhand.toml");
            assert_eq!(Source::by_name(p, otherwise), otherwise);
        }
        assert_eq!(Source::Project.trust(), "project");
        assert_eq!(Source::Env.trust(), "global");
    }

    #[test]
    fn only_the_global_config_may_leave_out_remote() {
        let cfg = Config::parse("[approval]\nmode='auto'").unwrap();
        assert!(cfg.remote.is_none());
        let err = Config::parse("activation='always'\n[approval]\nmode='auto'").unwrap_err();
        assert!(err.to_string().contains("[remote]"), "{err}");
        let err = Config::parse_at("[approval]\nmode='auto'", Some(Path::new("/p"))).unwrap_err();
        assert!(err.to_string().contains("[remote] is missing"), "{err}");
        let d = tempfile::tempdir().unwrap();
        assert!(Config::parse_project("[approval]\nmode='ask'", Some(d.path()), None).is_err());
    }

    #[test]
    fn a_global_config_without_remote_is_inactive() {
        let l = Loaded {
            config: Config::parse("activation='project'").unwrap(),
            path: PathBuf::from("/g"),
            source: Source::Global,
            notices: Vec::new(),
        };
        assert!(!l.active());
    }

    #[test]
    fn rejects_unknown_fields() {
        assert!(Config::parse("[remote]\nhost='h'\nworkdir='/'\nbogus=1").is_err());
    }
}