paulrun 0.1.0__tar.gz

paulrun-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI - Lint and Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14", "3.15-dev"]
+    steps:
+      #----------------------------------------------
+      #       check-out repo and set-up python
+      #----------------------------------------------
+      - name: Check out repository
+        uses: actions/checkout@v7
+      - name: Set up python
+        id: setup-python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{matrix.python-version}}
+      #----------------------------------------------
+      #  -----  install & configure uv  -----
+      #----------------------------------------------
+      # Pointing uv at the interpreter setup-python installed overrides .python-version,
+      # which would otherwise make every matrix entry run on 3.14.
+      - name: Install UV
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ steps.setup-python.outputs.python-path }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      #----------------------------------------------
+      # install dependencies
+      #----------------------------------------------
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Show Python version
+        run: uv run python --version
+      #----------------------------------------------
+      # Run linting and tests
+      #----------------------------------------------
+      - name: Ruff format check
+        run: |
+          uv run ruff format --check .
+      - name: Ruff linting
+        run: |
+          uv run ruff check .
+      - name: Type check with ty
+        run: |
+          uv run ty check
+      - name: Test with pytest
+        run: |
+          uv run pytest -vv --cov=paulrun --cov-branch --cov-report=term-missing --cov-config=pyproject.toml

paulrun-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+.ty_cache/
+.ruff_cache/
+.pytest_cache/
+.idea/
+__pycache__
+.DS_Store
+dist/
+site/
+htmlcov/
+*.coverage*
+coverage.xml
+.cache/
+
+# Transcripts written by running the fixture runbooks by hand
+tests/runbooks/logs/
+
+# Transcripts written by releasing paulrun with PUBLISHING.md, or running the examples by hand
+/logs/
+examples/logs/

paulrun-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

paulrun-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Change log
+
+## 0.1.0
+
+Initial release. paulrun runs hand-written markdown runbooks.
+
+- `paulrun go` runs a runbook's steps in order, streaming each block's output as it's printed and stopping at the first block that fails.
+- `run` blocks for shell (`sh`, `bash`, `shell`) and Python (`python`, `py`), with the `python` frontmatter key to choose the interpreter.
+- `docstring` blocks to show notes as the runbook runs, and `confirm` blocks to pause for steps done by hand.
+- `input` blocks to ask for a value part way through a run, once it exists: a pull request number from a step done by hand, or a one-time code that expires in seconds.
+- Inputs, collected from the environment or by asking, with an optional `pattern` to check them against. Plain inputs fill in `<NAME>` placeholders; secrets are hidden as you type them and replaced with `****` everywhere paulrun shows or records them.
+- `paulrun go --dry` to see every block with its inputs filled in, without running anything.
+- `paulrun go --step` to run, skip or quit at each block.
+- Transcripts: with `output_path` set, every run is added to a plain record of what ran, what it printed and how it finished.
+- Ctrl-C stops a run cleanly, letting a running block stop and recording how far the run got.
+- `paulrun check` to find problems before running anything: missing or malformed frontmatter, undeclared placeholders, secrets used as placeholders, blocks outside a step, and shell and Python syntax errors, with shellcheck warnings when it's installed.
+- `paulrun inputs` to list the inputs a runbook needs, and `paulrun backends` to list the languages paulrun can run.
+- Backends for other languages can be added by any package, through the `paulrun.backends` entry point group.

paulrun-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# paulrun Code of Conduct
+
+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.
+
+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.
+
+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.
+
+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.
+
+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).
+
+- **Be friendly and patient.**
+- **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.
+- **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.
+- **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.
+- **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:
+  - Violent threats or language directed against another person.
+  - Discriminatory jokes and language.
+  - Posting sexually explicit or violent material.
+  - Posting (or threatening to post) other people's personally identifying information ("doxing").
+  - Personal insults, especially those using racist or sexist terms.
+  - Unwelcome sexual attention.
+  - Advocating for, or encouraging, any of the above behavior.
+  - Repeated harassment of others. In general, if someone asks you to stop, then stop.
+- **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.
+
+Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html).
+
+## Questions?
+
+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).

paulrun-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,150 @@
+# Contributing
+
+First things first: thank you for contributing! This project will be successful thanks to everyone who contributes, and we're happy to have you.
+
+## AI disclosure
+
+Within paulrun we use coding agents to prototype and build out ideas, and then take the idea to fruition using human reviewed and approved code.
+
+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.
+
+## Bug or issue?
+
+To raise a bug or issue please use [our GitHub](https://github.com/phalt/paulrun/issues).
+
+Please check the issue has not been raised before by using the search feature.
+
+When submitting an issue or bug, please make sure you provide thorough detail on:
+
+1. The version of paulrun you are using (`paulrun --version`)
+2. Your operating system and Python version
+3. Any errors or outputs you see in your terminal
+4. The smallest runbook that shows the problem (this is particularly important). Take out any secrets first!
+
+## Contribution
+
+If you want to directly contribute you can do so in two ways:
+
+1. Documentation
+2. Code
+
+### Documentation
+
+We use [mkdocs](https://www.mkdocs.org/) and [GitHub pages](https://pages.github.com/) to deploy our docs.
+
+Fixing grammar, spelling mistakes, or expanding the documentation to cover features that are not yet documented, are all valuable contributions.
+
+Please see the **Set up** instructions below to run the docs locally on your computer, then:
+
+```sh
+make docs-serve
+```
+
+The examples in the docs and the README are tested, so if you change one, run `make test` too.
+
+### Code
+
+Contribution by writing code for new features, or fixing bugs, is a great way to contribute to the project.
+
+Please [open an issue](https://github.com/phalt/paulrun/issues) to talk it through before changing the runbook format (frontmatter keys, what a fence does, placeholders or the transcript), adding a command or flag, or adding a dependency. These are hard to change once people's runbooks rely on them.
+
+#### Set up
+
+Clone the repo:
+
+```sh
+git clone git@github.com:phalt/paulrun.git
+cd paulrun
+```
+
+Move to a feature branch:
+
+```sh
+git switch -c my-branch-name
+```
+
+Install UV (if not already installed):
+
+```sh
+# On macOS and Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Or using pip:
+pip install uv
+```
+
+Install all the dependencies:
+
+```sh
+make install
+```
+
+This will use UV to create a virtual environment and install all dependencies, including paulrun itself, so its built-in backends are registered. UV handles the virtual environment automatically, so you don't need to manually activate it.
+
+To make sure you have things set up correctly, please run the tests:
+
+```sh
+make test
+```
+
+You can run your copy of paulrun with `uv run paulrun`, e.g. on one of the example runbooks in `tests/runbooks/`:
+
+```sh
+uv run paulrun go tests/runbooks/two_steps.md
+```
+
+Run `make help` to see every command.
+
+### Adding a backend
+
+paulrun runs shell and Python blocks out of the box. To add another language to paulrun itself:
+
+1. Write `paulrun/backends/<name>.py`, implementing the backend protocol
+2. Add one entry point line for it in `pyproject.toml`, then run `make install`
+3. Write `tests/backends/test_<name>.py`, which really runs blocks (skipped if the language isn't installed)
+4. Add a section about it to `docs/backends.md`
+5. Add a CHANGELOG entry
+
+[docs/backends.md](https://phalt.github.io/paulrun/backends/) explains each step, and how backends work.
+
+A backend doesn't have to be part of paulrun: the same page shows how to ship one in your own package.
+
+### Preparing changes for review
+
+Once you've made changes, here's a good checklist to run through before publishing for review:
+
+Format and lint the code:
+
+```sh
+make format
+```
+
+Check the types:
+
+```sh
+make ty
+```
+
+Run the tests:
+
+```sh
+make test
+```
+
+New behaviour needs tests, and each new runbook feature gets an example runbook in `tests/runbooks/` that shows it off.
+
+If you've changed how runbooks are written or run, update `docs/runbook-format.md` or `docs/cli.md` to match.
+
+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.
+
+Make sure you add your name to `CONTRIBUTORS.md` as well!
+
+### Making a pull request
+
+Please push your changes up to a feature branch and make a new [pull request](https://github.com/phalt/paulrun/compare) on GitHub.
+
+Please add a description to the PR and some information about why the change is being made.
+
+After a review, you might need to make more changes.
+
+Once accepted, a core contributor will merge your changes!

paulrun-0.1.0/CONTRIBUTORS.md

@@ -0,0 +1,3 @@
+# Contributors
+
+- [Paul Hallett](https://github.com/phalt)

paulrun-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Hallett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paulrun-0.1.0/Makefile

@@ -0,0 +1,42 @@
+help:
+	@echo Developer commands for paulrun
+	@echo
+	@grep -E '^[ .a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+
+install:  ## Install requirements ready for development
+	uv sync
+
+deploy-docs:  ## Build and deploy the documentation
+	uv run mkdocs build
+	uv run mkdocs gh-deploy
+
+docs-serve:  ## Run a local documentation server
+	uv run mkdocs serve
+
+release:  ## Build a new version and release it
+	uv build
+	uv publish
+
+ty: ## Run a static syntax check
+	uv run ty check .
+
+format: ## Format the code correctly
+	uv run ruff format .
+	uv run ruff check --fix .
+
+clean:  ## Clear any cache files and test files
+	rm -rf .ty_cache
+	rm -rf .pytest_cache
+	rm -rf .ruff_cache
+	rm -rf site/
+	rm -rf dist/
+	find paulrun tests -name __pycache__ -prune -exec rm -rf {} +
+	rm -rf htmlcov/
+	rm -rf .coverage
+
+test:  ## Run tests
+	uv run pytest -vvv -x --cov=paulrun --cov-report=term-missing --cov-report=html --cov-config=pyproject.toml
+
+shell:  ## Run an ipython shell
+	uv run ipython

paulrun-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: paulrun
+Version: 0.1.0
+Summary: Run hand-written markdown runbooks
+Project-URL: Homepage, https://github.com/phalt/paulrun
+Project-URL: Documentation, https://phalt.github.io/paulrun/
+Project-URL: Issues, https://github.com/phalt/paulrun/issues
+Author-email: Paul Hallett <paulandrewhallett@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: click>=8.5.0
+Requires-Dist: markdown-it-py>=4.2.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Description-Content-Type: text/markdown
+
+# 🏃‍♂️‍➡️📕 paulrun
+
+## What is paulrun?
+
+paulrun runs hand-written markdown runbooks.
+
+A runbook is a normal markdown file that a person can read and follow without paulrun. Mark a code block `run`, and paulrun runs it for you. Everything else stays documentation.
+
+[![Package version](https://img.shields.io/pypi/v/paulrun?color=%2334D058&label=latest%20version)](https://pypi.org/project/paulrun)
+![Python versions](https://img.shields.io/badge/python-3.12+-blue)
+![PyPI - License](https://img.shields.io/pypi/l/paulrun)
+
+## Example runbook
+
+Save this as `hello.md`:
+
+````markdown
+---
+title: Say hello
+inputs:
+  - name: NAME
+    description: Who to say hello to
+---
+
+# Say hello
+
+A runbook is just markdown. paulrun runs the blocks marked `run`, shows the
+`docstring` ones, and leaves everything else alone, like this paragraph.
+
+## Greet
+
+```docstring
+Saying hello to <NAME>.
+```
+
+```sh run
+echo "Hello, <NAME>!"
+```
+
+## Count the letters
+
+```python run
+import os
+
+name = os.environ["NAME"]
+print(f"{name} has {len(name)} letters")
+```
+````
+
+Check it, then run it:
+
+```sh
+paulrun check hello.md
+paulrun go hello.md
+```
+
+```
+hello.md: ok
+NAME (Who to say hello to): Paul
+Say hello
+inputs: NAME=Paul
+  1. Greet
+  2. Count the letters
+2 run blocks
+Start? [y/N] y
+
+=== Greet ===
+Saying hello to Paul.
+    echo "Hello, Paul!"
+Hello, Paul!
+exit 0 (0.0s)
+
+=== Count the letters ===
+    import os
+
+    name = os.environ["NAME"]
+    print(f"{name} has {len(name)} letters")
+Paul has 4 letters
+exit 0 (0.1s)
+
+finished: ok (0.1s)
+```
+
+`check` finds problems before anything runs. `go` asks for the inputs, shows you the plan, then runs each step in order, streaming every command's output as it goes. It stops at the first command that fails.
+
+## Why use paulrun?
+
+Release steps get forgotten. Writing them down helps; making the written-down version run itself fixes it.
+
+- **It's just markdown** - A runbook reads like documentation, renders on GitHub, and works fine without paulrun.
+- **Check before you run** - `paulrun check` catches undeclared placeholders, broken frontmatter and shell or Python syntax errors before anything runs.
+- **See what would happen** - `paulrun go --dry` shows every command with its inputs filled in, and runs nothing.
+- **Inputs and secrets** - Ask for values once, check them against a pattern, and keep secrets off the screen and out of the log.
+- **Manual steps too** - `confirm` blocks pause for the things only a person can do.
+- **A record of every run** - An optional transcript keeps every command, its output and how the run finished.
+- **More than shell** - Shell and Python blocks are built in, and other languages can be added as backends.
+
+## Install
+
+paulrun is a command-line tool, so install it on its own rather than into a project:
+
+```sh
+uv tool install paulrun
+```
+
+Or with pip:
+
+```sh
+pip install paulrun
+```
+
+paulrun needs Python 3.12 or later and `bash`, and runs on **macOS and Linux**. Windows isn't supported. It's for runbooks you run yourself, at a terminal; there's no CI mode.
+
+## Getting started
+
+👉 Read the [full documentation](https://phalt.github.io/paulrun/) for the runbook format, every command, and writing your own backend.
+
+See [`examples/`](https://github.com/phalt/paulrun/tree/main/examples) for more runbooks, including a real release, and [`PUBLISHING.md`](https://github.com/phalt/paulrun/blob/main/PUBLISHING.md) for the runbook paulrun releases itself with.
+
+Want to help? See [CONTRIBUTING.md](https://github.com/phalt/paulrun/blob/main/CONTRIBUTING.md).

paulrun-0.1.0/PUBLISHING.md

@@ -0,0 +1,134 @@
+---
+title: Release paulrun
+description: Release a new version of paulrun to GitHub, the docs site and PyPI.
+output_path: logs/release-<VERSION>.md
+inputs:
+  - name: VERSION
+    description: The version to release, e.g. 0.2.0
+    pattern: '^\d+\.\d+\.\d+$'
+  - name: UV_PUBLISH_TOKEN
+    description: PyPI API token for paulrun
+    secret: true
+---
+
+# 🏃‍♂️‍➡️📕 Releasing paulrun
+
+paulrun releases itself with this runbook:
+
+```sh
+paulrun check PUBLISHING.md
+paulrun go PUBLISHING.md --dry
+paulrun go PUBLISHING.md
+```
+
+You can also follow it by hand: each step's commands are in the order they run.
+
+Before you start, add a `## <version>` section for the release to the top of
+`CHANGELOG.md`, and copy it to `docs/CHANGELOG.md`. That change gets committed
+with the version bump.
+
+Each run is recorded in `logs/release-<version>.md`, which git ignores.
+
+## Check before releasing
+
+Releases are made from an up-to-date `main`, with nothing left uncommitted
+except the changelog, for a version that hasn't been released yet.
+
+```sh run
+git switch main
+git pull origin main
+git fetch --tags
+
+if [ -n "$(git status --porcelain -- . ':!CHANGELOG.md' ':!docs/CHANGELOG.md' ':!logs')" ]; then
+  echo "Commit or stash these changes first:"
+  git status --short
+  exit 1
+fi
+if git rev-parse --quiet --verify "refs/tags/<VERSION>" > /dev/null; then
+  echo "Tag <VERSION> already exists"
+  exit 1
+fi
+if ! grep -qx "## <VERSION>" CHANGELOG.md; then
+  echo "CHANGELOG.md has no '## <VERSION>' section"
+  exit 1
+fi
+```
+
+## Run the checks
+
+```sh run
+make ty
+make test
+```
+
+## Update the version
+
+`pyproject.toml` holds paulrun's only copy of its version. `uv version` sets
+it and updates `uv.lock` to match.
+
+```sh run
+uv version <VERSION>
+uv run paulrun --version
+```
+
+## Commit and push
+
+There's nothing to commit if the version and changelog were already
+committed, e.g. for the first release, or when rerunning one that failed
+after this step.
+
+```sh run
+if git diff --quiet HEAD; then
+  echo "Nothing to commit"
+else
+  git commit -am "version <VERSION>"
+fi
+git push origin main
+```
+
+## Tag the release
+
+```sh run
+git tag <VERSION>
+git push origin <VERSION>
+```
+
+## Create the GitHub release
+
+These are the release notes, from `CHANGELOG.md`:
+
+```python run
+import os
+import re
+from pathlib import Path
+
+version = re.escape(os.environ["VERSION"])
+changelog = Path("CHANGELOG.md").read_text()
+notes = re.search(rf"^## {version}\n(.*?)(?=^## |\Z)", changelog, re.MULTILINE | re.DOTALL)
+print(notes.group(1).strip())
+```
+
+```confirm
+Create a release on GitHub from tag <VERSION>:
+https://github.com/phalt/paulrun/releases/new?tag=<VERSION>
+
+Paste in the release notes above, and mark it as the latest release.
+```
+
+## Publish the documentation
+
+Takes about 5-10 minutes to deploy fully.
+
+```sh run
+make deploy-docs
+```
+
+## Release to PyPI
+
+`uv publish` uploads everything in `dist/`, so clear it out first.
+
+```sh run
+rm -rf dist
+# uv publish reads the token from $UV_PUBLISH_TOKEN.
+make release
+```