kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/primer/__init__.py

@@ -0,0 +1,337 @@
+"""Primer namespace: /primer, /primer/note, /primer/article.
+
+Project-local knowledge capsule for LLM consumers.  Stores conventions,
+key article references, and do's/don'ts in ``.kd /primer.yaml``.
+"""
+
+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
+from kd.cli.input import resolve_text_input
+from kd.exceptions import ValidationError
+from kd.primer import (
+    add_article,
+    add_note,
+    clear_articles,
+    clear_notes,
+    load_primer,
+    remove_article,
+    remove_note,
+    update_note,
+)
+
+
+# ---------------------------------------------------------------------------
+# /primer show (root default)
+# ---------------------------------------------------------------------------
+
+
+class PrimerShowCommand(Command):
+    """Show the full project primer."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show project primer",
+            usage="kd /primer show",
+            long_description="Displays the full project primer — notes, pinned articles, "
+            "and all other sections.  Returns an empty primer if none exists yet.",
+            examples=[
+                "kd /primer show",
+                "kd /primer show --output json",
+            ],
+            see_also=["/primer/note list", "/primer/article list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        data = load_primer()
+        if not data.notes and not data.articles:
+            return None
+        result: dict[str, Any] = {}
+        if data.notes:
+            result["notes"] = [{"#": i + 1, "note": n} for i, n in enumerate(data.notes)]
+        if data.articles:
+            result["articles"] = [{"id": a.id, "summary": a.summary or ""} for a in data.articles]
+        return result
+
+
+# ---------------------------------------------------------------------------
+# /primer/note
+# ---------------------------------------------------------------------------
+
+
+class PrimerNoteListCommand(Command):
+    """List all primer notes."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List primer notes",
+            usage="kd /primer/note list",
+            long_description="Lists all notes in the project primer with their 1-based index.",
+            examples=["kd /primer/note list"],
+            see_also=["/primer/note add", "/primer/note remove"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        data = load_primer()
+        return [{"index": i + 1, "note": note} for i, note in enumerate(data.notes)]
+
+
+class PrimerNoteAddCommand(Command):
+    """Add a note to the primer."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Add a primer note",
+            usage="kd /primer/note add TEXT",
+            long_description="Appends a note to the project primer.  TEXT can be inline, "
+            "@file to read from a file, or - to read from stdin.",
+            examples=[
+                'kd /primer/note add "Sprint field is called Board"',
+                "kd /primer/note add @conventions.txt",
+            ],
+            see_also=["/primer/note list", "/primer/note remove"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /primer/note add TEXT")
+        text = resolve_text_input(" ".join(args))
+        if not text:
+            raise ValidationError("Note text cannot be empty")
+        index = add_note(text)
+        return {"ok": True, "action": "add", "index": index, "note": text}
+
+
+class PrimerNoteRemoveCommand(Command):
+    """Remove a note by index, or all notes with --all."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "remove",
+            "Remove a primer note by index or all notes",
+            usage="kd /primer/note remove INDEX | --all",
+            long_description="Removes the note at the given 1-based index, or all notes "
+            "if --all is passed.  Use '/primer/note list' to see current indices.",
+            examples=[
+                "kd /primer/note remove 2",
+                "kd /primer/note remove --all",
+            ],
+            see_also=["/primer/note list", "/primer/note add"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="all",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Remove all notes",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if options.command.get("all"):
+            count = clear_notes()
+            return {"ok": True, "action": "clear", "removed": count}
+        if not args:
+            raise ValidationError("Usage: kd /primer/note remove INDEX | --all")
+        try:
+            index = int(args[0])
+        except ValueError:
+            raise ValidationError(f"INDEX must be a number, got: {args[0]}") from None
+        removed = remove_note(index)
+        return {"ok": True, "action": "remove", "index": index, "note": removed}
+
+
+class PrimerNoteUpdateCommand(Command):
+    """Replace a note by index."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "update",
+            "Replace a primer note by index",
+            usage="kd /primer/note update INDEX TEXT",
+            long_description="Replaces the note at the given 1-based index with new text.  "
+            "TEXT can be inline, @file to read from a file, or - to read from stdin.  "
+            "Use '/primer/note list' to see current indices.",
+            examples=[
+                'kd /primer/note update 1 "Updated convention"',
+                "kd /primer/note update 2 @updated.txt",
+            ],
+            see_also=["/primer/note list", "/primer/note remove"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /primer/note update INDEX TEXT")
+        try:
+            index = int(args[0])
+        except ValueError:
+            raise ValidationError(f"INDEX must be a number, got: {args[0]}") from None
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /primer/note update INDEX TEXT")
+        text = resolve_text_input(" ".join(args[1:]))
+        if not text:
+            raise ValidationError("Note text cannot be empty")
+        old = update_note(index, text)
+        return {"ok": True, "action": "update", "index": index, "old": old, "new": text}
+
+
+# ---------------------------------------------------------------------------
+# /primer/article
+# ---------------------------------------------------------------------------
+
+
+class PrimerArticleListCommand(Command):
+    """List pinned articles."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List pinned articles",
+            usage="kd /primer/article list",
+            long_description="Lists all articles pinned in the project primer.",
+            examples=["kd /primer/article list"],
+            see_also=["/primer/article add", "/primer/article remove"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        data = load_primer()
+        return [{"id": a.id, "summary": a.summary or ""} for a in data.articles]
+
+
+class PrimerArticleAddCommand(Command):
+    """Pin an article to the primer."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "add",
+            "Pin an article to the primer",
+            usage="kd /primer/article add ARTICLE_ID [--summary S]",
+            long_description="Adds a YouTrack article reference to the project primer.  "
+            "Use --summary to store a description alongside the ID.",
+            examples=[
+                "kd /primer/article add FB-A-42",
+                'kd /primer/article add FB-A-42 --summary "Architecture Overview"',
+            ],
+            see_also=["/primer/article list", "/primer/article remove"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="summary",
+                short_name="s",
+                layer=OptionLayer.COMMAND,
+                help_text="Description to store with the article reference",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /primer/article add ARTICLE_ID")
+        article_id = args[0]
+        summary = options.command.get("summary")
+        article = add_article(article_id, summary=summary)
+        result: dict[str, Any] = {"ok": True, "action": "add", "id": article.id}
+        if article.summary:
+            result["summary"] = article.summary
+        return result
+
+
+class PrimerArticleRemoveCommand(Command):
+    """Unpin an article by ID, or all articles with --all."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "remove",
+            "Unpin an article or all articles",
+            usage="kd /primer/article remove ARTICLE_ID | --all",
+            long_description="Removes the article with the given ID from the primer, "
+            "or all pinned articles if --all is passed.",
+            examples=[
+                "kd /primer/article remove FB-A-42",
+                "kd /primer/article remove --all",
+            ],
+            see_also=["/primer/article list", "/primer/article add"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="all",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Remove all pinned articles",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if options.command.get("all"):
+            count = clear_articles()
+            return {"ok": True, "action": "clear", "removed": count}
+        if not args:
+            raise ValidationError("Usage: kd /primer/article remove ARTICLE_ID | --all")
+        removed = remove_article(args[0])
+        return {"ok": True, "action": "remove", "id": removed.id}
+
+
+# ---------------------------------------------------------------------------
+# Namespace factory
+# ---------------------------------------------------------------------------
+
+
+def create_primer_namespace() -> Namespace:
+    """Build the /primer namespace with /primer/note and /primer/article."""
+    ns = Namespace(
+        "primer",
+        "Project primer — local knowledge for LLM consumers",
+        path="primer",
+    )
+    ns.register_command("show", PrimerShowCommand())
+
+    # /primer/note
+    note_ns = Namespace("note", "Primer notes and conventions", path="primer/note")
+    note_ns.register_command("list", PrimerNoteListCommand())
+    note_ns.register_command("add", PrimerNoteAddCommand())
+    note_ns.register_command("remove", PrimerNoteRemoveCommand())
+    note_ns.register_command("update", PrimerNoteUpdateCommand())
+    ns.register_sub_namespace(note_ns)
+
+    # /primer/article
+    article_ns = Namespace(
+        "article",
+        "Pinned article references",
+        path="primer/article",
+    )
+    article_ns.register_command("list", PrimerArticleListCommand())
+    article_ns.register_command("add", PrimerArticleAddCommand())
+    article_ns.register_command("remove", PrimerArticleRemoveCommand())
+    ns.register_sub_namespace(article_ns)
+
+    return ns

kd/cli/namespaces/project/__init__.py

@@ -0,0 +1,243 @@
+"""Project namespace: /project
+
+Commands: list, create, show, configure, delete
+API layer: YouTrack REST API (/api/admin/projects)
+"""
+
+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,
+    project_option,
+)
+from kd.exceptions import ValidationError
+
+
+class ProjectListCommand(Command):
+    """List all projects."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List all projects",
+            requires_client=True,
+            usage="kd /project list",
+            examples=["kd /project list", "kd /project list --output json"],
+            see_also=["/project show", "/project create"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        projects = client.projects.list()
+        return [
+            {
+                "key": p.short_name,
+                "name": p.name,
+                "leader": p.leader.name if p.leader else "",
+                "archived": p.archived,
+            }
+            for p in projects
+        ]
+
+
+class ProjectCreateCommand(Command):
+    """Create a project."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "create",
+            "Create a project",
+            requires_client=True,
+            usage="kd /project create KEY NAME",
+            long_description="KEY is the project short name (max 10 chars, uppercase + digits). "
+            "NAME is the full project name.",
+            examples=[
+                'kd /project create FB "Franco Bet"',
+                "kd /project create DEMO Demo",
+            ],
+            see_also=["/project list", "/project show"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError("Usage: kd /project create KEY NAME")
+        key = args[0]
+        name = " ".join(args[1:])
+        project = client.projects.create(name=name, short_name=key)
+        return {"key": project.short_name, "name": project.name, "id": project.id}
+
+
+class ProjectShowCommand(Command):
+    """Show project details."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show project details",
+            requires_client=True,
+            usage="kd /project show KEY",
+            examples=["kd /project show FB", "kd /project show FB --output json"],
+            see_also=["/project list", "/project configure"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /project show KEY")
+        project = client.projects.get(args[0])
+        return {
+            "key": project.short_name,
+            "name": project.name,
+            "description": project.description or "",
+            "leader": project.leader.name if project.leader else "",
+            "archived": project.archived,
+            "id": project.id,
+        }
+
+
+class ProjectConfigureCommand(Command):
+    """Configure project settings."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "configure",
+            "Configure project settings",
+            requires_client=True,
+            usage="kd /project configure KEY --time-tracking true",
+            long_description="Configure project-level settings like time tracking.",
+            examples=[
+                "kd /project configure FB --time-tracking true",
+                "kd /project configure FB --time-tracking false",
+            ],
+            see_also=["/project show"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="time-tracking",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                required=True,
+                help_text="Enable or disable time tracking",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /project configure KEY --time-tracking true|false")
+        key = args[0]
+        enabled = options.command["time-tracking"]
+        settings = client.projects.configure_time_tracking(key, enabled)
+        return {"project": key, "time_tracking": settings.enabled}
+
+
+class ProjectDeleteCommand(Command):
+    """Delete a project."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete a project",
+            requires_client=True,
+            usage="kd /project delete KEY",
+            examples=["kd /project delete TST"],
+            see_also=["/project list"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /project delete KEY")
+        key = args[0]
+        client.projects.delete(key)
+        return {"ok": True, "action": "delete", "project": key}
+
+
+class ProjectFieldListCommand(Command):
+    """List custom fields for a project."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List custom fields for a project",
+            requires_client=True,
+            usage="kd /project/field list KEY [-p KEY] [--field NAME]",
+            examples=[
+                "kd /project/field list FB",
+                "kd /project/field list -p FB",
+                "kd /project/field list FB --field State",
+                "kd /project/field list FB --output json",
+            ],
+            see_also=["/project show", "/issue create", "/issue update"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Project key"))
+        self.register_option(
+            OptionDeclaration(
+                name="field",
+                layer=OptionLayer.COMMAND,
+                help_text="Show only this field and its values",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        positional = args[0] if args else None
+        from_option = options.command.get("project")
+        key = positional or from_option
+        if not key:
+            raise ValidationError("Usage: kd /project/field list KEY  (or --project/-p KEY)")
+
+        fields = client.projects.list_fields(key)
+
+        field_name = options.command.get("field")
+        if field_name is not None:
+            match = [f for f in fields if f.name == field_name]
+            if not match:
+                names = ", ".join(f.name for f in fields)
+                raise ValidationError(
+                    f"No field named '{field_name}' in project {key}. Available: {names}"
+                )
+            fields = match
+
+        return [
+            {
+                "name": f.name,
+                "type": f.field_type_id,
+                "required": not f.can_be_empty,
+                "values": ", ".join(v.name for v in f.bundle_values) if f.bundle_values else "",
+            }
+            for f in fields
+        ]
+
+
+def create_project_namespace() -> Namespace:
+    """Build the /project namespace tree."""
+    ns = Namespace("project", "Project management", path="project")
+    ns.register_command("list", ProjectListCommand())
+    ns.register_command("create", ProjectCreateCommand())
+    ns.register_command("show", ProjectShowCommand())
+    ns.register_command("configure", ProjectConfigureCommand())
+    ns.register_command("delete", ProjectDeleteCommand())
+
+    field_ns = Namespace("field", "Project custom fields", path="project/field")
+    field_ns.register_command("list", ProjectFieldListCommand())
+    ns.register_sub_namespace(field_ns)
+
+    return ns