mammoth-cli 2.2.29__tar.gz → 2.2.31__tar.gz

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.29
+Version: 2.2.31
 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.2.29 → mammoth_cli-2.2.31}/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.29"
+__version__ = "2.2.31"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/mammoth_cli/bundled_skill/mammoth-cli/references/about-mammoth.md

@@ -106,7 +106,7 @@ Checkpoint Alert are the `view data-check` and `view checkpoint` families.
 | Add columns from another view by matching keys | Join | `join` (`INNER`, `LEFT`, `RIGHT`, `OUTER`) |
 | Bring one value per key from another view | Lookup | `lookup` |
 | Totals, counts, averages per group | Group & Pivot | `pivot` (replaces the view's columns) |
-| A rows-by-columns summary table | Group & Pivot (crosstab) | `crosstab` (writes a new dataset) |
+| A rows-by-columns summary table | Group & Pivot (crosstab) | `crosstab` (writes a new dataset, and keeps rewriting it on every pipeline run of the view) |
 | Turn wide columns into label/value rows | Unpivot | `unnest` |
 | Read fields out of a JSON column | Extract JSON | `json-extract` |
 | Classify, tag or summarise rows with AI | Generative AI | `ai` |

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/batch.md

@@ -6,7 +6,7 @@ Every command returns the standard JSON envelope. On nonzero exit, read the erro
 
 Run: `mammoth batch bulk-delete`. Exact input fields: `mammoth schema get batch.bulk-delete`.
 
-Example: `mammoth batch bulk-delete 123`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth batch bulk-delete 123 --input '{"ids": [11, 12]}'`. Illustrative only: append `--yes` after observing an owned target.
 
 Result: `BatchBulkDeleteResult`; mutation `destructive`, confirmation `prompt_or_yes`, wait policy `not_async`.
 
@@ -16,7 +16,7 @@ Status on release: ran once on CLI 2.0.14 — write sweep 2026-09-18: exit 0 on
 
 Run: `mammoth batch create`. Exact input fields: `mammoth schema get batch.create`.
 
-Example: `mammoth batch create 123 123 --input '{"mapping": [{"source_c_name": "column_1", "destination_c_name": "column_1", "expected_destination_c_type": "TEXT"}]}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth batch create 123 123 --input '{"mapping": {"column_1": "column_1"}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `BatchCreateResult`; mutation `benign_mutation`, confirmation `none`, wait policy `returns_job`.
 

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/exports.md

@@ -84,7 +84,7 @@ the run log. The connector command is `external_effect` with
 mammoth schema get view.export.postgres   # read secret_fields, required fields
 # operator writes /private/path/request.json (mode 0600):
 # {"host":"db.example","port":5432,"database":"analytics","table":"exports",
-#  "username":"agent","password":"…","dataset_id":DATASET_ID}
+#  "username":"agent","password":"…","replace_table":true,"dataset_id":DATASET_ID}
 mammoth view export postgres VIEW_ID DATASET_ID --project PROJECT_ID \
   --input /private/path/request.json --yes
 mammoth view export list VIEW_ID DATASET_ID --project PROJECT_ID
@@ -93,6 +93,16 @@ mammoth view export list VIEW_ID DATASET_ID --project PROJECT_ID
 If the operator has not supplied such a file, stop and ask for it; do not
 compose the body yourself from values seen in chat.
 
+A database export (`postgres`, `mysql`, `mssql`, `redshift`, `bigquery` with
+`export_type` REPLACE, and `publish-db`) drops and recreates its destination
+table now and on every later run of the view's pipeline, so any existing table
+of that name is lost. It is refused (`replace_table_not_acknowledged`) unless
+the input says `"replace_table": true`; only set that for a table the user said
+may be overwritten. `postgres` and `mysql` also cut a table name to 60
+characters and write a different table, so a longer name is refused
+(`table_name_too_long`). The result carries `refreshes_on_pipeline_run` and a
+`note` saying so.
+
 ## Generic export routes
 
 `view export csv` and the typed destination commands are the proven path. The

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/mammoth_cli/commands/automation.py

@@ -24,6 +24,7 @@ from mammoth_cli.errors.envelope import (
 )
 from mammoth_cli.manifest.loader import command_by_id
 from mammoth_cli.runtime.confirm import (
+    POLICY_CONFIRM_TARGET,
     POLICY_PROMPT_OR_YES,
     POLICY_YES_ALWAYS,
     enforce_confirmation,
@@ -215,6 +216,50 @@ def automation_delete(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, resolved_project(invocation))
 
 
+_RETENTION_TASK = "apply_retention_policy"
+_UNATTENDED_DELETE_TARGET = "unattended-delete"
+
+
+def _guard_retention_tasks(invocation: Invocation, tasks: Any) -> Any:
+    """Default retention tasks to ``require_approval`` and gate an unattended delete.
+
+    The route defaults ``require_approval`` to false, so a retention task with
+    the default ``delete`` action would hard-delete batches on every run with no
+    one approving. Here an omitted ``require_approval`` becomes true; an explicit
+    false with a delete action needs ``--yes --confirm unattended-delete``.
+    """
+    if not isinstance(tasks, list):
+        return tasks
+    guarded: list[Any] = []
+    unattended = False
+    for task in tasks:
+        details = task.get("details") if isinstance(task, dict) else None
+        if not (
+            isinstance(task, dict)
+            and task.get("task_type") == _RETENTION_TASK
+            and isinstance(details, dict)
+        ):
+            guarded.append(task)
+        elif "require_approval" not in details:
+            guarded.append({**task, "details": {**details, "require_approval": True}})
+        else:
+            unattended = unattended or (
+                details["require_approval"] is False and details.get("action", "delete") == "delete"
+            )
+            guarded.append(task)
+    if unattended:
+        enforce_confirmation(
+            invocation,
+            policy=POLICY_CONFIRM_TARGET,
+            action=(
+                "create a retention policy that DELETES matching batches on every run without "
+                "approval (require_approval is false)"
+            ),
+            target=_UNATTENDED_DELETE_TARGET,
+        )
+    return guarded
+
+
 def automation_create(invocation: Invocation) -> HandlerResult:
     """Create an automation. Name comes from a positional or the ``name`` field.
 
@@ -232,7 +277,7 @@ def automation_create(invocation: Invocation) -> HandlerResult:
             hint="Pass the name as a positional argument or a 'name' input field.",
         )
     description = document.get("description", "")
-    tasks = _require_field(document, "tasks")
+    tasks = _guard_retention_tasks(invocation, _require_field(document, "tasks"))
     kwargs: dict[str, Any] = {"name": name, "description": description, "tasks": tasks}
     _forward_optional(document, kwargs, ("conditions", "condition_mode"))
     enforce_confirmation(invocation, policy=POLICY_YES_ALWAYS, action="create an automation")

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/mammoth_cli/commands/batch.py

@@ -123,6 +123,144 @@ def batch_get(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
+_DATASET_GET_SYMBOL = "mammoth.api.datasets.DatasetsAPI.get"
+
+
+def _dataset_columns(service: Any, dataset_id: int, side: str) -> list[dict[str, Any]]:
+    """The dataset's own schema rows (``c_name``, ``c_id``, ``c_type``), or raise.
+
+    An unreadable schema is never treated as "no columns": the mapping check
+    could not run, so the batch is not created.
+    """
+    response = service.call(_DATASET_GET_SYMBOL, dataset_id=dataset_id)
+    dataset = response.get("dataset") if isinstance(response, dict) else None
+    schema = dataset.get("data_schema") if isinstance(dataset, dict) else None
+    if not isinstance(schema, list) or not all(
+        isinstance(col, dict) and isinstance(col.get("c_name"), str) for col in schema
+    ):
+        raise CliError(
+            code="append_schema_unreadable",
+            message=f"Could not read the {side} dataset {dataset_id}'s schema before the batch.",
+            hint=f"Read dataset {dataset_id} before creating the batch.",
+            details={"side": side, "dataset_id": dataset_id},
+        )
+    return schema
+
+
+def _mapping_items(mapping: Any) -> list[Any]:
+    """Expand a ``{src: dst}`` mapping into ``ColumnNameMapping`` items, untyped."""
+    if isinstance(mapping, dict):
+        return [{"source_c_name": src, "destination_c_name": dst} for src, dst in mapping.items()]
+    return list(mapping) if isinstance(mapping, list) else []
+
+
+def _resolve_item(
+    item: dict[str, Any], source: list[dict[str, Any]], dest: list[dict[str, Any]]
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """The (source, destination) schema rows an item names by name or id, else None."""
+    by_id = "source_c_id" in item
+    field, src_key, dest_key = (
+        ("c_id", "source_c_id", "destination_c_id")
+        if by_id
+        else ("c_name", "source_c_name", "destination_c_name")
+    )
+    src_col = next((col for col in source if col.get(field) == item.get(src_key)), None)
+    dest_col = next((col for col in dest if col.get(field) == item.get(dest_key)), None)
+    return src_col, dest_col
+
+
+def _reject_incomplete_batch_mapping(
+    ids: tuple[int, int],
+    source_names: set[str],
+    mapped_sources: set[str],
+    unknown: list[str],
+) -> None:
+    """Refuse a mapping that leaves source columns out or names a missing destination."""
+    unmapped = sorted(source_names - mapped_sources)
+    if not unmapped and not unknown:
+        return
+    dataset_id, source_id = ids
+    problems = []
+    if unknown:
+        problems.append(f"destination column(s) not in dataset {dataset_id}: {', '.join(unknown)}")
+    if unmapped:
+        problems.append(f"source column(s) left unmapped and not appended: {', '.join(unmapped)}")
+    raise CliError(
+        code="append_mapping_incomplete",
+        message=(
+            f"mapping for appending dataset {source_id} into dataset {dataset_id} would corrupt "
+            f"the append: {'; '.join(problems)}. Unmapped source columns are not appended."
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            f"Map every source column of dataset {source_id} to an existing column of dataset "
+            f"{dataset_id}."
+        ),
+        details={"unknown_destinations": unknown, "unmapped_source_columns": unmapped},
+    )
+
+
+def _reject_type_change(item: dict[str, Any], dest_col: dict[str, Any], dataset_id: int) -> None:
+    """Refuse an explicit expected type that differs from the destination's real one."""
+    expected, actual = item.get("expected_destination_c_type"), dest_col.get("c_type")
+    if expected is None or not actual or str(expected).upper() == str(actual).upper():
+        return
+    raise CliError(
+        code="append_type_mismatch",
+        message=(
+            f"expected_destination_c_type {expected} for destination column "
+            f"{dest_col['c_name']!r} of dataset {dataset_id} would change its type from "
+            f"{actual}; the append would convert the whole destination column."
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            "Omit expected_destination_c_type (the CLI sends the destination's current "
+            f"type, {actual})."
+        ),
+        details={"column": dest_col["c_name"], "expected": expected, "actual": actual},
+    )
+
+
+def _checked_batch_mapping(
+    service: Any, dataset_id: int, source_id: int, mapping: Any
+) -> tuple[list[dict[str, Any]], list[str]]:
+    """Validate a batch mapping against both schemas; return typed items and warnings.
+
+    Refuses unmapped source columns and unknown destinations (the backend appends
+    only the mapped columns) and stamps every item with the destination's actual
+    current type, so no destination column is silently re-typed. A mapped pair
+    whose source and destination types differ is returned as a warning.
+    """
+    source = _dataset_columns(service, source_id, "source")
+    dest = _dataset_columns(service, dataset_id, "target")
+    items = [dict(item) for item in _mapping_items(mapping) if isinstance(item, dict)]
+    typed: list[dict[str, Any]] = []
+    mapped_sources: set[str] = set()
+    unknown: list[str] = []
+    warnings: list[str] = []
+    for item in items:
+        src_col, dest_col = _resolve_item(item, source, dest)
+        if src_col is not None:
+            mapped_sources.add(src_col["c_name"])
+        if dest_col is None:
+            if item.get("action") != "add_column":
+                unknown.append(str(item.get("destination_c_name", item.get("destination_c_id"))))
+            typed.append(item)
+            continue
+        _reject_type_change(item, dest_col, dataset_id)
+        item.setdefault("expected_destination_c_type", dest_col.get("c_type"))
+        typed.append(item)
+        if src_col and src_col.get("c_type") and src_col["c_type"] != dest_col.get("c_type"):
+            warnings.append(
+                f"mapped column {src_col['c_name']!r} is {str(src_col['c_type']).lower()} but "
+                f"destination column {dest_col['c_name']!r} is {str(dest_col['c_type']).lower()}"
+            )
+    _reject_incomplete_batch_mapping(
+        (dataset_id, source_id), {col["c_name"] for col in source}, mapped_sources, unknown
+    )
+    return typed, warnings
+
+
 def batch_create(invocation: Invocation) -> HandlerResult:
     """Create a batch for a dataset. ``source_id`` and ``mapping`` are required."""
     project_id = require_project(invocation)
@@ -158,7 +296,12 @@ def batch_create(invocation: Invocation) -> HandlerResult:
             action=f"create a batch on dataset {dataset_id} and DELETE the source dataset",
         )
     with open_service(invocation) as (service, auth):
+        kwargs["mapping"], warnings = _checked_batch_mapping(
+            service, dataset_id, source_id, mapping
+        )
         data = service.call(_symbol(invocation), **kwargs)
+    if warnings and isinstance(data, dict):
+        data["mapping_check"] = {"warnings": warnings}
     return data, _meta(invocation, auth.workspace_id, project_id)
 
 
@@ -249,20 +392,30 @@ def batch_delete(invocation: Invocation) -> HandlerResult:
 
 
 def batch_bulk_delete(invocation: Invocation) -> HandlerResult:
-    """Bulk-delete batches for a dataset. Prompt or ``--yes`` required.
+    """Bulk-delete the named batches of a dataset. Prompt or ``--yes`` required.
 
-    When no ``ids`` are given, every batch for the dataset is deleted.
+    ``ids`` is required: the backend rejects a delete with no batch ids, it
+    never deletes "all batches".
     """
     project_id = require_project(invocation)
     dataset_id = _require_int_positional_at(invocation, 0, "dataset id")
     document = invocation.load_input() or {}
+    ids = _require_field(document, "ids")
+    if not ids:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message="The 'ids' input field must name at least one batch id.",
+            exit_status=EXIT_USAGE,
+            hint=f"List batch ids with `mammoth batch list {dataset_id}`.",
+        )
+    count = len(ids) if isinstance(ids, list) else len(str(ids).split(","))
     enforce_confirmation(
         invocation,
         policy=POLICY_PROMPT_OR_YES,
-        action=f"delete batches of dataset {dataset_id}",
+        action=f"delete {count} batch(es) of dataset {dataset_id}",
     )
-    kwargs: dict[str, Any] = {"dataset_id": dataset_id, "project_id": project_id}
-    _forward_optional(document, kwargs, ("ids",))
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), **kwargs)
+        data = service.call(
+            _symbol(invocation), dataset_id=dataset_id, project_id=project_id, ids=ids
+        )
     return data, _meta(invocation, auth.workspace_id, project_id)

{mammoth_cli-2.2.29 → mammoth_cli-2.2.31}/mammoth_cli/commands/project.py

@@ -505,23 +505,54 @@ def project_data_check_list(invocation: Invocation) -> HandlerResult:
     return _list_with_filters(invocation)
 
 
+_PROJECT_MEMBERS_SYMBOL = "mammoth.api.workspace.WorkspaceAPI.list_users"
+
+
+def _reject_existing_members(service: Any, project_id: int, user_ids: Any) -> None:
+    """Refuse an add naming a user who is already a member of the project.
+
+    The backend treats adding an existing member as a role replacement (it
+    revokes the current role, then assigns the given one), so an add can
+    silently demote a project admin. Role changes belong to ``project user
+    update``.
+    """
+    members = service.call(_PROJECT_MEMBERS_SYMBOL, project_id=project_id)
+    member_ids = {str(m.get("id")) for m in members if isinstance(m, dict)}
+    existing = [uid for uid in user_ids if str(uid) in member_ids]
+    if existing:
+        raise CliError(
+            code=CODE_INVALID_ARGUMENT,
+            message=(
+                f"User(s) {', '.join(str(uid) for uid in existing)} already belong to project "
+                f"{project_id}; adding them again would replace their current role."
+            ),
+            exit_status=EXIT_USAGE,
+            hint="Use `mammoth project user update` to change a member's role.",
+            details={"existing_user_ids": existing, "project_id": project_id},
+        )
+
+
 def project_user_add(invocation: Invocation) -> HandlerResult:
-    """Add users to a project. High-impact: ``--yes --confirm PROJECT_ID``."""
+    """Add users to a project. High-impact: ``--yes --confirm PROJECT_ID``.
+
+    ``role`` is required and no listed user may already be a member (the
+    backend would replace that member's role).
+    """
     project_id = _project_id(invocation)
     document = invocation.load_input()
     user_ids = _require_input_field(document, "user_ids")
+    role = _require_input_field(document, "role")
     enforce_confirmation(
         invocation,
         policy=POLICY_CONFIRM_TARGET,
         action=f"add users to project {project_id}",
         target=str(project_id),
     )
-    kwargs: dict[str, Any] = {"project_id": project_id, "user_ids": user_ids}
-    assert document is not None
-    if "role" in document:
-        kwargs["role"] = document["role"]
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), **kwargs)
+        _reject_existing_members(service, project_id, user_ids)
+        data = service.call(
+            _symbol(invocation), project_id=project_id, user_ids=user_ids, role=role
+        )
     return data, _meta(invocation, auth.workspace_id, project_id)