monoco-toolkit 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

monoco/core/config.py

@@ -2,8 +2,18 @@ import os
 import yaml
 from pathlib import Path
 from typing import Optional, Dict, Any
+from enum import Enum
 from pydantic import BaseModel, Field
 
+import logging
+
+# Import AgentIntegration for type hints
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from monoco.core.integrations import AgentIntegration
+
+logger = logging.getLogger("monoco.core.config")
+
 class PathsConfig(BaseModel):
     """Configuration for directory paths."""
     root: str = Field(default=".", description="Project root directory")
@@ -37,6 +47,16 @@ class TelemetryConfig(BaseModel):
     """Configuration for Telemetry."""
     enabled: Optional[bool] = Field(default=None, description="Whether telemetry is enabled")
 
+class AgentConfig(BaseModel):
+    """Configuration for Agent Environment Integration."""
+    targets: Optional[list[str]] = Field(default=None, description="Specific target files to inject into (e.g. .cursorrules)")
+    framework: Optional[str] = Field(default=None, description="Manually specified agent framework (cursor, windsurf, etc.)")
+    includes: Optional[list[str]] = Field(default=None, description="List of specific features to include in injection")
+    integrations: Optional[Dict[str, Any]] = Field(
+        default=None, 
+        description="Custom agent framework integrations (overrides defaults from monoco.core.integrations)"
+    )
+
 class MonocoConfig(BaseModel):
     """
     Main Configuration Schema.
@@ -48,6 +68,7 @@ class MonocoConfig(BaseModel):
     i18n: I18nConfig = Field(default_factory=I18nConfig)
     ui: UIConfig = Field(default_factory=UIConfig)
     telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig)
+    agent: AgentConfig = Field(default_factory=AgentConfig)
 
     @staticmethod
     def _deep_merge(base: Dict[str, Any], update: Dict[str, Any]) -> Dict[str, Any]:
@@ -73,7 +94,11 @@ class MonocoConfig(BaseModel):
         # Determine project path
         cwd = Path(project_root) if project_root else Path.cwd()
         proj_path_hidden = cwd / ".monoco" / "config.yaml"
-        proj_path_root = cwd / "monoco.yaml"
+        
+        # [Legacy] Check for monoco.yaml and warn
+        proj_path_legacy = cwd / "monoco.yaml"
+        if proj_path_legacy.exists():
+            logger.warning(f"Legacy configuration found: {proj_path_legacy}. Please move it to .monoco/config.yaml")
 
         # 3. Load User Config
         if home_path.exists():
@@ -86,14 +111,10 @@ class MonocoConfig(BaseModel):
                 # We don't want to crash on config load fail, implementing simple warning equivalent
                 pass
 
-        # 4. Load Project Config (prefer .monoco/config.yaml, fallback to monoco.yaml)
-        target_proj_conf = proj_path_hidden if proj_path_hidden.exists() else (
-            proj_path_root if proj_path_root.exists() else None
-        )
-
-        if target_proj_conf:
+        # 4. Load Project Config (Only .monoco/config.yaml)
+        if proj_path_hidden.exists():
             try:
-                with open(target_proj_conf, "r") as f:
+                with open(proj_path_hidden, "r") as f:
                     proj_config = yaml.safe_load(f)
                     if proj_config:
                         cls._deep_merge(config_data, proj_config)
@@ -111,3 +132,34 @@ def get_config(project_root: Optional[str] = None) -> MonocoConfig:
     if _settings is None or project_root is not None:
         _settings = MonocoConfig.load(project_root)
     return _settings
+
+class ConfigScope(str, Enum):
+    GLOBAL = "global"
+    PROJECT = "project"
+
+def get_config_path(scope: ConfigScope, project_root: Optional[str] = None) -> Path:
+    """Get the path to the configuration file for a given scope."""
+    if scope == ConfigScope.GLOBAL:
+        return Path.home() / ".monoco" / "config.yaml"
+    else:
+        cwd = Path(project_root) if project_root else Path.cwd()
+        return cwd / ".monoco" / "config.yaml"
+
+def load_raw_config(scope: ConfigScope, project_root: Optional[str] = None) -> Dict[str, Any]:
+    """Load raw configuration dictionary from a specific scope."""
+    path = get_config_path(scope, project_root)
+    if not path.exists():
+        return {}
+    try:
+        with open(path, "r") as f:
+            return yaml.safe_load(f) or {}
+    except Exception as e:
+        logger.warning(f"Failed to load config from {path}: {e}")
+        return {}
+
+def save_raw_config(scope: ConfigScope, data: Dict[str, Any], project_root: Optional[str] = None) -> None:
+    """Save raw configuration dictionary to a specific scope."""
+    path = get_config_path(scope, project_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        yaml.dump(data, f, default_flow_style=False)

monoco/core/feature.py

@@ -0,0 +1,58 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+@dataclass
+class IntegrationData:
+    """
+    Data collection returned by a feature for integration into the Agent environment.
+    """
+    # System Prompts to be injected into agent configuration (e.g., .cursorrules)
+    # Key: Section Title (e.g., "Issue Management"), Value: Markdown Content
+    system_prompts: Dict[str, str] = field(default_factory=dict)
+    
+    # Paths to skill directories or files to be copied/symlinked
+    # DEPRECATED: Skill distribution is cancelled. Only prompts are synced.
+    skills: List[Path] = field(default_factory=list)
+
+class MonocoFeature(ABC):
+    """
+    Abstract base class for all Monoco features.
+    Features must implement this protocol to participate in init and sync lifecycles.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for the feature (e.g., 'issue', 'spike')."""
+        pass
+
+    @abstractmethod
+    def initialize(self, root: Path, config: Dict) -> None:
+        """
+        Lifecycle hook: Physical Structure Initialization.
+        Called during `monoco init`.
+        Responsible for creating necessary directories, files, and config templates.
+        
+        Args:
+            root: The root directory of the project.
+            config: The full project configuration dictionary.
+        """
+        pass
+
+    @abstractmethod
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        """
+        Lifecycle hook: Agent Environment Integration.
+        Called during `monoco sync`.
+        Responsible for returning data (prompts, skills) needed for the Agent Setup.
+        
+        Args:
+            root: The root directory of the project.
+            config: The full project configuration dictionary.
+            
+        Returns:
+            IntegrationData object containing prompts and skills.
+        """
+        pass

monoco/core/injection.py

@@ -0,0 +1,196 @@
+import re
+from pathlib import Path
+from typing import Dict, List, Optional
+
+class PromptInjector:
+    """
+    Engine for injecting managed content into Markdown-like files (e.g., .cursorrules, GEMINI.md).
+    Maintains a 'Managed Block' defined by a specific header.
+    """
+
+    MANAGED_HEADER = "## Monoco Toolkit"
+    
+    def __init__(self, target_file: Path):
+        self.target_file = target_file
+
+    def inject(self, prompts: Dict[str, str]) -> bool:
+        """
+        Injects the provided prompts into the target file.
+        
+        Args:
+            prompts: A dictionary where key is the section title and value is the content.
+            
+        Returns:
+            True if changes were written, False otherwise.
+        """
+        current_content = ""
+        if self.target_file.exists():
+            current_content = self.target_file.read_text(encoding="utf-8")
+
+        new_content = self._merge_content(current_content, prompts)
+        
+        if new_content != current_content:
+            self.target_file.write_text(new_content, encoding="utf-8")
+            return True
+        return False
+
+    def _merge_content(self, original: str, prompts: Dict[str, str]) -> str:
+        """
+        Merges the generated prompts into the original content within the managed block.
+        """
+        # 1. Generate the new managed block content
+        managed_block = [self.MANAGED_HEADER, ""]
+        managed_block.append("> **Auto-Generated**: This section is managed by Monoco. Do not edit manually.\n")
+        
+        for title, content in prompts.items():
+            managed_block.append(f"### {title}")
+            managed_block.append("") # Blank line after header
+            
+            # Sanitize content: remove leading header if it matches the title
+            clean_content = content.strip()
+            # Regex to match optional leading hash header matching the title (case insensitive)
+            # e.g. "### Issue Management" or "# Issue Management"
+            pattern = r"^(#+\s*)" + re.escape(title) + r"\s*\n"
+            match = re.match(pattern, clean_content, re.IGNORECASE)
+            
+            if match:
+                clean_content = clean_content[match.end():].strip()
+            
+            managed_block.append(clean_content)
+            managed_block.append("") # Blank line after section
+
+        managed_block_str = "\n".join(managed_block).strip() + "\n"
+
+        # 2. Find and replace/append in the original content
+        lines = original.splitlines()
+        start_idx = -1
+        end_idx = -1
+        
+        # Find start
+        for i, line in enumerate(lines):
+            if line.strip() == self.MANAGED_HEADER:
+                start_idx = i
+                break
+        
+        if start_idx == -1:
+            # Block not found, append to end
+            if original and not original.endswith("\n"):
+                return original + "\n\n" + managed_block_str
+            elif original:
+                return original + "\n" + managed_block_str
+            else:
+                return managed_block_str
+
+        # Find end: Look for next header of level 1 (assuming Managed Header is H1)
+        # Or EOF
+        # Note: If MANAGED_HEADER is "# ...", we look for next "# ..."
+        # But allow "## ..." as children.
+        
+        header_level_match = re.match(r"^(#+)\s", self.MANAGED_HEADER)
+        header_level_prefix = header_level_match.group(1) if header_level_match else "#"
+        
+        for i in range(start_idx + 1, len(lines)):
+            line = lines[i]
+            # Check if this line is a header of the same level or higher (fewer #s)
+            # e.g. if Managed is "###", then "#" and "##" are higher/parents, "###" is sibling.
+            # We treat siblings as end of block too.
+            if line.startswith("#"):
+                 # Match regex to get level
+                 match = re.match(r"^(#+)\s", line)
+                 if match:
+                     level = match.group(1)
+                     if len(level) <= len(header_level_prefix):
+                         end_idx = i
+                         break
+        
+        if end_idx == -1:
+            end_idx = len(lines)
+
+        # 3. Construct result
+        pre_block = "\n".join(lines[:start_idx])
+        post_block = "\n".join(lines[end_idx:])
+        
+        result = pre_block
+        if result:
+             result += "\n\n"
+        
+        result += managed_block_str
+        
+        if post_block:
+            # Ensure separation if post block exists and isn't just empty lines
+            if post_block.strip():
+                result += "\n" + post_block
+            else:
+                result += post_block # Keep trailing newlines if any, or normalize?
+                
+        return result.strip() + "\n"
+
+    def remove(self) -> bool:
+        """
+        Removes the managed block from the target file.
+
+        Returns:
+            True if changes were written (block removed), False otherwise.
+        """
+        if not self.target_file.exists():
+            return False
+
+        current_content = self.target_file.read_text(encoding="utf-8")
+        lines = current_content.splitlines()
+
+        start_idx = -1
+        end_idx = -1
+
+        # Find start
+        for i, line in enumerate(lines):
+            if line.strip() == self.MANAGED_HEADER:
+                start_idx = i
+                break
+
+        if start_idx == -1:
+            return False
+
+        # Find end: exact logic as in _merge_content
+        header_level_match = re.match(r"^(#+)\s", self.MANAGED_HEADER)
+        header_level_prefix = header_level_match.group(1) if header_level_match else "#"
+
+        for i in range(start_idx + 1, len(lines)):
+            line = lines[i]
+            if line.startswith("#"):
+                 match = re.match(r"^(#+)\s", line)
+                 if match:
+                     level = match.group(1)
+                     if len(level) <= len(header_level_prefix):
+                         end_idx = i
+                         break
+        
+        if end_idx == -1:
+            end_idx = len(lines)
+
+        # Reconstruct content without the block
+        # We also need to be careful about surrounding newlines to avoid leaving gaps
+        
+        # Check lines before start_idx
+        while start_idx > 0 and not lines[start_idx-1].strip():
+            start_idx -= 1
+        
+        # Check lines after end_idx (optional, but good for cleanup)
+        # Usually end_idx points to the next header or EOF.
+        # If it points to next header, we keep it.
+
+        pre_block = lines[:start_idx]
+        post_block = lines[end_idx:]
+
+        # If we removed everything, the file might become empty or just newlines
+        
+        new_lines = pre_block + post_block
+        if not new_lines:
+             new_content = ""
+        else:
+             new_content = "\n".join(new_lines).strip() + "\n"
+
+        if new_content != current_content:
+            self.target_file.write_text(new_content, encoding="utf-8")
+            return True
+
+        return False

monoco/core/integrations.py

@@ -0,0 +1,181 @@
+"""
+Core Integration Registry for Agent Frameworks.
+
+This module provides a centralized registry for managing integrations with various
+agent frameworks (Cursor, Claude, Gemini, Qwen, Antigravity, etc.).
+
+It defines the standard structure for framework integrations and provides utilities
+for detection and configuration.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class AgentIntegration(BaseModel):
+    """
+    Configuration for a single agent framework integration.
+    
+    Attributes:
+        key: Unique identifier for the framework (e.g., 'cursor', 'gemini')
+        name: Human-readable name of the framework
+        system_prompt_file: Path to the system prompt/rules file relative to project root
+        skill_root_dir: Path to the skills directory relative to project root
+        enabled: Whether this integration is active (default: True)
+    """
+    key: str = Field(..., description="Unique framework identifier")
+    name: str = Field(..., description="Human-readable framework name")
+    system_prompt_file: str = Field(..., description="Path to system prompt file (relative to project root)")
+    skill_root_dir: str = Field(..., description="Path to skills directory (relative to project root)")
+    enabled: bool = Field(default=True, description="Whether this integration is active")
+
+
+# Default Integration Registry
+DEFAULT_INTEGRATIONS: Dict[str, AgentIntegration] = {
+    "cursor": AgentIntegration(
+        key="cursor",
+        name="Cursor",
+        system_prompt_file=".cursorrules",
+        skill_root_dir=".cursor/skills/",
+    ),
+    "claude": AgentIntegration(
+        key="claude",
+        name="Claude Code",
+        system_prompt_file="CLAUDE.md",
+        skill_root_dir=".claude/skills/",
+    ),
+    "gemini": AgentIntegration(
+        key="gemini",
+        name="Gemini CLI",
+        system_prompt_file="GEMINI.md",
+        skill_root_dir=".gemini/skills/",
+    ),
+    "qwen": AgentIntegration(
+        key="qwen",
+        name="Qwen Code",
+        system_prompt_file="QWEN.md",
+        skill_root_dir=".qwen/skills/",
+    ),
+    "agent": AgentIntegration(
+        key="agent",
+        name="Antigravity",
+        system_prompt_file="GEMINI.md",
+        skill_root_dir=".agent/skills/",
+    ),
+}
+
+
+def get_integration(
+    name: str,
+    config_overrides: Optional[Dict[str, AgentIntegration]] = None
+) -> Optional[AgentIntegration]:
+    """
+    Get an agent integration by name.
+    
+    Args:
+        name: The framework key (e.g., 'cursor', 'gemini')
+        config_overrides: Optional user-defined integrations from config
+        
+    Returns:
+        AgentIntegration if found, None otherwise
+        
+    Priority:
+        1. User config overrides
+        2. Default registry
+    """
+    # Check user overrides first
+    if config_overrides and name in config_overrides:
+        return config_overrides[name]
+    
+    # Fall back to defaults
+    return DEFAULT_INTEGRATIONS.get(name)
+
+
+def get_all_integrations(
+    config_overrides: Optional[Dict[str, AgentIntegration]] = None,
+    enabled_only: bool = True
+) -> Dict[str, AgentIntegration]:
+    """
+    Get all available integrations.
+    
+    Args:
+        config_overrides: Optional user-defined integrations from config
+        enabled_only: If True, only return enabled integrations
+        
+    Returns:
+        Dictionary of all integrations (merged defaults + overrides)
+    """
+    # Start with defaults
+    all_integrations = DEFAULT_INTEGRATIONS.copy()
+    
+    # Merge user overrides
+    if config_overrides:
+        all_integrations.update(config_overrides)
+    
+    # Filter by enabled status if requested
+    if enabled_only:
+        return {k: v for k, v in all_integrations.items() if v.enabled}
+    
+    return all_integrations
+
+
+def detect_frameworks(root: Path) -> List[str]:
+    """
+    Auto-detect which agent frameworks are present in the project.
+    
+    Detection is based on the existence of characteristic files/directories
+    for each framework.
+    
+    Args:
+        root: Project root directory
+        
+    Returns:
+        List of detected framework keys (e.g., ['cursor', 'gemini'])
+        
+    Example:
+        >>> root = Path("/path/to/project")
+        >>> frameworks = detect_frameworks(root)
+        >>> print(frameworks)
+        ['cursor', 'gemini']
+    """
+    detected = []
+    
+    for key, integration in DEFAULT_INTEGRATIONS.items():
+        # Check if system prompt file exists
+        prompt_file = root / integration.system_prompt_file
+        
+        # Check if skill directory exists
+        skill_dir = root / integration.skill_root_dir
+        
+        # Consider framework present if either exists
+        if prompt_file.exists() or skill_dir.exists():
+            detected.append(key)
+    
+    return detected
+
+
+def get_active_integrations(
+    root: Path,
+    config_overrides: Optional[Dict[str, AgentIntegration]] = None,
+    auto_detect: bool = True
+) -> Dict[str, AgentIntegration]:
+    """
+    Get integrations that are both enabled and detected in the project.
+    
+    Args:
+        root: Project root directory
+        config_overrides: Optional user-defined integrations from config
+        auto_detect: If True, only return integrations detected in the project
+        
+    Returns:
+        Dictionary of active integrations
+    """
+    all_integrations = get_all_integrations(config_overrides, enabled_only=True)
+    
+    if not auto_detect:
+        return all_integrations
+    
+    # Filter by detection
+    detected_keys = detect_frameworks(root)
+    return {k: v for k, v in all_integrations.items() if k in detected_keys}

monoco/core/registry.py

@@ -0,0 +1,36 @@
+from typing import Dict, List, Type
+from monoco.core.feature import MonocoFeature
+
+class FeatureRegistry:
+    _features: Dict[str, MonocoFeature] = {}
+
+    @classmethod
+    def register(cls, feature: MonocoFeature):
+        """Register a feature instance."""
+        cls._features[feature.name] = feature
+
+    @classmethod
+    def get_features(cls) -> List[MonocoFeature]:
+        """Get all registered features."""
+        return list(cls._features.values())
+
+    @classmethod
+    def get_feature(cls, name: str) -> MonocoFeature:
+        """Get a specific feature by name."""
+        return cls._features.get(name)
+
+    @classmethod
+    def load_defaults(cls):
+        """
+        Load default core features.
+        TODO: In the future, this could be dynamic via entry points.
+        """
+        # 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
+        
+        cls.register(IssueFeature())
+        cls.register(SpikeFeature())
+        cls.register(I18nFeature())
+        pass

monoco/core/resources/en/AGENTS.md

@@ -0,0 +1,8 @@
+### Monoco Core
+
+Core toolkit commands for project management.
+
+- **Init**: `monoco init` (Initialize new Monoco project)
+- **Config**: `monoco config get|set <key> [value]` (Manage configuration)
+- **Sync**: `monoco sync` (Synchronize with agent environments)
+- **Uninstall**: `monoco uninstall` (Clean up agent integrations)

monoco/core/resources/en/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: monoco-core
+description: Core skill for Monoco Toolkit. Provides essential commands for project initialization, configuration, and workspace management.
+---
+
+# Monoco Core
+
+Core functionality and commands for the Monoco Toolkit.
+
+## Overview
+
+Monoco is a developer productivity toolkit that provides:
+
+- **Project initialization** with standardized structure
+- **Configuration management** at global and project levels
+- **Workspace management** for multi-project setups
+
+## Key Commands
+
+### Project Setup
+
+- **`monoco init`**: Initialize a new Monoco project
+  - Creates `.monoco/` directory with default configuration
+  - Sets up project structure (Issues/, .references/, etc.)
+  - Generates initial documentation
+
+### Configuration
+
+- **`monoco config`**: Manage configuration
+  - `monoco config get <key>`: View configuration value
+  - `monoco config set <key> <value>`: Update configuration
+  - Supports both global (`~/.monoco/config.yaml`) and project (`.monoco/config.yaml`) scopes
+
+### Agent Integration
+
+- **`monoco sync`**: Synchronize with agent environments
+
+  - Injects system prompts into agent configuration files (GEMINI.md, CLAUDE.md, etc.)
+  - Distributes skills to agent framework directories
+  - Respects language configuration from `i18n.source_lang`
+
+- **`monoco uninstall`**: Clean up agent integrations
+  - Removes managed blocks from agent configuration files
+  - Cleans up distributed skills
+
+## Configuration Structure
+
+Configuration is stored in YAML format at:
+
+- **Global**: `~/.monoco/config.yaml`
+- **Project**: `.monoco/config.yaml`
+
+Key configuration sections:
+
+- `core`: Editor, log level, author
+- `paths`: Directory paths (issues, spikes, specs)
+- `project`: Project metadata, spike repos, workspace members
+- `i18n`: Internationalization settings
+- `agent`: Agent framework integration settings
+
+## Best Practices
+
+1. **Use CLI commands** instead of manual file editing when possible
+2. **Run `monoco sync`** after configuration changes to update agent environments
+3. **Commit `.monoco/config.yaml`** to version control for team consistency
+4. **Keep global config minimal** - most settings should be project-specific

monoco/core/resources/zh/AGENTS.md

@@ -0,0 +1,8 @@
+### Monoco 核心
+
+项目管理的核心工具包命令。
+
+- **初始化**: `monoco init` (初始化新的 Monoco 项目)
+- **配置**: `monoco config get|set <key> [value]` (管理配置)
+- **同步**: `monoco sync` (与 agent 环境同步)
+- **卸载**: `monoco uninstall` (清理 agent 集成)