mammoth-cli 2.2.73__tar.gz → 2.2.74__tar.gz

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.73
+Version: 2.2.74
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
+Project-URL: documentation, https://docs.mammoth.io/build/cli
 Author-email: Mammoth Analytics <support@mammoth.io>
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -17,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.33
+Requires-Dist: mammoth-io<0.9,>=0.8.38
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.2.73"
+__version__ = "2.2.74"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/app.py

@@ -949,7 +949,7 @@ def _execute(invocation: Invocation) -> None:
     from mammoth_cli.runtime.strict import validate_extra_args
 
     if invocation.profile is None:
-        invocation = replace(invocation, profile=profiles.get_selected())
+        invocation = replace(invocation, profile=profiles.get_selected(), profile_is_default=True)
 
     def producer() -> tuple[Any, dict[str, Any]]:
         refuse_hand_crafted_write(invocation.command_id)
@@ -1321,6 +1321,10 @@ def _top_level_typer(name: str) -> typer.Typer:
     return sub
 
 
+#: Groups kept out of ``mammoth --help`` until their backend is generally available.
+#: They still run when typed; only the listing hides them.
+_HIDDEN_UNTIL_GA = frozenset({"agent"})
+
 # Top-level groups are converted to Click on first use. Building the leaf
 # callbacks and ``--help`` text for all ~550 commands, then letting Typer
 # convert every one of them, used to cost most of the CLI's start-up time on
@@ -1337,6 +1341,7 @@ def _load_top_level_group(name: str) -> Any:
         name=name,
         help=_GROUP_DESCRIPTIONS.get(name, f"Commands for {name}."),
         rich_help_panel=_ROOT_HELP_PANELS.get(name),
+        hidden=name in _HIDDEN_UNTIL_GA,
     )
     return typer.main.get_group_from_info(info, **_LAZY_SETTINGS)
 
@@ -1409,6 +1414,7 @@ def _group_stub(name: str) -> Any:
         help=_GROUP_DESCRIPTIONS.get(name, f"Commands for {name}."),
         rich_help_panel=_ROOT_HELP_PANELS.get(name),
         rich_markup_mode=_LAZY_SETTINGS["rich_markup_mode"],
+        hidden=name in _HIDDEN_UNTIL_GA,
     )
 
 

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -266,7 +266,7 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth view data get`. Exact input fields: `mammoth schema get view.data.get`.
 
-Example: `mammoth view data get 123 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth view data get 123 456`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `ViewDataGetResult`; mutation `read`, confirmation `none`, wait policy `always_wait`.
 

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/bundled_skill/mammoth-cli/references/task-start.md

@@ -10,7 +10,7 @@ or secrets in an argument, prompt, transcript, or checkpoint.
 
    ```bash
    python3 -m venv .mammoth && .mammoth/bin/python -m pip install --no-cache-dir --upgrade mammoth-cli
-   .mammoth/bin/mammoth --version      # or: uv tool install mammoth-cli
+   .mammoth/bin/mammoth --version      # or: uv tool install mammoth-cli && uv tool update-shell
    ```
 
    Pin `mammoth-cli==X.Y.Z` when the task names an approved release, and

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/commands/schema.py

@@ -684,7 +684,7 @@ IN_PLACE_RECIPE = (
     "EDITS THE GIVEN VIEW IN PLACE: this adds a step to the view and changes that view "
     "and its dataset's output. To make a NEW dataset and leave the source untouched: "
     "`mammoth view create SOURCE_DATASET_ID` (working view), do the steps on that working "
-    'view, then `mammoth view export dataset WORKING_VIEW_ID` (add dataset_name only if the user named it).'
+    "view, then `mammoth view export dataset WORKING_VIEW_ID` (add dataset_name only if the user named it)."
 )
 _IN_PLACE_KEYWORDS = (
     "new dataset create make in place edits given view working view source untouched"
@@ -1244,6 +1244,10 @@ def runnable_example(
     # the manifest carries the safe ``creds.json`` invocation instead.
     if record["command_id"] == "auth.login":
         return None
+    if record["command_id"] == "view.data.get":
+        # VIEW_ID then DATASET_ID: two different placeholders so a reader can
+        # tell which is which (the generic fallback printed "123 123").
+        return "mammoth view data get 123 456"
     if record["command_id"] == "ai.retention.condition":
         return shlex.join(
             [

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/commands/view.py

@@ -35,6 +35,7 @@ from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENTS,
     CODE_MISSING_ARGUMENT,
     CODE_MISSING_FIELD,
+    CODE_RESOURCE_NOT_FOUND,
     CODE_SDK_SYMBOL_UNRESOLVED,
     CODE_UNSUPPORTED_CONTRACT,
     EXIT_USAGE,
@@ -1227,7 +1228,13 @@ def view_data_get(invocation: Invocation) -> HandlerResult:
     limit = document.get("limit", _DATA_GET_DEFAULT_LIMIT)
     with open_service(invocation) as (service, auth):
         dataset_id = _resolve_dataset_id(service, invocation, view_id, document)
-        meta = _read_meta(service, invocation, auth.workspace_id, dataset_id, view_id, project_id)
+        try:
+            meta = _read_meta(
+                service, invocation, auth.workspace_id, dataset_id, view_id, project_id
+            )
+        except CliError as exc:
+            _explain_swapped_ids(service, exc, view_id, dataset_id)
+            raise
         kwargs: dict[str, Any] = {
             "dataset_id": dataset_id,
             "dataview_id": view_id,
@@ -1247,7 +1254,51 @@ def view_data_get(invocation: Invocation) -> HandlerResult:
             service, dataset_id, view_id, project_id, data, whole_view=whole_view
         )
     page_size = _DATA_PAGE_ROWS if whole_view else kwargs["limit"]
-    return _trim_rows(data, limit, page_size), meta
+    data = _trim_rows(data, limit, page_size)
+    if document.get("sequence") is None:
+        # The view's row count is its latest step's; a read at an earlier step differs.
+        data = _with_paging_total(data, meta)
+    return data, meta
+
+
+def _with_paging_total(data: Any, meta: dict[str, Any]) -> Any:
+    """Fill ``paging.total`` with the view's row count; the query route reports 0."""
+    paging = data.get("paging") if isinstance(data, dict) else None
+    row_count = meta["view"].get("row_count")
+    if (
+        isinstance(paging, dict)
+        and isinstance(row_count, int)
+        and row_count > paging.get("total", 0)
+    ):
+        return {**data, "paging": {**paging, "total": row_count}}
+    return data
+
+
+def _explain_swapped_ids(service: Any, error: CliError, view_id: int, dataset_id: int) -> None:
+    """Raise a clear refusal when a not-found read was given DATASET_ID then VIEW_ID.
+
+    The arguments are ``VIEW_ID [DATASET_ID]``; passing them the other way round
+    only produces a bare 404. If the first number is really a view of the second,
+    say so. Any other outcome leaves the original error to be re-raised.
+    """
+    if error.code != CODE_RESOURCE_NOT_FOUND:
+        return
+    try:
+        parent = int(service.call(_FIND_DATASET_SYMBOL, dataview_id=dataset_id))
+    except CliError:
+        return
+    if parent != view_id:
+        return
+    raise CliError(
+        code=CODE_INVALID_ARGUMENT,
+        message=(
+            f"{view_id} is a dataset id and {dataset_id} is its view; "
+            "the order is VIEW_ID DATASET_ID"
+        ),
+        exit_status=EXIT_USAGE,
+        hint=f"Run it again as: mammoth view data get {dataset_id} {view_id}",
+        details={"view_id": dataset_id, "dataset_id": view_id},
+    ) from error
 
 
 _QUERY_DATA_SYMBOL = "mammoth.api.dataviews.DataviewsAPI.query_data"

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/context/resolver.py

@@ -3,8 +3,8 @@
 Authentication requires a login. Credentials come from an explicit secure
 input to the current command (a prompt or a permission-checked ``--input``
 file), or from the selected or ``--profile`` profile's saved credentials.
-There is no environment-variable credential path: ``mammoth auth login`` is the
-only way to establish credentials. The API endpoint falls back to the ``app``
+For CI, an ``mm_...`` token in ``MAMMOTH_API_TOKEN`` (server prefix in
+``MAMMOTH_SERVER_PREFIX``) is used instead of a profile. The API endpoint falls back to the ``app``
 default when a profile supplies no server prefix. Project context resolves
 separately: ``--project`` overrides the saved profile project id, which
 overrides no project at all.
@@ -12,6 +12,8 @@ overrides no project at all.
 
 from __future__ import annotations
 
+import os
+import sys
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 
@@ -158,6 +160,20 @@ def _endpoint(server_prefix: str | None) -> str:
     return resolve_base_url(server_prefix)
 
 
+#: Environment variables a CI job sets instead of running ``mammoth auth login``.
+API_TOKEN_ENV = "MAMMOTH_API_TOKEN"  # noqa: S105 -- the variable name, not a secret
+SERVER_PREFIX_ENV = "MAMMOTH_SERVER_PREFIX"
+
+
+def _env_token_login() -> ExplicitLogin | None:
+    """The ``mm_...`` token in ``MAMMOTH_API_TOKEN`` as a login, or None when unset."""
+    token = os.environ.get(API_TOKEN_ENV, "").strip()
+    if not token:
+        return None
+    prefix = os.environ.get(SERVER_PREFIX_ENV, "").strip() or None
+    return ExplicitLogin(api_key=None, api_secret=None, server_prefix=prefix, api_token=token)
+
+
 def resolve_auth(
     invocation: Invocation,
     explicit_login: ExplicitLogin | None = None,
@@ -167,8 +183,9 @@ def resolve_auth(
     Credentials come from an explicit login (a secure prompt or ``--input``
     document handed to :func:`resolve_auth` by ``auth login``, or the login of
     the current embedded call, :mod:`mammoth_cli.runtime.embedded`), otherwise from
-    the selected or ``--profile`` saved profile. There is no environment
-    credential path; ``mammoth auth login`` is the only way to authenticate.
+    the selected or ``--profile`` saved profile. A ``MAMMOTH_API_TOKEN`` (and optional
+    ``MAMMOTH_SERVER_PREFIX``) in the environment outranks the selected profile, for CI,
+    but never an explicit ``--profile``; using it prints one stderr line.
 
     Args:
         invocation: The current command's resolved global options.
@@ -184,8 +201,15 @@ def resolve_auth(
     """
     if explicit_login is None and (call := embedded.current()) is not None:
         explicit_login = call.login
+    from_env = False
+    if explicit_login is None and (invocation.profile is None or invocation.profile_is_default):
+        # An explicit ``--profile`` outranks the ambient environment token.
+        explicit_login = _env_token_login()
+        from_env = explicit_login is not None
     if explicit_login is not None:
         base_url = _endpoint(explicit_login.server_prefix)
+        if from_env:
+            print(f"Using {API_TOKEN_ENV} for {base_url}", file=sys.stderr)
         return ResolvedAuth(
             api_key=explicit_login.api_key,
             api_secret=explicit_login.api_secret,

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/errors/envelope.py

@@ -66,19 +66,19 @@ CODE_EMPTIES_VIEW = "empties_view"
 # ``message``/``hint``. Plain language only: no command names, ids, field names
 # or jargon. Exactly one entry per error code the CLI can raise;
 # ``tests/unit/test_error_summaries.py`` fails if a raised code has none.
-_S_BAD_REQUEST = "The assistant's request wasn't valid, so it is trying a different way."
+_S_BAD_REQUEST = "The request wasn't valid."
 _S_BAD_INPUT = "Some of the information provided couldn't be used."
-_S_SIGN_IN = "The assistant isn't signed in to Mammoth."
-_S_INTERNAL = "The assistant hit an internal problem with this step."
-_S_NOT_FOUND = "Something the assistant looked for couldn't be found."
-_S_MISSING_INFO = "The assistant's request was missing some information."
+_S_SIGN_IN = "You aren't signed in to Mammoth."
+_S_INTERNAL = "This step hit an internal problem."
+_S_NOT_FOUND = "Something that was looked for couldn't be found."
+_S_MISSING_INFO = "The request was missing some information."
 _S_SETUP = "A setting needed for this step isn't set up correctly."
 _S_UNAVAILABLE = "This step isn't available right now."
 
 ERROR_SUMMARIES: dict[str, str] = {
     "aborted": "This step was stopped before it finished.",
     "ambiguous_resource_identity": (
-        "More than one item matched, so the assistant needs to be more specific."
+        "More than one item matched, so the request needs to be more specific."
     ),
     "api_error": "Mammoth couldn't complete this step.",
     "append_leaves_columns_blank": (
@@ -90,8 +90,8 @@ ERROR_SUMMARIES: dict[str, str] = {
     "append_schema_unreadable": "The columns of the existing data couldn't be read.",
     "authentication_failed": "Mammoth didn't accept the sign-in for this step.",
     "authorization_required": "You don't have permission to do this.",
-    "capability_not_found": "The assistant tried something Mammoth doesn't support.",
-    "cli_key_expired": "The saved API key has expired, so the assistant needs to sign in again.",
+    "capability_not_found": "That isn't something Mammoth supports.",
+    "cli_key_expired": "The saved API key has expired, so a new sign-in is needed.",
     "cli_keys_need_browser_sign_in": "Managing API keys needs a browser sign-in, not an API token.",
     "cli_keys_not_allowed": "This server doesn't let a browser sign-in create API keys.",
     "confirmation_declined": "This step was not confirmed, so nothing was changed.",
@@ -102,7 +102,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "conflict": "This conflicts with the current state of your data, so nothing was changed.",
     "device_login_expired": "The sign-in code expired before it was approved.",
     "dry_run_targets_unresolvable": (
-        "The assistant couldn't tell exactly which items this would change, so nothing was changed."
+        "It wasn't clear exactly which items this would change, so nothing was changed."
     ),
     "download_failed": "A download didn't complete.",
     "dry_run_unsupported": "That command can't be previewed, so it was not run.",
@@ -119,7 +119,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "input_unreadable": _S_BAD_INPUT,
     "insecure_credential_file": _S_SETUP,
     "insecure_input_file": _S_BAD_INPUT,
-    "intent_only_dashboards": "The assistant builds dashboards from your request only.",
+    "intent_only_dashboards": "Dashboards are built from the request only.",
     "internal_column_name": "That column is internal to Mammoth and can't be used.",
     "internal_error": _S_INTERNAL,
     "interrupted": "This step was interrupted before it finished.",
@@ -169,7 +169,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "no_saved_project": "This step can't save a project here; each step names its own.",
     "not_available_embedded": "This step isn't available inside the Mammoth app.",
     "not_available": _S_UNAVAILABLE,
-    "user_control": "Stopping, pausing or extending a run is left to you, not the assistant.",
+    "user_control": "Stopping, pausing or extending a run is left to you, not done automatically.",
     "profile_write_failed": _S_SETUP,
     "project_required": "No project has been chosen for this step.",
     "pypi_response_invalid": "An update check didn't return a usable answer.",
@@ -177,7 +177,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "replace_table_not_acknowledged": (
         "This export would drop and recreate a database table, and needs an explicit yes."
     ),
-    "resource_identity_required": "The assistant needs to say which item it means.",
+    "resource_identity_required": "The request needs to say which item it means.",
     "resource_not_found": _S_NOT_FOUND,
     "retryable_error": "Mammoth was temporarily unavailable. Trying again may work.",
     "schema_not_found": _S_NOT_FOUND,
@@ -190,7 +190,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "too_many_ids": _S_BAD_REQUEST,
     "unexpected_argument": _S_BAD_REQUEST,
     "unknown_agent": _S_SETUP,
-    "unknown_column": "A column the assistant referred to doesn't exist.",
+    "unknown_column": "A column that was referred to doesn't exist.",
     "unknown_config_key": _S_SETUP,
     "unknown_input_field": _S_BAD_REQUEST,
     "unknown_option": _S_BAD_REQUEST,

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/runtime/invocation.py

@@ -49,6 +49,9 @@ class Invocation:
     command_id: str
     output: str = "table"
     profile: str | None = None
+    # True when ``profile`` is the saved selection filled in for a command that
+    # named none, rather than a ``--profile`` / ``MAMMOTH_PROFILE`` the user gave.
+    profile_is_default: bool = field(default=False, repr=False, compare=False)
     project: int | None = None
     session: str | None = None
     timeout: float | None = None

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/runtime/state.py

@@ -224,6 +224,7 @@ def _read_invocation(command_id: str, resolved_ids: dict[str, Any], base: Invoca
         command_id=command_id,
         output="json",
         profile=base.profile,
+        profile_is_default=base.profile_is_default,
         project=base.project,
         timeout=base.timeout,
         job_timeout=base.job_timeout,

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/services/sdk_service.py

@@ -26,6 +26,7 @@ from typing import Any, NoReturn
 
 from mammoth.exceptions import MammothAPIError, MammothColumnError
 
+from mammoth_cli import __version__
 from mammoth_cli.context.resolver import ResolvedAuth
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENTS,
@@ -190,6 +191,7 @@ class SdkMammothService:
         self._client = MammothClient(
             **credential,
             base_url=auth.base_url,
+            user_agent=f"mammoth-cli/{__version__}",
             **kwargs,
         )
         # One loop for the process, not one per call: the client's connection

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/mammoth_cli/skills/steering.py

@@ -30,9 +30,10 @@ Transform-menu task is a `mammoth view transform` command (`mammoth view
 transform --help`). Before the first Mammoth command in a session run
 `mammoth doctor` (it must pass), then `mammoth skill show` and follow that
 guide. If `mammoth` is missing, install it with `pip install mammoth-cli`
-(or `uv tool install mammoth-cli`). If `mammoth auth status` shows no
-credentials, tell the operator the exact `mammoth auth login` command to run
-in their own terminal and wait; never ask for, read, or pass a key or secret.
+(or `uv tool install mammoth-cli`, then `uv tool update-shell` so it is on
+PATH). If `mammoth auth status` shows no credentials, tell the operator the
+exact `mammoth auth login` command to run in their own terminal
+and wait; never ask for, read, or pass a key or secret.
 Piped output is compact JSON. Take ids only from reads; run `mammoth schema get
 COMMAND_ID` before a command you have not used (`schema get A,B,C` reads
 several in one call); destructive commands need

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.73"
+version = "2.2.74"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.8.33,<0.9)",
+    "mammoth-io (>=0.8.38,<0.9)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",
@@ -17,7 +17,7 @@ dependencies = [
     "pydantic (>=2.12.5,<3)",
     "jsonschema (>=4.20)",
 ]
-urls = {homepage = "https://mammoth.io", repository = "https://github.com/EdgeMetric/mammothsdk"}
+urls = {homepage = "https://mammoth.io", repository = "https://github.com/EdgeMetric/mammothsdk", documentation = "https://docs.mammoth.io/build/cli"}
 scripts.mammoth = "mammoth_cli.__main__:main"
 classifiers = [
     "Development Status :: 5 - Production/Stable",

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/spec/manifests/commands/project.yaml

@@ -265,7 +265,7 @@ commands:
   readback:
     command: project.get
     ids:
-      project_id: result.id
+      project_id: result.project_id
     kind: object
 - command_id: project.data-check.list
   command_path: project data-check list

{mammoth_cli-2.2.73 → mammoth_cli-2.2.74}/spec/manifests/commands/view.yaml

@@ -1168,7 +1168,7 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth view data get VIEW_ID --help
-  agent_example: mammoth view data get 123 123
+  agent_example: mammoth view data get 123 456
   unit_tests:
   - UT-VIEW-DATA-GET
   contract_tests: