zoetty 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.
Files changed (67) hide show
  1. zoetty-0.1.0/.github/workflows/ci.yml +62 -0
  2. zoetty-0.1.0/.gitignore +17 -0
  3. zoetty-0.1.0/.python-version +1 -0
  4. zoetty-0.1.0/CHANGELOG.md +11 -0
  5. zoetty-0.1.0/CLAUDE.md +9 -0
  6. zoetty-0.1.0/CODE_OF_CONDUCT.md +32 -0
  7. zoetty-0.1.0/CONTRIBUTING.md +144 -0
  8. zoetty-0.1.0/CONTRIBUTORS.md +3 -0
  9. zoetty-0.1.0/LICENSE +21 -0
  10. zoetty-0.1.0/Makefile +46 -0
  11. zoetty-0.1.0/PKG-INFO +145 -0
  12. zoetty-0.1.0/PUBLISHING.md +147 -0
  13. zoetty-0.1.0/README.md +124 -0
  14. zoetty-0.1.0/SECURITY.md +11 -0
  15. zoetty-0.1.0/docs/CHANGELOG.md +11 -0
  16. zoetty-0.1.0/docs/agents.md +54 -0
  17. zoetty-0.1.0/docs/cli.md +63 -0
  18. zoetty-0.1.0/docs/clip-format.md +134 -0
  19. zoetty-0.1.0/docs/clips/captures/quickstart-build.ansi +1 -0
  20. zoetty-0.1.0/docs/clips/captures/quickstart-check.ansi +1 -0
  21. zoetty-0.1.0/docs/clips/captures/quickstart-init.ansi +2 -0
  22. zoetty-0.1.0/docs/clips/captures/repl.ansi +6 -0
  23. zoetty-0.1.0/docs/clips/captures/zen.ansi +21 -0
  24. zoetty-0.1.0/docs/clips/hello.html +32 -0
  25. zoetty-0.1.0/docs/clips/hello.svg +42 -0
  26. zoetty-0.1.0/docs/clips/hello.toml +13 -0
  27. zoetty-0.1.0/docs/clips/quickstart.html +37 -0
  28. zoetty-0.1.0/docs/clips/quickstart.svg +55 -0
  29. zoetty-0.1.0/docs/clips/quickstart.toml +24 -0
  30. zoetty-0.1.0/docs/clips/repl.html +33 -0
  31. zoetty-0.1.0/docs/clips/repl.svg +47 -0
  32. zoetty-0.1.0/docs/clips/repl.toml +20 -0
  33. zoetty-0.1.0/docs/clips/steps.html +61 -0
  34. zoetty-0.1.0/docs/clips/steps.svg +125 -0
  35. zoetty-0.1.0/docs/clips/steps.toml +94 -0
  36. zoetty-0.1.0/docs/clips/zen.html +48 -0
  37. zoetty-0.1.0/docs/clips/zen.svg +92 -0
  38. zoetty-0.1.0/docs/clips/zen.toml +23 -0
  39. zoetty-0.1.0/docs/embedding.md +82 -0
  40. zoetty-0.1.0/docs/examples.md +65 -0
  41. zoetty-0.1.0/docs/index.md +69 -0
  42. zoetty-0.1.0/docs/install.md +33 -0
  43. zoetty-0.1.0/mkdocs.yml +53 -0
  44. zoetty-0.1.0/pyproject.toml +145 -0
  45. zoetty-0.1.0/specs/SPEC.md +154 -0
  46. zoetty-0.1.0/tasks/plan.md +46 -0
  47. zoetty-0.1.0/tasks/todo.md +77 -0
  48. zoetty-0.1.0/tests/conftest.py +23 -0
  49. zoetty-0.1.0/tests/test_ansi.py +64 -0
  50. zoetty-0.1.0/tests/test_cli.py +148 -0
  51. zoetty-0.1.0/tests/test_clip.py +224 -0
  52. zoetty-0.1.0/tests/test_docs.py +68 -0
  53. zoetty-0.1.0/tests/test_markup.py +51 -0
  54. zoetty-0.1.0/tests/test_record.py +84 -0
  55. zoetty-0.1.0/tests/test_render.py +120 -0
  56. zoetty-0.1.0/tests/test_timeline.py +153 -0
  57. zoetty-0.1.0/uv.lock +1257 -0
  58. zoetty-0.1.0/zoetty/__init__.py +0 -0
  59. zoetty-0.1.0/zoetty/ansi.py +70 -0
  60. zoetty-0.1.0/zoetty/cli.py +173 -0
  61. zoetty-0.1.0/zoetty/clip.py +272 -0
  62. zoetty-0.1.0/zoetty/html.py +91 -0
  63. zoetty-0.1.0/zoetty/markup.py +91 -0
  64. zoetty-0.1.0/zoetty/record.py +130 -0
  65. zoetty-0.1.0/zoetty/settings.py +3 -0
  66. zoetty-0.1.0/zoetty/svg.py +141 -0
  67. zoetty-0.1.0/zoetty/timeline.py +128 -0
@@ -0,0 +1,62 @@
1
+ name: CI - Lint and Test
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ build:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ matrix:
14
+ python-version: ["3.12", "3.13", "3.14", "3.15-dev"]
15
+ steps:
16
+ #----------------------------------------------
17
+ # check-out repo and set-up python
18
+ #----------------------------------------------
19
+ - name: Check out repository
20
+ uses: actions/checkout@v7
21
+ - name: Set up python
22
+ id: setup-python
23
+ uses: actions/setup-python@v7
24
+ with:
25
+ python-version: ${{matrix.python-version}}
26
+ #----------------------------------------------
27
+ # ----- install & configure uv -----
28
+ #----------------------------------------------
29
+ # Pointing uv at the interpreter setup-python installed overrides .python-version,
30
+ # which would otherwise make every matrix entry run on 3.14.
31
+ - name: Install UV
32
+ uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
33
+ with:
34
+ python-version: ${{ steps.setup-python.outputs.python-path }}
35
+ enable-cache: true
36
+ cache-dependency-glob: "uv.lock"
37
+
38
+ #----------------------------------------------
39
+ # install dependencies
40
+ #----------------------------------------------
41
+ - name: Install dependencies
42
+ run: uv sync --frozen
43
+ - name: Show Python version
44
+ run: uv run python --version
45
+ #----------------------------------------------
46
+ # Run linting and tests
47
+ #----------------------------------------------
48
+ - name: Ruff format check
49
+ run: |
50
+ uv run ruff format --check .
51
+ - name: Ruff linting
52
+ run: |
53
+ uv run ruff check .
54
+ - name: Type check with ty
55
+ run: |
56
+ uv run ty check
57
+ - name: Check import contracts
58
+ run: |
59
+ make lint-imports
60
+ - name: Test with pytest
61
+ run: |
62
+ uv run pytest -vv --cov=zoetty --cov-branch --cov-report=term-missing --cov-config=pyproject.toml
@@ -0,0 +1,17 @@
1
+ .venv/
2
+ .ty_cache/
3
+ .ruff_cache/
4
+ .import_linter_cache/
5
+ .pytest_cache/
6
+ .idea/
7
+ __pycache__
8
+ .DS_Store
9
+ dist/
10
+ site/
11
+ htmlcov/
12
+ *.coverage*
13
+ coverage.xml
14
+ .cache/
15
+
16
+ # Transcripts written by releasing zoetty with PUBLISHING.md
17
+ /logs/
@@ -0,0 +1 @@
1
+ 3.14
@@ -0,0 +1,11 @@
1
+ # Change log
2
+
3
+ ## 0.1.0
4
+
5
+ The first release.
6
+
7
+ - `zoetty init`, `record`, `build` and `check`.
8
+ - Clip specs in TOML: `[[run]]` sessions with recorded or hand-written output, or hand-timed `[[step]]`s.
9
+ - `zoetty record` runs commands in a pseudo-terminal the size of the clip, keeps their colours, types `input` after each prompt and ends with Ctrl-D.
10
+ - SVG output for READMEs and anywhere that takes images; HTML fragments for docs sites, safe to put several on one page.
11
+ - Long output wraps at `cols` and scrolls past `rows`. `[theme]` colours, optional window chrome, and reduced-motion support.
zoetty-0.1.0/CLAUDE.md ADDED
@@ -0,0 +1,9 @@
1
+ # CLAUDE.md
2
+
3
+ ## Workflow
4
+
5
+ ### Workflow for planned tasks
6
+
7
+ 1. Read the plan, spec and todos, then present a short plan. STOP and wait for my approval.
8
+ 2. Implement test-first in red-green slices. Keep 100% line and branch coverage.
9
+ 3. Only tick checkboxes or approval boxes when I say so, or after CI is confirmed green.
@@ -0,0 +1,32 @@
1
+ # paulrun Code of Conduct
2
+
3
+ Like the technical community as a whole, the paulrun team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
4
+
5
+ Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
6
+
7
+ This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
8
+
9
+ This code of conduct applies to all spaces managed by the paulrun project or Paul Hallett. This includes the issue tracker, pull requests, discussions, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
10
+
11
+ If you believe someone is violating the code of conduct, we ask that you report it by emailing [paulandrewhallett@gmail.com](mailto:paulandrewhallett@gmail.com).
12
+
13
+ - **Be friendly and patient.**
14
+ - **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
15
+ - **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
16
+ - **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the paulrun community should be respectful when dealing with other members as well as with people outside the paulrun community.
17
+ - **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
18
+ - Violent threats or language directed against another person.
19
+ - Discriminatory jokes and language.
20
+ - Posting sexually explicit or violent material.
21
+ - Posting (or threatening to post) other people's personally identifying information ("doxing").
22
+ - Personal insults, especially those using racist or sexist terms.
23
+ - Unwelcome sexual attention.
24
+ - Advocating for, or encouraging, any of the above behavior.
25
+ - Repeated harassment of others. In general, if someone asks you to stop, then stop.
26
+ - **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and paulrun is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of paulrun comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
27
+
28
+ Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html).
29
+
30
+ ## Questions?
31
+
32
+ If you have questions, please see [CONTRIBUTING.md](CONTRIBUTING.md). If that doesn't answer your questions, feel free to [contact us](mailto:paulandrewhallett@gmail.com).
@@ -0,0 +1,144 @@
1
+ # Contributing
2
+
3
+ First things first: thank you for contributing! This project will be successful thanks to everyone who contributes, and we're happy to have you.
4
+
5
+ ## AI disclosure
6
+
7
+ Within zoetty we use coding agents to prototype and build out ideas, and then take the idea to fruition using human reviewed and approved code.
8
+
9
+ You, the human and the author of changes are responsible for the contributions, and if you cannot confidently explain or demonstrate understanding of the changes you are contributing, then they will not be accepted.
10
+
11
+ ## Bug or issue?
12
+
13
+ To raise a bug or issue please use [our GitHub](https://github.com/phalt/zoetty/issues).
14
+
15
+ Please check the issue has not been raised before by using the search feature.
16
+
17
+ When submitting an issue or bug, please make sure you provide thorough detail on:
18
+
19
+ 1. The version of zoetty you are using (`zoetty --version`)
20
+ 2. Your operating system and Python version
21
+ 3. Any errors or outputs you see in your terminal
22
+ 4. The smallest clip spec (and capture file, if there is one) that shows the problem. Take out any secrets first!
23
+
24
+ ## Contribution
25
+
26
+ If you want to directly contribute you can do so in two ways:
27
+
28
+ 1. Documentation
29
+ 2. Code
30
+
31
+ ### Documentation
32
+
33
+ We use [mkdocs](https://www.mkdocs.org/) and [GitHub pages](https://pages.github.com/) to deploy our docs.
34
+
35
+ Fixing grammar, spelling mistakes, or expanding the documentation to cover features that are not yet documented, are all valuable contributions.
36
+
37
+ Please see the **Set up** instructions below to run the docs locally on your computer, then:
38
+
39
+ ```sh
40
+ make docs-serve
41
+ ```
42
+
43
+ The examples in the docs and the README are tested, so if you change one, run `make test` too.
44
+
45
+ ### Code
46
+
47
+ Contribution by writing code for new features, or fixing bugs, is a great way to contribute to the project.
48
+
49
+ Please [open an issue](https://github.com/phalt/zoetty/issues) to talk it through before changing the clip spec format (keys, markup or what `record` does), adding a command or flag, adding JavaScript to an output, or adding a dependency. These are hard to change once people's clips rely on them.
50
+
51
+ #### Set up
52
+
53
+ Clone the repo:
54
+
55
+ ```sh
56
+ git clone git@github.com:phalt/zoetty.git
57
+ cd zoetty
58
+ ```
59
+
60
+ Move to a feature branch:
61
+
62
+ ```sh
63
+ git switch -c my-branch-name
64
+ ```
65
+
66
+ Install UV (if not already installed):
67
+
68
+ ```sh
69
+ # On macOS and Linux:
70
+ curl -LsSf https://astral.sh/uv/install.sh | sh
71
+
72
+ # Or using pip:
73
+ pip install uv
74
+ ```
75
+
76
+ Install all the dependencies:
77
+
78
+ ```sh
79
+ make install
80
+ ```
81
+
82
+ This will use UV to create a virtual environment and install all dependencies, including zoetty itself. UV handles the virtual environment automatically, so you don't need to manually activate it.
83
+
84
+ To make sure you have things set up correctly, please run the tests:
85
+
86
+ ```sh
87
+ make test
88
+ ```
89
+
90
+ You can run your copy of zoetty with `uv run zoetty`, e.g. to rebuild the docs clips:
91
+
92
+ ```sh
93
+ uv run zoetty build docs/clips/*.toml
94
+ ```
95
+
96
+ Run `make help` to see every command.
97
+
98
+ ### Preparing changes for review
99
+
100
+ Once you've made changes, here's a good checklist to run through before publishing for review:
101
+
102
+ Format and lint the code:
103
+
104
+ ```sh
105
+ make format
106
+ ```
107
+
108
+ Check the types:
109
+
110
+ ```sh
111
+ make ty
112
+ ```
113
+
114
+ Check the import contracts:
115
+
116
+ ```sh
117
+ make lint-imports
118
+ ```
119
+
120
+ [Import Linter](https://import-linter.readthedocs.io/) checks that modules only import in the directions we want: `zoetty.cli` sits on top and wires everything together, the renderers never import each other or the recorder, and only the CLI uses `click` and `rich`. The contracts, and the reasons for them, are under `[tool.importlinter]` in `pyproject.toml`. If one breaks, change the import rather than the contract.
121
+
122
+ Run the tests:
123
+
124
+ ```sh
125
+ make test
126
+ ```
127
+
128
+ New behaviour needs tests, and coverage stays at 100%. A new spec feature also gets an example in `docs/clips/` and on `docs/examples.md`.
129
+
130
+ If you've changed how clips are written or built, update `docs/clip-format.md` or `docs/cli.md` to match. If a change alters what zoetty draws, rebuild the docs clips with `uv run zoetty build docs/clips/*.toml`; a test fails if they're stale.
131
+
132
+ Make sure you add to `CHANGELOG.md` and `docs/CHANGELOG.md` what changes you have made. The two must be identical, and a test checks they are.
133
+
134
+ Make sure you add your name to `CONTRIBUTORS.md` as well!
135
+
136
+ ### Making a pull request
137
+
138
+ Please push your changes up to a feature branch and make a new [pull request](https://github.com/phalt/zoetty/compare) on GitHub.
139
+
140
+ Please add a description to the PR and some information about why the change is being made.
141
+
142
+ After a review, you might need to make more changes.
143
+
144
+ Once accepted, a core contributor will merge your changes!
@@ -0,0 +1,3 @@
1
+ # Contributors
2
+
3
+ - [Paul Hallett](https://github.com/phalt)
zoetty-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paul Hallett
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.
zoetty-0.1.0/Makefile ADDED
@@ -0,0 +1,46 @@
1
+ help:
2
+ @echo Developer commands for zoetty
3
+ @echo
4
+ @grep -E '^[ .a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
5
+ @echo
6
+
7
+ install: ## Install requirements ready for development
8
+ uv sync
9
+
10
+ deploy-docs: ## Build and deploy the documentation
11
+ uv run mkdocs build
12
+ uv run mkdocs gh-deploy
13
+
14
+ docs-serve: ## Run a local documentation server
15
+ uv run mkdocs serve
16
+
17
+ release: ## Build a new version and release it
18
+ uv build
19
+ uv publish
20
+
21
+ ty: ## Run a static syntax check
22
+ uv run ty check .
23
+
24
+ lint-imports: ## Check the import contracts in pyproject.toml
25
+ uv run lint-imports
26
+
27
+ format: ## Format the code correctly
28
+ uv run ruff format .
29
+ uv run ruff check --fix .
30
+
31
+ clean: ## Clear any cache files and test files
32
+ rm -rf .ty_cache
33
+ rm -rf .pytest_cache
34
+ rm -rf .ruff_cache
35
+ rm -rf .import_linter_cache
36
+ rm -rf site/
37
+ rm -rf dist/
38
+ find zoetty tests -name __pycache__ -prune -exec rm -rf {} +
39
+ rm -rf htmlcov/
40
+ rm -rf .coverage
41
+
42
+ test: ## Run tests
43
+ uv run pytest -vvv -x --cov=zoetty --cov-report=term-missing --cov-report=html --cov-config=pyproject.toml
44
+
45
+ shell: ## Run an ipython shell
46
+ uv run ipython
zoetty-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,145 @@
1
+ Metadata-Version: 2.5
2
+ Name: zoetty
3
+ Version: 0.1.0
4
+ Summary: Looping terminal demo clips as plain SVG or HTML and CSS
5
+ Project-URL: Homepage, https://github.com/phalt/zoetty
6
+ Project-URL: Documentation, https://phalt.github.io/zoetty/
7
+ Project-URL: Issues, https://github.com/phalt/zoetty/issues
8
+ Author-email: Paul Hallett <paulandrewhallett@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: animation,cli,demo,docs,readme,svg,terminal
12
+ Classifier: Environment :: Console
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Topic :: Documentation
16
+ Classifier: Topic :: Multimedia :: Graphics
17
+ Requires-Python: >=3.12
18
+ Requires-Dist: click>=8.5.0
19
+ Requires-Dist: rich>=15.0.0
20
+ Description-Content-Type: text/markdown
21
+
22
+ # ⚜ zoetty
23
+
24
+ ## What is zoetty?
25
+
26
+ zoetty turns terminal sessions into small, looping, animated clips made of plain SVG or HTML and CSS. No video, no GIF, no JavaScript.
27
+
28
+ [![Package version](https://img.shields.io/pypi/v/zoetty?color=%2334D058&label=latest%20version)](https://pypi.org/project/zoetty)
29
+ ![Python versions](https://img.shields.io/badge/python-3.12+-blue)
30
+ ![PyPI - License](https://img.shields.io/pypi/l/zoetty)
31
+
32
+ ![zoetty init writes a starter clip spec, zoetty build renders it to SVG, and zoetty check confirms it is up to date](https://raw.githubusercontent.com/phalt/zoetty/main/docs/clips/quickstart.svg)
33
+
34
+ That's zoetty, recorded by zoetty. Every clip in this README is built from a spec in [`docs/clips/`](https://github.com/phalt/zoetty/tree/main/docs/clips).
35
+
36
+ ## Why use zoetty?
37
+
38
+ Terminal GIFs go stale, weigh megabytes, look blurry, and have to be re-recorded by hand every time the output changes.
39
+
40
+ - **Real output** - `zoetty record` runs your commands in a real terminal and keeps their colours.
41
+ - **Small and sharp** - A clip is a few KB of text, crisp at any size.
42
+ - **Works in READMEs** - The SVG is just an image: it plays on GitHub, PyPI and anywhere else that shows one.
43
+ - **Or in your docs** - The HTML fragment drops into any page, with selectable text.
44
+ - **Kept in your repo** - The spec is a short TOML file. When your tool changes, re-record and rebuild.
45
+ - **Checked in CI** - `zoetty check` fails if a clip is out of date.
46
+
47
+ ## Install
48
+
49
+ ```sh
50
+ uv tool install zoetty
51
+ ```
52
+
53
+ Or with pip:
54
+
55
+ ```sh
56
+ pip install zoetty
57
+ ```
58
+
59
+ zoetty needs Python 3.12 or later, and runs on **macOS and Linux**.
60
+
61
+ ## Quick start
62
+
63
+ ```sh
64
+ zoetty init docs/clips/hello.toml # write a starter spec
65
+ zoetty build docs/clips/hello.toml # render it to docs/clips/hello.svg
66
+ ```
67
+
68
+ Then put it in your README like any image:
69
+
70
+ ```markdown
71
+ ![What the clip shows](docs/clips/hello.svg)
72
+ ```
73
+
74
+ ## A basic clip
75
+
76
+ Two commands, with their output written by hand:
77
+
78
+ ```toml
79
+ title = "~/my-project"
80
+ label = "Typing two commands in a terminal: echo prints a greeting, ls lists three files"
81
+ cols = 60
82
+
83
+ [[run]]
84
+ cmd = "echo 'Hello from zoetty!'"
85
+ lines = ["Hello from zoetty!"]
86
+
87
+ [[run]]
88
+ cmd = "ls"
89
+ lines = ["[blue]docs[/] README.md [green]tool.py[/]"]
90
+ ```
91
+
92
+ ![Typing two commands in a terminal: echo prints a greeting, ls lists three files](https://raw.githubusercontent.com/phalt/zoetty/main/docs/clips/hello.svg)
93
+
94
+ ## Recording real output
95
+
96
+ Give a run an `output` file and `zoetty record` runs the command for real and saves what it printed. `input` is typed into interactive programs, a line at a time, once each prompt is waiting:
97
+
98
+ ```toml
99
+ title = "python"
100
+ label = "A Python REPL importing zoetty's markup parser and parsing some styled text"
101
+ cols = 64
102
+
103
+ [record]
104
+ env = { PYTHON_BASIC_REPL = "1" }
105
+
106
+ [[run]]
107
+ cmd = "python -q"
108
+ output = "captures/repl.ansi"
109
+ input = """
110
+ from zoetty.markup import parse, plain
111
+ plain(parse("[bold]zoe[/]tty"))
112
+ [s.styles for s in parse("[bold green]ok[/] done")]
113
+ """
114
+ ```
115
+
116
+ ```sh
117
+ zoetty record docs/clips/repl.toml
118
+ zoetty build docs/clips/repl.toml
119
+ ```
120
+
121
+ ![A Python REPL importing zoetty's markup parser and parsing some styled text](https://raw.githubusercontent.com/phalt/zoetty/main/docs/clips/repl.svg)
122
+
123
+ Long output scrolls once it passes `rows`, and `[theme]` recolours the whole window:
124
+
125
+ ![python -m this printing the Zen of Python, scrolling past the bottom of a ten-row terminal](https://raw.githubusercontent.com/phalt/zoetty/main/docs/clips/zen.svg)
126
+
127
+ See [more examples](https://phalt.github.io/zoetty/examples/), including the HTML output and hand-timed clips.
128
+
129
+ ## Use it with your coding agent
130
+
131
+ zoetty is easy for coding agents to drive: specs are small text files, and every command says what it did. Paste this into Claude Code, Codex, Cursor or similar:
132
+
133
+ ```text
134
+ Use zoetty to add an animated terminal demo of this project to the README.
135
+ Read https://phalt.github.io/zoetty/agents/ first and follow it: install zoetty,
136
+ write a clip spec in docs/clips/ that shows the most useful commands, record the
137
+ real output with `zoetty record`, build it with `zoetty build`, look at the result,
138
+ embed the SVG in README.md, and add `zoetty check docs/clips/*.toml` to CI.
139
+ ```
140
+
141
+ ## Documentation
142
+
143
+ 👉 Read the [full documentation](https://phalt.github.io/zoetty/) for the clip format, every command, embedding clips and more examples.
144
+
145
+ Want to help? See [CONTRIBUTING.md](https://github.com/phalt/zoetty/blob/main/CONTRIBUTING.md).
@@ -0,0 +1,147 @@
1
+ ---
2
+ title: Release zoetty
3
+ description: Release a new version of zoetty to GitHub, the docs site and PyPI.
4
+ output_path: logs/release-<VERSION>.md
5
+ inputs:
6
+ - name: VERSION
7
+ description: The version to release, e.g. 0.2.0
8
+ pattern: '^\d+\.\d+\.\d+$'
9
+ - name: UV_PUBLISH_TOKEN
10
+ description: PyPI API token for zoetty
11
+ secret: true
12
+ ---
13
+
14
+ # ⚜ Releasing zoetty
15
+
16
+ zoetty is released with [paulrun](https://github.com/phalt/paulrun), which runs this runbook:
17
+
18
+ ```sh
19
+ uv tool install paulrun
20
+ paulrun check PUBLISHING.md
21
+ paulrun PUBLISHING.md --dry
22
+ paulrun PUBLISHING.md
23
+ ```
24
+
25
+ You can also follow it by hand: each step's commands are in the order they run.
26
+
27
+ Before you start, add a `## <version>` section for the release to the top of
28
+ `CHANGELOG.md`, and copy it to `docs/CHANGELOG.md`. That change gets committed
29
+ with the version bump.
30
+
31
+ Each run is recorded in `logs/release-<version>.md`, which git ignores.
32
+
33
+ ## Check before releasing
34
+
35
+ Releases are made from an up-to-date `main`, with nothing left uncommitted
36
+ except the changelog, for a version that hasn't been released yet.
37
+
38
+ ```sh run
39
+ git switch main
40
+ git pull origin main
41
+ git fetch --tags
42
+
43
+ if [ -n "$(git status --porcelain -- . ':!CHANGELOG.md' ':!docs/CHANGELOG.md' ':!logs')" ]; then
44
+ echo "Commit or stash these changes first:"
45
+ git status --short
46
+ exit 1
47
+ fi
48
+ if git rev-parse --quiet --verify "refs/tags/<VERSION>" > /dev/null; then
49
+ echo "Tag <VERSION> already exists"
50
+ exit 1
51
+ fi
52
+ if ! grep -qx "## <VERSION>" CHANGELOG.md; then
53
+ echo "CHANGELOG.md has no '## <VERSION>' section"
54
+ exit 1
55
+ fi
56
+ ```
57
+
58
+ ## Run the checks
59
+
60
+ The tests have to pass, but coverage isn't checked here: CI holds it at 100% on
61
+ Linux, and a few lines only run on Linux, so it reads a little lower on macOS.
62
+
63
+ ```sh run
64
+ make ty
65
+ make lint-imports
66
+ uv run pytest -q
67
+ ```
68
+
69
+ ## Check the docs clips are up to date
70
+
71
+ The test suite checks this too, but it's worth seeing before a release.
72
+
73
+ ```sh run
74
+ uv run zoetty check docs/clips/*.toml
75
+ ```
76
+
77
+ ## Update the version
78
+
79
+ `pyproject.toml` holds zoetty's only copy of its version. `uv version` sets
80
+ it and updates `uv.lock` to match.
81
+
82
+ ```sh run
83
+ uv version <VERSION>
84
+ uv run zoetty --version
85
+ ```
86
+
87
+ ## Commit and push
88
+
89
+ There's nothing to commit if the version and changelog were already
90
+ committed, e.g. for the first release, or when rerunning one that failed
91
+ after this step.
92
+
93
+ ```sh run
94
+ if git diff --quiet HEAD; then
95
+ echo "Nothing to commit"
96
+ else
97
+ git commit -am "version <VERSION>"
98
+ fi
99
+ git push origin main
100
+ ```
101
+
102
+ ## Tag the release
103
+
104
+ ```sh run
105
+ git tag <VERSION>
106
+ git push origin <VERSION>
107
+ ```
108
+
109
+ ## Create the GitHub release
110
+
111
+ These are the release notes, from `CHANGELOG.md`:
112
+
113
+ ```python run
114
+ import os
115
+ import re
116
+ from pathlib import Path
117
+
118
+ version = re.escape(os.environ["VERSION"])
119
+ changelog = Path("CHANGELOG.md").read_text()
120
+ notes = re.search(rf"^## {version}\n(.*?)(?=^## |\Z)", changelog, re.MULTILINE | re.DOTALL)
121
+ print(notes.group(1).strip())
122
+ ```
123
+
124
+ ```confirm
125
+ Create a release on GitHub from tag <VERSION>:
126
+ https://github.com/phalt/zoetty/releases/new?tag=<VERSION>
127
+
128
+ Paste in the release notes above, and mark it as the latest release.
129
+ ```
130
+
131
+ ## Publish the documentation
132
+
133
+ Takes about 5-10 minutes to deploy fully.
134
+
135
+ ```sh run
136
+ make deploy-docs
137
+ ```
138
+
139
+ ## Release to PyPI
140
+
141
+ `uv publish` uploads everything in `dist/`, so clear it out first.
142
+
143
+ ```sh run
144
+ rm -rf dist
145
+ # uv publish reads the token from $UV_PUBLISH_TOKEN.
146
+ make release
147
+ ```