solwyn-cli 0.1.0__py3-none-any.whl

solwyn_cli/artifacts/_atomic.py

@@ -0,0 +1,79 @@
+"""Descriptor-relative atomic rename operations for Tier-1 POSIX platforms."""
+
+import ctypes
+import errno
+import os
+import sys
+
+
+_LIBC = ctypes.CDLL(None, use_errno=True)
+_LINUX_NOREPLACE = 1
+_LINUX_EXCHANGE = 2
+_MACOS_SWAP = 0x00000002
+_MACOS_EXCL = 0x00000004
+
+
+def _call(
+    function_name: str, source: str, target: str, parent_fd: int, flag: int
+) -> None:
+    try:
+        function = getattr(_LIBC, function_name)
+    except AttributeError:
+        raise OSError(
+            errno.ENOTSUP,
+            f"Atomic rename operation {function_name} is unavailable.",
+        ) from None
+    function.argtypes = [
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_int,
+        ctypes.c_char_p,
+        ctypes.c_uint,
+    ]
+    function.restype = ctypes.c_int
+    ctypes.set_errno(0)
+    result = function(
+        parent_fd,
+        os.fsencode(source),
+        parent_fd,
+        os.fsencode(target),
+        flag,
+    )
+    if result != 0:
+        error_number = ctypes.get_errno() or errno.EIO
+        raise OSError(error_number, os.strerror(error_number), target)
+
+
+def _dispatch(source: str, target: str, parent_fd: int, *, exchange: bool) -> None:
+    if sys.platform == "linux":
+        _call(
+            "renameat2",
+            source,
+            target,
+            parent_fd,
+            _LINUX_EXCHANGE if exchange else _LINUX_NOREPLACE,
+        )
+        return
+    if sys.platform == "darwin":
+        _call(
+            "renameatx_np",
+            source,
+            target,
+            parent_fd,
+            _MACOS_SWAP if exchange else _MACOS_EXCL,
+        )
+        return
+    raise OSError(
+        errno.ENOTSUP,
+        f"Atomic artifact renames are unsupported on {sys.platform}.",
+    )
+
+
+def atomic_exchange(source: str, target: str, parent_fd: int) -> None:
+    """Atomically swap two existing names without losing either inode."""
+    _dispatch(source, target, parent_fd, exchange=True)
+
+
+def atomic_noreplace(source: str, target: str, parent_fd: int) -> None:
+    """Atomically rename source only when target does not exist."""
+    _dispatch(source, target, parent_fd, exchange=False)

solwyn_cli/auth.py

@@ -0,0 +1,252 @@
+"""Credential resolution and bounded JWT refresh for authenticated requests."""
+
+import os
+from collections.abc import Callable, Mapping
+from typing import ClassVar, Literal, TypeAlias
+
+import httpx
+import keyring
+from keyring.errors import NoKeyringError, PasswordDeleteError
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    SecretStr,
+    ValidationError,
+    field_serializer,
+    field_validator,
+)
+
+from solwyn_cli._vendor.validation import validate_project_key_format
+from solwyn_cli._vendor.wire import RefreshRequest
+
+KEYRING_SERVICE = "solwyn-cli"
+API_KEY_ENTRY = "api_key"
+ACCESS_TOKEN_ENTRY = "access_token"
+REFRESH_TOKEN_ENTRY = "refresh_token"
+AUTH_EXIT_CODE = 3
+
+
+class AuthError(RuntimeError):
+    """Authentication failed without exposing credential material."""
+
+    exit_code: ClassVar[int] = AUTH_EXIT_CODE
+
+
+class CredentialStorageError(AuthError):
+    """The operating-system credential store could not be updated."""
+
+
+class ProjectKeyCredential(BaseModel):
+    """A validated project API key with an explicitly retrievable secret."""
+
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+    api_key: SecretStr
+    source: Literal["environment", "keyring"]
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_api_key(cls, value: SecretStr) -> SecretStr:
+        """Keep direct model construction inside the project-key invariant."""
+        validate_project_key_format(value.get_secret_value())
+        return value
+
+    def bearer_value(self) -> str:
+        """Return the key for an Authorization header at the request boundary."""
+        return self.api_key.get_secret_value()
+
+
+class JwtCredential(BaseModel):
+    """A complete access/refresh pair whose repr remains redacted."""
+
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+    access_token: SecretStr = Field(min_length=1)
+    refresh_token: SecretStr = Field(min_length=1)
+
+    def bearer_value(self) -> str:
+        """Return the access token at the request boundary."""
+        return self.access_token.get_secret_value()
+
+    def refresh_value(self) -> str:
+        """Return the refresh token only for the refresh request boundary."""
+        return self.refresh_token.get_secret_value()
+
+
+class _TokenResponse(BaseModel):
+    """Validated token rotation response from the auth API."""
+
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+
+    access_token: SecretStr = Field(min_length=1)
+    refresh_token: SecretStr = Field(min_length=1)
+    token_type: Literal["bearer"] = "bearer"
+
+
+class _RefreshRequest(RefreshRequest):
+    """Refresh request whose in-memory representation redacts its token."""
+
+    refresh_token: SecretStr
+
+    @field_serializer("refresh_token")
+    def serialize_refresh_token(self, value: SecretStr) -> str:
+        """Reveal the token only while constructing the authenticated POST body."""
+        return value.get_secret_value()
+
+
+ResolvedCredential: TypeAlias = ProjectKeyCredential | JwtCredential
+AuthenticatedRequest: TypeAlias = Callable[[ResolvedCredential], httpx.Response]
+CredentialRotation: TypeAlias = Callable[[JwtCredential], None]
+
+
+def _project_key_credential(
+    value: str, source: Literal["environment", "keyring"]
+) -> ProjectKeyCredential:
+    try:
+        validated = validate_project_key_format(value)
+    except ValueError:
+        raise AuthError("Configured project key is invalid.") from None
+    return ProjectKeyCredential(api_key=validated, source=source)
+
+
+def _get_password(entry: str) -> tuple[bool, str | None]:
+    """Read one entry, reporting an unavailable backend as a safe outcome."""
+    try:
+        return True, keyring.get_password(KEYRING_SERVICE, entry)
+    except NoKeyringError:
+        return False, None
+    except Exception:
+        return False, None
+
+
+def resolve_credential(
+    environ: Mapping[str, str] | None = None,
+) -> ResolvedCredential | None:
+    """Resolve credentials in the frozen env, API-key, JWT precedence order."""
+    environment = os.environ if environ is None else environ
+    if "SOLWYN_API_KEY" in environment:
+        return _project_key_credential(environment["SOLWYN_API_KEY"], "environment")
+
+    available, stored_key = _get_password(API_KEY_ENTRY)
+    if not available:
+        return None
+    if stored_key is not None:
+        return _project_key_credential(stored_key, "keyring")
+
+    available, access_token = _get_password(ACCESS_TOKEN_ENTRY)
+    if not available:
+        return None
+    available, refresh_token = _get_password(REFRESH_TOKEN_ENTRY)
+    if not available:
+        return None
+    if not access_token or not refresh_token:
+        return None
+    return JwtCredential(
+        access_token=access_token,
+        refresh_token=refresh_token,
+    )
+
+
+def _set_password(entry: str, value: str) -> None:
+    try:
+        keyring.set_password(KEYRING_SERVICE, entry, value)
+    except NoKeyringError:
+        raise CredentialStorageError(
+            "Could not update credentials in the operating-system keychain."
+        ) from None
+    except Exception:
+        raise CredentialStorageError(
+            "Could not update credentials in the operating-system keychain."
+        ) from None
+
+
+def _confirm_entry_absent(entry: str) -> bool:
+    available, retained_value = _get_password(entry)
+    return available and retained_value is None
+
+
+def _delete_password(entry: str) -> bool:
+    try:
+        keyring.delete_password(KEYRING_SERVICE, entry)
+    except PasswordDeleteError:
+        return _confirm_entry_absent(entry)
+    except NoKeyringError:
+        return _confirm_entry_absent(entry)
+    except Exception:
+        return _confirm_entry_absent(entry)
+    return True
+
+
+def store_project_key(project_key: str) -> ProjectKeyCredential:
+    """Validate and store a project key only in the OS keychain."""
+    credential = _project_key_credential(project_key, "keyring")
+    _set_password(API_KEY_ENTRY, credential.bearer_value())
+    return credential
+
+
+def store_jwt_pair(access_token: str, refresh_token: str) -> JwtCredential:
+    """Store or rotate a complete JWT pair only in the OS keychain."""
+    try:
+        credential = JwtCredential(
+            access_token=access_token,
+            refresh_token=refresh_token,
+        )
+    except ValidationError:
+        raise CredentialStorageError("Received an invalid token pair.") from None
+    _set_password(REFRESH_TOKEN_ENTRY, credential.refresh_value())
+    _set_password(ACCESS_TOKEN_ENTRY, credential.bearer_value())
+    return credential
+
+
+def clear_credentials() -> None:
+    """Remove every supported credential entry from the OS keychain."""
+    all_entries_cleared = True
+    for entry in (API_KEY_ENTRY, ACCESS_TOKEN_ENTRY, REFRESH_TOKEN_ENTRY):
+        if not _delete_password(entry):
+            all_entries_cleared = False
+    if not all_entries_cleared:
+        raise CredentialStorageError(
+            "Could not clear credentials from the operating-system keychain."
+        )
+
+
+def request_with_refresh_retry(
+    *,
+    client: httpx.Client,
+    api_url: str,
+    credential: ResolvedCredential,
+    request: AuthenticatedRequest,
+    on_credential_rotated: CredentialRotation | None = None,
+) -> httpx.Response:
+    """Run a request and make at most one JWT refresh plus one retry on 401."""
+    response = request(credential)
+    if response.status_code != httpx.codes.UNAUTHORIZED:
+        return response
+    if not isinstance(credential, JwtCredential):
+        raise AuthError("Authentication failed. Check your credentials.")
+
+    refresh_request = _RefreshRequest(refresh_token=credential.refresh_value())
+    try:
+        refresh_response = client.post(
+            f"{api_url.rstrip('/')}/api/v1/auth/refresh",
+            json=refresh_request.model_dump(),
+        )
+        if not refresh_response.is_success:
+            raise AuthError("Authentication refresh failed. Log in again.")
+        token_response = _TokenResponse.model_validate(refresh_response.json())
+    except AuthError:
+        raise
+    except (httpx.HTTPError, ValueError, TypeError, ValidationError):
+        raise AuthError("Authentication refresh failed. Log in again.") from None
+
+    rotated = store_jwt_pair(
+        token_response.access_token.get_secret_value(),
+        token_response.refresh_token.get_secret_value(),
+    )
+    if on_credential_rotated is not None:
+        on_credential_rotated(rotated)
+    retry_response = request(rotated)
+    if retry_response.status_code == httpx.codes.UNAUTHORIZED:
+        raise AuthError("Authentication failed after refresh. Log in again.")
+    return retry_response

solwyn_cli/client.py

@@ -0,0 +1,279 @@
+"""Synchronous authenticated HTTP client with bounded retries."""
+
+import time
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import Any, cast
+from urllib.parse import unquote, urlsplit
+
+import httpx
+
+from solwyn_cli import __version__
+from solwyn_cli.auth import (
+    AuthError,
+    JwtCredential,
+    ResolvedCredential,
+    request_with_refresh_retry,
+    resolve_credential,
+)
+from solwyn_cli.errors import ApiError, error_from_response
+
+
+CONNECT_TIMEOUT_SECONDS = 5.0
+READ_TIMEOUT_SECONDS = 30.0
+WRITE_TIMEOUT_SECONDS = 30.0
+POOL_TIMEOUT_SECONDS = 5.0
+MAX_RETRY_AFTER_SECONDS = 10.0
+
+_UNSET = object()
+
+
+def _contains_dot_segment(path: str) -> bool:
+    decoded_path = path
+    while True:
+        normalized_path = decoded_path.replace("\\", "/")
+        if any(segment in {".", ".."} for segment in normalized_path.split("/")):
+            return True
+        next_path = unquote(decoded_path)
+        if next_path == decoded_path:
+            return False
+        decoded_path = next_path
+
+
+def _retry_after_seconds(value: str | None, now: datetime) -> float:
+    if value is None:
+        return 0.0
+    try:
+        integer_delay = int(value.strip())
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(value)
+            if retry_at.tzinfo is None:
+                retry_at = retry_at.replace(tzinfo=UTC)
+            if now.tzinfo is None:
+                now = now.replace(tzinfo=UTC)
+        except (TypeError, ValueError, OverflowError):
+            return 0.0
+        delay = (retry_at - now).total_seconds()
+        return min(MAX_RETRY_AFTER_SECONDS, max(0.0, delay))
+    return float(min(int(MAX_RETRY_AFTER_SECONDS), max(0, integer_delay)))
+
+
+class SolwynClient:
+    """A closeable synchronous client for authenticated Solwyn API requests."""
+
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        credential: ResolvedCredential | None | object = _UNSET,
+        transport: httpx.BaseTransport | None = None,
+        sleeper: Callable[[float], object] = time.sleep,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        normalized_api_url = f"{api_url.rstrip('/')}/"
+        self._api_url = normalized_api_url.rstrip("/")
+        self._credential = credential
+        self._sleeper = sleeper
+        self._clock = clock or (lambda: datetime.now(UTC))
+        self._client = httpx.Client(
+            base_url=normalized_api_url,
+            headers={"User-Agent": f"solwyn-cli/{__version__}"},
+            timeout=httpx.Timeout(
+                connect=CONNECT_TIMEOUT_SECONDS,
+                read=READ_TIMEOUT_SECONDS,
+                write=WRITE_TIMEOUT_SECONDS,
+                pool=POOL_TIMEOUT_SECONDS,
+            ),
+            transport=transport,
+        )
+
+    @property
+    def is_closed(self) -> bool:
+        """Report whether the underlying connection pool is closed."""
+        return self._client.is_closed
+
+    @property
+    def current_credential(self) -> ResolvedCredential:
+        """Return the credential currently retained after any JWT rotation."""
+        return self._resolve_credential()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> "SolwynClient":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def _resolve_credential(self) -> ResolvedCredential:
+        credential = (
+            resolve_credential()
+            if self._credential is _UNSET
+            else cast(ResolvedCredential | None, self._credential)
+        )
+        if credential is None:
+            raise AuthError("Authentication required. Configure credentials and retry.")
+        return credential
+
+    def _prepare_request(
+        self,
+        path: str,
+        kwargs: dict[str, Any],
+    ) -> tuple[str, httpx.Headers]:
+        """Validate a relative path and fixed-timeout request options."""
+        parsed_path = urlsplit(path)
+        if parsed_path.scheme or parsed_path.netloc:
+            raise ApiError(
+                status_code=None,
+                code="invalid_request",
+                message="API request paths must be relative.",
+                hint=None,
+                detail=None,
+            )
+        if _contains_dot_segment(parsed_path.path):
+            raise ApiError(
+                status_code=None,
+                code="invalid_request",
+                message="API request path is invalid.",
+                hint=None,
+                detail=None,
+            )
+        request_extensions = kwargs.get("extensions")
+        if "timeout" in kwargs or (
+            isinstance(request_extensions, Mapping) and "timeout" in request_extensions
+        ):
+            raise ApiError(
+                status_code=None,
+                code="invalid_request",
+                message="Request timeouts are fixed by the CLI.",
+                hint=None,
+                detail=None,
+            )
+        request_headers = httpx.Headers(kwargs.pop("headers", None))
+        request_headers["User-Agent"] = f"solwyn-cli/{__version__}"
+        return path.lstrip("/"), request_headers
+
+    def _send_with_rate_limit_retry(
+        self,
+        *,
+        method: str,
+        path: str,
+        headers: httpx.Headers,
+        kwargs: dict[str, Any],
+        retry_state: list[bool],
+        retry_rate_limit: bool = True,
+    ) -> httpx.Response:
+        """Send with the one shared bounded 429 retry budget."""
+        response = self._client.request(
+            method,
+            path,
+            headers=headers,
+            **kwargs,
+        )
+        if retry_rate_limit and response.status_code == httpx.codes.TOO_MANY_REQUESTS:
+            if retry_state[0]:
+                return response
+            retry_state[0] = True
+            delay = _retry_after_seconds(
+                response.headers.get("Retry-After"), self._clock()
+            )
+            self._sleeper(delay)
+            response = self._client.request(
+                method,
+                path,
+                headers=headers,
+                **kwargs,
+            )
+        return response
+
+    @staticmethod
+    def _raise_for_unsuccessful_response(response: httpx.Response) -> None:
+        if response.status_code == httpx.codes.TOO_MANY_REQUESTS:
+            raise error_from_response(response, code_override="rate_limited")
+        if not response.is_success:
+            raise error_from_response(response)
+
+    def request_unauthenticated(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Make a guarded request without resolving or sending credentials."""
+        relative_path, request_headers = self._prepare_request(path, kwargs)
+        try:
+            response = self._send_with_rate_limit_retry(
+                method=method,
+                path=relative_path,
+                headers=request_headers,
+                kwargs=kwargs,
+                retry_state=[False],
+            )
+        except httpx.HTTPError:
+            raise ApiError(
+                status_code=None,
+                code="transport_error",
+                message="Could not connect to the Solwyn API.",
+                hint=None,
+                detail=None,
+            ) from None
+        self._raise_for_unsuccessful_response(response)
+        return response
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        retry_rate_limit: bool = True,
+        retry_auth: bool = True,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Make one logical request with bounded rate-limit and auth retries."""
+        relative_path, request_headers = self._prepare_request(path, kwargs)
+        credential = self._resolve_credential()
+        retry_state = [False]
+
+        def retain_rotated_credential(rotated: JwtCredential) -> None:
+            if self._credential is not _UNSET:
+                self._credential = rotated
+
+        def send(resolved: ResolvedCredential) -> httpx.Response:
+            headers = request_headers.copy()
+            headers["Authorization"] = f"Bearer {resolved.bearer_value()}"
+            return self._send_with_rate_limit_retry(
+                method=method,
+                path=relative_path,
+                headers=headers,
+                kwargs=kwargs,
+                retry_state=retry_state,
+                retry_rate_limit=retry_rate_limit,
+            )
+
+        try:
+            response = (
+                request_with_refresh_retry(
+                    client=self._client,
+                    api_url=self._api_url,
+                    credential=credential,
+                    request=send,
+                    on_credential_rotated=retain_rotated_credential,
+                )
+                if retry_auth
+                else send(credential)
+            )
+        except httpx.HTTPError:
+            raise ApiError(
+                status_code=None,
+                code="transport_error",
+                message="Could not connect to the Solwyn API.",
+                hint=None,
+                detail=None,
+            ) from None
+
+        self._raise_for_unsuccessful_response(response)
+        return response

solwyn_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command groups exposed by the Solwyn CLI."""

solwyn_cli/commands/_shared.py

@@ -0,0 +1,49 @@
+"""Shared command authentication and error dispatch."""
+
+from collections.abc import Callable
+
+import typer
+
+from solwyn_cli.auth import AuthError, ResolvedCredential, resolve_credential
+from solwyn_cli.errors import ApiError
+from solwyn_cli.exit_codes import ErrorSemantic, exit_code_for_error
+from solwyn_cli.output import OutputError
+from solwyn_cli.runtime import output_engine
+
+
+def required_credential(
+    context: typer.Context,
+    *,
+    resolve: Callable[[], ResolvedCredential | None] = resolve_credential,
+) -> ResolvedCredential:
+    """Resolve one required credential with the stable command auth contract."""
+    try:
+        credential = resolve()
+    except AuthError as error:
+        exit_with_error(
+            context,
+            OutputError(code="authentication_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    if credential is None:
+        exit_with_error(
+            context,
+            OutputError(
+                code="authentication_required",
+                message="Authentication is required.",
+                hint="Set SOLWYN_API_KEY or run solwyn login.",
+            ),
+            semantic=ErrorSemantic.AUTH,
+        )
+    return credential
+
+
+def exit_with_error(
+    context: typer.Context,
+    error: ApiError | OutputError,
+    *,
+    semantic: ErrorSemantic | None = None,
+) -> None:
+    """Render one safe error and stop with its stable process exit code."""
+    output_engine(context).write_error(error)
+    raise typer.Exit(code=int(exit_code_for_error(error, semantic=semantic)))

solwyn_cli/commands/agent_context.py

@@ -0,0 +1,19 @@
+"""Render deterministic agent-facing Solwyn capability guidance."""
+
+import typer
+
+from solwyn_cli.artifacts import ArtifactSurface, render_surface
+from solwyn_cli.help import help_contract
+
+
+AGENT_CONTEXT_HELP = help_contract(
+    endpoint="local capability artifact",
+    auth="local (none)",
+    exits="0 success; 2 usage",
+    schema="none (plain text capability document)",
+)
+
+
+def agent_context() -> None:
+    """Print safe Solwyn budget guidance for coding agents."""
+    typer.echo(render_surface(ArtifactSurface.AGENT_CONTEXT), nl=False)