modelshelf 0.1.0

//! The [`Shelf`]: the main entry point of the SDK.
//!
//! Designed FFI-first: all methods are synchronous, take `&self`, and use no
//! generics or lifetimes on public signatures, so a C API can wrap them 1:1.

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

use serde::Serialize;

use crate::hw::Hardware;
use crate::identity::HashCache;
use crate::paths::ShelfPaths;
use crate::recommend::{RecommendReport, RECOMMEND_APP_ID};
use crate::registry::{
    Ecosystem, Location, LocationRole, ModelEntry, ModelId, Registry, RegistryStore,
};
use crate::scan::{FoundFile, ScanEnv};
use crate::{Error, Result};

/// Options for [`Shelf::open`].
#[derive(Debug, Clone, Default)]
pub struct OpenOptions {
    path: Option<PathBuf>,
    app_id: Option<String>,
    lock_timeout: Option<Duration>,
}

impl OpenOptions {
    /// Open the shelf at an explicit directory instead of the default
    /// (`$MODELSHELF_HOME` or `~/.modelshelf`).
    pub fn at(path: impl Into<PathBuf>) -> Self {
        OpenOptions {
            path: Some(path.into()),
            ..Default::default()
        }
    }

    /// Identify the calling application (reverse-DNS style). Required for
    /// [`Shelf::add_ref`] / [`Shelf::remove_ref`].
    pub fn app_id(mut self, app_id: impl Into<String>) -> Self {
        self.app_id = Some(app_id.into());
        self
    }

    /// How long to wait for the registry lock (default 5 s).
    pub fn lock_timeout(mut self, timeout: Duration) -> Self {
        self.lock_timeout = Some(timeout);
        self
    }
}

/// How scans establish content identity for files whose hash is not already
/// known from a content-addressed store (Ollama blobs, HF LFS blobs).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum HashMode {
    /// Hash unknown files in full (streamed, cached by size+mtime). The
    /// first scan of a large tree is slow; rescans are free.
    #[default]
    Full,
    /// Only use free or previously cached hashes; report other files as
    /// skipped instead of reading gigabytes.
    CachedOnly,
}

/// Options for [`Shelf::scan`].
#[derive(Debug, Clone, Default)]
pub struct ScanOptions {
    /// Where to look for ecosystem roots (tests inject fake homes here).
    pub env: ScanEnv,
    /// Restrict to these ecosystems; `None` scans all.
    pub ecosystems: Option<Vec<Ecosystem>>,
    /// Additional user directories to walk for `*.gguf`.
    pub extra_roots: Vec<PathBuf>,
    /// Hashing strategy for files without a free hash.
    pub hash_mode: HashMode,
}

/// A file skipped during a scan, with the reason.
#[derive(Debug, Clone)]
pub struct SkippedFile {
    /// The file that was skipped.
    pub path: PathBuf,
    /// Human-readable reason.
    pub reason: String,
}

/// A group of identical-content copies found in more than one place.
#[derive(Debug, Clone)]
pub struct DupGroup {
    /// Content identity shared by every member.
    pub id: ModelId,
    /// Display name of the model.
    pub display_name: String,
    /// Every location holding this content.
    pub locations: Vec<PathBuf>,
    /// Number of physically distinct copies (hardlinks counted once when
    /// detectable; equals `locations.len()` otherwise).
    pub distinct_copies: usize,
    /// Bytes that dedup could reclaim: `size × (distinct_copies − 1)`.
    pub reclaimable_bytes: u64,
}

/// Result of [`Shelf::scan`].
#[derive(Debug, Clone, Default)]
pub struct ScanReport {
    /// Model files seen by the scanners.
    pub files_found: usize,
    /// Models that were not previously in the registry.
    pub new_models: usize,
    /// Registry locations dropped because the file no longer exists.
    pub locations_pruned: usize,
    /// Groups of duplicated content.
    pub duplicate_groups: Vec<DupGroup>,
    /// Files that could not be identified or read.
    pub skipped: Vec<SkippedFile>,
}

/// A remote model specification: `hf:<org>/<repo>[/<file.gguf>]`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelSpec {
    /// Hugging Face repo id (`org/repo`).
    pub repo: String,
    /// Specific file within the repo; `None` lets [`PullOptions::quant`] or
    /// a single-GGUF repo determine it.
    pub filename: Option<String>,
}

impl ModelSpec {
    /// Parse a spec string. Accepted forms:
    /// `hf:org/repo` and `hf:org/repo/path/to/file.gguf`.
    pub fn parse(s: &str) -> Result<Self> {
        let rest = s
            .strip_prefix("hf:")
            .ok_or_else(|| Error::InvalidSpec(format!("expected hf:<org>/<repo>[/file]: {s}")))?;
        let mut parts = rest.splitn(3, '/');
        let org = parts.next().filter(|p| !p.is_empty());
        let repo = parts.next().filter(|p| !p.is_empty());
        let (Some(org), Some(repo)) = (org, repo) else {
            return Err(Error::InvalidSpec(format!(
                "expected hf:<org>/<repo>[/file]: {s}"
            )));
        };
        Ok(ModelSpec {
            repo: format!("{org}/{repo}"),
            filename: parts.next().map(str::to_owned),
        })
    }
}

/// Options for [`Shelf::ensure`] / [`Shelf::pull_update`].
#[derive(Default)]
pub struct PullOptions {
    /// Alternative hub endpoint (tests, mirrors). `None` = huggingface.co.
    pub endpoint: Option<String>,
    /// Pick the repo file whose name contains this quantization label
    /// (case-insensitive) when the spec names no file.
    pub quant: Option<String>,
    /// Progress callback for downloads.
    pub progress: Option<Box<crate::download::ProgressFn>>,
}

impl std::fmt::Debug for PullOptions {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PullOptions")
            .field("endpoint", &self.endpoint)
            .field("quant", &self.quant)
            .field("progress", &self.progress.as_ref().map(|_| "<fn>"))
            .finish()
    }
}

/// A query for [`Shelf::find`]. All set conditions must match.
#[derive(Debug, Clone, Default)]
pub struct ModelQuery {
    name_contains: Option<String>,
    quantization: Option<String>,
}

impl ModelQuery {
    /// Match models whose display name or GGUF name contains `needle`
    /// (case-insensitive).
    pub fn name_contains(needle: impl Into<String>) -> Self {
        ModelQuery {
            name_contains: Some(needle.into()),
            ..Default::default()
        }
    }

    /// Additionally require an exact quantization label (e.g. `Q4_K_M`).
    pub fn quant(mut self, quant: impl Into<String>) -> Self {
        self.quantization = Some(quant.into());
        self
    }

    fn matches(&self, m: &ModelEntry) -> bool {
        if let Some(needle) = &self.name_contains {
            // Case-insensitive, and `-`/`_`/space are interchangeable so
            // "llama-3.1" matches "Meta Llama 3.1 8B Instruct".
            let needle = normalize(needle);
            let in_display = normalize(&m.display_name).contains(&needle);
            let in_gguf = m
                .gguf
                .as_ref()
                .and_then(|g| g.general_name.as_ref())
                .is_some_and(|n| normalize(n).contains(&needle));
            if !in_display && !in_gguf {
                return false;
            }
        }
        if let Some(quant) = &self.quantization {
            let has = m
                .gguf
                .as_ref()
                .and_then(|g| g.quantization.as_ref())
                .is_some_and(|q| q.eq_ignore_ascii_case(quant));
            if !has {
                return false;
            }
        }
        true
    }
}

pub(crate) fn normalize(s: &str) -> String {
    s.to_lowercase().replace(['-', '_'], " ")
}

/// A handle to the shared shelf. Cheap to clone; safe to use from multiple
/// threads (every operation locks the registry on disk).
#[derive(Debug, Clone)]
pub struct Shelf {
    paths: ShelfPaths,
    store: RegistryStore,
    app_id: Option<String>,
}

impl Shelf {
    /// Open (creating if necessary) the shelf.
    pub fn open(options: OpenOptions) -> Result<Self> {
        let paths = ShelfPaths::resolve(options.path.as_deref()).ok_or_else(|| {
            Error::Refused("cannot determine shelf home (no home directory)".into())
        })?;
        paths.ensure_layout()?;
        let timeout = options
            .lock_timeout
            .unwrap_or(crate::registry::lock::DEFAULT_LOCK_TIMEOUT);
        Ok(Shelf {
            store: RegistryStore::new(paths.clone(), timeout),
            paths,
            app_id: options.app_id,
        })
    }

    /// The resolved shelf home paths.
    pub fn paths(&self) -> &ShelfPaths {
        &self.paths
    }

    /// Direct access to the registry store (advanced use).
    pub fn registry(&self) -> &RegistryStore {
        &self.store
    }

    /// Discard a corrupt registry and start empty. See
    /// [`RegistryStore::rebuild`]; never called automatically.
    pub fn rebuild(&self) -> Result<()> {
        self.store.rebuild().map(|_| ())
    }

    /// All models currently in the registry.
    pub fn list(&self) -> Result<Vec<ModelEntry>> {
        Ok(self.store.read()?.models)
    }

    /// Models matching `query`.
    pub fn find(&self, query: &ModelQuery) -> Result<Vec<ModelEntry>> {
        Ok(self
            .store
            .read()?
            .models
            .into_iter()
            .filter(|m| query.matches(m))
            .collect())
    }

    /// The canonical store path for a model, if it has been adopted into the
    /// shelf's blob store. This is the path apps feed to their runtime.
    pub fn blob_path(&self, id: &ModelId) -> Result<PathBuf> {
        let hex = id
            .sha256_hex()
            .ok_or_else(|| Error::InvalidSpec(format!("not a sha256 id: {id}")))?;
        let path = self.paths.blob_file(hex);
        if path.is_file() {
            Ok(path)
        } else {
            Err(Error::NotFound(format!("no store blob for {id}")))
        }
    }

    /// Declare that the calling app (from [`OpenOptions::app_id`]) uses a
    /// model. Referenced models are protected from `gc`.
    pub fn add_ref(&self, id: &ModelId, alias: &str) -> Result<()> {
        let app_id = self.require_app_id()?.to_owned();
        let alias = alias.to_owned();
        let id = id.clone();
        self.store.update(move |reg| {
            let entry = reg
                .find_mut(&id)
                .ok_or_else(|| Error::NotFound(id.to_string()))?;
            if let Some(existing) = entry.refs.iter_mut().find(|r| r.app_id == app_id) {
                existing.alias = Some(alias);
            } else {
                entry.refs.push(crate::registry::AppRef {
                    app_id,
                    alias: Some(alias),
                    added_at: crate::time_util::now_rfc3339(),
                    extra: Default::default(),
                });
            }
            Ok(())
        })
    }

    /// Remove the calling app's reference from a model.
    pub fn remove_ref(&self, id: &ModelId) -> Result<()> {
        let app_id = self.require_app_id()?.to_owned();
        let id = id.clone();
        self.store.update(move |reg| {
            let entry = reg
                .find_mut(&id)
                .ok_or_else(|| Error::NotFound(id.to_string()))?;
            entry.refs.retain(|r| r.app_id != app_id);
            Ok(())
        })
    }

    fn require_app_id(&self) -> Result<&str> {
        self.app_id.as_deref().ok_or_else(|| {
            Error::Refused("no app_id configured; set it via OpenOptions::app_id".into())
        })
    }

    /// Scan the machine for local models and merge the results into the
    /// registry. Returns what changed and which duplicates exist.
    pub fn scan(&self, options: &ScanOptions) -> Result<ScanReport> {
        let found = crate::scan::scan_all(
            &options.env,
            options.ecosystems.as_deref(),
            &options.extra_roots,
        );

        let mut report = ScanReport {
            files_found: found.len(),
            ..Default::default()
        };

        // Resolve content identity for every found file (outside the
        // registry lock: hashing can take minutes on first scan).
        let mut cache = HashCache::load(self.paths.home());
        let mut identified: Vec<(ModelId, FoundFile)> = Vec::new();
        for f in found {
            let id = match &f.known_sha256 {
                Some(hex) => ModelId::from_sha256_hex(hex),
                None => match options.hash_mode {
                    HashMode::Full => match cache.model_id_of(&f.path) {
                        Ok(id) => id,
                        Err(e) => {
                            report.skipped.push(SkippedFile {
                                path: f.path.clone(),
                                reason: e.to_string(),
                            });
                            continue;
                        }
                    },
                    HashMode::CachedOnly => {
                        report.skipped.push(SkippedFile {
                            path: f.path.clone(),
                            reason: "no cached hash (rerun with full hashing)".into(),
                        });
                        continue;
                    }
                },
            };
            identified.push((id, f));
        }
        cache.save(self.paths.home())?;

        // GGUF metadata for ids we don't know yet (one representative file
        // per id is enough).
        let existing_ids: std::collections::HashSet<ModelId> = self
            .store
            .read()?
            .models
            .iter()
            .filter(|m| m.gguf.is_some())
            .map(|m| m.id.clone())
            .collect();
        let mut gguf_meta: std::collections::HashMap<ModelId, crate::registry::GgufMeta> =
            std::collections::HashMap::new();
        for (id, f) in &identified {
            if existing_ids.contains(id) || gguf_meta.contains_key(id) {
                continue;
            }
            if crate::gguf::is_gguf(&f.path) {
                if let Ok(meta) = crate::gguf::read_meta(&f.path) {
                    gguf_meta.insert(id.clone(), meta);
                }
            }
        }

        let blobs_dir = self.paths.blobs_dir();
        let (new_models, locations_pruned) = self
            .store
            .update(move |reg| merge_found(reg, identified, gguf_meta, &blobs_dir))?;
        report.new_models = new_models;
        report.locations_pruned = locations_pruned;

        report.duplicate_groups = duplicate_groups(&self.store.read()?);
        Ok(report)
    }
}

/// Merge identified files into the registry. Returns (new models, pruned
/// locations). Runs under the exclusive registry lock.
fn merge_found(
    reg: &mut Registry,
    identified: Vec<(ModelId, FoundFile)>,
    mut gguf_meta: std::collections::HashMap<ModelId, crate::registry::GgufMeta>,
    blobs_dir: &Path,
) -> Result<(usize, usize)> {
    let now = crate::time_util::now_rfc3339();
    let mut new_models = 0usize;

    for (id, f) in identified {
        let role = if f.path.starts_with(blobs_dir) {
            LocationRole::Store
        } else {
            LocationRole::External
        };
        let entry = match reg.find_mut(&id) {
            Some(e) => e,
            None => {
                new_models += 1;
                reg.models.push(ModelEntry {
                    id: id.clone(),
                    format: "gguf".into(),
                    size_bytes: f.size_bytes,
                    display_name: f.display_name.clone(),
                    gguf: None,
                    source: None,
                    store_path: None,
                    locations: Vec::new(),
                    refs: Vec::new(),
                    first_seen: now.clone(),
                    last_verified: None,
                    extra: Default::default(),
                });
                reg.models.last_mut().expect("just pushed")
            }
        };

        if let Some(meta) = gguf_meta.remove(&id) {
            // Prefer the GGUF's own name for display.
            if let Some(name) = &meta.general_name {
                if entry.display_name == f.display_name || entry.display_name.is_empty() {
                    entry.display_name = name.clone();
                }
            }
            entry.gguf = Some(meta);
        }
        if entry.source.is_none() {
            entry.source = f.source.clone();
        }
        if role == LocationRole::Store {
            entry.store_path = f
                .path
                .file_name()
                .map(|n| format!("blobs/{}", n.to_string_lossy()));
        }

        match entry.locations.iter_mut().find(|l| l.path == f.path) {
            Some(loc) => {
                loc.last_seen = now.clone();
                loc.ecosystem = f.ecosystem;
            }
            None => entry.locations.push(Location {
                path: f.path.clone(),
                ecosystem: f.ecosystem,
                role,
                last_seen: now.clone(),
                extra: Default::default(),
            }),
        }
    }

    // Prune locations whose file disappeared; drop entries left with
    // nothing on disk at all.
    let mut pruned = 0usize;
    for entry in &mut reg.models {
        let before = entry.locations.len();
        entry.locations.retain(|l| l.path.is_file());
        pruned += before - entry.locations.len();
    }
    reg.models.retain(|m| !m.locations.is_empty());

    Ok((new_models, pruned))
}

/// Compute duplicate groups from registry state.
fn duplicate_groups(reg: &Registry) -> Vec<DupGroup> {
    let mut groups = Vec::new();
    for m in &reg.models {
        if m.locations.len() < 2 {
            continue;
        }
        // Count physically distinct copies: locations that don't share an
        // inode with an earlier location.
        let paths: Vec<&PathBuf> = m.locations.iter().map(|l| &l.path).collect();
        let mut distinct = 0usize;
        for (i, p) in paths.iter().enumerate() {
            let dup_of_earlier = paths[..i].iter().any(|q| crate::identity::same_inode(p, q));
            if !dup_of_earlier {
                distinct += 1;
            }
        }
        if distinct > 1 {
            groups.push(DupGroup {
                id: m.id.clone(),
                display_name: m.display_name.clone(),
                locations: m.locations.iter().map(|l| l.path.clone()).collect(),
                distinct_copies: distinct,
                reclaimable_bytes: m.size_bytes * (distinct as u64 - 1),
            });
        }
    }
    groups.sort_by_key(|g| std::cmp::Reverse(g.reclaimable_bytes));
    groups
}

// ---- acquisition & updates ----------------------------------------------

impl Shelf {
    /// Make a model available locally, downloading only if necessary.
    ///
    /// Resolution order:
    /// 1. the hub is asked which file the spec means and what its content
    ///    sha256 is (one metadata request, no download);
    /// 2. if that content already exists anywhere locally, it is adopted
    ///    into the store (hardlink — zero extra disk) and returned;
    /// 3. otherwise the file is downloaded (resumable), verified against
    ///    the expected hash, and registered.
    pub fn ensure(&self, spec: &ModelSpec, options: &PullOptions) -> Result<ModelEntry> {
        let client = crate::download::hf::HfClient::from_env(options.endpoint.as_deref());
        let info = client.repo_info(&spec.repo)?;
        let file = select_file(&info, spec, options)?;
        let expected_sha = file.sha256();
        let rfilename = file.rfilename.clone();

        // Already have this exact content somewhere?
        if let Some(sha) = &expected_sha {
            let id = ModelId::from_sha256_hex(sha);
            if let Some(entry) = self.store.read()?.find(&id).cloned() {
                return self.adopt_entry(entry, &spec.repo, &rfilename, &info.sha);
            }
        }

        // Download into downloads/, verify, promote into blobs/.
        let downloaded = client.download_file(
            &spec.repo,
            &info.sha,
            &rfilename,
            expected_sha.as_deref(),
            &self.paths.downloads_dir(),
            options.progress.as_deref(),
        )?;
        let blob =
            crate::store::promote_download(&self.paths, &downloaded.path, &downloaded.sha256)?;
        self.register_blob(
            &downloaded.sha256,
            &blob,
            downloaded.size_bytes,
            &spec.repo,
            &rfilename,
            &info.sha,
        )
    }

    /// Check all Hugging Face-sourced models for newer content. Read-only:
    /// performs network requests but never mutates the registry.
    pub fn check_updates(
        &self,
        options: &crate::update::UpdateOptions,
    ) -> Result<crate::update::UpdateReport> {
        let client = crate::download::hf::HfClient::from_env(options.endpoint.as_deref());
        let models = self.store.read()?.models;
        crate::update::check_updates(&client, &models)
    }

    /// Download the newer revision described by an [`UpdateInfo`]. The old
    /// model entry is kept (apps may still reference it) until `gc`.
    pub fn pull_update(
        &self,
        update: &crate::update::UpdateInfo,
        options: &PullOptions,
    ) -> Result<ModelEntry> {
        let spec = ModelSpec {
            repo: update.repo.clone(),
            filename: Some(update.filename.clone()),
        };
        self.ensure(&spec, options)
    }

    /// The model exists in the registry: make sure a store copy exists too,
    /// then stamp the freshest source mapping.
    fn adopt_entry(
        &self,
        entry: ModelEntry,
        repo: &str,
        rfilename: &str,
        revision: &str,
    ) -> Result<ModelEntry> {
        let hex = entry
            .id
            .sha256_hex()
            .ok_or_else(|| Error::InvalidSpec(format!("not a sha256 id: {}", entry.id)))?
            .to_owned();
        let blob = self.paths.blob_file(&hex);
        if !blob.is_file() {
            let src = entry
                .locations
                .iter()
                .map(|l| l.path.clone())
                .find(|p| p.is_file())
                .ok_or_else(|| {
                    Error::NotFound(format!("{}: all recorded locations vanished", entry.id))
                })?;
            crate::store::adopt(&self.paths, &src, &hex)?;
        }
        self.register_blob(&hex, &blob, entry.size_bytes, repo, rfilename, revision)
    }

    /// Upsert the registry entry for a store blob and return it.
    fn register_blob(
        &self,
        sha256_hex: &str,
        blob: &Path,
        size_bytes: u64,
        repo: &str,
        rfilename: &str,
        revision: &str,
    ) -> Result<ModelEntry> {
        let id = ModelId::from_sha256_hex(sha256_hex);
        let gguf_meta = if crate::gguf::is_gguf(blob) {
            crate::gguf::read_meta(blob).ok()
        } else {
            None
        };
        let format = file_format(rfilename, gguf_meta.is_some());
        let blob = blob.to_path_buf();
        let store_rel = format!("blobs/sha256-{sha256_hex}");
        let repo = repo.to_owned();
        let rfilename = rfilename.to_owned();
        let revision = revision.to_owned();

        self.store.update(move |reg| {
            let now = crate::time_util::now_rfc3339();
            let entry = match reg.find_mut(&id) {
                Some(e) => e,
                None => {
                    let display_name = gguf_meta
                        .as_ref()
                        .and_then(|g| g.general_name.clone())
                        .unwrap_or_else(|| {
                            std::path::Path::new(&rfilename)
                                .file_stem()
                                .map(|s| s.to_string_lossy().into_owned())
                                .unwrap_or_else(|| rfilename.clone())
                        });
                    reg.models.push(ModelEntry {
                        id: id.clone(),
                        format: format.into(),
                        size_bytes,
                        display_name,
                        gguf: None,
                        source: None,
                        store_path: None,
                        locations: Vec::new(),
                        refs: Vec::new(),
                        first_seen: now.clone(),
                        last_verified: Some(now.clone()),
                        extra: Default::default(),
                    });
                    reg.models.last_mut().expect("just pushed")
                }
            };
            if entry.gguf.is_none() {
                entry.gguf = gguf_meta.clone();
            }
            entry.store_path = Some(store_rel.clone());
            entry.source = Some(crate::registry::Source {
                kind: "huggingface".into(),
                repo: repo.clone(),
                filename: rfilename.clone(),
                revision: Some(revision.clone()),
                resolved_at: now.clone(),
                extra: Default::default(),
            });
            match entry.locations.iter_mut().find(|l| l.path == blob) {
                Some(loc) => loc.last_seen = now.clone(),
                None => entry.locations.push(Location {
                    path: blob.clone(),
                    ecosystem: Ecosystem::Shelf,
                    role: LocationRole::Store,
                    last_seen: now.clone(),
                    extra: Default::default(),
                }),
            }
            Ok(entry.clone())
        })
    }
}

/// Registry `format` value for a downloaded file: by parsed GGUF header
/// first, then by extension (`.bin` = ggml, e.g. whisper.cpp models).
fn file_format(rfilename: &str, is_gguf: bool) -> &'static str {
    if is_gguf {
        return "gguf";
    }
    let lower = rfilename.to_ascii_lowercase();
    if lower.ends_with(".gguf") {
        "gguf"
    } else if lower.ends_with(".bin") {
        "ggml"
    } else if lower.ends_with(".onnx") {
        "onnx"
    } else {
        "other"
    }
}

/// Pick which repo file a spec refers to.
fn select_file<'a>(
    info: &'a crate::download::hf::RepoInfo,
    spec: &ModelSpec,
    options: &PullOptions,
) -> Result<&'a crate::download::hf::RepoFile> {
    if let Some(name) = &spec.filename {
        return info
            .file(name)
            .ok_or_else(|| Error::NotFound(format!("{}: no file named {name}", spec.repo)));
    }
    let ggufs = info.gguf_files();
    if let Some(quant) = &options.quant {
        let quant_lower = quant.to_lowercase();
        let matches: Vec<_> = ggufs
            .iter()
            .filter(|f| f.rfilename.to_lowercase().contains(&quant_lower))
            .collect();
        return match matches.as_slice() {
            [one] => Ok(**one),
            [] => Err(Error::NotFound(format!(
                "{}: no .gguf file matching quantization {quant}",
                spec.repo
            ))),
            many => Err(Error::InvalidSpec(format!(
                "{}: quantization {quant} is ambiguous: {}",
                spec.repo,
                many.iter()
                    .map(|f| f.rfilename.as_str())
                    .collect::<Vec<_>>()
                    .join(", ")
            ))),
        };
    }
    match ggufs.as_slice() {
        [one] => Ok(one),
        [] => Err(Error::NotFound(format!(
            "{}: repo contains no .gguf files",
            spec.repo
        ))),
        many => Err(Error::InvalidSpec(format!(
            "{}: specify a file or --quant; candidates: {}",
            spec.repo,
            many.iter()
                .map(|f| f.rfilename.as_str())
                .collect::<Vec<_>>()
                .join(", ")
        ))),
    }
}

#[cfg(test)]
mod spec_tests {
    use super::ModelSpec;

    #[test]
    fn parses_repo_only_and_repo_with_file() {
        let s = ModelSpec::parse("hf:org/repo").unwrap();
        assert_eq!(s.repo, "org/repo");
        assert_eq!(s.filename, None);

        let s = ModelSpec::parse("hf:org/repo/sub/dir/file.gguf").unwrap();
        assert_eq!(s.repo, "org/repo");
        assert_eq!(s.filename.as_deref(), Some("sub/dir/file.gguf"));
    }

    #[test]
    fn rejects_malformed_specs() {
        for bad in ["org/repo", "hf:", "hf:solo", "hf:/repo", "hf:org/"] {
            assert!(ModelSpec::parse(bad).is_err(), "should reject {bad}");
        }
    }
}

// ---- recommendations ------------------------------------------------------

/// Options for [`Shelf::recommend_with`] / [`Shelf::provision_recommended`].
#[derive(Debug, Clone)]
pub struct RecommendOptions {
    /// The use case to recommend for (default `chat`); see
    /// [`crate::recommend::KNOWN_TASKS`].
    pub task: String,
    /// Explicit catalog URL for refreshes. `None` falls back to
    /// `MODELSHELF_CATALOG_URL`, then [`crate::catalog::DEFAULT_CATALOG_URL`].
    pub catalog_url: Option<String>,
    /// Skip the opportunistic catalog refresh (offline mode, tests).
    pub no_refresh: bool,
}

impl Default for RecommendOptions {
    fn default() -> Self {
        RecommendOptions {
            task: "chat".to_owned(),
            catalog_url: None,
            no_refresh: false,
        }
    }
}

/// Result of [`Shelf::provision_recommended`].
#[derive(Debug, Clone, Serialize)]
pub struct ProvisionOutcome {
    /// The provisioned model; its store blob exists.
    pub entry: ModelEntry,
    /// Companion files the entry needs at runtime (a TTS vocoder, a vision
    /// projector, …), each provisioned into the store as well.
    pub extras: Vec<ModelEntry>,
    /// Models (a main model and its companions) that previously were this
    /// task's recommendation and got unmarked. Nothing is deleted
    /// automatically: the caller decides (typically after asking the user)
    /// whether to pass them to [`Shelf::remove_if_unreferenced`].
    pub replaced: Vec<ModelEntry>,
}

/// Result of [`Shelf::remove_if_unreferenced`].
#[derive(Debug, Clone, Serialize)]
#[serde(tag = "outcome", rename_all = "snake_case")]
pub enum RemoveOutcome {
    /// The model was deregistered and its store blob deleted.
    Removed {
        /// Nominal bytes freed (the blob size).
        bytes_freed: u64,
    },
    /// Kept: applications still reference it.
    KeptReferenced {
        /// The referencing application ids.
        apps: Vec<String>,
    },
    /// Kept: copies exist outside the shelf store. modelshelf never deletes
    /// inside other ecosystems' directories.
    KeptExternalCopies {
        /// The external copies.
        paths: Vec<PathBuf>,
    },
}

impl Shelf {
    /// Evaluate the model catalog against `hw` and the current registry:
    /// what fits, what is already installed, and whether the model
    /// provisioned via [`Shelf::provision_recommended`] has been superseded
    /// ([`RecommendReport::upgrade`] — applications surface that as their
    /// "a better model is available" notification).
    ///
    /// Unless disabled, the catalog cache is refreshed first — at most once
    /// per [`crate::catalog::REFRESH_TTL`], with failures ignored, so this
    /// works offline.
    pub fn recommend_with(
        &self,
        hw: &Hardware,
        options: &RecommendOptions,
    ) -> Result<RecommendReport> {
        if !options.no_refresh {
            crate::catalog::refresh_if_stale(&self.paths, options.catalog_url.as_deref());
        }
        let (catalog, origin) = crate::catalog::load(&self.paths);
        let installed = self.list()?;
        Ok(crate::recommend::recommend(
            &catalog,
            origin,
            hw,
            &installed,
            &options.task,
        ))
    }

    /// [`Shelf::recommend_with`] with default options (the `chat` task).
    pub fn recommend(&self, hw: &Hardware) -> Result<RecommendReport> {
        self.recommend_with(hw, &RecommendOptions::default())
    }

    /// Upgrade signals for *every* task that has a provisioned model
    /// (`options.task` is ignored). What background "a better model is
    /// available" checks should surface.
    pub fn recommend_upgrades(
        &self,
        hw: &Hardware,
        options: &RecommendOptions,
    ) -> Result<Vec<crate::recommend::Upgrade>> {
        if !options.no_refresh {
            crate::catalog::refresh_if_stale(&self.paths, options.catalog_url.as_deref());
        }
        let (catalog, origin) = crate::catalog::load(&self.paths);
        let installed = self.list()?;
        Ok(crate::recommend::all_upgrades(
            &catalog, origin, hw, &installed,
        ))
    }

    /// Fetch the latest catalog now and cache it: the explicit counterpart
    /// of the opportunistic refresh. Returns the fetched catalog.
    pub fn update_catalog(&self, url: Option<&str>) -> Result<crate::catalog::Catalog> {
        crate::catalog::fetch_and_cache(&self.paths, url)
    }

    /// One-call machine setup for a task: pick the best model for `hw`,
    /// make it locally available (reusing any byte-identical local copy,
    /// resuming interrupted downloads, verifying hashes) together with its
    /// companion files, and mark everything as the task's current
    /// recommendation (`sh.modelshelf.recommend.<task>` refs).
    ///
    /// Fails with [`Error::Refused`] when no catalog model fits.
    pub fn provision_recommended(
        &self,
        hw: &Hardware,
        rec_options: &RecommendOptions,
        pull_options: &PullOptions,
    ) -> Result<ProvisionOutcome> {
        let report = self.recommend_with(hw, rec_options)?;
        let best = report.best_item().ok_or_else(|| {
            Error::Refused(format!(
                "no catalog model for task {:?} fits this machine (memory budget {} bytes)",
                rec_options.task, report.budget_bytes
            ))
        })?;
        let entry = self.ensure(
            &ModelSpec {
                repo: best.entry.repo.clone(),
                filename: Some(best.entry.filename.clone()),
            },
            pull_options,
        )?;
        let mut extras = Vec::new();
        for extra in &best.entry.extra_files {
            extras.push(
                self.ensure(
                    &ModelSpec {
                        repo: extra
                            .repo
                            .clone()
                            .unwrap_or_else(|| best.entry.repo.clone()),
                        filename: Some(extra.filename.clone()),
                    },
                    // Progress callbacks are tied to the main download.
                    &PullOptions {
                        endpoint: pull_options.endpoint.clone(),
                        quant: None,
                        progress: None,
                    },
                )?,
            );
        }

        // Move the task's recommendation mark onto the new model set.
        let app_id = crate::recommend::recommend_app_id(&rec_options.task);
        let legacy_chat = rec_options.task == "chat";
        let name = best.entry.name.clone();
        let mut keep_ids: Vec<ModelId> = vec![entry.id.clone()];
        keep_ids.extend(extras.iter().map(|e| e.id.clone()));
        let aliases: Vec<(ModelId, String)> = std::iter::once((entry.id.clone(), name.clone()))
            .chain(
                extras
                    .iter()
                    .map(|e| (e.id.clone(), format!("{name}#extra"))),
            )
            .collect();
        let (entry, extras, replaced) = self.store.update(move |reg| {
            let mut replaced = Vec::new();
            for m in reg.models.iter_mut().filter(|m| !keep_ids.contains(&m.id)) {
                let is_marked = m
                    .refs
                    .iter()
                    .any(|r| r.app_id == app_id || (legacy_chat && r.app_id == RECOMMEND_APP_ID));
                if is_marked {
                    m.refs.retain(|r| {
                        r.app_id != app_id && !(legacy_chat && r.app_id == RECOMMEND_APP_ID)
                    });
                    replaced.push(m.clone());
                }
            }
            let now = crate::time_util::now_rfc3339();
            let mut updated = Vec::new();
            for (id, alias) in &aliases {
                let e = reg
                    .find_mut(id)
                    .ok_or_else(|| Error::NotFound(id.to_string()))?;
                match e.refs.iter_mut().find(|r| r.app_id == app_id) {
                    Some(r) => r.alias = Some(alias.clone()),
                    None => e.refs.push(crate::registry::AppRef {
                        app_id: app_id.clone(),
                        alias: Some(alias.clone()),
                        added_at: now.clone(),
                        extra: Default::default(),
                    }),
                }
                updated.push(e.clone());
            }
            let entry = updated.remove(0);
            Ok((entry, updated, replaced))
        })?;
        Ok(ProvisionOutcome {
            entry,
            extras,
            replaced,
        })
    }

    /// Remove a model when nothing needs it anymore: deregisters it and
    /// deletes its store blob, but only if **no** application references it
    /// and **no** copies exist outside the shelf store. Copies inside other
    /// ecosystems (Ollama, LM Studio, the HF cache, …) are never touched;
    /// their existence keeps the model registered.
    pub fn remove_if_unreferenced(&self, id: &ModelId) -> Result<RemoveOutcome> {
        let hex = id
            .sha256_hex()
            .ok_or_else(|| Error::InvalidSpec(format!("not a sha256 id: {id}")))?
            .to_owned();
        let blobs_dir = self.paths.blobs_dir();
        let target = id.clone();
        let outcome = self.store.update(move |reg| {
            let Some(pos) = reg.models.iter().position(|m| m.id == target) else {
                return Err(Error::NotFound(target.to_string()));
            };
            let entry = &reg.models[pos];
            let apps: Vec<String> = entry.refs.iter().map(|r| r.app_id.clone()).collect();
            if !apps.is_empty() {
                return Ok(RemoveOutcome::KeptReferenced { apps });
            }
            let external: Vec<PathBuf> = entry
                .locations
                .iter()
                .filter(|l| !l.path.starts_with(&blobs_dir))
                .map(|l| l.path.clone())
                .collect();
            if !external.is_empty() {
                return Ok(RemoveOutcome::KeptExternalCopies { paths: external });
            }
            let removed = reg.models.remove(pos);
            Ok(RemoveOutcome::Removed {
                bytes_freed: removed.size_bytes,
            })
        })?;
        if let RemoveOutcome::Removed { .. } = &outcome {
            let blob = self.paths.blob_file(&hex);
            match std::fs::remove_file(&blob) {
                Ok(()) => {}
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
                // The entry is already deregistered; the blob is now an
                // orphan `gc` can collect, but surface the failure.
                Err(e) => return Err(Error::io(&blob, e)),
            }
        }
        Ok(outcome)
    }
}

// ---- dedup & gc -----------------------------------------------------------

/// Result of [`Shelf::gc`].
#[derive(Debug, Clone, Default)]
pub struct GcReport {
    /// Store blobs with no registry entry at all (safe to delete: they are
    /// either leftovers of interrupted operations or of removed models).
    pub orphan_blobs: Vec<PathBuf>,
    /// Blobs actually deleted (only when applying).
    pub deleted: usize,
    /// Nominal bytes freed. Note: if other hardlinks to the same inode
    /// exist, the space is only reclaimed once those are gone too.
    pub bytes_freed: u64,
    /// Models whose store blob exists but that no app references. Reported
    /// for visibility; never deleted automatically.
    pub unreferenced: Vec<ModelId>,
}

impl Shelf {
    /// Compute a deduplication plan. Pure: reads files and the registry,
    /// changes nothing. Inspect [`crate::dedup::DedupPlan::summary`] and the
    /// per-action details before applying.
    pub fn plan_dedup(
        &self,
        options: &crate::dedup::DedupOptions,
    ) -> Result<crate::dedup::DedupPlan> {
        let reg = self.store.read()?;
        crate::dedup::plan::build(&self.paths, &reg, options)
    }

    /// Apply a dedup plan: journaled, re-verified, atomic. Actions whose
    /// target changed since planning are skipped individually.
    pub fn apply_dedup(&self, plan: &crate::dedup::DedupPlan) -> Result<crate::dedup::DedupReport> {
        crate::dedup::execute::apply(&self.paths, &self.store, plan)
    }

    /// Revert a previous [`Shelf::apply_dedup`] operation: every replaced
    /// file becomes an independent copy again.
    pub fn undo(&self, op_id: &str) -> Result<crate::dedup::UndoReport> {
        crate::dedup::undo::undo(&self.paths, &self.store, op_id)
    }

    /// Journal ids of past dedup operations, newest first.
    pub fn journal_ops(&self) -> Result<Vec<String>> {
        let dir = self.paths.journal_dir();
        let mut ids: Vec<String> = match std::fs::read_dir(&dir) {
            Ok(entries) => entries
                .filter_map(|e| e.ok())
                .filter_map(|e| {
                    e.file_name()
                        .to_string_lossy()
                        .strip_suffix(".json")
                        .map(str::to_owned)
                })
                .collect(),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Vec::new(),
            Err(e) => return Err(Error::io(&dir, e)),
        };
        ids.sort_by(|a, b| b.cmp(a));
        Ok(ids)
    }

    /// Garbage-collect the store. With `apply == false` this only reports.
    /// Only *orphan* blobs (no registry entry) are ever deleted; models
    /// without app references are reported but kept.
    pub fn gc(&self, apply: bool) -> Result<GcReport> {
        let reg = self.store.read()?;
        let mut report = GcReport::default();
        for (hex, path) in crate::store::list_blobs(&self.paths)? {
            let id = ModelId::from_sha256_hex(&hex);
            match reg.find(&id) {
                None => {
                    let size = std::fs::metadata(&path).map(|m| m.len()).unwrap_or(0);
                    if apply {
                        std::fs::remove_file(&path).map_err(|e| Error::io(&path, e))?;
                        report.deleted += 1;
                        report.bytes_freed += size;
                    }
                    report.orphan_blobs.push(path);
                }
                Some(entry) if entry.refs.is_empty() => {
                    report.unreferenced.push(entry.id.clone());
                }
                Some(_) => {}
            }
        }
        Ok(report)
    }
}