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

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

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

{kd_cli-2.6.5 → kd_cli-2.6.6}/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.6.6}/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 "