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

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

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

{kd_cli-2.1.6 → kd_cli-2.2.0}/kd/api/tags.py

@@ -36,6 +36,7 @@ _TAGGED_ISSUE_FIELDS = str(
         "id",
         "idReadable",
         "summary",
+        "updated",
         project=FieldSet("id", "name", "shortName"),
     )
 )
@@ -49,11 +50,20 @@ class TagsAPI:
 
     # --- Tag CRUD ---
 
-    def list_tags(self, top: int = 50, skip: int = 0) -> list[Tag]:
+    def list_tags(
+        self,
+        top: int = 50,
+        skip: int = 0,
+        *,
+        query: str | None = None,
+    ) -> list[Tag]:
+        params: dict[str, object] = {"$top": top, "$skip": skip}
+        if query is not None:
+            params["query"] = query
         data = self._http.get(
             "/tags",
             fields=_TAG_LIST_FIELDS,
-            params={"$top": top, "$skip": skip},
+            params=params,
         )
         return [Tag.model_validate(t) for t in data]
 

{kd_cli-2.1.6 → kd_cli-2.2.0}/kd/api/youtrack.py

@@ -68,11 +68,29 @@ _ISSUE_FIELDS = str(
         "summary",
         "description",
         "created",
+        "updated",
         project=FieldSet("id", "name", "shortName"),
         reporter=FieldSet("id", "login", "name"),
         customFields=FieldSet("name", value=FieldSet("name")),
     )
 )
+# Tag-aware list field set. Kept separate from _ISSUE_FIELDS so default
+# /issue list calls don't pay the tag payload cost. Symmetric to
+# _ARTICLE_TAG_SCAN_FIELDS in kd/api/articles.py.
+_ISSUE_LIST_FIELDS_WITH_TAGS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "description",
+        "created",
+        "updated",
+        project=FieldSet("id", "name", "shortName"),
+        reporter=FieldSet("id", "login", "name"),
+        customFields=FieldSet("name", value=FieldSet("name")),
+        tags=FieldSet("id", "name"),
+    )
+)
 _ISSUE_RICH_FIELDS = str(
     FieldSet(
         "id",
@@ -80,6 +98,7 @@ _ISSUE_RICH_FIELDS = str(
         "summary",
         "description",
         "created",
+        "updated",
         project=FieldSet("id", "name", "shortName"),
         reporter=FieldSet("id", "login", "name"),
         customFields=FieldSet("name", value=FieldSet("name")),
@@ -93,6 +112,7 @@ _ISSUE_RICH_FIELDS = str(
         attachments=FieldSet(
             "id", "name", "size", "mimeType", "created", author=FieldSet("id", "login", "name")
         ),
+        tags=FieldSet("id", "name"),
     )
 )
 _COMMENT_FIELDS = "id,text,author(id,login,name),created,updated"
@@ -188,11 +208,14 @@ class YouTrackAPI:
 
     # --- Issues ---
 
-    def list_issues(self, query: str = "", top: int = 50, skip: int = 0) -> list[Issue]:
+    def list_issues(
+        self, query: str = "", top: int = 50, skip: int = 0, with_tags: bool = False
+    ) -> list[Issue]:
         params: dict[str, Any] = {"$top": top, "$skip": skip}
         if query:
             params["query"] = query
-        data = self._http.get("/issues", fields=_ISSUE_FIELDS, params=params)
+        fields = _ISSUE_LIST_FIELDS_WITH_TAGS if with_tags else _ISSUE_FIELDS
+        data = self._http.get("/issues", fields=fields, params=params)
         return [Issue.model_validate(i) for i in data]
 
     def get_issue(self, issue_id: str, rich: bool = False) -> Issue:

{kd_cli-2.1.6 → kd_cli-2.2.0}/kd/cli/namespaces/issue/__init__.py

@@ -30,19 +30,6 @@ from kd.models import Attachment, CustomField, Issue
 _SEMANTIC_SLOTS = ("type", "priority", "state")
 
 
-def _get_field_aliases(client: Any, project_key: str) -> dict[str, str]:
-    """Extract field aliases for a project from config."""
-    if not client or not hasattr(client, "config") or not client.config:
-        return {}
-    for source in (client.config.local_projects, client.config.global_projects):
-        proj_cfg = source.get(project_key)
-        if isinstance(proj_cfg, dict):
-            aliases = proj_cfg.get("field_aliases")
-            if isinstance(aliases, dict):
-                return {str(k): str(v) for k, v in aliases.items()}
-    return {}
-
-
 def _build_custom_fields(
     options: dict[str, Any],
     client: Any = None,
@@ -64,7 +51,7 @@ def _build_custom_fields(
 
     semantic_fields: list[CustomField] = []
     if slots and client and project_key:
-        aliases = _get_field_aliases(client, project_key)
+        aliases = client.config.field_aliases_for(project_key) if client.config else {}
         semantic_fields = client.issues.resolve_custom_fields(project_key, slots, aliases) or []
     elif slots:
         # Fallback: hardcoded defaults (no client available)
@@ -122,9 +109,15 @@ def _extract_semantic_field(issue: Issue, candidates: set[str]) -> str:
     return ""
 
 
-def _issue_to_row(issue: Issue) -> dict[str, Any]:
-    """Convert an Issue to a flat dict for table output."""
-    return {
+def _issue_to_row(issue: Issue, with_tags: bool = False) -> dict[str, Any]:
+    """Convert an Issue to a flat dict for table output.
+
+    When ``with_tags`` is True, a ``tags`` column is appended (comma-joined
+    tag names, parity with ``_article_to_detail``). Without the flag, the
+    column is omitted entirely so cheap ``/issue list`` calls don't surface
+    an empty column.
+    """
+    row: dict[str, Any] = {
         "id": issue.id_readable,
         "summary": issue.summary,
         "project": issue.project.name if issue.project else "",
@@ -132,6 +125,9 @@ def _issue_to_row(issue: Issue) -> dict[str, Any]:
         "priority": _extract_semantic_field(issue, _PRIORITY_NAMES),
         "state": _extract_semantic_field(issue, _STATE_NAMES),
     }
+    if with_tags:
+        row["tags"] = ", ".join(t.name for t in issue.tags)
+    return row
 
 
 _RICH_SECTIONS = {"description", "comments", "links", "attachments"}
@@ -151,6 +147,8 @@ def _issue_to_detail(issue: Issue, sections: set[str] | None = None) -> dict[str
         "project": issue.project.name if issue.project else "",
         "reporter": issue.reporter.name if issue.reporter else "",
         "created": issue.created,
+        "updated": issue.updated,
+        "tags": ", ".join(t.name for t in issue.tags),
     }
     for cf in issue.custom_fields:
         name = cf.name.lower().replace(" ", "_")
@@ -215,13 +213,14 @@ class IssueListCommand(Command):
             "list",
             "List issues",
             requires_client=True,
-            usage="kd /issue list [--project P] [--query Q] [--limit N]",
+            usage="kd /issue list [--project P] [--query Q] [--limit N] [--with-tags]",
             examples=[
                 "kd /issue list --project FB",
                 'kd /issue list --query "State: Open"',
                 "kd /issue list --project FB --limit 10",
+                "kd /issue list --project FB --with-tags",
             ],
-            see_also=["/issue show", "/issue create"],
+            see_also=["/issue show", "/issue create", "/tag issues"],
         )
 
     def _register_options(self) -> None:
@@ -235,6 +234,15 @@ class IssueListCommand(Command):
             )
         )
         self.register_option(limit_option())
+        self.register_option(
+            OptionDeclaration(
+                name="with-tags",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Include tags in the response (opt-in; doubles payload size)",
+            )
+        )
 
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
@@ -248,8 +256,9 @@ class IssueListCommand(Command):
             parts.append(query)
         full_query = " ".join(parts)
         limit = options.command.get("limit", 50)
-        issues = client.issues.list(query=full_query, top=limit)
-        return [_issue_to_row(i) for i in issues]
+        with_tags = options.command.get("with-tags", False)
+        issues = client.issues.list(query=full_query, top=limit, with_tags=with_tags)
+        return [_issue_to_row(i, with_tags=with_tags) for i in issues]
 
 
 class IssueCreateCommand(Command):

{kd_cli-2.1.6 → kd_cli-2.2.0}/kd/cli/namespaces/primer/__init__.py

@@ -17,15 +17,19 @@ from kd.cli.core.option_registry import (
     project_option,
 )
 from kd.cli.input import resolve_text_input
-from kd.exceptions import ValidationError
+from kd.cli.output import emit_warning
+from kd.exceptions import KdError, NotFoundError, ValidationError
 from kd.primer import (
     add_article,
     add_note,
+    add_tag,
     clear_articles,
     clear_notes,
+    clear_tags,
     load_primer,
     remove_article,
     remove_note,
+    remove_tag,
     update_note,
 )
 
@@ -33,19 +37,33 @@ from kd.primer import (
 def _assert_workspace_project(command: Command, options: ResolvedOptions) -> None:
     """Enforce the ``--project`` assertion on workspace-scoped primer commands.
 
-    The primer lives in ``.kd/primer.yaml`` and has no project dimension.
-    ``--project`` is accepted as an assertion of which workspace's primer the
-    caller thinks it's editing: matches ``default_project`` → silent no-op;
-    mismatches → raise so an agent running from the wrong workspace fails loud.
+    The primer lives in ``.kd/primer.yaml`` and has no project dimension:
+    every workspace owns exactly one primer, and any entity (tag, article,
+    issue) from any project the token can see can be pinned from that
+    workspace.  ``--project`` is therefore accepted as an **assertion** of
+    which workspace's primer the caller thinks it's editing, not an
+    override that selects a different primer file.  Matches
+    ``default_project`` → silent no-op; mismatches → raise so an agent
+    running from the wrong workspace fails loud.
     """
     asserted = options.command.get("project")
     if not asserted:
         return
+    # Read commands (/primer show, /primer/*/list) declare the flag for
+    # symmetry with write commands but do not declare requires_config=True
+    # so they work in a fresh workspace before `kd init`.  When no config
+    # is loaded the assertion silently passes — the flag is accepted, the
+    # user sees no "unknown option" rejection (KDCLI-84 symptom).
+    if command._resolved_config is None:
+        return
     current = command.config.default_project
     if current and asserted != current:
         raise ValidationError(
-            f"Primer is workspace-scoped. --project={asserted} does not match "
-            f"this workspace's default_project={current}. To edit {asserted}'s "
+            f"Primer is workspace-scoped (one .kd/primer.yaml per workspace). "
+            f"--project={asserted} does not match this workspace's "
+            f"default_project={current}. Primer pinning does not restrict "
+            f"which project an entity can belong to — you can pin {asserted} "
+            f"entities from this workspace.  To edit a *different* workspace's "
             f"primer, run from that workspace."
         )
 
@@ -63,22 +81,28 @@ class PrimerShowCommand(Command):
             "show",
             "Show project primer",
             usage="kd /primer show",
-            long_description="Displays the full project primer — notes, pinned articles, "
-            "and all other sections.  Returns an empty primer if none exists yet.",
+            long_description="Displays the full project primer — notes, pinned tags, "
+            "pinned articles, and all other sections.  Returns an empty primer if "
+            "none exists yet.",
             examples=[
                 "kd /primer show",
                 "kd /primer show --output json",
             ],
-            see_also=["/primer/note list", "/primer/article list"],
+            see_also=["/primer/note list", "/primer/tag list", "/primer/article list"],
         )
         self.display_hint = "primer_show"
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this shows"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         data = load_primer()
         return {
             "notes": [{"#": i + 1, "note": n} for i, n in enumerate(data.notes)],
+            "tags": [{"name": t.name, "summary": t.summary or ""} for t in data.tags],
             "articles": [{"id": a.id, "summary": a.summary or ""} for a in data.articles],
         }
 
@@ -101,9 +125,13 @@ class PrimerNoteListCommand(Command):
             see_also=["/primer/note add", "/primer/note remove"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this reads"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         data = load_primer()
         return [{"index": i + 1, "note": note} for i, note in enumerate(data.notes)]
 
@@ -248,9 +276,13 @@ class PrimerArticleListCommand(Command):
             see_also=["/primer/article add", "/primer/article remove"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this reads"))
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
+        _assert_workspace_project(self, options)
         data = load_primer()
         return [{"id": a.id, "summary": a.summary or ""} for a in data.articles]
 
@@ -342,6 +374,153 @@ class PrimerArticleRemoveCommand(Command):
         return {"ok": True, "action": "remove", "id": removed.id}
 
 
+# ---------------------------------------------------------------------------
+# /primer/tag
+# ---------------------------------------------------------------------------
+
+
+class PrimerTagListCommand(Command):
+    """List pinned tags."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List pinned tags",
+            usage="kd /primer/tag list",
+            long_description="Lists all tags pinned in the project primer.  Pinned "
+            "tags act as the OR scope for `kd /tag entities --primer-scope`.",
+            examples=["kd /primer/tag list"],
+            see_also=["/primer/tag add", "/primer/tag remove", "/tag entities"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Assert which project's primer this reads"))
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        _assert_workspace_project(self, options)
+        data = load_primer()
+        return [{"name": t.name, "summary": t.summary or ""} for t in data.tags]
+
+
+class PrimerTagAddCommand(Command):
+    """Pin a tag to the primer."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Pin a tag to the primer",
+            requires_config=True,
+            requires_client=True,
+            usage="kd /primer/tag add TAG_NAME [--summary S]",
+            long_description="Adds a tag to the project primer.  Upstream existence "
+            "is validated via the tag namespace: tags not found upstream are still "
+            "written but return a `tag_not_found` warning — this supports declaring "
+            "tag intent before the tag is created.  A failed validation call "
+            "(network / auth / timeout) writes the entry with a "
+            "`tag_validation_skipped` warning so a local primer edit is not "
+            "silently blocked by an unreachable server.",
+            examples=[
+                "kd /primer/tag add kind:incident",
+                'kd /primer/tag add kind:incident --summary "Active incidents"',
+            ],
+            see_also=["/primer/tag list", "/primer/tag remove", "/tag entities"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="summary",
+                short_name="s",
+                layer=OptionLayer.COMMAND,
+                help_text="Description to store with the tag reference",
+            )
+        )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        _assert_workspace_project(self, options)
+        if not args:
+            raise ValidationError("Usage: kd /primer/tag add TAG_NAME")
+        name = args[0]
+        summary = options.command.get("summary")
+
+        warning: dict[str, Any] | None = None
+        try:
+            client.tags.get(name)
+        except NotFoundError as exc:
+            warning = emit_warning(
+                "tag_not_found",
+                f"Tag '{name}' not found upstream — pinning anyway (declare-intent).",
+                name=name,
+                detail=str(exc),
+            )
+        except KdError as exc:
+            warning = emit_warning(
+                "tag_validation_skipped",
+                f"Could not validate tag '{name}' upstream ({type(exc).__name__}) — "
+                "pinning the entry; verify the name when the upstream is reachable.",
+                name=name,
+                error_code=type(exc).__name__,
+                detail=str(exc),
+            )
+
+        tag = add_tag(name, summary=summary)
+        result: dict[str, Any] = {"ok": True, "action": "add", "name": tag.name}
+        if tag.summary:
+            result["summary"] = tag.summary
+        if warning is not None:
+            result["warnings"] = [warning]
+        return result
+
+
+class PrimerTagRemoveCommand(Command):
+    """Unpin a tag by name, or all tags with --all."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "remove",
+            "Unpin a tag or all tags",
+            requires_config=True,
+            usage="kd /primer/tag remove TAG_NAME | --all",
+            long_description="Removes the tag with the given name from the primer, "
+            "or all pinned tags if --all is passed.  Local-only edit — no upstream "
+            "call.",
+            examples=[
+                "kd /primer/tag remove kind:incident",
+                "kd /primer/tag remove --all",
+            ],
+            see_also=["/primer/tag list", "/primer/tag add"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="all",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Remove all pinned tags",
+            )
+        )
+        self.register_option(project_option(help_text="Assert which project's primer this edits"))
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        _assert_workspace_project(self, options)
+        if options.command.get("all"):
+            count = clear_tags()
+            return {"ok": True, "action": "clear", "removed": count}
+        if not args:
+            raise ValidationError("Usage: kd /primer/tag remove TAG_NAME | --all")
+        removed = remove_tag(args[0])
+        return {"ok": True, "action": "remove", "name": removed.name}
+
+
 # ---------------------------------------------------------------------------
 # Namespace factory
 # ---------------------------------------------------------------------------
@@ -364,6 +543,17 @@ def create_primer_namespace() -> Namespace:
     note_ns.register_command("update", PrimerNoteUpdateCommand())
     ns.register_sub_namespace(note_ns)
 
+    # /primer/tag
+    tag_ns = Namespace(
+        "tag",
+        "Pinned tag references",
+        path="primer/tag",
+    )
+    tag_ns.register_command("list", PrimerTagListCommand())
+    tag_ns.register_command("add", PrimerTagAddCommand())
+    tag_ns.register_command("remove", PrimerTagRemoveCommand())
+    ns.register_sub_namespace(tag_ns)
+
     # /primer/article
     article_ns = Namespace(
         "article",