code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/plan_mode/plan_generation.py

@@ -0,0 +1,68 @@
+"""Plan document generation and persistence.
+
+Produces markdown plan files with YAML front-matter and saves them to a
+local ``plans/`` directory.
+"""
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+def generate_plan_md(
+    goal: str,
+    research_notes: str,
+    discussion: str,
+    steps: list[str],
+) -> str:
+    """Generate a markdown plan document with YAML front-matter.
+
+    Args:
+        goal: Short title/summary of the plan.
+        research_notes: Analysis and context gathered during planning.
+        discussion: Reasoning and trade-offs considered.
+        steps: Ordered list of implementation steps.
+
+    Returns:
+        A fully formatted markdown string.
+    """
+    ts = datetime.now(UTC).isoformat()
+    numbered_steps = "\n".join(f"{i + 1}. {step}" for i, step in enumerate(steps))
+    return f"""---
+goal: "{goal}"
+created_at: "{ts}"
+status: draft
+---
+
+# Plan: {goal}
+
+## Analysis
+{research_notes}
+
+## Discussion
+{discussion}
+
+## Implementation Steps
+{numbered_steps}
+
+## Risks
+- (placeholder)
+"""
+
+
+def save_plan(content: str, plans_dir: Path = Path("plans")) -> Path:
+    """Save plan markdown to ``plans/plan_{timestamp}.md``.
+
+    Creates the directory if it does not exist.
+
+    Args:
+        content: Markdown content to save.
+        plans_dir: Target directory (default: ``plans/`` in cwd).
+
+    Returns:
+        The path to the written file.
+    """
+    plans_dir.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    file_path = plans_dir / f"plan_{ts}.md"
+    file_path.write_text(content, encoding="utf-8")
+    return file_path

code_muse/plugins/plan_mode/plan_hooks.py

@@ -0,0 +1,74 @@
+"""Plan mode enforcement hook.
+
+Registers a ``pre_tool_call`` callback that blocks destructive tools
+according to the active plan mode state.
+"""
+
+import logging
+from typing import Any
+
+from code_muse.plugins.plan_mode.plan_mode_tools import PlanModeState, get_current_mode
+
+logger = logging.getLogger(__name__)
+
+# Tools allowed in PLAN mode (research / read-only / meta)
+_PLAN_ALLOWED_TOOLS: set[str] = {
+    "read_file",
+    "list_files",
+    "grep",
+    "ask_user_question",
+    "list_or_search_skills",
+    "enter_plan_mode",
+    "exit_plan_mode",
+    "get_plan_mode",
+    "approve_plan",
+    "cancel_plan",
+    "open_plan_in_editor",
+}
+
+# Tools blocked in AUTO_EDIT mode (shell commands only)
+_AUTO_EDIT_BLOCKED_TOOLS: set[str] = {
+    "agent_run_shell_command",
+    "run_shell_command",
+}
+
+
+async def plan_mode_pre_tool_call_hook(
+    tool_name: str, tool_args: dict, context: Any = None
+) -> dict | None:
+    """Enforce mode-specific tool restrictions.
+
+    Returns:
+        ``{"blocked": True, "error_message": "..."}`` if the tool is
+        blocked in the current mode, otherwise ``None``.
+    """
+    mode = get_current_mode()
+
+    if mode == PlanModeState.DEFAULT:
+        return None
+
+    if mode == PlanModeState.PLAN:
+        if tool_name in _PLAN_ALLOWED_TOOLS:
+            return None
+        logger.info("Blocked tool '%s' during plan mode", tool_name)
+        return {
+            "blocked": True,
+            "error_message": (
+                "🚫 Plan mode is active. This tool is blocked during planning. "
+                "Use exit_plan_mode to return to normal mode."
+            ),
+        }
+
+    if mode == PlanModeState.AUTO_EDIT:
+        if tool_name in _AUTO_EDIT_BLOCKED_TOOLS:
+            logger.info("Blocked tool '%s' during auto-edit mode", tool_name)
+            return {
+                "blocked": True,
+                "error_message": (
+                    "🚫 Auto-edit mode is active. Shell commands are blocked. "
+                    "Use exit_plan_mode to return to normal mode."
+                ),
+            }
+        return None
+
+    return None

code_muse/plugins/plan_mode/plan_mode_tools.py

@@ -0,0 +1,138 @@
+"""Plan mode state management and tool registration.
+
+Tools:
+    - enter_plan_mode(goal: str = "")
+    - exit_plan_mode()
+    - get_plan_mode()
+    - approve_plan()
+    - open_plan_in_editor()
+"""
+
+import enum
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from pydantic_ai import RunContext
+
+from code_muse.messaging.bus import get_message_bus
+
+
+class PlanModeState(enum.Enum):
+    """Three-state mode model."""
+
+    DEFAULT = "default"
+    AUTO_EDIT = "auto_edit"
+    PLAN = "plan"
+
+
+# Module-level mutable state (integration note: if the agent runtime ever
+# exposes a formal ``_mode`` attribute, mirror state there).
+_current_mode: PlanModeState = PlanModeState.DEFAULT
+_plan_goal: str = ""
+
+
+def get_current_mode() -> PlanModeState:
+    """Return the active plan mode state."""
+    return _current_mode
+
+
+def get_plan_goal() -> str:
+    """Return the current planning goal, if any."""
+    return _plan_goal
+
+
+def set_plan_mode(mode: PlanModeState, goal: str = "") -> None:
+    """Update the global plan mode state and optional goal."""
+    global _current_mode, _plan_goal
+    _current_mode = mode
+    _plan_goal = goal
+
+
+def register_enter_plan_mode(agent: Any) -> None:
+    """Register the ``enter_plan_mode`` tool on *agent*."""
+
+    @agent.tool
+    def enter_plan_mode(context: RunContext, goal: str = "") -> str:
+        """Enter plan mode. Optional goal describes what you are planning.
+
+        In plan mode, destructive tools (write_file, replace_in_file,
+        delete_file, shell commands) are blocked. Research tools
+        (read_file, list_files, grep, ask_user_question) remain available.
+        """
+        set_plan_mode(PlanModeState.PLAN, goal)
+        bus = get_message_bus()
+        bus.emit_info(f"📋 Plan mode activated{f' (goal: {goal})' if goal else ''}")
+        return f"Plan mode active. Goal: {goal or '(none)'}"
+
+
+def register_exit_plan_mode(agent: Any) -> None:
+    """Register the ``exit_plan_mode`` tool on *agent*."""
+
+    @agent.tool
+    def exit_plan_mode(context: RunContext) -> str:
+        """Exit plan mode and return to normal operation."""
+        set_plan_mode(PlanModeState.DEFAULT)
+        bus = get_message_bus()
+        bus.emit_info("📋 Plan mode deactivated — normal editing resumed")
+        return "Plan mode deactivated. Normal editing resumed."
+
+
+def register_get_plan_mode(agent: Any) -> None:
+    """Register the ``get_plan_mode`` tool on *agent*."""
+
+    @agent.tool
+    def get_plan_mode(context: RunContext) -> str:
+        """Return the current plan mode state and goal."""
+        mode = get_current_mode()
+        goal = get_plan_goal()
+        return f"Mode: {mode.value} | Goal: {goal or '(none)'}"
+
+
+def register_approve_plan(agent: Any) -> None:
+    """Register the ``approve_plan`` tool on *agent*."""
+
+    @agent.tool
+    def approve_plan(context: RunContext) -> str:
+        """Approve the current plan and enter auto-edit mode."""
+        set_plan_mode(PlanModeState.AUTO_EDIT)
+        bus = get_message_bus()
+        bus.emit_info("✅ Plan approved — entering auto-edit mode")
+        return "Plan approved. Auto-edit mode active."
+
+
+def register_open_plan_in_editor(agent: Any) -> None:
+    """Register the ``open_plan_in_editor`` tool on *agent*."""
+
+    @agent.tool
+    def open_plan_in_editor(context: RunContext) -> str:
+        """Open the most recent plan file in the default editor."""
+        plans_dir = Path("plans")
+        if not plans_dir.exists():
+            return "Error: plans directory not found."
+
+        plan_files = sorted(
+            plans_dir.glob("*.md"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        if not plan_files:
+            return "Error: no plan files found."
+
+        plan_path = plan_files[0]
+
+        candidates = []
+        editor = os.environ.get("EDITOR")
+        if editor:
+            candidates.append(editor)
+        candidates.extend(["nvim", "vim", "nano"])
+
+        for editor in candidates:
+            try:
+                subprocess.run([editor, str(plan_path)], check=False)
+                return f"Opened {plan_path} in {editor}"
+            except FileNotFoundError:
+                continue
+
+        return "Error: no suitable editor found (tried $EDITOR, nvim, vim, nano)."

code_muse/plugins/plan_mode/register_callbacks.py

@@ -0,0 +1,121 @@
+"""Callback registration for the Plan Mode plugin.
+
+Registers:
+    - ``enter_plan_mode``, ``exit_plan_mode``, ``get_plan_mode`` tools
+    - ``pre_tool_call`` enforcement hook
+    - ``/plan [goal]``, ``/plan exit`` slash commands
+    - ``/mode`` slash command (delegated to :mod:`mode_cycling`)
+    - Help entries for all slash commands
+"""
+
+import logging
+from typing import Any
+
+from code_muse.callbacks import register_callback
+from code_muse.messaging import emit_info, emit_success
+from code_muse.plugins.plan_mode.mode_cycling import cycle_mode
+from code_muse.plugins.plan_mode.plan_hooks import plan_mode_pre_tool_call_hook
+from code_muse.plugins.plan_mode.plan_mode_tools import (
+    PlanModeState,
+    get_current_mode,
+    register_approve_plan,
+    register_enter_plan_mode,
+    register_exit_plan_mode,
+    register_get_plan_mode,
+    register_open_plan_in_editor,
+    set_plan_mode,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Tool registration callback
+# ---------------------------------------------------------------------------
+
+
+def _register_plan_mode_tools() -> list[dict[str, Any]]:
+    """Return tool definitions for the plan mode plugin."""
+    return [
+        {"name": "enter_plan_mode", "register_func": register_enter_plan_mode},
+        {"name": "exit_plan_mode", "register_func": register_exit_plan_mode},
+        {"name": "get_plan_mode", "register_func": register_get_plan_mode},
+        {"name": "approve_plan", "register_func": register_approve_plan},
+        {"name": "open_plan_in_editor", "register_func": register_open_plan_in_editor},
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Slash-command handlers
+# ---------------------------------------------------------------------------
+
+
+def _on_custom_command(command: str, name: str) -> bool | None:
+    """Handle ``/plan``, ``/plan exit``, and ``/mode`` commands."""
+    if name == "mode":
+        return _handle_mode_command(command)
+
+    if name == "plan":
+        return _handle_plan_command(command)
+
+    return None
+
+
+def _handle_plan_command(command: str) -> bool:
+    """Handle ``/plan [goal]`` and ``/plan exit``."""
+    parts = command.split(maxsplit=1)
+    remainder = parts[1].strip() if len(parts) > 1 else ""
+
+    if remainder.lower() == "exit":
+        set_plan_mode(PlanModeState.DEFAULT)
+        emit_success("📋 Plan mode exited — normal editing resumed")
+        return True
+
+    # remainder is the optional goal (may be empty)
+    set_plan_mode(PlanModeState.PLAN, remainder)
+    if remainder:
+        emit_success(f"📋 Plan mode active — goal: {remainder}")
+    else:
+        emit_success("📋 Plan mode active")
+    return True
+
+
+def _handle_mode_command(command: str) -> bool:
+    """Handle ``/mode`` — cycle through DEFAULT → AUTO_EDIT → PLAN."""
+    old_mode = get_current_mode()
+    new_mode = cycle_mode()
+    mode_names = {
+        PlanModeState.DEFAULT: "Default",
+        PlanModeState.AUTO_EDIT: "Auto-edit",
+        PlanModeState.PLAN: "Plan",
+    }
+    emit_info(
+        f"🔁 Mode changed: {mode_names.get(old_mode, old_mode.value)} → "
+        f"{mode_names.get(new_mode, new_mode.value)}"
+    )
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Help entries
+# ---------------------------------------------------------------------------
+
+
+def _on_custom_command_help() -> list[tuple[str, str]]:
+    return [
+        ("plan", "Enter plan mode (optionally with a goal)"),
+        ("plan exit", "Exit plan mode and resume normal editing"),
+        ("mode", "Cycle through DEFAULT → AUTO_EDIT → PLAN mode"),
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Register all callbacks
+# ---------------------------------------------------------------------------
+
+register_callback("register_tools", _register_plan_mode_tools)
+register_callback("pre_tool_call", plan_mode_pre_tool_call_hook)
+register_callback("custom_command", _on_custom_command)
+register_callback("custom_command_help", _on_custom_command_help)
+
+logger.debug("Plan Mode plugin callbacks registered")

code_muse/plugins/plugin_trust/register_callbacks.py

@@ -0,0 +1,140 @@
+"""Builtin plugin trust command handler.
+
+Implements /plugin list, /plugin trust <name>, /plugin revoke <name>,
+and /plugin help.
+"""
+
+import logging
+
+from code_muse.callbacks import register_callback
+from code_muse.plugins import (
+    _PLUGINS_LOADED,
+    compute_plugin_hash,
+    get_user_plugins_dir,
+    is_plugin_trusted,
+    record_plugin_trust,
+    revoke_plugin_trust,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _plugin_command_help() -> list[tuple[str, str]]:
+    """Return help entries for plugin trust commands."""
+    return [
+        ("plugin list", "List discovered user plugins with trust status"),
+        ("plugin trust <name>", "Trust a user plugin by content hash"),
+        ("plugin revoke <name>", "Revoke trust for a user plugin"),
+        ("plugin help", "Show plugin trust command help"),
+    ]
+
+
+def _handle_plugin_command(command: str, name: str) -> str | None:
+    """Handle /plugin subcommands."""
+    if name != "plugin":
+        return None
+
+    parts = command.strip().split()
+    if len(parts) < 2:
+        return _plugin_help_text()
+
+    sub = parts[1].lower()
+
+    if sub == "help":
+        return _plugin_help_text()
+
+    if sub in ("list", "plugins"):
+        return _plugin_list()
+
+    if sub == "trust":
+        if len(parts) < 3:
+            return "Usage: /plugin trust <plugin_name>"
+        return _plugin_trust(parts[2])
+
+    if sub == "revoke":
+        if len(parts) < 3:
+            return "Usage: /plugin revoke <plugin_name>"
+        return _plugin_revoke(parts[2])
+
+    return f"Unknown /plugin subcommand: {sub}. Usage: /plugin trust|revoke|list|help"
+
+
+def _plugin_help_text() -> str:
+    return (
+        "Plugin trust commands:\n"
+        "  /plugin list          — List discovered user plugins with hash & trust status\n"
+        "  /plugin trust <name>  — Record trust for a user plugin\n"
+        "  /plugin revoke <name> — Revoke trust for a user plugin\n"
+        "  /plugin help          — Show this help"
+    )
+
+
+def _plugin_list() -> str:
+    """Summarise discovered user plugins with hash and trust status."""
+    user_dir = get_user_plugins_dir()
+    if not user_dir.exists():
+        return f"No user plugins directory found at {user_dir}"
+
+    entries: list[str] = []
+    for item in sorted(user_dir.iterdir()):
+        if not item.is_dir() or item.name.startswith(".") or item.name.startswith("_"):
+            continue
+
+        has_callbacks = (item / "register_callbacks.py").exists()
+        has_init = (item / "__init__.py").exists()
+        if not has_callbacks and not has_init:
+            continue
+
+        try:
+            content_hash = compute_plugin_hash(item)
+        except OSError as exc:
+            logger.warning("Failed to hash plugin %s: %s", item.name, exc)
+            continue
+
+        trusted = is_plugin_trusted(item.name, content_hash)
+        status = "trusted" if trusted else "untrusted"
+        entries.append(f"  {item.name:20}  {status:10}  {content_hash[:12]}…  {item}")
+
+    if not entries:
+        return f"No user plugins found in {user_dir}"
+
+    header = f"{'Name':20}  {'Status':10}  {'Hash':14}  Path"
+    return "User plugins:\n" + header + "\n" + "\n".join(entries)
+
+
+def _plugin_trust(plugin_name: str) -> str:
+    """Compute current hash and record trust for a user plugin."""
+    user_dir = get_user_plugins_dir()
+    plugin_dir = user_dir / plugin_name
+
+    if not plugin_dir.exists() or not plugin_dir.is_dir():
+        return f"Plugin '{plugin_name}' not found in {user_dir}"
+
+    if (
+        not (plugin_dir / "register_callbacks.py").exists()
+        and not (plugin_dir / "__init__.py").exists()
+    ):
+        return f"Plugin '{plugin_name}' has no register_callbacks.py or __init__.py"
+
+    try:
+        content_hash = compute_plugin_hash(plugin_dir)
+    except OSError as exc:
+        logger.warning("Failed to hash plugin %s: %s", plugin_name, exc)
+        return f"Failed to compute hash for plugin '{plugin_name}'"
+
+    record_plugin_trust(plugin_name, content_hash, str(plugin_dir))
+
+    msg = f"Trust recorded for plugin '{plugin_name}' (hash: {content_hash[:12]}…)."
+    if _PLUGINS_LOADED:
+        msg += " Restart Muse to load newly trusted plugins."
+    return msg
+
+
+def _plugin_revoke(plugin_name: str) -> str:
+    """Revoke trust for a user plugin."""
+    revoke_plugin_trust(plugin_name)
+    return f"Trust revoked for plugin '{plugin_name}'. Restart Muse to unload."
+
+
+register_callback("custom_command", _handle_plugin_command)
+register_callback("custom_command_help", _plugin_command_help)

code_muse/plugins/policy_engine/__init__.py

@@ -0,0 +1,46 @@
+"""Policy Engine plugin for Muse.
+
+TOML-based rules that control tool execution:
+- allow → auto-approve (skip confirmation)
+- deny → block with message
+- ask_user → show normal confirmation dialog
+
+Rules match by toolName (with * wildcard) and optional commandPrefix
+(for shell commands). Rules are loaded from:
+- User tier: ~/.muse/policies/*.toml
+- Project tier: .muse/policies/*.toml
+
+Priority resolves conflicts (higher wins).
+"""
+
+from code_muse.plugins.policy_engine.approval_flow_integration import (
+    integrate_policy_check,
+)
+from code_muse.plugins.policy_engine.policy_evaluator import (
+    evaluate_policy,
+    evaluate_tool_policy,
+)
+from code_muse.plugins.policy_engine.policy_file_discovery import (
+    clear_policy_cache,
+    discover_policy_files,
+    load_all_policies,
+)
+from code_muse.plugins.policy_engine.policy_toml_schema import (
+    Decision,
+    ToolRule,
+    parse_policy_toml,
+    validate_rules,
+)
+
+__all__ = [
+    "Decision",
+    "ToolRule",
+    "clear_policy_cache",
+    "discover_policy_files",
+    "evaluate_policy",
+    "evaluate_tool_policy",
+    "integrate_policy_check",
+    "load_all_policies",
+    "parse_policy_toml",
+    "validate_rules",
+]

code_muse/plugins/policy_engine/approval_flow_integration.py

@@ -0,0 +1,59 @@
+import logging
+from typing import Any
+
+from code_muse.plugins.policy_engine.policy_evaluator import (
+    evaluate_policy,
+    evaluate_tool_policy,
+)
+from code_muse.plugins.policy_engine.policy_file_discovery import load_all_policies
+from code_muse.plugins.policy_engine.policy_toml_schema import Decision, ToolRule
+
+logger = logging.getLogger(__name__)
+
+
+def integrate_policy_check(
+    tool_name: str,
+    command: str | None = None,
+    rules: list[ToolRule] | None = None,
+) -> dict[str, Any] | None:
+    if rules is None:
+        rules = load_all_policies()
+
+    if command is not None:
+        decision, matched_rule = evaluate_policy(tool_name, command, rules)
+    else:
+        decision, matched_rule = evaluate_tool_policy(tool_name, rules)
+
+    if decision == Decision.ALLOW:
+        if command is not None:
+            # Shell command path: signal auto_approval to skip confirmation
+            logger.info(
+                "Policy auto-approved %s (command=%s, rule=%s)",
+                tool_name,
+                command,
+                matched_rule.description if matched_rule else "default",
+            )
+            return {"auto_approve": True}
+        # Non-shell tool path: auto_approve not relevant, just allow
+        logger.debug("Policy allowed %s (no confirmation to skip)", tool_name)
+        return None
+
+    if decision == Decision.DENY:
+        message = _build_block_message(matched_rule, tool_name)
+        logger.warning(
+            "Policy blocked %s (command=%s): %s", tool_name, command, message
+        )
+        return {"blocked": True, "error_message": message}
+
+    if decision == Decision.ASK_USER:
+        logger.debug("Policy ASK_USER for %s (command=%s)", tool_name, command)
+        return None
+
+    # Should never reach here, but default to normal flow
+    return None
+
+
+def _build_block_message(rule: Any, tool_name: str) -> str:
+    if rule and getattr(rule, "description", None):
+        return f"🚫 Policy: {rule.description}"
+    return f"🚫 Policy: blocked {tool_name}"