feat: Implement server CLI interface (bssh-server binary) (#131)

[inureyes]

Summary

This PR implements the bssh-server binary with a comprehensive CLI interface for starting and managing the SSH server, resolving issue #131.

Implementation Details

Commands Implemented

• run - Start the SSH server (default command)
• gen-config - Generate configuration file template
• hash-password - Hash passwords for configuration using bcrypt
• check-config - Validate configuration files
• gen-host-key - Generate SSH host keys (Ed25519/RSA)
• version - Show version and build information

Global CLI Arguments

• -c, --config - Configuration file path
• -b, --bind-address - Bind address override
• -p, --port - Port override
• -k, --host-key - Host key file(s) override
• -v, --verbose - Verbosity level (repeatable: -v, -vv, -vvv)
• -D, --foreground - Run in foreground
• --pid-file - PID file path

Features

✓ Configuration loading from YAML files with CLI overrides
✓ Signal handling for graceful shutdown (SIGTERM, SIGINT)
✓ Password hashing with bcrypt (cost factor 12)
✓ SSH host key generation (Ed25519 recommended, RSA supported)
✓ Configuration validation and checking
✓ Proper error handling and exit codes
✓ Integration with existing ServerFileConfig from #130

Technical Changes

• Created src/bin/bssh_server.rs with full CLI implementation
• Updated Cargo.toml to add binary target and dependencies:
  • bcrypt 0.16 for password hashing
  • rand 0.8 for key generation
  • ssh-key 0.6 for key file operations
• Added bssh-server.yaml to .gitignore

Testing

• ✓ All commands compile and run successfully
• ✓ CLI help output verified
• ✓ Config generation works
• ✓ Host key generation tested (Ed25519/RSA)
• ✓ All clippy checks pass with -D warnings

Usage Examples

# Generate host key
bssh-server gen-host-key -t ed25519 -o /etc/bssh/host_key

# Generate config template
bssh-server gen-config -o /etc/bssh/server.yaml

# Hash a password
bssh-server hash-password

# Check configuration
bssh-server check-config -c /etc/bssh/server.yaml

# Start server
bssh-server -c /etc/bssh/server.yaml -k /etc/bssh/host_key

Related Issues

• Resolves Create server CLI interface (bssh-server binary) #131
• Depends on Create server configuration system #130 (ServerFileConfig implementation)
• Part of Implement bssh-server with SFTP/SCP support #123 (bssh-server epic)

Checklist

• Binary compiles and runs
• Clap-based CLI with subcommands
• Configuration file loading
• CLI argument overrides
• Signal handling for graceful shutdown
• gen-config command works
• hash-password command works
• check-config command works
• gen-host-key command works
• Proper exit codes
• Tests passing (clippy)

[inureyes]

PR Finalization Report

Project Structure Discovered

• Project Type: Rust
• Test Framework: cargo test
• Documentation System: Plain markdown (ARCHITECTURE.md + docs/architecture/)
• Multi-language Docs: No
• Lint Tools: cargo fmt, cargo clippy

Checklist

Tests

• Analyzed existing test structure (2 existing tests in bssh_server.rs)
• Identified missing test coverage
• Generated 19 new tests:
  • CLI parsing tests (subcommands, global options, gen-host-key options)
  • CliArgs conversion tests (empty, multiple host keys)
  • gen_config tests (stdout, file output, file permissions)
  • gen_host_key tests (ed25519, rsa, invalid type, small bits, case insensitive, permissions)
  • write_pid_file tests (basic, stale PID, invalid content)
  • Default command test
  • show_version test
• All 21 tests passing

Documentation

• ARCHITECTURE.md updated (added Server CLI Binary section with full command documentation)
• docs/architecture/README.md updated (added server CLI references, updated code organization)
• docs/architecture/server-configuration.md updated (added Server CLI Commands section)

Code Quality

• cargo fmt: All formatting issues fixed
• cargo clippy -- -D warnings: No warnings
• All tests pass

Changes Made

• src/bin/bssh_server.rs: Added 19 comprehensive unit tests covering:

  • All CLI subcommands (run, gen-config, hash-password, check-config, gen-host-key, version)
  • Global CLI options parsing (-c, -b, -p, -k, -v, -D, --pid-file)
  • Configuration file generation with permission validation
  • Host key generation for both Ed25519 and RSA types
  • PID file management including stale PID detection
  • Fixed formatting issues identified by cargo fmt

• ARCHITECTURE.md: Added new "Server CLI Binary" section documenting:

  • All subcommands with descriptions
  • Global options
  • Usage examples

• docs/architecture/README.md:

  • Added server CLI to Server Components section
  • Added server CLI to Quick Reference
  • Updated Code Organization to include src/bin/

• docs/architecture/server-configuration.md:

  • Added new "Server CLI Commands" section with examples for all commands

Verification Results

cargo fmt --check    # PASS
cargo clippy -- -D warnings    # PASS
cargo test --bin bssh-server    # 21 tests passed