vikunja-python 0.1.0__py3-none-any.whl

vikunja_python/cli/main.py

@@ -0,0 +1,264 @@
+import asyncio
+import os
+from typing import Optional, List
+import typer
+import httpx
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich import print as rprint
+from dotenv import load_dotenv
+
+from vikunja_python.core.client import VikunjaClient
+from vikunja_python.core.models.task import Task
+from vikunja_python.core.models.project import Project
+
+load_dotenv()
+
+app = typer.Typer(help="Vikunja CLI - Manage your tasks from the terminal")
+console = Console()
+
+def get_client():
+    base_url = os.getenv("VIKUNJA_URL")
+    token = os.getenv("VIKUNJA_API_TOKEN")
+    if not base_url or not token:
+        rprint("[bold red]Error:[/bold red] VIKUNJA_URL and VIKUNJA_API_TOKEN must be set in .env")
+        raise typer.Exit(1)
+    return VikunjaClient(base_url, token)
+
+@app.command()
+def list_tasks(
+    project_id: Optional[int] = typer.Option(None, "--project-id", "-p", help="Project ID to list tasks from"),
+    page: int = typer.Option(1, help="Page number"),
+    per_page: int = typer.Option(20, help="Items per page"),
+    filter: Optional[str] = typer.Option(None, help="Vikunja filter string"),
+    expand: Optional[List[str]] = typer.Option(
+        None, 
+        help=(
+            "Fields to expand: 'subtasks', 'comments', 'reactions', 'buckets', 'comment_count', 'is_unread'. "
+            "Note: list-tasks returns descriptions and assignees by default."
+        )
+    )
+):
+    """List tasks with rich formatting."""
+    async def _list():
+        async with get_client() as client:
+            params = {"page": page, "per_page": per_page}
+            if filter: params["filter"] = filter
+            if expand: params["expand"] = expand
+            
+            if project_id is None:
+                path = "/tasks"
+            elif project_id < 0:
+                path = "/tasks"
+                params["project_id"] = project_id
+            else:
+                path = f"/projects/{project_id}/tasks"
+            data = await client.request("GET", path, params=params)
+            
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+                return
+
+            table = Table(title="Vikunja Tasks")
+            table.add_column("ID", style="cyan", no_wrap=True)
+            table.add_column("Status", width=6)
+            table.add_column("Title", style="magenta")
+            table.add_column("Assignees", style="green")
+            table.add_column("Due Date", style="yellow")
+            table.add_column("Labels", style="blue")
+
+            tasks = [Task(**item) for item in data]
+            for t in tasks:
+                status = "[green]DONE[/green]" if t.done else "[yellow]TODO[/yellow]"
+                due = t.due_date.strftime("%Y-%m-%d %H:%M") if t.due_date else ""
+                labels = ", ".join(l.title for l in t.labels) if t.labels else ""
+                assignees = ", ".join(u.username for u in t.assignees) if t.assignees else ""
+                
+                table.add_row(str(t.id), status, t.title, assignees, due, labels)
+                if t.description:
+                    # Add description preview in a dimmed style
+                    desc = t.description.split('\n')[0]
+                    if len(desc) > 80: desc = desc[:77] + "..."
+                    table.add_row("", "", f"[dim]  Desc: {desc}[/dim]", "", "", "")
+
+            console.print(table)
+
+    asyncio.run(_list())
+
+@app.command()
+def list_saved_filter(
+    filter_id: int = typer.Option(..., "--filter-id", "-f", help="Saved filter ID (negative, e.g., -2 for Due in 3 Days, -3 Overdue, -4 Due Today)"),
+    page: int = typer.Option(1, help="Page number"),
+    per_page: int = typer.Option(50, help="Items per page"),
+):
+    """List tasks from a saved filter."""
+    async def _list():
+        async with get_client() as client:
+            params = {"page": page, "per_page": per_page, "project_id": filter_id}
+            data = await client.request("GET", "/tasks", params=params)
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+                return
+
+            table = Table(title=f"Saved Filter {filter_id}")
+            table.add_column("ID", style="cyan", no_wrap=True)
+            table.add_column("Status", width=6)
+            table.add_column("Title", style="magenta")
+            table.add_column("Due Date", style="yellow")
+            table.add_column("Labels", style="blue")
+
+            tasks = [Task(**item) for item in data]
+            for t in tasks:
+                status = "[green]DONE[/green]" if t.done else "[yellow]TODO[/yellow]"
+                due = t.due_date.strftime("%Y-%m-%d %H:%M") if t.due_date else ""
+                labels = ", ".join(l.title for l in t.labels) if t.labels else ""
+                table.add_row(str(t.id), status, t.title, due, labels)
+
+            console.print(table)
+    asyncio.run(_list())
+
+@app.command()
+def summary(
+    top_n: int = typer.Option(5, "--top", "-t", help="Number of top tasks to show per filter"),
+):
+    """Quick dashboard summary — counts and top tasks for overdue, due today, due soon."""
+    async def _summary():
+        async with get_client() as client:
+            data = await client.get_dashboard_summary()
+            rprint(f"[bold white]Vikunja Task Summary: {data['total']} urgent[/bold white]")
+            for section in ["overdue", "due_today", "due_soon"]:
+                s = data["filters"].get(section, {})
+                labels = {"overdue": "🔴 Overdue", "due_today": "🟡 Due Today", "due_soon": "🟢 Due in 3 Days"}
+                rprint(f"\n[bold]{labels.get(section, section)} ({s.get('count', 0)})[/bold]")
+                for t in s.get("tasks", [])[:top_n]:
+                    due = t.get("due_date", "")
+                    if due and due.startswith("0001"):
+                        due = ""
+                    elif due and len(due) > 10:
+                        due = due[:10]
+                    due_str = f" ({due})" if due else ""
+                    rprint(f"  #{t['id']} {t['title']}{due_str}")
+                if not s.get("tasks"):
+                    rprint("  [dim]None 🎉[/dim]")
+    asyncio.run(_summary())
+
+@app.command()
+def get_project(project_id: int):
+    """Get project details and views."""
+    async def _get():
+        async with get_client() as client:
+            data = await client.request("GET", f"/projects/{project_id}")
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+                return
+            
+            p = Project(**data)
+            rprint(Panel(f"[bold cyan]Project:[/bold cyan] {p.title} (ID: {p.id})\n[dim]{p.description or 'No description'}[/dim]"))
+            
+            if p.views:
+                table = Table(title="Project Views")
+                table.add_column("ID", style="cyan")
+                table.add_column("Title", style="magenta")
+                table.add_column("Kind", style="yellow")
+                for v in p.views:
+                    table.add_row(str(v.get('id')), v.get('title'), v.get('view_kind'))
+                console.print(table)
+    asyncio.run(_get())
+
+@app.command()
+def list_view_tasks(project_id: int, view_id: int):
+    """List all tasks in a specific project view with full descriptions."""
+    async def _list():
+        async with get_client() as client:
+            data = await client.request("GET", f"/projects/{project_id}/views/{view_id}/tasks")
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+                return
+            
+            # Flatten buckets if needed
+            all_tasks = []
+            if isinstance(data, list) and len(data) > 0:
+                if "tasks" in data[0]:
+                    for bucket in data:
+                        for t_item in bucket.get("tasks", []):
+                            all_tasks.append(Task(**t_item))
+                else:
+                    all_tasks = [Task(**item) for item in data]
+            
+            for t in all_tasks:
+                status = "[green]DONE[/green]" if t.done else "[yellow]TODO[/yellow]"
+                rprint(f"[bold cyan]ID: {t.id}[/bold cyan] {status} [bold magenta]{t.title}[/bold magenta]")
+                if t.assignees:
+                    rprint(f"[dim]  Assignees: {', '.join(u.username for u in t.assignees)}[/dim]")
+                if t.description:
+                    rprint(Panel(t.description, subtitle="Description", border_style="dim"))
+                rprint("-" * 20)
+    asyncio.run(_list())
+
+@app.command()
+def get_task(task_id: int):
+    """Get full details for a single task."""
+    async def _get():
+        async with get_client() as client:
+            data = await client.request("GET", f"/tasks/{task_id}")
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+                return
+            
+            t = Task(**data)
+            status = "[bold green]DONE[/bold green]" if t.done else "[bold yellow]TODO[/bold yellow]"
+            
+            rprint(Panel(
+                f"[bold cyan]ID:[/bold cyan] {t.id} {status}\n"
+                f"[bold cyan]Title:[/bold cyan] {t.title}\n"
+                f"[bold cyan]Project:[/bold cyan] {t.project_id}\n"
+                f"[bold cyan]Due:[/bold cyan] {t.due_date or 'None'}\n"
+                f"[bold cyan]Priority:[/bold cyan] {t.priority}\n"
+                f"[bold cyan]Labels:[/bold cyan] {', '.join(l.title for l in t.labels) if t.labels else 'None'}\n"
+                f"[bold cyan]Assignees:[/bold cyan] {', '.join(u.username for u in t.assignees) if t.assignees else 'None'}\n\n"
+                f"[bold white]Description:[/bold white]\n{t.description or 'No description'}",
+                title=f"Task {t.id}",
+                border_style="blue"
+            ))
+    asyncio.run(_get())
+
+@app.command()
+def create_task(
+    title: str, 
+    project_id: int, 
+    description: Optional[str] = typer.Option(None, help="Task description"),
+    due_date: Optional[str] = typer.Option(None, help="Due date (natural language ok)")
+):
+    """Create a new task."""
+    async def _create():
+        async with get_client() as client:
+            payload = {"title": title}
+            if description: payload["description"] = description
+            if due_date: payload["due_date"] = due_date
+            
+            data = await client.request("PUT", f"/projects/{project_id}/tasks", json=payload)
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+            else:
+                rprint(f"[bold green]Task created![/bold green] ID: {data['id']}")
+
+    asyncio.run(_create())
+
+@app.command()
+def create_label(title: str, hex_color: Optional[str] = typer.Option(None, help="Label color")):
+    """Create a new label."""
+    async def _create():
+        async with get_client() as client:
+            payload = {"title": title}
+            if hex_color: payload["hex_color"] = hex_color
+            data = await client.request("PUT", "/labels", json=payload)
+            if isinstance(data, dict) and "error" in data:
+                rprint(f"[bold red]Error:[/bold red] {data['error']}")
+            else:
+                rprint(f"[bold green]Label created![/bold green] ID: {data['id']} - {data['title']}")
+
+    asyncio.run(_create())
+
+if __name__ == "__main__":
+    app()

vikunja_python/core/client.py

@@ -0,0 +1,106 @@
+import os
+import sys
+import logging
+from typing import Optional
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+# Set up logging for CLI/MCP
+def setup_logging(is_mcp: bool = False):
+    # Support VIKUNJA_DEBUG=true or 1 to enable DEBUG logs
+    debug_val = os.getenv("VIKUNJA_DEBUG", "").lower()
+    level = logging.DEBUG if debug_val in ("1", "true", "yes", "on") else logging.INFO
+    
+    if is_mcp:
+        # MCP must log to stderr to avoid corrupting JSON-RPC on stdout
+        logging.basicConfig(
+            level=level,
+            format="%(levelname)s: %(message)s",
+            stream=sys.stderr,
+            force=True  # Ensure we override any default handlers from libraries
+        )
+    else:
+        logging.basicConfig(
+            level=level,
+            format="%(levelname)s: %(message)s",
+            force=True
+        )
+
+class VikunjaClient:
+    """
+    Core HTTP client for Vikunja API.
+    Handles both JWT and API Key authentication.
+    """
+    def __init__(self, base_url: str, token: str, is_api_key: bool = True):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.is_api_key = is_api_key
+        
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json"
+        }
+        # Respect SSL_CERT_FILE explicitly — more reliable than relying on
+        # certifi's env-var propagation which can be lost in subprocess spawns.
+        verify = os.environ.get("SSL_CERT_FILE") or os.environ.get("REQUESTS_CA_BUNDLE") or True
+        self.client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=30.0,
+            verify=verify,
+        )
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.client.aclose()
+
+    async def request(self, method: str, path: str, **kwargs):
+        """Wrapper for httpx requests with error handling."""
+        try:
+            resp = await self.client.request(method, path, **kwargs)
+            resp.raise_for_status()
+            if resp.status_code == 204:
+                return None
+            return resp.json()
+        except httpx.HTTPStatusError as e:
+            # Return structured error for LLM/CLI to digest
+            error_data = {"error": str(e), "status_code": e.response.status_code}
+            try:
+                error_data["details"] = e.response.json()
+            except:
+                error_data["details"] = e.response.text
+            return error_data
+        except Exception as e:
+            return {"error": str(e), "status_code": 500}
+
+    async def get_dashboard_summary(self) -> dict:
+        """Quick polling summary for ePaper dashboard. Queries saved filters in parallel."""
+        filters = {
+            "overdue": -3,
+            "due_today": -4,
+            "due_soon": -2,
+        }
+        import asyncio
+        async def fetch(label: str, filter_id: int) -> dict:
+            data = await self.request("GET", "/tasks", params={
+                "page": 1, "per_page": 10, "project_id": filter_id
+            })
+            if isinstance(data, dict) and "error" in data:
+                return {"label": label, "count": 0, "tasks": [], "error": data["error"]}
+            tasks = data if isinstance(data, list) else []
+            return {
+                "label": label,
+                "count": len(tasks),
+                "tasks": [
+                    {"id": t.get("id"), "title": t.get("title"),
+                     "due_date": t.get("due_date"), "priority": t.get("priority", 0)}
+                    for t in tasks[:10]
+                ]
+            }
+        results = await asyncio.gather(*[
+            fetch(label, fid) for label, fid in filters.items()
+        ])
+        total = sum(r["count"] for r in results)
+        return {"total": total, "filters": {r["label"]: r for r in results}}