monoco-toolkit 0.3.6__py3-none-any.whl → 0.3.9__py3-none-any.whl

monoco/cli/workspace.py

@@ -4,7 +4,7 @@ from rich.console import Console
 import yaml
 
 from monoco.core.output import AgentOutput, OutputManager
-from monoco.core.hooks import install_hooks
+from monoco.core.githooks import install_hooks
 
 app = typer.Typer(help="Manage Monoco Workspace")
 console = Console()

monoco/core/config.py

@@ -93,12 +93,55 @@ class TransitionConfig(BaseModel):
     command_template: Optional[str] = None
 
 
+class CriticalityRuleConfig(BaseModel):
+    """Configuration for auto-escalation rules."""
+
+    name: str
+    description: str = ""
+    path_patterns: List[str] = Field(default_factory=list)
+    tag_patterns: List[str] = Field(default_factory=list)
+    target_level: str = "medium"  # low, medium, high, critical
+
+
+class CriticalityConfig(BaseModel):
+    """Configuration for issue criticality system."""
+
+    enabled: bool = Field(default=True)
+    # Type to criticality default mapping
+    type_defaults: Dict[str, str] = Field(
+        default_factory=lambda: {
+            "epic": "high",
+            "feature": "medium",
+            "chore": "low",
+            "fix": "high",
+        }
+    )
+    # Auto-escalation rules
+    auto_rules: List[CriticalityRuleConfig] = Field(default_factory=list)
+
+    def merge(self, other: "CriticalityConfig") -> "CriticalityConfig":
+        if not other:
+            return self
+        if other.enabled is not None:
+            self.enabled = other.enabled
+        if other.type_defaults:
+            self.type_defaults.update(other.type_defaults)
+        if other.auto_rules:
+            # Merge by name
+            existing = {r.name: r for r in self.auto_rules}
+            for rule in other.auto_rules:
+                existing[rule.name] = rule
+            self.auto_rules = list(existing.values())
+        return self
+
+
 class IssueSchemaConfig(BaseModel):
     types: List[IssueTypeConfig] = Field(default_factory=list)
     statuses: List[str] = Field(default_factory=list)
     stages: List[str] = Field(default_factory=list)
     solutions: List[str] = Field(default_factory=list)
     workflows: List[TransitionConfig] = Field(default_factory=list)
+    criticality: CriticalityConfig = Field(default_factory=CriticalityConfig)
 
     def merge(self, other: "IssueSchemaConfig") -> "IssueSchemaConfig":
         if not other:
@@ -130,6 +173,10 @@ class IssueSchemaConfig(BaseModel):
                 wf_map[ow.name] = ow
             self.workflows = list(wf_map.values())
 
+        # Criticality config
+        if other.criticality:
+            self.criticality = self.criticality.merge(other.criticality)
+
         return self
 
 
@@ -187,6 +234,10 @@ class MonocoConfig(BaseModel):
         default_factory=dict,
         description="Git hooks configuration (hook_name -> command)",
     )
+    session_hooks: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Session lifecycle hooks configuration (hook_name -> config)",
+    )
 
     issue: IssueSchemaConfig = Field(default_factory=IssueSchemaConfig)
     domains: DomainConfig = Field(default_factory=DomainConfig)

monoco/core/hooks/__init__.py

@@ -0,0 +1,19 @@
+"""
+Monoco Native Hook System
+
+Provides lifecycle hooks for Agent Sessions, independent of specific CLI tools.
+"""
+
+from .base import SessionLifecycleHook, HookResult, HookStatus
+from .context import HookContext
+from .registry import HookRegistry, get_registry, reset_registry
+
+__all__ = [
+    "SessionLifecycleHook",
+    "HookResult",
+    "HookStatus",
+    "HookContext",
+    "HookRegistry",
+    "get_registry",
+    "reset_registry",
+]

monoco/core/hooks/base.py

@@ -0,0 +1,104 @@
+"""
+Base classes for Session Lifecycle Hooks.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+from enum import Enum
+
+from .context import HookContext
+
+
+class HookStatus(str, Enum):
+    """Status of hook execution."""
+    SUCCESS = "success"
+    FAILURE = "failure"
+    SKIPPED = "skipped"
+    WARNING = "warning"
+
+
+@dataclass
+class HookResult:
+    """Result of a hook execution."""
+    status: HookStatus
+    message: str = ""
+    details: Optional[dict] = None
+
+    @classmethod
+    def success(cls, message: str = "", details: Optional[dict] = None) -> "HookResult":
+        return cls(status=HookStatus.SUCCESS, message=message, details=details)
+
+    @classmethod
+    def failure(cls, message: str = "", details: Optional[dict] = None) -> "HookResult":
+        return cls(status=HookStatus.FAILURE, message=message, details=details)
+
+    @classmethod
+    def skipped(cls, message: str = "", details: Optional[dict] = None) -> "HookResult":
+        return cls(status=HookStatus.SKIPPED, message=message, details=details)
+
+    @classmethod
+    def warning(cls, message: str = "", details: Optional[dict] = None) -> "HookResult":
+        return cls(status=HookStatus.WARNING, message=message, details=details)
+
+
+class SessionLifecycleHook(ABC):
+    """
+    Abstract base class for session lifecycle hooks.
+    
+    Hooks can be registered to execute at specific points in a session's lifecycle:
+    - on_session_start: Called when a session starts
+    - on_session_end: Called when a session ends (terminate)
+    
+    Example:
+        class MyHook(SessionLifecycleHook):
+            def on_session_start(self, context: HookContext) -> HookResult:
+                print(f"Session {context.session_id} started")
+                return HookResult.success()
+            
+            def on_session_end(self, context: HookContext) -> HookResult:
+                print(f"Session {context.session_id} ended")
+                return HookResult.success()
+    """
+
+    def __init__(self, name: Optional[str] = None, config: Optional[dict] = None):
+        """
+        Initialize the hook.
+        
+        Args:
+            name: Optional name for the hook. If not provided, uses class name.
+            config: Optional configuration dictionary for the hook.
+        """
+        self.name = name or self.__class__.__name__
+        self.config = config or {}
+        self.enabled = self.config.get("enabled", True)
+
+    @abstractmethod
+    def on_session_start(self, context: HookContext) -> HookResult:
+        """
+        Called when a session starts.
+        
+        Args:
+            context: The hook context containing session information.
+            
+        Returns:
+            HookResult indicating the outcome of the hook execution.
+        """
+        pass
+
+    @abstractmethod
+    def on_session_end(self, context: HookContext) -> HookResult:
+        """
+        Called when a session ends.
+        
+        Args:
+            context: The hook context containing session information.
+            
+        Returns:
+            HookResult indicating the outcome of the hook execution.
+        """
+        pass
+
+    def is_enabled(self) -> bool:
+        """Check if this hook is enabled."""
+        return self.enabled

monoco/core/hooks/builtin/__init__.py

@@ -0,0 +1,11 @@
+"""
+Built-in session lifecycle hooks.
+"""
+
+from .git_cleanup import GitCleanupHook
+from .logging_hook import LoggingHook
+
+__all__ = [
+    "GitCleanupHook",
+    "LoggingHook",
+]

monoco/core/hooks/builtin/git_cleanup.py

@@ -0,0 +1,266 @@
+"""
+GitCleanupHook - Performs git cleanup operations when a session ends.
+
+This hook ensures that:
+1. Current branch is switched back to main (if safe)
+2. Feature branches are deleted if the associated issue is completed/merged
+"""
+
+import logging
+from typing import Optional
+
+from ..base import SessionLifecycleHook, HookResult, HookStatus
+from ..context import HookContext
+
+logger = logging.getLogger("monoco.core.hooks.git_cleanup")
+
+
+class GitCleanupHook(SessionLifecycleHook):
+    """
+    Hook for cleaning up git state when a session ends.
+    
+    Configuration options:
+        - auto_switch_to_main: Whether to automatically switch to main branch (default: True)
+        - auto_delete_merged_branches: Whether to delete merged feature branches (default: True)
+        - main_branch: Name of the main branch (default: "main", fallback: "master")
+        - require_clean_worktree: Whether to require clean worktree before operations (default: True)
+    """
+
+    def __init__(self, name: Optional[str] = None, config: Optional[dict] = None):
+        super().__init__(name=name or "git_cleanup", config=config)
+        
+        # Configuration with defaults
+        self.auto_switch_to_main = self.config.get("auto_switch_to_main", True)
+        self.auto_delete_merged_branches = self.config.get("auto_delete_merged_branches", True)
+        self.main_branch = self.config.get("main_branch", "main")
+        self.require_clean_worktree = self.config.get("require_clean_worktree", True)
+
+    def on_session_start(self, context: HookContext) -> HookResult:
+        """
+        Called when session starts.
+        
+        No action needed at session start for git cleanup.
+        """
+        return HookResult.success("Git cleanup hook initialized")
+
+    def on_session_end(self, context: HookContext) -> HookResult:
+        """
+        Called when session ends.
+        
+        Performs cleanup operations:
+        1. Check current git state
+        2. Switch to main branch if needed and safe
+        3. Delete feature branch if issue is completed
+        """
+        if not context.git:
+            return HookResult.skipped("No git context available")
+        
+        project_root = context.git.project_root
+        
+        try:
+            from monoco.core import git
+            
+            # Check if we're in a git repo
+            if not git.is_git_repo(project_root):
+                return HookResult.skipped("Not a git repository")
+            
+            # Get current state
+            current_branch = git.get_current_branch(project_root)
+            default_branch = self._get_default_branch(project_root)
+            
+            # Check for uncommitted changes
+            has_changes = len(git.get_git_status(project_root)) > 0
+            
+            results = []
+            
+            # Step 1: Switch to main branch if needed
+            if self.auto_switch_to_main and current_branch != default_branch:
+                switch_result = self._switch_to_main(
+                    project_root, current_branch, default_branch, has_changes
+                )
+                results.append(switch_result)
+                
+                if switch_result.status == HookStatus.SUCCESS:
+                    current_branch = default_branch
+            
+            # Step 2: Delete feature branch if issue is completed
+            if self.auto_delete_merged_branches and context.issue:
+                delete_result = self._cleanup_feature_branch(
+                    project_root, context.issue, default_branch, current_branch
+                )
+                if delete_result:
+                    results.append(delete_result)
+            
+            # Combine results
+            failures = [r for r in results if r.status == HookStatus.FAILURE]
+            warnings = [r for r in results if r.status == HookStatus.WARNING]
+            
+            if failures:
+                return HookResult.failure(
+                    f"Git cleanup completed with {len(failures)} failures",
+                    {"results": [r.message for r in results]}
+                )
+            elif warnings:
+                return HookResult.warning(
+                    f"Git cleanup completed with {len(warnings)} warnings",
+                    {"results": [r.message for r in results]}
+                )
+            else:
+                return HookResult.success(
+                    "Git cleanup completed successfully",
+                    {"results": [r.message for r in results]}
+                )
+                
+        except Exception as e:
+            logger.error(f"Git cleanup failed: {e}")
+            return HookResult.failure(f"Git cleanup failed: {e}")
+
+    def _get_default_branch(self, project_root) -> str:
+        """Determine the default branch (main or master)."""
+        from monoco.core import git
+        
+        if git.branch_exists(project_root, self.main_branch):
+            return self.main_branch
+        elif git.branch_exists(project_root, "master"):
+            return "master"
+        return self.main_branch
+
+    def _switch_to_main(
+        self, 
+        project_root, 
+        current_branch: str, 
+        default_branch: str,
+        has_changes: bool
+    ) -> HookResult:
+        """
+        Switch to the main branch if safe to do so.
+        
+        Args:
+            project_root: The project root path
+            current_branch: Current branch name
+            default_branch: Target branch name (main/master)
+            has_changes: Whether there are uncommitted changes
+            
+        Returns:
+            HookResult indicating success/failure
+        """
+        from monoco.core import git
+        
+        # Safety check: uncommitted changes
+        if has_changes and self.require_clean_worktree:
+            return HookResult.warning(
+                f"Cannot switch from '{current_branch}' to '{default_branch}': "
+                f"uncommitted changes exist. Please commit or stash changes."
+            )
+        
+        # Check if default branch exists
+        if not git.branch_exists(project_root, default_branch):
+            return HookResult.warning(
+                f"Cannot switch to '{default_branch}': branch does not exist"
+            )
+        
+        try:
+            git.checkout_branch(project_root, default_branch)
+            return HookResult.success(
+                f"Switched from '{current_branch}' to '{default_branch}'"
+            )
+        except Exception as e:
+            return HookResult.failure(
+                f"Failed to switch to '{default_branch}': {e}"
+            )
+
+    def _cleanup_feature_branch(
+        self,
+        project_root,
+        issue,
+        default_branch: str,
+        current_branch: str
+    ) -> Optional[HookResult]:
+        """
+        Clean up the feature branch associated with an issue.
+        
+        Args:
+            project_root: The project root path
+            issue: The IssueInfo object
+            default_branch: The default branch name
+            current_branch: Current branch name
+            
+        Returns:
+            HookResult or None if no action needed
+        """
+        from monoco.core import git
+        
+        # Get the branch name from issue
+        branch_name = issue.branch_name
+        if not branch_name:
+            # Try to infer from convention: feat/<issue_id>-*
+            # This is a fallback if isolation metadata is not set
+            return None
+        
+        # Check if branch exists
+        if not git.branch_exists(project_root, branch_name):
+            return None
+        
+        # Safety: don't delete the branch we're currently on
+        if current_branch == branch_name:
+            return HookResult.warning(
+                f"Cannot delete branch '{branch_name}': currently checked out"
+            )
+        
+        # Check if issue is completed/closed
+        is_completed = issue.status in ("closed", "done", "merged")
+        
+        if not is_completed:
+            return HookResult.skipped(
+                f"Branch '{branch_name}' not deleted: issue status is '{issue.status}'"
+            )
+        
+        # Check if branch is merged into default branch
+        try:
+            is_merged = self._is_branch_merged(project_root, branch_name, default_branch)
+        except Exception:
+            is_merged = False
+        
+        if not is_merged:
+            return HookResult.warning(
+                f"Branch '{branch_name}' not deleted: not merged into '{default_branch}'"
+            )
+        
+        # Safe to delete
+        try:
+            git.delete_branch(project_root, branch_name, force=False)
+            return HookResult.success(
+                f"Deleted merged branch '{branch_name}'"
+            )
+        except Exception as e:
+            return HookResult.failure(
+                f"Failed to delete branch '{branch_name}': {e}"
+            )
+
+    def _is_branch_merged(
+        self, 
+        project_root, 
+        branch: str, 
+        target: str
+    ) -> bool:
+        """
+        Check if a branch is merged into the target branch.
+        
+        Args:
+            project_root: The project root path
+            branch: The branch to check
+            target: The target branch to check against
+            
+        Returns:
+            True if branch is merged into target
+        """
+        from monoco.core import git
+        
+        # Use git merge-base to check if branch is ancestor of target
+        code, stdout, _ = git._run_git(
+            ["merge-base", "--is-ancestor", branch, target],
+            project_root
+        )
+        
+        # Exit code 0 means branch is ancestor of target (merged)
+        return code == 0

monoco/core/hooks/builtin/logging_hook.py

@@ -0,0 +1,78 @@
+"""
+LoggingHook - Logs session lifecycle events.
+
+Simple hook that logs when sessions start and end for auditing/debugging.
+"""
+
+import logging
+from datetime import datetime
+from typing import Optional
+
+from ..base import SessionLifecycleHook, HookResult
+from ..context import HookContext
+
+logger = logging.getLogger("monoco.core.hooks.logging")
+
+
+class LoggingHook(SessionLifecycleHook):
+    """
+    Hook for logging session lifecycle events.
+    
+    Configuration options:
+        - log_level: The logging level to use (default: INFO)
+        - log_start: Whether to log session start (default: True)
+        - log_end: Whether to log session end (default: True)
+    """
+
+    def __init__(self, name: Optional[str] = None, config: Optional[dict] = None):
+        super().__init__(name=name or "logging", config=config)
+        
+        self.log_level = self._parse_log_level(self.config.get("log_level", "INFO"))
+        self.log_start = self.config.get("log_start", True)
+        self.log_end = self.config.get("log_end", True)
+
+    def _parse_log_level(self, level: str) -> int:
+        """Parse log level string to logging constant."""
+        levels = {
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "WARNING": logging.WARNING,
+            "ERROR": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+        return levels.get(level.upper(), logging.INFO)
+
+    def on_session_start(self, context: HookContext) -> HookResult:
+        """Log session start."""
+        if not self.log_start:
+            return HookResult.skipped("Session start logging disabled")
+        
+        issue_info = f" for issue {context.issue.id}" if context.issue else ""
+        log_message = (
+            f"Session {context.session_id} started{issue_info} "
+            f"(role: {context.role_name})"
+        )
+        
+        logger.log(self.log_level, log_message)
+        
+        return HookResult.success(f"Logged session start: {context.session_id}")
+
+    def on_session_end(self, context: HookContext) -> HookResult:
+        """Log session end with duration."""
+        if not self.log_end:
+            return HookResult.skipped("Session end logging disabled")
+        
+        duration = datetime.now() - context.created_at
+        duration_seconds = duration.total_seconds()
+        
+        issue_info = f" for issue {context.issue.id}" if context.issue else ""
+        log_message = (
+            f"Session {context.session_id} ended{issue_info} "
+            f"(duration: {duration_seconds:.2f}s, status: {context.session_status})"
+        )
+        
+        logger.log(self.log_level, log_message)
+        
+        return HookResult.success(
+            f"Logged session end: {context.session_id} (duration: {duration_seconds:.2f}s)"
+        )

monoco/core/hooks/context.py

@@ -0,0 +1,131 @@
+"""
+Hook Context - Data passed to hooks during session lifecycle events.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+
+@dataclass
+class IssueInfo:
+    """Information about the issue associated with a session."""
+    id: str
+    status: Optional[str] = None
+    stage: Optional[str] = None
+    title: Optional[str] = None
+    branch_name: Optional[str] = None
+    is_merged: bool = False
+    
+    @classmethod
+    def from_metadata(cls, metadata: Any) -> "IssueInfo":
+        """Create IssueInfo from IssueMetadata."""
+        return cls(
+            id=getattr(metadata, "id", ""),
+            status=getattr(metadata, "status", None),
+            stage=getattr(metadata, "stage", None),
+            title=getattr(metadata, "title", None),
+            branch_name=getattr(metadata, "isolation", {}).get("ref") if hasattr(metadata, "isolation") and metadata.isolation else None,
+            is_merged=False,  # Will be determined by GitCleanupHook
+        )
+
+
+@dataclass
+class GitInfo:
+    """Git repository information."""
+    project_root: Path
+    current_branch: Optional[str] = None
+    has_uncommitted_changes: bool = False
+    default_branch: str = "main"
+    
+    def __post_init__(self):
+        if self.current_branch is None:
+            # Lazy load current branch
+            try:
+                from monoco.core import git
+                self.current_branch = git.get_current_branch(self.project_root)
+            except Exception:
+                self.current_branch = None
+
+
+@dataclass
+class HookContext:
+    """
+    Context object passed to lifecycle hooks.
+    
+    Contains all relevant information about the session, issue, and environment
+    that hooks might need to perform their operations.
+    """
+    
+    # Session Information
+    session_id: str
+    role_name: str
+    session_status: str
+    created_at: datetime
+    
+    # Issue Information
+    issue: Optional[IssueInfo] = None
+    
+    # Git Information
+    git: Optional[GitInfo] = None
+    
+    # Additional Context
+    extra: Dict[str, Any] = field(default_factory=dict)
+    
+    @classmethod
+    def from_runtime_session(
+        cls,
+        runtime_session: Any,
+        project_root: Optional[Path] = None,
+    ) -> "HookContext":
+        """
+        Create a HookContext from a RuntimeSession.
+        
+        Args:
+            runtime_session: The RuntimeSession object
+            project_root: Optional project root path
+            
+        Returns:
+            A populated HookContext
+        """
+        model = runtime_session.model
+        
+        # Build IssueInfo if we have an issue_id
+        issue_info = None
+        if model.issue_id:
+            issue_info = IssueInfo(
+                id=model.issue_id,
+                branch_name=model.branch_name,
+            )
+            
+            # Try to load full issue metadata
+            try:
+                from monoco.features.issue.core import find_issue_path, parse_issue
+                from monoco.core.config import find_monoco_root
+                
+                if project_root is None:
+                    project_root = find_monoco_root()
+                
+                issues_root = project_root / "Issues"
+                issue_path = find_issue_path(issues_root, model.issue_id)
+                if issue_path:
+                    metadata = parse_issue(issue_path)
+                    if metadata:
+                        issue_info = IssueInfo.from_metadata(metadata)
+            except Exception:
+                pass  # Use basic issue info
+        
+        # Build GitInfo
+        git_info = None
+        if project_root:
+            git_info = GitInfo(project_root=project_root)
+        
+        return cls(
+            session_id=model.id,
+            role_name=model.role_name,
+            session_status=model.status,
+            created_at=model.created_at,
+            issue=issue_info,
+            git=git_info,
+        )