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

{kd_cli-2.6.2/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.2
+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.2 → 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.2 → 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.2 → kd_cli-2.6.3}/kd/cli/main.py

@@ -141,6 +141,74 @@ def _print_error(error: KdError) -> None:
         print(f"Hint: {error.suggestion}", file=sys.stderr)
 
 
+def _configure_windows_stdio() -> None:
+    """Force UTF-8 on stdout/stderr when running on Windows.
+
+    No-op on POSIX. Errors during reconfigure are swallowed; the wrapper's
+    UnicodeEncodeError handler is the defensive backstop for the rare
+    embedded-interpreter case where reconfigure is unavailable.
+    """
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr,unused-ignore]
+        except Exception:
+            pass
+
+
+_DEBUG_TOKEN = re.compile(r"^-D{1,3}$")
+
+
+def _debug_requested(argv: list[str]) -> bool:
+    """Cheap preparse for ``--debug`` / ``-D{1,3}`` in the wrapper.
+
+    Used only by the friendly diagnostic handler to decide whether to re-raise
+    so the runtime prints the full traceback. Not a substitute for
+    :func:`_extract_globals`, which is the authoritative parser.
+    """
+    return any(token == "--debug" or _DEBUG_TOKEN.match(token) for token in argv)
+
+
+def _command_summary(argv: list[str]) -> str:
+    """Best-effort command path for the internal-error block.
+
+    Returns the first non-flag tokens joined by space, or ``"<unknown>"``.
+    """
+    tokens = [t for t in argv if not t.startswith("-")]
+    return " ".join(tokens) if tokens else "<unknown>"
+
+
+_MSYS_NAMESPACE_REGEX = re.compile(
+    r"^[A-Za-z]:[\\/].*?[\\/]"
+    r"(system|issue|article|primer|tag|user|time|project|query|search|alias|cache)$"
+)
+
+
+def _maybe_emit_msys_hint(args: list[str]) -> None:
+    """Stderr hint when git-bash MSYS rewrote a kd subcommand path.
+
+    From git-bash on Windows, ``kd /system info`` arrives as
+    ``["C:/Program Files/Git/system", "info"]`` because MSYS converts the
+    leading ``/`` to a Windows path before kd ever sees argv. Print a one-
+    line hint pointing at the operating-guide recovery recipes; normal
+    command parsing still runs and still fails with "Unknown command", but
+    the hint tells the operator how to retry.
+    """
+    if sys.platform != "win32" or not args:
+        return
+    if not _MSYS_NAMESPACE_REGEX.match(args[0]):
+        return
+    print(
+        "Hint: leading '/' in kd subcommand paths was converted to a "
+        "Windows path by git-bash / MSYS. Recover with `kd //system info`, "
+        "`MSYS_NO_PATHCONV=1 kd /system info`, or set "
+        "`alias kd='MSYS_NO_PATHCONV=1 kd'` in ~/.bashrc. "
+        "See `kd --guide` 'Windows shells' section.",
+        file=sys.stderr,
+    )
+
+
 def _resolve_config_or_exit(
     flags: dict[str, str] | None,
     debug_log: DebugLog,
@@ -158,7 +226,53 @@ def _resolve_config_or_exit(
 
 
 def main(argv: list[str] | None = None) -> None:
-    """CLI entry point."""
+    """CLI entry point.
+
+    Wraps :func:`_main` with the UTF-8 stdio shim and a friendly diagnostic
+    handler. ``SystemExit`` and ``KeyboardInterrupt`` propagate naturally past
+    ``except Exception`` so existing exit paths and Ctrl-C behavior are
+    preserved.
+    """
+    _configure_windows_stdio()
+    args = argv if argv is not None else sys.argv[1:]
+    _maybe_emit_msys_hint(args)
+    debug = _debug_requested(args)
+    try:
+        _main(argv)
+    except KdError as e:
+        _print_error(e)
+        sys.exit(1)
+    except UnicodeEncodeError as e:
+        if debug:
+            raise
+        print(
+            f"Error: stdout encoding could not represent a character ({e.reason!s}). "
+            "Set PYTHONIOENCODING=utf-8 or upgrade kd to a build that forces UTF-8 stdout on Windows.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except Exception as e:
+        if debug:
+            raise
+        py_version = sys.version.split()[0]
+        cmd_summary = _command_summary(args)
+        print(
+            f"Internal error: {type(e).__name__}: {e}\n"
+            "\n"
+            f"kd version:    {__version__}\n"
+            f"Python:        {py_version}\n"
+            f"Platform:      {sys.platform}\n"
+            f"Command:       {cmd_summary}\n"
+            "\n"
+            "This is a bug. Please file an issue with the above context.\n"
+            "Re-run with --debug to see the full traceback.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _main(argv: list[str] | None = None) -> None:
+    """CLI dispatch body. See :func:`main` for the friendly-diagnostic wrapper."""
     args = argv if argv is not None else sys.argv[1:]
 
     # Extract global options before namespace parsing

{kd_cli-2.6.2 → kd_cli-2.6.3}/kd/cli/namespaces/system/__init__.py

@@ -74,6 +74,7 @@ class SystemInfoCommand(Command):
         if base_url.endswith("/api"):
             base_url = base_url[:-4]
         return {
+            "connection": client.connection.name,
             "url": base_url,
             "user": me.get("login", "unknown"),
             "name": me.get("name", ""),

kd_cli-2.6.3/kd/locking.py

@@ -0,0 +1,68 @@
+"""Advisory file locking for read-modify-write transactions on kd-managed files.
+
+Provides :func:`file_transaction` — a context manager that acquires an
+exclusive advisory lock on a sidecar lockfile (``<path>.lock``) for the
+duration of a load → mutate → save cycle.  Concurrent kd processes that
+enter the same transaction serialize rather than clobber each other.
+
+Backed by :mod:`filelock`, which abstracts over ``fcntl.flock`` on POSIX
+and ``msvcrt.locking`` on Windows.  Behavior is identical on both:
+
+* **Sidecar lockfile, not the target file.**  Atomic writes elsewhere in
+  kd use ``tempfile.mkstemp`` + ``os.replace``, which changes the target
+  file's inode on every write.  Holding an advisory lock on the target
+  inode would not protect a second writer that opens the freshly-replaced
+  file.  Locking a separate sidecar that nobody rewrites keeps the lock
+  stable across atomic replaces of the data file.
+
+* **Sidecar lifecycle is filelock-managed.**  filelock owns sidecar
+  creation and removal: it unlinks the sidecar on release on both POSIX
+  and Windows.  The kd contract is the *behavior* of the lock —
+  concurrent enterers serialize — not the on-disk artifact.  Existence
+  of the sidecar is not evidence of an active lock; absence is not
+  evidence of release.  Removing the sidecar under contention is a
+  two-inode race and is not part of any recovery recipe.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+from kd.exceptions import ConfigError
+
+LOCK_SUFFIX = ".lock"
+
+
+@contextmanager
+def file_transaction(path: Path, *, timeout: float = 30.0) -> Generator[None, None, None]:
+    """Hold an exclusive advisory lock on ``<path>.lock`` for the ``with`` body.
+
+    Acquisition blocks up to *timeout* seconds.  On timeout, raises
+    :class:`ConfigError` naming the contested file.  filelock unlinks
+    the sidecar on release; the kd contract is the lock behavior, not
+    the on-disk artifact.
+    """
+    lock_path = path.with_name(path.name + LOCK_SUFFIX)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+
+    lock = FileLock(str(lock_path))
+    try:
+        lock.acquire(timeout=timeout)
+    except Timeout:
+        raise ConfigError(
+            f"Another kd process is writing to {path}; retry in a moment.",
+            suggestion=(
+                "If the wait persists, verify no other kd process is mutating "
+                "this file and check parent-directory permissions. Do not "
+                "delete the sidecar lockfile while another process may be "
+                "running."
+            ),
+        ) from None
+    try:
+        yield
+    finally:
+        lock.release()

{kd_cli-2.6.2 → kd_cli-2.6.3}/kd/resources/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.6.3] — 2026-04-30
+
+This release focuses on Windows shakedown: encoding crashes, primer
+locking, mojibake in help text, the git-bash path-conversion gotcha,
+and a contributor-token field-resolver bug surfaced along the way.
+
+### Fixed
+- `/project/field list` and the `--type` / `--priority` / `--state` /
+  `--field` resolvers now work for tokens that lack project-administration
+  rights (e.g. contributor / bot accounts). When both the per-issue and
+  admin paths return no fields, kd raises a typed error pointing at
+  token permissions instead of failing the resolver silently. Surfaced
+  during the Windows shakedown but identity-class — the fix is
+  platform-agnostic (KDCLI-164).
+- Primer mutations (`/primer/note add`, `/primer/tag add`,
+  `/primer/article add`, plus all update/remove paths) now succeed on
+  Windows. Replaces the previous POSIX-only implementation that raised
+  `ConfigError("File locking is not available on this platform (POSIX
+  only).")` at the very first acquisition on Windows. Concurrent kd
+  processes still serialize on the `.kd/primer.yaml.lock` file on both
+  platforms (KDCLI-159).
+- Output containing characters outside cp1252 (`→`, `—`, `≤`) no longer
+  crashes with `UnicodeEncodeError` on Windows, and help/synopsis text
+  on the default Windows console no longer renders mojibake (`?` / `�`)
+  for en-dashes and similar. Both paths went through the same encoding
+  layer (KDCLI-158, KDCLI-161, KDCLI-156).
+- Unhandled exceptions in the CLI now render a one-line (encoding) or
+  one-paragraph (generic) friendly diagnostic on stderr and exit `1`
+  instead of dumping a raw Python traceback. The traceback is preserved
+  under `--debug` / `-D` / `-DD` / `-DDD` so developer workflows are
+  intact. Applies on every platform (KDCLI-162).
+- Operating guide and user guide now document the git-bash MSYS
+  path-conversion gotcha. `kd /primer show` from git-bash on Windows
+  arrives as `kd C:/Program Files/Git/primer show` because MSYS
+  rewrites the leading `/` before kd ever sees argv; recovery is the
+  recommended `alias kd='MSYS_NO_PATHCONV=1 kd'` in `~/.bashrc`,
+  `MSYS_NO_PATHCONV=1 kd …` per call, or the `kd //primer show`
+  double-slash form (KDCLI-163).
+
+### Added
+- `kd /system info -o yaml` now exposes the active connection slug as
+  a top-level `connection` key. Paste `kd /system info -o yaml` into
+  a bug report and the slug used to reach the instance is captured
+  without hand-typing — `-c <slug>` overrides flow through to the
+  field as well. The previous payload named the URL but never the
+  slug, so reports against multi-connection setups had to spell the
+  slug out by hand (KDCLI-160).
+- Git-bash MSYS path-conversion hint on Windows: when `kd <converted
+  path>` reaches argv as `C:/.../<known kd namespace>`, kd prints a
+  one-line stderr hint above the existing "Unknown command" failure
+  pointing at the recovery recipes (KDCLI-163).
+
+### Changed
+- Added `filelock>=3.12` as a direct runtime dependency. Normal
+  `kd-cli` end-user installs gain one new direct runtime package; the
+  dev wheel set is unaffected because dev tooling already resolved
+  `filelock` transitively. See
+  `docs/design/ADR-012-cross-platform-locking.md` (KDCLI-159).
+- Structured cache reports normalize file-path fields to POSIX form for
+  cross-platform stability. `path:` and `manifest_path:` fields inside the
+  YAML / JSON envelopes of `/cache refresh`, `/cache clear`, `/cache status`,
+  and `/cache search` now use `/` separators on Windows the same as on macOS
+  and Linux, so LLM consumers parsing the envelope see a platform-stable
+  shape (KDCLI-168).
+
 ## [2.6.2] — 2026-04-28
 
 ### Added

{kd_cli-2.6.2 → kd_cli-2.6.3}/kd/resources/operating-guide.md

@@ -164,7 +164,7 @@ When both pinned tags and pinned articles exist, read them in order: notes tell
 
 Keep the primer local and curated. If a note becomes generally true for kd, move it into docs or this guide. If it is workspace-specific, keep it in `.kd/primer.yaml`.
 
-Primer mutations are serialized per file through an advisory lock on `.kd/primer.yaml.lock`; concurrent kd processes writing to the same primer queue rather than conflict, so agent-launched parallel `/primer/note`, `/primer/tag`, and `/primer/article` commands all converge without lost updates.
+Primer mutations are serialized per file through an advisory lock on `.kd/primer.yaml.lock`; concurrent kd processes writing to the same primer queue rather than conflict, so agent-launched parallel `/primer/note`, `/primer/tag`, and `/primer/article` commands all converge without lost updates. The lock works identically on macOS, Linux, and Windows — the underlying primitive is `fcntl.flock` on POSIX and `msvcrt.locking` on Windows, both selected automatically.
 
 ## Articles And Push
 
@@ -244,6 +244,10 @@ kd -DDD /issue list --project KDCLI
 
 Debug output goes to stderr and tokens are redacted. Use `-DDD` when investigating upstream API behavior because it includes request and response details.
 
+On Windows, kd forces UTF-8 stdout and stderr at the entry point so non-ASCII characters (`→`, `—`, `≤`, em-dash) render correctly regardless of the console's default code page (cp1252 on most installs). No `PYTHONIOENCODING` workaround is needed.
+
+Unhandled exceptions render a one-line or one-paragraph friendly diagnostic and exit non-zero. To see the full traceback (for bug reports or local debugging), re-run with `--debug` / `-D`; the wrapper re-raises the original exception so the runtime prints the traceback. `KdError` (expected user-facing failures) keep their existing one-line `Error: ...` / optional `Hint: ...` shape on every platform.
+
 If config resolution is confusing, inspect it directly:
 
 ```bash
@@ -284,6 +288,27 @@ Multi-target commands (`/issue/attachment add`, `/article/attachment add`) carry
 
 When filing a kd bug, include the output of `kd /system info -o yaml`. It names the active connection alongside `kd_version`, `python_version`, and `platform`, so the report is self-describing without hand-typing the version. Redact `url` / `email` before sharing externally.
 
+## Windows Shells
+
+kd works directly from PowerShell and `cmd.exe` on Windows — `kd /system info`, `kd /primer show`, and the rest run as written.
+
+From git-bash (and other MSYS environments), the leading `/` of a kd subcommand path is converted to a Windows path *before* kd ever sees argv, so `kd /primer show` arrives as `kd C:/Program Files/Git/primer show` and falls through to `Unknown command: C:/Program Files/Git/primer`. kd detects this shape on Windows and prints a one-line hint to stderr above the failure.
+
+Per-invocation recovery:
+
+- `MSYS_NO_PATHCONV=1 kd /primer show` — turn MSYS path conversion off for one call.
+- `kd //primer show` — the double-slash form MSYS itself documents as "I meant a literal slash."
+
+Recommended permanent fix — a kd-scoped bash alias in `~/.bashrc`:
+
+```bash
+alias kd='MSYS_NO_PATHCONV=1 kd'
+```
+
+Lowest blast radius: only `kd` invocations are affected. Other MSYS-aware tools (docker volume mounts, MinGW build scripts, etc.) keep their normal path-conversion behavior.
+
+The global form (`export MSYS_NO_PATHCONV=1` in `~/.bashrc` or a Windows-level environment variable via `setx MSYS_NO_PATHCONV 1`) also works but turns path conversion off for *every* program in the shell — that surprises tools that rely on it. Prefer the alias unless you have a deliberate reason to disable conversion globally.
+
 ## Where To Go Next
 
 Use these sources together:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.6.2
+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.2 → kd_cli-2.6.3}/kd_cli.egg-info/requires.txt

@@ -1,3 +1,4 @@
+filelock>=3.12
 httpx>=0.27
 packaging>=23.0
 pydantic>=2.0

{kd_cli-2.6.2 → kd_cli-2.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.6.2"
+version = "2.6.3"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,6 +26,7 @@ classifiers = [
 ]
 
 dependencies = [
+    "filelock>=3.12",
     "httpx>=0.27",
     "packaging>=23.0",
     "pydantic>=2.0",

kd_cli-2.6.2/kd/locking.py

@@ -1,97 +0,0 @@
-"""Advisory file locking for read-modify-write transactions on kd-managed files.
-
-Provides :func:`file_transaction` — a context manager that acquires an
-exclusive advisory lock on a sidecar lockfile (``<path>.lock``) for the
-duration of a load → mutate → save cycle.  Concurrent kd processes that
-enter the same transaction serialize rather than clobber each other.
-
-Design notes:
-
-* **Sidecar lockfile, not the target file.**  Atomic writes elsewhere in
-  kd use ``tempfile.mkstemp`` + ``os.replace``, which changes the target
-  file's inode on every write.  Holding ``flock`` on the target inode
-  would not protect a second writer that opens the freshly-replaced file.
-  Locking a separate sidecar file that nobody rewrites keeps the lock
-  stable across atomic replaces of the data file.
-
-* **No unlink on release.**  Removing the lockfile after releasing the
-  lock is a classic race: process B can open the doomed inode while
-  process C creates a fresh one, and both end up holding "exclusive"
-  locks on different inodes.  Empty sidecar files are cheap; leave them.
-
-* **POSIX only.**  ``fcntl`` is imported lazily inside the context
-  manager so that unrelated kd commands remain importable on Windows.
-  On non-POSIX platforms, :func:`file_transaction` raises ``ConfigError``
-  with a suggestion to run the command sequentially.
-
-* **NFS caveat.**  ``flock`` on NFS has been unreliable historically.
-  Modern Linux kernels implement it correctly, but operators using a
-  networked ``$HOME`` should be aware that concurrency guarantees weaken.
-  Local ``.kd/`` directories inside a repo are unaffected.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-import time
-from collections.abc import Generator
-from contextlib import contextmanager
-from pathlib import Path
-
-from kd.exceptions import ConfigError
-
-LOCK_SUFFIX = ".lock"
-_POLL_INTERVAL_SECONDS = 0.05
-
-
-@contextmanager
-def file_transaction(path: Path, *, timeout: float = 30.0) -> Generator[None, None, None]:
-    """Hold an exclusive advisory lock on ``<path>.lock`` for the ``with`` body.
-
-    The sidecar lockfile is created if missing (``O_RDWR | O_CREAT``,
-    never truncated).  Acquisition polls non-blocking ``flock`` until
-    the lock is granted or *timeout* seconds elapse.  On timeout, raises
-    :class:`ConfigError` naming the contested file.  The lockfile is
-    intentionally left on disk after release.
-
-    Raises :class:`ConfigError` on non-POSIX platforms.
-    """
-    if sys.platform == "win32":
-        raise ConfigError(
-            "File locking is not available on this platform (POSIX only).",
-            suggestion="Run the kd command sequentially; concurrent mutations are not supported on Windows.",
-        )
-
-    import fcntl  # noqa: PLC0415 — lazy import keeps kd importable on Windows
-
-    lock_path = path.with_name(path.name + LOCK_SUFFIX)
-    lock_path.parent.mkdir(parents=True, exist_ok=True)
-
-    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o644)
-    try:
-        deadline = time.monotonic() + timeout
-        while True:
-            try:
-                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
-                break
-            except BlockingIOError:
-                if time.monotonic() >= deadline:
-                    raise ConfigError(
-                        f"Another kd process is writing to {path}; retry in a moment.",
-                        suggestion=f"If no other kd process is running, remove the stale lockfile: {lock_path}",
-                    ) from None
-                time.sleep(_POLL_INTERVAL_SECONDS)
-
-        try:
-            yield
-        finally:
-            try:
-                fcntl.flock(fd, fcntl.LOCK_UN)
-            except OSError:
-                pass
-    finally:
-        try:
-            os.close(fd)
-        except OSError:
-            pass