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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.5
+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
@@ -195,7 +195,7 @@ backend, and dependency versions — run it and paste the output when filing a b
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 22 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"
@@ -205,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
 ```
@@ -251,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. **22 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, julia, mandelbrot, perlin) 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.
 
@@ -285,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 (22 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.5 → smartcli_toolkit-0.1.6}/README.md

@@ -149,7 +149,7 @@ backend, and dependency versions — run it and paste the output when filing a b
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 22 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"
@@ -159,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
 ```
@@ -205,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. **22 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, julia, mandelbrot, perlin) 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.
 
@@ -239,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 (22 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.5 → smartcli_toolkit-0.1.6}/pyproject.toml

@@ -30,7 +30,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartcli-toolkit"
-version = "0.1.5"
+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.5 → smartcli_toolkit-0.1.6}/smartcli_core/__init__.py

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

{smartcli_toolkit-0.1.5 → 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
@@ -295,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.5 → 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.5
+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
@@ -195,7 +195,7 @@ backend, and dependency versions — run it and paste the output when filing a b
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 22 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"
@@ -205,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
 ```
@@ -251,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. **22 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, julia, mandelbrot, perlin) 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.
 
@@ -285,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 (22 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.5 → smartcli_toolkit-0.1.6}/smartcli_toolkit.egg-info/SOURCES.txt

@@ -21,4 +21,5 @@ 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_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())