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.
@@ -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
+ ![demo](assets/demo.gif)
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
+ ![demo](assets/demo.gif)
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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,2 @@
1
+ """amagi-democast: record a README's demo commands into a GIF, then fail CI when they drift."""
2
+ __version__ = "0.1.0"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
@@ -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