feat(hm-cloud): scaffold crate with the cloud CLI tree

New crate that will own the whole cloud domain (executor + verbs). This
first step lands the clap command tree only, no runtime:

- CloudCommand { Auth{login,logout,whoami}, Org, Pipeline, Build, Job,
  Billing } with every arg documented.
- Pipeline-identifying args are Option<String> so an omitted --pipeline
  falls back to config.default_pipeline.
- No submit verb: submission stays with hm run --cloud.

Author: markovejnovic

Cargo.lock

@@ -2,6 +2,7 @@
 resolver = "2"
 members = [
     "crates/hm",
+    "crates/hm-cloud",
     "crates/hm-common",
     "crates/hm-core",
     "crates/hm-plugin-protocol",
@@ -12,6 +13,7 @@ members = [
 ]
 default-members = [
     "crates/hm",
+    "crates/hm-cloud",
     "crates/hm-common",
     "crates/hm-core",
     "crates/hm-plugin-protocol",
@@ -28,6 +30,7 @@ repository = "https://github.com/harmont-dev/harmont-cli"
 
 [workspace.dependencies]
 hm-core            = { path = "crates/hm-core",           version = "0.0.0-dev" }
+hm-cloud           = { path = "crates/hm-cloud",          version = "0.0.0-dev" }
 hm-plugin-protocol = { path = "crates/hm-plugin-protocol", version = "0.0.0-dev" }
 hm-pipeline-ir     = { path = "crates/hm-pipeline-ir",     version = "0.0.0-dev" }
 hm-dsl-engine      = { path = "crates/hm-dsl-engine",     version = "0.0.0-dev" }

Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "hm-cloud"
+version = "0.0.0-dev"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Harmont cloud execution backend and `hm cloud` command surface."
+keywords = ["ci", "harmont", "cloud"]
+categories = ["command-line-utilities"]
+
+[lib]
+path = "src/lib.rs"
+
+[dependencies]
+clap = { version = "4", features = ["derive"] }
+
+[lints]
+workspace = true

crates/hm-cloud/Cargo.toml

@@ -0,0 +1,162 @@
+//! The `hm cloud` command tree.
+
+use clap::Subcommand;
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum CloudCommand {
+    /// Authenticate and inspect the active session.
+    #[command(subcommand)]
+    Auth(AuthCommand),
+    /// Manage organizations.
+    #[command(subcommand)]
+    Org(OrgCommand),
+    /// Manage pipelines.
+    #[command(subcommand)]
+    Pipeline(PipelineCommand),
+    /// Manage builds.
+    #[command(subcommand)]
+    Build(BuildCommand),
+    /// Manage jobs.
+    #[command(subcommand)]
+    Job(JobCommand),
+    /// Manage credits, top-ups, and usage.
+    #[command(subcommand)]
+    Billing(BillingCommand),
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum AuthCommand {
+    /// Authenticate this CLI against the Harmont API.
+    Login {
+        /// Skip the loopback flow and prompt for a paste-in code.
+        #[arg(long)]
+        paste: bool,
+    },
+    /// Remove stored credentials.
+    Logout,
+    /// Show the authenticated user.
+    Whoami,
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum OrgCommand {
+    /// Set the active organization.
+    Switch {
+        /// Organization slug.
+        slug: String,
+    },
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum PipelineCommand {
+    /// List pipelines for the active organization.
+    List,
+    /// Show pipeline details by slug. Defaults to the configured pipeline.
+    Show {
+        /// Pipeline slug; defaults to the configured pipeline.
+        slug: Option<String>,
+    },
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum BuildCommand {
+    /// List builds for a pipeline.
+    List {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+    },
+    /// Show a build by number.
+    Show {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+        /// Build number.
+        number: i64,
+    },
+    /// Cancel a build.
+    Cancel {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+        /// Build number.
+        number: i64,
+    },
+    /// Watch a build until it reaches a terminal state.
+    Watch {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+        /// Build number.
+        number: i64,
+    },
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum JobCommand {
+    /// List jobs in a build.
+    List {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+        /// Build number.
+        #[arg(short, long)]
+        build: i64,
+    },
+    /// Show a job by id.
+    Show {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+        /// Build number.
+        #[arg(short, long)]
+        build: i64,
+        /// Job id.
+        job_id: String,
+    },
+    /// Print the job log.
+    Log {
+        /// Pipeline slug; defaults to the configured pipeline.
+        #[arg(short, long)]
+        pipeline: Option<String>,
+        /// Build number.
+        #[arg(short, long)]
+        build: i64,
+        /// Job id.
+        job_id: String,
+    },
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum BillingCommand {
+    /// Print the current credit balance.
+    Balance,
+    /// List billing transactions.
+    Transactions {
+        /// Maximum number of transactions to return.
+        #[arg(long, default_value = "100")]
+        limit: u32,
+    },
+    /// Show usage over a time window.
+    Usage {
+        /// Start of the usage window.
+        #[arg(long)]
+        from: Option<String>,
+        /// End of the usage window.
+        #[arg(long)]
+        to: Option<String>,
+    },
+    /// Top up credits via Stripe checkout.
+    Topup {
+        /// Amount to add, in whole US dollars.
+        amount_usd: u32,
+        /// Print the checkout URL instead of opening a browser.
+        #[arg(long)]
+        no_browser: bool,
+    },
+    /// Redeem a coupon code.
+    Redeem {
+        /// Coupon code.
+        code: String,
+    },
+}

crates/hm-cloud/src/cli.rs

@@ -0,0 +1,3 @@
+//! Harmont cloud: the cloud execution backend and `hm cloud` command surface.
+
+pub mod cli;