feat(facts): add requires_command guard sentinel and preconditions() hook

Background
----------
Two related reliability gaps existed in the fact-collection layer:

1. The old shell guard for requires_command used:

       ! command -v <bin> >/dev/null || (<fact-command>)

   When the binary is absent this produces *no stdout*, making it
   impossible to distinguish "binary not installed" from "binary
   installed but returned no data".  Both cases silently return
   default(), masking real errors.

2. There was no way for a fact to express runtime prerequisites beyond
   "this binary must exist" — e.g. ZFS datasets cannot be listed when
   the zfs kernel module is not loaded, even if the zfs binary is
   present.

Changes
-------

Replace the old `! … ||` guard with an explicit if/then/else that emits
a unique marker when the binary is absent:

    if command -v <bin> >/dev/null 2>&1; then
        (<fact-command>);
    else
        echo '##PYINFRA_NOCMD##';
    fi

The marker `_MISSING_COMMAND_MARKER = "##PYINFRA_NOCMD##"` is detected
in `_get_fact` and converted into a `MissingCommandError` exception so
callers can tell the two cases apart.

    FactError
    └── FactNotCollected          # base: fact skipped, not a data error
        ├── MissingCommandError   # requires_command binary absent
        └── FactPreconditionError # preconditions() not satisfied

All three are exported from `pyinfra.api`.

Both exceptions obey the deploy phase in `get_fact()`:

- **Prepare phase**: silently return `default()`.  The binary / module
  may simply not be installed yet; a later operation will install it.
- **Execute phase**: re-raise.  The binary / module should already be
  present; its absence indicates incorrect ordering in the deploy.

New optional override on `FactBase`:

    def preconditions(self, state, host) -> bool | tuple[Literal[False], str] | None:

Return `True` / `None` to proceed, `False` to skip with a generic
message, or `(False, "human reason")` to skip with context.  The
framework raises `FactPreconditionError` automatically — fact authors
never need to import exception classes.

* `ZfsPools` added with `requires_command = "zpool"`.
* `ZfsDatasets.preconditions()` uses the existing `server.KernelModules`
  fact to verify the zfs kernel module is loaded before attempting
  `zfs get -H all` — a real-world scenario where `requires_command`
  alone is not sufficient.

Tests
-----
* tests/test_api/test_api_facts_missing_command.py — phase-aware
  behaviour for MissingCommandError and the ##PYINFRA_NOCMD## sentinel.
* tests/test_api/test_api_facts_preconditions.py — phase-aware
  behaviour for FactPreconditionError via preconditions().

Author: maisim

CHANGELOG.md

@@ -1,3 +1,16 @@
+# Unreleased
+
+Core:
+
+- api.facts: `requires_command` now uses an if/then/else shell guard with a sentinel marker
+  (`##PYINFRA_NOCMD##`) so that "binary absent" can be distinguished from "binary returned no data"
+- api.facts: add `preconditions(state, host)` hook on `FactBase` for runtime prerequisite checks
+  (e.g. kernel module loaded, service running) — return `False` or `(False, "reason")`
+- api.exceptions: add `FactNotCollected`, `MissingCommandError`, `FactPreconditionError` exception
+  hierarchy; both exceptions are phase-aware (silent during prepare, raised during execute)
+- facts.zfs: fix `ZfsDatasets.requires_command` returning `"zpool"` instead of `"zfs"`; add
+  `ZfsPools` fact; add `ZfsDatasets.preconditions()` checking kernel module via `server.KernelModules`
+
 # v3.7
 
 Thank you to all contributors - particular shout out to @wowi42 for an incredible run of PRs!

docs/api/facts.md

@@ -5,9 +5,78 @@ and a ``process`` function. The command is executed on the target host and the o
 passed (as a ``list`` of lines) to the ``process`` handler to generate fact data. Facts can output anything, normally a ``list`` or ``dict``.
 
 Fact classes may provide a ``default`` function that takes no arguments (except ``self``). The return value of this function is used if an error
-occurs during fact collection. Additionally, a ``requires_command`` variable can be set on the fact that specifies a command that must be available
-on the host to collect the fact. If this command is not present on the host, the fact will be set to the default, or empty if no ``default`` function
-is available.
+occurs during fact collection.
+
+## Guarding against missing binaries: `requires_command`
+
+Override `requires_command` to declare a binary that must be present on the remote host before
+the fact command is run. When the binary is absent pyinfra emits a unique sentinel instead of
+executing the command, then raises `MissingCommandError` internally:
+
+```py
+from pyinfra.api import FactBase
+
+class ZfsPools(FactBase):
+    def requires_command(self) -> str:
+        return "zpool"
+
+    def command(self) -> str:
+        return "zpool get -H all"
+```
+
+**Phase-aware behaviour** — The exception is handled differently depending on the deploy phase:
+
+- **Prepare phase**: the fact returns `default()` silently. The binary may simply not be
+  installed yet; a later operation will install it.
+- **Execute phase**: `MissingCommandError` is re-raised so the developer knows the deploy
+  is incorrectly ordered (the install step must come first).
+
+## Checking runtime prerequisites: `preconditions()`
+
+Some facts require more than just a binary — they need a specific runtime state (e.g. a kernel
+module loaded, a service running). Override `preconditions` to express these checks:
+
+```py
+from pyinfra.api import FactBase
+
+class ZfsDatasets(FactBase):
+    def requires_command(self) -> str:
+        return "zfs"
+
+    def preconditions(self, state, host):
+        from pyinfra.facts.server import KernelModules
+        modules = host.get_fact(KernelModules) or {}
+        if "zfs" not in modules:
+            return False, "kernel module 'zfs' is not loaded"
+
+    def command(self) -> str:
+        return "zfs get -H all"
+```
+
+Return values:
+
+| Return value | Meaning |
+|---|---|
+| `True` or `None` | Prerequisites satisfied — proceed normally |
+| `False` | Prerequisite not satisfied, no reason given |
+| `(False, "reason")` | Prerequisite not satisfied with a human-readable explanation |
+
+The framework raises `FactPreconditionError` automatically and applies the same
+phase-aware behaviour as `requires_command`: silent during prepare, raised during execute.
+Fact authors never need to import any exception class.
+
+## Exception hierarchy
+
+All "fact skipped" situations use a common base class so callers can catch at any level:
+
+```
+FactError
+└── FactNotCollected          # base: fact could not be collected
+    ├── MissingCommandError   # requires_command binary absent
+    └── FactPreconditionError # preconditions() not satisfied
+```
+
+All three are exported from `pyinfra.api`.
 
 ## Importing & Using Facts
 

src/pyinfra/api/__init__.py

@@ -11,11 +11,14 @@
 from .deploy import deploy  # noqa: F401 # pragma: no cover
 from .exceptions import (  # noqa: F401
     DeployError,  # noqa: F401 # pragma: no cover
+    FactPreconditionError,
     FactError,
+    FactNotCollected,
     FactProcessError,
     FactTypeError,
     FactValueError,
     InventoryError,
+    MissingCommandError,
     OperationError,
     OperationTypeError,
     OperationValueError,

src/pyinfra/api/exceptions.py

@@ -60,6 +60,39 @@ class NestedOperationError(OperationError):
     """
 
 
+class FactNotCollected(FactError):
+    """
+    Base exception raised when a fact could not be collected (e.g. binary absent
+    on the remote host, or the fact was skipped by a condition).
+    """
+
+
+class MissingCommandError(FactNotCollected):
+    """
+    Exception raised when ``requires_command`` specifies a binary that is
+    not present on the remote host.  The fact returns its ``default()`` value
+    instead of raising, unless explicitly configured otherwise.
+    """
+
+    def __init__(self, command: str) -> None:
+        self.command = command
+        super().__init__(f"Command not found on remote host: {command}")
+
+
+class FactPreconditionError(FactNotCollected):
+    """
+    Exception raised when a fact's ``preconditions()`` check is not satisfied
+    on the remote host (e.g. a kernel module is not loaded).  Like
+    ``MissingCommandError``, this is silenced during the prepare phase and
+    re-raised during execute.
+    """
+
+    def __init__(self, fact_cls: type, reason: str) -> None:
+        self.fact_cls = fact_cls
+        self.reason = reason
+        super().__init__(f"Fact precondition not satisfied ({fact_cls.__name__}): {reason}")
+
+
 class DeployError(PyinfraError):
     """
     User exception for raising in deploys or sub deploys.

src/pyinfra/api/facts.py

@@ -14,7 +14,7 @@
 import re
 from inspect import getcallargs
 from socket import error as socket_error, timeout as timeout_error
-from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, Type, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Callable, Generic, Literal, Optional, Type, TypeVar, cast
 
 import click
 import gevent
@@ -24,7 +24,7 @@
 from pyinfra import logger
 from pyinfra.api import StringCommand
 from pyinfra.api.arguments import all_global_arguments, pop_global_arguments
-from pyinfra.api.exceptions import FactProcessError
+from pyinfra.api.exceptions import FactPreconditionError, FactProcessError, MissingCommandError
 from pyinfra.api.util import (
     get_kwargs_str,
     log_error_or_warning,
@@ -36,10 +36,14 @@
 from pyinfra.progress import progress_spinner
 
 from .arguments import CONNECTOR_ARGUMENT_KEYS
+from .state import StateStage
 
 if TYPE_CHECKING:
     from pyinfra.api import Host, State
 
+# Sentinel output line emitted when skip_unless_command binary is absent on the remote host.
+_MISSING_COMMAND_MARKER = "##PYINFRA_NOCMD##"
+
 SUDO_REGEX = r"^sudo: unknown user"
 SU_REGEXES = (
     r"^su: user .+ does not exist",
@@ -60,8 +64,27 @@ class FactBase(Generic[T]):
     command: Callable[..., str | StringCommand]
 
     def requires_command(self, *args, **kwargs) -> str | None:
+        """Return the binary name that must exist on the remote host for this fact to run.
+        If the binary is absent the fact returns its ``default()`` value silently.
+        """
         return None
 
+    def preconditions(
+        self, state: "State", host: "Host"
+    ) -> bool | tuple[Literal[False], str] | None:
+        """Check that this fact's prerequisites are satisfied before running.
+
+        Override this method to call ``host.get_fact(...)`` and return:
+
+        - ``True`` (or ``None``) — all prerequisites satisfied, proceed normally
+        - ``False`` — prerequisite not satisfied, no reason given
+        - ``(False, "reason message")`` — prerequisite not satisfied with explanation
+
+        The framework handles raising ``FactPreconditionError`` and phase-awareness
+        automatically; fact authors never need to import exception classes.
+        """
+        return True
+
     @override
     def __init_subclass__(cls) -> None:
         super().__init_subclass__()
@@ -186,15 +209,45 @@ def get_fact(
             apply_failed_hosts=apply_failed_hosts,
         )
 
-    return _get_fact(
-        state,
-        host,
-        cls,
-        args,
-        kwargs,
-        ensure_hosts,
-        apply_failed_hosts,
-    )
+    try:
+        return _get_fact(
+            state,
+            host,
+            cls,
+            args,
+            kwargs,
+            ensure_hosts,
+            apply_failed_hosts,
+        )
+    except MissingCommandError as e:
+        # During the prepare phase the binary might not yet be installed (a prior
+        # operation will install it).  Silently return the default so change
+        # detection can proceed normally.
+        if state.current_stage != StateStage.Execute:
+            logger.debug(
+                "Fact %s skipped on %s during prepare: %s",
+                cls.__name__,
+                host.print_prefix,
+                e,
+            )
+            return cls().default()
+        # During the execute phase the binary should already be present.  If it
+        # isn't, the deploy is incorrectly ordered (missing an install step).
+        # Re-raise so the error surface is clear and actionable.
+        raise
+    except FactPreconditionError as e:
+        # Same phase-aware logic: a precondition not satisfied during prepare
+        # is normal (e.g. kernel module not yet loaded); during execute it is an
+        # ordering error in the deploy.
+        if state.current_stage != StateStage.Execute:
+            logger.debug(
+                "Fact %s skipped on %s during prepare: %s",
+                cls.__name__,
+                host.print_prefix,
+                e,
+            )
+            return cls().default()
+        raise
 
 
 def _get_fact(
@@ -229,20 +282,33 @@ def _get_fact(
     if fact.shell_executable:
         global_kwargs["_shell_executable"] = fact.shell_executable
 
+    # Check preconditions before running this fact's command.
+    # preconditions() returns True/None (ok), False (fail), or (False, reason).
+    pre = fact.preconditions(state, host)
+    if pre is not True and pre is not None:
+        reason = pre[1] if isinstance(pre, tuple) else f"{cls.__name__} preconditions not met"
+        raise FactPreconditionError(cls, reason)
+
     command = _make_command(fact.command, fact_kwargs)
     requires_command = _make_command(fact.requires_command, fact_kwargs)
     if requires_command:
         command = StringCommand(
-            # Command doesn't exist, return 0 *or* run & return fact command
-            "!",
+            # If binary exists → run the fact command; otherwise emit the sentinel so
+            # pyinfra can distinguish "binary absent" from "no output".
+            "if",
             "command",
             "-v",
             requires_command,
             ">/dev/null",
-            "||",
+            "2>&1;",
+            "then",
             "(",
             command,
-            ")",
+            ");",
+            "else",
+            "echo",
+            f"'{_MISSING_COMMAND_MARKER}';",
+            "fi",
         )
 
     status = False
@@ -268,6 +334,17 @@ def _get_fact(
 
     stdout_lines, stderr_lines = output.stdout_lines, output.stderr_lines
 
+    # Detect the "binary absent" sentinel from the if/then/else shell guard.
+    if status and stdout_lines == [_MISSING_COMMAND_MARKER]:
+        cmd_str = str(requires_command) if requires_command else ""
+        logger.debug(
+            "Skipping fact %s on %s: command not found: %s",
+            name,
+            host.print_prefix,
+            cmd_str,
+        )
+        raise MissingCommandError(cmd_str)
+
     data = fact.default()
 
     if status:

src/pyinfra/facts/zfs.py

@@ -32,14 +32,22 @@ def process(self, output):
 
 
 class ZfsDatasets(FactBase):
-    @override
-    def command(self) -> str:
-        return "zfs get -H all"
-
     @override
     def requires_command(self) -> str:
         return "zfs"
 
+    @override
+    def preconditions(self, state, host):
+        from pyinfra.facts.server import KernelModules
+
+        modules = host.get_fact(KernelModules) or {}
+        if "zfs" not in modules:
+            return False, "kernel module 'zfs' is not loaded"
+
+    @override
+    def command(self) -> str:
+        return "zfs get -H all"
+
     @override
     def process(self, output):
         return _process_zfs_props_table(output)