kd-cli 2.2.2__tar.gz → 2.3.0__tar.gz

{kd_cli-2.2.2/kd_cli.egg-info → kd_cli-2.3.0}/PKG-INFO

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

{kd_cli-2.2.2 → kd_cli-2.3.0}/kd/cli/namespaces/article/__init__.py

@@ -181,7 +181,7 @@ class ArticlePushCommand(Command):
             requires_client=True,
             usage=(
                 "kd /article push FILE --project P --title T "
-                "[--slug S] [--parent ID] [--tag T] [--force] [--dry-run]"
+                "[--slug S] [--parent ID] [--tag T] [--create-tags] [--force] [--dry-run]"
             ),
             long_description=(
                 "Push a local markdown file to YouTrack as a knowledge base "
@@ -201,6 +201,7 @@ class ArticlePushCommand(Command):
                 'kd /article push guide.md --project FB --title "User Guide" --parent FB-A-1',
                 'kd /article push guide.md --project FB --title "Guide" --tag "type:guide"',
                 'kd /article push guide.md --project FB --title "Guide" --tag "type:guide" --tag "platform:rdk-e"',
+                'kd /article push guide.md --project FB --title "Guide" --tag "type:guide" --create-tags',
                 'kd /article push guide.md --project FB --title "Guide" --dry-run',
                 'kd /article push guide.md --project FB --title "Guide" --force',
             ],
@@ -264,6 +265,15 @@ class ArticlePushCommand(Command):
                 help_text="Resolve and validate, but do not write anywhere",
             )
         )
+        self.register_option(
+            OptionDeclaration(
+                name="create-tags",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Create missing tags before pushing",
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -289,6 +299,7 @@ class ArticlePushCommand(Command):
             force=bool(options.command.get("force")),
             dry_run=bool(options.command.get("dry-run")),
             tags=tags or None,
+            create_tags=bool(options.command.get("create-tags")),
         )
         return {
             "ok": True,

{kd_cli-2.2.2 → kd_cli-2.3.0}/kd/client.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 
 import builtins
 import difflib
+import shlex
 from collections import OrderedDict
 from dataclasses import dataclass, field as dataclass_field
 from datetime import datetime, timezone
@@ -43,7 +44,7 @@ from kd.article_marker import (
 from kd.config import ResolvedConfig
 from kd.connection import ConnectionContext
 from kd.debug import DebugLog
-from kd.exceptions import APIError, ConfigError, NotFoundError, ValidationError, KdError
+from kd.exceptions import APIError, ConfigError, KdError, NotFoundError, ValidationError
 from kd.query_parser import youtrack_query_literal
 from kd.models import (
     Article,
@@ -1013,6 +1014,44 @@ class TimeOperations:
         raise ValidationError(f"Unknown work item type '{name}'. Available: {available}")
 
 
+def _tag_prefix_for_list(tag: str) -> str:
+    """Return the smallest useful prefix for missing-tag discovery."""
+    if ":" in tag:
+        return tag.split(":", 1)[0] + ":"
+    return tag
+
+
+def _extract_tag_suggestions(error: NotFoundError) -> builtins.list[str]:
+    """Extract close-match names from the existing tag resolver message."""
+    message = str(error)
+    marker = "Did you mean: "
+    if marker not in message:
+        return []
+    raw = message.split(marker, 1)[1].rstrip(".?")
+    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."""
+    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)}",
+            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)}.",
+        ]
+    )
+    return "\n".join(lines)
+
+
 class ArticleOperations:
     """High-level knowledge base article operations."""
 
@@ -1137,6 +1176,41 @@ class ArticleOperations:
                 failed.append(f"{tag} ({exc})")
         return applied, failed
 
+    def _preflight_tags(
+        self,
+        tags: builtins.list[str],
+        *,
+        create_missing: bool = False,
+        dry_run: bool = False,
+    ) -> builtins.list[str]:
+        """Resolve tags before mutating an article.
+
+        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.
+        """
+        if self._tag_ops is None:
+            raise KdError("Tag operations not available")
+        failed: builtins.list[str] = []
+        for tag in tags:
+            try:
+                self._tag_ops.get(tag)
+            except NotFoundError as exc:
+                if create_missing:
+                    if dry_run:
+                        continue
+                    try:
+                        self._tag_ops.create(tag)
+                    except KdError as create_exc:
+                        failed.append(
+                            f"Tag '{tag}' not found and could not be created. {create_exc}"
+                        )
+                    continue
+                failed.append(_missing_tag_resolution(tag, exc))
+            except KdError as exc:
+                failed.append(f"Tag '{tag}' could not be resolved. {exc}")
+        return failed
+
     def update(
         self,
         article_id: str,
@@ -1160,6 +1234,7 @@ class ArticleOperations:
         force: bool = False,
         dry_run: bool = False,
         tags: builtins.list[str] | None = None,
+        create_tags: bool = False,
     ) -> PushResult:
         """Idempotently upsert a local markdown file as a YouTrack article.
 
@@ -1278,6 +1353,18 @@ class ArticleOperations:
                 f"move {existing_remote.id_readable} --parent {parent}."
             )
 
+        if tags:
+            preflight_failed = self._preflight_tags(
+                tags,
+                create_missing=create_tags,
+                dry_run=dry_run,
+            )
+            if preflight_failed:
+                raise KdError(
+                    f"Article {'update' if is_update else 'create'} aborted because "
+                    "tagging failed.\n\n" + "\n\n".join(preflight_failed)
+                )
+
         # Dry-run bails out here with all validation done but no writes.
         if dry_run:
             existing_sec = 0

{kd_cli-2.2.2 → kd_cli-2.3.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.3.0] — 2026-04-18
+
+### Added
+- `/article push --create-tags` explicitly creates missing tags before pushing and attaching them, for scripted flows that own their tag namespace (KDCLI-85).
+
+### Fixed
+- `/article push --tag` missing-tag failures now print actionable recovery commands instead of a bare not-found / close-match message (KDCLI-85).
+
 ## [2.2.2] — 2026-04-18
 
 ### Fixed

{kd_cli-2.2.2 → kd_cli-2.3.0}/kd/resources/operating-guide.md

@@ -80,6 +80,7 @@ kd /issue update KDCLI-42 --state Fixed -o yaml
 ```
 
 For article push, use `--dry-run` before a risky write and inspect conflicts with `/article pull`.
+`/article push --tag` rejects missing tags by default and prints the concrete recovery commands. Use `--create-tags` only for scripted flows that already own the tag namespace.
 
 ## YouTrack Gotchas
 
@@ -143,6 +144,8 @@ Use `/article show` for metadata plus rendered content. Use `/article pull` when
 
 Do not use push for one-off web edits or broad tree migration. It is single-file by design. If the remote changed, pull, diff, merge by hand, then push again. Use `--force` only after inspecting the remote state.
 
+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.
+
 ## 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.

{kd_cli-2.2.2 → kd_cli-2.3.0/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.2.2 → kd_cli-2.3.0}/pyproject.toml

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