repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

scripts/demo.py

Raw
#!/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"<!-- demo:{driver.readme_id}:start -->\n\n"
            f"{body}\n\n"
            f"<!-- demo:{driver.readme_id}:end -->"
        )
    body = f"![{driver.title}](assets/{driver.name}.gif)"
    return f"<!-- demo:{driver.readme_id}:start -->\n{body}\n<!-- demo:{driver.readme_id}:end -->"


DEMO_SECTION_RE = re.compile(
    r"\n*## Demo\n\n<!-- demo:[^:\n]+:start -->.*?<!-- demo:[^:\n]+:end -->\n*",
    re.DOTALL,
)
DEMO_BLOCK_RE = re.compile(
    r"\n*<!-- demo:[^:\n]+:start -->.*?<!-- demo:[^:\n]+:end -->\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())