tuffcli 0.6.0

use std::path::Path;

use semver::Version;
use serde::Serialize;

use crate::error::Result;
use crate::git;
use crate::lockfile;
use crate::manifest::CapabilityType;
use crate::oci::{self, OciTransferOptions};
use crate::release;

use super::{home_dir_opt, render_table, short_sha, style_outdated_status};

struct OutdatedRow {
    id: String,
    capability_type: CapabilityType,
    target: String,
    /// Shown beside CURRENT for a git install whose version is only what
    /// the source declared, and carried in the JSON for every row.
    version_scheme: lockfile::VersionScheme,
    /// Whether the entry came from git, where a declared version is weaker
    /// than a release and the table says so.
    from_git: bool,
    current: String,
    latest: String,
    status: String,
    /// `major`, `minor`, or `patch` when both sides are releases: the size
    /// of the change the author claimed, shown beside `outdated`.
    change: Option<String>,
}

/// The `--json` shape of an [`OutdatedRow`], with the same `type`/`target`
/// keys as `tuff check --json`. The table prints `—` where nothing could be
/// resolved; a script should not have to compare against a dash, so that
/// becomes `null`.
#[derive(Serialize)]
struct JsonOutdatedRow<'a> {
    id: &'a str,
    #[serde(rename = "type")]
    capability_type: CapabilityType,
    target: &'a str,
    version_scheme: lockfile::VersionScheme,
    current: &'a str,
    latest: Option<&'a str>,
    status: &'a str,
    #[serde(skip_serializing_if = "Option::is_none")]
    change: Option<&'a str>,
}

impl OutdatedRow {
    fn as_json(&self) -> JsonOutdatedRow<'_> {
        JsonOutdatedRow {
            id: &self.id,
            capability_type: self.capability_type,
            target: &self.target,
            version_scheme: self.version_scheme,
            current: &self.current,
            latest: (self.latest != UNRESOLVED).then_some(self.latest.as_str()),
            status: &self.status,
            change: self.change.as_deref(),
        }
    }
}

/// What the LATEST column shows when there is nothing to compare against.
const UNRESOLVED: &str = "—";

/// What the registry's tags say about an installed pack version.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum PackVersionStatus {
    /// A newer semver tag is published.
    Newer(String),
    /// The installed version is the newest semver tag.
    Current,
    /// Nothing conclusive: the installed version or every tag is unparsable.
    Unknown,
}

/// Compare an installed pack version against the tags published for it.
///
/// Tags are not compared as strings: `"1.9.0" > "1.10.0"` under plain
/// lexicographic ordering, which is the wrong answer and exactly the kind of
/// confidently-wrong result `tuff outdated` should not produce. Only tags
/// that parse as semver are compared, using real version ordering; anything
/// else is excluded rather than guessed at. `tuff pack build --version` does
/// not enforce a version scheme, so an unparsable installed version is a
/// real case, not a hypothetical one.
pub(crate) fn compare_pack_versions(installed: &str, tags: &[String]) -> PackVersionStatus {
    let Ok(installed_version) = Version::parse(installed) else {
        return PackVersionStatus::Unknown;
    };
    match tags.iter().filter_map(|tag| Version::parse(tag).ok()).max() {
        None => PackVersionStatus::Unknown,
        Some(latest) if latest > installed_version => PackVersionStatus::Newer(latest.to_string()),
        Some(_) => PackVersionStatus::Current,
    }
}

/// Whether the installed pack tag still names the bytes that were installed.
///
/// A tag is mutable by design. `PackProvenance.digest` records the artifact
/// that was actually installed, and the tag's manifest names the artifact it
/// points at now; when they differ, someone published different bytes under
/// the same version. That is a different finding from "a newer version
/// exists": it means the version you have may not be what you think it is.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum PackTagIntegrity {
    /// The tag still points at the installed artifact.
    Matches,
    /// The tag now points at a different artifact.
    Repointed { live_digest: String },
    /// The registry no longer has the tag at all.
    Missing,
    /// The tag could not be resolved (network, auth, or protocol failure).
    Unavailable(String),
}

/// Resolve the installed tag and compare it against the recorded digest.
pub(crate) fn verify_pack_tag(
    pack: &lockfile::PackProvenance,
    registry: &str,
    options: &OciTransferOptions,
) -> PackTagIntegrity {
    let reference = format!("{registry}:{}", pack.version);
    match super::block_on_oci(oci::resolve_pack_tag(&reference, options)) {
        Err(error) => PackTagIntegrity::Unavailable(error.to_string()),
        Ok(None) => PackTagIntegrity::Missing,
        Ok(Some(resolved)) => {
            if resolved.artifact_digest == format!("sha256:{}", pack.digest) {
                PackTagIntegrity::Matches
            } else {
                PackTagIntegrity::Repointed {
                    live_digest: resolved.artifact_digest,
                }
            }
        }
    }
}

/// Render [`compare_pack_versions`] as an `outdated` table row.
fn pick_latest_pack_version(installed: &str, tags: &[String]) -> (String, String, String) {
    let current = installed.to_string();
    match compare_pack_versions(installed, tags) {
        PackVersionStatus::Unknown => (current, UNRESOLVED.to_string(), "not checked".to_string()),
        PackVersionStatus::Newer(latest) => (current, latest, "outdated".to_string()),
        PackVersionStatus::Current => (current.clone(), current, "up to date".to_string()),
    }
}

/// Fold the tag integrity into a version row. Integrity findings win: a
/// repointed or deleted tag is reported even when a newer version exists,
/// because "what you have is not what you installed" changes what the
/// LATEST column means. LATEST is still shown, so the way forward is visible.
fn pack_row(
    installed: &str,
    tags: &[String],
    integrity: &PackTagIntegrity,
) -> (String, String, String) {
    let (current, latest, status) = pick_latest_pack_version(installed, tags);
    let status = match integrity {
        PackTagIntegrity::Matches => status,
        PackTagIntegrity::Repointed { .. } => "repointed".to_string(),
        PackTagIntegrity::Missing => "tag missing".to_string(),
        PackTagIntegrity::Unavailable(_) => "error".to_string(),
    };
    (current, latest, status)
}

/// One registry round trip per pack per run, not per member per harness.
///
/// Every member of a pack shares the same provenance, and `outdated` emits a
/// row per member per target, so without this a four-member pack installed
/// for two harnesses would list the registry's tags eight times.
#[derive(Default)]
pub(crate) struct PackCheckCache {
    rows: std::collections::BTreeMap<String, (String, String, String)>,
}

/// Check a pack-sourced capability against its registry.
///
/// `pack.registry` is only present when the pack was installed with
/// `tuff add pack --reference`; the caller already confirmed that before
/// reaching here.
fn classify_pack(
    pack: &lockfile::PackProvenance,
    registry: &str,
    options: &OciTransferOptions,
    cache: &mut PackCheckCache,
) -> (String, String, String) {
    let key = format!("{registry}:{}@{}", pack.version, pack.digest);
    if let Some(row) = cache.rows.get(&key) {
        return row.clone();
    }
    let row = match super::block_on_oci(oci::list_pack_versions(registry, options)) {
        Err(_) => (
            pack.version.clone(),
            "unavailable".to_string(),
            "error".to_string(),
        ),
        Ok(tags) => {
            let integrity = verify_pack_tag(pack, registry, options);
            pack_row(&pack.version, &tags, &integrity)
        }
    };
    cache.rows.insert(key, row.clone());
    row
}

/// Classify one capability against its upstream.
///
/// A capability with no recorded source and no registry-aware pack — anything
/// installed from a pack without `--reference`, or from a local path —
/// cannot be checked at all. That is reported as `not checked` rather than
/// folded into `up to date`: an honest unknown sends someone to look, a
/// confident "up to date" does not.
fn classify(
    id: &str,
    entry: &lockfile::CapabilityLockEntry,
    oci_options: &OciTransferOptions,
    cache: &mut PackCheckCache,
) -> (String, String, String) {
    let git = match &entry.source {
        lockfile::CapabilitySource::Pack(pack) => {
            return match &pack.registry {
                Some(registry) => classify_pack(pack, registry, oci_options, cache),
                None => (
                    entry.version.clone(),
                    UNRESOLVED.to_string(),
                    "not checked".to_string(),
                ),
            };
        }
        lockfile::CapabilitySource::Local(_) => {
            return (
                entry.version.clone(),
                UNRESOLVED.to_string(),
                "not checked".to_string(),
            );
        }
        lockfile::CapabilitySource::Catalog(catalog) if catalog.registry.is_some() => {
            let registry = catalog.registry.as_deref().expect("registry checked above");
            let (latest, status) =
                match super::block_on_oci(crate::registry::fetch(registry, &catalog.id)) {
                    Ok(Some(server)) if server.version == entry.version => {
                        (server.version, "up to date")
                    }
                    Ok(Some(server)) => (server.version, "outdated"),
                    // Unpublished, or the registry is unreachable: either way
                    // there is nothing current to compare against, and saying
                    // "up to date" would be a conclusion never reached.
                    Ok(None) => ("unpublished".to_string(), "error"),
                    Err(_) => ("unavailable".to_string(), "error"),
                };
            return (entry.version.clone(), latest, status.to_string());
        }
        lockfile::CapabilitySource::Catalog(catalog) => {
            let (latest, status) = match crate::catalog::lookup(&catalog.id) {
                Ok(Some(manifest)) if manifest.version == entry.version => {
                    (manifest.version, "up to date")
                }
                Ok(Some(manifest)) => (manifest.version, "outdated"),
                // Removed from the catalog, or the catalog itself is broken:
                // either way there is nothing current to compare against.
                _ => ("unavailable".to_string(), "error"),
            };
            return (entry.version.clone(), latest, status.to_string());
        }
        lockfile::CapabilitySource::Git(git) if git.tag.is_some() => {
            return classify_release(id, entry, git);
        }
        lockfile::CapabilitySource::Git(git) => git,
    };
    classify_commit(entry, git)
}

/// A git install with no release pin is compared commit to commit: HEAD
/// moved or it did not. What the columns show depends on what the version
/// is. A `sha` entry shows short commits. A `declared` entry shows the
/// version the source declared then and declares now, with the claimed
/// size of the change when both parse; when HEAD moved but the declared
/// version did not, the row still reads `outdated`, which is exactly why a
/// declared version is weaker than a release.
fn classify_commit(
    entry: &lockfile::CapabilityLockEntry,
    git: &lockfile::GitSource,
) -> (String, String, String) {
    let declared = entry.version_scheme == lockfile::VersionScheme::Declared;
    let current = if declared {
        entry.version.clone()
    } else {
        short_sha(&entry.version).to_string()
    };
    let (_guard, checkout, _) = match git::clone_to_temp(&git.url, None) {
        Ok(clone) => clone,
        Err(_) => return (current, "unavailable".to_string(), "error".to_string()),
    };
    let Ok(latest_sha) = git::resolve_ref(&checkout) else {
        return (current, "unavailable".to_string(), "error".to_string());
    };
    if latest_sha == git.git_ref {
        return (current.clone(), current, "up to date".to_string());
    }
    if !declared {
        return (
            current,
            short_sha(&latest_sha).to_string(),
            "outdated".to_string(),
        );
    }
    let latest_declared = git::discover_capability(&checkout, &git.path, entry.capability_type)
        .ok()
        .and_then(|dir| crate::manifest::declared_version(&dir));
    let latest = latest_declared.unwrap_or_else(|| short_sha(&latest_sha).to_string());
    let status = match (Version::parse(&entry.version), Version::parse(&latest)) {
        (Ok(from), Ok(to)) if to != from => {
            format!("outdated ({})", release::change_kind(&from, &to))
        }
        _ => "outdated".to_string(),
    };
    (current, latest, status)
}

/// A tag-pinned install (RFC-101) is compared against the newest release
/// tag, whatever the recorded requirement allows: `outdated` answers "is
/// there something newer", and `update` decides whether the requirement
/// lets you have it. One `ls-remote` per row, no clone.
fn classify_release(
    id: &str,
    entry: &lockfile::CapabilityLockEntry,
    git: &lockfile::GitSource,
) -> (String, String, String) {
    let current = entry.version.clone();
    let tags = match git::list_remote_tags(&git.url) {
        Ok(tags) => tags,
        Err(_) => return (current, "unavailable".to_string(), "error".to_string()),
    };
    let releases = release::release_tags(tags.iter().map(|tag| tag.name.as_str()), id);
    let latest = release::latest_release(&releases).map(|latest| latest.version.to_string());
    // The tag is mutable; the commit is what was installed. A tag that
    // moved, or is gone, changes what LATEST means and wins over the
    // version verdict, while LATEST still shows the way forward.
    let integrity = git
        .tag
        .as_deref()
        .map(|tag| release::tag_integrity(tag, &git.git_ref, &tags));
    match integrity {
        Some(release::TagIntegrity::Repointed { .. }) => {
            return (
                current,
                latest.unwrap_or_else(|| UNRESOLVED.to_string()),
                "repointed".to_string(),
            );
        }
        Some(release::TagIntegrity::Missing) => {
            return (
                current,
                latest.unwrap_or_else(|| UNRESOLVED.to_string()),
                "tag missing".to_string(),
            );
        }
        Some(release::TagIntegrity::Matches) | None => {}
    }
    let Some(latest) = release::latest_release(&releases) else {
        return (current, UNRESOLVED.to_string(), "tag missing".to_string());
    };
    match Version::parse(&entry.version) {
        Ok(installed) if latest.version > installed => (
            current,
            latest.version.to_string(),
            format!(
                "outdated ({})",
                release::change_kind(&installed, &latest.version)
            ),
        ),
        Ok(_) => (
            current,
            latest.version.to_string(),
            "up to date".to_string(),
        ),
        Err(_) => (
            current,
            latest.version.to_string(),
            "not checked".to_string(),
        ),
    }
}

/// Take the change kind out of an `outdated (minor)` status so the status
/// column and the JSON `status` stay one of the documented words.
fn split_change(status: String) -> (String, Option<String>) {
    match status
        .strip_prefix("outdated (")
        .and_then(|rest| rest.strip_suffix(')'))
    {
        Some(kind) => ("outdated".to_string(), Some(kind.to_string())),
        None => (status, None),
    }
}

fn collect_rows(
    lf: &lockfile::Lockfile,
    oci_options: &OciTransferOptions,
    cache: &mut PackCheckCache,
    rows: &mut Vec<OutdatedRow>,
) {
    for (id, entry) in &lf.capabilities {
        for target_id in entry.targets.keys() {
            let (current, latest, status) = classify(id, entry, oci_options, cache);
            let (status, change) = split_change(status);
            rows.push(OutdatedRow {
                id: id.clone(),
                capability_type: entry.capability_type,
                target: target_id.clone(),
                version_scheme: entry.version_scheme,
                from_git: matches!(entry.source, lockfile::CapabilitySource::Git(_)),
                current,
                latest,
                status,
                change,
            });
        }
    }
}

pub fn cmd_outdated(
    repo_root: &Path,
    plain_http: bool,
    ca_files: &[std::path::PathBuf],
    json: bool,
) -> Result<()> {
    let oci_options = OciTransferOptions {
        plain_http,
        ca_files: ca_files.to_vec(),
    };
    let mut rows: Vec<OutdatedRow> = Vec::new();
    let mut cache = PackCheckCache::default();

    if let Some(lf) = lockfile::read_optional_lockfile(&lockfile::project_lockfile(repo_root))? {
        collect_rows(&lf, &oci_options, &mut cache, &mut rows);
    }

    if let Some(home) = home_dir_opt() {
        let lock_path = crate::paths::global_lockfile(&home);
        if let Some(lf) = lockfile::read_optional_lockfile(&lock_path)? {
            collect_rows(&lf, &oci_options, &mut cache, &mut rows);
        }
    }

    if rows.is_empty() {
        if json {
            println!("[]");
        } else {
            println!("no capabilities installed");
        }
        return Ok(());
    }

    rows.sort_by(|a, b| a.id.cmp(&b.id));

    if json {
        let rows: Vec<JsonOutdatedRow<'_>> = rows.iter().map(OutdatedRow::as_json).collect();
        println!("{}", serde_json::to_string_pretty(&rows)?);
        return Ok(());
    }

    let table_rows: Vec<Vec<String>> = rows
        .into_iter()
        .map(|r| {
            let status = match &r.change {
                Some(change) => format!("{} ({change})", style_outdated_status(&r.status)),
                None => style_outdated_status(&r.status),
            };
            let current = if r.from_git && r.version_scheme == lockfile::VersionScheme::Declared {
                format!("{} (declared)", r.current)
            } else {
                r.current.clone()
            };
            let row = OutdatedRow {
                status,
                current,
                ..r
            };
            vec![
                row.id,
                row.capability_type.to_string(),
                row.target,
                row.current,
                row.latest,
                row.status,
            ]
        })
        .collect();

    println!(
        "{}",
        render_table(
            &["ID", "TYPE", "AGENT", "CURRENT", "LATEST", "STATUS"],
            &table_rows
        )
    );
    Ok(())
}

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

    fn entry(source: lockfile::CapabilitySource) -> lockfile::CapabilityLockEntry {
        lockfile::CapabilityLockEntry {
            capability_type: CapabilityType::Skill,
            version: "1.0.0".to_string(),
            version_scheme: lockfile::VersionScheme::Declared,
            description: String::new(),
            source,
            targets: BTreeMap::new(),
            implementation: None,
            parameters: None,
            workflow: None,
            server: None,
        }
    }

    #[test]
    fn a_capability_with_no_source_is_reported_as_unchecked() {
        // Anything installed from a pack without --reference, or from a
        // local path, has no git source and no registry to check. Reporting
        // "up to date" here states a conclusion that was never reached: the
        // row would claim the capability is current while LATEST is unknown.
        let (current, latest, status) = classify(
            "example",
            &entry(lockfile::CapabilitySource::local(
                "agent-capabilities/example",
            )),
            &OciTransferOptions::default(),
            &mut PackCheckCache::default(),
        );

        assert_eq!(status, "not checked");
        assert_ne!(
            status, "up to date",
            "an unchecked capability must not read as current"
        );
        assert_eq!(latest, "—");
        assert_eq!(current, "1.0.0");
    }

    #[test]
    fn a_newer_semver_tag_is_reported_as_outdated() {
        let tags = vec![
            "1.0.0".to_string(),
            "1.2.0".to_string(),
            "0.9.0".to_string(),
        ];
        let (current, latest, status) = pick_latest_pack_version("1.0.0", &tags);

        assert_eq!(status, "outdated");
        assert_eq!(current, "1.0.0");
        assert_eq!(latest, "1.2.0");
    }

    #[test]
    fn the_installed_tag_being_the_newest_reads_as_up_to_date() {
        let tags = vec!["1.0.0".to_string(), "0.9.0".to_string()];
        let (_, _, status) = pick_latest_pack_version("1.0.0", &tags);

        assert_eq!(status, "up to date");
    }

    #[test]
    fn version_ordering_is_semantic_not_lexicographic() {
        // Plain string comparison puts "1.9.0" after "1.10.0", because '9' >
        // '1' as the first differing character. That is the wrong answer,
        // and exactly the shape of bug this function exists to avoid.
        let tags = vec!["1.10.0".to_string()];
        let (_, latest, status) = pick_latest_pack_version("1.9.0", &tags);

        assert_eq!(status, "outdated");
        assert_eq!(latest, "1.10.0");
    }

    #[test]
    fn tags_that_do_not_parse_as_semver_are_excluded_not_guessed_at() {
        let tags = vec!["latest".to_string(), "nightly".to_string()];
        let (_, latest, status) = pick_latest_pack_version("1.0.0", &tags);

        assert_eq!(status, "not checked");
        assert_eq!(latest, "—");
    }

    #[test]
    fn an_unparsable_installed_version_is_reported_as_unchecked() {
        // tuff pack build --version does not enforce a version scheme, so
        // this is a real case: the pack itself may not be semver-tagged.
        let tags = vec!["1.0.0".to_string()];
        let (current, latest, status) = pick_latest_pack_version("release-42", &tags);

        assert_eq!(status, "not checked");
        assert_eq!(latest, "—");
        assert_eq!(current, "release-42");
    }

    #[test]
    fn a_repointed_tag_is_reported_even_when_a_newer_version_exists() {
        // "A newer version exists" and "the version you have is not what
        // you installed" are different findings; the second must not hide
        // behind the first. LATEST still shows the way forward.
        let tags = vec!["1.0.0".to_string(), "1.2.0".to_string()];
        let integrity = PackTagIntegrity::Repointed {
            live_digest: "sha256:beef".to_string(),
        };
        let (current, latest, status) = pack_row("1.0.0", &tags, &integrity);

        assert_eq!(status, "repointed");
        assert_eq!(current, "1.0.0");
        assert_eq!(latest, "1.2.0");
    }

    #[test]
    fn a_repointed_tag_never_reads_as_up_to_date() {
        let tags = vec!["1.0.0".to_string()];
        let integrity = PackTagIntegrity::Repointed {
            live_digest: "sha256:beef".to_string(),
        };
        let (_, _, status) = pack_row("1.0.0", &tags, &integrity);

        assert_eq!(status, "repointed");
    }

    #[test]
    fn a_deleted_tag_is_its_own_status() {
        let tags = vec!["1.2.0".to_string()];
        let (_, latest, status) = pack_row("1.0.0", &tags, &PackTagIntegrity::Missing);

        assert_eq!(status, "tag missing");
        assert_eq!(latest, "1.2.0");
    }

    #[test]
    fn a_matching_tag_leaves_the_version_verdict_alone() {
        let tags = vec!["1.0.0".to_string(), "1.2.0".to_string()];
        let (_, _, status) = pack_row("1.0.0", &tags, &PackTagIntegrity::Matches);
        assert_eq!(status, "outdated");

        let tags = vec!["1.0.0".to_string()];
        let (_, _, status) = pack_row("1.0.0", &tags, &PackTagIntegrity::Matches);
        assert_eq!(status, "up to date");
    }
}