refactor: Transform CLI to modular architecture

- Refactor 842-line main.rs into clean 35-line entry point
- Organize commands into focused modules by category:
  * info.rs - Information and listing commands
  * token.rs - Token management operations
  * keys.rs - Key management operations
  * crypto.rs - Sign/verify/encrypt/decrypt operations
  * symmetric.rs - Symmetric key operations
  * key_wrap.rs - Key wrapping/unwrapping
  * mac.rs - HMAC and CMAC operations
  * util.rs - Utility commands (benchmark, audit, troubleshooting)
  * analyze.rs - Observability log analysis
- Add commands/common.rs for shared utilities (PIN handling, config)
- Implement commands/mod.rs as main dispatcher with routing logic
- All 55 integration tests pass - no functionality lost
- Update documentation with CLI_ARCHITECTURE.md
- Improve maintainability, testability, and extensibility

Breaking: None (full backward compatibility maintained)
Features: Modular command architecture for easier maintenance

Author: testingapisname

.github/copilot-instructions.md

@@ -192,9 +192,13 @@ Keep this pattern; observability layers should complement, not replace.
 ---
 
 ## CLI Conventions
-- Use `clap` derive macros; keep subcommands in `cli.rs`, dispatch in `main.rs`.
-- Keep operations in `pkcs11/*` modules.
-- Add tests to `test.sh` when introducing core ops.
+- **Modular Architecture**: Commands are organized into focused handlers in `src/commands/`
+- **Entry Point**: `main.rs` is now a clean 35-line file with configuration and dispatch
+- **Command Handlers**: Each category (info, token, keys, crypto, etc.) has its own module
+- **Shared Utilities**: Common functionality (PIN handling, config) in `commands/common.rs`
+- Use `clap` derive macros; keep subcommands in `cli.rs`, dispatch via `commands::dispatch_command`
+- Keep core operations in `rust-hsm-core/src/pkcs11/*` modules
+- Add tests to `test.sh` when introducing core ops
 
 ---
 
@@ -398,12 +402,24 @@ let key_handle = session.find_objects(&template)?.first().copied()
 ## Adding New Commands
 
 1. Add variant to `Commands` enum in [cli.rs](../crates/rust-hsm-cli/src/cli.rs)
-2. Implement function in appropriate `pkcs11/*.rs` module
-3. Add export to [pkcs11/keys/mod.rs](../crates/rust-hsm-cli/src/pkcs11/keys/mod.rs) if needed
-4. Add match arm in [main.rs](../crates/rust-hsm-cli/src/main.rs) to dispatch to your function
-5. Add test case to [test.sh](../test.sh) for SoftHSM2
-6. Add test case to [testKryoptic.sh](../testKryoptic.sh) for Kryoptic
-7. Update command documentation in [docs/commands/](../docs/commands/)
+2. Implement function in appropriate `rust-hsm-core/src/pkcs11/*.rs` module
+3. Add handler to appropriate `commands/*.rs` module (or create new category)
+4. Update dispatcher in [commands/mod.rs](../crates/rust-hsm-cli/src/commands/mod.rs) 
+5. Use shared utilities from [commands/common.rs](../crates/rust-hsm-cli/src/commands/common.rs) for PIN handling and config
+6. Add test case to [test.sh](../test.sh) for SoftHSM2
+7. Add test case to [testKryoptic.sh](../testKryoptic.sh) for Kryoptic
+8. Update command documentation in [docs/commands/](../docs/commands/)
+
+**Command Handler Categories:**
+- `info.rs` - Information and listing commands
+- `token.rs` - Token management operations  
+- `keys.rs` - Key management operations
+- `crypto.rs` - Cryptographic operations (sign, verify, encrypt, decrypt)
+- `symmetric.rs` - Symmetric key operations
+- `key_wrap.rs` - Key wrapping/unwrapping
+- `mac.rs` - HMAC and CMAC operations
+- `util.rs` - Utility commands (benchmark, audit, troubleshooting)
+- `analyze.rs` - Observability log analysis
 
 ---
 

README.md

@@ -0,0 +1,70 @@
+//! Log analysis command
+
+use anyhow::Result;
+
+pub fn handle_analyze(log_file: String, format: String) -> Result<()> {
+    use rust_hsm_analyze::{parse_observe_json, Analyzer};
+
+    // Parse the log file
+    let events = parse_observe_json(&log_file)?;
+
+    if events.is_empty() {
+        println!("No events found in log file");
+        return Ok(());
+    }
+
+    // Analyze the events
+    let analyzer = Analyzer::new(events);
+    let analysis = analyzer.analyze();
+
+    // Output results
+    if format == "json" {
+        println!("{}", serde_json::to_string_pretty(&analysis)?);
+    } else {
+        println!("\n=== PKCS#11 Session Analysis ===\n");
+        println!("Total Operations: {}", analysis.total_ops);
+        println!("Success Rate: {:.2}%", analysis.success_rate);
+        println!("Error Count: {}", analysis.error_count);
+
+        println!("\n--- Overall Timing ---");
+        println!("Total Duration: {:.2}ms", analysis.duration_stats.total_ms);
+        println!("Average: {:.2}ms", analysis.duration_stats.avg_ms);
+        println!("Min: {:.2}ms", analysis.duration_stats.min_ms);
+        println!("Max: {:.2}ms", analysis.duration_stats.max_ms);
+        println!("P50: {:.2}ms", analysis.duration_stats.p50_ms);
+        println!("P95: {:.2}ms", analysis.duration_stats.p95_ms);
+        println!("P99: {:.2}ms", analysis.duration_stats.p99_ms);
+
+        if !analysis.by_function.is_empty() {
+            println!("\n--- Per-Function Statistics ---");
+            for (func, stats) in &analysis.by_function {
+                println!("\n{}", func);
+                println!("  Calls: {}", stats.count);
+                let success_rate = if stats.count > 0 {
+                    (stats.success_count as f64 / stats.count as f64) * 100.0
+                } else {
+                    0.0
+                };
+                let error_rate = if stats.count > 0 {
+                    (stats.error_count as f64 / stats.count as f64) * 100.0
+                } else {
+                    0.0
+                };
+                println!("  Success: {} ({:.1}%)", stats.success_count, success_rate);
+                println!("  Errors: {} ({:.1}%)", stats.error_count, error_rate);
+                println!("  Avg Duration: {:.2}ms", stats.avg_duration_ms);
+            }
+        }
+
+        if !analysis.errors.is_empty() {
+            println!("\n--- Errors ---");
+            for error in &analysis.errors {
+                println!("\n{} → {} ({})", error.func, error.rv_name, error.rv);
+                println!("  Count: {}", error.count);
+                println!("  First seen: {}", error.timestamp);
+            }
+        }
+    }
+
+    Ok(())
+}

crates/rust-hsm-cli/src/commands/analyze.rs

@@ -0,0 +1,61 @@
+//! Common utilities and structures for command handling
+
+use anyhow::Result;
+use std::env;
+use std::io::{self, BufRead};
+
+use crate::config::Config;
+
+/// Shared context for all command handlers
+pub struct CommandContext {
+    pub config: Config,
+    pub module_path: String,
+}
+
+impl CommandContext {
+    pub fn new(config: Config) -> Result<Self> {
+        let module_path =
+            env::var("PKCS11_MODULE").unwrap_or_else(|_| config.get_pkcs11_module().to_string());
+
+        tracing::info!("Using PKCS#11 module: {}", module_path);
+
+        Ok(CommandContext {
+            config,
+            module_path,
+        })
+    }
+
+    /// Get token label, using CLI value or config default
+    pub fn token_label(&self, cli_value: Option<String>) -> Result<String> {
+        self.config
+            .token_label(cli_value.as_deref())
+            .ok_or_else(|| anyhow::anyhow!("Token label required"))
+    }
+}
+
+/// Read a PIN from stdin, trimming whitespace
+pub fn read_pin_from_stdin() -> Result<String> {
+    let stdin = io::stdin();
+    let mut line = String::new();
+    stdin.lock().read_line(&mut line)?;
+    Ok(line.trim().to_string())
+}
+
+/// Common PIN handling logic
+pub fn get_pin(pin: Option<String>, use_stdin: bool, error_msg: &str) -> Result<String> {
+    if use_stdin {
+        read_pin_from_stdin()
+    } else {
+        pin.ok_or_else(|| anyhow::anyhow!("{}", error_msg))
+    }
+}
+
+/// Get user PIN with consistent error handling
+pub fn get_user_pin(pin: Option<String>, use_stdin: bool) -> Result<String> {
+    get_pin(pin, use_stdin, "User PIN required")
+}
+
+/// Get SO PIN with consistent error handling
+pub fn get_so_pin(pin: Option<String>, use_stdin: bool) -> Result<String> {
+    get_pin(pin, use_stdin, "SO PIN required")
+}

crates/rust-hsm-cli/src/commands/common.rs

@@ -0,0 +1,99 @@
+//! Cryptographic operation commands
+
+use anyhow::Result;
+
+use super::common::{get_user_pin, CommandContext};
+
+pub fn handle_sign(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    key_label: String,
+    input: String,
+    output: String,
+    json: bool,
+    pin_stdin: bool,
+) -> Result<()> {
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::keys::sign(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        &key_label,
+        &input,
+        &output,
+        json,
+        ctx.config.observe_enabled,
+        &ctx.config.observe_log_file,
+    )
+}
+
+pub fn handle_verify(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    key_label: String,
+    input: String,
+    signature: String,
+    json: bool,
+    pin_stdin: bool,
+) -> Result<()> {
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::keys::verify(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        &key_label,
+        &input,
+        &signature,
+        json,
+    )
+}
+
+pub fn handle_encrypt(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    key_label: String,
+    input: String,
+    output: String,
+    pin_stdin: bool,
+) -> Result<()> {
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::keys::encrypt(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        &key_label,
+        &input,
+        &output,
+    )
+}
+
+pub fn handle_decrypt(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    key_label: String,
+    input: String,
+    output: String,
+    pin_stdin: bool,
+) -> Result<()> {
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::keys::decrypt(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        &key_label,
+        &input,
+        &output,
+    )
+}

crates/rust-hsm-cli/src/commands/crypto.rs

@@ -0,0 +1,44 @@
+//! Information and listing commands
+
+use anyhow::Result;
+
+use super::common::CommandContext;
+
+pub fn handle_info(ctx: CommandContext, json: bool) -> Result<()> {
+    rust_hsm_core::info::display_info(&ctx.module_path, json)
+}
+
+pub fn handle_list_slots(ctx: CommandContext, json: bool) -> Result<()> {
+    rust_hsm_core::slots::list_slots(&ctx.module_path, json)
+}
+
+pub fn handle_list_mechanisms(
+    ctx: CommandContext,
+    slot: Option<u64>,
+    detailed: bool,
+    json: bool,
+) -> Result<()> {
+    rust_hsm_core::info::list_mechanisms(&ctx.module_path, slot, detailed, json)
+}
+
+pub fn handle_list_objects(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    pin_stdin: bool,
+    detailed: bool,
+    json: bool,
+) -> Result<()> {
+    use super::common::get_user_pin;
+
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::objects::list_objects(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        detailed,
+        json,
+    )
+}

crates/rust-hsm-cli/src/commands/info.rs

@@ -0,0 +1,51 @@
+//! Key wrapping operation commands
+
+use anyhow::Result;
+
+use super::common::{get_user_pin, CommandContext};
+
+pub fn handle_wrap_key(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    key_label: String,
+    wrapping_key_label: String,
+    output: String,
+    pin_stdin: bool,
+) -> Result<()> {
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::keys::wrap_key(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        &key_label,
+        &wrapping_key_label,
+        &output,
+    )
+}
+
+pub fn handle_unwrap_key(
+    ctx: CommandContext,
+    label: Option<String>,
+    user_pin: Option<String>,
+    key_label: String,
+    wrapping_key_label: String,
+    input: String,
+    key_type: String,
+    pin_stdin: bool,
+) -> Result<()> {
+    let token_label = ctx.token_label(label)?;
+    let user_pin_value = get_user_pin(user_pin, pin_stdin)?;
+
+    rust_hsm_core::keys::unwrap_key(
+        &ctx.module_path,
+        &token_label,
+        &user_pin_value,
+        &key_label,
+        &wrapping_key_label,
+        &input,
+        &key_type,
+    )
+}