kd-cli 2.0.4__py3-none-any.whl

kd/connection.py

@@ -0,0 +1,156 @@
+"""Named connection configuration and runtime resolution.
+
+A connection represents a complete working context: URL, auth source,
+defaults, and compatibility profile for a single YouTrack instance.
+
+Config-level models (:class:`ConnectionConfig`, :class:`CompatibilityConfig`)
+map directly to YAML.  :class:`ConnectionContext` is the frozen runtime object
+that commands and the SDK receive after token resolution and override merging.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, model_validator
+
+from kd.auth import resolve_connection_token
+from kd.exceptions import ConfigError
+
+if TYPE_CHECKING:
+    from kd.debug import DebugLog
+
+
+# ---------------------------------------------------------------------------
+# Config models (YAML ↔ Pydantic)
+# ---------------------------------------------------------------------------
+
+
+class CompatibilityConfig(BaseModel):
+    """Per-connection compatibility settings.
+
+    Only ``pinned`` mode in M031.  ``probe`` mode arrives in M033.
+    """
+
+    target: str = "auto"
+    mode: Literal["pinned"] = "pinned"
+
+
+class ConnectionConfig(BaseModel):
+    """One named connection in the ``connections:`` config section."""
+
+    provider: str = "youtrack"
+    url: str
+    token_cmd: str | None = None
+    token_env: str | None = None
+    default_project: str | None = None
+    output: str | None = None
+    limit: int | None = None
+    defaults: dict[str, dict[str, Any]] = {}
+    compatibility: CompatibilityConfig = CompatibilityConfig()
+
+    @model_validator(mode="after")
+    def _require_auth_source(self) -> ConnectionConfig:
+        if not self.token_cmd and not self.token_env:
+            msg = (
+                "Connection must specify at least one of 'token_cmd' or 'token_env'. "
+                "Secrets are never stored as raw values in config."
+            )
+            raise ValueError(msg)
+        return self
+
+
+# ---------------------------------------------------------------------------
+# Runtime context (frozen, post-resolution)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ConnectionContext:
+    """Resolved runtime state for the active connection.
+
+    Created by :func:`resolve_connection` after token resolution and
+    override merging.  Commands receive this — never raw config models.
+    """
+
+    name: str
+    provider: str
+    base_url: str
+    token: str
+    default_project: str | None
+    output: str | None
+    limit: int | None
+    defaults: dict[str, dict[str, Any]]
+    compat_tier: str
+    capabilities: frozenset[str]  # empty in M031, populated in M033
+
+
+# ---------------------------------------------------------------------------
+# Connection resolution
+# ---------------------------------------------------------------------------
+
+
+def resolve_connection(
+    connections: dict[str, ConnectionConfig],
+    default_connection: str | None,
+    *,
+    debug_log: DebugLog | None = None,
+) -> ConnectionContext:
+    """Resolve the active connection into a :class:`ConnectionContext`.
+
+    Parameters
+    ----------
+    connections:
+        All parsed ``ConnectionConfig`` objects keyed by name.
+    default_connection:
+        Name of the connection to resolve (from ``default_connection`` config key).
+    debug_log:
+        Optional debug logger.
+    """
+    if not connections:
+        raise ConfigError(
+            "No connections configured. Add a 'connections:' section to your config "
+            "(run 'kd init' to scaffold one)."
+        )
+
+    if not default_connection:
+        if len(connections) == 1:
+            default_connection = next(iter(connections))
+        else:
+            names = ", ".join(sorted(connections))
+            raise ConfigError(
+                f"No default_connection set and multiple connections exist ({names}). "
+                "Use -c <name> or set 'default_connection' in your config."
+            )
+
+    if default_connection not in connections:
+        names = ", ".join(sorted(connections))
+        raise ConfigError(
+            f"Connection '{default_connection}' not found. Available connections: {names}. "
+            "Use -c <name> or set 'default_connection' in your config."
+        )
+
+    conn = connections[default_connection]
+
+    if debug_log:
+        debug_log.info("connection", f"resolving connection '{default_connection}'")
+
+    token = resolve_connection_token(conn, debug_log=debug_log)
+
+    if debug_log:
+        debug_log.info("connection", f"url={conn.url}")
+        debug_log.info("connection", f"compat_tier={conn.compatibility.target}")
+
+    return ConnectionContext(
+        name=default_connection,
+        provider=conn.provider,
+        base_url=conn.url,
+        token=token,
+        default_project=conn.default_project,
+        output=conn.output,
+        limit=conn.limit,
+        defaults=conn.defaults,
+        compat_tier=conn.compatibility.target,
+        capabilities=frozenset(),
+    )

kd/debug.py

@@ -0,0 +1,107 @@
+"""Progressive debug logging.
+
+Three verbosity levels via stacking ``-D`` flags:
+
+- ``-D``   (info):  high-level flow — config source, API status, item count
+- ``-DD``  (debug): request details, config chain, retries, elapsed timestamps
+- ``-DDD`` (trace): full bodies, headers, per-source walk, correlation ID
+
+All output goes to **stderr** so stdout remains pipeable.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+import uuid
+from enum import IntEnum
+
+
+class DebugLevel(IntEnum):
+    """Verbosity levels for diagnostic output."""
+
+    SILENT = 0
+    INFO = 1
+    DEBUG = 2
+    TRACE = 3
+
+
+class DebugLog:
+    """Component-tagged diagnostic logger writing to stderr.
+
+    Create once per invocation and thread through the call stack
+    or retrieve via :func:`get_debug_log`.
+    """
+
+    def __init__(self, level: DebugLevel = DebugLevel.SILENT) -> None:
+        self._level = level
+        self._start = time.monotonic()
+        self._correlation_id = uuid.uuid4().hex[:8]
+
+    @property
+    def level(self) -> DebugLevel:
+        """Current verbosity level (read-only)."""
+        return self._level
+
+    def info(self, component: str, message: str) -> None:
+        """Emit at level 1 (info) — high-level flow."""
+        if self._level >= DebugLevel.INFO:
+            self._emit("info", component, message)
+
+    def debug(self, component: str, message: str) -> None:
+        """Emit at level 2 (debug) — request details, config chain."""
+        if self._level >= DebugLevel.DEBUG:
+            self._emit("debug", component, message)
+
+    def trace(self, component: str, message: str) -> None:
+        """Emit at level 3 (trace) — full bodies, headers, walk."""
+        if self._level >= DebugLevel.TRACE:
+            self._emit("trace", component, message)
+
+    def _emit(self, level: str, component: str, message: str) -> None:
+        parts: list[str] = [f"[{level:<5}]", f"({component})"]
+        if self._level >= DebugLevel.TRACE:
+            parts.append(f"[{self._correlation_id}]")
+        if self._level >= DebugLevel.DEBUG:
+            elapsed = time.monotonic() - self._start
+            parts.append(f"+{elapsed:.1f}s")
+        parts.append(message)
+        print("  ".join(parts), file=sys.stderr)
+
+
+def redact_token(token: str) -> str:
+    """Redact an API token for debug display.
+
+    Shows the first 8 characters followed by ``***``.
+    Short or empty tokens become just ``***``.
+    """
+    if len(token) >= 8:
+        return token[:8] + "***"
+    return "***"
+
+
+# ── Module-level singleton ──────────────────────────────────────────
+
+_log: DebugLog | None = None
+
+
+def init_debug_log(level: DebugLevel) -> DebugLog:
+    """Create and store the module-level :class:`DebugLog`.
+
+    Called once from ``main()`` after parsing the ``-D`` flags.
+    Returns the new instance for explicit threading.
+    """
+    global _log  # noqa: PLW0603
+    _log = DebugLog(level)
+    return _log
+
+
+def get_debug_log() -> DebugLog:
+    """Return the module-level :class:`DebugLog`.
+
+    Returns a silent (level 0) instance when :func:`init_debug_log`
+    has not been called — callers never need to guard against ``None``.
+    """
+    if _log is not None:
+        return _log
+    return DebugLog()

kd/exceptions.py

@@ -0,0 +1,189 @@
+"""Exception hierarchy for kd.
+
+All kd exceptions inherit from KdError. API-layer exceptions
+carry the HTTP status code and response body for debugging.
+
+Error messages from the YouTrack API are rewritten into user-friendly
+text using regex mappings loaded from ``resources/error-messages.yaml``.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import re
+from typing import Any
+
+import yaml
+
+
+class KdError(Exception):
+    """Base exception for all kd errors."""
+
+
+class AuthError(KdError):
+    """Token missing, invalid, or expired."""
+
+
+class ConfigError(KdError):
+    """Config file missing, malformed, or incomplete."""
+
+
+class APIError(KdError):
+    """HTTP error from YouTrack or Hub API."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        response_body: str = "",
+        suggestion: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.response_body = response_body
+        self.suggestion = suggestion
+        super().__init__(message)
+
+
+class NotFoundError(APIError):
+    """404 — entity does not exist."""
+
+    def __init__(
+        self,
+        message: str,
+        response_body: str = "",
+        suggestion: str | None = None,
+    ) -> None:
+        super().__init__(404, message, response_body, suggestion)
+
+
+class ConflictError(APIError):
+    """409 — duplicate project key, etc."""
+
+    def __init__(
+        self,
+        message: str,
+        response_body: str = "",
+        suggestion: str | None = None,
+    ) -> None:
+        super().__init__(409, message, response_body, suggestion)
+
+
+class PermissionDeniedError(APIError):
+    """403 — insufficient permissions for the requested operation."""
+
+    def __init__(
+        self,
+        message: str,
+        response_body: str = "",
+        suggestion: str | None = None,
+    ) -> None:
+        super().__init__(403, message, response_body, suggestion)
+
+
+class ValidationError(KdError):
+    """Invalid input before API call."""
+
+
+# ---------------------------------------------------------------------------
+# Error message enrichment
+# ---------------------------------------------------------------------------
+
+_ErrorMapping = dict[str, Any]
+_error_mappings: list[_ErrorMapping] | None = None
+
+
+def _load_mappings() -> list[_ErrorMapping]:
+    """Load and compile error message mappings from the resource file.
+
+    Each entry supports three optional filters — ``status``, ``path``,
+    and ``pattern`` — plus a required ``message`` and an optional
+    ``suggestion``. All present filters must match for the rule to apply.
+    """
+    global _error_mappings  # noqa: PLW0603
+    if _error_mappings is not None:
+        return _error_mappings
+
+    raw = (
+        importlib.resources.files("kd.resources")
+        .joinpath("error-messages.yaml")
+        .read_text(encoding="utf-8")
+    )
+    entries: list[dict[str, Any]] = yaml.safe_load(raw) or []
+    compiled: list[_ErrorMapping] = []
+    for e in entries:
+        compiled.append(
+            {
+                "status": e.get("status"),
+                "path_re": re.compile(e["path"]) if e.get("path") else None,
+                "msg_re": re.compile(e["pattern"]) if e.get("pattern") else None,
+                "message": e["message"],
+                "suggestion": e.get("suggestion", ""),
+            }
+        )
+    _error_mappings = compiled
+    return _error_mappings
+
+
+def _substitute(
+    template: str,
+    named: dict[str, str],
+    positional: tuple[str | None, ...],
+) -> str:
+    """Replace ``{name}`` and ``{1}..{N}`` placeholders in *template*.
+
+    Unmatched optional groups (``None``) are skipped.
+    """
+    out = template
+    for key, named_val in named.items():
+        out = out.replace(f"{{{key}}}", named_val)
+    for i, pos_val in enumerate(positional, 1):
+        if pos_val is not None:
+            out = out.replace(f"{{{i}}}", pos_val)
+    return out
+
+
+def enrich_error(
+    message: str,
+    *,
+    status: int | None = None,
+    path: str | None = None,
+) -> tuple[str, str | None]:
+    """Match *message* against known API error patterns.
+
+    Rules may filter on HTTP ``status``, request URL ``path``, and/or
+    the extracted response ``message`` text. All present filters must
+    match. The first matching rule wins.
+
+    Returns ``(rewritten_message, suggestion)`` if a rule matches,
+    or ``(message, None)`` otherwise.
+    """
+    for mapping in _load_mappings():
+        if mapping["status"] is not None and mapping["status"] != status:
+            continue
+
+        path_match: re.Match[str] | None = None
+        if mapping["path_re"] is not None:
+            if path is None:
+                continue
+            path_match = mapping["path_re"].search(path)
+            if path_match is None:
+                continue
+
+        msg_match: re.Match[str] | None = None
+        if mapping["msg_re"] is not None:
+            msg_match = mapping["msg_re"].search(message)
+            if msg_match is None:
+                continue
+
+        named: dict[str, str] = {}
+        if path_match is not None:
+            named.update({k: v for k, v in path_match.groupdict().items() if v is not None})
+        if msg_match is not None:
+            named.update({k: v for k, v in msg_match.groupdict().items() if v is not None})
+        positional = msg_match.groups() if msg_match is not None else ()
+
+        rewritten = _substitute(mapping["message"], named, positional)
+        suggestion_tmpl = mapping["suggestion"] or None
+        suggestion = _substitute(suggestion_tmpl, named, positional) if suggestion_tmpl else None
+        return rewritten, suggestion
+    return message, None

kd/history.py

@@ -0,0 +1,169 @@
+"""Copy-on-write history for config and primer files.
+
+Provides automatic snapshots before every mutation, retention pruning,
+atomic file writes, and diff utilities. Snapshot files are stored in a
+``history/`` subdirectory next to the original file.
+
+Phase 1 — local snapshots only. Git auto-commit is deferred to Phase 2.
+"""
+
+from __future__ import annotations
+
+import difflib
+import logging
+import os
+import shutil
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import NamedTuple
+
+from kd.exceptions import ConfigError, KdError
+
+log = logging.getLogger(__name__)
+
+DEFAULT_RETENTION = 20
+
+
+# ---------------------------------------------------------------------------
+# Atomic writes
+# ---------------------------------------------------------------------------
+
+
+def atomic_write_text(path: Path, text: str) -> None:
+    """Write *text* to *path* atomically.
+
+    Writes to a temp file in the same directory, then ``os.replace``
+    to swap. Either the new content is fully committed or the old
+    content is fully intact.
+    """
+    dir_ = str(path.parent) if str(path.parent) else "."
+    fd, tmp = tempfile.mkstemp(dir=dir_, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as f:
+            f.write(text)
+        os.replace(tmp, path)
+    except OSError as e:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise KdError(f"Cannot write to {path}: {e}") from e
+
+
+# ---------------------------------------------------------------------------
+# Timestamp helpers
+# ---------------------------------------------------------------------------
+
+_TS_FORMAT = "%Y-%m-%dT%H-%M-%S"
+
+
+def _timestamp() -> str:
+    """Return a filesystem-safe ISO 8601 timestamp (UTC, second precision)."""
+    return datetime.now(timezone.utc).strftime(_TS_FORMAT)
+
+
+def _parse_timestamp(ts: str) -> datetime:
+    """Parse a filesystem-safe timestamp back to datetime."""
+    return datetime.strptime(ts, _TS_FORMAT).replace(tzinfo=timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Snapshot operations
+# ---------------------------------------------------------------------------
+
+
+def snapshot_before_write(path: Path, *, retention: int = DEFAULT_RETENTION) -> Path | None:
+    """Copy *path* to ``<parent>/history/<name>.<timestamp>`` before mutation.
+
+    Returns the snapshot path, or ``None`` if the file does not exist yet
+    (first write — nothing to snapshot). Prunes oldest snapshots beyond
+    *retention*. Best-effort: failures log a warning but do not block the
+    caller's write.
+    """
+    if not path.exists():
+        return None
+    try:
+        history_dir = path.parent / "history"
+        history_dir.mkdir(parents=True, exist_ok=True)
+        snapshot_name = f"{path.name}.{_timestamp()}"
+        snapshot_path = history_dir / snapshot_name
+        shutil.copy2(path, snapshot_path)
+        _prune_snapshots(history_dir, path.name, retention)
+        return snapshot_path
+    except OSError as e:
+        log.warning("Failed to snapshot %s: %s", path, e)
+        return None
+
+
+def _prune_snapshots(history_dir: Path, filename: str, retention: int) -> None:
+    """Remove oldest snapshots of *filename* beyond *retention* count."""
+    snapshots = _sorted_snapshots(history_dir, filename)
+    for info in snapshots[retention:]:
+        try:
+            info.path.unlink()
+        except OSError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Listing and lookup
+# ---------------------------------------------------------------------------
+
+
+class SnapshotInfo(NamedTuple):
+    """Metadata for a single snapshot file."""
+
+    path: Path
+    timestamp: str
+    size: int
+
+
+def list_snapshots(history_dir: Path, filename: str) -> list[SnapshotInfo]:
+    """Return snapshots for *filename*, newest first.
+
+    Returns an empty list if the history directory does not exist.
+    """
+    if not history_dir.is_dir():
+        return []
+    return _sorted_snapshots(history_dir, filename)
+
+
+def _sorted_snapshots(history_dir: Path, filename: str) -> list[SnapshotInfo]:
+    """Glob and sort snapshots for *filename*, newest first."""
+    prefix = f"{filename}."
+    results: list[SnapshotInfo] = []
+    for entry in history_dir.iterdir():
+        if entry.name.startswith(prefix) and entry.is_file():
+            ts = entry.name[len(prefix) :]
+            try:
+                _parse_timestamp(ts)
+            except ValueError:
+                continue  # skip files that don't match the timestamp format
+            results.append(SnapshotInfo(path=entry, timestamp=ts, size=entry.stat().st_size))
+    results.sort(key=lambda s: s.timestamp, reverse=True)
+    return results
+
+
+def get_snapshot_path(history_dir: Path, filename: str, timestamp: str) -> Path:
+    """Resolve a snapshot by timestamp, or raise ``ConfigError``."""
+    path = history_dir / f"{filename}.{timestamp}"
+    if not path.is_file():
+        raise ConfigError(f"Snapshot not found: {path.name}")
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Diff
+# ---------------------------------------------------------------------------
+
+
+def diff_text(text_a: str, text_b: str, label_a: str, label_b: str) -> str:
+    """Return a unified diff between two text strings.
+
+    Returns an empty string when the texts are identical.
+    """
+    lines_a = text_a.splitlines(keepends=True)
+    lines_b = text_b.splitlines(keepends=True)
+    diff = difflib.unified_diff(lines_a, lines_b, fromfile=label_a, tofile=label_b)
+    return "".join(diff)

kd/models/__init__.py

@@ -0,0 +1,75 @@
+"""Pydantic models for YouTrack entities.
+
+All models use field aliases to map between Python snake_case
+and YouTrack's camelCase API responses.
+"""
+
+from kd.models.article import Article, ArticleCreate, ArticleRef, ArticleUpdate
+from kd.models.assist import AssistResponse, AssistSuggestion
+from kd.models.attachment import Attachment
+from kd.models.comment import Comment, CommentCreate
+from kd.models.common import FieldSet, IdEntity, NamedEntity
+from kd.models.issue import CustomField, Issue, IssueCreate, IssueUpdate
+from kd.models.project import (
+    BundleValue,
+    Project,
+    ProjectCreate,
+    ProjectCustomField,
+    TimeTrackingSettings,
+)
+from kd.models.saved_query import (
+    QueryValidationResult,
+    SavedQuery,
+    SavedQueryCreate,
+    SavedQueryUpdate,
+)
+from kd.models.search import SearchResult
+from kd.models.tag import Tag, TagColor
+from kd.models.user import Group, ProjectTeam, User, UserCreate
+from kd.models.work_item import (
+    Duration,
+    WorkItem,
+    WorkItemCreate,
+    WorkItemType,
+    WorkItemUpdate,
+)
+
+__all__ = [
+    "Article",
+    "ArticleCreate",
+    "ArticleRef",
+    "ArticleUpdate",
+    "AssistResponse",
+    "AssistSuggestion",
+    "Attachment",
+    "BundleValue",
+    "Comment",
+    "CommentCreate",
+    "CustomField",
+    "Duration",
+    "FieldSet",
+    "Group",
+    "IdEntity",
+    "NamedEntity",
+    "Issue",
+    "IssueCreate",
+    "IssueUpdate",
+    "QueryValidationResult",
+    "Project",
+    "ProjectCreate",
+    "ProjectCustomField",
+    "ProjectTeam",
+    "SavedQuery",
+    "SavedQueryCreate",
+    "SavedQueryUpdate",
+    "SearchResult",
+    "Tag",
+    "TagColor",
+    "TimeTrackingSettings",
+    "User",
+    "UserCreate",
+    "WorkItem",
+    "WorkItemCreate",
+    "WorkItemType",
+    "WorkItemUpdate",
+]