kd-cli 2.1.5__tar.gz → 2.1.7__tar.gz

{kd_cli-2.1.5/kd_cli.egg-info → kd_cli-2.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.1.5
+Version: 2.1.7
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.1.5 → kd_cli-2.1.7}/kd/api/saved_queries.py

@@ -65,8 +65,7 @@ class SavedQueriesAPI:
         """List saved queries owned by a specific user.
 
         The literal string ``"me"`` is accepted as ``user_id`` and resolves
-        to the authenticated user server-side (verified against
-        ``vod.youtrack.cloud``).
+        to the authenticated user server-side.
         """
         data = self._http.get(
             f"/users/{user_id}/savedQueries",

kd_cli-2.1.7/kd/auth.py

@@ -0,0 +1,173 @@
+"""Connection-aware token resolution.
+
+Each connection resolves its token from one of two sources:
+
+1. ``token_cmd`` — shell command that prints the token to stdout.
+2. ``token_env`` — environment variable name containing the token.
+
+Priority: ``token_cmd`` > ``token_env``.  Secrets never live in config
+files — only references to external sources.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import TYPE_CHECKING
+
+from kd.exceptions import AuthError
+
+if TYPE_CHECKING:
+    from kd.config import ConnectionOrigin
+    from kd.connection import ConnectionConfig
+    from kd.debug import DebugLog
+
+
+def resolve_connection_token(
+    conn: ConnectionConfig,
+    *,
+    name: str | None = None,
+    origin: ConnectionOrigin | None = None,
+    debug_log: DebugLog | None = None,
+) -> str:
+    """Resolve the API token for a connection.
+
+    Parameters
+    ----------
+    conn:
+        The connection config whose auth sources to try.
+    name:
+        Optional connection name, used in error messages to name the
+        failing connection.
+    origin:
+        Optional per-key origin map, used to cite the exact config file
+        that declared the (now-broken) auth key.
+    debug_log:
+        Optional debug logger.
+
+    Returns
+    -------
+    str
+        The resolved token.
+
+    Raises
+    ------
+    AuthError
+        If no token can be resolved from any source. When *name* and
+        *origin* are supplied, the error carries a multi-line
+        ``.suggestion`` with connection-specific guidance and a
+        ``Config: <path>`` pointer.
+    """
+    if conn.token_cmd:
+        if debug_log:
+            debug_log.info("auth", f"running token_cmd: {conn.token_cmd}")
+        return _run_token_cmd(conn.token_cmd)
+
+    if conn.token_env:
+        if debug_log:
+            debug_log.info("auth", f"reading token from env var: {conn.token_env}")
+        value = os.environ.get(conn.token_env)
+        if value:
+            return value
+        raise _missing_token_error(conn, name, origin)
+
+    raise _no_auth_source_error(conn, name, origin)
+
+
+def _run_token_cmd(cmd: str) -> str:
+    """Execute a token command and return its stdout.
+
+    Raises :class:`AuthError` on non-zero exit or empty output.
+    """
+    try:
+        proc = subprocess.run(
+            cmd,
+            shell=True,  # noqa: S602 — user's own config, same trust as git credential.helper
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except subprocess.TimeoutExpired:
+        raise AuthError(f"token_cmd timed out after 10s: {cmd}") from None
+
+    if proc.returncode != 0:
+        stderr = proc.stderr.strip()
+        detail = f": {stderr}" if stderr else ""
+        raise AuthError(f"token_cmd failed (exit {proc.returncode}){detail}: {cmd}")
+
+    token = proc.stdout.strip()
+    if not token:
+        raise AuthError(f"token_cmd returned empty output: {cmd}")
+
+    return token
+
+
+def _missing_token_error(
+    conn: ConnectionConfig,
+    name: str | None,
+    origin: ConnectionOrigin | None,
+) -> AuthError:
+    """Build an ``AuthError`` for a ``token_env`` that points at an unset var."""
+    env_name = conn.token_env or "<token_env>"
+    where = _describe_connection(conn, name)
+    message = f"{where} needs a token — environment variable '{env_name}' is not set."
+    suggestion = _build_suggestion(
+        lines=[
+            f"Either export {env_name} or configure `token_cmd:` on the connection:",
+            f"  connections.{name or '<name>'}.token_cmd: gopass show -o path/to/token",
+        ],
+        origin=origin,
+        key="token_env",
+    )
+    return AuthError(message, suggestion=suggestion)
+
+
+def _no_auth_source_error(
+    conn: ConnectionConfig,
+    name: str | None,
+    origin: ConnectionOrigin | None,
+) -> AuthError:
+    """Build an ``AuthError`` for a connection with no ``token_cmd`` or ``token_env``."""
+    where = _describe_connection(conn, name)
+    message = f"{where} has no auth source configured."
+    suggestion = _build_suggestion(
+        lines=[
+            "Set one of `token_cmd:` or `token_env:` on the connection:",
+            f"  connections.{name or '<name>'}.token_cmd: gopass show -o path/to/token",
+            f"  connections.{name or '<name>'}.token_env: KD_{(name or 'NAME').upper()}_TOKEN",
+        ],
+        origin=origin,
+        key=None,
+    )
+    return AuthError(message, suggestion=suggestion)
+
+
+def _describe_connection(conn: ConnectionConfig, name: str | None) -> str:
+    """Render the ``Connection '<name>' (<url>)`` prefix, degraded when no name."""
+    if name:
+        return f"Connection '{name}' ({conn.url})"
+    return f"Connection ({conn.url})"
+
+
+def _build_suggestion(
+    *,
+    lines: list[str],
+    origin: ConnectionOrigin | None,
+    key: str | None,
+) -> str:
+    """Assemble a multi-line suggestion, appending ``Config: <path>`` when known.
+
+    When *origin* is provided, prefer the per-key origin for *key* (which
+    points at the exact file declaring that key); fall back to the
+    connection's primary path. Omit the line entirely when no origin is
+    known so tests and ad-hoc callers don't see a dangling ``Config:``.
+    """
+    path: str | None = None
+    if origin is not None:
+        if key and key in origin.keys:
+            path = origin.keys[key].path
+        else:
+            path = origin.path
+    if path:
+        lines = [*lines, f"Config: {path}"]
+    return "\n".join(lines)

{kd_cli-2.1.5 → kd_cli-2.1.7}/kd/cli/main.py

@@ -29,7 +29,7 @@ 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, ConfigError, KdError
+from kd.exceptions import KdError
 
 # Global options — single source of truth for extraction, help, and reference.
 GLOBAL_OPTIONS: list[OptionDeclaration] = [
@@ -121,7 +121,7 @@ def expand_toplevel_alias(
 def _print_error(error: KdError) -> None:
     """Print error with optional suggestion to stderr."""
     print(f"Error: {error}", file=sys.stderr)
-    if isinstance(error, (APIError, ConfigError)) and error.suggestion:
+    if error.suggestion:
         print(f"Hint: {error.suggestion}", file=sys.stderr)
 
 
@@ -272,6 +272,7 @@ def main(argv: list[str] | None = None) -> None:
             connection = resolve_connection(
                 connections=resolved.connections,
                 default_connection=resolved.default_connection_name,
+                connection_origins=resolved.connection_origins,
                 debug_log=debug_log,
             )
             client = YouTrackClient(

{kd_cli-2.1.5 → kd_cli-2.1.7}/kd/cli/namespaces/system/__init__.py

@@ -9,6 +9,7 @@ copy-on-write history for config and primer files.
 from __future__ import annotations
 
 import difflib
+from dataclasses import asdict
 from pathlib import Path
 from typing import Any
 
@@ -18,14 +19,15 @@ from kd.cli.core.option_registry import OptionDeclaration, OptionLayer, Resolved
 from kd.config import (
     DEFAULT_CONFIG_PATH,
     FLAT_KEYS,
-    LayerState,
     ResolvedConfig,
+    ShadowWarning,
+    detect_shadow,
     find_local_config,
-    load_config,
     resolve_config,
     update_config_path,
     walk_option_layers,
 )
+from kd.config_read import get_config_path
 from kd.config_schema import MISSING, ConfigKeyEntry, resolve_path, walk_schema
 from kd.exceptions import ConfigError, ValidationError
 from kd.history import (
@@ -273,7 +275,7 @@ class ConfigGetCommand(Command):
                 "source": str(rv.source),
                 "origin": rv.origin,
             }
-        resolved = _nested_get(rc, path)
+        resolved = get_config_path(rc, path)
         if resolved is None:
             return {"path": path, "value": None}
         return resolved
@@ -296,7 +298,7 @@ class ConfigSetCommand(Command):
             ),
             examples=[
                 "kd /system/config set default_connection corp",
-                "kd /system/config set connections.vod.default_project L9FRM --local",
+                "kd /system/config set connections.support.default_project BCO --local",
                 "kd /system/config set history.retention 50 --global",
             ],
             see_also=["/system/config get", "/system/config keys", "/system/config list"],
@@ -370,132 +372,43 @@ class ConfigSetCommand(Command):
         }
 
         if not options.command.get("no-shadow-warning", False):
-            warning = _detect_shadow(resolved_path, tier, options)
+            rc = resolve_config()
+            warning = detect_shadow(resolved_path, tier, rc, default_lookup=_lookup_builtin_default)
             if warning is not None:
-                result["warning"] = warning
+                result["warning"] = asdict(warning)
                 _emit_shadow_warning(warning)
 
         return result
 
 
-def _detect_shadow(path: str, tier: str, options: ResolvedOptions) -> dict[str, Any] | None:
-    """Return a warning payload if *path* (just written in *tier*) is shadowed.
-
-    Returns ``None`` when the path is not part of the command-option chain,
-    when the write landed at the winning layer, or when the post-write walker
-    reports no higher-priority layer with a value. Skips paths that don't map
-    to a specific ``<command_key>.<option>`` target — flat top-level writes and
-    connection-level flat writes are cross-command by nature and are not
-    flagged here.
-    """
-    rc = resolve_config()
-    classified = _classify_set_path(path, tier, rc.default_connection_name)
-    if classified is None:
-        return None
-    written_layer, command_key, option_name = classified
-
-    declared = _lookup_option(command_key, option_name)
-    builtin_default = declared.default if declared is not None else None
-
-    states = walk_option_layers(
-        option_name,
-        command_key,
-        _active_project(rc),
-        rc,
-        builtin_default=builtin_default,
-    )
-    winner = next((s for s in states if s.status == "winning"), None)
-    if winner is None or winner.layer >= written_layer:
-        return None  # write is active (equal) or nothing set (impossible post-write)
-
-    written = next((s for s in states if s.layer == written_layer), None)
-    hint_path = _shadow_hint_path(winner, command_key, option_name, rc)
-    return {
-        "written": {
-            "layer": written_layer,
-            "value": written.value if written else None,
-            "source": written.source if written else "",
-        },
-        "winning": {
-            "layer": winner.layer,
-            "value": winner.value,
-            "source": winner.source,
-            "origin": winner.origin,
-        },
-        "option": f"{command_key}.{option_name}",
-        "hint_path": hint_path,
-    }
-
-
-def _classify_set_path(
-    path: str, tier: str, active_connection: str | None
-) -> tuple[int, str, str] | None:
-    """Map a written config path to a chain layer + (command_key, option)."""
-    segs = path.split(".")
-    # defaults.<cmd>.<opt> — layer 4 (local) / 8 (global)
-    if len(segs) == 3 and segs[0] == "defaults":
-        layer = 4 if tier == "local" else 8
-        return layer, segs[1], segs[2]
-    # connections.<name>.defaults.<cmd>.<opt> — layer 6 when <name> is active
-    if (
-        len(segs) == 5
-        and segs[0] == "connections"
-        and segs[2] == "defaults"
-        and active_connection is not None
-        and segs[1] == active_connection
-    ):
-        return 6, segs[3], segs[4]
-    return None
-
-
-def _lookup_option(command_key: str, option_name: str) -> OptionDeclaration | None:
-    """Best-effort OptionDeclaration lookup; None if the registry cannot answer."""
+def _lookup_builtin_default(command_key: str, option_name: str) -> Any:
+    """Option-registry accessor passed to :func:`detect_shadow` for layer-10 hints."""
     try:
         options_map = _command_options_map()
     except Exception:
         return None
-    return options_map.get(command_key, {}).get(option_name)
-
-
-def _active_project(rc: ResolvedConfig) -> str | None:
-    """Project context for shadow detection — mirrors _determine_project's config path."""
-    return rc.default_project
-
-
-def _shadow_hint_path(
-    winner: LayerState, command_key: str, option_name: str, rc: ResolvedConfig
-) -> str | None:
-    """Suggest a path that would actually override the winning layer, if any.
-
-    For a winning connection-flat value, suggest
-    ``connections.<name>.defaults.<cmd>.<opt>`` which sits at layer 6 —
-    one step above layer 7 and scoped per-command.
-    """
-    if winner.layer == 7 and rc.default_connection_name is not None:
-        return f"connections.{rc.default_connection_name}.defaults.{command_key}.{option_name}"
-    return None
+    decl = options_map.get(command_key, {}).get(option_name)
+    return decl.default if decl is not None else None
 
 
-def _emit_shadow_warning(warning: dict[str, Any]) -> None:
+def _emit_shadow_warning(warning: ShadowWarning) -> None:
     """Render the shadow warning to stderr — non-fatal, user-readable."""
     import sys
 
-    written = warning["written"]
-    winning = warning["winning"]
-    option = warning["option"]
+    written = warning.written
+    winning = warning.winning
     lines = [
         "",
         (
-            f"Warning: wrote {option} = {written['value']!r} at layer {written['layer']} "
-            f"({written['source']}), but layer {winning['layer']} ({winning['source']}) "
-            f"= {winning['value']!r} shadows it."
+            f"Warning: wrote {warning.option} = {written['value']!r} at layer "
+            f"{written['layer']} ({written['source']}), but layer {winning['layer']} "
+            f"({winning['source']}) = {winning['value']!r} shadows it."
         ),
-        f"Run 'kd /system/config which {option}' for the full chain.",
+        f"Run 'kd /system/config which {warning.option}' for the full chain.",
     ]
-    hint = warning.get("hint_path")
-    if hint:
+    if warning.hint_path:
         lines.append("Hint: to override at a higher-priority layer, set:")
-        lines.append(f"  kd /system/config set {hint} {written['value']!r}")
+        lines.append(f"  kd /system/config set {warning.hint_path} {written['value']!r}")
     print("\n".join(lines), file=sys.stderr)
 
 
@@ -547,196 +460,6 @@ def _render_default(default: Any) -> str:
     return str(default)
 
 
-# ---------------------------------------------------------------------------
-# Nested config get
-# ---------------------------------------------------------------------------
-
-
-def _nested_get(rc: ResolvedConfig, path: str) -> dict[str, Any] | None:
-    """Resolve a nested dotted path to ``{path, value, source, origin}``.
-
-    Returns ``None`` when the path is legal but unset — caller wraps that
-    into ``{path, value: None}``.
-    """
-    segments = path.split(".")
-    root = segments[0]
-    if root == "connections" and len(segments) >= 3:
-        return _nested_get_connection(rc, segments, path)
-    if root == "defaults":
-        return _nested_get_from_section(
-            path, segments[1:], [("local", rc.local_defaults), ("global", rc.global_defaults)]
-        )
-    if root == "projects":
-        return _nested_get_project(rc, segments, path)
-    if root == "aliases" and len(segments) == 2:
-        return _nested_get_from_section(
-            path, segments[1:], [("local", rc.local_aliases), ("global", rc.global_aliases)]
-        )
-    if root == "history" and len(segments) == 2:
-        return _nested_get_history(path, segments[1])
-    return None
-
-
-def _nested_get_connection(
-    rc: ResolvedConfig, segments: list[str], path: str
-) -> dict[str, Any] | None:
-    name = segments[1]
-    conn = rc.connections.get(name)
-    if conn is None:
-        return None
-    # connections.<name>.<key>
-    if len(segments) == 3:
-        key = segments[2]
-        value = getattr(conn, key, None)
-        if value is None or (isinstance(value, (dict, list)) and not value):
-            return None
-        origin = rc.connection_origins.get(name)
-        key_origin = origin.keys.get(key) if origin else None
-        if key_origin is not None:
-            return {
-                "path": path,
-                "value": _render_value(value),
-                "source": key_origin.source,
-                "origin": key_origin.path,
-            }
-        return {
-            "path": path,
-            "value": _render_value(value),
-            "source": origin.source if origin else "",
-            "origin": origin.path if origin else "",
-        }
-    # connections.<name>.compatibility.<field>
-    if len(segments) == 4 and segments[2] == "compatibility":
-        compat = conn.compatibility
-        field_name = segments[3]
-        value = getattr(compat, field_name, None)
-        if value is None:
-            return None
-        origin = rc.connection_origins.get(name)
-        key_origin = origin.keys.get("compatibility") if origin else None
-        source = key_origin.source if key_origin else (origin.source if origin else "")
-        origin_path = key_origin.path if key_origin else (origin.path if origin else "")
-        return {
-            "path": path,
-            "value": _render_value(value),
-            "source": source,
-            "origin": origin_path,
-        }
-    # connections.<name>.defaults.<cmd>.<opt>
-    if len(segments) == 5 and segments[2] == "defaults":
-        cmd, opt = segments[3], segments[4]
-        defaults = conn.defaults.get(cmd) if isinstance(conn.defaults, dict) else None
-        if not isinstance(defaults, dict) or opt not in defaults:
-            return None
-        origin = rc.connection_origins.get(name)
-        key_origin = origin.keys.get("defaults") if origin else None
-        source = key_origin.source if key_origin else (origin.source if origin else "")
-        origin_path = key_origin.path if key_origin else (origin.path if origin else "")
-        return {
-            "path": path,
-            "value": _render_value(defaults[opt]),
-            "source": source,
-            "origin": origin_path,
-        }
-    return None
-
-
-def _nested_get_project(
-    rc: ResolvedConfig, segments: list[str], path: str
-) -> dict[str, Any] | None:
-    if len(segments) < 4:
-        return None
-    key = segments[1]
-    section = segments[2]
-    for source_label, projects in (("local", rc.local_projects), ("global", rc.global_projects)):
-        proj = projects.get(key)
-        if not isinstance(proj, dict):
-            continue
-        if section == "field_aliases" and len(segments) == 4:
-            aliases = proj.get("field_aliases")
-            if isinstance(aliases, dict) and segments[3] in aliases:
-                return {
-                    "path": path,
-                    "value": _render_value(aliases[segments[3]]),
-                    "source": source_label,
-                    "origin": "",
-                }
-        if section == "defaults" and len(segments) == 5:
-            defaults = proj.get("defaults")
-            if isinstance(defaults, dict):
-                cmd = defaults.get(segments[3])
-                if isinstance(cmd, dict) and segments[4] in cmd:
-                    return {
-                        "path": path,
-                        "value": _render_value(cmd[segments[4]]),
-                        "source": source_label,
-                        "origin": "",
-                    }
-    return None
-
-
-def _nested_get_from_section(
-    path: str,
-    remaining: list[str],
-    sources: list[tuple[str, dict[str, Any]]],
-) -> dict[str, Any] | None:
-    """Walk a flat or nested dict section across local/global sources."""
-    for source_label, section in sources:
-        value = _walk_dict(section, remaining)
-        if value is not None:
-            return {
-                "path": path,
-                "value": _render_value(value),
-                "source": source_label,
-                "origin": "",
-            }
-    return None
-
-
-def _walk_dict(data: Any, segments: list[str]) -> Any:
-    current: Any = data
-    for seg in segments:
-        if not isinstance(current, dict) or seg not in current:
-            return None
-        current = current[seg]
-    return current
-
-
-def _nested_get_history(path: str, key: str) -> dict[str, Any] | None:
-    """``history`` is not exposed on ResolvedConfig — read both tiers directly."""
-    for source_label, tier_path in (
-        ("local", find_local_config()),
-        ("global", DEFAULT_CONFIG_PATH),
-    ):
-        if tier_path is None or not tier_path.exists():
-            continue
-        cfg = load_config(tier_path)
-        value = getattr(cfg.history, key, None)
-        if value is None:
-            continue
-        # Only surface values actually written to the file, not schema defaults.
-        import yaml as _yaml
-
-        raw = _yaml.safe_load(tier_path.read_text()) or {}
-        history_block = raw.get("history") if isinstance(raw.get("history"), dict) else {}
-        if not isinstance(history_block, dict) or key not in history_block:
-            continue
-        return {
-            "path": path,
-            "value": _render_value(value),
-            "source": source_label,
-            "origin": str(tier_path),
-        }
-    return None
-
-
-def _render_value(value: Any) -> Any:
-    """Render a resolved value for output — keep scalars, stringify everything else."""
-    if isinstance(value, (str, int, float, bool)) or value is None:
-        return value
-    return str(value)
-
-
 class ConfigWhichCommand(Command):
     """Show which config files are active, or trace a single option's resolution."""
 
@@ -877,7 +600,7 @@ def _which_option_path(
         if connection_override not in rc.connections:
             known = ", ".join(sorted(rc.connections)) or "(none)"
             raise ConfigError(f"Unknown connection: {connection_override}. Known: {known}.")
-        active_rc = _activate_connection(rc, connection_override)
+        active_rc = rc.with_active_connection(connection_override)
     active_project = project_override  # None → no project layer
 
     states = walk_option_layers(
@@ -915,33 +638,6 @@ def _which_option_path(
     }
 
 
-def _activate_connection(rc: ResolvedConfig, name: str) -> ResolvedConfig:
-    """Return a derived ResolvedConfig with *name* as the active connection."""
-    conn = rc.connections[name]
-    conn_defaults = conn.defaults
-    conn_flat: dict[str, Any] = {}
-    if conn.output is not None:
-        conn_flat["output"] = conn.output
-    if conn.limit is not None:
-        conn_flat["limit"] = conn.limit
-    return ResolvedConfig(
-        rc.entries,
-        local_defaults=rc.local_defaults,
-        global_defaults=rc.global_defaults,
-        local_projects=rc.local_projects,
-        global_projects=rc.global_projects,
-        local_flat=rc.local_flat,
-        global_flat=rc.global_flat,
-        local_aliases=rc.local_aliases,
-        global_aliases=rc.global_aliases,
-        connections=rc.connections,
-        connection_origins=rc.connection_origins,
-        default_connection_name=name,
-        connection_defaults=conn_defaults,
-        connection_flat=conn_flat,
-    )
-
-
 def _command_options_map() -> dict[str, dict[str, OptionDeclaration]]:
     """Walk the registered namespace tree and return ``{command_key: {opt: decl}}``.