kd-cli 2.7.0__tar.gz → 2.8.0__tar.gz

{kd_cli-2.7.0/kd_cli.egg-info → kd_cli-2.8.0}/PKG-INFO

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

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/api/youtrack.py

@@ -438,6 +438,9 @@ class YouTrackAPI:
         )
         return data
 
+    def delete_issue_link(self, issue_id: str, link_id: str, target_id: str) -> None:
+        self._http.delete(f"/issues/{issue_id}/links/{link_id}/issues/{target_id}")
+
     def apply_command(self, issue_id: str, command: str) -> None:
         """Apply a command to an issue via the commands API.
 

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/cli/namespaces/article/__init__.py

@@ -68,6 +68,35 @@ def _article_to_detail(article: Article) -> dict[str, Any]:
     return result
 
 
+def _apply_content_truncation(
+    detail: dict[str, Any],
+    *,
+    no_content: bool,
+    body_lines: int | None,
+) -> None:
+    """Mutate detail in place to apply --no-content / --body-lines truncation."""
+    content = detail.get("content")
+    if no_content:
+        chars = len(content) if isinstance(content, str) else 0
+        lines = len(content.splitlines()) if isinstance(content, str) else 0
+        detail.pop("content", None)
+        detail["content_truncated"] = True
+        detail["content_omitted"] = True
+        detail["content_chars"] = chars
+        detail["content_lines"] = lines
+        return
+    if body_lines is None or not isinstance(content, str):
+        return
+    parts = content.splitlines()
+    if len(parts) <= body_lines:
+        return
+    detail["content"] = "\n".join(parts[:body_lines])
+    detail["content_truncated"] = True
+    detail["content_chars"] = len(content)
+    detail["content_lines"] = len(parts)
+    detail["content_preview_lines"] = body_lines
+
+
 # --- Article Commands ---
 
 
@@ -141,6 +170,7 @@ class ArticleSearchCommand(Command):
             examples=[
                 'kd /article search "project: {Code OnTime} {wix}"',
                 'kd /article search "project: {Intellect Solutions} content: HKEY_LOCAL_MACHINE"',
+                'kd /article search "project: {COT} tag: {kind:proposal}"',
                 'kd /article search "summary: timeout" --limit 10',
             ],
             see_also=["/article list", "/search", "/tag articles"],
@@ -178,18 +208,79 @@ class ArticleShowCommand(Command):
             "show",
             "Show article details",
             requires_client=True,
-            usage="kd /article show ARTICLE_ID",
-            examples=["kd /article show FB-A-1"],
+            usage=("kd /article show ARTICLE_ID [--no-content | [--preview] [--body-lines N]]"),
+            long_description=(
+                "By default emits full metadata plus the rendered article body. "
+                "Pass --preview (sugar for --body-lines 40) or --body-lines N "
+                "to truncate the body to the first N lines; the structured "
+                "envelope gains content_truncated, content_chars, "
+                "content_lines, and content_preview_lines only when "
+                "truncation actually applies. Pass --no-content to omit the "
+                "body entirely; the envelope drops content and adds "
+                "content_omitted: true alongside content_chars and "
+                "content_lines. --no-content is mutually exclusive with "
+                "--body-lines and --preview. For the canonical raw body "
+                "(stdout, no envelope) use /article pull."
+            ),
+            examples=[
+                "kd /article show FB-A-1",
+                "kd /article show FB-A-1 --preview",
+                "kd /article show FB-A-1 --body-lines 10",
+                "kd /article show FB-A-1 --no-content -o yaml",
+            ],
             see_also=["/article list", "/article children", "/article pull"],
         )
 
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="no-content",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text=(
+                    "Omit the article body; emit metadata-only output with content_omitted: true"
+                ),
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="body-lines",
+                layer=OptionLayer.COMMAND,
+                type=int,
+                help_text=("Truncate the body to the first N lines; emit truncation metadata"),
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="preview",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Preview mode — sugar for --body-lines 40",
+            )
+        )
+
     def execute(
         self, args: list[str], options: ResolvedOptions, client: Any = None
     ) -> CommandResult:
         if not args:
             raise ValidationError("Usage: kd /article show ARTICLE_ID")
+        no_content = bool(options.command.get("no-content"))
+        raw_body_lines = options.command.get("body-lines")
+        preview = bool(options.command.get("preview"))
+        if no_content and (raw_body_lines is not None or preview):
+            raise ValidationError(
+                "--no-content is mutually exclusive with --body-lines and --preview"
+            )
+        if raw_body_lines is not None and raw_body_lines < 0:
+            raise ValidationError("--body-lines must be a non-negative integer")
+        body_lines = raw_body_lines if raw_body_lines is not None else (40 if preview else None)
         article = client.articles.get(args[0])
-        return _article_to_detail(article)
+        detail = _article_to_detail(article)
+        if no_content or body_lines is not None:
+            _apply_content_truncation(detail, no_content=no_content, body_lines=body_lines)
+        return detail
 
 
 class ArticlePullCommand(Command):

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/cli/namespaces/issue/__init__.py

@@ -716,11 +716,13 @@ class LinkListCommand(Command):
         links = client.issues.list_links(args[0])
         rows: list[dict[str, Any]] = []
         for link in links:
+            link_id = link.get("id", "")
             link_type = link.get("linkType", {}).get("name", "")
             direction = link.get("direction", "")
             for issue in link.get("issues", []):
                 rows.append(
                     {
+                        "id": link_id,
                         "type": link_type,
                         "direction": direction,
                         "issue": issue.get("idReadable", ""),
@@ -772,6 +774,73 @@ class LinkAddCommand(Command):
         }
 
 
+class LinkRemoveCommand(Command):
+    """Remove a link between two issues."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "remove",
+            "Remove a link between two issues",
+            requires_client=True,
+            usage="kd /issue/link remove ID TYPE TARGET | kd /issue/link remove ID --by-id LINK_ID",
+            long_description=(
+                "TYPE is one of: subtask-of, parent-for, depends-on, "
+                "required-for, duplicates, duplicated-by, relates-to. "
+                "Pass --by-id LINK_ID to disambiguate when the type+target "
+                "form is ambiguous; LINK_ID is the value surfaced in the "
+                "'id' column of `kd /issue/link list`. Returns a parseable "
+                "single-line ack: the last stdout line is "
+                "``ok: <ID> unlinked type=<TYPE> target=<TARGET>`` or "
+                "``ok: <ID> unlinked link_id=<LINK_ID>``. Pass --quiet to "
+                "suppress the detail block above the ack."
+            ),
+            examples=[
+                "kd /issue/link remove FB-42 subtask-of FB-1",
+                "kd /issue/link remove FB-42 --by-id 80-2s",
+            ],
+            see_also=["/issue/link add", "/issue/link list"],
+        )
+        self.display_hint = "mutation"
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="by-id",
+                layer=OptionLayer.COMMAND,
+                help_text="Remove the link with the given YT-internal link id (from `link list`)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        link_id = options.command.get("by-id")
+        if link_id:
+            if len(args) != 1:
+                raise ValidationError("Usage: kd /issue/link remove ID --by-id LINK_ID")
+            issue_id = args[0]
+            client.issues.unlink_by_id(issue_id, link_id)
+            return {
+                "ok": True,
+                "action": "unlinked",
+                "id": issue_id,
+                "link_id": link_id,
+            }
+        if len(args) != 3:
+            raise ValidationError("Usage: kd /issue/link remove ID TYPE TARGET")
+        issue_id = args[0]
+        link_type = args[1]
+        target_id = args[2]
+        client.issues.unlink(issue_id, link_type, target_id)
+        return {
+            "ok": True,
+            "action": "unlinked",
+            "id": issue_id,
+            "type": link_type,
+            "target": target_id,
+        }
+
+
 # --- Assign / Unassign / Move ---
 
 
@@ -1282,6 +1351,7 @@ def create_issue_namespace() -> Namespace:
     link_ns = Namespace("link", "Issue links", path="issue/link")
     link_ns.register_command("list", LinkListCommand())
     link_ns.register_command("add", LinkAddCommand())
+    link_ns.register_command("remove", LinkRemoveCommand())
     ns.register_sub_namespace(link_ns)
 
     attachment_ns = Namespace("attachment", "Issue attachments", path="issue/attachment")

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/cli/output.py

@@ -25,7 +25,6 @@ import yaml
 from tabulate import tabulate
 
 from kd.cli.core.command_base import CommandResult
-from kd.cli.tree import TreeNode, render_tree
 
 # Fields whose int values are Unix-epoch milliseconds.
 TIMESTAMP_FIELDS = frozenset({"created", "updated", "resolved"})
@@ -399,32 +398,31 @@ class OutputFormatter:
 
     @staticmethod
     def _render_tree_display(data: dict[str, Any]) -> str:
-        """Render nested tree dict as pretty box-drawing output."""
+        """Render nested tree dict as pretty box-drawing output.
 
-        def _to_node(d: dict[str, Any]) -> TreeNode:
-            return TreeNode(
-                id=d.get("id", ""),
-                label=d.get("summary", d.get("id", "")),
-                has_children=bool(d.get("children")),
-            )
+        Walks ``data["children"]`` directly. Depth truncation is applied
+        upstream (e.g. by ``_collect_tree``); this renderer just walks the
+        shape it receives.
+        """
+
+        def _label(d: dict[str, Any]) -> str:
+            label = d.get("summary", d.get("id", ""))
+            return label if isinstance(label, str) else ""
 
-        def _fetch_children(node_id: str) -> list[TreeNode]:
-            # Walk the tree dict to find the node and return its children
-            children = _find_children(data, node_id)
-            return [_to_node(c) for c in children]
-
-        def _find_children(node: dict[str, Any], target_id: str) -> list[dict[str, Any]]:
-            kids: list[dict[str, Any]] = node.get("children", [])
-            if node.get("id") == target_id:
-                return kids
-            for child in kids:
-                result = _find_children(child, target_id)
-                if result is not None:
-                    return result
-            return []
-
-        root = _to_node(data)
-        return render_tree(root, _fetch_children)
+        lines: list[str] = [_label(data)]
+
+        def _walk(children: list[dict[str, Any]], prefix: str) -> None:
+            for i, child in enumerate(children):
+                is_last = i == len(children) - 1
+                connector = "└── " if is_last else "├── "
+                lines.append(f"{prefix}{connector}{_label(child)}")
+                grandchildren = child.get("children") or []
+                if grandchildren:
+                    extension = "    " if is_last else "│   "
+                    _walk(grandchildren, prefix + extension)
+
+        _walk(data.get("children") or [], "")
+        return "\n".join(lines)
 
     # ------------------------------------------------------------------
     # Tag entities rendering

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/client.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 
 import builtins
 import difflib
+import re
 import shlex
 from collections import OrderedDict
 from collections.abc import Callable
@@ -104,6 +105,22 @@ _LINK_TYPE_MAP: dict[str, str] = {
     "relates-to": "relates to",
 }
 
+# Maps user-friendly link type to the (linkType.name, source-side direction)
+# pair returned by GET /api/issues/{id}/links. Used by the unlink path to
+# locate the right link entry on the source issue. Direction follows the YT
+# spec table: when the user-friendly word matches sourceToTarget the
+# source-side direction is OUTWARD, when it matches targetToSource it is
+# INWARD; undirected types use BOTH.
+_LINK_TYPE_NAME_MAP: dict[str, tuple[str, str]] = {
+    "subtask-of": ("Subtask", "INWARD"),
+    "parent-for": ("Subtask", "OUTWARD"),
+    "depends-on": ("Depend", "INWARD"),
+    "required-for": ("Depend", "OUTWARD"),
+    "duplicates": ("Duplicate", "INWARD"),
+    "duplicated-by": ("Duplicate", "OUTWARD"),
+    "relates-to": ("Relates", "BOTH"),
+}
+
 
 def _issue_to_entity_ref(issue: Issue) -> EntityRef:
     """Build a cross-entity ``EntityRef`` row from an :class:`Issue`."""
@@ -959,6 +976,59 @@ class IssueOperations:
         command_str = _resolve_link_command(link_type)
         self._yt.apply_command(issue_id, f"{command_str} {target_id}")
 
+    def unlink(self, issue_id: str, link_type: str, target_id: str) -> None:
+        """Remove a link between two issues.
+
+        ``link_type`` is a user-friendly name like ``subtask-of``. Lists the
+        links on ``issue_id``, locates the entry matching the type/direction
+        pair from ``_LINK_TYPE_NAME_MAP`` whose target's ``idReadable``
+        equals ``target_id``, then issues the documented DELETE. The DELETE
+        URL requires the target's **internal** id (readable ids return 404
+        on the target slot — verified live on YouTrack 2025), so the
+        helper passes ``issue["id"]`` (internal) along with the source
+        readable id and the resolved linkID.
+        """
+        mapping = _LINK_TYPE_NAME_MAP.get(link_type.lower())
+        if mapping is None:
+            valid = ", ".join(sorted(_LINK_TYPE_NAME_MAP))
+            raise ValidationError(f"Unknown link type '{link_type}'. Valid types: {valid}")
+        type_name, direction = mapping
+        for link in self._yt.list_issue_links(issue_id):
+            if link.get("linkType", {}).get("name") != type_name:
+                continue
+            if link.get("direction") != direction:
+                continue
+            for issue in link.get("issues", []):
+                if issue.get("idReadable") == target_id:
+                    self._yt.delete_issue_link(issue_id, link["id"], issue["id"])
+                    return
+        raise NotFoundError(f"No {link_type} link from {issue_id} to {target_id}")
+
+    def unlink_by_id(self, issue_id: str, link_id: str) -> None:
+        """Remove a link by its YT-internal link id.
+
+        Lists links on ``issue_id``, finds the entry whose ``id`` equals
+        ``link_id``, and DELETEs the single target it points at. Raises
+        ``ValidationError`` when the matched link contains more than one
+        target (the operator must use ``unlink(issue_id, type, target)``
+        instead). Raises ``NotFoundError`` when no link with that id exists
+        on the issue. The DELETE uses the target's internal id (readable
+        ids 404 on the target slot — see :meth:`unlink`).
+        """
+        for link in self._yt.list_issue_links(issue_id):
+            if link.get("id") != link_id:
+                continue
+            issues = link.get("issues", [])
+            if len(issues) != 1:
+                raise ValidationError(
+                    f"Link {link_id} on {issue_id} has {len(issues)} targets; "
+                    "use 'kd /issue/link remove ID TYPE TARGET' to disambiguate"
+                )
+            target = issues[0]
+            self._yt.delete_issue_link(issue_id, link_id, target["id"])
+            return
+        raise NotFoundError(f"No link with id '{link_id}' on {issue_id}")
+
     def assign(self, issue_id: str, user_ref: str) -> User:
         """Assign an issue. Returns the resolved user.
 
@@ -1345,6 +1415,36 @@ def _is_unknown_query_param(exc: APIError) -> bool:
     return ("parameter" in body) and ("unknown" in body or "unrecognized" in body)
 
 
+_TAG_BARE_COLON_LITERAL_RE = re.compile(r"\btag\s*:\s*(?!\{)\S*:\S*")
+
+
+def _is_tag_literal_misparse(exc: APIError, query: str) -> bool:
+    """Heuristic: did YT's article query DSL parse a colon inside a
+    bare ``tag:`` literal as a field separator?
+
+    Two gates, both required:
+
+    1. The 400 body matches the observed phrasing — *"... isn't used
+       for the tag field"* or its non-curly variant.
+    2. The user's *input query* contains a ``tag:`` clause followed
+       by a non-brace token that itself contains a colon. Without
+       this the same upstream phrase fires for legitimate unknown-tag
+       errors (e.g. ``tag: NOPE``), where the brace-wrapping hint
+       would be misleading.
+
+    The regex is intentionally conservative — it does not understand
+    quoted strings or full YT-DSL grammar; that is what the M012
+    verbatim-passthrough contract trades away. False negatives prefer
+    the no-hint path (raw YT message still surfaces) over the noisy
+    false positive of suggesting braces when no colon was typed.
+    """
+    body = (exc.response_body or "").lower()
+    body_match = "isn't used for the tag field" in body or "is not used for the tag field" in body
+    if not body_match:
+        return False
+    return _TAG_BARE_COLON_LITERAL_RE.search(query) is not None
+
+
 class ArticleOperations:
     """High-level knowledge base article operations."""
 
@@ -1392,6 +1492,13 @@ class ArticleOperations:
         except APIError as exc:
             if exc.status_code == 400 and _is_unknown_query_param(exc):
                 raise ValidationError(_CAPABILITY_MISSING_MSG) from exc
+            if exc.status_code == 400 and _is_tag_literal_misparse(exc, query):
+                raise ValidationError(
+                    f"{exc}\n"
+                    "Hint: tag names with colons need brace wrapping in YouTrack "
+                    "query syntax — use `tag: {kind:proposal}`, not "
+                    "`tag: kind:proposal`. See `kd --guide` §YouTrack Gotchas."
+                ) from exc
             if exc.status_code == 400:
                 raise ValidationError(str(exc)) from exc
             raise

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/resources/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.8.0] — 2026-05-07
+
+### Added
+- `kd /issue/link remove ID TYPE TARGET` and
+  `kd /issue/link remove ID --by-id LINK_ID` close the gap that left
+  operators in the YouTrack web UI to detach issues. `kd /issue/link list`
+  now surfaces link ids so the `--by-id` form is usable end-to-end.
+  Removal uses the documented `DELETE /api/issues/{id}/links/{linkID}/issues/{targetID}`
+  path, not the commands API (KDCLI-190).
+- `kd /article show` gains `--preview` (first 40 lines), `--body-lines N`,
+  and `--no-content` for previewing or skipping the body on long articles.
+  Truncation lives in the CLI layer; the structured envelope adds
+  `content_truncated`, `content_chars`, `content_lines`, and
+  `content_preview_lines` only when truncation applies; `--no-content`
+  drops `content` and adds `content_omitted: true`. Default behaviour is
+  unchanged — full body, no new keys (KDCLI-188).
+
+### Fixed
+- `kd /article tree` now renders the full tree at every branching factor.
+  The table/markdown renderer previously expanded only the first sibling's
+  subtree at each level; structured output (`-o yaml` / `-o json`) was
+  unaffected (KDCLI-189).
+
+## [2.7.1] — 2026-05-02
+
+### Fixed
+- `kd /article search` now appends a brace-wrapping hint when YouTrack returns
+  the *"… isn't used for the tag field"* 400 caused by a bare colon-bearing
+  `tag:` literal (e.g. `tag: kind:proposal`). The upstream message stays
+  visible; kd points to the fix — `tag: {kind:proposal}` — and references
+  `kd --guide` §YouTrack Gotchas. Docs and `kd /article search --help` now
+  show the brace form (KDCLI-186).
+
 ## [2.7.0] — 2026-05-02
 
 This release adds server-backed full-text search for knowledge-base

{kd_cli-2.7.0 → kd_cli-2.8.0}/kd/resources/operating-guide.md

@@ -112,7 +112,7 @@ YouTrack's article query API is undocumented but supported on the YT tiers kd ta
 
 Saved queries are YouTrack issue-search objects. `/query issues` executes them directly. `/query articles` only translates supported `project:` and `tag:` fields into article scans; issue-specific fields such as state or assignee are rejected for articles.
 
-Tag names with colons or spaces need YouTrack query literal handling. `tag: type:case` is wrong; YouTrack reads `type` as the tag value and `case` as another field. Use `tag: {type:case}` in hand-written queries. kd command paths that compose tag queries use the shared literal helper.
+Tag names with colons or spaces need YouTrack query literal handling in both issue and article queries (the article query DSL is the same syntax family). `tag: type:case` is wrong; YouTrack reads `type` as the tag value and `case` as another field. Use `tag: {type:case}` in hand-written queries — for `/issue list --query` and `/article search` alike. kd command paths that compose tag queries use the shared literal helper; `/article search` preserves the YouTrack 400 and appends a brace-wrapping hint when a bare colon-bearing `tag:` literal trips the misparse.
 
 Repeated same-field clauses in YouTrack query syntax default to OR. `tag: A tag: B` matches either tag. kd multi-tag issue operations join tag clauses with explicit `and` when intersection is required.
 
@@ -200,7 +200,7 @@ Primer mutations are serialized per file through an advisory lock on `.kd/primer
 
 ## Articles And Push
 
-Use `/article show` for metadata plus rendered content. Use `/article pull` when you need raw article content on stdout; `pull` is format-agnostic and ignores `--output`.
+Use `/article show` for metadata plus rendered content. Pass `--preview` (sugar for `--body-lines 40`) or `--body-lines N` for an N-line head; the structured envelope gains `content_truncated`, `content_chars`, `content_lines`, and `content_preview_lines` only when truncation actually applies. Pass `--no-content` for metadata only (drops `content`, sets `content_omitted: true`). `--no-content` is mutually exclusive with `--body-lines`/`--preview`. Use `/article pull` when you need raw article content on stdout; `pull` is format-agnostic and ignores `--output`.
 
 `/article push` is an idempotent file-to-YouTrack workflow. The local file gains a `<!-- kd-meta ... -->` marker exactly once — on the first push that creates or resolves the upstream article (or to repair a stale `upstream-id`). Subsequent pushes do not modify the file. Commit the one-time marker insertion with the content; from there `git status` stays clean across pushes. The marker is identity (`slug` + `upstream-id`), not tool state.
 

{kd_cli-2.7.0 → kd_cli-2.8.0/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.7.0 → kd_cli-2.8.0}/pyproject.toml

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