maestro/crates/maestro-cli/src/dispatch.rs

//! Public dispatch for the `maestro` CLI subcommands.
//!
//! Every command talks to the local daemon (`[cli].daemon_url`, default
//! `http://127.0.0.1:7070`): `list` reads its session catalog, `spawn` / `kill`
//! hit its session endpoints, and `attach` opens `WS /api/attach/:id`.

use std::path::{Path, PathBuf};

use maestro_protocol::DaemonClient;

use crate::attach::{parse_detach_key, run_attach_url};
use crate::cli::Command;
use crate::sessions::{run_kill, run_list, run_spawn};
use maestro_config::{default_config_path, MaestroConfigFile};

#[derive(Debug, thiserror::Error)]
#[allow(clippy::result_large_err)]
pub enum CliError {
    #[error("config: {0}")]
    Config(#[from] maestro_config::ConfigError),
    #[error("{0}")]
    Client(#[from] maestro_protocol::ClientError),
    #[error("{0}")]
    Attach(#[from] crate::attach::AttachError),
    #[error("{0}")]
    Hooks(#[from] maestro_hooks::HooksError),
    #[error("could not determine the home directory ($HOME unset?)")]
    NoHome,
    #[error("{0}")]
    Io(#[from] std::io::Error),
}

/// Dispatch a parsed top-level subcommand. The umbrella binary passes the
/// global flags (`--config`, `--daemon-url`) in alongside the variant.
#[allow(clippy::result_large_err)]
pub async fn dispatch(
    command: Command,
    config: Option<PathBuf>,
    daemon_url_override: Option<String>,
) -> Result<(), CliError> {
    let config_path = match config {
        Some(p) => p,
        None => default_config_path()?,
    };

    // `hooks install` is purely local: it must work with the daemon down, so
    // it never touches the client.
    if let Command::Hooks(args) = &command {
        match args.command {
            crate::cli::HooksCommand::Install => run_hooks_install()?,
        }
        return Ok(());
    }

    let daemon = client(&config_path, daemon_url_override)?;

    match command {
        Command::List(args) => {
            let mut stdout = std::io::stdout().lock();
            run_list(&daemon, &args, &mut stdout).await?;
        }
        Command::Spawn(args) => {
            let attach_after = args.attach;
            let session = run_spawn(&daemon, args).await?;
            println!("spawned {}", session.id);
            if attach_after {
                // `spawn --attach` has no detach-key flag; use the attach
                // default (Ctrl-q).
                run_attach_url(&daemon.attach_url(session.id)?, CTRL_Q).await?;
            }
        }
        Command::Attach(args) => {
            let detach = parse_detach_key(&args.detach_key)?;
            run_attach_url(&daemon.attach_url(args.session_id)?, detach).await?;
        }
        Command::Kill(args) => {
            // #83: warn BEFORE the attempt, so the refusal is not a surprise.
            // Best-effort: an unreachable list must not block the kill.
            if !args.force {
                warn_if_blocked(&daemon, args.session_id).await;
            }
            run_kill(&daemon, &args).await?;
            println!("killed {}", args.session_id);
        }
        Command::Hooks(_) => unreachable!("hooks handled before the daemon client exists"),
    }
    Ok(())
}

/// `maestro hooks install` (#106): write the shipped hook script under the
/// user's data dir and register it in their Claude Code settings. Idempotent
/// and foreign-hook-preserving — the guarantees live in [`maestro_hooks`].
#[allow(clippy::result_large_err)]
fn run_hooks_install() -> Result<(), CliError> {
    let home = dirs::home_dir().ok_or(CliError::NoHome)?;
    let changed = maestro_hooks::install_for_home(&home)?;
    if changed {
        println!(
            "installed claude-code activity hook: {} → {}",
            maestro_hooks::script_path(&home).display(),
            maestro_hooks::settings_path(&home).display()
        );
    } else {
        println!("claude-code activity hook already up to date");
    }
    Ok(())
}

/// Default detach byte, matching `maestro attach --detach-key`'s `^q`.
const CTRL_Q: u8 = 0x11;

/// #83: say "this will be refused" before the operator commits to it, in the
/// same words [`maestro_protocol::InTheWay`] uses everywhere else.
async fn warn_if_blocked(daemon: &DaemonClient, id: uuid::Uuid) {
    let Ok(sessions) = daemon.list_sessions().await else {
        return;
    };
    if let Some(b) = sessions
        .iter()
        .find(|s| s.id == id)
        .and_then(|s| s.blocked_work)
    {
        if !b.is_clear() {
            eprintln!(
                "warning: this kill will be refused — the session's worktree holds unsaved work ({b}); use --force to end it anyway"
            );
        }
    }
}

/// HTTP client pointed at the daemon's API. That surface needs no auth —
/// reaching `bind_addr` is the authorization.
#[allow(clippy::result_large_err)]
fn client(config_path: &Path, override_url: Option<String>) -> Result<DaemonClient, CliError> {
    let cfg = MaestroConfigFile::load(config_path)?;
    Ok(DaemonClient::new(cfg.resolve_daemon_url(override_url)))
}