kd-cli 2.6.6__tar.gz → 2.7.1__tar.gz

{kd_cli-2.6.6/kd_cli.egg-info → kd_cli-2.7.1}/PKG-INFO

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

{kd_cli-2.6.6 → kd_cli-2.7.1}/kd/api/articles.py

@@ -1,12 +1,16 @@
 """Articles REST API wrapper.
 
 Covers ``/api/articles`` endpoints:
-- Articles: list (global + project-scoped), get, create, update, delete
+- Articles: list (global + project-scoped), search, get, create, update, delete
 - Child articles: list, attach, detach parent
 - Comments: list, create
 - Attachments: list, get, create, delete
 
-Articles have no ``query`` parameter — filtering is project-scoped only.
+The ``query`` parameter on ``/api/articles`` is undocumented in the
+public REST reference but probed-and-supported on the YT tiers kd
+targets (current cloud + on-prem 2023.2); ``search_articles`` is the
+canonical full-text path. Servers that reject it surface as a 400 with
+"unknown parameter" wording, classified at the SDK boundary.
 """
 
 from __future__ import annotations
@@ -103,6 +107,16 @@ class ArticlesAPI:
         )
         return [Article.model_validate(a) for a in data]
 
+    # --- Search ---
+
+    def search_articles(self, query: str, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            "/articles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"query": query, "$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
     # --- Tag scan (articles with tags for client-side filtering) ---
 
     def list_articles_with_tags(self, top: int = 50, skip: int = 0) -> list[Article]:

{kd_cli-2.6.6 → kd_cli-2.7.1}/kd/cli/namespaces/article/__init__.py

@@ -1,6 +1,6 @@
 """Article namespace: /article
 
-Commands: list, show, children, create, update, delete, tree, move
+Commands: list, search, show, pull, push, children, create, update, delete, tree, move
 Sub-namespaces: /article/comment (list, add), /article/attachment (list, add, show, download, delete)
 API layer: YouTrack REST API (/api/articles)
 """
@@ -81,17 +81,19 @@ class ArticleListCommand(Command):
             requires_client=True,
             usage="kd /article list [--project P] [--parent ID] [--limit N]",
             long_description=(
-                "Articles do not support search queries. Use --project to filter "
-                "by project, or --parent ARTICLE_ID to list direct children of "
-                "another article. When --parent is given, --project is ignored "
-                "because child listing is already scoped to the parent's project."
+                "List articles structurally — by project (--project) or by "
+                "parent (--parent ARTICLE_ID). For full-text / body / "
+                "field-bearing queries use `/article search`; this command "
+                "does not interpret query syntax. When --parent is given, "
+                "--project is ignored because child listing is already "
+                "scoped to the parent's project."
             ),
             examples=[
                 "kd /article list --project FB",
                 "kd /article list --project FB --limit 10",
                 "kd /article list --parent FB-A-1",
             ],
-            see_also=["/article show", "/article children"],
+            see_also=["/article show", "/article children", "/article search"],
         )
 
     def _register_options(self) -> None:
@@ -118,6 +120,57 @@ class ArticleListCommand(Command):
         return [_article_to_row(a) for a in articles]
 
 
+class ArticleSearchCommand(Command):
+    """Server-side article full-text search via the YT article query DSL."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "search",
+            "Search articles by full-text query",
+            requires_client=True,
+            usage="kd /article search QUERY [--limit N] [--skip N]",
+            long_description=(
+                "Run a YouTrack article query against /api/articles?query=. "
+                "Matches body, summary, tags, and other YT-indexed fields; "
+                "results are server-side relevance-ranked. The upstream "
+                "query parameter is undocumented; servers that reject it "
+                "surface a specific capability error rather than silently "
+                "falling back to local substring search. See the article "
+                "search how-to for query syntax and field filters."
+            ),
+            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"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(limit_option())
+        self.register_option(
+            OptionDeclaration(
+                name="skip",
+                layer=OptionLayer.COMMAND,
+                type=int,
+                default=0,
+                help_text="Skip the first N results (pagination).",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        query = " ".join(args).strip()
+        if not query:
+            raise ValidationError("Usage: kd /article search QUERY")
+        limit = options.command.get("limit", 50)
+        skip = options.command.get("skip", 0)
+        articles = client.articles.search(query, top=limit, skip=skip)
+        return [_article_to_row(a) for a in articles]
+
+
 class ArticleShowCommand(Command):
     """Show article details."""
 
@@ -1058,6 +1111,7 @@ def create_article_namespace() -> Namespace:
     """Build the /article namespace."""
     ns = Namespace("article", "Knowledge base articles", path="article")
     ns.register_command("list", ArticleListCommand())
+    ns.register_command("search", ArticleSearchCommand())
     ns.register_command("show", ArticleShowCommand())
     ns.register_command("pull", ArticlePullCommand())
     ns.register_command("push", ArticlePushCommand())

{kd_cli-2.6.6 → kd_cli-2.7.1}/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
@@ -1325,6 +1326,56 @@ def _splice_body(old_body: str, block: str, position: str) -> str:
     return combined
 
 
+_CAPABILITY_MISSING_MSG = (
+    "Article full-text search is not available on this YouTrack "
+    "instance. The REST article query parameter is undocumented and "
+    "this server rejected it. Use `/article list`, `/tag articles`, "
+    "or `/cache search` for local cached content."
+)
+
+
+def _is_unknown_query_param(exc: APIError) -> bool:
+    """Heuristic: did YT reject the ``query`` parameter as unknown?
+
+    YT versions that surface this path emit phrases like "unknown
+    parameter" or "unrecognized parameter" in the 400 body. Refined
+    once an instance that exhibits it surfaces during dogfooding;
+    until then the heuristic is intentionally loose.
+    """
+    body = (exc.response_body or "").lower()
+    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."""
 
@@ -1355,6 +1406,34 @@ class ArticleOperations:
             return self._articles.list_project_articles(project_obj.id, top=top, skip=skip)
         return self._articles.list_articles(top=top, skip=skip)
 
+    def search(
+        self,
+        query: str,
+        top: int = 50,
+        skip: int = 0,
+    ) -> builtins.list[Article]:
+        """Server-side article full-text search via the YT article query
+        engine. Wraps ``/api/articles?query=`` (undocumented but supported
+        on current cloud + on-prem 2023.2). Server relevance order is
+        preserved — no client-side re-sort, no local-substring fallback.
+        """
+        self._debug.info("api", f"searching articles query={query!r}")
+        try:
+            return self._articles.search_articles(query, top=top, skip=skip)
+        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
+
     def get(self, article_id: str) -> Article:
         return self._articles.get_article(article_id)
 

{kd_cli-2.6.6 → kd_cli-2.7.1}/kd/resources/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [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
+articles. Until now `/article list --project P` was the only way to
+find articles without knowing their id; body and field queries
+required a manual scan. `kd /article search QUERY` closes that gap
+with relevance ranking.
+
+### Added
+- `kd /article search QUERY [--limit N] [--skip N]` and
+  `client.articles.search()` — server-backed article full-text search
+  via the YouTrack article query DSL (same syntax family as issue
+  search; supports `project: {…}`, `content:`, `summary:`, `tag:`,
+  `comments:`, etc., relevance-ranked by YouTrack). Output columns
+  match `/article list`. The upstream REST `query` parameter is
+  undocumented but supported on YouTrack cloud and on-prem 2023.2;
+  instances that reject it surface a specific capability error
+  rather than silently falling back to local substring matching, so
+  scripts cannot accidentally trade ranked server results for
+  unranked summary scans (KDCLI-183).
+
 ## [2.6.6] — 2026-05-01
 
 This release adds pinned issues as a first-class primer section

{kd_cli-2.6.6 → kd_cli-2.7.1}/kd/resources/operating-guide.md

@@ -76,9 +76,9 @@ Not every read has the same cost.
 
 **Direct reads** fetch one entity or one server-side page. Examples: `/issue show`, `/article show`, `/project show`, `/tag show`, `/query show`.
 
-**Query-backed reads** rely on an upstream query or filter. Examples: `/issue list --query`, `/query issues`, `/tag issues`, `/tag list --prefix`, `/tag list --namespace`. They are usually cheap but still depend on YouTrack query semantics.
+**Query-backed reads** rely on an upstream query or filter. Examples: `/issue list --query`, `/query issues`, `/tag issues`, `/tag list --prefix`, `/tag list --namespace`, `/article search`. They are usually cheap but still depend on YouTrack query semantics.
 
-**Scan-backed reads** walk pages and filter client-side because YouTrack has no matching endpoint. Examples: `/tag articles`, the article half of `/tag entities`, article substring search in `/search`, and deep `/article tree` traversal. Use limits and project scoping.
+**Scan-backed reads** walk pages and filter client-side because YouTrack has no matching endpoint. Examples: `/tag articles`, the article half of `/tag entities`, the article half of `/search --types article` (client-side substring), and deep `/article tree` traversal. Use limits and project scoping.
 
 Write-side commands do not prompt for confirmation unless their help says so. Pair destructive or broad operations with a read first:
 
@@ -108,11 +108,11 @@ The cache namespace (`kd /cache refresh|status|search|clear`) is read-side by co
 
 ## YouTrack Gotchas
 
-YouTrack articles are not queryable like issues. `/api/articles` has no issue-style `query` parameter, and there is no server-side article-by-tag endpoint. kd article tag lookup scans article pages that include `tags(id,name)` and filters locally.
+YouTrack's article query API is undocumented but supported on the YT tiers kd targets (cloud + on-prem 2023.2). `kd /article search QUERY` calls `GET /api/articles?query=…` and returns relevance-ranked results matching across body, summary, tags, and comments. Instances that reject the parameter surface a specific capability error rather than falling back silently. Server-side article-by-tag is still missing — `/tag articles` scans article pages that include `tags(id,name)` and filters locally.
 
 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.
 
@@ -357,4 +357,4 @@ Use these sources together:
 - `docs/design/architecture.md` and ADRs for architectural constraints.
 
 ---
-Updated: 2026-04-26
+Updated: 2026-05-02

{kd_cli-2.6.6 → kd_cli-2.7.1/kd_cli.egg-info}/PKG-INFO

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

{kd_cli-2.6.6 → kd_cli-2.7.1}/pyproject.toml

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