feat: Add pdsh compatibility mode for drop-in replacement

[inureyes]

Summary

Implement a pdsh (Parallel Distributed Shell) compatibility mode that allows bssh to be used as a drop-in replacement for pdsh. Users should be able to use pdsh command syntax and have it automatically mapped to bssh's superior functionality.

This is a meta-issue. See linked sub-issues below for individual implementation tasks.

Background

pdsh is a widely-used parallel shell utility in HPC environments. Adding compatibility mode would allow users to migrate from pdsh to bssh without changing their existing scripts and workflows.

Activation Methods (Proposed)

1. Binary name detection: If argv[0] is "pdsh", automatically enable compatibility mode
2. Environment variable: BSSH_PDSH_COMPAT=1
3. Command-line flag: bssh --pdsh-compat or bssh pdsh subcommand

Option Conflict Analysis

Critical Conflicts (same short flag, different meaning)

Option	pdsh meaning	bssh meaning	Resolution
-f	fanout (max concurrent, default 32)	--filter (host filter pattern)	In pdsh mode: map to --parallel
-t	connection timeout (seconds)	--tty (force TTY allocation)	In pdsh mode: new --connect-timeout
-A	all nodes (genders database)	--use-agent (SSH agent)	In pdsh mode: target all configured hosts
-q	display options/nodelist then exit	--quiet (suppress output)	In pdsh mode: dry-run/list mode
-S	return largest exit code	--sudo-password	In pdsh mode: map to new --any-failure
-L	list loaded modules	--local-forward	In pdsh mode: show info
-R	rcmd module selection	--remote-forward	In pdsh mode: ignore (ssh only)
-C	SLURM features filter	--cluster	Similar concept, may work
-F	genders file path	--ssh-config	Different file format

Compatible Options

Option	Both pdsh and bssh meaning
-l	Login user name

pdsh Options Not in bssh (need implementation)

Option	pdsh meaning	Proposed bssh implementation
-w	Host targets	Map to -H
-x	Exclude hosts	New --exclude option
-u	Command timeout	Map to --timeout
-N	Disable hostname prefix	New --no-prefix option
-b	Batch mode (single Ctrl+C kills)	New --batch option
-k	Fail fast on error	New --fail-fast option
-d	Debug/timing statistics	Map to -vvv
-g	Target by group/attributes	Map to -C (cluster)

Implementation Phases

Note: Phases are ordered by dependency - new bssh options must exist before the pdsh compatibility layer can map to them.

Phase 1: New Options for Feature Parity

Add new options to bssh that pdsh compatibility mode will map to:

• Add --exclude option for host exclusion
• Add --no-prefix option to disable hostname prefix in output
• Add --batch option for single Ctrl+C termination
• Add --fail-fast option to stop on first failure
• Add --connect-timeout option (separate from command timeout)

Phase 2: Core Infrastructure

Build the pdsh compatibility layer:

• Add binary name detection in main.rs (argv[0] check)
• Add BSSH_PDSH_COMPAT environment variable support
• Create src/cli/pdsh.rs with pdsh-compatible CLI parser
• Implement option mapping/translation layer

Phase 3: Hostlist Expression Support

• Implement pdsh-style range expansion: host[01-05] -> host01,host02,...,host05
• Implement exclusion in range: host[1-5] -x host[2-3]
• Support file input with ^filename syntax

Phase 4: Installation & Documentation

• Add symlink creation in install scripts (pdsh -> bssh)
• Document pdsh compatibility mode in README
• Add migration guide for pdsh users
• Create compatibility test suite

Sub-Issues

Phase 1: New Options for Feature Parity

• feat: Add --exclude option for host exclusion (pdsh -x compatibility) #93 - Add --exclude option for host exclusion
• feat: Add --no-prefix option to disable hostname prefix in output (pdsh -N compatibility) #92 - Add --no-prefix option to disable hostname prefix
• feat: Add --batch option for single Ctrl+C termination (pdsh -b compatibility) #95 - Add --batch option for batch mode
• feat: Add --fail-fast option to stop on first failure (pdsh -k compatibility) #94 - Add --fail-fast option for fail-fast execution
• feat: Add --connect-timeout option for connection timeout (pdsh -t compatibility) #96 - Add --connect-timeout option for connection timeout

Phase 2: Core Infrastructure

• feat: Implement pdsh compatibility layer core infrastructure #97 - Implement pdsh compatibility layer core infrastructure

Phase 3: Hostlist Expression Support

• feat: Add pdsh-style hostlist expression support (range expansion) #98 - Add pdsh-style hostlist expression support (range expansion)

Phase 4: Installation & Documentation

• docs: Add pdsh compatibility mode documentation and installation scripts #99 - Add pdsh compatibility mode documentation and installation scripts

Impact on Existing Behavior

• No impact: Default bssh behavior remains unchanged
• Opt-in only: Compatibility mode requires explicit activation
• Backward compatible: All existing bssh commands continue to work

Example Usage (after implementation)

# pdsh-style commands work when running as pdsh or with compat mode
pdsh -w node[01-10] -f 20 "uptime"        # Using pdsh symlink
bssh --pdsh-compat -w node[01-10] -f 20 "uptime"  # Using flag
BSSH_PDSH_COMPAT=1 bssh -w node[01-10] "uptime"   # Using env var

# Equivalent bssh native command
bssh -H "node01,node02,...,node10" --parallel 20 "uptime"

References

• pdsh GitHub: https://github.com/chaos/pdsh
• pdsh man page: https://manpages.ubuntu.com/manpages/questing/man1/pdsh.1.html
• ADMIN Magazine article: https://www.admin-magazine.com/HPC/Articles/pdsh-Parallel-Shell