mammoth-cli 2.2.44__tar.gz → 2.2.45__tar.gz

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/PKG-INFO

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

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/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 655 commands. 516 of them bind one of the 545 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, 1 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. Use an untried command normally: confirm a write with the user first, check its result with a read afterwards, and never refuse a command only because it is untried.
+The CLI publishes 656 commands. 516 of them bind one of the 545 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, 1 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. Use an untried command normally: confirm a write with the user first, check its result with a read afterwards, and never refuse a command only because it is untried.
 
 Status meanings:
 

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/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 655; 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 656; 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:
 
@@ -38,6 +38,7 @@ Load only the applicable domain file:
 - [parameter](commands/parameter.md) — 14 published commands
 - [project](commands/project.md) — 25 published commands
 - [report](commands/report.md) — 1 published commands
+- [resolve](commands/resolve.md) — 1 published commands
 - [schedule](commands/schedule.md) — 5 published commands
 - [schema](commands/schema.md) — 3 published commands
 - [skill](commands/skill.md) — 7 published commands

mammoth_cli-2.2.45/mammoth_cli/bundled_skill/mammoth-cli/references/commands/resolve.md

@@ -0,0 +1,13 @@
+# `resolve` commands
+
+Every command returns the standard JSON envelope. On nonzero exit, read the error envelope and its `recovery_commands`; do not guess request fields. "Status on release" is joined from `docs/release-capability-matrix.json`: *ran once* means one bounded live run succeeded on the named CLI release, *untried* means nobody has run it (use it normally: confirm writes with the user, check the result afterwards), *not supported* means the backend refuses it. When this file disagrees with [capabilities](../capabilities.md) or a recipe, they win. Envelope shapes: [machine output](../machine-output.md).
+
+### `resolve`
+
+Run: `mammoth resolve`. Exact input fields: `mammoth schema get resolve`.
+
+Example: `mammoth resolve uqa-w29-ren`. Placeholders are illustrative; resolve IDs and input from observed reads.
+
+Result: `ResolveResult`; mutation `read`, confirmation `none`, wait policy `not_async`.
+
+Status on release: untried; no live run recorded.

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/mammoth_cli/commands/dataset.py

@@ -353,15 +353,38 @@ def _find_by_columns(
     return matches, cut
 
 
+def _tag_scope(matches: list[dict[str, Any]], project_id: int) -> list[dict[str, Any]]:
+    """Mark each match ``in_project``: whether it sits in the project the call runs under."""
+    return [{**m, "in_project": m.get("project_id") == project_id} for m in matches]
+
+
+def _find_scoped(
+    service: Any,
+    needle: str,
+    visible: list[dict[str, Any]],
+    project_id: int,
+    skipped: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], bool]:
+    """``(matches, projects searched, cut)``: the project's own matches, then every other one's."""
+    home = named_project(service, project_id, visible)
+    own = _find_in_projects(service, needle, [home], skipped)
+    holding, cut = _projects_holding(service, needle, visible)
+    outside = _find_in_projects(service, needle, _other_projects(holding, project_id), skipped)
+    searched = [home] + _other_projects(visible, project_id)
+    return _tag_scope(own + outside, project_id), searched, cut
+
+
 def dataset_find(invocation: Invocation) -> HandlerResult:
     """Search dataset names for a substring across every visible project.
 
     Read-only local composite: lists the projects the credential can see, then
     lists datasets in each and keeps a case-insensitive substring match. With
-    ``--project`` that project is searched first, and the rest only when it holds
-    no match: the in-product agent runs every call under the project the user
-    last opened, which is often not the one the named dataset is in. Does not
-    require an active project.
+    ``--project`` the project's own matches come first and the matches in every
+    other visible project are returned too, each row marked ``in_project`` and
+    carrying its ``project_id`` and ``project_name``: the in-product agent runs
+    every call under the project the user last opened, which is often not the one
+    the named dataset is in, so it states where the name is instead of asking the
+    user to switch. Does not require an active project.
     """
     name_substring = _require_string_positional(invocation, "name substring")
     needle = name_substring.lower()
@@ -370,14 +393,9 @@ def dataset_find(invocation: Invocation) -> HandlerResult:
         visible = _visible_projects(service)
         cut = False
         if invocation.project is not None:
-            projects: list[dict[str, Any]] = [named_project(service, invocation.project, visible)]
-            matches = _find_in_projects(service, needle, projects, skipped)
-            if not matches:
-                holding, cut = _projects_holding(service, needle, visible)
-                matches = _find_in_projects(
-                    service, needle, _other_projects(holding, invocation.project), skipped
-                )
-                projects += _other_projects(visible, invocation.project)
+            matches, projects, cut = _find_scoped(
+                service, needle, visible, invocation.project, skipped
+            )
         else:
             projects = visible
             holding, cut = _projects_holding(service, needle, visible)

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/mammoth_cli/commands/registry.py

@@ -45,6 +45,7 @@ from mammoth_cli.commands import notification as notification_cmd
 from mammoth_cli.commands import parameter as parameter_cmd
 from mammoth_cli.commands import project as project_cmd
 from mammoth_cli.commands import report as report_cmd
+from mammoth_cli.commands import resolve as resolve_cmd
 from mammoth_cli.commands import schedule as schedule_cmd
 from mammoth_cli.commands import schema as schema_cmd
 from mammoth_cli.commands import skill as skill_cmd
@@ -283,6 +284,7 @@ HANDLERS: dict[str, Handler] = {
     "doctor": doctor_cmd.doctor,
     "calc": calc_cmd.calc,
     "link": link_cmd.link,
+    "resolve": resolve_cmd.resolve,
     "completion.show": completion_cmd.completion_show,
     "completion.install": completion_cmd.completion_install,
     "skill.agents-md.install": skill_cmd.skill_agents_md_install,

mammoth_cli-2.2.45/mammoth_cli/commands/resolve.py

@@ -0,0 +1,119 @@
+"""The ``resolve`` command: read-only, says what a name refers to.
+
+A user types a name ("uqa-w29-ren") and the agent has to know whether it is a
+dataset, a view or a project, and where. Reading it as the wrong kind sent the
+agent looking for a project that was a dataset's name, and a name that lives in
+another project made it ask the user to switch scope. One call answers both:
+every dataset, view and project whose name matches, with ids and projects.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mammoth_cli.commands.dataset import (
+    _require_string_positional,
+    _visible_projects,
+    search_cut_note,
+    search_hits,
+)
+from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.session import open_service
+
+HandlerResult = tuple[Any, dict[str, Any]]
+
+#: Resource-search type for each kind of match, in the order the kinds are listed.
+_SEARCH_TYPES = (("dataset", "datasource"), ("view", "dataview"))
+
+
+def _row(
+    kind: str, needle: str, entry: dict[str, Any], names: dict[Any, Any], home: int | None
+) -> dict[str, Any]:
+    """One match: its kind, ids, project, whether the name is exact and where it sits."""
+    is_project = kind == "project"
+    project_id = entry.get("id") if is_project else entry.get("project_id")
+    name = entry.get("name")
+    row: dict[str, Any] = {
+        "kind": kind,
+        "id": entry.get("id") if is_project else entry.get("object_id"),
+        "name": name,
+        "project_id": project_id,
+        "project_name": name if is_project else names.get(project_id),
+        "exact": isinstance(name, str) and name.lower() == needle,
+    }
+    if home is not None:
+        row["in_project"] = project_id == home
+    return row
+
+
+def resolve_matches(
+    needle: str,
+    projects: list[dict[str, Any]],
+    hits_by_kind: dict[str, list[dict[str, Any]]],
+    home: int | None = None,
+) -> list[dict[str, Any]]:
+    """Every project, dataset and view whose name contains ``needle`` (any case).
+
+    Exact names come first, then the project the call runs under (``home``), then
+    projects, datasets and views in that order. Pure: no network.
+    """
+    lowered = needle.lower()
+    names = {p.get("id"): p.get("name") for p in projects}
+    rows = [
+        _row("project", lowered, p, names, home)
+        for p in projects
+        if isinstance(p.get("name"), str) and lowered in p["name"].lower()
+    ]
+    for kind, _ in _SEARCH_TYPES:
+        rows += [_row(kind, lowered, h, names, home) for h in hits_by_kind.get(kind, [])]
+    order = {"project": 0, "dataset": 1, "view": 2}
+    return sorted(
+        rows, key=lambda r: (not r["exact"], not r.get("in_project", False), order[r["kind"]])
+    )
+
+
+def kinds_note(name: str, rows: list[dict[str, Any]]) -> str:
+    """Says what the name is: one kind, or several, so it is never read as the wrong one."""
+    if not rows:
+        return f"Nothing visible to this login is named like '{name}'."
+    exact = [r for r in rows if r["exact"]] or rows
+    kinds = sorted({r["kind"] for r in exact}, key=("project", "dataset", "view").index)
+    if len(exact) == 1:
+        only = exact[0]
+        return f"'{name}' is a {only['kind']} (id {only['id']}) in project {only['project_name']}."
+    if len(kinds) == 1:
+        where = sorted({str(r["project_name"]) for r in exact})
+        return f"'{name}' is {len(exact)} {kinds[0]}s, in projects {', '.join(where)}: ask which."
+    return (
+        f"'{name}' names {len(exact)} things ({', '.join(kinds)}): tell them apart by "
+        "kind and project before using an id."
+    )
+
+
+def resolve(invocation: Invocation) -> HandlerResult:
+    """Say what NAME refers to: a dataset, a view or a project, with ids and projects.
+
+    Read-only. NAME is a case-insensitive substring and the only argument; the
+    command has no options besides the global ``--project``, which only marks
+    each match ``in_project`` (matches elsewhere are always returned). Searches
+    every project the credential can see. Does not require an active project.
+    """
+    name = _require_string_positional(invocation, "name")
+    cut = False
+    with open_service(invocation) as (service, auth):
+        projects = _visible_projects(service)
+        hits: dict[str, list[dict[str, Any]]] = {}
+        for kind, resource_type in _SEARCH_TYPES:
+            hits[kind], more = search_hits(service, resource_type, name)
+            cut = cut or more
+        meta = {
+            "profile": invocation.profile,
+            "workspace_id": auth.workspace_id,
+            "project_id": invocation.project,
+        }
+    rows = resolve_matches(name, projects, hits, invocation.project)
+    result: dict[str, Any] = {"name": name, "matches": rows, "note": kinds_note(name, rows)}
+    if cut:
+        result["truncated"] = True
+        result["note"] += " " + search_cut_note("datasets or views")
+    return result, meta

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/mammoth_cli/commands/schema.py

@@ -411,6 +411,10 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "link url pasted address app page open file dataset view folder project "
         "workspace ids selected resource parse"
     ),
+    "resolve": (
+        "resolve name what is this dataset view project called named which kind "
+        "ambiguous same name another project lookup identify"
+    ),
     "dataset.broken-rows.list": (
         "unstructured skipped ragged rows lines unparsed mismatched columns monitor "
         "needs review file upload bad rows"

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/mammoth_cli/services/command_contract.py

@@ -410,6 +410,7 @@ _LOCAL_COMMANDS = frozenset(
         "doctor",
         "project.check",
         "project.ensure",
+        "resolve",
         "folder.find",
         "link",
         "log.path",

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/mammoth_cli/services/positionals.py

@@ -644,6 +644,15 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
             example_value="https://app.mammoth.io/workspaces/1/projects/2/data/datasets",
         ),
     ),
+    "resolve": (
+        PositionalSpec(
+            name="name",
+            type=str,
+            required=True,
+            help="Case-insensitive name, or part of one, to look up as a dataset, view or project.",
+            example_value="uqa-w29-ren",
+        ),
+    ),
     "capability.find": (
         PositionalSpec(
             name="query",
@@ -673,7 +682,8 @@ POSITIONAL_OVERRIDES: dict[str, tuple[PositionalSpec, ...]] = {
             type=str,
             required=False,
             help="Case-insensitive substring to match against dataset names; optional "
-            "when --input gives 'columns'.",
+            "when --input gives 'columns'. Matches in other projects are listed too, "
+            "marked in_project when --project is given.",
             example_value="sales",
         ),
     ),

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mammoth-cli"
-version = "2.2.44"
+version = "2.2.45"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"

{mammoth_cli-2.2.44 → mammoth_cli-2.2.45}/spec/manifests/commands/dataset.yaml

@@ -523,7 +523,8 @@ commands:
     metavar: NAME_SUBSTRING
     falls_back_to_field: null
     help: Case-insensitive substring to match against dataset names; optional when --input
-      gives 'columns'.
+      gives 'columns'. Matches in other projects are listed too, marked in_project when
+      --project is given.
   options: []
   sdk_symbol: mammoth_cli.commands.dataset.find
   sdk_conversion: Call mammoth_cli.commands.dataset.find with validated request fields.

mammoth_cli-2.2.45/spec/manifests/commands/resolve.yaml

@@ -0,0 +1,39 @@
+manifest_schema_version: 1
+commands:
+- command_id: resolve
+  command_path: resolve
+  disposition: command
+  alias_of: null
+  operation_ids: []
+  positionals:
+  - name: name
+    type: str
+    required: true
+    metavar: NAME
+    falls_back_to_field: null
+    help: Case-insensitive name, or part of one, to look up as a dataset, view or project.
+  options: []
+  sdk_symbol: mammoth_cli.commands.resolve.resolve
+  sdk_conversion: Call mammoth_cli.commands.resolve.resolve with validated request fields.
+  request_model: ResolveRequest
+  result_model: ResolveResult
+  mutation_class: read
+  confirmation: none
+  wait_policy: not_async
+  pagination_policy: none
+  acceptance_evidence: live_read_only
+  live_test: null
+  live_exemption_reason: Read-only composite over the workspace resource search and the project list.
+  contract_fixture: null
+  required_fixture_guard: null
+  secret_fields: []
+  human_example: mammoth resolve NAME --help
+  agent_example: mammoth resolve uqa-w29-ren
+  unit_tests:
+  - UT-RESOLVE
+  contract_tests:
+  - CT-RESOLVE-S1-LOCAL
+  draft_test: null
+  undo_test: null
+  known_restrictions: null
+  reviewed_by: primary