Linear Skills

LINEAR_API_KEY=your_api_key_here

#!/usr/bin/env python3
"""
Linear Get Issue Skill

Fetch Linear issue details by ID using direct GraphQL API.
Zero external dependencies - uses only urllib and json from stdlib.
"""

import os
import sys
import json
import argparse
import urllib.request
import urllib.error
from pathlib import Path

# Load environment variables
# When installed in .claude/skills/linear-get-issue/, the structure is:
# .claude/skills/linear-get-issue/
#   ├── scripts/
#   │   └── get_issue.py (this file)
#   ├── .env
#   ├── .env.example
#   └── SKILL.md

script_dir = Path(__file__).parent  # scripts/
skill_root = script_dir.parent      # linear-get-issue/ (or linear-skills/)

# Possible .env locations in order of preference
env_locations = [
    skill_root / ".env",            # Skill directory (preferred)
    skill_root.parent / ".env",     # Project root (fallback)
]

for env_path in env_locations:
    if env_path.exists():
        with open(env_path) as f:
            for line in f:
                line = line.strip()
                if line and "=" in line and not line.startswith("#"):
                    key, value = line.split("=", 1)
                    os.environ[key.strip()] = value.strip()
        break


def get_api_key() -> str:
    """Get Linear API key from environment."""
    api_key = os.getenv("LINEAR_API_KEY")
    if not api_key:
        print(
            "Error: LINEAR_API_KEY environment variable not set.",
            file=sys.stderr,
        )
        print("Create a .env file with: LINEAR_API_KEY=your_key_here", file=sys.stderr)
        print(
            "Or run: export LINEAR_API_KEY='your_api_key_here'",
            file=sys.stderr,
        )
        sys.exit(1)
    return api_key


def fetch_issue_graphql(issue_id: str, api_key: str) -> dict:
    """
    Fetch Linear issue using GraphQL API.

    Args:
        issue_id: Linear issue identifier (e.g., "ENG-123")
        api_key: Linear API key

    Returns:
        Dictionary containing issue data

    Raises:
        ValueError: If issue not found or API error occurs
    """
    # GraphQL query to fetch issue details
    query = """
    query GetIssue($id: String!) {
      issue(id: $id) {
        id
        identifier
        title
        description
        priority
        url
        createdAt
        updatedAt
        state {
          id
          name
          type
        }
        assignee {
          id
          name
          email
        }
        team {
          id
          name
          key
        }
        labels(first: 20) {
          nodes {
            id
            name
            color
          }
        }
      }
    }
    """

    payload = {
        "query": query,
        "variables": {"id": issue_id}
    }

    try:
        req = urllib.request.Request(
            "https://api.linear.app/graphql",
            data=json.dumps(payload).encode("utf-8"),
            headers={
                "Content-Type": "application/json",
                "Authorization": api_key,
            },
        )

        with urllib.request.urlopen(req) as response:
            result = json.loads(response.read().decode("utf-8"))

    except urllib.error.HTTPError as e:
        error_body = e.read().decode("utf-8")
        try:
            error_json = json.loads(error_body)
            if error_json.get("errors"):
                error_msg = error_json["errors"][0].get("message", str(e))
            else:
                error_msg = error_body
        except json.JSONDecodeError:
            error_msg = error_body
        raise ValueError(f"API error: {error_msg}")
    except Exception as e:
        raise ValueError(f"Network error: {str(e)}")

    # Check for GraphQL errors
    if "errors" in result:
        error_msg = result["errors"][0].get("message", "Unknown error")
        raise ValueError(f"GraphQL error: {error_msg}")

    # Check if issue was found
    if not result.get("data") or not result["data"].get("issue"):
        raise ValueError(f"Issue '{issue_id}' not found")

    return result["data"]["issue"]


def priority_to_label(priority: int) -> str:
    """Convert priority number to human-readable label."""
    labels = {0: "No priority", 1: "Urgent", 2: "High", 3: "Medium", 4: "Low"}
    return labels.get(priority, "Unknown")


def format_pretty(issue: dict) -> str:
    """Format issue data for human-readable output."""
    lines = []

    # Header with identifier and title
    lines.append(f"\033[1;36m{issue['identifier']}: {issue['title']}\033[0m")

    # Status line
    state_name = issue["state"]["name"] if issue["state"] else "Unknown"
    lines.append(f"Status: {state_name}")

    # Priority
    lines.append(f"Priority: {priority_to_label(issue.get('priority', 0))}")

    # Assignee
    if issue.get("assignee"):
        lines.append(
            f"Assignee: {issue['assignee']['name']} ({issue['assignee']['email']})"
        )
    else:
        lines.append("Assignee: Unassigned")

    # Team
    if issue.get("team"):
        lines.append(f"Team: {issue['team']['name']}")

    # Labels
    if issue.get("labels") and issue["labels"].get("nodes"):
        label_names = ", ".join(label["name"] for label in issue["labels"]["nodes"])
        lines.append(f"Labels: {label_names}")

    # Description
    if issue.get("description"):
        lines.append("")
        lines.append("Description:")
        lines.append(issue["description"])

    # Footer with metadata
    lines.append("")
    lines.append(f"\033[90mURL: {issue['url']}\033[0m")
    if issue.get("createdAt"):
        lines.append(f"\033[90mCreated: {issue['createdAt']}\033[0m")
    if issue.get("updatedAt"):
        lines.append(f"\033[90mUpdated: {issue['updatedAt']}\033[0m")

    return "\n".join(lines)


def format_json(issue: dict) -> str:
    """Format issue data as JSON."""
    # Flatten the response for cleaner JSON output
    formatted = {
        "id": issue["id"],
        "identifier": issue["identifier"],
        "title": issue["title"],
        "description": issue.get("description") or "",
        "priority": priority_to_label(issue.get("priority", 0)),
        "url": issue["url"],
        "state": {
            "name": issue["state"]["name"] if issue["state"] else "Unknown",
            "type": issue["state"]["type"] if issue["state"] else "unknown",
        },
        "assignee": {
            "name": issue["assignee"]["name"],
            "email": issue["assignee"]["email"],
        }
        if issue.get("assignee")
        else None,
        "team": {
            "name": issue["team"]["name"],
            "key": issue["team"]["key"],
        }
        if issue.get("team")
        else None,
        "labels": [
            {"name": label["name"], "color": label["color"]}
            for label in (issue.get("labels", {}).get("nodes") or [])
        ],
        "created_at": issue.get("createdAt"),
        "updated_at": issue.get("updatedAt"),
    }
    return json.dumps(formatted, indent=2)


def main():
    """Parse arguments and fetch issue."""
    parser = argparse.ArgumentParser(
        description="Fetch Linear issue by ID",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python scripts/get_issue.py ENG-123
  python scripts/get_issue.py ENG-123 --json
  python scripts/get_issue.py ENG-123 --json | jq '.description'
        """,
    )

    parser.add_argument(
        "issue_id",
        help="Linear issue identifier (e.g., ENG-123)",
    )

    parser.add_argument(
        "--json",
        action="store_true",
        help="Output as JSON",
    )

    args = parser.parse_args()

    try:
        api_key = get_api_key()
        issue = fetch_issue_graphql(args.issue_id, api_key)

        if args.json:
            print(format_json(issue))
        else:
            print(format_pretty(issue))

    except ValueError as e:
        print(f"Error: {str(e)}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Unexpected error: {str(e)}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Linear Search Issues

Search Linear issues by number, title, status, or team.
Read-only skill that returns compact results for issue discovery.
"""

import os
import sys
import json
import argparse
import urllib.request
import urllib.error
from pathlib import Path

# Load environment variables
# When installed in .claude/skills/linear-get-issue/, the structure is:
# .claude/skills/linear-get-issue/
#   ├── scripts/
#   │   └── search_issues.py (this file)
#   ├── .env
#   ├── .env.example
#   └── SKILL.md

script_dir = Path(__file__).parent  # scripts/
skill_root = script_dir.parent      # linear-get-issue/ (or linear-skills/)

# Possible .env locations in order of preference
env_locations = [
    skill_root / ".env",            # Skill directory (preferred)
    skill_root.parent / ".env",     # Project root (fallback)
]

for env_path in env_locations:
    if env_path.exists():
        with open(env_path) as f:
            for line in f:
                line = line.strip()
                if line and "=" in line and not line.startswith("#"):
                    key, value = line.split("=", 1)
                    os.environ[key.strip()] = value.strip()
        break


def get_api_key() -> str:
    """Get Linear API key from environment."""
    api_key = os.getenv("LINEAR_API_KEY")
    if not api_key:
        print(
            "Error: LINEAR_API_KEY environment variable not set.",
            file=sys.stderr,
        )
        sys.exit(1)
    return api_key


def search_issues_graphql(query: str, api_key: str, limit: int = 10) -> dict:
    """
    Search Linear issues using GraphQL.

    Args:
        query: Search query (matches title, description, or identifier)
        api_key: Linear API key
        limit: Maximum number of results to return

    Returns:
        Dictionary containing search results

    Raises:
        ValueError: If search fails
    """
    graphql_query = """
    query SearchIssues($query: String!, $first: Int!) {
      issues(
        first: $first
        filter: {
          searchableContent: { contains: $query }
        }
      ) {
        nodes {
          id
          identifier
          title
          description
          priority
          state {
            name
            type
          }
          assignee {
            name
          }
          team {
            name
            key
          }
          updatedAt
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
    """

    payload = {
        "query": graphql_query,
        "variables": {"query": query, "first": limit}
    }

    try:
        req = urllib.request.Request(
            "https://api.linear.app/graphql",
            data=json.dumps(payload).encode("utf-8"),
            headers={
                "Content-Type": "application/json",
                "Authorization": api_key,
            },
        )

        with urllib.request.urlopen(req) as response:
            result = json.loads(response.read().decode("utf-8"))

    except urllib.error.HTTPError as e:
        error_body = e.read().decode("utf-8")
        try:
            error_json = json.loads(error_body)
            if error_json.get("errors"):
                error_msg = error_json["errors"][0].get("message", str(e))
            else:
                error_msg = error_body
        except json.JSONDecodeError:
            error_msg = error_body
        raise ValueError(f"API error: {error_msg}")
    except Exception as e:
        raise ValueError(f"Network error: {str(e)}")

    # Check for GraphQL errors
    if "errors" in result:
        error_msg = result["errors"][0].get("message", "Unknown error")
        raise ValueError(f"GraphQL error: {error_msg}")

    return result["data"]["issues"]


def format_pretty(results: dict) -> str:
    """Format search results for human-readable output."""
    nodes = results.get("nodes", [])

    if not nodes:
        return "No issues found."

    lines = [f"\nFound {len(nodes)} issue(s):\n"]

    for i, issue in enumerate(nodes, 1):
        identifier = issue["identifier"]
        title = issue["title"]
        state = issue["state"]["name"] if issue["state"] else "Unknown"
        assignee = issue["assignee"]["name"] if issue["assignee"] else "Unassigned"
        team = issue["team"]["key"] if issue["team"] else "?"

        # Truncate title if too long
        if len(title) > 60:
            title = title[:57] + "..."

        lines.append(f"{i}. \033[1;36m{identifier}\033[0m - {title}")
        lines.append(f"   Status: {state} | Assignee: {assignee} | Team: {team}")
        lines.append("")

    if results.get("pageInfo", {}).get("hasNextPage"):
        lines.append("(More results available - refine your search)")

    return "\n".join(lines)


def format_json(results: dict) -> str:
    """Format search results as JSON."""
    formatted = {
        "count": len(results.get("nodes", [])),
        "has_more": results.get("pageInfo", {}).get("hasNextPage", False),
        "issues": [
            {
                "identifier": issue["identifier"],
                "title": issue["title"],
                "state": issue["state"]["name"] if issue["state"] else "Unknown",
                "assignee": issue["assignee"]["name"] if issue["assignee"] else None,
                "team": issue["team"]["key"] if issue["team"] else None,
                "priority": issue.get("priority", 0),
                "updated_at": issue.get("updatedAt"),
            }
            for issue in results.get("nodes", [])
        ]
    }
    return json.dumps(formatted, indent=2)


def main():
    """Parse arguments and search issues."""
    parser = argparse.ArgumentParser(
        description="Search Linear issues",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python scripts/search_issues.py 320
  python scripts/search_issues.py "filtering"
  python scripts/search_issues.py "in progress" --limit 20
  python scripts/search_issues.py exercise --json
        """,
    )

    parser.add_argument(
        "query",
        help="Search query (issue number, title, or description)",
    )

    parser.add_argument(
        "--limit",
        type=int,
        default=10,
        help="Maximum number of results (default: 10)",
    )

    parser.add_argument(
        "--json",
        action="store_true",
        help="Output as JSON",
    )

    args = parser.parse_args()

    try:
        api_key = get_api_key()
        results = search_issues_graphql(args.query, api_key, args.limit)

        if args.json:
            print(format_json(results))
        else:
            print(format_pretty(results))

    except ValueError as e:
        print(f"Error: {str(e)}", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"Unexpected error: {str(e)}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()