devtools-inspector-mcp 0.1.0__py3-none-any.whl

devtools_inspector/fixing.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from uuid import uuid4
+
+from .redaction import redact_text
+
+
+_ALLOWED_SUFFIXES = {".py", ".js", ".jsx", ".ts", ".tsx", ".html", ".css"}
+_BLOCKED_PARTS = {".git", ".venv", "venv", "node_modules", "site-packages", "dist", "build"}
+
+
+class PatchError(ValueError):
+    """A patch could not be safely prepared, applied, or rolled back."""
+
+
+@dataclass
+class ProposedPatch:
+    patch_id: str
+    path: Path
+    expected_sha256: str
+    old_text: str
+    new_text: str
+    rationale: str
+
+
+class PatchManager:
+    def __init__(self, project_root: Path):
+        self.root = project_root.resolve()
+        self._proposals: dict[str, ProposedPatch] = {}
+        self._backup_root = self.root / ".devtools_mcp" / "rollback"
+
+    def _ensure_state_dir(self) -> None:
+        state_dir = self.root / ".devtools_mcp"
+        try:
+            state_dir.mkdir(exist_ok=True)
+            if state_dir.is_symlink():
+                raise PatchError("The patch state directory cannot be a symbolic link.")
+            state_dir.resolve().relative_to(self.root)
+            self._backup_root.mkdir(exist_ok=True)
+            if self._backup_root.is_symlink():
+                raise PatchError("The rollback directory cannot be a symbolic link.")
+            self._backup_root.resolve().relative_to(self.root)
+        except ValueError:
+            raise PatchError("The patch state directory must remain inside the project root.") from None
+        except OSError as error:
+            raise PatchError(f"Could not prepare patch state: {error}") from error
+
+    def _record(self, action: str, details: dict[str, str]) -> None:
+        self._ensure_state_dir()
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "action": action,
+            **details,
+        }
+        with (self.root / ".devtools_mcp" / "history.jsonl").open("a", encoding="utf-8") as history:
+            history.write(json.dumps(record, ensure_ascii=True) + "\n")
+
+    def _resolve_source(self, relative_path: str) -> Path:
+        candidate = Path(relative_path)
+        if candidate.is_absolute() or not relative_path or ".." in candidate.parts:
+            raise PatchError("Use a project-relative source path without '..'.")
+        if candidate.suffix.lower() not in _ALLOWED_SUFFIXES or any(part.lower() in _BLOCKED_PARTS for part in candidate.parts):
+            raise PatchError("This path is not an allowed source file; dependency, build, and environment paths are blocked.")
+        path = (self.root / candidate).resolve()
+        try:
+            path.relative_to(self.root)
+        except ValueError:
+            raise PatchError("The source path resolves outside the configured project root.") from None
+        if path.is_symlink() or not path.is_file():
+            raise PatchError("The selected path must be an existing regular source file.")
+        if path.stat().st_size > 250_000:
+            raise PatchError("Files larger than 250 KB are not eligible for patching.")
+        return path
+
+    def propose(
+        self,
+        relative_path: str,
+        expected_sha256: str,
+        old_text: str,
+        new_text: str,
+        rationale: str,
+    ) -> dict[str, str]:
+        path = self._resolve_source(relative_path)
+        original_bytes = path.read_bytes()
+        content = original_bytes.decode("utf-8")
+        actual_hash = hashlib.sha256(original_bytes).hexdigest()
+        if actual_hash != expected_sha256:
+            raise PatchError("The file changed since it was inspected. Read it again and propose against its current SHA-256.")
+        if not old_text or len(old_text) > 20_000 or len(new_text) > 20_000:
+            raise PatchError("Provide a non-empty old snippet and snippets no larger than 20 KB.")
+        if content.count(old_text) != 1:
+            raise PatchError("The old snippet must match exactly once; no file changes were made.")
+        patch_id = uuid4().hex[:16]
+        self._proposals[patch_id] = ProposedPatch(
+            patch_id=patch_id,
+            path=path,
+            expected_sha256=actual_hash,
+            old_text=old_text,
+            new_text=new_text,
+            rationale=redact_text(rationale, 500),
+        )
+        self._record(
+            "proposed",
+            {"patch_id": patch_id, "path": path.relative_to(self.root).as_posix(), "sha256": actual_hash},
+        )
+        return {"patch_id": patch_id, "path": path.relative_to(self.root).as_posix(), "rationale": redact_text(rationale, 500), "approval_required": True}
+
+    def apply(self, patch_id: str, approved: bool) -> dict[str, str | bool]:
+        if not approved:
+            raise PatchError("Patch not applied. Set approved=true only after reviewing the proposed change.")
+        proposal = self._proposals.get(patch_id)
+        if proposal is None:
+            raise PatchError("Proposal not found or expired with this server session; create it again.")
+        current_bytes = proposal.path.read_bytes()
+        current = current_bytes.decode("utf-8")
+        if hashlib.sha256(current_bytes).hexdigest() != proposal.expected_sha256:
+            raise PatchError("The file changed after the proposal. Patch refused; inspect and propose again.")
+        if current.count(proposal.old_text) != 1:
+            raise PatchError("The patch anchor is no longer unique. No file changes were made.")
+        updated = current.replace(proposal.old_text, proposal.new_text, 1)
+        updated_bytes = updated.encode("utf-8")
+        applied_hash = hashlib.sha256(updated_bytes).hexdigest()
+        self._ensure_state_dir()
+        backup = {
+            "patch_id": patch_id,
+            "path": proposal.path.relative_to(self.root).as_posix(),
+            "original": current,
+            "original_sha256": proposal.expected_sha256,
+            "applied_sha256": applied_hash,
+            "rationale": proposal.rationale,
+        }
+        self._atomic_write(self._backup_root / f"{patch_id}.json", json.dumps(backup, ensure_ascii=True))
+        self._atomic_write(proposal.path, updated_bytes)
+        self._proposals.pop(patch_id, None)
+        self._record(
+            "applied",
+            {"patch_id": patch_id, "path": proposal.path.relative_to(self.root).as_posix(), "sha256": applied_hash},
+        )
+        return {
+            "patch_id": patch_id,
+            "applied": True,
+            "path": proposal.path.relative_to(self.root).as_posix(),
+            "applied_sha256": applied_hash,
+            "verification": "unverified",
+        }
+
+    def rollback(self, patch_id: str) -> dict[str, str | bool]:
+        backup_path = self._backup_root / f"{patch_id}.json"
+        if not backup_path.is_file():
+            raise PatchError("No recovery point exists for this patch ID.")
+        backup = json.loads(backup_path.read_text(encoding="utf-8"))
+        path = self._resolve_source(backup["path"])
+        current_bytes = path.read_bytes()
+        current_hash = hashlib.sha256(current_bytes).hexdigest()
+        if current_hash != backup["applied_sha256"]:
+            raise PatchError("The file has changed since the patch was applied. Rollback refused to preserve newer edits.")
+        self._atomic_write(path, backup["original"].encode("utf-8"))
+        backup_path.unlink()
+        self._record("rolled_back", {"patch_id": patch_id, "path": backup["path"]})
+        return {"patch_id": patch_id, "rolled_back": True, "path": backup["path"]}
+
+    async def run_project_checks(self, patch_id: str | None = None, timeout: float = 120) -> dict[str, object]:
+        """Run project tests and roll back the linked patch if checks fail.
+
+        Supports common project types:
+        - Python: pytest
+        - JavaScript/TypeScript: npm test, pnpm test, yarn test
+        - Other ecosystems only when safely supported.
+
+        Detects project type from actual project files.
+        Does not install dependencies automatically.
+        Uses an explicit command allowlist and timeout.
+        Captures stdout, stderr, exit code and test summary.
+        Never claims tests passed if they were not executed.
+        """
+        # Determine project type from project files
+        project_type = self._detect_project_type()
+
+        # Build the appropriate test command based on project type
+        command, command_name = self._build_test_command(project_type)
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *command,
+                cwd=self.root,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+            )
+            try:
+                output, _ = await asyncio.wait_for(process.communicate(), timeout=timeout)
+                exit_code = process.returncode
+            except TimeoutError:
+                process.kill()
+                await process.wait()
+                output = b"pytest/verification exceeded the verification limit."
+                exit_code = -1
+            executed = True
+        except OSError as error:
+            output = str(error).encode("utf-8", errors="replace")
+            exit_code = -1
+            executed = False
+
+        result: dict[str, object] = {
+            "command": command_name,
+            "executed": executed,
+            "passed": executed and exit_code == 0,
+            "exit_code": exit_code,
+            "output": redact_text(output.decode("utf-8", errors="replace")[-10_000:], 10_000),
+            "project_type": project_type,
+        }
+
+        self._record(
+            "checks",
+            {
+                "patch_id": patch_id or "",
+                "passed": str(result["passed"]),
+                "exit_code": str(exit_code),
+                "project_type": project_type,
+            },
+        )
+        if patch_id and not result["passed"]:
+            try:
+                result["rollback"] = self.rollback(patch_id)
+            except PatchError as error:
+                result["rollback"] = {"rolled_back": False, "error": str(error)}
+        return result
+
+    def _detect_project_type(self) -> str:
+        """Detect the project type from actual project files.
+
+        Returns one of: 'python', 'javascript', 'typescript', 'unknown'
+        """
+        # Check for Python project files
+        python_files = [
+            "pyproject.toml",
+            "setup.py",
+            "setup.cfg",
+            "requirements.txt",
+            "conftest.py",
+        ]
+        for fname in python_files:
+            if (self.root / fname).is_file():
+                return "python"
+
+        # Check for Node.js project files
+        node_files = ["package.json"]
+        for fname in node_files:
+            if (self.root / fname).is_file():
+                # Try to read just the scripts section to determine test command
+                try:
+                    content = (self.root / fname).read_text(encoding="utf-8", errors="replace")
+                    if '"test"' in content or "'test'" in content:
+                        return "javascript"
+                except Exception:
+                    return "javascript"  # Assume JavaScript project if package.json exists
+
+        # Check for TypeScript project files
+        ts_files = ["tsconfig.json"]
+        for fname in ts_files:
+            if (self.root / fname).is_file():
+                return "typescript"
+
+        return "unknown"
+
+    def _build_test_command(self, project_type: str) -> tuple[list[str], str]:
+        """Build the appropriate test command based on project type.
+
+        Returns (command_list, command_name_string) tuple.
+        Uses an explicit command allowlist - no arbitrary commands from project config.
+        """
+        if project_type == "python":
+            return ["python", "-m", "pytest", "-q"], "python -m pytest -q"
+        if project_type == "javascript":
+            # Check for npm, pnpm, or yarn
+            package_json = (self.root / "package.json").read_text(encoding="utf-8", errors="replace")
+            if '"pnpm"' in package_json or "'pnpm'" in package_json:
+                return ["pnpm", "test"], "pnpm test"
+            if '"yarn"' in package_json or "'yarn'" in package_json:
+                return ["yarn", "test"], "yarn test"
+            return ["npm", "test"], "npm test"
+        if project_type == "typescript":
+            return ["npm", "test"], "npm test"
+        
+        # unknown or unsupported - try pytest as fallback if in a Python-like structure
+        return ["python", "-m", "pytest", "-q"], "python -m pytest -q (fallback)"
+
+    @staticmethod
+    def _atomic_write(path: Path, content: str | bytes) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        mode = path.stat().st_mode if path.exists() else None
+        if isinstance(content, bytes):
+            with NamedTemporaryFile("wb", dir=path.parent, delete=False) as temporary:
+                temporary.write(content)
+                temporary_path = Path(temporary.name)
+        else:
+            with NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as temporary:
+                temporary.write(content)
+                temporary_path = Path(temporary.name)
+        if mode is not None:
+            os.chmod(temporary_path, mode)
+        os.replace(temporary_path, path)

devtools_inspector/models.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from hashlib import sha256
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+Category = Literal["console", "runtime", "network", "performance", "security", "accessibility"]
+Severity = Literal["error", "warning", "info"]
+Confidence = Literal["confirmed", "correlated", "potential", "suspicion"]
+Verification = Literal["unverified", "passed", "failed", "not_applicable"]
+
+
+class SourceLocation(BaseModel):
+    url: str
+    line: int | None = None
+    column: int | None = None
+    function: str | None = None
+
+
+class Issue(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    issue_id: str
+    category: Category
+    severity: Severity
+    confidence: Confidence
+    title: str
+    explanation: str
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    url: str | None = None
+    target_id: str | None = None
+    source_location: SourceLocation | None = None
+    evidence: dict[str, Any] = Field(default_factory=dict)
+    verification: Verification = "unverified"
+
+
+def build_issue(
+    *,
+    category: Category,
+    severity: Severity,
+    confidence: Confidence,
+    title: str,
+    explanation: str,
+    url: str | None = None,
+    target_id: str | None = None,
+    source_location: SourceLocation | None = None,
+    evidence: dict[str, Any] | None = None,
+) -> Issue:
+    dedupe_key = "\0".join((category, title, url or "", target_id or ""))
+    issue_id = sha256(dedupe_key.encode("utf-8", errors="replace")).hexdigest()[:16]
+    return Issue(
+        issue_id=issue_id,
+        category=category,
+        severity=severity,
+        confidence=confidence,
+        title=title[:240],
+        explanation=explanation[:2000],
+        url=url,
+        target_id=target_id,
+        source_location=source_location,
+        evidence=evidence or {},
+    )

devtools_inspector/redaction.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import re
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+
+_SECRET_KEY = re.compile(r"token|secret|password|passwd|authorization|api[-_]?key|cookie", re.I)
+_BEARER = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/-]+=*")
+_ASSIGNMENT = re.compile(
+    r"(?i)\b(api[-_]?key|access[-_]?token|refresh[-_]?token|token|password|secret|authorization)"
+    r"\s*[:=]\s*(['\"]?)[^\s,;'\"]+"
+)
+
+
+def redact_text(value: str, limit: int = 1000) -> str:
+    value = _BEARER.sub("Bearer [REDACTED]", value)
+    value = _ASSIGNMENT.sub(lambda match: f"{match.group(1)}=[REDACTED]", value)
+    return value[:limit]
+
+
+def redact_url(value: str) -> str:
+    try:
+        parts = urlsplit(value)
+        if not parts.scheme or not parts.netloc:
+            return redact_text(value, 2000)
+        host = parts.hostname or ""
+        if ":" in host and not host.startswith("["):
+            host = f"[{host}]"
+        if parts.port:
+            host = f"{host}:{parts.port}"
+        query = urlencode(
+            [(key, "[REDACTED]" if _SECRET_KEY.search(key) else item) for key, item in parse_qsl(parts.query, keep_blank_values=True)]
+        )
+        fragment = parts.fragment
+        if "=" in fragment:
+            fragment = urlencode(
+                [(key, "[REDACTED]" if _SECRET_KEY.search(key) else item) for key, item in parse_qsl(fragment, keep_blank_values=True)]
+            )
+        else:
+            fragment = redact_text(fragment, 500)
+        return urlunsplit((parts.scheme, host, parts.path, query, fragment))[:2000]
+    except ValueError:
+        return redact_text(value, 2000)

devtools_inspector/server.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+from fastmcp import FastMCP
+
+from .cdp import BrowserConnectionError, BrowserSession
+from .fixing import PatchError, PatchManager
+
+
+mcp = FastMCP(
+    "Live DevTools Inspector",
+    instructions="Inspect an explicitly selected local Chrome tab. Browser debugging grants powerful access; keep its endpoint local and protected.",
+)
+browser = BrowserSession()
+project_root = Path(os.environ.get("DEVTOOLS_PROJECT_ROOT", Path.cwd())).resolve()
+patches = PatchManager(project_root)
+
+
+@mcp.tool
+async def list_browser_targets(endpoint: str = "http://127.0.0.1:9222") -> list[dict[str, str]]:
+    """List page targets from a local Chrome debugging endpoint."""
+    return await browser.list_targets(endpoint)
+
+
+@mcp.tool
+async def connect_browser(endpoint: str, target_id: str) -> dict[str, object]:
+    """Connect to the explicitly selected page target and begin Console/Network monitoring."""
+    return await browser.connect(endpoint, target_id)
+
+
+@mcp.tool
+async def select_browser_target(endpoint: str, target_id: str) -> dict[str, object]:
+    """Switch the active CDP session to a selected page target."""
+    return await browser.connect(endpoint, target_id)
+
+
+@mcp.tool
+async def disconnect_browser() -> dict[str, object]:
+    """Close the active page connection and remove event handlers."""
+    return await browser.disconnect()
+
+
+@mcp.tool
+def get_connection_status() -> dict[str, object]:
+    """Report browser connection and monitoring state."""
+    return browser.status()
+
+
+@mcp.tool
+def start_live_inspection() -> dict[str, object]:
+    """Resume bounded event-driven Console and Network collection."""
+    if browser.collector is None:
+        raise BrowserConnectionError("Connect to a selected page target first.")
+    browser.collector.monitoring = True
+    return {"monitoring": True, "target": browser.target}
+
+
+@mcp.tool
+def stop_live_inspection() -> dict[str, object]:
+    """Pause diagnostic collection without disconnecting the browser."""
+    if browser.collector is None:
+        raise BrowserConnectionError("Connect to a selected page target first.")
+    browser.collector.monitoring = False
+    return {"monitoring": False, "target": browser.target}
+
+
+@mcp.tool
+def get_live_diagnostics(category: Literal["console", "runtime", "network", "performance", "security", "accessibility"] | None = None) -> list[dict[str, object]]:
+    """Return normalized, deduplicated diagnostics collected for the active page."""
+    return [issue.model_dump(mode="json") for issue in browser.diagnostics(category)]
+
+
+@mcp.tool
+def inspect_console() -> list[dict[str, object]]:
+    """Return captured console warnings, errors, and runtime exceptions."""
+    return [issue.model_dump(mode="json") for issue in browser.diagnostics() if issue.category in ("console", "runtime")]
+
+
+@mcp.tool
+def inspect_network() -> list[dict[str, object]]:
+    """Return captured HTTP errors and failed or aborted requests."""
+    return [issue.model_dump(mode="json") for issue in browser.diagnostics("network")]
+
+
+@mcp.tool
+async def inspect_performance() -> list[dict[str, object]]:
+    """Return observed long tasks, using explicitly labeled CDP tracing only when needed."""
+    return [issue.model_dump(mode="json") for issue in await browser.performance_diagnostics()]
+
+
+@mcp.tool
+def propose_fix(relative_path: str, expected_sha256: str, old_text: str, new_text: str, rationale: str) -> dict[str, str | bool]:
+    """Prepare a minimal exact-snippet patch without changing files."""
+    return patches.propose(relative_path, expected_sha256, old_text, new_text, rationale)
+
+
+@mcp.tool
+def apply_patch(patch_id: str, approved: bool) -> dict[str, str | bool]:
+    """Apply a reviewed patch only after explicit approval and save a recovery point."""
+    return patches.apply(patch_id, approved)
+
+
+@mcp.tool
+async def run_project_checks(patch_id: str | None = None) -> dict[str, object]:
+    """Run the fixed pytest command; roll back the linked patch if checks fail."""
+    return await patches.run_project_checks(patch_id)
+
+
+@mcp.tool
+def rollback_patch(patch_id: str) -> dict[str, str | bool]:
+    """Restore a patch recovery point if the file has not changed since application."""
+    return patches.rollback(patch_id)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()