kd-cli 2.0.4__py3-none-any.whl

kd/cli/namespaces/query/__init__.py

@@ -0,0 +1,465 @@
+"""Query namespace: /query
+
+Commands: list, show, create, update, delete, issues, articles, validate, assist
+API layer: YouTrack REST API (/api/savedQueries, /api/search/assist)
+
+The namespace is named ``/query`` rather than ``/saved-query`` to match the
+single-word cadence of the other namespaces (/tag, /article, /time, /alias).
+Subcommands disambiguate intent — ``list`` and ``show`` inspect saved queries,
+``issues`` and ``articles`` execute one against the respective entity type,
+and ``assist`` calls the search-autocomplete endpoint on a free-form query
+string.
+"""
+
+from __future__ import annotations
+
+import sys
+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.cli.namespaces.issue import _issue_to_row
+from kd.cli.namespaces.tag import _article_to_row
+from kd.exceptions import ValidationError
+from kd.models import AssistSuggestion, QueryValidationResult, SavedQuery
+
+
+def _saved_query_to_row(sq: SavedQuery) -> dict[str, Any]:
+    """Convert a SavedQuery to a flat dict for table output."""
+    return {
+        "id": sq.id,
+        "name": sq.name,
+        "query": sq.query,
+        "owner": sq.owner.name if sq.owner and sq.owner.name else "",
+    }
+
+
+def _saved_query_to_detail(sq: SavedQuery) -> dict[str, Any]:
+    """Convert a SavedQuery to a detail dict for show/create/update output."""
+    return {
+        "id": sq.id,
+        "name": sq.name,
+        "query": sq.query,
+        "owner": sq.owner.name if sq.owner and sq.owner.name else "",
+    }
+
+
+def _suggestion_to_row(s: AssistSuggestion) -> dict[str, Any]:
+    """Convert an AssistSuggestion to a flat dict for table output."""
+    return {
+        "option": s.option,
+        "description": s.description or "",
+        "prefix": s.prefix or "",
+        "suffix": s.suffix or "",
+        "caret": s.completion_start if s.completion_start is not None else "",
+    }
+
+
+def _warn_invalid_query(result: QueryValidationResult, name: str) -> None:
+    """Print a validation warning to stderr if the query is invalid."""
+    if result.valid:
+        return
+    print(f"Warning: query syntax error — {result.error}", file=sys.stderr)
+    if result.suggestion:
+        print(f"Hint: {result.suggestion}", file=sys.stderr)
+    print(f'Hint: delete with: kd /query delete "{name}"', file=sys.stderr)
+
+
+# --- Commands ---
+
+
+class QueryListCommand(Command):
+    """List saved queries."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "list",
+            "List saved queries",
+            requires_client=True,
+            usage="kd /query list [--mine] [--limit N]",
+            long_description=(
+                "Lists saved queries visible to the authenticated user. "
+                "Pass --mine to restrict to queries you own."
+            ),
+            examples=[
+                "kd /query list",
+                "kd /query list --mine",
+                "kd /query list --limit 100",
+            ],
+            see_also=["/query show", "/query issues", "/query articles"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="mine",
+                layer=OptionLayer.COMMAND,
+                type=bool,
+                default=False,
+                help_text="Only queries owned by the current user",
+            )
+        )
+        self.register_option(limit_option())
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        limit = options.command.get("limit", 50)
+        mine = options.command.get("mine", False)
+        owner = "me" if mine else None
+        queries = client.queries.list(owner=owner, top=limit)
+        return [_saved_query_to_row(sq) for sq in queries]
+
+
+class QueryShowCommand(Command):
+    """Show saved query details."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "show",
+            "Show saved query details",
+            requires_client=True,
+            usage="kd /query show NAME_OR_ID",
+            long_description=(
+                "Resolves NAME_OR_ID to a saved query. Names are matched "
+                "case-insensitively; use the ID (e.g. 11-24) to disambiguate "
+                "duplicates."
+            ),
+            examples=[
+                'kd /query show "Assigned to me"',
+                "kd /query show 11-24",
+            ],
+            see_also=["/query list", "/query issues", "/query articles"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /query show NAME_OR_ID")
+        sq = client.queries.get(args[0])
+        return _saved_query_to_detail(sq)
+
+
+class QueryCreateCommand(Command):
+    """Create a saved query."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "create",
+            "Create a saved query",
+            requires_client=True,
+            usage='kd /query create NAME "QUERY_TEXT"',
+            long_description=(
+                "Creates a personal saved query. Sharing settings default to "
+                "owner-only; other users can be granted access via the "
+                "YouTrack web UI.\n\n"
+                "The query is validated after saving by executing a dry-run "
+                "search. If the syntax is invalid, a warning is printed but "
+                "the query is still saved.\n\n"
+                "Syntax tip: values containing colons, spaces, or braces must "
+                "be wrapped in braces — e.g. tag: {type:case} instead of "
+                "tag: type:case."
+            ),
+            examples=[
+                'kd /query create "My Bugs" "for: me Type: Bug #Unresolved"',
+                'kd /query create "Sprint 47" "Sprint: {Sprint 47}"',
+            ],
+            see_also=["/query list", "/query delete"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if len(args) < 2:
+            raise ValidationError('Usage: kd /query create NAME "QUERY_TEXT"')
+        name, query_text = args[0], args[1]
+        sq = client.queries.create(name, query_text)
+        vr = client.queries.validate(query_text)
+        _warn_invalid_query(vr, name)
+        return _saved_query_to_detail(sq)
+
+
+class QueryUpdateCommand(Command):
+    """Update a saved query."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "update",
+            "Update a saved query",
+            requires_client=True,
+            usage="kd /query update NAME_OR_ID [--name NEW_NAME] [--query NEW_QUERY]",
+            long_description=(
+                "Partial update — pass whichever of --name / --query you want "
+                "to change. At least one is required.\n\n"
+                "When --query is provided, the new query text is validated by "
+                "executing a dry-run search. A warning is printed if the "
+                "syntax is invalid.\n\n"
+                "Syntax tip: values containing colons, spaces, or braces must "
+                "be wrapped in braces — e.g. tag: {type:case} instead of "
+                "tag: type:case."
+            ),
+            examples=[
+                'kd /query update "My Bugs" --name "My Bugs (archived)"',
+                'kd /query update 11-24 --query "project: FB #Unresolved"',
+                'kd /query update 11-24 --name "New" --query "project: FB"',
+            ],
+            see_also=["/query show", "/query create"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="name",
+                layer=OptionLayer.COMMAND,
+                help_text="New name",
+            )
+        )
+        self.register_option(
+            OptionDeclaration(
+                name="query",
+                layer=OptionLayer.COMMAND,
+                help_text="New query text",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /query update NAME_OR_ID [--name ...] [--query ...]")
+        new_name = options.command.get("name")
+        new_query = options.command.get("query")
+        if new_name is None and new_query is None:
+            raise ValidationError("Provide at least one of --name or --query to update.")
+        sq = client.queries.update(args[0], name=new_name, query=new_query)
+        if new_query is not None:
+            vr = client.queries.validate(new_query)
+            _warn_invalid_query(vr, sq.name)
+        return _saved_query_to_detail(sq)
+
+
+class QueryDeleteCommand(Command):
+    """Delete a saved query."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "delete",
+            "Delete a saved query",
+            requires_client=True,
+            usage="kd /query delete NAME_OR_ID",
+            examples=[
+                'kd /query delete "My Bugs"',
+                "kd /query delete 11-24",
+            ],
+            see_also=["/query list", "/query create"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError("Usage: kd /query delete NAME_OR_ID")
+        target = args[0]
+        client.queries.delete(target)
+        return {"ok": True, "action": "delete", "query": target}
+
+
+class QueryIssuesCommand(Command):
+    """Run a saved query and return matching issues."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "issues",
+            "Execute a saved query against issues",
+            requires_client=True,
+            usage="kd /query issues NAME_OR_ID [--project P] [--limit N]",
+            long_description=(
+                "Resolves the saved query, fetches its query text, and runs "
+                "it through /issue list. Use --project to scope results to a "
+                "specific project. Output columns match `kd /issue list`."
+            ),
+            examples=[
+                'kd /query issues "My Bugs"',
+                'kd /query issues "Sprint 47" --limit 100',
+                'kd /query issues "My Bugs" --project FB',
+            ],
+            see_also=["/query list", "/query articles", "/issue list"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Scope results 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 /query issues NAME_OR_ID")
+        limit = options.command.get("limit", 50)
+        project = options.command.get("project")
+        issues = client.queries.run_issues(args[0], top=limit, project=project)
+        return [_issue_to_row(i) for i in issues]
+
+
+class QueryArticlesCommand(Command):
+    """Run a saved query and return matching articles."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "articles",
+            "Execute a saved query against articles",
+            requires_client=True,
+            usage="kd /query articles NAME_OR_ID [--project P] [--limit N]",
+            long_description=(
+                "Resolves the saved query, parses project and tag fields from "
+                "the query text, and finds articles matching those tags. "
+                "Use --project to scope or override the project parsed from "
+                "the query text. Only project: and tag: fields are supported — "
+                "queries with issue-specific fields (state, assignee, priority, "
+                "etc.) are rejected with an error.\n\n"
+                "Output columns match `kd /tag articles`."
+            ),
+            examples=[
+                'kd /query articles "CMCSA Cases"',
+                'kd /query articles "Tagged Guides" --limit 100',
+                'kd /query articles "Tagged Guides" --project CMCSA',
+            ],
+            see_also=["/query list", "/query issues", "/tag articles"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(project_option(help_text="Scope results 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 /query articles NAME_OR_ID")
+        limit = options.command.get("limit", 50)
+        project = options.command.get("project")
+        articles = client.queries.run_articles(args[0], top=limit, project=project)
+        return [_article_to_row(a) for a in articles]
+
+
+class QueryValidateCommand(Command):
+    """Validate saved query syntax."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "validate",
+            "Validate saved query syntax against the search API",
+            requires_client=True,
+            usage="kd /query validate [NAME_OR_ID]",
+            long_description=(
+                "Validates query syntax by executing a dry-run search. "
+                "With no argument, validates all saved queries and reports "
+                "which ones have syntax errors. With a name or ID, validates "
+                "a single saved query."
+            ),
+            examples=[
+                "kd /query validate",
+                'kd /query validate "My Bugs"',
+                "kd /query validate 11-24",
+            ],
+            see_also=["/query list", "/query create"],
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if args:
+            sq = client.queries.get(args[0])
+            vr = client.queries.validate(sq.query)
+            return _validation_to_row(sq, vr)
+        queries = client.queries.list(top=500)
+        rows: list[dict[str, Any]] = []
+        for sq in queries:
+            vr = client.queries.validate(sq.query)
+            rows.append(_validation_to_row(sq, vr))
+        return rows
+
+
+def _validation_to_row(sq: SavedQuery, vr: QueryValidationResult) -> dict[str, Any]:
+    """Convert a validation result to a flat dict for output."""
+    return {
+        "name": sq.name,
+        "query": sq.query,
+        "status": "ok" if vr.valid else "error",
+        "error": vr.error or "",
+    }
+
+
+class QueryAssistCommand(Command):
+    """Fetch search-query autocomplete suggestions."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "assist",
+            "Autocomplete a YouTrack search query",
+            requires_client=True,
+            usage='kd /query assist "QUERY_TEXT" [--caret N]',
+            long_description=(
+                "Wraps POST /api/search/assist. --caret defaults to the end "
+                "of QUERY_TEXT so typical use (tab-completion at the tail) "
+                "works without specifying it."
+            ),
+            examples=[
+                'kd /query assist "project: "',
+                'kd /query assist "for: " --caret 5',
+                'kd /query assist "Assignee: ad"',
+            ],
+            see_also=["/query issues", "/query create"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="caret",
+                layer=OptionLayer.COMMAND,
+                type=int,
+                help_text="Caret position (defaults to end of query)",
+            )
+        )
+
+    def execute(
+        self, args: list[str], options: ResolvedOptions, client: Any = None
+    ) -> CommandResult:
+        if not args:
+            raise ValidationError('Usage: kd /query assist "QUERY_TEXT" [--caret N]')
+        query_text = args[0]
+        caret = options.command.get("caret")
+        if caret is None:
+            caret = len(query_text)
+        response = client.assist.search(query_text, caret=caret)
+        return [_suggestion_to_row(s) for s in response.suggestions]
+
+
+# --- Namespace factory ---
+
+
+def create_query_namespace() -> Namespace:
+    """Build the /query namespace."""
+    ns = Namespace(
+        "query",
+        "Saved queries and search autocomplete",
+        path="query",
+    )
+    ns.register_command("list", QueryListCommand())
+    ns.register_command("show", QueryShowCommand())
+    ns.register_command("create", QueryCreateCommand())
+    ns.register_command("update", QueryUpdateCommand())
+    ns.register_command("delete", QueryDeleteCommand())
+    ns.register_command("issues", QueryIssuesCommand())
+    ns.register_command("articles", QueryArticlesCommand())
+    ns.register_command("validate", QueryValidateCommand())
+    ns.register_command("assist", QueryAssistCommand())
+    return ns

kd/cli/namespaces/search/__init__.py

@@ -0,0 +1,82 @@
+"""Search command: /search
+
+Cross-entity aggregated search across issues, users, tags, projects,
+and articles. Backed by composed calls to multiple YouTrack REST API
+endpoints (client-side aggregation, not a single upstream endpoint).
+
+Registered as a root command (not a namespace) so that the first
+positional argument is the search query, not a subcommand name.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kd.cli.core.command_base import Command, CommandResult
+from kd.cli.core.option_registry import (
+    OptionDeclaration,
+    OptionLayer,
+    ResolvedOptions,
+    limit_option,
+    project_option,
+)
+from kd.exceptions import ValidationError
+
+
+class SearchCommand(Command):
+    """Cross-entity search."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "search",
+            "Search across entity types",
+            requires_client=True,
+            usage="kd /search QUERY [--types TYPE,...] [--project P] [--limit N]",
+            long_description=(
+                "Aggregated search across issues, users, tags, projects, and articles. "
+                "Issue and user searches use server-side query APIs. Tag, project, and "
+                "article searches use client-side substring matching."
+            ),
+            examples=[
+                'kd /search "router"',
+                'kd /search "router" --types issue,article',
+                'kd /search "alice" --types user',
+                'kd /search "dns" --project FB',
+                'kd /search "router" --limit 10',
+            ],
+            see_also=["/issue list"],
+        )
+
+    def _register_options(self) -> None:
+        self.register_option(
+            OptionDeclaration(
+                name="types",
+                layer=OptionLayer.COMMAND,
+                type=str,
+                default=None,
+                help_text="Comma-separated entity types: issue,user,tag,project,article",
+            )
+        )
+        self.register_option(project_option(help_text="Scope issues and articles 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 /search QUERY")
+        query = args[0]
+        types_raw = options.command.get("types")
+        types = types_raw.split(",") if types_raw else None
+        project = options.command.get("project")
+        limit = options.command.get("limit", 50)
+        results = client.search.search(query, types=types, project=project, limit=limit)
+        return [
+            {
+                "type": r.type,
+                "id": r.id,
+                "title": r.title,
+                "project": r.project,
+            }
+            for r in results
+        ]