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

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

{kd_cli-2.2.1 → kd_cli-2.3.0}/kd/api/youtrack.py

@@ -24,6 +24,7 @@ from kd.models import (
     Attachment,
     Comment,
     CommentCreate,
+    CustomField,
     FieldSet,
     Issue,
     IssueCreate,
@@ -38,6 +39,28 @@ from kd.models import (
     WorkItemType,
 )
 
+
+def _custom_field_payload(field: CustomField) -> dict[str, Any]:
+    payload = field.model_dump(by_alias=True, exclude_none=True)
+    if field.value is None:
+        payload["value"] = None
+    return payload
+
+
+def _issue_create_payload(issue: IssueCreate) -> dict[str, Any]:
+    payload = issue.model_dump(by_alias=True, exclude_none=True)
+    if issue.custom_fields is not None:
+        payload["customFields"] = [_custom_field_payload(field) for field in issue.custom_fields]
+    return payload
+
+
+def _issue_update_payload(update: IssueUpdate) -> dict[str, Any]:
+    payload = update.model_dump(by_alias=True, exclude_none=True)
+    if update.custom_fields is not None:
+        payload["customFields"] = [_custom_field_payload(field) for field in update.custom_fields]
+    return payload
+
+
 # Default field selections for common queries
 _PROJECT_LIST_FIELDS = str(
     FieldSet(
@@ -226,7 +249,7 @@ class YouTrackAPI:
     def create_issue(self, issue: IssueCreate) -> Issue:
         data = self._http.post(
             "/issues",
-            json=issue.model_dump(by_alias=True, exclude_none=True),
+            json=_issue_create_payload(issue),
             fields=_ISSUE_FIELDS,
         )
         return Issue.model_validate(data)
@@ -234,7 +257,7 @@ class YouTrackAPI:
     def update_issue(self, issue_id: str, update: IssueUpdate) -> Issue:
         data = self._http.post(
             f"/issues/{issue_id}",
-            json=update.model_dump(by_alias=True, exclude_none=True),
+            json=_issue_update_payload(update),
             fields=_ISSUE_FIELDS,
         )
         return Issue.model_validate(data)

{kd_cli-2.2.1 → 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.1 → 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,
@@ -279,11 +280,7 @@ class FieldSchema:
                 )
 
             validated_value = self._validate_field_value(field, value)
-            field_value = (
-                {"login": validated_value}
-                if self._is_user_field(field)
-                else {"name": validated_value}
-            )
+            field_value = self._field_value_payload(field, validated_value)
             self._debug.debug(
                 "fields",
                 f"resolved '{slot}' -> field '{field.name}' ($type={issue_type})",
@@ -350,9 +347,7 @@ class FieldSchema:
                 f"Unsupported field type '{field.project_field_type}' for field '{field.name}'"
             )
         validated_value = self._validate_field_value(field, value)
-        field_value = (
-            {"login": validated_value} if self._is_user_field(field) else {"name": validated_value}
-        )
+        field_value = self._field_value_payload(field, validated_value)
         self._debug.debug(
             "fields",
             f"resolved generic '{field_name}' -> field '{field.name}' "
@@ -392,16 +387,36 @@ class FieldSchema:
         """Return True if this field is a user-type field (user[1])."""
         return field.field_type_id.startswith("user")
 
+    def _field_value_payload(
+        self,
+        field: ProjectCustomField,
+        value: str | None,
+    ) -> dict[str, str] | None:
+        """Build the YouTrack issue-field value payload.
+
+        ``None`` is a deliberate clear operation and must serialize as
+        ``"value": null`` in the final issue mutation payload.
+        """
+        if value is None:
+            return None
+        return {"login": value} if self._is_user_field(field) else {"name": value}
+
     def _validate_field_value(
         self,
         field: ProjectCustomField,
         value: str,
-    ) -> str:
+    ) -> str | None:
         """Validate a value against the field's bundle.
 
-        Returns the canonical value name (case-corrected).
+        Returns the canonical value name (case-corrected), or ``None``
+        when an optional field should be cleared.
         Raises ValidationError with allowed values on mismatch.
         """
+        if value == "":
+            if field.can_be_empty:
+                return None
+            raise ValidationError(f"Field '{field.name}' is required and cannot be cleared.")
+
         if self._is_user_field(field):
             return value  # User fields: server validates against group members
         if not field.bundle_values:
@@ -999,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."""
 
@@ -1123,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,
@@ -1146,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.
 
@@ -1264,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.1 → kd_cli-2.3.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,19 @@ 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 /issue update ID --field "NAME="` now clears optional custom fields by sending `value: null` to YouTrack. Required fields reject empty values with a clear client-side error instead of the generic "invalid value" bundle message (KDCLI-81).
+
 ## [2.2.1] — 2026-04-18
 
 ### Added

{kd_cli-2.2.1 → 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
 
@@ -97,6 +98,8 @@ Issue custom fields are project-specific and need `$type` discriminators on muta
 kd /project/field list KDCLI
 ```
 
+Clear optional custom fields with an empty value, for example `kd /issue update KDCLI-42 --field "Milestone="`. Required fields reject empty values before any upstream write.
+
 Attachment metadata download URLs may start with `/api/`. kd handles this internally on download commands; do not assume the raw URL can be appended unchanged to an API base URL in custom scripts.
 
 Tag existence, tag visibility, and tag sharing rights are different concerns. A visible tag may not be usable for every operation, and sharing settings are provider-specific security posture, not just display metadata.
@@ -141,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.1 → 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.1
+Version: 2.3.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

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

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