# cloyster: a shell wrapper for machine-oriented shell scripts

_cloyster_ helps you making small, as portable as possible, single-task focused shell scripts
that are primarily consumed by other scripts or machines.

_cloyster_ provides a portable utilitary functions library to help you be efficient transforming
and manipulating data.

_cloyster_ scripts are called "commands". A good command does a single thing/action
(list something, create an interface, bridge an interface, ...).

Being machine-oriented and automation-oriented, commands accepts arguments as JSON, and return
JSON: this also to easily combine and use commands in commands, filter outputs easily (using `jq`),
pipe them together...

**Base dependencies**: POSIX shell, jq, jo

## Scripting commands

A command is a POSIX shell script, using `/usr/local/libexec/cloyster` as shebang.

It will run in the _cloyster_ environment and has three outputs:

- the standards outputs, stdout and stderr, which acts as usual: unstructured, line based text, automatically
  handled by _cloyster_ and returned as `output`,
- the structured JSON result of your command, set by calling `return_result`, returned as `result`.
- a structured JSON fatal error, set by calling `return_error`, returned as `error`.

### API

* `return_result JSON|JO` exits successfully with a JSON result
* `return_error JSON|JO [exit_code=1]` exists with exit_code and a JSON error
* `args_get [JQ_QUERY=.]` query the arguments using jq

### Utilitary Functions

* `ensure_command_exists BINARY` ensures a binary exists, exits with error if not
* `os_get [KEY=.|jq] [JQ_QUERY]` operating system version (type, name, pretty_name, version, version_id, supported)
* `make_random_identifier [SIZE=32]`
* `date_now_iso_utc`
* `posix_time_microseconds`

### Arguments/Input

Arguments, or inputs to the command, are also passed in JSON. You have three ways of passing the arguments:

* human friendly: `COMMAND arg1=something ...` (uses `jo`),
* escaped json string: `COMMAND '{"something": true}'`
* json wrapped in base64: `COMMAND -b eyJiYW5uZXIiOiJiZWFzdGllIGZvciB0aGUgd2luIn0K`

### Output

```js
{
  "error": null /* Error */,
  "exit_status": 0,
  "command": "./commands/ifconfig-interfaces-list.sh",
  "arguments": {},
  "duration_microseconds": /* microseconds */,
  "started_at_utc": /* ISO8061Z */,
  "finished_at_utc": /* ISO8061Z */,
  "result": /* any */,
  "output": [
    // Output Line
  ]
}
```

Output Line:

```js
{"output": "stdout|stderr", "date":"ISO8061Z", line: "...."}
```

Error:

```js
{
  "type": "execution|command",
  "error": "error_name",
  // Error specific field
}
```

### Reading script from stdin

You can tell _cloyster_ to execute a script from stdin by setting the `-s` or `-` option to `cloyster`:

```sh
cat commands/ifconfig-interfaces-list | cloyster -s
cloyster - <<EOF
json=$(jls --libxo json | jq -r '.["jail-information"].jail | @json')
set_result "${json}"
EOF
```

### Examples

#### Example: `commands/ifconfig-interfaces-names.sh`

```sh
#!/usr/local/libexec/cloyster
echo "stdout something"
>&2 "stderr something"
set_result $(ifconfig | grep -E "^[a-z0-9_]+:" | cut -d ':' -f 1 | jq -nRr '[inputs | select(length>0)] | @json')
```

Run it (piped to `jq` so you beautify JSON output):

```sh
./commands/ifconfig-interfaces-names.sh | jq
```

Result:

```json
{
  "error": false,
  "exit_status": 0,
  "command": "./commands/ifconfig-interfaces-list.sh",
  "arguments": [],
  "duration_microseconds": 67,
  "started_at_utc": "2022-03-22T09:28:51Z",
  "finished_at_utc": "2022-03-22T09:28:51Z",
  "result": ["eth0", "eth1", "lo0"],
  "output": [
    {"output": "stdout", "date":"iso8601 utc", line: "stdout something"},
    {"output": "stderr", "date":"iso8601 utc", line: "stderr something"}
  ]
}
```

## Code guide

meh

* We write POSIX Shell compliant code.
* Use `shellcheck`.
* Variables:
  * are considered private/local if they begin by a `_`
  * are considered public if they are in lowercase
  * are exported/env if they are in uppercase
* Cloyster itself must be portable (POSIX Shell) and should be able to work on macOS, Linux, ...
*