cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/credential_helpers/docker/installer.py

@@ -0,0 +1,349 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Installer for the Docker credential helper.
+
+Manages writing/removing the ``docker-credential-cloudsmith`` launcher and
+patching ``~/.docker/config.json`` to enable the helper for Cloudsmith
+registry hosts.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+from ...core.cache_utils import merge_json_file
+from ..backends import BackendKind
+from ..custom_domains import get_format_domains
+from ..launchers import is_on_path, remove_launcher, resolve_bin_dir, write_launcher
+
+logger = logging.getLogger(__name__)
+
+
+def _docker_config_path() -> Path:
+    """Return the path to the Docker client configuration file.
+
+    Respects the ``DOCKER_CONFIG`` environment variable; otherwise returns
+    the platform default ``~/.docker/config.json``.
+    """
+    docker_config_env = os.environ.get("DOCKER_CONFIG")
+    if docker_config_env:
+        return Path(docker_config_env) / "config.json"
+    return Path.home() / ".docker" / "config.json"
+
+
+class DockerInstaller:
+    """Manages installation of the Docker credential helper for Cloudsmith.
+
+    This installer writes a ``docker-credential-cloudsmith`` launcher binary
+    and patches ``~/.docker/config.json`` to route the configured registry
+    hosts through the Cloudsmith credential helper.
+
+    Usage::
+
+        installer = DockerInstaller()
+        actions = installer.install(domains=["my-registry.example.com"])
+        for action in actions:
+            print(action)
+    """
+
+    LAUNCHER_NAME = "docker-credential-cloudsmith"
+    TARGET_CMD = "cloudsmith credential-helper docker"
+    HELPER_VALUE = "cloudsmith"
+    DEFAULT_HOST = "docker.cloudsmith.io"
+
+    name = "docker"
+    summary = "Docker credential helper for Cloudsmith registries"
+
+    @classmethod
+    def _resolve_target_cmd(cls) -> str:
+        """Return the command the launcher forwards to.
+
+        A pip/source install resolves the bare ``cloudsmith`` command via
+        ``PATH``.  A frozen standalone binary (PyInstaller) is not guaranteed
+        to be on ``PATH`` under that name, so point the launcher at the
+        absolute executable instead — mirroring the frozen handling in
+        :func:`cloudsmith_cli.cli.commands.mcp._get_server_config`.  The path
+        is quoted so a directory containing spaces still execs correctly.
+        """
+        if getattr(sys, "frozen", False):
+            return f'"{sys.executable}" credential-helper docker'
+        return cls.TARGET_CMD
+
+    def install(
+        self,
+        *,
+        bin_dir: str | None = None,
+        domains: tuple[str, ...] = (),
+        discover: bool = True,
+        refresh: bool = False,
+        org: str | None = None,
+        api_key: str | None = None,
+        auth_type: str = "api_key",
+        api_host: str | None = None,
+        dry_run: bool = False,
+    ) -> list[str]:
+        """Install the Docker credential helper.
+
+        Writes the launcher binary and registers Cloudsmith registry hosts in
+        ``~/.docker/config.json``.
+
+        Parameters
+        ----------
+        bin_dir:
+            Override for the directory to install the launcher.  Defaults to
+            :func:`resolve_bin_dir` auto-detection.
+        domains:
+            Additional registry hostnames to configure (in addition to the
+            default ``docker.cloudsmith.io``).
+        discover:
+            When ``True`` (default), attempt to auto-discover Docker custom
+            domains via the Cloudsmith API.  Discovery is best-effort and never
+            prevents the defaults from being registered.
+        refresh:
+            When ``True``, bypass the domain cache and fetch fresh data from
+            the API.  Only meaningful when *discover* is also ``True``.
+        org:
+            Cloudsmith organisation slug used for custom-domain discovery.
+        api_key:
+            API key used for custom-domain discovery.
+        auth_type:
+            Credential type: ``"api_key"`` (default) or ``"bearer"``.
+        api_host:
+            Cloudsmith API host URL override.
+        dry_run:
+            When ``True``, compute and return planned actions without writing
+            any files.
+
+        Returns
+        -------
+        list[str]
+            Human-readable descriptions of actions taken (or planned, when
+            *dry_run* is ``True``).
+        """
+        target_dir = resolve_bin_dir(bin_dir)
+        config_path = _docker_config_path()
+
+        actions: list[str] = []
+
+        # Start with the default host plus any explicitly requested domains.
+        hosts: list[str] = [self.DEFAULT_HOST, *domains]
+
+        # --- Custom-domain auto-discovery (best-effort) ---
+        if discover:
+            if org and api_key:
+                # Discovery boundary: network/SDK errors must never abort the
+                # default install.  ApiException is already handled inside
+                # get_format_domains; this broad catch is the deliberate outer
+                # boundary (consistent with "boundary catches, library stays clean").
+                # Note: BaseException subclasses (KeyboardInterrupt/SystemExit)
+                # intentionally propagate — they are not caught by `except Exception`.
+                try:
+                    discovered = get_format_domains(
+                        org,
+                        BackendKind.DOCKER,
+                        api_key=api_key,
+                        auth_type=auth_type,
+                        api_host=api_host,
+                        refresh=refresh,
+                    )
+                except Exception as exc:  # pylint: disable=broad-except
+                    # Discovery is best-effort: never let it abort the install of
+                    # the defaults.  (Network/SDK errors degrade to a warning;
+                    # ApiException is already handled inside.)
+                    actions.append(
+                        f"WARNING: custom-domain auto-discovery failed: {exc}"
+                    )
+                    discovered = []
+                new_hosts = [h for h in discovered if h not in hosts]
+                hosts.extend(discovered)
+                actions.append(
+                    f"discovered {len(new_hosts)} new Docker custom domain(s)"
+                )
+            else:
+                logger.debug(
+                    "skipped auto-discovery"
+                    " (no organization/credentials; pass --no-discover to silence)"
+                )
+
+        # De-duplicate while preserving order
+        seen: set[str] = set()
+        deduped: list[str] = []
+        for h in hosts:
+            if h not in seen:
+                seen.add(h)
+                deduped.append(h)
+        hosts = deduped
+
+        def mutate(config: dict) -> None:
+            helpers = config.get("credHelpers")
+            if not isinstance(helpers, dict):
+                helpers = config["credHelpers"] = {}
+            for host in hosts:
+                helpers[host] = self.HELPER_VALUE
+
+        if dry_run:
+            if os.name == "nt":
+                launcher_path = target_dir / f"{self.LAUNCHER_NAME}.cmd"
+            else:
+                launcher_path = target_dir / self.LAUNCHER_NAME
+            actions.append(f"would write launcher {launcher_path}")
+
+            would_change = merge_json_file(config_path, mutate, dry_run=True)
+            for host in hosts:
+                if would_change:
+                    actions.append(
+                        f"would set credHelpers[{host!r}]={self.HELPER_VALUE!r}"
+                        f" in {config_path}"
+                    )
+                else:
+                    actions.append(
+                        f"credHelpers[{host!r}] already set"
+                        f" in {config_path} (no change)"
+                    )
+            return actions
+
+        # Real install
+        launcher_path = write_launcher(
+            target_dir, self.LAUNCHER_NAME, self._resolve_target_cmd()
+        )
+        actions.append(f"wrote launcher {launcher_path}")
+
+        changed = merge_json_file(config_path, mutate)
+        if changed:
+            for host in hosts:
+                actions.append(
+                    f"set credHelpers[{host!r}]={self.HELPER_VALUE!r}"
+                    f" in {config_path}"
+                )
+        else:
+            actions.append(f"config.json already up to date ({config_path})")
+
+        if not is_on_path(target_dir):
+            actions.append(
+                f"WARNING: {target_dir} is not on PATH — "
+                "add it to your PATH so Docker can find docker-credential-cloudsmith"
+            )
+
+        return actions
+
+    def uninstall(
+        self, *, bin_dir: str | None = None, dry_run: bool = False
+    ) -> list[str]:
+        """Uninstall the Docker credential helper.
+
+        Removes the launcher binary and strips Cloudsmith-managed entries from
+        ``~/.docker/config.json``.
+
+        Parameters
+        ----------
+        bin_dir:
+            Override for the directory where the launcher was installed.
+            Defaults to :func:`resolve_bin_dir` auto-detection.  Pass the same
+            value that was given to :meth:`install` so the correct launcher file
+            is found and removed.
+        dry_run:
+            When ``True``, return planned actions without writing any files.
+
+        Returns
+        -------
+        list[str]
+            Human-readable descriptions of actions taken (or planned).
+        """
+        target_dir = resolve_bin_dir(bin_dir)
+        config_path = _docker_config_path()
+
+        def mutate(config: dict) -> None:
+            helpers = config.get("credHelpers")
+            if not isinstance(helpers, dict):
+                return
+            removed = [k for k, v in helpers.items() if v == self.HELPER_VALUE]
+            for key in removed:
+                del helpers[key]
+            if removed and not helpers:
+                del config["credHelpers"]
+
+        actions: list[str] = []
+
+        if os.name == "nt":
+            launcher_path = target_dir / f"{self.LAUNCHER_NAME}.cmd"
+        else:
+            launcher_path = target_dir / self.LAUNCHER_NAME
+
+        if dry_run:
+            if launcher_path.exists():
+                actions.append(f"would remove launcher {launcher_path}")
+            else:
+                actions.append(
+                    f"launcher not found at {launcher_path} (nothing to remove)"
+                )
+
+            would_change = merge_json_file(config_path, mutate, dry_run=True)
+            if would_change:
+                actions.append(
+                    f"would remove credHelpers entries with value"
+                    f" {self.HELPER_VALUE!r} from {config_path}"
+                )
+            else:
+                actions.append(f"no credHelpers entries to remove from {config_path}")
+            return actions
+
+        # Real uninstall
+        removed = remove_launcher(target_dir, self.LAUNCHER_NAME)
+        if removed:
+            actions.append(f"removed launcher {launcher_path}")
+        else:
+            actions.append(f"launcher not found at {launcher_path} (nothing to remove)")
+
+        changed = merge_json_file(config_path, mutate)
+        if changed:
+            actions.append(
+                f"removed credHelpers entries with value"
+                f" {self.HELPER_VALUE!r} from {config_path}"
+            )
+        else:
+            actions.append(f"no credHelpers entries to remove from {config_path}")
+
+        return actions
+
+    def status(self) -> dict:
+        """Return current installation status.
+
+        Returns
+        -------
+        dict
+            A dict with keys:
+
+            ``"launcher"``
+                The :class:`~pathlib.Path` of the launcher if it exists,
+                else ``None``.
+            ``"hosts"``
+                List of hostnames in ``config.json``'s ``credHelpers`` block
+                whose value equals ``"cloudsmith"``.
+        """
+        target_dir = resolve_bin_dir()
+        if os.name == "nt":
+            launcher_path: Path | None = target_dir / f"{self.LAUNCHER_NAME}.cmd"
+        else:
+            launcher_path = target_dir / self.LAUNCHER_NAME
+
+        if launcher_path is not None and not launcher_path.exists():
+            launcher_path = None
+
+        config_path = _docker_config_path()
+        hosts: list[str] = []
+        if config_path.exists():
+            try:
+                data = json.loads(config_path.read_text(encoding="utf-8"))
+                if isinstance(data, dict):
+                    helpers = data.get("credHelpers", {})
+                    hosts = [k for k, v in helpers.items() if v == self.HELPER_VALUE]
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        return {
+            "launcher": str(launcher_path) if launcher_path is not None else None,
+            "hosts": hosts,
+        }

cloudsmith_cli/credential_helpers/docker/runtime.py

@@ -0,0 +1,117 @@
+# Copyright 2026 Cloudsmith Ltd
+"""
+Docker credential helper runtime.
+
+Transport-light protocol logic for the Docker credential helper protocol.
+This module is intentionally free of Click/sys imports so it can be unit-tested
+without invoking the CLI machinery.
+
+See: https://github.com/docker/docker-credential-helpers
+"""
+
+import json
+import logging
+
+from ..backends import BackendKind
+from ..common import is_cloudsmith_domain
+
+logger = logging.getLogger(__name__)
+
+_REFUSAL_MESSAGE = (
+    "Error: Unable to retrieve credentials. "
+    "Provide credentials via the CLOUDSMITH_API_KEY environment variable, "
+    "credentials.ini, the system keyring, or an OIDC service. "
+    "Verify current authentication with `cloudsmith whoami --verbose`."
+)
+
+
+def get_credentials(server_url, credential=None, api_host=None):
+    """
+    Get credentials for a Cloudsmith Docker registry.
+
+    Verifies the URL is a Cloudsmith registry (including custom domains)
+    and returns credentials if available.
+
+    Args:
+        server_url: The Docker registry server URL
+        credential: Pre-resolved CredentialResult from the provider chain
+        api_host: Cloudsmith API host URL
+
+    Returns:
+        dict: Credentials with 'Username' and 'Secret' keys, or None
+    """
+    if not credential or not credential.api_key:
+        return None
+
+    if not is_cloudsmith_domain(
+        server_url,
+        api_key=credential.api_key,
+        auth_type=getattr(credential, "auth_type", "api_key"),
+        api_host=api_host,
+        backend_kind=BackendKind.DOCKER,
+    ):
+        return None
+
+    return {"Username": "token", "Secret": credential.api_key}
+
+
+def _execute_get(stdin, credential, api_host) -> tuple[int, str | None, str | None]:
+    """Handle the 'get' operation of the Docker credential helper protocol."""
+    try:
+        server_url = stdin.read().strip()
+        if not server_url:
+            return (1, None, "Error: No server URL provided on stdin")
+
+        creds = get_credentials(server_url, credential=credential, api_host=api_host)
+        if creds is None:
+            return (1, None, _REFUSAL_MESSAGE)
+
+        return (0, json.dumps(creds), None)
+    except Exception as exc:  # pylint: disable=broad-except
+        # Protocol boundary: a credential helper must never crash `docker pull`/`push`.
+        # Covers: broken-pipe OSError from stdin.read(), network/SDK errors from
+        # get_credentials, and TypeError from json.dumps — all degrade to a clean
+        # refusal (exit 1), not a traceback.
+        # This is the ONLY intentional broad except in this feature.
+        # (Exception does not catch KeyboardInterrupt/SystemExit, which is correct.)
+        logger.debug("docker credential-helper get failed: %s", exc, exc_info=True)
+        return (1, None, _REFUSAL_MESSAGE)
+
+
+def execute(
+    operation, stdin, credential=None, api_host=None
+) -> tuple[int, str | None, str | None]:
+    """
+    Execute a Docker credential helper protocol operation.
+
+    Args:
+        operation: One of 'get', 'store', 'erase', 'list'
+        stdin: A file-like object to read the server URL from (for 'get')
+        credential: Pre-resolved CredentialResult from the provider chain
+        api_host: Cloudsmith API host URL
+
+    Returns:
+        A (exit_code, stdout_text, stderr_text) tuple.  Either text value may
+        be None if there is nothing to write to that stream.
+    """
+    if operation in ("store", "erase"):
+        # Drain stdin to keep Docker happy; guard against tty/pipe errors.
+        try:
+            if not stdin.isatty():
+                stdin.read()
+        except (OSError, ValueError, AttributeError):
+            pass
+        return (0, None, None)
+
+    if operation == "list":
+        return (0, "{}", None)
+
+    if operation == "get":
+        return _execute_get(stdin, credential, api_host)
+
+    return (
+        1,
+        None,
+        f"Error: Unknown operation '{operation}'. "
+        "Valid operations: get, store, erase, list",
+    )

cloudsmith_cli/credential_helpers/launchers.py

@@ -0,0 +1,175 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Launcher writer/remover for credential-helper on-PATH binaries.
+
+Creates a thin shell script (Unix) or .cmd batch file (Windows) named
+``docker-credential-cloudsmith`` (or similar) that forwards every call to the
+single ``cloudsmith`` binary already installed on the user's PATH.
+
+The platform-specific bits (file name, script body, user bin directory) live in
+small pure helpers parameterised on ``windows`` so they can be unit-tested
+without monkeypatching ``os.name`` — faking ``os.name`` on a posix host makes
+``pathlib.Path`` raise ``NotImplementedError`` on Python < 3.12.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+
+def _is_windows() -> bool:
+    """Return True when running on Windows."""
+    return os.name == "nt"
+
+
+def _launcher_filename(name: str, *, windows: bool) -> str:
+    """Return the launcher file name for the platform (``.cmd`` on Windows)."""
+    return f"{name}.cmd" if windows else name
+
+
+def _launcher_content(target_cmd: str, *, windows: bool) -> str:
+    """Return the launcher script body for the platform.
+
+    Windows uses a ``.cmd`` batch file (``@echo off`` keeps stdout clean for
+    Docker's credential JSON); Unix uses a ``#!/bin/sh`` script that ``exec``s
+    the target so signals and the exit code pass straight through.
+    """
+    if windows:
+        return f"@echo off\r\n{target_cmd} %*\r\n"
+    return f'#!/bin/sh\nexec {target_cmd} "$@"\n'
+
+
+def _user_bin_dir(windows: bool) -> Path:
+    """Return the user-local bin directory for the platform.
+
+    Unix → ``~/.local/bin``; Windows → ``%LOCALAPPDATA%\\Cloudsmith\\bin``
+    (falling back to the home directory when ``LOCALAPPDATA`` is unset).
+    """
+    if windows:
+        localappdata = os.environ.get("LOCALAPPDATA")
+        base = Path(localappdata) if localappdata else Path.home()
+        return base / "Cloudsmith" / "bin"
+    return Path.home() / ".local" / "bin"
+
+
+def write_launcher(bin_dir: Path, name: str, target_cmd: str) -> Path:
+    """Write a launcher script for *name* in *bin_dir* that execs *target_cmd*.
+
+    Parameters
+    ----------
+    bin_dir:
+        Directory in which to create the launcher.  Created if absent.
+    name:
+        Base name of the helper binary (e.g. ``docker-credential-cloudsmith``).
+    target_cmd:
+        The command the launcher forwards to (e.g.
+        ``cloudsmith credential-helper docker``).
+
+    Returns
+    -------
+    Path
+        The path of the written file.
+    """
+    windows = _is_windows()
+    bin_dir = Path(bin_dir)
+    bin_dir.mkdir(parents=True, exist_ok=True)
+
+    dest = bin_dir / _launcher_filename(name, windows=windows)
+    dest.write_text(
+        _launcher_content(target_cmd, windows=windows), encoding="utf-8", newline=""
+    )
+    if not windows:
+        dest.chmod(0o755)
+
+    return dest
+
+
+def remove_launcher(bin_dir: Path, name: str) -> bool:
+    """Remove a launcher previously created by :func:`write_launcher`.
+
+    Parameters
+    ----------
+    bin_dir:
+        Directory that contains (or contained) the launcher.
+    name:
+        Base name of the helper binary (without extension).
+
+    Returns
+    -------
+    bool
+        ``True`` if a file was removed, ``False`` if no file was found.
+    """
+    target = Path(bin_dir) / _launcher_filename(name, windows=_is_windows())
+
+    if target.exists():
+        target.unlink()
+        return True
+    return False
+
+
+def resolve_bin_dir(override: str | None = None) -> Path:
+    """Determine the best directory in which to place a launcher.
+
+    Resolution order
+    ----------------
+    1. *override* → ``Path(override)``.
+    2. The directory of the running ``cloudsmith`` executable — if that
+       directory is writable.
+    3. The user-local bin directory (see :func:`_user_bin_dir`).
+
+    The chosen directory is **not** created here; that happens when the
+    launcher is written via :func:`write_launcher`.
+
+    Parameters
+    ----------
+    override:
+        Explicit path supplied by the caller (e.g. ``--bin-dir`` CLI option).
+
+    Returns
+    -------
+    Path
+        The resolved directory.
+    """
+    if override is not None:
+        return Path(override)
+
+    # Option 2: beside the running cloudsmith binary (if writable)
+    cloudsmith_path = shutil.which("cloudsmith")
+    if cloudsmith_path:
+        candidate = Path(os.path.dirname(os.path.realpath(cloudsmith_path)))
+    else:
+        candidate = Path(os.path.dirname(os.path.realpath(sys.argv[0])))
+
+    if os.access(candidate, os.W_OK | os.X_OK):
+        return candidate
+
+    # Option 3: user-local bin
+    return _user_bin_dir(_is_windows())
+
+
+def is_on_path(directory: Path) -> bool:
+    """Return True if *directory* is an entry in the current ``$PATH``.
+
+    Comparison is case-insensitive on Windows (``os.path.normcase``) and
+    normalised via ``os.path.normpath`` on all platforms.
+
+    Parameters
+    ----------
+    directory:
+        The directory to check.
+
+    Returns
+    -------
+    bool
+        ``True`` if *directory* appears in ``$PATH``.
+    """
+    needle = os.path.normcase(os.path.normpath(str(directory)))
+    path_env = os.environ.get("PATH", "")
+    for entry in path_env.split(os.pathsep):
+        if not entry:
+            continue
+        if os.path.normcase(os.path.normpath(entry)) == needle:
+            return True
+    return False

cloudsmith_cli/data/VERSION

@@ -0,0 +1 @@
+1.20.0

cloudsmith_cli/data/config.ini

@@ -0,0 +1,23 @@
+# Default configuration
+[default]
+# The API host to connect to (default: api.cloudsmith.io).
+api_host=
+
+# The API proxy to connect through (default: None).
+api_proxy=
+
+# Whether to verify SSL connection to the API (default: True)
+api_ssl_verify=true
+
+# The user agent to use for requests (default: calculated).
+api_user_agent=
+
+
+# Profile-based configuration
+# You can set as many additional profiles as you need to provide
+# for different configuration environments (e.g. prod vs staging).
+# Add your overrides in the sections and then specify one of:
+#  * -P your-profile-name (as an argument)
+#  * --profile your-profile-name (an an argument)
+#  * CLOUDSMITH_PROFILE=your-profile-name (as an env variable)
+[profile:your-profile-name]

cloudsmith_cli/data/credentials.ini

@@ -0,0 +1,14 @@
+# Default configuration
+[default]
+# The API key for authenticating with the API.
+api_key=
+
+
+# Profile-based configuration
+# You can set as many additional profiles as you need to provide
+# for different configuration environments (e.g. prod vs staging).
+# Add your overrides in the sections and then specify one of:
+#  * -P your-profile-name (as an argument)
+#  * --profile your-profile-name (an an argument)
+#  * CLOUDSMITH_PROFILE=your-profile-name (as an env variable)
+[profile:your-profile-name]

cloudsmith_cli/templates/__init__.py

@@ -0,0 +1,3 @@
+"""
+HTML templates for Cloudsmith CLI interface.
+"""