refactor: extract hm-util crate + modernize CancellationToken

CLAUDE.md

@@ -1,6 +1,7 @@
 The `cli/` directory is a Cargo workspace.
 
 - `crates/hm/` — the `hm` binary (today's CLI body).
+- `crates/hm-util/` — shared OS and filesystem utilities.
 - `crates/hm-plugin-protocol/` — wire types (serde structs only).
 - `crates/hm-plugin-sdk/` — authoring SDK for plugin writers.
 - `crates/hm-fixtures/` — test-only WASM plugins; compiled to

Cargo.toml

@@ -9,11 +9,13 @@ members = [
     "crates/hm-plugin-output-json",
     "crates/hm-plugin-cloud",
     "crates/hm-fixtures",
+    "crates/hm-util",
 ]
 default-members = [
     "crates/hm",
     "crates/hm-plugin-protocol",
     "crates/hm-plugin-sdk",
+    "crates/hm-util",
 ]
 
 [workspace.package]
@@ -24,6 +26,7 @@ repository = "https://github.com/harmont-dev/harmont-cli"
 [workspace.dependencies]
 hm-plugin-protocol = { path = "crates/hm-plugin-protocol", version = "0.0.0-dev" }
 hm-plugin-sdk      = { path = "crates/hm-plugin-sdk",      version = "0.0.0-dev" }
+hm-util            = { path = "crates/hm-util",            version = "0.0.0-dev" }
 serde       = { version = "1", features = ["derive"] }
 serde_json  = "1"
 schemars    = { version = "0.8", features = ["preserve_order", "semver", "uuid1", "chrono"] }
@@ -54,6 +57,9 @@ cargo_common_metadata = "allow"
 # schemars 0.8 pulls older indexmap / wit-bindgen transitively; we
 # can't fix without bumping schemars.
 multiple_crate_versions = "allow"
+# `pub(crate)` inside a non-pub module triggers this, but `unreachable_pub`
+# already enforces the same invariant from the rustc side.
+redundant_pub_crate = "allow"
 dbg_macro = "deny"
 todo = "deny"
 unimplemented = "deny"

crates/hm-util/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "hm-util"
+version = "0.0.0-dev"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Shared OS and filesystem utilities for Harmont crates."
+
+[dependencies]
+dirs = "6"
+tokio = { version = "1", features = ["rt", "fs"] }
+
+[target.'cfg(windows)'.dependencies.windows]
+version = "0.62"
+features = [
+    "Win32_Foundation",
+    "Win32_Storage_FileSystem",
+]
+
+[dev-dependencies]
+tempfile = "3"
+tokio = { version = "1", features = ["full", "test-util"] }
+
+[lints]
+workspace = true

crates/hm-util/src/dirs.rs

@@ -0,0 +1,62 @@
+//! Harmont-specific directory resolution.
+//!
+//! Every directory accessor in this module returns a Harmont-namespaced
+//! path. Raw platform primitives (`home_dir`, `config_dir`) live in
+//! `os::dirs` and are **not** re-exported — callers outside `hm-util`
+//! should never need them.
+
+#![allow(clippy::must_use_candidate)]
+
+use std::path::PathBuf;
+
+use crate::os::dirs as platform;
+
+/// `~/.harmont/` — CLI config home (config.toml, credentials.toml).
+pub fn harmont_config_dir() -> Option<PathBuf> {
+    platform::home_dir().map(|h| h.join(".harmont"))
+}
+
+/// `<config_dir>/harmont/` — XDG-aware data root (plugins, state).
+pub fn harmont_data_dir() -> Option<PathBuf> {
+    platform::config_dir().map(|c| c.join("harmont"))
+}
+
+/// `<config_dir>/harmont/plugins/` — user-global plugin directory.
+pub fn harmont_plugins_dir() -> Option<PathBuf> {
+    harmont_data_dir().map(|d| d.join("plugins"))
+}
+
+/// `<config_dir>/harmont/state/` — per-plugin persistent KV state.
+pub fn harmont_plugin_state_dir() -> Option<PathBuf> {
+    harmont_data_dir().map(|d| d.join("state"))
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn harmont_config_dir_under_home() {
+        let p = harmont_config_dir().unwrap();
+        assert!(p.ends_with(".harmont"));
+    }
+
+    #[test]
+    fn harmont_data_dir_under_config() {
+        let p = harmont_data_dir().unwrap();
+        assert!(p.ends_with("harmont"));
+    }
+
+    #[test]
+    fn harmont_plugins_dir_resolves() {
+        let p = harmont_plugins_dir().unwrap();
+        assert!(p.ends_with("harmont/plugins"));
+    }
+
+    #[test]
+    fn harmont_plugin_state_dir_resolves() {
+        let p = harmont_plugin_state_dir().unwrap();
+        assert!(p.ends_with("harmont/state"));
+    }
+}

crates/hm-util/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod os;
+pub mod dirs;

crates/hm-util/src/os/dirs.rs

@@ -0,0 +1,14 @@
+//! Raw platform directory primitives.
+//!
+//! This module is `pub(crate)` — external callers must use
+//! [`crate::dirs`] which provides Harmont-specific accessors.
+
+use std::path::PathBuf;
+
+pub(crate) fn home_dir() -> Option<PathBuf> {
+    dirs::home_dir()
+}
+
+pub(crate) fn config_dir() -> Option<PathBuf> {
+    dirs::config_dir()
+}