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

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

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

{mammoth_cli-2.0.29 → mammoth_cli-2.0.31}/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
@@ -330,6 +330,13 @@ class _LeafGroup(TyperGroup):
 class _EnvelopeGroup(TyperGroup):
     """Root group that renders Click usage errors as the machine error envelope.
 
+    It also materialises top-level command groups lazily (see
+    :func:`_load_top_level_group`): ``list_commands`` and ``get_command`` know
+    every group by name from the manifest, but a group's Click tree is only
+    built when it is invoked, completed or listed in ``--help``. Reading
+    ``commands`` directly materialises them all, so tools that walk the tree
+    still see the full surface.
+
     Click's standalone error handling prints a human ``Usage: ... Error: ...``
     message and exits, even under ``--output json``: an agent driving the CLI
     then receives un-parseable prose (or, for a leaf that also parents
@@ -345,6 +352,28 @@ class _EnvelopeGroup(TyperGroup):
     on.
     """
 
+    @property  # type: ignore[override]
+    def commands(self) -> dict[str, Any]:
+        loaded: dict[str, Any] = self.__dict__.setdefault("_eager_commands", {})
+        for name in _LAZY_GROUP_NAMES:
+            if name not in loaded:
+                loaded[name] = _load_top_level_group(name)
+        return loaded
+
+    @commands.setter
+    def commands(self, value: Any) -> None:
+        self.__dict__["_eager_commands"] = dict(value or {})
+
+    def list_commands(self, ctx: Any) -> list[str]:
+        eager = self.__dict__.get("_eager_commands", {})
+        return [*eager, *(name for name in _LAZY_GROUP_NAMES if name not in eager)]
+
+    def get_command(self, ctx: Any, cmd_name: str) -> Any:
+        eager: dict[str, Any] = self.__dict__.setdefault("_eager_commands", {})
+        if cmd_name not in eager and cmd_name in _LAZY_GROUP_NAMES:
+            eager[cmd_name] = _load_top_level_group(cmd_name)
+        return eager.get(cmd_name)
+
     def main(self, *args: Any, **kwargs: Any) -> Any:
         if not kwargs.get("standalone_mode", True):
             return super().main(*args, **kwargs)
@@ -629,6 +658,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 +818,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 +832,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.
 
@@ -855,68 +917,55 @@ def _short_type(type_name: str) -> str:
     return " | ".join(part.strip().rsplit(".", 1)[-1] for part in text.split("|"))[:40]
 
 
-def build_app() -> typer.Typer:
-    """Construct the full Typer command tree from the command manifests."""
-    root = typer.Typer(
-        name="mammoth",
-        help=(
-            "Command-line interface for the Mammoth Analytics platform.\n\n"
-            "Start with 'mammoth doctor' to check access, 'mammoth schema find QUERY' "
-            "to locate a command, and 'mammoth schema get COMMAND_ID' for its full input schema."
-        ),
+def _command_records() -> list[dict[str, Any]]:
+    return [r for r in load_commands() if r.get("disposition") != "alias"]
+
+
+@cache
+def _command_tree() -> tuple[dict[tuple[str, ...], str], frozenset[tuple[str, ...]]]:
+    """Map every command path to its id, and name the container nodes.
+
+    A "container command" sits at a node that also has deeper subcommands
+    (e.g. ``dataset file-settings``, which also has ``... undo`` / ``... update``).
+    """
+    path_to_command = {
+        tuple(r["command_path"].split()): r["command_id"] for r in _command_records()
+    }
+    prefixes: set[tuple[str, ...]] = set()
+    for tokens in path_to_command:
+        for depth in range(1, len(tokens)):
+            prefixes.add(tokens[:depth])
+    return path_to_command, frozenset(prefixes & path_to_command.keys())
+
+
+def _group_typer(tokens: tuple[str, ...], command_id: str | None) -> typer.Typer:
+    if command_id is not None:
+        # This node is both a group and an invocable command.
+        sub = typer.Typer(
+            cls=_LeafGroup,
+            no_args_is_help=False,
+            invoke_without_command=True,
+            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        )
+        sub.callback()(_build_leaf(command_id, is_group_callback=True))
+        return sub
+    return typer.Typer(
+        help=_GROUP_DESCRIPTIONS.get(tokens[0], f"Commands for {' '.join(tokens)}."),
         no_args_is_help=True,
-        add_completion=True,
-        cls=_EnvelopeGroup,
         context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
     )
 
-    @root.callback()
-    def _root(
-        version: bool = typer.Option(
-            False, "--version", callback=_version_callback, is_eager=True, help="Show version."
-        ),
-    ) -> None:
-        """Root callback holding eager global options."""
 
-    records = [r for r in load_commands() if r.get("disposition") != "alias"]
-    path_to_command: dict[tuple[str, ...], str] = {
-        tuple(r["command_path"].split()): r["command_id"] for r in records
-    }
-    all_paths = set(path_to_command)
-    # A "container command" sits at a node that also has deeper subcommands
-    # (e.g. `dataset file-settings`, which also has `... undo` / `... update`).
-    containers = {
-        tokens
-        for tokens in all_paths
-        if any(other != tokens and other[: len(tokens)] == tokens for other in all_paths)
-    }
-
-    groups: dict[tuple[str, ...], typer.Typer] = {(): root}
-
-    def _make_group(tokens: tuple[str, ...]) -> typer.Typer:
-        command_id = path_to_command.get(tokens)
-        if command_id is not None:
-            # This node is both a group and an invocable command.
-            sub = typer.Typer(
-                cls=_LeafGroup,
-                no_args_is_help=False,
-                invoke_without_command=True,
-                context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
-            )
-            sub.callback()(_build_leaf(command_id, is_group_callback=True))
-        else:
-            sub = typer.Typer(
-                help=_GROUP_DESCRIPTIONS.get(tokens[0], f"Commands for {' '.join(tokens)}."),
-                no_args_is_help=True,
-                context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
-            )
-        return sub
+def _populate(base: tuple[str, ...], group: typer.Typer) -> None:
+    """Register every command below ``base`` (exclusive) on ``group``."""
+    path_to_command, containers = _command_tree()
+    groups: dict[tuple[str, ...], typer.Typer] = {base: group}
 
     def _group_for(tokens: tuple[str, ...]) -> typer.Typer:
         if tokens in groups:
             return groups[tokens]
         parent = _group_for(tokens[:-1])
-        sub = _make_group(tokens)
+        sub = _group_typer(tokens, path_to_command.get(tokens))
         top_level = tokens[0]
         parent.add_typer(
             sub,
@@ -927,15 +976,16 @@ def build_app() -> typer.Typer:
         groups[tokens] = sub
         return sub
 
+    below = {t: c for t, c in path_to_command.items() if t[: len(base)] == base and t != base}
     # Ensure every container group exists (parents before children).
-    for tokens in sorted(containers, key=len):
+    for tokens in sorted((t for t in below if t in containers), key=len):
         _group_for(tokens)
 
     # Register every non-container command as a leaf under its parent group.
     # A command_id with a bespoke, fully-typed callback overrides the generic
     # leaf at the same registered name and path; the manifest-driven surface
     # is otherwise unchanged.
-    for tokens, command_id in sorted(path_to_command.items()):
+    for tokens, command_id in sorted(below.items()):
         if tokens in containers:
             continue
         record = command_by_id(command_id)
@@ -947,11 +997,88 @@ def build_app() -> typer.Typer:
             context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
         )(callback)
 
+
+@cache
+def _top_level_typer(name: str) -> typer.Typer:
+    """Build (once) the Typer sub-app for one top-level command group."""
+    path_to_command, _ = _command_tree()
+    sub = _group_typer((name,), path_to_command.get((name,)))
+    _populate((name,), sub)
+    return sub
+
+
+# Top-level groups are converted to Click on first use. Building the leaf
+# callbacks and ``--help`` text for all ~550 commands, then letting Typer
+# convert every one of them, used to cost most of the CLI's start-up time on
+# every invocation; a run touches one group.
+_LAZY_GROUP_NAMES: list[str] = []
+_LAZY_SETTINGS: dict[str, Any] = {}
+
+
+def _load_top_level_group(name: str) -> Any:
+    from typer.models import TyperInfo
+
+    info = TyperInfo(
+        _top_level_typer(name),
+        name=name,
+        help=_GROUP_DESCRIPTIONS.get(name, f"Commands for {name}."),
+        rich_help_panel=_ROOT_HELP_PANELS.get(name),
+    )
+    return typer.main.get_group_from_info(info, **_LAZY_SETTINGS)
+
+
+def build_app() -> typer.Typer:
+    """Construct the Typer command tree from the command manifests.
+
+    Top-level leaves (``doctor``, ``version``, ...) are registered here; every
+    top-level group is materialised by :class:`_EnvelopeGroup` on demand.
+    """
+    root = typer.Typer(
+        name="mammoth",
+        help=(
+            "Command-line interface for the Mammoth Analytics platform.\n\n"
+            "Start with 'mammoth doctor' to check access, 'mammoth schema find QUERY' "
+            "to locate a command, and 'mammoth schema get COMMAND_ID' for its full input schema."
+        ),
+        no_args_is_help=True,
+        add_completion=True,
+        cls=_EnvelopeGroup,
+        context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+    )
+
+    @root.callback()
+    def _root(
+        version: bool = typer.Option(
+            False, "--version", callback=_version_callback, is_eager=True, help="Show version."
+        ),
+    ) -> None:
+        """Root callback holding eager global options."""
+
+    path_to_command, containers = _command_tree()
+    top_names = sorted({tokens[0] for tokens in path_to_command})
+    lazy: list[str] = []
+    for name in top_names:
+        if (name,) in containers or (name,) not in path_to_command:
+            lazy.append(name)
+            continue
+        command_id = path_to_command[(name,)]
+        root.command(
+            name=name,
+            help=_command_help(command_id, command_by_id(command_id)),
+            rich_help_panel=_ROOT_HELP_PANELS.get(name),
+            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        )(BESPOKE.get(command_id) or _build_leaf(command_id))
+    _LAZY_GROUP_NAMES[:] = lazy
+    _LAZY_SETTINGS.update(
+        pretty_exceptions_short=root.pretty_exceptions_short,
+        rich_markup_mode=root.rich_markup_mode,
+        suggest_commands=root.suggest_commands,
+    )
     return root
 
 
 def registered_command_paths() -> set[str]:
-    """Return every registered command path by walking the built Typer tree.
+    """Return every registered command path by walking the built Typer trees.
 
     Container commands (a node that is both a group and invocable) are counted
     by their own path as well as their subcommands.
@@ -965,14 +1092,20 @@ def registered_command_paths() -> set[str]:
                 paths.add(" ".join((*prefix, name)))
         for group in instance.registered_groups:
             sub = group.typer_instance
-            if sub is None or not group.name:
+            name = group.name
+            if sub is None or not name:
                 continue
-            node = (*prefix, group.name)
-            if getattr(sub.info, "invoke_without_command", False) and sub.registered_callback:
+            node = (*prefix, name)
+            if sub.registered_callback is not None:
                 paths.add(" ".join(node))
             walk(sub, node)
 
-    walk(build_app(), ())
+    walk(app, ())
+    for name in _LAZY_GROUP_NAMES:
+        sub = _top_level_typer(name)
+        if sub.registered_callback is not None:
+            paths.add(name)
+        walk(sub, (name,))
     return paths
 
 
@@ -987,7 +1120,9 @@ def _root_click_command() -> Any:
     the tree is fixed for the process lifetime (:data:`app` is built once at
     import time).
     """
-    return typer.main.get_command(app)
+    root: Any = typer.main.get_command(app)
+    root.commands  # noqa: B018 -- materialise every lazy top-level group
+    return root
 
 
 def command_option_names(command_path: str) -> set[str]:

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

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.29
+version: 2.0.31
 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.31}/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.31}/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.31}/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.29 → mammoth_cli-2.0.31}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/exports.md

@@ -3,10 +3,13 @@
 ```bash
 mammoth schema find "view export"
 mammoth schema get view.export.csv
-mammoth view export csv VIEW_ID --project PROJECT_ID
+mammoth view export csv VIEW_ID --project PROJECT_ID --input '{"dataset_id": DATASET_ID, "output_path": "out.csv"}'
 mammoth view export list VIEW_ID DATASET_ID --project PROJECT_ID
 ```
 
+`view export csv` takes one positional (the view); `dataset_id` and
+`output_path` go in `--input`. It is a download, not a pipeline step.
+
 If the export or its source dataset/view is requested as a deliverable, mark
 both as retained before starting. Wait/reconcile returned jobs. Verify local
 artifact headers, rows and hash;

{mammoth_cli-2.0.29 → mammoth_cli-2.0.31}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/need-action.md

@@ -30,9 +30,13 @@ mammoth dataset file-settings update DATASET_ID --project PROJECT_ID \
 ```
 
 The response is a job (`operation: "understand_csv"`). Poll `dataset get`
-until `status` leaves `need_action`; it normally reaches `ready` within a few
-seconds, after which `view list` returns the generated view and typed
-transforms can proceed. If the status becomes `error`, read `status_info`
+(the record is under `data.dataset`, so read `data.dataset.status`) until
+the status leaves `need_action`. It usually reaches `ready` within seconds;
+on prague an ISO `YYYY-MM-DD` column was flagged ambiguous and took about
+three minutes, so poll for up to five minutes before treating it as stuck.
+Then `view list` returns the generated view and typed transforms can
+proceed. Which environments ask differs: release processed the same file
+straight to `ready`. If the status becomes `error`, read `status_info`
 and stop; do not retry with guessed settings.
 
 ## All-text CSV: `ready` without a view

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

@@ -0,0 +1,73 @@
+# 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
+```
+
+A dry run is a full process with the same reads as the real run. On a
+hosted environment budget roughly 2 s per request (about 0.7 s of it TLS
+setup from a cold process, the rest server time), so `view task list` →
+`--dry-run` → write costs about 30–40 s per pipeline step. That is the
+price of the procedure, not a hang; do not shorten `--timeout` below the
+default to speed it up.
+
+## 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.31}/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.31}/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]: