raise-cli 2.2.1__py3-none-any.whl

raise_cli/cli/main.py

@@ -0,0 +1,163 @@
+"""Main CLI application entry point."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+import typer
+from rich.console import Console
+
+from raise_cli import __version__
+from raise_cli.cli.commands.adapters import adapters_app
+from raise_cli.cli.commands.artifact import artifact_app
+from raise_cli.cli.commands.backlog import backlog_app
+from raise_cli.cli.commands.base import base_app
+from raise_cli.cli.commands.discover import discover_app
+from raise_cli.cli.commands.docs import docs_app
+from raise_cli.cli.commands.doctor import doctor_app
+from raise_cli.cli.commands.gate import gate_app
+from raise_cli.cli.commands.graph import graph_app
+from raise_cli.cli.commands.info import info_command
+from raise_cli.cli.commands.init import init_command
+from raise_cli.cli.commands.mcp import mcp_app
+from raise_cli.cli.commands.memory import memory_app
+from raise_cli.cli.commands.pattern import pattern_app
+from raise_cli.cli.commands.profile import profile_app
+from raise_cli.cli.commands.publish import publish_app
+from raise_cli.cli.commands.release import release_app
+from raise_cli.cli.commands.session import session_app
+from raise_cli.cli.commands.signal import signal_app
+from raise_cli.cli.commands.skill import skill_app
+from raise_cli.config import RaiSettings
+
+# Module-level state for error handling
+_current_output_format: Literal["human", "json", "table"] = "human"
+
+
+def get_output_format() -> Literal["human", "json", "table"]:
+    """Get the current output format.
+
+    Returns:
+        The output format string ("human", "json", or "table").
+    """
+    return _current_output_format
+
+
+app = typer.Typer(
+    name="rai",
+    help="RaiSE CLI - Reliable AI Software Engineering",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Register command groups
+app.add_typer(adapters_app, name="adapter")
+app.add_typer(artifact_app, name="artifact")
+app.add_typer(backlog_app, name="backlog")
+app.add_typer(base_app, name="base")
+app.add_typer(docs_app, name="docs")
+app.add_typer(discover_app, name="discover")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(gate_app, name="gate")
+app.add_typer(graph_app, name="graph")
+app.add_typer(mcp_app, name="mcp")
+app.add_typer(memory_app, name="memory")
+app.add_typer(pattern_app, name="pattern")
+app.add_typer(profile_app, name="profile")
+app.add_typer(publish_app, name="publish")
+app.add_typer(release_app, name="release")
+app.add_typer(session_app, name="session")
+app.add_typer(signal_app, name="signal")
+app.add_typer(skill_app, name="skill")
+
+# Register standalone commands
+app.command("info")(info_command)
+app.command("init")(init_command)
+
+console = Console()
+
+
+class OutputFormat(StrEnum):
+    """Output format options."""
+
+    human = "human"
+    json = "json"
+    table = "table"
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        console.print(f"raise-cli version {__version__}")
+        raise typer.Exit(0)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=version_callback,
+            is_eager=True,
+            help="Show version and exit",
+        ),
+    ] = False,
+    format: Annotated[
+        OutputFormat,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format (human, json, table)",
+        ),
+    ] = OutputFormat.human,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Increase verbosity (-v, -vv, -vvv)",
+        ),
+    ] = 0,
+    quiet: Annotated[
+        bool,
+        typer.Option(
+            "--quiet",
+            "-q",
+            help="Suppress non-error output",
+        ),
+    ] = False,
+) -> None:
+    """RaiSE CLI - Reliable AI Software Engineering governance framework.
+
+    Global options apply to all commands and control output format and verbosity.
+    """
+    global _current_output_format  # noqa: PLW0603
+    _current_output_format = format.value  # type: ignore[assignment]
+
+    # Calculate verbosity from flags
+    verbosity = -1 if quiet else min(verbose, 3)
+
+    # Create settings with CLI overrides (highest priority)
+    settings = RaiSettings(
+        output_format=format.value,  # type: ignore[arg-type]
+        verbosity=verbosity,
+    )
+
+    # Store in context for subcommands
+    ctx.ensure_object(dict)
+    ctx.obj["settings"] = settings
+
+    # Backward compatibility: keep individual values in ctx.obj
+    # (Can be removed once all commands migrate to using settings)
+    ctx.obj["format"] = format.value
+    ctx.obj["verbosity"] = verbosity
+    ctx.obj["quiet"] = quiet
+
+
+if __name__ == "__main__":
+    app()

raise_cli/compat.py

@@ -0,0 +1,66 @@
+"""Cross-platform compatibility layer.
+
+Centralizes all platform-specific code so the rest of the codebase
+never checks sys.platform directly. Pattern used by pip, poetry, virtualenv.
+
+All platform guards live here. Import from compat, not from fcntl/msvcrt.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import IO
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+def file_lock(f: IO[str], *, exclusive: bool = True) -> None:
+    """Acquire a file lock. Uses fcntl on Unix, msvcrt on Windows."""
+    if sys.platform == "win32":
+        import msvcrt
+
+        msvcrt.locking(f.fileno(), msvcrt.LK_LOCK, 1)
+    else:
+        import fcntl
+
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
+
+
+def file_unlock(f: IO[str]) -> None:
+    """Release a file lock. Uses fcntl on Unix, msvcrt on Windows."""
+    if sys.platform == "win32":
+        import msvcrt
+
+        msvcrt.locking(f.fileno(), msvcrt.LK_UNLCK, 1)
+    else:
+        import fcntl
+
+        fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+
+
+def portable_path(path: Path, relative_to: Path) -> str:
+    """Return forward-slash relative path string for serialization.
+
+    Always uses forward slashes regardless of OS, ensuring consistent
+    path strings in JSON, graph data, and other serialized formats.
+    """
+    return path.relative_to(relative_to).as_posix()
+
+
+def to_file_uri(path: Path) -> str:
+    """Return correct file:// URI on any platform.
+
+    Uses pathlib's as_uri() which handles Windows drive letters correctly.
+    """
+    return path.resolve().as_uri()
+
+
+def secure_permissions(path: Path) -> None:
+    """Set restrictive file permissions (0o600). No-op on Windows.
+
+    On Windows, POSIX chmod has no effect. For true Windows ACL
+    restriction, icacls would be needed — deferred until required.
+    """
+    if not IS_WINDOWS:
+        path.chmod(0o600)

raise_cli/config/__init__.py

@@ -0,0 +1,41 @@
+"""Configuration module for raise-cli.
+
+Provides configuration settings and XDG-compliant directory helpers.
+"""
+
+from __future__ import annotations
+
+from raise_cli.config.agents import (
+    BUILTIN_AGENTS,
+    AgentChoice,
+    AgentConfig,
+    BuiltinAgentType,
+    get_agent_config,
+)
+from raise_cli.config.paths import get_cache_dir, get_config_dir, get_data_dir
+from raise_cli.config.settings import RaiSettings
+
+# Backward-compat aliases
+IDE_CONFIGS = BUILTIN_AGENTS
+IdeChoice = AgentChoice
+IdeConfig = AgentConfig
+IdeType = BuiltinAgentType
+get_ide_config = get_agent_config
+
+__all__ = [
+    "BUILTIN_AGENTS",
+    "AgentChoice",
+    "AgentConfig",
+    "BuiltinAgentType",
+    "get_agent_config",
+    # Backward-compat
+    "IDE_CONFIGS",
+    "IdeChoice",
+    "IdeConfig",
+    "IdeType",
+    "get_ide_config",
+    "get_cache_dir",
+    "get_config_dir",
+    "get_data_dir",
+    "RaiSettings",
+]

raise_cli/config/agent_plugin.py

@@ -0,0 +1,105 @@
+"""AgentPlugin protocol and default implementation.
+
+Defines the extensibility interface for agent-specific transformations.
+Plugins can transform instructions, skills, and run post-init hooks.
+
+Architecture: ADR-032 (Multi-agent skill distribution).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from raise_cli.config.agents import AgentConfig
+
+
+@runtime_checkable
+class AgentPlugin(Protocol):
+    """Protocol for custom agent connectors.
+
+    Implementors add agent-specific transformation logic without modifying
+    the raise-cli engine. A plugin only needs to implement the methods it uses —
+    duck typing, no forced inheritance.
+
+    Example (minimal plugin):
+        class MyPlugin:
+            def transform_instructions(self, content, config):
+                return f"<!-- {config.name} -->\\n{content}"
+
+            def transform_skill(self, frontmatter, body, config):
+                return frontmatter, body
+
+            def post_init(self, project_root, config):
+                return []
+    """
+
+    def transform_instructions(self, content: str, config: AgentConfig) -> str:
+        """Transform generated instructions for this target.
+
+        Called after the instructions content is generated, before writing to disk.
+        Default: pass-through (return content unchanged).
+
+        Args:
+            content: Generated markdown instructions content.
+            config: Target agent configuration.
+
+        Returns:
+            Transformed content string.
+        """
+        ...
+
+    def transform_skill(
+        self, frontmatter: dict[str, Any], body: str, config: AgentConfig
+    ) -> tuple[dict[str, Any], str]:
+        """Transform a SKILL.md for this target.
+
+        Called for each skill file during scaffolding.
+        Default: pass-through (return unchanged).
+
+        Args:
+            frontmatter: Parsed YAML frontmatter dict.
+            body: Skill body markdown text.
+            config: Target agent configuration.
+
+        Returns:
+            Tuple of (transformed_frontmatter, transformed_body).
+        """
+        ...
+
+    def post_init(self, project_root: Path, config: AgentConfig) -> list[str]:
+        """Run after all files are generated.
+
+        Called once at the end of `rai init` for this agent.
+        Default: no-op (return empty list).
+
+        Args:
+            project_root: Project root directory.
+            config: Target agent configuration.
+
+        Returns:
+            List of file paths created by this hook.
+        """
+        ...
+
+
+class DefaultAgentPlugin:
+    """Default no-op plugin used when no plugin is specified.
+
+    All methods are pass-through — skills and instructions are copied
+    as-is with no transformation. Four of five built-in agents use this.
+    """
+
+    def transform_instructions(self, content: str, config: AgentConfig) -> str:
+        """Return content unchanged."""
+        return content
+
+    def transform_skill(
+        self, frontmatter: dict[str, Any], body: str, config: AgentConfig
+    ) -> tuple[dict[str, Any], str]:
+        """Return frontmatter and body unchanged (copies, not references)."""
+        return dict(frontmatter), body
+
+    def post_init(self, project_root: Path, config: AgentConfig) -> list[str]:
+        """No-op — return empty list."""
+        return []

raise_cli/config/agent_registry.py

@@ -0,0 +1,233 @@
+"""Agent registry — 3-tier YAML loading with override precedence.
+
+Loads agent configurations from:
+  1. Built-in YAML files (bundled in raise_cli.agents package)
+  2. Project-level .raise/agents/*.yaml
+  3. User-level ~/.rai/agents/*.yaml
+
+Last-wins precedence: user > project > built-in.
+
+Architecture: ADR-032 (Multi-agent skill distribution).
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from raise_cli.config.agent_plugin import AgentPlugin, DefaultAgentPlugin
+from raise_cli.config.agents import AgentConfig
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_PLUGIN = DefaultAgentPlugin()
+
+
+def _parse_agent_config(data: dict[str, Any]) -> AgentConfig:
+    """Parse a YAML dict into an AgentConfig model."""
+    return AgentConfig(
+        name=data["name"],
+        agent_type=data["agent_type"],
+        instructions_file=data["instructions_file"],
+        skills_dir=data.get("skills_dir"),
+        workflows_dir=data.get("workflows_dir"),
+        detection_markers=data.get("detection_markers", []),
+        plugin=data.get("plugin"),
+    )
+
+
+def _load_yaml_dir(directory: Path) -> dict[str, AgentConfig]:
+    """Load all *.yaml files from a directory into agent configs."""
+    configs: dict[str, AgentConfig] = {}
+    if not directory.exists():
+        return configs
+    for yaml_file in sorted(directory.glob("*.yaml")):
+        try:
+            raw = yaml.safe_load(yaml_file.read_text(encoding="utf-8"))
+            if not isinstance(raw, dict):
+                logger.warning("Skipping %s: not a YAML mapping", yaml_file)
+                continue
+            config = _parse_agent_config(cast(dict[str, Any], raw))
+            configs[config.agent_type] = config
+        except (yaml.YAMLError, KeyError, TypeError, ValueError) as e:
+            logger.warning("Skipping %s: %s", yaml_file, e)
+    return configs
+
+
+def _load_builtin_agents() -> dict[str, AgentConfig]:
+    """Load agent configs from the bundled raise_cli.agents package."""
+    configs: dict[str, AgentConfig] = {}
+    agents_pkg = files("raise_cli.agents")
+    for entry in agents_pkg.iterdir():
+        if not entry.name.endswith(".yaml"):
+            continue
+        try:
+            raw = yaml.safe_load(entry.read_text(encoding="utf-8"))
+            if not isinstance(raw, dict):
+                logger.warning("Skipping built-in %s: not a YAML mapping", entry.name)
+                continue
+            config = _parse_agent_config(cast(dict[str, Any], raw))
+            configs[config.agent_type] = config
+        except (yaml.YAMLError, KeyError, TypeError, ValueError) as e:
+            logger.warning("Skipping built-in %s: %s", entry.name, e)
+    return configs
+
+
+def _resolve_plugin(plugin_path: str | None) -> AgentPlugin:
+    """Resolve a plugin module path string to an AgentPlugin instance.
+
+    Expects the module to contain a class with the same name as the last
+    segment of the module path (PascalCase), or a class named 'Plugin'.
+
+    Args:
+        plugin_path: Module path like "raise_cli.agents.copilot_plugin",
+                     or None for default pass-through.
+
+    Returns:
+        AgentPlugin instance.
+    """
+    if not plugin_path:
+        return _DEFAULT_PLUGIN
+
+    try:
+        module = importlib.import_module(plugin_path)
+    except ImportError as e:
+        logger.warning("Could not import plugin %r: %s — using default", plugin_path, e)
+        return _DEFAULT_PLUGIN
+
+    # Convention: look for class named Plugin, or derive from module name
+    # e.g. "copilot_plugin" → "CopilotPlugin"
+    segments = plugin_path.split(".")
+    module_name = segments[-1]  # e.g. "copilot_plugin"
+    class_name = "".join(part.capitalize() for part in module_name.split("_"))
+    # e.g. "CopilotPlugin"
+
+    cls = getattr(module, class_name, None) or getattr(module, "Plugin", None)
+    if cls is None:
+        logger.warning(
+            "Plugin module %r has no class %r or 'Plugin' — using default",
+            plugin_path,
+            class_name,
+        )
+        return _DEFAULT_PLUGIN
+
+    try:
+        return cls()
+    except Exception as e:
+        logger.warning(
+            "Could not instantiate %r from %r: %s", class_name, plugin_path, e
+        )
+        return _DEFAULT_PLUGIN
+
+
+class AgentRegistry:
+    """Registry of agent configurations loaded from 3-tier YAML sources.
+
+    Provides config and plugin lookup by agent_type key.
+    """
+
+    def __init__(self, configs: dict[str, AgentConfig]) -> None:
+        self._configs = configs
+        self._plugins: dict[str, AgentPlugin] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_config(self, agent_type: str) -> AgentConfig:
+        """Return AgentConfig for the given agent_type.
+
+        Raises:
+            KeyError: If agent_type is not registered.
+        """
+        return self._configs[agent_type]
+
+    def get_plugin(self, agent_type: str) -> AgentPlugin:
+        """Return AgentPlugin for the given agent_type (cached after first call).
+
+        Falls back to DefaultAgentPlugin if no plugin specified or load fails.
+
+        Raises:
+            KeyError: If agent_type is not registered.
+        """
+        if agent_type not in self._configs:
+            raise KeyError(agent_type)
+        if agent_type not in self._plugins:
+            config = self._configs[agent_type]
+            self._plugins[agent_type] = _resolve_plugin(config.plugin)
+        return self._plugins[agent_type]
+
+    def list_agents(self) -> list[str]:
+        """Return sorted list of all registered agent_type keys."""
+        return sorted(self._configs.keys())
+
+    def detect_agents(
+        self, project_root: Path, user_home: Path | None = None
+    ) -> list[str]:
+        """Detect which registered agents have marker files in project_root.
+
+        Checks each agent's detection_markers list; stops at first match per
+        agent. Markers starting with ``~/`` are resolved against user_home
+        (defaults to Path.home()) instead of project_root.
+
+        Args:
+            project_root: Directory to check for project-relative marker paths.
+            user_home: Home directory for ``~/`` markers (defaults to Path.home()).
+
+        Returns:
+            Sorted list of detected agent_type strings.
+        """
+        home = user_home if user_home is not None else Path.home()
+        detected: list[str] = []
+        for agent_type, config in self._configs.items():
+            for marker in config.detection_markers:
+                if marker.startswith("~/"):
+                    check_path = home / marker[2:]
+                else:
+                    check_path = project_root / marker
+                if check_path.exists():
+                    detected.append(agent_type)
+                    break
+        return sorted(detected)
+
+
+def load_registry(
+    project_root: Path | None = None,
+    user_home: Path | None = None,
+) -> AgentRegistry:
+    """Load the 3-tier agent registry.
+
+    Loading order (last-wins):
+    1. Built-in YAML files bundled in raise_cli.agents package
+    2. Project-level .raise/agents/*.yaml (if project_root provided)
+    3. User-level ~/.rai/agents/*.yaml (if user_home provided; defaults to Path.home())
+
+    Args:
+        project_root: Project root directory for .raise/agents/ lookup.
+        user_home: Home directory for ~/.rai/agents/ lookup.
+                   Defaults to Path.home() if not provided.
+
+    Returns:
+        AgentRegistry populated with merged configs.
+    """
+    # Tier 1: built-in
+    configs: dict[str, AgentConfig] = _load_builtin_agents()
+
+    # Tier 2: project-level
+    if project_root is not None:
+        project_agents_dir = project_root / ".raise" / "agents"
+        project_configs = _load_yaml_dir(project_agents_dir)
+        configs.update(project_configs)
+
+    # Tier 3: user-level
+    home = user_home if user_home is not None else Path.home()
+    user_agents_dir = home / ".rai" / "agents"
+    user_configs = _load_yaml_dir(user_agents_dir)
+    configs.update(user_configs)
+
+    return AgentRegistry(configs)