@trac3er/oh-my-god 1.0.2

package/omg_natives/__init__.py

@@ -0,0 +1,186 @@
+"""OMG Natives — Rust-accelerated hot paths with pure-Python fallbacks.
+
+When the Rust binary is built and installed (via ``maturin develop``),
+this package delegates to the compiled ``omg_natives._native`` extension.
+Otherwise, every public function falls back to a pure-Python implementation
+so that OMG works identically — just slower on CPU-intensive paths.
+
+Feature flag: ``OMG_RUST_ENGINE_ENABLED`` (default: False)
+"""
+
+from __future__ import annotations
+
+import fnmatch as _fnmatch
+import os as _os
+import re as _re
+import sys as _sys
+from pathlib import Path as _Path
+from typing import List, Optional
+
+# ---------------------------------------------------------------------------
+# Feature flag — follows the hooks/_common.get_feature_flag pattern
+# ---------------------------------------------------------------------------
+
+def _get_feature_flag(flag_name: str, default: bool = False) -> bool:
+    """Minimal feature-flag check (env var only, no settings.json dependency).
+
+    Mirrors the resolution logic of ``hooks/_common.get_feature_flag`` but
+    avoids importing hooks internals so this package stays self-contained.
+    """
+    env_key = f"OMG_{flag_name.upper()}_ENABLED"
+    env_val = _os.environ.get(env_key, "").lower()
+    if env_val in ("0", "false", "no"):
+        return False
+    if env_val in ("1", "true", "yes"):
+        return True
+    # Try full get_feature_flag if available
+    try:
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from hooks._common import get_feature_flag  # type: ignore[import-untyped]
+        return get_feature_flag(flag_name, default=default)
+    except Exception:
+        return default
+
+
+OMG_RUST_ENABLED: bool = _get_feature_flag("RUST_ENGINE", default=False)
+
+# ---------------------------------------------------------------------------
+# Try importing compiled Rust extension
+# ---------------------------------------------------------------------------
+
+RUST_AVAILABLE: bool = False
+
+if OMG_RUST_ENABLED:
+    try:
+        from omg_natives._native import *  # noqa: F401, F403
+        RUST_AVAILABLE = True
+    except ImportError:
+        RUST_AVAILABLE = False
+
+# ---------------------------------------------------------------------------
+# Pure-Python fallback implementations
+# ---------------------------------------------------------------------------
+
+if not RUST_AVAILABLE:
+
+    def grep(pattern: str, path: str) -> List[str]:
+        """Search for *pattern* (regex) in the file at *path*.
+
+        Returns a list of matching lines (without trailing newline).
+        """
+        matches: List[str] = []
+        try:
+            compiled = _re.compile(pattern)
+            with open(path, "r", encoding="utf-8", errors="ignore") as fh:
+                for line in fh:
+                    if compiled.search(line):
+                        matches.append(line.rstrip("\n"))
+        except (OSError, _re.error):
+            pass
+        return matches
+
+    def glob_match(pattern: str, base: str = ".") -> List[str]:
+        """Return file paths under *base* that match the glob *pattern*.
+
+        Pure-Python implementation using ``os.walk`` + ``fnmatch``.
+        """
+        results: List[str] = []
+        base_path = _Path(base).resolve()
+        try:
+            for root, _dirs, files in _os.walk(base_path):
+                for name in files:
+                    full = _os.path.join(root, name)
+                    rel = _os.path.relpath(full, base_path)
+                    if _fnmatch.fnmatch(rel, pattern):
+                        results.append(rel)
+        except OSError:
+            pass
+        return results
+
+    def normalize(text: str) -> str:
+        """Normalize whitespace and line endings in *text*."""
+        return text.replace("\r\n", "\n").strip()
+
+    def highlight_syntax(code: str, language: str = "") -> str:
+        """Return *code* unchanged (no highlighting without Rust)."""
+        _ = language
+        return code
+
+    def strip_tags(html: str) -> str:
+        """Strip HTML tags from *html*, returning plain text."""
+        return _re.sub(r"<[^>]+>", "", html)
+
+# ---------------------------------------------------------------------------
+# N-API Binding Registry (Task 5.2)
+# ---------------------------------------------------------------------------
+
+from omg_natives._bindings import (  # noqa: E402
+    REGISTRY,
+    BindingRegistry,
+    BindingSpec,
+    bind_function,
+    call_binding,
+    get_binding,
+    marshal_from_rust,
+    marshal_to_rust,
+)
+
+# ---------------------------------------------------------------------------
+# Task 5.3: Import 12 module fallbacks (self-register via bind_function)
+# Each module self-registers with REGISTRY at import time.
+# Note: grep module imported without shadowing legacy grep(pattern, path)->List[str]
+# ---------------------------------------------------------------------------
+
+# Save legacy functions that module imports would shadow
+_legacy_grep = grep  # type: ignore[possibly-undefined]  # noqa: E402
+
+import omg_natives.grep as _grep_mod  # noqa: E402, F401
+from omg_natives.glob import glob as glob  # noqa: E402
+from omg_natives.shell import shell  # noqa: E402
+from omg_natives.text import text as text  # noqa: E402
+from omg_natives.keys import keys  # noqa: E402
+from omg_natives.highlight import highlight  # noqa: E402
+from omg_natives.task import task_run  # noqa: E402
+from omg_natives.ps import ps  # noqa: E402
+from omg_natives.prof import prof  # noqa: E402
+from omg_natives.image import image  # noqa: E402
+from omg_natives.clipboard import clipboard  # noqa: E402
+from omg_natives.html import html  # noqa: E402
+
+# Restore legacy grep (returns List[str] for backward compat)
+grep = _legacy_grep  # type: ignore[assignment]  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Public API surface
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "OMG_RUST_ENABLED",
+    "RUST_AVAILABLE",
+    "grep",
+    "glob_match",
+    "normalize",
+    "highlight_syntax",
+    "strip_tags",
+    # N-API Binding Registry
+    "REGISTRY",
+    "BindingRegistry",
+    "BindingSpec",
+    "bind_function",
+    "call_binding",
+    "get_binding",
+    "marshal_from_rust",
+    "marshal_to_rust",
+    # Task 5.3: 12 Core Module Functions
+    "glob",
+    "shell",
+    "text",
+    "keys",
+    "highlight",
+    "task_run",
+    "ps",
+    "prof",
+    "image",
+    "clipboard",
+    "html",
+]

package/omg_natives/_bindings.py

@@ -0,0 +1,165 @@
+"""N-API Binding Registry — maps function names to (rust_fn_spec, python_fallback) pairs.
+
+Provides a registry for Rust↔Python bindings with marshalling utilities.
+When Rust is not available, all calls transparently use the Python fallback.
+
+This module is pure stdlib — no external dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# BindingSpec — describes a single Rust↔Python binding
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BindingSpec:
+    """Specification for a single Rust↔Python binding.
+
+    Attributes:
+        name: Logical name of the binding (e.g. ``"grep"``).
+        rust_symbol: Rust symbol path (e.g. ``"omg_natives::grep::grep"``).
+        python_fallback: Callable Python implementation used when Rust is unavailable.
+        type_hints: Optional mapping of parameter names to type strings for
+            documentation and marshalling guidance.
+    """
+
+    name: str
+    rust_symbol: str
+    python_fallback: Callable[..., Any]
+    type_hints: Dict[str, str] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Marshalling utilities — Rust↔Python data type conversion
+# ---------------------------------------------------------------------------
+
+# Supported types for Rust↔Python marshalling.
+_SUPPORTED_TYPES = (str, list, dict, int, float, bool, bytes, type(None))
+
+
+def marshal_to_rust(value: Any) -> Any:
+    """Convert a Python value to a Rust-compatible representation.
+
+    In the current pure-Python fallback mode this is an identity operation
+    for all supported types (str, list, dict, int, float, bool, bytes, None).
+
+    Raises:
+        TypeError: If *value* is not a supported type.
+    """
+    if not isinstance(value, _SUPPORTED_TYPES):
+        raise TypeError(
+            f"Unsupported type for Rust marshalling: {type(value).__name__}. "
+            f"Supported: str, list, dict, int, float, bool, bytes, None"
+        )
+    return value
+
+
+def marshal_from_rust(value: Any) -> Any:
+    """Convert a Rust-returned value back to a Python representation.
+
+    In pure-Python fallback mode this is always the identity function
+    because no actual FFI boundary is crossed.
+    """
+    return value
+
+
+# ---------------------------------------------------------------------------
+# BindingRegistry — central store for all registered bindings
+# ---------------------------------------------------------------------------
+
+class BindingRegistry:
+    """Thread-safe registry mapping binding names to :class:`BindingSpec` instances.
+
+    Usage::
+
+        registry = BindingRegistry()
+        registry.register("grep", "omg_natives::grep::grep", _py_grep)
+        result = registry.call("grep", pattern, path)
+    """
+
+    def __init__(self) -> None:
+        self._bindings: Dict[str, BindingSpec] = {}
+
+    # -- mutators -----------------------------------------------------------
+
+    def register(
+        self,
+        name: str,
+        rust_symbol: str,
+        python_fallback: Callable[..., Any],
+        type_hints: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """Register a new binding (or overwrite an existing one)."""
+        self._bindings[name] = BindingSpec(
+            name=name,
+            rust_symbol=rust_symbol,
+            python_fallback=python_fallback,
+            type_hints=type_hints or {},
+        )
+
+    # -- accessors ----------------------------------------------------------
+
+    def get(self, name: str) -> Optional[BindingSpec]:
+        """Return the :class:`BindingSpec` for *name*, or ``None``."""
+        return self._bindings.get(name)
+
+    def list_names(self) -> List[str]:
+        """Return a sorted list of all registered binding names."""
+        return sorted(self._bindings.keys())
+
+    def is_rust_available(self, name: str) -> bool:
+        """Check whether the Rust implementation is available for *name*.
+
+        Always returns ``False`` in pure-Python fallback mode.
+        """
+        # In a real Rust-enabled build this would probe the native extension.
+        return False
+
+    # -- invocation ---------------------------------------------------------
+
+    def call(self, __name: str, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the binding identified by *__name*.
+
+        In pure-Python fallback mode this delegates directly to the
+        registered ``python_fallback`` callable.
+
+        Raises:
+            KeyError: If no binding with *__name* is registered.
+        """
+        spec = self._bindings.get(__name)
+        if spec is None:
+            raise KeyError(f"No binding registered with name: {__name!r}")
+        return spec.python_fallback(*args, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton and convenience wrappers
+# ---------------------------------------------------------------------------
+
+REGISTRY = BindingRegistry()
+"""Module-level singleton :class:`BindingRegistry` instance."""
+
+
+def bind_function(
+    name: str,
+    rust_symbol: str,
+    python_fallback: Callable[..., Any],
+    type_hints: Optional[Dict[str, str]] = None,
+) -> None:
+    """Convenience wrapper — register a binding in the global :data:`REGISTRY`."""
+    REGISTRY.register(name, rust_symbol, python_fallback, type_hints=type_hints)
+
+
+def get_binding(name: str) -> Optional[BindingSpec]:
+    """Convenience wrapper — look up a binding in the global :data:`REGISTRY`."""
+    return REGISTRY.get(name)
+
+
+def call_binding(__name: str, *args: Any, **kwargs: Any) -> Any:
+    """Convenience wrapper — invoke a binding via the global :data:`REGISTRY`."""
+    return REGISTRY.call(__name, *args, **kwargs)

package/omg_natives/clipboard.py

@@ -0,0 +1,36 @@
+"""OMG Natives — clipboard: clipboard operation stubs.
+
+Pure-Python stubs for clipboard operations.
+No actual clipboard interaction — returns placeholder values.
+
+Feature flag: ``OMG_RUST_ENGINE_ENABLED`` (default: False)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from omg_natives._bindings import bind_function
+
+
+def clipboard(operation: str = "get", text: Optional[str] = None) -> str:
+    """Clipboard operation stubs.
+
+    - ``"get"``: returns ``""`` (stub — no actual clipboard access).
+    - ``"set"``: returns ``"ok"`` (stub — no actual clipboard access).
+    """
+    if operation == "get":
+        return ""
+    elif operation == "set":
+        return "ok"
+    else:
+        return ""
+
+
+# Self-register with the global binding registry
+bind_function(
+    name="clipboard",
+    rust_symbol="omg_natives::clipboard::clipboard",
+    python_fallback=clipboard,
+    type_hints={"operation": "str", "text": "str"},
+)

package/omg_natives/glob.py

@@ -0,0 +1,42 @@
+"""OMG Natives — glob: file path matching.
+
+Pure-Python fallback for the Rust ``omg_natives::glob::glob_match`` function.
+Uses ``pathlib.Path.glob`` for pattern matching.
+
+Feature flag: ``OMG_RUST_ENGINE_ENABLED`` (default: False)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from omg_natives._bindings import bind_function
+
+
+def glob(pattern: str, base: str = ".") -> list[str]:
+    """Return file paths under *base* that match the glob *pattern*.
+
+    Uses ``pathlib.Path.glob`` for matching.
+    Returns relative paths as strings.
+    """
+    results: List[str] = []
+    base_path = Path(base).resolve()
+    try:
+        for match in base_path.glob(pattern):
+            try:
+                results.append(str(match.relative_to(base_path)))
+            except ValueError:
+                results.append(str(match))
+    except OSError:
+        pass
+    return results
+
+
+# Self-register with the global binding registry
+bind_function(
+    name="glob",
+    rust_symbol="omg_natives::glob::glob_match",
+    python_fallback=glob,
+    type_hints={"pattern": "str", "base": "str"},
+)

package/omg_natives/grep.py

@@ -0,0 +1,61 @@
+"""OMG Natives — grep: regex search in files.
+
+Pure-Python fallback for the Rust ``omg_natives::grep::grep`` function.
+Uses ``re`` and ``os.walk`` for recursive file searching.
+
+Feature flag: ``OMG_RUST_ENGINE_ENABLED`` (default: False)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import List
+
+from omg_natives._bindings import bind_function
+
+
+def grep(pattern: str, path: str, recursive: bool = False) -> list[dict]:
+    """Search for *pattern* (regex) in files.
+
+    If *recursive* is False, searches only the single file at *path*.
+    If *recursive* is True and *path* is a directory, walks the directory tree.
+
+    Returns a list of ``{"file": path, "line": lineno, "text": line_content}``.
+    """
+    results: List[dict] = []
+    try:
+        compiled = re.compile(pattern)
+    except re.error:
+        return results
+
+    def _search_file(filepath: str) -> None:
+        try:
+            with open(filepath, "r", encoding="utf-8", errors="ignore") as fh:
+                for lineno, line in enumerate(fh, start=1):
+                    if compiled.search(line):
+                        results.append({
+                            "file": filepath,
+                            "line": lineno,
+                            "text": line.rstrip("\n"),
+                        })
+        except OSError:
+            pass
+
+    if recursive and os.path.isdir(path):
+        for root, _dirs, files in os.walk(path):
+            for name in files:
+                _search_file(os.path.join(root, name))
+    else:
+        _search_file(path)
+
+    return results
+
+
+# Self-register with the global binding registry
+bind_function(
+    name="grep",
+    rust_symbol="omg_natives::grep::grep",
+    python_fallback=grep,
+    type_hints={"pattern": "str", "path": "str", "recursive": "bool"},
+)

package/omg_natives/highlight.py

@@ -0,0 +1,54 @@
+"""OMG Natives — highlight: basic syntax highlighting.
+
+Pure-Python fallback that returns code unchanged (no Pygments dependency).
+Optionally wraps code with a language comment header.
+
+Feature flag: ``OMG_RUST_ENGINE_ENABLED`` (default: False)
+"""
+
+from __future__ import annotations
+
+from omg_natives._bindings import bind_function
+
+# Known language comment prefixes
+_COMMENT_STYLES = {
+    "python": "#",
+    "javascript": "//",
+    "typescript": "//",
+    "rust": "//",
+    "go": "//",
+    "java": "//",
+    "c": "//",
+    "cpp": "//",
+    "ruby": "#",
+    "bash": "#",
+    "shell": "#",
+    "sh": "#",
+    "yaml": "#",
+    "toml": "#",
+}
+
+
+def highlight(code: str, language: str = "") -> str:
+    """Basic syntax highlighting — returns code unchanged (no Pygments).
+
+    If *language* is known, prepends a comment header indicating the language.
+    Otherwise returns *code* as-is.
+    """
+    if not language:
+        return code
+
+    lang_lower = language.lower()
+    comment = _COMMENT_STYLES.get(lang_lower)
+    if comment:
+        return f"{comment} [{lang_lower}]\n{code}"
+    return code
+
+
+# Self-register with the global binding registry
+bind_function(
+    name="highlight",
+    rust_symbol="omg_natives::highlight::highlight",
+    python_fallback=highlight,
+    type_hints={"code": "str", "language": "str"},
+)