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

monoco/core/registry.py

@@ -1,39 +1,54 @@
-from typing import Dict, List
+from typing import Dict, List, Optional
 from monoco.core.feature import MonocoFeature
+from monoco.core.loader import FeatureLoader, FeatureRegistry as LoaderFeatureRegistry
 
 
 class FeatureRegistry:
-    _features: Dict[str, MonocoFeature] = {}
+    """
+    Feature registry that wraps the new unified FeatureLoader.
+    
+    This class provides backward compatibility while delegating to the
+    new FeatureLoader for dynamic discovery and lifecycle management.
+    """
+
+    _loader: Optional[FeatureLoader] = None
+
+    @classmethod
+    def _get_loader(cls) -> FeatureLoader:
+        """Get or create the default feature loader."""
+        if cls._loader is None:
+            cls._loader = FeatureLoader()
+            # Discover and load all features
+            cls._loader.discover()
+            cls._loader.load_all()
+        return cls._loader
 
     @classmethod
     def register(cls, feature: MonocoFeature):
         """Register a feature instance."""
-        cls._features[feature.name] = feature
+        loader = cls._get_loader()
+        loader.registry.register(feature)  # type: ignore
 
     @classmethod
     def get_features(cls) -> List[MonocoFeature]:
         """Get all registered features."""
-        return list(cls._features.values())
+        loader = cls._get_loader()
+        return loader.registry.get_all()  # type: ignore
 
     @classmethod
-    def get_feature(cls, name: str) -> MonocoFeature:
+    def get_feature(cls, name: str) -> Optional[MonocoFeature]:
         """Get a specific feature by name."""
-        return cls._features.get(name)
+        loader = cls._get_loader()
+        return loader.registry.get(name)  # type: ignore
 
     @classmethod
     def load_defaults(cls):
         """
-        Load default core features.
-        TODO: In the future, this could be dynamic via entry points.
+        Load default core features using the unified FeatureLoader.
+        
+        This method discovers and loads all features from monoco/features/
+        automatically, replacing the manual registration approach.
         """
-        # Import here to avoid circular dependencies at module level
-        from monoco.features.issue.adapter import IssueFeature
-        from monoco.features.spike.adapter import SpikeFeature
-        from monoco.features.i18n.adapter import I18nFeature
-        from monoco.features.memo.adapter import MemoFeature
-
-        cls.register(IssueFeature())
-        cls.register(SpikeFeature())
-        cls.register(I18nFeature())
-        cls.register(MemoFeature())
-        pass
+        loader = cls._get_loader()
+        # Features are already discovered and loaded in _get_loader
+        # This method is kept for backward compatibility

monoco/core/resource/__init__.py

@@ -0,0 +1,5 @@
+from .models import ResourceNode, ResourceType
+from .finder import ResourceFinder
+from .manager import ResourceManager
+
+__all__ = ["ResourceNode", "ResourceType", "ResourceFinder", "ResourceManager"]

monoco/core/resource/finder.py

@@ -0,0 +1,98 @@
+import sys
+from pathlib import Path
+from typing import List, Generator, Union
+import importlib.util
+
+# Use standard importlib.resources for Python 3.9+
+if sys.version_info < (3, 9):
+    # Fallback or error - for now assume 3.9+ as this is a modern toolkit
+    raise RuntimeError("Monoco requires Python 3.9+")
+from importlib.resources import files, as_file
+
+from .models import ResourceNode, ResourceType
+
+class ResourceFinder:
+    """
+    Scans Python packages for Monoco standard resources.
+    Standard Layout: <package>/resources/<lang>/<type>/<file>
+    """
+
+    def scan_package(self, package_name: str) -> List[ResourceNode]:
+        """
+        Traverses the 'resources' directory of a given package.
+        Returns a flat list of ResourceNode objects.
+        """
+        nodes = []
+        
+        # Check if package exists
+        if not importlib.util.find_spec(package_name):
+            return []
+
+        try:
+            pkg_root = files(package_name)
+            resources_root = pkg_root.joinpath("resources")
+            
+            if not resources_root.is_dir():
+                return []
+                
+            # Iterate over languages (direct children of resources/)
+            for lang_dir in resources_root.iterdir():
+                if not lang_dir.is_dir() or lang_dir.name.startswith("_"):
+                    continue
+                
+                lang = lang_dir.name
+                
+                # Iterate over resource types (children of lang/)
+                for type_dir in lang_dir.iterdir():
+                    if not type_dir.is_dir() or type_dir.name.startswith("_"):
+                        continue
+                        
+                    try:
+                        res_type = ResourceType(type_dir.name)
+                    except ValueError:
+                        res_type = ResourceType.OTHER
+
+                    # Iterate over files (children of type/)
+                    # Note: This effectively supports shallow structure. 
+                    # For recursive (like skills folders), we might need recursion.
+                    # For now, let's assume flat files or folders treated as units (like flow skill dirs).
+                    
+                    for item in type_dir.iterdir():
+                         # For skills, the item might be a directory (Flow Skill)
+                         # We treat the directory path as the resource path in that case?
+                         # Or we recursively scan?
+                         # ResourceNode expects a path.
+                         
+                         # Use as_file to ensure we have a filesystem path (needed for symlinks/copy)
+                         with as_file(item) as item_path:
+                             # Note: as_file context manager keeps the temporary file alive if extracted from zip.
+                             # But here we probably want the path to persist?
+                             # if it's a real file system, item_path is the real path.
+                             
+                             if item.is_dir():
+                                 # Flow skills are directories
+                                 # We add the directory itself as a node?
+                                 if res_type == ResourceType.SKILLS:
+                                     nodes.append(ResourceNode(
+                                         name=item.name,
+                                         path=item_path,
+                                         type=res_type,
+                                         language=lang
+                                     ))
+                             elif item.is_file():
+                                 if item.name.startswith("."):
+                                     continue
+                                     
+                                 nodes.append(ResourceNode(
+                                     name=item.name,
+                                     path=item_path,
+                                     type=res_type,
+                                     language=lang
+                                 ))
+
+        except Exception as e:
+            # gracefully handle errors, maybe log?
+            print(f"Warning: Error scanning resources in {package_name}: {e}")
+            return []
+
+        return nodes

monoco/core/resource/manager.py

@@ -0,0 +1,91 @@
+from typing import List, Optional, Dict
+from pathlib import Path
+import shutil
+import os
+
+from .models import ResourceNode, ResourceType
+from .finder import ResourceFinder
+
+class ResourceManager:
+    def __init__(self, source_lang: str = "en"):
+        self.finder = ResourceFinder()
+        self.source_lang = source_lang
+
+    def list_resources(self, package: str, type: Optional[ResourceType] = None, lang: Optional[str] = None) -> List[ResourceNode]:
+        """
+        Low-level listing of resources with optional exact filtering.
+        """
+        all_nodes = self.finder.scan_package(package)
+        filtered = []
+        for node in all_nodes:
+            if type and node.type != type:
+                continue
+            if lang and node.language != lang:
+                continue
+            filtered.append(node)
+        return filtered
+
+    def get_merged_resources(self, package: str, type: ResourceType, target_lang: str) -> List[ResourceNode]:
+        """
+        Get resources of a specific type, merging source language defaults with target language overrides.
+        Returns a list of unique resources (by name), prioritizing target_lang.
+        """
+        all_nodes = self.finder.scan_package(package)
+        type_nodes = [n for n in all_nodes if n.type == type]
+        
+        # Dictionary to hold the best match for each filename: name -> ResourceNode
+        best_matches: Dict[str, ResourceNode] = {}
+        
+        # 1. Populate with source language (Default Base)
+        for node in type_nodes:
+            if node.language == self.source_lang:
+                best_matches[node.name] = node
+                
+        # 2. Override with target language if different
+        if target_lang != self.source_lang:
+            for node in type_nodes:
+                if node.language == target_lang:
+                    best_matches[node.name] = node
+                    
+        return list(best_matches.values())
+
+    def extract_to(self, nodes: List[ResourceNode], destination: Path, symlink: bool = False, force: bool = True) -> int:
+        """
+        Extracts (copy or symlink) resources to the destination directory.
+        Returns count of extracted items.
+        
+        Args:
+            nodes: List of resources to extract
+            destination: Target directory
+            symlink: If True, create symbolic links instead of copying
+            force: If True, overwrite existing files/symlinks
+        """
+        destination.mkdir(parents=True, exist_ok=True)
+        count = 0
+        
+        for node in nodes:
+            dest_path = destination / node.name
+            
+            if dest_path.exists():
+                if not force:
+                    continue
+                # Remove existing
+                if dest_path.is_symlink() or dest_path.is_file():
+                    dest_path.unlink()
+                elif dest_path.is_dir():
+                    shutil.rmtree(dest_path)
+            
+            try:
+                if symlink:
+                    # Symlink target must be absolute
+                    dest_path.symlink_to(node.path)
+                else:
+                    if node.path.is_dir():
+                        shutil.copytree(node.path, dest_path)
+                    else:
+                        shutil.copy2(node.path, dest_path)
+                count += 1
+            except Exception as e:
+                print(f"Error extracting {node.name}: {e}")
+                
+        return count

monoco/core/resource/models.py

@@ -0,0 +1,35 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, List
+from enum import Enum
+
+class ResourceType(str, Enum):
+    PROMPTS = "prompts"
+    RULES = "rules"
+    SKILLS = "skills"
+    ROLES = "roles"
+    GLOSSARY = "glossary"
+    TEMPLATES = "templates"
+    DOCS = "docs"
+    OTHER = "other"
+
+@dataclass
+class ResourceNode:
+    """
+    Represents a discovered resource file in a Python package.
+    """
+    name: str
+    path: Path  # Absolute path to the source file
+    type: ResourceType
+    language: str  # "en", "zh", etc.
+    content: Optional[str] = None  # Lazy loaded content
+    
+    @property
+    def key(self) -> str:
+        """Unique identifier for the resource (e.g. 'agent.prompts.system')"""
+        return f"{self.type.value}.{self.name}"
+
+    def read_text(self) -> str:
+        if self.content:
+            return self.content
+        return self.path.read_text(encoding="utf-8")

monoco/core/skill_framework.py

@@ -0,0 +1,292 @@
+"""
+Skill Framework for Monoco Toolkit - Three-Level Architecture
+
+This module implements the Role-Workflow-Atom three-level skill architecture:
+
+1. Atom Skills (atom): Atomic capabilities that perform single operations
+   - atom-issue-lifecycle: Issue lifecycle operations (create, start, submit, close)
+   - atom-code-dev: Code development operations (investigate, implement, test, document)
+   - atom-knowledge: Knowledge management operations (capture, process, convert, archive)
+   - atom-review: Review operations (checkout, verify, challenge, feedback)
+
+2. Workflow Skills (workflow): Orchestration of atom skills into workflows
+   - workflow-dev: Development workflow (setup → investigate → implement → test → submit)
+   - workflow-issue-create: Issue creation workflow (extract → classify → create)
+   - workflow-review: Review workflow (checkout → verify → challenge → decide)
+
+3. Role Skills (role): Configuration layer defining default workflow and preferences
+   - role-engineer: Engineer role (uses workflow-dev, autopilot mode)
+   - role-manager: Manager role (uses workflow-planning, copilot mode)
+   - role-planner: Planner role (uses workflow-design, copilot mode)
+   - role-reviewer: Reviewer role (uses workflow-review, autopilot mode)
+
+Key Design Principles:
+- Single Responsibility: Each atom skill does one thing
+- Composition over Inheritance: Workflows compose atoms
+- Mode Agnostic: Same workflow supports both copilot and autopilot modes
+- Convention over Configuration: System constraints defined once in atom layer
+"""
+
+from __future__ import annotations
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Union
+from pydantic import BaseModel, Field, model_validator
+import yaml
+
+
+class SkillMode(str, Enum):
+    """Execution mode for skills."""
+    COPILOT = "copilot"      # Human-led, AI-assisted
+    AUTOPILOT = "autopilot"  # AI-led, automatic execution
+
+
+class SkillType(str, Enum):
+    """Skill type in the three-level architecture."""
+    ATOM = "atom"        # Atomic capability
+    WORKFLOW = "workflow"  # Workflow orchestration
+    ROLE = "role"        # Role configuration
+
+
+class ComplianceRule(BaseModel):
+    """A compliance rule."""
+    rule: str = Field(..., description="Rule description")
+    severity: str = Field(default="warning", description="Rule severity: error, warning, info")
+    check: Optional[str] = Field(default=None, description="Check command or condition")
+    command: Optional[str] = Field(default=None, description="Associated CLI command")
+    mindset: Optional[str] = Field(default=None, description="Related mindset/principle")
+    fail_if: Optional[str] = Field(default=None, description="Condition that causes failure")
+
+
+class AtomOperation(BaseModel):
+    """An operation within an atom skill."""
+    name: str = Field(..., description="Operation name (e.g., 'create', 'start')")
+    description: str = Field(..., description="What this operation does")
+    command: Optional[str] = Field(default=None, description="Associated CLI command")
+    reminder: Optional[str] = Field(default=None, description="Reminder text for this operation")
+    compliance_rules: List[ComplianceRule] = Field(default_factory=list, description="Compliance rules for this operation")
+    checkpoints: List[str] = Field(default_factory=list, description="Checkpoints for this operation")
+    output: Optional[str] = Field(default=None, description="Expected output")
+
+
+class Checkpoint(BaseModel):
+    """A checkpoint in a workflow stage."""
+    description: str = Field(..., description="What to check")
+    atom_skill: str = Field(..., description="Atom skill to use")
+    operation: str = Field(..., description="Operation to invoke")
+    reminder: Optional[str] = Field(default=None, description="Reminder at this checkpoint")
+
+
+class WorkflowStage(BaseModel):
+    """A stage in a workflow."""
+    name: str = Field(..., description="Stage name")
+    atom_skill: Optional[str] = Field(default=None, description="Atom skill to use (optional for virtual stages)")
+    operation: Optional[str] = Field(default=None, description="Operation to invoke (optional for virtual stages)")
+    description: Optional[str] = Field(default=None, description="Stage description")
+    reminder: Optional[str] = Field(default=None, description="Reminder for this stage")
+    checkpoints: List[Checkpoint] = Field(default_factory=list, description="Checkpoints within this stage")
+    next_stages: Dict[str, str] = Field(default_factory=dict, description="Conditional next stages")
+
+
+class ModeConfig(BaseModel):
+    """Configuration for a specific execution mode."""
+    behavior: str = Field(..., description="Behavior description")
+    pause_on: List[str] = Field(default_factory=list, description="Stages to pause on")
+    auto_execute: bool = Field(default=False, description="Whether to auto-execute stages")
+
+
+# ============================================================================
+# Atom Skill Models
+# ============================================================================
+
+class AtomSkillMetadata(BaseModel):
+    """Metadata for an atom skill."""
+    name: str = Field(..., description="Unique atom skill name (e.g., 'atom-issue-lifecycle')")
+    type: str = Field(default="atom", description="Skill type (always 'atom')")
+    domain: str = Field(..., description="Domain (e.g., 'issue', 'code', 'knowledge', 'review')")
+    description: str = Field(..., description="What this atom skill provides")
+    version: str = Field(default="1.0.0", description="Skill version")
+    author: Optional[str] = Field(default=None, description="Skill author")
+    
+    operations: List[AtomOperation] = Field(..., description="Available operations")
+    compliance_rules: List[ComplianceRule] = Field(default_factory=list, description="System-level compliance rules")
+
+
+# ============================================================================
+# Workflow Skill Models
+# ============================================================================
+
+class WorkflowSkillMetadata(BaseModel):
+    """Metadata for a workflow skill."""
+    name: str = Field(..., description="Unique workflow skill name (e.g., 'workflow-dev')")
+    type: str = Field(default="workflow", description="Skill type (always 'workflow')")
+    description: str = Field(..., description="What this workflow orchestrates")
+    version: str = Field(default="1.0.0", description="Skill version")
+    author: Optional[str] = Field(default=None, description="Skill author")
+    
+    dependencies: List[str] = Field(..., description="Required atom skills")
+    stages: List[WorkflowStage] = Field(..., description="Workflow stages")
+    
+    mode_config: Dict[SkillMode, ModeConfig] = Field(
+        default_factory=dict,
+        description="Configuration for copilot and autopilot modes"
+    )
+
+
+# ============================================================================
+# Role Skill Models
+# ============================================================================
+
+class RolePreference(BaseModel):
+    """A preference for a role."""
+    category: str = Field(..., description="Preference category")
+    value: str = Field(..., description="Preference value")
+
+
+class RoleSkillMetadata(BaseModel):
+    """Metadata for a role skill."""
+    name: str = Field(..., description="Unique role name (e.g., 'role-engineer')")
+    type: str = Field(default="role", description="Skill type (always 'role')")
+    description: str = Field(..., description="Role description")
+    version: str = Field(default="1.0.0", description="Skill version")
+    author: Optional[str] = Field(default=None, description="Skill author")
+    
+    workflow: str = Field(..., description="Default workflow skill to use")
+    default_mode: SkillMode = Field(default=SkillMode.COPILOT, description="Default execution mode")
+    
+    preferences: List[str] = Field(default_factory=list, description="Role preferences/mindset")
+    system_prompt: Optional[str] = Field(default=None, description="System prompt for this role")
+    trigger: Optional[str] = Field(default=None, description="When to trigger this role")
+    goal: Optional[str] = Field(default=None, description="Goal of this role")
+
+
+# ============================================================================
+# Unified Skill Loader
+# ============================================================================
+
+class SkillLoader:
+    """Loader for the three-level skill architecture."""
+    
+    def __init__(self, resources_dir: Path):
+        self.resources_dir = resources_dir
+        self._atoms: Dict[str, AtomSkillMetadata] = {}
+        self._workflows: Dict[str, WorkflowSkillMetadata] = {}
+        self._roles: Dict[str, RoleSkillMetadata] = {}
+    
+    def load_all(self) -> None:
+        """Load all skills from resources directory."""
+        self._load_atoms()
+        self._load_workflows()
+        self._load_roles()
+    
+    def _load_atoms(self) -> None:
+        """Load atom skills from resources/atoms/.
+        
+        Only loads files starting with 'atom-' prefix.
+        """
+        atoms_dir = self.resources_dir / "atoms"
+        if not atoms_dir.exists():
+            return
+        
+        for skill_file in atoms_dir.glob("atom-*.yaml"):
+            try:
+                data = yaml.safe_load(skill_file.read_text())
+                atom = AtomSkillMetadata(**data)
+                self._atoms[atom.name] = atom
+            except Exception as e:
+                print(f"Failed to load atom skill {skill_file}: {e}")
+    
+    def _load_workflows(self) -> None:
+        """Load workflow skills from resources/workflows/.
+        
+        Only loads files starting with 'workflow-' prefix.
+        """
+        workflows_dir = self.resources_dir / "workflows"
+        if not workflows_dir.exists():
+            return
+        
+        for skill_file in workflows_dir.glob("workflow-*.yaml"):
+            try:
+                data = yaml.safe_load(skill_file.read_text())
+                workflow = WorkflowSkillMetadata(**data)
+                self._workflows[workflow.name] = workflow
+            except Exception as e:
+                print(f"Failed to load workflow skill {skill_file}: {e}")
+    
+    def _load_roles(self) -> None:
+        """Load role skills from resources/roles/.
+        
+        Only loads files starting with 'role-' prefix to avoid conflicts
+        with legacy role definitions.
+        """
+        roles_dir = self.resources_dir / "roles"
+        if not roles_dir.exists():
+            return
+        
+        for skill_file in roles_dir.glob("role-*.yaml"):
+            try:
+                data = yaml.safe_load(skill_file.read_text())
+                role = RoleSkillMetadata(**data)
+                self._roles[role.name] = role
+            except Exception as e:
+                print(f"Failed to load role skill {skill_file}: {e}")
+    
+    def get_atom(self, name: str) -> Optional[AtomSkillMetadata]:
+        """Get an atom skill by name."""
+        return self._atoms.get(name)
+    
+    def get_workflow(self, name: str) -> Optional[WorkflowSkillMetadata]:
+        """Get a workflow skill by name."""
+        return self._workflows.get(name)
+    
+    def get_role(self, name: str) -> Optional[RoleSkillMetadata]:
+        """Get a role skill by name."""
+        return self._roles.get(name)
+    
+    def list_atoms(self) -> List[AtomSkillMetadata]:
+        """List all atom skills."""
+        return list(self._atoms.values())
+    
+    def list_workflows(self) -> List[WorkflowSkillMetadata]:
+        """List all workflow skills."""
+        return list(self._workflows.values())
+    
+    def list_roles(self) -> List[RoleSkillMetadata]:
+        """List all role skills."""
+        return list(self._roles.values())
+    
+    def resolve_role_workflow(self, role_name: str) -> Optional[WorkflowSkillMetadata]:
+        """Resolve a role to its workflow."""
+        role = self.get_role(role_name)
+        if role:
+            return self.get_workflow(role.workflow)
+        return None
+    
+    def validate_workflow(self, workflow_name: str) -> List[str]:
+        """Validate a workflow's dependencies are satisfied."""
+        errors = []
+        workflow = self.get_workflow(workflow_name)
+        if not workflow:
+            return [f"Workflow '{workflow_name}' not found"]
+        
+        for dep in workflow.dependencies:
+            if not self.get_atom(dep):
+                errors.append(f"Missing atom skill dependency: {dep}")
+        
+        for stage in workflow.stages:
+            # Virtual stages (decision points) don't need atom skills
+            if not stage.atom_skill or not stage.operation:
+                continue
+                
+            atom = self.get_atom(stage.atom_skill)
+            if not atom:
+                errors.append(f"Stage '{stage.name}' uses unknown atom skill: {stage.atom_skill}")
+            else:
+                op_names = [op.name for op in atom.operations]
+                if stage.operation not in op_names:
+                    errors.append(
+                        f"Stage '{stage.name}' uses unknown operation '{stage.operation}' "
+                        f"in atom skill '{stage.atom_skill}'"
+                    )
+        
+        return errors