monoco-toolkit 0.1.0__py3-none-any.whl → 0.2.5__py3-none-any.whl

monoco/core/integrations.py

@@ -0,0 +1,234 @@
+"""
+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
+        bin_name: Optional name of the binary to check for (e.g., 'cursor', 'gemini')
+        version_cmd: Optional command to check version (e.g., '--version')
+        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)")
+    bin_name: Optional[str] = Field(None, description="Binary name to check for availability")
+    version_cmd: Optional[str] = Field(None, description="Command to check version")
+    enabled: bool = Field(default=True, description="Whether this integration is active")
+
+    def check_health(self) -> "AgentProviderHealth":
+        """
+        Check health of this integration.
+        """
+        import shutil
+        import subprocess
+        import time
+
+        if not self.bin_name:
+            return AgentProviderHealth(available=True) # If no binary required, assume ok
+
+        bin_path = shutil.which(self.bin_name)
+        if not bin_path:
+            return AgentProviderHealth(available=False, error=f"Binary '{self.bin_name}' not found in PATH")
+
+        if not self.version_cmd:
+             return AgentProviderHealth(available=True, path=bin_path)
+
+        start_time = time.time()
+        try:
+            # We use a shortcut to check version cmd
+            # Some tools might need e.g. 'cursor --version'
+            subprocess.run(
+                [self.bin_name] + self.version_cmd.split(),
+                check=True,
+                capture_output=True,
+                timeout=5
+            )
+            latency = int((time.time() - start_time) * 1000)
+            return AgentProviderHealth(available=True, path=bin_path, latency_ms=latency)
+        except Exception as e:
+            return AgentProviderHealth(available=False, path=bin_path, error=str(e))
+
+
+class AgentProviderHealth(BaseModel):
+    """Health check result for an agent provider."""
+    available: bool
+    path: Optional[str] = None
+    error: Optional[str] = None
+    latency_ms: Optional[int] = None
+
+
+# Default Integration Registry
+DEFAULT_INTEGRATIONS: Dict[str, AgentIntegration] = {
+    "cursor": AgentIntegration(
+        key="cursor",
+        name="Cursor",
+        system_prompt_file=".cursorrules",
+        skill_root_dir=".cursor/skills/",
+        bin_name="cursor",
+        version_cmd="--version",
+    ),
+    "claude": AgentIntegration(
+        key="claude",
+        name="Claude Code",
+        system_prompt_file="CLAUDE.md",
+        skill_root_dir=".claude/skills/",
+        bin_name="claude",
+        version_cmd="--version",
+    ),
+    "gemini": AgentIntegration(
+        key="gemini",
+        name="Gemini CLI",
+        system_prompt_file="GEMINI.md",
+        skill_root_dir=".gemini/skills/",
+        bin_name="gemini",
+        version_cmd="--version",
+    ),
+    "qwen": AgentIntegration(
+        key="qwen",
+        name="Qwen Code",
+        system_prompt_file="QWEN.md",
+        skill_root_dir=".qwen/skills/",
+        bin_name="qwen",
+        version_cmd="--version",
+    ),
+    "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/lsp.py

@@ -0,0 +1,61 @@
+from enum import IntEnum
+from typing import List, Optional, Union
+from pydantic import BaseModel
+
+class Position(BaseModel):
+    """
+    Position in a text document expressed as zero-based line and character offset.
+    """
+    line: int
+    character: int
+
+    def __lt__(self, other):
+        if self.line != other.line:
+            return self.line < other.line
+        return self.character < other.character
+
+class Range(BaseModel):
+    """
+    A range in a text document expressed as (zero-based) start and end positions.
+    """
+    start: Position
+    end: Position
+
+    def __repr__(self):
+        return f"{self.start.line}:{self.start.character}-{self.end.line}:{self.end.character}"
+
+class DiagnosticSeverity(IntEnum):
+    Error = 1
+    Warning = 2
+    Information = 3
+    Hint = 4
+
+class DiagnosticRelatedInformation(BaseModel):
+    """
+    Represents a related message and source code location for a diagnostic.
+    """
+    # location: Location  # Defined elsewhere or simplified here
+    message: str
+
+class Diagnostic(BaseModel):
+    """
+    Represents a diagnostic, such as a compiler error or warning.
+    """
+    range: Range
+    severity: Optional[DiagnosticSeverity] = None
+    code: Optional[Union[int, str]] = None
+    source: Optional[str] = "monoco"
+    message: str
+    related_information: Optional[List[DiagnosticRelatedInformation]] = None
+    data: Optional[dict] = None  # To carry extra info (e.g. for code actions)
+
+    def to_user_string(self) -> str:
+        """Helper to format for CLI output"""
+        severity_map = {
+            1: "[red]Error[/red]",
+            2: "[yellow]Warning[/yellow]",
+            3: "[blue]Info[/blue]",
+            4: "[dim]Hint[/dim]"
+        }
+        sev = severity_map.get(self.severity, "Error")
+        return f"{sev}: {self.message} (Line {self.range.start.line + 1})"

monoco/core/output.py

@@ -24,8 +24,8 @@ class OutputManager:
         """
         Check if running in Agent Mode.
         Triggers:
-        1. Environment variable AGENT_FLAG=true (or 1)
-        2. Environment variable MONOCO_AGENT=true (or 1)
+            1. Environment variable AGENT_FLAG=true (or 1)
+            2. Environment variable MONOCO_AGENT=true (or 1)
         """
         return os.getenv("AGENT_FLAG", "").lower() in ("true", "1") or \
                os.getenv("MONOCO_AGENT", "").lower() in ("true", "1")
@@ -40,6 +40,16 @@ class OutputManager:
         else:
             OutputManager._render_human(data, title)
 
+    @staticmethod
+    def error(message: str):
+        """
+        Print error message.
+        """
+        if OutputManager.is_agent_mode():
+            print(json.dumps({"error": message}))
+        else:
+            rprint(f"[bold red]Error:[/bold red] {message}")
+
     @staticmethod
     def _render_agent(data: Any):
         """
@@ -95,3 +105,4 @@ class OutputManager:
 
 # Global helper
 print_output = OutputManager.print
+print_error = OutputManager.error

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`: 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 集成)

monoco/core/resources/zh/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: monoco-core
+description: Monoco Toolkit 的核心技能。提供项目初始化、配置管理和工作空间管理的基础命令。
+---
+
+# Monoco 核心
+
+Monoco Toolkit 的核心功能和命令。
+
+## 概述
+
+Monoco 是一个开发者生产力工具包，提供：
+
+- **项目初始化**：标准化的项目结构
+- **配置管理**：全局和项目级别的配置
+- **工作空间管理**：多项目设置
+
+## 核心命令
+
+### 项目设置
+
+- **`monoco init`**: 初始化新的 Monoco 项目
+  - 创建 `.monoco/` 目录及默认配置
+  - 设置项目结构（Issues/, .references/ 等）
+  - 生成初始文档
+
+### 配置管理
+
+- **`monoco config`**: 管理配置
+  - `monoco config get <key>`: 查看配置值
+  - `monoco config set <key> <value>`: 更新配置
+  - 支持全局（`~/.monoco/config.yaml`）和项目（`.monoco/config.yaml`）作用域
+
+### Agent 集成
+
+- **`monoco sync`**: 与 agent 环境同步
+
+  - 将系统提示注入到 agent 配置文件（GEMINI.md, CLAUDE.md 等）
+  - 分发 skills 到 agent 框架目录
+  - 遵循 `i18n.source_lang` 的语言配置
+
+- **`monoco uninstall`**: 清理 agent 集成
+  - 从 agent 配置文件中移除托管块
+  - 清理已分发的 skills
+
+## 配置结构
+
+配置以 YAML 格式存储在：
+
+- **全局**: `~/.monoco/config.yaml`
+- **项目**: `.monoco/config.yaml`
+
+关键配置段：
+
+- `core`: 编辑器、日志级别、作者
+- `paths`: 目录路径（issues, spikes, specs）
+- `project`: 项目元数据、spike repos、工作空间成员
+- `i18n`: 国际化设置
+- `agent`: Agent 框架集成设置
+
+## 最佳实践
+
+1. **优先使用 CLI 命令**，而不是手动编辑文件
+2. **配置更改后运行 `monoco sync`** 以更新 agent 环境
+3. **将 `.monoco/config.yaml` 提交到版本控制**，保持团队一致性
+4. **保持全局配置最小化** - 大多数设置应该是项目特定的