superqode 0.1.5__py3-none-any.whl

superqode/core/roles.py

@@ -0,0 +1,281 @@
+"""
+Unified Role Definitions for SuperQode.
+
+Provides a single interface for all role types across the platform:
+- dev: Development roles (fullstack, frontend, backend, etc.)
+- qe: Quality Engineering roles (smoke, regression, security, etc.)
+- devops: DevOps roles (deployment, infrastructure, monitoring)
+
+Each role can operate in either BYOK or ACP mode.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Literal, Optional, Any
+
+from ..__init__ import __version__
+
+
+class RoleCategory(Enum):
+    """Role category (top-level grouping)."""
+
+    DEV = "dev"
+    QE = "qe"
+    DEVOPS = "devops"
+
+
+class QERoleType(Enum):
+    """Type of QE role."""
+
+    EXECUTION = "execution"  # Runs existing tests (smoke, sanity, regression)
+    DETECTION = "detection"  # Proactive issue detection (security, api, e2e)
+
+
+@dataclass
+class Role:
+    """
+    Unified role definition.
+
+    Represents a role in the SuperQode system, whether it's a development,
+    QE, or DevOps role. Each role can operate in BYOK or ACP mode.
+    """
+
+    category: RoleCategory
+    name: str
+    description: str
+    job_description: str = ""
+
+    # Execution mode
+    mode: Literal["byok", "acp"] = "byok"
+
+    # BYOK settings
+    provider: Optional[str] = None
+    model: Optional[str] = None
+
+    # ACP settings
+    agent: Optional[str] = None
+
+    # QE-specific
+    qe_type: Optional[QERoleType] = None
+
+    # Common settings
+    enabled: bool = True
+    mcp_servers: List[str] = field(default_factory=list)
+
+    @property
+    def display_name(self) -> str:
+        """Get display name like 'dev.fullstack'."""
+        return f"{self.category.value}.{self.name}"
+
+    @property
+    def command(self) -> str:
+        """Get TUI command like ':<mode> <role>'."""
+        return f":{self.category.value} {self.name}"
+
+    @property
+    def is_byok(self) -> bool:
+        """Check if role uses BYOK mode."""
+        return self.mode == "byok"
+
+    @property
+    def is_acp(self) -> bool:
+        """Check if role uses ACP mode."""
+        return self.mode == "acp"
+
+    @property
+    def is_execution_role(self) -> bool:
+        """Check if this is an execution QE role."""
+        return self.qe_type == QERoleType.EXECUTION
+
+    @property
+    def is_detection_role(self) -> bool:
+        """Check if this is a detection QE role."""
+        return self.qe_type == QERoleType.DETECTION
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        result = {
+            "category": self.category.value,
+            "name": self.name,
+            "display_name": self.display_name,
+            "description": self.description,
+            "job_description": self.job_description,
+            "mode": self.mode,
+            "enabled": self.enabled,
+        }
+
+        if self.mode == "byok":
+            result["provider"] = self.provider
+            result["model"] = self.model
+        else:
+            result["agent"] = self.agent
+
+        if self.qe_type:
+            result["qe_type"] = self.qe_type.value
+
+        if self.mcp_servers:
+            result["mcp_servers"] = self.mcp_servers
+
+        return result
+
+
+# =============================================================================
+# Default Role Definitions
+# =============================================================================
+
+DEFAULT_DEV_ROLES = {
+    "fullstack": Role(
+        category=RoleCategory.DEV,
+        name="fullstack",
+        description="Full-stack development",
+        job_description="Implement features, fix bugs, refactor code across the entire stack",
+        mode="acp",
+        agent="claude-code",
+    ),
+    "frontend": Role(
+        category=RoleCategory.DEV,
+        name="frontend",
+        description="Frontend/UI specialist",
+        job_description="Build and maintain user interfaces, ensure great UX",
+        mode="acp",
+        agent="claude-code",
+    ),
+    "backend": Role(
+        category=RoleCategory.DEV,
+        name="backend",
+        description="Backend/API specialist",
+        job_description="Design and implement APIs, services, and data layers",
+        mode="acp",
+        agent="claude-code",
+    ),
+}
+
+DEFAULT_QE_ROLES = {
+    "smoke": Role(
+        category=RoleCategory.QE,
+        name="smoke",
+        description="Fast critical path validation",
+        job_description="Run smoke tests to validate critical paths work",
+        mode="byok",
+        qe_type=QERoleType.EXECUTION,
+    ),
+    "sanity": Role(
+        category=RoleCategory.QE,
+        name="sanity",
+        description="Core functionality check",
+        job_description="Verify core functionality and recent changes",
+        mode="byok",
+        qe_type=QERoleType.EXECUTION,
+    ),
+    "regression": Role(
+        category=RoleCategory.QE,
+        name="regression",
+        description="Full test suite execution",
+        job_description="Run full regression suite with flake detection",
+        mode="byok",
+        qe_type=QERoleType.EXECUTION,
+    ),
+    "security": Role(
+        category=RoleCategory.QE,
+        name="security",
+        description="Security vulnerability scanning",
+        job_description="Proactively detect security vulnerabilities and suggest fixes",
+        mode="acp",
+        agent="claude-code",
+        qe_type=QERoleType.DETECTION,
+    ),
+    "api": Role(
+        category=RoleCategory.QE,
+        name="api",
+        description="API contract and behavior testing",
+        job_description="Validate API contracts, test edge cases, check error handling",
+        mode="acp",
+        agent="claude-code",
+        qe_type=QERoleType.DETECTION,
+    ),
+    "e2e": Role(
+        category=RoleCategory.QE,
+        name="e2e",
+        description="End-to-end workflow validation",
+        job_description="Test complete user workflows and integration points",
+        mode="acp",
+        agent="claude-code",
+        qe_type=QERoleType.DETECTION,
+    ),
+    "performance": Role(
+        category=RoleCategory.QE,
+        name="performance",
+        description="Performance bottleneck detection",
+        job_description="Identify performance issues and optimization opportunities",
+        mode="acp",
+        agent="claude-code",
+        qe_type=QERoleType.DETECTION,
+    ),
+}
+
+DEFAULT_DEVOPS_ROLES = {
+    "deployment": Role(
+        category=RoleCategory.DEVOPS,
+        name="deployment",
+        description="Deployment readiness validation",
+        job_description="Validate deployment configurations and readiness",
+        mode="acp",
+        agent="claude-code",
+    ),
+    "infrastructure": Role(
+        category=RoleCategory.DEVOPS,
+        name="infrastructure",
+        description="Infrastructure and config validation",
+        job_description="Review infrastructure code and configurations",
+        mode="acp",
+        agent="claude-code",
+    ),
+    "monitoring": Role(
+        category=RoleCategory.DEVOPS,
+        name="monitoring",
+        description="Observability and alerting setup",
+        job_description="Set up and validate monitoring, logging, and alerting",
+        mode="acp",
+        agent="claude-code",
+    ),
+}
+
+
+def get_default_roles() -> Dict[str, Dict[str, Role]]:
+    """Get all default roles organized by category."""
+    return {
+        "dev": DEFAULT_DEV_ROLES,
+        "qe": DEFAULT_QE_ROLES,
+        "devops": DEFAULT_DEVOPS_ROLES,
+    }
+
+
+def get_role(category: str, name: str) -> Optional[Role]:
+    """Get a specific role by category and name."""
+    defaults = get_default_roles()
+    category_roles = defaults.get(category, {})
+    return category_roles.get(name)
+
+
+def list_all_roles() -> List[Role]:
+    """List all available roles."""
+    roles = []
+    for category_roles in get_default_roles().values():
+        roles.extend(category_roles.values())
+    return roles
+
+
+def list_roles_by_category(category: str) -> List[Role]:
+    """List roles in a specific category."""
+    defaults = get_default_roles()
+    return list(defaults.get(category, {}).values())
+
+
+def list_qe_execution_roles() -> List[Role]:
+    """List QE roles that run existing tests."""
+    return [r for r in DEFAULT_QE_ROLES.values() if r.qe_type == QERoleType.EXECUTION]
+
+
+def list_qe_detection_roles() -> List[Role]:
+    """List QE roles that detect issues proactively."""
+    return [r for r in DEFAULT_QE_ROLES.values() if r.qe_type == QERoleType.DETECTION]

superqode/danger.py

@@ -0,0 +1,386 @@
+"""
+SuperQode Danger Detection - Command Safety Analysis
+
+Analyzes shell commands to detect potentially dangerous operations.
+Uses a unique visual style with gradient warnings.
+"""
+
+from enum import IntEnum
+from functools import lru_cache
+from pathlib import Path
+from typing import Iterable, NamedTuple, Sequence, Tuple
+
+# Commands that are generally safe (read-only operations)
+SAFE_COMMANDS = {
+    # Display & Output
+    "echo",
+    "cat",
+    "less",
+    "more",
+    "head",
+    "tail",
+    "tac",
+    "nl",
+    "bat",
+    # File & Directory Information
+    "ls",
+    "tree",
+    "pwd",
+    "file",
+    "stat",
+    "du",
+    "df",
+    "exa",
+    "lsd",
+    # Search & Find
+    "find",
+    "locate",
+    "which",
+    "whereis",
+    "type",
+    "grep",
+    "egrep",
+    "fgrep",
+    "rg",
+    "ag",
+    "fd",
+    "fzf",
+    # Text Processing (read-only)
+    "wc",
+    "sort",
+    "uniq",
+    "cut",
+    "paste",
+    "column",
+    "tr",
+    "diff",
+    "cmp",
+    "comm",
+    # System Information
+    "whoami",
+    "who",
+    "w",
+    "id",
+    "hostname",
+    "uname",
+    "uptime",
+    "date",
+    "cal",
+    "env",
+    "printenv",
+    # Process Information
+    "ps",
+    "top",
+    "htop",
+    "pgrep",
+    "jobs",
+    "pstree",
+    # Network (read-only)
+    "ping",
+    "traceroute",
+    "nslookup",
+    "dig",
+    "host",
+    "netstat",
+    "ss",
+    "ifconfig",
+    "ip",
+    # View compressed files
+    "zcat",
+    "zless",
+    # History & Help
+    "history",
+    "man",
+    "help",
+    "info",
+    "apropos",
+    "whatis",
+    # Checksums
+    "md5sum",
+    "sha256sum",
+    "sha1sum",
+    "cksum",
+    "sum",
+    "md5",
+    "shasum",
+    # Other Safe
+    "bc",
+    "expr",
+    "test",
+    "sleep",
+    "true",
+    "false",
+    "yes",
+    "seq",
+    "basename",
+    "dirname",
+    "realpath",
+    "readlink",
+    # Dev tools (read-only)
+    "git status",
+    "git log",
+    "git diff",
+    "git show",
+    "git branch",
+    "npm list",
+    "pip list",
+    "cargo tree",
+}
+
+# Commands that can modify the filesystem
+UNSAFE_COMMANDS = {
+    # File/Directory Creation
+    "mkdir",
+    "touch",
+    "mktemp",
+    "mkfifo",
+    "mknod",
+    # File/Directory Deletion
+    "rm",
+    "rmdir",
+    "shred",
+    # File/Directory Moving/Copying
+    "mv",
+    "cp",
+    "rsync",
+    "scp",
+    "install",
+    # File Modification
+    "sed",
+    "awk",
+    "tee",
+    "nano",
+    "vim",
+    "vi",
+    "emacs",
+    "code",
+    # Permissions/Ownership
+    "chmod",
+    "chown",
+    "chgrp",
+    "chattr",
+    "setfacl",
+    # Linking
+    "ln",
+    "link",
+    "unlink",
+    # Archive/Compression
+    "tar",
+    "zip",
+    "unzip",
+    "gzip",
+    "gunzip",
+    "bzip2",
+    "bunzip2",
+    "xz",
+    "unxz",
+    "7z",
+    "rar",
+    "unrar",
+    # Download Tools
+    "wget",
+    "curl",
+    "fetch",
+    "aria2c",
+    # Low-level Disk
+    "dd",
+    "truncate",
+    "fallocate",
+    # File Splitting
+    "split",
+    "csplit",
+    # Sync
+    "sync",
+    # System Administration
+    "useradd",
+    "userdel",
+    "usermod",
+    "groupadd",
+    "groupdel",
+    "passwd",
+    "mount",
+    "umount",
+    "mkfs",
+    "fdisk",
+    "parted",
+    "swapon",
+    "swapoff",
+    # Package managers (can install/remove)
+    "npm install",
+    "pip install",
+    "cargo install",
+    "brew install",
+    "apt",
+    "yum",
+    "dnf",
+    "pacman",
+    # Other Dangerous
+    "patch",
+    "git checkout",
+    "git reset",
+    "git clean",
+}
+
+
+class DangerLevel(IntEnum):
+    """The danger level of a command."""
+
+    SAFE = 0  # Command is known to be generally safe
+    UNKNOWN = 1  # We don't know about this command
+    DANGEROUS = 2  # Command can modify filesystem
+    DESTRUCTIVE = 3  # Command modifies files outside project
+
+
+class CommandInfo(NamedTuple):
+    """Information about a command's danger level."""
+
+    command: str
+    level: DangerLevel
+    target_path: Path | None
+    reason: str
+
+
+# Visual styles for each danger level
+DANGER_STYLES = {
+    DangerLevel.SAFE: {
+        "icon": "✅",
+        "color": "#22c55e",
+        "bg": "#22c55e20",
+        "label": "Safe",
+        "border": "green",
+    },
+    DangerLevel.UNKNOWN: {
+        "icon": "❓",
+        "color": "#f59e0b",
+        "bg": "#f59e0b20",
+        "label": "Unknown",
+        "border": "yellow",
+    },
+    DangerLevel.DANGEROUS: {
+        "icon": "⚠️",
+        "color": "#f97316",
+        "bg": "#f9731620",
+        "label": "Dangerous",
+        "border": "orange1",
+    },
+    DangerLevel.DESTRUCTIVE: {
+        "icon": "🚨",
+        "color": "#ef4444",
+        "bg": "#ef444420",
+        "label": "DESTRUCTIVE",
+        "border": "red",
+    },
+}
+
+
+@lru_cache(maxsize=512)
+def analyze_command(
+    project_dir: str,
+    working_dir: str,
+    command: str,
+) -> Tuple[DangerLevel, str, Path | None]:
+    """
+    Analyze a shell command for potential dangers.
+
+    Args:
+        project_dir: The project root directory
+        working_dir: Current working directory
+        command: The shell command to analyze
+
+    Returns:
+        Tuple of (danger_level, reason, target_path)
+    """
+    if not command or not command.strip():
+        return DangerLevel.SAFE, "Empty command", None
+
+    command = command.strip()
+    parts = command.split()
+    if not parts:
+        return DangerLevel.SAFE, "Empty command", None
+
+    base_cmd = parts[0]
+    project_path = Path(project_dir).resolve()
+    current_path = Path(working_dir).resolve()
+
+    # Check for safe commands first
+    if base_cmd in SAFE_COMMANDS:
+        return DangerLevel.SAFE, f"'{base_cmd}' is a read-only command", None
+
+    # Check for known unsafe commands
+    is_unsafe = base_cmd in UNSAFE_COMMANDS
+
+    # Look for file paths in arguments
+    target_path = None
+    for arg in parts[1:]:
+        if arg.startswith("-"):
+            continue
+        try:
+            # Try to resolve the path
+            if arg.startswith("/"):
+                target_path = Path(arg).resolve()
+            elif arg.startswith("~"):
+                target_path = Path(arg).expanduser().resolve()
+            else:
+                target_path = (current_path / arg).resolve()
+            break
+        except (OSError, ValueError):
+            continue
+
+    # Determine danger level
+    if is_unsafe:
+        if target_path:
+            try:
+                # Check if path is outside project
+                target_path.relative_to(project_path)
+                return DangerLevel.DANGEROUS, f"'{base_cmd}' can modify files", target_path
+            except ValueError:
+                return (
+                    DangerLevel.DESTRUCTIVE,
+                    f"'{base_cmd}' targets files outside project!",
+                    target_path,
+                )
+        return DangerLevel.DANGEROUS, f"'{base_cmd}' can modify the filesystem", None
+
+    # Unknown command
+    return DangerLevel.UNKNOWN, f"Unknown command '{base_cmd}'", target_path
+
+
+def get_danger_display(level: DangerLevel) -> dict:
+    """Get display properties for a danger level."""
+    return DANGER_STYLES.get(level, DANGER_STYLES[DangerLevel.UNKNOWN])
+
+
+def format_danger_message(
+    command: str,
+    level: DangerLevel,
+    reason: str,
+    target_path: Path | None = None,
+) -> str:
+    """Format a danger warning message."""
+    style = DANGER_STYLES[level]
+    icon = style["icon"]
+    label = style["label"]
+
+    msg = f"{icon} [{label}] {reason}"
+    if target_path:
+        msg += f"\n   📁 Target: {target_path}"
+    return msg
+
+
+# Quick check functions
+def is_safe(command: str, project_dir: str = ".", working_dir: str = ".") -> bool:
+    """Check if a command is safe to run."""
+    level, _, _ = analyze_command(project_dir, working_dir, command)
+    return level == DangerLevel.SAFE
+
+
+def is_destructive(command: str, project_dir: str = ".", working_dir: str = ".") -> bool:
+    """Check if a command is destructive (modifies files outside project)."""
+    level, _, _ = analyze_command(project_dir, working_dir, command)
+    return level == DangerLevel.DESTRUCTIVE
+
+
+def requires_approval(command: str, project_dir: str = ".", working_dir: str = ".") -> bool:
+    """Check if a command requires user approval."""
+    level, _, _ = analyze_command(project_dir, working_dir, command)
+    return level >= DangerLevel.DANGEROUS