shotgun-sh 0.2.6.dev1__py3-none-any.whl → 0.2.17__py3-none-any.whl

shotgun/prompts/agents/specify.j2

@@ -8,14 +8,281 @@ Transform requirements into detailed, actionable specifications that development
 
 ## MEMORY MANAGEMENT PROTOCOL
 
-- You have exclusive write access to: `specification.md`
+- You have exclusive write access to: `specification.md` and `.shotgun/contracts/*`
 - SHOULD READ `research.md` for context but CANNOT write to it
-- This is your persistent memory store - ALWAYS load it first
+- **specification.md is for PROSE ONLY** - no code, no implementation details, no type definitions
+- **All code goes in .shotgun/contracts/** - types, interfaces, schemas
+- specification.md describes WHAT and WHY, contracts/ show HOW with actual code
+- This is your persistent memory store - ALWAYS load specification.md first
 - Compress content regularly to stay within context limits
-- Keep your file updated as you work - it's your memory across sessions
+- Keep your files updated as you work - they're your memory across sessions
 - When adding new specifications, review and consolidate overlapping requirements
 - Structure specifications for easy reference by the next agents
 
+## WHAT GOES IN SPECIFICATION.MD
+
+specification.md is your prose documentation file. It should contain:
+
+**INCLUDE in specification.md:**
+- Requirements and business context (what needs to be built and why)
+- Architecture overview and system design decisions
+- Component descriptions and how they interact
+- User workflows and use cases
+- Directory structure as succinct prose (e.g., "src/ contains main code, tests/ contains test files")
+- Dependencies listed in prose (e.g., "Requires TypeScript 5.0+, React 18, and PostgreSQL")
+- Configuration requirements described (e.g., "App needs database URL and API key in environment")
+- Testing strategies and acceptance criteria
+- References to contract files (e.g., "See contracts/user_models.py for User type definition")
+
+**DO NOT INCLUDE in specification.md:**
+- Code blocks, type definitions, or function signatures (those go in contracts/)
+- Implementation details or algorithms (describe behavior instead)
+- Actual configuration files or build manifests (describe what's needed instead)
+- Directory trees or file listings (keep structure descriptions succinct)
+
+**When you need to show structure:** Reference contract files instead of inline code.
+Example: "User authentication uses OAuth2. See contracts/auth_types.ts for AuthUser and AuthToken types."
+
+## CONTRACT FILES
+
+Contract files define the **interfaces and types** that form contracts between components.
+They contain actual code that shows structure, not prose descriptions.
+
+**ONLY put these in `.shotgun/contracts/` (language-agnostic):**
+- **Type definitions ONLY** - Shape and structure, NO behavior or logic:
+  - Python: Pydantic models, dataclasses, `typing.Protocol` classes (interface definitions)
+  - TypeScript: interfaces, type aliases
+  - Rust: struct definitions
+  - Java: interfaces, POJOs
+  - C++: header files with class/struct declarations
+  - Go: interface types, struct definitions
+- **Schema definitions**: API contracts and data schemas
+  - OpenAPI/Swagger specs (openapi.json, openapi.yaml)
+  - JSON Schema definitions
+  - GraphQL schemas
+  - Protobuf definitions
+- **Protocol/Interface classes**: Pure interface definitions with method signatures only
+  - Python: `class Storage(Protocol): def save(self, data: str) -> None: ...`
+  - Use `...` (Ellipsis) for protocol methods, NOT `pass`
+
+**NEVER put these in `.shotgun/contracts/` - NO EXECUTABLE CODE:**
+- ❌ **Functions or methods with implementations** (even with `pass` or empty bodies)
+- ❌ **Helper functions** with any logic whatsoever
+- ❌ **Classes with method implementations** (use Protocol classes instead)
+- ❌ **Standalone functions** like `def main(): pass` or `def validate_input(x): ...`
+- ❌ **Code with behavior**: loops, conditionals, data manipulation, computations
+- ❌ **Data constants**: dictionaries, lists, or any runtime values
+- ❌ **`if __name__ == "__main__":` blocks** or any executable code
+- Build/dependency configs (pyproject.toml, package.json, Cargo.toml, requirements.txt)
+- Directory structure files (directory_structure.txt)
+- Configuration templates (.env, config.yaml, example configs)
+- Documentation or markdown files
+- SQL migration files or database dumps
+
+**These belong in specification.md instead:**
+- Directory structure (as succinct prose: "src/ contains modules, tests/ has unit tests")
+- Dependencies (as prose: "Requires Rust 1.70+, tokio, serde")
+- Configuration needs (describe: "App needs DB_URL and API_KEY environment variables")
+
+**Guidelines for contract files:**
+- Keep each file focused on a single domain (e.g., user_types.ts, payment_models.py)
+- Reference from specification.md: "See contracts/user_types.ts for User and Profile types"
+- Use descriptive filenames: `auth_models.py`, `api_spec.json`, `database_types.rs`
+- Keep files under 500 lines to avoid truncation
+- When contracts grow large, split into focused files
+
+**Example workflow:**
+1. In specification.md: "Authentication system with JWT tokens. See contracts/auth_types.ts for types."
+2. Create contract file: `write_file("contracts/auth_types.ts", content)` with actual TypeScript interfaces
+3. Create contract file: `write_file("contracts/auth_api.json", content)` with actual OpenAPI spec
+4. Coding agents can directly use these contracts to implement features
+
+## HOW TO WRITE CONTRACT FILES
+
+**CRITICAL - Always use correct file paths with write_file():**
+
+Your working directory is `.shotgun/`, so paths should be relative to that directory.
+
+<GOOD_EXAMPLES>
+✅ `write_file("contracts/user_models.py", content)` - Correct path for Python models
+✅ `write_file("contracts/auth_types.ts", content)` - Correct path for TypeScript types
+✅ `write_file("contracts/api_spec.json", content)` - Correct path for OpenAPI spec
+✅ `write_file("contracts/payment_service.rs", content)` - Correct path for Rust code
+</GOOD_EXAMPLES>
+
+<BAD_EXAMPLES>
+❌ `write_file(".shotgun/contracts/user_models.py", content)` - WRONG! Don't include .shotgun/ prefix
+❌ `write_file("contracts/directory_structure.txt", content)` - WRONG! No documentation files
+❌ `write_file("contracts/pyproject.toml", content)` - WRONG! No build configs in contracts/
+❌ `write_file("contracts/requirements.txt", content)` - WRONG! No dependency lists in contracts/
+❌ `write_file("contracts/config.yaml", content)` - WRONG! No config templates in contracts/
+</BAD_EXAMPLES>
+
+**Path format rule:** Always use `contracts/filename.ext`, never `.shotgun/contracts/filename.ext`
+
+**Language-specific examples:**
+
+<PYTHON_EXAMPLE>
+# Python Pydantic model contract
+from pydantic import BaseModel, Field
+from typing import Optional
+
+class User(BaseModel):
+    """User model contract."""
+    id: int
+    email: str = Field(..., description="User email address")
+    username: str
+    is_active: bool = True
+    role: Optional[str] = None
+
+# Save as: write_file("contracts/user_models.py", content)
+</PYTHON_EXAMPLE>
+
+<TYPESCRIPT_EXAMPLE>
+// TypeScript interface contract
+interface User {
+  id: number;
+  email: string;
+  username: string;
+  isActive: boolean;
+  role?: string;
+}
+
+interface AuthToken {
+  token: string;
+  expiresAt: Date;
+  userId: number;
+}
+
+// Save as: write_file("contracts/auth_types.ts", content)
+</TYPESCRIPT_EXAMPLE>
+
+<RUST_EXAMPLE>
+// Rust struct contract
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct User {
+    pub id: u64,
+    pub email: String,
+    pub username: String,
+    pub is_active: bool,
+    pub role: Option<String>,
+}
+
+// Save as: write_file("contracts/user_types.rs", content)
+</RUST_EXAMPLE>
+
+<OPENAPI_EXAMPLE>
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "User API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "List users",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/User" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "email": { "type": "string" },
+          "username": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+
+// Save as: write_file("contracts/user_api.json", content)
+</OPENAPI_EXAMPLE>
+
+## WHAT IS ALLOWED vs WHAT IS FORBIDDEN
+
+**✅ ALLOWED - Type Definitions (Shape and Structure):**
+
+```python
+# ✅ GOOD: Pydantic model (type definition)
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    email: str
+    username: str
+
+# ✅ GOOD: Protocol class (interface definition)
+from typing import Protocol
+
+class Storage(Protocol):
+    def save(self, data: str) -> None: ...
+    def load(self) -> str: ...
+
+# ✅ GOOD: Type aliases and enums
+from typing import Literal
+from enum import Enum
+
+UserRole = Literal["admin", "user", "guest"]
+
+class Status(Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+```
+
+**❌ FORBIDDEN - Executable Code (Behavior and Logic):**
+
+```python
+# ❌ BAD: Function with pass (executable code)
+def main() -> int:
+    pass
+
+# ❌ BAD: Function with implementation
+def validate_input(x: str) -> str:
+    return x.strip()
+
+# ❌ BAD: Class with method implementations
+class HistoryManager:
+    def __init__(self):
+        pass
+
+    def add_message(self, msg: str):
+        pass
+
+# ❌ BAD: Data constants (runtime values)
+SUPPORTED_PROVIDERS = [
+    {"name": "openai", "key": "OPENAI_API_KEY"}
+]
+
+# ❌ BAD: Helper functions
+def get_default_config() -> dict:
+    return {"model": "gpt-4"}
+
+# ❌ BAD: Executable code blocks
+if __name__ == "__main__":
+    main()
+```
+
+**Remember**: Contracts define **SHAPES** (types, interfaces, schemas), NOT **BEHAVIOR** (functions, logic, implementations).
+
 ## AI AGENT PIPELINE AWARENESS
 
 **CRITICAL**: Your output will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)

shotgun/prompts/agents/tasks.j2

@@ -99,7 +99,7 @@ Then organize tasks into logical sections:
 USER INTERACTION - ASK CLARIFYING QUESTIONS:
 
 - ALWAYS ask clarifying questions when the request is vague or ambiguous
-- Use ask_user tool to gather specific details about:
+- Use clarifying questions to gather specific details about:
   - Specific features or functionality to prioritize
   - Technical constraints or preferences
   - Timeline and resource constraints

shotgun/sentry_telemetry.py

@@ -1,14 +1,132 @@
 """Sentry observability setup for Shotgun."""
 
-import os
+from pathlib import Path
+from typing import Any
 
 from shotgun import __version__
 from shotgun.logging_config import get_early_logger
+from shotgun.settings import settings
 
 # Use early logger to prevent automatic StreamHandler creation
 logger = get_early_logger(__name__)
 
 
+def _scrub_path(path: str) -> str:
+    """Scrub sensitive information from file paths.
+
+    Removes home directory and current working directory prefixes to prevent
+    leaking usernames that might be part of the path.
+
+    Args:
+        path: The file path to scrub
+
+    Returns:
+        The scrubbed path with sensitive prefixes removed
+    """
+    if not path:
+        return path
+
+    try:
+        # Get home and cwd as Path objects for comparison
+        home = Path.home()
+        cwd = Path.cwd()
+
+        # Convert path to Path object
+        path_obj = Path(path)
+
+        # Try to make path relative to cwd first (most common case)
+        try:
+            relative_to_cwd = path_obj.relative_to(cwd)
+            return str(relative_to_cwd)
+        except ValueError:
+            pass
+
+        # Try to replace home directory with ~
+        try:
+            relative_to_home = path_obj.relative_to(home)
+            return f"~/{relative_to_home}"
+        except ValueError:
+            pass
+
+        # If path is absolute but not under cwd or home, just return filename
+        if path_obj.is_absolute():
+            return path_obj.name
+
+        # Return as-is if already relative
+        return path
+
+    except Exception:
+        # If anything goes wrong, return the original path
+        # Better to leak a path than break error reporting
+        return path
+
+
+def _scrub_sensitive_paths(event: dict[str, Any]) -> None:
+    """Scrub sensitive paths from Sentry event data.
+
+    Modifies the event in-place to remove:
+    - Home directory paths (might contain usernames)
+    - Current working directory paths (might contain usernames)
+    - Server name/hostname
+    - Paths in sys.argv
+
+    Args:
+        event: The Sentry event dictionary to scrub
+    """
+    extra = event.get("extra", {})
+    if "sys.argv" in extra:
+        argv = extra["sys.argv"]
+        if isinstance(argv, list):
+            extra["sys.argv"] = [
+                _scrub_path(arg) if isinstance(arg, str) else arg for arg in argv
+            ]
+
+    # Scrub server name if present
+    if "server_name" in event:
+        event["server_name"] = ""
+
+    # Scrub contexts that might contain paths
+    if "contexts" in event:
+        contexts = event["contexts"]
+        # Remove runtime context if it has CWD
+        if "runtime" in contexts:
+            if "cwd" in contexts["runtime"]:
+                del contexts["runtime"]["cwd"]
+            # Scrub sys.argv to remove paths
+            if "sys.argv" in contexts["runtime"]:
+                argv = contexts["runtime"]["sys.argv"]
+                if isinstance(argv, list):
+                    contexts["runtime"]["sys.argv"] = [
+                        _scrub_path(arg) if isinstance(arg, str) else arg
+                        for arg in argv
+                    ]
+
+    # Scrub exception stack traces
+    if "exception" in event and "values" in event["exception"]:
+        for exception in event["exception"]["values"]:
+            if "stacktrace" in exception and "frames" in exception["stacktrace"]:
+                for frame in exception["stacktrace"]["frames"]:
+                    # Scrub file paths
+                    if "abs_path" in frame:
+                        frame["abs_path"] = _scrub_path(frame["abs_path"])
+                    if "filename" in frame:
+                        frame["filename"] = _scrub_path(frame["filename"])
+
+                    # Scrub local variables that might contain paths
+                    if "vars" in frame:
+                        for var_name, var_value in frame["vars"].items():
+                            if isinstance(var_value, str):
+                                frame["vars"][var_name] = _scrub_path(var_value)
+
+    # Scrub breadcrumbs that might contain paths
+    if "breadcrumbs" in event and "values" in event["breadcrumbs"]:
+        for breadcrumb in event["breadcrumbs"]["values"]:
+            if "data" in breadcrumb:
+                for key, value in breadcrumb["data"].items():
+                    if isinstance(value, str):
+                        breadcrumb["data"][key] = _scrub_path(value)
+
+
 def setup_sentry_observability() -> bool:
     """Set up Sentry observability for error tracking.
 
@@ -23,48 +141,77 @@ def setup_sentry_observability() -> bool:
             logger.debug("Sentry is already initialized, skipping")
             return True
 
-        # Try to get DSN from build constants first (production builds)
-        dsn = None
-        try:
-            from shotgun import build_constants
-
-            dsn = build_constants.SENTRY_DSN
-            logger.debug("Using Sentry DSN from build constants")
-        except ImportError:
-            # Fallback to environment variable (development)
-            dsn = os.getenv("SENTRY_DSN", "")
-            if dsn:
-                logger.debug("Using Sentry DSN from environment variable")
+        # Get DSN from settings (handles build constants + env vars automatically)
+        dsn = settings.telemetry.sentry_dsn
 
         if not dsn:
             logger.debug("No Sentry DSN configured, skipping Sentry initialization")
             return False
 
-        logger.debug("Found DSN, proceeding with Sentry setup")
+        logger.debug("Using Sentry DSN from settings, proceeding with setup")
 
         # Determine environment based on version
-        # Dev versions contain "dev", "rc", "alpha", or "beta"
+        # Dev versions contain "dev", "rc", "alpha", "beta"
         if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
             environment = "development"
         else:
             environment = "production"
 
+        def before_send(event: Any, hint: dict[str, Any]) -> Any:
+            """Filter out user-actionable errors and scrub sensitive paths.
+
+            User-actionable errors (like context size limits) are expected conditions
+            that users need to resolve, not bugs that need tracking.
+
+            Also scrubs sensitive information like usernames from file paths and
+            working directories to protect user privacy.
+            """
+
+            log_record = hint.get("log_record")
+            if log_record:
+                # Scrub pathname using the helper function
+                log_record.pathname = _scrub_path(log_record.pathname)
+
+                # Scrub traceback text if it exists
+                if hasattr(log_record, "exc_text") and isinstance(
+                    log_record.exc_text, str
+                ):
+                    # Replace home directory in traceback text
+                    home = Path.home()
+                    log_record.exc_text = log_record.exc_text.replace(str(home), "~")
+
+            if "exc_info" in hint:
+                _, exc_value, _ = hint["exc_info"]
+                from shotgun.exceptions import ErrorNotPickedUpBySentry
+
+                if isinstance(exc_value, ErrorNotPickedUpBySentry):
+                    # Don't send to Sentry - this is user-actionable, not a bug
+                    return None
+
+            # Scrub sensitive paths from the event
+            _scrub_sensitive_paths(event)
+            return event
+
         # Initialize Sentry
         sentry_sdk.init(
             dsn=dsn,
             release=f"shotgun-sh@{__version__}",
             environment=environment,
             send_default_pii=False,  # Privacy-first: never send PII
+            server_name="",  # Privacy: don't send hostname (may contain username)
             traces_sample_rate=0.1 if environment == "production" else 1.0,
             profiles_sample_rate=0.1 if environment == "production" else 1.0,
+            before_send=before_send,
         )
 
         # Set user context with anonymous shotgun instance ID from config
         try:
+            import asyncio
+
             from shotgun.agents.config import get_config_manager
 
             config_manager = get_config_manager()
-            shotgun_instance_id = config_manager.get_shotgun_instance_id()
+            shotgun_instance_id = asyncio.run(config_manager.get_shotgun_instance_id())
             sentry_sdk.set_user({"id": shotgun_instance_id})
             logger.debug("Sentry user context set with anonymous ID")
         except Exception as e: