mammoth-cli 1.0.0__py3-none-any.whl

mammoth_cli/commands/client_app.py

@@ -0,0 +1,233 @@
+"""Handlers for the ``client-app`` command family.
+
+Client apps are workspace-level API credentials: none of the reviewed manifest
+signatures in this family take a ``project_id`` argument, so no handler here
+requires an active project. The (optional) active project is still reported
+in the envelope metadata for context, mirroring the read handlers in
+:mod:`mammoth_cli.commands.file`. The family's resource id is ``client_key``,
+a string identifier — never a secret — read from the first CLI positional.
+No command in this family accepts application secret material as input at
+all: ``create`` only takes a name and description, and ``update`` forwards an
+opaque ``patch_request`` document from ``--input``, never a positional.
+Handlers dispatch through the generic
+:meth:`~mammoth_cli.services.protocol.MammothService.call` seam to the public
+SDK method named by the command's reviewed manifest ``sdk_symbol``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.errors.envelope import (
+    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, resolved_project
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+
+def _symbol(invocation: Invocation) -> str:
+    """Return the reviewed backing SDK symbol for this command.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The dotted SDK symbol recorded in the command's manifest entry.
+
+    Raises:
+        CliError: ``sdk_symbol_unresolved`` when no symbol is recorded.
+    """
+    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.
+
+    Args:
+        invocation: The current command's resolved global options.
+
+    Returns:
+        The first extra argument, or None when there is none.
+    """
+    return invocation.extra_args[0] if invocation.extra_args else None
+
+
+def _require_string_positional(invocation: Invocation, name: str) -> str:
+    """Return the required first positional argument, or raise usage.
+
+    Args:
+        invocation: The current command's resolved global options.
+        name: A human-readable name for the argument, used in error text.
+
+    Returns:
+        The first extra argument.
+
+    Raises:
+        CliError: ``missing_argument`` when no positional was given.
+    """
+    value = _string_positional(invocation)
+    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.
+
+    Args:
+        document: The parsed ``--input`` request document, or None.
+        field: The required field name.
+
+    Returns:
+        The field's value.
+
+    Raises:
+        CliError: ``missing_field`` when the document or field is absent.
+    """
+    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 of ``fields`` present in ``document`` into ``kwargs``, unchanged.
+
+    Args:
+        document: The parsed ``--input`` request document.
+        kwargs: The keyword arguments accumulator to update in place.
+        fields: The optional field names to forward when present.
+    """
+    for field in fields:
+        if field in document:
+            kwargs[field] = document[field]
+
+
+def _meta(invocation: Invocation, workspace_id: int, project_id: int | None) -> dict[str, Any]:
+    """Build the common envelope metadata for a client-app command.
+
+    Args:
+        invocation: The current command's resolved global options.
+        workspace_id: The authenticated client's resolved workspace id.
+        project_id: The active project id, or None when unset.
+
+    Returns:
+        The envelope metadata mapping.
+    """
+    return {
+        "profile": invocation.profile,
+        "workspace_id": workspace_id,
+        "project_id": project_id,
+    }
+
+
+def client_app_list(invocation: Invocation) -> HandlerResult:
+    """List client apps in the active workspace (requires an admin role)."""
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {}
+    _forward_optional(document, kwargs, ("limit", "offset", "fields", "sort"))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def client_app_get(invocation: Invocation) -> HandlerResult:
+    """Get one client app by its client key."""
+    client_key = _require_string_positional(invocation, "client key")
+    document = invocation.load_input() or {}
+    kwargs: dict[str, Any] = {"client_key": client_key}
+    _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, resolved_project(invocation))
+
+
+def client_app_create(invocation: Invocation) -> HandlerResult:
+    """Create a client app. Name comes from a positional or the ``app_name`` field.
+
+    High-impact: this mints a new set of API credentials in the workspace, so
+    it requires ``--yes --confirm APP_NAME``. No secret material is ever
+    accepted as input here; any tokens are returned by the API, not supplied.
+    """
+    document = invocation.load_input() or {}
+    app_name = _string_positional(invocation) or document.get("app_name")
+    if not app_name:
+        raise CliError(
+            code=CODE_MISSING_ARGUMENT,
+            message="A client app name is required.",
+            exit_status=EXIT_USAGE,
+            hint="Pass the name as a positional argument or an 'app_name' input field.",
+        )
+    enforce_confirmation(
+        invocation,
+        policy=POLICY_CONFIRM_TARGET,
+        action=f"create client app '{app_name}'",
+        target=str(app_name),
+    )
+    kwargs: dict[str, Any] = {"app_name": app_name}
+    _forward_optional(document, kwargs, ("description",))
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), **kwargs)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def client_app_update(invocation: Invocation) -> HandlerResult:
+    """Apply a patch request to one client app. Client key is positional.
+
+    High-impact: requires ``--yes --confirm CLIENT_KEY``. The patch document
+    is a required ``--input`` field (``patch_request``); no secret material
+    is ever taken from a positional argument.
+    """
+    client_key = _require_string_positional(invocation, "client key")
+    document = invocation.load_input()
+    patch_request = _require_field(document, "patch_request")
+    enforce_confirmation(
+        invocation,
+        policy=POLICY_CONFIRM_TARGET,
+        action=f"update client app {client_key}",
+        target=str(client_key),
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), client_key=client_key, patch_request=patch_request)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
+
+
+def client_app_delete(invocation: Invocation) -> HandlerResult:
+    """Permanently delete one client app by its client key. Prompt or ``--yes`` required."""
+    client_key = _require_string_positional(invocation, "client key")
+    enforce_confirmation(
+        invocation, policy=POLICY_PROMPT_OR_YES, action=f"delete client app {client_key}"
+    )
+    with open_service(invocation) as (service, auth):
+        data = service.call(_symbol(invocation), client_key=client_key)
+    return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))

mammoth_cli/commands/completion.py

@@ -0,0 +1,82 @@
+"""The ``completion`` commands: show or install shell tab-completion.
+
+``completion show`` prints the activation snippet for a shell (deterministic,
+side-effect free). ``completion install`` appends that snippet to the shell's
+startup file, idempotently, and reports the path. Both resolve the shell from a
+positional argument, the ``--input`` ``shell`` field, or the ``$SHELL``
+environment variable, and never prompt.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
+from mammoth_cli.runtime.invocation import Invocation
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+# click/Typer complete-var for the ``mammoth`` program.
+_COMPLETE_VAR = "_MAMMOTH_COMPLETE"
+_SUPPORTED = ("bash", "zsh", "fish")
+
+
+def _snippet(shell: str) -> str:
+    if shell == "fish":
+        return f"{_COMPLETE_VAR}=fish_source mammoth | source"
+    return f'eval "$({_COMPLETE_VAR}={shell}_source mammoth)"'
+
+
+def _rc_path(shell: str) -> Path:
+    home = Path.home()
+    if shell == "bash":
+        return home / ".bashrc"
+    if shell == "zsh":
+        return home / ".zshrc"
+    return home / ".config" / "fish" / "config.fish"
+
+
+def _resolve_shell(invocation: Invocation) -> str:
+    document = invocation.load_input() or {}
+    candidate = (
+        (invocation.extra_args[0] if invocation.extra_args else None)
+        or document.get("shell")
+        or os.path.basename(os.environ.get("SHELL", ""))
+    )
+    shell = str(candidate).strip().lower()
+    if shell not in _SUPPORTED:
+        raise CliError(
+            code="unsupported_shell",
+            message=f"Cannot generate completion for shell '{candidate or ''}'.",
+            exit_status=EXIT_USAGE,
+            hint=f"Pass one of: {', '.join(_SUPPORTED)}.",
+        )
+    return shell
+
+
+def completion_show(invocation: Invocation) -> HandlerResult:
+    """Print the completion activation snippet for a shell."""
+    shell = _resolve_shell(invocation)
+    return {"shell": shell, "script": _snippet(shell)}, {}
+
+
+def completion_install(invocation: Invocation) -> HandlerResult:
+    """Append the completion snippet to the shell startup file, idempotently."""
+    shell = _resolve_shell(invocation)
+    snippet = _snippet(shell)
+    rc_path = _rc_path(shell)
+    rc_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = rc_path.read_text(encoding="utf-8") if rc_path.exists() else ""
+    added = snippet not in existing
+    if added:
+        prefix = "" if existing.endswith("\n") or not existing else "\n"
+        with rc_path.open("a", encoding="utf-8") as handle:
+            handle.write(f"{prefix}# Mammoth CLI completion\n{snippet}\n")
+    return {
+        "shell": shell,
+        "path": str(rc_path),
+        "added": added,
+        "detail": "installed" if added else "already present",
+    }, {}

mammoth_cli/commands/config.py

@@ -0,0 +1,309 @@
+"""Bespoke `config` command family: get, set, list, path.
+
+Manages non-secret, profile-scoped configuration: the default output mode,
+the timeout family, the one-label server prefix, and the active project id.
+All local; no command in this family makes a network call.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from mammoth_cli.context import profiles
+from mammoth_cli.context.endpoint import resolve_base_url
+from mammoth_cli.errors.envelope import (
+    CODE_INVALID_CONFIG_VALUE,
+    CODE_PROFILE_NOT_FOUND,
+    EXIT_USAGE,
+    CliError,
+)
+from mammoth_cli.output.policy import VALID_OUTPUTS
+from mammoth_cli.runtime import executor
+from mammoth_cli.runtime import options as go
+from mammoth_cli.runtime.invocation import Invocation
+
+#: The timeout-family setting keys, shared between the settable-key registry
+#: and the numeric-parsing branch below.
+_TIMEOUT_KEYS = ("timeout", "job_timeout", "pipeline_timeout")
+_PROFILE_KEYS = ("server_prefix", "project")
+_SETTING_KEYS = ("output", *_TIMEOUT_KEYS)
+ALL_CONFIG_KEYS = tuple(sorted(_PROFILE_KEYS + _SETTING_KEYS))
+
+
+def _profile_name(invocation: Invocation) -> str:
+    return invocation.profile or profiles.get_selected()
+
+
+def _unknown_key_error(key: str) -> CliError:
+    return CliError(
+        code="unknown_config_key",
+        message=f"'{key}' is not a recognized configuration key.",
+        exit_status=EXIT_USAGE,
+        hint=f"Use one of: {', '.join(ALL_CONFIG_KEYS)}.",
+    )
+
+
+def _profile_not_found_error(profile_name: str) -> CliError:
+    return CliError(
+        code=CODE_PROFILE_NOT_FOUND,
+        message=f"No profile named '{profile_name}' exists yet.",
+        exit_status=EXIT_USAGE,
+        hint="Run 'mammoth auth login' first.",
+        recovery_commands=["mammoth auth login"],
+    )
+
+
+def _validate_key(key: str) -> None:
+    if key not in _PROFILE_KEYS and key not in _SETTING_KEYS:
+        raise _unknown_key_error(key)
+
+
+def _get_value(profile_name: str, key: str) -> str | int | None:
+    if key in _SETTING_KEYS:
+        return profiles.get_setting(profile_name, key)
+    record = profiles.get_profile(profile_name)
+    if record is None:
+        return None
+    if key == "project":
+        return record.project_id
+    return record.server_prefix
+
+
+def _require_profile(profile_name: str) -> profiles.ProfileRecord:
+    existing = profiles.get_profile(profile_name)
+    if existing is None:
+        raise _profile_not_found_error(profile_name)
+    return existing
+
+
+def _set_value(profile_name: str, key: str, value: str) -> str | int | float:
+    if key == "output":
+        if value not in VALID_OUTPUTS:
+            raise CliError(
+                code=CODE_INVALID_CONFIG_VALUE,
+                message=f"'{value}' is not a valid --output mode.",
+                exit_status=EXIT_USAGE,
+                hint=f"Use one of: {', '.join(VALID_OUTPUTS)}.",
+            )
+        profiles.set_setting(profile_name, key, value)
+        return value
+
+    if key in _TIMEOUT_KEYS:
+        try:
+            parsed = float(value)
+        except ValueError as exc:
+            raise CliError(
+                code=CODE_INVALID_CONFIG_VALUE,
+                message=f"'{value}' is not a number.",
+                exit_status=EXIT_USAGE,
+            ) from exc
+        if parsed <= 0:
+            raise CliError(
+                code=CODE_INVALID_CONFIG_VALUE,
+                message="Timeouts must be positive.",
+                exit_status=EXIT_USAGE,
+            )
+        profiles.set_setting(profile_name, key, value)
+        return parsed
+
+    if key == "project":
+        try:
+            project_id = int(value)
+        except ValueError as exc:
+            raise CliError(
+                code=CODE_INVALID_CONFIG_VALUE,
+                message=f"'{value}' is not an integer project id.",
+                exit_status=EXIT_USAGE,
+            ) from exc
+        if project_id <= 0:
+            raise CliError(
+                code=CODE_INVALID_CONFIG_VALUE,
+                message="project must be a positive integer.",
+                exit_status=EXIT_USAGE,
+            )
+        existing = _require_profile(profile_name)
+        profiles.save_profile(
+            profiles.ProfileRecord(
+                name=existing.name,
+                workspace_id=existing.workspace_id,
+                server_prefix=existing.server_prefix,
+                project_id=project_id,
+            )
+        )
+        return project_id
+
+    if key == "server_prefix":
+        resolve_base_url(value)
+        existing = _require_profile(profile_name)
+        profiles.save_profile(
+            profiles.ProfileRecord(
+                name=existing.name,
+                workspace_id=existing.workspace_id,
+                server_prefix=value,
+                project_id=existing.project_id,
+            )
+        )
+        return value
+
+    raise _unknown_key_error(key)
+
+
+def config_get(
+    output: str = go.output_option(),
+    profile: str | None = go.profile_option(),
+    project: int | None = go.project_option(),
+    timeout: float | None = go.timeout_option(),
+    job_timeout: float | None = go.job_timeout_option(),
+    pipeline_timeout: float | None = go.pipeline_timeout_option(),
+    color: str = go.color_option(),
+    no_input: bool = go.no_input_option(),
+    no_progress: bool = go.no_progress_option(),
+    debug: bool = go.debug_option(),
+    input_file: str | None = go.input_file_option(),
+    input_format: str | None = go.input_format_option(),
+    key: str = typer.Argument(..., help="Configuration key."),
+) -> None:
+    """Get one profile-scoped configuration value."""
+    invocation = go.make_invocation(
+        "config.get",
+        output=output,
+        profile=profile,
+        project=project,
+        timeout=timeout,
+        job_timeout=job_timeout,
+        pipeline_timeout=pipeline_timeout,
+        color=color,
+        no_input=no_input,
+        no_progress=no_progress,
+        debug=debug,
+        input_file=input_file,
+        input_format=input_format,
+    )
+
+    def producer() -> tuple[Any, dict[str, Any]]:
+        _validate_key(key)
+        profile_name = _profile_name(invocation)
+        value = _get_value(profile_name, key)
+        return {"key": key, "value": value, "profile": profile_name}, {"profile": profile_name}
+
+    executor.run(invocation.command_id, invocation.output, producer)
+
+
+def config_set(
+    output: str = go.output_option(),
+    profile: str | None = go.profile_option(),
+    project: int | None = go.project_option(),
+    timeout: float | None = go.timeout_option(),
+    job_timeout: float | None = go.job_timeout_option(),
+    pipeline_timeout: float | None = go.pipeline_timeout_option(),
+    color: str = go.color_option(),
+    no_input: bool = go.no_input_option(),
+    no_progress: bool = go.no_progress_option(),
+    debug: bool = go.debug_option(),
+    input_file: str | None = go.input_file_option(),
+    input_format: str | None = go.input_format_option(),
+    key: str = typer.Argument(..., help="Configuration key."),
+    value: str = typer.Argument(..., help="New value."),
+) -> None:
+    """Set one profile-scoped configuration value."""
+    invocation = go.make_invocation(
+        "config.set",
+        output=output,
+        profile=profile,
+        project=project,
+        timeout=timeout,
+        job_timeout=job_timeout,
+        pipeline_timeout=pipeline_timeout,
+        color=color,
+        no_input=no_input,
+        no_progress=no_progress,
+        debug=debug,
+        input_file=input_file,
+        input_format=input_format,
+    )
+
+    def producer() -> tuple[Any, dict[str, Any]]:
+        _validate_key(key)
+        profile_name = _profile_name(invocation)
+        stored = _set_value(profile_name, key, value)
+        return {"key": key, "value": stored, "profile": profile_name}, {"profile": profile_name}
+
+    executor.run(invocation.command_id, invocation.output, producer)
+
+
+def config_list(
+    output: str = go.output_option(),
+    profile: str | None = go.profile_option(),
+    project: int | None = go.project_option(),
+    timeout: float | None = go.timeout_option(),
+    job_timeout: float | None = go.job_timeout_option(),
+    pipeline_timeout: float | None = go.pipeline_timeout_option(),
+    color: str = go.color_option(),
+    no_input: bool = go.no_input_option(),
+    no_progress: bool = go.no_progress_option(),
+    debug: bool = go.debug_option(),
+    input_file: str | None = go.input_file_option(),
+    input_format: str | None = go.input_format_option(),
+) -> None:
+    """List every profile-scoped configuration value."""
+    invocation = go.make_invocation(
+        "config.list",
+        output=output,
+        profile=profile,
+        project=project,
+        timeout=timeout,
+        job_timeout=job_timeout,
+        pipeline_timeout=pipeline_timeout,
+        color=color,
+        no_input=no_input,
+        no_progress=no_progress,
+        debug=debug,
+        input_file=input_file,
+        input_format=input_format,
+    )
+
+    def producer() -> tuple[Any, dict[str, Any]]:
+        profile_name = _profile_name(invocation)
+        values = {key: _get_value(profile_name, key) for key in ALL_CONFIG_KEYS}
+        return {"profile": profile_name, "values": values}, {"profile": profile_name}
+
+    executor.run(invocation.command_id, invocation.output, producer)
+
+
+def config_path(
+    output: str = go.output_option(),
+    profile: str | None = go.profile_option(),
+    project: int | None = go.project_option(),
+    timeout: float | None = go.timeout_option(),
+    job_timeout: float | None = go.job_timeout_option(),
+    pipeline_timeout: float | None = go.pipeline_timeout_option(),
+    color: str = go.color_option(),
+    no_input: bool = go.no_input_option(),
+    no_progress: bool = go.no_progress_option(),
+    debug: bool = go.debug_option(),
+    input_file: str | None = go.input_file_option(),
+    input_format: str | None = go.input_format_option(),
+) -> None:
+    """Print the path to the non-secret profiles file."""
+    invocation = go.make_invocation(
+        "config.path",
+        output=output,
+        profile=profile,
+        project=project,
+        timeout=timeout,
+        job_timeout=job_timeout,
+        pipeline_timeout=pipeline_timeout,
+        color=color,
+        no_input=no_input,
+        no_progress=no_progress,
+        debug=debug,
+        input_file=input_file,
+        input_format=input_format,
+    )
+
+    def producer() -> tuple[Any, dict[str, Any]]:
+        return {"profiles_path": str(profiles.profiles_path())}, {}
+
+    executor.run(invocation.command_id, invocation.output, producer)