mrapids 0.1.31

use clap::{Parser, Subcommand};
use std::path::PathBuf;

#[derive(Parser)]
#[command(name = "mrapids")]
#[command(about = "Your OpenAPI, but executable", long_about = None)]
#[command(version)]
#[command(before_help = crate::core::banner::get_help_header())]
#[command(after_help = get_help_footer())]
#[command(override_help = get_grouped_help())]
pub struct Args {
    #[command(subcommand)]
    pub command: Commands,

    /// Global: Environment name (dev, staging, prod)
    #[arg(long, global = true, value_name = "ENV")]
    pub env: Option<String>,

    /// Global: Output format (json, yaml, table, pretty)
    #[arg(long = "output-format", global = true, value_name = "FORMAT")]
    pub output_format: Option<String>,

    /// Global: Suppress all output except errors
    #[arg(long, short = 'q', global = true)]
    pub quiet: bool,

    /// Global: Enable verbose output
    #[arg(long, short = 'v', global = true)]
    pub verbose: bool,

    /// Global: Enable trace output (includes HTTP requests/responses)
    #[arg(long, global = true)]
    pub trace: bool,

    /// Global: Disable colored output
    #[arg(long, global = true)]
    pub no_color: bool,

    /// Global: Output as JSON (agent-friendly structured output)
    #[arg(long, global = true, help_heading = "Agent Automation")]
    pub json: bool,

    /// Global: Machine-readable mode (no colors, no decorations, structured output)
    #[arg(long, global = true, help_heading = "Agent Automation")]
    pub machine: bool,
}

#[derive(Subcommand)]
pub enum Commands {
    // === GETTING STARTED ===
    /// Initialize a new MicroRapid project from OpenAPI/GraphQL specs
    #[command(display_order = 1)]
    Init(InitCommand),

    /// Discover what operations are available in your API
    #[command(alias = "search", alias = "discover", display_order = 2)]
    Explore(ExploreCommand),

    /// Show detailed information about specific operations
    #[command(display_order = 3)]
    Show(ShowCommand),

    /// Ensure your OpenAPI specification is correct
    #[command(display_order = 4)]
    Validate(ValidateCommand),

    // === EXECUTION & TESTING ===
    /// Execute API operations directly from specifications
    #[command(display_order = 5)]
    Run(RunCommand),

    /// Run automated tests against your API
    #[command(display_order = 6)]
    Test(TestCommand),

    /// List available operations, requests, or resources
    #[command(display_order = 7)]
    List(ListCommand),

    // === CODE GENERATION ===
    /// Generate SDKs, examples, test fixtures, and code
    #[command(alias = "generate", display_order = 8)]
    Gen(GenCommand),

    /// Resolve all $ref references in your specification
    #[command(display_order = 9)]
    Flatten(FlattenCommand),

    // === AUTOMATION & WORKFLOWS ===
    /// Manage and run complex API request collections
    #[command(display_order = 10)]
    Collection(CollectionCommand),

    /// Set up complete test environment automatically
    #[command(alias = "tests-init", display_order = 11)]
    SetupTests(SetupTestsCommand),

    // === CONFIGURATION ===
    /// Comprehensive authentication management (detect, connect, validate, OAuth)
    #[command(display_order = 12)]
    Auth(AuthCommand),

    /// Manage environment configurations
    #[command(display_order = 13)]
    Env(EnvCommand),

    // === UTILITIES ===
    /// Compare specifications for breaking changes
    #[command(display_order = 14)]
    Diff(DiffCommand),

    /// Clean up test artifacts and temporary files
    #[command(display_order = 15)]
    Cleanup(CleanupCommand),

    /// Diagnose configuration, auth, spec, and environment issues with auto-fix
    #[command(display_order = 16)]
    Doctor(DoctorCommand),

    // === ANALYTICS ===
    /// Local analytics database powered by DuckDB
    #[command(display_order = 17)]
    Db(DbCommand),

    /// Query API history with SQL - your requests become a queryable database
    #[command(display_order = 18)]
    Sql(SqlCommand),

    /// Compare two API runs and identify differences (reconciliation)
    #[command(display_order = 19)]
    Compare(CompareCommand),

    /// Show API run history - see all past executions at a glance
    #[command(display_order = 20)]
    History(HistoryCommand),

    /// Export data to Parquet, CSV, or JSON for external analysis
    #[command(display_order = 21)]
    Export(ExportCommand),

    // === AGENT / SEMANTIC SEARCH ===
    /// Build and manage operation index for semantic search
    #[command(display_order = 22)]
    Index(IndexCommand),

    /// Find operations using semantic search
    #[command(display_order = 23)]
    Find(FindCommand),

    // === PLANNING ===
    /// Sketch execution plans from operations or collections (read-only, no execution)
    #[command(display_order = 25)]
    Plan(PlanCommand),

    // === SECURITY & GOVERNANCE ===
    /// Manage agent access policies (init, validate, report)
    #[command(display_order = 24)]
    Policy(PolicyCommand),

    // === MCP SERVER ===
    /// MCP (Model Context Protocol) server for AI agent integration
    #[command(display_order = 26)]
    Mcp(McpCommand),
}

#[derive(Parser)]
pub struct PolicyCommand {
    #[command(subcommand)]
    pub command: PolicySubcommand,
}

#[derive(Subcommand)]
pub enum PolicySubcommand {
    /// Generate a starter policy from your API spec
    Init {
        /// Path to the OpenAPI spec
        #[arg(long)]
        spec: Option<PathBuf>,

        /// Output path (default: .mrapids/policy.yaml)
        #[arg(long, short)]
        output: Option<PathBuf>,

        /// Read-only mode (block all writes)
        #[arg(long)]
        read_only: bool,

        /// Apply a compliance preset (hipaa, pci, sox)
        #[arg(long)]
        preset: Option<String>,
    },

    /// Validate a policy file for errors
    Validate {
        /// Path to policy file (default: auto-detect)
        #[arg(long)]
        policy: Option<PathBuf>,
    },

    /// Show a human-readable policy report
    Report {
        /// Path to policy file (default: auto-detect)
        #[arg(long)]
        policy: Option<PathBuf>,
    },
}

#[derive(Parser)]
pub struct ValidateCommand {
    /// Path to the OpenAPI/Swagger specification file
    pub spec: PathBuf,

    /// Strict mode - treat warnings as errors
    #[arg(long)]
    pub strict: bool,

    /// Enable linting for best practices and style issues
    #[arg(long)]
    pub lint: bool,

    /// Custom linting rules file
    #[arg(long, requires = "lint")]
    pub rules: Option<PathBuf>,

    /// Output format (text or json)
    #[arg(short, long, value_enum, default_value = "text")]
    pub format: ValidateFormat,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum ValidateFormat {
    /// Human-readable text format
    Text,
    /// JSON format for tooling
    Json,
}

#[derive(Parser)]
pub struct InitCommand {
    /// Project name (defaults to current directory name)
    #[arg(default_value = "my-api-project")]
    pub name: String,

    /// Project template (minimal, rest, graphql)
    #[arg(short, long, default_value = "rest")]
    pub template: String,

    /// Initialize from a URL (downloads OpenAPI/GraphQL schema)
    #[arg(long, value_name = "URL", conflicts_with = "from_file")]
    pub from_url: Option<String>,

    /// Initialize from a local file (OpenAPI/GraphQL schema)
    #[arg(long, value_name = "FILE", conflicts_with = "from_url")]
    pub from_file: Option<String>,

    /// Force overwrite if directory exists
    #[arg(short, long)]
    pub force: bool,

    /// Allow insecure HTTP connections when downloading specs (not recommended)
    #[arg(long)]
    pub allow_insecure: bool,
}

#[derive(Parser, Clone)]
#[command(
    args_override_self = true,
    after_help = "AGENT/AUTOMATION:
    --json-output     Structured JSON with run_id, metadata, request/response
    --machine         No colors, no decorations
    Exit codes:       0=success  2=args  3=auth  4=network  5=rate-limit  7=validation

WORKFLOW:
    mrapids run <operation> -Q                   # See parameters + copy-ready command
    mrapids run <operation> --param key=value    # Execute with parameters
    mrapids run <operation> --json-output        # JSON for scripts/agents

COPY-READY EXAMPLES:
    # 1. Discover what parameters an operation needs
    mrapids run getPetById -Q

    # 2. Execute GET with path/query parameters
    mrapids run getPetById --param petId=1

    # 3. Execute POST with JSON body
    mrapids run createUser --data '{\"name\": \"john\", \"email\": \"john@example.com\"}'

    # 4. Use saved auth profile
    mrapids run getProfile --profile github

    # 5. JSON output for scripts/agents
    mrapids run listUsers --param limit=10 --json-output

    # 6. Preview as curl (don't send)
    mrapids run getUser --param id=123 --as-curl

    # 7. Dry run (preview request without sending)
    mrapids run createOrder --data @order.json --dry-run

TIPS:
    • Parameters are auto URL-encoded - pass plain text
    • Use quotes for spaces: --param q=\"status:active type:user\"
    • Read body from file: --data @request.json or --file request.json
    • Save response: --save response.json"
)]
pub struct RunCommand {
    /// Operation ID (e.g., users/get, repos/create) or path to request config file
    #[arg(required_unless_present_any = ["list_queries", "load_query"])]
    pub operation: Option<String>,

    /// Path to OpenAPI/Swagger specification file (auto-detected if not provided)
    #[arg(
        short = 's',
        long,
        value_name = "FILE",
        help_heading = "Spec Selection"
    )]
    pub spec: Option<PathBuf>,

    // === DATA INPUT ===
    /// Request body as JSON string or @file.json
    #[arg(short, long, conflicts_with = "file", help_heading = "Data Input")]
    pub data: Option<String>,

    /// Read request body from file
    #[arg(short, long, conflicts_with = "data", help_heading = "Data Input")]
    pub file: Option<PathBuf>,

    // === COMMON PARAMETERS ===
    /// Resource ID (auto-mapped to path/query parameters)
    #[arg(long, help_heading = "Common Parameters")]
    pub id: Option<String>,

    /// Resource name
    #[arg(long, help_heading = "Common Parameters")]
    pub name: Option<String>,

    /// Filter by status
    #[arg(long, help_heading = "Common Parameters")]
    pub status: Option<String>,

    /// Limit number of results
    #[arg(long, help_heading = "Common Parameters")]
    pub limit: Option<u32>,

    /// Offset for pagination
    #[arg(long, help_heading = "Common Parameters")]
    pub offset: Option<u32>,

    /// Sort order
    #[arg(long, help_heading = "Common Parameters")]
    pub sort: Option<String>,

    // === REQUEST PARAMETERS ===
    /// Set any parameter: --param key=value (can be used multiple times)
    #[arg(
        long = "param",
        value_name = "KEY=VALUE",
        help_heading = "Request Parameters"
    )]
    pub params: Vec<String>,

    /// Force query parameters: --query key=value (can be used multiple times)
    #[arg(
        long = "query",
        value_name = "KEY=VALUE",
        help_heading = "Request Parameters"
    )]
    pub query_params: Vec<String>,

    /// Add HTTP headers: --header "Key: Value" (can be used multiple times)
    #[arg(
        short = 'H',
        long = "header",
        value_name = "KEY: VALUE",
        help_heading = "Request Parameters"
    )]
    pub headers: Vec<String>,

    // === AUTHENTICATION ===
    /// Bearer token or Basic auth (e.g., "Bearer token123" or "Basic base64")
    #[arg(long, conflicts_with = "auth_profile", help_heading = "Authentication")]
    pub auth: Option<String>,

    /// API key for X-API-Key header
    #[arg(long, conflicts_with = "auth_profile", help_heading = "Authentication")]
    pub api_key: Option<String>,

    /// Use saved OAuth/auth profile
    #[arg(long = "profile", value_name = "PROFILE", conflicts_with_all = &["auth", "api_key"], help_heading = "Authentication")]
    pub auth_profile: Option<String>,

    /// Environment to use (dev, staging, prod)
    #[arg(short, long)]
    pub env: Option<String>,

    /// Base URL to override default
    #[arg(short, long)]
    pub url: Option<String>,

    /// Output format (json, yaml, table, pretty)
    #[arg(short, long, default_value = "pretty")]
    pub output: String,

    /// Save response to file
    #[arg(long)]
    pub save: Option<PathBuf>,

    /// Use template file
    #[arg(long)]
    pub template: Option<String>,

    /// Set template variables: --set key=value (can be used multiple times)
    #[arg(long = "set", value_name = "KEY=VALUE")]
    pub template_vars: Vec<String>,

    // === OUTPUT & DEBUGGING ===
    /// Use only required fields in requests
    #[arg(long, help_heading = "Testing & Debugging")]
    pub required_only: bool,

    /// Show detailed request/response info
    #[arg(short, long, help_heading = "Testing & Debugging")]
    pub verbose: bool,

    /// Preview request without sending
    #[arg(long, help_heading = "Testing & Debugging")]
    pub dry_run: bool,

    /// Show equivalent curl command
    #[arg(long, help_heading = "Testing & Debugging")]
    pub as_curl: bool,

    /// Log decision records for debugging agent behavior
    /// Saves to ~/.mrapids/decisions.jsonl
    #[arg(long, help_heading = "Testing & Debugging")]
    pub log_decisions: bool,

    /// Edit generated data before sending
    #[arg(long, help_heading = "Data Input")]
    pub edit: bool,

    /// Read request body from stdin
    #[arg(long, help_heading = "Data Input")]
    pub stdin: bool,

    // === REQUEST OPTIONS ===
    /// Number of retries for failed requests
    #[arg(long, default_value = "0", help_heading = "Request Options")]
    pub retry: u32,

    /// Request timeout in seconds
    #[arg(long, default_value = "30", help_heading = "Request Options")]
    pub timeout: u32,

    /// Allow insecure HTTPS connections (skip certificate validation)
    #[arg(long, help_heading = "Security")]
    pub allow_insecure: bool,

    /// Allow connections to localhost and private IPs (for development)
    #[arg(long, help_heading = "Security")]
    pub allow_localhost: bool,

    /// Suppress warnings about sensitive data in requests
    #[arg(long, help_heading = "Security")]
    pub no_warnings: bool,

    /// Redact sensitive data (passwords, tokens, SSN, cards) from responses
    #[arg(long, help_heading = "Security")]
    pub redact: bool,

    // === INTERACTIVE MODE ===
    /// Generate interactive template (saves to file for editing)
    #[arg(short = 'i', long, conflicts_with_all = &["data", "file", "stdin"], help_heading = "Interactive Mode")]
    pub interactive: bool,

    /// Save template with custom filename (used with -i)
    #[arg(
        long,
        requires = "interactive",
        value_name = "FILE",
        help_heading = "Interactive Mode"
    )]
    pub save_as: Option<PathBuf>,

    /// Include only required fields in template
    #[arg(long, requires = "interactive", help_heading = "Interactive Mode")]
    pub minimal: bool,

    // === QUERY ASSISTANCE ===
    /// Show query syntax help for filter parameters
    #[arg(long, help_heading = "Query Assistance")]
    pub help_query: bool,

    /// Show parameters and ready-to-copy command for an operation (spec-driven)
    #[arg(short = 'Q', long, conflicts_with_all = &["data", "file", "stdin", "interactive"], help_heading = "Query Assistance")]
    pub build_query: bool,

    /// Load query from file
    #[arg(long, value_name = "FILE", help_heading = "Query Assistance")]
    pub query_file: Option<PathBuf>,

    /// Replay last successful query for this operation
    #[arg(long, help_heading = "Query Assistance")]
    pub replay_last: bool,

    /// Save current query parameters for reuse (e.g., --save-query active-users)
    #[arg(long, value_name = "NAME", help_heading = "Query Assistance")]
    pub save_query: Option<String>,

    /// Load and run a previously saved query (e.g., --load-query active-users)
    #[arg(long, value_name = "NAME", help_heading = "Query Assistance")]
    pub load_query: Option<String>,

    /// List all saved queries
    #[arg(long, help_heading = "Query Assistance")]
    pub list_queries: bool,

    // === COLLECTION SAVE ===
    /// Save successful request to a collection
    #[arg(long, help_heading = "Collection Management")]
    pub save_to_collection: bool,

    /// Collection name to save to (default: daily-YYYY-MM-DD)
    #[arg(long, value_name = "NAME", help_heading = "Collection Management")]
    pub collection: Option<String>,

    /// Custom name for the saved request
    #[arg(
        long,
        value_name = "NAME",
        requires = "save_to_collection",
        help_heading = "Collection Management"
    )]
    pub save_as_request: Option<String>,

    // === AGENT AUTOMATION ===
    /// Output as JSON (agent-friendly structured output with run_id, metadata)
    #[arg(long, help_heading = "Agent Automation")]
    pub json_output: bool,
}

#[derive(Parser)]
pub struct TestCommand {
    /// Path to the OpenAPI specification file
    pub spec: PathBuf,

    /// Test all operations
    #[arg(long)]
    pub all: bool,

    /// Specific operation to test
    #[arg(short, long)]
    pub operation: Option<String>,

    /// Automatically clean up test artifacts after completion
    #[arg(long, default_value = "true")]
    pub cleanup: bool,

    /// Keep test artifacts even after cleanup (for debugging)
    #[arg(long)]
    pub keep_artifacts: bool,

    /// Allow insecure HTTP connections (not recommended)
    #[arg(long)]
    pub allow_insecure: bool,

    /// Suppress security warnings about request content
    #[arg(long)]
    pub no_warnings: bool,
}

// Still used internally by gen snippets
#[derive(Parser)]
pub struct AnalyzeCommand {
    /// Path to the OpenAPI/Swagger specification file
    pub spec: Option<PathBuf>,

    /// Analyze specific operation only
    #[arg(short, long)]
    pub operation: Option<String>,

    /// Output directory for generated examples (defaults to current directory)
    #[arg(short = 'd', long, default_value = ".")]
    pub output: PathBuf,

    /// Generate examples for all operations
    #[arg(long)]
    pub all: bool,

    /// Skip generating data files for request bodies
    #[arg(long)]
    pub skip_data: bool,

    /// Skip OpenAPI validation
    #[arg(long)]
    pub skip_validate: bool,

    /// Overwrite existing files
    #[arg(short, long)]
    pub force: bool,

    /// Clean up old backup directories after analysis
    #[arg(long, default_value = "true")]
    pub cleanup_backups: bool,
}

#[derive(Parser)]
pub struct ListCommand {
    /// What to list: operations, requests, or all
    #[arg(value_enum, default_value = "operations")]
    pub resource: ListResource,

    /// Path to OpenAPI specification file (optional)
    pub spec: Option<PathBuf>,

    /// Filter results by text
    #[arg(short, long)]
    pub filter: Option<String>,

    /// Filter by HTTP method
    #[arg(short, long)]
    pub method: Option<String>,

    /// Filter by tag (for operations)
    #[arg(short, long)]
    pub tag: Option<String>,

    /// Output format
    #[arg(long, value_enum, default_value = "table")]
    pub format: ListFormat,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum ListResource {
    /// List operations from API spec
    Operations,
    /// List saved request configurations
    Requests,
    /// List all resources
    All,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum ListFormat {
    /// Table format with borders
    Table,
    /// Simple list format
    Simple,
    /// JSON output
    Json,
    /// YAML output
    Yaml,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum GenerateTarget {
    /// TypeScript/JavaScript with Fetch API
    Typescript,
    /// Python with Requests
    Python,
    /// Go with net/http
    Go,
    /// Rust with reqwest
    Rust,
    /// Java with OkHttp
    Java,
    /// C# with HttpClient
    Csharp,
    /// Ruby with Net::HTTP
    Ruby,
    /// PHP with Guzzle
    Php,
    /// Swift with URLSession
    Swift,
    /// Kotlin with Ktor
    Kotlin,
    /// cURL commands
    Curl,
    /// Postman collection
    Postman,
}

#[derive(Parser)]
pub struct SetupTestsCommand {
    /// Path to the OpenAPI/Swagger specification file
    pub spec: PathBuf,

    /// Output format for test setup
    #[arg(short, long, value_enum, default_value = "npm")]
    pub format: TestSetupFormat,

    /// Output directory or file
    #[arg(short, long, default_value = ".")]
    pub output: PathBuf,

    /// Overwrite existing files
    #[arg(long)]
    pub force: bool,

    /// Show what would be generated without creating files
    #[arg(long)]
    pub dry_run: bool,

    /// Include example usage in generated files
    #[arg(long)]
    pub with_examples: bool,

    /// Generate .env.example file
    #[arg(long)]
    pub with_env: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum TestSetupFormat {
    /// NPM package.json with scripts (cross-platform)
    Npm,
    /// Makefile for Unix/Mac
    Make,
    /// Shell script for automation
    Shell,
    /// Docker Compose for containers
    Compose,
    /// Direct cURL commands (no mrapids needed)
    Curl,
    /// Generate all formats
    All,
}

#[derive(Parser)]
pub struct CleanupCommand {
    /// Clean all test artifacts in current directory
    #[arg(long, default_value = "true")]
    pub test_artifacts: bool,

    /// Clean empty directories
    #[arg(long, default_value = "true")]
    pub empty_dirs: bool,

    /// Clean backup directories (.backup, .old, etc)
    #[arg(long, default_value = "true")]
    pub backups: bool,

    /// Preserve directories containing spec files
    #[arg(long, default_value = "true")]
    pub preserve_specs: bool,

    /// Target directory to clean (defaults to current directory)
    #[arg(short, long, default_value = ".")]
    pub path: PathBuf,

    /// Dry run - show what would be deleted without actually deleting
    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Parser)]
pub struct DoctorCommand {
    /// Automatically fix issues where possible
    #[arg(long)]
    pub fix: bool,

    /// Check specific aspect (all, config, auth, spec, env)
    #[arg(long, default_value = "all")]
    pub check: String,

    /// Path to project directory (defaults to current directory)
    #[arg(short, long, default_value = ".")]
    pub path: PathBuf,

    /// Output format (text, json)
    #[arg(short, long, default_value = "text")]
    pub format: String,

    /// Verbose output with more details
    #[arg(short, long)]
    pub verbose: bool,
}

#[derive(Parser)]
pub struct ShowCommand {
    /// Operation to show details for (e.g., create-customer, list-users)
    pub operation: String,

    /// Path to the API specification file
    pub spec: Option<PathBuf>,

    /// Show examples for the operation
    #[arg(long)]
    pub examples: bool,

    /// Generate and display JSON template for the operation
    #[arg(long)]
    pub template: bool,

    /// Output format
    #[arg(short, long, value_enum, default_value = "pretty")]
    pub format: ShowFormat,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum ShowFormat {
    /// Human-readable format with colors
    Pretty,
    /// JSON output
    Json,
    /// YAML output
    Yaml,
}

#[derive(Parser)]
pub struct ExploreCommand {
    /// Keyword to search for in operations, paths, and descriptions
    pub keyword: String,

    /// Path to the API specification file (defaults to specs/api.yaml)
    #[arg(short, long)]
    pub spec: Option<PathBuf>,

    /// Maximum number of results to show per category
    #[arg(short, long, default_value = "5")]
    pub limit: usize,

    /// Show detailed results including descriptions
    #[arg(long)]
    pub detailed: bool,

    /// Output format
    #[arg(short, long, value_enum, default_value = "pretty")]
    pub format: ExploreFormat,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum ExploreFormat {
    /// Human-readable format with colors and grouping
    Pretty,
    /// Simple list format
    Simple,
    /// JSON output for machine processing
    Json,
}

#[derive(Parser)]
pub struct AuthCommand {
    #[command(subcommand)]
    pub command: AuthCommands,
}

#[derive(Parser)]
pub struct EnvCommand {
    #[command(subcommand)]
    pub command: EnvCommands,
}

#[derive(Subcommand)]
pub enum EnvCommands {
    /// List all available environments
    List {
        /// Show detailed information including config files and env files
        #[arg(short, long)]
        verbose: bool,
    },

    /// Show details about a specific environment
    Show {
        /// Environment name
        environment: String,

        /// Show full configuration (including resolved variables)
        #[arg(short, long)]
        full: bool,
    },

    /// Create a new environment configuration
    Create {
        /// Environment name
        name: String,

        /// Copy from existing environment
        #[arg(long)]
        from: Option<String>,

        /// Base URL for the environment
        #[arg(long)]
        base_url: Option<String>,
    },

    /// Validate environment configurations
    Validate {
        /// Specific environment to validate (or all if not specified)
        environment: Option<String>,
    },
}

#[derive(Subcommand)]
pub enum AuthCommands {
    /// Login to an OAuth provider
    Login {
        /// Provider name (github, google, microsoft, etc.) or 'custom' for custom provider
        provider: String,

        /// Client ID (required for custom providers)
        #[arg(long)]
        client_id: Option<String>,

        /// Client Secret (for custom providers)
        #[arg(long)]
        client_secret: Option<String>,

        /// Authorization URL (required for custom providers)
        #[arg(long)]
        auth_url: Option<String>,

        /// Token URL (required for custom providers)
        #[arg(long)]
        token_url: Option<String>,

        /// OAuth scopes to request (space-separated)
        #[arg(long, value_delimiter = ' ')]
        scopes: Vec<String>,

        /// Profile name (defaults to provider name)
        #[arg(long)]
        profile: Option<String>,

        /// Show provider-specific setup instructions
        #[arg(long)]
        setup_help: bool,
    },

    /// List stored auth profiles
    List {
        /// Show detailed information
        #[arg(long)]
        detailed: bool,
    },

    /// Show auth profile details
    Show {
        /// Profile name to show
        profile: String,

        /// Show decrypted tokens (security warning)
        #[arg(long)]
        show_tokens: bool,
    },

    /// Refresh tokens for a profile
    Refresh {
        /// Profile name to refresh
        profile: String,
    },

    /// Remove auth profile
    Logout {
        /// Profile name to remove
        profile: String,

        /// Skip confirmation prompt
        #[arg(long)]
        force: bool,
    },

    /// Test authentication by making a simple API call
    Test {
        /// Profile name to test
        profile: String,
    },

    /// Show setup instructions for a provider
    Setup {
        /// Provider name (github, google, microsoft, etc.)
        provider: String,
    },

    /// Detect and analyze authentication requirements from OpenAPI spec
    Detect {
        /// Path to OpenAPI specification file
        #[arg(short, long)]
        spec: Option<String>,

        /// Output format
        #[arg(short, long, value_enum, default_value = "table")]
        format: DetectOutputFormat,

        /// Show detailed operation-level requirements
        #[arg(long)]
        operations: bool,

        /// Show only summary without scheme details
        #[arg(long)]
        summary_only: bool,
    },

    /// Connect and configure authentication credentials
    Connect {
        /// Authentication scheme name from OpenAPI spec
        scheme: String,

        /// Auth type (api-key, bearer, basic, oauth2, oidc, mtls)
        #[arg(short = 't', long)]
        auth_type: Option<String>,

        /// API key value (for api-key type)
        #[arg(long, conflicts_with_all = &["token", "username"])]
        api_key: Option<String>,

        /// Bearer token (for bearer type)
        #[arg(long, conflicts_with_all = &["api_key", "username"])]
        token: Option<String>,

        /// Username (for basic auth)
        #[arg(long, requires = "password", conflicts_with_all = &["api_key", "token"])]
        username: Option<String>,

        /// Password (for basic auth)
        #[arg(long, requires = "username")]
        password: Option<String>,

        /// OAuth2 flow type
        #[arg(long, value_enum)]
        flow: Option<OAuth2FlowType>,

        /// Client ID (for OAuth2)
        #[arg(long)]
        client_id: Option<String>,

        /// Client secret (for OAuth2)
        #[arg(long)]
        client_secret: Option<String>,

        /// Scopes to request (for OAuth2)
        #[arg(long)]
        scopes: Option<String>,

        /// Non-interactive mode (fail if input needed)
        #[arg(long)]
        non_interactive: bool,

        /// Force overwrite existing configuration
        #[arg(short, long)]
        force: bool,

        /// Environment to save credentials to (default: local)
        #[arg(short, long, default_value = "local")]
        env: String,
    },

    /// Validate configured authentication credentials
    Validate {
        /// Specific scheme to validate (validates all if not specified)
        #[arg(short, long)]
        scheme: Option<String>,

        /// OpenAPI specification file
        #[arg(long)]
        spec: Option<String>,

        /// Test endpoint to validate against
        #[arg(short = 'e', long)]
        endpoint: Option<String>,

        /// Show detailed validation output
        #[arg(short, long)]
        verbose: bool,

        /// Enable debug mode for troubleshooting
        #[arg(long)]
        debug: bool,

        /// Perform quick validation (skip endpoint tests)
        #[arg(short, long)]
        quick: bool,
    },
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum DetectOutputFormat {
    /// Human-readable table format
    Table,
    /// JSON format for programmatic consumption
    Json,
    /// YAML format for configuration files
    Yaml,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum OAuth2FlowType {
    /// Client credentials flow
    ClientCredentials,
    /// Authorization code flow
    AuthorizationCode,
    /// Device code flow
    DeviceCode,
    /// Password flow (deprecated)
    Password,
}

#[derive(Parser)]
pub struct FlattenCommand {
    /// Path to the OpenAPI/Swagger specification file
    pub spec: PathBuf,

    /// Output file path (defaults to stdout if not specified)
    #[arg(short, long)]
    pub output: Option<PathBuf>,

    /// Output format (json or yaml)
    #[arg(short, long, value_enum, default_value = "yaml")]
    pub format: FlattenFormat,

    /// Include schemas that are not referenced
    #[arg(long)]
    pub include_unused: bool,

    /// Resolve external references (http:// or file paths)
    #[arg(long)]
    pub resolve_external: bool,

    /// Allow insecure HTTP connections when resolving external references (not recommended)
    #[arg(long)]
    pub allow_insecure: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum FlattenFormat {
    /// YAML format
    Yaml,
    /// JSON format  
    Json,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum SdkLanguage {
    /// TypeScript (fetch-based)
    Typescript,
    /// Python (httpx-based)
    Python,
    /// Go (net/http-based)
    Go,
    /// Rust (reqwest-based)
    Rust,
}

#[derive(Parser)]
pub struct DiffCommand {
    /// Path to the old OpenAPI/Swagger specification file
    pub old_spec: PathBuf,

    /// Path to the new OpenAPI/Swagger specification file  
    pub new_spec: PathBuf,

    /// Only show breaking changes
    #[arg(long, alias = "breaking")]
    pub breaking_only: bool,

    /// Output format (text, json, markdown)
    #[arg(short, long, value_enum, default_value = "text")]
    pub format: DiffFormat,

    /// Exit with non-zero code if breaking changes found
    #[arg(long)]
    pub fail_on_breaking: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum DiffFormat {
    /// Human-readable text format
    Text,
    /// JSON format for tooling
    Json,
    /// Markdown format for PRs
    Markdown,
}

#[derive(Parser)]
pub struct GenCommand {
    #[command(subcommand)]
    pub target: GenTarget,
}

#[derive(Subcommand)]
pub enum GenTarget {
    /// Generate example requests and responses (replaces 'analyze')
    Snippets(GenSnippetsCommand),

    /// Generate SDK client library (replaces 'sdk')
    Sdk(GenSdkCommand),

    /// Generate server stubs (replaces 'generate')
    Stubs(GenStubsCommand),

    /// Generate test fixtures and sample data
    Fixtures(GenFixturesCommand),
}

#[derive(Parser)]
pub struct GenSnippetsCommand {
    /// Path to the OpenAPI specification
    pub spec: Option<PathBuf>,

    /// Output directory for examples
    #[arg(short, long, default_value = "./examples")]
    pub output: PathBuf,

    /// Operation ID to generate examples for (all if not specified)
    #[arg(long)]
    pub operation: Option<String>,

    /// Example format
    #[arg(long, value_enum, default_value = "json")]
    pub format: SnippetFormat,

    /// Include curl examples
    #[arg(long)]
    pub curl: bool,

    /// Include HTTPie examples
    #[arg(long)]
    pub httpie: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum SnippetFormat {
    Json,
    Yaml,
    Curl,
    Httpie,
    All,
}

#[derive(Parser)]
pub struct GenSdkCommand {
    /// Path to the OpenAPI specification
    pub spec: Option<PathBuf>,

    /// Target language
    #[arg(short, long, value_enum)]
    pub language: SdkLanguage,

    /// Output directory
    #[arg(short, long)]
    pub output: Option<PathBuf>,

    /// Package name
    #[arg(long)]
    pub package: Option<String>,

    /// Include documentation
    #[arg(long, default_value = "true")]
    pub docs: bool,

    /// Include examples
    #[arg(long, default_value = "true")]
    pub examples: bool,
}

#[derive(Parser)]
pub struct GenStubsCommand {
    /// Path to the OpenAPI specification
    pub spec: Option<PathBuf>,

    /// Target framework
    #[arg(short, long)]
    pub framework: String,

    /// Output directory
    #[arg(short, long)]
    pub output: Option<PathBuf>,

    /// Include tests
    #[arg(long)]
    pub with_tests: bool,

    /// Include validation
    #[arg(long)]
    pub with_validation: bool,
}

#[derive(Parser)]
pub struct GenFixturesCommand {
    /// Path to the OpenAPI specification
    pub spec: Option<PathBuf>,

    /// Output directory
    #[arg(short, long, default_value = "./fixtures")]
    pub output: PathBuf,

    /// Number of samples per schema
    #[arg(long, default_value = "10")]
    pub count: u32,

    /// Specific schemas to generate (all if not specified)
    #[arg(long)]
    pub schema: Vec<String>,

    /// Random seed for deterministic output
    #[arg(long)]
    pub seed: Option<u64>,

    /// Output format
    #[arg(long, value_enum, default_value = "json")]
    pub format: FixtureFormat,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum FixtureFormat {
    Json,
    Yaml,
    Csv,
}

#[derive(Parser)]
pub struct CollectionCommand {
    #[command(subcommand)]
    pub command: CollectionSubcommand,
}

#[derive(Parser)]
pub struct DbCommand {
    #[command(subcommand)]
    pub command: DbSubcommand,
}

#[derive(Subcommand)]
pub enum DbSubcommand {
    /// Show database status and statistics
    Status {
        /// Show detailed information
        #[arg(short, long)]
        verbose: bool,
    },

    /// Display the database schema (tables and columns)
    Schema {
        /// Show specific table only
        #[arg(short, long)]
        table: Option<String>,

        /// Output format (table, json, sql)
        #[arg(short, long, value_enum, default_value = "table")]
        format: DbSchemaFormat,
    },

    /// Run a SQL query against the analytics database
    Query {
        /// SQL query to execute
        sql: String,

        /// Output format (json, table)
        #[arg(short, long, value_enum, default_value = "table")]
        format: DbOutputFormat,
    },

    /// Show API request statistics
    Stats {
        /// Filter by spec file
        #[arg(long)]
        spec: Option<String>,

        /// Filter by operation ID
        #[arg(long)]
        operation: Option<String>,

        /// Time range (today, week, month, all)
        #[arg(long, default_value = "all")]
        range: String,
    },

    /// List recent API runs
    Runs {
        /// Number of runs to show
        #[arg(short, long, default_value = "10")]
        limit: usize,

        /// Output format (json, table)
        #[arg(short, long, value_enum, default_value = "table")]
        format: DbOutputFormat,
    },

    /// Show details of a specific run
    Run {
        /// Run ID to show details for
        run_id: String,

        /// Output format (json, table)
        #[arg(short, long, value_enum, default_value = "table")]
        format: DbOutputFormat,
    },

    /// Show details of a specific request
    Request {
        /// Request ID to show details for
        request_id: String,

        /// Output format (json, table)
        #[arg(short, long, value_enum, default_value = "json")]
        format: DbOutputFormat,
    },

    /// Reset/clear the analytics database
    Reset {
        /// Skip confirmation prompt
        #[arg(short, long)]
        force: bool,
    },

    /// Run health checks on the database
    Check {
        /// Output format (text, json)
        #[arg(short, long, value_enum, default_value = "text")]
        format: DbCheckFormat,

        /// Fix issues automatically if possible
        #[arg(long)]
        fix: bool,
    },

    /// Show migration history and current schema version
    Migrations,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum DbCheckFormat {
    /// Human-readable text output
    Text,
    /// JSON output for automation
    Json,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum DbOutputFormat {
    /// JSON output
    Json,
    /// Table format
    Table,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum DbSchemaFormat {
    /// Table format with columns
    Table,
    /// JSON output
    Json,
    /// SQL CREATE statements
    Sql,
}

/// SQL command for querying API history
#[derive(Parser)]
#[command(after_help = "EXAMPLES:
    # Run inline SQL query
    mrapids sql \"SELECT count(*) FROM responses\"
    mrapids sql \"SELECT * FROM runs\" --json

    # Save a query for reuse
    mrapids sql save slow-requests \"SELECT * FROM responses WHERE duration_ms > 1000\"

    # Run a saved query
    mrapids sql run slow-requests
    mrapids sql run slow-requests --csv

    # List saved queries
    mrapids sql list

AVAILABLE TABLES:
    runs       - API execution sessions (run_id, timestamp, status, duration_ms)
    requests   - Request details (request_id, method, endpoint, url, headers)
    responses  - Response details (status_code, body, duration_ms, success)")]
pub struct SqlCommand {
    #[command(subcommand)]
    pub command: Option<SqlSubcommand>,

    /// SQL query to execute (when not using subcommand)
    pub query: Option<String>,

    /// Output as JSON
    #[arg(long, conflicts_with_all = &["csv", "table"])]
    pub json: bool,

    /// Output as CSV
    #[arg(long, conflicts_with_all = &["json", "table"])]
    pub csv: bool,

    /// Output as table (default)
    #[arg(long, conflicts_with_all = &["json", "csv"])]
    pub table: bool,

    /// Don't print column headers
    #[arg(long)]
    pub no_header: bool,
}

#[derive(Subcommand)]
pub enum SqlSubcommand {
    /// Save a query for later use
    Save {
        /// Name for the saved query (without .sql extension)
        name: String,

        /// SQL query to save
        query: String,

        /// Description of what this query does
        #[arg(short, long)]
        description: Option<String>,
    },

    /// Run a saved query
    Run {
        /// Name of the saved query
        name: String,

        /// Output as JSON
        #[arg(long, conflicts_with_all = &["csv", "table"])]
        json: bool,

        /// Output as CSV
        #[arg(long, conflicts_with_all = &["json", "table"])]
        csv: bool,

        /// Output as table (default)
        #[arg(long, conflicts_with_all = &["json", "csv"])]
        table: bool,

        /// Don't print column headers
        #[arg(long)]
        no_header: bool,
    },

    /// List all saved queries
    List,

    /// Delete a saved query
    Delete {
        /// Name of the query to delete
        name: String,

        /// Skip confirmation
        #[arg(short, long)]
        force: bool,
    },
}

/// Compare two API runs for differences (reconciliation)
#[derive(Parser)]
#[command(
    about = "Compare two API runs and identify differences",
    long_about = r#"Compare two API runs side-by-side to identify differences.

This is useful for:
- Comparing legacy vs new API implementations
- Detecting regressions between deployments
- Validating API migrations

The comparison identifies:
- Status code differences
- Response body changes
- Missing/new endpoints
- Performance variations

Examples:
  mrapids compare --left abc123 --right def456
  mrapids compare --left abc123 --right def456 --json
  mrapids compare --left abc123 --right def456 --ignore-headers"#
)]
pub struct CompareCommand {
    /// Left (baseline) run ID
    #[arg(long)]
    pub left: String,

    /// Right (comparison) run ID
    #[arg(long)]
    pub right: String,

    /// Output as JSON
    #[arg(long)]
    pub json: bool,

    /// Ignore header differences
    #[arg(long)]
    pub ignore_headers: bool,

    /// Ignore timing differences
    #[arg(long)]
    pub ignore_timing: bool,

    /// Only show breaking changes (status code changes, missing fields)
    #[arg(long)]
    pub breaking_only: bool,
}

/// Show API run history
#[derive(Parser)]
#[command(
    about = "Show API run history",
    long_about = r#"Display a history of all API runs stored in the local database.

Shows run ID, timestamp, spec file, request counts, duration, and status.

Examples:
  mrapids history
  mrapids history --limit 20
  mrapids history --json"#
)]
pub struct HistoryCommand {
    /// Maximum number of runs to display
    #[arg(short, long, default_value = "10")]
    pub limit: usize,

    /// Output as JSON
    #[arg(long)]
    pub json: bool,

    /// Show only runs from a specific spec file
    #[arg(long)]
    pub spec: Option<String>,

    /// Show only failed runs
    #[arg(long)]
    pub failed: bool,
}

/// Export format options
#[derive(Clone, Debug, clap::ValueEnum)]
pub enum ExportFormat {
    Parquet,
    Csv,
    Json,
}

/// Export data to various formats
#[derive(Parser)]
#[command(
    about = "Export data to Parquet, CSV, or JSON",
    long_about = r#"Export DuckDB tables to external file formats for analysis in other tools.

Supported formats:
- parquet: Columnar format, ideal for analytics (Spark, DuckDB, Pandas)
- csv: Universal format for spreadsheets and data tools
- json: JSON array format for web applications

Examples:
  mrapids export --table responses --format parquet
  mrapids export --table runs --format csv --output runs.csv
  mrapids export --query "SELECT * FROM responses WHERE status_code >= 400" --format json"#
)]
pub struct ExportCommand {
    /// Table to export (runs, requests, responses, comparisons, comparison_diffs)
    #[arg(long, conflicts_with = "query")]
    pub table: Option<String>,

    /// Custom SQL query to export
    #[arg(long, conflicts_with = "table")]
    pub query: Option<String>,

    /// Output format
    #[arg(long, short, value_enum, default_value = "parquet")]
    pub format: ExportFormat,

    /// Output file path (auto-generated if not specified)
    #[arg(long, short)]
    pub output: Option<PathBuf>,
}

#[derive(Subcommand)]
pub enum CollectionSubcommand {
    /// List available collections
    List {
        /// Directory containing collections
        #[arg(long, default_value = "collections")]
        dir: PathBuf,
    },

    /// Show details of a collection
    Show {
        /// Collection name
        name: String,

        /// Directory containing collections
        #[arg(long, default_value = "collections")]
        dir: PathBuf,
    },

    /// Validate collection syntax and operations
    Validate {
        /// Collection name
        name: String,

        /// Directory containing collections
        #[arg(long, default_value = "collections")]
        dir: PathBuf,

        /// Path to API specification
        #[arg(long)]
        spec: Option<PathBuf>,
    },

    /// Run a collection
    Run {
        /// Collection name
        name: String,

        /// Directory containing collections
        #[arg(long, default_value = "collections")]
        dir: PathBuf,

        /// Output format (json, yaml, pretty)
        #[arg(long, default_value = "pretty")]
        output: String,

        /// Save all responses to directory
        #[arg(long)]
        save_all: Option<PathBuf>,

        /// Save execution summary
        #[arg(long)]
        save_summary: Option<PathBuf>,

        /// Override variables (key=value)
        #[arg(long = "var", value_parser = parse_key_val::<String, String>)]
        variables: Vec<(String, String)>,

        /// Authentication profile to use
        #[arg(long = "profile", value_name = "PROFILE")]
        auth_profile: Option<String>,

        /// Continue execution on errors
        #[arg(long)]
        continue_on_error: bool,

        /// Run specific request(s)
        #[arg(long = "request")]
        requests: Vec<String>,

        /// Skip specific request(s)
        #[arg(long = "skip")]
        skip_requests: Vec<String>,

        /// Use environment variables
        #[arg(long)]
        use_env: bool,

        /// Path to .env file
        #[arg(long)]
        env_file: Option<PathBuf>,

        /// Path to API specification
        #[arg(long)]
        spec: Option<PathBuf>,

        /// Environment name
        #[arg(long)]
        env: Option<String>,
    },

    /// Run collection as tests
    Test {
        /// Collection name
        name: String,

        /// Directory containing collections
        #[arg(long, default_value = "collections")]
        dir: PathBuf,

        /// Path to API specification
        #[arg(long)]
        spec: Option<PathBuf>,

        /// Authentication profile to use
        #[arg(long = "profile", value_name = "PROFILE")]
        auth_profile: Option<String>,

        /// Output format (pretty, json, junit)
        #[arg(long, default_value = "pretty")]
        output: String,

        /// Continue on test failures
        #[arg(long)]
        continue_on_error: bool,
    },
}

// === PLAN COMMAND ===

/// Plan command for sketching execution plans
#[derive(Parser)]
#[command(
    about = "Sketch execution plans from operations or collections",
    long_about = r#"Generate read-only execution plan sketches showing how operations
would compose into a workflow. No side effects, no tokens, no execution.

Examples:
  mrapids plan sketch getPetById updatePet deletePet
  mrapids plan sketch --from my-collection
  mrapids plan sketch --from my-collection --format json"#
)]
pub struct PlanCommand {
    #[command(subcommand)]
    pub command: PlanSubcommand,
}

#[derive(Subcommand)]
pub enum PlanSubcommand {
    /// Generate a sketch of an execution plan (read-only, no side effects)
    Sketch {
        /// Operation IDs to include in the plan
        #[arg(required_unless_present = "from")]
        operations: Vec<String>,

        /// Build plan from a collection YAML file
        #[arg(long, value_name = "COLLECTION", conflicts_with = "operations")]
        from: Option<String>,

        /// Directory containing collections (used with --from)
        #[arg(long, default_value = "collections")]
        dir: PathBuf,

        /// Path to API specification (auto-detected if not provided)
        #[arg(long)]
        spec: Option<PathBuf>,

        /// Output format
        #[arg(long, value_enum, default_value = "text")]
        format: PlanFormat,

        /// Show execution readiness gaps (missing required params, body, auth)
        #[arg(long)]
        show_gaps: bool,
    },
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum PlanFormat {
    /// Human-readable text format with colors
    Text,
    /// JSON format for tooling
    Json,
}

// === INDEX COMMAND ===

/// Index command for building and managing operation cards
#[derive(Parser)]
#[command(
    about = "Build and manage operation index for semantic search",
    long_about = r#"Build and manage an index of API operations for semantic search.

The index stores operation cards - structured representations of API operations
that enable fast keyword and semantic search across multiple specs.

Examples:
  mrapids index build                    # Build index from current project spec
  mrapids index add ./other-api.yaml     # Add another spec to the index
  mrapids index list                     # List all indexed specs
  mrapids index status                   # Show index health and stats
  mrapids index rebuild                  # Rebuild entire index"#
)]
pub struct IndexCommand {
    #[command(subcommand)]
    pub command: IndexSubcommand,
}

#[derive(Subcommand)]
pub enum IndexSubcommand {
    /// Build index from current project spec
    Build {
        /// Path to OpenAPI spec (auto-detected if not provided)
        #[arg(long)]
        spec: Option<PathBuf>,

        /// Custom spec ID (defaults to filename)
        #[arg(long)]
        id: Option<String>,

        /// Force rebuild even if spec unchanged
        #[arg(short, long)]
        force: bool,

        /// Embedding provider (none, local, openai)
        #[arg(long, default_value = "none")]
        embed: String,
    },

    /// Add an external spec to the index
    Add {
        /// Path to OpenAPI spec file
        spec: PathBuf,

        /// Custom spec ID (defaults to filename)
        #[arg(long)]
        id: Option<String>,

        /// Force re-index even if already indexed
        #[arg(short, long)]
        force: bool,

        /// Embedding provider (none, local, openai)
        #[arg(long, default_value = "none")]
        embed: String,
    },

    /// List all indexed specs
    List {
        /// Output format
        #[arg(long, value_enum, default_value = "table")]
        format: IndexOutputFormat,
    },

    /// Show index status and health
    Status {
        /// Output format
        #[arg(long, value_enum, default_value = "table")]
        format: IndexOutputFormat,
    },

    /// Rebuild entire index
    Rebuild {
        /// Only rebuild specific spec
        #[arg(long)]
        spec: Option<String>,

        /// Embedding provider (none, local, openai)
        #[arg(long, default_value = "none")]
        embed: String,
    },

    /// Remove a spec from the index
    Remove {
        /// Spec ID to remove
        spec_id: String,

        /// Skip confirmation
        #[arg(short, long)]
        force: bool,
    },
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum IndexOutputFormat {
    /// Table format
    Table,
    /// JSON format
    Json,
}

// === FIND COMMAND ===

/// Find command for semantic search across operations
#[derive(Parser)]
#[command(
    about = "Find operations using semantic search",
    long_about = r#"Search for API operations using natural language queries.

Uses the operation index to find relevant operations based on:
- Operation IDs and paths
- Summaries and descriptions
- Parameter names and types
- Request/response schemas

Examples:
  mrapids find "create user"             # Find operations related to user creation
  mrapids find "list products" --limit 5 # Limit results
  mrapids find "auth" --spec users-api   # Search within specific spec
  mrapids find "POST" --method POST      # Filter by HTTP method
  mrapids find "update" --risk write     # Filter by risk level"#
)]
pub struct FindCommand {
    /// Search query (natural language or keywords)
    pub query: String,

    /// Maximum number of results
    #[arg(short, long, default_value = "10")]
    pub limit: usize,

    /// Filter by spec ID
    #[arg(long)]
    pub spec: Option<String>,

    /// Filter by HTTP method (GET, POST, PUT, DELETE, etc.)
    #[arg(long)]
    pub method: Option<String>,

    /// Filter by risk level (read, write)
    #[arg(long)]
    pub risk: Option<String>,

    /// Output format
    #[arg(long, value_enum, default_value = "table")]
    pub format: FindOutputFormat,

    /// Use semantic search with embeddings (requires indexed embeddings)
    #[arg(long)]
    pub semantic: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, clap::ValueEnum)]
pub enum FindOutputFormat {
    /// Human-readable table
    Table,
    /// JSON format for automation
    Json,
    /// Just operation IDs (one per line)
    Ids,
}

// === MCP COMMAND ===

/// MCP (Model Context Protocol) command for AI agent integration
#[derive(Parser)]
#[command(
    about = "MCP server for AI agent integration",
    long_about = r#"Run an MCP (Model Context Protocol) server that provides AI agents
with secure access to API operations.

SECURITY FEATURES:
  - Zero Trust: Every request validated against policies
  - Credential Isolation: AI never sees raw tokens
  - Audit Logging: Complete logging of all AI actions
  - Policy-based Access Control: Define what operations AI can perform

TOOLS PROVIDED:
  api_find      - Search for API operations using natural language
  api_run       - Execute API operations with credential injection
  api_auth      - Check authentication status

Examples:
  # Start MCP server (stdio transport for Claude Desktop)
  mrapids mcp serve

  # Start with specific policy file
  mrapids mcp serve --policy ./policy.yaml

  # Show available tools
  mrapids mcp tools

  # Test a tool locally
  mrapids mcp test api_find --query "create user""#
)]
pub struct McpCommand {
    #[command(subcommand)]
    pub command: McpSubcommand,
}

#[derive(Subcommand)]
pub enum McpSubcommand {
    /// Start the MCP server (stdio transport)
    Serve {
        /// Policy file for access control
        #[arg(long)]
        policy: Option<std::path::PathBuf>,

        /// Path to OpenAPI spec (auto-detected if not provided)
        #[arg(long)]
        spec: Option<std::path::PathBuf>,

        /// Allow connections to localhost/loopback (for local development)
        #[arg(long)]
        allow_localhost: bool,

        /// Enable debug logging to stderr
        #[arg(long)]
        debug: bool,

        /// Enable decision logging for debugging agent behavior
        /// Saves to ~/.mrapids/decisions.jsonl (or custom path)
        #[arg(long)]
        log_decisions: Option<Option<std::path::PathBuf>>,
    },

    /// Start HTTP REST server for trusted callers (Agent API)
    Http {
        /// Port to bind to
        #[arg(long, default_value = "8420")]
        port: u16,

        /// Bind address
        #[arg(long, default_value = "127.0.0.1")]
        bind: String,

        /// API key for authenticating callers (set MRAPIDS_HTTP_API_KEY env var)
        #[arg(long)]
        api_key: Option<String>,

        /// Policy file for access control
        #[arg(long)]
        policy: Option<std::path::PathBuf>,

        /// Path to OpenAPI spec
        #[arg(long)]
        spec: Option<std::path::PathBuf>,

        /// Base URL of the target API (e.g., http://localhost:8000)
        #[arg(long)]
        base_url: Option<String>,

        /// Allow connections to localhost/loopback targets
        #[arg(long)]
        allow_localhost: bool,

        /// Enable debug logging
        #[arg(long)]
        debug: bool,
    },

    /// List available MCP tools
    Tools,

    /// Test a tool locally without starting server
    Test {
        /// Tool name to test (api_find, api_run, api_auth)
        tool: String,

        /// Query for api_find
        #[arg(long)]
        query: Option<String>,

        /// Operation ID for api_run
        #[arg(long)]
        operation: Option<String>,

        /// Parameters as JSON for api_run
        #[arg(long)]
        params: Option<String>,
    },

    /// Show server status
    Status,
}

/// Parse key=value pairs
fn parse_key_val<T, U>(
    s: &str,
) -> Result<(T, U), Box<dyn std::error::Error + Send + Sync + 'static>>
where
    T: std::str::FromStr,
    T::Err: std::error::Error + Send + Sync + 'static,
    U: std::str::FromStr,
    U::Err: std::error::Error + Send + Sync + 'static,
{
    let pos = s
        .find('=')
        .ok_or_else(|| format!("invalid KEY=value: no `=` found in `{}`", s))?;
    Ok((s[..pos].parse()?, s[pos + 1..].parse()?))
}

/// Get the grouped help display with section headers
fn get_grouped_help() -> &'static str {
    r#"mrapids - Your OpenAPI, but executable

Usage: mrapids [OPTIONS] <COMMAND>

QUICK START (your first 5 minutes):
  mrapids init my-api --from-url https://api.example.com/openapi.json
  mrapids explore "user"                     # Find operations
  mrapids run <operation> -Q                 # See parameters + copy-ready command
  mrapids run <operation> --param id=123     # Execute
  mrapids history                            # See past runs
  mrapids compare --left <run1> --right <run2>   # Diff two runs

AGENT/AUTOMATION MODE:
  --json        Structured JSON output (run_id, metadata, errors)
  --machine     No colors, no decorations, parseable output
  Exit codes:   0=success  2=args  3=auth  4=network  5=rate-limit  7=validation

COMMANDS

Getting Started:
  init          Create project from OpenAPI/GraphQL spec
  explore       Search operations by keyword (aliases: search, discover)
  show          Display operation details, parameters, examples
  validate      Check spec correctness + linting
  doctor        Diagnose issues with auto-fix (--fix)

Execution:
  run           Execute API operations
                  -Q            Show parameters + copy-ready command
                  --as-curl     Output as curl command
                  --dry-run     Preview without sending
                  --json        Structured output for agents
  test          Run automated tests against your API
  list          List operations, requests, or resources

Authentication:
  auth detect   Auto-detect auth requirements from spec
  auth connect  Configure credentials (API key, Bearer, OAuth)
  auth login    OAuth flow (GitHub, Google, custom)
  auth validate Test configured credentials
  auth list     Show all auth profiles

Analytics (DuckDB-powered):
  history       Show recent API runs
  sql           Query history: mrapids sql "SELECT * FROM responses"
  compare       Diff two runs (regression/migration testing)
  export        Export to Parquet, CSV, JSON
  db status     Database stats and health

Workflows:
  collection run   Execute request sequences with dependencies
  collection test  Run collections as test suites
  setup-tests      Auto-generate test harness

Code Generation:
  gen snippets     Generate request/response examples
  gen sdk          [BETA] Generate SDK (TypeScript, Python, Go, Rust)
  gen stubs        [BETA] Generate server stubs
  gen fixtures     Generate test data from schemas
  flatten          Resolve all $ref references

Configuration:
  env list/show/create   Manage environments (dev, staging, prod)

Utilities:
  diff          Compare specs for breaking changes
  cleanup       Remove test artifacts
  help          Show help for any command

OPTIONS
      --env <ENV>               Environment (dev, staging, prod)
      --output-format <FORMAT>  Output format (json, yaml, table, pretty)
  -q, --quiet                   Suppress output except errors
  -v, --verbose                 Verbose output
      --trace                   Trace HTTP requests/responses
      --no-color                Disable colors
  -h, --help                    Print help
  -V, --version                 Print version

COPY-READY EXAMPLES:
  # 1. Initialize from remote spec
  mrapids init my-api --from-url https://petstore.swagger.io/v2/swagger.json

  # 2. Find operations
  mrapids explore "pet"

  # 3. See what parameters an operation needs
  mrapids run getPetById -Q

  # 4. Execute with parameters (JSON output for scripts)
  mrapids run getPetById --param petId=1 --json

  # 5. Query your API history
  mrapids sql "SELECT operation_id, status_code, duration_ms FROM responses LIMIT 10"

  # 6. Compare two runs (migration/regression testing)
  mrapids compare --left abc123 --right def456

More help:
  mrapids <command> --help
  mrapids auth --help
  mrapids db --help

https://microrapid.io"#
}

/// Get the help footer with examples and additional information
fn get_help_footer() -> &'static str {
    r#"
More help:  mrapids <command> --help
Docs:       https://microrapid.io"#
}