vtcode_skills/

command_skills.rs

use crate::model::{SkillMetadata, SkillScope};
use crate::types::{SkillContext, SkillManifest, SkillManifestMetadata, SkillVariety};
use hashbrown::HashMap;
use serde_json::json;
use std::path::PathBuf;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BuiltInCommandExecutor {
    SlashAlias,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CommandSkillBackend {
    TraditionalSkill {
        skill_name: &'static str,
        skill_path: &'static str,
    },
    BuiltInCommand {
        executor: BuiltInCommandExecutor,
    },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommandSkillSpec {
    pub slash_name: &'static str,
    pub skill_name: &'static str,
    pub description: &'static str,
    pub usage: &'static str,
    category: &'static str,
    /// Additional slash names that resolve to this command (the canonical name
    /// stays `slash_name`). Used so legacy commands keep working after a rename.
    aliases: &'static [&'static str],
    pub backend: CommandSkillBackend,
}

impl CommandSkillSpec {
    /// Category used to group the command in host-specific command surfaces.
    pub const fn category(self) -> &'static str {
        self.category
    }

    const fn is_traditional(self) -> bool {
        matches!(self.backend, CommandSkillBackend::TraditionalSkill { .. })
    }

    const fn is_built_in(self) -> bool {
        matches!(self.backend, CommandSkillBackend::BuiltInCommand { .. })
    }
}

#[derive(Debug, Clone)]
pub struct BuiltInCommandSkill {
    spec: &'static CommandSkillSpec,
    manifest: SkillManifest,
    path: PathBuf,
}

impl BuiltInCommandSkill {
    fn from_spec(spec: &'static CommandSkillSpec) -> Self {
        Self {
            spec,
            manifest: built_in_manifest(spec),
            path: built_in_path(spec.skill_name),
        }
    }

    pub fn spec(&self) -> &'static CommandSkillSpec {
        self.spec
    }

    pub fn manifest(&self) -> &SkillManifest {
        &self.manifest
    }

    pub fn name(&self) -> &str {
        &self.manifest.name
    }

    pub fn description(&self) -> &str {
        &self.manifest.description
    }

    pub fn usage(&self) -> &'static str {
        self.spec.usage
    }

    pub fn category(&self) -> &'static str {
        self.spec.category
    }

    pub fn slash_name(&self) -> &'static str {
        self.spec.slash_name
    }

    pub fn path(&self) -> &PathBuf {
        &self.path
    }

    pub fn scope(&self) -> SkillScope {
        SkillScope::System
    }

    pub fn instructions(&self) -> String {
        format!(
            "# {}\n\nThis built-in command skill executes the existing `/{}` slash command backend.\n\n- Slash alias: `/{}`
\n- Usage: `{}`
\n- Category: `{}`
\n- Backend: `built_in`\n",
            self.name(),
            self.slash_name(),
            self.slash_name(),
            self.usage(),
            self.category()
        )
    }
}

macro_rules! built_in_command_spec {
    ($slash:literal, $description:literal, $usage:literal, $category:literal) => {
        CommandSkillSpec {
            slash_name: $slash,
            skill_name: concat!("cmd-", $slash),
            description: $description,
            usage: $usage,
            category: $category,
            aliases: &[],
            backend: CommandSkillBackend::BuiltInCommand { executor: BuiltInCommandExecutor::SlashAlias },
        }
    };
}

macro_rules! traditional_command_spec {
    ($slash:literal, $description:literal, $usage:literal, $category:literal, $skill_path:literal) => {
        CommandSkillSpec {
            slash_name: $slash,
            skill_name: concat!("cmd-", $slash),
            description: $description,
            usage: $usage,
            category: $category,
            aliases: &[],
            backend: CommandSkillBackend::TraditionalSkill {
                skill_name: concat!("cmd-", $slash),
                skill_path: $skill_path,
            },
        }
    };
}

const COMMAND_SKILL_SPECS: &[CommandSkillSpec] = &[
    built_in_command_spec!(
        "init",
        "Guided workspace setup for vtcode.toml, AGENTS.md, and indexing (usage: /init [--force])",
        "/init [--force]",
        "workspace"
    ),
    built_in_command_spec!(
        "config",
        "Browse settings and run workspace panels: memory, permissions, model, ide, tasks, jobs, log, subprocess, notify, checkup, or reset the active layer (usage: /config [memory|permissions|model|ide|tasks|jobs|log|subprocess|notify|checkup|<path>|reset])",
        "/config [memory|permissions|model|ide|tasks|jobs|log|subprocess|notify|checkup|<path>|reset]",
        "configuration"
    ),
    CommandSkillSpec {
        slash_name: "model",
        skill_name: "cmd-model",
        description: "Launch the interactive model picker (includes reasoning effort)",
        usage: "/model (alias: /models)",
        category: "configuration",
        aliases: &["models"],
        backend: CommandSkillBackend::BuiltInCommand { executor: BuiltInCommandExecutor::SlashAlias },
    },
    built_in_command_spec!(
        "fast",
        "Toggle native OpenAI ultrafast or Claude fast at premium pricing (usage: /fast [on|off])",
        "/fast [on|off]",
        "configuration"
    ),
    built_in_command_spec!(
        "mode",
        "Switch the active agent mode (usage: /mode [agent-name])",
        "/mode [agent-name]",
        "configuration"
    ),
    built_in_command_spec!("theme", "Switch UI theme (usage: /theme <theme-id>)", "/theme [theme-id]", "configuration"),
    traditional_command_spec!(
        "review",
        "Review the current diff or selected files (usage: /review [instructions | --last-diff | --target <expr> | --file <path> | files...] [--style <style>])",
        "/review [instructions | --last-diff | --target <expr> | --file <path> | files...] [--style <style>]",
        "tools",
        ".system/cmd-review"
    ),
    built_in_command_spec!(
        "files",
        "Browse and select files from workspace (usage: /files [filter])",
        "/files [filter]",
        "tools"
    ),
    built_in_command_spec!("copy", "Copy the latest complete assistant reply to clipboard", "/copy", "tools"),
    built_in_command_spec!(
        "skills",
        "Open interactive skills manager (usage: /skills, /skills manager)",
        "/skills [manager|list|search|create|load|unload|info|use|validate|package|regenerate-index|doctor|help]",
        "tools"
    ),
    built_in_command_spec!(
        "agent",
        "Manage subagents and delegated child threads (usage: /agent [list|threads|inspect <id>|close <id>|create [project|user] [name]|edit [name]|delete <name>])",
        "/agent [list|threads|inspect <id>|close <id>|create [project|user] [name]|edit [name]|delete <name>]",
        "tools"
    ),
    built_in_command_spec!("status", "Show model, provider, workspace, and tool status", "/status", "status"),
    built_in_command_spec!("splash", "Show CLI, Desktop, and WebMCP connection wiring status", "/splash", "status"),
    built_in_command_spec!("stop", "Stop the active turn immediately", "/stop", "status"),
    built_in_command_spec!("pause", "Pause the active turn at the next safe boundary", "/pause", "status"),
    built_in_command_spec!(
        "update",
        "Check for new VT Code releases and install updates (usage: /update [check|install] [--force], or run `vtcode update` from the CLI)",
        "/update [check|install] [--force]",
        "status"
    ),
    built_in_command_spec!(
        "mcp",
        "Open interactive MCP manager (usage: /mcp, optional subcommands still supported)",
        "/mcp [status|list|tools|refresh|config|config edit|repair|diagnose|login <name>|logout <name>]",
        "integration"
    ),
    built_in_command_spec!(
        "webmcp",
        "Manage the opt-in authenticated browser editor bridge (usage: /webmcp [help|status|tools|roots|pair [--replace] <origin>|unpair])",
        "/webmcp [help|status|tools|roots|pair [--replace] <origin>|unpair]",
        "integration"
    ),
    built_in_command_spec!(
        "explain",
        "Explain recorded execution without a model call",
        "/explain [--scope task|session] [--details|diagram|--web|--export html]",
        "status"
    ),
    built_in_command_spec!(
        "plugin",
        "Open interactive Agent Plugins manager (usage: /plugin, /plugin manager)",
        "/plugin [manager|list|info <name>|add <source> [--name <id>]|remove <name>|validate <path>|refresh|help]",
        "integration"
    ),
    built_in_command_spec!(
        "local",
        "Manage local inference servers: Ollama, LM Studio, llama.cpp (usage: /local [action] [provider])",
        "/local [status|start|stop|configure|troubleshoot] [ollama|lmstudio|llamacpp]",
        "integration"
    ),
    built_in_command_spec!(
        "resume",
        "List archived sessions when idle; resume the active turn while it is paused",
        "/resume [limit|--all]",
        "session"
    ),
    built_in_command_spec!(
        "fork",
        "Fork an archived session into a new thread (usage: /fork [limit] [--all])",
        "/fork [limit] [--all]",
        "session"
    ),
    built_in_command_spec!(
        "history",
        "Open command history picker (usage: /history, same as Ctrl+R)",
        "/history",
        "session"
    ),
    built_in_command_spec!("clear", "Clear visible screen (usage: /clear [new])", "/clear [new]", "session"),
    built_in_command_spec!(
        "transcript",
        "Inspect or manage the bounded TUI transcript snapshot (usage: /transcript [stats|clear|export [path]])",
        "/transcript [stats|clear|export [path]]",
        "session"
    ),
    built_in_command_spec!(
        "compact",
        "Compact the current conversation immediately or manage the saved manual compaction prompt",
        "/compact [--instructions <text>] [--max-output-tokens <n>] [--reasoning-effort <none|minimal|low|medium|high|xhigh>] [--verbosity <low|medium|high>] [--native-only] | /compact edit-prompt | /compact reset-prompt",
        "session"
    ),
    built_in_command_spec!("new", "Start a new session", "/new", "session"),
    built_in_command_spec!(
        "share",
        "Export the current session as JSON, Markdown, or self-contained HTML timeline (usage: /share [json|markdown|md|html|--format <fmt>])",
        "/share [json|markdown|md|html|--format <fmt>]",
        "session"
    ),
    built_in_command_spec!(
        "rewind",
        "Open the rewind picker or restore a specific checkpoint (usage: /rewind [turn] [conversation|code|both])",
        "/rewind [turn] [conversation|code|both]",
        "session"
    ),
    built_in_command_spec!("redo", "Restore files and conversation from before the last rewind", "/redo", "session"),
    built_in_command_spec!(
        "plan",
        "Start or continue the planning workflow with an optional task prompt (usage: /plan [task])",
        "/plan [task]",
        "session"
    ),
    built_in_command_spec!("docs", "Open vtcode documentation in web browser", "/docs", "support"),
    built_in_command_spec!(
        "feedback",
        "Open a new GitHub issue to report a bug or request a feature",
        "/feedback",
        "support"
    ),
    built_in_command_spec!("help", "Show slash command help", "/help [command]", "support"),
    built_in_command_spec!("exit", "Exit the session", "/exit", "session"),
    built_in_command_spec!("donate", "Support the project by buying the author a coffee", "/donate", "support"),
    built_in_command_spec!(
        "terminal-setup",
        "Configure terminal for VT Code (multiline, copy/paste, shell, themes, tab icon)",
        "/terminal-setup [install-iterm2-icon|reset-iterm2-icon|icon [light|dark|clear|tinted|dynamic]]",
        "terminal"
    ),
    built_in_command_spec!(
        "statusline",
        "Set up a custom status line with target selection (usage: /statusline [instructions...])",
        "/statusline [instructions...]",
        "terminal"
    ),
    built_in_command_spec!("title", "Configure the terminal title items interactively", "/title", "terminal"),
    built_in_command_spec!(
        "vim",
        "Toggle Vim-style prompt editing for this session (usage: /vim [on|off])",
        "/vim [on|off]",
        "terminal"
    ),
    built_in_command_spec!(
        "login",
        "Authenticate with OpenAI, OpenRouter, or GitHub Copilot (usage: /login [provider])",
        "/login [provider]",
        "auth"
    ),
    built_in_command_spec!(
        "logout",
        "Clear stored provider authentication (usage: /logout [provider])",
        "/logout [provider]",
        "auth"
    ),
    built_in_command_spec!(
        "auth",
        "Show authentication status for providers (usage: /auth [provider])",
        "/auth [provider]",
        "auth"
    ),
    built_in_command_spec!(
        "refresh-oauth",
        "Refresh stored provider credentials when supported (usage: /refresh-oauth [provider])",
        "/refresh-oauth [provider]",
        "auth"
    ),
    built_in_command_spec!(
        "secret",
        "Manage provider API keys in your OS keyring (usage: /secret [list|status [provider] [key-name]|add <provider> [key-name]|delete <provider> [key-name]|migrate [provider]|help])",
        "/secret [list|status [provider] [key-name]|add <provider> [key-name]|delete <provider> [key-name]|migrate [provider]|help]",
        "auth"
    ),
];

pub fn command_skill_specs() -> &'static [CommandSkillSpec] {
    COMMAND_SKILL_SPECS
}

pub fn find_command_skill_by_slash_name(name: &str) -> Option<&'static CommandSkillSpec> {
    COMMAND_SKILL_SPECS
        .iter()
        .find(|spec| spec.slash_name == name || spec.aliases.contains(&name))
}

pub fn find_command_skill_by_skill_name(name: &str) -> Option<&'static CommandSkillSpec> {
    COMMAND_SKILL_SPECS.iter().find(|spec| spec.skill_name == name)
}

fn is_command_skill_name(name: &str) -> bool {
    find_command_skill_by_skill_name(name).is_some()
}

pub fn is_model_catalog_eligible(skill: &SkillMetadata) -> bool {
    if skill
        .manifest
        .as_ref()
        .and_then(|manifest| manifest.disable_model_invocation)
        .unwrap_or(false)
    {
        return false;
    }

    !is_command_skill_name(&skill.name)
}

pub fn built_in_command_skill_contexts() -> Vec<SkillContext> {
    COMMAND_SKILL_SPECS
        .iter()
        .copied()
        .filter(|spec| spec.is_built_in())
        .map(|spec| SkillContext::MetadataOnly(built_in_manifest(&spec), built_in_path(spec.skill_name)))
        .collect()
}

pub fn built_in_command_skill(name: &str) -> Option<BuiltInCommandSkill> {
    find_command_skill_by_skill_name(name)
        .filter(|spec| spec.is_built_in())
        .map(BuiltInCommandSkill::from_spec)
}

pub fn merge_built_in_command_skill_contexts(skills: &mut Vec<SkillContext>) {
    skills.extend(built_in_command_skill_contexts());
    skills.sort_by(|left, right| left.manifest().name.cmp(&right.manifest().name));
    skills.dedup_by(|left, right| left.manifest().name == right.manifest().name);
}

pub fn merge_built_in_command_skill_metadata(skills: &mut Vec<SkillMetadata>) {
    skills.extend(built_in_command_skill_contexts().into_iter().map(|skill_ctx| SkillMetadata {
        name: skill_ctx.manifest().name.clone(),
        description: skill_ctx.manifest().description.clone(),
        short_description: None,
        path: skill_ctx.path().clone(),
        scope: SkillScope::System,
        manifest: Some(skill_ctx.manifest().clone().into()),
    }));
    skills.sort_by(|left, right| left.name.cmp(&right.name));
    skills.dedup_by(|left, right| left.name == right.name);
}

fn built_in_manifest(spec: &CommandSkillSpec) -> SkillManifest {
    SkillManifest {
        name: spec.skill_name.to_string(),
        description: spec.description.to_string(),
        disable_model_invocation: Some(true),
        variety: SkillVariety::BuiltIn,
        metadata: Some(command_skill_metadata(spec, "built_in_command")),
        ..Default::default()
    }
}

fn command_skill_metadata(spec: &CommandSkillSpec, backend: &str) -> SkillManifestMetadata {
    let mut metadata = HashMap::new();
    metadata.insert("slash_alias".to_string(), json!(format!("/{}", spec.slash_name)));
    metadata.insert("usage".to_string(), json!(spec.usage));
    metadata.insert("category".to_string(), json!(spec.category));
    metadata.insert("backend".to_string(), json!(backend));
    metadata
}

fn built_in_path(skill_name: &str) -> PathBuf {
    PathBuf::from(format!("<built-in>/{skill_name}"))
}

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

    #[test]
    fn traditional_and_built_in_commands_are_mapped() {
        let review = find_command_skill_by_slash_name("review").expect("review spec");
        assert!(review.is_traditional());
        assert_eq!(review.skill_name, "cmd-review");

        let status = find_command_skill_by_slash_name("status").expect("status spec");
        assert!(status.is_built_in());
        assert_eq!(status.skill_name, "cmd-status");

        let splash = find_command_skill_by_slash_name("splash").expect("splash spec");
        assert!(splash.is_built_in());
        assert_eq!(splash.usage, "/splash");
    }

    #[test]
    fn models_alias_opens_the_model_picker() {
        let model = find_command_skill_by_slash_name("models").expect("models alias");
        assert_eq!(model.slash_name, "model");
        assert!(model.is_built_in());
    }

    #[test]
    fn built_in_contexts_are_tagged_correctly() {
        let built_in = built_in_command_skill_contexts();
        let status = built_in
            .iter()
            .find(|ctx| ctx.manifest().name == "cmd-status")
            .expect("cmd-status context");
        assert_eq!(status.manifest().variety, SkillVariety::BuiltIn);
    }

    #[test]
    fn removed_generate_agent_file_command_is_not_registered() {
        assert!(find_command_skill_by_slash_name("generate-agent-file").is_none());
        assert!(find_command_skill_by_skill_name("cmd-generate-agent-file").is_none());
    }

    #[test]
    fn mode_command_switches_active_agent_mode() {
        // The `/mode` command was re-introduced (commit ef1b52b6f) as a live
        // feature: with no argument it opens the mode palette, with an argument
        // (build|auto|duck|plan) it selects the primary agent directly. It must
        // remain registered alongside the dedicated mode commands.
        let mode = find_command_skill_by_slash_name("mode").expect("mode spec");
        assert!(mode.description.contains("mode"));
    }

    #[test]
    fn plan_command_skill_uses_workflow_copy() {
        let plan = find_command_skill_by_slash_name("plan").expect("plan spec");
        assert!(plan.description.contains("planning workflow"));
        assert!(!plan.description.contains("mode"));
        assert_eq!(plan.usage, "/plan [task]");
    }

    #[test]
    fn removed_config_consolidated_commands_are_not_registered() {
        for removed in [
            "checkup",
            "doctor",
            "permissions",
            "ide",
            "tasks",
            "jobs",
            "log",
            "subprocess",
            "notify",
            "memory",
            "effort",
            "continue",
            "edit",
            "analyze",
        ] {
            assert!(
                find_command_skill_by_slash_name(removed).is_none(),
                "/{removed} must not be registered; use /config instead"
            );
        }
        let config = find_command_skill_by_slash_name("config").expect("config spec");
        assert!(config.usage.contains("checkup"));
    }
}