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

{kd_cli-2.5.0/kd_cli.egg-info → kd_cli-2.5.2}/PKG-INFO

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

{kd_cli-2.5.0 → kd_cli-2.5.2}/kd/cli/namespaces/article/__init__.py

@@ -181,7 +181,8 @@ class ArticlePushCommand(Command):
             requires_client=True,
             usage=(
                 "kd /article push FILE --project P --title T "
-                "[--slug S] [--parent ID] [--tag T] [--create-tags] [--force] [--dry-run]"
+                "[--slug S] [--parent ID] [--tag T] [--create-tags] "
+                "[--force] [--dry-run] [--no-marker-write]"
             ),
             long_description=(
                 "Push a local markdown file to YouTrack as a knowledge base "
@@ -194,7 +195,13 @@ class ArticlePushCommand(Command):
                 "the marker — treat the file as owned by push after the first "
                 "run, like Cargo.lock. "
                 "Refuses to overwrite a remotely-edited article unless --force "
-                "is passed. --dry-run exits 1 on would-conflict, 0 on would-succeed."
+                "is passed. --dry-run exits 1 on would-conflict, 0 on would-succeed. "
+                "Pass --no-marker-write for one-way migrations where the local "
+                "file will be deleted after the push: the article is still "
+                "created/updated and tags are still applied, but the local file "
+                "is not rewritten. Re-running --no-marker-write pays the "
+                "scan-by-slug cost on every invocation since no upstream-id is "
+                "cached locally."
             ),
             examples=[
                 'kd /article push docs/infra/dns-setup.md --project FB --title "DNS Setup Guide"',
@@ -204,6 +211,8 @@ class ArticlePushCommand(Command):
                 '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',
+                'kd /article push migrated.md --project FB --title "Migrated" --no-marker-write',
+                'kd /article push migrated.md --project FB --title "Migrated" --no-marker-write --tag "type:guide"',
             ],
             see_also=[
                 "/article pull",
@@ -274,6 +283,18 @@ class ArticlePushCommand(Command):
                 help_text="Create missing tags before pushing",
             )
         )
+        self.register_option(
+            OptionDeclaration(
+                name="no-marker-write",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Skip the local kd-meta marker rewrite for one-way "
+                    "migrations; the server write and tag apply still run"
+                ),
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -300,6 +321,7 @@ class ArticlePushCommand(Command):
             dry_run=bool(options.command.get("dry-run")),
             tags=tags or None,
             create_tags=bool(options.command.get("create-tags")),
+            write_marker=not bool(options.command.get("no-marker-write")),
         )
         return {
             "ok": True,
@@ -310,6 +332,8 @@ class ArticlePushCommand(Command):
             "dry_run": result.dry_run,
             "tags_applied": result.tags_applied,
             "tags_failed": result.tags_failed,
+            "marker_written": result.marker_written,
+            "parent": result.parent,
         }
 
 

{kd_cli-2.5.0 → kd_cli-2.5.2}/kd/cli/namespaces/issue/__init__.py

@@ -270,11 +270,20 @@ class IssueCreateCommand(Command):
             "Create an issue",
             requires_client=True,
             usage='kd /issue create "Summary" --project P [--field NAME=VALUE] [--attach FILE]',
-            long_description="Summary is the issue title. --project is the project key (e.g. FB).",
+            long_description=(
+                "Summary is the issue title. --project is the project key (e.g. FB). "
+                "--field NAME=VALUE supports bundle families (enum, state, owned, "
+                "version, build), user logins, period, and string custom fields; the "
+                "field name is fuzzy-matched and the value is passed verbatim. "
+                "Unsupported families (text, Multi*, and integer/float/date subtypes "
+                "of SimpleProjectCustomField) fail client-side with an error naming "
+                "both the project $type and fieldType.id subtype."
+            ),
             examples=[
                 'kd /issue create "Fix router config" --project FB --type Task',
                 'kd /issue create "Bug report" -p FB --attach screenshot.png --attach log.txt',
                 'kd /issue create "Sprint task" -p FB --field "Sprint=Sprint 47"',
+                'kd /issue create "Tracked" -p VIS --field "Milestone=M039"',
                 'kd /issue create "Design doc" -p FB --description @design.md',
             ],
             see_also=["/issue list", "/issue show", "/issue/attachment add", "/project/field list"],
@@ -437,10 +446,21 @@ class IssueUpdateCommand(Command):
             "Update an issue",
             requires_client=True,
             usage="kd /issue update ID [--title T] [--field NAME=VALUE]",
+            long_description=(
+                "--field NAME=VALUE supports bundle families (enum, state, owned, "
+                "version, build), user logins, period, and string custom fields; the "
+                "field name is fuzzy-matched and the value is passed verbatim. "
+                "Clear optional custom fields with NAME= (empty value). Unsupported "
+                "families (text, Multi*, and integer/float/date subtypes of "
+                "SimpleProjectCustomField) fail client-side with an error naming "
+                "both the project $type and fieldType.id subtype."
+            ),
             examples=[
                 'kd /issue update FB-42 --title "New title"',
                 "kd /issue update FB-42 --state Open --priority Critical",
                 'kd /issue update FB-42 --field "Sprint=Sprint 48"',
+                'kd /issue update VIS-21 --field "Milestone=M039"',
+                'kd /issue update FB-42 --field "Milestone="',
                 "kd /issue update FB-42 --description @updated.md",
             ],
             see_also=["/issue show", "/project/field list"],

{kd_cli-2.5.0 → kd_cli-2.5.2}/kd/client.py

@@ -22,6 +22,7 @@ import builtins
 import difflib
 import shlex
 from collections import OrderedDict
+from collections.abc import Callable
 from dataclasses import dataclass, field as dataclass_field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -130,15 +131,43 @@ def _resolve_link_command(link_type: str) -> str:
     return result
 
 
-# Maps project custom field $type to the $type needed for issue mutations.
-_PROJECT_TO_ISSUE_TYPE: dict[str, str] = {
-    "EnumProjectCustomField": "SingleEnumIssueCustomField",
-    "StateProjectCustomField": "StateIssueCustomField",
-    "UserProjectCustomField": "SingleUserIssueCustomField",
-    "OwnedProjectCustomField": "SingleOwnedIssueCustomField",
-    "VersionProjectCustomField": "MultiVersionIssueCustomField",
-    "BuildProjectCustomField": "SingleBuildIssueCustomField",
-    "PeriodProjectCustomField": "PeriodIssueCustomField",
+# Dispatch over (project_field_type, field_type_id) → (issue_type, payload_builder).
+#
+# The builder wraps a validated value into the exact shape YouTrack expects in
+# the ``customFields[].value`` slot of an issue create/update payload. Bundle
+# families wrap as ``{"name": ...}``; user fields wrap as ``{"login": ...}``;
+# the scalar simple-string family passes through verbatim.
+#
+# ``""`` as the second tuple element means "any field_type_id under this
+# ``$type``" — used when every subtype of a family shares one payload shape.
+# A specific ``field_type_id`` key wins over the wildcard when both are present
+# (see ``SimpleProjectCustomField`` which only supports the ``string`` subtype
+# this session; ``integer``/``float``/``date`` stay unmapped).
+
+FieldValueBuilder = Callable[[str], Any]
+
+
+def _bundle_name(value: str) -> dict[str, str]:
+    return {"name": value}
+
+
+def _user_login(value: str) -> dict[str, str]:
+    return {"login": value}
+
+
+def _scalar(value: str) -> str:
+    return value
+
+
+_FIELD_DISPATCH: dict[tuple[str, str], tuple[str, FieldValueBuilder]] = {
+    ("EnumProjectCustomField", ""): ("SingleEnumIssueCustomField", _bundle_name),
+    ("StateProjectCustomField", ""): ("StateIssueCustomField", _bundle_name),
+    ("UserProjectCustomField", ""): ("SingleUserIssueCustomField", _user_login),
+    ("OwnedProjectCustomField", ""): ("SingleOwnedIssueCustomField", _bundle_name),
+    ("VersionProjectCustomField", ""): ("MultiVersionIssueCustomField", _bundle_name),
+    ("BuildProjectCustomField", ""): ("SingleBuildIssueCustomField", _bundle_name),
+    ("PeriodProjectCustomField", ""): ("PeriodIssueCustomField", _bundle_name),
+    ("SimpleProjectCustomField", "string"): ("SimpleIssueCustomField", _scalar),
 }
 
 # Default target field names for semantic CLI slots.
@@ -166,6 +195,11 @@ class PushResult:
     - ``remote_updated_sec`` is the epoch-seconds timestamp of the
       article's ``updated`` field on the upstream side after the push.
       Zero for dry-runs that did not resolve an existing article.
+    - ``marker_written`` is ``True`` iff the local file was rewritten
+      on this invocation. ``False`` for dry-runs and for
+      ``write_marker=False`` pushes (one-way migrations).
+    - ``parent`` is the ``id_readable`` of the target article's parent
+      on the upstream side, or ``None`` for root articles.
     """
 
     action: Literal["create", "update"]
@@ -176,6 +210,8 @@ class PushResult:
     dry_run: bool
     tags_applied: builtins.list[str] = dataclass_field(default_factory=list)
     tags_failed: builtins.list[str] = dataclass_field(default_factory=list)
+    marker_written: bool = False
+    parent: str | None = None
 
 
 def _derive_slug_from_path(file_path: Path) -> str:
@@ -274,14 +310,10 @@ class FieldSchema:
             self._debug.debug("fields", f"resolving slot '{slot}' -> target '{target_name}'")
 
             field = self._find_field(project_fields, target_name, slot)
-            issue_type = _PROJECT_TO_ISSUE_TYPE.get(field.project_field_type)
-            if not issue_type:
-                raise ValidationError(
-                    f"Unsupported field type '{field.project_field_type}' for field '{field.name}'"
-                )
+            issue_type, builder = self._resolve_dispatch(field)
 
             validated_value = self._validate_field_value(field, value)
-            field_value = self._field_value_payload(field, validated_value)
+            field_value = builder(validated_value) if validated_value is not None else None
             self._debug.debug(
                 "fields",
                 f"resolved '{slot}' -> field '{field.name}' ($type={issue_type})",
@@ -342,13 +374,9 @@ class FieldSchema:
         """
         project_fields = self.get_fields(project_id)
         field = self._find_field_fuzzy(project_fields, field_name)
-        issue_type = _PROJECT_TO_ISSUE_TYPE.get(field.project_field_type)
-        if not issue_type:
-            raise ValidationError(
-                f"Unsupported field type '{field.project_field_type}' for field '{field.name}'"
-            )
+        issue_type, builder = self._resolve_dispatch(field)
         validated_value = self._validate_field_value(field, value)
-        field_value = self._field_value_payload(field, validated_value)
+        field_value = builder(validated_value) if validated_value is not None else None
         self._debug.debug(
             "fields",
             f"resolved generic '{field_name}' -> field '{field.name}' "
@@ -388,19 +416,30 @@ 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,
+    @staticmethod
+    def _resolve_dispatch(
         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.
+    ) -> tuple[str, FieldValueBuilder]:
+        """Look up the issue-side ``$type`` and payload builder for *field*.
+
+        Prefers an exact ``(project_field_type, field_type_id)`` key, then
+        falls back to the wildcard ``(project_field_type, "")`` key for
+        families where every subtype shares a payload shape. Unmapped
+        combinations raise a ``ValidationError`` naming both identifiers so
+        a follow-on ticket has the upstream type info it needs.
         """
-        if value is None:
-            return None
-        return {"login": value} if self._is_user_field(field) else {"name": value}
+        key = (field.project_field_type, field.field_type_id)
+        if key in _FIELD_DISPATCH:
+            return _FIELD_DISPATCH[key]
+        wildcard = (field.project_field_type, "")
+        if wildcard in _FIELD_DISPATCH:
+            return _FIELD_DISPATCH[wildcard]
+        raise ValidationError(
+            f"Unsupported custom field type '{field.project_field_type}' "
+            f"with subtype '{field.field_type_id}' for field '{field.name}'. "
+            "kd does not know how to build a safe value payload for this "
+            "YouTrack field family."
+        )
 
     def _validate_field_value(
         self,
@@ -421,7 +460,7 @@ class FieldSchema:
         if self._is_user_field(field):
             return value  # User fields: server validates against group members
         if not field.bundle_values:
-            return value  # Freeform field (period, text) — accept as-is
+            return value  # Freeform family (period or scalar string) — server validates
 
         # Case-insensitive exact match → return canonical name
         value_lower = value.lower()
@@ -684,7 +723,7 @@ class IssueOperations:
             if "=" not in pair:
                 raise ValidationError(f"Invalid field format: '{pair}'. Expected NAME=VALUE")
             name, value = pair.split("=", 1)
-            cf = self._field_schema.resolve_field(project_obj.id, name.strip(), value.strip())
+            cf = self._field_schema.resolve_field(project_obj.id, name.strip(), value)
             result.append(cf)
         return result
 
@@ -1272,6 +1311,7 @@ class ArticleOperations:
         dry_run: bool = False,
         tags: builtins.list[str] | None = None,
         create_tags: bool = False,
+        write_marker: bool = True,
     ) -> PushResult:
         """Idempotently upsert a local markdown file as a YouTrack article.
 
@@ -1282,6 +1322,10 @@ class ArticleOperations:
 
         On success, the local file is rewritten atomically to refresh
         the marker's ``upstream-id`` and ``upstream-updated`` fields.
+        Pass ``write_marker=False`` for one-way migrations where the
+        local file will be deleted after the push — the outgoing
+        server payload is unchanged, only the local write-back is
+        skipped. See ``PushResult.marker_written`` (KDCLI-110).
         """
         # Step 1: read the local file and parse the marker.
         try:
@@ -1405,8 +1449,12 @@ class ArticleOperations:
         # Dry-run bails out here with all validation done but no writes.
         if dry_run:
             existing_sec = 0
-            if existing_remote is not None and existing_remote.updated is not None:
-                existing_sec = existing_remote.updated // 1000
+            existing_parent: str | None = None
+            if existing_remote is not None:
+                if existing_remote.updated is not None:
+                    existing_sec = existing_remote.updated // 1000
+                if existing_remote.parent_article is not None:
+                    existing_parent = existing_remote.parent_article.id_readable
             return PushResult(
                 action="update" if is_update else "create",
                 article_id=existing_remote.id_readable if existing_remote else "",
@@ -1414,6 +1462,8 @@ class ArticleOperations:
                 path=file_path,
                 remote_updated_sec=existing_sec,
                 dry_run=True,
+                marker_written=False,
+                parent=existing_parent,
             )
 
         # Step 7: build outgoing content. `upstream-updated` is intentionally
@@ -1482,10 +1532,18 @@ class ArticleOperations:
         )
         final_content = render_content(final)
 
-        # Step 10: atomic local write-back.
-        _atomic_write_text(file_path, final_content)
+        # Step 10: atomic local write-back (skipped for one-way
+        # migration flows that opt out via write_marker=False; the
+        # server payload in Step 7 is unchanged either way).
+        if write_marker:
+            _atomic_write_text(file_path, final_content)
 
         # Step 11: return result.
+        result_parent: str | None = (
+            result_article.parent_article.id_readable
+            if result_article.parent_article is not None
+            else None
+        )
         push_result = PushResult(
             action="update" if is_update else "create",
             article_id=result_article.id_readable,
@@ -1495,6 +1553,8 @@ class ArticleOperations:
             dry_run=False,
             tags_applied=tags_applied,
             tags_failed=tags_failed,
+            marker_written=write_marker,
+            parent=result_parent,
         )
         if tags_failed:
             raise KdError(

{kd_cli-2.5.0 → kd_cli-2.5.2}/kd/resources/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.5.2] — 2026-04-19
+
+### Fixed
+- `kd /article push` one-way migrations no longer force `git rm -f`. Before: push always rewrote the local markdown file with a `kd-meta` marker on success, which left the file "locally modified" and made `git rm` refuse without `-f` on migrations that delete the local copy after push. Now: pass `--no-marker-write` to skip the local rewrite. The upstream article is still created or updated, `--tag` values are still applied, and the outgoing server payload still carries a marker with the slug — so scan-by-slug resolves the article on any later push even without the local file. Default behavior is unchanged; the flag is opt-in (KDCLI-110).
+
+### Added
+- `kd /article push` structured output (`-o yaml` / `-o json`) now carries two sibling keys on every push: `marker_written` (`false` for dry-runs and `--no-marker-write` pushes, `true` on the default path after the local rewrite) and `parent` (readable id of the target article's upstream parent, or `null` for root articles). Scripts can assert local-file state and the article's place in the tree from the push response directly (KDCLI-110).
+
+## [2.5.1] — 2026-04-19
+
+### Fixed
+- `kd /issue create --field NAME=VALUE` and `kd /issue update --field NAME=VALUE` now accept **string custom fields**. Before: `kd /issue update VIS-21 --field Milestone=M039` rejected with `Error: Unsupported field type 'SimpleProjectCustomField' for field 'Milestone'`, blocking workflows that track freeform per-issue metadata such as a rolling milestone string. `--field "NAME="` clears an optional string field just like it clears enum/user fields today; required string fields reject empty values with the same client-side error shipped in 2.2.2. Whitespace inside the value is preserved — `--field "Milestone=  M 039  "` sends `  M 039  ` verbatim. Only the field **name** is trimmed (KDCLI-106).
+
+### Changed
+- Unsupported custom-field errors now name both identifiers and the cause. Before: `Error: Unsupported field type 'X' for field 'Y'`. Now: `Error: Unsupported custom field type 'X' with subtype 'Y' for field 'Z'. kd does not know how to build a safe value payload for this YouTrack field family.` Applies to YouTrack text fields, multi-arity enum/user variants, and integer/float/date simple-field subtypes — paste the message into a bug report and the two type identifiers are already there (KDCLI-106).
+
 ## [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.

{kd_cli-2.5.0 → kd_cli-2.5.2}/kd/resources/operating-guide.md

@@ -108,6 +108,8 @@ 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.
 
+`--field` supports bundle families (enum, state, owned, version, build), user fields, period, and string `SimpleProjectCustomField` subtypes; whitespace inside the value is preserved. Unsupported families (text, `Multi*` enum/user variants, and `SimpleProjectCustomField` with `integer` / `float` / `date` subtypes) fail client-side with a message naming both the project `$type` and the `fieldType.id` subtype so a follow-on bug report can skip the probe.
+
 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.
@@ -156,6 +158,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.
 
+For one-way migrations where the local file will be deleted after the push, pass `--no-marker-write`. The server article is still created or updated and tags are still applied, but kd skips the local `kd-meta` rewrite so `git rm` works without `-f`. The structured response gains `marker_written: false`; re-running `--no-marker-write` pays the scan-by-slug cost every invocation because no `upstream-id` is cached locally.
+
 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`.

{kd_cli-2.5.0 → kd_cli-2.5.2/kd_cli.egg-info}/PKG-INFO

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

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

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