"""Filesystem checks shared by secret provisioning and handoff paths."""
from __future__ import annotations

from pathlib import Path


def containing_git_worktree(path: Path) -> Path | None:
    """Return the nearest enclosing Git worktree, if one is identifiable.

    A real worktree has either a ``.git`` file (linked worktrees/submodules) or
    a ``.git`` directory containing ``HEAD``. Merely finding an empty directory
    named ``.git`` is not enough; sandbox and test environments may use such a
    marker outside any repository.
    """
    resolved = path.expanduser().resolve()
    for parent in (resolved.parent, *resolved.parent.parents):
        marker = parent / ".git"
        if marker.is_file() or (marker.is_dir() and (marker / "HEAD").is_file()):
            return parent
    return None