kasl/commands/

mod.rs

//! Command-line interface commands for kasl application.
//!
//! Contains all CLI command implementations for task management, activity monitoring,
//! reporting, and system configuration.
//!
//! ## Usage
//!
//! ```bash
//! kasl watch                    # Start activity monitoring
//! kasl task add --name "Review code" # Create a new task
//! kasl report                   # Generate today's report
//! kasl export tasks --format csv # Export tasks to CSV
//! ```

pub mod autostart;
pub mod export;
pub mod inbox;
pub mod init;
pub mod migrations;
pub mod pauses;
pub mod report;
pub mod server;
pub mod sum;
pub mod tag;
pub mod task;
pub mod template;
pub mod toast_action;
pub mod update;
pub mod watch;

use crate::{
    db::workdays::Workdays,
    libs::{messages::types::Message, output},
    msg_error_anyhow, msg_info, msg_warning,
};
use anyhow::Result;
use chrono::Local;
use clap::{Parser, Subcommand};

/// Defines the main subcommands that the application can execute.
#[derive(Debug, Subcommand)]
enum Commands {
    /// Manage autostart configuration for system boot
    ///
    /// Controls whether kasl automatically starts monitoring when the system boots.
    /// Supports both system-level and user-level autostart on Windows.
    #[command(about = "Manage autostart on system boot")]
    Autostart(autostart::AutostartArgs),

    /// Set up application configuration interactively
    ///
    /// Guides the user through setting up API credentials, monitor settings,
    /// and other configuration options required for kasl to function properly.
    ///
    /// `init` stays as a deprecated alias until 2.0. An alias rather than a
    /// hidden variant: clap_complete emits hidden subcommands into the
    /// completion scripts, so Tab would keep teaching the old spelling.
    #[command(about = "Set up configuration", alias = "init")]
    Setup(init::SetupArgs),

    /// Comprehensive task management command
    ///
    /// Handles all task-related operations including creation, editing, deletion,
    /// viewing, and integration with external services like GitLab and Jira.
    #[command(about = "Create task")]
    Task(task::TaskArgs),

    /// Manually end the current workday
    ///
    /// Records the end timestamp for today's work session. Typically used
    /// when the automatic monitoring needs to be manually finalized.
    #[command(about = "Write end timestamp to database")]
    End,

    /// Display monthly working hours summary
    ///
    /// Shows a comprehensive overview of work hours, productivity metrics,
    /// and daily breakdowns for the current month.
    #[command(about = "Get summary")]
    Sum(sum::SumArgs),

    /// Update kasl itself to the latest release
    ///
    /// Checks GitHub releases for newer versions and automatically downloads
    /// and installs updates if available.
    ///
    /// `update` stays as a deprecated alias until 2.0; it read as "update my
    /// data", which is what every other command does.
    #[command(name = "self-update", about = "Update kasl itself to the latest release", alias = "update")]
    SelfUpdate,

    /// Generate and optionally submit work reports
    ///
    /// Creates detailed daily reports with work intervals, tasks, and productivity
    /// metrics. Can automatically submit reports to configured APIs.
    #[command(about = "Prepare a report")]
    Report(report::ReportArgs),

    /// Export application data to external formats
    ///
    /// Supports exporting tasks, reports, and summaries to CSV, JSON, and Excel
    /// formats for external analysis or backup purposes.
    #[command(about = "Export data to various formats")]
    Export(export::ExportArgs),

    /// Manage reusable task templates
    ///
    /// Create, edit, and use templates for frequently created tasks to
    /// streamline task creation workflow.
    #[command(about = "Manage task templates")]
    Template(template::TemplateArgs),

    /// Organize tasks with custom tags
    ///
    /// Create and manage tags to categorize and filter tasks by project,
    /// priority, or any custom criteria.
    #[command(about = "Manage task tags")]
    Tag(tag::TagArgs),

    /// Background activity monitoring daemon
    ///
    /// Monitors user input activity to automatically detect work sessions,
    /// breaks, and workday boundaries. Can run as a background service.
    #[command(about = "Watch user activity in the background to record pauses")]
    Watch(watch::WatchArgs),

    /// View recorded pauses and record ones the monitor missed
    ///
    /// Lists detected pauses for a date, and lets the user add an absence the
    /// activity monitor did not catch or remove one recorded by mistake.
    #[command(about = "View pauses and record ones the monitor missed")]
    Pauses(pauses::PausesArgs),

    /// Connection to the team's kasl-server
    ///
    /// Connects this machine to a kasl-server with an agent token issued by
    /// an administrator, shows where the connection stands, and forgets it
    /// again. The token lives in the OS keyring, never in the config file.
    #[command(about = "Manage the connection to a kasl-server")]
    Server(server::ServerArgs),

    /// Jira inbox of assigned open issues
    ///
    /// Syncs assigned unresolved Jira issues into a local table, lists them
    /// by priority, and supports pin / dismiss / open / import into tasks,
    /// and starting, closing and commenting on issues in Jira.
    // Boxed: a filter set on every subcommand makes these the largest
    // arguments by far, and every other variant would carry their size.
    #[command(about = "Manage Jira inbox issues")]
    Inbox(Box<inbox::InboxArgs>),

    /// Print a shell completion script
    ///
    /// Emits the completion script for the chosen shell on stdout; source it
    /// from the shell profile to get completion for kasl's commands and flags.
    #[command(about = "Print a shell completion script (source it from your shell profile)")]
    Completions {
        /// Target shell
        shell: clap_complete::Shell,
    },

    /// Carry one toast button press to the watcher (internal)
    ///
    /// Launched by the shortcut behind a toast's Take / Snooze / Dismiss
    /// button, because a toast button cannot pass an argument of its own.
    /// It posts the decision to the watcher and exits without printing.
    /// Hidden from help and completion: the commands a person types for this
    /// are `kasl inbox take`, `snooze` and `dismiss`, which say what they did.
    #[command(hide = true, about = "Carry a toast button press to the watcher")]
    ToastAction(toast_action::ToastActionArgs),

    /// Database migration management utilities (debug builds only)
    ///
    /// Provides tools for database schema management, migration history,
    /// and rollback operations. Available only in debug builds for safety.
    #[cfg(debug_assertions)]
    #[command(about = "Database migration management")]
    Migrations(migrations::MigrationsArgs),
}

/// The main CLI structure that parses command-line arguments.
///
/// Uses `clap` to define the application's interface and delegates
/// command execution to the appropriate subcommand module. The CLI
/// requires at least one subcommand to be specified.
///
/// # Examples
///
/// ```bash
/// # Display help
/// kasl --help
///
/// # Run a specific command
/// kasl task add --name "New task"
///
/// # The inbox as JSON, and today's report for a log
/// kasl inbox list --json
/// kasl report --plain
/// ```
#[derive(Debug, Parser)]
#[command(name = "kasl", author, version, about, long_about = None)]
#[command(arg_required_else_help(true))]
pub struct Cli {
    #[command(subcommand)]
    command: Commands,

    /// Plain text for logs and pipes: no colour, no emoji, tables as tab-separated lines
    #[arg(long, global = true)]
    plain: bool,

    /// Whether the command asked for `--json`, read off the parsed arguments.
    #[arg(skip)]
    json: bool,
}

impl Cli {
    /// Parses `args` (the program name first), exiting with clap's message on a usage error.
    ///
    /// `--json` is flattened into each command that prints data (see
    /// [`crate::libs::output::Format`]), so whether this run asked for it is
    /// read off the parsed arguments wherever in the subcommand chain it sits,
    /// rather than out of a match over every command that has it.
    pub fn from_args(args: &[String]) -> Cli {
        use clap::{CommandFactory, FromArgMatches};
        let matches = Self::command().color(output::clap_colour(args)).get_matches_from(args);
        let mut cli = Self::from_arg_matches(&matches).unwrap_or_else(|error| error.exit());
        cli.json = json_requested(&matches);
        cli
    }

    /// Whether this run prints a JSON document.
    pub fn json(&self) -> bool {
        self.json
    }

    /// Whether this run asked for plain text.
    pub fn plain(&self) -> bool {
        self.plain
    }

    /// Executes the parsed command.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use kasl::commands::Cli;
    ///
    /// #[tokio::main]
    /// async fn main() -> anyhow::Result<()> {
    ///     let args: Vec<String> = std::env::args().collect();
    ///     Cli::from_args(&args).dispatch().await
    /// }
    /// ```
    pub async fn dispatch(self) -> Result<()> {
        let cli = self;
        match cli.command {
            Commands::Autostart(args) => autostart::cmd(args),
            Commands::Setup(args) => {
                warn_if_deprecated_alias();
                init::cmd(args)
            }
            Commands::Task(args) => task::cmd(args).await,
            Commands::End => {
                // Manually end the current workday. A day that was never
                // opened is a refusal, not a success: saying "ended" over an
                // empty database taught users to trust a stamp that is not
                // there.
                let today = Local::now().date_naive();
                if !Workdays::new()?.insert_end(today)? {
                    return Err(msg_error_anyhow!(Message::WorkdayNeverStarted(today.to_string())));
                }
                msg_info!(Message::WorkdayEnded);
                Ok(())
            }
            Commands::Sum(args) => sum::cmd(args).await,
            Commands::Report(args) => report::cmd(args).await,
            Commands::Export(args) => export::cmd(args).await,
            Commands::Template(args) => template::cmd(args),
            Commands::Tag(args) => tag::cmd(args).await,
            Commands::SelfUpdate => {
                warn_if_deprecated_alias();
                update::cmd().await
            }
            Commands::Watch(args) => watch::cmd(args).await,
            Commands::Pauses(args) => pauses::cmd(args).await,
            Commands::Completions { shell } => {
                use clap::CommandFactory;
                use std::io::Write;
                // Generated whole, then written: clap_complete panics on a
                // failed write in its own words, which the closed-pipe hook
                // does not know, so `kasl completions bash | head` would end
                // in a panic instead of quietly.
                let mut script = Vec::new();
                clap_complete::generate(shell, &mut Self::command(), "kasl", &mut script);
                match std::io::stdout().write_all(&script) {
                    Err(error) if output::is_a_closed_pipe_error(&error) => Ok(()),
                    written => Ok(written?),
                }
            }
            Commands::Server(args) => server::cmd(args).await,
            Commands::Inbox(args) => inbox::cmd(*args).await,
            Commands::ToastAction(args) => toast_action::cmd(args).await,

            // Database migrations only available in debug builds
            #[cfg(debug_assertions)]
            Commands::Migrations(args) => migrations::cmd(args),
        }
    }
}

/// Whether `--json` was given to the command at the end of the chain or on the way to it.
fn json_requested(matches: &clap::ArgMatches) -> bool {
    let here = matches!(matches.try_get_one::<bool>("json"), Ok(Some(true)));
    here || matches.subcommand().is_some_and(|(_, sub)| json_requested(sub))
}

/// Old command names still accepted as aliases, with their replacements.
///
/// Removed in 2.0; until then the alias works and says so.
const DEPRECATED_ALIASES: [(&str, &str); 2] = [("init", "setup"), ("update", "self-update")];

/// Prints a rename notice when the command was invoked by its old name.
///
/// clap resolves an alias to the canonical variant without recording which
/// spelling was typed, so the first non-flag argument is what tells them
/// apart.
fn warn_if_deprecated_alias() {
    let Some(typed) = std::env::args().nth(1) else {
        return;
    };
    if let Some((old, new)) = DEPRECATED_ALIASES.iter().find(|(old, _)| *old == typed) {
        msg_warning!(Message::DeprecatedCommand(old, new));
    }
}