//! `hive-forge` — typed CLI wrapper around the in-cluster Forgejo's
//! REST API. Reads credentials from the environment:
//!
//!   `HIVE_FORGE_URL`      — base URL, e.g. `http://localhost:3000`
//!   `HYPERHIVE_STATE_DIR` — state dir; `forge-token` lives here
//!   `HIVE_FORGE_DEADLINE` — optional; whole seconds one invocation may run
//!                           before it exits with code 75 (default 900)
//!
//! The active repo resolves `-r/--repo` > the `origin` remote of the
//! cwd's git checkout > `HIVE_FORGE_REPO` (last-resort override, unset
//! by default) > a hard error — see `client::Client::from_env`.
//!
//! The global `-f/--forge <label>` flag targets a swarm-UI-linked
//! external forge account instead: it reads `forge-<label>-token` +
//! `forge-<label>.json` (base URL) from the state dir rather than
//! `HIVE_FORGE_URL`/`forge-token`. See `client::Client::from_env`.
//!
//! Single binary with verb subcommands. Replaces a prior bash
//! script so that agents and operators get
//! the same error handling, exit codes, and JSON shapes regardless
//! of how the bash mood was that day.

#![warn(missing_docs)]
// Clap-derived `Args` structs are intentionally consumed by their
// per-verb `run` handler so we can move owned String fields out
// without cloning. The pedantic lint flags every one of them.
#![allow(clippy::needless_pass_by_value)]

mod body;
mod client;
mod deadline;
mod notify;
mod verbs;

use anyhow::{Context, Result};
use clap::{Parser, Subcommand};
use std::process::ExitCode;

#[derive(Parser)]
#[command(
    name = "hive-forge",
    about = "Forgejo CLI wrapper for hyperhive",
    after_help = "Deadline: hive-forge stops after HIVE_FORGE_DEADLINE seconds (default 900), \
                  prints `hive-forge: FAILED: ...` and exits 75. A write may already have \
                  reached the forge, so check before retrying.",
    disable_help_subcommand = true
)]
struct Cli {
    /// Repo to act on, as `owner/name` (default: inferred from the
    /// cwd's git `origin` remote, then `HIVE_FORGE_REPO`). Works with
    /// any verb.
    #[arg(short = 'r', long, global = true)]
    repo: Option<String>,
    /// Act as an external forge account linked in the swarm UI (by its
    /// label) instead of the internal forge. Independent of `-r/--repo`.
    #[arg(short = 'f', long, global = true)]
    forge: Option<String>,
    /// Emit JSON instead of the default human-readable output (for verbs
    /// that support both).
    #[arg(long, global = true)]
    json: bool,
    #[command(subcommand)]
    verb: Verb,
}

#[derive(Subcommand)]
enum Verb {
    // The hidden verbs below are back-compat aliases of the `pr <verb>` /
    // `issue <verb>` forms. They're kind-agnostic (`view`, `comment`,
    // `comments`, `close`, `assign`, `labels`, `timeline`) and stay —
    // hidden, not deprecated. Each exists as both `issue <verb>` and
    // `pr <verb>`, so there is no single replacement to send a caller to
    // when all they hold is a number: refusing these would remove a
    // capability rather than rename one. Their pure-rename siblings
    // (`pr-status`, `pr-create`, `pr-merge`, `pr-reviews`, `pr-commits`,
    // `pr-assign-reviewer`, `issue-create`, `issue-edit`, `diff`) had an
    // exact scoped equivalent each and no ambiguity, so those were
    // removed outright rather than kept as forever-refusing aliases.
    //
    // `credential-helper` is hidden for a third reason and is in neither
    // group — git invokes it, no human does. A sweep that reads
    // `hide = true` as "deprecated" would take out checkout auth.
    /// Dump title + body + all comments for an issue or PR.
    #[command(hide = true)]
    View(verbs::view::Args),
    /// Issue-scoped commands: `issue <show|create|edit|view|comment|comments|close|reopen|labels|assign|dependency|reaction|timeline> …`.
    Issue(verbs::issue_cmd::Args),
    /// PR-scoped commands: `pr <show|status|create|merge|reviews|assign-reviewer|commits|diff|view|edit|comment|comments|close|reopen|labels|assign-committer|dependency|reaction|timeline> …`.
    Pr(verbs::pr_cmd::Args),
    /// Post a comment on an issue or PR.
    #[command(hide = true)]
    Comment(verbs::comment::Args),
    /// List all comments on an issue or PR.
    #[command(hide = true)]
    Comments(verbs::comments::Args),
    /// Print the body (or full JSON) of a single comment by id.
    CommentShow(verbs::comment_show::Args),
    /// Edit an existing comment by id.
    CommentEdit(verbs::comment_edit::Args),
    /// Assign or unassign a user on an issue or PR.
    #[command(hide = true)]
    Assign(verbs::assign::Args),
    /// Close an issue or PR.
    #[command(hide = true)]
    Close(verbs::close::Args),
    /// List, add, or remove labels on an issue or PR.
    #[command(hide = true)]
    Labels(verbs::labels::Args),
    /// Clone a forge repo (default `-r`/`HIVE_FORGE_REPO`) with
    /// credentials autoinjected. Pairs with `pr create --agit`.
    Clone(verbs::clone::Args),
    /// Create a forge repo under the current user (or `--org`). Prints
    /// the repo URL.
    RepoCreate(verbs::repo_create::Args),
    /// Add a collaborator to the active repo (`-r`/`HIVE_FORGE_REPO`)
    /// with a permission level. Companion to `repo-create`.
    RepoAddCollaborator(verbs::repo_add_collaborator::Args),
    /// List every label defined on the repo (name + description),
    /// optionally filtered by a name substring.
    RepoLabels(verbs::repo_labels::Args),
    /// Search the forge for repositories by keyword, topic, or description.
    RepoSearch(verbs::repo_search::Args),
    /// Triage lint queries (unassigned / no-reviewer / stale-branches / assignments / unlabeled).
    Lint(verbs::lint::Args),
    /// List issues / PRs with filters (`--kind`, `--state`, `--assignee`,
    /// `--author`, `--label`, `--limit`). Pretty rows by default; pass
    /// `--json` for raw JSON.
    // Discovery aliases: the verb is `list`, but `issues` / `issue-list`
    // are the names people reach for first (and clap's "did you mean"
    // tip points at `issue`, not here). Visible so they show in `--help`.
    #[command(visible_alias = "issues", visible_alias = "issue-list")]
    List(verbs::list::Args),
    /// Manage milestones (list / create / close).
    Milestone(verbs::milestone::Args),
    /// List branches, optionally filtered.
    Branches(verbs::branches::Args),
    /// Print the tree SHA at a branch or commit.
    TreeSha(verbs::tree_sha::Args),
    /// Get/set this user's watch subscription on a repo, or --list all watched repos.
    Subscription(verbs::subscription::Args),
    /// List timeline events on an issue or PR (closes, label adds,
    /// assignments, commit refs, pushes, etc.) — the audit trail
    /// `view` + `comments` don't surface.
    #[command(hide = true)]
    Timeline(verbs::timeline::Args),
    /// Upload a file as an attachment to an issue.
    AttachIssue(verbs::attach::IssueArgs),
    /// Upload a file as an attachment to a comment.
    AttachComment(verbs::attach::CommentArgs),
    /// Download an attachment by UUID or URL. Saves to a temp file and
    /// prints the path (pass `-o -` to stream raw bytes to stdout).
    AttachmentGet(verbs::attachment_get::Args),
    /// Download a CI Actions artifact from a run (`<name> --run <n>`).
    /// Saves a zip, or pass `-o -` to stream to stdout.
    ArtifactGet(verbs::artifact_get::Args),
    /// Print a CI Actions run's job step logs
    /// (`--run <n> [--job i] [--step i]`).
    CiLog(verbs::ci_log::Args),
    /// Re-run CI without an empty commit. Pass one of `--pr <n>`,
    /// `--run <n>`, or `--branch <name>`; `--workflow` defaults to `ci.yml`.
    CiRerun(verbs::ci_rerun::Args),
    /// List CI Actions runs, newest first (`--workflow`, `--branch`,
    /// `--limit`, `--page`) — the run numbers `ci-log`/`ci-rerun --run`/
    /// `artifact-get --run` take.
    CiRuns(verbs::ci_runs::Args),
    /// Git credential-helper protocol (`get|store|erase`) — not a verb
    /// you run by hand. `clone` configures each checkout's
    /// `credential.helper` to invoke this, so git asks it for a token
    /// fresh on every fetch/push instead of one being embedded in the
    /// remote URL.
    #[command(hide = true)]
    CredentialHelper(verbs::credential_helper::Args),
    /// Emit the full CLI reference as Markdown, walking hive-forge's own
    /// clap command tree.
    ///
    /// Hidden tooling command used by the docs build to keep the published
    /// `hive-forge` reference in lockstep with the code.
    #[command(hide = true)]
    MarkdownDocs,
}

/// Wrapper over [`run`] that owns how a failure reaches the operator.
///
/// `fn main() -> Result<()>` would format the error with anyhow's `Debug`
/// impl, which prints a bare `Error:` header. `hive-forge` is almost always
/// invoked from an agent's bash task, where stdout is what gets surfaced
/// first and stderr is easy to miss — so failures are prefixed with the
/// binary name to be unmistakably ours, and rendered with `{:#}`
/// (alternate `Display`), which keeps the full `context` chain inline
/// rather than dropping it the way plain `Display` would.
fn main() -> ExitCode {
    restore_sigpipe();
    if let Err(e) = run() {
        eprintln!("hive-forge: FAILED: {e:#}");
        return ExitCode::FAILURE;
    }
    ExitCode::SUCCESS
}

/// Give `SIGPIPE` back its default disposition before any output happens.
///
/// Rust's runtime sets `SIGPIPE` to `SIG_IGN` at startup, so writing to a
/// pipe whose reader has gone away returns `EPIPE` and `println!` panics.
/// `hive-forge <verb> | head` therefore dies with a panic message and exit
/// **101** where every other CLI in a pipeline exits quietly — and 101 is
/// a real failure to a caller running `set -o pipefail`, so a shell script
/// that pipes our output stops on a condition that is not an error.
///
/// Restoring `SIG_DFL` makes the process die by signal instead, which is
/// what the surrounding shell already knows how to interpret.
fn restore_sigpipe() {
    // SAFETY: called first thing in `main`, before any thread exists and
    // before any output — so no concurrent handler mutation is possible,
    // and no write can race the change.
    unsafe {
        libc::signal(libc::SIGPIPE, libc::SIG_DFL);
    }
}

fn run() -> Result<()> {
    let cli = Cli::parse();
    let verb = cli.verb;
    // `credential-helper` bypasses the normal client construction below:
    // it needs no repo (unlike `Client::from_env`, which errors without
    // one), and git may invoke it from a directory that isn't a resolved
    // checkout yet (mid-`clone`, before the destination exists).
    if let Verb::CredentialHelper(args) = verb {
        return verbs::credential_helper::run(args, cli.forge.as_deref());
    }
    // Same reasoning as `credential-helper` above: no repo, no forge
    // credentials — just a pure render of the clap tree the docs build
    // pipes into `docs/tools/forge-cli.md`.
    if let Verb::MarkdownDocs = verb {
        // `show_footer(false)`: the default footer's wording ("This
        // document was generated automatically by...") is clap-markdown's
        // own fixed text, not ours to reword into active voice, and the
        // repo's docs are prose we write ourselves throughout — so we
        // drop the footer rather than carry the one string in this tree
        // we have no control over.
        let options = clap_markdown::MarkdownOptions::new().show_footer(false);
        print!("{}", clap_markdown::help_markdown_custom::<Cli>(&options));
        return Ok(());
    }
    deadline::start()?;
    let client = client::Client::from_env(cli.repo, cli.json, cli.forge)
        .context("initialize forge client")?;
    // Attach the resolved repo to every verb's error uniformly here,
    // rather than threading `.with_context` through 30-odd verb files
    // individually. Most verb failures bottom out in `forgejo-api`'s
    // `ForgejoError`, which for a body-decode failure (an empty/wrong
    // body on a write) carries no status code or URL — see
    // `client::check_status`'s doc comment for the raw-route case this
    // can't reach. Without the repo in the message, a failure on a
    // mistyped `owner/name` (nonexistent org/repo) is indistinguishable
    // from a transient flake; this turns "EOF while parsing a value at
    // line 1 column 0" into "repo typo-org/repo: EOF while parsing a
    // value at line 1 column 0", which is diagnosable on sight.
    //
    // `client.repo()` is fallible now (a repo-independent verb like
    // `repo-search` may have none at all) — this wrapper must not
    // become the thing that revives the eager-bail bug one frame down,
    // so an unresolved repo just means no context is attached, not a
    // failure. A verb that actually needs a repo still fails, from
    // wherever it calls `client.repo()`/`client.owner_repo()` itself.
    match client.repo().ok().map(str::to_owned) {
        Some(repo) => dispatch(&client, verb).with_context(|| format!("repo {repo}")),
        None => dispatch(&client, verb),
    }
}

fn dispatch(client: &client::Client, verb: Verb) -> Result<()> {
    match verb {
        Verb::View(a) => verbs::view::run(client, a),
        Verb::Issue(a) => verbs::issue_cmd::run(client, a),
        Verb::Pr(a) => verbs::pr_cmd::run(client, a),
        Verb::Comment(a) => verbs::comment::run(client, a),
        Verb::Comments(a) => verbs::comments::run(client, a),
        Verb::CommentShow(a) => verbs::comment_show::run(client, a),
        Verb::CommentEdit(a) => verbs::comment_edit::run(client, a),
        Verb::Assign(a) => verbs::assign::run(client, a),
        Verb::Close(a) => verbs::close::run(client, a),
        Verb::Labels(a) => verbs::labels::run(client, a),
        Verb::Clone(a) => verbs::clone::run(client, a),
        Verb::RepoCreate(a) => verbs::repo_create::run(client, a),
        Verb::RepoAddCollaborator(a) => verbs::repo_add_collaborator::run(client, a),
        Verb::RepoLabels(a) => verbs::repo_labels::run(client, a),
        Verb::RepoSearch(a) => verbs::repo_search::run(client, a),
        Verb::Lint(a) => verbs::lint::run(client, a),
        Verb::List(a) => verbs::list::run(client, a),
        Verb::Milestone(a) => verbs::milestone::run(client, a),
        Verb::Branches(a) => verbs::branches::run(client, a),
        Verb::TreeSha(a) => verbs::tree_sha::run(client, a),
        Verb::Subscription(a) => verbs::subscription::run(client, a),
        Verb::Timeline(a) => verbs::timeline::run(client, a),
        Verb::AttachIssue(a) => verbs::attach::run_issue(client, a),
        Verb::AttachComment(a) => verbs::attach::run_comment(client, a),
        Verb::AttachmentGet(a) => verbs::attachment_get::run(client, a),
        Verb::ArtifactGet(a) => verbs::artifact_get::run(client, a),
        Verb::CiLog(a) => verbs::ci_log::run(client, a),
        Verb::CiRerun(a) => verbs::ci_rerun::run(client, a),
        Verb::CiRuns(a) => verbs::ci_runs::run(client, a),
        Verb::CredentialHelper(_) | Verb::MarkdownDocs => {
            unreachable!("handled in `run` before client construction")
        }
    }
}