mammoth-cli 2.0.84__tar.gz → 2.0.86__tar.gz

{mammoth_cli-2.0.84 → mammoth_cli-2.0.86}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.84
+Version: 2.0.86
 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.38
+Requires-Dist: mammoth-io<0.8,>=0.7.40
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.0.84 → mammoth_cli-2.0.86}/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,
@@ -867,12 +885,15 @@ def _dry_run(handler: Handler, invocation: Invocation) -> tuple[Any, dict[str, A
     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
+    from mammoth_cli.runtime.dryrun_targets import resolve_targets
+    from mammoth_cli.runtime.session import open_service, resolved_project
 
     try:
         return handler(invocation)
     except DryRunStop as stop:
-        return stop.record, {
+        with open_service(invocation) as (service, _auth):
+            targets = resolve_targets(service, invocation.command_id, stop.record["would_call"])
+        return {**stop.record, "targets": targets}, {
             "profile": invocation.profile,
             "project_id": resolved_project(invocation),
         }

{mammoth_cli-2.0.84 → mammoth_cli-2.0.86}/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.84 → mammoth_cli-2.0.86}/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.84 → mammoth_cli-2.0.86}/mammoth_cli/commands/view.py

@@ -2591,7 +2591,8 @@ def view_export_specialized(invocation: Invocation) -> HandlerResult:
             code="unknown_input_field",
             message=(
                 f"Unknown input field(s) for '{invocation.command_id.replace('.', ' ')}': "
-                f"{', '.join(unknown)}."
+                f"{', '.join(unknown)}. "
+                f"Accepted fields: {', '.join(sorted(allowed - {_DATASET_ID_FIELD}))}."
             ),
             exit_status=EXIT_USAGE,
             hint=f"Accepted fields: {', '.join(sorted(allowed - {_DATASET_ID_FIELD}))}.",

{mammoth_cli-2.0.84 → mammoth_cli-2.0.86}/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.84 → mammoth_cli-2.0.86}/mammoth_cli/errors/envelope.py

@@ -52,6 +52,126 @@ CODE_JOB_FAILED = "job_failed"
 CODE_INTERRUPTED = "interrupted"
 CODE_UNSUPPORTED_CONTRACT = "unsupported_contract"
 
+# User-safe, one-line summaries shown to the customer instead of the model-facing
+# ``message``/``hint``. Plain language only: no command names, ids, field names
+# or jargon. Exactly one entry per error code the CLI can raise;
+# ``tests/unit/test_error_summaries.py`` fails if a raised code has none.
+_S_BAD_REQUEST = "The assistant's request wasn't valid, so it is trying a different way."
+_S_BAD_INPUT = "Some of the information provided couldn't be used."
+_S_SIGN_IN = "The assistant isn't signed in to Mammoth."
+_S_INTERNAL = "The assistant hit an internal problem with this step."
+_S_NOT_FOUND = "Something the assistant looked for couldn't be found."
+_S_MISSING_INFO = "The assistant's request was missing some information."
+_S_SETUP = "A setting needed for this step isn't set up correctly."
+_S_UNAVAILABLE = "This step isn't available right now."
+
+ERROR_SUMMARIES: dict[str, str] = {
+    "aborted": "This step was stopped before it finished.",
+    "ambiguous_resource_identity": (
+        "More than one item matched, so the assistant needs to be more specific."
+    ),
+    "api_error": "Mammoth couldn't complete this step.",
+    "append_schema_mismatch": "The new data doesn't line up with the existing columns.",
+    "append_schema_unreadable": "The columns of the existing data couldn't be read.",
+    "authentication_failed": "Mammoth didn't accept the sign-in for this step.",
+    "authorization_required": "You don't have permission to do this.",
+    "capability_not_found": "The assistant tried something Mammoth doesn't support.",
+    "confirmation_declined": "This step was not confirmed, so nothing was changed.",
+    "confirmation_required": "This step needs your confirmation before it can go ahead.",
+    "confirmation_target_mismatch": (
+        "The confirmation was for a different item, so nothing was changed."
+    ),
+    "conflict": "This conflicts with the current state of your data, so nothing was changed.",
+    "dry_run_targets_unresolvable": (
+        "The assistant couldn't tell exactly which items this would change, so nothing was changed."
+    ),
+    "download_failed": "A download didn't complete.",
+    "duplicate_input_key": _S_BAD_INPUT,
+    "empty_search_query": "The search was empty.",
+    "export_already_exists": "An export with that name already exists.",
+    "incomplete_environment_auth": _S_SIGN_IN,
+    "input_file_not_found": _S_NOT_FOUND,
+    "input_format_required": _S_BAD_INPUT,
+    "input_not_found": _S_NOT_FOUND,
+    "input_too_deep": _S_BAD_INPUT,
+    "input_too_large": "The information provided was too large.",
+    "input_unreadable": _S_BAD_INPUT,
+    "insecure_credential_file": _S_SETUP,
+    "insecure_input_file": _S_BAD_INPUT,
+    "internal_column_name": "That column is internal to Mammoth and can't be used.",
+    "internal_error": _S_INTERNAL,
+    "interrupted": "This step was interrupted before it finished.",
+    "invalid_argument": _S_BAD_REQUEST,
+    "invalid_argument_combination": _S_BAD_REQUEST,
+    "invalid_arguments": _S_BAD_REQUEST,
+    "invalid_condition": "A filter condition wasn't valid.",
+    "invalid_condition_value": "A filter condition used a value that isn't valid.",
+    "invalid_config_value": _S_SETUP,
+    "invalid_credentials": "The sign-in details weren't accepted.",
+    "invalid_input_document": _S_BAD_INPUT,
+    "invalid_input_encoding": _S_BAD_INPUT,
+    "invalid_input_field_type": _S_BAD_INPUT,
+    "invalid_input_format": _S_BAD_INPUT,
+    "invalid_login_document": "The sign-in details weren't valid.",
+    "invalid_option_value": _S_BAD_REQUEST,
+    "invalid_output_mode": _S_BAD_REQUEST,
+    "invalid_profile_name": _S_SETUP,
+    "invalid_project_id": "The project couldn't be identified.",
+    "invalid_resource_context": _S_BAD_REQUEST,
+    "invalid_server_prefix": _S_SETUP,
+    "invalid_storage_mode": _S_SETUP,
+    "invalid_workspace_id": "The workspace couldn't be identified.",
+    "job_failed": "A background task didn't finish successfully.",
+    "keyring_unavailable": _S_SETUP,
+    "keyring_unresponsive": _S_SETUP,
+    "login_input_required": _S_SIGN_IN,
+    "missing_argument": _S_MISSING_INFO,
+    "missing_field": _S_MISSING_INFO,
+    "no_output": "This step didn't return anything.",
+    "nonfinite_input_number": _S_BAD_INPUT,
+    "not_authenticated": _S_SIGN_IN,
+    "not_implemented": _S_UNAVAILABLE,
+    "outcome_unknown": "It isn't clear whether this step went through. Check before trying again.",
+    "pipeline_changed": "The pipeline was changed by someone else while this step ran.",
+    "pipeline_reference_error": "A step in the pipeline refers to something that no longer exists.",
+    "profile_not_found": _S_SETUP,
+    "profile_write_failed": _S_SETUP,
+    "project_required": "No project has been chosen for this step.",
+    "pypi_response_invalid": "An update check didn't return a usable answer.",
+    "pypi_unreachable": "An update check couldn't connect.",
+    "resource_identity_required": "The assistant needs to say which item it means.",
+    "resource_not_found": _S_NOT_FOUND,
+    "retryable_error": "Mammoth was temporarily unavailable. Trying again may work.",
+    "schema_not_found": _S_NOT_FOUND,
+    "sdk_symbol_unresolved": _S_INTERNAL,
+    "skill_conflict": _S_SETUP,
+    "task_runtime_error": "A background task hit an error while running.",
+    "timeout": "This step took too long. It may still be running.",
+    "too_many_goals": _S_BAD_REQUEST,
+    "unexpected_argument": _S_BAD_REQUEST,
+    "unknown_agent": _S_SETUP,
+    "unknown_column": "A column the assistant referred to doesn't exist.",
+    "unknown_config_key": _S_SETUP,
+    "unknown_input_field": _S_BAD_REQUEST,
+    "unknown_option": _S_BAD_REQUEST,
+    "unknown_scope": _S_SETUP,
+    "unsupported_contract": _S_UNAVAILABLE,
+    "unsupported_profile_base_url": _S_SETUP,
+    "unsupported_shell": _S_UNAVAILABLE,
+    "upgrade_failed": "The update didn't complete.",
+    "usage_error": _S_BAD_REQUEST,
+    "view_in_draft": "This view is still a draft and can't be used yet.",
+}
+
+#: Shown for a code with no entry (a runtime backstop only; the exhaustiveness
+#: test keeps every raised code out of this path).
+DEFAULT_ERROR_SUMMARY = "Something went wrong with this step."
+
+
+def user_summary(code: str) -> str:
+    """The user-safe one-line summary for an error code."""
+    return ERROR_SUMMARIES.get(code, DEFAULT_ERROR_SUMMARY)
+
 
 @dataclass
 class CliError(Exception):
@@ -77,6 +197,7 @@ class CliError(Exception):
     def to_envelope(self) -> dict[str, Any]:
         error: dict[str, Any] = {
             "code": self.code,
+            "summary": user_summary(self.code),
             "message": self.message,
             "hint": self.hint,
             "details": self.details,

{mammoth_cli-2.0.84 → mammoth_cli-2.0.86}/mammoth_cli/runtime/dryrun.py

@@ -30,6 +30,11 @@ 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."
+DATAVIEW_GET = "mammoth.api.dataviews.DataviewsAPI.get"
+#: The manifest ``mutation_class`` that marks a command as irreversible: the
+#: only class whose commands the manifest describes as permanent (no undo).
+IRREVERSIBLE_CLASS = "destructive"
+
 NOTE_UNDECLARED = (
     "Stopped before an SDK call the command's manifest does not declare; "
     "nothing was sent for it."
@@ -92,7 +97,8 @@ def make_gate(command_id: str) -> Gate:
     # 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()
+    # The target-name read is a read whichever command asked for it.
+    reads = _read_symbols() | {DATAVIEW_GET}
     view_reads = _read_view_methods()
 
     def stop(symbol: str, arguments: dict[str, Any], *, own: bool, **scope: Any) -> None:
@@ -101,6 +107,7 @@ def make_gate(command_id: str) -> Gate:
                 "dry_run": True,
                 "command": command_id.replace(".", " "),
                 "mutation_class": mutation_class,
+                "irreversible": mutation_class == IRREVERSIBLE_CLASS,
                 "would_call": {
                     "sdk_symbol": symbol,
                     **{key: value for key, value in scope.items() if value is not None},