ocmo-cli 0.8.19__py3-none-any.whl

ocmo_cli/_body_payload.py

@@ -0,0 +1,203 @@
+"""Parse and validate structured (-f) bodies for SDK BODY_PAYLOAD operations."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = [
+    "BODY_PAYLOADS",
+    "format_usage_error",
+    "merge_tag_address_version",
+    "parse_structured_content",
+    "prepare_body_payload",
+    "prepare_untag_body_payload",
+    "sdk_path_for_body_payload",
+    "validate_create_request",
+    "validate_tag_request",
+]
+
+from ._exit import USAGE_ERROR
+from ._sdk_dispatch import address_keyword_for_op
+
+try:
+    from ocmo._facade_meta import BODY_PAYLOADS
+except ImportError:  # pragma: no cover - CLI tests may run without SDK on path quirks
+    BODY_PAYLOADS = {}
+
+
+_CREATE_REQUIREMENTS: dict[str, tuple[tuple[str, ...], str]] = {
+    "create_namespace": (
+        ("name",),
+        "create namespace requires a name (ADDRESS).",
+    ),
+    "create_global_permission": (
+        ("namespace",),
+        "create global permission requires namespace in -f " "(and optionally rule id via ADDRESS).",
+    ),
+    "create_lock": (
+        ("reason",),
+        "create lock requires --reason with a lock rationale.",
+    ),
+    "replace_lock": (
+        ("reason",),
+        "update lock requires --reason with a lock rationale.",
+    ),
+}
+
+_ADDRESS_REQUIRED_OPS = frozenset({"create_lock"})
+
+# BODY_PAYLOAD ops where ADDRESS is a positional tree path, not a body field.
+_BODY_PAYLOAD_PATH_ARG_OPS = frozenset(
+    {
+        "create_lock",
+        "replace_lock",
+        "rotate_resolver_token",
+        "set_tag",
+    }
+)
+
+# Extra CLI kwargs that must not be merged into the rule/document body.
+_BODY_PAYLOAD_EXCLUDED_EXTRA: dict[str, frozenset[str]] = {
+    "create_global_permission": frozenset({"position"}),
+}
+
+
+def parse_structured_content(content: str) -> dict[str, Any]:
+    """Parse YAML or JSON file/stdin content into an object dict."""
+    import yaml  # deferred
+
+    text = content.strip()
+    if not text:
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        data = yaml.safe_load(text)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError("Body must be a YAML/JSON object (mapping), not a scalar or list.")
+    return data
+
+
+def prepare_body_payload(
+    op_id: str,
+    *,
+    address: str | None,
+    content: str | None,
+    extra: dict[str, Any] | None = None,
+    address_version: str | None = None,
+) -> dict[str, Any]:
+    """Build a dict suitable for SDK ``body=`` on BODY_PAYLOAD create/update ops."""
+    if op_id not in BODY_PAYLOADS:
+        return {}
+
+    payload: dict[str, Any] = {}
+    if content:
+        payload = parse_structured_content(content)
+
+    if address is not None and op_id not in _BODY_PAYLOAD_PATH_ARG_OPS:
+        address_key = address_keyword_for_op(op_id)
+        payload.setdefault(address_key, address)
+
+    if extra:
+        excluded = _BODY_PAYLOAD_EXCLUDED_EXTRA.get(op_id, frozenset())
+        for key, value in extra.items():
+            if key in excluded:
+                continue
+            if value is not None and value is not False:
+                payload.setdefault(key, value)
+
+    if op_id == "set_tag":
+        payload = merge_tag_address_version(payload, address_version)
+
+    return payload
+
+
+def prepare_untag_body_payload(tag: str) -> dict[str, Any]:
+    """POST body to remove a tag (``set_tag`` with ``version: null``)."""
+    return {"tag": tag, "version": None}
+
+
+def validate_tag_request(
+    op_id: str,
+    *,
+    action: str | None = None,
+    payload: dict[str, Any] | None = None,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Fail fast when tag/untag commands omit required --tag."""
+    import sys
+
+    if action == "untag":
+        tag = (extra or {}).get("tag")
+        message = "untag item requires --tag with the version tag name to remove."
+    elif op_id == "set_tag":
+        tag = (payload or {}).get("tag")
+        message = "tag item requires --tag with a version tag name."
+    else:
+        return
+
+    if tag not in (None, ""):
+        return
+
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(USAGE_ERROR)
+
+
+def merge_tag_address_version(
+    payload: dict[str, Any],
+    version: str | None,
+) -> dict[str, Any]:
+    """Fold ADDRESS@version into TagPayload when not already set in the body."""
+    if not version or payload.get("version") not in (None, ""):
+        return payload
+    merged = dict(payload)
+    merged["version"] = int(version) if version.isdigit() else version
+    return merged
+
+
+def validate_create_request(
+    op_id: str,
+    *,
+    address: str | None,
+    payload: dict[str, Any],
+) -> None:
+    """Fail fast with actionable CLI messages before calling the API."""
+    import sys
+
+    if op_id in _ADDRESS_REQUIRED_OPS and not address:
+        print(
+            "Error: create lock requires ADDRESS (tree path to lock).",
+            file=sys.stderr,
+        )
+        raise SystemExit(USAGE_ERROR)
+
+    spec = _CREATE_REQUIREMENTS.get(op_id)
+    if spec is None:
+        return
+
+    required_fields, message = spec
+    if all(payload.get(field) not in (None, "") for field in required_fields):
+        return
+
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(USAGE_ERROR)
+
+
+def format_usage_error(exc: ValueError) -> str:
+    return f"Invalid -f body: {exc}"
+
+
+def sdk_path_for_body_payload(
+    op_id: str,
+    path: str | None,
+    body_payload: dict[str, Any] | None,
+) -> str | None:
+    """Return the path argument for ``build_sdk_call`` (omit when merged into body)."""
+    if body_payload is None:
+        return path
+    if op_id in _BODY_PAYLOAD_PATH_ARG_OPS:
+        return path
+    return None

ocmo_cli/_click_groups.py

@@ -0,0 +1,227 @@
+"""Click group helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from ._lazy_mixin import ClickLazyMixin
+
+
+class DefaultCommandGroup(click.Group):
+    """Group that routes unknown first tokens to a default subcommand."""
+
+    def __init__(self, *args: Any, default_command: str, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.default_command = default_command
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        if args and args[0] not in self.commands and not args[0].startswith("-"):
+            args = [self.default_command, *args]
+        return super().parse_args(ctx, args)
+
+    def _default_command(self, ctx: click.Context) -> click.Command | None:
+        cmd = self.get_command(ctx, self.default_command)
+        if cmd is None:
+            return None
+        return cmd
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        if not args:
+            return None, None, args
+
+        first = args[0]
+        if first in self.commands:
+            return super().resolve_command(ctx, args)
+
+        if ctx.token_normalize_func is not None:
+            normalized = ctx.token_normalize_func(first)
+            if normalized in self.commands:
+                return super().resolve_command(ctx, args)
+
+        default_cmd = self._default_command(ctx)
+        if default_cmd is None:
+            return super().resolve_command(ctx, args)
+
+        if first.startswith("-") or first not in self.commands:
+            return self.default_command, default_cmd, args
+
+        return super().resolve_command(ctx, args)
+
+    def shell_complete(
+        self,
+        ctx: click.Context,
+        incomplete: str,
+    ) -> list[click.shell_completion.CompletionItem]:
+        results = super().shell_complete(ctx, incomplete)
+        default_cmd = self._default_command(ctx)
+        if default_cmd is None:
+            return results
+
+        seen = {item.value for item in results}
+        for item in default_cmd.shell_complete(ctx, incomplete):
+            if item.value not in seen:
+                results.append(item)
+                seen.add(item.value)
+        return results
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Include the default subcommand's options in group help."""
+        self.format_usage(ctx, formatter)
+        self.format_help_text(ctx, formatter)
+        default_cmd = self.get_command(ctx, self.default_command)
+        if default_cmd is not None:
+            with formatter.section("Options"):
+                opts: list[tuple[str, str]] = []
+                for param in default_cmd.get_params(ctx):
+                    record = param.get_help_record(ctx)
+                    if record is not None:
+                        opts.append(record)
+                if opts:
+                    formatter.write_dl(opts)
+        self.format_commands(ctx, formatter)
+        self.format_epilog(ctx, formatter)
+
+
+class ResourceAliasGroup(click.Group):
+    """Group that lists resource aliases on one help line per canonical command."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._alias_to_canonical: dict[str, str] = {}
+        self._aliases_for_resource: dict[str, list[str]] = {}
+
+    def add_resource_command(
+        self,
+        cmd: click.Command,
+        *,
+        canonical: str,
+        aliases: list[str] | None = None,
+    ) -> None:
+        """Register a command under its canonical name and optional aliases."""
+        self.add_command(cmd, name=canonical)
+        alias_list = aliases or []
+        if alias_list:
+            self._aliases_for_resource[canonical] = alias_list
+            for alias in alias_list:
+                self._alias_to_canonical[alias] = canonical
+                self.add_command(cmd, name=alias)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        commands: list[tuple[str, click.Command]] = []
+        for subcommand in self.list_commands(ctx):
+            if subcommand in self._alias_to_canonical:
+                continue
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None or cmd.hidden:
+                continue
+            commands.append((subcommand, cmd))
+
+        if not commands:
+            return
+
+        limit = formatter.width - 6 - max(len(name) for name, _ in commands)
+
+        rows: list[tuple[str, str]] = []
+        for subcommand, cmd in commands:
+            help_text = cmd.get_short_help_str(limit=limit)
+            aliases = self._aliases_for_resource.get(subcommand, [])
+            if aliases:
+                suffix = f" (aliases: {', '.join(aliases)})"
+                help_text = f"{help_text}{suffix}" if help_text else suffix.strip()
+            rows.append((subcommand, help_text))
+
+        with formatter.section("Commands"):
+            formatter.write_dl(rows)
+
+
+def ensure_resource_alias_group(
+    root: click.Group,
+    name: str,
+    *,
+    help: str,
+) -> ResourceAliasGroup:
+    """Return an existing relocate group or create a ``ResourceAliasGroup`` stub."""
+    group = root.commands.get(name)
+    if isinstance(group, ResourceAliasGroup):
+        return group
+    if isinstance(group, click.Group):
+        return group  # type: ignore[return-value]
+
+    @click.group(name, cls=ResourceAliasGroup, help=help)
+    @click.pass_context
+    def group_cmd(ctx: click.Context) -> None:
+        pass
+
+    root.add_command(group_cmd)
+    return group_cmd
+
+
+def attach_resource_command(
+    group: click.Group,
+    cmd: click.Command,
+    *,
+    canonical: str,
+    aliases: list[str] | None = None,
+) -> None:
+    """Register a command on a group, using alias metadata when supported."""
+    if isinstance(group, ResourceAliasGroup):
+        group.add_resource_command(cmd, canonical=canonical, aliases=aliases)
+    elif isinstance(group, click.Group):
+        group.add_command(cmd, name=canonical)
+
+
+class ConfigPathHelpGroup(click.Group):
+    """Group that appends the local CLI config file path to help."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        super().format_help(ctx, formatter)
+        from ._config import format_config_path_note
+
+        formatter.write_paragraph()
+        formatter.write_text(format_config_path_note())
+
+
+class LazyGroup(ClickLazyMixin, click.Group):
+    """Group stub that builds the real group on first use."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        help: str,
+        build_fn: Callable[[], click.Group],
+    ) -> None:
+        super().__init__(name, help=help)
+        self._build_fn = build_fn
+        self._real: click.Group | None = None
+
+    def _lazy_target(self) -> click.Group:
+        return self._ensure()
+
+    def _ensure(self) -> click.Group:
+        if self._real is None:
+            self._real = self._build_fn()
+        return self._real
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        return self._ensure().list_commands(ctx)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        return self._ensure().get_command(ctx, cmd_name)
+
+    def resolve_command(
+        self,
+        ctx: click.Context,
+        args: list[str],
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        return self._ensure().resolve_command(ctx, args)
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        self._ensure().format_help(ctx, formatter)