Usages:
  conventions: .goga/usages/conventions.md
  gitpython: .goga/usages/cooks/gitpython.md

Annotations: |
  Read-only access to the git repository holding specifications.
  Swax never commits or pushes — clone, read, discard the clone.

  Use `conventions` for code writing rules and testing.
  Use `gitpython` for repository cloning and error mapping.

---

"clone_specs(repo_url: str, specs_location: str) -> Iterator[specs_path: pathlib.Path]":
  location: clone_specs.py
  annotations: |
    Context manager: clones the repository into a temporary directory and yields
    the path to the specs subdirectory for the duration of the with block. Cleanup
    is guaranteed even on exception.

    `repo_url`: clone URL of the repository holding API specifications.
    `specs_location`: subdirectory inside the repository where specs live.
    `specs_path`: path to the specs directory inside the clone, valid only within the context.

    Algorithm:
    1. Create a temporary directory and shallow-clone the repository into it.
    2. Locate the specs subdirectory inside the clone.
    3. Yield the resolved path.
    4. On exit (normal or exception) remove the temporary directory.

    Requirements:
    - Shallow clone — only the latest commit is needed.
    - The temporary directory is cleaned up on every outcome.
    - GitPython errors are wrapped into RepositoryCloneError with the URL and reason.

    Constraints:
    - Credentials are not embedded in the URL — private repositories rely on git credential helpers.
    - The yielded path does not outlive the context — the temporary directory is deleted on exit.

"RepositoryCloneError(url: str, reason: str)":
  location: errors.py
  annotations: |
    Raised by clone_specs when cloning the repository fails.

    `url`: clone URL that failed.
    `reason`: original error message from GitPython.

"SpecsNotFoundError(path: pathlib.Path)":
  location: errors.py
  annotations: |
    Raised by clone_specs when the declared specs_location does not exist inside the clone.

    `path`: expected path that was not found.

---

Author: Goga
CreatedAt: 25/06/26
Description: |
  Git repository cloning for reading API specifications (read-only access).
