Cue Light

Cue Light runs the commands in a plain-text cue file one at a time, and only after two separate key presses: Space (Standby), then Enter (Go); Enter on its own is refused and nothing runs. However the show ends, it writes a stage manager's show report in the current directory. Its real input is a cue file a person wrote, the shell commands in it, the keyboard of a real terminal (it refuses to run without one), the clock and the exit codes of those commands; ship.cues in this folder is the real runbook for this tool. Use it for the three commands you hesitate over.

Run

From this folder, with Python 3.9 or later on macOS or Linux (no packages, no network):

uv run python cuelight.py ship.cues a live show uv run python cuelight.py --rehearse ship.cues a rehearsal: nothing runs, every cue is checked uv run python cuelight.py -h usage uv run python -m unittest -v test_cuelight the tests (they drive the tool through a pty) uv run python qa/e2e.py the end to end run in tmux, captures into out/

The cue file

# Lines starting with # are comments. Blank lines are ignored. Show: Friday migration

10 Snapshot the database $ pg_dump app > snap.sql 20 Run the migration $ ./migrate.sh

A cue is a number at column 0, spaces and a label, followed by exactly one indented line that starts with $ and holds the command. Numbers must rise down the file; gaps are allowed, so a cue can later be slipped in as 15. Show: sets the title and may appear once, before the first cue; without it the title is the file name. There are no multi-line commands: put them in a script and call the script. A bad file is reported as cuelight: FILE:LINE: message before the terminal is touched, with exit code 2.

Keys

KeyWaitingIn Standby
SpaceStandbynothing
Enterrefused, and countedGo
Backspacenothingstand down
qends the showends the show
Ctrl-Cinterrupts the showinterrupts the show

Standby belongs to one cue; the next cue needs its own. A command runs with /bin/sh -c in the current directory, with the terminal handed to it as it was, its output untouched. Anything typed while it runs is thrown away, so a stray Space and Enter cannot call the next cue. A cue that fails stops the show. While waiting, the screen stays still.

Rehearsal

--rehearse uses the same keys and the same screen, but Go prints the command instead of running it, together with a check made without executing anything: sh -n for syntax, and for a first word that contains a slash, whether the file exists and is executable. Bare command names are not guessed at, so the best a cue can earn is syntax ok, or syntax ok, path ok with a path. The rehearsal exits 1 if any check failed, so it can gate a script.

The report

Written on every ending (complete, failed cue, q, Ctrl-C) as show-report-STEM-YYYYMMDD-HHMMSS.txt, or rehearsal-report-... for a rehearsal, never overwriting an earlier one, then printed. It records curtain times, running time, and for each cue the command, Standby and Go times, how long it was held, how long it ran, its exit code, how many Go presses were refused and the result. It never contains colour codes.

Exit codes

0 complete. 1 a live cue failed, or a rehearsal had a failed check. 2 bad usage, bad cue file, or stdin is not a terminal (no report). 3 ended with q. 130 Ctrl-C.

Files

cuelight.py the tool. test_cuelight.py the tests. ship.cues the runbook for this folder. qa/e2e.py the tmux run behind out/ and shots/. out/ the captures and the report from that run. BUILD.md how each acceptance check was verified.

Colophon

Catalogue number 43 of 100. Written in Python with the standard library and nothing else. Set in whatever monospace the terminal already uses; one colour, brick #EC5E52, on three words. Called from the prompt side. Latecomers will not be admitted while a cue is running.

NORMAL IS DEAD

Files