Merge branch 'docs/demo-recording'

Author: glocker

CHANGELOG.md

@@ -9,6 +9,11 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- A recorded demo in the README: one run showing the install, a PASS with its
+  exit code, the `--trace` wire output including the OBC's own command frame, a
+  thermal module closing a heater loop, and a deliberate failure exiting 1. The
+  session is scripted rather than hand-recorded, so it can be reproduced when
+  the CLI's output changes — see [`docs/demo/`](docs/demo/).
 - A documented, tested path to writing your own subsystem module:
   [`docs/writing-a-module.md`](docs/writing-a-module.md). It covers the
   module/FSM contract, the config dataclass that doubles as the

README.md

@@ -54,6 +54,14 @@ breakdown.
 
 ## Quickstart
 
+![Demo of a full run](https://raw.githubusercontent.com/glocker/CubeSatTestbed/main/docs/images/demo.gif)
+
+One run end to end: install, a PASS with its exit code, the wire trace proving
+assertions read frames off the bus, a thermal module closing a heater loop, and
+a deliberate failure exiting 1. Recorded from `main` — the published 1.0.0
+predates `init`, `--example` and `--trace`. The cast is scripted and
+re-recordable: see [`docs/demo/`](docs/demo/).
+
 ```sh
 pip install cubesat-testbed
 cubesat-testbed run --example default

docs/demo/README.md

@@ -0,0 +1,43 @@
+# Demo recording
+
+The GIF embedded in the top-level `README.md` is not hand-recorded. It is
+rendered from a scripted session so it can be reproduced whenever the CLI's
+output changes, instead of quietly drifting out of date the way a one-off
+screen capture does.
+
+- `demo.sh` — the content of the recording: the commands, the pacing, and the
+  short prompt it prints instead of whoever's real shell prompt. Run it
+  directly to iterate on the script without recording anything.
+- `record.sh` — wraps `demo.sh` in `asciinema`, renders the resulting cast to
+  `demo.gif` with `agg`, and installs both tools into `~/.local/bin` if they
+  are missing. Neither needs root.
+
+```sh
+docs/demo/record.sh
+cp docs/demo/demo.gif docs/images/demo.gif
+```
+
+`asciinema` needs a real TTY, so this cannot run from CI or a non-interactive
+session. Size the terminal to roughly 100x30 first: `asciinema` 2.x takes the
+frame size from the terminal it runs in (3.x is passed `--cols`/`--rows`).
+
+## What the recording has to show
+
+Two things are the point of the demo and should survive any edit:
+
+- **The wire trace.** The strongest claim this project makes is that an
+  assertion only ever observes telemetry by decoding a frame that crossed the
+  bus. `--trace` is what makes that visible, including the OBC's own
+  low-battery command as bytes.
+- **A deliberate failure with a non-zero exit code.** A demo where everything
+  passes says nothing about whether the tool would catch a regression. The
+  script breaks the injected battery level so the FDIR rule never trips, and
+  the assertion fails with the observed value — which is exactly what CI sees.
+
+## Installing from git
+
+`demo.sh` installs from `git+https://github.com/glocker/CubeSatTestbed@main`
+rather than from PyPI, because the published 1.0.0 predates `init`,
+`--example` and `--trace`; a demo of those commands cannot be recorded against
+it. Once a release carrying them is on PyPI, set `INSTALL_SPEC` at the top of
+`demo.sh` back to plain `cubesat-testbed` and re-record.

docs/demo/demo.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Scripted CubeSatTestbed demo -- the *content* of the recording.
+#
+# Run it through record.sh, which wraps it in asciinema and renders the GIF.
+# Running it directly also works and is the fastest way to iterate on the
+# script without recording anything.
+#
+# Deliberately not `set -e`: the last step is *supposed* to fail, and its
+# non-zero exit code is the point of the demo.
+set -u
+
+# PyPI still serves 1.0.0, which predates `init`, `--example` and `--trace`.
+# Until 1.1.0 is published the demo has to install from git; after that,
+# change this to just `cubesat-testbed` and re-record.
+INSTALL_SPEC="${INSTALL_SPEC:-git+https://github.com/glocker/CubeSatTestbed@main}"
+
+TYPE_DELAY="${TYPE_DELAY:-0.03}"   # seconds per typed character
+PAUSE="${PAUSE:-1.2}"              # pause after a command's output
+
+# A short prompt of our own: the recording must not show whatever host and
+# username happen to be running it.
+PROMPT_COLOR=$'\033[38;5;114m'
+COMMENT_COLOR=$'\033[38;5;245m'
+RESET=$'\033[0m'
+
+say() {
+    printf '%s# %s%s\n' "$COMMENT_COLOR" "$*" "$RESET"
+    sleep 0.9
+}
+
+type_cmd() {
+    printf '%s$%s ' "$PROMPT_COLOR" "$RESET"
+    local i
+    for ((i = 0; i < ${#1}; i++)); do
+        printf '%s' "${1:i:1}"
+        sleep "$TYPE_DELAY"
+    done
+    printf '\n'
+    sleep 0.35
+}
+
+run() {
+    type_cmd "$1"
+    eval "$1"
+    sleep "$PAUSE"
+}
+
+WORKDIR="$(mktemp -d)"
+cd "$WORKDIR"
+
+say "A CubeSat subsystem testbed: deterministic scenarios over a real CSP/CAN bus."
+say "Install it into a clean virtualenv."
+run "python3 -m venv .venv && . .venv/bin/activate && pip install -q $INSTALL_SPEC"
+run "cubesat-testbed init --list"
+
+say "Copy a packaged example out and run it: setup, scenario, PASS, exit code."
+run "cubesat-testbed init demo && cd demo"
+run "cubesat-testbed run -c setup.toml -s scenario.yaml; echo exit=\$?"
+
+say "Assertions never read Python state -- they decode frames off the bus."
+say "--trace prints every frame that actually crossed it."
+run "cubesat-testbed run --example default --trace 2>&1 | head -8"
+
+say "And the OBC's low-battery decision is on that same bus, as real bytes:"
+run "cubesat-testbed run --example default --trace 2>&1 | grep command | head -2"
+
+say "Subsystem behaviour lives in modules. Here a thermal node and an OBC"
+say "rule close a heater control loop entirely over that same bus."
+run "cubesat-testbed run --example thermal-heater"
+
+say "Now break it on purpose: inject a battery level that never trips the rule."
+say "The FDIR logic then never sheds the payload -- and the test must catch that."
+run "sed -i s/value:\\ 25/value:\\ 95/ scenario.yaml"
+run "cubesat-testbed run -c setup.toml -s scenario.yaml; echo exit=\$?"
+
+say "FAIL, with the observed value, and exit code 1. That is what CI sees."
+sleep 2

docs/demo/record.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Record demo.sh as an asciinema cast and render it to an animated GIF.
+#
+# Installs both tools into ~/.local/bin without root: asciinema is pure
+# Python, agg is a single static binary. Run this from a real terminal --
+# asciinema needs a TTY, which is the one thing a non-interactive session
+# cannot give it.
+set -euo pipefail
+
+AGG_VERSION="${AGG_VERSION:-v1.9.0}"
+
+# agg ships one binary per architecture and there is no universal build, so
+# pick by uname rather than assuming x86_64 -- guessing wrong fails late, at
+# render time, with a bare "Exec format error" after the cast is recorded.
+if [ -z "${AGG_TARGET:-}" ]; then
+    case "$(uname -m)" in
+        x86_64 | amd64) AGG_TARGET="x86_64-unknown-linux-musl" ;;
+        aarch64 | arm64) AGG_TARGET="aarch64-unknown-linux-gnu" ;;
+        armv7l | armv6l) AGG_TARGET="arm-unknown-linux-gnueabihf" ;;
+        *)
+            echo "no agg build for $(uname -m); set AGG_TARGET manually" >&2
+            exit 1
+            ;;
+    esac
+fi
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUT_DIR="${OUT_DIR:-$HERE}"
+CAST="$OUT_DIR/demo.cast"
+GIF="$OUT_DIR/demo.gif"
+
+BIN_DIR="$HOME/.local/bin"
+mkdir -p "$BIN_DIR" "$OUT_DIR"
+export PATH="$BIN_DIR:$PATH"
+
+if ! command -v asciinema >/dev/null 2>&1; then
+    echo "installing asciinema..."
+    if command -v uv >/dev/null 2>&1; then
+        uv tool install asciinema
+    else
+        python3 -m pip install --user asciinema
+    fi
+fi
+
+if ! command -v agg >/dev/null 2>&1 || ! agg --version >/dev/null 2>&1; then
+    echo "installing agg $AGG_VERSION for $AGG_TARGET..."
+    curl -fsSL -o "$BIN_DIR/agg" \
+        "https://github.com/asciinema/agg/releases/download/$AGG_VERSION/agg-$AGG_TARGET"
+    chmod +x "$BIN_DIR/agg"
+    # Fail here, not after a recording, if the binary still does not run.
+    agg --version >/dev/null
+fi
+
+rm -f "$CAST" "$GIF"
+
+# --cols/--rows exist in asciinema 3.x but not 2.x, where the pty simply
+# inherits the terminal. Probe instead of pinning a version: on 2.x, size
+# your terminal to about 100x30 before recording.
+REC_ARGS=(--idle-time-limit 1 --command "bash $HERE/demo.sh")
+if asciinema rec --help 2>&1 | grep -q -- '--cols'; then
+    REC_ARGS+=(--cols 100 --rows 30)
+fi
+
+echo "recording -> $CAST"
+asciinema rec "${REC_ARGS[@]}" "$CAST"
+
+echo "rendering -> $GIF"
+agg --font-size 16 --speed 1.3 --theme asciinema "$CAST" "$GIF"
+
+ls -lh "$GIF"
+echo
+echo "Preview it, then copy into the repo:"
+echo "  cp $GIF ~/CubesatTestbed/docs/images/demo.gif"