ai-push-hooks 0.2.1 → 0.3.0

package/src/ai_push_hooks/plugin_loader.py

@@ -0,0 +1,398 @@
+"""Internal loader and dispatcher for repository-local Python workflow hooks.
+
+This module intentionally does not provide discovery, registration, or a plugin
+SDK.  A :class:`PluginLoader` belongs to one workflow run.  It reads each
+referenced source file once and keeps the resulting module snapshot in a
+canonical, per-run cache.  :class:`PluginDispatcher` is the small adapter the
+workflow engine can use after its normal gates and artifact resolution have
+completed.
+"""
+
+from __future__ import annotations  # noqa: I001
+
+import copy
+import errno
+import hashlib
+import inspect
+import os
+import pathlib
+import re
+import stat
+import threading
+from collections.abc import Callable, Mapping, Sequence
+from types import ModuleType
+from typing import Any
+
+from .paths import (
+    path_has_symlink,
+    relative_path_parts,
+    resolve_contained_path,
+)
+from .plugins import PluginContext, PushContext
+from .types import HookError, ModuleRuntimeState, RuntimeContext, StepConfig
+
+
+_CALLABLE_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+_SOURCE_ENCODING = "utf-8"
+_OS_OPEN = os.open
+_DESCRIPTOR_RELATIVE_SUPPORTED = bool(
+    getattr(os, "O_DIRECTORY", 0)
+    and getattr(os, "O_NOFOLLOW", 0)
+    and _OS_OPEN in getattr(os, "supports_dir_fd", ())
+)
+
+
+def _descriptor_relative_supported() -> bool:
+    return _DESCRIPTOR_RELATIVE_SUPPORTED
+
+
+def _reference_parts(reference: str) -> tuple[str, str]:
+    if not isinstance(reference, str) or reference.count(":") != 1:
+        raise HookError(
+            "Python plugin reference must be a repository-relative .py path followed by :callable"
+        )
+    path_value, callable_name = reference.split(":", 1)
+    if not _CALLABLE_PATTERN.fullmatch(callable_name):
+        raise HookError("Python plugin callable must be one top-level identifier")
+    parts = relative_path_parts(path_value, "Python plugin path")
+    if not parts[-1].endswith(".py"):
+        raise HookError("Python plugin path must name a .py file")
+    return "/".join(parts), callable_name
+
+
+def _canonical_root(repo_root: pathlib.Path) -> pathlib.Path:
+    try:
+        root = pathlib.Path(repo_root).resolve(strict=True)
+    except (OSError, RuntimeError):
+        raise HookError("Python plugin repository root is not accessible") from None
+    if not root.is_dir():
+        raise HookError("Python plugin repository root must be a directory")
+    return root
+
+
+def _open_source_descriptor_relative(
+    root: pathlib.Path, parts: tuple[str, ...]
+) -> tuple[pathlib.Path, bytes]:
+    """Walk every component relative to an O_NOFOLLOW directory descriptor."""
+
+    directory_fd = -1
+    file_fd = -1
+    directory_flags = (
+        os.O_RDONLY
+        | getattr(os, "O_CLOEXEC", 0)
+        | getattr(os, "O_DIRECTORY", 0)
+        | getattr(os, "O_NOFOLLOW", 0)
+    )
+    file_flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        directory_fd = _OS_OPEN(root, directory_flags)
+        for part in parts[:-1]:
+            next_fd = _OS_OPEN(part, directory_flags, dir_fd=directory_fd)
+            os.close(directory_fd)
+            directory_fd = next_fd
+        file_fd = _OS_OPEN(parts[-1], file_flags, dir_fd=directory_fd)
+        metadata = os.fstat(file_fd)
+        if not stat.S_ISREG(metadata.st_mode):
+            raise HookError("Python plugin path must reference an ordinary regular file")
+        with os.fdopen(file_fd, "rb") as source:
+            file_fd = -1
+            return root.joinpath(*parts), source.read()
+    except HookError:
+        raise
+    except OSError as exc:
+        if exc.errno in {errno.ELOOP, errno.ENOTDIR}:
+            raise HookError("Python plugin path must not traverse a symlink or reparse point") from None
+        if exc.errno == errno.ENOENT:
+            raise HookError("Python plugin path must reference an existing regular file") from None
+        raise HookError("Python plugin path could not be opened safely") from None
+    finally:
+        if file_fd >= 0:
+            os.close(file_fd)
+        if directory_fd >= 0:
+            os.close(directory_fd)
+
+
+def _open_source_absolute(root: pathlib.Path, relative_path: str) -> tuple[pathlib.Path, bytes]:
+    """Fallback for platforms without descriptor-relative open support."""
+
+    lexical_path = root.joinpath(*relative_path.split("/"))
+    if path_has_symlink(root, lexical_path):
+        raise HookError("Python plugin path must not traverse a symlink or reparse point")
+    callback_path = resolve_contained_path(root, relative_path, "Python plugin path")
+
+    try:
+        metadata = callback_path.lstat()
+    except (FileNotFoundError, OSError):
+        raise HookError("Python plugin path must reference an existing regular file") from None
+    reparse_flag = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+    if stat.S_ISLNK(metadata.st_mode) or bool(
+        getattr(metadata, "st_file_attributes", 0) & reparse_flag
+    ):
+        raise HookError("Python plugin path must not be a symlink or reparse point")
+    if not stat.S_ISREG(metadata.st_mode):
+        raise HookError("Python plugin path must reference an ordinary regular file")
+
+    flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(callback_path, flags)
+    except OSError:
+        raise HookError("Python plugin path could not be opened safely") from None
+    try:
+        descriptor_metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(descriptor_metadata.st_mode):
+            raise HookError("Python plugin path must reference an ordinary regular file")
+        with os.fdopen(descriptor, "rb") as source:
+            descriptor = -1
+            return callback_path, source.read()
+    except HookError:
+        raise
+    except OSError:
+        raise HookError("Python plugin source could not be read") from None
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+
+
+def _open_source(root: pathlib.Path, relative_path: str) -> tuple[pathlib.Path, bytes]:
+    """Open and read a contained ordinary file without following parents."""
+
+    parts = tuple(relative_path.split("/"))
+    if _descriptor_relative_supported():
+        return _open_source_descriptor_relative(root, parts)
+    return _open_source_absolute(root, relative_path)
+
+
+def _failure(stage: str, relative_path: str, callable_name: str, detail: str) -> HookError:
+    return HookError(
+        f"Python {stage} plugin {relative_path}:{callable_name} {detail}"
+    )
+
+
+class PluginLoader:
+    """Load explicit repository-local callbacks once for one workflow run."""
+
+    def __init__(self) -> None:
+        self._cache: dict[tuple[pathlib.Path, pathlib.Path], ModuleType] = {}
+        self._lock = threading.RLock()
+        self._module_number = 0
+
+    def load(self, repo_root: pathlib.Path, reference: str) -> Callable[..., Any]:
+        """Return the named top-level callable from a safe source snapshot.
+
+        The lock includes descriptor open, source read, compilation, and module
+        execution.  Thus concurrent collectors cannot execute the same source
+        twice.  The cache key includes both canonical repository root and
+        canonical file path, so identical relative names in two repositories
+        remain independent.
+        """
+
+        relative_path, callable_name = _reference_parts(reference)
+        root = _canonical_root(repo_root)
+        with self._lock:
+            lexical_callback_path = root.joinpath(*relative_path.split("/"))
+            key = (root, lexical_callback_path)
+            module = self._cache.get(key)
+            if module is None:
+                try:
+                    callback_path, source = _open_source(root, relative_path)
+                except HookError as exc:
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} could not be loaded safely: "
+                        f"{str(exc).removeprefix('Python plugin ')}"
+                    ) from None
+                # ``callback_path`` is canonical after containment checks and
+                # is equal to the lexical path for a safe repository file.
+                key = (root, callback_path)
+                try:
+                    source_text = source.decode(_SOURCE_ENCODING)
+                    code = compile(source_text, str(callback_path), "exec")
+                except UnicodeDecodeError:
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} source is not valid UTF-8"
+                    ) from None
+                except (SyntaxError, ValueError, TypeError):
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} could not be compiled"
+                    ) from None
+
+                self._module_number += 1
+                digest = hashlib.sha256(
+                    f"{root}\0{callback_path}".encode()
+                ).hexdigest()[:16]
+                module_name = f"ai_push_hooks_plugin_{digest}_{self._module_number}"
+                module = ModuleType(module_name)
+                module.__file__ = str(callback_path)
+                module.__package__ = ""
+                try:
+                    exec(code, module.__dict__)  # noqa: S102
+                except KeyboardInterrupt:
+                    raise
+                except SystemExit:
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} exited during import"
+                    ) from None
+                except ModuleNotFoundError as exc:
+                    if exc.name:
+                        detail = f"is missing dependency {exc.name!r}"
+                    else:
+                        detail = "could not import a dependency"
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} {detail}"
+                    ) from None
+                except ImportError:
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} could not import a dependency"
+                    ) from None
+                except Exception:  # noqa: BLE001
+                    raise HookError(
+                        f"Python plugin {relative_path}:{callable_name} failed during import"
+                    ) from None
+                self._cache[key] = module
+
+            try:
+                callback = getattr(module, callable_name)
+            except AttributeError:
+                raise _failure(
+                    "callback", relative_path, callable_name, "was not defined"
+                ) from None
+            if not callable(callback):
+                raise _failure(
+                    "callback", relative_path, callable_name, "is not callable"
+                ) from None
+            if inspect.iscoroutinefunction(callback):
+                raise _failure(
+                    "callback", relative_path, callable_name, "must be synchronous"
+                ) from None
+            return callback
+
+    def invoke(
+        self,
+        repo_root: pathlib.Path,
+        reference: str,
+        context: PluginContext,
+        *,
+        stage: str = "workflow",
+    ) -> Any:
+        """Load lazily and invoke one callback with exactly one context argument."""
+
+        relative_path, callable_name = _reference_parts(reference)
+        try:
+            callback = self.load(repo_root, reference)
+        except HookError as exc:
+            message = str(exc)
+            if message.startswith("Python plugin "):
+                message = message.replace(
+                    "Python plugin ", f"Python {stage} plugin ", 1
+                )
+            elif message.startswith("Python callback plugin "):
+                message = message.replace(
+                    "Python callback plugin ", f"Python {stage} plugin ", 1
+                )
+            raise HookError(message) from None
+
+        try:
+            value = callback(context)
+        except KeyboardInterrupt:
+            raise
+        except SystemExit:
+            raise _failure(stage, relative_path, callable_name, "exited") from None
+        except Exception:  # noqa: BLE001
+            raise _failure(stage, relative_path, callable_name, "raised an exception") from None
+
+        if inspect.isawaitable(value):
+            close = getattr(value, "close", None)
+            if callable(close):
+                close()
+            raise _failure(stage, relative_path, callable_name, "must return synchronously")
+        return value
+
+    # Explicit aliases make the intended internal seam easy to integrate while
+    # retaining one implementation and one cache.
+    load_callback = load
+    invoke_callback = invoke
+
+
+def _ordered_inputs(
+    step: StepConfig, input_paths: Mapping[str, pathlib.Path] | Sequence[pathlib.Path]
+) -> dict[str, pathlib.Path]:
+    if isinstance(input_paths, Mapping):
+        declared = set(step.inputs)
+        extra = [reference for reference in input_paths if reference not in declared]
+        if extra:
+            raise HookError(f"Undeclared Python plugin input: {extra[0]}")
+        missing = [reference for reference in step.inputs if reference not in input_paths]
+        if missing:
+            raise HookError(f"Missing resolved Python plugin input: {missing[0]}")
+        return {reference: input_paths[reference] for reference in step.inputs}
+    if len(input_paths) != len(step.inputs):
+        raise HookError("Resolved Python plugin inputs do not match declared inputs")
+    return dict(zip(step.inputs, input_paths))
+
+
+def build_plugin_context(
+    runtime: RuntimeContext,
+    state: ModuleRuntimeState,
+    step: StepConfig,
+    input_paths: Mapping[str, pathlib.Path] | Sequence[pathlib.Path],
+) -> PluginContext:
+    """Create the immutable callback snapshot from runtime state at invocation."""
+
+    cache = runtime.cache
+    branch_name = str(cache.get("branch_name", ""))
+    checked_out_branch = str(cache.get("checked_out_branch", branch_name))
+    ranges = cache.get("ranges", cache.get("branch_ranges", ()))
+    changed_files = cache.get("changed_files", cache.get("branch_changed_files", ()))
+    diff_text = str(cache.get("diff_text", cache.get("branch_diff_text", "")))
+    push_updates = cache.get("push_updates", cache.get("pushed_branch_updates", ()))
+    push = PushContext(
+        branch_name=branch_name,
+        checked_out_branch=checked_out_branch,
+        base_branch=runtime.config.general.base_branch,
+        ranges=tuple(ranges),
+        changed_files=tuple(changed_files),
+        diff_text=diff_text,
+        push_updates=tuple(push_updates),
+    )
+    return PluginContext(
+        repo_root=_canonical_root(runtime.repo_root),
+        module_id=state.module.id,
+        step_id=step.id,
+        inputs=_ordered_inputs(step, input_paths),
+        options=copy.deepcopy(step.options),
+        prior_module_metadata=copy.deepcopy(state.metadata),
+        push=push,
+        logger=runtime.logger,
+    )
+
+
+class PluginDispatcher:
+    """Dispatch configured Python steps without changing engine scheduling."""
+
+    def __init__(self, loader: PluginLoader | None = None) -> None:
+        self.loader = loader or PluginLoader()
+
+    def dispatch(
+        self,
+        runtime: RuntimeContext,
+        state: ModuleRuntimeState,
+        step: StepConfig,
+        input_paths: Mapping[str, pathlib.Path] | Sequence[pathlib.Path],
+    ) -> Any:
+        if not step.python:
+            raise HookError(f"Python {step.type} step `{step.id}` has no callback reference")
+        context = build_plugin_context(runtime, state, step, input_paths)
+        return self.loader.invoke(
+            runtime.repo_root,
+            step.python,
+            context,
+            stage=step.type,
+        )
+
+    invoke = dispatch
+
+
+__all__ = [
+    "PluginDispatcher",
+    "PluginLoader",
+    "build_plugin_context",
+]

package/src/ai_push_hooks/plugins.py

@@ -0,0 +1,134 @@
+"""Public, deliberately small contracts for repository-local workflow callbacks.
+
+This module is a contract surface, not a plugin SDK.  Callback code should only
+depend on the three records exported here; loading and dispatch remain host
+responsibilities.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import pathlib
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any
+
+from .paths import validate_path_component
+from .types import CollectorResult, HookError, HookLogger, PushRefUpdate
+
+__all__ = ["CollectorResult", "PluginContext", "PushContext"]
+
+
+def _freeze(value: Any) -> Any:
+    """Copy a supported snapshot value into immutable public containers."""
+
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(item) for item in value)
+    if isinstance(value, set):
+        return frozenset(_freeze(item) for item in value)
+    return copy.deepcopy(value)
+
+
+@dataclass(frozen=True, slots=True)
+class PushContext:
+    """The bounded push facts made available to a configured callback."""
+
+    branch_name: str
+    checked_out_branch: str
+    base_branch: str
+    ranges: tuple[str, ...]
+    changed_files: tuple[str, ...]
+    diff_text: str
+    push_updates: tuple[PushRefUpdate, ...]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "ranges", tuple(self.ranges))
+        object.__setattr__(self, "changed_files", tuple(self.changed_files))
+        object.__setattr__(self, "push_updates", tuple(self.push_updates))
+
+
+@dataclass(frozen=True, slots=True)
+class PluginContext:
+    """Frozen, flat input passed as the sole argument to a callback."""
+
+    repo_root: pathlib.Path
+    module_id: str
+    step_id: str
+    inputs: Mapping[str, pathlib.Path]
+    options: Mapping[str, Any]
+    prior_module_metadata: Mapping[str, Any]
+    push: PushContext
+    logger: HookLogger
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "inputs", MappingProxyType(dict(self.inputs)))
+        object.__setattr__(self, "options", _freeze(self.options))
+        object.__setattr__(self, "prior_module_metadata", _freeze(self.prior_module_metadata))
+
+
+def _require_json(value: Any, label: str) -> None:
+    try:
+        json.dumps(value, allow_nan=False)
+    except (RecursionError, TypeError, ValueError) as exc:
+        raise HookError(f"{label} must be JSON-serializable") from exc
+    pending = [(value, 0)]
+    while pending:
+        current, depth = pending.pop()
+        if depth > 1000:
+            raise HookError(f"{label} exceeds the maximum JSON nesting depth")
+        if isinstance(current, dict):
+            pending.extend((item, depth + 1) for item in current.values())
+        elif isinstance(current, list):
+            pending.extend((item, depth + 1) for item in current)
+
+
+def validate_collector_result(value: Any) -> CollectorResult:
+    """Validate and return a callback's collector result without mutating it."""
+
+    if not isinstance(value, CollectorResult):
+        raise HookError("Python collect callback must return CollectorResult")
+    if not isinstance(value.artifacts, dict):
+        raise HookError("CollectorResult.artifacts must be a mapping")
+    if type(value.skip_module) is not bool:
+        raise HookError("CollectorResult.skip_module must be a boolean")
+    if not isinstance(value.skip_reason, str):
+        raise HookError("CollectorResult.skip_reason must be a string")
+    if not isinstance(value.metadata, dict):
+        raise HookError("CollectorResult.metadata must be a mapping")
+    _require_json(value.metadata, "CollectorResult.metadata")
+    for name, payload in value.artifacts.items():
+        if not isinstance(name, str):
+            raise HookError("CollectorResult artifact names must be strings")
+        validate_path_component(name, "CollectorResult artifact name")
+        if not isinstance(payload, (str, dict, list)):
+            raise HookError(
+                f"CollectorResult.artifacts[{name!r}] must be a string, object, or array"
+            )
+        _require_json(payload, f"CollectorResult artifact {name!r}")
+    return value
+
+
+def validate_exec_result(value: Any) -> dict[str, Any]:
+    """Validate the JSON object returned by a Python exec callback."""
+
+    if not isinstance(value, dict):
+        raise HookError("Python exec callback must return a dict")
+    _require_json(value, "Python exec callback result")
+    return value
+
+
+def validate_assert_result(value: Any) -> dict[str, Any]:
+    """Validate the JSON object and strict boolean verdict from an assert callback."""
+
+    if not isinstance(value, dict):
+        raise HookError("Python assert callback must return a dict")
+    if "ok" not in value or type(value["ok"]) is not bool:
+        raise HookError("Python assert callback result.ok must be a boolean")
+    if "message" in value and not isinstance(value["message"], str):
+        raise HookError("Python assert callback result.message must be a string")
+    _require_json(value, "Python assert callback result")
+    return value

package/src/ai_push_hooks/prompts_builtin.py

@@ -71,6 +71,11 @@ skip_on_sync_branch = true
 base_branch = "main"
 
 [llm]
+# Compatibility default: OpenCode receives validated hook artifacts only.
+# Define [runners.<name>] and select it with [llm].runner, or override an
+# individual ask/apply step with runner = "<name>". Project access is explicit.
+# Repository callbacks use python = "path/to/file.py:callable" and command
+# steps use a direct argv array; both are trusted local code.
 runner = "opencode"
 model = "openai/gpt-5.6-terra"
 variant = ""
@@ -82,6 +87,8 @@ json_retry_new_session = true
 delete_session_after_run = true
 
 [logging]
+# Transcripts are OpenCode-only lifecycle exports; other runners are ephemeral
+# or command-owned. print_llm_output, when enabled, is normalized/redacted text.
 level = "status"
 jsonl = true
 dir = ".git/ai-push-hooks/logs"
@@ -102,7 +109,7 @@ collector = "docs_context"
 
 [[modules.docs.steps]]
 id = "query"
-type = "llm"
+type = "ask"
 prompt = """
 Given the attached diff and changed file list, output a JSON array of concise
 documentation search queries. Return JSON only.
@@ -113,7 +120,7 @@ schema = "string_array"
 
 [[modules.docs.steps]]
 id = "analyze"
-type = "llm"
+type = "ask"
 prompt = """
 Review the diff and matched docs excerpts. Return JSON issues only for factual
 documentation drift caused by the code changes.