livery.toolroom.bench._tasks¶
livery.toolroom.bench._tasks ¶
Keep the tool records honest — fm tools ….
The bridge never goes stale, because it transcribes nothing. A tool's
record can: it describes the tool at the versions read, and tools
move. These tasks close that gap by reading the installed tools into
the records and by failing a check when a tool and its record disagree.
A stub is a rendering of a record, written by the index build and
materialised into a workspace by fm toolroom.restub; nothing here writes
one into a package.
fm toolroom.list what footman curates, and what's installed
fm toolroom.spec ruff what one tool says about itself, right now
fm toolroom.read read the installed tools into their records
fm toolroom.audit which tools have moved past their record
fm toolroom.color how footman forces colour, per tool
A reading is a snapshot, not a contract: sync takes one, audit says
which tools have released a newer version since. Being behind is news
rather than a fault, so audit reports and exits zero unless you ask for
--strict, and the readings are retaken by the refresh rather than the
moment a tool ships. A snapshot only ever moves forward: a tool that isn't
installed, is missing from a --prefix, or reads older than the record
already holds is named and left alone — a check that quietly covered three
of thirteen would be worse than no check.
Attributes:
| Name | Type | Description |
|---|---|---|
tasks |
Group
|
|
OBSERVATION_SCHEMA
module-attribute
¶
The observation document's shape. Bumped when a reader must know.
index_tasks
module-attribute
¶
index_tasks = tasks.group('index', help='The published index of the tool records')
STUBS_MODULE
module-attribute
¶
The module the docs pages' stubs are rendered as, for the docs build's renderer.
HostCheck
dataclass
¶
One tool's executable check on this host.
Attributes:
| Name | Type | Description |
|---|---|---|
tool |
str
|
The record's name. |
version |
str
|
The version checked, the newest with a build for the host. |
outcome |
str
|
|
detail |
str
|
What happened, in the words a reviewer acts on. |
Methods:
| Name | Description |
|---|---|
__str__ |
|
Gathered
dataclass
¶
Gathered(platform: str, observations: dict[str, dict[str, dict[str, Any]]], holes: dict[str, list[str]] = dict(), unreachable: dict[str, str] = dict(), skipped: list[str] = list())
What one platform saw, as data — the document a matrix leg hands on.
Deliberately portable rather than a CI internal: written by
fm toolroom.gather --out=…, copied off a Windows box by hand if that is
how the week goes, and folded by fm toolroom.assemble wherever the store
lives. Self-describing, because the machine that reads it is not the
machine that wrote it.
Methods:
| Name | Description |
|---|---|
document |
|
Attributes:
| Name | Type | Description |
|---|---|---|
platform |
str
|
Who looked — the one fact every observation in this document shares. |
observations |
dict[str, dict[str, dict[str, Any]]]
|
|
holes |
dict[str, list[str]]
|
Releases this platform meant to read and could not. Carried rather |
unreachable |
dict[str, str]
|
Indexes that would not answer here. Carried so the assembler can tell |
skipped |
list[str]
|
Tools with no index, or no history to add to, on this platform. |
platform
instance-attribute
¶
platform: str
Who looked — the one fact every observation in this document shares.
observations
instance-attribute
¶
tool -> version -> {date, tag, surface}: what this platform found.
holes
class-attribute
instance-attribute
¶
Releases this platform meant to read and could not. Carried rather than dropped: the assembler reports them, a later run fills them.
unreachable
class-attribute
instance-attribute
¶
Indexes that would not answer here. Carried so the assembler can tell "this leg saw nothing new" from "this leg could not look".
Owed
dataclass
¶
What a gather would read, without reading any of it.
Attributes:
| Name | Type | Description |
|---|---|---|
releases |
dict[str, list[str]]
|
Versions this platform owes a reading of, per tool. |
unreachable |
dict[str, str]
|
Indexes that would not answer. Not the same as nothing to do — a |
skipped |
list[str]
|
Tools with no index to read, or no record to add to. |
total |
int
|
|
releases
instance-attribute
¶
Versions this platform owes a reading of, per tool.
unreachable
instance-attribute
¶
Indexes that would not answer. Not the same as nothing to do — a walk that cannot see an index cannot say the index has nothing new.
skipped
instance-attribute
¶
Tools with no index to read, or no record to add to.
Refreshed
dataclass
¶
Refreshed(read: dict[str, list[str]], events: dict[str, list[str]], unreachable: dict[str, str], skipped: list[str], holes: dict[str, list[str]] = dict(), wrote_changelog: bool = False, release: bool = False, additions_only: bool = False, ingest: dict[str, list[str]] = dict(), ingest_ok: bool = True, artifacts: dict[str, list[str]] = dict())
What a refresh found — the release decision, as data.
Returned rather than printed, so fm --json toolroom.refresh hands a
scheduled job the same answer a person reads.
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
Attributes:
| Name | Type | Description |
|---|---|---|
read |
dict[str, list[str]]
|
Releases newly observed, per tool, oldest first. |
events |
dict[str, list[str]]
|
The subset of those that are newer than anything seen before and |
unreachable |
dict[str, str]
|
Indexes that would not answer, and why. Not the same as a tool with |
skipped |
list[str]
|
Tools with no index to read, or no record to add to. |
holes |
dict[str, list[str]]
|
Releases that were listed but could not be observed — an install that |
wrote_changelog |
bool
|
Whether the events reached |
release |
bool
|
Whether any tool's surface moved — decision 4, in one line. A field |
additions_only |
bool
|
Whether every surface change across every announced event only ADDED |
ingest |
dict[str, list[str]]
|
Per announced tool, the ingest verification's lines: the verdict, |
ingest_ok |
bool
|
Whether every ingest check passed on every host of every event |
artifacts |
dict[str, list[str]]
|
Per tool read from a forge tier, the artifact step's lines: the |
armed |
bool
|
Whether the pull request arms: additions only and every check passed. |
read
instance-attribute
¶
Releases newly observed, per tool, oldest first.
events
instance-attribute
¶
The subset of those that are newer than anything seen before and changed the tool's surface. This is the release decision and the CHANGELOG line at once — so a backfill, which reaches only downwards, is saved and reported but never announced.
unreachable
instance-attribute
¶
Indexes that would not answer, and why. Not the same as a tool with
nothing new — see _toolfetch.Unreachable.
skipped
instance-attribute
¶
Tools with no index to read, or no record to add to.
holes
class-attribute
instance-attribute
¶
Releases that were listed but could not be observed — an install that failed, a binary that would not describe itself. A hole is not an error: the record stays whole by construction, a later run fills it, and until then a change the missing release carried reads as arriving at the next release actually read.
wrote_changelog
class-attribute
instance-attribute
¶
wrote_changelog: bool = False
Whether the events reached CHANGELOG.md. False with nothing to say,
and false when the file has no [Unreleased] section to write into —
which a caller should notice rather than assume the notes got written.
release
class-attribute
instance-attribute
¶
release: bool = False
Whether any tool's surface moved — decision 4, in one line. A field
rather than a property, and recomputed from events on construction:
dataclasses.asdict serialises fields only, and this is the one value
the scheduled job reads out of fm --json toolroom.refresh.
additions_only
class-attribute
instance-attribute
¶
additions_only: bool = False
Whether every surface change across every announced event only ADDED to a tool's surface — nothing dropped, no verb withdrawn. Half of the graded release trigger's green light: additions cannot break a caller. False when there are no events at all (nothing to ship is not "safe to ship"). Rewordings count as additions-safe: they change what a stub says, never what a tool accepts.
ingest
class-attribute
instance-attribute
¶
Per announced tool, the ingest verification's lines: the verdict, each finding and each host's structural diff, for every event version that has a host (livery.toolroom.bench._ingest). Empty for a tool whose versions have no host, since there is nothing to stage.
ingest_ok
class-attribute
instance-attribute
¶
ingest_ok: bool = True
Whether every ingest check passed on every host of every event version: the other half of the green light. True when nothing had a host to check, so a tool read but never downloaded arms as before.
artifacts
class-attribute
instance-attribute
¶
Per tool read from a forge tier, the artifact step's lines: the hosts each fresh version gained, the assets they came from, and any version whose artifacts could not be recorded.
default_prefix ¶
default_prefix() -> Path
Where provisioned tools live when no --prefix names another place.
A toolroom-bench room in footman's data directory: durable, never
touched by the cache collector, and moved wholesale by
FOOTMAN_DATA_DIR (or XDG_DATA_HOME). One machine-level home,
instead of a .tools-latest in whichever directory the command
happened to run from, and beside the store's own toolroom home,
never inside it: the store's bin directory is not a provisioned
prefix.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
list_ ¶
list_(show: Annotated[Literal['all', 'installed', 'missing'], doc('which tools to list (default: all, present or not)')] = 'all') -> None
The curated tools: version, in-process capability, stub state.
Every curated tool is listed by default, absent ones included — the
version column says not installed. --show installed narrows to what
this machine can actually run, --show missing to what it can't.
A present tool whose version will not read is a different fact from an
absent one, and the column says which: unreadable (timed out after
30s), never a false not installed — the CI contradiction that
conflation produced (a row both passing the installed filter and
claiming absence) is exactly what the diagnosis channel exists to
prevent.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
spec ¶
spec(name: Annotated[str, doc('a curated tool: ruff, uv, mkdocs, …')], verb: Annotated[str, doc('one verb, dotted for nesting (compose.up)')] = '') -> None
Print what a tool says about itself, as footman reads it.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
read ¶
read(only: Annotated[str, doc('regenerate just this tool')] = '', prefix: Annotated[str, doc("read binaries from this prefix's bin/")] = '') -> None
Read the tools installed on this machine into their records.
A reading is a snapshot: what one tool accepted at one version, on
one machine. Point --prefix at a fm toolroom.provision directory to
take that snapshot from the isolated latest set instead of whatever
this machine has — a dev environment's pytest carries its plugins'
flags too, and those do not belong in a record whose driver never
asked for them.
A tool that isn't installed keeps the record that is checked in — there is nothing to read it from, and a record that exists beats one that was emptied because a laptop happened to be missing a binary.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
audit ¶
audit(only: Annotated[str, doc('check just this tool')] = '', fix: Annotated[bool, doc('take a fresh snapshot instead of reporting')] = False, prefix: Annotated[str, doc("read binaries from this prefix's bin/")] = '', strict: Annotated[bool, doc('exit non-zero when a snapshot is behind')] = False) -> dict[str, object]
Report which tools have moved on since their record's newest reading.
A record holds what one tool accepted at the versions it was read
from. Tools keep releasing, and footman promises no particular speed
at following them — so a tool showing up here means a newer version
exists, not that anything is wrong. Every stubbed verb ends in
**flags: Any, so the bridge already speaks a flag the record has
never heard of; only the hint is behind. --fix takes a fresh
reading, --strict gives automation something to trip on, and
--prefix asks the question against a provisioned latest set rather
than this machine.
A snapshot only ever moves forward, so two readings are worth less
than the record already checked in and are named and left alone: a
tool missing from --prefix (a partial provision must not read as
drift, and the host's copy is not the answer), and one whose version
is older than the record holds (a machine behind the one that took
the snapshot has nothing to add). Neither counts as behind — they are
unanswered.
One finding here is a fault, and always exits non-zero: footman's negation and wrapper tables are read by the runtime, so a disagreement there means a task emits the wrong command today.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
color ¶
color(only: Annotated[str, doc('probe just this tool')] = '', write: Annotated[bool, doc("regenerate toolroom's _colordata.py")] = True, prefix: Annotated[str, doc("probe binaries from this prefix's bin/")] = '') -> None
Probe how footman forces colour for each installed tool, and regenerate the colour data.
footman spawns over pipes (no PTY), so it forces colour into the tools it
spawns — by the environment (FORCE_COLOR/NO_COLOR) for the modern set, by
the tool's own switch for the few that ignore it. Which is which is probed,
not assumed: each tool is run with colour forced on and off, and the bytes
read, so a direction is recorded env, flag (like git's
-c color.ui=always), none, or unprobed (no trigger figured out).
Writes toolroom's _colordata.py, which the bridge reads for its forcing
table and the docs read for the support table — and only ever from a
--prefix, a fm toolroom.provision directory. A verdict is a claim about a
release, so it has to come from a release someone fetched on purpose:
without a prefix this machine's own binaries answer, at whatever versions
it happens to carry and missing whatever it never installed. That reads
fine as a table on a terminal, which is why it still prints one; it is not
something to check in.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
verify_host ¶
verify_host(*, store: _Installer | None = None, only: str = '', run: Callable[[list[str]], tuple[int, str]] | None = None, extract: Callable[[Driver], ToolSpec] | None = None) -> list[HostCheck]
The executable checks on this host: each downloaded tool installs, runs, reads.
For each curated tool whose record is a downloaded kind, the newest version with a build for this host is supplied through store, its first entry point is run with the driver's help flag, and its surface is extracted from the installed tree and must describe the tool. A download with no entry point is not a program, and the presence of the files its env names is the whole check. A tool with no build for this host is skipped and says so. store, run and extract are the seams the tests drive; the defaults are the bench's store, a subprocess with a two-minute limit, and the bench's own extractor.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 | |
tools_verify_host ¶
Install, run and read every downloaded tool on this host; red when one fails.
The six-host verification point's task: for each curated tool of a downloaded kind, the newest version with a build for this host installs through the bench's store, its entry point runs with the driver's help flag, and its surface extracts to a reading that describes the tool. A tool with no build for this host is skipped and says so.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
colour_page ¶
colour_page() -> str
The colour support page, rendered from the checked-in colour data.
Reads toolroom's probed table (livery.toolroom.tools.colour_controls),
not a live probe, so a docs build needs nothing on PATH and the page
says exactly what ships — the same rule the per-tool pages follow.
fm toolroom.color refreshes the data; the page follows on the next
build.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
prime ¶
prime(only: Annotated[str, doc('prime just this tool')] = '', count: Annotated[int, doc('how many releases back to read')] = 20, keep: Annotated[bool, doc('leave the throwaway environments behind')] = False, prefix: Annotated[str, doc("drive the tiers from this prefix's bin/")] = '') -> None
Read past releases into the option history, deepening each chain.
Reaches below each tool's floor, up to --count releases further back.
Nothing already written is touched, and a release the chain already has
is skipped — so a prime interrupted by a rate limit is resumed by
running it again.
The releases are gathered in parallel, a bounded wave at a time —
installing a release and reading its --help depends on no other
release, and the chain assembles whatever order the observations arrive
in. A release that will not install, or whose binary will not describe
itself, is a hole: named in the report, filled by a later run, and
never the end of the tool's walk.
--prefix points at a fm toolroom.provision directory, and the tiers are
driven from its binaries. That is not the same nicety it is on sync:
uv carries CPython's download index inside itself, so a stale uv reports
a stale newest python and the walk silently starts too low.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 | |
gather ¶
gather(only: Annotated[str, doc('gather just this tool')] = '', prefix: Annotated[str, doc("drive the tiers from this prefix's bin/")] = '', out: Annotated[str, doc('write the observation document here')] = '', count: Annotated[int, doc('also reach this many releases below the floor')] = 0) -> Gathered
Observe every release this platform has not yet accounted for.
Half of a refresh, and the half that must happen on the platform: a
Linux box cannot tell you what a tool's --help says on Windows. It
writes no store — only a document saying what this machine saw — so the
three platforms of a matrix can run at once and nothing races for the
files.
What it observes: every release newer than each tool's base, every hole
the chain reports, and the base itself when this platform has not looked
at it yet — that last one is what makes a new platform's coverage
converge on the versions people are actually running, in one pass.
--count also reaches below the floor, for deepening a platform's
history the way prime does.
--out writes the document for another machine to fold; without it the
document is returned (and printed under --json), which is what
refresh uses when both halves run in one process.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 | |
owed ¶
owed(only: Annotated[str, doc('ask about just this tool')] = '', prefix: Annotated[str, doc("drive the tiers from this prefix's bin/")] = '', count: Annotated[int, doc('also reach this many releases below the floor')] = 0) -> Owed
What this platform would read, without installing anything.
A gather provisions every tool and then discovers there is nothing to observe — which is most weeks, since a store that is current stays current until something ships. Listing is network and nothing else, so the question "is there any work" can be answered before the work is prepared for.
One tool must be current for the answer to be true: uv carries CPython's download index inside the binary, so a stale uv reports a stale newest python and this says "nothing owed" about a release it cannot see. Provision uv, ask this, and only then provision the rest.
An index that would not answer is not nothing to do — unreachable
is reported separately for exactly that reason.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
assemble ¶
assemble(documents: Annotated[list[str], doc('observation documents to fold in')], changelog: Annotated[bool, doc('write the events into CHANGELOG.md')] = True) -> Refreshed
Fold gathered observations into the store — the single-writer half.
Every platform's reading of one release is folded into one surface and one sidecar before the chain is touched, so a matrix run never writes the churn of an option being inserted, dropped and resurrected as each leg's turn comes. Then releases go in oldest first, and a release the chain already holds is merged rather than replaced.
One process, one owner per file. Three machines committing to
tool-history/ on their own would be three whole-file conflicts a week:
git is not a merge engine for this, and the algebra is.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
refresh ¶
refresh(only: Annotated[str, doc('refresh just this tool')] = '', prefix: Annotated[str, doc("drive the tiers from this prefix's bin/")] = '', changelog: Annotated[bool, doc('write the events into CHANGELOG.md')] = True, submit: Annotated[bool, doc('commit what moved on a branch and open its pull request')] = False) -> Refreshed
Observe what is new on this platform, and fold it into the store.
gather then assemble, in one process — the whole job when one
machine is the whole matrix, and exactly the two halves the weekly
workflow runs on three machines and one assembler. There is no third
code path: what runs locally is what runs in CI, with the document
handed across a function call instead of an artifact.
Nothing new anywhere means nothing to release, and that is the whole exit condition. An index that would not answer is reported and exits non-zero rather than counting as "nothing new": a rename or a moved repo would otherwise make a tool silently untracked while the job kept reporting success.
With --submit, a refresh that moved a tool's surface is
committed on the day's branch and submitted as a pull request:
armed when every change only added to a surface, the graded
trigger's green light, and left for a person otherwise. A day's
branch that origin already holds with every file this refresh
wrote means the day's refresh is already submitted. Nothing moved
means no branch and no pull request. A refresh asked to submit
submits from the history of origin's default branch alone, so on
another checkout, a branch a rehearsal runs on among them, it
observes nothing and says so.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
submit_refresh ¶
submit_refresh(found: Refreshed, *, git: Callable[..., Result] | None = None, submit: Callable[[list[str]], int] | None = None, on: date | None = None, dry_run: bool | None = None) -> list[str]
Commit a refresh that moved something and open its pull request.
The branch is chore/tools-refresh-<date>, cut from HEAD, and a
refresh submits only from the history of origin's default branch:
on another checkout it submits nothing and says so, and the files it
wrote stand. When origin already
holds the day's branch, from an earlier refresh on another machine
or in another job, the refresh compares and moves nothing: when
that branch holds every file this refresh wrote, with the same
content, it submits nothing and says the day's refresh is already
submitted; otherwise it stops, naming the branch and the files that
differ, for a person to merge or close that pull request and run
the refresh again. The checkout stays on its own tree either way:
the run reads its code and declarations from the checkout after the
refresh, and the day's branch can be cut from an older main. Origin
is asked before anything in the checkout changes, so a refresh that
cannot ask it leaves the checkout as the walk left it.
The pull request is armed when Refreshed.armed holds, every change
an addition and every ingest check passed, and unarmed otherwise, so
a dropped verb or a deployment that does not stand waits for a
person. The commit body carries the ingest lines,
so the pull request's summary is the structural diff. A refresh that
moved nothing opens nothing and says so. Under a dry run nothing is
committed or submitted: the lines say what would happen, the arming
decision included.
git, submit, on and dry_run are the seams the tests drive; the defaults are the git tool handle, the runner's own submit verb, today, and the run's own dry-run flag. git answers each command with its exit code and output and never raises; a code this does not expect fails the refresh in git's own words.
Returns:
| Type | Description |
|---|---|
list[str]
|
The lines to print, one per step. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 | |
observe ¶
observe(tool: str, version: str, tag: str = '', date: str = '', published: str = '', requires_python: str = '', scratch: str = '') -> dict[str, Any] | None
Install one release, read what it accepts, and throw it away.
The unit of the gather, pure in (tool, version): requests for the same release dedupe on the futures work key, and arrival order is nobody's business: the record places each version at its own position whatever order these finish in.
A real task deliberately, not a helper. The task boundary is what buys
each observation its own environment: a body call copies the caller's
overlay, so the PATH written around extraction here is this
observation's alone, while the sandbox variables and prefix PATH the
caller set flow in — and on into every subprocess the tiers spawn.
None — a release that would not install, or a binary that would not
describe itself — is a hole for the caller to report, never an error:
the chain stays contiguous by construction, and a later run fills it.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 | |
tools_verify ¶
tools_verify(tool: Annotated[str, doc('the curated tool, as its record is named')], version: Annotated[str, doc('the version to check; the newest with a host when empty')] = '') -> None
Run the ingest checks on one version of a tool for every host, from here.
Each host's artifact is staged through the bench's store and looked at; the verdict, each finding and each host's structural diff against the version before it print, and a finding is red.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
tools_artifacts ¶
tools_artifacts(tool: Annotated[str, doc('the curated tool, as its record is named')], version: Annotated[str, doc('the version to record; the newest when empty')] = '') -> None
Record a version's release artifacts per host, then run the ingest checks.
For a tool read from a forge tier: the release's asset for each host is downloaded once, hashed and written on the version line, a host the release has no asset for is left absent, and the nine checks then run on every host recorded. The record is saved before the checks, so a finding is red with the artifacts in place for the fix. A version already read from another index, as a tool has before it moves to its own release, is addressed by its version when no forge tag is known for it.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
index_build ¶
index_build(into: Annotated[str, doc('the index root; omitted = docs/tools in the workspace')] = '', from_genesis: Annotated[bool, doc('ignore the build already there and materialise every tool')] = False) -> Built
Materialise every record into the index: a strongroom store and its pointer.
The index is a strongroom store served as static files, one tree per
tool holding the tool axis, each version's deployment per host and
its surface as one blob, and beside it pointer.json naming each
tool's current tree. A build into a directory that already
holds one reads its pointer and reuses every tool whose record did
not move; --from-genesis ignores the pointer and rebuilds every
tool, and two builds from genesis land the same objects and the same
pointer.
Declared as a docs generator, so the site's build writes the index
under docs/tools and the site's deploy serves it at tools/.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
golden_records ¶
The golden records, small and shaped to exercise the renderer.
golden_path ¶
Where record's stub at version is checked in.
goldens ¶
goldens(check: Annotated[bool, doc('report what differs instead of writing')] = False) -> dict[str, list[str]]
Render the golden records, the golden stubs and the records' schema.
A golden is a small record shaped to exercise the renderer, and its
stub at every version is checked in, rendered as a consumer renders
the version it locks. The test compares each render with its golden
byte for byte, so a change to the renderer fails the gate until this
verb moves the goldens in the same change, which is what keeps a
render change deliberate. records/record.schema.json is the same
kind of file, exported from the record's shape and compared by a
test, so it moves here too. --check names what would move and
writes nothing.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
provision ¶
provision(only: Annotated[str, doc('provision just this tool')] = '', prefix: Annotated[Path | None, doc("directory to materialise into; omitted = footman's data dir")] = None, sync_: Annotated[bool, doc('run `tools read` against the prefix afterwards')] = False, clean: Annotated[bool, doc('remove the prefix when done')] = False, strict: Annotated[bool, doc('fail if any tier could not be provisioned')] = False) -> None
Fetch the latest curated tools into an isolated prefix — no pollution.
The records are read from installed binaries, so syncing against the newest
release means having it on PATH. This gathers the latest of every curated
tool under one isolated prefix — uv tool install for the PyPI wheels
(the Rust and C++ tools included), bun's own release then bun add for the
node CLIs, a release asset for the Go ones — touching nothing outside it.
Omitted, the prefix is the toolroom-bench room in footman's data directory,
which every empty-prefix reading looks in first, so provisioning once
serves every later sync/audit on this machine. --sync reads the
records against the prefix; --clean deletes it, which is the whole undo.
--strict turns a failed tier into a failed run. Without it the table
names what did not arrive and the run still succeeds, which is right
for a person deciding what to do next and wrong for a job that will
read the prefix and believe it.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 | |
pages ¶
pages(out: Annotated[Path, doc('directory to write the reference pages into')], nav: Annotated[Path | None, doc('the generated docs tree to emit the Tools nav block into')] = None, stubs: Annotated[Path | None, doc("directory to render the pages' stubs into")] = None) -> None
Write one reference page per tool, plus the index table.
Rendered from the records rather than from the installed tools, so
the docs build needs nothing on PATH and says exactly what the records
hold. The stubs the pages point at are written as the module
toolroom_stubs under stubs, <out>/../stubs/toolroom_stubs by
default, a search path the docs build adds for its renderer. Tools
are ordered alphabetically. With nav, the Tools nav block is
emitted into that generated tree too, so the sidebar can never fall
behind the drivers again.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
write_tools_nav ¶
Emit the Tools nav block's entries from keys into generated; the path.
The block is data the docs site reads: nav.tools.toml beside the
pages, a nav list of one-key tables, each a label to its page. The
bench writes the file itself, since only an extension that requires
another imports it, and the bench is no extension.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_tasks.py
nav_keys ¶
The tool keys the emitted Tools nav block at block lists, in order.