smartcli-toolkit 0.1.4__tar.gz → 0.1.6__tar.gz

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.4
+Version: 0.1.6
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
 Author: dwgx
 License-Expression: MIT
@@ -45,6 +45,10 @@ Requires-Dist: coverage[toml]>=7.0; extra == "dev"
 Dynamic: license-file
 
 <!-- Language: English | [简体中文](docs/i18n/README.zh-Hans.md) | [繁體中文](docs/i18n/README.zh-Hant.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) -->
+<!-- mcp-name: io.github.dwgx/smartcli -->
+<!-- ^ MCP Registry PyPI ownership marker: this string must appear in the
+     published package's README (= PyPI description) and match server.json's
+     "name". Do not remove or change without updating server.json. -->
 
 # SmartCLI
 
@@ -61,6 +65,20 @@ Dynamic: license-file
 [![Skills: 3](https://img.shields.io/badge/skills-3-purple)](#features)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](#install)
 
+**Let an AI drive, perceive, and render real terminal programs.** SmartCLI reads
+the actual screen with a `pyte` cell model — not a byte pipe — so it knows which
+menu row is highlighted, presses the right keys, and waits for the screen to
+settle. Below: it drives the real **lazygit** TUI end-to-end (arrow-key
+navigation, opening a commit diff, highlighting a branch) — no script, no mock.
+
+<p align="center">
+  <img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
+</p>
+
+```bash
+pip install smartcli-toolkit
+```
+
 ## What & why
 
 SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
@@ -75,16 +93,12 @@ in place from the checkout.
 
 ## Driving a real TUI
 
-SmartCLI driving **lazygit** — a real full-screen curses app — through its
-perceive → act → confirm loop: it reads the `pyte` cell grid (which row is
-selected, the alt-screen diff), moves with arrow keys, opens a commit's diff,
-and highlights a branch. This is captured by driving the actual program in a
-Linux container, not scripted or mocked. A byte-stream matcher like pexpect
-can't perceive "which row is highlighted"; a screen model can.
-
-<p align="center">
-  <img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
-</p>
+The demo above is SmartCLI driving **lazygit** — a real full-screen curses app —
+through its perceive → act → confirm loop: it reads the `pyte` cell grid (which
+row is selected, the alt-screen diff), moves with arrow keys, opens a commit's
+diff, and highlights a branch. Captured by driving the actual program in a Linux
+container, not scripted or mocked. A byte-stream matcher like pexpect can't
+perceive "which row is highlighted"; a screen model can.
 
 > Honest scope: CI runs a Windows + Linux + macOS matrix. The POSIX pty backend
 > (spawn / read / drive / resize / zombie-free terminate) is verified on Linux
@@ -171,13 +185,17 @@ set PYTHONIOENCODING=utf-8
 Verified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,
 `pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.
 
+**Diagnostics.** `python -m smartcli_core` prints your OS, Python, terminal, PTY
+backend, and dependency versions — run it and paste the output when filing a bug
+(SmartCLI's behavior is very terminal- and platform-sensitive).
+
 ## Quickstart
 
 ### cmd-art — terminal visual effects
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 19 effects
+python -m fx list                          # list all 28 effects
 python -m fx play donut --seconds 5        # play one effect (bounded)
 python -m fx gallery                       # one frame of each effect
 python -m fx show --seq "donut:fire:3,plasma::3"
@@ -187,7 +205,7 @@ python -m fx show --seq "donut:fire:3,plasma::3"
 
 ```bash
 cd skills/tui-ui
-python -m ui widgets                       # list all 15 widgets
+python -m ui widgets                       # list all 17 widgets
 python -m ui gallery --width 100 --height 30
 python -m ui demo table --width 80 --height 12 --theme dashboard
 ```
@@ -233,9 +251,9 @@ suite, see **[`README-USAGE.md`](README-USAGE.md)**.
 ## Features
 
 **`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
-`@register` decorator + auto-discovery. **19 effects** (donut, solarsystem, fire, plasma,
+`@register` decorator + auto-discovery. **28 effects** (donut, solarsystem, fire, plasma,
 rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
-gradient_text, banner_scroll, image2ascii, typewriter) across **8 themes** (mono, fire,
+gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt) across **8 themes** (mono, fire,
 ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
 producers; `play` is bounded by default and always restores the terminal.
 
@@ -267,9 +285,9 @@ cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
 ```text
 SmartCLI/
   smartcli_core/           shared PTY + pyte engine (importable package)
-  skills/cmd-art/          fx effect package and CLI (19 effects, 8 themes)
+  skills/cmd-art/          fx effect package and CLI (28 effects, 8 themes)
   skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
-  skills/tui-ui/           terminal UI layout engine and widgets (15 widgets)
+  skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
   tools/screenshot/        pyte -> PNG smoke-test harness
   tools/agentcli/          agent-CLI control validation harness
   knowledge/               122-note knowledge graph (see knowledge/INDEX.md)

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/README.md

@@ -1,4 +1,8 @@
 <!-- Language: English | [简体中文](docs/i18n/README.zh-Hans.md) | [繁體中文](docs/i18n/README.zh-Hant.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) -->
+<!-- mcp-name: io.github.dwgx/smartcli -->
+<!-- ^ MCP Registry PyPI ownership marker: this string must appear in the
+     published package's README (= PyPI description) and match server.json's
+     "name". Do not remove or change without updating server.json. -->
 
 # SmartCLI
 
@@ -15,6 +19,20 @@
 [![Skills: 3](https://img.shields.io/badge/skills-3-purple)](#features)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](#install)
 
+**Let an AI drive, perceive, and render real terminal programs.** SmartCLI reads
+the actual screen with a `pyte` cell model — not a byte pipe — so it knows which
+menu row is highlighted, presses the right keys, and waits for the screen to
+settle. Below: it drives the real **lazygit** TUI end-to-end (arrow-key
+navigation, opening a commit diff, highlighting a branch) — no script, no mock.
+
+<p align="center">
+  <img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
+</p>
+
+```bash
+pip install smartcli-toolkit
+```
+
 ## What & why
 
 SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
@@ -29,16 +47,12 @@ in place from the checkout.
 
 ## Driving a real TUI
 
-SmartCLI driving **lazygit** — a real full-screen curses app — through its
-perceive → act → confirm loop: it reads the `pyte` cell grid (which row is
-selected, the alt-screen diff), moves with arrow keys, opens a commit's diff,
-and highlights a branch. This is captured by driving the actual program in a
-Linux container, not scripted or mocked. A byte-stream matcher like pexpect
-can't perceive "which row is highlighted"; a screen model can.
-
-<p align="center">
-  <img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
-</p>
+The demo above is SmartCLI driving **lazygit** — a real full-screen curses app —
+through its perceive → act → confirm loop: it reads the `pyte` cell grid (which
+row is selected, the alt-screen diff), moves with arrow keys, opens a commit's
+diff, and highlights a branch. Captured by driving the actual program in a Linux
+container, not scripted or mocked. A byte-stream matcher like pexpect can't
+perceive "which row is highlighted"; a screen model can.
 
 > Honest scope: CI runs a Windows + Linux + macOS matrix. The POSIX pty backend
 > (spawn / read / drive / resize / zombie-free terminate) is verified on Linux
@@ -125,13 +139,17 @@ set PYTHONIOENCODING=utf-8
 Verified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,
 `pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.
 
+**Diagnostics.** `python -m smartcli_core` prints your OS, Python, terminal, PTY
+backend, and dependency versions — run it and paste the output when filing a bug
+(SmartCLI's behavior is very terminal- and platform-sensitive).
+
 ## Quickstart
 
 ### cmd-art — terminal visual effects
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 19 effects
+python -m fx list                          # list all 28 effects
 python -m fx play donut --seconds 5        # play one effect (bounded)
 python -m fx gallery                       # one frame of each effect
 python -m fx show --seq "donut:fire:3,plasma::3"
@@ -141,7 +159,7 @@ python -m fx show --seq "donut:fire:3,plasma::3"
 
 ```bash
 cd skills/tui-ui
-python -m ui widgets                       # list all 15 widgets
+python -m ui widgets                       # list all 17 widgets
 python -m ui gallery --width 100 --height 30
 python -m ui demo table --width 80 --height 12 --theme dashboard
 ```
@@ -187,9 +205,9 @@ suite, see **[`README-USAGE.md`](README-USAGE.md)**.
 ## Features
 
 **`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
-`@register` decorator + auto-discovery. **19 effects** (donut, solarsystem, fire, plasma,
+`@register` decorator + auto-discovery. **28 effects** (donut, solarsystem, fire, plasma,
 rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
-gradient_text, banner_scroll, image2ascii, typewriter) across **8 themes** (mono, fire,
+gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt) across **8 themes** (mono, fire,
 ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
 producers; `play` is bounded by default and always restores the terminal.
 
@@ -221,9 +239,9 @@ cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
 ```text
 SmartCLI/
   smartcli_core/           shared PTY + pyte engine (importable package)
-  skills/cmd-art/          fx effect package and CLI (19 effects, 8 themes)
+  skills/cmd-art/          fx effect package and CLI (28 effects, 8 themes)
   skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
-  skills/tui-ui/           terminal UI layout engine and widgets (15 widgets)
+  skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
   tools/screenshot/        pyte -> PNG smoke-test harness
   tools/agentcli/          agent-CLI control validation harness
   knowledge/               122-note knowledge graph (see knowledge/INDEX.md)

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/pyproject.toml

@@ -30,7 +30,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartcli-toolkit"
-version = "0.1.4"
+version = "0.1.6"
 description = "Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core)."
 readme = "README.md"
 license = "MIT"

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/smartcli_core/__init__.py

@@ -55,4 +55,4 @@ __all__ = [
     "KEY_MAP",
 ]
 
-__version__ = "0.1.4"
+__version__ = "0.1.6"

smartcli_toolkit-0.1.6/smartcli_core/__main__.py

@@ -0,0 +1,122 @@
+"""python -m smartcli_core — environment diagnostics.
+
+Prints the OS, Python, terminal, and dependency facts that most affect how
+SmartCLI behaves, so a bug report can start from ground truth instead of a
+round-trip of "which OS? which terminal? is pywinpty installed?". Inspired by
+`textual diagnose`, which its maintainers called the single most valuable thing
+for cutting issue back-and-forth on a cross-platform, terminal-sensitive tool.
+
+Pure/read-only: it imports nothing that spawns a process and never opens a PTY.
+Run it and paste the output into an issue.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import sys
+
+
+def _ver(mod_name: str, dist_name: str | None = None) -> str:
+    """Best-effort version string for an optional dependency, or a clear absent
+    marker. Tries the module's __version__, then importlib.metadata."""
+    import importlib
+    import importlib.metadata as md
+    import importlib.util
+
+    if importlib.util.find_spec(mod_name) is None:
+        return "not installed"
+    try:
+        mod = importlib.import_module(mod_name)
+        v = getattr(mod, "__version__", None)
+        if v:
+            return str(v)
+    except Exception:
+        pass
+    try:
+        return md.version(dist_name or mod_name)
+    except Exception:
+        return "installed (version unknown)"
+
+
+def _section(title: str, rows: list[tuple[str, str]]) -> None:
+    print(f"\n{title}")
+    print("-" * len(title))
+    width = max((len(k) for k, _ in rows), default=0)
+    for k, v in rows:
+        print(f"  {k:<{width}}  {v}")
+
+
+def main() -> int:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+    try:
+        from . import __version__ as core_version
+    except Exception:
+        core_version = "?"
+
+    print("=" * 60)
+    print("SmartCLI diagnostics")
+    print("=" * 60)
+
+    _section("SmartCLI", [
+        ("smartcli_core", core_version),
+        ("import path", os.path.dirname(os.path.abspath(__file__))),
+    ])
+
+    _section("Python & OS", [
+        ("python", sys.version.split()[0]),
+        ("implementation", platform.python_implementation()),
+        ("executable", sys.executable),
+        ("platform", platform.platform()),
+        ("machine", platform.machine()),
+    ])
+
+    # Terminal facts that change SmartCLI's behavior (isatty gates keyboard
+    # input; TERM/COLORTERM affect what programs emit; on Windows the PTY path
+    # is ConPTY via pywinpty).
+    is_win = sys.platform == "win32"
+    _section("Terminal", [
+        ("stdout.isatty()", str(sys.stdout.isatty())),
+        ("stdin.isatty()", str(sys.stdin.isatty())),
+        ("TERM", os.environ.get("TERM", "(unset)")),
+        ("COLORTERM", os.environ.get("COLORTERM", "(unset)")),
+        ("PYTHONIOENCODING", os.environ.get("PYTHONIOENCODING", "(unset)")),
+        ("stdout.encoding", getattr(sys.stdout, "encoding", "?") or "?"),
+    ])
+
+    _section("PTY backend & deps", [
+        ("default backend", "ConPTY (pywinpty)" if is_win else "POSIX pty (stdlib)"),
+        ("pyte", _ver("pyte")),
+        ("pywinpty", _ver("winpty", "pywinpty") if is_win else "n/a (POSIX)"),
+    ])
+
+    _section("Optional extras", [
+        ("pyfiglet", _ver("pyfiglet")),
+        ("Pillow (PIL)", _ver("PIL", "Pillow")),
+        ("wcwidth", _ver("wcwidth")),
+    ])
+
+    # Notes that commonly explain reports.
+    notes = []
+    if is_win and (os.environ.get("PYTHONIOENCODING", "").lower() not in ("utf-8", "utf8")):
+        notes.append("Windows without PYTHONIOENCODING=utf-8 — box/CJK glyphs may "
+                     "crash on a legacy codepage. Set it before running.")
+    if _ver("pyte") == "not installed":
+        notes.append("pyte is REQUIRED and missing — `pip install smartcli-toolkit`.")
+    if is_win and _ver("winpty", "pywinpty") == "not installed":
+        notes.append("pywinpty missing on Windows — the ConPTY backend can't run.")
+    if notes:
+        print("\nNotes")
+        print("-----")
+        for n in notes:
+            print(f"  ! {n}")
+
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/smartcli_core/screen_model.py

@@ -74,6 +74,32 @@ class ScreenModel:
         # feed raise) is not silently indistinguishable from the occasional
         # garbled byte run it is meant to tolerate.
         self.feed_errors = 0
+        # Device-query replies (DSR-CPR "ESC[6n", DA "ESC[c") that pyte generates
+        # while parsing. pyte routes them to Screen.write_process_input, which is a
+        # no-op by default — so a program that SYNCHRONOUSLY waits for a cursor-
+        # position report can stall/degrade because nothing answers. We capture
+        # them here (pyte builds the correct reply from its own cursor/attrs) and
+        # PtySession.pump() writes them back to the PTY. See drain_replies().
+        self._reply_buf = bytearray()
+        self.screen.write_process_input = self._collect_reply  # type: ignore[method-assign]
+
+    def _collect_reply(self, data) -> None:
+        """pyte hands us the bytes/str it wants sent back to the process."""
+        if isinstance(data, str):
+            data = data.encode("utf-8", "replace")
+        self._reply_buf.extend(data)
+
+    def drain_replies(self) -> bytes:
+        """Return and clear any pending device-query replies pyte generated.
+
+        PtySession.pump() calls this after feed() and writes the result back to
+        the PTY, so DSR-CPR / DA queries from the driven program get answered.
+        """
+        if not self._reply_buf:
+            return b""
+        out = bytes(self._reply_buf)
+        self._reply_buf.clear()
+        return out
 
     # -- feeding -----------------------------------------------------------
 

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/smartcli_core/session.py

@@ -20,6 +20,7 @@ Key tokens (``send_keys``) are mapped to escape bytes via :data:`KEY_MAP`.
 
 from __future__ import annotations
 
+import time
 from typing import List, Optional, Tuple, Union, Sequence
 
 from .pty_backend import PtyBackend, get_default_backend
@@ -177,10 +178,24 @@ class PtySession:
     # -- io ----------------------------------------------------------------
 
     def pump(self) -> bytes:
-        """Read whatever is available and feed it into the screen. Returns bytes."""
+        """Read whatever is available and feed it into the screen. Returns bytes.
+
+        After feeding, answer any device-status/attribute queries the program
+        emitted (DSR-CPR ``ESC[6n``, DA ``ESC[c``): pyte builds the correct reply
+        from its own cursor/attr state, and we write it back to the PTY. Without
+        this, a program that synchronously waits for a cursor-position report can
+        stall or fall back to a degraded mode. Best-effort: a write failure here
+        must never break perception.
+        """
         data = self.backend.read_nonblocking()
         if data:
             self.model.feed(data)
+            reply = self.model.drain_replies()
+            if reply:
+                try:
+                    self.backend.write(reply)
+                except Exception:
+                    pass
         return data
 
     def send_text(self, text: str) -> None:
@@ -281,3 +296,38 @@ class PtySession:
             flags=flags,
         )
         return matched, snap  # type: ignore[return-value]
+
+    def wait_change(
+        self,
+        baseline_hash: Optional[str] = None,
+        timeout_ms: int = 10000,
+        poll_ms: int = 30,
+    ) -> Tuple[bool, Snapshot]:
+        """Wait until the screen content changes away from ``baseline_hash``.
+
+        The precise "did my action land?" primitive: after sending input, block
+        until the screen's content hash differs from the baseline (by default,
+        the hash at the moment of the call). Returns (changed, snapshot) —
+        ``changed`` is False on timeout, and the snapshot is always the latest
+        screen so the caller can inspect it either way. Complements wait_stable
+        (settle) / wait_for (a specific marker): this catches ANY change, which
+        is what you want right after acting, and it can't false-positive on a
+        screen that was already showing the target text.
+
+        This is a thin session-level poll over the existing pump + content_hash;
+        it adds no new core state.
+        """
+        if baseline_hash is None:
+            # Baseline = the screen as it stands NOW, WITHOUT draining pending
+            # bytes first — otherwise the very output we're waiting for could be
+            # folded into the baseline and never register as a change.
+            baseline_hash = self.model.content_hash()
+        deadline = time.monotonic() + timeout_ms / 1000.0
+        poll_s = max(0.0, poll_ms / 1000.0)
+        while True:
+            self.pump()
+            if self.model.content_hash() != baseline_hash:
+                return True, self.snapshot()
+            if time.monotonic() >= deadline:
+                return False, self.snapshot()
+            time.sleep(poll_s)

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/smartcli_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.4
+Version: 0.1.6
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
 Author: dwgx
 License-Expression: MIT
@@ -45,6 +45,10 @@ Requires-Dist: coverage[toml]>=7.0; extra == "dev"
 Dynamic: license-file
 
 <!-- Language: English | [简体中文](docs/i18n/README.zh-Hans.md) | [繁體中文](docs/i18n/README.zh-Hant.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) -->
+<!-- mcp-name: io.github.dwgx/smartcli -->
+<!-- ^ MCP Registry PyPI ownership marker: this string must appear in the
+     published package's README (= PyPI description) and match server.json's
+     "name". Do not remove or change without updating server.json. -->
 
 # SmartCLI
 
@@ -61,6 +65,20 @@ Dynamic: license-file
 [![Skills: 3](https://img.shields.io/badge/skills-3-purple)](#features)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)](#install)
 
+**Let an AI drive, perceive, and render real terminal programs.** SmartCLI reads
+the actual screen with a `pyte` cell model — not a byte pipe — so it knows which
+menu row is highlighted, presses the right keys, and waits for the screen to
+settle. Below: it drives the real **lazygit** TUI end-to-end (arrow-key
+navigation, opening a commit diff, highlighting a branch) — no script, no mock.
+
+<p align="center">
+  <img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
+</p>
+
+```bash
+pip install smartcli-toolkit
+```
+
 ## What & why
 
 SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
@@ -75,16 +93,12 @@ in place from the checkout.
 
 ## Driving a real TUI
 
-SmartCLI driving **lazygit** — a real full-screen curses app — through its
-perceive → act → confirm loop: it reads the `pyte` cell grid (which row is
-selected, the alt-screen diff), moves with arrow keys, opens a commit's diff,
-and highlights a branch. This is captured by driving the actual program in a
-Linux container, not scripted or mocked. A byte-stream matcher like pexpect
-can't perceive "which row is highlighted"; a screen model can.
-
-<p align="center">
-  <img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
-</p>
+The demo above is SmartCLI driving **lazygit** — a real full-screen curses app —
+through its perceive → act → confirm loop: it reads the `pyte` cell grid (which
+row is selected, the alt-screen diff), moves with arrow keys, opens a commit's
+diff, and highlights a branch. Captured by driving the actual program in a Linux
+container, not scripted or mocked. A byte-stream matcher like pexpect can't
+perceive "which row is highlighted"; a screen model can.
 
 > Honest scope: CI runs a Windows + Linux + macOS matrix. The POSIX pty backend
 > (spawn / read / drive / resize / zombie-free terminate) is verified on Linux
@@ -171,13 +185,17 @@ set PYTHONIOENCODING=utf-8
 Verified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,
 `pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.
 
+**Diagnostics.** `python -m smartcli_core` prints your OS, Python, terminal, PTY
+backend, and dependency versions — run it and paste the output when filing a bug
+(SmartCLI's behavior is very terminal- and platform-sensitive).
+
 ## Quickstart
 
 ### cmd-art — terminal visual effects
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 19 effects
+python -m fx list                          # list all 28 effects
 python -m fx play donut --seconds 5        # play one effect (bounded)
 python -m fx gallery                       # one frame of each effect
 python -m fx show --seq "donut:fire:3,plasma::3"
@@ -187,7 +205,7 @@ python -m fx show --seq "donut:fire:3,plasma::3"
 
 ```bash
 cd skills/tui-ui
-python -m ui widgets                       # list all 15 widgets
+python -m ui widgets                       # list all 17 widgets
 python -m ui gallery --width 100 --height 30
 python -m ui demo table --width 80 --height 12 --theme dashboard
 ```
@@ -233,9 +251,9 @@ suite, see **[`README-USAGE.md`](README-USAGE.md)**.
 ## Features
 
 **`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
-`@register` decorator + auto-discovery. **19 effects** (donut, solarsystem, fire, plasma,
+`@register` decorator + auto-discovery. **28 effects** (donut, solarsystem, fire, plasma,
 rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
-gradient_text, banner_scroll, image2ascii, typewriter) across **8 themes** (mono, fire,
+gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt) across **8 themes** (mono, fire,
 ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
 producers; `play` is bounded by default and always restores the terminal.
 
@@ -267,9 +285,9 @@ cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
 ```text
 SmartCLI/
   smartcli_core/           shared PTY + pyte engine (importable package)
-  skills/cmd-art/          fx effect package and CLI (19 effects, 8 themes)
+  skills/cmd-art/          fx effect package and CLI (28 effects, 8 themes)
   skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
-  skills/tui-ui/           terminal UI layout engine and widgets (15 widgets)
+  skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
   tools/screenshot/        pyte -> PNG smoke-test harness
   tools/agentcli/          agent-CLI control validation harness
   knowledge/               122-note knowledge graph (see knowledge/INDEX.md)

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/smartcli_toolkit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 smartcli_core/__init__.py
+smartcli_core/__main__.py
 smartcli_core/pty_backend.py
 smartcli_core/py.typed
 smartcli_core/readiness.py
@@ -13,9 +14,12 @@ smartcli_toolkit.egg-info/SOURCES.txt
 smartcli_toolkit.egg-info/dependency_links.txt
 smartcli_toolkit.egg-info/requires.txt
 smartcli_toolkit.egg-info/top_level.txt
+tests/test_char_width.py
+tests/test_cpr_reply.py
 tests/test_degenerate_inputs.py
 tests/test_doc_counts.py
 tests/test_fx_contract.py
 tests/test_golden_frames.py
 tests/test_readiness.py
-tests/test_vendor_sync.py
+tests/test_vendor_sync.py
+tests/test_wait_change.py

smartcli_toolkit-0.1.6/tests/test_char_width.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""test_char_width.py — width function: default stability + the new knobs.
+
+Character cell width is a coordination problem (terminals ship different Unicode
+DBs). ui.core.width/char_width gained two optional knobs — unicode_version and
+ambiguous_wide — so a caller can pin the answer to its terminal. This locks:
+  * defaults are byte-identical to the old behavior (so golden/fx baselines
+    don't move),
+  * ambiguous_wide flips East-Asian Ambiguous glyphs 1<->2 without touching
+    unambiguous ones,
+  * CJK / emoji / ZWJ / combining widths are unaffected by the knob,
+  * pinning unicode_version doesn't crash.
+
+Pure/in-memory: imports the ui package, computes widths. No process, no PTY.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "skills" / "tui-ui"))
+
+from ui.core import char_width, width  # noqa: E402
+
+failures = 0
+
+
+def check(cond: bool, label: str, detail: str = "") -> None:
+    global failures
+    if not cond:
+        failures += 1
+    print(f"{'PASS' if cond else 'FAIL'}  {label}" + (f"  -- {detail}" if detail else ""))
+
+
+# East-Asian Ambiguous sample chars (unicodedata.east_asian_width == 'A').
+AMBIGUOUS = ["§", "±", "…", "○", "×"]
+# Unambiguous references that must never change with the knob.
+CJK = "你好"          # each 2 cells
+ASCII = "hello"       # each 1 cell
+EMOJI = "😀"          # 2 cells
+ZWJ = "‍"        # 0 cells
+
+
+def test_defaults_unchanged() -> None:
+    # Default: ambiguous is narrow (1), matching the pre-change behavior.
+    for c in AMBIGUOUS:
+        check(char_width(c) == 1, f"default: ambiguous U+{ord(c):04X} is 1 cell",
+              detail=str(char_width(c)))
+    check(width(ASCII) == 5, "default: 'hello' is 5", detail=str(width(ASCII)))
+    check(width(CJK) == 4, "default: 2 CJK chars are 4", detail=str(width(CJK)))
+    check(char_width(EMOJI) == 2, "default: emoji is 2")
+    check(char_width(ZWJ) == 0, "default: ZWJ is 0")
+
+
+def test_ambiguous_wide_knob() -> None:
+    # With the CJK-locale knob, ambiguous glyphs count as 2.
+    for c in AMBIGUOUS:
+        check(char_width(c, ambiguous_wide=True) == 2,
+              f"ambiguous_wide: U+{ord(c):04X} is 2 cells",
+              detail=str(char_width(c, ambiguous_wide=True)))
+    # A whole string of ambiguous chars scales.
+    s = "".join(AMBIGUOUS)
+    check(width(s, ambiguous_wide=True) == 2 * len(AMBIGUOUS),
+          "ambiguous_wide: string doubles", detail=str(width(s, ambiguous_wide=True)))
+
+
+def test_knob_leaves_unambiguous_alone() -> None:
+    # The knob must ONLY affect ambiguous chars — CJK/ASCII/emoji/ZWJ unchanged.
+    check(width(ASCII, ambiguous_wide=True) == 5, "knob: ASCII still 5")
+    check(width(CJK, ambiguous_wide=True) == 4, "knob: CJK still 4")
+    check(char_width(EMOJI, ambiguous_wide=True) == 2, "knob: emoji still 2")
+    check(char_width(ZWJ, ambiguous_wide=True) == 0, "knob: ZWJ still 0")
+
+
+def test_unicode_version_pin() -> None:
+    # Pinning a version must not crash and must return a sane width for ASCII.
+    try:
+        w = width("hello", unicode_version="9.0.0")
+        check(w == 5, "unicode_version='9.0.0' gives 'hello'==5", detail=str(w))
+    except Exception as exc:
+        check(False, "unicode_version pin did not crash", detail=repr(exc))
+
+
+def main() -> int:
+    test_defaults_unchanged()
+    test_ambiguous_wide_knob()
+    test_knob_leaves_unambiguous_alone()
+    test_unicode_version_pin()
+    print()
+    if failures:
+        print(f"{failures} FAILURE(S)")
+        return 1
+    print("ALL PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

smartcli_toolkit-0.1.6/tests/test_cpr_reply.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""test_cpr_reply.py — device-query auto-answer regression (DSR-CPR / DA).
+
+A program that emits a cursor-position query (``ESC[6n``) or a device-attributes
+query (``ESC[c``) and then SYNCHRONOUSLY waits for the reply will stall or fall
+back to a degraded mode if nothing answers. pyte generates the correct reply
+(from its own cursor/attr state) and routes it to Screen.write_process_input;
+SmartCLI now captures that and PtySession.pump() writes it back to the PTY.
+
+This locks that wiring. Pure/in-memory: a fake backend feeds the query bytes and
+captures what gets written back — no PTY, no process. Mutation check: if pump()
+stops writing the reply (or ScreenModel stops capturing it), the writes-back
+assertions fail.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from smartcli_core import PtySession, ScreenModel  # noqa: E402
+from smartcli_core.pty_backend import PtyBackend  # noqa: E402
+
+failures = 0
+
+
+def check(cond: bool, label: str, detail: str = "") -> None:
+    global failures
+    if not cond:
+        failures += 1
+    print(f"{'PASS' if cond else 'FAIL'}  {label}" + (f"  -- {detail}" if detail else ""))
+
+
+class FakeBackend(PtyBackend):
+    """A minimal backend: hands out queued bytes on read, captures writes."""
+
+    def __init__(self) -> None:
+        self._to_read: list[bytes] = []
+        self.written = bytearray()
+        self._alive = True
+
+    def queue(self, data: bytes) -> None:
+        self._to_read.append(data)
+
+    # PtyBackend interface --------------------------------------------------
+    def spawn(self, cmd, cols, rows) -> None:  # noqa: D401
+        pass
+
+    def read_nonblocking(self, timeout: float = 0.0) -> bytes:
+        return self._to_read.pop(0) if self._to_read else b""
+
+    def write(self, data: bytes) -> None:
+        self.written.extend(data)
+
+    def resize(self, cols: int, rows: int) -> None:
+        pass
+
+    def is_alive(self) -> bool:
+        return self._alive
+
+    def terminate(self) -> None:
+        self._alive = False
+
+
+def test_screenmodel_captures_replies() -> None:
+    m = ScreenModel(80, 24)
+    # Move cursor to row 3, col 5 (1-based), then ask for a cursor-position report.
+    m.feed(b"\x1b[3;5H\x1b[6n")
+    reply = m.drain_replies()
+    check(reply == b"\x1b[3;5R", "ScreenModel answers DSR-CPR from its cursor",
+          detail=repr(reply))
+    # drain is one-shot.
+    check(m.drain_replies() == b"", "drain_replies clears after read")
+    # Device-attributes query.
+    m.feed(b"\x1b[c")
+    check(m.drain_replies() == b"\x1b[?6c", "ScreenModel answers DA1")
+
+
+def test_pump_writes_reply_back() -> None:
+    be = FakeBackend()
+    sess = PtySession(cols=80, rows=24, backend=be)
+    # Program positions the cursor and queries it, all in one read.
+    be.queue(b"hello\x1b[2;3H\x1b[6n")
+    data = sess.pump()
+    check(b"hello" in data, "pump returns the screen bytes it read")
+    check(be.written == b"\x1b[2;3R", "pump wrote the CPR reply back to the PTY",
+          detail=repr(bytes(be.written)))
+
+
+def test_no_query_no_write() -> None:
+    be = FakeBackend()
+    sess = PtySession(cols=80, rows=24, backend=be)
+    be.queue(b"just some text, no queries")
+    sess.pump()
+    check(be.written == b"", "no device query -> nothing written back",
+          detail=repr(bytes(be.written)))
+
+
+def test_reply_survives_resize() -> None:
+    # pyte.Screen.resize is in-place (doesn't rebuild the screen or reset
+    # write_process_input), so the reply binding must survive a resize.
+    m = ScreenModel(80, 24)
+    m.resize(100, 30)
+    m.feed(b"\x1b[2;2H\x1b[6n")
+    check(m.drain_replies() == b"\x1b[2;2R", "CPR still answered after resize")
+
+
+def test_no_feedback_loop() -> None:
+    # Our own replies, fed back in (as an echoing PTY might), must NOT generate a
+    # second reply — otherwise a CPR/DA answer could amplify into a loop. The
+    # reply terminators (R / ?..c / ..n status) are not queries.
+    m = ScreenModel(80, 24)
+    m.feed(b"\x1b[3;5R")   # a CPR reply
+    m.feed(b"\x1b[?6c")    # a DA reply
+    m.feed(b"\x1b[0n")     # a DSR status reply
+    check(m.drain_replies() == b"", "replies fed back produce no second reply")
+
+
+def main() -> int:
+    test_screenmodel_captures_replies()
+    test_pump_writes_reply_back()
+    test_no_query_no_write()
+    test_reply_survives_resize()
+    test_no_feedback_loop()
+    print()
+    if failures:
+        print(f"{failures} FAILURE(S)")
+        return 1
+    print("ALL PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{smartcli_toolkit-0.1.4 → smartcli_toolkit-0.1.6}/tests/test_golden_frames.py

@@ -49,6 +49,20 @@ WIDTH, HEIGHT = 60, 12
 THEME = "dashboard"
 
 results: list[tuple[str, bool, str]] = []
+skipped: list[str] = []
+
+# Widgets whose rendered frame depends on an OPTIONAL dependency: their output
+# differs between "dep present" (real render) and "dep absent" (graceful stdlib
+# fallback), so a single baseline can't cover both. When the dep is missing we
+# SKIP the widget rather than fail — the baseline is only meaningful when the dep
+# matches the environment that generated it. (banner -> pyfiglet FIGlet fonts;
+# the baseline is the pyfiglet render. CI installs .[all] so it's exercised.)
+OPTIONAL_DEP = {"banner": "pyfiglet"}
+
+
+def _dep_available(mod: str) -> bool:
+    import importlib.util
+    return importlib.util.find_spec(mod) is not None
 
 
 def record(name: str, ok: bool, detail: str = "") -> None:
@@ -56,6 +70,11 @@ def record(name: str, ok: bool, detail: str = "") -> None:
     print(f"{'PASS' if ok else 'FAIL'}  {name}" + (f"  -- {detail}" if detail else ""))
 
 
+def note_skip(name: str, detail: str) -> None:
+    skipped.append(name)
+    print(f"SKIP  {name}  -- {detail}")
+
+
 def render_widget(cls) -> str:
     """Render ONE widget to a deterministic ANSI frame — mirrors ui.cli.cmd_demo:
     sample(theme) -> Box -> Page.to_ansi()."""
@@ -92,6 +111,14 @@ def _first_diff(a: str, b: str) -> str:
 
 def check_widget(cls, update: bool) -> None:
     key = cls.key
+    # If this widget's render depends on an optional dep that's absent, its
+    # fallback output won't match the baseline (generated with the dep present).
+    # Skip rather than fail — a missing optional dep is not a regression.
+    dep = OPTIONAL_DEP.get(key)
+    if dep and not _dep_available(dep) and not update:
+        note_skip(f"golden {key}", f"optional dep '{dep}' absent — baseline needs it")
+        return
+
     # Determinism gate: render twice, must be byte-identical. A widget that
     # depends on time/random would trip here instead of baking flakiness in.
     frame1 = render_widget(cls)
@@ -147,9 +174,10 @@ def main(argv: list[str]) -> int:
         check_widget(cls, update)
 
     failed = [r for r in results if not r[1]]
+    skip_note = f", {len(skipped)} skipped (optional dep absent)" if skipped else ""
     print(f"\n{len(results) - len(failed)}/{len(results)} widgets "
           f"{'baselined' if update else 'match golden frames'} "
-          f"(size {WIDTH}x{HEIGHT}, theme {THEME})")
+          f"(size {WIDTH}x{HEIGHT}, theme {THEME}){skip_note}")
     if failed and not update:
         print("golden-frame drift — review, then `--update` if intended:")
         for name, _ok, detail in failed:

smartcli_toolkit-0.1.6/tests/test_wait_change.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""test_wait_change.py — PtySession.wait_change regression (deterministic).
+
+wait_change is the precise "did my action land?" primitive: block until the
+screen content hash changes away from a baseline. This locks:
+  * baseline is the screen NOW, without draining pending bytes first (so the
+    awaited output can't be folded into the baseline and missed),
+  * a real content change returns (True, snapshot),
+  * no change within the window returns (False, latest snapshot),
+  * an explicit baseline_hash lets a caller wait for change from a known state.
+
+Pure/in-memory: a fake backend feeds bytes on demand. No PTY, no process.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from smartcli_core import PtySession  # noqa: E402
+from smartcli_core.pty_backend import PtyBackend  # noqa: E402
+
+failures = 0
+
+
+def check(cond, label, detail=""):
+    global failures
+    if not cond:
+        failures += 1
+    print(f"{'PASS' if cond else 'FAIL'}  {label}" + (f"  -- {detail}" if detail else ""))
+
+
+class FakeBackend(PtyBackend):
+    def __init__(self):
+        self._q = []
+        self._alive = True
+
+    def queue(self, data):
+        self._q.append(data)
+
+    def spawn(self, cmd, cols, rows):
+        pass
+
+    def read_nonblocking(self, timeout=0.0):
+        return self._q.pop(0) if self._q else b""
+
+    def write(self, data):
+        pass
+
+    def resize(self, cols, rows):
+        pass
+
+    def is_alive(self):
+        return self._alive
+
+    def terminate(self):
+        self._alive = False
+
+
+def test_change_detected():
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b"hello world")
+    changed, snap = sess.wait_change(timeout_ms=2000)
+    check(changed is True, "content change is detected")
+    check("hello" in snap.to_text(), "returned snapshot shows the new content")
+
+
+def test_no_change_times_out():
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    changed, snap = sess.wait_change(timeout_ms=250)
+    check(changed is False, "no change within the window -> False (timeout)")
+    check(snap is not None, "timeout still returns the latest snapshot")
+
+
+def test_baseline_not_polluted():
+    # The bug this guards: if wait_change drained pending bytes to form the
+    # baseline, the awaited output would be in the baseline and never seen.
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b"the output I am waiting for")   # already queued before the call
+    changed, _ = sess.wait_change(timeout_ms=2000)
+    check(changed is True, "pending bytes at call time still count as a change")
+
+
+def test_explicit_baseline():
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b"first")
+    sess.wait_change(timeout_ms=2000)          # consume 'first'
+    h = sess.model.content_hash()
+    be.queue(b"\x1b[2J\x1b[Hsecond")           # clear + new
+    changed, snap = sess.wait_change(baseline_hash=h, timeout_ms=2000)
+    check(changed is True, "explicit baseline_hash detects change from a known state")
+    check("second" in snap.to_text(), "snapshot reflects the change")
+
+
+def main():
+    test_change_detected()
+    test_no_change_times_out()
+    test_baseline_not_polluted()
+    test_explicit_baseline()
+    print()
+    if failures:
+        print(f"{failures} FAILURE(S)")
+        return 1
+    print("ALL PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())