skill-seekers 2.7.3__py3-none-any.whl

skill_seekers/cli/upload_skill.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Automatic Skill Uploader
+Uploads a skill package to LLM platforms (Claude, Gemini, OpenAI, etc.)
+
+Usage:
+    # Claude (default)
+    export ANTHROPIC_API_KEY=sk-ant-...
+    skill-seekers upload output/react.zip
+
+    # Gemini
+    export GOOGLE_API_KEY=AIzaSy...
+    skill-seekers upload output/react-gemini.tar.gz --target gemini
+
+    # OpenAI
+    export OPENAI_API_KEY=sk-proj-...
+    skill-seekers upload output/react-openai.zip --target openai
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+# Import utilities
+try:
+    from utils import print_upload_instructions
+except ImportError:
+    sys.path.insert(0, str(Path(__file__).parent))
+    from utils import print_upload_instructions
+
+
+def upload_skill_api(package_path, target="claude", api_key=None):
+    """
+    Upload skill package to LLM platform
+
+    Args:
+        package_path: Path to skill package file
+        target: Target platform ('claude', 'gemini', 'openai')
+        api_key: Optional API key (otherwise read from environment)
+
+    Returns:
+        tuple: (success, message)
+    """
+    try:
+        from skill_seekers.cli.adaptors import get_adaptor
+    except ImportError:
+        return False, "Adaptor system not available. Reinstall skill-seekers."
+
+    # Get platform-specific adaptor
+    try:
+        adaptor = get_adaptor(target)
+    except ValueError as e:
+        return False, str(e)
+
+    # Get API key
+    if not api_key:
+        api_key = os.environ.get(adaptor.get_env_var_name(), "").strip()
+
+    if not api_key:
+        return False, f"{adaptor.get_env_var_name()} not set. Export your API key first."
+
+    # Validate API key format
+    if not adaptor.validate_api_key(api_key):
+        return False, f"Invalid API key format for {adaptor.PLATFORM_NAME}"
+
+    package_path = Path(package_path)
+
+    # Basic file validation
+    if not package_path.exists():
+        return False, f"File not found: {package_path}"
+
+    skill_name = package_path.stem
+
+    print(f"📤 Uploading skill: {skill_name}")
+    print(f"   Target: {adaptor.PLATFORM_NAME}")
+    print(f"   Source: {package_path}")
+    print(f"   Size: {package_path.stat().st_size:,} bytes")
+    print()
+
+    # Upload using adaptor
+    print(f"⏳ Uploading to {adaptor.PLATFORM_NAME}...")
+
+    try:
+        result = adaptor.upload(package_path, api_key)
+
+        if result["success"]:
+            print()
+            print(f"✅ {result['message']}")
+            print()
+            if result["url"]:
+                print("Your skill is now available at:")
+                print(f"   {result['url']}")
+            if result["skill_id"]:
+                print(f"   Skill ID: {result['skill_id']}")
+            print()
+            return True, "Upload successful"
+        else:
+            return False, result["message"]
+
+    except Exception as e:
+        return False, f"Unexpected error: {str(e)}"
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Upload a skill package to LLM platforms",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Setup:
+  Claude:
+    export ANTHROPIC_API_KEY=sk-ant-...
+
+  Gemini:
+    export GOOGLE_API_KEY=AIzaSy...
+
+  OpenAI:
+    export OPENAI_API_KEY=sk-proj-...
+
+Examples:
+  # Upload to Claude (default)
+  skill-seekers upload output/react.zip
+
+  # Upload to Gemini
+  skill-seekers upload output/react-gemini.tar.gz --target gemini
+
+  # Upload to OpenAI
+  skill-seekers upload output/react-openai.zip --target openai
+
+  # Upload with explicit API key
+  skill-seekers upload output/react.zip --api-key sk-ant-...
+        """,
+    )
+
+    parser.add_argument("package_file", help="Path to skill package file (e.g., output/react.zip)")
+
+    parser.add_argument(
+        "--target",
+        choices=["claude", "gemini", "openai"],
+        default="claude",
+        help="Target LLM platform (default: claude)",
+    )
+
+    parser.add_argument("--api-key", help="Platform API key (or set environment variable)")
+
+    args = parser.parse_args()
+
+    # Upload skill
+    success, message = upload_skill_api(args.package_file, args.target, args.api_key)
+
+    if success:
+        sys.exit(0)
+    else:
+        print(f"\n❌ Upload failed: {message}")
+        print()
+        print("📝 Manual upload instructions:")
+        print_upload_instructions(args.package_file)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

skill_seekers/cli/utils.py

@@ -0,0 +1,432 @@
+#!/usr/bin/env python3
+"""
+Utility functions for Skill Seeker CLI tools
+"""
+
+import logging
+import os
+import platform
+import subprocess
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+def open_folder(folder_path: str | Path) -> bool:
+    """
+    Open a folder in the system file browser
+
+    Args:
+        folder_path: Path to folder to open
+
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    folder_path = Path(folder_path).resolve()
+
+    if not folder_path.exists():
+        print(f"⚠️  Folder not found: {folder_path}")
+        return False
+
+    system = platform.system()
+
+    try:
+        if system == "Linux":
+            # Try xdg-open first (standard)
+            subprocess.run(["xdg-open", str(folder_path)], check=True)
+        elif system == "Darwin":  # macOS
+            subprocess.run(["open", str(folder_path)], check=True)
+        elif system == "Windows":
+            subprocess.run(["explorer", str(folder_path)], check=True)
+        else:
+            print(f"⚠️  Unknown operating system: {system}")
+            return False
+
+        return True
+
+    except subprocess.CalledProcessError:
+        print("⚠️  Could not open folder automatically")
+        return False
+    except FileNotFoundError:
+        print("⚠️  File browser not found on system")
+        return False
+
+
+def has_api_key() -> bool:
+    """
+    Check if ANTHROPIC_API_KEY is set in environment
+
+    Returns:
+        bool: True if API key is set, False otherwise
+    """
+    api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    return len(api_key) > 0
+
+
+def get_api_key() -> str | None:
+    """
+    Get ANTHROPIC_API_KEY from environment
+
+    Returns:
+        str: API key or None if not set
+    """
+    api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
+    return api_key if api_key else None
+
+
+def get_upload_url() -> str:
+    """
+    Get the Claude skills upload URL
+
+    Returns:
+        str: Claude skills upload URL
+    """
+    return "https://claude.ai/skills"
+
+
+def print_upload_instructions(zip_path: str | Path) -> None:
+    """
+    Print clear upload instructions for manual upload
+
+    Args:
+        zip_path: Path to the .zip file to upload
+    """
+    zip_path = Path(zip_path)
+
+    print()
+    print("╔══════════════════════════════════════════════════════════╗")
+    print("║                     NEXT STEP                            ║")
+    print("╚══════════════════════════════════════════════════════════╝")
+    print()
+    print(f"📤 Upload to Claude: {get_upload_url()}")
+    print()
+    print(f"1. Go to {get_upload_url()}")
+    print('2. Click "Upload Skill"')
+    print(f"3. Select: {zip_path}")
+    print("4. Done! ✅")
+    print()
+
+
+def format_file_size(size_bytes: int) -> str:
+    """
+    Format file size in human-readable format
+
+    Args:
+        size_bytes: Size in bytes
+
+    Returns:
+        str: Formatted size (e.g., "45.3 KB")
+    """
+    if size_bytes < 1024:
+        return f"{size_bytes} bytes"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    else:
+        return f"{size_bytes / (1024 * 1024):.1f} MB"
+
+
+def validate_skill_directory(skill_dir: str | Path) -> tuple[bool, str | None]:
+    """
+    Validate that a directory is a valid skill directory
+
+    Args:
+        skill_dir: Path to skill directory
+
+    Returns:
+        tuple: (is_valid, error_message)
+    """
+    skill_path = Path(skill_dir)
+
+    if not skill_path.exists():
+        return False, f"Directory not found: {skill_dir}"
+
+    if not skill_path.is_dir():
+        return False, f"Not a directory: {skill_dir}"
+
+    skill_md = skill_path / "SKILL.md"
+    if not skill_md.exists():
+        return False, f"SKILL.md not found in {skill_dir}"
+
+    return True, None
+
+
+def validate_zip_file(zip_path: str | Path) -> tuple[bool, str | None]:
+    """
+    Validate that a file is a valid skill .zip file
+
+    Args:
+        zip_path: Path to .zip file
+
+    Returns:
+        tuple: (is_valid, error_message)
+    """
+    zip_path = Path(zip_path)
+
+    if not zip_path.exists():
+        return False, f"File not found: {zip_path}"
+
+    if not zip_path.is_file():
+        return False, f"Not a file: {zip_path}"
+
+    if zip_path.suffix != ".zip":
+        return False, f"Not a .zip file: {zip_path}"
+
+    return True, None
+
+
+def read_reference_files(
+    skill_dir: str | Path, max_chars: int = 100000, preview_limit: int = 40000
+) -> dict[str, dict]:
+    """Read reference files from a skill directory with enriched metadata.
+
+    This function reads markdown files from the references/ subdirectory
+    of a skill, applying both per-file and total content limits.
+    Returns enriched metadata including source type, confidence, and path.
+
+    Args:
+        skill_dir (str or Path): Path to skill directory
+        max_chars (int): Maximum total characters to read (default: 100000)
+        preview_limit (int): Maximum characters per file (default: 40000)
+
+    Returns:
+        dict: Dictionary mapping filename to metadata dict with keys:
+            - 'content': File content
+            - 'source': Source type (documentation/github/pdf/api/codebase_analysis)
+            - 'confidence': Confidence level (high/medium/low)
+            - 'path': Relative path from references directory
+            - 'repo_id': Repository identifier for multi-source (e.g., 'encode_httpx'), None for single-source
+
+    Example:
+        >>> refs = read_reference_files('output/react/', max_chars=50000)
+        >>> refs['documentation/api.md']['source']
+        'documentation'
+        >>> refs['documentation/api.md']['confidence']
+        'high'
+    """
+    from pathlib import Path
+
+    skill_path = Path(skill_dir)
+    references_dir = skill_path / "references"
+    references: dict[str, dict] = {}
+
+    if not references_dir.exists():
+        print(f"⚠ No references directory found at {references_dir}")
+        return references
+
+    def _determine_source_metadata(relative_path: Path) -> tuple[str, str, str | None]:
+        """Determine source type, confidence level, and repo_id from path.
+
+        For multi-source support, extracts repo_id from paths like:
+        - codebase_analysis/encode_httpx/ARCHITECTURE.md -> repo_id='encode_httpx'
+        - github/README.md -> repo_id=None (single source)
+
+        Returns:
+            tuple: (source_type, confidence_level, repo_id)
+        """
+        path_str = str(relative_path)
+        repo_id = None  # Default: no repo identity
+
+        # Documentation sources (official docs)
+        if path_str.startswith("documentation/"):
+            return "documentation", "high", None
+
+        # GitHub sources
+        elif path_str.startswith("github/"):
+            # README and releases are medium confidence
+            if "README" in path_str or "releases" in path_str:
+                return "github", "medium", None
+            # Issues are low confidence (user reports)
+            elif "issues" in path_str:
+                return "github", "low", None
+            else:
+                return "github", "medium", None
+
+        # PDF sources (books, manuals)
+        elif path_str.startswith("pdf/"):
+            return "pdf", "high", None
+
+        # Merged API (synthesized from multiple sources)
+        elif path_str.startswith("api/"):
+            return "api", "high", None
+
+        # Codebase analysis (C3.x automated analysis)
+        elif path_str.startswith("codebase_analysis/"):
+            # Extract repo_id from path: codebase_analysis/{repo_id}/...
+            parts = Path(path_str).parts
+            if len(parts) >= 2:
+                repo_id = parts[1]  # e.g., 'encode_httpx', 'encode_httpcore'
+
+            # ARCHITECTURE.md is high confidence (comprehensive)
+            if "ARCHITECTURE" in path_str:
+                return "codebase_analysis", "high", repo_id
+            # Patterns and examples are medium (heuristic-based)
+            elif "patterns" in path_str or "examples" in path_str:
+                return "codebase_analysis", "medium", repo_id
+            # Configuration is high (direct extraction)
+            elif "configuration" in path_str:
+                return "codebase_analysis", "high", repo_id
+            else:
+                return "codebase_analysis", "medium", repo_id
+
+        # Conflicts report (discrepancy detection)
+        elif "conflicts" in path_str:
+            return "conflicts", "medium", None
+
+        # Fallback
+        else:
+            return "unknown", "medium", None
+
+    total_chars = 0
+    # Search recursively for all .md files (including subdirectories like github/README.md)
+    for ref_file in sorted(references_dir.rglob("*.md")):
+        # Note: We now include index.md files as they contain important content
+        # (patterns, examples, configuration analysis)
+
+        content = ref_file.read_text(encoding="utf-8")
+
+        # Limit size per file
+        truncated = False
+        if len(content) > preview_limit:
+            content = content[:preview_limit] + "\n\n[Content truncated...]"
+            truncated = True
+
+        # Use relative path from references_dir as key for nested files
+        relative_path = ref_file.relative_to(references_dir)
+        source_type, confidence, repo_id = _determine_source_metadata(relative_path)
+
+        # Build enriched metadata (with repo_id for multi-source support)
+        references[str(relative_path)] = {
+            "content": content,
+            "source": source_type,
+            "confidence": confidence,
+            "path": str(relative_path),
+            "truncated": truncated,
+            "size": len(content),
+            "repo_id": repo_id,  # None for single-source, repo identifier for multi-source
+        }
+
+        total_chars += len(content)
+
+        # Stop if we've read enough
+        if total_chars > max_chars:
+            print(f"  ℹ Limiting input to {max_chars:,} characters")
+            break
+
+    return references
+
+
+def retry_with_backoff(
+    operation: Callable[[], T],
+    max_attempts: int = 3,
+    base_delay: float = 1.0,
+    operation_name: str = "operation",
+) -> T:
+    """Retry an operation with exponential backoff.
+
+    Useful for network operations that may fail due to transient errors.
+    Waits progressively longer between retries (exponential backoff).
+
+    Args:
+        operation: Function to retry (takes no arguments, returns result)
+        max_attempts: Maximum number of attempts (default: 3)
+        base_delay: Base delay in seconds, doubles each retry (default: 1.0)
+        operation_name: Name for logging purposes (default: "operation")
+
+    Returns:
+        Result of successful operation
+
+    Raises:
+        Exception: Last exception if all retries fail
+
+    Example:
+        >>> def fetch_page():
+        ...     response = requests.get(url, timeout=30)
+        ...     response.raise_for_status()
+        ...     return response.text
+        >>> content = retry_with_backoff(fetch_page, max_attempts=3, operation_name=f"fetch {url}")
+    """
+    last_exception: Exception | None = None
+
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return operation()
+        except Exception as e:
+            last_exception = e
+            if attempt < max_attempts:
+                delay = base_delay * (2 ** (attempt - 1))
+                logger.warning(
+                    "%s failed (attempt %d/%d), retrying in %.1fs: %s",
+                    operation_name,
+                    attempt,
+                    max_attempts,
+                    delay,
+                    e,
+                )
+                time.sleep(delay)
+            else:
+                logger.error("%s failed after %d attempts: %s", operation_name, max_attempts, e)
+
+    # This should always have a value, but mypy doesn't know that
+    if last_exception is not None:
+        raise last_exception
+    raise RuntimeError(f"{operation_name} failed with no exception captured")
+
+
+async def retry_with_backoff_async(
+    operation: Callable[[], T],
+    max_attempts: int = 3,
+    base_delay: float = 1.0,
+    operation_name: str = "operation",
+) -> T:
+    """Async version of retry_with_backoff for async operations.
+
+    Args:
+        operation: Async function to retry (takes no arguments, returns awaitable)
+        max_attempts: Maximum number of attempts (default: 3)
+        base_delay: Base delay in seconds, doubles each retry (default: 1.0)
+        operation_name: Name for logging purposes (default: "operation")
+
+    Returns:
+        Result of successful operation
+
+    Raises:
+        Exception: Last exception if all retries fail
+
+    Example:
+        >>> async def fetch_page():
+        ...     response = await client.get(url, timeout=30.0)
+        ...     response.raise_for_status()
+        ...     return response.text
+        >>> content = await retry_with_backoff_async(fetch_page, operation_name=f"fetch {url}")
+    """
+    import asyncio
+
+    last_exception: Exception | None = None
+
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return await operation()
+        except Exception as e:
+            last_exception = e
+            if attempt < max_attempts:
+                delay = base_delay * (2 ** (attempt - 1))
+                logger.warning(
+                    "%s failed (attempt %d/%d), retrying in %.1fs: %s",
+                    operation_name,
+                    attempt,
+                    max_attempts,
+                    delay,
+                    e,
+                )
+                await asyncio.sleep(delay)
+            else:
+                logger.error("%s failed after %d attempts: %s", operation_name, max_attempts, e)
+
+    if last_exception is not None:
+        raise last_exception
+    raise RuntimeError(f"{operation_name} failed with no exception captured")

skill_seekers/mcp/__init__.py

@@ -0,0 +1,33 @@
+"""Skill Seekers MCP (Model Context Protocol) server package.
+
+This package provides MCP server integration for Claude Code, allowing
+natural language interaction with Skill Seekers tools.
+
+Main modules:
+    - server_fastmcp: FastMCP-based server with 17 tools (MCP 2025 spec)
+    - agent_detector: AI coding agent detection and configuration
+
+Available MCP Tools:
+    - list_configs: List all available preset configurations
+    - generate_config: Generate a new config file for any docs site
+    - validate_config: Validate a config file structure
+    - estimate_pages: Estimate page count before scraping
+    - scrape_docs: Scrape and build a skill
+    - package_skill: Package skill into .zip file (with auto-upload)
+    - upload_skill: Upload .zip to Claude
+    - split_config: Split large documentation configs
+    - generate_router: Generate router/hub skills
+
+Agent Detection:
+    - Supports 5 AI coding agents: Claude Code, Cursor, Windsurf, VS Code + Cline, IntelliJ IDEA
+    - Auto-detects installed agents on Linux, macOS, and Windows
+    - Generates correct MCP config for each agent (stdio vs HTTP)
+
+Usage:
+    The MCP server is typically run by Claude Code via configuration
+    in ~/.config/claude-code/mcp.json
+"""
+
+__version__ = "2.7.2"
+
+__all__ = ["agent_detector"]