tga 10.0.0

//! Remote fetch helper used prior to revwalk.
//!
//! Performs a non-interactive `git fetch` against a configured remote so
//! the local clone has the latest commits before [`super::GitCollector`]
//! walks history.  Since tga 2.6.0 the fetch is **required** by default:
//! if the remote cannot be reached, `tga collect` errors rather than
//! silently walking stale local refs.  Pass `--allow-stale` to revert to
//! the old best-effort behaviour.
//!
//! ## Authentication strategy (tried in order)
//!
//! 1. SSH agent (if running and has a usable key)
//! 2. SSH key files at `~/.ssh/id_ed25519` then `~/.ssh/id_rsa`
//! 3. HTTPS token from `GITHUB_TOKEN` or `GH_TOKEN` environment variable
//!    (used as the password with username `x-access-token` — the standard
//!    GitHub Personal-Access-Token / GitHub App token form)
//! 4. Git credential helper (falls through to the platform keychain, e.g.
//!    `osxkeychain`, `store`, or `manager-core`)
//!
//! Each is offered at most once per fetch, in that order: libgit2 re-enters
//! the credential callback after every rejection, so a callback that answered
//! from the top each time would re-offer source 1 forever (#6782).
//!
//! **No interactive prompts** — SSH BatchMode-equivalent. We never ask
//! for a password or passphrase, because the binary is typically run
//! in CI / background tasks where stdin is unavailable.

use std::path::PathBuf;

use git2::{Cred, CredentialType, FetchOptions, RemoteCallbacks, Repository};
use tracing::{info, warn};

use crate::collect::collector::{FetchOutcome, PerRepoFetch};
use crate::collect::errors::Result;

/// Fetch all refs from the configured remote before walking.
///
/// Why: backwards-compatible soft-fail wrapper; callers that do not need
/// per-repo outcome tracking use this.
/// What: returns `Ok(())` whether the fetch succeeds or fails so that
/// collection can always proceed on whatever the local clone has.
/// Test: covered indirectly by extractor tests that call `GitCollector::collect`.
pub fn fetch_remote(repo: &Repository, remote_name: &str) -> Result<()> {
    fetch_remote_with_outcome(repo, remote_name).map(|_| ())
}

/// Fetch all refs from the configured remote and return a typed outcome.
///
/// Why: `fetch_remote` discards success/failure information; this variant
/// surfaces it as a [`FetchOutcome`] so the CLI can print an end-of-run
/// summary table (requirement #334).
/// What: attempts `git fetch <remote_name>`.  Returns:
///   - `FetchOutcome::Success` on a clean fetch,
///   - `FetchOutcome::Skipped` when the named remote does not exist
///     (local-only repos are a supported case — not an error),
///   - `FetchOutcome::Failed` for any auth/transport/git2 error.
///
/// Test: unit test `tests::fetch_outcome_skipped_for_local_repo` in this
/// module verifies the Skipped path; Failed and Success paths are exercised
/// by integration tests against real git fixtures.
pub fn fetch_remote_with_outcome(repo: &Repository, remote_name: &str) -> Result<FetchOutcome> {
    let mut remote = match repo.find_remote(remote_name) {
        Ok(r) => r,
        Err(e) => {
            // Most common: local-only repo with no remotes configured.
            info!(
                remote = remote_name,
                error = %e,
                "no matching remote; skipping fetch (local-only repo)"
            );
            return Ok(FetchOutcome::Skipped {
                reason: "no remote configured".to_string(),
            });
        }
    };

    info!("Fetching from remote '{}'", remote_name);

    // #6782: libgit2 calls this callback again after every credential the
    // remote rejects, so one that answers with the same source each time never
    // reaches the next one. That is not hypothetical: `Cred::ssh_key_from_agent`
    // succeeds against an `ssh-agent` holding no identities, so a host whose
    // key lives in a file — the ordinary macOS 1Password/keychain setup — spent
    // two minutes re-offering an empty agent to github.com and then reported
    // `Auth (-16)`, never trying `~/.ssh/id_ed25519` at all. The cursor is what
    // advances the chain.
    let cursor = std::cell::Cell::new(0usize);
    let mut callbacks = RemoteCallbacks::new();
    callbacks.credentials(move |_url, username_from_url, allowed_types| {
        let (next, cred) =
            non_interactive_credentials(cursor.get(), username_from_url, allowed_types)?;
        cursor.set(next);
        Ok(cred)
    });

    let mut fetch_options = FetchOptions::new();
    fetch_options.remote_callbacks(callbacks);

    // Fetch with default refspecs (empty slice == use configured refspecs).
    match remote.fetch(&[] as &[&str], Some(&mut fetch_options), None) {
        Ok(()) => {
            info!(remote = remote_name, "fetch succeeded");
            Ok(FetchOutcome::Success {
                remote: remote_name.to_string(),
            })
        }
        Err(e) => {
            // git2 lumps auth, transport, and certificate problems together;
            // treat anything in the auth/transport family as a soft failure
            // but record the error string so the end-of-run summary is useful.
            let kind = if is_auth_or_transport_error(&e) {
                "auth/transport"
            } else {
                "git"
            };
            warn!(
                remote = remote_name,
                error = %e,
                kind,
                "fetch failed — continuing with local refs"
            );
            Ok(FetchOutcome::Failed {
                remote: remote_name.to_string(),
                error: e.to_string(),
            })
        }
    }
}

/// Build a [`PerRepoFetch`] by running a tracked fetch for a named repository.
///
/// Why: wraps `fetch_remote_with_outcome` with the repo display name so the
/// returned value is ready to push into [`crate::collect::collector::CollectionStats::fetch_outcomes`].
/// What: opens the repo, runs `fetch_remote_with_outcome`, and packages the
/// result with `repo_name`.  If opening the repo fails, returns a Failed
/// outcome rather than propagating the error (consistent with the soft-fail
/// policy for all per-repo operations).
/// Test: covered by the integration test in `collector::tests`.
pub fn fetch_and_record(repo: &Repository, repo_name: &str, remote_name: &str) -> PerRepoFetch {
    match fetch_remote_with_outcome(repo, remote_name) {
        Ok(outcome) => PerRepoFetch {
            repo: repo_name.to_string(),
            outcome,
        },
        Err(e) => PerRepoFetch {
            repo: repo_name.to_string(),
            outcome: FetchOutcome::Failed {
                remote: remote_name.to_string(),
                error: e.to_string(),
            },
        },
    }
}

/// One non-interactive place a credential can come from.
///
/// Why (#6782): the chain used to be `if` arms inside one function, which is
/// only expressible as "the first source that yields anything". libgit2 asks
/// again after each rejection, so what it actually needs is an ordered list it
/// can be walked through — the same order, addressable by position.
#[derive(Clone, Copy)]
enum CredSource {
    /// A key held by a running `ssh-agent`.
    Agent,
    /// A private key file under `~/.ssh/`, by basename.
    KeyFile(&'static str),
    /// `GITHUB_TOKEN` / `GH_TOKEN` as an HTTPS password.
    GithubToken,
    /// The platform credential helper (`osxkeychain`, `store`, …).
    Helper,
}

/// The sources tried, in order, most specific first.
const CRED_CHAIN: [CredSource; 5] = [
    CredSource::Agent,
    CredSource::KeyFile("id_ed25519"),
    CredSource::KeyFile("id_rsa"),
    CredSource::GithubToken,
    CredSource::Helper,
];

/// The next usable credential at or after `from` in [`CRED_CHAIN`], and the
/// position the caller should resume from.
///
/// Why: `RemoteCallbacks::credentials` is re-entered after every credential the
/// remote rejects. Answering from a cursor rather than from the top is what
/// turns the chain into a real fallback sequence — before #6782 it was a loop,
/// because `Cred::ssh_key_from_agent` succeeds against an agent holding no
/// identities and so was re-offered until libgit2 gave up.
/// What: scans forward for the first source whose `allowed_types` the remote
/// permits and that can actually build a `Cred`, and returns it with the index
/// after it. Sources that cannot apply are skipped without consuming a turn.
/// Never prompts: a key file is passed with no passphrase, so an encrypted one
/// fails here rather than blocking on stdin.
/// Test: `tests::the_credential_chain_advances_rather_than_repeating`.
fn non_interactive_credentials(
    from: usize,
    username_from_url: Option<&str>,
    allowed_types: CredentialType,
) -> std::result::Result<(usize, Cred), git2::Error> {
    let username = username_from_url.unwrap_or("git");

    for (index, source) in CRED_CHAIN.iter().enumerate().skip(from) {
        let cred = match source {
            CredSource::Agent if allowed_types.contains(CredentialType::SSH_KEY) => {
                Cred::ssh_key_from_agent(username).ok()
            }
            CredSource::KeyFile(name) if allowed_types.contains(CredentialType::SSH_KEY) => {
                home_dir()
                    .map(|home| home.join(".ssh").join(name))
                    .filter(|key| key.exists())
                    .and_then(|key| {
                        // git2 needs a passphrase parameter even for unencrypted
                        // keys; None forces non-interactive behaviour.
                        Cred::ssh_key(username, None, key.as_path(), None).ok()
                    })
            }
            // The canonical `x-access-token` username GitHub expects for PAT /
            // GitHub App token authentication over HTTPS.
            CredSource::GithubToken
                if allowed_types.contains(CredentialType::USER_PASS_PLAINTEXT) =>
            {
                std::env::var(trusty_common::env_vars::ENV_GITHUB_TOKEN)
                    .or_else(|_| std::env::var("GH_TOKEN"))
                    .ok()
                    .and_then(|token| Cred::userpass_plaintext("x-access-token", &token).ok())
            }
            CredSource::Helper if allowed_types.contains(CredentialType::DEFAULT) => {
                Cred::default().ok()
            }
            _ => None,
        };
        if let Some(cred) = cred {
            return Ok((index + 1, cred));
        }
    }

    Err(git2::Error::from_str(
        "no non-interactive credentials available \
         (tried SSH agent, ~/.ssh/id_ed25519, ~/.ssh/id_rsa, \
         GITHUB_TOKEN/GH_TOKEN env, platform credential helper)",
    ))
}

/// Best-effort home-directory lookup using `$HOME`.
///
/// We deliberately avoid pulling in the `home` / `dirs` crate for one
/// path lookup; `$HOME` is set on every supported platform.
fn home_dir() -> Option<PathBuf> {
    std::env::var_os("HOME").map(PathBuf::from)
}

/// Classify an error as an auth/transport failure suitable for soft-failing.
fn is_auth_or_transport_error(e: &git2::Error) -> bool {
    matches!(
        e.class(),
        git2::ErrorClass::Ssh
            | git2::ErrorClass::Http
            | git2::ErrorClass::Net
            | git2::ErrorClass::Callback
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Why: local-only repos (no remotes) are a valid configuration; the
    /// fetch path must return Skipped rather than an error.
    /// What: creates a temp in-memory git repo with no remotes, calls
    /// `fetch_remote_with_outcome`, and asserts the Skipped variant.
    /// Test: this test itself.
    #[test]
    fn fetch_outcome_skipped_for_local_repo() {
        let td = tempfile::tempdir().expect("tempdir");
        let repo = git2::Repository::init(td.path()).expect("init");
        // No remote configured → expect Skipped.
        let outcome =
            fetch_remote_with_outcome(&repo, "origin").expect("no error expected from soft-fail");
        assert!(
            matches!(outcome, FetchOutcome::Skipped { .. }),
            "expected Skipped, got {outcome:?}"
        );
    }

    /// Why: ensure that `fetch_and_record` wraps the outcome with the correct
    /// repo name without panicking.
    /// What: uses the same local-only repo and verifies PerRepoFetch.repo field.
    /// Test: this test itself.
    #[test]
    fn fetch_and_record_sets_repo_name() {
        let td = tempfile::tempdir().expect("tempdir");
        let repo = git2::Repository::init(td.path()).expect("init");
        let prf = fetch_and_record(&repo, "my-repo", "origin");
        assert_eq!(prf.repo, "my-repo");
        assert!(
            matches!(prf.outcome, FetchOutcome::Skipped { .. }),
            "expected Skipped, got {:?}",
            prf.outcome
        );
    }

    /// Why: the end-of-run fetch summary must include `Failed` entries for
    /// repos whose remote exists but cannot be reached.  This test proves that
    /// `fetch_remote_with_outcome` returns a `Failed` variant (not a panic or
    /// an `Err`) when the remote's URL is unreachable.
    /// What: creates two git repos, adds repo-b as an "origin" remote on
    /// repo-a, then deletes repo-b so the URL is valid-looking but the target
    /// directory is gone.  The fetch attempt against that dead path must
    /// produce `FetchOutcome::Failed`.
    /// Test: this test itself — covers the `Failed` branch of
    /// `fetch_remote_with_outcome` and by extension `fetch_and_record`.
    #[test]
    fn fetch_remote_with_outcome_returns_failed_for_dead_remote() {
        let td_remote = tempfile::tempdir().expect("tempdir for remote");
        // Initialise a bare remote repo so git2 can point an origin at a valid path.
        let _remote = git2::Repository::init_bare(td_remote.path()).expect("init bare");

        let td_local = tempfile::tempdir().expect("tempdir for local");
        let local = git2::Repository::init(td_local.path()).expect("init local");

        // Set the origin remote to the path of the bare repo, then remove it
        // to make the URL dead without being syntactically invalid.
        let remote_url = td_remote.path().to_str().expect("valid utf8").to_string();
        local
            .remote("origin", &remote_url)
            .expect("add remote origin");
        // Drop td_remote explicitly to delete the directory.
        drop(td_remote);
        // Reopen local after remote dir is gone.
        let local2 = git2::Repository::open(td_local.path()).expect("reopen local");

        let outcome = fetch_remote_with_outcome(&local2, "origin")
            .expect("no Err — soft-fail policy means we return Ok(Failed)");
        assert!(
            matches!(outcome, FetchOutcome::Failed { .. }),
            "expected Failed for dead remote path, got {outcome:?}"
        );

        // Also verify the fetch_and_record wrapper preserves the repo name.
        let local3 = git2::Repository::open(td_local.path()).expect("reopen local 3");
        let prf = fetch_and_record(&local3, "dead-remote-repo", "origin");
        assert_eq!(prf.repo, "dead-remote-repo");
        assert!(
            matches!(prf.outcome, FetchOutcome::Failed { .. }),
            "expected Failed in PerRepoFetch, got {:?}",
            prf.outcome
        );
    }

    /// The error libgit2 returns when it has no transport for a URL's scheme.
    ///
    /// #6782: this is the string 59 client repositories hit, and the one thing
    /// an SSH remote must never produce — it means libssh2 was never linked in,
    /// so no credential this module offers was ever consulted.
    const NO_TRANSPORT: &str = "unsupported URL protocol";

    /// A loopback port with nothing listening, so a connect attempt is refused
    /// immediately rather than waiting out a TCP timeout.
    fn closed_loopback_port() -> u16 {
        let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind ephemeral port");
        let port = listener.local_addr().expect("local addr").port();
        drop(listener);
        port
    }

    /// Run a tracked fetch against `url` and return the recorded failure text.
    fn fetch_error_for(url: &str) -> String {
        let td = tempfile::tempdir().expect("tempdir");
        let repo = git2::Repository::init(td.path()).expect("init");
        repo.remote("origin", url).expect("add remote origin");
        match fetch_remote_with_outcome(&repo, "origin").expect("soft-fail returns Ok") {
            FetchOutcome::Failed { error, .. } => error,
            other => panic!("expected Failed for unreachable {url}, got {other:?}"),
        }
    }

    /// Why (#6782): with the SSH transport linked, the credential chain ran for
    /// the first time and looped. `Cred::ssh_key_from_agent` succeeds against an
    /// `ssh-agent` holding no identities, and the callback answered from the top
    /// of the chain every time libgit2 re-entered it, so `~/.ssh/id_ed25519` was
    /// never reached — a real fetch spent 120 s re-offering an empty agent to
    /// github.com and then reported `class=Ssh (23); code=Auth (-16)`.
    /// What: walks the chain from every position and asserts each answer
    /// advances the cursor, so the sequence is finite whatever this machine
    /// happens to hold. Environment-independent by construction: it asserts the
    /// advance, never which source answered.
    /// Test: this is the test.
    #[test]
    fn the_credential_chain_advances_rather_than_repeating() {
        let allowed =
            CredentialType::SSH_KEY | CredentialType::USER_PASS_PLAINTEXT | CredentialType::DEFAULT;

        let mut cursor = 0usize;
        let mut answers = 0usize;
        while let Ok((next, _cred)) = non_interactive_credentials(cursor, Some("git"), allowed) {
            assert!(
                next > cursor,
                "the callback answered without advancing: cursor {cursor} -> {next}"
            );
            cursor = next;
            answers += 1;
            assert!(
                answers <= CRED_CHAIN.len(),
                "the chain answered more times than it has sources"
            );
        }
        assert!(
            cursor <= CRED_CHAIN.len(),
            "the cursor ran past the chain: {cursor}"
        );
    }

    /// Why (#6782): tga's `git2` was built without the `ssh` feature, so
    /// libgit2 rejected every `ssh://` remote before the credential callback
    /// above ran. The audit then walked whatever the clone-time refs held and
    /// reported success.
    /// What: points `origin` at an `ssh://` URL on a closed loopback port and
    /// asserts the recorded failure is a connect/auth failure, not libgit2
    /// declining the scheme. Pre-fix this asserts against `unsupported URL
    /// protocol; class=Net (12)`.
    /// Test: this is the test.
    #[test]
    fn an_ssh_url_reaches_the_ssh_transport() {
        let url = format!(
            "ssh://git@127.0.0.1:{}/org/repo.git",
            closed_loopback_port()
        );
        let error = fetch_error_for(&url);
        assert!(
            !error.contains(NO_TRANSPORT),
            "ssh:// remote was rejected for want of a transport, not for want of a \
             reachable host: {error}"
        );
    }

    /// Why (#6782): the scp-style spelling `git@host:org/repo.git` is what
    /// `git clone` writes for a GitHub SSH remote, so it is the form the client
    /// audit actually carried. libgit2 parses it into the same SSH transport,
    /// which means it fails the same way when that transport is absent.
    /// What: points `origin` at a scp-style URL on loopback and asserts the
    /// failure is not the missing-transport error.
    /// Test: this is the test.
    #[test]
    fn an_scp_style_remote_reaches_the_ssh_transport() {
        let error = fetch_error_for("git@127.0.0.1:org/repo.git");
        assert!(
            !error.contains(NO_TRANSPORT),
            "scp-style remote was rejected for want of a transport, not for want of a \
             reachable host: {error}"
        );
    }
}