mammoth-cli 2.0.83__tar.gz → 2.0.85__tar.gz

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.83
+Version: 2.0.85
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.8,>=0.7.37
+Requires-Dist: mammoth-io<0.8,>=0.7.39
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/app.py

@@ -579,6 +579,24 @@ def _shared_option_params() -> list[inspect.Parameter]:
                 ),
             ],
         ),
+        opt(
+            "return_running",
+            False,
+            Annotated[
+                bool,
+                typer.Option(
+                    "--return-running",
+                    help=(
+                        "When a job or pipeline wait runs out, exit 0 with "
+                        "{status: running, job_id or dataview_id, resume} instead of a "
+                        "timeout error; resume with 'mammoth job wait JOB_ID' "
+                        "(reports success, failure or still running; waits at most "
+                        "15 minutes by default)."
+                    ),
+                    rich_help_panel="Context and timeouts",
+                ),
+            ],
+        ),
         opt(
             "pipeline_timeout",
             None,

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities-misc.md

@@ -47,8 +47,6 @@ Ran once: `billing.stripe.history`, `billing.stripe.payment-method.list`, `billi
 | Command | State | Note |
 |---|---|---|
 | `billing.chargebee-plan` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 4SUBS014 'Chargebee plan not found for the given workspace' (workspace 4 is n |
-| `billing.invoice.get` | observed blocker | blocked_missing_fixture: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: billing invoice list answered HTTP 500, so no invoice id was observed |
-| `billing.invoice.list` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 500 with empty body on GET /workspaces/4/subscription_v1/invoices |
 | `billing.stripe.preview-invoice` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 4SUBS037 'Failed to perform subscription operation' |
 | `billing.stripe.upcoming-invoice` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 4SUBS074 'Upcoming invoice not found' (no active Stripe subscription on works |
 | `billing.stripe.usage` | observed blocker | backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 400 5GENR010 UNKNOWN_ERROR 'Unknown error occurred |

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/capabilities.md

@@ -1,7 +1,7 @@
 # What is proven on release
 
 Generated from `docs/release-capability-matrix.json`; do not edit by hand.
-The CLI publishes 567 commands. 455 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
+The CLI publishes 573 commands. 453 of them bind one of the 528 API operations in the matrix; the remainder are local commands (`schema`, `auth`, `doctor`, `log`, ...) or typed variants that share an operation (`view transform *` commands submit through `view.task.add`, except `rename-columns` and `sort`, which set view display properties through `view.update`). 262 bound commands ran once successfully on release, 2 are not supported there, and the rest are untried. Untried is not broken: discover the contract with `mammoth schema get COMMAND_ID`, run it, and treat the structured error envelope as the answer.
 
 Status meanings:
 
@@ -20,8 +20,8 @@ The typed `view transform *` commands all submit through `view.task.add` (`renam
 | `dashboard` | 104 | 81 | 2 | 21 |
 | `view` | 62 | 58 | 0 | 4 |
 | `support` | 45 | 9 | 0 | 36 |
-| `billing` | 23 | 4 | 0 | 19 |
 | `connector` | 22 | 3 | 0 | 19 |
+| `billing` | 21 | 4 | 0 | 17 |
 | `workspace` | 19 | 7 | 0 | 12 |
 | `project` | 17 | 15 | 0 | 2 |
 | `workflow` | 16 | 9 | 0 | 7 |

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/command-index.md

@@ -1,6 +1,6 @@
 # Published CLI command catalog
 
-This generated catalog is a lookup table for every command in the published CLI manifest, currently 574; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
+This generated catalog is a lookup table for every command in the published CLI manifest, currently 573; each entry carries its release status line. It is a command-contract index, not an assertion that every backend/OpenAPI operation has a CLI binding. For an exact local CLI contract, run `mammoth schema get COMMAND_ID`; `mammoth capability list` is an API-binding inventory and can omit typed/local CLI routes. For focused workflows, read the [recipes index](recipes/index.md). Sensitive structured input must come from a private file or pipe; never put secrets in literal argv.
 
 Load only the applicable domain file:
 
@@ -12,7 +12,7 @@ Load only the applicable domain file:
 - [auth](commands/auth.md) — 3 published commands
 - [automation](commands/automation.md) — 7 published commands
 - [batch](commands/batch.md) — 7 published commands
-- [billing](commands/billing.md) — 23 published commands
+- [billing](commands/billing.md) — 22 published commands
 - [browse](commands/browse.md) — 4 published commands
 - [calc](commands/calc.md) — 1 published commands
 - [capability](commands/capability.md) — 3 published commands

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/billing.md

@@ -32,16 +32,6 @@ Result: `BillingInvoiceChargeResult`; mutation `high_impact`, confirmation `conf
 
 Status on release: untried; no live run recorded.
 
-### `billing.invoice.get`
-
-Run: `mammoth billing invoice get`. Exact input fields: `mammoth schema get billing.invoice.get`.
-
-Example: `mammoth billing invoice get 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
-
-Result: `BillingInvoiceGetResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
-
-Status on release: observed blocker — blocked_missing_fixture: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: billing invoice list answered HTTP 500, so no invoice id was observed. Re-check before relying on it.
-
 ### `billing.invoice.list`
 
 Run: `mammoth billing invoice list`. Exact input fields: `mammoth schema get billing.invoice.list`.
@@ -50,7 +40,7 @@ Example: `mammoth billing invoice list`. Placeholders are illustrative; resolve
 
 Result: `BillingInvoiceListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-Status on release: observed blocker — backend_error: The CLI gates this GET behind --yes --confirm WORKSPACE_ID; with confirmation: HTTP 500 with empty body on GET /workspaces/4/subscription_v1/invoices. Re-check before relying on it.
+Status on release: untried; no live run recorded.
 
 ### `billing.stripe.cancel`
 

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/connector.md

@@ -76,7 +76,9 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth connector connection create`. Exact input fields: `mammoth schema get connector.connection.create`.
 
-Example: `mammoth connector connection create sample --input '{"config": {"sample_key": "Status"}}'`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth connector connection create sample --input /private/path/request.json`. Illustrative only: append `--yes` after observing an owned target.
+
+Secret fields: pass the body as `--input FILE` (mode 0600); never inline.
 
 Result: `ConnectorConnectionCreateResult`; mutation `external_effect`, confirmation `yes_always`, wait policy `not_async`.
 
@@ -116,7 +118,9 @@ Status on release: observed blocker — server_error: see sweep report. Re-check
 
 Run: `mammoth connector connection update`. Exact input fields: `mammoth schema get connector.connection.update`.
 
-Example: `mammoth connector connection update sample sample --input '{"credentials": {"sample_key": "Status"}}'`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth connector connection update sample sample --input /private/path/request.json`. Illustrative only: append `--yes` after observing an owned target.
+
+Secret fields: pass the body as `--input FILE` (mode 0600); never inline.
 
 Result: `ConnectorConnectionUpdateResult`; mutation `external_effect`, confirmation `yes_always`, wait policy `not_async`.
 
@@ -200,8 +204,6 @@ Example: `mammoth connector list`. Placeholders are illustrative; resolve IDs an
 
 Result: `ConnectorListResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
 
-`is_premium: true` with `is_added: false` means the connector must be enabled by Mammoth sales before this workspace can use it -- not that nobody has set it up yet. Such an item also carries `availability: "premium_not_enabled"` and an `availability_note` saying so. Tell the user why (premium, not enabled here) and offer to contact Mammoth sales; there is no CLI command that enables a premium connector or contacts sales on the user's behalf.
-
 Status on release: ran once on CLI 2.0.18 — fixture-lifecycle sweep 2026-09-19: exit 0 on release with CLI 2.0.18. Listed 42 available connectors (name_key, disp_name, api_type, is_added, is_premium). Single invocation only.
 
 ### `connector.query.generate`

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/jobs-drafts.md

@@ -24,6 +24,11 @@ or wait that job — inspect it rather than submitting the original mutation.
 The `--job-timeout` /
 `--pipeline-timeout` options bound the wait.
 
+With `--return-running` a wait that runs out exits 0 with `{status: running, job_id, resume}`
+(`dataview_id` for a pipeline wait). `mammoth job wait JOB_ID` resumes: it returns
+`{status: success, job_id, result}`, a `job_failed` error with the reason, or the running handle
+again, and waits at most 15 minutes by default.
+
 A transport failure during a mutation without a confirmed job/resource handle
 is `outcome_unknown`. Re-read the exact target and scope before replaying it;
 the operation may already have committed.

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/commands/billing.py

@@ -171,21 +171,10 @@ def billing_invoice_charge(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id, None)
 
 
-def billing_invoice_get(invocation: Invocation) -> HandlerResult:
-    """Get one invoice by id."""
-    invoice_id = _require_int_positional(invocation, "invoice id")
-    with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), invoice_id=invoice_id)
-    return data, _meta(invocation, auth.workspace_id, None)
-
-
 def billing_invoice_list(invocation: Invocation) -> HandlerResult:
-    """List invoices for the workspace."""
-    document = _bound_document(invocation)
-    kwargs: dict[str, Any] = {}
-    _forward_optional(document, kwargs, ("limit", "sort"))
+    """List invoices for the workspace (Stripe billing history)."""
     with open_service(invocation) as (service, auth):
-        data = service.call(_symbol(invocation), **kwargs)
+        data = service.call(_symbol(invocation))
     return data, _meta(invocation, auth.workspace_id, None)
 
 

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/commands/job.py

@@ -30,6 +30,7 @@ from mammoth_cli.runtime.session import open_service
 HandlerResult = tuple[Any, dict[str, Any]]
 
 _WAIT_OPTIONAL = ("timeout", "poll_interval")
+_DASHBOARD_WAIT_SYMBOL = "mammoth.api.dashboards.DashboardsAPI.wait_for_job_by_url"
 
 
 def _symbol(invocation: Invocation) -> str:
@@ -127,20 +128,48 @@ def job_get_many(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id)
 
 
-def job_wait(invocation: Invocation) -> HandlerResult:
-    """Block until one job completes, or raise on failure/timeout.
+def _wait_call(
+    invocation: Invocation, document: dict[str, Any], kwargs: dict[str, Any]
+) -> tuple[str, dict[str, Any]]:
+    """The SDK symbol and arguments for one job wait.
+
+    A ``dashboard_url`` field switches to the URL-scoped wait: jobs dispatched
+    by published-dashboard routes are unreadable through ``GET /jobs/{id}``.
+    """
+    if "dashboard_url" not in document:
+        return _symbol(invocation), kwargs
+    return _DASHBOARD_WAIT_SYMBOL, {**kwargs, "url": document["dashboard_url"]}
+
 
-    The job id is a positional argument; optional ``timeout`` and
-    ``poll_interval`` fields are forwarded from the ``--input`` document when
-    present.
+def _wait_result(job_id: int, job: Any) -> dict[str, Any]:
+    """The ``job wait`` success payload: the job's response, plus what the job was."""
+    data: dict[str, Any] = {"status": "success", "job_id": job_id}
+    if isinstance(job, dict):
+        data.update({key: job[key] for key in ("operation", "path") if job.get(key) is not None})
+        data["result"] = job.get("response", job)
+    else:
+        data["result"] = job
+    return data
+
+
+def job_wait(invocation: Invocation) -> HandlerResult:
+    """Wait for one job and report success, failure, or still running (15 min default).
+
+    The job id is a positional argument; optional ``timeout``, ``poll_interval``
+    and ``dashboard_url`` (a published dashboard's URL slug) fields are read from
+    the ``--input`` document. Success returns ``{status, job_id, result}``; a
+    failed job is a ``job_failed`` error with its reason; a wait that runs out is
+    a ``timeout`` error, or with ``--return-running`` ``{status: running, job_id,
+    resume}``.
     """
     job_id = _require_int_positional(invocation, "job id")
     document = invocation.load_input() or {}
     kwargs: dict[str, Any] = {"job_id": job_id}
     _forward_optional(document, kwargs, _WAIT_OPTIONAL)
+    symbol, kwargs = _wait_call(invocation, document, kwargs)
     try:
         with open_service(invocation) as (service, auth):
-            data = service.call(_symbol(invocation), **kwargs)
+            data = _wait_result(job_id, service.call(symbol, **kwargs))
     except KeyboardInterrupt as exc:
         # Keep the explicit handle even when the polling implementation raises
         # a bare SIGINT.  A caller can inspect/resume it without replaying the

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/commands/registry.py

@@ -566,7 +566,6 @@ HANDLERS: dict[str, Handler] = {
     "billing.chargebee-plan": billing_cmd.billing_chargebee_plan,
     "billing.hosted-page": billing_cmd.billing_hosted_page,
     "billing.invoice.charge": billing_cmd.billing_invoice_charge,
-    "billing.invoice.get": billing_cmd.billing_invoice_get,
     "billing.invoice.list": billing_cmd.billing_invoice_list,
     "billing.stripe.cancel": billing_cmd.billing_stripe_cancel,
     "billing.stripe.checkout-url": billing_cmd.billing_stripe_checkout_url,

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/embed.py

@@ -41,6 +41,8 @@ def invoke(
     project_id: int | None = None,
     timeout: float | None = None,
     pipeline_timeout: float | None = None,
+    job_timeout: float | None = None,
+    return_running: bool = False,
 ) -> dict[str, Any]:
     """Run ``mammoth <args>`` as ``login`` and return its envelope.
 
@@ -54,12 +56,23 @@ def invoke(
             ``args`` already sets one.
         pipeline_timeout: Pipeline wait timeout in seconds, sent as
             ``--pipeline-timeout`` unless ``args`` already sets one.
+        job_timeout: Job wait timeout in seconds, sent as ``--job-timeout``
+            unless ``args`` already sets one.
+        return_running: Send ``--return-running`` so a wait that runs out
+            returns a ``status: running`` handle instead of a timeout error.
 
     Returns:
         The success envelope (``data`` + ``meta``) or the error envelope
         (``error``). A CLI error is returned, never raised.
     """
-    argv = _argv(args, project_id=project_id, timeout=timeout, pipeline_timeout=pipeline_timeout)
+    argv = _argv(
+        args,
+        project_id=project_id,
+        timeout=timeout,
+        pipeline_timeout=pipeline_timeout,
+        job_timeout=job_timeout,
+        return_running=return_running,
+    )
     call = embedded.EmbeddedCall(login=login)
     token = embedded.enter(call)
     try:
@@ -77,6 +90,8 @@ def _argv(
     project_id: int | None,
     timeout: float | None,
     pipeline_timeout: float | None,
+    job_timeout: float | None,
+    return_running: bool,
 ) -> list[str]:
     """``args`` plus the options an embedded call always runs with."""
     argv = list(args)
@@ -86,6 +101,10 @@ def _argv(
         argv += ["--timeout", str(timeout)]
     if pipeline_timeout is not None and not _has_option(argv, "--pipeline-timeout"):
         argv += ["--pipeline-timeout", str(pipeline_timeout)]
+    if job_timeout is not None and not _has_option(argv, "--job-timeout"):
+        argv += ["--job-timeout", str(job_timeout)]
+    if return_running and not _has_option(argv, "--return-running"):
+        argv.append("--return-running")
     # Last, so they win over any output or input option in ``args``.
     return [*argv, "--output", "json", "--no-input"]
 

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/runtime/executor.py

@@ -24,7 +24,7 @@ from mammoth_cli.output.render import render
 from mammoth_cli.runtime import embedded, updates
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.runlog import RunLog
-from mammoth_cli.services.mapping import map_sdk_exception
+from mammoth_cli.services.mapping import map_sdk_exception, running_handle
 
 Producer = Callable[[], tuple[Any, dict[str, Any]]]
 
@@ -193,8 +193,17 @@ def run(
         emit_success(command_id, data, output, update_available=update, **meta_extra)
         updates.emit_hint(update, output=output)
     except CliError as error:
-        fail(error)
-        raise typer.Exit(error.exit_status) from None
+        running = (
+            running_handle(error, command_id)
+            if invocation is not None and invocation.return_running
+            else None
+        )
+        if running is None:
+            fail(error)
+            raise typer.Exit(error.exit_status) from None
+        # --return-running: a wait that ran out is not a failure; hand back the
+        # handle to resume with.
+        emit_success(command_id, running, output, profile=profile)
     except KeyboardInterrupt as exc:
         # Polling can be interrupted after a job handle was observed.  Keep
         # that handle when an SDK exception exposes one; never turn Ctrl-C

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/runtime/invocation.py

@@ -53,6 +53,7 @@ class Invocation:
     timeout: float | None = None
     job_timeout: float | None = None
     pipeline_timeout: float | None = None
+    return_running: bool = False
     color: str = "auto"
     no_input: bool = False
     no_progress: bool = False
@@ -146,7 +147,7 @@ class Invocation:
                 continue
             try:
                 value = float(raw)
-            except (TypeError, ValueError):
+            except TypeError, ValueError:
                 continue
             if value > 0:
                 object.__setattr__(self, key, value)
@@ -228,7 +229,7 @@ class Invocation:
                     resource_dataset = int(resource_dataset)
                     if resource_dataset <= 0:
                         raise ValueError
-                except (TypeError, ValueError):
+                except TypeError, ValueError:
                     raise CliError(
                         code="invalid_resource_context",
                         message="Input field 'dataset_id' must be a positive integer.",
@@ -251,7 +252,7 @@ class Invocation:
                     expected_tasks = int(expected_tasks)
                     if expected_tasks < 0:
                         raise ValueError
-                except (TypeError, ValueError):
+                except TypeError, ValueError:
                     raise CliError(
                         code="invalid_resource_context",
                         message=f"Input field '{TASK_COUNT_FIELD}' must be a non-negative integer.",

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/runtime/session.py

@@ -32,9 +32,17 @@ from mammoth_cli.services.protocol import MammothService
 #: pass ``--timeout 300`` by hand. Reads keep the SDK default.
 DEFAULT_MUTATION_JOB_TIMEOUT = 300.0
 
+#: Wait budget for ``job wait`` / ``job wait-many`` when no timeout was given:
+#: long enough for a big transform, and never unbounded, so a resuming agent
+#: is always told the job's state (success, failure, or still running).
+DEFAULT_JOB_WAIT_TIMEOUT = 900.0
+_JOB_WAIT_COMMANDS = ("job.wait", "job.wait-many")
+
 
 def default_job_timeout(command_id: str) -> float | None:
     """The job-wait timeout for ``command_id`` when none was configured."""
+    if command_id in _JOB_WAIT_COMMANDS:
+        return DEFAULT_JOB_WAIT_TIMEOUT
     record = command_by_id(command_id) or {}
     if record.get("mutation_class", "read") in (None, "read"):
         return None

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/runtime/state.py

@@ -187,6 +187,7 @@ def _read_invocation(command_id: str, resolved_ids: dict[str, Any], base: Invoca
         timeout=base.timeout,
         job_timeout=base.job_timeout,
         pipeline_timeout=base.pipeline_timeout,
+        return_running=base.return_running,
         no_input=True,
         positionals=positionals,
         extra_args=extra_args,

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/services/command_contract.py

@@ -603,6 +603,9 @@ S7_COMMANDS = frozenset(
 # admission, and handler binding agree instead of treating every arbitrary
 # keyword as valid.
 _S7_ADDITIONAL_INPUT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
+    # Published-dashboard jobs are readable only through the URL-scoped job
+    # route; ``job wait`` polls it when the dashboard URL slug is given.
+    "job.wait": (FieldSpec("dashboard_url", required=False, annotation=str | None, default=None),),
     # The GET data route has no server-side page size; the CLI trims the row
     # list so a read-back costs a screen of tokens, not the whole view.
     "view.data.get": (

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/services/mapping.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import re
 import shlex
 from typing import Any
@@ -13,6 +14,7 @@ from mammoth.exceptions import (
     MammothError,
     MammothJobFailedError,
     MammothJobTimeoutError,
+    MammothPipelineTimeoutError,
     MammothValidationError,
     safe_response_body,
 )
@@ -107,6 +109,23 @@ def _job_recovery(job_id: object, *, profile: str | None = None) -> list[str]:
     ]
 
 
+def _pipeline_recovery(exc: MammothPipelineTimeoutError, *, profile: str | None) -> list[str]:
+    scope = f" --project {exc.project_id}" if exc.project_id is not None else ""
+    scope += f" --profile {shlex.quote(profile)}" if profile else ""
+    return [
+        f"mammoth view pipeline get {exc.dataview_id}{scope}",
+        f"mammoth view pipeline wait {exc.dataview_id}{scope}",
+    ]
+
+
+def _observed_job_fields(details: dict[str, Any]) -> dict[str, Any]:
+    """The ``operation``/``path`` of the last observed job, when the server sent them."""
+    observed = details.get("observed_job")
+    if not isinstance(observed, dict):
+        return {}
+    return {key: observed[key] for key in ("operation", "path") if observed.get(key) is not None}
+
+
 _PROJECT_DELETE = re.compile(r"/workspaces/\d+/projects/(\d+)/?$")
 _DASHBOARD_WRITE = re.compile(r"/dashboards/(\d+)(?:/|$)")
 _ENDPOINT_WORKSPACE = re.compile(r"/workspaces/(\d+)")
@@ -168,6 +187,49 @@ def _resource_recovery(
     return []
 
 
+def with_dashboard_scope(error: CliError, dashboard_url: str) -> CliError:
+    """Point a timed-out published-dashboard job's recovery at the URL-scoped route.
+
+    ``GET /jobs/{id}`` answers ``4PERM002`` for these jobs, so the generic
+    ``job get``/``job wait`` recovery would fail; ``job wait`` takes the
+    dashboard URL as an ``--input`` field and polls the URL-scoped route.
+    """
+    job_id = error.details.get("job_id")
+    if error.code != "timeout" or job_id is None:
+        return error
+    document = shlex.quote(json.dumps({"dashboard_url": dashboard_url}))
+    error.details["resume"] = f"mammoth job wait {job_id} --input {document}"
+    error.recovery_commands = [
+        f"mammoth dashboard job-by-url {shlex.quote(dashboard_url)} {job_id}",
+        error.details["resume"],
+    ]
+    return error
+
+
+def running_handle(error: CliError, command_id: str) -> dict[str, Any] | None:
+    """The ``status: running`` payload for a wait that ran out, else ``None``.
+
+    Used by ``--return-running``: a job wait or pipeline wait that timed out is
+    not a failure, so the caller gets the handle to resume with instead.
+    """
+    details = error.details
+    if error.code != "timeout" or "resume" not in details:
+        return None
+    if details.get("phase") == "pipeline" and "dataview_id" in details:
+        handle: dict[str, Any] = {"dataview_id": details["dataview_id"]}
+    elif "job_id" in details:
+        handle = {"job_id": details["job_id"], **_observed_job_fields(details)}
+    else:
+        return None
+    return {
+        "status": "running",
+        **handle,
+        "command": command_id,
+        "waited_seconds": details.get("waited_seconds"),
+        "resume": details["resume"],
+    }
+
+
 def map_sdk_exception(
     exc: BaseException,
     *,
@@ -206,6 +268,21 @@ def map_sdk_exception(
             recovery_commands=["mammoth auth login"],
         )
 
+    if isinstance(exc, MammothPipelineTimeoutError):
+        recovery = _pipeline_recovery(exc, profile=profile)
+        details = dict(exc.details)
+        details["waited_seconds"] = details.get("timeout")
+        details["resume"] = recovery[1]
+        return CliError(
+            code="timeout",
+            message="The view pipeline did not finish before the timeout.",
+            exit_status=EXIT_RETRYABLE,
+            hint="No job is involved; read the view's pipeline state and wait for it to finish.",
+            details=details,
+            retryable=True,
+            recovery_commands=recovery,
+        )
+
     if isinstance(exc, MammothJobTimeoutError):
         job_id = getattr(exc, "job_handle", None) or getattr(exc, "job_id", None)
         details = dict(getattr(exc, "details", {}) or {})
@@ -213,6 +290,10 @@ def map_sdk_exception(
             details.setdefault("job_id", job_id)
         details.setdefault("operation_state", "running")
         details.setdefault("phase", getattr(exc, "phase", None) or "polling")
+        details.update(_observed_job_fields(details))
+        details["waited_seconds"] = details.get("timeout")
+        if job_id is not None:
+            details["resume"] = _job_recovery(job_id, profile=profile)[1]
         return CliError(
             code="timeout",
             message="The operation did not finish before the timeout.",
@@ -226,13 +307,18 @@ def map_sdk_exception(
     if isinstance(exc, MammothJobFailedError):
         details = dict(getattr(exc, "details", {}) or {})
         job_id = getattr(exc, "job_handle", None) or getattr(exc, "job_id", None)
+        details["status"] = "failure"
+        details["reason"] = details.get("failure_reason") or "no reason recorded by the job"
+        details.update(_observed_job_fields(details))
         return CliError(
             code=CODE_JOB_FAILED,
-            message="The Mammoth job failed.",
+            message=f"The Mammoth job failed: {details['reason']}",
             exit_status=EXIT_API,
             hint="Inspect the job response for the failure reason.",
             details=details,
-            recovery_commands=_job_recovery(job_id, profile=profile) if job_id is not None else [],
+            recovery_commands=(
+                _job_recovery(job_id, profile=profile)[:1] if job_id is not None else []
+            ),
         )
 
     if isinstance(exc, MammothAPIError):

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/mammoth_cli/services/sdk_service.py

@@ -32,7 +32,7 @@ from mammoth_cli.runtime import parents
 from mammoth_cli.services.coerce import coerce_arguments
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.dispatch import resolve_sdk_method
-from mammoth_cli.services.mapping import map_sdk_exception
+from mammoth_cli.services.mapping import map_sdk_exception, with_dashboard_scope
 
 #: Largest ``limit`` the projects route accepts (``4GENR007`` above it).
 _PROJECT_MISS = re.compile(r"^Project (ID \d+|'.*') not found\.")
@@ -284,7 +284,10 @@ class SdkMammothService:
                     fetch=lambda job_id, _remaining: dashboards.job_by_url(dashboard_url, job_id),
                 )
         except Exception as exc:
-            raise map_sdk_exception(exc) from exc
+            mapped = map_sdk_exception(exc)
+            if dashboard_url is not None:
+                mapped = with_dashboard_scope(mapped, dashboard_url)
+            raise mapped from exc
 
     def call_view(
         self,

{mammoth_cli-2.0.83 → mammoth_cli-2.0.85}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.83"
+version = "2.0.85"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.7.37,<0.8)",
+    "mammoth-io (>=0.7.39,<0.8)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",