feat: add metadata

[kerthcet]

What this PR does / why we need it

Which issue(s) this PR fixes

Fixes #

Special notes for your reviewer

Does this PR introduce a user-facing change?

[Copilot]

Pull request overview

This PR expands PUMA’s CLI capabilities by adding a local model registry (metadata persistence), Hugging Face download support with progress reporting, and system/cache introspection utilities.

Changes:

• Introduces registry + system modules to track local models and display system/cache information.
• Adds utils formatting/helpers and a Hugging Face downloader with multi-file progress rendering.
• Updates project tooling/docs (CI workflow, Makefile targets, README) and removes the old util module.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/utils/mod.rs	Defines the new utils module surface (file + format).
src/utils/format.rs	Adds formatting helpers (sizes/parameters/time-ago) and unit tests.
src/utils/file.rs	Adds cache/home-path helpers and model-name formatting for HF cache layout.
src/system/system_info.rs	Implements system info + GPU detection + cache size calculation.
src/system/mod.rs	Exposes the system module.
src/registry/model_registry.rs	Implements model metadata storage (models.json) and model removal.
src/registry/mod.rs	Exposes the registry module.
src/main.rs	Wires new modules into the binary and adjusts logger initialization.
src/lib.rs	Adds a library target file (currently empty).
src/downloader/progress.rs	Adds multi-progress display manager for downloads.
src/downloader/mod.rs	Exposes downloader submodules publicly.
src/downloader/huggingface.rs	Implements Hugging Face snapshot download + registry integration + tests.
src/downloader/downloader.rs	Refactors downloader error types and introduces a Downloader trait.
src/cli/commands.rs	Updates CLI commands to use registry/downloader/system info features.
README.md	Updates documentation with commands, features, and examples.
Makefile	Adds test, lint, and formatting targets.
Cargo.toml	Adds new dependencies for registry/system/HF download and bumps indicatif.
Cargo.lock	Locks new/updated dependency graph.
.github/workflows/rust-ci.yaml	Adds CI jobs for lint and tests.
src/util/request.rs	Removed legacy chunked download implementation.
src/util/mod.rs	Removed legacy util module.
src/util/file.rs	Removed old home-dir helper (superseded by utils::file).

Comments suppressed due to low confidence (3)

src/downloader/huggingface.rs:134

• This spawns one Tokio task per file in the model repo with no concurrency limiting. Large repos can contain hundreds/thousands of files, which can overwhelm the runtime and Hugging Face API. Consider using a bounded concurrency approach (e.g., tokio::sync::Semaphore, FuturesUnordered + buffer_unordered, or batching) while still updating progress bars.

        // Process all files in manifest order (cached files show as instantly complete)
        let mut tasks = Vec::new();

        for sibling in model_info.siblings {
            let api_clone = api.clone();
            let model_name = name.to_string();
            let filename = sibling.rfilename.clone();
            let progress_manager_clone = progress_manager.clone();
            let snapshot_path_clone = snapshot_path.clone();

            let task = tokio::spawn(async move {
                let repo = api_clone.model(model_name);

src/downloader/huggingface.rs:278

• These #[tokio::test] cases hit the real Hugging Face network/API. That makes cargo test (and the GitHub Actions workflow) flaky and slow, and can fail in offline/restricted CI environments. Consider converting them to mocked/unit tests, or gating as explicit integration tests (e.g., #[ignore] + opt-in env var) so the default test suite stays deterministic.

    #[tokio::test]
    async fn test_download_model_invalid() {
        let downloader = HuggingFaceDownloader::new();
        let result = downloader
            .download_model("invalid-model-that-does-not-exist-12345")
            .await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn test_download_real_tiny_model() {
        let downloader = HuggingFaceDownloader::new();
        // Use HF's official tiny test model (only a few KB)
        let result = downloader.download_model("InftyAI/tiny-random-gpt2").await;
        assert!(
            result.is_ok(),
            "Failed to download tiny model: {:?}",
            result
        );

        // Cleanup: remove the downloaded files from PUMA cache
        let cache_dir = file::huggingface_cache_dir().join("models--InftyAI--tiny-random-gpt2");

        if cache_dir.exists() {
            let _ = std::fs::remove_dir_all(&cache_dir);
        }
    }

src/registry/model_registry.rs:195

• remove_model deletes info.cache_path from the registry file without validating it. Since models.json is user-editable/corruptible, this can be abused to delete arbitrary directories. Consider restricting deletions to paths under PUMA’s cache root (e.g., utils::file::cache_dir()), canonicalizing and verifying prefix before calling remove_dir_all, and refusing otherwise.

        if let Some(info) = model_info {
            // Delete cache directory if it exists
            let cache_path = std::path::Path::new(&info.cache_path);
            if cache_path.exists() {
                fs::remove_dir_all(cache_path)?;
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kerthcet]

/lgtm

[kerthcet]

/kind cleanup