feat(cmd[git,hg,svn]) Surface timeout= on public Cmd.run signatures

why: ``timeout=`` was reachable only by spelunking through ``**kwargs``
into ``libvcs._internal.run.run()``; it did not appear in any public
signature or docstring. That made the new deadline feature
undiscoverable for downstream callers (e.g. vcspull) and easy to miss
in IDE autocomplete.
what:
- Add explicit ``timeout: float | None = None`` keyword to ``Git.run``,
  ``Hg.run``, and ``Svn.run`` with NumPy "Parameters" entries that
  describe the SIGTERM/SIGKILL escalation and ``CommandTimeoutError``
  contract.
- Forward ``timeout`` to ``run()`` at each call site.
- Cover the propagation in ``tests/cmd/test_{git,hg,svn}.py`` by
  mocking ``run`` and asserting the kwarg lands.

Author: tony

src/libvcs/cmd/git.py

@@ -146,6 +146,7 @@ def run(
         config_env: str | None = None,
         # Pass-through to run()
         log_in_real_time: bool = False,
+        timeout: float | None = None,
         **kwargs: t.Any,
     ) -> str:
         """Run a command for this git repository.
@@ -205,6 +206,13 @@ def run(
             ``--config=<name>=<value>``
         config_env :
             ``--config-env=<name>=<envvar>``
+        timeout : float, optional
+            Wall-clock seconds to wait before terminating the subprocess.
+            ``None`` (default) preserves the legacy behaviour of blocking
+            until the process exits. When the deadline is exceeded the
+            process is sent ``SIGTERM`` (then ``SIGKILL`` after a grace
+            period) and :class:`libvcs.exc.CommandTimeoutError` is raised
+            with any output collected so far.
 
         Examples
         --------
@@ -281,7 +289,7 @@ def stringify(v: t.Any) -> str:
         if self.progress_callback is not None:
             kwargs["callback"] = self.progress_callback
 
-        return run(args=cli_args, **kwargs)
+        return run(args=cli_args, timeout=timeout, **kwargs)
 
     def clone(
         self,

src/libvcs/cmd/hg.py

@@ -98,6 +98,7 @@ def run(
         pager: HgPagerType | None = None,
         color: HgColorType | None = None,
         check_returncode: bool | None = None,
+        timeout: float | None = None,
         **kwargs: t.Any,
     ) -> str:
         """Run a command for this Mercurial repository.
@@ -149,6 +150,13 @@ def run(
             ``--config CONFIG [+]``, ``section.name=value``
         check_returncode : bool, default: ``True``
             Passthrough to :func:`libvcs._internal.run.run()`
+        timeout : float, optional
+            Wall-clock seconds to wait before terminating the subprocess.
+            ``None`` (default) preserves the legacy behaviour of blocking
+            until the process exits. When the deadline is exceeded the
+            process is sent ``SIGTERM`` (then ``SIGKILL`` after a grace
+            period) and :class:`libvcs.exc.CommandTimeoutError` is raised
+            with any output collected so far.
 
         Examples
         --------
@@ -194,6 +202,7 @@ def run(
         return run(
             args=cli_args,
             check_returncode=True if check_returncode is None else check_returncode,
+            timeout=timeout,
             **kwargs,
         )
 

src/libvcs/cmd/svn.py

@@ -83,6 +83,7 @@ def run(
         # Special behavior
         make_parents: bool | None = True,
         check_returncode: bool | None = None,
+        timeout: float | None = None,
         **kwargs: t.Any,
     ) -> str:
         """Run a command for this SVN working copy.
@@ -119,6 +120,13 @@ def run(
             Creates checkout directory (`:attr:`self.path`) if it doesn't already exist.
         check_returncode : bool, default: ``None``
             Passthrough to :meth:`Svn.run`
+        timeout : float, optional
+            Wall-clock seconds to wait before terminating the subprocess.
+            ``None`` (default) preserves the legacy behaviour of blocking
+            until the process exits. When the deadline is exceeded the
+            process is sent ``SIGTERM`` (then ``SIGKILL`` after a grace
+            period) and :class:`libvcs.exc.CommandTimeoutError` is raised
+            with any output collected so far.
 
         Examples
         --------
@@ -152,6 +160,7 @@ def run(
         return run(
             args=cli_args,
             check_returncode=True if check_returncode is None else check_returncode,
+            timeout=timeout,
             **kwargs,
         )
 

tests/cmd/test_git.py

@@ -12,6 +12,8 @@
 from libvcs.cmd import git
 
 if t.TYPE_CHECKING:
+    from pytest_mock import MockerFixture
+
     from libvcs.pytest_plugin import CreateRepoFn, GitCommitEnvVars
     from libvcs.sync.git import GitSync
 
@@ -44,6 +46,24 @@ def test_git_run_accepts_scalar_string(tmp_path: pathlib.Path) -> None:
     assert result.startswith("git version ")
 
 
+def test_git_run_timeout_propagates_to_runner(
+    tmp_path: pathlib.Path,
+    mocker: MockerFixture,
+) -> None:
+    """``Git.run(timeout=X)`` forwards X to the underlying ``run()`` call.
+
+    Regression guard for the discoverability fix: ``timeout=`` is part of the
+    public ``Git.run`` signature rather than reachable only via ``**kwargs``.
+    """
+    repo = git.Git(path=tmp_path)
+    mock_run = mocker.patch("libvcs.cmd.git.run", return_value="")
+
+    repo.run(["--version"], timeout=2.5)
+
+    _args, kwargs = mock_run.call_args
+    assert kwargs.get("timeout") == 2.5
+
+
 def test_git_init_bare(tmp_path: pathlib.Path) -> None:
     """Test git init with bare repository."""
     repo = git.Git(path=tmp_path)

tests/cmd/test_hg.py

@@ -4,11 +4,15 @@
 
 import pathlib
 import shutil
+import typing as t
 
 import pytest
 
 from libvcs.cmd.hg import Hg
 
+if t.TYPE_CHECKING:
+    from pytest_mock import MockerFixture
+
 if not shutil.which("hg"):
     pytestmark = pytest.mark.skip(reason="hg is not available")
 
@@ -20,3 +24,17 @@ def test_hg_run_accepts_scalar_string(tmp_path: pathlib.Path) -> None:
     result = repo.run("help")
 
     assert "Mercurial Distributed SCM" in result
+
+
+def test_hg_run_timeout_propagates_to_runner(
+    tmp_path: pathlib.Path,
+    mocker: MockerFixture,
+) -> None:
+    """``Hg.run(timeout=X)`` forwards X to the underlying ``run()``."""
+    repo = Hg(path=tmp_path)
+    mock_run = mocker.patch("libvcs.cmd.hg.run", return_value="")
+
+    repo.run(["help"], timeout=2.5)
+
+    _args, kwargs = mock_run.call_args
+    assert kwargs.get("timeout") == 2.5

tests/cmd/test_svn.py

@@ -4,11 +4,15 @@
 
 import pathlib
 import shutil
+import typing as t
 
 import pytest
 
 from libvcs.cmd.svn import Svn
 
+if t.TYPE_CHECKING:
+    from pytest_mock import MockerFixture
+
 if not shutil.which("svn"):
     pytestmark = pytest.mark.skip(reason="svn is not available")
 
@@ -20,3 +24,17 @@ def test_svn_run_accepts_scalar_string(tmp_path: pathlib.Path) -> None:
     result = repo.run("help")
 
     assert "usage: svn <subcommand> [options] [args]" in result
+
+
+def test_svn_run_timeout_propagates_to_runner(
+    tmp_path: pathlib.Path,
+    mocker: MockerFixture,
+) -> None:
+    """``Svn.run(timeout=X)`` forwards X to the underlying ``run()``."""
+    repo = Svn(path=tmp_path)
+    mock_run = mocker.patch("libvcs.cmd.svn.run", return_value="")
+
+    repo.run(["help"], timeout=2.5)
+
+    _args, kwargs = mock_run.call_args
+    assert kwargs.get("timeout") == 2.5