mammoth-cli 2.0.24__tar.gz → 2.0.26__tar.gz

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.24
+Version: 2.0.26
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,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.8,>=0.7.11
+Requires-Dist: mammoth-io<0.8,>=0.7.12
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.13
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/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.0.24"
+__version__ = "2.0.26"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.24
+version: 2.0.26
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines, dashboards, exports, and handoffs."
 ---
 

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities-misc.md

@@ -140,4 +140,4 @@ Ran once: `workflow.create`, `workflow.delete`, `workflow.get`, `workflow.graph`
 
 Ran once: `workspace.app-usage`, `workspace.get`, `workspace.list`, `workspace.segment.list`, `workspace.segment.update`, `workspace.storage-breakdown`, `workspace.user.list`
 
-Evidence collected on CLI releases 1.1.5 through 2.0.21; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.
+Evidence collected on CLI releases 1.1.5 through 2.0.24; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-The CLI publishes 552 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (every `view transform *` command submits through `view.task.add`). 260 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
+The CLI publishes 552 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (every `view transform *` command submits through `view.task.add`). 261 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
 
 Status meanings:
 
@@ -18,7 +18,7 @@ The typed `view transform *` commands all submit through `view.task.add`; its ma
 | Family | Commands | Ran once | Not supported | Untried |
 |---|---|---|---|---|
 | `dashboard` | 104 | 81 | 2 | 21 |
-| `view` | 62 | 56 | 0 | 6 |
+| `view` | 62 | 57 | 0 | 5 |
 | `support` | 45 | 9 | 0 | 36 |
 | `billing` | 23 | 4 | 0 | 19 |
 | `connector` | 22 | 3 | 0 | 19 |
@@ -110,14 +110,13 @@ Ran once: `project.bulk-delete`, `project.bulk-update`, `project.checkpoint.list
 
 ## `view`
 
-Ran once: `view.active-user.list`, `view.active-user.mark`, `view.ai.generate-data`, `view.ai.profile`, `view.bulk-delete`, `view.checkpoint.create`, `view.checkpoint.delete`, `view.checkpoint.get`, `view.checkpoint.list`, `view.checkpoint.update`, `view.conditional-format.create`, `view.conditional-format.delete-all`, `view.conditional-format.list`, `view.conditional-format.update`, `view.create`, `view.data-check.create`, `view.data-check.delete`, `view.data-check.get`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.delete`, `view.derivative.create`, `view.derivative.delete`, `view.derivative.list`, `view.derivative.update`, `view.draft.command`, `view.export.delete`, `view.export.get`, `view.export.list`, `view.export.publish-db`, `view.export.update`, `view.exportable-config.apply`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.edit`, `view.pipeline.get`, `view.pipeline.items`, `view.pipeline.rerun`, `view.preview`, `view.restore`, `view.task.add`, `view.task.delete`, `view.task.get`, `view.task.list`, `view.task.preview`, `view.task.update`, `view.trash`, `view.version.apply`, `view.version.delete`, `view.version.get`, `view.version.list`, `view.version.update`
+Ran once: `view.active-user.list`, `view.active-user.mark`, `view.ai.generate-data`, `view.ai.profile`, `view.bulk-delete`, `view.checkpoint.create`, `view.checkpoint.delete`, `view.checkpoint.get`, `view.checkpoint.list`, `view.checkpoint.update`, `view.conditional-format.create`, `view.conditional-format.delete-all`, `view.conditional-format.list`, `view.conditional-format.update`, `view.create`, `view.data-check.create`, `view.data-check.delete`, `view.data-check.get`, `view.data-check.list`, `view.data.get`, `view.data.query`, `view.delete`, `view.derivative.create`, `view.derivative.data`, `view.derivative.delete`, `view.derivative.list`, `view.derivative.update`, `view.draft.command`, `view.export.delete`, `view.export.get`, `view.export.list`, `view.export.publish-db`, `view.export.update`, `view.exportable-config.apply`, `view.exportable-config.get`, `view.get`, `view.list`, `view.parameter-context`, `view.pipeline.edit`, `view.pipeline.get`, `view.pipeline.items`, `view.pipeline.rerun`, `view.preview`, `view.restore`, `view.task.add`, `view.task.delete`, `view.task.get`, `view.task.list`, `view.task.preview`, `view.task.update`, `view.trash`, `view.version.apply`, `view.version.delete`, `view.version.get`, `view.version.list`, `view.version.update`
 
 | Command | State | Note |
 |---|---|---|
 | `view.ai.generation-info` | observed blocker | backend: GET /workspaces/4/projects/24/datasets/54/dataviews/76/data/generate -> HTTP 400 5GENR011 NOT_IMPLEMENTED 'Not implemented', request_id:null |
 | `view.data-check.update` | observed blocker | backend_error: PATCH with the schema's documented {op: command, path: enable/disable, value: null} shape returns HTTP 500 empty body (CLI outcome_unknown, exit 7) while the mutatio |
-| `view.derivative.data` | observed blocker | backend_error: SUSPECTED DEFECT: using the CLI's own documented agent_example body verbatim, derivative data fetch returns HTTP 500 empty body / outcome_unknown, reproduced twice ( |
 | `view.export.create` | observed blocker | backend: CLI accepts the request (exit 0, job 358 accepted on POST /dataviews/76/actions), but job get 358 -> status:error, response:{"error":{"message":"'destination'"}} (a raw Py |
 | `view.export.publish-db-update` | CLI defect fixed, untried since | 2.0.16 (example value is the documented {"odbc_type": "postgres"} object (a bare string is rejected)) |
 
-Evidence collected on CLI releases 1.1.5 through 2.0.21; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.
+Evidence collected on CLI releases 1.1.5 through 2.0.24; each row's release is recorded in `docs/release-capability-matrix.json` (`evidence_version`). A row that ran on an older release has not been re-run since unless its note says so. Details: `docs/capability-evidence/` in the repository.

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -246,21 +246,21 @@ Status on release: ran once on CLI 2.0.18 — golden-data check 2026-09-19: exit
 
 Run: `mammoth view derivative create`. Exact input fields: `mammoth schema get view.derivative.create`.
 
-Example: `mammoth view derivative create 123 123 --input '{"body": {"param": {"METRIC": {"AS": "sample", "EXPRESSION": [{"TYPE": "FUNCTION", "VALUE": {"ARGUMENT": "sample", "FUNCTION": "SUM"}}]}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth view derivative create 123 123 --input '{"body": {"param": {"METRIC": {"AS": "total", "EXPRESSION": [{"TYPE": "FUNCTION", "VALUE": {"ARGUMENT": "column_1", "FUNCTION": "SUM"}}]}}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `ViewDerivativeCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 
-Status on release: ran once on CLI 2.0.21 — Partial bounded evidence only (earlier run); ergonomics sweep 2026-09-19 (CLI 2.0.21) observed backend_error: POST .../derivatives with the example shape (METRIC object) returns HTTP 500 empty body / outcome_unknown on release today. A list under METRIC is re…
+Status on release: ran once on CLI 2.0.24 — payload probe 2026-09-19: exit 0 on release with CLI 2.0.24. Created derivative id=6 on view 123 (project 52, dataset 104) with the column INTERNAL name as ARGUMENT; metric_status DONE on read-back. The same call with the display name reproduces the HTTP 500…
 
 ### `view.derivative.data`
 
 Run: `mammoth view derivative data`. Exact input fields: `mammoth schema get view.derivative.data`.
 
-Example: `mammoth view derivative data 123 123 123 --input '{"body": {"condition": {"FILTER_TYPE": "SHOW"}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth view derivative data 123 123 123 --input '{"body": {"limit": null}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `ViewDerivativeDataResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 
-Status on release: observed blocker — backend_error: SUSPECTED DEFECT: using the CLI's own documented agent_example body verbatim, derivative data fetch returns HTTP 500 empty body / outcome_unknown, reproduced twice (. Re-check before relying on it.
+Status on release: ran once on CLI 2.0.24 — payload probe 2026-09-19: exit 0 on release with CLI 2.0.24. STATUS READY, data [{RESULT: 60.0}], metadata total/RESULT/NUMERIC, row_count 1. {"condition": null, "limit": null} (the web app's body) also works; {} is 4GENR007. Example corrected in 2.0.25. Sing…
 
 ### `view.derivative.delete`
 

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/transforms.md

@@ -89,6 +89,15 @@ but the copy answers every read with `4DTVW019` and its copied tasks never
 execute. A plain `view create DATASET_ID` (no `clone_from`) gives a fresh view
 of the raw upload, without the pipeline:
 
+A task must fit the column's type: `replace-values`, `bulk-replace` and the
+text operations take TEXT columns, `math` takes NUMERIC. Check `type` in the
+`metadata` from `view get` first; the uploader already types `$1,234.56` as
+NUMERIC, so strip nothing. When a task does not fit, the CLI answers
+`pipeline_reference_error` with the column, the reason and the exact
+`view task delete VIEW_ID TASK_ID --yes` that removes it; until then the view
+is in `ref_error` and every read of it fails with `4DTVW019`. `convert-type`
+changes the column's type when the task really needs the other one.
+
 Every pivot `as_name` must be a display name that does not already exist on
 the view (`4DTVW018 Same display name cannot be reused`): to carry a joined
 column such as `monthly_target` into the summary, aggregate it under a new

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/bundled_skill/mammoth-cli/references/recovery.md

@@ -27,6 +27,7 @@ these commands are not blanket permission to replay a mutation.
 | `invalid_condition` (exit 2, `details.accepted` lists operators) | operator not in the accepted set (symbols `=`, `>` are accepted as aliases of EQ/GT; words like `GREATER` are not) | use an operator from references/input.md |
 | `resource_not_found` (exit 5) after `view get VIEW_ID` / `view data get VIEW_ID` without a parent | discovery could not find the view in the selected project | pass `--project PROJECT_ID` and the `DATASET_ID` positional from `view list` |
 | `{"data": "<unserializable View>"}` from `view get VIEW_ID` | CLI ≤ 2.0.17 only; fixed in 2.0.18 | upgrade, or rerun as `view get VIEW_ID DATASET_ID` |
+| `pipeline_reference_error` (exit 1) from a transform or `view task add`, `details.reference_errors[].reason` `type mismatch` / `not available` | the backend stored the task but cannot bind it to that column (find/replace and text operations take TEXT columns, math takes NUMERIC); the view is in `ref_error` and every read of it fails with `4DTVW019` until the task goes | run the printed `view task delete VIEW_ID TASK_ID --yes`, then convert-type the column or pick a transform for its type; CLI ≤ 2.0.24 reported this as success with `has_error: true` |
 | `4DTVW019 INVALID_RESPONSE_GENERATED` on every read of a view made with `view create ... "clone_from"` | backend: the clone is never processed (tasks stay `added`) | delete the copy; export the source view's rows, then run the summary in place as the last step; see recipes/end-to-end.md |
 | `status: ready` with `status_info.ready` "more than one plausible way to be read" and `view list` empty | all-text CSV; the platform did not process it | `file upload` (2.0.18) reports this as `need_action`; see recipes/need-action.md |
 | `need_action` in `file upload` result | the platform needs a parsing decision (e.g. ambiguous dates) | run the `next_command` it returns (`dataset file-settings get ID`), then `dataset file-settings update ID`; see recipes/need-action.md |

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/commands/schema.py

@@ -70,6 +70,17 @@ _COMMAND_DISCOVERY_PURPOSES = {
     "view.transform.convert-type": "convert type cast numeric text date column",
     "view.transform.fill-missing": "fill missing null empty impute carry forward values",
     "view.transform.join": "join blend lookup merge matching keys rows",
+    "view.transform.extract-date": (
+        "extract date part year month day hour minute second week quarter weekday "
+        "month_text into a new column"
+    ),
+    "view.transform.date-diff": "date difference days between two date columns age duration",
+    "view.transform.increment-date": "add subtract days months years to a date column shift",
+    "view.transform.math": "math arithmetic multiply divide add subtract formula expression amount",
+    "view.transform.pivot": "pivot group by aggregate sum count summary per region total",
+    "view.transform.set-values": "set values assign overwrite blank empty default where condition",
+    "view.transform.text": "text case upper lower title trim whitespace normalise",
+    "view.transform.bulk-replace": "find replace strip characters text values mapping",
 }
 
 # A compact string scope is retained for existing discovery consumers.  These
@@ -268,8 +279,18 @@ def _humanize_sample(value: Any, field_name: str) -> Any:
 
 
 def _tokens(value: str) -> frozenset[str]:
-    """Tokenize search text consistently across platforms and Python runs."""
-    return frozenset(_TOKEN_RE.findall(value.casefold()))
+    """Tokenize search text consistently across platforms and Python runs.
+
+    A hyphenated word is kept whole and also split into its parts, so that
+    ``date`` finds ``extract-date`` and ``date-diff`` as well as ``convert-type``'s
+    example text.
+    """
+    tokens: set[str] = set()
+    for token in _TOKEN_RE.findall(value.casefold()):
+        tokens.add(token)
+        if "-" in token:
+            tokens.update(token.split("-"))
+    return frozenset(tokens)
 
 
 def _query_tokens(query: str) -> tuple[str, ...]:

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/commands/upgrade.py

@@ -19,6 +19,7 @@ real subprocess.
 from __future__ import annotations
 
 import json
+import os
 import shutil
 import subprocess
 import sys
@@ -54,37 +55,50 @@ ACTION_ALREADY_CURRENT = "already_current"
 ACTION_WOULD_UPGRADE = "would_upgrade"
 
 
-def _uv_tool_lists_package() -> bool:
-    """Whether ``uv tool list`` reports this package as a uv-managed tool.
+def _tool_root(argv: list[str]) -> str | None:
+    """Return the directory a tool manager keeps its venvs in, or None.
 
-    Returns False (rather than raising) when ``uv`` is absent or the listing
-    fails, so detection can fall through to the next manager.
+    ``uv tool dir`` / ``pipx environment --value PIPX_LOCAL_VENVS`` answer
+    with one path. Returns None (rather than raising) when the manager is
+    absent or the query fails, so detection can fall through.
     """
-    uv = shutil.which("uv")
-    if not uv:
-        return False
+    binary = shutil.which(argv[0])
+    if not binary:
+        return None
     try:
-        result = subprocess.run(  # noqa: S603 - fixed argv, no shell, trusted uv path
-            [uv, "tool", "list"],
+        result = subprocess.run(  # noqa: S603 - fixed argv, no shell, trusted path
+            [binary, *argv[1:]],
             capture_output=True,
             text=True,
             timeout=30,
             check=False,
         )
     except (OSError, subprocess.SubprocessError):
-        return False
+        return None
     if result.returncode != 0:
+        return None
+    root = result.stdout.strip().splitlines()
+    return root[0].strip() if root else None
+
+
+def _runs_under(root: str | None) -> bool:
+    """Whether the running interpreter's environment lives under ``root``."""
+    if not root:
         return False
-    return PACKAGE_NAME in result.stdout
+    prefix = os.path.realpath(sys.prefix)
+    return prefix.startswith(os.path.realpath(root).rstrip("/\\") + os.sep)
 
 
 def detect_manager() -> str:
     """Detect which tool manages this CLI install.
 
-    Detection order is ``uv tool`` (the running executable lives under a uv
-    tools directory, or ``uv tool list`` reports the package), then ``pipx``
-    (the executable lives under a pipx venvs directory), then a ``pip``
-    fallback.
+    The decision is about the *running* environment, never about what else
+    is installed on the machine: a plain venv on a host that also has a
+    ``uv tool`` install must be upgraded with pip in that venv, or the
+    upgrade lands somewhere else and the caller keeps the old version.
+    Detection order is ``uv tool`` (``sys.executable`` under a uv tools
+    directory, or ``sys.prefix`` under ``uv tool dir``), then ``pipx`` (the
+    same for its venvs directory), then the ``pip`` of the running interpreter.
 
     Returns:
         One of :data:`MANAGER_UV`, :data:`MANAGER_PIPX`, or :data:`MANAGER_PIP`.
@@ -94,8 +108,13 @@ def detect_manager() -> str:
         return MANAGER_UV
     if "/pipx/venvs/" in location or "/pipx/venv/" in location:
         return MANAGER_PIPX
-    if _uv_tool_lists_package():
-        return MANAGER_UV
+    if sys.prefix != sys.base_prefix:
+        # Inside some virtual environment: only a manager that owns *this*
+        # environment may upgrade it.
+        if _runs_under(_tool_root(["uv", "tool", "dir"])):
+            return MANAGER_UV
+        if _runs_under(_tool_root(["pipx", "environment", "--value", "PIPX_LOCAL_VENVS"])):
+            return MANAGER_PIPX
     return MANAGER_PIP
 
 

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/commands/view.py

@@ -1447,6 +1447,10 @@ def view_task_add(invocation: Invocation) -> HandlerResult:
     _forward_optional(document, kwargs, ("dataset_id",))
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
+        # Imported here: view_ops imports this module for the brief record helpers.
+        from mammoth_cli.commands.view_ops import reject_pipeline_reference_errors
+
+        reject_pipeline_reference_errors(service, dataview_id, kwargs.get("dataset_id"), data)
     return data, _meta(invocation, auth.workspace_id, None)
 
 

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/commands/view_ops.py

@@ -32,6 +32,7 @@ from mammoth_cli.errors.envelope import (
     CODE_MISSING_ARGUMENT,
     CODE_MISSING_FIELD,
     CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_API,
     EXIT_USAGE,
     CliError,
 )
@@ -45,6 +46,20 @@ from mammoth_cli.services.conditions import CONDITION_KWARG
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
+#: Error code for a task the backend accepted but could not bind to the view.
+CODE_PIPELINE_REFERENCE_ERROR = "pipeline_reference_error"
+_PIPELINE_SYMBOL = "mammoth.api.pipeline.PipelineAPI.get_pipeline"
+_PIPELINE_ITEMS_SYMBOL = "mammoth.api.pipeline.PipelineAPI.items"
+_PIPELINE_ITEMS_FULL = "__full"
+_REFERROR_REASON_HINTS = {
+    "type mismatch": (
+        "the task needs a different column type (find/replace and text operations "
+        "take TEXT columns, math takes NUMERIC); convert-type the column first or "
+        "use a transform for that type"
+    ),
+    "not available": "the column does not exist in the view at that point in the pipeline",
+}
+
 
 def _symbol(invocation: Invocation) -> str:
     """Return the reviewed backing SDK symbol for this command."""
@@ -236,14 +251,106 @@ def _dispatch_view(
     with open_service(invocation) as (service, auth):
         if dataset_id is None:
             dataset_id = parents.lookup(_profile_name(invocation), auth.workspace_id, view_id)
-        if dataset_id is None:
-            _require_discovery_allowed(invocation, view_id)
-            data = service.call_view(view_id, method, **kwargs)
-        else:
-            data = service.call_view(view_id, method, dataset_id=int(dataset_id), **kwargs)
+        try:
+            if dataset_id is None:
+                _require_discovery_allowed(invocation, view_id)
+                data = service.call_view(view_id, method, **kwargs)
+            else:
+                data = service.call_view(view_id, method, dataset_id=int(dataset_id), **kwargs)
+        except CliError as exc:
+            # SDK >= 0.7.12 raises on the same job result; enrich it the same way.
+            response = exc.details.get("response") if isinstance(exc.details, dict) else None
+            reject_pipeline_reference_errors(service, view_id, dataset_id, response)
+            raise
+        reject_pipeline_reference_errors(service, view_id, dataset_id, data)
     return data, _meta(invocation, auth.workspace_id)
 
 
+def _compact_reference_error(entry: Any) -> dict[str, Any]:
+    if not isinstance(entry, dict):
+        return {"reason": str(entry)}
+    raw_column = entry.get("column")
+    column: dict[str, Any] = raw_column if isinstance(raw_column, dict) else {}
+    return {
+        "column": column.get("display_name"),
+        "internal_name": column.get("internal_name"),
+        "type": column.get("type"),
+        "reason": entry.get("reason"),
+        "error_code": entry.get("error_code"),
+    }
+
+
+def reject_pipeline_reference_errors(
+    service: Any, view_id: int, dataset_id: Any, data: Any
+) -> None:
+    """Fail a pipeline mutation whose task the backend accepted but could not bind.
+
+    A task that references a missing column or the wrong column type is stored
+    with ``reference_errors`` and answered with ``has_error: true``; the
+    pipeline then sits in ``ref_error`` and every read of the view fails with
+    4DTVW019 until the task is removed. The SDK reads the view's draft flag
+    after the submit, and the backend flips that flag on a reference error, so
+    the SDK returns the job result instead of raising. Turn that into one
+    envelope that names the column, the reason and the exact repair command.
+    """
+    if not (isinstance(data, dict) and data.get("has_error") is True):
+        return
+    kwargs: dict[str, Any] = {"dataview_id": view_id}
+    if dataset_id is not None:
+        kwargs["dataset_id"] = int(dataset_id)
+    pipeline: dict[str, Any] = {}
+    broken: list[dict[str, Any]] = []
+    try:
+        read = service.call(_PIPELINE_SYMBOL, **kwargs)
+        if isinstance(read, dict):
+            pipeline = read
+        items = service.call(_PIPELINE_ITEMS_SYMBOL, fields=_PIPELINE_ITEMS_FULL, **kwargs)
+        if isinstance(items, dict):
+            broken = [
+                item
+                for item in items.get("items") or []
+                if isinstance(item, dict) and item.get("reference_errors")
+            ]
+    except CliError:
+        # The mutation already failed; a failed follow-up read must not hide that.
+        pass
+    reference_errors = [
+        _compact_reference_error(entry)
+        for item in broken
+        for entry in (item.get("reference_errors") or {}).get("reference_errors") or []
+    ]
+    task_ids = [item.get("id") for item in broken if item.get("id") is not None]
+    first = reference_errors[0] if reference_errors else {}
+    reason = str(first.get("reason") or "").lower()
+    column = first.get("column")
+    what = f"column '{column}' ({first.get('type')})" if column else "a column it references"
+    why = _REFERROR_REASON_HINTS.get(reason, f"reason: {reason or 'unknown'}")
+    raise CliError(
+        code=CODE_PIPELINE_REFERENCE_ERROR,
+        message=(
+            f"The task was added to view {view_id} but cannot bind to {what}; "
+            "the pipeline is in ref_error and the data did not change."
+        ),
+        exit_status=EXIT_API,
+        hint=(
+            f"Reads of view {view_id} fail (4DTVW019) until the task is removed: "
+            f"run the recovery command, then fix the input ({why})."
+        ),
+        details={
+            "view_id": view_id,
+            "dataset_id": kwargs.get("dataset_id"),
+            "pipeline_state": pipeline.get("state"),
+            "task_ids": task_ids,
+            "reference_errors": reference_errors,
+            "response": data,
+        },
+        recovery_commands=[
+            f"mammoth view task delete {view_id} {task_id} --yes" for task_id in task_ids
+        ]
+        or [f'mammoth view pipeline items {view_id} --input \'{{"fields": "__full"}}\''],
+    )
+
+
 def _profile_name(invocation: Invocation) -> str:
     return invocation.profile or profiles.get_selected()
 

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/mammoth_cli/services/input_fields.py

@@ -269,6 +269,25 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     "view.data-check.update": {
         "body": {"patches": [{"op": "command", "path": "disable", "value": None}]},
     },
+    # ARGUMENT is the column's *internal* name (metadata[].internal_name from
+    # view get); a display name makes the backend fail with HTTP 500.
+    "view.derivative.create": {
+        "body": {
+            "param": {
+                "METRIC": {
+                    "AS": "total",
+                    "EXPRESSION": [
+                        {
+                            "TYPE": "FUNCTION",
+                            "VALUE": {"ARGUMENT": "column_1", "FUNCTION": "SUM"},
+                        }
+                    ],
+                }
+            }
+        },
+    },
+    # The web app posts {condition, limit: null}; an empty body is 4GENR007.
+    "view.derivative.data": {"body": {"limit": None}},
     # The backend accepts NUMERIC, TEXT or DATE (4PARM008 otherwise).
     "parameter.create": {"param_type": "TEXT", "value": "Q3"},
     # The backend requires a placement ("Data check position must be given");

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.24"
+version = "2.0.26"
 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.7.11,<0.8)",
+    "mammoth-io (>=0.7.12,<0.8)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/spec/manifests/commands/dashboard.yaml

@@ -3560,7 +3560,9 @@ commands:
   - CT-DASHBOARD-TEMPLATE-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'dashboard_id must name a dashboard whose widgets bind dataset columns; a blank dashboard
+    fails with "None of the columns this template binds are in the dataset". Build the dashboard first (dashboard
+    create, then widgets), then save it as a template.'
   reviewed_by: primary
 - command_id: dashboard.template.delete
   command_path: dashboard template delete

{mammoth_cli-2.0.24 → mammoth_cli-2.0.26}/spec/manifests/commands/view.yaml

@@ -993,7 +993,7 @@ commands:
   - CT-VIEW-DATA-CHECK-UPDATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'patches are {op: command, path: enable|disable, value: null} or {op: replace, path: spec, value: AddDataCheckSpec}. On release the PATCH returns HTTP 500 (outcome_unknown) after applying; read the check back with view data-check get.'
+  known_restrictions: 'patches are {op: command, path: enable|disable, value: null} or {op: replace, path: spec, value: AddDataCheckSpec}, the same body the web app sends. On release the PATCH returns HTTP 500 (outcome_unknown) from backend validation that runs after the change is committed; read the check back with view data-check get before retrying.'
   reviewed_by: primary
 - command_id: view.data.get
   command_path: view data get
@@ -1173,7 +1173,7 @@ commands:
   secret_fields: []
   human_example: mammoth view derivative create VIEW_ID --help
   agent_example: 'mammoth view derivative create 123 123 --input ''{"body": {"param": {"METRIC": {"AS":
-    "sample", "EXPRESSION": [{"TYPE": "FUNCTION", "VALUE": {"ARGUMENT": "sample", "FUNCTION": "SUM"}}]}}}}'''
+    "total", "EXPRESSION": [{"TYPE": "FUNCTION", "VALUE": {"ARGUMENT": "column_1", "FUNCTION": "SUM"}}]}}}}'''
   unit_tests:
   - UT-VIEW-DERIVATIVE-CREATE
   contract_tests:
@@ -1182,7 +1182,9 @@ commands:
   - CT-VIEW-DERIVATIVE-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'ARGUMENT and any column reference in the METRIC expression are internal names (metadata[].internal_name
+    from view get, e.g. column_1), not display names; a display name makes the backend fail with HTTP 500. The
+    result is {"id": N}; read the value with view derivative data.'
   reviewed_by: primary
 - command_id: view.derivative.data
   command_path: view derivative data
@@ -1226,8 +1228,7 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth view derivative data VIEW_ID DERIVATIVE_ID --help
-  agent_example: 'mammoth view derivative data 123 123 123 --input ''{"body": {"condition": {"FILTER_TYPE":
-    "SHOW"}}}'''
+  agent_example: 'mammoth view derivative data 123 123 123 --input ''{"body": {"limit": null}}'''
   unit_tests:
   - UT-VIEW-DERIVATIVE-DATA
   contract_tests:
@@ -1236,7 +1237,9 @@ commands:
   - CT-VIEW-DERIVATIVE-DATA-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: 'body is {"condition": CONDITION_OR_NULL, "limit": null}, the same document the web app posts;
+    {"limit": null} is the minimal accepted body and an empty body is rejected (4GENR007). Returns STATUS, the
+    metric row(s) under data and their metadata.'
   reviewed_by: primary
 - command_id: view.derivative.delete
   command_path: view derivative delete
@@ -3786,8 +3789,7 @@ commands:
   - CT-VIEW-TRANSFORM-BULK-REPLACE-ERROR
   draft_test: LT-VIEW-TRANSFORM-BULK-REPLACE-DRAFT
   undo_test: LT-VIEW-TRANSFORM-BULK-REPLACE-UNDO
-  known_restrictions: Complete flags/defaults/result/draft/undo/live contract is specified in plan 02's
-    'Complete bulk-replace command contract'; this appendix does not narrow or replace it.
+  known_restrictions: 'Complete flags/defaults/result/draft/undo/live contract is specified in plan 02''s ''Complete bulk-replace command contract''; this appendix does not narrow or replace it. columns must be TEXT (metadata[].type from view get): a NUMERIC or DATE column is stored with a type-mismatch reference error, the view enters ref_error and the CLI answers pipeline_reference_error with the view task delete that removes the task.'
   reviewed_by: primary
 - command_id: view.transform.combine-columns
   command_path: view transform combine-columns
@@ -4535,7 +4537,9 @@ commands:
   - CT-VIEW-TRANSFORM-PIVOT-ERROR
   draft_test: LT-VIEW-TRANSFORM-PIVOT-DRAFT
   undo_test: LT-VIEW-TRANSFORM-PIVOT-UNDO
-  known_restrictions: null
+  known_restrictions: 'Replaces the view''s columns with the summary, so run it last (export rows first). Every as_name
+    must be a display name that does not already exist on the view (4DTVW018 SAME_DISPLAY_NAME_CANNOT_BE_REUSED):
+    aggregate a joined column under a new name.'
   reviewed_by: primary
 - command_id: view.transform.replace
   command_path: view transform replace
@@ -4576,7 +4580,7 @@ commands:
   - CT-VIEW-TRANSFORM-REPLACE-ERROR
   draft_test: LT-VIEW-TRANSFORM-REPLACE-DRAFT
   undo_test: LT-VIEW-TRANSFORM-REPLACE-UNDO
-  known_restrictions: null
+  known_restrictions: 'columns must be TEXT (metadata[].type from view get): a NUMERIC or DATE column is stored with a type-mismatch reference error, the view enters ref_error and the CLI answers pipeline_reference_error with the view task delete that removes the task.'
   reviewed_by: primary
 - command_id: view.transform.set-values
   command_path: view transform set-values