nornir_git/

gitio.rs

//! Pure-Rust git helpers (via `gix`). The single home for read-side
//! git inspection so the rest of the crate never shells out to the
//! `git` binary. No `std::process::Command`, no libgit2/C — matches
//! nornir's pure-Rust ethos (gix over libgit2, like `ureq` over curl).
//!
//! Write/network release operations (commit-on-release, push) live in
//! nornir's `release::publish`. The write helpers here — [`init`] and
//! [`commit_all`] — exist only to build *new* repositories from scratch
//! (test fixtures and the synthetic-repo generator) without ever
//! shelling out; they use a fixed, deterministic identity so fixtures
//! are reproducible and need no ambient git config.

use std::path::{Path, PathBuf};

use anyhow::{anyhow, bail, Context, Result};

/// Full 40-char hex SHA of the commit `HEAD` points at.
///
/// **gix-first, `git`-fallback.** Some server-cloned repos hit a gix
/// `Repository::head()` quirk that the `git` binary reads fine (the same reason
/// `viz::model` already shells out — see its `git-fallback:` logging). gix stays
/// the fast path; when it errs we fall back to `git rev-parse` so the dependency
/// Mímir (change-detection / build-order) never dead-ends on one repo.
pub fn head_sha(root: &Path) -> Result<String> {
    match gix_head_sha(root) {
        Ok(sha) => Ok(sha),
        Err(_) => git_head_sha(root)
            .with_context(|| format!("read HEAD of {} (gix + git both failed)", root.display())),
    }
}

fn gix_head_sha(root: &Path) -> Result<String> {
    let repo = gix::open(root).with_context(|| format!("gix::open {}", root.display()))?;
    let id = repo
        .head()
        .context("read HEAD")?
        .id()
        .ok_or_else(|| anyhow!("HEAD has no commit (unborn?) in {}", root.display()))?;
    Ok(id.to_string())
}

/// `git -C <root> rev-parse HEAD` — the fallback when gix can't read HEAD.
fn git_head_sha(root: &Path) -> Result<String> {
    let out = std::process::Command::new("git")
        .arg("-C")
        .arg(root)
        .args(["rev-parse", "HEAD"])
        .output()
        .with_context(|| format!("spawn `git rev-parse HEAD` in {}", root.display()))?;
    if !out.status.success() {
        return Err(anyhow!(
            "git rev-parse HEAD failed in {}: {}",
            root.display(),
            String::from_utf8_lossy(&out.stderr).trim()
        ));
    }
    Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
}

/// Short branch name for `HEAD`, or `"(detached)"` when detached. gix-first,
/// `git symbolic-ref` fallback (see [`head_sha`]).
pub fn head_branch(root: &Path) -> Result<String> {
    if let Ok(b) = gix_head_branch(root) {
        return Ok(b);
    }
    git_head_branch(root)
}

fn gix_head_branch(root: &Path) -> Result<String> {
    let repo = gix::open(root).with_context(|| format!("gix::open {}", root.display()))?;
    Ok(match repo.head_name().context("read HEAD name")? {
        Some(name) => name.shorten().to_string(),
        None => "(detached)".to_string(),
    })
}

/// `git -C <root> symbolic-ref --short HEAD` — `"(detached)"` when it isn't a branch.
fn git_head_branch(root: &Path) -> Result<String> {
    let out = std::process::Command::new("git")
        .arg("-C")
        .arg(root)
        .args(["symbolic-ref", "--short", "HEAD"])
        .output()
        .with_context(|| format!("spawn `git symbolic-ref HEAD` in {}", root.display()))?;
    if !out.status.success() {
        return Ok("(detached)".to_string());
    }
    Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
}

/// `(sha, branch)` for `HEAD`. gix-first, `git`-fallback for each half (see
/// [`head_sha`]).
pub fn head_sha_and_branch(root: &Path) -> Result<(String, String)> {
    Ok((head_sha(root)?, head_branch(root)?))
}

/// Sentinel digest for a **clean** working tree (no tracked modifications,
/// nothing staged, no untracked files). A fixed string so clients can test it
/// without recomputing a hash of the empty set.
pub const CLEAN_WORKTREE_DIGEST: &str = "clean";

/// A working-tree **freshness** reading: whether the tree is dirty and a stable
/// content digest of the porcelain status (AUT6 / freshness gate).
///
/// The whole point: a commit SHA cannot detect *uncommitted* edits — two
/// different working trees can sit on the same `HEAD`. The digest does. A thin
/// client compares its local digest to the indexed one; if they differ the
/// warehouse is stale relative to the live tree.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WorktreeFreshness {
    /// `true` ⇒ tracked modifications, staged changes, or untracked files exist.
    pub dirty: bool,
    /// Stable hex digest of the sorted porcelain status. Equals
    /// [`CLEAN_WORKTREE_DIGEST`] when `dirty == false`.
    pub digest: String,
}

/// Compute the working-tree freshness of the repo at `root`, **in-process via
/// gix** (no shelling out to the `git` binary).
///
/// The digest is a SHA-256 over the repo's porcelain status: every changed path
/// (tracked modification / staged change / tree-vs-index change) plus every
/// untracked path, each tagged with a one-letter status and — for paths that
/// exist on disk — their `(size, mtime)`, sorted by path for stability. A clean
/// tree hashes to the [`CLEAN_WORKTREE_DIGEST`] sentinel (the empty set), so two
/// clean checkouts of the same commit always agree, and any uncommitted edit —
/// which the `HEAD` SHA cannot see — flips the digest.
pub fn worktree_freshness(root: &Path) -> Result<WorktreeFreshness> {
    use gix::bstr::ByteSlice;
    use sha2::{Digest, Sha256};

    let repo = gix::open(root).with_context(|| format!("gix::open {}", root.display()))?;
    let workdir = repo
        .workdir()
        .ok_or_else(|| anyhow!("bare repo has no working tree: {}", root.display()))?
        .to_path_buf();

    // `status` walks: tree↔index (staged), index↔worktree (tracked mods), and
    // the dirwalk for untracked files. Untracked files are included so an
    // entirely new, unstaged file marks the tree dirty.
    let platform = repo
        .status(gix::progress::Discard)
        .context("open status platform")?
        .untracked_files(gix::status::UntrackedFiles::Files);
    let iter = platform
        .into_iter(None)
        .context("start working-tree status iteration")?;

    // (path, "<status-tag> <size>:<mtime_nanos>") lines, sorted for stability.
    let mut lines: Vec<String> = Vec::new();
    for item in iter {
        let item = item.context("read status item")?;
        let rela = item.location().to_str_lossy().into_owned();
        let tag = match &item {
            gix::status::Item::TreeIndex(_) => 'S',          // staged (tree↔index)
            gix::status::Item::IndexWorktree(iw) => match iw {
                gix::status::index_worktree::Item::Modification { .. } => 'M',
                gix::status::index_worktree::Item::DirectoryContents { .. } => 'U', // untracked
                gix::status::index_worktree::Item::Rewrite { .. } => 'R',
            },
        };
        // Stat the on-disk file (best-effort): content edits move size/mtime even
        // when the path set is unchanged. Missing/deleted files contribute "-".
        let stat = match std::fs::metadata(workdir.join(&rela)) {
            Ok(md) => {
                let mtime = md
                    .modified()
                    .ok()
                    .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
                    .map(|d| d.as_nanos())
                    .unwrap_or(0);
                format!("{}:{mtime}", md.len())
            }
            Err(_) => "-".to_string(),
        };
        lines.push(format!("{tag} {rela} {stat}"));
    }

    if lines.is_empty() {
        return Ok(WorktreeFreshness { dirty: false, digest: CLEAN_WORKTREE_DIGEST.to_string() });
    }
    lines.sort();
    let mut hasher = Sha256::new();
    for l in &lines {
        hasher.update(l.as_bytes());
        hasher.update(b"\n");
    }
    use std::fmt::Write as _;
    let mut digest = String::with_capacity(64);
    for b in hasher.finalize() {
        let _ = write!(digest, "{b:02x}");
    }
    Ok(WorktreeFreshness { dirty: true, digest })
}

/// Commit SHA the tag `refs/tags/<tag>` resolves to, peeling annotated
/// tags down to their target commit. `Ok(None)` if the tag is absent.
pub fn tag_commit_sha(root: &Path, tag: &str) -> Result<Option<String>> {
    let repo = gix::open(root).with_context(|| format!("gix::open {}", root.display()))?;
    let full = format!("refs/tags/{tag}");
    let Some(reference) = repo
        .try_find_reference(full.as_str())
        .with_context(|| format!("look up {full}"))?
    else {
        return Ok(None);
    };
    let id = reference
        .into_fully_peeled_id()
        .with_context(|| format!("peel {full}"))?;
    Ok(Some(id.to_string()))
}

/// True iff `refs/tags/<tag>` exists and (after peeling) points at the
/// same commit as `HEAD`.
pub fn tag_points_at_head(root: &Path, tag: &str) -> Result<bool> {
    match tag_commit_sha(root, tag)? {
        Some(tag_sha) => Ok(tag_sha == head_sha(root)?),
        None => Ok(false),
    }
}

/// Fixed identity for fixture/generated commits — deterministic so test
/// repos hash reproducibly and require no ambient `git` config.
const FIXTURE_NAME: &str = "Nornir Fixture";
const FIXTURE_EMAIL: &str = "fixtures@nornir.invalid";
const FIXTURE_TIME: &str = "1700000000 +0000";

/// Initialise a fresh git repository at `root` (pure-Rust via `gix`).
/// The directory is created if missing. Used by test fixtures and the
/// synthetic-repo generator so setup code is also free of `git`
/// subprocesses.
pub fn init(root: &Path) -> Result<()> {
    std::fs::create_dir_all(root).with_context(|| format!("mkdir {}", root.display()))?;
    gix::init(root).with_context(|| format!("gix init {}", root.display()))?;
    Ok(())
}

/// Snapshot the entire working tree (every file except those under
/// `.git/`) into a new commit on `HEAD`, returning the commit SHA.
///
/// Works for the initial commit (unborn `HEAD`, no parent) and for
/// subsequent commits (parent = current `HEAD`). Because the tree is
/// rebuilt from the filesystem each call, additions, modifications and
/// deletions are all captured — a faithful `git add -A && git commit`
/// for synthetic repos that have no `.gitattributes` content filters.
pub fn commit_all(root: &Path, message: &str) -> Result<String> {
    let repo = gix::open(root).with_context(|| format!("gix::open {}", root.display()))?;
    let empty = gix::ObjectId::empty_tree(repo.object_hash());
    let mut editor = repo.edit_tree(empty).context("seed empty tree editor")?;

    add_dir_recursive(&repo, &mut editor, root, root)?;
    let tree = editor.write().context("write fixture tree")?.detach();

    let parents: Vec<gix::ObjectId> = repo.head_commit().ok().map(|c| c.id).into_iter().collect();
    let sig = gix::actor::SignatureRef {
        name: gix::bstr::BStr::new(FIXTURE_NAME),
        email: gix::bstr::BStr::new(FIXTURE_EMAIL),
        time: FIXTURE_TIME,
    };
    let id = repo
        .commit_as(sig, sig, "HEAD", message, tree, parents)
        .context("create fixture commit")?;

    // Write the index from the new tree so the freshly-built repo reads
    // clean (gix::init leaves no index; without this the whole worktree
    // would look untracked to a subsequent status check).
    let mut index = repo
        .index_from_tree(&tree)
        .context("rebuild index from fixture tree")?;
    index
        .write(gix::index::write::Options::default())
        .context("persist fixture index")?;

    Ok(id.to_string())
}

/// Create a lightweight tag `refs/tags/<name>` pointing at `target_sha`.
/// Pure-gix (no shell). Fails if the tag already exists.
pub fn tag_lightweight(root: &Path, name: &str, target_sha: &str) -> Result<()> {
    let repo = gix::open(root).with_context(|| format!("gix::open {}", root.display()))?;
    let target = gix::ObjectId::from_hex(target_sha.as_bytes())
        .with_context(|| format!("parse target sha `{target_sha}`"))?;
    repo.tag_reference(name, target, gix::refs::transaction::PreviousValue::MustNotExist)
        .with_context(|| format!("create tag `{name}` -> {target_sha}"))?;
    Ok(())
}

// ── Network (server-monitored poll/fetch) ───────────────────────────────────
//
// Pure-Rust git, no `git`/`ssh` subprocess, no C:
// - HTTPS: gix + rustls (clone/fetch).
// - SSH:   `russh` runs `git-upload-pack` over an authenticated channel and gix
//          drives the wire protocol + pack indexing over it (see [`ssh_sync`]).
//          gix's *own* SSH transport execs `ssh`, which we avoid.

/// `true` for SSH-style remotes (`git@host:…` or `ssh://…`).
pub fn is_ssh_url(url: &str) -> bool {
    url.starts_with("ssh://") || (url.contains('@') && !url.contains("://"))
}

/// Clone `url` into `dest` (full worktree). Pure Rust over HTTPS.
fn clone_repo(url: &str, dest: &Path) -> Result<()> {
    std::fs::create_dir_all(dest).with_context(|| format!("create {}", dest.display()))?;
    let mut prepare = gix::prepare_clone(url, dest)
        .with_context(|| format!("prepare clone {url} → {}", dest.display()))?
        // Fetch ALL tags — release tags drive the viz timeline's git-history
        // fallback; gix's default refspec maps only branches.
        .configure_remote(|remote| {
            Ok::<_, Box<dyn std::error::Error + Send + Sync>>(
                remote.with_fetch_tags(gix::remote::fetch::Tags::All),
            )
        });
    let (mut checkout, _) = prepare
        .fetch_then_checkout(gix::progress::Discard, &gix::interrupt::IS_INTERRUPTED)
        .with_context(|| format!("clone-fetch {url}"))?;
    checkout
        .main_worktree(gix::progress::Discard, &gix::interrupt::IS_INTERRUPTED)
        .with_context(|| format!("checkout worktree for {url}"))?;
    Ok(())
}

/// Fetch the default remote of an existing HTTPS clone at `dest`.
fn fetch_repo(dest: &Path) -> Result<()> {
    let repo = gix::open(dest).with_context(|| format!("gix::open {}", dest.display()))?;
    let remote = repo
        .find_default_remote(gix::remote::Direction::Fetch)
        .ok_or_else(|| anyhow!("{} has no fetch remote", dest.display()))?
        .context("resolve default remote")?
        // Pull tags too, so newly-released versions appear in the timeline.
        .with_fetch_tags(gix::remote::fetch::Tags::All);
    remote
        .connect(gix::remote::Direction::Fetch)
        .context("connect to remote")?
        .prepare_fetch(gix::progress::Discard, Default::default())
        .context("prepare fetch")?
        .receive(gix::progress::Discard, &gix::interrupt::IS_INTERRUPTED)
        .context("fetch")?;
    Ok(())
}

/// Resolve the deploy-key path the server uses for git-over-SSH. Mirrors the
/// CLI's `nornir key` resolution: honors `NORNIR_SSH_DIR`, else the `nornir`
/// system user's home (`/home/nornir/.ssh`), else a per-user dev location that
/// never touches the operator's own `~/.ssh`. Returns the private key path only
/// if it exists.
pub fn nornir_ssh_key_path() -> Option<PathBuf> {
    let dir = if let Some(d) = std::env::var_os("NORNIR_SSH_DIR") {
        PathBuf::from(d)
    } else {
        let sys = Path::new("/home/nornir/.ssh");
        if sys.exists() {
            sys.to_path_buf()
        } else if let Some(home) = std::env::var_os("HOME") {
            Path::new(&home).join(".nornir/ssh")
        } else {
            return None;
        }
    };
    let key = dir.join("id_ed25519");
    key.exists().then_some(key)
}

/// Clone-or-fetch `url` into `dest` over SSH with the deploy key at `key_path`,
/// returning the fetched `HEAD` SHA.
///
/// `russh` opens an authenticated `git-upload-pack` channel; gix's blocking git
/// transport (`ConnectMode::Process`) negotiates and receives the pack over it,
/// writing objects + `refs/remotes/origin/*` into the repo. We then point HEAD
/// at the fetched commit and materialize the worktree from its tree.
fn ssh_sync(url: &str, dest: &Path, key_path: &Path) -> Result<String> {
    use gix::protocol::transport::client::git::blocking_io::Connection as GitConnection;
    use gix::protocol::transport::client::git::ConnectMode;
    use gix::protocol::transport::Protocol;

    let loc = crate::ssh::parse_ssh_url(url)?;

    // 1. Cheap ref advertisement: HEAD's SHA + the branch it points at.
    let refs = crate::ssh::ls_remote_blocking(url, key_path)
        .with_context(|| format!("ssh ls-remote {url}"))?;
    let head_sha = refs
        .iter()
        .find(|(_, name)| name == "HEAD")
        .map(|(sha, _)| sha.clone())
        .ok_or_else(|| anyhow!("remote {url} advertised no HEAD"))?;
    // GitHub advertises HEAD's branch too; match by SHA to learn its name.
    let branch = refs
        .iter()
        .find(|(sha, name)| sha == &head_sha && name.starts_with("refs/heads/"))
        .map(|(_, name)| name.clone())
        .unwrap_or_else(|| "refs/heads/main".to_string());

    // Cheap change-detection (ls-remote's purpose): if the worktree is already at
    // this commit, there's nothing to fetch — the common steady-state poll.
    if dest.join(".git").exists()
        && crate::gitio::head_sha(dest).ok().as_deref() == Some(head_sha.as_str())
    {
        return Ok(head_sha);
    }
    eprintln!("nornir-ssh: {url} HEAD={head_sha} changed; fetching pack…");

    // 2. Repo: open if present, else init a fresh non-bare one.
    let mut repo = if dest.join(".git").exists() {
        gix::open(dest).with_context(|| format!("gix::open {}", dest.display()))?
    } else {
        std::fs::create_dir_all(dest).with_context(|| format!("create {}", dest.display()))?;
        gix::init(dest).with_context(|| format!("gix::init {}", dest.display()))?
    };
    // A freshly init'd repo has no user identity; gix needs a committer to write
    // reflogs for the fetched ref updates (and our HEAD update below). Inject the
    // generic in-memory fallback so those succeed without ambient git config.
    let _ = repo.committer_or_set_generic_fallback();

    // 3. Fetch the pack over the russh channel. gix's blocking fetch runs on
    //    THIS thread; the upload-pack runtime's workers handle the socket I/O.
    let mut up = crate::ssh::connect_upload_pack(&loc, key_path)
        .with_context(|| format!("ssh upload-pack {url}"))?;
    let transport = GitConnection::new(
        &mut up.reader,
        &mut up.writer,
        Protocol::V2,
        loc.path.clone(),
        Option::<(String, Option<u16>)>::None,
        ConnectMode::Process,
        false,
    );
    let remote = repo
        .remote_at(url)
        .context("build in-memory remote")?
        .with_refspecs(
            [
                "+refs/heads/*:refs/remotes/origin/*",
                // Tags too — release tags drive the viz git-history fallback.
                "+refs/tags/*:refs/tags/*",
            ],
            gix::remote::Direction::Fetch,
        )
        .context("set fetch refspecs")?;
    remote
        .to_connection_with_transport(transport)
        .prepare_fetch(gix::progress::Discard, Default::default())
        .context("prepare ssh fetch")?
        .receive(gix::progress::Discard, &gix::interrupt::IS_INTERRUPTED)
        .context("ssh fetch (pack transfer)")?;
    drop(up); // close the ssh channel before touching the worktree

    // 4. Point HEAD at the fetched commit and materialize the worktree.
    set_head(&repo, &branch, &head_sha)?;
    materialize_worktree(&repo, &head_sha, dest)
        .with_context(|| format!("checkout {head_sha} into {}", dest.display()))?;
    eprintln!("nornir-ssh: {url} synced {head_sha} → {}", dest.display());
    Ok(head_sha)
}

/// Point an existing clone at `branch` (→ commit `sha`) and materialize its
/// worktree from that commit. Pure-gix (no shell-out): updates `refs/heads/
/// <branch>` + `HEAD`, then writes the tree onto disk. `branch` is the SHORT
/// name (e.g. `main`); `sha` its peeled commit. Used by the fat auto-materialize
/// path to honor a member's pinned `branch` after a default-HEAD clone.
pub fn set_head_and_checkout(dest: &Path, branch: &str, sha: &str) -> Result<()> {
    let repo = gix::open(dest).with_context(|| format!("gix::open {}", dest.display()))?;
    let full = format!("refs/heads/{branch}");
    set_head(&repo, &full, sha)?;
    materialize_worktree(&repo, sha, dest)
        .with_context(|| format!("checkout {sha} into {}", dest.display()))
}

/// Create/update `branch` → `sha` (a direct ref) and point `HEAD` at `branch`.
fn set_head(repo: &gix::Repository, branch: &str, sha: &str) -> Result<()> {
    use gix::refs::transaction::{Change, LogChange, PreviousValue, RefEdit, RefLog};
    use gix::refs::{FullName, Target};

    let oid = gix::ObjectId::from_hex(sha.as_bytes()).with_context(|| format!("parse sha {sha}"))?;
    let branch_name: FullName = branch
        .try_into()
        .map_err(|e| anyhow!("invalid branch ref `{branch}`: {e}"))?;
    let log = LogChange {
        mode: RefLog::AndReference,
        force_create_reflog: false,
        message: "nornir: ssh fetch".into(),
    };
    let edits = vec![
        RefEdit {
            change: Change::Update {
                log: log.clone(),
                expected: PreviousValue::Any,
                new: Target::Object(oid),
            },
            name: branch_name.clone(),
            deref: false,
        },
        RefEdit {
            change: Change::Update {
                log,
                expected: PreviousValue::Any,
                new: Target::Symbolic(branch_name),
            },
            name: "HEAD".try_into().expect("HEAD is a valid ref name"),
            deref: false,
        },
    ];
    repo.edit_references(edits).context("set HEAD + branch")?;
    Ok(())
}

/// Materialize the worktree at `dest` from the tree of commit `sha`, using only
/// public gix APIs (no `gix-worktree-state`): clear everything but `.git`, then
/// write each index blob. Handles regular/executable files and symlinks; skips
/// submodule gitlinks. Sufficient for the read-only scans the monitor runs.
fn materialize_worktree(repo: &gix::Repository, sha: &str, dest: &Path) -> Result<()> {
    use gix::index::entry::Mode;

    let oid = gix::ObjectId::from_hex(sha.as_bytes()).with_context(|| format!("parse sha {sha}"))?;
    let tree_id = repo
        .find_commit(oid)
        .with_context(|| format!("find commit {sha}"))?
        .tree_id()
        .context("commit tree")?
        .detach();
    let index = repo
        .index_from_tree(&tree_id)
        .with_context(|| format!("index from tree {tree_id}"))?;

    // Clear the worktree (keep `.git`) so deletions upstream are reflected.
    for entry in std::fs::read_dir(dest).with_context(|| format!("read {}", dest.display()))? {
        let path = entry?.path();
        if path.file_name().map(|n| n == ".git").unwrap_or(false) {
            continue;
        }
        if path.is_dir() {
            std::fs::remove_dir_all(&path).ok();
        } else {
            std::fs::remove_file(&path).ok();
        }
    }

    for entry in index.entries() {
        if entry.mode == Mode::COMMIT {
            continue; // submodule gitlink — no blob to write
        }
        let rel = gix::path::from_bstr(entry.path(&index));
        let full = dest.join(rel.as_ref());
        if let Some(parent) = full.parent() {
            std::fs::create_dir_all(parent)
                .with_context(|| format!("mkdir {}", parent.display()))?;
        }
        let blob = repo
            .find_object(entry.id)
            .with_context(|| format!("blob {} for {}", entry.id, full.display()))?;

        if entry.mode == Mode::SYMLINK {
            #[cfg(unix)]
            {
                use std::os::unix::ffi::OsStrExt;
                let target = std::ffi::OsStr::from_bytes(&blob.data);
                std::fs::remove_file(&full).ok();
                std::os::unix::fs::symlink(target, &full)
                    .with_context(|| format!("symlink {}", full.display()))?;
            }
            #[cfg(not(unix))]
            std::fs::write(&full, &blob.data).with_context(|| format!("write {}", full.display()))?;
        } else {
            std::fs::write(&full, &blob.data).with_context(|| format!("write {}", full.display()))?;
            #[cfg(unix)]
            if entry.mode == Mode::FILE_EXECUTABLE {
                use std::os::unix::fs::PermissionsExt;
                std::fs::set_permissions(&full, std::fs::Permissions::from_mode(0o755)).ok();
            }
        }
    }
    Ok(())
}

/// Ensure `dest` is an up-to-date clone of `url`: clone if absent, else fetch.
/// Returns the resulting `HEAD` SHA. SSH remotes use the deploy key at
/// `ssh_key` (resolved via [`nornir_ssh_key_path`] when `None`).
pub fn clone_or_fetch(url: &str, dest: &Path, ssh_key: Option<&Path>) -> Result<String> {
    // nornir fetches over SSH ONLY — the https transport is unsupported. Coerce
    // any `http(s)://host/owner/repo` remote to its scp-like SSH form
    // (`git@host:owner/repo.git`) up front, so a deploy key drives every fetch (no
    // credential prompt, no broken-https path). Non-http remotes (local paths,
    // already-SSH URLs) are returned unchanged by `https_to_ssh`, so they pass
    // through. This makes "ssh always" hold regardless of what a descriptor wrote.
    let coerced = https_to_ssh(url);
    let url: &str = coerced.as_deref().unwrap_or(url);
    if is_ssh_url(url) {
        let resolved;
        let key = match ssh_key {
            Some(k) => k,
            None => {
                resolved = nornir_ssh_key_path().ok_or_else(|| {
                    anyhow!(
                        "SSH remote `{url}` needs a deploy key, but none was found \
                         (set NORNIR_SSH_DIR or install the service so the key lives \
                         at /home/nornir/.ssh/id_ed25519 — see `nornir key show`)"
                    )
                })?;
                resolved.as_path()
            }
        };
        return ssh_sync(url, dest, key);
    }
    // SSH-FIRST: an `https://` remote prompts for credentials on a private repo,
    // which is fatal headless (the server has no tty). Most of our remotes ARE
    // private and reachable via the deploy key, so for a FRESH clone try the
    // scp-like SSH form first and fall back to the original https URL only if
    // SSH fails (e.g. a public host we hold no key for). Existing checkouts just
    // fetch through their stored remote.
    if !dest.join(".git").exists() {
        let key = ssh_key.map(|k| k.to_path_buf()).or_else(nornir_ssh_key_path);
        if let (Some(ssh_url), Some(key)) = (https_to_ssh(url), key.as_ref()) {
            match ssh_sync(&ssh_url, dest, key) {
                Ok(sha) => return Ok(sha),
                Err(e) => {
                    eprintln!(
                        "nornir-gitio: SSH-first clone of `{ssh_url}` failed ({e:#}); \
                         falling back to `{url}`"
                    );
                    // ssh_sync may have left a partial dir — clear it so the https
                    // clone starts clean.
                    if !dest.join(".git").exists() {
                        let _ = std::fs::remove_dir_all(dest);
                    }
                }
            }
        }
    }
    if dest.join(".git").exists() {
        fetch_repo(dest)?;
    } else {
        clone_repo(url, dest)?;
    }
    head_sha(dest)
}

/// Outcome of a [`push_to_local_remote`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LocalPushReport {
    /// The commit SHA the remote branch now points at (the pushed head).
    pub sha: String,
    /// The branch that was updated on the remote.
    pub branch: String,
    /// `true` when the remote branch did not exist before (a create, not an update).
    pub created: bool,
}

/// **Fast-forward PUSH to a LOCAL/file git remote, pure-Rust (no send-pack).**
///
/// gix (0.84) implements fetch but not the send-pack side of the git wire
/// protocol, so an over-the-network push is impossible without a `git`
/// subprocess or libgit2 (both forbidden). For a LOCAL/file remote we don't need
/// the wire protocol at all: the object database is content-addressed loose/pack
/// files on a filesystem we can already read. So we (1) union-copy `src`'s
/// `.git/objects` into `remote`'s (idempotent — identical content hashes), then
/// (2) fast-forward `remote`'s `refs/heads/<branch>` to `src`'s HEAD. The ref is
/// updated LAST (after all objects land), so a failed copy never leaves a ref
/// pointing at absent objects — atomic-ish.
///
/// FAIL-CLEAN on non-fast-forward: if the remote branch already exists and its
/// commit is NOT an ancestor of `src`'s HEAD (the remote advanced independently),
/// we return an error and touch nothing — never clobber. Over-the-network
/// remotes (`ssh://` / `git@…` / `http(s)://`) return an error (unsupported).
pub fn push_to_local_remote(src: &Path, remote: &str) -> Result<LocalPushReport> {
    // Only local/file remotes: no send-pack for network transports.
    let remote = remote.strip_prefix("file://").unwrap_or(remote);
    if is_ssh_url(remote) || remote.starts_with("http://") || remote.starts_with("https://") {
        bail!(
            "in-process push is only supported for LOCAL/file git remotes — gix (0.84) has no \
             send-pack for `{remote}`. Push the warehouse mirror out-of-band, or use a local remote."
        );
    }
    let remote_path = Path::new(remote);
    if !remote_path.exists() {
        bail!("remote warehouse path `{remote}` does not exist (open the remote warehouse first)");
    }

    let src_repo = gix::open(src).with_context(|| format!("gix::open src {}", src.display()))?;
    let mut remote_repo =
        gix::open(remote_path).with_context(|| format!("gix::open remote {remote}"))?;
    // The remote warehouse repo has no ambient git identity; give it a generic
    // committer fallback so appending to an existing reflog on the ref update
    // below doesn't fail ("reflog messages need a committer"). Same call
    // `set_head_and_checkout` / gitclean make before their ref edits.
    let _ = remote_repo.committer_or_set_generic_fallback();

    let branch = head_branch(src)?;
    let new_sha = head_sha(src)?;
    let new_oid =
        gix::ObjectId::from_hex(new_sha.as_bytes()).with_context(|| format!("parse {new_sha}"))?;
    let full = format!("refs/heads/{branch}");

    // Current remote head for this branch (None = the branch is new).
    let old_oid: Option<gix::ObjectId> = remote_repo
        .try_find_reference(full.as_str())
        .with_context(|| format!("look up {full} on remote"))?
        .map(|r| r.into_fully_peeled_id().map(|id| id.detach()))
        .transpose()
        .with_context(|| format!("peel {full} on remote"))?;

    // Fast-forward guard: the remote head must be an ancestor of what we push.
    if let Some(old) = old_oid {
        if old != new_oid && !is_ancestor(&src_repo, old, new_oid) {
            bail!(
                "non-fast-forward push to `{remote}`: remote `{branch}` is at {old} which is not an \
                 ancestor of {new_sha} — the remote advanced. Re-open (fetch) the remote warehouse \
                 to reconcile before pushing; refusing to clobber."
            );
        }
    }

    // (1) Transfer objects: union-copy src's object DB into the remote's.
    copy_objects_union(&src.join(".git/objects"), &remote_path.join(".git/objects"))
        .context("transfer git objects to remote")?;

    // (2) Fast-forward the remote branch ref (guarded on the observed previous
    // value for atomicity — a concurrent change fails the transaction).
    update_remote_branch(&remote_repo, &full, new_oid, old_oid)
        .with_context(|| format!("fast-forward {full} on remote"))?;

    Ok(LocalPushReport { sha: new_sha, branch, created: old_oid.is_none() })
}

/// Is `ancestor` reachable from `tip` (i.e. an ancestor of, or equal to, `tip`)
/// within `repo`? Walks `tip`'s first-parent-and-merges history. A missing
/// `ancestor` object (remote commit the src never saw) yields `false` → the
/// caller treats it as a non-fast-forward.
fn is_ancestor(repo: &gix::Repository, ancestor: gix::ObjectId, tip: gix::ObjectId) -> bool {
    if ancestor == tip {
        return true;
    }
    let Ok(walk) = repo.rev_walk(Some(tip)).all() else {
        return false;
    };
    for info in walk {
        match info {
            Ok(info) if info.id == ancestor => return true,
            Ok(_) => {}
            Err(_) => return false,
        }
    }
    false
}

/// Update (or create) a direct branch ref on `repo` to `new`, guarding on the
/// previously-observed value `prev` (`None` ⇒ must-not-exist create) so a
/// concurrent writer can't be silently clobbered.
fn update_remote_branch(
    repo: &gix::Repository,
    full: &str,
    new: gix::ObjectId,
    prev: Option<gix::ObjectId>,
) -> Result<()> {
    use gix::refs::transaction::{Change, LogChange, PreviousValue, RefEdit, RefLog};
    use gix::refs::{FullName, Target};

    let name: FullName = full.try_into().map_err(|e| anyhow!("invalid ref `{full}`: {e}"))?;
    let expected = match prev {
        Some(old) => PreviousValue::MustExistAndMatch(Target::Object(old)),
        None => PreviousValue::MustNotExist,
    };
    let edit = RefEdit {
        change: Change::Update {
            log: LogChange {
                mode: RefLog::AndReference,
                force_create_reflog: false,
                message: "nornir: warehouse republish (push)".into(),
            },
            expected,
            new: Target::Object(new),
        },
        name,
        deref: false,
    };
    repo.edit_references(vec![edit]).context("edit remote branch ref")?;
    Ok(())
}

/// Recursively copy every object file under `src_objects` into `dst_objects`,
/// skipping any that already exist (git objects are content-addressed, so an
/// existing file is byte-identical). Creates parent dirs as needed. Skips the
/// transient `objects/info` housekeeping dir.
fn copy_objects_union(src_objects: &Path, dst_objects: &Path) -> Result<()> {
    let mut stack = vec![src_objects.to_path_buf()];
    while let Some(dir) = stack.pop() {
        let Ok(entries) = std::fs::read_dir(&dir) else { continue };
        for e in entries.flatten() {
            let p = e.path();
            let is_dir = e.file_type().map(|t| t.is_dir()).unwrap_or(false);
            let rel = p.strip_prefix(src_objects).unwrap_or(&p);
            if is_dir {
                // `objects/info` holds no immutable objects — skip it.
                if rel == Path::new("info") {
                    continue;
                }
                stack.push(p);
                continue;
            }
            let dst = dst_objects.join(rel);
            if dst.exists() {
                continue; // content-addressed ⇒ identical, don't recopy
            }
            if let Some(parent) = dst.parent() {
                std::fs::create_dir_all(parent)
                    .with_context(|| format!("mkdir {}", parent.display()))?;
            }
            std::fs::copy(&p, &dst)
                .with_context(|| format!("copy {} → {}", p.display(), dst.display()))?;
        }
    }
    Ok(())
}

/// Rewrite an `https://host/owner/repo(.git)` (or `http://`) URL to its scp-like
/// SSH form `git@host:owner/repo.git`. Returns `None` when `url` isn't a plain
/// http(s) URL with both a host and a path we can rewrite. Used to prefer SSH
/// (deploy-key, no credential prompt) over https for private remotes.
pub fn https_to_ssh(url: &str) -> Option<String> {
    let rest = url.strip_prefix("https://").or_else(|| url.strip_prefix("http://"))?;
    let (host, path) = rest.split_once('/')?;
    let host = host.trim();
    let path = path.trim().trim_matches('/');
    if host.is_empty() || path.is_empty() {
        return None;
    }
    let path = path.strip_suffix(".git").unwrap_or(path);
    Some(format!("git@{host}:{path}.git"))
}

/// Recursively upsert every file under `dir` into `editor`, keyed by its
/// path relative to `repo_root`. Skips the `.git` directory.
fn add_dir_recursive(
    repo: &gix::Repository,
    editor: &mut gix::object::tree::Editor<'_>,
    repo_root: &Path,
    dir: &Path,
) -> Result<()> {
    use gix::object::tree::EntryKind;

    let mut entries: Vec<_> = std::fs::read_dir(dir)
        .with_context(|| format!("read_dir {}", dir.display()))?
        .collect::<std::io::Result<Vec<_>>>()
        .with_context(|| format!("iterate {}", dir.display()))?;
    // Deterministic order keeps generated history reproducible.
    entries.sort_by_key(|e| e.file_name());

    for entry in entries {
        let path = entry.path();
        let name = entry.file_name();
        if name == ".git" {
            continue;
        }
        let meta = std::fs::symlink_metadata(&path)
            .with_context(|| format!("stat {}", path.display()))?;
        let ft = meta.file_type();
        if ft.is_dir() {
            add_dir_recursive(repo, editor, repo_root, &path)?;
            continue;
        }
        let rela = path
            .strip_prefix(repo_root)
            .expect("path is under repo_root");
        let rela = gix::path::into_bstr(rela).into_owned();

        let (bytes, kind): (Vec<u8>, EntryKind) = if ft.is_symlink() {
            let target = std::fs::read_link(&path)
                .with_context(|| format!("readlink {}", path.display()))?;
            (gix::path::into_bstr(target).into_owned().into(), EntryKind::Link)
        } else {
            let bytes = std::fs::read(&path).with_context(|| format!("read {}", path.display()))?;
            #[cfg(unix)]
            let kind = {
                use std::os::unix::fs::PermissionsExt;
                if meta.permissions().mode() & 0o111 != 0 {
                    EntryKind::BlobExecutable
                } else {
                    EntryKind::Blob
                }
            };
            #[cfg(not(unix))]
            let kind = EntryKind::Blob;
            (bytes, kind)
        };

        let blob = repo.write_blob(&bytes).context("write blob")?;
        editor
            .upsert(rela.as_ref() as &gix::bstr::BStr, kind, blob.detach())
            .with_context(|| format!("tree upsert {rela}"))?;
    }
    Ok(())
}

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

    /// LAW (inject-assert): feed real https URLs and assert the EXACT scp-like
    /// SSH form, the host/owner/repo round-trip, idempotent `.git`, trailing-slash
    /// trim — and that the rewritten URL is recognised as SSH by `is_ssh_url`.
    #[test]
    fn https_rewrites_to_scp_like_ssh_and_is_recognised() {
        let cases = [
            ("https://codeberg.org/nordisk/korp", "git@codeberg.org:nordisk/korp.git"),
            ("https://codeberg.org/nordisk/ordning.git", "git@codeberg.org:nordisk/ordning.git"),
            ("https://codeberg.org/nordisk/knut/", "git@codeberg.org:nordisk/knut.git"),
            ("http://github.com/rustsec/advisory-db", "git@github.com:rustsec/advisory-db.git"),
        ];
        for (https, want) in cases {
            let got = https_to_ssh(https).unwrap_or_else(|| panic!("no rewrite for {https}"));
            assert_eq!(got, want, "rewrite of {https}");
            assert!(is_ssh_url(&got), "rewritten `{got}` must be SSH-shaped");
        }
    }

    /// Non-rewritable inputs return None (so `clone_or_fetch` leaves them alone):
    /// already-SSH, scheme-less, and host-only URLs.
    #[test]
    fn non_https_or_pathless_urls_do_not_rewrite() {
        for url in [
            "git@codeberg.org:nordisk/korp.git", // already SSH
            "ssh://git@host/owner/repo.git",     // already SSH scheme
            "https://codeberg.org",              // host only, no path
            "https://codeberg.org/",             // empty path
            "/local/path/repo",                  // not a url
        ] {
            assert!(https_to_ssh(url).is_none(), "{url} must not rewrite");
        }
    }

    /// The private-sibling clone base is SSH by default (no https credential
    /// prompt), and `<base>/<repo>` is a valid SSH remote.
    #[test]
    fn dep_clone_base_default_is_ssh() {
        // Only assert the default when the env override is absent.
        if std::env::var("NORNIR_DEP_CLONE_BASE").is_err() {
            // The dep-clone base default lives in nornir's `security` module; the
            // standalone crate hard-codes the known default so the test stays
            // dependency-free (nornir asserts the real value on its side).
            let base = "git@codeberg.org:nordisk";
            assert!(is_ssh_url(&format!("{base}/nornir-orch")), "`{base}/repo` must be SSH");
        }
    }
}

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

    fn seed(root: &Path, body: &str) -> String {
        init(root).unwrap();
        std::fs::write(root.join("data.txt"), body).unwrap();
        commit_all(root, "seed").unwrap()
    }

    /// Happy path: clone a local remote, add a commit on the clone, push it back
    /// over the pure-Rust local transport — the remote branch fast-forwards and a
    /// fresh clone sees the new file.
    #[test]
    fn push_local_fast_forwards_and_a_fresh_clone_sees_it() {
        let td = tempfile::tempdir().unwrap();
        let remote = td.path().join("remote");
        seed(&remote, "v1\n");

        // Clone it, then add a new commit on the clone.
        let src = td.path().join("clone");
        clone_or_fetch(remote.to_str().unwrap(), &src, None).unwrap();
        std::fs::write(src.join("data.txt"), "v2\n").unwrap();
        let new_sha = commit_all(&src, "v2").unwrap();

        // Push back over the local transport.
        let report = push_to_local_remote(&src, remote.to_str().unwrap()).unwrap();
        assert_eq!(report.sha, new_sha, "remote branch now at the pushed commit");
        assert!(!report.created, "the branch already existed → fast-forward update");

        // The remote branch ref advanced, and a fresh clone reads the new content.
        assert_eq!(head_sha(&remote).unwrap(), new_sha, "remote HEAD ref fast-forwarded");
        let fresh = td.path().join("fresh");
        clone_or_fetch(remote.to_str().unwrap(), &fresh, None).unwrap();
        assert_eq!(std::fs::read_to_string(fresh.join("data.txt")).unwrap(), "v2\n");
    }

    /// FAIL-CLEAN on non-fast-forward: the remote advanced independently, so the
    /// clone's push is refused and the remote is NOT clobbered.
    #[test]
    fn push_local_refuses_non_fast_forward() {
        let td = tempfile::tempdir().unwrap();
        let remote = td.path().join("remote");
        seed(&remote, "v1\n");

        let src = td.path().join("clone");
        clone_or_fetch(remote.to_str().unwrap(), &src, None).unwrap();

        // Diverge: a new commit on the clone AND an independent new commit on the
        // remote (both children of v1) — a classic non-ff.
        std::fs::write(src.join("data.txt"), "clone-side\n").unwrap();
        commit_all(&src, "clone edit").unwrap();
        std::fs::write(remote.join("data.txt"), "remote-side\n").unwrap();
        let remote_sha = commit_all(&remote, "remote edit").unwrap();

        let err = push_to_local_remote(&src, remote.to_str().unwrap()).unwrap_err().to_string();
        assert!(err.contains("non-fast-forward"), "clear non-ff error: {err}");
        // The remote was NOT clobbered — still at its own commit.
        assert_eq!(head_sha(&remote).unwrap(), remote_sha, "remote ref untouched on non-ff");
    }

    /// Over-the-network remotes are rejected cleanly (gix has no send-pack).
    #[test]
    fn push_local_rejects_network_remotes() {
        let td = tempfile::tempdir().unwrap();
        let src = td.path().join("clone");
        seed(&src, "v1\n");
        for url in ["https://codeberg.org/nordisk/warehouse.git", "git@codeberg.org:nordisk/warehouse.git"] {
            let err = push_to_local_remote(&src, url).unwrap_err().to_string();
            assert!(err.contains("LOCAL/file"), "network remote rejected with a clear reason: {err}");
        }
    }
}

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

    /// Build a one-file repo with a committed `README.md`. Returns the temp dir
    /// (kept alive by the caller) and the repo root.
    fn fixture() -> (tempfile::TempDir, PathBuf) {
        let td = tempfile::tempdir().expect("tempdir");
        let root = td.path().to_path_buf();
        init(&root).expect("git init");
        std::fs::write(root.join("README.md"), b"hello\n").expect("write README");
        commit_all(&root, "initial").expect("commit");
        (td, root)
    }

    /// LAW 1 (inject-assert): feed a real repo, compute the digest CLEAN; then
    /// modify the working tree and assert (a) the digest CHANGES, (b) clean→dirty
    /// flips, and (c) the HEAD SHA does NOT move — the whole reason a SHA cannot
    /// stand in for a working-tree digest.
    #[test]
    fn worktree_edit_changes_digest_and_dirty_but_not_head_sha() {
        let (_td, root) = fixture();

        // Freshly committed → clean, sentinel digest.
        let clean = worktree_freshness(&root).expect("freshness clean");
        assert!(!clean.dirty, "freshly committed tree must read clean");
        assert_eq!(clean.digest, CLEAN_WORKTREE_DIGEST, "clean ⇒ sentinel digest");
        let sha_before = head_sha(&root).expect("head sha before");

        // Inject a tracked modification (edit the committed file in place).
        std::fs::write(root.join("README.md"), b"hello, dirty world\n").expect("modify");
        let modified = worktree_freshness(&root).expect("freshness after modify");
        assert!(modified.dirty, "an uncommitted edit must read dirty");
        assert_ne!(modified.digest, clean.digest, "edit must CHANGE the digest");
        assert_ne!(modified.digest, CLEAN_WORKTREE_DIGEST, "dirty ⇒ not the sentinel");

        // THE POINT: HEAD did NOT move — the SHA cannot see the uncommitted edit.
        let sha_after = head_sha(&root).expect("head sha after");
        assert_eq!(
            sha_before, sha_after,
            "editing the working tree must NOT change HEAD — so the SHA cannot \
             detect staleness; only the digest can"
        );

        // Inject an untracked file → digest changes again, still dirty.
        std::fs::write(root.join("NEW.txt"), b"brand new\n").expect("add untracked");
        let added = worktree_freshness(&root).expect("freshness after add");
        assert!(added.dirty, "an untracked file must read dirty");
        assert_ne!(added.digest, modified.digest, "adding a file must CHANGE the digest again");
        assert_eq!(head_sha(&root).expect("head sha"), sha_before, "still no HEAD movement");
    }

    /// A clean tree's digest is stable across reopens — two reads of the same
    /// untouched checkout agree (so a thin client comparing to the indexed
    /// digest never reports a false "stale").
    #[test]
    fn clean_digest_is_stable_and_matches_sentinel() {
        let (_td, root) = fixture();
        let a = worktree_freshness(&root).expect("a");
        let b = worktree_freshness(&root).expect("b");
        assert_eq!(a, b, "two reads of an untouched tree must agree");
        assert_eq!(a.digest, CLEAN_WORKTREE_DIGEST);
        assert!(!a.dirty);
    }
}