//! Top-level clap parser and subcommand enum.
//!
//! Adding a new subcommand is a mechanical three-edit change: a new
//! `src/commands/<name>.rs` module with an `Args` struct and `run()`
//! function, a `pub mod <name>;` line in `src/commands/mod.rs`, and a
//! new variant on `Command` below. The exhaustive match in `main.rs`
//! forces the compiler to refuse to build until the dispatcher is
//! wired up, which is the structural encoding of R11.

use clap::{Parser, Subcommand};

use crate::commands;

#[derive(Debug, Parser)]
#[command(
    name = "omne",
    version,
    about = "Manage omne volumes: init, upgrade, validate",
    long_about = "omne is a CLI for managing omne volumes. It fetches kernel \
and distro release tarballs from GitHub Releases, scaffolds a `.omne/` \
directory, and validates volume integrity. \
\n\nPhase 1 status: this build is a scaffold. The init, upgrade, and \
validate subcommands are stub handlers that exit 0 without doing real \
work; the operational behavior described below lands in subsequent units.\
\n\nAuthentication: set GITHUB_TOKEN or GH_TOKEN to raise the GitHub API \
rate limit from 60/hour to 5000/hour. When both are set, GITHUB_TOKEN wins.\
\n\nExit codes:\n  0  success\n  1  logical error (bad specifier, volume \
not found, validation failure)\n  2  argument parse error",
    subcommand_required = true,
    arg_required_else_help = false
)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, Subcommand)]
pub enum Command {
    /// Initialize a new omne volume in the current directory.
    Init(commands::init::Args),

    /// Upgrade the kernel or distro to the latest release.
    Upgrade(commands::upgrade::Args),

    /// Check volume integrity and run the distro gate runner.
    Validate(commands::validate::Args),

    /// Execute a pipe end-to-end: allocate a run_id, dispatch each DAG
    /// node, and stream events to `.omne/var/runs/<run_id>/events.jsonl`.
    Run(commands::run::Args),

    /// Show run state. Without a run_id, lists all runs. With a run_id,
    /// shows per-node DAG state with ✓ / ▶ / ✗ glyphs.
    Status(commands::status::Args),
}
