processkit/

client.rs

//! [`CliClient`] — a small, reusable core for building typed wrappers around an
//! external CLI tool (`git`, `jj`, `gh`, …).
//!
//! It owns the program name, a [`ProcessRunner`], and an optional default
//! timeout; hands back preconfigured [`Command`]s; and provides the terminal
//! run/parse helpers a wrapper otherwise repeats. A wrapper then reduces to a
//! typed facade over its parsers, with no process plumbing — and is mockable by
//! construction, since the runner is injectable (pass a
//! [`ScriptedRunner`](crate::testing::ScriptedRunner) in tests).
//!
//! The [`cli_client!`](crate::cli_client) macro scaffolds the wrapper struct and
//! its constructors.

use std::ffi::{OsStr, OsString};
use std::path::Path;
use std::time::Duration;

use crate::command::Command;
use crate::error::Result;
use crate::result::ProcessResult;
use crate::runner::{JobRunner, ProcessRunner, ProcessRunnerExt};

mod sealed {
    use std::ffi::OsStr;
    pub trait Sealed {}
    impl Sealed for crate::Command {}
    impl<S: AsRef<OsStr>, const N: usize> Sealed for [S; N] {}
    impl<S: AsRef<OsStr>> Sealed for Vec<S> {}
    impl<S: AsRef<OsStr>> Sealed for &[S] {}
}

/// What a [`CliClient`] verb accepts: either an **argument list** — built
/// into a [`Command`] for the client's program with its defaults (timeout, env,
/// cancellation) applied — or a ready-made `Command`, run as-is.
///
/// This lets one verb serve both the common `git.run(["status"])` and the
/// customized `git.run(git.command(["push"]).timeout(d))`, removing the
/// double-mention of the older `git.run(git.command([…]))` form. Implemented for
/// argument containers (`[S; N]`, `Vec<S>`, `&[S]` where `S: AsRef<OsStr>`) and
/// for [`Command`]; **sealed** (not implementable downstream).
///
/// Either form receives the client's defaults (timeout / env /
/// [`default_cancel_on`](CliClient::default_cancel_on)): an argument list builds a
/// fresh command with them, and a ready-made [`Command`] has them **filled into
/// the gaps it left** — its own explicit settings win, but a client-wide cancel
/// token / timeout / env still reaches a per-call-customized command rather than
/// being silently dropped.
pub trait IntoCommand<R: ProcessRunner>: sealed::Sealed {
    /// Build the [`Command`] to run for `client` — used by the verbs.
    #[doc(hidden)]
    fn into_command(self, client: &CliClient<R>) -> Command;
}

impl<R: ProcessRunner> IntoCommand<R> for Command {
    fn into_command(self, client: &CliClient<R>) -> Command {
        // Fill defaults into the caller-supplied command's gaps; its explicit
        // settings win. Idempotent if `command()` already applied them.
        client.apply_defaults(self)
    }
}

impl<R: ProcessRunner, S: AsRef<OsStr>, const N: usize> IntoCommand<R> for [S; N] {
    fn into_command(self, client: &CliClient<R>) -> Command {
        client.command(self)
    }
}

impl<R: ProcessRunner, S: AsRef<OsStr>> IntoCommand<R> for Vec<S> {
    fn into_command(self, client: &CliClient<R>) -> Command {
        client.command(self)
    }
}

impl<R: ProcessRunner, S: AsRef<OsStr>> IntoCommand<R> for &[S] {
    fn into_command(self, client: &CliClient<R>) -> Command {
        client.command(self)
    }
}

/// Owns a CLI tool's program name, [`ProcessRunner`], and default timeout, and
/// builds + runs [`Command`]s against them.
///
/// Generic over the runner so tests inject a fake; [`new`](Self::new) uses the
/// real job-backed [`JobRunner`].
pub struct CliClient<R: ProcessRunner = JobRunner> {
    program: OsString,
    runner: R,
    timeout: Option<Duration>,
    /// Environment overrides applied to every built command (`None` = remove),
    /// in registration order — e.g. `GIT_TERMINAL_PROMPT=0` set once instead of
    /// on every probe.
    envs: Vec<(OsString, Option<OsString>)>,
    /// A cancellation token applied to every built command (see
    /// [`default_cancel_on`](Self::default_cancel_on)).
    cancel: Option<tokio_util::sync::CancellationToken>,
}

// Manual Debug: no `Debug` bound on R; env values omitted per secret-safety rule.
impl<R: ProcessRunner> std::fmt::Debug for CliClient<R> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut d = f.debug_struct("CliClient");
        d.field("program", &self.program)
            .field("timeout", &self.timeout)
            .field("env_names", &crate::command::redacted_env_names(&self.envs));
        d.field("has_default_cancel", &self.cancel.is_some());
        d.finish_non_exhaustive()
    }
}

impl CliClient<JobRunner> {
    /// A client driving `program` through the real job-backed runner.
    pub fn new(program: impl AsRef<OsStr>) -> Self {
        Self {
            program: program.as_ref().to_os_string(),
            runner: JobRunner,
            timeout: None,
            envs: Vec::new(),
            cancel: None,
        }
    }
}

impl<R: ProcessRunner> CliClient<R> {
    /// A client driving `program` through `runner` — pass a fake in tests.
    pub fn with_runner(program: impl AsRef<OsStr>, runner: R) -> Self {
        Self {
            program: program.as_ref().to_os_string(),
            runner,
            timeout: None,
            envs: Vec::new(),
            cancel: None,
        }
    }

    /// Apply a default timeout to every command this client builds.
    #[must_use]
    pub fn default_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }

    /// Set an environment variable on every command this client builds — e.g.
    /// `GIT_TERMINAL_PROMPT=0` so a probe can never block on a credential
    /// prompt. Per-command [`Command::env`] still works and is layered after.
    #[must_use]
    pub fn default_env(mut self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>) -> Self {
        self.envs.push((
            key.as_ref().to_os_string(),
            Some(value.as_ref().to_os_string()),
        ));
        self
    }

    /// Remove an inherited environment variable on every command this client
    /// builds.
    #[must_use]
    pub fn default_env_remove(mut self, key: impl AsRef<OsStr>) -> Self {
        self.envs.push((key.as_ref().to_os_string(), None));
        self
    }

    /// Cancel every command this client builds when `token` fires: each built
    /// command gets [`cancel_on(token.clone())`](Command::cancel_on), so
    /// cancelling the token kills every in-flight run of **this client** (the
    /// whole tree, surfacing [`Error::Cancelled`](crate::Error::Cancelled) on
    /// the awaiting call — same semantics as the per-command builder).
    ///
    /// **Precedence:** a per-command [`Command::cancel_on`] chained on a built
    /// command *replaces* the default (an explicit setting beats a default,
    /// like a per-command [`timeout`](Command::timeout) after
    /// [`default_timeout`](Self::default_timeout)). When both sources should
    /// fire, wire it explicitly — derive a child of the default
    /// (`let c = default.child_token()`), hand the command `cancel_on(c.clone())`,
    /// and have the second source call `c.cancel()` — or simply build a
    /// dedicated client per scope.
    ///
    /// Scope cancellation by client, not by call: clients are cheap — build
    /// one per cancellable scope and hand each its own token.
    #[must_use]
    pub fn default_cancel_on(mut self, token: tokio_util::sync::CancellationToken) -> Self {
        self.cancel = Some(token);
        self
    }

    /// The injected runner — for direct [`ProcessRunner`]/[`ProcessRunnerExt`] use.
    pub fn runner(&self) -> &R {
        &self.runner
    }

    /// The default timeout, if one was set.
    pub fn timeout(&self) -> Option<Duration> {
        self.timeout
    }

    /// A [`Command`] for `program <args>` in the current directory, defaults
    /// (timeout, env) pre-applied. Chain more builders (`.arg`, `.stdin`, …) for
    /// dynamic-argument commands.
    pub fn command<I, S>(&self, args: I) -> Command
    where
        I: IntoIterator<Item = S>,
        S: AsRef<OsStr>,
    {
        self.apply_defaults(Command::new(&self.program).args(args))
    }

    /// A [`Command`] for `program <args>` run in `dir`, defaults (timeout, env)
    /// pre-applied.
    pub fn command_in<I, S>(&self, dir: &Path, args: I) -> Command
    where
        I: IntoIterator<Item = S>,
        S: AsRef<OsStr>,
    {
        self.apply_defaults(Command::new(&self.program).current_dir(dir).args(args))
    }

    /// Fill the client's defaults into `command`, but only where the command has
    /// not set them itself — so a fresh [`command()`](Self::command) (no settings)
    /// gets every default, while a caller-supplied [`Command`] passed straight to
    /// a verb keeps its own explicit timeout/cancel/env and only fills the gaps
    /// (so a client-wide cancel token / timeout / env is not silently dropped
    /// when you customize a single call). Idempotent — running it twice (a verb
    /// applies it to a command that `command()` already defaulted) is a no-op
    /// the second time.
    fn apply_defaults(&self, mut command: Command) -> Command {
        if command.configured_timeout().is_none()
            && let Some(timeout) = self.timeout
        {
            command = command.timeout(timeout);
        }
        if command.cancel_token().is_none()
            && let Some(token) = &self.cancel
        {
            command = command.cancel_on(token.clone());
        }
        command.fill_default_envs(&self.envs);
        command
    }

    /// Run, returning stdout (trailing whitespace trimmed) on success (errors on
    /// a non-zero exit) — the same verb, with the same semantics, as
    /// [`Command::run`](crate::Command::run) and
    /// [`ProcessRunnerExt::run`](crate::ProcessRunnerExt::run). Trims with
    /// `trim_end`: the trailing newline is noise, but leading whitespace can be
    /// significant.
    ///
    /// Accepts an argument list (`git.run(["status"])`) or a customized
    /// [`Command`] (`git.run(git.command(["push"]).timeout(d))`) — see
    /// [`IntoCommand`].
    pub async fn run(&self, call: impl IntoCommand<R>) -> Result<String> {
        let command = call.into_command(self);
        let result = self.runner.checked(&command).await?;
        let policy = command.output_buffer_policy();
        result.reject_if_truncated(policy.max_lines, policy.max_bytes)?;
        Ok(result.into_stdout().trim_end().to_owned())
    }

    /// Run, requiring an accepted exit, and return the full
    /// [`ProcessResult`] (untrimmed) — the [`CliClient`] analogue of
    /// [`ProcessRunnerExt::checked`](crate::ProcessRunnerExt::checked); the
    /// building block when you need the whole result after success-checking.
    pub async fn checked(&self, call: impl IntoCommand<R>) -> Result<ProcessResult<String>> {
        self.runner.checked(&call.into_command(self)).await
    }

    /// Run, capturing the full result without erroring on a non-zero exit — the
    /// same verb as [`ProcessRunner::output_string`].
    pub async fn output_string(&self, call: impl IntoCommand<R>) -> Result<ProcessResult<String>> {
        self.runner.output_string(&call.into_command(self)).await
    }

    /// Run, capturing stdout as **raw bytes** (stderr as text), without erroring
    /// on a non-zero exit — the same verb as [`ProcessRunner::output_bytes`].
    /// For binary tools whose stdout is not UTF-8.
    pub async fn output_bytes(&self, call: impl IntoCommand<R>) -> Result<ProcessResult<Vec<u8>>> {
        self.runner.output_bytes(&call.into_command(self)).await
    }

    /// Run for the side effect, discarding stdout (errors on a non-zero exit) —
    /// the same verb as
    /// [`ProcessRunnerExt::run_unit`](crate::ProcessRunnerExt::run_unit).
    pub async fn run_unit(&self, call: impl IntoCommand<R>) -> Result<()> {
        self.runner.run_unit(&call.into_command(self)).await
    }

    /// Run and return the exit code (e.g. `git diff --quiet`, `gh auth status`)
    /// — never errors on a non-zero exit. The same verb as
    /// [`Command::exit_code`](crate::Command::exit_code).
    pub async fn exit_code(&self, call: impl IntoCommand<R>) -> Result<i32> {
        self.runner.exit_code(&call.into_command(self)).await
    }

    /// Run a predicate and read its exit code as a boolean: exit `0` →
    /// `Ok(true)`, exit `1` → `Ok(false)`, anything else → `Err`. Collapses the
    /// `match code { 0 => …, 1 => …, _ => Err }` idiom for commands whose exit
    /// code is the answer (`git diff --quiet`, `git show-ref --verify --quiet`,
    /// `grep -q`, …); other codes / timeout / signal-kill all error.
    pub async fn probe(&self, call: impl IntoCommand<R>) -> Result<bool> {
        self.runner.probe(&call.into_command(self)).await
    }

    /// Stream stdout and return the first line matching `predicate` (`None` if
    /// the stream ends first) — the [`CliClient`] analogue of
    /// [`ProcessRunnerExt::first_line`](crate::ProcessRunnerExt::first_line),
    /// bounded by the command's [`timeout`](crate::Command::timeout).
    pub async fn first_line<F>(
        &self,
        call: impl IntoCommand<R>,
        predicate: F,
    ) -> Result<Option<String>>
    where
        F: Fn(&str) -> bool + Send,
    {
        self.runner
            .first_line(&call.into_command(self), predicate)
            .await
    }

    /// Run (errors on a non-zero exit) and feed stdout to an infallible
    /// `parse` — the shape of git/jj struct-returning commands. Fails loud on a
    /// bounded-buffer truncation. Delegates to
    /// [`ProcessRunnerExt::parse`](crate::ProcessRunnerExt::parse).
    pub async fn parse<T, F>(&self, call: impl IntoCommand<R>, parse: F) -> Result<T>
    where
        T: Send,
        F: FnOnce(&str) -> T + Send,
    {
        self.runner.parse(&call.into_command(self), parse).await
    }

    /// Run (errors on a non-zero exit) and feed stdout to a *fallible* `parse` —
    /// the shape of JSON deserialization, where a parse failure becomes
    /// [`Error::Parse`](crate::Error::Parse). Fails loud on a bounded-buffer
    /// truncation. Delegates to
    /// [`ProcessRunnerExt::try_parse`](crate::ProcessRunnerExt::try_parse).
    pub async fn try_parse<T, F>(&self, call: impl IntoCommand<R>, parse: F) -> Result<T>
    where
        T: Send,
        F: FnOnce(&str) -> Result<T> + Send,
    {
        self.runner.try_parse(&call.into_command(self), parse).await
    }
}

/// Scaffold a typed CLI-wrapper struct around a [`CliClient`].
///
/// Expands `cli_client!(pub struct Git => "git");` into a
/// `struct Git<R: ProcessRunner = JobRunner> { core: CliClient<R> }` with
/// `new()` (real runner), a `Default` impl, `with_runner(runner)`, and
/// `default_timeout(d)`. Implement the tool's typed methods on it, delegating to
/// `self.core` — see the crate docs for an example.
///
/// This macro is **committed public API**. Because it is `#[macro_export]`,
/// it lives at the crate root and is a stable part of the surface — the
/// supported scaffold for typed CLI wrappers. The hand-rolled equivalent (a
/// struct wrapping [`CliClient`]) remains valid and interchangeable.
#[macro_export]
macro_rules! cli_client {
    ($(#[$meta:meta])* $vis:vis struct $name:ident => $binary:expr) => {
        $(#[$meta])*
        $vis struct $name<R: $crate::ProcessRunner = $crate::JobRunner> {
            core: $crate::CliClient<R>,
        }

        impl $name<$crate::JobRunner> {
            /// Create a client driving the real job-backed runner.
            pub fn new() -> Self {
                Self { core: $crate::CliClient::new($binary) }
            }
        }

        impl ::core::default::Default for $name<$crate::JobRunner> {
            fn default() -> Self {
                Self::new()
            }
        }

        impl<R: $crate::ProcessRunner> $name<R> {
            /// Create a client driving `runner` — inject a fake in tests.
            pub fn with_runner(runner: R) -> Self {
                Self { core: $crate::CliClient::with_runner($binary, runner) }
            }

            /// Apply a default timeout to every command this client builds.
            pub fn default_timeout(mut self, timeout: ::core::time::Duration) -> Self {
                self.core = self.core.default_timeout(timeout);
                self
            }

            /// Set an environment variable on every command this client builds
            /// (e.g. `GIT_TERMINAL_PROMPT=0`).
            pub fn default_env(
                mut self,
                key: impl ::core::convert::AsRef<::std::ffi::OsStr>,
                value: impl ::core::convert::AsRef<::std::ffi::OsStr>,
            ) -> Self {
                self.core = self.core.default_env(key, value);
                self
            }

            /// Remove an inherited environment variable on every command this
            /// client builds.
            pub fn default_env_remove(
                mut self,
                key: impl ::core::convert::AsRef<::std::ffi::OsStr>,
            ) -> Self {
                self.core = self.core.default_env_remove(key);
                self
            }
        }

        impl<R: $crate::ProcessRunner> $name<R> {
            /// Cancel every command this client builds when `token` fires (a
            /// per-command `cancel_on` replaces the default — see
            /// `CliClient::default_cancel_on`).
            pub fn default_cancel_on(mut self, token: $crate::CancellationToken) -> Self {
                self.core = self.core.default_cancel_on(token);
                self
            }
        }
    };
}

#[cfg(test)]
mod tests {
    use std::path::Path;
    use std::time::Duration;

    use super::*;
    use crate::Error;
    use crate::testing::{RecordingRunner, Reply, ScriptedRunner};

    #[test]
    fn debug_redacts_default_env_values_keeping_names() {
        let client = CliClient::new("git")
            .default_env("API_TOKEN", "topsecret-value")
            .default_env_remove("GIT_PAGER");
        let dbg = format!("{client:?}");
        assert!(
            !dbg.contains("topsecret-value"),
            "env value must not appear in Debug: {dbg}"
        );
        assert!(
            dbg.contains("API_TOKEN") && dbg.contains("GIT_PAGER"),
            "env names should appear: {dbg}"
        );
    }

    crate::cli_client!(struct Demo => "git");

    impl<R: ProcessRunner> Demo<R> {
        async fn head(&self, dir: &Path) -> Result<String> {
            self.core
                .run(self.core.command_in(dir, ["rev-parse", "HEAD"]))
                .await
        }
        async fn is_clean(&self, dir: &Path) -> Result<bool> {
            Ok(self
                .core
                .exit_code(self.core.command_in(dir, ["diff", "--quiet"]))
                .await?
                == 0)
        }
        async fn branches(&self, dir: &Path) -> Result<Vec<String>> {
            self.core
                .parse(self.core.command_in(dir, ["branch"]), |s| {
                    s.lines().map(|l| l.trim().to_owned()).collect()
                })
                .await
        }
    }

    #[tokio::test]
    async fn run_trims_trailing_whitespace_only() {
        let demo = Demo::with_runner(
            ScriptedRunner::new().on(["git", "rev-parse"], Reply::ok("  abc123 \n")),
        );
        assert_eq!(demo.head(Path::new(".")).await.unwrap(), "  abc123");
    }

    #[tokio::test]
    async fn exit_code_maps_exit_status() {
        let demo = Demo::with_runner(ScriptedRunner::new().on(["git", "diff"], Reply::fail(1, "")));
        assert!(!demo.is_clean(Path::new(".")).await.unwrap());
    }

    #[tokio::test]
    async fn parse_builds_a_typed_value() {
        let demo = Demo::with_runner(
            ScriptedRunner::new().on(["git", "branch"], Reply::ok("main\nfeature\n")),
        );
        assert_eq!(
            demo.branches(Path::new(".")).await.unwrap(),
            vec!["main", "feature"]
        );
    }

    #[tokio::test]
    async fn try_parse_maps_failure_to_parse_error() {
        let client = CliClient::with_runner(
            "gh",
            ScriptedRunner::new().fallback(Reply::ok("not a number")),
        );
        let err = client
            .try_parse::<u32, _>(client.command(["x"]), |s| {
                s.trim().parse::<u32>().map_err(|e| Error::Parse {
                    program: "gh".into(),
                    message: e.to_string(),
                })
            })
            .await
            .unwrap_err();
        assert!(matches!(err, Error::Parse { .. }), "got {err:?}");
    }

    #[tokio::test]
    async fn verbs_accept_args_directly_or_a_customized_command() {
        use std::time::Duration;
        let runner = ScriptedRunner::new().on(["git", "status"], Reply::ok("clean"));
        let client = CliClient::with_runner("git", runner);

        // Argument list — the program comes from the client, defaults applied.
        assert_eq!(client.run(["status"]).await.unwrap(), "clean");
        assert_eq!(client.run(vec!["status"]).await.unwrap(), "clean");
        // A customized Command runs through the same verb (pass-through).
        let custom = client.command(["status"]).timeout(Duration::from_secs(3));
        assert_eq!(custom.configured_timeout(), Some(Duration::from_secs(3)));
        assert_eq!(client.run(custom).await.unwrap(), "clean");
        let args = ["status"];
        assert_eq!(client.run(&args[..]).await.unwrap(), "clean");
        let result = client.checked(["status"]).await.unwrap();
        assert_eq!(result.stdout(), "clean");
    }

    #[tokio::test]
    async fn first_line_verb_streams_and_matches() {
        let runner =
            ScriptedRunner::new().on(["git", "log"], Reply::lines(["one", "two", "three"]));
        let client = CliClient::with_runner("git", runner);
        let found = client
            .first_line(["log"], |line| line.starts_with('t'))
            .await
            .unwrap();
        assert_eq!(found.as_deref(), Some("two"));
    }

    #[tokio::test]
    async fn when_predicate_reads_public_command_accessors() {
        // Proves `Command`'s accessors are public enough for an external
        // `ScriptedRunner::when` predicate to inspect the command.
        let runner = ScriptedRunner::new()
            .when(
                |c| c.working_dir() == Some(Path::new("/repo")),
                Reply::ok("in-repo"),
            )
            .fallback(Reply::ok("elsewhere"));
        let client = CliClient::with_runner("git", runner);
        assert_eq!(
            client
                .run(client.command_in(Path::new("/repo"), ["status"]))
                .await
                .unwrap(),
            "in-repo"
        );
        assert_eq!(
            client.run(client.command(["status"])).await.unwrap(),
            "elsewhere"
        );
    }

    #[tokio::test]
    async fn recording_runner_captures_args_cwd_and_absence() {
        let rec = RecordingRunner::replying(Reply::ok("https://gh/pr/2\n"));
        let client = CliClient::with_runner("gh", &rec);
        let _ = client
            .run(client.command_in(Path::new("/repo"), ["pr", "create", "--title", "T"]))
            .await
            .unwrap();

        let call = rec.only_call();
        assert_eq!(call.cwd.as_deref(), Some(std::path::Path::new("/repo")));
        assert_eq!(call.args_str(), ["pr", "create", "--title", "T"]);
        assert!(!call.has_flag("--base"), "no --base flag was passed");
    }

    #[tokio::test]
    async fn exit_code_errors_on_timeout() {
        let client = CliClient::with_runner("gh", ScriptedRunner::new().fallback(Reply::timeout()));
        assert!(matches!(
            client
                .exit_code(client.command(["auth", "status"]))
                .await
                .unwrap_err(),
            Error::Timeout { .. }
        ));
    }

    #[tokio::test]
    async fn default_timeout_is_applied() {
        let client = CliClient::new("git").default_timeout(Duration::from_secs(7));
        assert_eq!(
            client.command(["status"]).configured_timeout(),
            Some(Duration::from_secs(7))
        );
    }

    #[tokio::test]
    async fn probe_maps_exit_code_to_bool() {
        let client = CliClient::with_runner(
            "git",
            ScriptedRunner::new()
                .on(["git", "diff"], Reply::fail(1, ""))
                .fallback(Reply::ok("")),
        );
        // `git diff --quiet` exits 1 (dirty) -> false; anything else (0) -> true.
        assert!(
            !client
                .probe(client.command(["diff", "--quiet"]))
                .await
                .unwrap()
        );
        assert!(client.probe(client.command(["status"])).await.unwrap());
    }

    #[tokio::test]
    async fn default_env_is_applied_to_every_command() {
        use std::ffi::OsString;
        let client = CliClient::new("git").default_env("GIT_TERMINAL_PROMPT", "0");
        for cmd in [
            client.command(["status"]),
            client.command_in(Path::new("."), ["fetch"]),
        ] {
            assert!(
                cmd.env_overrides()
                    .iter()
                    .any(|(k, v)| k == "GIT_TERMINAL_PROMPT"
                        && v.as_deref() == Some(OsString::from("0").as_os_str())),
                "default env missing on built command",
            );
        }
    }

    #[tokio::test]
    async fn default_env_reaches_the_invocation() {
        let rec = RecordingRunner::replying(Reply::ok("ok\n"));
        let client = CliClient::with_runner("git", &rec).default_env("GIT_TERMINAL_PROMPT", "0");
        let _ = client.run(client.command(["status"])).await.unwrap();
        let call = rec.only_call();
        assert!(
            call.envs
                .iter()
                .any(|(k, v)| k == "GIT_TERMINAL_PROMPT" && v.is_some()),
            "env override did not reach the runner: {:?}",
            call.envs
        );
    }

    #[tokio::test]
    async fn a_prebuilt_command_passed_to_a_verb_still_gets_client_defaults() {
        let token = crate::CancellationToken::new();
        let client = CliClient::new("git")
            .default_timeout(Duration::from_secs(9))
            .default_env("GIT_TERMINAL_PROMPT", "0")
            .default_cancel_on(token);

        // Built WITHOUT the client (no defaults applied yet).
        let raw = Command::new("git").args(["push"]);
        let filled = raw.into_command(&client);
        assert_eq!(
            filled.configured_timeout(),
            Some(Duration::from_secs(9)),
            "the client default timeout fills the gap"
        );
        assert!(
            filled.cancel_token().is_some(),
            "the client cancel token reaches it"
        );
        assert!(
            filled
                .env_overrides()
                .iter()
                .any(|(k, _)| k == "GIT_TERMINAL_PROMPT"),
            "the client default env reaches it"
        );

        let explicit = Command::new("git")
            .args(["push"])
            .timeout(Duration::from_secs(2))
            .env("GIT_TERMINAL_PROMPT", "1");
        let filled = explicit.into_command(&client);
        assert_eq!(
            filled.configured_timeout(),
            Some(Duration::from_secs(2)),
            "an explicit per-command timeout wins"
        );
        let prompt: Vec<_> = filled
            .env_overrides()
            .iter()
            .filter(|(k, _)| k == "GIT_TERMINAL_PROMPT")
            .collect();
        assert_eq!(prompt.len(), 1, "no duplicate env op for the same key");
        assert_eq!(
            prompt[0].1.as_deref(),
            Some(std::ffi::OsStr::new("1")),
            "the per-command env value wins over the client default"
        );
    }

    #[tokio::test]
    async fn prebuilt_command_env_wins_over_a_case_differing_client_default() {
        let client = CliClient::new("git").default_env("Path", "from-client");
        let cmd = Command::new("git").env("PATH", "from-command");
        let filled = cmd.into_command(&client);
        let path_ops: Vec<_> = filled
            .env_overrides()
            .iter()
            .filter(|(k, _)| k.to_str().is_some_and(|k| k.eq_ignore_ascii_case("PATH")))
            .collect();
        #[cfg(windows)]
        {
            assert_eq!(
                path_ops.len(),
                1,
                "the case-differing client default for the same var is skipped"
            );
            assert_eq!(
                path_ops[0].1.as_deref(),
                Some(std::ffi::OsStr::new("from-command")),
                "the explicit per-command value wins"
            );
        }
        #[cfg(not(windows))]
        {
            assert_eq!(
                path_ops.len(),
                2,
                "on Unix PATH and Path are distinct variables — both kept"
            );
        }
    }

    #[tokio::test]
    async fn default_cancel_on_is_applied_to_every_command() {
        let token = crate::CancellationToken::new();
        let client = CliClient::new("git").default_cancel_on(token);
        for cmd in [
            client.command(["status"]),
            client.command_in(Path::new("."), ["fetch"]),
        ] {
            assert!(
                cmd.cancel_token().is_some(),
                "default token missing on built command"
            );
        }
        assert!(format!("{client:?}").contains("has_default_cancel: true"));
    }

    #[tokio::test(start_paused = true)]
    async fn per_command_cancel_on_overrides_the_default() {
        use crate::CancellationToken;
        let default_token = CancellationToken::new();
        let explicit = CancellationToken::new();
        let client = CliClient::with_runner("gh", ScriptedRunner::new().fallback(Reply::pending()))
            .default_cancel_on(default_token.clone());
        let cmd = client.command(["run", "watch"]).cancel_on(explicit.clone());

        let call = client.output_string(cmd);
        tokio::pin!(call);
        default_token.cancel();
        assert!(
            tokio::time::timeout(Duration::from_secs(3600), &mut call)
                .await
                .is_err(),
            "the replaced default token must not cancel the call"
        );
        explicit.cancel();
        let err = tokio::time::timeout(Duration::from_secs(3600), call)
            .await
            .expect("the explicit token must resolve the call")
            .expect_err("explicit token cancels");
        assert!(matches!(err, Error::Cancelled { .. }), "got {err:?}");
    }

    #[tokio::test(start_paused = true)]
    async fn acceptance_pending_reply_with_client_default_cancel() {
        use crate::CancellationToken;
        let token = CancellationToken::new();
        let rec = RecordingRunner::new(
            ScriptedRunner::new().on(["gh", "run", "watch"], Reply::pending()),
        );
        let client = CliClient::with_runner("gh", &rec).default_cancel_on(token.clone());

        let call = client.output_string(client.command(["run", "watch", "123"]));
        tokio::pin!(call);
        assert!(
            tokio::time::timeout(Duration::from_secs(3600), &mut call)
                .await
                .is_err(),
            "must not resolve before the token fires"
        );
        token.cancel();
        match tokio::time::timeout(Duration::from_secs(3600), call)
            .await
            .expect("the cancelled token must resolve the call")
        {
            Err(Error::Cancelled { program }) => assert_eq!(program, "gh"),
            other => panic!("expected Error::Cancelled, got {other:?}"),
        }
        assert_eq!(rec.only_call().args_str(), ["run", "watch", "123"]);
    }

    #[test]
    fn macro_emits_default_cancel_on() {
        let _client = Demo::with_runner(ScriptedRunner::new())
            .default_cancel_on(crate::CancellationToken::new());
    }

    #[test]
    fn macro_generates_all_constructors() {
        let _real = Demo::new();
        let _default = Demo::default();
        let _fake = Demo::with_runner(ScriptedRunner::new())
            .default_timeout(Duration::from_secs(1))
            .default_env("GIT_TERMINAL_PROMPT", "0")
            .default_env_remove("GIT_PAGER");
    }
}