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

{kd_cli-2.1.4/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.4
+Version: 2.1.6
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.1.4 → 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.4 → kd_cli-2.1.6}/kd/cli/core/command_base.py

@@ -114,8 +114,6 @@ class Command(ABC):
                 if opt.aliases:
                     alias_str = ", ".join(f"--{a}" for a in opt.aliases)
                     flag += f" (alias: {alias_str})"
-                if opt.choices:
-                    flag += f"  ({', '.join(opt.choices)})"
                 if opt.help_text:
                     flag += f"    {opt.help_text}"
                 lines.append(flag)

{kd_cli-2.1.4 → kd_cli-2.1.6}/kd/cli/core/option_registry.py

@@ -253,7 +253,7 @@ OUTPUT_OPTIONS: list[OptionDeclaration] = [
         layer=OptionLayer.OUTPUT,
         type=str,
         choices=["table", "json", "yaml", "md"],
-        help_text="Output format (table, json, yaml, md)",
+        help_text="Output format: table|json|yaml|md (default: table)",
     ),
     OptionDeclaration(
         name="fields",

{kd_cli-2.1.4 → 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(
@@ -503,8 +504,6 @@ def _show_reference(
             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()
@@ -539,8 +538,6 @@ def _print_namespace_reference(ns: Namespace, depth: int = 0) -> None:
             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}"
@@ -621,8 +618,5 @@ def _show_discovery(namespace: Namespace, *, file: Any = None) -> None:
             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(f"  {flag:<16}{decl.help_text}", file=file)
         print(file=file)

{kd_cli-2.1.4 → kd_cli-2.1.6}/kd/cli/namespaces/primer/__init__.py

@@ -10,7 +10,12 @@ 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.cli.core.option_registry import (
+    OptionDeclaration,
+    OptionLayer,
+    ResolvedOptions,
+    project_option,
+)
 from kd.cli.input import resolve_text_input
 from kd.exceptions import ValidationError
 from kd.primer import (
@@ -25,6 +30,26 @@ from kd.primer import (
 )
 
 
+def _assert_workspace_project(command: Command, options: ResolvedOptions) -> None:
+    """Enforce the ``--project`` assertion on workspace-scoped primer commands.
+
+    The primer lives in ``.kd/primer.yaml`` and has no project dimension.
+    ``--project`` is accepted as an assertion of which workspace's primer the
+    caller thinks it's editing: matches ``default_project`` → silent no-op;
+    mismatches → raise so an agent running from the wrong workspace fails loud.
+    """
+    asserted = options.command.get("project")
+    if not asserted:
+        return
+    current = command.config.default_project
+    if current and asserted != current:
+        raise ValidationError(
+            f"Primer is workspace-scoped. --project={asserted} does not match "
+            f"this workspace's default_project={current}. To edit {asserted}'s "
+            f"primer, run from that workspace."
+        )
+
+
 # ---------------------------------------------------------------------------
 # /primer show (root default)
 # ---------------------------------------------------------------------------
@@ -46,19 +71,16 @@ class PrimerShowCommand(Command):
             ],
             see_also=["/primer/note list", "/primer/article list"],
         )
+        self.display_hint = "primer_show"
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
         data = load_primer()
-        if not data.notes and not data.articles:
-            return None
-        result: dict[str, Any] = {}
-        if data.notes:
-            result["notes"] = [{"#": i + 1, "note": n} for i, n in enumerate(data.notes)]
-        if data.articles:
-            result["articles"] = [{"id": a.id, "summary": a.summary or ""} for a in data.articles]
-        return result
+        return {
+            "notes": [{"#": i + 1, "note": n} for i, n in enumerate(data.notes)],
+            "articles": [{"id": a.id, "summary": a.summary or ""} for a in data.articles],
+        }
 
 
 # ---------------------------------------------------------------------------
@@ -93,6 +115,7 @@ class PrimerNoteAddCommand(Command):
         super().__init__(
             "add",
             "Add a primer note",
+            requires_config=True,
             usage="kd /primer/note add TEXT",
             long_description="Appends a note to the project primer.  TEXT can be inline, "
             "@file to read from a file, or - to read from stdin.",
@@ -103,9 +126,13 @@ class PrimerNoteAddCommand(Command):
             see_also=["/primer/note list", "/primer/note remove"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if not args:
             raise ValidationError("Usage: kd /primer/note add TEXT")
         text = resolve_text_input(" ".join(args))
@@ -122,6 +149,7 @@ class PrimerNoteRemoveCommand(Command):
         super().__init__(
             "remove",
             "Remove a primer note by index or all notes",
+            requires_config=True,
             usage="kd /primer/note remove INDEX | --all",
             long_description="Removes the note at the given 1-based index, or all notes "
             "if --all is passed.  Use '/primer/note list' to see current indices.",
@@ -142,10 +170,12 @@ class PrimerNoteRemoveCommand(Command):
                 help_text="Remove all notes",
             )
         )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if options.command.get("all"):
             count = clear_notes()
             return {"ok": True, "action": "clear", "removed": count}
@@ -166,6 +196,7 @@ class PrimerNoteUpdateCommand(Command):
         super().__init__(
             "update",
             "Replace a primer note by index",
+            requires_config=True,
             usage="kd /primer/note update INDEX TEXT",
             long_description="Replaces the note at the given 1-based index with new text.  "
             "TEXT can be inline, @file to read from a file, or - to read from stdin.  "
@@ -177,9 +208,13 @@ class PrimerNoteUpdateCommand(Command):
             see_also=["/primer/note list", "/primer/note remove"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if not args:
             raise ValidationError("Usage: kd /primer/note update INDEX TEXT")
         try:
@@ -227,6 +262,7 @@ class PrimerArticleAddCommand(Command):
         super().__init__(
             "add",
             "Pin an article to the primer",
+            requires_config=True,
             usage="kd /primer/article add ARTICLE_ID [--summary S]",
             long_description="Adds a YouTrack article reference to the project primer.  "
             "Use --summary to store a description alongside the ID.",
@@ -246,10 +282,12 @@ class PrimerArticleAddCommand(Command):
                 help_text="Description to store with the article reference",
             )
         )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if not args:
             raise ValidationError("Usage: kd /primer/article add ARTICLE_ID")
         article_id = args[0]
@@ -268,6 +306,7 @@ class PrimerArticleRemoveCommand(Command):
         super().__init__(
             "remove",
             "Unpin an article or all articles",
+            requires_config=True,
             usage="kd /primer/article remove ARTICLE_ID | --all",
             long_description="Removes the article with the given ID from the primer, "
             "or all pinned articles if --all is passed.",
@@ -288,10 +327,12 @@ class PrimerArticleRemoveCommand(Command):
                 help_text="Remove all pinned articles",
             )
         )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         if options.command.get("all"):
             count = clear_articles()
             return {"ok": True, "action": "clear", "removed": count}

{kd_cli-2.1.4 → 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.4 → kd_cli-2.1.6}/kd/cli/output.py

@@ -1,13 +1,14 @@
 """Output formatting.
 
 Renders command results in multiple formats:
-- table: human-readable tabular output (default for TTY)
+- table: human-readable tabular output (unconditional default)
 - 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.
+Default is ``table`` regardless of stdout context; TTY state does not
+influence format (ADR-006 — TTY detection stays config-first). Consumers
+that want JSON or YAML pass ``-o json`` / ``-o yaml`` explicitly.
 
 Value normalization runs before serialization: epoch-ms timestamps become
 ISO 8601, enums become their ``.value``, and nested collections render
@@ -17,7 +18,6 @@ cleanly in every format.
 from __future__ import annotations
 
 import json
-import sys
 from datetime import datetime, timezone
 from typing import Any
 
@@ -75,7 +75,8 @@ class OutputFormatter:
 
         Args:
             data: Structured data from a command.
-            fmt: Output format. Auto-detected if None (TTY->table, pipe->json).
+            fmt: Output format. Defaults to ``"table"`` when None; TTY state
+                does not influence the default (ADR-006).
             fields: Comma-separated field names to include.
             display_hint: Rendering hint from the command (e.g. ``"tree"``).
         """
@@ -87,12 +88,28 @@ class OutputFormatter:
         normalized: list[dict[str, Any]] | dict[str, Any] = self._normalize(data)
 
         if fmt is None:
-            fmt = "table" if sys.stdout.isatty() else "json"
+            fmt = "table"
 
         # 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)
 
+        # Primer show: table/md formats drop empty sections so a notes-only
+        # primer renders without an empty "articles" row. When both sections
+        # are empty, show a populate hint. json/yaml pass through unchanged.
+        if (
+            display_hint == "primer_show"
+            and fmt in ("table", "md")
+            and isinstance(normalized, dict)
+        ):
+            if not normalized.get("notes") and not normalized.get("articles"):
+                return (
+                    "Primer is empty.\n"
+                    '  Populate with: kd /primer/note add "<text>"\n'
+                    "                 kd /primer/article add <ARTICLE_ID>"
+                )
+            normalized = {k: v for k, v in normalized.items() if v}
+
         field_list = [f.strip() for f in fields.split(",")] if fields else None
 
         match fmt:

{kd_cli-2.1.4 → 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.4 → 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.4 → 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.4 → 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.4 → kd_cli-2.1.6}/kd/resources/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.
+
+### Fixed
+- `--help`, `--reference`, and per-command help now render the `--output` choices list exactly once. The literal help text carries the list and the default (`Output format: table|json|yaml|md (default: table)`); four renderer sites that previously auto-appended `(table, json, yaml, md)` a second time stopped doing so (KDCLI-73).
+- `kd` no longer flips the default output format to JSON when stdout is a pipe. `table` is the unconditional default across TTY, pipes, and subprocess contexts, per [ADR-006](../../docs/design/ADR-006-tty-detection-config-first.md). Consumers wanting JSON or YAML pass `-o json` / `-o yaml` explicitly (KDCLI-74).
+- `kd /primer show` on an empty primer now prints a populate hint in `table` and `md` output, instead of rendering zero bytes. JSON and YAML continue to return the canonical empty container `{"notes": [], "articles": []}` (KDCLI-76).
+- `kd /primer/note add`, `kd /primer/article add`, and their sibling `remove` / `update` commands accept `--project/-p` as a workspace assertion. A match against the active connection's `default_project` is a silent no-op; a mismatch raises a `ValidationError` naming both the asserted and resolved keys so an agent running from the wrong workspace fails loud instead of silently writing to the wrong primer (KDCLI-70).
+
 ## [2.1.4] — 2026-04-15
 
 ### Fixed

{kd_cli-2.1.4 → 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.4
+Version: 2.1.6
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

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

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

kd_cli-2.1.4/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