mammoth-cli 2.2.95__tar.gz → 2.2.96__tar.gz

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.95
+Version: 2.2.96
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -16,9 +16,10 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
+Requires-Dist: certifi>=2026.10.19
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.9,>=0.8.48
+Requires-Dist: mammoth-io<0.9,>=0.8.49
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/app.py

@@ -19,6 +19,7 @@ import inspect
 import json
 import re
 import sys
+import threading
 from collections.abc import Callable, Sequence
 from dataclasses import replace
 from difflib import get_close_matches
@@ -1624,6 +1625,10 @@ def _lazy_help_command(command_id: str) -> type[TyperCommand]:
     return LazyHelpCommand
 
 
+#: Guards the lazy builds below. Re-entrant: building a command can build another.
+_BUILD_LOCK = threading.RLock()
+
+
 def _unbuilt_leaf() -> None:
     """Registration placeholder: a lazy leaf takes its real callback from the built command."""
 
@@ -1640,24 +1645,33 @@ def _lazy_leaf_command(command_id: str) -> type[TyperCommand]:
         _built: _ClickCommand | None = None
 
         def _real(self) -> _ClickCommand:
-            if self._built is None:
-                from typer.models import CommandInfo
-
-                info = CommandInfo(
-                    name=self.name,
-                    callback=_build_leaf(command_id),
-                    # The help text is read from this class's lazy ``help`` property; building
-                    # it here would import the contract and schema layers on every run.
-                    help="",
-                    rich_help_panel=self.rich_help_panel,
-                    context_settings=_leaf_context_settings(command_id),
-                )
-                self._built = typer.main.get_command_from_info(
-                    info,
-                    pretty_exceptions_short=_LAZY_SETTINGS["pretty_exceptions_short"],
-                    rich_markup_mode=self.rich_markup_mode,
-                )
-            return self._built
+            built = self._built
+            if built is not None:
+                return built
+            # Double-checked: a host's worker threads may reach a first use together.
+            with _BUILD_LOCK:
+                built = self._built
+                if built is None:
+                    built = self._built = self._build()
+            return built
+
+        def _build(self) -> _ClickCommand:
+            from typer.models import CommandInfo
+
+            info = CommandInfo(
+                name=self.name,
+                callback=_build_leaf(command_id),
+                # The help text is read from this class's lazy ``help`` property; building
+                # it here would import the contract and schema layers on every run.
+                help="",
+                rich_help_panel=self.rich_help_panel,
+                context_settings=_leaf_context_settings(command_id),
+            )
+            return typer.main.get_command_from_info(
+                info,
+                pretty_exceptions_short=_LAZY_SETTINGS["pretty_exceptions_short"],
+                rich_markup_mode=self.rich_markup_mode,
+            )
 
         @property
         def params(self) -> list[_ClickParameter]:
@@ -1919,7 +1933,9 @@ def registered_command_paths() -> set[str]:
     return paths
 
 
-@cache
+_ROOT_COMMAND: Any = None
+
+
 def _root_click_command() -> Any:
     """Build (once) and cache the fully resolved Click command tree.
 
@@ -1928,11 +1944,19 @@ def _root_click_command() -> Any:
     that is expensive enough that recomputing it per lookup made a full sweep
     over every command (see the contract test) take minutes. Cached because
     the tree is fixed for the process lifetime (:data:`app` is built once at
-    import time).
+    import time). Built under a lock, so a host's threads making their first call
+    together share one tree instead of each building their own.
     """
-    root: Any = typer.main.get_command(app)
-    root.commands  # noqa: B018 -- materialise every lazy top-level group
-    return root
+    global _ROOT_COMMAND
+    root = _ROOT_COMMAND
+    if root is not None:
+        return root
+    with _BUILD_LOCK:
+        if _ROOT_COMMAND is None:
+            built: Any = typer.main.get_command(app)
+            built.commands  # noqa: B018 -- materialise every lazy top-level group
+            _ROOT_COMMAND = built
+        return _ROOT_COMMAND
 
 
 def command_option_names(command_path: str) -> set[str]:

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mammoth-cli
-version: 2.2.95
+version: 2.2.96
 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."
 ---
 

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/dashboard-template.md

@@ -66,7 +66,7 @@ Status on release: ran once on CLI 2.0.21 — ergonomics sweep 2026-09-19: exit
 
 Run: `mammoth dashboard template preview`. Exact input fields: `mammoth schema get dashboard.template.preview`.
 
-Example: `mammoth dashboard template preview --input '{"body": {"params": {"source_dashboard_id": 1, "target_dataview_id": 1}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth dashboard template preview --input '{"body": {"params": {"source_dashboard_id": 1}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `DashboardTemplatePreviewResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 
@@ -86,7 +86,7 @@ Status on release: untried; no live run recorded.
 
 Run: `mammoth dashboard template resolve-mapping`. Exact input fields: `mammoth schema get dashboard.template.resolve-mapping`.
 
-Example: `mammoth dashboard template resolve-mapping --input '{"body": {"params": {"source_dashboard_id": 1, "target_dataview_id": 1}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
+Example: `mammoth dashboard template resolve-mapping --input '{"body": {"params": {"source_dashboard_id": 1}}}'`. Placeholders are illustrative; resolve IDs and input from observed reads.
 
 Result: `DashboardTemplateResolveMappingResult`; mutation `benign_mutation`, confirmation `none`, wait policy `not_async`.
 

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/bundled_skill/mammoth-cli/references/machine-output.md

@@ -2,12 +2,15 @@
 
 ## Success envelope (stdout)
 ```json
-{"schema_version":1,"data":<result>,"meta":{"command":"project list","profile":"default","workspace_id":4,"project_id":180}}
+{"schema_version":1,"data":<result>,"meta":{"command":"project list","profile":"default","workspace_id":4,"project_id":180,"exit":0}}
 ```
 
 Compact single-line JSON when stdout is not a terminal (pretty when it is;
 `MAMMOTH_JSON_PRETTY=1` forces pretty). `meta` carries only the keys that have a
-value: `pagination` appears on paged reads, `update_available`
+value: `exit` is the exit status (0, or 1 or 3 for a write whose read-back failed
+or was partial); `stderr` (embedded calls only) holds up to 500 characters a library
+wrote to stderr during the call, and `elapsed_ms` (embedded calls only) its wall time;
+`pagination` appears on paged reads, `update_available`
 (`{"current", "latest", "command"}`) when a newer CLI is on PyPI (checked once
 a day, after a command, never blocking). Run its `command` before starting a
 task, not in the middle of one. `next_commands` appears after a main-flow
@@ -18,7 +21,7 @@ when they fit the task; a write that did not verify has none.
 
 ## Error envelope (stderr)
 ```json
-{"schema_version": 1, "error": {"code": "resource_not_found", "message": "...", "hint": "...", "details": {}, "request_id": null, "retryable": false, "authorization_required": false, "recovery_commands": ["..."], "log_ref": {"file": ".../logs/2026-09-19.jsonl", "run_id": "b6bc6bf6d166"}}}
+{"schema_version": 1, "error": {"code": "resource_not_found", "message": "...", "hint": "...", "details": {}, "request_id": null, "retryable": false, "authorization_required": false, "recovery_commands": ["..."], "exit": 1, "log_ref": {"file": ".../logs/2026-09-19.jsonl", "run_id": "b6bc6bf6d166"}}}
 ```
 
 A mistyped command, option or column carries `details.did_you_mean`: the nearest

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/bundled_skill/mammoth-cli/references/recovery.md

@@ -14,6 +14,7 @@ these commands are not blanket permission to replay a mutation.
 | 2 | project_required | `mammoth context project use ID` or `--project` (in the app: `--project` only) |
 | 2 | confirmation_required | re-run with `--yes` (and `--confirm TARGET`) |
 | 2 | not_available_embedded | the command is not offered in the Mammoth app; use another route |
+| 2 | pending_server_release | the command's route is not on the production server yet (`server_status: pending` in `schema get`); use another route |
 | 6 | conflict | inspect current remote state and resolve it |
 | 7 | `timeout` with a known job | inspect or wait that job; do not replay the mutation |
 | 7 | `outcome_unknown` | reconcile exact target/scope before any replay |

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/commands/capability.py

@@ -13,6 +13,7 @@ from typing import Any
 from mammoth_cli.commands.schema import command_scope
 from mammoth_cli.errors.envelope import is_feature_unavailable
 from mammoth_cli.manifest.loader import command_by_id, load_operations
+from mammoth_cli.runtime import embedded
 from mammoth_cli.services.command_contract import resolve_command_contract
 
 _MAX_FIND_RESULTS = 20
@@ -51,6 +52,7 @@ def capability_entries() -> list[dict[str, Any]]:
                 "canonical_command": command_id,
                 "command_path": command["command_path"] if command else None,
                 "unavailable": is_feature_unavailable(command_id),
+                "server_status": command.get("server_status", "served") if command else None,
                 "sdk_symbol": op.get("sdk_symbol"),
                 "mutation_class": (
                     resolved.effects
@@ -72,6 +74,11 @@ def capability_entries() -> list[dict[str, Any]]:
     return sorted(entries, key=lambda entry: entry["operation_id"])
 
 
+def hidden_pending(entry: dict[str, Any]) -> bool:
+    """Whether an embedded call that opted out of pending commands must not see ``entry``."""
+    return embedded.hides_pending() and entry.get("server_status") == "pending"
+
+
 def get_capability(operation_id: str) -> dict[str, Any] | None:
     for entry in capability_entries():
         if entry["operation_id"] == operation_id:
@@ -156,7 +163,7 @@ def find_capabilities(
                 "sdk_symbol",
             )
         )
-        if entry.get("unavailable"):
+        if entry.get("unavailable") or hidden_pending(entry):
             continue
         candidates = _tokens(text)
         command_id = entry.get("canonical_command")

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/commands/registry.py

@@ -52,7 +52,8 @@ def _version(_: Invocation) -> HandlerResult:
 def _capability_list(_: Invocation) -> HandlerResult:
     from mammoth_cli.commands import capability as capability_cmd
 
-    return capability_cmd.capability_entries(), {}
+    entries = capability_cmd.capability_entries()
+    return [entry for entry in entries if not capability_cmd.hidden_pending(entry)], {}
 
 
 def _capability_get(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/commands/run.py

@@ -54,7 +54,7 @@ from mammoth_cli.runtime import linecapture
 from mammoth_cli.runtime.executor import EXIT_STATUS_META, STREAMED_META
 from mammoth_cli.runtime.input_loader import MAX_INPUT_BYTES
 from mammoth_cli.runtime.invocation import Invocation
-from mammoth_cli.runtime.shared import remembering_auth
+from mammoth_cli.runtime.shared import forget_reads, remembering_auth
 from mammoth_cli.runtime.strict import NEGATIVE_NUMBER
 
 HandlerResult = tuple[Any, dict[str, Any]]
@@ -373,7 +373,7 @@ def execute_line(argv: Sequence[str], command: str = "") -> tuple[int, dict[str,
     if exit_status == 0:
         # Help or version text: the command succeeded and printed no envelope.
         text = {"text": stray[:500]} if stray else None
-        return 0, Result(data=text, meta=Meta(command=command)).to_envelope()
+        return 0, Result(data=text, meta=Meta(command=command, exit=0)).to_envelope()
     silent = CliError(
         code="no_output",
         message="This command printed text only (help or version) and no envelope.",
@@ -490,6 +490,7 @@ def run(invocation: Invocation) -> HandlerResult:
                 spec = parse_line(number, text, defaults, _command_flags)
                 cmd, line_id = spec.cmd, spec.line_id
                 exit_status, envelope = execute_line(spec.argv, spec.cmd)
+                forget_reads()
             except CliError as error:
                 cmd = cmd or _best_effort_cmd(text)
                 exit_status, envelope = error.exit_status, error.to_envelope()
@@ -528,7 +529,7 @@ def run(invocation: Invocation) -> HandlerResult:
         "dry_run": invocation.dry_run,
         "exit": run_exit,
     }
-    meta = Meta(command="run", profile=invocation.profile)
+    meta = Meta(command="run", profile=invocation.profile, exit=run_exit)
     _write(Result(data=summary, meta=meta).to_envelope())
     return None, {STREAMED_META: True, EXIT_STATUS_META: run_exit}
 

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/commands/schema.py

@@ -24,6 +24,8 @@ from typing import Any, cast
 from mammoth_cli.errors.envelope import is_feature_unavailable
 from mammoth_cli.manifest.loader import command_by_id, load_commands, load_operations
 from mammoth_cli.output.normalize import trusted_json_schema
+from mammoth_cli.runtime import embedded
+from mammoth_cli.runtime.local_paths import local_path_fields
 from mammoth_cli.services.argspec import FieldSpec
 from mammoth_cli.services.command_contract import LOCAL_COMMANDS, resolve_command_contract
 from mammoth_cli.services.field_enums import field_enum, with_enum
@@ -33,7 +35,7 @@ from mammoth_cli.services.input_fields import (
     handler_owned_fields,
 )
 from mammoth_cli.services.openapi_types import openapi_body_schema_for, sample_from_schema
-from mammoth_cli.services.positionals import PositionalSpec, resolve_positionals
+from mammoth_cli.services.positionals import LOCAL_PATH, PositionalSpec, resolve_positionals
 from mammoth_cli.services.type_system import is_opaque_mapping, json_schema, sample_value
 
 # Agent examples carry no ``--output json --no-input``: a piped run already
@@ -1225,6 +1227,7 @@ def _accepted_fields(record: dict[str, Any]) -> list[dict[str, Any]] | None:
     body_schema = openapi_body_schema_for(
         tuple(str(item) for item in record.get("operation_ids", []))
     )
+    path_fields = local_path_fields(record["command_id"], record.get("positionals", []))
     return [
         {
             "name": field.name,
@@ -1239,6 +1242,8 @@ def _accepted_fields(record: dict[str, Any]) -> list[dict[str, Any]] | None:
                 and body_schema is not None
                 else json_schema(field.annotation, field.name)
             ),
+            # Only where it applies: a host that cannot read the path refuses the command.
+            **({"kind": LOCAL_PATH} if field.name in path_fields else {}),
         }
         for field in contract.accepted_fields
         if field.name not in excluded
@@ -1263,7 +1268,9 @@ def _compact_accepted_fields(record: dict[str, Any]) -> list[dict[str, Any]] | N
         return None
     compact: list[dict[str, Any]] = []
     for field in fields:
-        item = {key: field[key] for key in ("name", "type", "required", "enum")}
+        item: dict[str, Any] = {
+            key: field[key] for key in ("name", "type", "required", "enum", "kind") if key in field
+        }
         schema = field.get("schema")
         if (
             schema is not None
@@ -2197,6 +2204,7 @@ def _schema_common(record: dict[str, Any]) -> dict[str, Any]:
         else "partially_typed" if opaque_fields else "typed"
     )
     return {
+        "server_status": record.get("server_status", "served"),
         "positionals": _positionals(record["command_id"]),
         "accepted_fields": accepted,
         "input_schema": input_schema,
@@ -2217,10 +2225,15 @@ def _schema_common(record: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _hidden_pending(record: dict[str, Any]) -> bool:
+    """Whether an embedded call that opted out of pending commands must not see ``record``."""
+    return embedded.hides_pending() and record.get("server_status") == "pending"
+
+
 def schema_entries() -> list[dict[str, Any]]:
     entries: list[dict[str, Any]] = []
     for record in load_commands():
-        if record.get("disposition") == "alias":
+        if record.get("disposition") == "alias" or _hidden_pending(record):
             continue
         entries.append(
             {
@@ -2247,6 +2260,7 @@ def schema_entries() -> list[dict[str, Any]]:
 _BRIEF_SCHEMA_KEYS = (
     "command_id",
     "command_path",
+    "server_status",
     "positionals",
     "accepted_fields",
     "agent_example",
@@ -2278,6 +2292,7 @@ def schema_index(family: str | None = None) -> dict[str, Any]:
                 "command_path": entry["command_path"],
                 "mutation_class": entry["mutation_class"],
                 "confirmation": entry["confirmation"],
+                "server_status": entry["server_status"],
             }
             for entry in entries
             if entry["command_path"].split()[0] == wanted
@@ -2428,7 +2443,7 @@ def find_schemas(
     for record in load_commands():
         if record.get("disposition") == "alias":
             continue
-        if is_feature_unavailable(str(record["command_id"])):
+        if is_feature_unavailable(str(record["command_id"])) or _hidden_pending(record):
             continue
         command_id = str(record["command_id"])
         command_path = str(record["command_path"])
@@ -2490,6 +2505,7 @@ def find_schemas(
             "command_path": command_path,
             "mutation_class": record["mutation_class"],
             "confirmation": record["confirmation"],
+            "server_status": record.get("server_status", "served"),
             "full_schema_command": f"mammoth schema get {command_id}",
         }
         # A match on hidden curated purpose text (T1-I-07) is otherwise

{mammoth_cli-2.2.95 → mammoth_cli-2.2.96}/mammoth_cli/context/resolver.py

@@ -43,8 +43,10 @@ class ExplicitLogin:
     Attributes:
         api_key: The deprecated Mammoth API key (with ``api_secret``).
         api_secret: The deprecated Mammoth API secret.
-        workspace_id: The workspace id, only with the deprecated key + secret;
-            an ``api_token`` names its own workspace and rejects this field.
+        workspace_id: The workspace id. Required with the deprecated key +
+            secret. With an ``api_token`` it is a hint that saves asking the
+            server which workspace the token names; a wrong hint is caught on
+            the first 401 or 403 (``workspace_mismatch``).
         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
@@ -148,15 +150,9 @@ def resolve_token_workspace(base_url: str, api_token: str, timeout: float | None
 
 
 def _explicit_workspace(login: ExplicitLogin, base_url: str, timeout: float | None) -> int:
-    """The workspace of an explicit login: the token's own, or the key pair's given id."""
-    if login.api_token is None:
+    """The workspace of an explicit login: the key pair's given id, or the token's hint or own."""
+    if login.api_token is None or login.workspace_id is not None:
         return _require_positive_workspace(login.workspace_id or 0, source="login")
-    if login.workspace_id is not None:
-        raise CliError(
-            code=CODE_INVALID_WORKSPACE_ID,
-            message="A token login takes no workspace id; the token names its own.",
-            exit_status=EXIT_USAGE,
-        )
     return resolve_token_workspace(base_url, login.api_token, timeout)