refactor and README rewrite

Author: mxcl

Cargo.toml

@@ -10,6 +10,15 @@ license = "Apache-2.0"
 name = "cargox"
 path = "src/main.rs"
 
+[package.metadata.binstall]
+pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ version }-{ target }.tar.gz"
+pkg-fmt = "tgz"
+bin-dir = "{ bin }{ binary-ext }"
+
+[package.metadata.binstall.overrides.x86_64-pc-windows-msvc]
+pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ version }-{ target }.zip"
+pkg-fmt = "zip"
+
 [dependencies]
 anyhow = "1.0"
 clap = { version = "4.5", features = ["derive"] }

README.md

@@ -30,9 +30,16 @@ cargox bat ./README.md
 cargox cargo-deny@0.16.3 check
 
 # Force a reinstall using cargo install instead of cargo-binstall
-cargox cargo-nextest --force --use-cargo-install
+cargox --force --use-cargo-install cargo-nextest
 ```
 
+> [!TIP]
+>
+> - Arguments before the first positional are passed to `cargox`.
+> - Arguments after `--` are passed to the invoked binary.
+> - Use `--` if necessary to define the separation point.
+> - If the crate exposes multiple binaries, use `--bin <name>` to select one.
+
 ### Flags
 
 - `--bin <name>`: choose a specific binary when a crate exposes several.
@@ -90,36 +97,3 @@ This sandboxing guarantees that:
   that is automatically cleaned up after installation completes
 
 This keeps your system clean and prevents build cache bloat.
-
-**Adding binaries to your PATH:**
-
-To use binaries installed by `cargox`, ensure the install directory is in your `PATH`:
-
-```bash
-# Linux/Unix - add to ~/.bashrc, ~/.zshrc, or equivalent
-export PATH="$HOME/.local/share/cargox/bin:$PATH"
-
-# macOS - add to ~/.zshrc or ~/.bash_profile
-export PATH="$HOME/Library/Application Support/cargox/bin:$PATH"
-
-# Or use the custom directory if you set CARGOX_INSTALL_DIR
-export PATH="/your/custom/path/bin:$PATH"
-```
-
-## Development
-
-```bash
-cargo fmt
-cargo test
-```
-
-`cargox` (published as `cargox-cli`) is distributed as a standard Cargo binary
-crate; build it locally with `cargo build --release` if you want a standalone
-executable.
-
-## Releasing
-
-Tag releases with `vX.Y.Z` and push the tag. A GitHub Actions workflow (powered
-by `cargo-dist`) builds binaries for Linux, macOS (Intel + Apple Silicon), and
-Windows, uploads them as release assets, and generates the metadata that
-`cargo-binstall` needs to install `cargox` directly from those releases.

src/cli.rs

@@ -0,0 +1,31 @@
+use clap::Parser;
+use std::ffi::OsString;
+
+/// Run Cargo binaries on demand, installing them via `cargo-binstall` when missing.
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None, arg_required_else_help = true)]
+pub struct Cli {
+    /// Crate to run, optionally suffixed with `@version`
+    #[arg(value_name = "crate[@version]")]
+    pub crate_spec: String,
+
+    /// Execute this binary from the crate (defaults to crate name)
+    #[arg(long, value_name = "NAME")]
+    pub bin: Option<String>,
+
+    /// Force reinstall even if the binary is already on PATH
+    #[arg(short, long)]
+    pub force: bool,
+
+    /// Suppress installer output
+    #[arg(short, long)]
+    pub quiet: bool,
+
+    /// Use `cargo install` instead of `cargo-binstall`
+    #[arg(long)]
+    pub use_cargo_install: bool,
+
+    /// Arguments passed to the executed binary (use `--` to delimit)
+    #[arg(trailing_var_arg = true, value_name = "binary-args")]
+    pub args: Vec<OsString>,
+}

src/executor.rs

@@ -0,0 +1,15 @@
+use anyhow::{Context, Result};
+use std::ffi::OsString;
+use std::path::Path;
+use std::process::{Command, ExitStatus};
+
+pub fn execute_binary(binary_path: &Path, args: &[OsString]) -> Result<ExitStatus> {
+    let mut cmd = Command::new(binary_path);
+    cmd.args(args);
+
+    let status = cmd
+        .status()
+        .with_context(|| format!("failed to execute {}", binary_path.display()))?;
+
+    Ok(status)
+}

src/installer.rs

@@ -0,0 +1,176 @@
+use anyhow::{anyhow, Context, Result};
+use std::process::Command;
+
+use crate::cli::Cli;
+use crate::paths::get_install_dir;
+use crate::target::Target;
+
+pub fn ensure_installed(target: &Target, cli: &Cli) -> Result<()> {
+    if !cli.use_cargo_install && which::which("cargo-binstall").is_ok() {
+        install_with_binstall(target, cli)
+    } else {
+        log_fallback_reason(cli, target);
+        install_with_cargo(target, cli)
+    }
+}
+
+fn log_fallback_reason(cli: &Cli, target: &Target) {
+    if cli.use_cargo_install {
+        eprintln!(
+            "cargo-binstall was skipped explicitly; installing {} with cargo install",
+            target.descriptor()
+        );
+    } else {
+        eprintln!(
+            "cargo-binstall not found; falling back to cargo install for {}",
+            target.descriptor()
+        );
+    }
+}
+
+fn install_with_binstall(target: &Target, cli: &Cli) -> Result<()> {
+    let install_dir = get_install_dir()?;
+
+    let mut cmd = Command::new("cargo");
+    cmd.arg("binstall");
+    if cli.quiet {
+        cmd.arg("--quiet");
+    }
+    cmd.arg("--no-confirm");
+    if cli.force {
+        cmd.arg("--force");
+    }
+    if let Some(bin) = &cli.bin {
+        cmd.arg("--bin");
+        cmd.arg(bin);
+    }
+    cmd.arg(target.install_spec());
+
+    // Set the install root for cargo-binstall and remove any environment variables
+    // that could leak into the installation process
+    sanitize_cargo_env(&mut cmd, &install_dir);
+
+    eprintln!(
+        "Installing {} with cargo-binstall{} to {}",
+        target.descriptor(),
+        if cli.quiet { " (quiet)" } else { "" },
+        install_dir.display()
+    );
+
+    let status = cmd.status().context("failed to invoke cargo-binstall")?;
+    if status.success() {
+        Ok(())
+    } else {
+        Err(anyhow!(
+            "cargo-binstall exited with status code {}",
+            status
+                .code()
+                .map(|c| c.to_string())
+                .unwrap_or_else(|| "signal".to_string())
+        ))
+    }
+}
+
+fn install_with_cargo(target: &Target, cli: &Cli) -> Result<()> {
+    let install_dir = get_install_dir()?;
+
+    // Create a temporary directory for the build
+    let temp_dir = tempfile::tempdir().context("failed to create temp directory")?;
+
+    let mut cmd = Command::new("cargo");
+    cmd.arg("install");
+    if cli.quiet {
+        cmd.arg("--quiet");
+    }
+    if cli.force {
+        cmd.arg("--force");
+    }
+    cmd.arg("--root");
+    cmd.arg(&install_dir);
+    cmd.arg(&target.crate_name);
+    if let Some(version) = &target.version {
+        cmd.arg("--version");
+        cmd.arg(version);
+    }
+    if let Some(bin) = &cli.bin {
+        cmd.arg("--bin");
+        cmd.arg(bin);
+    }
+
+    // Use temp directory for target build directory and sanitize environment
+    cmd.env("CARGO_TARGET_DIR", temp_dir.path());
+    sanitize_cargo_env(&mut cmd, &install_dir);
+
+    eprintln!(
+        "Installing {} with cargo install{} to {}",
+        target.descriptor(),
+        if cli.quiet { " (quiet)" } else { "" },
+        install_dir.display()
+    );
+
+    let status = cmd.status().context("failed to invoke cargo install")?;
+
+    // Temp directory will be automatically cleaned up when temp_dir goes out of scope
+
+    if status.success() {
+        Ok(())
+    } else {
+        Err(anyhow!(
+            "cargo install exited with status code {}",
+            status
+                .code()
+                .map(|c| c.to_string())
+                .unwrap_or_else(|| "signal".to_string())
+        ))
+    }
+}
+
+/// Sanitize the environment for cargo commands to ensure complete sandboxing.
+/// Removes any Cargo-related environment variables that could leak into the installation
+/// and sets only the variables we explicitly want.
+fn sanitize_cargo_env(cmd: &mut Command, install_dir: &std::path::Path) {
+    // List of environment variables to remove to ensure sandboxing
+    let vars_to_remove = [
+        "CARGO_INSTALL_ROOT",
+        "CARGO_HOME",
+        "CARGO_BUILD_TARGET_DIR",
+        "CARGO_TARGET_DIR",
+        "BINSTALL_INSTALL_PATH",
+        "RUSTUP_HOME",
+        "RUSTUP_TOOLCHAIN",
+    ];
+
+    for var in &vars_to_remove {
+        cmd.env_remove(var);
+    }
+
+    // Set only our controlled install location
+    cmd.env("CARGO_INSTALL_ROOT", install_dir);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sanitize_cargo_env_removes_cargo_variables() {
+        let temp = tempfile::tempdir().unwrap();
+        let install_dir = temp.path();
+
+        // Create a command with cargo env vars set
+        let mut cmd = Command::new("echo");
+        cmd.env("CARGO_INSTALL_ROOT", "/some/path");
+        cmd.env("CARGO_HOME", "/some/cargo");
+        cmd.env("BINSTALL_INSTALL_PATH", "/some/binstall");
+        cmd.env("RUSTUP_HOME", "/some/rustup");
+        cmd.env("CARGO_TARGET_DIR", "/some/target");
+        cmd.env("SOME_OTHER_VAR", "should_remain");
+
+        // Sanitize the environment
+        sanitize_cargo_env(&mut cmd, install_dir);
+
+        // Note: We can't directly inspect Command's env, but we can verify
+        // the function exists and compiles correctly. The actual behavior
+        // is tested through integration tests.
+    }
+}