kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/user/__init__.py

@@ -0,0 +1,99 @@
+"""User namespace: /user
+
+Commands: list, create, delete
+API layer: Hub REST API (/hub/api/rest/users)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.namespaces import Namespace
+from kd.cli.core.option_registry import ResolvedOptions
+from kd.exceptions import ValidationError
+
+
+class UserListCommand(Command):
+    """List users."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List users",
+            requires_client=True,
+            usage="kd /user list",
+            examples=["kd /user list"],
+            see_also=["/user create"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        users = client.users.list()
+        return [
+            {
+                "login": u.login,
+                "name": u.name,
+                "email": u.email or "",
+                "banned": u.banned,
+            }
+            for u in users
+        ]
+
+
+class UserCreateCommand(Command):
+    """Create a user."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "create",
+            "Create a user",
+            requires_client=True,
+            usage="kd /user create LOGIN NAME EMAIL",
+            examples=['kd /user create testbot "Test Bot" testbot@example.com'],
+            see_also=["/user list", "/user delete"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 3:
+            raise ValidationError("Usage: kd /user create LOGIN NAME EMAIL")
+        user = client.users.create(login=args[0], name=args[1], email=args[2])
+        return {
+            "login": user.login,
+            "name": user.name,
+            "email": user.email or "",
+        }
+
+
+class UserDeleteCommand(Command):
+    """Delete a user."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete a user",
+            requires_client=True,
+            usage="kd /user delete HUB_USER_ID",
+            examples=["kd /user delete abc-123"],
+            see_also=["/user list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /user delete HUB_USER_ID")
+        client.users.delete(args[0])
+        return {"ok": True, "action": "delete", "user": args[0]}
+
+
+def create_user_namespace() -> Namespace:
+    """Build the /user namespace tree."""
+    ns = Namespace("user", "User management", path="user")
+    ns.register_command("list", UserListCommand())
+    ns.register_command("create", UserCreateCommand())
+    ns.register_command("delete", UserDeleteCommand())
+    return ns

kd/cli/output.py

@@ -0,0 +1,287 @@
+"""Output formatting.
+
+Renders command results in multiple formats:
+- table: human-readable tabular output (default for TTY)
+- json: JSON output for piping to jq
+- yaml: YAML output
+- md: Markdown table
+
+Auto-detects TTY vs pipe: uses table format for interactive terminals,
+falls back to json when piped.
+
+Value normalization runs before serialization: epoch-ms timestamps become
+ISO 8601, enums become their ``.value``, and nested collections render
+cleanly in every format.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+import yaml
+from tabulate import tabulate
+
+from kd.cli.core.command_base import CommandResult
+from kd.cli.tree import TreeNode, render_tree
+
+# Fields whose int values are Unix-epoch milliseconds.
+TIMESTAMP_FIELDS = frozenset({"created", "updated", "resolved"})
+
+# Fields whose int values are epoch-ms but semantically a date (no time component).
+DATE_FIELDS = frozenset({"date"})
+
+# Threshold: timestamps below this are normal ints, not epoch-ms.
+# 1_000_000_000_000 ms ≈ 2001-09-09 — all YouTrack timestamps exceed this.
+_EPOCH_MS_FLOOR = 1_000_000_000_000
+
+# Detail-table scalars longer than this (or containing newlines) render as
+# separate unindented blocks rather than being padded into the key column by
+# tabulate. 80 matches the common terminal width; shorter values fit inline
+# without padding damage.
+_LONG_TEXT_THRESHOLD = 80
+
+
+def _is_long_text(value: Any) -> bool:
+    """Detect scalar strings that should render as their own block."""
+    return isinstance(value, str) and ("\n" in value or len(value) > _LONG_TEXT_THRESHOLD)
+
+
+def _format_timestamp(epoch_ms: int) -> str:
+    """Convert Unix-epoch milliseconds to ``YYYY-MM-DD HH:MM UTC``."""
+    dt = datetime.fromtimestamp(epoch_ms / 1000, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%d %H:%M UTC")
+
+
+def _format_date(epoch_ms: int) -> str:
+    """Convert Unix-epoch milliseconds to ``YYYY-MM-DD`` (UTC)."""
+    dt = datetime.fromtimestamp(epoch_ms / 1000, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%d")
+
+
+class OutputFormatter:
+    """Formats CommandResult for display."""
+
+    def format(
+        self,
+        data: CommandResult,
+        fmt: str | None = None,
+        fields: str | None = None,
+        display_hint: str | None = None,
+    ) -> str:
+        """Format data for output.
+
+        Args:
+            data: Structured data from a command.
+            fmt: Output format. Auto-detected if None (TTY->table, pipe->json).
+            fields: Comma-separated field names to include.
+            display_hint: Rendering hint from the command (e.g. ``"tree"``).
+        """
+        if data is None:
+            return ""
+        if isinstance(data, str):
+            return data
+
+        normalized: list[dict[str, Any]] | dict[str, Any] = self._normalize(data)
+
+        if fmt is None:
+            fmt = "table" if sys.stdout.isatty() else "json"
+
+        # Tree display: table/md render as pretty tree, json/yaml serialize structure.
+        if display_hint == "tree" and isinstance(normalized, dict) and fmt in ("table", "md"):
+            return self._render_tree_display(normalized)
+
+        field_list = [f.strip() for f in fields.split(",")] if fields else None
+
+        match fmt:
+            case "table":
+                return self._format_table(normalized, field_list)
+            case "json":
+                return self._format_json(normalized, field_list)
+            case "yaml":
+                return self._format_yaml(normalized, field_list)
+            case "md":
+                return self._format_markdown(normalized, field_list)
+            case _:
+                return self._format_table(normalized, field_list)
+
+    # ------------------------------------------------------------------
+    # Normalization
+    # ------------------------------------------------------------------
+
+    def _normalize(self, data: Any) -> Any:
+        """Walk *data* and normalize values for safe serialization."""
+        if isinstance(data, dict):
+            return {k: self._normalize_value(k, v) for k, v in data.items()}
+        if isinstance(data, list):
+            return [self._normalize(item) for item in data]
+        return data
+
+    def _normalize_value(self, key: str, value: Any) -> Any:
+        """Normalize a single value based on its key and type."""
+        if isinstance(value, int) and key in DATE_FIELDS and value > _EPOCH_MS_FLOOR:
+            return _format_date(value)
+        if isinstance(value, int) and key in TIMESTAMP_FIELDS and value > _EPOCH_MS_FLOOR:
+            return _format_timestamp(value)
+        if hasattr(value, "value") and hasattr(value, "name"):  # enum
+            return value.value
+        if isinstance(value, dict):
+            return self._normalize(value)
+        if isinstance(value, list):
+            return [self._normalize(item) for item in value]
+        return value
+
+    # ------------------------------------------------------------------
+    # Tree rendering
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _render_tree_display(data: dict[str, Any]) -> str:
+        """Render nested tree dict as pretty box-drawing output."""
+
+        def _to_node(d: dict[str, Any]) -> TreeNode:
+            return TreeNode(
+                id=d.get("id", ""),
+                label=d.get("summary", d.get("id", "")),
+                has_children=bool(d.get("children")),
+            )
+
+        def _fetch_children(node_id: str) -> list[TreeNode]:
+            # Walk the tree dict to find the node and return its children
+            children = _find_children(data, node_id)
+            return [_to_node(c) for c in children]
+
+        def _find_children(node: dict[str, Any], target_id: str) -> list[dict[str, Any]]:
+            kids: list[dict[str, Any]] = node.get("children", [])
+            if node.get("id") == target_id:
+                return kids
+            for child in kids:
+                result = _find_children(child, target_id)
+                if result is not None:
+                    return result
+            return []
+
+        root = _to_node(data)
+        return render_tree(root, _fetch_children)
+
+    # ------------------------------------------------------------------
+    # Format dispatchers
+    # ------------------------------------------------------------------
+
+    def _format_table(
+        self, data: list[dict[str, Any]] | dict[str, Any], fields: list[str] | None
+    ) -> str:
+        """Format as plain text table."""
+        if isinstance(data, dict):
+            filtered_dict = self._filter_dict(data, fields)
+            return self._render_detail_table(filtered_dict)
+
+        filtered_rows = self._filter_list(data, fields)
+        if not filtered_rows:
+            return "(no entries)"
+        headers = list(filtered_rows[0].keys())
+        rows = [list(row.values()) for row in filtered_rows]
+        result: str = tabulate(rows, headers=headers, tablefmt="simple")
+        return result
+
+    def _render_detail_table(self, data: dict[str, Any]) -> str:
+        """Render a single-entity detail view.
+
+        Scalar fields are aligned in a two-column key/value block.
+        Nested lists of dicts become indented sub-tables with a header.
+        Long-text scalars (newlines or > ``_LONG_TEXT_THRESHOLD`` chars)
+        are lifted out of the scalar block and rendered unindented so
+        multi-line markdown stays copy-paste clean.
+        """
+        parts: list[str] = []
+        rows: list[list[Any]] = []
+
+        def _flush_rows() -> None:
+            if rows:
+                parts.append(tabulate(rows, tablefmt="plain"))
+                rows.clear()
+
+        for key, value in data.items():
+            if isinstance(value, list) and value and isinstance(value[0], dict):
+                _flush_rows()
+                parts.append(f"\n{key}")
+                sub_headers = list(value[0].keys())
+                sub_rows = [list(item.values()) for item in value]
+                parts.append(
+                    "  "
+                    + tabulate(sub_rows, headers=sub_headers, tablefmt="simple").replace(
+                        "\n", "\n  "
+                    )
+                )
+            elif _is_long_text(value):
+                _flush_rows()
+                parts.append(f"\n{key}:")
+                parts.append(str(value))
+            else:
+                rows.append([key, value])
+        _flush_rows()
+        return "\n".join(parts)
+
+    def _format_json(
+        self, data: list[dict[str, Any]] | dict[str, Any], fields: list[str] | None
+    ) -> str:
+        """Format as JSON."""
+        filtered = self._filter(data, fields)
+        return json.dumps(filtered, indent=2)
+
+    def _format_yaml(
+        self, data: list[dict[str, Any]] | dict[str, Any], fields: list[str] | None
+    ) -> str:
+        """Format as YAML."""
+        filtered = self._filter(data, fields)
+        result: str = yaml.safe_dump(
+            filtered,
+            default_flow_style=False,
+            sort_keys=False,
+            allow_unicode=True,
+        )
+        return result.rstrip()
+
+    def _format_markdown(
+        self, data: list[dict[str, Any]] | dict[str, Any], fields: list[str] | None
+    ) -> str:
+        """Format as Markdown table."""
+        if isinstance(data, dict):
+            filtered_dict = self._filter_dict(data, fields)
+            rows = [[k, v] for k, v in filtered_dict.items()]
+            result: str = tabulate(rows, headers=["Key", "Value"], tablefmt="github")
+            return result
+
+        filtered_rows = self._filter_list(data, fields)
+        if not filtered_rows:
+            return ""
+        headers = list(filtered_rows[0].keys())
+        rows = [list(row.values()) for row in filtered_rows]
+        result = tabulate(rows, headers=headers, tablefmt="github")
+        return result
+
+    def _filter(
+        self,
+        data: list[dict[str, Any]] | dict[str, Any],
+        fields: list[str] | None,
+    ) -> list[dict[str, Any]] | dict[str, Any]:
+        """Apply field filtering to data."""
+        if isinstance(data, dict):
+            return self._filter_dict(data, fields)
+        return self._filter_list(data, fields)
+
+    def _filter_dict(self, data: dict[str, Any], fields: list[str] | None) -> dict[str, Any]:
+        """Filter dict keys to only requested fields."""
+        if not fields:
+            return data
+        return {k: v for k, v in data.items() if k in fields}
+
+    def _filter_list(
+        self, data: list[dict[str, Any]], fields: list[str] | None
+    ) -> list[dict[str, Any]]:
+        """Filter list of dicts to only requested fields."""
+        if not fields:
+            return data
+        return [{k: v for k, v in row.items() if k in fields} for row in data]

kd/cli/tree.py

@@ -0,0 +1,65 @@
+"""Tree rendering utility.
+
+Renders hierarchical data as an indented tree with box-drawing characters::
+
+    Root Node
+    ├── Child 1
+    │   └── Grandchild
+    └── Child 2
+
+Generic interface: provide a root node and a callback that fetches children.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass
+class TreeNode:
+    """A node in a tree display."""
+
+    id: str
+    label: str
+    has_children: bool = False
+
+
+def render_tree(
+    root: TreeNode,
+    fetch_children: Callable[[str], list[TreeNode]],
+    max_depth: int = 5,
+) -> str:
+    """Render a tree as a string with box-drawing characters.
+
+    Args:
+        root: The root node to display.
+        fetch_children: Callback that takes a node ID and returns child nodes.
+        max_depth: Maximum depth to recurse (0 = root only).
+    """
+    lines: list[str] = [f"{root.label}"]
+    if max_depth > 0 and root.has_children:
+        children = fetch_children(root.id)
+        _render_children(lines, children, fetch_children, "", max_depth - 1)
+    return "\n".join(lines)
+
+
+def _render_children(
+    lines: list[str],
+    children: list[TreeNode],
+    fetch_children: Callable[[str], list[TreeNode]],
+    prefix: str,
+    remaining_depth: int,
+) -> None:
+    """Recursively render child nodes with correct box-drawing prefixes."""
+    for i, child in enumerate(children):
+        is_last = i == len(children) - 1
+        connector = "└── " if is_last else "├── "
+        lines.append(f"{prefix}{connector}{child.label}")
+
+        if remaining_depth > 0 and child.has_children:
+            extension = "    " if is_last else "│   "
+            grandchildren = fetch_children(child.id)
+            _render_children(
+                lines, grandchildren, fetch_children, prefix + extension, remaining_depth - 1
+            )