ci: add github action, update readme

2 files changed, 242 insertions, 0 deletions

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..1f92c63
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,81 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  publish:
+    name: ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+            use-cross: false
+
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-musl
+            use-cross: false
+
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+            use-cross: false
+
+          - os: macos-latest
+            target: x86_64-apple-darwin
+            use-cross: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 1
+
+      - name: Set the version
+        id: version
+        run: echo ::set-output name=VERSION::${GITHUB_REF#refs/tags/}
+
+      - name: Install Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          profile: minimal
+          override: true
+          target: ${{ matrix.target }}
+
+      - name: Build
+        uses: actions-rs/cargo@v1
+        with:
+          use-cross: ${{ matrix.use-cross }}
+          command: build
+          args:
+            --target ${{ matrix.target }} --release --locked --bin angelsharkcli
+
+      - name: Strip binary
+        if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest'
+        run: strip target/${{ matrix.target }}/release/angelsharkcli
+
+      - name: Upload nix binaries to release
+        if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest'
+        uses: svenstaro/upload-release-action@v1-release
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          file: target/${{ matrix.target }}/release/angelsharkcli
+          asset_name:
+            angelsharkcli-${{ steps.version.outputs.VERSION }}-${{ matrix.target
+            }}
+          tag: ${{ github.ref }}
+
+      - name: Upload Windows binaries to release
+        if: matrix.os == 'windows-latest'
+        uses: svenstaro/upload-release-action@v1-release
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          file: target/${{ matrix.target }}/release/angelsharkcli.exe
+          asset_name:
+            angelsharkcli-${{ steps.version.outputs.VERSION }}-${{ matrix.target
+            }}.exe
+          tag: ${{ github.ref }}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1b66410
--- /dev/null
+++ b/README.md
@@ -0,0 +1,161 @@
+# Altruistic Angelshark
+
+[![Conventional git style](https://img.shields.io/badge/git%20style-conventional%20commit-blue)](https://conventionalcommits.org/)
+
+Angelshark is a collection of programs that make automating over Communication
+Managers (ACMs) easier. It uses the OSSI protocol over SSH to run user commands
+on one or more configurable ACMs. This functionality is exposed as a developer
+library (`libangelshark`), a command line application (`angelsharkcli`), and an
+HTTP daemon (`angelsharkd`).
+
+## Detailed User Guides
+
+These guides give an overview of the end-user Angelshark programs, their
+capabilities, and common use cases. It assumes the user has familiarity with
+using a shell and the command line. Some of the commands may be formatted for
+\*nix, others for Windows. They should all be directly translatable, just make
+sure you're using (for example) `./angelsharkcli` for \*nix and
+`./angelsharkcli.exe` for Windows.
+
+- [`angelsharkcli`](angelsharkcli/README.md): a command line application for
+  running OSSI-formatted commands on one or more ACMs and parses the output data
+  into useful formats (CSV, JSON, etc.)
+- [`angelsharkd`](angelsharkd/README.md): a HTTP service for running
+  OSSI-formatted commands formatted in JSON on one or more ACMs, by one or more
+  clients
+
+## Installation
+
+`angelsharkcli` is available as a prebuilt binary for many platforms in the
+GitHub releases. You may also build it from scratch with
+[`cargo`](https://rustup.rs):
+
+```sh
+cargo install --path angelsharkcli
+```
+
+To build and install `angelsharkd`:
+
+```sh
+cargo install --path angelsharkd
+```
+
+## Quick Examples
+
+Get the numbers and names of all stations on a single ACM via the CLI.
+
+```sh
+$ printf 'aCM01\nclist stat\nf8005ff00\nf8003ff00\nt\n' | angelsharkcli print
+17571230001    Doe, Jane
+17571230002    Doe, John
+17571230003    Conference Rm. 1
+```
+
+Check three ACMs for a station and print it as JSON via the CLI.
+
+```sh
+$ angelsharkcli print <<EOF
+aCM01
+aCM02
+aCM03
+clist stat 17571230009
+f8005ff00
+f8003ff00
+t
+EOF
+angelsharkcli: ossi: error: 1 00000000 29cf No records match the specified query options
+angelsharkcli: ossi: error: 1 00000000 29cf No records match the specified query options
+[
+  [
+    "17571230009",
+    "Carpenter, Adam"
+  ]
+]
+```
+
+Do the same thing over HTTP via `curl`.
+
+```sh
+$ nohup angelsharkd &
+nohup: ignoring input and appending output to 'nohup.out'
+$ curl -X POST http://localhost:80/ossi \
+    -H 'Content-Type: application/json' \
+    -d '[
+    {
+        "acms": [ "CM01", "CM02", "CM03" ],
+        "command": "list stat 17571230009",
+        "fields": ["8005ff00", "8003ff00"]
+    }
+]'
+
+[
+    {
+        "acm": "CM01",
+        "command": "list stat 17571230009",
+        "fields": [ "8005ff00", "8003ff00" ],
+        "datas": [ [ "17571230001", "Carpenter, Adam", ] ],
+        "error": ""
+    },
+    {
+        "acm": "CM02",
+        "command": "list stat 17571230001",
+        "fields": [ "8005ff00", "8003ff00" ],
+        "datas": [ [] ],
+        "error": "1 00000000 29cf No records match the specified query options"
+    }
+    {
+        "acm": "CM03",
+        "command": "list stat 17571230001",
+        "fields": [ "8005ff00", "8003ff00" ],
+        "datas": [ [] ],
+        "error": "1 00000000 29cf No records match the specified query options"
+    }
+]
+
+$ cat nohup.out
+[2021-07-21T16:57:12Z INFO  angelsharkd] Reading config...
+[2021-07-21T16:57:12Z INFO  angelsharkd] Initializing command runner...
+[2021-07-21T16:57:12Z INFO  angelsharkd] Starting server...
+[2021-07-21T16:58:49Z INFO  angelsharkd::activity_log] {"status":"200 OK","method":"POST","uri":"/ossi","commands":[{"acms":["CM01","CM02","CM03"],"command":"list stat 17571230009","fields":["8005ff00","8003ff00"],"datas":null}]}
+```
+
+## Why should I use Angelshark? Why might it be preferable to ASA or other projects?
+
+- Angelshark is cross-platform. It is available for Windows, Mac OSX, Linux, and
+  FreeBSD. Angelshark should run on anything that can compile it. If statically
+  linked, no runtime dependencies are required.
+- It requires no graphical desktop to generate the same output as ASA, making it
+  more versatile for servers or containers.
+- Angelshark executables are super-fast binaries and commands are run in
+  parallel across multiple ACMs to deliver output faster.
+- Angelshark does not need or use waits or timeouts (such as one would see with
+  `expect` scripts).
+- Angelshark can parse ACM output data into a variety of useful formats
+  including tab-delimited (TSV), CSV, and JSON.
+- The command line is easily scripted with login configuration, command files,
+  and task schedulers such as Cron. It outputs tab-delimited data by default,
+  making it friendly for `sed`, `grep`, and `awk`.
+- It is extensible, allowing developers to use the daemon or the library to
+  write their own software on top of Angelshark!
+- Angelshark uses `libssh` internally and will work on platforms without an SSH
+  client, such as OpenSSH.
+
+``````plain
+                                                  `r***`
+                                                _i?`  .|v-
+                                              <x>        ^x:
+                                            rx_            =]~  `-'
+                                _^**^**=` -V,                X]*<!~^*r*
+:r*:                        rr**"      '<*n                 ,nl`?#i   `}~   *_
+H  _r?r`                   (~                                 i"_n,     l~~|?
+5     `*(r`            ``'_P`                                         <` 0_
+P        `*^^^^^^^^^^^>!=:,-`'-,,:=!~><<^^^^**^^^^<<~~!=:,,-'`        !i H
+5          `````.''-__,,,::"                                          =.-q^*x
+H      :rrr>~!!==::,,,_--'.Z                                , y`6@=    -e`  r`
+xr=**rr"                   n_                               ??"!~]`  !|?
+ ..                        `}r:`         '(`                 ,Hx^^^^*-
+                              -<***^^^^r(<H`                 }<
+                                      `   :(r~`            '2,
+                                             `<****=`    `vv
+                                                   .!*^^^r`
+``````