raise-cli 2.2.1__py3-none-any.whl

raise_cli/config/agents.py

@@ -0,0 +1,120 @@
+"""Agent configuration model and factory.
+
+Defines agent-specific conventions (paths, file names) as data.
+Each supported agent has a pre-built AgentConfig in the registry.
+Factory function returns the config for a given agent type.
+
+Replaces the IDE-specific model from ADR-031 with a generic agent abstraction.
+Architecture decision: ADR-032 (Multi-agent skill distribution).
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+BuiltinAgentType = Literal[
+    "claude", "cursor", "windsurf", "copilot", "antigravity", "roo"
+]
+
+
+class AgentChoice(StrEnum):
+    """Typer-compatible enum for --agent CLI option."""
+
+    claude = "claude"
+    cursor = "cursor"
+    windsurf = "windsurf"
+    copilot = "copilot"
+    antigravity = "antigravity"
+    roo = "roo"
+
+
+class AgentConfig(BaseModel):
+    """Configuration for a target agent/IDE/CLI.
+
+    Attributes:
+        name: Display name for this agent.
+        agent_type: Registry key (e.g. "claude", "codex-cli", "azure-devops").
+        instructions_file: Relative path to instructions/rules file from project root.
+        skills_dir: Relative path to skills directory (None if agent has no skills support).
+        workflows_dir: Relative path to workflows directory (None if agent has no equivalent).
+        detection_markers: Paths to check for presence during auto-detection.
+        plugin: Python module path for custom logic (None for default pass-through).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str
+    agent_type: str
+    instructions_file: str
+    skills_dir: str | None = None
+    workflows_dir: str | None = None
+    detection_markers: list[str] = Field(default_factory=list)
+    plugin: str | None = None
+
+
+BUILTIN_AGENTS: dict[BuiltinAgentType, AgentConfig] = {
+    "claude": AgentConfig(
+        name="Claude Code",
+        agent_type="claude",
+        skills_dir=".claude/skills",
+        instructions_file="CLAUDE.md",
+        detection_markers=["CLAUDE.md", ".claude"],
+    ),
+    "cursor": AgentConfig(
+        name="Cursor",
+        agent_type="cursor",
+        skills_dir=".cursor/skills",
+        instructions_file=".cursor/rules/raise.mdc",
+        detection_markers=[".cursor/rules", ".cursor"],
+    ),
+    "windsurf": AgentConfig(
+        name="Windsurf",
+        agent_type="windsurf",
+        skills_dir=".windsurf/skills",
+        instructions_file=".windsurf/rules/raise.md",
+        workflows_dir=".windsurf/workflows",
+        detection_markers=[".windsurf/rules", ".windsurf"],
+    ),
+    "copilot": AgentConfig(
+        name="GitHub Copilot",
+        agent_type="copilot",
+        skills_dir=".github/agents",
+        instructions_file=".github/copilot-instructions.md",
+        workflows_dir=".github/prompts",
+        detection_markers=[".github/copilot-instructions.md"],
+        plugin="raise_cli.agents.copilot_plugin",
+    ),
+    "antigravity": AgentConfig(
+        name="Antigravity",
+        agent_type="antigravity",
+        skills_dir=".agent/skills",
+        instructions_file=".agent/rules/raise.md",
+        workflows_dir=".agent/workflows",
+        detection_markers=[".agent/rules", ".agent"],
+    ),
+    "roo": AgentConfig(
+        name="Roo Code",
+        agent_type="roo",
+        skills_dir=".roo/skills",
+        instructions_file=".roo/rules/raise.md",
+        detection_markers=[".roo/rules", ".roo", ".rooignore"],
+    ),
+}
+
+
+def get_agent_config(agent_type: BuiltinAgentType = "claude") -> AgentConfig:
+    """Get the agent configuration for a given agent type.
+
+    Args:
+        agent_type: The agent to get config for. Defaults to "claude".
+
+    Returns:
+        AgentConfig with paths and conventions for the requested agent.
+
+    Raises:
+        KeyError: If agent_type is not in the built-in registry.
+    """
+    return BUILTIN_AGENTS[agent_type]

raise_cli/config/ide.py

@@ -0,0 +1,32 @@
+"""Backward-compatibility shim for IDE configuration.
+
+All types have been moved to raise_cli.config.agents.
+This module re-exports old names for external consumers.
+
+Migration: IdeConfig → AgentConfig, IdeType → BuiltinAgentType,
+IdeChoice → AgentChoice, IDE_CONFIGS → BUILTIN_AGENTS,
+get_ide_config → get_agent_config.
+"""
+
+from raise_cli.config.agents import (
+    BUILTIN_AGENTS as BUILTIN_AGENTS,
+)
+from raise_cli.config.agents import (
+    AgentChoice as AgentChoice,
+)
+from raise_cli.config.agents import (
+    AgentConfig as AgentConfig,
+)
+from raise_cli.config.agents import (
+    BuiltinAgentType as BuiltinAgentType,
+)
+from raise_cli.config.agents import (
+    get_agent_config as get_agent_config,
+)
+
+# Backward-compat aliases
+IdeConfig = AgentConfig
+IdeType = BuiltinAgentType
+IdeChoice = AgentChoice
+IDE_CONFIGS = BUILTIN_AGENTS
+get_ide_config = get_agent_config

raise_cli/config/paths.py

@@ -0,0 +1,379 @@
+"""Path helpers for raise-cli.
+
+Includes:
+- XDG Base Directory paths (global user config/cache/data)
+- Per-project directory structure constants
+
+Directory Structure (per-project):
+    .raise/                    # RaiSE framework presence
+    ├── manifest.yaml          # Project metadata
+    ├── config.yaml            # Project configuration
+    ├── graph/                 # Context graph cache
+    └── rai/                   # AI partner state
+        ├── identity/          # Rai's identity
+        ├── memory/            # Patterns, calibration, graph (shared, committed)
+        └── personal/          # Sessions, telemetry (per-developer, gitignored)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# =============================================================================
+# Per-Project Directory Constants
+# =============================================================================
+
+# Root directory for RaiSE in a project
+RAISE_PROJECT_DIR = ".raise"
+
+# Subdirectory for Rai (AI partner) state within .raise/
+RAI_SUBDIR = "rai"
+
+# Common subdirectories
+MEMORY_SUBDIR = "memory"
+TELEMETRY_SUBDIR = "telemetry"
+IDENTITY_SUBDIR = "identity"
+GRAPH_SUBDIR = "graph"
+FRAMEWORK_SUBDIR = "framework"
+MANIFESTS_SUBDIR = "manifests"
+
+# File names
+SKILLS_MANIFEST_FILE = "skills.json"
+MANIFEST_FILE = "manifest.yaml"
+CONFIG_FILE = "config.yaml"
+PATTERNS_FILE = "patterns.jsonl"
+CALIBRATION_FILE = "calibration.jsonl"
+SESSIONS_DIR = "sessions"
+SIGNALS_FILE = "signals.jsonl"
+
+
+def get_raise_dir(project_root: Path | None = None) -> Path:
+    """Get the .raise/ directory for a project.
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to .raise/ directory.
+    """
+    root = project_root or Path.cwd()
+    return root / RAISE_PROJECT_DIR
+
+
+def get_rai_dir(project_root: Path | None = None) -> Path:
+    """Get the .raise/rai/ directory for AI partner state.
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to .raise/rai/ directory.
+    """
+    return get_raise_dir(project_root) / RAI_SUBDIR
+
+
+def get_memory_dir(project_root: Path | None = None) -> Path:
+    """Get the .raise/rai/memory/ directory.
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to memory directory.
+    """
+    return get_rai_dir(project_root) / MEMORY_SUBDIR
+
+
+def get_telemetry_dir(project_root: Path | None = None) -> Path:
+    """Get the .raise/rai/personal/telemetry/ directory.
+
+    Telemetry is personal data (developer-specific, gitignored).
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to telemetry directory.
+    """
+    return get_personal_dir(project_root) / TELEMETRY_SUBDIR
+
+
+def get_identity_dir(project_root: Path | None = None) -> Path:
+    """Get the .raise/rai/identity/ directory.
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to identity directory.
+    """
+    return get_rai_dir(project_root) / IDENTITY_SUBDIR
+
+
+def get_framework_dir(project_root: Path | None = None) -> Path:
+    """Get the .raise/rai/framework/ directory.
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to framework directory.
+    """
+    return get_rai_dir(project_root) / FRAMEWORK_SUBDIR
+
+
+def get_graph_dir(project_root: Path | None = None) -> Path:
+    """Get the memory index directory (.raise/rai/memory/).
+
+    The "graph" is an implementation detail — it's really memory indexing.
+    This function returns the memory directory where index.json lives.
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to memory directory (contains index.json).
+    """
+    return get_memory_dir(project_root)
+
+
+# =============================================================================
+# Global User Directory (XDG)
+# =============================================================================
+
+# Global Rai directory in user home (for developer profile)
+GLOBAL_RAI_DIR = ".rai"
+
+# Personal subdirectory (gitignored, per-developer within project)
+PERSONAL_SUBDIR = "personal"
+
+
+def _sanitize_env_path(raw: str, var_name: str) -> Path:
+    """Sanitize a path read from an environment variable (CWE-23).
+
+    Validates that the raw value does not contain ``..`` path components
+    (before resolution) and that the resolved result is absolute.
+
+    Args:
+        raw: Raw environment variable value.
+        var_name: Variable name (for error messages).
+
+    Returns:
+        Resolved, absolute ``Path``.
+
+    Raises:
+        ValueError: If the path contains traversal components or is not absolute.
+    """
+    if ".." in raw.split(os.sep):
+        msg = f"${var_name} must not contain '..' path components: {raw}"
+        raise ValueError(msg)
+    resolved = Path(raw).resolve()
+    if not resolved.is_absolute():
+        msg = f"${var_name} must resolve to an absolute path: {raw}"
+        raise ValueError(msg)
+    return resolved
+
+
+def get_global_rai_dir() -> Path:
+    """Get the global ~/.rai directory for cross-repo Rai state.
+
+    This directory stores:
+    - developer.yaml (identity, already exists)
+    - patterns.jsonl (universal patterns, NEW)
+    - calibration.jsonl (global calibration, NEW)
+
+    Can be overridden with RAI_HOME environment variable.
+
+    Returns:
+        Path to global Rai directory (e.g., ~/.rai or $RAI_HOME)
+
+    Raises:
+        ValueError: If RAI_HOME contains path-traversal components.
+
+    Example:
+        >>> global_dir = get_global_rai_dir()
+        >>> patterns_file = global_dir / "patterns.jsonl"
+    """
+    rai_home = os.environ.get("RAI_HOME")
+    if rai_home:
+        return _sanitize_env_path(rai_home, "RAI_HOME")
+    return Path.home() / GLOBAL_RAI_DIR
+
+
+def ensure_global_rai_dir() -> Path:
+    """Ensure the global ~/.rai directory exists with required files.
+
+    Creates:
+    - ~/.rai/ directory (if not exists)
+    - ~/.rai/patterns.jsonl (empty, if not exists)
+    - ~/.rai/calibration.jsonl (empty, if not exists)
+
+    Does NOT overwrite existing files.
+
+    Returns:
+        Path to global Rai directory.
+
+    Example:
+        >>> global_dir = ensure_global_rai_dir()
+        >>> # Now safe to write patterns to global_dir / "patterns.jsonl"
+    """
+    global_dir = get_global_rai_dir()
+    global_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create empty JSONL files if they don't exist
+    patterns_file = global_dir / PATTERNS_FILE
+    if not patterns_file.exists():
+        patterns_file.touch()
+
+    calibration_file = global_dir / CALIBRATION_FILE
+    if not calibration_file.exists():
+        calibration_file.touch()
+
+    return global_dir
+
+
+def get_credentials_path() -> Path:
+    """Get path to encrypted credentials file for external providers.
+
+    Returns path to ~/.rai/credentials.json which stores OAuth tokens
+    for external providers (JIRA, GitLab, etc.) with Fernet encryption.
+
+    The file is created with user-only permissions (0600) when first written.
+
+    Returns:
+        Path to credentials file (e.g., ~/.rai/credentials.json).
+
+    Example:
+        >>> creds_path = get_credentials_path()
+        >>> # Use with rai_pro.providers.auth.credentials.store_token()
+    """
+    return get_global_rai_dir() / "credentials.json"
+
+
+def get_session_dir(session_id: str, project_root: Path | None = None) -> Path:
+    """Get the per-session directory for isolated session state.
+
+    Each session instance gets its own directory containing:
+    - state.yaml (session working state)
+    - signals.jsonl (session telemetry)
+
+    Args:
+        session_id: Session identifier (e.g., "SES-177").
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to per-session directory (e.g., .raise/rai/personal/sessions/SES-177/)
+    """
+    sessions_base = (get_personal_dir(project_root) / SESSIONS_DIR).resolve()
+    session_path = (sessions_base / session_id).resolve()
+    if not session_path.is_relative_to(sessions_base):
+        raise ValueError(f"Invalid session_id — path traversal detected: {session_id!r}")
+    return session_path
+
+
+def get_personal_dir(project_root: Path | None = None) -> Path:
+    """Get the personal directory for developer-specific project data.
+
+    This directory is gitignored and stores:
+    - sessions/index.jsonl (my sessions)
+    - telemetry/signals.jsonl (my telemetry)
+    - calibration.jsonl (project-specific calibration)
+    - patterns.jsonl (project-specific learnings)
+
+    Args:
+        project_root: Project root path. Defaults to current directory.
+
+    Returns:
+        Path to personal directory (e.g., .raise/rai/personal/)
+
+    Example:
+        >>> personal_dir = get_personal_dir()
+        >>> my_sessions = personal_dir / "sessions" / "index.jsonl"
+    """
+    return get_rai_dir(project_root) / PERSONAL_SUBDIR
+
+
+def get_claude_memory_path(project_root: Path) -> Path:
+    """Get the Claude Code MEMORY.md path for a project.
+
+    Claude Code stores per-project memory at:
+        ~/.claude/projects/{encoded_path}/memory/MEMORY.md
+
+    Where {encoded_path} replaces '/' with '-' and prepends '-'.
+    This is the first IDE-specific path helper — future IDEs
+    (Cursor, Windsurf, etc.) will have sibling functions.
+
+    Args:
+        project_root: Absolute path to the project root.
+
+    Returns:
+        Path to the Claude Code MEMORY.md file.
+
+    Example:
+        >>> get_claude_memory_path(Path("/home/user/Code/my-project"))
+        PosixPath('/home/user/.claude/projects/-home-user-Code-my-project/memory/MEMORY.md')
+    """
+    # Claude Code convention: replace path separators with -, prepend -
+    # Must handle both Unix (/) and Windows (\) separators
+    path_str = str(project_root)
+    # Normalize Windows backslashes to forward slashes
+    path_str = path_str.replace("\\", "/")
+    # Remove drive letter colon on Windows (C:/Users -> C/Users)
+    path_str = path_str.replace(":", "")
+    encoded = path_str.replace("/", "-")
+    return Path.home() / ".claude" / "projects" / encoded / "memory" / "MEMORY.md"
+
+
+def _get_xdg_dir(env_var: str, fallback: str) -> Path:
+    """Get an XDG directory for raise-cli.
+
+    Args:
+        env_var: XDG environment variable name (e.g., "XDG_CONFIG_HOME").
+        fallback: Fallback path relative to home (e.g., ".config").
+
+    Returns:
+        Path to the rai subdirectory within the XDG directory.
+    """
+    xdg_value = os.environ.get(env_var)
+    base = _sanitize_env_path(xdg_value, env_var) if xdg_value else Path.home() / fallback
+    return base / "rai"
+
+
+def get_config_dir() -> Path:
+    """Get the XDG config directory for raise-cli.
+
+    Returns:
+        Path to config directory (e.g., ~/.config/rai/ or $XDG_CONFIG_HOME/rai/)
+
+    Example:
+        >>> config_dir = get_config_dir()
+        >>> config_file = config_dir / "config.toml"
+    """
+    return _get_xdg_dir("XDG_CONFIG_HOME", ".config")
+
+
+def get_cache_dir() -> Path:
+    """Get the XDG cache directory for raise-cli.
+
+    Returns:
+        Path to cache directory (e.g., ~/.cache/rai/ or $XDG_CACHE_HOME/rai/)
+
+    Example:
+        >>> cache_dir = get_cache_dir()
+        >>> cache_file = cache_dir / "downloaded_katas.json"
+    """
+    return _get_xdg_dir("XDG_CACHE_HOME", ".cache")
+
+
+def get_data_dir() -> Path:
+    """Get the XDG data directory for raise-cli.
+
+    Returns:
+        Path to data directory (e.g., ~/.local/share/rai/ or $XDG_DATA_HOME/rai/)
+
+    Example:
+        >>> data_dir = get_data_dir()
+        >>> state_file = data_dir / "session_state.json"
+    """
+    return _get_xdg_dir("XDG_DATA_HOME", ".local/share")