kd-cli 2.2.0__py3-none-any.whl → 2.2.2__py3-none-any.whl

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/main.py

@@ -30,6 +30,7 @@ from kd.config import ResolvedConfig, resolve_command_defaults, resolve_config
 from kd.connection import ConnectionContext, resolve_connection
 from kd.debug import DebugLevel, DebugLog, init_debug_log
 from kd.exceptions import KdError
+from kd.operating_guide import load_guide
 
 # Global options — single source of truth for extraction, help, and reference.
 GLOBAL_OPTIONS: list[OptionDeclaration] = [
@@ -54,6 +55,13 @@ GLOBAL_OPTIONS: list[OptionDeclaration] = [
         type=bool,
         help_text="Print full command reference (LLM-friendly)",
     ),
+    OptionDeclaration(
+        name="guide",
+        short_name="G",
+        layer=OptionLayer.GLOBAL,
+        type=bool,
+        help_text="Print embedded operating guide (LLM-friendly)",
+    ),
     OptionDeclaration(
         name="debug",
         short_name="D",
@@ -158,6 +166,10 @@ def main(argv: list[str] | None = None) -> None:
         print(f"kd {__version__}")
         return
 
+    if global_opts.get("guide"):
+        print(load_guide(), end="")
+        return
+
     # Alias expansion: detect `alias <name>` and expand before parsing.
     # Config is loaded early only when needed; stored for reuse later.
     resolved: ResolvedConfig | None = None

kd/client.py

@@ -279,11 +279,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 +346,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 +386,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:

kd/operating_guide.py

@@ -0,0 +1,20 @@
+"""Operating guide loader.
+
+Reads the bundled ``kd/resources/operating-guide.md`` for ``kd --guide``.
+The guide carries durable operating doctrine (product boundary, primer
+workflow, cost classes, YouTrack gotchas) — a complement to the
+syntax-focused ``kd --reference``.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+
+
+def load_guide() -> str:
+    """Read the bundled operating guide as text."""
+    return (
+        importlib.resources.files("kd.resources")
+        .joinpath("operating-guide.md")
+        .read_text(encoding="utf-8")
+    )

kd/resources/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [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 --guide` / `-G` prints an embedded operating guide covering kd's product boundary, primer workflow, cost classes, and YouTrack gotchas — the doctrine complement to the syntax-focused `kd --reference`. Runs without a connection or working config, so it's safe in fresh or broken-config environments (KDCLI-94).
+
 ## [2.2.0] — 2026-04-18
 
 Milestone 006 — tag discovery and taxonomy hygiene v1. Eight sequenced sessions that turn tags into a load-bearing cross-entity discovery primitive: `/issue` tag parity with `/article`, multi-tag intersection on `/tag issues`, the `/tag entities` cross-kind verb, `/tag list --prefix|--namespace` taxonomy introspection, and workspace-pinned tags on the primer consumed as an implicit OR scope.

kd/resources/operating-guide.md

@@ -97,6 +97,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.

{kd_cli-2.2.0.dist-info → kd_cli-2.2.2.dist-info}/METADATA

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

{kd_cli-2.2.0.dist-info → kd_cli-2.2.2.dist-info}/RECORD

@@ -1,7 +1,7 @@
 kd/__init__.py,sha256=hzqgTR9bMhfiHP3qoh3Z-0uJ4gTkPIIzEAvqSJp_gKU,993
 kd/article_marker.py,sha256=qfVw1Id9PEezYszq0yn6fJgY88-fz98OdNnF9G49xPA,12700
 kd/auth.py,sha256=uNq8wOZBPBa4-uYurZCBu2kSDy_eZlIu2yKzNjTnIp0,5459
-kd/client.py,sha256=8dkYK1OdoBwZOjsBiIDjOoMAmmpYhOKxyQZDA9jAfYw,85013
+kd/client.py,sha256=TisHwLEdJZJGhNA4haI1v-j0xKXoCubsL8cAzPXLBj8,85576
 kd/config.py,sha256=AvyN0GH-cQAVldVYlrFYCQq6a6QThh-8upQnUzB9RAQ,53714
 kd/config_read.py,sha256=tr3b_JGq3VYt8m-P9QJDS4s8E4_nS54I3RMOSl4D3EQ,7265
 kd/config_schema.py,sha256=H4PlVl5CorrztDEX3E4Y-4QHK5o-fpcPZsWIYybnJzM,7943
@@ -9,6 +9,7 @@ kd/connection.py,sha256=oHjT4i4dbnV47ZPpbw1eGmNPLM9PR2iO-xc_pxLwa2g,6728
 kd/debug.py,sha256=JvhBUiUvCzOSsH-ONfmKLnLHSaphbveAq_mbf-Y0OQY,3322
 kd/exceptions.py,sha256=-dtT9sD_qGXEtquoDQZ7wlm9oRTN3pDqxoIvJ-TPYg4,6533
 kd/history.py,sha256=osLPgcgK1dwDU5Af4LoNDMpmh2M6zyvJJO3TUoGtJPQ,5701
+kd/operating_guide.py,sha256=PvBolNHiSMKGxgyCQbx3cDPxd9Wq6zvURNiuzJ9Mo1w,567
 kd/primer.py,sha256=49PCHDtfTgWtBXTenGg_rjmecfQ7cwOPTp4_lCJmNRs,9714
 kd/query_parser.py,sha256=y4_xQ5eeeq9oeiUdCk4YdJ-MyJ5e-Ox72JWWouo0uNI,8205
 kd/release_notes.py,sha256=lrBIHvByCX-dojEljQqf8cbIAvoTOc_3ZV8Am_3wnkc,3294
@@ -18,10 +19,10 @@ kd/api/http.py,sha256=_lsWyvSktlKqb3v3Is-4-3dw_G-2ILquYvfXGEwyajo,8804
 kd/api/hub.py,sha256=zHEDr9-_SqqkVmC3Duu87Yx4bbLrEh0NbSSRhrD25ug,2364
 kd/api/saved_queries.py,sha256=5GhMqJeeTvcooC-07T6RU-WIxMGbRyMJKcGIGx3ihTk,2579
 kd/api/tags.py,sha256=P9gA-rfqinshgNFkkb0KLz0iIZR3rf-f-H1RwR63GNg,3275
-kd/api/youtrack.py,sha256=l3HeuDxQRc2p6D0O4DhLQlN_hYu3PzubNlsUFUNjt7M,14838
+kd/api/youtrack.py,sha256=YuVOExRvcy676gn6bA8q65QgaWYHtrPPCZWW3vKKZHU,15605
 kd/cli/__init__.py,sha256=Pvvndapu834rERT6IhFb5hqzSgr0V-fctfHCcz8uT0U,138
 kd/cli/input.py,sha256=u3gLQfRg0R5VS2s45s2q0shplussssSHP5TdA7IliK0,1350
-kd/cli/main.py,sha256=501IRnTyunSzxGaPRcJFnkfbOMJ3504P7oyhJ-9kmkU,21974
+kd/cli/main.py,sha256=Ry8oiafbEiltpwnN_bGVoOEggSrOGoGfioeLrqxg6mY,22297
 kd/cli/output.py,sha256=O8qfOSV-zwsGu79snQwizpOi1KoAzbepF7u2tIoqIIM,17775
 kd/cli/tree.py,sha256=1fMQ6QZNL6LGt7GzsbxR-ECzRyp9wTxP2Ca7l5Hvc4A,1883
 kd/cli/core/__init__.py,sha256=cwxvTg-ABcTHnnC86UDjrNfxT7ekRFnn2p_J12QoFG4,588
@@ -57,15 +58,15 @@ kd/models/tag.py,sha256=imrqqi-M-5aepel5pk81DmsRu0W6pbNcPRkZYVHYHl8,742
 kd/models/tag_entities.py,sha256=GhEufLlG_pN_p-5H-mipzodeBg0n0ovhlsMpWKrIrHY,1335
 kd/models/user.py,sha256=ICu10OdvZJVuXtFC5XUYreUdJRpDmfQbILR1bjPDZ6k,912
 kd/models/work_item.py,sha256=fJXcSiTQQmXa9d4IuFYmcmC1qrlupNJjtYFW1tzYv6A,1394
-kd/resources/CHANGELOG.md,sha256=YnW_WHO9JspfstT_IHKaPok91785iYvx0Bb-XOOSKwc,12227
+kd/resources/CHANGELOG.md,sha256=Waf9fGCccc7TIsXCYOrfSkJohyiWSRkJ_TWHgB-wLj4,12866
 kd/resources/__init__.py,sha256=yHAagxZ8q-eFXM0-mvWkafl_zQWDmaq7V2d_S8BAd0k,58
 kd/resources/command-synonyms.yaml,sha256=KW4hT9YSCB1rw_k51fNRf5XhCq-olic-JS_VMi5ufuY,435
 kd/resources/config-template.yaml,sha256=PszXHqT9-iYEaWOk995-xecCsX9kDi8Un2j2l-pNVKM,1616
 kd/resources/error-messages.yaml,sha256=fHzMW0vlNDaudEWMOMk_mbxZoGQKGarBKtUfk_Bpcn0,3857
-kd/resources/operating-guide.md,sha256=wLWvOzrSven9EB6XNktmIf34zXcQ0tYbiPqQsKxT1QQ,12390
-kd_cli-2.2.0.dist-info/licenses/LICENSE,sha256=snwwWzfIuTq72ybFaCbx-o5n8SXhNxPMgUjqSSnSS8U,1071
-kd_cli-2.2.0.dist-info/METADATA,sha256=S5ZujYKr5zLdz2pw7u9znceXsSYNEfbovK3-piXkrKo,7168
-kd_cli-2.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-kd_cli-2.2.0.dist-info/entry_points.txt,sha256=njF_5vmjE3couro9XU8CRuqQzpp-VqmAmq63bmxZeqo,40
-kd_cli-2.2.0.dist-info/top_level.txt,sha256=-ZAP5fwCL_0Wess0ja8bEYr1IjR8LfrEuBtjEDxD8XU,3
-kd_cli-2.2.0.dist-info/RECORD,,
+kd/resources/operating-guide.md,sha256=nkgmq-IYeCn9mbNfTqW9l5_4PZ4GDXlmeC-U21C0QBk,12566
+kd_cli-2.2.2.dist-info/licenses/LICENSE,sha256=snwwWzfIuTq72ybFaCbx-o5n8SXhNxPMgUjqSSnSS8U,1071
+kd_cli-2.2.2.dist-info/METADATA,sha256=ct7DYeMOckJGk0v_VA0l0SEou2AkNM1t9ib3Au6WAGk,7168
+kd_cli-2.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+kd_cli-2.2.2.dist-info/entry_points.txt,sha256=njF_5vmjE3couro9XU8CRuqQzpp-VqmAmq63bmxZeqo,40
+kd_cli-2.2.2.dist-info/top_level.txt,sha256=-ZAP5fwCL_0Wess0ja8bEYr1IjR8LfrEuBtjEDxD8XU,3
+kd_cli-2.2.2.dist-info/RECORD,,