ocmo-cli 0.8.19__py3-none-any.whl

ocmo_cli/_errors.py

@@ -0,0 +1,151 @@
+"""Map SDK exceptions to CLI exit codes and human-readable messages."""
+
+from __future__ import annotations
+
+import functools
+import sys
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from . import _exit
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def handle_sdk_error(exc: Exception) -> None:
+    """Print an error message and raise SystemExit with the right exit code.
+
+    Import the error hierarchy lazily so this module itself is cheap to import.
+    """
+    # Lazy import to keep startup time low
+    from ocmo.errors import (  # noqa: I001
+        OcmoAPIError,
+        OcmoAuthError,
+        OcmoConfigError,
+        OcmoConflictError,
+        OcmoIncompatibleVersionError,
+        OcmoLockedError,
+        OcmoNotFoundError,
+        OcmoPayloadTooLargeError,
+        OcmoPermissionError,
+        OcmoTransportError,
+        OcmoValidationError,
+    )
+
+    if isinstance(exc, OcmoConfigError):
+        _die(str(exc), _exit.FAILURE)
+    elif isinstance(exc, OcmoIncompatibleVersionError):
+        _die(str(exc), _exit.FAILURE)
+    elif isinstance(exc, OcmoPermissionError):
+        _die(str(exc), _exit.AUTH_ERROR)
+    elif isinstance(exc, OcmoAuthError):
+        _die(str(exc), _exit.AUTH_ERROR)
+    elif isinstance(exc, OcmoNotFoundError):
+        _die(str(exc), _exit.NOT_FOUND)
+    elif isinstance(exc, OcmoConflictError):
+        _die(str(exc), _exit.CONFLICT)
+    elif isinstance(exc, OcmoLockedError):
+        _die(
+            f"{exc} (lock path: {exc.lock_path}, reason: {exc.reason})",
+            _exit.LOCKED,
+        )
+    elif isinstance(exc, OcmoValidationError | OcmoPayloadTooLargeError):
+        detail = _format_validation_errors(getattr(exc, "errors", None))
+        _die(detail if detail else str(exc), _exit.VALIDATION_ERROR)
+    elif isinstance(exc, OcmoTransportError):
+        _die(str(exc), _exit.FAILURE)
+    elif isinstance(exc, OcmoAPIError):
+        msg = str(exc)
+        if exc.method and exc.path and exc.method != "HTTP":
+            msg = f"{exc.method} {exc.path}: {msg}"
+        elif exc.path:
+            msg = f"{exc.path}: {msg}"
+        code = exc.status_code if 400 <= exc.status_code < 600 else _exit.FAILURE
+        if exc.status_code == 404:
+            code = _exit.NOT_FOUND
+        elif exc.status_code == 409:
+            code = _exit.CONFLICT
+        elif exc.status_code == 422:
+            code = _exit.VALIDATION_ERROR
+        _die(msg, code)
+    else:
+        _die(str(exc), _exit.FAILURE)
+
+
+def _die(msg: str, code: int) -> None:
+    msg = msg.rstrip("\n")
+    if "\n" in msg or msg.startswith("  -"):
+        print(f"Error:\n{msg}", file=sys.stderr)
+    else:
+        print(f"Error: {msg}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _format_validation_errors(errors: Any) -> str:
+    if not errors:
+        return ""
+    if isinstance(errors, list):
+        lines: list[str] = []
+        for item in errors:
+            if isinstance(item, dict):
+                loc = item.get("loc") or item.get("field")
+                msg = item.get("msg") or item.get("message") or item.get("error")
+                if loc and msg:
+                    if isinstance(loc, list | tuple):
+                        loc = _format_validation_location(loc)
+                    lines.append(f"  - {loc}: {msg}")
+                elif msg:
+                    lines.append(f"  - {msg}")
+                else:
+                    lines.append(f"  - {item}")
+            elif isinstance(item, str) and ": " in item:
+                field, _, message = item.partition(": ")
+                lines.append(f"  - {field}: {message}")
+            else:
+                lines.append(f"  - {item}")
+        return "\n".join(lines)
+    return f"  - {errors}"
+
+
+def _format_validation_location(loc: tuple[Any, ...] | list[Any]) -> str:
+    parts = [str(part) for part in loc]
+    if not parts:
+        return ""
+    if parts[0] in {"body", "query", "path", "header", "form", "cookie"}:
+        source, *path = parts
+        if not path:
+            return source
+        field = _format_validation_field_path(path)
+        return field if source == "body" else f"{source}.{field}"
+    return _format_validation_field_path(parts)
+
+
+def _format_validation_field_path(parts: list[str]) -> str:
+    result = ""
+    for part in parts:
+        if part.isdigit():
+            result += f"[{part}]"
+        elif result:
+            result += f".{part}"
+        else:
+            result = part
+    return result
+
+
+def sdk_command(fn: Callable[P, R]) -> Callable[P, R]:
+    """Decorator that wraps a click command body to catch SDK errors."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return fn(*args, **kwargs)
+        except KeyboardInterrupt:
+            raise SystemExit(_exit.INTERRUPTED)
+        except SystemExit:
+            raise
+        except Exception as exc:
+            handle_sdk_error(exc)
+            raise AssertionError("handle_sdk_error always exits") from exc
+
+    return wrapper

ocmo_cli/_exit.py

@@ -0,0 +1,13 @@
+"""Exit code constants — public contract, covered by tests."""
+
+SUCCESS = 0
+FAILURE = 1
+USAGE_ERROR = 2
+NOT_FOUND = 3
+AUTH_ERROR = 4
+CONFLICT = 5
+LOCKED = 6
+VALIDATION_ERROR = 7
+HOOK_FAILURE = 8
+VERIFY_FAILURE = 9
+INTERRUPTED = 130

ocmo_cli/_export_metadata.py

@@ -0,0 +1,47 @@
+"""Export metadata comments and extended attributes."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ._item_output import item_metadata_rows
+
+_XATTR_PREFIX = "user.ocmo."
+
+
+def export_metadata_rows(raw_item: Any, *, namespace: str) -> list[tuple[str, Any]]:
+    """Metadata key/value pairs to embed in exports."""
+    rows = item_metadata_rows(raw_item)
+    if namespace:
+        rows = [("namespace", namespace), *rows]
+    return rows
+
+
+def metadata_file_prefix(rows: list[tuple[str, Any]], *, node_type: str) -> str:
+    """Return a comment block to prepend to exported file content."""
+    if not rows or node_type == "secret":
+        return ""
+
+    lines: list[str] = []
+    for key, value in rows:
+        text = f"{key}: {value}"
+        if node_type == "template":
+            lines.append(f"{{# {text} #}}")
+        else:
+            lines.append(f"# {text}")
+
+    return "\n".join(lines) + "\n"
+
+
+def write_export_xattrs(path: os.PathLike[str] | str, rows: list[tuple[str, Any]]) -> None:
+    """Best-effort write of export metadata to ``user.ocmo.*`` xattrs."""
+    if not rows or not hasattr(os, "setxattr"):
+        return
+
+    for key, value in rows:
+        attr = f"{_XATTR_PREFIX}{key}"
+        try:
+            os.setxattr(path, attr, str(value).encode("utf-8"))
+        except OSError:
+            continue

ocmo_cli/_generated_registry.py

@@ -0,0 +1,45 @@
+"""Lightweight registry for generated CLI action groups.
+
+Keeps action names and help text available without importing generated.py.
+Help strings here must stay import-light (no generated.py or SDK).
+"""
+
+from __future__ import annotations
+
+_GENERATED_ACTION_HELP: dict[str, str] = {
+    "get": "Retrieve API resources.",
+    "create": "Create new resources.",
+    "update": "Update existing resources.",
+    "delete": "Delete resources.",
+    "tag": "Add a version tag to an item.",
+    "untag": "Remove a version tag from an item.",
+    "rotate": "Rotate resolver access tokens.",
+    "propagate": "Propagate an item to descendant paths.",
+    "search": "Search the item tree.",
+}
+
+
+def generated_action_names() -> list[str]:
+    """Return sorted action names for generated command groups."""
+    from ocmo_cli._commands_map import OPERATIONS
+
+    actions: set[str] = set()
+    has_set_tag = False
+    for config in OPERATIONS.values():
+        if not isinstance(config, dict):
+            continue
+        if config.get("hand_written") or config.get("skip"):
+            continue
+        action = config.get("action")
+        if not action or action == "resolve":
+            continue
+        actions.add(action)
+        if action == "tag":
+            has_set_tag = True
+    if has_set_tag:
+        actions.add("untag")
+    return sorted(actions)
+
+
+def action_help(action: str) -> str:
+    return _GENERATED_ACTION_HELP.get(action, f"{action.capitalize()} resources.")

ocmo_cli/_get_cast_output.py

@@ -0,0 +1,52 @@
+"""List/show helpers for ``ocmo get cast``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+GET_CAST_LIST_OUTPUT_KEY = "get cast list"
+
+
+class CastFormatNotFoundError(ValueError):
+    """Raised when a requested cast format name is not available."""
+
+
+def is_get_cast_list_mode(*, action: str, resource: str, address: str | None) -> bool:
+    return action == "get" and resource == "cast" and not address
+
+
+def is_get_cast_show_mode(*, action: str, resource: str, address: str | None) -> bool:
+    return action == "get" and resource == "cast" and bool(address)
+
+
+def _formats_from_payload(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, list):
+        return [row for row in data if isinstance(row, dict)]
+    if isinstance(data, dict):
+        formats = data.get("formats")
+        if isinstance(formats, list):
+            return [row for row in formats if isinstance(row, dict)]
+    return []
+
+
+def cast_list_rows(data: Any) -> list[dict[str, str]]:
+    """Return one row per cast format name for list output."""
+    rows: list[dict[str, str]] = []
+    for entry in _formats_from_payload(data):
+        name = entry.get("format")
+        if isinstance(name, str) and name:
+            rows.append({"format": name})
+    return rows
+
+
+def cast_show_payload(data: Any, format_name: str) -> dict[str, Any]:
+    """Return one cast format entry (format + options_schema) for show output."""
+    target = format_name.casefold()
+    for entry in _formats_from_payload(data):
+        name = entry.get("format")
+        if isinstance(name, str) and name.casefold() == target:
+            return {
+                "format": name,
+                "options_schema": entry.get("options_schema") or {},
+            }
+    raise CastFormatNotFoundError(f"Unknown cast format {format_name!r}.")

ocmo_cli/_get_item_list.py

@@ -0,0 +1,23 @@
+"""List-mode helpers for ``ocmo get item`` (namespace-wide item listing)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+ITEM_NODE_TYPES: tuple[str, ...] = ("config", "template", "secret", "resolver")
+GET_ITEM_TYPE_CHOICES: tuple[str, ...] = ITEM_NODE_TYPES
+GET_ITEM_LIST_OUTPUT_KEY = "get item list"
+
+
+def is_get_item_list_mode(*, action: str, resource: str, address: str | None) -> bool:
+    return action == "get" and resource == "item" and not address
+
+
+def prepare_get_item_list_extra(
+    extra: dict[str, Any],
+    *,
+    item_types: tuple[str, ...],
+) -> dict[str, Any]:
+    merged = dict(extra)
+    merged["types"] = list(item_types) if item_types else list(ITEM_NODE_TYPES)
+    return merged

ocmo_cli/_globalpermission_output.py

@@ -0,0 +1,98 @@
+"""Output helpers for global permission rules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._output import as_dict, sanitize_for_output
+
+_PERMISSION_SECTIONS = ("read", "write", "delete", "audit")
+
+
+def _format_actor_claims(claims: dict[str, Any]) -> str:
+    """Format one actor block: claim constraints are combined with AND."""
+    parts = [f"{key}={claims[key]}" for key in sorted(claims) if claims[key] is not None]
+    if not parts:
+        return ""
+    if len(parts) == 1:
+        return parts[0]
+    return " AND ".join(parts)
+
+
+def format_section_claims(section: Any) -> str:
+    """Format one permission section with AND inside actors and OR between actors."""
+    if section is None:
+        return ""
+    payload = as_dict(section, fallback_vars=False)
+    if not isinstance(payload, dict):
+        return ""
+    actors = payload.get("actors")
+    if not isinstance(actors, list):
+        return ""
+
+    blocks: list[str] = []
+    for actor in actors:
+        if not isinstance(actor, dict):
+            continue
+        claims = actor.get("claims")
+        if not isinstance(claims, dict):
+            continue
+        block = _format_actor_claims(claims)
+        if block:
+            blocks.append(block)
+
+    if not blocks:
+        return ""
+    if len(blocks) == 1:
+        return blocks[0]
+
+    formatted_blocks: list[str] = []
+    for block in blocks:
+        if " AND " in block:
+            formatted_blocks.append(f"({block})")
+        else:
+            formatted_blocks.append(block)
+    return " OR ".join(formatted_blocks)
+
+
+def global_permission_table_row(row: dict[str, Any], *, wide: bool = False) -> dict[str, Any]:
+    """Flatten rule payload fields used by ``ocmo get gp`` output."""
+    rule = as_dict(row.get("rule"), fallback_vars=False)
+    flat = dict(row)
+    flat["namespace"] = rule.get("namespace", "")
+    rule_id = rule.get("id")
+    if rule_id not in (None, ""):
+        flat["id"] = str(rule_id)
+    elif flat.get("id") is not None:
+        flat["id"] = str(flat["id"])
+    if wide:
+        for section in _PERMISSION_SECTIONS:
+            flat[section] = format_section_claims(rule.get(section))
+        flat.pop("rule", None)
+    return flat
+
+
+def global_permission_table_rows(
+    rows: list[dict[str, Any]],
+    *,
+    wide: bool = False,
+) -> list[dict[str, Any]]:
+    return [global_permission_table_row(row, wide=wide) for row in rows]
+
+
+def emit_get_globalpermission_output(
+    data: Any,
+    *,
+    output_fmt: str | None = None,
+    ctx_fmt: str | None = None,
+) -> None:
+    """Emit one rule like ``ocmo get globalpermission ADDRESS``."""
+    from ._output_manifest import emit_command_output
+
+    payload = sanitize_for_output(as_dict(data, fallback_vars=False) or data)
+    emit_command_output(
+        "get globalpermission",
+        payload,
+        output_fmt,
+        ctx_fmt=ctx_fmt,
+    )

ocmo_cli/_import_metadata.py

@@ -0,0 +1,140 @@
+"""Read OCMO export metadata from files (xattrs and comment headers)."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from ._export_metadata import _XATTR_PREFIX
+
+_YAML_META_RE = re.compile(r"^#\s*([^:]+):\s*(.*)$")
+_JINJA_META_RE = re.compile(r"^\{#\s*([^:]+):\s*(.*?)\s*#\}$")
+
+# Keys written by ``ocmo export --metadata`` (see ``item_metadata_rows``).
+EXPORT_METADATA_KEYS = frozenset(
+    {
+        "namespace",
+        "path",
+        "name",
+        "node_type",
+        "author",
+        "version",
+        "updater",
+        "updated_at",
+        "description",
+        "deleted_at",
+        "deleted_by",
+    }
+)
+
+
+def read_file_metadata(path: Path) -> dict[str, str]:
+    """Read ``user.ocmo.*`` xattrs and leading comment metadata from *path*."""
+    meta = _read_xattr_metadata(path)
+    text = path.read_text(encoding="utf-8", errors="replace")
+    for key, value in _parse_leading_comment_metadata(text).items():
+        meta.setdefault(key, value)
+    return meta
+
+
+def import_file_text(content_bytes: bytes) -> str:
+    """Decode file bytes and strip leading export metadata comments."""
+    text = content_bytes.decode("utf-8", errors="replace")
+    return strip_export_metadata_comments(text)
+
+
+def strip_export_metadata_comments(content: str) -> str:
+    """Remove leading export metadata comment lines from *content*."""
+    if not content:
+        return content
+
+    lines = content.splitlines(keepends=True)
+    index = 0
+    while index < len(lines):
+        line = lines[index].rstrip("\n")
+        if _is_export_metadata_comment_line(line):
+            index += 1
+            continue
+        break
+    return "".join(lines[index:])
+
+
+def strip_leading_metadata_comments(content: str, *, node_type: str) -> str:
+    """Backward-compatible alias for :func:`strip_export_metadata_comments`."""
+    return strip_export_metadata_comments(content)
+
+
+def metadata_tree_path(metadata_path: str, target_prefix: str) -> str:
+    """Join optional ``--to`` prefix with the path from metadata."""
+    item_path = metadata_path.strip("/")
+    prefix = target_prefix.strip("/")
+    if prefix and item_path:
+        return f"{prefix}/{item_path}"
+    if prefix:
+        return prefix
+    return item_path
+
+
+def _read_xattr_metadata(path: Path) -> dict[str, str]:
+    if not hasattr(os, "listxattr"):
+        return {}
+
+    try:
+        names = os.listxattr(path)
+    except OSError:
+        return {}
+
+    meta: dict[str, str] = {}
+    for name in names:
+        if not isinstance(name, str) or not name.startswith(_XATTR_PREFIX):
+            continue
+        key = name[len(_XATTR_PREFIX) :]
+        try:
+            value = os.getxattr(path, name)
+        except OSError:
+            continue
+        if isinstance(value, bytes):
+            meta[key] = value.decode("utf-8", errors="replace")
+        else:
+            meta[key] = str(value)
+    return meta
+
+
+def _parse_metadata_comment_key(line: str) -> str | None:
+    stripped = line.strip()
+    if not stripped:
+        return None
+    parsed_yaml = _YAML_META_RE.match(stripped)
+    if parsed_yaml:
+        return parsed_yaml.group(1).strip()
+    parsed_jinja = _JINJA_META_RE.match(stripped)
+    if parsed_jinja:
+        return parsed_jinja.group(1).strip()
+    return None
+
+
+def _is_export_metadata_comment_line(line: str) -> bool:
+    key = _parse_metadata_comment_key(line)
+    return key is not None and key in EXPORT_METADATA_KEYS
+
+
+def _parse_leading_comment_metadata(text: str) -> dict[str, str]:
+    meta: dict[str, str] = {}
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        key = _parse_metadata_comment_key(stripped)
+        if key is None or key not in EXPORT_METADATA_KEYS:
+            break
+        parsed_yaml = _YAML_META_RE.match(stripped)
+        if parsed_yaml:
+            meta[key] = parsed_yaml.group(2).strip()
+            continue
+        parsed_jinja = _JINJA_META_RE.match(stripped)
+        if parsed_jinja:
+            meta[key] = parsed_jinja.group(2).strip()
+            continue
+        break
+    return meta