feat: Add SSH isolation support for remote command execution

[konard]

Summary

This PR implements SSH isolation support for executing commands on remote servers via SSH, addressing issue #31.

The implementation follows the same pattern as existing isolation backends (screen, tmux, docker), providing a consistent user experience while enabling remote command execution.

Implementation Details

Core Features

• SSH Backend: New runInSsh() function in src/lib/isolation.js
• Attached Mode: Direct SSH connection with interactive session
• Detached Mode: Background execution using nohup on remote server with log file capture
• Endpoint Option: New --endpoint CLI option to specify SSH target (e.g., [email protected])
• Session Support: Custom session names via --session option

Changes Made

1. src/lib/isolation.js:

   • Added runInSsh() function implementing both attached and detached modes
   • Updated runIsolated() dispatcher to include SSH backend
   • Exported runInSsh in module exports

2. src/lib/args-parser.js:

   • Added ssh to VALID_BACKENDS array
   • Added --endpoint option parser (both --endpoint value and --endpoint=value formats)
   • Added endpoint property to wrapperOptions
   • Added validation requiring --endpoint when using SSH isolation
   • Added validation ensuring --endpoint is only used with SSH

3. src/bin/cli.js:

   • Updated help text to include SSH in isolation backends list
   • Added --endpoint option to help output
   • Added SSH usage example
   • Updated runWithIsolation() to pass endpoint option to isolation backend
   • Added endpoint logging when using SSH isolation

4. README.md:

   • Updated Process Isolation section with SSH backend
   • Added SSH to Supported Backends table
   • Added --endpoint to Isolation Options table
   • Added SSH usage example

5. test/isolation.test.js:

   • Added SSH availability check test
   • Added error handling tests for SSH (missing ssh command, missing endpoint)
   • Following the same pattern as screen/tmux/docker tests

6. test/args-parser.test.js:

   • Added --endpoint option parsing tests
   • Added SSH validation tests

7. test/ssh-integration.test.js (new file):

   • Comprehensive SSH integration tests
   • Tests attached mode, detached mode, error handling
   • Tests command execution with arguments, environment variables, special characters
   • Designed to run in CI with a local SSH server

8. .github/workflows/release.yml:

   • Added SSH server setup for Linux integration tests
   • Generates SSH keys, configures passwordless localhost SSH
   • Runs SSH integration tests on Linux

Usage Examples

# Run command on remote server (attached mode)
$ --isolated ssh --endpoint [email protected] -- npm test

# Run in background on remote server (detached mode)
$ --isolated ssh --endpoint [email protected] --detached -- npm start

# Short form with custom session name
$ -i ssh --endpoint user@server -s my-session -d npm start

Testing

All tests pass:

• ✅ Unit tests for SSH isolation (error handling, availability checks)
• ✅ Unit tests for --endpoint option parsing
• ✅ Integration tests with local SSH server (Linux CI)
• ✅ Linting and formatting checks pass
• ✅ Pre-commit hooks passed

Notes

• SSH must be installed on the system (openssh-client on Debian/Ubuntu, openssh on macOS)
• Detached mode logs are saved to /tmp/<session-name>.log on the remote server
• Follows the same pattern and conventions as existing isolation backends

Fixes #31

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $4.665101 USD
• Calculated by Anthropic: $2.719040 USD
• Difference: $-1.946061 (-41.72%)
  📎 Log file uploaded as GitHub Gist (929KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

We should rename --host to --endpoint, install our own SSH server locally in GitHub Actions, and test that we can connect to our own SSH server. These tests should be added in CI, so we will be absolutely sure each and and every feature will work as expected, if there any problem with installing SSH server on the host machine of GitHub Actions - we can just use a docker image with ssh server running.

Think of the most reliable way possible to make sure we test everything.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2025-12-25T09:16:43.788Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $5.717945 USD
• Calculated by Anthropic: $3.781167 USD
• Difference: $-1.936779 (-33.87%)
  📎 Log file uploaded as GitHub Gist (900KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2025-12-26T21:23:16.335Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $2.405637 USD
• Calculated by Anthropic: $1.285927 USD
• Difference: $-1.119710 (-46.55%)
  📎 Log file uploaded as GitHub Gist (666KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.