heddle_cli_args/cli/cli_args/

cli_base.rs

// SPDX-License-Identifier: Apache-2.0
//! Base CLI flags.
//!
//! ## Short-flag conventions
//!
//! The CLI is small and the short forms have to mean the same thing
//! everywhere they appear. The table below is the source of truth — new
//! verbs should reuse these letters before claiming new ones. Verbs that
//! diverge (e.g. `-n` for `--steps` on `undo`/`redo` vs `--limit` on
//! `log`/`list`) keep the muscle memory consistent within the verb's own
//! family: "n" is always "how many," "m" is always "message."
//!
//! | Short | Long(s)                           | Used by                       |
//! |-------|-----------------------------------|-------------------------------|
//! | `-m`  | `--message`, `--body`, `--intent` | capture, revert, context,     |
//! |       |                                   | discuss                       |
//! | `-n`  | `--limit` (queries),              | log, list, query (limit);     |
//! |       | `--steps` (undo/redo)             | undo, redo (steps)            |
//! | `-f`  | `--force`                         | capture, push, revert, purge  |
//! | `-s`  | `--short`                         | status                        |
//! | `-U`  | `--unified`                       | diff                          |
//! | `-C`  | `--repo`                          | global                        |
//! | `-v`  | `--verbose` (repeatable)          | global                        |
//! | `-q`  | `--quiet`                         | global                        |
//!
//! Heddle is pre-1.0 and contracts misleading surface area instead of
//! preserving obsolete spellings. Add a short alias only when the letter is
//! already reserved for that semantic in the current table above.

use std::{path::Path, sync::OnceLock};

use clap::Parser;
use repo::{Config, OutputFormat};

use super::{CliOutputMode, Commands};

/// Heddle: An AI-native version control system.
#[derive(Parser)]
#[command(name = "heddle")]
#[command(author, version, about, long_about = None)]
// We ship our own `Help` subcommand (curated everyday/advanced
// surface + topic pages). clap's auto-generated `help` subcommand
// would shadow it; turn it off so `heddle help [topic]` reaches our
// printer instead.
#[command(disable_help_subcommand = true)]
pub struct Cli {
    #[command(subcommand)]
    pub command: Commands,

    // This is a `global = true` arg, so clap stamps its help onto every
    // subcommand's --help. Keep it to ONE line; the full contract
    // (json vs json-compact fields, no-TTY-autodetect guarantee) lives in
    // `heddle help output-formats` (help.rs OUTPUT_FORMATS_TOPIC) and the
    // top-level `heddle help` Output paragraph, stated exactly once each
    // (heddle#652).
    /// Output format: `text` (default), `json`, or `json-compact`. See `heddle help output-formats`
    #[arg(long, global = true, value_enum)]
    pub output: Option<CliOutputMode>,

    /// Disable colored output.
    #[arg(long, global = true)]
    pub no_color: bool,

    // Global short-circuit like `--help`: print the JSON Schema for the
    // resolved command's `--output json` payload and exit without running
    // the command. Resolves to the deepest selected verb (including
    // flag-differentiated payloads like `land --threads`). Kept to one
    // line on every subcommand's help (heddle#652).
    /// Print the JSON Schema for this command's `--output json` payload and exit.
    #[arg(long, global = true)]
    pub schema: bool,

    /// Repository path (default: find .heddle in ancestors).
    #[arg(short = 'C', long, global = true, value_name = "PATH")]
    pub repo: Option<std::path::PathBuf>,

    /// Increase verbosity.
    #[arg(short, long, global = true, action = clap::ArgAction::Count)]
    pub verbose: u8,

    /// Decrease verbosity.
    #[arg(short, long, global = true)]
    pub quiet: bool,

    // Global like --output, and revealed on every `supports_op_id`
    // command's help — keep it to one line (heddle#652). Replay semantics
    // (`supports_op_id` advertisement, same-body replay, typed conflicts)
    // live in `heddle help operation-ids`. Hidden from default `--help` to
    // keep the human surface uncluttered.
    /// Operation id (UUID v4) for idempotent retries. See `heddle help operation-ids`
    #[arg(long, global = true, env = "HEDDLE_OPERATION_ID", hide = true)]
    pub op_id: Option<String>,
}

impl Cli {
    /// Load and cache the process-wide user configuration.
    pub fn user_config_or_exit() -> &'static config::UserConfig {
        static USER_CONFIG: OnceLock<config::UserConfig> = OnceLock::new();
        USER_CONFIG.get_or_init(|| config::UserConfig::load_default().unwrap_or_default())
    }

    pub fn output_mode(&self) -> Option<config::OutputMode> {
        self.output.map(Into::into)
    }

    /// Open the Heddle repository the command should act on: the `--repo`
    /// path if given, otherwise the current working directory (resolved
    /// lazily so a supplied `--repo` never touches the cwd).
    pub fn open_repo(&self) -> anyhow::Result<repo::Repository> {
        use anyhow::Context as _;
        let cwd;
        let repo_path = match self.repo.as_ref() {
            Some(path) => path,
            None => {
                cwd = std::env::current_dir().context("get current working directory")?;
                &cwd
            }
        };
        let repo = repo::Repository::open(repo_path).context("open Heddle repository")?;
        let mode = Self::user_config_or_exit()
            .worktree_status_options(Some(repo.config()))
            .fsmonitor
            .mode;
        Ok(repo.with_fsmonitor_mode(mode))
    }
}

/// Small projection of [`Cli`] that hosted commands rely on.
/// Defining the surface here lets the hosted-client implementation compile
/// against the parsed CLI state without depending on `cli`.
///
/// Keep this trait deliberately small. Every new method is a permanent
/// contract with the hosted side; before adding one, ask whether the hosted
/// command should really need that context at all, or whether the caller can
/// compute it and pass a primitive value.
pub trait CliContext: Send + Sync {
    /// `--repo` override; `None` means "use the process's current
    /// directory."
    fn repo_path(&self) -> Option<&Path>;

    /// `--op-id` override for idempotent hosted calls. Empty string
    /// means the caller did not supply one and the server should not
    /// dedupe.
    fn operation_id_wire(&self) -> String;

    /// Resolves whether output should be JSON, encapsulating the
    /// precedence between the `--json` / `--output` cli flags, the
    /// user's global config, and (when supplied) the repo's
    /// `output.format` config. Hosted commands typically pass
    /// `Some(repo.config())` after opening the repo and `None`
    /// otherwise.
    fn should_output_json(&self, repo_config: Option<&Config>) -> bool;
}

impl CliContext for Cli {
    fn repo_path(&self) -> Option<&std::path::Path> {
        self.repo.as_deref()
    }

    fn operation_id_wire(&self) -> String {
        self.op_id.clone().unwrap_or_default()
    }

    fn should_output_json(&self, repo_config: Option<&Config>) -> bool {
        should_output_json(self, repo_config)
    }
}

/// Resolve whether command output should use JSON after applying user,
/// repository, and explicit CLI output settings.
pub fn should_output_json(cli: &Cli, repo_config: Option<&Config>) -> bool {
    let mut format = repo_config
        .and_then(|config| config.output.format)
        .unwrap_or(Cli::user_config_or_exit().output.format);

    if let Some(output) = cli.output_mode() {
        format = match output {
            config::OutputMode::Json | config::OutputMode::JsonCompact => OutputFormat::Json,
            config::OutputMode::Text => OutputFormat::Text,
        };
    }

    matches!(format, OutputFormat::Json)
}