monoco-toolkit 0.1.5__py3-none-any.whl

monoco/features/issue/linter.py

@@ -0,0 +1,172 @@
+from typing import List, Optional, Tuple, Set
+from pathlib import Path
+from rich.console import Console
+from rich.table import Table
+import typer
+
+from . import core
+from .models import IssueStatus, IssueStage
+
+console = Console()
+
+
+def validate_issue(path: Path, meta: core.IssueMetadata, all_issue_ids: Set[str] = set(), issues_root: Optional[Path] = None) -> List[str]:
+    """
+    Validate a single issue's integrity.
+    """
+    errors = []
+    
+    # A. Directory/Status Consistency
+    expected_status = meta.status.value
+    path_parts = path.parts
+    # We might be validating a temp file, so we skip path check if it's not in the tree?
+    # Or strict check? For "Safe Edit", the file might be in a temp dir. 
+    # So we probably only care about content/metadata integrity.
+    
+    # But wait, if we overwrite the file, it MUST be valid.
+    # Let's assume the validation is about the content itself (metadata logic).
+    
+    # B. Solution Compliance
+    if meta.status == IssueStatus.CLOSED and not meta.solution:
+        errors.append(f"[red]Solution Missing:[/red] {meta.id} is closed but has no [dim]solution[/dim] field.")
+        
+    # C. Link Integrity
+    if meta.parent:
+        if all_issue_ids and meta.parent not in all_issue_ids:
+             # Check workspace (fallback)
+             found = False
+             if issues_root:
+                 if core.find_issue_path(issues_root, meta.parent):
+                     found = True
+             
+             if not found:
+                 errors.append(f"[red]Broken Link:[/red] {meta.id} refers to non-existent parent [bold]{meta.parent}[/bold].")
+
+    # D. Lifecycle Guard (Backlog)
+    if meta.status == IssueStatus.BACKLOG and meta.stage != IssueStage.FREEZED:
+        errors.append(f"[red]Lifecycle Error:[/red] {meta.id} is backlog but stage is not [bold]freezed[/bold] (found: {meta.stage}).")
+
+    return errors
+
+def check_integrity(issues_root: Path, recursive: bool = False) -> List[str]:
+    """
+    Verify the integrity of the Issues directory.
+    Returns a list of error messages.
+    
+    If recursive=True, performs workspace-level validation including:
+    - Cross-project ID collision detection
+    - Cross-project UID collision detection
+    """
+    errors = []
+    all_issue_ids = set()  # For parent reference validation (includes namespaced IDs)
+    id_to_projects = {}  # local_id -> [(project_name, meta, file)]
+    all_uids = {}  # uid -> (project, issue_id)
+    all_issues = []
+    
+    # Helper to collect issues from a project
+    def collect_project_issues(project_issues_root: Path, project_name: str = "local"):
+        project_issues = []
+        for subdir in ["Epics", "Features", "Chores", "Fixes"]:
+            d = project_issues_root / subdir
+            if d.exists():
+                files = []
+                for status in ["open", "closed", "backlog"]:
+                    status_dir = d / status
+                    if status_dir.exists():
+                        files.extend(status_dir.rglob("*.md"))
+
+                for f in files:
+                    meta = core.parse_issue(f)
+                    if meta:
+                        local_id = meta.id
+                        full_id = f"{project_name}::{local_id}" if project_name != "local" else local_id
+                        
+                        # Track ID occurrences per project
+                        if local_id not in id_to_projects:
+                            id_to_projects[local_id] = []
+                        id_to_projects[local_id].append((project_name, meta, f))
+                        
+                        # Add IDs for reference validation
+                        all_issue_ids.add(local_id)  # Local ID
+                        if project_name != "local":
+                            all_issue_ids.add(full_id)  # Namespaced ID
+                        
+                        # Check UID collision (if UID exists)
+                        if meta.uid:
+                            if meta.uid in all_uids:
+                                existing_project, existing_id = all_uids[meta.uid]
+                                errors.append(
+                                    f"[red]UID Collision:[/red] UID {meta.uid} is duplicated.\n"
+                                    f"  - {existing_project}::{existing_id}\n"
+                                    f"  - {project_name}::{local_id}"
+                                )
+                            else:
+                                all_uids[meta.uid] = (project_name, local_id)
+                        
+                        project_issues.append((f, meta, project_name))
+        return project_issues
+
+    # 1. Collect local issues
+    all_issues.extend(collect_project_issues(issues_root, "local"))
+
+    # 2. If recursive, collect workspace member issues
+    if recursive:
+        try:
+            from monoco.core.config import get_config
+            project_root = issues_root.parent
+            conf = get_config(str(project_root))
+            
+            for member_name, rel_path in conf.project.members.items():
+                member_root = (project_root / rel_path).resolve()
+                member_issues_dir = member_root / "Issues"
+                
+                if member_issues_dir.exists():
+                    all_issues.extend(collect_project_issues(member_issues_dir, member_name))
+        except Exception as e:
+            # Fail gracefully if workspace config is missing
+            pass
+
+    # 3. Check for ID collisions within same project
+    for local_id, occurrences in id_to_projects.items():
+        # Group by project
+        projects_with_id = {}
+        for project_name, meta, f in occurrences:
+            if project_name not in projects_with_id:
+                projects_with_id[project_name] = []
+            projects_with_id[project_name].append((meta, f))
+        
+        # Check for duplicates within same project
+        for project_name, metas in projects_with_id.items():
+            if len(metas) > 1:
+                # Same ID appears multiple times in same project - this is an error
+                error_msg = f"[red]ID Collision:[/red] {local_id} appears {len(metas)} times in project '{project_name}':\n"
+                for idx, (meta, f) in enumerate(metas, 1):
+                    error_msg += f"  {idx}. uid: {meta.uid or 'N/A'} | created: {meta.created_at} | stage: {meta.stage} | status: {meta.status.value}\n"
+                error_msg += f"  [yellow]→ Action:[/yellow] Remove duplicate or use 'monoco issue move --to <target> --renumber' to resolve."
+                errors.append(error_msg)
+
+    # 4. Validation
+    for path, meta, project_name in all_issues:
+        # A. Directory/Status Consistency (Only check this for files in the tree)
+        expected_status = meta.status.value
+        path_parts = path.parts
+        if expected_status not in path_parts:
+             errors.append(f"[yellow]Placement Error:[/yellow] {meta.id} has status [cyan]{expected_status}[/cyan] but is not under a [dim]{expected_status}/[/dim] directory.")
+        
+        # Reuse common logic
+        errors.extend(validate_issue(path, meta, all_issue_ids, issues_root))
+
+    return errors
+
+
+def run_lint(issues_root: Path, recursive: bool = False):
+    errors = check_integrity(issues_root, recursive)
+    
+    if not errors:
+        console.print("[green]✔[/green] Issue integrity check passed. No integrity errors found.")
+    else:
+        table = Table(title="Issue Integrity Issues", show_header=False, border_style="red")
+        for err in errors:
+            table.add_row(err)
+        console.print(table)
+        raise typer.Exit(code=1)

monoco/features/issue/models.py

@@ -0,0 +1,157 @@
+from enum import Enum
+from typing import List, Optional, Any
+from pydantic import BaseModel, Field, model_validator
+from datetime import datetime
+import hashlib
+import secrets
+
+
+class IssueID:
+    """
+    Helper for parsing Issue IDs that might be namespaced (e.g. 'toolkit::FEAT-0001').
+    """
+    def __init__(self, raw: str):
+        self.raw = raw
+        if "::" in raw:
+            self.namespace, self.local_id = raw.split("::", 1)
+        else:
+            self.namespace = None
+            self.local_id = raw
+
+    def __str__(self):
+        if self.namespace:
+            return f"{self.namespace}::{self.local_id}"
+        return self.local_id
+        
+    def __repr__(self):
+        return f"IssueID({self.raw})"
+
+    @property
+    def is_local(self) -> bool:
+        return self.namespace is None
+
+    def matches(self, other_id: str) -> bool:
+        """Check if this ID matches another ID string."""
+        return str(self) == other_id or (self.is_local and self.local_id == other_id)
+
+def current_time() -> datetime:
+    return datetime.now().replace(microsecond=0)
+
+def generate_uid() -> str:
+    """
+    Generate a globally unique 6-character short hash for issue identity.
+    Uses timestamp + random bytes to ensure uniqueness across projects.
+    """
+    timestamp = str(datetime.now().timestamp()).encode()
+    random_bytes = secrets.token_bytes(8)
+    combined = timestamp + random_bytes
+    hash_digest = hashlib.sha256(combined).hexdigest()
+    return hash_digest[:6]
+
+
+class IssueType(str, Enum):
+    EPIC = "epic"
+    FEATURE = "feature"
+    CHORE = "chore"
+    FIX = "fix"
+
+class IssueStatus(str, Enum):
+    OPEN = "open"
+    CLOSED = "closed"
+    BACKLOG = "backlog"
+
+class IssueStage(str, Enum):
+    TODO = "todo"
+    DOING = "doing"
+    REVIEW = "review"
+    DONE = "done"
+    FREEZED = "freezed"
+
+class IssueSolution(str, Enum):
+    IMPLEMENTED = "implemented"
+    CANCELLED = "cancelled"
+    WONTFIX = "wontfix"
+    DUPLICATE = "duplicate"
+
+class IsolationType(str, Enum):
+    BRANCH = "branch"
+    WORKTREE = "worktree"
+
+class IssueIsolation(BaseModel):
+    type: IsolationType
+    ref: str  # Git branch name
+    path: Optional[str] = None  # Worktree path (relative to repo root or absolute)
+    created_at: datetime = Field(default_factory=current_time)
+
+class IssueMetadata(BaseModel):
+    model_config = {"extra": "allow"}
+    
+    id: str
+    uid: Optional[str] = None  # Global unique identifier for cross-project identity
+    type: IssueType
+    status: IssueStatus = IssueStatus.OPEN
+    stage: Optional[IssueStage] = None
+    title: str
+    
+    # Time Anchors
+    created_at: datetime = Field(default_factory=current_time)
+    opened_at: Optional[datetime] = None
+    updated_at: datetime = Field(default_factory=current_time)
+    closed_at: Optional[datetime] = None
+
+    parent: Optional[str] = None
+    sprint: Optional[str] = None
+    solution: Optional[IssueSolution] = None
+    isolation: Optional[IssueIsolation] = None
+    dependencies: List[str] = []
+    related: List[str] = []
+    dependencies: List[str] = []
+    related: List[str] = []
+    tags: List[str] = []
+    path: Optional[str] = None  # Absolute path to the issue file
+
+
+    @model_validator(mode='before')
+    @classmethod
+    def normalize_fields(cls, v: Any) -> Any:
+        if isinstance(v, dict):
+            # Normalize type and status to lowercase for compatibility
+            if "type" in v and isinstance(v["type"], str):
+                v["type"] = v["type"].lower()
+            if "status" in v and isinstance(v["status"], str):
+                v["status"] = v["status"].lower()
+            if "solution" in v and isinstance(v["solution"], str):
+                v["solution"] = v["solution"].lower()
+            # Stage normalization
+            if "stage" in v and isinstance(v["stage"], str):
+                v["stage"] = v["stage"].lower()
+        return v
+
+    @model_validator(mode='after')
+    def validate_lifecycle(self) -> 'IssueMetadata':
+        # Logic Definition:
+        # status: backlog -> stage: null
+        # status: closed -> stage: done
+        # status: open -> stage: todo | doing | review (default todo)
+
+        if self.status == IssueStatus.BACKLOG:
+            self.stage = IssueStage.FREEZED
+        
+        elif self.status == IssueStatus.CLOSED:
+            # Enforce stage=done for closed issues
+            if self.stage != IssueStage.DONE:
+                self.stage = IssueStage.DONE
+            # Auto-fill closed_at if missing
+            if not self.closed_at:
+                self.closed_at = current_time()
+        
+        elif self.status == IssueStatus.OPEN:
+            # Ensure valid stage for open status
+            if self.stage is None or self.stage == IssueStage.DONE:
+                self.stage = IssueStage.TODO
+        
+        return self
+
+class IssueDetail(IssueMetadata):
+    body: str = ""
+    raw_content: Optional[str] = None # Full file content including frontmatter for editing

monoco/features/pty/core.py

@@ -0,0 +1,185 @@
+
+import asyncio
+import os
+import pty
+import select
+import signal
+import struct
+import fcntl
+import termios
+import logging
+from typing import Dict, Optional, Tuple, Any
+
+logger = logging.getLogger("monoco.pty")
+
+class PTYSession:
+    """
+    Manages a single PTY session connected to a subprocess (shell).
+    """
+    def __init__(self, session_id: str, cmd: list[str], env: Optional[Dict[str, str]] = None, cwd: Optional[str] = None):
+        self.session_id = session_id
+        self.cmd = cmd
+        self.env = env or os.environ.copy()
+        self.cwd = cwd or os.getcwd()
+        
+        self.fd: Optional[int] = None
+        self.pid: Optional[int] = None
+        self.proc = None # subprocess.Popen object
+        self.running = False
+        self.loop = asyncio.get_running_loop()
+
+    def start(self, cols: int = 80, rows: int = 24):
+        """
+        Spawn a subprocess connected to a new PTY using subprocess.Popen.
+        This provides better safety in threaded/asyncio environments than pty.fork().
+        """
+        import subprocess
+
+        # 1. Open PTY pair
+        master_fd, slave_fd = pty.openpty()
+        
+        # 2. Set initial size
+        self._set_winsize(master_fd, rows, cols)
+
+        try:
+            # 3. Spawn process
+            # start_new_session=True executes setsid()
+            self.proc = subprocess.Popen(
+                self.cmd,
+                stdin=slave_fd,
+                stdout=slave_fd,
+                stderr=slave_fd,
+                cwd=self.cwd,
+                env=self.env,
+                start_new_session=True,
+                close_fds=True # Important to close other FDs in child
+            )
+            
+            self.pid = self.proc.pid
+            self.fd = master_fd
+            self.running = True
+            
+            # 4. Close slave fd in parent (child has it open now)
+            os.close(slave_fd)
+            
+            logger.info(f"Started session {self.session_id} (PID: {self.pid})")
+            
+        except Exception as e:
+            logger.error(f"Failed to spawn process: {e}")
+            # Ensure we clean up fds if spawn fails
+            try:
+                os.close(master_fd)
+            except: pass
+            try:
+                os.close(slave_fd)
+            except: pass
+            raise e
+
+
+    def resize(self, cols: int, rows: int):
+        """
+        Resize the PTY.
+        """
+        if self.fd and self.running:
+            self._set_winsize(self.fd, rows, cols)
+
+    def write(self, data: bytes):
+        """
+        Write input data (from websocket) to the PTY master fd.
+        """
+        if self.fd and self.running:
+            os.write(self.fd, data)
+
+    async def read(self) -> bytes:
+        """
+        Read output data from PTY master fd (to forward to websocket).
+        """
+        if not self.fd or not self.running:
+            return b""
+            
+        try:
+            # Run in executor to avoid blocking the event loop
+            # pty read is blocking
+            return await self.loop.run_in_executor(None, self._read_blocking)
+        except OSError:
+            return b""
+
+    def _read_blocking(self) -> bytes:
+        try:
+            return os.read(self.fd, 1024)
+        except OSError:
+            return b""
+
+    def terminate(self):
+        """
+        Terminate the process and close the PTY.
+        """
+        self.running = False
+        
+        # Use Popen object if available
+        if self.proc:
+            try:
+                self.proc.terminate()
+                try:
+                    self.proc.wait(timeout=1.0)
+                except:
+                    # Force kill if not terminated
+                    self.proc.kill()
+                    self.proc.wait()
+            except Exception as e:
+                logger.error(f"Error terminating process: {e}")
+            self.proc = None
+            self.pid = None
+        elif self.pid:
+            # Fallback for legacy or if Popen obj lost
+            try:
+                os.kill(self.pid, signal.SIGTERM)
+                os.waitpid(self.pid, 0) # Reap zombie
+            except OSError:
+                pass
+            self.pid = None
+            
+        if self.fd:
+            try:
+                os.close(self.fd)
+            except OSError:
+                pass
+            self.fd = None
+        logger.info(f"Terminated session {self.session_id}")
+
+    def _set_winsize(self, fd: int, row: int, col: int, xpix: int = 0, ypix: int = 0):
+        winsize = struct.pack("HHHH", row, col, xpix, ypix)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, winsize)
+
+
+class PTYManager:
+    """
+    Singleton to manage multiple PTY sessions.
+    """
+    def __init__(self):
+        self.sessions: Dict[str, PTYSession] = {}
+
+    def create_session(self, session_id: str, cwd: str, cmd: list[str] = ["/bin/zsh"], env: Dict = None) -> PTYSession:
+        if session_id in self.sessions:
+            # In a real app, we might want to attach to existing?
+            # For now, kill and recreate (or error)
+            self.close_session(session_id)
+            
+        session = PTYSession(session_id, cmd, env, cwd)
+        self.sessions[session_id] = session
+        return session
+
+    def get_session(self, session_id: str) -> Optional[PTYSession]:
+        return self.sessions.get(session_id)
+
+    def close_session(self, session_id: str):
+        if session_id in self.sessions:
+            self.sessions[session_id].terminate()
+            del self.sessions[session_id]
+
+    def close_all_sessions(self):
+        """
+        Terminate all active PTY sessions.
+        """
+        for session_id in list(self.sessions.keys()):
+            self.close_session(session_id)

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()