Skip to content

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 --help lists forty commands and git has 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 --help opens a man page, so it wants -h. A tool whose real name differs from its attribute (markdownlint-cli2 is tools.markdownlint) says so.
  • the default. Whether tools.<name> runs in-process by default, which mirrors how it is constructed in tools.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 kind="man" tool's per-release pages are published.

Provision

How fm toolroom.provision fetches this tool's latest binary.

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

<tool> --version, reduced to the version itself.

read_versions

(version, diagnosis) per tool, read side by side, the stalled ones again alone.

in_process_capable

Whether the tool publishes a [console_scripts] entry point.

extract

Ask the installed tool to describe itself, best source first.

find

The driver for tools.<key>.

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

Manual(index: str, archive: str, listing: str, pages: tuple[str, ...] = ())

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 {version} slot, joined to index.

listing str

Regex over the listing naming each release: must bind

pages tuple[str, ...]

Member basenames to pull into man1/ (("ssh.1",) from a source

index instance-attribute

index: str

The directory listing the per-release archives appear in.

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).

pages class-attribute instance-attribute

pages: tuple[str, ...] = ()

Member basenames to pull into man1/ (("ssh.1",) from a source tarball). Empty means the archive already is a bare man tree, unpacked whole (git's manpages tarball).

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 package/repo, else the tool name.

Attributes:

Name Type Description
kind str

uv — a PyPI console script, uv tool install --upgraded into an

package str

The PyPI or npm package, when it differs from the driver's binary name

runtime str

What a node-tier package runs on and installs through: node, unless

repo str

owner/repo for a github / gitlab release download.

note str

Why a deferred source is parked — shown by provision.

floor str

Releases below this are not offered — not listed, not walked, and

plugins tuple[str, ...]

Extra packages to install alongside the tool (uv --with), so a

manual Manual | None

Where the pages live, for kind="man" — required there, unused

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

plugins: tuple[str, ...] = ()

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

target(name: str) -> str

What to fetch: the explicit package/repo, else the tool name.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
def target(self, name: str) -> str:
    """What to fetch: the explicit `package`/`repo`, else the tool *name*."""
    return self.package or self.repo or name

Plugin dataclass

Plugin(name: str, repo: str, owns: str = '', path: str = '', since: str = '')

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 (docker-compose).

repo str

owner/repo of the plugin's own releases.

owns str

The verb prefix these releases account for (compose).

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

name instance-attribute

name: str

The binary as the host tool looks for it (docker-compose).

repo instance-attribute

repo: str

owner/repo of the plugin's own releases.

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: default, available, no.

Attributes:

Name Type Description
name str

The binary as it is invoked.

attr str

tools.<attr>, when it differs from the binary's name.

verbs tuple[str, ...]

The subcommands to stub, dotted for nesting (compose.up). Empty

help_flag str

git's --help opens a man page; -h is the help text.

in_process bool

Whether tools.<attr> prefers in-process, as tools.py builds it.

base tuple[str, ...]

A pre-bound verb: tools.ruff_format is Tool("ruff", "format").

source str

auto prefers structure (click) and falls back to --help.

shorts str

Short-option policy for the stub: "none" never keys on a short,

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 (git help <verb>) instead of its terse

provision Provision

How to fetch the latest binary — the default is a PyPI uv install.

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.

name instance-attribute

name: str

The binary as it is invoked.

attr class-attribute instance-attribute

attr: str = ''

tools.<attr>, when it differs from the binary's name.

verbs class-attribute instance-attribute

verbs: tuple[str, ...] = field(default_factory=tuple)

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

base: tuple[str, ...] = field(default_factory=tuple)

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

provision: Provision = field(default_factory=Provision)

How to fetch the latest binary — the default is a PyPI uv install.

plugins class-attribute instance-attribute

plugins: tuple[Plugin, ...] = field(default_factory=tuple)

Companion programs some of the verbs really come from, each released on its own line — see Plugin.

key property

key: str

wanted property

wanted: tuple[str, ...]

The verbs to read: a pre-bound tool wants only the one it binds.

mode

mode(capable: bool) -> str

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
def mode(self, capable: bool) -> str:
    """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.
    """
    if self.in_process:
        return "default"
    return "available" if capable else "no"

installed

installed(driver: Driver) -> bool

Whether this machine has the tool to ask.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
def installed(driver: Driver) -> bool:
    """Whether this machine has the tool to ask."""
    return _resolve(driver.name) is not None

version

version(name: str) -> str

<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
def version(name: str) -> str:
    """`<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.
    """
    return _read_version(name)[0]

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
def 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.
    """
    from concurrent.futures import ThreadPoolExecutor
    from functools import partial

    wanted = list(names)
    if not wanted:
        return {}
    with ThreadPoolExecutor(max_workers=len(wanted)) as pool:
        first = pool.map(partial(_read_version, timeout=timeout), wanted)
        read = dict(zip(wanted, first, strict=True))
    for name in wanted:
        found, why = read[name]
        if found or why != _timed_out(timeout):
            continue
        again, why_again = _read_version(name, timeout=retry_timeout)
        if again:
            read[name] = (again, "")
        elif why_again == _timed_out(retry_timeout):
            read[name] = ("", f"{why}, then {why_again} alone")
        else:
            read[name] = ("", why_again)
    return read

in_process_capable

in_process_capable(name: str) -> bool

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
def in_process_capable(name: str) -> bool:
    """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.
    """
    import livery.toolroom.tools as tools

    return tools.console_script(name) is not None

extract

extract(driver: Driver, home: Path | None = None) -> ToolSpec

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.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
def extract(driver: Driver, home: Path | None = None) -> ToolSpec:
    """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.
    """
    from livery.toolroom.store import ToolSpec

    spec = ToolSpec(name=driver.name)
    if driver.source in {"auto", "click"}:
        spec = _from_click(driver) or spec
    if not spec.verbs and driver.source in {"auto", "help"}:
        # A fetched manual names its own release, and there is no binary
        # to ask: the whole point of reading the pages is that the version
        # they document never has to be installed.
        tree = _toolhelp._fetched_manpath() if driver.man else ""
        spec = _toolhelp.from_help(
            driver.name,
            binary=_resolve(driver.name),
            verbs=driver.wanted,
            version=(
                _toolhelp.man_version(Path(tree), driver.name)
                if tree
                else version(driver.name)
            ),
            in_process=in_process_capable(driver.name),
            flag=driver.help_flag,
            man=driver.man,
            shorts=driver.shorts,
        )
    return _anonymous(
        _rebase(spec, driver.base) if driver.base else spec,
        *([home] if home else []),
        Path.home(),
    )

find

find(key: str) -> Driver | None

The driver for tools.<key>.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_drivers.py
def find(key: str) -> Driver | None:
    """The driver for `tools.<key>`."""
    for driver in DRIVERS:
        if driver.key == key:
            return driver
    return None