raise-cli 2.2.1__py3-none-any.whl

raise_cli/__init__.py

@@ -0,0 +1,38 @@
+"""RaiSE CLI - Reliable AI Software Engineering.
+
+A governance framework for AI-assisted software development.
+"""
+
+from __future__ import annotations
+
+from raise_cli.exceptions import (
+    ArtifactNotFoundError,
+    ConfigurationError,
+    DependencyError,
+    GateFailedError,
+    GateNotFoundError,
+    KataNotFoundError,
+    RaiError,
+    StateError,
+    ValidationError,
+)
+
+__version__ = "2.2.1"
+__author__ = "Emilio Osorio"
+__license__ = "MIT"
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__license__",
+    # Exceptions
+    "RaiError",
+    "ConfigurationError",
+    "KataNotFoundError",
+    "GateNotFoundError",
+    "ArtifactNotFoundError",
+    "DependencyError",
+    "StateError",
+    "ValidationError",
+    "GateFailedError",
+]

raise_cli/__main__.py

@@ -0,0 +1,30 @@
+"""Entry point for python -m raise_cli."""
+
+from __future__ import annotations
+
+import sys
+
+from raise_cli.cli.main import app
+from raise_cli.exceptions import RaiError
+
+
+def main() -> None:
+    """Run the CLI application with error handling.
+
+    Catches RaiError exceptions and displays them with proper formatting,
+    then exits with the appropriate exit code.
+    """
+    try:
+        app()
+    except RaiError as error:
+        # Import here to avoid circular imports and for lazy loading
+        from raise_cli.cli.error_handler import handle_error
+        from raise_cli.cli.main import get_output_format
+
+        output_format = get_output_format()
+        exit_code = handle_error(error, output_format=output_format)
+        sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

raise_cli/adapters/__init__.py

@@ -0,0 +1,91 @@
+"""Adapter contracts and registry for raise-cli extensibility.
+
+Public API: 7 Protocols + 15 boundary models + 2 sync wrappers
++ 5 registry functions + 5 group constants.
+KnowledgeGraphBackend + BackendHealth moved to raise_core (E275).
+
+Architecture: ADR-033 (PM), ADR-034 (Governance)
+"""
+
+from raise_cli.adapters.models import (
+    AdapterHealth,
+    ArtifactLocator,
+    BatchResult,
+    Comment,
+    CommentRef,
+    CoreArtifactType,
+    FailureDetail,
+    IssueDetail,
+    IssueRef,
+    IssueSpec,
+    IssueSummary,
+    PageContent,
+    PageSummary,
+    PublishResult,
+)
+from raise_cli.adapters.protocols import (
+    AsyncDocumentationTarget,
+    AsyncProjectManagementAdapter,
+    DocumentationTarget,
+    GovernanceParser,
+    GovernanceSchemaProvider,
+    ProjectManagementAdapter,
+)
+from raise_cli.adapters.registry import (
+    EP_DOC_TARGETS,
+    EP_GOVERNANCE_PARSERS,
+    EP_GOVERNANCE_SCHEMAS,
+    EP_GRAPH_BACKENDS,
+    EP_PM_ADAPTERS,
+    get_doc_targets,
+    get_governance_parsers,
+    get_governance_schemas,
+    get_graph_backends,
+    get_pm_adapters,
+)
+from raise_cli.adapters.sync import SyncDocsAdapter, SyncPMAdapter
+from raise_core.graph.backends.models import BackendHealth
+from raise_core.graph.backends.protocol import KnowledgeGraphBackend
+
+__all__ = [
+    # Protocols — sync (4 local + 1 from raise_core)
+    "DocumentationTarget",
+    "GovernanceParser",
+    "GovernanceSchemaProvider",
+    "KnowledgeGraphBackend",
+    "ProjectManagementAdapter",
+    # Protocols — async (2)
+    "AsyncDocumentationTarget",
+    "AsyncProjectManagementAdapter",
+    # Sync wrappers (2)
+    "SyncDocsAdapter",
+    "SyncPMAdapter",
+    # Models (14 local + 1 from raise_core)
+    "AdapterHealth",
+    "ArtifactLocator",
+    "BackendHealth",
+    "BatchResult",
+    "Comment",
+    "CommentRef",
+    "CoreArtifactType",
+    "FailureDetail",
+    "IssueDetail",
+    "IssueRef",
+    "IssueSpec",
+    "IssueSummary",
+    "PageContent",
+    "PageSummary",
+    "PublishResult",
+    # Registry functions
+    "get_doc_targets",
+    "get_governance_parsers",
+    "get_governance_schemas",
+    "get_graph_backends",
+    "get_pm_adapters",
+    # Entry point group constants
+    "EP_DOC_TARGETS",
+    "EP_GOVERNANCE_PARSERS",
+    "EP_GOVERNANCE_SCHEMAS",
+    "EP_GRAPH_BACKENDS",
+    "EP_PM_ADAPTERS",
+]

raise_cli/adapters/declarative/__init__.py

@@ -0,0 +1,26 @@
+"""Declarative MCP adapter framework.
+
+Enables integration of any MCP server via YAML config instead of Python code.
+
+Architecture: ADR-041, E337
+"""
+
+from raise_cli.adapters.declarative.adapter import DeclarativeMcpAdapter
+from raise_cli.adapters.declarative.expressions import ExpressionEvaluator
+from raise_cli.adapters.declarative.schema import (
+    AdapterMeta,
+    DeclarativeAdapterConfig,
+    MethodMapping,
+    ResponseMapping,
+)
+from raise_cli.mcp.schema import ServerConnection
+
+__all__ = [
+    "AdapterMeta",
+    "DeclarativeAdapterConfig",
+    "DeclarativeMcpAdapter",
+    "ExpressionEvaluator",
+    "MethodMapping",
+    "ResponseMapping",
+    "ServerConnection",
+]

raise_cli/adapters/declarative/adapter.py

@@ -0,0 +1,267 @@
+"""Generic declarative MCP adapter driven by YAML config.
+
+Implements ``AsyncProjectManagementAdapter`` and ``AsyncDocumentationTarget``
+by dispatching each protocol method to the MCP tool specified in the YAML
+config. Expression templates in args are evaluated against a context dict
+built from method parameters. One class serves both protocols (AR-Q1).
+
+Architecture: ADR-041, E337, AR-C1/C2/R1/Q1
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, cast
+
+from raise_cli.adapters.declarative.expressions import ExpressionEvaluator
+from raise_cli.adapters.declarative.schema import (
+    DeclarativeAdapterConfig,
+    MethodMapping,
+)
+from raise_cli.adapters.models import (
+    AdapterHealth,
+    BatchResult,
+    Comment,
+    CommentRef,
+    FailureDetail,
+    IssueDetail,
+    IssueRef,
+    IssueSpec,
+    IssueSummary,
+    PageContent,
+    PageSummary,
+    PublishResult,
+)
+from raise_cli.mcp.bridge import McpBridge, McpBridgeError, McpToolResult
+from raise_cli.mcp.registry import discover_mcp_servers
+from raise_cli.mcp.schema import ServerConnection
+
+logger = logging.getLogger(__name__)
+
+
+class DeclarativeMcpAdapter:
+    """Async adapter driven by YAML config — serves PM or Docs protocol.
+
+    Implements ``AsyncProjectManagementAdapter`` and ``AsyncDocumentationTarget``
+    via structural typing. Each protocol method dispatches to the MCP tool
+    declared in config.methods. One class, both protocols (AR-Q1).
+
+    Args:
+        config: Parsed YAML adapter configuration.
+    """
+
+    def __init__(self, config: DeclarativeAdapterConfig) -> None:
+        self._config = config
+        self._evaluator = ExpressionEvaluator()
+        self._bridge = self._create_bridge()
+
+    def _create_bridge(self) -> McpBridge:
+        """Create McpBridge from server config.
+
+        Resolves ``server.ref`` via MCP registry if set, otherwise
+        uses inline connection fields. (S338.5, AR-C2)
+        """
+        server = self._config.server
+        if server.ref is not None:
+            registry = discover_mcp_servers()
+            if server.ref not in registry:
+                msg = f"Server ref '{server.ref}' not found in MCP registry"
+                raise McpBridgeError(msg)
+            conn = registry[server.ref].server
+        else:
+            assert server.command is not None  # guaranteed by ServerRef validator
+            conn = ServerConnection(
+                command=server.command,
+                args=server.args,
+                env=server.env,
+            )
+        env: dict[str, str] | None = None
+        if conn.env:
+            env = {
+                **os.environ,
+                **{k: os.environ.get(k, "") for k in conn.env},
+            }
+        return McpBridge(
+            server_command=conn.command,
+            server_args=conn.args,
+            env=env,
+        )
+
+    def _get_method(self, name: str) -> MethodMapping:
+        """Get method mapping, raising NotImplementedError if null or missing."""
+        mapping = self._config.methods.get(name)
+        if mapping is None:
+            msg = f"Method '{name}' not supported by adapter '{self._config.adapter.name}'"
+            raise NotImplementedError(msg)
+        return mapping
+
+    async def _dispatch(
+        self, method_name: str, context: dict[str, Any]
+    ) -> McpToolResult:
+        """Dispatch a protocol method call to the configured MCP tool."""
+        mapping = self._get_method(method_name)
+        args = self._evaluator.evaluate_args(mapping.args, context)
+        return await self._bridge.call(mapping.tool, args)
+
+    def _parse_single(
+        self, method_name: str, result: McpToolResult, context: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Parse a single-item response using the method's response mapping."""
+        mapping = self._get_method(method_name)
+        if mapping.response is None:
+            return result.data
+
+        parse_ctx = {**context, "data": result.data}
+        return {
+            field: self._evaluator.evaluate(tmpl, parse_ctx)
+            for field, tmpl in mapping.response.fields.items()
+        }
+
+    def _parse_list(
+        self, method_name: str, result: McpToolResult
+    ) -> list[dict[str, Any]]:
+        """Parse a list response using items_path and field mappings."""
+        mapping = self._get_method(method_name)
+        if mapping.response is None:
+            return result.data.get("items", [])
+
+        # Navigate to list via items_path
+        items: Any = result.data
+        if mapping.response.items_path:
+            for part in mapping.response.items_path.split("."):
+                if isinstance(items, dict):
+                    items = cast(Any, items.get(part, []))
+
+        if not isinstance(items, list):
+            items = []
+
+        parsed: list[dict[str, Any]] = []
+        for raw_item in cast(list[Any], items):
+            item_ctx: dict[str, Any] = {"item": raw_item}
+            row = {
+                field: self._evaluator.evaluate(tmpl, item_ctx)
+                for field, tmpl in mapping.response.fields.items()
+            }
+            parsed.append(row)
+        return parsed
+
+    # ----- CRUD -----
+
+    async def create_issue(self, project_key: str, issue: IssueSpec) -> IssueRef:
+        ctx = {"project_key": project_key, "issue": issue.model_dump()}
+        result = await self._dispatch("create_issue", ctx)
+        fields = self._parse_single("create_issue", result, ctx)
+        return IssueRef(**fields)
+
+    async def get_issue(self, key: str) -> IssueDetail:
+        ctx = {"key": key}
+        result = await self._dispatch("get_issue", ctx)
+        fields = self._parse_single("get_issue", result, ctx)
+        return IssueDetail(**fields)
+
+    async def update_issue(self, key: str, fields: dict[str, Any]) -> IssueRef:
+        ctx = {"key": key, "fields": fields}
+        result = await self._dispatch("update_issue", ctx)
+        parsed = self._parse_single("update_issue", result, ctx)
+        return IssueRef(**parsed)
+
+    async def transition_issue(self, key: str, status: str) -> IssueRef:
+        ctx = {"key": key, "status": status}
+        result = await self._dispatch("transition_issue", ctx)
+        parsed = self._parse_single("transition_issue", result, ctx)
+        return IssueRef(**parsed)
+
+    # ----- Batch -----
+
+    async def batch_transition(self, keys: list[str], status: str) -> BatchResult:
+        """Auto-loops over transition_issue (AR design D6)."""
+        succeeded: list[IssueRef] = []
+        failed: list[FailureDetail] = []
+
+        for key in keys:
+            try:
+                ref = await self.transition_issue(key, status)
+                succeeded.append(ref)
+            except (McpBridgeError, NotImplementedError, Exception) as exc:
+                failed.append(FailureDetail(key=key, error=str(exc)))
+
+        return BatchResult(succeeded=succeeded, failed=failed)
+
+    # ----- Relationships -----
+
+    async def link_to_parent(self, child_key: str, parent_key: str) -> None:
+        ctx = {"child_key": child_key, "parent_key": parent_key}
+        await self._dispatch("link_to_parent", ctx)
+
+    async def link_issues(self, source: str, target: str, link_type: str) -> None:
+        ctx = {"source": source, "target": target, "link_type": link_type}
+        await self._dispatch("link_issues", ctx)
+
+    # ----- Comments -----
+
+    async def add_comment(self, key: str, body: str) -> CommentRef:
+        ctx = {"key": key, "body": body}
+        result = await self._dispatch("add_comment", ctx)
+        fields = self._parse_single("add_comment", result, ctx)
+        return CommentRef(**fields)
+
+    async def get_comments(self, key: str, limit: int = 10) -> list[Comment]:
+        ctx = {"key": key, "limit": limit}
+        result = await self._dispatch("get_comments", ctx)
+        items = self._parse_list("get_comments", result)
+        return [Comment(**item) for item in items]
+
+    # ----- Query -----
+
+    async def search(
+        self, query: str, limit: int = 50
+    ) -> list[IssueSummary] | list[PageSummary]:
+        """Protocol-aware search: returns IssueSummary (PM) or PageSummary (docs).
+
+        SyncDocsAdapter calls .search() — must return the right type based on
+        the adapter's configured protocol (QR-C1 fix).
+        """
+        ctx = {"query": query, "limit": limit}
+        result = await self._dispatch("search", ctx)
+        items = self._parse_list("search", result)
+        if self._config.adapter.protocol == "docs":
+            return [PageSummary(**item) for item in items]
+        return [IssueSummary(**item) for item in items]
+
+    # ----- Docs: Documentation Target (AR-Q1) -----
+
+    async def can_publish(self, doc_type: str, metadata: dict[str, Any]) -> bool:
+        ctx = {"doc_type": doc_type, "metadata": metadata}
+        result = await self._dispatch("can_publish", ctx)
+        fields = self._parse_single("can_publish", result, ctx)
+        return bool(fields.get("result", False))
+
+    async def publish(
+        self, doc_type: str, content: str, metadata: dict[str, Any]
+    ) -> PublishResult:
+        ctx = {"doc_type": doc_type, "content": content, "metadata": metadata}
+        result = await self._dispatch("publish", ctx)
+        fields = self._parse_single("publish", result, ctx)
+        return PublishResult(**fields)
+
+    async def get_page(self, identifier: str) -> PageContent:
+        ctx = {"identifier": identifier}
+        result = await self._dispatch("get_page", ctx)
+        fields = self._parse_single("get_page", result, ctx)
+        return PageContent(**fields)
+
+    # ----- Lifecycle -----
+
+    async def health(self) -> AdapterHealth:
+        bridge_health = await self._bridge.health()
+        return AdapterHealth(
+            name=self._config.adapter.name,
+            healthy=bridge_health.healthy,
+            message=bridge_health.message,
+            latency_ms=bridge_health.latency_ms,
+        )
+
+    async def aclose(self) -> None:
+        """Close the underlying MCP bridge."""
+        await self._bridge.aclose()

raise_cli/adapters/declarative/discovery.py

@@ -0,0 +1,94 @@
+"""YAML adapter discovery for declarative MCP adapters.
+
+Scans ``.raise/adapters/*.yaml`` for adapter configs, parses them with
+``DeclarativeAdapterConfig``, filters by protocol, and returns factory
+closures compatible with ``resolve_entrypoint``.
+
+Architecture: ADR-041, E337, S337.3, AR-C1 (factory closure)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from raise_cli.adapters.declarative.schema import DeclarativeAdapterConfig
+
+logger = logging.getLogger(__name__)
+
+
+def _make_factory(cfg: DeclarativeAdapterConfig) -> Callable[[], Any]:
+    """AR-C1: factory closure captures config for no-arg instantiation."""
+
+    def factory() -> Any:
+        from raise_cli.adapters.declarative.adapter import DeclarativeMcpAdapter
+
+        return DeclarativeMcpAdapter(cfg)
+
+    return factory
+
+
+def discover_yaml_adapters(
+    protocol: str,
+    *,
+    adapters_dir: Path | None = None,
+) -> dict[str, Callable[[], Any]]:
+    """Discover YAML-defined adapters for a given protocol.
+
+    Scans ``adapters_dir`` (default: ``.raise/adapters/``) for ``*.yaml``
+    files, parses each as a ``DeclarativeAdapterConfig``, filters by
+    ``adapter.protocol``, and returns factory closures.
+
+    Each factory closure captures its parsed config and returns a new
+    ``DeclarativeMcpAdapter`` when called with no arguments (AR-C1).
+
+    Args:
+        protocol: Protocol to filter by (``"pm"`` or ``"docs"``).
+        adapters_dir: Directory to scan. Defaults to ``.raise/adapters/``.
+
+    Returns:
+        Mapping of adapter name to no-arg factory callable.
+    """
+    if adapters_dir is None:
+        adapters_dir = Path.cwd() / ".raise" / "adapters"
+
+    if not adapters_dir.is_dir():
+        return {}
+
+    result: dict[str, Callable[[], Any]] = {}
+
+    for yaml_path in sorted(adapters_dir.glob("*.yaml")):
+        try:
+            raw = yaml.safe_load(yaml_path.read_text(encoding="utf-8"))
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Skipping %s: YAML parse error: %s", yaml_path.name, exc)
+            continue
+
+        try:
+            config = DeclarativeAdapterConfig.model_validate(raw)
+        except ValidationError as exc:
+            logger.warning(
+                "Skipping %s: schema validation error: %s", yaml_path.name, exc
+            )
+            continue
+
+        if config.adapter.protocol != protocol:
+            continue
+
+        name = config.adapter.name
+        if name in result:
+            logger.warning(
+                "Skipping %s: adapter name '%s' already defined by another YAML file",
+                yaml_path.name,
+                name,
+            )
+            continue
+
+        result[name] = _make_factory(config)
+
+    return result

raise_cli/adapters/declarative/expressions.py

@@ -0,0 +1,150 @@
+"""Mini expression evaluator for declarative adapter templates.
+
+Supports: ``{{ var }}``, ``{{ obj.field }}``, ``{{ value | filter }}``.
+Filters: ``str``, ``default('fallback')``, ``pluck('field')``, ``json``.
+
+~100 LOC, zero external dependencies.
+
+Architecture: ADR-041 (D2 — mini evaluator, not Jinja2)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, cast
+
+# Matches {{ expression }} with optional whitespace
+_TEMPLATE_RE = re.compile(r"\{\{\s*(.+?)\s*\}\}")
+
+# Matches filter with optional quoted argument: filter_name('arg')
+_FILTER_RE = re.compile(r"(\w+)\s*(?:\(\s*'([^']*)'\s*\))?")
+
+
+class ExpressionEvaluator:
+    """Evaluate template expressions against a context dict.
+
+    Designed for declarative MCP adapter YAML configs. Intentionally
+    minimal — covers dot-access and 4 filters. Not a general-purpose
+    template engine.
+    """
+
+    def evaluate(self, template: str, context: dict[str, Any]) -> Any:
+        """Evaluate a single template string against context.
+
+        Args:
+            template: Template string, e.g. ``"{{ issue.summary | str }}"``.
+            context: Variable context dict.
+
+        Returns:
+            Resolved value. Type depends on expression — may be str, int,
+            list, dict, None, etc.
+
+        Raises:
+            KeyError: If a referenced variable is not in context.
+        """
+        match = _TEMPLATE_RE.fullmatch(template.strip()) if template else None
+        if match is None:
+            # Literal passthrough — no {{ }} found
+            return template
+
+        expr = match.group(1).strip()
+        return self._eval_expr(expr, context)
+
+    def evaluate_args(
+        self, args: dict[str, str], context: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Evaluate all values in an args dict.
+
+        Args:
+            args: Mapping of param name → template string.
+            context: Variable context dict.
+
+        Returns:
+            New dict with all values resolved.
+        """
+        return {key: self.evaluate(tmpl, context) for key, tmpl in args.items()}
+
+    def _eval_expr(self, expr: str, context: dict[str, Any]) -> Any:
+        """Evaluate an expression, optionally with a pipe filter."""
+        # Split on pipe: "value | filter('arg')"
+        parts = expr.split("|", maxsplit=1)
+        var_path = parts[0].strip()
+
+        try:
+            value = self._resolve_path(var_path, context)
+        except KeyError:
+            # If there's a default filter, use it; otherwise re-raise
+            if len(parts) > 1 and "default" in parts[1]:
+                value = None
+            else:
+                raise
+
+        if len(parts) > 1:
+            filter_expr = parts[1].strip()
+            value = self._apply_filter(filter_expr, value, context)
+
+        return value
+
+    def _resolve_path(self, path: str, context: dict[str, Any]) -> Any:
+        """Resolve a dot-separated path against context.
+
+        ``"issue.summary"`` → ``context["issue"]["summary"]``
+        """
+        parts = path.split(".")
+        current: Any = context
+
+        for part in parts:
+            if isinstance(current, dict):
+                if part not in current:
+                    raise KeyError(part)
+                current = cast(Any, current[part])
+            else:
+                raise KeyError(part)
+
+        return current
+
+    def _apply_filter(
+        self, filter_expr: str, value: Any, context: dict[str, Any]
+    ) -> Any:
+        """Apply a filter to a value."""
+        match = _FILTER_RE.fullmatch(filter_expr)
+        if not match:
+            msg = f"Invalid filter expression: {filter_expr}"
+            raise ValueError(msg)
+
+        filter_name = match.group(1)
+        filter_arg = match.group(2)  # None if no arg
+
+        if filter_name == "str":
+            return str(value)
+        if filter_name == "json":
+            return json.dumps(value)
+        if filter_name == "default":
+            if value is None:
+                return filter_arg
+            # Also handle KeyError case — caller catches and retries with default
+            return value
+        if filter_name == "pluck":
+            if not isinstance(value, list):
+                msg = f"pluck requires a list, got {type(value).__name__}"
+                raise TypeError(msg)
+            if filter_arg is None:
+                msg = "pluck requires a field argument"
+                raise ValueError(msg)
+            return [
+                self._pluck_item(item, filter_arg) for item in cast(list[Any], value)
+            ]
+
+        msg = f"Unknown filter: {filter_name}"
+        raise ValueError(msg)
+
+    @staticmethod
+    def _pluck_item(item: Any, field: str) -> Any:
+        """Extract a field from a dict item, raising KeyError if missing."""
+        if isinstance(item, dict):
+            if field not in item:
+                raise KeyError(field)
+            return cast(Any, item[field])
+        msg = f"pluck expects dict items, got {type(item).__name__}"
+        raise TypeError(msg)

raise_cli/adapters/declarative/reference/__init__.py

@@ -0,0 +1 @@
+"""Reference YAML adapter configs shipped with the package."""