livery.toolroom.bench._drivers¶
livery.toolroom.bench._drivers ¶
The curated tools, and the little each one needs said about it.
Extraction is generic — _toolspec reads a click command's parameters,
_toolhelp reads anybody's --help — so a driver is not a wrapper. It
carries only what a tool cannot tell you by being asked:
- which verbs are worth stubbing.
docker --helplists forty commands andgithas hundreds; a stub of all of them would be a megabyte nobody reads. The list here is the verbs tasks actually call. - the quirks. git's
--helpopens a man page, so it wants-h. A tool whose real name differs from its attribute (markdownlint-cli2istools.markdownlint) says so. - the default. Whether
tools.<name>runs in-process by default, which mirrors how it is constructed intools.py.
Everything else — the flags, their help, their types, the negations — comes from the installed tool, every time the stubs are regenerated.
Classes:
| Name | Description |
|---|---|
Manual |
Where a |
Provision |
How |
Plugin |
A separately released program a tool loads as one of its verbs. |
Driver |
One curated tool: what to run, and which verbs to read. |
Functions:
| Name | Description |
|---|---|
installed |
Whether this machine has the tool to ask. |
version |
|
read_versions |
|
in_process_capable |
Whether the tool publishes a |
extract |
Ask the installed tool to describe itself, best source first. |
find |
The driver for |
Attributes:
| Name | Type | Description |
|---|---|---|
RECORD_KINDS |
Each provision tier's installer kind, one of livery.toolroom.store.KINDS. |
|
DRIVERS |
tuple[Driver, ...]
|
|
RECORD_KINDS
module-attribute
¶
RECORD_KINDS = {'uv': 'pypi', 'python': 'python', 'node': 'npm', 'nodejs': 'download', 'dotnet': 'download', 'nuget': 'dotnet', 'man': 'system-check', 'docker': 'system-check', 'bun': 'download', 'github': 'download', 'gitlab': 'download', 'gitea': 'download', 'deferred': 'download'}
Each provision tier's installer kind, one of livery.toolroom.store.KINDS.
DRIVERS
module-attribute
¶
DRIVERS: tuple[Driver, ...] = (Driver('ruff', verbs=('check', 'format', 'clean'), url='https://docs.astral.sh/ruff/', provision=Provision(kind='github', repo='astral-sh/ruff')), Driver('ruff', attr='ruff_format', base=('format',), url='https://docs.astral.sh/ruff/formatter/', provision=Provision(kind='github', repo='astral-sh/ruff')), Driver('basedpyright', url='https://docs.basedpyright.com/', provision=Provision(kind='node')), Driver('uv', provision=Provision(kind='github', repo='astral-sh/uv'), url='https://docs.astral.sh/uv/', verbs=('sync', 'lock', 'run', 'add', 'remove', 'build', 'publish', 'export', 'venv', 'tree', 'version', 'pip.install', 'pip.compile', 'pip.sync', 'pip.list', 'tool.install', 'tool.run', 'tool.upgrade')), Driver('git', provision=Provision(kind='man', manual=Manual(index='https://mirrors.edge.kernel.org/pub/software/scm/git/', archive='git-manpages-{version}.tar.gz', listing='href="../git-manpages-(?P<version>\\d+(?:\\.\\d+)+)\\.tar\\.gz".*?(?P<day>\\d{2})-(?P<month>[A-Z][a-z]{2})-(?P<year>\\d{4})')), url='https://git-scm.com/docs', help_flag='-h', man=True, verbs=('add', 'commit', 'push', 'pull', 'fetch', 'clone', 'init', 'checkout', 'switch', 'branch', 'tag', 'status', 'diff', 'log', 'rev-parse', 'describe', 'stash', 'restore', 'worktree')), Driver('ssh', provision=Provision(kind='man', manual=Manual(index='https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/', archive='openssh-{version}.tar.gz', listing='href="../openssh-(?P<version>\\d+\\.\\d+p\\d+)\\.tar\\.gz"[\\s\\S]*?(?P<day>\\d{2})-(?P<month>[A-Z][a-z]{2})-(?P<year>\\d{4})', pages=('ssh.1',))), man=True, url='https://man.openbsd.org/ssh.1'), Driver('ssh-keygen', attr='ssh_keygen', version_of='ssh', provision=Provision(kind='man', manual=Manual(index='https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/', archive='openssh-{version}.tar.gz', listing='href="../openssh-(?P<version>\\d+\\.\\d+p\\d+)\\.tar\\.gz"[\\s\\S]*?(?P<day>\\d{2})-(?P<month>[A-Z][a-z]{2})-(?P<year>\\d{4})', pages=('ssh-keygen.1',))), man=True, url='https://man.openbsd.org/ssh-keygen.1'), Driver('ssh-keyscan', attr='ssh_keyscan', version_of='ssh', provision=Provision(kind='man', manual=Manual(index='https://cdn.openbsd.org/pub/OpenBSD/OpenSSH/portable/', archive='openssh-{version}.tar.gz', listing='href="../openssh-(?P<version>\\d+\\.\\d+p\\d+)\\.tar\\.gz"[\\s\\S]*?(?P<day>\\d{2})-(?P<month>[A-Z][a-z]{2})-(?P<year>\\d{4})', pages=('ssh-keyscan.1',))), man=True, url='https://man.openbsd.org/ssh-keyscan.1'), Driver('docker', provision=Provision(kind='docker'), plugins=(Plugin(name='docker-compose', repo='docker/compose', owns='compose', path='.docker/cli-plugins', since='2.0.0'), Plugin(name='docker-buildx', repo='docker/buildx', owns='build', path='.docker/cli-plugins')), url='https://docs.docker.com/reference/cli/docker/', verbs=('build', 'run', 'push', 'pull', 'images', 'ps', 'exec', 'logs', 'compose.up', 'compose.down', 'compose.build', 'compose.logs', 'compose.ps', 'compose.run', 'compose.exec')), Driver('bun', provision=Provision(kind='bun', repo='oven-sh/bun'), verbs=('install', 'add', 'remove', 'run', 'build', 'test', 'x'), url='https://bun.sh/docs/cli/install'), Driver('node', provision=Provision(kind='nodejs'), url='https://nodejs.org/docs/latest/api/cli.html'), Driver('dotnet', provision=Provision(kind='dotnet'), url='https://learn.microsoft.com/dotnet/core/tools/'), Driver('dotnet-coverage', attr='dotnet_coverage', provision=Provision(kind='nuget', runtime='dotnet'), verbs=('collect', 'instrument', 'merge', 'snapshot', 'connect', 'shutdown'), url='https://learn.microsoft.com/dotnet/core/additional-tools/dotnet-coverage'), Driver('mkdocs', verbs=('build', 'serve', 'new', 'gh-deploy'), in_process=True, url='https://www.mkdocs.org/'), Driver('zensical', verbs=('build', 'serve', 'new'), in_process=True, url='https://zensical.org/'), Driver('coverage', url='https://coverage.readthedocs.io/', verbs=('run', 'report', 'html', 'xml', 'json', 'combine', 'erase', 'annotate'), in_process=True), Driver('cspell', provision=Provision(kind='node', runtime='bun'), verbs=('lint', 'trace', 'check', 'suggest'), url='https://cspell.org/'), Driver('prek', verbs=('run', 'install', 'uninstall', 'autoupdate', 'clean'), url='https://prek.j178.dev/', provision=Provision(kind='github', repo='j178/prek')), Driver('markdownlint-cli2', attr='markdownlint', provision=Provision(kind='node', runtime='bun'), url='https://github.com/DavidAnson/markdownlint-cli2'), Driver('claude', provision=Provision(kind='node', package='@anthropic-ai/claude-code', runtime='bun'), url='https://docs.claude.com/en/docs/claude-code/cli-reference', verbs=('agents', 'auth.login', 'auth.logout', 'auth.status', 'doctor', 'install', 'mcp.add', 'mcp.add-json', 'mcp.get', 'mcp.list', 'mcp.remove', 'mcp.serve', 'plugin.disable', 'plugin.enable', 'plugin.install', 'plugin.list', 'plugin.marketplace.add', 'plugin.marketplace.list', 'plugin.marketplace.remove', 'plugin.marketplace.update', 'plugin.uninstall', 'plugin.update', 'plugin.validate', 'setup-token', 'update')), Driver('gh', provision=Provision(kind='github', repo='cli/cli'), url='https://cli.github.com/manual/', verbs=('pr.create', 'pr.list', 'pr.view', 'pr.checkout', 'pr.merge', 'issue.create', 'issue.list', 'issue.view', 'release.create', 'release.upload', 'release.view', 'release.list', 'repo.clone', 'repo.view', 'run.list', 'run.view', 'run.watch', 'workflow.run', 'workflow.list', 'auth.status', 'auth.login', 'api', 'label.list', 'label.create')), Driver('tea', provision=Provision(kind='gitea', repo='gitea/tea', floor='0.15.0'), url='https://gitea.com/gitea/tea', verbs=('issues.create', 'issues.list', 'issues.close', 'pulls.create', 'pulls.list', 'pulls.checkout', 'pulls.merge', 'releases.create', 'releases.list', 'releases.assets', 'repos.create', 'repos.list', 'repos.fork', 'labels.list', 'labels.create', 'milestones.list', 'milestones.create', 'comments.add', 'comments.list', 'branches.list', 'logins.add', 'logins.list', 'whoami', 'clone', 'api')), Driver('eclint', provision=Provision(kind='gitlab', repo='willemkokke/eclint'), url='https://gitlab.com/willemkokke/eclint'), Driver('djlint', url='https://www.djlint.com/'), Driver('mypy', url='https://mypy.readthedocs.io/'), Driver('ty', verbs=('check',), url='https://docs.astral.sh/ty/', provision=Provision(kind='github', repo='astral-sh/ty')), Driver('pyrefly', verbs=('check',), url='https://pyrefly.org/', provision=Provision(kind='github', repo='facebook/pyrefly')), Driver('twine', verbs=('upload', 'check'), url='https://twine.readthedocs.io/'), Driver('git-changelog', url='https://pawamoy.github.io/git-changelog/'), Driver('git-cliff', url='https://git-cliff.org/', provision=Provision(kind='github', repo='orhun/git-cliff')), Driver('git-lfs', url='https://git-lfs.com/', verbs=('install', 'track', 'untrack', 'ls-files', 'pull', 'fetch', 'push'), provision=Provision(kind='github', repo='git-lfs/git-lfs')), Driver('pyproject-build', attr='build', provision=Provision(package='build'), url='https://build.pypa.io/'), Driver('cmake', url='https://cmake.org/documentation/', provision=Provision(kind='github', repo='Kitware/CMake')), Driver('ninja', url='https://ninja-build.org/', provision=Provision(kind='github', repo='ninja-build/ninja')), Driver('clang-format', attr='clang_format', url='https://clang.llvm.org/docs/ClangFormat.html'), Driver('clang-tidy', attr='clang_tidy', url='https://clang.llvm.org/extra/clang-tidy/'), Driver('cmake-conan', source='manual', url='https://github.com/conan-io/cmake-conan', provision=Provision(kind='github', repo='conan-io/cmake-conan', floor='0.19.0', asset='https://raw.githubusercontent.com/{repo}/{tag}/conan_provider.cmake')), Driver('conan', verbs=('install', 'create', 'upload', 'list', 'remote', 'cache', 'profile', 'editable'), url='https://docs.conan.io/', provision=Provision(kind='github', repo='conan-io/conan', floor='2.0.0')), Driver('pytest', url='https://docs.pytest.org/', in_process=True, provision=Provision(plugins=('pytest-cov',))), Driver('python', provision=Provision(kind='python'), url='https://docs.python.org/3/using/cmdline.html'), Driver('bash', source='manual', url='https://www.gnu.org/software/bash/'), Driver('zsh', source='manual', url='https://www.zsh.org/'), Driver('fish', source='manual', url='https://fishshell.com/'), Driver('pwsh', source='manual', url='https://learn.microsoft.com/powershell/', provision=Provision(kind='github', repo='PowerShell/PowerShell')), Driver('nu', source='manual', url='https://www.nushell.sh/'), Driver('cmd', source='manual', url='https://learn.microsoft.com/windows-server/administration/windows-commands/cmd'))
Manual
dataclass
¶
Where a kind="man" tool's per-release pages are published.
A manual is not a binary: the pages are the reading, so nothing is
installed and nothing is run — the fetch is a directory listing, an
archive per release, and a man -M tree to unpack it into. Two
publishers so far: kernel.org's per-release git manpage tarballs, and
OpenSSH's portable release tarballs (which carry ssh.1 alongside the
sources). The pages are the same bytes everywhere — a manual has no
platform — so machines reading this tier cannot disagree.
Attributes:
| Name | Type | Description |
|---|---|---|
index |
str
|
The directory listing the per-release archives appear in. |
archive |
str
|
The archive's filename with a |
listing |
str
|
Regex over the listing naming each release: must bind |
pages |
tuple[str, ...]
|
Member basenames to pull into |
archive
instance-attribute
¶
archive: str
The archive's filename with a {version} slot, joined to index.
listing
instance-attribute
¶
listing: str
Regex over the listing naming each release: must bind
(?P<version>…), and may bind (?P<day>…)/(?P<month>…)/(?P<year>…)
where the listing shows dates (kernel.org does; OpenSSH's does not, and
its patchlevels tie under version_tuple — _order breaks that tie on
the numeric pN suffix).
Provision
dataclass
¶
Provision(kind: str = 'uv', package: str = '', runtime: str = '', repo: str = '', note: str = '', floor: str = '', plugins: tuple[str, ...] = (), manual: Manual | None = None, asset: str = '')
How fm toolroom.provision fetches this tool's latest binary.
Data, like everything else a driver carries. The extractor reads the installed tool; this says how to get the latest one into a throwaway prefix, without touching the machine's own environment.
Methods:
| Name | Description |
|---|---|
target |
What to fetch: the explicit |
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
str
|
|
package |
str
|
The PyPI or npm package, when it differs from the driver's binary name |
runtime |
str
|
What a |
repo |
str
|
|
note |
str
|
Why a |
floor |
str
|
Releases below this are not offered — not listed, not walked, and |
plugins |
tuple[str, ...]
|
Extra packages to install alongside the tool ( |
manual |
Manual | None
|
Where the pages live, for |
asset |
str
|
A URL template for a release that lists no asset: the file at a |
record_kind |
str
|
The installer kind a new record of this tool names, from the tier. |
kind
class-attribute
instance-attribute
¶
kind: str = 'uv'
uv — a PyPI console script, uv tool install --upgraded into an
isolated prefix; for programs that are Python alone, where the wheel is
the release (a test pins the tier's members). node — a package from
npm, installed through the runtime runtime names and run on it.
nodejs — node's own build from nodejs.org's release index, the runtime
a node-tier package runs on unless its driver names bun. bun — bun's
own GitHub release, the other runtime. dotnet — the .NET SDK from
Microsoft's release metadata, the runtime a nuget package runs on
and installs through. nuget — a .NET tool package from nuget.org,
installed by that SDK into a tool path. github / gitlab / gitea — a prebuilt
release asset, the tier for every tool with a release of its own.
docker — a static build from docker's own per-platform index, which is
a directory listing rather than an asset list. man — a release's
manual pages, for a tool read from its manual rather than its -h.
deferred — parked whole, note saying why (tea sat here until its
0.15.0 release; a per-release boundary wants floor instead).
package
class-attribute
instance-attribute
¶
package: str = ''
The PyPI or npm package, when it differs from the driver's binary name
(markdownlint-cli2); otherwise the binary name is used.
runtime
class-attribute
instance-attribute
¶
runtime: str = ''
What a node-tier package runs on and installs through: node, unless
this says bun; dotnet for a nuget package. Stamped on the record
when it is first written, and
read by every install of the package since. Which runtime a package
gets is measured: a package moves by a reviewed edit here and on its
record, never by default.
repo
class-attribute
instance-attribute
¶
repo: str = ''
owner/repo for a github / gitlab release download.
note
class-attribute
instance-attribute
¶
note: str = ''
Why a deferred source is parked — shown by provision.
floor
class-attribute
instance-attribute
¶
floor: str = ''
Releases below this are not offered — not listed, not walked, and
so never holes. The precedent is READ_PYTHON_SINCE: a hole says "this
could not be read", and the store should not carry a shrug about a
release that is simply out of scope. Unlike deferred this is per
release, not per tool — the tool stays curated, its history just starts
here. The boundary applies on every platform, so set it only where the
releases below are not worth having anywhere, and say why alongside.
plugins
class-attribute
instance-attribute
¶
Extra packages to install alongside the tool (uv --with), so a
plugin-extended CLI is read whole. pytest's --cov* flags come from
pytest-cov; without it a bare provisioned pytest would stub none of them.
manual
class-attribute
instance-attribute
¶
manual: Manual | None = None
Where the pages live, for kind="man" — required there, unused
elsewhere.
asset
class-attribute
instance-attribute
¶
asset: str = ''
A URL template for a release that lists no asset: the file at a
versioned address, the same for every host, with {repo} and {tag}
filled in. cmake-conan's provider is one CMake file at
raw.githubusercontent.com/<repo>/<tag>/conan_provider.cmake.
record_kind
property
¶
record_kind: str
The installer kind a new record of this tool names, from the tier.
A record that exists keeps its own kind; this answers only for a tool read for the first time. A forge release lands as a download, the manual and docker tiers verify a system tool, and the package tiers delegate to their installer.
target ¶
What to fetch: the explicit package/repo, else the tool name.
Plugin
dataclass
¶
A separately released program a tool loads as one of its verbs.
docker compose is not part of docker. It is its own project on its
own release line, shipped as a binary the CLI discovers under the
user's config directory — so a static docker build has no compose in
it, and reading docker compose up --help reads whatever the machine
happened to have installed. Under a walk that is a lie with a date on
it: compose's surface of today, recorded as docker 20.10's. Across a
platform matrix it is worse, because two machines with different
compose versions look like a genuine per-platform divergence.
So the plugin is fetched like the tool is, and paired by date: the
release a user of that docker would have had. The verbs keep their
place — tools.docker.compose.up(...) is still how you say it — and
the pairing is deterministic, so the same walk gives the same answer
forever.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The binary as the host tool looks for it ( |
repo |
str
|
|
owns |
str
|
The verb prefix these releases account for ( |
path |
str
|
Where the host tool looks, relative to the user's home |
since |
str
|
The first release that was a plugin at all. compose 1.x was a |
owns
class-attribute
instance-attribute
¶
owns: str = ''
The verb prefix these releases account for (compose).
path
class-attribute
instance-attribute
¶
path: str = ''
Where the host tool looks, relative to the user's home
(.docker/cli-plugins).
since
class-attribute
instance-attribute
¶
since: str = ''
The first release that was a plugin at all. compose 1.x was a
standalone program you ran as docker-compose; docker compose did
not exist until 2.0. Dropping a 1.x binary into the plugin directory
would not make it one, so an era before this pairs with nothing and
the verbs read as absent — which they were.
Driver
dataclass
¶
Driver(name: str, attr: str = '', verbs: tuple[str, ...] = tuple(), help_flag: str = '--help', in_process: bool = False, base: tuple[str, ...] = tuple(), source: str = 'auto', shorts: str = 'only', url: str = '', version_of: str = '', man: bool = False, provision: Provision = Provision(), plugins: tuple[Plugin, ...] = tuple())
One curated tool: what to run, and which verbs to read.
Methods:
| Name | Description |
|---|---|
mode |
How this tool runs, as a stub's header says: |
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The binary as it is invoked. |
attr |
str
|
|
verbs |
tuple[str, ...]
|
The subcommands to stub, dotted for nesting ( |
help_flag |
str
|
git's |
in_process |
bool
|
Whether |
base |
tuple[str, ...]
|
A pre-bound verb: |
source |
str
|
|
shorts |
str
|
Short-option policy for the stub: |
url |
str
|
The tool's home, for the reference page's table. |
version_of |
str
|
The sibling binary whose version answers for this tool, when it has |
man |
bool
|
Read each verb's manual ( |
provision |
Provision
|
How to fetch the latest binary — the default is a PyPI |
plugins |
tuple[Plugin, ...]
|
Companion programs some of the verbs really come from, each released |
key |
str
|
|
wanted |
tuple[str, ...]
|
The verbs to read: a pre-bound tool wants only the one it binds. |
attr
class-attribute
instance-attribute
¶
attr: str = ''
tools.<attr>, when it differs from the binary's name.
verbs
class-attribute
instance-attribute
¶
The subcommands to stub, dotted for nesting (compose.up). Empty
means the tool is its own command and its options hang off __call__.
help_flag
class-attribute
instance-attribute
¶
help_flag: str = '--help'
git's --help opens a man page; -h is the help text.
in_process
class-attribute
instance-attribute
¶
in_process: bool = False
Whether tools.<attr> prefers in-process, as tools.py builds it.
base
class-attribute
instance-attribute
¶
A pre-bound verb: tools.ruff_format is Tool("ruff", "format").
source
class-attribute
instance-attribute
¶
source: str = 'auto'
auto prefers structure (click) and falls back to --help.
shorts
class-attribute
instance-attribute
¶
shorts: str = 'only'
Short-option policy for the stub: "none" never keys on a short,
"only" (default) keys on one when it is the option's sole spelling
(python's -m, git's -C), and "all" also keys on a short that has a
long form. Read only from --help, never a man page (its prose is noisy).
url
class-attribute
instance-attribute
¶
url: str = ''
The tool's home, for the reference page's table.
version_of
class-attribute
instance-attribute
¶
version_of: str = ''
The sibling binary whose version answers for this tool, when it has no version output of its own — ssh-keygen ships in lockstep with ssh, and the OpenSSH release is the version of both.
man
class-attribute
instance-attribute
¶
man: bool = False
Read each verb's manual (git help <verb>) instead of its terse
-h. git's -h omits about half its flags and prints an idiosyncratic
multi-form usage; the manual is complete and states one SYNOPSIS per
form, so both options and positional shape come out right. Runs only at
stub-generation time, so the man-page dependency never reaches a user.
provision
class-attribute
instance-attribute
¶
How to fetch the latest binary — the default is a PyPI uv install.
plugins
class-attribute
instance-attribute
¶
Companion programs some of the verbs really come from, each released
on its own line — see Plugin.
wanted
property
¶
The verbs to read: a pre-bound tool wants only the one it binds.
mode ¶
How this tool runs, as a stub's header says: default, available, no.
A Python tool publishes a [console_scripts] entry point, which
is what Tool.__call__ resolves, so capable is detected, not
listed. Whether footman prefers it is this driver's business.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
installed ¶
version ¶
<tool> --version, reduced to the version itself.
Reads the binary extraction resolves, which is not always the one a
task would run (_resolve prefers a Homebrew keg for host-read tools).
The parsing is shared with tools.Tool.installed_version so only the
choice of binary can ever differ, never the grammar.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
read_versions ¶
read_versions(names: Sequence[str], *, timeout: float = 30.0, retry_timeout: float = 120.0) -> dict[str, tuple[str, str]]
(version, diagnosis) per tool, read side by side, the stalled ones again alone.
The first round spawns every tool at once, so a caller waits for the slowest tool and not for the sum of them. On a fresh Windows runner that round is also where Defender scans every binary on its first spawn, all at once, and a scan that has not finished inside timeout reads as a stall. So each tool that timed out is read again after the round, one at a time with retry_timeout: the scans are cached or finishing, and nothing contends. A tool that times out twice has earned its diagnosis, which names both budgets. Any other failure stands as read: a spawn that failed or answered nothing is not a stall, and a second spawn would teach nothing.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
in_process_capable ¶
Whether the tool publishes a [console_scripts] entry point.
That entry point is exactly what Tool.__call__ resolves to run a tool
inside footman's process, so its existence is the capability — no
list to maintain, and it answers correctly for a tool footman has never
heard of.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
extract ¶
Ask the installed tool to describe itself, best source first.
home is the throwaway home the caller gave this reading, when it gave
one — see _anonymous for why it cannot be discovered here.
click hands over its parameters as data — including secondary_opts,
the negation a --help scrape can only find if the tool happens to
mention it in prose. So structure wins when it is available, and the
help text covers everyone else.