github2gerrit 0.1.10__py3-none-any.whl → 0.1.11__py3-none-any.whl

github2gerrit/rich_logging.py

@@ -0,0 +1,316 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2025 The Linux Foundation
+
+"""
+Rich-aware logging infrastructure to prevent interference with Rich displays.
+
+This module provides a centralized logging system that detects when Rich
+displays are active and routes log messages appropriately to avoid breaking
+clean terminal output.
+
+Key features:
+- Automatic detection of Rich display contexts
+- Clean routing of ERROR/WARNING logs through Rich console when available
+- Background-only logging for DEBUG/INFO when Rich is active
+- Seamless fallback to normal logging when Rich is not available
+- Thread-safe operation for concurrent logging
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+from typing import ClassVar
+
+
+try:
+    from rich.console import Console
+    from rich.logging import RichHandler
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+    Console = None
+    RichHandler = None
+
+
+class RichAwareLogger:
+    """
+    Rich-aware logging coordinator that manages logging behavior based on
+    whether Rich displays are currently active.
+
+    This class provides a global registry of active Rich display contexts
+    and routes logging calls appropriately to prevent interference.
+    """
+
+    _instance: ClassVar[RichAwareLogger | None] = None
+    _lock: ClassVar[threading.Lock] = threading.Lock()
+
+    def __init__(self) -> None:
+        """Initialize the Rich-aware logger."""
+        self._active_rich_contexts: set[str] = set()
+        self._rich_console: Console | None = None
+        self._original_handlers: dict[str, list[logging.Handler]] = {}
+        self._rich_handlers_installed = False
+        self._context_lock = threading.Lock()
+
+        if RICH_AVAILABLE:
+            # Create a dedicated Rich console for logging
+            self._rich_console = Console(stderr=True, markup=False)
+
+    @classmethod
+    def get_instance(cls) -> RichAwareLogger:
+        """Get the singleton instance of RichAwareLogger."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def register_rich_context(self, context_id: str) -> None:
+        """
+        Register an active Rich display context.
+
+        Args:
+            context_id: Unique identifier for the Rich display context
+        """
+        with self._context_lock:
+            was_empty = len(self._active_rich_contexts) == 0
+            self._active_rich_contexts.add(context_id)
+
+            # If this is the first Rich context, install Rich handlers
+            if was_empty and RICH_AVAILABLE:
+                self._install_rich_handlers()
+
+    def unregister_rich_context(self, context_id: str) -> None:
+        """
+        Unregister a Rich display context.
+
+        Args:
+            context_id: Unique identifier for the Rich display context
+        """
+        with self._context_lock:
+            self._active_rich_contexts.discard(context_id)
+
+            # If no more Rich contexts, restore original handlers
+            if len(self._active_rich_contexts) == 0:
+                self._restore_original_handlers()
+
+    def is_rich_active(self) -> bool:
+        """Check if any Rich display contexts are currently active."""
+        with self._context_lock:
+            return len(self._active_rich_contexts) > 0 and RICH_AVAILABLE
+
+    def _install_rich_handlers(self) -> None:
+        """Install Rich-aware logging handlers."""
+        if not RICH_AVAILABLE or self._rich_handlers_installed:
+            return
+
+        # Get the root logger and key module loggers
+        loggers_to_modify = [
+            logging.getLogger(),  # Root logger
+            logging.getLogger("github2gerrit"),
+            logging.getLogger("github2gerrit.cli"),
+            logging.getLogger("github2gerrit.core"),
+            logging.getLogger("github2gerrit.duplicate_detection"),
+            logging.getLogger("github2gerrit.external_api"),
+            logging.getLogger("github2gerrit.gerrit_rest"),
+            logging.getLogger("github2gerrit.gitutils"),
+        ]
+
+        for logger in loggers_to_modify:
+            logger_name = logger.name or "root"
+
+            # Store original handlers
+            self._original_handlers[logger_name] = logger.handlers.copy()
+
+            # Remove existing handlers
+            for handler in logger.handlers[:]:
+                logger.removeHandler(handler)
+
+            # Add Rich-aware handler for ERROR and WARNING levels
+            rich_handler = RichAwareHandler(self._rich_console)
+            rich_handler.setLevel(
+                logging.WARNING
+            )  # Only handle WARNING and ERROR
+            logger.addHandler(rich_handler)
+
+            # Add silent handler for INFO and DEBUG (logs to file but not
+            # console)
+            silent_handler = SilentHandler()
+            silent_handler.setLevel(logging.DEBUG)
+            logger.addHandler(silent_handler)
+
+        self._rich_handlers_installed = True
+
+    def _restore_original_handlers(self) -> None:
+        """Restore original logging handlers."""
+        if not self._rich_handlers_installed:
+            return
+
+        for logger_name, original_handlers in self._original_handlers.items():
+            logger = logging.getLogger(
+                logger_name if logger_name != "root" else None
+            )
+
+            # Remove Rich handlers
+            for handler in logger.handlers[:]:
+                logger.removeHandler(handler)
+
+            # Restore original handlers
+            for handler in original_handlers:
+                logger.addHandler(handler)
+
+        self._original_handlers.clear()
+        self._rich_handlers_installed = False
+
+
+class RichAwareHandler(logging.Handler):
+    """
+    Logging handler that routes ERROR/WARNING messages through Rich console
+    when Rich displays are active.
+    """
+
+    def __init__(self, rich_console: Console | None = None) -> None:
+        """Initialize the Rich-aware handler."""
+        super().__init__()
+        self._rich_console = rich_console
+
+        # Set up formatting
+        formatter = logging.Formatter("%(levelname)s: %(message)s")
+        self.setFormatter(formatter)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Emit a log record through Rich console."""
+        if not self._rich_console:
+            return
+
+        try:
+            msg = self.format(record)
+
+            # Choose style based on log level
+            if record.levelno >= logging.ERROR:
+                style = "red"
+                prefix = "❌"
+            elif record.levelno >= logging.WARNING:
+                style = "yellow"
+                prefix = "⚠️"
+            else:
+                style = "white"
+                prefix = "i"
+
+            # Print through Rich console
+            self._rich_console.print(f"{prefix} {msg}", style=style)
+
+        except Exception:
+            # Fallback to handleError if Rich printing fails
+            self.handleError(record)
+
+
+class SilentHandler(logging.Handler):
+    """
+    Handler that silently discards log messages.
+
+    This is used for INFO and DEBUG messages when Rich is active,
+    to prevent them from interfering with Rich displays while still
+    allowing them to be captured by file handlers if configured.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Silently discard the log record."""
+        # Do nothing - this prevents console output
+
+
+class RichDisplayContext:
+    """
+    Context manager for Rich display contexts.
+
+    This should be used around any Rich display operations to ensure
+    that logging doesn't interfere with clean Rich output.
+
+    Example:
+        with RichDisplayContext("progress_tracker"):
+            # Rich display operations
+            console.print(table)
+            # Logging here won't interfere with Rich display
+    """
+
+    def __init__(self, context_id: str) -> None:
+        """
+        Initialize Rich display context.
+
+        Args:
+            context_id: Unique identifier for this display context
+        """
+        self.context_id = context_id
+        self._logger = RichAwareLogger.get_instance()
+
+    def __enter__(self) -> RichDisplayContext:
+        """Enter the Rich display context."""
+        self._logger.register_rich_context(self.context_id)
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit the Rich display context."""
+        self._logger.unregister_rich_context(self.context_id)
+
+
+def setup_rich_aware_logging() -> None:
+    """
+    Initialize Rich-aware logging for the entire application.
+
+    This should be called early in the application lifecycle,
+    typically in the main CLI entry point.
+    """
+    # Just ensure the singleton is created - actual setup happens
+    # when Rich contexts are registered
+    RichAwareLogger.get_instance()
+
+
+def is_rich_logging_active() -> bool:
+    """
+    Check if Rich-aware logging is currently active.
+
+    Returns:
+        True if Rich displays are active and logging is being routed
+        through Rich console, False otherwise.
+    """
+    return RichAwareLogger.get_instance().is_rich_active()
+
+
+# Convenience functions for common logging patterns that are Rich-aware
+def rich_error(message: str, *args: Any) -> None:
+    """Log an error message in a Rich-aware manner."""
+    logger = logging.getLogger("github2gerrit")
+    logger.error(message, *args)
+
+
+def rich_warning(message: str, *args: Any) -> None:
+    """Log a warning message in a Rich-aware manner."""
+    logger = logging.getLogger("github2gerrit")
+    logger.warning(message, *args)
+
+
+def rich_info(message: str, *args: Any) -> None:
+    """Log an info message in a Rich-aware manner."""
+    logger = logging.getLogger("github2gerrit")
+    logger.info(message, *args)
+
+
+def rich_debug(message: str, *args: Any) -> None:
+    """Log a debug message in a Rich-aware manner."""
+    logger = logging.getLogger("github2gerrit")
+    logger.debug(message, *args)
+
+
+__all__ = [
+    "RichAwareLogger",
+    "RichDisplayContext",
+    "is_rich_logging_active",
+    "rich_debug",
+    "rich_error",
+    "rich_info",
+    "rich_warning",
+    "setup_rich_aware_logging",
+]

github2gerrit/similarity.py

@@ -16,8 +16,10 @@ Design goals:
 - Explainability: each scorer returns both a score and human-readable reasons.
 
 Implementation notes:
-- Most functions are fully implemented with robust normalization and scoring logic.
-- The similarity scoring system supports exact matches, fuzzy matching, and automation-aware detection.
+- Most functions are fully implemented with robust normalization and scoring
+  logic.
+- The similarity scoring system supports exact matches, fuzzy matching, and
+  automation-aware detection.
 """
 
 from __future__ import annotations
@@ -68,6 +70,10 @@ class ScoringConfig:
     workflow_min_floor: float = 0.50
 
 
+# Default scoring configuration singleton
+_DEFAULT_SCORING_CONFIG = ScoringConfig()
+
+
 @dataclass(frozen=True)
 class ScoreResult:
     """
@@ -174,7 +180,9 @@ def remove_commit_trailers(message: str) -> str:
     """
     lines = (message or "").splitlines()
     out: list[str] = []
-    trailer_re = re.compile(r"(?i)^(change-id|signed-off-by|issue-id|github-hash|github-pr|co-authored-by):")
+    trailer_re = re.compile(
+        r"(?i)^(change-id|signed-off-by|issue-id|github-hash|github-pr|co-authored-by):"
+    )
     for ln in lines:
         if trailer_re.match(ln.strip()):
             continue
@@ -267,7 +275,11 @@ def classify_automation_context(
         signals.append("dependabot")
     if "pre-commit" in text or ".pre-commit-config.yaml" in text:
         signals.append("pre-commit")
-    if "github actions" in text or ".github/workflows" in text or "uses:" in text:
+    if (
+        "github actions" in text
+        or ".github/workflows" in text
+        or "uses:" in text
+    ):
         signals.append("github-actions")
     # Deduplicate while preserving order
     seen: set[str] = set()
@@ -308,7 +320,9 @@ def score_subjects(
         pkg_src = extract_dependency_package_from_subject(src)
         pkg_cand = extract_dependency_package_from_subject(candidate_subject)
         if pkg_src and pkg_cand and pkg_src == pkg_cand:
-            return ScoreResult(score=1.0, reasons=[f"Same dependency package: {pkg_src}"])
+            return ScoreResult(
+                score=1.0, reasons=[f"Same dependency package: {pkg_src}"]
+            )
         r = sequence_ratio(src_norm, cand_norm)
         if r > best_ratio:
             best_ratio = r
@@ -323,7 +337,7 @@ def score_files(
     source_files: Sequence[str],
     candidate_files: Sequence[str],
     *,
-    workflow_min_floor: float = ScoringConfig.workflow_min_floor,
+    workflow_min_floor: float | None = None,
 ) -> ScoreResult:
     """
     Score similarity based on changed file paths.
@@ -334,6 +348,8 @@ def score_files(
     - If both sides include one or more files under .github/workflows/,
       floor the score to workflow_min_floor.
     """
+    if workflow_min_floor is None:
+        workflow_min_floor = ScoringConfig.workflow_min_floor
 
     def _nf(p: str) -> str:
         q = (p or "").strip().lower()
@@ -354,7 +370,8 @@ def score_files(
         reasons.append("Both modify workflow files (.github/workflows/*)")
     if src_set or cand_set:
         reasons.append(
-            f"File overlap Jaccard: {score:.2f} (|n|={len(src_set & cand_set)}, |U|={len(src_set | cand_set)})"
+            f"File overlap Jaccard: {score:.2f} "
+            f"(|n|={len(src_set & cand_set)}, |U|={len(src_set | cand_set)})"
         )
     return ScoreResult(score=score, reasons=reasons)
 
@@ -371,18 +388,28 @@ def score_bodies(
     # Very short bodies: exact match or zero
     if len(source_body.strip()) < 50 or len(candidate_body.strip()) < 50:
         if normalize_body(source_body) == normalize_body(candidate_body):
-            return ScoreResult(score=1.0, reasons=["Short bodies exactly match"])
+            return ScoreResult(
+                score=1.0, reasons=["Short bodies exactly match"]
+            )
         return ScoreResult(score=0.0, reasons=[])
     reasons: list[str] = []
     # Automation-aware checks
     src_text = source_body or ""
     cand_text = candidate_body or ""
-    src_is_dep = "dependabot" in src_text.lower() or "dependency-name:" in src_text.lower()
-    cand_is_dep = "dependabot" in cand_text.lower() or "dependency-name:" in cand_text.lower()
+    src_is_dep = (
+        "dependabot" in src_text.lower()
+        or "dependency-name:" in src_text.lower()
+    )
+    cand_is_dep = (
+        "dependabot" in cand_text.lower()
+        or "dependency-name:" in cand_text.lower()
+    )
     if src_is_dep and cand_is_dep:
         pkg1 = ""
         pkg2 = ""
-        m1 = re.search(r"dependency-name:\s*([^\s\n]+)", src_text, flags=re.IGNORECASE)
+        m1 = re.search(
+            r"dependency-name:\s*([^\s\n]+)", src_text, flags=re.IGNORECASE
+        )
         m2 = re.search(
             r"dependency-name:\s*([^\s\n]+)",
             cand_text,
@@ -393,16 +420,28 @@ def score_bodies(
         if m2:
             pkg2 = m2.group(1).strip()
         if pkg1 and pkg2 and pkg1 == pkg2:
-            return ScoreResult(score=0.95, reasons=[f"Dependabot package match: {pkg1}"])
+            return ScoreResult(
+                score=0.95, reasons=[f"Dependabot package match: {pkg1}"]
+            )
         # Different packages -> slight similarity for being both dependabot
         reasons.append("Both look like Dependabot bodies")
         # do not return yet; fall through to normalized ratio
-    src_is_pc = "pre-commit" in src_text.lower() or ".pre-commit-config.yaml" in src_text.lower()
-    cand_is_pc = "pre-commit" in cand_text.lower() or ".pre-commit-config.yaml" in cand_text.lower()
+    src_is_pc = (
+        "pre-commit" in src_text.lower()
+        or ".pre-commit-config.yaml" in src_text.lower()
+    )
+    cand_is_pc = (
+        "pre-commit" in cand_text.lower()
+        or ".pre-commit-config.yaml" in cand_text.lower()
+    )
     if src_is_pc and cand_is_pc:
-        return ScoreResult(score=0.9, reasons=["Both look like pre-commit updates"])
+        return ScoreResult(
+            score=0.9, reasons=["Both look like pre-commit updates"]
+        )
     src_is_actions = (
-        "github actions" in src_text.lower() or ".github/workflows" in src_text.lower() or "uses:" in src_text.lower()
+        "github actions" in src_text.lower()
+        or ".github/workflows" in src_text.lower()
+        or "uses:" in src_text.lower()
     )
     cand_is_actions = (
         "github actions" in cand_text.lower()
@@ -412,7 +451,12 @@ def score_bodies(
     if src_is_actions and cand_is_actions:
         a1 = re.search(r"uses:\s*([^@\s]+)", src_text, flags=re.IGNORECASE)
         a2 = re.search(r"uses:\s*([^@\s]+)", cand_text, flags=re.IGNORECASE)
-        if a1 and a2 and a1.group(1).strip() and a1.group(1).strip() == a2.group(1).strip():
+        if (
+            a1
+            and a2
+            and a1.group(1).strip()
+            and a1.group(1).strip() == a2.group(1).strip()
+        ):
             return ScoreResult(
                 score=0.9,
                 reasons=[f"Same GitHub Action: {a1.group(1).strip()}"],
@@ -447,8 +491,10 @@ def aggregate_scores(
         Weighted average in [0,1].
     """
     if config is None:
-        config = ScoringConfig()
-    w_sum = float(config.subject_weight + config.files_weight + config.body_weight)
+        config = _DEFAULT_SCORING_CONFIG
+    w_sum = float(
+        config.subject_weight + config.files_weight + config.body_weight
+    )
     if w_sum <= 0:
         return 0.0
     total = (

github2gerrit/ssh_agent_setup.py

@@ -16,6 +16,7 @@ import os
 import shutil
 import subprocess
 from pathlib import Path
+from typing import cast
 
 from .gitutils import CommandError
 from .gitutils import run_cmd
@@ -42,6 +43,7 @@ _MSG_LIST_FAILED = "Failed to list keys: {error}"
 _MSG_NO_KEYS_LOADED = "No keys were loaded into SSH agent"
 _MSG_SSH_AGENT_NOT_FOUND = "ssh-agent not found in PATH"
 _MSG_SSH_ADD_NOT_FOUND = "ssh-add not found in PATH"
+_MSG_TOOL_NOT_FOUND = "Required tool '{tool_name}' not found in PATH"
 
 
 class SSHAgentManager:
@@ -63,10 +65,7 @@ class SSHAgentManager:
         """Start a new SSH agent process."""
         try:
             # Locate ssh-agent executable
-            ssh_agent_path = shutil.which("ssh-agent")
-            if not ssh_agent_path:
-                _raise_ssh_agent_not_found()
-            assert ssh_agent_path is not None  # for mypy  # noqa: S101
+            ssh_agent_path = _ensure_tool_available("ssh-agent")
 
             # Start ssh-agent and capture its output
             result = run_cmd([ssh_agent_path, "-s"], timeout=10)
@@ -74,7 +73,8 @@ class SSHAgentManager:
             # Parse the ssh-agent output to get environment variables
             for line in result.stdout.strip().split("\n"):
                 if line.startswith("SSH_AUTH_SOCK="):
-                    # Format: SSH_AUTH_SOCK=/path/to/socket; export SSH_AUTH_SOCK;
+                    # Format: SSH_AUTH_SOCK=/path/to/socket; export
+                    # SSH_AUTH_SOCK;
                     value = line.split("=", 1)[1].split(";")[0].strip()
                     self.auth_sock = value
                 elif line.startswith("SSH_AGENT_PID="):
@@ -97,7 +97,11 @@ class SSHAgentManager:
             if self.agent_pid:
                 os.environ["SSH_AGENT_PID"] = str(self.agent_pid)
 
-            log.debug("Started SSH agent with PID %d, socket %s", self.agent_pid, self.auth_sock)
+            log.debug(
+                "Started SSH agent with PID %d, socket %s",
+                self.agent_pid,
+                self.auth_sock,
+            )
 
         except Exception as exc:
             raise SSHAgentError(_MSG_START_FAILED.format(error=exc)) from exc
@@ -112,20 +116,20 @@ class SSHAgentManager:
             raise SSHAgentError(_MSG_NOT_STARTED)
 
         # Locate ssh-add executable
-        ssh_add_path = shutil.which("ssh-add")
-        if not ssh_add_path:
-            _raise_ssh_add_not_found()
-        assert ssh_add_path is not None  # for mypy  # noqa: S101
+        ssh_add_path = _ensure_tool_available("ssh-add")
 
         process = None
         try:
             # Use ssh-add with stdin to add the key
-            process = subprocess.Popen(  # noqa: S603
+            # Security: ssh_add_path is validated by _ensure_tool_available()
+            # which uses shutil.which() to find the actual ssh-add binary
+            process = subprocess.Popen(  # noqa: S603  # ssh_add_path validated by _ensure_tool_available via shutil.which
                 [ssh_add_path, "-"],
                 stdin=subprocess.PIPE,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
                 text=True,
+                shell=False,  # Explicitly disable shell for security
                 env={
                     **os.environ,
                     "SSH_AUTH_SOCK": self.auth_sock,
@@ -133,7 +137,9 @@ class SSHAgentManager:
                 },
             )
 
-            stdout, stderr = process.communicate(input=private_key_content.strip() + "\n", timeout=10)
+            _stdout, stderr = process.communicate(
+                input=private_key_content.strip() + "\n", timeout=10
+            )
 
             if process.returncode != 0:
                 _raise_add_key_error(stderr)
@@ -158,7 +164,8 @@ class SSHAgentManager:
             tool_ssh_dir = self.workspace / ".ssh-g2g"
             tool_ssh_dir.mkdir(mode=0o700, exist_ok=True)
 
-            # Write known hosts file (normalize/augment with [host]:port entries)
+            # Write known hosts file (normalize/augment with [host]:port
+            # entries)
             self.known_hosts_path = tool_ssh_dir / "known_hosts"
             host = (os.getenv("GERRIT_SERVER") or "").strip()
             port = (os.getenv("GERRIT_SERVER_PORT") or "29418").strip()
@@ -168,7 +175,9 @@ class SSHAgentManager:
                 port_int = 29418
 
             # Use centralized augmentation logic
-            augmented_content = augment_known_hosts_with_bracketed_entries(known_hosts_content, host, port_int)
+            augmented_content = augment_known_hosts_with_bracketed_entries(
+                known_hosts_content, host, port_int
+            )
 
             with open(self.known_hosts_path, "w", encoding="utf-8") as f:
                 f.write(augmented_content)
@@ -177,7 +186,9 @@ class SSHAgentManager:
             log.debug("Known hosts written to %s", self.known_hosts_path)
 
         except Exception as exc:
-            raise SSHAgentError(_MSG_SETUP_HOSTS_FAILED.format(error=exc)) from exc
+            raise SSHAgentError(
+                _MSG_SETUP_HOSTS_FAILED.format(error=exc)
+            ) from exc
 
     def get_git_ssh_command(self) -> str:
         """Generate GIT_SSH_COMMAND for SSH agent-based authentication.
@@ -227,10 +238,7 @@ class SSHAgentManager:
 
         try:
             # Locate ssh-add executable
-            ssh_add_path = shutil.which("ssh-add")
-            if not ssh_add_path:
-                _raise_ssh_add_not_found()
-            assert ssh_add_path is not None  # for mypy  # noqa: S101
+            ssh_add_path = _ensure_tool_available("ssh-add")
 
             result = run_cmd(
                 [ssh_add_path, "-l"],
@@ -274,7 +282,9 @@ class SSHAgentManager:
                 import shutil
 
                 shutil.rmtree(tool_ssh_dir)
-                log.debug("Cleaned up temporary SSH directory: %s", tool_ssh_dir)
+                log.debug(
+                    "Cleaned up temporary SSH directory: %s", tool_ssh_dir
+                )
 
         except Exception as exc:
             log.warning("Failed to clean up SSH agent: %s", exc)
@@ -284,7 +294,9 @@ class SSHAgentManager:
             self.known_hosts_path = None
 
 
-def setup_ssh_agent_auth(workspace: Path, private_key_content: str, known_hosts_content: str) -> SSHAgentManager:
+def setup_ssh_agent_auth(
+    workspace: Path, private_key_content: str, known_hosts_content: str
+) -> SSHAgentManager:
     """Setup SSH agent-based authentication.
 
     Args:
@@ -315,7 +327,7 @@ def setup_ssh_agent_auth(workspace: Path, private_key_content: str, known_hosts_
         if "No keys loaded" in keys_list:
             _raise_no_keys_error()
 
-        log.info("SSH agent authentication configured successfully")
+        log.debug("SSH agent authentication configured successfully")
         log.debug("Loaded keys: %s", keys_list)
 
     except Exception:
@@ -336,6 +348,31 @@ def _raise_add_key_error(stderr: str) -> None:
     raise SSHAgentError(_MSG_ADD_FAILED.format(error=stderr))
 
 
+def _ensure_tool_available(tool_name: str) -> str:
+    """Ensure a required tool is available and return its path.
+
+    Args:
+        tool_name: Name of the tool to locate
+
+    Returns:
+        Path to the tool executable
+
+    Raises:
+        SSHAgentError: If the tool is not found
+    """
+    tool_path = shutil.which(tool_name)
+    if not tool_path:
+        if tool_name == "ssh-agent":
+            _raise_ssh_agent_not_found()
+        elif tool_name == "ssh-add":
+            _raise_ssh_add_not_found()
+        else:
+            raise SSHAgentError(_MSG_TOOL_NOT_FOUND.format(tool_name=tool_name))
+    # At this point, tool_path is guaranteed not to be None
+    # (the above conditions raise exceptions if it was None)
+    return cast(str, tool_path)
+
+
 def _raise_ssh_agent_not_found() -> None:
     """Raise SSH agent not found error."""
     raise SSHAgentError(_MSG_SSH_AGENT_NOT_FOUND)