misterdev 0.2.0__py3-none-any.whl

misterdev/mcp_server.py

@@ -0,0 +1,208 @@
+"""misterdev as an MCP server: drive the orchestrator from any MCP client.
+
+This is a THIN adapter over the same ``ProjectOrchestrator`` the CLI uses. The
+heavy work — reading the codebase, symbol-graph context management, multi-step
+reasoning, model selection, budget — all runs IN THIS PROCESS with misterdev's
+own LLM key. The client only sends a short instruction and receives a short
+summary, so the codebase never enters the client's context window and the
+context-scaling misterdev exists to provide is fully preserved.
+
+Run it with the ``misterdev-mcp`` entry point (needs the ``mcp`` extra:
+``pip install 'misterdev[mcp]'``). Tool definitions carry per-parameter
+descriptions and honest behavioral annotations (read-only vs. destructive,
+idempotent, open-world) so an AI agent can pick and call them correctly.
+"""
+
+from typing import Annotated, Any, Dict, Optional
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from misterdev.agent import ProjectOrchestrator
+
+# Conservative default $ ceiling for an AI-client-triggered build (the CLI
+# default is higher). The client can raise it explicitly per call.
+_DEFAULT_MCP_BUDGET = 10.0
+
+mcp = FastMCP("misterdev")
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="List registered projects",
+        readOnlyHint=True,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def list_projects() -> Dict[str, Any]:
+    """List every project misterdev currently knows about.
+
+    Use this first to see what is registered before calling ``status`` or
+    ``build`` on a specific one. Read-only — nothing is changed.
+
+    Returns a mapping of project id to its registered path and name.
+    """
+    return ProjectOrchestrator().list_projects()
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Project status",
+        readOnlyHint=True,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def status(
+    path: Annotated[
+        str,
+        Field(
+            description="Path to the project (its directory, containing project.yaml)."
+        ),
+    ],
+) -> Dict[str, Any]:
+    """Show a project's tasks and their current state.
+
+    Use to inspect what work exists and how far it has progressed, e.g. before
+    deciding whether to ``run`` pending tasks or ``build`` something new.
+    Read-only — it does not run anything.
+
+    Returns the project's tasks with their statuses.
+    """
+    return ProjectOrchestrator().get_project_status(path)
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Scan for projects",
+        readOnlyHint=False,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def scan(
+    directory: Annotated[
+        str,
+        Field(description="Directory to search recursively for projects to register."),
+    ],
+) -> str:
+    """Discover misterdev projects under a directory and register them.
+
+    Use once to make projects known to misterdev before inspecting or building
+    them. It writes to the project registry but does not touch project code, and
+    re-scanning the same directory is idempotent.
+
+    Returns a short confirmation string.
+    """
+    ProjectOrchestrator().scan_directory(directory)
+    return f"Scanned and registered projects under: {directory}"
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Autonomous build",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    )
+)
+def build(
+    path: Annotated[
+        str, Field(description="Path to the project to build (its directory).")
+    ],
+    goal: Annotated[
+        str,
+        Field(
+            description="Plain-English goal, or a mode word: 'debug', 'complete', or 'review'."
+        ),
+    ],
+    budget: Annotated[
+        float,
+        Field(description="Maximum dollars to spend on this run.", gt=0),
+    ] = _DEFAULT_MCP_BUDGET,
+    dry_run: Annotated[
+        bool,
+        Field(description="Plan and preview tasks without editing any code."),
+    ] = False,
+    parallel: Annotated[
+        bool,
+        Field(
+            description="Run independent tasks concurrently in isolated git worktrees."
+        ),
+    ] = False,
+    max_tasks: Annotated[
+        Optional[int],
+        Field(description="Cap how many tasks are planned/executed (bounds cost)."),
+    ] = None,
+) -> str:
+    """Autonomously plan AND execute a goal in a project, from scratch.
+
+    This is the main tool. Unlike ``run`` (which executes an existing plan),
+    ``build`` analyzes the project, decomposes ``goal`` into tasks, edits the
+    code, and verifies each change through build/test/lint/typecheck gates,
+    reverting anything that regresses.
+
+    DESTRUCTIVE: it edits files and makes git commits. It refuses to run on a
+    dirty working tree (commit or stash first). Use ``dry_run=True`` to preview
+    the plan without changing anything. ``budget`` caps spend; ``max_tasks``
+    caps scope. It calls an external LLM provider (open-world).
+
+    Returns a compact report: what was done, gate results, and cost.
+    """
+    orch = ProjectOrchestrator()
+    parts = [goal, "--budget", str(budget)]
+    if dry_run:
+        parts.append("--dry-run")
+    if parallel:
+        parts.append("--parallel")
+    if max_tasks is not None:
+        parts += ["--max-tasks", str(max_tasks)]
+    report = orch.build(path, " ".join(parts))
+    outcome = "succeeded" if orch.last_build_succeeded else "did not fully succeed"
+    return f"Build {outcome}.\n\n{report}"
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Run planned tasks",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    )
+)
+def run(
+    path: Annotated[str, Field(description="Path to the project.")],
+    task_id: Annotated[
+        Optional[str],
+        Field(description="Run only this task id; omit to run all pending tasks."),
+    ] = None,
+    dry_run: Annotated[
+        bool, Field(description="Preview the tasks without executing them.")
+    ] = False,
+) -> str:
+    """Execute a project's ALREADY-PLANNED pending tasks (a devplan).
+
+    Use this when tasks already exist (from a prior ``plan`` or devplan) and you
+    just want to run them — it does NOT analyze or decompose a goal; that is
+    ``build``'s job. Pass ``task_id`` to run a single task.
+
+    DESTRUCTIVE: it edits files and commits. Use ``dry_run=True`` to preview.
+    Calls an external LLM provider (open-world). Returns a summary.
+    """
+    orch = ProjectOrchestrator()
+    if task_id:
+        orch.run_task(path, task_id)
+        return f"Ran task {task_id} for {path}."
+    orch.run_project(path, dry_run=dry_run)
+    verb = "Previewed" if dry_run else "Ran"
+    return f"{verb} pending tasks for {path}."
+
+
+def main() -> None:
+    """Console entry point: serve misterdev over stdio MCP."""
+    mcp.run()

misterdev/nl_cli.py

@@ -0,0 +1,149 @@
+"""Natural-language CLI: describe what you want in English; misterdev routes it.
+
+When ``misterdev`` is invoked with something that isn't a known subcommand, the
+whole request is treated as plain English. misterdev's own model maps it to an
+action, shows a preview, asks for confirmation before anything mutating, and
+runs it — so there are no flags to memorize. Known subcommands still work
+unchanged for power users.
+"""
+
+from typing import Any, Dict
+
+from rich.console import Console
+
+from misterdev.config import ConfigManager
+from misterdev.llm.client import create_llm_client
+from misterdev.llm.responses import extract_json_object
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+console = Console()
+
+# Commands the natural-language layer can resolve to. Kept in sync with the CLI.
+KNOWN_COMMANDS = {"scan", "list", "status", "report", "run", "plan", "build"}
+_MUTATING = {"scan", "run", "build"}
+
+_SYSTEM = (
+    "You translate a developer's plain-English request into a single misterdev "
+    "action. misterdev is an autonomous build orchestrator. Reply with ONLY a "
+    "JSON object, no prose."
+)
+
+_PROMPT = """Map this request to one misterdev action.
+
+Commands:
+- build: autonomously build / fix / complete a coding GOAL in a project (edits code).
+- run: run a project's already-planned pending tasks.
+- scan: discover and register projects under a directory.
+- status: show a project's tasks and state.
+- report: summarize the last build's cost and results.
+- list: list registered projects.
+- plan: analyze a project and propose work.
+
+Return ONLY this JSON (omit keys you don't need):
+{{"command": "<one of build|run|scan|status|report|list|plan>",
+  "path": "<project or directory path, default '.'>",
+  "goal": "<the plain-English goal, for build>",
+  "budget": <dollars as number or null>,
+  "dry_run": <true|false>,
+  "parallel": <true|false>,
+  "max_tasks": <int or null>}}
+
+Request: {request}"""
+
+
+def parse_intent(request: str, client) -> Dict[str, Any]:
+    """One model call: request -> a structured action dict (empty on failure)."""
+    text = client.generate_code(_PROMPT.format(request=request), _SYSTEM)
+    obj = extract_json_object(text or "")
+    return obj if isinstance(obj, dict) else {}
+
+
+def _build_args(intent: Dict[str, Any]) -> str:
+    """Render a build intent into the flag string ``ProjectOrchestrator.build`` parses."""
+    parts = [str(intent.get("goal") or "").strip()]
+    budget = intent.get("budget")
+    if isinstance(budget, (int, float)):
+        parts += ["--budget", str(budget)]
+    if intent.get("dry_run"):
+        parts.append("--dry-run")
+    if intent.get("parallel"):
+        parts.append("--parallel")
+    mt = intent.get("max_tasks")
+    if isinstance(mt, int):
+        parts += ["--max-tasks", str(mt)]
+    return " ".join(p for p in parts if p)
+
+
+def preview(intent: Dict[str, Any]) -> str:
+    """A human-readable one-liner of the resolved command."""
+    cmd = intent.get("command")
+    path = intent.get("path") or "."
+    if cmd == "build":
+        return f"build {path} {_build_args(intent)}".strip()
+    if cmd == "run":
+        return f"run {path}" + (" --dry-run" if intent.get("dry_run") else "")
+    if cmd == "scan":
+        return f"scan {path}"
+    return f"{cmd} {path}".strip()
+
+
+def _dispatch(intent: Dict[str, Any], orchestrator) -> int:
+    cmd = intent.get("command")
+    path = intent.get("path") or "."
+    if cmd == "build":
+        report = orchestrator.build(path, _build_args(intent))
+        console.print(report)
+        return 0 if orchestrator.last_build_succeeded else 1
+    if cmd == "run":
+        orchestrator.run_project(path, dry_run=bool(intent.get("dry_run")))
+        return 0
+    if cmd == "scan":
+        orchestrator.scan_directory(path)
+        console.print("[green]Scan complete.[/]")
+        return 0
+    if cmd == "status":
+        console.print(orchestrator.get_project_status(path))
+        return 0
+    if cmd == "list":
+        console.print(orchestrator.list_projects())
+        return 0
+    if cmd == "plan":
+        orchestrator.interactive_plan(path, "")
+        return 0
+    if cmd == "report":
+        console.print(orchestrator.get_project_status(path))
+        return 0
+    return 1
+
+
+def route(request: str, orchestrator, confirm=input) -> int:
+    """Resolve a plain-English request to an action and run it.
+
+    Returns a process exit code. ``confirm`` is injectable for testing.
+    """
+    cfg = ConfigManager().load_project_config(".")
+    try:
+        client = create_llm_client(cfg)
+    except Exception as e:
+        console.print(
+            "[yellow]Natural-language mode needs an LLM configured "
+            f"(model + API key). {e}[/]\nRun `misterdev --help` for the flag-based CLI."
+        )
+        return 1
+
+    intent = parse_intent(request, client)
+    cmd = intent.get("command")
+    if cmd not in KNOWN_COMMANDS:
+        console.print(
+            "[yellow]Couldn't map that to an action.[/] Try `misterdev --help`."
+        )
+        return 1
+
+    console.print(f"[dim]→ I'll run:[/] misterdev {preview(intent)}")
+    if cmd in _MUTATING:
+        answer = confirm("proceed? [Y/n] ").strip().lower()
+        if answer and answer not in ("y", "yes"):
+            console.print("Cancelled.")
+            return 0
+    return _dispatch(intent, orchestrator)

misterdev/plugins.py

@@ -0,0 +1,115 @@
+"""Extensibility registry for tools, gates, and targets.
+
+Built-in capabilities self-register here, and third-party packages contribute
+through ``importlib.metadata`` entry points, so ``pip install misterdev-plugin-x``
+adds a tool/gate/target with zero edits to this codebase:
+
+    # in the plugin package's pyproject.toml
+    [project.entry-points."misterdev.tools"]
+    my_tool = "my_pkg:MyTool"
+
+Entry points are discovered lazily on first lookup and never override a built-in
+of the same name (a plugin cannot hijack ``command``); a plugin that fails to
+import is logged and skipped, never fatal. Registration is thread-safe because
+the orchestrator resolves capabilities from parallel executor workers.
+"""
+
+import importlib.metadata
+import threading
+from typing import Callable, Dict, Generic, List, Optional, TypeVar, Union
+
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+T = TypeVar("T")
+
+
+def _iter_entry_points(group: str):
+    """Entry points for ``group`` across Python 3.10–3.13 metadata APIs."""
+    eps = importlib.metadata.entry_points()
+    if hasattr(eps, "select"):  # 3.10+ selectable interface
+        return eps.select(group=group)
+    return eps.get(group, [])  # pragma: no cover - legacy dict interface (<3.10)
+
+
+class Registry(Generic[T]):
+    """A name -> item map that also discovers external items via entry points.
+
+    ``item`` is whatever the kind needs — for tools/gates it is a class or
+    factory; the registry does not construct it, so a caller stays in control of
+    how the object is instantiated.
+    """
+
+    def __init__(self, kind: str, entry_point_group: str):
+        self.kind = kind
+        self._group = entry_point_group
+        self._items: Dict[str, T] = {}
+        self._lock = threading.Lock()
+        self._entry_points_loaded = False
+
+    def register(
+        self, name: str, item: Optional[T] = None
+    ) -> Union[T, Callable[[T], T]]:
+        """Register ``item`` under ``name``.
+
+        Usable directly (``TOOLS.register("command", CommandTool)``) or as a
+        decorator (``@TOOLS.register("command")``). A later registration of the
+        same name replaces the earlier one, so an in-process override is explicit.
+        """
+
+        def _add(obj: T) -> T:
+            with self._lock:
+                self._items[name] = obj
+            return obj
+
+        return _add(item) if item is not None else _add
+
+    def unregister(self, name: str) -> None:
+        """Remove a registration if present (a no-op otherwise). Lets a plugin be
+        disabled at runtime and keeps tests from leaking registrations."""
+        with self._lock:
+            self._items.pop(name, None)
+
+    def get(self, name: str) -> Optional[T]:
+        """Look up an item by name (loading external plugins first), or None."""
+        self._ensure_entry_points()
+        with self._lock:
+            return self._items.get(name)
+
+    def names(self) -> List[str]:
+        """All registered names, built-in and plugin, sorted."""
+        self._ensure_entry_points()
+        with self._lock:
+            return sorted(self._items)
+
+    def _ensure_entry_points(self) -> None:
+        if self._entry_points_loaded:
+            return
+        with self._lock:
+            if self._entry_points_loaded:
+                return
+            self._entry_points_loaded = True
+            for ep in _iter_entry_points(self._group):
+                if ep.name in self._items:
+                    # A built-in already claims this name; a plugin must not
+                    # silently shadow it.
+                    logger.debug(
+                        f"{self.kind} plugin {ep.name!r} shadows a built-in; ignored"
+                    )
+                    continue
+                try:
+                    self._items[ep.name] = ep.load()
+                    logger.info(f"Loaded {self.kind} plugin: {ep.name}")
+                except Exception as e:
+                    # A broken third-party plugin must never break the build.
+                    logger.warning(
+                        f"Skipping unloadable {self.kind} plugin {ep.name!r}: {e}"
+                    )
+
+
+# One registry per extensible kind. The entry-point group is the third-party
+# contract; keep these strings stable.
+TOOLS: Registry = Registry("tool", "misterdev.tools")
+GATES: Registry = Registry("gate", "misterdev.gates")
+TARGETS: Registry = Registry("target", "misterdev.targets")

misterdev/task_executors/base_executor.py

@@ -0,0 +1,10 @@
+from abc import ABC, abstractmethod
+from misterdev.core.models import Task, ExecutionResult
+from misterdev.core.execution.project import Project
+
+
+class BaseTaskExecutor(ABC):
+    @abstractmethod
+    def execute(self, task: Task, project_context: Project) -> ExecutionResult:
+        """Executes a given task within the project context."""
+        pass

misterdev/task_executors/markdown_plan_executor/__init__.py

@@ -0,0 +1,90 @@
+"""Markdown plan executor - executes tasks via LLM with Try-Test-Fix loop.
+
+This package preserves the original ``markdown_plan_executor`` module's import
+path: the executor class and every module-level helper it historically exported
+are re-exported here unchanged. The implementation is split into cohesive
+mixins purely as code movement; behaviour is identical.
+"""
+
+from typing import Optional
+
+from misterdev.core.context.scratchpad import Scratchpad
+from misterdev.core.verification.validator import StallDetector
+from misterdev.task_executors.base_executor import BaseTaskExecutor
+
+from .helpers import (
+    logger,
+    _is_golden_path,
+    _LANG_MAP,
+    EDIT_FORMAT_INSTRUCTIONS,
+    FULL_FILE_FALLBACK_INSTRUCTIONS,
+    JUDGE_MIN_BUDGET_FRACTION,
+    _relevant_line_ranges,
+    _merge_ranges,
+    _window_lines,
+    _bisect_first_failing,
+    _is_truncated,
+    _detect_language,
+    _is_test_file,
+    _extract_acceptance_command,
+    _test_metrics,
+    _count_tautologies,
+    _diagnose_tampering,
+    _diagnose_py_tampering,
+)
+from .execute_mixin import ExecuteMixin
+from .git_mixin import GitMixin
+from .commands_mixin import CommandsMixin
+from .context_mixin import ContextMixin
+from .llm_mixin import LLMMixin
+from .gates_mixin import GatesMixin
+from .critic_spec_mixin import CriticSpecMixin
+from .edits_mixin import EditsMixin
+from .results_mixin import ResultsMixin
+
+# Re-exports preserving the original module's public surface (see module docstring).
+__all__ = [
+    "MarkdownPlanExecutor",
+    "logger",
+    "_is_golden_path",
+    "_LANG_MAP",
+    "EDIT_FORMAT_INSTRUCTIONS",
+    "FULL_FILE_FALLBACK_INSTRUCTIONS",
+    "JUDGE_MIN_BUDGET_FRACTION",
+    "_relevant_line_ranges",
+    "_merge_ranges",
+    "_window_lines",
+    "_bisect_first_failing",
+    "_is_truncated",
+    "_detect_language",
+    "_is_test_file",
+    "_extract_acceptance_command",
+    "_test_metrics",
+    "_count_tautologies",
+    "_diagnose_tampering",
+    "_diagnose_py_tampering",
+]
+
+
+class MarkdownPlanExecutor(
+    ExecuteMixin,
+    GitMixin,
+    CommandsMixin,
+    ContextMixin,
+    LLMMixin,
+    GatesMixin,
+    CriticSpecMixin,
+    EditsMixin,
+    ResultsMixin,
+    BaseTaskExecutor,
+):
+    """Executes tasks with a Try-Test-Fix loop.
+
+    Uses git branch-per-task for atomic execution: each task runs on a
+    temporary branch. Success merges to the current branch. Failure
+    deletes the branch, leaving the repo clean.
+    """
+
+    def __init__(self, scratchpad: Optional[Scratchpad] = None):
+        self.scratchpad = scratchpad or Scratchpad()
+        self.stall_detector = StallDetector()

misterdev/task_executors/markdown_plan_executor/commands_mixin.py

@@ -0,0 +1,82 @@
+"""Command execution and file snapshot operations."""
+
+from typing import Dict, List, Optional
+
+from misterdev.core.models import Task
+from misterdev.core.execution.project import Project
+from misterdev.core.verification.validator import _run_cmd
+from misterdev.utils.file_utils import write_file
+
+from .helpers import logger
+
+
+class CommandsMixin:
+    # ----------------------------------------------------------------
+    # Command execution and file operations
+    # ----------------------------------------------------------------
+
+    def _run_command(
+        self, project: Project, command: str, timeout: int = 120, cwd=None
+    ) -> tuple:
+        # cwd lets a routed multi-target task run its gate in the TARGET's
+        # directory (e.g. `npm run typecheck` under clients/web), not the repo
+        # root where that command would not resolve. Defaults to project.path.
+        run_dir = cwd or project.path
+        logger.info(f"Running: {command} (cwd={run_dir}, timeout={timeout}s)")
+        activation = (
+            project.env_manager.activate_command() if project.env_manager else None
+        )
+        # Governance gate + audit trail (both no-ops when off: governance_policy
+        # is None unless orchestrator.governance is set; audit only appends).
+        # getattr-guarded so a lightweight project stub without these subsystems
+        # still executes commands unchanged.
+        return _run_cmd(
+            command,
+            run_dir,
+            activation,
+            timeout,
+            policy=getattr(project, "governance_policy", None),
+            audit=getattr(project, "audit_trail", None),
+        )
+
+    def _snapshot_files(
+        self, project: Project, files: List[str]
+    ) -> Dict[str, Optional[str]]:
+        snapshot = {}
+        for file_path in files:
+            full_path = project.path / file_path
+            if full_path.exists():
+                try:
+                    snapshot[file_path] = full_path.read_text(encoding="utf-8")
+                except (UnicodeDecodeError, OSError):
+                    snapshot[file_path] = None
+            else:
+                snapshot[file_path] = None
+        return snapshot
+
+    def _revert_files(
+        self, project: Project, snapshot: Dict[str, Optional[str]]
+    ) -> None:
+        for file_path, content in snapshot.items():
+            full_path = project.path / file_path
+            if content is None:
+                if full_path.exists():
+                    full_path.unlink()
+            else:
+                write_file(full_path, content)
+
+    def _record_success(self, task: Task, files: List[str]) -> None:
+        self.scratchpad.record(
+            category="pattern",
+            discovery=f"Task {task.id} completed successfully",
+            task_id=task.id,
+            files=files,
+            tags=[task.category],
+        )
+
+    def _get_processor_config(self, project: Project) -> dict:
+        processors = project.config.get("task_processors", [])
+        for p in processors:
+            if p.get("type") == "markdown_planner":
+                return p.get("settings", {})
+        return {}