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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.10.0
+Version: 2.11.1
 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.1}/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.11.1/kd/_option_chain.py

@@ -0,0 +1,414 @@
+"""The 10-layer command-option resolution chain and shadow detection.
+
+The layers are listed on :func:`resolve_command_defaults`. :mod:`kd.config`
+re-exports the public names and is imported here only at call time, so either
+module may be imported first.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from kd.debug import DebugLog
+
+if TYPE_CHECKING:
+    from kd.cli.core.option_registry import OptionDeclaration
+    from kd.config import ResolvedConfig
+
+
+# Keys that exist as both flat config keys and command/output options.
+# These participate in levels 5/7 of the command option resolution chain.
+_FLAT_OPTION_KEYS = {"limit", "output"}
+
+
+def resolve_command_defaults(
+    command_key: str,
+    project: str | None,
+    raw_options: dict[str, Any],
+    config: ResolvedConfig,
+    declarations: list[OptionDeclaration],
+    *,
+    debug_log: DebugLog | None = None,
+) -> dict[str, Any]:
+    """Resolve command option defaults from the config hierarchy.
+
+    Returns a dict of option values for options **not** present in
+    *raw_options* (CLI flags always win — level 1).
+
+    Resolution per option (first non-None wins):
+
+    1. CLI flag — skipped (present in *raw_options*)
+    2. Env var — N/A for command options
+    3. Project command default — ``projects.<proj>.defaults.<cmd>.<opt>``
+    4. Local command default — ``defaults.<cmd>.<opt>`` in local config
+    5. Local flat key — for ``limit``/``output`` only
+    6. Connection command default — ``connections.<name>.defaults.<cmd>.<opt>``
+    7. Connection flat key — for ``limit``/``output`` only
+    8. Global command default — ``defaults.<cmd>.<opt>`` in global config
+    9. Global flat key — for ``limit``/``output`` only
+    10. Built-in default — from ``OptionDeclaration.default``
+    """
+    d = debug_log or DebugLog()
+    resolved: dict[str, Any] = {}
+
+    for decl in declarations:
+        opt = decl.name
+
+        # Level 1: CLI flag already set — skip
+        if opt in raw_options:
+            continue
+
+        value = _resolve_single_option(opt, command_key, project, config, d)
+        if value is not None:
+            resolved[opt] = value
+
+    return resolved
+
+
+@dataclass(frozen=True)
+class LayerState:
+    """State of a single layer in the 10-layer command-option resolution chain.
+
+    ``value`` is ``None`` when the layer does not contribute — either because
+    the option is not configured there, or because the layer never applies to
+    this option class (e.g. flat layers 5/7/9 for non-flat options). ``status``
+    disambiguates those cases and marks which layer wins vs. is shadowed.
+    """
+
+    layer: int
+    source: str
+    origin: str | None
+    value: Any
+    status: str  # "winning" | "shadowed" | "not set" | "n/a" | "invalid"
+
+
+def walk_option_layers(
+    opt: str,
+    command_key: str,
+    project: str | None,
+    config: ResolvedConfig,
+    *,
+    cli_value: Any = None,
+    builtin_default: Any = None,
+    local_config_path: str | None = None,
+    global_config_path: str | None = None,
+) -> list[LayerState]:
+    """Walk the 10-layer command-option resolution chain for *opt*.
+
+    Returns one :class:`LayerState` per layer in priority order (1..10). The
+    first layer with a non-``None`` value has ``status="winning"``; subsequent
+    non-``None`` layers have ``status="shadowed"``. Layers that never apply
+    (flat layers 5/7/9 for options outside ``_FLAT_OPTION_KEYS``, layer 2 for
+    command options, layer 6/7 when no active connection) have ``status="n/a"``.
+    Populated-eligible layers with no value are ``"not set"``.
+    """
+    from kd import config as kd_config  # at call time: tests patch these names there
+
+    if local_config_path is None:
+        _lp = kd_config.find_local_config()
+        local_config_path = str(_lp) if _lp else None
+    if global_config_path is None:
+        global_config_path = str(kd_config.DEFAULT_CONFIG_PATH)
+
+    conn_name = config.default_connection_name
+    conn_origin = config.connection_origins.get(conn_name) if conn_name else None
+    conn_invalid = config.invalid_connections.get(conn_name) if conn_name else None
+    is_flat = opt in _FLAT_OPTION_KEYS
+
+    def _conn_key_origin(key: str) -> str | None:
+        if conn_origin is None:
+            return None
+        ko = conn_origin.keys.get(key)
+        return ko.path if ko is not None else conn_origin.path
+
+    def _conn_default_origin() -> str | None:
+        """Layer 6's file: the one that sets this command's option, per leaf.
+
+        A local key replaces the global one in the connection merge even
+        when it is empty, so the first file that has the key is the origin.
+        """
+        if conn_name is not None:
+            leaf = ["connections", conn_name, "defaults", command_key, opt]
+            for tier in kd_config.config_tier_values(config, leaf):
+                if tier.present:
+                    return str(tier.path) if tier.path is not None else None
+        return _conn_key_origin("defaults")
+
+    # (layer, source, origin, value, applicable) in priority order.
+    raw: list[tuple[int, str, str | None, Any, bool]] = []
+
+    # Layer 1 — CLI flag
+    raw.append((1, f"cli.{opt}", None, cli_value, True))
+
+    # Layer 2 — env var (always n/a for command options)
+    raw.append((2, "env", None, None, False))
+
+    # Layer 3 — project command default (local-first then global, same layer)
+    proj_val: Any = None
+    proj_source = f"project.defaults.{command_key}"
+    proj_origin: str | None = None
+    if project:
+        v = _project_command_default(project, command_key, opt, config.local_projects)
+        if v is not None:
+            proj_val = v
+            proj_source = f"project({project}).local.{command_key}"
+            proj_origin = local_config_path
+        else:
+            v = _project_command_default(project, command_key, opt, config.global_projects)
+            if v is not None:
+                proj_val = v
+                proj_source = f"project({project}).global.{command_key}"
+                proj_origin = global_config_path
+    raw.append((3, proj_source, proj_origin, proj_val, project is not None))
+
+    # Layer 4 — local command default
+    raw.append(
+        (
+            4,
+            f"local.defaults.{command_key}",
+            local_config_path,
+            config.local_defaults.get(command_key, {}).get(opt),
+            True,
+        )
+    )
+
+    # Layer 5 — local flat key (limit/output only)
+    raw.append(
+        (
+            5,
+            "local.flat",
+            local_config_path,
+            config.local_flat.get(opt) if is_flat else None,
+            is_flat,
+        )
+    )
+
+    # Layer 6 — connection command default
+    raw.append(
+        (
+            6,
+            f"connection.defaults.{command_key}",
+            _conn_default_origin(),
+            config.connection_defaults.get(command_key, {}).get(opt),
+            conn_name is not None,
+        )
+    )
+
+    # Layer 7 — connection flat key (limit/output only)
+    raw.append(
+        (
+            7,
+            "connection.flat",
+            _conn_key_origin(opt),
+            config.connection_flat.get(opt) if is_flat else None,
+            is_flat and conn_name is not None,
+        )
+    )
+
+    # Layer 8 — global command default
+    raw.append(
+        (
+            8,
+            f"global.defaults.{command_key}",
+            global_config_path,
+            config.global_defaults.get(command_key, {}).get(opt),
+            True,
+        )
+    )
+
+    # Layer 9 — global flat key (limit/output only)
+    raw.append(
+        (
+            9,
+            "global.flat",
+            global_config_path,
+            config.global_flat.get(opt) if is_flat else None,
+            is_flat,
+        )
+    )
+
+    # Layer 10 — built-in default
+    raw.append((10, "built-in", None, builtin_default, builtin_default is not None))
+
+    # Stamp statuses: first non-None wins, later non-Nones are shadowed. An
+    # invalid active connection contributes nothing to layers 6 and 7, and
+    # says so instead of reading "not set" (KDCLI-321).
+    winner_found = False
+    out: list[LayerState] = []
+    for layer, source, origin, value, applicable in raw:
+        if conn_invalid is not None and layer in (6, 7) and applicable:
+            out.append(
+                LayerState(
+                    layer=layer,
+                    source=source,
+                    origin=conn_invalid.path,
+                    value=None,
+                    status="invalid",
+                )
+            )
+            continue
+        if value is None:
+            status = "not set" if applicable else "n/a"
+        elif not winner_found:
+            status = "winning"
+            winner_found = True
+        else:
+            status = "shadowed"
+        out.append(
+            LayerState(layer=layer, source=source, origin=origin, value=value, status=status)
+        )
+    return out
+
+
+def _resolve_single_option(
+    opt: str,
+    command_key: str,
+    project: str | None,
+    config: ResolvedConfig,
+    d: DebugLog,
+) -> Any:
+    """Walk levels 3–9 for a single option. Returns None if no config value found."""
+    for state in walk_option_layers(opt, command_key, project, config):
+        if state.status == "winning":
+            d.debug("config", f"option {opt}: {state.source} -> {state.value}")
+            return state.value
+    return None
+
+
+def _project_command_default(
+    project: str,
+    command_key: str,
+    opt: str,
+    projects_raw: dict[str, Any],
+) -> Any:
+    """Look up a project command default from a raw projects dict."""
+    proj_data = projects_raw.get(project)
+    if not isinstance(proj_data, dict):
+        return None
+    defaults = proj_data.get("defaults")
+    if not isinstance(defaults, dict):
+        return None
+    cmd_defaults = defaults.get(command_key)
+    if not isinstance(cmd_defaults, dict):
+        return None
+    return cmd_defaults.get(opt)
+
+
+# ---------------------------------------------------------------------------
+# Shadow detection — post-write check against the 10-layer chain
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ShadowWarning:
+    """Result of :func:`detect_shadow` — a written value is shadowed.
+
+    ``written`` names the layer and source the write landed at; ``winning``
+    names the higher-priority layer whose value continues to resolve.
+    ``option`` is ``"<command_key>.<option>"``. ``hint_path`` suggests a
+    dotted path that would actually override the winning layer, or None
+    when no such path exists below the winning tier.
+    """
+
+    written: dict[str, Any]
+    winning: dict[str, Any]
+    option: str
+    hint_path: str | None
+
+
+def detect_shadow(
+    path: str,
+    tier: str,
+    rc: ResolvedConfig,
+    *,
+    default_lookup: Callable[[str, str], Any] | None = None,
+) -> ShadowWarning | None:
+    """Return a :class:`ShadowWarning` when *path* (just written in *tier*)
+    is shadowed by a higher-priority layer in *rc*, else ``None``.
+
+    Returns ``None`` when the path is not part of the command-option chain,
+    when the write landed at the winning layer, or when the post-write walker
+    reports no higher-priority layer with a value. Paths that don't map to a
+    specific ``<command_key>.<option>`` target — flat top-level writes and
+    connection-level flat writes — are cross-command by nature and are not
+    flagged here.
+
+    *rc* must be a freshly-resolved config (post-write); callers are
+    responsible for reloading. *default_lookup*, when provided, is called
+    as ``default_lookup(command_key, option_name)`` to obtain the layer-10
+    built-in default (typically the caller reaches into the CLI option
+    registry); ``None`` or a lookup returning ``None`` means layer 10 stays
+    unpopulated, which is fine for shadow comparison.
+    """
+    classified = _classify_set_path(path, tier, rc.default_connection_name)
+    if classified is None:
+        return None
+    written_layer, command_key, option_name = classified
+
+    builtin_default = default_lookup(command_key, option_name) if default_lookup else None
+
+    states = walk_option_layers(
+        option_name,
+        command_key,
+        rc.default_project,
+        rc,
+        builtin_default=builtin_default,
+    )
+    winner = next((s for s in states if s.status == "winning"), None)
+    if winner is None or winner.layer >= written_layer:
+        return None  # write is active (equal) or nothing set (impossible post-write)
+
+    written = next((s for s in states if s.layer == written_layer), None)
+    hint_path = _shadow_hint_path(winner, command_key, option_name, rc)
+    return ShadowWarning(
+        written={
+            "layer": written_layer,
+            "value": written.value if written else None,
+            "source": written.source if written else "",
+        },
+        winning={
+            "layer": winner.layer,
+            "value": winner.value,
+            "source": winner.source,
+            "origin": winner.origin,
+        },
+        option=f"{command_key}.{option_name}",
+        hint_path=hint_path,
+    )
+
+
+def _classify_set_path(
+    path: str, tier: str, active_connection: str | None
+) -> tuple[int, str, str] | None:
+    """Map a written config path to a chain layer + (command_key, option)."""
+    segs = path.split(".")
+    # defaults.<cmd>.<opt> — layer 4 (local) / 8 (global)
+    if len(segs) == 3 and segs[0] == "defaults":
+        layer = 4 if tier == "local" else 8
+        return layer, segs[1], segs[2]
+    # connections.<name>.defaults.<cmd>.<opt> — layer 6 when <name> is active
+    if (
+        len(segs) == 5
+        and segs[0] == "connections"
+        and segs[2] == "defaults"
+        and active_connection is not None
+        and segs[1] == active_connection
+    ):
+        return 6, segs[3], segs[4]
+    return None
+
+
+def _shadow_hint_path(
+    winner: LayerState, command_key: str, option_name: str, rc: ResolvedConfig
+) -> str | None:
+    """Suggest a path that would actually override the winning layer, if any.
+
+    For a winning connection-flat value, suggest
+    ``connections.<name>.defaults.<cmd>.<opt>`` which sits at layer 6 —
+    one step above layer 7 and scoped per-command.
+    """
+    if winner.layer == 7 and rc.default_connection_name is not None:
+        return f"connections.{rc.default_connection_name}.defaults.{command_key}.{option_name}"
+    return None