flow_application/

template_hub.rs

//! Template Hub - a browsable catalog of downloadable flow templates.
//!
//! The Model Hub ([`crate::hub`]) browses + downloads AI-model artifacts; the
//! Template Hub is its analog for **flow templates**. The catalog is a
//! checked-in JSON file ([`template_catalog.json`]) shaped as an API-response
//! envelope `{ "apiVersion": "1", "templates": [ … ] }` - a proof-of-concept of
//! the future cloud template registry, exactly mirroring the Model Hub's
//! `hub_catalog.json`. Each entry embeds the full `FlowGraph`; "downloading" an
//! entry copies that graph into the local template store
//! (`~/.flow-studio/templates/`), after which it shows up in the top-bar
//! **Load** modal like any other saved template.
//!
//! Editing the JSON is all it takes to add/remove templates - no Rust changes,
//! and no product-specific templates hardcoded in the codebase.

use std::sync::OnceLock;

use chrono::Utc;
use flow_domain::graph::FlowGraph;
use flow_storage::{Store, TemplateMembershipRow};
use serde::{Deserialize, Serialize};

use crate::templates::{self, TemplateError, TemplateRecord, TemplateSource};

const FALLBACK_VERSION: &str = "0.0.0";

const CATALOG_JSON: &str = include_str!("../../../mocks/template_catalog.json");

/// One catalog entry as stored in `template_catalog.json`: browse metadata plus
/// the embedded graph used on install.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
struct TemplateCatalogEntry {
    slug: String,
    name: String,
    #[serde(default)]
    description: String,
    #[serde(default)]
    tags: Vec<String>,
    /// Catalog entry version (semantic-ish, dot-separated u32 triple).
    /// Missing in older catalog snapshots → fall back to `"0.0.0"` so the
    /// comparator treats them as "always older than the embedded one".
    #[serde(default = "default_version")]
    version: String,
    graph: FlowGraph,
}

fn default_version() -> String {
    FALLBACK_VERSION.to_string()
}

/// API-response envelope: `{ "apiVersion": "1", "templates": [ … ] }`. Mirrors
/// the shape the future registry service will serve.
#[derive(Deserialize)]
struct CatalogEnvelope {
    #[serde(default)]
    api_version: String,
    templates: Vec<TemplateCatalogEntry>,
}

/// Browse metadata for a hub template (no embedded graph - that's resolved
/// on install). Serialized to the frontend with camelCase keys.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TemplateHubEntry {
    pub slug: String,
    pub name: String,
    pub description: String,
    pub tags: Vec<String>,
    pub version: String,
    pub node_count: usize,
    pub edge_count: usize,
}

/// Where a hub template currently lives in the local store, plus what
/// version was last installed. `None` when nothing matches.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct HubInstalledStatus {
    pub template_slug: String,
    pub collection_slug: String,
    pub installed_version: String,
}

/// One hub entry + install status. The `update_available` flag is
/// pre-computed server-side so the frontend doesn't need to parse versions.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TemplateHubEntryWithStatus {
    pub slug: String,
    pub name: String,
    pub description: String,
    pub tags: Vec<String>,
    pub version: String,
    pub node_count: usize,
    pub edge_count: usize,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub installed_as: Option<HubInstalledStatus>,
    pub update_available: bool,
}

/// Parse the embedded catalog once. A malformed JSON file panics at first use
/// (loud, deterministic - it ships in the binary, so it's a build-time error in
/// spirit, exactly like `hub_catalog.json`).
fn entries() -> &'static [TemplateCatalogEntry] {
    static CATALOG: OnceLock<Vec<TemplateCatalogEntry>> = OnceLock::new();
    CATALOG
        .get_or_init(|| {
            let env: CatalogEnvelope =
                serde_json::from_str(CATALOG_JSON).expect("template_catalog.json is malformed");
            let _ = env.api_version;
            env.templates
        })
        .as_slice()
}

/// Browse list: catalog entries mapped to display metadata (+ node/edge
/// counts from the embedded graph).
pub fn catalog() -> Vec<TemplateHubEntry> {
    entries().iter().map(entry_to_browse).collect()
}

fn entry_to_browse(e: &TemplateCatalogEntry) -> TemplateHubEntry {
    TemplateHubEntry {
        slug: e.slug.clone(),
        name: e.name.clone(),
        description: e.description.clone(),
        tags: e.tags.clone(),
        version: e.version.clone(),
        node_count: e.graph.nodes.len(),
        edge_count: e.graph.edges.len(),
    }
}

/// Annotate the catalog with per-entry install status. A template counts
/// as installed when either:
/// - a `template_membership` row exists whose `hub_source_slug` matches
///   the catalog slug, OR
/// - the canonical file `<templates_dir>/<slug>.flow.json` is on disk.
///
/// The on-disk check covers orphan files (DB reset, schema migration,
/// row hand-deleted) so the Hub row's button flips to Update / Installed
/// without the user having to click Add first and rely on the heal
/// path in [`add_to_collection`].
pub fn catalog_with_status(
    store: &Store,
    templates_dir: &std::path::Path,
) -> Result<Vec<TemplateHubEntryWithStatus>, TemplateError> {
    let memberships = store.list_template_memberships()?;
    let mut by_hub: std::collections::HashMap<String, &flow_storage::TemplateMembershipRow> =
        std::collections::HashMap::new();
    for row in &memberships {
        if let Some(hub_slug) = row.hub_source_slug.as_deref() {
            by_hub.insert(hub_slug.to_string(), row);
        }
    }
    let mut out = Vec::with_capacity(entries().len());
    for e in entries() {
        let installed = by_hub
            .get(&e.slug)
            .map(|row| HubInstalledStatus {
                template_slug: row.template_slug.clone(),
                collection_slug: row.collection_slug.clone(),
                installed_version: row
                    .hub_version
                    .clone()
                    .unwrap_or_else(|| FALLBACK_VERSION.into()),
            })
            .or_else(|| {
                // Orphan file: present on disk, no row points at it.
                let file_path = templates_dir.join(format!("{}.flow.json", e.slug));
                if file_path.exists() {
                    Some(HubInstalledStatus {
                        template_slug: e.slug.clone(),
                        collection_slug: crate::templates::DEFAULT_COLLECTION_SLUG.into(),
                        installed_version: FALLBACK_VERSION.into(),
                    })
                } else {
                    None
                }
            });
        let update_available = installed
            .as_ref()
            .map(|status| {
                compare_versions(&e.version, &status.installed_version)
                    == std::cmp::Ordering::Greater
            })
            .unwrap_or(false);
        out.push(TemplateHubEntryWithStatus {
            slug: e.slug.clone(),
            name: e.name.clone(),
            description: e.description.clone(),
            tags: e.tags.clone(),
            version: e.version.clone(),
            node_count: e.graph.nodes.len(),
            edge_count: e.graph.edges.len(),
            installed_as: installed,
            update_available,
        });
    }
    Ok(out)
}

/// Install a catalog entry into a user-chosen collection.
///
/// - When neither the file nor a membership row exists, this is a normal
///   first install: write the canonical JSON, write the sibling DSL,
///   upsert the membership row.
/// - When the file exists AND a membership row exists, refuse - the
///   caller must explicitly go through [`update_installed`] to overwrite.
/// - When the file exists but no row references it (the DB was reset,
///   migrated, or the row was hand-deleted), heal silently: write the
///   missing row pointing at the on-disk file without overwriting any
///   user edits. The user clicked Add and now the install is tracked,
///   which is what they wanted.
pub fn add_to_collection(
    templates_dir: &std::path::Path,
    store: &Store,
    hub_slug: &str,
    collection_slug: &str,
) -> Result<TemplateRecord, TemplateError> {
    let entry = entries()
        .iter()
        .find(|e| e.slug == hub_slug)
        .ok_or_else(|| TemplateError::NotFound(hub_slug.to_string()))?;
    let file_path = templates_dir.join(format!("{}.flow.json", entry.slug));

    if file_path.exists() {
        let already_tracked = store
            .list_template_memberships()?
            .into_iter()
            .any(|r| r.hub_source_slug.as_deref() == Some(entry.slug.as_str()));
        if already_tracked {
            return Err(TemplateError::Store(
                flow_storage::StoreError::Refused(format!(
                    "template `{}` is already installed; use Update to overwrite",
                    entry.slug
                )),
            ));
        }
        return heal_membership(templates_dir, store, entry, collection_slug);
    }

    let source = TemplateSource {
        hub_slug: entry.slug.clone(),
        version: entry.version.clone(),
        installed_at: Utc::now(),
    };
    templates::save_with_slug(
        templates_dir,
        store,
        &entry.slug,
        &entry.name,
        &entry.graph,
        collection_slug,
        Some(source),
    )
}

/// Reconcile an orphan on-disk template (file exists, no membership row)
/// by writing the row. The file is NOT overwritten - local edits, if any,
/// are preserved.
fn heal_membership(
    templates_dir: &std::path::Path,
    store: &Store,
    entry: &TemplateCatalogEntry,
    collection_slug: &str,
) -> Result<TemplateRecord, TemplateError> {
    let installed_at = Utc::now();
    store.upsert_template_membership(&TemplateMembershipRow {
        template_slug: entry.slug.clone(),
        collection_slug: collection_slug.into(),
        hub_source_slug: Some(entry.slug.clone()),
        hub_version: Some(entry.version.clone()),
        installed_at: Some(installed_at),
    })?;
    let graph = templates::load(templates_dir, &entry.slug)?;
    let dsl_path = templates_dir.join(format!("{}.flow", entry.slug));
    Ok(TemplateRecord {
        slug: entry.slug.clone(),
        collection_slug: collection_slug.to_string(),
        name: entry.name.clone(),
        node_count: graph.nodes.len(),
        edge_count: graph.edges.len(),
        updated_at: installed_at,
        has_dsl: dsl_path.exists(),
        source: Some(TemplateSource {
            hub_slug: entry.slug.clone(),
            version: entry.version.clone(),
            installed_at,
        }),
    })
}

/// Overwrite an installed hub template in place with the catalog's current
/// graph, bumping `hub_version`. When `force` is false and the user has
/// edited the file (mtime > installed_at), returns a `Refused` error so the
/// frontend can prompt the user before clobbering local edits.
pub fn update_installed(
    templates_dir: &std::path::Path,
    store: &Store,
    hub_slug: &str,
    force: bool,
) -> Result<TemplateRecord, TemplateError> {
    let entry = entries()
        .iter()
        .find(|e| e.slug == hub_slug)
        .ok_or_else(|| TemplateError::NotFound(hub_slug.to_string()))?;

    // Locate the existing membership row by hub slug (small scan; the table
    // never grows past a few dozen rows).
    let existing_row = store
        .list_template_memberships()?
        .into_iter()
        .find(|r| r.hub_source_slug.as_deref() == Some(hub_slug))
        .ok_or_else(|| TemplateError::NotFound(format!("hub template `{hub_slug}` not installed")))?;

    if !force {
        let file_path = templates_dir.join(format!("{}.flow.json", existing_row.template_slug));
        if let (Ok(meta), Some(installed_at)) =
            (std::fs::metadata(&file_path), existing_row.installed_at)
        {
            if let Ok(modified) = meta.modified() {
                let modified_dt: chrono::DateTime<Utc> = modified.into();
                if modified_dt > installed_at {
                    return Err(TemplateError::Store(flow_storage::StoreError::Refused(
                        format!(
                            "template `{}` has local edits since install; pass force=true to overwrite",
                            existing_row.template_slug
                        ),
                    )));
                }
            }
        }
    }

    let source = TemplateSource {
        hub_slug: entry.slug.clone(),
        version: entry.version.clone(),
        installed_at: Utc::now(),
    };
    templates::save_with_slug(
        templates_dir,
        store,
        &existing_row.template_slug,
        &entry.name,
        &entry.graph,
        &existing_row.collection_slug,
        Some(source),
    )
}

/// Tuple compare on the parsed dotted-int triple. Non-parseable segments
/// degrade to 0 so a malformed catalog entry still compares (against
/// `0.0.0` it'll come out equal, which is harmless).
fn compare_versions(a: &str, b: &str) -> std::cmp::Ordering {
    let parse = |s: &str| -> (u32, u32, u32) {
        let mut it = s.split('.').map(|p| p.parse::<u32>().unwrap_or(0));
        (it.next().unwrap_or(0), it.next().unwrap_or(0), it.next().unwrap_or(0))
    };
    parse(a).cmp(&parse(b))
}

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

    #[test]
    fn catalog_parses_and_is_well_formed() {
        // The shipped catalog is allowed to be empty - vendor-specific
        // templates ship as Hub catalog data added by operators, not by
        // this crate. The well-formedness check only kicks in when there
        // ARE entries.
        for e in &catalog() {
            assert!(!e.slug.is_empty());
            assert!(!e.name.is_empty());
            assert!(!e.version.is_empty(), "{} has a version", e.slug);
            assert!(e.node_count > 0, "{} has nodes", e.slug);
        }
    }

    fn first_catalog_entry() -> Option<TemplateHubEntry> {
        catalog().into_iter().next()
    }

    #[test]
    fn add_to_collection_writes_a_loadable_local_template() {
        let Some(first) = first_catalog_entry() else {
            // No-op on builds that ship an empty catalog; the tests below
            // exercise behaviour that's only reachable when a hub entry
            // exists.
            return;
        };
        let dir = std::env::temp_dir().join(format!("flow-thub-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(&dir).unwrap();

        let store = flow_storage::Store::open_in_memory().expect("in-memory store");
        templates::ensure_default(&store).expect("ensure_default");
        let rec = add_to_collection(&dir, &store, &first.slug, "default").expect("install");
        assert_eq!(rec.slug, first.slug);
        assert_eq!(rec.collection_slug, "default");
        assert!(rec.source.is_some(), "hub install records its source");
        let graph = templates::load(&dir, &first.slug).expect("loads");
        assert!(!graph.nodes.is_empty());

        assert!(add_to_collection(&dir, &store, "does-not-exist", "default").is_err());

        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn add_to_collection_refuses_when_already_installed() {
        let Some(first) = first_catalog_entry() else { return };
        let dir = std::env::temp_dir().join(format!("flow-thub-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(&dir).unwrap();
        let store = flow_storage::Store::open_in_memory().unwrap();
        templates::ensure_default(&store).unwrap();
        add_to_collection(&dir, &store, &first.slug, "default").unwrap();
        let err =
            add_to_collection(&dir, &store, &first.slug, "default").expect_err("re-add refused");
        assert!(err.to_string().contains("already installed"), "got {err}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn catalog_with_status_marks_installed_for_orphan_files_on_disk() {
        let Some(first) = first_catalog_entry() else { return };
        let dir = std::env::temp_dir().join(format!("flow-thub-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(&dir).unwrap();
        let store = flow_storage::Store::open_in_memory().unwrap();
        templates::ensure_default(&store).unwrap();

        // Install, then drop the row to simulate an orphan-file state.
        add_to_collection(&dir, &store, &first.slug, "default").unwrap();
        store.delete_template_membership(&first.slug).unwrap();

        // No row, but the file is still on disk - catalog_with_status
        // must still report this as installed so the Hub row's button
        // shows Update instead of "Add to collection…".
        let annotated = catalog_with_status(&store, &dir).unwrap();
        let our_row = annotated
            .iter()
            .find(|e| e.slug == first.slug)
            .expect("entry");
        assert!(
            our_row.installed_as.is_some(),
            "orphan file should count as installed"
        );

        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn add_to_collection_heals_orphan_file_when_membership_row_missing() {
        let Some(first) = first_catalog_entry() else { return };
        let dir = std::env::temp_dir().join(format!("flow-thub-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(&dir).unwrap();
        let store = flow_storage::Store::open_in_memory().unwrap();
        templates::ensure_default(&store).unwrap();

        // First install lays down both the file and the row.
        add_to_collection(&dir, &store, &first.slug, "default").unwrap();
        // Simulate the DB being reset / migrated underneath: drop the row
        // but keep the on-disk file (and a deliberate local edit).
        store.delete_template_membership(&first.slug).unwrap();
        let file_path = dir.join(format!("{}.flow.json", first.slug));
        let original_bytes = std::fs::read(&file_path).unwrap();
        std::fs::write(&file_path, &original_bytes).unwrap(); // unchanged bytes - proves we don't touch the file

        // Now Add should heal instead of refusing.
        let rec = add_to_collection(&dir, &store, &first.slug, "default")
            .expect("orphan file heals into a tracked install");
        assert_eq!(rec.slug, first.slug);
        assert!(rec.source.is_some(), "heal sets source provenance");
        // File contents preserved byte-for-byte.
        assert_eq!(std::fs::read(&file_path).unwrap(), original_bytes);
        // Membership row now present.
        let row = store
            .get_template_membership(&first.slug)
            .unwrap()
            .expect("row");
        assert_eq!(row.hub_source_slug.as_deref(), Some(first.slug.as_str()));

        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn catalog_with_status_marks_installed_and_update_available() {
        let Some(first) = first_catalog_entry() else { return };
        let dir = std::env::temp_dir().join(format!("flow-thub-{}", uuid::Uuid::new_v4()));
        std::fs::create_dir_all(&dir).unwrap();
        let store = flow_storage::Store::open_in_memory().unwrap();
        templates::ensure_default(&store).unwrap();
        add_to_collection(&dir, &store, &first.slug, "default").unwrap();

        // Force the installed version to look older so update_available trips.
        let mut row = store
            .get_template_membership(&first.slug)
            .unwrap()
            .expect("row");
        row.hub_version = Some("0.0.1".into());
        store.upsert_template_membership(&row).unwrap();

        let annotated = catalog_with_status(&store, &dir).unwrap();
        let our_row = annotated
            .iter()
            .find(|e| e.slug == first.slug)
            .expect("entry");
        assert!(our_row.installed_as.is_some());
        assert!(
            our_row.update_available,
            "catalog version > 0.0.1 should be update_available"
        );
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn compare_versions_orders_dotted_triples() {
        use std::cmp::Ordering::*;
        assert_eq!(compare_versions("1.0.0", "1.0.0"), Equal);
        assert_eq!(compare_versions("1.0.1", "1.0.0"), Greater);
        assert_eq!(compare_versions("0.9.9", "1.0.0"), Less);
        assert_eq!(compare_versions("2.0.0", "1.99.0"), Greater);
        assert_eq!(compare_versions("0.0.0", "0.0.0"), Equal);
        // Missing segments degrade to 0 - non-parseable still compares.
        assert_eq!(compare_versions("1", "1.0.0"), Equal);
    }
}