|
|
|
|
@@ -0,0 +1,281 @@
|
|
|
|
|
# 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)
|