smartcli-toolkit 0.1.0__py3-none-any.whl

smartcli_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: smartcli-toolkit
+Version: 0.1.0
+Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyte>=0.8.1
+Requires-Dist: pywinpty>=2.0; platform_system == "Windows"
+Provides-Extra: art
+Requires-Dist: pyfiglet>=1.0.0; extra == "art"
+Provides-Extra: image
+Requires-Dist: Pillow>=10.0.0; extra == "image"
+Provides-Extra: width
+Requires-Dist: wcwidth>=0.2.0; extra == "width"
+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"
+Dynamic: license-file
+
+# SmartCLI
+
+**A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + `pyte` core.**
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Version 0.1.0](https://img.shields.io/badge/version-0.1.0-orange)](CHANGELOG.md)
+[![Skills: 3](https://img.shields.io/badge/skills-3-purple)](#features)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20POSIX-lightgrey)](#install)
+
+## What & why
+
+SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
+interactive terminal programs, **perceiving** what a screen actually shows, and
+**rendering** visuals and layouts back out. It is built on one shared, pluggable PTY
+backend plus a `pyte` screen model — chosen over screenshot/vision so a single
+structured screen model feeds both perception (read the screen) and rendering
+(draw the screen). The PTY layer is intentionally **not** tmux-bound: local dev runs
+on Windows via ConPTY (`pywinpty`), while target programs can run under POSIX ptys
+or tmux elsewhere. Three skills sit on that core, each a self-contained tool you run
+in place from the checkout.
+
+Verified on Windows 11, Python 3.14.6, `pyte` + `pywinpty` / ConPTY. This machine has
+no real `tmux`, so screenshot reports are honestly labelled `pyte-simulation`, not
+real tmux captures.
+
+## Screenshots
+
+A small gallery of `cmd-art` effects, rendered through the `fx` engine. Reproduce any
+of these with `python -m fx play <name>` (see [Quickstart](#quickstart)).
+
+| | | |
+|:---:|:---:|:---:|
+| ![donut](showcase/donut.png) | ![fire](showcase/fire.png) | ![plasma](showcase/plasma.png) |
+| **donut** | **fire** | **plasma** |
+| ![rain](showcase/rain.png) | ![starfield](showcase/starfield.png) | ![tunnel](showcase/tunnel.png) |
+| **rain** | **starfield** | **tunnel** |
+
+## Install
+
+SmartCLI is **not on PyPI yet** — install from a source checkout. Every command below
+works today from a clean clone.
+
+**Primary — reproduce the full dev environment** (recommended):
+
+```bash
+git clone <repo-url> SmartCLI
+cd SmartCLI
+python -m pip install -r requirements.txt
+```
+
+`requirements.txt` pulls only the two required runtime deps: `pyte` (everywhere) and
+`pywinpty` (Windows only — the marker skips it on POSIX, which uses the stdlib `pty`
+backend).
+
+**Install the shared core package** (`smartcli_core`):
+
+```bash
+pip install .
+```
+
+> **Distribution vs import name:** the PyPI distribution is `smartcli-toolkit`
+> (the names `smartcli` / `smart-cli` were taken or blocked), but the importable
+> package is `smartcli_core`. So after `pip install smartcli-toolkit` you still
+> write `from smartcli_core import PtySession`.
+
+Honest scope note: `pip install .` installs the clean, importable `smartcli_core`
+package plus its required deps. It does **not** relocate the three skills — those run
+in place via their own entry points (`python -m fx`, `python -m ui`,
+`skills/drive-tui/scripts/tui.py`), exactly as the Quickstart shows. This is by design;
+see the note at the top of [`pyproject.toml`](pyproject.toml).
+
+**Optional extras** (real FIGlet fonts, raster images, authoritative cell widths — all
+degrade gracefully to stdlib fallbacks when absent):
+
+```bash
+python -m pip install -r requirements-optional.txt
+# or, from the checkout, via pyproject extras:
+pip install ".[all]"        # pyfiglet + Pillow + wcwidth
+pip install ".[art]"        # pyfiglet only
+pip install ".[image]"      # Pillow only  (also: the PNG screenshot harness needs it)
+pip install ".[width]"      # wcwidth only
+```
+
+**Windows note:** set UTF-8 output before running any skill so box-drawing and CJK
+glyphs encode cleanly (the CLIs also auto-reconfigure stdout, but set this to be safe):
+
+```powershell
+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.
+
+## Quickstart
+
+### cmd-art — terminal visual effects
+
+```bash
+cd skills/cmd-art
+python -m fx list                          # list all 18 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"
+```
+
+### tui-ui — cell-accurate terminal UI
+
+```bash
+cd skills/tui-ui
+python -m ui widgets                       # list all 15 widgets
+python -m ui gallery --width 100 --height 30
+python -m ui demo table --width 80 --height 12 --theme dashboard
+```
+
+### drive-tui — perceive & drive interactive programs
+
+Persistent-session CLI (state survives across shell calls):
+
+```bash
+python skills/drive-tui/scripts/tui.py start --cmd "python" --cols 80 --rows 24
+python skills/drive-tui/scripts/tui.py wait-regex --id <SID> ">>> " --timeout-ms 15000
+python skills/drive-tui/scripts/tui.py send-line --id <SID> "print(6*7)"
+python skills/drive-tui/scripts/tui.py snapshot --id <SID>
+python skills/drive-tui/scripts/tui.py close --id <SID>
+```
+
+### As a library
+
+The shared core is importable directly:
+
+```python
+import sys
+from smartcli_core import PtySession
+
+s = PtySession()
+s.start([sys.executable, "-q"])
+s.wait_for(r">>> ")            # readiness sync, never a blind sleep
+print(s.snapshot().to_text())  # pyte-backed structured screen
+s.close()
+```
+
+For the full command reference, the screenshot/AGENTCLI harnesses, and the regression
+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. **18 effects** (donut, fire, plasma, rain,
+starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
+gradient_text, banner_scroll, image2ascii, typewriter) 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.
+
+**`tui-ui`** (`skills/tui-ui`) — a web-like terminal layout engine emitting tmux-safe
+ANSI frames (SGR color runs + newlines only; no cursor moves, no alt-screen). **15
+widgets** (badge, banner, braille_chart, card, gradient_rule, kv, meter, panel,
+progress, radial_glow, rule, slider_track, table, tabs, tree) over a real **engine**:
+`field.py` (shader compositors), `raster.py` (sub-cell half/quad/braille pixels),
+`box_junction.py` (edge-algebra box joins), `color_model.py` (honest truecolor → 256 →
+16 → mono degrade). Display-cell accurate for CJK/emoji/ZWJ so columns never desync.
+
+**`drive-tui`** (`skills/drive-tui`) — drives interactive terminal programs (REPLs,
+menus, pagers, y/N prompts, wizards) through a PTY via a
+perceive → decide → act → wait → confirm loop, never a blind sleep. A thin CLI
+(`scripts/tui.py`) offers a persistent detached session and a one-shot `run` mode, with
+an importable pattern library of **8 recipes** (repl, menu_select, pager, search_filter,
+confirm, form, progress, wizard) that `classify()` a screen and `drive()` it.
+
+**Shared core** (`smartcli_core`) — the pluggable PTY backend + `pyte` screen model +
+semantic snapshot + readiness sync (`pty_backend / screen_model / snapshot / readiness /
+session`). The reusable, importable foundation under all three skills.
+
+**Knowledge graph** (`knowledge/`) — a 122-note wiki-link graph of exact rendering
+formulas, ANSI sequences, and measured constants, each note carrying a source and
+cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
+
+## Project layout
+
+```text
+SmartCLI/
+  smartcli_core/           shared PTY + pyte engine (importable package)
+  skills/cmd-art/          fx effect package and CLI (18 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
+  tools/agentcli/          agent-CLI control validation harness
+  knowledge/               122-note knowledge graph (see knowledge/INDEX.md)
+  showcase/                rendered effect PNGs (see Screenshots)
+  tests/                   direct script-style regressions
+  research/                archived first-pass research notes
+```
+
+## Documentation
+
+- **[`README-USAGE.md`](README-USAGE.md)** — the full usage cheat-sheet: every skill,
+  the screenshot and AGENTCLI harnesses, and the regression commands.
+- **[`knowledge/INDEX.md`](knowledge/INDEX.md)** — the 122-note knowledge graph.
+- **[`AGENTCLI-VALIDATION.md`](AGENTCLI-VALIDATION.md)** — agent-CLI control test matrix.
+- **[`CHANGELOG.md`](CHANGELOG.md)** — release history.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

smartcli_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+smartcli_core/__init__.py,sha256=_baqQ8WAl7DanvDRZ6DbwEqXiday4x0VzT5F0Uc1Brk,1229
+smartcli_core/pty_backend.py,sha256=sQ7av4GrRCYAqR0G5AJqArMtjvOWVIBRQuJ8rNzFyyo,7988
+smartcli_core/readiness.py,sha256=eap_mya7o-RaKEA7iriV0I26i_b2CJiyki62QDFseGQ,7278
+smartcli_core/screen_model.py,sha256=OP76OxJRYwjUd-ioLbsjQYtSeLVBnJCcHEbd8QLqO_A,4706
+smartcli_core/session.py,sha256=Olf3iHnCpq4SDEEp4dmSF6ckLe89rLDntTlo5q92JrU,7737
+smartcli_core/snapshot.py,sha256=RA44RkTrko5Q_h6GNmMTldQTEPgKqvSsAB8FDLYEuSw,10797
+smartcli_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=e0FKb0QeD2o5pneL0SQaTePQYRViG4Wb-sw-6Q53LQw,1078
+smartcli_toolkit-0.1.0.dist-info/METADATA,sha256=xG2o4ExTbS79ayvaADZeCqrCXgVOjM_euzJiP75MkRQ,9859
+smartcli_toolkit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+smartcli_toolkit-0.1.0.dist-info/top_level.txt,sha256=svT7ZPxhEf3E95fkz_HX7VfD-BFpkSnSd2O3u4K4MlY,14
+smartcli_toolkit-0.1.0.dist-info/RECORD,,

smartcli_toolkit-0.1.0.dist-info/WHEEL

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

smartcli_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SmartCLI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smartcli_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+smartcli_core