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

README.md

@@ -1,5 +1,6 @@
-# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code.
+# Harmony : Open-source infrastructure orchestration that treats your platform like first-class code
-*By [NationTech](https://nationtech.io)*
+
+_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 |
+| 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. |
+| **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. |
+| **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. |
+| **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
+    // 2. Enhance with extra scores (monitoring, CI/CD, …)
-    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, …)
     let mut monitoring = MonitoringAlertingStackScore::new();
     monitoring.namespace = Some(lamp_stack.config.namespace.clone());
 
-    maestro.register_all(vec![Box::new(lamp_stack), Box::new(monitoring)]);
+    // 3. Run your scores on the desired topology & inventory
-
+    harmony_cli::run(
-    // 4. Launch an interactive CLI / TUI
+        Inventory::autoload(),                // auto-detect hardware / kube-config
-    harmony_cli::init(maestro, None).await.unwrap();
+        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 |
+| Term             | One-liner                                                                                            |
-|------|-----------|
+| ---------------- | ---------------------------------------------------------------------------------------------------- |
-| **Score<T>** | Declarative description of the desired state (e.g., `LAMPScore`). |
+| **Score<T>**     | Declarative description of the desired state (e.g., `LAMPScore`).                                    |
-| **Interpret<T>** | Imperative logic that realises a `Score` on a specific environment. |
+| **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, …). |
+| **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**. |
+| **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. |
+| **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 
+- Rust
-* Docker (if you deploy locally)
+- Docker (if you deploy locally)
-* `kubectl` / `helm` for Kubernetes-based topologies
+- `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_

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();
+    harmony_cli::run(
-    let topology = LocalhostTopology::new();
+        Inventory::autoload(),
-    let mut maestro = Maestro::initialize(inventory, topology).await.unwrap();
+        LocalhostTopology::new(),
-
+        vec![
-    maestro.register_all(vec![
+            Box::new(SuccessScore {}),
-        Box::new(SuccessScore {}),
+            Box::new(ErrorScore {}),
-        Box::new(ErrorScore {}),
+            Box::new(PanicScore {}),
-        Box::new(PanicScore {}),
+        ],
-    ]);
+        None,
-    harmony_cli::init(maestro, None).await.unwrap();
+    )
+    .await
+    .unwrap();
 }

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.

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();
 }

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();
 }

examples/ntfy/src/main.rs

@@ -1,20 +1,18 @@
 use harmony::{
-    inventory::Inventory, maestro::Maestro, modules::monitoring::ntfy::ntfy::NtfyScore,
+    inventory::Inventory, modules::monitoring::ntfy::ntfy::NtfyScore, topology::K8sAnywhereTopology,
-    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();
 }

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::run(
-    harmony_cli::init(maestro, None).await.unwrap();
+        Inventory::autoload(),
-
+        K8sAnywhereTopology::from_env(),
-    let _ = tokio::try_join!(cli_logger_handle);
+        vec![Box::new(app)],
+        None,
+    )
+    .await
+    .unwrap();
 }

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

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};
 

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>> {