//! Program resolution — find an external tool that is installed but not on `PATH`. //! //! Luxe drives a lot of external programs: language servers, debug adapters, formatters, `git`, //! `ast-grep`. Resolving them through `PATH` alone reports "not installed" for a tool that is //! sitting on disk, because a package manager's bin directory and the launching process's `PATH` //! are different things. `cargo install` writes to `~/.cargo/bin` whether or not that directory was //! ever added to a shell profile; `pipx`, `npm -g`, `go install`, and Homebrew each have their own. //! An app also inherits whatever environment launched it, which for a desktop entry, a systemd //! unit, or an editor's integrated terminal is often not the user's login shell. //! //! So: try `PATH` first (it is the user's stated preference), then the well-known install //! directories. A tool that is genuinely absent still reports absent, with its install hint intact. use std::path::{Path, PathBuf}; mod bounded; mod nesting; mod opener; mod process; pub use bounded::{run_bounded, run_bounded_with_input, BoundedRunError}; pub use nesting::{ check_nesting, claim_nesting_slot, NestingRefused, DEFAULT_MAX_NESTING_DEPTH, MAX_NESTING_DEPTH_VAR, NESTING_DEPTH_VAR, }; pub use opener::{ desktop_opener, editor, editor_file_args, file_manager, file_manager_from, parse_editor, EditorError, }; pub use process::{ captured_command, detach_from_terminal, group_members, hostname, kill_tree, process_is_alive, take_stdin, GroupMember, }; /// Directories a package manager drops executables into, checked after `PATH`. /// /// Ordered by how likely the entry is to be the one a developer meant: language toolchains first, /// then the generic user bin directory, then system-wide installs. fn well_known_bin_dirs() -> Vec { let home = crate::user_dirs::home_dir().unwrap_or_else(|| PathBuf::from(".")); let mut dirs = vec![ home.join(".cargo").join("bin"), home.join(".local").join("bin"), home.join("go").join("bin"), home.join(".bun").join("bin"), home.join(".deno").join("bin"), home.join(".npm-global").join("bin"), ]; if cfg!(windows) { dirs.extend(windows_bin_dirs()); } else { dirs.push(PathBuf::from("/opt/homebrew/bin")); dirs.push(PathBuf::from("/usr/local/bin")); } dirs } /// Where Windows keeps installed programs that its installers did not put on `PATH`. /// /// Scoop and winget shim their own directories onto `PATH`, so the interesting entries are Git for /// Windows and Chocolatey. Git matters most: its default install adds only `Git\cmd` (which holds /// `git.exe` and little else), so the unix tools a coding agent leans on sit on disk, one directory /// away, invisible to a `PATH` lookup. fn windows_bin_dirs() -> Vec { let mut dirs = Vec::new(); let roots = ["ProgramFiles", "ProgramFiles(x86)", "ProgramW6432"] .iter() .filter_map(std::env::var_os) .map(PathBuf::from) .chain(std::env::var_os("LOCALAPPDATA").map(|local| PathBuf::from(local).join("Programs"))); for root in roots { dirs.push(root.join("Git").join("bin")); dirs.push(root.join("Git").join("usr").join("bin")); dirs.push(root.join("Git").join("cmd")); } if let Some(data) = std::env::var_os("ProgramData") { dirs.push(PathBuf::from(data).join("chocolatey").join("bin")); } dirs } /// Whether `path` is a file we could execute. #[cfg(unix)] fn is_executable(path: &Path) -> bool { use std::os::unix::fs::PermissionsExt; std::fs::metadata(path) .is_ok_and(|meta| meta.is_file() && meta.permissions().mode() & 0o111 != 0) } #[cfg(not(unix))] fn is_executable(path: &Path) -> bool { path.is_file() } /// Resolve `program` to a runnable path: `PATH` first, then the well-known install directories. /// /// An absolute or relative path (anything containing a separator) is honored as given. Returns /// `None` only when the program really cannot be found. pub fn resolve(program: &str) -> Option { let candidate = Path::new(program); // Windows accepts both separators, so checking only `MAIN_SEPARATOR` would treat `tools/rg` as a // bare program name and go looking for it on `PATH`. if candidate.is_absolute() || program.contains('/') || program.contains('\\') { return runnable(candidate).map(|_| candidate.to_path_buf()); } let dirs = std::env::var_os("PATH") .map(|path| std::env::split_paths(&path).collect::>()) .unwrap_or_default(); dirs.into_iter().chain(well_known_bin_dirs()).find_map(|dir| runnable(&dir.join(program))) } /// The runnable file at `base`, trying the platform's executable suffixes. /// /// On unix a program is its own filename. On Windows the name on disk carries an extension from /// `PATHEXT` — `rg` is `rg.exe`, a shim may be `rg.cmd` — so a bare-name lookup finds nothing at all, /// which reads as "ripgrep is not installed" on a machine where it plainly is. fn runnable(base: &Path) -> Option { if is_executable(base) { return Some(base.to_path_buf()); } if !cfg!(windows) { return None; } for extension in executable_suffixes() { let mut name = base.as_os_str().to_os_string(); name.push(&extension); let candidate = PathBuf::from(name); if is_executable(&candidate) { return Some(candidate); } } None } /// Windows executable suffixes, from `PATHEXT` when it is set. fn executable_suffixes() -> Vec { std::env::var("PATHEXT") .ok() .map(|list| list.split(';').filter(|ext| !ext.is_empty()).map(str::to_string).collect()) .unwrap_or_else(|| { [".COM", ".EXE", ".BAT", ".CMD"].iter().map(|ext| (*ext).to_string()).collect() }) } /// The shell a script-running tool should go through, as `(program, flag)`. /// /// The `bash` tool hands whole command lines to a shell, and the model writes those in POSIX: pipes, /// `&&`, globs, quoting. So a POSIX shell is preferred wherever one exists — on Windows that means /// the one Git for Windows ships. `cmd` is the last resort rather than the default, because a command /// written for `sh` mostly fails in it, and failing *differently* is worse than failing clearly. /// /// Returns `None` for the shell only if the platform has nothing at all, which cannot happen: unix /// has `sh` and Windows has `cmd`. pub fn shell() -> (PathBuf, &'static str) { if !cfg!(windows) { return (resolve("sh").unwrap_or_else(|| PathBuf::from("sh")), "-c"); } match posix_shell_on_windows(resolve, || std::env::var("SystemRoot").ok()) { Some(path) => (path, "-c"), None => (resolve("cmd").unwrap_or_else(|| PathBuf::from("cmd")), "/C"), } } /// Whether [`shell`] found a real POSIX shell, or fell back to `cmd`. /// /// The `bash` tool uses this to explain a failure that is really "this box has no shell that speaks /// your command" rather than a problem with the command. pub fn has_posix_shell() -> bool { shell().1 == "-c" } /// Find a POSIX shell on Windows, refusing the one that is not what it says. /// /// `C:\Windows\System32\bash.exe` is the WSL launcher. It is on `PATH` before anything else the /// moment WSL is installed, and running an agent's commands through it would execute them inside a /// Linux VM with a different filesystem — `cd` into the project would fail, and every subsequent /// error would describe a machine the user is not looking at. So a candidate sitting in the Windows /// system directory is skipped rather than taken. /// /// Args: `(program lookup, `%SystemRoot%` lookup)` — both injected so the rule is testable from any /// platform. fn posix_shell_on_windows( lookup: impl Fn(&str) -> Option, system_root: impl Fn() -> Option, ) -> Option { let system = system_root() .map(|root| PathBuf::from(root).join("System32")) .unwrap_or_else(|| PathBuf::from(r"C:\Windows\System32")); ["bash", "sh"] .iter() .filter_map(|name| lookup(name)) .find(|path| path.parent().is_none_or(|parent| !crate::paths::contains(&system, parent))) } /// Whether `program` can be run at all — `PATH` or a well-known install directory. pub fn is_available(program: &str) -> bool { resolve(program).is_some() } /// The first of `programs` that resolves, as `(requested name, runnable path)`. /// /// For a tool that ships under more than one name (`fd`/`fdfind`, `ast-grep`/`sg`). pub fn resolve_any<'a>(programs: &[&'a str]) -> Option<(&'a str, PathBuf)> { programs.iter().find_map(|name| resolve(name).map(|path| (*name, path))) } /// The copy of `program` a project under `root` supplies for itself, if any. /// /// Two conventions, one question. npm links a dev dependency's executable into /// `node_modules/.bin`, and Python installs everything into a virtualenv — in both cases the /// version a repository pins is invisible to [`resolve`], which answers with whatever global copy /// shares the name. The environment is checked first because it belongs to `root` itself, then /// `node_modules/.bin` walking upward, because a workspace hoists: a package in a monorepo has its /// own or shares the root's, and which one depends on the package manager rather than on anything /// the caller can see. /// /// **This returns a path to a binary the repository supplied**, so whether to run it is the /// caller's decision and not this module's. Home is skipped on the way up: a stray `~/node_modules` /// belongs to no project and would otherwise answer for every one of them. pub fn project_local(root: &Path, program: &str) -> Option { // A name with a separator is a path, not something to go looking for. if program.contains('/') || program.contains('\\') { return None; } if let Some(installed) = project_venv(root).and_then(|venv| venv_program(&venv, program)) { return Some(installed); } let home = crate::user_dirs::home_dir(); std::iter::successors(Some(root), |dir| dir.parent()) .filter(|dir| home.as_deref() != Some(*dir)) .find_map(|dir| runnable(&dir.join("node_modules").join(".bin").join(program))) } /// Directory names a Python virtualenv conventionally lives under, most idiomatic first. const VENV_DIR_NAMES: &[&str] = &[".venv", "venv", "env"]; /// The copy of `program` installed into the virtualenv at `venv`, if both exist. /// /// A virtualenv's executables are the ones a Python project actually pinned, and they are never on /// `PATH` unless somebody activated it — so [`resolve`] answers with a global interpreter that /// shares nothing with the project but a version number. The layout differs by platform (`bin` on /// unix, `Scripts` on Windows) and that is the whole reason this lives here: a call site that /// hardcodes `bin/python` works everywhere except Windows, silently. pub fn venv_program(venv: &Path, program: &str) -> Option { if program.contains('/') || program.contains('\\') { return None; } let bin = if cfg!(windows) { "Scripts" } else { "bin" }; runnable(&venv.join(bin).join(program)) } /// The virtualenv a project under `root` carries, if any. /// /// An activated `VIRTUAL_ENV` inside the tree wins, because it is the user's own answer and it may /// be named something no list would guess (`.direnv/python-3.12`). One *outside* the tree is /// ignored on purpose: it belongs to another project, and if it should win it is already on `PATH`. /// /// Only `root` itself is searched. Walking upward would let a parent directory's environment answer /// for a project that has none, which is the failure this exists to prevent. pub fn project_venv(root: &Path) -> Option { let active = std::env::var_os("VIRTUAL_ENV").map(PathBuf::from).filter(|venv| { crate::paths::contains(root, venv) && venv_program(venv, "python").is_some() }); active.or_else(|| { VENV_DIR_NAMES .iter() .map(|name| root.join(name)) .find(|venv| venv_program(venv, "python").is_some()) }) } /// Resolve `program` for work rooted at `root`, preferring what the project installed for itself. /// /// `allow_project_local` is the whole gate, and it is the caller's answer rather than this /// module's: a binary under `root` got there from the repository, so who is watching and what the /// user configured decide it, and neither is knowable here. Denied, this is exactly [`resolve`]. pub fn resolve_in(root: &Path, program: &str, allow_project_local: bool) -> Option { if allow_project_local { if let Some(local) = project_local(root, program) { return Some(local); } } resolve(program) } #[cfg(test)] pub(crate) mod tests;