leviath_cli/

dispatch.rs

//! Command dispatch: the `Commands` enum and the `dispatch()` function that
//! routes a parsed subcommand to its executor.
//!
//! This lives in the library crate (not `main.rs`) so its routing logic can be
//! unit-tested under `cargo llvm-cov`'s `--lib` scope. The subcommands whose
//! real execution performs I/O a unit test must never trigger - a real
//! terminal takeover (`dash`), blocking stdin (`setup` interactive,
//! foreground `run`), binding a real port (`serve`), spawning a detached
//! worker or running a real inference loop (`run` background / `__run-worker`) -
//! are routed through the [`RiskyExecutors`] trait rather than called
//! directly. That way:
//!
//! * unit tests drive `dispatch()`'s full routing match against a
//!   `#[cfg(test)]` mock (`MockRisky`) that touches nothing real, and
//! * the real implementations live in the (coverage-unmeasured) `lev` binary
//!   as `main.rs`'s `RealExecutors`, which simply wires real I/O into the
//!   library's already-tested command cores.
//!
//! Injection gives a "routing is tested, real I/O is never touched by a test"
//! guarantee without any coverage escape hatch in library code.

use crate::commands;

#[derive(clap::Subcommand)]
pub enum Commands {
    /// Create a new agent blueprint
    Create(commands::create::CreateArgs),

    /// Configure API keys and defaults
    Setup(commands::setup::SetupArgs),

    /// Run an agent
    Run(commands::run::RunArgs),

    /// List agents running in the shared-world daemon
    Ps(commands::ps::PsArgs),

    /// Send a message to a running agent
    Msg(commands::ctl::MsgArgs),

    /// Cancel a running agent (alias: `kill`)
    #[command(alias = "kill")]
    Cancel(commands::ctl::CancelArgs),

    /// Answer a pending interaction (or list open ones with no request id)
    Respond(commands::ctl::RespondArgs),

    /// List available and installed blueprints
    List(commands::list::ListArgs),

    /// Install a blueprint
    Add(commands::add::AddArgs),

    /// Remove an installed blueprint
    Remove(commands::remove::RemoveArgs),

    /// Run blueprint tests
    Test(commands::test::TestArgs),

    /// Bundle a blueprint for distribution
    Pack(commands::pack::PackArgs),

    /// Interactive agent dashboard
    #[command(name = "dash")]
    Dashboard(commands::dashboard::DashboardArgs),

    /// List and inspect available models
    Models(commands::models::ModelsArgs),

    /// Validate an agent blueprint
    Validate(commands::validate::ValidateArgs),

    /// List and validate the global Rhai script tools
    Tools(commands::tools::ToolsArgs),

    /// Manage taint tracking policy rules
    Policy(commands::policy::PolicyArgs),

    /// Start the REST + WebSocket API server
    Serve(commands::serve::ServeArgs),

    /// Serve this agent over the Agent Client Protocol (JSON-RPC over stdio)
    #[command(name = "agent-client")]
    AgentClient(commands::agent_client::AgentClientArgs),

    /// Run the shared-world daemon in the foreground
    Daemon(commands::daemon::DaemonArgs),

    /// Show a run's context-window history (from its run.lvr archive)
    Context(commands::context::ContextArgs),

    /// Manage MCP tool servers and their authentication
    Mcp(commands::mcp::McpArgs),

    /// Inspect and move the secrets Leviath holds
    Auth(commands::auth::AuthArgs),
}

/// The subset of commands whose real execution performs I/O that a unit test
/// must never trigger. `dispatch()` routes these through this trait so its
/// routing logic stays unit-testable with a mock; the real implementations are
/// supplied by the binary (`main.rs`'s `RealExecutors`).
///
/// `async fn` in a trait is fine here: `dispatch` takes `&impl RiskyExecutors`
/// (static dispatch, no `dyn`), so no boxing or `Send` bound is required.
#[allow(async_fn_in_trait)]
pub trait RiskyExecutors {
    /// `lev run` - auto-starts the daemon (real process spawn) if needed and
    /// spawns the agent into the shared world over the control socket.
    async fn run(&self, args: commands::run::RunArgs) -> anyhow::Result<()>;
    /// `lev ps` - resolves the control-socket path and queries the daemon.
    async fn ps(&self, args: commands::ps::PsArgs) -> anyhow::Result<()>;
    /// `lev msg` - resolves the control-socket path and sends a message.
    async fn msg(&self, args: commands::ctl::MsgArgs) -> anyhow::Result<()>;
    /// `lev cancel` - resolves the control-socket path and cancels a run.
    async fn cancel(&self, args: commands::ctl::CancelArgs) -> anyhow::Result<()>;
    /// `lev respond` - resolves the control-socket path and answers/lists interactions.
    async fn respond(&self, args: commands::ctl::RespondArgs) -> anyhow::Result<()>;
    /// `lev setup` - interactive (blocking stdin) or `--non-interactive`.
    async fn setup(&self, args: commands::setup::SetupArgs) -> anyhow::Result<()>;
    /// `lev dash` - takes over the real terminal and blocks on real keyboard input.
    async fn dashboard(&self, args: commands::dashboard::DashboardArgs) -> anyhow::Result<()>;
    /// `lev serve` - binds a real port and serves indefinitely.
    async fn serve(&self, args: commands::serve::ServeArgs) -> anyhow::Result<()>;
    /// `lev agent-client` - takes over real stdin/stdout to speak the Agent
    /// Client Protocol against the shared-world daemon.
    async fn agent_client(
        &self,
        args: commands::agent_client::AgentClientArgs,
    ) -> anyhow::Result<()>;
    /// `lev daemon` - binds the control socket and serves the shared world.
    async fn daemon(&self, args: commands::daemon::DaemonArgs) -> anyhow::Result<()>;
    /// `lev mcp` - rewrites config, opens a browser for OAuth, touches the token store.
    async fn mcp(&self, args: commands::mcp::McpArgs) -> anyhow::Result<()>;

    /// `lev auth` - reads the config file and may write the OS credential store.
    async fn auth(&self, args: commands::auth::AuthArgs) -> anyhow::Result<()>;
}

/// Inject argv-prescanned dynamic `--<region>` seed flags into a parsed
/// `run` command. A no-op for every other subcommand. Kept here (a tested lib
/// seam) so the bin entrypoint's post-parse wiring stays branch-free.
pub fn apply_region_flags(
    command: &mut Commands,
    regions: std::collections::HashMap<String, String>,
) {
    if let Commands::Run(args) = command {
        args.regions = regions;
    }
}

/// Route a parsed subcommand to its executor. Safe commands are called
/// directly (and are exercised through `dispatch()` by the tests below); the
/// I/O-risky ones go through `ex` (see [`RiskyExecutors`]).
pub async fn dispatch(command: Commands, ex: &impl RiskyExecutors) -> anyhow::Result<()> {
    match command {
        Commands::Create(args) => commands::create::execute(args).await,
        Commands::Setup(args) => ex.setup(args).await,
        Commands::Run(args) => ex.run(args).await,
        Commands::Ps(args) => ex.ps(args).await,
        Commands::Msg(args) => ex.msg(args).await,
        Commands::Cancel(args) => ex.cancel(args).await,
        Commands::Respond(args) => ex.respond(args).await,
        Commands::List(args) => commands::list::execute(args).await,
        Commands::Add(args) => commands::add::execute(args).await,
        Commands::Remove(args) => commands::remove::execute(args).await,
        Commands::Test(args) => commands::test::execute(args).await,
        Commands::Pack(args) => commands::pack::execute(args).await,
        Commands::Dashboard(args) => ex.dashboard(args).await,
        Commands::Models(args) => commands::models::execute(args).await,
        Commands::Validate(args) => commands::validate::execute(args).await,
        Commands::Tools(args) => commands::tools::execute(args).await,
        Commands::Policy(args) => commands::policy::execute(args).await,
        Commands::Serve(args) => ex.serve(args).await,
        Commands::AgentClient(args) => ex.agent_client(args).await,
        Commands::Daemon(args) => ex.daemon(args).await,
        Commands::Context(args) => commands::context::execute(args).await,
        Commands::Mcp(args) => ex.mcp(args).await,
        Commands::Auth(args) => ex.auth(args).await,
    }
}

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

    /// Test double for [`RiskyExecutors`]: every method is a no-op returning
    /// `Ok(())`, so `dispatch()`'s risky routing arms are exercised without
    /// touching a real terminal / stdin / port / subprocess.
    struct MockRisky;

    impl RiskyExecutors for MockRisky {
        async fn run(&self, _args: commands::run::RunArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn ps(&self, _args: commands::ps::PsArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn msg(&self, _args: commands::ctl::MsgArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn respond(&self, _args: commands::ctl::RespondArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn cancel(&self, _args: commands::ctl::CancelArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn setup(&self, _args: commands::setup::SetupArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn dashboard(&self, _args: commands::dashboard::DashboardArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn serve(&self, _args: commands::serve::ServeArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn agent_client(
            &self,
            _args: commands::agent_client::AgentClientArgs,
        ) -> anyhow::Result<()> {
            Ok(())
        }
        async fn daemon(&self, _args: commands::daemon::DaemonArgs) -> anyhow::Result<()> {
            Ok(())
        }
        async fn auth(&self, _args: commands::auth::AuthArgs) -> anyhow::Result<()> {
            Ok(())
        }

        async fn mcp(&self, _args: commands::mcp::McpArgs) -> anyhow::Result<()> {
            Ok(())
        }
    }

    fn create_args() -> commands::create::CreateArgs {
        commands::create::CreateArgs {
            name: "unused".to_string(),
            template: "software-engineer".to_string(),
        }
    }

    // ─── apply_region_flags ──────────────────────────────────────────────────

    #[test]
    fn apply_region_flags_populates_run_and_noops_other_commands() {
        let mut run = Commands::Run(commands::run::RunArgs::default());
        let flags = std::collections::HashMap::from([("criteria".to_string(), "safe".to_string())]);
        apply_region_flags(&mut run, flags);
        assert!(
            matches!(&run, Commands::Run(a) if a.regions.get("criteria").map(String::as_str) == Some("safe")),
            "region flag was injected into the Run args"
        );
        // A non-run command hits the no-op branch: it must not panic (and there
        // is nothing to inject). Asserting the variant here would leave an
        // always-false `matches!` arm uncovered, so the call itself is the check.
        let mut other = Commands::Ps(commands::ps::PsArgs::default());
        apply_region_flags(&mut other, std::collections::HashMap::new());
    }

    // ─── Risky variants: routed through the injected executor ────────────────

    #[tokio::test]
    async fn dispatch_run_variant_is_routed_through_the_executor() {
        let result = dispatch(Commands::Run(commands::run::RunArgs::default()), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_setup_variant_is_routed_through_the_executor() {
        let args = commands::setup::SetupArgs {
            non_interactive: true,
            no_verify: false,
            install_agents: false,
            anthropic_key: None,
            openai_key: None,
            google_key: None,
            openrouter_key: None,
            ollama_url: None,
            default_model: None,
            claude_code: None,
            claude_code_effort: None,
        };
        let result = dispatch(Commands::Setup(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_dashboard_variant_is_routed_through_the_executor() {
        let args = commands::dashboard::DashboardArgs {};
        let result = dispatch(Commands::Dashboard(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_msg_variant_is_routed_through_the_executor() {
        let args = commands::ctl::MsgArgs {
            agent_id: "a".to_string(),
            content: "c".to_string(),
        };
        assert!(dispatch(Commands::Msg(args), &MockRisky).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_respond_variant_is_routed_through_the_executor() {
        let args = commands::ctl::RespondArgs {
            request_id: None,
            value: None,
            choice: None,
            approve: false,
            deny: false,
            session: false,
        };
        assert!(dispatch(Commands::Respond(args), &MockRisky).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_cancel_variant_is_routed_through_the_executor() {
        let args = commands::ctl::CancelArgs {
            run_id: "r".to_string(),
            force: false,
        };
        assert!(dispatch(Commands::Cancel(args), &MockRisky).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_ps_variant_is_routed_through_the_executor() {
        let result = dispatch(Commands::Ps(commands::ps::PsArgs {}), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_daemon_variant_is_routed_through_the_executor() {
        let args = commands::daemon::DaemonArgs {
            action: None,
            socket: None,
        };
        let result = dispatch(Commands::Daemon(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_auth_variant_is_routed_through_the_executor() {
        let args = commands::auth::AuthArgs::status_for_test();
        let result = dispatch(Commands::Auth(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_mcp_variant_is_routed_through_the_executor() {
        let args = commands::mcp::McpArgs::list_for_test();
        let result = dispatch(Commands::Mcp(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_serve_variant_is_routed_through_the_executor() {
        let args = commands::serve::ServeArgs {
            port: 0,
            host: "127.0.0.1".to_string(),
            cors: None,
            token: Some("test-token".to_string()),
            allow_admin: false,
            workdir_root: None,
            no_remote_yolo: false,
        };
        let result = dispatch(Commands::Serve(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_agent_client_variant_is_routed_through_the_executor() {
        let args = commands::agent_client::AgentClientArgs::default();
        let result = dispatch(Commands::AgentClient(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    // ─── Safe variants: called directly, driven through dispatch() ───────────

    #[tokio::test]
    async fn dispatch_create_variant_is_routed() {
        // An already-existing directory makes `create::execute` return a real,
        // harmless `Err` without touching anything outside a tempdir.
        let dir = tempfile::tempdir().unwrap();
        let args = commands::create::CreateArgs {
            name: dir.path().to_str().unwrap().to_string(),
            ..create_args()
        };
        let result = dispatch(Commands::Create(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_list_variant_is_routed() {
        // Isolated: this reaches `Config::load()`, which reads process-wide
        // environment. Unisolated it races every `temp_env` test in the binary.
        crate::config::with_isolated_config_path_async("dispatch-list", |_fake_dir| async move {
            let args = commands::list::ListArgs {
                filter: "all".to_string(),
            };
            let result = dispatch(Commands::List(args), &MockRisky).await;
            assert!(result.is_ok());
        })
        .await;
    }

    #[tokio::test]
    async fn dispatch_add_variant_is_routed() {
        let args = commands::add::AddArgs {
            package: "definitely-not-a-real-bundle-xyz.leviath-bundle".to_string(),
        };
        let result = dispatch(Commands::Add(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_remove_variant_is_routed() {
        let args = commands::remove::RemoveArgs {
            name: "definitely-not-an-installed-agent-xyz".to_string(),
        };
        let result = dispatch(Commands::Remove(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_test_variant_is_routed() {
        let dir = tempfile::tempdir().unwrap();
        let args = commands::test::TestArgs {
            path: Some(dir.path().to_str().unwrap().to_string()),
            filter: None,
            dry_run: true,
        };
        let result = dispatch(Commands::Test(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_pack_variant_is_routed() {
        let dir = tempfile::tempdir().unwrap();
        let args = commands::pack::PackArgs {
            path: Some(dir.path().to_str().unwrap().to_string()),
            output: None,
        };
        let result = dispatch(Commands::Pack(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_models_variant_is_routed() {
        crate::config::with_isolated_config_path_async("dispatch-models", |_fake_dir| async move {
            let args = commands::models::ModelsArgs {
                command: commands::models::ModelsCommand::List(commands::models::ListArgs {
                    provider: None,
                    remote: false,
                    all: false,
                }),
            };
            let result = dispatch(Commands::Models(args), &MockRisky).await;
            assert!(result.is_ok());
        })
        .await;
    }

    #[tokio::test]
    async fn dispatch_validate_variant_is_routed() {
        let dir = tempfile::tempdir().unwrap();
        let args = commands::validate::ValidateArgs {
            path: dir
                .path()
                .join("does-not-exist")
                .to_str()
                .unwrap()
                .to_string(),
        };
        let result = dispatch(Commands::Validate(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_tools_variant_is_routed() {
        // Point LEVIATH_HOME at a temp dir so the scan is hermetic; an empty
        // tools dir just lists nothing and returns Ok (routing is exercised).
        let home = tempfile::tempdir().unwrap();
        let result = temp_env::async_with_vars(
            [("LEVIATH_HOME", Some(home.path().to_str().unwrap()))],
            async {
                let args = commands::tools::ToolsArgs { json: false };
                dispatch(Commands::Tools(args), &MockRisky).await
            },
        )
        .await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_context_variant_is_routed() {
        // A run with no archive → the command errors (routing is exercised).
        let args = commands::context::ContextArgs {
            run_id: "no-such-run-xyzzy".to_string(),
            json: false,
            full: false,
        };
        let result = dispatch(Commands::Context(args), &MockRisky).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn dispatch_policy_list_variant_is_routed() {
        let args = commands::policy::PolicyArgs {
            command: commands::policy::PolicyCommand::List(commands::policy::PolicyListArgs {}),
        };
        let result = dispatch(Commands::Policy(args), &MockRisky).await;
        assert!(result.is_ok());
    }

    #[tokio::test]
    async fn dispatch_policy_test_variant_is_routed() {
        let args = commands::policy::PolicyArgs {
            command: commands::policy::PolicyCommand::Test(commands::policy::PolicyTestArgs {
                tool: "shell".to_string(),
                target: None,
                taint: "public".to_string(),
            }),
        };
        let result = dispatch(Commands::Policy(args), &MockRisky).await;
        assert!(result.is_ok());
    }
}