foundry-mcp 0.8.22__py3-none-any.whl

foundry_mcp/cli/config.py

@@ -0,0 +1,98 @@
+"""CLI configuration and workspace detection.
+
+Provides configuration handling for the SDD CLI, leveraging the
+shared foundry_mcp.config module and core spec utilities.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from foundry_mcp.config import ServerConfig, get_config as get_server_config
+from foundry_mcp.core.spec import find_specs_directory
+
+
+class CLIContext:
+    """CLI execution context with resolved configuration.
+
+    Holds the effective configuration for a CLI command, including
+    any overrides from command-line options.
+    """
+
+    def __init__(
+        self,
+        specs_dir: Optional[str] = None,
+        server_config: Optional[ServerConfig] = None,
+    ):
+        """Initialize CLI context.
+
+        Args:
+            specs_dir: Explicit specs directory override from --specs-dir.
+            server_config: Optional server config (uses global if not provided).
+        """
+        self._specs_dir_override = specs_dir
+        self._config = server_config or get_server_config()
+        self._resolved_specs_dir: Optional[Path] = None
+
+    @property
+    def specs_dir(self) -> Optional[Path]:
+        """Get the resolved specs directory.
+
+        Resolution order:
+        1. CLI --specs-dir option (highest priority)
+        2. ServerConfig.specs_dir (from env/TOML)
+        3. Auto-detected via find_specs_directory()
+        """
+        if self._resolved_specs_dir is not None:
+            return self._resolved_specs_dir
+
+        # CLI override takes priority
+        if self._specs_dir_override:
+            self._resolved_specs_dir = Path(self._specs_dir_override).resolve()
+            return self._resolved_specs_dir
+
+        # Server config next
+        if self._config.specs_dir:
+            self._resolved_specs_dir = self._config.specs_dir.resolve()
+            return self._resolved_specs_dir
+
+        # Auto-detect
+        detected = find_specs_directory()
+        if detected:
+            self._resolved_specs_dir = detected
+            return self._resolved_specs_dir
+
+        return None
+
+    @property
+    def config(self) -> ServerConfig:
+        """Get the underlying server configuration."""
+        return self._config
+
+    def require_specs_dir(self) -> Path:
+        """Get specs directory, raising if not found.
+
+        Returns:
+            Resolved specs directory path.
+
+        Raises:
+            FileNotFoundError: If no specs directory could be resolved.
+        """
+        specs = self.specs_dir
+        if specs is None:
+            raise FileNotFoundError(
+                "No specs directory found. "
+                "Use --specs-dir or set SDD_SPECS_DIR environment variable."
+            )
+        return specs
+
+
+def create_context(specs_dir: Optional[str] = None) -> CLIContext:
+    """Create a CLI context with optional overrides.
+
+    Args:
+        specs_dir: Optional specs directory override.
+
+    Returns:
+        Configured CLIContext instance.
+    """
+    return CLIContext(specs_dir=specs_dir)

foundry_mcp/cli/context.py

@@ -0,0 +1,298 @@
+"""Context tracking for SDD CLI sessions.
+
+Provides session markers, consultation limits, and context window tracking
+for CLI-driven LLM workflows.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+import os
+import uuid
+
+
+@dataclass
+class SessionLimits:
+    """Configurable limits for a CLI session."""
+    max_consultations: int = 50  # Max LLM consultations per session
+    max_context_tokens: int = 100000  # Approximate token budget
+    warn_at_percentage: float = 0.8  # Warn at 80% usage
+
+
+@dataclass
+class SessionStats:
+    """Runtime statistics for a CLI session."""
+    consultation_count: int = 0
+    estimated_tokens_used: int = 0
+    commands_executed: int = 0
+    errors_encountered: int = 0
+    last_activity: Optional[str] = None
+
+
+@dataclass
+class AutonomousSession:
+    """
+    Ephemeral state for autonomous task execution mode.
+
+    This tracks whether the agent is running in autonomous mode where
+    it continues to the next task without explicit user confirmation.
+
+    NOTE: This state is EPHEMERAL - it exists only in memory and does
+    not persist across CLI restarts. Each new CLI session starts with
+    autonomous mode disabled.
+    """
+    enabled: bool = False
+    tasks_completed: int = 0
+    pause_reason: Optional[str] = None  # Why auto-mode paused: "limit", "error", "user", "context"
+    started_at: Optional[str] = None    # ISO timestamp when auto-mode was enabled
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON output."""
+        return {
+            "enabled": self.enabled,
+            "tasks_completed": self.tasks_completed,
+            "pause_reason": self.pause_reason,
+            "started_at": self.started_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AutonomousSession":
+        """Create from dictionary (for in-session use only)."""
+        return cls(
+            enabled=data.get("enabled", False),
+            tasks_completed=data.get("tasks_completed", 0),
+            pause_reason=data.get("pause_reason"),
+            started_at=data.get("started_at"),
+        )
+
+
+@dataclass
+class ContextSession:
+    """
+    Tracks a CLI session with limits and markers.
+
+    Used for:
+    - Session identification across CLI invocations
+    - Tracking consultation usage against limits
+    - Providing context budget information
+    """
+    session_id: str
+    started_at: str
+    limits: SessionLimits = field(default_factory=SessionLimits)
+    stats: SessionStats = field(default_factory=SessionStats)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    autonomous: Optional[AutonomousSession] = None
+
+    @property
+    def consultations_remaining(self) -> int:
+        """Number of consultations remaining."""
+        return max(0, self.limits.max_consultations - self.stats.consultation_count)
+
+    @property
+    def tokens_remaining(self) -> int:
+        """Estimated tokens remaining in budget."""
+        return max(0, self.limits.max_context_tokens - self.stats.estimated_tokens_used)
+
+    @property
+    def consultation_usage_percentage(self) -> float:
+        """Percentage of consultation limit used."""
+        if self.limits.max_consultations == 0:
+            return 0.0
+        return (self.stats.consultation_count / self.limits.max_consultations) * 100
+
+    @property
+    def token_usage_percentage(self) -> float:
+        """Percentage of token budget used."""
+        if self.limits.max_context_tokens == 0:
+            return 0.0
+        return (self.stats.estimated_tokens_used / self.limits.max_context_tokens) * 100
+
+    @property
+    def should_warn(self) -> bool:
+        """Whether to warn about approaching limits."""
+        return (
+            self.consultation_usage_percentage >= self.limits.warn_at_percentage * 100 or
+            self.token_usage_percentage >= self.limits.warn_at_percentage * 100
+        )
+
+    @property
+    def at_limit(self) -> bool:
+        """Whether session has reached its limits."""
+        return (
+            self.stats.consultation_count >= self.limits.max_consultations or
+            self.stats.estimated_tokens_used >= self.limits.max_context_tokens
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON output."""
+        return {
+            "session_id": self.session_id,
+            "started_at": self.started_at,
+            "limits": {
+                "max_consultations": self.limits.max_consultations,
+                "max_context_tokens": self.limits.max_context_tokens,
+                "warn_at_percentage": self.limits.warn_at_percentage,
+            },
+            "stats": {
+                "consultation_count": self.stats.consultation_count,
+                "estimated_tokens_used": self.stats.estimated_tokens_used,
+                "commands_executed": self.stats.commands_executed,
+                "errors_encountered": self.stats.errors_encountered,
+                "last_activity": self.stats.last_activity,
+            },
+            "derived": {
+                "consultations_remaining": self.consultations_remaining,
+                "tokens_remaining": self.tokens_remaining,
+                "consultation_usage_percentage": round(self.consultation_usage_percentage, 1),
+                "token_usage_percentage": round(self.token_usage_percentage, 1),
+                "should_warn": self.should_warn,
+                "at_limit": self.at_limit,
+            },
+            "metadata": self.metadata,
+            "autonomous": self.autonomous.to_dict() if self.autonomous else None,
+        }
+
+
+class ContextTracker:
+    """
+    Tracks CLI session context across command invocations.
+
+    Provides:
+    - Session markers for correlation
+    - Consultation counting and limits
+    - Context budget tracking
+    """
+
+    def __init__(self):
+        self._session: Optional[ContextSession] = None
+        self._load_from_env()
+
+    def _load_from_env(self) -> None:
+        """Load limits from environment variables."""
+        self._default_limits = SessionLimits(
+            max_consultations=int(os.environ.get("SDD_MAX_CONSULTATIONS", "50")),
+            max_context_tokens=int(os.environ.get("SDD_MAX_CONTEXT_TOKENS", "100000")),
+            warn_at_percentage=float(os.environ.get("SDD_WARN_PERCENTAGE", "0.8")),
+        )
+
+    def start_session(
+        self,
+        session_id: Optional[str] = None,
+        limits: Optional[SessionLimits] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> ContextSession:
+        """
+        Start a new tracking session.
+
+        Args:
+            session_id: Custom session ID (auto-generated if not provided)
+            limits: Custom limits (uses defaults if not provided)
+            metadata: Optional session metadata
+
+        Returns:
+            The created ContextSession
+        """
+        self._session = ContextSession(
+            session_id=session_id or self._generate_session_id(),
+            started_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            limits=limits or SessionLimits(
+                max_consultations=self._default_limits.max_consultations,
+                max_context_tokens=self._default_limits.max_context_tokens,
+                warn_at_percentage=self._default_limits.warn_at_percentage,
+            ),
+            metadata=metadata or {},
+        )
+        return self._session
+
+    def get_session(self) -> Optional[ContextSession]:
+        """Get the current session, if any."""
+        return self._session
+
+    def get_or_create_session(self) -> ContextSession:
+        """Get existing session or create a new one."""
+        if self._session is None:
+            return self.start_session()
+        return self._session
+
+    def record_consultation(self, estimated_tokens: int = 0) -> Dict[str, Any]:
+        """
+        Record an LLM consultation.
+
+        Args:
+            estimated_tokens: Estimated tokens used in this consultation
+
+        Returns:
+            Status dictionary with current usage info
+        """
+        session = self.get_or_create_session()
+        session.stats.consultation_count += 1
+        session.stats.estimated_tokens_used += estimated_tokens
+        session.stats.last_activity = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+        return {
+            "consultation_number": session.stats.consultation_count,
+            "consultations_remaining": session.consultations_remaining,
+            "tokens_used": estimated_tokens,
+            "tokens_remaining": session.tokens_remaining,
+            "should_warn": session.should_warn,
+            "at_limit": session.at_limit,
+        }
+
+    def record_command(self, error: bool = False) -> None:
+        """Record a CLI command execution."""
+        session = self.get_or_create_session()
+        session.stats.commands_executed += 1
+        if error:
+            session.stats.errors_encountered += 1
+        session.stats.last_activity = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+    def get_status(self) -> Dict[str, Any]:
+        """Get current session status."""
+        session = self._session
+        if session is None:
+            return {
+                "active": False,
+                "message": "No active session",
+            }
+        return {
+            "active": True,
+            **session.to_dict(),
+        }
+
+    def reset(self) -> None:
+        """Reset the current session."""
+        self._session = None
+
+    def _generate_session_id(self) -> str:
+        """Generate a unique session ID."""
+        return f"sdd_{uuid.uuid4().hex[:12]}"
+
+
+# Global context tracker
+_tracker: Optional[ContextTracker] = None
+
+
+def get_context_tracker() -> ContextTracker:
+    """Get the global context tracker."""
+    global _tracker
+    if _tracker is None:
+        _tracker = ContextTracker()
+    return _tracker
+
+
+def start_cli_session(
+    session_id: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> ContextSession:
+    """Start a new CLI session."""
+    return get_context_tracker().start_session(session_id=session_id, metadata=metadata)
+
+
+def get_session_status() -> Dict[str, Any]:
+    """Get current session status."""
+    return get_context_tracker().get_status()
+
+
+def record_consultation(estimated_tokens: int = 0) -> Dict[str, Any]:
+    """Record an LLM consultation."""
+    return get_context_tracker().record_consultation(estimated_tokens)

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()