raise-cli 2.2.1__py3-none-any.whl

raise_cli/adapters/declarative/reference/github.yaml

@@ -0,0 +1,143 @@
+# Reference YAML adapter config: GitHub Issues via MCP
+#
+# This file demonstrates how to integrate an MCP server with the
+# declarative adapter framework. Copy and adapt for your own server.
+#
+# Architecture: ADR-041, E337
+
+# --- Adapter identity ---
+# name: Used with --adapter flag (e.g., rai backlog search --adapter github)
+# protocol: "pm" (ProjectManagement) or "docs" (Documentation)
+# description: Human-readable, shown in `rai adapter list`
+adapter:
+  name: github
+  protocol: pm
+  description: "GitHub Issues via mcp-github"
+
+# --- MCP server connection ---
+# command: Executable to launch the MCP server subprocess
+# args: Command-line arguments passed to the server
+# env: Environment variable names to forward to the subprocess
+#      (values read from the current environment at runtime)
+server:
+  command: uvx
+  args: [mcp-github]
+  env: [GITHUB_TOKEN]
+
+# --- Protocol method mappings ---
+# Each key is a protocol method name from AsyncProjectManagementAdapter.
+# Set to null for methods the MCP server doesn't support.
+#
+# Per method:
+#   tool: MCP tool name to call
+#   args: Argument name → expression template
+#         Templates use {{ var }} syntax with dot-access and filters:
+#           {{ issue.summary }}       — dot-access into nested objects
+#           {{ data.number | str }}   — type coercion filter
+#           {{ data.url | default:"" }} — default value filter
+#           {{ data.labels | pluck:"name" }} — extract field from list items
+#   response: How to parse the MCP tool response
+#     fields: Field name → expression template (for single-item responses)
+#     items_path: Dot-path to list in response data (for list responses)
+methods:
+
+  # --- CRUD ---
+
+  create_issue:
+    tool: github_create_issue
+    args:
+      title: "{{ issue.summary }}"
+      body: "{{ issue.description | default:'' }}"
+      repo: "{{ project_key }}"
+      labels: "{{ issue.labels | default:'' }}"
+    response:
+      fields:
+        key: "{{ data.number | str }}"
+        url: "{{ data.html_url }}"
+
+  get_issue:
+    tool: github_get_issue
+    args:
+      issue_number: "{{ key }}"
+    response:
+      fields:
+        key: "{{ data.number | str }}"
+        summary: "{{ data.title }}"
+        status: "{{ data.state }}"
+        issue_type: "{{ data.type | default:'Issue' }}"
+        description: "{{ data.body | default:'' }}"
+
+  update_issue:
+    tool: github_update_issue
+    args:
+      issue_number: "{{ key }}"
+      title: "{{ fields.summary | default:'' }}"
+      body: "{{ fields.description | default:'' }}"
+    response:
+      fields:
+        key: "{{ data.number | str }}"
+        url: "{{ data.html_url }}"
+
+  transition_issue:
+    tool: github_update_issue
+    args:
+      issue_number: "{{ key }}"
+      state: "{{ status }}"
+    response:
+      fields:
+        key: "{{ data.number | str }}"
+        url: "{{ data.html_url }}"
+
+  # --- Batch ---
+  # batch_transition is auto-looped by the adapter (calls transition_issue N times).
+  # No MCP tool needed — set to null.
+  batch_transition: null
+
+  # --- Relationships ---
+  # GitHub doesn't have native issue linking via MCP tools.
+  link_to_parent: null
+  link_issues: null
+
+  # --- Comments ---
+
+  add_comment:
+    tool: github_add_comment
+    args:
+      issue_number: "{{ key }}"
+      body: "{{ body }}"
+    response:
+      fields:
+        id: "{{ data.id | str }}"
+        url: "{{ data.html_url }}"
+
+  get_comments:
+    tool: github_list_comments
+    args:
+      issue_number: "{{ key }}"
+      per_page: "{{ limit }}"
+    response:
+      items_path: data
+      fields:
+        id: "{{ item.id | str }}"
+        author: "{{ item.user.login }}"
+        body: "{{ item.body }}"
+        created: "{{ item.created_at }}"
+
+  # --- Query ---
+
+  search:
+    tool: github_search_issues
+    args:
+      query: "{{ query }}"
+      per_page: "{{ limit }}"
+    response:
+      items_path: data.items
+      fields:
+        key: "{{ item.number | str }}"
+        summary: "{{ item.title }}"
+        status: "{{ item.state }}"
+
+  # --- Lifecycle ---
+  # health is handled by the adapter framework (pings the MCP bridge).
+  # No MCP tool needed — set to null.
+  health: null

raise_cli/adapters/declarative/schema.py

@@ -0,0 +1,98 @@
+"""Pydantic models for declarative MCP adapter YAML config.
+
+Validates the YAML structure used by DeclarativeMcpAdapter.
+No ``model`` field in ResponseMapping — the adapter infers
+the return type from the protocol method name (AR-R1).
+
+Architecture: ADR-041, E337, E338 (AR-C2: shared ServerConnection)
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class AdapterMeta(BaseModel):
+    """Top-level adapter identity and protocol selection."""
+
+    name: str = Field(..., description="Adapter name (used in --adapter flag)")
+    protocol: Literal["pm", "docs"] = Field(
+        ..., description="Protocol: 'pm' (ProjectManagement) or 'docs' (Documentation)"
+    )
+    description: str | None = Field(
+        default=None, description="Human-readable description"
+    )
+
+
+class ResponseMapping(BaseModel):
+    """How to parse MCP tool response into adapter models.
+
+    No ``model`` field — adapter infers return type from method name (AR-R1).
+    """
+
+    fields: dict[str, str] = Field(
+        ..., description="Field name → expression template mapping"
+    )
+    items_path: str | None = Field(
+        default=None,
+        description="Dot-path to list in response (e.g. 'data.items')",
+    )
+
+
+class MethodMapping(BaseModel):
+    """Maps a protocol method to an MCP tool call."""
+
+    tool: str = Field(..., description="MCP tool name to call")
+    args: dict[str, str] = Field(
+        default_factory=dict,
+        description="Argument name → expression template mapping",
+    )
+    response: ResponseMapping | None = Field(
+        default=None, description="Response parsing config (None = raw result)"
+    )
+
+
+class ServerRef(BaseModel):
+    """Server config: reference MCP registry OR inline connection.
+
+    Either ``ref`` (name in ``.raise/mcp/`` registry) or ``command``
+    (inline connection) must be provided. Both may be set but ref
+    takes precedence at resolution time.
+
+    Architecture: E338 S338.5 — Option B (separate from ServerConnection).
+    """
+
+    ref: str | None = Field(default=None, description="Name in .raise/mcp/ registry")
+    command: str | None = Field(
+        default=None, description="Server command (e.g. 'uvx', 'npx')"
+    )
+    args: list[str] = Field(
+        default_factory=list, description="Server command arguments"
+    )
+    env: list[str] | None = Field(
+        default=None,
+        description="Env var names to pass to server subprocess",
+    )
+
+    @model_validator(mode="after")
+    def _ref_or_command(self) -> ServerRef:
+        if self.ref is None and self.command is None:
+            msg = "Either 'ref' or 'command' must be provided"
+            raise ValueError(msg)
+        return self
+
+
+class DeclarativeAdapterConfig(BaseModel):
+    """Root config model for a declarative MCP adapter.
+
+    Parsed from ``.raise/adapters/<name>.yaml``.
+    """
+
+    adapter: AdapterMeta
+    server: ServerRef
+    methods: dict[str, MethodMapping | None] = Field(
+        default_factory=dict,
+        description="Protocol method → MCP tool mapping. None = unsupported.",
+    )

raise_cli/adapters/filesystem.py

@@ -0,0 +1,299 @@
+"""Filesystem-based PM adapter with YAML file store.
+
+Open-core fallback: provides read + write PM functionality without
+external services. Each issue is a YAML file at
+``.raise/backlog/items/{KEY}.yaml`` validated by Pydantic on load/dump.
+
+Architecture: S347.2 (E347 Backlog Automation)
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from raise_cli.adapters.models import (
+    AdapterHealth,
+    BacklogComment,
+    BacklogItem,
+    BacklogLink,
+    BatchResult,
+    Comment,
+    CommentRef,
+    FailureDetail,
+    IssueDetail,
+    IssueRef,
+    IssueSpec,
+    IssueSummary,
+)
+
+
+class FilesystemPMAdapter:
+    """PM adapter backed by YAML file store.
+
+    Each issue lives at ``.raise/backlog/items/{KEY}.yaml``.
+    """
+
+    def __init__(self, project_root: Path | None = None) -> None:
+        self._root = project_root or Path.cwd()
+        self._items_dir = self._root / ".raise" / "backlog" / "items"
+
+    # -- YAML I/O helpers ---------------------------------------------------
+
+    def _item_path(self, key: str) -> Path:
+        """Path to a YAML item file."""
+        return self._items_dir / f"{key}.yaml"
+
+    def _load_item(self, key: str) -> BacklogItem:
+        """Load and validate a single YAML item. Raises KeyError if missing."""
+        path = self._item_path(key)
+        if not path.exists():
+            raise KeyError(key)
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+        return BacklogItem.model_validate(raw)
+
+    def _save_item(self, item: BacklogItem) -> None:
+        """Dump a BacklogItem to YAML, excluding None values for clean files."""
+        self._items_dir.mkdir(parents=True, exist_ok=True)
+        data = item.model_dump(exclude_none=True)
+        # Remove empty collections for clean YAML
+        for field in ("comments", "links", "labels"):
+            if field in data and not data[field]:
+                del data[field]
+        if "description" in data and not data["description"]:
+            del data["description"]
+        path = self._item_path(item.key)
+        path.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8")
+
+    def _load_all_items(self) -> list[BacklogItem]:
+        """Load all YAML items from the store."""
+        if not self._items_dir.is_dir():
+            return []
+        items: list[BacklogItem] = []
+        for path in sorted(self._items_dir.glob("*.yaml")):
+            raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+            items.append(BacklogItem.model_validate(raw))
+        return items
+
+    # -- Key generation helpers -----------------------------------------------
+
+    def _next_epic_key(self) -> str:
+        """Scan existing E{N}.yaml files and return E{N+1}."""
+        max_n = 0
+        if self._items_dir.is_dir():
+            for path in self._items_dir.glob("E*.yaml"):
+                m = re.match(r"E(\d+)\.yaml$", path.name)
+                if m:
+                    max_n = max(max_n, int(m.group(1)))
+        return f"E{max_n + 1}"
+
+    def _next_story_key(self, parent_key: str) -> str:
+        """Scan existing S{epic_num}.{M}.yaml and return S{epic_num}.{M+1}.
+
+        Requires the parent epic key (e.g., 'E1') to derive the epic number.
+        """
+        m = re.match(r"E(\d+)", parent_key)
+        if not m:
+            raise ValueError(f"Cannot derive epic number from parent key: {parent_key}")
+        epic_num = m.group(1)
+        max_m = 0
+        if self._items_dir.is_dir():
+            for path in self._items_dir.glob(f"S{epic_num}.*.yaml"):
+                sm = re.match(rf"S{epic_num}\.(\d+)\.yaml$", path.name)
+                if sm:
+                    max_m = max(max_m, int(sm.group(1)))
+        return f"S{epic_num}.{max_m + 1}"
+
+    # -- Search helper -------------------------------------------------------
+
+    def _match(self, item: IssueSummary, query: str) -> bool:
+        """Check if an item matches a search query.
+
+        Supports:
+        - Empty query: matches all
+        - field = value: exact match on status, key
+        - bare text: case-insensitive substring match on key + summary
+        """
+        query = query.strip()
+        if not query:
+            return True
+
+        # field = value
+        m = re.match(r"(\w+)\s*=\s*(.+)", query)
+        if m:
+            field, value = m.group(1).lower(), m.group(2).strip().lower()
+            if field == "status":
+                return item.status.lower() == value
+            if field == "name":
+                return value in item.summary.lower()
+            if field == "priority":
+                return False
+            return False
+
+        # bare text -> substring match on key + summary
+        q = query.lower()
+        return q in item.key.lower() or q in item.summary.lower()
+
+    # -- Read operations ----------------------------------------------------
+
+    def get_issue(self, key: str) -> IssueDetail:
+        """Get issue detail by key."""
+        item = self._load_item(key)
+        return IssueDetail(
+            key=item.key,
+            summary=item.summary,
+            status=item.status,
+            issue_type=item.issue_type,
+            description=item.description,
+            labels=item.labels,
+            parent_key=item.parent,
+            priority=item.priority,
+            assignee=item.assignee,
+            created=item.created,
+            updated=item.updated,
+        )
+
+    def search(self, query: str, limit: int = 50) -> list[IssueSummary]:
+        """Search issues."""
+        items = self._load_all_items()
+        summaries = [
+            IssueSummary(
+                key=it.key,
+                summary=it.summary,
+                status=it.status,
+                issue_type=it.issue_type,
+                parent_key=it.parent,
+            )
+            for it in items
+        ]
+        matched = [s for s in summaries if self._match(s, query)]
+        return matched[:limit]
+
+    def get_comments(self, key: str, limit: int = 10) -> list[Comment]:
+        """Get comments for an issue. Returns [] if issue not found."""
+        try:
+            item = self._load_item(key)
+        except KeyError:
+            return []
+        comments = [
+            Comment(id=c.id, body=c.body, author=c.author, created=c.created)
+            for c in item.comments
+        ]
+        return comments[:limit]
+
+    def health(self) -> AdapterHealth:
+        """Check adapter health."""
+        if self._items_dir.is_dir():
+            count = len(list(self._items_dir.glob("*.yaml")))
+            return AdapterHealth(
+                name="filesystem",
+                healthy=True,
+                message=f".raise/backlog/items/ ({count} items)",
+            )
+        return AdapterHealth(
+            name="filesystem",
+            healthy=False,
+            message="YAML store not found (.raise/backlog/items/)",
+        )
+
+    # -- Write operations ---------------------------------------------------
+
+    def create_issue(self, project_key: str, issue: IssueSpec) -> IssueRef:
+        """Create a new issue."""
+        meta = issue.metadata or {}
+        now = datetime.now(UTC).isoformat()
+        itype = issue.issue_type.lower()
+        if itype == "epic":
+            key = self._next_epic_key()
+        elif itype in ("story", "subtask"):
+            parent_key = meta.get("parent_key")
+            if not parent_key:
+                raise KeyError("Story creation requires parent_key")
+            key = self._next_story_key(parent_key)
+        else:
+            # Default to epic-style key for Task and other types
+            key = self._next_epic_key()
+        new_item = BacklogItem(
+            key=key,
+            summary=issue.summary,
+            issue_type=issue.issue_type,
+            status="pending",
+            parent=meta.get("parent_key"),
+            description=issue.description,
+            labels=issue.labels,
+            priority=meta.get("priority"),
+            created=now,
+            updated=now,
+        )
+        self._save_item(new_item)
+        return IssueRef(key=new_item.key)
+
+    # Fields that must not be mutated via update_issue()
+    _IMMUTABLE_FIELDS: frozenset[str] = frozenset(
+        {"key", "created", "comments", "links"}
+    )
+
+    def update_issue(self, key: str, fields: dict[str, Any]) -> IssueRef:
+        """Update fields on an existing issue."""
+        item = self._load_item(key)
+        for field_name, value in fields.items():
+            if field_name in self._IMMUTABLE_FIELDS:
+                continue
+            if hasattr(item, field_name):
+                setattr(item, field_name, value)
+        item.updated = datetime.now(UTC).isoformat()
+        self._save_item(item)
+        return IssueRef(key=key)
+
+    def transition_issue(self, key: str, status: str) -> IssueRef:
+        """Update issue status."""
+        item = self._load_item(key)
+        item.status = status
+        item.updated = datetime.now(UTC).isoformat()
+        self._save_item(item)
+        return IssueRef(key=key)
+
+    def batch_transition(self, keys: list[str], status: str) -> BatchResult:
+        """Transition multiple issues."""
+        succeeded: list[IssueRef] = []
+        failed: list[FailureDetail] = []
+        for key in keys:
+            try:
+                ref = self.transition_issue(key, status)
+                succeeded.append(ref)
+            except KeyError:
+                failed.append(FailureDetail(key=key, error=f"{key} not found"))
+        return BatchResult(succeeded=succeeded, failed=failed)
+
+    # -- Relationship & comment operations ----------------------------------
+
+    def link_to_parent(self, child_key: str, parent_key: str) -> None:
+        """Set parent field on child issue."""
+        item = self._load_item(child_key)
+        item.parent = parent_key
+        item.updated = datetime.now(UTC).isoformat()
+        self._save_item(item)
+
+    def link_issues(self, source: str, target: str, link_type: str) -> None:
+        """Add a link from source to target."""
+        item = self._load_item(source)
+        item.links.append(BacklogLink(target=target, link_type=link_type))
+        item.updated = datetime.now(UTC).isoformat()
+        self._save_item(item)
+
+    def add_comment(self, key: str, body: str) -> CommentRef:
+        """Add a comment to an issue."""
+        item = self._load_item(key)
+        next_n = len(item.comments) + 1
+        comment_id = f"{key}-{next_n}"
+        now = datetime.now(UTC).isoformat()
+        item.comments.append(
+            BacklogComment(id=comment_id, body=body, author="rai", created=now)
+        )
+        item.updated = now
+        self._save_item(item)
+        return CommentRef(id=comment_id)

raise_cli/adapters/mcp_bridge.py

@@ -0,0 +1,10 @@
+"""Backwards-compat re-export. Import from raise_cli.mcp.bridge instead.
+
+Architecture: ADR-042, E338 — McpBridge moved to raise_cli.mcp.bridge.
+This shim exists for backwards compatibility with external consumers.
+"""
+
+from raise_cli.mcp.bridge import McpBridge, McpBridgeError  # noqa: F401
+from raise_cli.mcp.models import McpToolInfo, McpToolResult  # noqa: F401
+
+__all__ = ["McpBridge", "McpBridgeError", "McpToolInfo", "McpToolResult"]