shotgun-sh 0.2.23.dev1__py3-none-any.whl → 0.2.29.dev2__py3-none-any.whl

shotgun/cli/spec/commands.py

@@ -0,0 +1,130 @@
+"""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 .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,
+            )
+
+        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,30 @@
+"""Pydantic models for spec CLI commands."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+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,165 @@
+"""Shared spec pull service for CLI and TUI."""
+
+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.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 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,
+    ) -> 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
+
+        Returns:
+            PullResult with success status and details
+        """
+
+        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:
+            if is_cancelled and is_cancelled():
+                raise CancelledError()
+
+        # Phase 1: Fetch version metadata
+        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:
+            return PullResult(
+                success=False,
+                spec_name=spec_name,
+                error="No files in this version.",
+            )
+
+        # Phase 2: Backup existing content
+        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
+        total_files = len(files)
+        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)
+
+            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
+        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))
+
+        return PullResult(
+            success=True,
+            spec_name=spec_name,
+            file_count=total_files,
+            backup_path=backup_path,
+            web_url=response.web_url,
+        )

shotgun/codebase/core/ingestor.py

@@ -6,6 +6,7 @@ import os
 import time
 import uuid
 from collections import defaultdict
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -198,11 +199,21 @@ class Ingestor:
                     return True
         return False
 
-    def flush_nodes(self) -> None:
-        """Flush pending node insertions to the database."""
+    def flush_nodes(
+        self,
+        progress_callback: Callable[[int, int], None] | None = None,
+    ) -> None:
+        """Flush pending node insertions to the database.
+
+        Args:
+            progress_callback: Optional callback(current, total) for progress reporting
+        """
         if not self.node_buffer:
             return
 
+        total_nodes = len(self.node_buffer)
+        processed = 0
+
         # Group nodes by label
         nodes_by_label: dict[str, list[dict[str, Any]]] = defaultdict(list)
         for label, properties in self.node_buffer:
@@ -239,9 +250,18 @@ class Ingestor:
                     params = dict(zip(prop_names, prop_values, strict=False))
                     self.conn.execute(query, params)
 
+                    # Report progress
+                    processed += 1
+                    if progress_callback and processed % 10 == 0:
+                        progress_callback(processed, total_nodes)
+
             except Exception as e:
                 logger.error(f"Failed to insert {label} nodes: {e}")
 
+        # Final progress report
+        if progress_callback:
+            progress_callback(total_nodes, total_nodes)
+
         # Log node counts by type
         node_type_counts: dict[str, int] = {}
         for label, _ in self.node_buffer:
@@ -280,11 +300,21 @@ class Ingestor:
 
         # Don't auto-flush relationships - wait for explicit flush_all() to ensure nodes exist first
 
-    def flush_relationships(self) -> None:
-        """Flush pending relationship insertions to the database."""
+    def flush_relationships(
+        self,
+        progress_callback: Callable[[int, int], None] | None = None,
+    ) -> None:
+        """Flush pending relationship insertions to the database.
+
+        Args:
+            progress_callback: Optional callback(current, total) for progress reporting
+        """
         if not self.relationship_buffer:
             return
 
+        total_rels = len(self.relationship_buffer)
+        processed = 0
+
         # Group relationships by type
         rels_by_type: dict[
             str, list[tuple[str, str, Any, str, str, str, Any, dict[str, Any] | None]]
@@ -299,7 +329,7 @@ class Ingestor:
                 to_label,
                 to_key,
                 to_value,
-                properties,
+                _properties,
             ) = rel_data
 
             # Determine actual table name
@@ -323,7 +353,7 @@ class Ingestor:
                         to_label,
                         to_key,
                         to_value,
-                        properties,
+                        _properties,
                     ) = rel_data
 
                     # Build MATCH and MERGE query (use MERGE to avoid duplicate relationships)
@@ -337,6 +367,11 @@ class Ingestor:
                     try:
                         self.conn.execute(query, params)
                         success_count += 1
+
+                        # Report progress
+                        processed += 1
+                        if progress_callback and processed % 10 == 0:
+                            progress_callback(processed, total_rels)
                     except Exception as e:
                         logger.error(
                             f"Failed to create single relationship {table_name}: {from_label}({from_value}) -> {to_label}({to_value})"
@@ -360,6 +395,10 @@ class Ingestor:
                 # Don't swallow the exception - let it propagate
                 raise
 
+        # Final progress report
+        if progress_callback:
+            progress_callback(total_rels, total_rels)
+
         # Log summary of flushed relationships
         logger.info(
             f"Flushed {len(self.relationship_buffer)} relationships: {relationship_counts}"
@@ -586,6 +625,9 @@ class SimpleGraphBuilder:
             self.ignore_dirs = self.ignore_dirs.union(set(exclude_patterns))
         self.progress_callback = progress_callback
 
+        # Generate unique session ID for correlating timing events in PostHog
+        self._index_session_id = str(uuid.uuid4())[:8]
+
         # Caches
         self.structural_elements: dict[Path, str | None] = {}
         self.ast_cache: dict[Path, tuple[Node, str]] = {}
@@ -621,25 +663,129 @@ class SimpleGraphBuilder:
             # Don't let progress callback errors crash the build
             logger.debug(f"Progress callback error: {e}")
 
+    def _log_timing(
+        self,
+        phase: str,
+        duration: float,
+        items: int,
+        extra_props: dict[str, Any] | None = None,
+    ) -> None:
+        """Log timing data to PostHog for analysis."""
+        from shotgun.posthog_telemetry import track_event
+
+        properties: dict[str, Any] = {
+            "session_id": self._index_session_id,
+            "phase": phase,
+            "duration_seconds": round(duration, 3),
+            "item_count": items,
+        }
+        if extra_props:
+            properties.update(extra_props)
+
+        track_event("codebase_index_phase_completed", properties)
+
+    def _log_summary(
+        self,
+        total_duration: float,
+        total_files: int,
+        total_nodes: int,
+        total_relationships: int,
+    ) -> None:
+        """Log indexing summary event to PostHog."""
+        from shotgun.posthog_telemetry import track_event
+
+        track_event(
+            "codebase_index_completed",
+            {
+                "session_id": self._index_session_id,
+                "total_duration_seconds": round(total_duration, 3),
+                "total_files": total_files,
+                "total_nodes": total_nodes,
+                "total_relationships": total_relationships,
+            },
+        )
+
     async def run(self) -> None:
         """Run the three-pass graph building process."""
         logger.info(f"Building graph for project: {self.project_name}")
 
         # Pass 1: Structure
         logger.info("Pass 1: Identifying packages and folders...")
+        t0 = time.time()
         self._identify_structure()
+        t1 = time.time()
+        self._log_timing("structure", t1 - t0, len(self.structural_elements))
 
         # Pass 2: Definitions
         logger.info("Pass 2: Processing files and extracting definitions...")
+        t2 = time.time()
         await self._process_files()
+        t3 = time.time()
+        self._log_timing(
+            "definitions",
+            t3 - t2,
+            len(self.ast_cache),
+            {"file_count": len(self.ast_cache)},
+        )
 
         # Pass 3: Relationships
         logger.info("Pass 3: Processing relationships (calls, imports)...")
+        t4 = time.time()
         self._process_relationships()
+        t5 = time.time()
+        self._log_timing("relationships", t5 - t4, len(self.ast_cache))
 
         # Flush all pending operations
         logger.info("Flushing all data to database...")
-        self.ingestor.flush_all()
+        t6 = time.time()
+        node_count = len(self.ingestor.node_buffer)
+
+        # Create progress callback for flush_nodes
+        def node_progress(current: int, total: int) -> None:
+            self._report_progress(
+                "flush_nodes", "Flushing nodes to database", current, total
+            )
+
+        self.ingestor.flush_nodes(progress_callback=node_progress)
+        self._report_progress(
+            "flush_nodes", "Flushing nodes to database", node_count, node_count, True
+        )
+        t7 = time.time()
+        self._log_timing("flush_nodes", t7 - t6, node_count, {"node_count": node_count})
+
+        rel_count = len(self.ingestor.relationship_buffer)
+
+        # Create progress callback for flush_relationships
+        def rel_progress(current: int, total: int) -> None:
+            self._report_progress(
+                "flush_relationships",
+                "Flushing relationships to database",
+                current,
+                total,
+            )
+
+        self.ingestor.flush_relationships(progress_callback=rel_progress)
+        self._report_progress(
+            "flush_relationships",
+            "Flushing relationships to database",
+            rel_count,
+            rel_count,
+            True,
+        )
+        t8 = time.time()
+        self._log_timing(
+            "flush_relationships", t8 - t7, rel_count, {"relationship_count": rel_count}
+        )
+
+        # Track summary event with totals (no PII - only numeric metadata)
+        total_duration = t8 - t0
+        self._log_summary(
+            total_duration=total_duration,
+            total_files=len(self.ast_cache),
+            total_nodes=node_count,
+            total_relationships=rel_count,
+        )
+
         logger.info("Graph building complete!")
 
     def _identify_structure(self) -> None:

shotgun/codebase/models.py

@@ -29,6 +29,8 @@ class ProgressPhase(StrEnum):
     STRUCTURE = "structure"  # Identifying packages and folders
     DEFINITIONS = "definitions"  # Processing files and extracting definitions
     RELATIONSHIPS = "relationships"  # Processing relationships (calls, imports)
+    FLUSH_NODES = "flush_nodes"  # Flushing nodes to database
+    FLUSH_RELATIONSHIPS = "flush_relationships"  # Flushing relationships to database
 
 
 class IndexProgress(BaseModel):

shotgun/exceptions.py

@@ -153,8 +153,9 @@ class BudgetExceededException(ShotgunAccountException):
         return (
             "⚠️ **Your Shotgun Account budget has been exceeded!**\n\n"
             "Your account has reached its spending limit and cannot process more requests.\n\n"
-            "**Need help?** Contact us for budget increase.\n\n"
-            "• Self-service budget increases are coming soon!\n\n"
+            "**Action Required:** Top up your account to continue using Shotgun.\n\n"
+            "👉 **[Top Up Now at https://app.shotgun.sh/dashboard](https://app.shotgun.sh/dashboard)**\n\n"
+            "**Need help?** Contact us if you have questions about your budget.\n\n"
             f"_Error details: {str(self)}_"
         )
 
@@ -163,8 +164,9 @@ class BudgetExceededException(ShotgunAccountException):
         return (
             "⚠️  Your Shotgun Account budget has been exceeded!\n\n"
             "Your account has reached its spending limit and cannot process more requests.\n\n"
+            "Action Required: Top up your account to continue using Shotgun.\n\n"
+            "→ Top Up Now: https://app.shotgun.sh/dashboard\n\n"
             f"Need help? Contact: {SHOTGUN_CONTACT_EMAIL}\n\n"
-            "• Self-service budget increases are coming soon!\n\n"
             f"Error details: {str(self)}"
         )
 

shotgun/main.py

@@ -32,6 +32,7 @@ from shotgun.cli import (
     feedback,
     plan,
     research,
+    spec,
     specify,
     tasks,
     update,
@@ -95,6 +96,7 @@ app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic ap
 app.add_typer(export.app, name="export", help="Export artifacts to various formats")
 app.add_typer(update.app, name="update", help="Check for and install updates")
 app.add_typer(feedback.app, name="feedback", help="Send us feedback")
+app.add_typer(spec.app, name="spec", help="Manage shared specifications")
 
 
 def version_callback(value: bool) -> None:

shotgun/posthog_telemetry.py

@@ -8,7 +8,7 @@ from pydantic import BaseModel
 
 from shotgun import __version__
 from shotgun.agents.config import get_config_manager
-from shotgun.agents.conversation_manager import ConversationManager
+from shotgun.agents.conversation import ConversationManager
 from shotgun.logging_config import get_early_logger
 from shotgun.settings import settings
 

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -7,11 +7,11 @@ Your extensive expertise spans, among other things:
 ## KEY RULES
 
 {% if interactive_mode %}
-0. Always ask CLARIFYING QUESTIONS using structured output before doing work.
+0. Ask CLARIFYING QUESTIONS using structured output for complex or multi-step tasks when the request lacks sufficient detail.
    - Return your response with the clarifying_questions field populated
-   - Do not make assumptions about what the user wants, get a clear understanding first.
+   - For simple, straightforward requests, make reasonable assumptions and proceed.
+   - Only ask the most critical questions to avoid overwhelming the user.
    - Questions should be clear, specific, and answerable
-   - Do not ask too many questions that might overwhelm the user; prioritize the most important ones.
 {% endif %}
 1. Above all, prefer using tools to do the work and NEVER respond with text.
 2. IMPORTANT: Always ask for review and go ahead to move forward after using write_file().

shotgun/prompts/agents/partials/interactive_mode.j2

@@ -19,10 +19,10 @@ You must return responses using this structured format:
 
 ## When to Use Clarifying Questions
 
-- BEFORE GETTING TO WORK: If the user's request is ambiguous, use clarifying_questions to ask what they want
+- BEFORE GETTING TO WORK: For complex or multi-step tasks where the request is ambiguous or lacks sufficient detail, use clarifying_questions to ask what they want
 - DURING WORK: After using write_file(), you can suggest that the user review it and ask any clarifying questions with clarifying_questions
-- Don't assume - ask for confirmation of your understanding
-- When in doubt about any aspect of the goal, include clarifying_questions
+- For simple, straightforward requests, make reasonable assumptions and proceed
+- Only ask critical questions that significantly impact the outcome
 
 ## Important Notes
 

shotgun/prompts/agents/research.j2

@@ -38,9 +38,6 @@ For research tasks:
 
 ## RESEARCH PRINCIPLES
 
-{% if interactive_mode -%}
-- CRITICAL: BEFORE RUNNING ANY SEARCH TOOL, ASK THE USER FOR APPROVAL using clarifying questions. Include what you plan to search for and ask if they want you to proceed.
-{% endif -%}
 - Build upon existing research rather than starting from scratch
 - Focus on practical, actionable information over theoretical concepts
 - Include specific examples, tools, and implementation details