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

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

{kd_cli-2.4.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.4.1 → 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.1 → 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.1 → kd_cli-2.5.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,21 @@ 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

{kd_cli-2.4.1 → 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.1 → kd_cli-2.5.0}/kd/resources/operating-guide.md

@@ -158,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.
@@ -182,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:
@@ -211,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.1 → 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.1
+Version: 2.5.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

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

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