# Runner

Simple c++ demonstration program of the dropshell runner library.

use:
    runner BASE64COMMAND

BASE64COMMAND is Base64 encoded json. The json format is as described below. The exit code is that of the command run, or -1 if the command couldn't be run.

The c++ library used, which is contained in this codebase, has two simple functions:
   bool runner(nlohmann::json run_json); // no output capture
   bool runner(nlohmann::json run_json, std::string & output); // with output capture.

## JSON Specification

```json
{
  "ssh": {                      // Optional: SSH connection information
    "host": "hostname",         // Remote host to connect to
    "port": 22,                 // Port number (default: 22)
    "user": "username",         // Username for SSH connection
    "key": "path/to/key"        // Path to SSH key file or "auto" to use current user's key
  },
  "env": {                      // Optional: Environment variables
    "VAR1": "value1",
    "VAR2": "value2"
  },
  "command": "command_name",    // Required: Command to execute
  "args": ["arg1", "arg2"],     // Optional: Command arguments
  "options": {                  // Optional: Execution options
    "silent": false,            // Suppress all terminal output (default: false)
    "interactive": false        // Hook up TTY for interactive sessions (default: false)
  }
}
```

If SSH information is provided, the command will be executed on the remote server.

## Build Instructions

### Prerequisites

- CMake 3.10 or newer
- C++17 compatible compiler
- libssh development libraries
- jq (for the helper scripts)

#### Installing Dependencies

##### Quick Installation (Ubuntu/Debian)

For Ubuntu/Debian systems, you can use the provided installation script:

```bash
sudo ./install_deps.sh
```

This will install all required dependencies (cmake, g++, libssh-dev, jq).

##### Manual Installation

###### Ubuntu/Debian

```bash
sudo apt-get install cmake g++ libssh-dev jq
```

###### CentOS/RHEL

```bash
sudo yum install cmake gcc-c++ libssh-devel jq
```

###### macOS

```bash
brew install cmake libssh jq
```

###### Windows

Using vcpkg:

```bash
vcpkg install libssh nlohmann-json
```

### Building

To build the project, you can use the provided build script:

```bash
./build.sh
```

Or manually:

```bash
mkdir -p build
cd build
cmake ..
make
```

The executable will be created at `build/runner`.

### Testing

A simple test script is included to verify the functionality:

```bash
./test.sh
```

This will run basic tests for command execution, environment variables, silent mode, and return codes.

If you have SSH configured on your local machine and want to test the SSH functionality:

```bash
ENABLE_SSH_TEST=1 ./test.sh
```

### Troubleshooting

If CMake cannot find libssh, you can:

1. Run the libssh finder script to locate your installation:
   ```bash
   ./examples/find_libssh.sh
   ```

2. Specify its location manually:
   ```bash
   cmake -DCMAKE_PREFIX_PATH=/path/to/libssh/installation ..
   ```

3. Or set the libssh_DIR environment variable:
   ```bash
   export libssh_DIR=/path/to/libssh/installation
   cmake ..
   ```

4. If the problem persists, specify the library and include paths directly:
   ```bash
   cmake -DLIBSSH_LIBRARY=/path/to/libssh.so -DLIBSSH_INCLUDE_DIR=/path/to/include ..
   ```

## Usage Examples

### Running a local command

```bash
# Create a JSON configuration for the 'ls -l' command
JSON='{"command":"ls","args":["-l"]}'

# Base64 encode the JSON
BASE64=$(echo -n "$JSON" | base64)

# Run the command
./build/runner $BASE64
```

### Running a command with environment variables

```bash
# Create a JSON configuration with environment variables
JSON='{"command":"echo","args":["$GREETING"],"env":{"GREETING":"Hello, World!"}}'

# Base64 encode the JSON
BASE64=$(echo -n "$JSON" | base64)

# Run the command
./build/runner $BASE64
```

### Running a command on a remote server via SSH

```bash
# Create a JSON configuration for a remote command
JSON='{"ssh":{"host":"example.com","user":"username","key":"auto"},"command":"hostname"}'

# Base64 encode the JSON
BASE64=$(echo -n "$JSON" | base64)

# Run the command
./build/runner $BASE64
```

### Running an interactive command

```bash
# Create a JSON configuration for an interactive command
JSON='{"command":"vim","options":{"interactive":true}}'

# Base64 encode the JSON
BASE64=$(echo -n "$JSON" | base64)

# Run the command
./build/runner $BASE64
```

### Using the helper script

The `run.sh` script simplifies testing by handling the JSON validation and Base64 encoding:

```bash
# Run with a JSON file
./run.sh examples/local_command.json

# Run with a JSON string
./run.sh '{"command":"echo","args":["Hello World"]}'
```