kd-cli 2.4.0__tar.gz → 2.5.0__tar.gz

{kd_cli-2.4.0/kd_cli.egg-info → kd_cli-2.5.0}/PKG-INFO

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

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/api/tags.py

@@ -38,6 +38,7 @@ _TAGGED_ISSUE_FIELDS = str(
         "summary",
         "updated",
         project=FieldSet("id", "name", "shortName"),
+        tags=FieldSet("id", "name"),
     )
 )
 

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/cli/namespaces/article/__init__.py

@@ -353,7 +353,11 @@ class ArticleCreateCommand(Command):
                 "title. Pass --parent to attach the new article under an "
                 "existing one in a single call, avoiding a create-then-move "
                 "two-step in migration scripts. Pass --tag (repeatable) to "
-                "apply tags at creation time."
+                "apply tags at creation time: every --tag must exist, the "
+                "article is refused before creation if any tag is missing "
+                "(no orphan article on unknown tags), and the structured "
+                "response reflects post-tag state so it matches a "
+                "subsequent /article show on the returned id."
             ),
             examples=[
                 'kd /article create "Setup Guide" --project FB --content @guide.md',

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/cli/namespaces/system/__init__.py

@@ -9,10 +9,12 @@ copy-on-write history for config and primer files.
 from __future__ import annotations
 
 import difflib
+import platform as _platform
 from dataclasses import asdict
 from pathlib import Path
 from typing import Any
 
+from kd import __version__ as _kd_version
 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
@@ -51,10 +53,13 @@ class SystemInfoCommand(Command):
             requires_client=True,
             usage="kd /system info",
             long_description="Connects to the YouTrack instance and displays the current "
-            "user, server URL, and connection status. Uses the active connection "
-            "(selected via -c or 'default_connection').",
+            "user, server URL, and connection status, plus kd client/runtime metadata "
+            "(`kd_version`, `python_version`, `platform`) so bug reports are "
+            "self-describing without hand-typing the version. Uses the active "
+            "connection (selected via -c or 'default_connection').",
             examples=[
                 "kd /system info",
+                "kd /system info -o yaml",
                 "kd -c upstream /system info",
             ],
             see_also=["/system/config list"],
@@ -73,6 +78,9 @@ class SystemInfoCommand(Command):
             "user": me.get("login", "unknown"),
             "name": me.get("name", ""),
             "email": me.get("email", ""),
+            "kd_version": _kd_version,
+            "python_version": _platform.python_version(),
+            "platform": _platform.platform(),
         }
 
 

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/cli/namespaces/tag/__init__.py

@@ -152,7 +152,7 @@ class TagShowCommand(Command):
 
 
 class TagCreateCommand(Command):
-    """Create a tag."""
+    """Create a tag (idempotent)."""
 
     def __init__(self) -> None:
         super().__init__(
@@ -160,8 +160,16 @@ class TagCreateCommand(Command):
             "Create a tag",
             requires_client=True,
             usage="kd /tag create TAG_NAME",
+            long_description=(
+                "Idempotent: if a tag with the requested name is already "
+                "visible, the command returns the existing tag with "
+                "action: exists and does not POST. Response envelope: "
+                "{ok, action, tag} with action ∈ {create, exists} in both "
+                "branches. Name resolution is case-insensitive (same "
+                "resolver /tag show uses)."
+            ),
             examples=['kd /tag create "sprint-47"'],
-            see_also=["/tag list", "/tag delete"],
+            see_also=["/tag list", "/tag show", "/tag delete"],
         )
 
     def execute(
@@ -169,8 +177,12 @@ class TagCreateCommand(Command):
     ) -> CommandResult:
         if not args:
             raise ValidationError("Usage: kd /tag create TAG_NAME")
-        tag = client.tags.create(args[0])
-        return _tag_to_detail(tag)
+        result = client.tags.create(args[0])
+        return {
+            "ok": True,
+            "action": result.action,
+            "tag": _tag_to_detail(result.tag),
+        }
 
 
 class TagRenameCommand(Command):

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/client.py

@@ -72,6 +72,7 @@ from kd.models import (
     EntityRef,
     KindMeta,
     Tag,
+    TagCreateResult,
     TagEntitiesResult,
     TimeTrackingSettings,
     User,
@@ -1031,24 +1032,44 @@ def _extract_tag_suggestions(error: NotFoundError) -> builtins.list[str]:
     return [part.strip() for part in raw.split(",") if part.strip()]
 
 
-def _missing_tag_resolution(tag: str, error: NotFoundError) -> str:
-    """Format an actionable missing-tag instruction for article push."""
+def _missing_tag_resolution(
+    tag: str,
+    error: NotFoundError,
+    *,
+    context: Literal["create", "push"] = "push",
+) -> str:
+    """Format an actionable missing-tag instruction for ``/article create`` or ``/article push``.
+
+    *context* selects the retry-wording so the create path does not ship
+    push-specific recovery text and vice versa. The shared prelude
+    (heading, near-matches, ``/tag list --prefix``, ``/tag create``)
+    is identical across callers.
+    """
     lines = [f"Tag '{tag}' not found."]
     suggestions = _extract_tag_suggestions(error)
     if suggestions:
         lines.append(f"  Near matches: {', '.join(suggestions)}")
     prefix = _tag_prefix_for_list(tag)
-    lines.extend(
-        [
-            "",
-            f"To use an existing tag:   kd /tag list --prefix {shlex.quote(prefix)}",
-            f"To create a new tag:      kd /tag create {shlex.quote(tag)}",
+    shared = [
+        "",
+        f"To use an existing tag:   kd /tag list --prefix {shlex.quote(prefix)}",
+        f"To create a new tag:      kd /tag create {shlex.quote(tag)}",
+    ]
+    if context == "push":
+        recovery = [
             f"To retry push without this tag: omit --tag {shlex.quote(tag)}",
             "",
             "If you are still curating the tag set, push without --tag and apply tags",
             f"separately with kd /tag add ARTICLE-ID {shlex.quote(tag)}.",
         ]
-    )
+    else:
+        recovery = [
+            f"To retry create without this tag: omit --tag {shlex.quote(tag)} from kd /article create",
+            "",
+            "If you are still curating the tag set, create the article without --tag and apply",
+            f"tags separately with kd /tag add ARTICLE-ID {shlex.quote(tag)}.",
+        ]
+    lines.extend(shared + recovery)
     return "\n".join(lines)
 
 
@@ -1126,9 +1147,21 @@ class ArticleOperations:
 
         When *parent* is given (readable id like ``FB-A-1`` or internal id),
         the new article is attached to that parent in a single POST.
-        When *tags* is given, each tag is applied after article creation.
+        When *tags* is given, tag existence is validated **before** the
+        article write so an unknown tag aborts with an actionable error
+        instead of creating an orphan article that then fails on
+        attachment. After every applied tag, the article is re-fetched
+        so the returned :class:`Article` reflects post-tag state and
+        matches a subsequent ``/article show`` on the returned ID.
         """
         self._debug.info("api", f"creating article in project {project}")
+        if tags:
+            preflight_failed = self._preflight_tags(tags, context="create")
+            if preflight_failed:
+                raise KdError(
+                    "Article create aborted because tagging failed.\n\n"
+                    + "\n\n".join(preflight_failed)
+                )
         project_obj = self._yt.get_project(project)
         parent_ref: IdEntity | None = None
         if parent is not None:
@@ -1152,6 +1185,8 @@ class ArticleOperations:
                     f"Applied: {applied or '(none)'}. "
                     f"Failed: {', '.join(failed)}."
                 )
+            if applied:
+                result = self._articles.get_article(result.id_readable)
         return result
 
     def _apply_tags(
@@ -1182,12 +1217,14 @@ class ArticleOperations:
         *,
         create_missing: bool = False,
         dry_run: bool = False,
+        context: Literal["create", "push"] = "push",
     ) -> builtins.list[str]:
-        """Resolve tags before mutating an article.
+        """Resolve tags before ``/article create`` or ``/article push`` writes.
 
-        Returns actionable failure blocks. When ``create_missing`` is true,
-        missing tags are created before the article write; ``dry_run`` never
-        writes tags and treats missing tags as would-create.
+        Returns actionable failure blocks. *context* selects the retry-wording
+        for missing-tag recovery so create and push do not share push-only
+        prose. ``create_missing`` and ``dry_run`` are push-only flags today
+        and are expected to stay false on the create path.
         """
         if self._tag_ops is None:
             raise KdError("Tag operations not available")
@@ -1206,7 +1243,7 @@ class ArticleOperations:
                             f"Tag '{tag}' not found and could not be created. {create_exc}"
                         )
                     continue
-                failed.append(_missing_tag_resolution(tag, exc))
+                failed.append(_missing_tag_resolution(tag, exc, context=context))
             except KdError as exc:
                 failed.append(f"Tag '{tag}' could not be resolved. {exc}")
         return failed
@@ -1631,12 +1668,28 @@ class TagOperations:
         tag_id = self._resolve_tag(name)
         return self._tags.get_tag(tag_id)
 
-    def create(self, name: str) -> Tag:
-        self._debug.info("api", f"creating tag '{name}'")
-        tag = self._tags.create_tag(name)
-        self._name_cache[name.lower()] = tag.id
-        self._debug.info("api", f"created tag '{name}' ({tag.id})")
-        return tag
+    def create(self, name: str) -> TagCreateResult:
+        """Idempotent tag creation.
+
+        Pre-checks existence via :meth:`_resolve_tag` — the same resolver
+        ``/tag show`` uses, so case-insensitive by construction — and
+        short-circuits with ``action="exists"`` if a tag by that name is
+        already visible. Otherwise POSTs and returns ``action="create"``.
+        ``Tag.name-is-invalid`` from the upstream POST is enriched by
+        ``kd/resources/error-messages.yaml`` into a factual diagnostic
+        naming sharing/visibility and name-acceptance as plausible causes.
+        """
+        try:
+            tag_id = self._resolve_tag(name)
+        except NotFoundError:
+            self._debug.info("api", f"creating tag '{name}'")
+            created = self._tags.create_tag(name)
+            self._name_cache[name.lower()] = created.id
+            self._debug.info("api", f"created tag '{name}' ({created.id})")
+            return TagCreateResult(action="create", tag=created)
+        self._debug.info("api", f"tag '{name}' already exists ({tag_id})")
+        existing = self._tags.get_tag(tag_id)
+        return TagCreateResult(action="exists", tag=existing)
 
     def rename(self, name: str, new_name: str) -> Tag:
         tag_id = self._resolve_tag(name)
@@ -1697,6 +1750,14 @@ class TagOperations:
         composes the OR query (``tag: A or tag: B``).  The single-tag fast
         path is unaffected by ``match`` because one tag is itself the same
         set regardless of combinator.
+
+        Both dispatch paths unconditionally project ``tags(id,name)`` on
+        issue rows — the fast-path field-set (``_TAGGED_ISSUE_FIELDS`` in
+        :mod:`kd.api.tags`) includes it, and the composed-query call
+        passes ``with_tags=True`` to :meth:`YouTrackAPI.list_issues`.
+        Keeps ``/tag entities`` discovery rows in parity with
+        ``/issue show --rich`` and ``/issue list --with-tags`` so
+        tag-matched rows expose which tags caused the match.
         """
         tag_names = [tags] if isinstance(tags, str) else list(tags)
         if not tag_names:
@@ -1710,7 +1771,7 @@ class TagOperations:
         if project is not None:
             query += f" project: {youtrack_query_literal(project)}"
         self._debug.info("api", f"composing multi-tag issue query ({match}): {query}")
-        return self._yt.list_issues(query=query, top=top, skip=skip)
+        return self._yt.list_issues(query=query, top=top, skip=skip, with_tags=True)
 
     def articles(
         self,

kd_cli-2.5.0/kd/locking.py

@@ -0,0 +1,97 @@
+"""Advisory file locking for read-modify-write transactions on kd-managed files.
+
+Provides :func:`file_transaction` — a context manager that acquires an
+exclusive advisory lock on a sidecar lockfile (``<path>.lock``) for the
+duration of a load → mutate → save cycle.  Concurrent kd processes that
+enter the same transaction serialize rather than clobber each other.
+
+Design notes:
+
+* **Sidecar lockfile, not the target file.**  Atomic writes elsewhere in
+  kd use ``tempfile.mkstemp`` + ``os.replace``, which changes the target
+  file's inode on every write.  Holding ``flock`` on the target inode
+  would not protect a second writer that opens the freshly-replaced file.
+  Locking a separate sidecar file that nobody rewrites keeps the lock
+  stable across atomic replaces of the data file.
+
+* **No unlink on release.**  Removing the lockfile after releasing the
+  lock is a classic race: process B can open the doomed inode while
+  process C creates a fresh one, and both end up holding "exclusive"
+  locks on different inodes.  Empty sidecar files are cheap; leave them.
+
+* **POSIX only.**  ``fcntl`` is imported lazily inside the context
+  manager so that unrelated kd commands remain importable on Windows.
+  On non-POSIX platforms, :func:`file_transaction` raises ``ConfigError``
+  with a suggestion to run the command sequentially.
+
+* **NFS caveat.**  ``flock`` on NFS has been unreliable historically.
+  Modern Linux kernels implement it correctly, but operators using a
+  networked ``$HOME`` should be aware that concurrency guarantees weaken.
+  Local ``.kd/`` directories inside a repo are unaffected.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from kd.exceptions import ConfigError
+
+LOCK_SUFFIX = ".lock"
+_POLL_INTERVAL_SECONDS = 0.05
+
+
+@contextmanager
+def file_transaction(path: Path, *, timeout: float = 30.0) -> Generator[None, None, None]:
+    """Hold an exclusive advisory lock on ``<path>.lock`` for the ``with`` body.
+
+    The sidecar lockfile is created if missing (``O_RDWR | O_CREAT``,
+    never truncated).  Acquisition polls non-blocking ``flock`` until
+    the lock is granted or *timeout* seconds elapse.  On timeout, raises
+    :class:`ConfigError` naming the contested file.  The lockfile is
+    intentionally left on disk after release.
+
+    Raises :class:`ConfigError` on non-POSIX platforms.
+    """
+    if sys.platform == "win32":
+        raise ConfigError(
+            "File locking is not available on this platform (POSIX only).",
+            suggestion="Run the kd command sequentially; concurrent mutations are not supported on Windows.",
+        )
+
+    import fcntl  # noqa: PLC0415 — lazy import keeps kd importable on Windows
+
+    lock_path = path.with_name(path.name + LOCK_SUFFIX)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
+    try:
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise ConfigError(
+                        f"Another kd process is writing to {path}; retry in a moment.",
+                        suggestion=f"If no other kd process is running, remove the stale lockfile: {lock_path}",
+                    ) from None
+                time.sleep(_POLL_INTERVAL_SECONDS)
+
+        try:
+            yield
+        finally:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            except OSError:
+                pass
+    finally:
+        try:
+            os.close(fd)
+        except OSError:
+            pass

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/models/__init__.py

@@ -24,7 +24,7 @@ from kd.models.saved_query import (
     SavedQueryUpdate,
 )
 from kd.models.search import SearchResult
-from kd.models.tag import Tag, TagColor
+from kd.models.tag import Tag, TagColor, TagCreateResult
 from kd.models.tag_entities import EntityRef, KindMeta, TagEntitiesResult
 from kd.models.user import Group, ProjectTeam, User, UserCreate
 from kd.models.work_item import (
@@ -68,6 +68,7 @@ __all__ = [
     "SearchResult",
     "Tag",
     "TagColor",
+    "TagCreateResult",
     "TagEntitiesResult",
     "TimeTrackingSettings",
     "User",

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/models/tag.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Literal
+
 from pydantic import BaseModel, ConfigDict, Field
 
 from kd.models.common import IdEntity, NamedEntity
@@ -28,3 +30,18 @@ class Tag(IdEntity):
     owner: NamedEntity | None = None
     color: TagColor | None = None
     untag_on_resolve: bool = Field(default=False, alias="untagOnResolve")
+
+
+class TagCreateResult(BaseModel):
+    """Result of an idempotent tag-create call.
+
+    ``action`` is ``"create"`` when YouTrack minted a new tag and
+    ``"exists"`` when the pre-check resolved a tag with the requested
+    name (short-circuit, no POST). The ``tag`` field carries the current
+    upstream state either way.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    action: Literal["create", "exists"]
+    tag: Tag

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/primer.py

@@ -11,6 +11,8 @@ knowledge).  The file is created lazily on first write operation.
 from __future__ import annotations
 
 import importlib.resources
+from collections.abc import Generator
+from contextlib import contextmanager
 from pathlib import Path
 from typing import Any
 
@@ -18,6 +20,7 @@ import yaml
 from pydantic import BaseModel
 
 from kd.exceptions import ConfigError, ValidationError
+from kd.locking import file_transaction
 
 
 # ---------------------------------------------------------------------------
@@ -125,10 +128,15 @@ def load_primer(path: Path | None = None) -> PrimerData:
 
 
 def save_primer(data: PrimerData, path: Path | None = None) -> None:
-    """Write primer to YAML.
+    """Write primer to YAML — low-level primitive.
 
     Snapshots the current file before writing (copy-on-write) and uses
-    atomic writes to prevent partial-write corruption.
+    atomic writes to prevent partial-write corruption.  Does **not**
+    serialize concurrent writers on its own; callers that do
+    ``load_primer → mutate → save_primer`` across processes risk lost
+    updates.  Prefer the mutator functions below (:func:`add_note`,
+    :func:`update_note`, etc.), which wrap load/save in
+    :func:`primer_transaction` to guarantee per-file serialization.
     """
     from kd.history import atomic_write_text, snapshot_before_write
 
@@ -172,46 +180,56 @@ def _tag_dump(tag: dict[str, Any]) -> dict[str, Any]:
 # ---------------------------------------------------------------------------
 
 
+@contextmanager
+def _primer_transaction(path: Path) -> Generator[PrimerData, None, None]:
+    """Serialize a primer read-modify-write cycle under an advisory lock.
+
+    Holds an exclusive advisory lock on ``<path>.lock`` for the full
+    cycle: loads the primer, yields a ``PrimerData`` for the caller to
+    mutate in place, and saves on clean exit.  If the caller raises,
+    the save is skipped (the file is not modified).
+    """
+    with file_transaction(path):
+        data = load_primer(path)
+        yield data
+        save_primer(data, path)
+
+
 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)
+    with _primer_transaction(primer_file) as data:
+        data.notes.append(text)
+        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
+    with _primer_transaction(primer_file) as data:
+        if index < 1 or index > len(data.notes):
+            raise ValidationError(f"Note index {index} out of range (1–{len(data.notes)})")
+        return data.notes.pop(index - 1)
 
 
 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
+    with _primer_transaction(primer_file) as data:
+        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
+        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
+    with _primer_transaction(primer_file) as data:
+        count = len(data.notes)
+        data.notes.clear()
+        return count
 
 
 def add_article(
@@ -219,71 +237,63 @@ def add_article(
 ) -> 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
+    with _primer_transaction(primer_file) as data:
+        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)
+        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")
+    with _primer_transaction(primer_file) as data:
+        for i, article in enumerate(data.articles):
+            if article.id == article_id:
+                return data.articles.pop(i)
+        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
+    with _primer_transaction(primer_file) as data:
+        count = len(data.articles)
+        data.articles.clear()
+        return count
 
 
 def add_tag(name: str, summary: str | None = None, path: Path | None = None) -> PrimerTag:
     """Pin a tag. Raises if already pinned."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for existing in data.tags:
-        if existing.name == name:
-            raise ValidationError(f"Tag '{name}' is already pinned")
-    tag = PrimerTag(name=name, summary=summary)
-    data.tags.append(tag)
-    save_primer(data, primer_file)
-    return tag
+    with _primer_transaction(primer_file) as data:
+        for existing in data.tags:
+            if existing.name == name:
+                raise ValidationError(f"Tag '{name}' is already pinned")
+        tag = PrimerTag(name=name, summary=summary)
+        data.tags.append(tag)
+        return tag
 
 
 def remove_tag(name: str, path: Path | None = None) -> PrimerTag:
     """Unpin a tag by name. Returns the removed entry."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    for i, tag in enumerate(data.tags):
-        if tag.name == name:
-            removed = data.tags.pop(i)
-            save_primer(data, primer_file)
-            return removed
-    raise ValidationError(f"Tag '{name}' is not pinned")
+    with _primer_transaction(primer_file) as data:
+        for i, tag in enumerate(data.tags):
+            if tag.name == name:
+                return data.tags.pop(i)
+        raise ValidationError(f"Tag '{name}' is not pinned")
 
 
 def clear_tags(path: Path | None = None) -> int:
     """Remove all pinned tags. Returns the count removed."""
     primer_file = path or _primer_path()
-    data = load_primer(primer_file)
-    count = len(data.tags)
-    data.tags.clear()
-    save_primer(data, primer_file)
-    return count
+    with _primer_transaction(primer_file) as data:
+        count = len(data.tags)
+        data.tags.clear()
+        return count
 
 
 # ---------------------------------------------------------------------------

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.5.0] — 2026-04-19
+
+Dogfooding friction fixes across tag and article workflows, plus self-describing `/system info` output for bug reports. Focus of this release: the taxonomy and article-create loops now behave the way field use expects, and a paste of `kd /system info -o yaml` replaces hand-typed version footers.
+
+### Added
+- `kd /system info` now carries three additional fields alongside the existing connection identity: `kd_version` (matches `kd --version`), `python_version`, and `platform`. Paste `kd /system info -o yaml` into a bug report to tie an observed behavior to a specific build without hand-typing the version. The four existing keys (`url`, `user`, `name`, `email`) are unchanged; redact `url` / `email` before sharing externally (KDCLI-104).
+
+### Changed
+- `kd /tag create TAG_NAME` is now idempotent and returns a `{ok, action, tag}` envelope with `action` being either `create` or `exists`. Re-running create on an already-visible tag is safe and no longer surfaces `Tag.name-is-invalid`. **Breaking vs. the prior flat tag object** — downstream scripts and SDK consumers that parsed the top-level tag fields must now read from the nested `tag:` block. Python SDK: the `create(...)` method on the tag operations client returns a `TagCreateResult(action, tag)` object; unpack `.tag` to reach the tag fields (KDCLI-105).
+
+### Fixed
+- `kd /tag create TAG_NAME` against an already-existing tag no longer emits the raw upstream `Tag.name-is-invalid` error. When the POST still fails (genuinely unacceptable name, or a tag hidden by sharing/visibility that the caller cannot see), the error names both plausible causes without inventing a character grammar (KDCLI-105).
+- `kd /tag entities` structured output (`-o yaml` / `-o json`, including `--primer-scope`) now populates the `tags` field on issue rows, bringing the verb to parity with `/issue show --rich` and `/issue list --with-tags`. Before: structured issue rows reported `tags: []` even when they matched via a pinned tag, forcing a second `/issue show` round-trip to see which tag caused the match. Table output is unchanged and still omits the tag column by design (KDCLI-100).
+- `kd /article create --tag TAG` structured output now returns the post-tag article state: the response `tags` field matches a subsequent `kd /article show` on the returned id. Missing tags are rejected **before** the article is created, so a typo in `--tag` no longer leaves an untagged article behind; the error names `kd /tag create` for the missing tag, retrying `kd /article create` without the tag, or applying the tag after create via `kd /tag add ARTICLE-ID TAG`. Before: the CLI rendered `tags: ''` even when tags were attached upstream (KDCLI-101).
+
+## [2.4.1] — 2026-04-19
+
+### Fixed
+- Concurrent `kd /primer/note`, `/primer/tag`, and `/primer/article` commands against the same `.kd/primer.yaml` no longer silently lose writes. Before: running three `kd /primer/note update` calls in parallel (common in agent-driven sessions) all reported `ok: true` but only one update survived. Now: each command runs inside an advisory file lock on a sidecar `.kd/primer.yaml.lock`, so concurrent kd processes queue rather than clobber each other and every successful call is reflected in the final file. Concurrent acquirers wait up to 30 s before erroring with `Another kd process is writing to …; retry in a moment`; the error includes the path of the sidecar lockfile for stale-holder recovery. POSIX only; first lock attempt on Windows raises a clear error pointing at sequential invocation (KDCLI-98).
+
 ## [2.4.0] — 2026-04-19
 
 ### Added

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/resources/error-messages.yaml

@@ -70,6 +70,17 @@
   message: 'Issue {id} not found'
   suggestion: 'Check the issue ID and project key.'
 
+# --- Tag create 400 (path-scoped so rename POSTs are unaffected) ---
+
+- status: 400
+  path: '/tags$'
+  pattern: 'Tag\.name-is-invalid'
+  message: 'YouTrack rejected the tag name.'
+  suggestion: >-
+    The tag may already exist but be hidden by sharing or visibility
+    settings, or the name may contain characters YouTrack does not accept.
+    Verify with 'kd /tag show TAG_NAME' or try a different name.
+
 # --- Query parse errors ---
 
 - pattern: "(?i)can.t parse search query"

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd/resources/operating-guide.md

@@ -146,6 +146,8 @@ When both pinned tags and pinned articles exist, read them in order: notes tell
 
 Keep the primer local and curated. If a note becomes generally true for kd, move it into docs or this guide. If it is workspace-specific, keep it in `.kd/primer.yaml`.
 
+Primer mutations are serialized per file through an advisory lock on `.kd/primer.yaml.lock`; concurrent kd processes writing to the same primer queue rather than conflict, so agent-launched parallel `/primer/note`, `/primer/tag`, and `/primer/article` commands all converge without lost updates.
+
 ## Articles And Push
 
 Use `/article show` for metadata plus rendered content. Use `/article pull` when you need raw article content on stdout; `pull` is format-agnostic and ignores `--output`.
@@ -156,6 +158,8 @@ Do not use push for one-off web edits or broad tree migration. It is single-file
 
 When pushing with `--tag`, kd validates all tags before the article write. Missing tags abort with commands to list the namespace, create the tag, retry without it, or apply the tag separately after push. `--create-tags` is the explicit opt-in for automation that should create missing tags first.
 
+`/article create --tag` applies the same preflight: every tag must exist, missing tags abort before the article write (no orphan article on a typo), and the structured response reflects post-tag state so it matches an immediate `/article show` on the returned id. There is no `--create-tags` on `/article create` — curate the namespace with `/tag create` first, or omit `--tag` and apply tags after creation via `/tag add ARTICLE-ID TAG`.
+
 ## Tags And Discovery
 
 Tags are the main YouTrack-native cross-entity discovery primitive. A namespaced taxonomy such as `kind:*`, `component:*`, and `outcome:*` gives both humans and LLMs a stable way to move across issues and articles.
@@ -180,6 +184,10 @@ Use `/tag entities` when the question is "what do we know about this topic acros
 
 Do not treat `--primer-scope` as implicit global state. It is a deliberate flag for content-management triage and workspace orientation. When you need a precise topical intersection, pass the tags explicitly.
 
+`/tag entities` structured output (`-o yaml` / `-o json`) populates the `tags` field on both issue and article rows with the entity's visible tags, so a primer-scope or explicit-tag match is self-describing — no second `/issue show` round-trip is needed to confirm which tags caused a row to surface. Table output groups by kind and does not render a tag column.
+
+`/tag create TAG_NAME` is idempotent. It resolves the name first (same case-insensitive resolver `/tag show` uses) and returns `{ok, action, tag}` with `action: exists` when the tag is already visible, or `action: create` after a successful POST. Taxonomy bootstrapping and fixture setup can re-run the command safely without decoding `Tag.name-is-invalid`. When the POST still fails — either a genuinely unacceptable name or an existing tag hidden by sharing/visibility — kd surfaces a factual diagnostic naming both plausible causes rather than the raw upstream error.
+
 ## Output And Debugging
 
 For deterministic machine consumption, always pass an explicit output format:
@@ -209,6 +217,8 @@ kd /system/config which primer_show.output
 
 If a command exits 0 but includes `warnings` in JSON or YAML, keep the primary result and inspect the warning code. For example, `tag_not_found` on `/primer/tag add` means the local primer changed but the upstream tag did not resolve at validation time.
 
+When filing a kd bug, include the output of `kd /system info -o yaml`. It names the active connection alongside `kd_version`, `python_version`, and `platform`, so the report is self-describing without hand-typing the version. Redact `url` / `email` before sharing externally.
+
 ## Where To Go Next
 
 Use these sources together:

{kd_cli-2.4.0 → kd_cli-2.5.0/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.4.0 → kd_cli-2.5.0}/kd_cli.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ kd/connection.py
 kd/debug.py
 kd/exceptions.py
 kd/history.py
+kd/locking.py
 kd/operating_guide.py
 kd/primer.py
 kd/query_parser.py

{kd_cli-2.4.0 → kd_cli-2.5.0}/pyproject.toml

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