//! View subcommand - interactive TUI browser for tasks, contracts, and files.
//!
//! The `makima view` command provides an interactive Terminal User Interface (TUI)
//! for browsing and managing makima entities. It features fuzzy search filtering,
//! keyboard navigation, and quick actions.
//!
//! # Usage
//!
//! ```bash
//! # Browse tasks interactively
//! makima view tasks
//!
//! # Browse contracts with an initial search query
//! makima view contracts "my project"
//!
//! # Browse files without preview pane
//! makima view files --no-preview
//!
//! # Browse tasks for a specific contract
//! makima view tasks --contract-id <uuid>
//!
//! # Change directory to selected task's worktree
//! cd $(makima view tasks)
//! ```
//!
//! # Keyboard Shortcuts
//!
//! | Key         | Action                    |
//! |-------------|---------------------------|
//! | `↑` / `k`   | Move selection up         |
//! | `↓` / `j`   | Move selection down       |
//! | `Enter`     | View/select item          |
//! | `e`         | Open in editor ($EDITOR)  |
//! | `d`         | Delete item (with confirm)|
//! | `Tab`       | Toggle preview pane       |
//! | `/`         | Focus search input        |
//! | `Esc`       | Clear search / cancel     |
//! | `q`         | Quit                      |
//! | `c`         | Navigate to worktree (cd) |
//! | `Ctrl+r`    | Refresh data              |
//! | `?`         | Show help                 |
//!
//! # Features
//!
//! - **Fuzzy Search**: Type to filter items in real-time
//! - **Multi-term Search**: Use space-separated terms (e.g., "fix bug")
//! - **Recency Sorting**: Recent items appear higher in results
//! - **Preview Pane**: See item details without leaving the list
//! - **Status Indicators**: Visual icons for task states

use clap::{Args, Subcommand};
use uuid::Uuid;

/// Interactive TUI browser for tasks, contracts, and files.
///
/// Provides a fuzzy-searchable interface for browsing and managing
/// makima entities with keyboard navigation and quick actions.
///
/// # Examples
///
/// Browse tasks:
/// ```bash
/// makima view tasks
/// ```
///
/// Browse with initial search:
/// ```bash
/// makima view contracts "auth"
/// ```
#[derive(Subcommand, Debug)]
pub enum ViewCommand {
    /// Browse tasks interactively
    ///
    /// Shows all tasks for the current contract with status indicators,
    /// fuzzy search filtering, and quick actions.
    Tasks(ViewArgs),

    /// Browse contracts interactively
    ///
    /// Lists all contracts with their phase, status, and task counts.
    Contracts(ViewArgs),

    /// Browse files interactively
    ///
    /// Shows contract files with preview of their content.
    Files(ViewArgs),
}

/// Common arguments for view commands.
///
/// These arguments are shared across all view subcommands (tasks, contracts, files).
#[derive(Args, Debug, Clone)]
pub struct ViewArgs {
    /// API URL for the makima server
    #[arg(long, env = "MAKIMA_API_URL", default_value = "https://api.makima.jp")]
    pub api_url: String,

    /// API key for authentication
    #[arg(long, env = "MAKIMA_API_KEY")]
    pub api_key: String,

    /// Contract ID to filter results (optional)
    ///
    /// When specified, only shows items belonging to this contract.
    #[arg(long, env = "MAKIMA_CONTRACT_ID")]
    pub contract_id: Option<Uuid>,

    /// Initial search query
    ///
    /// Pre-populates the search field with this query when the TUI opens.
    #[arg(index = 1)]
    pub query: Option<String>,

    /// Disable the preview pane
    ///
    /// Shows only the item list without the side preview panel.
    /// Useful for smaller terminal windows.
    #[arg(long)]
    pub no_preview: bool,

    /// Sort order for results
    ///
    /// - `recent`: Sort by last updated time (default)
    /// - `name`: Sort alphabetically by name
    /// - `status`: Group by status, then by name
    #[arg(long, default_value = "recent")]
    pub sort: String,
}