kd-cli 2.0.6__tar.gz → 2.1.0__tar.gz

{kd_cli-2.0.6 → kd_cli-2.1.0}/MANIFEST.in

@@ -3,7 +3,7 @@ include LICENSE
 include pyproject.toml
 include MANIFEST.in
 
-recursive-include kd *.py *.yaml
+recursive-include kd *.py *.yaml *.md
 
 prune tests
 prune .kd

{kd_cli-2.0.6/kd_cli.egg-info → kd_cli-2.1.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.0.6
+Version: 2.1.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT
 Project-URL: Homepage, https://pypi.org/project/kd-cli/
 Project-URL: Issues, https://github.com/IntellectSolutionsCom/kd-cli/issues
 Project-URL: Source, https://github.com/IntellectSolutionsCom/kd-cli
+Project-URL: Changelog, https://github.com/IntellectSolutionsCom/kd-cli/blob/main/kd/resources/CHANGELOG.md
 Keywords: youtrack,cli,sdk,knowledge-management,knowledge-network
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -22,6 +23,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx>=0.27
+Requires-Dist: packaging>=23.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tabulate>=0.9
@@ -80,6 +82,8 @@ 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).
+
 ## Configure
 
 ```bash

{kd_cli-2.0.6 → kd_cli-2.1.0}/README.md

@@ -43,6 +43,8 @@ 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).
+
 ## Configure
 
 ```bash

{kd_cli-2.0.6 → kd_cli-2.1.0}/kd/cli/main.py

@@ -29,7 +29,7 @@ from kd.client import YouTrackClient
 from kd.config import ResolvedConfig, resolve_command_defaults, resolve_config
 from kd.connection import ConnectionContext, resolve_connection
 from kd.debug import DebugLevel, DebugLog, init_debug_log
-from kd.exceptions import APIError, KdError
+from kd.exceptions import APIError, ConfigError, KdError
 
 # Global options — single source of truth for extraction, help, and reference.
 GLOBAL_OPTIONS: list[OptionDeclaration] = [
@@ -121,10 +121,26 @@ def expand_toplevel_alias(
 def _print_error(error: KdError) -> None:
     """Print error with optional suggestion to stderr."""
     print(f"Error: {error}", file=sys.stderr)
-    if isinstance(error, APIError) and error.suggestion:
+    if isinstance(error, (APIError, ConfigError)) and error.suggestion:
         print(f"Hint: {error.suggestion}", file=sys.stderr)
 
 
+def _resolve_config_or_exit(
+    flags: dict[str, str] | None,
+    debug_log: DebugLog,
+) -> ResolvedConfig:
+    """Wrap :func:`resolve_config` so config failures exit cleanly.
+
+    Unexpected (non-``KdError``) exceptions are not caught — they must
+    remain visible with their traceback.
+    """
+    try:
+        return resolve_config(flags=flags, debug_log=debug_log)
+    except KdError as e:
+        _print_error(e)
+        sys.exit(1)
+
+
 def main(argv: list[str] | None = None) -> None:
     """CLI entry point."""
     args = argv if argv is not None else sys.argv[1:]
@@ -146,7 +162,7 @@ def main(argv: list[str] | None = None) -> None:
     # Config is loaded early only when needed; stored for reuse later.
     resolved: ResolvedConfig | None = None
     if len(remaining) >= 2 and remaining[0] == "alias" and remaining[1] not in _ALIAS_SUBCOMMANDS:
-        resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+        resolved = _resolve_config_or_exit(config_flags, debug_log)
         remaining = expand_alias(remaining, resolved)
 
     # Build registry and parser
@@ -155,7 +171,7 @@ def main(argv: list[str] | None = None) -> None:
 
     if global_opts.get("reference"):
         if resolved is None:
-            resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+            resolved = _resolve_config_or_exit(config_flags, debug_log)
         _show_reference(registry, config=resolved)
         return
     parser = CommandParser(registry)
@@ -195,7 +211,7 @@ def main(argv: list[str] | None = None) -> None:
         # check whether it matches a configured alias and expand it.
         if unresolved.namespace is registry.root:
             if resolved is None:
-                resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+                resolved = _resolve_config_or_exit(config_flags, debug_log)
             expanded = expand_toplevel_alias(unresolved.command_name, remaining[1:], resolved)
             if expanded is not None:
                 try:
@@ -229,7 +245,7 @@ def main(argv: list[str] | None = None) -> None:
 
     # Resolve config from flags + env + local + global (reuse if loaded for alias expansion)
     if resolved is None:
-        resolved = resolve_config(flags=config_flags, debug_log=debug_log)
+        resolved = _resolve_config_or_exit(config_flags, debug_log)
 
     # Debug config key: if config says debug=true and no -D on CLI, enable level 1
     if resolved.debug and not global_opts.get("debug"):

{kd_cli-2.0.6 → kd_cli-2.1.0}/kd/cli/namespaces/__init__.py

@@ -12,6 +12,7 @@ from kd.cli.namespaces.issue import create_issue_namespace
 from kd.cli.namespaces.primer import create_primer_namespace
 from kd.cli.namespaces.project import create_project_namespace
 from kd.cli.namespaces.query import create_query_namespace
+from kd.cli.namespaces.release_notes import ReleaseNotesCommand
 from kd.cli.namespaces.search import SearchCommand
 from kd.cli.namespaces.system import create_system_namespace
 from kd.cli.namespaces.tag import create_tag_namespace
@@ -22,6 +23,7 @@ from kd.cli.namespaces.user import create_user_namespace
 def register_all_namespaces(registry: NamespaceRegistry) -> None:
     """Register all namespace trees in the registry."""
     registry.root.register_command("init", InitCommand())
+    registry.root.register_command("release-notes", ReleaseNotesCommand())
     registry.root.register_command("search", SearchCommand())
     registry.register_namespace(create_alias_namespace())
     registry.register_namespace(create_article_namespace())

kd_cli-2.1.0/kd/cli/namespaces/init.py

@@ -0,0 +1,61 @@
+"""Init command: kd init
+
+Scaffolds a kd config file at the local tier (.kd/config.yaml in the
+current directory, with .gitignore management) or the global tier
+(~/.config/kd/config.yaml, parent directory created as needed).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.option_registry import OptionDeclaration, OptionLayer, ResolvedOptions
+from kd.config import init_project_config
+
+
+class InitCommand(Command):
+    """Initialize project config."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "init",
+            "Initialize kd config (.kd/config.yaml or ~/.config/kd/config.yaml)",
+            usage="kd init [URL] [--global]",
+            long_description=(
+                "Creates a config file. Default is .kd/config.yaml in the "
+                "current directory, with .kd/ added to .gitignore when inside "
+                "a git repository. With --global (-g), writes "
+                "~/.config/kd/config.yaml instead, creating the parent "
+                "directory if needed. Optionally pre-fills the YouTrack URL."
+            ),
+            examples=[
+                "kd init",
+                "kd init https://example.youtrack.cloud",
+                "kd init --global https://example.youtrack.cloud",
+            ],
+            see_also=["/system/config list", "/system/config which"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="global",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                short_name="g",
+                help_text="Scaffold global config at ~/.config/kd/config.yaml",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        url = args[0] if args else None
+        use_global = options.command.get("global", False)
+        result = init_project_config(url=url, global_tier=use_global)
+        return {
+            "created": str(result.created),
+            "gitignore": result.gitignore_action,
+            "next": "Run 'kd /system/config keys' to list configurable paths.",
+        }

kd_cli-2.1.0/kd/cli/namespaces/release_notes.py

@@ -0,0 +1,116 @@
+"""Release-notes command: /release-notes
+
+Serves the bundled `kd/resources/CHANGELOG.md`. Supports slicing by
+`--version`, `--since`, or `--all`. Default returns the latest released
+section.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from packaging.version import InvalidVersion
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.option_registry import OptionDeclaration, OptionLayer, ResolvedOptions
+from kd.exceptions import ValidationError
+from kd.release_notes import (
+    filter_since,
+    get_version,
+    latest,
+    load_changelog,
+    parse_changelog,
+    render_section,
+)
+
+
+class ReleaseNotesCommand(Command):
+    """Print release notes from the bundled changelog."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "release-notes",
+            "Print release notes from the bundled changelog",
+            usage="kd /release-notes [VERSION] [--since X.Y.Z | --all]",
+            long_description=(
+                "Reads the bundled CHANGELOG.md and prints one or more "
+                "release sections. Default returns the latest released "
+                "section. Pass a version positionally to pin a specific "
+                "release, --since to slice everything strictly newer than "
+                "a given version, or --all for the complete file. Output "
+                "defaults to markdown; -o json or -o yaml emits a "
+                "structured list of {version, date, body} dicts for "
+                "programmatic consumers. Source: kd/resources/CHANGELOG.md "
+                "in the installed wheel."
+            ),
+            examples=[
+                "kd /release-notes",
+                "kd /release-notes 2.1.0",
+                "kd /release-notes --since 2.0.5",
+                "kd /release-notes --all -o json",
+            ],
+            see_also=["/primer show"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="since",
+                layer=OptionLayer.COMMAND,
+                type=str,
+                help_text="Return every version strictly newer than this",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="all",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                help_text="Return the complete changelog",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        version = args[0] if args else None
+        since = options.command.get("since")
+        show_all = options.command.get("all", False)
+
+        chosen = [
+            flag
+            for flag, val in (("VERSION", version), ("--since", since), ("--all", show_all))
+            if val
+        ]
+        if len(chosen) > 1:
+            raise ValidationError(
+                f"VERSION, --since, and --all are mutually exclusive; got {', '.join(chosen)}"
+            )
+
+        sections = parse_changelog(load_changelog())
+
+        if version:
+            section = get_version(sections, version)
+            if section is None:
+                raise ValidationError(
+                    f"Version {version} not found in changelog. "
+                    f"Run 'kd /release-notes --all' to see available versions."
+                )
+            result = [section]
+        elif since:
+            try:
+                result = filter_since(sections, since)
+            except InvalidVersion as exc:
+                raise ValidationError(f"Invalid version '{since}': {exc}") from exc
+        elif show_all:
+            result = sections
+        else:
+            only = latest(sections)
+            if only is None:
+                raise ValidationError("Changelog has no released versions.")
+            result = [only]
+
+        fmt = options.output.get("output")
+        if fmt in ("json", "yaml"):
+            return [{"version": s.version, "date": s.date, "body": s.body} for s in result]
+        return "\n\n".join(render_section(s) for s in result)