amagi-democast 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.
- amagi_democast-0.1.0/LICENSE +21 -0
- amagi_democast-0.1.0/PKG-INFO +159 -0
- amagi_democast-0.1.0/README.md +136 -0
- amagi_democast-0.1.0/pyproject.toml +38 -0
- amagi_democast-0.1.0/setup.cfg +4 -0
- amagi_democast-0.1.0/src/amagi_democast/__init__.py +2 -0
- amagi_democast-0.1.0/src/amagi_democast/__main__.py +5 -0
- amagi_democast-0.1.0/src/amagi_democast/cli.py +208 -0
- amagi_democast-0.1.0/src/amagi_democast/readme.py +114 -0
- amagi_democast-0.1.0/src/amagi_democast/render.py +211 -0
- amagi_democast-0.1.0/src/amagi_democast/runner.py +69 -0
- amagi_democast-0.1.0/src/amagi_democast/sidecar.py +50 -0
- amagi_democast-0.1.0/src/amagi_democast.egg-info/PKG-INFO +159 -0
- amagi_democast-0.1.0/src/amagi_democast.egg-info/SOURCES.txt +19 -0
- amagi_democast-0.1.0/src/amagi_democast.egg-info/dependency_links.txt +1 -0
- amagi_democast-0.1.0/src/amagi_democast.egg-info/entry_points.txt +2 -0
- amagi_democast-0.1.0/src/amagi_democast.egg-info/requires.txt +4 -0
- amagi_democast-0.1.0/src/amagi_democast.egg-info/top_level.txt +1 -0
- amagi_democast-0.1.0/tests/test_cli.py +111 -0
- amagi_democast-0.1.0/tests/test_readme.py +73 -0
- amagi_democast-0.1.0/tests/test_runner.py +38 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs)
|
|
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,159 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: amagi-democast
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Turn the shell blocks in your README into a demo GIF from a real run, and fail CI when the tool's output no longer matches the GIF. Pillow only: no ffmpeg, ttyd, Go or Node.
|
|
5
|
+
Author-email: "AmagiLabs (Amagisolutionsgroup, Inc.)" <dev@amagisolutionsgroup.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/amagilabs/amagi-democast
|
|
8
|
+
Keywords: gif,demo,readme,terminal,cli,documentation,ci,screencast,claude-code
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Topic :: Documentation
|
|
14
|
+
Classifier: Topic :: Software Development :: Testing
|
|
15
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Requires-Dist: Pillow>=9.1
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# amagi-democast
|
|
25
|
+
|
|
26
|
+
Make the demo GIF in your README from a real run of the commands in it, then fail CI when the tool's output stops matching the GIF. Pillow is the only dependency.
|
|
27
|
+
|
|
28
|
+
A README demo GIF goes stale the moment you rename a flag or reword an error. Nobody notices, because nothing checks it. amagi-democast reads the commands from a code block you mark in your README, runs them, draws the real output as a terminal GIF, and saves what each command printed next to the GIF. `amagi-democast check` runs them again and exits `1` with a diff when the output, an exit code or the GIF itself has changed.
|
|
29
|
+
|
|
30
|
+

|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pipx install amagi-democast
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Python 3.9 or newer. The one dependency is Pillow. No ffmpeg, ttyd, Go or Node.
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
Put a `<!-- democast -->` comment on the line above a code block of commands. GitHub does not render the comment, so readers see a normal code block:
|
|
43
|
+
|
|
44
|
+
````markdown
|
|
45
|
+
<!-- democast -->
|
|
46
|
+
```console
|
|
47
|
+
$ mytool --help
|
|
48
|
+
$ mytool run example.txt
|
|
49
|
+
```
|
|
50
|
+
````
|
|
51
|
+
|
|
52
|
+
Then, from the folder with the README:
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
amagi-democast record # run the commands, write assets/demo.gif and assets/demo.democast.json
|
|
56
|
+
amagi-democast check # run them again; exit 1 if anything drifted
|
|
57
|
+
amagi-democast list # show the marked blocks and their commands
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The GIF at the top of this page was made by `amagi-democast record` from this block in this README:
|
|
61
|
+
|
|
62
|
+
<!-- democast -->
|
|
63
|
+
```console
|
|
64
|
+
$ amagi-democast list examples/greet
|
|
65
|
+
$ amagi-democast check examples/greet
|
|
66
|
+
$ amagi-democast check examples/drifted
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Real output of those three commands:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
$ amagi-democast list examples/greet
|
|
73
|
+
block 1 (line 7)
|
|
74
|
+
$ python greet.py Ada
|
|
75
|
+
$ python greet.py Ada --shout
|
|
76
|
+
$ python greet.py
|
|
77
|
+
|
|
78
|
+
$ amagi-democast check examples/greet
|
|
79
|
+
OK 3 commands in examples/greet/README.md still match examples/greet/assets/demo.gif
|
|
80
|
+
|
|
81
|
+
$ amagi-democast check examples/drifted
|
|
82
|
+
DRIFT the demo GIF no longer matches what the commands print (2 problems)
|
|
83
|
+
- step 1 `python greet.py Ada`: output changed
|
|
84
|
+
--- in the GIF
|
|
85
|
+
+++ now
|
|
86
|
+
@@ -1 +1 @@
|
|
87
|
+
-Hello, Ada!
|
|
88
|
+
+Hi there, Ada.
|
|
89
|
+
- step 2 `python greet.py Ada --shout`: output changed
|
|
90
|
+
--- in the GIF
|
|
91
|
+
+++ now
|
|
92
|
+
@@ -1 +1 @@
|
|
93
|
+
-HELLO, ADA!
|
|
94
|
+
+HI THERE, ADA.
|
|
95
|
+
Fix: run `amagi-democast record` and commit the new GIF, or revert the change.
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
`examples/drifted` is a copy of `examples/greet` that was recorded, after which its greeting was changed from `Hello, Ada!` to `Hi there, Ada.` without recording again. That is the stale-GIF case `check` exists to catch.
|
|
99
|
+
|
|
100
|
+
Exit codes: `0` everything matches, `1` drift (or no recording yet), `2` usage error, such as a README with no marked block.
|
|
101
|
+
|
|
102
|
+
## In CI
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
- run: pipx install amagi-democast
|
|
106
|
+
- run: amagi-democast check
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Run `check` on the same operating system you recorded on, since command output often differs between Windows and Linux.
|
|
110
|
+
|
|
111
|
+
## Options
|
|
112
|
+
|
|
113
|
+
| Option | What it does |
|
|
114
|
+
|---|---|
|
|
115
|
+
| `README` | Markdown file or folder to read (default `README.md`) |
|
|
116
|
+
| `-o, --output GIF` | Where the GIF goes (default `assets/demo.gif` next to the README). The sidecar is `<name>.democast.json` beside it. |
|
|
117
|
+
| `--ignore REGEX` | Text matching REGEX is treated as equal when checking, for timings, dates and temp paths. Repeatable. |
|
|
118
|
+
| `--timeout S` | Seconds each command may run (default 60). A timeout is shown in the GIF as exit code 124. |
|
|
119
|
+
| `--cols N` | Terminal width in characters (default 100). Long lines wrap. |
|
|
120
|
+
| `--rows N` | Terminal height for `record` (default: fit the output, 8 to 28 lines). Longer output scrolls. |
|
|
121
|
+
| `--theme dark\|light` | Colours for `record` |
|
|
122
|
+
| `--title TEXT` | Window title for `record` (default: the README's folder name) |
|
|
123
|
+
|
|
124
|
+
Per-block options go in the comment itself: `<!-- democast cwd=examples timeout=120 ignore="took [0-9.]+s" -->`. The `cwd` option is relative to the README.
|
|
125
|
+
|
|
126
|
+
## How it works
|
|
127
|
+
|
|
128
|
+
1. **Find.** Every fenced block with a `<!-- democast -->` comment above it, in order. In a block with `$ ` lines, those lines are the commands and the rest is treated as sample output. Otherwise every non-empty line that is not a `#` comment is a command. Several marked blocks make one GIF.
|
|
129
|
+
2. **Run.** Each command runs through your shell in the README's folder, with `NO_COLOR=1` and `TERM=dumb` so colour codes stay out. Stdout and stderr are both captured. A nonzero exit is shown in the GIF as `[exit code N]` and is not treated as a failure, because a demo often shows an error on purpose.
|
|
130
|
+
3. **Draw.** The command is typed out, the output appears, and the last frame holds. The font is Consolas, Menlo or DejaVu Sans Mono, whichever the machine has, or Pillow's built-in font if none is found. Frames are stored with their own durations, so pauses cost nothing.
|
|
131
|
+
4. **Save.** The sidecar JSON holds each command, its output with colour codes stripped, its exit code, and the GIF's SHA-256.
|
|
132
|
+
5. **Check.** `check` compares the README's commands with the sidecar, runs them again, and compares output and exit codes after normalising line endings and trailing spaces. It does not redraw the GIF, because fonts differ between machines. It checks the GIF file against the recorded hash instead.
|
|
133
|
+
|
|
134
|
+
## How it differs from vhs and asciinema
|
|
135
|
+
|
|
136
|
+
[vhs](https://github.com/charmbracelet/vhs) records a GIF from a `.tape` script you write, and needs ttyd and ffmpeg. [asciinema](https://asciinema.org) records a terminal session to its own cast format. Both make better-looking recordings. Neither tells you when a recording no longer matches the tool. amagi-democast takes its commands from the README itself and adds the `check` step, at the cost of a plainer animation: no real terminal emulator, no colours, no interactive programs.
|
|
137
|
+
|
|
138
|
+
## Limits
|
|
139
|
+
|
|
140
|
+
- Commands run with your current `PATH`, so install the tool or activate its venv before you record. `record` warns when a command is not found.
|
|
141
|
+
- Commands run without a terminal attached. Programs that need one (full-screen apps, prompts, progress bars that redraw) show their non-interactive output or hang until `--timeout`.
|
|
142
|
+
- Colour is stripped. The GIF is drawn in one foreground colour, with nonzero exit codes in red.
|
|
143
|
+
- Commands run through `cmd.exe` on Windows and `/bin/sh` elsewhere, so write the block for the shell you record on. The example uses `python`, which may be `python3` on Linux.
|
|
144
|
+
- `check` compares text, not pixels. Changing `--cols`, `--theme` or fonts does not count as drift until you record again.
|
|
145
|
+
|
|
146
|
+
## If this saved you time
|
|
147
|
+
|
|
148
|
+
A star helps other people find it.
|
|
149
|
+
|
|
150
|
+
## More from AmagiLabs
|
|
151
|
+
|
|
152
|
+
- [amagilabs](https://github.com/amagilabs): other small open source dev tools from the same lab.
|
|
153
|
+
- [amagi-hookguard](https://github.com/amagilabs/amagi-hookguard): Claude Code hooks that block `rm -rf ~`, force pushes and `.env` reads.
|
|
154
|
+
- [amagi-docleak](https://github.com/amagilabs/amagi-docleak): checks a file you are about to send for tracked changes, metadata and badly redacted text.
|
|
155
|
+
- [amagi-legal-review-skills](https://github.com/amagilabs/amagi-legal-review-skills): Claude Code skills for contract and lease review.
|
|
156
|
+
|
|
157
|
+
## License
|
|
158
|
+
|
|
159
|
+
MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs)
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# amagi-democast
|
|
2
|
+
|
|
3
|
+
Make the demo GIF in your README from a real run of the commands in it, then fail CI when the tool's output stops matching the GIF. Pillow is the only dependency.
|
|
4
|
+
|
|
5
|
+
A README demo GIF goes stale the moment you rename a flag or reword an error. Nobody notices, because nothing checks it. amagi-democast reads the commands from a code block you mark in your README, runs them, draws the real output as a terminal GIF, and saves what each command printed next to the GIF. `amagi-democast check` runs them again and exits `1` with a diff when the output, an exit code or the GIF itself has changed.
|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pipx install amagi-democast
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Python 3.9 or newer. The one dependency is Pillow. No ffmpeg, ttyd, Go or Node.
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
Put a `<!-- democast -->` comment on the line above a code block of commands. GitHub does not render the comment, so readers see a normal code block:
|
|
20
|
+
|
|
21
|
+
````markdown
|
|
22
|
+
<!-- democast -->
|
|
23
|
+
```console
|
|
24
|
+
$ mytool --help
|
|
25
|
+
$ mytool run example.txt
|
|
26
|
+
```
|
|
27
|
+
````
|
|
28
|
+
|
|
29
|
+
Then, from the folder with the README:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
amagi-democast record # run the commands, write assets/demo.gif and assets/demo.democast.json
|
|
33
|
+
amagi-democast check # run them again; exit 1 if anything drifted
|
|
34
|
+
amagi-democast list # show the marked blocks and their commands
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The GIF at the top of this page was made by `amagi-democast record` from this block in this README:
|
|
38
|
+
|
|
39
|
+
<!-- democast -->
|
|
40
|
+
```console
|
|
41
|
+
$ amagi-democast list examples/greet
|
|
42
|
+
$ amagi-democast check examples/greet
|
|
43
|
+
$ amagi-democast check examples/drifted
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Real output of those three commands:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
$ amagi-democast list examples/greet
|
|
50
|
+
block 1 (line 7)
|
|
51
|
+
$ python greet.py Ada
|
|
52
|
+
$ python greet.py Ada --shout
|
|
53
|
+
$ python greet.py
|
|
54
|
+
|
|
55
|
+
$ amagi-democast check examples/greet
|
|
56
|
+
OK 3 commands in examples/greet/README.md still match examples/greet/assets/demo.gif
|
|
57
|
+
|
|
58
|
+
$ amagi-democast check examples/drifted
|
|
59
|
+
DRIFT the demo GIF no longer matches what the commands print (2 problems)
|
|
60
|
+
- step 1 `python greet.py Ada`: output changed
|
|
61
|
+
--- in the GIF
|
|
62
|
+
+++ now
|
|
63
|
+
@@ -1 +1 @@
|
|
64
|
+
-Hello, Ada!
|
|
65
|
+
+Hi there, Ada.
|
|
66
|
+
- step 2 `python greet.py Ada --shout`: output changed
|
|
67
|
+
--- in the GIF
|
|
68
|
+
+++ now
|
|
69
|
+
@@ -1 +1 @@
|
|
70
|
+
-HELLO, ADA!
|
|
71
|
+
+HI THERE, ADA.
|
|
72
|
+
Fix: run `amagi-democast record` and commit the new GIF, or revert the change.
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`examples/drifted` is a copy of `examples/greet` that was recorded, after which its greeting was changed from `Hello, Ada!` to `Hi there, Ada.` without recording again. That is the stale-GIF case `check` exists to catch.
|
|
76
|
+
|
|
77
|
+
Exit codes: `0` everything matches, `1` drift (or no recording yet), `2` usage error, such as a README with no marked block.
|
|
78
|
+
|
|
79
|
+
## In CI
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
- run: pipx install amagi-democast
|
|
83
|
+
- run: amagi-democast check
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Run `check` on the same operating system you recorded on, since command output often differs between Windows and Linux.
|
|
87
|
+
|
|
88
|
+
## Options
|
|
89
|
+
|
|
90
|
+
| Option | What it does |
|
|
91
|
+
|---|---|
|
|
92
|
+
| `README` | Markdown file or folder to read (default `README.md`) |
|
|
93
|
+
| `-o, --output GIF` | Where the GIF goes (default `assets/demo.gif` next to the README). The sidecar is `<name>.democast.json` beside it. |
|
|
94
|
+
| `--ignore REGEX` | Text matching REGEX is treated as equal when checking, for timings, dates and temp paths. Repeatable. |
|
|
95
|
+
| `--timeout S` | Seconds each command may run (default 60). A timeout is shown in the GIF as exit code 124. |
|
|
96
|
+
| `--cols N` | Terminal width in characters (default 100). Long lines wrap. |
|
|
97
|
+
| `--rows N` | Terminal height for `record` (default: fit the output, 8 to 28 lines). Longer output scrolls. |
|
|
98
|
+
| `--theme dark\|light` | Colours for `record` |
|
|
99
|
+
| `--title TEXT` | Window title for `record` (default: the README's folder name) |
|
|
100
|
+
|
|
101
|
+
Per-block options go in the comment itself: `<!-- democast cwd=examples timeout=120 ignore="took [0-9.]+s" -->`. The `cwd` option is relative to the README.
|
|
102
|
+
|
|
103
|
+
## How it works
|
|
104
|
+
|
|
105
|
+
1. **Find.** Every fenced block with a `<!-- democast -->` comment above it, in order. In a block with `$ ` lines, those lines are the commands and the rest is treated as sample output. Otherwise every non-empty line that is not a `#` comment is a command. Several marked blocks make one GIF.
|
|
106
|
+
2. **Run.** Each command runs through your shell in the README's folder, with `NO_COLOR=1` and `TERM=dumb` so colour codes stay out. Stdout and stderr are both captured. A nonzero exit is shown in the GIF as `[exit code N]` and is not treated as a failure, because a demo often shows an error on purpose.
|
|
107
|
+
3. **Draw.** The command is typed out, the output appears, and the last frame holds. The font is Consolas, Menlo or DejaVu Sans Mono, whichever the machine has, or Pillow's built-in font if none is found. Frames are stored with their own durations, so pauses cost nothing.
|
|
108
|
+
4. **Save.** The sidecar JSON holds each command, its output with colour codes stripped, its exit code, and the GIF's SHA-256.
|
|
109
|
+
5. **Check.** `check` compares the README's commands with the sidecar, runs them again, and compares output and exit codes after normalising line endings and trailing spaces. It does not redraw the GIF, because fonts differ between machines. It checks the GIF file against the recorded hash instead.
|
|
110
|
+
|
|
111
|
+
## How it differs from vhs and asciinema
|
|
112
|
+
|
|
113
|
+
[vhs](https://github.com/charmbracelet/vhs) records a GIF from a `.tape` script you write, and needs ttyd and ffmpeg. [asciinema](https://asciinema.org) records a terminal session to its own cast format. Both make better-looking recordings. Neither tells you when a recording no longer matches the tool. amagi-democast takes its commands from the README itself and adds the `check` step, at the cost of a plainer animation: no real terminal emulator, no colours, no interactive programs.
|
|
114
|
+
|
|
115
|
+
## Limits
|
|
116
|
+
|
|
117
|
+
- Commands run with your current `PATH`, so install the tool or activate its venv before you record. `record` warns when a command is not found.
|
|
118
|
+
- Commands run without a terminal attached. Programs that need one (full-screen apps, prompts, progress bars that redraw) show their non-interactive output or hang until `--timeout`.
|
|
119
|
+
- Colour is stripped. The GIF is drawn in one foreground colour, with nonzero exit codes in red.
|
|
120
|
+
- Commands run through `cmd.exe` on Windows and `/bin/sh` elsewhere, so write the block for the shell you record on. The example uses `python`, which may be `python3` on Linux.
|
|
121
|
+
- `check` compares text, not pixels. Changing `--cols`, `--theme` or fonts does not count as drift until you record again.
|
|
122
|
+
|
|
123
|
+
## If this saved you time
|
|
124
|
+
|
|
125
|
+
A star helps other people find it.
|
|
126
|
+
|
|
127
|
+
## More from AmagiLabs
|
|
128
|
+
|
|
129
|
+
- [amagilabs](https://github.com/amagilabs): other small open source dev tools from the same lab.
|
|
130
|
+
- [amagi-hookguard](https://github.com/amagilabs/amagi-hookguard): Claude Code hooks that block `rm -rf ~`, force pushes and `.env` reads.
|
|
131
|
+
- [amagi-docleak](https://github.com/amagilabs/amagi-docleak): checks a file you are about to send for tracked changes, metadata and badly redacted text.
|
|
132
|
+
- [amagi-legal-review-skills](https://github.com/amagilabs/amagi-legal-review-skills): Claude Code skills for contract and lease review.
|
|
133
|
+
|
|
134
|
+
## License
|
|
135
|
+
|
|
136
|
+
MIT, see [LICENSE](LICENSE). Copyright (c) 2026 Amagisolutionsgroup, Inc. (AmagiLabs)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "amagi-democast"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Turn the shell blocks in your README into a demo GIF from a real run, and fail CI when the tool's output no longer matches the GIF. Pillow only: no ffmpeg, ttyd, Go or Node."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
authors = [{ name = "AmagiLabs (Amagisolutionsgroup, Inc.)", email = "dev@amagisolutionsgroup.com" }]
|
|
12
|
+
requires-python = ">=3.9"
|
|
13
|
+
dependencies = ["Pillow>=9.1"]
|
|
14
|
+
keywords = ["gif", "demo", "readme", "terminal", "cli", "documentation", "ci", "screencast", "claude-code"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Environment :: Console",
|
|
20
|
+
"Topic :: Documentation",
|
|
21
|
+
"Topic :: Software Development :: Testing",
|
|
22
|
+
"Topic :: Multimedia :: Graphics",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Homepage = "https://github.com/amagilabs/amagi-democast"
|
|
27
|
+
|
|
28
|
+
[project.scripts]
|
|
29
|
+
amagi-democast = "amagi_democast.cli:main"
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
dev = ["pytest>=7.0"]
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["src"]
|
|
36
|
+
|
|
37
|
+
[tool.pytest.ini_options]
|
|
38
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
"""amagi-democast record | check | list"""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import argparse
|
|
5
|
+
import difflib
|
|
6
|
+
import os
|
|
7
|
+
import re
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import List, Optional, Tuple
|
|
11
|
+
|
|
12
|
+
from . import __version__, readme, render, runner, sidecar
|
|
13
|
+
|
|
14
|
+
DEFAULT_GIF = "assets/demo.gif"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _slash(p: Path) -> str:
|
|
18
|
+
try:
|
|
19
|
+
p = p.resolve().relative_to(Path.cwd().resolve())
|
|
20
|
+
except ValueError:
|
|
21
|
+
p = p.resolve()
|
|
22
|
+
return p.as_posix()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _load(readme_arg: str) -> Tuple[Path, List[readme.Block]]:
|
|
26
|
+
path = Path(readme_arg)
|
|
27
|
+
if path.is_dir():
|
|
28
|
+
path = path / "README.md"
|
|
29
|
+
if not path.is_file():
|
|
30
|
+
raise readme.ReadmeError(f"{readme_arg}: no such file")
|
|
31
|
+
blocks = readme.parse(path.read_text(encoding="utf-8"))
|
|
32
|
+
if not blocks:
|
|
33
|
+
raise readme.ReadmeError(f"{_slash(path)}: no <!-- democast --> block found. Put the comment on the line "
|
|
34
|
+
"above a fenced code block of commands.")
|
|
35
|
+
return path, blocks
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _steps(blocks: List[readme.Block], extra_ignore: List[str], timeout: float):
|
|
39
|
+
for b in blocks:
|
|
40
|
+
for cmd in b.commands:
|
|
41
|
+
yield cmd, b.cwd, (b.timeout or timeout), b.ignore + extra_ignore
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _gif_path(md: Path, out: Optional[str]) -> Path:
|
|
45
|
+
return Path(out) if out else md.parent / DEFAULT_GIF
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _run_all(md: Path, blocks, args, verbose: bool) -> Tuple[List[runner.Run], List[List[str]]]:
|
|
49
|
+
runs, ignores = [], []
|
|
50
|
+
for cmd, cwd, timeout, ignore in _steps(blocks, args.ignore, args.timeout):
|
|
51
|
+
if verbose:
|
|
52
|
+
print(f"running: {cmd}", file=sys.stderr)
|
|
53
|
+
runs.append(runner.run_command(cmd, md.parent, cwd, timeout, args.cols))
|
|
54
|
+
ignores.append(ignore)
|
|
55
|
+
return runs, ignores
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def cmd_record(args) -> int:
|
|
59
|
+
md, blocks = _load(args.readme)
|
|
60
|
+
gif = _gif_path(md, args.output)
|
|
61
|
+
runs, _ = _run_all(md, blocks, args, verbose=not args.quiet)
|
|
62
|
+
needed = 1 + sum(2 + len(render.wrap(r.output, args.cols) if r.output else []) + (r.exit_code != 0)
|
|
63
|
+
for r in runs)
|
|
64
|
+
rows = args.rows if args.rows else min(28, max(8, needed))
|
|
65
|
+
term = render.Terminal(args.cols, rows, args.theme, title=args.title if args.title is not None
|
|
66
|
+
else md.resolve().parent.name)
|
|
67
|
+
for r in runs:
|
|
68
|
+
term.type_command(r.command)
|
|
69
|
+
term.show_output(r.output, r.exit_code)
|
|
70
|
+
term.finish()
|
|
71
|
+
size = term.save(gif, args.max_bytes)
|
|
72
|
+
rel = os.path.relpath(md.resolve(), gif.resolve().parent).replace(os.sep, "/")
|
|
73
|
+
side = sidecar.write(gif, rel, runs, args.cols, rows, args.theme)
|
|
74
|
+
failed = sum(1 for r in runs if r.exit_code != 0)
|
|
75
|
+
note = f", {failed} exited nonzero (shown in the GIF)" if failed else ""
|
|
76
|
+
print(f"recorded {len(runs)} command{'s' if len(runs) != 1 else ''} from {_slash(md)}{note}")
|
|
77
|
+
print(f" {_slash(gif)} {size // 1024} KB, {render.frame_count(gif)} frames, {args.cols}x{rows}")
|
|
78
|
+
print(f" {_slash(side)}")
|
|
79
|
+
for r in runs:
|
|
80
|
+
if r.exit_code in (127, 9009) or "is not recognized as an internal or external command" in r.output:
|
|
81
|
+
print(f"warning: `{r.command}` was not found. Is the tool installed, or its venv activated?",
|
|
82
|
+
file=sys.stderr)
|
|
83
|
+
return 0
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def cmd_check(args) -> int:
|
|
87
|
+
md, blocks = _load(args.readme)
|
|
88
|
+
gif = _gif_path(md, args.output)
|
|
89
|
+
side_path = sidecar.sidecar_path(gif)
|
|
90
|
+
if not gif.is_file() or not side_path.is_file():
|
|
91
|
+
missing = _slash(gif) if not gif.is_file() else _slash(side_path)
|
|
92
|
+
print(f"DRIFT {missing} is missing. Run: amagi-democast record {args.readme}")
|
|
93
|
+
return 1
|
|
94
|
+
try:
|
|
95
|
+
doc = sidecar.read(gif)
|
|
96
|
+
except ValueError as e:
|
|
97
|
+
print(f"amagi-democast: {e}", file=sys.stderr)
|
|
98
|
+
return 2
|
|
99
|
+
problems: List[str] = []
|
|
100
|
+
if sidecar.sha256_file(gif) != doc.get("gif_sha256"):
|
|
101
|
+
problems.append(f"{_slash(gif)} changed since it was recorded (hash differs from the sidecar)")
|
|
102
|
+
|
|
103
|
+
wanted = [s[0] for s in _steps(blocks, args.ignore, args.timeout)]
|
|
104
|
+
recorded = [s.get("command") for s in doc["steps"]]
|
|
105
|
+
if wanted != recorded:
|
|
106
|
+
problems.append("the README commands changed since the GIF was recorded:\n" + "\n".join(
|
|
107
|
+
" " + ln for ln in difflib.unified_diff(recorded, wanted, "recorded", "README", lineterm="", n=0)
|
|
108
|
+
if not ln.startswith("@@")))
|
|
109
|
+
_report(problems)
|
|
110
|
+
return 1
|
|
111
|
+
|
|
112
|
+
runs, ignores = _run_all(md, blocks, args, verbose=False)
|
|
113
|
+
for i, (run, old, ignore) in enumerate(zip(runs, doc["steps"], ignores), 1):
|
|
114
|
+
before = runner.normalise(old.get("output", ""), ignore)
|
|
115
|
+
after = runner.normalise(run.output, ignore)
|
|
116
|
+
head = f"step {i} `{run.command}`"
|
|
117
|
+
if old.get("exit_code") != run.exit_code:
|
|
118
|
+
problems.append(f"{head}: exit code {old.get('exit_code')} -> {run.exit_code}")
|
|
119
|
+
if before != after:
|
|
120
|
+
diff = difflib.unified_diff(before.split("\n"), after.split("\n"), "in the GIF", "now", lineterm="", n=1)
|
|
121
|
+
problems.append(f"{head}: output changed\n" + "\n".join(" " + ln for ln in diff))
|
|
122
|
+
if problems:
|
|
123
|
+
_report(problems)
|
|
124
|
+
return 1
|
|
125
|
+
print(f"OK {len(runs)} command{'s' if len(runs) != 1 else ''} in {_slash(md)} still match {_slash(gif)}")
|
|
126
|
+
return 0
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _report(problems: List[str]) -> None:
|
|
130
|
+
print(f"DRIFT the demo GIF no longer matches what the commands print ({len(problems)} "
|
|
131
|
+
f"problem{'s' if len(problems) != 1 else ''})")
|
|
132
|
+
for p in problems:
|
|
133
|
+
print(" - " + p)
|
|
134
|
+
print("Fix: run `amagi-democast record` and commit the new GIF, or revert the change.")
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def cmd_list(args) -> int:
|
|
138
|
+
md, blocks = _load(args.readme)
|
|
139
|
+
for n, b in enumerate(blocks, 1):
|
|
140
|
+
opts = []
|
|
141
|
+
if b.cwd:
|
|
142
|
+
opts.append(f"cwd={b.cwd}")
|
|
143
|
+
if b.timeout:
|
|
144
|
+
opts.append(f"timeout={b.timeout:g}")
|
|
145
|
+
opts += [f"ignore={x}" for x in b.ignore]
|
|
146
|
+
print(f"block {n} (line {b.line}){' ' + ' '.join(opts) if opts else ''}")
|
|
147
|
+
for c in b.commands:
|
|
148
|
+
print(f" $ {c}")
|
|
149
|
+
return 0
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
153
|
+
p = argparse.ArgumentParser(
|
|
154
|
+
prog="amagi-democast",
|
|
155
|
+
description="Record the commands in a README's marked code block into a terminal GIF, "
|
|
156
|
+
"and fail CI when the real output drifts from the GIF.")
|
|
157
|
+
p.add_argument("--version", action="version", version=f"amagi-democast {__version__}")
|
|
158
|
+
sub = p.add_subparsers(dest="command", metavar="{record,check,list}")
|
|
159
|
+
|
|
160
|
+
def common(sp, run=True):
|
|
161
|
+
sp.add_argument("readme", nargs="?", default="README.md", help="Markdown file or folder (default README.md)")
|
|
162
|
+
if run:
|
|
163
|
+
sp.add_argument("-o", "--output", metavar="GIF", help=f"GIF path (default: {DEFAULT_GIF} next to the README)")
|
|
164
|
+
sp.add_argument("--timeout", type=float, default=60.0, metavar="S", help="seconds per command (default 60)")
|
|
165
|
+
sp.add_argument("--ignore", action="append", default=[], metavar="REGEX",
|
|
166
|
+
help="treat text matching REGEX as equal when checking (timings, paths); repeatable")
|
|
167
|
+
sp.add_argument("--cols", type=int, default=100, help="terminal width in characters (default 100)")
|
|
168
|
+
|
|
169
|
+
r = sub.add_parser("record", help="run the commands and write the GIF plus its .democast.json sidecar")
|
|
170
|
+
common(r)
|
|
171
|
+
r.add_argument("--rows", type=int, default=0, help="terminal height in lines (default: fit the output, 8 to 28)")
|
|
172
|
+
r.add_argument("--theme", choices=sorted(render.THEMES), default="dark")
|
|
173
|
+
r.add_argument("--title", default=None, help="window title (default: the README's folder name)")
|
|
174
|
+
r.add_argument("--max-bytes", type=int, default=2_000_000, help="shrink the GIF above this size (default 2 MB)")
|
|
175
|
+
r.add_argument("-q", "--quiet", action="store_true", help="do not print each command as it runs")
|
|
176
|
+
c = sub.add_parser("check", help="re-run the commands; exit 1 if output, exit codes or the GIF changed")
|
|
177
|
+
common(c)
|
|
178
|
+
ls = sub.add_parser("list", help="show the marked blocks and their commands")
|
|
179
|
+
common(ls, run=False)
|
|
180
|
+
return p
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def main(argv: Optional[List[str]] = None) -> int:
|
|
184
|
+
parser = build_parser()
|
|
185
|
+
try:
|
|
186
|
+
args = parser.parse_args(argv)
|
|
187
|
+
except SystemExit as e:
|
|
188
|
+
return 0 if e.code == 0 else 2
|
|
189
|
+
if not args.command:
|
|
190
|
+
parser.print_help()
|
|
191
|
+
return 2
|
|
192
|
+
rows = getattr(args, "rows", 0)
|
|
193
|
+
if getattr(args, "cols", 100) < 20 or (rows != 0 and rows < 5) or getattr(args, "timeout", 1) <= 0:
|
|
194
|
+
print("amagi-democast: --cols must be >= 20, --rows >= 5, --timeout > 0", file=sys.stderr)
|
|
195
|
+
return 2
|
|
196
|
+
try:
|
|
197
|
+
for rx in getattr(args, "ignore", []):
|
|
198
|
+
re.compile(rx)
|
|
199
|
+
return {"record": cmd_record, "check": cmd_check, "list": cmd_list}[args.command](args)
|
|
200
|
+
except readme.ReadmeError as e:
|
|
201
|
+
print(f"amagi-democast: {e}", file=sys.stderr)
|
|
202
|
+
return 2
|
|
203
|
+
except re.error as e:
|
|
204
|
+
print(f"amagi-democast: bad --ignore regex: {e}", file=sys.stderr)
|
|
205
|
+
return 2
|
|
206
|
+
except FileNotFoundError as e:
|
|
207
|
+
print(f"amagi-democast: {e}", file=sys.stderr)
|
|
208
|
+
return 2
|