feat(hm-common): process module — capture + pathbin

crates/hm-common/Cargo.toml

@@ -11,13 +11,18 @@ categories = ["command-line-utilities"]
 [lib]
 path = "src/lib.rs"
 
+[features]
+app-runtime = []
+
 [dependencies]
 anyhow      = { workspace = true }
 async-trait = { workspace = true }
 chrono      = { workspace = true }
 derive_more = { workspace = true }
 serde       = { workspace = true }
 serde_json  = { workspace = true }
+thiserror   = { workspace = true }
+bstr        = "1"
 include_dir = "0.7"
 num-traits  = { workspace = true }
 tempfile    = "3"
@@ -30,7 +35,6 @@ which       = "7"
 [dev-dependencies]
 tempfile    = "3"
 tokio       = { version = "1", features = ["macros", "rt-multi-thread"] }
-which       = "7"
 rstest      = { workspace = true }
 proptest    = { workspace = true }
 

crates/hm-common/src/app_runtime.rs

@@ -0,0 +1,143 @@
+//! Application runtime context.
+
+use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
+
+use crate::git::Git;
+use crate::process::{ExecutableNotFound, pathbin};
+use crate::python::Python;
+
+/// Failure to initialize the [`AppRuntime`].
+#[derive(Debug, thiserror::Error)]
+pub enum InitError {
+    /// A required executable was missing from `PATH`.
+    #[error(transparent)]
+    Executables(#[from] ExecutableNotFound),
+    /// The current directory could not be read.
+    #[error("reading the current directory")]
+    Cwd(#[source] std::io::Error),
+}
+
+// TODO: This is a process-wide singleton (a global `OnceLock`), which is
+// convenient but couples every caller to hidden global state. Consider
+// threading an explicit `AppRuntime` handle through the application instead,
+// so dependencies are visible in signatures and tests can inject their own.
+/// Process-wide runtime context, resolved once at startup.
+///
+/// Install it with [`init`](Self::init), then read it from anywhere through the
+/// associated accessors — no threading required.
+#[derive(Debug)]
+pub struct AppRuntime {
+    git: PathBuf,
+    python3: PathBuf,
+    cwd: PathBuf,
+}
+
+static RUNTIME: OnceLock<AppRuntime> = OnceLock::new();
+
+impl AppRuntime {
+    /// Resolve the runtime and install it as the process-wide singleton.
+    ///
+    /// Call once, early in `main`, before any accessor. A later call is ignored.
+    ///
+    /// # Errors
+    /// [`InitError`] if a required executable is missing from `PATH` or the
+    /// current directory cannot be read.
+    pub fn init() -> Result<(), InitError> {
+        let runtime = Self::resolve()?;
+        let _ = RUNTIME.set(runtime);
+        Ok(())
+    }
+
+    fn resolve() -> Result<Self, InitError> {
+        Ok(Self {
+            git: pathbin("git")?,
+            python3: pathbin("python3")?,
+            cwd: std::env::current_dir().map_err(InitError::Cwd)?,
+        })
+    }
+
+    #[allow(
+        clippy::expect_used,
+        reason = "accessing the runtime before init is a startup bug, not a runtime error"
+    )]
+    fn get() -> &'static Self {
+        RUNTIME
+            .get()
+            .expect("AppRuntime::init must be called before the runtime is accessed")
+    }
+
+    /// The absolute working directory captured at initialization.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn cwd() -> &'static Path {
+        &Self::get().cwd
+    }
+
+    /// The system `git`, bound to a [`Git`] handle.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn git() -> Git<'static> {
+        Git::new(&Self::get().git)
+    }
+
+    /// The system `python3`, bound to a [`Python`] handle.
+    ///
+    /// # Panics
+    /// If [`init`](Self::init) has not been called.
+    #[must_use]
+    pub fn python() -> Python<'static> {
+        Python::new(&Self::get().python3)
+    }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::unwrap_used,
+    clippy::print_stderr,
+    reason = "test setup, assertions, and skip diagnostics"
+)]
+mod tests {
+    use super::*;
+    use rstest::rstest;
+
+    #[rstest]
+    fn resolve_reports_toolchain_availability() {
+        assert_eq!(
+            AppRuntime::resolve().is_ok(),
+            pathbin("python3").is_ok() && pathbin("git").is_ok()
+        );
+    }
+
+    #[rstest]
+    fn resolve_captures_an_absolute_cwd() {
+        let Ok(runtime) = AppRuntime::resolve() else {
+            eprintln!("skipping: toolchain unavailable");
+            return;
+        };
+        assert!(runtime.cwd.is_absolute(), "cwd was {:?}", runtime.cwd);
+    }
+
+    #[rstest]
+    fn init_installs_a_globally_accessible_runtime() {
+        if AppRuntime::resolve().is_err() {
+            eprintln!("skipping: toolchain unavailable");
+            return;
+        }
+        AppRuntime::init().unwrap();
+        assert!(AppRuntime::cwd().is_absolute());
+        // git() binds the resolved git; a fresh temp dir is not a repo.
+        let dir = tempfile::tempdir().unwrap();
+        assert!(AppRuntime::git().repo(dir.path()).is_err());
+    }
+
+    #[rstest]
+    fn init_error_wraps_a_missing_executable() {
+        let err: InitError = pathbin("hm-common-no-such-binary-xyz").unwrap_err().into();
+        assert!(matches!(err, InitError::Executables(_)));
+    }
+}