foundry-mcp 0.3.3__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,259 @@
+"""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 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)
+
+    @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,
+        }
+
+
+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/flags.py

@@ -0,0 +1,266 @@
+"""CLI feature flag bootstrap bridging CLI options and discovery manifest.
+
+Provides CLI-specific flag management that wraps the core feature flag
+infrastructure, enabling runtime flag overrides via CLI options and
+exposing flag status for tool discovery.
+
+See docs/mcp_best_practices/14-feature-flags.md for guidance.
+"""
+
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+import click
+
+from foundry_mcp.core.feature_flags import (
+    FeatureFlag,
+    FeatureFlagRegistry,
+    FlagState,
+    get_registry,
+)
+
+__all__ = [
+    "CLIFlagRegistry",
+    "get_cli_flags",
+    "apply_cli_flag_overrides",
+    "flags_for_discovery",
+    "with_flag_options",
+]
+
+T = TypeVar("T")
+
+
+class CLIFlagRegistry:
+    """Registry of CLI-specific feature flags.
+
+    Wraps the core FeatureFlagRegistry and provides CLI-specific
+    functionality like mapping command-line options to flag overrides
+    and generating discovery manifests.
+
+    Example:
+        >>> registry = CLIFlagRegistry()
+        >>> registry.register_cli_flag(
+        ...     name="experimental_commands",
+        ...     description="Enable experimental CLI commands",
+        ...     default_enabled=False,
+        ...     state=FlagState.BETA,
+        ... )
+        >>> registry.is_enabled("experimental_commands")
+        False
+    """
+
+    def __init__(self, core_registry: Optional[FeatureFlagRegistry] = None):
+        """Initialize with optional core registry.
+
+        Args:
+            core_registry: Core feature flag registry. Uses global if None.
+        """
+        self._core = core_registry or get_registry()
+        self._cli_flags: Dict[str, FeatureFlag] = {}
+
+    def register_cli_flag(
+        self,
+        name: str,
+        description: str,
+        default_enabled: bool = False,
+        state: FlagState = FlagState.BETA,
+        **kwargs: Any,
+    ) -> None:
+        """Register a CLI-specific feature flag.
+
+        Creates a flag in both the CLI registry and the core registry
+        for unified evaluation.
+
+        Args:
+            name: Unique flag identifier (e.g., "experimental_commands").
+            description: Human-readable description for discovery.
+            default_enabled: Whether enabled by default.
+            state: Flag lifecycle state.
+            **kwargs: Additional FeatureFlag parameters.
+        """
+        flag = FeatureFlag(
+            name=name,
+            description=description,
+            default_enabled=default_enabled,
+            state=state,
+            **kwargs,
+        )
+        self._cli_flags[name] = flag
+        try:
+            self._core.register(flag)
+        except ValueError:
+            # Flag already registered in core, update our local copy
+            existing = self._core.get(name)
+            if existing:
+                self._cli_flags[name] = existing
+
+    def is_enabled(self, flag_name: str, default: bool = False) -> bool:
+        """Check if a CLI flag is enabled.
+
+        Args:
+            flag_name: Name of the flag to check.
+            default: Value if flag doesn't exist.
+
+        Returns:
+            True if flag is enabled, False otherwise.
+        """
+        return self._core.is_enabled(flag_name, client_id="cli", default=default)
+
+    def apply_overrides(self, overrides: Dict[str, bool]) -> None:
+        """Apply multiple flag overrides.
+
+        Used to translate CLI options into flag state. Overrides
+        persist for the duration of the CLI command execution.
+
+        Args:
+            overrides: Mapping of flag names to enabled/disabled state.
+        """
+        for flag_name, enabled in overrides.items():
+            self._core.set_override("cli", flag_name, enabled)
+
+    def clear_overrides(self) -> None:
+        """Clear all CLI-applied overrides."""
+        self._core.clear_all_overrides("cli")
+
+    def get_discovery_manifest(self) -> Dict[str, Dict[str, Any]]:
+        """Generate discovery manifest for CLI flags.
+
+        Returns flag information suitable for tool discovery responses,
+        allowing AI coding assistants to understand available features.
+
+        Returns:
+            Dictionary with flag names as keys and info dicts as values.
+        """
+        manifest = {}
+        for name, flag in self._cli_flags.items():
+            manifest[name] = {
+                "enabled": self.is_enabled(name),
+                "state": flag.state.value,
+                "description": flag.description,
+                "default": flag.default_enabled,
+            }
+            if flag.state == FlagState.DEPRECATED and flag.expires_at:
+                manifest[name]["expires"] = flag.expires_at.isoformat()
+        return manifest
+
+    def list_flags(self) -> List[str]:
+        """List all registered CLI flag names."""
+        return list(self._cli_flags.keys())
+
+
+# Global CLI flag registry
+_cli_registry: Optional[CLIFlagRegistry] = None
+
+
+def get_cli_flags() -> CLIFlagRegistry:
+    """Get the global CLI flag registry."""
+    global _cli_registry
+    if _cli_registry is None:
+        _cli_registry = CLIFlagRegistry()
+    return _cli_registry
+
+
+def apply_cli_flag_overrides(
+    enable: Optional[List[str]] = None,
+    disable: Optional[List[str]] = None,
+) -> None:
+    """Apply flag overrides from CLI options.
+
+    Translates --enable-feature and --disable-feature CLI options
+    into feature flag overrides.
+
+    Args:
+        enable: List of flag names to enable.
+        disable: List of flag names to disable.
+    """
+    registry = get_cli_flags()
+    overrides: Dict[str, bool] = {}
+
+    if enable:
+        for flag_name in enable:
+            overrides[flag_name] = True
+
+    if disable:
+        for flag_name in disable:
+            overrides[flag_name] = False
+
+    if overrides:
+        registry.apply_overrides(overrides)
+
+
+def flags_for_discovery() -> Dict[str, Any]:
+    """Get flag status for inclusion in discovery responses.
+
+    Returns:
+        Dictionary suitable for JSON serialization in discovery manifest.
+    """
+    return get_cli_flags().get_discovery_manifest()
+
+
+def with_flag_options(
+    func: Optional[Callable[..., T]] = None,
+) -> Callable[..., T]:
+    """Click decorator that adds --enable-feature/--disable-feature options.
+
+    Adds common flag override options to a Click command and applies
+    them before command execution.
+
+    Example:
+        >>> @cli.command()
+        ... @with_flag_options
+        ... def my_command():
+        ...     # flags are already applied
+        ...     if get_cli_flags().is_enabled("experimental"):
+        ...         do_experimental_thing()
+
+    Args:
+        func: The Click command function to wrap.
+
+    Returns:
+        Decorated function with flag options.
+    """
+
+    def decorator(f: Callable[..., T]) -> Callable[..., T]:
+        # Add the Click options
+        f = click.option(
+            "--enable-feature",
+            "enable_features",
+            multiple=True,
+            help="Enable feature flag(s) for this command.",
+        )(f)
+        f = click.option(
+            "--disable-feature",
+            "disable_features",
+            multiple=True,
+            help="Disable feature flag(s) for this command.",
+        )(f)
+
+        # Wrap to apply flags before execution
+        original = f
+
+        @click.pass_context
+        def wrapper(ctx: click.Context, *args: Any, **kwargs: Any) -> T:
+            enable = kwargs.pop("enable_features", ())
+            disable = kwargs.pop("disable_features", ())
+
+            apply_cli_flag_overrides(
+                enable=list(enable) if enable else None,
+                disable=list(disable) if disable else None,
+            )
+
+            try:
+                # Call original with remaining kwargs
+                return ctx.invoke(original, *args, **kwargs)
+            finally:
+                # Clean up overrides after command
+                get_cli_flags().clear_overrides()
+
+        # Preserve function metadata
+        wrapper.__name__ = f.__name__
+        wrapper.__doc__ = f.__doc__
+
+        return wrapper  # type: ignore[return-value]
+
+    if func is not None:
+        return decorator(func)
+
+    return decorator  # type: ignore[return-value]