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

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

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

{mammoth_cli-2.2.29 → mammoth_cli-2.2.30}/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.30}/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.30}/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.30}/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)
 
 

{mammoth_cli-2.2.29 → mammoth_cli-2.2.30}/mammoth_cli/services/input_fields.py

@@ -236,6 +236,7 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     },
     "view.conditional-format.delete-all": {"rule_id": "bca0ff33bd6f8ed1"},
     "dataset.bulk-delete": {"dataset_ids": [456, 457]},
+    "batch.bulk-delete": {"ids": [11, 12]},
     "folder.move": {"resource_ids": [8024], "target_folder_resource_id": "root"},
     "project.update": {"name": "Renamed project"},
     # ProjectsPatch: role changes across explicitly named projects.
@@ -267,17 +268,9 @@ _EXAMPLE_INPUT_HINTS: dict[str, dict[str, Any]] = {
     "view.export.publish-db-update": {
         "patch": [{"op": "replace", "path": "credentials", "value": {"odbc_type": "postgres"}}],
     },
-    # BatchesPostRequest: every ColumnNameMapping item carries the expected
-    # destination type; a bare {src: dst} map cannot satisfy the route.
-    "batch.create": {
-        "mapping": [
-            {
-                "source_c_name": "column_1",
-                "destination_c_name": "column_1",
-                "expected_destination_c_type": "TEXT",
-            }
-        ]
-    },
+    # BatchesPostRequest items carry the expected destination type; the CLI
+    # fills it from the destination's real schema, so the example omits it.
+    "batch.create": {"mapping": {"column_1": "column_1"}},
     # The SQL task reads the view as the quoted table "view:<id>" (or its
     # quoted display name); placeholder names such as ``data`` are rejected.
     "view.transform.add-sql": {

{mammoth_cli-2.2.29 → mammoth_cli-2.2.30}/pyproject.toml

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

{mammoth_cli-2.2.29 → mammoth_cli-2.2.30}/spec/manifests/commands/automation.yaml

@@ -82,7 +82,9 @@ commands:
     task, trigger, option and file format in and out (PDF included). Task models can pull cloud files and send email;
     requires connector/email allowlists and dedicated fixtures. Delete old rows on a schedule with
     task apply_retention_policy (datasource_id, rule_type time_based, count_based or
-    condition_based). An emailed file is task send_an_alert with attachments.dataview_ids: each
+    condition_based). The CLI sets require_approval=true on a retention task that omits it (the route
+    defaults to false, an unattended hard delete); require_approval=false with the delete action needs
+    --yes --confirm unattended-delete. An emailed file is task send_an_alert with attachments.dataview_ids: each
     selected view is emailed as a CSV file. The combined row count of all attached views must stay
     within 100,000 -- over that, the automation is refused (and a run that grows past it fails).'
   reviewed_by: primary

{mammoth_cli-2.2.29 → mammoth_cli-2.2.30}/spec/manifests/commands/batch.yaml

@@ -30,7 +30,7 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth batch bulk-delete DATASET_ID --help
-  agent_example: mammoth batch bulk-delete 123
+  agent_example: 'mammoth batch bulk-delete 123 --input ''{"ids": [11, 12]}'''
   unit_tests:
   - UT-BATCH-BULK-DELETE
   contract_tests:
@@ -39,7 +39,7 @@ commands:
   - CT-BATCH-BULK-DELETE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: null
+  known_restrictions: ids is required (the backend rejects a delete with no batch ids; it never deletes all batches). List ids with batch list.
   reviewed_by: primary
   readback:
     command: batch.list
@@ -82,8 +82,7 @@ commands:
   required_fixture_guard: null
   secret_fields: []
   human_example: mammoth batch create DATASET_ID SOURCE_ID --help
-  agent_example: 'mammoth batch create 123 123 --input ''{"mapping": [{"source_c_name": "column_1", "destination_c_name":
-    "column_1", "expected_destination_c_type": "TEXT"}]}'''
+  agent_example: 'mammoth batch create 123 123 --input ''{"mapping": {"column_1": "column_1"}}'''
   unit_tests:
   - UT-BATCH-CREATE
   contract_tests:
@@ -92,7 +91,7 @@ commands:
   - CT-BATCH-CREATE-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: SOURCE_ID is a standalone dataset in the same project (4BATC010 INVALID_SOURCE_DATASET for a file id or an append child); to append a file use file upload with append_to_ds_id. delete_source_ds=true changes the mutation class to destructive and requires confirmation.
+  known_restrictions: Every source column must be mapped to an existing destination column; the CLI reads both schemas and refuses (append_mapping_incomplete) an unmapped source column or a destination the dataset lacks, because the backend appends only mapped columns. The CLI sends each item's expected_destination_c_type as the destination's current type (never re-types it; an explicit different value is refused with append_type_mismatch) and warns in mapping_check.warnings when source and destination types differ. SOURCE_ID is a standalone dataset in the same project (4BATC010 INVALID_SOURCE_DATASET for a file id or an append child); to append a file use file upload with append_to_ds_id. delete_source_ds=true changes the mutation class to destructive and requires confirmation.
   reviewed_by: primary
   readback:
     command: batch.list

{mammoth_cli-2.2.29 → mammoth_cli-2.2.30}/spec/manifests/commands/project.yaml

@@ -933,7 +933,7 @@ commands:
   - CT-PROJECT-USER-ADD-ERROR
   draft_test: null
   undo_test: null
-  known_restrictions: 'B03 PROJECT_USER_ID_ROLE_UNTYPED. Takes existing workspace users'' ids. To add
+  known_restrictions: 'B03 PROJECT_USER_ID_ROLE_UNTYPED. role is required, and a user who is already a project member is refused (the backend would replace that member''s role, demoting an admin); change roles with project user update. Takes existing workspace users'' ids. To add
     someone by email who is not in the workspace yet, use workspace user add with
     {"email_ids": [EMAIL], "projects": [{"project_id": PROJECT_ID, "role": ROLE}]}: it invites them as a workspace member
     with that project role, which is how a project gets a new person.'