kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/article/__init__.py

@@ -0,0 +1,843 @@
+"""Article namespace: /article
+
+Commands: list, show, children, create, update, delete, tree, move
+Sub-namespaces: /article/comment (list, add), /article/attachment (list, add, show, download, delete)
+API layer: YouTrack REST API (/api/articles)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+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.cli.input import resolve_text_input
+from kd.cli.tree import TreeNode
+from kd.exceptions import ValidationError
+from kd.models import Article, Attachment
+
+
+def _parent_label(article: Article) -> str:
+    """Render an article's parent for display, preferring readable id."""
+    parent = article.parent_article
+    if parent is None:
+        return ""
+    return parent.id_readable or parent.name or ""
+
+
+def _article_to_row(article: Article) -> dict[str, Any]:
+    """Convert an Article to a flat dict for table output."""
+    return {
+        "id": article.id_readable,
+        "summary": article.summary,
+        "project": article.project.name if article.project else "",
+        "reporter": article.reporter.name if article.reporter else "",
+        "parent": _parent_label(article),
+        "created": article.created,
+        "updated": article.updated,
+        "children": article.has_children,
+    }
+
+
+def _article_to_detail(article: Article) -> dict[str, Any]:
+    """Convert an Article to a detailed dict for show output."""
+    result: dict[str, Any] = {
+        "id": article.id_readable,
+        "summary": article.summary,
+        "project": article.project.name if article.project else "",
+        "reporter": article.reporter.name if article.reporter else "",
+        "created": article.created,
+        "updated": article.updated,
+        "has_children": article.has_children,
+        "tags": ", ".join(t.name for t in article.tags),
+    }
+    if article.parent_article:
+        result["parent"] = _parent_label(article)
+    if article.content is not None:
+        result["content"] = article.content
+    return result
+
+
+# --- Article Commands ---
+
+
+class ArticleListCommand(Command):
+    """List articles."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List articles",
+            requires_client=True,
+            usage="kd /article list [--project P] [--parent ID] [--limit N]",
+            long_description=(
+                "Articles do not support search queries. Use --project to filter "
+                "by project, or --parent ARTICLE_ID to list direct children of "
+                "another article. When --parent is given, --project is ignored "
+                "because child listing is already scoped to the parent's project."
+            ),
+            examples=[
+                "kd /article list --project FB",
+                "kd /article list --project FB --limit 10",
+                "kd /article list --parent FB-A-1",
+            ],
+            see_also=["/article show", "/article children"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option())
+        self.register_option(
+            OptionDeclaration(
+                name="parent",
+                layer=OptionLayer.COMMAND,
+                help_text="List direct children of this article id",
+            )
+        )
+        self.register_option(limit_option())
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        project = options.command.get("project")
+        parent = options.command.get("parent")
+        limit = options.command.get("limit", 50)
+        if parent:
+            articles = client.articles.children(parent, top=limit)
+        else:
+            articles = client.articles.list(project=project, top=limit)
+        return [_article_to_row(a) for a in articles]
+
+
+class ArticleShowCommand(Command):
+    """Show article details."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show article details",
+            requires_client=True,
+            usage="kd /article show ARTICLE_ID",
+            examples=["kd /article show FB-A-1"],
+            see_also=["/article list", "/article children", "/article pull"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article show ARTICLE_ID")
+        article = client.articles.get(args[0])
+        return _article_to_detail(article)
+
+
+class ArticlePullCommand(Command):
+    """Write raw article content to stdout."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "pull",
+            "Write raw article content to stdout",
+            requires_client=True,
+            usage="kd /article pull ARTICLE_ID",
+            long_description=(
+                "Writes the article's raw markdown content to stdout with no "
+                "framing, headers, or metadata. Use for scripting, backups, "
+                "and file→YouTrack migration round-trips. The --output flag "
+                "has no effect; pull is intentionally format-agnostic."
+            ),
+            examples=[
+                "kd /article pull FB-A-1",
+                "kd /article pull FB-A-1 > setup.md",
+            ],
+            see_also=["/article show", "/article list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article pull ARTICLE_ID")
+        content: str | None = client.articles.pull(args[0])
+        if content is None:
+            raise ValidationError(f"Article {args[0]} has no content")
+        return content
+
+
+class ArticlePushCommand(Command):
+    """Idempotent upsert of a local markdown file as a YouTrack article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "push",
+            "Idempotently upsert a markdown file as an article",
+            requires_client=True,
+            usage=(
+                "kd /article push FILE --project P --title T "
+                "[--slug S] [--parent ID] [--tag T] [--force] [--dry-run]"
+            ),
+            long_description=(
+                "Push a local markdown file to YouTrack as a knowledge base "
+                "article. The file carries its own identity in an HTML comment "
+                "marker block at the top (<!-- kd-meta ... -->). On first push, "
+                "a marker is synthesized and the local file is rewritten to "
+                "include it. On subsequent pushes, the marker routes the update "
+                "to the same article. "
+                "IMPORTANT: push rewrites the local file on success to refresh "
+                "the marker — treat the file as owned by push after the first "
+                "run, like Cargo.lock. "
+                "Refuses to overwrite a remotely-edited article unless --force "
+                "is passed. --dry-run exits 1 on would-conflict, 0 on would-succeed."
+            ),
+            examples=[
+                'kd /article push docs/infra/dns-setup.md --project FB --title "DNS Setup Guide"',
+                'kd /article push guide.md --project FB --title "User Guide" --parent FB-A-1',
+                'kd /article push guide.md --project FB --title "Guide" --tag "type:guide"',
+                'kd /article push guide.md --project FB --title "Guide" --tag "type:guide" --tag "platform:rdk-e"',
+                'kd /article push guide.md --project FB --title "Guide" --dry-run',
+                'kd /article push guide.md --project FB --title "Guide" --force',
+            ],
+            see_also=[
+                "/article pull",
+                "/article create",
+                "/article update",
+                "/article move",
+            ],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Project key for new articles (required)"))
+        self.register_option(
+            OptionDeclaration(
+                name="slug",
+                layer=OptionLayer.COMMAND,
+                help_text="Override the slug on first push; rejected if it conflicts with the marker",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="parent",
+                layer=OptionLayer.COMMAND,
+                help_text="Attach a new article under this parent (first create only)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="title",
+                short_name="s",
+                layer=OptionLayer.COMMAND,
+                help_text="Article title (required)",
+                aliases=["summary"],
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="force",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Bypass the remote-edit conflict check",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="tag",
+                short_name="t",
+                layer=OptionLayer.COMMAND,
+                is_list=True,
+                help_text="Tag name (repeatable)",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="dry-run",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Resolve and validate, but do not write anywhere",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article push FILE --project P")
+        file_path = Path(args[0])
+        if not file_path.is_file():
+            raise ValidationError(f"File not found: {file_path}")
+        project = options.command.get("project")
+        if not project:
+            raise ValidationError("--project is required")
+        title = options.command.get("title")
+        if not title:
+            raise ValidationError("--title is required")
+        tags = options.command.get("tag", [])
+        result = client.articles.push(
+            file_path=file_path,
+            project=project,
+            summary=title,
+            slug=options.command.get("slug"),
+            parent=options.command.get("parent"),
+            force=bool(options.command.get("force")),
+            dry_run=bool(options.command.get("dry-run")),
+            tags=tags or None,
+        )
+        return {
+            "ok": True,
+            "action": result.action,
+            "article": result.article_id,
+            "slug": result.slug,
+            "path": str(result.path),
+            "dry_run": result.dry_run,
+            "tags_applied": result.tags_applied,
+            "tags_failed": result.tags_failed,
+        }
+
+
+class ArticleChildrenCommand(Command):
+    """List child articles."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "children",
+            "List child articles",
+            requires_client=True,
+            usage="kd /article children ARTICLE_ID [--limit N]",
+            examples=["kd /article children FB-A-1"],
+            see_also=["/article show", "/article list"],
+        )
+
+    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 /article children ARTICLE_ID")
+        limit = options.command.get("limit", 50)
+        children = client.articles.children(args[0], top=limit)
+        return [_article_to_row(a) for a in children]
+
+
+class ArticleCreateCommand(Command):
+    """Create an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "create",
+            "Create an article",
+            requires_client=True,
+            usage='kd /article create "Summary" --project P [--content TEXT] [--parent ID] [--tag T]',
+            long_description=(
+                "--project is the project key (e.g. FB). Summary is the article "
+                "title. Pass --parent to attach the new article under an "
+                "existing one in a single call, avoiding a create-then-move "
+                "two-step in migration scripts. Pass --tag (repeatable) to "
+                "apply tags at creation time."
+            ),
+            examples=[
+                'kd /article create "Setup Guide" --project FB --content @guide.md',
+                'kd /article create "Quick Note" -p FB --content "Remember to update DNS"',
+                'echo "# Draft" | kd /article create "Draft" -p FB --content -',
+                'kd /article create "Sub Guide" -p FB --parent FB-A-1 --content @sub.md',
+                'kd /article create "Guide" -p FB --content @g.md --tag "type:guide" --tag "reviewed"',
+            ],
+            see_also=["/article show", "/article update", "/article move"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(required=True))
+        self.register_option(
+            OptionDeclaration(
+                name="content",
+                short_name="c",
+                layer=OptionLayer.COMMAND,
+                help_text="Article content (Markdown). Use @file.md to read from file, or @- / - for stdin",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="parent",
+                layer=OptionLayer.COMMAND,
+                help_text="Attach the new article as a child of this article id",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="tag",
+                short_name="t",
+                layer=OptionLayer.COMMAND,
+                is_list=True,
+                help_text="Tag name (repeatable)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError('Usage: kd /article create "Summary" --project P')
+        project_key = options.command["project"]
+        summary = " ".join(args)
+        content = resolve_text_input(options.command.get("content"))
+        parent = options.command.get("parent")
+        tags = options.command.get("tag", [])
+        article = client.articles.create(
+            project=project_key,
+            summary=summary,
+            content=content,
+            parent=parent,
+            tags=tags or None,
+        )
+        return _article_to_detail(article)
+
+
+class ArticleUpdateCommand(Command):
+    """Update an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "update",
+            "Update an article",
+            requires_client=True,
+            usage="kd /article update ARTICLE_ID [--title T] [--content TEXT]",
+            examples=[
+                'kd /article update FB-A-1 --title "New Title"',
+                "kd /article update FB-A-1 --content @revised.md",
+            ],
+            see_also=["/article show"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="title",
+                short_name="s",
+                layer=OptionLayer.COMMAND,
+                help_text="Article title",
+                aliases=["summary"],
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="content",
+                short_name="c",
+                layer=OptionLayer.COMMAND,
+                help_text="New article content (Markdown). Use @file.md to read from file, or @- / - for stdin",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article update ARTICLE_ID [--title T] ...")
+        article_id = args[0]
+        title = options.command.get("title")
+        content = resolve_text_input(options.command.get("content"))
+        if not title and not content:
+            raise ValidationError("At least one of --title or --content must be specified")
+        article = client.articles.update(article_id, summary=title, content=content)
+        return _article_to_detail(article)
+
+
+class ArticleDeleteCommand(Command):
+    """Delete an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete an article",
+            requires_client=True,
+            usage="kd /article delete ARTICLE_ID",
+            examples=["kd /article delete FB-A-1"],
+            see_also=["/article list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article delete ARTICLE_ID")
+        article_id = args[0]
+        client.articles.delete(article_id)
+        return {"ok": True, "action": "delete", "article": article_id}
+
+
+# --- Comment Commands ---
+
+
+class ArticleCommentListCommand(Command):
+    """List comments on an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List comments on an article",
+            requires_client=True,
+            usage="kd /article/comment list ARTICLE_ID",
+            examples=["kd /article/comment list FB-A-1"],
+            see_also=["/article/comment add", "/article show"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article/comment list ARTICLE_ID")
+        comments = client.articles.list_comments(args[0])
+        return [
+            {
+                "id": c.id,
+                "author": c.author.name if c.author else "",
+                "text": c.text,
+                "pinned": c.pinned,
+                "created": c.created,
+            }
+            for c in comments
+        ]
+
+
+class ArticleCommentAddCommand(Command):
+    """Add a comment to an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Add a comment to an article",
+            requires_client=True,
+            usage='kd /article/comment add ARTICLE_ID "Text"',
+            examples=[
+                'kd /article/comment add FB-A-1 "Needs review"',
+                "kd /article/comment add FB-A-1 @note.md",
+            ],
+            see_also=["/article/comment list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError('Usage: kd /article/comment add ARTICLE_ID "Text"')
+        article_id = args[0]
+        text = resolve_text_input(" ".join(args[1:]))
+        comment = client.articles.add_comment(article_id, text)
+        return {
+            "id": comment.id,
+            "author": comment.author.name if comment.author else "",
+            "text": comment.text,
+        }
+
+
+# --- Attachment Commands ---
+
+
+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 ArticleAttachmentListCommand(Command):
+    """List attachments on an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List attachments on an article",
+            requires_client=True,
+            usage="kd /article/attachment list ARTICLE_ID",
+            examples=["kd /article/attachment list FB-A-1"],
+            see_also=["/article/attachment add", "/article/attachment download"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article/attachment list ARTICLE_ID")
+        attachments = client.articles.list_attachments(args[0])
+        return [_attachment_to_row(a) for a in attachments]
+
+
+class ArticleAttachmentAddCommand(Command):
+    """Add attachments to an article."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Add attachments to an article",
+            requires_client=True,
+            usage="kd /article/attachment add ARTICLE_ID FILE [FILE...]",
+            examples=[
+                "kd /article/attachment add FB-A-1 diagram.png",
+                "kd /article/attachment add FB-A-1 log.txt report.pdf",
+            ],
+            see_also=["/article/attachment list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /article/attachment add ARTICLE_ID FILE [FILE...]")
+        article_id = args[0]
+        file_paths = [Path(p) for p in args[1:]]
+        attachments = client.articles.add_attachments(article_id, file_paths)
+        return [_attachment_to_row(a) for a in attachments]
+
+
+class ArticleAttachmentShowCommand(Command):
+    """Show attachment metadata."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show attachment metadata",
+            requires_client=True,
+            usage="kd /article/attachment show ARTICLE_ID ATTACHMENT_ID",
+            examples=["kd /article/attachment show FB-A-1 att-1"],
+            see_also=["/article/attachment list", "/article/attachment download"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /article/attachment show ARTICLE_ID ATTACHMENT_ID")
+        a = client.articles.get_attachment(args[0], args[1])
+        return {
+            "id": a.id,
+            "name": a.name,
+            "size": a.size,
+            "mime_type": a.mime_type or "",
+            "extension": a.extension or "",
+            "author": a.author.name if a.author else "",
+            "created": a.created,
+            "url": a.url or "",
+        }
+
+
+class ArticleAttachmentDownloadCommand(Command):
+    """Download an article attachment."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "download",
+            "Download an article attachment",
+            requires_client=True,
+            usage="kd /article/attachment download ARTICLE_ID ATTACHMENT_ID [--to DIR]",
+            examples=[
+                "kd /article/attachment download FB-A-1 att-1",
+                "kd /article/attachment download FB-A-1 att-1 --to ./docs",
+            ],
+            see_also=["/article/attachment list", "/article/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 /article/attachment download ARTICLE_ID ATTACHMENT_ID")
+        target_dir = None
+        to_value = options.command.get("to")
+        if to_value:
+            target_dir = Path(to_value)
+        dest = client.articles.download_attachment(args[0], args[1], target_dir=target_dir)
+        return {"ok": True, "action": "download", "article": args[0], "path": str(dest)}
+
+
+class ArticleAttachmentDeleteCommand(Command):
+    """Delete an article attachment."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete an article attachment",
+            requires_client=True,
+            usage="kd /article/attachment delete ARTICLE_ID ATTACHMENT_ID",
+            examples=["kd /article/attachment delete FB-A-1 att-1"],
+            see_also=["/article/attachment list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /article/attachment delete ARTICLE_ID ATTACHMENT_ID")
+        client.articles.delete_attachment(args[0], args[1])
+        return {"ok": True, "action": "delete", "article": args[0], "attachment": args[1]}
+
+
+# --- Move Command ---
+
+
+class ArticleMoveCommand(Command):
+    """Move an article to a new parent."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "move",
+            "Move an article to a new parent",
+            requires_client=True,
+            usage="kd /article move ARTICLE_ID --parent PARENT_ID",
+            long_description="Use --parent none to move an article to project root.",
+            examples=[
+                "kd /article move FB-A-3 --parent FB-A-1",
+                "kd /article move FB-A-3 --parent none",
+            ],
+            see_also=["/article tree", "/article children"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="parent",
+                layer=OptionLayer.COMMAND,
+                help_text="New parent article ID, or 'none' to move to root",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article move ARTICLE_ID --parent PARENT_ID")
+        parent_value = options.command.get("parent")
+        if not parent_value:
+            raise ValidationError("--parent is required (use 'none' for root)")
+        article_id = args[0]
+        parent = None if parent_value.lower() == "none" else parent_value
+        article = client.articles.move(article_id, parent=parent)
+        return _article_to_detail(article)
+
+
+# --- Tree Command ---
+
+
+def _article_to_tree_node(article: Article) -> TreeNode:
+    """Convert an Article to a TreeNode for tree rendering."""
+    return TreeNode(
+        id=article.id_readable,
+        label=f"{article.id_readable}: {article.summary}",
+        has_children=article.has_children,
+    )
+
+
+def _collect_tree(
+    node: TreeNode,
+    fetch_children: Callable[[str], list[TreeNode]],
+    max_depth: int,
+) -> dict[str, Any]:
+    """Walk the tree and return nested dicts for structured output."""
+    result: dict[str, Any] = {"id": node.id, "summary": node.label, "children": []}
+    if max_depth > 0 and node.has_children:
+        children = fetch_children(node.id)
+        result["children"] = [_collect_tree(c, fetch_children, max_depth - 1) for c in children]
+    return result
+
+
+class ArticleTreeCommand(Command):
+    """Display article subtree with box-drawing characters."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "tree",
+            "Display article subtree",
+            requires_client=True,
+            usage="kd /article tree ARTICLE_ID [--depth N]",
+            long_description=(
+                "Renders the article hierarchy as an indented tree. "
+                "Each level requires an API call to fetch children."
+            ),
+            examples=[
+                "kd /article tree FB-A-1",
+                "kd /article tree FB-A-1 --depth 3",
+            ],
+            see_also=["/article children", "/article show"],
+        )
+        self.display_hint = "tree"
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="depth",
+                short_name="d",
+                layer=OptionLayer.COMMAND,
+                type=int,
+                default=5,
+                help_text="Maximum tree depth (default: 5)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /article tree ARTICLE_ID")
+        article = client.articles.get(args[0])
+        root = _article_to_tree_node(article)
+        depth = options.command.get("depth", 5)
+
+        def fetch_children(article_id: str) -> list[TreeNode]:
+            children = client.articles.children(article_id)
+            return [_article_to_tree_node(c) for c in children]
+
+        return _collect_tree(root, fetch_children, depth)
+
+
+# --- Namespace Factory ---
+
+
+def create_article_namespace() -> Namespace:
+    """Build the /article namespace."""
+    ns = Namespace("article", "Knowledge base articles", path="article")
+    ns.register_command("list", ArticleListCommand())
+    ns.register_command("show", ArticleShowCommand())
+    ns.register_command("pull", ArticlePullCommand())
+    ns.register_command("push", ArticlePushCommand())
+    ns.register_command("children", ArticleChildrenCommand())
+    ns.register_command("create", ArticleCreateCommand())
+    ns.register_command("update", ArticleUpdateCommand())
+    ns.register_command("delete", ArticleDeleteCommand())
+    ns.register_command("tree", ArticleTreeCommand())
+    ns.register_command("move", ArticleMoveCommand())
+
+    comment_ns = Namespace("comment", "Article comments", path="article/comment")
+    comment_ns.register_command("list", ArticleCommentListCommand())
+    comment_ns.register_command("add", ArticleCommentAddCommand())
+    ns.register_sub_namespace(comment_ns)
+
+    attachment_ns = Namespace("attachment", "Article attachments", path="article/attachment")
+    attachment_ns.register_command("list", ArticleAttachmentListCommand())
+    attachment_ns.register_command("add", ArticleAttachmentAddCommand())
+    attachment_ns.register_command("show", ArticleAttachmentShowCommand())
+    attachment_ns.register_command("download", ArticleAttachmentDownloadCommand())
+    attachment_ns.register_command("delete", ArticleAttachmentDeleteCommand())
+    ns.register_sub_namespace(attachment_ns)
+
+    return ns