mergify-cli AGENTS.md

Agent Instructions

mergify is a native Rust CLI — a Cargo workspace under crates/, with the binary built from crates/mergify-cli ([[bin]] name = "mergify"). There is no Python: the port is complete and every command runs in-process. If you find a doc, comment, or rule mentioning console_error, click, DYMGroup, mergify_cli.dym, crates/mergify-py-shim, or a "Python shim", it is stale — fix it.

The bar is ruff/uv-grade Rust: typed errors, no panics in library code, clippy pedantic clean, snapshot-tested output. Concrete rules follow.

Workspace layout

• mergify-core — shared foundations: CliError/ExitCode, the HTTP Client, auth, Output, env.
• mergify-tui — terminal primitives: Theme (color), glyphs, relative time. Stays dependency-light and clap-free.
• mergify-cli — the binary: clap tree, dispatch, run_native, self_update, cli_schema.
• mergify-stack / mergify-ci / mergify-queue / mergify-events / mergify-freeze / mergify-config — one crate per command group. mergify-events also hosts the shared /logs client the queue crate's dequeue diagnosis consumes.
• mergify-test-support — shared test scaffolding (not published).

Error handling

Library and command code never prints errors and never calls process::exit. Return Result<_, mergify_core::CliError>. main() is the single error sink: it writes mergify: {err} to stderr, walks the source() chain printing each cause as a caused by: line, and exits with err.exit_code().

CliError is a typed enum; each variant maps to a stable ExitCode (GitHubApi→5, MergifyApi→6, Configuration→7, … see exit_code.rs). Pick the variant whose exit code matches the failure class. Never add a String catch-all for a new failure category that deserves its own code — add a variant.

// GOOD — typed variant, lowercase message, no prefix (the sink adds "mergify:")
return Err(CliError::StackNotFound(format!("branch {name} not found")));

// BAD — printing + exiting inside a command
eprintln!("error: branch not found");
std::process::exit(1);

// BAD — capitalized / pre-prefixed (the sink double-prefixes it)
return Err(CliError::Generic("Error: branch not found".into()));