cmd(fix[run-args]): normalize scalar command inputs

why: Fix the mypy arg-type failure and prevent scalar command strings from being split into character args.
what:
- widen _internal.run typing to StrOrBytesPath-compatible inputs
- normalize scalar and sequence command args before subprocess execution
- update git, hg, and svn wrappers to use the shared normalizer
- preserve path semantics with os.fspath and flatten hg enum flags

Author: tony

src/libvcs/_internal/run.py

@@ -12,13 +12,14 @@
 
 import datetime
 import logging
+import os
 import subprocess
 import sys
 import typing as t
 from collections.abc import Iterable, Mapping, MutableMapping, Sequence
 
 from libvcs import exc
-from libvcs._internal.types import StrPath
+from libvcs._internal.types import StrOrBytesPath
 
 logger = logging.getLogger(__name__)
 
@@ -97,23 +98,39 @@ def __call__(self, output: str, timestamp: datetime.datetime) -> None:
 if sys.platform == "win32":
     _ENV: t.TypeAlias = Mapping[str, str]
 else:
-    _ENV: t.TypeAlias = Mapping[bytes, StrPath] | Mapping[str, StrPath]
+    _ENV: t.TypeAlias = Mapping[bytes, StrOrBytesPath] | Mapping[str, StrOrBytesPath]
 
-_CMD = StrPath | Sequence[StrPath]
+_CMD: t.TypeAlias = StrOrBytesPath | Sequence[StrOrBytesPath]
 _FILE: t.TypeAlias = int | t.IO[t.Any] | None
 
 
+def _normalize_command_args(args: _CMD) -> list[StrOrBytesPath]:
+    """Return subprocess arguments without splitting scalar strings or bytes."""
+    if isinstance(args, (str, bytes, os.PathLike)):
+        return [os.fspath(args)]
+
+    return [os.fspath(arg) for arg in args]
+
+
+def _stringify_command(args: _CMD) -> str | list[str]:
+    """Return a human-readable command for CommandError."""
+    if isinstance(args, (str, bytes, os.PathLike)):
+        return os.fsdecode(args)
+
+    return [os.fsdecode(arg) for arg in args]
+
+
 def run(
     args: _CMD,
     bufsize: int = -1,
-    executable: StrPath | None = None,
+    executable: StrOrBytesPath | None = None,
     stdin: _FILE | None = None,
     stdout: _FILE | None = None,
     stderr: _FILE | None = None,
     preexec_fn: t.Callable[[], t.Any] | None = None,
     close_fds: bool = True,
     shell: bool = False,
-    cwd: StrPath | None = None,
+    cwd: StrOrBytesPath | None = None,
     env: _ENV | None = None,
     startupinfo: t.Any | None = None,
     creationflags: int = 0,
@@ -173,8 +190,14 @@ def progress_cb(output, timestamp):
     ----------------
     When minimum python >= 3.10, pipesize: int = -1 will be added after umask.
     """
+    normalized_args: _CMD
+    if shell:
+        normalized_args = os.fspath(args) if isinstance(args, os.PathLike) else args
+    else:
+        normalized_args = _normalize_command_args(args)
+
     proc = subprocess.Popen(
-        args,
+        normalized_args,
         bufsize=bufsize,
         executable=executable,
         stdin=stdin,
@@ -246,8 +269,6 @@ def progress_cb(output: t.AnyStr, timestamp: datetime.datetime) -> None:
         raise exc.CommandError(
             output=output,
             returncode=code,
-            cmd=[str(arg) for arg in args]
-            if isinstance(args, (list, tuple))
-            else str(args),
+            cmd=_stringify_command(normalized_args),
         )
     return output

src/libvcs/cmd/git.py

@@ -4,6 +4,7 @@
 
 import dataclasses
 import datetime
+import os
 import pathlib
 import re
 import shlex
@@ -12,7 +13,7 @@
 from collections.abc import Sequence
 
 from libvcs._internal.query_list import QueryList
-from libvcs._internal.run import ProgressCallbackProtocol, run
+from libvcs._internal.run import ProgressCallbackProtocol, _normalize_command_args, run
 from libvcs._internal.types import StrOrBytesPath, StrPath
 
 _CMD = StrOrBytesPath | Sequence[StrOrBytesPath]
@@ -211,10 +212,10 @@ def run(
         >>> git.run(['help'])
         "usage: git [...--version] [...--help] [-C <path>]..."
         """
-        cli_args = ["git", *args] if isinstance(args, Sequence) else ["git", args]
+        cli_args: list[StrOrBytesPath] = ["git", *_normalize_command_args(args)]
 
         if "cwd" not in kwargs:
-            kwargs["cwd"] = self.path
+            kwargs["cwd"] = self.path if cwd is None else cwd
 
         #
         # Print-and-exit
@@ -237,7 +238,7 @@ def run(
             if not isinstance(C, list):
                 C = [C]
             for c in C:
-                cli_args.extend(["-C", str(c)])
+                cli_args.extend(["-C", os.fspath(c)])
         if config is not None:
             assert isinstance(config, dict)
 
@@ -253,15 +254,15 @@ def stringify(v: t.Any) -> str:
         if config_env is not None:
             cli_args.append(f"--config-env={config_env}")
         if git_dir is not None:
-            cli_args.extend(["--git-dir", str(git_dir)])
+            cli_args.extend(["--git-dir", os.fspath(git_dir)])
         if work_tree is not None:
-            cli_args.extend(["--work-tree", str(work_tree)])
+            cli_args.extend(["--work-tree", os.fspath(work_tree)])
         if namespace is not None:
-            cli_args.extend(["--namespace", namespace])
+            cli_args.extend(["--namespace", os.fspath(namespace)])
         if super_prefix is not None:
-            cli_args.extend(["--super-prefix", super_prefix])
+            cli_args.extend(["--super-prefix", os.fspath(super_prefix)])
         if exec_path is not None:
-            cli_args.extend(["--exec-path", exec_path])
+            cli_args.extend(["--exec-path", os.fspath(exec_path)])
         if bare is True:
             cli_args.append("--bare")
         if no_replace_objects is True:

src/libvcs/cmd/hg.py

@@ -16,10 +16,10 @@
 import typing as t
 from collections.abc import Sequence
 
-from libvcs._internal.run import ProgressCallbackProtocol, run
+from libvcs._internal.run import ProgressCallbackProtocol, _normalize_command_args, run
 from libvcs._internal.types import StrOrBytesPath, StrPath
 
-_CMD = StrOrBytesPath | Sequence[StrOrBytesPath]
+_CMD: t.TypeAlias = StrOrBytesPath | Sequence[StrOrBytesPath]
 
 
 class HgColorType(enum.Enum):
@@ -156,7 +156,7 @@ def run(
         >>> hg.run(['help'])
         "Mercurial Distributed SCM..."
         """
-        cli_args = ["hg", *args] if isinstance(args, Sequence) else ["hg", args]
+        cli_args: list[StrOrBytesPath] = ["hg", *_normalize_command_args(args)]
 
         if "cwd" not in kwargs:
             kwargs["cwd"] = self.path
@@ -166,9 +166,9 @@ def run(
         if config is not None:
             cli_args.extend(["--config", config])
         if pager is not None:
-            cli_args.append(["--pager", pager])
+            cli_args.extend(["--pager", pager.value])
         if color is not None:
-            cli_args.append(["--color", color])
+            cli_args.extend(["--color", color.value])
         if verbose is True:
             cli_args.append("--verbose")
         if quiet is True:

src/libvcs/cmd/svn.py

@@ -10,15 +10,16 @@
 
 from __future__ import annotations
 
+import os
 import pathlib
 import typing as t
 from collections.abc import Sequence
 
 from libvcs import exc
-from libvcs._internal.run import ProgressCallbackProtocol, run
+from libvcs._internal.run import ProgressCallbackProtocol, _normalize_command_args, run
 from libvcs._internal.types import StrOrBytesPath, StrPath
 
-_CMD = StrOrBytesPath | Sequence[StrOrBytesPath]
+_CMD: t.TypeAlias = StrOrBytesPath | Sequence[StrOrBytesPath]
 
 DepthLiteral = t.Literal["infinity", "empty", "files", "immediates"] | None
 RevisionLiteral = t.Literal["HEAD", "BASE", "COMMITTED", "PREV"] | None
@@ -125,7 +126,7 @@ def run(
         >>> svn.run(['help'])
         "usage: svn <subcommand> [options] [args]..."
         """
-        cli_args = ["svn", *args] if isinstance(args, Sequence) else ["svn", args]
+        cli_args: list[StrOrBytesPath] = ["svn", *_normalize_command_args(args)]
 
         if "cwd" not in kwargs:
             kwargs["cwd"] = self.path
@@ -141,9 +142,9 @@ def run(
         if trust_server_cert is True:
             cli_args.append("--trust-server_cert")
         if config_dir is not None:
-            cli_args.extend(["--config-dir", str(config_dir)])
+            cli_args.extend(["--config-dir", os.fspath(config_dir)])
         if config_option is not None:
-            cli_args.extend(["--config-option", str(config_option)])
+            cli_args.extend(["--config-option", os.fspath(config_option)])
 
         if self.progress_callback is not None:
             kwargs["callback"] = self.progress_callback