ai-push-hooks 0.2.0 → 0.3.0

package/src/ai_push_hooks/engine.py

@@ -9,9 +9,24 @@ from .config import resolve_prompt_text
 from .executors.apply import run_apply_step
 from .executors.assertions import ASSERTION_HANDLERS
 from .executors.exec import EXEC_HANDLERS, env_bool
-from .executors.llm import run_llm_step
+from .executors.ask import run_ask_step
+from .executors.step_commands import execute_step_command
 from .modules import COLLECTORS
-from .types import CollectorResult, HookError, ModuleRuntimeState, RuntimeContext, StepConfig, StepResult, WorkflowRunResult
+from .plugin_loader import PluginDispatcher
+from .plugins import (
+    validate_assert_result,
+    validate_collector_result,
+    validate_exec_result,
+)
+from .types import (
+    CollectorResult,
+    HookError,
+    ModuleRuntimeState,
+    RuntimeContext,
+    StepConfig,
+    StepResult,
+    WorkflowRunResult,
+)
 
 CollectorHandler = Callable[[RuntimeContext, ModuleRuntimeState], CollectorResult]
 ExecHandler = Callable[[RuntimeContext, ModuleRuntimeState, StepConfig, list[pathlib.Path]], dict[str, Any]]
@@ -26,7 +41,7 @@ class WorkflowEngine:
         collectors: dict[str, CollectorHandler] | None = None,
         exec_handlers: dict[str, ExecHandler] | None = None,
         assertion_handlers: dict[str, AssertionHandler] | None = None,
-        llm_executor: Callable[[RuntimeContext, StepConfig, str, list[pathlib.Path], str], Any] = run_llm_step,
+        ask_executor: Callable[[RuntimeContext, StepConfig, str, list[pathlib.Path], str], Any] = run_ask_step,
         apply_executor: Callable[[RuntimeContext, ModuleRuntimeState, StepConfig, str, list[pathlib.Path], str], dict[str, object]] = run_apply_step,
     ) -> None:
         self.context = context
@@ -34,11 +49,16 @@ class WorkflowEngine:
         self.collectors = collectors or COLLECTORS
         self.exec_handlers = exec_handlers or EXEC_HANDLERS
         self.assertion_handlers = assertion_handlers or ASSERTION_HANDLERS
-        self.llm_executor = llm_executor
+        self.ask_executor = ask_executor
         self.apply_executor = apply_executor
+        self._plugin_dispatcher: PluginDispatcher | None = None
 
     def run(self) -> WorkflowRunResult:
         self.artifacts.prepare()
+        # A loader/cache is deliberately scoped to one workflow run.  In
+        # particular, a second run must not reuse a module snapshot from the
+        # first run.
+        self._plugin_dispatcher = PluginDispatcher()
         states = [
             ModuleRuntimeState(module=self.context.config.modules[module_id])
             for module_id in self.context.config.workflow.modules
@@ -110,14 +130,20 @@ class WorkflowEngine:
             return StepResult(status="skipped", artifacts={"result.json": path}, metadata={})
 
         if step.type == "collect":
+            if step.python:
+                input_paths = self._resolve_plugin_inputs(state, step)
+                result = validate_collector_result(
+                    self._dispatch_plugin(state, step, input_paths)
+                )
+                return self._persist_plugin_collect(state, step, result)
             return self._run_collect(state, step)
 
         input_paths = [self.artifacts.resolve_input(state, reference) for reference in step.inputs]
         stage_name = f"{state.module.id}.{step.id}"
 
-        if step.type == "llm":
+        if step.type == "ask":
             prompt = resolve_prompt_text(self.context.repo_root, step)
-            payload = self.llm_executor(self.context, step, prompt, input_paths, stage_name)
+            payload = self.ask_executor(self.context, step, prompt, input_paths, stage_name)
             artifact_name = step.output or "result.json"
             if isinstance(payload, (dict, list)) or artifact_name.endswith(".json"):
                 path = self.artifacts.write_json(state, state.step_index, step.id, artifact_name, payload)
@@ -132,6 +158,22 @@ class WorkflowEngine:
             return StepResult(artifacts={"result.json": path})
 
         if step.type == "exec":
+            if step.python:
+                plugin_inputs = dict(zip(step.inputs, input_paths))
+                payload = validate_exec_result(
+                    self._dispatch_plugin(state, step, plugin_inputs)
+                )
+                path = self._persist_plugin_result(state, step, payload)
+                return StepResult(artifacts={"result.json": path})
+            if step.command:
+                persisted = execute_step_command(
+                    self.context,
+                    state,
+                    step,
+                    dict(zip(step.inputs, input_paths)),
+                    artifacts=self.artifacts,
+                )
+                return StepResult(artifacts=dict(persisted.artifacts))
             handler = self.exec_handlers.get(step.executor or "")
             if handler is None:
                 raise HookError(f"Unknown exec handler: {step.executor}")
@@ -140,6 +182,24 @@ class WorkflowEngine:
             return StepResult(artifacts={"result.json": path})
 
         if step.type == "assert":
+            if step.python:
+                plugin_inputs = dict(zip(step.inputs, input_paths))
+                payload = validate_assert_result(
+                    self._dispatch_plugin(state, step, plugin_inputs)
+                )
+                path = self._persist_plugin_result(state, step, payload)
+                if not payload["ok"]:
+                    raise HookError(payload.get("message", "assertion failed"))
+                return StepResult(artifacts={"result.json": path})
+            if step.command:
+                persisted = execute_step_command(
+                    self.context,
+                    state,
+                    step,
+                    dict(zip(step.inputs, input_paths)),
+                    artifacts=self.artifacts,
+                )
+                return StepResult(artifacts=dict(persisted.artifacts))
             handler = self.assertion_handlers.get(step.assertion or "")
             if handler is None:
                 raise HookError(f"Unknown assertion handler: {step.assertion}")
@@ -151,6 +211,54 @@ class WorkflowEngine:
 
         raise HookError(f"Unsupported step type: {step.type}")
 
+    def _resolve_plugin_inputs(
+        self, state: ModuleRuntimeState, step: StepConfig
+    ) -> dict[str, pathlib.Path]:
+        """Resolve declared inputs in declaration order for a callback."""
+
+        return {
+            reference: self.artifacts.resolve_input(state, reference)
+            for reference in step.inputs
+        }
+
+    def _dispatch_plugin(
+        self,
+        state: ModuleRuntimeState,
+        step: StepConfig,
+        input_paths: dict[str, pathlib.Path],
+    ) -> Any:
+        dispatcher = self._plugin_dispatcher
+        if dispatcher is None:  # pragma: no cover - only direct private calls
+            dispatcher = PluginDispatcher()
+        return dispatcher.dispatch(self.context, state, step, input_paths)
+
+    def _persist_plugin_collect(
+        self, state: ModuleRuntimeState, step: StepConfig, result: CollectorResult
+    ) -> StepResult:
+        # Serialize and enforce both limits before the first write/register.
+        serialized = self.artifacts.serialize_plugin_artifacts(result.artifacts)
+        artifacts: dict[str, pathlib.Path] = {}
+        for artifact_name, content in serialized.items():
+            artifacts[artifact_name] = self.artifacts.write_bytes(
+                state, state.step_index, step.id, artifact_name, content
+            )
+        metadata = dict(result.metadata)
+        if result.skip_module:
+            metadata["skip_module"] = True
+            metadata["skip_reason"] = result.skip_reason
+        return StepResult(artifacts=artifacts, metadata=metadata)
+
+    def _persist_plugin_result(
+        self, state: ModuleRuntimeState, step: StepConfig, payload: dict[str, Any]
+    ) -> pathlib.Path:
+        # Use the same bounded serializer as collector artifacts.  Validation
+        # happens first, and serialization happens before the result is written
+        # or registered.
+        serialized = self.artifacts.serialize_plugin_artifacts({"result.json": payload})
+        return self.artifacts.write_bytes(
+            state, state.step_index, step.id, "result.json", serialized["result.json"]
+        )
+
     def _run_collect(self, state: ModuleRuntimeState, step: StepConfig) -> StepResult:
         handler = self.collectors.get(step.collector or "")
         if handler is None:

package/src/ai_push_hooks/executors/apply.py

@@ -9,6 +9,7 @@ import tempfile
 from dataclasses import dataclass
 from typing import Any
 
+from ..config import resolve_runner_profile
 from ..paths import (
     atomic_write_bytes,
     ensure_private_directory,
@@ -27,7 +28,8 @@ from .exec import (
     resolve_git_dir,
     run_command,
 )
-from .llm import call_opencode, finalize_opencode_session, validate_opencode_attachments
+from .ask import validate_opencode_attachments
+from .runner_workflow import run_runner_once
 
 METADATA_MAX_FILES = 20_000
 METADATA_MAX_BYTES = 64 * 1024 * 1024
@@ -354,6 +356,8 @@ def _copy_checkout_to_staging(
     context: RuntimeContext,
     staging_root: pathlib.Path,
     allow_paths: tuple[str, ...],
+    *,
+    project_access: str = "artifacts",
 ) -> dict[str, DestinationState]:
     repo_root = context.repo_root
     git_roots = (
@@ -364,16 +368,25 @@ def _copy_checkout_to_staging(
     copied_bytes = 0
     baselines: dict[str, DestinationState] = {}
     resolved_repo_root = repo_root.resolve(strict=True)
-    allowed_paths = {
-        relative_path
-        for relative_path in _tracked_and_unignored_paths(repo_root)
-        if not _is_protected_path(relative_path)
-        and any(path_matches(relative_path, pattern) for pattern in allow_paths)
-    }
-    allowed_paths -= _ignored_changed_paths(repo_root, allowed_paths)
-    for relative_path in sorted(allowed_paths):
+    checkout_paths = _tracked_and_unignored_paths(repo_root)
+    if project_access == "project":
+        projection_candidates = checkout_paths
+    else:
+        projection_candidates = {
+            relative_path
+            for relative_path in checkout_paths
+            if not _is_protected_path(relative_path)
+            and any(path_matches(relative_path, pattern) for pattern in allow_paths)
+        }
+    ignored_paths = _ignored_changed_paths(repo_root, projection_candidates)
+    projection_paths = projection_candidates - ignored_paths
+    for relative_path in sorted(projection_paths):
+        if _is_protected_path(relative_path):
+            continue
         source = _repo_path_from_git(repo_root, relative_path)
         if path_has_symlink(repo_root, source):
+            if project_access == "project":
+                continue
             raise HookError(
                 f"Allowed checkout path is or traverses a symlink or reparse point: {relative_path}"
             )
@@ -384,7 +397,9 @@ def _copy_checkout_to_staging(
             continue
         if not source.exists():
             continue
-        if not source.is_file():
+        if not stat.S_ISREG(source.lstat().st_mode):
+            if project_access == "project":
+                continue
             raise HookError(f"Allowed checkout path is not a regular file: {relative_path}")
         copied_files += 1
         if copied_files > STAGING_MAX_FILES:
@@ -449,8 +464,11 @@ def _changed_staging_paths(
     unexpected = sorted(
         path
         for path in all_paths
-        if _is_protected_path(path)
-        or not any(path_matches(path, pattern) for pattern in allow_paths)
+        if before.get(path) != after.get(path)
+        and (
+            _is_protected_path(path)
+            or not any(path_matches(path, pattern) for pattern in allow_paths)
+        )
     )
     if unexpected:
         raise HookError("Apply staging workspace contains paths outside allowlist: " + ", ".join(unexpected))
@@ -732,14 +750,33 @@ def _verify_post_propagation_security_state(
         )
 
 
-def _apply_prompt(prompt: str, allow_paths: tuple[str, ...]) -> str:
+def _apply_prompt(
+    prompt: str,
+    allow_paths: tuple[str, ...],
+    *,
+    project_access: str = "artifacts",
+) -> str:
     rendered_paths = "\n".join(f"- {pattern}" for pattern in allow_paths)
+    if project_access == "project":
+        projection_text = (
+            "This workspace contains the eligible readable project projection and may "
+            "include readable repository files beyond the allowlist."
+        )
+    else:
+        projection_text = (
+            "This workspace contains only eligible readable files selected by the "
+            "allowlist."
+        )
     return (
         prompt.rstrip()
-        + "\n\nMANDATORY STAGING WRITE BOUNDARY:\n"
-        + "This workspace contains only approved files. Modify only paths matching:\n"
+        + "\n\nMANDATORY STAGING BOUNDARY:\n"
+        + projection_text
+        + "\nOnly changes to paths matching the allowlist below propagate to the real "
+        "checkout. Any other staging change fails the apply step.\n"
+        + "Allowlisted paths:\n"
         + rendered_paths
-        + "\nDo not create symlinks. Do not use commands, tasks, web access, or external paths.\n"
+        + "\nTool availability is controlled by runner and user policy; this instruction "
+        + "does not impose a universal tool ban. Do not create symlinks.\n"
     )
 
 
@@ -783,6 +820,7 @@ def run_apply_step(
         if input_path.name.endswith("issues.json"):
             issues = json.loads(input_path.read_text(encoding="utf-8"))
             if isinstance(issues, list) and not issues:
+                # Legacy compatibility shortcut; keep until an explicit replacement exists.
                 return {"changed": False, "changed_files": [], "skipped": True}
 
     _assert_apply_targets_checked_out_head(context)
@@ -798,17 +836,25 @@ def run_apply_step(
     propagated_expected: dict[str, StagedFile | None] = {}
     with tempfile.TemporaryDirectory(prefix="ai-push-hooks-apply-") as temporary_directory:
         staging_root = pathlib.Path(temporary_directory).resolve(strict=True)
-        destination_baselines = _copy_checkout_to_staging(context, staging_root, step.allow_paths)
+        profile = resolve_runner_profile(context.config, step)
+        destination_baselines = _copy_checkout_to_staging(
+            context,
+            staging_root,
+            step.allow_paths,
+            project_access=profile.project_access,
+        )
         staged_before = _inventory_staging(staging_root)
         try:
-            result = call_opencode(
+            result = run_runner_once(
                 context,
-                stage_name=stage_name,
-                purpose=f"{step.type}:{step.id}",
-                prompt=_apply_prompt(prompt, step.allow_paths),
-                files=validated_inputs,
-                agent="apply",
-                allow_paths=step.allow_paths,
+                step,
+                _apply_prompt(
+                    prompt,
+                    step.allow_paths,
+                    project_access=profile.project_access,
+                ),
+                validated_inputs,
+                stage_name,
                 working_directory=staging_root,
             )
         except Exception as exc:  # noqa: BLE001
@@ -823,13 +869,6 @@ def run_apply_step(
             if call_error is None:
                 call_error = exc
 
-        if result is not None:
-            try:
-                finalize_opencode_session(context, stage_name, result.session_id)
-            except Exception as exc:  # noqa: BLE001
-                if call_error is None:
-                    call_error = exc
-
         _verify_pre_propagation_security_state(
             context,
             baseline,
@@ -840,9 +879,9 @@ def run_apply_step(
         if call_error is not None:
             raise HookError(f"Apply step failed in isolated staging: {call_error}") from call_error
         if result is None:
-            raise HookError("Apply step failed without an OpenCode result")
-        if result.return_code != 0:
-            details = result.stderr.strip() or result.stdout.strip() or f"exit code {result.return_code}"
+            raise HookError("Apply step failed without a runner result")
+        if result.returncode != 0:
+            details = result.stderr.strip() or result.stdout.strip() or f"exit code {result.returncode}"
             raise HookError(f"Apply step failed in isolated staging: {details}")
         propagated_expected = _propagate_staging_changes(
             context,