Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

15.5 KB
Raw Blame
use std::{
    io::IsTerminal,
    path::{Path, PathBuf},
};

use clap::{Args, Subcommand, ValueEnum};
use serde::Serialize;
use serde_json::{Map, Value, json};
use toml_edit::{Array, DocumentMut, Item, Table, value};

use crate::{OutputFormat, atomic, resolve_format, write_json};

const BUNDLED_SKILL: &str = include_str!("../skill/cap/SKILL.md");

// The cap-demo companion skill ships as a directory tree (scripts, cursor and
// music assets) embedded into the binary alongside the main cap skill.
static CAP_DEMO_SKILL: include_dir::Dir<'static> =
    include_dir::include_dir!("$CARGO_MANIFEST_DIR/skill/cap-demo");

// Flatten every embedded file (recursively) so each becomes its own install
// change. include_dir gives direct files via `files()` and nested dirs via
// `dirs()`; file paths are already relative to the embedded root.
fn collect_demo_files<'a>(dir: &'a include_dir::Dir<'a>, out: &mut Vec<&'a include_dir::File<'a>>) {
    for file in dir.files() {
        out.push(file);
    }
    for sub in dir.dirs() {
        collect_demo_files(sub, out);
    }
}

#[derive(Args)]
pub struct AgentsArgs {
    #[command(subcommand)]
    command: AgentsCommands,
}

#[derive(Subcommand)]
enum AgentsCommands {
    Install(InstallArgs),
}

#[derive(Clone, Copy, ValueEnum)]
enum AgentTarget {
    Codex,
    Claude,
    Cursor,
}

#[derive(Clone, Copy, ValueEnum)]
enum AgentComponent {
    Skill,
    Mcp,
    All,
}

#[derive(Args)]
struct InstallArgs {
    #[arg(long, value_enum)]
    target: AgentTarget,
    #[arg(long, value_enum)]
    component: AgentComponent,
    #[arg(long)]
    dry_run: bool,
    #[arg(long)]
    yes: bool,
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    format: OutputFormat,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct PlannedChange {
    component: &'static str,
    path: PathBuf,
    action: &'static str,
    value: Value,
    #[serde(skip)]
    expected: Option<Vec<u8>>,
    #[serde(skip)]
    content: Option<Vec<u8>>,
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct InstallResult {
    target: &'static str,
    dry_run: bool,
    applied: bool,
    changes: Vec<PlannedChange>,
}

fn home_dir() -> Result<PathBuf, String> {
    dirs::home_dir().ok_or_else(|| "Could not locate the home directory".to_string())
}

fn target_name(target: AgentTarget) -> &'static str {
    match target {
        AgentTarget::Codex => "codex",
        AgentTarget::Claude => "claude",
        AgentTarget::Cursor => "cursor",
    }
}

fn skill_path(target: AgentTarget) -> Result<PathBuf, String> {
    let home = home_dir()?;
    Ok(match target {
        AgentTarget::Codex => std::env::var_os("CODEX_HOME")
            .map(PathBuf::from)
            .unwrap_or_else(|| home.join(".codex"))
            .join("skills/cap/SKILL.md"),
        AgentTarget::Claude => home.join(".claude/skills/cap/SKILL.md"),
        AgentTarget::Cursor => home.join(".cursor/skills/cap/SKILL.md"),
    })
}

// The cap-demo skill installs as a directory sibling of the cap skill.
fn cap_demo_skill_dir(target: AgentTarget) -> Result<PathBuf, String> {
    let home = home_dir()?;
    Ok(match target {
        AgentTarget::Codex => std::env::var_os("CODEX_HOME")
            .map(PathBuf::from)
            .unwrap_or_else(|| home.join(".codex"))
            .join("skills/cap-demo"),
        AgentTarget::Claude => home.join(".claude/skills/cap-demo"),
        AgentTarget::Cursor => home.join(".cursor/skills/cap-demo"),
    })
}

fn mcp_path(target: AgentTarget) -> Result<PathBuf, String> {
    let home = home_dir()?;
    Ok(match target {
        AgentTarget::Codex => std::env::var_os("CODEX_HOME")
            .map(PathBuf::from)
            .unwrap_or_else(|| home.join(".codex"))
            .join("config.toml"),
        AgentTarget::Claude => home.join(".claude.json"),
        AgentTarget::Cursor => home.join(".cursor/mcp.json"),
    })
}

fn atomic_write(path: &Path, content: &[u8], private: bool) -> Result<(), String> {
    #[cfg(not(unix))]
    let _ = private;
    let parent = path
        .parent()
        .ok_or_else(|| "Install path has no parent directory".to_string())?;
    std::fs::create_dir_all(parent).map_err(|error| error.to_string())?;
    let temporary = path.with_extension(format!("tmp-{}", uuid::Uuid::new_v4()));
    std::fs::write(&temporary, content).map_err(|error| error.to_string())?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let permissions = std::fs::metadata(path)
            .map(|metadata| metadata.permissions())
            .unwrap_or_else(|_| {
                std::fs::Permissions::from_mode(if private { 0o600 } else { 0o644 })
            });
        std::fs::set_permissions(&temporary, permissions).map_err(|error| error.to_string())?;
    }
    if let Err(error) = atomic::replace(&temporary, path) {
        let _ = std::fs::remove_file(&temporary);
        return Err(error.to_string());
    }
    Ok(())
}

fn read_optional(path: &Path) -> Result<Option<Vec<u8>>, String> {
    match std::fs::read(path) {
        Ok(content) => Ok(Some(content)),
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(error) => Err(error.to_string()),
    }
}

fn print_changes(changes: &[PlannedChange]) -> Result<(), String> {
    for change in changes {
        println!(
            "{} {}: {}",
            change.action,
            change.component,
            change.path.display()
        );
        println!(
            "  {}",
            serde_json::to_string(&change.value).map_err(|error| error.to_string())?
        );
    }
    Ok(())
}

fn mcp_value() -> Value {
    json!({ "command": "cap", "args": ["mcp", "serve"] })
}

fn merge_json_mcp(existing: Option<&[u8]>) -> Result<Vec<u8>, String> {
    let mut document = match existing {
        Some(bytes) => serde_json::from_slice::<Value>(bytes).map_err(|error| error.to_string())?,
        None => json!({}),
    };
    let object = document
        .as_object_mut()
        .ok_or_else(|| "MCP configuration must be a JSON object".to_string())?;
    let servers = object
        .entry("mcpServers")
        .or_insert_with(|| Value::Object(Map::new()))
        .as_object_mut()
        .ok_or_else(|| "mcpServers must be a JSON object".to_string())?;
    if let Some(current) = servers.get("cap")
        && current != &mcp_value()
    {
        return Err("An incompatible MCP server named 'cap' already exists".to_string());
    }
    servers.insert("cap".to_string(), mcp_value());
    serde_json::to_vec_pretty(&document).map_err(|error| error.to_string())
}

fn merge_codex_mcp(existing: Option<&str>) -> Result<Vec<u8>, String> {
    let mut document = existing
        .unwrap_or_default()
        .parse::<DocumentMut>()
        .map_err(|error| error.to_string())?;
    if !document.as_table().contains_key("mcp_servers") {
        document["mcp_servers"] = Item::Table(Table::new());
    }
    let servers = document["mcp_servers"]
        .as_table_mut()
        .ok_or_else(|| "mcp_servers must be a TOML table".to_string())?;
    if let Some(current) = servers.get("cap") {
        let command = current.get("command").and_then(Item::as_str);
        let args = current.get("args").and_then(Item::as_array);
        let compatible = command == Some("cap")
            && args.is_some_and(|args| {
                args.len() == 2
                    && args.get(0).and_then(toml_edit::Value::as_str) == Some("mcp")
                    && args.get(1).and_then(toml_edit::Value::as_str) == Some("serve")
            });
        if !compatible {
            return Err("An incompatible MCP server named 'cap' already exists".to_string());
        }
    }
    servers["cap"]["command"] = value("cap");
    let mut args = Array::new();
    args.push("mcp");
    args.push("serve");
    servers["cap"]["args"] = value(args);
    Ok(document.to_string().into_bytes())
}

fn confirm() -> Result<(), String> {
    if !std::io::stdin().is_terminal() {
        return Err("Non-interactive installation requires --yes".to_string());
    }
    eprint!("Apply these changes? [y/N] ");
    let mut answer = String::new();
    std::io::stdin()
        .read_line(&mut answer)
        .map_err(|error| error.to_string())?;
    if !matches!(answer.trim().to_ascii_lowercase().as_str(), "y" | "yes") {
        return Err("Installation cancelled".to_string());
    }
    Ok(())
}

impl InstallArgs {
    fn includes_skill(&self) -> bool {
        matches!(self.component, AgentComponent::Skill | AgentComponent::All)
    }

    fn includes_mcp(&self) -> bool {
        matches!(self.component, AgentComponent::Mcp | AgentComponent::All)
    }

    fn plan(&self) -> Result<Vec<PlannedChange>, String> {
        let mut changes = Vec::new();
        if self.includes_skill() {
            let path = skill_path(self.target)?;
            let expected = read_optional(&path)?;
            let action = if expected.as_deref() == Some(BUNDLED_SKILL.as_bytes()) {
                "unchanged"
            } else if expected.is_some() {
                "replace"
            } else {
                "create"
            };
            let content = (action != "unchanged").then(|| BUNDLED_SKILL.as_bytes().to_vec());
            changes.push(PlannedChange {
                component: "skill",
                path,
                action,
                value: json!({ "name": "cap", "content": BUNDLED_SKILL }),
                expected,
                content,
            });

            // Ship the cap-demo companion skill as one change per embedded file.
            let demo_dir = cap_demo_skill_dir(self.target)?;
            let mut demo_files = Vec::new();
            collect_demo_files(&CAP_DEMO_SKILL, &mut demo_files);
            demo_files.sort_by(|a, b| a.path().cmp(b.path()));
            for file in demo_files {
                let relative = file.path();
                let dest = demo_dir.join(relative);
                let expected = read_optional(&dest)?;
                let bytes = file.contents();
                let action = if expected.as_deref() == Some(bytes) {
                    "unchanged"
                } else if expected.is_some() {
                    "replace"
                } else {
                    "create"
                };
                let content = (action != "unchanged").then(|| bytes.to_vec());
                changes.push(PlannedChange {
                    component: "skill",
                    path: dest,
                    action,
                    value: json!({
                        "name": "cap-demo",
                        "file": relative.to_string_lossy(),
                    }),
                    expected,
                    content,
                });
            }
        }
        if self.includes_mcp() {
            let path = mcp_path(self.target)?;
            let expected = read_optional(&path)?;
            let merged = if matches!(self.target, AgentTarget::Codex) {
                let text = expected
                    .as_deref()
                    .map(std::str::from_utf8)
                    .transpose()
                    .map_err(|error| error.to_string())?;
                merge_codex_mcp(text)?
            } else {
                merge_json_mcp(expected.as_deref())?
            };
            let unchanged = expected.as_deref() == Some(merged.as_slice());
            changes.push(PlannedChange {
                component: "mcp",
                action: if unchanged {
                    "unchanged"
                } else if expected.is_some() {
                    "merge"
                } else {
                    "create"
                },
                path,
                value: json!({ "name": "cap", "command": "cap", "args": ["mcp", "serve"] }),
                expected,
                content: (!unchanged).then_some(merged),
            });
        }
        Ok(changes)
    }

    fn apply(&self, changes: &[PlannedChange]) -> Result<(), String> {
        for change in changes {
            if read_optional(&change.path)? != change.expected {
                return Err(format!(
                    "{} changed after the installation preview; review a new preview before applying",
                    change.path.display()
                ));
            }
        }
        for change in changes {
            if let Some(content) = &change.content {
                atomic_write(&change.path, content, change.component == "mcp")?;
            }
        }
        Ok(())
    }
}

impl AgentsArgs {
    pub fn run(self, global_json: bool) -> Result<(), String> {
        let format = match &self.command {
            AgentsCommands::Install(args) => resolve_format(global_json, args.format),
        };
        let result = self.run_inner(global_json);
        if let Err(error) = &result
            && format == OutputFormat::Json
        {
            let _ = write_json(&json!({ "error": error }));
        }
        result
    }

    fn run_inner(self, global_json: bool) -> Result<(), String> {
        match self.command {
            AgentsCommands::Install(args) => {
                let format = resolve_format(global_json, args.format);
                let changes = args.plan()?;
                if args.dry_run {
                    let result = InstallResult {
                        target: target_name(args.target),
                        dry_run: true,
                        applied: false,
                        changes,
                    };
                    return match format {
                        OutputFormat::Json => write_json(&result),
                        OutputFormat::Text => print_changes(&result.changes),
                    };
                }
                if format == OutputFormat::Text {
                    print_changes(&changes)?;
                } else if !args.yes {
                    eprintln!(
                        "{}",
                        serde_json::to_string_pretty(&changes).map_err(|error| error.to_string())?
                    );
                }
                if !args.yes {
                    confirm()?;
                }
                args.apply(&changes)?;
                let result = InstallResult {
                    target: target_name(args.target),
                    dry_run: false,
                    applied: true,
                    changes,
                };
                match format {
                    OutputFormat::Json => write_json(&result),
                    OutputFormat::Text => {
                        println!("Installed Cap agent components for {}.", result.target);
                        Ok(())
                    }
                }
            }
        }
    }
}

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

    #[test]
    fn json_merge_preserves_unrelated_servers() {
        let merged = merge_json_mcp(Some(
            br#"{"mcpServers":{"other":{"command":"other"}},"setting":true}"#,
        ))
        .unwrap();
        let value: Value = serde_json::from_slice(&merged).unwrap();
        assert_eq!(value["setting"], true);
        assert_eq!(value["mcpServers"]["other"]["command"], "other");
        assert_eq!(value["mcpServers"]["cap"], mcp_value());
    }

    #[test]
    fn codex_merge_rejects_conflicting_cap_server() {
        let error = merge_codex_mcp(Some(
            "[mcp_servers.cap]\ncommand = \"different\"\nargs = []\n",
        ))
        .unwrap_err();
        assert!(error.contains("incompatible"));
    }

    #[test]
    fn codex_merge_is_stable() {
        let original = "[mcp_servers.cap]\ncommand = \"cap\"\nargs = [\"mcp\", \"serve\"]\n";
        assert_eq!(
            merge_codex_mcp(Some(original)).unwrap(),
            original.as_bytes()
        );
    }
}