ocmo-cli 0.8.19__py3-none-any.whl

ocmo_cli/_sdk_dispatch.py

@@ -0,0 +1,310 @@
+"""Map CLI addresses to SDK method calls for generated commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# First positional argument name when address is provided (by op_id).
+_POSITIONAL_ADDRESS: dict[str, str] = {
+    "show_namespace": "namespace",
+    "delete_namespace": "namespace",
+    "update_namespace": "namespace",
+    "get_global_audit_event": "event_id",
+    "get_namespace_audit_event": "event_id",
+    "get_global_permission": "rule_id",
+    "delete_global_permission": "rule_id",
+    "update_global_permission": "rule_id",
+    "move_global_permission": "rule_id",
+    "get_lock": "path",
+    "create_lock": "path",
+    "replace_lock": "path",
+    "delete_lock": "path",
+    "set_tag": "path",
+}
+
+# Keyword name for address when not using default ``path``.
+_KEYWORD_ADDRESS: dict[str, str] = {
+    "create_namespace": "name",
+    "create_global_permission": "id",
+}
+
+# Create/update ops whose ADDRESS is not a tree path (skip segment validation).
+NON_TREE_ADDRESS_OPS = frozenset(
+    {
+        "create_namespace",
+        "create_global_permission",
+    }
+)
+
+# Operations with multiple positional arguments after kwargs are assembled.
+_MULTI_POSITIONAL: dict[str, list[str]] = {}
+
+
+@dataclass(frozen=True)
+class SdkExtraParam:
+    """Extra CLI flag mapped to an SDK keyword argument."""
+
+    sdk_name: str
+    click_name: str
+    help: str
+    type_: type | None = str
+    is_flag: bool = False
+
+
+_SDK_PARAM_CATALOG: dict[str, SdkExtraParam] = {
+    "q": SdkExtraParam("q", "q", "Search query string."),
+    "types": SdkExtraParam("types", "types", "Filter by node types (comma-separated)."),
+    "limit": SdkExtraParam("limit", "limit", "Maximum number of results.", int),
+    "offset": SdkExtraParam("offset", "offset", "Result offset for pagination.", int),
+    "object_id": SdkExtraParam("object_id", "object-id", "Audit object ID."),
+    "object_type": SdkExtraParam("object_type", "object-type", "Audit object type."),
+    "search": SdkExtraParam("search", "search", "Free-text search filter."),
+    "from_": SdkExtraParam("from_", "from", "Range start (ISO timestamp)."),
+    "to": SdkExtraParam("to", "to", "Range end (ISO timestamp)."),
+    "bucket_seconds": SdkExtraParam("bucket_seconds", "bucket-seconds", "Bucket size in seconds.", int),
+    "tag": SdkExtraParam("tag", "tag", "Version tag name."),
+    "no_creds": SdkExtraParam("no_creds", "no-creds", "Omit credential-backed parameters.", is_flag=True),
+    "auth_id": SdkExtraParam("auth_id", "auth-id", "Filter by author ID."),
+    "auth_email": SdkExtraParam("auth_email", "auth-email", "Filter by author email."),
+    "event_id": SdkExtraParam("event_id", "event-id", "Filter by event ID."),
+    "event_kind": SdkExtraParam("event_kind", "event-kind", "Filter by event kind."),
+    "token_number": SdkExtraParam("token_number", "token-number", "Resolver token number.", int),
+    "reason": SdkExtraParam("reason", "reason", "Lock rationale."),
+    "expires_at": SdkExtraParam("expires_at", "expires-at", "Lock expiry time (ISO-8601 UTC)."),
+    "position": SdkExtraParam(
+        "position",
+        "position",
+        "Sort position for the new rule (applied via move after create).",
+        float,
+    ),
+    "description": SdkExtraParam(
+        "description",
+        "description",
+        "Human-readable namespace description.",
+    ),
+    "tagged_only": SdkExtraParam(
+        "tagged_only",
+        "tagged-only",
+        "Show only versions that have tags.",
+        is_flag=True,
+    ),
+    "preview": SdkExtraParam(
+        "preview",
+        "preview",
+        "Show what would be deleted without removing anything.",
+        is_flag=True,
+    ),
+}
+
+# Per-operation extra SDK kwargs exposed as CLI flags.
+_OP_EXTRA_PARAMS: dict[str, list[str]] = {
+    "search_root": ["q", "types", "limit", "offset"],
+    "search_path": ["q", "types", "limit", "offset"],
+    "namespace_audit_timeline": ["object_id", "object_type", "search", "limit", "offset"],
+    "namespace_audit_resolve_series": ["object_id", "object_type", "from_", "to", "bucket_seconds"],
+    "list_namespace_audit": [
+        "auth_id",
+        "auth_email",
+        "object_id",
+        "object_type",
+        "event_id",
+        "event_kind",
+        "search",
+        "from_",
+        "to",
+        "limit",
+        "offset",
+    ],
+    "list_global_audit": [
+        "auth_id",
+        "auth_email",
+        "object_id",
+        "object_type",
+        "event_id",
+        "event_kind",
+        "search",
+        "from_",
+        "to",
+        "limit",
+        "offset",
+    ],
+    "set_tag": ["tag"],
+    "rotate_resolver_token": ["token_number"],
+    "create_lock": ["reason", "expires_at"],
+    "replace_lock": ["reason", "expires_at"],
+    "create_namespace": ["description"],
+    "create_global_permission": ["position"],
+    "list_item_versions": ["limit", "offset", "tagged_only"],
+    "delete_item": ["preview"],
+}
+
+# Operations that accept version/tag via address@VER or --version.
+VERSION_ADDRESS_OPS = frozenset(
+    {
+        "get_item",
+        "delete_item",
+        "propagate_config",
+        "get_config_data_schema",
+        "set_tag",
+    }
+)
+
+# ADDRESS@VER is folded into the request body (not an SDK ``version`` kwarg).
+VERSION_BODY_OPS = frozenset(
+    {
+        "set_tag",
+    }
+)
+
+# ADDRESS@VER is a filter/query for these ops, not an SDK ``version`` argument.
+VERSION_FILTER_OPS = frozenset(
+    {
+        "list_item_versions",
+    }
+)
+
+# Operations that do not accept a tree path / address argument.
+NO_ADDRESS_OPS = frozenset(
+    {
+        "namespace_audit_timeline",
+        "namespace_audit_resolve_series",
+        "search_root",
+        "list_namespaces",
+        "list_global_audit",
+        "list_namespace_audit",
+        "list_global_permissions",
+        "list_locks",
+        "list_cast_formats",
+        "health",
+    }
+)
+
+
+def address_optional_for_command(
+    op_ids: list[str],
+    *,
+    action: str,
+    resource: str,
+) -> bool:
+    """True when ADDRESS may be omitted (list-without-path or scoped list ops)."""
+    if action == "create" and resource == "globalpermission":
+        return True
+    if action == "get" and resource in ("item", "cast"):
+        return True
+    return any(op_id in NO_ADDRESS_OPS for op_id in op_ids)
+
+
+def address_required_for_op(op_id: str, *, action: str, resource: str) -> bool:
+    """True when the resolved SDK operation needs a CLI ADDRESS."""
+    if action == "create" and resource == "globalpermission":
+        return False
+    return op_id not in NO_ADDRESS_OPS
+
+
+def extra_params_for_ops(op_ids: list[str]) -> list[SdkExtraParam]:
+    """Return sorted unique extra parameter specs for a generated command."""
+    seen: dict[str, SdkExtraParam] = {}
+    for op_id in op_ids:
+        for name in _OP_EXTRA_PARAMS.get(op_id, []):
+            seen[name] = _SDK_PARAM_CATALOG[name]
+    return [seen[k] for k in sorted(seen)]
+
+
+def pick_op_id(
+    op_ids: list[str],
+    *,
+    address: str | None,
+    namespace: str | None,
+    ops_meta: dict[str, dict[str, Any]],
+) -> str:
+    """Choose the SDK operation when several map to the same CLI command."""
+    if len(op_ids) == 1:
+        return op_ids[0]
+
+    candidates = list(op_ids)
+
+    # Mixed client/namespace audit & permission ops: prefer scope matching -n.
+    if namespace:
+        scoped = [o for o in candidates if ops_meta.get(o, {}).get("scope") == "namespace"]
+        if scoped:
+            candidates = scoped
+    else:
+        scoped = [o for o in candidates if ops_meta.get(o, {}).get("scope") == "client"]
+        if scoped:
+            candidates = scoped
+
+    if address:
+        singles = [
+            o
+            for o in candidates
+            if o.startswith(("show_", "get_", "search_path", "navigate_path")) or o.endswith("_path")
+        ]
+        if singles:
+            return singles[0]
+        non_list = [o for o in candidates if not o.startswith("list_") and not o.endswith("_root")]
+        return non_list[0] if non_list else candidates[0]
+
+    lists = [o for o in candidates if o.startswith("list_") or o.endswith("_root")]
+    return lists[0] if lists else candidates[0]
+
+
+def address_keyword_for_op(op_id: str) -> str:
+    """SDK keyword that receives the CLI ADDRESS for ``op_id``."""
+    return _KEYWORD_ADDRESS.get(op_id, "path")
+
+
+def build_sdk_call(
+    op_id: str,
+    *,
+    path: str | None,
+    version: str | None,
+    content: str | None,
+    extra: dict[str, Any] | None = None,
+) -> tuple[list[Any], dict[str, Any]]:
+    """Return (positional_args, keyword_args) for an SDK facade method."""
+    from ocmo._facade_meta import DOCUMENT_BODY_OPS
+
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
+
+    if path is not None:
+        if op_id in _POSITIONAL_ADDRESS:
+            args.append(path)
+        else:
+            kw = address_keyword_for_op(op_id)
+            kwargs[kw] = path
+
+    if version is not None and op_id not in VERSION_FILTER_OPS and op_id not in VERSION_BODY_OPS:
+        kwargs["version"] = version
+
+    if content is not None:
+        if op_id in DOCUMENT_BODY_OPS:
+            kwargs["content"] = content
+        else:
+            kwargs["body"] = content
+
+    if extra:
+        for key, value in extra.items():
+            if value is not None and value is not False:
+                kwargs[key] = value
+
+    multi = _MULTI_POSITIONAL.get(op_id)
+    if multi:
+        for name in multi:
+            if name in kwargs:
+                args.append(kwargs.pop(name))
+
+    return args, kwargs
+
+
+def unwrap_list_payload(data: Any) -> list[dict[str, Any]] | None:
+    """Extract a list of row dicts from common paginated API responses."""
+    if isinstance(data, list):
+        return [r for r in data if isinstance(r, dict)]
+    if isinstance(data, dict):
+        for key in ("items", "children", "versions", "locks", "rules", "formats"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return [r for r in value if isinstance(r, dict)]
+    return None

ocmo_cli/_typing.py

@@ -0,0 +1,27 @@
+"""Shared typing helpers for Click decorators and deferred SDK imports."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol, TypeAlias, TypeVar
+
+ClickDecorator: TypeAlias = Callable[[Callable[..., Any]], Callable[..., Any]]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ResolvedArtifact(Protocol):
+    name: str | None
+    version: int | None
+    format: str | None
+    checksum: str | None
+    trace: dict[str, Any]
+    url: str | None
+
+    @property
+    def bytes(self) -> bytes: ...
+
+    @property
+    def text(self) -> str: ...
+
+    def get(self, path: str, *, default: Any = ...) -> Any: ...

ocmo_cli/_version_output.py

@@ -0,0 +1,39 @@
+"""Helpers for ``ocmo get version`` address and query handling."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def apply_version_address_query(extra: dict[str, Any], version: str | None) -> None:
+    """Map ADDRESS@VER suffix to list_item_versions query parameters.
+
+    ``@latest``, ``@stable``, and other tag names are passed as ``q`` (search),
+    not as implicit ``limit=1`` — a tag may point at an older version.
+    """
+    if not version or extra.get("q") is not None:
+        return
+    extra.setdefault("q", version)
+
+
+def emit_item_versions_output(
+    view: Any,
+    path: str,
+    *,
+    version: str | None,
+    output_fmt: str | None,
+    ctx_fmt: str | None,
+    field: str | None = None,
+) -> None:
+    """Emit version history for *path* using ``get version`` output formatting."""
+    from ._output import as_dict, extract_field, sanitize_for_output
+    from ._output_manifest import emit_command_output
+
+    list_kwargs: dict[str, Any] = {}
+    apply_version_address_query(list_kwargs, version)
+    result = view.list_item_versions(path=path, **list_kwargs)
+    data = as_dict(result)
+    if field:
+        extract_field(sanitize_for_output(data), field)
+        return
+    emit_command_output("get version", data, output_fmt, ctx_fmt=ctx_fmt)

ocmo_cli/_whoami_output.py

@@ -0,0 +1,43 @@
+"""Output helpers for ``ocmo whoami``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._output import as_dict
+
+
+def whoami_table_row(data: Any) -> dict[str, Any]:
+    """Flatten whoami API payload for table output."""
+    payload = as_dict(data, fallback_vars=False)
+    if not payload:
+        return {}
+
+    row: dict[str, Any] = {
+        "auth_type": payload.get("auth_type"),
+        "identifier": payload.get("identifier"),
+        "display_name": payload.get("display_name"),
+        "access_scope": payload.get("access_scope"),
+    }
+
+    user_details = payload.get("user_details")
+    if isinstance(user_details, dict):
+        row["email"] = user_details.get("email")
+        row["is_global_admin"] = user_details.get("is_global_admin")
+        row["claims"] = user_details.get("claims")
+        return row
+
+    resolver_details = payload.get("resolver_details")
+    if isinstance(resolver_details, dict):
+        row["namespace"] = resolver_details.get("namespace")
+        row["name"] = resolver_details.get("name")
+        row["token_number"] = resolver_details.get("token_number")
+
+    return row
+
+
+def whoami_table_rows(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, list):
+        return [whoami_table_row(item) for item in data]
+    row = whoami_table_row(data)
+    return [row] if row else []

ocmo_cli/commands/__init__.py

@@ -0,0 +1 @@
+# Commands package.

ocmo_cli/commands/api.py

@@ -0,0 +1,125 @@
+"""ocmo api — escape hatch to invoke any SDK operation directly.
+
+This is the guarantee that no API capability is ever unreachable from the CLI.
+Prints raw JSON. Bypasses all ergonomic layers.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, NoReturn
+
+import click
+
+from .._client import OcmoCtx
+from .._errors import handle_sdk_error
+from .._output import as_dict, emit
+
+
+@click.command("api", hidden=True)
+@click.argument("operation_id")
+@click.option(
+    "--param", "-p", "params", multiple=True, metavar="KEY=VALUE", help="Operation parameters (may be repeated)."
+)
+@click.option(
+    "-f", "--file", "file_path", default=None, metavar="FILE|-", help="Request body from file ('-' for stdin)."
+)
+@click.option("-n", "--namespace", default=None)
+@click.pass_obj
+def api_cmd(
+    ctx: OcmoCtx,
+    operation_id: str,
+    params: tuple[str, ...],
+    file_path: str | None,
+    namespace: str | None,
+) -> None:
+    """Invoke any API operation directly by operation_id.
+
+    This is the escape hatch for operations marked `skip` in commands.yaml,
+    and for advanced usage. Output is always raw JSON.
+
+    \b
+    Examples:
+      ocmo api whoami
+      ocmo api get_item --param path=app/web -n prod
+      ocmo api create_config --param path=app/new -f body.yaml -n prod
+    """
+    kwargs: dict[str, Any] = {}
+
+    # Parse --param
+    for p in params:
+        if "=" not in p:
+            print(f"Error: --param must be KEY=VALUE, got {p!r}", file=sys.stderr)
+            raise SystemExit(2)
+        k, v = p.split("=", 1)
+        kwargs[k] = v
+
+    # Read body
+    if file_path:
+        if file_path == "-":
+            kwargs["content"] = sys.stdin.read()
+        else:
+            with open(file_path) as f:
+                kwargs["content"] = f.read()
+
+    try:
+        result = _dispatch(ctx, operation_id, namespace, kwargs)
+        if result is not None:
+            if isinstance(result, list):
+                emit([as_dict(item) for item in result], "json")
+            else:
+                payload = as_dict(result, fallback_vars=False) or result
+                emit(payload, "json")
+    except KeyboardInterrupt:
+        raise SystemExit(130)
+    except SystemExit:
+        raise
+    except Exception as exc:
+        handle_sdk_error(exc)
+
+
+def _dispatch(ctx: OcmoCtx, op_id: str, namespace: str | None, kwargs: dict[str, Any]) -> Any:
+    """Find the SDK method and call it."""
+    from pathlib import Path
+
+    import yaml  # deferred
+
+    ops_path = Path(__file__).parent.parent.parent.parent / "sdk" / "operations.yaml"
+    scope = "namespace"
+    if ops_path.exists():
+        with ops_path.open() as f:
+            ops = yaml.safe_load(f) or {}
+        op_cfg = ops.get("operations", {}).get(op_id, {})
+        scope = op_cfg.get("scope", "namespace")
+
+    if scope == "client":
+        client = ctx.client()
+        method = getattr(client, op_id, None)
+        if method is None:
+            _no_such_op(op_id)
+        assert method is not None
+        return method(**kwargs)
+    else:
+        ns = namespace or ctx.namespace
+        if ns:
+            view = ctx.ns(ns)
+        else:
+            # Try client first, then ask for namespace
+            client = ctx.client()
+            method = getattr(client, op_id, None)
+            if method:
+                return method(**kwargs)
+            ctx.require_namespace(namespace)  # will abort with error
+            raise SystemExit(2)  # unreachable but satisfies type checker
+
+        method = getattr(view, op_id, None)
+        if method is None:
+            _no_such_op(op_id)
+        assert method is not None
+        return method(**kwargs)
+
+
+def _no_such_op(op_id: str) -> NoReturn:
+    print(f"Error: unknown operation {op_id!r}.", file=sys.stderr)
+    print("Run `ocmo api --help` or check the SDK documentation for valid operation IDs.", file=sys.stderr)
+    raise SystemExit(2)

ocmo_cli/commands/api_health.py

@@ -0,0 +1,12 @@
+"""ocmo api-health — check API dependency health."""
+
+from __future__ import annotations
+
+from .._client_commands import client_command
+
+api_health_cmd = client_command(
+    "api-health",
+    help="Check API dependency health (database, cache, and related backends).",
+    manifest_key="api-health",
+    method="health",
+)