plane-cli 0.1.0__tar.gz

plane_cli-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.3
+Name: plane-cli
+Version: 0.1.0
+Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: plane-sdk>=0.2.0
+Requires-Dist: tomlkit>=0.13.0
+Requires-Python: >=3.11

plane_cli-0.1.0/plane_cli/__init__.py

@@ -0,0 +1,3 @@
+"""plane-cli: A command-line interface for Plane.so project management."""
+
+__version__ = "0.1.0"

plane_cli-0.1.0/plane_cli/client.py

@@ -0,0 +1,90 @@
+"""PlaneClient factory and retry logic."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+import typer
+from plane.client.plane_client import PlaneClient
+from plane.errors.errors import HttpError
+
+from plane_cli.output import print_error
+
+if TYPE_CHECKING:
+    from plane_cli.config import Config
+
+T = TypeVar("T")
+
+
+def get_client(cfg: "Config") -> PlaneClient:
+    """Build and return a PlaneClient, validating required credentials."""
+    if not cfg.api_key:
+        print_error(
+            "auth_error",
+            "No API key configured. Set PLANE_API_KEY, use --api-key, or run `plane config init`.",
+        )
+        raise typer.Exit(1)
+    if not cfg.workspace_slug:
+        print_error(
+            "config_error",
+            "No workspace slug configured. Set PLANE_WORKSPACE_SLUG, use --workspace, or run `plane config init`.",
+        )
+        raise typer.Exit(1)
+
+    return PlaneClient(base_url=cfg.base_url, api_key=cfg.api_key)
+
+
+def call_with_retry(fn: Callable[..., T], *args: Any, max_retries: int = 3, **kwargs: Any) -> T:
+    """Call fn(*args, **kwargs) with retry on HTTP 429."""
+    for attempt in range(max_retries):
+        try:
+            return fn(*args, **kwargs)
+        except HttpError as exc:
+            if exc.status_code == 429:
+                # Try to read Retry-After header
+                retry_after = 5
+                if hasattr(exc, "response") and exc.response is not None:
+                    try:
+                        retry_after = int(exc.response.headers.get("Retry-After", 5))
+                    except (AttributeError, ValueError):
+                        retry_after = 5
+
+                if attempt < max_retries - 1:
+                    time.sleep(retry_after)
+                    continue
+                else:
+                    print_error(
+                        "rate_limit",
+                        f"Rate limit exceeded after {max_retries} attempts.",
+                        status_code=429,
+                    )
+                    raise typer.Exit(2)
+            else:
+                _handle_http_error(exc)
+                raise typer.Exit(1)
+
+    # Should not reach here
+    raise typer.Exit(1)
+
+
+def _handle_http_error(exc: HttpError) -> None:
+    """Translate an HttpError into a structured error output."""
+    status = exc.status_code
+    message = str(exc)
+
+    if status == 401:
+        error_type = "auth_error"
+        message = "Authentication failed. Check your API key."
+    elif status == 403:
+        error_type = "forbidden"
+        message = "Permission denied."
+    elif status == 404:
+        error_type = "not_found"
+        message = f"Resource not found. {message}"
+    elif status == 400:
+        error_type = "validation_error"
+    else:
+        error_type = "api_error"
+
+    print_error(error_type, message, status_code=status)

plane_cli-0.1.0/plane_cli/commands/config_cmd.py

@@ -0,0 +1,123 @@
+"""config subcommand: show / set / init."""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from plane_cli.config import (
+    Config,
+    CONFIG_PATH,
+    config_as_dict,
+    load_config,
+    save_config,
+    save_config_key,
+)
+from plane_cli.output import print_json, print_error, out_console
+
+app = typer.Typer(name="config", help="Manage plane-cli configuration.", no_args_is_help=True)
+console = Console()
+err_console = Console(stderr=True)
+
+
+@app.command("show")
+def config_show(
+    ctx: typer.Context,
+    reveal: bool = typer.Option(False, "--reveal", help="Show the full API key."),
+) -> None:
+    """Show the resolved configuration (masks api_key by default)."""
+    cfg: Config = ctx.obj
+    print_json(config_as_dict(cfg, reveal=reveal))
+
+
+@app.command("set")
+def config_set(
+    ctx: typer.Context,
+    key: str = typer.Argument(..., help="Dotted config key, e.g. defaults.project"),
+    value: str = typer.Argument(..., help="Value to set"),
+) -> None:
+    """Write a config value. Example: plane config set defaults.project <UUID>"""
+    try:
+        save_config_key(key, value)
+        print_json({"ok": True, "key": key, "value": value})
+    except Exception as exc:
+        print_error("config_error", f"Failed to write config: {exc}")
+        raise typer.Exit(1)
+
+
+@app.command("init")
+def config_init(ctx: typer.Context) -> None:
+    """Interactive first-run wizard (TTY only)."""
+    if not sys.stdin.isatty():
+        print_error("validation_error", "`plane config init` requires an interactive terminal.")
+        raise typer.Exit(1)
+
+    console.print("[bold]plane-cli setup wizard[/bold]")
+    console.print(f"Config will be saved to: [dim]{CONFIG_PATH}[/dim]\n")
+
+    cfg: Config = ctx.obj
+
+    api_key = Prompt.ask(
+        "API key",
+        password=True,
+        default=cfg.api_key or "",
+    )
+    workspace_slug = Prompt.ask(
+        "Workspace slug",
+        default=cfg.workspace_slug or "",
+    )
+    base_url = Prompt.ask(
+        "Base URL",
+        default=cfg.base_url,
+    )
+
+    if not api_key:
+        print_error("validation_error", "API key is required.")
+        raise typer.Exit(1)
+    if not workspace_slug:
+        print_error("validation_error", "Workspace slug is required.")
+        raise typer.Exit(1)
+
+    # Validate credentials by listing projects
+    console.print("\nValidating credentials…")
+    try:
+        from plane.client.plane_client import PlaneClient
+        client = PlaneClient(base_url=base_url, api_key=api_key)
+        response = client.projects.list(workspace_slug)
+        projects = response.results or []
+        console.print(f"[green]✓[/green] Connected. Found {len(projects)} project(s).")
+    except Exception as exc:
+        print_error("auth_error", f"Could not connect: {exc}")
+        raise typer.Exit(1)
+
+    # Optionally set default project
+    default_project: Optional[str] = None
+    if projects:
+        console.print("\nAvailable projects:")
+        for i, p in enumerate(projects, 1):
+            console.print(f"  {i}. [{p.identifier}] {p.name}  (id: {p.id})")
+        choice = Prompt.ask(
+            "Set a default project? Enter number or press Enter to skip",
+            default="",
+        )
+        if choice.strip().isdigit():
+            idx = int(choice.strip()) - 1
+            if 0 <= idx < len(projects):
+                default_project = projects[idx].id
+                console.print(f"[green]✓[/green] Default project: {projects[idx].name}")
+
+    # Build and save config
+    new_cfg = load_config()
+    new_cfg.api_key = api_key
+    new_cfg.workspace_slug = workspace_slug
+    new_cfg.base_url = base_url
+    if default_project:
+        new_cfg.project = default_project
+
+    save_config(new_cfg)
+    console.print(f"\n[green]✓[/green] Config saved to {CONFIG_PATH}")
+    print_json(config_as_dict(new_cfg))

plane_cli-0.1.0/plane_cli/commands/issues.py

@@ -0,0 +1,317 @@
+"""issues subcommand: list / get / create / update / delete + comment add/list."""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+import typer
+from plane.models.work_items import (
+    CreateWorkItem,
+    CreateWorkItemComment,
+    UpdateWorkItem,
+)
+from plane.models.query_params import WorkItemQueryParams
+
+from plane_cli.client import get_client, call_with_retry
+from plane_cli.config import Config
+from plane_cli.output import (
+    build_comments_table,
+    build_issues_table,
+    out_console,
+    print_error,
+    print_json,
+    read_text_arg,
+)
+
+app = typer.Typer(name="issues", help="Manage issues (work items).", no_args_is_help=True)
+comment_app = typer.Typer(name="comment", help="Manage issue comments.", no_args_is_help=True)
+app.add_typer(comment_app)
+
+_VALID_PRIORITIES = ("urgent", "high", "medium", "low", "none")
+_MAX_ALL_PAGES = 1000
+
+
+def _issue_to_dict(issue: object) -> dict:
+    return issue.model_dump() if hasattr(issue, "model_dump") else dict(issue)
+
+
+def _resolve_project(cfg: Config, project_flag: Optional[str]) -> str:
+    project_id = project_flag or cfg.project
+    if not project_id:
+        print_error(
+            "config_error",
+            "No project specified. Use --project or set defaults.project in config.",
+        )
+        raise typer.Exit(1)
+    return project_id
+
+
+@app.command("list")
+def issues_list(
+    ctx: typer.Context,
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    state: Optional[str] = typer.Option(None, "--state", help="Filter by state ID"),
+    priority: Optional[str] = typer.Option(None, "--priority", help="Filter by priority"),
+    label: Optional[List[str]] = typer.Option(None, "--label", help="Filter by label ID (repeatable)"),
+    assignee: Optional[List[str]] = typer.Option(None, "--assignee", help="Filter by assignee ID (repeatable)"),
+    page: int = typer.Option(1, "--page", help="Page number"),
+    per_page: Optional[int] = typer.Option(None, "--per-page", help="Results per page"),
+    all_pages: bool = typer.Option(False, "--all", help="Fetch all pages (cap: 1000)"),
+) -> None:
+    """List issues in a project."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+    client = get_client(cfg)
+
+    effective_per_page = per_page or cfg.per_page
+
+    if all_pages:
+        all_issues: list[dict] = []
+        cursor: Optional[str] = None
+
+        while True:
+            params = WorkItemQueryParams(per_page=effective_per_page)
+            if cursor:
+                params.cursor = cursor
+
+            response = call_with_retry(
+                client.work_items.list, cfg.workspace_slug, project_id, params
+            )
+            batch = [_issue_to_dict(i) for i in (response.results or [])]
+            all_issues.extend(batch)
+
+            if len(all_issues) >= _MAX_ALL_PAGES:
+                from plane_cli.output import err_console
+                err_console.print(
+                    f"[yellow]Warning: reached {_MAX_ALL_PAGES} issue limit; stopping pagination.[/yellow]"
+                )
+                all_issues = all_issues[:_MAX_ALL_PAGES]
+                break
+
+            if not response.next_page_results:
+                break
+            cursor = response.next_cursor
+
+        issues = all_issues
+    else:
+        # Manual single-page fetch
+        # cursor-based: build cursor from page number
+        cursor_str: Optional[str] = None
+        if page > 1:
+            # Plane uses cursor format: "per_page:offset:0" style but the SDK
+            # exposes next_cursor strings from responses. For manual page navigation
+            # we use the offset pattern.
+            offset = (page - 1) * effective_per_page
+            cursor_str = f"{effective_per_page}:{offset}:0"
+
+        params = WorkItemQueryParams(per_page=effective_per_page)
+        if cursor_str:
+            params.cursor = cursor_str
+
+        response = call_with_retry(
+            client.work_items.list, cfg.workspace_slug, project_id, params
+        )
+        issues = [_issue_to_dict(i) for i in (response.results or [])]
+
+    if cfg.pretty:
+        table = build_issues_table(issues)
+        out_console.print(table)
+    else:
+        print_json(issues)
+
+
+@app.command("get")
+def issues_get(
+    ctx: typer.Context,
+    issue_id: str = typer.Argument(..., help="Issue ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+) -> None:
+    """Get a single issue by ID."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+    client = get_client(cfg)
+
+    issue = call_with_retry(
+        client.work_items.retrieve, cfg.workspace_slug, project_id, issue_id
+    )
+    print_json(_issue_to_dict(issue))
+
+
+@app.command("create")
+def issues_create(
+    ctx: typer.Context,
+    title: str = typer.Option(..., "--title", "-t", help="Issue title"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    description: Optional[str] = typer.Option(
+        None, "--description", "-d", help="Description or '-' for stdin"
+    ),
+    state: Optional[str] = typer.Option(None, "--state", help="State ID"),
+    priority: Optional[str] = typer.Option(
+        None, "--priority", help=f"Priority: {', '.join(_VALID_PRIORITIES)}"
+    ),
+    label: Optional[List[str]] = typer.Option(None, "--label", help="Label ID (repeatable)"),
+    assignee: Optional[List[str]] = typer.Option(None, "--assignee", help="Assignee ID (repeatable)"),
+    due_date: Optional[str] = typer.Option(None, "--due-date", help="Due date YYYY-MM-DD"),
+) -> None:
+    """Create a new issue."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    if priority is not None and priority not in _VALID_PRIORITIES:
+        print_error(
+            "validation_error",
+            f"Invalid priority '{priority}'. Choose from: {', '.join(_VALID_PRIORITIES)}",
+        )
+        raise typer.Exit(1)
+
+    data_kwargs: dict = {"name": title}
+
+    if description is not None:
+        desc_text = read_text_arg(description)
+        data_kwargs["description_html"] = f"<p>{desc_text}</p>"
+        data_kwargs["description_stripped"] = desc_text
+
+    if state is not None:
+        data_kwargs["state"] = state
+    if priority is not None:
+        data_kwargs["priority"] = priority
+    if label:
+        data_kwargs["labels"] = list(label)
+    if assignee:
+        data_kwargs["assignees"] = list(assignee)
+    if due_date is not None:
+        data_kwargs["target_date"] = due_date
+
+    client = get_client(cfg)
+    data = CreateWorkItem(**data_kwargs)
+    issue = call_with_retry(client.work_items.create, cfg.workspace_slug, project_id, data)
+    print_json(_issue_to_dict(issue))
+
+
+@app.command("update")
+def issues_update(
+    ctx: typer.Context,
+    issue_id: str = typer.Argument(..., help="Issue ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    title: Optional[str] = typer.Option(None, "--title", "-t"),
+    description: Optional[str] = typer.Option(
+        None, "--description", "-d", help="Description or '-' for stdin"
+    ),
+    state: Optional[str] = typer.Option(None, "--state", help="State ID"),
+    priority: Optional[str] = typer.Option(None, "--priority"),
+    label: Optional[List[str]] = typer.Option(None, "--label", help="Label ID (repeatable)"),
+    due_date: Optional[str] = typer.Option(None, "--due-date", help="Due date YYYY-MM-DD"),
+) -> None:
+    """Update an issue."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    data_kwargs: dict = {}
+
+    if title is not None:
+        data_kwargs["name"] = title
+    if description is not None:
+        desc_text = read_text_arg(description)
+        data_kwargs["description_html"] = f"<p>{desc_text}</p>"
+        data_kwargs["description_stripped"] = desc_text
+    if state is not None:
+        data_kwargs["state"] = state
+    if priority is not None:
+        if priority not in _VALID_PRIORITIES:
+            print_error(
+                "validation_error",
+                f"Invalid priority '{priority}'. Choose from: {', '.join(_VALID_PRIORITIES)}",
+            )
+            raise typer.Exit(1)
+        data_kwargs["priority"] = priority
+    if label:
+        data_kwargs["labels"] = list(label)
+    if due_date is not None:
+        data_kwargs["target_date"] = due_date
+
+    if not data_kwargs:
+        print_error("validation_error", "No fields to update.")
+        raise typer.Exit(1)
+
+    client = get_client(cfg)
+    data = UpdateWorkItem(**data_kwargs)
+    issue = call_with_retry(
+        client.work_items.update, cfg.workspace_slug, project_id, issue_id, data
+    )
+    print_json(_issue_to_dict(issue))
+
+
+@app.command("delete")
+def issues_delete(
+    ctx: typer.Context,
+    issue_id: str = typer.Argument(..., help="Issue ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete an issue."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    if not yes and not sys.stdin.isatty():
+        print_error("validation_error", "Pass --yes for non-interactive deletion.")
+        raise typer.Exit(1)
+    if not yes:
+        typer.confirm(f"Delete issue {issue_id}?", abort=True)
+
+    client = get_client(cfg)
+    call_with_retry(client.work_items.delete, cfg.workspace_slug, project_id, issue_id)
+    print_json({"ok": True, "deleted": issue_id})
+
+
+# ---------------------------------------------------------------------------
+# comment sub-subcommand
+# ---------------------------------------------------------------------------
+
+@comment_app.command("list")
+def comment_list(
+    ctx: typer.Context,
+    issue_id: str = typer.Argument(..., help="Issue ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+) -> None:
+    """List comments on an issue."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+    client = get_client(cfg)
+
+    response = call_with_retry(
+        client.work_items.comments.list, cfg.workspace_slug, project_id, issue_id
+    )
+    comments = [_issue_to_dict(c) for c in (response.results or [])]
+
+    if cfg.pretty:
+        table = build_comments_table(comments)
+        out_console.print(table)
+    else:
+        print_json(comments)
+
+
+@comment_app.command("add")
+def comment_add(
+    ctx: typer.Context,
+    issue_id: str = typer.Argument(..., help="Issue ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    body: str = typer.Option(..., "--body", "-b", help="Comment body or '-' for stdin"),
+) -> None:
+    """Add a comment to an issue."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    body_text = read_text_arg(body)
+    comment_html = f"<p>{body_text}</p>"
+
+    client = get_client(cfg)
+    data = CreateWorkItemComment(comment_html=comment_html)
+    comment = call_with_retry(
+        client.work_items.comments.create,
+        cfg.workspace_slug,
+        project_id,
+        issue_id,
+        data,
+    )
+    print_json(_issue_to_dict(comment))

plane_cli-0.1.0/plane_cli/commands/labels.py

@@ -0,0 +1,141 @@
+"""labels subcommand: list / get / create / update / delete."""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+from plane.models.labels import CreateLabel, UpdateLabel
+
+from plane_cli.client import get_client, call_with_retry
+from plane_cli.config import Config
+from plane_cli.output import (
+    print_json,
+    print_error,
+    build_labels_table,
+    out_console,
+)
+
+app = typer.Typer(name="labels", help="Manage work item labels.", no_args_is_help=True)
+
+
+def _label_to_dict(lb: object) -> dict:
+    return lb.model_dump() if hasattr(lb, "model_dump") else dict(lb)
+
+
+def _resolve_project(cfg: Config, project_flag: Optional[str]) -> str:
+    project_id = project_flag or cfg.project
+    if not project_id:
+        print_error(
+            "config_error",
+            "No project specified. Use --project or set defaults.project in config.",
+        )
+        raise typer.Exit(1)
+    return project_id
+
+
+@app.command("list")
+def labels_list(
+    ctx: typer.Context,
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+) -> None:
+    """List all labels in a project."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+    client = get_client(cfg)
+
+    response = call_with_retry(client.labels.list, cfg.workspace_slug, project_id)
+    labels = [_label_to_dict(lb) for lb in (response.results or [])]
+
+    if cfg.pretty:
+        table = build_labels_table(labels)
+        out_console.print(table)
+    else:
+        print_json(labels)
+
+
+@app.command("get")
+def labels_get(
+    ctx: typer.Context,
+    label_id: str = typer.Argument(..., help="Label ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+) -> None:
+    """Get a single label by ID."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+    client = get_client(cfg)
+
+    label = call_with_retry(client.labels.retrieve, cfg.workspace_slug, project_id, label_id)
+    print_json(_label_to_dict(label))
+
+
+@app.command("create")
+def labels_create(
+    ctx: typer.Context,
+    name: str = typer.Option(..., "--name", "-n", help="Label name"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    color: Optional[str] = typer.Option(None, "--color", help="Hex color code"),
+) -> None:
+    """Create a new label."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    data_kwargs: dict = {"name": name}
+    if color is not None:
+        data_kwargs["color"] = color
+
+    client = get_client(cfg)
+    data = CreateLabel(**data_kwargs)
+    label = call_with_retry(client.labels.create, cfg.workspace_slug, project_id, data)
+    print_json(_label_to_dict(label))
+
+
+@app.command("update")
+def labels_update(
+    ctx: typer.Context,
+    label_id: str = typer.Argument(..., help="Label ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    name: Optional[str] = typer.Option(None, "--name", "-n"),
+    color: Optional[str] = typer.Option(None, "--color"),
+) -> None:
+    """Update a label."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    data_kwargs: dict = {}
+    if name is not None:
+        data_kwargs["name"] = name
+    if color is not None:
+        data_kwargs["color"] = color
+
+    if not data_kwargs:
+        print_error("validation_error", "No fields to update.")
+        raise typer.Exit(1)
+
+    client = get_client(cfg)
+    data = UpdateLabel(**data_kwargs)
+    label = call_with_retry(client.labels.update, cfg.workspace_slug, project_id, label_id, data)
+    print_json(_label_to_dict(label))
+
+
+@app.command("delete")
+def labels_delete(
+    ctx: typer.Context,
+    label_id: str = typer.Argument(..., help="Label ID"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete a label."""
+    cfg: Config = ctx.obj
+    project_id = _resolve_project(cfg, project)
+
+    if not yes and not sys.stdin.isatty():
+        print_error("validation_error", "Pass --yes for non-interactive deletion.")
+        raise typer.Exit(1)
+    if not yes:
+        typer.confirm(f"Delete label {label_id}?", abort=True)
+
+    client = get_client(cfg)
+    call_with_retry(client.labels.delete, cfg.workspace_slug, project_id, label_id)
+    print_json({"ok": True, "deleted": label_id})