smartcli-toolkit 0.1.3__tar.gz → 0.1.5__tar.gz

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.3
+Version: 0.1.5
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
 Author: dwgx
 License-Expression: MIT
@@ -38,9 +38,17 @@ Provides-Extra: all
 Requires-Dist: pyfiglet>=1.0.0; extra == "all"
 Requires-Dist: Pillow>=10.0.0; extra == "all"
 Requires-Dist: wcwidth>=0.2.0; extra == "all"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+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
 
@@ -51,11 +59,26 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/smartcli-toolkit?color=orange)](https://pypi.org/project/smartcli-toolkit/)
 [![Python](https://img.shields.io/pypi/pyversions/smartcli-toolkit?color=blue)](https://pypi.org/project/smartcli-toolkit/)
 [![CI](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml/badge.svg)](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dwgx/SmartCLI/branch/main/graph/badge.svg)](https://codecov.io/gh/dwgx/SmartCLI)
 [![License: MIT](https://img.shields.io/pypi/l/smartcli-toolkit?color=green)](LICENSE)
 [![Downloads](https://img.shields.io/pypi/dm/smartcli-toolkit?color=blueviolet)](https://pypi.org/project/smartcli-toolkit/)
 [![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**
@@ -70,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
@@ -166,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 22 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"
@@ -199,6 +222,14 @@ python skills/drive-tui/scripts/tui.py snapshot --id <SID>
 python skills/drive-tui/scripts/tui.py close --id <SID>
 ```
 
+Or drive from any MCP client — the same verbs as MCP tools, with the
+per-session token attached automatically:
+
+```bash
+pip install "smartcli-toolkit[mcp]"
+python skills/drive-tui/scripts/mcp_server.py     # stdio MCP server
+```
+
 ### As a library
 
 The shared core is importable directly:
@@ -220,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. **22 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) 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.
 
@@ -254,7 +285,7 @@ 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 (22 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)
   tools/screenshot/        pyte -> PNG smoke-test harness

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/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
 
@@ -9,11 +13,26 @@
 [![PyPI](https://img.shields.io/pypi/v/smartcli-toolkit?color=orange)](https://pypi.org/project/smartcli-toolkit/)
 [![Python](https://img.shields.io/pypi/pyversions/smartcli-toolkit?color=blue)](https://pypi.org/project/smartcli-toolkit/)
 [![CI](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml/badge.svg)](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dwgx/SmartCLI/branch/main/graph/badge.svg)](https://codecov.io/gh/dwgx/SmartCLI)
 [![License: MIT](https://img.shields.io/pypi/l/smartcli-toolkit?color=green)](LICENSE)
 [![Downloads](https://img.shields.io/pypi/dm/smartcli-toolkit?color=blueviolet)](https://pypi.org/project/smartcli-toolkit/)
 [![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**
@@ -28,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
@@ -124,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 22 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"
@@ -157,6 +176,14 @@ python skills/drive-tui/scripts/tui.py snapshot --id <SID>
 python skills/drive-tui/scripts/tui.py close --id <SID>
 ```
 
+Or drive from any MCP client — the same verbs as MCP tools, with the
+per-session token attached automatically:
+
+```bash
+pip install "smartcli-toolkit[mcp]"
+python skills/drive-tui/scripts/mcp_server.py     # stdio MCP server
+```
+
 ### As a library
 
 The shared core is importable directly:
@@ -178,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. **22 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) 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.
 
@@ -212,7 +239,7 @@ 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 (22 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)
   tools/screenshot/        pyte -> PNG smoke-test harness

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/pyproject.toml

@@ -30,7 +30,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartcli-toolkit"
-version = "0.1.3"
+version = "0.1.5"
 description = "Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core)."
 readme = "README.md"
 license = "MIT"
@@ -96,6 +96,13 @@ art = ["pyfiglet>=1.0.0"]        # real FIGlet fonts (else built-in block font)
 image = ["Pillow>=10.0.0"]       # real raster images (else PNM/procedural demo)
 width = ["wcwidth>=0.2.0"]       # authoritative cell width (else unicodedata)
 all = ["pyfiglet>=1.0.0", "Pillow>=10.0.0", "wcwidth>=0.2.0"]
+# MCP server over the drive-tui daemon verb surface (skills/drive-tui/scripts/
+# mcp_server.py). Lets any MCP client drive interactive TUIs. Optional — the
+# CLI and library work without it.
+mcp = ["mcp>=1.0"]
+# Dev-only: multi-process coverage over the script-style suite (see
+# tools/coverage_run.py + .coveragerc). Not needed to run SmartCLI.
+dev = ["coverage[toml]>=7.0"]
 
 [tool.setuptools]
 # Only the shared core is a clean installable package (see HONEST NOTE above).

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/smartcli_core/__init__.py

@@ -55,4 +55,4 @@ __all__ = [
     "KEY_MAP",
 ]
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"

smartcli_toolkit-0.1.5/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.3 → smartcli_toolkit-0.1.5}/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.3 → smartcli_toolkit-0.1.5}/smartcli_core/session.py

@@ -177,10 +177,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:

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/smartcli_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.3
+Version: 0.1.5
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
 Author: dwgx
 License-Expression: MIT
@@ -38,9 +38,17 @@ Provides-Extra: all
 Requires-Dist: pyfiglet>=1.0.0; extra == "all"
 Requires-Dist: Pillow>=10.0.0; extra == "all"
 Requires-Dist: wcwidth>=0.2.0; extra == "all"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+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
 
@@ -51,11 +59,26 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/smartcli-toolkit?color=orange)](https://pypi.org/project/smartcli-toolkit/)
 [![Python](https://img.shields.io/pypi/pyversions/smartcli-toolkit?color=blue)](https://pypi.org/project/smartcli-toolkit/)
 [![CI](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml/badge.svg)](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/dwgx/SmartCLI/branch/main/graph/badge.svg)](https://codecov.io/gh/dwgx/SmartCLI)
 [![License: MIT](https://img.shields.io/pypi/l/smartcli-toolkit?color=green)](LICENSE)
 [![Downloads](https://img.shields.io/pypi/dm/smartcli-toolkit?color=blueviolet)](https://pypi.org/project/smartcli-toolkit/)
 [![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**
@@ -70,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
@@ -166,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 22 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"
@@ -199,6 +222,14 @@ python skills/drive-tui/scripts/tui.py snapshot --id <SID>
 python skills/drive-tui/scripts/tui.py close --id <SID>
 ```
 
+Or drive from any MCP client — the same verbs as MCP tools, with the
+per-session token attached automatically:
+
+```bash
+pip install "smartcli-toolkit[mcp]"
+python skills/drive-tui/scripts/mcp_server.py     # stdio MCP server
+```
+
 ### As a library
 
 The shared core is importable directly:
@@ -220,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. **22 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) 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.
 
@@ -254,7 +285,7 @@ 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 (22 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)
   tools/screenshot/        pyte -> PNG smoke-test harness

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/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,8 +14,11 @@ 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

{smartcli_toolkit-0.1.3 → smartcli_toolkit-0.1.5}/smartcli_toolkit.egg-info/requires.txt

@@ -11,8 +11,14 @@ wcwidth>=0.2.0
 [art]
 pyfiglet>=1.0.0
 
+[dev]
+coverage[toml]>=7.0
+
 [image]
 Pillow>=10.0.0
 
+[mcp]
+mcp>=1.0
+
 [width]
 wcwidth>=0.2.0

smartcli_toolkit-0.1.5/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.5/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.5/tests/test_golden_frames.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""test_golden_frames.py — golden-frame snapshot regression for tui-ui widgets.
+
+Every registered widget is rendered to a DETERMINISTIC ANSI frame (its
+``sample(theme)`` composed into a fixed-size ``Page``, exactly the path
+``python -m ui demo`` uses) and compared byte-for-byte against a committed
+baseline in ``tests/golden/<key>.txt``. This locks the 15 widgets against silent
+visual regressions — today only degenerate-input crashes and the fx frame
+contract are guarded; widget *output* was not.
+
+Pure/in-memory: it imports the ui package and renders strings, never spawns a
+process. Deterministic: widgets carry no random/time dependency (verified), and
+the test renders each widget TWICE and fails if the two disagree, so a
+non-deterministic widget can never silently bake flakiness into a baseline.
+
+Usage:
+    python tests/test_golden_frames.py            # check against baselines (exit 1 on drift)
+    python tests/test_golden_frames.py --update    # (re)write baselines from current output
+    python tests/test_golden_frames.py badge card  # limit to named widgets
+
+The baselines are meant to be reviewed in the diff: when a widget's look changes
+on purpose, run --update and the PR shows exactly which cells moved.
+"""
+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"))
+
+# Force UTF-8 stdout: baselines and diffs contain box-drawing + CJK, which crash
+# on a legacy Windows codepage (CP936) otherwise.
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+except Exception:
+    pass
+
+from ui import registry  # noqa: E402
+from ui.box import Box  # noqa: E402
+from ui.core import get_theme  # noqa: E402
+from ui.layout import Page  # noqa: E402
+
+GOLDEN_DIR = ROOT / "tests" / "golden"
+
+# Fixed render parameters — must stay constant or every baseline shifts. Chosen
+# wide/tall enough that no widget sample clips at its default.
+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:
+    results.append((name, ok, detail))
+    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()."""
+    theme = get_theme(THEME)
+    widget = cls.sample(theme)
+    page = Page(Box(content=widget, padding=(0, 0), bg=theme.bg),
+                width=WIDTH, height=HEIGHT, bg=theme.bg)
+    return page.to_ansi()
+
+
+def _baseline_path(key: str) -> Path:
+    return GOLDEN_DIR / f"{key}.txt"
+
+
+def _read_lf(path: Path) -> str:
+    """Read a baseline, normalizing any CRLF to LF so the comparison is
+    platform-independent (a Windows checkout may present CRLF; the rendered
+    frame is always LF)."""
+    return path.read_text(encoding="utf-8").replace("\r\n", "\n")
+
+
+def _first_diff(a: str, b: str) -> str:
+    """Human-pointable description of where two frames first differ."""
+    al, bl = a.splitlines(), b.splitlines()
+    if len(al) != len(bl):
+        return f"line count {len(al)} != baseline {len(bl)}"
+    for i, (x, y) in enumerate(zip(al, bl)):
+        if x != y:
+            col = next((j for j, (cx, cy) in enumerate(zip(x, y)) if cx != cy),
+                       min(len(x), len(y)))
+            return f"line {i} differs at col {col}"
+    return "identical length, content differs (trailing?)"
+
+
+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)
+    frame2 = render_widget(cls)
+    if frame1 != frame2:
+        record(f"golden {key}", False,
+               f"NON-DETERMINISTIC render ({_first_diff(frame1, frame2)}) — "
+               "fix the widget or seed it before baselining")
+        return
+
+    path = _baseline_path(key)
+    if update:
+        GOLDEN_DIR.mkdir(parents=True, exist_ok=True)
+        existed = path.exists()
+        old = _read_lf(path) if existed else None
+        # Write with LF newlines explicitly (newline="") so a Windows run doesn't
+        # bake CRLF into the baseline — the rendered frame uses \n, and git
+        # normalizes these files to LF (.gitattributes), so the baseline must be
+        # LF on every platform or the check would drift CRLF-vs-LF across OSes.
+        with open(path, "w", encoding="utf-8", newline="") as fh:
+            fh.write(frame1)
+        state = "unchanged" if old == frame1 else ("updated" if existed else "created")
+        record(f"golden {key}", True, f"baseline {state}")
+        return
+
+    if not path.exists():
+        record(f"golden {key}", False,
+               f"NO baseline at {path.relative_to(ROOT)} — run with --update")
+        return
+    baseline = _read_lf(path)
+    if frame1 == baseline:
+        record(f"golden {key}", True, f"matches baseline ({len(frame1)} bytes)")
+    else:
+        record(f"golden {key}", False,
+               f"DRIFT vs baseline: {_first_diff(frame1, baseline)} "
+               "(intentional? run --update and review the diff)")
+
+
+def main(argv: list[str]) -> int:
+    update = "--update" in argv
+    only = {a for a in argv if not a.startswith("-")}
+
+    registry.load_all()
+    for mod, _tb in registry.load_errors():
+        print(f"warning: widget module {mod} failed to import", file=sys.stderr)
+
+    widgets = [c for c in registry.all_widgets() if not only or c.key in only]
+    if not widgets:
+        print(f"error: no widgets matched {only or '(all)'}", file=sys.stderr)
+        return 2
+
+    for cls in widgets:
+        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}){skip_note}")
+    if failed and not update:
+        print("golden-frame drift — review, then `--update` if intended:")
+        for name, _ok, detail in failed:
+            print(f"  - {name}: {detail}")
+    return 1 if (failed and not update) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))