Skip to content

livery.workshop._doctor

livery.workshop._doctor

The workshop's doctors, registered under footman's footman.doctors group.

Four: the forge doctor, which reaches the forge and says who you are there, which server it is, what it grants, whether every declared owner exists and which admin token ladder is set; the host doctor, which reads the machine, the compilers the workspace's packages need, the tools the host serves, the listed extensions that are dormant, and the installed extensions the contract does not list; the uv cache doctor, which measures uv's cache against the workspace's limit; and the ssh doctor, which says whether the git plugin shares one connection per host and names a ControlMaster entry of the person's own. Each returns findings (livery.footman.Finding). Only the finding of a cache over its limit carries a repair, the prune fm doctor --fix runs; every other fix is a person's. fm doctor prints them, footman's own first.

Functions:

Name Description
forge_findings

The forge doctor's findings for forge; root's contract is read when given.

forge

The forge doctor: who you are on the forge, what it is, what it grants.

host

The host doctor: compilers, the host's tools, dormant and unlisted extensions.

unlisted

The doctor's line for an installed extension the workspace lists nowhere.

ssh

The ssh doctor: the shared connection, and a person's own multiplexing.

parse_size

The bytes a size such as 10G or 500M names.

show_size

A size in the largest unit that keeps one decimal, 47.2G.

uv_cache_dir

Where uv keeps its cache on this machine, as the locked uv answers.

prune_uv_cache

Drop the cache entries nothing references, through the locked uv.

uv_cache

The uv cache doctor: its size against the limit the workspace sets.

Attributes:

Name Type Description
CAPABILITIES tuple[Capability, ...]
UV_CACHE_LIMIT

CAPABILITIES module-attribute

CAPABILITIES: tuple[Capability, ...] = ('auto_merge', 'force_cancel', 'required_contexts', 'ci_secrets', 'schedule_events')

UV_CACHE_LIMIT module-attribute

UV_CACHE_LIMIT = '10G'

forge_findings

forge_findings(forge: Forge, root: Path | None) -> list[Finding]

The forge doctor's findings for forge; root's contract is read when given.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def forge_findings(forge: Forge, root: Path | None) -> list[Finding]:
    """The forge doctor's findings for *forge*; *root*'s contract is read when given."""
    findings: list[Finding] = []
    if root is not None:
        from livery.workshop._governance import unknown_owners
        from livery.workshop._tokens import admin_token

        contract = load_contract(root / "workshop.toml")
        owner = str((contract.get("forge") or {}).get("owner", ""))
        kind = str((contract.get("forge") or {}).get("kind", ""))
        url = str((contract.get("forge") or {}).get("url", ""))
        _, admin_var = admin_token(kind, url)
        if admin_var.startswith("FORGE_ADMIN_TOKEN"):
            findings.append(Finding(f"admin ladder: {admin_var} set"))
        elif admin_var:
            findings.append(
                Finding(
                    "admin ladder: FORGE_ADMIN_TOKEN unset"
                    f" ({admin_var} is the fallback)"
                )
            )
        else:
            findings.append(
                Finding(
                    "admin ladder: FORGE_ADMIN_TOKEN unset"
                    " (everyday token is the fallback)"
                )
            )
        try:
            unknown = unknown_owners(root, forge, owner)
        except Exception as error:
            findings.append(Finding(f"owners: not checked ({error})"))
        else:
            for entry in unknown:
                findings.append(
                    Finding(
                        "owners",
                        f"unknown {entry}",
                        "add the user or team on the forge, or drop it from the"
                        " contract's owners",
                    )
                )
            if not unknown:
                findings.append(
                    Finding("owners: every declared owner exists on the forge")
                )
    findings.append(Finding(f"{forge.whoami()} on {forge.server_version()}"))
    granted = [name for name in CAPABILITIES if forge.supports(name)]
    missing = [name for name in CAPABILITIES if name not in granted]
    if granted:
        findings.append(Finding(f"grants: {', '.join(granted)}"))
    if missing:
        findings.append(
            Finding(
                "grants",
                f"missing: {', '.join(missing)}",
                "a token or a plan that grants them; the workshop works around"
                " each one it lacks",
            )
        )
    else:
        findings.append(Finding("every capability the workshop can use is granted"))
    return findings

forge

forge(**facts: Any) -> list[Finding]

The forge doctor: who you are on the forge, what it is, what it grants.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def forge(**facts: Any) -> list[Finding]:
    """The forge doctor: who you are on the forge, what it is, what it grants."""
    from livery.workshop._forge_lane import this_forge

    root = workspace_root()
    if root is None:
        return [Finding("forge: no workspace here, not checked")]
    return forge_findings(this_forge(root), root)

host

host(**facts: Any) -> list[Finding]

The host doctor: compilers, the host's tools, dormant and unlisted extensions.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def host(**facts: Any) -> list[Finding]:
    """The host doctor: compilers, the host's tools, dormant and unlisted extensions."""
    from livery.workshop._env_tasks import missing_host_tools, served_by
    from livery.workshop._extensions import (
        available_extensions,
        composes_per_package,
        dormancy,
        extension_names,
    )
    from livery.workshop._tools import tool_receipts

    root = workspace_root()
    if root is None:
        return [Finding("host: no workspace here, not checked")]
    findings: list[Finding] = []
    missing = list(missing_host_tools(root))
    for tool in missing:
        findings.append(
            Finding(
                f"host: {tool}",
                "MISSING, a compiler the workspace's packages need",
                "install the platform toolchain",
            )
        )
    if not missing:
        findings.append(
            Finding("host: every compiler the workspace's packages need is present")
        )
    hosted = [
        f"{name} ({served_by(receipt)})"
        for name, receipt in sorted(tool_receipts(root).items())
        if receipt.source == "host"
    ]
    if hosted:
        findings.append(Finding(f"tools: served by the host: {', '.join(hosted)}"))
    for name, waits in dormancy(root).items():
        # Information, not a fault: a listing kept for a contributor
        # still to come is a statement of intent.
        findings.append(Finding(f"extensions: {name}: dormant, {waits}"))
    for module, dist in available_extensions(extension_names(root)):
        # Information, not a fault: an extension a wheel ships that this
        # workspace has no use for is the common case.
        findings.append(
            Finding(unlisted(module, dist, per_package=composes_per_package(module)))
        )
    return findings

unlisted

unlisted(module: str, dist: str, *, per_package: bool) -> str

The doctor's line for an installed extension the workspace lists nowhere.

The root's list takes any extension, and a package's list one that composes something in a package. The line names [workspace] extensions, and a package's extensions too when per_package says the extension composes something in a package that holds it (livery.workshop._extensions.composes_per_package).

Source code in packages/workshop/src/livery/workshop/_doctor.py
def unlisted(module: str, dist: str, *, per_package: bool) -> str:
    """The doctor's line for an installed extension the workspace lists nowhere.

    The root's list takes any extension, and a package's list one that
    composes something in a package. The line names `[workspace]
    extensions`, and a package's `extensions` too when *per_package*
    says the extension composes something in a package that holds it
    ([livery.workshop._extensions.composes_per_package][]).
    """
    named = f" ({dist})" if dist else ""
    places = "[workspace] extensions"
    if per_package:
        places += " or a package's extensions"
    return (
        f"extensions: {module}{named} is installed and not listed; it does"
        f" nothing until {places} names it"
    )

ssh

ssh(**facts: Any) -> list[Finding]

The ssh doctor: the shared connection, and a person's own multiplexing.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def ssh(**facts: Any) -> list[Finding]:
    """The ssh doctor: the shared connection, and a person's own multiplexing."""
    import livery.footman as footman
    from livery import git

    del facts
    findings: list[Finding] = []
    config = Path.home() / ".ssh" / "config"
    if config.is_file():
        lines = [
            line.strip()
            for line in config.read_text("utf-8", errors="replace").splitlines()
            if line.strip().lower().startswith(("controlmaster", "controlpath"))
        ]
        if lines:
            findings.append(
                Finding(
                    f"ssh: {config} multiplexes on its own ({'; '.join(lines)}); the"
                    " git plugin's command adds a master beside it"
                )
            )
    socket_dir = git.ssh_sockets(footman.data_dir())
    environment, reason = git.ssh_environment(
        socket_dir,
        configured=git.config_get(footman.cwd(), "core.sshCommand"),
    )
    if reason:
        findings.append(
            Finding(reason, "", f"delete {socket_dir / 'unsupported'} to try again")
        )
    elif not environment:
        findings.append(
            Finding("ssh: a command of your own stands; the plugin adds nothing")
        )
    else:
        findings.append(
            Finding(f"ssh: one connection per host, sockets in {socket_dir}")
        )
    return findings

parse_size

parse_size(text: str) -> int

The bytes a size such as 10G or 500M names.

Raises:

Type Description
ValueError

for any other shape, naming the accepted one.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def parse_size(text: str) -> int:
    """The bytes a size such as ``10G`` or ``500M`` names.

    Raises:
        ValueError: for any other shape, naming the accepted one.
    """
    match = re.fullmatch(r"\s*(\d+(?:\.\d+)?)\s*([KMGT])B?\s*", text, flags=re.I)
    if match is None:
        raise ValueError(
            f"{text!r} is not a size: a number with K, M, G or T, like 10G"
        )
    return int(float(match.group(1)) * _UNITS[match.group(2).upper()])

show_size

show_size(size: int) -> str

A size in the largest unit that keeps one decimal, 47.2G.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def show_size(size: int) -> str:
    """A size in the largest unit that keeps one decimal, ``47.2G``."""
    for unit in ("T", "G", "M", "K"):
        if size >= _UNITS[unit]:
            return f"{size / _UNITS[unit]:.1f}{unit}"
    return f"{size}B"

uv_cache_dir

uv_cache_dir() -> Path

Where uv keeps its cache on this machine, as the locked uv answers.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def uv_cache_dir() -> Path:
    """Where uv keeps its cache on this machine, as the locked uv answers."""
    from livery.toolroom import tools

    result = tools.uv.opts(nofail=True, recorded=False)("cache", "dir")
    if result.code != 0:
        raise RuntimeError(
            f"uv cache dir exited {result.code}: {result.stderr.strip()}"
        )
    return Path(result.stdout.strip())

prune_uv_cache

prune_uv_cache() -> None

Drop the cache entries nothing references, through the locked uv.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def prune_uv_cache() -> None:
    """Drop the cache entries nothing references, through the locked uv."""
    from livery.toolroom import tools

    tools.uv.opts(recorded=False)("cache", "prune")

uv_cache

uv_cache(**facts: Any) -> list[Finding]

The uv cache doctor: its size against the limit the workspace sets.

Source code in packages/workshop/src/livery/workshop/_doctor.py
def uv_cache(**facts: Any) -> list[Finding]:
    """The uv cache doctor: its size against the limit the workspace sets."""
    root = workspace_root()
    if root is None:
        return [Finding("uv cache: no workspace here, not checked")]
    workspace = load_contract(root / "workshop.toml").get("workspace") or {}
    declared = str(workspace.get("uv-cache-limit", UV_CACHE_LIMIT))
    try:
        limit = parse_size(declared)
    except ValueError as error:
        return [
            Finding(
                "uv cache",
                f"[workspace] uv-cache-limit: {error}",
                "set it to a size such as 10G in workshop.toml",
            )
        ]
    try:
        cache = uv_cache_dir()
    except RuntimeError as error:
        return [Finding("uv cache", str(error), "fm sync installs the locked uv")]
    size = _tree_size(cache) if cache.is_dir() else 0
    if size <= limit:
        return [Finding(f"uv cache: {show_size(size)}, under the {declared} limit")]
    return [
        Finding(
            "uv cache",
            f"{show_size(size)}, over the {declared} limit",
            "fm doctor --fix runs `uv cache prune`; `uv cache clean` empties it;"
            " raise [workspace] uv-cache-limit in workshop.toml if this machine"
            " needs a larger one",
            prune_uv_cache,
        )
    ]