foundry-mcp 0.8.22__py3-none-any.whl

foundry_mcp/cli/commands/dev.py

@@ -0,0 +1,446 @@
+"""Development utility commands for SDD CLI.
+
+Provides commands for skills development including:
+- Documentation generation helpers
+- Installation helpers
+- Server start helpers
+- Development tooling
+"""
+
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from foundry_mcp.cli.logging import cli_command, get_cli_logger
+from foundry_mcp.cli.output import emit_error, emit_success
+from foundry_mcp.cli.registry import get_context
+from foundry_mcp.cli.resilience import (
+    FAST_TIMEOUT,
+    MEDIUM_TIMEOUT,
+    handle_keyboard_interrupt,
+    with_sync_timeout,
+)
+
+logger = get_cli_logger()
+
+
+@click.group("dev")
+def dev_group() -> None:
+    """Development utility commands."""
+    pass
+
+
+@dev_group.command("gendocs")
+@click.option(
+    "--output-dir",
+    default="docs",
+    help="Output directory for generated documentation.",
+)
+@click.option(
+    "--format",
+    "doc_format",
+    type=click.Choice(["markdown", "html", "json"]),
+    default="markdown",
+    help="Output format for documentation.",
+)
+@click.option(
+    "--include-private",
+    is_flag=True,
+    help="Include private/internal APIs in documentation.",
+)
+@click.pass_context
+@cli_command("gendocs")
+@handle_keyboard_interrupt()
+@with_sync_timeout(MEDIUM_TIMEOUT, "Documentation generation timed out")
+def dev_gendocs_cmd(
+    ctx: click.Context,
+    output_dir: str,
+    doc_format: str,
+    include_private: bool,
+) -> None:
+    """Generate documentation from source code.
+
+    Scans the codebase and generates API documentation.
+    """
+    start_time = time.perf_counter()
+    cli_ctx = get_context(ctx)
+
+    # Determine project root
+    project_root = cli_ctx.specs_dir.parent if cli_ctx.specs_dir else Path.cwd()
+    output_path = project_root / output_dir
+
+    # Create output directory if needed
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Check for common doc generators
+    generators = []
+
+    # Check pdoc
+    try:
+        result = subprocess.run(
+            ["pdoc", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            generators.append("pdoc")
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # Check sphinx
+    try:
+        result = subprocess.run(
+            ["sphinx-build", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            generators.append("sphinx")
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    duration_ms = (time.perf_counter() - start_time) * 1000
+
+    if not generators:
+        emit_success(
+            {
+                "status": "no_generator",
+                "output_dir": str(output_path),
+                "format": doc_format,
+                "available_generators": [],
+                "recommendations": [
+                    "Install pdoc: pip install pdoc",
+                    "Or install sphinx: pip install sphinx",
+                ],
+                "telemetry": {"duration_ms": round(duration_ms, 2)},
+            }
+        )
+        return
+
+    emit_success(
+        {
+            "status": "ready",
+            "output_dir": str(output_path),
+            "format": doc_format,
+            "available_generators": generators,
+            "include_private": include_private,
+            "telemetry": {"duration_ms": round(duration_ms, 2)},
+        }
+    )
+
+
+@dev_group.command("install")
+@click.option(
+    "--dev",
+    is_flag=True,
+    help="Install with development dependencies.",
+)
+@click.option(
+    "--editable/--no-editable",
+    default=True,
+    help="Install in editable mode (default: true).",
+)
+@click.option(
+    "--extras",
+    help="Comma-separated list of extras to install.",
+)
+@click.pass_context
+@cli_command("install")
+@handle_keyboard_interrupt()
+@with_sync_timeout(300, "Installation timed out")
+def dev_install_cmd(
+    ctx: click.Context,
+    dev: bool,
+    editable: bool,
+    extras: Optional[str],
+) -> None:
+    """Install the package for development.
+
+    Installs the current package with optional dev dependencies.
+    """
+    start_time = time.perf_counter()
+    cli_ctx = get_context(ctx)
+
+    # Determine project root
+    project_root = cli_ctx.specs_dir.parent if cli_ctx.specs_dir else Path.cwd()
+
+    # Check for pyproject.toml or setup.py
+    has_pyproject = (project_root / "pyproject.toml").exists()
+    has_setup = (project_root / "setup.py").exists()
+
+    if not has_pyproject and not has_setup:
+        emit_error(
+            "No Python project found",
+            code="NO_PROJECT",
+            error_type="validation",
+            remediation="Ensure pyproject.toml or setup.py exists in the project root",
+            details={
+                "hint": "Ensure pyproject.toml or setup.py exists",
+                "project_root": str(project_root),
+            },
+        )
+        return
+
+    # Build pip install command
+    cmd = ["pip", "install"]
+
+    if editable:
+        cmd.append("-e")
+
+    # Build package specifier
+    package_spec = "."
+    if extras:
+        package_spec = f".[{extras}]"
+    if dev:
+        if extras:
+            package_spec = f".[dev,{extras}]"
+        else:
+            package_spec = ".[dev]"
+
+    cmd.append(package_spec)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=300,
+            cwd=str(project_root),
+        )
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+
+        if result.returncode != 0:
+            emit_error(
+                "Installation failed",
+                code="INSTALL_FAILED",
+                error_type="internal",
+                remediation="Check the error output and ensure all dependencies are available",
+                details={
+                    "exit_code": result.returncode,
+                    "stderr": result.stderr[:500] if result.stderr else None,
+                },
+            )
+            return
+
+        emit_success(
+            {
+                "status": "installed",
+                "editable": editable,
+                "dev": dev,
+                "extras": extras,
+                "project_root": str(project_root),
+                "telemetry": {"duration_ms": round(duration_ms, 2)},
+            }
+        )
+
+    except subprocess.TimeoutExpired:
+        emit_error(
+            "Installation timed out",
+            code="TIMEOUT",
+            error_type="internal",
+            remediation="Try again with a faster network or fewer dependencies",
+            details={"timeout_seconds": 300},
+        )
+    except FileNotFoundError:
+        emit_error(
+            "pip not found",
+            code="PIP_NOT_FOUND",
+            error_type="internal",
+            remediation="Ensure pip is installed and in PATH",
+            details={"hint": "Ensure pip is installed and in PATH"},
+        )
+
+
+@dev_group.command("start")
+@click.option(
+    "--port",
+    type=int,
+    default=8000,
+    help="Port to run the development server on.",
+)
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    help="Host to bind the server to.",
+)
+@click.option(
+    "--reload/--no-reload",
+    default=True,
+    help="Enable auto-reload on file changes.",
+)
+@click.pass_context
+@cli_command("start")
+@handle_keyboard_interrupt()
+@with_sync_timeout(FAST_TIMEOUT, "Server check timed out")
+def dev_start_cmd(
+    ctx: click.Context,
+    port: int,
+    host: str,
+    reload: bool,
+) -> None:
+    """Start a development server.
+
+    Checks for common development server configurations and
+    provides instructions for starting.
+    """
+    start_time = time.perf_counter()
+    cli_ctx = get_context(ctx)
+
+    # Determine project root
+    project_root = cli_ctx.specs_dir.parent if cli_ctx.specs_dir else Path.cwd()
+
+    # Check for various server configurations
+    server_configs = []
+
+    # Check for uvicorn (FastAPI/Starlette)
+    try:
+        result = subprocess.run(
+            ["uvicorn", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            server_configs.append(
+                {
+                    "name": "uvicorn",
+                    "command": f"uvicorn main:app --host {host} --port {port}"
+                    + (" --reload" if reload else ""),
+                }
+            )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # Check for flask
+    try:
+        result = subprocess.run(
+            ["flask", "--version"],
+            capture_output=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            server_configs.append(
+                {
+                    "name": "flask",
+                    "command": f"flask run --host {host} --port {port}"
+                    + (" --reload" if reload else ""),
+                }
+            )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # Check for MCP server config
+    mcp_config = project_root / "mcp.json"
+    if mcp_config.exists():
+        server_configs.append(
+            {
+                "name": "mcp",
+                "command": f"python -m foundry_mcp.server --port {port}",
+            }
+        )
+
+    duration_ms = (time.perf_counter() - start_time) * 1000
+
+    emit_success(
+        {
+            "host": host,
+            "port": port,
+            "reload": reload,
+            "available_servers": server_configs,
+            "project_root": str(project_root),
+            "telemetry": {"duration_ms": round(duration_ms, 2)},
+        }
+    )
+
+
+@dev_group.command("check")
+@click.pass_context
+@cli_command("check")
+@handle_keyboard_interrupt()
+@with_sync_timeout(FAST_TIMEOUT, "Environment check timed out")
+def dev_check_cmd(ctx: click.Context) -> None:
+    """Check development environment status.
+
+    Verifies that all development tools are available.
+    """
+    start_time = time.perf_counter()
+    get_context(ctx)
+
+    tools = {}
+
+    # Check Python
+    try:
+        result = subprocess.run(
+            ["python", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        tools["python"] = {
+            "available": result.returncode == 0,
+            "version": result.stdout.strip() if result.returncode == 0 else None,
+        }
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        tools["python"] = {"available": False}
+
+    # Check pip
+    try:
+        result = subprocess.run(
+            ["pip", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        tools["pip"] = {
+            "available": result.returncode == 0,
+            "version": result.stdout.split()[1] if result.returncode == 0 else None,
+        }
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        tools["pip"] = {"available": False}
+
+    # Check git
+    try:
+        result = subprocess.run(
+            ["git", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        tools["git"] = {
+            "available": result.returncode == 0,
+            "version": result.stdout.strip() if result.returncode == 0 else None,
+        }
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        tools["git"] = {"available": False}
+
+    # Check node (optional)
+    try:
+        result = subprocess.run(
+            ["node", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        tools["node"] = {
+            "available": result.returncode == 0,
+            "version": result.stdout.strip() if result.returncode == 0 else None,
+        }
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        tools["node"] = {"available": False}
+
+    duration_ms = (time.perf_counter() - start_time) * 1000
+
+    all_required = all(
+        tools.get(t, {}).get("available", False) for t in ["python", "pip", "git"]
+    )
+
+    emit_success(
+        {
+            "tools": tools,
+            "all_required_available": all_required,
+            "telemetry": {"duration_ms": round(duration_ms, 2)},
+        }
+    )