refactor: extract shared create_session utility

Move HTTP session creation logic into a shared create_session() function
in cloudsmith_cli/core/credentials/session.py. This provides a single
place for configuring proxy, SSL verification, user-agent, headers, and
optional Bearer auth on requests sessions.

Refactor KeyringProvider to use the shared function instead of inline
session configuration.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: cloudsmith-iduffy

cloudsmith_cli/cli/decorators.py

@@ -7,6 +7,7 @@
 from cloudsmith_cli.cli import validators
 
 from ..core.api.init import initialise_api as _initialise_api
+from ..core.config_resolver import ConfigResolver
 from ..core.credentials import CredentialContext, CredentialProviderChain
 from ..core.mcp import server
 from . import config, utils
@@ -315,16 +316,21 @@ def _set_boolean(name, invert=False):
         opts.error_retry_codes = kwargs.pop("error_retry_codes")
         opts.error_retry_cb = report_retry
 
+        client_config = ConfigResolver().resolve(
+            api_host=opts.api_host,
+            proxy=opts.api_proxy,
+            ssl_verify=opts.api_ssl_verify,
+            user_agent=opts.api_user_agent,
+            headers=opts.api_headers,
+            debug=opts.debug,
+        )
+
         credential_context = CredentialContext(
-            api_host=opts.api_host or "https://api.cloudsmith.io",
+            config=client_config,
             creds_file_path=ctx.meta.get("creds_file"),
             profile=ctx.meta.get("profile"),
             debug=opts.debug,
             cli_api_key=opts.api_key,
-            proxy=opts.api_proxy,
-            ssl_verify=opts.api_ssl_verify if opts.api_ssl_verify is not None else True,
-            user_agent=opts.api_user_agent,
-            headers=opts.api_headers,
         )
 
         chain = CredentialProviderChain()

cloudsmith_cli/core/config_resolver.py

@@ -0,0 +1,300 @@
+"""Unified configuration resolution for the Cloudsmith CLI.
+
+Inspired by boto3/botocore's ConfigChain pattern: each configuration
+variable is resolved through an ordered list of sources (explicit
+override → environment variable → config file → default).  The resolved
+values are collected into a frozen :class:`ClientConfig` dataclass that
+is passed to HTTP sessions, API clients, and credential providers.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .credentials.session import create_session
+
+logger = logging.getLogger(__name__)
+
+_SENTINEL = object()
+
+
+# ---------------------------------------------------------------------------
+# Source providers
+# ---------------------------------------------------------------------------
+
+
+class InstanceProvider:
+    """Return an explicit value supplied at call-site (e.g. a CLI flag)."""
+
+    def __init__(self, value: Any):
+        self._value = value
+
+    def __call__(self) -> Any:
+        return self._value
+
+
+class EnvironmentProvider:
+    """Read a value from an environment variable."""
+
+    def __init__(self, env_var: str, cast: Callable | None = None):
+        self._env_var = env_var
+        self._cast = cast
+
+    def __call__(self) -> Any:
+        raw = os.environ.get(self._env_var, "").strip()
+        if not raw:
+            return None
+        if self._cast:
+            return self._cast(raw)
+        return raw
+
+
+class ConfigFileProvider:
+    """Read a value from the CLI config.ini file."""
+
+    def __init__(
+        self, key: str, section: str = "default", cast: Callable | None = None
+    ):
+        self._key = key
+        self._section = section
+        self._cast = cast
+
+    def __call__(self) -> Any:
+        try:
+            from ..cli.config import ConfigReader
+
+            raw_config = ConfigReader.read_config()
+            value = raw_config.get(self._section, {}).get(self._key)
+            if value is None:
+                return None
+            if isinstance(value, str):
+                value = value.strip()
+                if not value:
+                    return None
+            if self._cast:
+                return self._cast(value)
+            return value
+        except Exception:  # pylint: disable=broad-exception-caught
+            logger.debug("Failed to read %s from config file", self._key, exc_info=True)
+            return None
+
+
+# ---------------------------------------------------------------------------
+# Chain resolver
+# ---------------------------------------------------------------------------
+
+
+class ChainProvider:
+    """Resolve a config value from an ordered list of source providers.
+
+    Walks the providers in order and returns the first non-``None`` value.
+    If all providers return ``None``, returns the given *default*.
+    """
+
+    def __init__(self, providers: list[Callable], default: Any = None):
+        self._providers = providers
+        self._default = default
+
+    def resolve(self) -> Any:
+        for provider in self._providers:
+            value = provider()
+            if value is not None:
+                return value
+        return self._default
+
+
+# ---------------------------------------------------------------------------
+# Cast helpers
+# ---------------------------------------------------------------------------
+
+
+def _cast_bool_truthy(value: str | bool) -> bool:
+    """Cast a string to bool where truthy values are ``1/true/yes``."""
+    if isinstance(value, bool):
+        return value
+    return value.lower() in ("1", "true", "yes")
+
+
+def _cast_bool_falsy_means_disabled(value: str | bool) -> bool:
+    """For ``CLOUDSMITH_WITHOUT_API_SSL_VERIFY``: truthy means *disable* SSL."""
+    return not _cast_bool_truthy(value)
+
+
+def _cast_bool_ssl_config(value: str | bool) -> bool:
+    """For config.ini ``api_ssl_verify``: ``0/false/no`` means disable."""
+    if isinstance(value, bool):
+        return value
+    return value.lower() not in ("0", "false", "no")
+
+
+def _cast_headers(value: str | dict | None) -> dict | None:
+    """Parse ``key=value,key2=value2`` CSV into a dict."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return value
+    headers = {}
+    for pair in value.split(","):
+        if "=" in pair:
+            k, v = pair.split("=", 1)
+            headers[k.strip()] = v.strip()
+    return headers or None
+
+
+# ---------------------------------------------------------------------------
+# ClientConfig
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ClientConfig:  # pylint: disable=too-many-instance-attributes
+    """Resolved, immutable configuration for Cloudsmith operations.
+
+    Created once by :class:`ConfigResolver` and passed to HTTP sessions,
+    API clients, credential providers, and OIDC detectors.
+    """
+
+    api_host: str = "https://api.cloudsmith.io"
+    proxy: str | None = None
+    ssl_verify: bool = True
+    user_agent: str | None = None
+    headers: dict | None = None
+    debug: bool = False
+
+    # Feature flags
+    no_keyring: bool = False
+
+    def create_session(self, api_key: str | None = None, retry=_SENTINEL):
+        """Create an HTTP session with this config applied.
+
+        Args:
+            api_key: Optional API key for Bearer auth.
+            retry: urllib3 Retry configuration.  Defaults to the
+                :data:`DEFAULT_RETRY` policy defined in
+                :mod:`~cloudsmith_cli.core.credentials.session`.
+                Pass ``None`` to disable retries.
+        """
+        from .credentials.session import DEFAULT_RETRY
+
+        return create_session(
+            proxy=self.proxy,
+            ssl_verify=self.ssl_verify,
+            user_agent=self.user_agent,
+            headers=self.headers,
+            api_key=api_key,
+            retry=DEFAULT_RETRY if retry is _SENTINEL else retry,
+        )
+
+
+# ---------------------------------------------------------------------------
+# ConfigResolver
+# ---------------------------------------------------------------------------
+
+
+class ConfigResolver:
+    """Build a :class:`ClientConfig` by resolving each variable through its chain.
+
+    Resolution order per variable: explicit override → env var → config file → default.
+
+    Usage::
+
+        # CLI entry-point — pass CLI flag values as overrides
+        config = ConfigResolver().resolve(
+            api_host=opts.api_host,
+            proxy=opts.api_proxy,
+        )
+
+        # Credential-helper entry-point — no overrides, resolve from env/config
+        config = ConfigResolver().resolve()
+    """
+
+    def resolve(self, **overrides: Any) -> ClientConfig:
+        """Resolve all config variables and return a frozen :class:`ClientConfig`.
+
+        Args:
+            **overrides: Explicit values (e.g. from CLI flags).  ``None``
+                values are silently ignored so callers can pass optional
+                values without filtering.
+        """
+        return ClientConfig(
+            api_host=self._resolve_api_host(overrides),
+            proxy=self._resolve_proxy(overrides),
+            ssl_verify=self._resolve_ssl_verify(overrides),
+            user_agent=self._resolve_user_agent(overrides),
+            headers=self._resolve_headers(overrides),
+            debug=bool(overrides.get("debug", False)),
+            no_keyring=self._resolve_no_keyring(overrides),
+        )
+
+    # -- individual resolvers ------------------------------------------------
+
+    @staticmethod
+    def _resolve_api_host(overrides: dict) -> str:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("api_host")),
+                EnvironmentProvider("CLOUDSMITH_API_HOST"),
+                ConfigFileProvider("api_host"),
+            ],
+            default="https://api.cloudsmith.io",
+        ).resolve()
+
+    @staticmethod
+    def _resolve_proxy(overrides: dict) -> str | None:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("proxy")),
+                EnvironmentProvider("CLOUDSMITH_API_PROXY"),
+                ConfigFileProvider("api_proxy"),
+            ],
+        ).resolve()
+
+    @staticmethod
+    def _resolve_ssl_verify(overrides: dict) -> bool:
+        override = overrides.get("ssl_verify")
+        if override is not None:
+            return bool(override)
+        return ChainProvider(
+            [
+                EnvironmentProvider(
+                    "CLOUDSMITH_WITHOUT_API_SSL_VERIFY",
+                    cast=_cast_bool_falsy_means_disabled,
+                ),
+                ConfigFileProvider("api_ssl_verify", cast=_cast_bool_ssl_config),
+            ],
+            default=True,
+        ).resolve()
+
+    @staticmethod
+    def _resolve_user_agent(overrides: dict) -> str | None:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("user_agent")),
+                EnvironmentProvider("CLOUDSMITH_API_USER_AGENT"),
+            ],
+        ).resolve()
+
+    @staticmethod
+    def _resolve_headers(overrides: dict) -> dict | None:
+        return ChainProvider(
+            [
+                InstanceProvider(overrides.get("headers")),
+                EnvironmentProvider("CLOUDSMITH_API_HEADERS", cast=_cast_headers),
+                ConfigFileProvider("api_headers", cast=_cast_headers),
+            ],
+        ).resolve()
+
+    @staticmethod
+    def _resolve_no_keyring(overrides: dict) -> bool:
+        override = overrides.get("no_keyring")
+        if override is not None:
+            return bool(override)
+        return ChainProvider(
+            [
+                EnvironmentProvider("CLOUDSMITH_NO_KEYRING", cast=_cast_bool_truthy),
+            ],
+            default=False,
+        ).resolve()

cloudsmith_cli/core/credentials/__init__.py

@@ -8,7 +8,10 @@
 
 import logging
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..config_resolver import ClientConfig
 
 logger = logging.getLogger(__name__)
 
@@ -17,20 +20,40 @@
 class CredentialContext:  # pylint: disable=too-many-instance-attributes
     """Context passed to credential providers during resolution."""
 
-    api_host: str = "https://api.cloudsmith.io"
-    config_file_path: str | None = None
+    config: ClientConfig | None = None
+
+    # Credential-specific inputs (not part of ClientConfig)
+    cli_api_key: str | None = None
     creds_file_path: str | None = None
+    config_file_path: str | None = None
     profile: str | None = None
     debug: bool = False
-    # Pre-resolved values from CLI flags (highest priority)
-    cli_api_key: str | None = None
-    # API networking configuration
-    proxy: str | None = None
-    ssl_verify: bool = True
-    user_agent: str | None = None
-    headers: dict | None = None
     keyring_refresh_failed: bool = False
 
+    # -- Convenience properties delegating to config -----------------------
+
+    @property
+    def api_host(self) -> str:
+        if self.config:
+            return self.config.api_host
+        return "https://api.cloudsmith.io"
+
+    @property
+    def proxy(self) -> str | None:
+        return self.config.proxy if self.config else None
+
+    @property
+    def ssl_verify(self) -> bool:
+        return self.config.ssl_verify if self.config else True
+
+    @property
+    def user_agent(self) -> str | None:
+        return self.config.user_agent if self.config else None
+
+    @property
+    def headers(self) -> dict | None:
+        return self.config.headers if self.config else None
+
 
 @dataclass
 class CredentialResult: