scriptcast 0.1.0__py3-none-any.whl

scriptcast/generator.py

@@ -0,0 +1,265 @@
+# scriptcast/generator.py
+import json
+import re
+import shlex
+from collections import deque
+from pathlib import Path
+
+from .config import ScriptcastConfig
+from .directives import build_directives
+
+
+def _parse_sc_header(
+    lines: list[str],
+    base: ScriptcastConfig | None = None,
+) -> ScriptcastConfig:
+    """Parse .sc JSONL header + pre-scene set directives into a ScriptcastConfig.
+
+    Reads the first line as a JSON header for width/height/directive-prefix.
+    Then walks subsequent lines applying 'set' directives until the first 'scene'.
+    If *base* is provided, its fields serve as defaults overridden by the header.
+    """
+    if not lines:
+        return base.copy() if base is not None else ScriptcastConfig()
+
+    try:
+        header = json.loads(lines[0])
+    except json.JSONDecodeError:
+        return base.copy() if base is not None else ScriptcastConfig()
+
+    if base is not None:
+        config = base.copy()
+        config.directive_prefix = header.get("directive-prefix", config.directive_prefix)
+        config.width = header.get("width", config.width)
+        config.height = header.get("height", config.height)
+    else:
+        config = ScriptcastConfig(
+            directive_prefix=header.get("directive-prefix", "SC"),
+            width=header.get("width", 100),
+            height=header.get("height", 28),
+        )
+
+    for raw in lines[1:]:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            row = json.loads(raw)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(row, list) or len(row) < 3:
+            continue
+        _, typ, text = row[0], row[1], row[2]
+        if typ != "dir":
+            continue
+        parts = shlex.split(str(text))
+        if not parts:
+            continue
+        if parts[0] == "scene":
+            break
+        if parts[0] == "set" and len(parts) >= 3:
+            config.apply("set", parts[1:])
+
+    return config
+
+
+def build_config_from_sc_text(
+    sc_text: str,
+    base: ScriptcastConfig | None = None,
+) -> ScriptcastConfig:
+    """Parse .sc JSONL header and pre-scene set directives into a ScriptcastConfig."""
+    return _parse_sc_header(sc_text.splitlines(), base)
+
+
+def generate_from_sc(
+    sc_path: Path,
+    output_dir: Path,
+    output_stem: str | None = None,
+    *,
+    split_scenes: bool = False,
+    base: ScriptcastConfig | None = None,
+) -> list[Path]:
+    """Read a JSONL .sc file and write .cast file(s) to output_dir."""
+    return generate_from_sc_text(
+        sc_path.read_text(),
+        output_dir,
+        output_stem=output_stem or sc_path.stem,
+        split_scenes=split_scenes,
+        base=base,
+    )
+
+
+def generate_from_sc_text(
+    sc_text: str,
+    output_dir: Path,
+    output_stem: str = "output",
+    *,
+    split_scenes: bool = False,
+    base: ScriptcastConfig | None = None,
+) -> list[Path]:
+    """Convert JSONL .sc text to .cast file(s). Returns list of written paths.
+
+    If *base* is provided, its fields serve as defaults for the generated config.
+    Pre-scene ``set`` directives in the .sc text still override the base, so a
+    theme passed as *base* acts as a template that the script can override.
+    """
+    lines = sc_text.splitlines()
+    if not lines:
+        return []
+
+    header = json.loads(lines[0])
+    pipeline_version = header.get("pipeline-version", 1)
+    if pipeline_version not in (1, 2, 3):
+        raise ValueError(f"Unsupported .sc pipeline-version: {pipeline_version}")
+
+    config = _parse_sc_header(lines, base)
+    config.split_scenes = split_scenes
+
+    events: list[tuple] = []
+    for line in lines[1:]:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            ts, typ, text = json.loads(line)
+            events.append((float(ts), str(typ), str(text)))
+        except (json.JSONDecodeError, ValueError):
+            continue
+
+    scenes = _split_scenes(events)
+
+    if config.split_scenes:
+        paths = []
+        for scene_name, scene_events in scenes:
+            content = _render_scene(scene_events, config.copy(), scene_name)
+            path = output_dir / f"{scene_name}.cast"
+            path.write_text(content)
+            paths.append(path)
+        return paths
+
+    cast_header = {
+        "version": 2,
+        "width": config.width,
+        "height": config.height,
+        "timestamp": 0,
+        "env": {"TERM": "xterm-256color"},
+    }
+    all_lines = [json.dumps(cast_header)]
+    cursor = 0.0
+    for scene_name, scene_events in scenes:
+        scene_lines, cursor = _render_scene_lines(scene_events, config.copy(), scene_name, cursor)
+        all_lines.extend(scene_lines)
+    path = output_dir / f"{output_stem}.cast"
+    path.write_text("\n".join(all_lines) + "\n")
+    return [path]
+
+
+def _split_scenes(events: list[tuple]) -> list[tuple[str, list[tuple]]]:
+    scenes: list[tuple[str, list[tuple]]] = []
+    current_name: str | None = None
+    current_events: list[tuple] = []
+
+    for event in events:
+        _, typ, text = event
+        if typ == "dir" and text.split()[0] == "scene":
+            if current_name is not None:
+                scenes.append((current_name, current_events))
+            parts = text.split(maxsplit=1)
+            current_name = parts[1] if len(parts) > 1 else "unnamed"
+            current_events = []
+        else:
+            if current_name is None:
+                current_name = "main"
+            current_events.append(event)
+
+    if current_name is not None:
+        scenes.append((current_name, current_events))
+
+    _overhead = {"set"}
+
+    def _is_overhead_only(evts: list[tuple]) -> bool:
+        return all(
+            typ == "dir" and text.split()[0] in _overhead
+            for _, typ, text in evts
+        )
+
+    return [
+        (name, evts)
+        for name, evts in scenes
+        if not (name == "main" and _is_overhead_only(evts))
+    ]
+
+
+def _render_scene(
+    events: list[tuple],
+    config: ScriptcastConfig,
+    scene_name: str,
+) -> str:
+    cast_header = {
+        "version": 2,
+        "width": config.width,
+        "height": config.height,
+        "timestamp": 0,
+        "env": {"TERM": "xterm-256color"},
+    }
+    lines, _ = _render_scene_lines(events, config, scene_name, 0.0)
+    return "\n".join([json.dumps(cast_header)] + lines) + "\n"
+
+
+def _render_scene_lines(
+    events: list[tuple],
+    config: ScriptcastConfig,
+    scene_name: str,
+    initial_cursor: float = 0.0,
+) -> tuple[list[str], float]:
+    lines: list[str] = []
+    cursor = initial_cursor
+    active = config.copy()
+    # Build gen registry: directive name → directive instance
+    # Uses handles attribute; directives without handles are recorder-only.
+    all_directives = build_directives(active.directive_prefix, active.trace_prefix)
+    gen_registry = {d.handles: d for d in all_directives if d.handles is not None}
+
+    lines.append(json.dumps([round(cursor, 6), "o", "\x1b[2J\x1b[H"]))
+    cursor += active.enter_wait / 1000.0
+
+    queue: deque[tuple] = deque(events)
+    while queue:
+        event = queue.popleft()
+        _, typ, text = event
+
+        if typ == "dir":
+            parts = text.split()
+            name = parts[0] if parts else ""
+            d = gen_registry.get(name)
+            if d is not None:
+                cursor, new_lines = d.gen(event, queue, active, cursor)
+                lines.extend(new_lines)
+
+        elif typ == "cmd":
+            lines.append(json.dumps([round(cursor, 6), "o", active.prompt]))
+            cursor += active.cmd_wait / 1000.0
+            for char in text:
+                cursor += active.type_speed / 1000.0
+                lines.append(json.dumps([round(cursor, 6), "o", char]))
+                if char == " ":
+                    cursor += active.effective_word_pause_s
+            cursor += active.type_speed / 1000.0
+            lines.append(json.dumps([round(cursor, 6), "o", "\r\n"]))
+
+        elif typ == "out":
+            if active.cr_delay > 0 and '\r' in text:
+                # Split before each bare \r (not \r\n) for progress-bar animation
+                parts = re.split(r'(?=\r(?!\n))', text)
+                for j, part in enumerate(parts):
+                    if part:
+                        lines.append(json.dumps([round(cursor, 6), "o", part]))
+                    if j < len(parts) - 1:
+                        cursor += active.cr_delay / 1000.0
+            elif text:
+                lines.append(json.dumps([round(cursor, 6), "o", text]))
+
+    lines.append(json.dumps([round(cursor, 6), "o", active.prompt]))
+    cursor += active.exit_wait / 1000.0
+    lines.append(json.dumps([round(cursor, 6), "o", ""]))
+    return lines, cursor

scriptcast/recorder.py

@@ -0,0 +1,212 @@
+# scriptcast/recorder.py
+import errno
+import fcntl
+import json
+import logging
+import os
+import pty
+import re
+import struct
+import subprocess
+import tempfile
+import termios
+import time
+from pathlib import Path
+
+from .config import ScriptcastConfig
+from .directives import ScEvent, build_directives
+from .shell import get_adapter
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_raw(
+    raw_text: str,
+    trace_prefix: str = "+",
+    directive_prefix: str = "SC",
+) -> list[ScEvent]:
+    """Parse raw xtrace log text into an initial list of ScEvents.
+
+    Each record has the form: "<ts> <content><term>" where <term> is either
+    \\n or empty (last record with no terminator).  Bare \\r within content
+    is preserved verbatim — it is not a record separator.
+
+    Classification rules (per record):
+      "+ : SC <rest>"  →  ScEvent(ts, "dir",  rest)   — terminator discarded, trailing \\r stripped
+      "+ <cmd>"        →  ScEvent(ts, "cmd",  cmd)    — terminator discarded, trailing \\r stripped
+      "<text>"         →  ScEvent(ts, "out",  text + term)  — verbatim, \\r preserved
+
+    Lines with non-float timestamps are skipped.
+    """
+    sc_prefix = f"{trace_prefix} : {directive_prefix} "
+    trace_prefix_sp = f"{trace_prefix} "
+    events: list[ScEvent] = []
+
+    # Split on any line terminator, keeping each terminator as a token.
+    # re.split with a capturing group gives [c0, t0, c1, t1, ..., cN].
+    parts = re.split(r'(\n)', raw_text)
+
+    i = 0
+    while i < len(parts):
+        entry = parts[i]
+        term = parts[i + 1] if i + 1 < len(parts) else ''
+        i += 2
+
+        if not entry:
+            continue
+        ts_str, _, content = entry.partition(' ')
+        try:
+            ts = float(ts_str)
+        except ValueError:
+            continue
+
+        if content.startswith(sc_prefix):
+            events.append(ScEvent(ts, "dir", content[len(sc_prefix):].removesuffix('\r')))
+        elif content.startswith(trace_prefix_sp):
+            events.append(ScEvent(ts, "cmd", content[len(trace_prefix_sp):].removesuffix('\r')))
+        else:
+            events.append(ScEvent(ts, "out", content + term))
+
+    return events
+
+
+def _serialise(events: list[ScEvent]) -> str:
+    """Convert a list of ScEvents to JSONL text (no trailing newline if empty)."""
+    lines = [json.dumps([e.ts, e.type, e.text]) for e in events]
+    return "\n".join(lines) + ("\n" if lines else "")
+
+
+def _preprocess(script_text: str, directive_prefix: str = "SC") -> str:
+    """Rewrite script lines using directive pre-phase before shell execution."""
+    directives = build_directives(directive_prefix)
+    lines = script_text.splitlines(keepends=True)
+    for d in directives:
+        lines = d.pre(lines)
+    return "".join(lines)
+
+
+def _postprocess(
+    raw_text: str,
+    trace_prefix: str = "+",
+    directive_prefix: str = "SC",
+) -> str:
+    """Convert raw .log text to JSONL .sc body (no header line)."""
+    directives = build_directives(directive_prefix, trace_prefix)
+    events = _parse_raw(raw_text, trace_prefix, directive_prefix)
+    for d in directives:
+        events = d.post(events)
+    return _serialise(events)
+
+
+def record(
+    script_path: str | Path,
+    sc_path: str | Path,
+    config: ScriptcastConfig,
+    shell: str,
+    xtrace_log: bool = False,
+) -> int:
+    """Run script_path in shell with tracing, write cleaned output to sc_path.
+
+    If xtrace_log is True, the raw PTY capture (before postprocessing) is
+    written to a file beside sc_path with the suffix ``.xtrace``.
+
+    Returns the shell exit code. Warns (does not raise) on non-zero exit.
+    """
+    script_path = Path(script_path)
+    sc_path = Path(sc_path)
+    adapter = get_adapter(shell)
+
+    preamble = adapter.tracing_preamble(config.trace_prefix)
+
+    script_content = script_path.read_text()
+    if script_content.startswith("#!"):
+        _, _, script_content = script_content.partition("\n")
+
+    script_content = _preprocess(script_content, config.directive_prefix)
+    logger.debug(
+        "Recording %s (shell=%s, width=%d, height=%d)",
+        script_path.name, shell, config.width, config.height,
+    )
+
+    master_fd = -1
+    proc = None
+    tmp = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".sh", delete=False, dir=tempfile.gettempdir()
+    )
+    try:
+        tmp.write(preamble)
+        tmp.write(script_content)
+        tmp.flush()
+        tmp.close()
+
+        master_fd, slave_fd = pty.openpty()
+        try:
+            fcntl.ioctl(
+                slave_fd, termios.TIOCSWINSZ,
+                struct.pack('HHHH', config.height, config.width, 0, 0),
+            )
+            stdin_fd = os.open('/dev/null', os.O_RDONLY)
+            try:
+                proc = subprocess.Popen(
+                    [shell, tmp.name],
+                    stdin=stdin_fd,
+                    stdout=slave_fd,
+                    stderr=slave_fd,
+                    close_fds=True,
+                    cwd=script_path.parent,
+                )
+            finally:
+                os.close(slave_fd)
+                os.close(stdin_fd)
+        except Exception:
+            os.close(master_fd)
+            master_fd = -1
+            raise
+
+        raw_lines: list[str] = []
+        try:
+            with open(master_fd, 'rb', closefd=False) as f:
+                for line in f:
+                    raw_lines.append(f"{time.time():.3f} {line.decode('utf-8', errors='replace')}")
+        except OSError as e:
+            if e.errno != errno.EIO:
+                raise
+        # Note: output without a trailing newline (e.g. printf "text") is not
+        # captured — the BufferedReader discards partial data when EIO fires.
+        os.close(master_fd)
+        master_fd = -1  # signal to finally: already closed
+        proc.wait()
+
+        logger.debug("PTY capture complete: %d raw lines", len(raw_lines))
+
+        raw_text = "".join(raw_lines)
+        if xtrace_log:
+            xtrace_path = sc_path.with_suffix('.xtrace')
+            xtrace_path.write_text(raw_text)
+            logger.info("Saved: %s", xtrace_path)
+        clean_text = _postprocess(raw_text, config.trace_prefix, config.directive_prefix)
+        logger.debug("Post-processed to %d events", clean_text.count("\n"))
+
+        header = json.dumps({
+            "version": 1,
+            "shell": adapter.name,
+            "width": config.width,
+            "height": config.height,
+            "directive-prefix": config.directive_prefix,
+            "pipeline-version": 3,
+        })
+        sc_path.write_text(header + "\n" + clean_text)
+
+        if proc.returncode != 0:
+            logger.warning(
+                "Script exited with non-zero status %d; .sc file written anyway.",
+                proc.returncode,
+            )
+        return proc.returncode
+    finally:
+        if master_fd != -1:
+            os.close(master_fd)
+        if proc is not None and proc.poll() is None:
+            proc.terminate()
+            proc.wait()
+        os.unlink(tmp.name)

scriptcast/shell/__init__.py

@@ -0,0 +1,20 @@
+# scriptcast/shell/__init__.py
+from .adapter import ShellAdapter
+from .bash import BashAdapter
+from .zsh import ZshAdapter
+
+_ADAPTERS: dict[str, ShellAdapter] = {
+    "bash": BashAdapter(),
+    "zsh": ZshAdapter(),
+}
+
+def get_adapter(shell: str) -> ShellAdapter:
+    """Return adapter for shell name or full path (e.g. '/bin/bash' → BashAdapter).
+    Raises ValueError for unsupported shells.
+    """
+    name = shell.split("/")[-1]
+    if name not in _ADAPTERS:
+        raise ValueError(
+            f"Unsupported shell: {shell!r}. Supported: {list(_ADAPTERS)}"
+        )
+    return _ADAPTERS[name]

scriptcast/shell/adapter.py

@@ -0,0 +1,13 @@
+# scriptcast/shell/adapter.py
+from abc import ABC, abstractmethod
+
+
+class ShellAdapter(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @abstractmethod
+    def tracing_preamble(self, trace_prefix: str) -> str:
+        """Return shell code to enable tracing with the given prefix."""
+        ...

scriptcast/shell/bash.py

@@ -0,0 +1,11 @@
+# scriptcast/shell/bash.py
+from .adapter import ShellAdapter
+
+
+class BashAdapter(ShellAdapter):
+    @property
+    def name(self) -> str:
+        return "bash"
+
+    def tracing_preamble(self, trace_prefix: str) -> str:
+        return f'PS4="{trace_prefix} "\nset -x\n'

scriptcast/shell/zsh.py

@@ -0,0 +1,11 @@
+# scriptcast/shell/zsh.py
+from .adapter import ShellAdapter
+
+
+class ZshAdapter(ShellAdapter):
+    @property
+    def name(self) -> str:
+        return "zsh"
+
+    def tracing_preamble(self, trace_prefix: str) -> str:
+        return f'PS4="{trace_prefix} "\nsetopt xtrace\n'

scriptcast-0.1.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: scriptcast
+Version: 0.1.0
+Summary: Generate terminal demos (asciinema casts & GIFs) from simple shell-like scripts.
+Author-email: Nasser Alansari <dacrystal@users.noreply.github.com>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pillow>=9.0
+Provides-Extra: dev
+Requires-Dist: asciinema>=2.4.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: git-cliff>=2.0; extra == "dev"

scriptcast-0.1.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+scriptcast/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scriptcast/__main__.py,sha256=XX2_fh8fXEDW5c67IPuYc4m9LUDHkycUuygryntMnSs,13415
+scriptcast/config.py,sha256=COMFJLg5IPMlhzFXY6Sk7bi7mavV6XJAqt2_uHLjah8,7610
+scriptcast/directives.py,sha256=nYXW8cFCuZYj6i5wfiTu1e9NfxPVsE4OCb8-9-3mXjA,15050
+scriptcast/export.py,sha256=vPXNHvdK7kXsyxBImHwehWNfl2GlRBEjUyBNP5Lx90g,20085
+scriptcast/generator.py,sha256=MxKc2zoTfzGwLC6xzg5Ni_chE1lhKkpy90UvUGSpNJ8,8661
+scriptcast/recorder.py,sha256=-TLo_oFF_CE2GViDMHYCKoo6Q3tzd3a1PDHu8YbBD6Y,6974
+scriptcast/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scriptcast/assets/fonts/DMSans-Regular.ttf,sha256=qVoziUKqNXFFQnvnyWP_aR-f6FnDUS2cBIPhkU1Xogg,78256
+scriptcast/assets/fonts/Pacifico.ttf,sha256=W2wNUzSnv3fepSuXXFoMQIh4wPcRXtW2-xUfY0t79wE,329380
+scriptcast/assets/themes/aurora.sh,sha256=futWVqJ2tH2WgbQ-Pj-3ONQM-5o2zJ8M3AX57MGxWHU,666
+scriptcast/assets/themes/dark.sh,sha256=-nqvnitACQ_dHgHZYCUvuED1bZ1GTUTlBLOljHUywCw,631
+scriptcast/assets/themes/light.sh,sha256=bFi3WDgI_ppotocaTox76JBJAkec_xcO1jgiQfVnTI0,631
+scriptcast/shell/__init__.py,sha256=iCT6AUH6s1ljS4KkC5YwxZ4mCmaU1cFuOLwpkp5_-mc,602
+scriptcast/shell/adapter.py,sha256=aswPs514-jaFTyETxnze9EKXv4c8Ahh50oYrDjBDTWI,322
+scriptcast/shell/bash.py,sha256=VRvVeKAEb5Og6uXpWeLp2xha9_UzQ3v8t5HCBJvlu14,268
+scriptcast/shell/zsh.py,sha256=47F44D0q5QlmcANgIDUbkgIgT5EnwgRSiW7zEWoutl4,272
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_cli.py,sha256=5vtfdy5MgjqD_bS1CTizSfnQXfXip1QpfmwKWKV9l8E,11380
+tests/test_config.py,sha256=RPaP0LqfOKEfxuP4NG0__ZDuAtbaiuPrRl8bOaTewZ0,13111
+tests/test_directives.py,sha256=n4Tz2gp0NnWWuCua49qsKJWNuXNq_J66E-50AV5a6Gc,19032
+tests/test_export.py,sha256=GlwGho6rWjrq5SKauxNKdgCRqtEGlqxUHSIP0m4T3-E,38461
+tests/test_generator.py,sha256=_HFmZH3ajctEKBMz0Kw6kRw6p2SgVIIK9R0XinpFjSk,14490
+tests/test_integration.py,sha256=VBFBUNHQLWiUkb7cLWWdW95R7HraHIDNt78BUN6btPk,3284
+tests/test_recorder.py,sha256=ZN5MiwmYbsXpXXfZCr8wx8NmxaRU8bZgrrJx0lziTCU,15802
+tests/test_registry.py,sha256=zqRMdR0M4TsUsx4EPB6x6Dgv5YuxxDZY5yKWrURHulI,1471
+tests/test_shell.py,sha256=IU8FpX7RoyreabtcassC87cO6zzUpojoruAvjQ9QwzM,933
+tests/test_theme.py,sha256=mR0uxvznJE9XYHwPWzXYT0L3TfabsonRewqkdXe5yV0,6898
+scriptcast-0.1.0.dist-info/METADATA,sha256=1krzrP7aIfIKUZUayOMjmqRuXXFeDeJLZECjxCOk1tY,835
+scriptcast-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scriptcast-0.1.0.dist-info/entry_points.txt,sha256=-GcwrQR9RHWFrD3kgAeEOViuc_02JmHoHBCEfw6m0w0,55
+scriptcast-0.1.0.dist-info/top_level.txt,sha256=q338tb0EgIDmLUyS3fcLPWbYG8C7BIvo-isL-yRsq7k,17
+scriptcast-0.1.0.dist-info/RECORD,,

scriptcast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scriptcast-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scriptcast = scriptcast.__main__:cli

scriptcast-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+scriptcast
+tests