clinear 0.2.0__py3-none-any.whl

VERSION

@@ -0,0 +1 @@
+0.2.0

clinear/__init__.py

@@ -0,0 +1,22 @@
+"""clinear — Type-safe Linear CLI built on Pydantic v2."""
+
+from pathlib import Path
+
+
+def _read_version() -> str:
+    """Read version from VERSION file at the repo root.
+
+    Falls back to a hardcoded string if the file is missing (e.g. when
+    installed from a wheel where VERSION isn't packaged).
+    """
+    try:
+        version_file = Path(__file__).resolve().parent.parent / "VERSION"
+        if version_file.is_file():
+            return version_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        pass
+    return "0.2.0"
+
+
+__version__ = _read_version()
+__all__ = ["__version__"]

clinear/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m clinear`."""
+
+from clinear.cli import app
+
+if __name__ == "__main__":
+    app()

clinear/auth.py

@@ -0,0 +1,43 @@
+"""Authentication helpers.
+
+Token resolution lives in `config.py`. This module wraps viewer caching
+so we can resolve "me" without an extra API call when the user passes
+`--assignee me`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from clinear.client import LinearClient
+from clinear.graphql import queries
+from clinear.models.user import User
+
+
+_viewer_cache: User | None = None
+_viewer_lock = asyncio.Lock()
+
+
+async def get_viewer(client: LinearClient, *, refresh: bool = False) -> User:
+    """Return the currently-authenticated user.
+
+    Cached per-process so repeated --assignee me resolutions don't
+    cost an API call each.
+    """
+    global _viewer_cache
+    if _viewer_cache is not None and not refresh:
+        return _viewer_cache
+
+    async with _viewer_lock:
+        if _viewer_cache is not None and not refresh:
+            return _viewer_cache
+        _viewer_cache = await client.execute_as(
+            User, queries.VIEWER, path=["viewer"], operation="Viewer"
+        )
+        return _viewer_cache
+
+
+def reset_viewer_cache() -> None:
+    """Reset cached viewer (used after logout/token change)."""
+    global _viewer_cache
+    _viewer_cache = None

clinear/cli.py

@@ -0,0 +1,122 @@
+"""Root CLI entrypoint.
+
+Defines the top-level Typer app, global flags, error handling, and
+registers all subcommand modules.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+
+from clinear import __version__
+from clinear.cli_state import CLIState, set_state
+from clinear.commands.auth_cmd import auth_app, me_app
+from clinear.commands.comment import comment_app
+from clinear.commands.cycle import cycle_app
+from clinear.commands.init import init_app
+from clinear.commands.issue import issue_app
+from clinear.commands.label import label_app
+from clinear.commands.project import project_app
+from clinear.commands.raw import raw_app
+from clinear.commands.team import team_app
+from clinear.config import load_config, resolve_token
+from clinear.errors import ClinearError
+from clinear.models.enums import OutputFormat
+from clinear.output import emit_error
+
+
+app = typer.Typer(
+    name="clinear",
+    help="Type-safe Linear CLI built on Pydantic v2 + httpx + Typer",
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+)
+
+
+def _version_cb(value: bool) -> None:
+    if value:
+        typer.echo(f"clinear {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    token: Optional[str] = typer.Option(None, "--token", envvar=None, help="Linear API token (overrides $LINEAR_TOKEN)"),
+    output: OutputFormat = typer.Option(OutputFormat.HUMAN, "--output", "-o", help="Output format"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Print GraphQL operations to stderr"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress non-essential output"),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable ANSI colors"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print mutations without executing"),
+    timeout: float = typer.Option(30.0, "--timeout", help="HTTP timeout in seconds"),
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=_version_cb, is_eager=True, help="Show version and exit"
+    ),
+) -> None:
+    """Global flags applied before any subcommand."""
+    # Resolve config + token
+    config = load_config()
+
+    # Token resolution: only required for commands that hit the API.
+    # We defer the actual AuthError to first API call to allow `--help` etc.
+    try:
+        resolved_token = resolve_token(token, config)
+    except ClinearError:
+        resolved_token = ""
+
+    state = CLIState(
+        token=resolved_token,
+        config=config,
+        output=output,
+        verbose=verbose,
+        quiet=quiet,
+        no_color=no_color,
+        dry_run=dry_run,
+        timeout=timeout,
+    )
+    set_state(state)
+
+
+# Register subcommands
+app.add_typer(me_app, name="me")
+app.add_typer(auth_app, name="auth")
+app.add_typer(init_app, name="init")
+app.add_typer(team_app, name="team")
+app.add_typer(issue_app, name="issue")
+app.add_typer(project_app, name="project")
+app.add_typer(cycle_app, name="cycle")
+app.add_typer(comment_app, name="comment")
+app.add_typer(label_app, name="label")
+app.add_typer(raw_app, name="raw")
+
+
+def _entry() -> None:
+    """Wrap typer_app() with consistent error handling and exit codes."""
+    try:
+        typer_app()
+    except ClinearError as e:
+        from clinear.cli_state import get_state
+        state = get_state()
+        if state.output == OutputFormat.JSON:
+            import json as _json
+            print(_json.dumps(e.to_dict(), indent=2), file=sys.stderr)
+        else:
+            emit_error(e.message, hint=e.hint)
+        sys.exit(int(e.exit_code))
+    except KeyboardInterrupt:
+        emit_error("Interrupted")
+        sys.exit(130)
+
+
+# Public callable for `clinear` script entry point in pyproject.toml.
+# Renamed to `typer_app` internally so the wrapper is what pip-installed
+# `clinear` actually invokes.
+typer_app = app
+app = _entry  # type: ignore[assignment]
+
+
+if __name__ == "__main__":
+    _entry()

clinear/cli_state.py

@@ -0,0 +1,50 @@
+"""Shared CLI state — populated by the root callback, read by subcommands.
+
+Typer doesn't have a great way to share state across commands without going
+through Context. We use a small module-level container to keep subcommands
+clean.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from clinear.client import LinearClient
+from clinear.config import Config
+from clinear.models.enums import OutputFormat
+
+
+@dataclass
+class CLIState:
+    """Mutable per-invocation state."""
+
+    token: str = ""
+    config: Config = field(default_factory=Config)
+    output: OutputFormat = OutputFormat.HUMAN
+    verbose: bool = False
+    quiet: bool = False
+    no_color: bool = False
+    dry_run: bool = False
+    timeout: float = 30.0
+
+
+_state = CLIState()
+
+
+def get_state() -> CLIState:
+    return _state
+
+
+def set_state(state: CLIState) -> None:
+    global _state
+    _state = state
+
+
+def build_client(state: CLIState | None = None) -> LinearClient:
+    """Construct a LinearClient configured from the current CLI state."""
+    s = state or _state
+    return LinearClient(
+        token=s.token,
+        timeout=s.timeout,
+        verbose=s.verbose,
+    )

clinear/client.py

@@ -0,0 +1,265 @@
+"""Async GraphQL client for the Linear API.
+
+Design goals:
+- Single httpx.AsyncClient with sensible defaults (HTTP/2, timeout, retries).
+- Token never logged in plaintext (redacted in verbose mode).
+- Linear errors lifted into typed exceptions.
+- Rate limit awareness (X-RateLimit-* headers honored).
+- Cursor-based pagination helper.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, AsyncIterator, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from clinear import __version__
+from clinear.config import redact_token
+from clinear.errors import (
+    APIError,
+    AuthError,
+    NetworkError,
+    RateLimitError,
+    ValidationError,
+)
+
+logger = logging.getLogger("clinear.client")
+
+LINEAR_API_URL = "https://api.linear.app/graphql"
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class LinearClient:
+    """Async GraphQL client for the Linear API."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str = LINEAR_API_URL,
+        timeout: float = 30.0,
+        verbose: bool = False,
+    ) -> None:
+        self._token = token
+        self._base_url = base_url
+        self._verbose = verbose
+        self._http = httpx.AsyncClient(
+            http2=False,  # httpx[http2] is a separate dep — keep deps minimal
+            timeout=timeout,
+            headers={
+                "Authorization": token,
+                "Content-Type": "application/json",
+                "User-Agent": f"clinear/{__version__} (+https://github.com/Clover/clinear)",
+            },
+        )
+
+    async def __aenter__(self) -> "LinearClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    # ------------------------------------------------------------------
+    # Core request method
+    # ------------------------------------------------------------------
+
+    async def execute(
+        self,
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        operation: str | None = None,
+    ) -> dict[str, Any]:
+        """Execute a GraphQL query/mutation. Returns the `data` portion.
+
+        Raises:
+            AuthError: 401
+            RateLimitError: 429
+            APIError: GraphQL errors in response
+            NetworkError: transport-level failures
+        """
+        payload: dict[str, Any] = {"query": query}
+        if variables:
+            # Drop None values — Linear's API rejects explicit nulls in many inputs
+            payload["variables"] = _strip_none(variables)
+        if operation:
+            payload["operationName"] = operation
+
+        if self._verbose:
+            logger.info(
+                "POST %s [token=%s] op=%s vars=%s",
+                self._base_url,
+                redact_token(self._token),
+                operation or "<anon>",
+                json.dumps(payload.get("variables", {}), default=str)[:200],
+            )
+
+        try:
+            resp = await self._http.post(self._base_url, json=payload)
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+        except httpx.RequestError as e:
+            raise NetworkError(f"Network error: {e}") from e
+
+        # Handle HTTP-level errors
+        if resp.status_code == 401:
+            raise AuthError(
+                "Linear rejected the token (HTTP 401)",
+                hint="Generate a new token at https://linear.app/settings/api",
+            )
+        if resp.status_code == 429:
+            retry = resp.headers.get("Retry-After")
+            raise RateLimitError(
+                "Linear API rate limit exceeded",
+                retry_after=int(retry) if retry and retry.isdigit() else None,
+            )
+        if resp.status_code >= 500:
+            raise APIError(
+                f"Linear API returned HTTP {resp.status_code}",
+                hint="This is usually transient — retry in a few seconds",
+            )
+        if resp.status_code >= 400:
+            raise APIError(
+                f"HTTP {resp.status_code}: {resp.text[:500]}",
+            )
+
+        try:
+            body = resp.json()
+        except json.JSONDecodeError as e:
+            raise APIError(f"Non-JSON response from Linear: {e}") from e
+
+        # GraphQL-level errors
+        if errors := body.get("errors"):
+            messages = "; ".join(e.get("message", "<unknown>") for e in errors)
+            raise APIError(messages, errors=errors)
+
+        data = body.get("data")
+        if data is None:
+            raise APIError("Linear returned empty data")
+        return data
+
+    # ------------------------------------------------------------------
+    # Typed helpers
+    # ------------------------------------------------------------------
+
+    async def execute_as(
+        self,
+        model: type[T],
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        path: list[str] | None = None,
+        operation: str | None = None,
+    ) -> T:
+        """Execute and validate the response against a Pydantic model.
+
+        path: list of dict keys to drill down to before parsing.
+            e.g. ["viewer"] turns {"viewer": {...}} into the viewer object.
+        """
+        data = await self.execute(query, variables, operation=operation)
+        node: Any = data
+        for key in path or []:
+            if not isinstance(node, dict) or key not in node:
+                raise ValidationError(
+                    f"Expected key {key!r} in response path "
+                    f"{'.'.join(path or [])}",
+                )
+            node = node[key]
+        try:
+            return model.model_validate(node)
+        except Exception as e:
+            raise ValidationError(
+                f"Response did not match {model.__name__}: {e}",
+            ) from e
+
+    async def execute_list(
+        self,
+        model: type[T],
+        query: str,
+        variables: dict[str, Any] | None = None,
+        *,
+        path: list[str],
+        operation: str | None = None,
+    ) -> list[T]:
+        """Execute and validate a connection.nodes list response.
+
+        path should end at the dict containing 'nodes'.
+        """
+        data = await self.execute(query, variables, operation=operation)
+        node: Any = data
+        for key in path:
+            if not isinstance(node, dict) or key not in node:
+                raise ValidationError(
+                    f"Expected key {key!r} at path {'.'.join(path)}",
+                )
+            node = node[key]
+        if not isinstance(node, dict) or "nodes" not in node:
+            raise ValidationError(
+                "Expected a connection object with 'nodes' at path "
+                f"{'.'.join(path)}"
+            )
+        try:
+            return [model.model_validate(item) for item in node["nodes"]]
+        except Exception as e:
+            raise ValidationError(
+                f"List items did not match {model.__name__}: {e}",
+            ) from e
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    async def paginate(
+        self,
+        query: str,
+        variables: dict[str, Any],
+        *,
+        path: list[str],
+        page_size: int = 50,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Yield every node across all pages of a connection."""
+        cursor: str | None = None
+        while True:
+            vars_with_cursor = {**variables, "first": page_size}
+            if cursor:
+                vars_with_cursor["after"] = cursor
+            data = await self.execute(query, vars_with_cursor)
+            node: Any = data
+            for key in path:
+                node = node[key]
+            for item in node.get("nodes", []):
+                yield item
+            page_info = node.get("pageInfo") or {}
+            if not page_info.get("hasNextPage"):
+                break
+            cursor = page_info.get("endCursor")
+            if not cursor:
+                break
+
+
+def _strip_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Recursively remove None values from a dict for GraphQL variables."""
+    if not isinstance(d, dict):
+        return d
+    out: dict[str, Any] = {}
+    for k, v in d.items():
+        if v is None:
+            continue
+        if isinstance(v, dict):
+            stripped = _strip_none(v)
+            if stripped:
+                out[k] = stripped
+        elif isinstance(v, list):
+            out[k] = [_strip_none(item) if isinstance(item, dict) else item for item in v]
+        else:
+            out[k] = v
+    return out

clinear/commands/__init__.py

@@ -0,0 +1,4 @@
+"""Command modules.
+
+Each file exports a Typer sub-app registered in clinear.cli.
+"""

clinear/commands/auth_cmd.py

@@ -0,0 +1,42 @@
+"""`clinear me` and `clinear auth ...` commands."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+
+from clinear.auth import get_viewer
+from clinear.cli_state import build_client, get_state
+from clinear.models.enums import OutputFormat
+from clinear.output import render
+
+me_app = typer.Typer(help="Show the currently-authenticated Linear user")
+auth_app = typer.Typer(help="Authentication operations")
+
+
+@me_app.callback(invoke_without_command=True)
+def me(ctx: typer.Context) -> None:
+    """Show the currently-authenticated user (alias for `auth status`)."""
+    if ctx.invoked_subcommand is not None:
+        return
+    asyncio.run(_run_me())
+
+
+@auth_app.command("status")
+def status() -> None:
+    """Show the currently-authenticated user and token source."""
+    asyncio.run(_run_me())
+
+
+@auth_app.command("whoami")
+def whoami() -> None:
+    """Alias of `auth status`."""
+    asyncio.run(_run_me())
+
+
+async def _run_me() -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        viewer = await get_viewer(client)
+        render(viewer, fmt=state.output, title="Viewer")