kd-cli 2.0.4__py3-none-any.whl

kd/primer.py

@@ -0,0 +1,231 @@
+"""Project primer: local knowledge capsule for LLM consumers.
+
+The primer stores project-specific context — conventions, key article
+references, do's and don'ts — in ``.kd/primer.yaml``.  LLMs read
+the primer once via ``/primer show`` to get instant project context.
+
+Storage is separate from ``config.yaml`` (tool settings vs project
+knowledge).  The file is created lazily on first write operation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel
+
+from kd.exceptions import ConfigError, ValidationError
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+class PrimerArticle(BaseModel):
+    """A pinned article reference."""
+
+    id: str
+    summary: str | None = None
+
+
+class PrimerData(BaseModel):
+    """Root primer document."""
+
+    notes: list[str] = []
+    articles: list[PrimerArticle] = []
+
+
+# ---------------------------------------------------------------------------
+# File I/O
+# ---------------------------------------------------------------------------
+
+PRIMER_FILENAME = "primer.yaml"
+
+
+def _find_workspace_dir(start: Path | None = None) -> Path | None:
+    """Walk up from *start*, bounded by the git root, return first ``.kd/`` dir found.
+
+    Stops at the git repository root to prevent walking into a parent
+    directory's ``.kd/`` that would act as an unintended global primer.
+    If not in a git repo, only checks *start* itself.
+    """
+    current = (start or Path.cwd()).resolve()
+    # Find the ceiling — git root or cwd-only if no repo
+    ceiling = _find_git_root(current)
+    if ceiling is None:
+        # Not in a git repo — only check the start directory
+        candidate = current / ".kd"
+        return candidate if candidate.is_dir() else None
+    while True:
+        candidate = current / ".kd"
+        if candidate.is_dir():
+            return candidate
+        if current == ceiling:
+            return None
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def _find_git_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a ``.git`` directory."""
+    current = start.resolve()
+    while True:
+        if (current / ".git").is_dir():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def require_workspace_dir(start: Path | None = None) -> Path:
+    """Find ``.kd/`` directory or raise."""
+    workspace_dir = _find_workspace_dir(start)
+    if workspace_dir is None:
+        raise ConfigError("No .kd/ directory found. Run 'kd init' first.")
+    return workspace_dir
+
+
+def _primer_path(start: Path | None = None) -> Path:
+    """Return path to primer.yaml inside the nearest .kd/ dir."""
+    return require_workspace_dir(start) / PRIMER_FILENAME
+
+
+def load_primer(path: Path | None = None) -> PrimerData:
+    """Load primer from YAML. Returns empty primer if file or .kd/ doesn't exist."""
+    if path is not None:
+        primer_file = path
+    else:
+        workspace_dir = _find_workspace_dir()
+        if workspace_dir is None:
+            return PrimerData()
+        primer_file = workspace_dir / PRIMER_FILENAME
+    if not primer_file.exists():
+        return PrimerData()
+    try:
+        raw = yaml.safe_load(primer_file.read_text()) or {}
+        return PrimerData(**raw)
+    except (yaml.YAMLError, TypeError, ValueError) as e:
+        raise ConfigError(f"Invalid primer at {primer_file}: {e}") from e
+
+
+def save_primer(data: PrimerData, path: Path | None = None) -> None:
+    """Write primer to YAML.
+
+    Snapshots the current file before writing (copy-on-write) and uses
+    atomic writes to prevent partial-write corruption.
+    """
+    from kd.history import atomic_write_text, snapshot_before_write
+
+    primer_file = path or _primer_path()
+    snapshot_before_write(primer_file)
+    dumped = data.model_dump(exclude_none=True)
+    # Omit empty sections from the file
+    if not dumped.get("notes"):
+        dumped.pop("notes", None)
+    if not dumped.get("articles"):
+        dumped.pop("articles", None)
+    # Serialize articles as list of dicts (not bare IDs)
+    if "articles" in dumped:
+        dumped["articles"] = [_article_dump(a) for a in dumped["articles"]]
+    atomic_write_text(
+        primer_file,
+        yaml.dump(dumped, default_flow_style=False, sort_keys=False, allow_unicode=True),
+    )
+
+
+def _article_dump(article: dict[str, Any]) -> dict[str, Any]:
+    """Ensure article dict always has id; include summary only if set."""
+    result: dict[str, Any] = {"id": article["id"]}
+    if article.get("summary"):
+        result["summary"] = article["summary"]
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Mutations
+# ---------------------------------------------------------------------------
+
+
+def add_note(text: str, path: Path | None = None) -> int:
+    """Append a note. Returns the 1-based index."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    data.notes.append(text)
+    save_primer(data, primer_file)
+    return len(data.notes)
+
+
+def remove_note(index: int, path: Path | None = None) -> str:
+    """Remove a note by 1-based index. Returns the removed text."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    if index < 1 or index > len(data.notes):
+        raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+    removed = data.notes.pop(index - 1)
+    save_primer(data, primer_file)
+    return removed
+
+
+def update_note(index: int, text: str, path: Path | None = None) -> str:
+    """Replace a note by 1-based index. Returns the old text."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    if index < 1 or index > len(data.notes):
+        raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+    old = data.notes[index - 1]
+    data.notes[index - 1] = text
+    save_primer(data, primer_file)
+    return old
+
+
+def clear_notes(path: Path | None = None) -> int:
+    """Remove all notes. Returns the count removed."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    count = len(data.notes)
+    data.notes.clear()
+    save_primer(data, primer_file)
+    return count
+
+
+def add_article(
+    article_id: str, summary: str | None = None, path: Path | None = None
+) -> PrimerArticle:
+    """Pin an article. Raises if already pinned."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    for existing in data.articles:
+        if existing.id == article_id:
+            raise ValidationError(f"Article '{article_id}' is already pinned")
+    article = PrimerArticle(id=article_id, summary=summary)
+    data.articles.append(article)
+    save_primer(data, primer_file)
+    return article
+
+
+def remove_article(article_id: str, path: Path | None = None) -> PrimerArticle:
+    """Unpin an article by ID. Returns the removed entry."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    for i, article in enumerate(data.articles):
+        if article.id == article_id:
+            removed = data.articles.pop(i)
+            save_primer(data, primer_file)
+            return removed
+    raise ValidationError(f"Article '{article_id}' is not pinned")
+
+
+def clear_articles(path: Path | None = None) -> int:
+    """Remove all pinned articles. Returns the count removed."""
+    primer_file = path or _primer_path()
+    data = load_primer(primer_file)
+    count = len(data.articles)
+    data.articles.clear()
+    save_primer(data, primer_file)
+    return count

kd/query_parser.py

@@ -0,0 +1,181 @@
+"""Parse YouTrack query strings for article-compatible field extraction.
+
+Extracts ``project:`` and ``tag:`` clauses from saved-query text so that
+tag-based queries can be translated into article-tag lookups.  Queries
+containing issue-specific fields (state, assignee, priority, etc.) are
+rejected with a clear error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kd.exceptions import ValidationError
+
+# Fields that only apply to issues and cannot be translated to article lookups.
+_UNSUPPORTED_FIELDS = frozenset(
+    {
+        "state",
+        "assignee",
+        "for",
+        "priority",
+        "type",
+        "has",
+        "created",
+        "updated",
+        "resolved",
+        "reporter",
+        "sprint",
+        "fix versions",
+        "affected versions",
+        "subsystem",
+    }
+)
+
+_SUPPORTED_FIELDS = frozenset({"project", "tag"})
+
+
+@dataclass(frozen=True)
+class ParsedQuery:
+    """Result of parsing a YouTrack query for article-compatible fields."""
+
+    project: str | None = None
+    tags: list[str] = field(default_factory=list)
+
+
+def parse_article_query(query: str) -> ParsedQuery:
+    """Parse a YouTrack query string for article-compatible fields.
+
+    Supported fields: ``project`` (at most one) and ``tag`` (zero or more).
+    Raises :class:`~kd.exceptions.ValidationError` if unsupported
+    issue-specific fields or ``#macros`` are found.
+    """
+    stripped = query.strip()
+    if not stripped:
+        return ParsedQuery()
+
+    tokens = _tokenize(stripped)
+    _reject_unsupported(tokens)
+
+    project: str | None = None
+    tags: list[str] = []
+
+    for field_name, value in tokens:
+        key = field_name.lower()
+        if key == "project":
+            project = value
+        elif key == "tag":
+            tags.append(value)
+
+    return ParsedQuery(project=project, tags=tags)
+
+
+def _tokenize(query: str) -> list[tuple[str, str]]:
+    """Tokenize a YouTrack query into (field, value) pairs.
+
+    Handles braced values (``tag: {multi word}``) and bare values
+    (``tag: single``).  Also detects ``#macros`` like ``#Unresolved``.
+    """
+    tokens: list[tuple[str, str]] = []
+    pos = 0
+    length = len(query)
+
+    while pos < length:
+        # Skip whitespace.
+        if query[pos].isspace():
+            pos += 1
+            continue
+
+        # Detect #macros (e.g. #Unresolved, #Resolved).
+        if query[pos] == "#":
+            start = pos
+            pos += 1
+            while pos < length and not query[pos].isspace():
+                pos += 1
+            macro = query[start:pos]
+            tokens.append(("#macro", macro))
+            continue
+
+        # Read a field name: word characters (letters, digits, underscore)
+        # and spaces (for multi-word fields like "fix versions").
+        field_start = pos
+        while pos < length and query[pos] != ":":
+            if query[pos].isspace():
+                # Peek ahead: if there's a colon after optional words, it's
+                # still part of a multi-word field name.  Otherwise stop.
+                peek = pos
+                while peek < length and query[peek].isspace():
+                    peek += 1
+                # If we hit a colon or another word char followed eventually
+                # by a colon, continue.  Simple heuristic: look for colon
+                # within the next token.
+                colon_ahead = False
+                scan = peek
+                while scan < length and query[scan] not in (":", "#"):
+                    if query[scan].isspace():
+                        break
+                    scan += 1
+                if scan < length and query[scan] == ":":
+                    # The next word ends with colon → multi-word field.
+                    pos = peek
+                    continue
+                else:
+                    colon_ahead = False  # noqa: F841
+                    break
+            pos += 1
+
+        if pos >= length or query[pos] != ":":
+            # Not a field: value pair — skip this word.
+            pos += 1
+            while pos < length and not query[pos].isspace():
+                pos += 1
+            continue
+
+        field_name = query[field_start:pos].strip()
+        pos += 1  # skip the colon
+
+        # Skip whitespace after colon.
+        while pos < length and query[pos].isspace():
+            pos += 1
+
+        if pos >= length:
+            tokens.append((field_name, ""))
+            break
+
+        # Read the value: braced or bare.
+        if query[pos] == "{":
+            pos += 1  # skip opening brace
+            value_start = pos
+            while pos < length and query[pos] != "}":
+                pos += 1
+            value = query[value_start:pos]
+            if pos < length:
+                pos += 1  # skip closing brace
+        else:
+            value_start = pos
+            while pos < length and not query[pos].isspace():
+                pos += 1
+            value = query[value_start:pos]
+
+        tokens.append((field_name, value))
+
+    return tokens
+
+
+def _reject_unsupported(tokens: list[tuple[str, str]]) -> None:
+    """Raise ValidationError if any tokens are unsupported for article queries."""
+    unsupported: list[str] = []
+
+    for field_name, value in tokens:
+        if field_name == "#macro":
+            unsupported.append(value)
+            continue
+        if field_name.lower() not in _SUPPORTED_FIELDS:
+            unsupported.append(field_name)
+
+    if unsupported:
+        joined = ", ".join(unsupported)
+        raise ValidationError(
+            f"Cannot search articles with issue-specific fields: {joined}. "
+            "Only project and tag are supported."
+        )

kd/resources/__init__.py

@@ -0,0 +1 @@
+"""Packaged resources for kd (config templates, etc.)."""

kd/resources/command-synonyms.yaml

@@ -0,0 +1,19 @@
+# Built-in command synonyms for LLM and CLI familiarity.
+#
+# Each entry maps a synonym to the canonical command name.
+# Applied globally to any namespace that has the canonical command
+# but does not already define a command with the synonym name.
+#
+# Keep this set small and curated. See YTCTL-8.
+
+- synonym: get
+  canonical: show
+
+- synonym: ls
+  canonical: list
+
+- synonym: read
+  canonical: show
+
+- synonym: rm
+  canonical: delete

kd/resources/config-template.yaml

@@ -0,0 +1,71 @@
+# kd project config
+#
+# Values here override ~/.config/kd/config.yaml for this directory tree.
+# Resolution order: CLI flags > local config > connection > global config.
+#
+# Connection keys:
+#   url             - YouTrack instance base URL
+#   token_cmd       - Shell command that prints the API token to stdout
+#   token_env       - Environment variable name containing the API token
+#   default_project - Default project key for commands that accept --project
+#   output          - Default output format: table, json, yaml, md
+#   limit           - Default result limit for list commands
+#   compatibility   - Version targeting (target + mode)
+#
+# At least one of token_cmd or token_env is required per connection.
+# Secrets are never stored as raw values in config.
+
+# default_connection: main
+
+# connections:
+#   main:
+#     provider: youtrack
+#     url: https://your-instance.youtrack.cloud
+#     # token_cmd: gopass show -o path/to/token
+#     token_env: KD_TOKEN
+#     # default_project: PROJ
+#     # output: table
+#     # limit: 50
+#     # defaults:
+#     #   issue_list:
+#     #     query: "for: me #Unresolved"
+#     # compatibility:
+#     #   target: auto
+#     #   mode: pinned
+
+# Global fallbacks (apply when connection doesn't specify):
+# output: table
+# limit: 50
+# debug: false
+
+# Per-command defaults (namespace_command as key):
+# defaults:
+#   issue_list:
+#     limit: 100
+#     query: "for: me #Unresolved"
+#   issue_show:
+#     detail: rich
+
+# Per-project overrides:
+# projects:
+#   FB:
+#     field_aliases:
+#       state: Stage
+#       type: Kind
+#     defaults:
+#       issue_list:
+#         fields: id,summary,state,priority,assignee
+
+# History settings (copy-on-write snapshots before config/primer writes):
+# history:
+#   retention: 20    # max snapshots per file (default: 20)
+
+# Command aliases (shortcuts that expand to full commands):
+# aliases:
+#   my-bugs: "/issue list --query 'for: me Type: Bug #Unresolved'"
+#   sprint: "/issue list --query '#Unresolved Board Sprint: {Current sprint}'"
+#   standup: "/issue list --query 'for: me updated: Today'"
+#
+# Invoke directly:    kd my-bugs
+# Explicit form:      kd alias my-bugs
+# With overrides:     kd my-bugs --limit 5

kd/resources/error-messages.yaml

@@ -0,0 +1,101 @@
+# Error message mappings for kd
+#
+# Each entry rewrites an upstream API error into a user-friendly message
+# with an actionable suggestion. Rules are matched in order; the first
+# match wins. A rule matches iff every present filter matches:
+#
+#   status   - Optional HTTP status code. Exact integer equality.
+#   path     - Optional regex matched against the request URL path.
+#              Use named groups like (?P<id>[^/]+) to expose values to
+#              the message/suggestion templates as {id}.
+#   pattern  - Optional regex matched against the extracted response
+#              message. Positional groups are exposed as {1}, {2}, ...
+#
+#   message     - Rewritten user-facing message. Required.
+#   suggestion  - Optional actionable hint shown below the error.
+#
+# Rule ordering convention:
+#   1. Sub-resource 404 rules first (most specific path segments).
+#   2. Top-level entity 404 rules (issues, articles).
+#   3. Message-based rules (status/path unset) last.
+# Reordering is load-bearing — narrower rules must precede broader ones.
+
+# --- Time tracking 403 ---
+
+- status: 403
+  path: '/issues/[^/]+/timeTracking'
+  message: 'Access denied for time tracking operation'
+  suggestion: >-
+    Time tracking may not be enabled for this project.
+    Enable it in YouTrack: project Settings → Time Tracking.
+
+# --- Sub-resource 404s (issues) ---
+
+- status: 404
+  path: '/issues/[^/]+/timeTracking/workItems/(?P<id>[^/]+)$'
+  message: 'Work item {id} not found'
+  suggestion: 'List work items with: kd /time list <ISSUE>.'
+
+- status: 404
+  path: '/issues/[^/]+/attachments/(?P<id>[^/]+)(/content)?$'
+  message: 'Attachment {id} not found'
+  suggestion: 'List attachments with: kd /issue attachment list <ISSUE>.'
+
+- status: 404
+  path: '/issues/[^/]+/comments/(?P<id>[^/]+)$'
+  message: 'Comment {id} not found'
+  suggestion: 'Show the parent issue to list its comments.'
+
+# --- Sub-resource 404s (articles) ---
+
+- status: 404
+  path: '/articles/[^/]+/attachments/(?P<id>[^/]+)(/content)?$'
+  message: 'Attachment {id} not found'
+  suggestion: 'List attachments with: kd /article attachment list <ARTICLE>.'
+
+- status: 404
+  path: '/articles/[^/]+/comments/(?P<id>[^/]+)$'
+  message: 'Comment {id} not found'
+  suggestion: 'List comments with: kd /article comment list <ARTICLE>.'
+
+# --- Top-level 404s ---
+
+- status: 404
+  path: '/articles/(?P<id>[^/]+)(/.*)?$'
+  message: 'Article {id} not found'
+  suggestion: 'Check the article ID with: kd /article list.'
+
+- status: 404
+  path: '/issues/(?P<id>[^/]+)(/.*)?$'
+  message: 'Issue {id} not found'
+  suggestion: 'Check the issue ID and project key.'
+
+# --- Query parse errors ---
+
+- pattern: "(?i)can.t parse search query"
+  message: 'Query syntax error'
+  suggestion: >-
+    Values containing special characters (colons, spaces, braces) must be
+    wrapped in braces, e.g. tag: {type:case}. See YouTrack query syntax reference.
+
+# --- Message-based rules (any status, any path) ---
+
+- pattern: 'The value "(.+)" isn''t used for the project field'
+  message: 'Project "{1}" does not exist'
+  suggestion: 'Run "kd project list" to see available projects.'
+
+- pattern: "Unknown command: (.+)"
+  message: 'Unknown YouTrack command: {1}'
+  suggestion: 'Check command syntax in the YouTrack documentation.'
+
+- pattern: "incompatible-issue-custom-field-name-(.+)"
+  message: 'Field "{1}" is not available in this project'
+  suggestion: 'Run "kd issue show <ID>" to see which fields this project uses.'
+
+- pattern: "Token is incorrect or has expired"
+  message: "API token is invalid or expired"
+  suggestion: 'Check your token with "kd system ping" or generate a new one in YouTrack → Profile → Authentication.'
+
+- pattern: "Banned: Too many failed authentication attempts"
+  message: "Too many failed authentication attempts"
+  suggestion: "Wait a few minutes and verify your token is correct."