mammoth-cli 1.0.0__py3-none-any.whl

mammoth_cli/commands/workspace.py

@@ -0,0 +1,359 @@
+"""Handlers for the ``workspace`` command family.
+
+None of these commands are project-scoped: every handler resolves an
+authenticated service and dispatches to the public SDK method named by the
+command's reviewed manifest ``sdk_symbol``, using the generic
+:meth:`~mammoth_cli.services.protocol.MammothService.call` seam. A handful of
+commands target a single, specific workspace (``get``, ``delete``,
+``reactivate``, ``update``); for those, the workspace id comes from the first
+CLI positional when given, and is otherwise left unset so the SDK falls back
+to the client's own workspace. All other required fields (tokens, bodies,
+patch lists, email lists) come from the strict ``--input`` document.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import (
+    CODE_INVALID_ARGUMENT,
+    CODE_MISSING_ARGUMENT,
+    CODE_MISSING_FIELD,
+    CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_USAGE,
+    CliError,
+)
+from mammoth_cli.manifest.loader import command_by_id
+from mammoth_cli.runtime.confirm import (
+    POLICY_CONFIRM_TARGET,
+    POLICY_PROMPT_OR_YES,
+    enforce_confirmation,
+)
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command."""
+    record = command_by_id(invocation.command_id)
+    if record is None or not record.get("sdk_symbol"):
+        raise CliError(
+            code=CODE_SDK_SYMBOL_UNRESOLVED,
+            message=f"No SDK symbol is recorded for '{invocation.command_id}'.",
+            exit_status=EXIT_USAGE,
+        )
+    return str(record["sdk_symbol"])
+
+
+def _string_positional(invocation: Invocation) -> str | None:
+    """Return the first positional argument, or None if absent."""
+    return invocation.extra_args[0] if invocation.extra_args else None
+
+
+def _require_string_positional(invocation: Invocation, name: str) -> str:
+    """Return the first positional argument, or raise a usage error."""
+    value = _string_positional(invocation)
+    if not value:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message=f"This command requires a {name} argument.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass the {name} as a positional argument.",
+        )
+    return value
+
+
+def _int_positional(invocation: Invocation, name: str) -> int | None:
+    """Parse the first positional argument as an int, or return None if absent."""
+    if not invocation.extra_args:
+        return None
+    raw = invocation.extra_args[0]
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message=f"The {name} argument '{raw}' is not an integer.",
+            exit_status=EXIT_USAGE,
+        ) from exc
+
+
+def _require_int_positional(invocation: Invocation, name: str) -> int:
+    """Parse the first positional argument as an int, or raise a usage error."""
+    value = _int_positional(invocation, name)
+    if value is None:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message=f"This command requires a {name} argument.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass the {name} as a positional argument.",
+        )
+    return value
+
+
+def _require_field(document: dict[str, Any] | None, field: str) -> Any:
+    """Return a required field from the ``--input`` document, or raise usage."""
+    if document is None or field not in document:
+        raise CliError(
+            code=CODE_MISSING_FIELD,
+            message=f"This command requires the '{field}' input field.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass it via --input, for example: --input '{{\"{field}\": ...}}'.",
+        )
+    return document[field]
+
+
+def _forward_optional(
+    document: dict[str, Any], kwargs: dict[str, Any], fields: tuple[str, ...]
+) -> None:
+    """Copy each present field from ``document`` into ``kwargs`` under the same name."""
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int) -> dict[str, Any]:
+    """Build the common envelope metadata for a workspace command (no project scope)."""
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": None,
+    }
+
+
+def workspace_accept_invite(invocation: Invocation) -> HandlerResult:
+    """Accept a pending workspace invite using a token from ``--input``."""
+    document = invocation.load_input()
+    token = _require_field(document, "token")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), token=token)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_app_usage(invocation: Invocation) -> HandlerResult:
+    """Report app usage stats for the current workspace."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("fields",))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_check_expression(invocation: Invocation) -> HandlerResult:
+    """Ask the AI assistant to check an expression. Payload comes from ``--input``."""
+    document = invocation.load_input()
+    body = _require_field(document, "body")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), body=body)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_create(invocation: Invocation) -> HandlerResult:
+    """Create a new workspace. Payload comes from the ``body`` input field."""
+    document = invocation.load_input()
+    body = _require_field(document, "body")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), body=body)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_delete(invocation: Invocation) -> HandlerResult:
+    """Delete a workspace. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    explicit = _int_positional(invocation, "workspace id")
+    with open_service(invocation) as (service, auth):
+        target_id = explicit if explicit is not None else auth.workspace_id
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"delete workspace {target_id}",
+            target=str(target_id),
+        )
+        kwargs: dict[str, Any] = {}
+        if explicit is not None:
+            kwargs["workspace_id"] = explicit
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_get(invocation: Invocation) -> HandlerResult:
+    """Get one workspace by id (positional), or the client's own workspace."""
+    explicit = _int_positional(invocation, "workspace id")
+    kwargs: dict[str, Any] = {}
+    if explicit is not None:
+        kwargs["workspace_id"] = explicit
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_list(invocation: Invocation) -> HandlerResult:
+    """List accessible workspaces."""
+    document = invocation.load_input() or {}
+    limit = int(document.get("limit", 100))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), limit=limit)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_llm_task(invocation: Invocation) -> HandlerResult:
+    """Submit a unified LLM task. ``task_type`` and ``params`` come from ``--input``."""
+    document = invocation.load_input()
+    task_type = _require_field(document, "task_type")
+    params = _require_field(document, "params")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), task_type=task_type, params=params)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_reactivate(invocation: Invocation) -> HandlerResult:
+    """Reactivate a deactivated workspace. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    explicit = _int_positional(invocation, "workspace id")
+    with open_service(invocation) as (service, auth):
+        target_id = explicit if explicit is not None else auth.workspace_id
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"reactivate workspace {target_id}",
+            target=str(target_id),
+        )
+        kwargs: dict[str, Any] = {}
+        if explicit is not None:
+            kwargs["workspace_id"] = explicit
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_segment_list(invocation: Invocation) -> HandlerResult:
+    """List split-test segments for the workspace."""
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation))
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_segment_update(invocation: Invocation) -> HandlerResult:
+    """Update split-test segments. ``patch`` comes from ``--input``."""
+    document = invocation.load_input()
+    patch = _require_field(document, "patch")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), patch=patch)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_storage_breakdown(invocation: Invocation) -> HandlerResult:
+    """Report a breakdown of storage usage for the workspace."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("limit", "offset"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_update(invocation: Invocation) -> HandlerResult:
+    """Patch workspace settings. High-impact: ``--yes --confirm WORKSPACE_ID``."""
+    explicit = _int_positional(invocation, "workspace id")
+    document = invocation.load_input()
+    patches = _require_field(document, "patches")
+    with open_service(invocation) as (service, auth):
+        target_id = explicit if explicit is not None else auth.workspace_id
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=f"update workspace {target_id}",
+            target=str(target_id),
+        )
+        kwargs: dict[str, Any] = {"patches": patches}
+        if explicit is not None:
+            kwargs["workspace_id"] = explicit
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_add(invocation: Invocation) -> HandlerResult:
+    """Invite one or more users to the workspace."""
+    document = invocation.load_input()
+    email_ids = _require_field(document, "email_ids")
+    kwargs: dict[str, Any] = {"email_ids": email_ids}
+    assert document is not None
+    _forward_optional(document, kwargs, ("projects",))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_get(invocation: Invocation) -> HandlerResult:
+    """Get one workspace user by id (positional), in the client's own workspace."""
+    user_id = _require_string_positional(invocation, "user id")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), user_id=user_id)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_list(invocation: Invocation) -> HandlerResult:
+    """List users in the client's own workspace."""
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation))
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_remove(invocation: Invocation) -> HandlerResult:
+    """Remove a single user from the workspace. Prompt or ``--yes`` required."""
+    user_id = _require_int_positional(invocation, "user id")
+    enforce_confirmation(
+        invocation,
+        policy=POLICY_PROMPT_OR_YES,
+        action=f"remove user {user_id} from the workspace",
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), user_id=user_id)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_remove_batch(invocation: Invocation) -> HandlerResult:
+    """Remove several users and/or pending invites. Prompt or ``--yes`` required."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("ids", "invite_ids"))
+    if not kwargs:
+        raise CliError(
+            code=CODE_MISSING_FIELD,
+            message="Provide at least one of 'ids' or 'invite_ids' to remove.",
+            exit_status=EXIT_USAGE,
+            hint="Pass fields via --input.",
+        )
+    enforce_confirmation(
+        invocation,
+        policy=POLICY_PROMPT_OR_YES,
+        action="remove users or invites from the workspace",
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_update(invocation: Invocation) -> HandlerResult:
+    """Update a user's role. High-impact: ``--yes --confirm USER_ID``."""
+    user_id = _require_string_positional(invocation, "user id")
+    document = invocation.load_input()
+    patches = _require_field(document, "patches")
+    enforce_confirmation(
+        invocation,
+        policy=POLICY_CONFIRM_TARGET,
+        action=f"update user {user_id}",
+        target=user_id,
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), user_id=user_id, patches=patches)
+    return data, _meta(invocation, auth.workspace_id)
+
+
+def workspace_user_update_batch(invocation: Invocation) -> HandlerResult:
+    """Update workspace users via JSON-patch operations. ``patches`` from ``--input``."""
+    document = invocation.load_input()
+    patches = _require_field(document, "patches")
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), patches=patches)
+    return data, _meta(invocation, auth.workspace_id)

mammoth_cli/context/__init__.py

@@ -0,0 +1 @@
+"""context layer for the Mammoth CLI."""

mammoth_cli/context/credentials.py

@@ -0,0 +1,223 @@
+"""Secret credential storage: OS keyring first, permission-checked file second.
+
+Stores a JSON blob ``{"api_key": ..., "api_secret": ...}`` under keyring
+service ``mammoth-cli`` with the profile name as username. When no keyring
+backend is available, an explicit or interactively-approved fallback stores
+the same blob in ``credentials.toml`` beside ``profiles.toml``, with
+directory mode ``0700`` and file mode ``0600`` on POSIX. A secret value is
+never logged or included in any rendered output.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import tempfile
+from pathlib import Path
+from typing import Literal
+
+import keyring
+import keyring.errors
+import tomlkit
+from tomlkit import TOMLDocument
+
+from mammoth_cli.context.profiles import config_dir
+from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
+
+KEYRING_SERVICE = "mammoth-cli"
+CREDENTIALS_FILENAME = "credentials.toml"
+
+StorageMode = Literal["auto", "keyring", "file"]
+
+_FAIL_BACKEND_MODULE = "keyring.backends.fail"
+
+
+def keyring_unavailable_error() -> CliError:
+    """Build the stable error for a missing or unusable OS keyring backend."""
+    return CliError(
+        code="keyring_unavailable",
+        message="No OS keyring is available to store the credential.",
+        exit_status=EXIT_USAGE,
+        hint="Store the credential in a permission-checked file instead.",
+        recovery_commands=["mammoth auth login --storage file"],
+    )
+
+
+def _keyring_available() -> bool:
+    try:
+        backend = keyring.get_keyring()
+    except keyring.errors.NoKeyringError:
+        return False
+    return type(backend).__module__ != _FAIL_BACKEND_MODULE
+
+
+def credentials_path() -> Path:
+    """Return the path to the file-fallback credential store."""
+    return config_dir() / CREDENTIALS_FILENAME
+
+
+def _store_keyring(profile: str, api_key: str, api_secret: str) -> None:
+    payload = json.dumps({"api_key": api_key, "api_secret": api_secret})
+    keyring.set_password(KEYRING_SERVICE, profile, payload)
+
+
+def _load_keyring(profile: str) -> tuple[str, str] | None:
+    try:
+        raw = keyring.get_password(KEYRING_SERVICE, profile)
+    except keyring.errors.KeyringError:
+        return None
+    if raw is None:
+        return None
+    data = json.loads(raw)
+    return str(data["api_key"]), str(data["api_secret"])
+
+
+def _delete_keyring(profile: str) -> bool:
+    try:
+        keyring.delete_password(KEYRING_SERVICE, profile)
+        return True
+    except keyring.errors.KeyringError:
+        return False
+
+
+def _load_file_document() -> TOMLDocument:
+    path = credentials_path()
+    if not path.exists():
+        return tomlkit.document()
+    return tomlkit.parse(path.read_text(encoding="utf-8"))
+
+
+def _write_file_document(document: TOMLDocument) -> None:
+    directory = config_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    if os.name == "posix":
+        os.chmod(directory, stat.S_IRWXU)
+    fd, tmp_name = tempfile.mkstemp(dir=str(directory), prefix=".credentials-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(tomlkit.dumps(document))
+        if os.name == "posix":
+            os.chmod(tmp_name, stat.S_IRUSR | stat.S_IWUSR)
+        os.replace(tmp_name, credentials_path())
+    except BaseException:
+        if os.path.exists(tmp_name):
+            os.remove(tmp_name)
+        raise
+
+
+def _store_file(profile: str, api_key: str, api_secret: str) -> None:
+    document = _load_file_document()
+    table = document.get("profiles")
+    if table is None:
+        table = tomlkit.table()
+        document["profiles"] = table
+    entry = tomlkit.table()
+    entry["api_key"] = api_key
+    entry["api_secret"] = api_secret
+    table[profile] = entry
+    _write_file_document(document)
+
+
+def _load_file(profile: str) -> tuple[str, str] | None:
+    document = _load_file_document()
+    table = document.get("profiles")
+    if not table or profile not in table:
+        return None
+    entry = table[profile]
+    return str(entry["api_key"]), str(entry["api_secret"])
+
+
+def _delete_file(profile: str) -> bool:
+    document = _load_file_document()
+    table = document.get("profiles")
+    if not table or profile not in table:
+        return False
+    del table[profile]
+    _write_file_document(document)
+    return True
+
+
+def store_credentials(
+    profile: str,
+    api_key: str,
+    api_secret: str,
+    storage: StorageMode = "auto",
+    *,
+    interactive: bool = False,
+) -> str:
+    """Store one profile's secret credential.
+
+    Args:
+        profile: The (already-validated) profile name.
+        api_key: The Mammoth API key.
+        api_secret: The Mammoth API secret.
+        storage: ``"auto"`` prefers the OS keyring and falls back to the file
+            store only when interactive; ``"keyring"`` requires the keyring;
+            ``"file"`` uses the permission-checked fallback file explicitly.
+        interactive: Whether the current process has an interactive TTY.
+            Only consulted by ``"auto"`` when no keyring backend exists.
+
+    Returns:
+        The storage backend actually used: ``"keyring"`` or ``"file"``.
+
+    Raises:
+        CliError: ``keyring_unavailable`` when keyring storage is required (or
+            selected by ``"auto"`` noninteractively) but no backend exists.
+    """
+    if storage == "file":
+        _store_file(profile, api_key, api_secret)
+        return "file"
+    if storage == "keyring":
+        if not _keyring_available():
+            raise keyring_unavailable_error()
+        _store_keyring(profile, api_key, api_secret)
+        return "keyring"
+    if _keyring_available():
+        _store_keyring(profile, api_key, api_secret)
+        return "keyring"
+    if interactive:
+        _store_file(profile, api_key, api_secret)
+        return "file"
+    raise keyring_unavailable_error()
+
+
+def load_credentials(profile: str) -> tuple[str, str] | None:
+    """Load one profile's secret credential.
+
+    Tries the OS keyring first, then the file fallback.
+
+    Args:
+        profile: The profile name.
+
+    Returns:
+        ``(api_key, api_secret)`` if a credential is stored, else None.
+    """
+    if _keyring_available():
+        found = _load_keyring(profile)
+        if found is not None:
+            return found
+    return _load_file(profile)
+
+
+def has_credentials(profile: str) -> bool:
+    """Return True if a secret credential is stored for ``profile``.
+
+    Args:
+        profile: The profile name.
+    """
+    return load_credentials(profile) is not None
+
+
+def delete_credentials(profile: str) -> bool:
+    """Delete one profile's secret credential from both backends.
+
+    Args:
+        profile: The profile name.
+
+    Returns:
+        True if a credential was removed from either backend.
+    """
+    removed_keyring = _delete_keyring(profile) if _keyring_available() else False
+    removed_file = _delete_file(profile)
+    return removed_keyring or removed_file

mammoth_cli/context/endpoint.py

@@ -0,0 +1,57 @@
+"""Resolve the Mammoth API base url from a server prefix.
+
+A server prefix is the only endpoint input the CLI exposes; it maps to
+``https://PREFIX.mammoth.io/api/v2`` with default ``app-eu``. There is no
+public base-url override: the supported configuration surface is exactly the
+API key, API secret, workspace id, and this optional one-label server prefix.
+"""
+
+from __future__ import annotations
+
+import re
+
+from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
+
+DEFAULT_SERVER_PREFIX = "app-eu"
+
+# One DNS label: 1-63 characters, alphanumeric, internal hyphens only. This
+# rejects schemes, dots, slashes, query strings, fragments, ports, and
+# whitespace by construction.
+_DNS_LABEL_RE = re.compile(r"^[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?$")
+
+
+def invalid_server_prefix_error(prefix: str) -> CliError:
+    """Build the stable error for a malformed server prefix.
+
+    Args:
+        prefix: The rejected candidate prefix.
+
+    Returns:
+        A ``invalid_server_prefix`` :class:`CliError` (exit status 2).
+    """
+    return CliError(
+        code="invalid_server_prefix",
+        message=f"'{prefix}' is not a valid server prefix.",
+        exit_status=EXIT_USAGE,
+        hint="Use one DNS label, for example 'app-eu'.",
+    )
+
+
+def resolve_base_url(server_prefix: str | None) -> str:
+    """Resolve the API base url from a server prefix.
+
+    Args:
+        server_prefix: A one-label server prefix (for example ``"app-eu"``),
+            or None to use the default ``app-eu``.
+
+    Returns:
+        The resolved API base url.
+
+    Raises:
+        CliError: ``invalid_server_prefix`` when the prefix is not one valid
+            DNS label.
+    """
+    prefix = server_prefix if server_prefix is not None else DEFAULT_SERVER_PREFIX
+    if not _DNS_LABEL_RE.match(prefix):
+        raise invalid_server_prefix_error(prefix)
+    return f"https://{prefix}.mammoth.io/api/v2"