ai-push-hooks 0.1.0

package/src/ai_push_hooks/executors/llm.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import shutil
+from dataclasses import dataclass
+from typing import Any
+
+from ..types import HookError, RuntimeContext, StepConfig
+from .exec import ensure_dir, extract_pr_url, resolve_storage_path, run_command
+
+
+@dataclass
+class OpenCodeRunResult:
+    output_text: str
+    session_id: str | None
+    stdout: str
+    stderr: str
+    return_code: int
+
+
+def sanitize_filename_component(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", value.strip())
+    return cleaned.strip("-") or "value"
+
+
+def prefer_opencode_cli_candidate(candidate: str) -> str:
+    path = pathlib.Path(candidate)
+    if path.name != "opencode":
+        return candidate
+    sibling = path.with_name("opencode-cli")
+    if sibling.exists() and os.access(sibling, os.X_OK):
+        return str(sibling)
+    return candidate
+
+
+def resolve_opencode_executable() -> str:
+    cli_path = shutil.which("opencode-cli")
+    if cli_path:
+        return cli_path
+    opencode_path = shutil.which("opencode")
+    if opencode_path:
+        return prefer_opencode_cli_candidate(opencode_path)
+    raise HookError("opencode is required but not installed")
+
+
+def parse_opencode_json_run_output(raw: str) -> tuple[str | None, str]:
+    session_id: str | None = None
+    parts: list[str] = []
+    for line in raw.splitlines():
+        payload = line.strip()
+        if not payload:
+            continue
+        try:
+            event = json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        if session_id is None and isinstance(event.get("sessionID"), str):
+            session_id = str(event["sessionID"]).strip()
+        if event.get("type") != "text":
+            continue
+        part = event.get("part")
+        if isinstance(part, dict) and isinstance(part.get("text"), str) and part["text"].strip():
+            parts.append(part["text"])
+    return session_id, "\n".join(parts).strip()
+
+
+def extract_json_array(text: str) -> list[Any]:
+    start = text.find("[")
+    end = text.rfind("]")
+    if start < 0 or end < start:
+        raise HookError("Could not find JSON array in model output")
+    try:
+        payload = json.loads(text[start : end + 1])
+    except json.JSONDecodeError as exc:
+        raise HookError(f"Failed to parse JSON array from model output: {exc}") from exc
+    if not isinstance(payload, list):
+        raise HookError("Model output JSON is not an array")
+    return payload
+
+
+def extract_json_object(text: str) -> dict[str, Any]:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start < 0 or end < start:
+        raise HookError("Could not find JSON object in model output")
+    try:
+        payload = json.loads(text[start : end + 1])
+    except json.JSONDecodeError as exc:
+        raise HookError(f"Failed to parse JSON object from model output: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise HookError("Model output JSON is not an object")
+    return payload
+
+
+def validate_schema(schema: str | None, payload: Any) -> Any:
+    if schema is None:
+        return payload
+    if schema == "string_array":
+        if not isinstance(payload, list) or not all(isinstance(item, str) for item in payload):
+            raise HookError("Expected schema string_array")
+        return payload
+    if schema == "docs_issue_array":
+        if not isinstance(payload, list):
+            raise HookError("Expected schema docs_issue_array")
+        for item in payload:
+            if not isinstance(item, dict):
+                raise HookError("docs_issue_array items must be objects")
+            if not str(item.get("file", "")).strip() or not str(item.get("description", "")).strip():
+                raise HookError("docs_issue_array items require file and description")
+        return payload
+    if schema == "beads_alignment_result":
+        if not isinstance(payload, dict):
+            raise HookError("Expected schema beads_alignment_result")
+        commands = payload.get("commands", [])
+        if commands is not None and (
+            not isinstance(commands, list) or not all(isinstance(item, str) for item in commands)
+        ):
+            raise HookError("beads_alignment_result.commands must be an array of strings")
+        return payload
+    if schema == "pr_create_payload":
+        if not isinstance(payload, dict):
+            raise HookError("Expected schema pr_create_payload")
+        return payload
+    raise HookError(f"Unsupported schema: {schema}")
+
+
+def _transcript_dir(context: RuntimeContext) -> pathlib.Path | None:
+    if not context.config.logging.capture_llm_transcript:
+        return None
+    return ensure_dir(
+        resolve_storage_path(
+            context.repo_root,
+            context.git_dir,
+            context.config.logging.transcript_dir,
+        )
+    )
+
+
+def export_opencode_session_json(
+    context: RuntimeContext,
+    session_id: str,
+    export_path: pathlib.Path,
+) -> bool:
+    completed = run_command(
+        [context.opencode_executable or resolve_opencode_executable(), "export", session_id],
+        cwd=context.repo_root,
+        timeout=context.config.llm.timeout_seconds,
+        check=False,
+    )
+    if completed.returncode != 0:
+        return False
+    payload = (completed.stdout or "").strip()
+    if not payload:
+        return False
+    export_path.write_text(payload + "\n", encoding="utf-8")
+    return True
+
+
+def delete_opencode_session(context: RuntimeContext, session_id: str) -> None:
+    run_command(
+        [context.opencode_executable or resolve_opencode_executable(), "session", "delete", session_id],
+        cwd=context.repo_root,
+        timeout=context.config.llm.timeout_seconds,
+        check=False,
+    )
+
+
+def finalize_opencode_session(context: RuntimeContext, stage_name: str, session_id: str | None) -> None:
+    if not session_id:
+        return
+    transcript_dir = _transcript_dir(context)
+    if transcript_dir is not None:
+        export_name = (
+            f"{sanitize_filename_component(context.run_id)}-"
+            f"{sanitize_filename_component(stage_name)}-"
+            f"{sanitize_filename_component(session_id)}.json"
+        )
+        export_opencode_session_json(context, session_id, transcript_dir / export_name)
+    if context.config.llm.delete_session_after_run:
+        delete_opencode_session(context, session_id)
+
+
+def call_opencode(
+    context: RuntimeContext,
+    stage_name: str,
+    purpose: str,
+    prompt: str,
+    files: list[pathlib.Path],
+    attempt: int | None = None,
+    total_attempts: int | None = None,
+    existing_session_id: str | None = None,
+) -> OpenCodeRunResult:
+    executable = context.opencode_executable or resolve_opencode_executable()
+    context.logger.llm_call(stage_name, purpose, context.config.llm.model, attempt, total_attempts)
+    cmd = [
+        executable,
+        "run",
+        "--format",
+        "json",
+        "--model",
+        context.config.llm.model,
+    ]
+    if context.config.llm.variant:
+        cmd.extend(["--variant", context.config.llm.variant])
+    if existing_session_id:
+        cmd.extend(["--session", existing_session_id])
+    else:
+        cmd.extend(["--title", f"{context.config.llm.session_title_prefix} {context.run_id} {stage_name}"])
+    for file_path in files:
+        cmd.extend(["--file", str(file_path)])
+    cmd.extend(["--", prompt])
+
+    completed = run_command(
+        cmd,
+        cwd=context.repo_root,
+        timeout=context.config.llm.timeout_seconds,
+        check=False,
+        env={"OPENCODE_SERVER_PASSWORD": None},
+    )
+    session_id, text_output = parse_opencode_json_run_output(completed.stdout or "")
+    stdout = completed.stdout or ""
+    stderr = completed.stderr or ""
+    if context.config.logging.print_llm_output and stdout.strip():
+        print(stdout)
+    return OpenCodeRunResult(
+        output_text=text_output if text_output else stdout.strip(),
+        session_id=session_id or existing_session_id,
+        stdout=stdout,
+        stderr=stderr,
+        return_code=completed.returncode,
+    )
+
+
+def run_llm_step(
+    context: RuntimeContext,
+    step: StepConfig,
+    prompt: str,
+    input_paths: list[pathlib.Path],
+    stage_name: str,
+) -> Any:
+    total_attempts = context.config.llm.json_max_retries + 1
+    session_id: str | None = None
+    prompt_text = prompt
+    last_error = ""
+    last_output = ""
+    wants_json = bool(step.schema)
+    for attempt in range(1, total_attempts + 1):
+        result = call_opencode(
+            context,
+            stage_name=stage_name,
+            purpose=f"{step.type}:{step.id}",
+            prompt=prompt_text,
+            files=input_paths,
+            attempt=attempt,
+            total_attempts=total_attempts,
+            existing_session_id=session_id,
+        )
+        session_id = result.session_id
+        if result.return_code != 0:
+            finalize_opencode_session(context, stage_name, session_id)
+            details = result.stderr.strip() or result.stdout.strip() or f"exit code {result.return_code}"
+            raise HookError(f"OpenCode command failed: {details}")
+        try:
+            if not wants_json:
+                finalize_opencode_session(context, stage_name, session_id)
+                return result.output_text
+            if step.schema == "string_array":
+                payload = extract_json_array(result.output_text)
+            else:
+                payload = extract_json_object(result.output_text)
+            finalize_opencode_session(context, stage_name, session_id)
+            return validate_schema(step.schema, payload)
+        except HookError as exc:
+            last_error = str(exc)
+            last_output = result.output_text
+            if attempt >= total_attempts:
+                break
+            snippet = last_output[: context.config.llm.invalid_json_feedback_max_chars]
+            if step.schema == "string_array":
+                suffix = "Return ONLY valid JSON array."
+            else:
+                suffix = "Return ONLY valid JSON object."
+            prompt_text = (
+                prompt
+                + "\n\nIMPORTANT: Your previous response was invalid JSON and could not be parsed.\n"
+                + f"Parse error: {last_error}\n"
+                + suffix
+                + "\nPrevious invalid output:\n```text\n"
+                + snippet
+                + "\n```"
+            )
+            if context.config.llm.json_retry_new_session:
+                session_id = None
+            pr_url = extract_pr_url(last_output)
+            if pr_url:
+                context.logger.info(
+                    "llm.invalid_json_pr_url_hint",
+                    "Detected PR URL in invalid JSON output",
+                    stage_name=stage_name,
+                    url=pr_url,
+                )
+    finalize_opencode_session(context, stage_name, session_id)
+    raise HookError(f"Model failed to return valid JSON for {stage_name}: {last_error}. {last_output[:400]}")

package/src/ai_push_hooks/hook.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+from typing import Sequence
+
+from .artifacts import ArtifactStore, generate_run_id
+from .config import load_config
+from .engine import WorkflowEngine
+from .executors.exec import (
+    collect_changed_files,
+    collect_diff,
+    collect_ranges_from_stdin,
+    current_branch,
+    ensure_dir,
+    git,
+    resolve_git_dir,
+    resolve_repo_root,
+    resolve_storage_path,
+    should_skip_for_sync_branch,
+)
+from .executors.llm import resolve_opencode_executable
+from .types import HookConfig, HookError, HookLogger, RuntimeContext
+
+
+def _build_logger(repo_root: pathlib.Path, git_dir: pathlib.Path, config: HookConfig) -> HookLogger:
+    jsonl_path = None
+    if config.logging.jsonl:
+        log_dir = ensure_dir(resolve_storage_path(repo_root, git_dir, config.logging.dir))
+        if log_dir is not None:
+            jsonl_path = log_dir / "hook.jsonl"
+    return HookLogger(jsonl_path=jsonl_path, console_level=config.logging.level)
+
+
+def _write_summary(context: RuntimeContext, result: dict[str, object]) -> None:
+    summary_dir = ensure_dir(
+        resolve_storage_path(context.repo_root, context.git_dir, context.config.logging.summary_dir)
+    )
+    if summary_dir is None:
+        return
+    summary_path = summary_dir / f"{context.run_id}.json"
+    summary_path.write_text(json.dumps(result, ensure_ascii=True, indent=2) + "\n", encoding="utf-8")
+
+
+def _assert_clean_worktree(repo_root: pathlib.Path) -> None:
+    status = git(repo_root, ["status", "--short"], check=False).strip()
+    if status:
+        raise HookError("Hook requires a clean worktree but local changes are present")
+
+
+def run_hook(
+    remote_name: str = "",
+    remote_url: str = "",
+    stdin_lines: Sequence[str] | None = None,
+    cwd: pathlib.Path | None = None,
+) -> int:
+    current_dir = cwd or pathlib.Path.cwd()
+    repo_root = resolve_repo_root(current_dir)
+    git_dir = resolve_git_dir(repo_root)
+    config, _config_path = load_config(repo_root)
+    logger = _build_logger(repo_root, git_dir, config)
+
+    if not config.general.enabled:
+        logger.status("hook.disabled", "AI push hooks disabled")
+        return 0
+    if config.general.require_clean_worktree:
+        _assert_clean_worktree(repo_root)
+    if config.general.skip_on_sync_branch:
+        skip_sync, reason = should_skip_for_sync_branch(repo_root)
+        if skip_sync:
+            logger.status("hook.skip_sync_branch", f"Skipping AI push hooks: {reason}")
+            return 0
+
+    actual_stdin = list(stdin_lines) if stdin_lines is not None else [line.rstrip("\n") for line in sys.stdin]
+    ranges = collect_ranges_from_stdin(repo_root, remote_name or "origin", actual_stdin)
+    changed_files = collect_changed_files(repo_root, ranges) if ranges else []
+    diff_text = collect_diff(repo_root, ranges, config.llm.max_diff_bytes) if ranges else ""
+    run_id = generate_run_id()
+    run_dir = resolve_storage_path(repo_root, git_dir, f".git/ai-push-hooks/runs/{run_id}")
+
+    opencode_executable = None
+    if any(
+        step.type in {"llm", "apply"}
+        for module in config.modules.values()
+        for step in module.steps
+        if module.enabled
+    ):
+        opencode_executable = resolve_opencode_executable()
+
+    context = RuntimeContext(
+        repo_root=repo_root,
+        git_dir=git_dir,
+        config=config,
+        logger=logger,
+        remote_name=remote_name or "origin",
+        remote_url=remote_url,
+        stdin_lines=actual_stdin,
+        run_id=run_id,
+        run_dir=run_dir,
+        opencode_executable=opencode_executable,
+        cache={
+            "ranges": ranges,
+            "changed_files": changed_files,
+            "diff_text": diff_text,
+            "branch_name": current_branch(repo_root),
+            "sync_branch": "beads-sync",
+        },
+    )
+    logger.status(
+        "hook.start",
+        "Starting AI push hooks workflow",
+        branch=context.cache["branch_name"],
+        changed_files=len(changed_files),
+        ranges=ranges,
+    )
+    engine = WorkflowEngine(context=context, artifacts=ArtifactStore(run_dir))
+    try:
+        workflow_result = engine.run()
+        logger.llm_summary()
+        _write_summary(context, {"run_dir": str(workflow_result.run_dir), "modules": workflow_result.modules})
+        logger.status("hook.complete", "AI push hooks workflow completed", run_dir=str(workflow_result.run_dir))
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        message = str(exc).strip() or exc.__class__.__name__
+        logger.error("hook.failed", "AI push hooks workflow failed", error=message)
+        if config.general.allow_push_on_error:
+            logger.warn("hook.fail_open", "Allowing push because allow_push_on_error=true", error=message)
+            return 0
+        raise

package/src/ai_push_hooks/modules/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .beads import collect_beads_status_context
+from .docs import collect_docs_context
+from .pr import collect_pr_context
+
+COLLECTORS = {
+    "docs_context": collect_docs_context,
+    "beads_status_context": collect_beads_status_context,
+    "pr_context": collect_pr_context,
+}

package/src/ai_push_hooks/modules/beads.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..executors.exec import collect_commit_messages_for_ranges, current_branch, is_feature_branch
+from ..types import CollectorResult, RuntimeContext
+
+
+def collect_beads_status_context(context: RuntimeContext, state: Any) -> CollectorResult:
+    branch_name = current_branch(context.repo_root)
+    sync_branch = context.cache.get("sync_branch", "beads-sync")
+    if not branch_name or branch_name in {"HEAD", "main", sync_branch} or not is_feature_branch(branch_name):
+        return CollectorResult(
+            artifacts={"branch-context.txt": f"branch={branch_name}\n"},
+            skip_module=True,
+            skip_reason="branch does not require beads alignment",
+        )
+
+    ranges = context.cache.get("ranges", [])
+    changed_files = context.cache.get("changed_files", [])
+    diff_text = context.cache.get("diff_text", "")
+    commits = collect_commit_messages_for_ranges(context.repo_root, ranges) if ranges else []
+    report_file = "BEADS_STATUS_ACTION_REQUIRED.md"
+    commit_lines = []
+    for commit in commits:
+        commit_lines.append(f"--- {commit['hash']}")
+        commit_lines.append(f"subject: {commit['subject']}")
+        if commit["body"]:
+            commit_lines.append("body:")
+            commit_lines.append(commit["body"])
+        commit_lines.append("")
+    return CollectorResult(
+        artifacts={
+            "branch-context.txt": "\n".join(
+                [
+                    f"branch={branch_name}",
+                    f"ranges={','.join(ranges)}",
+                    f"report_file={report_file}",
+                ]
+            )
+            + "\n",
+            "changed-files.txt": "\n".join(changed_files) + ("\n" if changed_files else ""),
+            "push.diff": diff_text + ("\n" if diff_text and not diff_text.endswith("\n") else ""),
+            "commits.txt": "\n".join(commit_lines).strip() + ("\n" if commit_lines else ""),
+        }
+    )

package/src/ai_push_hooks/modules/docs.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import pathlib
+import re
+import shutil
+from pathlib import PurePosixPath
+from typing import Any
+
+from ..types import CollectorResult, RuntimeContext
+from ..executors.exec import collect_commit_messages_for_ranges, git, run_command
+
+DOC_INCLUDE_PATTERNS = ("README.md", "docs/**/*.md")
+DOC_IGNORE_PATTERNS = ("docs/archive/**",)
+
+
+def _path_matches(path: str, patterns: tuple[str, ...]) -> bool:
+    pure = PurePosixPath(path)
+    return any(pure.match(pattern) for pattern in patterns)
+
+
+def _expand_doc_files(repo_root: pathlib.Path) -> list[pathlib.Path]:
+    files: list[pathlib.Path] = []
+    for candidate in repo_root.rglob("*.md"):
+        relative = candidate.relative_to(repo_root).as_posix()
+        if not _path_matches(relative, DOC_INCLUDE_PATTERNS):
+            continue
+        if _path_matches(relative, DOC_IGNORE_PATTERNS):
+            continue
+        files.append(candidate)
+    return sorted(files)
+
+
+def _deterministic_seed_queries(diff_text: str, changed_files: list[str]) -> list[str]:
+    stopwords = {
+        "const",
+        "return",
+        "value",
+        "false",
+        "true",
+        "string",
+        "number",
+        "object",
+        "class",
+        "function",
+        "public",
+        "private",
+        "static",
+        "async",
+        "await",
+        "import",
+        "export",
+        "from",
+        "default",
+        "docs",
+        "readme",
+    }
+    seeds: list[str] = []
+    for changed in changed_files:
+        pure = PurePosixPath(changed)
+        if len(pure.stem) >= 4:
+            seeds.append(pure.stem)
+        for segment in pure.parts:
+            if len(segment) >= 4 and segment not in {"docs", "src", "tests"}:
+                seeds.append(segment)
+    seeds.extend(re.findall(r"\b[A-Za-z][A-Za-z0-9_.-]{3,}\b", diff_text))
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for seed in seeds:
+        clean = seed.strip()
+        if clean.lower() in stopwords or clean in seen:
+            continue
+        seen.add(clean)
+        deduped.append(clean)
+    return deduped[:20]
+
+
+def _parse_rg_line(line: str) -> tuple[str, int, str] | None:
+    match = re.match(r"^(.*?):(\d+):(.*)$", line)
+    if not match:
+        return None
+    return match.group(1), int(match.group(2)), match.group(3)
+
+
+def _search_docs_context(repo_root: pathlib.Path, doc_files: list[pathlib.Path], queries: list[str]) -> str:
+    if not doc_files:
+        return ""
+    if shutil.which("rg") is None or not queries:
+        snippets: list[str] = []
+        budget = 32000
+        for path in doc_files[:8]:
+            relative = path.relative_to(repo_root).as_posix()
+            content = path.read_text(encoding="utf-8")[:4000]
+            block = f"--- {relative} ---\n{content}"
+            if len("\n\n".join(snippets)) + len(block) > budget:
+                break
+            snippets.append(block)
+        return "\n\n".join(snippets)
+
+    files = [str(path) for path in doc_files]
+    chunks: list[str] = []
+    seen: set[tuple[str, int]] = set()
+    for query in queries:
+        completed = run_command(
+            ["rg", "--line-number", "--no-heading", "--color=never", "-C", "2", "--", query, *files],
+            cwd=repo_root,
+            check=False,
+        )
+        if completed.returncode not in {0, 1}:
+            continue
+        for line in completed.stdout.splitlines():
+            parsed = _parse_rg_line(line)
+            if not parsed:
+                continue
+            file_name, line_number, content = parsed
+            key = (file_name, line_number)
+            if key in seen:
+                continue
+            seen.add(key)
+            chunks.append(f"{file_name}:{line_number}: {content}")
+            if sum(len(chunk) for chunk in chunks) > 32000:
+                return "\n".join(chunks)
+    return "\n".join(chunks)
+
+
+def collect_docs_context(context: RuntimeContext, _state: Any) -> CollectorResult:
+    ranges = context.cache.get("ranges", [])
+    changed_files = context.cache.get("changed_files", [])
+    diff_text = context.cache.get("diff_text", "")
+    doc_files = _expand_doc_files(context.repo_root)
+    docs_context = _search_docs_context(
+        context.repo_root,
+        doc_files,
+        _deterministic_seed_queries(diff_text, changed_files),
+    )
+    recent_commits = git(
+        context.repo_root,
+        ["log", "--oneline", "-n", "20", "--", "README.md", "docs"],
+        check=False,
+    )
+    commits = collect_commit_messages_for_ranges(context.repo_root, ranges) if ranges else []
+    commit_lines = []
+    for commit in commits:
+        commit_lines.append(f"--- {commit['hash']}")
+        commit_lines.append(f"subject: {commit['subject']}")
+        if commit["body"]:
+            commit_lines.append("body:")
+            commit_lines.append(commit["body"])
+        commit_lines.append("")
+    return CollectorResult(
+        artifacts={
+            "changed-files.txt": "\n".join(changed_files) + ("\n" if changed_files else ""),
+            "push.diff": diff_text + ("\n" if diff_text and not diff_text.endswith("\n") else ""),
+            "docs-inventory.txt": "\n".join(path.relative_to(context.repo_root).as_posix() for path in doc_files)
+            + ("\n" if doc_files else ""),
+            "docs-context.txt": docs_context + ("\n" if docs_context else ""),
+            "recent-commits.txt": recent_commits + ("\n" if recent_commits and not recent_commits.endswith("\n") else ""),
+            "commits.txt": "\n".join(commit_lines).strip() + ("\n" if commit_lines else ""),
+        }
+    )