@trac3er/oh-my-god 1.0.2

package/tools/browser_tool.py

@@ -0,0 +1,448 @@
+#!/usr/bin/env python3
+"""
+Puppeteer Browser Integration for OMG
+
+Wrapper around Puppeteer MCP tools that generates tool call specifications
+for browser automation. Functions produce spec dicts — actual execution is
+done by Claude Code when it dispatches the MCP call.
+
+Feature flag: OMG_BROWSER_ENABLED (default: False)
+"""
+
+import json
+import os
+import sys
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# --- Lazy imports for hooks/_common.py ---
+
+_get_feature_flag = None
+
+
+def _ensure_imports():
+    """Lazy import feature flag from hooks/_common.py."""
+    global _get_feature_flag
+    if _get_feature_flag is not None:
+        return
+    repo_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    if repo_root not in sys.path:
+        sys.path.insert(0, repo_root)
+    try:
+        from hooks._common import get_feature_flag as _gff
+        _get_feature_flag = _gff
+    except ImportError:
+        pass
+
+
+# --- Feature flag ---
+
+def _is_enabled() -> bool:
+    """Check if Browser feature is enabled."""
+    # Fast path: check env var directly
+    env_val = os.environ.get("OMG_BROWSER_ENABLED", "").lower()
+    if env_val in ("0", "false", "no"):
+        return False
+    if env_val in ("1", "true", "yes"):
+        return True
+    # Fallback to hooks/_common.get_feature_flag
+    _ensure_imports()
+    if _get_feature_flag is not None:
+        return _get_feature_flag("BROWSER", default=False)
+    return False
+
+
+# --- Response helpers ---
+
+def _success_response(result: Any) -> Dict[str, Any]:
+    """Create a success response dict."""
+    return {"success": True, "result": result, "error": None}
+
+
+def _error_response(error: str) -> Dict[str, Any]:
+    """Create an error response dict."""
+    return {"success": False, "result": None, "error": error}
+
+
+def _disabled_response() -> Dict[str, Any]:
+    """Create a response for when the feature flag is disabled."""
+    return _error_response("Browser feature is disabled (OMG_BROWSER_ENABLED=false)")
+
+
+# =============================================================================
+# BrowserSession — session state tracking
+# =============================================================================
+
+
+@dataclass
+class BrowserSession:
+    """Manages browser session state.
+
+    Tracks the current URL, navigation history, and screenshot names
+    for the duration of a browser automation session.
+
+    Attributes:
+        session_id: Unique identifier for this session.
+        current_url: The URL the browser is currently on (empty if none).
+        history: List of URLs visited during this session.
+        screenshots: List of screenshot names taken during this session.
+    """
+
+    session_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    current_url: str = ""
+    history: List[str] = field(default_factory=list)
+    screenshots: List[str] = field(default_factory=list)
+
+    def navigate_to(self, url: str) -> None:
+        """Record a navigation to a URL."""
+        self.current_url = url
+        self.history.append(url)
+
+    def record_screenshot(self, name: str) -> None:
+        """Record a screenshot taken."""
+        self.screenshots.append(name)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert session state to a plain dictionary."""
+        return asdict(self)
+
+    def reset(self) -> None:
+        """Reset session state while keeping the same session_id."""
+        self.current_url = ""
+        self.history.clear()
+        self.screenshots.clear()
+
+
+# Module-level session instance
+session = BrowserSession()
+
+
+# =============================================================================
+# Browser Operations — tool call spec generators
+# =============================================================================
+
+
+def browser_navigate(url: str, timeout: int = 30) -> Dict[str, Any]:
+    """Navigate the browser to a URL.
+
+    Generates a Puppeteer MCP tool call spec for navigation.
+
+    Args:
+        url: The URL to navigate to.
+        timeout: Navigation timeout in seconds (default: 30).
+
+    Returns:
+        A dict with ``success``, ``result`` (the tool call spec), and ``error``.
+        If the feature flag is disabled, returns an error response.
+    """
+    if not _is_enabled():
+        return _disabled_response()
+
+    try:
+        if not url or not isinstance(url, str):
+            return _error_response("URL must be a non-empty string")
+
+        # Validate URL has a scheme
+        if not url.startswith(("http://", "https://")):
+            url = f"https://{url}"
+
+        spec = {
+            "tool": "mcp_puppeteer_puppeteer_navigate",
+            "parameters": {
+                "url": url,
+            },
+        }
+
+        # Track session state
+        session.navigate_to(url)
+
+        return _success_response(spec)
+
+    except Exception as e:
+        return _error_response(str(e))
+
+
+def browser_click(selector: str) -> Dict[str, Any]:
+    """Click an element on the page.
+
+    Generates a Puppeteer MCP tool call spec for clicking.
+
+    Args:
+        selector: CSS selector for the element to click.
+
+    Returns:
+        A dict with ``success``, ``result`` (the tool call spec), and ``error``.
+    """
+    if not _is_enabled():
+        return _disabled_response()
+
+    try:
+        if not selector or not isinstance(selector, str):
+            return _error_response("Selector must be a non-empty string")
+
+        spec = {
+            "tool": "mcp_puppeteer_puppeteer_click",
+            "parameters": {
+                "selector": selector,
+            },
+        }
+
+        return _success_response(spec)
+
+    except Exception as e:
+        return _error_response(str(e))
+
+
+def browser_type(selector: str, text: str) -> Dict[str, Any]:
+    """Type text into an input element.
+
+    Generates a Puppeteer MCP tool call spec for filling an input field.
+
+    Args:
+        selector: CSS selector for the input field.
+        text: The text to type into the field.
+
+    Returns:
+        A dict with ``success``, ``result`` (the tool call spec), and ``error``.
+    """
+    if not _is_enabled():
+        return _disabled_response()
+
+    try:
+        if not selector or not isinstance(selector, str):
+            return _error_response("Selector must be a non-empty string")
+        if not isinstance(text, str):
+            return _error_response("Text must be a string")
+
+        spec = {
+            "tool": "mcp_puppeteer_puppeteer_fill",
+            "parameters": {
+                "selector": selector,
+                "value": text,
+            },
+        }
+
+        return _success_response(spec)
+
+    except Exception as e:
+        return _error_response(str(e))
+
+
+def browser_screenshot(name: str, selector: Optional[str] = None) -> Dict[str, Any]:
+    """Take a screenshot of the page or a specific element.
+
+    Generates a Puppeteer MCP tool call spec for taking a screenshot.
+
+    Args:
+        name: Name for the screenshot.
+        selector: Optional CSS selector for a specific element to capture.
+
+    Returns:
+        A dict with ``success``, ``result`` (the tool call spec), and ``error``.
+    """
+    if not _is_enabled():
+        return _disabled_response()
+
+    try:
+        if not name or not isinstance(name, str):
+            return _error_response("Name must be a non-empty string")
+
+        params: Dict[str, Any] = {"name": name}
+        if selector:
+            params["selector"] = selector
+
+        spec = {
+            "tool": "mcp_puppeteer_puppeteer_screenshot",
+            "parameters": params,
+        }
+
+        # Track screenshot
+        session.record_screenshot(name)
+
+        return _success_response(spec)
+
+    except Exception as e:
+        return _error_response(str(e))
+
+
+def browser_evaluate(script: str) -> Dict[str, Any]:
+    """Execute JavaScript in the browser console.
+
+    Generates a Puppeteer MCP tool call spec for evaluating JavaScript.
+
+    Args:
+        script: JavaScript code to execute.
+
+    Returns:
+        A dict with ``success``, ``result`` (the tool call spec), and ``error``.
+    """
+    if not _is_enabled():
+        return _disabled_response()
+
+    try:
+        if not script or not isinstance(script, str):
+            return _error_response("Script must be a non-empty string")
+
+        spec = {
+            "tool": "mcp_puppeteer_puppeteer_evaluate",
+            "parameters": {
+                "script": script,
+            },
+        }
+
+        return _success_response(spec)
+
+    except Exception as e:
+        return _error_response(str(e))
+
+
+# =============================================================================
+# CLI Interface
+# =============================================================================
+
+
+def _cli_main():
+    """CLI entry point for browser_tool.py."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="OMG Browser Tool — Puppeteer MCP wrapper for browser automation",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--navigate", dest="navigate_url", help="Navigate to URL")
+    parser.add_argument("--click", dest="click_selector", help="Click CSS selector")
+    parser.add_argument(
+        "--type", dest="type_args", nargs=2, metavar=("SELECTOR", "TEXT"),
+        help="Type text into selector",
+    )
+    parser.add_argument(
+        "--screenshot", dest="screenshot_name", help="Take screenshot with name",
+    )
+    parser.add_argument(
+        "--screenshot-selector", dest="screenshot_selector", default=None,
+        help="Optional CSS selector for screenshot (use with --screenshot)",
+    )
+    parser.add_argument("--evaluate", dest="eval_script", help="Evaluate JavaScript")
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Print the tool call spec without executing",
+    )
+    parser.add_argument(
+        "--session-info", action="store_true",
+        help="Show current session state",
+    )
+
+    args = parser.parse_args()
+
+    enabled = _is_enabled()
+
+    # Session info
+    if args.session_info:
+        print(json.dumps({
+            "session": session.to_dict(),
+            "enabled": enabled,
+        }, indent=2))
+        return
+
+    # Dry-run navigate
+    if args.dry_run and args.navigate_url:
+        result = browser_navigate(args.navigate_url)
+        print(json.dumps({
+            "dry_run": True,
+            "operation": "navigate",
+            "url": args.navigate_url,
+            "enabled": enabled,
+            "spec": result,
+        }, indent=2))
+        return
+
+    # Dry-run click
+    if args.dry_run and args.click_selector:
+        result = browser_click(args.click_selector)
+        print(json.dumps({
+            "dry_run": True,
+            "operation": "click",
+            "selector": args.click_selector,
+            "enabled": enabled,
+            "spec": result,
+        }, indent=2))
+        return
+
+    # Dry-run type
+    if args.dry_run and args.type_args:
+        result = browser_type(args.type_args[0], args.type_args[1])
+        print(json.dumps({
+            "dry_run": True,
+            "operation": "type",
+            "selector": args.type_args[0],
+            "text": args.type_args[1],
+            "enabled": enabled,
+            "spec": result,
+        }, indent=2))
+        return
+
+    # Dry-run screenshot
+    if args.dry_run and args.screenshot_name:
+        result = browser_screenshot(args.screenshot_name, args.screenshot_selector)
+        print(json.dumps({
+            "dry_run": True,
+            "operation": "screenshot",
+            "name": args.screenshot_name,
+            "selector": args.screenshot_selector,
+            "enabled": enabled,
+            "spec": result,
+        }, indent=2))
+        return
+
+    # Dry-run evaluate
+    if args.dry_run and args.eval_script:
+        result = browser_evaluate(args.eval_script)
+        print(json.dumps({
+            "dry_run": True,
+            "operation": "evaluate",
+            "script": args.eval_script,
+            "enabled": enabled,
+            "spec": result,
+        }, indent=2))
+        return
+
+    # Non-dry-run: check feature flag
+    if not enabled:
+        print(json.dumps({
+            "error": "Browser feature is disabled (OMG_BROWSER_ENABLED=false)",
+        }))
+        sys.exit(1)
+
+    # Execute operations
+    if args.navigate_url:
+        result = browser_navigate(args.navigate_url)
+        print(json.dumps(result, indent=2))
+        return
+
+    if args.click_selector:
+        result = browser_click(args.click_selector)
+        print(json.dumps(result, indent=2))
+        return
+
+    if args.type_args:
+        result = browser_type(args.type_args[0], args.type_args[1])
+        print(json.dumps(result, indent=2))
+        return
+
+    if args.screenshot_name:
+        result = browser_screenshot(args.screenshot_name, args.screenshot_selector)
+        print(json.dumps(result, indent=2))
+        return
+
+    if args.eval_script:
+        result = browser_evaluate(args.eval_script)
+        print(json.dumps(result, indent=2))
+        return
+
+    parser.print_help()
+
+
+if __name__ == "__main__":
+    _cli_main()

package/tools/changelog_generator.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+Changelog Generator for OMG
+
+Parses conventional commits from git log and generates/updates CHANGELOG.md
+in Keep-a-Changelog format.
+
+Feature flag: OMG_CHANGELOG_ENABLED (default: False)
+"""
+
+import os
+import re
+import sys
+from datetime import date
+from typing import Any, Dict, List, Optional
+
+# Lazy imports
+_git_inspector = None
+_get_feature_flag = None
+
+
+def _ensure_imports():
+    """Lazy import git_inspector and feature flag helper."""
+    global _git_inspector, _get_feature_flag
+    if _git_inspector is None:
+        sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+        from tools import git_inspector as _gi
+        from hooks._common import get_feature_flag as _gff
+        _git_inspector = _gi
+        _get_feature_flag = _gff
+
+
+def _is_enabled() -> bool:
+    """Check if changelog feature is enabled."""
+    _ensure_imports()
+    return _get_feature_flag("changelog", default=False)
+
+
+# Supported conventional commit types
+CONVENTIONAL_TYPES = frozenset({
+    "feat", "fix", "docs", "style", "refactor",
+    "test", "chore", "perf", "ci", "build", "sec",
+})
+
+# Regex for conventional commit: type(scope): description  OR  type: description
+_CONVENTIONAL_RE = re.compile(
+    r"^(?P<type>[a-z]+)(?:\((?P<scope>[^)]+)\))?!?:\s*(?P<description>.+)$"
+)
+
+# Changelog section groupings
+_TYPE_TO_SECTION = {
+    "feat": "Added",
+    "fix": "Fixed",
+    "refactor": "Changed",
+    "perf": "Changed",
+    "docs": "Changed",
+    "style": "Changed",
+    "build": "Changed",
+    "ci": "Changed",
+    "chore": "Other",
+    "test": "Other",
+    "sec": "Security",
+}
+
+_SECTION_ORDER = ["Added", "Fixed", "Changed", "Deprecated", "Removed", "Security", "Other"]
+
+
+def parse_commit_log(cwd: str = ".") -> List[Dict[str, Any]]:
+    """Parse git log for conventional commits.
+
+    Args:
+        cwd: Working directory (default: current directory)
+
+    Returns:
+        List of dicts with keys: type, scope, description, hash, author, date, breaking
+        Returns empty list if OMG_CHANGELOG_ENABLED is False or no conventional commits found.
+    """
+    if not _is_enabled():
+        return []
+
+    _ensure_imports()
+    raw_commits = _git_inspector.git_log(cwd, n=100)
+
+    if not raw_commits:
+        return []
+
+    parsed = []
+    for commit in raw_commits:
+        subject = commit.get("subject", "").strip()
+        if not subject:
+            continue
+
+        match = _CONVENTIONAL_RE.match(subject)
+        if not match:
+            continue
+
+        commit_type = match.group("type").lower()
+        if commit_type not in CONVENTIONAL_TYPES:
+            continue
+
+        # Detect breaking changes
+        breaking = "BREAKING CHANGE" in subject or "!" in subject.split(":")[0]
+
+        parsed.append({
+            "type": commit_type,
+            "scope": match.group("scope") or "",
+            "description": match.group("description").strip(),
+            "hash": commit.get("hash", "")[:7],
+            "author": commit.get("author", ""),
+            "date": commit.get("date", ""),
+            "breaking": breaking,
+        })
+
+    return parsed
+
+
+def generate_changelog_entry(
+    commits: List[Dict[str, Any]],
+    version: str = "Unreleased",
+) -> str:
+    """Format a Keep-a-Changelog section from parsed commits.
+
+    Args:
+        commits: List of parsed commit dicts from parse_commit_log()
+        version: Version label (default: "Unreleased")
+
+    Returns:
+        Formatted changelog section string.
+        Returns empty string if commits list is empty.
+    """
+    if not commits:
+        return ""
+
+    today = date.today().isoformat()
+    header = f"## [{version}] - {today}"
+
+    # Group commits by section
+    sections: Dict[str, List[str]] = {s: [] for s in _SECTION_ORDER}
+
+    for commit in commits:
+        section = _TYPE_TO_SECTION.get(commit["type"], "Other")
+        scope = commit.get("scope", "")
+        description = commit["description"]
+        short_hash = commit.get("hash", "")
+
+        if scope:
+            entry = f"- **{scope}**: {description}"
+        else:
+            entry = f"- {description}"
+
+        if short_hash:
+            entry += f" (#{short_hash})"
+
+        if commit.get("breaking"):
+            entry += " **[BREAKING]**"
+
+        sections[section].append(entry)
+
+    lines = [header, ""]
+
+    for section_name in _SECTION_ORDER:
+        entries = sections[section_name]
+        if not entries:
+            continue
+        lines.append(f"### {section_name}")
+        lines.extend(entries)
+        lines.append("")
+
+    # Strip trailing blank line
+    while lines and lines[-1] == "":
+        lines.pop()
+
+    return "\n".join(lines)
+
+
+def update_changelog(cwd: str = ".", version: str = None) -> bool:
+    """Parse commits and prepend a new entry to CHANGELOG.md.
+
+    Reads existing CHANGELOG.md (or creates a new one). Inserts the new
+    entry after the top-level `# Changelog` header without overwriting
+    existing sections.
+
+    Args:
+        cwd: Working directory (default: current directory)
+        version: Version label (default: "Unreleased")
+
+    Returns:
+        True on success, False on failure or if no commits to add.
+    """
+    commits = parse_commit_log(cwd)
+    if not commits:
+        return False
+
+    entry = generate_changelog_entry(commits, version=version or "Unreleased")
+    if not entry:
+        return False
+
+    changelog_path = os.path.join(cwd, "CHANGELOG.md")
+
+    try:
+        if os.path.exists(changelog_path):
+            with open(changelog_path, "r", encoding="utf-8") as f:
+                existing = f.read()
+        else:
+            existing = "# Changelog\n\nAll notable changes to this project will be documented here.\n"
+
+        # Find insertion point: after the first `# Changelog` header line
+        lines = existing.splitlines(keepends=True)
+        insert_idx = 0
+        for i, line in enumerate(lines):
+            if line.startswith("# "):
+                insert_idx = i + 1
+                # Skip blank lines immediately after the header
+                while insert_idx < len(lines) and lines[insert_idx].strip() == "":
+                    insert_idx += 1
+                break
+
+        new_block = entry + "\n\n"
+        lines.insert(insert_idx, new_block)
+        new_content = "".join(lines)
+
+        with open(changelog_path, "w", encoding="utf-8") as f:
+            f.write(new_content)
+
+        return True
+
+    except OSError:
+        return False
+
+
+def _dry_run(cwd: str = ".", version: str = None) -> str:
+    """Return the changelog entry that would be written, without modifying any file."""
+    commits = parse_commit_log(cwd)
+    if not commits:
+        return "[OMG Changelog] No conventional commits found (or feature flag disabled)."
+    return generate_changelog_entry(commits, version=version or "Unreleased")
+
+
+def main():
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="OMG Changelog Generator — parses conventional commits and updates CHANGELOG.md"
+    )
+    parser.add_argument("--cwd", default=".", help="Working directory (default: .)")
+    parser.add_argument("--version", default=None, help="Version label (default: Unreleased)")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the changelog entry without writing to file",
+    )
+    args = parser.parse_args()
+
+    if args.dry_run:
+        print(_dry_run(cwd=args.cwd, version=args.version))
+        return
+
+    success = update_changelog(cwd=args.cwd, version=args.version)
+    if success:
+        print("[OMG Changelog] CHANGELOG.md updated successfully.")
+    else:
+        print("[OMG Changelog] No changes written (no commits or feature flag disabled).")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()