kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/system/__init__.py

@@ -0,0 +1,528 @@
+"""System namespace: /system
+
+Commands: info, history, restore, diff
+Sub-namespaces: /system/config (list, get, set, which)
+Manages CLI configuration, displays server info, and provides
+copy-on-write history for config and primer files.
+"""
+
+from __future__ import annotations
+
+import difflib
+from pathlib import Path
+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 OptionDeclaration, OptionLayer, ResolvedOptions
+from kd.config import (
+    DEFAULT_CONFIG_PATH,
+    find_local_config,
+    update_config,
+)
+from kd.exceptions import ConfigError, ValidationError
+from kd.history import (
+    SnapshotInfo,
+    atomic_write_text,
+    diff_text,
+    get_snapshot_path,
+    list_snapshots,
+    snapshot_before_write,
+)
+from kd.primer import PRIMER_FILENAME, require_workspace_dir
+
+
+class SystemInfoCommand(Command):
+    """Show server info and connection status."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "info",
+            "Show server info and connection status",
+            requires_client=True,
+            usage="kd /system info",
+            long_description="Connects to the YouTrack instance and displays the current "
+            "user, server URL, and connection status. Uses the active connection "
+            "(selected via -c or 'default_connection').",
+            examples=[
+                "kd /system info",
+                "kd -c upstream /system info",
+            ],
+            see_also=["/system/config list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        me = client._yt_api.get_me()
+        base_url = str(client._yt_http._client.base_url).rstrip("/")
+        # Strip /api suffix to show the instance URL
+        if base_url.endswith("/api"):
+            base_url = base_url[:-4]
+        return {
+            "url": base_url,
+            "user": me.get("login", "unknown"),
+            "name": me.get("name", ""),
+            "email": me.get("email", ""),
+        }
+
+
+class ConfigListCommand(Command):
+    """Show all config values with source tracking."""
+
+    # Flat keys to display (exclude structured sections and connections)
+    _FLAT_KEYS = ("default_connection", "output", "limit", "debug")
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "Show all config values and their sources",
+            requires_config=True,
+            usage="kd /system/config list",
+            examples=[
+                "kd /system/config list",
+                "kd /system/config list --output json",
+            ],
+            see_also=["/system/config get", "/system/config set", "/system/config which"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        rc = self.config
+        rows: list[dict[str, Any]] = []
+
+        # Flat keys
+        for key in self._FLAT_KEYS:
+            rv = rc.get(key)
+            if rv is None:
+                continue
+            rows.append({"key": key, "value": rv.value, "source": rv.source, "origin": rv.origin})
+
+        # Connections
+        for conn_name, conn_cfg in rc.connections.items():
+            origin = rc.connection_origins.get(conn_name)
+            source_label = origin.source if origin else ""
+            origin_path = origin.path if origin else ""
+            prefix = f"connections.{conn_name}"
+            rows.append(
+                {
+                    "key": f"{prefix}.url",
+                    "value": conn_cfg.url,
+                    "source": source_label,
+                    "origin": origin_path,
+                }
+            )
+            if conn_cfg.default_project:
+                rows.append(
+                    {
+                        "key": f"{prefix}.default_project",
+                        "value": conn_cfg.default_project,
+                        "source": source_label,
+                        "origin": origin_path,
+                    }
+                )
+
+        # Defaults section (local then global, deduped)
+        seen_defaults: set[str] = set()
+        for source_label, defaults in [
+            ("local", rc.local_defaults),
+            ("global", rc.global_defaults),
+        ]:
+            for cmd_key, opts in sorted(defaults.items()):
+                for opt_name, opt_val in sorted(opts.items()):
+                    dotted = f"defaults.{cmd_key}.{opt_name}"
+                    if dotted in seen_defaults:
+                        continue
+                    seen_defaults.add(dotted)
+                    rows.append(
+                        {
+                            "key": dotted,
+                            "value": str(opt_val),
+                            "source": source_label,
+                            "origin": "",
+                        }
+                    )
+
+        # Projects section (local then global, deduped)
+        seen_projects: set[str] = set()
+        for source_label, projects in [
+            ("local", rc.local_projects),
+            ("global", rc.global_projects),
+        ]:
+            for proj_key, proj_data in sorted(projects.items()):
+                if not isinstance(proj_data, dict):
+                    continue
+                # Field aliases
+                aliases = proj_data.get("field_aliases", {})
+                if isinstance(aliases, dict):
+                    for alias_name, alias_val in sorted(aliases.items()):
+                        dotted = f"projects.{proj_key}.field_aliases.{alias_name}"
+                        if dotted in seen_projects:
+                            continue
+                        seen_projects.add(dotted)
+                        rows.append(
+                            {
+                                "key": dotted,
+                                "value": str(alias_val),
+                                "source": source_label,
+                                "origin": "",
+                            }
+                        )
+                # Project defaults
+                proj_defaults = proj_data.get("defaults", {})
+                if isinstance(proj_defaults, dict):
+                    for cmd_key, opts in sorted(proj_defaults.items()):
+                        if not isinstance(opts, dict):
+                            continue
+                        for opt_name, opt_val in sorted(opts.items()):
+                            dotted = f"projects.{proj_key}.defaults.{cmd_key}.{opt_name}"
+                            if dotted in seen_projects:
+                                continue
+                            seen_projects.add(dotted)
+                            rows.append(
+                                {
+                                    "key": dotted,
+                                    "value": str(opt_val),
+                                    "source": source_label,
+                                    "origin": "",
+                                }
+                            )
+
+        # Aliases section (local then global, deduped)
+        seen_aliases: set[str] = set()
+        for source_label, aliases in [
+            ("local", rc.local_aliases),
+            ("global", rc.global_aliases),
+        ]:
+            for alias_name, alias_cmd in sorted(aliases.items()):
+                dotted = f"aliases.{alias_name}"
+                if dotted in seen_aliases:
+                    continue
+                seen_aliases.add(dotted)
+                rows.append(
+                    {
+                        "key": dotted,
+                        "value": alias_cmd,
+                        "source": source_label,
+                        "origin": "",
+                    }
+                )
+
+        return rows
+
+
+class ConfigGetCommand(Command):
+    """Get a config value."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "get",
+            "Get a config value and its source",
+            requires_config=True,
+            usage="kd /system/config get KEY",
+            long_description="Valid keys: default_connection, output, limit, debug.",
+            examples=[
+                "kd /system/config get default_connection",
+                "kd /system/config get output",
+            ],
+            see_also=["/system/config set", "/system/config list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /system/config get KEY")
+        key = args[0]
+        flat_keys = ConfigListCommand._FLAT_KEYS
+        if key not in flat_keys:
+            valid_keys = ", ".join(flat_keys)
+            raise ConfigError(f"Unknown config key: {key}. Valid keys: {valid_keys}")
+        rc = self.config
+        rv = rc.get(key)
+        if rv is None:
+            return {key: None}
+        return {"key": key, "value": rv.value, "source": str(rv.source), "origin": rv.origin}
+
+
+class ConfigSetCommand(Command):
+    """Set a config value."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "set",
+            "Set a config value",
+            usage="kd /system/config set KEY VALUE [--local | --global]",
+            long_description="Writes to local .kd/config.yaml if it exists, "
+            "otherwise to ~/.config/kd/config.yaml. "
+            "Use --local or --global to force target."
+            "\n\n"
+            "Keys:\n"
+            "  default_connection  Active connection name\n"
+            "  output              Output format: table, json, yaml, md\n"
+            "  limit               Result limit for list commands (default: 50)\n"
+            "  debug               Enable debug output: true/false (default: false)",
+            examples=[
+                "kd /system/config set default_connection corp",
+                "kd /system/config set output json --local",
+            ],
+            see_also=["/system/config get", "/system/config list"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="local",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                help_text="Write to local .kd/config.yaml",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="global",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                help_text="Write to global ~/.config/kd/config.yaml",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /system/config set KEY VALUE")
+        key = args[0]
+        value = " ".join(args[1:])
+
+        use_local = options.command.get("local", False)
+        use_global = options.command.get("global", False)
+        if use_local and use_global:
+            raise ValidationError("Cannot use both --local and --global")
+
+        if use_local:
+            local_path = find_local_config()
+            if local_path is None:
+                raise ConfigError("No local config found. Run 'kd init' first.")
+            target = local_path
+        elif use_global:
+            target = DEFAULT_CONFIG_PATH
+        else:
+            # Default: local if it exists, otherwise global
+            target = find_local_config() or DEFAULT_CONFIG_PATH
+
+        update_config(key, value, target)
+        return {"ok": True, "action": "set", "key": key, "value": value, "file": str(target)}
+
+
+class ConfigWhichCommand(Command):
+    """Show which config files are active."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "which",
+            "Show active config file paths",
+            usage="kd /system/config which",
+            examples=["kd /system/config which"],
+            see_also=["/system/config list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        local_path = find_local_config()
+        result: dict[str, Any] = {
+            "global": str(DEFAULT_CONFIG_PATH),
+            "global_exists": DEFAULT_CONFIG_PATH.exists(),
+        }
+        if local_path:
+            result["local"] = str(local_path)
+            result["local_exists"] = True
+        else:
+            result["local"] = None
+            result["local_exists"] = False
+        return result
+
+
+# ---------------------------------------------------------------------------
+# History helpers
+# ---------------------------------------------------------------------------
+
+_VALID_TARGETS = ("config", "primer")
+
+
+def _resolve_target(name: str) -> tuple[Path, Path, str]:
+    """Resolve a history target name to (live_path, history_dir, filename).
+
+    Raises ``ValidationError`` for unknown target names and ``ConfigError``
+    when the required ``.kd/`` directory is missing.
+    """
+    if name == "config":
+        live = find_local_config()
+        if live is None:
+            raise ConfigError("No local config found. Run 'kd init' first.")
+        return live, live.parent / "history", live.name
+    if name == "primer":
+        workspace_dir = require_workspace_dir()
+        live = workspace_dir / PRIMER_FILENAME
+        return live, workspace_dir / "history", PRIMER_FILENAME
+    raise ValidationError(f"Unknown target: {name}. Valid targets: {', '.join(_VALID_TARGETS)}")
+
+
+def _diff_summary(snapshot: SnapshotInfo, current_text: str) -> str:
+    """One-line diff summary: ``+N -M`` lines vs current file."""
+    snap_lines = snapshot.path.read_text().splitlines()
+    curr_lines = current_text.splitlines()
+    added = removed = 0
+    for line in difflib.unified_diff(snap_lines, curr_lines, n=0):
+        if line.startswith("+") and not line.startswith("+++"):
+            added += 1
+        elif line.startswith("-") and not line.startswith("---"):
+            removed += 1
+    return f"+{added} -{removed}"
+
+
+# ---------------------------------------------------------------------------
+# History commands
+# ---------------------------------------------------------------------------
+
+
+class SystemHistoryCommand(Command):
+    """List copy-on-write snapshots for config or primer."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "history",
+            "List config/primer snapshots",
+            usage="kd /system history [config|primer]",
+            long_description="Lists copy-on-write snapshots for config, primer, or both "
+            "(default). Each entry shows the timestamp, file size, and a summary of lines "
+            "changed relative to the current file.",
+            examples=[
+                "kd /system history",
+                "kd /system history config",
+                "kd /system history primer",
+            ],
+            see_also=["/system restore", "/system diff"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        targets = [args[0]] if args else list(_VALID_TARGETS)
+        rows: list[dict[str, Any]] = []
+        for target_name in targets:
+            live_path, history_dir, filename = _resolve_target(target_name)
+            current_text = live_path.read_text() if live_path.exists() else ""
+            for snap in list_snapshots(history_dir, filename):
+                rows.append(
+                    {
+                        "file": target_name,
+                        "timestamp": snap.timestamp,
+                        "size": snap.size,
+                        "changes": _diff_summary(snap, current_text),
+                    }
+                )
+        return rows
+
+
+class SystemRestoreCommand(Command):
+    """Restore a config or primer file from a snapshot."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "restore",
+            "Restore config/primer from a snapshot",
+            usage="kd /system restore <config|primer> <timestamp>",
+            long_description="Replaces the live file with the specified snapshot. "
+            "The current file is snapshotted first, so restore is itself undoable.",
+            examples=[
+                "kd /system restore config 2026-04-09T10-30-00",
+                "kd /system restore primer 2026-04-09T14-20-00",
+            ],
+            see_also=["/system history", "/system diff"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /system restore <config|primer> <timestamp>")
+        target_name, timestamp = args[0], args[1]
+        live_path, history_dir, filename = _resolve_target(target_name)
+        snap_path = get_snapshot_path(history_dir, filename, timestamp)
+        # Snapshot current before restoring (so restore is undoable)
+        snapshot_before_write(live_path)
+        restored_text = snap_path.read_text()
+        atomic_write_text(live_path, restored_text)
+        return {
+            "ok": True,
+            "action": "restore",
+            "target": target_name,
+            "timestamp": timestamp,
+            "file": str(live_path),
+        }
+
+
+class SystemDiffCommand(Command):
+    """Show a unified diff for a config or primer snapshot."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "diff",
+            "Diff config/primer snapshots",
+            usage="kd /system diff <config|primer> <timestamp> [<timestamp>]",
+            long_description="With one timestamp, shows the diff between the snapshot "
+            "and the current file. With two timestamps, diffs the two snapshots.",
+            examples=[
+                "kd /system diff config 2026-04-09T10-30-00",
+                "kd /system diff primer 2026-04-09T10-00-00 2026-04-09T14-00-00",
+            ],
+            see_also=["/system history", "/system restore"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError(
+                "Usage: kd /system diff <config|primer> <timestamp> [<timestamp>]"
+            )
+        target_name = args[0]
+        live_path, history_dir, filename = _resolve_target(target_name)
+
+        snap_a = get_snapshot_path(history_dir, filename, args[1])
+        text_a = snap_a.read_text()
+        label_a = f"{filename}.{args[1]}"
+
+        if len(args) >= 3:
+            snap_b = get_snapshot_path(history_dir, filename, args[2])
+            text_b = snap_b.read_text()
+            label_b = f"{filename}.{args[2]}"
+        else:
+            text_b = live_path.read_text() if live_path.exists() else ""
+            label_b = filename
+
+        result = diff_text(text_a, text_b, label_a, label_b)
+        if not result:
+            return "No differences."
+        return result
+
+
+def create_system_namespace() -> Namespace:
+    """Build the /system namespace tree."""
+    system_ns = Namespace("system", "System management and configuration", path="system")
+    system_ns.register_command("info", SystemInfoCommand())
+    system_ns.register_command("history", SystemHistoryCommand())
+    system_ns.register_command("restore", SystemRestoreCommand())
+    system_ns.register_command("diff", SystemDiffCommand())
+
+    config_ns = Namespace("config", "CLI configuration", path="system/config")
+    config_ns.register_command("list", ConfigListCommand())
+    config_ns.register_command("get", ConfigGetCommand())
+    config_ns.register_command("set", ConfigSetCommand())
+    config_ns.register_command("which", ConfigWhichCommand())
+
+    system_ns.register_sub_namespace(config_ns)
+    return system_ns