foundry-mcp 0.8.22__py3-none-any.whl

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 in minified format for smaller payloads.
+
+    Args:
+        data: Any JSON-serializable data structure.
+    """
+    print(json.dumps(data, separators=(",", ":"), 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), separators=(",", ":"), 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

foundry_mcp/cli/transcript.py

@@ -0,0 +1,217 @@
+"""Parse Claude Code transcript files to extract token usage metrics.
+
+Ported from claude-sdd-toolkit context_tracker module.
+"""
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Sequence
+
+
+@dataclass
+class TokenMetrics:
+    """Token usage metrics extracted from a transcript."""
+
+    input_tokens: int
+    output_tokens: int
+    cached_tokens: int
+    total_tokens: int
+    context_length: int
+
+    def context_percentage(self, max_context: int = 155000) -> float:
+        """Calculate context usage percentage."""
+        return (self.context_length / max_context) * 100 if max_context > 0 else 0.0
+
+
+def is_clear_command(entry: dict) -> bool:
+    """
+    Check if a transcript entry is a /clear command.
+
+    The /clear command resets the conversation context, so we should
+    reset token counters when we encounter it.
+
+    Args:
+        entry: A parsed JSONL entry from the transcript
+
+    Returns:
+        True if this entry represents a /clear command
+    """
+    if entry.get("type") != "user":
+        return False
+
+    message = entry.get("message", {})
+    content = message.get("content", "")
+
+    # Handle both string content and list content
+    if isinstance(content, str):
+        return "<command-name>/clear</command-name>" in content
+
+    if isinstance(content, list):
+        for item in content:
+            if isinstance(item, dict):
+                text = item.get("text", "")
+                if "<command-name>/clear</command-name>" in text:
+                    return True
+
+    return False
+
+
+def parse_transcript(transcript_path: str | Path) -> Optional[TokenMetrics]:
+    """
+    Parse a Claude Code transcript JSONL file and extract token metrics.
+
+    Args:
+        transcript_path: Path to the transcript JSONL file
+
+    Returns:
+        TokenMetrics object with aggregated token data, or None if parsing fails
+    """
+    transcript_path = Path(transcript_path)
+
+    if not transcript_path.exists():
+        return None
+
+    input_tokens = 0
+    output_tokens = 0
+    cached_tokens = 0
+    context_length = 0
+
+    try:
+        with open(transcript_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                # Check for /clear command - reset all counters
+                if is_clear_command(entry):
+                    input_tokens = 0
+                    output_tokens = 0
+                    cached_tokens = 0
+                    context_length = 0
+                    continue  # Don't process /clear entry itself
+
+                # Skip sidechain and error messages
+                if entry.get("isSidechain") or entry.get("isApiErrorMessage"):
+                    continue
+
+                # Extract usage data
+                message = entry.get("message", {})
+                usage = message.get("usage", {})
+
+                if usage:
+                    # Accumulate token counts
+                    input_tokens += usage.get("input_tokens", 0)
+                    output_tokens += usage.get("output_tokens", 0)
+
+                    # Cached tokens come from both read and creation
+                    cache_read = usage.get("cache_read_input_tokens", 0)
+                    cache_creation = usage.get("cache_creation_input_tokens", 0)
+                    cached_tokens += cache_read + cache_creation
+
+                    # Context length is from the most recent valid entry
+                    # (input tokens + cached tokens, excluding output)
+                    context_length = (
+                        usage.get("input_tokens", 0)
+                        + usage.get("cache_read_input_tokens", 0)
+                        + usage.get("cache_creation_input_tokens", 0)
+                    )
+
+    except Exception:
+        return None
+
+    total_tokens = input_tokens + output_tokens + cached_tokens
+
+    return TokenMetrics(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_tokens=cached_tokens,
+        total_tokens=total_tokens,
+        context_length=context_length,
+    )
+
+
+def find_transcript_by_marker(
+    cwd: Path,
+    marker: str,
+    max_retries: int = 10,
+    search_dirs: Optional[Sequence[Path]] = None,
+    allow_home_search: bool = False,
+) -> Optional[Path]:
+    """
+    Search transcripts for a specific SESSION_MARKER to identify current session.
+
+    Args:
+        cwd: Current working directory (used to derive default project path)
+        marker: Specific marker to search for (e.g., "SESSION_MARKER_abc12345")
+        max_retries: Maximum number of retry attempts (default: 10)
+        search_dirs: Explicit directories to search (takes precedence over defaults)
+        allow_home_search: Whether to scan ~/.claude/projects derived paths
+
+    Returns:
+        Path to transcript containing the marker, or None if not found
+    """
+    candidate_dirs: list[Path] = []
+
+    if search_dirs:
+        for directory in search_dirs:
+            resolved = Path(directory).expanduser().resolve()
+            if resolved.is_dir() and resolved not in candidate_dirs:
+                candidate_dirs.append(resolved)
+
+    if allow_home_search:
+        current_path = cwd.resolve()
+        while True:
+            project_dir_name = str(current_path).replace("/", "-").replace("_", "-")
+            transcript_dir = Path.home() / ".claude" / "projects" / project_dir_name
+            if transcript_dir.exists() and transcript_dir not in candidate_dirs:
+                candidate_dirs.append(transcript_dir)
+
+            if current_path.parent == current_path or len(candidate_dirs) >= 5:
+                break
+            current_path = current_path.parent
+
+    if not candidate_dirs:
+        return None
+
+    delays = [min(0.1 * (2**i), 10.0) for i in range(max_retries)]
+
+    for attempt in range(max_retries):
+        current_time = time.time()
+
+        for transcript_dir in candidate_dirs:
+            try:
+                transcript_files = []
+                for transcript_path in transcript_dir.glob("*.jsonl"):
+                    try:
+                        mtime = transcript_path.stat().st_mtime
+                        if (current_time - mtime) > 86400:
+                            continue
+                        transcript_files.append((transcript_path, mtime))
+                    except (OSError, IOError):
+                        continue
+
+                transcript_files.sort(key=lambda x: x[1], reverse=True)
+
+                for transcript_path, _ in transcript_files:
+                    try:
+                        with open(transcript_path, "r", encoding="utf-8") as f:
+                            for line in f:
+                                if marker in line:
+                                    return transcript_path
+                    except (OSError, IOError, UnicodeDecodeError):
+                        continue
+            except (OSError, IOError):
+                continue
+
+        if attempt < max_retries - 1:
+            time.sleep(delays[attempt])
+
+    return None