docs: Add pdsh compatibility mode documentation and installation scripts

[inureyes]

Summary

Create comprehensive documentation and installation scripts for pdsh compatibility mode, including symlink setup, migration guide, and compatibility test suite.

Parent Issue

Part of #91 (pdsh compatibility mode) - Phase 4: Installation & Documentation

Prerequisites

• All Phase 1-3 features must be implemented and tested

Scope

1. Installation Scripts

Symlink Creation
Add to install scripts (Homebrew formula, cargo install post-hook, etc.):

# Create pdsh symlink pointing to bssh
ln -sf $(which bssh) /usr/local/bin/pdsh

Homebrew Formula Update

# In homebrew-bssh formula
def post_install
  # Create pdsh compatibility symlink
  bin.install_symlink "bssh" => "pdsh"
end

Shell Alias Alternative

# For users who prefer aliases over symlinks
# Add to .bashrc/.zshrc
alias pdsh='bssh --pdsh-compat'

2. Documentation Updates

README.md Section
Add a "pdsh Compatibility Mode" section:

• How to enable (symlink, env var, flag)
• Option mapping table
• Feature comparison
• Limitations

Migration Guide (docs/pdsh-migration.md)

• Side-by-side comparison of pdsh vs bssh commands
• Scripts to help migrate existing pdsh usage
• Common pdsh patterns and bssh equivalents
• Known incompatibilities

Man Page

• Add pdsh compatibility section to man page
• Consider separate pdsh(1) man page that redirects to bssh

3. Compatibility Test Suite

Create test scripts that verify pdsh command compatibility:

#!/bin/bash
# tests/pdsh_compat_test.sh

# Test basic host targeting
pdsh -w "node1,node2" "echo hello"

# Test range expansion
pdsh -w "node[1-5]" "hostname"

# Test fanout
pdsh -w "node[1-10]" -f 5 "uptime"

# Test exclusion
pdsh -w "node[1-10]" -x "node[3-5]" "hostname"

# Test timeout options
pdsh -w "node1" -t 5 -u 30 "sleep 1 && echo done"

Implementation Tasks

Installation

• Update Homebrew formula to create pdsh symlink (deferred to separate PR)
• Add post-install symlink creation to cargo install (deferred to separate PR)
• Create shell configuration examples (bash, zsh, fish)
• Add uninstall script to remove symlinks (deferred - covered in shell configs)

Documentation

• Add "pdsh Compatibility" section to README.md
• Create docs/pdsh-migration.md migration guide
• Create docs/pdsh-options.md option mapping reference
• Create docs/pdsh-examples.md usage examples
• Update CLI help text with pdsh compat information
• Add pdsh compatibility to CHANGELOG (will be done in release)

Testing

• Create tests/pdsh_compat/ test directory
• Implement basic pdsh command tests
• Implement hostlist expression tests
• Implement option mapping tests
• Create test runner script
• Add CI job for pdsh compatibility testing (deferred to separate PR)
• Create test matrix for different pdsh versions (future enhancement)

Documentation Structure

docs/
├── pdsh-migration.md      # Migration guide
├── pdsh-options.md        # Full option mapping reference
└── pdsh-examples.md       # Common use cases

tests/
└── pdsh_compat/
    ├── test_basic.sh
    ├── test_hostlist.sh
    ├── test_options.sh
    └── test_edge_cases.sh

Acceptance Criteria

• brew install bssh creates working pdsh symlink (deferred to Homebrew formula PR)
• Migration guide covers all common pdsh use cases
• Test suite passes on CI (tests created, CI integration deferred)
• Documentation is clear and complete
• Users can migrate from pdsh with minimal changes

Notes

• Consider creating a compatibility matrix comparing pdsh versions
• May want to add bssh pdsh-help command for pdsh-style help
• Document any intentional deviations from pdsh behavior