History

Ian Letourneau 06aab1f57f All checks were successful Run Check Script / check (push) Successful in -37s Details Compile and package harmony_composer / package_harmony_composer (push) Successful in 9m6s Details fix(cli): reduce noise & better track progress within Harmony (#91 ) Introduce a way to instrument what happens within Harmony and around Harmony (e.g. in the CLI or in Composer). The goal is to provide visual feedback to the end users and inform them of the progress of their tasks (e.g. deployment) as clearly as possible. It is important to also let them know of the outcome of their tasks (what was created, where to access stuff, etc.). <img src="https://media.discordapp.net/attachments/1295353830300713062/1400289618636574741/demo.gif?ex=688c18d5&is=688ac755&hm=2c70884aacb08f7bd15cbb65a7562a174846906718aa15294bbb238e64febbce&=" /> ## Changes ### Instrumentation architecture Extensibility and ease of use is key here, while preserving type safety as much as possible. The proposed API is quite simple: ```rs // Emit an event instrumentation::instrument( HarmonyEvent::TopologyPrepared { topology: "k8s-anywhere", outcome: Outcome::success("yay") } ); // Consume events instrumentation::subscribe("Harmony CLI Logger", async \|event\| { match event { HarmonyEvent::TopologyPrepared { name, outcome } => todo!(), } }); ``` #### Current limitations * this API is not very extensible, but it could be easily changed to allow end users to define custom events in addition to Harmony core events * we use a tokio broadcast channel behind the scene so only in process communication can happen, but it could be easily changed to a more flexible communication mechanism as implementation details are hidden ### `harmony_composer` VS `harmony_cli` As Harmony Composer launches commands from Harmony (CLI), they both live in different processes. And because of this, we cannot easily make all the logging happens in one place (Harmony Composer) and get rid of Harmony CLI. At least not without introducing additional complexity such as communication through a server, unix socket, etc. So for the time being, it was decided to preserve both `harmony_composer` and `harmony_cli` and let them independently log their stuff and handle their own responsibilities: * `harmony_composer`: takes care only of setting up & packaging a project, delegates everything else to `harmony_cli` * `harmony_cli`: takes care of configuring & running Harmony ### Logging & prompts * [indicatif](https://github.com/console-rs/indicatif) is used to create progress bars and track progress within Harmony, Harmony CLI, and Harmony Composer * [inquire](https://github.com/mikaelmello/inquire) is preserved, but was removed from `harmony` (core) as UI concerns shouldn't go that deep * note: for now the only prompt we had was simply deleted, we'll have to find a better way to prompt stuff in the future ## Todos * [ ] Update/Create ADRs * [ ] Continue instrumentation for missing branches * [ ] Allow instrumentation to emit and subscribe to custom events Co-authored-by: Ian Letourneau <letourneau.ian@gmail.com> Reviewed-on: https://git.nationtech.io/NationTech/harmony/pulls/91 Reviewed-by: johnride <jg@nationtech.io>		2025-07-31 19:35:33 +00:00
..
src	fix(cli): reduce noise & better track progress within Harmony (#91 )	2025-07-31 19:35:33 +00:00
Cargo.toml	fix(cli): reduce noise & better track progress within Harmony (#91 )	2025-07-31 19:35:33 +00:00
README.md	doc: Fix curl command for environments without ~/.local/bin/ folder	2025-07-01 11:32:24 -04:00

README.md

harmony_composer

harmony_composer is a command-line utility for compiling and bootstrapping deployments for the Harmony orchestration framework.

It's designed to simplify the build process by either compiling a Harmony project found in a local harmony directory or by bootstrapping a new deployment through auto-detection of the current project type.

⚡ Quick Install & Run (Linux x86-64)

You can download and run the latest snapshot build with a single command. This will place the binary in ~/.local/bin, which should be in your PATH on most modern Linux distributions.

mkdir -p ~/.local/bin && \
curl -L https://git.nationtech.io/NationTech/harmony/releases/download/snapshot-latest/harmony_composer \
  -o ~/.local/bin/harmony_composer && \
chmod +x ~/.local/bin/harmony_composer && \
alias hc=~/.local/bin/harmony_composer && \
echo "\n\nharmony_composer installed successfully\!\n\nUse \`hc\` to run it.\n\nNote : this hc alias only works for the current shell session. Add 'alias hc=~/.local/bin/harmony_composer' to your '~/.bashrc' or '~/.zshrc' file to make it permanently available to your user."

Then you can start using it with either :

harmony_composer if ~/.local/bin is in you $PATH
hc alias set up in your current shell session.
- If you want to make the hc command always available, add alias hc=~/.local/bin/harmony_composer to your shell profile. Usually ~/.bashrc for bash, ~/.zshrc for zsh.

⚠️ Warning: Unstable Builds The snapshot-latest tag points to the latest build from the master branch. It is unstable, unsupported, and intended only for early testing of new features. Please do not use it in production environments.

⚙️ How It Works

harmony_composer requires either cargo or docker to be available on your system to compile the Harmony project.

If cargo is found: It will be used to compile the project locally.
If cargo is not found: It will automatically download and run the harmony_composer Docker image. This image is a self-contained build environment with the required Cargo binary and build targets for both Linux and Windows.
If both cargo and docker are unavailable, harmony_composer will fail. Please install one of them.

📖 Basic Usage

Here are some common commands:


# Compile the repo's Harmony module
harmony_composer compile

# Run check script on the project
harmony_composer check

# Run the repo's entire harmony deployment sequence
harmony_composer deploy

# Run the full check, compile, and deploy pipeline
harmony_composer all

For a full list of commands and their options, run:


harmony_composer --help

🏗️ Supported Architectures

The build system currently supports compiling for:

x86_64-unknown-linux-gnu
x86_64-pc-windows-gnu

More target architectures are planned. If your platform is not yet supported, please open a feature request in the main repository.

🔗 Main Project

This tool is a small part of the main Harmony project. For complete documentation, contribution guidelines, and license information, please refer to the main repository.