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

shotgun/shotgun_web/models.py

@@ -1,6 +1,8 @@
 """Pydantic models for Shotgun Web API."""
 
+from datetime import datetime
 from enum import StrEnum
+from pathlib import Path
 
 from pydantic import BaseModel, Field
 
@@ -45,3 +47,391 @@ class TokenStatusResponse(BaseModel):
     message: str | None = Field(
         default=None, description="Human-readable status message"
     )
+
+
+# ============================================================================
+# Specs API Enums
+# ============================================================================
+
+
+class SpecVersionState(StrEnum):
+    """Spec version lifecycle states."""
+
+    UPLOADING = "uploading"
+    READY = "ready"
+    FAILED = "failed"
+
+
+class WorkspaceRole(StrEnum):
+    """User roles within a workspace."""
+
+    OWNER = "owner"
+    EDITOR = "editor"
+    VIEWER = "viewer"
+
+
+# ============================================================================
+# Workspace Models
+# ============================================================================
+
+
+class WorkspaceResponse(BaseModel):
+    """Workspace details."""
+
+    id: str = Field(description="Workspace UUID")
+    name: str = Field(description="Workspace name")
+
+
+class MeWorkspaceResponse(BaseModel):
+    """Workspace info from /api/me endpoint."""
+
+    id: str = Field(description="Workspace UUID")
+    name: str = Field(description="Workspace name")
+    role: str = Field(description="User's role in workspace")
+
+
+class MeResponse(BaseModel):
+    """Response from /api/me endpoint."""
+
+    id: str = Field(description="User UUID")
+    email: str = Field(description="User email")
+    first_name: str | None = Field(default=None, description="User's first name")
+    last_name: str | None = Field(default=None, description="User's last name")
+    workspace: MeWorkspaceResponse = Field(description="User's workspace info")
+    has_completed_unification: bool = Field(
+        description="Whether unification is complete"
+    )
+    last_unification_at: datetime | None = Field(
+        default=None, description="Last unification timestamp"
+    )
+
+
+class WorkspaceListResponse(BaseModel):
+    """Response for listing user's workspaces."""
+
+    workspaces: list[WorkspaceResponse] = Field(
+        description="List of workspaces the user has access to"
+    )
+
+
+# ============================================================================
+# File Metadata (for file scanner)
+# ============================================================================
+
+
+class FileMetadata(BaseModel):
+    """Metadata for a file discovered by the file scanner."""
+
+    relative_path: str = Field(description="Path relative to .shotgun/ directory")
+    absolute_path: Path = Field(description="Absolute path to the file")
+    size_bytes: int = Field(description="File size in bytes")
+
+
+# ============================================================================
+# Specs API Request Models
+# ============================================================================
+
+
+class SpecCreateRequest(BaseModel):
+    """Request to create a new spec."""
+
+    name: str = Field(
+        description="Human-readable spec name, unique per workspace",
+        min_length=1,
+        max_length=255,
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional description of the spec",
+        max_length=2000,
+    )
+
+
+class SpecUpdateRequest(BaseModel):
+    """Request to update spec metadata or visibility."""
+
+    name: str | None = Field(
+        default=None,
+        description="Update spec name",
+        min_length=1,
+        max_length=255,
+    )
+    description: str | None = Field(
+        default=None,
+        description="Update description",
+        max_length=2000,
+    )
+    is_public: bool | None = Field(
+        default=None,
+        description="Update visibility (public or team-only)",
+    )
+
+
+class SpecVersionCreateRequest(BaseModel):
+    """Request to create a new version for an existing spec."""
+
+    spec_id: str = Field(description="ID of the spec to create version for")
+    label: str | None = Field(
+        default=None,
+        description="Optional version label (e.g., 'v1.0', 'initial')",
+        max_length=100,
+    )
+    notes: str | None = Field(
+        default=None,
+        description="Optional version notes",
+        max_length=2000,
+    )
+
+
+class FileUploadRequest(BaseModel):
+    """Request to upload a file to a spec version."""
+
+    spec_id: str = Field(description="Spec ID")
+    version_id: str = Field(description="Version ID")
+    relative_path: str = Field(
+        description="Path relative to .shotgun/ directory",
+        max_length=1000,
+    )
+    size_bytes: int = Field(description="File size in bytes", gt=0)
+    content_hash: str = Field(
+        description="SHA-256 hash of file content (hex encoded)",
+        min_length=64,
+        max_length=64,
+    )
+
+
+# ============================================================================
+# Specs API Response Models
+# ============================================================================
+
+
+class SpecFileResponse(BaseModel):
+    """Response model for a spec file."""
+
+    id: str = Field(description="File record ID")
+    relative_path: str = Field(description="Path relative to .shotgun/")
+    bucket_key: str = Field(description="Full key in object storage")
+    size_bytes: int = Field(description="File size in bytes")
+    content_hash: str = Field(description="SHA-256 hash (hex)")
+    content_type: str | None = Field(
+        default=None,
+        description="MIME type (e.g., text/markdown, application/json)",
+    )
+    created_on: datetime | None = Field(
+        default=None, description="Upload timestamp (None until upload completes)"
+    )
+    download_url: str | None = Field(
+        default=None,
+        description="Pre-signed download URL (temporary)",
+    )
+
+
+class SpecVersionResponse(BaseModel):
+    """Response model for a spec version."""
+
+    id: str = Field(description="Version ID")
+    spec_id: str = Field(description="Parent spec ID")
+    workspace_id: str | None = Field(default=None, description="Workspace ID")
+    state: SpecVersionState = Field(description="Version state")
+    is_latest: bool = Field(description="Whether this is the latest version")
+    label: str | None = Field(default=None, description="Version label")
+    notes: str | None = Field(default=None, description="Version notes")
+    created_by: str = Field(description="User ID who created this version")
+    created_by_email: str | None = Field(
+        default=None,
+        description="Email of user who created version (hidden for anonymous viewers)",
+    )
+    created_on: datetime | None = Field(default=None, description="Creation timestamp")
+    file_count: int | None = Field(
+        default=None,
+        description="Number of files in this version",
+    )
+    total_size_bytes: int | None = Field(
+        default=None,
+        description="Total size of all files",
+    )
+    web_url: str | None = Field(
+        default=None,
+        description="URL to view this version in the web UI",
+    )
+
+
+class SpecResponse(BaseModel):
+    """Response model for a spec."""
+
+    id: str = Field(description="Spec ID")
+    workspace_id: str = Field(description="Workspace ID")
+    name: str = Field(description="Spec name")
+    description: str | None = Field(default=None, description="Spec description")
+    is_public: bool = Field(
+        default=False,
+        description="Whether spec is publicly accessible",
+    )
+    created_by: str = Field(description="User ID who created the spec")
+    created_by_email: str | None = Field(
+        default=None,
+        description="Email of original creator (hidden for anonymous viewers)",
+    )
+    created_on: datetime | None = Field(default=None, description="Creation timestamp")
+    updated_on: datetime | None = Field(
+        default=None, description="Last update timestamp"
+    )
+    updated_by_email: str | None = Field(
+        default=None,
+        description="Email of user who last updated (hidden for anonymous viewers)",
+    )
+    latest_version: SpecVersionResponse | None = Field(
+        default=None,
+        description="Latest version details (if exists)",
+    )
+    version_count: int = Field(description="Total number of versions")
+
+
+class PublicSpecResponse(BaseModel):
+    """Response model for public spec access (redacted for anonymous users)."""
+
+    id: str = Field(description="Spec ID")
+    name: str = Field(description="Spec name")
+    description: str | None = Field(default=None, description="Spec description")
+    created_on: datetime = Field(description="Creation timestamp")
+    updated_on: datetime = Field(description="Last update timestamp")
+    latest_version: SpecVersionResponse | None = Field(
+        default=None,
+        description="Latest version details (without sensitive user info)",
+    )
+
+
+class SpecListResponse(BaseModel):
+    """Response model for listing specs in a workspace."""
+
+    specs: list[SpecResponse] = Field(description="List of specs")
+    total: int = Field(description="Total number of specs")
+    page: int = Field(default=1, description="Current page number")
+    page_size: int = Field(default=50, description="Items per page")
+
+
+class VersionListResponse(BaseModel):
+    """Response model for listing versions of a spec."""
+
+    versions: list[SpecVersionResponse] = Field(description="List of versions")
+    spec_id: str = Field(description="Spec ID these versions belong to")
+    total: int = Field(description="Total number of versions")
+    page: int = Field(default=1, description="Current page number")
+    page_size: int = Field(default=50, description="Items per page")
+
+
+class FileListResponse(BaseModel):
+    """Response model for listing files in a version."""
+
+    files: list[SpecFileResponse] = Field(description="List of files")
+    version_id: str = Field(description="Version ID these files belong to")
+    total: int = Field(description="Total number of files")
+
+
+class SpecCreateResponse(BaseModel):
+    """Response after creating a spec with initial version."""
+
+    spec: SpecResponse = Field(description="Created spec details")
+    version: SpecVersionResponse = Field(
+        description="Initial version in uploading state"
+    )
+    upload_url: str | None = Field(
+        default=None, description="Base URL for file uploads"
+    )
+
+
+class VersionCreateResponse(BaseModel):
+    """Response after creating a new version."""
+
+    version: SpecVersionResponse = Field(
+        description="Created version in uploading state"
+    )
+    upload_url: str | None = Field(
+        default=None, description="Base URL for file uploads"
+    )
+
+
+class FileUploadResponse(BaseModel):
+    """Response after uploading a file."""
+
+    file: SpecFileResponse = Field(description="Uploaded file details")
+    upload_url: str = Field(description="Pre-signed URL to upload file content to")
+
+
+class VersionCloseResponse(BaseModel):
+    """Response after closing a version."""
+
+    version: SpecVersionResponse = Field(description="Closed version details")
+    web_url: str = Field(description="Web URL to view this version")
+
+
+class VersionWithFilesResponse(BaseModel):
+    """Response for GET /api/versions/{version_id} endpoint.
+
+    This is a convenience endpoint for CLI that returns version info
+    plus all files without requiring workspace_id/spec_id in the path.
+    """
+
+    version: SpecVersionResponse = Field(description="Version details")
+    spec_name: str = Field(description="Name of the parent spec")
+    spec_id: str = Field(description="Parent spec ID")
+    workspace_id: str = Field(description="Workspace ID")
+    files: list[SpecFileResponse] = Field(description="Files in this version")
+    download_urls_expire_at: datetime | None = Field(
+        default=None,
+        description="When presigned download URLs expire (UTC)",
+    )
+    web_url: str | None = Field(
+        default=None,
+        description="URL to view this version in the web UI",
+    )
+
+
+class PermissionCheckResponse(BaseModel):
+    """Response for permission check."""
+
+    workspace_id: str = Field(description="Workspace ID")
+    user_role: WorkspaceRole = Field(description="User's role in workspace")
+    can_create_specs: bool = Field(description="Whether user can create specs")
+    can_upload_versions: bool = Field(description="Whether user can upload versions")
+    can_set_latest: bool = Field(description="Whether user can set latest version")
+    can_change_visibility: bool = Field(
+        description="Whether user can change spec visibility (public/team)"
+    )
+
+
+# ============================================================================
+# Specs API Error Response Models
+# ============================================================================
+
+
+class ErrorDetail(BaseModel):
+    """Detailed error information."""
+
+    field: str | None = Field(default=None, description="Field that caused error")
+    message: str = Field(description="Error message")
+    code: str | None = Field(default=None, description="Machine-readable error code")
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response."""
+
+    error: str = Field(description="Error type or category")
+    message: str = Field(description="Human-readable error message")
+    details: list[ErrorDetail] | None = Field(
+        default=None,
+        description="Detailed error information",
+    )
+    request_id: str | None = Field(
+        default=None,
+        description="Request ID for debugging",
+    )
+
+
+# ============================================================================
+# Custom Exceptions
+# ============================================================================
+
+
+class WorkspaceNotFoundError(Exception):
+    """Raised when user has no workspaces."""

shotgun/shotgun_web/shared_specs/__init__.py

@@ -0,0 +1,32 @@
+"""Shared specs file utilities.
+
+This module provides utilities for scanning and hashing files in the
+.shotgun/ directory for upload to the shared specs API.
+"""
+
+from shotgun.shotgun_web.shared_specs.file_scanner import (
+    get_shotgun_directory,
+    scan_shotgun_directory,
+)
+from shotgun.shotgun_web.shared_specs.hasher import (
+    calculate_sha256,
+    calculate_sha256_with_size,
+)
+from shotgun.shotgun_web.shared_specs.models import (
+    UploadProgress,
+    UploadResult,
+)
+from shotgun.shotgun_web.shared_specs.upload_pipeline import run_upload_pipeline
+from shotgun.shotgun_web.shared_specs.utils import UploadPhase, format_bytes
+
+__all__ = [
+    "UploadPhase",
+    "UploadProgress",
+    "UploadResult",
+    "calculate_sha256",
+    "calculate_sha256_with_size",
+    "format_bytes",
+    "get_shotgun_directory",
+    "run_upload_pipeline",
+    "scan_shotgun_directory",
+]

shotgun/shotgun_web/shared_specs/file_scanner.py

@@ -0,0 +1,175 @@
+"""File scanner for .shotgun/ directory."""
+
+import fnmatch
+from pathlib import Path
+
+from shotgun.logging_config import get_logger
+from shotgun.shotgun_web.models import FileMetadata
+from shotgun.shotgun_web.shared_specs.models import ScanResult
+
+logger = get_logger(__name__)
+
+# Patterns to ignore when scanning .shotgun/ directory
+IGNORE_PATTERNS = [
+    # Shotgun metadata (created by `shotgun spec pull`)
+    "meta.json",
+    # OS-generated files
+    ".DS_Store",
+    "Thumbs.db",
+    # Python cache
+    "__pycache__",
+    "*.pyc",
+    "*.pyo",
+    # Editor files
+    ".vscode",
+    ".idea",
+    "*.swp",
+    "*~",
+    "*.bak",
+    # Git
+    ".git",
+]
+
+
+def _should_ignore(path: Path) -> bool:
+    """Check if a path should be ignored based on ignore patterns.
+
+    Args:
+        path: Path to check (can be file or directory)
+
+    Returns:
+        True if path matches any ignore pattern
+    """
+    name = path.name
+
+    for pattern in IGNORE_PATTERNS:
+        if fnmatch.fnmatch(name, pattern):
+            return True
+
+    return False
+
+
+def _is_in_ignored_directory(path: Path, base_path: Path) -> bool:
+    """Check if a path is inside an ignored directory.
+
+    Args:
+        path: Path to check
+        base_path: Base path to check relative to
+
+    Returns:
+        True if path is inside an ignored directory
+    """
+    relative = path.relative_to(base_path)
+    for part in relative.parts[
+        :-1
+    ]:  # Check all parent directories, not the file itself
+        if any(fnmatch.fnmatch(part, pattern) for pattern in IGNORE_PATTERNS):
+            return True
+    return False
+
+
+async def scan_shotgun_directory(project_root: Path) -> list[FileMetadata]:
+    """Recursively scan .shotgun/ directory and return file metadata.
+
+    Applies ignore patterns to exclude common unwanted files like:
+    - .DS_Store, Thumbs.db
+    - __pycache__, *.pyc, *.pyo
+    - .vscode, .idea, *.swp
+    - *~, *.bak
+
+    Args:
+        project_root: Path to project root containing .shotgun/ directory
+
+    Returns:
+        List of FileMetadata with relative paths (relative to .shotgun/)
+
+    Raises:
+        FileNotFoundError: If .shotgun/ directory does not exist
+    """
+    result = await scan_shotgun_directory_with_counts(project_root)
+    return result.files
+
+
+async def scan_shotgun_directory_with_counts(project_root: Path) -> ScanResult:
+    """Recursively scan .shotgun/ directory and return file metadata with counts.
+
+    Like scan_shotgun_directory, but also returns the total number of files
+    found before filtering. This helps distinguish between:
+    - Empty directory (no files at all)
+    - All files filtered by ignore patterns
+
+    Args:
+        project_root: Path to project root containing .shotgun/ directory
+
+    Returns:
+        ScanResult with files list and total_files_before_filter count
+
+    Raises:
+        FileNotFoundError: If .shotgun/ directory does not exist
+    """
+    shotgun_dir = project_root / ".shotgun"
+
+    if not shotgun_dir.exists():
+        raise FileNotFoundError(f".shotgun/ directory not found at {shotgun_dir}")
+
+    if not shotgun_dir.is_dir():
+        raise NotADirectoryError(f"{shotgun_dir} is not a directory")
+
+    files: list[FileMetadata] = []
+    total_before_filter = 0
+
+    logger.debug("Scanning directory: %s", shotgun_dir)
+
+    for path in shotgun_dir.rglob("*"):
+        # Skip directories
+        if path.is_dir():
+            continue
+
+        # Count all files before filtering
+        total_before_filter += 1
+
+        # Skip ignored files
+        if _should_ignore(path):
+            logger.debug("Ignoring file (pattern match): %s", path)
+            continue
+
+        # Skip files in ignored directories
+        if _is_in_ignored_directory(path, shotgun_dir):
+            logger.debug("Ignoring file (in ignored directory): %s", path)
+            continue
+
+        # Calculate relative path from .shotgun/
+        relative_path = str(path.relative_to(shotgun_dir))
+
+        files.append(
+            FileMetadata(
+                relative_path=relative_path,
+                absolute_path=path,
+                size_bytes=path.stat().st_size,
+            )
+        )
+
+    logger.info(
+        "Found %d files in .shotgun/ (%d before filtering)",
+        len(files),
+        total_before_filter,
+    )
+
+    # Sort by relative path for consistent ordering
+    files.sort(key=lambda f: f.relative_path)
+
+    return ScanResult(files=files, total_files_before_filter=total_before_filter)
+
+
+def get_shotgun_directory(project_root: Path | None = None) -> Path:
+    """Get the .shotgun/ directory path.
+
+    Args:
+        project_root: Optional project root path. If None, uses current directory.
+
+    Returns:
+        Path to .shotgun/ directory
+    """
+    if project_root is None:
+        project_root = Path.cwd()
+    return project_root / ".shotgun"

shotgun/shotgun_web/shared_specs/hasher.py

@@ -0,0 +1,83 @@
+"""Async SHA-256 file hashing utilities."""
+
+import hashlib
+from pathlib import Path
+
+import aiofiles
+
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+# Chunk sizes for reading files
+SMALL_FILE_CHUNK_SIZE = 65536  # 64KB for files < 10MB
+LARGE_FILE_CHUNK_SIZE = 1048576  # 1MB for files >= 10MB
+LARGE_FILE_THRESHOLD = 10 * 1024 * 1024  # 10MB
+
+
+def _get_chunk_size(file_size: int) -> int:
+    """Determine optimal chunk size based on file size.
+
+    Args:
+        file_size: Size of file in bytes
+
+    Returns:
+        Chunk size in bytes (64KB for small files, 1MB for large files)
+    """
+    if file_size >= LARGE_FILE_THRESHOLD:
+        return LARGE_FILE_CHUNK_SIZE
+    return SMALL_FILE_CHUNK_SIZE
+
+
+async def calculate_sha256(file_path: Path) -> str:
+    """Calculate SHA-256 hash of a file using streaming.
+
+    Reads file in chunks to avoid loading entire file into memory.
+    Uses adaptive chunk sizing: 64KB for files <10MB, 1MB for larger files.
+
+    Args:
+        file_path: Path to file to hash
+
+    Returns:
+        Hex-encoded SHA-256 hash string (64 characters)
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        PermissionError: If file is not readable
+    """
+    file_size = file_path.stat().st_size
+    chunk_size = _get_chunk_size(file_size)
+
+    logger.debug(
+        "Calculating SHA-256 for %s (size=%d, chunk_size=%d)",
+        file_path,
+        file_size,
+        chunk_size,
+    )
+
+    sha256_hash = hashlib.sha256()
+
+    async with aiofiles.open(file_path, "rb") as f:
+        while chunk := await f.read(chunk_size):
+            sha256_hash.update(chunk)
+
+    hex_digest = sha256_hash.hexdigest()
+    logger.debug("SHA-256 for %s: %s", file_path, hex_digest)
+
+    return hex_digest
+
+
+async def calculate_sha256_with_size(file_path: Path) -> tuple[str, int]:
+    """Calculate SHA-256 hash and get file size.
+
+    Convenience function that returns both hash and size in one call.
+
+    Args:
+        file_path: Path to file to hash
+
+    Returns:
+        Tuple of (hex-encoded SHA-256 hash, file size in bytes)
+    """
+    file_size = file_path.stat().st_size
+    content_hash = await calculate_sha256(file_path)
+    return content_hash, file_size