#!/usr/bin/env python3 """Record interactive Pi extension demos.""" from __future__ import annotations import argparse import importlib.util import os import re import shutil import subprocess import sys import time from dataclasses import dataclass from pathlib import Path from types import ModuleType try: import pexpect except ImportError as e: raise SystemExit("missing Python package: pexpect") from e ROOT = Path(__file__).resolve().parents[1] DRIVERS = ROOT / "drivers" EXTENSIONS = ROOT / "extensions" OUT = ROOT / ".demo" CAST_IDLE_LIMIT = "4.0" AGG_ARGS = [ "--theme", "asciinema", "--text-font-family", "JetBrains Mono", "--font-size", "14", "--line-height", "1.25", "--idle-time-limit", "4.0", "--last-frame-duration", "5", "--fps-cap", "24", ] @dataclass(frozen=True) class Driver: name: str title: str extensions: list[str] targets: list[str] cols: int rows: int cwd: Path steps: list[tuple] readme_id: str readme_items: list[tuple[str, str]] | None browser_script: str | None env: dict[str, str] def load_module(name: str) -> ModuleType: path = DRIVERS / f"{name}.py" if not path.exists(): raise SystemExit(f"driver not found: {path}") spec = importlib.util.spec_from_file_location(f"driver_{name}", path) if spec is None or spec.loader is None: raise SystemExit(f"cannot load driver: {path}") module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) return module def str_list(module: ModuleType, attr: str) -> list[str]: value = getattr(module, attr, None) if not isinstance(value, list) or not all(isinstance(x, str) and x for x in value): raise SystemExit(f"driver {module.__name__}: {attr} must be non-empty string list") return value def load_driver(name: str) -> Driver: module = load_module(name) title = getattr(module, "title", name.replace("_", " ").title()) if not isinstance(title, str) or not title: raise SystemExit("title must be string") cols = getattr(module, "cols", 100) rows = getattr(module, "rows", 28) if not isinstance(cols, int) or not isinstance(rows, int) or cols < 40 or rows < 12: raise SystemExit("cols/rows must be reasonable ints") cwd_raw = getattr(module, "cwd", ".") if not isinstance(cwd_raw, str): raise SystemExit("cwd must be string") cwd = (ROOT / cwd_raw).resolve() if not cwd.is_dir(): raise SystemExit(f"cwd missing: {cwd}") steps = getattr(module, "steps", None) if not isinstance(steps, list): raise SystemExit("steps must be list") for step in steps: validate_step(step) readme_id = getattr(module, "readme_id", name) if not isinstance(readme_id, str) or not readme_id: raise SystemExit("readme_id must be string") readme_items = getattr(module, "readme_items", None) if readme_items is not None: if not isinstance(readme_items, list) or not readme_items: raise SystemExit("readme_items must be non-empty list") for item in readme_items: if not ( isinstance(item, tuple) and len(item) == 2 and all(isinstance(x, str) and x for x in item) ): raise SystemExit(f"readme_items entries must be (caption, gif): {item!r}") browser_script = getattr(module, "browser_script", None) if browser_script is not None and not isinstance(browser_script, str): raise SystemExit("browser_script must be string") env = getattr(module, "env", {}) if not isinstance(env, dict) or not all( isinstance(k, str) and isinstance(v, str) for k, v in env.items() ): raise SystemExit("env must be dict[str, str]") driver = Driver( name=name, title=title, extensions=str_list(module, "extensions"), targets=str_list(module, "targets"), cols=cols, rows=rows, cwd=cwd, steps=steps, readme_id=readme_id, readme_items=readme_items, browser_script=browser_script, env=env, ) validate_driver(driver) return driver def validate_step(step: object) -> None: if not isinstance(step, tuple) or not step: raise SystemExit(f"invalid step: {step!r}") op = step[0] if op not in {"wait", "type", "send", "command", "prompt", "expect", "ready", "ctrl", "quit"}: raise SystemExit(f"unknown step op: {op!r}") if op == "wait" and not (len(step) == 2 and isinstance(step[1], int)): raise SystemExit(f"wait step must be ('wait', ms): {step!r}") if op in {"type", "send"} and not ( len(step) in {2, 3} and isinstance(step[1], str) and (len(step) == 2 or isinstance(step[2], int)) ): raise SystemExit(f"{op} step must be ('{op}', text[, delay_ms]): {step!r}") if op in {"command", "prompt"} and not ( len(step) in {2, 3} and isinstance(step[1], str) and (len(step) == 2 or isinstance(step[2], int)) ): raise SystemExit(f"{op} step must be ('{op}', text[, after_ms]): {step!r}") if op == "expect" and not ( len(step) in {3, 4} and isinstance(step[1], str) and isinstance(step[2], int) and (len(step) == 3 or isinstance(step[3], int)) ): raise SystemExit(f"expect step must be ('expect', regex, timeout_ms[, hold_ms]): {step!r}") if op == "ready" and not (len(step) in {1, 2} and (len(step) == 1 or isinstance(step[1], int))): raise SystemExit(f"ready step must be ('ready'[, timeout_ms]): {step!r}") if op == "ctrl" and not (len(step) == 2 and isinstance(step[1], str) and len(step[1]) == 1): raise SystemExit(f"ctrl step must be ('ctrl', key): {step!r}") if op == "quit" and len(step) != 1: raise SystemExit(f"quit step takes no args: {step!r}") def validate_driver(driver: Driver) -> None: if driver.browser_script and not (ROOT / driver.browser_script).exists(): raise SystemExit(f"browser_script missing: {driver.browser_script}") for name in driver.extensions: if not (EXTENSIONS / name / "index.ts").exists(): raise SystemExit(f"extension missing index.ts: {name}") for name in driver.targets: ext = EXTENSIONS / name if not ext.is_dir(): raise SystemExit(f"target extension missing: {name}") if not (ext / "README.md").exists(): raise SystemExit(f"target README missing: {ext / 'README.md'}") def pi_command(driver: Driver) -> str: parts = [ "pi", "--no-session", "--no-context-files", "--no-skills", "--no-prompt-templates", "--no-extensions", ] for name in driver.extensions: parts.extend(["-e", str(EXTENSIONS / name)]) return " ".join(shlex_quote(part) for part in parts) def shlex_quote(value: str) -> str: import shlex return shlex.quote(value) def pump(child: pexpect.spawn, seconds: float) -> None: end = time.time() + seconds while time.time() < end and child.isalive(): try: data = child.read_nonblocking(size=8192, timeout=0.03) if data: sys.stdout.write(data) sys.stdout.flush() except pexpect.TIMEOUT: pass except pexpect.EOF: break def type_text(child: pexpect.spawn, text: str, delay: float) -> None: for ch in text: child.send(ch) pump(child, delay) def expect_regex(child: pexpect.spawn, pattern: str, timeout_ms: int, hold_ms: int = 300) -> None: try: child.expect(pattern, timeout=timeout_ms / 1000) except pexpect.TIMEOUT as e: raise SystemExit(f"expect timed out after {timeout_ms}ms: {pattern}") from e for data in (child.before, child.after): if isinstance(data, str) and data: sys.stdout.write(data) sys.stdout.flush() pump(child, hold_ms / 1000) def run_step(child: pexpect.spawn, step: tuple) -> bool: op = step[0] if op == "wait": pump(child, step[1] / 1000) elif op == "type": delay = (step[2] if len(step) > 2 else 55) / 1000 type_text(child, step[1], delay) elif op == "send": child.send(step[1]) pump(child, (step[2] if len(step) > 2 else 500) / 1000) elif op == "command": type_text(child, step[1], 0.055) pump(child, 0.35) child.send("\r") pump(child, (step[2] if len(step) > 2 else 1000) / 1000) elif op == "prompt": type_text(child, step[1], 0.035) pump(child, 0.45) child.send("\r") pump(child, (step[2] if len(step) > 2 else 12000) / 1000) elif op == "expect": expect_regex(child, step[1], step[2], step[3] if len(step) > 3 else 300) elif op == "ready": expect_regex(child, r"(›|❯|> )", step[1] if len(step) > 1 else 30000, 300) elif op == "ctrl": child.sendcontrol(step[1]) pump(child, 0.5) elif op == "quit": return True return False def drive(driver: Driver) -> int: child = pexpect.spawn( pi_command(driver), cwd=str(driver.cwd), env={**os.environ, **driver.env}, encoding="utf-8", timeout=90, dimensions=(driver.rows, driver.cols), ) try: for step in driver.steps: if run_step(child, step): break finally: try: child.sendcontrol("c") pump(child, 1.0) except Exception: pass child.terminate(force=True) return 0 def ensure_tools() -> None: missing = [tool for tool in ["asciinema", "agg"] if not shutil.which(tool)] if missing: raise SystemExit(f"missing tool(s): {', '.join(missing)}") def record(driver: Driver, gif_out: Path | None = None) -> tuple[Path, Path, Path]: OUT.mkdir(exist_ok=True) cast = OUT / f"{driver.name}.cast" gif = gif_out or OUT / f"{driver.name}.gif" txt = OUT / f"{driver.name}.txt" gif.parent.mkdir(parents=True, exist_ok=True) if driver.browser_script: subprocess.run( ["bun", str(ROOT / driver.browser_script), "--out", str(gif)], cwd=ROOT, check=True, ) cast.write_text("browser demo: no asciinema cast\n") txt.write_text("browser demo\n") return cast, gif, txt ensure_tools() cmd = [ "asciinema", "rec", "--headless", "--overwrite", "--capture-input", "--window-size", f"{driver.cols}x{driver.rows}", "-i", CAST_IDLE_LIMIT, "-c", f"python3 {shlex_quote(str(Path(__file__).resolve()))} --drive {shlex_quote(driver.name)}", str(cast), ] subprocess.run(cmd, cwd=ROOT, check=True) subprocess.run( [ "agg", "--cols", str(driver.cols), "--rows", str(driver.rows), *AGG_ARGS, str(cast), str(gif), ], cwd=ROOT, check=True, ) subprocess.run( [ "asciinema", "convert", "-f", "txt", str(cast), str(txt), "--overwrite", ], cwd=ROOT, check=True, stdout=subprocess.DEVNULL, ) return cast, gif, txt def readme_block(driver: Driver) -> str: if driver.readme_items: headers = [f"**{caption}**" for caption, _gif in driver.readme_items] images = [f"![{caption}](assets/{gif})" for caption, gif in driver.readme_items] widths = [ max(len(header), len(image), 3) for header, image in zip(headers, images, strict=True) ] def row(cells: list[str]) -> str: padded = [cell.ljust(width) for cell, width in zip(cells, widths, strict=True)] return f"| {' | '.join(padded)} |" separators = ["-" * width for width in widths] body = f"{row(headers)}\n{row(separators)}\n{row(images)}" return ( f"\n\n" f"{body}\n\n" f"" ) body = f"![{driver.title}](assets/{driver.name}.gif)" return f"\n{body}\n" DEMO_SECTION_RE = re.compile( r"\n*## Demo\n\n.*?\n*", re.DOTALL, ) DEMO_BLOCK_RE = re.compile( r"\n*.*?\n*", re.DOTALL, ) DEMO_NONE_RE = re.compile(r"\n*## Demo\n\nNone\.\n*", re.DOTALL) def strip_demo_blocks(text: str) -> str: text = DEMO_SECTION_RE.sub("\n\n", text) text = DEMO_BLOCK_RE.sub("\n\n", text) text = DEMO_NONE_RE.sub("\n\n", text) return re.sub(r"\n{3,}", "\n\n", text).strip() + "\n" def update_readme(readme: Path, driver: Driver) -> None: text = strip_demo_blocks(readme.read_text()) block = readme_block(driver) lines = text.splitlines() for i, line in enumerate(lines): if line.startswith("# "): updated = ( "\n".join(lines[: i + 1]).rstrip() + "\n\n" + block + "\n\n" + "\n".join(lines[i + 1 :]).lstrip() ) readme.write_text(updated.rstrip() + "\n") return raise SystemExit(f"README missing H1 title: {readme}") def install_assets(driver: Driver, gif: Path) -> None: for name in driver.targets: ext = EXTENSIONS / name assets = ext / "assets" assets.mkdir(exist_ok=True) shutil.copy2(gif, assets / f"{driver.name}.gif") update_readme(ext / "README.md", driver) print(f"OK asset {name}/assets/{driver.name}.gif") def driver_names() -> list[str]: return sorted(path.stem for path in DRIVERS.glob("*.py") if not path.name.startswith("__")) def git(*args: str, check: bool = True, capture: bool = False) -> subprocess.CompletedProcess[str]: return subprocess.run( ["git", *args], cwd=ROOT, check=check, text=True, stdout=subprocess.PIPE if capture else None, stderr=subprocess.PIPE if capture else None, ) def latest_release_tag() -> str | None: proc = git("tag", "--list", "v*", "--sort=-creatordate", capture=True) tags = [line.strip() for line in proc.stdout.splitlines() if line.strip()] return tags[0] if tags else None def changed_since_release(path: Path, tag: str | None) -> bool: rel = str(path.relative_to(ROOT)) if git("status", "--porcelain", "--", rel, capture=True).stdout.strip(): return True if not tag: return True return git("diff", "--quiet", tag, "--", rel, check=False).returncode != 0 def driver_watch_paths(driver: Driver) -> list[Path]: paths = [DRIVERS / f"{driver.name}.py"] paths.extend(EXTENSIONS / name for name in sorted(set(driver.targets + driver.extensions))) return paths def changed_driver_names(names: list[str]) -> list[str]: tag = latest_release_tag() changed: list[str] = [] for name in names: driver = load_driver(name) if any(changed_since_release(path, tag) for path in driver_watch_paths(driver)): changed.append(name) else: print(f"OK demo {name} skipped (unchanged since {tag})") return changed def print_drivers() -> None: for name in driver_names(): driver = load_driver(name) print( f"{name}\ttargets={','.join(driver.targets)}\textensions={','.join(driver.extensions)}" ) def run_demo(name: str, *, no_install: bool, gif_out: Path | None) -> list[Path]: driver = load_driver(name) cast, gif, txt = record(driver, gif_out) print(f"OK cast {cast}") print(f"OK gif {gif}") print(f"OK txt {txt}") if not no_install: install_assets(driver, gif) return [EXTENSIONS / target for target in driver.targets] return [] def selected_names(items: list[str], all_flag: bool, changed_flag: bool) -> tuple[list[str], bool]: if items and items[0] == "all": return driver_names(), False if items and items[0] == "changed": names = items[1:] or driver_names() return changed_driver_names(names), True if all_flag: return driver_names(), False if changed_flag: names = items or driver_names() return changed_driver_names(names), True return items, False def main() -> int: parser = argparse.ArgumentParser(description="Record interactive Pi extension demo GIFs") parser.add_argument( "items", nargs="*", help="driver name(s), or subcommand: list | all | changed" ) parser.add_argument("--drive", dest="drive_name", help=argparse.SUPPRESS) parser.add_argument( "--no-install", action="store_true", help="record only; do not copy assets/update README" ) parser.add_argument("--out", type=Path, help="GIF output path; valid with exactly one driver") parser.add_argument("--all", action="store_true", help="record all drivers") parser.add_argument( "--changed", action="store_true", help="record drivers changed since latest v* tag" ) parser.add_argument("--list", action="store_true", help="list drivers") args = parser.parse_args() if args.drive_name: return drive(load_driver(args.drive_name)) if args.list or (args.items and args.items[0] in {"list", "ls"}): print_drivers() return 0 names, was_changed = selected_names(args.items, args.all, args.changed) if not names: if was_changed: print("OK demo none") return 0 print_drivers() return 0 if args.out and len(names) != 1: raise SystemExit("--out requires exactly one driver") touched: set[Path] = set() for name in names: touched.update(run_demo(name, no_install=args.no_install, gif_out=args.out)) print(f"OK demo {name}") return 0 if __name__ == "__main__": raise SystemExit(main())