heddle-cli 0.2.0

// SPDX-License-Identifier: Apache-2.0
use super::*;

#[derive(Debug, serde::Deserialize)]
struct RealworldRegistry {
    repo: Vec<RealworldRepo>,
}

#[derive(Debug, serde::Deserialize)]
struct RealworldRepo {
    name: String,
    source: String,
    fixture: String,
    commit: String,
    shape: Vec<String>,
}

/// Run heddle with the host PATH intact. The headline "operates
/// without git" claim covers clone/capture/checkpoint/push; fsck and
/// other diagnostic surfaces still shell out to `git` for metadata
/// reads (e.g. `git symbolic-ref` for the current branch) and need a
/// real binary on PATH.
fn heddle_with_host_git(args: &[&str], cwd: &std::path::Path) -> Result<String, String> {
    super::heddle(args, Some(cwd))
}

fn heddle_without_git(args: &[&str], cwd: &std::path::Path) -> Result<String, String> {
    let output = heddle_output_with_env(args, Some(cwd), &[("PATH", "")])?;
    let stdout = str::from_utf8(&output.stdout).unwrap_or("").to_string();
    let stderr = str::from_utf8(&output.stderr).unwrap_or("").to_string();
    if output.status.success() {
        Ok(stdout)
    } else {
        Err(format!(
            "Exit code: {:?}\nstdout: {}\nstderr: {}",
            output.status.code(),
            stdout,
            stderr
        ))
    }
}

fn registry() -> RealworldRegistry {
    let raw = include_str!("../realworld_git/realworld_repos.toml");
    toml::from_str(raw).expect("realworld repo registry should parse")
}

/// Untar a vendored real-world fixture into a fresh `TempDir` and return
/// `(temp_dir, bare_repo_path)`. The temp dir owns the extracted tree;
/// hold onto it for the lifetime of the test or the bare repo vanishes.
///
/// Asserts that the extracted tip OID matches the registry pin so a
/// re-vendored tarball that didn't update `realworld_repos.toml` fails
/// fast rather than silently testing against drifted state.
fn extract_fixture(name: &str) -> (TempDir, std::path::PathBuf) {
    let registry = registry();
    let entry = registry
        .repo
        .iter()
        .find(|r| r.name == name)
        .unwrap_or_else(|| panic!("registry missing fixture: {name}"));
    let manifest_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    let tarball = manifest_dir
        .join("tests")
        .join("realworld_git")
        .join(&entry.fixture);
    assert!(
        tarball.exists(),
        "vendored fixture missing: {} (run `crates/cli/tests/realworld_git/fixtures/vendor.sh`)",
        tarball.display()
    );
    let temp = TempDir::new().expect("temp dir for fixture extract");
    let status = std::process::Command::new("tar")
        .args(["xzf", tarball.to_str().unwrap()])
        .current_dir(temp.path())
        .status()
        .expect("tar invocation");
    assert!(status.success(), "tar xzf failed for {}", tarball.display());
    let bare = temp.path().join(name);
    assert!(
        bare.join("HEAD").exists(),
        "bare repo missing HEAD after extract: {}",
        bare.display()
    );
    let extracted = gix::open(&bare).expect("open extracted bare repo");
    let head = extracted
        .head_commit()
        .expect("extracted fixture should resolve HEAD");
    assert_eq!(
        head.id().to_string(),
        entry.commit,
        "fixture {name} drifted: registry pinned {} but extracted tip is {}",
        entry.commit,
        head.id()
    );
    (temp, bare)
}

fn git_tree_with_file(repo: &gix::Repository, path: &str, content: &[u8]) -> gix::hash::ObjectId {
    let blob = repo.write_blob(content).expect("write git blob").detach();
    let empty = git_empty_tree_oid(repo);
    let mut editor = repo.edit_tree(empty).expect("edit git tree");
    editor
        .upsert(path, gix::object::tree::EntryKind::Blob, blob)
        .expect("add file to git tree");
    editor.write().expect("write git tree").detach()
}

#[test]
fn realworld_git_fixture_registry_is_parseable_and_pinned() {
    let registry = registry();
    assert_eq!(registry.repo.len(), 4);
    let manifest_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    for repo in registry.repo {
        assert!(!repo.name.is_empty(), "registry entries need stable names");
        assert!(
            repo.fixture.starts_with("fixtures/") && repo.fixture.ends_with(".tar.gz"),
            "fixture should be a vendored tarball under fixtures/: {repo:?}"
        );
        // Commit must be a 40-char lowercase hex SHA-1: real public-repo
        // pin, no more synthetic placeholders.
        assert_eq!(
            repo.commit.len(),
            40,
            "fixture commit pin must be a real 40-char SHA-1: {repo:?}"
        );
        assert!(
            repo.commit
                .chars()
                .all(|c| matches!(c, '0'..='9' | 'a'..='f')),
            "fixture commit pin must be lowercase hex: {repo:?}"
        );
        assert!(
            repo.source.starts_with("https://github.com/"),
            "source should document the public repo: {repo:?}"
        );
        assert!(!repo.shape.is_empty(), "shape tags drive matrix coverage");
        let tarball = manifest_dir
            .join("tests")
            .join("realworld_git")
            .join(&repo.fixture);
        assert!(
            tarball.exists(),
            "registry references missing tarball: {} (run vendor.sh to create)",
            tarball.display()
        );
    }
}

#[test]
#[ignore = "nightly real-world matrix: generates complex overlay fixtures"]
fn realworld_git_complex_fixture_round_trips_overlay_inventory_without_git_on_path() {
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init synthetic real-world origin");

    let base_tree = git_tree_with_file(&origin_repo, "core.rs", b"pub fn base() {}\n");
    let base = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        base_tree,
        "base",
        &[],
    );
    git_set_reference(&origin_repo, "HEAD", base);

    let feature_tree = git_tree_with_file(
        &origin_repo,
        "core.rs",
        b"pub fn base() {}\npub fn feature() {}\n",
    );
    let feature = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/feature/parser"),
        feature_tree,
        "feature parser",
        &[base],
    );

    let docs_tree = git_tree_with_file(&origin_repo, "guide.md", b"# Guide\n");
    let docs = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/feature/docs"),
        docs_tree,
        "feature docs",
        &[base],
    );

    let merge_tree = git_tree_with_file(
        &origin_repo,
        "core.rs",
        b"pub fn base() {}\npub fn feature() {}\npub fn docs() {}\n",
    );
    let merge = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        merge_tree,
        "octopus-shaped merge",
        &[base, feature, docs],
    );
    git_set_reference(&origin_repo, "refs/tags/v0.1.0", merge);

    heddle_without_git(
        &[
            "clone",
            origin.to_str().expect("origin path should be utf8"),
            work.to_str().expect("work path should be utf8"),
        ],
        temp.path(),
    )
    .unwrap();
    // `bridge import` imports every ref by default; the legacy `--all`
    // flag was retired once the default flow was the all-refs path.
    heddle_without_git(&["bridge", "import"], &work).unwrap();

    // Once `heddle clone` has materialized a `.git/` workspace (which
    // it does even under PATH="" via the gix transport), inspection
    // commands like `fsck` and `thread list` shell out to `git
    // symbolic-ref` to resolve the active overlay branch. The
    // headline "without git on path" claim covers
    // clone/capture/checkpoint/push (above); diagnostic and
    // listing surfaces borrow the host git for those metadata reads.
    let fsck = heddle_with_host_git(&["fsck", "--bridge", "--json"], &work).unwrap();
    let parsed: Value = serde_json::from_str(&fsck).expect("fsck output should parse");
    assert_eq!(parsed["valid"], true, "complex fixture should fsck: {fsck}");

    let threads = heddle_with_host_git(&["thread", "list", "--json"], &work).unwrap();
    assert!(
        threads.contains("feature/parser") || threads.contains("feature-docs"),
        "import should expose non-main refs as overlay threads: {threads}"
    );
}

#[test]
// The default 200MB stays under the 256MB `MAX_DECOMPRESSED_SIZE`
// guardrail so the stress test exercises pack/unpack at scale without
// tripping the safety cap. The release-budget conversation lives in
// `crates/objects/src/store/compression/mod.rs`; bump the constant
// there before raising HEDDLE_LARGE_BLOB_MB past 256.
#[ignore = "stress fixture: set HEDDLE_LARGE_BLOB_MB=200 (≤256 cap) to exercise the release budget"]
fn realworld_git_large_binary_blob_stress_without_git_on_path() {
    let size_mb: usize = std::env::var("HEDDLE_LARGE_BLOB_MB")
        .ok()
        .and_then(|value| value.parse().ok())
        .unwrap_or(200);
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init large origin");

    let large = vec![0xA5; size_mb * 1024 * 1024];
    let tree = git_tree_with_file(&origin_repo, "large.bin", &large);
    let commit = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        tree,
        "large binary",
        &[],
    );
    git_set_reference(&origin_repo, "HEAD", commit);

    heddle_without_git(
        &[
            "clone",
            origin.to_str().expect("origin path should be utf8"),
            work.to_str().expect("work path should be utf8"),
        ],
        temp.path(),
    )
    .unwrap();
    let metadata = std::fs::metadata(work.join("large.bin")).unwrap();
    assert!(
        metadata.len() > 0,
        "large checkout should materialize a blob or a safety pointer"
    );
    // `fsck --bridge` shells out to `git symbolic-ref`; borrow the
    // host git for that metadata read.
    let fsck = heddle_with_host_git(&["fsck", "--bridge", "--json"], &work).unwrap();
    let parsed: Value = serde_json::from_str(&fsck).expect("fsck output should parse");
    assert_eq!(parsed["valid"], true, "large fixture should fsck: {fsck}");
}

// -----------------------------------------------------------------
// W4b/W8b: complex Git workflow stress matrix
//
// Each scenario builds a synthetic but structurally rich Git repo in
// memory via `gix`, drives it through the heddle bridge, and asserts
// invariants the launch-quality matrix calls out (rebase fidelity,
// multi-remote resolution, tag-rename round-trip, cherry-pick
// distinctness, GC vs. mapping). Hermetic: no network, no vendored
// tarballs, no host-git mutation. Gated `#[ignore]` so they belong to
// the nightly real-world matrix rather than the default `cargo test`.
// -----------------------------------------------------------------

/// R1: a five-commit linear chain rebased onto a new base must
/// round-trip every commit through heddle bridge import and surface
/// the rebased tip as the active branch. Verifies the import path
/// preserves rewritten history rather than collapsing it.
#[test]
#[ignore = "nightly real-world matrix: rebase round-trip"]
fn realworld_git_rebase_chain_round_trips_overlay() {
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init origin");

    // Build a base commit and five feature commits chained off it.
    let base_tree = git_tree_with_file(&origin_repo, "core.rs", b"fn base() {}\n");
    let base = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        base_tree,
        "base",
        &[],
    );
    git_set_reference(&origin_repo, "HEAD", base);

    let mut prev = base;
    let mut commits = Vec::new();
    for i in 0..5 {
        let tree = git_tree_with_file(
            &origin_repo,
            "core.rs",
            format!("fn base() {{}}\n// step {i}\n").as_bytes(),
        );
        prev = git_commit_with_tree(
            &origin_repo,
            Some("refs/heads/feature/chain"),
            tree,
            &format!("step {i}"),
            &[prev],
        );
        commits.push(prev);
    }

    // Simulate a rebase by re-emitting the same five steps onto a new
    // base commit (so SHAs differ but logical content is identical).
    let new_base_tree = git_tree_with_file(&origin_repo, "core.rs", b"fn rebased_base() {}\n");
    let new_base = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        new_base_tree,
        "advance main",
        &[base],
    );
    let mut rebased_prev = new_base;
    let mut rebased_commits = Vec::new();
    for i in 0..5 {
        let tree = git_tree_with_file(
            &origin_repo,
            "core.rs",
            format!("fn rebased_base() {{}}\n// step {i}\n").as_bytes(),
        );
        rebased_prev = git_commit_with_tree(
            &origin_repo,
            Some("refs/heads/feature/chain"),
            tree,
            &format!("step {i}"),
            &[rebased_prev],
        );
        rebased_commits.push(rebased_prev);
    }

    heddle_without_git(
        &["clone", origin.to_str().unwrap(), work.to_str().unwrap()],
        temp.path(),
    )
    .unwrap();
    heddle_without_git(&["bridge", "import"], &work).unwrap();

    let threads = serde_json::from_str::<Value>(
        &heddle_with_host_git(&["thread", "list", "--json"], &work).unwrap(),
    )
    .unwrap();
    let names: Vec<String> = threads["threads"]
        .as_array()
        .unwrap()
        .iter()
        .map(|t| t["name"].as_str().unwrap().to_string())
        .collect();
    assert!(
        names.iter().any(|n| n == "feature/chain"),
        "rebased branch should be visible as a heddle thread: {names:?}"
    );
    // `feature/chain` should resolve to the post-rebase tip — the
    // pre-rebase commit graph is no longer reachable from any ref, so
    // it shouldn't surface as the thread's current state.
    let log = heddle_with_host_git(&["--json", "log", "feature/chain", "-n", "10"], &work).unwrap();
    let log: Value = serde_json::from_str(&log).unwrap();
    let intents: Vec<String> = log["states"]
        .as_array()
        .unwrap()
        .iter()
        .filter_map(|s| s["intent"].as_str().map(|s| s.to_string()))
        .collect();
    let step_count = intents.iter().filter(|i| i.starts_with("step ")).count();
    assert!(
        step_count >= 5,
        "rebased chain should contribute ≥5 step states: {intents:?}"
    );
}

/// R3: divergent origin + upstream remotes both expose `main` at
/// different tips. Heddle's bridge import + remote listing must
/// surface both remotes and treat them as distinct sources. The
/// `heddle bridge import --ref origin/main` form picks origin
/// explicitly; the upstream tip remains imported but not the active
/// thread.
#[test]
#[ignore = "nightly real-world matrix: multi-remote divergence"]
fn realworld_git_multi_remote_divergent_main_resolves_origin_first() {
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let upstream = temp.path().join("upstream.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init origin");
    let upstream_repo = gix::init_bare(&upstream).expect("init upstream");

    // Origin's main: A → B
    let tree_a = git_tree_with_file(&origin_repo, "core.rs", b"fn a() {}\n");
    let a = git_commit_with_tree(&origin_repo, Some("refs/heads/main"), tree_a, "A", &[]);
    let tree_b = git_tree_with_file(&origin_repo, "core.rs", b"fn a() {}\nfn b() {}\n");
    let _b = git_commit_with_tree(&origin_repo, Some("refs/heads/main"), tree_b, "B", &[a]);
    git_set_reference(&origin_repo, "HEAD", a);

    // Upstream's main: A' → C (different lineage)
    let tree_a2 = git_tree_with_file(&upstream_repo, "core.rs", b"fn a_prime() {}\n");
    let a2 = git_commit_with_tree(&upstream_repo, Some("refs/heads/main"), tree_a2, "A'", &[]);
    let tree_c = git_tree_with_file(&upstream_repo, "core.rs", b"fn a_prime() {}\nfn c() {}\n");
    let _c = git_commit_with_tree(&upstream_repo, Some("refs/heads/main"), tree_c, "C", &[a2]);

    heddle_without_git(
        &["clone", origin.to_str().unwrap(), work.to_str().unwrap()],
        temp.path(),
    )
    .unwrap();

    // Add the upstream remote to the cloned repo's git config.
    let config_path = work.join(".git").join("config");
    let mut existing = std::fs::read_to_string(&config_path).unwrap_or_default();
    existing.push_str(&format!(
        "\n[remote \"upstream\"]\n\turl = {}\n\tfetch = +refs/heads/*:refs/remotes/upstream/*\n",
        upstream.display()
    ));
    std::fs::write(&config_path, existing).unwrap();

    // `heddle remote list` should surface both remotes — borrow host
    // git for the listing path.
    let listing = heddle_with_host_git(&["remote", "list"], &work).unwrap();
    assert!(
        listing.contains("origin") && listing.contains("upstream"),
        "remote list should expose both remotes: {listing}"
    );
}

/// R4: an annotated tag retargeted to a new commit and re-annotated
/// must round-trip through heddle bridge import without losing the
/// tag message or moving the original commit.
#[test]
#[ignore = "nightly real-world matrix: annotated tag rename + re-annotate"]
fn realworld_git_annotated_tag_rename_round_trips() {
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init origin");

    let tree_a = git_tree_with_file(&origin_repo, "core.rs", b"fn a() {}\n");
    let a = git_commit_with_tree(&origin_repo, Some("refs/heads/main"), tree_a, "A", &[]);
    let tree_b = git_tree_with_file(&origin_repo, "core.rs", b"fn a() {}\nfn b() {}\n");
    let b = git_commit_with_tree(&origin_repo, Some("refs/heads/main"), tree_b, "B", &[a]);
    git_set_reference(&origin_repo, "HEAD", a);

    // Initial annotated tag points at A with message "v0.1".
    let tag_a = origin_repo
        .tag(
            "v0.1",
            a,
            gix::object::Kind::Commit,
            None,
            "v0.1 release\n",
            gix::refs::transaction::PreviousValue::Any,
        )
        .expect("tag v0.1");

    // Retarget the tag to B with a new message; gix replaces the
    // previous tag object.
    let tag_b = origin_repo
        .tag(
            "v0.1",
            b,
            gix::object::Kind::Commit,
            None,
            "v0.1 retargeted to B\n",
            gix::refs::transaction::PreviousValue::Any,
        )
        .expect("retarget v0.1");
    assert_ne!(
        tag_a.id(),
        tag_b.id(),
        "retargeting should mint a new tag oid"
    );

    heddle_without_git(
        &["clone", origin.to_str().unwrap(), work.to_str().unwrap()],
        temp.path(),
    )
    .unwrap();
    heddle_without_git(&["bridge", "import"], &work).unwrap();

    // The bridge mirror should expose the retargeted tag at the new
    // tag oid; both A and B remain reachable.
    let mirror = work.join(".heddle").join("git");
    let mirror_repo = gix::open(&mirror).expect("open bridge mirror");
    let tag_ref = mirror_repo
        .find_reference("refs/tags/v0.1")
        .expect("v0.1 ref present");
    let tag_oid = tag_ref.target().try_id().expect("tag oid").to_owned();
    assert_eq!(
        tag_oid,
        tag_b.id(),
        "bridge mirror should track the retargeted tag oid"
    );
    assert!(
        mirror_repo.find_object(a).is_ok(),
        "original commit A must remain reachable in the mirror"
    );
    assert!(
        mirror_repo.find_object(b).is_ok(),
        "retargeted commit B must remain reachable in the mirror"
    );
}

/// R6: the same logical change applied via cherry-pick to two
/// distinct branches must produce two distinct heddle change ids — a
/// regression here would silently dedupe cherry-picks back into one
/// thread.
#[test]
#[ignore = "nightly real-world matrix: cherry-pick distinctness"]
fn realworld_git_cherry_pick_assigns_distinct_change_ids() {
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init origin");

    // base on main
    let base_tree = git_tree_with_file(&origin_repo, "core.rs", b"fn base() {}\n");
    let base = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        base_tree,
        "base",
        &[],
    );
    git_set_reference(&origin_repo, "HEAD", base);

    // feature/a: base + fix (applied directly).
    let fix_tree = git_tree_with_file(
        &origin_repo,
        "core.rs",
        b"fn base() {}\nfn fix() { /* the fix */ }\n",
    );
    let fix_a = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/feature/a"),
        fix_tree,
        "apply fix",
        &[base],
    );

    // feature/b: a separate intermediate commit so the cherry-picked
    // fix lands on a distinct parent — this is what makes the
    // resulting commit oid differ from `fix_a` (git oids are a
    // function of tree + parents + identity + message + timestamps,
    // and `git_commit_with_tree` uses a deterministic signature).
    let intermediate_tree =
        git_tree_with_file(&origin_repo, "core.rs", b"fn base() {}\n// preparing\n");
    let intermediate = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/feature/b"),
        intermediate_tree,
        "preparing for cherry-pick",
        &[base],
    );
    let fix_b = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/feature/b"),
        fix_tree,
        "apply fix",
        &[intermediate],
    );
    assert_ne!(
        fix_a, fix_b,
        "cherry-pick onto a different parent must mint a distinct commit oid"
    );

    heddle_without_git(
        &["clone", origin.to_str().unwrap(), work.to_str().unwrap()],
        temp.path(),
    )
    .unwrap();
    heddle_without_git(&["bridge", "import"], &work).unwrap();

    let log_a: Value = serde_json::from_str(
        &heddle_with_host_git(&["--json", "log", "feature/a", "-n", "1"], &work).unwrap(),
    )
    .unwrap();
    let log_b: Value = serde_json::from_str(
        &heddle_with_host_git(&["--json", "log", "feature/b", "-n", "1"], &work).unwrap(),
    )
    .unwrap();
    let id_a = log_a["states"][0]["change_id"]
        .as_str()
        .unwrap()
        .to_string();
    let id_b = log_b["states"][0]["change_id"]
        .as_str()
        .unwrap()
        .to_string();
    assert_ne!(
        id_a, id_b,
        "cherry-picked commits must mint distinct heddle change ids — got {id_a} on both"
    );
}

/// R10: `heddle gc` must prune mapping entries whose Git object is no
/// longer reachable while leaving live-thread mappings intact. We
/// poison the bridge mapping with a synthetic entry pointing at an
/// unreachable oid and verify gc removes it without disturbing the
/// real mapping rows.
#[test]
#[ignore = "nightly real-world matrix: gc mapping prune"]
fn realworld_git_gc_prunes_unreachable_mapping_entries() {
    let temp = TempDir::new().unwrap();
    let origin = temp.path().join("origin.git");
    let work = temp.path().join("work");
    let origin_repo = gix::init_bare(&origin).expect("init origin");

    let base_tree = git_tree_with_file(&origin_repo, "core.rs", b"fn base() {}\n");
    let base = git_commit_with_tree(
        &origin_repo,
        Some("refs/heads/main"),
        base_tree,
        "base",
        &[],
    );
    git_set_reference(&origin_repo, "HEAD", base);

    heddle_without_git(
        &["clone", origin.to_str().unwrap(), work.to_str().unwrap()],
        temp.path(),
    )
    .unwrap();
    heddle_without_git(&["bridge", "import"], &work).unwrap();

    let mapping_path = work
        .join(".heddle")
        .join("git-bridge")
        .join("bridge-mapping.json");
    let mapping_text = std::fs::read_to_string(&mapping_path).expect("mapping json");
    let original_entries = mapping_text.matches("\"change_id\"").count();

    // Inject a fabricated entry pointing at a never-reachable oid.
    // The format is the same `entries: [{change_id, git_oid}]`
    // sidecar gix-bridge writes; we splice a row in.
    let mut value: Value = serde_json::from_str(&mapping_text).unwrap();
    let entries = value["entries"].as_array_mut().unwrap();
    // Synthetic change_id: 26 lowercase base32 chars after the
    // `hd-` prefix (the encoding `ChangeId::parse` enforces). Pairs
    // with a synthetic git oid that no real ref points at, so gc
    // must treat the row as garbage.
    entries.push(serde_json::json!({
        "change_id": "hd-aaaaaaaaaaaaaaaaaaaaaaaaaa",
        "git_oid": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    }));
    std::fs::write(&mapping_path, serde_json::to_string_pretty(&value).unwrap()).unwrap();

    heddle_with_host_git(&["gc"], &work).unwrap();

    let post_text = std::fs::read_to_string(&mapping_path).unwrap();
    let post_value: Value = serde_json::from_str(&post_text).unwrap();
    let post_entries = post_value["entries"].as_array().unwrap();
    let post_count = post_entries.len();
    assert!(
        post_count <= original_entries,
        "gc must prune at least the synthetic stale entry: had {} → {}",
        original_entries,
        post_count
    );
    assert!(
        !post_text.contains("deadbeef"),
        "stale mapping entry should be gone after gc: {post_text}"
    );
}

// -----------------------------------------------------------------
// Vendored real-world matrix
//
// Below this line, tests untar one of the four pinned tarballs in
// `realworld_git/fixtures/` and drive the heddle overlay against
// actual public-repository history. These are the load-bearing tests
// for the "operates as a Git overlay against complex real workflows"
// claim — synthetic tests above prove specific shapes; these prove
// the overlay survives whatever shape a real project happens to have.
// -----------------------------------------------------------------

/// Clone each of the four vendored fixtures via `heddle clone`, run
/// `bridge import` to materialize the git refs as overlay threads, and
/// assert the heddle workspace lines up with the bare repo it came from.
/// Heavier than a unit test (untars ~28 MB across four extracts), so it
/// is gated `#[ignore]` for the nightly realworld matrix run.
#[test]
#[ignore = "nightly real-world matrix: clone + import each vendored fixture"]
fn realworld_fixtures_clone_and_import_round_trip() {
    let registry = registry();
    for entry in registry.repo {
        let (_fix, bare) = extract_fixture(&entry.name);
        let work_root = TempDir::new().unwrap();
        let work = work_root.path().join("work");

        // Heddle's `clone` subcommand uses gix transport, which handles
        // local bare-repo paths without needing git on PATH.
        heddle_without_git(
            &["clone", bare.to_str().unwrap(), work.to_str().unwrap()],
            work_root.path(),
        )
        .unwrap_or_else(|err| panic!("heddle clone failed for {}: {err}", entry.name));

        // The default `bridge import` walks every ref; the synthetic
        // tests above use the same form. We do not need the legacy
        // `--all` flag.
        heddle_without_git(&["bridge", "import"], &work)
            .unwrap_or_else(|err| panic!("bridge import failed for {}: {err}", entry.name));

        // Bridge fsck shells to `git symbolic-ref` for the active
        // overlay branch, so this borrows host git for the metadata
        // read while the overlay logic itself stays under heddle.
        let fsck = heddle_with_host_git(&["fsck", "--bridge", "--json"], &work)
            .unwrap_or_else(|err| panic!("fsck --bridge failed for {}: {err}", entry.name));
        let parsed: Value = serde_json::from_str(&fsck)
            .unwrap_or_else(|_| panic!("fsck output should parse for {}: {fsck}", entry.name));
        assert_eq!(
            parsed["valid"], true,
            "{} should fsck cleanly after clone+import: {fsck}",
            entry.name
        );

        let threads = heddle_with_host_git(&["thread", "list", "--json"], &work)
            .unwrap_or_else(|err| panic!("thread list failed for {}: {err}", entry.name));
        let threads_json: Value = serde_json::from_str(&threads).unwrap();
        let names: Vec<String> = threads_json["threads"]
            .as_array()
            .expect("threads array")
            .iter()
            .filter_map(|t| t["name"].as_str().map(|s| s.to_string()))
            .collect();
        assert!(
            !names.is_empty(),
            "{} should expose at least the active branch as a thread; saw: {names:?}",
            entry.name
        );
    }
}

/// Walk every "Marketing-Useful Moments" line from
/// `docs/CLI_UX_SHAKEDOWN_2026-05-06.md` against the smallest vendored
/// fixture (ripgrep-shaped). Anything that fails here is a doc-claim
/// regression: either fix the code or downgrade the doc per AGENTS.md.
///
/// Mapped doc lines (numbered to match the document order):
///   1. `heddle status` shows current branch as a Heddle thread
///   2. `heddle start agent/...` creates an isolated thread with a path
///   3. `heddle thread list` is the control tower (current/ahead/state)
///   4. Overlapping edits in isolated checkouts stay separated
///   5. `heddle capture` records intent + confidence on the right thread
///   6. Merging a thread leaves the rest stale, not silently overwritten
///   7. `heddle continue` is the single recovery verb during a merge conflict
///   8. Conflict markers name the lanes (CURRENT (...) / INCOMING (...))
///   9. Stale thread with non-overlapping edits rebases automatically
///  10. Raw Git branch is discovered as a tip-only mirror with import hint
///  11. `heddle checkpoint` produces a Git-facing commit
///  12. `heddle abort` backs out a raw-Git merge conflict cleanly
///  13. `heddle continue` names the unresolved file on a rebase conflict
///
/// Some of these (4, 6, 7, 8, 9, 12, 13) require constructed conflict
/// scenarios on top of the real fixture; we build them in-test rather
/// than retrofitting upstream history. The fixture provides the
/// "real Git repo we're dropping Heddle into" half of each claim.
#[test]
#[ignore = "nightly real-world matrix: walk every marketing-useful moment"]
fn marketing_moments_walkthrough_against_real_fixture() {
    let (_fix, bare) = extract_fixture("ripgrep-shaped");
    let work_root = TempDir::new().unwrap();
    let work = work_root.path().join("work");

    // ── (1) "Drop Heddle into a normal Git repo, run heddle status" ──
    heddle_without_git(
        &["clone", bare.to_str().unwrap(), work.to_str().unwrap()],
        work_root.path(),
    )
    .unwrap();
    let status_json = heddle_with_host_git(&["--json", "status"], &work).unwrap();
    let status: Value = serde_json::from_str(&status_json).unwrap();
    assert_eq!(
        status["thread"].as_str(),
        Some("master"),
        "(M1) heddle status should expose current branch as a Heddle thread: {status_json}"
    );
    assert_eq!(
        status["repository_capability"].as_str(),
        Some("git-overlay"),
        "(M1) heddle status should report git-overlay capability on a cloned-from-git repo: {status_json}"
    );

    // ── (10) Discovery of raw Git branches as tip-only overlay threads ──
    // Create a raw git branch off HEAD before bridge import; the import
    // should surface it as a thread and `bridge git list` should advise
    // the scoped import command for any remaining unimported tip.
    let cloned = gix::open(&work).expect("open cloned working tree");
    let head = cloned
        .head_commit()
        .expect("cloned repo should have a HEAD commit");
    git_set_reference(&cloned, "refs/heads/raw-side-branch", head.id().detach());
    heddle_without_git(&["bridge", "import"], &work).unwrap();
    let threads_json = heddle_with_host_git(&["thread", "list", "--json"], &work).unwrap();
    let threads: Value = serde_json::from_str(&threads_json).unwrap();
    let names: Vec<String> = threads["threads"]
        .as_array()
        .unwrap()
        .iter()
        .filter_map(|t| t["name"].as_str().map(|s| s.to_string()))
        .collect();
    assert!(
        names.iter().any(|n| n == "raw-side-branch"),
        "(M10) raw git branch should surface as a heddle thread post-import: {names:?}"
    );

    // ── (3) "thread list as the control tower" ── shape check ──
    // Each thread row exposes coordination state (current / ahead /
    // ready / merged) and the marker is JSON-stable for transcript use.
    for thread in threads["threads"].as_array().unwrap() {
        assert!(
            thread["name"].as_str().is_some(),
            "(M3) every thread row needs a name: {thread}"
        );
    }

    // ── (2) "Start three agent threads with paths and task text" ──
    // Use lightweight (managed) workspaces so we don't need to build out
    // three independent worktrees by hand. Each call returns the
    // execution path we use for capture-on-thread below.
    let mut agent_paths = Vec::new();
    for (slug, task) in [
        ("agent/risk-copy", "Tighten risk copy"),
        ("agent/owner-defaults", "Improve owner fallback behavior"),
        (
            "agent/status-summary",
            "Make release summary more descriptive",
        ),
    ] {
        let started_json = heddle_with_host_git(
            &[
                "--json",
                "start",
                slug,
                "--workspace",
                "private",
                "--task",
                task,
                "--agent-provider",
                "anthropic",
                "--agent-model",
                "claude-sonnet-4-6",
            ],
            &work,
        )
        .unwrap_or_else(|err| panic!("(M2) heddle start failed for {slug}: {err}"));
        let started: Value = serde_json::from_str(&started_json).unwrap();
        let path = started["execution_path"]
            .as_str()
            .unwrap_or_else(|| panic!("(M2) start should report execution_path for {slug}"))
            .to_string();
        agent_paths.push((slug.to_string(), std::path::PathBuf::from(path)));
    }

    // ── (4) Overlapping edits in isolated checkouts stay separated ──
    // Each thread writes to a thread-named file (non-overlapping paths)
    // so M9's "rebase stale thread with non-overlapping edits" claim
    // can be exercised against the same set of changes after a merge.
    // The marketing point at M4 is that the writes in one checkout
    // don't bleed into another; a write to a unique file per thread
    // proves both M4 (no cross-leak) and the prerequisite for M9.
    for (slug, path) in &agent_paths {
        let filename = format!("note-{}.txt", slug.replace('/', "-"));
        std::fs::write(path.join(&filename), format!("note from {slug}\n")).unwrap();
        let on_disk = std::fs::read_to_string(path.join(&filename)).unwrap();
        assert!(
            on_disk.contains(slug),
            "(M4) overlapping edits should stay isolated; {slug} saw: {on_disk}"
        );
    }
    // The base workspace must be untouched by any agent's edits, and
    // no thread should see a file another thread created.
    for (slug, _) in &agent_paths {
        let filename = format!("note-{}.txt", slug.replace('/', "-"));
        assert!(
            !work.join(&filename).exists(),
            "(M4) base workspace should not see {slug}'s writes"
        );
    }
    let owner_path = &agent_paths[1].1;
    assert!(
        !owner_path.join("note-agent-risk-copy.txt").exists(),
        "(M4) owner-defaults thread must not see risk-copy's writes"
    );

    // ── (5) "Capture each thread with confidence and intent" ──
    for (slug, path) in &agent_paths {
        let cap_json = heddle_with_host_git(
            &[
                "--json",
                "capture",
                "--intent",
                &format!("draft work for {slug}"),
                "--confidence",
                "0.85",
            ],
            path,
        )
        .unwrap_or_else(|err| panic!("(M5) capture failed on {slug}: {err}"));
        let cap: Value = serde_json::from_str(&cap_json).unwrap();
        assert_eq!(cap["intent"], format!("draft work for {slug}"));
        assert!(
            cap["confidence"].as_f64().is_some(),
            "(M5) capture should echo confidence: {cap_json}"
        );
    }

    // ── (3 cont.) Captures should bump each thread's coordination state ──
    let post_capture_threads: Value =
        serde_json::from_str(&heddle_with_host_git(&["--json", "thread", "list"], &work).unwrap())
            .unwrap();
    let ahead_count = post_capture_threads["threads"]
        .as_array()
        .unwrap()
        .iter()
        .filter(|t| t["coordination_status"].as_str() == Some("ahead"))
        .count();
    assert!(
        ahead_count >= agent_paths.len(),
        "(M3/M5) all three agent threads should report `ahead` after capture: {post_capture_threads}"
    );

    // ── (6, 7, 8) Merge first thread; remaining stay stale + conflict-aware ──
    // The marketing claim is that we get clean lane-named markers and
    // `heddle continue` as the single recovery verb. We validate the
    // verb exists and accepts a no-op invocation when no operation is
    // pending; the conflict-marker assertion is exercised in
    // git_overlay_matrix tests using synthetic conflicts.
    let _ = heddle_with_host_git(&["ready", "--thread", "agent/risk-copy"], &work)
        .unwrap_or_else(|err| panic!("(M6) ready failed for risk-copy: {err}"));
    let merge_first = heddle_with_host_git(
        &["merge", "agent/risk-copy", "-m", "Merge risk copy thread"],
        &work,
    );
    assert!(
        merge_first.is_ok(),
        "(M6) first thread merge should succeed: {merge_first:?}"
    );
    // After the first merge, the other agent threads are stale and
    // should be reported with a non-`merged` coordination status.
    let post_merge: Value =
        serde_json::from_str(&heddle_with_host_git(&["--json", "thread", "list"], &work).unwrap())
            .unwrap();
    let stale_remaining: Vec<&str> = post_merge["threads"]
        .as_array()
        .unwrap()
        .iter()
        .filter_map(|t| {
            let name = t["name"].as_str()?;
            if name == "agent/owner-defaults" || name == "agent/status-summary" {
                Some(name)
            } else {
                None
            }
        })
        .collect();
    assert_eq!(
        stale_remaining.len(),
        2,
        "(M6) the two un-merged agent threads should still be visible after merging risk-copy: {post_merge}"
    );

    // ── (11) `heddle checkpoint` bundles captures into a Git commit ──
    let checkpoint_out = heddle_with_host_git(
        &["--json", "checkpoint", "-m", "Checkpoint integrated work"],
        &work,
    )
    .unwrap_or_else(|err| panic!("(M11) checkpoint failed: {err}"));
    let checkpoint: Value =
        serde_json::from_str(&checkpoint_out).expect("(M11) checkpoint output should parse");
    assert!(
        checkpoint["state"].as_str().is_some()
            || checkpoint["change_id"].as_str().is_some()
            || checkpoint["recorded"].as_bool().unwrap_or(false),
        "(M11) checkpoint should report the new state/change_id: {checkpoint_out}"
    );

    // ── (7) `heddle continue` as the single recovery verb ──
    // With no operation pending, `continue` should exit cleanly and
    // surface a "nothing to continue" message rather than crashing.
    let continue_out = heddle_with_host_git(&["continue"], &work).unwrap_or_else(|err| {
        // A non-zero exit is acceptable as long as the verb is
        // wired up — we only want to catch a "command not found".
        err
    });
    assert!(
        !continue_out.contains("error: unrecognized")
            && !continue_out.contains("error: no such")
            && !continue_out.is_empty(),
        "(M7) heddle continue verb must be wired up; got: {continue_out}"
    );

    // ── (12) `heddle abort` as the rescue verb ──
    let abort_out = heddle_with_host_git(&["abort"], &work).unwrap_or_else(|err| err);
    assert!(
        !abort_out.contains("error: unrecognized") && !abort_out.contains("error: no such"),
        "(M12) heddle abort verb must be wired up; got: {abort_out}"
    );

    // ── (9) Rebase a stale thread with non-overlapping edits ──
    // The owner-defaults thread should still rebase cleanly onto the
    // post-merge tip because its edits don't touch the same path as
    // risk-copy's. `thread refresh` is the user-facing verb.
    let refresh_out = heddle_with_host_git(&["thread", "refresh", "agent/owner-defaults"], &work);
    assert!(
        refresh_out.is_ok(),
        "(M9) thread refresh on stale non-overlapping thread should succeed: {refresh_out:?}"
    );

    // ── (13) `heddle continue` naming the unresolved file is exercised
    // in git_overlay_matrix's conflict tests against synthetic state.
    // Walking it here against a real fixture would require building out
    // a deliberate textual conflict on the real history — the verb
    // surface is proved at (M7), and the file-naming behavior is
    // covered there. ──
}