showrun-cli 0.1.0__py3-none-any.whl

showrun/__init__.py

@@ -0,0 +1,6 @@
+"""showrun: scripted, keypress-driven terminal demos."""
+
+from .model import Demo, Settings, Step, load_demo
+
+__all__ = ["Demo", "Settings", "Step", "load_demo"]
+__version__ = "0.1.0"

showrun/cast.py

@@ -0,0 +1,86 @@
+"""asciinema v2 .cast recording and playback, with no asciinema install required."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import sys
+import time
+from pathlib import Path
+from typing import Optional, TextIO, Tuple
+
+_LONE_LF = re.compile(r"(?<!\r)\n")
+
+
+class CastTee:
+    """File-like wrapper: writes to the real stream and records an asciinema v2 cast."""
+
+    def __init__(self, stream: TextIO, path: str, title: Optional[str] = None,
+                 size: Optional[Tuple[int, int]] = None, crlf: bool = False):
+        self.stream = stream
+        self.crlf = crlf  # no tty to turn "\n" into "\r\n", so do it here (headless renders)
+        cols, rows = size or shutil.get_terminal_size((100, 30))
+        self.out = open(path, "w", encoding="utf-8")
+        header = {"version": 2, "width": cols, "height": rows,
+                  "timestamp": int(time.time()), "env": {"TERM": "xterm-256color"}}
+        if title:
+            header["title"] = title
+        self.out.write(json.dumps(header) + "\n")
+        self.start = time.monotonic()
+
+    def write(self, data: str) -> int:
+        if data:
+            rec = _LONE_LF.sub("\r\n", data) if self.crlf else data
+            self.out.write(json.dumps([round(time.monotonic() - self.start, 6), "o", rec]) + "\n")
+        return self.stream.write(data)
+
+    def marker(self, label: str) -> None:
+        self.out.write(json.dumps([round(time.monotonic() - self.start, 6), "m", label]) + "\n")
+
+    def flush(self) -> None:
+        self.stream.flush()
+        self.out.flush()
+
+    def close(self) -> None:
+        self.out.close()
+
+    # Rich inspects these.
+    def isatty(self) -> bool:
+        return self.stream.isatty()
+
+    def fileno(self) -> int:
+        return self.stream.fileno()
+
+    @property
+    def encoding(self) -> str:
+        return getattr(self.stream, "encoding", "utf-8")
+
+
+def replay(path: str, speed: float = 1.0, max_idle: Optional[float] = 1.0,
+           stream: TextIO = sys.stdout, sleep=time.sleep) -> float:
+    """Play a .cast file to *stream*. Returns total (scaled) playback time."""
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    if not lines:
+        raise ValueError("empty cast file")
+    header = json.loads(lines[0])
+    if header.get("version") != 2:
+        raise ValueError("only asciinema v2 casts are supported")
+    last = 0.0
+    total = 0.0
+    for line in lines[1:]:
+        if not line.strip():
+            continue
+        t, kind, data = json.loads(line)
+        delay = t - last
+        last = t
+        if max_idle is not None:
+            delay = min(delay, max_idle)
+        delay /= speed
+        if delay > 0:
+            sleep(delay)
+            total += delay
+        if kind == "o":
+            stream.write(data)
+            stream.flush()
+    return total

showrun/check.py

@@ -0,0 +1,95 @@
+"""Rehearsal: run every step unattended and report what would break on stage."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+from rich.console import Console
+from rich.table import Table
+
+from .model import Demo
+from .player import _strip_ansi
+from .shell import Shell
+
+
+@dataclass
+class CheckResult:
+    n: int
+    label: str
+    status: str  # ok | fail | skip
+    detail: str = ""
+    duration: float = 0.0
+
+
+def rehearse(demo: Demo, shell: Optional[Shell] = None, stop_on_fail: bool = False) -> List[CheckResult]:
+    s = demo.settings
+    sh = shell or Shell(s.shell, cwd=s.cwd, env=s.env)
+    results: List[CheckResult] = []
+    try:
+        for cmd in demo.setup:
+            r = sh.run(cmd, timeout=s.timeout)
+            if r.exit_code != 0:
+                results.append(CheckResult(0, f"setup: {cmd}", "fail", f"exit {r.exit_code}"))
+        for n, step in enumerate(demo.steps, 1):
+            label = step.label()
+            if step.run and not step.execute:
+                results.append(CheckResult(n, label, "skip", "canned output"))
+                continue
+            if not step.run and not step.wait_for:
+                continue
+            problems = []
+            dur = 0.0
+            if step.run and step.background:
+                pid, log = sh.start_background(step.run)
+            elif step.run:
+                r = sh.run(step.run, timeout=step.timeout or s.timeout)
+                dur = r.duration
+                if r.timed_out:
+                    problems.append(f"timed out after {step.timeout or s.timeout}s")
+                elif not step.exit_ok(r.exit_code):
+                    problems.append(f"exit {r.exit_code} (expected {step.expect_exit})")
+                if step.expect_output and not re.search(step.expect_output, _strip_ansi(r.output), re.M):
+                    problems.append(f"output missing /{step.expect_output}/")
+                if problems:
+                    tail = _strip_ansi(r.output).strip().splitlines()[-3:]
+                    if tail:
+                        problems.append("… " + " | ".join(tail))
+            if step.wait_for and not sh.wait_for(step.wait_for, step.wait_timeout):
+                problems.append(f"wait_for failed: {step.wait_for}")
+            results.append(CheckResult(n, label, "fail" if problems else "ok", "; ".join(problems), dur))
+            if problems and stop_on_fail:
+                break
+    finally:
+        for cmd in demo.cleanup:
+            try:
+                sh.run(cmd, timeout=30)
+            except Exception:
+                pass
+        if shell is None:
+            sh.close()
+    return results
+
+
+def report(results: List[CheckResult], console: Console) -> bool:
+    t = Table(title="rehearsal", header_style="bold")
+    t.add_column("#", justify="right")
+    t.add_column("step")
+    t.add_column("result")
+    t.add_column("time", justify="right")
+    t.add_column("detail", overflow="fold")
+    icons = {"ok": "[green]✓ ok[/]", "fail": "[red]✗ fail[/]", "skip": "[dim]– skip[/]"}
+    for r in results:
+        t.add_row(str(r.n or "-"), r.label, icons[r.status],
+                  f"{r.duration:.1f}s" if r.duration else "", r.detail)
+    console.print(t)
+    fails = sum(r.status == "fail" for r in results)
+    slow = sorted((r for r in results if r.duration > 5), key=lambda r: -r.duration)[:3]
+    if slow:
+        console.print("[yellow]slow steps (consider execute: false + output):[/] "
+                      + ", ".join(f"#{r.n} {r.duration:.0f}s" for r in slow))
+    total = sum(r.duration for r in results)
+    console.print(("[bold green]all good[/]" if not fails else f"[bold red]{fails} failing step(s)[/]")
+                  + f"  [dim](command time {total:.1f}s)[/]")
+    return fails == 0

showrun/cli.py

@@ -0,0 +1,236 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .model import DemoError, load_demo
+
+app = typer.Typer(add_completion=False, no_args_is_help=True, rich_markup_mode="rich",
+                  help="Scripted, keypress-driven terminal demos.")
+err = Console(stderr=True)
+
+
+def _vars(pairs: Optional[List[str]]) -> Dict[str, str]:
+    out = {}
+    for p in pairs or []:
+        if "=" not in p:
+            raise typer.BadParameter(f"expected KEY=VALUE, got {p!r}")
+        k, v = p.split("=", 1)
+        out[k.strip()] = v
+    return out
+
+
+def _load(path: Path, var: Optional[List[str]]):
+    try:
+        return load_demo(path, _vars(var))
+    except DemoError as e:
+        err.print(f"[red]{e}[/]")
+        raise typer.Exit(2)
+
+
+VarOpt = typer.Option(None, "--var", "-v", help="Override a variable: KEY=VALUE (repeatable).")
+
+
+@app.command()
+def play(
+    demo_file: Path = typer.Argument(..., help="Demo YAML file."),
+    var: Optional[List[str]] = VarOpt,
+    offline: bool = typer.Option(False, "--offline", help="Replay recorded output instead of running commands."),
+    fallback: bool = typer.Option(False, "--fallback", help="Run live, but if a step fails show its recorded output."),
+    auto: Optional[float] = typer.Option(None, "--auto", help="Advance by itself every N seconds."),
+    start: int = typer.Option(1, "--start", "-s", help="Start at step N (hidden steps before it are skipped)."),
+    cast: Optional[Path] = typer.Option(None, "--cast", help="Also record the session to an asciinema .cast file."),
+    speed: float = typer.Option(1.0, "--speed", help="Typing speed multiplier (2 = twice as fast)."),
+    notes: bool = typer.Option(True, "--notes/--no-notes", help="Publish position for `showrun notes`."),
+):
+    """Present a demo. Enter advances; press ? during the demo for all keys."""
+    from .cast import CastTee
+    from .keys import AutoKeys, TerminalKeys
+    from .notes import default_notes_path
+    from .player import Player
+
+    demo = _load(demo_file, var)
+    if speed > 0:
+        demo.settings.typing_speed /= speed
+    if not sys.stdin.isatty():
+        err.print("[red]play needs an interactive terminal (try `showrun check` for unattended runs)[/]")
+        raise typer.Exit(2)
+
+    tee = CastTee(sys.stdout, str(cast), demo.title) if cast else None
+    console = Console(file=tee, highlight=False, force_terminal=True) if tee else Console(highlight=False)
+    keys = TerminalKeys()
+    if auto is not None:
+        keys = AutoKeys(auto, inner=keys)
+    on_step = (lambda i, st: tee.marker(st.label())) if tee else None
+    player = Player(demo, console=console, keys=keys, offline=offline, fallback=fallback, start_at=start,
+                    notes_path=default_notes_path(str(demo_file)) if notes else None, on_step=on_step)
+    try:
+        failures = player.play()
+    finally:
+        if tee:
+            tee.close()
+            err.print(f"[dim]recorded {cast} — play it back with: showrun replay {cast}[/]")
+    raise typer.Exit(1 if failures else 0)
+
+
+@app.command()
+def check(
+    demo_file: Path = typer.Argument(..., help="Demo YAML file."),
+    var: Optional[List[str]] = VarOpt,
+    fail_fast: bool = typer.Option(False, "--fail-fast", "-x", help="Stop at the first failing step."),
+):
+    """Rehearse: run every step unattended and report failures (great in CI)."""
+    from .check import rehearse, report
+
+    demo = _load(demo_file, var)
+    ok = report(rehearse(demo, stop_on_fail=fail_fast), Console())
+    raise typer.Exit(0 if ok else 1)
+
+
+@app.command()
+def record(
+    demo_file: Path = typer.Argument(..., help="YAML file to write."),
+    title: Optional[str] = typer.Option(None, "--title", "-t"),
+    shell: str = typer.Option("bash", "--shell"),
+    append: bool = typer.Option(False, "--append", "-a", help="Add steps to an existing file."),
+):
+    """Do the demo once in a shell; every command (and its output) becomes a step."""
+    from .record import Recorder
+
+    if demo_file.exists() and not append:
+        if not typer.confirm(f"{demo_file} exists. Overwrite?"):
+            raise typer.Exit(1)
+    Recorder(str(demo_file), title=title, shell=shell, append=append).run()
+
+
+@app.command()
+def replay(
+    cast_file: Path = typer.Argument(..., help="asciinema v2 .cast file."),
+    speed: float = typer.Option(1.0, "--speed", help="Playback speed multiplier."),
+    max_idle: float = typer.Option(1.0, "--max-idle", help="Cap pauses at this many seconds (0 = no cap)."),
+):
+    """Play back a recorded .cast session in the terminal."""
+    from .cast import replay as do_replay
+
+    try:
+        do_replay(str(cast_file), speed=speed, max_idle=max_idle or None)
+    except (ValueError, FileNotFoundError) as e:
+        err.print(f"[red]{e}[/]")
+        raise typer.Exit(2)
+    except KeyboardInterrupt:
+        pass
+    sys.stdout.write("\x1b[0m\n")
+
+
+@app.command()
+def render(
+    demo_file: Path = typer.Argument(..., help="Demo YAML file."),
+    output: Path = typer.Option(..., "--output", "-o", help="The .cast file to write."),
+    var: Optional[List[str]] = VarOpt,
+    offline: bool = typer.Option(False, "--offline", help="Use recorded output instead of running commands."),
+    delay: float = typer.Option(1.0, "--delay", help="Seconds to wait before each Enter."),
+    width: int = typer.Option(100, "--width"),
+    height: int = typer.Option(30, "--height"),
+):
+    """Present a demo unattended and save it as an asciinema .cast (no terminal needed)."""
+    from .render import render_cast
+
+    demo = _load(demo_file, var)
+    r = render_cast(demo, str(output), offline=offline, delay=delay, width=width, height=height)
+    for w in r.warnings:
+        err.print(f"[yellow]{w}[/]")
+    err.print(f"[green]wrote {output}[/] — {r.steps} steps, {r.failures} failed. "
+              f"Play it with: showrun replay {output}")
+    raise typer.Exit(1 if r.failures else 0)
+
+
+@app.command()
+def mcp():
+    """Run an MCP server (stdio) so AI agents can write, check and render demos."""
+    try:
+        from .mcp_server import main
+    except ImportError:
+        err.print("[red]the MCP server needs the `mcp` extra:[/] pip install 'showrun-cli[mcp]' (Python 3.10+)")
+        raise typer.Exit(2)
+    main()
+
+
+@app.command()
+def notes(demo_file: Path = typer.Argument(..., help="The demo being presented.")):
+    """Presenter view: run in a second terminal to see the current step, notes and what's next."""
+    from .notes import default_notes_path, watch
+
+    try:
+        watch(default_notes_path(str(demo_file)))
+    except KeyboardInterrupt:
+        pass
+
+
+@app.command()
+def export(
+    demo_file: Path = typer.Argument(...),
+    var: Optional[List[str]] = VarOpt,
+    fmt: str = typer.Option("md", "--format", "-f", help="md (runbook) or sh (plain script)."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o"),
+    include_hidden: bool = typer.Option(False, "--include-hidden"),
+):
+    """Export as a Markdown runbook or a plain shell script."""
+    from .export import to_markdown, to_script
+
+    demo = _load(demo_file, var)
+    if fmt == "md":
+        text = to_markdown(demo, include_hidden=include_hidden)
+    elif fmt == "sh":
+        text = to_script(demo)
+    else:
+        raise typer.BadParameter("format must be md or sh")
+    if output:
+        output.write_text(text)
+        err.print(f"[green]wrote {output}[/]")
+    else:
+        sys.stdout.write(text)
+
+
+@app.command()
+def validate(demo_file: Path = typer.Argument(...), var: Optional[List[str]] = VarOpt):
+    """Check the file parses and list its steps."""
+    demo = _load(demo_file, var)
+    t = Table(title=demo.title or str(demo_file), header_style="bold")
+    for col in ("#", "kind", "step"):
+        t.add_column(col)
+    for n, st in enumerate(demo.steps, 1):
+        kind = ("hidden" if st.hidden else "bg" if st.background else "canned" if not st.execute
+                else "run" if st.run else "wait" if st.wait_for else "say" if st.say else "pause")
+        t.add_row(str(n), kind, st.label())
+    Console().print(t)
+    Console().print(f"[green]ok[/] — {len(demo.steps)} steps, {len(demo.setup)} setup, {len(demo.cleanup)} cleanup")
+
+
+@app.command()
+def init(path: Path = typer.Argument(Path("demo.yaml"))):
+    """Write a starter demo file that shows off the features."""
+    from importlib.resources import files
+
+    if path.exists():
+        err.print(f"[red]{path} already exists[/]")
+        raise typer.Exit(1)
+    path.write_text(files("showrun").joinpath("starter.yaml").read_text())
+    err.print(f"[green]wrote {path}[/] — try: showrun check {path} && showrun play {path}")
+
+
+@app.command()
+def version():
+    """Print the version."""
+    print(__version__)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

showrun/export.py

@@ -0,0 +1,50 @@
+"""Export a demo as a Markdown runbook or a plain shell script."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .model import Demo
+from .player import _strip_ansi
+
+
+def to_markdown(demo: Demo, include_hidden: bool = False, include_output: bool = True) -> str:
+    out: List[str] = [f"# {demo.title or 'Demo'}", ""]
+    if demo.setup and include_hidden:
+        out += ["## Setup", "", "```bash", *demo.setup, "```", ""]
+    for step in demo.steps:
+        if step.hidden and not include_hidden:
+            continue
+        if step.title:
+            out += [f"## {step.title}", ""]
+        if step.say:
+            out += [step.say.strip(), ""]
+        if step.run:
+            label = " (hidden)" if step.hidden else (" (background)" if step.background else "")
+            if label:
+                out.append(f"*{label.strip(' ()')}:*")
+            out += ["```bash", step.run.rstrip(), "```", ""]
+            sample = step.output if not step.execute else step.recorded_output
+            if include_output and sample:
+                out += ["```text", _strip_ansi(sample).rstrip(), "```", ""]
+        if step.wait_for:
+            out += [f"_Wait until `{step.wait_for}` succeeds._", ""]
+    if demo.cleanup and include_hidden:
+        out += ["## Cleanup", "", "```bash", *demo.cleanup, "```", ""]
+    return "\n".join(out).rstrip() + "\n"
+
+
+def to_script(demo: Demo) -> str:
+    out = ["#!/usr/bin/env bash", f"# {demo.title or 'demo'} — exported by showrun", "set -e", ""]
+    for cmd in demo.setup:
+        out.append(cmd)
+    for step in demo.steps:
+        if step.say:
+            out += ["", "# " + step.say.strip().replace("\n", "\n# ")]
+        if step.run and step.execute:
+            out.append(step.run.rstrip() + (" &" if step.background else ""))
+        if step.wait_for:
+            out.append(f"until {step.wait_for} >/dev/null 2>&1; do sleep 0.5; done")
+    if demo.cleanup:
+        out += ["", "# cleanup", *demo.cleanup]
+    return "\n".join(out) + "\n"

showrun/keys.py

@@ -0,0 +1,149 @@
+"""Keypress sources: the real terminal, a scripted list (tests), or auto-advance."""
+
+from __future__ import annotations
+
+import os
+import select
+import sys
+import time
+from typing import Iterable, Optional
+
+ENTER = "enter"
+ESC = "esc"
+BACKSPACE = "backspace"
+
+
+def _normalise(ch: str) -> str:
+    if ch in ("\r", "\n"):
+        return ENTER
+    if ch == "\x1b":
+        return ESC
+    if ch in ("\x7f", "\x08"):
+        return BACKSPACE
+    if ch == "\x03":
+        raise KeyboardInterrupt
+    return ch
+
+
+class KeySource:
+    def read(self, timeout: Optional[float] = None) -> Optional[str]:  # pragma: no cover
+        raise NotImplementedError
+
+    def poll(self) -> Optional[str]:
+        return self.read(timeout=0)
+
+    def suspend(self):  # context used while handing the tty to a child
+        return _Null()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        pass
+
+
+class _Null:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        pass
+
+
+class TerminalKeys(KeySource):
+    """Reads single keys from the controlling terminal in cbreak mode."""
+
+    def __init__(self, stream=None):
+        self.stream = stream or sys.stdin
+        self.fd = self.stream.fileno()
+        self._saved = None
+
+    def __enter__(self):
+        import termios
+        import tty
+
+        if os.isatty(self.fd):
+            self._saved = termios.tcgetattr(self.fd)
+            tty.setcbreak(self.fd)
+        return self
+
+    def __exit__(self, *exc):
+        import termios
+
+        if self._saved is not None:
+            termios.tcsetattr(self.fd, termios.TCSADRAIN, self._saved)
+            self._saved = None
+
+    def suspend(self):
+        outer = self
+
+        class _Suspend:
+            def __enter__(self_inner):
+                outer.__exit__()
+
+            def __exit__(self_inner, *exc):
+                outer.__enter__()
+
+        return _Suspend()
+
+    def read(self, timeout: Optional[float] = None) -> Optional[str]:
+        r, _, _ = select.select([self.fd], [], [], timeout)
+        if not r:
+            return None
+        ch = os.read(self.fd, 1).decode(errors="ignore")
+        if ch == "\x1b":
+            # Swallow the rest of an escape sequence (arrow keys etc.).
+            seq = ""
+            while select.select([self.fd], [], [], 0.01)[0]:
+                seq += os.read(self.fd, 1).decode(errors="ignore")
+            return {"[C": "right", "[D": "left", "[A": "up", "[B": "down"}.get(seq, ESC)
+        return _normalise(ch)
+
+
+class ScriptedKeys(KeySource):
+    """Feeds a fixed sequence of keys; returns ENTER forever (or 'q') when exhausted."""
+
+    def __init__(self, keys: Iterable[str], then: str = ENTER):
+        self.keys = list(keys)
+        self.then = then
+
+    def read(self, timeout: Optional[float] = None) -> Optional[str]:
+        if self.keys:
+            return self.keys.pop(0)
+        return self.then
+
+    def poll(self) -> Optional[str]:
+        return None  # never interrupts typing
+
+
+class AutoKeys(KeySource):
+    """Presses Enter by itself after *delay* seconds, but real keys still work."""
+
+    def __init__(self, delay: float, inner: Optional[KeySource] = None):
+        self.delay = delay
+        self.inner = inner
+
+    def __enter__(self):
+        if self.inner:
+            self.inner.__enter__()
+        return self
+
+    def __exit__(self, *exc):
+        if self.inner:
+            self.inner.__exit__(*exc)
+
+    def suspend(self):
+        return self.inner.suspend() if self.inner else _Null()
+
+    def read(self, timeout: Optional[float] = None) -> Optional[str]:
+        if timeout == 0:
+            return self.inner.read(0) if self.inner else None
+        end = time.monotonic() + self.delay
+        while time.monotonic() < end:
+            if self.inner:
+                k = self.inner.read(timeout=min(0.05, max(0, end - time.monotonic())))
+                if k:
+                    return k
+            else:
+                time.sleep(min(0.05, end - time.monotonic()))
+        return ENTER