mammoth-cli 2.0.42__tar.gz → 2.0.44__tar.gz

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.42
+Version: 2.0.44
 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.42 → mammoth_cli-2.0.44}/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.42"
+__version__ = "2.0.44"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/app.py

@@ -384,7 +384,7 @@ class _EnvelopeGroup(TyperGroup):
             argv = kwargs.get("args")
             if argv is None:
                 argv = args[0] if args else None
-            self._render_usage_error(error, argv)
+            self.render_usage_error(error, argv)
             raise SystemExit(getattr(error, "exit_code", EXIT_USAGE)) from None
         except _ABORT_ERRORS:
             typer.echo("Aborted!", err=True)
@@ -395,7 +395,7 @@ class _EnvelopeGroup(TyperGroup):
         # in-process test runner observe the exit status as before.
         raise SystemExit(result if isinstance(result, int) else 0)
 
-    def _render_usage_error(self, error: Any, argv: Sequence[str] | None) -> None:
+    def render_usage_error(self, error: Any, argv: Sequence[str] | None) -> None:
         """Emit a usage error as the JSON envelope (machine) or Click prose (human).
 
         A *missing required argument* is reported with the stable

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.0.42
+version: 2.0.44
 description: "Use Mammoth Analytics from a terminal: install or authenticate the CLI, discover its live command contract, and safely manage projects, data, views, pipelines (join, merge, pivot, filter, clean), dashboards, exports, and handoffs."
 ---
 
@@ -31,7 +31,9 @@ mammoth project ensure 'PROJECT NAME'   # get-or-create; becomes the active proj
 ```
 
 `doctor` failing is a precondition failure, not a reason to try the business
-command anyway. Production is the `app` endpoint; use `release` only when the
+command anyway. When the connection check fails with a 502, 504 or timeout,
+`mammoth doctor --input '{"wait": 300}'` probes again for up to that many
+seconds; go on only when it passes. Production is the `app` endpoint; use `release` only when the
 task names it, and check `meta.profile`/`auth status` `endpoint` match the
 intended environment before doing anything. If no profile has credentials,
 tell the operator to run `mammoth auth login` in their own terminal (add
@@ -173,6 +175,10 @@ your report. If no column links the files, ask before you combine them.
   "limit": 50}`.
 - A timeout, exit 7 or interruption does not prove failure; reconcile an
   `outcome_unknown` (`job get`, `view task list`) before replaying.
+- Before you report, run `mammoth project check PROJECT_ID`. Its `to_report`
+  has one line for each open finding in every view and dashboard (blanks,
+  text numbers, money not shown, columns a dashboard cannot see). Fix each
+  one, or give it one line in the report.
 - Run the [report checklist](references/report-checklist.md) before stating
   a number or calling a step done. When files here disagree,
   [capabilities](references/capabilities.md) wins over a recipe, and a recipe

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/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 556 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 557 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.
 
 Status meanings:
 

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/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 556; 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 557; 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:
 
@@ -31,7 +31,7 @@ Load only the applicable domain file:
 - [log](commands/log.md) — 2 published commands
 - [notification](commands/notification.md) — 5 published commands
 - [parameter](commands/parameter.md) — 14 published commands
-- [project](commands/project.md) — 19 published commands
+- [project](commands/project.md) — 20 published commands
 - [report](commands/report.md) — 1 published commands
 - [schedule](commands/schedule.md) — 5 published commands
 - [schema](commands/schema.md) — 3 published commands

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/project.md

@@ -22,6 +22,16 @@ Result: `ProjectBulkUpdateResult`; mutation `high_impact`, confirmation `confirm
 
 Status on release: ran once on CLI 2.0.15 — re-verification 2026-09-18: exit 0 on release with CLI 2.0.15. Fix held: body accepted as ProjectsPatch naming project_id in every value item; confirmation named the workspace scope (message: 'bulk-update roles in projects 23 of workspace 4', hint 'Pass --con…
 
+### `project.check`
+
+Run: `mammoth project check`. Exact input fields: `mammoth schema get project.check`.
+
+Example: `mammoth project check 123`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ProjectCheckResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.
+
 ### `project.checkpoint.list`
 
 Run: `mammoth project checkpoint list`. Exact input fields: `mammoth schema get project.checkpoint.list`.

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/dashboards.md

@@ -99,7 +99,8 @@ mammoth view transform math VIEW_ID --project PROJECT_ID \
   are in your report.
 - `create-blank`, `canvas save` and `pages add` return `deliverable_check`:
   `money_not_shown` (with the `math` command in `fix`), `unit_price_summed`,
-  and one `blank_values` entry for each column on the board that has blanks.
+  `columns_not_on_dashboard` (view columns added after the dashboard was
+  made, with the `create-blank` command in `fix`), and one `blank_values` entry for each column on the board that has blanks.
   Fix each warning, or say in your report why you kept it.
 
 **Read the bindings back, then the numbers.** `dashboard canvas get` returns

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/bundled_skill/mammoth-cli/references/recovery.md

@@ -36,7 +36,7 @@ these commands are not blanket permission to replay a mutation.
 | `4DASH012 DASHBOARD_LEGACY_CREATION_RETIRED` (HTTP 409) from `dashboard create` | legacy engine retired | `dashboard create-blank` or `dashboard v3 generate` |
 | `4GENR001 ... params.data` (HTTP 400) from `dashboard pdf export` | route needs a browser-rendered payload | not available from the CLI; report it, do not retry with `{"data": {}}` |
 | `'destination'` KeyError in a `view export create` job with handler_type csv_file | generic export route is broken for CSV on release | use `view export csv` |
-| `timeout` / `outcome_unknown` (exit 7) | the request may have completed | `job get JOB_ID` if you have one, else re-list the resource (`dataset list`, `view task list VIEW_ID DATASET_ID`) before any replay |
+| `timeout` / `outcome_unknown` (exit 7) | the request may have completed | run the envelope's `recovery_commands` first: `job get JOB_ID`, `project get ID` after a delete (repeat until `resource_not_found`), `dashboard list` after `create-blank` (look for your title), `dashboard canvas get ID` after a canvas or pages write. Else re-list the resource (`dataset list`, `view task list VIEW_ID DATASET_ID`) before any replay |
 | HTTP 502 / connection errors on every command | backend outage | `mammoth doctor`; wait and re-run doctor until it succeeds; do not replay mutations blindly |
 
 Every error envelope from CLI 2.0.18 carries `error.log_ref` `{file, run_id}`.

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/bundled_skill/mammoth-cli/references/report-checklist.md

@@ -8,7 +8,7 @@ Every "yes" must point at a command you ran in this task and its response.
 | State rows in and rows out for every step that can change row count (filter, discard-duplicates, join, limit, unnest, pivot) | `view data get` or `view get` (`row_count`) before and after the step, or the `view data get` around a set-values |
 | Read back every value-changing transform | `view data get VIEW_ID DATASET_ID` (full page; `view data query` with `limit`/`condition` for a slice) after the job reached `success`; the sample shows the intended change and nothing else changed |
 | No measure column is all-zero, all-null, or all one value after a transform | inspect the readback sample; an all-`0` / all-`Unknown` column means the condition or column mapping was wrong, not that the data is like that |
-| Decide on every blank the deliverable uses | one report line for each `blank_values` entry (from the upload, a data read or `deliverable_check`), in every view: the column, the count, and filled, filtered, or kept and why. Kept is a decision only when you write it down |
+| Decide on every blank the deliverable uses | one report line for each `blank_values` entry (`project check` lists them all: from every view and dashboard): the column, the count, and filled, filtered, or kept and why. Kept is a decision only when you write it down |
 | A join states its match rate and explains unmatched rows | row count before/after, `IS_EMPTY` filter count on a right-side column, and the key columns named exactly as both view schemas show them |
 | Group counts add up | Σ of per-group counts from a pivot/crosstab equals the source row count (or nulls in the group key explain the difference) |
 | Every job you submitted reached a terminal state | `job get JOB_ID` shows `success`; report anything else as failed/unknown, not done |

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/commands/dashboard.py

@@ -43,6 +43,7 @@ from mammoth_cli.services.dashboard_pages import check_added_pages
 from mammoth_cli.services.dashboard_review import (
     CANVAS_GET,
     NEW_COLUMN_NOTE,
+    columns_not_on_dashboard,
     has_profiles,
     review,
 )
@@ -721,10 +722,21 @@ def _with_deliverable_check(
             if isinstance(view_id, int)
             else None
         )
-        fallback = None
-        if not has_profiles(canvas_doc) and isinstance(view_id, int) and dataset_id is not None:
-            fallback = view_profiles(service, dataset_id, view_id, resolved_project(invocation))
-        warnings = review(canvas_doc, dataset_id, fallback)
+        current = (
+            view_profiles(service, dataset_id, view_id, resolved_project(invocation))
+            if isinstance(view_id, int) and dataset_id is not None
+            else None
+        )
+        if has_profiles(canvas_doc):
+            stale = columns_not_on_dashboard(canvas_doc, current)
+            warnings = stale + [
+                warning
+                for warning in review(canvas_doc, dataset_id)
+                # On a stale board the money advice is the rebuild, not a new column.
+                if not (stale and warning["issue"] in {"money_not_shown", "unit_price_summed"})
+            ]
+        else:
+            warnings = review(canvas_doc, dataset_id, current)
     except Exception:  # noqa: BLE001 -- advice must never fail the authoring step
         return data
     if warnings:

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/commands/doctor.py

@@ -13,6 +13,7 @@ import platform
 import re
 import shlex
 import sys
+import time
 from pathlib import Path
 from typing import Any, cast
 from urllib.parse import urlsplit
@@ -132,6 +133,25 @@ def _nearest_existing(path: Path) -> Path:
     return path
 
 
+#: ``doctor --input '{"wait": N}'``: retry a failing connection for up to N
+#: seconds (capped), probing every ``_WAIT_INTERVAL`` seconds.
+_WAIT_INTERVAL = 15
+_WAIT_MAX = 900
+
+
+def _wait_seconds(invocation: Invocation) -> float:
+    document = invocation.load_input() or {}
+    try:
+        value = float(document.get("wait") or 0)
+    except (TypeError, ValueError):
+        raise CliError(
+            code="invalid_argument",
+            message="wait must be a number of seconds.",
+            hint="mammoth doctor --input '{\"wait\": 300}'",
+        ) from None
+    return max(0.0, min(value, _WAIT_MAX))
+
+
 def doctor(invocation: Invocation) -> HandlerResult:
     """Run environment and connectivity diagnostics.
 
@@ -241,13 +261,30 @@ def doctor(invocation: Invocation) -> HandlerResult:
     connection_ok = False
     connection_detail = "not attempted"
     projects: list[dict[str, Any]] | None = None
+    wait_seconds = _wait_seconds(invocation)
     if auth_ok:
+        started = time.monotonic()
+        retries = 0
         try:
-            with open_service(invocation) as (service, _auth):
-                service.check_connection()
-                projects = _visible_projects(service)
+            while True:
+                try:
+                    with open_service(invocation) as (service, _auth):
+                        service.check_connection()
+                        projects = _visible_projects(service)
+                    break
+                except CliError as error:
+                    # A 502/504 or timeout during an outage: with ``wait``,
+                    # probe again instead of failing on the first try.
+                    remaining = wait_seconds - (time.monotonic() - started)
+                    if not error.retryable or remaining <= 0:
+                        raise
+                    time.sleep(min(_WAIT_INTERVAL, remaining))
+                    retries += 1
+            waited = time.monotonic() - started
             connection_ok = True
-            connection_detail = "authenticated request succeeded"
+            connection_detail = "authenticated request succeeded" + (
+                f" after {retries} retries over {round(waited)}s" if retries else ""
+            )
         except CliError as error:
             diagnostics = _safe_connection_diagnostics(error, debug=invocation.debug)
             connection_detail = diagnostics.pop("detail")

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/commands/project.py

@@ -509,3 +509,80 @@ def project_user_update(invocation: Invocation) -> HandlerResult:
     with open_service(invocation) as (service, auth):
         data = service.call(_symbol(invocation), **kwargs)
     return data, _meta(invocation, auth.workspace_id, project_id)
+
+
+_DATASETS_LIST_SYMBOL = "mammoth.api.datasets.DatasetsAPI.list_all"
+_DASHBOARDS_LIST_SYMBOL = "mammoth.api.dashboards.DashboardsAPI.list"
+
+
+def _report_line(where: str, warning: dict[str, Any]) -> str:
+    column = warning.get("column")
+    subject = f"{where}, column {column}" if column else where
+    return f"{subject}: {warning.get('issue')}. {warning.get('detail', '')}".strip()
+
+
+def project_check(invocation: Invocation) -> HandlerResult:
+    """List what a report on this project must still account for.
+
+    Read-only local composite, run before reporting: for each dataset, the
+    first view's ``column_warnings`` and ``before_dashboard``; for each
+    dashboard, its ``deliverable_check``. ``to_report`` flattens them into
+    one line per finding. Cold-agent evals (2.0.41) left one column's blanks
+    undecided in every run, because the warning sat in an earlier result.
+    """
+    from mammoth_cli.commands.dashboard import _with_deliverable_check
+    from mammoth_cli.commands.view import upload_preview
+
+    project_id = _project_id(invocation)
+    views: list[dict[str, Any]] = []
+    dashboards: list[dict[str, Any]] = []
+    to_report: list[str] = []
+    with open_service(invocation) as (service, auth):
+        listing = service.call(_DATASETS_LIST_SYMBOL, project_id=project_id)
+        datasets = listing.get("datasets", []) if isinstance(listing, dict) else []
+        for dataset in datasets:
+            dataset_id = dataset.get("id") if isinstance(dataset, dict) else None
+            if not isinstance(dataset_id, int):
+                continue
+            preview = upload_preview(service, dataset_id, project_id)
+            if preview is None:
+                continue
+            entry = {
+                "dataset_id": dataset_id,
+                "dataset_name": dataset.get("name"),
+                "view_id": preview["view_id"],
+                "row_count": preview.get("row_count"),
+                "column_warnings": preview.get("column_warnings", []),
+            }
+            if "before_dashboard" in preview:
+                entry["before_dashboard"] = preview["before_dashboard"]
+            views.append(entry)
+            where = f"view {preview['view_id']} ({dataset.get('name')})"
+            to_report += [_report_line(where, w) for w in entry["column_warnings"]]
+        boards = service.call(_DASHBOARDS_LIST_SYMBOL, project_id=project_id)
+        for board in boards if isinstance(boards, list) else []:
+            dashboard_id = board.get("id") if isinstance(board, dict) else None
+            if not isinstance(dashboard_id, int):
+                continue
+            checked = _with_deliverable_check(
+                invocation, service, auth, {"dashboard_id": dashboard_id}, {"id": dashboard_id}
+            )
+            check = checked.get("deliverable_check") if isinstance(checked, dict) else None
+            warnings = check.get("warnings", []) if isinstance(check, dict) else []
+            dashboards.append(
+                {"id": dashboard_id, "title": board.get("title"), "warnings": warnings}
+            )
+            to_report += [_report_line(f"dashboard {dashboard_id}", w) for w in warnings]
+        meta = _meta(invocation, auth.workspace_id, project_id)
+    return {
+        "project_id": project_id,
+        "views": views,
+        "dashboards": dashboards,
+        "to_report": to_report,
+        "note": (
+            "Before you report: fix each finding, or give it one line in the report "
+            "(what you did and why). A finding you do not mention is a miss."
+            if to_report
+            else "Nothing open in the views or dashboards."
+        ),
+    }, meta

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/commands/registry.py

@@ -205,6 +205,7 @@ HANDLERS: dict[str, Handler] = {
     # project family (read-only)
     "project.list": project_cmd.project_list,
     "project.get": project_cmd.project_get,
+    "project.check": project_cmd.project_check,
     "project.pending-changes": project_cmd.project_pending_changes,
     "project.resource-status": project_cmd.project_resource_status,
     "project.resource-dependencies": project_cmd.project_resource_dependencies,

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/context/resolver.py

@@ -12,6 +12,7 @@ overrides no project at all.
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import dataclass
 
 from mammoth_cli.context import credentials, profiles
@@ -23,6 +24,7 @@ from mammoth_cli.errors.envelope import (
     EXIT_USAGE,
     CliError,
 )
+from mammoth_cli.runtime import embedded
 from mammoth_cli.runtime.invocation import Invocation
 
 
@@ -39,6 +41,9 @@ class ExplicitLogin:
         workspace_id: The Mammoth workspace id.
         server_prefix: A one-label server prefix, or None.
         api_token: The ``mm_...`` Bearer token, instead of a key + secret.
+        headers: Extra request headers sent on every API call, after the
+            credential headers so they override them. Set only by an
+            embedding host that forwards its caller's session.
     """
 
     api_key: str | None
@@ -46,6 +51,7 @@ class ExplicitLogin:
     workspace_id: int
     server_prefix: str | None = None
     api_token: str | None = None
+    headers: Mapping[str, str] | None = None
 
 
 @dataclass(frozen=True)
@@ -58,6 +64,7 @@ class ResolvedAuth:
         workspace_id: The Mammoth workspace id.
         base_url: The resolved API base url.
         api_token: The ``mm_...`` Bearer token, or None with a key + secret.
+        headers: Extra request headers from an embedding host, or None.
     """
 
     api_key: str | None
@@ -65,6 +72,7 @@ class ResolvedAuth:
     workspace_id: int
     base_url: str
     api_token: str | None = None
+    headers: Mapping[str, str] | None = None
 
 
 def not_authenticated_error() -> CliError:
@@ -110,7 +118,8 @@ def resolve_auth(
     """Resolve credentials, workspace id, and base url for one invocation.
 
     Credentials come from an explicit login (a secure prompt or ``--input``
-    document handed to :func:`resolve_auth` by ``auth login``), otherwise from
+    document handed to :func:`resolve_auth` by ``auth login``, or the login of
+    the current embedded call, :mod:`mammoth_cli.runtime.embedded`), otherwise from
     the selected or ``--profile`` saved profile. There is no environment
     credential path; ``mammoth auth login`` is the only way to authenticate.
 
@@ -126,6 +135,8 @@ def resolve_auth(
             ``invalid_workspace_id`` when the resolved workspace id is not a
             positive integer; endpoint errors from :func:`resolve_base_url`.
     """
+    if explicit_login is None and (call := embedded.current()) is not None:
+        explicit_login = call.login
     if explicit_login is not None:
         base_url = _endpoint(explicit_login.server_prefix)
         return ResolvedAuth(
@@ -134,6 +145,7 @@ def resolve_auth(
             workspace_id=_require_positive_workspace(explicit_login.workspace_id, source="login"),
             base_url=base_url,
             api_token=explicit_login.api_token,
+            headers=explicit_login.headers,
         )
 
     profile_name = invocation.profile or profiles.get_selected()

mammoth_cli-2.0.44/mammoth_cli/embed.py

@@ -0,0 +1,99 @@
+"""Run one CLI command in-process and return its envelope.
+
+For a host (for example a server-side agent) that runs commands for its own
+signed-in users. Each call carries its own login, is forced to machine output
+and no prompts, writes nothing to stdout or stderr, and returns the success or
+error envelope as a dict. Calls are safe to run concurrently in threads: the
+login and the captured envelope live in a context variable
+(:mod:`mammoth_cli.runtime.embedded`), and the update check, the run log and
+saved profiles are not used.
+
+Example::
+
+    from mammoth_cli.context.resolver import ExplicitLogin
+    from mammoth_cli.embed import invoke
+
+    login = ExplicitLogin(
+        api_key=None, api_secret=None, workspace_id=7, api_token="...",
+        server_prefix="app", headers={"Cookie": "..."},
+    )
+    envelope = invoke(["project", "list"], login=login)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from mammoth_cli.app import _ABORT_ERRORS, _USAGE_ERRORS, _root_click_command
+from mammoth_cli.context.resolver import ExplicitLogin
+from mammoth_cli.errors.envelope import EXIT_API, EXIT_INTERRUPT, EXIT_USAGE, CliError
+from mammoth_cli.runtime import embedded
+
+
+def invoke(
+    args: Sequence[str],
+    *,
+    login: ExplicitLogin,
+    project_id: int | None = None,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Run ``mammoth <args>`` as ``login`` and return its envelope.
+
+    Args:
+        args: The command line after ``mammoth``, for example
+            ``["view", "data", "get", "12"]``.
+        login: The credentials, endpoint and extra headers for this call.
+        project_id: The active project, sent as ``--project`` unless ``args``
+            already names one.
+        timeout: Per-request timeout in seconds, sent as ``--timeout`` unless
+            ``args`` already sets one.
+
+    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)
+    call = embedded.EmbeddedCall(login=login)
+    token = embedded.enter(call)
+    try:
+        _run(argv)
+    finally:
+        embedded.leave(token)
+    if call.envelopes:
+        return call.envelopes[-1]
+    return _error("no_output", "This command printed text only (help or version).", EXIT_USAGE)
+
+
+def _argv(args: Sequence[str], *, project_id: int | None, timeout: float | None) -> list[str]:
+    """``args`` plus the options an embedded call always runs with."""
+    argv = list(args)
+    if project_id is not None and not _has_option(argv, "--project"):
+        argv += ["--project", str(project_id)]
+    if timeout is not None and not _has_option(argv, "--timeout"):
+        argv += ["--timeout", str(timeout)]
+    # Last, so they win over any output or input option in ``args``.
+    return [*argv, "--output", "json", "--no-input"]
+
+
+def _has_option(argv: Sequence[str], name: str) -> bool:
+    return any(token == name or token.startswith(f"{name}=") for token in argv)
+
+
+def _run(argv: list[str]) -> None:
+    """Run the command; every outcome ends as a captured envelope."""
+    root = _root_click_command()
+    try:
+        root.main(args=argv, prog_name="mammoth", standalone_mode=False)
+    except _USAGE_ERRORS as error:
+        root.render_usage_error(error, argv)
+    except _ABORT_ERRORS:
+        embedded.capture(_error("aborted", "The command was aborted.", EXIT_INTERRUPT))
+    except SystemExit:
+        return
+    except Exception as exc:  # noqa: BLE001 -- the host gets an envelope, never a traceback
+        embedded.capture(_error("internal_error", f"{type(exc).__name__}: {exc}", EXIT_API))
+
+
+def _error(code: str, message: str, exit_status: int) -> dict[str, Any]:
+    return CliError(code=code, message=message, exit_status=exit_status).to_envelope()

mammoth_cli-2.0.44/mammoth_cli/runtime/embedded.py

@@ -0,0 +1,56 @@
+"""Per-call state for an in-process (embedded) invocation.
+
+:func:`mammoth_cli.embed.invoke` runs a command inside a host process that may
+run several commands at once, each for a different user. The login and the
+captured envelope therefore live in a :class:`contextvars.ContextVar`, never in
+``os.environ`` or a profile file: each thread (or task) sees only its own.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mammoth_cli.context.resolver import ExplicitLogin
+
+
+@dataclass
+class EmbeddedCall:
+    """The login for one embedded call and the envelope it produced."""
+
+    login: ExplicitLogin
+    envelopes: list[dict[str, Any]] = field(default_factory=list)
+
+
+_CURRENT: ContextVar[EmbeddedCall | None] = ContextVar("mammoth_cli_embedded", default=None)
+
+
+def current() -> EmbeddedCall | None:
+    """The embedded call running in this context, or None for a normal CLI run."""
+    return _CURRENT.get()
+
+
+def active() -> bool:
+    """Whether this context runs an embedded call."""
+    return _CURRENT.get() is not None
+
+
+def capture(envelope: dict[str, Any]) -> bool:
+    """Keep ``envelope`` for the embedded caller; False when not embedded."""
+    call = _CURRENT.get()
+    if call is None:
+        return False
+    call.envelopes.append(envelope)
+    return True
+
+
+def enter(call: EmbeddedCall) -> Any:
+    """Make ``call`` current; returns the token for :func:`leave`."""
+    return _CURRENT.set(call)
+
+
+def leave(token: Any) -> None:
+    """Restore the context that was current before :func:`enter`."""
+    _CURRENT.reset(token)

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/runtime/executor.py

@@ -18,9 +18,10 @@ import typer
 
 from mammoth_cli.errors.envelope import EXIT_USAGE, CliError
 from mammoth_cli.output.envelope import Meta, Result
+from mammoth_cli.output.normalize import normalize
 from mammoth_cli.output.policy import MACHINE_OUTPUTS, VALID_OUTPUTS
 from mammoth_cli.output.render import render
-from mammoth_cli.runtime import updates
+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
@@ -98,6 +99,8 @@ def emit_success(
         update_available=update_available,
     )
     envelope = Result(data=data, meta=meta).to_envelope()
+    if embedded.capture(normalize(envelope)):
+        return
     render(envelope, output=output)
 
 
@@ -113,6 +116,8 @@ def emit_error(error: CliError, *, machine: bool, output: str = "json") -> None:
         output: The selected machine mode. Only ``ndjson`` selects lifecycle
             framing; all other machine errors retain the JSON envelope.
     """
+    if embedded.capture(normalize(error.to_envelope())):
+        return
     if machine:
         render(
             error.to_envelope(),
@@ -237,7 +242,7 @@ def _sync_skill_installs(command_id: str, output: str) -> None:
 
 def _open_run_log(command_id: str, invocation: Invocation | None) -> RunLog | None:
     """Open the run log for ``invocation``; never let logging break a command."""
-    if invocation is None:
+    if invocation is None or embedded.active():
         return None
     try:
         return RunLog.start(

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/runtime/session.py

@@ -21,6 +21,7 @@ from mammoth_cli.context.resolver import ResolvedAuth, resolve_auth, resolve_pro
 from mammoth_cli.errors.envelope import missing_project_error
 from mammoth_cli.manifest.loader import command_by_id
 from mammoth_cli.output.policy import resolve_policy
+from mammoth_cli.runtime import embedded
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.services import factory
 from mammoth_cli.services.protocol import MammothService
@@ -101,6 +102,10 @@ def resolved_project(invocation: Invocation) -> int | None:
     Returns:
         The resolved project id, or None when none is set.
     """
+    if embedded.active():
+        # An embedded call has no profile: the host's saved profiles belong to
+        # the host's OS user, not to the user the call runs for.
+        return invocation.project
     profile_name = invocation.profile or profiles.get_selected()
     return resolve_project(invocation, profiles.get_profile(profile_name))
 

{mammoth_cli-2.0.42 → mammoth_cli-2.0.44}/mammoth_cli/runtime/updates.py

@@ -33,6 +33,7 @@ from typing import Any
 import platformdirs
 
 from mammoth_cli import __version__
+from mammoth_cli.runtime import embedded
 
 DISABLE_ENV = "MAMMOTH_NO_UPDATE_CHECK"
 AUTO_UPGRADE_ENV = "MAMMOTH_AUTO_UPGRADE"
@@ -60,8 +61,8 @@ def _flag(name: str) -> bool:
 
 
 def enabled() -> bool:
-    """Whether the check runs at all (``MAMMOTH_NO_UPDATE_CHECK`` unset)."""
-    return not _flag(DISABLE_ENV)
+    """Whether the check runs at all (``MAMMOTH_NO_UPDATE_CHECK`` unset, not embedded)."""
+    return not _flag(DISABLE_ENV) and not embedded.active()
 
 
 def auto_upgrade_enabled() -> bool: