claude-task-master 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

claude_task_master/api/routes_repo.py

@@ -0,0 +1,317 @@
+"""Repository setup REST API routes for Claude Task Master.
+
+This module provides REST API endpoints for repository setup operations:
+- POST /repo/clone: Clone a git repository to the workspace
+- POST /repo/setup: Set up a cloned repository for development
+- POST /repo/plan: Create a plan for a repository (read-only, no work)
+
+These endpoints support the AI developer workflow where repositories are
+cloned, set up for development, and then work is planned/executed.
+
+Usage:
+    from claude_task_master.api.routes_repo import create_repo_router
+
+    router = create_repo_router()
+    app.include_router(router, prefix="/repo")
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from claude_task_master.api.models import (
+    CloneRepoRequest,
+    CloneRepoResponse,
+    ErrorResponse,
+    PlanRepoRequest,
+    PlanRepoResponse,
+    SetupRepoRequest,
+    SetupRepoResponse,
+)
+from claude_task_master.mcp.tools import (
+    clone_repo,
+    plan_repo,
+    setup_repo,
+)
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter
+    from fastapi.responses import JSONResponse
+
+# Import FastAPI - using try/except for graceful degradation
+try:
+    from fastapi import APIRouter
+    from fastapi.responses import JSONResponse
+
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+def create_repo_router() -> APIRouter:
+    """Create router for repository setup endpoints.
+
+    These endpoints support the AI developer workflow for cloning,
+    setting up, and planning work on repositories.
+
+    Returns:
+        APIRouter configured with repo setup endpoints.
+
+    Raises:
+        ImportError: If FastAPI is not installed.
+    """
+    if not FASTAPI_AVAILABLE:
+        raise ImportError(
+            "FastAPI not installed. Install with: pip install claude-task-master[api]"
+        )
+
+    router = APIRouter(tags=["Repository Setup"])
+
+    @router.post(
+        "/clone",
+        response_model=CloneRepoResponse,
+        responses={
+            400: {"model": ErrorResponse, "description": "Invalid request or clone failed"},
+            500: {"model": ErrorResponse, "description": "Internal server error"},
+        },
+        summary="Clone Repository",
+        description=(
+            "Clone a git repository to the workspace. "
+            "Default target is ~/workspace/claude-task-master/{repo-name}."
+        ),
+    )
+    async def post_clone_repo(
+        clone_request: CloneRepoRequest,
+    ) -> CloneRepoResponse | JSONResponse:
+        """Clone a git repository.
+
+        Clones the specified repository to the workspace directory.
+        If no target directory is specified, clones to
+        ~/workspace/claude-task-master/{repo-name}.
+
+        Args:
+            clone_request: Clone request with URL, optional target_dir, and branch.
+
+        Returns:
+            CloneRepoResponse with clone result including target directory path.
+
+        Raises:
+            400: If the URL is invalid or clone fails.
+            500: If an unexpected error occurs.
+        """
+        try:
+            # Use the MCP tool implementation for consistency
+            result = clone_repo(
+                url=clone_request.url,
+                target_dir=clone_request.target_dir,
+                branch=clone_request.branch,
+            )
+
+            if not result.get("success", False):
+                return JSONResponse(
+                    status_code=400,
+                    content=ErrorResponse(
+                        error="clone_failed",
+                        message=result.get("message", "Clone failed"),
+                        detail=result.get("error"),
+                        suggestion="Check the repository URL and your network connection",
+                    ).model_dump(),
+                )
+
+            return CloneRepoResponse(
+                success=True,
+                message=result.get("message", "Repository cloned successfully"),
+                repo_url=result.get("repo_url"),
+                target_dir=result.get("target_dir"),
+                branch=result.get("branch"),
+            )
+
+        except Exception as e:
+            logger.exception("Error cloning repository")
+            return JSONResponse(
+                status_code=500,
+                content=ErrorResponse(
+                    error="internal_error",
+                    message="Failed to clone repository",
+                    detail=str(e),
+                ).model_dump(),
+            )
+
+    @router.post(
+        "/setup",
+        response_model=SetupRepoResponse,
+        responses={
+            400: {"model": ErrorResponse, "description": "Invalid request or setup failed"},
+            404: {"model": ErrorResponse, "description": "Directory not found"},
+            500: {"model": ErrorResponse, "description": "Internal server error"},
+        },
+        summary="Setup Repository",
+        description=(
+            "Set up a cloned repository for development. "
+            "Detects project type and installs dependencies, creates venv, runs setup scripts."
+        ),
+    )
+    async def post_setup_repo(
+        setup_request: SetupRepoRequest,
+    ) -> SetupRepoResponse | JSONResponse:
+        """Set up a cloned repository for development.
+
+        Detects the project type and performs appropriate setup:
+        - Creates virtual environment (for Python projects)
+        - Installs dependencies (pip, npm, pnpm, yarn, bun)
+        - Runs setup scripts (setup-hooks.sh, setup.sh, etc.)
+
+        Args:
+            setup_request: Setup request with work_dir path.
+
+        Returns:
+            SetupRepoResponse with setup result including steps completed.
+
+        Raises:
+            400: If setup fails.
+            404: If the work directory doesn't exist.
+            500: If an unexpected error occurs.
+        """
+        try:
+            # Use the MCP tool implementation for consistency
+            result = setup_repo(work_dir=setup_request.work_dir)
+
+            if not result.get("success", False):
+                # Determine appropriate error code
+                error_msg = result.get("error", "")
+                if "not found" in error_msg.lower() or "does not exist" in error_msg.lower():
+                    return JSONResponse(
+                        status_code=404,
+                        content=ErrorResponse(
+                            error="not_found",
+                            message=result.get("message", "Directory not found"),
+                            detail=result.get("error"),
+                            suggestion="Ensure the work directory exists and is accessible",
+                        ).model_dump(),
+                    )
+
+                return JSONResponse(
+                    status_code=400,
+                    content=ErrorResponse(
+                        error="setup_failed",
+                        message=result.get("message", "Setup failed"),
+                        detail=result.get("error"),
+                        suggestion="Check the project structure and dependencies",
+                    ).model_dump(),
+                )
+
+            return SetupRepoResponse(
+                success=True,
+                message=result.get("message", "Repository setup completed"),
+                work_dir=result.get("work_dir"),
+                steps_completed=result.get("steps_completed", []),
+                venv_path=result.get("venv_path"),
+                dependencies_installed=result.get("dependencies_installed", False),
+                setup_scripts_run=result.get("setup_scripts_run", []),
+            )
+
+        except Exception as e:
+            logger.exception("Error setting up repository")
+            return JSONResponse(
+                status_code=500,
+                content=ErrorResponse(
+                    error="internal_error",
+                    message="Failed to set up repository",
+                    detail=str(e),
+                ).model_dump(),
+            )
+
+    @router.post(
+        "/plan",
+        response_model=PlanRepoResponse,
+        responses={
+            400: {"model": ErrorResponse, "description": "Invalid request or planning failed"},
+            404: {"model": ErrorResponse, "description": "Directory not found"},
+            500: {"model": ErrorResponse, "description": "Internal server error"},
+        },
+        summary="Plan Repository Work",
+        description=(
+            "Create a plan for a repository without executing any work. "
+            "Uses read-only tools to analyze the codebase and generate a task list."
+        ),
+    )
+    async def post_plan_repo(
+        plan_request: PlanRepoRequest,
+    ) -> PlanRepoResponse | JSONResponse:
+        """Create a plan for a repository.
+
+        Uses read-only tools (Read, Glob, Grep) to analyze the codebase
+        and output a structured plan with tasks and success criteria.
+        No changes are made to the repository.
+
+        Use this after cloning and setting up a repo to plan work before
+        execution, or to get a plan for a new goal in an existing repository.
+
+        Args:
+            plan_request: Plan request with work_dir, goal, and optional model.
+
+        Returns:
+            PlanRepoResponse with plan, criteria, and run_id.
+
+        Raises:
+            400: If planning fails or goal is invalid.
+            404: If the work directory doesn't exist.
+            500: If an unexpected error occurs.
+        """
+        try:
+            # Use the MCP tool implementation for consistency
+            result = plan_repo(
+                work_dir=plan_request.work_dir,
+                goal=plan_request.goal,
+                model=plan_request.model,
+            )
+
+            if not result.get("success", False):
+                # Determine appropriate error code
+                error_msg = result.get("error", "")
+                if "not found" in error_msg.lower() or "does not exist" in error_msg.lower():
+                    return JSONResponse(
+                        status_code=404,
+                        content=ErrorResponse(
+                            error="not_found",
+                            message=result.get("message", "Directory not found"),
+                            detail=result.get("error"),
+                            suggestion="Ensure the work directory exists and is accessible",
+                        ).model_dump(),
+                    )
+
+                return JSONResponse(
+                    status_code=400,
+                    content=ErrorResponse(
+                        error="planning_failed",
+                        message=result.get("message", "Planning failed"),
+                        detail=result.get("error"),
+                        suggestion="Check the goal description and repository structure",
+                    ).model_dump(),
+                )
+
+            return PlanRepoResponse(
+                success=True,
+                message=result.get("message", "Plan created successfully"),
+                work_dir=result.get("work_dir"),
+                goal=result.get("goal"),
+                plan=result.get("plan"),
+                criteria=result.get("criteria"),
+                run_id=result.get("run_id"),
+            )
+
+        except Exception as e:
+            logger.exception("Error planning repository work")
+            return JSONResponse(
+                status_code=500,
+                content=ErrorResponse(
+                    error="internal_error",
+                    message="Failed to create plan",
+                    detail=str(e),
+                ).model_dump(),
+            )
+
+    return router

claude_task_master/bin/claudetm

@@ -33,7 +33,7 @@ set -euo pipefail
 
 # Script version - synchronized with Python package version
 # This should be kept in sync using scripts/sync_version.py
-SCRIPT_VERSION="0.1.2"
+SCRIPT_VERSION="0.1.5"
 
 # Configuration file location
 CONFIG_DIR=".claude-task-master"

claude_task_master/cli.py

@@ -11,6 +11,7 @@ from .cli_commands.control import register_control_commands
 from .cli_commands.fix_pr import register_fix_pr_command
 from .cli_commands.github import register_github_commands
 from .cli_commands.info import register_info_commands
+from .cli_commands.mailbox import register_mailbox_commands
 from .cli_commands.workflow import register_workflow_commands
 from .core.state import StateManager
 from .utils.debug_claude_md import debug_claude_md_detection
@@ -63,12 +64,13 @@ def main(
 
 
 # Register commands from submodules
-register_workflow_commands(app)  # start, resume
+register_workflow_commands(app)  # start, resume (resume accepts optional message for plan updates)
 register_info_commands(app)  # status, plan, logs, context, progress
 register_github_commands(app)  # ci-status, ci-logs, pr-comments, pr-status
 register_config_commands(app)  # config init, config show, config path
 register_control_commands(app)  # pause, stop, config-update
 register_fix_pr_command(app)  # fix-pr
+register_mailbox_commands(app)  # mailbox, mailbox send, mailbox clear
 
 
 @app.command()

claude_task_master/cli_commands/mailbox.py

@@ -0,0 +1,295 @@
+"""Mailbox CLI commands for Claude Task Master.
+
+This module provides CLI commands for interacting with the mailbox:
+- mailbox (status) - show mailbox status
+- mailbox send - send a message to the mailbox
+- mailbox clear - clear all messages
+"""
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..core.state import StateManager
+from ..mailbox.models import Priority
+from ..mailbox.storage import MailboxStorage
+
+console = Console()
+
+
+def get_mailbox_storage() -> MailboxStorage:
+    """Get mailbox storage instance using state manager's directory.
+
+    Returns:
+        MailboxStorage instance configured for the current project.
+    """
+    state_manager = StateManager()
+    return MailboxStorage(state_dir=state_manager.state_dir)
+
+
+def mailbox_status() -> None:
+    """Show mailbox status.
+
+    Displays the number of pending messages and their previews.
+
+    Examples:
+        claudetm mailbox
+    """
+    state_manager = StateManager()
+
+    if not state_manager.exists():
+        console.print("[yellow]No active task found.[/yellow]")
+        console.print("[dim]Start a task first with 'claudetm start'.[/dim]")
+        raise typer.Exit(1)
+
+    try:
+        mailbox = get_mailbox_storage()
+        status = mailbox.get_status()
+
+        console.print("\n[bold blue]Mailbox Status[/bold blue]\n")
+
+        # Show summary
+        count = status["count"]
+        if count == 0:
+            console.print("[dim]No pending messages.[/dim]")
+        else:
+            console.print(f"[cyan]Pending messages:[/cyan] {count}")
+
+        # Show last checked
+        if status["last_checked"]:
+            console.print(f"[cyan]Last checked:[/cyan] {status['last_checked']}")
+
+        # Show total received
+        console.print(f"[cyan]Total received:[/cyan] {status['total_messages_received']}")
+
+        # Show message previews if any
+        if status["previews"]:
+            console.print()
+            table = Table(title="Messages")
+            table.add_column("Priority", style="cyan", width=8)
+            table.add_column("Sender", style="green", width=15)
+            table.add_column("Content", style="white")
+            table.add_column("Time", style="dim", width=20)
+
+            priority_names = {0: "LOW", 1: "NORMAL", 2: "HIGH", 3: "URGENT"}
+            priority_styles = {0: "dim", 1: "white", 2: "yellow", 3: "red bold"}
+
+            for preview in status["previews"]:
+                prio = preview["priority"]
+                prio_name = priority_names.get(prio, str(prio))
+                prio_style = priority_styles.get(prio, "white")
+
+                table.add_row(
+                    f"[{prio_style}]{prio_name}[/{prio_style}]",
+                    preview["sender"],
+                    preview["content_preview"],
+                    preview["timestamp"][:19].replace("T", " "),  # Truncate and format datetime
+                )
+
+            console.print(table)
+
+        raise typer.Exit(0)
+
+    except typer.Exit:
+        raise
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+def mailbox_send(
+    message: Annotated[str, typer.Argument(help="Message content to send")],
+    sender: Annotated[
+        str,
+        typer.Option("--sender", "-s", help="Sender identifier"),
+    ] = "cli",
+    priority: Annotated[
+        int,
+        typer.Option("--priority", "-p", help="Priority level (0=low, 1=normal, 2=high, 3=urgent)"),
+    ] = 1,
+) -> None:
+    """Send a message to the mailbox.
+
+    Adds a new message that will be processed after the current task completes.
+    The orchestrator checks the mailbox after each task and updates the plan
+    if messages are present.
+
+    Examples:
+        claudetm mailbox send "Please also update the README"
+        claudetm mailbox send "Fix the auth bug first" --priority 3
+        claudetm mailbox send "Low priority cleanup" -p 0 -s "supervisor"
+    """
+    state_manager = StateManager()
+
+    if not state_manager.exists():
+        console.print("[yellow]No active task found.[/yellow]")
+        console.print("[dim]Start a task first with 'claudetm start'.[/dim]")
+        raise typer.Exit(1)
+
+    # Validate priority
+    if priority < 0 or priority > 3:
+        console.print("[red]Error: Priority must be between 0 and 3.[/red]")
+        console.print("[dim]0=low, 1=normal, 2=high, 3=urgent[/dim]")
+        raise typer.Exit(1)
+
+    try:
+        mailbox = get_mailbox_storage()
+        message_id = mailbox.add_message(
+            content=message,
+            sender=sender,
+            priority=Priority(priority),
+        )
+
+        priority_names = {0: "LOW", 1: "NORMAL", 2: "HIGH", 3: "URGENT"}
+        console.print("[green]Message sent to mailbox.[/green]")
+        console.print(f"[dim]ID: {message_id}[/dim]")
+        console.print(f"[dim]Priority: {priority_names.get(priority, str(priority))}[/dim]")
+        console.print(f"[dim]Sender: {sender}[/dim]")
+        console.print()
+        console.print(
+            "[dim]The orchestrator will process this message after the current task.[/dim]"
+        )
+
+        raise typer.Exit(0)
+
+    except typer.Exit:
+        raise
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+def mailbox_clear(
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Skip confirmation"),
+    ] = False,
+) -> None:
+    """Clear all messages from the mailbox.
+
+    Removes all pending messages. This is useful to cancel pending plan updates
+    or start fresh.
+
+    Examples:
+        claudetm mailbox clear
+        claudetm mailbox clear -f
+    """
+    state_manager = StateManager()
+
+    if not state_manager.exists():
+        console.print("[yellow]No active task found.[/yellow]")
+        console.print("[dim]Start a task first with 'claudetm start'.[/dim]")
+        raise typer.Exit(1)
+
+    try:
+        mailbox = get_mailbox_storage()
+        count = mailbox.count()
+
+        if count == 0:
+            console.print("[dim]Mailbox is already empty.[/dim]")
+            raise typer.Exit(0)
+
+        # Confirm unless forced
+        if not force:
+            confirm = typer.confirm(f"Clear {count} message(s) from mailbox?")
+            if not confirm:
+                console.print("[yellow]Cancelled.[/yellow]")
+                raise typer.Exit(0)
+
+        cleared = mailbox.clear()
+        console.print(f"[green]Cleared {cleared} message(s) from mailbox.[/green]")
+
+        raise typer.Exit(0)
+
+    except typer.Exit:
+        raise
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1) from None
+
+
+# Create the mailbox subcommand group
+mailbox_app = typer.Typer(
+    name="mailbox",
+    help="""Manage the mailbox for inter-instance communication.
+
+The mailbox allows external systems (MCP, REST API, other claudetm instances)
+to send messages that will be processed by the orchestrator after each task.
+
+Commands:
+  (no subcommand)  Show mailbox status
+  send             Send a message to the mailbox
+  clear            Clear all messages
+
+Examples:
+    claudetm mailbox                              # Show status
+    claudetm mailbox send "Update the README"     # Send a message
+    claudetm mailbox send "Urgent fix" -p 3       # High priority message
+    claudetm mailbox clear                        # Clear messages
+""",
+    add_completion=False,
+    invoke_without_command=True,
+)
+
+
+@mailbox_app.callback(invoke_without_command=True)
+def mailbox_callback(ctx: typer.Context) -> None:
+    """Show mailbox status when called without subcommand."""
+    if ctx.invoked_subcommand is None:
+        mailbox_status()
+
+
+@mailbox_app.command("send")
+def mailbox_send_command(
+    message: Annotated[str, typer.Argument(help="Message content to send")],
+    sender: Annotated[
+        str,
+        typer.Option("--sender", "-s", help="Sender identifier"),
+    ] = "cli",
+    priority: Annotated[
+        int,
+        typer.Option("--priority", "-p", help="Priority level (0=low, 1=normal, 2=high, 3=urgent)"),
+    ] = 1,
+) -> None:
+    """Send a message to the mailbox.
+
+    Adds a new message that will be processed after the current task completes.
+    The orchestrator checks the mailbox after each task and updates the plan
+    if messages are present.
+
+    Examples:
+        claudetm mailbox send "Please also update the README"
+        claudetm mailbox send "Fix the auth bug first" --priority 3
+        claudetm mailbox send "Low priority cleanup" -p 0 -s "supervisor"
+    """
+    mailbox_send(message, sender, priority)
+
+
+@mailbox_app.command("clear")
+def mailbox_clear_command(
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Skip confirmation"),
+    ] = False,
+) -> None:
+    """Clear all messages from the mailbox.
+
+    Removes all pending messages. This is useful to cancel pending plan updates
+    or start fresh.
+
+    Examples:
+        claudetm mailbox clear
+        claudetm mailbox clear -f
+    """
+    mailbox_clear(force)
+
+
+def register_mailbox_commands(app: typer.Typer) -> None:
+    """Register mailbox commands with the main Typer app.
+
+    Args:
+        app: The main Typer application.
+    """
+    app.add_typer(mailbox_app, name="mailbox")