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

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

@@ -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 → kd_cli-2.2.2}/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.0 → kd_cli-2.2.2}/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_cli-2.2.0 → kd_cli-2.2.2}/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_cli-2.2.2/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_cli-2.2.0 → kd_cli-2.2.2}/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_cli-2.2.0 → kd_cli-2.2.2}/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 → kd_cli-2.2.2/kd_cli.egg-info}/PKG-INFO

@@ -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 → kd_cli-2.2.2}/kd_cli.egg-info/SOURCES.txt

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

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

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