hud-python 0.3.5__py3-none-any.whl → 0.4.1__py3-none-any.whl

hud/cli/analyze.py

@@ -0,0 +1,371 @@
+"""Analyze command implementation for MCP environments."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.tree import Tree
+
+from hud.clients import MCPClient
+from hud.utils.design import HUDDesign
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+console = Console()
+design = HUDDesign()
+
+
+def parse_docker_command(docker_cmd: list[str]) -> dict:
+    """Convert Docker command to MCP config."""
+    return {
+        "local": {"command": docker_cmd[0], "args": docker_cmd[1:] if len(docker_cmd) > 1 else []}
+    }
+
+
+async def analyze_environment(docker_cmd: list[str], output_format: str, verbose: bool) -> None:
+    """Analyze MCP environment and display results."""
+    design.header("MCP Environment Analysis", icon="🔍")
+
+    # Convert Docker command to MCP config
+    mcp_config = parse_docker_command(docker_cmd)
+
+    # Display command being analyzed
+    design.dim_info("Command:", " ".join(docker_cmd))
+    design.info("")  # Empty line
+
+    # Create client
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Initializing MCP client...", total=None)
+
+        client = MCPClient(mcp_config=mcp_config, verbose=verbose, auto_trace=False)
+
+        try:
+            await client.initialize()
+            progress.update(task, description="[green]✓ Client initialized[/green]")
+
+            # Analyze environment
+            progress.update(task, description="Analyzing environment...")
+            analysis = await client.analyze_environment()
+            progress.update(task, description="[green]✓ Analysis complete[/green]")
+
+        except Exception as e:
+            progress.update(task, description=f"[red]✗ Failed: {e}[/red]")
+
+            # On Windows, Docker stderr might not propagate properly
+            import platform
+
+            if platform.system() == "Windows" and "docker" in docker_cmd[0].lower():
+                console.print("\n[yellow]💡 Tip: Docker logs may not show on Windows.[/yellow]")
+                console.print(f"[yellow]   Try: hud debug {' '.join(docker_cmd[3:])}[/yellow]")
+                console.print("[yellow]   This will show more detailed error information.[/yellow]")
+            elif verbose:
+                console.print("\n[dim]For more details, try running with 'hud debug'[/dim]")
+
+            return
+        finally:
+            await client.shutdown()
+
+    # Display results based on format
+    if output_format == "json":
+        console.print_json(json.dumps(analysis, indent=2))
+    elif output_format == "markdown":
+        display_markdown(analysis)
+    else:  # interactive
+        display_interactive(analysis)
+
+
+def display_interactive(analysis: dict) -> None:
+    """Display analysis results in interactive format."""
+    # Server metadata
+    design.section_title("📊 Environment Overview")
+    meta_table = Table(show_header=False, box=None)
+    meta_table.add_column("Property", style="dim")
+    meta_table.add_column("Value")
+
+    # Check if this is a live analysis (has metadata) or metadata-only analysis
+    if "metadata" in analysis:
+        # Live analysis format
+        for server in analysis["metadata"]["servers"]:
+            meta_table.add_row("Server", f"[green]{server}[/green]")
+        meta_table.add_row(
+            "Initialized",
+            "[green]✓[/green]" if analysis["metadata"]["initialized"] else "[red]✗[/red]",
+        )
+    else:
+        # Metadata-only format
+        if "image" in analysis:
+            # Show simple name in table
+            image = analysis["image"]
+            display_ref = image.split("@")[0] if ":" in image and "@" in image else image
+            meta_table.add_row("Image", f"[green]{display_ref}[/green]")
+
+        if "status" in analysis:
+            meta_table.add_row("Source", analysis.get("source", analysis["status"]).title())
+
+        if "build_info" in analysis:
+            meta_table.add_row("Built", analysis["build_info"].get("generatedAt", "Unknown"))
+            meta_table.add_row("HUD Version", analysis["build_info"].get("hudVersion", "Unknown"))
+
+        if "push_info" in analysis:
+            meta_table.add_row("Pushed", analysis["push_info"].get("pushedAt", "Unknown"))
+
+        if "init_time" in analysis:
+            meta_table.add_row("Init Time", f"{analysis['init_time']} ms")
+
+        if "tool_count" in analysis:
+            meta_table.add_row("Tools", str(analysis["tool_count"]))
+
+    console.print(meta_table)
+
+    # Tools
+    design.section_title("🔧 Available Tools")
+    tools_tree = Tree("Tools")
+
+    # Check if we have hub_tools info (live analysis) or not (metadata-only)
+    if "hub_tools" in analysis:
+        # Live analysis format - separate regular and hub tools
+        # Regular tools
+        regular_tools = tools_tree.add("Regular Tools")
+        for tool in analysis["tools"]:
+            if tool["name"] not in analysis["hub_tools"]:
+                tool_node = regular_tools.add(f"[default]{tool['name']}[/default]")
+                if tool["description"]:
+                    tool_node.add(f"[dim]{tool['description']}[/dim]")
+
+                # Show input schema if verbose
+                if analysis.get("verbose") and tool.get("input_schema"):
+                    schema_str = json.dumps(tool["input_schema"], indent=2)
+                    syntax = Syntax(schema_str, "json", theme="monokai", line_numbers=False)
+                    tool_node.add(syntax)
+
+        # Hub tools
+        if analysis["hub_tools"]:
+            hub_tools = tools_tree.add("Hub Tools")
+            for hub_name, functions in analysis["hub_tools"].items():
+                hub_node = hub_tools.add(f"[yellow]{hub_name}[/yellow]")
+                for func in functions:
+                    hub_node.add(f"[default]{func}[/default]")
+    else:
+        # Metadata-only format - just list all tools
+        for tool in analysis["tools"]:
+            tool_node = tools_tree.add(f"[default]{tool['name']}[/default]")
+            if tool.get("description"):
+                tool_node.add(f"[dim]{tool['description']}[/dim]")
+
+            # Show input schema if verbose
+            if tool.get("inputSchema"):
+                schema_str = json.dumps(tool["inputSchema"], indent=2)
+                syntax = Syntax(schema_str, "json", theme="monokai", line_numbers=False)
+                tool_node.add(syntax)
+
+    console.print(tools_tree)
+
+    # Resources
+    if analysis["resources"]:
+        design.section_title("📚 Available Resources")
+        resources_table = Table()
+        resources_table.add_column("URI", style="default")
+        resources_table.add_column("Name", style="white")
+        resources_table.add_column("Type", style="dim")
+
+        for resource in analysis["resources"][:10]:
+            resources_table.add_row(
+                resource["uri"], resource.get("name", ""), resource.get("mime_type", "")
+            )
+
+        console.print(resources_table)
+
+        if len(analysis["resources"]) > 10:
+            console.print(f"[dim]... and {len(analysis['resources']) - 10} more resources[/dim]")
+
+    # Telemetry (only for live analysis)
+    if analysis.get("telemetry"):
+        design.section_title("📡 Telemetry Data")
+        telemetry_table = Table(show_header=False, box=None)
+        telemetry_table.add_column("Key", style="dim")
+        telemetry_table.add_column("Value")
+
+        if "live_url" in analysis["telemetry"]:
+            telemetry_table.add_row("Live URL", f"[link]{analysis['telemetry']['live_url']}[/link]")
+        if "status" in analysis["telemetry"]:
+            telemetry_table.add_row("Status", f"[green]{analysis['telemetry']['status']}[/green]")
+        if "services" in analysis["telemetry"]:
+            services = analysis["telemetry"]["services"]
+            running = sum(1 for s in services.values() if s == "running")
+            telemetry_table.add_row("Services", f"{running}/{len(services)} running")
+
+        console.print(telemetry_table)
+
+    # Environment variables (for metadata-only analysis)
+    if analysis.get("env_vars"):
+        design.section_title("🔑 Environment Variables")
+        env_table = Table(show_header=False, box=None)
+        env_table.add_column("Type", style="dim")
+        env_table.add_column("Variables")
+
+        if analysis["env_vars"].get("required"):
+            env_table.add_row("Required", ", ".join(analysis["env_vars"]["required"]))
+        if analysis["env_vars"].get("optional"):
+            env_table.add_row("Optional", ", ".join(analysis["env_vars"]["optional"]))
+
+        console.print(env_table)
+
+
+def display_markdown(analysis: dict) -> None:
+    """Display analysis results in markdown format."""
+    md = []
+    md.append("# MCP Environment Analysis\n")
+
+    # Metadata
+    md.append("## Environment Overview")
+
+    # Check if this is live analysis or metadata-only
+    if "metadata" in analysis:
+        md.append(f"- **Servers**: {', '.join(analysis['metadata']['servers'])}")
+        md.append(f"- **Initialized**: {'✓' if analysis['metadata']['initialized'] else '✗'}")
+    else:
+        # Metadata-only format
+        if "image" in analysis:
+            md.append(f"- **Image**: {analysis['image']}")
+        if "source" in analysis:
+            md.append(f"- **Source**: {analysis['source']}")
+        if "build_info" in analysis:
+            md.append(f"- **Built**: {analysis['build_info'].get('generatedAt', 'Unknown')}")
+        if "tool_count" in analysis:
+            md.append(f"- **Tools**: {analysis['tool_count']}")
+
+    md.append("")
+
+    # Tools
+    md.append("## Available Tools\n")
+
+    # Check if we have hub_tools info (live analysis) or not (metadata-only)
+    if "hub_tools" in analysis:
+        # Regular tools
+        md.append("### Regular Tools")
+        for tool in analysis["tools"]:
+            if tool["name"] not in analysis["hub_tools"]:
+                md.extend([f"- **{tool['name']}**: {tool.get('description', 'No description')}"])
+        md.append("")
+
+        # Hub tools
+        if analysis["hub_tools"]:
+            md.append("### Hub Tools")
+            for hub_name, functions in analysis["hub_tools"].items():
+                md.extend([f"- **{hub_name}**"])
+                for func in functions:
+                    md.extend([f"  - {func}"])
+            md.append("")
+    else:
+        # Metadata-only format - just list all tools
+        for tool in analysis["tools"]:
+            md.extend([f"- **{tool['name']}**: {tool.get('description', 'No description')}"])
+        md.append("")
+
+    # Resources
+    if analysis["resources"]:
+        md.append("## Available Resources\n")
+        md.append("| URI | Name | Type |")
+        md.append("|-----|------|------|")
+        for resource in analysis["resources"]:
+            uri = resource["uri"]
+            name = resource.get("name", "")
+            mime_type = resource.get("mime_type", "")
+            md.extend([f"| {uri} | {name} | {mime_type} |"])
+        md.append("")
+
+    # Telemetry (only for live analysis)
+    if analysis.get("telemetry"):
+        md.append("## Telemetry")
+        if "live_url" in analysis["telemetry"]:
+            md.extend([f"- **Live URL**: {analysis['telemetry']['live_url']}"])
+        if "status" in analysis["telemetry"]:
+            md.extend([f"- **Status**: {analysis['telemetry']['status']}"])
+        if "services" in analysis["telemetry"]:
+            md.extend([f"- **Services**: {analysis['telemetry']['services']}"])
+        md.append("")
+
+    # Environment variables (for metadata-only analysis)
+    if analysis.get("env_vars"):
+        md.append("## Environment Variables")
+        if analysis["env_vars"].get("required"):
+            md.extend([f"- **Required**: {', '.join(analysis['env_vars']['required'])}"])
+        if analysis["env_vars"].get("optional"):
+            md.extend([f"- **Optional**: {', '.join(analysis['env_vars']['optional'])}"])
+        md.append("")
+
+    console.print("\n".join(md))
+
+
+async def analyze_environment_from_config(
+    config_path: Path, output_format: str, verbose: bool
+) -> None:
+    """Analyze MCP environment from a JSON config file."""
+    design.header("MCP Environment Analysis", icon="🔍")
+
+    # Load config from file
+    try:
+        with open(config_path) as f:  # noqa: ASYNC230
+            mcp_config = json.load(f)
+        console.print(f"[dim]Config: {config_path}[/dim]\n")
+    except Exception as e:
+        console.print(f"[red]Error loading config: {e}[/red]")
+        return
+
+    await _analyze_with_config(mcp_config, output_format, verbose)
+
+
+async def analyze_environment_from_mcp_config(
+    mcp_config: dict[str, Any], output_format: str, verbose: bool
+) -> None:
+    """Analyze MCP environment from MCP config dict."""
+    design.header("MCP Environment Analysis", icon="🔍")
+    await _analyze_with_config(mcp_config, output_format, verbose)
+
+
+async def _analyze_with_config(
+    mcp_config: dict[str, Any], output_format: str, verbose: bool
+) -> None:
+    """Internal helper to analyze with MCP config."""
+    # Create client
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Initializing MCP client...", total=None)
+
+        client = MCPClient(mcp_config=mcp_config, verbose=verbose)
+
+        try:
+            await client.initialize()
+            progress.update(task, description="[green]✓ Client initialized[/green]")
+
+            # Analyze environment
+            progress.update(task, description="Analyzing environment...")
+            analysis = await client.analyze_environment()
+            progress.update(task, description="[green]✓ Analysis complete[/green]")
+
+        except Exception as e:
+            progress.update(task, description=f"[red]✗ Failed: {e}[/red]")
+            return
+        finally:
+            await client.shutdown()
+
+    # Display results based on format
+    if output_format == "json":
+        console.print_json(json.dumps(analysis, indent=2))
+    elif output_format == "markdown":
+        display_markdown(analysis)
+    else:  # interactive
+        display_interactive(analysis)

hud/cli/analyze_metadata.py

@@ -0,0 +1,230 @@
+"""Fast metadata analysis functions for hud analyze."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import requests
+import yaml
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from hud.settings import settings
+from hud.utils.design import HUDDesign
+
+console = Console()
+design = HUDDesign()
+
+
+def fetch_lock_from_registry(reference: str) -> dict | None:
+    """Fetch lock file from HUD registry."""
+    try:
+        # Reference should be org/name:tag format
+        # If no tag specified, append :latest
+        if "/" in reference and ":" not in reference:
+            reference = f"{reference}:latest"
+
+        registry_url = f"{settings.hud_telemetry_url.rstrip('/')}/registry/envs/{reference}"
+
+        headers = {}
+        if settings.api_key:
+            headers["Authorization"] = f"Bearer {settings.api_key}"
+
+        response = requests.get(registry_url, headers=headers, timeout=10)
+
+        if response.status_code == 200:
+            data = response.json()
+            # Parse the lock YAML from the response
+            if "lock" in data:
+                return yaml.safe_load(data["lock"])
+            elif "lock_data" in data:
+                return data["lock_data"]
+            else:
+                # Try to treat the whole response as lock data
+                return data
+
+        return None
+    except Exception:
+        return None
+
+
+def check_local_cache(reference: str) -> dict | None:
+    """Check local cache for lock file."""
+    # Extract digest if present
+    if "@sha256:" in reference:
+        digest = reference.split("@sha256:")[-1][:12]
+    elif "/" in reference:
+        # Try to find by name pattern
+        cache_dir = Path.home() / ".hud" / "envs"
+        if cache_dir.exists():
+            # Look for any cached version of this image
+            for env_dir in cache_dir.iterdir():
+                if env_dir.is_dir():
+                    lock_file = env_dir / "hud.lock.yaml"
+                    if lock_file.exists():
+                        with open(lock_file) as f:
+                            lock_data = yaml.safe_load(f)
+                        # Check if this matches our reference
+                        if lock_data and "image" in lock_data:
+                            image = lock_data["image"]
+                            # Match by name (ignoring tag/digest)
+                            ref_base = reference.split("@")[0].split(":")[0]
+                            img_base = image.split("@")[0].split(":")[0]
+                            if ref_base in img_base or img_base in ref_base:
+                                return lock_data
+        return None
+    else:
+        digest = "latest"
+
+    # Check specific digest directory
+    lock_file = Path.home() / ".hud" / "envs" / digest / "hud.lock.yaml"
+    if lock_file.exists():
+        with open(lock_file) as f:
+            return yaml.safe_load(f)
+
+    return None
+
+
+async def analyze_from_metadata(reference: str, output_format: str, verbose: bool) -> None:
+    """Analyze environment from cached or registry metadata."""
+    import json
+
+    from .analyze import display_interactive, display_markdown
+
+    design.header("MCP Environment Analysis", icon="🔍")
+    design.info(f"Looking up: {reference}")
+    design.info("")
+
+    lock_data = None
+    source = None
+
+    # 1. Check local cache first
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    ) as progress:
+        task = progress.add_task("Checking local cache...", total=None)
+
+        lock_data = check_local_cache(reference)
+        if lock_data:
+            progress.update(task, description="[green]✓ Found in local cache[/green]")
+            source = "local"
+        else:
+            progress.update(
+                task, description="[yellow]→ Not in cache, checking registry...[/yellow]"
+            )
+
+            # 2. Try HUD registry
+            # Parse reference to get org/name format
+            if "/" in reference and "@" not in reference and ":" not in reference:
+                # Already in org/name format
+                registry_ref = reference
+            elif "/" in reference:
+                # Extract org/name from full reference
+                parts = reference.split("/")
+                if len(parts) >= 2:
+                    # Handle docker.io/org/name or just org/name
+                    if parts[0] in ["docker.io", "registry-1.docker.io", "index.docker.io"]:
+                        # Remove registry prefix but keep tag
+                        registry_ref = "/".join(parts[1:]).split("@")[0]
+                    else:
+                        # Keep org/name:tag format
+                        registry_ref = "/".join(parts[:2]).split("@")[0]
+                else:
+                    registry_ref = reference
+            else:
+                registry_ref = reference
+
+            if not settings.api_key:
+                progress.update(
+                    task, description="[yellow]→ No API key (checking public registry)...[/yellow]"
+                )
+
+            lock_data = fetch_lock_from_registry(registry_ref)
+            if lock_data:
+                progress.update(task, description="[green]✓ Found in HUD registry[/green]")
+                source = "registry"
+
+                # Save to local cache for next time
+                if "@sha256:" in lock_data.get("image", ""):
+                    digest = lock_data["image"].split("@sha256:")[-1][:12]
+                else:
+                    digest = "latest"
+
+                cache_dir = Path.home() / ".hud" / "envs" / digest
+                cache_dir.mkdir(parents=True, exist_ok=True)
+                with open(cache_dir / "hud.lock.yaml", "w") as f:  # noqa: ASYNC230
+                    yaml.dump(lock_data, f, default_flow_style=False, sort_keys=False)
+            else:
+                progress.update(task, description="[red]✗ Not found[/red]")
+
+    if not lock_data:
+        design.error("Environment metadata not found")
+        console.print("\n[yellow]This environment hasn't been analyzed yet.[/yellow]")
+        console.print("\nOptions:")
+        console.print(f"  1. Pull it first: [cyan]hud pull {reference}[/cyan]")
+        console.print(f"  2. Run live analysis: [cyan]hud analyze {reference} --live[/cyan]")
+        if not settings.api_key:
+            console.print("  3. Set HUD_API_KEY for private environments")
+        return
+
+    # Convert lock data to analysis format
+    analysis = {
+        "status": "metadata" if source == "local" else "registry",
+        "source": source,
+        "tools": [],
+        "resources": [],
+        "prompts": [],
+    }
+
+    # Add basic info
+    if "image" in lock_data:
+        analysis["image"] = lock_data["image"]
+
+    if "build" in lock_data:
+        analysis["build_info"] = lock_data["build"]
+
+    if "push" in lock_data:
+        analysis["push_info"] = lock_data["push"]
+
+    # Extract environment info
+    if "environment" in lock_data:
+        env = lock_data["environment"]
+        if "initializeMs" in env:
+            analysis["init_time"] = env["initializeMs"]
+        if "toolCount" in env:
+            analysis["tool_count"] = env["toolCount"]
+        if "variables" in env:
+            analysis["env_vars"] = env["variables"]
+
+    # Extract tools
+    if "tools" in lock_data:
+        for tool in lock_data["tools"]:
+            analysis["tools"].append(
+                {
+                    "name": tool["name"],
+                    "description": tool.get("description", ""),
+                    "inputSchema": tool.get("inputSchema", {}) if verbose else None,
+                }
+            )
+
+    # Display results
+    design.info("")
+    if source == "local":
+        design.dim_info("Source:", "Local cache")
+    else:
+        design.dim_info("Source:", "HUD registry")
+
+    if "image" in analysis:
+        design.dim_info("Image:", analysis["image"])
+
+    design.info("")
+
+    # Display results based on format
+    if output_format == "json":
+        console.print_json(json.dumps(analysis, indent=2))
+    elif output_format == "markdown":
+        display_markdown(analysis)
+    else:  # interactive
+        display_interactive(analysis)