smartcli-toolkit 0.1.0__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.0/LICENSE +21 -0
- smartcli_toolkit-0.1.0/PKG-INFO +226 -0
- smartcli_toolkit-0.1.0/README.md +204 -0
- smartcli_toolkit-0.1.0/pyproject.toml +61 -0
- smartcli_toolkit-0.1.0/setup.cfg +4 -0
- smartcli_toolkit-0.1.0/smartcli_core/__init__.py +53 -0
- smartcli_toolkit-0.1.0/smartcli_core/pty_backend.py +259 -0
- smartcli_toolkit-0.1.0/smartcli_core/readiness.py +210 -0
- smartcli_toolkit-0.1.0/smartcli_core/screen_model.py +132 -0
- smartcli_toolkit-0.1.0/smartcli_core/session.py +244 -0
- smartcli_toolkit-0.1.0/smartcli_core/snapshot.py +297 -0
- smartcli_toolkit-0.1.0/smartcli_toolkit.egg-info/PKG-INFO +226 -0
- smartcli_toolkit-0.1.0/smartcli_toolkit.egg-info/SOURCES.txt +14 -0
- smartcli_toolkit-0.1.0/smartcli_toolkit.egg-info/dependency_links.txt +1 -0
- smartcli_toolkit-0.1.0/smartcli_toolkit.egg-info/requires.txt +18 -0
- smartcli_toolkit-0.1.0/smartcli_toolkit.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 SmartCLI contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: smartcli-toolkit
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Requires-Python: >=3.9
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Dist: pyte>=0.8.1
|
|
10
|
+
Requires-Dist: pywinpty>=2.0; platform_system == "Windows"
|
|
11
|
+
Provides-Extra: art
|
|
12
|
+
Requires-Dist: pyfiglet>=1.0.0; extra == "art"
|
|
13
|
+
Provides-Extra: image
|
|
14
|
+
Requires-Dist: Pillow>=10.0.0; extra == "image"
|
|
15
|
+
Provides-Extra: width
|
|
16
|
+
Requires-Dist: wcwidth>=0.2.0; extra == "width"
|
|
17
|
+
Provides-Extra: all
|
|
18
|
+
Requires-Dist: pyfiglet>=1.0.0; extra == "all"
|
|
19
|
+
Requires-Dist: Pillow>=10.0.0; extra == "all"
|
|
20
|
+
Requires-Dist: wcwidth>=0.2.0; extra == "all"
|
|
21
|
+
Dynamic: license-file
|
|
22
|
+
|
|
23
|
+
# SmartCLI
|
|
24
|
+
|
|
25
|
+
**A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + `pyte` core.**
|
|
26
|
+
|
|
27
|
+
[](https://www.python.org/)
|
|
28
|
+
[](LICENSE)
|
|
29
|
+
[](CHANGELOG.md)
|
|
30
|
+
[](#features)
|
|
31
|
+
[](#install)
|
|
32
|
+
|
|
33
|
+
## What & why
|
|
34
|
+
|
|
35
|
+
SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
|
|
36
|
+
interactive terminal programs, **perceiving** what a screen actually shows, and
|
|
37
|
+
**rendering** visuals and layouts back out. It is built on one shared, pluggable PTY
|
|
38
|
+
backend plus a `pyte` screen model — chosen over screenshot/vision so a single
|
|
39
|
+
structured screen model feeds both perception (read the screen) and rendering
|
|
40
|
+
(draw the screen). The PTY layer is intentionally **not** tmux-bound: local dev runs
|
|
41
|
+
on Windows via ConPTY (`pywinpty`), while target programs can run under POSIX ptys
|
|
42
|
+
or tmux elsewhere. Three skills sit on that core, each a self-contained tool you run
|
|
43
|
+
in place from the checkout.
|
|
44
|
+
|
|
45
|
+
Verified on Windows 11, Python 3.14.6, `pyte` + `pywinpty` / ConPTY. This machine has
|
|
46
|
+
no real `tmux`, so screenshot reports are honestly labelled `pyte-simulation`, not
|
|
47
|
+
real tmux captures.
|
|
48
|
+
|
|
49
|
+
## Screenshots
|
|
50
|
+
|
|
51
|
+
A small gallery of `cmd-art` effects, rendered through the `fx` engine. Reproduce any
|
|
52
|
+
of these with `python -m fx play <name>` (see [Quickstart](#quickstart)).
|
|
53
|
+
|
|
54
|
+
| | | |
|
|
55
|
+
|:---:|:---:|:---:|
|
|
56
|
+
|  |  |  |
|
|
57
|
+
| **donut** | **fire** | **plasma** |
|
|
58
|
+
|  |  |  |
|
|
59
|
+
| **rain** | **starfield** | **tunnel** |
|
|
60
|
+
|
|
61
|
+
## Install
|
|
62
|
+
|
|
63
|
+
SmartCLI is **not on PyPI yet** — install from a source checkout. Every command below
|
|
64
|
+
works today from a clean clone.
|
|
65
|
+
|
|
66
|
+
**Primary — reproduce the full dev environment** (recommended):
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
git clone <repo-url> SmartCLI
|
|
70
|
+
cd SmartCLI
|
|
71
|
+
python -m pip install -r requirements.txt
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`requirements.txt` pulls only the two required runtime deps: `pyte` (everywhere) and
|
|
75
|
+
`pywinpty` (Windows only — the marker skips it on POSIX, which uses the stdlib `pty`
|
|
76
|
+
backend).
|
|
77
|
+
|
|
78
|
+
**Install the shared core package** (`smartcli_core`):
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
pip install .
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
> **Distribution vs import name:** the PyPI distribution is `smartcli-toolkit`
|
|
85
|
+
> (the names `smartcli` / `smart-cli` were taken or blocked), but the importable
|
|
86
|
+
> package is `smartcli_core`. So after `pip install smartcli-toolkit` you still
|
|
87
|
+
> write `from smartcli_core import PtySession`.
|
|
88
|
+
|
|
89
|
+
Honest scope note: `pip install .` installs the clean, importable `smartcli_core`
|
|
90
|
+
package plus its required deps. It does **not** relocate the three skills — those run
|
|
91
|
+
in place via their own entry points (`python -m fx`, `python -m ui`,
|
|
92
|
+
`skills/drive-tui/scripts/tui.py`), exactly as the Quickstart shows. This is by design;
|
|
93
|
+
see the note at the top of [`pyproject.toml`](pyproject.toml).
|
|
94
|
+
|
|
95
|
+
**Optional extras** (real FIGlet fonts, raster images, authoritative cell widths — all
|
|
96
|
+
degrade gracefully to stdlib fallbacks when absent):
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
python -m pip install -r requirements-optional.txt
|
|
100
|
+
# or, from the checkout, via pyproject extras:
|
|
101
|
+
pip install ".[all]" # pyfiglet + Pillow + wcwidth
|
|
102
|
+
pip install ".[art]" # pyfiglet only
|
|
103
|
+
pip install ".[image]" # Pillow only (also: the PNG screenshot harness needs it)
|
|
104
|
+
pip install ".[width]" # wcwidth only
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
**Windows note:** set UTF-8 output before running any skill so box-drawing and CJK
|
|
108
|
+
glyphs encode cleanly (the CLIs also auto-reconfigure stdout, but set this to be safe):
|
|
109
|
+
|
|
110
|
+
```powershell
|
|
111
|
+
set PYTHONIOENCODING=utf-8
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Verified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,
|
|
115
|
+
`pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.
|
|
116
|
+
|
|
117
|
+
## Quickstart
|
|
118
|
+
|
|
119
|
+
### cmd-art — terminal visual effects
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
cd skills/cmd-art
|
|
123
|
+
python -m fx list # list all 18 effects
|
|
124
|
+
python -m fx play donut --seconds 5 # play one effect (bounded)
|
|
125
|
+
python -m fx gallery # one frame of each effect
|
|
126
|
+
python -m fx show --seq "donut:fire:3,plasma::3"
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### tui-ui — cell-accurate terminal UI
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
cd skills/tui-ui
|
|
133
|
+
python -m ui widgets # list all 15 widgets
|
|
134
|
+
python -m ui gallery --width 100 --height 30
|
|
135
|
+
python -m ui demo table --width 80 --height 12 --theme dashboard
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### drive-tui — perceive & drive interactive programs
|
|
139
|
+
|
|
140
|
+
Persistent-session CLI (state survives across shell calls):
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
python skills/drive-tui/scripts/tui.py start --cmd "python" --cols 80 --rows 24
|
|
144
|
+
python skills/drive-tui/scripts/tui.py wait-regex --id <SID> ">>> " --timeout-ms 15000
|
|
145
|
+
python skills/drive-tui/scripts/tui.py send-line --id <SID> "print(6*7)"
|
|
146
|
+
python skills/drive-tui/scripts/tui.py snapshot --id <SID>
|
|
147
|
+
python skills/drive-tui/scripts/tui.py close --id <SID>
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### As a library
|
|
151
|
+
|
|
152
|
+
The shared core is importable directly:
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
import sys
|
|
156
|
+
from smartcli_core import PtySession
|
|
157
|
+
|
|
158
|
+
s = PtySession()
|
|
159
|
+
s.start([sys.executable, "-q"])
|
|
160
|
+
s.wait_for(r">>> ") # readiness sync, never a blind sleep
|
|
161
|
+
print(s.snapshot().to_text()) # pyte-backed structured screen
|
|
162
|
+
s.close()
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
For the full command reference, the screenshot/AGENTCLI harnesses, and the regression
|
|
166
|
+
suite, see **[`README-USAGE.md`](README-USAGE.md)**.
|
|
167
|
+
|
|
168
|
+
## Features
|
|
169
|
+
|
|
170
|
+
**`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
|
|
171
|
+
`@register` decorator + auto-discovery. **18 effects** (donut, fire, plasma, rain,
|
|
172
|
+
starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
|
|
173
|
+
gradient_text, banner_scroll, image2ascii, typewriter) across **8 themes** (mono, fire,
|
|
174
|
+
ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
|
|
175
|
+
producers; `play` is bounded by default and always restores the terminal.
|
|
176
|
+
|
|
177
|
+
**`tui-ui`** (`skills/tui-ui`) — a web-like terminal layout engine emitting tmux-safe
|
|
178
|
+
ANSI frames (SGR color runs + newlines only; no cursor moves, no alt-screen). **15
|
|
179
|
+
widgets** (badge, banner, braille_chart, card, gradient_rule, kv, meter, panel,
|
|
180
|
+
progress, radial_glow, rule, slider_track, table, tabs, tree) over a real **engine**:
|
|
181
|
+
`field.py` (shader compositors), `raster.py` (sub-cell half/quad/braille pixels),
|
|
182
|
+
`box_junction.py` (edge-algebra box joins), `color_model.py` (honest truecolor → 256 →
|
|
183
|
+
16 → mono degrade). Display-cell accurate for CJK/emoji/ZWJ so columns never desync.
|
|
184
|
+
|
|
185
|
+
**`drive-tui`** (`skills/drive-tui`) — drives interactive terminal programs (REPLs,
|
|
186
|
+
menus, pagers, y/N prompts, wizards) through a PTY via a
|
|
187
|
+
perceive → decide → act → wait → confirm loop, never a blind sleep. A thin CLI
|
|
188
|
+
(`scripts/tui.py`) offers a persistent detached session and a one-shot `run` mode, with
|
|
189
|
+
an importable pattern library of **8 recipes** (repl, menu_select, pager, search_filter,
|
|
190
|
+
confirm, form, progress, wizard) that `classify()` a screen and `drive()` it.
|
|
191
|
+
|
|
192
|
+
**Shared core** (`smartcli_core`) — the pluggable PTY backend + `pyte` screen model +
|
|
193
|
+
semantic snapshot + readiness sync (`pty_backend / screen_model / snapshot / readiness /
|
|
194
|
+
session`). The reusable, importable foundation under all three skills.
|
|
195
|
+
|
|
196
|
+
**Knowledge graph** (`knowledge/`) — a 122-note wiki-link graph of exact rendering
|
|
197
|
+
formulas, ANSI sequences, and measured constants, each note carrying a source and
|
|
198
|
+
cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
|
|
199
|
+
|
|
200
|
+
## Project layout
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
SmartCLI/
|
|
204
|
+
smartcli_core/ shared PTY + pyte engine (importable package)
|
|
205
|
+
skills/cmd-art/ fx effect package and CLI (18 effects, 8 themes)
|
|
206
|
+
skills/drive-tui/ TUI pattern library and PTY driver CLI (8 recipes)
|
|
207
|
+
skills/tui-ui/ terminal UI layout engine and widgets (15 widgets)
|
|
208
|
+
tools/screenshot/ pyte -> PNG smoke-test harness
|
|
209
|
+
tools/agentcli/ agent-CLI control validation harness
|
|
210
|
+
knowledge/ 122-note knowledge graph (see knowledge/INDEX.md)
|
|
211
|
+
showcase/ rendered effect PNGs (see Screenshots)
|
|
212
|
+
tests/ direct script-style regressions
|
|
213
|
+
research/ archived first-pass research notes
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Documentation
|
|
217
|
+
|
|
218
|
+
- **[`README-USAGE.md`](README-USAGE.md)** — the full usage cheat-sheet: every skill,
|
|
219
|
+
the screenshot and AGENTCLI harnesses, and the regression commands.
|
|
220
|
+
- **[`knowledge/INDEX.md`](knowledge/INDEX.md)** — the 122-note knowledge graph.
|
|
221
|
+
- **[`AGENTCLI-VALIDATION.md`](AGENTCLI-VALIDATION.md)** — agent-CLI control test matrix.
|
|
222
|
+
- **[`CHANGELOG.md`](CHANGELOG.md)** — release history.
|
|
223
|
+
|
|
224
|
+
## License
|
|
225
|
+
|
|
226
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# SmartCLI
|
|
2
|
+
|
|
3
|
+
**A local Python toolkit for driving, perceiving, and rendering the terminal — three agent skills over one pluggable PTY + `pyte` core.**
|
|
4
|
+
|
|
5
|
+
[](https://www.python.org/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](CHANGELOG.md)
|
|
8
|
+
[](#features)
|
|
9
|
+
[](#install)
|
|
10
|
+
|
|
11
|
+
## What & why
|
|
12
|
+
|
|
13
|
+
SmartCLI is a workspace for terminal work that agents and humans both do: **driving**
|
|
14
|
+
interactive terminal programs, **perceiving** what a screen actually shows, and
|
|
15
|
+
**rendering** visuals and layouts back out. It is built on one shared, pluggable PTY
|
|
16
|
+
backend plus a `pyte` screen model — chosen over screenshot/vision so a single
|
|
17
|
+
structured screen model feeds both perception (read the screen) and rendering
|
|
18
|
+
(draw the screen). The PTY layer is intentionally **not** tmux-bound: local dev runs
|
|
19
|
+
on Windows via ConPTY (`pywinpty`), while target programs can run under POSIX ptys
|
|
20
|
+
or tmux elsewhere. Three skills sit on that core, each a self-contained tool you run
|
|
21
|
+
in place from the checkout.
|
|
22
|
+
|
|
23
|
+
Verified on Windows 11, Python 3.14.6, `pyte` + `pywinpty` / ConPTY. This machine has
|
|
24
|
+
no real `tmux`, so screenshot reports are honestly labelled `pyte-simulation`, not
|
|
25
|
+
real tmux captures.
|
|
26
|
+
|
|
27
|
+
## Screenshots
|
|
28
|
+
|
|
29
|
+
A small gallery of `cmd-art` effects, rendered through the `fx` engine. Reproduce any
|
|
30
|
+
of these with `python -m fx play <name>` (see [Quickstart](#quickstart)).
|
|
31
|
+
|
|
32
|
+
| | | |
|
|
33
|
+
|:---:|:---:|:---:|
|
|
34
|
+
|  |  |  |
|
|
35
|
+
| **donut** | **fire** | **plasma** |
|
|
36
|
+
|  |  |  |
|
|
37
|
+
| **rain** | **starfield** | **tunnel** |
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
SmartCLI is **not on PyPI yet** — install from a source checkout. Every command below
|
|
42
|
+
works today from a clean clone.
|
|
43
|
+
|
|
44
|
+
**Primary — reproduce the full dev environment** (recommended):
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
git clone <repo-url> SmartCLI
|
|
48
|
+
cd SmartCLI
|
|
49
|
+
python -m pip install -r requirements.txt
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`requirements.txt` pulls only the two required runtime deps: `pyte` (everywhere) and
|
|
53
|
+
`pywinpty` (Windows only — the marker skips it on POSIX, which uses the stdlib `pty`
|
|
54
|
+
backend).
|
|
55
|
+
|
|
56
|
+
**Install the shared core package** (`smartcli_core`):
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
pip install .
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
> **Distribution vs import name:** the PyPI distribution is `smartcli-toolkit`
|
|
63
|
+
> (the names `smartcli` / `smart-cli` were taken or blocked), but the importable
|
|
64
|
+
> package is `smartcli_core`. So after `pip install smartcli-toolkit` you still
|
|
65
|
+
> write `from smartcli_core import PtySession`.
|
|
66
|
+
|
|
67
|
+
Honest scope note: `pip install .` installs the clean, importable `smartcli_core`
|
|
68
|
+
package plus its required deps. It does **not** relocate the three skills — those run
|
|
69
|
+
in place via their own entry points (`python -m fx`, `python -m ui`,
|
|
70
|
+
`skills/drive-tui/scripts/tui.py`), exactly as the Quickstart shows. This is by design;
|
|
71
|
+
see the note at the top of [`pyproject.toml`](pyproject.toml).
|
|
72
|
+
|
|
73
|
+
**Optional extras** (real FIGlet fonts, raster images, authoritative cell widths — all
|
|
74
|
+
degrade gracefully to stdlib fallbacks when absent):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
python -m pip install -r requirements-optional.txt
|
|
78
|
+
# or, from the checkout, via pyproject extras:
|
|
79
|
+
pip install ".[all]" # pyfiglet + Pillow + wcwidth
|
|
80
|
+
pip install ".[art]" # pyfiglet only
|
|
81
|
+
pip install ".[image]" # Pillow only (also: the PNG screenshot harness needs it)
|
|
82
|
+
pip install ".[width]" # wcwidth only
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**Windows note:** set UTF-8 output before running any skill so box-drawing and CJK
|
|
86
|
+
glyphs encode cleanly (the CLIs also auto-reconfigure stdout, but set this to be safe):
|
|
87
|
+
|
|
88
|
+
```powershell
|
|
89
|
+
set PYTHONIOENCODING=utf-8
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Verified dep versions on the dev box (Windows 11, CPython 3.14.6): `pyte` 0.8.2,
|
|
93
|
+
`pywinpty` 3.0.5, `pyfiglet` 1.0.4, `Pillow` 12.2.0, `wcwidth` 0.8.1.
|
|
94
|
+
|
|
95
|
+
## Quickstart
|
|
96
|
+
|
|
97
|
+
### cmd-art — terminal visual effects
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
cd skills/cmd-art
|
|
101
|
+
python -m fx list # list all 18 effects
|
|
102
|
+
python -m fx play donut --seconds 5 # play one effect (bounded)
|
|
103
|
+
python -m fx gallery # one frame of each effect
|
|
104
|
+
python -m fx show --seq "donut:fire:3,plasma::3"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### tui-ui — cell-accurate terminal UI
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
cd skills/tui-ui
|
|
111
|
+
python -m ui widgets # list all 15 widgets
|
|
112
|
+
python -m ui gallery --width 100 --height 30
|
|
113
|
+
python -m ui demo table --width 80 --height 12 --theme dashboard
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### drive-tui — perceive & drive interactive programs
|
|
117
|
+
|
|
118
|
+
Persistent-session CLI (state survives across shell calls):
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
python skills/drive-tui/scripts/tui.py start --cmd "python" --cols 80 --rows 24
|
|
122
|
+
python skills/drive-tui/scripts/tui.py wait-regex --id <SID> ">>> " --timeout-ms 15000
|
|
123
|
+
python skills/drive-tui/scripts/tui.py send-line --id <SID> "print(6*7)"
|
|
124
|
+
python skills/drive-tui/scripts/tui.py snapshot --id <SID>
|
|
125
|
+
python skills/drive-tui/scripts/tui.py close --id <SID>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### As a library
|
|
129
|
+
|
|
130
|
+
The shared core is importable directly:
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
import sys
|
|
134
|
+
from smartcli_core import PtySession
|
|
135
|
+
|
|
136
|
+
s = PtySession()
|
|
137
|
+
s.start([sys.executable, "-q"])
|
|
138
|
+
s.wait_for(r">>> ") # readiness sync, never a blind sleep
|
|
139
|
+
print(s.snapshot().to_text()) # pyte-backed structured screen
|
|
140
|
+
s.close()
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
For the full command reference, the screenshot/AGENTCLI harnesses, and the regression
|
|
144
|
+
suite, see **[`README-USAGE.md`](README-USAGE.md)**.
|
|
145
|
+
|
|
146
|
+
## Features
|
|
147
|
+
|
|
148
|
+
**`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
|
|
149
|
+
`@register` decorator + auto-discovery. **18 effects** (donut, fire, plasma, rain,
|
|
150
|
+
starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
|
|
151
|
+
gradient_text, banner_scroll, image2ascii, typewriter) across **8 themes** (mono, fire,
|
|
152
|
+
ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
|
|
153
|
+
producers; `play` is bounded by default and always restores the terminal.
|
|
154
|
+
|
|
155
|
+
**`tui-ui`** (`skills/tui-ui`) — a web-like terminal layout engine emitting tmux-safe
|
|
156
|
+
ANSI frames (SGR color runs + newlines only; no cursor moves, no alt-screen). **15
|
|
157
|
+
widgets** (badge, banner, braille_chart, card, gradient_rule, kv, meter, panel,
|
|
158
|
+
progress, radial_glow, rule, slider_track, table, tabs, tree) over a real **engine**:
|
|
159
|
+
`field.py` (shader compositors), `raster.py` (sub-cell half/quad/braille pixels),
|
|
160
|
+
`box_junction.py` (edge-algebra box joins), `color_model.py` (honest truecolor → 256 →
|
|
161
|
+
16 → mono degrade). Display-cell accurate for CJK/emoji/ZWJ so columns never desync.
|
|
162
|
+
|
|
163
|
+
**`drive-tui`** (`skills/drive-tui`) — drives interactive terminal programs (REPLs,
|
|
164
|
+
menus, pagers, y/N prompts, wizards) through a PTY via a
|
|
165
|
+
perceive → decide → act → wait → confirm loop, never a blind sleep. A thin CLI
|
|
166
|
+
(`scripts/tui.py`) offers a persistent detached session and a one-shot `run` mode, with
|
|
167
|
+
an importable pattern library of **8 recipes** (repl, menu_select, pager, search_filter,
|
|
168
|
+
confirm, form, progress, wizard) that `classify()` a screen and `drive()` it.
|
|
169
|
+
|
|
170
|
+
**Shared core** (`smartcli_core`) — the pluggable PTY backend + `pyte` screen model +
|
|
171
|
+
semantic snapshot + readiness sync (`pty_backend / screen_model / snapshot / readiness /
|
|
172
|
+
session`). The reusable, importable foundation under all three skills.
|
|
173
|
+
|
|
174
|
+
**Knowledge graph** (`knowledge/`) — a 122-note wiki-link graph of exact rendering
|
|
175
|
+
formulas, ANSI sequences, and measured constants, each note carrying a source and
|
|
176
|
+
cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
|
|
177
|
+
|
|
178
|
+
## Project layout
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
SmartCLI/
|
|
182
|
+
smartcli_core/ shared PTY + pyte engine (importable package)
|
|
183
|
+
skills/cmd-art/ fx effect package and CLI (18 effects, 8 themes)
|
|
184
|
+
skills/drive-tui/ TUI pattern library and PTY driver CLI (8 recipes)
|
|
185
|
+
skills/tui-ui/ terminal UI layout engine and widgets (15 widgets)
|
|
186
|
+
tools/screenshot/ pyte -> PNG smoke-test harness
|
|
187
|
+
tools/agentcli/ agent-CLI control validation harness
|
|
188
|
+
knowledge/ 122-note knowledge graph (see knowledge/INDEX.md)
|
|
189
|
+
showcase/ rendered effect PNGs (see Screenshots)
|
|
190
|
+
tests/ direct script-style regressions
|
|
191
|
+
research/ archived first-pass research notes
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Documentation
|
|
195
|
+
|
|
196
|
+
- **[`README-USAGE.md`](README-USAGE.md)** — the full usage cheat-sheet: every skill,
|
|
197
|
+
the screenshot and AGENTCLI harnesses, and the regression commands.
|
|
198
|
+
- **[`knowledge/INDEX.md`](knowledge/INDEX.md)** — the 122-note knowledge graph.
|
|
199
|
+
- **[`AGENTCLI-VALIDATION.md`](AGENTCLI-VALIDATION.md)** — agent-CLI control test matrix.
|
|
200
|
+
- **[`CHANGELOG.md`](CHANGELOG.md)** — release history.
|
|
201
|
+
|
|
202
|
+
## License
|
|
203
|
+
|
|
204
|
+
MIT — see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# pyproject.toml — packaging metadata for SmartCLI.
|
|
2
|
+
#
|
|
3
|
+
# ---------------------------------------------------------------------------
|
|
4
|
+
# HONEST NOTE ON THE INSTALL TARGET (read before `pip install .`):
|
|
5
|
+
#
|
|
6
|
+
# This repo is a multi-skill workspace, not a single tidy importable package.
|
|
7
|
+
# The only clean top-level package is `smartcli_core/` (it has __init__.py and
|
|
8
|
+
# exports PtySession et al.). The three skills run IN PLACE via their own
|
|
9
|
+
# entry points — `python -m fx`, `python -m ui`, and
|
|
10
|
+
# `skills/drive-tui/scripts/tui.py` — with a sys.path insertion, and are NOT
|
|
11
|
+
# structured as installable packages under a single namespace.
|
|
12
|
+
#
|
|
13
|
+
# Therefore:
|
|
14
|
+
# * `pip install .` installs the shared core package (`smartcli_core`) plus
|
|
15
|
+
# its REQUIRED deps (pyte; pywinpty on Windows). That is real and works.
|
|
16
|
+
# * It does NOT relocate/install the skills — keep using them from the repo
|
|
17
|
+
# checkout as the SKILL.md / HANDOFF.md commands show.
|
|
18
|
+
# * The PRIMARY, fully-honest install path for reproducing the whole dev
|
|
19
|
+
# environment is: python -m pip install -r requirements.txt
|
|
20
|
+
# (plus requirements-optional.txt for the optional extras).
|
|
21
|
+
#
|
|
22
|
+
# Dependency floors are `>=` known-good baselines. Installed & VERIFIED on the
|
|
23
|
+
# dev box (Windows 11, CPython 3.14.6): pyte 0.8.2, pywinpty 3.0.5,
|
|
24
|
+
# pyfiglet 1.0.4, Pillow 12.2.0, wcwidth 0.8.1.
|
|
25
|
+
# ---------------------------------------------------------------------------
|
|
26
|
+
|
|
27
|
+
[build-system]
|
|
28
|
+
requires = ["setuptools>=61.0"]
|
|
29
|
+
build-backend = "setuptools.build_meta"
|
|
30
|
+
|
|
31
|
+
[project]
|
|
32
|
+
name = "smartcli-toolkit"
|
|
33
|
+
version = "0.1.0"
|
|
34
|
+
description = "Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core)."
|
|
35
|
+
readme = "README.md"
|
|
36
|
+
license = "MIT"
|
|
37
|
+
license-files = ["LICENSE"]
|
|
38
|
+
# Floor is the HONEST minimum: skills/tui-ui/ui/core.py evaluates a runtime
|
|
39
|
+
# `tuple[int, int, int]` subscription at import (PEP 585), which requires 3.9+.
|
|
40
|
+
# No match/case and no runtime `X | Y` types are used, so nothing forces higher.
|
|
41
|
+
requires-python = ">=3.9"
|
|
42
|
+
|
|
43
|
+
# REQUIRED runtime deps (mirror requirements.txt). pyte is a hard top-level
|
|
44
|
+
# import; pywinpty is imported only on the Windows PTY backend path, hence the
|
|
45
|
+
# environment marker. POSIX uses the stdlib `pty` backend (no extra package).
|
|
46
|
+
dependencies = [
|
|
47
|
+
"pyte>=0.8.1",
|
|
48
|
+
"pywinpty>=2.0; platform_system == 'Windows'",
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
[project.optional-dependencies]
|
|
52
|
+
# All guarded imports with pure-stdlib fallbacks — none required to run.
|
|
53
|
+
art = ["pyfiglet>=1.0.0"] # real FIGlet fonts (else built-in block font)
|
|
54
|
+
image = ["Pillow>=10.0.0"] # real raster images (else PNM/procedural demo)
|
|
55
|
+
width = ["wcwidth>=0.2.0"] # authoritative cell width (else unicodedata)
|
|
56
|
+
all = ["pyfiglet>=1.0.0", "Pillow>=10.0.0", "wcwidth>=0.2.0"]
|
|
57
|
+
|
|
58
|
+
[tool.setuptools]
|
|
59
|
+
# Only the shared core is a clean installable package (see HONEST NOTE above).
|
|
60
|
+
# The skills are intentionally left out — they run in place from the checkout.
|
|
61
|
+
packages = ["smartcli_core"]
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""SmartCLI shared core.
|
|
2
|
+
|
|
3
|
+
A pluggable-PTY + pyte screen model + semantic snapshot + readiness stack for
|
|
4
|
+
driving interactive terminal programs. Both SmartCLI skills build on this.
|
|
5
|
+
|
|
6
|
+
Quick start::
|
|
7
|
+
|
|
8
|
+
from smartcli_core import PtySession
|
|
9
|
+
|
|
10
|
+
with PtySession(cols=100, rows=30) as sess:
|
|
11
|
+
sess.start("python")
|
|
12
|
+
sess.wait_ready(marker=r">>> $")
|
|
13
|
+
sess.send_line("print('hello')")
|
|
14
|
+
reason, snap = sess.wait_ready(marker=r">>> $")
|
|
15
|
+
print(snap.to_text())
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from .pty_backend import (
|
|
21
|
+
PosixPtyBackend,
|
|
22
|
+
PtyBackend,
|
|
23
|
+
WinptyBackend,
|
|
24
|
+
get_default_backend,
|
|
25
|
+
)
|
|
26
|
+
from .readiness import wait_for_regex, wait_ready, wait_until_stable
|
|
27
|
+
from .screen_model import CellAttrs, ScreenModel
|
|
28
|
+
from .session import KEY_MAP, PtySession
|
|
29
|
+
from .snapshot import Snapshot, Span, build_snapshot
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
# backends
|
|
33
|
+
"PtyBackend",
|
|
34
|
+
"WinptyBackend",
|
|
35
|
+
"PosixPtyBackend",
|
|
36
|
+
"get_default_backend",
|
|
37
|
+
# screen
|
|
38
|
+
"ScreenModel",
|
|
39
|
+
"CellAttrs",
|
|
40
|
+
# snapshot
|
|
41
|
+
"Snapshot",
|
|
42
|
+
"Span",
|
|
43
|
+
"build_snapshot",
|
|
44
|
+
# readiness
|
|
45
|
+
"wait_until_stable",
|
|
46
|
+
"wait_for_regex",
|
|
47
|
+
"wait_ready",
|
|
48
|
+
# session
|
|
49
|
+
"PtySession",
|
|
50
|
+
"KEY_MAP",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
__version__ = "0.1.0"
|