smartcli-toolkit 0.1.0__py3-none-any.whl

smartcli_core/__init__.py

@@ -0,0 +1,53 @@
+"""SmartCLI shared core.
+
+A pluggable-PTY + pyte screen model + semantic snapshot + readiness stack for
+driving interactive terminal programs. Both SmartCLI skills build on this.
+
+Quick start::
+
+    from smartcli_core import PtySession
+
+    with PtySession(cols=100, rows=30) as sess:
+        sess.start("python")
+        sess.wait_ready(marker=r">>> $")
+        sess.send_line("print('hello')")
+        reason, snap = sess.wait_ready(marker=r">>> $")
+        print(snap.to_text())
+"""
+
+from __future__ import annotations
+
+from .pty_backend import (
+    PosixPtyBackend,
+    PtyBackend,
+    WinptyBackend,
+    get_default_backend,
+)
+from .readiness import wait_for_regex, wait_ready, wait_until_stable
+from .screen_model import CellAttrs, ScreenModel
+from .session import KEY_MAP, PtySession
+from .snapshot import Snapshot, Span, build_snapshot
+
+__all__ = [
+    # backends
+    "PtyBackend",
+    "WinptyBackend",
+    "PosixPtyBackend",
+    "get_default_backend",
+    # screen
+    "ScreenModel",
+    "CellAttrs",
+    # snapshot
+    "Snapshot",
+    "Span",
+    "build_snapshot",
+    # readiness
+    "wait_until_stable",
+    "wait_for_regex",
+    "wait_ready",
+    # session
+    "PtySession",
+    "KEY_MAP",
+]
+
+__version__ = "0.1.0"

smartcli_core/pty_backend.py

@@ -0,0 +1,259 @@
+"""Pluggable PTY backends for SmartCLI.
+
+A :class:`PtyBackend` abstracts spawning a child process attached to a
+pseudo-terminal and exchanging bytes with it. Two concrete backends ship:
+
+* :class:`WinptyBackend` -- uses ``pywinpty`` (ConPTY) on Windows. ``pywinpty``
+  reads are blocking and return ``str``; a background reader thread drains the
+  process into a queue so :meth:`read_nonblocking` never blocks.
+* :class:`PosixPtyBackend` -- uses the stdlib ``pty``/``os``/``select`` stack.
+  The POSIX-only imports are guarded so this module imports cleanly on Windows.
+
+Both backends normalise their read side to **bytes** so the rest of the core
+(screen model, readiness) can feed a single long-lived ``pyte.ByteStream``.
+
+Use :func:`get_default_backend` to obtain the right backend for the host.
+"""
+
+from __future__ import annotations
+
+import abc
+import queue
+import sys
+import threading
+import time
+from typing import Optional, Sequence, Union
+
+
+class PtyBackend(abc.ABC):
+    """Abstract pseudo-terminal backend.
+
+    Implementations own a child process running under a PTY sized ``cols`` x
+    ``rows``. All reads are non-blocking and return raw ``bytes`` (possibly
+    empty). Writes accept ``bytes``.
+    """
+
+    @abc.abstractmethod
+    def spawn(self, cmd: Union[str, Sequence[str]], cols: int, rows: int) -> None:
+        """Launch ``cmd`` in a PTY of size ``cols`` x ``rows``."""
+
+    @abc.abstractmethod
+    def read_nonblocking(self) -> bytes:
+        """Return any bytes available right now; ``b""`` if none. Never blocks."""
+
+    @abc.abstractmethod
+    def write(self, data: bytes) -> None:
+        """Write ``data`` to the child's stdin."""
+
+    @abc.abstractmethod
+    def resize(self, cols: int, rows: int) -> None:
+        """Resize the PTY window to ``cols`` x ``rows``."""
+
+    @abc.abstractmethod
+    def is_alive(self) -> bool:
+        """Return ``True`` while the child process is running."""
+
+    @abc.abstractmethod
+    def terminate(self) -> None:
+        """Terminate the child and release resources. Idempotent."""
+
+
+class WinptyBackend(PtyBackend):
+    """PTY backend built on ``pywinpty`` (ConPTY).
+
+    ``pywinpty`` returns already-decoded ``str`` and its ``read`` can block, so a
+    daemon reader thread performs blocking reads and pushes UTF-8 encoded chunks
+    into a :class:`queue.Queue`. :meth:`read_nonblocking` drains that queue.
+    """
+
+    def __init__(self) -> None:
+        self._proc = None  # winpty.PtyProcess
+        self._queue: "queue.Queue[Optional[bytes]]" = queue.Queue()
+        self._reader: Optional[threading.Thread] = None
+        self._eof = False
+
+    def spawn(self, cmd: Union[str, Sequence[str]], cols: int, rows: int) -> None:
+        import winpty  # imported lazily so non-Windows hosts don't require it
+
+        # winpty.spawn accepts a command string or an argv list; dimensions are
+        # (rows, cols).
+        self._proc = winpty.PtyProcess.spawn(cmd, dimensions=(rows, cols))
+        self._reader = threading.Thread(target=self._read_loop, daemon=True)
+        self._reader.start()
+
+    def _read_loop(self) -> None:
+        """Blocking-read the child until EOF, pushing bytes into the queue."""
+        proc = self._proc
+        while True:
+            try:
+                data = proc.read(65536)  # returns str; blocks if nothing ready
+            except EOFError:
+                break
+            except OSError:
+                break
+            if data:
+                self._queue.put(data.encode("utf-8", "replace"))
+        self._queue.put(None)  # EOF sentinel
+
+    def read_nonblocking(self) -> bytes:
+        out = bytearray()
+        while True:
+            try:
+                item = self._queue.get_nowait()
+            except queue.Empty:
+                break
+            if item is None:
+                self._eof = True
+                break
+            out.extend(item)
+        return bytes(out)
+
+    def write(self, data: bytes) -> None:
+        if self._proc is None:
+            raise RuntimeError("spawn() must be called before write()")
+        # pywinpty.write expects str.
+        self._proc.write(data.decode("utf-8", "replace"))
+
+    def resize(self, cols: int, rows: int) -> None:
+        if self._proc is not None:
+            self._proc.setwinsize(rows, cols)
+
+    def is_alive(self) -> bool:
+        if self._proc is None:
+            return False
+        try:
+            return bool(self._proc.isalive())
+        except Exception:
+            return False
+
+    def terminate(self) -> None:
+        if self._proc is None:
+            return
+        try:
+            self._proc.terminate(force=True)
+        except Exception:
+            pass
+        finally:
+            self._proc = None
+
+
+class PosixPtyBackend(PtyBackend):
+    """PTY backend built on the stdlib ``pty``/``os``/``select`` stack.
+
+    Only usable on POSIX hosts. The heavy imports happen inside :meth:`spawn`
+    (and a small module-level guard) so importing this file on Windows is safe.
+    """
+
+    def __init__(self) -> None:
+        self._pid: Optional[int] = None
+        self._fd: Optional[int] = None
+        self._eof = False
+
+    def spawn(self, cmd: Union[str, Sequence[str]], cols: int, rows: int) -> None:
+        import fcntl
+        import os
+        import pty
+        import struct
+        import termios
+
+        if isinstance(cmd, str):
+            argv = ["/bin/sh", "-c", cmd]
+        else:
+            argv = list(cmd)
+
+        pid, master_fd = pty.fork()
+        if pid == 0:  # child
+            try:
+                os.execvp(argv[0], argv)
+            except Exception:
+                os._exit(127)
+        # parent
+        self._pid = pid
+        self._fd = master_fd
+        os.set_blocking(master_fd, False)
+        fcntl.ioctl(
+            master_fd,
+            termios.TIOCSWINSZ,
+            struct.pack("HHHH", rows, cols, 0, 0),
+        )
+
+    def read_nonblocking(self) -> bytes:
+        import os
+        import select
+
+        if self._fd is None:
+            return b""
+        out = bytearray()
+        while True:
+            r, _, _ = select.select([self._fd], [], [], 0)
+            if not r:
+                break
+            try:
+                chunk = os.read(self._fd, 65536)
+            except BlockingIOError:
+                break
+            except OSError:  # EIO on child exit (Linux)
+                self._eof = True
+                break
+            if not chunk:  # EOF (BSD/mac)
+                self._eof = True
+                break
+            out.extend(chunk)
+        return bytes(out)
+
+    def write(self, data: bytes) -> None:
+        import os
+
+        if self._fd is None:
+            raise RuntimeError("spawn() must be called before write()")
+        os.write(self._fd, data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        import fcntl
+        import struct
+        import termios
+
+        if self._fd is not None:
+            fcntl.ioctl(
+                self._fd,
+                termios.TIOCSWINSZ,
+                struct.pack("HHHH", rows, cols, 0, 0),
+            )
+
+    def is_alive(self) -> bool:
+        import os
+
+        if self._pid is None:
+            return False
+        try:
+            pid, _ = os.waitpid(self._pid, os.WNOHANG)
+            return pid == 0
+        except OSError:
+            return False
+
+    def terminate(self) -> None:
+        import os
+        import signal
+
+        if self._pid is not None:
+            try:
+                os.kill(self._pid, signal.SIGTERM)
+            except OSError:
+                pass
+        if self._fd is not None:
+            try:
+                os.close(self._fd)
+            except OSError:
+                pass
+        self._pid = None
+        self._fd = None
+
+
+def get_default_backend() -> PtyBackend:
+    """Return a backend appropriate for the current platform.
+
+    Windows -> :class:`WinptyBackend`; everything else -> :class:`PosixPtyBackend`.
+    """
+    if sys.platform == "win32":
+        return WinptyBackend()
+    return PosixPtyBackend()

smartcli_core/readiness.py

@@ -0,0 +1,210 @@
+"""Readiness synchronisation for driving an interactive PTY program.
+
+Three independent signals, combined so the agent never fires input into a
+program that isn't ready and never hangs on an animation:
+
+* **Quiescence** -- no bytes arriving (transport level).
+* **Screen stability** -- the pyte content hash stops changing (semantic level,
+  survives chunked/bursty reads). Cursor-only and attribute-only changes are
+  excluded from the hash upstream in :meth:`ScreenModel.content_hash`.
+* **Marker match** -- an expected regex appears (strongest signal).
+
+Every wait has a hard ``max_wait`` ceiling so spinners/progress bars return the
+last screen instead of hanging.
+
+The functions take plain callables (``read_fn`` to pump bytes, ``get_screen_hash_fn``
+to sample stability, ``get_snapshot_fn`` to produce a result) so they stay
+decoupled from the session/backend concrete types.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Callable, Optional, Tuple
+
+# Callable aliases (documentation only)
+ReadFn = Callable[[], bytes]      # pump: read+feed one batch, return bytes read
+HashFn = Callable[[], int]        # sample the cursor-excluded content hash
+TextFn = Callable[[], str]        # current rendered screen text (for regex)
+
+
+def _ms(seconds: float) -> float:
+    return seconds
+
+
+def wait_until_stable(
+    read_fn: ReadFn,
+    get_screen_hash_fn: HashFn,
+    quiet_ms: int = 200,
+    poll_ms: int = 30,
+    max_wait_ms: int = 8000,
+    grace_ms: int = 40,
+    min_wait_ms: int = 0,
+) -> bool:
+    """Pump reads until the screen hash is unchanged for ``quiet_ms``.
+
+    The stable timer resets on *either* new bytes arriving *or* the hash
+    changing; quiet time accumulates only when both are absent. After stability
+    is declared a short ``grace`` sleep absorbs a late flush, then one final
+    drain re-checks; if the flush changed the screen, the wait resumes.
+
+    Args:
+        read_fn: called each poll to read+feed a batch; returns bytes read.
+        get_screen_hash_fn: returns the current cursor-excluded content hash.
+        quiet_ms: continuous no-change duration required to declare stable.
+        poll_ms: sleep between polls when idle.
+        max_wait_ms: hard ceiling; returns ``False`` if reached.
+        grace_ms: final settle sleep after stability, before returning.
+        min_wait_ms: minimum elapsed time before stability may be declared
+            (guards the stale-screen race right after sending input).
+
+    Returns:
+        ``True`` if the screen settled, ``False`` on timeout.
+    """
+    poll = poll_ms / 1000.0
+    quiet = quiet_ms / 1000.0
+    grace = grace_ms / 1000.0
+    min_wait = min_wait_ms / 1000.0
+
+    start = time.monotonic()
+    deadline = start + (max_wait_ms / 1000.0)
+    last_hash: Optional[int] = None
+    stable_since: Optional[float] = None
+
+    while True:
+        now = time.monotonic()
+        data = read_fn()
+        h = get_screen_hash_fn()
+        elapsed = now - start
+
+        if not data and h == last_hash:
+            if stable_since is None:
+                stable_since = now
+            elif (now - stable_since) >= quiet and elapsed >= min_wait:
+                if grace > 0:
+                    time.sleep(grace)
+                tail = read_fn()
+                if tail:
+                    # late flush: resume waiting
+                    stable_since = None
+                    last_hash = get_screen_hash_fn()
+                    continue
+                return True
+        else:
+            stable_since = None
+            last_hash = h
+
+        if now >= deadline:
+            return False
+        time.sleep(poll)
+
+
+def wait_for_regex(
+    read_fn: ReadFn,
+    get_text_fn: TextFn,
+    get_snapshot_fn: Callable[[], object],
+    pattern: str,
+    timeout_ms: int = 10000,
+    poll_ms: int = 30,
+    min_wait_ms: int = 0,
+    flags: int = 0,
+) -> Tuple[bool, object]:
+    """Pump reads until ``pattern`` matches the rendered screen, or timeout.
+
+    Args:
+        read_fn: called each poll to read+feed a batch.
+        get_text_fn: returns the current screen text searched by the regex.
+        get_snapshot_fn: builds the :class:`Snapshot` returned to the caller.
+        pattern: regular expression searched against the whole screen text.
+        timeout_ms: hard ceiling.
+        poll_ms: sleep between polls when idle.
+        min_wait_ms: ignore matches before this much time has elapsed (guards
+            against matching a stale prior prompt).
+        flags: extra ``re`` flags (``re.I`` etc.).
+
+    Returns:
+        ``(matched, snapshot)`` -- ``snapshot`` is always the current screen,
+        even on timeout, so the agent can act on the last state.
+    """
+    rx = re.compile(pattern, flags)
+    poll = poll_ms / 1000.0
+    min_wait = min_wait_ms / 1000.0
+    start = time.monotonic()
+    deadline = start + (timeout_ms / 1000.0)
+
+    while True:
+        now = time.monotonic()
+        read_fn()
+        elapsed = now - start
+        if elapsed >= min_wait and rx.search(get_text_fn()):
+            return True, get_snapshot_fn()
+        if now >= deadline:
+            return False, get_snapshot_fn()
+        time.sleep(poll)
+
+
+def wait_ready(
+    read_fn: ReadFn,
+    get_screen_hash_fn: HashFn,
+    get_text_fn: TextFn,
+    get_snapshot_fn: Callable[[], object],
+    marker: Optional[str] = None,
+    quiet_ms: int = 200,
+    poll_ms: int = 30,
+    max_wait_ms: int = 10000,
+    min_wait_ms: int = 50,
+    grace_ms: int = 40,
+    flags: int = 0,
+) -> Tuple[str, object]:
+    """Unified wait: satisfy on ``marker`` OR screen stability, capped by max_wait.
+
+    A single loop races the marker (if given) against stability so callers get
+    the earliest safe moment. ``min_wait_ms`` guards the stale-screen race after
+    sending input.
+
+    Returns:
+        ``(reason, snapshot)`` where ``reason`` is ``"MARKER"``, ``"STABLE"`` or
+        ``"TIMEOUT"``. The snapshot is always the current screen.
+    """
+    rx = re.compile(marker, flags) if marker else None
+    poll = poll_ms / 1000.0
+    quiet = quiet_ms / 1000.0
+    grace = grace_ms / 1000.0
+    min_wait = min_wait_ms / 1000.0
+
+    start = time.monotonic()
+    deadline = start + (max_wait_ms / 1000.0)
+    last_hash: Optional[int] = None
+    stable_since: Optional[float] = None
+
+    while True:
+        now = time.monotonic()
+        data = read_fn()
+        elapsed = now - start
+
+        # 1) marker wins immediately (respect min_wait)
+        if rx is not None and elapsed >= min_wait and rx.search(get_text_fn()):
+            return "MARKER", get_snapshot_fn()
+
+        # 2) stability
+        h = get_screen_hash_fn()
+        if not data and h == last_hash:
+            if stable_since is None:
+                stable_since = now
+            elif (now - stable_since) >= quiet and elapsed >= min_wait:
+                if grace > 0:
+                    time.sleep(grace)
+                tail = read_fn()
+                if tail:
+                    stable_since = None
+                    last_hash = get_screen_hash_fn()
+                    continue
+                return "STABLE", get_snapshot_fn()
+        else:
+            stable_since = None
+            last_hash = h
+
+        if now >= deadline:
+            return "TIMEOUT", get_snapshot_fn()
+        time.sleep(poll)

smartcli_core/screen_model.py

@@ -0,0 +1,132 @@
+"""Thin wrapper over ``pyte`` that turns a byte stream into an inspectable grid.
+
+:class:`ScreenModel` owns a single long-lived ``pyte.ByteStream`` + ``pyte.Screen``
+pair. Feed raw PTY bytes with :meth:`feed`; the stream is stateful and stream-safe
+so partial ANSI escapes and split multibyte UTF-8 across reads are handled
+correctly. Never recreate the stream per read.
+
+Exposes plain text (``pyte.screen.display``), the cursor, a stability hash, and a
+per-cell attribute reader that copes with the sparse dict-of-dicts buffer.
+"""
+
+from __future__ import annotations
+
+import zlib
+from typing import List, NamedTuple, Tuple
+
+import pyte
+
+
+class CellAttrs(NamedTuple):
+    """Reduced view of a single :class:`pyte.screens.Char`."""
+
+    data: str
+    fg: str
+    bg: str
+    bold: bool
+    reverse: bool
+
+
+class ScreenModel:
+    """Feed PTY bytes into a ``pyte`` screen and read structured state back out."""
+
+    def __init__(self, cols: int = 80, rows: int = 24) -> None:
+        self._cols = cols
+        self._rows = rows
+        self.screen = pyte.Screen(cols, rows)
+        # ByteStream decodes UTF-8 incrementally, so multibyte chars split across
+        # feed() boundaries are reassembled correctly.
+        self.stream = pyte.ByteStream(self.screen)
+
+    # -- feeding -----------------------------------------------------------
+
+    def feed(self, data: bytes) -> None:
+        """Feed raw bytes from the PTY into the screen. Safe with partial data."""
+        if data:
+            self.stream.feed(data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        """Resize the underlying screen. Keep this in sync with the PTY winsize."""
+        self._cols = cols
+        self._rows = rows
+        # pyte.Screen.resize takes (lines, columns).
+        self.screen.resize(rows, cols)
+
+    # -- geometry ----------------------------------------------------------
+
+    @property
+    def cols(self) -> int:
+        return self.screen.columns
+
+    @property
+    def rows(self) -> int:
+        return self.screen.lines
+
+    # -- plain text --------------------------------------------------------
+
+    @property
+    def display(self) -> List[str]:
+        """List of rendered lines (wide-char aware, right-padded to ``cols``)."""
+        return list(self.screen.display)
+
+    def text(self) -> str:
+        """The full screen joined with newlines (trailing padding preserved)."""
+        return "\n".join(self.screen.display)
+
+    # -- cursor ------------------------------------------------------------
+
+    @property
+    def cursor(self) -> Tuple[int, int]:
+        """Cursor as ``(row, col)``, both 0-based."""
+        return (self.screen.cursor.y, self.screen.cursor.x)
+
+    @property
+    def cursor_hidden(self) -> bool:
+        return bool(self.screen.cursor.hidden)
+
+    @property
+    def title(self) -> str:
+        return self.screen.title or ""
+
+    @property
+    def base_reverse(self) -> bool:
+        """Screen-wide reverse baseline (DECSCNM). Highlight is measured vs this."""
+        return bool(self.screen.default_char.reverse)
+
+    # -- attributes --------------------------------------------------------
+
+    def cell(self, row: int, col: int) -> CellAttrs:
+        """Return attributes for one cell.
+
+        Safe against the sparse buffer: ``screen.buffer`` is a real ``defaultdict``
+        (indexing a missing *row* would insert it), so we only index rows within
+        range; missing *cells* fall back to the screen default char without
+        mutating anything.
+        """
+        if not (0 <= row < self.screen.lines and 0 <= col < self.screen.columns):
+            dc = self.screen.default_char
+            return CellAttrs(dc.data, dc.fg, dc.bg, dc.bold, dc.reverse)
+        ch = self.screen.buffer[row][col]  # StaticDefaultDict: missing col -> default
+        return CellAttrs(ch.data, ch.fg, ch.bg, ch.bold, ch.reverse)
+
+    def row_cells(self, row: int) -> List[CellAttrs]:
+        """Return the attribute cells for a whole row, left to right."""
+        if not (0 <= row < self.screen.lines):
+            return []
+        buf = self.screen.buffer[row]
+        out = []
+        for col in range(self.screen.columns):
+            ch = buf[col]
+            out.append(CellAttrs(ch.data, ch.fg, ch.bg, ch.bold, ch.reverse))
+        return out
+
+    # -- stability ---------------------------------------------------------
+
+    def content_hash(self) -> int:
+        """CRC32 of the plain-text display.
+
+        Excludes cursor position and all attributes, so cursor movement and
+        attribute-only churn (blink/reverse cycling) do not count as changes for
+        stability detection.
+        """
+        return zlib.crc32(self.text().encode("utf-8", "replace"))