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

monoco/features/pty/router.py

@@ -0,0 +1,138 @@
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, Query
+from pydantic import BaseModel
+from typing import Optional, Dict
+import json
+import asyncio
+import logging
+import os
+from pathlib import Path
+from monoco.features.pty.core import PTYManager
+from monoco.core.config import get_config
+
+# We will use dependency injection or a global singleton for now
+# Ideally attached to app state
+pty_manager = PTYManager()
+
+router = APIRouter(prefix="/api/v1/pty", tags=["pty"])
+
+logger = logging.getLogger("monoco.pty")
+
+@router.websocket("/ws/{session_id}")
+async def websocket_pty_endpoint(
+    websocket: WebSocket, 
+    session_id: str,
+    cwd: Optional[str] = Query(None),
+    cols: int = Query(80), 
+    rows: int = Query(24),
+    env: Optional[str] = Query(None) # JSON-encoded env vars
+):
+    await websocket.accept()
+    
+    # Determine working directory
+    # 1. Provide explicit CWD in query
+    # 2. Or fallback to ProjectRoot from env (if integrated)
+    # 3. Or fallback to process CWD
+    
+    # Since monoco pty runs as a separate service, we expect CWD to be passed
+    # or we default to where monoco pty was started
+    working_dir = cwd if cwd else os.getcwd()
+    
+    # Prepare environment
+    env_vars = os.environ.copy()
+    env_vars["TERM"] = "xterm-256color"
+    env_vars["COLORTERM"] = "truecolor"
+    if "SHELL" not in env_vars:
+        env_vars["SHELL"] = "/bin/zsh"
+    if "HOME" not in env_vars:
+        import pathlib
+        env_vars["HOME"] = str(pathlib.Path.home())
+
+    # Filter out Trae/Gemini specific variables to avoid shell integration conflicts
+    # This prevents the shell from trying to write to IDE-specific logs which causes EPERM
+    keys_to_remove = [k for k in env_vars.keys() if k.startswith("TRAE_") or k.startswith("GEMINI_") or k == "AI_AGENT"]
+    for k in keys_to_remove:
+        del env_vars[k]
+
+    if env:
+        try:
+            custom_env = json.loads(env)
+            env_vars.update(custom_env)
+        except:
+            logger.warning("Failed to parse custom env vars")
+
+    # Start Session
+    try:
+        session = pty_manager.create_session(
+            session_id=session_id, 
+            cwd=working_dir,
+            cmd=["/bin/zsh", "-l"], # Use login shell to ensure full user environment
+            env=env_vars
+        )
+        session.start(cols, rows)
+    except Exception as e:
+        logger.error(f"Failed to start session: {e}")
+        await websocket.close(code=1011)
+        return
+
+    # Pipe Loop
+    reader_task = None
+    try:
+        # Task to read from PTY and send to WebSocket
+        async def pty_reader():
+            while session.running:
+                data = await session.read()
+                if not data:
+                    break
+                # xterm.js expects string or binary. We send string/bytes.
+                # Usually text is fine, but binary is safer for control codes.
+                await websocket.send_bytes(data)
+            
+            # If PTY exits, close WS
+            await websocket.close()
+
+        reader_task = asyncio.create_task(pty_reader())
+
+        # Main loop: Read from WebSocket and write to PTY
+        try:
+            while True:
+                # Receive message from Client (xterm.js)
+                # Message can be simple input string, or a JSON command (resize)
+                message = await websocket.receive()
+                
+                if message["type"] == "websocket.disconnect":
+                    raise WebSocketDisconnect(code=message.get("code", 1000))
+                
+                if "text" in message:
+                    payload = message["text"]
+                    
+                    # Check if it's a control message (Hack: usually client sends raw input)
+                    # We can enforce a protocol: binary for Input, text JSON for Control.
+                    try:
+                        # Try parsing as JSON control message
+                        cmd = json.loads(payload)
+                        if cmd.get("type") == "resize":
+                            session.resize(cmd["cols"], cmd["rows"])
+                            continue
+                    except:
+                        pass # Not JSON, treat as raw input
+                    
+                    session.write(payload.encode())
+                    
+                elif "bytes" in message:
+                    session.write(message["bytes"])
+        except RuntimeError:
+            # Handle "Cannot call 'receive' once a disconnect message has been received"
+            # This happens if Starlette/FastAPI already processed the disconnect internally
+            # but we called receive() again.
+            logger.info(f"Runtime disconnect for session {session_id}")
+
+    except WebSocketDisconnect:
+        logger.info(f"Client disconnected for session {session_id}")
+    except Exception as e:
+        logger.error(f"WebSocket error: {e}")
+    finally:
+        # Cleanup
+        pty_manager.close_session(session_id)
+        if reader_task and not reader_task.done():
+            reader_task.cancel()

monoco/features/pty/server.py

@@ -0,0 +1,56 @@
+import logging
+import signal
+import sys
+from typing import Optional
+from pathlib import Path
+from contextlib import asynccontextmanager
+import uvicorn
+from fastapi import FastAPI
+from monoco.features.pty.router import router as pty_router, pty_manager
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    yield
+    # Shutdown
+    logging.info("Shutting down PTY manager and cleaning up sessions...")
+    pty_manager.close_all_sessions()
+
+def run_pty_server(host: str = "127.0.0.1", port: int = 3124, cwd: Optional[Path] = None):
+    """
+    Entry point for the 'monoco pty' command.
+    """
+    # Configure Logging
+    logging.basicConfig(level=logging.INFO)
+    
+    # Register a manual signal handler to ensure we catch termination even if uvicorn misses it
+    # or if we are stuck before uvicorn starts.
+    def handle_signal(signum, frame):
+        logging.info(f"Received signal {signum}, initiating shutdown...")
+        # We rely on uvicorn to handle the actual exit loop for SIGINT/SIGTERM usually,
+        # but having this log confirms propagation.
+        # If uvicorn is running, it should catch this first. 
+        # If not, we exit manually.
+        sys.exit(0)
+
+    # Note: Uvicorn overwrites SIGINT/SIGTERM handlers by default. 
+    # relying on lifespan is the standard "Uvicorn way".
+    
+    app = FastAPI(title="Monoco PTY Service", lifespan=lifespan)
+    app.include_router(pty_router)
+    
+    # If cwd is provided, we might want to set it as current process CWD
+    # so that new sessions default to it.
+    if cwd and cwd.exists():
+        import os
+        os.chdir(cwd)
+        logging.info(f"PTY Service Root: {cwd}")
+
+    logging.info(f"Starting Monoco PTY Service on ws://{host}:{port}")
+    try:
+        uvicorn.run(app, host=host, port=port)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # Final safety net
+        pty_manager.close_all_sessions()

monoco/features/spike/adapter.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.feature import MonocoFeature, IntegrationData
+from monoco.features.spike import core
+
+class SpikeFeature(MonocoFeature):
+    @property
+    def name(self) -> str:
+        return "spike"
+
+    def initialize(self, root: Path, config: Dict) -> None:
+        spikes_name = config.get("paths", {}).get("spikes", ".references")
+        core.init(root, spikes_name)
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        # Determine language from config, default to 'en'
+        lang = config.get("i18n", {}).get("source_lang", "en")
+        base_dir = Path(__file__).parent / "resources"
+        
+        prompt_file = base_dir / lang / "AGENTS.md"
+        if not prompt_file.exists():
+            prompt_file = base_dir / "en" / "AGENTS.md"
+            
+        content = ""
+        if prompt_file.exists():
+            content = prompt_file.read_text(encoding="utf-8").strip()
+
+        return IntegrationData(
+            system_prompts={"Spike (Research)": content}
+        )

monoco/features/spike/commands.py

@@ -1,15 +1,18 @@
 import typer
 from pathlib import Path
 from rich.console import Console
+from typing import Annotated
 
 from monoco.core.config import get_config
+from monoco.core.output import AgentOutput, OutputManager
 from . import core
 
 app = typer.Typer(help="Spike & Repo Management.")
-console = Console()
 
 @app.command("init")
-def init():
+def init(
+    json: AgentOutput = False,
+):
     """Initialize the Spike environment (gitignore setup)."""
     config = get_config()
     root_dir = Path(config.paths.root)
@@ -20,11 +23,16 @@ def init():
     # Create the directory
     (root_dir / spikes_dir_name).mkdir(exist_ok=True)
     
-    console.print(f"[green]✔[/green] Initialized Spike environment. Added '{spikes_dir_name}/' to .gitignore.")
+    OutputManager.print({
+        "status": "initialized",
+        "directory": spikes_dir_name,
+        "gitignore_updated": True
+    })
 
 @app.command("add")
 def add_repo(
     url: str = typer.Argument(..., help="Git Repository URL"),
+    json: AgentOutput = False,
 ):
     """Add a new research repository."""
     config = get_config()
@@ -38,13 +46,18 @@ def add_repo(
         name = name[:-4]
         
     core.update_config_repos(root_dir, name, url)
-    console.print(f"[green]✔[/green] Added repo [bold]{name}[/bold] ({url}) to configuration.")
-    console.print("Run [bold]monoco spike sync[/bold] to download content.")
+    OutputManager.print({
+        "status": "added",
+        "name": name,
+        "url": url,
+        "message": f"Run 'monoco spike sync' to download content."
+    })
 
 @app.command("remove")
 def remove_repo(
     name: str = typer.Argument(..., help="Repository Name"),
     force: bool = typer.Option(False, "--force", "-f", help="Force delete physical directory without asking"),
+    json: AgentOutput = False,
 ):
     """Remove a repository from configuration."""
     config = get_config()
@@ -52,30 +65,34 @@ def remove_repo(
     spikes_dir = root_dir / config.paths.spikes
     
     if name not in config.project.spike_repos:
-        console.print(f"[yellow]![/yellow] Repo [bold]{name}[/bold] not found in configuration.")
+        OutputManager.error(f"Repo {name} not found in configuration.")
         return
 
     # Remove from config
     core.update_config_repos(root_dir, name, "", remove=True)
-    console.print(f"[green]✔[/green] Removed [bold]{name}[/bold] from configuration.")
     
     target_path = spikes_dir / name
+    deleted = False
     if target_path.exists():
         if force or typer.confirm(f"Do you want to delete the directory {target_path}?", default=False):
             core.remove_repo_dir(spikes_dir, name)
-            console.print(f"[gray]✔[/gray] Deleted directory {target_path}.")
+            deleted = True
         else:
-            console.print(f"[gray]ℹ[/gray] Directory {target_path} kept.")
+            deleted = False
+            
+    OutputManager.print({
+        "status": "removed",
+        "name": name,
+        "directory_deleted": deleted
+    })
 
 @app.command("sync")
-def sync_repos():
+def sync_repos(
+    json: AgentOutput = False,
+):
     """Sync (Clone/Pull) all configured repositories."""
     # Force reload config to get latest updates
     config = get_config()
-    # Note: get_config is a singleton, so for 'add' then 'sync' in same process, 
-    # we rely on 'add' writing to disk and us reading from memory? 
-    # Actually, if we run standard CLI "monoco spike add" then "monoco spike sync", 
-    # they are separate processes, so config loads fresh.
     
     root_dir = Path(config.paths.root)
     spikes_dir = root_dir / config.paths.spikes
@@ -84,27 +101,31 @@ def sync_repos():
     repos = config.project.spike_repos
     
     if not repos:
-        console.print("[yellow]No repositories configured.[/yellow] Use 'monoco spike add <url>' first.")
+        OutputManager.print({"status": "empty", "message": "No repositories configured."}, title="Sync")
         return
         
-    console.print(f"Syncing {len(repos)} repositories...")
+    results = []
     
     for name, url in repos.items():
-        core.sync_repo(root_dir, spikes_dir, name, url)
+        try:
+            core.sync_repo(root_dir, spikes_dir, name, url)
+            results.append({"name": name, "status": "synced", "url": url})
+        except Exception as e:
+             results.append({"name": name, "status": "failed", "error": str(e), "url": url})
         
-    console.print("[green]✔[/green] Sync complete.")
+    OutputManager.print(results, title="Sync Results")
 
-# Alias for list (showing configured repos) could be useful but not strictly asked for.
-# Let's add a simple list command to see what we have.
 @app.command("list")
-def list_repos():
+def list_repos(
+    json: AgentOutput = False,
+):
     """List configured repositories."""
     config = get_config()
     repos = config.project.spike_repos
     
     if not repos:
-        console.print("[yellow]No repositories configured.[/yellow]")
+        OutputManager.print([], title="Repositories")
         return
         
-    for name, url in repos.items():
-        console.print(f"- [bold]{name}[/bold]: {url}")
+    data = [{"name": name, "url": url} for name, url in repos.items()]
+    OutputManager.print(data, title="Repositories")

monoco/features/spike/core.py

@@ -31,17 +31,10 @@ def run_git_command(cmd: List[str], cwd: Path) -> bool:
 
 def get_config_file_path(root: Path) -> Path:
     """Determine the config file to update."""
-    # Priority 1: .monoco/config.yaml
-    hidden = root / ".monoco" / "config.yaml"
-    if hidden.exists():
-        return hidden
+    # Standard: .monoco/project.yaml
+    hidden = root / ".monoco" / "project.yaml"
     
-    # Priority 2: monoco.yaml
-    visible = root / "monoco.yaml"
-    if visible.exists():
-        return visible
-    
-    # Default to .monoco/config.yaml for new files
+    # Ensure parent exists
     hidden.parent.mkdir(exist_ok=True)
     return hidden
 
@@ -131,24 +124,14 @@ This skill normalizes how we introduce external code repositories.
 3. **Remove**: `monoco spike remove <name>`
 """
 
-PROMPT_CONTENT = """### Spike (Research)
-Manage external reference repositories.
-- **Add Repo**: `monoco spike add <url>` (Available in `.reference/<name>` for reading)
-- **Sync**: `monoco spike sync` (Run to download content)
-- **Constraint**: Never edit files in `.reference/`. Treat them as read-only external knowledge."""
-
 def init(root: Path, spikes_dir_name: str):
     """Initialize Spike environment."""
     ensure_gitignore(root, spikes_dir_name)
     (root / spikes_dir_name).mkdir(exist_ok=True)
 
-def get_resources() -> Dict[str, Any]:
     return {
         "skills": {
             "git-repo-spike": SKILL_CONTENT
         },
-        "prompts": {
-            "spike": PROMPT_CONTENT
-        }
+        "prompts": {} # Handled by adapter via resource files
     }
-

monoco/features/spike/resources/en/AGENTS.md

@@ -0,0 +1,7 @@
+### Spike (Research)
+
+Manage external reference repositories.
+
+- **Add Repo**: `monoco spike add <url>` (Available in `.reference/<name>` for reading)
+- **Sync**: `monoco spike sync` (Run to download content)
+- **Constraint**: Never edit files in `.reference/`. Treat them as read-only external knowledge.

monoco/features/spike/resources/en/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: monoco-spike
+description: Manage external reference repositories for research and learning. Provides read-only access to curated codebases.
+---
+
+# Spike (Research)
+
+Manage external reference repositories in Monoco projects.
+
+## Overview
+
+The Spike feature allows you to:
+
+- **Add external repositories** as read-only references
+- **Sync repository content** to local `.references/` directory
+- **Access curated knowledge** without modifying source code
+
+## Key Commands
+
+### Add Repository
+
+```bash
+monoco spike add <url>
+```
+
+Adds an external repository as a reference. The repository will be cloned to `.references/<name>/` where `<name>` is derived from the repository URL.
+
+**Example**:
+
+```bash
+monoco spike add https://github.com/example/awesome-project
+# Available at: .references/awesome-project/
+```
+
+### Sync Repositories
+
+```bash
+monoco spike sync
+```
+
+Downloads or updates all configured spike repositories from `.monoco/config.yaml`.
+
+### List Spikes
+
+```bash
+monoco spike list
+```
+
+Shows all configured spike repositories and their sync status.
+
+## Configuration
+
+Spike repositories are configured in `.monoco/config.yaml`:
+
+```yaml
+project:
+  spike_repos:
+    awesome-project: https://github.com/example/awesome-project
+    another-ref: https://github.com/example/another-ref
+```
+
+## Best Practices
+
+1. **Read-Only Access**: Never edit files in `.references/`. Treat them as external knowledge.
+2. **Curated Selection**: Only add high-quality, relevant repositories.
+3. **Regular Sync**: Run `monoco spike sync` periodically to get updates.
+4. **Commit Configuration**: Add spike repo URLs to version control for team consistency.
+
+## Use Cases
+
+- **Learning from Examples**: Study well-architected codebases
+- **API Reference**: Keep framework documentation locally
+- **Pattern Library**: Maintain a collection of design patterns
+- **Competitive Analysis**: Reference similar projects

monoco/features/spike/resources/zh/AGENTS.md

@@ -0,0 +1,7 @@
+### Spike (研究)
+
+管理外部参考仓库。
+
+- **添加仓库**: `monoco spike add <url>` (在 `.reference/<name>` 中可读)
+- **同步**: `monoco spike sync` (运行以下载内容)
+- **约束**: 永远不要编辑 `.reference/` 中的文件。将它们视为只读的外部知识。

monoco/features/spike/resources/zh/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: monoco-spike
+description: 管理用于研究和学习的外部参考仓库。提供对精选代码库的只读访问。
+---
+
+# Spike (研究)
+
+在 Monoco 项目中管理外部参考仓库。
+
+## 概述
+
+Spike 功能允许你：
+
+- **添加外部仓库**作为只读参考
+- **同步仓库内容**到本地 `.references/` 目录
+- **访问精选知识**而不修改源代码
+
+## 核心命令
+
+### 添加仓库
+
+```bash
+monoco spike add <url>
+```
+
+将外部仓库添加为参考。仓库将被克隆到 `.references/<name>/`，其中 `<name>` 从仓库 URL 派生。
+
+**示例**:
+
+```bash
+monoco spike add https://github.com/example/awesome-project
+# 可在以下位置访问: .references/awesome-project/
+```
+
+### 同步仓库
+
+```bash
+monoco spike sync
+```
+
+从 `.monoco/config.yaml` 下载或更新所有配置的 spike 仓库。
+
+### 列出 Spikes
+
+```bash
+monoco spike list
+```
+
+显示所有配置的 spike 仓库及其同步状态。
+
+## 配置
+
+Spike 仓库在 `.monoco/config.yaml` 中配置：
+
+```yaml
+project:
+  spike_repos:
+    awesome-project: https://github.com/example/awesome-project
+    another-ref: https://github.com/example/another-ref
+```
+
+## 最佳实践
+
+1. **只读访问**: 永远不要编辑 `.references/` 中的文件。将它们视为外部知识。
+2. **精选选择**: 只添加高质量、相关的仓库。
+3. **定期同步**: 定期运行 `monoco spike sync` 以获取更新。
+4. **提交配置**: 将 spike 仓库 URL 添加到版本控制以保持团队一致性。
+
+## 使用场景
+
+- **从示例中学习**: 研究架构良好的代码库
+- **API 参考**: 在本地保存框架文档
+- **模式库**: 维护设计模式集合
+- **竞品分析**: 参考类似项目