raise-cli 2.2.1__py3-none-any.whl

raise_cli/adapters/models.py

@@ -0,0 +1,205 @@
+"""Pydantic models for adapter boundaries.
+
+Shared data types consumed by adapter Protocols. These models define
+the contracts at integration boundaries — what goes in and comes out
+of adapters regardless of their concrete implementation.
+
+Architecture: ADR-033 (Open-core adapter architecture), ADR-034 (Governance extensibility)
+"""
+
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class CoreArtifactType(StrEnum):
+    """Core governance artifact types.
+
+    Protocols accept ``str`` — plugins are not restricted to this enum.
+    Use these constants for built-in artifact types.
+    """
+
+    BACKLOG = "backlog"
+    ADR = "adr"
+    CONSTITUTION = "constitution"
+    PRD = "prd"
+    VISION = "vision"
+    GUARDRAILS = "guardrails"
+    GLOSSARY = "glossary"
+    ROADMAP = "roadmap"
+    EPIC_SCOPE = "epic_scope"
+
+
+class ArtifactLocator(BaseModel):
+    """Points to a governance artifact for parsing."""
+
+    path: str = Field(..., description="Relative path from project root")
+    artifact_type: str = Field(
+        ..., description="Artifact type (CoreArtifactType or custom str)"
+    )
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Type-specific context"
+    )
+
+
+class IssueSpec(BaseModel):
+    """Specification for creating a PM issue."""
+
+    summary: str = Field(..., description="Issue title")
+    description: str = Field(default="", description="Issue body (markdown)")
+    issue_type: str = Field(default="Task", description="Issue type name")
+    labels: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="PM-specific fields"
+    )
+
+
+class IssueRef(BaseModel):
+    """Reference to an existing PM issue."""
+
+    key: str = Field(..., description="Issue key (e.g., 'PROJ-123')")
+    url: str = Field(default="", description="Web URL to the issue")
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class PublishResult(BaseModel):
+    """Result of publishing documentation."""
+
+    success: bool = Field(..., description="Whether publish succeeded")
+    url: str = Field(default="", description="URL of published content")
+    message: str = Field(default="", description="Status or error message")
+
+
+class IssueDetail(IssueRef):
+    """Full issue details — extends IssueRef (inherits key, url, metadata).
+
+    Timestamps use ISO 8601 format (e.g. ``2026-02-27T10:30:00Z``).
+    Empty string means timestamp not available.
+    """
+
+    summary: str = Field(..., description="Issue title")
+    description: str = Field(default="", description="Issue body (markdown)")
+    status: str = Field(..., description="Current status name")
+    issue_type: str = Field(..., description="Issue type (e.g., 'Story', 'Bug')")
+    parent_key: str | None = Field(default=None, description="Parent issue key")
+    labels: list[str] = Field(default_factory=list)
+    assignee: str | None = Field(default=None, description="Assignee identifier")
+    priority: str | None = Field(default=None, description="Priority name")
+    created: str = Field(default="", description="ISO 8601 creation timestamp")
+    updated: str = Field(default="", description="ISO 8601 last update timestamp")
+
+
+class IssueSummary(BaseModel):
+    """Compact issue for search results and listings."""
+
+    key: str = Field(..., description="Issue key (e.g., 'PROJ-123')")
+    summary: str = Field(..., description="Issue title")
+    status: str = Field(..., description="Current status name")
+    issue_type: str = Field(..., description="Issue type name")
+    parent_key: str | None = Field(default=None, description="Parent issue key")
+
+
+class Comment(BaseModel):
+    """Issue comment. Timestamps use ISO 8601 format."""
+
+    id: str = Field(..., description="Comment ID")
+    body: str = Field(..., description="Comment body (markdown)")
+    author: str = Field(..., description="Author identifier")
+    created: str = Field(..., description="ISO 8601 creation timestamp")
+
+
+class CommentRef(BaseModel):
+    """Reference to a created comment."""
+
+    id: str = Field(..., description="Comment ID")
+    url: str = Field(default="", description="Web URL to the comment")
+
+
+class FailureDetail(BaseModel):
+    """A single failure in a batch operation."""
+
+    key: str = Field(..., description="Issue key that failed")
+    error: str = Field(..., description="Error description")
+
+
+class BatchResult(BaseModel):
+    """Result of a batch operation."""
+
+    succeeded: list[IssueRef] = Field(default_factory=lambda: list[IssueRef]())
+    failed: list[FailureDetail] = Field(default_factory=lambda: list[FailureDetail]())
+
+
+class PageContent(BaseModel):
+    """Full page content from documentation target."""
+
+    id: str = Field(..., description="Page ID")
+    title: str = Field(..., description="Page title")
+    content: str = Field(..., description="Page content (markdown)")
+    url: str = Field(default="", description="Web URL to the page")
+    space_key: str = Field(default="", description="Space key (e.g., 'DEV')")
+    version: int = Field(default=1, description="Page version number")
+
+
+class PageSummary(BaseModel):
+    """Compact page for search results. Timestamps use ISO 8601 format."""
+
+    id: str = Field(..., description="Page ID")
+    title: str = Field(..., description="Page title")
+    url: str = Field(default="", description="Web URL to the page")
+    space_key: str = Field(default="", description="Space key")
+    updated: str = Field(default="", description="ISO 8601 last update timestamp")
+
+
+class AdapterHealth(BaseModel):
+    """Health check result for an adapter."""
+
+    name: str = Field(..., description="Adapter name (e.g., 'jira')")
+    healthy: bool = Field(..., description="Whether the adapter is healthy")
+    message: str = Field(default="", description="Status or error message")
+    latency_ms: int | None = Field(
+        default=None, description="Response latency in milliseconds"
+    )
+
+
+# ---------------------------------------------------------------------------
+# YAML store models (S347.2 — FileAdapter parity)
+# ---------------------------------------------------------------------------
+
+
+class BacklogLink(BaseModel):
+    """Link from one backlog item to another."""
+
+    target: str = Field(..., description="Target issue key")
+    link_type: str = Field(..., description="Relationship type (blocks, depends_on, relates_to)")
+
+
+class BacklogComment(BaseModel):
+    """Comment embedded in a backlog item YAML file."""
+
+    id: str = Field(..., description="Comment ID ({KEY}-{N})")
+    body: str = Field(..., description="Comment body text")
+    author: str = Field(..., description="Author identifier")
+    created: str = Field(..., description="ISO 8601 creation timestamp")
+
+
+class BacklogItem(BaseModel):
+    """Single backlog item stored as .raise/backlog/items/{KEY}.yaml."""
+
+    key: str = Field(..., description="Issue key (E1, S1.1, etc.)")
+    summary: str = Field(..., description="Issue title")
+    issue_type: str = Field(..., description="Epic, Story, Task")
+    status: str = Field(..., description="pending, in_progress, complete")
+    parent: str | None = Field(default=None, description="Parent issue key")
+    description: str = Field(default="", description="Issue description")
+    labels: list[str] = Field(default_factory=list)
+    priority: str | None = Field(default=None, description="Priority level")
+    assignee: str | None = Field(default=None, description="Assignee identifier")
+    comments: list[BacklogComment] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    links: list[BacklogLink] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    created: str = Field(default="", description="ISO 8601 creation timestamp")
+    updated: str = Field(default="", description="ISO 8601 last update timestamp")
+
+
+# BackendHealth moved to raise_core.graph.backends.models (E275)

raise_cli/adapters/protocols.py

@@ -0,0 +1,180 @@
+"""Protocol contracts for raise-cli adapters.
+
+Defines the typed interfaces that adapter implementations must satisfy.
+All Protocols are ``@runtime_checkable`` for isinstance() checks.
+
+**Sync vs Async:**
+- ``AsyncProjectManagementAdapter`` / ``AsyncDocumentationTarget`` are the primary
+  protocols. Concrete adapters (JiraAdapter, ConfluenceTarget) implement these.
+- ``ProjectManagementAdapter`` / ``DocumentationTarget`` are the sync facades.
+  CLI commands consume these. Use ``SyncPMAdapter`` / ``SyncDocsAdapter`` wrappers
+  (from ``adapters.sync``) to bridge async adapters to sync consumption.
+
+Architecture: ADR-033 (PM), ADR-034 (Governance)
+Note: KnowledgeGraphBackend moved to raise_core.graph.backends.protocol (E275)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from raise_cli.adapters.models import (
+    AdapterHealth,
+    ArtifactLocator,
+    BatchResult,
+    Comment,
+    CommentRef,
+    IssueDetail,
+    IssueRef,
+    IssueSpec,
+    IssueSummary,
+    PageContent,
+    PageSummary,
+    PublishResult,
+)
+from raise_core.graph.models import GraphNode
+
+# ---------------------------------------------------------------------------
+# Sync protocols (CLI consumption)
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class ProjectManagementAdapter(Protocol):
+    """Sync PM adapter contract. CLI commands consume this.
+
+    For concrete adapters, implement ``AsyncProjectManagementAdapter`` and wrap
+    with ``SyncPMAdapter`` for CLI consumption.
+    """
+
+    # CRUD
+    def create_issue(self, project_key: str, issue: IssueSpec) -> IssueRef: ...
+
+    def get_issue(self, key: str) -> IssueDetail: ...
+
+    def update_issue(self, key: str, fields: dict[str, Any]) -> IssueRef: ...
+
+    def transition_issue(self, key: str, status: str) -> IssueRef: ...
+
+    # Batch
+    def batch_transition(self, keys: list[str], status: str) -> BatchResult: ...
+
+    # Relationships
+    def link_to_parent(self, child_key: str, parent_key: str) -> None: ...
+
+    def link_issues(self, source: str, target: str, link_type: str) -> None: ...
+
+    # Comments
+    def add_comment(self, key: str, body: str) -> CommentRef: ...
+
+    def get_comments(self, key: str, limit: int = 10) -> list[Comment]: ...
+
+    # Query — query is adapter-specific (JQL for Jira, etc.)
+    def search(self, query: str, limit: int = 50) -> list[IssueSummary]: ...
+
+    # Health
+    def health(self) -> AdapterHealth: ...
+
+
+@runtime_checkable
+class GovernanceSchemaProvider(Protocol):
+    """ADR-034: Declares what artifact types exist and where to find them.
+
+    Implementations: RaiSEDefaultSchema (built-in), OrgSchema (raise-pro).
+    """
+
+    def list_artifact_types(self) -> list[str]: ...
+
+    def locate(self, artifact_type: str) -> list[ArtifactLocator]: ...
+
+
+@runtime_checkable
+class GovernanceParser(Protocol):
+    """ADR-034: Parses a governance artifact into graph nodes.
+
+    Implementations: BacklogParser, AdrParser, etc. (S211.3 wraps existing).
+    """
+
+    def can_parse(self, locator: ArtifactLocator) -> bool: ...
+
+    def parse(self, locator: ArtifactLocator) -> list[GraphNode]: ...
+
+
+@runtime_checkable
+class DocumentationTarget(Protocol):
+    """Sync docs target contract. CLI commands consume this.
+
+    For concrete targets, implement ``AsyncDocumentationTarget`` and wrap
+    with ``SyncDocsAdapter`` for CLI consumption.
+    """
+
+    def can_publish(self, doc_type: str, metadata: dict[str, Any]) -> bool: ...
+
+    def publish(
+        self, doc_type: str, content: str, metadata: dict[str, Any]
+    ) -> PublishResult: ...
+
+    def get_page(self, identifier: str) -> PageContent: ...
+
+    def search(self, query: str, limit: int = 10) -> list[PageSummary]: ...
+
+    def health(self) -> AdapterHealth: ...
+
+
+# ---------------------------------------------------------------------------
+# Async protocols (adapter implementation target)
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class AsyncProjectManagementAdapter(Protocol):
+    """Async PM adapter contract. Concrete adapters implement this.
+
+    Consumed directly by async contexts (rai-server) or via ``SyncPMAdapter``
+    wrapper for CLI.
+    """
+
+    # CRUD
+    async def create_issue(self, project_key: str, issue: IssueSpec) -> IssueRef: ...
+
+    async def get_issue(self, key: str) -> IssueDetail: ...
+
+    async def update_issue(self, key: str, fields: dict[str, Any]) -> IssueRef: ...
+
+    async def transition_issue(self, key: str, status: str) -> IssueRef: ...
+
+    # Batch
+    async def batch_transition(self, keys: list[str], status: str) -> BatchResult: ...
+
+    # Relationships
+    async def link_to_parent(self, child_key: str, parent_key: str) -> None: ...
+
+    async def link_issues(self, source: str, target: str, link_type: str) -> None: ...
+
+    # Comments
+    async def add_comment(self, key: str, body: str) -> CommentRef: ...
+
+    async def get_comments(self, key: str, limit: int = 10) -> list[Comment]: ...
+
+    # Query — query is adapter-specific (JQL for Jira, etc.)
+    async def search(self, query: str, limit: int = 50) -> list[IssueSummary]: ...
+
+    # Health
+    async def health(self) -> AdapterHealth: ...
+
+
+@runtime_checkable
+class AsyncDocumentationTarget(Protocol):
+    """Async docs target contract. Concrete targets implement this."""
+
+    async def can_publish(self, doc_type: str, metadata: dict[str, Any]) -> bool: ...
+
+    async def publish(
+        self, doc_type: str, content: str, metadata: dict[str, Any]
+    ) -> PublishResult: ...
+
+    async def get_page(self, identifier: str) -> PageContent: ...
+
+    async def search(self, query: str, limit: int = 10) -> list[PageSummary]: ...
+
+    async def health(self) -> AdapterHealth: ...

raise_cli/adapters/registry.py

@@ -0,0 +1,90 @@
+"""Entry point registry for adapter discovery.
+
+Discovers adapter implementations registered via Python entry points
+(``[project.entry-points]`` in pyproject.toml). Each group maps to a
+Protocol contract from ``raise_cli.adapters.protocols``.
+
+Trust model: entry point loading inherits the ``pip install`` trust boundary.
+If a package is installed in the environment, its entry points are trusted.
+There is no allowlist or sandboxing — this is consistent with how pytest,
+stevedore, and the broader Python ecosystem handle plugin discovery.
+
+Architecture: ADR-033 (PM), ADR-034 (Governance), ADR-036 (Graph Backend)
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Entry point group names — stable contract for external packages.
+EP_PM_ADAPTERS: str = "rai.adapters.pm"
+EP_GOVERNANCE_SCHEMAS: str = "rai.governance.schemas"
+EP_GOVERNANCE_PARSERS: str = "rai.governance.parsers"
+EP_DOC_TARGETS: str = "rai.docs.targets"
+EP_GRAPH_BACKENDS: str = "rai.graph.backends"
+
+
+def _dist_name(ep: Any) -> str:
+    """Best-effort extraction of the distribution name that provides an entry point."""
+    try:
+        return ep.dist.name  # type: ignore[union-attr]
+    except AttributeError:
+        return "unknown"
+
+
+def _discover(group: str) -> dict[str, type]:
+    """Load all entry points for a group. Skips broken or non-class ones with warning."""
+    result: dict[str, type] = {}
+    for ep in entry_points(group=group):
+        try:
+            loaded: Any = ep.load()
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Skipping entry point '%s' from '%s' in group '%s': %s",
+                ep.name,
+                _dist_name(ep),
+                group,
+                exc,
+            )
+            continue
+        if not inspect.isclass(loaded):
+            logger.warning(
+                "Skipping entry point '%s' from '%s' in group '%s': expected a class, got %s",
+                ep.name,
+                _dist_name(ep),
+                group,
+                type(loaded).__name__,
+            )
+            continue
+        result[ep.name] = loaded
+    return result
+
+
+def get_pm_adapters() -> dict[str, type]:
+    """Discover ProjectManagementAdapter implementations."""
+    return _discover(EP_PM_ADAPTERS)
+
+
+def get_governance_schemas() -> dict[str, type]:
+    """Discover GovernanceSchemaProvider implementations."""
+    return _discover(EP_GOVERNANCE_SCHEMAS)
+
+
+def get_governance_parsers() -> dict[str, type]:
+    """Discover GovernanceParser implementations."""
+    return _discover(EP_GOVERNANCE_PARSERS)
+
+
+def get_doc_targets() -> dict[str, type]:
+    """Discover DocumentationTarget implementations."""
+    return _discover(EP_DOC_TARGETS)
+
+
+def get_graph_backends() -> dict[str, type]:
+    """Discover KnowledgeGraphBackend implementations."""
+    return _discover(EP_GRAPH_BACKENDS)

raise_cli/adapters/sync.py

@@ -0,0 +1,149 @@
+"""Sync wrappers for async adapter protocols.
+
+Bridges async adapters to sync consumption. Safe to call from both sync
+contexts (CLI) and async contexts (hooks, server) — uses a thread-based
+fallback when an event loop is already running.
+
+Usage::
+
+    from raise_cli.adapters.sync import SyncPMAdapter
+
+    async_adapter = JiraAdapter(config)
+    sync_adapter = SyncPMAdapter(async_adapter)
+    issue = sync_adapter.get_issue("RAISE-301")  # sync call
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+from collections.abc import Coroutine
+from typing import Any
+
+from raise_cli.adapters.models import (
+    AdapterHealth,
+    BatchResult,
+    Comment,
+    CommentRef,
+    IssueDetail,
+    IssueRef,
+    IssueSpec,
+    IssueSummary,
+    PageContent,
+    PageSummary,
+    PublishResult,
+)
+from raise_cli.adapters.protocols import (
+    AsyncDocumentationTarget,
+    AsyncProjectManagementAdapter,
+)
+
+
+def _run_sync[T](coro: Coroutine[Any, Any, T], closeable: Any = None) -> T:
+    """Run a coroutine synchronously, safe from both sync and async contexts.
+
+    - **No running loop:** uses ``asyncio.run()`` directly.
+    - **Loop already running:** runs ``asyncio.run()`` in a separate thread
+      so each thread gets its own event loop, avoiding the
+      ``RuntimeError: asyncio.run() cannot be called from a running event loop``.
+
+    Args:
+        coro: The coroutine to run.
+        closeable: Optional object with ``aclose()`` method. Called in a
+            ``finally`` block within the same event loop to prevent
+            asyncgen finalizer tracebacks (RAISE-324).
+    """
+
+    async def _wrapped() -> T:
+        try:
+            return await coro
+        finally:
+            if closeable is not None:
+                aclose = getattr(closeable, "aclose", None)
+                if aclose:
+                    await aclose()
+
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        # No loop running — safe to use asyncio.run()
+        return asyncio.run(_wrapped())
+    else:
+        # Loop already running — delegate to a thread with its own loop
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            future = pool.submit(asyncio.run, _wrapped())
+            return future.result()
+
+
+class SyncPMAdapter:
+    """Wraps ``AsyncProjectManagementAdapter`` for sync CLI consumption.
+
+    Satisfies ``ProjectManagementAdapter`` protocol via structural typing.
+    Each method delegates to the async adapter via ``_run_sync()``.
+    """
+
+    def __init__(self, async_adapter: AsyncProjectManagementAdapter) -> None:
+        self._adapter = async_adapter
+
+    def create_issue(self, project_key: str, issue: IssueSpec) -> IssueRef:
+        return _run_sync(self._adapter.create_issue(project_key, issue), self._adapter)
+
+    def get_issue(self, key: str) -> IssueDetail:
+        return _run_sync(self._adapter.get_issue(key), self._adapter)
+
+    def update_issue(self, key: str, fields: dict[str, Any]) -> IssueRef:
+        return _run_sync(self._adapter.update_issue(key, fields), self._adapter)
+
+    def transition_issue(self, key: str, status: str) -> IssueRef:
+        return _run_sync(self._adapter.transition_issue(key, status), self._adapter)
+
+    def batch_transition(self, keys: list[str], status: str) -> BatchResult:
+        return _run_sync(self._adapter.batch_transition(keys, status), self._adapter)
+
+    def link_to_parent(self, child_key: str, parent_key: str) -> None:
+        _run_sync(self._adapter.link_to_parent(child_key, parent_key), self._adapter)
+
+    def link_issues(self, source: str, target: str, link_type: str) -> None:
+        _run_sync(self._adapter.link_issues(source, target, link_type), self._adapter)
+
+    def add_comment(self, key: str, body: str) -> CommentRef:
+        return _run_sync(self._adapter.add_comment(key, body), self._adapter)
+
+    def get_comments(self, key: str, limit: int = 10) -> list[Comment]:
+        return _run_sync(self._adapter.get_comments(key, limit), self._adapter)
+
+    def search(self, query: str, limit: int = 50) -> list[IssueSummary]:
+        return _run_sync(self._adapter.search(query, limit), self._adapter)
+
+    def health(self) -> AdapterHealth:
+        return _run_sync(self._adapter.health(), self._adapter)
+
+
+class SyncDocsAdapter:
+    """Wraps ``AsyncDocumentationTarget`` for sync CLI consumption.
+
+    Satisfies ``DocumentationTarget`` protocol via structural typing.
+    Each method delegates to the async target via ``_run_sync()``.
+    """
+
+    def __init__(self, async_target: AsyncDocumentationTarget) -> None:
+        self._target = async_target
+
+    def can_publish(self, doc_type: str, metadata: dict[str, Any]) -> bool:
+        return _run_sync(self._target.can_publish(doc_type, metadata), self._target)
+
+    def publish(
+        self, doc_type: str, content: str, metadata: dict[str, Any]
+    ) -> PublishResult:
+        return _run_sync(
+            self._target.publish(doc_type, content, metadata), self._target
+        )
+
+    def get_page(self, identifier: str) -> PageContent:
+        return _run_sync(self._target.get_page(identifier), self._target)
+
+    def search(self, query: str, limit: int = 10) -> list[PageSummary]:
+        return _run_sync(self._target.search(query, limit), self._target)
+
+    def health(self) -> AdapterHealth:
+        return _run_sync(self._target.health(), self._target)

raise_cli/agents/__init__.py

@@ -0,0 +1,14 @@
+"""Built-in agent configuration package.
+
+Contains YAML config files for the 5 Tier-1 built-in agents:
+  - claude.yaml     (Claude Code)
+  - cursor.yaml     (Cursor 2.4+)
+  - windsurf.yaml   (Windsurf)
+  - copilot.yaml    (GitHub Copilot — has CopilotPlugin)
+  - antigravity.yaml (Antigravity)
+
+Usage:
+    from importlib.resources import files
+    agents_pkg = files("raise_cli.agents")
+    claude_yaml = (agents_pkg / "claude.yaml").read_text(encoding="utf-8")
+"""

raise_cli/agents/antigravity.yaml

@@ -0,0 +1,8 @@
+name: Antigravity
+agent_type: antigravity
+instructions_file: .agent/rules/raise.md
+skills_dir: .agent/skills
+workflows_dir: .agent/workflows
+detection_markers:
+  - .agent/rules
+  - .agent

raise_cli/agents/claude.yaml

@@ -0,0 +1,8 @@
+name: Claude Code
+agent_type: claude
+instructions_file: CLAUDE.md
+skills_dir: .claude/skills
+detection_markers:
+  - CLAUDE.md
+  - .claude
+  - ~/.claude

raise_cli/agents/copilot.yaml

@@ -0,0 +1,8 @@
+name: GitHub Copilot
+agent_type: copilot
+instructions_file: .github/copilot-instructions.md
+skills_dir: .github/agents
+workflows_dir: .github/prompts
+detection_markers:
+  - .github/copilot-instructions.md
+plugin: raise_cli.agents.copilot_plugin