kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/tag/__init__.py

@@ -0,0 +1,337 @@
+"""Tag namespace: /tag
+
+Commands: list, show, create, rename, delete, add, remove, issues, articles
+API layer: YouTrack REST API (/api/tags, /api/issues/*/tags, /api/articles/*/tags)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.namespaces import Namespace
+from kd.cli.core.option_registry import (
+    OptionDeclaration,
+    OptionLayer,
+    ResolvedOptions,
+    limit_option,
+    project_option,
+)
+from kd.exceptions import ValidationError
+from kd.models import Article, Issue, Tag
+
+
+def _tag_to_row(tag: Tag) -> dict[str, Any]:
+    """Convert a Tag to a flat dict for table output."""
+    return {
+        "name": tag.name,
+        "owner": tag.owner.name if tag.owner else "",
+        "color": tag.color.id if tag.color else "",
+        "untag_on_resolve": tag.untag_on_resolve,
+    }
+
+
+def _tag_to_detail(tag: Tag) -> dict[str, Any]:
+    """Convert a Tag to a detailed dict for show output."""
+    result: dict[str, Any] = {
+        "name": tag.name,
+        "owner": tag.owner.name if tag.owner else "",
+        "untag_on_resolve": tag.untag_on_resolve,
+    }
+    if tag.color:
+        result["color"] = tag.color.id
+        if tag.color.background:
+            result["background"] = tag.color.background
+        if tag.color.foreground:
+            result["foreground"] = tag.color.foreground
+    return result
+
+
+def _issue_to_row(issue: Issue) -> dict[str, Any]:
+    """Convert a tagged Issue to a flat dict for table output."""
+    return {
+        "id": issue.id_readable,
+        "summary": issue.summary,
+        "project": issue.project.name if issue.project else "",
+    }
+
+
+def _article_to_row(article: Article) -> dict[str, Any]:
+    """Convert a tagged Article to a flat dict for table output."""
+    return {
+        "id": article.id_readable,
+        "summary": article.summary,
+        "project": article.project.name if article.project else "",
+    }
+
+
+# --- Tag Commands ---
+
+
+class TagListCommand(Command):
+    """List all tags."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List tags",
+            requires_client=True,
+            usage="kd /tag list [--limit N]",
+            examples=["kd /tag list", "kd /tag list --limit 100"],
+            see_also=["/tag show"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(limit_option())
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        limit = options.command.get("limit", 50)
+        tags = client.tags.list(top=limit)
+        return [_tag_to_row(t) for t in tags]
+
+
+class TagShowCommand(Command):
+    """Show tag details."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show tag details",
+            requires_client=True,
+            usage="kd /tag show TAG_NAME",
+            examples=["kd /tag show sprint-47"],
+            see_also=["/tag list", "/tag issues"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /tag show TAG_NAME")
+        tag = client.tags.get(args[0])
+        return _tag_to_detail(tag)
+
+
+class TagCreateCommand(Command):
+    """Create a tag."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "create",
+            "Create a tag",
+            requires_client=True,
+            usage="kd /tag create TAG_NAME",
+            examples=['kd /tag create "sprint-47"'],
+            see_also=["/tag list", "/tag delete"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /tag create TAG_NAME")
+        tag = client.tags.create(args[0])
+        return _tag_to_detail(tag)
+
+
+class TagRenameCommand(Command):
+    """Rename a tag."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "rename",
+            "Rename a tag",
+            requires_client=True,
+            usage="kd /tag rename TAG_NAME NEW_NAME",
+            examples=['kd /tag rename sprint-47 "sprint-48"'],
+            see_also=["/tag show"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /tag rename TAG_NAME NEW_NAME")
+        tag = client.tags.rename(args[0], args[1])
+        return _tag_to_detail(tag)
+
+
+class TagDeleteCommand(Command):
+    """Delete a tag."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete a tag",
+            requires_client=True,
+            usage="kd /tag delete TAG_NAME",
+            examples=["kd /tag delete sprint-47"],
+            see_also=["/tag list", "/tag create"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /tag delete TAG_NAME")
+        name = args[0]
+        client.tags.delete(name)
+        return {"ok": True, "action": "delete", "tag": name}
+
+
+class TagAddCommand(Command):
+    """Add a tag to an issue or article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Tag an issue or article",
+            requires_client=True,
+            usage="kd /tag add ENTITY_ID TAG_NAME",
+            long_description=(
+                "Entity type is auto-detected from the ID format: FB-123 = issue, FB-A-1 = article."
+            ),
+            examples=[
+                "kd /tag add FB-123 sprint-47",
+                "kd /tag add FB-A-1 reviewed",
+            ],
+            see_also=["/tag remove", "/tag issues"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /tag add ENTITY_ID TAG_NAME")
+        entity_id, tag_name = args[0], args[1]
+        client.tags.add(entity_id, tag_name)
+        return {"ok": True, "action": "add", "entity": entity_id, "tag": tag_name}
+
+
+class TagRemoveCommand(Command):
+    """Remove a tag from an issue or article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "remove",
+            "Untag an issue or article",
+            requires_client=True,
+            usage="kd /tag remove ENTITY_ID TAG_NAME",
+            long_description=(
+                "Entity type is auto-detected from the ID format: FB-123 = issue, FB-A-1 = article."
+            ),
+            examples=[
+                "kd /tag remove FB-123 sprint-47",
+                "kd /tag remove FB-A-1 reviewed",
+            ],
+            see_also=["/tag add", "/tag issues"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /tag remove ENTITY_ID TAG_NAME")
+        entity_id, tag_name = args[0], args[1]
+        client.tags.remove(entity_id, tag_name)
+        return {"ok": True, "action": "remove", "entity": entity_id, "tag": tag_name}
+
+
+class TagIssuesCommand(Command):
+    """List issues tagged with a specific tag."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "issues",
+            "List issues with a tag",
+            requires_client=True,
+            usage="kd /tag issues TAG_NAME [--limit N]",
+            long_description=(
+                "Lists issues tagged with the given tag using the server-side tag-issues endpoint."
+            ),
+            examples=["kd /tag issues sprint-47", "kd /tag issues blocked --limit 100"],
+            see_also=["/tag show", "/tag add", "/tag articles"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(limit_option())
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /tag issues TAG_NAME")
+        limit = options.command.get("limit", 50)
+        issues = client.tags.issues(args[0], top=limit)
+        return [_issue_to_row(i) for i in issues]
+
+
+class TagArticlesCommand(Command):
+    """List articles tagged with a specific tag (or intersection of tags)."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "articles",
+            "List articles with a tag",
+            requires_client=True,
+            usage="kd /tag articles TAG_NAME [--tag TAG ...] [--project P] [--limit N]",
+            long_description=(
+                "Lists articles tagged with the given tag. Uses client-side "
+                "filtering because the YouTrack API has no server-side "
+                "article-by-tag endpoint. Use --project to scope the scan "
+                "to a single project. Repeat --tag to require multiple tags "
+                "(AND semantics)."
+            ),
+            examples=[
+                "kd /tag articles reviewed",
+                'kd /tag articles "type:guide" --project FB',
+                "kd /tag articles type:case --tag component:authservice -p CMCSA",
+                "kd /tag articles blocked --limit 100",
+            ],
+            see_also=["/tag issues", "/tag show", "/tag add"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="tag",
+                short_name="t",
+                layer=OptionLayer.COMMAND,
+                is_list=True,
+                help_text="Additional tag filter (repeatable, AND semantics)",
+            )
+        )
+        self.register_option(project_option(help_text="Scope scan to a project"))
+        self.register_option(limit_option())
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /tag articles TAG_NAME")
+        extra_tags: list[str] = options.command.get("tag", [])
+        tags = [args[0], *extra_tags]
+        limit = options.command.get("limit", 50)
+        project = options.command.get("project")
+        articles = client.tags.articles(tags, project=project, top=limit)
+        return [_article_to_row(a) for a in articles]
+
+
+# --- Namespace Factory ---
+
+
+def create_tag_namespace() -> Namespace:
+    """Build the /tag namespace."""
+    ns = Namespace("tag", "Tag management and entity tagging", path="tag")
+    ns.register_command("list", TagListCommand())
+    ns.register_command("show", TagShowCommand())
+    ns.register_command("create", TagCreateCommand())
+    ns.register_command("rename", TagRenameCommand())
+    ns.register_command("delete", TagDeleteCommand())
+    ns.register_command("add", TagAddCommand())
+    ns.register_command("remove", TagRemoveCommand())
+    ns.register_command("issues", TagIssuesCommand())
+    ns.register_command("articles", TagArticlesCommand())
+    return ns

kd/cli/namespaces/time/__init__.py

@@ -0,0 +1,307 @@
+"""Time namespace: /time
+
+Commands: list, log, update, delete
+API layer: YouTrack REST API (/api/issues/{id}/timeTracking/workItems)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.namespaces import Namespace
+from kd.cli.core.option_registry import OptionDeclaration, OptionLayer, ResolvedOptions
+from kd.exceptions import ValidationError
+
+_MS_PER_DAY = 86_400_000
+
+
+def _parse_date(raw: str) -> int:
+    """Parse ``YYYY-MM-DD`` into epoch-ms at UTC midnight."""
+    try:
+        d = datetime.strptime(raw, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+    except ValueError:
+        raise ValidationError(f"Invalid date '{raw}'. Expected YYYY-MM-DD.") from None
+    return int(d.timestamp() * 1000)
+
+
+def _work_item_to_dict(w: Any) -> dict[str, Any]:
+    return {
+        "id": w.id,
+        "minutes": w.duration.minutes if w.duration else 0,
+        "type": w.type.name if w.type else "",
+        "author": w.author.name if w.author else "",
+        "text": w.text or "",
+        "date": w.date,
+    }
+
+
+class TimeListCommand(Command):
+    """List work items on an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List work items on an issue",
+            requires_client=True,
+            usage="kd /time list ISSUE_ID [--date DATE] [--from DATE --to DATE]",
+            examples=[
+                "kd /time list FB-42",
+                "kd /time list FB-42 --date 2025-12-31",
+                "kd /time list FB-42 --from 2025-12-01 --to 2025-12-31",
+            ],
+            see_also=["/time log", "/time update", "/time delete"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="date",
+                layer=OptionLayer.COMMAND,
+                help_text="Filter to a single date (YYYY-MM-DD)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="from",
+                layer=OptionLayer.COMMAND,
+                help_text="Start of date range (YYYY-MM-DD, inclusive)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="to",
+                layer=OptionLayer.COMMAND,
+                help_text="End of date range (YYYY-MM-DD, inclusive)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /time list ISSUE_ID")
+        date_opt = options.command.get("date")
+        from_opt = options.command.get("from")
+        to_opt = options.command.get("to")
+
+        if date_opt and (from_opt or to_opt):
+            raise ValidationError("--date is mutually exclusive with --from/--to")
+        if (from_opt and not to_opt) or (to_opt and not from_opt):
+            raise ValidationError("--from and --to must be supplied together")
+
+        date_from: int | None = None
+        date_to: int | None = None
+        if date_opt:
+            day = _parse_date(date_opt)
+            date_from = day
+            date_to = day + _MS_PER_DAY - 1
+        elif from_opt and to_opt:
+            date_from = _parse_date(from_opt)
+            date_to = _parse_date(to_opt) + _MS_PER_DAY - 1
+            if date_from > date_to:
+                raise ValidationError("--from must not be later than --to")
+
+        items = client.time.list(args[0], date_from=date_from, date_to=date_to)
+        return [_work_item_to_dict(w) for w in items]
+
+
+class TimeLogCommand(Command):
+    """Log work on an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "log",
+            "Log work on an issue",
+            requires_client=True,
+            usage=(
+                "kd /time log ISSUE_ID MINUTES [--date DATE] [--type TYPE] [--description DESC]"
+            ),
+            examples=[
+                "kd /time log FB-42 30",
+                'kd /time log FB-42 60 --type Development --description "SDK work"',
+                "kd /time log FB-42 90 --date 2025-12-31 --type Development",
+            ],
+            see_also=["/time list", "/time update", "/time delete"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="type",
+                short_name="t",
+                layer=OptionLayer.COMMAND,
+                help_text="Work item type (Development, Testing, etc.)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="description",
+                short_name="d",
+                layer=OptionLayer.COMMAND,
+                help_text="Work item description",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="date",
+                layer=OptionLayer.COMMAND,
+                help_text="Work date (YYYY-MM-DD, defaults to today)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /time log ISSUE_ID MINUTES")
+        issue_id = args[0]
+        try:
+            minutes = int(args[1])
+        except ValueError:
+            raise ValidationError(f"MINUTES must be a number, got '{args[1]}'") from None
+        work_type = options.command.get("type")
+        description = options.command.get("description")
+        date_raw = options.command.get("date")
+        date_ms = _parse_date(date_raw) if date_raw else None
+        item = client.time.log(
+            issue_id,
+            minutes,
+            work_type=work_type,
+            description=description,
+            date=date_ms,
+        )
+        return {
+            "id": item.id,
+            "minutes": item.duration.minutes if item.duration else 0,
+            "type": item.type.name if item.type else "",
+            "date": item.date,
+        }
+
+
+class TimeUpdateCommand(Command):
+    """Update a work item."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "update",
+            "Update an existing work item",
+            requires_client=True,
+            usage=(
+                "kd /time update ISSUE_ID WORK_ITEM_ID "
+                "[--minutes M] [--date DATE] [--type TYPE] [--description DESC]"
+            ),
+            examples=[
+                "kd /time update FB-42 199-54 --minutes 45",
+                'kd /time update FB-42 199-54 --date 2026-01-02 --description "updated"',
+            ],
+            see_also=["/time log", "/time list", "/time delete"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="minutes",
+                short_name="m",
+                layer=OptionLayer.COMMAND,
+                help_text="New duration in minutes",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="date",
+                layer=OptionLayer.COMMAND,
+                help_text="New work date (YYYY-MM-DD)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="type",
+                short_name="t",
+                layer=OptionLayer.COMMAND,
+                help_text="New work item type",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="description",
+                short_name="d",
+                layer=OptionLayer.COMMAND,
+                help_text="New description",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /time update ISSUE_ID WORK_ITEM_ID")
+        issue_id = args[0]
+        work_item_id = args[1]
+
+        minutes_raw = options.command.get("minutes")
+        date_raw = options.command.get("date")
+        work_type = options.command.get("type")
+        description = options.command.get("description")
+
+        if minutes_raw is None and date_raw is None and work_type is None and description is None:
+            raise ValidationError(
+                "Provide at least one of --minutes, --date, --type, --description"
+            )
+
+        minutes: int | None = None
+        if minutes_raw is not None:
+            try:
+                minutes = int(minutes_raw)
+            except ValueError:
+                raise ValidationError(f"--minutes must be a number, got '{minutes_raw}'") from None
+
+        date_ms = _parse_date(date_raw) if date_raw else None
+
+        item = client.time.update(
+            issue_id,
+            work_item_id,
+            minutes=minutes,
+            work_type=work_type,
+            description=description,
+            date=date_ms,
+        )
+        return _work_item_to_dict(item)
+
+
+class TimeDeleteCommand(Command):
+    """Delete a work item."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete a work item",
+            requires_client=True,
+            usage="kd /time delete ISSUE_ID WORK_ITEM_ID",
+            examples=["kd /time delete FB-42 199-54"],
+            see_also=["/time list", "/time log", "/time update"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /time delete ISSUE_ID WORK_ITEM_ID")
+        client.time.delete(args[0], args[1])
+        return {
+            "ok": True,
+            "action": "delete",
+            "issue": args[0],
+            "work_item": args[1],
+        }
+
+
+def create_time_namespace() -> Namespace:
+    """Build the /time namespace tree."""
+    ns = Namespace("time", "Time tracking", path="time")
+    ns.register_command("list", TimeListCommand())
+    ns.register_command("log", TimeLogCommand())
+    ns.register_command("update", TimeUpdateCommand())
+    ns.register_command("delete", TimeDeleteCommand())
+    return ns