foundry-mcp 0.3.3__py3-none-any.whl

foundry_mcp/cli/logging.py

@@ -0,0 +1,212 @@
+"""Structured logging hooks for CLI commands.
+
+Provides context ID generation, metrics emission, and structured
+logging for CLI command execution. Wraps core observability primitives
+for CLI-specific use cases.
+"""
+
+import logging
+import time
+import uuid
+from contextvars import ContextVar
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar
+
+from foundry_mcp.core.observability import (
+    get_metrics,
+    redact_sensitive_data,
+)
+
+__all__ = [
+    "get_request_id",
+    "set_request_id",
+    "cli_command",
+    "get_cli_logger",
+    "CLILogContext",
+]
+
+T = TypeVar("T")
+
+# Context variable for request/correlation ID
+_request_id: ContextVar[str] = ContextVar("request_id", default="")
+
+
+def generate_request_id() -> str:
+    """Generate a unique request ID for CLI command tracking.
+
+    Returns:
+        Short UUID suitable for log correlation.
+    """
+    return f"cli_{uuid.uuid4().hex[:12]}"
+
+
+def get_request_id() -> str:
+    """Get the current request ID for this execution context.
+
+    Returns:
+        The request ID, or empty string if not set.
+    """
+    return _request_id.get()
+
+
+def set_request_id(request_id: str) -> None:
+    """Set the request ID for this execution context.
+
+    Args:
+        request_id: The request ID to set.
+    """
+    _request_id.set(request_id)
+
+
+class CLILogContext:
+    """Context manager for CLI command logging context.
+
+    Automatically generates and sets a request ID for the duration
+    of the context, enabling log correlation.
+
+    Example:
+        >>> with CLILogContext() as ctx:
+        ...     logger.info("Processing", extra={"request_id": ctx.request_id})
+    """
+
+    def __init__(self, request_id: Optional[str] = None):
+        """Initialize logging context.
+
+        Args:
+            request_id: Optional custom request ID (auto-generated if None).
+        """
+        self.request_id = request_id or generate_request_id()
+        self._token = None
+
+    def __enter__(self) -> "CLILogContext":
+        self._token = _request_id.set(self.request_id)
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if self._token is not None:
+            _request_id.reset(self._token)
+
+
+class CLILogger:
+    """Structured logger for CLI commands.
+
+    Provides JSON-formatted logging with automatic request ID inclusion
+    and sensitive data redaction.
+    """
+
+    def __init__(self, name: str = "foundry_mcp.cli"):
+        self._logger = logging.getLogger(name)
+
+    def _log(
+        self,
+        level: int,
+        message: str,
+        **extra: Any,
+    ) -> None:
+        """Log with structured context."""
+        request_id = get_request_id()
+        context = {
+            "request_id": request_id,
+            **redact_sensitive_data(extra),
+        }
+        self._logger.log(level, message, extra={"cli_context": context})
+
+    def debug(self, message: str, **extra: Any) -> None:
+        """Log debug message."""
+        self._log(logging.DEBUG, message, **extra)
+
+    def info(self, message: str, **extra: Any) -> None:
+        """Log info message."""
+        self._log(logging.INFO, message, **extra)
+
+    def warning(self, message: str, **extra: Any) -> None:
+        """Log warning message."""
+        self._log(logging.WARNING, message, **extra)
+
+    def error(self, message: str, **extra: Any) -> None:
+        """Log error message."""
+        self._log(logging.ERROR, message, **extra)
+
+
+# Global CLI logger
+_cli_logger = CLILogger()
+
+
+def get_cli_logger() -> CLILogger:
+    """Get the global CLI logger."""
+    return _cli_logger
+
+
+def cli_command(
+    command_name: Optional[str] = None,
+    emit_metrics: bool = True,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator for CLI commands with observability.
+
+    Automatically:
+    - Generates request ID for correlation
+    - Logs command start/end
+    - Emits latency and status metrics
+
+    Args:
+        command_name: Override command name (defaults to function name).
+        emit_metrics: Whether to emit metrics (default: True).
+
+    Returns:
+        Decorated function with observability.
+
+    Example:
+        >>> @cli_command("fetch-spec")
+        ... def fetch_spec(spec_id: str):
+        ...     return load_spec(spec_id)
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        name = command_name or func.__name__
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            with CLILogContext():
+                metrics = get_metrics()
+                start = time.perf_counter()
+                success = True
+                error_msg = None
+
+                _cli_logger.debug(
+                    f"CLI command started: {name}",
+                    command=name,
+                )
+
+                try:
+                    result = func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    success = False
+                    error_msg = str(e)
+                    raise
+                finally:
+                    duration_ms = (time.perf_counter() - start) * 1000
+
+                    _cli_logger.debug(
+                        f"CLI command completed: {name}",
+                        command=name,
+                        success=success,
+                        duration_ms=round(duration_ms, 2),
+                        error=error_msg,
+                    )
+
+                    if emit_metrics:
+                        labels = {
+                            "command": name,
+                            "status": "success" if success else "error",
+                        }
+                        metrics.counter("cli.command.invocations", labels=labels)
+                        metrics.timer(
+                            "cli.command.latency",
+                            duration_ms,
+                            labels={"command": name},
+                        )
+
+        return wrapper
+
+    return decorator

foundry_mcp/cli/main.py

@@ -0,0 +1,44 @@
+"""SDD CLI entry point.
+
+JSON-first output for AI coding assistants.
+
+The current CLI emits response-v2 JSON envelopes by default; `--json` is
+accepted as an explicit compatibility flag.
+"""
+
+import click
+
+from foundry_mcp.cli.config import create_context
+from foundry_mcp.cli.registry import register_all_commands
+
+
+@click.group()
+@click.option(
+    "--specs-dir",
+    envvar="SDD_SPECS_DIR",
+    type=click.Path(exists=False),
+    help="Override specs directory path",
+)
+@click.option(
+    "--json",
+    "json_output",
+    is_flag=True,
+    help="Emit JSON response envelopes (default behavior).",
+)
+@click.pass_context
+def cli(ctx: click.Context, specs_dir: str | None, json_output: bool) -> None:
+    """SDD CLI - Spec-Driven Development for AI assistants.
+
+    All commands output JSON for reliable parsing by AI coding tools.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["cli_context"] = create_context(specs_dir=specs_dir)
+    ctx.obj["json_output_requested"] = bool(json_output)
+
+
+# Register all command groups
+register_all_commands(cli)
+
+
+if __name__ == "__main__":
+    cli()

foundry_mcp/cli/output.py

@@ -0,0 +1,122 @@
+"""JSON output helpers for SDD CLI.
+
+This module provides the sole output mechanism for the CLI.
+The CLI is JSON-first and currently emits JSON envelopes only.
+
+Design rationale:
+- Primary consumers are AI coding assistants (Claude, Cursor, etc.)
+- AI agents parse structured data best - no regex/pattern matching needed
+- Consistent output format = reliable integration
+- Humans can pipe through `jq` if needed
+
+This module wraps the canonical response helpers from foundry_mcp.core.responses
+to ensure CLI output matches the response-v2 schema used by MCP tools.
+"""
+
+import json
+import sys
+from dataclasses import asdict
+from typing import Any, Mapping, Sequence, NoReturn
+
+from foundry_mcp.cli.logging import generate_request_id, get_request_id, set_request_id
+from foundry_mcp.core.responses import error_response, success_response
+
+
+def _ensure_request_id() -> str:
+    request_id = get_request_id()
+    if request_id:
+        return request_id
+    request_id = generate_request_id()
+    set_request_id(request_id)
+    return request_id
+
+
+def emit(data: Any) -> None:
+    """Emit JSON to stdout.
+
+    This is the single output function for all CLI commands.
+    Data is serialized with indent=2 for readability when debugging.
+
+    Args:
+        data: Any JSON-serializable data structure.
+    """
+    print(json.dumps(data, indent=2, default=str))
+
+
+def emit_error(
+    message: str,
+    code: str = "INTERNAL_ERROR",
+    *,
+    error_type: str = "internal",
+    remediation: str | None = None,
+    details: Mapping[str, Any] | None = None,
+) -> NoReturn:
+    """Emit error JSON to stderr and exit with code 1.
+
+    Uses foundry_mcp.core.responses.error_response to ensure response-v2 compliance.
+    Error info is structured in the `data` field with `error_code`, `error_type`,
+    and `remediation` fields. The `error` field contains the human-readable message.
+
+    Args:
+        message: Human-readable error description.
+        code: Error code in SCREAMING_SNAKE_CASE (e.g., VALIDATION_ERROR, NOT_FOUND).
+        error_type: Error category for routing (validation, not_found, internal, etc.).
+        remediation: Actionable guidance for resolving the error.
+        details: Optional additional error context.
+
+    Raises:
+        SystemExit: Always exits with code 1.
+    """
+    response = error_response(
+        message=message,
+        error_code=code,
+        error_type=error_type,
+        remediation=remediation,
+        details=details,
+        request_id=_ensure_request_id(),
+    )
+    print(json.dumps(asdict(response), indent=2, default=str), file=sys.stderr)
+    sys.exit(1)
+
+
+def emit_success(
+    data: Any,
+    *,
+    warnings: Sequence[str] | None = None,
+    pagination: Mapping[str, Any] | None = None,
+    telemetry: Mapping[str, Any] | None = None,
+    meta: Mapping[str, Any] | None = None,
+) -> None:
+    """Emit success response envelope to stdout.
+
+    Uses foundry_mcp.core.responses.success_response to ensure response-v2 compliance.
+    All responses include meta.version: "response-v2".
+
+    Args:
+        data: The operation-specific payload.
+        warnings: Non-fatal issues to surface in meta.warnings.
+        pagination: Cursor metadata for list results.
+        telemetry: Timing/performance metadata.
+        meta: Additional metadata to merge into meta object.
+    """
+    # Handle both dict and non-dict data
+    if isinstance(data, dict):
+        response = success_response(
+            data=data,
+            warnings=warnings,
+            pagination=pagination,
+            telemetry=telemetry,
+            meta=meta,
+            request_id=_ensure_request_id(),
+        )
+    else:
+        # Wrap non-dict data in a result key
+        response = success_response(
+            data={"result": data},
+            warnings=warnings,
+            pagination=pagination,
+            telemetry=telemetry,
+            meta=meta,
+            request_id=_ensure_request_id(),
+        )
+    emit(asdict(response))

foundry_mcp/cli/registry.py

@@ -0,0 +1,110 @@
+"""Command registry for SDD CLI.
+
+Centralized registration of all command groups.
+Commands are organized by domain (specs, tasks, journal, etc.).
+"""
+
+from typing import Optional
+
+import click
+
+from foundry_mcp.cli.config import CLIContext
+
+# Module-level storage for CLI context (for testing)
+_cli_context: Optional[CLIContext] = None
+
+
+def set_context(ctx: CLIContext) -> None:
+    """Set the CLI context at module level.
+
+    Primarily used for testing when not using Click's context.
+
+    Args:
+        ctx: The CLIContext to store.
+    """
+    global _cli_context
+    _cli_context = ctx
+
+
+def get_context(ctx: Optional[click.Context] = None) -> CLIContext:
+    """Get CLI context from Click context or module-level storage.
+
+    Args:
+        ctx: Optional Click context with cli_context stored in obj.
+             If None, returns module-level context.
+
+    Returns:
+        The CLIContext instance.
+
+    Raises:
+        RuntimeError: If no context is available.
+    """
+    if ctx is not None:
+        return ctx.obj["cli_context"]
+
+    if _cli_context is not None:
+        return _cli_context
+
+    raise RuntimeError("No CLI context available. Call set_context() first.")
+
+
+def register_all_commands(cli: click.Group) -> None:
+    """Register all command groups with the CLI.
+
+    Command groups are lazily imported to avoid circular dependencies
+    and improve startup time.
+
+    Args:
+        cli: The main Click group to register commands with.
+    """
+    # Import and register command groups
+    from foundry_mcp.cli.commands import (
+        cache,
+        dashboard_group,
+        dev_group,
+        journal,
+        lifecycle,
+        modify_group,
+        plan_group,
+        pr_group,
+        review_group,
+        session,
+        specs,
+        tasks,
+        test_group,
+        validate_group,
+    )
+
+    cli.add_command(specs)
+    cli.add_command(tasks)
+    cli.add_command(lifecycle)
+    cli.add_command(session)
+    cli.add_command(cache)
+    cli.add_command(journal)
+    cli.add_command(validate_group)
+    cli.add_command(review_group)
+    cli.add_command(pr_group)
+    cli.add_command(modify_group)
+    cli.add_command(test_group)
+    cli.add_command(dev_group)
+    cli.add_command(dashboard_group)
+    cli.add_command(plan_group)
+
+    # Placeholder: version command for testing the scaffold
+    @cli.command("version")
+    @click.pass_context
+    def version(ctx: click.Context) -> None:
+        """Show CLI version information."""
+        from foundry_mcp.cli.output import emit
+
+        cli_ctx = get_context(ctx)
+        specs_dir = cli_ctx.specs_dir
+
+        emit(
+            {
+                "version": "0.1.0",
+                "name": "foundry-cli",
+                "json_only": True,
+                "specs_dir": str(specs_dir) if specs_dir else None,
+            }
+        )

foundry_mcp/cli/resilience.py

@@ -0,0 +1,178 @@
+"""CLI resilience wrappers for timeout and cancellation.
+
+Provides synchronous timeout and retry decorators for CLI commands,
+wrapping the core resilience primitives from foundry_mcp.core.resilience.
+"""
+
+import signal
+import sys
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar
+
+from foundry_mcp.core.resilience import (
+    FAST_TIMEOUT,
+    MEDIUM_TIMEOUT,
+    SLOW_TIMEOUT,
+    BACKGROUND_TIMEOUT,
+    TimeoutException,
+    retry_with_backoff,
+)
+
+# Re-export constants for CLI usage
+__all__ = [
+    "FAST_TIMEOUT",
+    "MEDIUM_TIMEOUT",
+    "SLOW_TIMEOUT",
+    "BACKGROUND_TIMEOUT",
+    "TimeoutException",
+    "with_sync_timeout",
+    "cli_retryable",
+    "handle_keyboard_interrupt",
+]
+
+T = TypeVar("T")
+
+
+class _TimeoutHandler:
+    """Context manager for signal-based timeout on Unix systems."""
+
+    def __init__(self, seconds: float, error_message: str):
+        self.seconds = int(seconds)  # signal.alarm requires int
+        self.error_message = error_message
+        self._old_handler = None
+
+    def _timeout_handler(self, signum: int, frame: Any) -> None:
+        raise TimeoutException(
+            self.error_message,
+            timeout_seconds=float(self.seconds),
+            operation="cli_command",
+        )
+
+    def __enter__(self) -> "_TimeoutHandler":
+        if sys.platform != "win32":
+            self._old_handler = signal.signal(signal.SIGALRM, self._timeout_handler)
+            signal.alarm(self.seconds)
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if sys.platform != "win32":
+            signal.alarm(0)
+            if self._old_handler is not None:
+                signal.signal(signal.SIGALRM, self._old_handler)
+
+
+def with_sync_timeout(
+    seconds: float = MEDIUM_TIMEOUT,
+    error_message: Optional[str] = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator to add timeout to synchronous CLI commands.
+
+    Uses signal.SIGALRM on Unix systems. On Windows, timeout is not
+    enforced (function runs without timeout).
+
+    Args:
+        seconds: Timeout duration in seconds (default: MEDIUM_TIMEOUT).
+        error_message: Custom error message on timeout.
+
+    Returns:
+        Decorated function with timeout enforcement.
+
+    Example:
+        >>> @with_sync_timeout(FAST_TIMEOUT, "Query timed out")
+        ... def fetch_data():
+        ...     return expensive_operation()
+
+    Note:
+        This uses SIGALRM which only works on Unix. Windows has no
+        signal-based timeout mechanism for synchronous code.
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            msg = error_message or f"{func.__name__} timed out after {seconds}s"
+
+            if sys.platform == "win32":
+                # Windows: run without timeout (signal.alarm not available)
+                return func(*args, **kwargs)
+
+            with _TimeoutHandler(seconds, msg):
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def cli_retryable(
+    max_retries: int = 3,
+    delay: float = 1.0,
+    exceptions: tuple[type[Exception], ...] = (Exception,),
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator for automatic retries with exponential backoff.
+
+    Wraps core retry_with_backoff for CLI command usage.
+
+    Args:
+        max_retries: Maximum retry attempts (default 3).
+        delay: Base delay in seconds (default 1.0).
+        exceptions: Tuple of exceptions to retry on.
+
+    Returns:
+        Decorated function with retry logic.
+
+    Example:
+        >>> @cli_retryable(max_retries=3, exceptions=(IOError,))
+        ... def read_spec_file(path):
+        ...     return load_json(path)
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            return retry_with_backoff(
+                lambda: func(*args, **kwargs),
+                max_retries=max_retries,
+                base_delay=delay,
+                retryable_exceptions=list(exceptions),
+            )
+
+        return wrapper
+
+    return decorator
+
+
+def handle_keyboard_interrupt(
+    cleanup: Optional[Callable[[], None]] = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator to gracefully handle Ctrl+C in CLI commands.
+
+    Catches KeyboardInterrupt, optionally runs cleanup, and exits
+    with appropriate code.
+
+    Args:
+        cleanup: Optional cleanup function to run on interrupt.
+
+    Returns:
+        Decorated function with interrupt handling.
+
+    Example:
+        >>> @handle_keyboard_interrupt(cleanup=lambda: print("Cancelled"))
+        ... def long_running_task():
+        ...     # ... work ...
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            try:
+                return func(*args, **kwargs)
+            except KeyboardInterrupt:
+                if cleanup:
+                    cleanup()
+                # Exit with 130 (128 + SIGINT signal number 2)
+                sys.exit(130)
+
+        return wrapper
+
+    return decorator