mnml_bridge/

install.rs

//! Integration manifest install helpers — sibling-authored
//! self-registration for the rail chip, palette commands, chord
//! bindings, context menu additions, menu-bar entries,
//! statusline segments, settings pages, and OS notification
//! policy. Writes a single TOML file per integration:
//!
//!   `~/.config/mnml/integrations/<id>.toml`
//!
//! mnml picks the file up on startup + on the
//! `integrations.refresh` palette command. Uninstall = delete
//! the file. No IPC required — the fs is the interface.
//!
//! ```no_run
//! use mnml_bridge::install::{
//!     ChipSpec, CommandSpec, IntegrationSpec, install_integration,
//! };
//!
//! install_integration(&IntegrationSpec {
//!     id: "slack".into(),
//!     label: "Slack".into(),
//!     description: Some("Slack browse + post".into()),
//!     version: Some(env!("CARGO_PKG_VERSION").into()),
//!     binary: "mnml-msg-slack".into(),
//!     category: Some("msg".into()),
//!     chip: Some(ChipSpec {
//!         glyph: "\u{F0839}".into(),
//!         fallback: "Sk".into(),
//!         color: "purple".into(),
//!         label: Some("Slack".into()),
//!         enabled: true,
//!         in_palette_bar: false,
//!         badge_key: Some("slack".into()),
//!         ..Default::default()
//!     }),
//!     commands: vec![CommandSpec {
//!         id: "slack.open".into(),
//!         title: "Slack: open".into(),
//!         group: Some("integrations".into()),
//!         keys: vec!["<leader>iS".into()],
//!         run: ":term mnml-msg-slack".into(),
//!     }],
//!     ..Default::default()
//! }).ok();
//! ```

use serde::Serialize;
use std::fs;
use std::io;
use std::path::{Path, PathBuf};

/// Complete integration description written to the manifest
/// file. Only `id`, `label`, and `binary` are required —
/// everything else defaults to sensible empty values.
///
/// 2026-08-01 — the identity strings live here at the top level:
///   * `label` — short display name (chip hover, tree row, picker,
///     detail-pane header). Required. ~20 chars max.
///   * `description` — one-sentence longer form for the detail
///     pane subtitle. ~80 chars.
///
/// The old `name` field was dead code (never rendered); dropped.
/// The old `chip.tooltip` field is folded into top-level `label`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct IntegrationSpec {
    pub id: String,
    pub label: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    pub binary: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub category: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]
    pub chip: Option<ChipSpec>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub commands: Vec<CommandSpec>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub context_menu: Vec<ContextMenuEntry>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub menu_bar: Vec<MenuBarEntry>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub statusline: Option<StatuslineSpec>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub settings: Vec<SettingsPage>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub notifications: Option<NotificationsSpec>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub requires: Option<Requires>,
}

/// Visual + interaction settings for the sibling's chip. Display
/// strings (label, description) live at `IntegrationSpec` top
/// level, not here — the chip is about rendering, not identity.
#[derive(Debug, Clone, Default, Serialize)]
pub struct ChipSpec {
    pub glyph: String,
    pub fallback: String,
    pub color: String,
    pub enabled: bool,
    pub in_palette_bar: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub badge_key: Option<String>,
    /// Path (relative to the sibling repo root, or absolute) to an
    /// SVG file the sibling owns and wants baked into mnml's
    /// runtime symbols font. On [`install_integration`] the file
    /// is copied to `~/.config/mnml/glyphs/<integration-id>.svg`;
    /// mnml discovers it on next startup (or on the
    /// `integrations.refresh` palette command), assigns a stable
    /// codepoint, and — on `integrations.bake_sibling_glyphs` —
    /// bakes the SVG into `~/Library/Fonts/MnmlSymbols.ttf` so the
    /// chip renders the branded glyph.
    ///
    /// Leaving both this and `glyph_codepoint` unset means "use
    /// whatever `glyph` says" — the pre-SDK behaviour where
    /// siblings pick a Nerd Font codepoint by hand.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub glyph_svg: Option<PathBuf>,
    /// Optional explicit codepoint the sibling wants (uppercase
    /// hex, no `U+` prefix — e.g. `"F1C05"`). When set, mnml uses
    /// this codepoint verbatim for the sibling's SVG bake instead
    /// of auto-assigning one from the sibling PUA range
    /// (`U+F1C00–U+F1CFF`). Useful for migration cases where a
    /// sibling wants to keep the codepoint mnml core baked before
    /// this SDK feature landed. Trusted — no range validation
    /// beyond "parses as u32"; the manifest author is expected to
    /// stay inside mnml's PUA layout documented in
    /// `src/icon_catalog.rs`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub glyph_codepoint: Option<String>,
}

#[derive(Debug, Clone, Serialize)]
pub struct CommandSpec {
    pub id: String,
    pub title: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub group: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub keys: Vec<String>,
    pub run: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct ContextMenuEntry {
    /// `tree.file` | `tree.dir` | `tab` | `agent.row` | `pane`.
    pub target: String,
    pub title: String,
    pub command: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct MenuBarEntry {
    /// Slash-separated path like `"File > Send via Slack"`.
    pub path: String,
    pub command: String,
}

#[derive(Debug, Clone, Serialize)]
pub struct StatuslineSpec {
    /// `"left"` | `"right"`.
    pub side: String,
    pub segment_id: String,
    #[serde(skip_serializing_if = "String::is_empty")]
    pub initial_text: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub initial_color: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub click_command: Option<String>,
    pub priority: u8,
    pub min_width: u16,
    pub max_width: u16,
}

#[derive(Debug, Clone, Serialize)]
pub struct SettingsPage {
    pub section: String,
    pub label: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub help: Option<String>,
}

#[derive(Debug, Clone, Copy, Default, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum OsNotifyPolicy {
    #[default]
    Never,
    ErrorOnly,
    Always,
}

#[derive(Debug, Clone, Serialize)]
pub struct NotificationsSpec {
    pub os_notify_on: OsNotifyPolicy,
    pub os_rate_limit_sec: u64,
}

#[derive(Debug, Clone, Serialize)]
pub struct Requires {
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub env: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub binary: Option<String>,
}

// ── Filesystem operations ─────────────────────────────

/// Serialize `spec` and write to
/// `~/.config/mnml/integrations/<id>.toml`. Creates the parent
/// directory if needed. Overwrites any existing file with the
/// same id. Returns the path written.
///
/// If `spec.chip.glyph_svg` is set, ALSO copies the referenced
/// SVG to `~/.config/mnml/glyphs/<id>.svg` so mnml can discover
/// and bake it. A missing / unreadable SVG is a warning, not a
/// failure — the manifest is the primary contract.
///
/// Fails if `spec.id` contains `/` or `\` (dir traversal
/// protection), or if the manifest fs write itself fails.
pub fn install_integration(spec: &IntegrationSpec) -> io::Result<PathBuf> {
    validate_id(&spec.id)?;
    let dir = user_integration_dir()?;
    fs::create_dir_all(&dir)?;
    let path = dir.join(format!("{}.toml", spec.id));
    let toml = toml_serialize(spec)?;
    fs::write(&path, toml)?;
    // If the chip declares a `glyph_svg`, copy it into
    // ~/.config/mnml/glyphs/<id>.svg so mnml can discover + bake
    // it. Copy is best-effort — a missing / unreadable source SVG
    // logs to stderr but does NOT fail the install (the manifest
    // itself is the primary contract; a broken SVG just means the
    // chip renders whatever the plain `glyph` string says, which
    // is the pre-SDK fallback).
    if let Some(chip) = &spec.chip
        && let Some(svg_src) = &chip.glyph_svg
    {
        match copy_glyph_svg(&spec.id, svg_src) {
            Ok(dest) => eprintln!("mnml-bridge: copied glyph SVG → {}", dest.display()),
            Err(e) => eprintln!(
                "mnml-bridge: WARN failed to copy glyph SVG {}: {e}",
                svg_src.display()
            ),
        }
    }
    Ok(path)
}

/// Copy `src` (relative to CWD or absolute) to
/// `~/.config/mnml/glyphs/<id>.svg`. Creates the parent dir if
/// missing. Overwrites any existing file (idempotent).
fn copy_glyph_svg(id: &str, src: &Path) -> io::Result<PathBuf> {
    validate_id(id)?;
    if !src.exists() {
        return Err(io::Error::new(
            io::ErrorKind::NotFound,
            format!("glyph SVG not found: {}", src.display()),
        ));
    }
    let dir = sibling_glyphs_dir()?;
    fs::create_dir_all(&dir)?;
    let dest = dir.join(format!("{id}.svg"));
    fs::copy(src, &dest)?;
    Ok(dest)
}

/// User-config dir for sibling-shipped glyph SVGs — the sibling
/// side of the sibling-icons SDK. mnml scans this dir at startup +
/// on `integrations.refresh`, assigns each SVG a stable codepoint
/// in the `U+F1C00–U+F1CFF` range, and (on
/// `integrations.bake_sibling_glyphs`) bakes them into the
/// runtime symbols font. Sibling code doesn't usually need to
/// touch this dir — [`install_integration`] copies the SVG here
/// automatically when `ChipSpec::glyph_svg` is set.
pub fn sibling_glyphs_dir() -> io::Result<PathBuf> {
    let home = std::env::var_os("HOME")
        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "$HOME is not set"))?;
    Ok(PathBuf::from(home)
        .join(".config")
        .join("mnml")
        .join("glyphs"))
}

/// Delete the manifest at `~/.config/mnml/integrations/<id>.toml`.
/// Returns `Ok(true)` if the file was removed, `Ok(false)` if
/// the file didn't exist (already uninstalled). Fails on other
/// fs errors.
pub fn uninstall_integration(id: &str) -> io::Result<bool> {
    validate_id(id)?;
    let path = integration_manifest_path(id)?;
    // Also drop the sibling-owned glyph SVG if one exists. Best
    // effort — a NotFound isn't an error (the sibling may not have
    // shipped an SVG at all). The codepoint assignment persists in
    // `~/.config/mnml/glyphs/assignments.toml` so re-installing
    // the sibling later gets the same codepoint back.
    if let Ok(glyph_dir) = sibling_glyphs_dir() {
        let svg = glyph_dir.join(format!("{id}.svg"));
        match fs::remove_file(&svg) {
            Ok(()) | Err(_) => {}
        }
    }
    match fs::remove_file(&path) {
        Ok(()) => Ok(true),
        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(false),
        Err(e) => Err(e),
    }
}

/// List installed integrations by id — reads the manifest
/// directory + strips the `.toml` suffix. Returns an empty vec
/// if the dir doesn't exist.
pub fn list_installed_integrations() -> io::Result<Vec<String>> {
    let dir = user_integration_dir()?;
    let entries = match fs::read_dir(&dir) {
        Ok(e) => e,
        Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(e) => return Err(e),
    };
    let mut out: Vec<String> = Vec::new();
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name) = name.to_str() else { continue };
        if let Some(id) = name.strip_suffix(".toml")
            && !id.is_empty()
        {
            out.push(id.to_string());
        }
    }
    out.sort();
    Ok(out)
}

/// Path to a specific integration's manifest file. Doesn't check
/// whether the file exists.
pub fn integration_manifest_path(id: &str) -> io::Result<PathBuf> {
    validate_id(id)?;
    Ok(user_integration_dir()?.join(format!("{id}.toml")))
}

fn user_integration_dir() -> io::Result<PathBuf> {
    let home = std::env::var_os("HOME")
        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "$HOME is not set"))?;
    Ok(PathBuf::from(home)
        .join(".config")
        .join("mnml")
        .join("integrations"))
}

fn validate_id(id: &str) -> io::Result<()> {
    if id.is_empty() {
        return Err(io::Error::new(io::ErrorKind::InvalidInput, "id is empty"));
    }
    if id.contains(['/', '\\', '\0']) {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!("id contains path characters: {id}"),
        ));
    }
    Ok(())
}

fn toml_serialize<T: Serialize>(v: &T) -> io::Result<String> {
    // Use serde_json → toml conversion since we don't ship the
    // toml crate as a dep (keeps mnml-bridge's dep tree tight).
    // Instead: format the manifest by hand for the common shape.
    // For fidelity, we use serde_json and let the reader (mnml)
    // parse the TOML directly. But since we're WRITING TOML, we
    // need actual TOML serialization.
    //
    // The simplest path: use serde_json to reflect the struct,
    // then hand-convert to TOML. Given the flat + list shape of
    // IntegrationSpec, this is straightforward.
    let json = serde_json::to_value(v)
        .map_err(|e| io::Error::new(io::ErrorKind::InvalidData, format!("serialize: {e}")))?;
    Ok(json_to_toml(&json))
}

/// Best-effort JSON → TOML for the IntegrationSpec shape.
/// Handles top-level scalar fields + nested tables +
/// arrays-of-tables. Not a general JSON→TOML converter — but
/// sufficient for the shapes this SDK emits.
fn json_to_toml(v: &serde_json::Value) -> String {
    let mut out = String::new();
    let Some(map) = v.as_object() else {
        return out;
    };
    // Emit top-level scalars first.
    for (k, val) in map {
        if val.is_object() || val.is_array() {
            continue;
        }
        push_kv(&mut out, k, val);
    }
    // Then arrays-of-tables and tables.
    for (k, val) in map {
        match val {
            serde_json::Value::Object(_) => {
                out.push_str(&format!("\n[{k}]\n"));
                for (inner_k, inner_v) in val.as_object().unwrap() {
                    if inner_v.is_object() || inner_v.is_array() {
                        continue;
                    }
                    push_kv(&mut out, inner_k, inner_v);
                }
            }
            serde_json::Value::Array(arr) => {
                for item in arr {
                    if let Some(obj) = item.as_object() {
                        out.push_str(&format!("\n[[{k}]]\n"));
                        for (inner_k, inner_v) in obj {
                            push_kv(&mut out, inner_k, inner_v);
                        }
                    }
                }
            }
            _ => {}
        }
    }
    out
}

fn push_kv(out: &mut String, k: &str, v: &serde_json::Value) {
    match v {
        serde_json::Value::String(s) => {
            out.push_str(&format!("{k} = {}\n", toml_str(s)));
        }
        serde_json::Value::Number(n) => {
            out.push_str(&format!("{k} = {n}\n"));
        }
        serde_json::Value::Bool(b) => {
            out.push_str(&format!("{k} = {b}\n"));
        }
        serde_json::Value::Array(arr) => {
            let items: Vec<String> = arr
                .iter()
                .filter_map(|x| x.as_str().map(toml_str))
                .collect();
            out.push_str(&format!("{k} = [{}]\n", items.join(", ")));
        }
        _ => {}
    }
}

fn toml_str(s: &str) -> String {
    // Basic TOML string escape — quote + escape backslash + quote.
    let escaped = s.replace('\\', "\\\\").replace('"', "\\\"");
    format!("\"{escaped}\"")
}

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

    // HOME-mutating tests share a single tempdir path. Rust runs
    // tests in the same process on multiple threads by default, and
    // set_var("HOME", …) leaks across threads — without a mutex,
    // one test's tempdir can shadow another mid-run. Serialize
    // every HOME-touching test through this lock.
    fn home_lock() -> &'static std::sync::Mutex<()> {
        static LOCK: std::sync::OnceLock<std::sync::Mutex<()>> = std::sync::OnceLock::new();
        LOCK.get_or_init(|| std::sync::Mutex::new(()))
    }

    #[test]
    fn validate_id_rejects_dangerous_chars() {
        assert!(validate_id("").is_err());
        assert!(validate_id("../foo").is_err());
        assert!(validate_id("a/b").is_err());
        assert!(validate_id("a\\b").is_err());
        assert!(validate_id("valid_id-123").is_ok());
    }

    #[test]
    fn serializes_minimal_spec_to_toml() {
        let spec = IntegrationSpec {
            id: "slack".into(),
            label: "Slack".into(),
            binary: "mnml-msg-slack".into(),
            ..Default::default()
        };
        let toml = toml_serialize(&spec).unwrap();
        assert!(toml.contains("id = \"slack\""));
        assert!(toml.contains("name = \"Slack\""));
        assert!(toml.contains("binary = \"mnml-msg-slack\""));
    }

    #[test]
    fn serializes_full_spec_with_chip_and_commands() {
        let spec = IntegrationSpec {
            id: "slack".into(),
            label: "Slack".into(),
            binary: "mnml-msg-slack".into(),
            chip: Some(ChipSpec {
                glyph: "S".into(),
                fallback: "Sk".into(),
                color: "purple".into(),
                enabled: true,
                in_palette_bar: false,
                badge_key: None,
                glyph_svg: None,
                glyph_codepoint: None,
            }),
            commands: vec![CommandSpec {
                id: "slack.open".into(),
                title: "Slack: open".into(),
                group: Some("integrations".into()),
                keys: vec!["<leader>iS".into()],
                run: ":term mnml-msg-slack".into(),
            }],
            ..Default::default()
        };
        let toml = toml_serialize(&spec).unwrap();
        assert!(toml.contains("[chip]"));
        assert!(toml.contains("glyph = \"S\""));
        assert!(toml.contains("[[commands]]"));
        assert!(toml.contains("id = \"slack.open\""));
        assert!(toml.contains("keys = [\"<leader>iS\"]"));
    }

    #[test]
    fn glyph_svg_and_codepoint_serialize_when_set() {
        let spec = IntegrationSpec {
            id: "amplify".into(),
            label: "Amplify".into(),
            binary: "mnml-aws-amplify".into(),
            chip: Some(ChipSpec {
                glyph: "\u{F1B00}".into(),
                fallback: "Am".into(),
                color: "purple".into(),
                enabled: true,
                in_palette_bar: false,
                badge_key: None,
                glyph_svg: Some(PathBuf::from("assets/icons/amplify.svg")),
                glyph_codepoint: Some("F1B00".into()),
            }),
            ..Default::default()
        };
        let toml = toml_serialize(&spec).unwrap();
        assert!(toml.contains("glyph_svg = \"assets/icons/amplify.svg\""));
        assert!(toml.contains("glyph_codepoint = \"F1B00\""));
    }

    #[test]
    fn install_copies_glyph_svg_into_glyphs_dir() {
        let _lk = home_lock().lock().unwrap();
        let tmp = tempfile::tempdir().unwrap();
        unsafe { std::env::set_var("HOME", tmp.path()) };

        // Stage a fake SVG the sibling would ship.
        let src_svg = tmp.path().join("assets/icons/amplify.svg");
        fs::create_dir_all(src_svg.parent().unwrap()).unwrap();
        fs::write(&src_svg, b"<svg/>").unwrap();

        let spec = IntegrationSpec {
            id: "amplify".into(),
            label: "Amplify".into(),
            binary: "mnml-aws-amplify".into(),
            chip: Some(ChipSpec {
                glyph: "A".into(),
                fallback: "Am".into(),
                color: "purple".into(),
                enabled: true,
                in_palette_bar: false,
                badge_key: None,
                glyph_svg: Some(src_svg.clone()),
                glyph_codepoint: Some("F1B00".into()),
            }),
            ..Default::default()
        };
        install_integration(&spec).unwrap();

        let dest = sibling_glyphs_dir().unwrap().join("amplify.svg");
        assert!(dest.exists(), "glyph SVG should be copied to {dest:?}");
        assert_eq!(fs::read(&dest).unwrap(), b"<svg/>");

        // Manifest also mirrors the fields back so mnml can read them.
        let manifest = fs::read_to_string(integration_manifest_path("amplify").unwrap()).unwrap();
        assert!(manifest.contains("glyph_codepoint = \"F1B00\""));
        assert!(manifest.contains("glyph_svg ="));

        // Uninstall removes the SVG copy alongside the manifest.
        uninstall_integration("amplify").unwrap();
        assert!(!dest.exists(), "glyph SVG should be removed on uninstall");
    }

    #[test]
    fn install_survives_missing_glyph_svg_source() {
        let _lk = home_lock().lock().unwrap();
        let tmp = tempfile::tempdir().unwrap();
        unsafe { std::env::set_var("HOME", tmp.path()) };

        let spec = IntegrationSpec {
            id: "broken".into(),
            label: "Broken".into(),
            binary: "mnml-broken".into(),
            chip: Some(ChipSpec {
                glyph: "B".into(),
                fallback: "Br".into(),
                color: "red".into(),
                enabled: true,
                in_palette_bar: false,
                badge_key: None,
                glyph_svg: Some(PathBuf::from("/nonexistent/path/to/nothing.svg")),
                glyph_codepoint: None,
            }),
            ..Default::default()
        };
        // A missing SVG is a warning, NOT a failure — the manifest
        // still gets written so `--install` succeeds even when the
        // sibling packager forgot to bundle the SVG.
        install_integration(&spec).unwrap();
        let manifest = integration_manifest_path("broken").unwrap();
        assert!(manifest.exists());
    }

    #[test]
    fn install_and_uninstall_round_trip() {
        // Redirect HOME to a tempdir so we don't scribble in the
        // real user config.
        let _lk = home_lock().lock().unwrap();
        let tmp = tempfile::tempdir().unwrap();
        unsafe { std::env::set_var("HOME", tmp.path()) };

        let spec = IntegrationSpec {
            id: "roundtrip".into(),
            label: "Round Trip".into(),
            binary: "mnml-rt".into(),
            ..Default::default()
        };
        let p = install_integration(&spec).unwrap();
        assert!(p.exists());
        assert_eq!(p.file_name().unwrap(), "roundtrip.toml");

        let ids = list_installed_integrations().unwrap();
        assert!(ids.contains(&"roundtrip".to_string()));

        let removed = uninstall_integration("roundtrip").unwrap();
        assert!(removed);
        assert!(!p.exists());

        // Second uninstall is a no-op (already gone).
        let removed2 = uninstall_integration("roundtrip").unwrap();
        assert!(!removed2);
    }
}