kd-cli 2.0.4__py3-none-any.whl

kd/article_marker.py

@@ -0,0 +1,348 @@
+"""kd-meta marker parser and renderer.
+
+The marker block is the upsert key for ``/article push``. It lives as
+an HTML comment at the top of an article's content and in the local
+source file. See ``docs/proposals/19-article-push-proposal.md`` for
+the full rationale.
+
+Grammar (informal):
+
+    <!-- kd-meta
+    key: value
+    ...
+    -->
+    <optional blank line>
+    <body>
+
+Rules (pinned down by ``tests/test_article_marker.py``):
+
+- Open and close lines must be exact (``<!-- kd-meta`` / ``-->``).
+- Keys match ``[a-z][a-z0-9-]*``; uppercase and underscores are
+  rejected to keep the grammar ASCII-boring.
+- Unknown keys are preserved verbatim on round-trip — the load-bearing
+  property that lets future kd versions add keys without breaking
+  older versions' round-trips.
+- Known keys are emitted first in the canonical order ``slug``,
+  ``upstream-id``, ``upstream-updated``. Unknown keys follow in their
+  original insertion order.
+- Line endings and trailing newlines are preserved so that a
+  ``parse → render`` cycle is a fixed point.
+
+Legacy marker synonym (transitional, proposal 28 / M003 §S4):
+
+    The parser accepts any ``<!-- kd-meta`` or ``<!-- ytctl-meta``
+    open line and treats them identically. The renderer always writes
+    ``<!-- kd-meta``, so every successful push rewrites a legacy
+    header to native; upstream state converges one article at a time.
+    The legacy set is pinned to ``_LEGACY_SYNONYMS`` and to a single
+    test assertion so removal is a one-file, one-PR edit once the
+    upstream population of ``ytctl-meta`` is empty. No auto-disable,
+    no timer — a deliberate future milestone.
+
+Stdlib only; no third-party deps. The push workflow (in
+``kd.client.ArticleOperations.push``) and its tests are the only
+importers.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import OrderedDict
+from dataclasses import dataclass, field
+
+from kd.exceptions import ValidationError
+
+__all__ = [
+    "ArticleMarker",
+    "MarkerError",
+    "ParsedFile",
+    "parse_content",
+    "render_content",
+    "validate_slug",
+]
+
+
+_MARKER_OPEN = "<!-- kd-meta"
+_MARKER_CLOSE = "-->"
+
+# Transitional read-only synonyms for the marker open line. The parser
+# accepts these identically to ``_MARKER_OPEN``; the renderer only ever
+# emits ``_MARKER_OPEN``, so every successful push rewrites an upstream
+# body to the native marker.
+#
+# Removability contract (proposal 28 §Article Marker / M003 §S4):
+# sunset this table by deleting the single entry below and the
+# ``TestLegacySynonym.test_synonym_set_pinned`` assertion once the
+# upstream population of ``ytctl-meta`` markers is empty. Do not add
+# more synonyms; every extra entry is more work for the removal
+# milestone.
+_LEGACY_SYNONYMS: tuple[str, ...] = ("<!-- ytctl-meta",)
+
+# Every marker-open line the parser recognizes (native + legacy).
+_RECOGNIZED_OPENS: frozenset[str] = frozenset((_MARKER_OPEN, *_LEGACY_SYNONYMS))
+
+# Keys are marker identifiers (e.g. "slug", "upstream-id"). Lowercase,
+# ASCII, hyphen-separated. Underscores are intentionally excluded so
+# the grammar stays HTML-comment-safe and greppable.
+_KEY_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+
+# `key: value` line inside the marker block. Value is captured raw and
+# stripped separately.
+_LINE_RE = re.compile(r"^([a-z][a-z0-9-]*)\s*:\s*(.*)$")
+
+# Slug charset: file-path shape, case-preserved. Rejects whitespace,
+# colons (would break the marker grammar), and newlines.
+_SLUG_RE = re.compile(r"^[A-Za-z0-9._][A-Za-z0-9._/\-]*$")
+
+# Canonical emission order for keys kd itself writes. Anything else
+# is an "unknown key" and appended in original order.
+_KNOWN_KEYS: tuple[str, ...] = ("slug", "upstream-id", "upstream-updated")
+
+
+class MarkerError(ValidationError):
+    """Raised when a marker block fails to parse or a slug is invalid."""
+
+
+@dataclass
+class ArticleMarker:
+    """Parsed kd-meta marker block.
+
+    ``data`` is an insertion-ordered dict of every key/value pair found
+    in the block, including unknown keys. The three known keys expose
+    typed properties for convenience; everything else is accessed via
+    ``data``.
+    """
+
+    data: "OrderedDict[str, str]" = field(default_factory=OrderedDict)
+
+    def get(self, key: str) -> str | None:
+        return self.data.get(key)
+
+    def set(self, key: str, value: str) -> None:
+        """Set a key; validates the key charset."""
+        if not _KEY_RE.match(key):
+            raise MarkerError(f"invalid key: {key!r}")
+        self.data[key] = value
+
+    @property
+    def slug(self) -> str | None:
+        return self.data.get("slug")
+
+    @property
+    def upstream_id(self) -> str | None:
+        return self.data.get("upstream-id")
+
+    @property
+    def upstream_updated(self) -> str | None:
+        return self.data.get("upstream-updated")
+
+
+@dataclass(frozen=True)
+class ParsedFile:
+    """Result of parsing a local file's content into marker + body.
+
+    Preserves enough metadata to re-emit the file byte-identically:
+
+    - ``marker`` is ``None`` when the input has no marker at the top.
+    - ``body`` is the content after the marker (and its optional blank
+      separator line), with line endings normalized to ``"\\n"``.
+      ``render_content`` restores the original line ending style.
+    - ``newline`` is ``"\\n"`` or ``"\\r\\n"`` detected from the input.
+    - ``trailing_newline`` is ``True`` iff the original input ended
+      with a line terminator.
+    - ``body_separator`` is ``True`` iff there was a blank line between
+      the marker close and the first body line. The renderer emits one
+      iff this flag is set. Synthesized markers default to ``True``
+      (canonical form; also what the YouTrack web UI normalizes into).
+    """
+
+    marker: ArticleMarker | None
+    body: str
+    newline: str
+    trailing_newline: bool
+    body_separator: bool = True
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+
+def _detect_newline(text: str) -> str:
+    """Return ``"\\r\\n"`` if the first line terminator is CRLF, else ``"\\n"``."""
+    idx = text.find("\n")
+    if idx > 0 and text[idx - 1] == "\r":
+        return "\r\n"
+    return "\n"
+
+
+def _split_lines(text: str, newline: str) -> list[str]:
+    """Split on the given line terminator, preserving empty trailing lines.
+
+    Normalizes to ``\\n``-joined form internally; callers never see the
+    raw terminator. A trailing terminator produces an extra empty
+    element which the caller handles via ``trailing_newline``.
+    """
+    if newline == "\r\n":
+        text = text.replace("\r\n", "\n")
+    return text.split("\n")
+
+
+def parse_content(text: str) -> ParsedFile:
+    """Parse *text* into a ``ParsedFile`` with optional marker + body.
+
+    Raises ``MarkerError`` if a marker block is opened but malformed.
+    A file with no marker at the top returns ``marker=None``; the body
+    equals the input verbatim (modulo newline normalization).
+    """
+    newline = _detect_newline(text)
+    trailing_newline = text.endswith(("\n", "\r\n"))
+    lines = _split_lines(text, newline)
+    # A trailing newline leaves an extra empty element at the end; drop
+    # it and record the fact so render() can restore it.
+    if trailing_newline and lines and lines[-1] == "":
+        lines = lines[:-1]
+
+    # Scan past any leading blank lines (tolerated before the marker
+    # open). If the first non-blank line is not the marker open, the
+    # file is marker-less and we return the entire text as body.
+    i = 0
+    while i < len(lines) and lines[i] == "":
+        i += 1
+    if i >= len(lines) or lines[i] not in _RECOGNIZED_OPENS:
+        return ParsedFile(
+            marker=None,
+            body=_join_body(lines, trailing_newline),
+            newline=newline,
+            trailing_newline=trailing_newline,
+            body_separator=False,
+        )
+
+    # Find the matching close line before per-line parsing. If there is
+    # no close at all, report "not closed" rather than misdiagnosing a
+    # body line as a malformed key:value.
+    close_idx: int | None = None
+    for k in range(i + 1, len(lines)):
+        if lines[k] == _MARKER_CLOSE:
+            close_idx = k
+            break
+    if close_idx is None:
+        raise MarkerError("marker block not closed (expected '-->' on its own line)")
+
+    # Refuse a second marker anywhere later in the file — native or
+    # legacy. Prevents a stray ``<!-- ytctl-meta`` further down from
+    # being silently accepted as body content on a file that also
+    # carries a native header at the top.
+    for k in range(close_idx + 1, len(lines)):
+        if lines[k] in _RECOGNIZED_OPENS:
+            raise MarkerError("file contains more than one kd-meta block")
+
+    # Parse key:value lines between open and close.
+    marker = ArticleMarker()
+    for j in range(i + 1, close_idx):
+        line = lines[j]
+        if line == "":
+            continue  # blank lines inside the marker are tolerated
+        m = _LINE_RE.match(line)
+        if m is None:
+            # Distinguish "invalid key charset" from "no colon at all"
+            # to give a more actionable error message.
+            if ":" not in line:
+                raise MarkerError(f"malformed key:value line: {line!r}")
+            raw_key = line.split(":", 1)[0].strip()
+            raise MarkerError(f"invalid key: {raw_key!r}")
+        key, value = m.group(1), m.group(2).strip()
+        marker.data[key] = value
+
+    # Consume one optional blank separator line after the close.
+    body_start = close_idx + 1
+    body_separator = False
+    if body_start < len(lines) and lines[body_start] == "":
+        body_separator = True
+        body_start += 1
+
+    body_lines = lines[body_start:]
+    body = _join_body(body_lines, trailing_newline)
+    return ParsedFile(
+        marker=marker,
+        body=body,
+        newline=newline,
+        trailing_newline=trailing_newline,
+        body_separator=body_separator,
+    )
+
+
+def _join_body(lines: list[str], trailing_newline: bool) -> str:
+    """Join body lines with ``\\n``, restoring the final terminator if any."""
+    if not lines:
+        return "\n" if trailing_newline else ""
+    body = "\n".join(lines)
+    if trailing_newline:
+        body += "\n"
+    return body
+
+
+# ---------------------------------------------------------------------------
+# Renderer
+# ---------------------------------------------------------------------------
+
+
+def render_content(parsed: ParsedFile) -> str:
+    """Render a ``ParsedFile`` back to text, preserving byte-identity.
+
+    - Known keys first (``slug``, ``upstream-id``, ``upstream-updated``),
+      then unknown keys in their original insertion order.
+    - Blank line separator between ``-->`` and the first body line
+      (canonical form; also the shape the YouTrack web UI normalizes
+      into).
+    - Line endings are ``parsed.newline``; trailing newline follows
+      ``parsed.trailing_newline``.
+    """
+    if parsed.marker is None:
+        # Marker-less files pass through verbatim. ``body`` already
+        # includes any trailing newline; line endings are ``\n``.
+        return _retarget_newlines(parsed.body, parsed.newline)
+
+    marker = parsed.marker
+    lines: list[str] = [_MARKER_OPEN]
+    # Known keys first, in canonical order, if present.
+    for key in _KNOWN_KEYS:
+        if key in marker.data:
+            lines.append(f"{key}: {marker.data[key]}")
+    # Unknown keys, in their original insertion order.
+    for key, value in marker.data.items():
+        if key in _KNOWN_KEYS:
+            continue
+        lines.append(f"{key}: {value}")
+    lines.append(_MARKER_CLOSE)
+    if parsed.body_separator:
+        lines.append("")
+
+    header = "\n".join(lines) + "\n"
+    body = parsed.body
+    combined = header + body
+    return _retarget_newlines(combined, parsed.newline)
+
+
+def _retarget_newlines(text: str, newline: str) -> str:
+    """Replace ``\\n`` with *newline* if *newline* is CRLF; else no-op."""
+    if newline == "\r\n":
+        return text.replace("\n", "\r\n")
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Slug validation
+# ---------------------------------------------------------------------------
+
+
+def validate_slug(slug: str) -> None:
+    """Raise ``MarkerError`` if *slug* does not match the push slug charset.
+
+    Allowed: ``[A-Za-z0-9._]`` as first char, then ``[A-Za-z0-9._/-]*``.
+    Rejects whitespace, colons, newlines, and a leading ``/``.
+    """
+    if not slug:
+        raise MarkerError("slug cannot be empty")
+    if not _SLUG_RE.match(slug):
+        raise MarkerError(f"invalid slug {slug!r}: must match [A-Za-z0-9._][A-Za-z0-9._/-]*")

kd/auth.py

@@ -0,0 +1,96 @@
+"""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

kd/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI layer — thin wrapper over the SDK.
+
+Parses arguments via namespace-based command routing,
+calls SDK methods, formats output.
+"""

kd/cli/core/__init__.py

@@ -0,0 +1,25 @@
+"""CLI framework core — namespace system, command base, option registry."""
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.namespaces import Namespace, NamespaceRegistry
+from kd.cli.core.option_registry import (
+    OUTPUT_OPTIONS,
+    OptionDeclaration,
+    OptionError,
+    OptionLayer,
+    OptionRegistry,
+    ResolvedOptions,
+)
+
+__all__ = [
+    "OUTPUT_OPTIONS",
+    "Command",
+    "CommandResult",
+    "Namespace",
+    "NamespaceRegistry",
+    "OptionDeclaration",
+    "OptionError",
+    "OptionLayer",
+    "OptionRegistry",
+    "ResolvedOptions",
+]

kd/cli/core/command_base.py

@@ -0,0 +1,133 @@
+"""Command base class.
+
+All CLI commands inherit from Command and implement execute().
+Commands receive positional args, resolved options, and optionally
+a YouTrackClient. They return structured data for output formatting.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from kd.cli.core.option_registry import OptionDeclaration, ResolvedOptions
+
+if TYPE_CHECKING:
+    from kd.config import ResolvedConfig
+
+# Commands return structured data — the output layer formats it.
+# list[dict] -> table rows; dict -> key-value pairs; str -> passthrough; None -> no output
+CommandResult = list[dict[str, Any]] | dict[str, Any] | str | None
+
+
+class Command(ABC):
+    """Base class for all CLI commands."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        *,
+        requires_client: bool = False,
+        requires_config: bool = False,
+        usage: str = "",
+        long_description: str = "",
+        examples: list[str] | None = None,
+        see_also: list[str] | None = None,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.requires_client = requires_client
+        self.requires_config = requires_config
+        self.usage = usage
+        self.long_description = long_description
+        self.examples: list[str] = examples or []
+        self.see_also: list[str] = see_also or []
+        self.display_hint: str | None = None
+        self._options: list[OptionDeclaration] = []
+        self._resolved_config: ResolvedConfig | None = None
+        self._register_options()
+
+    def set_config(self, config: ResolvedConfig) -> None:
+        """Inject the resolved config. Called by the dispatcher when
+        ``requires_config`` is True, before ``execute()`` runs.
+        """
+        self._resolved_config = config
+
+    @property
+    def config(self) -> ResolvedConfig:
+        """The resolved config for this invocation.
+
+        Only valid when the command declares ``requires_config=True``; the
+        dispatcher calls :meth:`set_config` before :meth:`execute` in that
+        case. Raises :class:`RuntimeError` otherwise.
+        """
+        if self._resolved_config is None:
+            raise RuntimeError(f"{self.name}: config not set. Did you forget requires_config=True?")
+        return self._resolved_config
+
+    def _register_options(self) -> None:
+        """Register command-specific options. Override in subclasses."""
+
+    @abstractmethod
+    def execute(
+        self,
+        args: list[str],
+        options: ResolvedOptions,
+        client: Any = None,
+    ) -> CommandResult:
+        """Execute the command. Return structured data for output formatting.
+
+        Args:
+            args: Positional arguments after namespace+command resolution.
+            options: Resolved command and output options.
+            client: YouTrackClient instance (None if requires_client is False).
+        """
+
+    def register_option(self, option: OptionDeclaration) -> None:
+        """Add an option declaration to this command."""
+        self._options.append(option)
+
+    def get_options(self) -> list[OptionDeclaration]:
+        """Return all option declarations for this command."""
+        return list(self._options)
+
+    def get_help_text(self) -> str:
+        """Generate help text from command metadata and options."""
+        lines = [self.description]
+
+        if self.usage:
+            lines.append("")
+            lines.append(f"Usage: {self.usage}")
+
+        if self.long_description:
+            lines.append("")
+            lines.append(self.long_description)
+
+        if self._options:
+            lines.append("")
+            lines.append("Options:")
+            for opt in self._options:
+                flag = f"  --{opt.name}"
+                if opt.short_name:
+                    flag += f", -{opt.short_name}"
+                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)
+
+        if self.examples:
+            lines.append("")
+            lines.append("Examples:")
+            for ex in self.examples:
+                lines.append(f"  {ex}")
+
+        if self.see_also:
+            lines.append("")
+            lines.append(f"See also: {', '.join(self.see_also)}")
+
+        return "\n".join(lines)