Skip to content

Changelog

All notable changes to toolroom are documented here. The format follows Keep a Changelog, and the project follows SemVer — pre-1.0, minor versions may include breaking changes.

Unreleased

Changed

  • The plan records the rulings of 2026-10-18

[0.12.0] - 2026-10-17

Added

  • [coverage] replaces [qa]: the coverage extension declares a package's floor, epsilon and required, a package with tests and no floor is judged at 100, and new projects list coverage by @willemkokke
  • An mkdocstrings extension draws the python API reference and writes its handler's tables through docs.config, the docstring checks move to it, and the kind's extractor goes by @willemkokke
  • Every package lists its extensions, a contract's kind refuses naming the list to write, and the kind fallbacks, the backend protocol and the kind guards go by @willemkokke

Fixed

  • A bytes stdin takes footman's run and the toolroom's handle down a binary lane, no newline translation and the capture decoded with surrogateescape, and the state store writes every blob, the tree and the commit with one fast-import through it by @willemkokke

Changed

  • Raise toolroom's coverage floor to 95 and toolroom-bench's to 89, just under the 95.8% and 89.1% the CI union measures by @willemkokke
  • This repository's packages list their extensions by @willemkokke
  • Remove what the redesigns left behind: the register-and-withdraw functions, dead definitions, leftover sweeps, empty stylesheets and the text naming kinds and seeds by @willemkokke

[0.11.0] - 2026-10-08

Added

  • No package reaches another's privates: footman exports host, CommandView, styled and its brand's names, toolroom its colour and stub tables by @willemkokke

Changed

  • The tool extensions sit inside the workshop's entry of the site's Packages tree, and five contracts state their description by @willemkokke
  • The tool store's table, lock and verbs take toolroom's name, and the store ships the table's schema and its own reader by @willemkokke

[0.10.0] - 2026-10-07

Added

  • Ruff runs as its own extension, a birth finishes in the newborn's own fm, and the local loop tests an extension before its release by @willemkokke
  • Every distribution root declares its public names in its init.py and serves what need not load on first use, and the api modules go by @willemkokke

Fixed

  • The abort reconcile spawns the runner by its real module, two footman invariant tests scan the real tree again, the push guard tests the branch a push names, and the review's smaller faults go by @willemkokke

Changed

  • Footman's internal modules are private, every public module under a root is its api or declared there, and other packages' sources reach footman through its api by @willemkokke

[0.9.0] - 2026-10-04

Added

  • Examples are files: a package's examples live under docs/examples/ as python files a page includes by snippet, and one harness runs each through the kind's runner, replacing footman's page-as-session harness and its three markers by @willemkokke
  • The extractor is data and the development section is pages: the site's handler blocks render from the kind's data, the prose fragments render one page per section, and the mount refuses two pages at one URL by @willemkokke
  • Every distribution root is a namespace whose public names live in its api module, and the docs layer moves to livery.extensions.docs by @willemkokke
  • Extensions replace layers: each declares itself in the workshop.extensions entry point group, and a workspace lists them by name in [workspace] extensions by @willemkokke
  • The copier answers move into workshop.toml: identity in [workspace], members from discovery with their own description, dev-extras and template, and the answers files go by @willemkokke
  • Tasks.py and each package's cliff.toml are composed by the fragment engine, so copier only births by @willemkokke

[0.8.0] - 2026-09-29

Added

  • The release act, the points by hand and the clock on GitLab: the loop is whole on both lanes by @willemkokke
  • The surface rides in the record, and the histories are absorbed by @willemkokke
  • The stubs live in typings/, written from the index, and the toolroom wheel ships none by @willemkokke
  • Stubs for the locked tools only, with sorted imports and a noqa header, declared by a handles module beside them by @willemkokke
  • The store renders stubs from surfaces, and the index holds none by @willemkokke
  • Pyrefly has a record, a stub and a place in the python kind's lock by @willemkokke
  • A package's docs section is the package's, and the site assembles its config at build time by @willemkokke
  • A tool's own switches live in its record's env, and gh's update check leaves the code for the record by @willemkokke
  • The tools lock and sync in uv's shape, and a newborn locks its own by @willemkokke
  • A managed file carries the regions the repository owns by @willemkokke

Fixed

  • The stubs and handles live beside the tools package, never inside its directory by @willemkokke

Changed

  • The tool store plan takes its digests from the host by @willemkokke
  • Pinning reads a digest per host rather than downloading every asset by @willemkokke
  • The contract key type becomes kind by @willemkokke

[0.7.0] - 2026-09-13

Added

  • Contract keys are kebab-case; one loader refuses underscores, the render verbs migrate by @willemkokke
  • Livery.toolroom is a namespace, the handles live in livery.toolroom.tools by @willemkokke
  • A schedule entry runs every week or every two weeks, and the refresh submits what moved by @willemkokke
  • The stub machinery is livery.toolroom.bench, its own distribution by @willemkokke
  • Tests are namespaced by their path, and a helper carries its package's name by @willemkokke

Changed

  • The remaining quick wins on the leg's profile by @willemkokke
  • Plan the tool store over strongroom by @willemkokke
  • The tool store plan gains windows-arm and the checkout's bin directory by @willemkokke
  • The tool store plan names its packages and keeps interpreters with uv by @willemkokke
  • The README's beta note carries no literal minor to roll by @willemkokke
  • The tool store plan records phases 0 and 1 as landed by @willemkokke

[0.6.2] - 2026-09-06

Added

  • Toolroom joins the workspace
  • Footman joins the workspace
  • The version rules speak as the ecosystem's own
  • The train carries a migrated line's first release

Fixed

  • One release number per distribution line
  • The isolated leg answers for its own environment
  • The leg's click exemplar rides the test extra
  • The leg runs serial, and the history ships in the wheel

Unreleased

Added

  • An answer canned but never served warns. A canned prefix that matched no call by a clean answers() block exit raises UnservedAnswers (a Warning): an unmatched call is often incidental, but an unserved table entry is almost always a mis-keyed prefix, and the test was passing vacuously without the answer it meant to inject. Blocks that exit on an exception stay quiet — they already failed loudly — and the category filters or escalates like any warning.

0.6.1 — 2026-08-21

Added

  • Call.args / Call.kwargs — the call as handed. The testing seam's record now carries what the caller wrote, pre-render: positionals verbatim and call keywords with False values included, where the argv honestly omits them. "Never handed" and "handed, as False" are different facts — "python" not in call.kwargs versus call.kwargs["frozen"] is False — and tests can now assert either directly instead of over-rendering flags into an argv no real call would produce. Probe records keep them empty; .flags() keywords stay part of the handle and show only in argv/raw.

Changed

  • The README's minor-pin example can no longer go stale. fm tools.prepare-release rolls the beta note's toolroom~=X.Y.0 alongside the two version files on a minor bump, and a drift test fails the gate whenever the pin and the tree disagree.

0.6.0 — 2026-08-21

Added

  • toolroom.testing — canned answers for bridge calls. A test wraps the code under test in with toolroom.testing.answers({...}) as calls: and every bridge call is answered from the table instead of spawning: keys are argv prefixes (longest match wins), values are canned stdout, an exit code, or a full Result, and the yielded list records each call's argv, environment and run policy for assertions. The handles stay completely real — chaining, flag translation, redaction are the bridge's own — only execution is replaced, at the _host seam both lanes already pass through. A non-zero answer takes the failing lane honestly (ToolError, or footman's RunFailed under answers(hosted=True), which simulates the hosted lane for code written to run in footman tasks). installed_version() is covered too: its spawn moved into the seam as _host.probe() — same semantics, still untouched by --dry-run and recording() — so a test can can a version line while the per-process cache is isolated for the block.

0.5.3 — 2026-08-20

Changed

  • gh 2.98.0 adds --worktree.
  • Provisioned tools get a durable home. With no --prefix, fm tools.provision now materialises into the toolroom room in footman's data directory (~/.local/share/footman/toolroom, moved wholesale by FOOTMAN_DATA_DIR or XDG_DATA_HOME) instead of a .tools-latest in the current directory — and every empty-prefix reading (sync, audit, the tier drives) looks there first when it has been provisioned, falling back to the host's PATH exactly as before when it hasn't. Provision once, and every later reading on the machine uses the isolated set. Breaking for anything that relied on the old .tools-latest default: pass --prefix=.tools-latest to keep it.

0.5.2 — 2026-08-20

Changed

  • bun 1.4.0 adds --asset, --catalog, --define, --disable-warning, --drop, --experimental-stream-iter, --extension-order, --feature, --filter, --heap-prof-interval, --ignore-dce-annotations, --insecure-http-parser, --interactive, --jsx-factory, --jsx-fragment, --jsx-import-source, --jsx-runtime, --jsx-side-effects, --loader, --main-fields, --no-macros, --no-warnings, --pending-deprecation, --preserve-symlinks, --preserve-symlinks-main, --react-compiler, --redirect-warnings, --timings, --tls-max-v1.2, --tls-max-v1.3, --tls-min-v1.0, --tls-min-v1.1, --tls-min-v1.2, --tls-min-v1.3, --trace-deprecation, --trace-warnings, --tsconfig-override, --update-timings and --watch-kill-signal. It also rewords 8 descriptions and restates its own description.
  • claude 2.1.238 adds --yes, over 3 releases. It also rewords 1 description.
  • ssh 10.5p1 adds -Z. It also rewords 2 descriptions and restates its own description.
  • ssh_keygen 10.5p1 rewords 1 description. It also restates its own description.
  • ssh_keyscan 10.5p1 rewords 1 description. It also restates its own description.
  • uv 0.12.5 rewords 34 descriptions.

0.5.1 — 2026-08-16

Fixed

  • A Secret passed through the bridge no longer prints in the clear. A credential flag is exactly the shape a bridged call takes (author=Secret("…") → --author …), and the bridge str()-ed every value on its way to the argv — destroying the type marker footman's display-time redaction keys on, and printing the real value in the shown line, the step receipt, and the failure message. Three changes, none of which imports footman:

  • the execution path passes a str through as its own type — positionals, option values, and the attached --flag=value form all keep the subclass, so the marker reaches the argv (the child always received the real value; subprocess stringifies at the syscall boundary);

  • toolroom's shown line and the standalone Result.command (and with it ToolError's message) render any reveal-carrying value as ***, duck-typed so the bridge never learns who defined it;
  • a secret bound through .flags() redacts as the whole token, flag name included — the safe direction.

str(secret), f-strings, and reveal() still pass in the clear: the caller unwrapping is the caller choosing to expose, which is footman's documented contract. .to_argv() and a built Argv keep real values — they exist to be executed, not shown.

0.5.0 — 2026-08-15

Added

  • Flag, Value, and ValuedFlag are public. The three types every generated signature is written in were private aliases (_Flag, …) — internals-flavoured names in the one place users look, and unimportable for a wrapper that wanted to annotate its own parameters with exactly what a call accepts. They now live on toolroom directly, at runtime too, and every generated stub spells them bare.

Changed

  • Signatures accept paths. The bridge has always str()-ed what it was handed, so ruff.check(Path("src")) ran fine and only the types called it an error. Positionals are str | PathLike[str] now, and Value takes PathLike scalars and sequences alike — the annotations caught up with the runtime.
  • Hover signatures shrank to one line per flag. An option with a closed set of values used to inline its Literal union twice over (Literal[…] | Sequence[Literal[…]] | None — ruff's output_format alone was eight hover lines); each distinct choice set is now a named module-level alias in its tool's stub (OutputFormat, TargetVersion), and checkers render the name. Generated classes derive from ToolBase — the same Tool, imported under a name that reads public in every class header a hover shows. A verb that would collide with a stub import (none does) makes the renderer refuse loudly rather than write a stub that means the wrong thing.
  • Flag help stays on one line per entry. Docstring wraps chosen for the .pyi's column limit landed as hard breaks mid-sentence in every hover; entries are unwrapped now, so each renderer reflows them to its own width.

0.4.0 — 2026-08-09

Changed

  • .opts(color=) now reaches a tool's environment hosted, not just its flags. The mode travels to the executor unresolved — auto means "follow whoever owns the ambient", and inside a run that is the run — so footman's run(color=) applies it to that one child. Before, a per-call colour reached only the tools that take a switch; a tool that reads the environment followed the run-wide answer, because footman owns the child's environment inside a run. One keyword now reaches both halves on both lanes.
  • The keyword arrived in a footman later than the floor toolroom names, so the bridge reads run()'s signature once per process and passes it when it is there. Neither package waits on the other's release, and an older footman still gets the switch half, with a --verbose note saying what a decided colour could not reach.
  • A decided colour merges over an explicit env= rather than deferring to it, matching what run(color=) does hosted: an instruction aimed at one child outranks the environment it was handed. auto still leaves an explicit environment alone — ambient is what that environment already carries.

0.3.0 — 2026-08-09

Added

  • .opts(color="auto"|"always"|"never") — colour, decided per call. "always"/"never" settle that call outright; "auto" (the default) takes the ambient answer. An explicit choice beats NO_COLOR, the same way a --color=always does: an instruction aimed at one call is not the same kind of thing as an environment-wide preference, and it is what lets a colour assertion hold on CI that exports one. An unknown mode is a taught error.

The decision travels on the call rather than through the environment because os.environ is one per process and calls are not — two threads wanting different answers can both have one this way. It drives whichever half of the forcing each tool needs, so a caller never has to know which half that is.

Changed

  • Colour is toolroom's to arrange, from one bit. The seam is now two environment variable names and nothing else: whoever decides — a footman run publishing its answer, a user exporting one, or toolroom reading the terminal — spells it FORCE_COLOR or NO_COLOR, and toolroom translates that into what each tool actually needs. Tools that read the environment get the whole force set written into the child; the few that ignore it get their own switch, as the colour probe found (git's -c color.ui=always). Forcing off clears any inherited force variable rather than setting "0", which a tool reading mere presence would honour straight past NO_COLOR.
  • Standalone, that closes a gap: a spawned tool's stdout is a pipe whenever toolroom captures it, and nothing was writing the force set, so everything but git and cspell came back monochrome even with colour asked for. Forcing over a pipe is what those variables are for.
  • The ambient answer is read from the environment, hosted or not: FORCE_COLOR, CLICOLOR_FORCE, CLICOLOR, NO_COLOR, with FORCE_COLOR taken by truthiness — so an explicit FORCE_COLOR=0 no longer forces — and a dumb terminal counted as no terminal. Inside a footman run that reads the answer the run published at its boundary, so nothing about the outcome changes; what goes is toolroom's last import of footman, and with it the wart where the same call coloured differently depending on whether footman happened to be imported.
  • recording(force_color=True) no longer influences the argv toolroom builds — it never could standalone. Say .opts(color="always") on the call under test instead, which is the more honest spelling anyway: the assertion is about that call.
  • An explicit env= still replaces rather than merges, colour included — the same word it is hosted.
  • The footman dev floor moves to 0.36, whose removal of its own tools bridge finished the split. The repo's tests reached into footman._toolspec and footman._drivers for the drivers and the click reader; both have lived in machinery/ since the split, and now they are read from there.

Fixed

  • A refresh now says which platforms skipped a tool, where they did not all skip it. The assembler folded three legs' skip lists into one and dropped who reported each line, so git (no man to read the pages with) — true only of Windows, which has no man — read in the PR as a tier nobody refreshes. git's pages had in fact been read twice over, on Linux and macOS, which is all a manual needs: the same bytes everywhere. A skip every leg reported still says nothing extra, because that one is a fact about the tool.

0.2.0 — 2026-08-09

Added

  • claude joins the curated tools — Claude Code, read from the @anthropic-ai/claude-code package on the node tier. The headless surface is the root call, so tools.claude("explain this", print=True, output_format="json", model="sonnet") types and completes; the stubbed verbs are the ones a task reaches for around it (mcp.*, plugin.*, auth.*, agents, doctor, update).
  • A Colour page, listing how each curated tool is talked into (and out of) colour over a pipe. It renders from the checked-in colour data on every docs build, so it needs no tool on PATH and cannot drift from what ships — the rule the per-tool pages already follow. The table came over from footman, where it was left orphaned by the split: its data lives here, so its page does too.
  • The docs resolve footman's symbol inventory, so a mention of run() or Result links straight into footman's API reference (and footman's site resolves toolroom's, the other way).

Changed

  • coverage 7.15.4 rewords 1 description. It also restates its own description.
  • python 3.14.7 rewords 1 description.
  • fm tools.color reads only what was provisioned. A verdict is a claim about a release, so it has to come from a release someone fetched: with a --prefix a tool the prefix does not carry is skipped rather than falling through to the host's copy, and without one the probe still prints its table but writes nothing. The write also folds into the checked-in data instead of replacing it — git and the other tools read from their manuals have no binary in any prefix, and a run that wrote only what it saw would have dropped git's -c color.ui=always and taken the bridge's colour forcing with it.

Fixed

  • An option a tool spells two ways now takes its keyword from the spelling Python is written in. Claude Code prints --allowedTools, --allowed-tools, and the first one won, so the stub suggested allowedTools=. Sameness folds case and dashes away before choosing, which is what keeps a neighbour from being mistaken for a dialect: markdownlint-cli2's --configPointer, --config are two different options its column alignment runs into one block, and git prints --column[=<options>], --no-column the same way.
  • The stub generator no longer writes a line its own gate refuses. A summary with no Args: block under it is folded onto one line by the formatter, closing quotes and all, and the wrap left room for only the opening ones — so a summary landing in a two-character band came out at
  • An alone summary is now wrapped for both.
  • fm tools.color --write writes src/toolroom/_colordata.py again. It had been writing src/_colordata.py since the split — the module moved into the package and the path did not follow — so a re-probe wrote a file nothing imports and left the real data untouched.

0.1.1 — 2026-08-05

Fixed

  • .opts(env=…) standalone now means what it means hosted: the child's whole environment, never a merge over the parent's. The divergence was a portability trap between the two lanes, caught by a consumer's sweep.
  • Host detection keys on orchestration, not presence: a call routes through footman only when a footman context is live (a task body, a parallel() worker, a recording() block). A bare call in a process that merely imported footman — a pytest run auto-loading footman's plugin, say — now takes the standalone lane deterministically, so which exception a failure raises never depends on what some other module imported. The same sweep caught this one.

0.1.0 — 2026-08-05

Added

  • The bridge, extracted from footman (footman.tools → toolroom) and reworked to stand alone: typed handles for command-line tools with mechanical keyword-to-flag translation, subcommand chaining, .flags() / .opts() / .at() / .argv, the off sentinel, and installed_version().
  • The seam (toolroom._host): host detection plus a plain subprocess executor. Standalone, calls answer in toolroom's own Result and failures raise ToolError unless nofail; with footman present in the process, the same calls route through footman's run() and inherit capture, replay-on-failure, dry-run, recording(), and --json receipts. Neither package depends on the other.
  • The typed surface: a hand stub and generated per-tool stubs anchored on toolroom, with Argv, Result, and ToolError declared locally so type-checking toolroom never requires footman installed.

Changed

  • djlint 1.44.0 adds --allow-empty-input.

0.0.1 — 2026-08-05

Added

  • Name reservation on PyPI: an empty typed module and the trusted-publishing release workflow. Nothing importable of substance.