✨ feat(cli): scaffold InitCli subcommand and clap wiring

src/cli/init_cli.rs

@@ -0,0 +1,197 @@
+//! # Initialization CLI Module
+//!
+//! This module provides CLI functionality for initializing the cull-gmail application,
+//! including creating configuration directories, setting up OAuth2 credentials,
+//! generating default configuration files, and completing the initial authentication flow.
+//!
+//! ## Overview
+//!
+//! The initialization system allows users to:
+//!
+//! - **Create configuration directory**: Set up the cull-gmail configuration directory
+//! - **Install credentials**: Copy and validate OAuth2 credential files  
+//! - **Generate configuration**: Create default cull-gmail.toml and rules.toml files
+//! - **Complete OAuth2 flow**: Authenticate with Gmail API and persist tokens
+//! - **Interactive setup**: Guide users through setup with prompts and confirmations
+//! - **Dry-run mode**: Preview all actions without making changes
+//!
+//! ## Use Cases
+//!
+//! ### First-time Setup
+//! ```bash
+//! # Interactive setup with credential file
+//! cull-gmail init --interactive --credential-file ~/Downloads/client_secret.json
+//!
+//! # Non-interactive setup (credential file copied manually later)
+//! cull-gmail init --config-dir ~/.cull-gmail
+//! ```
+//!
+//! ### Planning and Verification
+//! ```bash
+//! # See what would be created without making changes
+//! cull-gmail init --dry-run
+//!
+//! # Preview with specific options
+//! cull-gmail init --config-dir /custom/path --credential-file credentials.json --dry-run
+//! ```
+//!
+//! ### Force Overwrite
+//! ```bash
+//! # Recreate configuration, backing up existing files
+//! cull-gmail init --force
+//! ```
+//!
+//! ## Security Considerations
+//!
+//! - **Credential Protection**: OAuth2 credential files are copied with 0600 permissions
+//! - **Token Directory**: Token cache directory is created with 0700 permissions
+//! - **Backup Safety**: Existing files are backed up with timestamps before overwriting
+//! - **Interactive Confirmation**: Prompts for confirmation before overwriting existing files
+
+use clap::Parser;
+use std::path::PathBuf;
+
+/// Initialize cull-gmail configuration, credentials, and OAuth2 tokens.
+///
+/// This command sets up the complete cull-gmail environment by creating the configuration
+/// directory, installing OAuth2 credentials, generating default configuration files,
+/// and completing the initial Gmail API authentication to persist tokens.
+///
+/// ## Setup Process
+///
+/// 1. **Configuration Directory**: Create or verify the configuration directory
+/// 2. **Credential Installation**: Copy and validate OAuth2 credential file (if provided)  
+/// 3. **Configuration Generation**: Create cull-gmail.toml with safe defaults
+/// 4. **Rules Template**: Generate rules.toml with example retention rules
+/// 5. **Token Directory**: Ensure OAuth2 token cache directory exists
+/// 6. **Authentication**: Complete OAuth2 flow to generate and persist tokens
+///
+/// ## Interactive vs Non-Interactive
+///
+/// - **Non-interactive** (default): Proceeds with provided options, fails if conflicts exist
+/// - **Interactive** (`--interactive`): Prompts for missing information and confirmation for conflicts
+/// - **Dry-run** (`--dry-run`): Shows planned actions without making any changes
+///
+/// ## Examples
+///
+/// ```bash
+/// # Basic initialization
+/// cull-gmail init
+///
+/// # Interactive setup with credential file
+/// cull-gmail init --interactive --credential-file client_secret.json
+///
+/// # Custom configuration directory
+/// cull-gmail init --config-dir /path/to/config
+///
+/// # Preview actions without changes
+/// cull-gmail init --dry-run
+///
+/// # Force overwrite existing files
+/// cull-gmail init --force
+/// ```
+#[derive(Parser, Debug)]
+pub struct InitCli {
+    /// Configuration directory path.
+    ///
+    /// Supports path prefixes:
+    /// - `h:path` - Relative to home directory (default: `h:.cull-gmail`)
+    /// - `c:path` - Relative to current directory
+    /// - `r:path` - Relative to filesystem root
+    /// - `path` - Use path as-is
+    #[arg(
+        long = "config-dir",
+        value_name = "DIR",
+        default_value = "h:.cull-gmail",
+        help = "Configuration directory path"
+    )]
+    pub config_dir: String,
+
+    /// OAuth2 credential file path.
+    ///
+    /// This should be the JSON file downloaded from Google Cloud Console
+    /// containing your OAuth2 client credentials for Desktop application type.
+    /// The file will be copied to the configuration directory as `credential.json`.
+    #[arg(
+        long = "credential-file",
+        value_name = "PATH",
+        help = "Path to OAuth2 credential JSON file"
+    )]
+    pub credential_file: Option<PathBuf>,
+
+    /// Overwrite existing files without prompting.
+    ///
+    /// When enabled, existing configuration files will be backed up with
+    /// timestamps and then overwritten with new defaults. Use with caution
+    /// as this will replace your current configuration.
+    #[arg(
+        long = "force",
+        help = "Overwrite existing files (creates timestamped backups)"
+    )]
+    pub force: bool,
+
+    /// Show planned actions without making changes.
+    ///
+    /// Enables preview mode where all planned operations are displayed
+    /// but no files are created, modified, or removed. OAuth2 authentication
+    /// flow is also skipped in dry-run mode.
+    #[arg(
+        long = "dry-run", 
+        help = "Preview actions without making changes"
+    )]
+    pub dry_run: bool,
+
+    /// Enable interactive prompts and confirmations.
+    ///
+    /// When enabled, the command will prompt for missing information
+    /// (such as credential file path) and ask for confirmation before
+    /// overwriting existing files. Recommended for first-time users.
+    #[arg(
+        long = "interactive",
+        short = 'i',
+        help = "Prompt for missing information and confirmations"
+    )]
+    pub interactive: bool,
+}
+
+impl InitCli {
+    /// Execute the initialization command.
+    ///
+    /// This method orchestrates the complete initialization workflow including
+    /// configuration directory creation, credential installation, file generation,
+    /// and OAuth2 authentication based on the provided command-line options.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Result<()>` indicating success or failure of the initialization process.
+    ///
+    /// # Process Flow
+    ///
+    /// 1. **Plan Operations**: Analyze current state and generate operation plan
+    /// 2. **Validate Inputs**: Check credential file validity and resolve paths  
+    /// 3. **Interactive Prompts**: Request missing information if in interactive mode
+    /// 4. **Execute or Preview**: Apply operations or show dry-run preview
+    /// 5. **OAuth2 Flow**: Complete authentication and token generation
+    /// 6. **Success Reporting**: Display results and next steps
+    ///
+    /// # Errors
+    ///
+    /// This method can return errors for:
+    /// - Invalid or missing credential files
+    /// - File system permission issues  
+    /// - Configuration conflicts without force or interactive resolution
+    /// - OAuth2 authentication failures
+    /// - Network connectivity issues during authentication
+    pub async fn run(&self) -> cull_gmail::Result<()> {
+        log::info!("Starting cull-gmail initialization");
+        
+        if self.dry_run {
+            println!("DRY RUN: No changes will be made");
+        }
+
+        // TODO: Implement initialization logic
+        println!("Init command called with options: {self:?}");
+        
+        Ok(())
+    }
+}