ref-agents 1.0.0__py3-none-any.whl

ref_agents/__init__.py

@@ -0,0 +1,9 @@
+"""REF Agents - AI-Powered SDLC Guidance Layer.
+
+Built on Anthropic's Model Context Protocol (MCP) for seamless AI assistant
+integration. Provides agent-based prompts, workflow management, and quality tools.
+
+Usage:
+    from ref_agents.server import mcp
+    mcp.run()
+"""

ref_agents/api_keys.json.example

@@ -0,0 +1,8 @@
+{
+  "_comment": "API keys for REF-Agents MCP server. Add keys here to grant access.",
+  "sk-ref-example-key-1": {
+    "user": "admin@example.com",
+    "created": "2026-01-17",
+    "scopes": ["mcp:access"]
+  }
+}

ref_agents/auth.py

@@ -0,0 +1,129 @@
+"""Authentication module for REF-Agents MCP server.
+
+Provides API key validation using FastMCP's DebugTokenVerifier.
+Keys loaded from environment variable (cloud) or JSON file (local).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import structlog
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+logger = structlog.get_logger(__name__)
+
+# Environment variable for cloud deployment
+ENV_VAR_NAME = "REF_API_KEYS"
+# Default path for local API keys file
+DEFAULT_KEYS_PATH = Path(__file__).parent / "api_keys.json"
+
+
+def load_api_keys(keys_path: Path | None = None) -> set[str]:
+    """Load API keys from environment variable or JSON file.
+
+    Priority:
+    1. REF_API_KEYS env var (comma-separated keys for cloud)
+    2. JSON file (for local development) - ONLY if REF_ENABLE_AUTH is set.
+
+    Args:
+        keys_path: Path to JSON file. Defaults to api_keys.json in module dir.
+
+    Returns:
+        Set of valid API key strings.
+        Empty set if no keys configured (Open Mode).
+    """
+    # Priority 1: Environment variable (cloud deployment)
+    env_keys = os.environ.get(ENV_VAR_NAME)
+    if env_keys and env_keys.strip():
+        # Support comma-separated keys: "key1,key2,key3"
+        keys = {k.strip() for k in env_keys.split(",") if k.strip()}
+        if keys:
+            logger.info("api_keys_loaded_from_env", count=len(keys))
+            return keys
+        # Empty env var or no valid keys → Open Mode
+        logger.info("auth_open_mode", reason="REF_API_KEYS_empty_or_invalid")
+
+    # Priority 2: JSON file (local development)
+    # Only load from file if explicitly enabled via environment variable
+    enable_auth = os.environ.get("REF_ENABLE_AUTH", "").lower() in ("true", "1", "yes")
+
+    # If not cloud (Priority 1) and not explicitly enabled, return empty (Open Mode)
+    if not enable_auth:
+        logger.info("auth_open_mode", reason="REF_ENABLE_AUTH_not_set")
+        return set()
+
+    path = keys_path or DEFAULT_KEYS_PATH
+    if not path.exists():
+        logger.debug("api_keys_file_missing", path=str(path))
+        return set()
+
+    try:
+        content = path.read_text(encoding="utf-8")
+        data = json.loads(content)
+        # Support both formats:
+        # Simple list: ["key1", "key2"]
+        # Dict with metadata: {"key1": {...}, "key2": {...}}
+        if isinstance(data, list):
+            keys = set(data)
+        else:
+            keys = set(data.keys())
+        # Filter out comment keys
+        keys = {k for k in keys if not k.startswith("_")}
+        logger.info("api_keys_loaded_from_file", count=len(keys))
+        return keys
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("api_keys_load_failed", error=str(e))
+        return set()
+
+
+def create_api_key_verifier(
+    keys_path: Path | None = None,
+) -> "DebugTokenVerifier | None":
+    """Create verifier that validates tokens against configured keys.
+
+    Args:
+        keys_path: Path to JSON file with API keys (optional).
+
+    Returns:
+        DebugTokenVerifier configured for API key validation.
+        Passthrough verifier (accepts all tokens) if no keys configured.
+        This satisfies FastMCP Cloud's OAuth requirement while maintaining open access.
+    """
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+    keys = load_api_keys(keys_path)
+
+    if not keys:
+        # No keys configured → Open Mode
+        # For FastMCP Cloud compatibility, use passthrough verifier
+        # that accepts all tokens (effectively no auth) but exposes OAuth endpoints
+        logger.info("auth_open_mode_passthrough", reason="no_api_keys_configured")
+
+        def passthrough_validate(token: str) -> bool:
+            """Accept all tokens (effectively no authentication)."""
+            return True
+
+        return DebugTokenVerifier(
+            validate=passthrough_validate,
+            client_id="ref-agents-client",
+            scopes=["mcp:access"],
+        )
+
+    def validate(token: str) -> bool:
+        """Check if token exists in configured keys."""
+        is_valid = token in keys
+        if not is_valid:
+            logger.warning("token_rejected", token_prefix=token[:8] + "...")
+        return is_valid
+
+    return DebugTokenVerifier(
+        validate=validate,
+        client_id="ref-agents-client",
+        scopes=["mcp:access"],
+    )

ref_agents/codemap/..md

@@ -0,0 +1,62 @@
+# CODE_MAP: `.`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `tools/` | Dir | [Desc] | - |
+| `core/` | Dir | [Desc] | - |
+| `config/` | Dir | [Desc] | - |
+| `security/` | Dir | [Desc] | - |
+| `utils/` | Dir | [Desc] | - |
+| `models/` | Dir | [Desc] | - |
+| `codemap/` | Dir | [Desc] | - |
+| `workflow/` | Dir | [Desc] | - |
+| `rules/` | Dir | [Desc] | - |
+| `prompts/` | Dir | [Desc] | - |
+| `ref-reports/` | Dir | [Desc] | - |
+| `auth.py` | File | [Desc] | - |
+| `api_keys.json` | File | [Desc] | - |
+| `server.py` | File | [Desc] | - |
+| `api_keys.json.example` | File | [Desc] | - |
+| `constants.py` | File | [Desc] | - |
+| `session.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+| `tool_names.py` | File | [Desc] | - |
+| `security_scan.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+### Hardcoded External URLs
+
+| Domain | File | Line | Notes |
+|--------|------|------|-------|
+| `cdn.jsdelivr.net` | `context_graph.py` | 713 | ⚠️ Consider env var |
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/CODE_MAP.md

@@ -0,0 +1,37 @@
+# CODE_MAP: Project Overview
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the overall project purpose]
+
+
+
+## Package Index
+<!-- REF:AUTO -->
+| Package | Path | Purpose |
+|---------|------|---------|
+| [ref_agents](./..md) | `.` | [Desc] |
+| [core](./core.md) | `core` | [Desc] |
+| [models](./models.md) | `models` | [Desc] |
+| [prompts](./prompts.md) | `prompts` | [Desc] |
+| [security](./security.md) | `security` | [Desc] |
+| [tools](./tools.md) | `tools` | [Desc] |
+| [utils](./utils.md) | `utils` | [Desc] |
+| [workflow](./workflow.md) | `workflow` | [Desc] |
+| [browser](./tools_browser.md) | `tools/browser` | [Desc] |
+
+
+## Project Statistics
+<!-- REF:AUTO -->
+- **Total Packages:** 9
+- **Generated:** Auto-updated by discovery
+
+
+## Quick Navigation
+<!-- REF:MANUAL -->
+*Add frequently accessed modules here*
+
+| Module | Description |
+|--------|-------------|
+| ...    | ...         |

ref_agents/codemap/core.md

@@ -0,0 +1,43 @@
+# CODE_MAP: `core`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `config_loader.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+| `config_models.py` | File | [Desc] | - |
+| `language_detector.py` | File | [Desc] | - |
+| `config_parsing.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/models.md

@@ -0,0 +1,43 @@
+# CODE_MAP: `models`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `gherkin.py` | File | [Desc] | - |
+| `version.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+| `hierarchy.py` | File | [Desc] | - |
+| `invest.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/prompts.md

@@ -0,0 +1,40 @@
+# CODE_MAP: `prompts`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `start_agent.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/security.md

@@ -0,0 +1,45 @@
+# CODE_MAP: `security`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `file_audit.py` | File | [Desc] | - |
+| `url_scan.py` | File | [Desc] | - |
+| `dependency_audit.py` | File | [Desc] | - |
+| `secret_scan.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+| `report_generator.py` | File | [Desc] | - |
+| `network_scan.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/tools.md

@@ -0,0 +1,94 @@
+# CODE_MAP: `tools`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `browser/` | Dir | [Desc] | - |
+| `codemap/` | Dir | [Desc] | - |
+| `ref-reports/` | Dir | [Desc] | - |
+| `invest_scorer.py` | File | [Desc] | - |
+| `workflow_tools.py` | File | [Desc] | - |
+| `test_plan_validator.py` | File | [Desc] | - |
+| `compliance_remediation.py` | File | [Desc] | - |
+| `jira_confluence_export.py` | File | [Desc] | - |
+| `symbol_smoke_runner.py` | File | [Desc] | - |
+| `context_manager.py` | File | [Desc] | - |
+| `agents_generator.py` | File | [Desc] | - |
+| `requirements_serializer.py` | File | [Desc] | - |
+| `debt_scanner.py` | File | [Desc] | - |
+| `version_manager.py` | File | [Desc] | - |
+| `report_utils.py` | File | [Desc] | - |
+| `compliance.py` | File | [Desc] | - |
+| `flow_mapper.py` | File | [Desc] | - |
+| `ai_pattern_detector.py` | File | [Desc] | - |
+| `dependency_graph.py` | File | [Desc] | - |
+| `migration_readiness_scanner.py` | File | [Desc] | - |
+| `complexity.py` | File | [Desc] | - |
+| `health_scanner.py` | File | [Desc] | - |
+| `summary_generator.py` | File | [Desc] | - |
+| `external_detector.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+| `dead_code_scanner.py` | File | [Desc] | - |
+| `codemap.py` | File | [Desc] | - |
+| `tier1_fixer.py` | File | [Desc] | - |
+| `brownfield_populator.py` | File | [Desc] | - |
+| `pattern_learner.py` | File | [Desc] | - |
+| `context_tools.py` | File | [Desc] | - |
+| `context_graph.py` | File | [Desc] | - |
+| `json_output.py` | File | [Desc] | - |
+| `evaluate_gate.py` | File | [Desc] | - |
+| `docs_scanner.py` | File | [Desc] | - |
+| `guard_tools.py` | File | [Desc] | - |
+| `gherkin_parser.py` | File | [Desc] | - |
+| `sequencing_engine.py` | File | [Desc] | - |
+| `symbol_resolver.py` | File | [Desc] | - |
+| `test_smell_walker.py` | File | [Desc] | - |
+| `code_quality_scanner.py` | File | [Desc] | - |
+| `flow_gap_detector.py` | File | [Desc] | - |
+| `features_generator.py` | File | [Desc] | - |
+| `complexity_ast.py` | File | [Desc] | - |
+| `codemap_freshness.py` | File | [Desc] | - |
+| `discovery_audit.py` | File | [Desc] | - |
+| `migration_mapper.py` | File | [Desc] | - |
+| `handoff_tools.py` | File | [Desc] | - |
+| `full_suite_runner.py` | File | [Desc] | - |
+| `security_audit_tool.py` | File | [Desc] | - |
+| `cross_repo_linker.py` | File | [Desc] | - |
+| `hierarchy_manager.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+### Hardcoded External URLs
+
+| Domain | File | Line | Notes |
+|--------|------|------|-------|
+| `cdn.jsdelivr.net` | `context_graph.py` | 713 | ⚠️ Consider env var |
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/tools_browser.md

@@ -0,0 +1,44 @@
+# CODE_MAP: `tools/browser`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `screenshot_utils.py` | File | [Desc] | - |
+| `__init__.py` | File | [Desc] | - |
+| `evidence_verifier.py` | File | [Desc] | - |
+| `test_executor.py` | File | [Desc] | - |
+| `execution_logger.py` | File | [Desc] | - |
+| `playwright_mcp_client.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/utils.md

@@ -0,0 +1,42 @@
+# CODE_MAP: `utils`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `__init__.py` | File | [Desc] | - |
+| `handoff_logger.py` | File | [Desc] | - |
+| `ignore_matcher.py` | File | [Desc] | - |
+| `git_utils.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |

ref_agents/codemap/workflow.md

@@ -0,0 +1,42 @@
+# CODE_MAP: `workflow`
+
+
+## Purpose
+<!-- REF:MANUAL -->
+[Describe the purpose of this module]
+
+
+
+## Directory Structure
+<!-- REF:AUTO -->
+| Item | Type | Purpose | Dependencies |
+|------|------|---------|--------------|
+| `__init__.py` | File | [Desc] | - |
+| `state_machine.py` | File | [Desc] | - |
+| `transitions.py` | File | [Desc] | - |
+| `capabilities.py` | File | [Desc] | - |
+
+
+## Key Classes / Functions
+<!-- REF:MANUAL -->
+| Name | File | Purpose | Dependencies |
+|------|------|---------|--------------|
+| ...  | ...  | ...     | ...          |
+
+
+
+## External Dependencies
+<!-- REF:AUTO -->
+*Auto-detected by external_detector.py*
+
+No external dependencies detected.
+
+
+
+## Integration Boundaries
+<!-- REF:MANUAL -->
+*Where this module connects to external systems*
+
+| Boundary Type | Local Code | External System | Data Flow | Risk Level |
+|---------------|------------|-----------------|-----------|------------|
+| API Call      | [file.py]  | [External API]  | Outbound  | Medium     |