mecha10_templates/services/

template_download.rs

//! Template download service
//!
//! Downloads project templates via the public `mecha10-api` downloads proxy
//! (`GET /api/downloads/templates`), never a distribution point directly — same pattern as
//! `mecha10-deploy`'s `BinaryManager`. Templates are versioned and cached locally for offline
//! use. The templates tarball also carries the bundled simulation asset catalog
//! (`models`/`environments`/`tasks`, LAB-2019) - there is no separate simulation-assets
//! download/cache service anymore (the former `packages/nodes/simulator`'s
//! `SimulationAssetManager` was removed).

use anyhow::{Context, Result};
use flate2::read::GzDecoder;
use mecha10_cli_core::paths::urls::mecha10_api_base_url;
use mecha10_cli_core::paths::user::templates_dir;
use mecha10_cli_core::utils::build_client;
use serde::Deserialize;
use std::fs;
use std::path::{Path, PathBuf};
use tar::Archive;

/// Mirrors `mecha10-api`'s `catalog::downloads::types::VersionResponse`.
#[derive(Debug, Deserialize)]
struct VersionResponse {
    version: String,
}

/// Version string used for templates installed locally via
/// `scripts/release/index.py --component templates --install` (see
/// `scripts/release/install.py::install_templates`).
///
/// Never a valid published semver, so a `--install`ed build can never collide
/// with (or be silently overwritten by) a real release, and `resolve_version`
/// can detect it purely from the filesystem without hitting the network.
pub const DEV_VERSION: &str = "dev";

/// Service for downloading and caching project templates via `mecha10-api`
pub struct TemplateDownloadService {
    /// Cache directory for templates (~/.mecha10/templates/)
    cache_dir: PathBuf,
}

impl TemplateDownloadService {
    /// Create a new TemplateDownloadService with default cache directory
    pub fn new() -> Self {
        Self {
            cache_dir: templates_dir(),
        }
    }

    /// Create a TemplateDownloadService with a custom cache directory (for testing)
    #[allow(dead_code)]
    pub fn with_cache_dir(cache_dir: PathBuf) -> Self {
        Self { cache_dir }
    }

    /// Get the latest template version via `mecha10-api`
    ///
    /// Calls `GET /api/downloads/templates/version`, which resolves the version
    /// without downloading the tarball.
    pub async fn get_latest_version(&self) -> Result<String> {
        let url = format!("{}/downloads/templates/version", mecha10_api_base_url());

        let client = build_client()?;
        let response = client
            .get(&url)
            .send()
            .await
            .context("Failed to fetch latest templates version from mecha10-api")?;

        if !response.status().is_success() {
            anyhow::bail!(
                "Failed to get latest templates version: HTTP {}\nURL: {}",
                response.status(),
                url
            );
        }

        let parsed: VersionResponse = response
            .json()
            .await
            .context("Failed to parse version response from mecha10-api")?;
        Ok(parsed.version)
    }

    /// Get the path to cached templates for a specific version
    pub fn get_cached_path(&self, version: &str) -> PathBuf {
        self.cache_dir.join(format!("v{}", version))
    }

    /// Check if templates for a specific version are cached
    pub fn is_cached(&self, version: &str) -> bool {
        let cache_path = self.get_cached_path(version);
        cache_path.exists() && cache_path.join("templates").exists()
    }

    /// Resolve which template version to use.
    ///
    /// Prefers a locally `--install`ed dev build ([`DEV_VERSION`]) if one is
    /// cached, so `scripts/release/index.py --component templates --install`
    /// lets you iterate on template changes with `mecha10 init` fully
    /// offline - no publish, no `MECHA10_API_URL` pointed at a local
    /// mecha10-api. Falls back to [`Self::get_latest_version`] (a network
    /// call) when no dev build is installed.
    pub async fn resolve_version(&self) -> Result<String> {
        if self.is_cached(DEV_VERSION) {
            tracing::info!("Using locally installed dev templates (v{DEV_VERSION}) - run `mecha10 init` after a real publish to go back to the latest published templates");
            return Ok(DEV_VERSION.to_string());
        }

        self.get_latest_version().await
    }

    /// Ensure templates are available for a specific version
    ///
    /// Downloads and caches templates if not already present.
    /// Returns the path to the templates directory.
    pub async fn ensure_templates(&self, version: &str) -> Result<PathBuf> {
        let cache_path = self.get_cached_path(version);
        let templates_path = cache_path.join("templates");

        if templates_path.exists() {
            tracing::debug!("Using cached templates v{}", version);
            return Ok(templates_path);
        }

        tracing::info!("Downloading templates v{}...", version);
        self.download_templates(version, &cache_path).await?;

        Ok(templates_path)
    }

    /// Download templates for a specific version via `mecha10-api`
    async fn download_templates(&self, version: &str, cache_path: &Path) -> Result<()> {
        let url = format!("{}/downloads/templates?version={}", mecha10_api_base_url(), version);

        let client = build_client()?;

        let response = client
            .get(&url)
            .send()
            .await
            .context("Failed to connect to mecha10-api for templates")?;

        if !response.status().is_success() {
            anyhow::bail!("Failed to download templates: HTTP {}\nURL: {}", response.status(), url);
        }

        let bytes = response.bytes().await.context("Failed to read template archive")?;

        fs::create_dir_all(cache_path).context("Failed to create template cache directory")?;

        let decoder = GzDecoder::new(&bytes[..]);
        let mut archive = Archive::new(decoder);

        archive
            .unpack(cache_path)
            .context("Failed to extract template archive")?;

        tracing::info!("Templates v{} cached at {:?}", version, cache_path);

        Ok(())
    }

    /// Resolve `relative_path` against the cached `templates/` directory for `version`.
    ///
    /// Every method below needs this same `<cache_dir>/v<version>/templates/<relative_path>`
    /// join; centralized so cargo-dupes' `read_template`/`read_template_bytes` finding
    /// (LAB-2749) can't recur as more `templates/`-relative accessors are added here.
    fn resolve_template_path(&self, version: &str, relative_path: &str) -> PathBuf {
        self.get_cached_path(version).join("templates").join(relative_path)
    }

    /// Read a template file from the cached templates as UTF-8 text.
    ///
    /// Built on [`Self::read_template_bytes`] rather than a parallel
    /// `resolve_template_path` + `fs::read_to_string` body: the two were byte-for-byte
    /// identical in shape (cargo-dupes exact-duplicate group, LAB-2490) once
    /// `resolve_template_path` was factored out, since the only real difference is
    /// text-vs-bytes decoding, which layering on top of the bytes variant expresses
    /// directly instead of duplicating the read.
    #[allow(dead_code)]
    pub fn read_template(&self, version: &str, relative_path: &str) -> Result<String> {
        let bytes = self.read_template_bytes(version, relative_path)?;

        String::from_utf8(bytes).with_context(|| {
            format!(
                "Template is not valid UTF-8: {:?}",
                self.resolve_template_path(version, relative_path)
            )
        })
    }

    /// Read a binary template file from the cached templates
    #[allow(dead_code)]
    pub fn read_template_bytes(&self, version: &str, relative_path: &str) -> Result<Vec<u8>> {
        let file_path = self.resolve_template_path(version, relative_path);

        fs::read(&file_path).with_context(|| format!("Failed to read template: {:?}", file_path))
    }

    /// List all files in a template directory
    #[allow(dead_code)]
    pub fn list_template_dir(&self, version: &str, relative_path: &str) -> Result<Vec<PathBuf>> {
        let dir_path = self.resolve_template_path(version, relative_path);

        if !dir_path.exists() {
            return Ok(Vec::new());
        }

        let mut files = Vec::new();
        for entry in fs::read_dir(&dir_path)? {
            let entry = entry?;
            files.push(entry.path());
        }

        Ok(files)
    }

    /// Copy a template directory to the project
    pub fn copy_template_dir(&self, version: &str, template_relative_path: &str, dest_path: &Path) -> Result<()> {
        let src_path = self.resolve_template_path(version, template_relative_path);

        if !src_path.exists() {
            tracing::debug!("Template directory not found: {:?}", src_path);
            return Ok(());
        }

        copy_dir_recursive(&src_path, dest_path)?;

        Ok(())
    }

    /// Copy a single template file to the project
    pub fn copy_template_file(&self, version: &str, template_relative_path: &str, dest_path: &Path) -> Result<()> {
        let src_path = self.resolve_template_path(version, template_relative_path);

        if !src_path.exists() {
            tracing::debug!("Template file not found: {:?}", src_path);
            return Ok(());
        }

        if let Some(parent) = dest_path.parent() {
            fs::create_dir_all(parent)?;
        }

        fs::copy(&src_path, dest_path)?;

        Ok(())
    }
}

impl Default for TemplateDownloadService {
    fn default() -> Self {
        Self::new()
    }
}

/// Recursively copy a directory
fn copy_dir_recursive(src: &Path, dst: &Path) -> Result<()> {
    fs::create_dir_all(dst)?;

    for entry in fs::read_dir(src)? {
        let entry = entry?;
        let src_path = entry.path();
        let dst_path = dst.join(entry.file_name());

        if src_path.is_dir() {
            copy_dir_recursive(&src_path, &dst_path)?;
        } else {
            fs::copy(&src_path, &dst_path)?;
        }
    }

    Ok(())
}

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

    #[test]
    fn test_cache_path() {
        let service = TemplateDownloadService::with_cache_dir(PathBuf::from("/tmp/test"));
        assert_eq!(service.get_cached_path("0.1.14"), PathBuf::from("/tmp/test/v0.1.14"));
    }

    #[test]
    fn default_cache_dir_matches_paths_user_templates_dir() {
        let service = TemplateDownloadService::new();
        assert_eq!(service.cache_dir, templates_dir());
    }

    #[test]
    fn dev_version_path_matches_install_py_layout() {
        let service = TemplateDownloadService::with_cache_dir(PathBuf::from("/tmp/test"));
        assert_eq!(service.get_cached_path(DEV_VERSION), PathBuf::from("/tmp/test/vdev"));
    }

    #[tokio::test]
    async fn resolve_version_prefers_locally_installed_dev_build_without_network() {
        let tmp = tempfile::tempdir().unwrap();
        let dev_templates_dir = tmp.path().join(format!("v{DEV_VERSION}")).join("templates");
        fs::create_dir_all(&dev_templates_dir).unwrap();

        let service = TemplateDownloadService::with_cache_dir(tmp.path().to_path_buf());
        let version = service.resolve_version().await.unwrap();
        assert_eq!(version, DEV_VERSION);
    }
}