feat: Implement pdsh compatibility layer core infrastructure (#97)

Add pdsh compatibility mode allowing bssh to act as a drop-in replacement
for pdsh. This implements Phase 2 of the pdsh compatibility roadmap.

Changes:
- Create CLI module structure: cli/mod.rs, cli/bssh.rs, cli/pdsh.rs
- Add is_pdsh_compat_mode() for binary name and env var detection
- Add PdshCli struct with pdsh-compatible argument parsing
- Implement to_bssh_cli() conversion method for option mapping
- Add --pdsh-compat flag to bssh CLI
- Add --any-failure flag for pdsh -S compatibility
- Wire up mode detection in main.rs entry point
- Add query mode (-q) support to show hosts and exit

Option mapping:
- -w hosts -> -H hosts
- -x hosts -> --exclude hosts
- -f N -> --parallel N
- -l user -> -l user
- -t N -> --connect-timeout N
- -u N -> --timeout N
- -N -> --no-prefix
- -b -> --batch
- -k -> --fail-fast
- -q -> query mode
- -S -> --any-failure

Activation methods:
1. Symlink bssh as "pdsh"
2. Set BSSH_PDSH_COMPAT=1 environment variable
3. Use --pdsh-compat flag

Includes 24 unit tests for mode detection and option mapping.
Updates ARCHITECTURE.md with pdsh compatibility documentation.

Author: inureyes

ARCHITECTURE.md

@@ -212,6 +212,78 @@ async fn main() -> Result<()> {
 - Subcommand pattern adds complexity but improves UX
 - Modular structure increases file count but improves testability
 
+#### pdsh Compatibility Mode (Issue #97)
+
+bssh supports pdsh compatibility mode, allowing it to act as a drop-in replacement for pdsh. This enables migration from pdsh without modifying existing scripts.
+
+**Module Structure:**
+- `cli/mod.rs` - CLI module exports and pdsh re-exports
+- `cli/bssh.rs` - Standard bssh CLI parser
+- `cli/pdsh.rs` - pdsh-compatible CLI parser and conversion logic
+- `cli/mode_detection_tests.rs` - Tests for mode detection
+
+**Activation Methods:**
+
+1. **Binary name detection**: When bssh is invoked as "pdsh" (via symlink)
+   ```bash
+   ln -s /usr/bin/bssh /usr/local/bin/pdsh
+   pdsh -w hosts "uptime"  # Uses pdsh compat mode
+   ```
+
+2. **Environment variable**: `BSSH_PDSH_COMPAT=1` or `BSSH_PDSH_COMPAT=true`
+   ```bash
+   BSSH_PDSH_COMPAT=1 bssh -w hosts "uptime"
+   ```
+
+3. **CLI flag**: `--pdsh-compat`
+   ```bash
+   bssh --pdsh-compat -w hosts "uptime"
+   ```
+
+**Option Mapping:**
+
+| pdsh option | bssh option | Description |
+|-------------|-------------|-------------|
+| `-w hosts` | `-H hosts` | Target hosts (comma-separated) |
+| `-x hosts` | `--exclude hosts` | Exclude hosts from target list |
+| `-f N` | `--parallel N` | Fanout (parallel connections) |
+| `-l user` | `-l user` | Remote username |
+| `-t N` | `--connect-timeout N` | Connection timeout (seconds) |
+| `-u N` | `--timeout N` | Command timeout (seconds) |
+| `-N` | `--no-prefix` | Disable hostname prefix in output |
+| `-b` | `--batch` | Batch mode (single Ctrl+C terminates) |
+| `-k` | `--fail-fast` | Stop on first failure |
+| `-q` | (query mode) | Show hosts and exit |
+| `-S` | `--any-failure` | Return largest exit code from any node |
+
+**Implementation Details:**
+
+```rust
+// Mode detection in main.rs
+let pdsh_mode = is_pdsh_compat_mode() || has_pdsh_compat_flag(&args);
+
+if pdsh_mode {
+    return run_pdsh_mode(&args).await;
+}
+
+// pdsh CLI parsing and conversion
+let pdsh_cli = PdshCli::parse_from(filtered_args.iter());
+let mut cli = pdsh_cli.to_bssh_cli();
+```
+
+**Design Decisions:**
+
+1. **Separate parser**: pdsh CLI uses its own clap parser to avoid conflicts with bssh options
+2. **Conversion method**: `to_bssh_cli()` converts pdsh options to bssh `Cli` struct
+3. **Query mode**: pdsh `-q` shows target hosts without executing commands
+4. **Default fanout**: pdsh default is 32, bssh default is 10 - pdsh mode uses 32
+
+**Key Points:**
+- Mode detection happens before any argument parsing
+- pdsh and bssh modes are mutually exclusive
+- Unknown pdsh options produce helpful error messages
+- Normal bssh operation is completely unaffected by pdsh compat code
+
 ### 2. Configuration Management (`config/*`)
 
 **Module Structure (Refactored 2025-10-17):**

src/cli.rs src/cli/bssh.rssrc/cli.rs renamed to src/cli/bssh.rs

@@ -203,6 +203,18 @@ pub struct Cli {
     )]
     pub fail_fast: bool,
 
+    #[arg(
+        long = "any-failure",
+        help = "Return largest exit code from any node (pdsh -S compatible)\nWhen enabled, returns the maximum exit code from all nodes\nUseful for build/test pipelines where any failure should be reported"
+    )]
+    pub any_failure: bool,
+
+    #[arg(
+        long = "pdsh-compat",
+        help = "Enable pdsh compatibility mode\nAccepts pdsh-style command line arguments (-w, -x, -f, etc.)\nUseful when migrating from pdsh or in mixed environments"
+    )]
+    pub pdsh_compat: bool,
+
     #[arg(
         trailing_var_arg = true,
         help = "Command to execute on remote hosts",

src/cli/mod.rs

@@ -0,0 +1,49 @@
+// Copyright 2025 Lablup Inc. and Jeongkyu Shin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! CLI module for bssh
+//!
+//! This module provides command-line interface parsing for bssh, including:
+//! - Standard bssh CLI (`Cli`)
+//! - pdsh compatibility layer (`pdsh` submodule)
+//!
+//! # Architecture
+//!
+//! The CLI module is structured as follows:
+//! - `bssh.rs` - Main bssh CLI parser with all standard options
+//! - `pdsh.rs` - pdsh-compatible CLI parser for drop-in replacement mode
+//!
+//! # pdsh Compatibility Mode
+//!
+//! bssh can operate in pdsh compatibility mode, activated by:
+//! 1. Setting `BSSH_PDSH_COMPAT=1` environment variable
+//! 2. Symlinking bssh to "pdsh" and invoking via that name
+//! 3. Using the `--pdsh-compat` flag
+//!
+//! See the `pdsh` module documentation for details on option mapping.
+
+mod bssh;
+pub mod pdsh;
+
+#[cfg(test)]
+mod mode_detection_tests;
+
+// Re-export main CLI types from bssh module
+pub use bssh::{Cli, Commands};
+
+// Re-export pdsh compatibility utilities
+pub use pdsh::{
+    has_pdsh_compat_flag, is_pdsh_compat_mode, remove_pdsh_compat_flag, PdshCli, QueryResult,
+    PDSH_COMPAT_ENV_VAR,
+};

src/cli/mode_detection_tests.rs

@@ -0,0 +1,243 @@
+// Copyright 2025 Lablup Inc. and Jeongkyu Shin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Tests for pdsh compatibility mode detection
+//!
+//! These tests verify that pdsh compatibility mode is correctly detected
+//! based on environment variables and binary names.
+
+#[cfg(test)]
+mod tests {
+    use crate::cli::pdsh::PDSH_COMPAT_ENV_VAR;
+    use std::env;
+
+    /// Test that environment variable detection works for "1"
+    #[test]
+    fn test_env_var_detection_one() {
+        // Save and restore env var state
+        let original = env::var(PDSH_COMPAT_ENV_VAR).ok();
+
+        env::set_var(PDSH_COMPAT_ENV_VAR, "1");
+
+        // Create a test for the env var checking logic
+        let value = env::var(PDSH_COMPAT_ENV_VAR).ok();
+        assert!(value.is_some());
+        let value = value.unwrap();
+        assert!(value == "1" || value.to_lowercase() == "true");
+
+        // Restore
+        match original {
+            Some(v) => env::set_var(PDSH_COMPAT_ENV_VAR, v),
+            None => env::remove_var(PDSH_COMPAT_ENV_VAR),
+        }
+    }
+
+    /// Test that environment variable detection works for "true"
+    #[test]
+    fn test_env_var_detection_true() {
+        let original = env::var(PDSH_COMPAT_ENV_VAR).ok();
+
+        env::set_var(PDSH_COMPAT_ENV_VAR, "true");
+
+        let value = env::var(PDSH_COMPAT_ENV_VAR).ok();
+        assert!(value.is_some());
+        assert_eq!(value.unwrap().to_lowercase(), "true");
+
+        match original {
+            Some(v) => env::set_var(PDSH_COMPAT_ENV_VAR, v),
+            None => env::remove_var(PDSH_COMPAT_ENV_VAR),
+        }
+    }
+
+    /// Test that environment variable detection works for "TRUE" (case insensitive)
+    #[test]
+    fn test_env_var_detection_case_insensitive() {
+        let original = env::var(PDSH_COMPAT_ENV_VAR).ok();
+
+        env::set_var(PDSH_COMPAT_ENV_VAR, "TRUE");
+
+        let value = env::var(PDSH_COMPAT_ENV_VAR).ok();
+        assert!(value.is_some());
+        assert_eq!(value.unwrap().to_lowercase(), "true");
+
+        match original {
+            Some(v) => env::set_var(PDSH_COMPAT_ENV_VAR, v),
+            None => env::remove_var(PDSH_COMPAT_ENV_VAR),
+        }
+    }
+
+    /// Test that environment variable is not detected when unset
+    #[test]
+    fn test_env_var_not_set() {
+        let original = env::var(PDSH_COMPAT_ENV_VAR).ok();
+
+        env::remove_var(PDSH_COMPAT_ENV_VAR);
+
+        let value = env::var(PDSH_COMPAT_ENV_VAR).ok();
+        assert!(value.is_none());
+
+        // Restore
+        if let Some(v) = original {
+            env::set_var(PDSH_COMPAT_ENV_VAR, v);
+        }
+    }
+
+    /// Test that invalid env var values are not treated as enabled
+    #[test]
+    fn test_env_var_invalid_values() {
+        let original = env::var(PDSH_COMPAT_ENV_VAR).ok();
+
+        // Test "0"
+        env::set_var(PDSH_COMPAT_ENV_VAR, "0");
+        let value = env::var(PDSH_COMPAT_ENV_VAR).unwrap();
+        let enabled = value == "1" || value.to_lowercase() == "true";
+        assert!(!enabled);
+
+        // Test "false"
+        env::set_var(PDSH_COMPAT_ENV_VAR, "false");
+        let value = env::var(PDSH_COMPAT_ENV_VAR).unwrap();
+        let enabled = value == "1" || value.to_lowercase() == "true";
+        assert!(!enabled);
+
+        // Test empty string
+        env::set_var(PDSH_COMPAT_ENV_VAR, "");
+        let value = env::var(PDSH_COMPAT_ENV_VAR).unwrap();
+        let enabled = value == "1" || value.to_lowercase() == "true";
+        assert!(!enabled);
+
+        // Restore
+        match original {
+            Some(v) => env::set_var(PDSH_COMPAT_ENV_VAR, v),
+            None => env::remove_var(PDSH_COMPAT_ENV_VAR),
+        }
+    }
+
+    /// Test binary name detection logic for "pdsh"
+    #[test]
+    fn test_binary_name_pdsh() {
+        use std::path::Path;
+
+        let arg0 = "/usr/bin/pdsh";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert_eq!(binary_name, "pdsh");
+        assert!(binary_name == "pdsh" || binary_name.starts_with("pdsh."));
+    }
+
+    /// Test binary name detection for relative path
+    #[test]
+    fn test_binary_name_relative_path() {
+        use std::path::Path;
+
+        let arg0 = "./pdsh";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert_eq!(binary_name, "pdsh");
+    }
+
+    /// Test binary name detection for "pdsh.exe" (Windows)
+    #[test]
+    #[cfg(windows)]
+    fn test_binary_name_windows() {
+        use std::path::Path;
+
+        let arg0 = "C:\\Program Files\\bssh\\pdsh.exe";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert!(binary_name.starts_with("pdsh."));
+    }
+
+    /// Test binary name detection for "pdsh.exe" pattern
+    #[test]
+    fn test_binary_name_exe_extension() {
+        use std::path::Path;
+
+        // Test just the filename (works cross-platform)
+        let arg0 = "pdsh.exe";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert!(binary_name.starts_with("pdsh."));
+    }
+
+    /// Test that bssh binary name is not detected as pdsh
+    #[test]
+    fn test_binary_name_bssh() {
+        use std::path::Path;
+
+        let arg0 = "/usr/bin/bssh";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert_eq!(binary_name, "bssh");
+        assert!(!(binary_name == "pdsh" || binary_name.starts_with("pdsh.")));
+    }
+
+    /// Test that symlinked pdsh is detected
+    #[test]
+    fn test_binary_name_symlink() {
+        use std::path::Path;
+
+        // When bssh is symlinked as pdsh, arg0 would be the symlink name
+        let arg0 = "/usr/local/bin/pdsh";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert_eq!(binary_name, "pdsh");
+    }
+
+    /// Test edge case: empty arg0
+    #[test]
+    fn test_binary_name_empty() {
+        use std::path::Path;
+
+        let arg0 = "";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert!(binary_name.is_empty());
+        assert!(!(binary_name == "pdsh" || binary_name.starts_with("pdsh.")));
+    }
+
+    /// Test edge case: just filename without path
+    #[test]
+    fn test_binary_name_no_path() {
+        use std::path::Path;
+
+        let arg0 = "pdsh";
+        let binary_name = Path::new(arg0)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+
+        assert_eq!(binary_name, "pdsh");
+    }
+}