gitacross 2.2.0__tar.gz → 2.3.1__tar.gz

{gitacross-2.2.0/src/gitacross.egg-info → gitacross-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitacross
-Version: 2.2.0
+Version: 2.3.1
 Summary: Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines.
 Author: Matthew Deik
 License-Expression: MIT
@@ -157,6 +157,13 @@ A config file starts with a `projects` list — each entry is one mirror and nee
 
 Tokens use `${VAR}` syntax — resolved from environment variables.
 
+For local **targets**, the `path` does not have to exist yet: if the directory is
+missing or is not already a git repository, GitAcross creates the directory and
+runs `git init` there before committing. If a repository already exists at that
+path it is opened as-is — existing git metadata is never re-initialised or
+overwritten (bare repositories and broken `.git` markers are refused with an
+error). Local **sources** must point at an existing git repository.
+
 | Option | Description |
 |---|---|
 | [`enabled`](#enabled) | Disable a project without deleting it |
@@ -436,7 +443,7 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--clean-cache] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
@@ -446,6 +453,7 @@ gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--re
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
+| `--clean-cache` | Delete mirror caches no longer referenced by the config (e.g. after changing a repo's host or name in the config) |
 | `--lint` | Check the config for YAML errors, invalid settings, and redundant options |
 | `--fix` | Fix misplaced keys and remove redundant options in the config |
 | `-v, --verbose` | Debug logging |

{gitacross-2.2.0 → gitacross-2.3.1}/README.md

@@ -128,6 +128,13 @@ A config file starts with a `projects` list — each entry is one mirror and nee
 
 Tokens use `${VAR}` syntax — resolved from environment variables.
 
+For local **targets**, the `path` does not have to exist yet: if the directory is
+missing or is not already a git repository, GitAcross creates the directory and
+runs `git init` there before committing. If a repository already exists at that
+path it is opened as-is — existing git metadata is never re-initialised or
+overwritten (bare repositories and broken `.git` markers are refused with an
+error). Local **sources** must point at an existing git repository.
+
 | Option | Description |
 |---|---|
 | [`enabled`](#enabled) | Disable a project without deleting it |
@@ -407,7 +414,7 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--clean-cache] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
@@ -417,6 +424,7 @@ gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--re
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
+| `--clean-cache` | Delete mirror caches no longer referenced by the config (e.g. after changing a repo's host or name in the config) |
 | `--lint` | Check the config for YAML errors, invalid settings, and redundant options |
 | `--fix` | Fix misplaced keys and remove redundant options in the config |
 | `-v, --verbose` | Debug logging |

{gitacross-2.2.0 → gitacross-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitacross"
-version = "2.2.0"
+version = "2.3.1"
 description = "Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines."
 readme = "README.md"
 requires-python = ">=3.8"

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/cli.py

@@ -50,6 +50,11 @@ def main():
         default=DEFAULT_WORK_DIR,
         help="Directory for state.yml and cache/ (default: .gitsync)",
     )
+    _ = parser.add_argument(
+        "--clean-cache",
+        action="store_true",
+        help="Delete mirror caches no longer referenced by the config",
+    )
     _ = parser.add_argument("-v", "--verbose", action="store_true", help="Debug logging")
     args = parser.parse_args()
 
@@ -62,6 +67,7 @@ def main():
     dry_run_flag = cast(bool, args.dry_run)
     reset_flag = cast(bool, args.reset)
     workdir = cast(str, args.workdir)
+    clean_cache_flag = cast(bool, args.clean_cache)
 
     _setup_logging(verbose)
 
@@ -96,6 +102,7 @@ def main():
             dry_run=dry_run_flag,
             reset=reset_flag,
             work_dir=workdir,
+            clean_cache=clean_cache_flag,
         )
     except (FileNotFoundError, ValueError) as exc:
         sys.exit(str(exc))

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/config.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import hashlib
 import logging
 import os
 from pathlib import Path
@@ -170,6 +171,41 @@ class _EndpointConfig:
         """Filesystem-safe repo identifier (``owner/name`` → ``owner_name``)."""
         return self.repo.replace("/", "_")
 
+    @property
+    def host(self):
+        """Git host for a remote endpoint.
+
+        GitHub's API lives at api.github.com, but its git host is github.com.
+        Gitea's API typically lives on the same host as git, so no transform is
+        needed there. Returns "" when no ``api`` is configured.
+        """
+        if not self.api:
+            return ""
+        raw_host = self.api.split("://")[1].split("/")[0] if "://" in self.api else self.api
+        return "github.com" if raw_host == "api.github.com" else raw_host
+
+    @property
+    def host_slug(self):
+        """Filesystem-safe host identifier for cache paths.
+
+        Keeps dots and hyphens (so e.g. ``my.host.com`` and ``my-host.com`` stay
+        distinct); only the port separator and any slashes become underscores.
+        """
+        return self.host.lower().replace(":", "_").replace("/", "_")
+
+    def mirror_dir_name(self, role):
+        """Deterministic, collision-resistant cache directory name for a remote endpoint.
+
+        Mirrors persist between runs — that is what makes them a cache — so the
+        name must be a pure function of the endpoint identity, never random.
+        Separator-based slugs alone can still collide (e.g. ``a/b_c`` and
+        ``a_b/c`` on the same host), so a short hash of the full identity
+        (role, type, host, repo) is appended to the readable prefix.
+        """
+        identity = "\0".join([role, self.type, self.host.lower(), self.repo])
+        digest = hashlib.sha1(identity.encode("utf-8")).hexdigest()[:10]
+        return f"{role}_{self.type}_{self.host_slug}_{self.repo_slug}_{digest}.git"
+
     @property
     def owner(self):
         return self.repo.split("/")[0] if "/" in self.repo else ""
@@ -179,11 +215,7 @@ class _EndpointConfig:
         """HTTPS clone URL with token embedded for auth."""
         if not self.api or not self.repo:
             return ""
-        raw_host = self.api.split("://")[1].split("/")[0] if "://" in self.api else self.api
-        # GitHub's API lives at api.github.com, but its git host is github.com.
-        # Gitea's API typically lives on the same host as git, so no transform needed.
-        host = "github.com" if raw_host == "api.github.com" else raw_host
-        return f"https://{self.owner}:{self.token}@{host}/{self.repo}.git"
+        return f"https://{self.owner}:{self.token}@{self.host}/{self.repo}.git"
 
 
 @final

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/git.py

@@ -37,9 +37,16 @@ def _log_git_stderr(command, returncode, stderr, level):
         )
 
 
-def _git(*args, check=True, input_data=None, text=True, env=None):
-    cmd = ["git"] + [str(a) for a in args]
-    logger.debug("> git %s", _redact(" ".join(str(a) for a in args)))
+def _git(*args, check=True, input_data=None, text=True, env=None, safe_dir=None):
+    cmd = ["git"]
+    if safe_dir:
+        # Git refuses to operate in a repository owned by another user
+        # ("dubious ownership"). The bare mirrors under the cache dir are
+        # created and managed by gitacross itself, so whitelist exactly that
+        # directory for this one invocation via -c — never written to a config.
+        cmd += ["-c", f"safe.directory={Path(safe_dir).resolve()}"]
+    cmd += [str(a) for a in args]
+    logger.debug("> git %s", _redact(" ".join(str(a) for a in cmd[1:])))
     try:
         result = subprocess.run(
             cmd,
@@ -56,6 +63,12 @@ def _git(*args, check=True, input_data=None, text=True, env=None):
             if isinstance(part, str):
                 e.cmd[i] = _redact(part)
         raise
+    except FileNotFoundError as exc:
+        # subprocess can't find the `git` binary at all — give a clear error
+        # instead of the raw "[Errno 2] No such file or directory: 'git'".
+        raise ValueError(
+            "git executable not found — install Git and make sure it is on PATH."
+        ) from exc
     if result.returncode != 0:
         # check=False path — callers inspect the return code themselves
         _log_git_stderr(args[0], result.returncode, result.stderr, level=logging.DEBUG)
@@ -87,34 +100,122 @@ class GitRepo:
         path = Path(dest)
         if path.exists():
             # Update remote URL *before* fetching so token rotation takes effect
-            current = _git("-C", str(path), "remote", "get-url", "origin", check=False)
+            current = _git(
+                "-C", str(path), "remote", "get-url", "origin",
+                check=False, safe_dir=path,
+            )
             if current.returncode == 0 and current.stdout.strip() != url:
-                _ = _git("-C", str(path), "remote", "set-url", "origin", url)
+                _ = _git(
+                    "-C", str(path), "remote", "set-url", "origin", url,
+                    safe_dir=path,
+                )
                 logger.info("Updated remote URL for mirror at %s", dest)
-            _ = _git("-C", str(path), "fetch", "--tags", "--prune", "origin")
+            _ = _git(
+                "-C", str(path), "fetch", "--tags", "--prune", "origin",
+                safe_dir=path,
+            )
             logger.info("Updated mirror at %s", dest)
         else:
             path.parent.mkdir(parents=True, exist_ok=True)
-            _ = _git("clone", "--mirror", url, str(path))
+            _ = _git("clone", "--mirror", url, str(path), safe_dir=path)
             logger.info("Cloned mirror from %s", _redact(url))
         # Ensure author identity for automated commits
-        _ = _git("-C", str(path), "config", "user.name", "GitAcross")
-        _ = _git("-C", str(path), "config", "user.email", "sync@gitacross")
+        _ = _git("-C", str(path), "config", "user.name", "GitAcross", safe_dir=path)
+        _ = _git("-C", str(path), "config", "user.email", "sync@gitacross", safe_dir=path)
         return cls(path, is_bare=True)
 
     @classmethod
     def local(cls, path):
-        """Open an existing local git repository."""
+        """Open an existing local git repository.
+
+        *path* must be the root of its own git working tree. Git resolves a
+        path that merely lives *inside* a repository to the nearest enclosing
+        repository, so without this check a configured path that is not itself
+        a git repository would silently commit to and reset that enclosing
+        repo — e.g. the directory the tool is being run from — instead of the
+        configured location.
+        """
         p = Path(path)
-        result = _git("-C", str(p), "rev-parse", "--git-dir")
-        git_dir = p / result.stdout.strip()
-        if not git_dir.exists():
+        result = _git("-C", str(p), "rev-parse", "--show-toplevel", check=False)
+        if result.returncode != 0:
             raise ValueError(f"Not a git repository: {path}")
-        return cls(git_dir, is_bare=False)
+        root = Path(result.stdout.strip())
+        if Path(p).resolve() != root.resolve():
+            raise ValueError(
+                f"Not a git repository: {path} — it is inside the git repository "
+                + f"'{root}'. A local endpoint path must point at a repository "
+                + f"root; run 'git init' in {path} or point the path at {root}."
+            )
+        git_dir = _git("-C", str(root), "rev-parse", "--absolute-git-dir")
+        return cls(Path(git_dir.stdout.strip()), is_bare=False)
+
+    @classmethod
+    def ensure_local(cls, path):
+        """Open a local git repository at *path*, creating it if necessary.
+
+        Unlike :meth:`local`, a missing directory or a plain directory that is
+        not yet a git repository is accepted: the directory is created
+        (including parents) and ``git init`` is run there. Used for local
+        *targets*, which receive commits. Local *sources* still go through
+        :meth:`local` so a misconfigured source path is reported instead of
+        silently yielding an empty repository.
+
+        An existing repository is opened as-is and never re-initialised. If
+        *path* already holds git metadata that cannot be used as a working tree
+        (a bare repository, a git-internal directory, or a broken ``.git``
+        marker), a :class:`ValueError` is raised instead of overwriting it.
+        """
+        if not path or not str(path).strip():
+            raise ValueError(
+                "Local target path is empty — set 'path' to the directory where "
+                + "the mirrored repository should live."
+            )
+        try:
+            return cls.local(path)
+        except ValueError:
+            pass
+
+        # Only auto-initialise when the directory is genuinely not a git
+        # repository yet — never run `git init` over existing git metadata
+        # (re-initialising a bare repo pollutes it with a nested .git).
+        p = Path(path)
+        if p.exists() and not p.is_dir():
+            raise ValueError(f"Local target path is not a directory: {path}")
+        if (p / ".git").exists():
+            raise ValueError(
+                f"Not initialising {path}: it already contains a '.git' entry "
+                + "that is not a usable working tree. Refusing to overwrite it — "
+                + "fix or remove that repository, or point the local target at a "
+                + "missing or empty directory."
+            )
+        if (p / "HEAD").is_file() and (p / "objects").is_dir():
+            raise ValueError(
+                f"Not initialising {path}: it is a bare git repository or git's "
+                + "internal directory. Local targets need a working tree, and "
+                + "existing repositories are never re-initialised."
+            )
+        p.mkdir(parents=True, exist_ok=True)
+        _ = _git("init", str(p))
+        # Give a fresh repo a repo-local identity so commits never depend on
+        # the ambient git config (mirrors get the same treatment in
+        # ensure_mirror). Existing repos are opened as-is and left untouched.
+        _ = _git("-C", str(p), "config", "user.name", "GitAcross")
+        _ = _git("-C", str(p), "config", "user.email", "sync@gitacross")
+        logger.info("Initialised git repository at %s", p)
+        return cls.local(path)
 
     def _g(self, *args, text=True, env=None, **kwargs):
         """Run git command with --git-dir set."""
-        return _git("--git-dir", str(self.git_dir), *args, text=text, env=env, **kwargs)
+        return _git(
+            "--git-dir",
+            str(self.git_dir),
+            *args,
+            text=text,
+            env=env,
+            # Mirrors are gitacross-managed; whitelist them for the ownership check.
+            safe_dir=self.git_dir if self.is_bare else None,
+            **kwargs,
+        )
 
     def _gw(self, work_dir, *args, env=None, **kwargs):
         """Run git command with --git-dir and --work-tree set."""
@@ -125,6 +226,8 @@ class GitRepo:
             str(work_dir),
             *args,
             env=env,
+            # Mirrors are gitacross-managed; whitelist them for the ownership check.
+            safe_dir=self.git_dir if self.is_bare else None,
             **kwargs,
         )
 

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/main.py

@@ -446,6 +446,7 @@ def run(
     dry_run: bool = False,
     reset: bool = False,
     work_dir: str | Path = DEFAULT_WORK_DIR,
+    clean_cache: bool = False,
 ):
     """Sync releases from a config — the primary Python API entry point.
 
@@ -469,6 +470,14 @@ def run(
             syncing so that all releases are treated as new.
         work_dir:    Directory path for ``state.yml`` and ``cache/``.
             Defaults to ``.gitsync``.
+        clean_cache: When ``True``, delete bare mirror clones under
+            ``work_dir/cache/`` that no endpoint in the config references
+            anymore (e.g. after the config changed hosts or repos). Mirrors are
+            disposable clones, so this only ever costs a re-clone. Skipped in
+            dry-run mode. Note: mirrors are identified per config, so if
+            multiple config files share one ``work_dir``, run them with the
+            same ``clean_cache`` setting to avoid deleting each other's
+            mirrors.
 
     Returns:
         A list of dicts — one per enabled project that was attempted — with
@@ -522,6 +531,9 @@ def run(
     if project_name and not projects:
         raise ValueError(f"Project '{project_name}' not found in config")
 
+    if clean_cache and not dry_run and not reset:
+        _clean_mirror_cache(work_dir, config)
+
     results = []
     for proj in projects:
         if not proj.enabled:
@@ -552,6 +564,42 @@ def run(
     return results
 
 
+def _clean_mirror_cache(work_dir: str | Path, config: Config) -> None:
+    """Delete mirror clones under ``work_dir/cache/`` not referenced by *config*.
+
+    Cache keys are deterministic identity names (role, type, host, repo), so a
+    config edit that changes any of those orphans the previous mirror. Orphans
+    are harmless but waste disk, so this removes them. The reference set is
+    built from *every* project in the config — enabled or not — and remote
+    endpoints only, so running a project subset or re-enabling a disabled
+    project never deletes a mirror it still needs.
+    """
+    cache_dir = Path(work_dir) / "cache"
+    if not cache_dir.is_dir():
+        return
+    referenced = {
+        endpoint.mirror_dir_name(role)
+        for proj in config.projects
+        for endpoint, role in ((proj.source, "source"), (proj.target, "target"))
+        if endpoint.is_remote
+    }
+    removed = []
+    for child in sorted(cache_dir.iterdir()):
+        if (
+            child.is_dir()
+            and child.name.endswith(".git")
+            and child.name not in referenced
+        ):
+            shutil.rmtree(child, ignore_errors=True)
+            removed.append(child.name)
+    if removed:
+        logger.info(
+            "Removed %d stale mirror cache(s): %s",
+            len(removed),
+            ", ".join(removed),
+        )
+
+
 
 
 # Imported at the bottom to avoid a circular import (cli.py imports .main.run).

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/source.py

@@ -64,7 +64,7 @@ class _RemoteSource:
         self._api.ensure_repo_exists(create=not dry_run)
         self._git = GitRepo.ensure_mirror(
             config.clone_url,
-            Path(cache_dir) / f"source_{config.type}_{config.repo_slug}.git",
+            Path(cache_dir) / config.mirror_dir_name("source"),
         )
         self._include_prereleases = config.include_prereleases
         self._include_drafts = config.include_drafts

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/state.py

@@ -26,11 +26,24 @@ class State:
         return f"State(work_dir={str(self.work_dir)!r})"
 
     def _load(self):
+        data = {}
         if self.path.exists():
             with open(self.path) as f:
-                data = yaml.safe_load(f) or {}
-        else:
+                data = yaml.safe_load(f)
+        # Tolerate degenerate or hand-edited YAML (e.g. a bare ``projects:``
+        # key with no value, non-map documents, or null entries) so a corrupt
+        # state file can never crash a run — it is simply treated as empty.
+        if not isinstance(data, dict):
             data = {}
+        projects = data.get("projects")
+        if not isinstance(projects, dict):
+            projects = {}
+            data["projects"] = projects
+        for name, project in list(projects.items()):
+            if not isinstance(project, dict):
+                projects[name] = {}
+            elif not isinstance(project.get("releases"), dict):
+                project["releases"] = {}
         return data
 
     def has_release(self, project_name, tag_name):

{gitacross-2.2.0 → gitacross-2.3.1}/src/gitacross/target.py

@@ -58,7 +58,7 @@ class _RemoteTarget:
             )
         self._git = GitRepo.ensure_mirror(
             clone_url,
-            Path(cache_dir) / f"target_{config.type}_{config.repo_slug}.git",
+            Path(cache_dir) / config.mirror_dir_name("target"),
         )
         self._retry_max = retry_max
         self._retry_backoff = retry_backoff
@@ -120,10 +120,15 @@ class _RemoteTarget:
 
 
 class _LocalTarget:
-    """Target backed by a local git repo — no push, no API release."""
+    """Target backed by a local git repo — no push, no API release.
+
+    The repository at ``config.path`` is created on demand (directory plus
+    ``git init``) if it does not exist yet, so a local target can point at a
+    brand-new backup/mirror location.
+    """
 
     def __init__(self, config, author=None):
-        self._git = GitRepo.local(config.path)
+        self._git = GitRepo.ensure_local(config.path)
         self._author = author
 
     def setup(self, branch):

{gitacross-2.2.0 → gitacross-2.3.1/src/gitacross.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitacross
-Version: 2.2.0
+Version: 2.3.1
 Summary: Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines.
 Author: Matthew Deik
 License-Expression: MIT
@@ -157,6 +157,13 @@ A config file starts with a `projects` list — each entry is one mirror and nee
 
 Tokens use `${VAR}` syntax — resolved from environment variables.
 
+For local **targets**, the `path` does not have to exist yet: if the directory is
+missing or is not already a git repository, GitAcross creates the directory and
+runs `git init` there before committing. If a repository already exists at that
+path it is opened as-is — existing git metadata is never re-initialised or
+overwritten (bare repositories and broken `.git` markers are refused with an
+error). Local **sources** must point at an existing git repository.
+
 | Option | Description |
 |---|---|
 | [`enabled`](#enabled) | Disable a project without deleting it |
@@ -436,7 +443,7 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--clean-cache] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
@@ -446,6 +453,7 @@ gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--re
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
+| `--clean-cache` | Delete mirror caches no longer referenced by the config (e.g. after changing a repo's host or name in the config) |
 | `--lint` | Check the config for YAML errors, invalid settings, and redundant options |
 | `--fix` | Fix misplaced keys and remove redundant options in the config |
 | `-v, --verbose` | Debug logging |

{gitacross-2.2.0 → gitacross-2.3.1}/tests/test_config.py

@@ -73,6 +73,85 @@ projects:
         os.unlink(config_path)
 
 
+def test_endpoint_host_and_host_slug():
+    """host/host_slug identify the git host and stay filesystem-safe."""
+    from gitacross.config import _EndpointConfig
+
+    gitea = _EndpointConfig(
+        {"type": "gitea", "repo": "a/b", "api": "https://git.nodebay.top/api/v1"},
+        is_source=True,
+    )
+    assert gitea.host == "git.nodebay.top"
+    assert gitea.host_slug == "git.nodebay.top"
+
+    # GitHub's API host maps to its git host
+    gh = _EndpointConfig(
+        {"type": "github", "repo": "a/b", "api": "https://api.github.com"},
+        is_source=True,
+    )
+    assert gh.host == "github.com"
+    assert gh.host_slug == "github.com"
+
+    # Ports are kept in the slug so hosts differing only by port stay distinct
+    port = _EndpointConfig(
+        {"type": "gitea", "repo": "a/b", "api": "https://git.nodebay.top:8443/api/v1"},
+        is_source=True,
+    )
+    assert port.host_slug == "git.nodebay.top_8443"
+
+    # Dots vs hyphens are NOT collapsed into the same slug
+    assert (
+        _EndpointConfig({"api": "https://my.host.com"}, is_source=True).host_slug
+        == "my.host.com"
+    )
+    assert (
+        _EndpointConfig({"api": "https://my-host.com"}, is_source=True).host_slug
+        == "my-host.com"
+    )
+
+    # No api configured -> empty host
+    assert _EndpointConfig({"api": ""}, is_source=True).host == ""
+    print("  ✓ config: endpoint host / host_slug")
+
+
+def test_mirror_dir_name_deterministic_and_unique():
+    """mirror_dir_name is deterministic across runs and collision-resistant."""
+    import re
+
+    from gitacross.config import _EndpointConfig
+
+    def name(repo, api="https://git.nodebay.top/api/v1", kind="gitea", role="source"):
+        raw = {"type": kind, "repo": repo, "api": api}
+        return _EndpointConfig(raw, is_source=True).mirror_dir_name(role)
+
+    # Deterministic: same identity always yields the same cache name
+    assert name("uqkami/Awara") == name("uqkami/Awara")
+
+    # Role is part of the identity (source vs target never share a mirror)
+    assert name("uqkami/Awara", role="target") != name("uqkami/Awara", role="source")
+
+    # Readable prefix + a short hex digest before the .git suffix
+    n = name("uqkami/Awara")
+    assert n.startswith("source_gitea_git.nodebay.top_uqkami_Awara_")
+    digest = n.rsplit("_", 1)[1]
+    assert re.fullmatch(r"[0-9a-f]{10}\.git", digest)
+
+    # Slug-ambiguous owner/repo pairs must never share a mirror
+    assert name("a/b_c") != name("a_b/c")
+
+    # Host case differences resolve to the same host -> same cache (dedup)
+    upper = _EndpointConfig(
+        {"type": "gitea", "repo": "a/b", "api": "https://GIT.NODEBAY.TOP/api/v1"},
+        is_source=True,
+    ).mirror_dir_name("source")
+    assert upper == name("a/b")
+
+    # Different hosts or ports stay distinct
+    assert name("a/b", api="https://git.nodebay.top:8443/api/v1") != name("a/b")
+    assert name("a/b", api="https://gitea.example.com/api/v1") != name("a/b")
+    print("  ✓ config: mirror_dir_name is deterministic and collision-resistant")
+
+
 def test_config_local():
     from gitacross.config import Config