docs: demo on readme, better docs and images (#8)

.gitignore

@@ -3,3 +3,4 @@ jspm_packages
 package-lock.json
 boxes.json
 artifacts/
+.DS_Store

README.md

@@ -4,15 +4,13 @@
 
 Quickly turn on, turn off, list and connect to your AWS instances. Great for saving costs by running servers in the cloud and starting them only when needed.
 
-TODO demo recording
+![Recording of a terminal session that shows the boxes CLI in action](./docs/democast.svg)
 
 ## Quickstart
 
 Tag any AWS instance you want to control with a tag named `boxes.boxid`:
 
-TODO smaller screenshot
-
-![Screenshot: The AWS EC2 Instances console showing two boxes and the boxid tag](./docs/aws-instance-tags.png)
+<img alt="Screenshot: The AWS EC2 Instances console showing two boxes and the boxid tag" src="https://github.com/dwmkerr/boxes/raw/main/docs/aws-instance-tags.png" width="48">
 
 In this screenshot I have two instances tagged, one with the value `steambox` (used for gaming) and one with `torrentbox` (for fast BitTorrent downloads).
 
@@ -22,9 +20,7 @@ Install the Boxes CLI with:
 npm install @dwmkerr/boxes
 ```
 
-You can now list your boxes with `list` and start or stop them with `start` and `stop`:
-
-![Screen recording: TODO]()
+You can now list your boxes with `list` and start or stop them with `start` and `stop`.
 
 The following commands are available for `boxes`:
 
@@ -121,7 +117,6 @@ The `boxes ssh` command can be used to quickly ssh into a box. Provide the ssh c
   "boxes": {
     "torrentbox": {
       "sshCommand": "ssh -i /Users/dwmkerr/repos/github/dwmkerr/dwmkerr/tf-aws-dwmkerr/dwmkerr_aws_key.pem ec2-user@${host}"
-"
     }
   }
 }
@@ -164,17 +159,14 @@ Boxes manages EC2 instances that have a tag with the name `boxes.boxid`.
 
 ## Terminal Recording / asciinema
 
-The recording at the top of the README file is an SVG based on an [asciinema](https://asciinema.org/) recording that has been converted to SVG with [svg-term-cli](https://github.com/marionebl/svg-term-cli).
-
-To update the recording:
-
-1. Install asciinema `brew install asciinema`
+To create a terminal recording for the documentation:
 
-To record a Tmux session, you will need to start _detached_ from Tmux and then attach. You can do this by hand, simply using `tmux attach`, but this adds some noise to the beginning of the recording. A better way is to use the command below:
-
-```bash
-asciinema rec --command "tmux attach [-t session-name]"
-```
+- Install [asciinema](https://asciinema.org/) `brew install asciinema`
+- Check that you have your profiles setup as documented in `./scripts/record-demo.sh`
+- Run the script to start a 'clean' terminal `./scripts/record-demo.sh`
+- Download your recording, e.g. to `./docs/620124.cast`
+- Install [svg-term-cli](https://github.com/marionebl/svg-term-cli) `npm install -g svg-term-cli`
+- Convert to SVG: `svg-term --in ./docs/620124.cast --out docs/democast.svg --window --no-cursor --from=1000`
 
 ## Dependencies
 
@@ -192,9 +184,9 @@ Quick and dirty task-list.
 - [x] npm badge download link
 - [x] bug: package.json path
 - [x] build / lint / test / deploy pipeline
-- [ ] screen recording of boxes list / stop / start / connect
-- [ ] document how 'connect' works
-- [ ] feat: ssh connect
+- [x] screen recording of boxes list / stop / start / connect
+- [x] document how 'connect' works
+- [x] feat: ssh connect
 - [ ] docs: make AWS screenshot a bit smaller in readme
 - [ ] Cost management tags configuration to allow pricing info
 - [ ] docs: create and share blogpost

cli.js

@@ -8,7 +8,8 @@ import theme from "./theme.js";
 //  node.
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
-const packageJson = require("./package.json");
+const pathName = require.resolve("./package.json");
+const packageJson = require(pathName);
 
 const program = new Command();
 program

docs/620124.cast

@@ -0,0 +1,88 @@
+{"version": 2, "width": 80, "height": 15, "timestamp": 1699552835, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}
+[2.466846, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                               \r \r\u001b]2;dwmkerr@M-C02GM0C4MD6W:~\u0007\u001b]1;~\u0007"]
+[2.470209, "o", "\u001b]7;file://M-C02GM0C4MD6W/Users/dwmkerr\u001b\\"]
+[2.487209, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\r\n\u001b[1m\u001b[34m~\u001b(B\u001b[m \r\n\u001b[1m\u001b[37m%\u001b(B\u001b[m \u001b[K"]
+[2.487443, "o", "\u001b[?1h\u001b="]
+[2.487701, "o", "\u001b[?2004h"]
+[3.085836, "o", "b"]
+[3.240263, "o", "\bbo"]
+[3.32951, "o", "x"]
+[3.543513, "o", "e"]
+[3.608813, "o", "s"]
+[3.708517, "o", " "]
+[3.864636, "o", "l"]
+[3.984628, "o", "s"]
+[4.113332, "o", "\u001b[?1l\u001b>"]
+[4.113384, "o", "\u001b[?2004l\r\r\n"]
+[4.114693, "o", "\u001b]2;boxes ls\u0007\u001b]1;boxes\u0007"]
+[6.576788, "o", "\u001b[37m\u001b[1msteambox\u001b[22m\u001b[39m: \u001b[31mstopped\u001b[39m\r\n"]
+[6.576827, "o", "  Name: Steam Box\r\n"]
+[6.577025, "o", "\u001b[37m\u001b[1mtorrentbox\u001b[22m\u001b[39m: \u001b[32mrunning\u001b[39m\r\n  Name: Torrent Box\r\n  DNS: ec2-54-149-102-61.us-west-2.compute.amazonaws.com\r\n"]
+[6.577052, "o", "  IP: 54.149.102.61\r\n"]
+[6.587465, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                               \r \r"]
+[6.587499, "o", "\u001b]2;dwmkerr@M-C02GM0C4MD6W:~\u0007\u001b]1;~\u0007"]
+[6.591195, "o", "\u001b]7;file://M-C02GM0C4MD6W/Users/dwmkerr\u001b\\"]
+[6.607757, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\r\n\u001b[1m\u001b[34m~\u001b(B\u001b[m \r\n\u001b[1m\u001b[37m%\u001b(B\u001b[m \u001b[K"]
+[6.607939, "o", "\u001b[?1h\u001b="]
+[6.608028, "o", "\u001b[?2004h"]
+[7.796396, "o", "b"]
+[7.920805, "o", "\bbo"]
+[8.047564, "o", "x"]
+[8.515093, "o", "e"]
+[8.603128, "o", "s"]
+[8.730474, "o", " "]
+[8.890789, "o", "s"]
+[9.027785, "o", "t"]
+[9.094546, "o", "a"]
+[9.172, "o", "r"]
+[9.243816, "o", "t"]
+[9.354994, "o", " "]
+[9.510634, "o", "s"]
+[9.596419, "o", "t"]
+[9.658548, "o", "e"]
+[9.742389, "o", "a"]
+[9.844931, "o", "m"]
+[10.101993, "o", "b"]
+[10.190474, "o", "o"]
+[10.301566, "o", "x"]
+[10.453033, "o", "\u001b[?1l\u001b>"]
+[10.45319, "o", "\u001b[?2004l\r\r\n"]
+[10.454544, "o", "\u001b]2;boxes start steambox\u0007\u001b]1;boxes\u0007"]
+[13.042577, "o", "  \u001b[37m\u001b[1msteambox\u001b[22m\u001b[39m (i-098e8d30d5e399b03): \u001b[31mstopped\u001b[39m -> \u001b[33mpending\u001b[39m\r\n"]
+[13.054534, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                               \r \r"]
+[13.054574, "o", "\u001b]2;dwmkerr@M-C02GM0C4MD6W:~\u0007\u001b]1;~\u0007"]
+[13.059034, "o", "\u001b]7;file://M-C02GM0C4MD6W/Users/dwmkerr\u001b\\"]
+[13.076873, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\r\n\u001b[1m\u001b[34m~\u001b(B\u001b[m \r\n\u001b[1m\u001b[37m%\u001b(B\u001b[m \u001b[K"]
+[13.077061, "o", "\u001b[?1h\u001b="]
+[13.077165, "o", "\u001b[?2004h"]
+[13.931367, "o", "b"]
+[14.602968, "o", "\bbo"]
+[14.732315, "o", "x"]
+[15.015553, "o", "e"]
+[15.038521, "o", "s"]
+[15.162844, "o", " "]
+[15.531655, "o", "s"]
+[15.671802, "o", "s"]
+[15.758503, "o", "h"]
+[15.851143, "o", " "]
+[16.390448, "o", "t"]
+[16.505791, "o", "o"]
+[16.638439, "o", "r"]
+[16.78592, "o", "r"]
+[16.857885, "o", "e"]
+[16.949987, "o", "n"]
+[17.030032, "o", "t"]
+[17.250174, "o", "b"]
+[17.355355, "o", "o"]
+[17.442323, "o", "x"]
+[17.845435, "o", "\u001b[?1l\u001b>"]
+[17.845502, "o", "\u001b[?2004l\r\r\n"]
+[17.847002, "o", "\u001b]2;boxes ssh torrentbox\u0007\u001b]1;boxes\u0007"]
+[19.208474, "o", "ssh -i /Users/dwmkerr/repos/github/dwmkerr/dwmkerr/tf-aws-dwmkerr/dwmkerr_aws_key.pem ec2-user@ec2-54-149-102-61.us-west-2.compute.amazonaws.com\r\n"]
+[19.217744, "o", "\u001b[1m\u001b[7m%\u001b[27m\u001b[1m\u001b[0m                                                                               \r \r"]
+[19.21787, "o", "\u001b]2;dwmkerr@M-C02GM0C4MD6W:~\u0007\u001b]1;~\u0007"]
+[19.221501, "o", "\u001b]7;file://M-C02GM0C4MD6W/Users/dwmkerr\u001b\\"]
+[19.237673, "o", "\r\u001b[0m\u001b[27m\u001b[24m\u001b[J\r\n\u001b[1m\u001b[34m~\u001b(B\u001b[m \r\n\u001b[1m\u001b[37m%\u001b(B\u001b[m \u001b[K"]
+[19.237891, "o", "\u001b[?1h\u001b="]
+[19.237971, "o", "\u001b[?2004h"]
+[22.067614, "o", "\u001b[?2004l\r\r\n"]

scripts/record-demo.sh

@@ -0,0 +1,13 @@
+# For this script to work:
+# 1. make sure you have an iterm profile named 'dwmkerr-recording'
+# 2. This profile should run the command: `/usr/local/bin/bash --noprofile --norc -c 'export TMUX="ignore"; bash'`
+# 3. The profile should be windowed, and sized to 80x15.
+osascript <<EOF
+tell application "iTerm"
+    set newWindow to (create window with profile "dwmkerr-recording")
+    tell current session of newWindow
+        write text "clear"
+        write text "asciinema rec"
+    end tell
+end tell
+EOF