smartcli-toolkit 0.1.1__tar.gz → 0.1.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/PKG-INFO +278 -246
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/README.md +64 -32
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/pyproject.toml +32 -1
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/setup.cfg +4 -4
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_core/__init__.py +9 -4
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_core/pty_backend.py +49 -2
- smartcli_toolkit-0.1.3/smartcli_core/py.typed +0 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_core/readiness.py +22 -2
- smartcli_toolkit-0.1.3/smartcli_core/screen_model.py +224 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_core/session.py +44 -5
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_toolkit.egg-info/PKG-INFO +278 -246
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_toolkit.egg-info/SOURCES.txt +6 -1
- smartcli_toolkit-0.1.3/tests/test_degenerate_inputs.py +122 -0
- smartcli_toolkit-0.1.3/tests/test_doc_counts.py +134 -0
- smartcli_toolkit-0.1.3/tests/test_fx_contract.py +267 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/tests/test_readiness.py +116 -21
- smartcli_toolkit-0.1.3/tests/test_vendor_sync.py +43 -0
- smartcli_toolkit-0.1.1/smartcli_core/screen_model.py +0 -132
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/LICENSE +0 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_core/snapshot.py +0 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_toolkit.egg-info/dependency_links.txt +0 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_toolkit.egg-info/requires.txt +0 -0
- {smartcli_toolkit-0.1.1 → smartcli_toolkit-0.1.3}/smartcli_toolkit.egg-info/top_level.txt +0 -0
|
@@ -1,246 +1,278 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: smartcli-toolkit
|
|
3
|
-
Version: 0.1.
|
|
4
|
-
Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
|
|
5
|
-
Author: dwgx
|
|
6
|
-
License-Expression: MIT
|
|
7
|
-
Project-URL: Homepage, https://github.com/dwgx/SmartCLI
|
|
8
|
-
Project-URL: Repository, https://github.com/dwgx/SmartCLI
|
|
9
|
-
Project-URL: Changelog, https://github.com/dwgx/SmartCLI/blob/main/CHANGELOG.md
|
|
10
|
-
Project-URL: Issues, https://github.com/dwgx/SmartCLI/issues
|
|
11
|
-
Project-URL: PyPI, https://pypi.org/project/smartcli-toolkit/
|
|
12
|
-
Keywords: terminal,tui,pty,ansi,cli,ascii-art,terminal-effects,claude-skill,pyte,conpty
|
|
13
|
-
Classifier: Development Status :: 4 - Beta
|
|
14
|
-
Classifier: Intended Audience :: Developers
|
|
15
|
-
Classifier: Operating System :: OS Independent
|
|
16
|
-
Classifier: Programming Language :: Python :: 3
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
-
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
-
Classifier: Topic :: Terminals
|
|
24
|
-
Classifier: Topic :: Software Development :: Libraries
|
|
25
|
-
Classifier: Environment :: Console
|
|
26
|
-
Requires-Python: >=3.9
|
|
27
|
-
Description-Content-Type: text/markdown
|
|
28
|
-
License-File: LICENSE
|
|
29
|
-
Requires-Dist: pyte>=0.8.1
|
|
30
|
-
Requires-Dist: pywinpty>=2.0; platform_system == "Windows"
|
|
31
|
-
Provides-Extra: art
|
|
32
|
-
Requires-Dist: pyfiglet>=1.0.0; extra == "art"
|
|
33
|
-
Provides-Extra: image
|
|
34
|
-
Requires-Dist: Pillow>=10.0.0; extra == "image"
|
|
35
|
-
Provides-Extra: width
|
|
36
|
-
Requires-Dist: wcwidth>=0.2.0; extra == "width"
|
|
37
|
-
Provides-Extra: all
|
|
38
|
-
Requires-Dist: pyfiglet>=1.0.0; extra == "all"
|
|
39
|
-
Requires-Dist: Pillow>=10.0.0; extra == "all"
|
|
40
|
-
Requires-Dist: wcwidth>=0.2.0; extra == "all"
|
|
41
|
-
Dynamic: license-file
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
[
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
[ | [繁體中文](docs/i18n/README.zh-Hant.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) -->
|
|
44
|
+
|
|
45
|
+
# SmartCLI
|
|
46
|
+
|
|
47
|
+
*Read this in: **English** · [简体中文](docs/i18n/README.zh-Hans.md) · [繁體中文](docs/i18n/README.zh-Hant.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md)*
|
|
48
|
+
|
|
49
|
+
**A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + `pyte` core.**
|
|
50
|
+
|
|
51
|
+
[](https://pypi.org/project/smartcli-toolkit/)
|
|
52
|
+
[](https://pypi.org/project/smartcli-toolkit/)
|
|
53
|
+
[](https://github.com/dwgx/SmartCLI/actions/workflows/ci.yml)
|
|
54
|
+
[](LICENSE)
|
|
55
|
+
[](https://pypi.org/project/smartcli-toolkit/)
|
|
56
|
+
[](#features)
|
|
57
|
+
[](#install)
|
|
58
|
+
|
|
59
|
+
## What & why
|
|
60
|
+
|
|
61
|
+
SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
|
|
62
|
+
interactive terminal programs, **perceiving** what a screen actually shows, and
|
|
63
|
+
**rendering** visuals and layouts back out. It is built on one shared, pluggable PTY
|
|
64
|
+
backend plus a `pyte` screen model — chosen over screenshot/vision so a single
|
|
65
|
+
structured screen model feeds both perception (read the screen) and rendering
|
|
66
|
+
(draw the screen). The PTY layer is intentionally **not** tmux-bound: local dev runs
|
|
67
|
+
on Windows via ConPTY (`pywinpty`), while target programs can run under POSIX ptys
|
|
68
|
+
or tmux elsewhere. Three skills sit on that core, each a self-contained tool you run
|
|
69
|
+
in place from the checkout.
|
|
70
|
+
|
|
71
|
+
## Driving a real TUI
|
|
72
|
+
|
|
73
|
+
SmartCLI driving **lazygit** — a real full-screen curses app — through its
|
|
74
|
+
perceive → act → confirm loop: it reads the `pyte` cell grid (which row is
|
|
75
|
+
selected, the alt-screen diff), moves with arrow keys, opens a commit's diff,
|
|
76
|
+
and highlights a branch. This is captured by driving the actual program in a
|
|
77
|
+
Linux container, not scripted or mocked. A byte-stream matcher like pexpect
|
|
78
|
+
can't perceive "which row is highlighted"; a screen model can.
|
|
79
|
+
|
|
80
|
+
<p align="center">
|
|
81
|
+
<img src="showcase/drive-lazygit.gif" alt="SmartCLI driving the real lazygit TUI: navigating panels, opening a commit diff, highlighting a branch" width="700">
|
|
82
|
+
</p>
|
|
83
|
+
|
|
84
|
+
> Honest scope: CI runs a Windows + Linux + macOS matrix. The POSIX pty backend
|
|
85
|
+
> (spawn / read / drive / resize / zombie-free terminate) is verified on Linux
|
|
86
|
+
> **and macOS** in CI; the interactive DECCKM/SS3-arrow probe is skipped on CI
|
|
87
|
+
> runners (no controllable terminal) and still wants a real-host run. Real tmux is
|
|
88
|
+
> not yet verified — known edges are listed in
|
|
89
|
+
> [`skills/drive-tui/references/LIMITATIONS.md`](skills/drive-tui/references/LIMITATIONS.md).
|
|
90
|
+
|
|
91
|
+
Verified on Windows 11, Python 3.14.6, `pyte` + `pywinpty` / ConPTY. This machine has
|
|
92
|
+
no real `tmux`, so screenshot reports are honestly labelled `pyte-simulation`, not
|
|
93
|
+
real tmux captures.
|
|
94
|
+
|
|
95
|
+
## Live effects
|
|
96
|
+
|
|
97
|
+
Real captures of the `cmd-art` `fx` engine — each GIF is the actual effect
|
|
98
|
+
rendered frame-by-frame through the project's own pipeline (no screen recorder).
|
|
99
|
+
Reproduce any with `python -m fx play <name>` (see [Quickstart](#quickstart)).
|
|
100
|
+
|
|
101
|
+
<p align="center">
|
|
102
|
+
<img src="showcase/fx-solarsystem.gif" alt="ASCII solar system orrery — planets orbiting a pulsing sun" width="620"><br>
|
|
103
|
+
<sub><b>solarsystem</b> — an orrery: planets on elliptical orbits around a pulsing sun</sub>
|
|
104
|
+
</p>
|
|
105
|
+
|
|
106
|
+
| | | |
|
|
107
|
+
|:---:|:---:|:---:|
|
|
108
|
+
|  |  |  |
|
|
109
|
+
| **donut** — the classic ASCII torus | **fire** — demoscene heat field | **rain** — Matrix digital rain |
|
|
110
|
+
|
|
111
|
+
> 🌐 **[Explore the live showcase →](https://dwgx.github.io/SmartCLI/)** — play with
|
|
112
|
+
> the effect engine, drive a menu with arrow keys, and poke the widgets, right in
|
|
113
|
+
> your browser.
|
|
114
|
+
|
|
115
|
+
## Install
|
|
116
|
+
|
|
117
|
+
**Primary — from PyPI:**
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pip install smartcli-toolkit
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
> **Distribution vs import name:** the PyPI distribution is `smartcli-toolkit`
|
|
124
|
+
> (the names `smartcli` / `smart-cli` were taken or blocked), but the importable
|
|
125
|
+
> package is `smartcli_core`. So after `pip install smartcli-toolkit` you still
|
|
126
|
+
> write `from smartcli_core import PtySession`.
|
|
127
|
+
|
|
128
|
+
**Alternative — reproduce the full dev environment from a source checkout:**
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
git clone https://github.com/dwgx/SmartCLI SmartCLI
|
|
132
|
+
cd SmartCLI
|
|
133
|
+
python -m pip install -r requirements.txt
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
`requirements.txt` pulls only the two required runtime deps: `pyte` (everywhere) and
|
|
137
|
+
`pywinpty` (Windows only — the marker skips it on POSIX, which uses the stdlib `pty`
|
|
138
|
+
backend). From the checkout, `pip install .` installs the same importable
|
|
139
|
+
`smartcli_core` package.
|
|
140
|
+
|
|
141
|
+
Honest scope note: `pip install smartcli-toolkit` installs the clean, importable `smartcli_core`
|
|
142
|
+
package plus its required deps. It does **not** relocate the three skills — those run
|
|
143
|
+
in place via their own entry points (`python -m fx`, `python -m ui`,
|
|
144
|
+
`skills/drive-tui/scripts/tui.py`), exactly as the Quickstart shows. This is by design;
|
|
145
|
+
see the note at the top of [`pyproject.toml`](pyproject.toml).
|
|
146
|
+
|
|
147
|
+
**Optional extras** (real FIGlet fonts, raster images, authoritative cell widths — all
|
|
148
|
+
degrade gracefully to stdlib fallbacks when absent):
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
python -m pip install -r requirements-optional.txt
|
|
152
|
+
# or, from the checkout, via pyproject extras:
|
|
153
|
+
pip install ".[all]" # pyfiglet + Pillow + wcwidth
|
|
154
|
+
pip install ".[art]" # pyfiglet only
|
|
155
|
+
pip install ".[image]" # Pillow only (also: the PNG screenshot harness needs it)
|
|
156
|
+
pip install ".[width]" # wcwidth only
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
**Windows note:** set UTF-8 output before running any skill so box-drawing and CJK
|
|
160
|
+
glyphs encode cleanly (the CLIs also auto-reconfigure stdout, but set this to be safe):
|
|
161
|
+
|
|
162
|
+
```powershell
|
|
163
|
+
set PYTHONIOENCODING=utf-8
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Verified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,
|
|
167
|
+
`pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.
|
|
168
|
+
|
|
169
|
+
## Quickstart
|
|
170
|
+
|
|
171
|
+
### cmd-art — terminal visual effects
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
cd skills/cmd-art
|
|
175
|
+
python -m fx list # list all 19 effects
|
|
176
|
+
python -m fx play donut --seconds 5 # play one effect (bounded)
|
|
177
|
+
python -m fx gallery # one frame of each effect
|
|
178
|
+
python -m fx show --seq "donut:fire:3,plasma::3"
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### tui-ui — cell-accurate terminal UI
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
cd skills/tui-ui
|
|
185
|
+
python -m ui widgets # list all 15 widgets
|
|
186
|
+
python -m ui gallery --width 100 --height 30
|
|
187
|
+
python -m ui demo table --width 80 --height 12 --theme dashboard
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### drive-tui — perceive & drive interactive programs
|
|
191
|
+
|
|
192
|
+
Persistent-session CLI (state survives across shell calls):
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
python skills/drive-tui/scripts/tui.py start --cmd "python" --cols 80 --rows 24
|
|
196
|
+
python skills/drive-tui/scripts/tui.py wait-regex --id <SID> ">>> " --timeout-ms 15000
|
|
197
|
+
python skills/drive-tui/scripts/tui.py send-line --id <SID> "print(6*7)"
|
|
198
|
+
python skills/drive-tui/scripts/tui.py snapshot --id <SID>
|
|
199
|
+
python skills/drive-tui/scripts/tui.py close --id <SID>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### As a library
|
|
203
|
+
|
|
204
|
+
The shared core is importable directly:
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
import sys
|
|
208
|
+
from smartcli_core import PtySession
|
|
209
|
+
|
|
210
|
+
s = PtySession()
|
|
211
|
+
s.start([sys.executable, "-q"])
|
|
212
|
+
s.wait_for(r">>> ") # readiness sync, never a blind sleep
|
|
213
|
+
print(s.snapshot().to_text()) # pyte-backed structured screen
|
|
214
|
+
s.close()
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
For the full command reference, the screenshot/AGENTCLI harnesses, and the regression
|
|
218
|
+
suite, see **[`README-USAGE.md`](README-USAGE.md)**.
|
|
219
|
+
|
|
220
|
+
## Features
|
|
221
|
+
|
|
222
|
+
**`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
|
|
223
|
+
`@register` decorator + auto-discovery. **19 effects** (donut, solarsystem, fire, plasma,
|
|
224
|
+
rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
|
|
225
|
+
gradient_text, banner_scroll, image2ascii, typewriter) across **8 themes** (mono, fire,
|
|
226
|
+
ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
|
|
227
|
+
producers; `play` is bounded by default and always restores the terminal.
|
|
228
|
+
|
|
229
|
+
**`tui-ui`** (`skills/tui-ui`) — a web-like terminal layout engine emitting tmux-safe
|
|
230
|
+
ANSI frames (SGR color runs + newlines only; no cursor moves, no alt-screen). **15
|
|
231
|
+
widgets** (badge, banner, braille_chart, card, gradient_rule, kv, meter, panel,
|
|
232
|
+
progress, radial_glow, rule, slider_track, table, tabs, tree) over a real **engine**:
|
|
233
|
+
`field.py` (shader compositors), `raster.py` (sub-cell half/quad/braille pixels),
|
|
234
|
+
`box_junction.py` (edge-algebra box joins), `color_model.py` (honest truecolor → 256 →
|
|
235
|
+
16 → mono degrade). Display-cell accurate for CJK/emoji/ZWJ so columns never desync.
|
|
236
|
+
|
|
237
|
+
**`drive-tui`** (`skills/drive-tui`) — drives interactive terminal programs (REPLs,
|
|
238
|
+
menus, pagers, y/N prompts, wizards) through a PTY via a
|
|
239
|
+
perceive → decide → act → wait → confirm loop, never a blind sleep. A thin CLI
|
|
240
|
+
(`scripts/tui.py`) offers a persistent detached session and a one-shot `run` mode, with
|
|
241
|
+
an importable pattern library of **8 recipes** (repl, menu_select, pager, search_filter,
|
|
242
|
+
confirm, form, progress, wizard) that `classify()` a screen and `drive()` it.
|
|
243
|
+
|
|
244
|
+
**Shared core** (`smartcli_core`) — the pluggable PTY backend + `pyte` screen model +
|
|
245
|
+
semantic snapshot + readiness sync (`pty_backend / screen_model / snapshot / readiness /
|
|
246
|
+
session`). The reusable, importable foundation under all three skills.
|
|
247
|
+
|
|
248
|
+
**Knowledge graph** (`knowledge/`) — a 122-note wiki-link graph of exact rendering
|
|
249
|
+
formulas, ANSI sequences, and measured constants, each note carrying a source and
|
|
250
|
+
cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
|
|
251
|
+
|
|
252
|
+
## Project layout
|
|
253
|
+
|
|
254
|
+
```text
|
|
255
|
+
SmartCLI/
|
|
256
|
+
smartcli_core/ shared PTY + pyte engine (importable package)
|
|
257
|
+
skills/cmd-art/ fx effect package and CLI (19 effects, 8 themes)
|
|
258
|
+
skills/drive-tui/ TUI pattern library and PTY driver CLI (8 recipes)
|
|
259
|
+
skills/tui-ui/ terminal UI layout engine and widgets (15 widgets)
|
|
260
|
+
tools/screenshot/ pyte -> PNG smoke-test harness
|
|
261
|
+
tools/agentcli/ agent-CLI control validation harness
|
|
262
|
+
knowledge/ 122-note knowledge graph (see knowledge/INDEX.md)
|
|
263
|
+
showcase/ rendered effect PNGs + demo GIFs (shown above)
|
|
264
|
+
tests/ direct script-style regressions
|
|
265
|
+
research/ archived first-pass research notes
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
## Documentation
|
|
269
|
+
|
|
270
|
+
- **[`README-USAGE.md`](README-USAGE.md)** — the full usage cheat-sheet: every skill,
|
|
271
|
+
the screenshot and AGENTCLI harnesses, and the regression commands.
|
|
272
|
+
- **[`knowledge/INDEX.md`](knowledge/INDEX.md)** — the 122-note knowledge graph.
|
|
273
|
+
- **[`AGENTCLI-VALIDATION.md`](AGENTCLI-VALIDATION.md)** — agent-CLI control test matrix.
|
|
274
|
+
- **[`CHANGELOG.md`](CHANGELOG.md)** — release history.
|
|
275
|
+
|
|
276
|
+
## License
|
|
277
|
+
|
|
278
|
+
MIT — see [LICENSE](LICENSE).
|