fix(core): use home crate for cross-platform home directory resolution

Cargo.toml

@@ -49,6 +49,9 @@ ratatui = "0.26"
 crossterm = "0.28"
 terminal-colorsaurus = "1.0"
 
+# Home directory resolution
+home = "0.5"
+
 # Error handling
 miette = { version = "7", features = ["fancy"] }
 thiserror = "2"

crates/openshell-cli/src/run.rs

@@ -735,7 +735,11 @@ fn package_managed_tls_dirs() -> Vec<PathBuf> {
 
     let state_dir = std::env::var_os("XDG_STATE_HOME")
         .map(PathBuf::from)
-        .or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".local/state")));
+        .or_else(|| {
+            openshell_core::paths::home_dir()
+                .ok()
+                .map(|home| home.join(".local/state"))
+        });
     if let Some(state_dir) = state_dir {
         dirs.push(state_dir.join("openshell/tls"));
     }
@@ -4351,10 +4355,10 @@ fn read_gcloud_adc() -> Result<(String, String, String)> {
     {
         PathBuf::from(config_dir).join("application_default_credentials.json")
     } else {
-        let home = std::env::var("HOME")
-            .map_err(|_| miette::miette!("HOME is not set; cannot locate gcloud ADC file"))?;
-        PathBuf::from(home)
-            .join(".config")
+        let home = openshell_core::paths::home_dir().map_err(|_| {
+            miette::miette!("could not determine home directory; cannot locate gcloud ADC file")
+        })?;
+        home.join(".config")
             .join("gcloud")
             .join("application_default_credentials.json")
     };

crates/openshell-cli/src/ssh.rs

@@ -1454,10 +1454,8 @@ fn openshell_ssh_config_path() -> Result<PathBuf> {
 }
 
 fn user_ssh_config_path() -> Result<PathBuf> {
-    let home = std::env::var("HOME")
-        .into_diagnostic()
-        .wrap_err("HOME is not set")?;
-    Ok(PathBuf::from(home).join(".ssh").join("config"))
+    let home = openshell_core::paths::home_dir()?;
+    Ok(home.join(".ssh").join("config"))
 }
 
 fn render_include_line(path: &Path) -> String {

crates/openshell-core/Cargo.toml

@@ -17,6 +17,7 @@ tonic = { workspace = true, features = ["channel", "tls-native-roots"] }
 tonic-prost = { workspace = true }
 tokio = { workspace = true }
 thiserror = { workspace = true }
+home = { workspace = true }
 miette = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }

crates/openshell-core/src/config.rs

@@ -161,7 +161,7 @@ fn podman_socket_candidates() -> Vec<PathBuf> {
     podman_socket_candidates_from_env(
         socket,
         std::env::var_os("XDG_RUNTIME_DIR").map(PathBuf::from),
-        std::env::var_os("HOME").map(PathBuf::from),
+        crate::paths::home_dir().ok(),
     )
 }
 
@@ -216,8 +216,8 @@ fn docker_socket_candidates() -> Vec<PathBuf> {
 
     candidates.push(PathBuf::from("/var/run/docker.sock"));
 
-    if let Some(home) = std::env::var_os("HOME") {
-        candidates.push(PathBuf::from(home).join(".docker/run/docker.sock"));
+    if let Ok(home) = crate::paths::home_dir() {
+        candidates.push(home.join(".docker/run/docker.sock"));
     }
 
     if let Some(runtime_dir) = std::env::var_os("XDG_RUNTIME_DIR") {

crates/openshell-core/src/paths.rs

@@ -13,17 +13,24 @@
 use miette::{IntoDiagnostic, Result, WrapErr};
 use std::path::{Path, PathBuf};
 
+/// Resolve the user's home directory in a cross-platform way.
+///
+/// Uses the `home` crate, which reads `HOME` on Unix and `USERPROFILE`
+/// (falling back to `HOMEDRIVE`+`HOMEPATH`) on Windows.
+pub fn home_dir() -> Result<PathBuf> {
+    home::home_dir().ok_or_else(|| miette::miette!("could not determine home directory"))
+}
+
 /// Resolve the XDG config base directory.
 ///
 /// Returns `$XDG_CONFIG_HOME` if set, otherwise `$HOME/.config`.
 pub fn xdg_config_dir() -> Result<PathBuf> {
     if let Ok(path) = std::env::var("XDG_CONFIG_HOME") {
         return Ok(PathBuf::from(path));
     }
-    let home = std::env::var("HOME")
-        .into_diagnostic()
-        .wrap_err("HOME is not set")?;
-    Ok(PathBuf::from(home).join(".config"))
+    Ok(home_dir()
+        .wrap_err("cannot resolve XDG config directory")?
+        .join(".config"))
 }
 
 /// The top-level `OpenShell` config directory: `$XDG_CONFIG_HOME/openshell/`.
@@ -38,10 +45,10 @@ pub fn xdg_state_dir() -> Result<PathBuf> {
     if let Ok(path) = std::env::var("XDG_STATE_HOME") {
         return Ok(PathBuf::from(path));
     }
-    let home = std::env::var("HOME")
-        .into_diagnostic()
-        .wrap_err("HOME is not set")?;
-    Ok(PathBuf::from(home).join(".local").join("state"))
+    Ok(home_dir()
+        .wrap_err("cannot resolve XDG state directory")?
+        .join(".local")
+        .join("state"))
 }
 
 /// The top-level `OpenShell` state directory: `$XDG_STATE_HOME/openshell/`.
@@ -56,10 +63,10 @@ pub fn xdg_data_dir() -> Result<PathBuf> {
     if let Ok(path) = std::env::var("XDG_DATA_HOME") {
         return Ok(PathBuf::from(path));
     }
-    let home = std::env::var("HOME")
-        .into_diagnostic()
-        .wrap_err("HOME is not set")?;
-    Ok(PathBuf::from(home).join(".local").join("share"))
+    Ok(home_dir()
+        .wrap_err("cannot resolve XDG data directory")?
+        .join(".local")
+        .join("share"))
 }
 
 /// Create a directory (and parents) with owner-only permissions (`0o700`) on
@@ -159,6 +166,12 @@ pub fn normalize_path(path: &str) -> String {
 mod tests {
     use super::*;
 
+    #[test]
+    fn home_dir_returns_ok() {
+        let dir = home_dir().unwrap();
+        assert!(dir.is_absolute(), "expected absolute path, got: {dir:?}");
+    }
+
     #[test]
     fn xdg_config_dir_respects_env() {
         // This test checks the logic — actual env var mutation is unsafe so

crates/openshell-driver-podman/Cargo.toml

@@ -33,6 +33,7 @@ rustix = { workspace = true }
 tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 thiserror = { workspace = true }
+home = { workspace = true }
 miette = { workspace = true }
 
 [dev-dependencies]

crates/openshell-driver-podman/src/config.rs

@@ -227,8 +227,8 @@ impl PodmanComputeConfig {
     pub fn default_socket_path() -> PathBuf {
         #[cfg(target_os = "macos")]
         {
-            let home = std::env::var("HOME").expect("HOME must be set on macOS");
-            PathBuf::from(home).join(".local/share/containers/podman/machine/podman.sock")
+            let home = home::home_dir().expect("home directory must be resolvable on macOS");
+            home.join(".local/share/containers/podman/machine/podman.sock")
         }
         #[cfg(target_os = "linux")]
         {

crates/openshell-driver-vm/Cargo.toml

@@ -33,6 +33,7 @@ nix = { workspace = true }
 clap = { workspace = true }
 tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
+home = { workspace = true }
 miette = { workspace = true }
 url = { workspace = true }
 serde = { workspace = true }

crates/openshell-driver-vm/src/driver.rs

@@ -3229,8 +3229,8 @@ async fn connect_local_container_engine() -> Option<Docker> {
 fn podman_socket_path() -> PathBuf {
     #[cfg(target_os = "macos")]
     {
-        let home = std::env::var("HOME").unwrap_or_default();
-        PathBuf::from(home).join(".local/share/containers/podman/machine/podman.sock")
+        let home = home::home_dir().unwrap_or_default();
+        home.join(".local/share/containers/podman/machine/podman.sock")
     }
     #[cfg(target_os = "linux")]
     {

crates/openshell-providers/src/providers/opencode.rs

@@ -22,9 +22,9 @@ fn opencode_config_path() -> Option<PathBuf> {
         .ok()
         .map(PathBuf::from)
         .or_else(|| {
-            std::env::var("HOME")
+            openshell_core::paths::home_dir()
                 .ok()
-                .map(|h| PathBuf::from(h).join(".config"))
+                .map(|h| h.join(".config"))
         })?;
     Some(config_home.join("opencode").join("opencode.json"))
 }

crates/openshell-server/src/compute/vm.rs

@@ -234,9 +234,9 @@ fn resolve_driver_search_dirs(vm_config: &VmComputeConfig) -> Vec<PathBuf> {
                 push_unique_path(&mut dirs, prefix.join("libexec"));
                 push_unique_path(&mut dirs, prefix.join("libexec").join("openshell"));
             }
-            for dir in VmComputeConfig::default_driver_search_dirs(
-                std::env::var_os("HOME").map(PathBuf::from),
-            ) {
+            for dir in
+                VmComputeConfig::default_driver_search_dirs(openshell_core::paths::home_dir().ok())
+            {
                 push_unique_path(&mut dirs, dir);
             }
             dirs