kd-cli 2.6.1__tar.gz → 2.6.3__tar.gz

{kd_cli-2.6.1/kd_cli.egg-info → kd_cli-2.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.6.1
+Version: 2.6.3
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT
@@ -22,6 +22,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: filelock>=3.12
 Requires-Dist: httpx>=0.27
 Requires-Dist: packaging>=23.0
 Requires-Dist: pydantic>=2.0

{kd_cli-2.6.1 → kd_cli-2.6.3}/kd/api/youtrack.py

@@ -16,9 +16,11 @@ Uses HttpClient for transport and Pydantic models for serialization.
 
 from __future__ import annotations
 
+import re
 from typing import Any
 
 from kd.api.http import HttpClient
+from kd.exceptions import KdError
 from kd.models import (
     AssistResponse,
     Attachment,
@@ -169,6 +171,24 @@ _PROJECT_CUSTOM_FIELDS_PARAM = (
     "canBeEmpty,emptyFieldText"
     ")"
 )
+# Per-issue projection that surfaces the same projectCustomField shape
+# /admin/projects/{id} returns, but readable by any token with Read Issue.
+# See KDCLI-A-22 for the YouTrack permission-tier rationale.
+_PROJECT_FIELD_VIA_ISSUE_PARAM = (
+    "id,idReadable,"
+    "customFields("
+    "projectCustomField("
+    "field(name,fieldType(id)),"
+    "$type,"
+    "bundle(values(name,ordinal,isResolved)),"
+    "canBeEmpty,emptyFieldText"
+    ")"
+    ")"
+)
+# YouTrack internal-id format: "<entity-class>-<seq>", e.g. "0-9". Project
+# short-names (KDCLI, VTX, FB) are alphabetic and never match this shape,
+# so a regex match is a reliable "this is an id, not a key" signal.
+_PROJECT_INTERNAL_ID_RE = re.compile(r"\d+-\d+")
 
 
 class YouTrackAPI:
@@ -203,13 +223,76 @@ class YouTrackAPI:
         self._http.delete(f"/admin/projects/{project_id}")
 
     def list_project_custom_fields(self, project_id: str) -> list[dict[str, Any]]:
-        """Fetch custom fields for a project with bundle values."""
-        data: dict[str, Any] = self._http.get(
+        """Fetch a project's custom-field schema (name, type, bundle values).
+
+        Queries the per-issue ``projectCustomField`` projection so the call
+        works for any token with Read Issue, not just project admins. Falls
+        back to ``/admin/projects/{id}`` only when the project has no
+        issues to sample from. See KDCLI-A-22 for the permission-tier
+        rationale.
+
+        Accepts either the project short-name ("KDCLI") or the internal id
+        ("0-9"); the search-query DSL needs the short-name, so internal
+        ids are resolved via a cheap shortName lookup that any contributor
+        token can make.
+        """
+        short_name = self._resolve_project_short_name(project_id)
+        issues: list[dict[str, Any]] = self._http.get(
+            "/issues",
+            fields=_PROJECT_FIELD_VIA_ISSUE_PARAM,
+            params={"query": f"project: {short_name}", "$top": 1},
+        )
+        if issues:
+            sample = issues[0]
+            return [
+                cf["projectCustomField"]
+                for cf in sample.get("customFields") or []
+                if cf.get("projectCustomField")
+            ]
+
+        admin: dict[str, Any] = self._http.get(
             f"/admin/projects/{project_id}",
             fields=_PROJECT_CUSTOM_FIELDS_PARAM,
         )
-        result: list[dict[str, Any]] = data.get("customFields", [])
-        return result
+        admin_fields: list[dict[str, Any]] = admin.get("customFields") or []
+        if admin_fields:
+            return admin_fields
+        raise KdError(
+            f"No custom fields discovered for project '{project_id}'.",
+            suggestion=(
+                "Either the project has no issues to sample from, or the "
+                "active token lacks Read Project Full on this project. "
+                "Create one issue (any contributor token works), or use a "
+                "token with project-administration rights. See KDCLI-A-22."
+            ),
+        )
+
+    def _resolve_project_short_name(self, project_id: str) -> str:
+        """Return a project short-name (key) usable in a YouTrack query.
+
+        Pass-through if ``project_id`` already looks like a key. If it
+        looks like an internal id (``\\d+-\\d+``), look up the short-name
+        via ``GET /admin/projects/{id}?fields=shortName`` — that endpoint
+        is readable by any token with Read Project Basic, so it works
+        for contributor tokens.
+        """
+        if not _PROJECT_INTERNAL_ID_RE.fullmatch(project_id):
+            return project_id
+        meta: dict[str, Any] = self._http.get(
+            f"/admin/projects/{project_id}",
+            fields="shortName",
+        )
+        short_name = meta.get("shortName")
+        if not short_name:
+            raise KdError(
+                f"Could not resolve project '{project_id}' to a short name.",
+                suggestion=(
+                    "Verify the project exists and the active token has "
+                    "Read Project Basic. Try `kd /project list` to see "
+                    "projects this token can read."
+                ),
+            )
+        return str(short_name)
 
     # --- Time Tracking ---
 

{kd_cli-2.6.1 → kd_cli-2.6.3}/kd/cache.py

@@ -21,7 +21,7 @@ import dataclasses
 import re
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
-from pathlib import Path
+from pathlib import Path, PurePath, PurePosixPath
 from typing import Any, Literal
 
 import yaml
@@ -597,6 +597,22 @@ class CacheScopeEnumeration:
 # ---------------------------------------------------------------------------
 
 
+def _report_path(value: Path | PurePath | str) -> str:
+    """Normalize a filesystem path to POSIX form for structured-report fields.
+
+    Single chokepoint for every path-bearing field on the cache report
+    dataclasses (``HydratedIssue.path``, ``HydratedArticle.path``,
+    ``EpicRefreshReport.manifest_path``, ``CacheStatusInfo.path``,
+    ``CacheSearchMatch.path`` and siblings). The structured envelope of
+    ``/cache refresh``, ``/cache clear``, ``/cache status``, and
+    ``/cache search`` uses ``/`` separators on Windows and POSIX alike so
+    LLM consumers see a platform-stable shape.
+    """
+    if isinstance(value, (Path, PurePath)):
+        return value.as_posix()
+    return PurePosixPath(value.replace("\\", "/")).as_posix()
+
+
 def cache_dir(start: Path | None = None) -> Path:
     """Return the cache directory inside the nearest ``.kd/`` workspace.
 
@@ -1133,19 +1149,19 @@ def _clear_subtree(directory: Path, errors: list[ClearReportError]) -> int:
                 _remove_file(entry)
                 removed += 1
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
         elif entry.is_dir():
             removed += _clear_subtree(entry, errors)
             try:
                 entry.rmdir()
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
         else:
             try:
                 _remove_file(entry)
                 removed += 1
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
     return removed
 
 
@@ -1183,25 +1199,25 @@ def clear_cache(*, cache_root: Path | None = None) -> ClearReport:
                 _remove_file(entry)
                 counts["other"] += 1
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
         elif entry.is_dir():
             kind = _classify(entry.name)
             counts[kind] += _clear_subtree(entry, errors)
             try:
                 entry.rmdir()
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
         else:
             try:
                 _remove_file(entry)
                 counts["other"] += 1
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
 
     try:
         target.rmdir()
     except OSError as e:
-        errors.append(ClearReportError(path=str(target), reason=str(e)))
+        errors.append(ClearReportError(path=_report_path(target), reason=str(e)))
 
     return ClearReport(
         existed=True,
@@ -1244,7 +1260,7 @@ def clear_all_scopes(*, cache_root: Path | None = None) -> ClearReport:
         try:
             entry.rmdir()
         except OSError as e:
-            errors.append(ClearReportError(path=str(entry), reason=str(e)))
+            errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
 
     for entry in sorted(target.iterdir()):
         if entry.is_symlink():
@@ -1252,7 +1268,7 @@ def clear_all_scopes(*, cache_root: Path | None = None) -> ClearReport:
                 _remove_file(entry)
                 counts["other"] += 1
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
         elif entry.is_dir():
             if entry.name == CONNECTIONS_DIRNAME:
                 for scope in sorted(entry.iterdir()):
@@ -1261,7 +1277,7 @@ def clear_all_scopes(*, cache_root: Path | None = None) -> ClearReport:
                             _remove_file(scope)
                             counts["other"] += 1
                         except OSError as e:
-                            errors.append(ClearReportError(path=str(scope), reason=str(e)))
+                            errors.append(ClearReportError(path=_report_path(scope), reason=str(e)))
                     elif scope.is_dir():
                         for inner in sorted(scope.iterdir()):
                             if inner.is_dir():
@@ -1271,21 +1287,23 @@ def clear_all_scopes(*, cache_root: Path | None = None) -> ClearReport:
                                     _remove_file(inner)
                                     counts["other"] += 1
                                 except OSError as e:
-                                    errors.append(ClearReportError(path=str(inner), reason=str(e)))
+                                    errors.append(
+                                        ClearReportError(path=_report_path(inner), reason=str(e))
+                                    )
                         try:
                             scope.rmdir()
                         except OSError as e:
-                            errors.append(ClearReportError(path=str(scope), reason=str(e)))
+                            errors.append(ClearReportError(path=_report_path(scope), reason=str(e)))
                     else:
                         try:
                             _remove_file(scope)
                             counts["other"] += 1
                         except OSError as e:
-                            errors.append(ClearReportError(path=str(scope), reason=str(e)))
+                            errors.append(ClearReportError(path=_report_path(scope), reason=str(e)))
                 try:
                     entry.rmdir()
                 except OSError as e:
-                    errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                    errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
             else:
                 _tally_kind_subdir(entry)
         else:
@@ -1293,12 +1311,12 @@ def clear_all_scopes(*, cache_root: Path | None = None) -> ClearReport:
                 _remove_file(entry)
                 counts["other"] += 1
             except OSError as e:
-                errors.append(ClearReportError(path=str(entry), reason=str(e)))
+                errors.append(ClearReportError(path=_report_path(entry), reason=str(e)))
 
     try:
         target.rmdir()
     except OSError as e:
-        errors.append(ClearReportError(path=str(target), reason=str(e)))
+        errors.append(ClearReportError(path=_report_path(target), reason=str(e)))
 
     return ClearReport(
         existed=True,
@@ -1405,7 +1423,7 @@ def enumerate_cache_scopes(cache_root: Path | None = None) -> CacheScopeEnumerat
         # a logic error, not user-recoverable state.
         assert data is not None
         manifest = _validate_scope_manifest_schema(data, manifest_path)
-        scopes.append(CacheScopeRef(slug=entry.name, path=str(entry), manifest=manifest))
+        scopes.append(CacheScopeRef(slug=entry.name, path=_report_path(entry), manifest=manifest))
 
     return CacheScopeEnumeration(scopes=scopes, orphan_dirs=orphans)
 
@@ -1459,7 +1477,7 @@ def _scan_articles_dir(
             CacheStatusWarning(
                 code="article_pair_mismatch",
                 message=f"article body without sidecar: {article_id}.md",
-                path=str(bodies[article_id]),
+                path=_report_path(bodies[article_id]),
             )
         )
     for article_id in sorted(only_sidecar):
@@ -1467,7 +1485,7 @@ def _scan_articles_dir(
             CacheStatusWarning(
                 code="article_pair_mismatch",
                 message=f"article sidecar without body: {article_id}.meta.yaml",
-                path=str(sidecars[article_id]),
+                path=_report_path(sidecars[article_id]),
             )
         )
 
@@ -1483,7 +1501,7 @@ def _scan_articles_dir(
                 CacheStatusWarning(
                     code="sidecar_unparseable",
                     message=f"unable to parse fetched_at from {sidecar_path.name}: {exc}",
-                    path=str(sidecar_path),
+                    path=_report_path(sidecar_path),
                 )
             )
             continue
@@ -1522,7 +1540,7 @@ def _scan_yaml_kind_dir(
                 CacheStatusWarning(
                     code=code,
                     message=f"unable to parse banner from {path.name}: {exc}",
-                    path=str(path),
+                    path=_report_path(path),
                 )
             )
             continue
@@ -1701,7 +1719,7 @@ def compute_cache_status(
     when = now if now is not None else datetime.now(timezone.utc)
     target = cache_dir() if cache_root is None else Path(cache_root).resolve()
 
-    info_path = str(target)
+    info_path = _report_path(target)
     if not target.exists():
         return CacheStatusReport(
             cache=CacheStatusInfo(
@@ -1855,7 +1873,7 @@ def _refresh_primer_articles(
                     id=article.id_readable,
                     summary=article.summary,
                     upstream_updated=meta.upstream_updated,
-                    path=str(cache_root / ARTICLES_DIRNAME / f"{article.id_readable}.md"),
+                    path=_report_path(cache_root / ARTICLES_DIRNAME / f"{article.id_readable}.md"),
                 )
             )
         except APIError as e:
@@ -1906,7 +1924,7 @@ def _refresh_primer_query(
         hydrated=[
             HydratedQuery(
                 slug=PRIMER_SCOPE_QUERY_SLUG,
-                path=str(cache_root / QUERIES_DIRNAME / f"{PRIMER_SCOPE_QUERY_SLUG}.yaml"),
+                path=_report_path(cache_root / QUERIES_DIRNAME / f"{PRIMER_SCOPE_QUERY_SLUG}.yaml"),
                 issue_count=issue_count,
                 article_count=article_count,
             )
@@ -2102,7 +2120,7 @@ def refresh_issue(
                     id=issue.id_readable,
                     summary=issue.summary,
                     upstream_updated=_ms_to_iso(issue.updated),
-                    path=str(root / ISSUES_DIRNAME / f"{issue.id_readable}.yaml"),
+                    path=_report_path(root / ISSUES_DIRNAME / f"{issue.id_readable}.yaml"),
                     comments_count=comments_count,
                 )
             ],
@@ -2314,7 +2332,7 @@ def refresh_query(
                 query_name=sq.name,
                 query_id=sq.id,
                 slug=slug,
-                path=str(root / QUERIES_DIRNAME / f"{slug}.yaml"),
+                path=_report_path(root / QUERIES_DIRNAME / f"{slug}.yaml"),
                 count=len(issues),
                 truncated=truncated,
             )
@@ -2458,7 +2476,7 @@ def refresh_milestone(
                 field_name=actual_field_name,
                 query_text=query_text,
                 slug=slug,
-                path=str(root / QUERIES_DIRNAME / f"{slug}.yaml"),
+                path=_report_path(root / QUERIES_DIRNAME / f"{slug}.yaml"),
                 count=len(issues),
                 truncated=truncated,
             )
@@ -2616,7 +2634,7 @@ def refresh_epic_with_children(
         id=epic.id_readable,
         summary=epic.summary,
         upstream_updated=_ms_to_iso(epic.updated),
-        path=str(root / ISSUES_DIRNAME / f"{epic.id_readable}.yaml"),
+        path=_report_path(root / ISSUES_DIRNAME / f"{epic.id_readable}.yaml"),
         comments_count=None,
     )
 
@@ -2657,7 +2675,7 @@ def refresh_epic_with_children(
                     id=child.id_readable,
                     summary=child.summary,
                     upstream_updated=_ms_to_iso(child.updated),
-                    path=str(root / ISSUES_DIRNAME / f"{child.id_readable}.yaml"),
+                    path=_report_path(root / ISSUES_DIRNAME / f"{child.id_readable}.yaml"),
                     comments_count=None,
                 )
             )
@@ -2701,7 +2719,7 @@ def refresh_epic_with_children(
         "children": manifest_rows,
     }
     write_cached_query(slug, manifest_payload, fetched_at=when, cache_root=root)
-    manifest_path = str(root / QUERIES_DIRNAME / f"{slug}.yaml")
+    manifest_path = _report_path(root / QUERIES_DIRNAME / f"{slug}.yaml")
 
     return EpicRefreshReport(
         epic=epic_hydrated,
@@ -2754,7 +2772,7 @@ def refresh_article(
                     id=article.id_readable,
                     summary=article.summary,
                     upstream_updated=meta.upstream_updated,
-                    path=str(root / ARTICLES_DIRNAME / f"{article.id_readable}.md"),
+                    path=_report_path(root / ARTICLES_DIRNAME / f"{article.id_readable}.md"),
                 )
             ],
             failed=[],
@@ -2907,7 +2925,7 @@ def _search_article_dir(
                     CacheStatusWarning(
                         code="sidecar_unparseable",
                         message=f"unable to parse {sidecar_path.name}: {exc}",
-                        path=str(sidecar_path),
+                        path=_report_path(sidecar_path),
                     )
                 )
         try:
@@ -2917,7 +2935,7 @@ def _search_article_dir(
                 CacheStatusWarning(
                     code="banner_unparseable",
                     message=f"unable to read {body_path.name}: {exc}",
-                    path=str(body_path),
+                    path=_report_path(body_path),
                 )
             )
             continue
@@ -2928,7 +2946,7 @@ def _search_article_dir(
                 CacheStatusWarning(
                     code="banner_unparseable",
                     message=f"unable to parse banner from {body_path.name}: {exc}",
-                    path=str(body_path),
+                    path=_report_path(body_path),
                 )
             )
             continue
@@ -2940,7 +2958,7 @@ def _search_article_dir(
             continue
         matches.append(
             CacheSearchMatch(
-                path=str(body_path),
+                path=_report_path(body_path),
                 connection=connection,
                 slug=slug,
                 kind="article",
@@ -2972,7 +2990,7 @@ def _load_yaml_payload(
             CacheStatusWarning(
                 code="payload_unparseable",
                 message=f"unable to read {path.name}: {exc}",
-                path=str(path),
+                path=_report_path(path),
             )
         )
         return None
@@ -2983,7 +3001,7 @@ def _load_yaml_payload(
             CacheStatusWarning(
                 code="banner_unparseable",
                 message=f"unable to parse banner from {path.name}: {exc}",
-                path=str(path),
+                path=_report_path(path),
             )
         )
         body = raw  # try the full file — payload may parse without banner
@@ -2994,7 +3012,7 @@ def _load_yaml_payload(
             CacheStatusWarning(
                 code="payload_unparseable",
                 message=f"unable to parse YAML payload from {path.name}: {exc}",
-                path=str(path),
+                path=_report_path(path),
             )
         )
         return None
@@ -3003,7 +3021,7 @@ def _load_yaml_payload(
             CacheStatusWarning(
                 code="payload_unparseable",
                 message=f"YAML payload in {path.name} is not a mapping",
-                path=str(path),
+                path=_report_path(path),
             )
         )
         return None
@@ -3052,7 +3070,7 @@ def _search_issue_dir(
             continue
         matches.append(
             CacheSearchMatch(
-                path=str(path),
+                path=_report_path(path),
                 connection=connection,
                 slug=slug,
                 kind="issue",
@@ -3181,7 +3199,7 @@ def _search_query_dir(
                 CacheStatusWarning(
                     code="query_shape_unrecognized",
                     message=f"unknown query cache shape in {path.name}",
-                    path=str(path),
+                    path=_report_path(path),
                 )
             )
             continue
@@ -3189,7 +3207,7 @@ def _search_query_dir(
             continue
         matches.append(
             CacheSearchMatch(
-                path=str(path),
+                path=_report_path(path),
                 connection=connection,
                 slug=slug,
                 kind="query",

{kd_cli-2.6.1 → kd_cli-2.6.3}/kd/cli/core/option_registry.py

@@ -246,7 +246,12 @@ def state_option(
     )
 
 
-# Standard OUTPUT options available to all commands
+# Standard OUTPUT options available to all commands.
+#
+# ``--quiet`` is registered globally so any command's parser accepts it,
+# but it only affects mutation commands that opt into the write-output
+# contract (``display_hint="mutation"``). On reads and structured output
+# modes (``-o yaml`` / ``-o json``), ``--quiet`` is silently no-op.
 OUTPUT_OPTIONS: list[OptionDeclaration] = [
     OptionDeclaration(
         name="output",
@@ -263,4 +268,14 @@ OUTPUT_OPTIONS: list[OptionDeclaration] = [
         type=str,
         help_text="Comma-separated field list",
     ),
+    OptionDeclaration(
+        name="quiet",
+        layer=OptionLayer.OUTPUT,
+        type=bool,
+        default=False,
+        help_text=(
+            "Suppress detail block on mutation commands; print only the "
+            "single-line ack. No-op on reads and structured modes (-o yaml/json)."
+        ),
+    ),
 ]