kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/issue/__init__.py

@@ -0,0 +1,959 @@
+"""Issue namespace: /issue
+
+Commands: list, create, show, update, delete, assign, unassign, assignees, move
+Sub-namespaces: /issue/comment, /issue/link, /issue/attachment
+API layer: YouTrack REST API (/api/issues)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+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,
+    priority_option,
+    project_option,
+    state_option,
+    type_option,
+)
+from kd.cli.input import resolve_text_input
+from kd.exceptions import ValidationError
+from kd.models import Attachment, CustomField, Issue
+
+
+_SEMANTIC_SLOTS = ("type", "priority", "state")
+
+
+def _get_field_aliases(client: Any, project_key: str) -> dict[str, str]:
+    """Extract field aliases for a project from config."""
+    if not client or not hasattr(client, "config") or not client.config:
+        return {}
+    for source in (client.config.local_projects, client.config.global_projects):
+        proj_cfg = source.get(project_key)
+        if isinstance(proj_cfg, dict):
+            aliases = proj_cfg.get("field_aliases")
+            if isinstance(aliases, dict):
+                return {str(k): str(v) for k, v in aliases.items()}
+    return {}
+
+
+def _build_custom_fields(
+    options: dict[str, Any],
+    client: Any = None,
+    project_key: str | None = None,
+) -> list[CustomField] | None:
+    """Build CustomField list from semantic slots and generic ``--field`` pairs.
+
+    Semantic slots (``--type``, ``--priority``, ``--state``) are resolved via
+    field discovery when a client is available, otherwise via hardcoded defaults.
+
+    Generic ``--field NAME=VALUE`` pairs are resolved via fuzzy field discovery
+    (requires client). On field name collision, generic overrides semantic.
+    """
+    slots = {name: options[name] for name in _SEMANTIC_SLOTS if options.get(name)}
+    field_pairs: list[str] = options.get("field", [])
+
+    if not slots and not field_pairs:
+        return None
+
+    semantic_fields: list[CustomField] = []
+    if slots and client and project_key:
+        aliases = _get_field_aliases(client, project_key)
+        semantic_fields = client.issues.resolve_custom_fields(project_key, slots, aliases) or []
+    elif slots:
+        # Fallback: hardcoded defaults (no client available)
+        for cli_name, yt_name in [("type", "Type"), ("priority", "Priority"), ("state", "State")]:
+            value = slots.get(cli_name)
+            if value:
+                semantic_fields.append(
+                    CustomField.model_validate(
+                        {
+                            "name": yt_name,
+                            "value": {"name": value},
+                            "$type": "SingleEnumIssueCustomField",
+                        }
+                    )
+                )
+
+    generic_fields: list[CustomField] = []
+    if field_pairs:
+        if not client or not project_key:
+            raise ValidationError("--field requires a connected client with project context")
+        generic_fields = client.issues.resolve_generic_fields(project_key, field_pairs)
+
+    # Merge: generic overrides semantic on name collision
+    if semantic_fields and generic_fields:
+        generic_names = {f.name for f in generic_fields}
+        merged = [f for f in semantic_fields if f.name not in generic_names]
+        merged.extend(generic_fields)
+        return merged or None
+    return (semantic_fields + generic_fields) or None
+
+
+def _extract_field(issue: Issue, field_name: str) -> str:
+    """Extract a custom field value by name from an issue."""
+    for cf in issue.custom_fields:
+        if cf.name == field_name and cf.value:
+            if isinstance(cf.value, dict):
+                return str(cf.value.get("name", ""))
+            return str(cf.value)
+    return ""
+
+
+# Known field name variants for display columns.
+_STATE_NAMES = {"State", "Stage"}
+_TYPE_NAMES = {"Type"}
+_PRIORITY_NAMES = {"Priority"}
+
+
+def _extract_semantic_field(issue: Issue, candidates: set[str]) -> str:
+    """Extract a custom field value by matching any of the candidate names."""
+    for cf in issue.custom_fields:
+        if cf.name in candidates and cf.value:
+            if isinstance(cf.value, dict):
+                return str(cf.value.get("name", ""))
+            return str(cf.value)
+    return ""
+
+
+def _issue_to_row(issue: Issue) -> dict[str, Any]:
+    """Convert an Issue to a flat dict for table output."""
+    return {
+        "id": issue.id_readable,
+        "summary": issue.summary,
+        "project": issue.project.name if issue.project else "",
+        "type": _extract_semantic_field(issue, _TYPE_NAMES),
+        "priority": _extract_semantic_field(issue, _PRIORITY_NAMES),
+        "state": _extract_semantic_field(issue, _STATE_NAMES),
+    }
+
+
+_RICH_SECTIONS = {"description", "comments", "links", "attachments"}
+
+
+def _issue_to_detail(issue: Issue, sections: set[str] | None = None) -> dict[str, Any]:
+    """Convert an Issue to a detailed dict.
+
+    ``sections`` controls which rich sections to include. When *None*,
+    all available sections are included. Pass an empty set for brief mode.
+    """
+    include = sections if sections is not None else _RICH_SECTIONS
+
+    result: dict[str, Any] = {
+        "id": issue.id_readable,
+        "summary": issue.summary,
+        "project": issue.project.name if issue.project else "",
+        "reporter": issue.reporter.name if issue.reporter else "",
+        "created": issue.created,
+    }
+    for cf in issue.custom_fields:
+        name = cf.name.lower().replace(" ", "_")
+        if cf.value and isinstance(cf.value, dict):
+            result[name] = cf.value.get("name", "")
+        elif cf.value is not None:
+            result[name] = cf.value
+        else:
+            result[name] = ""
+
+    if "description" in include:
+        result["description"] = issue.description or ""
+
+    if "comments" in include and issue.comments is not None:
+        result["comments"] = [
+            {
+                "author": c.author.name if c.author else "",
+                "text": c.text,
+                "created": c.created,
+            }
+            for c in issue.comments[-5:]
+        ]
+
+    if "links" in include and issue.links is not None:
+        rows: list[dict[str, str]] = []
+        for link in issue.links:
+            link_type = link.get("linkType", {}).get("name", "")
+            direction = link.get("direction", "")
+            for linked in link.get("issues", []):
+                rows.append(
+                    {
+                        "type": link_type,
+                        "direction": direction,
+                        "issue": linked.get("idReadable", ""),
+                        "summary": linked.get("summary", ""),
+                    }
+                )
+        if rows:
+            result["links"] = rows
+
+    if "attachments" in include and issue.attachments is not None:
+        result["attachments"] = [
+            {
+                "id": a.id,
+                "name": a.name,
+                "size": a.size,
+            }
+            for a in issue.attachments
+        ]
+
+    return result
+
+
+# --- Issue Commands ---
+
+
+class IssueListCommand(Command):
+    """List issues."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List issues",
+            requires_client=True,
+            usage="kd /issue list [--project P] [--query Q] [--limit N]",
+            examples=[
+                "kd /issue list --project FB",
+                'kd /issue list --query "State: Open"',
+                "kd /issue list --project FB --limit 10",
+            ],
+            see_also=["/issue show", "/issue create"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option())
+        self.register_option(
+            OptionDeclaration(
+                name="query",
+                short_name="q",
+                layer=OptionLayer.COMMAND,
+                help_text="YouTrack search query",
+            )
+        )
+        self.register_option(limit_option())
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        parts: list[str] = []
+        project = options.command.get("project")
+        if project:
+            parts.append(f"project: {project}")
+        query = options.command.get("query")
+        if query:
+            parts.append(query)
+        full_query = " ".join(parts)
+        limit = options.command.get("limit", 50)
+        issues = client.issues.list(query=full_query, top=limit)
+        return [_issue_to_row(i) for i in issues]
+
+
+class IssueCreateCommand(Command):
+    """Create an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "create",
+            "Create an issue",
+            requires_client=True,
+            usage='kd /issue create "Summary" --project P [--field NAME=VALUE] [--attach FILE]',
+            long_description="Summary is the issue title. --project is the project key (e.g. FB).",
+            examples=[
+                'kd /issue create "Fix router config" --project FB --type Task',
+                'kd /issue create "Bug report" -p FB --attach screenshot.png --attach log.txt',
+                'kd /issue create "Sprint task" -p FB --field "Sprint=Sprint 47"',
+                'kd /issue create "Design doc" -p FB --description @design.md',
+            ],
+            see_also=["/issue list", "/issue show", "/issue/attachment add", "/project/field list"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(required=True))
+        self.register_option(
+            OptionDeclaration(
+                name="description",
+                short_name="d",
+                layer=OptionLayer.COMMAND,
+                help_text="Issue description (Markdown). Use @file.md to read from file, or @- / - for stdin",
+            )
+        )
+        self.register_option(type_option())
+        self.register_option(priority_option())
+        self.register_option(state_option())
+        self.register_option(
+            OptionDeclaration(
+                name="field",
+                short_name="F",
+                layer=OptionLayer.COMMAND,
+                is_list=True,
+                help_text="Custom field as NAME=VALUE (repeatable)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="attach",
+                short_name="a",
+                layer=OptionLayer.COMMAND,
+                is_list=True,
+                help_text="File to attach (repeatable)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError('Usage: kd /issue create "Summary" --project P')
+        project_key = options.command["project"]
+        summary = " ".join(args)
+        description = resolve_text_input(options.command.get("description"))
+        custom_fields = _build_custom_fields(
+            options.command, client=client, project_key=project_key
+        )
+        attach_paths = options.command.get("attach", [])
+        file_paths = [Path(p) for p in attach_paths] if attach_paths else None
+
+        if file_paths:
+            issue = client.create_issue_with_attachments(
+                project=project_key,
+                summary=summary,
+                description=description,
+                custom_fields=custom_fields,
+                file_paths=file_paths,
+            )
+        else:
+            issue = client.issues.create(
+                project=project_key,
+                summary=summary,
+                description=description,
+                custom_fields=custom_fields,
+            )
+        return _issue_to_detail(issue)
+
+
+class IssueShowCommand(Command):
+    """Show issue details."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show issue details",
+            requires_client=True,
+            usage="kd /issue show ID [--brief|--rich] [--with S] [--without S]",
+            examples=[
+                "kd /issue show FB-42",
+                "kd /issue show FB-42 --brief",
+                "kd /issue show FB-42 --with comments,attachments",
+                "kd /issue show FB-42 --without comments",
+            ],
+            see_also=["/issue list", "/issue update"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="brief",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Show minimal view (header + custom fields only)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="rich",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Show expanded view with all sections (default)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="with",
+                layer=OptionLayer.COMMAND,
+                help_text="Comma-separated sections to include: description,comments,links,attachments",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="without",
+                layer=OptionLayer.COMMAND,
+                help_text="Comma-separated sections to exclude",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue show ID")
+        is_brief = options.command.get("brief", False)
+        with_opt = options.command.get("with")
+        without_opt = options.command.get("without")
+
+        # Determine detail level for API call
+        detail = "brief" if is_brief and not with_opt else "rich"
+        issue = client.issues.get(args[0], detail=detail)
+
+        # Determine sections to render
+        if is_brief:
+            sections: set[str] = set()
+        else:
+            sections = set(_RICH_SECTIONS)
+
+        if with_opt:
+            for s in with_opt.split(","):
+                s = s.strip()
+                if s in _RICH_SECTIONS:
+                    sections.add(s)
+        if without_opt:
+            for s in without_opt.split(","):
+                s = s.strip()
+                sections.discard(s)
+
+        return _issue_to_detail(issue, sections=sections)
+
+
+class IssueUpdateCommand(Command):
+    """Update an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "update",
+            "Update an issue",
+            requires_client=True,
+            usage="kd /issue update ID [--title T] [--field NAME=VALUE]",
+            examples=[
+                'kd /issue update FB-42 --title "New title"',
+                "kd /issue update FB-42 --state Open --priority Critical",
+                'kd /issue update FB-42 --field "Sprint=Sprint 48"',
+                "kd /issue update FB-42 --description @updated.md",
+            ],
+            see_also=["/issue show", "/project/field list"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="title",
+                short_name="s",
+                layer=OptionLayer.COMMAND,
+                help_text="Issue title",
+                aliases=["summary"],
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="description",
+                short_name="d",
+                layer=OptionLayer.COMMAND,
+                help_text="New description (Markdown). Use @file.md to read from file, or @- / - for stdin",
+            )
+        )
+        self.register_option(type_option())
+        self.register_option(priority_option())
+        self.register_option(state_option())
+        self.register_option(
+            OptionDeclaration(
+                name="field",
+                short_name="F",
+                layer=OptionLayer.COMMAND,
+                is_list=True,
+                help_text="Custom field as NAME=VALUE (repeatable)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue update ID [--title T] ...")
+        issue_id = args[0]
+        # Extract project key from issue ID (e.g., "FB-42" -> "FB")
+        project_key = issue_id.rsplit("-", 1)[0] if "-" in issue_id else None
+        title = options.command.get("title")
+        description = resolve_text_input(options.command.get("description"))
+        custom_fields = _build_custom_fields(
+            options.command, client=client, project_key=project_key
+        )
+        if not title and not description and not custom_fields:
+            raise ValidationError("At least one field must be specified for update")
+        issue = client.issues.update(
+            issue_id,
+            summary=title,
+            description=description,
+            custom_fields=custom_fields,
+        )
+        return _issue_to_detail(issue)
+
+
+class IssueDeleteCommand(Command):
+    """Delete an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete an issue",
+            requires_client=True,
+            usage="kd /issue delete ID",
+            examples=["kd /issue delete FB-42"],
+            see_also=["/issue list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue delete ID")
+        issue_id = args[0]
+        client.issues.delete(issue_id)
+        return {"ok": True, "action": "delete", "issue": issue_id}
+
+
+# --- Comment Sub-namespace ---
+
+
+class CommentListCommand(Command):
+    """List comments on an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List comments on an issue",
+            requires_client=True,
+            usage="kd /issue/comment list ID",
+            examples=["kd /issue/comment list FB-42"],
+            see_also=["/issue/comment add", "/issue show"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue/comment list ID")
+        comments = client.issues.list_comments(args[0])
+        return [
+            {
+                "id": c.id,
+                "author": c.author.name if c.author else "",
+                "text": c.text,
+                "created": c.created,
+            }
+            for c in comments
+        ]
+
+
+class CommentAddCommand(Command):
+    """Add a comment to an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Add a comment to an issue",
+            requires_client=True,
+            usage='kd /issue/comment add ID "Text"',
+            examples=[
+                'kd /issue/comment add FB-42 "Fixed in latest build"',
+                "kd /issue/comment add FB-42 @comment.md",
+                "echo 'Done' | kd /issue/comment add FB-42 @-",
+            ],
+            see_also=["/issue/comment list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError('Usage: kd /issue/comment add ID "Text"')
+        issue_id = args[0]
+        text = resolve_text_input(" ".join(args[1:]))
+        comment = client.issues.add_comment(issue_id, text)
+        return {
+            "id": comment.id,
+            "author": comment.author.name if comment.author else "",
+            "text": comment.text,
+        }
+
+
+# --- Link Sub-namespace ---
+
+
+class LinkListCommand(Command):
+    """List links on an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List links on an issue",
+            requires_client=True,
+            usage="kd /issue/link list ID",
+            examples=["kd /issue/link list FB-42"],
+            see_also=["/issue/link add"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue/link list ID")
+        links = client.issues.list_links(args[0])
+        rows: list[dict[str, Any]] = []
+        for link in links:
+            link_type = link.get("linkType", {}).get("name", "")
+            direction = link.get("direction", "")
+            for issue in link.get("issues", []):
+                rows.append(
+                    {
+                        "type": link_type,
+                        "direction": direction,
+                        "issue": issue.get("idReadable", ""),
+                        "summary": issue.get("summary", ""),
+                    }
+                )
+        return rows
+
+
+class LinkAddCommand(Command):
+    """Link two issues."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Link two issues",
+            requires_client=True,
+            usage="kd /issue/link add ID TYPE TARGET",
+            long_description="TYPE is one of: subtask-of, parent-for, depends-on, "
+            "required-for, duplicates, duplicated-by, relates-to.",
+            examples=[
+                "kd /issue/link add FB-42 subtask-of FB-1",
+                "kd /issue/link add FB-42 relates-to FB-43",
+            ],
+            see_also=["/issue/link list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 3:
+            raise ValidationError("Usage: kd /issue/link add ID TYPE TARGET")
+        issue_id = args[0]
+        link_type = args[1]
+        target_id = args[2]
+        client.issues.link(issue_id, link_type, target_id)
+        return {
+            "ok": True,
+            "action": "link",
+            "issue": issue_id,
+            "type": link_type,
+            "target": target_id,
+        }
+
+
+# --- Assign / Unassign / Move ---
+
+
+class IssueAssignCommand(Command):
+    """Assign an issue to a user."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "assign",
+            "Assign an issue to a user",
+            requires_client=True,
+            usage="kd /issue assign ID USER",
+            long_description="USER can be a login, email, display name, or 'me'.",
+            examples=[
+                "kd /issue assign FB-42 alice",
+                "kd /issue assign FB-42 me",
+            ],
+            see_also=["/issue unassign", "/issue assignees"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /issue assign ID USER")
+        user = client.issues.assign(args[0], args[1])
+        return {"ok": True, "action": "assign", "issue": args[0], "assignee": user.login}
+
+
+class IssueUnassignCommand(Command):
+    """Remove the assignee from an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "unassign",
+            "Remove the assignee from an issue",
+            requires_client=True,
+            usage="kd /issue unassign ID",
+            examples=["kd /issue unassign FB-42"],
+            see_also=["/issue assign"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue unassign ID")
+        client.issues.unassign(args[0])
+        return {"ok": True, "action": "unassign", "issue": args[0]}
+
+
+class IssueAssigneesCommand(Command):
+    """List users that can be assigned."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "assignees",
+            "List users that can be assigned",
+            requires_client=True,
+            usage="kd /issue assignees [--match QUERY]",
+            examples=[
+                "kd /issue assignees",
+                "kd /issue assignees --match alice",
+            ],
+            see_also=["/issue assign"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="match",
+                short_name="m",
+                layer=OptionLayer.COMMAND,
+                help_text="Filter users by name or login",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        query = options.command.get("match", "")
+        users = client.issues.list_assignees(query=query)
+        return [
+            {
+                "login": u.login,
+                "name": u.name,
+                "email": u.email or "",
+            }
+            for u in users
+        ]
+
+
+class IssueMoveCommand(Command):
+    """Move an issue to another project."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "move",
+            "Move an issue to another project",
+            requires_client=True,
+            usage="kd /issue move ID TARGET_PROJECT",
+            examples=["kd /issue move FB-42 BACKEND"],
+            see_also=["/issue show"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /issue move ID TARGET_PROJECT")
+        client.issues.move(args[0], args[1])
+        return {"ok": True, "action": "move", "issue": args[0], "project": args[1]}
+
+
+# --- Attachment Sub-namespace ---
+
+
+def _attachment_to_row(a: Attachment) -> dict[str, Any]:
+    """Convert an Attachment to a flat dict for table output."""
+    return {
+        "id": a.id,
+        "name": a.name,
+        "size": a.size,
+        "mime_type": a.mime_type or "",
+        "author": a.author.name if a.author else "",
+        "created": a.created,
+    }
+
+
+class AttachmentListCommand(Command):
+    """List attachments on an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List attachments on an issue",
+            requires_client=True,
+            usage="kd /issue/attachment list ID",
+            examples=["kd /issue/attachment list FB-42"],
+            see_also=["/issue/attachment add", "/issue/attachment download"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /issue/attachment list ID")
+        attachments = client.attachments.list(args[0])
+        return [_attachment_to_row(a) for a in attachments]
+
+
+class AttachmentAddCommand(Command):
+    """Add attachments to an issue."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Add attachments to an issue",
+            requires_client=True,
+            usage="kd /issue/attachment add ID FILE [FILE...]",
+            examples=[
+                "kd /issue/attachment add FB-42 screenshot.png",
+                "kd /issue/attachment add FB-42 log.txt report.pdf",
+            ],
+            see_also=["/issue/attachment list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /issue/attachment add ID FILE [FILE...]")
+        issue_id = args[0]
+        file_paths = [Path(p) for p in args[1:]]
+        attachments = client.attachments.add(issue_id, file_paths)
+        return [_attachment_to_row(a) for a in attachments]
+
+
+class AttachmentShowCommand(Command):
+    """Show attachment metadata."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show attachment metadata",
+            requires_client=True,
+            usage="kd /issue/attachment show ISSUE_ID ATTACHMENT_ID",
+            examples=["kd /issue/attachment show FB-42 att-1"],
+            see_also=["/issue/attachment list", "/issue/attachment download"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /issue/attachment show ISSUE_ID ATTACHMENT_ID")
+        a = client.attachments.get(args[0], args[1])
+        return {
+            "id": a.id,
+            "name": a.name,
+            "size": a.size,
+            "mime_type": a.mime_type or "",
+            "author": a.author.name if a.author else "",
+            "created": a.created,
+            "url": a.url or "",
+        }
+
+
+class AttachmentDownloadCommand(Command):
+    """Download an attachment."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "download",
+            "Download an attachment",
+            requires_client=True,
+            usage="kd /issue/attachment download ISSUE_ID ATTACHMENT_ID [--to DIR]",
+            examples=[
+                "kd /issue/attachment download FB-42 att-1",
+                "kd /issue/attachment download FB-42 att-1 --to ./artifacts",
+            ],
+            see_also=["/issue/attachment list", "/issue/attachment show"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="to",
+                layer=OptionLayer.COMMAND,
+                help_text="Target directory for download (default: current directory)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /issue/attachment download ISSUE_ID ATTACHMENT_ID")
+        target_dir = None
+        to_value = options.command.get("to")
+        if to_value:
+            target_dir = Path(to_value)
+        dest = client.attachments.download(args[0], args[1], target_dir=target_dir)
+        return {"ok": True, "action": "download", "issue": args[0], "path": str(dest)}
+
+
+class AttachmentDeleteCommand(Command):
+    """Delete an attachment."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete an attachment",
+            requires_client=True,
+            usage="kd /issue/attachment delete ISSUE_ID ATTACHMENT_ID",
+            examples=["kd /issue/attachment delete FB-42 att-1"],
+            see_also=["/issue/attachment list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /issue/attachment delete ISSUE_ID ATTACHMENT_ID")
+        client.attachments.delete(args[0], args[1])
+        return {"ok": True, "action": "delete", "issue": args[0], "attachment": args[1]}
+
+
+# --- Namespace Factory ---
+
+
+def create_issue_namespace() -> Namespace:
+    """Build the /issue namespace tree."""
+    ns = Namespace("issue", "Issue management", path="issue")
+    ns.register_command("list", IssueListCommand())
+    ns.register_command("create", IssueCreateCommand())
+    ns.register_command("show", IssueShowCommand())
+    ns.register_command("update", IssueUpdateCommand())
+    ns.register_command("delete", IssueDeleteCommand())
+    ns.register_command("assign", IssueAssignCommand())
+    ns.register_command("unassign", IssueUnassignCommand())
+    ns.register_command("assignees", IssueAssigneesCommand())
+    ns.register_command("move", IssueMoveCommand())
+
+    comment_ns = Namespace("comment", "Issue comments", path="issue/comment")
+    comment_ns.register_command("list", CommentListCommand())
+    comment_ns.register_command("add", CommentAddCommand())
+    ns.register_sub_namespace(comment_ns)
+
+    link_ns = Namespace("link", "Issue links", path="issue/link")
+    link_ns.register_command("list", LinkListCommand())
+    link_ns.register_command("add", LinkAddCommand())
+    ns.register_sub_namespace(link_ns)
+
+    attachment_ns = Namespace("attachment", "Issue attachments", path="issue/attachment")
+    attachment_ns.register_command("list", AttachmentListCommand())
+    attachment_ns.register_command("add", AttachmentAddCommand())
+    attachment_ns.register_command("show", AttachmentShowCommand())
+    attachment_ns.register_command("download", AttachmentDownloadCommand())
+    attachment_ns.register_command("delete", AttachmentDeleteCommand())
+    ns.register_sub_namespace(attachment_ns)
+
+    return ns