harmony/ROADMAP/13-unified-cli.md

# Phase 13: Unified CLI — Extensible, Composable, Subcommand-Driven

## Goal

Replace the current landscape of disconnected `harmony-*` binaries and
60+ example `main.rs` files with a single, extensible CLI where:

- The framework provides global concerns (config, SSO, topology selection,
  Score runner, TUI) as shared infrastructure.
- Each module (fleet, tenant, okd, …) registers its own subcommands.
- Third-party `MyAppScore` authors get `harmony myapp deploy` with zero
  framework boilerplate.

The CLI is the user-facing surface of Harmony. Every design decision here
shapes the developer experience for the entire ecosystem.

## Current State

- `harmony_cli::Args` — flat Score-runner flags (`--yes`, `--filter`,
  `--list`, `--number`, `--interactive`). Drives the Maestro loop over
  a `Vec<Score>`.
- `harmony_cli::run(Inventory, Topology, Vec<Score>, Option<Args>)` —
  the single entry point consumed by 60+ example binaries.
- `harmony_tui::run()` — separate crate, separate `run()`, same inputs.
- `harmony-fleet-deploy` — deploy binary with `deploy`/`publish`
  subcommands (just merged from two separate binaries).
- `harmony_composer` — infrastructure composition tool, separate binary.
- ADR-023 principle 8 describes the staged evolution (B → C) but defers
  the plugin protocol.

## Design

### Top-level binary with subcommands

```
harmony [global flags] <module> <action> [action flags]

harmony --config-namespace fleet-staging fleet deploy --from-tag v0.1.0
harmony --config-namespace fleet-staging fleet publish --from-tag v0.1.0 --no-push
harmony --config-namespace okd-staging okd bootstrap
harmony --config-namespace tenant-c1 tenant create --name c1
harmony --config-namespace harmony myapp deploy --image foo:latest
```

Global flags (owned by the top-level binary):
- `--config-namespace` — maps to `ConfigClient::for_namespace()`
- `--kubeconfig` — topology selection
- `--topology` — explicit topology choice (k3d, okd, bare, …)
- `--yes` — skip confirmation prompts
- `--interactive` — delegate to TUI

Module subcommands (owned by each module):
- `fleet deploy`, `fleet publish`
- `tenant create`, `tenant list`, `tenant health`, `tenant install`
- `okd bootstrap`, `okd add-node`
- User-defined: `myapp deploy`, `myapp publish`, …

### Two kinds of subcommands

**Score-runner subcommands** — compose multiple Scores, need
`--filter`/`--list`/`--number`. Examples, ad-hoc orchestration, the
current `harmony_cli::run()` use case. The Maestro loop lives here.

**Action subcommands** — single-purpose (deploy a chart, publish an
image, create a tenant). No filter/list/number. Run one Score or a
fixed composition.

The distinction matters: forcing action subcommands through the
filter/list/number machinery is ceremony; forcing Score-runner
subcommands into a rigid single-action shape is constraining.

### Deploy crates become library-only

Per ADR-023 principle 5, deploy logic lives in `*-deploy` crates. The
unified CLI absorbs the **binaries** — deploy crates lose their
`[[bin]]` entries and become libraries consumed by the top-level
`harmony` binary. The crate boundary stays; the binary boundary goes
away.

```
harmony-fleet-deploy/
  Cargo.toml        # [lib] only, no [[bin]]
  src/
    lib.rs          # FleetDeployConfig, FleetDeploySecrets, FleetOperatorScore
    commands.rs     # DeployCommand, PublishCommand (clap Subcommand structs)
```

The top-level `harmony` binary imports `harmony_fleet_deploy::commands`
and wires them into its own `Command` enum.

### Publish logic as Scores

Build/push logic (currently imperative `Command::new("docker")` in
`harmony-fleet-publish`) should be encapsulated in Scores, following
the `Application` trait + feature composition pattern
(`examples/try_rust_webapp` + `PackagingDeployment`). The publish
subcommand becomes a thin CLI wrapper over a Score composition, not
a shell-out script.

This is not `PackagingDeployment` specifically — the operator isn't a
`RustWebapp`. The pattern is the **`Application` trait + feature
composition** model: a typed application description with composable
features (build, push, deploy, monitor).

### Plugin discovery (stage C, deferred)

ADR-023 principle 8 envisions `harmony` discovering `harmony-*`
binaries on `$PATH` (kubectl-style). This is the third-party
extensibility story: a `MyAppScore` author ships a `harmony-myapp`
binary, and `harmony myapp deploy` works without rebuilding the
framework.

**Open question**: is the end state a monolithic binary with
composable subcommands (first-party modules compiled in), or
kubectl-style plugin discovery for everything? Likely both:
first-party modules are compiled-in subcommands (tighter integration,
shared types), third-party modules are discovered plugins (loose
coupling, separate release cycles). The protocol for plugin
communication (env vars, stdin JSON, exit codes) is a separate design
effort.

### TUI integration

`harmony_tui` is a separate crate with its own `run()`. The unified
CLI's `--interactive` global flag delegates to `harmony_tui::run()`
for Score-runner subcommands. Action subcommands may or may not have
TUI equivalents — that's per-subcommand, not global.

### `harmony_composer`

Stays separate for now. It's an infrastructure composition tool with
a different audience (platform engineers building topologies, not
operators deploying apps). May become `harmony compose` later if the
use cases converge.

## Tasks

### 13.1 Rewrite `harmony_cli` — subcommand-aware runner

Replace the flat `Args` struct with a subcommand-aware `Cli` struct.
Global flags move to the top level. The `run()` function accepts a
`Command` enum instead of `Option<Args>`.

```rust
#[derive(Parser)]
struct Cli {
    #[arg(long, env = "HARMONY_CONFIG_NAMESPACE", global = true)]
    config_namespace: String,

    #[arg(long, global = true)]
    kubeconfig: Option<String>,

    #[arg(long, global = true)]
    yes: bool,

    #[command(subcommand)]
    command: Command,
}
```

**Files**: `harmony_cli/src/lib.rs`, `harmony_cli/src/args.rs` (new)
**Blocked by**: Phase 02 (config migration — so the new CLI is born
on `harmony_config`, not retrofitted)
**Blocks**: 13.2, 13.3

### 13.2 Migrate one deploy binary to subcommand pattern

Proof of concept: `harmony-fleet-deploy` already has `deploy`/`publish`
subcommands. Migrate it to the new `harmony_cli` runner: deploy crate
becomes library-only, exports `Command` enum, top-level binary wires
it in.

**Files**: `fleet/harmony-fleet-deploy/`, new top-level `harmony` binary
**Blocked by**: 13.1

### 13.3 Migrate examples

Each of the 60+ examples currently calls `harmony_cli::run()` with
flat args. Migration: each example becomes a subcommand of the
top-level `harmony` binary, or stays as a standalone binary that
imports the new `harmony_cli` runner.

**Migration shape** (before/after):

```rust
// Before (standalone binary)
fn main() {
    harmony_cli::run(Inventory::autoload(), topology, scores, None).await;
}

// After (subcommand of top-level binary)
// In the example's crate:
pub struct MyExampleCommand { /* clap args */ }
impl Subcommand for MyExampleCommand { ... }

// In the top-level binary:
enum Command {
    MyExample(MyExampleCommand),
    Fleet(FleetCommand),
    ...
}
```

**Files**: 60+ example crates
**Blocked by**: 13.2 (prove the pattern works on one)

### 13.4 Publish-as-Score

Extract build/push logic from `harmony-fleet-publish` into Scores
following the `Application` trait + feature composition pattern.
The `publish` subcommand becomes a thin wrapper.

**Files**: `harmony/src/modules/application/` (extend), `fleet/harmony-fleet-deploy/`
**Blocked by**: 13.2

### 13.5 Topology selection in the CLI

Global `--topology` flag or auto-detection. Requires Phase 12.6
(topology proliferation / `K8sBareTopology`) to land first — the
CLI's topology selection is simpler if the topology landscape is
clean.

**Blocked by**: Phase 12.6

### 13.6 Plugin discovery protocol (stage C)

Design the protocol for third-party `harmony-*` binaries to
communicate with the top-level `harmony` binary. Env vars for
global args? stdin JSON? Exit codes for outcomes?

**Status**: Research + ADR first. No implementation until the
protocol is locked.
**Blocked by**: 13.5 (first-party subcommands working end-to-end)

## Dependencies

```
Phase 02 (config migration)  ──→  13.1 (CLI rewrite)
Phase 12.6 (topology cleanup) ──→  13.5 (topology selection)
13.1  ──→  13.2 (fleet-deploy migration)
13.2  ──→  13.3 (example migration)
13.2  ──→  13.4 (publish-as-Score)
13.5  ──→  13.6 (plugin discovery)
```

Phase 11 (named config instances) can land after the CLI rewrite —
the global `--config-namespace` flag maps directly to
`ConfigClient::for_namespace()`, and named instances
(`get_named::<T>("fw-primary")`) become a CLI concern too.

## ADR-023 Tensions

These need resolution during implementation:

1. **Principle 5 vs. absorbing binaries.** Deploy crates keep their
   crate boundary (library + Scores) but lose their `[[bin]]`. The
   unified binary is the sole entry point. This is a refinement of
   principle 5, not a violation — the deploy logic still lives in
   the deploy crate.

2. **Principle 8 monolith vs. plugin.** First-party modules are
   compiled-in subcommands. Third-party modules are discovered
   plugins. The boundary between "first-party" and "third-party"
   needs a clear doctrine (likely: anything in the harmony repo is
   first-party; everything else is a plugin).

3. **`harmony_composer` placement.** Stays separate for now. If the
   use cases converge with the unified CLI, it becomes `harmony
   compose`. Not a blocker.

## References

- ADR-023 principle 8 — CLI: hybrid, staged (B → C)
- ADR-023 principle 5 — deploy logic in `*-deploy` crates
- ADR draft 024 §Q5 — runtime tools in the dependency graph
- `examples/try_rust_webapp` — `Application` trait + feature composition
- `harmony/src/modules/application/features/packaging_deployment.rs` —
  build/push as a Score feature
- Phase 02 — config migration (prerequisite)
- Phase 11 — named config instances (parallel)
- Phase 12.6 — topology proliferation (prerequisite for 13.5)