solwyn-cli 0.1.0__py3-none-any.whl

solwyn_cli/commands/whoami.py

@@ -0,0 +1,170 @@
+"""Current identity command."""
+
+from typing import Literal
+
+import typer
+from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
+
+from solwyn_cli.auth import (
+    AuthError,
+    JwtCredential,
+    ProjectKeyCredential,
+    resolve_credential,
+)
+from solwyn_cli.client import SolwynClient
+from solwyn_cli.commands._shared import exit_with_error
+from solwyn_cli.errors import ApiError
+from solwyn_cli.exit_codes import ErrorSemantic
+from solwyn_cli.help import help_contract
+from solwyn_cli.output import OutputError, TableData
+from solwyn_cli.runtime import command_context, output_engine
+
+
+WHOAMI_HELP = help_contract(
+    endpoint=("local key identity or GET /api/v1/account/me and GET /api/v1/projects"),
+    auth="any",
+    exits="0 success; 1 generic/API; 2 usage; 3 auth",
+    schema="solwyn.whoami.v1",
+)
+
+
+class _Identity(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    user_id: str
+    email: str
+    display_name: str
+    subscription_tier: Literal["free", "founder", "team", "scale"]
+
+
+class _Project(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    id: str
+    name: str
+
+
+class _WhoamiData(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    auth_type: Literal["jwt", "project_key"]
+    auth_source: Literal["keyring", "environment"]
+    configured_project: str | None
+    user: _Identity | None
+    projects: list[_Project]
+    hint: str | None
+
+
+_PROJECTS = TypeAdapter(list[_Project])
+
+
+def _key_data(credential: ProjectKeyCredential, project: str | None) -> _WhoamiData:
+    return _WhoamiData(
+        auth_type="project_key",
+        auth_source=credential.source,
+        configured_project=project,
+        user=None,
+        projects=[],
+        hint=(
+            None
+            if project is not None
+            else "Choose a project with --project, SOLWYN_PROJECT_ID, or config."
+        ),
+    )
+
+
+def _jwt_data(context: typer.Context, credential: JwtCredential) -> _WhoamiData:
+    runtime = command_context(context)
+    try:
+        with SolwynClient(
+            api_url=runtime.api_url,
+            credential=credential,
+        ) as client:
+            identity_response = client.request("GET", "/api/v1/account/me")
+            projects_response = client.request("GET", "/api/v1/projects")
+        identity = _Identity.model_validate(identity_response.json())
+        projects = _PROJECTS.validate_python(projects_response.json())
+    except ApiError as error:
+        exit_with_error(context, error)
+    except AuthError as error:
+        exit_with_error(
+            context,
+            OutputError(code="authentication_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    except (ValidationError, ValueError, TypeError):
+        exit_with_error(
+            context,
+            OutputError(
+                code="invalid_identity_response",
+                message="The identity response was invalid.",
+            ),
+        )
+    return _WhoamiData(
+        auth_type="jwt",
+        auth_source="keyring",
+        configured_project=None,
+        user=identity,
+        projects=projects,
+        hint=None,
+    )
+
+
+def _table(data: _WhoamiData) -> TableData:
+    rows: list[tuple[str, str]] = [
+        ("Authentication", data.auth_type),
+        ("Source", data.auth_source),
+    ]
+    if data.auth_type == "project_key":
+        rows.append(("Configured project", data.configured_project or "not configured"))
+        if data.hint is not None:
+            rows.append(("Hint", data.hint))
+    elif data.user is not None:
+        rows.extend(
+            [
+                ("User", data.user.display_name),
+                ("Email", data.user.email),
+                ("Tier", data.user.subscription_tier),
+            ]
+        )
+        rows.extend(
+            ("Project", f"{project.id} ({project.name})") for project in data.projects
+        )
+    return TableData(
+        columns=("Field", "Value"),
+        rows=tuple(rows),
+        right_align=("Value",),
+    )
+
+
+def whoami(context: typer.Context) -> None:
+    """Show the current Solwyn identity and project context."""
+    try:
+        credential = resolve_credential()
+    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,
+        )
+    runtime = command_context(context)
+    data = (
+        _key_data(credential, runtime.project)
+        if isinstance(credential, ProjectKeyCredential)
+        else _jwt_data(context, credential)
+    )
+    output_engine(context).write_success(
+        schema="solwyn.whoami.v1",
+        data=data,
+        table=_table(data),
+    )

solwyn_cli/config.py

@@ -0,0 +1,209 @@
+"""Allowlisted, non-secret local configuration for the Solwyn CLI."""
+
+import os
+import tempfile
+import tomllib
+from collections.abc import Mapping
+from contextlib import contextmanager
+from pathlib import Path
+from typing import BinaryIO, Iterator, Literal
+from urllib.parse import urlsplit
+
+import tomli_w
+from platformdirs import user_config_dir
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+class ConfigLoadError(ValueError):
+    """Configuration could not be safely loaded."""
+
+
+class ConfigWriteError(OSError):
+    """Configuration could not be safely persisted."""
+
+
+class Config(BaseModel):
+    """Persisted CLI settings; credentials are intentionally not modeled."""
+
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+
+    api_url: str = "https://api.solwyn.ai"
+    default_project: str | None = None
+    format: Literal["table", "json"] = "table"
+
+    @field_validator("api_url")
+    @classmethod
+    def validate_api_url(cls, value: str) -> str:
+        """Require a credential-free absolute HTTP(S) API base URL."""
+        try:
+            parsed = urlsplit(value)
+            parsed.port
+        except ValueError:
+            raise ValueError("api_url must be a safe absolute HTTP(S) URL") from None
+
+        authority = parsed.netloc.rsplit("@", maxsplit=1)[-1]
+        if (
+            value != value.strip()
+            or "\\" in value
+            or any(character.isspace() for character in value)
+            or parsed.scheme not in {"http", "https"}
+            or parsed.hostname is None
+            or parsed.username is not None
+            or parsed.password is not None
+            or "?" in value
+            or "#" in value
+            or authority.endswith(":")
+        ):
+            raise ValueError("api_url must be a safe absolute HTTP(S) URL")
+        return value
+
+
+CONFIG_KEYS = frozenset(Config.model_fields)
+
+
+def get_config_path() -> Path:
+    """Return the platform-native path to the user's local configuration."""
+    return Path(user_config_dir("solwyn")) / "config.toml"
+
+
+def load_config() -> Config:
+    """Load allowlisted settings, returning defaults when no file exists."""
+    path = get_config_path()
+    if not path.exists():
+        return Config()
+
+    try:
+        with path.open("rb") as config_file:
+            values = tomllib.load(config_file)
+        return Config.model_validate(values)
+    except (
+        OSError,
+        UnicodeError,
+        tomllib.TOMLDecodeError,
+        ValidationError,
+        TypeError,
+    ) as exc:
+        raise ConfigLoadError(f"Could not load configuration at {path}.") from exc
+
+
+def _acquire_lock(lock_file: BinaryIO) -> None:
+    """Acquire an exclusive advisory lock using the host platform API."""
+    if os.name == "nt":
+        lock_file.seek(0, os.SEEK_END)
+        if lock_file.tell() == 0:
+            lock_file.write(b"\0")
+            lock_file.flush()
+        lock_file.seek(0)
+        msvcrt.locking(lock_file.fileno(), msvcrt.LK_LOCK, 1)
+    else:
+        fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+
+
+def _release_lock(lock_file: BinaryIO) -> None:
+    """Release a lock acquired by :func:`_acquire_lock`."""
+    if os.name == "nt":
+        lock_file.seek(0)
+        msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)
+    else:
+        fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+
+
+@contextmanager
+def _config_lock(path: Path) -> Iterator[None]:
+    """Hold the cross-process lock associated with a configuration path."""
+    lock_path = path.with_suffix(f"{path.suffix}.lock")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        lock_file = lock_path.open("a+b")
+        try:
+            _acquire_lock(lock_file)
+        except OSError:
+            lock_file.close()
+            raise
+    except OSError as exc:
+        raise ConfigWriteError(f"Could not lock configuration at {path}.") from exc
+
+    try:
+        yield
+    finally:
+        try:
+            _release_lock(lock_file)
+        except OSError as exc:
+            raise ConfigWriteError(
+                f"Could not unlock configuration at {path}."
+            ) from exc
+        finally:
+            lock_file.close()
+
+
+def _fsync_parent_directory(path: Path) -> None:
+    """Durably record an atomic replace on POSIX; Windows has no directory fsync."""
+    if os.name == "nt":
+        return
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    directory_fd = os.open(path.parent, flags)
+    try:
+        os.fsync(directory_fd)
+    finally:
+        os.close(directory_fd)
+
+
+def save_config(config: Config, *, omit_default_api_url: bool = False) -> None:
+    """Atomically persist only modeled, non-null settings."""
+    path = get_config_path()
+    values = config.model_dump(include=CONFIG_KEYS, exclude_none=True)
+    if omit_default_api_url and config.api_url == Config().api_url:
+        values.pop("api_url", None)
+    content = tomli_w.dumps(values)
+    temporary_path: Path | None = None
+
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as temporary_file:
+            temporary_path = Path(temporary_file.name)
+            temporary_file.write(content)
+            temporary_file.flush()
+            os.fsync(temporary_file.fileno())
+        os.replace(temporary_path, path)
+        _fsync_parent_directory(path)
+    except OSError as exc:
+        raise ConfigWriteError(f"Could not write configuration at {path}.") from exc
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+
+
+def update_config_value(key: str, value: str) -> Config:
+    """Atomically read, validate, and update one allowlisted setting."""
+    return update_config_values({key: value})
+
+
+def update_config_values(
+    values: Mapping[str, object], *, omit_default_api_url: bool = False
+) -> Config:
+    """Atomically merge and persist multiple allowlisted settings under one lock."""
+    invalid_keys = set(values).difference(CONFIG_KEYS)
+    if invalid_keys:
+        invalid_key = sorted(invalid_keys)[0]
+        raise ValueError(f"Invalid configuration key: {invalid_key}")
+
+    path = get_config_path()
+    with _config_lock(path):
+        current = load_config()
+        updated = Config.model_validate(
+            {**current.model_dump(include=CONFIG_KEYS), **values}
+        )
+        save_config(updated, omit_default_api_url=omit_default_api_url)
+    return updated

solwyn_cli/errors.py

@@ -0,0 +1,114 @@
+"""Safe typed errors for HTTP and API failures."""
+
+import unicodedata
+from typing import Any, TypeAlias
+from urllib.parse import urlsplit
+
+import httpx
+
+
+RawDetail: TypeAlias = str | dict[str, Any]
+
+
+class ApiError(RuntimeError):
+    """A structured request failure whose repr does not expose raw detail."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int | None,
+        code: str,
+        message: str,
+        hint: str | None,
+        detail: RawDetail | None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.hint = hint
+        self.detail = detail
+
+
+def _safe_cta_path(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    if not value.startswith("/") or value.startswith("//") or "\\" in value:
+        return None
+    if any(unicodedata.category(character).startswith("C") for character in value):
+        return None
+    try:
+        parsed = urlsplit(value)
+    except ValueError:
+        return None
+    if parsed.scheme or parsed.netloc or parsed.username or parsed.password:
+        return None
+    return value
+
+
+def _upgrade_hint(cta_path: str) -> str:
+    return f"Review upgrade options in the dashboard: {cta_path}"
+
+
+def _quota_hint(cta_path: str) -> str:
+    return f"Review usage and plan limits in the dashboard: {cta_path}"
+
+
+def _project_limit_hint(cta_path: str) -> str:
+    return f"Manage project limits in the dashboard: {cta_path}"
+
+
+_ENTITLEMENT_HINTS = {
+    "upgrade_required": _upgrade_hint,
+    "quota_exceeded": _quota_hint,
+    "project_limit_reached": _project_limit_hint,
+}
+
+
+def _response_detail(response: httpx.Response) -> RawDetail | None:
+    try:
+        payload = response.json()
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(payload, dict):
+        return None
+    detail = payload.get("detail")
+    if isinstance(detail, (str, dict)):
+        return detail
+    return None
+
+
+def error_from_response(
+    response: httpx.Response,
+    *,
+    code_override: str | None = None,
+) -> ApiError:
+    """Turn an unsuccessful response into a safe structured error."""
+    detail = _response_detail(response)
+    fallback_message = f"Request failed with status {response.status_code}."
+    code = code_override or "http_error"
+    message = detail if isinstance(detail, str) else fallback_message
+    hint = None
+
+    if isinstance(detail, dict):
+        server_code = detail.get("code")
+        server_message = detail.get("message")
+        if code_override is None and isinstance(server_code, str) and server_code:
+            code = server_code
+        if isinstance(server_message, str) and server_message:
+            message = server_message
+
+        hint_builder = (
+            _ENTITLEMENT_HINTS.get(code) if response.status_code == 402 else None
+        )
+        cta_path = _safe_cta_path(detail.get("cta_path"))
+        if hint_builder is not None and cta_path is not None:
+            hint = hint_builder(cta_path)
+
+    return ApiError(
+        status_code=response.status_code,
+        code=code,
+        message=message,
+        hint=hint,
+        detail=detail,
+    )

solwyn_cli/exit_codes.py

@@ -0,0 +1,56 @@
+"""Stable process exit codes for the Solwyn CLI machine contract."""
+
+from enum import IntEnum, StrEnum
+
+from solwyn_cli.auth import AuthError
+from solwyn_cli.errors import ApiError
+
+
+class ExitCode(IntEnum):
+    """Permanently frozen exit meanings across all CLI major versions."""
+
+    SUCCESS = 0
+    GENERIC_ERROR = 1
+    USAGE_ERROR = 2
+    AUTH_ERROR = 3
+    BUDGET_DENIED = 4
+    NOT_FOUND = 5
+
+
+class ErrorSemantic(StrEnum):
+    """Explicit local semantics that cannot be inferred from HTTP status alone."""
+
+    GENERIC = "generic"
+    USAGE = "usage"
+    AUTH = "auth"
+    BUDGET_DENIED = "budget_denied"
+    NOT_FOUND = "not_found"
+
+
+_SEMANTIC_EXIT_CODES = {
+    ErrorSemantic.GENERIC: ExitCode.GENERIC_ERROR,
+    ErrorSemantic.USAGE: ExitCode.USAGE_ERROR,
+    ErrorSemantic.AUTH: ExitCode.AUTH_ERROR,
+    ErrorSemantic.BUDGET_DENIED: ExitCode.BUDGET_DENIED,
+    ErrorSemantic.NOT_FOUND: ExitCode.NOT_FOUND,
+}
+
+
+def exit_code_for_error(
+    error: BaseException | None,
+    *,
+    semantic: ErrorSemantic | None = None,
+) -> ExitCode:
+    """Map typed failures without interfering with Click's native usage handling."""
+    if semantic is not None:
+        return _SEMANTIC_EXIT_CODES[semantic]
+    if error is None:
+        return ExitCode.SUCCESS
+    if isinstance(error, AuthError):
+        return ExitCode.AUTH_ERROR
+    if isinstance(error, ApiError):
+        if error.status_code == 401:
+            return ExitCode.AUTH_ERROR
+        if error.status_code == 404:
+            return ExitCode.NOT_FOUND
+    return ExitCode.GENERIC_ERROR

solwyn_cli/help.py

@@ -0,0 +1,19 @@
+"""Stable, machine-legible CLI help contract formatting."""
+
+
+def help_contract(
+    *,
+    endpoint: str,
+    auth: str,
+    exits: str,
+    schema: str,
+    guidance: tuple[str, ...] = (),
+) -> str:
+    """Render one semantic help contract without terminal-specific formatting."""
+    contract = (
+        f"Endpoint: {endpoint}",
+        f"Auth: {auth}",
+        f"Exit codes: {exits}",
+        f"JSON schema: {schema}",
+    )
+    return "\n".join((*contract, *guidance))

solwyn_cli/main.py

@@ -0,0 +1,135 @@
+"""Command-line entrypoint for Solwyn."""
+
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+
+from solwyn_cli import __version__
+from solwyn_cli.commands.agent_context import AGENT_CONTEXT_HELP, agent_context
+from solwyn_cli.commands.budget import app as budget_app
+from solwyn_cli.commands.config import app as config_app
+from solwyn_cli.commands.costs import COSTS_HELP, costs
+from solwyn_cli.commands.init import INIT_HELP, init
+from solwyn_cli.commands.login import LOGIN_HELP, LOGOUT_HELP, login, logout
+from solwyn_cli.commands.mcp import MCP_HELP, McpLaunchOptions, mcp
+from solwyn_cli.commands.keys import app as keys_app
+from solwyn_cli.commands.projects import app as projects_app
+from solwyn_cli.commands.status import STATUS_HELP, status
+from solwyn_cli.commands.whoami import WHOAMI_HELP, whoami
+from solwyn_cli.config import ConfigLoadError
+from solwyn_cli.help import help_contract
+from solwyn_cli.output import OutputError, OutputUsageError
+from solwyn_cli.runtime import (
+    bootstrap_output_engine,
+    resolve_command_context,
+    validate_output_intent,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    invoke_without_command=True,
+    no_args_is_help=True,
+    epilog=help_contract(
+        endpoint="composite command router",
+        auth="varies by command",
+        exits="0 success; 2 usage",
+        schema="varies by command",
+        guidance=(
+            "Agents: run solwyn agent-context for the compact capability contract.",
+        ),
+    ),
+)
+app.add_typer(budget_app, name="budget")
+app.add_typer(config_app, name="config")
+app.add_typer(keys_app, name="keys")
+app.add_typer(projects_app, name="projects")
+app.command("agent-context", epilog=AGENT_CONTEXT_HELP)(agent_context)
+app.command("costs", epilog=COSTS_HELP)(costs)
+app.command("init", epilog=INIT_HELP)(init)
+app.command("login", epilog=LOGIN_HELP)(login)
+app.command("logout", epilog=LOGOUT_HELP)(logout)
+app.command("mcp", epilog=MCP_HELP)(mcp)
+app.command("status", epilog=STATUS_HELP)(status)
+app.command("whoami", epilog=WHOAMI_HELP)(whoami)
+
+
+@app.callback()
+def main(
+    context: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", help="Show the installed version and exit.", is_eager=True
+        ),
+    ] = False,
+    project: Annotated[
+        str | None,
+        typer.Option("--project", "-p", help="Project ID for this invocation."),
+    ] = None,
+    api_url: Annotated[
+        str | None,
+        typer.Option("--api-url", help="Solwyn API base URL."),
+    ] = None,
+    output_format: Annotated[
+        str | None,
+        typer.Option("--format", help="Output format: table or json."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Emit schema-bearing JSON output."),
+    ] = False,
+    no_color: Annotated[
+        bool,
+        typer.Option("--no-color", help="Disable terminal color."),
+    ] = False,
+) -> None:
+    """Work with Solwyn from the command line."""
+    if version:
+        typer.echo(f"solwyn {__version__}")
+        raise typer.Exit()
+    if context.invoked_subcommand == "mcp":
+        context.obj = McpLaunchOptions(api_url=api_url, project_id=project)
+        return
+    if context.invoked_subcommand in {"agent-context", "config"}:
+        return
+    try:
+        validate_output_intent(
+            output_format=output_format,
+            json_flag=json_output,
+        )
+    except OutputUsageError:
+        raise typer.BadParameter(
+            "Invalid or conflicting output options.", param_hint="format"
+        ) from None
+    try:
+        context.obj = resolve_command_context(
+            api_url=api_url,
+            project=project,
+            output_format=output_format,
+            json_flag=json_output,
+            no_color=no_color,
+        )
+    except OutputUsageError:
+        raise typer.BadParameter(
+            "Invalid or conflicting output options.", param_hint="format"
+        ) from None
+    except ValidationError:
+        raise typer.BadParameter("Invalid API URL.", param_hint="api-url") from None
+    except ConfigLoadError:
+        if context.invoked_subcommand == "init":
+            bootstrap_output_engine(
+                output_format=output_format,
+                json_flag=json_output,
+                no_color=no_color,
+            ).write_error(
+                OutputError(
+                    code="config_load_failed",
+                    message="The existing configuration could not be loaded.",
+                    hint="Repair or remove the configuration file, then retry init.",
+                )
+            )
+            raise typer.Exit(code=1) from None
+        raise typer.BadParameter(
+            "Could not load configuration.", param_hint="config"
+        ) from None