mammoth-cli 2.2.47__tar.gz → 2.2.48__tar.gz

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.47
+Version: 2.2.48
 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.9,>=0.8.25
+Requires-Dist: mammoth-io<0.9,>=0.8.26
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

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

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/bundled_skill/mammoth-cli/SKILL.md

@@ -49,7 +49,7 @@ MAMMOTH_OUTPUT=json MAMMOTH_NO_INPUT=1` once.
 Use the project you are given; never `project ensure`. No `doctor`, auth,
 profiles, `config set`, `upgrade`, `skill install`, env vars, local files,
 stdin, `--input FILE` or `output_path` (they fail `not_available_embedded`);
-downloads return `download_url`. On an auth error, ask the user to reload.
+downloads return `download_url`. Ask for a reload on `authentication_failed` only; on a 403 check ids and scope.
 
 ## Defaults you do not repeat
 

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/bundled_skill/mammoth-cli/references/auth.md

@@ -17,8 +17,11 @@ created without a project.
 `mammoth auth login --method oauth` signs the operator in through the browser (PKCE, loopback
 `127.0.0.1`). The CLI keeps a 1 h `mm_` token and refreshes it under a file lock. `auth status`
 reports `credential: oauth` and `expires_at`. A refresh that fails exits 4 with `login_expired`:
-tell the operator to run `mammoth auth login` again. `--no-browser` prints the URL. Browser sign-in
-is for the operator's own terminal; an agent never runs it. `auth logout` also revokes the
+tell the operator to run `mammoth auth login` again. `--no-browser` prints the URL. `--device` is the sign-in for a
+machine with no browser: it prints a short code and a URL for the operator to approve on another
+device, then polls. Browser and device sign-in are for the operator's own terminal; an agent never
+runs them. A key made with `token create` expires after 30 days: `cli_key_expired` means run
+`mammoth auth login` again. `auth logout` also revokes the
 connection on the server, and warns (still clearing local state) if it cannot.
 
 `mammoth token create NAME`, `token list`, `token revoke KEY` are aliases of `client-app create`,

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/bundled_skill/mammoth-cli/references/commands/view.md

@@ -738,7 +738,7 @@ Status on release: ran once on CLI 2.0.21 — ergonomics sweep 2026-09-19: exit
 
 Run: `mammoth view optimize`. Exact input fields: `mammoth schema get view.optimize`.
 
-Example: `mammoth view optimize 123 123`. Illustrative only: append `--yes` after observing an owned target.
+Example: `mammoth view optimize 123`. Illustrative only: append `--yes` after observing an owned target.
 
 Result: `ViewOptimizeResult`; mutation `reversible_pipeline`, confirmation `prompt_or_yes`, wait policy `start_or_wait`.
 

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/bundled_skill/mammoth-cli/references/recipes/auth-scope.md

@@ -19,5 +19,6 @@ condition, not permission to retry mutations. The credential rule lives in
 Exit 4 is auth/authorization; preserve the structured error and stop safely.
 
 In the Mammoth app none of the above applies: there is no `auth status`,
-`doctor` or profile, and the app passes the login and project. On exit 4 ask
-the user to reload the page.
+`doctor` or profile, and the app passes the login and project. On `authentication_failed` or
+`not_authenticated` ask the user to reload the page; on `authorization_required` (403)
+check the ids and scope first, since a reload does not fix them.

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/bundled_skill/mammoth-cli/references/recovery.md

@@ -7,7 +7,8 @@ these commands are not blanket permission to replay a mutation.
 
 | exit | error.code (examples) | next step |
 |---|---|---|
-| 4 | not_authenticated, authentication_failed | `mammoth auth login`; in the Mammoth app, ask the user to reload the page |
+| 4 | not_authenticated, authentication_failed | `mammoth auth login`; in the Mammoth app, ask the user to reload the page (an expired or invalid sign-in only) |
+| 4 | authorization_required (403) | check the view, dataset and project ids and the scope first; a reload does not fix a wrong id |
 | 2 | keyring_unavailable, keyring_unresponsive | operator runs `mammoth auth login --storage file` (or unlocks the OS keychain); not seen in the app |
 | 5 | resource_not_found | re-list to find the correct id |
 | 2 | project_required | `mammoth context project use ID` or `--project` (in the app: `--project` only) |
@@ -48,7 +49,7 @@ the `run_id` when you report a backend fault.
 
 Do not run the next mutation on any of these; report the state (with
 `log_ref.run_id`) and either recover per the tables above or hand off:
-- `auth status` is missing or its `endpoint` does not match the intended environment (in the app there is no `auth status` or `doctor`: an auth error means ask the user to reload the page)
+- `auth status` is missing or its `endpoint` does not match the intended environment (in the app there is no `auth status` or `doctor`: a sign-in error (`authentication_failed`, `not_authenticated`) means ask the user to reload the page; `authorization_required` means check the ids and scope)
 - `mammoth doctor` fails (CLI only)
 - a dataset is still `need_action` after the settings update
 - a read-back after a value-changing step shows a uniform column (all 0 / all one value / all null) or a changed row the condition should not have touched

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/commands/auth.py

@@ -270,13 +270,13 @@ def _verify_login(invocation: Invocation, *, base_url: str, api_token: str) -> i
     return workspace_id
 
 
-_LOGIN_METHODS = ("oauth", "token")
+_LOGIN_METHODS = ("oauth", "device", "token")
 
 
 def _choose_method(
     method: str | None, invocation: Invocation, *, server_prefix: str | None, blockers: list[str]
 ) -> str:
-    """Pick ``oauth`` or ``token``: explicit, implied by ``--input``, or asked.
+    """Pick ``oauth``, ``device`` or ``token``: explicit, implied by ``--input``, or asked.
 
     A server with no CLI OAuth client, a non-interactive run, and ``--input``
     all keep the token login that existed before browser sign-in.
@@ -289,10 +289,10 @@ def _choose_method(
                 exit_status=EXIT_USAGE,
                 hint=f"Use one of: {', '.join(_LOGIN_METHODS)}.",
             )
-        if method == "oauth" and invocation.input_file is not None:
+        if method != "token" and invocation.input_file is not None:
             raise CliError(
                 code="invalid_argument_combination",
-                message="--input is for token logins; it cannot be used with --method oauth.",
+                message=f"--input is for token logins; it cannot be used with --method {method}.",
                 exit_status=EXIT_USAGE,
             )
         return method
@@ -302,16 +302,18 @@ def _choose_method(
         return "token"
     typer.echo("How do you want to sign in?", err=True)
     typer.echo("  1) Browser (OAuth)      recommended", err=True)
+    typer.echo("  2) Device code          no browser on this machine", err=True)
     typer.echo("  3) Paste an API token   for CI and scripts", err=True)
     choice = typer.prompt("Choose", default="1", show_default=False).strip()
-    if choice not in ("1", "3"):
+    methods = {"1": "oauth", "2": "device", "3": "token"}
+    if choice not in methods:
         raise CliError(
             code="invalid_login_method",
             message=f"'{choice}' is not one of the choices.",
             exit_status=EXIT_USAGE,
-            hint="Enter 1 for the browser or 3 to paste an API token.",
+            hint="Enter 1 for the browser, 2 for a device code or 3 to paste an API token.",
         )
-    return "oauth" if choice == "1" else "token"
+    return methods[choice]
 
 
 def _iso(epoch: int) -> str:
@@ -325,16 +327,18 @@ def _run_oauth_login(
     storage: str,
     open_browser: bool,
     interactive: bool,
+    device: bool = False,
 ) -> tuple[dict[str, Any], dict[str, Any]]:
-    """Sign in through the browser and persist the refreshable session."""
+    """Sign in through the browser (or a device code) and persist the refreshable session."""
     base_url = resolve_base_url(server_prefix)
     client_id = oauth.client_id_for(server_prefix)
-    session = oauth.browser_login(
-        base_url,
-        client_id=client_id,
-        open_browser=open_browser,
-        say=lambda line: typer.echo(line, err=True),
-    )
+    say = lambda line: typer.echo(line, err=True)  # noqa: E731
+    if device:
+        session = oauth.device_login(base_url, client_id=client_id, say=say)
+    else:
+        session = oauth.browser_login(
+            base_url, client_id=client_id, open_browser=open_browser, say=say
+        )
     workspace_id = _verify_login(invocation, base_url=base_url, api_token=session.access)
 
     profile_name = invocation.profile or profiles.DEFAULT_PROFILE_NAME
@@ -378,8 +382,18 @@ def _run_login(
     storage: str,
     method: str | None = None,
     no_browser: bool = False,
+    device: bool = False,
 ) -> tuple[dict[str, Any], dict[str, Any]]:
     """Validate, connection-check, and persist one `auth login` invocation."""
+    if device:
+        if method not in (None, "device"):
+            raise CliError(
+                code="invalid_argument_combination",
+                message=f"--device cannot be used with --method {method}.",
+                exit_status=EXIT_USAGE,
+                hint="Use --device alone, or --method device.",
+            )
+        method = "device"
     if storage not in _STORAGE_MODES:
         raise CliError(
             code="invalid_storage_mode",
@@ -390,16 +404,15 @@ def _run_login(
 
     blockers = _prompt_blockers(invocation)
 
-    if (
-        _choose_method(method, invocation, server_prefix=server_prefix, blockers=blockers)
-        == "oauth"
-    ):
+    chosen = _choose_method(method, invocation, server_prefix=server_prefix, blockers=blockers)
+    if chosen in ("oauth", "device"):
         return _run_oauth_login(
             invocation,
             server_prefix=server_prefix,
             storage=storage,
             open_browser=not no_browser,
             interactive=not blockers,
+            device=chosen == "device",
         )
 
     if invocation.input_file is not None:
@@ -488,19 +501,33 @@ def auth_login(
     method: str | None = typer.Option(
         None,
         "--method",
-        help="How to sign in: a browser (oauth) or a pasted API token (token).",
-        metavar="oauth|token",
+        help=(
+            "How to sign in: a browser (oauth), a code typed on another device (device) "
+            "or a pasted API token (token)."
+        ),
+        metavar="oauth|device|token",
     ),
     no_browser: bool = typer.Option(
         False, "--no-browser", help="Print the sign-in URL instead of opening a browser."
     ),
+    device: bool = typer.Option(
+        False,
+        "--device",
+        help=(
+            "Sign in with a device code, for a machine with no browser: the CLI prints "
+            "a short code and a URL, you approve on any other device, and the CLI "
+            "polls until you do. Same as --method device."
+        ),
+    ),
 ) -> None:
     """Log in and store one profile's credentials.
 
     In a terminal, choose a browser sign-in (OAuth; the CLI keeps a token that
-    refreshes itself) or paste an API token (mm_..., from Workspace settings ->
-    API Tokens). The token names its workspace. For non-interactive use
-    (agents, CI), pass ``--input FILE`` with {"api_token": ...} instead.
+    refreshes itself), a device code (``--device``: for a machine with no
+    browser, you type a short code on any other device) or paste an API token
+    (mm_..., from Workspace settings -> API Tokens). The token names its
+    workspace. For non-interactive use (agents, CI), pass ``--input FILE`` with
+    {"api_token": ...} instead.
     Performs a lightweight connection check before saving anything; a failed
     check leaves existing profile state unchanged.
     """
@@ -531,6 +558,7 @@ def auth_login(
             storage=storage,
             method=method,
             no_browser=no_browser,
+            device=device,
         )
 
     executor.run(

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/commands/job.py

@@ -199,7 +199,9 @@ def _with_outcome(service: Any, data: dict[str, Any]) -> dict[str, Any]:
     gets its copied counts and per-view runs (no read). The job succeeded either way, so
     a view that cannot be read is an ``outcome_error``, never a failed wait.
     """
-    copied = job_outcome.copy_outcome(data.get("result"))
+    result = job_outcome.with_derived_datasets(data.get("result"))
+    data = {**data, "result": result} if result is not data.get("result") else data
+    copied = job_outcome.copy_outcome(result)
     if copied is not None and data.get("operation") == job_outcome.COPY_PROJECT_OPERATION:
         return {**data, "outcome": copied}
     target = job_outcome.view_target(data)

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/commands/project.py

@@ -36,6 +36,7 @@ from mammoth_cli.runtime.confirm import (
 )
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, resolved_project
+from mammoth_cli.services import job_outcome
 
 HandlerResult = tuple[Any, dict[str, Any]]
 
@@ -299,7 +300,7 @@ def project_copy(invocation: Invocation) -> HandlerResult:
     _forward_optional(document, kwargs, _COPY_OPTIONAL)
     with open_service(invocation) as (service, auth):
         queued = service.call(_symbol(invocation), **kwargs)
-        data = service.wait_if_job(queued)
+        data = job_outcome.with_derived_datasets(service.wait_if_job(queued))
     return data, _meta(invocation, auth.workspace_id, source_id)
 
 

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/commands/schema.py

@@ -45,6 +45,7 @@ _PROTECTED_INPUT_PATH = "/private/path/request.json"
 # Commands whose useful example the SDK signature cannot express: a distinct
 # second id, an optional-but-central input field, or two views to compare.
 _FIXED_EXAMPLES: dict[str, tuple[tuple[str, ...], dict[str, Any]]] = {
+    "view.optimize": (("123",), {}),
     "project.check": (("123", "456"), {}),
     "view.data.profile": (("123",), {"target": "Churn"}),
     "workflow.canvas": (

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/commands/view.py

@@ -213,6 +213,48 @@ def _resolve_dataset_id(
     return dataset_id
 
 
+def _check_parent_matches(view_id: int, given: int, real: int) -> None:
+    """Refuse a DATASET_ID that is not the view's parent, before any write."""
+    if given == real:
+        return
+    raise CliError(
+        code=CODE_INVALID_ARGUMENT,
+        message=f"view {view_id} belongs to dataset {real}, not {given}",
+        exit_status=EXIT_USAGE,
+        hint=f"Run it again with dataset {real}, or leave DATASET_ID out: mammoth looks it up.",
+        details={"view_id": view_id, "given_dataset_id": given, "dataset_id": real},
+    )
+
+
+def _view_parent_dataset_id(service: Any, invocation: Invocation, view_id: int) -> int:
+    """The view's own dataset: the remembered parent, else one read of the view's row."""
+    profile_name = _profile_name(invocation)
+    workspace_id = getattr(service, "_workspace_id", None)
+    remembered = parents.lookup(profile_name, workspace_id, view_id)
+    if remembered is not None:
+        return remembered
+    dataset_id = int(service.call(_FIND_DATASET_SYMBOL, dataview_id=view_id))
+    parents.remember(profile_name, workspace_id, {view_id: dataset_id})
+    return dataset_id
+
+
+def _verified_dataset_id(
+    service: Any, invocation: Invocation, view_id: int, document: dict[str, Any]
+) -> int:
+    """The view's dataset for a write, so the caller never has to supply it.
+
+    A DATASET_ID (positional or ``dataset_id`` input field) is checked against the
+    view's real parent and refused when it differs; with none, the parent is looked up.
+    """
+    explicit = _int_positional_at(invocation, 1, "dataset id")
+    if explicit is None and document.get(_DATASET_ID_FIELD) is not None:
+        explicit = _int_field(document[_DATASET_ID_FIELD], _DATASET_ID_FIELD)
+    real = _view_parent_dataset_id(service, invocation, view_id)
+    if explicit is not None:
+        _check_parent_matches(view_id, explicit, real)
+    return real
+
+
 def _resolve_dataset_id_for_settle(
     service: Any,
     invocation: Invocation,
@@ -1030,7 +1072,7 @@ def view_optimize(invocation: Invocation) -> HandlerResult:
     kwargs: dict[str, Any] = {"dataview_id": dataview_id, "project_id": project_id}
     _forward_optional(document, kwargs, ("apply_rules",))
     with open_service(invocation) as (service, auth):
-        kwargs["dataset_id"] = _resolve_dataset_id(service, invocation, dataview_id, document)
+        kwargs["dataset_id"] = _verified_dataset_id(service, invocation, dataview_id, document)
         data = service.call(_symbol(invocation), **kwargs)
         if isinstance(data, dict) and data.get("job_id") is not None:
             settled = service.wait_if_job({"job_id": data["job_id"]})

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/context/oauth.py

@@ -1,9 +1,14 @@
-"""Browser sign-in (OAuth 2.0 authorization code + PKCE) and token refresh.
+"""Browser sign-in (OAuth 2.0 authorization code + PKCE), device-code sign-in
+(RFC 8628) and token refresh.
 
 ``mammoth auth login`` opens the Mammoth consent page, receives the code on a
 loopback listener (RFC 8252), and exchanges it for a 1 h ``mm_`` access token
 plus a rotating refresh token. The CLI is a public client: it holds no secret.
 
+``mammoth auth login --device`` is for a machine with no browser: it prints a
+short code and a URL to open on any other device, then polls the token endpoint
+until the code is approved, denied or expired.
+
 The refresh token rotates on every use, and replaying an already-used one
 revokes the whole connection on the server. Two CLI processes must therefore
 never refresh at once: :func:`refresh_session` takes a file lock, re-reads the
@@ -52,6 +57,14 @@ _LOCK_WAIT_SECONDS = 60.0
 CODE_LOGIN_EXPIRED = "login_expired"
 CODE_OAUTH_UNAVAILABLE = "oauth_unavailable"
 CODE_OAUTH_LOGIN_FAILED = "oauth_login_failed"
+CODE_DEVICE_LOGIN_EXPIRED = "device_login_expired"
+
+#: RFC 8628 §3.4: the grant type the device sign-in polls with.
+DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+#: RFC 8628 §3.5: a slow_down answer adds this many seconds to the interval.
+SLOW_DOWN_STEP_SECONDS = 5
+#: Added to every wait so a poll never lands a hair before the server's interval.
+POLL_MARGIN_SECONDS = 1.0
 
 
 def login_expired_error() -> CliError:
@@ -324,6 +337,114 @@ def browser_login(
     return session_from_grant(grant, client_id)
 
 
+# --- device code (RFC 8628) -----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DeviceChallenge:
+    """What the server issues to start a device sign-in."""
+
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+def parse_device_challenge(body: dict[str, object]) -> DeviceChallenge:
+    """Read the device-authorization answer; an unreadable one is a failed login."""
+    try:
+        return DeviceChallenge(
+            device_code=str(body["device_code"]),
+            user_code=str(body["user_code"]),
+            verification_uri=str(body["verification_uri"]),
+            verification_uri_complete=str(body.get("verification_uri_complete") or ""),
+            expires_in=int(str(body["expires_in"])),
+            interval=int(str(body["interval"])),
+        )
+    except (ValueError, KeyError, TypeError) as exc:
+        raise _login_failed("Mammoth's sign-in service returned an unreadable answer.") from exc
+
+
+def start_device_login(base_url: str, *, client_id: str) -> DeviceChallenge:
+    """Ask Mammoth for a device code and the code the person will type."""
+    try:
+        status, body = sdk_oauth.device_authorization_request(base_url, {"client_id": client_id})
+    except sdk_oauth.OAuthTransportError as exc:
+        raise CliError(
+            code="network_error",
+            message="Could not reach Mammoth's sign-in service.",
+            exit_status=EXIT_AUTH,
+            hint="Check your connection and try again.",
+        ) from exc
+    if status != 200 or not isinstance(body, dict):
+        raise _login_failed(f"Mammoth refused to start a device sign-in (HTTP {status}).")
+    return parse_device_challenge(body)
+
+
+def read_poll(status: int, body: dict[str, object], interval: int) -> TokenGrant | int:
+    """Interpret one poll answer.
+
+    Returns the tokens once approved, or the seconds to wait before the next
+    poll (longer after ``slow_down``).
+
+    Raises:
+        CliError: ``oauth_login_failed`` when the person denied the sign-in or
+            the answer is not one RFC 8628 lets the client retry on;
+            ``device_login_expired`` when the code ran out.
+    """
+    if status == 200:
+        return _parse_grant(body)
+    error = str(body.get("error", ""))
+    if error == "authorization_pending":
+        return interval
+    if error == "slow_down":
+        return interval + SLOW_DOWN_STEP_SECONDS
+    if error == "access_denied":
+        raise _login_failed("The sign-in was denied in the browser.")
+    if error == "expired_token":
+        raise device_login_expired_error()
+    raise _login_failed(f"Mammoth refused the sign-in ({error or f'HTTP {status}'}).")
+
+
+def device_login_expired_error() -> CliError:
+    return CliError(
+        code=CODE_DEVICE_LOGIN_EXPIRED,
+        message="The sign-in code expired before it was approved.",
+        exit_status=EXIT_AUTH,
+        hint="Run `mammoth auth login --device` again and approve the new code.",
+        recovery_commands=["mammoth auth login --device"],
+    )
+
+
+def device_login(base_url: str, *, client_id: str, say: Callable[[str], None]) -> OAuthSession:
+    """Run one device sign-in: print the code, poll until it is approved."""
+    challenge = start_device_login(base_url, client_id=client_id)
+    say(f"To sign in, open {challenge.verification_uri} on any device and enter:")
+    say(f"  {challenge.user_code}")
+    if challenge.verification_uri_complete:
+        say(f"Or open this link directly:\n  {challenge.verification_uri_complete}")
+    say("Waiting for approval ...")
+    deadline = time.monotonic() + challenge.expires_in
+    interval = challenge.interval
+    while time.monotonic() < deadline:
+        time.sleep(interval + POLL_MARGIN_SECONDS)
+        status, body = _post_token(
+            base_url,
+            {
+                "grant_type": DEVICE_GRANT_TYPE,
+                "device_code": challenge.device_code,
+                "client_id": client_id,
+            },
+        )
+        step = read_poll(status, body, interval)
+        if isinstance(step, TokenGrant):
+            return session_from_grant(step, client_id)
+        interval = step
+    raise device_login_expired_error()
+
+
 # --- refresh under a file lock ----------------------------------------------------
 
 

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/errors/envelope.py

@@ -89,6 +89,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "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.",
+    "cli_key_expired": "The saved API key has expired, so the assistant needs to sign in again.",
     "cli_keys_need_browser_sign_in": "Managing API keys needs a browser sign-in, not an API token.",
     "cli_keys_not_allowed": "This server doesn't let a browser sign-in create API keys.",
     "confirmation_declined": "This step was not confirmed, so nothing was changed.",
@@ -97,6 +98,7 @@ ERROR_SUMMARIES: dict[str, str] = {
         "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.",
+    "device_login_expired": "The sign-in code expired before it was approved.",
     "dry_run_targets_unresolvable": (
         "The assistant couldn't tell exactly which items this would change, so nothing was changed."
     ),
@@ -284,7 +286,7 @@ def no_saved_project_error() -> CliError:
     )
 
 
-EMBEDDED_AUTH_HINT = "Your session expired or is not authorised; ask the user to reload the page."
+EMBEDDED_AUTH_HINT = "Your session expired or is invalid; ask the user to reload the page."
 EMBEDDED_NO_PROFILE_HINT = "This environment keeps no profiles; the login comes from the host."
 
 

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/runtime/dataset_health.py

@@ -10,6 +10,7 @@ makes a request.
 from __future__ import annotations
 
 import json
+import shlex
 from collections.abc import Iterator
 from typing import Any
 
@@ -113,7 +114,7 @@ def _entry(record: dict[str, Any]) -> dict[str, Any]:
         entry["stored_suggestions"] = suggestions
         entry["fix"] = (
             f"mammoth dataset interpretation preview {dataset_id} --input "
-            + json.dumps({"user_instruction": suggestions[0]})
+            + shlex.quote(json.dumps({"user_instruction": suggestions[0]}))
             + "; then mammoth dataset interpretation confirm "
             + f"{dataset_id} with the same input"
         )

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/services/job_outcome.py

@@ -91,6 +91,26 @@ def view_outcome(record: Any, target: ViewTarget) -> dict[str, Any]:
     }
 
 
+def with_derived_datasets(result: Any) -> Any:
+    """Add ``derived_datasets`` beside a copy's ``derived``, whose direction misleads.
+
+    The backend records ``derived`` as ``{"5214": [5224]}``: dataset 5214 is derived,
+    and view 5224 exports into it. Read as "view 5224 of dataset 5214", it sent an agent
+    to the wrong parent. ``derived_datasets`` says the same thing in words:
+    ``[{"dataset_id": 5214, "from_view_ids": [5224]}]``. ``derived`` stays as it was.
+    """
+    derived = result.get("derived") if isinstance(result, dict) else None
+    if not isinstance(derived, dict) or not derived:
+        return result
+    return {
+        **result,
+        "derived_datasets": [
+            {"dataset_id": _int_or_none(dataset) or dataset, "from_view_ids": list(views or [])}
+            for dataset, views in sorted(derived.items(), key=lambda item: str(item[0]))
+        ],
+    }
+
+
 def copy_outcome(result: Any) -> dict[str, Any] | None:
     """A project copy's outcome: what was copied, what was skipped, and how each run ended.
 
@@ -107,6 +127,9 @@ def copy_outcome(result: Any) -> dict[str, Any] | None:
         "views": len(result.get("view_map") or {}),
         "skipped": len(result.get("skipped") or []),
     }
+    derived = with_derived_datasets(result).get("derived_datasets")
+    if derived:
+        outcome["derived_datasets"] = derived
     runs = result.get("runs")
     if isinstance(runs, dict):
         outcome["runs"] = _run_summary(runs, result.get("run_views"))

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/services/mapping.py

@@ -258,6 +258,8 @@ def _not_allowed_reason(body: Any, status: int | None) -> str | None:
 
 CODE_CLI_KEYS_NOT_ALLOWED = "cli_keys_not_allowed"
 CODE_CLI_KEYS_NEED_BROWSER_SIGN_IN = "cli_keys_need_browser_sign_in"
+CODE_CLI_KEY_EXPIRED = "cli_key_expired"
+_TOKEN_EXPIRED_NAME = "API_TOKEN_EXPIRED"  # noqa: S105 - an error name
 _TOKEN_REFUSED_NAME = "INVALID_TOKEN_FOR_CLIENT_APPS"  # noqa: S105 - an error name
 
 
@@ -267,6 +269,12 @@ def _is_cli_keys_refused(exc: BaseException) -> bool:
     return isinstance(body, dict) and body.get("name") == _TOKEN_REFUSED_NAME
 
 
+def _is_token_expired(exc: BaseException) -> bool:
+    """True for the server's 401 naming an API key that is past its expiry."""
+    body = getattr(exc, "response_body", None)
+    return isinstance(body, dict) and body.get("name") == _TOKEN_EXPIRED_NAME
+
+
 def _stored_credential_kind(profile: str | None) -> str | None:
     """The stored credential kind of ``profile`` (the selected one when None)."""
     credential = credentials.load_credential(profile or profiles.get_selected())
@@ -303,6 +311,17 @@ def map_sdk_exception(
             details=getattr(exc, "details", None),
         )
 
+    if isinstance(exc, MammothAuthError) and _is_token_expired(exc):
+        return CliError(
+            code=CODE_CLI_KEY_EXPIRED,
+            message="This API key has expired; run `mammoth auth login` to sign in again.",
+            exit_status=EXIT_AUTH,
+            hint="Sign in again to get a new key.",
+            details=_metadata(exc),
+            request_id=exc.request_id,
+            recovery_commands=["mammoth auth login"],
+        )
+
     if isinstance(exc, MammothAuthError):
         mismatch = _workspace_mismatch_error(exc, workspace_id)
         if mismatch is not None:
@@ -535,7 +554,9 @@ def map_sdk_exception(
                 message="Mammoth denied access to the requested resource or operation.",
                 exit_status=EXIT_AUTH,
                 hint=(
-                    "Check the target scope or ask an administrator for permission. "
+                    "Check the ids and scope first: a view id given with another dataset's id, "
+                    "or an id from a different project, is refused the same way. Then ask an "
+                    "administrator for permission. "
                     "An API token limited to one project gets this in every other "
                     "project, including one it created: pass that project's --project ID, "
                     "or log in with a token created without a project."

{mammoth_cli-2.2.47 → mammoth_cli-2.2.48}/mammoth_cli/services/positionals.py

@@ -1231,6 +1231,9 @@ EXACT_PARENT_HELP = (
 # instead and hit a not-found on the (unrelated) source view's own parent
 # (WPP evidence c38/c39).
 _EXACT_PARENT_HELP_OVERRIDES: dict[str, str] = {
+    "view.optimize": (
+        "Optional parent dataset ID. Leave it out and the CLI looks up the view's dataset. A value that is not the view's dataset is refused before the write."
+    ),
     "view.export.dataset": (
         "Exact parent dataset ID of the SOURCE view being exported -- not the "
         "destination. Required for this command: pass it here or as the "