kd-cli 2.8.1__tar.gz → 2.9.1__tar.gz

{kd_cli-2.8.1/kd_cli.egg-info → kd_cli-2.9.1}/PKG-INFO

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

{kd_cli-2.8.1 → kd_cli-2.9.1}/kd/cli/namespaces/tag/__init__.py

@@ -138,8 +138,18 @@ class TagShowCommand(Command):
             "show",
             "Show tag details",
             requires_client=True,
-            usage="kd /tag show TAG_NAME",
-            examples=["kd /tag show sprint-47"],
+            usage="kd /tag show TAG_NAME_OR_ID",
+            long_description=(
+                "Accepts either a display name or the tag-id form "
+                "(NN-NN); the id form skips name resolution and is the "
+                "disambiguator when two visible tags share a name. A "
+                "name that resolves to multiple visible tags refuses "
+                "with a candidate list — pass the tag id to pick."
+            ),
+            examples=[
+                "kd /tag show sprint-47",
+                "kd /tag show 10-178",
+            ],
             see_also=["/tag list", "/tag issues"],
         )
 
@@ -162,13 +172,16 @@ class TagCreateCommand(Command):
             requires_client=True,
             usage="kd /tag create TAG_NAME",
             long_description=(
-                "Idempotent: if a tag with the requested name is already "
-                "visible, the command returns ``action: noop`` and does "
-                "not POST. Otherwise the tag is created with "
+                "Idempotent: if exactly one tag with the requested name "
+                "is already visible, the command returns ``action: noop`` "
+                "and does not POST. Otherwise the tag is created with "
                 "``action: created``. Returns a parseable single-line ack: "
                 "the last stdout line is ``ok: <NAME> created`` or "
                 "``ok: <NAME> noop``. Name resolution is case-insensitive "
-                "(same resolver /tag show uses). Pass --quiet to suppress "
+                "(same resolver /tag show uses). When the name collides "
+                "with multiple visible tags, create refuses with a "
+                "candidate list rather than picking one — inspect them "
+                "with ``kd /tag show <id>``. Pass --quiet to suppress "
                 "the detail block above the ack."
             ),
             examples=['kd /tag create "sprint-47"'],
@@ -206,17 +219,25 @@ class TagRenameCommand(Command):
             "rename",
             "Rename a tag",
             requires_client=True,
-            usage="kd /tag rename TAG_NAME NEW_NAME",
+            usage="kd /tag rename TAG_NAME_OR_ID NEW_NAME",
             long_description=(
                 "Returns a parseable single-line ack: the last stdout line "
                 "is ``ok: <NEW_NAME> renamed old_name=<TAG_NAME>``. The "
                 "tail-line ID is the **new name**, since scripts that "
                 "follow the rename refer to the tag by its new identity. "
                 "The previous name is preserved in ``old_name=`` so "
-                "audit/log consumers can correlate. Pass --quiet to "
-                "suppress the detail block above the ack."
+                "audit/log consumers can correlate. The first argument "
+                "accepts either a display name or the tag-id form "
+                "(NN-NN); the id form skips name resolution and is the "
+                "disambiguator when two visible tags share a name. A "
+                "name that resolves to multiple visible tags refuses "
+                "with a candidate list — pass the tag id to pick. Pass "
+                "--quiet to suppress the detail block above the ack."
             ),
-            examples=['kd /tag rename sprint-47 "sprint-48"'],
+            examples=[
+                'kd /tag rename sprint-47 "sprint-48"',
+                'kd /tag rename 10-178 "lifecycle:final"',
+            ],
             see_also=["/tag show"],
         )
         self.display_hint = "mutation"
@@ -244,15 +265,23 @@ class TagDeleteCommand(Command):
             "delete",
             "Delete a tag",
             requires_client=True,
-            usage="kd /tag delete TAG_NAME",
+            usage="kd /tag delete TAG_NAME_OR_ID",
             long_description=(
                 "Returns a parseable single-line ack: the last stdout line "
                 "is ``ok: <NAME> deleted``. --confirm is required and is "
                 "**not** softened by --quiet — the safety gate fires "
-                "before any envelope is rendered. Pass --quiet to suppress "
-                "the detail block above the ack."
+                "before any envelope is rendered. The argument accepts "
+                "either a display name or the tag-id form (NN-NN); the "
+                "id form skips name resolution and is the disambiguator "
+                "when two visible tags share a name. A name that "
+                "resolves to multiple visible tags refuses with a "
+                "candidate list — pass the tag id to pick. Pass "
+                "--quiet to suppress the detail block above the ack."
             ),
-            examples=["kd /tag delete sprint-47 --confirm"],
+            examples=[
+                "kd /tag delete sprint-47 --confirm",
+                "kd /tag delete 10-178 --confirm",
+            ],
             see_also=["/tag list", "/tag create"],
         )
         self.display_hint = "mutation"
@@ -298,13 +327,20 @@ class TagAddCommand(Command):
             "add",
             "Tag an issue or article",
             requires_client=True,
-            usage="kd /tag add ENTITY_ID TAG_NAME",
+            usage="kd /tag add ENTITY_ID TAG_NAME_OR_ID",
             long_description=(
-                "Entity type is auto-detected from the ID format: FB-123 = issue, FB-A-1 = article."
+                "Entity type is auto-detected from the ID format: FB-123 = "
+                "issue, FB-A-1 = article. The tag argument accepts either a "
+                "display name or the tag-id form (NN-NN); the id form skips "
+                "name resolution and is the disambiguator when two tags share "
+                "a name. Adding a name already attached to the entity is an "
+                "idempotent re-tag; adding a name that has multiple visible "
+                "tags refuses with a candidate list — pass the tag id to pick."
             ),
             examples=[
                 "kd /tag add FB-123 sprint-47",
                 "kd /tag add FB-A-1 reviewed",
+                "kd /tag add FB-A-1 10-178",
             ],
             see_also=["/tag remove", "/tag issues"],
         )
@@ -327,10 +363,15 @@ class TagRemoveCommand(Command):
             "remove",
             "Untag an issue or article",
             requires_client=True,
-            usage="kd /tag remove ENTITY_ID TAG_NAME",
+            usage="kd /tag remove ENTITY_ID TAG_NAME_OR_ID",
             long_description=(
                 "Entity type is auto-detected from the ID format: FB-123 = "
-                "issue, FB-A-1 = article. "
+                "issue, FB-A-1 = article. The tag argument is resolved "
+                "against the tags attached to the entity — names that are "
+                "not attached refuse loudly even when a same-name tag "
+                "exists globally. Pass the tag-id form (NN-NN) to skip name "
+                "resolution; this is the disambiguator when multiple "
+                "same-name tags are attached. "
                 "Returns a parseable single-line ack: the last stdout line "
                 "is ``ok: <ENTITY_ID> removed tag=<TAG_NAME>``. The "
                 "entity ID is the primary tail-line ID (``$2``); the "
@@ -340,6 +381,7 @@ class TagRemoveCommand(Command):
             examples=[
                 "kd /tag remove FB-123 sprint-47",
                 "kd /tag remove FB-A-1 reviewed",
+                "kd /tag remove FB-A-1 10-178",
             ],
             see_also=["/tag add", "/tag issues"],
         )
@@ -363,16 +405,26 @@ class TagIssuesCommand(Command):
             "issues",
             "List issues with a tag",
             requires_client=True,
-            usage="kd /tag issues TAG_NAME [--tag TAG ...] [--project P] [--limit N]",
+            usage="kd /tag issues TAG_NAME_OR_ID [--tag TAG ...] [--project P] [--limit N]",
             long_description=(
-                "Lists issues tagged with the given tag.  Single-tag uses the "
+                "Lists issues tagged with the given tag. Single-tag uses the "
                 "fast server-side tag-issues endpoint; multi-tag composes a "
                 "YouTrack query and uses /issues?query=... with AND semantics. "
                 "Use --project to scope results to a single project (forces "
-                "the composed-query path)."
+                "the composed-query path). The tag argument accepts either a "
+                "display name or the tag-id form (NN-NN) on the fast path "
+                "(single tag, no --project); the id form skips name "
+                "resolution and is the disambiguator when two visible tags "
+                "share a name. On the composed-query path (--project set or "
+                "multiple --tag arguments), the id form is rejected because "
+                "YouTrack's ``tag:`` predicate is name-keyed — use the name "
+                "form (which refuses on duplicate-name collision) or the "
+                "fast path. A name that resolves to multiple visible tags "
+                "refuses with a candidate list before the query is composed."
             ),
             examples=[
                 "kd /tag issues sprint-47",
+                "kd /tag issues 10-178",
                 "kd /tag issues blocked --limit 100",
                 "kd /tag issues kind:note --tag component:authservice",
                 "kd /tag issues kind:note --tag component:authservice --project KDCLI",
@@ -414,16 +466,22 @@ class TagArticlesCommand(Command):
             "articles",
             "List articles with a tag",
             requires_client=True,
-            usage="kd /tag articles TAG_NAME [--tag TAG ...] [--project P] [--limit N]",
+            usage="kd /tag articles TAG_NAME_OR_ID [--tag TAG ...] [--project P] [--limit N]",
             long_description=(
                 "Lists articles tagged with the given tag. Uses client-side "
                 "filtering because the YouTrack API has no server-side "
                 "article-by-tag endpoint. Use --project to scope the scan "
                 "to a single project. Repeat --tag to require multiple tags "
-                "(AND semantics)."
+                "(AND semantics). Every tag argument accepts either a "
+                "display name or the tag-id form (NN-NN); the id form "
+                "filters precisely by id and is the disambiguator when "
+                "two visible tags share a name. A name that resolves to "
+                "multiple visible tags refuses with a candidate list — "
+                "pass the tag id to pick."
             ),
             examples=[
                 "kd /tag articles reviewed",
+                "kd /tag articles 10-178",
                 'kd /tag articles "type:guide" --project FB',
                 "kd /tag articles type:case --tag component:authservice -p CMCSA",
                 "kd /tag articles blocked --limit 100",
@@ -484,10 +542,23 @@ class TagEntitiesCommand(Command):
                 "--limit-issues and --limit-articles override per kind.  "
                 "--primer-scope substitutes the primer's pinned tags as an "
                 "OR scope (match=any); mutually exclusive with the positional "
-                "TAG and --tag arguments."
+                "TAG and --tag arguments. "
+                "The tag argument accepts either a display name or the "
+                "tag-id form (NN-NN); the id form skips name resolution "
+                "and is the disambiguator when two visible tags share a "
+                "name. Id-form scope: allowed when the issue half routes "
+                "through the fast path (single tag, no --project) or when "
+                "only --kind article is requested (article filtering is "
+                "client-side by id). With --project or multiple tags AND "
+                "the issue kind included, id-form is rejected because "
+                "YouTrack's ``tag:`` predicate is name-keyed. Names are "
+                "pre-validated before the issue/article fanout — a "
+                "duplicate-name refusal is the whole-command outcome, not "
+                "a partial-success row."
             ),
             examples=[
                 "kd /tag entities kind:note",
+                "kd /tag entities 10-178",
                 "kd /tag entities kind:note --tag component:authservice --project KDCLI",
                 "kd /tag entities kind:note --kind article --limit-articles 5",
                 "kd /tag entities kind:note --limit 20 -o json",