kd-cli 2.0.4__py3-none-any.whl

kd/cli/input.py

@@ -0,0 +1,42 @@
+"""Shared text input resolution.
+
+Provides a single function for resolving text values that may reference
+a file (``@path``), stdin (``-`` or ``@-``). Used by any CLI command
+that accepts free-text input such as descriptions or comments.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from kd.exceptions import ValidationError
+
+
+def resolve_text_input(value: str | None) -> str | None:
+    """Resolve a text value that may reference a file or stdin.
+
+    - ``None`` or empty string: returned as-is
+    - ``@path``: reads file at *path* and returns its contents
+    - ``@-``: reads all of stdin (raises on empty input)
+    - ``-``: reads all of stdin and returns it
+    - anything else: returned as-is (plain text)
+    """
+    if not value:
+        return value
+    if value == "-":
+        return sys.stdin.read()
+    if value == "@-":
+        text = sys.stdin.read()
+        if not text:
+            raise ValidationError("No input received from stdin")
+        return text
+    if value.startswith("@"):
+        file_path = Path(value[1:])
+        if not file_path.is_file():
+            raise ValidationError(f"File not found: {file_path}")
+        text = file_path.read_text(encoding="utf-8")
+        if not text:
+            raise ValidationError(f"File is empty: {file_path}")
+        return text
+    return value

kd/cli/main.py

@@ -0,0 +1,612 @@
+"""CLI entry point.
+
+Initializes the namespace tree, parses arguments, dispatches
+to the matching command, and handles output formatting.
+
+Entry point registered in pyproject.toml as:
+    kd = "kd.cli.main:main"
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+import shlex
+import sys
+from typing import Any
+
+from kd import __version__
+from kd.cli.core.command_parser import (
+    CommandParser,
+    ParseError,
+    UnresolvedCommand,
+)
+from kd.cli.core.namespaces import Namespace, NamespaceRegistry
+from kd.cli.core.option_registry import OUTPUT_OPTIONS, OptionDeclaration, OptionLayer
+from kd.cli.namespaces import register_all_namespaces
+from kd.cli.output import OutputFormatter
+from kd.client import YouTrackClient
+from kd.config import ResolvedConfig, resolve_command_defaults, resolve_config
+from kd.connection import ConnectionContext, resolve_connection
+from kd.debug import DebugLevel, DebugLog, init_debug_log
+from kd.exceptions import APIError, KdError
+
+# Global options — single source of truth for extraction, help, and reference.
+GLOBAL_OPTIONS: list[OptionDeclaration] = [
+    OptionDeclaration(
+        name="help",
+        short_name="h",
+        layer=OptionLayer.GLOBAL,
+        type=bool,
+        help_text="Show help for a command or namespace",
+    ),
+    OptionDeclaration(
+        name="version",
+        short_name="V",
+        layer=OptionLayer.GLOBAL,
+        type=bool,
+        help_text="Show version",
+    ),
+    OptionDeclaration(
+        name="reference",
+        short_name="R",
+        layer=OptionLayer.GLOBAL,
+        type=bool,
+        help_text="Print full command reference (LLM-friendly)",
+    ),
+    OptionDeclaration(
+        name="debug",
+        short_name="D",
+        layer=OptionLayer.GLOBAL,
+        type=bool,
+        help_text="Enable debug output (-D info, -DD debug, -DDD trace)",
+    ),
+    OptionDeclaration(
+        name="connection",
+        short_name="c",
+        layer=OptionLayer.GLOBAL,
+        type=str,
+        help_text="Select a configured connection by name (env: KD_CONNECTION)",
+    ),
+]
+
+
+def _config_flags_from_globals(global_opts: dict[str, Any]) -> dict[str, str] | None:
+    """Build the ``flags`` dict for :func:`resolve_config` from extracted globals.
+
+    Returns ``None`` when no relevant globals are set, so call sites can use
+    ``resolve_config(flags=_config_flags_from_globals(global_opts))`` and pass
+    ``None`` naturally.
+    """
+    flags: dict[str, str] = {}
+    conn = global_opts.get("connection")
+    if conn:
+        flags["default_connection"] = conn
+    return flags or None
+
+
+# Subcommands in the /alias namespace — not eligible for alias expansion.
+_ALIAS_SUBCOMMANDS = {"list", "show"}
+
+
+def expand_alias(args: list[str], config: ResolvedConfig) -> list[str]:
+    """Expand an alias invocation to the full command string.
+
+    If ``args`` starts with ``["alias", NAME]`` where NAME is a defined alias,
+    replace with the expanded command tokens plus any trailing override flags.
+    Returns *args* unchanged if no expansion applies.
+    """
+    if len(args) >= 2 and args[0] == "alias" and args[1] in config.aliases:
+        expanded = shlex.split(config.aliases[args[1]])
+        return expanded + args[2:]
+    return args
+
+
+def expand_toplevel_alias(
+    name: str,
+    trailing: list[str],
+    config: ResolvedConfig,
+) -> list[str] | None:
+    """Expand a top-level alias to full command tokens, or *None*.
+
+    Unlike :func:`expand_alias` (which handles the explicit ``alias <name>``
+    form), this function is used as a fallback when the dispatcher encounters
+    an unknown command at root level.
+    """
+    if name in config.aliases:
+        return shlex.split(config.aliases[name]) + trailing
+    return None
+
+
+def _print_error(error: KdError) -> None:
+    """Print error with optional suggestion to stderr."""
+    print(f"Error: {error}", file=sys.stderr)
+    if isinstance(error, APIError) and error.suggestion:
+        print(f"Hint: {error.suggestion}", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    args = argv if argv is not None else sys.argv[1:]
+
+    # Extract global options before namespace parsing
+    global_opts, remaining = _extract_globals(args)
+    config_flags = _config_flags_from_globals(global_opts)
+
+    # Initialize debug logging from -D count (0 = silent)
+    debug_raw = global_opts.get("debug", 0)
+    debug_level = DebugLevel(min(debug_raw, 3)) if debug_raw else DebugLevel.SILENT
+    debug_log = init_debug_log(debug_level)
+
+    if global_opts.get("version"):
+        print(f"kd {__version__}")
+        return
+
+    # Alias expansion: detect `alias <name>` and expand before parsing.
+    # Config is loaded early only when needed; stored for reuse later.
+    resolved: ResolvedConfig | None = None
+    if len(remaining) >= 2 and remaining[0] == "alias" and remaining[1] not in _ALIAS_SUBCOMMANDS:
+        resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+        remaining = expand_alias(remaining, resolved)
+
+    # Build registry and parser
+    registry = NamespaceRegistry()
+    register_all_namespaces(registry)
+
+    if global_opts.get("reference"):
+        if resolved is None:
+            resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+        _show_reference(registry, config=resolved)
+        return
+    parser = CommandParser(registry)
+    formatter = OutputFormatter()
+
+    # Phase 1: resolve command and tokenize options (no validation).
+    # A ParseError on an unknown root token may still be resolved by
+    # alias expansion, so we defer the error in that case.
+    parse_error: ParseError | None = None
+    try:
+        unresolved = parser.parse_command(remaining)
+    except ParseError as e:
+        # If the first token could be a top-level alias, defer the error
+        # and let the alias fallback below handle it.
+        if remaining and not remaining[0].startswith("-"):
+            parse_error = e
+            # Build a minimal UnresolvedCommand so the fallback logic can inspect it.
+            unresolved = UnresolvedCommand(
+                namespace=registry.root,
+                command_name=remaining[0],
+                command=None,
+            )
+        else:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    # No command found — show discovery or help
+    if unresolved.command is None:
+        if not parse_error and global_opts.get("help"):
+            _show_discovery(unresolved.namespace)
+            return
+        if not unresolved.command_name:
+            _show_discovery(unresolved.namespace)
+            return
+
+        # Top-level alias fallback: when an unknown command is typed at root,
+        # check whether it matches a configured alias and expand it.
+        if unresolved.namespace is registry.root:
+            if resolved is None:
+                resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+            expanded = expand_toplevel_alias(unresolved.command_name, remaining[1:], resolved)
+            if expanded is not None:
+                try:
+                    unresolved = parser.parse_command(expanded)
+                except ParseError as e:
+                    print(f"Error: {e}", file=sys.stderr)
+                    sys.exit(1)
+                parse_error = None
+                # Fall through to normal execution below.
+            elif parse_error:
+                print(f"Error: {parse_error}", file=sys.stderr)
+                sys.exit(1)
+            else:
+                print(f"Unknown command: {unresolved.command_name}", file=sys.stderr)
+                _show_suggestions(unresolved.namespace, unresolved.command_name)
+                sys.exit(1)
+        elif parse_error:
+            print(f"Error: {parse_error}", file=sys.stderr)
+            sys.exit(1)
+        else:
+            print(f"Unknown command: {unresolved.command_name}", file=sys.stderr)
+            _show_suggestions(unresolved.namespace, unresolved.command_name)
+            sys.exit(1)
+
+    assert unresolved.command is not None  # alias expansion guarantees a resolved command
+
+    # --help for a specific command — before option validation or config resolution
+    if global_opts.get("help"):
+        print(unresolved.command.get_help_text())
+        return
+
+    # Resolve config from flags + env + local + global (reuse if loaded for alias expansion)
+    if resolved is None:
+        resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+
+    # Debug config key: if config says debug=true and no -D on CLI, enable level 1
+    if resolved.debug and not global_opts.get("debug"):
+        debug_log = init_debug_log(DebugLevel.INFO)
+        debug_log.info("config", "debug enabled via config")
+
+    # Inject config defaults into raw options BEFORE validation
+    _apply_config_defaults(unresolved, resolved, debug_log)
+
+    # Phase 2: validate and resolve options (after config defaults filled in)
+    try:
+        parsed = parser.resolve_options(unresolved)
+    except ParseError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    assert parsed.command is not None  # guaranteed by unresolved.command assertion above
+
+    # Create client if needed — resolve connection first
+    client: YouTrackClient | None = None
+    connection: ConnectionContext | None = None
+    if parsed.command.requires_client:
+        try:
+            connection = resolve_connection(
+                connections=resolved.connections,
+                default_connection=resolved.default_connection_name,
+                debug_log=debug_log,
+            )
+            client = YouTrackClient(
+                connection=connection,
+                config=resolved,
+                debug_log=debug_log,
+            )
+        except KdError as e:
+            _print_error(e)
+            sys.exit(1)
+
+    # Execute command
+    if parsed.command.requires_config:
+        parsed.command.set_config(resolved)
+    try:
+        result = parsed.command.execute(parsed.args, parsed.options, client)
+    except KdError as e:
+        _print_error(e)
+        sys.exit(1)
+    finally:
+        if client:
+            client.close()
+
+    # Format and print output
+    if result is not None:
+        fmt = parsed.options.output.get("output")
+        fields = parsed.options.output.get("fields")
+        display_hint = getattr(parsed.command, "display_hint", None)
+        output = formatter.format(result, fmt=fmt, fields=fields, display_hint=display_hint)
+        if output:
+            # String results (e.g. /article pull) own their trailing newline.
+            # Everything else goes through print() which appends one newline.
+            if isinstance(result, str):
+                sys.stdout.write(output)
+                if not output.endswith("\n"):
+                    sys.stdout.write("\n")
+            else:
+                print(output)
+
+
+def _extract_globals(args: list[str]) -> tuple[dict[str, Any], list[str]]:
+    """Extract global options from args. Returns (globals_dict, remaining_args).
+
+    Driven by GLOBAL_OPTIONS declarations — adding a new global option
+    only requires adding an OptionDeclaration to the list.
+    """
+    # Build lookup tables from declarations
+    flags: dict[str, str] = {}  # --name / -short → name (bool options)
+    value_opts: dict[str, str] = {}  # --name / -short → name (str options)
+    for decl in GLOBAL_OPTIONS:
+        if decl.type is bool:
+            flags[f"--{decl.name}"] = decl.name
+            if decl.short_name:
+                flags[f"-{decl.short_name}"] = decl.name
+        else:
+            value_opts[f"--{decl.name}"] = decl.name
+            if decl.short_name:
+                value_opts[f"-{decl.short_name}"] = decl.name
+
+    # Pre-pass: count -D occurrences (stacking).  -DD = 2, -DDD = 3,
+    # --debug = 1.  Remove matched tokens so the main loop never sees them.
+    _D_PATTERN = re.compile(r"^-D{1,3}$")
+    debug_count = 0
+    filtered: list[str] = []
+    for token in args:
+        if _D_PATTERN.match(token):
+            debug_count += len(token) - 1  # "-DD" → 2
+        elif token == "--debug":
+            debug_count += 1
+        else:
+            filtered.append(token)
+    # Remove debug from the generic flag map — already handled above.
+    flags.pop("--debug", None)
+    flags.pop("-D", None)
+
+    global_opts: dict[str, Any] = {}
+    if debug_count:
+        global_opts["debug"] = min(debug_count, 3)
+
+    remaining: list[str] = []
+
+    i = 0
+    while i < len(filtered):
+        token = filtered[i]
+
+        if token in flags:
+            global_opts[flags[token]] = True
+            i += 1
+            continue
+
+        if token in value_opts:
+            name = value_opts[token]
+            if i + 1 < len(filtered):
+                global_opts[name] = filtered[i + 1]
+                i += 2
+            else:
+                print(f"Error: {token} requires a value", file=sys.stderr)
+                sys.exit(1)
+            continue
+
+        # Handle --name=value for value options
+        matched_equals = False
+        for prefix, name in value_opts.items():
+            if prefix.startswith("--") and token.startswith(f"{prefix}="):
+                global_opts[name] = token.split("=", 1)[1]
+                matched_equals = True
+                break
+        if matched_equals:
+            i += 1
+            continue
+
+        remaining.append(token)
+        i += 1
+
+    return global_opts, remaining
+
+
+# ---------------------------------------------------------------------------
+# Config default injection
+# ---------------------------------------------------------------------------
+
+_ISSUE_ID_RE = re.compile(r"^([A-Za-z][A-Za-z0-9_]*)-\d+$")
+
+
+def _command_key(namespace: Namespace, command_name: str) -> str:
+    """Derive the config command key from namespace path and command name.
+
+    Examples: ``issue_list``, ``issue_comment_add``, ``system_config_list``.
+    """
+    if namespace.path:
+        return namespace.path.replace("/", "_") + "_" + command_name
+    return command_name
+
+
+def _determine_project(
+    args: list[str], raw_options: dict[str, Any], config: ResolvedConfig
+) -> str | None:
+    """Determine which project a command targets.
+
+    Priority: explicit ``--project`` flag → ``default_project`` from
+    config → inferred from first issue-ID-shaped arg.
+    """
+    # 1. Explicit --project flag
+    project = raw_options.get("project")
+    if project:
+        return str(project)
+
+    # 2. default_project from config
+    if config.default_project:
+        return config.default_project
+
+    # 3. Infer from first issue-ID-shaped arg (e.g. "FB-123" → "FB")
+    for arg in args:
+        m = _ISSUE_ID_RE.match(arg)
+        if m:
+            return m.group(1).upper()
+
+    return None
+
+
+def _apply_config_defaults(
+    unresolved: UnresolvedCommand,
+    config: ResolvedConfig,
+    debug_log: DebugLog | None,
+) -> None:
+    """Inject config defaults into raw options before validation.
+
+    Mutates ``unresolved.raw_options`` so that phase-2 validation
+    sees config-provided values for options not set by the CLI.
+    """
+    if unresolved.command is None:
+        return
+
+    cmd_key = _command_key(unresolved.namespace, unresolved.command_name)
+    project = _determine_project(unresolved.args, unresolved.raw_options, config)
+
+    # Gather all declarations (command + output options)
+    all_decls = unresolved.command.get_options() + OUTPUT_OPTIONS
+
+    defaults = resolve_command_defaults(
+        cmd_key, project, unresolved.raw_options, config, all_decls, debug_log=debug_log
+    )
+
+    # Inject default_project for commands that declare a project option.
+    # Priority: --project flag > command defaults > default_project > none.
+    if (
+        "project" not in unresolved.raw_options
+        and "project" not in defaults
+        and config.default_project
+        and any(d.name == "project" for d in all_decls)
+    ):
+        defaults["project"] = config.default_project
+        if debug_log:
+            debug_log.debug(
+                "config",
+                f"injecting default_project={config.default_project} for {cmd_key}",
+            )
+
+    if not defaults:
+        return
+
+    if debug_log:
+        debug_log.debug("config", f"injecting config defaults for {cmd_key}: {defaults}")
+
+    # Merge defaults into raw_options — CLI flags already present are not overwritten
+    for key, value in defaults.items():
+        if key not in unresolved.raw_options:
+            unresolved.raw_options[key] = value
+
+
+def _show_reference(
+    registry: NamespaceRegistry,
+    *,
+    config: ResolvedConfig | None = None,
+) -> None:
+    """Print a condensed reference of all commands, options, and examples.
+
+    Generated from command metadata — always in sync with the code.
+    Designed for LLM consumption: one output, full coverage.
+    """
+    print(f"kd {__version__} — YouTrack CLI and SDK")
+    print()
+
+    # Global options line — generated from declarations
+    parts: list[str] = []
+    for decl in GLOBAL_OPTIONS + OUTPUT_OPTIONS:
+        flag = f"--{decl.name}"
+        if decl.short_name:
+            flag += f"/-{decl.short_name}"
+        if decl.type is not bool:
+            flag += f" {decl.name.upper()}"
+        if decl.choices:
+            flag += f" ({'/'.join(decl.choices)})"
+        parts.append(flag)
+    print(f"Global options: {', '.join(parts)}")
+    print()
+    _print_namespace_reference(registry.root)
+
+    # Aliases — show user-defined shortcuts when any are configured
+    if config and config.aliases:
+        print()
+        print("Aliases:")
+        for name, command in sorted(config.aliases.items()):
+            print(f"  kd {name:<20}{command}")
+        print(
+            "  Aliases are invocable as top-level commands. Flags after the name override the expansion."
+        )
+
+
+def _print_namespace_reference(ns: Namespace, depth: int = 0) -> None:
+    """Recursively print reference for a namespace and its children."""
+    for cmd_name, cmd in sorted(ns.commands.items()):
+        # Build the full command path using canonical slash notation
+        prefix = f"kd /{ns.path} " if ns.path else "kd "
+        usage = cmd.usage or f"{prefix}{cmd_name}"
+
+        # Command line
+        print(f"  {usage}")
+        print(f"    {cmd.description}")
+        if cmd.long_description:
+            print(f"    {cmd.long_description}")
+
+        # Options
+        for opt in cmd.get_options():
+            flag = f"--{opt.name}"
+            if opt.short_name:
+                flag += f"/-{opt.short_name}"
+            if opt.choices:
+                flag += f" ({', '.join(opt.choices)})"
+            line = f"      {flag}"
+            if opt.help_text:
+                line += f"  {opt.help_text}"
+            print(line)
+
+        print()
+
+    # Recurse into sub-namespaces
+    for _, sub_ns in sorted(ns.sub_namespaces.items()):
+        if sub_ns.commands or sub_ns.sub_namespaces:
+            _print_namespace_reference(sub_ns, depth + 1)
+
+
+def _show_suggestions(namespace: Namespace, typo: str) -> None:
+    """Show fuzzy suggestions for an unknown command or namespace name."""
+    # Collect all candidate names: commands + synonyms + sub-namespaces
+    candidates = (
+        list(namespace.commands.keys())
+        + list(namespace.synonyms.keys())
+        + list(namespace.sub_namespaces.keys())
+    )
+    matches = difflib.get_close_matches(typo, candidates, n=3, cutoff=0.6)
+
+    if matches:
+        print(file=sys.stderr)
+        print("Did you mean?", file=sys.stderr)
+        for name in matches:
+            if name in namespace.synonyms:
+                canonical = namespace.synonyms[name]
+                desc = namespace.commands[canonical].description
+                print(f"  {name:<16}{desc} (synonym for {canonical})", file=sys.stderr)
+            elif name in namespace.commands:
+                desc = namespace.commands[name].description
+                print(f"  {name:<16}{desc}", file=sys.stderr)
+            else:
+                desc = namespace.sub_namespaces[name].description
+                print(f"  {name:<16}{desc}", file=sys.stderr)
+
+    print(file=sys.stderr)
+    _show_discovery(namespace, file=sys.stderr)
+
+
+def _show_discovery(namespace: Namespace, *, file: Any = None) -> None:
+    """Display available commands and sub-namespaces."""
+    if file is None:
+        file = sys.stdout
+
+    if namespace.path:
+        print(f"kd /{namespace.path}", file=file)
+    else:
+        print("kd — YouTrack CLI and SDK", file=file)
+    print(file=file)
+
+    if namespace.sub_namespaces:
+        print("Namespaces:", file=file)
+        for name, ns in sorted(namespace.sub_namespaces.items()):
+            print(f"  {name:<16}{ns.description}", file=file)
+        print(file=file)
+
+    if namespace.commands:
+        print("Commands:", file=file)
+        for name, cmd in sorted(namespace.commands.items()):
+            print(f"  {name:<16}{cmd.description}", file=file)
+        print(file=file)
+
+    # Show global options at root level
+    if not namespace.path:
+        print("Global options:", file=file)
+        for decl in GLOBAL_OPTIONS:
+            flag = f"--{decl.name}"
+            if decl.short_name:
+                flag += f", -{decl.short_name}"
+            print(f"  {flag:<16}{decl.help_text}", file=file)
+        print(file=file)
+
+        print("Output options:", file=file)
+        for decl in OUTPUT_OPTIONS:
+            flag = f"--{decl.name}"
+            if decl.short_name:
+                flag += f", -{decl.short_name}"
+            extra = ""
+            if decl.choices:
+                extra = f" ({', '.join(decl.choices)})"
+            print(f"  {flag:<16}{decl.help_text}{extra}", file=file)
+        print(file=file)

kd/cli/namespaces/__init__.py

@@ -0,0 +1,38 @@
+"""Namespace command implementations.
+
+Each sub-package exports a create_*_namespace() factory function
+that returns a configured Namespace with registered commands.
+"""
+
+from kd.cli.core.namespaces import NamespaceRegistry, apply_synonyms, load_synonyms
+from kd.cli.namespaces.alias import create_alias_namespace
+from kd.cli.namespaces.article import create_article_namespace
+from kd.cli.namespaces.init import InitCommand
+from kd.cli.namespaces.issue import create_issue_namespace
+from kd.cli.namespaces.primer import create_primer_namespace
+from kd.cli.namespaces.project import create_project_namespace
+from kd.cli.namespaces.query import create_query_namespace
+from kd.cli.namespaces.search import SearchCommand
+from kd.cli.namespaces.system import create_system_namespace
+from kd.cli.namespaces.tag import create_tag_namespace
+from kd.cli.namespaces.time import create_time_namespace
+from kd.cli.namespaces.user import create_user_namespace
+
+
+def register_all_namespaces(registry: NamespaceRegistry) -> None:
+    """Register all namespace trees in the registry."""
+    registry.root.register_command("init", InitCommand())
+    registry.root.register_command("search", SearchCommand())
+    registry.register_namespace(create_alias_namespace())
+    registry.register_namespace(create_article_namespace())
+    registry.register_namespace(create_system_namespace())
+    registry.register_namespace(create_project_namespace())
+    registry.register_namespace(create_issue_namespace())
+    registry.register_namespace(create_primer_namespace())
+    registry.register_namespace(create_query_namespace())
+    registry.register_namespace(create_tag_namespace())
+    registry.register_namespace(create_user_namespace())
+    registry.register_namespace(create_time_namespace())
+
+    # Apply built-in command synonyms (YTCTL-8)
+    apply_synonyms(registry.root, load_synonyms())