monoco-toolkit 0.1.7__py3-none-any.whl → 0.2.0__py3-none-any.whl

monoco/features/agent/commands.py

@@ -0,0 +1,160 @@
+
+import typer
+from typing import Optional
+from pathlib import Path
+from monoco.core.output import print_output, print_error
+from monoco.core.agent.adapters import get_agent_client
+from monoco.core.agent.state import AgentStateManager
+from monoco.core.agent.action import ActionRegistry, ActionContext
+from monoco.core.config import get_config
+import asyncio
+import re
+import json as j
+
+app = typer.Typer()
+
+@app.command(name="run")
+def run_command(
+    prompt_or_task: str = typer.Argument(..., help="Prompt string OR execution task name (e.g. 'refine-issue')"),
+    target: Optional[str] = typer.Argument(None, help="Target file argument for the task"),
+    provider: Optional[str] = typer.Option(None, "--using", "-u", help="Override agent provider"),
+    instruction: Optional[str] = typer.Option(None, "--instruction", "-i", help="Additional instruction for the agent"),
+):
+    """
+    Execute a prompt or a named task using an Agent CLI.
+    """
+    # 0. Setup
+    settings = get_config()
+    state_manager = AgentStateManager()
+    registry = ActionRegistry(Path(settings.paths.root))
+    
+    # 1. Check if it's a named task
+    action = registry.get(prompt_or_task)
+    
+    final_prompt = prompt_or_task
+    context_files = []
+    
+    # Determine Provider Priority: CLI > Action Def > Config > Default
+    prov_name = provider 
+    
+    if action:
+        # It IS an action
+        print(f"Running action: {action.name}")
+        
+        # Simple template substitution
+        final_prompt = action.template
+        
+        if "{{file}}" in final_prompt:
+             if not target:
+                 print_error("This task requires a target file argument.")
+                 raise typer.Exit(1)
+             
+             target_path = Path(target).resolve()
+             if not target_path.exists():
+                 print_error(f"Target file not found: {target}")
+                 raise typer.Exit(1)
+                 
+             final_prompt = final_prompt.replace("{{file}}", target_path.read_text())
+             # Also add to context files? Ideally the prompt has it.
+             # Let's add it to context files list to be safe if prompt didn't embed it fully
+             context_files.append(target_path)
+             
+        if not prov_name:
+            prov_name = action.provider
+
+    # 2. Append Instruction if provided
+    if instruction:
+        final_prompt = f"{final_prompt}\n\n[USER INSTRUCTION]\n{instruction}"
+
+    # 2. Provider Resolution Fallback
+    prov_name = prov_name or settings.agent.framework or "gemini"
+
+    # 3. State Check
+    state = state_manager.load()
+    if not state or state.is_stale:
+        print("Agent state stale or missing, refreshing...")
+        state = state_manager.refresh()
+    
+    if prov_name not in state.providers:
+         print_error(f"Provider '{prov_name}' unknown.")
+         raise typer.Exit(1)
+         
+    if not state.providers[prov_name].available:
+         print_error(f"Provider '{prov_name}' is not available. Run 'monoco doctor' to diagnose.")
+         raise typer.Exit(1)
+
+    # 4. Execute
+    try:
+        client = get_agent_client(prov_name)
+        result = asyncio.run(client.execute(final_prompt, context_files=context_files))
+        print(result)
+        
+    except Exception as e:
+        print_error(f"Execution failed: {e}")
+        raise typer.Exit(1)
+
+@app.command()
+def list(
+    json: bool = typer.Option(False, "--json", help="Output in JSON format"),
+    context: Optional[str] = typer.Option(None, "--context", help="Context for filtering (JSON string)")
+):
+    """List available actions."""
+    settings = get_config()
+    registry = ActionRegistry(Path(settings.paths.root))
+    
+    action_context = None
+    if context:
+        try:
+            ctx_data = j.loads(context)
+            action_context = ActionContext(**ctx_data)
+        except Exception as e:
+            print_error(f"Invalid context JSON: {e}")
+
+    actions = registry.list_available(action_context)
+    if json:
+        print(j.dumps([a.dict() for a in actions], indent=2))
+    else:
+        print_output(actions, title="Available Actions")
+
+@app.command()
+def status(
+    json: bool = typer.Option(False, "--json", help="Output in JSON format"),
+    force: bool = typer.Option(False, "--force", "-f", help="Force refresh of agent state")
+):
+    """View status of Agent Providers."""
+    state_manager = AgentStateManager()
+    state = state_manager.get_or_refresh(force=force)
+    
+    if json:
+        import json as j
+        # Convert datetime to ISO string for JSON serialization
+        data = state.dict()
+        data["last_checked"] = data["last_checked"].isoformat()
+        print(j.dumps(data, indent=2))
+    else:
+        # Standard output using existing print_output or custom formatting
+        from monoco.core.output import Table
+        table = Table(title=f"Agent Status (Last Checked: {state.last_checked.strftime('%Y-%m-%d %H:%M:%S')})")
+        table.add_column("Provider")
+        table.add_column("Available")
+        table.add_column("Path")
+        table.add_column("Error")
+        
+        for name, p_state in state.providers.items():
+            table.add_row(
+                name,
+                "✅" if p_state.available else "❌",
+                p_state.path or "-",
+                p_state.error or "-"
+            )
+        print_output(table)
+
+@app.command()
+def doctor(
+    force: bool = typer.Option(False, "--force", "-f", help="Force refresh of agent state")
+):
+    """
+    Diagnose Agent Environment and refresh state.
+    """
+    from monoco.features.agent.doctor import doctor as doc_impl
+    doc_impl(force)

monoco/features/agent/doctor.py

@@ -0,0 +1,30 @@
+import typer
+from monoco.core.output import print_output, print_error
+from monoco.core.agent.state import AgentStateManager
+
+app = typer.Typer()
+
+@app.command()
+def doctor(
+    force: bool = typer.Option(False, "--force", "-f", help="Force refresh of agent state")
+):
+    """
+    Diagnose Agent Environment and refresh state.
+    """
+    manager = AgentStateManager()
+    try:
+        if force:
+            print("Force refreshing agent state...")
+            state = manager.refresh()
+        else:
+            state = manager.get_or_refresh()
+            
+        print_output(state, title="Agent Diagnosis Report")
+        
+        # Simple summary
+        available = [k for k, v in state.providers.items() if v.available]
+        print(f"\n✅ Available Agents: {', '.join(available) if available else 'None'}")
+        
+    except Exception as e:
+        print_error(f"Doctor failed: {e}")
+        raise typer.Exit(1)

monoco/features/issue/core.py

@@ -52,9 +52,9 @@ def parse_issue(file_path: Path) -> Optional[IssueMetadata]:
         if not isinstance(data, dict):
              return None
         
-        # Inject path before validation to ensure it persists
         data['path'] = str(file_path.absolute())
         meta = IssueMetadata(**data)
+        meta.actions = get_available_actions(meta)
         return meta
     except Exception:
         return None
@@ -171,47 +171,36 @@ def create_issue_file(
     metadata.path = str(file_path.absolute())
     
     return metadata, file_path
-def validate_transition(
-    current_status: IssueStatus,
-    current_stage: Optional[IssueStage],
-    target_status: IssueStatus,
-    target_stage: Optional[IssueStage],
-    target_solution: Optional[str],
-    issue_dependencies: List[str],
-    issues_root: Path,
-    issue_id: str
-):
-    """
-    Centralized validation logic for state transitions.
-    """
-    # Policy: Prevent Backlog -> Review
-    if target_stage == IssueStage.REVIEW and current_status == IssueStatus.BACKLOG:
-         raise ValueError(f"Lifecycle Policy: Cannot submit Backlog issue directly. Run `monoco issue pull {issue_id}` first.")
+def get_available_actions(meta: IssueMetadata) -> List[Any]:
+    from .models import IssueAction
+    actions = []
+
+    if meta.status == IssueStatus.OPEN:
+        # Stage-based movements
+        if meta.stage == IssueStage.DRAFT:
+            actions.append(IssueAction(label="Start", target_status=IssueStatus.OPEN, target_stage=IssueStage.DOING))
+            actions.append(IssueAction(label="Freeze", target_status=IssueStatus.BACKLOG))
+        elif meta.stage == IssueStage.DOING:
+            actions.append(IssueAction(label="Stop", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
+            actions.append(IssueAction(label="Submit", target_status=IssueStatus.OPEN, target_stage=IssueStage.REVIEW))
+        elif meta.stage == IssueStage.REVIEW:
+            actions.append(IssueAction(label="Approve", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.IMPLEMENTED))
+            actions.append(IssueAction(label="Reject", target_status=IssueStatus.OPEN, target_stage=IssueStage.DOING))
+        elif meta.stage == IssueStage.DONE:
+            actions.append(IssueAction(label="Reopen", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
+            actions.append(IssueAction(label="Close", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.IMPLEMENTED))
+        
+        # Generic cancel
+        actions.append(IssueAction(label="Cancel", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.CANCELLED))
 
-    if target_status == IssueStatus.CLOSED:
-        if not target_solution:
-            raise ValueError(f"Closing an issue requires a solution. Please provide --solution or edit the file metadata.")
-            
-        # Policy: IMPLEMENTED requires REVIEW stage (unless we are already in REVIEW)
-        # Check current stage.
-        if target_solution == IssueSolution.IMPLEMENTED.value:
-            # If we are transitioning FROM Review, it's fine.
-            # If we are transitioning TO Closed, current stage must be Review.
-            if current_stage != IssueStage.REVIEW:
-                raise ValueError(f"Lifecycle Policy: 'Implemented' issues must be submitted for review first.\nCurrent stage: {current_stage}\nAction: Run `monoco issue submit {issue_id}`.")
-
-        # Policy: No closing from DOING (General Safety)
-        if current_stage == IssueStage.DOING:
-             raise ValueError("Cannot close issue in progress (Doing). Please review (`monoco issue submit`) or stop (`monoco issue open`) first.")
-             
-        # Policy: Dependencies must be closed
-        if issue_dependencies:
-            for dep_id in issue_dependencies:
-                dep_path = find_issue_path(issues_root, dep_id)
-                if dep_path:
-                    dep_meta = parse_issue(dep_path)
-                    if dep_meta and dep_meta.status != IssueStatus.CLOSED:
-                        raise ValueError(f"Dependency Block: Cannot close {issue_id} because dependency {dep_id} is not closed.")
+    elif meta.status == IssueStatus.BACKLOG:
+        actions.append(IssueAction(label="Pull", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
+        actions.append(IssueAction(label="Cancel", target_status=IssueStatus.CLOSED, target_stage=IssueStage.DONE, target_solution=IssueSolution.CANCELLED))
+
+    elif meta.status == IssueStatus.CLOSED:
+        actions.append(IssueAction(label="Reopen", target_status=IssueStatus.OPEN, target_stage=IssueStage.DRAFT))
+
+    return actions
 
 def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
     parsed = IssueID(issue_id)
@@ -253,7 +242,17 @@ def find_issue_path(issues_root: Path, issue_id: str) -> Optional[Path]:
         return f
     return None
 
-def update_issue(issues_root: Path, issue_id: str, status: Optional[IssueStatus] = None, stage: Optional[IssueStage] = None, solution: Optional[IssueSolution] = None) -> IssueMetadata:
+def update_issue(
+    issues_root: Path, 
+    issue_id: str, 
+    status: Optional[IssueStatus] = None, 
+    stage: Optional[IssueStage] = None, 
+    solution: Optional[IssueSolution] = None,
+    parent: Optional[str] = None,
+    dependencies: Optional[List[str]] = None,
+    related: Optional[List[str]] = None,
+    tags: Optional[List[str]] = None
+) -> IssueMetadata:
     path = find_issue_path(issues_root, issue_id)
     if not path:
         raise FileNotFoundError(f"Issue {issue_id} not found.")
@@ -262,7 +261,7 @@ def update_issue(issues_root: Path, issue_id: str, status: Optional[IssueStatus]
     content = path.read_text()
     
     # Split Frontmatter and Body
-    match = re.search(r"^---(.*?)---\n(.*)$\n", content, re.DOTALL | re.MULTILINE)
+    match = re.search(r"^---(.*?)---\n(.*)\n", content, re.DOTALL | re.MULTILINE)
     if not match:
         # Fallback
         match_simple = re.search(r"^---(.*?)---", content, re.DOTALL | re.MULTILINE)
@@ -313,14 +312,29 @@ def update_issue(issues_root: Path, issue_id: str, status: Optional[IssueStatus]
              raise ValueError("Cannot close issue in progress (Doing). Please review (`monoco issue submit`) or stop (`monoco issue open`) first.")
              
         # Policy: Dependencies must be closed
-        dependencies = data.get('dependencies', [])
-        if dependencies:
-            for dep_id in dependencies:
+        dependencies_to_check = dependencies if dependencies is not None else data.get('dependencies', [])
+        if dependencies_to_check:
+            for dep_id in dependencies_to_check:
                 dep_path = find_issue_path(issues_root, dep_id)
                 if dep_path:
                     dep_meta = parse_issue(dep_path)
                     if dep_meta and dep_meta.status != IssueStatus.CLOSED:
                         raise ValueError(f"Dependency Block: Cannot close {issue_id} because dependency {dep_id} is [Status: {dep_meta.status.value}].")
+    
+    # Validate new parent/dependencies/related exist
+    if parent is not None and parent != "":
+        if not find_issue_path(issues_root, parent):
+            raise ValueError(f"Parent issue {parent} not found.")
+    
+    if dependencies is not None:
+        for dep_id in dependencies:
+            if not find_issue_path(issues_root, dep_id):
+                raise ValueError(f"Dependency issue {dep_id} not found.")
+    
+    if related is not None:
+        for rel_id in related:
+            if not find_issue_path(issues_root, rel_id):
+                raise ValueError(f"Related issue {rel_id} not found.")
             
     # Update Data
     if status:
@@ -331,6 +345,21 @@ def update_issue(issues_root: Path, issue_id: str, status: Optional[IssueStatus]
     if solution:
         data['solution'] = solution.value
     
+    if parent is not None:
+        if parent == "":
+            data.pop('parent', None)  # Remove parent field
+        else:
+            data['parent'] = parent
+    
+    if dependencies is not None:
+        data['dependencies'] = dependencies
+    
+    if related is not None:
+        data['related'] = related
+    
+    if tags is not None:
+        data['tags'] = tags
+    
     # Lifecycle Hooks
     # 1. Opened At: If transitioning to OPEN
     if target_status == IssueStatus.OPEN and current_status != IssueStatus.OPEN:
@@ -385,11 +414,15 @@ def update_issue(issues_root: Path, issue_id: str, status: Optional[IssueStatus]
         if path != target_path:
             target_path.parent.mkdir(parents=True, exist_ok=True)
             path.rename(target_path)
+            path = target_path # Update local path variable for returned meta
 
     # Hook: Recursive Aggregation (FEAT-0003)
     if updated_meta.parent:
         recalculate_parent(issues_root, updated_meta.parent)
-        
+    
+    # Update returned metadata with final absolute path
+    updated_meta.path = str(path.absolute())
+    updated_meta.actions = get_available_actions(updated_meta)
     return updated_meta
 
 def start_issue_isolation(issues_root: Path, issue_id: str, mode: IsolationType, project_root: Path) -> IssueMetadata:

monoco/features/issue/executions/refine.md

@@ -0,0 +1,26 @@
+---
+name: refine-issue
+description: Refine a raw issue description into a structured Monoco Feature.
+provider: claude
+args: ["file"]
+---
+
+You are an expert Technical Product Manager using the Monoco Issue System.
+Your task is to refine the provided Issue file into a high-quality "Feature Ticket".
+
+# Input Context
+
+File: {{file}}
+
+# Monoco Ontology Rules
+
+1. **Feature**: Delivers User Value (Atomic, Shippable). Prefix: `FEAT-`.
+2. **Architecture**: Uses `Chore` for purely technical maintenance.
+3. **Structure**: Must have clear `Objective`, `Context`, `Strategy`, `Detailed Design`, and `Acceptance Criteria`.
+
+# Instructions
+
+1. Analyze the input content.
+2. Rewrite it to be professional, clear, and comprehensive.
+3. Fill in missing details with reasonable technical assumptions (but mark them if unsure).
+4. OUTPUT ONLY the Markdown content of the new file.

monoco/features/issue/models.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import List, Optional, Any
+from typing import List, Optional, Any, Dict
 from pydantic import BaseModel, Field, model_validator
 from datetime import datetime
 import hashlib
@@ -83,6 +83,17 @@ class IssueIsolation(BaseModel):
     path: Optional[str] = None  # Worktree path (relative to repo root or absolute)
     created_at: datetime = Field(default_factory=current_time)
 
+class IssueAction(BaseModel):
+    label: str
+    target_status: Optional[IssueStatus] = None
+    target_stage: Optional[IssueStage] = None
+    target_solution: Optional[IssueSolution] = None
+    icon: Optional[str] = None
+    
+    # Generic execution extensions
+    command: Optional[str] = None
+    params: Dict[str, Any] = {}
+
 class IssueMetadata(BaseModel):
     model_config = {"extra": "allow"}
     
@@ -105,10 +116,11 @@ class IssueMetadata(BaseModel):
     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
+    
+    # Proxy UI Actions (Excluded from file persistence)
+    actions: List[IssueAction] = Field(default=[], exclude=True)
 
 
     @model_validator(mode='before')
@@ -132,9 +144,9 @@ class IssueMetadata(BaseModel):
     @model_validator(mode='after')
     def validate_lifecycle(self) -> 'IssueMetadata':
         # Logic Definition:
-        # status: backlog -> stage: null
+        # status: backlog -> stage: freezed
         # status: closed -> stage: done
-        # status: open -> stage: draft | doing | review (default draft)
+        # status: open -> stage: draft | doing | review | done (default draft)
 
         if self.status == IssueStatus.BACKLOG:
             self.stage = IssueStage.FREEZED
@@ -149,7 +161,7 @@ class IssueMetadata(BaseModel):
         
         elif self.status == IssueStatus.OPEN:
             # Ensure valid stage for open status
-            if self.stage is None or self.stage == IssueStage.DONE:
+            if self.stage is None:
                 self.stage = IssueStage.DRAFT
         
         return self

monoco/features/issue/monitor.py

@@ -0,0 +1,94 @@
+import re
+import asyncio
+import logging
+from pathlib import Path
+from typing import Callable, Awaitable, Any, Optional
+
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+
+logger = logging.getLogger("monoco.features.issue.monitor")
+
+class IssueEventHandler(FileSystemEventHandler):
+    def __init__(self, loop, on_upsert: Callable[[dict], Awaitable[None]], on_delete: Callable[[dict], Awaitable[None]]):
+        self.loop = loop
+        self.on_upsert = on_upsert
+        self.on_delete = on_delete
+
+    def _process_upsert(self, path_str: str):
+        if not path_str.endswith(".md"):
+            return
+        asyncio.run_coroutine_threadsafe(self._handle_upsert(path_str), self.loop)
+    
+    async def _handle_upsert(self, path_str: str):
+        try:
+            from monoco.features.issue.core import parse_issue
+            path = Path(path_str)
+            if not path.exists():
+                return
+            issue = parse_issue(path)
+            if issue:
+                await self.on_upsert(issue.model_dump(mode='json'))
+        except Exception as e:
+            logger.error(f"Error handling upsert for {path_str}: {e}")
+
+    def _process_delete(self, path_str: str):
+        if not path_str.endswith(".md"):
+            return
+        asyncio.run_coroutine_threadsafe(self._handle_delete(path_str), self.loop)
+
+    async def _handle_delete(self, path_str: str):
+        try:
+            filename = Path(path_str).name
+            match = re.match(r"([A-Z]+-\d{4})", filename)
+            if match:
+                issue_id = match.group(1)
+                await self.on_delete({"id": issue_id})
+        except Exception as e:
+            logger.error(f"Error handling delete for {path_str}: {e}")
+
+    def on_created(self, event):
+        if not event.is_directory:
+            self._process_upsert(event.src_path)
+
+    def on_modified(self, event):
+        if not event.is_directory:
+            self._process_upsert(event.src_path)
+            
+    def on_deleted(self, event):
+        if not event.is_directory:
+            self._process_delete(event.src_path)
+
+    def on_moved(self, event):
+        if not event.is_directory:
+            self._process_delete(event.src_path)
+            self._process_upsert(event.dest_path)
+
+class IssueMonitor:
+    """
+    Monitor the Issues directory for changes using Watchdog and trigger callbacks.
+    """
+    def __init__(self, issues_root: Path, on_upsert: Callable[[dict], Awaitable[None]], on_delete: Callable[[dict], Awaitable[None]]):
+        self.issues_root = issues_root
+        self.on_upsert = on_upsert
+        self.on_delete = on_delete
+        self.observer = Observer()
+        self.loop = None
+
+    async def start(self):
+        self.loop = asyncio.get_running_loop()
+        event_handler = IssueEventHandler(self.loop, self.on_upsert, self.on_delete)
+        
+        if not self.issues_root.exists():
+            logger.warning(f"Issues root {self.issues_root} does not exist. creating...")
+            self.issues_root.mkdir(parents=True, exist_ok=True)
+
+        self.observer.schedule(event_handler, str(self.issues_root), recursive=True)
+        self.observer.start()
+        logger.info(f"Issue Monitor started (Watchdog). Watching {self.issues_root}")
+
+    def stop(self):
+        if self.observer.is_alive():
+            self.observer.stop()
+            self.observer.join()
+        logger.info(f"Issue Monitor stopped for {self.issues_root}")

monoco/main.py

@@ -44,6 +44,16 @@ from monoco.core.sync import sync_command, uninstall_command
 app.command(name="sync")(sync_command)
 app.command(name="uninstall")(uninstall_command)
 
+@app.command(name="doctor")
+def doctor_cmd(
+    force: bool = typer.Option(False, "--force", "-f", help="Force refresh of agent state")
+):
+    """
+    Diagnose Agent Environment.
+    """
+    from monoco.features.agent.doctor import doctor
+    doctor(force)
+
 @app.command()
 def info():
     """
@@ -92,6 +102,9 @@ app.add_typer(spike_cmd.app, name="spike", help="Manage research spikes")
 app.add_typer(i18n_cmd.app, name="i18n", help="Manage documentation i18n")
 app.add_typer(config_cmd.app, name="config", help="Manage configuration")
 
+from monoco.features.agent import commands as agent_cmd
+app.add_typer(agent_cmd.app, name="agent", help="Delegate tasks to Agent CLIs")
+
 from monoco.daemon.commands import serve
 app.command(name="serve")(serve)
 

{monoco_toolkit-0.1.7.dist-info → monoco_toolkit-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: monoco-toolkit
-Version: 0.1.7
+Version: 0.2.0
 Summary: Agent Native Toolkit for Monoco - Task Management & Kanban for AI Agents
 Project-URL: Homepage, https://monoco.io
 Project-URL: Repository, https://github.com/IndenScale/Monoco