kd-cli 2.0.4__tar.gz

kd_cli-2.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergiy Gladkyy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kd_cli-2.0.4/MANIFEST.in

@@ -0,0 +1,32 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include MANIFEST.in
+
+recursive-include kd *.py *.yaml
+
+prune tests
+prune .kd
+prune .claude
+prune .github
+prune .venv
+prune playground
+prune ref
+prune scripts
+prune docs
+prune build
+prune dist
+prune .mypy_cache
+prune .ruff_cache
+prune .pytest_cache
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.egg-info
+global-exclude .DS_Store
+global-exclude .env*
+global-exclude .secrets*
+global-exclude .mcp*.json
+global-exclude uv.lock
+global-exclude .envrc
+global-exclude .pre-commit-config.yaml

kd_cli-2.0.4/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: kd-cli
+Version: 2.0.4
+Summary: Knowledge dispatcher for live knowledge systems
+Author: Sergiy Gladkyy
+License-Expression: MIT
+Keywords: youtrack,cli,sdk,knowledge-management,knowledge-network
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tabulate>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-tabulate; extra == "dev"
+Dynamic: license-file
+
+# kd
+
+A knowledge dispatcher for live knowledge systems — pull what you need to reason, push your updates back, and stay on top of a live system rather than copying it.
+
+## Purpose
+
+**kd is a knowledge-network tool, not a data-exchange tool.** It is built around a small, primer-shaped idea: the operator reasons *on top of* live trackers, not alongside copies of them. The primary loop is **pull → reason → push updates back**. Integrating multiple sources happens in the operator's head — not in kd's data model. Occasional cross-system moves exist, but they are deliberately thin: at the limit, a stub with a similar title and a backref to the original, not a faithful reproduction. kd is not a migration tool or a comprehensive import-export platform; it is a network-of-knowledge dispatcher that speaks YouTrack fluently and will, over time, speak other trackers through narrow domain protocols.
+
+The **primer** (`kd /primer`) is the working illustration: a small set of pinned references plus curated notes, living in the workspace, sitting on top of live systems without replacing them. The rest of the tool extends that shape.
+
+**SDK-first**: the Python library (`kd.client`) is the primary interface; CLI commands are thin wrappers over it. LLMs constructing commands programmatically are the primary consumer, so syntax clarity and structured output matter more than keystroke economy.
+
+## Install
+
+```bash
+# pipx (recommended)
+pipx install kd
+
+# or uv
+uv tool install kd
+```
+
+## Configure
+
+```bash
+# Scaffold a project-local config in the current directory.
+kd init
+
+# Or set via environment (overrides workspace + global config).
+export KD_TOKEN=your_token
+export KD_CONNECTION=main
+```
+
+Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.
+
+## Usage
+
+### CLI
+
+```bash
+# Projects
+kd /project list
+kd /project show FB
+
+# Issues
+kd /issue list --project FB --query "#Unresolved"
+kd /issue create "Fix router configuration" -p FB --type Task
+kd /issue show FB-1
+
+# Time tracking
+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 pull FB-A-42 > setup.md
+
+# Tags
+kd /tag list
+kd /tag articles type:case --project CMCSA
+
+# Saved queries
+kd /query list
+kd /query issues "Sprint 47" --project FB
+
+# Primer (local knowledge, LLM context)
+kd /primer/note add "Sprint field is called 'Board'"
+kd /primer/article add FB-A-42 --summary "Architecture Overview"
+kd /primer show
+
+# Cross-entity search
+kd /search "router" --types issue,article --project FB
+
+# Output formats
+kd /project list --output json | jq '.[].key'
+kd /issue list --output yaml
+```
+
+### Python SDK
+
+```python
+from kd import YouTrackClient
+
+client = YouTrackClient(
+    url="https://your-instance.youtrack.cloud",
+    token="your_token",
+)
+
+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")
+results = client.search.search("router", types=["issue", "article"])
+```
+
+## What kd is not
+
+- **Not a migration platform.** Cross-system moves are lossy cherry-picks: a stub on the target side with a backref to the source, nothing more.
+- **Not a faithful mirror.** kd never claims to be a complete copy of upstream state; it reads what it needs and writes what changed.
+- **Not a data warehouse.** Data lives in the upstream tracker; kd sits on top.
+
+If you need a migration tool or an import-export platform, kd is the wrong tool.
+
+## Development
+
+```bash
+pytest tests/ -v --tb=short
+
+ruff format kd/ tests/
+ruff check --fix kd/ tests/
+mypy kd/
+```
+
+---
+Updated: 2026-04-13

kd_cli-2.0.4/README.md

@@ -0,0 +1,115 @@
+# kd
+
+A knowledge dispatcher for live knowledge systems — pull what you need to reason, push your updates back, and stay on top of a live system rather than copying it.
+
+## Purpose
+
+**kd is a knowledge-network tool, not a data-exchange tool.** It is built around a small, primer-shaped idea: the operator reasons *on top of* live trackers, not alongside copies of them. The primary loop is **pull → reason → push updates back**. Integrating multiple sources happens in the operator's head — not in kd's data model. Occasional cross-system moves exist, but they are deliberately thin: at the limit, a stub with a similar title and a backref to the original, not a faithful reproduction. kd is not a migration tool or a comprehensive import-export platform; it is a network-of-knowledge dispatcher that speaks YouTrack fluently and will, over time, speak other trackers through narrow domain protocols.
+
+The **primer** (`kd /primer`) is the working illustration: a small set of pinned references plus curated notes, living in the workspace, sitting on top of live systems without replacing them. The rest of the tool extends that shape.
+
+**SDK-first**: the Python library (`kd.client`) is the primary interface; CLI commands are thin wrappers over it. LLMs constructing commands programmatically are the primary consumer, so syntax clarity and structured output matter more than keystroke economy.
+
+## Install
+
+```bash
+# pipx (recommended)
+pipx install kd
+
+# or uv
+uv tool install kd
+```
+
+## Configure
+
+```bash
+# Scaffold a project-local config in the current directory.
+kd init
+
+# Or set via environment (overrides workspace + global config).
+export KD_TOKEN=your_token
+export KD_CONNECTION=main
+```
+
+Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.
+
+## Usage
+
+### CLI
+
+```bash
+# Projects
+kd /project list
+kd /project show FB
+
+# Issues
+kd /issue list --project FB --query "#Unresolved"
+kd /issue create "Fix router configuration" -p FB --type Task
+kd /issue show FB-1
+
+# Time tracking
+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 pull FB-A-42 > setup.md
+
+# Tags
+kd /tag list
+kd /tag articles type:case --project CMCSA
+
+# Saved queries
+kd /query list
+kd /query issues "Sprint 47" --project FB
+
+# Primer (local knowledge, LLM context)
+kd /primer/note add "Sprint field is called 'Board'"
+kd /primer/article add FB-A-42 --summary "Architecture Overview"
+kd /primer show
+
+# Cross-entity search
+kd /search "router" --types issue,article --project FB
+
+# Output formats
+kd /project list --output json | jq '.[].key'
+kd /issue list --output yaml
+```
+
+### Python SDK
+
+```python
+from kd import YouTrackClient
+
+client = YouTrackClient(
+    url="https://your-instance.youtrack.cloud",
+    token="your_token",
+)
+
+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")
+results = client.search.search("router", types=["issue", "article"])
+```
+
+## What kd is not
+
+- **Not a migration platform.** Cross-system moves are lossy cherry-picks: a stub on the target side with a backref to the source, nothing more.
+- **Not a faithful mirror.** kd never claims to be a complete copy of upstream state; it reads what it needs and writes what changed.
+- **Not a data warehouse.** Data lives in the upstream tracker; kd sits on top.
+
+If you need a migration tool or an import-export platform, kd is the wrong tool.
+
+## Development
+
+```bash
+pytest tests/ -v --tb=short
+
+ruff format kd/ tests/
+ruff check --fix kd/ tests/
+mypy kd/
+```
+
+---
+Updated: 2026-04-13

kd_cli-2.0.4/kd/__init__.py

@@ -0,0 +1,45 @@
+"""kd — knowledge dispatcher for live knowledge systems.
+
+SDK-first design: import YouTrackClient for programmatic access,
+or use the ``kd`` command for CLI operations.
+
+Usage::
+
+    from kd import YouTrackClient
+
+    client = YouTrackClient(url="https://example.youtrack.cloud", token="...")
+    projects = client.projects.list()
+"""
+
+from importlib.metadata import version as _pkg_version
+
+__version__ = _pkg_version("kd-cli")
+
+from kd.client import YouTrackClient
+from kd.config import ConfigSource, ResolvedConfig, resolve_config
+from kd.debug import DebugLevel, DebugLog
+from kd.exceptions import (
+    APIError,
+    AuthError,
+    ConfigError,
+    ConflictError,
+    NotFoundError,
+    ValidationError,
+    KdError,
+)
+
+__all__ = [
+    "APIError",
+    "AuthError",
+    "ConfigError",
+    "ConfigSource",
+    "ConflictError",
+    "DebugLevel",
+    "DebugLog",
+    "NotFoundError",
+    "ResolvedConfig",
+    "ValidationError",
+    "YouTrackClient",
+    "KdError",
+    "resolve_config",
+]

kd_cli-2.0.4/kd/api/__init__.py

@@ -0,0 +1,15 @@
+"""Low-level API wrappers.
+
+Four API layers, same bearer token:
+- ArticlesAPI: ``/api/articles`` — knowledge base articles
+- TagsAPI: ``/api/tags`` — tags, issue/article tagging
+- YouTrackAPI: ``/api/...`` — projects, issues, fields, time tracking
+- HubAPI: ``/hub/api/rest/...`` — users, groups, project teams, roles
+"""
+
+from kd.api.articles import ArticlesAPI
+from kd.api.hub import HubAPI
+from kd.api.tags import TagsAPI
+from kd.api.youtrack import YouTrackAPI
+
+__all__ = ["ArticlesAPI", "HubAPI", "TagsAPI", "YouTrackAPI"]

kd_cli-2.0.4/kd/api/articles.py

@@ -0,0 +1,232 @@
+"""Articles REST API wrapper.
+
+Covers ``/api/articles`` endpoints:
+- Articles: list (global + project-scoped), get, create, update, delete
+- Child articles: list, attach, detach parent
+- Comments: list, create
+- Attachments: list, get, create, delete
+
+Articles have no ``query`` parameter — filtering is project-scoped only.
+"""
+
+from __future__ import annotations
+
+from kd.api.http import HttpClient
+from kd.models import (
+    Article,
+    ArticleCreate,
+    ArticleUpdate,
+    Attachment,
+    Comment,
+    CommentCreate,
+    FieldSet,
+)
+
+# List fields omit content to keep responses lightweight
+_ARTICLE_LIST_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "created",
+        "updated",
+        "hasChildren",
+        project=FieldSet("id", "name"),
+        reporter=FieldSet("id", "name"),
+        parentArticle=FieldSet("id", "idReadable"),
+    )
+)
+
+# Tag-scan fields include tags for client-side tag filtering.
+# Kept separate from _ARTICLE_LIST_FIELDS so normal article list
+# calls don't pay the tag payload cost.
+_ARTICLE_TAG_SCAN_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "created",
+        "updated",
+        "hasChildren",
+        project=FieldSet("id", "name"),
+        reporter=FieldSet("id", "name"),
+        parentArticle=FieldSet("id", "idReadable"),
+        tags=FieldSet("id", "name"),
+    )
+)
+
+# Detail fields include content for single-article views
+_ARTICLE_DETAIL_FIELDS = str(
+    FieldSet(
+        "id",
+        "idReadable",
+        "summary",
+        "content",
+        "created",
+        "updated",
+        "hasChildren",
+        project=FieldSet("id", "name"),
+        reporter=FieldSet("id", "name"),
+        parentArticle=FieldSet("id", "idReadable"),
+        tags=FieldSet("id", "name"),
+    )
+)
+
+
+_ARTICLE_COMMENT_FIELDS = "id,text,pinned,author(id,login,name),created,updated"
+_ARTICLE_ATTACHMENT_FIELDS = (
+    "id,name,size,mimeType,extension,author(id,login,name),created,updated,url"
+)
+
+
+class ArticlesAPI:
+    """Articles REST API wrapper (/api/articles)."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    # --- List ---
+
+    def list_articles(self, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            "/articles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    def list_project_articles(self, project_id: str, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            f"/admin/projects/{project_id}/articles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    # --- Tag scan (articles with tags for client-side filtering) ---
+
+    def list_articles_with_tags(self, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            "/articles",
+            fields=_ARTICLE_TAG_SCAN_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    def list_project_articles_with_tags(
+        self, project_id: str, top: int = 50, skip: int = 0
+    ) -> list[Article]:
+        data = self._http.get(
+            f"/admin/projects/{project_id}/articles",
+            fields=_ARTICLE_TAG_SCAN_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    # --- Get ---
+
+    def get_article(self, article_id: str) -> Article:
+        data = self._http.get(
+            f"/articles/{article_id}",
+            fields=_ARTICLE_DETAIL_FIELDS,
+        )
+        return Article.model_validate(data)
+
+    # --- Children ---
+
+    def list_child_articles(self, article_id: str, top: int = 50, skip: int = 0) -> list[Article]:
+        data = self._http.get(
+            f"/articles/{article_id}/childArticles",
+            fields=_ARTICLE_LIST_FIELDS,
+            params={"$top": top, "$skip": skip},
+        )
+        return [Article.model_validate(a) for a in data]
+
+    # --- Create / Update / Delete ---
+
+    def create_article(self, article: ArticleCreate) -> Article:
+        data = self._http.post(
+            "/articles",
+            json=article.model_dump(by_alias=True, exclude_none=True),
+            fields=_ARTICLE_DETAIL_FIELDS,
+        )
+        return Article.model_validate(data)
+
+    def update_article(self, article_id: str, update: ArticleUpdate) -> Article:
+        data = self._http.post(
+            f"/articles/{article_id}",
+            json=update.model_dump(by_alias=True, exclude_none=True),
+            fields=_ARTICLE_DETAIL_FIELDS,
+        )
+        return Article.model_validate(data)
+
+    def delete_article(self, article_id: str) -> None:
+        self._http.delete(f"/articles/{article_id}")
+
+    # --- Comments ---
+
+    def list_article_comments(self, article_id: str) -> list[Comment]:
+        data = self._http.get(
+            f"/articles/{article_id}/comments",
+            fields=_ARTICLE_COMMENT_FIELDS,
+        )
+        return [Comment.model_validate(c) for c in data]
+
+    def create_article_comment(self, article_id: str, comment: CommentCreate) -> Comment:
+        data = self._http.post(
+            f"/articles/{article_id}/comments",
+            json=comment.model_dump(exclude_none=True),
+            fields=_ARTICLE_COMMENT_FIELDS,
+        )
+        return Comment.model_validate(data)
+
+    # --- Attachments ---
+
+    def list_article_attachments(self, article_id: str) -> list[Attachment]:
+        data = self._http.get(
+            f"/articles/{article_id}/attachments",
+            fields=_ARTICLE_ATTACHMENT_FIELDS,
+        )
+        return [Attachment.model_validate(a) for a in data]
+
+    def get_article_attachment(self, article_id: str, attachment_id: str) -> Attachment:
+        data = self._http.get(
+            f"/articles/{article_id}/attachments/{attachment_id}",
+            fields=_ARTICLE_ATTACHMENT_FIELDS,
+        )
+        return Attachment.model_validate(data)
+
+    def create_article_attachment(
+        self, article_id: str, file_name: str, file_content: bytes
+    ) -> Attachment:
+        data = self._http.post_file(
+            f"/articles/{article_id}/attachments",
+            file_name=file_name,
+            file_content=file_content,
+            fields=_ARTICLE_ATTACHMENT_FIELDS,
+        )
+        if isinstance(data, list):
+            return Attachment.model_validate(data[0])
+        return Attachment.model_validate(data)
+
+    def delete_article_attachment(self, article_id: str, attachment_id: str) -> None:
+        self._http.delete(f"/articles/{article_id}/attachments/{attachment_id}")
+
+    # --- Hierarchy ---
+
+    def attach_child_article(self, parent_id: str, child_id: str) -> None:
+        """Attach an existing article as a child of another."""
+        self._http.post(
+            f"/articles/{parent_id}/childArticles",
+            json={"id": child_id},
+        )
+
+    def detach_parent_article(self, article_id: str) -> None:
+        """Remove an article's parent (move to project root).
+
+        Uses POST update with parentArticle set to null.
+        """
+        self._http.post(
+            f"/articles/{article_id}",
+            json={"parentArticle": None},
+        )