shotgun-sh 0.2.8.dev2__py3-none-any.whl → 0.3.3.dev1__py3-none-any.whl

shotgun/cli/research.py

@@ -11,7 +11,10 @@ from shotgun.agents.research import (
     create_research_agent,
     run_research_agent,
 )
+from shotgun.cli.error_handler import print_agent_error
+from shotgun.exceptions import ErrorNotPickedUpBySentry
 from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
 
 app = typer.Typer(
     name="research", help="Perform research with agentic loops", no_args_is_help=True
@@ -59,8 +62,6 @@ async def async_research(
 ) -> None:
     """Async wrapper for research process."""
     # Track research command usage
-    from shotgun.posthog_telemetry import track_event
-
     track_event(
         "research_command",
         {
@@ -73,13 +74,20 @@ async def async_research(
     agent_runtime_options = AgentRuntimeOptions(interactive_mode=not non_interactive)
 
     # Create the research agent with deps and provider
-    agent, deps = create_research_agent(agent_runtime_options, provider)
+    agent, deps = await create_research_agent(agent_runtime_options, provider)
 
-    # Start research process
+    # Start research process with error handling
     logger.info("🔬 Starting research...")
-    result = await run_research_agent(agent, query, deps)
-
-    # Display results
-    print("✅ Research Complete!")
-    print("📋 Findings:")
-    print(result.output)
+    try:
+        result = await run_research_agent(agent, query, deps)
+        # Display results
+        print("✅ Research Complete!")
+        print("📋 Findings:")
+        print(result.output)
+    except ErrorNotPickedUpBySentry as e:
+        # All user-actionable errors - display with plain text
+        print_agent_error(e)
+    except Exception as e:
+        # Unexpected errors that weren't wrapped (shouldn't happen)
+        logger.exception("Unexpected error in research command")
+        print(f"⚠️  An unexpected error occurred: {str(e)}")

shotgun/cli/spec/__init__.py

@@ -0,0 +1,5 @@
+"""Spec CLI module."""
+
+from .commands import app
+
+__all__ = ["app"]

shotgun/cli/spec/backup.py

@@ -0,0 +1,81 @@
+"""Backup utility for .shotgun/ directory before pulling specs."""
+
+import shutil
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Backup directory location
+BACKUP_DIR = Path.home() / ".shotgun-sh" / "backups"
+
+
+async def create_backup(shotgun_dir: Path) -> str | None:
+    """Create a zip backup of the .shotgun/ directory.
+
+    Creates a timestamped backup at ~/.shotgun-sh/backups/{YYYYMMDD_HHMMSS}.zip.
+    Only creates backup if the directory exists and has content.
+
+    Args:
+        shotgun_dir: Path to the .shotgun/ directory to backup
+
+    Returns:
+        Path to the backup file as string, or None if no backup was created
+        (e.g., directory doesn't exist or is empty)
+
+    Raises:
+        Exception: If backup creation fails (caller should handle)
+    """
+    # Check if directory exists and has content
+    if not shotgun_dir.exists():
+        logger.debug("No .shotgun/ directory to backup")
+        return None
+
+    files_to_backup = list(shotgun_dir.rglob("*"))
+    if not any(f.is_file() for f in files_to_backup):
+        logger.debug(".shotgun/ directory is empty, skipping backup")
+        return None
+
+    # Create backup directory if needed
+    BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Generate timestamp-based filename
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    backup_path = BACKUP_DIR / f"{timestamp}.zip"
+
+    logger.info("Creating backup of .shotgun/ at %s", backup_path)
+
+    # Create zip file
+    with zipfile.ZipFile(backup_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+        for file_path in files_to_backup:
+            if file_path.is_file():
+                # Store with path relative to shotgun_dir
+                arcname = file_path.relative_to(shotgun_dir)
+                zipf.write(file_path, arcname)
+                logger.debug("Added to backup: %s", arcname)
+
+    logger.info("Backup created successfully: %s", backup_path)
+    return str(backup_path)
+
+
+def clear_shotgun_dir(shotgun_dir: Path) -> None:
+    """Clear all contents of the .shotgun/ directory.
+
+    Removes all files and subdirectories but keeps the .shotgun/ directory itself.
+
+    Args:
+        shotgun_dir: Path to the .shotgun/ directory to clear
+    """
+    if not shotgun_dir.exists():
+        return
+
+    for item in shotgun_dir.iterdir():
+        if item.is_dir():
+            shutil.rmtree(item)
+        else:
+            item.unlink()
+
+    logger.debug("Cleared contents of %s", shotgun_dir)

shotgun/cli/spec/commands.py

@@ -0,0 +1,132 @@
+"""Spec management commands for shotgun CLI."""
+
+import asyncio
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.progress import BarColumn, Progress, SpinnerColumn, TaskID, TextColumn
+
+from shotgun.logging_config import get_logger
+from shotgun.shotgun_web.exceptions import (
+    ForbiddenError,
+    NotFoundError,
+    UnauthorizedError,
+)
+from shotgun.tui import app as tui_app
+from shotgun.utils.file_system_utils import get_shotgun_base_path
+
+from .models import PullSource
+from .pull_service import CancelledError, PullProgress, SpecPullService
+
+app = typer.Typer(
+    name="spec",
+    help="Manage shared specifications",
+    no_args_is_help=True,
+)
+logger = get_logger(__name__)
+console = Console()
+
+
+@app.command()
+def pull(
+    version_id: Annotated[str, typer.Argument(help="Version ID to pull")],
+    no_tui: Annotated[
+        bool,
+        typer.Option("--no-tui", help="Run in CLI-only mode (requires existing auth)"),
+    ] = False,
+) -> None:
+    """Pull a spec version from the cloud to local .shotgun/ directory.
+
+    Downloads all files for the specified version and writes them to the
+    local .shotgun/ directory. If the directory already has content, it
+    will be backed up to ~/.shotgun-sh/backups/ before being replaced.
+
+    By default, launches the TUI which handles authentication and shows
+    the pull progress. Use --no-tui for scripted/headless use (requires
+    existing authentication).
+
+    Example:
+        shotgun spec pull 2532e1c7-7068-4d23-9379-58ea439c592f
+    """
+    if no_tui:
+        # CLI-only mode: do pull directly (requires existing auth)
+        success = asyncio.run(_async_pull(version_id))
+        if not success:
+            raise typer.Exit(1)
+    else:
+        # TUI mode: launch TUI which handles auth and pull
+        tui_app.run(pull_version_id=version_id)
+
+
+async def _async_pull(version_id: str) -> bool:
+    """Async implementation of spec pull command.
+
+    Returns:
+        True if pull was successful, False otherwise.
+    """
+    shotgun_dir = get_shotgun_base_path()
+    service = SpecPullService()
+
+    # Track current progress state for rich display
+    current_task_id: TaskID | None = None
+    progress_ctx: Progress | None = None
+
+    def on_progress(p: PullProgress) -> None:
+        nonlocal current_task_id, progress_ctx
+        # For CLI, we just update the description - progress bar handled by result
+        if progress_ctx and current_task_id is not None:
+            progress_ctx.update(current_task_id, description=p.phase)
+            if p.total_files and p.file_index is not None:
+                pct = ((p.file_index + 1) / p.total_files) * 100
+                progress_ctx.update(current_task_id, completed=pct)
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        ) as progress:
+            progress_ctx = progress
+            current_task_id = progress.add_task("Starting...", total=100)
+
+            result = await service.pull_version(
+                version_id=version_id,
+                shotgun_dir=shotgun_dir,
+                on_progress=on_progress,
+                source=PullSource.CLI,
+            )
+
+        if result.success:
+            console.print()
+            console.print(f"[green]Successfully pulled '{result.spec_name}'[/green]")
+            console.print(f"  [dim]Files downloaded:[/dim] {result.file_count}")
+            if result.backup_path:
+                console.print(f"  [dim]Previous backup:[/dim] {result.backup_path}")
+            if result.web_url:
+                console.print(f"  [blue]View in browser:[/blue] {result.web_url}")
+            return True
+        else:
+            console.print(f"[red]Error: {result.error}[/red]")
+            return False
+
+    except UnauthorizedError:
+        console.print(
+            "[red]Not authenticated. Please re-run the command to login.[/red]"
+        )
+        raise typer.Exit(1) from None
+    except NotFoundError:
+        console.print(f"[red]Version not found: {version_id}[/red]")
+        console.print("[dim]Check the version ID and try again.[/dim]")
+        raise typer.Exit(1) from None
+    except ForbiddenError:
+        console.print("[red]You don't have access to this spec.[/red]")
+        raise typer.Exit(1) from None
+    except CancelledError:
+        console.print("[yellow]Pull cancelled.[/yellow]")
+        raise typer.Exit(1) from None
+    except Exception as e:
+        logger.exception("Unexpected error in spec pull")
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1) from None

shotgun/cli/spec/models.py

@@ -0,0 +1,48 @@
+"""Pydantic models for spec CLI commands."""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class PullSource(StrEnum):
+    """Source of spec pull operation for analytics."""
+
+    CLI = "cli"
+    TUI = "tui"
+
+
+class PullPhase(StrEnum):
+    """Phases during spec pull operation for analytics."""
+
+    STARTING = "starting"
+    FETCHING = "fetching"
+    BACKUP = "backup"
+    DOWNLOADING = "downloading"
+    FINALIZING = "finalizing"
+
+
+class SpecMeta(BaseModel):
+    """Metadata stored in .shotgun/meta.json after pulling a spec.
+
+    This file tracks the source of the local spec files and is used
+    by the TUI to display version information and enable future sync operations.
+    """
+
+    version_id: str = Field(description="Pulled version UUID")
+    spec_id: str = Field(description="Spec UUID")
+    spec_name: str = Field(description="Spec name at time of pull")
+    workspace_id: str = Field(description="Workspace UUID")
+    is_latest: bool = Field(
+        description="Whether this was the latest version when pulled"
+    )
+    pulled_at: datetime = Field(description="Timestamp when spec was pulled (UTC)")
+    backup_path: str | None = Field(
+        default=None,
+        description="Path where previous .shotgun/ files were backed up",
+    )
+    web_url: str | None = Field(
+        default=None,
+        description="URL to view this version in the web UI",
+    )

shotgun/cli/spec/pull_service.py

@@ -0,0 +1,219 @@
+"""Shared spec pull service for CLI and TUI."""
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
+from shotgun.shotgun_web.specs_client import SpecsClient
+from shotgun.shotgun_web.supabase_client import download_file_from_url
+
+from .backup import clear_shotgun_dir, create_backup
+from .models import PullPhase, PullSource, SpecMeta
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class PullProgress:
+    """Progress update during spec pull."""
+
+    phase: str
+    file_index: int | None = None
+    total_files: int | None = None
+    current_file: str | None = None
+
+
+@dataclass
+class PullResult:
+    """Result of a spec pull operation."""
+
+    success: bool
+    spec_name: str | None = None
+    file_count: int = 0
+    backup_path: str | None = None
+    web_url: str | None = None
+    error: str | None = None
+
+
+class CancelledError(Exception):
+    """Raised when pull is cancelled."""
+
+
+class SpecPullService:
+    """Service for pulling spec versions from cloud."""
+
+    def __init__(self) -> None:
+        self._client = SpecsClient()
+
+    async def pull_version(
+        self,
+        version_id: str,
+        shotgun_dir: Path,
+        on_progress: Callable[[PullProgress], None] | None = None,
+        is_cancelled: Callable[[], bool] | None = None,
+        source: PullSource = PullSource.CLI,
+    ) -> PullResult:
+        """Pull a spec version to the local directory.
+
+        Args:
+            version_id: The version UUID to pull
+            shotgun_dir: Target directory (typically .shotgun/)
+            on_progress: Optional callback for progress updates
+            is_cancelled: Optional callback to check if cancelled
+            source: Source of the pull request (CLI or TUI)
+
+        Returns:
+            PullResult with success status and details
+        """
+        start_time = time.time()
+        current_phase: PullPhase = PullPhase.STARTING
+        track_event("spec_pull_started", {"source": source.value})
+
+        def report(
+            phase: str,
+            file_index: int | None = None,
+            total_files: int | None = None,
+            current_file: str | None = None,
+        ) -> None:
+            if on_progress:
+                on_progress(
+                    PullProgress(
+                        phase=phase,
+                        file_index=file_index,
+                        total_files=total_files,
+                        current_file=current_file,
+                    )
+                )
+
+        def check_cancelled() -> None:
+            nonlocal current_phase
+            if is_cancelled and is_cancelled():
+                track_event(
+                    "spec_pull_cancelled",
+                    {"source": source.value, "phase": current_phase.value},
+                )
+                raise CancelledError()
+
+        try:
+            # Phase 1: Fetch version metadata
+            current_phase = PullPhase.FETCHING
+            report("Fetching version info...")
+            check_cancelled()
+
+            response = await self._client.get_version_with_files(version_id)
+            spec_name = response.spec_name
+            files = response.files
+
+            if not files:
+                track_event(
+                    "spec_pull_failed",
+                    {
+                        "source": source.value,
+                        "error_type": "EmptyVersion",
+                        "phase": current_phase.value,
+                    },
+                )
+                return PullResult(
+                    success=False,
+                    spec_name=spec_name,
+                    error="No files in this version.",
+                )
+
+            # Phase 2: Backup existing content
+            current_phase = PullPhase.BACKUP
+            backup_path: str | None = None
+            if shotgun_dir.exists():
+                report("Backing up existing files...")
+                check_cancelled()
+
+                backup_path = await create_backup(shotgun_dir)
+                if backup_path:
+                    clear_shotgun_dir(shotgun_dir)
+
+            # Ensure directory exists
+            shotgun_dir.mkdir(parents=True, exist_ok=True)
+
+            # Phase 3: Download files
+            current_phase = PullPhase.DOWNLOADING
+            total_files = len(files)
+            total_bytes = 0
+            for idx, file_info in enumerate(files):
+                check_cancelled()
+
+                report(
+                    f"Downloading files ({idx + 1}/{total_files})...",
+                    file_index=idx,
+                    total_files=total_files,
+                    current_file=file_info.relative_path,
+                )
+
+                if not file_info.download_url:
+                    logger.warning(
+                        "Skipping file without download URL: %s",
+                        file_info.relative_path,
+                    )
+                    continue
+
+                content = await download_file_from_url(file_info.download_url)
+                total_bytes += file_info.size_bytes
+
+                local_path = shotgun_dir / file_info.relative_path
+                local_path.parent.mkdir(parents=True, exist_ok=True)
+                local_path.write_bytes(content)
+
+            # Phase 4: Write meta.json
+            current_phase = PullPhase.FINALIZING
+            report("Finalizing...")
+            check_cancelled()
+
+            meta = SpecMeta(
+                version_id=response.version.id,
+                spec_id=response.spec_id,
+                spec_name=response.spec_name,
+                workspace_id=response.workspace_id,
+                is_latest=response.version.is_latest,
+                pulled_at=datetime.now(timezone.utc),
+                backup_path=backup_path,
+                web_url=response.web_url,
+            )
+            meta_path = shotgun_dir / "meta.json"
+            meta_path.write_text(meta.model_dump_json(indent=2))
+
+            # Track successful completion
+            duration = time.time() - start_time
+            track_event(
+                "spec_pull_completed",
+                {
+                    "source": source.value,
+                    "file_count": total_files,
+                    "total_bytes": total_bytes,
+                    "duration_seconds": round(duration, 2),
+                    "had_backup": backup_path is not None,
+                },
+            )
+
+            return PullResult(
+                success=True,
+                spec_name=spec_name,
+                file_count=total_files,
+                backup_path=backup_path,
+                web_url=response.web_url,
+            )
+
+        except CancelledError:
+            # Already tracked in check_cancelled()
+            raise
+        except Exception as e:
+            track_event(
+                "spec_pull_failed",
+                {
+                    "source": source.value,
+                    "error_type": type(e).__name__,
+                    "phase": current_phase.value,
+                },
+            )
+            raise

shotgun/cli/specify.py

@@ -11,6 +11,8 @@ from shotgun.agents.specify import (
     create_specify_agent,
     run_specify_agent,
 )
+from shotgun.cli.error_handler import print_agent_error
+from shotgun.exceptions import ErrorNotPickedUpBySentry
 from shotgun.logging_config import get_logger
 
 app = typer.Typer(
@@ -44,26 +46,25 @@ def specify(
 
     logger.info("📝 Specification Requirement: %s", requirement)
 
-    try:
-        # Create agent dependencies
-        agent_runtime_options = AgentRuntimeOptions(
-            interactive_mode=not non_interactive
-        )
+    # Create agent dependencies
+    agent_runtime_options = AgentRuntimeOptions(interactive_mode=not non_interactive)
 
-        # Create the specify agent with deps and provider
-        agent, deps = create_specify_agent(agent_runtime_options, provider)
+    # Create the specify agent with deps and provider
+    agent, deps = asyncio.run(create_specify_agent(agent_runtime_options, provider))
 
-        # Start specification process
-        logger.info("📋 Starting specification generation...")
-        result = asyncio.run(run_specify_agent(agent, requirement, deps))
+    # Start specification process with error handling
+    logger.info("📋 Starting specification generation...")
 
-        # Display results
-        logger.info("✅ Specification Complete!")
-        logger.info("📋 Results:")
-        logger.info("%s", result.output)
+    async def async_specify() -> None:
+        try:
+            result = await run_specify_agent(agent, requirement, deps)
+            logger.info("✅ Specification Complete!")
+            logger.info("📋 Results:")
+            logger.info("%s", result.output)
+        except ErrorNotPickedUpBySentry as e:
+            print_agent_error(e)
+        except Exception as e:
+            logger.exception("Unexpected error in specify command")
+            print(f"⚠️  An unexpected error occurred: {str(e)}")
 
-    except Exception as e:
-        logger.error("❌ Error during specification: %s", str(e))
-        import traceback
-
-        logger.debug("Full traceback:\n%s", traceback.format_exc())
+    asyncio.run(async_specify())

shotgun/cli/tasks.py

@@ -11,7 +11,10 @@ from shotgun.agents.tasks import (
     create_tasks_agent,
     run_tasks_agent,
 )
+from shotgun.cli.error_handler import print_agent_error
+from shotgun.exceptions import ErrorNotPickedUpBySentry
 from shotgun.logging_config import get_logger
+from shotgun.posthog_telemetry import track_event
 
 app = typer.Typer(name="tasks", help="Generate task lists with agentic approach")
 logger = get_logger(__name__)
@@ -42,37 +45,34 @@ def tasks(
 
     logger.info("📋 Task Creation Instruction: %s", instruction)
 
-    try:
-        # Track tasks command usage
-        from shotgun.posthog_telemetry import track_event
-
-        track_event(
-            "tasks_command",
-            {
-                "non_interactive": non_interactive,
-                "provider": provider.value if provider else "default",
-            },
-        )
-
-        # Create agent dependencies
-        agent_runtime_options = AgentRuntimeOptions(
-            interactive_mode=not non_interactive
-        )
-
-        # Create the tasks agent with deps and provider
-        agent, deps = create_tasks_agent(agent_runtime_options, provider)
-
-        # Start task creation process
-        logger.info("🎯 Starting task creation...")
-        result = asyncio.run(run_tasks_agent(agent, instruction, deps))
-
-        # Display results
-        logger.info("✅ Task Creation Complete!")
-        logger.info("📋 Results:")
-        logger.info("%s", result.output)
-
-    except Exception as e:
-        logger.error("❌ Error during task creation: %s", str(e))
-        import traceback
-
-        logger.debug("Full traceback:\n%s", traceback.format_exc())
+    # Track tasks command usage
+    track_event(
+        "tasks_command",
+        {
+            "non_interactive": non_interactive,
+            "provider": provider.value if provider else "default",
+        },
+    )
+
+    # Create agent dependencies
+    agent_runtime_options = AgentRuntimeOptions(interactive_mode=not non_interactive)
+
+    # Create the tasks agent with deps and provider
+    agent, deps = asyncio.run(create_tasks_agent(agent_runtime_options, provider))
+
+    # Start task creation process with error handling
+    logger.info("🎯 Starting task creation...")
+
+    async def async_tasks() -> None:
+        try:
+            result = await run_tasks_agent(agent, instruction, deps)
+            logger.info("✅ Task Creation Complete!")
+            logger.info("📋 Results:")
+            logger.info("%s", result.output)
+        except ErrorNotPickedUpBySentry as e:
+            print_agent_error(e)
+        except Exception as e:
+            logger.exception("Unexpected error in tasks command")
+            print(f"⚠️  An unexpected error occurred: {str(e)}")
+
+    asyncio.run(async_tasks())