showrun-cli 0.1.0__py3-none-any.whl

showrun/mcp_server.py

@@ -0,0 +1,205 @@
+"""MCP server: lets AI agents write, validate, rehearse, export and render showrun demos.
+
+Run it with `showrun mcp` (stdio). Needs the `mcp` extra: pip install 'showrun-cli[mcp]'.
+Note that check_demo and render_demo run the demo's shell commands on this machine, just as
+`showrun check` does, so an MCP client should ask before calling them.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:  # mcp >= 2
+    from mcp.server.mcpserver import MCPServer as _Server
+except ImportError:  # mcp 1.x
+    from mcp.server.fastmcp import FastMCP as _Server
+
+from . import __version__
+from .model import Demo, DemoError, load_demo, parse_demo
+
+INSTRUCTIONS = """\
+showrun turns a YAML file of shell steps into a keypress-driven terminal presentation.
+Typical agent workflow:
+  1. read the format with `demo_format` (or start from `starter_demo`),
+  2. write the YAML with `write_demo` (it is validated before it is saved),
+  3. rehearse it with `check_demo` (runs every command and reports failures),
+  4. optionally `render_demo` to produce an asciinema .cast, and `read_cast` to see it as text.
+The human then presents it with `showrun play <file>` (Enter advances).
+Most tools accept either `path` (a YAML file) or `yaml_text` (inline YAML)."""
+
+server = _Server("showrun", instructions=INSTRUCTIONS)
+
+_ANSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07]*\x07|\r")
+
+
+def _demo(path: Optional[str], yaml_text: Optional[str], variables: Optional[Dict[str, str]]) -> Demo:
+    if bool(path) == bool(yaml_text):
+        raise ValueError("pass exactly one of `path` or `yaml_text`")
+    if path:
+        return load_demo(os.path.expanduser(path), variables)
+    return parse_demo(yaml_text or "", variables, base_dir=Path.cwd())
+
+
+def _kind(st) -> str:
+    return ("hidden" if st.hidden else "background" 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")
+
+
+def _steps(demo: Demo) -> List[Dict[str, Any]]:
+    return [{"n": n, "kind": _kind(st), "label": st.label()} for n, st in enumerate(demo.steps, 1)]
+
+
+@server.tool()
+def demo_format() -> str:
+    """Reference for the demo YAML format: settings, vars, setup/cleanup and every step option."""
+    from .model import Settings, Step
+
+    def fields(model) -> Dict[str, str]:
+        return {name: str(f.annotation).replace("typing.", "") + (f" — {f.description}" if f.description else "")
+                for name, f in model.model_fields.items()}
+
+    return json.dumps({
+        "top_level": {"title": "str", "settings": "mapping (see settings)", "vars": "mapping; use as {{name}}",
+                      "setup": "list of commands run silently before step 1",
+                      "cleanup": "list of commands that always run at the end", "steps": "list of steps"},
+        "settings": fields(Settings),
+        "step": fields(Step),
+        "notes": ["A step can be a plain string, which means `run: <string>`.",
+                  "execute: false + output: shows canned output without running the command.",
+                  "background: true + wait_for: <cmd> starts a service and waits until <cmd> exits 0.",
+                  "expect_output is a regex checked by check_demo; expect_exit may be an int or 'any'."],
+        "example": files("showrun").joinpath("starter.yaml").read_text(),
+    }, indent=2)
+
+
+@server.tool()
+def starter_demo() -> str:
+    """A complete starter demo (YAML) that uses most features; a good template to edit."""
+    return files("showrun").joinpath("starter.yaml").read_text()
+
+
+@server.tool()
+def validate_demo(path: Optional[str] = None, yaml_text: Optional[str] = None,
+                  variables: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    """Parse a demo (from `path` or `yaml_text`) and list its steps. Runs nothing."""
+    try:
+        d = _demo(path, yaml_text, variables)
+    except DemoError as e:
+        return {"ok": False, "error": str(e)}
+    return {"ok": True, "title": d.title, "steps": _steps(d), "setup": len(d.setup), "cleanup": len(d.cleanup)}
+
+
+@server.tool()
+def write_demo(path: str, yaml_text: str, overwrite: bool = False) -> Dict[str, Any]:
+    """Validate `yaml_text` and save it to `path`. Refuses to replace an existing file unless overwrite=true."""
+    p = Path(os.path.expanduser(path))
+    if p.exists() and not overwrite:
+        return {"ok": False, "error": f"{p} exists; pass overwrite=true to replace it"}
+    try:
+        d = parse_demo(yaml_text, base_dir=p.parent)
+    except DemoError as e:
+        return {"ok": False, "error": str(e)}
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(yaml_text)
+    return {"ok": True, "path": str(p.resolve()), "steps": _steps(d),
+            "next": f"check it with check_demo, then present with: showrun play {p}"}
+
+
+@server.tool()
+def check_demo(path: Optional[str] = None, yaml_text: Optional[str] = None,
+               variables: Optional[Dict[str, str]] = None, fail_fast: bool = False) -> Dict[str, Any]:
+    """Rehearse a demo: RUNS every command in a real shell and reports failures, timeouts and
+    missing expected output (same as `showrun check`). Canned steps are skipped."""
+    from .check import rehearse
+
+    try:
+        d = _demo(path, yaml_text, variables)
+    except DemoError as e:
+        return {"ok": False, "error": str(e)}
+    results = rehearse(d, stop_on_fail=fail_fast)
+    rows = [{"n": r.n, "step": r.label, "status": r.status, "seconds": round(r.duration, 2),
+             **({"detail": r.detail} if r.detail else {})} for r in results]
+    fails = sum(r.status == "fail" for r in results)
+    return {"ok": fails == 0, "failing": fails, "results": rows}
+
+
+@server.tool()
+def export_demo(path: Optional[str] = None, yaml_text: Optional[str] = None, format: str = "md",
+                include_hidden: bool = False, variables: Optional[Dict[str, str]] = None) -> str:
+    """Export a demo as a Markdown runbook (format='md') or a plain bash script (format='sh')."""
+    from .export import to_markdown, to_script
+
+    d = _demo(path, yaml_text, variables)
+    if format == "md":
+        return to_markdown(d, include_hidden=include_hidden)
+    if format == "sh":
+        return to_script(d)
+    raise ValueError("format must be 'md' or 'sh'")
+
+
+@server.tool()
+def render_demo(output: str, path: Optional[str] = None, yaml_text: Optional[str] = None,
+                offline: bool = False, delay: float = 1.0, width: int = 100, height: int = 30,
+                variables: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    """Present the demo unattended and save it as an asciinema v2 .cast at `output`. RUNS the
+    commands unless offline=true (then recorded/canned output is shown instead)."""
+    from .render import render_cast
+
+    d = _demo(path, yaml_text, variables)
+    out = Path(os.path.expanduser(output))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    r = render_cast(d, str(out), offline=offline, delay=delay, width=width, height=height)
+    return {"ok": r.failures == 0, "path": str(out.resolve()), "steps": r.steps, "failures": r.failures,
+            "warnings": r.warnings, "replay": f"showrun replay {out}"}
+
+
+@server.tool()
+def read_cast(path: str, max_chars: int = 20000) -> str:
+    """Read a .cast recording as plain text, with a `── step: … ──` line at each step marker."""
+    lines = Path(os.path.expanduser(path)).read_text(encoding="utf-8").splitlines()
+    out: List[str] = []
+    for line in lines[1:]:
+        if not line.strip():
+            continue
+        _, kind, data = json.loads(line)
+        if kind == "m":
+            out.append(f"\n── step: {data} ──\n")
+        elif kind == "o":
+            out.append(_ANSI.sub("", data))
+    text = "".join(out)
+    return text if len(text) <= max_chars else text[:max_chars] + f"\n… ({len(text) - max_chars} more chars)"
+
+
+def guide_text() -> str:
+    """The project README (shipped as the package's long description)."""
+    from importlib.metadata import PackageNotFoundError, metadata
+
+    try:
+        return metadata("showrun-cli").get_payload() or metadata("showrun-cli")["Description"] or ""
+    except PackageNotFoundError:
+        return "showrun guide: https://github.com/honnuanand/showrun#readme"
+
+
+@server.resource("showrun://guide", name="showrun guide", mime_type="text/markdown",
+                 description="The one-page showrun guide: commands, keys, demo format, MCP tools.")
+def guide() -> str:
+    return guide_text()
+
+
+@server.tool()
+def showrun_version() -> str:
+    """The installed showrun version."""
+    return __version__
+
+
+def main() -> None:
+    server.run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

showrun/model.py

@@ -0,0 +1,203 @@
+"""Demo script format: YAML -> validated pydantic models."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+VAR_PATTERN = re.compile(r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}")
+
+
+class DemoError(Exception):
+    """Raised for invalid demo files."""
+
+
+class Settings(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prompt: str = "[bold green]demo[/] [bold blue]{cwd}[/] [bold]$[/] "
+    typing_speed: float = Field(0.04, ge=0, description="Seconds per character.")
+    jitter: float = Field(0.5, ge=0, le=1, description="Random +/- fraction of typing_speed.")
+    wait_before_typing: bool = False
+    shell: str = "bash"
+    cwd: Optional[str] = None
+    env: Dict[str, str] = Field(default_factory=dict)
+    syntax_highlight: bool = True
+    theme: str = "monokai"
+    typo_rate: float = Field(0.0, ge=0, le=0.3, description="Chance per letter of a fake typo.")
+    timeout: Optional[float] = Field(None, gt=0, description="Default per-step timeout (s).")
+    highlight_style: str = "bold black on yellow"
+
+
+class Step(BaseModel):
+    """One demo step.
+
+    Kinds of step:
+      - run a command shown to the audience (default)
+      - run a command silently (hidden: true)
+      - show a command and canned output without running it (execute: false + output)
+      - narration only (say without run)
+      - pause until a keypress (pause: true)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    run: Optional[str] = None
+    say: Optional[str] = None
+    hidden: bool = False
+    type: bool = True
+    wait: bool = True
+    execute: bool = True
+    output: Optional[str] = None
+    expect_exit: Union[int, str] = 0  # int, or "any"
+    timeout: Optional[float] = Field(None, gt=0)
+    speed: Optional[float] = Field(None, ge=0)
+    clear: bool = False
+    pause: bool = False
+    title: Optional[str] = None
+    notes: Optional[str] = None            # presenter-only notes
+    typos: Optional[bool] = None           # override settings.typo_rate on/off
+    highlight: List[str] = Field(default_factory=list)  # regexes to highlight in output
+    expect_output: Optional[str] = None    # regex checked in rehearsal (and flagged live)
+    background: bool = False               # start command in background (servers etc.)
+    wait_for: Optional[str] = None         # poll until this command exits 0
+    wait_timeout: float = Field(30, gt=0)
+    recorded_output: Optional[str] = None  # captured by `showrun record`; used by --offline
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce(cls, data: Any) -> Any:
+        if isinstance(data, dict) and isinstance(data.get("highlight"), str):
+            data = dict(data)
+            data["highlight"] = [data["highlight"]]
+        return data
+
+    @model_validator(mode="after")
+    def _check(self) -> "Step":
+        if not (self.run or self.say or self.pause or self.clear or self.title or self.wait_for):
+            raise ValueError("step needs at least one of: run, say, pause, clear, title, wait_for")
+        if self.background and not self.run:
+            raise ValueError("background steps need a 'run' command")
+        if self.background and self.output is not None:
+            raise ValueError("background steps can't have canned output")
+        for pat in self.highlight + ([self.expect_output] if self.expect_output else []):
+            try:
+                re.compile(pat)
+            except re.error as e:
+                raise ValueError(f"bad regex {pat!r}: {e}")
+        if isinstance(self.expect_exit, str) and self.expect_exit != "any":
+            raise ValueError("expect_exit must be an integer or 'any'")
+        if self.output is not None and self.execute:
+            raise ValueError("'output' (canned output) requires execute: false")
+        if self.hidden and not self.run:
+            raise ValueError("hidden steps need a 'run' command")
+        return self
+
+    @property
+    def visible(self) -> bool:
+        return not self.hidden
+
+    def exit_ok(self, code: int) -> bool:
+        return self.expect_exit == "any" or code == self.expect_exit
+
+    def label(self) -> str:
+        if self.title:
+            return self.title
+        if self.run:
+            first = self.run.strip().splitlines()[0]
+            return first if len(first) <= 60 else first[:57] + "..."
+        if self.say:
+            return "say: " + self.say.strip().splitlines()[0][:50]
+        return "pause"
+
+
+class Demo(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    title: Optional[str] = None
+    settings: Settings = Field(default_factory=Settings)
+    vars: Dict[str, Any] = Field(default_factory=dict)
+    setup: List[str] = Field(default_factory=list)
+    cleanup: List[str] = Field(default_factory=list)
+    steps: List[Step]
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalise_steps(cls, data: Any) -> Any:
+        # Allow plain strings as shorthand for {run: "..."}.
+        if isinstance(data, dict) and isinstance(data.get("steps"), list):
+            data = dict(data)
+            data["steps"] = [{"run": s} if isinstance(s, str) else s for s in data["steps"]]
+        return data
+
+
+def substitute(text: str, variables: Dict[str, Any]) -> str:
+    def repl(m: re.Match) -> str:
+        name = m.group(1)
+        # Unknown names are left alone so Go/Jinja templates in commands
+        # (e.g. docker --format '{{ json . }}') pass through untouched.
+        return str(variables[name]) if name in variables else m.group(0)
+
+    return VAR_PATTERN.sub(repl, text)
+
+
+def _sub_all(obj: Any, variables: Dict[str, Any]) -> Any:
+    if isinstance(obj, str):
+        return substitute(obj, variables)
+    if isinstance(obj, list):
+        return [_sub_all(x, variables) for x in obj]
+    if isinstance(obj, dict):
+        return {k: _sub_all(v, variables) for k, v in obj.items()}
+    return obj
+
+
+def parse_demo(text: str, overrides: Optional[Dict[str, str]] = None, base_dir: Optional[Path] = None) -> Demo:
+    try:
+        raw = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise DemoError(f"YAML error: {e}") from e
+    if not isinstance(raw, dict):
+        raise DemoError("demo file must be a mapping with a 'steps' list")
+
+    # Resolve variables: file defaults < SHOWRUN_VAR_<NAME> env < CLI overrides.
+    variables: Dict[str, Any] = dict(raw.get("vars") or {})
+    for key in list(variables):
+        env_val = os.environ.get(f"SHOWRUN_VAR_{key.upper()}")
+        if env_val is not None:
+            variables[key] = env_val
+    variables.update(overrides or {})
+    raw["vars"] = variables
+
+    for section in ("steps", "setup", "cleanup", "settings", "title"):
+        if section in raw:
+            raw[section] = _sub_all(raw[section], variables)
+
+    try:
+        demo = Demo.model_validate(raw)
+    except ValidationError as e:
+        raise DemoError(_format_validation(e)) from e
+
+    if base_dir is not None:
+        cwd = demo.settings.cwd
+        demo.settings.cwd = str((base_dir / os.path.expanduser(cwd)).resolve()) if cwd else str(base_dir.resolve())
+    return demo
+
+
+def load_demo(path: Union[str, Path], overrides: Optional[Dict[str, str]] = None) -> Demo:
+    p = Path(path)
+    if not p.exists():
+        raise DemoError(f"file not found: {p}")
+    return parse_demo(p.read_text(), overrides, base_dir=p.parent)
+
+
+def _format_validation(e: ValidationError) -> str:
+    lines = ["invalid demo file:"]
+    for err in e.errors():
+        loc = ".".join(str(x) for x in err["loc"])
+        lines.append(f"  {loc or '<root>'}: {err['msg']}")
+    return "\n".join(lines)

showrun/notes.py

@@ -0,0 +1,96 @@
+"""Presenter notes: the player publishes its position to a small JSON file and
+`showrun notes` renders it live in a second terminal (or on a second screen)."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console, Group
+from rich.live import Live
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+from .model import Demo
+
+
+def default_notes_path(demo_path: str) -> str:
+    stem = Path(demo_path).resolve().as_posix().replace("/", "_").strip("_")
+    return os.path.join(tempfile.gettempdir(), f"showrun-notes-{stem}.json")
+
+
+class NotesPublisher:
+    def __init__(self, path: Optional[str], demo: Demo):
+        self.path = path
+        self.demo = demo
+        self.started = time.time()
+
+    def publish(self, index: int, state: str = "ready") -> None:
+        if not self.path:
+            return
+        steps = self.demo.steps
+
+        def info(i: int) -> Optional[dict]:
+            if 0 <= i < len(steps):
+                s = steps[i]
+                return {"n": i + 1, "label": s.label(), "run": s.run, "say": s.say,
+                        "notes": s.notes, "hidden": s.hidden}
+            return None
+
+        nxt = next((j for j in range(index + 1, len(steps)) if not steps[j].hidden), -1)
+        payload = {"title": self.demo.title, "total": len(steps), "state": state,
+                   "started": self.started, "current": info(index), "next": info(nxt)}
+        tmp = self.path + ".tmp"
+        with open(tmp, "w") as f:
+            json.dump(payload, f)
+        os.replace(tmp, self.path)
+
+    def finish(self) -> None:
+        self.publish(len(self.demo.steps), state="finished")
+
+
+def _render(data: dict) -> Panel:
+    elapsed = int(time.time() - data.get("started", time.time()))
+    cur = data.get("current")
+    parts = []
+    header = Text()
+    header.append(data.get("title") or "showrun", style="bold")
+    header.append(f"   ⏱ {elapsed // 60:02d}:{elapsed % 60:02d}", style="cyan")
+    if data.get("state") == "finished":
+        header.append("   ✓ finished", style="bold green")
+    parts.append(header)
+    if cur:
+        parts.append(Text(f"\nNOW  step {cur['n']}/{data['total']}: {cur['label']}", style="bold yellow"))
+        if cur.get("run"):
+            parts.append(Syntax(cur["run"], "bash", theme="monokai", background_color="default"))
+        if cur.get("say"):
+            parts.append(Text("Say: " + cur["say"], style="italic"))
+        if cur.get("notes"):
+            parts.append(Panel(cur["notes"], title="notes", border_style="magenta"))
+    nxt = data.get("next")
+    if nxt:
+        parts.append(Text(f"\nNEXT step {nxt['n']}: {nxt['label']}", style="dim"))
+        if nxt.get("notes"):
+            parts.append(Text("  " + nxt["notes"].splitlines()[0], style="dim magenta"))
+    return Panel(Group(*parts), title="presenter notes", border_style="blue")
+
+
+def watch(path: str, console: Optional[Console] = None) -> None:
+    console = console or Console()
+    console.print(f"[dim]watching {path} — start `showrun play` in another terminal. Ctrl-C to quit.[/]")
+    last = None
+    with Live(Panel("waiting for the demo to start…"), console=console, refresh_per_second=4) as live:
+        while True:
+            try:
+                data = json.loads(Path(path).read_text())
+                last = data
+            except (FileNotFoundError, json.JSONDecodeError):
+                data = last
+            if data:
+                live.update(_render(data))
+            time.sleep(0.25)