mammoth-cli 2.0.23__tar.gz → 2.0.25__tar.gz

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.23
+Version: 2.0.25
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk

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

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.23
+version: 2.0.25
 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."
 ---
 
@@ -51,6 +51,10 @@ before the next step.
   family, `schema find WORDS` a search.
 - Uploads return a **dataset** id; transforms, joins, exports and previews
   take the **view** id from `view list DATASET_ID`.
+- `view list` and `view get` return the brief record (id, ds_id, name,
+  status, row_count, `metadata` columns and types, pipeline state);
+  `view get ... --input '{"fields": "__full"}'` or `view list ... --input
+  '{"full": true}'` returns the dependency and display trees too.
 - Column inputs and expressions use the exact **display names** the view
   returns, never backend aliases.
 - Destructive commands need `--yes --confirm ID`. Preserve requested

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/end-to-end.md

@@ -68,6 +68,8 @@ mammoth dataset list --project PROJECT_ID           # the id is gone
 mammoth project list                                # matches the baseline plus your deliverables
 # only if the task said the whole project was temporary:
 # mammoth project delete PROJECT_ID --yes --confirm PROJECT_ID
+#   202 means queued: project list can still show it for a while; project get
+#   returning resource_not_found is the proof, re-check rather than re-delete
 ```
 
 Then walk the [report checklist](../report-checklist.md). If any step

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/resources.md

@@ -56,10 +56,12 @@ through your context, so size costs nothing but time. Two boundaries hold:
   upload the parts, or compress it (a `.zip`/`.gz` of a CSV is accepted and
   expanded server-side).
 
-Scanning and parsing time grows with size; pass `--timeout 300` on anything
-past a few MB and, when the command returns `timeout` with a `job_handle`,
-poll with the `job get` recovery command it prints instead of uploading
-again. A bare HTTP 500 from this route (`outcome_unknown`, empty body) means
+Scanning and parsing time grows with size; the upload waits up to 300 s by
+default (`--job-timeout N` to change it) and, when the command returns
+`timeout` with a `job_handle`, poll with the `job get` recovery command it
+prints instead of uploading again: a second upload of the same file queues a
+second job behind the first, and one stuck scan job holds every later upload
+in the workspace (seen on release with jobs 667 and 708). A bare HTTP 500 from this route (`outcome_unknown`, empty body) means
 the upload service is degraded; check `job get` for a job first, do not
 retry in a loop.
 

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/mammoth_cli/commands/view.py

@@ -231,6 +231,34 @@ def _meta(invocation: Invocation, workspace_id: int, project_id: int | None) ->
 # ---------------------------------------------------------------------------
 
 
+#: What an agent reads a view for: identity, parent, columns and types, row
+#: count, and pipeline state. The record's ``dependencies_info`` and display
+#: trees are several times that size and rarely wanted; ``fields`` (``"__full"``,
+#: ``"__standard"`` or a list) returns them.
+BRIEF_VIEW_FIELDS: tuple[str, ...] = (
+    "id",
+    "ds_id",
+    "dataset_id",
+    "name",
+    "status",
+    "row_count",
+    "column_count",
+    "metadata",
+    "pipeline_status",
+    "is_pipeline_running",
+    "is_dataview_data_in_sync",
+    "data_updated_at",
+    "updated_at",
+)
+
+
+def brief_view_record(record: Any) -> Any:
+    """Keep only :data:`BRIEF_VIEW_FIELDS` of a dataview record."""
+    if not isinstance(record, dict):
+        return record
+    return {key: record[key] for key in BRIEF_VIEW_FIELDS if key in record}
+
+
 def view_list(invocation: Invocation) -> HandlerResult:
     """List dataviews for a dataset in the active project."""
     project_id = require_project(invocation)
@@ -243,6 +271,14 @@ def view_list(invocation: Invocation) -> HandlerResult:
         parents.remember_records(
             _profile_name(invocation), auth.workspace_id, data, project_id=project_id
         )
+    if (
+        isinstance(data, dict)
+        and isinstance(data.get("dataviews"), list)
+        and not document.get("full")
+    ):
+        # The list route has no field projection in the SDK; trim each record
+        # to the brief shape ``view get`` returns (``full: true`` keeps all).
+        data = {**data, "dataviews": [brief_view_record(item) for item in data["dataviews"]]}
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -1411,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.23 → mammoth_cli-2.0.25}/mammoth_cli/commands/view_ops.py

@@ -21,13 +21,18 @@ from __future__ import annotations
 
 from typing import Any
 
-from mammoth_cli.commands.view import _require_discovery_allowed
+from mammoth_cli.commands.view import (
+    BRIEF_VIEW_FIELDS,
+    _require_discovery_allowed,
+    brief_view_record,
+)
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import (
     CODE_INVALID_ARGUMENT,
     CODE_MISSING_ARGUMENT,
     CODE_MISSING_FIELD,
     CODE_SDK_SYMBOL_UNRESOLVED,
+    EXIT_API,
     EXIT_USAGE,
     CliError,
 )
@@ -41,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."""
@@ -237,9 +256,95 @@ def _dispatch_view(
             data = service.call_view(view_id, method, **kwargs)
         else:
             data = service.call_view(view_id, method, dataset_id=int(dataset_id), **kwargs)
+        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()
 
@@ -304,9 +409,13 @@ def view_get(invocation: Invocation) -> HandlerResult:
         # The release operation is dataset-scoped.  Bypass the rich-object
         # resolver when the caller supplied the exact parent so no discovery
         # probe can escape the requested project/dataset.
-        kwargs: dict[str, Any] = {"dataset_id": dataset_id, "dataview_id": view_id}
-        if "fields" in document:
-            kwargs["fields"] = document["fields"]
+        kwargs: dict[str, Any] = {
+            "dataset_id": dataset_id,
+            "dataview_id": view_id,
+            # Server-side projection; the brief set unless the caller asks.
+            "fields": document.get("fields")
+            or ",".join(key for key in BRIEF_VIEW_FIELDS if key != "dataset_id"),
+        }
         with open_service(invocation) as (service, auth):
             data = service.call("mammoth.api.dataviews.DataviewsAPI.get", **kwargs)
             parents.remember(_profile_name(invocation), auth.workspace_id, {view_id: dataset_id})
@@ -324,6 +433,10 @@ def view_get(invocation: Invocation) -> HandlerResult:
         data = service.call(_symbol(invocation), **kwargs)
         payload = _view_payload(data)
         parents.remember_records(_profile_name(invocation), auth.workspace_id, payload)
+    if not document.get("fields"):
+        # The discovery path returns the standard record; trim it to the same
+        # brief shape the exact path asks the server for.
+        payload = brief_view_record(payload)
     return payload, _meta(invocation, auth.workspace_id)
 
 

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/mammoth_cli/services/command_contract.py

@@ -578,6 +578,11 @@ _S7_ADDITIONAL_INPUT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
     # The GET data route has no server-side page size; the CLI trims the row
     # list so a read-back costs a screen of tokens, not the whole view.
     "view.data.get": (FieldSpec("limit", required=False, annotation=int, default=50),),
+    # The dataview GET takes a server-side projection: "__min", "__standard",
+    # "__full" or a comma-separated field list.
+    "view.get": (FieldSpec("fields", required=False, annotation=str | None, default=None),),
+    # ``view list`` records are trimmed to the brief shape; ``full`` keeps them.
+    "view.list": (FieldSpec("full", required=False, annotation=bool, default=False),),
     "activity.list": (
         FieldSpec("project_id", required=False, annotation=int | None, default=None),
         FieldSpec("workspace_id", required=False, annotation=int | None, default=None),

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.23"
+version = "2.0.25"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"

{mammoth_cli-2.0.23 → mammoth_cli-2.0.25}/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.23 → mammoth_cli-2.0.25}/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