fix(cli): simplify running the CLI by hiding the maestro inside the implemtation (#93)

Co-authored-by: Ian Letourneau <letourneau.ian@gmail.com> Reviewed-on: https://git.nationtech.io/NationTech/harmony/pulls/93
2025-08-04 20:59:07 +00:00 · 2025-08-04 20:59:07 +00:00 · 54990cd1a5
commit 54990cd1a5
parent 06aab1f57f
10 changed files with 99 additions and 95 deletions
--- a/README.md
+++ b/README.md
@ -1,5 +1,6 @@
-# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code.
-*By [NationTech](https://nationtech.io)*
+# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code
+
+_By [NationTech](https://nationtech.io)_

 [![Build](https://git.nationtech.io/NationTech/harmony/actions/workflows/check.yml/badge.svg)](https://git.nationtech.io/nationtech/harmony)
 [![License](https://img.shields.io/badge/license-AGPLv3-blue?style=flat-square)](LICENSE)
@ -23,11 +24,11 @@ From a **developer laptop** to a **global production cluster**, a single **sourc

 Infrastructure is essential, but it shouldn’t be your core business. Harmony is built on three guiding principles that make modern platforms reliable, repeatable, and easy to reason about.

-| Principle | What it means for you |
-|-----------|-----------------------|
-| **Infrastructure as Resilient Code** | Replace sprawling YAML and bash scripts with type-safe Rust. Test, refactor, and version your platform just like application code. |
-| **Prove It Works — Before You Deploy** | Harmony uses the compiler to verify that your application’s needs match the target environment’s capabilities at **compile-time**, eliminating an entire class of runtime outages. |
-| **One Unified Model** | Software and infrastructure are a single system. Harmony models them together, enabling deep automation—from bare-metal servers to Kubernetes workloads—with zero context switching. |
+| Principle                              | What it means for you                                                                                                                                                                |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Infrastructure as Resilient Code**   | Replace sprawling YAML and bash scripts with type-safe Rust. Test, refactor, and version your platform just like application code.                                                   |
+| **Prove It Works — Before You Deploy** | Harmony uses the compiler to verify that your application’s needs match the target environment’s capabilities at **compile-time**, eliminating an entire class of runtime outages.   |
+| **One Unified Model**                  | Software and infrastructure are a single system. Harmony models them together, enabling deep automation—from bare-metal servers to Kubernetes workloads—with zero context switching. |

 These principles surface as simple, ergonomic Rust APIs that let teams focus on their product while trusting the platform underneath.

@ -63,22 +64,20 @@ async fn main() {
        },
    };

-    // 2. Pick where it should run
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
-        Inventory::autoload(),                // auto-detect hardware / kube-config
-        K8sAnywhereTopology::from_env(),      // local k3d, CI, staging, prod…
-    )
-    .await
-    .unwrap();
-
-    // 3. Enhance with extra scores (monitoring, CI/CD, …)
+    // 2. Enhance with extra scores (monitoring, CI/CD, …)
    let mut monitoring = MonitoringAlertingStackScore::new();
    monitoring.namespace = Some(lamp_stack.config.namespace.clone());

-    maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring)]);
-
-    // 4. Launch an interactive CLI / TUI
-    harmony_cli::init(maestro, None).await.unwrap();
+    // 3. Run your scores on the desired topology & inventory
+    harmony_cli::run(
+        Inventory::autoload(),                // auto-detect hardware / kube-config
+        K8sAnywhereTopology::from_env(),      // local k3d, CI, staging, prod…
+        vec![
+          Box::new(lamp_stack),
+          Box::new(monitoring)
+        ],
+        None
+    ).await.unwrap();
 }
 ```

@ -94,13 +93,13 @@ Harmony analyses the code, shows an execution plan in a TUI, and applies it once

 ## 3 · Core Concepts

-| Term | One-liner |
-|------|-----------|
-| **Score<T>** | Declarative description of the desired state (e.g., `LAMPScore`). |
-| **Interpret<T>** | Imperative logic that realises a `Score` on a specific environment. |
-| **Topology** | An environment (local k3d, AWS, bare-metal) exposing verified *Capabilities* (Kubernetes, DNS, …). |
-| **Maestro** | Orchestrator that compiles Scores + Topology, ensuring all capabilities line up **at compile-time**. |
-| **Inventory** | Optional catalogue of physical assets for bare-metal and edge deployments. |
+| Term             | One-liner                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------------------------- |
+| **Score<T>**     | Declarative description of the desired state (e.g., `LAMPScore`).                                    |
+| **Interpret<T>** | Imperative logic that realises a `Score` on a specific environment.                                  |
+| **Topology**     | An environment (local k3d, AWS, bare-metal) exposing verified _Capabilities_ (Kubernetes, DNS, …).   |
+| **Maestro**      | Orchestrator that compiles Scores + Topology, ensuring all capabilities line up **at compile-time**. |
+| **Inventory**    | Optional catalogue of physical assets for bare-metal and edge deployments.                           |

 A visual overview is in the diagram below.

@ -112,9 +111,9 @@ A visual overview is in the diagram below.

 Prerequisites:

-* Rust 
-* Docker (if you deploy locally)
-* `kubectl` / `helm` for Kubernetes-based topologies
+- Rust
+- Docker (if you deploy locally)
+- `kubectl` / `helm` for Kubernetes-based topologies

 ```bash
 git clone https://git.nationtech.io/nationtech/harmony
@ -126,15 +125,15 @@ cargo build --release          # builds the CLI, TUI and libraries

 ## 5 · Learning More

-* **Architectural Decision Records** – dive into the rationale  
+- **Architectural Decision Records** – dive into the rationale
  - [ADR-001 · Why Rust](adr/001-rust.md)
  - [ADR-003 · Infrastructure Abstractions](adr/003-infrastructure-abstractions.md)
  - [ADR-006 · Secret Management](adr/006-secret-management.md)
  - [ADR-011 · Multi-Tenant Cluster](adr/011-multi-tenant-cluster.md)

-* **Extending Harmony** – write new Scores / Interprets, add hardware like OPNsense firewalls, or embed Harmony in your own tooling (`/docs`).
+- **Extending Harmony** – write new Scores / Interprets, add hardware like OPNsense firewalls, or embed Harmony in your own tooling (`/docs`).

-* **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!
+- **Community** – discussions and roadmap live in [GitLab issues](https://git.nationtech.io/nationtech/harmony/-/issues). PRs, ideas, and feedback are welcome!

 ---

@ -148,4 +147,4 @@ See [LICENSE](LICENSE) for the full text.

 ---

-*Made with ❤️ & 🦀 by the NationTech and the Harmony community*
+_Made with ❤️ & 🦀 by the NationTech and the Harmony community_
--- a/examples/cli/src/main.rs
+++ b/examples/cli/src/main.rs
@ -1,20 +1,21 @@
 use harmony::{
    inventory::Inventory,
-    maestro::Maestro,
    modules::dummy::{ErrorScore, PanicScore, SuccessScore},
    topology::LocalhostTopology,
 };

 #[tokio::main]
 async fn main() {
-    let inventory = Inventory::autoload();
-    let topology = LocalhostTopology::new();
-    let mut maestro = Maestro::initialize(inventory, topology).await.unwrap();
-
-    maestro.register_all(vec![
-        Box::new(SuccessScore {}),
-        Box::new(ErrorScore {}),
-        Box::new(PanicScore {}),
-    ]);
-    harmony_cli::init(maestro, None).await.unwrap();
+    harmony_cli::run(
+        Inventory::autoload(),
+        LocalhostTopology::new(),
+        vec![
+            Box::new(SuccessScore {}),
+            Box::new(ErrorScore {}),
+            Box::new(PanicScore {}),
+        ],
+        None,
+    )
+    .await
+    .unwrap();
 }
--- a/examples/lamp/src/main.rs
+++ b/examples/lamp/src/main.rs
@ -1,7 +1,6 @@
 use harmony::{
    data::Version,
    inventory::Inventory,
-    maestro::Maestro,
    modules::lamp::{LAMPConfig, LAMPScore},
    topology::{K8sAnywhereTopology, Url},
 };
@ -43,15 +42,13 @@ async fn main() {
    // K8sAnywhereTopology as it is the most automatic one that enables you to easily deploy
    // locally, to development environment from a CI, to staging, and to production with settings
    // that automatically adapt to each environment grade.
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
+    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
+        vec![Box::new(lamp_stack)],
+        None,
    )
    .await
    .unwrap();
-
-    maestro.register_all(vec![Box::new(lamp_stack)]);
-    // Here we bootstrap the CLI, this gives some nice features if you need them
-    harmony_cli::init(maestro, None).await.unwrap();
 }
 // That's it, end of the infra as code.
--- a/examples/monitoring/src/main.rs
+++ b/examples/monitoring/src/main.rs
@ -2,7 +2,6 @@ use std::collections::HashMap;

 use harmony::{
    inventory::Inventory,
-    maestro::Maestro,
    modules::{
        monitoring::{
            alert_channel::discord_alert_channel::DiscordWebhook,
@ -74,13 +73,13 @@ async fn main() {
        rules: vec![Box::new(additional_rules), Box::new(additional_rules2)],
        service_monitors: vec![service_monitor],
    };
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
+
+    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
+        vec![Box::new(alerting_score)],
+        None,
    )
    .await
    .unwrap();
-
-    maestro.register_all(vec![Box::new(alerting_score)]);
-    harmony_cli::init(maestro, None).await.unwrap();
 }
--- a/examples/monitoring_with_tenant/src/main.rs
+++ b/examples/monitoring_with_tenant/src/main.rs
@ -3,7 +3,6 @@ use std::collections::HashMap;
 use harmony::{
    data::Id,
    inventory::Inventory,
-    maestro::Maestro,
    modules::{
        monitoring::{
            alert_channel::discord_alert_channel::DiscordWebhook,
@ -78,13 +77,13 @@ async fn main() {
        rules: vec![Box::new(additional_rules)],
        service_monitors: vec![service_monitor],
    };
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
+
+    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
+        vec![Box::new(tenant), Box::new(alerting_score)],
+        None,
    )
    .await
    .unwrap();
-
-    maestro.register_all(vec![Box::new(tenant), Box::new(alerting_score)]);
-    harmony_cli::init(maestro, None).await.unwrap();
 }
--- a/examples/ntfy/src/main.rs
+++ b/examples/ntfy/src/main.rs
@ -1,20 +1,18 @@
 use harmony::{
-    inventory::Inventory, maestro::Maestro, modules::monitoring::ntfy::ntfy::NtfyScore,
-    topology::K8sAnywhereTopology,
+    inventory::Inventory, modules::monitoring::ntfy::ntfy::NtfyScore, topology::K8sAnywhereTopology,
 };

 #[tokio::main]
 async fn main() {
-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
+    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
+        vec![Box::new(NtfyScore {
+            namespace: "monitoring".to_string(),
+            host: "localhost".to_string(),
+        })],
+        None,
    )
    .await
    .unwrap();
-
-    maestro.register_all(vec![Box::new(NtfyScore {
-        namespace: "monitoring".to_string(),
-        host: "localhost".to_string(),
-    })]);
-    harmony_cli::init(maestro, None).await.unwrap();
 }
--- a/examples/rust/src/main.rs
+++ b/examples/rust/src/main.rs
@ -2,24 +2,15 @@ use std::{path::PathBuf, sync::Arc};

 use harmony::{
    inventory::Inventory,
-    maestro::Maestro,
    modules::application::{
        ApplicationScore, RustWebFramework, RustWebapp,
        features::{ContinuousDelivery, Monitoring},
    },
    topology::{K8sAnywhereTopology, Url},
 };
-use harmony_cli::cli_logger;

 #[tokio::main]
 async fn main() {
-    let cli_logger_handle = cli_logger::init();
-
-    let topology = K8sAnywhereTopology::from_env();
-    let mut maestro = Maestro::initialize(Inventory::autoload(), topology)
-        .await
-        .unwrap();
-
    let application = Arc::new(RustWebapp {
        name: "harmony-example-rust-webapp".to_string(),
        domain: Url::Url(url::Url::parse("https://rustapp.harmony.example.com").unwrap()),
@ -39,8 +30,12 @@ async fn main() {
        application,
    };

-    maestro.register_all(vec![Box::new(app)]);
-    harmony_cli::init(maestro, None).await.unwrap();
-
-    let _ = tokio::try_join!(cli_logger_handle);
+    harmony_cli::run(
+        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
+        vec![Box::new(app)],
+        None,
+    )
+    .await
+    .unwrap();
 }
--- a/examples/tenant/src/main.rs
+++ b/examples/tenant/src/main.rs
@ -1,7 +1,6 @@
 use harmony::{
    data::Id,
    inventory::Inventory,
-    maestro::Maestro,
    modules::tenant::TenantScore,
    topology::{K8sAnywhereTopology, tenant::TenantConfig},
 };
@ -16,15 +15,14 @@ async fn main() {
        },
    };

-    let mut maestro = Maestro::<K8sAnywhereTopology>::initialize(
+    harmony_cli::run(
        Inventory::autoload(),
        K8sAnywhereTopology::from_env(),
+        vec![Box::new(tenant)],
+        None,
    )
    .await
    .unwrap();
-
-    maestro.register_all(vec![Box::new(tenant)]);
-    harmony_cli::init(maestro, None).await.unwrap();
 }

 // TODO write tests
--- a/harmony/src/domain/maestro/mod.rs
+++ b/harmony/src/domain/maestro/mod.rs
@ -1,6 +1,6 @@
 use std::sync::{Arc, Mutex, RwLock};

-use log::{debug, info, warn};
+use log::{debug, warn};

 use crate::instrumentation::{self, HarmonyEvent};

--- a/harmony_cli/src/lib.rs
+++ b/harmony_cli/src/lib.rs
@ -1,8 +1,10 @@
 use clap::Parser;
 use clap::builder::ArgPredicate;
-use harmony;
+use harmony::inventory::Inventory;
+use harmony::maestro::Maestro;
 use harmony::{score::Score, topology::Topology};
 use inquire::Confirm;
+use log::debug;

 pub mod cli_logger; // FIXME: Don't make me pub
 pub mod progress;
@ -10,7 +12,6 @@ pub mod theme;

 #[cfg(feature = "tui")]
 use harmony_tui;
-use log::debug;

 #[derive(Parser, Debug)]
 #[command(version, about, long_about = None)]
@ -85,7 +86,24 @@ fn list_scores_with_index<T: Topology>(scores_vec: &Vec<Box<dyn Score<T>>>) -> S
    return display_str;
 }

-pub async fn init<T: Topology + Send + Sync + 'static>(
+pub async fn run<T: Topology + Send + Sync + 'static>(
+    inventory: Inventory,
+    topology: T,
+    scores: Vec<Box<dyn Score<T>>>,
+    args_struct: Option<Args>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let cli_logger_handle = cli_logger::init();
+
+    let mut maestro = Maestro::initialize(inventory, topology).await.unwrap();
+    maestro.register_all(scores);
+
+    let result = init(maestro, args_struct).await;
+
+    let _ = tokio::try_join!(cli_logger_handle);
+    result
+}
+
+async fn init<T: Topology + Send + Sync + 'static>(
    maestro: harmony::maestro::Maestro<T>,
    args_struct: Option<Args>,
 ) -> Result<(), Box<dyn std::error::Error>> {