ai-push-hooks 0.1.0

package/src/ai_push_hooks/modules/pr.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..executors.exec import (
+    collect_commit_messages_for_ranges,
+    current_branch,
+    env_bool,
+    is_feature_branch,
+    lookup_open_pr_url,
+)
+from ..types import CollectorResult, RuntimeContext
+
+
+def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
+    branch_name = current_branch(context.repo_root)
+    flag_env = ""
+    for step in state.module.steps:
+        if step.when_env:
+            flag_env = step.when_env
+            break
+    if flag_env and env_bool(flag_env) is not True:
+        return CollectorResult(
+            artifacts={"pr-context.txt": f"branch={branch_name}\nflag_env={flag_env}\n"},
+            skip_module=True,
+            skip_reason="PR create env flag is not enabled",
+        )
+    if not branch_name or branch_name in {"HEAD", "main"} or not is_feature_branch(branch_name):
+        return CollectorResult(
+            artifacts={"pr-context.txt": f"branch={branch_name}\n"},
+            skip_module=True,
+            skip_reason="branch does not require PR creation",
+        )
+    existing_pr_url = ""
+    try:
+        existing_pr_url = lookup_open_pr_url(context.repo_root, branch_name)
+    except Exception:  # noqa: BLE001
+        existing_pr_url = ""
+    if existing_pr_url:
+        return CollectorResult(
+            artifacts={"pr-context.txt": f"branch={branch_name}\nexisting_pr_url={existing_pr_url}\n"},
+            skip_module=True,
+            skip_reason="open PR already exists",
+            metadata={"existing_pr_url": existing_pr_url},
+        )
+
+    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 []
+    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={
+            "pr-context.txt": "\n".join(
+                [
+                    f"branch={branch_name}",
+                    f"base_branch=main",
+                    f"remote_name={context.remote_name or 'origin'}",
+                ]
+            )
+            + "\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/prompts_builtin.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+DOCS_QUERY_PROMPT = """Given the attached diff and changed file list, output a JSON array of concise documentation search queries.
+
+Requirements:
+- Return JSON only.
+- Prefer exact config keys, commands, flags, function names, and domain terms.
+- Keep the list concise and unique.
+"""
+
+DOCS_ANALYSIS_PROMPT = """Review the attached diff and documentation context. Return JSON issues only for factual documentation drift caused by the code changes.
+
+Each item must include:
+- file
+- line
+- description
+- doc_excerpt
+- suggested_fix
+
+Return [] when the docs remain factually correct.
+"""
+
+DOCS_APPLY_PROMPT = """Apply the minimum Markdown documentation changes required to fix the detected factual drift.
+
+Rules:
+1. Modify only README.md and docs/**/*.md files allowed by this step.
+2. Keep edits minimal and factual.
+3. Update docs index files when a referenced Markdown file is added or renamed.
+4. If no edits are required, do not modify files.
+"""
+
+BEADS_PLAN_PROMPT = """Check the attached branch context and output a JSON object describing Beads alignment work.
+
+Return keys:
+- commands: array of non-interactive br command strings to run
+- unresolved: boolean
+- report_markdown: markdown string or empty
+
+Return JSON only.
+"""
+
+PR_COMPOSE_PROMPT = """Draft a pull request payload from the attached branch context.
+
+Return a JSON object with:
+- title
+- body
+- base_branch
+- head_branch
+- draft
+
+Return JSON only.
+"""
+
+BUILTIN_PROMPTS = {
+    "docs-query-basic": DOCS_QUERY_PROMPT,
+    "docs-analysis-basic": DOCS_ANALYSIS_PROMPT,
+    "docs-apply-basic": DOCS_APPLY_PROMPT,
+    "beads-plan-basic": BEADS_PLAN_PROMPT,
+    "pr-compose-basic": PR_COMPOSE_PROMPT,
+}
+
+MINIMAL_DOCS_TEMPLATE = '''[general]
+enabled = true
+allow_push_on_error = false
+require_clean_worktree = false
+skip_on_sync_branch = true
+
+[llm]
+runner = "opencode"
+model = "openai/gpt-5.3-codex-spark"
+variant = ""
+timeout_seconds = 800
+max_parallel = 2
+json_max_retries = 2
+invalid_json_feedback_max_chars = 6000
+json_retry_new_session = true
+delete_session_after_run = true
+
+[logging]
+level = "status"
+jsonl = true
+dir = ".git/ai-push-hooks/logs"
+capture_llm_transcript = true
+transcript_dir = ".git/ai-push-hooks/transcripts"
+summary_dir = ".git/ai-push-hooks/summaries"
+
+[workflow]
+modules = ["docs"]
+
+[modules.docs]
+enabled = true
+
+[[modules.docs.steps]]
+id = "collect"
+type = "collect"
+collector = "docs_context"
+
+[[modules.docs.steps]]
+id = "query"
+type = "llm"
+prompt = """
+Given the attached diff and changed file list, output a JSON array of concise
+documentation search queries. Return JSON only.
+"""
+inputs = ["collect/push.diff", "collect/changed-files.txt"]
+output = "queries.json"
+schema = "string_array"
+
+[[modules.docs.steps]]
+id = "analyze"
+type = "llm"
+prompt = """
+Review the diff and matched docs excerpts. Return JSON issues only for factual
+documentation drift caused by the code changes.
+"""
+inputs = ["collect/push.diff", "collect/docs-context.txt", "query/queries.json", "collect/recent-commits.txt"]
+output = "issues.json"
+schema = "docs_issue_array"
+
+[[modules.docs.steps]]
+id = "apply"
+type = "apply"
+prompt = """
+Apply the minimum Markdown documentation changes required to fix the detected
+factual drift. Modify only files allowed by the step.
+"""
+inputs = ["collect/push.diff", "collect/docs-context.txt", "analyze/issues.json"]
+allow_paths = ["README.md", "docs/**/*.md"]
+
+[[modules.docs.steps]]
+id = "assert"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+'''

package/src/ai_push_hooks/types.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import json
+import pathlib
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+READ_ONLY_STEP_TYPES = frozenset({"collect", "llm"})
+PROMPTABLE_STEP_TYPES = frozenset({"llm", "apply"})
+SUPPORTED_STEP_TYPES = frozenset({"collect", "llm", "apply", "exec", "assert"})
+FEATURE_BRANCH_PREFIXES = ("feat/", "feature/")
+
+
+class HookError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class GeneralConfig:
+    enabled: bool = True
+    allow_push_on_error: bool = False
+    require_clean_worktree: bool = False
+    skip_on_sync_branch: bool = True
+
+
+@dataclass(frozen=True)
+class LlmConfig:
+    runner: str = "opencode"
+    model: str = "openai/gpt-5.3-codex-spark"
+    variant: str = ""
+    timeout_seconds: int = 800
+    max_parallel: int = 2
+    json_max_retries: int = 2
+    invalid_json_feedback_max_chars: int = 6000
+    json_retry_new_session: bool = True
+    delete_session_after_run: bool = True
+    max_diff_bytes: int = 180000
+    session_title_prefix: str = "ai-push-hooks"
+
+
+@dataclass(frozen=True)
+class LoggingConfig:
+    level: str = "status"
+    jsonl: bool = True
+    dir: str = ".git/ai-push-hooks/logs"
+    capture_llm_transcript: bool = True
+    transcript_dir: str = ".git/ai-push-hooks/transcripts"
+    summary_dir: str = ".git/ai-push-hooks/summaries"
+    print_llm_output: bool = False
+
+
+@dataclass(frozen=True)
+class StepConfig:
+    id: str
+    type: str
+    inputs: tuple[str, ...] = ()
+    output: str | None = None
+    schema: str | None = None
+    prompt: str | None = None
+    prompt_file: str | None = None
+    fallback_prompt_id: str | None = None
+    collector: str | None = None
+    allow_paths: tuple[str, ...] = ()
+    executor: str | None = None
+    assertion: str | None = None
+    when_env: str | None = None
+
+    @property
+    def is_read_only(self) -> bool:
+        return self.type in READ_ONLY_STEP_TYPES
+
+    @property
+    def is_promptable(self) -> bool:
+        return self.type in PROMPTABLE_STEP_TYPES
+
+
+@dataclass(frozen=True)
+class ModuleConfig:
+    id: str
+    enabled: bool
+    steps: tuple[StepConfig, ...]
+
+
+@dataclass(frozen=True)
+class WorkflowConfig:
+    modules: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class HookConfig:
+    general: GeneralConfig
+    llm: LlmConfig
+    logging: LoggingConfig
+    workflow: WorkflowConfig
+    modules: dict[str, ModuleConfig]
+
+
+@dataclass
+class CollectorResult:
+    artifacts: dict[str, str | dict[str, Any] | list[Any]] = field(default_factory=dict)
+    skip_module: bool = False
+    skip_reason: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class StepResult:
+    status: str = "completed"
+    artifacts: dict[str, pathlib.Path] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    message: str = ""
+
+
+@dataclass
+class ModuleRuntimeState:
+    module: ModuleConfig
+    step_index: int = 0
+    status: str = "pending"
+    active_step_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    artifacts: dict[str, pathlib.Path] = field(default_factory=dict)
+    error: str | None = None
+
+    @property
+    def next_step(self) -> StepConfig | None:
+        if self.step_index >= len(self.module.steps):
+            return None
+        return self.module.steps[self.step_index]
+
+
+@dataclass
+class RuntimeContext:
+    repo_root: pathlib.Path
+    git_dir: pathlib.Path
+    config: HookConfig
+    logger: "HookLogger"
+    remote_name: str
+    remote_url: str
+    stdin_lines: list[str]
+    run_id: str
+    run_dir: pathlib.Path
+    opencode_executable: str | None = None
+    cache: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class WorkflowRunResult:
+    run_dir: pathlib.Path
+    modules: dict[str, str]
+
+
+@dataclass
+class HookLogger:
+    jsonl_path: pathlib.Path | None
+    console_level: str = "status"
+    jsonl_write_failed: bool = False
+    llm_calls: list[dict[str, Any]] = field(default_factory=list)
+
+    _verbosity_order = {"status": 0, "info": 1, "debug": 2}
+
+    def _level_is_enabled(self, level: str) -> bool:
+        if level in {"warn", "error"}:
+            return True
+        configured = self._verbosity_order.get(self.console_level, 0)
+        required = self._verbosity_order.get(level, 0)
+        return configured >= required
+
+    def _emit(self, level: str, event: str, message: str, **fields: Any) -> None:
+        if not self._level_is_enabled(level):
+            return
+        stamp = datetime.now(timezone.utc).isoformat()
+        sys.stderr.write(f"[ai-push-hooks] {message}\n")
+        if self.jsonl_path is None or self.jsonl_write_failed:
+            return
+        record = {"ts": stamp, "level": level, "event": event, "message": message, **fields}
+        try:
+            with self.jsonl_path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(record, ensure_ascii=True) + "\n")
+        except Exception as exc:  # noqa: BLE001
+            self.jsonl_write_failed = True
+            sys.stderr.write(f"[ai-push-hooks] JSONL logging disabled after write failure: {exc}\n")
+
+    def debug(self, event: str, message: str, **fields: Any) -> None:
+        self._emit("debug", event, message, **fields)
+
+    def info(self, event: str, message: str, **fields: Any) -> None:
+        self._emit("info", event, message, **fields)
+
+    def status(self, event: str, message: str, **fields: Any) -> None:
+        self._emit("status", event, message, **fields)
+
+    def warn(self, event: str, message: str, **fields: Any) -> None:
+        self._emit("warn", event, message, **fields)
+
+    def error(self, event: str, message: str, **fields: Any) -> None:
+        self._emit("error", event, message, **fields)
+
+    def llm_call(
+        self,
+        stage_name: str,
+        purpose: str,
+        model: str,
+        attempt: int | None = None,
+        total_attempts: int | None = None,
+    ) -> None:
+        call_number = len(self.llm_calls) + 1
+        record: dict[str, Any] = {
+            "call_number": call_number,
+            "stage_name": stage_name,
+            "purpose": purpose,
+            "model": model,
+        }
+        if attempt is not None:
+            record["attempt"] = attempt
+        if total_attempts is not None:
+            record["total_attempts"] = total_attempts
+        self.llm_calls.append(record)
+        self.status(
+            "llm.call",
+            f"LLM call #{call_number}: {stage_name} - {purpose}",
+            **record,
+        )
+
+    def llm_summary(self) -> None:
+        stage_counts: dict[str, int] = {}
+        for call in self.llm_calls:
+            stage_name = str(call.get("stage_name", "")).strip() or "<unknown>"
+            stage_counts[stage_name] = stage_counts.get(stage_name, 0) + 1
+        self.status(
+            "llm.calls_total",
+            f"Total LLM calls this run: {len(self.llm_calls)}",
+            total_calls=len(self.llm_calls),
+            stage_counts=stage_counts,
+        )