fix(config): migrate ~/.harmont config forward, plumb HARMONT_* env, hint on legacy .harmont/ project dir (#133)

Author: markovejnovic

Cargo.lock

@@ -271,7 +271,7 @@ and stores the token in `~/.config/hm/credentials.toml` (mode 0600). No browser?
 Use `hm cloud login --paste`. In CI, set a token instead:
 
 ```sh
-export HARMONT_API_TOKEN=hm_live_...   # takes precedence over the file
+export HM_API_TOKEN=hm_live_...   # takes precedence over the file
 hm run --cloud --org acme
 ```
 
@@ -284,7 +284,7 @@ hm run --cloud --org acme
 
 Settings layer **defaults → user config → project `.hm/config.toml` → env**, so
 you can commit per-repo defaults and still override them locally. Env overrides:
-`HARMONT_API_URL`, `HARMONT_API_TOKEN`.
+`HM_API_URL`, `HM_API_TOKEN`.
 
 ### Managing builds from the CLI
 

README.md

@@ -17,6 +17,8 @@ anyhow = "1"
 [dev-dependencies]
 tempfile = "3"
 tokio = { workspace = true }
+# `test` brings in `figment::Jail` for isolated env-var/cwd testing.
+figment = { workspace = true, features = ["test"] }
 
 [lints]
 workspace = true

crates/hm-config/Cargo.toml

@@ -66,12 +66,12 @@ pub const CLOUD_SERVICE: &str = "harmont-cloud";
 
 /// Resolve the cloud bearer token for `api_base`.
 ///
-/// Priority: `HARMONT_API_TOKEN` env (non-empty) first, then the stored
+/// Priority: `HM_API_TOKEN` env (non-empty) first, then the stored
 /// credential keyed by `(CLOUD_SERVICE, api_base)`. Returns `None` when
 /// neither is present, so the caller can produce a clear "not logged in" error.
 #[must_use]
 pub fn cloud_token(api_base: &str) -> Option<String> {
-    if let Ok(t) = std::env::var("HARMONT_API_TOKEN")
+    if let Ok(t) = std::env::var("HM_API_TOKEN")
         && !t.is_empty()
     {
         return Some(t);

crates/hm-config/src/creds.rs

@@ -43,7 +43,7 @@ pub enum Backend {
 /// the host first.
 ///
 /// Priority:
-/// 1. `override_url` (e.g. the `HARMONT_APP_URL` env override) when non-empty,
+/// 1. `override_url` (e.g. the `HM_APP_URL` env override) when non-empty,
 /// 2. heuristic mapping of `api.` → `app.` on the API host,
 /// 3. the API base itself (last-resort dev fallback for hosts like
 ///    `localhost` that have no `api.`/`app.` split).
@@ -139,6 +139,14 @@ impl Config {
 
     /// Testable core: build a `Config` from explicit file paths.
     ///
+    /// Layering, lowest to highest precedence: defaults -> user file ->
+    /// project file -> env.
+    ///
+    /// Env precedence (highest): both the `HM_`-prefixed split form
+    /// (`HM_CLOUD__ORG`, `HM_CLOUD__API_URL`) and the documented
+    /// `HM_ORG` / `HM_API_URL` are honored; the latter map onto
+    /// `cloud.org` / `cloud.api_url`.
+    ///
     /// # Errors
     ///
     /// Returns an error if figment extraction fails (malformed TOML, type mismatches).
@@ -152,7 +160,9 @@ impl Config {
             figment = figment.merge(Toml::file(p));
         }
 
-        figment = figment.merge(Env::prefixed("HM_").split("__"));
+        figment = figment
+            .merge(Env::prefixed("HM_").split("__"))
+            .merge(hm_alias_env());
 
         Ok(figment.extract()?)
     }
@@ -183,11 +193,45 @@ impl Config {
     }
 }
 
+/// Figment env provider mapping the friendly `HM_ORG` / `HM_API_URL`
+/// variables onto the nested `cloud` config keys.
+///
+/// The cloud settings docs and `hm`'s error messages tell users to
+/// `set HM_ORG=<slug>` / `HM_API_URL=<url>`, so those flat names must feed
+/// the config. This binds them to `cloud.org` / `cloud.api_url` alongside the
+/// generic `HM_`-prefixed split layer (`HM_CLOUD__ORG`, …).
+fn hm_alias_env() -> Env {
+    Env::raw()
+        .only(&["HM_ORG", "HM_API_URL"])
+        .map(|key| match key.as_str() {
+            "HM_ORG" => "cloud.org".into(),
+            "HM_API_URL" => "cloud.api_url".into(),
+            other => other.into(),
+        })
+        .split(".")
+}
+
 #[cfg(test)]
 #[allow(clippy::unwrap_used)]
 mod tests {
     use super::*;
     use std::io::Write as _;
+    use std::sync::{Mutex, MutexGuard};
+
+    /// Serializes every test that resolves config through `load_*`.
+    ///
+    /// All `load_*` paths merge the process environment as their top layer, so
+    /// a test that sets `HM_*` (via `figment::Jail`, which mutates the
+    /// real process env for the duration of its closure) would otherwise leak
+    /// into a concurrently-running file-layering test. Holding this lock for
+    /// the whole body of any env-or-load test makes them mutually exclusive.
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
+
+    fn env_guard() -> MutexGuard<'static, ()> {
+        ENV_LOCK
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner)
+    }
 
     #[test]
     fn app_url_maps_prod_api_to_app() {
@@ -250,6 +294,7 @@ auto_watch = true
 
     #[test]
     fn deserialize_sparse_toml() {
+        let _g = env_guard();
         let toml_str = r#"
 [cloud]
 org = "sparse-co"
@@ -266,6 +311,7 @@ org = "sparse-co"
 
     #[test]
     fn deserialize_empty_toml() {
+        let _g = env_guard();
         let mut f = tempfile::NamedTempFile::new().unwrap();
         f.write_all(b"").unwrap();
 
@@ -278,6 +324,7 @@ org = "sparse-co"
 
     #[test]
     fn figment_project_overrides_user() {
+        let _g = env_guard();
         let user_toml = r#"
 [cloud]
 org = "user-org"
@@ -313,6 +360,7 @@ org = "project-org"
 
     #[test]
     fn backend_defaults_docker_and_parses_and_layers() {
+        let _g = env_guard();
         // default
         assert_eq!(Config::default().backend, Backend::Docker);
 
@@ -334,6 +382,7 @@ org = "project-org"
 
     #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
     async fn save_and_reload_roundtrip() {
+        let _g = env_guard();
         let tmp = tempfile::tempdir().unwrap();
         let path = tmp.path().join("config.toml");
         let cfg = Config {
@@ -351,8 +400,47 @@ org = "project-org"
         assert_eq!(loaded.preferences.format, "human");
     }
 
+    #[test]
+    #[allow(clippy::result_large_err)] // figment::Error is the Jail closure's error type.
+    fn hm_env_overrides_cloud_keys() {
+        let _g = env_guard();
+        // `Jail` isolates env mutation from concurrently-running tests.
+        figment::Jail::expect_with(|jail| {
+            jail.set_env("HM_ORG", "env-org");
+            jail.set_env("HM_API_URL", "https://env.api");
+
+            let cfg = Config::load_from_paths(None, None).unwrap();
+            assert_eq!(cfg.cloud.org.as_deref(), Some("env-org"));
+            assert_eq!(cfg.cloud.api_url, "https://env.api");
+            Ok(())
+        });
+    }
+
+    #[test]
+    #[allow(clippy::result_large_err)] // figment::Error is the Jail closure's error type.
+    fn hm_env_overrides_user_file() {
+        let _g = env_guard();
+        // Env is the highest-precedence layer: it wins over a user file.
+        figment::Jail::expect_with(|jail| {
+            jail.set_env("HM_ORG", "env-org");
+
+            jail.create_file(
+                "config.toml",
+                "[cloud]\norg = \"file-org\"\napi_url = \"https://file.api\"\n",
+            )?;
+            let user = jail.directory().join("config.toml");
+
+            let cfg = Config::load_from_paths(Some(&user), None).unwrap();
+            assert_eq!(cfg.cloud.org.as_deref(), Some("env-org"));
+            // Unset env keys still come from the file.
+            assert_eq!(cfg.cloud.api_url, "https://file.api");
+            Ok(())
+        });
+    }
+
     #[test]
     fn figment_missing_files_still_resolve() {
+        let _g = env_guard();
         let nonexistent_user = Path::new("/tmp/harmont-test-nonexistent-user/config.toml");
         let nonexistent_project = Path::new("/tmp/harmont-test-nonexistent-project/config.toml");
 

crates/hm-config/src/lib.rs

@@ -68,7 +68,7 @@ def dump_registry_json(
     """Emit the schema_version=1 envelope JSON.
 
     Defaults mirror ``pipeline_to_json``:
-      ``pipeline_org`` <- ``env["HARMONT_PIPELINE_ORG"]`` or ``"default"``
+      ``pipeline_org`` <- ``env["HM_PIPELINE_ORG"]`` or ``"default"``
       ``now``          <- ``int(time.time())``
       ``base_path``    <- ``Path.cwd()`` (resolves ``on_change`` cache paths)
       ``env``          <- ``os.environ``
@@ -81,11 +81,7 @@ def dump_registry_json(
     """
     clear_target_memo()
     env_map: Mapping[str, str] = env if env is not None else os.environ
-    org = (
-        pipeline_org
-        if pipeline_org is not None
-        else env_map.get("HARMONT_PIPELINE_ORG", "default")
-    )
+    org = pipeline_org if pipeline_org is not None else env_map.get("HM_PIPELINE_ORG", "default")
     render_now = now if now is not None else int(time.time())
     bp = base_path if base_path is not None else Path.cwd()
     return json.dumps(

crates/hm-dsl-engine/harmont-py/harmont/_envelope.py

@@ -37,22 +37,16 @@ def pipeline_to_json(
 
     Resolves cache keys before serialization. Defaults mirror the
     environment hooks of the old Scheme renderer:
-      pipeline_org  <- env["HARMONT_PIPELINE_ORG"] or "default"
-      pipeline_slug <- env["HARMONT_PIPELINE_SLUG"] or "default"
+      pipeline_org  <- env["HM_PIPELINE_ORG"] or "default"
+      pipeline_slug <- env["HM_PIPELINE_SLUG"] or "default"
       now           <- int(time.time())
       base_path     <- Path.cwd()
       env           <- os.environ
     """
     env_map: Mapping[str, str] = env if env is not None else os.environ
-    org = (
-        pipeline_org
-        if pipeline_org is not None
-        else env_map.get("HARMONT_PIPELINE_ORG", "default")
-    )
+    org = pipeline_org if pipeline_org is not None else env_map.get("HM_PIPELINE_ORG", "default")
     slug = (
-        pipeline_slug
-        if pipeline_slug is not None
-        else env_map.get("HARMONT_PIPELINE_SLUG", "default")
+        pipeline_slug if pipeline_slug is not None else env_map.get("HM_PIPELINE_SLUG", "default")
     )
     render_now = now if now is not None else int(time.time())
     bp = base_path if base_path is not None else Path.cwd()

crates/hm-dsl-engine/harmont-py/harmont/json_emit.py

@@ -1,7 +1,7 @@
 """Shared helpers for rendering external example pipelines.
 
 These tests render the pipeline definitions in harmont-cli/examples/
-to v0 IR JSON. They are gated behind HARMONT_CLI_PATH so they only
+to v0 IR JSON. They are gated behind HM_CLI_PATH so they only
 run when a sibling harmont-cli checkout is available.
 """
 
@@ -19,7 +19,7 @@
 
 
 def harmont_cli_examples_root() -> pathlib.Path | None:
-    raw = os.environ.get("HARMONT_CLI_PATH")
+    raw = os.environ.get("HM_CLI_PATH")
     if not raw:
         return None
     p = pathlib.Path(raw) / "examples"

crates/hm-dsl-engine/harmont-py/tests/examples_render_conftest.py

@@ -1,6 +1,6 @@
 """End-to-end render checks against harmont-cli example pipelines.
 
-Gated: skipped when HARMONT_CLI_PATH is unset. CI sets it after
+Gated: skipped when HM_CLI_PATH is unset. CI sets it after
 cloning harmont-cli.
 """
 
@@ -24,7 +24,7 @@
 
 pytestmark = pytest.mark.skipif(
     EXAMPLES_ROOT is None,
-    reason="HARMONT_CLI_PATH not set or examples/ missing",
+    reason="HM_CLI_PATH not set or examples/ missing",
 )
 
 

crates/hm-dsl-engine/harmont-py/tests/test_examples_render.py

@@ -37,7 +37,7 @@ export function renderEnvelope(
   const pipelineOrg =
     opts?.pipelineOrg ??
     (typeof process !== "undefined"
-      ? process.env.HARMONT_PIPELINE_ORG
+      ? process.env.HM_PIPELINE_ORG
       : undefined) ??
     "default";
   const now = opts?.now ?? Math.floor(Date.now() / 1000);