Verbs¶
The verbs by extension¶
fm composes these verbs from the base, the plugins the project mounts and the repository's own tasks file, and an extension's verbs are in its section below; fm <verb> --help describes one.
- livery.workshop: abandon, caches.clear, check, ci.balance, ci.cancel, ci.dispatch, ci.e2e, ci.footprint, ci.logs, ci.profile, ci.rerun, ci.run, ci.scale, ci.status, ci.timings, clean, commit, devenv.down, devenv.ls, devenv.rm, devenv.up, drift, drift.check, env.check, env.emit, env.set, env.show, examples, explain, extensions, format, graph.affected, integrate, issue, issue.close, issue.comment, issue.create, issue.list, issue.reopen, issue.search, issue.show, issue.stop, issue.update, layering, layering.base-imports-no-extension, layering.graph, layering.sibling-references, lint, lock, new.package.workshop-extension, new.project, provenance, release.verify, run, shell, speed.accept, start, status, store.ls, store.show, submit, submit.arm, submit.disarm, submit.merge, sync, test, toolroom.add, toolroom.lock, toolroom.restub, toolroom.sync, typecheck, typecomplete, workflow.abort, workflow.release, workflow.release.dispatch, workflow.update, workflow.update.dependencies
- footman.doctor: doctor
- footman.janitor: janitor
- footman.self: self.add, self.install, self.path, self.remove, self.uninstall
- livery.footman: footman.pages
- livery.forge: forge.conformance, forge.dev.down, forge.dev.restart, forge.dev.seed, forge.dev.up, forge.fixtures.record
- livery.toolroom.bench: toolroom.artifacts, toolroom.assemble, toolroom.audit, toolroom.color, toolroom.docs, toolroom.gather, toolroom.goldens, toolroom.index.build, toolroom.list, toolroom.owed, toolroom.pages, toolroom.prime, toolroom.provision, toolroom.read, toolroom.refresh, toolroom.spec, toolroom.verify, toolroom.verify-host
Each extension the workspace installs, listed or required by one listed, has a block below: what it does, its verbs, its templates, the contract keys and step options it reads, and the installed extensions it contributes to. A package turns any step off with enabled = false in its [phases.<phase>.<step>] table.
basedpyright¶
The type checker basedpyright, warnings as errors, over the python files the root pyrightconfig.json names, and a step that judges every public API type-complete, which a workspace turns on.
| item | kind | what it does |
|---|---|---|
fm typecheck.basedpyright |
verb | Run the typecheck.basedpyright step alone, over the named paths or the workspace; the words after -- go to its tool. |
fm typecomplete.basedpyright |
verb | Run the typecomplete.basedpyright step alone, over the named paths or the workspace; the words after -- go to its tool. |
[phases.typecomplete.basedpyright] enabled = true |
root contract switch | turns on the step, which the extension declares off |
changelog¶
Each package's CHANGELOG.md: at each release, git-cliff writes the entry from the commits since the package's last release tag, as the package's cliff.toml says.
clang-format¶
The C and C++ formatter clang-format, judging each C or C++ package against the style in its .clang-format; under --fix it rewrites the files.
| item | kind | what it does |
|---|---|---|
fm format.clang-format |
verb | Run the format.clang-format step alone, over the named paths or the workspace; the words after -- go to its tool. |
clang-tidy¶
The C and C++ linter clang-tidy, judging each C or C++ package against the checks in its .clang-tidy and the compilation database its build writes.
| item | kind | what it does |
|---|---|---|
fm lint.clang-tidy |
verb | Run the lint.clang-tidy step alone, over the named paths or the workspace; the words after -- go to its tool. |
claude¶
What Claude Code reads in a workspace: CLAUDE.md, the guidance under .workshop/fragments/, and the skills, hooks and settings under .claude/, with the hook verbs those settings run.
coverage¶
Each package's coverage floor, judged on the union of what every CI leg measured, the record that carries it across runs, and the site's coverage pages. It stays dormant until a listed extension measures for it.
| item | kind | what it does |
|---|---|---|
fm coverage.accept |
verb | Lower a package's coverage mark deliberately, with the reason on the record. |
fm coverage.enforce |
verb | Enforce every package's floor on the measured data here. |
[coverage] |
package contract key | the package's coverage policy |
[coverage] floor |
package contract key | the coverage the package keeps: a percentage, or auto-ratchet for the mark its CI runs record; 100 when absent and the package has tests |
[coverage] epsilon |
package contract key | how far, in percentage points, coverage may fall below the floor; 0.5 when absent |
[coverage] required |
package contract key | whether anything judges the package's coverage; true when absent, and false gives no verdict, records no mark and takes no floor |
Contributes to docs and python.
docs¶
The documentation site: its verbs build, serve and publish it from the workspace's docs/ and each package's docs/, and a lint step judges the links in the authored pages.
| item | kind | what it does |
|---|---|---|
fm docs.build |
verb | Mount every package's docs, assemble the config, and build the site, strict. |
fm docs.publish |
verb | Run the deploy phase on the built site, then publish it through the seam. |
fm docs.serve |
verb | Mount every package's docs and serve the site live. |
fm lint.doclinks |
verb | Run the lint.doclinks step alone, over the named paths or the workspace. |
[docs] |
root contract key | the documentation site: its address, its title, its description and where it publishes |
[docs] site-url |
root contract key | the site's public address, ending in a slash, for its canonical links, its llms.txt and the task links in --help, --list and --json rows; no task links when absent |
[docs] title |
root contract key | the site's title; the project's name when absent |
[docs] description |
root contract key | the site's one-line description |
[docs] publish |
root contract key | where the site publishes; the forge's default when absent: pages on GitHub and GitLab, a container on Gitea |
[docs] |
package contract key | how the site documents the package |
[docs] api |
package contract key | whether the package's modules get API reference pages; true when absent |
[docs] generators |
package contract key | the verbs that write the package's pages: a verb's name, or a table with the system packages it needs |
[docs] generators[] |
package contract key | one generator: a verb's name, or a table with the verb, the system packages it needs and the paths it writes |
[docs] generators[].verb |
package contract key | the verb, a task the package ships |
[docs] generators[].requires |
package contract key | the system packages the verb needs on a docs machine |
[docs] generators[].outputs |
package contract key | the paths the verb writes outside the generated trees, each relative to the root, a directory ending in /, or package/ |
[docs] name |
package contract key | the package's place in the site's Packages tree, a dotted path whose last part is its label: workshop.extensions.ruff; its shallowest import path less the namespace every package shares, or its folder under packages/, when absent |
[docs] coverage |
package contract key | the static coverage reports the package's own tooling writes |
[docs] coverage[] |
package contract key | one report: its name on the page and its directory |
[docs] coverage[].label |
package contract key | the report's name on the page |
[docs] coverage[].path |
package contract key | the report's directory, relative to the package |
[docs] extra-css |
package contract key | stylesheets for the package's pages, relative to its docs/ |
[docs] extra-javascript |
package contract key | scripts for the package's pages: a path, or a table with its attributes |
[docs] extra-javascript[] |
package contract key | one script: a path, or a table with its path and the script element's attributes |
[docs] extra-javascript[].path |
package contract key | the script, relative to the package's docs/ |
[docs] extra-javascript[].type |
package contract key | the script element's type |
[docs] extra-javascript[].defer |
package contract key | whether the script runs after the page parses |
[docs] extra-javascript[].async |
package contract key | whether the script runs as soon as it loads |
[phases.docs.task-reference] enabled = true |
root contract switch | turns on the step, which the extension declares off |
mkdocstrings¶
The python API reference on the docs site, a page per module, and the lint steps that judge the docstrings it publishes and the cross-references in them.
| item | kind | what it does |
|---|---|---|
fm lint.docrefs |
verb | Run the lint.docrefs step alone, over the named paths or the workspace. |
fm lint.docstrings |
verb | Run the lint.docstrings step alone, over the named paths or the workspace. |
[phases.docs.mkdocstrings] paths |
package step option, strs, default [] | the directories, relative to the package, the python handler also reads modules from, after its sources |
mypy¶
The type checker mypy, run once for each of linux, darwin and win32, over the python files the root mypy.ini names.
| item | kind | what it does |
|---|---|---|
fm typecheck.mypy |
verb | Run the typecheck.mypy step alone, over the named paths or the workspace; the words after -- go to its tool. |
pyrefly¶
The type checker pyrefly, over every platform at once, on the python files the root pyrefly.toml includes.
| item | kind | what it does |
|---|---|---|
fm typecheck.pyrefly |
verb | Run the typecheck.pyrefly step alone, over the named paths or the workspace; the words after -- go to its tool. |
pytest¶
The test runner pytest: each python package's suite and its documentation examples, run in the workspace's environment. While coverage is listed, it measures every python suite for it.
| item | kind | what it does |
|---|---|---|
fm examples.pytest |
verb | Run the examples.pytest step alone, over the named paths or the workspace; the words after -- go to its tool. |
fm test.pytest |
verb | Run the test.pytest step alone, over the named paths or the workspace; the words after -- go to its tool. |
[phases.test.pytest] parallel |
package step option, bool, default true | run the package's suite across cores; false runs it under -n 0 |
Contributes to coverage.
python¶
Python distributions: each package's version stamped, its wheel and sdist built, published and verified, its suite run against the installed wheel, and the layering rules over the python sources. Its run phase starts the scripts a pyproject.toml names.
| item | kind | what it does |
|---|---|---|
fm layering.declared-imports |
verb | Run the layering.declared-imports step alone, over the named paths or the workspace. |
fm layering.private-reaches |
verb | Run the layering.private-reaches step alone, over the named paths or the workspace. |
fm layering.runner-terminal |
verb | Run the layering.runner-terminal step alone, over the named paths or the workspace. |
fm new.package.python-library <name> |
template | a python library: a typed module, its tests, a pyproject.toml uv builds, and with --command a script on PATH |
fm new.package.python-library --command |
template option, str, default "" | the name of a script on PATH that runs the package's main(); none by default |
[python] |
root contract key | the python extension's settings for the workspace |
[python] private-reaches |
root contract key | each reach into another distribution's private name the private-reaches rule allows, with its reason; an entry no source uses any more refuses |
[python] private-reaches[] |
root contract key | one allowed reach: the distribution that reaches, the private it reaches, and why |
[python] private-reaches[].from |
root contract key | the distribution whose source reaches |
[python] private-reaches[].reaches |
root contract key | the private it reaches, by its dotted path |
[python] private-reaches[].reason |
root contract key | why the reach stays, and the public seam that will replace it |
Contributes to pytest.
ruff¶
The python formatter and linter ruff, over the python files they claim and each conan package's recipe, configured by the root ruff.toml; under --fix they rewrite the files.
| item | kind | what it does |
|---|---|---|
fm format.ruff |
verb | Run the format.ruff step alone, over the named paths or the workspace; the words after -- go to its tool. |
fm lint.ruff |
verb | Run the lint.ruff step alone, over the named paths or the workspace; the words after -- go to its tool. |
ty¶
The type checker ty, over every platform at once, on the python files the root ty.toml includes.
| item | kind | what it does |
|---|---|---|
fm typecheck.ty |
verb | Run the typecheck.ty step alone, over the named paths or the workspace; the words after -- go to its tool. |