code-muse 0.0.1__py3-none-any.whl

code_muse/plugins/force_push_guard/register_callbacks.py

@@ -0,0 +1,144 @@
+"""Callback registration for the force push guard plugin.
+
+Hooks into the run_shell_command phase to intercept git force push
+commands and prompt the user for approval before allowing them through.
+Returns {"blocked": True} to deny, None to allow.
+"""
+
+import sys
+from typing import Any
+
+from rich.text import Text
+
+from code_muse.callbacks import register_callback
+from code_muse.messaging import emit_info, emit_warning
+from code_muse.plugins.force_push_guard.detector import detect_force_push
+
+
+def _is_interactive() -> bool:
+    """Check if we're in an interactive terminal that can show prompts."""
+    try:
+        return sys.stdin.isatty()
+    except AttributeError, OSError:
+        return False
+
+
+async def force_push_guard_callback(
+    context: Any, command: str, cwd: str | None = None, timeout: int = 60
+) -> dict[str, Any | None]:
+    """Intercept shell commands containing git force push operations.
+
+    When a force push is detected:
+    - Interactive TTY: prompt the user with approve/reject options.
+    - Non-interactive (CI, sub-agent, piped): hard-block with an error.
+
+    This runs on *every* shell command, but the heavy lifting (regex
+    matching) is gated behind a cheap "push" substring check inside
+    detect_force_push().
+
+    Args:
+        context: Execution context (unused).
+        command: The shell command about to run.
+        cwd: Working directory (unused).
+        timeout: Command timeout (unused).
+
+    Returns:
+        None if the command is safe to proceed or user approved it.
+        Dict with blocked=True if a force push was detected and rejected.
+    """
+    match = detect_force_push(command)
+    if match is None:
+        return None
+
+    # --- Interactive TTY: ask the user ---
+    if _is_interactive():
+        return await _prompt_user_approval(command, match)
+
+    # --- Non-interactive: hard-block ---
+    return _block_command(command, match)
+
+
+async def _prompt_user_approval(command: str, match: Any) -> dict[str, Any | None]:
+    """Show an interactive approval prompt for the detected force push.
+
+    Args:
+        command: The original shell command.
+        match: The ForcePushMatch from the detector.
+
+    Returns:
+        None if user approves, Dict with blocked=True if rejected.
+    """
+    from code_muse.tools.common import get_user_approval_async
+
+    panel_content = Text()
+    panel_content.append("⚠️  Force push detected: ", style="bold yellow")
+    panel_content.append(match.pattern_name, style="bold red")
+    panel_content.append("\n", style="")
+    panel_content.append(f"  {match.description}", style="dim")
+    panel_content.append("\n\n", style="")
+    panel_content.append("$ ", style="bold green")
+    panel_content.append(command, style="bold white")
+    panel_content.append(
+        "\n\nForce pushing rewrites remote history and can destroy others' work.",
+        style="yellow",
+    )
+
+    confirmed, user_feedback = await get_user_approval_async(
+        title="Force Push Guard 🛡️",
+        content=panel_content,
+        border_style="red",
+    )
+
+    if confirmed:
+        emit_info("⚠️  Force push approved — proceeding with caution.")
+        return None  # Allow the command through
+
+    # Rejected
+    reason = user_feedback or "User rejected force push"
+    return {
+        "blocked": True,
+        "reasoning": f"Force push rejected: {match.pattern_name} — {reason}",
+        "error_message": (
+            f"🛑 Force push rejected. Detected {match.pattern_name} "
+            f"in command:\n  {command}\n"
+            f"  {match.description}\n"
+            f"Feedback: {reason}"
+        ),
+    }
+
+
+def _block_command(command: str, match: Any) -> dict[str, Any]:
+    """Hard-block a force push in non-interactive contexts.
+
+    Args:
+        command: The original shell command.
+        match: The ForcePushMatch from the detector.
+
+    Returns:
+        Dict with blocked=True and a descriptive error.
+    """
+    error_message = (
+        f"🛑 Force push blocked! Detected {match.pattern_name} "
+        f"in command:\n  {command}\n"
+        f"  {match.description}\n\n"
+        f"Force pushing rewrites remote history and can destroy others' work.\n"
+        f"If you *really* need to force push, use the exact command directly\n"
+        f"in your terminal (outside Muse) after double-checking the target branch."
+    )
+
+    emit_warning(error_message)
+
+    return {
+        "blocked": True,
+        "reasoning": f"Force push detected: {match.pattern_name} — {match.description}",
+        "error_message": error_message,
+    }
+
+
+def register() -> None:
+    """Register the force push guard callback."""
+    register_callback("run_shell_command", force_push_guard_callback)
+
+
+# Auto-register when this module is imported
+register()

code_muse/plugins/force_push_guard/test_detector.py

@@ -0,0 +1,143 @@
+"""Tests for the force push guard detector."""
+
+from code_muse.plugins.force_push_guard.detector import detect_force_push
+
+
+class TestDetectForcePush:
+    """Test suite for force push pattern detection."""
+
+    # --- Should BLOCK these commands ---
+
+    def test_long_force_flag(self):
+        result = detect_force_push("git push --force origin main")
+        assert result is not None
+        assert result.pattern_name == "--force"
+
+    def test_short_f_flag(self):
+        result = detect_force_push("git push -f origin main")
+        assert result is not None
+        assert result.pattern_name == "-f"
+
+    def test_capital_f_flag(self):
+        result = detect_force_push("git push -F origin main")
+        assert result is not None
+        assert result.pattern_name == "-F"
+
+    def test_force_with_lease(self):
+        result = detect_force_push("git push --force-with-lease origin feature")
+        assert result is not None
+        assert result.pattern_name == "--force-with-lease"
+
+    def test_force_if_includes(self):
+        result = detect_force_push("git push --force-if-includes origin feature")
+        assert result is not None
+        assert result.pattern_name == "--force-if-includes"
+
+    def test_plus_refspec(self):
+        result = detect_force_push("git push origin +main")
+        assert result is not None
+        assert result.pattern_name == "+refspec"
+
+    def test_plus_refspec_head(self):
+        result = detect_force_push("git push origin +HEAD:refs/heads/main")
+        assert result is not None
+        assert result.pattern_name == "+refspec"
+
+    def test_force_before_remote(self):
+        result = detect_force_push(
+            "git push --force-with-lease --set-upstream origin foo"
+        )
+        assert result is not None
+        assert result.pattern_name == "--force-with-lease"
+
+    def test_force_after_remote(self):
+        result = detect_force_push("git push origin feature --force")
+        assert result is not None
+        assert result.pattern_name == "--force"
+
+    def test_force_flag_with_equals(self):
+        result = detect_force_push("git push --force=yes origin main")
+        assert result is not None
+        assert result.pattern_name == "--force"
+
+    def test_force_with_other_flags(self):
+        result = detect_force_push("git push -v -f origin main")
+        assert result is not None
+        assert result.pattern_name == "-f"
+
+    # --- Should ALLOW these commands ---
+
+    def test_normal_push(self):
+        assert detect_force_push("git push origin main") is None
+
+    def test_push_with_set_upstream(self):
+        assert detect_force_push("git push --set-upstream origin feature") is None
+
+    def test_push_with_tags(self):
+        assert detect_force_push("git push origin --tags") is None
+
+    def test_push_u(self):
+        assert detect_force_push("git push -u origin main") is None
+
+    def test_git_pull(self):
+        assert detect_force_push("git pull origin main") is None
+
+    def test_git_status(self):
+        assert detect_force_push("git status") is None
+
+    def test_unrelated_command(self):
+        assert detect_force_push("npm install --force") is None
+
+    def test_empty_string(self):
+        assert detect_force_push("") is None
+
+    def test_echo_push(self):
+        assert detect_force_push("echo 'git push --force'") is None
+
+    def test_push_dry_run(self):
+        assert detect_force_push("git push --dry-run origin main") is None
+
+    def test_git_push_all(self):
+        assert detect_force_push("git push --all origin") is None
+
+    def test_git_push_mirror(self):
+        """--mirror IS destructive, but it's not a 'force push' per se.
+        We don't block it — different safety concern."""
+        assert detect_force_push("git push --mirror") is None
+
+    def test_push_no_force_file(self):
+        """A file named '--force' in a weirdly structured command shouldn't match."""
+        # This is a contrived edge case — the regex should not match
+        assert detect_force_push("git push origin main") is None
+
+    def test_grep_push(self):
+        """grep containing 'push' should not trigger."""
+        assert detect_force_push("grep -r push src/") is None
+
+    # --- Compound commands (shell operators) ---
+
+    def test_compound_and_force(self):
+        result = detect_force_push("cd foo && git push --force origin main")
+        assert result is not None
+        assert result.pattern_name == "--force"
+
+    def test_compound_semicolon_force(self):
+        result = detect_force_push("echo hi; git push -f origin main")
+        assert result is not None
+        assert result.pattern_name == "-f"
+
+    def test_compound_or_force(self):
+        result = detect_force_push("git pull || git push --force origin main")
+        assert result is not None
+        assert result.pattern_name == "--force"
+
+    def test_compound_pipe_not_force(self):
+        """Piped git push (uncommon) should still be caught if forced."""
+        result = detect_force_push("cat file | git push --force")
+        # Note: piping to git push makes no sense, but regex should still match
+        assert result is not None
+        assert result.pattern_name == "--force"
+
+    def test_compound_and_normal_push(self):
+        """Compound with a normal push should be allowed."""
+        assert detect_force_push("cd foo && git push origin main") is None

code_muse/plugins/frontend_emitter/__init__.py

@@ -0,0 +1,25 @@
+"""Frontend emitter plugin for Muse.
+
+This plugin provides event emission capabilities for frontend integration,
+allowing WebSocket handlers to subscribe to real-time events from the
+agent system including tool calls, streaming events, and agent invocations.
+
+Usage:
+    from code_muse.plugins.frontend_emitter.emitter import (
+        emit_event,
+        subscribe,
+        unsubscribe,
+        get_recent_events,
+    )
+
+    # Subscribe to events
+    queue = subscribe()
+
+    # Process events in your WebSocket handler
+    while True:
+        event = await queue.get()
+        await websocket.send_json(event)
+
+    # Clean up
+    unsubscribe(queue)
+"""

code_muse/plugins/frontend_emitter/emitter.py

@@ -0,0 +1,121 @@
+"""Event emitter for frontend integration.
+
+Provides a global event queue that WebSocket handlers can subscribe to.
+Events are JSON-serializable dicts with type, timestamp, and data.
+"""
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+from code_muse.config import (
+    get_frontend_emitter_enabled,
+    get_frontend_emitter_max_recent_events,
+    get_frontend_emitter_queue_size,
+)
+
+logger = logging.getLogger(__name__)
+
+# Global state for event distribution
+_subscribers: set[asyncio.Queue[dict[str, Any]]] = set()
+_recent_events: list[dict[str, Any]] = []  # Keep last N events for new subscribers
+
+
+def emit_event(event_type: str, data: Any = None) -> None:
+    """Emit an event to all subscribers.
+
+    Creates a structured event dict with unique ID, type, timestamp, and data,
+    then broadcasts it to all active subscriber queues.
+
+    Args:
+        event_type: Type of event (e.g., "tool_call_start", "stream_token")
+        data: Event data payload - should be JSON-serializable
+    """
+    # Early return if emitter is disabled
+    if not get_frontend_emitter_enabled():
+        return
+
+    event: dict[str, Any] = {
+        "id": str(uuid4()),
+        "type": event_type,
+        "timestamp": datetime.now(UTC).isoformat(),
+        "data": data or {},
+    }
+
+    # Store in recent events for replay to new subscribers
+    max_recent = get_frontend_emitter_max_recent_events()
+    _recent_events.append(event)
+    if len(_recent_events) > max_recent:
+        _recent_events.pop(0)
+
+    # Broadcast to all active subscribers
+    for subscriber_queue in _subscribers.copy():
+        try:
+            subscriber_queue.put_nowait(event)
+        except asyncio.QueueFull:
+            logger.warning(f"Subscriber queue full, dropping event: {event_type}")
+        except Exception as e:
+            logger.error(f"Failed to emit event to subscriber: {e}")
+
+
+def subscribe() -> asyncio.Queue[dict[str, Any]]:
+    """Subscribe to events.
+
+    Creates and returns a new async queue that will receive all future events.
+    The queue has a configurable max size (via frontend_emitter_queue_size)
+    to prevent unbounded memory growth if the subscriber is slow to process events.
+
+    Returns:
+        An asyncio.Queue that will receive event dictionaries.
+    """
+    queue_size = get_frontend_emitter_queue_size()
+    queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=queue_size)
+    _subscribers.add(queue)
+    logger.debug(f"New subscriber added, total subscribers: {len(_subscribers)}")
+    return queue
+
+
+def unsubscribe(queue: asyncio.Queue[dict[str, Any]]) -> None:
+    """Unsubscribe from events.
+
+    Removes the queue from the subscriber set. Safe to call even if the queue
+    was never subscribed or already unsubscribed.
+
+    Args:
+        queue: The queue returned from subscribe()
+    """
+    _subscribers.discard(queue)
+    logger.debug(f"Subscriber removed, remaining subscribers: {len(_subscribers)}")
+
+
+def get_recent_events() -> list[dict[str, Any]]:
+    """Get recent events for new subscribers.
+
+    Returns a copy of the most recent events (up to frontend_emitter_max_recent_events).
+    Useful for allowing new WebSocket connections to "catch up" on
+    recent activity.
+
+    Returns:
+        A list of recent event dictionaries.
+    """
+    return _recent_events.copy()
+
+
+def get_subscriber_count() -> int:
+    """Get the current number of active subscribers.
+
+    Returns:
+        Number of active subscriber queues.
+    """
+    return len(_subscribers)
+
+
+def clear_recent_events() -> None:
+    """Clear the recent events buffer.
+
+    Useful for testing or resetting state.
+    """
+    _recent_events.clear()
+    logger.debug("Recent events cleared")

code_muse/plugins/frontend_emitter/register_callbacks.py

@@ -0,0 +1,259 @@
+"""Callback registration for frontend event emission.
+
+This module registers callbacks for various agent events and emits them
+to subscribed WebSocket handlers via the emitter module.
+"""
+
+import logging
+import time
+from typing import Any
+
+from code_muse.callbacks import register_callback
+from code_muse.plugins.frontend_emitter.emitter import emit_event
+
+logger = logging.getLogger(__name__)
+
+
+async def on_pre_tool_call(
+    tool_name: str, tool_args: dict[str, Any], context: Any = None
+) -> None:
+    """Emit an event when a tool call starts.
+
+    Args:
+        tool_name: Name of the tool being called
+        tool_args: Arguments being passed to the tool
+        context: Optional context data for the tool call
+    """
+    try:
+        emit_event(
+            "tool_call_start",
+            {
+                "tool_name": tool_name,
+                "tool_args": _sanitize_args(tool_args),
+                "start_time": time.time(),
+            },
+        )
+        logger.debug(f"Emitted tool_call_start for {tool_name}")
+    except Exception as e:
+        logger.error(f"Failed to emit pre_tool_call event: {e}")
+
+
+async def on_post_tool_call(
+    tool_name: str,
+    tool_args: dict[str, Any],
+    result: Any,
+    duration_ms: float,
+    context: Any = None,
+) -> None:
+    """Emit an event when a tool call completes.
+
+    Args:
+        tool_name: Name of the tool that was called
+        tool_args: Arguments that were passed to the tool
+        result: The result returned by the tool
+        duration_ms: Execution time in milliseconds
+        context: Optional context data for the tool call
+    """
+    try:
+        emit_event(
+            "tool_call_complete",
+            {
+                "tool_name": tool_name,
+                "tool_args": _sanitize_args(tool_args),
+                "duration_ms": duration_ms,
+                "success": _is_successful_result(result),
+                "result_summary": _summarize_result(result),
+            },
+        )
+        logger.debug(
+            f"Emitted tool_call_complete for {tool_name} ({duration_ms:.2f}ms)"
+        )
+    except Exception as e:
+        logger.error(f"Failed to emit post_tool_call event: {e}")
+
+
+async def on_stream_event(
+    event_type: str, event_data: Any, agent_session_id: str | None = None
+) -> None:
+    """Emit streaming events from the agent.
+
+    Args:
+        event_type: Type of the streaming event
+        event_data: Data associated with the event
+        agent_session_id: Optional session ID of the agent emitting the event
+    """
+    try:
+        emit_event(
+            "stream_event",
+            {
+                "event_type": event_type,
+                "event_data": _sanitize_event_data(event_data),
+                "agent_session_id": agent_session_id,
+            },
+        )
+        logger.debug(f"Emitted stream_event: {event_type}")
+    except Exception as e:
+        logger.error(f"Failed to emit stream_event: {e}")
+
+
+async def on_invoke_agent(*args: Any, **kwargs: Any) -> None:
+    """Emit an event when an agent is invoked.
+
+    Args:
+        *args: Positional arguments from the invoke_agent callback
+        **kwargs: Keyword arguments from the invoke_agent callback
+    """
+    try:
+        # Extract relevant info from args/kwargs
+        agent_info = {
+            "agent_name": kwargs.get("agent_name") or (args[0] if args else None),
+            "session_id": kwargs.get("session_id"),
+            "prompt_preview": _truncate_string(
+                kwargs.get("prompt") or (args[1] if len(args) > 1 else None),
+                max_length=200,
+            ),
+        }
+        emit_event("agent_invoked", agent_info)
+        logger.debug(f"Emitted agent_invoked: {agent_info.get('agent_name')}")
+    except Exception as e:
+        logger.error(f"Failed to emit invoke_agent event: {e}")
+
+
+def _sanitize_args(args: dict[str, Any]) -> dict[str, Any]:
+    """Sanitize tool arguments for safe emission.
+
+    Truncates large values and removes potentially sensitive data.
+
+    Args:
+        args: The raw tool arguments
+
+    Returns:
+        Sanitized arguments safe for emission
+    """
+    if not isinstance(args, dict):
+        return {}
+
+    sanitized: dict[str, Any] = {}
+    for key, value in args.items():
+        if isinstance(value, str):
+            sanitized[key] = _truncate_string(value, max_length=500)
+        elif isinstance(value, (int, float, bool, type(None))):
+            sanitized[key] = value
+        elif isinstance(value, (list, dict)):
+            # Just indicate the type and length for complex types
+            sanitized[key] = f"<{type(value).__name__}[{len(value)}]>"
+        else:
+            sanitized[key] = f"<{type(value).__name__}>"
+
+    return sanitized
+
+
+def _sanitize_event_data(data: Any) -> Any:
+    """Sanitize event data for safe emission.
+
+    Args:
+        data: The raw event data
+
+    Returns:
+        Sanitized data safe for emission
+    """
+    if data is None:
+        return None
+
+    if isinstance(data, str):
+        return _truncate_string(data, max_length=1000)
+
+    if isinstance(data, (int, float, bool)):
+        return data
+
+    if isinstance(data, dict):
+        return {k: _sanitize_event_data(v) for k, v in list(data.items())[:20]}
+
+    if isinstance(data, (list, tuple)):
+        return [_sanitize_event_data(item) for item in data[:20]]
+
+    return f"<{type(data).__name__}>"
+
+
+def _is_successful_result(result: Any) -> bool:
+    """Determine if a tool result indicates success.
+
+    Args:
+        result: The tool result
+
+    Returns:
+        True if the result appears successful
+    """
+    if result is None:
+        return True  # No result often means success
+
+    if isinstance(result, dict):
+        # Check for error indicators
+        if result.get("error"):
+            return False
+        return result.get("success") is not False
+
+    if isinstance(result, bool):
+        return result
+
+    return True  # Default to success
+
+
+def _summarize_result(result: Any) -> str:
+    """Create a brief summary of a tool result.
+
+    Args:
+        result: The tool result
+
+    Returns:
+        A string summary of the result
+    """
+    if result is None:
+        return "<no result>"
+
+    if isinstance(result, str):
+        return _truncate_string(result, max_length=200)
+
+    if isinstance(result, dict):
+        if "error" in result:
+            return f"Error: {_truncate_string(str(result['error']), max_length=100)}"
+        if "message" in result:
+            return _truncate_string(str(result["message"]), max_length=100)
+        return f"<dict with {len(result)} keys>"
+
+    if isinstance(result, (list, tuple)):
+        return f"<{type(result).__name__}[{len(result)}]>"
+
+    return _truncate_string(str(result), max_length=200)
+
+
+def _truncate_string(value: Any, max_length: int = 100) -> str | None:
+    """Truncate a string value if it exceeds max_length.
+
+    Args:
+        value: The value to truncate (will be converted to str)
+        max_length: Maximum length before truncation
+
+    Returns:
+        Truncated string or None if value is None
+    """
+    if value is None:
+        return None
+
+    s = str(value)
+    if len(s) > max_length:
+        return s[: max_length - 3] + "..."
+    return s
+
+
+def register() -> None:
+    """Register all frontend emitter callbacks."""
+    register_callback("pre_tool_call", on_pre_tool_call)
+    register_callback("post_tool_call", on_post_tool_call)
+    register_callback("stream_event", on_stream_event)
+    register_callback("invoke_agent", on_invoke_agent)
+    logger.debug("Frontend emitter callbacks registered")
+
+
+# Auto-register callbacks when this module is imported
+register()

code_muse/plugins/gac/__init__.py

@@ -0,0 +1,4 @@
+"""GAC plugin — AI-powered git commits via slash commands.
+
+Provides /gac, /gac push, and /gac bump commands.
+"""