mammoth-cli 2.0.29__tar.gz → 2.0.30__tar.gz

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.29
+Version: 2.0.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.0.29 → mammoth_cli-2.0.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.0.29"
+__version__ = "2.0.30"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/app.py

@@ -29,7 +29,7 @@ from typer.core import TyperGroup
 
 from mammoth_cli import __version__
 from mammoth_cli.commands import BESPOKE
-from mammoth_cli.commands.registry import HANDLERS
+from mammoth_cli.commands.registry import HANDLERS, Handler
 from mammoth_cli.context import profiles
 from mammoth_cli.errors.envelope import EXIT_USAGE, CliError, not_implemented_error
 from mammoth_cli.manifest.loader import command_by_id, load_commands
@@ -629,6 +629,18 @@ def _shared_option_params() -> list[inspect.Parameter]:
                 ),
             ],
         ),
+        opt(
+            "dry_run",
+            False,
+            Annotated[
+                bool,
+                typer.Option(
+                    "--dry-run",
+                    help="Resolve and validate, then report the request instead of sending it.",
+                    rich_help_panel="Safety",
+                ),
+            ],
+        ),
         opt(
             "input_file",
             None,
@@ -777,6 +789,8 @@ def _execute(invocation: Invocation) -> None:
             record = command_by_id(invocation.command_id)
             sdk_symbol = record.get("sdk_symbol", "") if record else ""
             raise not_implemented_error(invocation.command_id, sdk_symbol)
+        if invocation.dry_run:
+            return _dry_run(handler, invocation)
         return handler(invocation)
 
     executor.run(
@@ -789,6 +803,25 @@ def _execute(invocation: Invocation) -> None:
     )
 
 
+def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, Any]]:
+    """Run ``handler`` until its request would leave; report that request.
+
+    Local commands never open a service, so a dry run of one is the real run.
+    An API-backed handler that returns normally under ``--dry-run`` made no
+    gated SDK call at all (a pure read path); its result is returned as is.
+    """
+    from mammoth_cli.runtime.dryrun import DryRunStop
+    from mammoth_cli.runtime.session import resolved_project
+
+    try:
+        return handler(invocation)
+    except DryRunStop as stop:
+        return stop.record, {
+            "profile": invocation.profile,
+            "project_id": resolved_project(invocation),
+        }
+
+
 def _command_help(command_id: str, record: dict[str, Any] | None) -> str | None:
     """Build a command's user-facing ``--help`` summary.
 

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.29
+version: 2.0.30
 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."
 ---
 
@@ -60,6 +60,8 @@ before the next step.
   '{"full": true}'` returns the dependency and display trees too.
 - Column inputs and expressions use the exact **display names** the view
   returns, never backend aliases.
+- `--dry-run` on any API-backed command resolves everything and reports the
+  request instead of sending it; use it before a write you are not sure of.
 - Destructive commands need `--yes --confirm ID`. Preserve requested
   deliverables; cleanup is exact-ID authorized and
   never means delete-all-owned-resources: delete only ids this run created,

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -932,7 +932,7 @@ Example: `mammoth view transform extract-date 123 --input '{"column": "Status",
 
 Result: `ViewTransformExtractDateResult`; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+Status on release: ran once on CLI 2.0.18 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 
 ### `view.transform.fill-missing`
 
@@ -1112,7 +1112,7 @@ Example: `mammoth view transform window 123 --input '{"function": "ROW_NUMBER",
 
 Result: `ViewTransformWindowResult`; mutation `reversible_pipeline`, confirmation `none`, wait policy `always_wait`.
 
-Status on release: untried; it submits through `view.task.add`, but this transform was not among those run.
+Status on release: ran once on CLI 2.0.18 through `view.task.add` and was read back with `view data get`; other inputs for this transform are untried.
 
 ### `view.trash`
 

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/input.md

@@ -13,6 +13,8 @@ mammoth view transform filter 1039 --project 180 \
 - `--input FILE` (or `--input @FILE`) reads a JSON or YAML file; the format
   is inferred from the extension.
 - `--input -` reads stdin; then `--input-format json|yaml` is required.
+- `--dry-run` admits and resolves the document, then reports the SDK call
+  instead of making it ([safety](safety.md)).
 - The top level must be a mapping. A bad path, format, or shape fails with exit
   code 2 and a stable error code.
 - Column references use display names returned by the exact view schema. Do not

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/bundled_skill/mammoth-cli/references/operations.md

@@ -90,6 +90,14 @@ task/list or pipeline/items result back after a successful write. Without that
 independent specification, report the route as unsupported/ambiguous and stop
 safely.
 
+Typed transforms and `view task add` append at the end of the pipeline and
+never reorder or delete an existing step. On a pipeline other people or
+agents also edit, make that checkable: read `view task list VIEW_ID`, plan,
+then write with `"expected_task_count": N` in the input; the CLI re-reads
+the list just before the write and refuses with `pipeline_changed` when the
+count moved ([safety](safety.md)). `--dry-run` on the same command shows the
+resolved call first.
+
 For a new workflow (a container for automation), discover and then read it
 back; workflow creation is not the same as adding a view pipeline task:
 

mammoth_cli-2.0.30/mammoth_cli/bundled_skill/mammoth-cli/references/safety.md

@@ -0,0 +1,66 @@
+# Safe mutation
+
+Each command carries a reviewed confirmation policy:
+
+| policy | how to satisfy it noninteractively |
+|---|---|
+| none | nothing required |
+| prompt_or_yes | pass `--yes` |
+| yes_always | pass `--yes` (always, even at a terminal) |
+| confirm_target | pass `--yes` and `--confirm TARGET` (exact match) |
+
+Under `--no-input` (and in `json`/`ndjson` modes) there is no prompt: a missing
+`--yes`/`--confirm` fails with exit code 2 and error code
+`confirmation_required` or `confirmation_target_mismatch`.
+
+```bash
+# normal delete
+mammoth folder delete 7 --project 180 --yes
+
+# high-impact: target must equal the resource
+mammoth project user remove --project 180 \
+  --yes --confirm 180 --input '{"user_ids": ["u_123"]}'
+
+# project delete cascades to every dataset, view, export and dashboard in it
+mammoth project delete 180 --yes --confirm 180
+```
+
+Discover a command's policy with `mammoth schema get <command.id>`.
+
+## Rehearse before you write
+
+`--dry-run` on any API-backed command does everything but send the request:
+input admission, parent resolution, display-name and condition checks, then
+it stops at the SDK call and reports it as `data.would_call` (`sdk_symbol`,
+resolved `arguments`, `view_id`/`dataset_id`) with `data.dry_run: true`. No
+confirmation flag is needed for a dry run; the real run still needs its
+`--yes`/`--confirm`. Use it before a mutation on a shared or production
+resource, and whenever you are unsure which view or column an input resolves
+to.
+
+```bash
+mammoth view transform filter 144 --dry-run \
+  --input '{"filter_type": "REMOVE", "condition": {"column": "Location", "operator": "EQ", "value": "Total"}}'
+# data.would_call.sdk_symbol = ...FilterOpsMixin.filter_rows, view_id 144, dataset_id 122
+```
+
+## Add-only edits to a pipeline someone else may touch
+
+Every `view transform *` and `view task add` accepts `expected_task_count`:
+the number of tasks your last `view task list VIEW_ID` returned. The CLI
+re-reads the task list right before the write and refuses with
+`pipeline_changed` (exit 2, `details.actual_task_count`, `task_ids`) when the
+count differs, so a plan made against a stale read cannot land on a pipeline
+that changed under you. Read → decide → write with the count, one edit at a
+time; on `pipeline_changed`, re-read and re-decide rather than retrying with
+the new number blindly.
+
+```bash
+mammoth view task list 144            # data.tasks has 3 entries
+mammoth view transform filter 144 --input '{"expected_task_count": 3, "filter_type": "REMOVE", "condition": {...}}'
+```
+Use exact observed resource scope and display names before mutation. A known job
+handle should be inspected or waited, not submitted again. `outcome_unknown`
+means a mutation may have committed without a terminal response: reconcile the
+target before any replay. A retryable read can honor `Retry-After`; exit 7 is
+not blanket permission to retry a mutation.

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/commands/view.py

@@ -1445,11 +1445,15 @@ def view_task_add(invocation: Invocation) -> HandlerResult:
     kwargs: dict[str, Any] = {"dataview_id": dataview_id, "task_spec": task_spec}
     assert document is not None
     _forward_optional(document, kwargs, ("dataset_id",))
+    # Imported here: view_ops imports this module for the brief record helpers.
+    from mammoth_cli.commands.view_ops import (
+        reject_pipeline_reference_errors,
+        require_expected_task_count,
+    )
+
     with open_service(invocation) as (service, auth):
+        require_expected_task_count(service, dataview_id, kwargs.get("dataset_id"), document)
         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.29 → mammoth_cli-2.0.30}/mammoth_cli/commands/view_ops.py

@@ -43,6 +43,7 @@ from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, resolved_project
 from mammoth_cli.services.command_contract import bind_command_inputs
 from mammoth_cli.services.conditions import CONDITION_KWARG
+from mammoth_cli.services.input_fields import TASK_COUNT_FIELD
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -251,6 +252,7 @@ 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)
+        require_expected_task_count(service, view_id, dataset_id, document)
         try:
             if dataset_id is None:
                 _require_discovery_allowed(invocation, view_id)
@@ -266,6 +268,60 @@ def _dispatch_view(
     return data, _meta(invocation, auth.workspace_id)
 
 
+CODE_PIPELINE_CHANGED = "pipeline_changed"
+_TASK_LIST_SYMBOL = "mammoth.api.pipeline.PipelineAPI.list_tasks"
+
+
+def require_expected_task_count(
+    service: Any, view_id: int, dataset_id: Any, document: dict[str, Any] | None
+) -> None:
+    """Refuse a pipeline write when the view's task count is not the one read.
+
+    ``expected_task_count`` is the count from the caller's last ``view task
+    list``. A different live count means the pipeline changed since that read
+    (another agent, a person in the web app), and an append planned against
+    the old shape must not land. Without the field nothing is checked.
+    """
+    if not document or TASK_COUNT_FIELD not in document:
+        return
+    expected = int(document[TASK_COUNT_FIELD])
+    kwargs: dict[str, Any] = {"dataview_id": view_id}
+    if dataset_id is not None:
+        kwargs["dataset_id"] = int(dataset_id)
+    listing = service.call(_TASK_LIST_SYMBOL, **kwargs)
+    tasks = listing.get("tasks") if isinstance(listing, dict) else None
+    if not isinstance(tasks, list):
+        raise CliError(
+            code=CODE_PIPELINE_CHANGED,
+            message=f"Could not read the task list of view {view_id} to check the precondition.",
+            exit_status=EXIT_USAGE,
+            details={"view_id": view_id, "expected_task_count": expected, "response": listing},
+        )
+    actual = len(tasks)
+    if actual == expected:
+        return
+    raise CliError(
+        code=CODE_PIPELINE_CHANGED,
+        message=(
+            f"View {view_id} has {actual} pipeline task(s), not the {expected} expected; "
+            "the pipeline changed since it was read, so nothing was written."
+        ),
+        exit_status=EXIT_USAGE,
+        hint=(
+            "Re-read the pipeline, decide whether the plan still holds, and retry "
+            f"with expected_task_count {actual}."
+        ),
+        details={
+            "view_id": view_id,
+            "dataset_id": int(dataset_id) if dataset_id is not None else None,
+            "expected_task_count": expected,
+            "actual_task_count": actual,
+            "task_ids": [t.get("id") for t in tasks if isinstance(t, dict)],
+        },
+        recovery_commands=[f"mammoth view task list {view_id}"],
+    )
+
+
 def _compact_reference_error(entry: Any) -> dict[str, Any]:
     if not isinstance(entry, dict):
         return {"reason": str(entry)}
@@ -362,7 +418,11 @@ def _without_resource_context(document: dict[str, Any]) -> dict[str, Any]:
     # mapping.  These identifiers select the View receiver and are not method
     # kwargs; strip both parent and receiver identities before the transform
     # adapter forwards the document.
-    return {key: value for key, value in document.items() if key not in {"dataset_id", "view_id"}}
+    return {
+        key: value
+        for key, value in document.items()
+        if key not in {"dataset_id", "view_id", TASK_COUNT_FIELD}
+    }
 
 
 def _bind_transform_inputs(invocation: Invocation, document: dict[str, Any]) -> dict[str, Any]:

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/runtime/confirm.py

@@ -84,6 +84,10 @@ def enforce_confirmation(
     """
     if policy == POLICY_NONE:
         return
+    if invocation.dry_run:
+        # Nothing is sent under --dry-run, so there is nothing to confirm; the
+        # report names the confirmation the real run will need.
+        return
 
     tty = sys.stdin.isatty() if is_tty is None else is_tty
     machine = invocation.output in MACHINE_OUTPUTS

mammoth_cli-2.0.30/mammoth_cli/runtime/dryrun.py

@@ -0,0 +1,133 @@
+"""``--dry-run``: resolve a command completely, then stop before its request.
+
+A dry run does everything a real run does up to the network call that the
+command exists for — input admission, parent resolution, display-name checks,
+condition compilation, argument coercion — and then raises :class:`DryRunStop`
+instead of invoking the SDK method. The executor turns that into a success
+envelope describing the call that would have been made.
+
+The gate is a small callable installed on the production service by
+:func:`mammoth_cli.runtime.session.open_service`. It classifies each SDK call
+the handler makes:
+
+- the command's own manifest ``sdk_symbol`` (or, for View-backed commands,
+  the View method of that symbol) → stop and report;
+- a symbol some ``read`` command is backed by → let it through, so the
+  resolution the report depends on really happened;
+- anything else → stop and report it as an undeclared write, so a dry run
+  can never mutate through a side path.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from enum import Enum
+from functools import lru_cache
+from typing import Any
+
+from mammoth_cli.manifest.loader import command_by_id, load_commands
+
+Gate = Callable[..., None]
+
+NOTE_OWN = "No request was sent for this operation; the reads needed to resolve it did run."
+NOTE_UNDECLARED = (
+    "Stopped before an SDK call the command's manifest does not declare; "
+    "nothing was sent for it."
+)
+
+
+class DryRunStop(Exception):
+    """Raised by the gate at the point a real run would send the request."""
+
+    def __init__(self, record: dict[str, Any]) -> None:
+        super().__init__("dry run")
+        self.record = record
+
+
+@lru_cache(maxsize=1)
+def _read_symbols() -> frozenset[str]:
+    return frozenset(
+        str(record["sdk_symbol"])
+        for record in load_commands()
+        if record.get("mutation_class") == "read" and record.get("sdk_symbol")
+    )
+
+
+def _read_view_methods() -> frozenset[str]:
+    return frozenset(
+        symbol.rsplit(".", 1)[1]
+        for symbol in _read_symbols()
+        if symbol.startswith("mammoth.view.") or symbol.startswith("mammoth._mixins.")
+    )
+
+
+def jsonable(value: Any) -> Any:
+    """Render resolved SDK arguments for the report without leaking objects."""
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Mapping):
+        return {str(key): jsonable(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [jsonable(item) for item in value]
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    to_dict = getattr(value, "to_dict", None)
+    if callable(to_dict):
+        try:
+            return jsonable(to_dict())
+        except Exception:  # pragma: no cover - defensive; fall through to repr
+            return repr(value)
+    view_id = getattr(value, "id", None)
+    if type(value).__name__ == "View" and isinstance(view_id, int):
+        return {"view_id": view_id, "dataset_id": getattr(value, "dataset_id", None)}
+    return repr(value)
+
+
+def make_gate(command_id: str) -> Gate:
+    """Return the gate for ``command_id`` (see the module docstring)."""
+    record = command_by_id(command_id) or {}
+    own_symbol = str(record.get("sdk_symbol") or "")
+    own_method = own_symbol.rsplit(".", 1)[-1] if own_symbol else ""
+    mutation_class = record.get("mutation_class")
+    # A CLI-composed command (project ensure, ...) is backed by a CLI function
+    # and reaches the SDK through whichever writes it needs; those are its own.
+    composed = own_symbol.startswith("mammoth_cli.")
+    reads = _read_symbols()
+    view_reads = _read_view_methods()
+
+    def stop(symbol: str, arguments: dict[str, Any], *, own: bool, **scope: Any) -> None:
+        raise DryRunStop(
+            {
+                "dry_run": True,
+                "command": command_id.replace(".", " "),
+                "mutation_class": mutation_class,
+                "would_call": {
+                    "sdk_symbol": symbol,
+                    **{key: value for key, value in scope.items() if value is not None},
+                    "arguments": jsonable(arguments),
+                },
+                "note": NOTE_OWN if own else NOTE_UNDECLARED,
+            }
+        )
+
+    def gate(
+        symbol: str,
+        arguments: dict[str, Any],
+        *,
+        view_id: int | None = None,
+        dataset_id: int | None = None,
+    ) -> None:
+        if view_id is not None:
+            # A View-backed call: ``symbol`` is the View method name.
+            if symbol == own_method:
+                stop(own_symbol, arguments, own=True, view_id=view_id, dataset_id=dataset_id)
+            if symbol in view_reads:
+                return
+            stop(f"View.{symbol}", arguments, own=False, view_id=view_id, dataset_id=dataset_id)
+        if symbol == own_symbol:
+            stop(symbol, arguments, own=True)
+        if symbol in reads:
+            return
+        stop(symbol, arguments, own=composed)
+
+    return gate

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/runtime/invocation.py

@@ -16,7 +16,11 @@ from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
 from mammoth_cli.output.policy import OUTPUT_AUTO, SELECTABLE_OUTPUTS, resolve_output
 from mammoth_cli.runtime.input_loader import load_input_document
 from mammoth_cli.runtime.strict import validate_input_fields
-from mammoth_cli.services.input_fields import accepts_resource_dataset
+from mammoth_cli.services.input_fields import (
+    TASK_COUNT_FIELD,
+    accepts_resource_dataset,
+    accepts_task_count_precondition,
+)
 
 
 class _UninitializedInput:
@@ -55,6 +59,7 @@ class Invocation:
     debug: bool = False
     yes: bool = False
     confirm: str | None = None
+    dry_run: bool = False
     input_file: str | None = None
     input_format: str | None = None
     positionals: dict[str, Any] = field(default_factory=dict)
@@ -231,10 +236,36 @@ class Invocation:
                         hint="Pass the exact parent dataset id for the target view.",
                         details={"field": "dataset_id", "expected_type": "positive integer"},
                     ) from None
+            expected_tasks: Any = None
+            has_expected_tasks = (
+                document is not None
+                and accepts_task_count_precondition(self.command_id)
+                and TASK_COUNT_FIELD in document
+            )
+            if has_expected_tasks:
+                assert document is not None
+                expected_tasks = document.pop(TASK_COUNT_FIELD)
+                try:
+                    if isinstance(expected_tasks, bool):
+                        raise ValueError
+                    expected_tasks = int(expected_tasks)
+                    if expected_tasks < 0:
+                        raise ValueError
+                except (TypeError, ValueError):
+                    raise CliError(
+                        code="invalid_resource_context",
+                        message=f"Input field '{TASK_COUNT_FIELD}' must be a non-negative integer.",
+                        exit_status=EXIT_USAGE,
+                        hint="Pass the task count from your last 'view task list' read.",
+                        details={"field": TASK_COUNT_FIELD, "expected_type": "integer >= 0"},
+                    ) from None
             validate_input_fields(self.command_id, document)
             if has_resource_dataset:
                 assert document is not None
                 document["dataset_id"] = resource_dataset
+            if has_expected_tasks:
+                assert document is not None
+                document[TASK_COUNT_FIELD] = expected_tasks
             object.__setattr__(self, "_prepared_input", document)
         return self._prepared_input  # type: ignore[return-value]
 

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/runtime/session.py

@@ -79,6 +79,13 @@ def open_service(invocation: Invocation) -> Iterator[tuple[MammothService, Resol
         profile=invocation.profile or profiles.get_selected(),
         progress=not policy.progress_disabled,
     )
+    if invocation.dry_run:
+        # The production service exposes the gate; a test double may not, and
+        # then the dry run is simply the double's own behaviour.
+        if hasattr(service, "gate"):
+            from mammoth_cli.runtime.dryrun import make_gate
+
+            service.gate = make_gate(invocation.command_id)
     try:
         yield service, auth
     finally:

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/services/command_contract.py

@@ -26,7 +26,9 @@ from mammoth.models.batches import (
 from mammoth_cli.manifest.loader import command_by_id, load_commands
 from mammoth_cli.services.argspec import ArgSpec, FieldSpec, arg_spec
 from mammoth_cli.services.input_fields import (
+    TASK_COUNT_FIELD,
     accepts_resource_dataset,
+    accepts_task_count_precondition,
     excluded_input_fields,
     handler_owned_fields,
     is_closed_zero_input,
@@ -672,6 +674,12 @@ def resolve_command_contract(command_id: str) -> ResolvedCommandContract | None:
         field.name for field in fields
     }:
         fields += (FieldSpec("dataset_id", required=False, annotation=int | None, default=None),)
+    if accepts_task_count_precondition(command_id) and TASK_COUNT_FIELD not in {
+        field.name for field in fields
+    }:
+        fields += (
+            FieldSpec(TASK_COUNT_FIELD, required=False, annotation=int | None, default=None),
+        )
     additional_fields = _S7_ADDITIONAL_INPUT_FIELDS.get(command_id, ())
     declared_names = {field.name for field in fields}
     fields += tuple(field for field in additional_fields if field.name not in declared_names)
@@ -686,6 +694,8 @@ def resolve_command_contract(command_id: str) -> ResolvedCommandContract | None:
     # the subsequent shared bind idempotent after that protected preflight.
     if accepts_resource_dataset(command_id):
         context_values["dataset_id"] = "dataset_id"
+    if accepts_task_count_precondition(command_id):
+        context_values[TASK_COUNT_FIELD] = TASK_COUNT_FIELD
     context = MappingProxyType(context_values)
     extensibility = (
         "closed"

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/services/input_fields.py

@@ -351,6 +351,18 @@ def accepts_resource_dataset(command_id: str) -> bool:
     return command_id.startswith(_RESOURCE_DATASET_PREFIXES)
 
 
+#: Pipeline writes that admit ``expected_task_count``: the number of tasks the
+#: caller last read on the view. The write is refused when the pipeline has a
+#: different count, so an edit planned against a stale read cannot land on a
+#: pipeline someone else changed (the "add-only to a shared pipeline" rule).
+TASK_COUNT_FIELD = "expected_task_count"
+
+
+def accepts_task_count_precondition(command_id: str) -> bool:
+    """Return True when ``expected_task_count`` is admitted for ``command_id``."""
+    return command_id.startswith("view.transform.") or command_id == "view.task.add"
+
+
 def example_input_hints(command_id: str) -> dict[str, Any]:
     """Return extra ``--input`` fields to include in the generated example."""
     hints = dict(_EXAMPLE_INPUT_HINTS.get(command_id, {}))

{mammoth_cli-2.0.29 → mammoth_cli-2.0.30}/mammoth_cli/services/sdk_service.py

@@ -9,6 +9,7 @@ a private (``_``-prefixed) SDK member.
 from __future__ import annotations
 
 import re
+from collections.abc import Callable
 from types import TracebackType
 from typing import Any
 
@@ -72,6 +73,9 @@ class SdkMammothService:
         """
         self._progress = progress
         self._profile = profile
+        #: ``--dry-run`` hook (:mod:`mammoth_cli.runtime.dryrun`): called with
+        #: the resolved symbol and arguments right before each SDK call.
+        self.gate: Callable[..., None] | None = None
         self._project_id = project_id
         self._workspace_id = auth.workspace_id
         kwargs: dict[str, Any] = {}
@@ -124,6 +128,8 @@ class SdkMammothService:
         ):
             raise missing_project_error()
         kwargs = self._coerce_call_arguments(method, kwargs)
+        if self.gate is not None:
+            self.gate(sdk_symbol, kwargs)
         try:
             with spinner(self._progress):
                 return method(**kwargs)
@@ -356,6 +362,8 @@ class SdkMammothService:
             ) from exc
         if kwargs.get(CONDITION_KWARG) is not None:
             kwargs[CONDITION_KWARG] = compile_condition(kwargs[CONDITION_KWARG])
+        if self.gate is not None:
+            self.gate(method, kwargs, view_id=view_id, dataset_id=getattr(view, "dataset_id", None))
         try:
             with spinner(self._progress):
                 return attribute(**kwargs)
@@ -717,6 +725,8 @@ class SdkMammothService:
         Raises:
             CliError: Mapped from any SDK exception.
         """
+        if self.gate is not None:
+            self.gate("mammoth.api.projects.ProjectsAPI.create", {"name": name, **kwargs})
         try:
             return self._client.projects.create(name, **kwargs)
         except Exception as exc:
@@ -734,6 +744,8 @@ class SdkMammothService:
         Raises:
             CliError: Mapped from any SDK exception.
         """
+        if self.gate is not None:
+            self.gate("mammoth.api.projects.ProjectsAPI.delete", {"project_id": project_id})
         try:
             return self._client.projects.delete(project_id)
         except Exception as exc: