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

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

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

{kd_cli-2.6.5 → kd_cli-2.7.0}/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.5 → kd_cli-2.7.0}/kd/cache.py

@@ -30,7 +30,14 @@ from kd.connection import ConnectionContext
 from kd.exceptions import APIError, ConfigError, ValidationError
 from kd.history import atomic_write_text
 from kd.models.tag_entities import TagEntitiesResult, tag_entities_result_to_dict
-from kd.primer import PRIMER_FILENAME, PrimerArticle, PrimerTag, load_primer, require_workspace_dir
+from kd.primer import (
+    PRIMER_FILENAME,
+    PrimerArticle,
+    PrimerIssue,
+    PrimerTag,
+    load_primer,
+    require_workspace_dir,
+)
 from kd.query_parser import youtrack_query_literal
 
 # Public surface: names imported by external callers (CLI, client) and the
@@ -90,6 +97,7 @@ __all__ = [
     "HydratedQuery",
     "HydratedQueryRun",
     "IssueRefreshReport",
+    "IssueScopeRefreshReport",
     "MilestoneRefreshReport",
     "QueryNameRefreshReport",
     "QueryRefreshReport",
@@ -285,11 +293,26 @@ class QueryRefreshReport:
     failed: list[FailedQuery]
 
 
+@dataclass
+class IssueScopeRefreshReport:
+    """Per-pinned-issue half of :class:`RefreshReport`.
+
+    Parallels :class:`ArticleRefreshReport`.  Reuses :class:`HydratedIssue`
+    and :class:`FailedIssue` from the single-issue refresh path, with the
+    same per-id isolation contract.
+    """
+
+    skipped_no_pinned: bool
+    hydrated: list[HydratedIssue]
+    failed: list[FailedIssue]
+
+
 @dataclass
 class RefreshReport:
     """Result of a single ``refresh_primer_scope`` invocation."""
 
     articles: ArticleRefreshReport
+    issues: IssueScopeRefreshReport
     queries: QueryRefreshReport
 
 
@@ -1881,6 +1904,57 @@ def _refresh_primer_articles(
     return ArticleRefreshReport(skipped_no_pinned=False, hydrated=hydrated, failed=failed)
 
 
+def _refresh_primer_issues(
+    client: Any,
+    pinned: list[PrimerIssue],
+    fetched_at: datetime,
+    cache_root: Path,
+) -> IssueScopeRefreshReport:
+    """Hydrate each pinned issue into ``cache_root/issues/``.
+
+    Mirrors :func:`_refresh_primer_articles`.  Per-id ``APIError`` (and
+    subclasses) are isolated into ``failed``; ``AuthError`` and
+    ``ConfigError`` propagate as command-level failures and abort the
+    run.  Issues are fetched with ``detail="rich"`` so the cache payload
+    matches the single-issue refresh shape (proposal-39 §Issue Cache
+    Shape); ``include_comments`` stays off — the primer-scope contract
+    is "what does the agent need to start work," not "full comment log."
+    """
+    if not pinned:
+        return IssueScopeRefreshReport(skipped_no_pinned=True, hydrated=[], failed=[])
+
+    hydrated: list[HydratedIssue] = []
+    failed: list[FailedIssue] = []
+    for entry in pinned:
+        try:
+            issue = client.issues.get(entry.id, detail="rich")
+            payload = _issue_to_cache_payload(
+                issue,
+                fetched_at=fetched_at,
+                include_comments=False,
+                command=PRIMER_SCOPE_REFRESH_COMMAND,
+                reason="primer pinned issue",
+            )
+            write_cached_issue(
+                issue.id_readable,
+                payload,
+                fetched_at=fetched_at,
+                cache_root=cache_root,
+            )
+            hydrated.append(
+                HydratedIssue(
+                    id=issue.id_readable,
+                    summary=issue.summary,
+                    upstream_updated=_ms_to_iso(issue.updated),
+                    path=_report_path(cache_root / ISSUES_DIRNAME / f"{issue.id_readable}.yaml"),
+                    comments_count=None,
+                )
+            )
+        except APIError as e:
+            failed.append(FailedIssue(id=entry.id, reason=f"{type(e).__name__}: {e}"))
+    return IssueScopeRefreshReport(skipped_no_pinned=False, hydrated=hydrated, failed=failed)
+
+
 def _refresh_primer_query(
     client: Any,
     pinned_tags: list[PrimerTag],
@@ -1962,17 +2036,23 @@ def refresh_primer_scope(
         root = connection_cache_dir(connection, workspace_dir.parent)
     when = fetched_at or datetime.now(timezone.utc)
 
-    if not primer.articles and not primer.tags:
+    if not primer.articles and not primer.tags and not primer.issues:
         raise ValidationError(
-            "--primer-scope set but .kd/primer.yaml has no pinned articles or tags. "
-            "Pin a tag with: kd /primer/tag add TAG_NAME, or pin an article with: "
+            "--primer-scope set but .kd/primer.yaml has no pinned articles, tags, "
+            "or issues. Pin a tag with: kd /primer/tag add TAG_NAME, an issue "
+            "with: kd /primer/issue add ISSUE-ID, or an article with: "
             "kd /primer/article add ARTICLE-ID"
         )
 
     write_scope_manifest(connection, cache_root=root, fetched_at=when)
     article_report = _refresh_primer_articles(client, primer.articles, when, root)
+    issue_report = _refresh_primer_issues(client, primer.issues, when, root)
     query_report = _refresh_primer_query(client, primer.tags, when, root)
-    return RefreshReport(articles=article_report, queries=query_report)
+    return RefreshReport(
+        articles=article_report,
+        issues=issue_report,
+        queries=query_report,
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -2027,6 +2107,7 @@ def _issue_to_cache_payload(
     fetched_at: datetime,
     include_comments: bool,
     command: str,
+    reason: str = "single-entity refresh",
 ) -> dict[str, Any]:
     """Build the proposal-39 §Issue Cache Shape dict from an SDK ``Issue``.
 
@@ -2037,6 +2118,10 @@ def _issue_to_cache_payload(
     :func:`_project_key_from_id`. ``links`` and ``attachments`` are
     deliberately not projected (deferred to S7+).
 
+    ``reason`` defaults to ``"single-entity refresh"`` for the existing
+    single-issue refresh path; primer-scope refresh passes
+    ``"primer pinned issue"`` to record why the entry was hydrated.
+
     Not shared with ``kd/cli/namespaces/issue/__init__.py:_issue_to_detail``
     — that helper truncates comments to the last 5 (display logic),
     while cache projection must include all comments when
@@ -2053,7 +2138,7 @@ def _issue_to_cache_payload(
         "fetched_at": _format_iso(fetched_at),
         "source": {
             "command": command,
-            "reason": "single-entity refresh",
+            "reason": reason,
         },
     }
     for cf in issue.custom_fields:

{kd_cli-2.6.5 → kd_cli-2.7.0}/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,56 @@ 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 "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 +1110,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.5 → kd_cli-2.7.0}/kd/cli/namespaces/cache/__init__.py

@@ -131,8 +131,11 @@ class CacheRefreshCommand(Command):
                 "hydration verb — the cache is rehydratable upstream-"
                 "mirror data and no command silently reads through it. "
                 "Selectors are mutually exclusive: --primer-scope "
-                "hydrates primer-pinned articles plus the primer-scope "
-                "tag-entities query; --issue ID hydrates a single issue "
+                "hydrates primer-pinned articles, primer-pinned issues "
+                "(via the same single-issue projection at "
+                ".kd/cache/issues/<id>.yaml; comments not projected), "
+                "plus the primer-scope tag-entities query; --issue ID "
+                "hydrates a single issue "
                 "into .kd/cache/issues/<id>.yaml; --article ID hydrates "
                 "a single article; --query NAME runs a saved query and "
                 "writes the issue list to .kd/cache/queries/<slug>.yaml "