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

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

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

{kd_cli-2.1.5 → kd_cli-2.1.6}/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.6/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.6}/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.6}/kd/cli/namespaces/system/__init__.py

@@ -296,7 +296,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"],

{kd_cli-2.1.5 → kd_cli-2.1.6}/kd/config.py

@@ -452,7 +452,7 @@ def update_config_path(path: str, value: str, config_path: Path) -> tuple[str, A
             coerced = TypeAdapter(entry.annotation).validate_python(value)
         except ValidationError as e:
             details = _format_validation_errors(e)
-            raise ConfigError(f"Invalid value for {path}: {details}") from e
+            raise ConfigError(f"Invalid value for {path} in {config_path}: {details}") from e
 
     # Load raw YAML, capture original text for rollback.
     raw = _load_raw_yaml(config_path)
@@ -481,7 +481,7 @@ def update_config_path(path: str, value: str, config_path: Path) -> tuple[str, A
             ) from e
         details = _format_validation_errors(e)
         raise ConfigError(
-            f"Config would be invalid after setting {path}: {details}",
+            f"Config would be invalid after setting {path} in {config_path}: {details}",
         ) from e
 
     return path, coerced
@@ -864,7 +864,7 @@ def _resolve_connections(
             where = f" in {primary_path}"
             if isinstance(e, ValidationError):
                 d.trace("config", f"connection '{name}' validation error: {e!r}")
-                details = _format_validation_errors(e)
+                details = _format_validation_errors(e, key_origins)
             else:
                 details = str(e)
             message = f"Invalid connection '{name}'{where}: {details}"
@@ -873,17 +873,33 @@ def _resolve_connections(
     return result, origins
 
 
-def _format_validation_errors(err: ValidationError) -> str:
+def _format_validation_errors(
+    err: ValidationError,
+    key_origins: dict[str, ConnectionKeyOrigin] | None = None,
+) -> str:
     """Render a Pydantic ``ValidationError`` as a user-facing summary.
 
     Drops the ``input_value=...`` dump and the ``errors.pydantic.dev`` URL,
     keeping only ``<dotted-loc>: <msg>`` parts joined by ``; ``.
+
+    When *key_origins* is supplied, each locus is annotated with the config
+    file that contributed its top-level key, e.g.
+    ``default_project: Input should be a string (from /path/.kd/config.yaml)``.
+    Origin tracking is per-top-level-key because deep merges on
+    ``defaults`` and ``compatibility`` replace the whole sub-dict from
+    whichever tier wrote last.
     """
     parts: list[str] = []
     for item in err.errors():
-        loc = ".".join(str(p) for p in item.get("loc", ()))
+        loc_parts = item.get("loc", ())
+        loc = ".".join(str(p) for p in loc_parts)
         msg = item.get("msg", "")
-        parts.append(f"{loc}: {msg}" if loc else msg)
+        origin_suffix = ""
+        if key_origins and loc_parts:
+            top_key = str(loc_parts[0])
+            if top_key in key_origins:
+                origin_suffix = f" (from {key_origins[top_key].path})"
+        parts.append(f"{loc}: {msg}{origin_suffix}" if loc else msg)
     return "; ".join(parts) if parts else str(err)
 
 

{kd_cli-2.1.5 → kd_cli-2.1.6}/kd/connection.py

@@ -19,6 +19,9 @@ from kd.auth import resolve_connection_token
 from kd.exceptions import ConfigError
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from kd.config import ConnectionOrigin
     from kd.debug import DebugLog
 
 
@@ -132,6 +135,7 @@ def resolve_connection(
     connections: dict[str, ConnectionConfig],
     default_connection: str | None,
     *,
+    connection_origins: Mapping[str, ConnectionOrigin] | None = None,
     debug_log: DebugLog | None = None,
 ) -> ConnectionContext:
     """Resolve the active connection into a :class:`ConnectionContext`.
@@ -142,6 +146,9 @@ def resolve_connection(
         All parsed ``ConnectionConfig`` objects keyed by name.
     default_connection:
         Name of the connection to resolve (from ``default_connection`` config key).
+    connection_origins:
+        Per-connection provenance from :class:`ResolvedConfig`, used to
+        cite the originating config file in auth-error messages.
     debug_log:
         Optional debug logger.
     """
@@ -173,7 +180,13 @@ def resolve_connection(
     if debug_log:
         debug_log.info("connection", f"resolving connection '{default_connection}'")
 
-    token = resolve_connection_token(conn, debug_log=debug_log)
+    origin = connection_origins.get(default_connection) if connection_origins else None
+    token = resolve_connection_token(
+        conn,
+        name=default_connection,
+        origin=origin,
+        debug_log=debug_log,
+    )
 
     if debug_log:
         debug_log.info("connection", f"url={conn.url}")

{kd_cli-2.1.5 → kd_cli-2.1.6}/kd/exceptions.py

@@ -17,7 +17,16 @@ import yaml
 
 
 class KdError(Exception):
-    """Base exception for all kd errors."""
+    """Base exception for all kd errors.
+
+    Carries an optional :attr:`suggestion` that ``_print_error`` renders
+    as a ``Hint:`` line. Subclasses may pass it through their own
+    constructors or rely on this default.
+    """
+
+    def __init__(self, message: str, *, suggestion: str | None = None) -> None:
+        self.suggestion = suggestion
+        super().__init__(message)
 
 
 class AuthError(KdError):
@@ -28,8 +37,7 @@ class ConfigError(KdError):
     """Config file missing, malformed, or incomplete."""
 
     def __init__(self, message: str, suggestion: str | None = None) -> None:
-        self.suggestion = suggestion
-        super().__init__(message)
+        super().__init__(message, suggestion=suggestion)
 
 
 class APIError(KdError):
@@ -44,8 +52,7 @@ class APIError(KdError):
     ) -> None:
         self.status_code = status_code
         self.response_body = response_body
-        self.suggestion = suggestion
-        super().__init__(message)
+        super().__init__(message, suggestion=suggestion)
 
 
 class NotFoundError(APIError):

{kd_cli-2.1.5 → kd_cli-2.1.6}/kd/models/saved_query.py

@@ -36,7 +36,7 @@ class SavedQueryUpdate(BaseModel):
 
     All fields optional. Dump with ``exclude_none=True`` so the POST body only
     carries the fields the caller actually wants to change; YouTrack preserves
-    omitted fields (live-verified on ``vod.youtrack.cloud`` 2026-04-05).
+    omitted fields.
     """
 
     model_config = ConfigDict(populate_by_name=True)

{kd_cli-2.1.5 → kd_cli-2.1.6}/kd/resources/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.1.6] — 2026-04-17
+
+Milestone 005 — CLI friction audit, session S2. Two raise sites enriched so users land on the right file and the right fix.
+
+### Fixed
+- Missing-token errors now name the connection and URL, surface a copy-pasteable `token_cmd:` example, and cite the config file that declared `token_env:`. Previously the user saw only the env-var name — in a multi-connection setup, guesswork about which connection failed and which file to edit (KDCLI-72).
+- Config merge-validation errors cite the contributing file for each offending locus. A bad local override now names the local file per key; a bad global-only entry names the global file. `kd /system/config set` leaf-coercion errors name the target config path. Origin data was already tracked via `ConnectionOrigin` for `config list`; this release threads it into the user-visible error string too (KDCLI-69).
+
+### Changed
+- The `.suggestion` attribute now lives on the `KdError` base instead of being declared per-subclass. `_print_error` renders `Hint:` for any `KdError` with a suggestion — `AuthError` and `ValidationError` now carry suggestions alongside `APIError` and `ConfigError`. Internal plumbing; no CLI surface change.
+
+### Documentation
+- Replace `vod` with `support` in help-text examples, code docstrings, current-behavior design docs, specs, how-tos, and test fixtures. Historical records (session docs, CHANGELOG, shipped milestone close-outs) keep their `vod` references intact so the audit trail stays honest (KDCLI-30).
+
 ## [2.1.5] — 2026-04-17
 
 Milestone 005 — CLI friction audit, session S1. Four first-time-user surface fixes on the `--help` / `--output` axis.

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

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

{kd_cli-2.1.5 → kd_cli-2.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.1.5"
+version = "2.1.6"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"

kd_cli-2.1.5/kd/auth.py

@@ -1,96 +0,0 @@
-"""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.connection import ConnectionConfig
-    from kd.debug import DebugLog
-
-
-def resolve_connection_token(
-    conn: ConnectionConfig,
-    *,
-    debug_log: DebugLog | None = None,
-) -> str:
-    """Resolve the API token for a connection.
-
-    Parameters
-    ----------
-    conn:
-        The connection config whose auth sources to try.
-    debug_log:
-        Optional debug logger.
-
-    Returns
-    -------
-    str
-        The resolved token.
-
-    Raises
-    ------
-    AuthError
-        If no token can be resolved from any source.
-    """
-    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 AuthError(
-            f"Environment variable '{conn.token_env}' is not set. "
-            f"Export it or use 'token_cmd' instead."
-        )
-
-    raise AuthError(
-        "Connection has no auth source configured. "
-        "Set 'token_cmd' or 'token_env' in the connection config."
-    )
-
-
-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