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

mcp_ticketer/cli/ticket_commands.py

@@ -213,11 +213,25 @@ def create(
         "--epic",
         help="Parent epic/project ID (synonym for --project)",
     ),
+    wait: bool = typer.Option(
+        False,
+        "--wait",
+        "-w",
+        help="Wait for operation to complete (synchronous mode, returns actual ticket ID)",
+    ),
+    timeout: float = typer.Option(
+        30.0,
+        "--timeout",
+        help="Timeout in seconds for --wait mode (default: 30)",
+    ),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
     """Create a new ticket with comprehensive health checks."""
+    from .utils import format_error_json, format_json_response, serialize_task
+
     # IMMEDIATE HEALTH CHECK - Critical for reliability
     health_monitor = QueueHealthMonitor()
     health = health_monitor.check_health()
@@ -336,22 +350,35 @@ def create(
 
             result = asyncio.run(adapter_instance.create(task))
 
-            console.print(f"[green]✓[/green] Ticket created successfully: {result.id}")
-            console.print(f"  Title: {result.title}")
-            console.print(f"  Priority: {result.priority}")
-            console.print(f"  State: {result.state}")
-            # Get URL from metadata if available
-            if (
-                result.metadata
-                and "linear" in result.metadata
-                and "url" in result.metadata["linear"]
-            ):
-                console.print(f"  URL: {result.metadata['linear']['url']}")
+            if output_json:
+                data = serialize_task(result)
+                console.print(
+                    format_json_response(
+                        "success", data, message="Ticket created successfully"
+                    )
+                )
+            else:
+                console.print(
+                    f"[green]✓[/green] Ticket created successfully: {result.id}"
+                )
+                console.print(f"  Title: {result.title}")
+                console.print(f"  Priority: {result.priority}")
+                console.print(f"  State: {result.state}")
+                # Get URL from metadata if available
+                if (
+                    result.metadata
+                    and "linear" in result.metadata
+                    and "url" in result.metadata["linear"]
+                ):
+                    console.print(f"  URL: {result.metadata['linear']['url']}")
 
             return result.id
 
         except Exception as e:
-            console.print(f"[red]❌[/red] Failed to create ticket: {e}")
+            if output_json:
+                console.print(format_error_json(e))
+            else:
+                console.print(f"[red]❌[/red] Failed to create ticket: {e}")
             raise
 
     # Use queue for other adapters
@@ -369,51 +396,113 @@ def create(
         queue_id, adapter_name, "create", title, task_data
     )
 
-    console.print(f"[green]✓[/green] Queued ticket creation: {queue_id}")
-    console.print(f"  Title: {title}")
-    console.print(f"  Priority: {priority}")
-    console.print(f"  Adapter: {adapter_name}")
-    console.print(
-        "[dim]Use 'mcp-ticketer ticket check {queue_id}' to check progress[/dim]"
-    )
-
-    # Start worker if needed with immediate feedback
+    # Start worker if needed - must happen before polling
     manager = WorkerManager()
     worker_started = manager.start_if_needed()
 
     if worker_started:
-        console.print("[dim]Worker started to process request[/dim]")
+        if not output_json:
+            console.print("[dim]Worker started to process request[/dim]")
 
-        # Give immediate feedback on processing
-        import time
-
-        time.sleep(1)  # Brief pause to let worker start
-
-        # Check if item is being processed
-        item = queue.get_item(queue_id)
-        if item and item.status == QueueStatus.PROCESSING:
-            console.print("[green]✓ Item is being processed by worker[/green]")
-        elif item and item.status == QueueStatus.PENDING:
-            console.print("[yellow]⏳ Item is queued for processing[/yellow]")
-        else:
+    # SYNCHRONOUS MODE: Poll until completion if --wait flag is set
+    if wait:
+        if not output_json:
             console.print(
-                "[red]⚠️  Item status unclear - check with 'mcp-ticketer ticket check {queue_id}'[/red]"
+                f"[yellow]⏳[/yellow] Waiting for operation to complete (timeout: {timeout}s)..."
             )
+
+        try:
+            # Poll the queue until operation completes
+            completed_item = queue.poll_until_complete(queue_id, timeout=timeout)
+
+            # Extract result data
+            result = completed_item.result
+
+            # Extract ticket ID from result
+            ticket_id = result.get("id") if result else queue_id
+
+            if output_json:
+                # Return actual ticket data in JSON format
+                data = result if result else {"queue_id": queue_id}
+                console.print(
+                    format_json_response(
+                        "success", data, message="Ticket created successfully"
+                    )
+                )
+            else:
+                # Display ticket creation success with actual ID
+                console.print(
+                    f"[green]✓[/green] Ticket created successfully: {ticket_id}"
+                )
+                console.print(f"  Title: {title}")
+                console.print(f"  Priority: {priority}")
+
+                # Display additional metadata if available
+                if result:
+                    if "url" in result:
+                        console.print(f"  URL: {result['url']}")
+                    if "state" in result:
+                        console.print(f"  State: {result['state']}")
+
+            return ticket_id
+
+        except TimeoutError as e:
+            if output_json:
+                console.print(format_error_json(str(e), queue_id=queue_id))
+            else:
+                console.print(f"[red]❌[/red] Operation timed out after {timeout}s")
+                console.print(f"  Queue ID: {queue_id}")
+                console.print(
+                    f"  Use 'mcp-ticketer ticket check {queue_id}' to check status later"
+                )
+            raise typer.Exit(1) from None
+
+        except RuntimeError as e:
+            if output_json:
+                console.print(format_error_json(str(e), queue_id=queue_id))
+            else:
+                console.print(f"[red]❌[/red] Operation failed: {e}")
+                console.print(f"  Queue ID: {queue_id}")
+            raise typer.Exit(1) from None
+
+    # ASYNCHRONOUS MODE (default): Return queue ID immediately
     else:
-        # Worker didn't start - this is a problem
-        pending_count = queue.get_pending_count()
-        if pending_count > 1:  # More than just this item
-            console.print(
-                f"[red]❌ Worker failed to start with {pending_count} pending items![/red]"
-            )
+        if output_json:
+            data = {
+                "queue_id": queue_id,
+                "title": title,
+                "priority": priority.value if hasattr(priority, "value") else priority,
+                "adapter": adapter_name,
+                "status": "queued",
+            }
             console.print(
-                "[red]This is a critical issue. Try 'mcp-ticketer queue worker start' manually.[/red]"
+                format_json_response("success", data, message="Ticket creation queued")
             )
         else:
+            console.print(f"[green]✓[/green] Queued ticket creation: {queue_id}")
+            console.print(f"  Title: {title}")
+            console.print(f"  Priority: {priority}")
+            console.print(f"  Adapter: {adapter_name}")
             console.print(
-                "[yellow]Worker not started (no other pending items)[/yellow]"
+                "[dim]Use 'mcp-ticketer ticket check {queue_id}' to check progress[/dim]"
             )
 
+            # Give immediate feedback on processing
+            import time
+
+            time.sleep(1)  # Brief pause to let worker start
+
+            # Check if item is being processed
+            item = queue.get_item(queue_id)
+            if item and item.status == QueueStatus.PROCESSING:
+                console.print("[green]✓ Item is being processed by worker[/green]")
+            elif item and item.status == QueueStatus.PENDING:
+                console.print("[yellow]⏳ Item is queued for processing[/yellow]")
+            else:
+                console.print(
+                    "[red]⚠️  Item status unclear - check with 'mcp-ticketer ticket check {queue_id}'[/red]"
+                )
+
 
 @app.command("list")
 def list_tickets(
@@ -424,11 +513,13 @@ def list_tickets(
         None, "--priority", "-p", help="Filter by priority"
     ),
     limit: int = typer.Option(10, "--limit", "-l", help="Maximum number of tickets"),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
     """List tickets with optional filters."""
+    from .utils import format_json_response, serialize_task
 
     async def _list() -> list[Any]:
         adapter_instance = get_adapter(
@@ -444,10 +535,29 @@ def list_tickets(
     tickets = asyncio.run(_list())
 
     if not tickets:
-        console.print("[yellow]No tickets found[/yellow]")
+        if output_json:
+            console.print(
+                format_json_response(
+                    "success", {"tickets": [], "count": 0, "has_more": False}
+                )
+            )
+        else:
+            console.print("[yellow]No tickets found[/yellow]")
         return
 
-    # Create table
+    # JSON output
+    if output_json:
+        tickets_data = [serialize_task(t) for t in tickets]
+        data = {
+            "tickets": tickets_data,
+            "count": len(tickets_data),
+            "has_more": len(tickets)
+            >= limit,  # Heuristic: if we got exactly limit, there might be more
+        }
+        console.print(format_json_response("success", data))
+        return
+
+    # Original table output
     table = Table(title="Tickets")
     table.add_column("ID", style="cyan", no_wrap=True)
     table.add_column("Title", style="white")
@@ -473,62 +583,180 @@ def list_tickets(
 @app.command()
 def show(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
-    comments: bool = typer.Option(False, "--comments", "-c", help="Show comments"),
+    no_comments: bool = typer.Option(
+        False, "--no-comments", help="Hide comments (shown by default)"
+    ),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
-    """Show detailed ticket information."""
+    """Show detailed ticket information with full context.
+
+    By default, displays ticket details along with all comments to provide
+    a holistic view of the ticket's history and context.
+
+    Use --no-comments to display only ticket metadata without comments.
+    Use --json to output in machine-readable JSON format.
+    """
+    from .utils import format_error_json, format_json_response, serialize_task
 
-    async def _show() -> tuple[Any, Any]:
+    async def _show() -> tuple[Any, Any, Any]:
         adapter_instance = get_adapter(
             override_adapter=adapter.value if adapter else None
         )
         ticket = await adapter_instance.read(ticket_id)
         ticket_comments = None
-        if comments and ticket:
-            ticket_comments = await adapter_instance.get_comments(ticket_id)
-        return ticket, ticket_comments
+        attachments = None
 
-    ticket, ticket_comments = asyncio.run(_show())
+        # Fetch comments by default (unless explicitly disabled)
+        if not no_comments and ticket:
+            try:
+                ticket_comments = await adapter_instance.get_comments(ticket_id)
+            except (NotImplementedError, AttributeError):
+                # Adapter doesn't support comments
+                pass
 
-    if not ticket:
-        console.print(f"[red]✗[/red] Ticket not found: {ticket_id}")
-        raise typer.Exit(1) from None
+        # Try to fetch attachments if available
+        if ticket and hasattr(adapter_instance, "list_attachments"):
+            try:
+                attachments = await adapter_instance.list_attachments(ticket_id)
+            except (NotImplementedError, AttributeError):
+                pass
 
-    # Display ticket details
-    console.print(f"\n[bold]Ticket: {ticket.id}[/bold]")
-    console.print(f"Title: {ticket.title}")
-    console.print(f"State: [green]{ticket.state}[/green]")
-    console.print(f"Priority: [yellow]{ticket.priority}[/yellow]")
+        return ticket, ticket_comments, attachments
 
-    if ticket.description:
-        console.print("\n[dim]Description:[/dim]")
-        console.print(ticket.description)
+    try:
+        ticket, ticket_comments, attachments = asyncio.run(_show())
 
-    if ticket.tags:
-        console.print(f"\nTags: {', '.join(ticket.tags)}")
+        if not ticket:
+            if output_json:
+                console.print(
+                    format_error_json(
+                        f"Ticket not found: {ticket_id}", ticket_id=ticket_id
+                    )
+                )
+            else:
+                console.print(f"[red]✗[/red] Ticket not found: {ticket_id}")
+            raise typer.Exit(1) from None
+
+        # JSON output
+        if output_json:
+            data = serialize_task(ticket)
+
+            # Add comments if available
+            if ticket_comments:
+                data["comments"] = [
+                    {
+                        "id": getattr(c, "id", None),
+                        "text": c.content,
+                        "author": c.author,
+                        "created_at": (
+                            c.created_at.isoformat()
+                            if hasattr(c.created_at, "isoformat")
+                            else str(c.created_at)
+                        ),
+                    }
+                    for c in ticket_comments
+                ]
+
+            # Add attachments if available
+            if attachments:
+                data["attachments"] = attachments
+
+            console.print(format_json_response("success", data))
+            return
+
+        # Original formatted output continues below...
+    except Exception as e:
+        if output_json:
+            console.print(format_error_json(e, ticket_id=ticket_id))
+            raise typer.Exit(1) from None
+        raise
+
+    # Display ticket header with metadata
+    console.print(f"\n[bold cyan]┌─ Ticket: {ticket.id}[/bold cyan]")
+    console.print(f"[bold]│ {ticket.title}[/bold]")
+    console.print("└" + "─" * 60)
+
+    # Display metadata in organized sections
+    console.print("\n[bold]Status[/bold]")
+    console.print(f"  State: [green]{ticket.state}[/green]")
+    console.print(f"  Priority: [yellow]{ticket.priority}[/yellow]")
 
     if ticket.assignee:
-        console.print(f"Assignee: {ticket.assignee}")
+        console.print(f"  Assignee: {ticket.assignee}")
+
+    # Display timestamps if available
+    if ticket.created_at or ticket.updated_at:
+        console.print("\n[bold]Timeline[/bold]")
+        if ticket.created_at:
+            console.print(f"  Created: {ticket.created_at}")
+        if ticket.updated_at:
+            console.print(f"  Updated: {ticket.updated_at}")
+
+    # Display tags
+    if ticket.tags:
+        console.print("\n[bold]Tags[/bold]")
+        console.print(f"  {', '.join(ticket.tags)}")
 
-    # Display comments if requested
+    # Display description
+    if ticket.description:
+        console.print("\n[bold]Description[/bold]")
+        console.print(f"  {ticket.description}")
+
+    # Display parent/child relationships
+    parent_info = []
+    if hasattr(ticket, "parent_epic") and ticket.parent_epic:
+        parent_info.append(f"Epic: {ticket.parent_epic}")
+    if hasattr(ticket, "parent_issue") and ticket.parent_issue:
+        parent_info.append(f"Parent Issue: {ticket.parent_issue}")
+
+    if parent_info:
+        console.print("\n[bold]Hierarchy[/bold]")
+        for info in parent_info:
+            console.print(f"  {info}")
+
+    # Display attachments if available
+    if attachments and len(attachments) > 0:
+        console.print(f"\n[bold]Attachments ({len(attachments)})[/bold]")
+        for att in attachments:
+            att_title = att.get("title", "Untitled")
+            att_url = att.get("url", "")
+            console.print(f"  📎 {att_title}")
+            if att_url:
+                console.print(f"     {att_url}")
+
+    # Display comments with enhanced formatting
     if ticket_comments:
-        console.print(f"\n[bold]Comments ({len(ticket_comments)}):[/bold]")
-        for comment in ticket_comments:
-            console.print(f"\n[dim]{comment.created_at} - {comment.author}:[/dim]")
-            console.print(comment.content)
+        console.print(f"\n[bold]Activity & Comments ({len(ticket_comments)})[/bold]")
+        for i, comment in enumerate(ticket_comments, 1):
+            # Format timestamp
+            timestamp = comment.created_at if comment.created_at else "Unknown time"
+            author = comment.author if comment.author else "Unknown author"
+
+            console.print(f"\n[dim]  {i}. {timestamp}[/dim]")
+            console.print(f"  [cyan]@{author}[/cyan]")
+            console.print(f"  {comment.content}")
+
+    # Footer with hint
+    if no_comments:
+        console.print(
+            "\n[dim]💡 Tip: Remove --no-comments to see activity and comments[/dim]"
+        )
 
 
 @app.command()
 def comment(
     ticket_id: str = typer.Argument(..., help="Ticket ID"),
     content: str = typer.Argument(..., help="Comment content"),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
     """Add a comment to a ticket."""
+    from .utils import format_error_json, format_json_response
 
     async def _comment() -> Comment:
         adapter_instance = get_adapter(
@@ -547,12 +775,203 @@ def comment(
 
     try:
         result = asyncio.run(_comment())
-        console.print("[green]✓[/green] Comment added successfully")
-        if result.id:
-            console.print(f"Comment ID: {result.id}")
-        console.print(f"Content: {content}")
+
+        if output_json:
+            data = {
+                "id": result.id,
+                "ticket_id": ticket_id,
+                "text": content,
+                "author": result.author,
+                "created_at": (
+                    result.created_at.isoformat()
+                    if hasattr(result.created_at, "isoformat")
+                    else str(result.created_at)
+                ),
+            }
+            console.print(
+                format_json_response(
+                    "success", data, message="Comment added successfully"
+                )
+            )
+        else:
+            console.print("[green]✓[/green] Comment added successfully")
+            if result.id:
+                console.print(f"Comment ID: {result.id}")
+            console.print(f"Content: {content}")
     except Exception as e:
-        console.print(f"[red]✗[/red] Failed to add comment: {e}")
+        if output_json:
+            console.print(format_error_json(e, ticket_id=ticket_id))
+        else:
+            console.print(f"[red]✗[/red] Failed to add comment: {e}")
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def attach(
+    ticket_id: str = typer.Argument(..., help="Ticket ID or URL"),
+    file_path: Path = typer.Argument(..., help="Path to file to attach", exists=True),
+    description: str | None = typer.Option(
+        None, "--description", "-d", help="Attachment description or comment"
+    ),
+    adapter: AdapterType | None = typer.Option(
+        None, "--adapter", help="Override default adapter"
+    ),
+) -> None:
+    """Attach a file to a ticket.
+
+    Examples:
+        mcp-ticketer ticket attach 1M-157 docs/analysis.md
+        mcp-ticketer ticket attach PROJ-123 screenshot.png -d "Error screenshot"
+        mcp-ticketer ticket attach https://linear.app/.../issue/ABC-123 diagram.pdf
+    """
+
+    async def _attach() -> dict[str, Any]:
+        import mimetypes
+
+        adapter_instance = get_adapter(
+            override_adapter=adapter.value if adapter else None
+        )
+
+        # Detect MIME type
+        mime_type, _ = mimetypes.guess_type(str(file_path))
+        if not mime_type:
+            mime_type = "application/octet-stream"
+
+        # Method 1: Try Linear-specific upload (if available)
+        if hasattr(adapter_instance, "upload_file") and hasattr(
+            adapter_instance, "attach_file_to_issue"
+        ):
+            try:
+                # Upload file to Linear's S3
+                file_url = await adapter_instance.upload_file(
+                    file_path=str(file_path), mime_type=mime_type
+                )
+
+                # Attach to issue
+                attachment = await adapter_instance.attach_file_to_issue(
+                    issue_id=ticket_id,
+                    file_url=file_url,
+                    title=file_path.name,
+                    subtitle=description,
+                )
+
+                return {
+                    "status": "completed",
+                    "attachment": attachment,
+                    "file_url": file_url,
+                    "method": "linear_native_upload",
+                }
+            except Exception:
+                # If Linear upload fails, fall through to next method
+                pass
+
+        # Method 2: Try generic add_attachment (if available)
+        if hasattr(adapter_instance, "add_attachment"):
+            try:
+                attachment = await adapter_instance.add_attachment(
+                    ticket_id=ticket_id,
+                    file_path=str(file_path),
+                    description=description or "",
+                )
+                return {
+                    "status": "completed",
+                    "attachment": attachment,
+                    "method": "adapter_native",
+                }
+            except NotImplementedError:
+                pass
+
+        # Method 3: Fallback - Add file reference as comment
+        from ..core.models import Comment
+
+        comment_content = f"📎 File reference: {file_path.name}"
+        if description:
+            comment_content += f"\n\n{description}"
+
+        comment_obj = Comment(
+            ticket_id=ticket_id,
+            content=comment_content,
+            author="cli-user",
+        )
+
+        comment = await adapter_instance.add_comment(comment_obj)
+        return {
+            "status": "completed",
+            "comment": comment,
+            "method": "comment_reference",
+            "note": "Adapter doesn't support attachments - added file reference as comment",
+        }
+
+    # Validate file before attempting upload
+    if not file_path.exists():
+        console.print(f"[red]✗[/red] File not found: {file_path}")
+        raise typer.Exit(1) from None
+
+    if not file_path.is_file():
+        console.print(f"[red]✗[/red] Path is not a file: {file_path}")
+        raise typer.Exit(1) from None
+
+    # Display file info
+    file_size = file_path.stat().st_size
+    size_mb = file_size / (1024 * 1024)
+    console.print(f"\n[dim]Attaching file to ticket {ticket_id}...[/dim]")
+    console.print(f"  File: {file_path.name} ({size_mb:.2f} MB)")
+
+    # Detect MIME type
+    import mimetypes
+
+    mime_type, _ = mimetypes.guess_type(str(file_path))
+    if mime_type:
+        console.print(f"  Type: {mime_type}")
+
+    try:
+        result = asyncio.run(_attach())
+
+        if result["status"] == "completed":
+            console.print(
+                f"\n[green]✓[/green] File attached successfully to {ticket_id}"
+            )
+
+            # Display attachment details based on method used
+            method = result.get("method", "unknown")
+
+            if method == "linear_native_upload":
+                console.print("  Method: Linear native upload")
+                if "file_url" in result:
+                    console.print(f"  URL: {result['file_url']}")
+                if "attachment" in result and isinstance(result["attachment"], dict):
+                    att = result["attachment"]
+                    if "id" in att:
+                        console.print(f"  ID: {att['id']}")
+                    if "title" in att:
+                        console.print(f"  Title: {att['title']}")
+
+            elif method == "adapter_native":
+                console.print("  Method: Adapter native")
+                if "attachment" in result:
+                    att = result["attachment"]
+                    if isinstance(att, dict):
+                        if "id" in att:
+                            console.print(f"  ID: {att['id']}")
+                        if "url" in att:
+                            console.print(f"  URL: {att['url']}")
+
+            elif method == "comment_reference":
+                console.print("  Method: Comment reference")
+                console.print(f"  [dim]{result.get('note', '')}[/dim]")
+                if "comment" in result:
+                    comment = result["comment"]
+                    if isinstance(comment, dict) and "id" in comment:
+                        console.print(f"  Comment ID: {comment['id']}")
+
+        else:
+            # Error case
+            error_msg = result.get("error", "Unknown error")
+            console.print(f"\n[red]✗[/red] Failed to attach file: {error_msg}")
+            raise typer.Exit(1) from None
+
+    except Exception as e:
+        console.print(f"\n[red]✗[/red] Failed to attach file: {e}")
         raise typer.Exit(1) from None
 
 
@@ -567,11 +986,25 @@ def update(
         None, "--priority", "-p", help="New priority"
     ),
     assignee: str | None = typer.Option(None, "--assignee", "-a", help="New assignee"),
+    wait: bool = typer.Option(
+        False,
+        "--wait",
+        "-w",
+        help="Wait for operation to complete (synchronous mode)",
+    ),
+    timeout: float = typer.Option(
+        30.0,
+        "--timeout",
+        help="Timeout in seconds for --wait mode (default: 30)",
+    ),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
     """Update ticket fields."""
+    from .utils import format_json_response
+
     updates = {}
     if title:
         updates["title"] = title
@@ -585,7 +1018,16 @@ def update(
         updates["assignee"] = assignee
 
     if not updates:
-        console.print("[yellow]No updates specified[/yellow]")
+        if output_json:
+            console.print(
+                format_json_response(
+                    "error",
+                    {"error": "No updates specified"},
+                    message="No updates specified",
+                )
+            )
+        else:
+            console.print("[yellow]No updates specified[/yellow]")
         raise typer.Exit(1) from None
 
     # Get the adapter name
@@ -606,18 +1048,77 @@ def update(
         project_dir=str(Path.cwd()),  # Explicitly pass current project directory
     )
 
-    console.print(f"[green]✓[/green] Queued ticket update: {queue_id}")
-    for key, value in updates.items():
-        if key != "ticket_id":
-            console.print(f"  {key}: {value}")
-    console.print(
-        "[dim]Use 'mcp-ticketer ticket check {queue_id}' to check progress[/dim]"
-    )
-
     # Start worker if needed
     manager = WorkerManager()
     if manager.start_if_needed():
-        console.print("[dim]Worker started to process request[/dim]")
+        if not output_json:
+            console.print("[dim]Worker started to process request[/dim]")
+
+    # SYNCHRONOUS MODE: Poll until completion if --wait flag is set
+    if wait:
+        from .utils import format_error_json
+
+        if not output_json:
+            console.print(
+                f"[yellow]⏳[/yellow] Waiting for update to complete (timeout: {timeout}s)..."
+            )
+
+        try:
+            # Poll the queue until operation completes
+            completed_item = queue.poll_until_complete(queue_id, timeout=timeout)
+            result = completed_item.result
+
+            if output_json:
+                data = result if result else {"queue_id": queue_id, "id": ticket_id}
+                console.print(
+                    format_json_response(
+                        "success", data, message="Ticket updated successfully"
+                    )
+                )
+            else:
+                console.print(
+                    f"[green]✓[/green] Ticket updated successfully: {ticket_id}"
+                )
+                for key, value in updates.items():
+                    if key != "ticket_id":
+                        console.print(f"  {key}: {value}")
+
+        except TimeoutError as e:
+            if output_json:
+                console.print(format_error_json(str(e), queue_id=queue_id))
+            else:
+                console.print(f"[red]❌[/red] Operation timed out after {timeout}s")
+                console.print(f"  Queue ID: {queue_id}")
+            raise typer.Exit(1) from None
+
+        except RuntimeError as e:
+            if output_json:
+                console.print(format_error_json(str(e), queue_id=queue_id))
+            else:
+                console.print(f"[red]❌[/red] Operation failed: {e}")
+            raise typer.Exit(1) from None
+
+    # ASYNCHRONOUS MODE (default)
+    else:
+        if output_json:
+            updated_fields = [k for k in updates.keys() if k != "ticket_id"]
+            data = {
+                "id": ticket_id,
+                "queue_id": queue_id,
+                "updated_fields": updated_fields,
+                **{k: v for k, v in updates.items() if k != "ticket_id"},
+            }
+            console.print(
+                format_json_response("success", data, message="Ticket update queued")
+            )
+        else:
+            console.print(f"[green]✓[/green] Queued ticket update: {queue_id}")
+            for key, value in updates.items():
+                if key != "ticket_id":
+                    console.print(f"  {key}: {value}")
+            console.print(
+                "[dim]Use 'mcp-ticketer ticket check {queue_id}' to check progress[/dim]"
+            )
 
 
 @app.command()
@@ -629,6 +1130,18 @@ def transition(
     state: TicketState | None = typer.Option(
         None, "--state", "-s", help="Target state (recommended)"
     ),
+    wait: bool = typer.Option(
+        False,
+        "--wait",
+        "-w",
+        help="Wait for operation to complete (synchronous mode)",
+    ),
+    timeout: float = typer.Option(
+        30.0,
+        "--timeout",
+        help="Timeout in seconds for --wait mode (default: 30)",
+    ),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
@@ -644,16 +1157,25 @@ def transition(
         mcp-ticketer ticket transition BTA-215 done
 
     """
+    from .utils import format_json_response
+
     # Determine which state to use (prefer flag over positional)
     target_state = state if state is not None else state_positional
 
     if target_state is None:
-        console.print("[red]Error: State is required[/red]")
-        console.print(
-            "Use either:\n"
-            "  - Flag syntax (recommended): mcp-ticketer ticket transition TICKET-ID --state STATE\n"
-            "  - Positional syntax: mcp-ticketer ticket transition TICKET-ID STATE"
-        )
+        if output_json:
+            console.print(
+                format_json_response(
+                    "error", {"error": "State is required"}, message="State is required"
+                )
+            )
+        else:
+            console.print("[red]Error: State is required[/red]")
+            console.print(
+                "Use either:\n"
+                "  - Flag syntax (recommended): mcp-ticketer ticket transition TICKET-ID --state STATE\n"
+                "  - Positional syntax: mcp-ticketer ticket transition TICKET-ID STATE"
+            )
         raise typer.Exit(1) from None
 
     # Get the adapter name
@@ -664,28 +1186,92 @@ def transition(
 
     # Add to queue with explicit project directory
     queue = Queue()
+    state_value = target_state.value if hasattr(target_state, "value") else target_state
     queue_id = queue.add(
         ticket_data={
             "ticket_id": ticket_id,
-            "state": (
-                target_state.value if hasattr(target_state, "value") else target_state
-            ),
+            "state": state_value,
         },
         adapter=adapter_name,
         operation="transition",
         project_dir=str(Path.cwd()),  # Explicitly pass current project directory
     )
 
-    console.print(f"[green]✓[/green] Queued state transition: {queue_id}")
-    console.print(f"  Ticket: {ticket_id} → {target_state}")
-    console.print(
-        "[dim]Use 'mcp-ticketer ticket check {queue_id}' to check progress[/dim]"
-    )
-
     # Start worker if needed
     manager = WorkerManager()
     if manager.start_if_needed():
-        console.print("[dim]Worker started to process request[/dim]")
+        if not output_json:
+            console.print("[dim]Worker started to process request[/dim]")
+
+    # SYNCHRONOUS MODE: Poll until completion if --wait flag is set
+    if wait:
+        from .utils import format_error_json
+
+        if not output_json:
+            console.print(
+                f"[yellow]⏳[/yellow] Waiting for transition to complete (timeout: {timeout}s)..."
+            )
+
+        try:
+            # Poll the queue until operation completes
+            completed_item = queue.poll_until_complete(queue_id, timeout=timeout)
+            result = completed_item.result
+
+            if output_json:
+                data = (
+                    result
+                    if result
+                    else {
+                        "id": ticket_id,
+                        "new_state": state_value,
+                        "matched_state": state_value,
+                        "confidence": 1.0,
+                    }
+                )
+                console.print(
+                    format_json_response(
+                        "success", data, message="State transition completed"
+                    )
+                )
+            else:
+                console.print(
+                    f"[green]✓[/green] State transition completed: {ticket_id} → {target_state}"
+                )
+
+        except TimeoutError as e:
+            if output_json:
+                console.print(format_error_json(str(e), queue_id=queue_id))
+            else:
+                console.print(f"[red]❌[/red] Operation timed out after {timeout}s")
+                console.print(f"  Queue ID: {queue_id}")
+            raise typer.Exit(1) from None
+
+        except RuntimeError as e:
+            if output_json:
+                console.print(format_error_json(str(e), queue_id=queue_id))
+            else:
+                console.print(f"[red]❌[/red] Operation failed: {e}")
+            raise typer.Exit(1) from None
+
+    # ASYNCHRONOUS MODE (default)
+    else:
+        if output_json:
+            data = {
+                "id": ticket_id,
+                "queue_id": queue_id,
+                "new_state": state_value,
+                "matched_state": state_value,
+                "confidence": 1.0,
+            }
+            console.print(
+                format_json_response("success", data, message="State transition queued")
+            )
+        else:
+            console.print(f"[green]✓[/green] Queued state transition: {queue_id}")
+            console.print(f"  Ticket: {ticket_id} → {target_state}")
+            console.print(
+                "[dim]Use 'mcp-ticketer ticket check {queue_id}' to check progress[/dim]"
+            )
 
 
 @app.command()
@@ -695,11 +1281,13 @@ def search(
     priority: Priority | None = typer.Option(None, "--priority", "-p"),
     assignee: str | None = typer.Option(None, "--assignee", "-a"),
     limit: int = typer.Option(10, "--limit", "-l"),
+    output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
     adapter: AdapterType | None = typer.Option(
         None, "--adapter", help="Override default adapter"
     ),
 ) -> None:
     """Search tickets with advanced query."""
+    from .utils import format_json_response, serialize_task
 
     async def _search() -> list[Any]:
         adapter_instance = get_adapter(
@@ -717,7 +1305,21 @@ def search(
     tickets = asyncio.run(_search())
 
     if not tickets:
-        console.print("[yellow]No tickets found matching query[/yellow]")
+        if output_json:
+            console.print(
+                format_json_response(
+                    "success", {"tickets": [], "query": query, "count": 0}
+                )
+            )
+        else:
+            console.print("[yellow]No tickets found matching query[/yellow]")
+        return
+
+    # JSON output
+    if output_json:
+        tickets_data = [serialize_task(t) for t in tickets]
+        data = {"tickets": tickets_data, "query": query, "count": len(tickets_data)}
+        console.print(format_json_response("success", data))
         return
 
     # Display results