//! PR-based config-flow merge primitives — the forge-side mechanics //! hive-c0re's approve-handler (`run_merge_config_pr`) orchestrates to //! land an operator-approved config PR. Part of the operator trust //! boundary; moved verbatim from the `forge` module root. use anyhow::Context; use forgejo_api::ForgejoError; use forgejo_api::structs::{MergePullRequestOption, MergePullRequestOptionDo, StateType}; use super::{CONFIG_ORG, api, core_token, forge_git_url}; // --------------------------------------------------------------------------- // PR-based config-flow merge primitives (part of the // dashboard-approve-driven config-change flow). // // The dashboard-approve-driven flow has hive-c0re verify an operator-approved // config PR, then land it: ff-push the verified sha to the protected default // branch (= the merge) and mark the PR merged manually. These three fns are // the forge-side mechanics the c0re approve-handler (`run_merge_config_pr`) // orchestrates; the orchestration fetches the verified sha into the agent's // applied repo before calling `ff_push_to_main`. The core token is sourced // internally (`core_token`), never passed in. `repo` is the agent's editable // forge config repo in `owner/name` form (e.g. `agent-configs/`). // --------------------------------------------------------------------------- /// Typed failure for the merge primitives so the c0re approve-handler can /// `match` recoverable drift (refresh the request sha + re-verify) against a /// hard failure (fail the approval). The two drift variants carry the observed /// sha so the handler can re-pin to it; `Other` is everything else (transport, /// API, unexpected) and is not auto-retried. #[derive(Debug)] pub enum ForgeMergeError { /// The PR head moved off `expected` (now at `actual`), seen at /// mark-merged time. The handler's pre-merge `pr_head_sha` re-read is the /// primary drift gate; this is the belt-and-suspenders race catch. HeadDrift { expected: String, actual: String }, /// `main` (`actual_head`) is not a descendant of `expected_ancestor`, so /// pushing the verified sha would not be a fast-forward — `main` raced. NotFastForward { expected_ancestor: String, actual_head: String, }, /// Transport / API / unexpected failure — hard-fail, no auto-retry. Other(anyhow::Error), } impl std::fmt::Display for ForgeMergeError { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { Self::HeadDrift { expected, actual } => { write!(f, "PR head drifted: expected {expected}, found {actual}") } Self::NotFastForward { expected_ancestor, actual_head, } => write!( f, "not a fast-forward: main {actual_head} is not a descendant of {expected_ancestor}" ), Self::Other(e) => write!(f, "{e}"), } } } impl std::error::Error for ForgeMergeError {} impl From for ForgeMergeError { fn from(e: anyhow::Error) -> Self { Self::Other(e) } } /// Agent name from an `owner/name` forge repo string (the trailing segment). fn repo_agent_name(repo: &str) -> &str { repo.rsplit('/').next().unwrap_or(repo) } /// Resolve a PR's head sha via `git ls-remote refs/pull//head` /// (Forgejo exposes PR heads there). Pure read, no mutation — the handler's /// primary drift gate (compare against the approved sha), and `mark_pr_merged` /// uses it to detect head-drift on failure. /// /// # Errors /// `Other` on transport failure or an empty/missing ref. pub async fn pr_head_sha(repo: &str, pr: u64) -> Result { let token = core_token() .ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?; let url = forge_git_url(&token, repo); let refspec = format!("refs/pull/{pr}/head"); let out = crate::lifecycle::git_command() .args(["ls-remote", &url, &refspec]) .output() .await .context("git ls-remote PR head")?; if !out.status.success() { return Err(ForgeMergeError::Other(anyhow::anyhow!( "git ls-remote {repo} {refspec} failed ({}): {}", out.status, String::from_utf8_lossy(&out.stderr).trim() ))); } let stdout = String::from_utf8_lossy(&out.stdout); let sha = stdout .split_whitespace() .next() .filter(|s| !s.is_empty()) .ok_or_else(|| { ForgeMergeError::Other(anyhow::anyhow!( "no head ref for PR #{pr} in {repo} (ls-remote empty)" )) })?; Ok(sha.to_string()) } /// Check whether PR `pr` on `repo` is still open. Returns `Ok(true)` if /// open, `Ok(false)` if closed or merged, or an error on transport failure. /// /// Called at submission time to give an early, actionable error rather than /// queuing an approval card that will fail later in the approve handler. /// /// # Errors /// `Other` on transport failure or a missing/malformed PR response. pub async fn pr_is_open(repo: &str, pr: u64) -> Result { let token = core_token() .ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?; let (owner, name) = repo.split_once('/').ok_or_else(|| { ForgeMergeError::Other(anyhow::anyhow!("forge repo `{repo}` is not owner/name")) })?; let index = i64::try_from(pr) .map_err(|_| ForgeMergeError::Other(anyhow::anyhow!("PR index {pr} overflows i64")))?; let client = api(&token).map_err(ForgeMergeError::Other)?; let pull = client .repo_get_pull_request(owner, name, index) .await .map_err(|e| ForgeMergeError::Other(anyhow::Error::from(e).context("GET pull request")))?; Ok(pull.state == Some(StateType::Open)) } /// Full `owner/name` path of an agent's config repo on the forge — the /// `agent-configs` org mirror that the PR-merge flow reads + fast-forwards. pub fn config_repo(agent: &str) -> String { format!("{CONFIG_ORG}/{agent}") } /// Fetch PR #`pr`'s head into the agent's applied repo via /// `refs/pull//head` (which Forgejo always serves — a bare-sha fetch can /// be refused by uploadpack policy). This makes the reviewed head an object /// in the applied repo so the ancestor check in [`ff_push_to_main`], the /// `git_update_ref(main, …)` in the deploy tail, and the eval-verify all /// resolve it locally before the irreversible push. /// /// # Errors /// `Other` on transport failure or a non-zero git exit. pub async fn fetch_pr_head_into_applied(repo: &str, pr: u64) -> Result<(), ForgeMergeError> { let token = core_token() .ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?; let url = forge_git_url(&token, repo); let applied = crate::paths::applied_dir(repo_agent_name(repo)); let refspec = format!("refs/pull/{pr}/head"); let out = crate::lifecycle::git_command() .current_dir(&applied) .args(["fetch", "--no-tags", &url, &refspec]) .output() .await .context("git fetch PR head into applied")?; if !out.status.success() { return Err(ForgeMergeError::Other(anyhow::anyhow!( "git fetch {repo} {refspec} into applied failed ({}): {}", out.status, String::from_utf8_lossy(&out.stderr).trim() ))); } Ok(()) } /// Fast-forward the forge repo's `main` to `sha` — THE merge in the PR flow. /// Reads `main`'s current sha (`git ls-remote … refs/heads/main`), verifies it /// is a strict ancestor of `sha` (`git merge-base --is-ancestor`, run in the /// agent's applied repo where the orchestration has already fetched `sha`), /// then does a **non-force** `git push :refs/heads/main`. The ancestor /// pre-check and the non-force push are two independent guards: either catches /// a raced `main` (→ `NotFastForward`) rather than clobbering reviewed history. /// /// # Errors /// `NotFastForward` if `main` raced ahead of `sha`; `Other` on transport/other. pub async fn ff_push_to_main(repo: &str, sha: &str) -> Result<(), ForgeMergeError> { let token = core_token() .ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?; let url = forge_git_url(&token, repo); let applied = crate::paths::applied_dir(repo_agent_name(repo)); // Current `main` on the forge repo. let ls = crate::lifecycle::git_command() .args(["ls-remote", &url, "refs/heads/main"]) .output() .await .context("git ls-remote main")?; if !ls.status.success() { return Err(ForgeMergeError::Other(anyhow::anyhow!( "git ls-remote {repo} refs/heads/main failed ({}): {}", ls.status, String::from_utf8_lossy(&ls.stderr).trim() ))); } let ls_out = String::from_utf8_lossy(&ls.stdout); let main_sha = ls_out.split_whitespace().next().unwrap_or("").to_string(); // Strict-ancestor check: `main` must be an ancestor of `sha` for a true // fast-forward. Skip when `main` is unborn (empty) — the push creates it. if !main_sha.is_empty() { let anc = crate::lifecycle::git_command() .current_dir(&applied) .args(["merge-base", "--is-ancestor", &main_sha, sha]) .output() .await .context("git merge-base --is-ancestor")?; match anc.status.code() { Some(0) => {} // ancestor → fast-forward safe Some(1) => { return Err(ForgeMergeError::NotFastForward { expected_ancestor: main_sha, actual_head: sha.to_string(), }); } _ => { return Err(ForgeMergeError::Other(anyhow::anyhow!( "git merge-base --is-ancestor errored ({}): {}", anc.status, String::from_utf8_lossy(&anc.stderr).trim() ))); } } } // Non-force push `sha` → `main`. Without `--force`, git rejects a // non-fast-forward (a race between the check above and now), surfaced as // `NotFastForward` rather than clobbering the remote. let push = crate::lifecycle::git_command() .current_dir(&applied) .args(["push", &url, &format!("{sha}:refs/heads/main")]) .output() .await .context("git push sha:main")?; if !push.status.success() { let stderr = String::from_utf8_lossy(&push.stderr); if stderr.contains("non-fast-forward") || stderr.contains("fetch first") { return Err(ForgeMergeError::NotFastForward { expected_ancestor: main_sha, actual_head: sha.to_string(), }); } return Err(ForgeMergeError::Other(anyhow::anyhow!( "git push {repo} {sha}:main failed ({}): {}", push.status, stderr.trim() ))); } Ok(()) } /// Mark PR `pr` as **manually merged** at `sha` (Forgejo /// `repo_merge_pull_request` with `Do=manually-merged`, `MergeCommitID=sha`). /// `ff_push_to_main` must have already set `main` to `sha` (Forgejo requires /// the branch already be at the merge commit). On an API rejection, re-reads /// the PR head to distinguish drift (`HeadDrift`) from a generic failure /// (`Other`) — best-effort, since the handler's pre-merge head re-read is /// the real gate. A transport failure skips the drift re-read (it couldn't /// reach the forge either) and surfaces as `Other` directly. /// /// # Errors /// `HeadDrift` if the PR head no longer matches `sha`; `Other` otherwise. pub async fn mark_pr_merged(repo: &str, pr: u64, sha: &str) -> Result<(), ForgeMergeError> { let token = core_token() .ok_or_else(|| ForgeMergeError::Other(anyhow::anyhow!("forge core token absent")))?; let (owner, name) = repo.split_once('/').ok_or_else(|| { ForgeMergeError::Other(anyhow::anyhow!("forge repo `{repo}` is not owner/name")) })?; let index = i64::try_from(pr) .map_err(|_| ForgeMergeError::Other(anyhow::anyhow!("PR index {pr} overflows i64")))?; let body = MergePullRequestOption { r#do: MergePullRequestOptionDo::ManuallyMerged, merge_commit_id: Some(sha.to_owned()), merge_message_field: None, merge_title_field: None, delete_branch_after_merge: None, force_merge: None, head_commit_id: None, merge_when_checks_succeed: None, }; let client = api(&token).map_err(ForgeMergeError::Other)?; match client .repo_merge_pull_request(owner, name, index, body) .await { Ok(()) => Ok(()), Err(ForgejoError::ReqwestError(e)) => Err(ForgeMergeError::Other( anyhow::Error::from(e).context("POST pulls//merge (manually-merged)"), )), Err(e) => { // Best-effort drift detection: if the live head no longer matches // `sha`, that's a head-drift race; otherwise surface as a hard // failure. match pr_head_sha(repo, pr).await { Ok(actual) if actual != sha => Err(ForgeMergeError::HeadDrift { expected: sha.to_string(), actual, }), _ => Err(ForgeMergeError::Other(anyhow::Error::from(e).context( format!("mark PR #{pr} in {repo} manually-merged at {sha}"), ))), } } } } #[cfg(test)] mod tests { use super::repo_agent_name; use crate::forge::forge_git_url; #[test] fn repo_agent_name_takes_trailing_segment() { assert_eq!(repo_agent_name("agent-configs/atlas"), "atlas"); assert_eq!(repo_agent_name("atlas"), "atlas"); assert_eq!(repo_agent_name("a/b/c"), "c"); } #[test] fn forge_git_url_shape() { // Credentials are inserted between scheme and authority; fallback // base is `http://localhost:3000` when HIVE_FORGE_URL is unset. let url = forge_git_url("tok", "agent-configs/iris"); assert!(url.contains("core:tok@"), "must embed credentials: {url}"); assert!( url.ends_with("/agent-configs/iris.git"), "must end with repo path: {url}" ); } }