mcp-ticketer 0.3.5__py3-none-any.whl → 0.12.0__py3-none-any.whl

mcp_ticketer/cli/instruction_commands.py

@@ -0,0 +1,429 @@
+"""Ticket instructions management commands.
+
+This module implements CLI commands for managing ticket writing instructions,
+allowing users to customize and view the guidelines that help create
+well-structured, consistent tickets.
+"""
+
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from ..core.instructions import (
+    InstructionsError,
+    InstructionsValidationError,
+    TicketInstructionsManager,
+)
+
+app = typer.Typer(
+    name="instructions",
+    help="Manage ticket writing instructions for your project",
+)
+console = Console()
+
+
+@app.command()
+def show(
+    default: bool = typer.Option(
+        False,
+        "--default",
+        help="Show default instructions instead of custom",
+    ),
+    raw: bool = typer.Option(
+        False,
+        "--raw",
+        help="Output raw markdown without formatting",
+    ),
+) -> None:
+    """Display current ticket writing instructions.
+
+    By default, shows custom instructions if they exist, otherwise shows defaults.
+    Use --default to always show the default instructions.
+    Use --raw to output raw markdown without Rich formatting (useful for piping).
+
+    Examples:
+        # Show current instructions (custom or default)
+        mcp-ticketer instructions show
+
+        # Always show default instructions
+        mcp-ticketer instructions show --default
+
+        # Output raw markdown for piping
+        mcp-ticketer instructions show --raw > team_guide.md
+
+    """
+    try:
+        manager = TicketInstructionsManager()
+
+        if default:
+            instructions = manager.get_default_instructions()
+            source = "default"
+        else:
+            instructions = manager.get_instructions()
+            source = "custom" if manager.has_custom_instructions() else "default"
+
+        if raw:
+            # Raw output for piping
+            console.print(instructions)
+        else:
+            # Rich formatted output
+            if source == "custom":
+                title = f"[green]Custom Instructions[/green] ({manager.get_instructions_path()})"
+            else:
+                title = "[blue]Default Instructions[/blue]"
+
+            panel = Panel(
+                Markdown(instructions),
+                title=title,
+                border_style="cyan",
+            )
+            console.print(panel)
+
+    except InstructionsError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def add(
+    file_path: str | None = typer.Argument(
+        None,
+        help="Path to markdown file with custom instructions",
+    ),
+    stdin: bool = typer.Option(
+        False,
+        "--stdin",
+        help="Read instructions from stdin instead of file",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing custom instructions without confirmation",
+    ),
+) -> None:
+    """Add custom ticket writing instructions for your project.
+
+    You can provide instructions from a file or via stdin. If custom instructions
+    already exist, you'll be prompted for confirmation unless --force is used.
+
+    Examples:
+        # Add from file
+        mcp-ticketer instructions add team_guidelines.md
+
+        # Add from stdin
+        cat guidelines.md | mcp-ticketer instructions add --stdin
+
+        # Force overwrite existing
+        mcp-ticketer instructions add new_guide.md --force
+
+    """
+    try:
+        manager = TicketInstructionsManager()
+
+        # Check for existing custom instructions
+        if manager.has_custom_instructions() and not force:
+            path = manager.get_instructions_path()
+            console.print(
+                f"[yellow]Warning:[/yellow] Custom instructions already exist at {path}"
+            )
+
+            confirm = typer.confirm("Do you want to overwrite them?")
+            if not confirm:
+                console.print("[yellow]Operation cancelled[/yellow]")
+                raise typer.Exit(0) from None
+
+        # Get content from stdin or file
+        if stdin:
+            console.print("[dim]Reading from stdin... (Press Ctrl+D when done)[/dim]")
+            content = sys.stdin.read()
+            if not content.strip():
+                console.print("[red]Error:[/red] No content provided on stdin")
+                raise typer.Exit(1) from None
+        elif file_path:
+            source_path = Path(file_path)
+            if not source_path.exists():
+                console.print(f"[red]Error:[/red] File not found: {file_path}")
+                raise typer.Exit(1) from None
+
+            try:
+                content = source_path.read_text(encoding="utf-8")
+            except Exception as e:
+                console.print(f"[red]Error:[/red] Failed to read file: {e}")
+                raise typer.Exit(1) from None
+        else:
+            console.print("[red]Error:[/red] Either provide a file path or use --stdin")
+            console.print("Example: mcp-ticketer instructions add guidelines.md")
+            raise typer.Exit(1) from None
+
+        # Set instructions
+        manager.set_instructions(content)
+
+        path = manager.get_instructions_path()
+        console.print(f"[green]✓[/green] Custom instructions saved to: {path}")
+        console.print("[dim]Use 'mcp-ticketer instructions show' to view them[/dim]")
+
+    except InstructionsValidationError as e:
+        console.print(f"[red]Validation Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except InstructionsError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def update(
+    file_path: str | None = typer.Argument(
+        None,
+        help="Path to markdown file with updated instructions",
+    ),
+    stdin: bool = typer.Option(
+        False,
+        "--stdin",
+        help="Read instructions from stdin instead of file",
+    ),
+) -> None:
+    """Update existing custom instructions (alias for 'add --force').
+
+    This is a convenience command that overwrites existing custom instructions
+    without prompting for confirmation.
+
+    Examples:
+        # Update from file
+        mcp-ticketer instructions update new_guidelines.md
+
+        # Update from stdin
+        cat updated.md | mcp-ticketer instructions update --stdin
+
+    """
+    try:
+        manager = TicketInstructionsManager()
+
+        if not manager.has_custom_instructions():
+            console.print("[yellow]Warning:[/yellow] No custom instructions exist yet")
+            console.print("Use 'mcp-ticketer instructions add' to create them first")
+            raise typer.Exit(1) from None
+
+        # Get content from stdin or file
+        if stdin:
+            console.print("[dim]Reading from stdin... (Press Ctrl+D when done)[/dim]")
+            content = sys.stdin.read()
+            if not content.strip():
+                console.print("[red]Error:[/red] No content provided on stdin")
+                raise typer.Exit(1) from None
+        elif file_path:
+            source_path = Path(file_path)
+            if not source_path.exists():
+                console.print(f"[red]Error:[/red] File not found: {file_path}")
+                raise typer.Exit(1) from None
+
+            try:
+                content = source_path.read_text(encoding="utf-8")
+            except Exception as e:
+                console.print(f"[red]Error:[/red] Failed to read file: {e}")
+                raise typer.Exit(1) from None
+        else:
+            console.print("[red]Error:[/red] Either provide a file path or use --stdin")
+            console.print("Example: mcp-ticketer instructions update guidelines.md")
+            raise typer.Exit(1) from None
+
+        # Update instructions (force overwrite)
+        manager.set_instructions(content)
+
+        path = manager.get_instructions_path()
+        console.print(f"[green]✓[/green] Custom instructions updated: {path}")
+        console.print("[dim]Use 'mcp-ticketer instructions show' to view them[/dim]")
+
+    except InstructionsValidationError as e:
+        console.print(f"[red]Validation Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except InstructionsError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def delete(
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip confirmation prompt",
+    ),
+) -> None:
+    """Delete custom instructions and revert to defaults.
+
+    This removes your project-specific instructions file. After deletion,
+    the default instructions will be used.
+
+    Examples:
+        # Delete with confirmation prompt
+        mcp-ticketer instructions delete
+
+        # Skip confirmation
+        mcp-ticketer instructions delete --yes
+
+    """
+    try:
+        manager = TicketInstructionsManager()
+
+        if not manager.has_custom_instructions():
+            console.print("[yellow]No custom instructions to delete[/yellow]")
+            console.print("[dim]Already using default instructions[/dim]")
+            raise typer.Exit(0) from None
+
+        path = manager.get_instructions_path()
+
+        if not yes:
+            console.print(f"[yellow]Warning:[/yellow] This will delete: {path}")
+            console.print("After deletion, default instructions will be used.")
+
+            confirm = typer.confirm("Are you sure?")
+            if not confirm:
+                console.print("[yellow]Operation cancelled[/yellow]")
+                raise typer.Exit(0) from None
+
+        # Delete instructions
+        manager.delete_instructions()
+
+        console.print("[green]✓[/green] Custom instructions deleted")
+        console.print("[dim]Now using default instructions[/dim]")
+
+    except InstructionsError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def path() -> None:
+    """Show path to custom instructions file.
+
+    Displays the path where custom instructions are (or would be) stored
+    for this project, along with status information.
+
+    Examples:
+        # Show instructions file path
+        mcp-ticketer instructions path
+
+        # Use in scripts
+        INST_PATH=$(mcp-ticketer instructions path --quiet)
+
+    """
+    try:
+        manager = TicketInstructionsManager()
+        inst_path = manager.get_instructions_path()
+        exists = manager.has_custom_instructions()
+
+        console.print(f"[cyan]Instructions file:[/cyan] {inst_path}")
+
+        if exists:
+            console.print("[green]Status:[/green] Custom instructions exist")
+
+            # Show file size
+            try:
+                size = inst_path.stat().st_size
+                console.print(f"[dim]Size: {size} bytes[/dim]")
+            except Exception:
+                pass
+        else:
+            console.print(
+                "[yellow]Status:[/yellow] No custom instructions (using defaults)"
+            )
+            console.print(
+                "[dim]Create with: mcp-ticketer instructions add <file>[/dim]"
+            )
+
+    except InstructionsError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def edit() -> None:
+    """Open instructions in default editor.
+
+    Opens the custom instructions file in your system's default text editor.
+    If custom instructions don't exist yet, creates them with default content
+    first.
+
+    The editor is determined by the EDITOR environment variable, or falls back
+    to sensible defaults (vim on Unix, notepad on Windows).
+
+    Examples:
+        # Edit instructions
+        mcp-ticketer instructions edit
+
+        # Use specific editor
+        EDITOR=nano mcp-ticketer instructions edit
+
+    """
+    import os
+    import platform
+    import subprocess
+
+    try:
+        manager = TicketInstructionsManager()
+
+        # If no custom instructions exist, create them with defaults
+        if not manager.has_custom_instructions():
+            console.print("[yellow]No custom instructions yet[/yellow]")
+            console.print("[dim]Creating from defaults...[/dim]")
+
+            # Copy defaults to custom location
+            default_content = manager.get_default_instructions()
+            manager.set_instructions(default_content)
+
+            console.print(
+                f"[green]✓[/green] Created custom instructions at: {manager.get_instructions_path()}"
+            )
+
+        inst_path = manager.get_instructions_path()
+
+        # Determine editor
+        editor = os.environ.get("EDITOR")
+
+        if not editor:
+            # Platform-specific defaults
+            system = platform.system()
+            if system == "Windows":
+                editor = "notepad"
+            else:
+                # Unix-like: try common editors
+                for candidate in ["vim", "vi", "nano", "emacs"]:
+                    try:
+                        result = subprocess.run(
+                            ["which", candidate],
+                            capture_output=True,
+                            text=True,
+                            timeout=1,
+                        )
+                        if result.returncode == 0:
+                            editor = candidate
+                            break
+                    except Exception:
+                        continue
+
+                if not editor:
+                    editor = "vi"  # Ultimate fallback
+
+        console.print(f"[dim]Opening with {editor}...[/dim]")
+
+        # Open editor
+        try:
+            subprocess.run([editor, str(inst_path)], check=True)
+            console.print(f"[green]✓[/green] Finished editing: {inst_path}")
+        except subprocess.CalledProcessError as e:
+            console.print(f"[red]Error:[/red] Editor exited with code {e.returncode}")
+            raise typer.Exit(1) from None
+        except FileNotFoundError:
+            console.print(f"[red]Error:[/red] Editor not found: {editor}")
+            console.print("Set EDITOR environment variable to your preferred editor")
+            raise typer.Exit(1) from None
+
+    except InstructionsError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None

mcp_ticketer/cli/linear_commands.py

@@ -1,7 +1,7 @@
 """Linear-specific CLI commands for workspace and team management."""
 
 import os
-from typing import Optional
+import re
 
 import typer
 from gql import Client, gql
@@ -13,13 +13,96 @@ app = typer.Typer(name="linear", help="Linear workspace and team management")
 console = Console()
 
 
+async def derive_team_from_url(
+    api_key: str, team_url: str
+) -> tuple[str | None, str | None]:
+    """Derive team ID from Linear team issues URL.
+
+    Accepts URLs like:
+    - https://linear.app/1m-hyperdev/team/1M/active
+    - https://linear.app/1m-hyperdev/team/1M/
+    - https://linear.app/1m-hyperdev/team/1M
+
+    Args:
+        api_key: Linear API key
+        team_url: URL to Linear team issues page
+
+    Returns:
+        Tuple of (team_id, error_message). If successful, team_id is set and error_message is None.
+        If failed, team_id is None and error_message contains the error.
+
+    """
+    # Extract team key from URL using regex
+    # Pattern: https://linear.app/<workspace>/team/<TEAM_KEY>/...
+    pattern = r"https://linear\.app/[\w-]+/team/([\w-]+)"
+    match = re.search(pattern, team_url)
+
+    if not match:
+        return (
+            None,
+            "Invalid Linear team URL format. Expected: https://linear.app/<workspace>/team/<TEAM_KEY>",
+        )
+
+    team_key = match.group(1)
+    console.print(f"[dim]Extracted team key: {team_key}[/dim]")
+
+    # Query Linear API to resolve team key to team ID
+    query = gql(
+        """
+        query GetTeamByKey($key: String!) {
+            teams(filter: { key: { eq: $key } }) {
+                nodes {
+                    id
+                    key
+                    name
+                    organization {
+                        name
+                        urlKey
+                    }
+                }
+            }
+        }
+    """
+    )
+
+    try:
+        # Create client
+        transport = HTTPXTransport(
+            url="https://api.linear.app/graphql", headers={"Authorization": api_key}
+        )
+        client = Client(transport=transport, fetch_schema_from_transport=False)
+
+        # Execute query
+        result = client.execute(query, variable_values={"key": team_key})
+        teams = result.get("teams", {}).get("nodes", [])
+
+        if not teams:
+            return (
+                None,
+                f"Team with key '{team_key}' not found. Please check your team URL and API key.",
+            )
+
+        team = teams[0]
+        team_id = team["id"]
+        team_name = team["name"]
+
+        console.print(
+            f"[green]✓[/green] Resolved team: {team_name} (Key: {team_key}, ID: {team_id})"
+        )
+
+        return team_id, None
+
+    except Exception as e:
+        return None, f"Failed to query Linear API: {str(e)}"
+
+
 def _create_linear_client() -> Client:
     """Create a Linear GraphQL client."""
     api_key = os.getenv("LINEAR_API_KEY")
     if not api_key:
         console.print("[red]❌ LINEAR_API_KEY not found in environment[/red]")
         console.print("Set it in .env.local or environment variables")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     transport = HTTPXTransport(
         url="https://api.linear.app/graphql", headers={"Authorization": api_key}
@@ -28,7 +111,7 @@ def _create_linear_client() -> Client:
 
 
 @app.command("workspaces")
-def list_workspaces():
+def list_workspaces() -> None:
     """List all accessible Linear workspaces."""
     console.print("🔍 Discovering Linear workspaces...")
 
@@ -75,18 +158,18 @@ def list_workspaces():
 
     except Exception as e:
         console.print(f"[red]❌ Error fetching workspace info: {e}[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @app.command("teams")
 def list_teams(
-    workspace: Optional[str] = typer.Option(
+    workspace: str | None = typer.Option(
         None, "--workspace", "-w", help="Workspace URL key (optional)"
     ),
     all_teams: bool = typer.Option(
         False, "--all", "-a", help="Show all teams across all workspaces"
     ),
-):
+) -> None:
     """List all teams in the current workspace or all accessible teams."""
     if all_teams:
         console.print("🔍 Discovering ALL accessible Linear teams across workspaces...")
@@ -245,25 +328,25 @@ def list_teams(
 
     except Exception as e:
         console.print(f"[red]❌ Error fetching teams: {e}[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e
 
 
 @app.command("configure")
 def configure_team(
-    team_key: Optional[str] = typer.Option(
+    team_key: str | None = typer.Option(
         None, "--team-key", "-k", help="Team key (e.g., '1M')"
     ),
-    team_id: Optional[str] = typer.Option(None, "--team-id", "-i", help="Team UUID"),
-    workspace: Optional[str] = typer.Option(
+    team_id: str | None = typer.Option(None, "--team-id", "-i", help="Team UUID"),
+    workspace: str | None = typer.Option(
         None, "--workspace", "-w", help="Workspace URL key"
     ),
-):
+) -> None:
     """Configure Linear adapter with a specific team."""
     from ..cli.main import load_config, save_config
 
     if not team_key and not team_id:
         console.print("[red]❌ Either --team-key or --team-id is required[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     console.print("🔧 Configuring Linear adapter...")
 
@@ -293,11 +376,11 @@ def configure_team(
 
             if not team:
                 console.print(f"[red]❌ Team with ID '{team_id}' not found[/red]")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
         except Exception as e:
             console.print(f"[red]❌ Error validating team: {e}[/red]")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from e
 
     elif team_key:
         # Validate team by key
@@ -326,14 +409,14 @@ def configure_team(
 
             if not teams:
                 console.print(f"[red]❌ Team with key '{team_key}' not found[/red]")
-                raise typer.Exit(1)
+                raise typer.Exit(1) from None
 
             team = teams[0]
             team_id = team["id"]  # Use the found team ID
 
         except Exception as e:
             console.print(f"[red]❌ Error validating team: {e}[/red]")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from e
 
     # Update configuration
     config = load_config()
@@ -382,17 +465,17 @@ def configure_team(
 
 @app.command("info")
 def show_info(
-    team_key: Optional[str] = typer.Option(
+    team_key: str | None = typer.Option(
         None, "--team-key", "-k", help="Team key to show info for"
     ),
-    team_id: Optional[str] = typer.Option(
+    team_id: str | None = typer.Option(
         None, "--team-id", "-i", help="Team UUID to show info for"
     ),
-):
+) -> None:
     """Show detailed information about a specific team."""
     if not team_key and not team_id:
         console.print("[red]❌ Either --team-key or --team-id is required[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from None
 
     # Query for detailed team information
     if team_id:
@@ -483,7 +566,7 @@ def show_info(
         if not team:
             identifier = team_id or team_key
             console.print(f"[red]❌ Team '{identifier}' not found[/red]")
-            raise typer.Exit(1)
+            raise typer.Exit(1) from None
 
         # Display team information
         console.print(f"\n🏷️  Team: {team.get('name')}")
@@ -530,4 +613,4 @@ def show_info(
 
     except Exception as e:
         console.print(f"[red]❌ Error fetching team info: {e}[/red]")
-        raise typer.Exit(1)
+        raise typer.Exit(1) from e