ruleforge-python 0.1.1__py3-none-win_amd64.whl

ruleforge_python-0.1.1.data/purelib/ruleforge/__init__.py

@@ -0,0 +1,50 @@
+"""Ruleforge Python SDK."""
+
+from ._version import __version__
+from .alerts import Alert, parse_alert_line
+from .binary import BinaryResolutionError, resolve_policy_exe
+from .cli import (
+    RunMetrics,
+    RunResult,
+    ServiceHandle,
+    bundle_build,
+    bundle_inspect,
+    fmt,
+    run,
+    serve,
+    test,
+)
+from .async_service import AsyncRuleforgeService
+from .retry_queue import RetryQueueSink
+from .service import RuleforgeService, ServeOptions
+from .sinks import AsyncAlertSink, AlertSink, FileJsonlSink, StdoutSink, WebhookSink
+from .sources import SourceDefaults, SourceSpec, SourcesConfig
+
+__all__ = [
+    "__version__",
+    "Alert",
+    "AlertSink",
+    "AsyncAlertSink",
+    "AsyncRuleforgeService",
+    "BinaryResolutionError",
+    "FileJsonlSink",
+    "RetryQueueSink",
+    "RunMetrics",
+    "RunResult",
+    "RuleforgeService",
+    "ServeOptions",
+    "ServiceHandle",
+    "SourceDefaults",
+    "SourceSpec",
+    "SourcesConfig",
+    "StdoutSink",
+    "WebhookSink",
+    "bundle_build",
+    "bundle_inspect",
+    "fmt",
+    "parse_alert_line",
+    "resolve_policy_exe",
+    "run",
+    "serve",
+    "test",
+]

ruleforge_python-0.1.1.data/purelib/ruleforge/_version.py

@@ -0,0 +1,9 @@
+"""Package version.
+
+Release automation should set RULEFORGE_VERSION to match the core Ruleforge
+release tag.
+"""
+
+import os
+
+__version__ = os.environ.get("RULEFORGE_VERSION", "0.0.0")

ruleforge_python-0.1.1.data/purelib/ruleforge/alerts.py

@@ -0,0 +1,86 @@
+"""Alert models and parsing helpers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class Alert:
+    ts: str
+    source_id: str
+    source: str
+    rule: str
+    severity: str
+    tags: tuple[str, ...] = field(default_factory=tuple)
+    emit: Mapping[str, Any] = field(default_factory=dict)
+    because: Mapping[str, Any] | None = None
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> "Alert":
+        tags: tuple[str, ...] = tuple(
+            str(tag) for tag in payload.get("tags", []) if isinstance(tag, (str, int, float))
+        )
+        emit = payload.get("emit")
+        if not isinstance(emit, Mapping):
+            emit = {}
+        because = payload.get("because")
+        if because is not None and not isinstance(because, Mapping):
+            because = None
+
+        return cls(
+            ts=str(payload.get("ts", "")),
+            source_id=str(payload.get("source_id", "")),
+            source=str(payload.get("source", "")),
+            rule=str(payload.get("rule", "")),
+            severity=str(payload.get("severity", "")),
+            tags=tags,
+            emit=emit,
+            because=because,
+            raw=dict(payload),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = dict(self.raw)
+        if data:
+            return data
+        return {
+            "ts": self.ts,
+            "source_id": self.source_id,
+            "source": self.source,
+            "rule": self.rule,
+            "severity": self.severity,
+            "tags": list(self.tags),
+            "emit": dict(self.emit),
+            "because": None if self.because is None else dict(self.because),
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, separators=(",", ":"))
+
+
+def parse_alert_line(line: str) -> Alert | None:
+    """Parse a single JSONL line from policy output.
+
+    Returns Alert for match records, otherwise None.
+    """
+
+    text = line.strip()
+    if not text or not text.startswith("{"):
+        return None
+
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+
+    if not isinstance(payload, dict):
+        return None
+
+    if "rule" not in payload or "severity" not in payload:
+        return None
+
+    return Alert.from_dict(payload)

ruleforge_python-0.1.1.data/purelib/ruleforge/async_service.py

@@ -0,0 +1,106 @@
+"""Async wrapper for RuleforgeService."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .alerts import Alert
+from .service import RuleforgeService, ServeOptions
+from .sinks import AlertSink
+
+_SENTINEL = object()
+
+
+class AsyncRuleforgeService:
+    def __init__(
+        self,
+        *,
+        sources_config: str | Path,
+        sources_status: str | Path | None = None,
+        policy_path: str | Path | None = None,
+        sinks: Sequence[AlertSink] | None = None,
+        options: ServeOptions | None = None,
+        extra_args: Sequence[str] | None = None,
+        serve_kwargs: Mapping[str, Any] | None = None,
+        cwd: str | Path | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        self._service = RuleforgeService.from_sources_config(
+            sources_config=sources_config,
+            sources_status=sources_status,
+            policy_path=policy_path,
+            sinks=sinks,
+            options=options,
+            extra_args=extra_args,
+            serve_kwargs=serve_kwargs,
+            cwd=cwd,
+            env=env,
+        )
+        self._bridge_stop = threading.Event()
+        self._bridge_thread: threading.Thread | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._queue: asyncio.Queue[Alert | object] = asyncio.Queue()
+
+    async def start(self) -> None:
+        if self._bridge_thread and self._bridge_thread.is_alive():
+            return
+        self._drain_queue()
+        self._loop = asyncio.get_running_loop()
+        self._bridge_stop.clear()
+        self._service.start()
+        self._bridge_thread = threading.Thread(
+            target=self._bridge_alerts,
+            name="ruleforge-async-bridge",
+            daemon=True,
+        )
+        self._bridge_thread.start()
+
+    async def stop(self) -> None:
+        self._bridge_stop.set()
+        self._service.stop()
+        await asyncio.to_thread(self._service.wait)
+        if self._bridge_thread is not None:
+            self._bridge_thread.join(timeout=2.0)
+
+    async def wait(self, timeout: float | None = None) -> bool:
+        return await asyncio.to_thread(self._service.wait, timeout)
+
+    async def next_alert(self, timeout: float | None = None) -> Alert | None:
+        if timeout is None:
+            item = await self._queue.get()
+        else:
+            item = await asyncio.wait_for(self._queue.get(), timeout=timeout)
+        if item is _SENTINEL:
+            return None
+        return item
+
+    async def alerts(self):
+        while True:
+            item = await self._queue.get()
+            if item is _SENTINEL:
+                break
+            yield item
+
+    @property
+    def last_exit_code(self) -> int | None:
+        return self._service.last_exit_code
+
+    def _bridge_alerts(self) -> None:
+        for alert in self._service.iter_alerts():
+            if self._bridge_stop.is_set():
+                break
+            if self._loop is None:
+                break
+            self._loop.call_soon_threadsafe(self._queue.put_nowait, alert)
+        if self._loop is not None:
+            self._loop.call_soon_threadsafe(self._queue.put_nowait, _SENTINEL)
+
+    def _drain_queue(self) -> None:
+        while True:
+            try:
+                self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                return

ruleforge_python-0.1.1.data/purelib/ruleforge/bin/README.md

@@ -0,0 +1,10 @@
+The host-platform `policy` executable is staged here during wheel packaging.
+
+Development helper:
+
+```bash
+python python/scripts/build_release_artifacts.py \
+  --policy-binary-path <path-to-policy-binary> \
+  --output-root <build-output-root> \
+  --skip-tests
+```

ruleforge_python-0.1.1.data/purelib/ruleforge/bin/policy.sha256

@@ -0,0 +1,7 @@
+{
+  "file": "policy.exe",
+  "sha256": "950586c2fc759b25ad431dc58b8eda968506421af126b37f04274c2e35623c6e",
+  "staged_utc": "2026-02-12T01:58:14.385884+00:00",
+  "platform": "windows",
+  "machine": "amd64"
+}

ruleforge_python-0.1.1.data/purelib/ruleforge/binary.py

@@ -0,0 +1,137 @@
+"""Policy executable resolution."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import stat
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+try:
+    from importlib import resources
+except ImportError:  # pragma: no cover
+    import importlib_resources as resources  # type: ignore
+
+
+class BinaryResolutionError(RuntimeError):
+    """Raised when no usable policy executable can be resolved."""
+
+
+@dataclass(frozen=True)
+class BinaryResolution:
+    path: Path
+    source: str
+
+
+_EMBEDDED_CACHE_PATH: Optional[Path] = None
+
+
+def resolve_policy_exe(explicit_path: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve policy executable path.
+
+    Resolution order:
+    1) explicit path
+    2) RULEFORGE_POLICY_PATH
+    3) embedded package binary
+    4) PATH lookup (platform-specific names)
+    """
+
+    resolved = resolve_policy(explicit_path)
+    return resolved.path
+
+
+def resolve_policy(explicit_path: str | os.PathLike[str] | None = None) -> BinaryResolution:
+    if explicit_path:
+        explicit = Path(explicit_path).expanduser().resolve()
+        _validate_executable(explicit, "explicit path")
+        return BinaryResolution(path=explicit, source="explicit")
+
+    env_path = os.environ.get("RULEFORGE_POLICY_PATH")
+    if env_path:
+        env_candidate = Path(env_path).expanduser().resolve()
+        _validate_executable(env_candidate, "RULEFORGE_POLICY_PATH")
+        return BinaryResolution(path=env_candidate, source="env")
+
+    embedded = _resolve_embedded_policy()
+    if embedded is not None:
+        return BinaryResolution(path=embedded, source="embedded")
+
+    for name in _path_lookup_names():
+        found = shutil.which(name)
+        if found:
+            candidate = Path(found).expanduser().resolve()
+            _validate_executable(candidate, "PATH")
+            return BinaryResolution(path=candidate, source="path")
+
+    raise BinaryResolutionError(
+        "Unable to locate policy executable. Provide policy_path, set "
+        "RULEFORGE_POLICY_PATH, install a wheel that bundles a platform-native "
+        "policy binary, or add policy to PATH."
+    )
+
+
+def _validate_executable(path: Path, source: str) -> None:
+    if not path.exists():
+        raise BinaryResolutionError(f"Policy executable from {source} does not exist: {path}")
+    if path.is_dir():
+        raise BinaryResolutionError(f"Policy executable from {source} is a directory: {path}")
+    if os.name != "nt" and not os.access(path, os.X_OK):
+        raise BinaryResolutionError(
+            f"Policy executable from {source} is not executable on this platform: {path}"
+        )
+
+
+def _embedded_binary_name() -> str:
+    return "policy.exe" if os.name == "nt" else "policy"
+
+
+def _alternate_embedded_binary_name() -> str:
+    return "policy" if os.name == "nt" else "policy.exe"
+
+
+def _path_lookup_names() -> tuple[str, ...]:
+    if os.name == "nt":
+        return ("policy.exe", "policy")
+    return ("policy", "policy.exe")
+
+
+def _resolve_embedded_policy() -> Optional[Path]:
+    global _EMBEDDED_CACHE_PATH
+
+    if _EMBEDDED_CACHE_PATH is not None and _EMBEDDED_CACHE_PATH.exists():
+        return _EMBEDDED_CACHE_PATH
+
+    try:
+        package_root = resources.files("ruleforge")
+    except ModuleNotFoundError:
+        return None
+
+    binary_name = _embedded_binary_name()
+    traversable = package_root.joinpath(f"bin/{binary_name}")
+    if not traversable.is_file():
+        alt_name = _alternate_embedded_binary_name()
+        alt_traversable = package_root.joinpath(f"bin/{alt_name}")
+        if alt_traversable.is_file():
+            raise BinaryResolutionError(
+                "Embedded policy binary does not match this platform "
+                f"(found {alt_name}, expected {binary_name}). Install a "
+                "wheel built for your OS/architecture."
+            )
+        return None
+
+    data = traversable.read_bytes()
+    digest = hashlib.sha256(data).hexdigest()[:16]
+    cache_dir = Path(tempfile.gettempdir()) / "ruleforge-python" / digest
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    materialized = cache_dir / binary_name
+    if not materialized.exists():
+        materialized.write_bytes(data)
+    if os.name != "nt":
+        materialized.chmod(materialized.stat().st_mode | stat.S_IEXEC)
+
+    _EMBEDDED_CACHE_PATH = materialized
+    return materialized