kd-cli 2.10.0__tar.gz → 2.11.0__tar.gz

{kd_cli-2.10.0/kd_cli.egg-info → kd_cli-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.10.0
+Version: 2.11.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT
@@ -59,7 +59,7 @@ The **primer** (`kd /primer`) is the centerpiece: a small, workspace-local file
 It exists to solve a problem that has gotten worse as LLMs have become central to real work:
 
 - **Visible memory.** Agentic tools accumulate hidden "memories" in opaque per-LLM buckets you cannot easily read, edit, or audit. The primer is a plain file you can open, version, and review. If an LLM appears to "remember" something load-bearing, you can see exactly where that came from.
-- **LLM-portable.** One primer works for any model. Switch from Claude to GPT-5 to the next generation — the primer travels with the project, not with a vendor.
+- **LLM-portable.** One primer works for any model. Switch from Claude to GPT to the next generation — the primer travels with the project, not with a vendor.
 - **Shared by humans and LLMs.** A developer jotting "on this project the sprint field is called `Board`" in the primer is building the same artifact an LLM would build, in the same place, readable by both. No separate convention to maintain.
 - **A routing layer, not a copy.** The primer can pin real knowledge-base articles (`kd /primer/article add FB-A-42`). It never duplicates their content — it points at them. The rest of kd extends this shape: pull what the current task needs from live systems, reason, push updates back. Nothing gets mirrored into a parallel store.
 
@@ -83,20 +83,24 @@ uv tool install kd-cli
 
 The PyPI distribution name is `kd-cli` (two-letter `kd` is reserved by PyPI policy). The installed command, the import name, and the CLI entry point are all `kd`.
 
-Release notes for the installed version: `kd /release-notes`. The canonical changelog lives at [`kd/resources/CHANGELOG.md`](kd/resources/CHANGELOG.md).
+Release notes for the installed version: `kd /release-notes`. Every release is listed in the [changelog](https://github.com/IntellectSolutionsCom/kd-cli/blob/main/CHANGELOG.md).
 
 ## Configure
 
 ```bash
-# Scaffold a project-local config in the current directory.
-kd init
+# Global config with your YouTrack URL (recommended on first install).
+kd init --global https://your-instance.youtrack.cloud
 
-# Or set via environment (overrides workspace + global config).
-export KD_TOKEN=your_token
-export KD_CONNECTION=main
+# The scaffolded connection reads its token from KD_TOKEN (its token_env).
+export KD_TOKEN=perm:your-token-here
+
+# Check the connection.
+kd /system info
 ```
 
-Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.
+Create the token in YouTrack under Profile → Account Security → New token. In PowerShell, set it with `$env:KD_TOKEN = "perm:your-token-here"`, or `setx KD_TOKEN perm:your-token-here` to keep it, then open a new terminal. `token_cmd:` in the connection reads the token from a command, such as a secrets manager, instead.
+
+Global config lives at `~/.config/kd/config.yaml` (Windows: `C:\Users\<you>\.config\kd\config.yaml`); `kd init <url>` without `--global` writes `.kd/config.yaml` in the current directory. `KD_CONNECTION` picks the connection by name.
 
 ## Usage
 
@@ -116,13 +120,13 @@ kd /issue show FB-1
 kd /time log FB-1 45 --type Development --description "Router reconfiguration"
 
 # Articles
-kd /article list --project CMCSA
-kd /article push guide.md --project CMCSA --title "Setup Guide" --tag "type:guide"
+kd /article list --project FB
+kd /article push guide.md --project FB --title "Setup Guide" --tag "type:guide"
 kd /article pull FB-A-42 > setup.md
 
 # Tags
 kd /tag list
-kd /tag articles type:case --project CMCSA
+kd /tag articles type:case --project FB
 
 # Saved queries
 kd /query list
@@ -156,7 +160,7 @@ client = YouTrackClient(
 projects = client.projects.list()
 issue = client.issues.create(project="FB", summary="Fix router config")
 client.time.log(issue_id="FB-1", minutes=45, work_type="Development")
-articles = client.tags.articles(["type:case"], project="CMCSA")
+articles = client.tags.articles(["type:case"], project="FB")
 results = client.search.search("router", types=["issue", "article"])
 ```
 
@@ -171,4 +175,4 @@ uv run mypy
 ```
 
 ---
-Updated: 2026-04-14
+Updated: 2026-11-01

{kd_cli-2.10.0 → kd_cli-2.11.0}/README.md

@@ -19,7 +19,7 @@ The **primer** (`kd /primer`) is the centerpiece: a small, workspace-local file
 It exists to solve a problem that has gotten worse as LLMs have become central to real work:
 
 - **Visible memory.** Agentic tools accumulate hidden "memories" in opaque per-LLM buckets you cannot easily read, edit, or audit. The primer is a plain file you can open, version, and review. If an LLM appears to "remember" something load-bearing, you can see exactly where that came from.
-- **LLM-portable.** One primer works for any model. Switch from Claude to GPT-5 to the next generation — the primer travels with the project, not with a vendor.
+- **LLM-portable.** One primer works for any model. Switch from Claude to GPT to the next generation — the primer travels with the project, not with a vendor.
 - **Shared by humans and LLMs.** A developer jotting "on this project the sprint field is called `Board`" in the primer is building the same artifact an LLM would build, in the same place, readable by both. No separate convention to maintain.
 - **A routing layer, not a copy.** The primer can pin real knowledge-base articles (`kd /primer/article add FB-A-42`). It never duplicates their content — it points at them. The rest of kd extends this shape: pull what the current task needs from live systems, reason, push updates back. Nothing gets mirrored into a parallel store.
 
@@ -43,20 +43,24 @@ uv tool install kd-cli
 
 The PyPI distribution name is `kd-cli` (two-letter `kd` is reserved by PyPI policy). The installed command, the import name, and the CLI entry point are all `kd`.
 
-Release notes for the installed version: `kd /release-notes`. The canonical changelog lives at [`kd/resources/CHANGELOG.md`](kd/resources/CHANGELOG.md).
+Release notes for the installed version: `kd /release-notes`. Every release is listed in the [changelog](https://github.com/IntellectSolutionsCom/kd-cli/blob/main/CHANGELOG.md).
 
 ## Configure
 
 ```bash
-# Scaffold a project-local config in the current directory.
-kd init
+# Global config with your YouTrack URL (recommended on first install).
+kd init --global https://your-instance.youtrack.cloud
 
-# Or set via environment (overrides workspace + global config).
-export KD_TOKEN=your_token
-export KD_CONNECTION=main
+# The scaffolded connection reads its token from KD_TOKEN (its token_env).
+export KD_TOKEN=perm:your-token-here
+
+# Check the connection.
+kd /system info
 ```
 
-Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.
+Create the token in YouTrack under Profile → Account Security → New token. In PowerShell, set it with `$env:KD_TOKEN = "perm:your-token-here"`, or `setx KD_TOKEN perm:your-token-here` to keep it, then open a new terminal. `token_cmd:` in the connection reads the token from a command, such as a secrets manager, instead.
+
+Global config lives at `~/.config/kd/config.yaml` (Windows: `C:\Users\<you>\.config\kd\config.yaml`); `kd init <url>` without `--global` writes `.kd/config.yaml` in the current directory. `KD_CONNECTION` picks the connection by name.
 
 ## Usage
 
@@ -76,13 +80,13 @@ kd /issue show FB-1
 kd /time log FB-1 45 --type Development --description "Router reconfiguration"
 
 # Articles
-kd /article list --project CMCSA
-kd /article push guide.md --project CMCSA --title "Setup Guide" --tag "type:guide"
+kd /article list --project FB
+kd /article push guide.md --project FB --title "Setup Guide" --tag "type:guide"
 kd /article pull FB-A-42 > setup.md
 
 # Tags
 kd /tag list
-kd /tag articles type:case --project CMCSA
+kd /tag articles type:case --project FB
 
 # Saved queries
 kd /query list
@@ -116,7 +120,7 @@ client = YouTrackClient(
 projects = client.projects.list()
 issue = client.issues.create(project="FB", summary="Fix router config")
 client.time.log(issue_id="FB-1", minutes=45, work_type="Development")
-articles = client.tags.articles(["type:case"], project="CMCSA")
+articles = client.tags.articles(["type:case"], project="FB")
 results = client.search.search("router", types=["issue", "article"])
 ```
 
@@ -131,4 +135,4 @@ uv run mypy
 ```
 
 ---
-Updated: 2026-04-14
+Updated: 2026-11-01

{kd_cli-2.10.0 → kd_cli-2.11.0}/kd/api/http.py

@@ -11,6 +11,7 @@ Wraps httpx.Client with:
 from __future__ import annotations
 
 import json
+import math
 import time
 from typing import Any
 
@@ -27,8 +28,11 @@ from kd.exceptions import (
     enrich_error,
 )
 
-_RETRYABLE_STATUSES = {429, 502, 503}
-_MAX_RETRIES = 3
+_GATEWAY_RETRY = {502, 503}  # retried, only for a request that cannot write
+_GATEWAY_UNCONFIRMED = {502, 503, 504}  # on a write: may have been applied
+_MAX_ATTEMPTS = 3
+_BACKOFF_BASE = 1.0  # seconds; doubles per attempt
+_RETRY_AFTER_CAP = 10.0  # seconds; a longer Retry-After ends the request
 
 
 def _refuse_control_characters(path: str) -> None:
@@ -47,6 +51,44 @@ def _refuse_control_characters(path: str) -> None:
             )
 
 
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    """Return ``Retry-After`` as non-negative seconds, or ``None``.
+
+    The HTTP-date form, a negative value and anything unparseable count
+    as no header.
+    """
+    raw = response.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    if value < 0 or not math.isfinite(value):
+        return None
+    return value
+
+
+def _retry_delay(response: httpx.Response, attempt: int, *, safe: bool) -> float | None:
+    """Return the delay before the next attempt, or ``None`` to stop.
+
+    A 429 is retried for any method: the server refused before processing
+    it. It waits ``Retry-After`` up to the cap, and above the cap it stops.
+    A 502 or 503 is retried only for a request that cannot write, since a
+    proxy can answer one after the server applied the write. A 504 is not
+    retried.
+    """
+    backoff: float = _BACKOFF_BASE * 2.0**attempt
+    if response.status_code == 429:
+        wait = _retry_after_seconds(response)
+        if wait is None:
+            return backoff
+        return wait if wait <= _RETRY_AFTER_CAP else None
+    if response.status_code in _GATEWAY_RETRY and safe:
+        return backoff
+    return None
+
+
 class HttpClient:
     """Low-level HTTP client with auth, retry, and error mapping."""
 
@@ -86,12 +128,17 @@ class HttpClient:
         json: dict[str, Any] | None = None,
         fields: str | None = None,
         params: dict[str, Any] | None = None,
+        safe: bool = False,
     ) -> Any:
-        """POST with optional fields on query string."""
+        """POST with optional fields on query string.
+
+        ``safe=True`` marks a POST that only reads (an assist call): it is
+        retried like a GET, and a failure is never reported as a write.
+        """
         all_params: dict[str, Any] = dict(params or {})
         if fields:
             all_params["fields"] = fields
-        response = self._request("POST", path, json=json, params=all_params or None)
+        response = self._request("POST", path, json=json, params=all_params or None, safe=safe)
         if response.status_code == 204 or not response.content:
             return {}
         return self._decode_json(response)
@@ -131,10 +178,13 @@ class HttpClient:
         """DELETE. Returns nothing."""
         self._request("DELETE", path)
 
-    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+    def _request(
+        self, method: str, path: str, *, safe: bool = False, **kwargs: Any
+    ) -> httpx.Response:
         """Execute request with retry and error mapping."""
         _refuse_control_characters(path)
         d = self._debug
+        safe = safe or method == "GET"
 
         # Log request details before first attempt
         if params := kwargs.get("params"):
@@ -148,8 +198,7 @@ class HttpClient:
         d.trace("http", "  headers: Authorization=Bearer ***")
 
         start = time.monotonic()
-        last_response: httpx.Response | None = None
-        for attempt in range(_MAX_RETRIES):
+        for attempt in range(_MAX_ATTEMPTS):
             try:
                 response = self._client.request(method, path, **kwargs)
             except httpx.HTTPError as e:
@@ -166,12 +215,14 @@ class HttpClient:
                 d.trace("http", f"  response: {response.text[:1000]}")
                 return response
 
-            last_response = response
-            if response.status_code in _RETRYABLE_STATUSES and attempt < _MAX_RETRIES - 1:
+            delay = _retry_delay(response, attempt, safe=safe)
+            if delay is not None and attempt < _MAX_ATTEMPTS - 1:
                 d.debug(
                     "http",
-                    f"  retry {attempt + 1}/{_MAX_RETRIES} (status {response.status_code})",
+                    f"  retry {attempt + 1}/{_MAX_ATTEMPTS} in {delay:g}s "
+                    f"(status {response.status_code})",
                 )
+                time.sleep(delay)
                 continue
 
             d.info(
@@ -179,11 +230,9 @@ class HttpClient:
                 f"{method} {path} -> {response.status_code} ({duration_ms:.0f}ms) FAILED",
             )
             d.trace("http", f"  response: {response.text[:1000]}")
-            self._raise_for_status(response)
+            self._raise_for_status(response, unconfirmed_write=self._unconfirmed(response, safe))
 
-        # Satisfy type checker — _raise_for_status always raises
-        assert last_response is not None
-        self._raise_for_status(last_response)
+        # Every attempt returns, raises or continues while attempts remain.
         raise AssertionError("unreachable")  # pragma: no cover
 
     @staticmethod
@@ -249,15 +298,45 @@ class HttpClient:
         return body
 
     @staticmethod
-    def _raise_for_status(response: httpx.Response) -> None:
-        """Map HTTP status to kd exceptions. Always raises."""
+    def _unconfirmed(response: httpx.Response, safe: bool) -> bool:
+        """A 502, 503 or 504 on a request that can write: it may have been applied."""
+        return response.status_code in _GATEWAY_UNCONFIRMED and not safe
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response, *, unconfirmed_write: bool = False) -> None:
+        """Map HTTP status to kd exceptions. Always raises.
+
+        *unconfirmed_write* marks a 502, 503 or 504 on a request kd did not
+        resend because it can write: the message says so and the hint
+        names a read that checks it.
+        """
         body = response.text
         status = response.status_code
         extracted = HttpClient._extract_message(body)
         request_path = response.request.url.path if response.request else None
-        message, suggestion = enrich_error(extracted, status=status, path=request_path)
+        message, suggestion = enrich_error(
+            extracted,
+            status=status,
+            path=request_path,
+            unconfirmed_write=unconfirmed_write,
+        )
+        if unconfirmed_write:
+            method = response.request.method if response.request else "request"
+            lines = message.strip().splitlines()
+            server = lines[0] if lines else "(empty response)"
+            raise APIError(
+                status,
+                f"API error ({status}) on {method} {request_path}: kd did not resend it, "
+                f"because the server may have applied it. Server said: {server}",
+                body,
+                suggestion,
+            )
+        if status == 429:
+            wait = _retry_after_seconds(response)
+            if wait is not None:
+                message = f"{message}; the server asked to wait {wait:g} s."
         if status == 401:
-            raise AuthError(f"Authentication failed: {message}")
+            raise AuthError(f"Authentication failed: {message}", suggestion=suggestion)
         if status == 403:
             body_lower = body.lower()
             if suggestion or "permission" in body_lower or "access" in body_lower:

{kd_cli-2.10.0 → kd_cli-2.11.0}/kd/api/youtrack.py

@@ -267,7 +267,7 @@ class YouTrackAPI:
                 "Create one issue (any contributor token works), or use a "
                 "token with project-administration rights. Or omit "
                 "--type / --priority / --state to create a minimal first "
-                "issue, then update it via `/issue update`. See KDCLI-A-22."
+                "issue, then update it via `/issue update`."
             ),
         )
 
@@ -525,7 +525,7 @@ class YouTrackAPI:
         body: dict[str, Any] = {"query": query}
         if caret is not None:
             body["caret"] = caret
-        data = self._http.post("/search/assist", json=body, fields=_ASSIST_FIELDS)
+        data = self._http.post("/search/assist", json=body, fields=_ASSIST_FIELDS, safe=True)
         return AssistResponse.model_validate(data)
 
     def commands_assist(
@@ -546,5 +546,5 @@ class YouTrackAPI:
         }
         if caret is not None:
             body["caret"] = caret
-        data = self._http.post("/commands/assist", json=body, fields=_ASSIST_FIELDS)
+        data = self._http.post("/commands/assist", json=body, fields=_ASSIST_FIELDS, safe=True)
         return AssistResponse.model_validate(data)

{kd_cli-2.10.0 → kd_cli-2.11.0}/kd/auth.py

@@ -69,9 +69,8 @@ def resolve_connection_token(
         value = os.environ.get(conn.token_env)
         if value:
             return value
-        raise _missing_token_error(conn, name, origin)
-
-    raise _no_auth_source_error(conn, name, origin)
+    # ConnectionConfig requires token_cmd or token_env, so only an unset env var lands here.
+    raise _missing_token_error(conn, name, origin)
 
 
 def _run_token_cmd(cmd: str) -> str:
@@ -122,26 +121,6 @@ def _missing_token_error(
     return AuthError(message, suggestion=suggestion)
 
 
-def _no_auth_source_error(
-    conn: ConnectionConfig,
-    name: str | None,
-    origin: ConnectionOrigin | None,
-) -> AuthError:
-    """Build an ``AuthError`` for a connection with no ``token_cmd`` or ``token_env``."""
-    where = _describe_connection(conn, name)
-    message = f"{where} has no auth source configured."
-    suggestion = _build_suggestion(
-        lines=[
-            "Set one of `token_cmd:` or `token_env:` on the connection:",
-            f"  connections.{name or '<name>'}.token_cmd: gopass show -o path/to/token",
-            f"  connections.{name or '<name>'}.token_env: KD_{(name or 'NAME').upper()}_TOKEN",
-        ],
-        origin=origin,
-        key=None,
-    )
-    return AuthError(message, suggestion=suggestion)
-
-
 def _describe_connection(conn: ConnectionConfig, name: str | None) -> str:
     """Render the ``Connection '<name>' (<url>)`` prefix, degraded when no name."""
     if name:

{kd_cli-2.10.0 → kd_cli-2.11.0}/kd/cache.py

@@ -153,7 +153,7 @@ SCOPE_MANIFEST_KIND = "cache_scope"
 
 #: Markdown banner for cached article bodies. Five-space continuation
 #: indent matches ``"<!-- "`` width so the banner reads as one logical
-#: line. Pinned by tests; aligned with KDCLI-A-18 §Cache contract.
+#: line. Pinned by tests; described in ``kd --guide`` §Cache.
 BANNER_TEMPLATE_MD = (
     "<!-- kd-cache: upstream={id} fetched={iso}.\n"
     "     Disposable mirror. Edits lost on refresh. Not authoritative. -->"
@@ -2026,7 +2026,7 @@ def refresh_primer_scope(
     Read-only by contract: writes only under ``cache_root``; the primer
     is read but never mutated; no upstream mutation.
 
-    See KDCLI-A-18 §Cache contract; M008 proposal 39.
+    See ``kd --guide`` §Cache.
     """
     workspace_dir = require_workspace_dir()
     primer = load_primer(workspace_dir / PRIMER_FILENAME)
@@ -2440,7 +2440,7 @@ def refresh_milestone(
     """Hydrate a milestone-scoped query into ``cache_root/queries/milestone-<slug>.yaml``.
 
     Resolves the project's milestone field through the per-project
-    ``field_aliases`` map (KDCLI-A-18 §Project tier) — if the project
+    ``field_aliases`` map — if the project
     aliased ``milestone`` → ``Stage``, the discovered field is ``Stage``
     and the cache file's ``source.field_name`` records that. Without an
     alias, falls back to the literal ``Milestone`` name. The discovery

{kd_cli-2.10.0 → kd_cli-2.11.0}/kd/cli/core/command_base.py

@@ -62,6 +62,9 @@ class Command(ABC):
         self.examples: list[str] = examples or []
         self.see_also: list[str] = see_also or []
         self.display_hint: str | None = None
+        # A connection the command's own output names as invalid: the dispatcher
+        # adds no connection_invalid warning about it (kd init's next line).
+        self.invalid_connection_named: str | None = None
         self._options: list[OptionDeclaration] = []
         self._resolved_config: ResolvedConfig | None = None
         self._register_options()

{kd_cli-2.10.0 → kd_cli-2.11.0}/kd/cli/input.py

@@ -12,6 +12,20 @@ from pathlib import Path
 
 from kd.exceptions import ValidationError
 
+#: Help clause for every option and argument read through
+#: :func:`resolve_text_input`; it names the guide section with the shell recipes.
+TEXT_INPUT_HELP = (
+    'Pass "@file.md" to read a file or "@-" to read stdin, in quotes '
+    "(PowerShell needs them); see kd --guide §Markdown Bodies"
+)
+
+#: Help sentence for the attachment commands: how a body references the file
+#: the user passed in.
+IMAGE_REFERENCE_HELP = (
+    "Reference an attached image in the body by its file name alone, as in "
+    "![Diagram](diagram.png); see kd --guide §Markdown Bodies."
+)
+
 
 def resolve_text_input(value: str | None) -> str | None:
     """Resolve a text value that may reference a file or stdin.