reorder run params & update README

2025-08-04 16:56:19 -04:00 · 2025-08-04 16:56:19 -04:00 · acf7e2f8b8
commit acf7e2f8b8
parent eab27b1f66
9 changed files with 44 additions and 45 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  
-  - [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)  
+- **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
@ -7,8 +7,8 @@ use harmony::{
 #[tokio::main]
 async fn main() {
    harmony_cli::run(
-        LocalhostTopology::new(),
        Inventory::autoload(),
+        LocalhostTopology::new(),
        vec![
            Box::new(SuccessScore {}),
            Box::new(ErrorScore {}),
--- a/examples/lamp/src/main.rs
+++ b/examples/lamp/src/main.rs
@ -43,8 +43,8 @@ async fn main() {
    // locally, to development environment from a CI, to staging, and to production with settings
    // that automatically adapt to each environment grade.
    harmony_cli::run(
-        K8sAnywhereTopology::from_env(),
        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
        vec![Box::new(lamp_stack)],
        None,
    )
--- a/examples/monitoring/src/main.rs
+++ b/examples/monitoring/src/main.rs
@ -75,8 +75,8 @@ async fn main() {
    };

    harmony_cli::run(
-        K8sAnywhereTopology::from_env(),
        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
        vec![Box::new(alerting_score)],
        None,
    )
--- a/examples/monitoring_with_tenant/src/main.rs
+++ b/examples/monitoring_with_tenant/src/main.rs
@ -79,8 +79,8 @@ async fn main() {
    };

    harmony_cli::run(
-        K8sAnywhereTopology::from_env(),
        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
        vec![Box::new(tenant), Box::new(alerting_score)],
        None,
    )
--- a/examples/ntfy/src/main.rs
+++ b/examples/ntfy/src/main.rs
@ -5,8 +5,8 @@ use harmony::{
 #[tokio::main]
 async fn main() {
    harmony_cli::run(
-        K8sAnywhereTopology::from_env(),
        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
        vec![Box::new(NtfyScore {
            namespace: "monitoring".to_string(),
            host: "localhost".to_string(),
--- a/examples/rust/src/main.rs
+++ b/examples/rust/src/main.rs
@ -31,8 +31,8 @@ async fn main() {
    };

    harmony_cli::run(
-        K8sAnywhereTopology::from_env(),
        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
        vec![Box::new(app)],
        None,
    )
--- a/examples/tenant/src/main.rs
+++ b/examples/tenant/src/main.rs
@ -16,8 +16,8 @@ async fn main() {
    };

    harmony_cli::run(
-        K8sAnywhereTopology::from_env(),
        Inventory::autoload(),
+        K8sAnywhereTopology::from_env(),
        vec![Box::new(tenant)],
        None,
    )
--- a/harmony_cli/src/lib.rs
+++ b/harmony_cli/src/lib.rs
@ -87,8 +87,8 @@ fn list_scores_with_index<T: Topology>(scores_vec: &Vec<Box<dyn Score<T>>>) -> S
 }

 pub async fn run<T: Topology + Send + Sync + 'static>(
-    topology: T,
    inventory: Inventory,
+    topology: T,
    scores: Vec<Box<dyn Score<T>>>,
    args_struct: Option<Args>,
 ) -> Result<(), Box<dyn std::error::Error>> {