xbp_cli/commands/version/

workspace_release.rs

use super::{
    git_worktree_state, parse_version, read_cargo_lock_version_for_package,
    read_regex_version_from_content, read_version_from_path, resolve_project_root,
    write_cargo_lock_version_for_package, write_version_to_path, GitWorktreeState,
};
use crate::utils::{cargo_command_exists, cargo_program, resolve_cargo_package_version};
use semver::Version;
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::thread;
use std::time::Duration as StdDuration;
use tokio::time::{sleep, Duration, Instant};
use toml::Value as TomlValue;
use toml_edit::{value, DocumentMut, Item, Table, Value};

const DEFAULT_METADATA_FILES: &[&str] = &[
    "README.md",
    "openapi.yaml",
    "openapi.yml",
    "openapi.json",
    "swagger.yaml",
    "swagger.yml",
    "swagger.json",
];
const CONFIG_CANDIDATES: &[&str] = &[".xbp/workspace-release.yaml", ".xbp/workspace-release.yml"];

#[derive(Debug, Clone)]
pub struct WorkspaceVersionCommandOptions {
    pub repo: Option<PathBuf>,
    pub json: bool,
    pub command: WorkspaceVersionCommand,
}

#[derive(Debug, Clone)]
pub enum WorkspaceVersionCommand {
    Check(WorkspaceVersionCheckOptions),
    Sync(WorkspaceVersionSyncOptions),
    Validate(WorkspaceVersionValidateOptions),
    PublishPlan(WorkspacePublishPlanOptions),
    PublishHeal(WorkspacePublishHealOptions),
    PublishRun(WorkspacePublishRunOptions),
}

#[derive(Debug, Clone)]
pub struct WorkspaceVersionCheckOptions {
    pub version: Option<String>,
}

#[derive(Debug, Clone)]
pub struct WorkspaceVersionSyncOptions {
    pub version: Option<String>,
    pub write: bool,
}

#[derive(Debug, Clone)]
pub struct WorkspaceVersionValidateOptions {
    pub package: Option<String>,
    pub cargo_check: bool,
    pub package_dry_run: bool,
}

#[derive(Debug, Clone)]
pub struct WorkspacePublishPlanOptions {
    pub only: Option<String>,
    pub include_prereqs: bool,
}

#[derive(Debug, Clone)]
pub struct WorkspacePublishHealOptions {
    pub only: Option<String>,
    pub include_prereqs: bool,
    pub write: bool,
    pub version: Option<String>,
}

#[derive(Debug, Clone)]
pub struct WorkspacePublishRunOptions {
    pub dry_run: bool,
    pub from: Option<String>,
    pub only: Option<String>,
    pub include_prereqs: bool,
    pub continue_on_error: bool,
    pub allow_dirty: bool,
    pub auto_fix: bool,
    pub timeout_seconds: f64,
    pub poll_interval_seconds: f64,
}

#[derive(Debug, Default, Clone, Deserialize)]
struct WorkspaceReleaseConfig {
    #[serde(default)]
    version_coupled_manifests: Vec<String>,
    #[serde(default)]
    metadata_files: Vec<String>,
    #[serde(default)]
    publish: WorkspaceReleasePublishConfig,
}

#[derive(Debug, Default, Clone, Deserialize)]
struct WorkspaceReleasePublishConfig {
    #[serde(default)]
    exclude: Vec<String>,
    #[serde(default)]
    order: Vec<String>,
}

#[derive(Debug, Clone)]
struct ReleaseSurface {
    repo_root: PathBuf,
    config_path: Option<PathBuf>,
    config: WorkspaceReleaseConfig,
    packages: Vec<ReleasePackage>,
    metadata_files: Vec<MetadataVersionFile>,
    cargo_lock: Option<PathBuf>,
    root_package_name: Option<String>,
}

#[derive(Debug, Clone)]
struct ReleasePackage {
    name: String,
    manifest_path: PathBuf,
    manifest_relative: String,
    version: Version,
    publishable: bool,
    publish_excluded: bool,
    dependency_pins: Vec<LocalDependencyPin>,
    publish_internal_dependencies: Vec<String>,
    publish_missing_version_pins: Vec<String>,
}

#[derive(Debug, Clone)]
struct LocalDependencyPin {
    field: String,
    version: Option<String>,
}

#[derive(Debug, Clone)]
struct MetadataVersionFile {
    path: PathBuf,
    relative: String,
}

#[derive(Debug, Clone, Serialize)]
struct DriftEntry {
    path: String,
    field: String,
    actual: Option<String>,
    expected: String,
}

#[derive(Debug, Clone, Serialize)]
struct SyncEdit {
    path: String,
    field: String,
    before: Option<String>,
    after: String,
}

#[derive(Debug, Clone, Serialize)]
pub(crate) struct PublishPlanItem {
    pub package: String,
    pub manifest: String,
    pub version: String,
    pub publishable: bool,
    pub crates_io_visible: Option<bool>,
    pub publish_needed: bool,
    pub blocked_by: Vec<String>,
    pub reason: String,
}

#[derive(Debug, Clone, Serialize)]
struct ValidationCommandResult {
    command: String,
    success: bool,
    exit_code: Option<i32>,
    stderr: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    warning: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
struct WorkspaceCheckReport {
    repo_root: String,
    expected_version: String,
    aligned: bool,
    drift: Vec<DriftEntry>,
}

#[derive(Debug, Clone, Serialize)]
struct WorkspaceSyncReport {
    repo_root: String,
    expected_version: String,
    write: bool,
    changed: bool,
    files_changed: Vec<String>,
    edits: Vec<SyncEdit>,
}

#[derive(Debug, Clone, Serialize)]
struct WorkspacePublishPlanReport {
    repo_root: String,
    requested_package: Option<String>,
    included_prereqs: Vec<String>,
    required_closure: Vec<String>,
    packages: Vec<PublishPlanItem>,
    publish_order: Vec<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    surface_issues: Vec<PublishSurfaceIssue>,
}

#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub(crate) enum PublishSurfaceIssueKind {
    PublishDisabled,
    PublishExcluded,
    MissingVersionPin,
    WorkspaceDepVersionDrift,
    MissingPackageMetadata,
}

#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub(crate) struct PublishSurfaceIssue {
    pub package: String,
    pub manifest: String,
    pub kind: PublishSurfaceIssueKind,
    pub detail: String,
    pub auto_fixable: bool,
}

#[derive(Debug, Clone, Serialize)]
struct WorkspacePublishHealReport {
    repo_root: String,
    write: bool,
    expected_version: String,
    issues: Vec<PublishSurfaceIssue>,
    edits: Vec<SyncEdit>,
    files_changed: Vec<String>,
}

#[derive(Debug, Clone)]
pub(crate) struct PublishSurfaceHealSummary {
    pub expected_version: Version,
    pub issue_count: usize,
    pub auto_fixable_count: usize,
    pub preview: Vec<String>,
}

#[derive(Debug, Clone, Serialize)]
struct WorkspaceValidateReport {
    repo_root: String,
    ok: bool,
    issues: Vec<DriftEntry>,
    commands: Vec<ValidationCommandResult>,
}

#[derive(Debug, Clone, Serialize)]
struct WorkspacePublishRunReport {
    repo_root: String,
    dry_run: bool,
    requested_package: Option<String>,
    included_prereqs: Vec<String>,
    required_closure: Vec<String>,
    published: Vec<String>,
    skipped: Vec<String>,
    failed: Vec<String>,
}

#[derive(Debug, Clone, Serialize)]
pub(crate) struct WorkspacePublishCommandTarget {
    pub package: String,
    pub version: String,
    pub manifest_path: PathBuf,
    pub manifest_relative: String,
}

#[derive(Debug, Clone, Serialize)]
pub(crate) struct ManifestWorkspacePublishResolution {
    pub workspace_root: PathBuf,
    pub requested_package: String,
    pub included_prereqs: Vec<String>,
    pub required_closure: Vec<String>,
    pub packages: Vec<PublishPlanItem>,
    pub publish_order: Vec<WorkspacePublishCommandTarget>,
}

#[derive(Debug, Deserialize)]
struct CargoMetadata {
    packages: Vec<CargoMetadataPackage>,
    workspace_members: Vec<String>,
    workspace_root: String,
}

#[derive(Debug, Deserialize)]
struct CargoMetadataPackage {
    id: String,
    manifest_path: String,
}

pub async fn run_version_workspace_command(
    options: WorkspaceVersionCommandOptions,
) -> Result<(), String> {
    let repo_root = match options.repo {
        Some(path) => path,
        None => resolve_project_root(),
    };
    let surface: ReleaseSurface = discover_release_surface(&repo_root)?;

    match options.command {
        WorkspaceVersionCommand::Check(check) => {
            let expected: Version = resolve_expected_version(&surface, check.version.as_deref())?;
            let drift: Vec<DriftEntry> = collect_drift(&surface, &expected)?;
            let report: WorkspaceCheckReport = WorkspaceCheckReport {
                repo_root: display_path(&surface.repo_root),
                expected_version: expected.to_string(),
                aligned: drift.is_empty(),
                drift,
            };
            if options.json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&report)
                        .map_err(|e| format!("Failed to serialize JSON report: {}", e))?
                );
            } else {
                print_check_report(&surface, &report);
            }
            if report.aligned {
                Ok(())
            } else {
                Err("Workspace release drift detected.".to_string())
            }
        }
        WorkspaceVersionCommand::Sync(sync) => {
            let expected = resolve_expected_version(&surface, sync.version.as_deref())?;
            let (edits, changed_files) = apply_sync(&surface, &expected, sync.write)?;
            let report = WorkspaceSyncReport {
                repo_root: display_path(&surface.repo_root),
                expected_version: expected.to_string(),
                write: sync.write,
                changed: !edits.is_empty(),
                files_changed: changed_files,
                edits,
            };
            if options.json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&report)
                        .map_err(|e| format!("Failed to serialize JSON report: {}", e))?
                );
            } else {
                print_sync_report(&surface, &report);
            }
            Ok(())
        }
        WorkspaceVersionCommand::Validate(validate) => {
            let report = run_validation(&surface, &validate)?;
            if options.json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&report)
                        .map_err(|e| format!("Failed to serialize JSON report: {}", e))?
                );
            } else {
                print_validation_report(&surface, &report);
            }
            if report.ok {
                Ok(())
            } else {
                Err("Workspace validation failed.".to_string())
            }
        }
        WorkspaceVersionCommand::PublishPlan(plan) => {
            let report = build_publish_plan_report(&surface, &plan).await?;
            if options.json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&report)
                        .map_err(|e| format!("Failed to serialize JSON report: {}", e))?
                );
            } else {
                print_publish_plan_report(&surface, &report);
            }
            Ok(())
        }
        WorkspaceVersionCommand::PublishHeal(heal) => {
            let report = run_publish_heal(&surface, &heal)?;
            if options.json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&report)
                        .map_err(|e| format!("Failed to serialize JSON report: {}", e))?
                );
            } else {
                print_publish_heal_report(&surface, &report);
            }
            Ok(())
        }
        WorkspaceVersionCommand::PublishRun(run) => {
            let surface = if run.auto_fix {
                let selection = PublishSelection {
                    from: run.from.clone(),
                    only: run.only.clone(),
                    include_prereqs: run.include_prereqs,
                };
                let expected = resolve_expected_version(&surface, None)?;
                let issues = collect_publish_surface_issues(&surface, Some(&selection), &expected)?;
                let auto_fixable = issues.iter().any(|issue| issue.auto_fixable);
                if auto_fixable {
                    let (_edits, files) =
                        apply_publish_surface_heals(&surface, Some(&selection), &expected, true)?;
                    if !files.is_empty() {
                        println!(
                            "Auto-fixed publish surface ({} file(s)): {}",
                            files.len(),
                            files.join(", ")
                        );
                    }
                    discover_release_surface(&repo_root)?
                } else {
                    surface
                }
            } else {
                surface
            };
            let report = run_publish(&surface, &run).await?;
            if options.json {
                println!(
                    "{}",
                    serde_json::to_string_pretty(&report)
                        .map_err(|e| format!("Failed to serialize JSON report: {}", e))?
                );
            } else {
                print_publish_run_report(&surface, &report);
            }
            if report.failed.is_empty() {
                Ok(())
            } else {
                Err("Workspace publish run failed.".to_string())
            }
        }
    }
}

fn discover_release_surface(repo_root: &Path) -> Result<ReleaseSurface, String> {
    let metadata = load_cargo_metadata(repo_root)?;
    discover_release_surface_from_metadata(metadata)
}

fn discover_release_surface_from_manifest(manifest_path: &Path) -> Result<ReleaseSurface, String> {
    let metadata = load_cargo_metadata_for_manifest(manifest_path)?;
    discover_release_surface_from_metadata(metadata)
}

fn discover_release_surface_from_metadata(
    metadata: CargoMetadata,
) -> Result<ReleaseSurface, String> {
    let repo_root = PathBuf::from(&metadata.workspace_root);
    let config_path = CONFIG_CANDIDATES
        .iter()
        .map(|candidate| repo_root.join(candidate))
        .find(|path| path.exists());
    let config = load_workspace_release_config(config_path.as_deref())?;

    let workspace_member_ids: BTreeSet<String> = metadata.workspace_members.into_iter().collect();
    let mut candidate_manifests = Vec::new();
    for package in metadata.packages {
        if !workspace_member_ids.contains(&package.id) {
            continue;
        }
        candidate_manifests.push(PathBuf::from(package.manifest_path));
    }
    for relative in &config.version_coupled_manifests {
        let manifest = repo_root.join(relative);
        if !candidate_manifests
            .iter()
            .any(|existing| existing == &manifest)
        {
            candidate_manifests.push(manifest);
        }
    }

    let mut basic_packages = Vec::new();
    for manifest_path in candidate_manifests {
        basic_packages.push(read_basic_manifest_info(&manifest_path, &config)?);
    }
    basic_packages.sort_by(|a, b| a.name.cmp(&b.name));

    let release_names: BTreeSet<String> = basic_packages
        .iter()
        .map(|package| package.name.clone())
        .collect();
    let mut packages = Vec::new();
    for basic in basic_packages {
        packages.push(read_release_package(&repo_root, basic, &release_names)?);
    }

    let root_manifest = repo_root.join("Cargo.toml");
    let root_package_name = packages
        .iter()
        .find(|package| package.manifest_path == root_manifest)
        .map(|package| package.name.clone());

    let mut seen = BTreeSet::new();
    let mut metadata_files = Vec::new();
    for relative in DEFAULT_METADATA_FILES
        .iter()
        .copied()
        .chain(config.metadata_files.iter().map(String::as_str))
    {
        if !seen.insert(relative.to_string()) {
            continue;
        }
        let path = repo_root.join(relative);
        if !path.exists() {
            continue;
        }
        if read_metadata_version(&path)?.is_some() {
            metadata_files.push(MetadataVersionFile {
                relative: normalize_relative(&repo_root, &path),
                path,
            });
        }
    }

    let cargo_lock = repo_root.join("Cargo.lock");
    Ok(ReleaseSurface {
        repo_root,
        config_path,
        config,
        packages,
        metadata_files,
        cargo_lock: cargo_lock.exists().then_some(cargo_lock),
        root_package_name,
    })
}

#[derive(Debug, Clone)]
struct BasicManifestInfo {
    name: String,
    manifest_path: PathBuf,
    publishable: bool,
    publish_excluded: bool,
}

fn read_basic_manifest_info(
    manifest_path: &Path,
    config: &WorkspaceReleaseConfig,
) -> Result<BasicManifestInfo, String> {
    let content = fs::read_to_string(manifest_path)
        .map_err(|e| format!("Failed to read {}: {}", manifest_path.display(), e))?;
    let value: TomlValue =
        toml::from_str(&content).map_err(|e| format!("Failed to parse TOML: {}", e))?;
    let package = value
        .get("package")
        .and_then(TomlValue::as_table)
        .ok_or_else(|| format!("Expected [package] in {}", manifest_path.display()))?;
    let name = package
        .get("name")
        .and_then(TomlValue::as_str)
        .ok_or_else(|| format!("Missing package.name in {}", manifest_path.display()))?
        .to_string();
    let publishable = match package.get("publish") {
        Some(TomlValue::Boolean(false)) => false,
        Some(TomlValue::Array(values)) if values.is_empty() => false,
        _ => true,
    };
    Ok(BasicManifestInfo {
        name: name.clone(),
        manifest_path: manifest_path.to_path_buf(),
        publishable,
        publish_excluded: config.publish.exclude.iter().any(|value| value == &name),
    })
}

fn read_release_package(
    repo_root: &Path,
    basic: BasicManifestInfo,
    release_names: &BTreeSet<String>,
) -> Result<ReleasePackage, String> {
    let content = fs::read_to_string(&basic.manifest_path)
        .map_err(|e| format!("Failed to read {}: {}", basic.manifest_path.display(), e))?;
    let value: TomlValue =
        toml::from_str(&content).map_err(|e| format!("Failed to parse TOML: {}", e))?;
    let version = resolve_cargo_package_version(&basic.manifest_path)?
        .ok_or_else(|| {
            format!(
                "Missing package.version in {}",
                basic.manifest_path.display()
            )
        })
        .and_then(|value| parse_version(&value))?;
    let dependency_analysis = analyze_local_dependencies_from_toml(&value, release_names);

    Ok(ReleasePackage {
        name: basic.name,
        manifest_path: basic.manifest_path.clone(),
        manifest_relative: normalize_relative(repo_root, &basic.manifest_path),
        version,
        publishable: basic.publishable,
        publish_excluded: basic.publish_excluded,
        dependency_pins: dependency_analysis.dependency_pins,
        publish_internal_dependencies: dependency_analysis.publish_internal_dependencies,
        publish_missing_version_pins: dependency_analysis.publish_missing_version_pins,
    })
}

#[derive(Debug, Default)]
struct DependencyAnalysis {
    dependency_pins: Vec<LocalDependencyPin>,
    publish_internal_dependencies: Vec<String>,
    publish_missing_version_pins: Vec<String>,
}

fn analyze_local_dependencies_from_toml(
    value: &TomlValue,
    release_names: &BTreeSet<String>,
) -> DependencyAnalysis {
    let mut pins = Vec::new();
    let mut publish_internal_dependencies = BTreeSet::new();
    let mut publish_missing_version_pins = Vec::new();
    collect_dependency_pins_from_table(
        value,
        "",
        release_names,
        &mut pins,
        &mut publish_internal_dependencies,
        &mut publish_missing_version_pins,
    );
    pins.sort_by(|a, b| a.field.cmp(&b.field));
    publish_missing_version_pins.sort();
    DependencyAnalysis {
        dependency_pins: pins,
        publish_internal_dependencies: publish_internal_dependencies.into_iter().collect(),
        publish_missing_version_pins,
    }
}

fn collect_dependency_pins_from_table(
    value: &TomlValue,
    prefix: &str,
    release_names: &BTreeSet<String>,
    pins: &mut Vec<LocalDependencyPin>,
    publish_internal_dependencies: &mut BTreeSet<String>,
    publish_missing_version_pins: &mut Vec<String>,
) {
    let Some(table) = value.as_table() else {
        return;
    };

    for (key, entry) in table {
        let path = if prefix.is_empty() {
            key.to_string()
        } else {
            format!("{}.{}", prefix, key)
        };
        if matches!(
            key.as_str(),
            "dependencies" | "dev-dependencies" | "build-dependencies"
        ) {
            let publish_relevant = !matches!(key.as_str(), "dev-dependencies");
            collect_dependency_section(
                path.as_str(),
                entry,
                release_names,
                publish_relevant,
                pins,
                publish_internal_dependencies,
                publish_missing_version_pins,
            );
            continue;
        }
        collect_dependency_pins_from_table(
            entry,
            &path,
            release_names,
            pins,
            publish_internal_dependencies,
            publish_missing_version_pins,
        );
    }
}

fn collect_dependency_section(
    section_name: &str,
    value: &TomlValue,
    release_names: &BTreeSet<String>,
    publish_relevant: bool,
    pins: &mut Vec<LocalDependencyPin>,
    publish_internal_dependencies: &mut BTreeSet<String>,
    publish_missing_version_pins: &mut Vec<String>,
) {
    let Some(table) = value.as_table() else {
        return;
    };
    for (dependency_name, dependency_value) in table {
        let Some(release_dependency_name) = resolve_release_dependency_name(
            dependency_name,
            dependency_value.as_table(),
            release_names,
        ) else {
            continue;
        };
        let Some(detail) = dependency_value.as_table() else {
            continue;
        };
        let uses_workspace = detail
            .get("workspace")
            .and_then(TomlValue::as_bool)
            .unwrap_or(false);
        let uses_path = detail.contains_key("path");
        if !uses_path && !uses_workspace {
            continue;
        }
        if publish_relevant {
            publish_internal_dependencies.insert(release_dependency_name);
        }
        if !uses_path {
            continue;
        }
        let field = format!("{}.{}.version", section_name, dependency_name);
        let version = detail
            .get("version")
            .and_then(TomlValue::as_str)
            .map(|value| value.to_string());
        if publish_relevant && version.is_none() {
            publish_missing_version_pins.push(field.clone());
        }
        pins.push(LocalDependencyPin { field, version });
    }
}

fn resolve_release_dependency_name(
    dependency_name: &str,
    detail: Option<&toml::map::Map<String, TomlValue>>,
    release_names: &BTreeSet<String>,
) -> Option<String> {
    if release_names.contains(dependency_name) {
        return Some(dependency_name.to_string());
    }

    let aliased_package_name = detail
        .and_then(|detail| detail.get("package"))
        .and_then(TomlValue::as_str)?;
    if release_names.contains(aliased_package_name) {
        return Some(aliased_package_name.to_string());
    }

    None
}

fn collect_drift(surface: &ReleaseSurface, expected: &Version) -> Result<Vec<DriftEntry>, String> {
    let expected_text = expected.to_string();
    let mut drift = Vec::new();

    for package in &surface.packages {
        if package.version != *expected {
            drift.push(DriftEntry {
                path: package.manifest_relative.clone(),
                field: "package.version".to_string(),
                actual: Some(package.version.to_string()),
                expected: expected_text.clone(),
            });
        }
        for pin in &package.dependency_pins {
            if pin.version.as_deref() != Some(expected_text.as_str()) {
                drift.push(DriftEntry {
                    path: package.manifest_relative.clone(),
                    field: pin.field.clone(),
                    actual: pin.version.clone(),
                    expected: expected_text.clone(),
                });
            }
        }
    }

    for metadata in &surface.metadata_files {
        let actual = read_metadata_version(&metadata.path)?;
        if actual.as_deref() != Some(expected_text.as_str()) {
            drift.push(DriftEntry {
                path: metadata.relative.clone(),
                field: "version".to_string(),
                actual,
                expected: expected_text.clone(),
            });
        }
    }

    if let Some(cargo_lock) = surface.cargo_lock.as_ref() {
        for package in &surface.packages {
            let actual = read_cargo_lock_version_for_package(cargo_lock, &package.name)?;
            if let Some(actual_version) = actual {
                if actual_version != expected_text {
                    drift.push(DriftEntry {
                        path: "Cargo.lock".to_string(),
                        field: format!("package.{}.version", package.name),
                        actual: Some(actual_version),
                        expected: expected_text.clone(),
                    });
                }
            }
        }
    }

    drift.sort_by(|a, b| a.path.cmp(&b.path).then(a.field.cmp(&b.field)));
    Ok(drift)
}

fn apply_sync(
    surface: &ReleaseSurface,
    expected: &Version,
    write: bool,
) -> Result<(Vec<SyncEdit>, Vec<String>), String> {
    let release_names: BTreeSet<String> = surface
        .packages
        .iter()
        .map(|package| package.name.clone())
        .collect();
    let mut edits = Vec::new();
    let mut changed_files = BTreeSet::new();
    let expected_text = expected.to_string();

    for package in &surface.packages {
        let file_edits = sync_manifest_versions(package, &release_names, &expected_text, write)?;
        if !file_edits.is_empty() {
            changed_files.insert(package.manifest_relative.clone());
            edits.extend(file_edits);
        }
    }

    for metadata in &surface.metadata_files {
        let actual = read_metadata_version(&metadata.path)?;
        if actual.as_deref() == Some(expected_text.as_str()) {
            continue;
        }
        if write {
            write_metadata_version(&metadata.path, expected)?;
        }
        changed_files.insert(metadata.relative.clone());
        edits.push(SyncEdit {
            path: metadata.relative.clone(),
            field: "version".to_string(),
            before: actual,
            after: expected_text.clone(),
        });
    }

    if let Some(cargo_lock) = surface.cargo_lock.as_ref() {
        for package in &surface.packages {
            let actual = read_cargo_lock_version_for_package(cargo_lock, &package.name)?;
            if actual.as_deref() == Some(expected_text.as_str()) {
                continue;
            }
            if actual.is_none() {
                continue;
            }
            if write {
                write_cargo_lock_version_for_package(cargo_lock, Some(&package.name), expected)?;
            }
            changed_files.insert("Cargo.lock".to_string());
            edits.push(SyncEdit {
                path: "Cargo.lock".to_string(),
                field: format!("package.{}.version", package.name),
                before: actual,
                after: expected_text.clone(),
            });
        }
    }

    let changed_files = changed_files.into_iter().collect::<Vec<_>>();
    Ok((edits, changed_files))
}

fn sync_manifest_versions(
    package: &ReleasePackage,
    release_names: &BTreeSet<String>,
    expected: &str,
    write: bool,
) -> Result<Vec<SyncEdit>, String> {
    let content = fs::read_to_string(&package.manifest_path)
        .map_err(|e| format!("Failed to read {}: {}", package.manifest_path.display(), e))?;
    let mut doc = content
        .parse::<DocumentMut>()
        .map_err(|e| format!("Failed to parse {}: {}", package.manifest_path.display(), e))?;
    let mut edits = Vec::new();

    let current_package_version = doc["package"]["version"].as_str().map(str::to_string);
    if current_package_version.as_deref() != Some(expected) {
        edits.push(SyncEdit {
            path: package.manifest_relative.clone(),
            field: "package.version".to_string(),
            before: current_package_version,
            after: expected.to_string(),
        });
        if write {
            doc["package"]["version"] = value(expected);
        }
    }

    sync_dependency_tables_in_item(
        doc.as_item_mut(),
        "",
        release_names,
        expected,
        &package.manifest_relative,
        &mut edits,
    );

    if write && !edits.is_empty() {
        fs::write(&package.manifest_path, doc.to_string())
            .map_err(|e| format!("Failed to write {}: {}", package.manifest_path.display(), e))?;
    }

    Ok(edits)
}

fn sync_dependency_tables_in_item(
    item: &mut Item,
    prefix: &str,
    release_names: &BTreeSet<String>,
    expected: &str,
    manifest_relative: &str,
    edits: &mut Vec<SyncEdit>,
) {
    let Some(table) = item.as_table_mut() else {
        return;
    };

    let keys = table
        .iter()
        .map(|(key, _)| key.to_string())
        .collect::<Vec<_>>();
    for key in keys {
        let next_prefix = if prefix.is_empty() {
            key.clone()
        } else {
            format!("{}.{}", prefix, key)
        };
        let Some(child) = table.get_mut(&key) else {
            continue;
        };
        if matches!(
            key.as_str(),
            "dependencies" | "dev-dependencies" | "build-dependencies"
        ) {
            if let Some(dep_table) = child.as_table_mut() {
                sync_dependency_entries(
                    dep_table,
                    &next_prefix,
                    release_names,
                    expected,
                    manifest_relative,
                    edits,
                );
            }
            continue;
        }
        sync_dependency_tables_in_item(
            child,
            &next_prefix,
            release_names,
            expected,
            manifest_relative,
            edits,
        );
    }
}

fn sync_dependency_entries(
    table: &mut Table,
    section_name: &str,
    release_names: &BTreeSet<String>,
    expected: &str,
    manifest_relative: &str,
    edits: &mut Vec<SyncEdit>,
) {
    let keys = table
        .iter()
        .map(|(key, _)| key.to_string())
        .collect::<Vec<_>>();
    for dependency_name in keys {
        let Some(item) = table.get_mut(&dependency_name) else {
            continue;
        };
        if !item_matches_release_dependency(&dependency_name, item, release_names) {
            continue;
        }
        match item {
            Item::Value(value_item) => {
                let Some(inline) = value_item.as_inline_table_mut() else {
                    continue;
                };
                if inline.get("path").is_none() {
                    continue;
                }
                let before = inline
                    .get("version")
                    .and_then(Value::as_str)
                    .map(|value| value.to_string());
                if before.as_deref() == Some(expected) {
                    continue;
                }
                inline.insert("version", Value::from(expected));
                edits.push(SyncEdit {
                    path: manifest_relative.to_string(),
                    field: format!("{}.{}.version", section_name, dependency_name),
                    before,
                    after: expected.to_string(),
                });
            }
            Item::Table(dep_table) => {
                if dep_table.get("path").is_none() {
                    continue;
                }
                let before = dep_table
                    .get("version")
                    .and_then(Item::as_str)
                    .map(|value| value.to_string());
                if before.as_deref() == Some(expected) {
                    continue;
                }
                dep_table["version"] = value(expected);
                edits.push(SyncEdit {
                    path: manifest_relative.to_string(),
                    field: format!("{}.{}.version", section_name, dependency_name),
                    before,
                    after: expected.to_string(),
                });
            }
            _ => {}
        }
    }
}

fn item_matches_release_dependency(
    dependency_name: &str,
    item: &Item,
    release_names: &BTreeSet<String>,
) -> bool {
    if release_names.contains(dependency_name) {
        return true;
    }

    let aliased_package_name = match item {
        Item::Value(value_item) => value_item
            .as_inline_table()
            .and_then(|table| table.get("package"))
            .and_then(Value::as_str),
        Item::Table(table) => table.get("package").and_then(Item::as_str),
        _ => None,
    };

    aliased_package_name
        .map(|package_name| release_names.contains(package_name))
        .unwrap_or(false)
}

fn run_validation(
    surface: &ReleaseSurface,
    options: &WorkspaceVersionValidateOptions,
) -> Result<WorkspaceValidateReport, String> {
    let mut issues = match resolve_expected_version(surface, None) {
        Ok(expected) => collect_drift(surface, &expected)?,
        Err(error) if error.contains("Workspace root has no package.version") => Vec::new(),
        Err(error) => return Err(error),
    };
    if let Some(package_name) = options.package.as_deref() {
        issues.retain(|issue| {
            issue.path == "Cargo.lock"
                || issue.path.ends_with("README.md")
                || issue.path.ends_with("openapi.yaml")
                || issue.path.ends_with("openapi.yml")
                || issue.path.ends_with("openapi.json")
                || issue.field.contains(package_name)
                || issue.path.contains(package_name)
        });
    }

    let mut commands = Vec::new();
    if options.cargo_check {
        let mut command = Command::new(cargo_program());
        command
            .current_dir(&surface.repo_root)
            .arg("check")
            .arg("-q");
        if let Some(package) = options.package.as_deref() {
            command.arg("-p").arg(package);
        }
        commands.push(run_command_capture(command, "cargo check -q")?);
    }

    if options.package_dry_run {
        commands.extend(run_package_dry_run_validation(
            surface,
            options.package.as_deref(),
        )?);
    }

    let ok = issues.is_empty() && commands.iter().all(|result| result.success);
    Ok(WorkspaceValidateReport {
        repo_root: display_path(&surface.repo_root),
        ok,
        issues,
        commands,
    })
}

fn select_packages_for_validation<'a>(
    surface: &'a ReleaseSurface,
    package_name: Option<&str>,
) -> Result<Vec<&'a ReleasePackage>, String> {
    if let Some(package_name) = package_name {
        let package = surface
            .packages
            .iter()
            .find(|package| package.name == package_name)
            .ok_or_else(|| format!("Unknown workspace package `{}`.", package_name))?;
        return Ok(vec![package]);
    }
    Ok(surface
        .packages
        .iter()
        .filter(|package| package.publishable && !package.publish_excluded)
        .collect())
}

fn select_ordered_packages_for_validation<'a>(
    surface: &'a ReleaseSurface,
    package_name: Option<&str>,
) -> Result<Vec<&'a ReleasePackage>, String> {
    let selected = select_packages_for_validation(surface, package_name)?;
    let selected_names: BTreeSet<String> = selected
        .iter()
        .map(|package| package.name.clone())
        .collect();
    let ordered_names = topological_package_order(surface)?;
    Ok(ordered_names
        .into_iter()
        .filter(|name| selected_names.contains(name))
        .filter_map(|name| {
            selected
                .iter()
                .find(|package| package.name == name)
                .copied()
        })
        .collect())
}

fn run_package_dry_run_validation(
    surface: &ReleaseSurface,
    package_name: Option<&str>,
) -> Result<Vec<ValidationCommandResult>, String> {
    let packages = select_ordered_packages_for_validation(surface, package_name)?;
    let mut results = Vec::new();

    for package in packages {
        let label = format!(
            "cargo publish --dry-run --locked --no-verify --manifest-path {}",
            package.manifest_relative
        );
        let repo_root = surface.repo_root.clone();
        let manifest_path = package.manifest_path.clone();
        let mut result = run_publish_dry_run_capture(&repo_root, &manifest_path, &label)?;
        if !result.success {
            if is_unpublished_workspace_dependency_error(&result.stderr) {
                let fallback_label = format!(
                    "cargo package --allow-dirty --no-verify --manifest-path {}",
                    package.manifest_relative
                );
                let fallback_result =
                    run_package_capture(&repo_root, &manifest_path, &fallback_label)?;
                if fallback_result.success {
                    result = ValidationCommandResult {
                        command: fallback_label,
                        success: true,
                        exit_code: fallback_result.exit_code,
                        stderr: fallback_result.stderr,
                        warning: Some(format!(
                            "Registry dry-run skipped for `{}`: workspace dependencies are not on crates.io yet. Local packaging succeeded.",
                            package.name
                        )),
                    };
                } else {
                    result.stderr = append_validation_hint(&result.stderr);
                }
            } else {
                result.stderr = append_validation_hint(&result.stderr);
            }
        }
        results.push(result);
    }

    Ok(results)
}

fn is_unpublished_workspace_dependency_error(stderr: &str) -> bool {
    stderr.contains("no matching package named")
        || stderr.contains("failed to select a version for the requirement")
}

fn is_transient_registry_error(stderr: &str) -> bool {
    stderr.contains("Could not resolve host")
        || stderr.contains("Could not resolve hostname")
        || stderr.contains("failed to update registry")
        || stderr.contains("download of config.json failed")
}

fn append_validation_hint(stderr: &str) -> String {
    let mut message = stderr.to_string();
    if stderr.contains("Access is denied") || stderr.contains("os error 5") {
        message.push_str(
            "\nHint: close any running `xbp` processes before package dry-run validation on Windows.",
        );
    }
    if is_transient_registry_error(stderr) {
        message
            .push_str("\nHint: crates.io was unreachable. Check network connectivity and retry.");
    }
    if is_unpublished_workspace_dependency_error(stderr) {
        message.push_str(
            "\nHint: publish workspace dependencies first, or rely on the local `cargo package` fallback.",
        );
    }
    message
}

fn run_publish_dry_run_capture(
    repo_root: &Path,
    manifest_path: &Path,
    label: &str,
) -> Result<ValidationCommandResult, String> {
    let build = || {
        let mut command = Command::new(cargo_program());
        command
            .current_dir(repo_root)
            .arg("publish")
            .arg("--dry-run")
            .arg("--locked")
            .arg("--no-verify")
            .arg("--manifest-path")
            .arg(manifest_path);
        command
    };
    run_command_capture_with_retry(build, label)
}

fn run_package_capture(
    repo_root: &Path,
    manifest_path: &Path,
    label: &str,
) -> Result<ValidationCommandResult, String> {
    let build = || {
        let mut command = Command::new(cargo_program());
        command
            .current_dir(repo_root)
            .arg("package")
            .arg("--allow-dirty")
            .arg("--no-verify")
            .arg("--manifest-path")
            .arg(manifest_path);
        command
    };
    run_command_capture_with_retry(build, label)
}

fn run_command_capture_with_retry(
    build_command: impl Fn() -> Command,
    label: &str,
) -> Result<ValidationCommandResult, String> {
    let first = run_command_capture(build_command(), label)?;
    if first.success || !is_transient_registry_error(&first.stderr) {
        return Ok(first);
    }

    thread::sleep(StdDuration::from_secs(2));
    let mut retry = run_command_capture(build_command(), format!("{label} (retry)"))?;
    if !retry.success {
        retry.stderr = append_validation_hint(&retry.stderr);
    }
    Ok(retry)
}

async fn build_publish_plan_report(
    surface: &ReleaseSurface,
    options: &WorkspacePublishPlanOptions,
) -> Result<WorkspacePublishPlanReport, String> {
    let visibility = collect_crates_io_visibility(surface).await?;
    let selection = PublishSelection {
        from: None,
        only: options.only.clone(),
        include_prereqs: options.include_prereqs,
    };
    let plan = build_publish_plan(surface, &visibility, Some(&selection))?;
    let expected = resolve_expected_version(surface, None).unwrap_or_else(|_| {
        surface
            .packages
            .first()
            .map(|package| package.version.clone())
            .unwrap_or_else(|| Version::new(0, 0, 0))
    });
    let surface_issues = collect_publish_surface_issues(surface, Some(&selection), &expected)?;
    Ok(WorkspacePublishPlanReport {
        repo_root: display_path(&surface.repo_root),
        requested_package: plan.requested_package,
        included_prereqs: plan.included_prereqs,
        required_closure: plan.required_closure,
        packages: plan.items,
        publish_order: plan.publish_order,
        surface_issues,
    })
}

fn run_publish_heal(
    surface: &ReleaseSurface,
    options: &WorkspacePublishHealOptions,
) -> Result<WorkspacePublishHealReport, String> {
    let selection = PublishSelection {
        from: None,
        only: options.only.clone(),
        include_prereqs: options.include_prereqs,
    };
    let expected = resolve_expected_version(surface, options.version.as_deref())?;
    let issues = collect_publish_surface_issues(surface, Some(&selection), &expected)?;
    let (edits, files_changed) =
        apply_publish_surface_heals(surface, Some(&selection), &expected, options.write)?;
    Ok(WorkspacePublishHealReport {
        repo_root: display_path(&surface.repo_root),
        write: options.write,
        expected_version: expected.to_string(),
        issues,
        edits,
        files_changed,
    })
}

#[derive(Debug, Clone)]
pub(crate) struct WorkspaceVersionDriftSummary {
    pub expected_version: Version,
    pub drift_count: usize,
    pub preview: Vec<String>,
}

pub(crate) fn inspect_workspace_version_drift(
    repo_root: &Path,
    expected_version: &Version,
) -> Result<Option<WorkspaceVersionDriftSummary>, String> {
    let surface = match discover_release_surface(repo_root) {
        Ok(surface) => surface,
        Err(_) => return Ok(None),
    };
    if surface.repo_root != repo_root {
        return Ok(None);
    }
    if surface.packages.len() <= 1 && surface.config_path.is_none() {
        return Ok(None);
    }

    let drift = collect_drift(&surface, expected_version)?;
    if drift.is_empty() {
        return Ok(None);
    }

    let preview = drift
        .iter()
        .take(6)
        .map(|entry| {
            format!(
                "{} {}: {} -> {}",
                entry.path,
                entry.field,
                entry.actual.as_deref().unwrap_or("<missing>"),
                entry.expected
            )
        })
        .collect();

    Ok(Some(WorkspaceVersionDriftSummary {
        expected_version: expected_version.clone(),
        drift_count: drift.len(),
        preview,
    }))
}

pub(crate) fn sync_workspace_to_version(
    repo_root: &Path,
    expected_version: &Version,
) -> Result<Vec<String>, String> {
    let surface = discover_release_surface(repo_root)?;
    let (_edits, changed_files) = apply_sync(&surface, expected_version, true)?;
    Ok(changed_files)
}

/// Inspect crates.io publish-surface issues for a release selection (path-dep
/// closure under `--only` / full workspace). Used by `version release --publish`.
pub(crate) fn inspect_publish_surface_for_release(
    repo_root: &Path,
    expected_version: &Version,
    only_package: Option<&str>,
) -> Result<Option<PublishSurfaceHealSummary>, String> {
    let surface = match discover_release_surface(repo_root) {
        Ok(surface) => surface,
        Err(_) => return Ok(None),
    };
    if surface.repo_root != repo_root {
        return Ok(None);
    }
    if surface.packages.len() <= 1 && surface.config_path.is_none() {
        return Ok(None);
    }

    let selection = PublishSelection {
        from: None,
        only: only_package.map(str::to_string),
        include_prereqs: true,
    };
    let issues = collect_publish_surface_issues(&surface, Some(&selection), expected_version)?;
    if issues.is_empty() {
        return Ok(None);
    }

    let auto_fixable_count = issues.iter().filter(|issue| issue.auto_fixable).count();
    let preview = issues
        .iter()
        .take(8)
        .map(|issue| {
            format!(
                "{}: {} ({})",
                issue.package,
                issue.detail,
                if issue.auto_fixable {
                    "auto-fixable"
                } else {
                    "manual"
                }
            )
        })
        .collect();

    Ok(Some(PublishSurfaceHealSummary {
        expected_version: expected_version.clone(),
        issue_count: issues.len(),
        auto_fixable_count,
        preview,
    }))
}

/// Apply auto-fixable publish-surface heals (enable `publish`, pin versions,
/// workspace dep versions, package metadata). Returns changed relative paths.
pub(crate) fn heal_publish_surface_for_release(
    repo_root: &Path,
    expected_version: &Version,
    only_package: Option<&str>,
) -> Result<Vec<String>, String> {
    let surface = discover_release_surface(repo_root)?;
    let selection = PublishSelection {
        from: None,
        only: only_package.map(str::to_string),
        include_prereqs: true,
    };
    let (_edits, files) =
        apply_publish_surface_heals(&surface, Some(&selection), expected_version, true)?;
    Ok(files)
}

pub(crate) async fn resolve_manifest_workspace_publish(
    manifest_path: &Path,
    include_prereqs: bool,
) -> Result<ManifestWorkspacePublishResolution, String> {
    let surface = discover_release_surface_from_manifest(manifest_path)?;
    let package = surface
        .packages
        .iter()
        .find(|package| same_path(&package.manifest_path, manifest_path))
        .ok_or_else(|| {
            format!(
                "Manifest {} is not a publishable package in the resolved Cargo workspace.",
                manifest_path.display()
            )
        })?;
    let visibility = collect_crates_io_visibility(&surface).await?;
    let plan = build_publish_plan(
        &surface,
        &visibility,
        Some(&PublishSelection {
            from: None,
            only: Some(package.name.clone()),
            include_prereqs,
        }),
    )?;
    Ok(ManifestWorkspacePublishResolution {
        workspace_root: surface.repo_root.clone(),
        requested_package: package.name.clone(),
        included_prereqs: plan.included_prereqs,
        required_closure: plan.required_closure,
        packages: plan.items,
        publish_order: build_publish_command_targets(&surface, &plan.publish_order)?,
    })
}

async fn run_publish(
    surface: &ReleaseSurface,
    options: &WorkspacePublishRunOptions,
) -> Result<WorkspacePublishRunReport, String> {
    if options.only.is_some() && options.from.is_some() {
        return Err("`--only` cannot be combined with `--from`.".to_string());
    }
    if !options.allow_dirty {
        enforce_clean_worktree(&surface.repo_root)?;
    }

    let validation = run_validation(
        surface,
        &WorkspaceVersionValidateOptions {
            package: options.only.clone(),
            cargo_check: false,
            package_dry_run: false,
        },
    )?;
    if !validation.ok {
        return Err("Workspace has structural publish blockers. Run `xbp version workspace validate` for details.".to_string());
    }

    let visibility = collect_crates_io_visibility(surface).await?;
    let selection = PublishSelection {
        from: options.from.clone(),
        only: options.only.clone(),
        include_prereqs: options.include_prereqs,
    };
    let plan = build_publish_plan(surface, &visibility, Some(&selection))?;
    let blockers = collect_publish_blockers(&plan.items);
    if !blockers.is_empty() {
        let expected = resolve_expected_version(surface, None).ok();
        let surface_issues = expected
            .as_ref()
            .and_then(|version| {
                collect_publish_surface_issues(surface, Some(&selection), version).ok()
            })
            .unwrap_or_default();
        return Err(render_workspace_publish_blockers(
            surface,
            &plan,
            Some(options),
            &blockers,
            &surface_issues,
        ));
    }

    let mut item_by_name = BTreeMap::new();
    for item in &plan.items {
        item_by_name.insert(item.package.clone(), item.clone());
    }

    let mut published = Vec::new();
    let mut skipped = Vec::new();
    let mut failed = Vec::new();
    let publish_order = plan.publish_order.clone();
    let total_in_order = publish_order.len();
    for (index, package_name) in publish_order.iter().enumerate() {
        let Some(item) = item_by_name.get(package_name) else {
            continue;
        };
        if !item.publish_needed {
            skipped.push(format!("{} {}", item.package, item.reason));
            continue;
        }
        if !item.blocked_by.is_empty() {
            let message = format!("{} blocked by {}", item.package, item.blocked_by.join(", "));
            failed.push(message.clone());
            if !options.continue_on_error {
                break;
            }
            continue;
        }

        let package = surface
            .packages
            .iter()
            .find(|package| package.name == item.package)
            .ok_or_else(|| format!("Missing package `{}` in release surface.", item.package))?;
        let cargo_publish = format!(
            "cargo publish --locked --manifest-path {}{}",
            package.manifest_relative,
            if options.allow_dirty {
                " --allow-dirty"
            } else {
                ""
            }
        );
        println!("{}", cargo_publish);
        if options.dry_run {
            published.push(format!("{} (dry-run)", item.package));
            continue;
        }

        let status = Command::new(cargo_program())
            .current_dir(&surface.repo_root)
            .arg("publish")
            .arg("--locked")
            .arg("--manifest-path")
            .arg(&package.manifest_path)
            .args(options.allow_dirty.then_some("--allow-dirty"))
            .status()
            .map_err(|e| {
                format!(
                    "Failed to execute cargo publish for {}: {}",
                    item.package, e
                )
            })?;
        if !status.success() {
            let message = format!(
                "{} publish failed with exit code {:?}",
                item.package,
                status.code()
            );
            failed.push(message.clone());
            if !options.continue_on_error {
                break;
            }
            continue;
        }

        // Soft-timeout on the last package: cargo already confirmed publish.
        // Intermediate packages stay hard so dependents can resolve the new version.
        let is_last = index + 1 == total_in_order;
        wait_for_crates_io_visibility(
            &item.package,
            &item.version,
            options.timeout_seconds,
            options.poll_interval_seconds,
            is_last,
        )
        .await?;
        published.push(item.package.clone());
    }

    Ok(WorkspacePublishRunReport {
        repo_root: display_path(&surface.repo_root),
        dry_run: options.dry_run,
        requested_package: plan.requested_package,
        included_prereqs: plan.included_prereqs,
        required_closure: plan.required_closure,
        published,
        skipped,
        failed,
    })
}

fn build_publish_command_targets(
    surface: &ReleaseSurface,
    publish_order: &[String],
) -> Result<Vec<WorkspacePublishCommandTarget>, String> {
    let mut targets = Vec::new();
    for package_name in publish_order {
        let package = surface
            .packages
            .iter()
            .find(|package| &package.name == package_name)
            .ok_or_else(|| format!("Missing package `{}` in release surface.", package_name))?;
        targets.push(WorkspacePublishCommandTarget {
            package: package.name.clone(),
            version: package.version.to_string(),
            manifest_path: package.manifest_path.clone(),
            manifest_relative: package.manifest_relative.clone(),
        });
    }
    Ok(targets)
}

#[derive(Debug, Clone)]
struct PublishSelection {
    from: Option<String>,
    only: Option<String>,
    include_prereqs: bool,
}

#[derive(Debug, Clone)]
struct ResolvedPublishSelection {
    requested_package: Option<String>,
    selected_packages: Vec<String>,
    included_prereqs: Vec<String>,
    required_closure: Vec<String>,
}

#[derive(Debug, Clone)]
struct BuiltPublishPlan {
    requested_package: Option<String>,
    included_prereqs: Vec<String>,
    required_closure: Vec<String>,
    items: Vec<PublishPlanItem>,
    publish_order: Vec<String>,
}

fn build_publish_plan(
    surface: &ReleaseSurface,
    visibility: &BTreeMap<String, bool>,
    selection: Option<&PublishSelection>,
) -> Result<BuiltPublishPlan, String> {
    let ordered_packages = topological_package_order(surface)?;
    let selected = resolve_selected_packages(surface, &ordered_packages, selection)?;
    let selected_set: BTreeSet<String> = selected.selected_packages.iter().cloned().collect();
    let mut available = visibility.clone();
    let mut items = Vec::new();
    let mut publish_order = Vec::new();

    for package_name in ordered_packages {
        if !selected_set.contains(&package_name) {
            continue;
        }
        let package = surface
            .packages
            .iter()
            .find(|package| package.name == package_name)
            .ok_or_else(|| format!("Missing package `{}` in release surface.", package_name))?;
        let visible = visibility.get(&package.name).copied();
        let mut publish_needed = false;
        let mut blocked_by = Vec::new();
        let reason = if visible == Some(true) {
            "already visible on crates.io".to_string()
        } else if !package.publishable {
            "publish disabled in package metadata (auto-fix available)".to_string()
        } else if package.publish_excluded {
            "publish excluded by workspace release config".to_string()
        } else if !package.publish_missing_version_pins.is_empty() {
            format!(
                "missing version pins for {} (auto-fix available)",
                package.publish_missing_version_pins.join(", ")
            )
        } else {
            for dependency in &package.publish_internal_dependencies {
                if available.get(dependency).copied().unwrap_or(false) {
                    continue;
                }
                // Private path deps are never crates.io-visible; treat as hard
                // blockers until the publish surface is healed.
                blocked_by.push(dependency.clone());
            }
            if blocked_by.is_empty() {
                publish_needed = true;
                publish_order.push(package.name.clone());
                available.insert(package.name.clone(), true);
                "publish required".to_string()
            } else {
                format!("waiting for {}", blocked_by.join(", "))
            }
        };

        items.push(PublishPlanItem {
            package: package.name.clone(),
            manifest: package.manifest_relative.clone(),
            version: package.version.to_string(),
            publishable: package.publishable
                && !package.publish_excluded
                && package.publish_missing_version_pins.is_empty(),
            crates_io_visible: visible,
            publish_needed,
            blocked_by,
            reason,
        });
    }

    Ok(BuiltPublishPlan {
        requested_package: selected.requested_package,
        included_prereqs: selected.included_prereqs,
        required_closure: selected.required_closure,
        items,
        publish_order,
    })
}

fn resolve_selected_packages(
    surface: &ReleaseSurface,
    ordered_packages: &[String],
    selection: Option<&PublishSelection>,
) -> Result<ResolvedPublishSelection, String> {
    let Some(selection) = selection else {
        return Ok(ResolvedPublishSelection {
            requested_package: None,
            selected_packages: ordered_packages.to_vec(),
            included_prereqs: Vec::new(),
            required_closure: ordered_packages.to_vec(),
        });
    };
    if let Some(only) = selection.only.as_deref() {
        if !ordered_packages.iter().any(|package| package == only) {
            return Err(format!("Unknown package `{}` for `--only`.", only));
        }
        let required_closure = collect_publish_closure(surface, only, ordered_packages)?;
        let selected_packages = if selection.include_prereqs {
            required_closure.clone()
        } else {
            vec![only.to_string()]
        };
        let included_prereqs = required_closure
            .iter()
            .filter(|package| package.as_str() != only)
            .cloned()
            .collect::<Vec<_>>();
        return Ok(ResolvedPublishSelection {
            requested_package: Some(only.to_string()),
            selected_packages,
            included_prereqs: if selection.include_prereqs {
                included_prereqs
            } else {
                Vec::new()
            },
            required_closure,
        });
    }
    if let Some(from) = selection.from.as_deref() {
        let start = ordered_packages
            .iter()
            .position(|package| package == from)
            .ok_or_else(|| format!("Unknown package `{}` for `--from`.", from))?;
        return Ok(ResolvedPublishSelection {
            requested_package: None,
            selected_packages: ordered_packages[start..].to_vec(),
            included_prereqs: Vec::new(),
            required_closure: ordered_packages[start..].to_vec(),
        });
    }
    Ok(ResolvedPublishSelection {
        requested_package: None,
        selected_packages: ordered_packages.to_vec(),
        included_prereqs: Vec::new(),
        required_closure: ordered_packages.to_vec(),
    })
}

fn collect_publish_closure(
    surface: &ReleaseSurface,
    root_package: &str,
    ordered_packages: &[String],
) -> Result<Vec<String>, String> {
    let mut by_name = BTreeMap::new();
    for package in &surface.packages {
        by_name.insert(package.name.as_str(), package);
    }
    let mut visited = BTreeSet::new();
    collect_publish_closure_visit(root_package, &by_name, &mut visited)?;
    Ok(ordered_packages
        .iter()
        .filter(|package| visited.contains(package.as_str()))
        .cloned()
        .collect())
}

fn collect_publish_closure_visit<'a>(
    package_name: &'a str,
    by_name: &BTreeMap<&'a str, &'a ReleasePackage>,
    visited: &mut BTreeSet<&'a str>,
) -> Result<(), String> {
    if !visited.insert(package_name) {
        return Ok(());
    }
    let package = by_name
        .get(package_name)
        .ok_or_else(|| format!("Missing package `{}` in release surface.", package_name))?;
    for dependency in &package.publish_internal_dependencies {
        collect_publish_closure_visit(dependency, by_name, visited)?;
    }
    Ok(())
}

fn collect_publish_surface_issues(
    surface: &ReleaseSurface,
    selection: Option<&PublishSelection>,
    expected_version: &Version,
) -> Result<Vec<PublishSurfaceIssue>, String> {
    let ordered = topological_package_order(surface)?;
    let resolved = resolve_selected_packages(surface, &ordered, selection)?;
    let selected: BTreeSet<String> = resolved.required_closure.iter().cloned().collect();
    let expected_text = expected_version.to_string();
    let workspace_meta = read_workspace_package_metadata(&surface.repo_root);
    let workspace_dep_versions =
        read_workspace_dependency_path_versions(&surface.repo_root, &selected)?;

    let mut issues = Vec::new();
    for package in &surface.packages {
        if !selected.contains(&package.name) {
            continue;
        }
        if !package.publishable {
            issues.push(PublishSurfaceIssue {
                package: package.name.clone(),
                manifest: package.manifest_relative.clone(),
                kind: PublishSurfaceIssueKind::PublishDisabled,
                detail: "package.publish disables crates.io publish".to_string(),
                auto_fixable: true,
            });
        }
        if package.publish_excluded {
            issues.push(PublishSurfaceIssue {
                package: package.name.clone(),
                manifest: package.manifest_relative.clone(),
                kind: PublishSurfaceIssueKind::PublishExcluded,
                detail: "listed in workspace-release publish.exclude".to_string(),
                auto_fixable: false,
            });
        }
        for pin in &package.publish_missing_version_pins {
            issues.push(PublishSurfaceIssue {
                package: package.name.clone(),
                manifest: package.manifest_relative.clone(),
                kind: PublishSurfaceIssueKind::MissingVersionPin,
                detail: format!("missing path dependency version pin `{pin}`"),
                auto_fixable: true,
            });
        }
        if !package.publishable {
            let missing_meta = missing_package_metadata_fields(&package.manifest_path, &workspace_meta);
            if !missing_meta.is_empty() {
                issues.push(PublishSurfaceIssue {
                    package: package.name.clone(),
                    manifest: package.manifest_relative.clone(),
                    kind: PublishSurfaceIssueKind::MissingPackageMetadata,
                    detail: format!(
                        "missing package metadata fields: {}",
                        missing_meta.join(", ")
                    ),
                    auto_fixable: workspace_meta.has_any(),
                });
            }
        }
    }

    for (name, actual) in workspace_dep_versions {
        if actual.as_deref() == Some(expected_text.as_str()) {
            continue;
        }
        issues.push(PublishSurfaceIssue {
            package: name.clone(),
            manifest: "Cargo.toml".to_string(),
            kind: PublishSurfaceIssueKind::WorkspaceDepVersionDrift,
            detail: format!(
                "[workspace.dependencies.{name}].version is {} (expected {expected_text})",
                actual.as_deref().unwrap_or("<missing>")
            ),
            auto_fixable: true,
        });
    }

    issues.sort_by(|a, b| {
        a.package
            .cmp(&b.package)
            .then(a.detail.cmp(&b.detail))
    });
    Ok(issues)
}

fn apply_publish_surface_heals(
    surface: &ReleaseSurface,
    selection: Option<&PublishSelection>,
    expected_version: &Version,
    write: bool,
) -> Result<(Vec<SyncEdit>, Vec<String>), String> {
    let issues = collect_publish_surface_issues(surface, selection, expected_version)?;
    if !write {
        return Ok((Vec::new(), Vec::new()));
    }

    let mut edits = Vec::new();
    let mut changed = BTreeSet::new();
    let expected_text = expected_version.to_string();
    let workspace_meta = read_workspace_package_metadata(&surface.repo_root);

    let packages_to_enable = issues
        .iter()
        .filter(|issue| {
            issue.auto_fixable
                && matches!(
                    issue.kind,
                    PublishSurfaceIssueKind::PublishDisabled
                        | PublishSurfaceIssueKind::MissingPackageMetadata
                )
        })
        .map(|issue| issue.package.clone())
        .collect::<BTreeSet<_>>();

    for package_name in &packages_to_enable {
        let Some(package) = surface
            .packages
            .iter()
            .find(|package| &package.name == package_name)
        else {
            continue;
        };
        let package_edits =
            heal_package_publish_metadata(package, &workspace_meta, &expected_text)?;
        if !package_edits.is_empty() {
            changed.insert(package.manifest_relative.clone());
            edits.extend(package_edits);
        }
    }

    // Align package + path-dep versions (covers MissingVersionPin).
    let (sync_edits, sync_files) = apply_sync(surface, expected_version, true)?;
    edits.extend(sync_edits);
    for file in sync_files {
        changed.insert(file);
    }

    let workspace_dep_packages = issues
        .iter()
        .filter(|issue| {
            issue.auto_fixable
                && matches!(issue.kind, PublishSurfaceIssueKind::WorkspaceDepVersionDrift)
        })
        .map(|issue| issue.package.clone())
        .collect::<BTreeSet<_>>();
    if !workspace_dep_packages.is_empty() {
        let root_edits = heal_workspace_dependency_versions(
            &surface.repo_root,
            &workspace_dep_packages,
            &expected_text,
        )?;
        if !root_edits.is_empty() {
            changed.insert("Cargo.toml".to_string());
            edits.extend(root_edits);
        }
    }

    Ok((edits, changed.into_iter().collect()))
}

#[derive(Debug, Clone, Default)]
struct WorkspacePackageMetadata {
    homepage: Option<String>,
    repository: Option<String>,
    license: Option<String>,
    authors: Option<String>,
}

impl WorkspacePackageMetadata {
    fn has_any(&self) -> bool {
        self.homepage.is_some()
            || self.repository.is_some()
            || self.license.is_some()
            || self.authors.is_some()
    }
}

fn read_workspace_package_metadata(repo_root: &Path) -> WorkspacePackageMetadata {
    let path = repo_root.join("Cargo.toml");
    let Ok(content) = fs::read_to_string(&path) else {
        return WorkspacePackageMetadata::default();
    };
    let Ok(doc) = content.parse::<DocumentMut>() else {
        return WorkspacePackageMetadata::default();
    };
    let Some(package) = doc
        .get("workspace")
        .and_then(|workspace| workspace.get("package"))
    else {
        return WorkspacePackageMetadata::default();
    };
    WorkspacePackageMetadata {
        homepage: package.get("homepage").and_then(Item::as_str).map(str::to_string),
        repository: package
            .get("repository")
            .and_then(Item::as_str)
            .map(str::to_string),
        license: package.get("license").and_then(Item::as_str).map(str::to_string),
        authors: package.get("authors").and_then(|authors| {
            if let Some(text) = authors.as_str() {
                Some(text.to_string())
            } else if let Some(array) = authors.as_array() {
                let joined = array
                    .iter()
                    .filter_map(|value| value.as_str())
                    .collect::<Vec<_>>()
                    .join(", ");
                if joined.is_empty() {
                    None
                } else {
                    Some(joined)
                }
            } else {
                None
            }
        }),
    }
}

fn missing_package_metadata_fields(
    manifest_path: &Path,
    workspace_meta: &WorkspacePackageMetadata,
) -> Vec<String> {
    let Ok(content) = fs::read_to_string(manifest_path) else {
        return Vec::new();
    };
    let Ok(value) = content.parse::<TomlValue>() else {
        return Vec::new();
    };
    let Some(package) = value.get("package").and_then(TomlValue::as_table) else {
        return Vec::new();
    };
    let mut missing = Vec::new();
    if package.get("homepage").and_then(TomlValue::as_str).is_none()
        && workspace_meta.homepage.is_some()
    {
        missing.push("homepage".to_string());
    }
    if package
        .get("repository")
        .and_then(TomlValue::as_str)
        .is_none()
        && workspace_meta.repository.is_some()
    {
        missing.push("repository".to_string());
    }
    if package.get("license").and_then(TomlValue::as_str).is_none()
        && workspace_meta.license.is_some()
    {
        missing.push("license".to_string());
    }
    missing
}

fn heal_package_publish_metadata(
    package: &ReleasePackage,
    workspace_meta: &WorkspacePackageMetadata,
    _expected_version: &str,
) -> Result<Vec<SyncEdit>, String> {
    let content = fs::read_to_string(&package.manifest_path).map_err(|e| {
        format!(
            "Failed to read {}: {}",
            package.manifest_path.display(),
            e
        )
    })?;
    let mut doc = content.parse::<DocumentMut>().map_err(|e| {
        format!(
            "Failed to parse {}: {}",
            package.manifest_path.display(),
            e
        )
    })?;
    let mut edits = Vec::new();

    let package_table = doc["package"].as_table_mut().ok_or_else(|| {
        format!(
            "Expected [package] table in {}",
            package.manifest_path.display()
        )
    })?;

    if let Some(publish_item) = package_table.get("publish") {
        let should_clear = match publish_item {
            Item::Value(Value::Boolean(formatted)) => !*formatted.value(),
            Item::Value(Value::Array(array)) => array.is_empty(),
            _ => false,
        };
        if should_clear {
            edits.push(SyncEdit {
                path: package.manifest_relative.clone(),
                field: "package.publish".to_string(),
                before: Some(publish_item.to_string().trim().to_string()),
                after: "<removed>".to_string(),
            });
            package_table.remove("publish");
        }
    }

    for (field, source) in [
        ("homepage", workspace_meta.homepage.as_deref()),
        ("repository", workspace_meta.repository.as_deref()),
        ("license", workspace_meta.license.as_deref()),
    ] {
        let Some(value_text) = source else {
            continue;
        };
        let current = package_table.get(field).and_then(Item::as_str);
        if current.is_none() {
            edits.push(SyncEdit {
                path: package.manifest_relative.clone(),
                field: format!("package.{field}"),
                before: None,
                after: value_text.to_string(),
            });
            package_table[field] = value(value_text);
        }
    }

    // Prefer cargo-dist skip for internal control-plane crates unless already configured.
    let has_dist_meta = doc
        .get("package")
        .and_then(|package| package.get("metadata"))
        .and_then(|metadata| metadata.get("dist"))
        .is_some();
    if !has_dist_meta {
        doc["package"]["metadata"]["dist"]["dist"] = value(false);
        edits.push(SyncEdit {
            path: package.manifest_relative.clone(),
            field: "package.metadata.dist.dist".to_string(),
            before: None,
            after: "false".to_string(),
        });
    }

    if !edits.is_empty() {
        fs::write(&package.manifest_path, doc.to_string()).map_err(|e| {
            format!(
                "Failed to write {}: {}",
                package.manifest_path.display(),
                e
            )
        })?;
    }
    Ok(edits)
}

fn read_workspace_dependency_path_versions(
    repo_root: &Path,
    package_names: &BTreeSet<String>,
) -> Result<BTreeMap<String, Option<String>>, String> {
    let path = repo_root.join("Cargo.toml");
    let content = match fs::read_to_string(&path) {
        Ok(content) => content,
        Err(_) => return Ok(BTreeMap::new()),
    };
    let value = match content.parse::<TomlValue>() {
        Ok(value) => value,
        Err(_) => return Ok(BTreeMap::new()),
    };
    let Some(deps) = value
        .get("workspace")
        .and_then(|workspace| workspace.get("dependencies"))
        .and_then(TomlValue::as_table)
    else {
        return Ok(BTreeMap::new());
    };

    let mut versions = BTreeMap::new();
    for (name, dep) in deps {
        if !package_names.contains(name) {
            // Also match when the workspace dep key equals a selected package.
            continue;
        }
        let Some(table) = dep.as_table() else {
            continue;
        };
        if !table.contains_key("path") {
            continue;
        }
        versions.insert(
            name.clone(),
            table
                .get("version")
                .and_then(TomlValue::as_str)
                .map(str::to_string),
        );
    }
    Ok(versions)
}

fn heal_workspace_dependency_versions(
    repo_root: &Path,
    package_names: &BTreeSet<String>,
    expected_version: &str,
) -> Result<Vec<SyncEdit>, String> {
    let path = repo_root.join("Cargo.toml");
    let content = fs::read_to_string(&path)
        .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
    let mut doc = content
        .parse::<DocumentMut>()
        .map_err(|e| format!("Failed to parse {}: {}", path.display(), e))?;
    let mut edits = Vec::new();

    let Some(deps) = doc
        .get_mut("workspace")
        .and_then(|workspace| workspace.as_table_mut())
        .and_then(|workspace| workspace.get_mut("dependencies"))
        .and_then(|deps| deps.as_table_mut())
    else {
        return Ok(edits);
    };

    for name in package_names {
        let Some(dep_item) = deps.get_mut(name) else {
            continue;
        };
        let Some(dep_table) = dep_item.as_table_like_mut() else {
            continue;
        };
        if dep_table.get("path").is_none() {
            continue;
        }
        let current = dep_table
            .get("version")
            .and_then(|item| item.as_str())
            .map(str::to_string);
        if current.as_deref() == Some(expected_version) {
            continue;
        }
        edits.push(SyncEdit {
            path: "Cargo.toml".to_string(),
            field: format!("workspace.dependencies.{name}.version"),
            before: current,
            after: expected_version.to_string(),
        });
        dep_table.insert("version", value(expected_version));
    }

    if !edits.is_empty() {
        fs::write(&path, doc.to_string())
            .map_err(|e| format!("Failed to write {}: {}", path.display(), e))?;
    }
    Ok(edits)
}

fn collect_publish_blockers(items: &[PublishPlanItem]) -> Vec<String> {
    // Orphan packages with publish=false are not blockers unless a selected
    // package that still needs publishing is waiting on them.
    let blocking_deps = items
        .iter()
        .filter(|item| item.crates_io_visible != Some(true) && !item.blocked_by.is_empty())
        .flat_map(|item| item.blocked_by.iter().cloned())
        .collect::<BTreeSet<_>>();

    items
        .iter()
        .filter(|item| {
            if item.crates_io_visible == Some(true) {
                return false;
            }
            if !item.blocked_by.is_empty() {
                return true;
            }
            if !item.publishable {
                // Private package only blocks when something needs it published.
                return blocking_deps.contains(&item.package);
            }
            // Missing pins / excluded packages that are selected and not visible.
            item.reason.contains("missing version pins")
                || item.reason.contains("publish excluded")
        })
        .map(|item| {
            if !item.blocked_by.is_empty() {
                format!("{} blocked by {}", item.package, item.blocked_by.join(", "))
            } else {
                format!("{} {}", item.package, item.reason)
            }
        })
        .collect()
}

fn render_workspace_publish_blockers(
    surface: &ReleaseSurface,
    plan: &BuiltPublishPlan,
    run_options: Option<&WorkspacePublishRunOptions>,
    blockers: &[String],
    surface_issues: &[PublishSurfaceIssue],
) -> String {
    let mut message = String::new();
    message.push_str("Workspace publish is blocked.\n");
    message.push_str(&format!("Repo: {}\n", surface.repo_root.display()));
    if let Some(requested_package) = plan.requested_package.as_deref() {
        message.push_str(&format!("Requested package: {}\n", requested_package));
    }
    if !plan.included_prereqs.is_empty() {
        message.push_str(&format!(
            "Auto-included prerequisites: {}\n",
            plan.included_prereqs.join(", ")
        ));
    }
    if !plan.required_closure.is_empty() {
        message.push_str(&format!(
            "Required publish order: {}\n",
            plan.required_closure.join(" -> ")
        ));
    }
    message.push_str("Blockers:\n");
    for blocker in blockers {
        message.push_str(&format!("- {}\n", blocker));
    }
    let auto_fixable = surface_issues
        .iter()
        .filter(|issue| issue.auto_fixable)
        .collect::<Vec<_>>();
    if !auto_fixable.is_empty() {
        message.push_str("Auto-fixable surface issues:\n");
        for issue in auto_fixable {
            message.push_str(&format!("- {}: {}\n", issue.package, issue.detail));
        }
        if let Some(requested_package) = plan.requested_package.as_deref() {
            message.push_str(&format!(
                "Heal with:\n  xbp version workspace publish heal --repo {} --only {} --include-prereqs --write\n",
                quote_argument(&surface.repo_root),
                requested_package
            ));
        } else {
            message.push_str(&format!(
                "Heal with:\n  xbp version workspace publish heal --repo {} --write\n",
                quote_argument(&surface.repo_root)
            ));
        }
        message.push_str(
            "Or re-run publish with auto-fix enabled (default for `workspace publish run`).\n",
        );
    }
    if let (Some(requested_package), Some(run_options)) =
        (plan.requested_package.as_deref(), run_options)
    {
        if !run_options.include_prereqs {
            message.push_str(&format!(
                "Workspace prerequisite closure required for `{}`.\n\
                 Rerun with prerequisites (recommended):\n\
                   xbp version workspace publish run --repo {} --only {} --include-prereqs{}\n\
                 Or plan first:\n\
                   xbp version workspace publish plan --repo {} --only {} --include-prereqs\n",
                requested_package,
                quote_argument(&surface.repo_root),
                requested_package,
                if run_options.allow_dirty {
                    " --allow-dirty"
                } else {
                    ""
                },
                quote_argument(&surface.repo_root),
                requested_package,
            ));
        }
    }
    message.trim_end().to_string()
}

fn topological_package_order(surface: &ReleaseSurface) -> Result<Vec<String>, String> {
    let package_names = surface
        .packages
        .iter()
        .map(|package| package.name.clone())
        .collect::<BTreeSet<_>>();
    let order_overrides = surface
        .config
        .publish
        .order
        .iter()
        .enumerate()
        .map(|(index, name)| (name.clone(), index))
        .collect::<BTreeMap<_, _>>();
    let mut indegree = BTreeMap::new();
    let mut reverse = BTreeMap::<String, Vec<String>>::new();
    for package in &surface.packages {
        let deps = package
            .publish_internal_dependencies
            .iter()
            .filter(|name| package_names.contains(*name))
            .cloned()
            .collect::<Vec<_>>();
        indegree.insert(package.name.clone(), deps.len());
        for dep in deps {
            reverse.entry(dep).or_default().push(package.name.clone());
        }
    }

    let mut queue = indegree
        .iter()
        .filter_map(|(name, degree)| (*degree == 0).then_some(name.clone()))
        .collect::<Vec<_>>();
    sort_package_names(&mut queue, &order_overrides);

    let mut ordered = Vec::new();
    while let Some(name) = queue.first().cloned() {
        queue.remove(0);
        ordered.push(name.clone());
        if let Some(children) = reverse.get(&name) {
            for child in children {
                if let Some(entry) = indegree.get_mut(child) {
                    *entry -= 1;
                    if *entry == 0 {
                        queue.push(child.clone());
                    }
                }
            }
            sort_package_names(&mut queue, &order_overrides);
        }
    }

    if ordered.len() != surface.packages.len() {
        return Err(
            "Workspace package graph contains a publish-relevant dependency cycle.".to_string(),
        );
    }
    Ok(ordered)
}

fn sort_package_names(names: &mut [String], overrides: &BTreeMap<String, usize>) {
    names.sort_by(|a, b| {
        overrides
            .get(a)
            .copied()
            .unwrap_or(usize::MAX)
            .cmp(&overrides.get(b).copied().unwrap_or(usize::MAX))
            .then(a.cmp(b))
    });
}

async fn collect_crates_io_visibility(
    surface: &ReleaseSurface,
) -> Result<BTreeMap<String, bool>, String> {
    let client = crates_io_client()?;
    let mut visibility = BTreeMap::new();
    for package in &surface.packages {
        if !package.publishable || package.publish_excluded {
            visibility.insert(package.name.clone(), false);
            continue;
        }
        visibility.insert(
            package.name.clone(),
            crates_io_has_exact_version(&client, &package.name, &package.version.to_string())
                .await?,
        );
    }
    Ok(visibility)
}

async fn wait_for_crates_io_visibility(
    package: &str,
    version: &str,
    timeout_seconds: f64,
    poll_interval_seconds: f64,
    soft_on_timeout: bool,
) -> Result<(), String> {
    let timeout = Duration::from_secs_f64(timeout_seconds.max(1.0));
    let poll = Duration::from_secs_f64(poll_interval_seconds.max(0.5));
    let deadline = Instant::now() + timeout;
    let client = crates_io_client()?;
    loop {
        match crates_io_version_lookup(&client, package, version).await? {
            CratesIoLookup::Found => return Ok(()),
            CratesIoLookup::NotFound | CratesIoLookup::Retryable => {}
        }
        if Instant::now() >= deadline {
            let message = format!(
                "{} {} was published, but did not become visible on crates.io within {:.0}s",
                package, version, timeout_seconds
            );
            if soft_on_timeout {
                eprintln!(
                    "Warning: registry visibility still pending for {}@{} — continuing because cargo already reported a successful publish. Check https://crates.io/crates/{}",
                    package, version, package
                );
                return Ok(());
            }
            return Err(message);
        }
        sleep(poll).await;
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum CratesIoLookup {
    Found,
    NotFound,
    Retryable,
}

async fn crates_io_version_lookup(
    client: &reqwest::Client,
    package: &str,
    version: &str,
) -> Result<CratesIoLookup, String> {
    let url = format!("https://crates.io/api/v1/crates/{}/{}", package, version);
    let response = client
        .get(url)
        .send()
        .await
        .map_err(|e| format!("Failed crates.io lookup for {} {}: {}", package, version, e))?;
    let status = response.status();
    if status.is_success() {
        return Ok(CratesIoLookup::Found);
    }
    if status == reqwest::StatusCode::NOT_FOUND {
        return Ok(CratesIoLookup::NotFound);
    }
    if status == reqwest::StatusCode::FORBIDDEN {
        return Err(format!(
            "crates.io rejected the visibility lookup for {} {} with HTTP 403 \
(descriptive User-Agent required). If cargo already printed Published, the crate is live.",
            package, version
        ));
    }
    if status == reqwest::StatusCode::TOO_MANY_REQUESTS || status.is_server_error() {
        return Ok(CratesIoLookup::Retryable);
    }
    Ok(CratesIoLookup::NotFound)
}

async fn crates_io_has_exact_version(
    client: &reqwest::Client,
    package: &str,
    version: &str,
) -> Result<bool, String> {
    Ok(matches!(
        crates_io_version_lookup(client, package, version).await?,
        CratesIoLookup::Found
    ))
}

fn crates_io_client() -> Result<reqwest::Client, String> {
    reqwest::Client::builder()
        .user_agent(format!(
            "xbp/{} (https://github.com/xylex-group/xbp)",
            env!("CARGO_PKG_VERSION")
        ))
        .build()
        .map_err(|e| format!("Failed to build crates.io HTTP client: {}", e))
}

fn enforce_clean_worktree(project_root: &Path) -> Result<(), String> {
    let Some(GitWorktreeState { is_dirty, .. }) = git_worktree_state(project_root)? else {
        return Ok(());
    };
    if is_dirty {
        return Err(
            "Workspace repo has uncommitted changes. Re-run with `--allow-dirty` to override."
                .to_string(),
        );
    }
    Ok(())
}

fn resolve_expected_version(
    surface: &ReleaseSurface,
    explicit: Option<&str>,
) -> Result<Version, String> {
    if let Some(explicit) = explicit {
        return parse_version(explicit);
    }
    if let Some(root_package_name) = surface.root_package_name.as_ref() {
        return surface
            .packages
            .iter()
            .find(|package| &package.name == root_package_name)
            .map(|package| package.version.clone())
            .ok_or_else(|| "Could not resolve the root package version.".to_string());
    }

    let root_manifest = surface.repo_root.join("Cargo.toml");
    resolve_cargo_package_version(&root_manifest)?
        .ok_or_else(|| {
            "Workspace root has no package.version or workspace.package.version; pass `--version` explicitly.".to_string()
        })
        .and_then(|version| parse_version(&version))
}

fn load_cargo_metadata(repo_root: &Path) -> Result<CargoMetadata, String> {
    let mut command = Command::new(cargo_program());
    command
        .current_dir(repo_root)
        .args(["metadata", "--format-version", "1", "--no-deps"]);
    load_cargo_metadata_command(&mut command)
}

fn load_cargo_metadata_for_manifest(manifest_path: &Path) -> Result<CargoMetadata, String> {
    let manifest_dir = manifest_path.parent().unwrap_or_else(|| Path::new("."));
    let mut command = Command::new(cargo_program());
    command
        .current_dir(manifest_dir)
        .arg("metadata")
        .arg("--format-version")
        .arg("1")
        .arg("--no-deps")
        .arg("--manifest-path")
        .arg(manifest_path);
    load_cargo_metadata_command(&mut command)
}

fn load_cargo_metadata_command(command: &mut Command) -> Result<CargoMetadata, String> {
    if !cargo_command_exists() {
        return Err("`cargo` is required to inspect workspace metadata.".to_string());
    }
    let output = command
        .output()
        .map_err(|e| format!("Failed to run `cargo metadata`: {}", e))?;
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
        return Err(format!("`cargo metadata` failed: {}", stderr));
    }
    serde_json::from_slice::<CargoMetadata>(&output.stdout)
        .map_err(|e| format!("Failed to parse cargo metadata JSON: {}", e))
}

fn load_workspace_release_config(path: Option<&Path>) -> Result<WorkspaceReleaseConfig, String> {
    let Some(path) = path else {
        return Ok(WorkspaceReleaseConfig::default());
    };
    let content = fs::read_to_string(path)
        .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
    serde_yaml::from_str(&content).map_err(|e| format!("Failed to parse {}: {}", path.display(), e))
}

fn run_command_capture(
    mut command: Command,
    label: impl Into<String>,
) -> Result<ValidationCommandResult, String> {
    let label = label.into();
    let output = command
        .output()
        .map_err(|e| format!("Failed to run `{}`: {}", label, e))?;
    Ok(ValidationCommandResult {
        command: label,
        success: output.status.success(),
        exit_code: output.status.code(),
        stderr: String::from_utf8_lossy(&output.stderr).trim().to_string(),
        warning: None,
    })
}

fn read_metadata_version(path: &Path) -> Result<Option<String>, String> {
    let file_name = path
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or_default();
    match file_name {
        "openapi.yaml" | "openapi.yml" | "swagger.yaml" | "swagger.yml" => {
            let content = fs::read_to_string(path)
                .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
            read_regex_version_from_content(&content, r#"(?m)^\s{2}version:\s*([^\s]+)\s*$"#)
        }
        _ => read_version_from_path(path),
    }
}

fn write_metadata_version(path: &Path, version: &Version) -> Result<(), String> {
    let file_name = path
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or_default();
    match file_name {
        "openapi.yaml" | "openapi.yml" | "swagger.yaml" | "swagger.yml" => {
            let content = fs::read_to_string(path)
                .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
            let regex = regex::Regex::new(r#"(?m)^\s{2}version:\s*([^\s]+)\s*$"#)
                .map_err(|e| format!("Failed to build OpenAPI regex: {}", e))?;
            let updated = regex
                .replace(&content, format!("  version: {}", version))
                .to_string();
            fs::write(path, updated)
                .map_err(|e| format!("Failed to write {}: {}", path.display(), e))
        }
        _ => write_version_to_path(path, version).map(|_| ()),
    }
}

fn normalize_relative(repo_root: &Path, path: &Path) -> String {
    path.strip_prefix(repo_root)
        .unwrap_or(path)
        .to_string_lossy()
        .replace('\\', "/")
}

fn display_path(path: &Path) -> String {
    path.to_string_lossy().to_string()
}

fn same_path(left: &Path, right: &Path) -> bool {
    fs::canonicalize(left).unwrap_or_else(|_| left.to_path_buf())
        == fs::canonicalize(right).unwrap_or_else(|_| right.to_path_buf())
}

fn quote_argument(path: &Path) -> String {
    let value = path.to_string_lossy();
    if value.contains(' ') {
        format!("\"{}\"", value)
    } else {
        value.to_string()
    }
}

fn print_check_report(surface: &ReleaseSurface, report: &WorkspaceCheckReport) {
    println!("Workspace version check");
    println!("Repo: {}", surface.repo_root.display());
    println!("Expected version: {}", report.expected_version);
    if let Some(config_path) = &surface.config_path {
        println!(
            "Config: {}",
            normalize_relative(&surface.repo_root, config_path)
        );
    }
    println!(
        "Status: {}",
        if report.aligned {
            "aligned"
        } else {
            "drift detected"
        }
    );
    for entry in &report.drift {
        println!(
            "{} {} actual={} expected={}",
            entry.path,
            entry.field,
            entry.actual.as_deref().unwrap_or("<missing>"),
            entry.expected
        );
    }
}

fn print_sync_report(surface: &ReleaseSurface, report: &WorkspaceSyncReport) {
    println!(
        "Workspace version {}",
        if report.write { "sync" } else { "sync preview" }
    );
    println!("Repo: {}", surface.repo_root.display());
    println!("Expected version: {}", report.expected_version);
    if report.edits.is_empty() {
        println!("No changes needed.");
        return;
    }
    println!("Files: {}", report.files_changed.join(", "));
    for edit in &report.edits {
        println!(
            "{} {} {} -> {}",
            edit.path,
            edit.field,
            edit.before.as_deref().unwrap_or("<missing>"),
            edit.after
        );
    }
}

fn print_validation_report(surface: &ReleaseSurface, report: &WorkspaceValidateReport) {
    println!("Workspace validation");
    println!("Repo: {}", surface.repo_root.display());
    println!("Status: {}", if report.ok { "ok" } else { "failed" });
    for issue in &report.issues {
        println!(
            "{} {} actual={} expected={}",
            issue.path,
            issue.field,
            issue.actual.as_deref().unwrap_or("<missing>"),
            issue.expected
        );
    }
    for command in &report.commands {
        let status = if command.success {
            if command.warning.is_some() {
                "ok (with warning)"
            } else {
                "ok"
            }
        } else {
            "failed"
        };
        println!("{} [{}]", command.command, status);
        if let Some(warning) = command.warning.as_deref() {
            println!("warning: {}", warning);
        }
        if !command.stderr.is_empty() {
            println!("{}", command.stderr);
        }
    }
}

fn print_publish_plan_report(surface: &ReleaseSurface, report: &WorkspacePublishPlanReport) {
    println!("Workspace publish plan");
    println!("Repo: {}", surface.repo_root.display());
    if let Some(requested_package) = report.requested_package.as_deref() {
        println!("Requested package: {}", requested_package);
    }
    if !report.included_prereqs.is_empty() {
        println!(
            "Auto-included prerequisites: {}",
            report.included_prereqs.join(", ")
        );
    }
    if !report.required_closure.is_empty() {
        println!("Required closure: {}", report.required_closure.join(" -> "));
    }
    println!(
        "Publish order: {}",
        if report.publish_order.is_empty() {
            "<none>".to_string()
        } else {
            report.publish_order.join(", ")
        }
    );
    for item in &report.packages {
        println!(
            "{} {} visible={} needed={} reason={}",
            item.package,
            item.version,
            item.crates_io_visible
                .map(|value| value.to_string())
                .unwrap_or_else(|| "n/a".to_string()),
            item.publish_needed,
            item.reason
        );
        if !item.blocked_by.is_empty() {
            println!("  blocked by {}", item.blocked_by.join(", "));
        }
    }
    if !report.surface_issues.is_empty() {
        println!("Surface issues:");
        for issue in &report.surface_issues {
            println!(
                "  {} {} — {}{}",
                issue.package,
                format!("{:?}", issue.kind).to_ascii_lowercase(),
                issue.detail,
                if issue.auto_fixable {
                    " [auto-fixable]"
                } else {
                    ""
                }
            );
        }
        if report.surface_issues.iter().any(|issue| issue.auto_fixable) {
            if let Some(requested_package) = report.requested_package.as_deref() {
                println!(
                    "Heal with: xbp version workspace publish heal --repo {} --only {} --include-prereqs --write",
                    quote_argument(&surface.repo_root),
                    requested_package
                );
            } else {
                println!(
                    "Heal with: xbp version workspace publish heal --repo {} --write",
                    quote_argument(&surface.repo_root)
                );
            }
        }
    }
}

fn print_publish_heal_report(surface: &ReleaseSurface, report: &WorkspacePublishHealReport) {
    println!("Workspace publish heal");
    println!("Repo: {}", surface.repo_root.display());
    println!("Expected version: {}", report.expected_version);
    println!("Write: {}", report.write);
    if report.issues.is_empty() {
        println!("No publish-surface issues found.");
        return;
    }
    println!("Issues:");
    for issue in &report.issues {
        println!(
            "  {} — {}{}",
            issue.package,
            issue.detail,
            if issue.auto_fixable {
                " [auto-fixable]"
            } else {
                " [manual]"
            }
        );
    }
    if report.write {
        if report.files_changed.is_empty() {
            println!("No files changed.");
        } else {
            println!("Files changed: {}", report.files_changed.join(", "));
        }
    } else if report.issues.iter().any(|issue| issue.auto_fixable) {
        println!("Dry preview only. Re-run with --write to apply auto-fixes.");
    }
}

fn print_publish_run_report(surface: &ReleaseSurface, report: &WorkspacePublishRunReport) {
    println!("Workspace publish run");
    println!("Repo: {}", surface.repo_root.display());
    println!("Dry run: {}", report.dry_run);
    if let Some(requested_package) = report.requested_package.as_deref() {
        println!("Requested package: {}", requested_package);
    }
    if !report.included_prereqs.is_empty() {
        println!(
            "Auto-included prerequisites: {}",
            report.included_prereqs.join(", ")
        );
    }
    if !report.required_closure.is_empty() {
        println!("Required closure: {}", report.required_closure.join(" -> "));
    }
    if !report.published.is_empty() {
        println!("Published: {}", report.published.join(", "));
    }
    if !report.skipped.is_empty() {
        println!("Skipped: {}", report.skipped.join("; "));
    }
    if !report.failed.is_empty() {
        println!("Failed: {}", report.failed.join("; "));
    }
}

#[cfg(test)]
mod tests {
    use super::{
        apply_publish_surface_heals, apply_sync, build_publish_plan, collect_drift,
        collect_publish_blockers, collect_publish_surface_issues, discover_release_surface,
        inspect_workspace_version_drift, resolve_expected_version, PublishSelection,
        PublishSurfaceIssueKind,
    };
    use semver::Version;
    use std::collections::BTreeMap;
    use std::fs;
    use std::path::PathBuf;
    use std::time::{SystemTime, UNIX_EPOCH};

    fn temp_dir(name: &str) -> PathBuf {
        let nanos = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("time")
            .as_nanos();
        let dir = std::env::temp_dir().join(format!("xbp-workspace-release-{}-{}", name, nanos));
        fs::create_dir_all(&dir).expect("create temp dir");
        dir
    }

    fn write_file(path: &PathBuf, content: &str) {
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent).expect("create parent");
        }
        fs::write(path, content).expect("write file");
    }

    fn create_demo_workspace() -> PathBuf {
        let root = temp_dir("demo");
        write_file(
            &root.join("Cargo.toml"),
            r#"[package]
name = "athena_rs"
version = "3.16.4"

[dependencies.alpha]
path = "crates/alpha"
version = "3.16.4"

[dependencies.beta]
path = "crates/beta"
version = "3.16.4"

[dependencies.athena-s3]
path = "crates/athena-s3"
version = "3.16.4"

[workspace]
members = ["crates/alpha", "crates/beta", "crates/athena-s3"]
resolver = "2"
"#,
        );
        write_file(&root.join("src/lib.rs"), "pub fn root() {}\n");
        write_file(
            &root.join("README.md"),
            "# Athena\n\ncurrent version: `3.16.4`\n",
        );
        write_file(
            &root.join("openapi.yaml"),
            "openapi: 3.1.0\ninfo:\n  title: Athena\n  version: 3.16.4\n",
        );
        write_file(
            &root.join("Cargo.lock"),
            r#"version = 4

[[package]]
name = "athena_rs"
version = "3.16.4"

[[package]]
name = "alpha"
version = "3.16.4"

[[package]]
name = "beta"
version = "3.16.4"

[[package]]
name = "athena-s3"
version = "3.16.4"
"#,
        );
        write_file(
            &root.join("crates/alpha/Cargo.toml"),
            r#"[package]
name = "alpha"
version = "3.16.4"

[dependencies]
beta = { path = "../beta", version = "3.16.4" }
athena-s3 = { path = "../athena-s3", version = "3.16.4" }
"#,
        );
        write_file(&root.join("crates/alpha/src/lib.rs"), "pub fn alpha() {}\n");
        write_file(
            &root.join("crates/beta/Cargo.toml"),
            r#"[package]
name = "beta"
version = "3.16.4"
"#,
        );
        write_file(&root.join("crates/beta/src/lib.rs"), "pub fn beta() {}\n");
        write_file(
            &root.join("crates/athena-s3/Cargo.toml"),
            r#"[package]
name = "athena-s3"
version = "3.16.4"
"#,
        );
        write_file(
            &root.join("crates/athena-s3/src/lib.rs"),
            "pub fn athena_s3() {}\n",
        );
        write_file(
            &root.join("crates/athena-backups/Cargo.toml"),
            r#"[package]
name = "athena-backups"
version = "3.16.0"

[dependencies]
beta = { path = "../beta", version = "3.16.0" }
"#,
        );
        write_file(
            &root.join("crates/athena-backups/src/lib.rs"),
            "pub fn athena_backups() {}\n",
        );
        root
    }

    #[test]
    fn inspect_workspace_version_drift_ignores_parent_workspace_for_nested_project_root() {
        let root = create_demo_workspace();
        let nested_project_root = root.join("packages").join("athena-js");
        fs::create_dir_all(&nested_project_root).expect("create nested project root");

        let drift = inspect_workspace_version_drift(&nested_project_root, &Version::new(2, 13, 0))
            .expect("inspect drift");

        assert!(drift.is_none());
    }

    fn create_workspace_dependency_demo_workspace() -> PathBuf {
        let root = temp_dir("workspace-deps");
        write_file(
            &root.join("Cargo.toml"),
            r#"[package]
name = "xbp"
version = "10.27.0"

[dependencies]
xbp-providers.workspace = true

[workspace]
members = ["crates/http", "crates/providers"]
resolver = "2"

[workspace.dependencies]
xbp-http = { path = "crates/http", version = "0.1.0" }
xbp-providers = { path = "crates/providers", version = "0.1.0" }
"#,
        );
        write_file(&root.join("src/lib.rs"), "pub fn root() {}\n");
        write_file(
            &root.join("crates/http/Cargo.toml"),
            r#"[package]
name = "xbp-http"
version = "0.1.0"
"#,
        );
        write_file(&root.join("crates/http/src/lib.rs"), "pub fn http() {}\n");
        write_file(
            &root.join("crates/providers/Cargo.toml"),
            r#"[package]
name = "xbp-providers"
version = "0.1.0"

[dependencies]
xbp-http.workspace = true
"#,
        );
        write_file(
            &root.join("crates/providers/src/lib.rs"),
            "pub fn providers() {}\n",
        );
        root
    }

    fn create_alias_dependency_demo_workspace() -> PathBuf {
        let root = temp_dir("workspace-alias-deps");
        write_file(
            &root.join("Cargo.toml"),
            r#"[package]
name = "xbp"
version = "10.27.0"

[dependencies.xbp_monitor]
package = "xbp-monitoring"
path = "crates/monitor"
version = "10.27.0"

[workspace]
members = ["crates/monitor"]
resolver = "2"
"#,
        );
        write_file(&root.join("src/lib.rs"), "pub fn root() {}\n");
        write_file(
            &root.join("crates/monitor/Cargo.toml"),
            r#"[package]
name = "xbp-monitoring"
version = "10.27.0"
"#,
        );
        write_file(
            &root.join("crates/monitor/src/lib.rs"),
            "pub fn monitor() {}\n",
        );
        root
    }

    fn create_virtual_workspace_package_demo_workspace() -> PathBuf {
        let root = temp_dir("virtual-workspace-package");
        write_file(
            &root.join("Cargo.toml"),
            r#"[workspace]
members = ["crates/cli"]
resolver = "2"

[workspace.package]
version = "10.35.0"
"#,
        );
        write_file(
            &root.join("crates/cli/Cargo.toml"),
            r#"[package]
name = "xbp"
version.workspace = true
"#,
        );
        write_file(&root.join("crates/cli/src/lib.rs"), "pub fn cli() {}\n");
        root
    }

    #[test]
    fn discovery_uses_workspace_members_and_excludes_non_member_crates() {
        let root = create_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let names = surface
            .packages
            .iter()
            .map(|package| package.name.clone())
            .collect::<Vec<_>>();
        assert!(names.contains(&"athena-s3".to_string()));
        assert!(!names.contains(&"athena-backups".to_string()));
    }

    #[test]
    fn expected_version_reads_virtual_workspace_package_version() {
        let root = create_virtual_workspace_package_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");

        assert_eq!(
            resolve_expected_version(&surface, None).expect("expected version"),
            Version::new(10, 35, 0)
        );

        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn drift_reports_package_dependency_metadata_and_lock_mismatches() {
        let root = create_demo_workspace();
        write_file(
            &root.join("crates/alpha/Cargo.toml"),
            r#"[package]
name = "alpha"
version = "3.16.5"

[dependencies]
beta = { path = "../beta", version = "3.16.4" }
athena-s3 = { path = "../athena-s3" }
"#,
        );
        let surface = discover_release_surface(&root).expect("discover");
        let expected = Version::new(3, 16, 4);
        let drift = collect_drift(&surface, &expected).expect("drift");
        assert!(drift.iter().any(
            |entry| entry.path == "crates/alpha/Cargo.toml" && entry.field == "package.version"
        ));
        assert!(
            drift
                .iter()
                .any(|entry| entry.field == "dependencies.athena-s3.version"
                    && entry.actual.is_none())
        );
    }

    #[test]
    fn sync_preview_and_write_updates_workspace_surface() {
        let root = create_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let expected = Version::new(3, 16, 5);
        let (preview, _) = apply_sync(&surface, &expected, false).expect("preview");
        assert!(!preview.is_empty());

        let (written, files) = apply_sync(&surface, &expected, true).expect("write");
        assert!(!written.is_empty());
        assert!(files.contains(&"Cargo.toml".to_string()));
        let updated = fs::read_to_string(root.join("crates/alpha/Cargo.toml")).expect("read");
        assert!(updated.contains("version = \"3.16.5\""));
        assert!(updated.contains("athena-s3 = { path = \"../athena-s3\", version = \"3.16.5\" }"));
    }

    #[test]
    fn drift_and_sync_follow_aliased_workspace_dependencies() {
        let root = create_alias_dependency_demo_workspace();
        write_file(
            &root.join("Cargo.toml"),
            r#"[package]
name = "xbp"
version = "10.27.1"

[dependencies.xbp_monitor]
package = "xbp-monitoring"
path = "crates/monitor"
version = "10.27.0"

[workspace]
members = ["crates/monitor"]
resolver = "2"
"#,
        );

        let surface = discover_release_surface(&root).expect("discover");
        let expected = Version::new(10, 27, 1);
        let drift = collect_drift(&surface, &expected).expect("drift");
        assert!(drift
            .iter()
            .any(|entry| entry.path == "Cargo.toml"
                && entry.field == "dependencies.xbp_monitor.version"));

        let (written, files) = apply_sync(&surface, &expected, true).expect("write");
        assert!(!written.is_empty());
        assert!(files.contains(&"Cargo.toml".to_string()));
        let updated = fs::read_to_string(root.join("Cargo.toml")).expect("read root manifest");
        assert!(updated.contains("version = \"10.27.1\""));
        assert!(updated.contains("package = \"xbp-monitoring\""));
        assert!(updated.contains("version = \"10.27.1\""));
    }

    #[test]
    fn publish_plan_orders_dependencies_before_dependents() {
        let root = create_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("athena_rs".to_string(), false);
        visibility.insert("alpha".to_string(), false);
        visibility.insert("beta".to_string(), true);
        visibility.insert("athena-s3".to_string(), false);
        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: None,
                include_prereqs: false,
            }),
        )
        .expect("plan");
        let alpha_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "alpha")
            .expect("alpha");
        let s3_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "athena-s3")
            .expect("s3");
        assert!(s3_pos < alpha_pos);
        assert!(plan
            .items
            .iter()
            .any(|item| item.package == "athena_rs" && item.publish_needed));
    }

    #[test]
    fn publish_plan_orders_workspace_dependencies_before_dependents() {
        let root = create_workspace_dependency_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("xbp".to_string(), false);
        visibility.insert("xbp-http".to_string(), false);
        visibility.insert("xbp-providers".to_string(), false);

        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: None,
                include_prereqs: false,
            }),
        )
        .expect("plan");

        let xbp_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "xbp")
            .expect("xbp");
        let providers_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "xbp-providers")
            .expect("providers");
        let http_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "xbp-http")
            .expect("http");

        assert!(http_pos < providers_pos);
        assert!(providers_pos < xbp_pos);
    }

    #[test]
    fn publish_plan_orders_aliased_workspace_dependencies_before_dependents() {
        let root = create_alias_dependency_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("xbp".to_string(), false);
        visibility.insert("xbp-monitoring".to_string(), false);

        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: None,
                include_prereqs: false,
            }),
        )
        .expect("plan");

        let xbp_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "xbp")
            .expect("xbp");
        let monitor_pos = plan
            .publish_order
            .iter()
            .position(|name| name == "xbp-monitoring")
            .expect("xbp-monitoring");

        assert!(monitor_pos < xbp_pos);
    }

    #[test]
    fn publish_plan_only_with_prereqs_limits_to_minimal_closure() {
        let root = create_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("athena_rs".to_string(), false);
        visibility.insert("alpha".to_string(), false);
        visibility.insert("beta".to_string(), false);
        visibility.insert("athena-s3".to_string(), false);

        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: Some("alpha".to_string()),
                include_prereqs: true,
            }),
        )
        .expect("plan");

        let package_names = plan
            .items
            .iter()
            .map(|item| item.package.as_str())
            .collect::<Vec<_>>();
        assert_eq!(package_names.len(), 3);
        assert!(!package_names.contains(&"athena_rs"));
        assert_eq!(plan.required_closure.len(), 3);
        assert!(plan.required_closure.contains(&"alpha".to_string()));
        assert!(plan.required_closure.contains(&"beta".to_string()));
        assert!(plan.required_closure.contains(&"athena-s3".to_string()));
        assert_eq!(plan.included_prereqs.len(), 2);
        assert!(plan.included_prereqs.contains(&"beta".to_string()));
        assert!(plan.included_prereqs.contains(&"athena-s3".to_string()));
        assert_eq!(plan.publish_order.len(), 3);

        let alpha_pos = plan
            .publish_order
            .iter()
            .position(|package| package == "alpha")
            .expect("alpha in publish order");
        let beta_pos = plan
            .publish_order
            .iter()
            .position(|package| package == "beta")
            .expect("beta in publish order");
        let s3_pos = plan
            .publish_order
            .iter()
            .position(|package| package == "athena-s3")
            .expect("athena-s3 in publish order");
        assert!(beta_pos < alpha_pos);
        assert!(s3_pos < alpha_pos);
    }

    #[test]
    fn publish_plan_only_without_prereqs_reports_blocked_package() {
        let root = create_demo_workspace();
        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("athena_rs".to_string(), false);
        visibility.insert("alpha".to_string(), false);
        visibility.insert("beta".to_string(), false);
        visibility.insert("athena-s3".to_string(), false);

        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: Some("alpha".to_string()),
                include_prereqs: false,
            }),
        )
        .expect("plan");

        assert_eq!(plan.required_closure.len(), 3);
        assert!(plan.required_closure.contains(&"alpha".to_string()));
        assert!(plan.required_closure.contains(&"beta".to_string()));
        assert!(plan.required_closure.contains(&"athena-s3".to_string()));
        assert!(plan.included_prereqs.is_empty());
        assert!(plan.publish_order.is_empty());
        assert_eq!(plan.items.len(), 1);
        assert_eq!(plan.items[0].package, "alpha");
        assert_eq!(plan.items[0].blocked_by.len(), 2);
        assert!(plan.items[0].blocked_by.contains(&"beta".to_string()));
        assert!(plan.items[0].blocked_by.contains(&"athena-s3".to_string()));
    }

    #[test]
    fn publish_plan_ignores_dev_dependencies_for_publish_blockers() {
        let root = temp_dir("publish-dev-deps");
        write_file(
            &root.join("Cargo.toml"),
            r#"[package]
name = "demo-root"
version = "1.0.0"

[workspace]
members = ["crates/app", "crates/dev-helper"]
resolver = "2"
"#,
        );
        write_file(&root.join("src/lib.rs"), "pub fn root() {}\n");
        write_file(
            &root.join("crates/app/Cargo.toml"),
            r#"[package]
name = "demo-app"
version = "1.0.0"

[dev-dependencies]
dev-helper = { path = "../dev-helper", version = "1.0.0" }
"#,
        );
        write_file(&root.join("crates/app/src/lib.rs"), "pub fn app() {}\n");
        write_file(
            &root.join("crates/dev-helper/Cargo.toml"),
            r#"[package]
name = "dev-helper"
version = "1.0.0"
"#,
        );
        write_file(
            &root.join("crates/dev-helper/src/lib.rs"),
            "pub fn helper() {}\n",
        );

        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("demo-root".to_string(), false);
        visibility.insert("demo-app".to_string(), false);
        visibility.insert("dev-helper".to_string(), false);

        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: Some("demo-app".to_string()),
                include_prereqs: false,
            }),
        )
        .expect("plan");

        assert_eq!(plan.required_closure, vec!["demo-app"]);
        assert_eq!(plan.publish_order, vec!["demo-app"]);
        assert!(plan.items[0].blocked_by.is_empty());
    }

    #[test]
    fn publish_plan_orphan_publish_false_is_not_a_blocker() {
        let root = temp_dir("publish-orphan-private");
        write_file(
            &root.join("Cargo.toml"),
            r#"[workspace]
members = ["crates/app", "crates/private-tool"]
resolver = "2"
"#,
        );
        write_file(
            &root.join("crates/app/Cargo.toml"),
            r#"[package]
name = "demo-app"
version = "1.0.0"
"#,
        );
        write_file(&root.join("crates/app/src/lib.rs"), "pub fn app() {}\n");
        write_file(
            &root.join("crates/private-tool/Cargo.toml"),
            r#"[package]
name = "private-tool"
version = "1.0.0"
publish = false
"#,
        );
        write_file(
            &root.join("crates/private-tool/src/lib.rs"),
            "pub fn tool() {}\n",
        );

        let surface = discover_release_surface(&root).expect("discover");
        let mut visibility = BTreeMap::new();
        visibility.insert("demo-app".to_string(), false);
        visibility.insert("private-tool".to_string(), false);

        let plan = build_publish_plan(
            &surface,
            &visibility,
            Some(&PublishSelection {
                from: None,
                only: None,
                include_prereqs: false,
            }),
        )
        .expect("plan");

        let blockers = collect_publish_blockers(&plan.items);
        assert!(
            blockers.is_empty(),
            "orphan private packages must not block: {blockers:?}"
        );
        assert!(plan.publish_order.contains(&"demo-app".to_string()));
        assert!(!plan.publish_order.contains(&"private-tool".to_string()));
    }

    #[test]
    fn publish_surface_heal_enables_private_path_prereq() {
        let root = temp_dir("publish-heal-private-prereq");
        write_file(
            &root.join("Cargo.toml"),
            r#"[workspace]
members = ["crates/app", "crates/internal"]
resolver = "2"

[workspace.package]
homepage = "https://example.com"
repository = "https://github.com/example/xbp"
license = "MIT"
"#,
        );
        write_file(
            &root.join("crates/app/Cargo.toml"),
            r#"[package]
name = "demo-app"
version = "1.2.0"

[dependencies]
internal = { path = "../internal", version = "1.2.0" }
"#,
        );
        write_file(&root.join("crates/app/src/lib.rs"), "pub fn app() {}\n");
        write_file(
            &root.join("crates/internal/Cargo.toml"),
            r#"[package]
name = "internal"
version = "1.2.0"
publish = false
"#,
        );
        write_file(
            &root.join("crates/internal/src/lib.rs"),
            "pub fn internal() {}\n",
        );

        let surface = discover_release_surface(&root).expect("discover");
        let selection = PublishSelection {
            from: None,
            only: Some("demo-app".to_string()),
            include_prereqs: true,
        };
        let expected = Version::new(1, 2, 0);
        let issues =
            collect_publish_surface_issues(&surface, Some(&selection), &expected).expect("issues");
        assert!(issues.iter().any(|issue| {
            issue.package == "internal"
                && issue.kind == PublishSurfaceIssueKind::PublishDisabled
                && issue.auto_fixable
        }));

        let mut visibility = BTreeMap::new();
        visibility.insert("demo-app".to_string(), false);
        visibility.insert("internal".to_string(), false);
        let blocked_plan =
            build_publish_plan(&surface, &visibility, Some(&selection)).expect("blocked plan");
        assert!(!collect_publish_blockers(&blocked_plan.items).is_empty());

        let (_edits, files) =
            apply_publish_surface_heals(&surface, Some(&selection), &expected, true)
                .expect("heal");
        assert!(
            files.iter().any(|path| path.contains("internal")),
            "expected internal Cargo.toml in {files:?}"
        );

        let healed = fs::read_to_string(root.join("crates/internal/Cargo.toml")).expect("read");
        assert!(
            !healed.contains("publish = false"),
            "publish=false should be removed: {healed}"
        );
        assert!(healed.contains("homepage"));
        assert!(healed.contains("repository"));

        let surface = discover_release_surface(&root).expect("rediscover");
        let plan = build_publish_plan(&surface, &visibility, Some(&selection)).expect("plan");
        assert!(
            collect_publish_blockers(&plan.items).is_empty(),
            "healed surface should be unblocked: {:?}",
            collect_publish_blockers(&plan.items)
        );
        assert!(plan.publish_order.contains(&"internal".to_string()));
        assert!(plan.publish_order.contains(&"demo-app".to_string()));
    }

    #[test]
    fn publish_surface_exclude_is_not_auto_fixable() {
        let root = temp_dir("publish-exclude-manual");
        write_file(
            &root.join("Cargo.toml"),
            r#"[workspace]
members = ["crates/app", "crates/secret"]
resolver = "2"
"#,
        );
        write_file(
            &root.join(".xbp/workspace-release.yaml"),
            "publish:\n  exclude:\n    - secret\n",
        );
        write_file(
            &root.join("crates/app/Cargo.toml"),
            r#"[package]
name = "demo-app"
version = "1.0.0"

[dependencies]
secret = { path = "../secret", version = "1.0.0" }
"#,
        );
        write_file(&root.join("crates/app/src/lib.rs"), "pub fn app() {}\n");
        write_file(
            &root.join("crates/secret/Cargo.toml"),
            r#"[package]
name = "secret"
version = "1.0.0"
"#,
        );
        write_file(&root.join("crates/secret/src/lib.rs"), "pub fn secret() {}\n");

        let surface = discover_release_surface(&root).expect("discover");
        let selection = PublishSelection {
            from: None,
            only: Some("demo-app".to_string()),
            include_prereqs: true,
        };
        let issues = collect_publish_surface_issues(
            &surface,
            Some(&selection),
            &Version::new(1, 0, 0),
        )
        .expect("issues");
        assert!(issues.iter().any(|issue| {
            issue.package == "secret"
                && issue.kind == PublishSurfaceIssueKind::PublishExcluded
                && !issue.auto_fixable
        }));
    }
}