ai-push-hooks 0.1.18 → 0.1.19

package/README.md

@@ -6,6 +6,23 @@ It runs module-based steps (collect, LLM, apply, exec, assert) before push so yo
 
 ## Install
 
+### Mise (recommended for repository hooks)
+
+Pin the currently published release in the consuming repository:
+
+```bash
+mise use npm:ai-push-hooks@0.1.19
+```
+
+This adds the following project-level tool entry to `mise.toml` and installs it:
+
+```toml
+[tools]
+"npm:ai-push-hooks" = "0.1.19"
+```
+
+After checking in `mise.toml`, other contributors can install the pinned tool with `mise install`.
+
 ### Python
 
 ```bash
@@ -30,36 +47,52 @@ Requirements:
 
 ## Quick start
 
-1. Install by following the steps above.
+1. Add the pinned Mise tool by following [Mise installation](#mise-recommended-for-repository-hooks) above.
 2. Generate a starter config:
 
-   Python tool install (`uv tool` / `pipx`):
+   ```bash
+   mise exec -- ai-push-hooks init --template minimal-docs
+   ```
+
+3. Add the single repository-owned runner at `scripts/hooks/pre-push-runner.sh`:
 
    ```bash
-   ai-push-hooks init --template minimal-docs
+   #!/usr/bin/env bash
+   set -euo pipefail
+
+   remote_name="${1:-}"
+   remote_url="${2:-}"
+   push_stdin="$(mktemp)"
+   trap 'rm -f "$push_stdin"' EXIT
+   cat >"$push_stdin"
+
+   # Run deterministic quality checks first. Replace these with the repository's checks.
+   npm run lint
+   npm test
+
+   # Keep ai-push-hooks as the single final phase and replay Git's pre-push input.
+   mise exec -- ai-push-hooks hook "$remote_name" "$remote_url" <"$push_stdin"
    ```
 
-   npm/pnpm local install:
+   Make the runner executable:
 
    ```bash
-   npx ai-push-hooks init --template minimal-docs
-   # or
-   pnpm exec ai-push-hooks init --template minimal-docs
+   chmod +x scripts/hooks/pre-push-runner.sh
    ```
 
-3. Configure modules and steps in [Configuration reference](#configuration-reference).
-4. Wire it into your pre-push hook manager. Lefthook example:
+4. Configure Lefthook to invoke only that runner in `lefthook.yml`:
 
    ```yaml
    pre-push:
      commands:
-       ai-push-hooks:
-         run: ai-push-hooks hook {1} {2}
+       repository-pre-push:
+         run: bash scripts/hooks/pre-push-runner.sh {1} {2}
+         use_stdin: true
    ```
 
-   In Lefthook, `{1}` is the remote name and `{2}` is the remote URL from Git's `pre-push` hook args.
-
-5. Push as usual. The workflow runs automatically before push completes.
+   `use_stdin: true` forwards Git's ref-update stream to the runner. The runner captures it before quality checks consume or close standard input, then replays it to `ai-push-hooks hook`. Lefthook's `{1}` and `{2}` are the remote name and remote URL. Keep all repository checks in this runner and keep the one `ai-push-hooks hook` call last so failures propagate and block the push.
+5. Configure modules and steps in [Configuration reference](#configuration-reference).
+6. Push as usual. The workflow runs automatically before push completes.
 
 ## Commands
 
@@ -99,13 +132,14 @@ If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm ex
 | `allow_push_on_error` | bool | `false` | If `true`, push continues even when workflow fails. |
 | `require_clean_worktree` | bool | `false` | If `true`, aborts when local changes exist. |
 | `skip_on_sync_branch` | bool | `true` | If `true`, skips on sync branch/worktree context. |
+| `base_branch` | string | `"main"` | Base branch used for new-branch range fallback and default PR base/context. |
 
 ### `[llm]`
 
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
 | `runner` | string | `"opencode"` | LLM runner label (currently OpenCode flow). |
-| `model` | string | `"openai/gpt-5.3-codex"` | Model passed to OpenCode. |
+| `model` | string | `"openai/gpt-5.5"` | Model passed to OpenCode. |
 | `variant` | string | `""` | Optional OpenCode variant. |
 | `timeout_seconds` | int | `800` | Timeout per LLM invocation and related OpenCode calls. |
 | `max_parallel` | int | `2` | Max concurrent read-only steps (`collect`, `llm`). |
@@ -161,6 +195,8 @@ If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm ex
 
 `llm` and `apply` are promptable step types: at least one of `prompt`, `prompt_file`, or `fallback_prompt_id` must be set.
 
+Artifact references in `inputs` are module-local. Use `<step>/<artifact>` to reference an artifact produced by an earlier step in the same module (for example, `collect/push.diff` or `analyze/issues.json`). Cross-module references such as `docs:collect/push.diff` are not currently supported.
+
 ### Supported handler and schema values
 
 #### Collectors
@@ -214,6 +250,7 @@ Boolean env parsing accepts: `1`, `true`, `yes`, `y`, `on` and `0`, `false`, `no
 | `AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR` | Overrides `general.allow_push_on_error`. |
 | `AI_PUSH_HOOKS_REQUIRE_CLEAN` | Overrides `general.require_clean_worktree`. |
 | `AI_PUSH_HOOKS_ALLOW_DIRTY` | If true, forces `general.require_clean_worktree = false`. |
+| `AI_PUSH_HOOKS_BASE_BRANCH` | Overrides `general.base_branch`. |
 | `AI_PUSH_HOOKS_LOG_LEVEL` | Overrides `logging.level`. |
 | `AI_PUSH_HOOKS_PRINT_LLM_OUTPUT` | Overrides `logging.print_llm_output`. |
 | `AI_PUSH_HOOKS_MODEL` | Overrides `llm.model`. |

package/ai-push-hooks.toml

@@ -3,10 +3,11 @@ enabled = true
 allow_push_on_error = false
 require_clean_worktree = false
 skip_on_sync_branch = true
+base_branch = "main"
 
 [llm]
 runner = "opencode"
-model = "openai/gpt-5.3-codex"
+model = "openai/gpt-5.5"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Modular AI push-hook workflow runner",
   "license": "MIT",
   "repository": {
@@ -11,7 +11,8 @@
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --with pytest pytest tests -q"
+    "test": "uv run --with pytest pytest tests -q",
+    "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
     "bin",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.1.18"
+version = "0.1.19"
 description = "Modular AI push-hook workflow runner"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,6 +21,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Topic :: Software Development :: Version Control :: Git",
 ]
+dependencies = ["tomli>=2.0.0; python_version < '3.11'"]
 
 [project.scripts]
 ai-push-hooks = "ai_push_hooks.cli:main"

package/src/ai_push_hooks/artifacts.py

@@ -63,8 +63,11 @@ class ArtifactStore:
 
     def resolve_input(self, state: ModuleRuntimeState, reference: str) -> pathlib.Path:
         if ":" in reference:
-            module_and_step, artifact_name = reference.split("/", 1)
-            module_id, step_id = module_and_step.split(":", 1)
+            try:
+                module_and_step, artifact_name = reference.split("/", 1)
+                module_id, step_id = module_and_step.split(":", 1)
+            except ValueError as exc:
+                raise HookError(f"Invalid artifact reference: {reference}") from exc
             key = f"{module_id}:{step_id}/{artifact_name}"
         else:
             key = reference
@@ -72,6 +75,11 @@ class ArtifactStore:
         if path is None:
             path = state.artifacts.get(reference)
         if path is None:
+            if ":" in reference:
+                raise HookError(
+                    f"Unknown artifact reference: {reference}. Artifact references are module-local; "
+                    "use '<step>/<artifact>' from an earlier step in the same module."
+                )
             raise HookError(f"Unknown artifact reference: {reference}")
         return path
 

package/src/ai_push_hooks/config.py

@@ -1,104 +1,21 @@
 from __future__ import annotations
 
-import json
 import os
 import pathlib
-import re
 from typing import Any
 
+from .executors.exec import env_bool
 from .prompts_builtin import BUILTIN_PROMPTS
 from .types import GeneralConfig, HookConfig, HookError, LlmConfig, LoggingConfig, ModuleConfig, StepConfig, SUPPORTED_STEP_TYPES, WorkflowConfig
-from .executors.exec import env_bool
 
 try:
     import tomllib
 except ModuleNotFoundError:  # pragma: no cover
-    tomllib = None  # type: ignore[assignment]
+    import tomli as tomllib
 
 ALLOWED_TOP_LEVEL_KEYS = {"general", "llm", "logging", "workflow", "modules"}
 
 
-def _parse_multiline_string(lines: list[str], index: int, initial: str) -> tuple[str, int]:
-    chunks: list[str] = []
-    value = initial[3:]
-    while True:
-        end_index = value.find('"""')
-        if end_index >= 0:
-            chunks.append(value[:end_index])
-            return "\n".join(chunks), index
-        chunks.append(value)
-        index += 1
-        if index >= len(lines):
-            raise HookError("Unterminated multiline string in TOML fallback parser")
-        value = lines[index]
-
-
-def _assign_path(root: dict[str, Any], path: list[str], value: Any, array_mode: bool = False) -> dict[str, Any]:
-    current: Any = root
-    for part in path[:-1]:
-        if isinstance(current, list):
-            if not current:
-                current.append({})
-            current = current[-1]
-        current = current.setdefault(part, {})
-    key = path[-1]
-    if array_mode:
-        items = current.setdefault(key, [])
-        if not isinstance(items, list):
-            raise HookError(f"Invalid array-of-table path: {'.'.join(path)}")
-        item: dict[str, Any] = {}
-        items.append(item)
-        return item
-    current[key] = value
-    return current
-
-
-def _parse_scalar(raw: str) -> Any:
-    raw = raw.strip()
-    if raw.startswith('"') and raw.endswith('"'):
-        return raw[1:-1]
-    if raw in {"true", "false"}:
-        return raw == "true"
-    if re.fullmatch(r"-?\d+", raw):
-        return int(raw)
-    if raw.startswith("[") and raw.endswith("]"):
-        return json.loads(raw)
-    return raw
-
-
-def parse_toml_fallback(raw: str) -> dict[str, Any]:
-    parsed: dict[str, Any] = {}
-    lines = raw.splitlines()
-    current: Any = parsed
-    index = 0
-    while index < len(lines):
-        line = lines[index].strip()
-        index += 1
-        if not line or line.startswith("#"):
-            continue
-        if line.startswith("[[") and line.endswith("]]"):
-            path = [part.strip() for part in line[2:-2].split(".") if part.strip()]
-            current = _assign_path(parsed, path, None, array_mode=True)
-            continue
-        if line.startswith("[") and line.endswith("]"):
-            path = [part.strip() for part in line[1:-1].split(".") if part.strip()]
-            current = parsed
-            for part in path:
-                current = current.setdefault(part, {})
-            continue
-        if "=" not in line:
-            continue
-        key, value = line.split("=", 1)
-        key = key.strip()
-        value = value.strip()
-        if value.startswith('"""'):
-            parsed_value, index = _parse_multiline_string(lines, index - 1, value)
-        else:
-            parsed_value = _parse_scalar(value)
-        current[key] = parsed_value
-    return parsed
-
-
 def _normalize_step(raw: dict[str, Any]) -> StepConfig:
     step_type = str(raw.get("type", "")).strip()
     if step_type not in SUPPORTED_STEP_TYPES:
@@ -187,6 +104,7 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
             "allow_push_on_error": config.general.allow_push_on_error,
             "require_clean_worktree": config.general.require_clean_worktree,
             "skip_on_sync_branch": config.general.skip_on_sync_branch,
+            "base_branch": config.general.base_branch,
         },
         "llm": config.llm.__dict__.copy(),
         "logging": config.logging.__dict__.copy(),
@@ -211,6 +129,9 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     allow_dirty = env_bool("AI_PUSH_HOOKS_ALLOW_DIRTY")
     if allow_dirty is True:
         raw["general"]["require_clean_worktree"] = False
+    base_branch = os.getenv("AI_PUSH_HOOKS_BASE_BRANCH")
+    if base_branch:
+        raw["general"]["base_branch"] = base_branch.strip() or "main"
 
     logging_level = os.getenv("AI_PUSH_HOOKS_LOG_LEVEL")
     if logging_level:
@@ -238,7 +159,7 @@ def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
             "Run `ai-push-hooks init --template minimal-docs` first"
         )
     text = config_path.read_text(encoding="utf-8")
-    loaded = tomllib.loads(text) if tomllib is not None else parse_toml_fallback(text)
+    loaded = tomllib.loads(text)
     if not isinstance(loaded, dict):
         raise HookError(f"Invalid config format in {config_path}")
     return _apply_env_overrides(_build_config(loaded)), config_path

package/src/ai_push_hooks/executors/apply.py

@@ -8,6 +8,17 @@ from .exec import list_repo_changes, path_matches
 from .llm import call_opencode, finalize_opencode_session
 
 
+def _snapshot_file_contents(repo_root: pathlib.Path, paths: set[str]) -> dict[str, bytes | None]:
+    snapshot: dict[str, bytes | None] = {}
+    for path in paths:
+        full_path = repo_root / path
+        if full_path.is_file():
+            snapshot[path] = full_path.read_bytes()
+        else:
+            snapshot[path] = None
+    return snapshot
+
+
 def run_apply_step(
     context: RuntimeContext,
     state: ModuleRuntimeState,
@@ -23,6 +34,7 @@ def run_apply_step(
                 return {"changed": False, "changed_files": [], "skipped": True}
 
     baseline = list_repo_changes(context.repo_root)
+    baseline_contents = _snapshot_file_contents(context.repo_root, baseline)
     files = list(input_paths)
     agents = context.repo_root / "AGENTS.md"
     if agents.exists():
@@ -41,7 +53,14 @@ def run_apply_step(
         raise HookError(f"Apply step failed: {details}")
 
     after = list_repo_changes(context.repo_root)
-    changed_files = sorted(after - baseline)
+    newly_dirty = after - baseline
+    after_baseline_contents = _snapshot_file_contents(context.repo_root, baseline)
+    changed_while_dirty = {
+        path
+        for path, before_content in baseline_contents.items()
+        if before_content != after_baseline_contents[path]
+    }
+    changed_files = sorted(newly_dirty | changed_while_dirty)
     unexpected = [
         path for path in changed_files if not any(path_matches(path, pattern) for pattern in step.allow_paths)
     ]

package/src/ai_push_hooks/executors/exec.py

@@ -129,7 +129,7 @@ def path_matches(path: str, pattern: str) -> bool:
 
 def list_repo_changes(repo_root: pathlib.Path) -> set[str]:
     changes: set[str] = set()
-    output = git(repo_root, ["status", "--short"], check=False)
+    output = run_command(["git", "status", "--short"], cwd=repo_root).stdout
     for line in output.splitlines():
         payload = line[3:].strip()
         if payload:
@@ -141,7 +141,9 @@ def collect_ranges_from_stdin(
     repo_root: pathlib.Path,
     remote_name: str,
     stdin_lines: list[str],
+    base_branch: str = "main",
 ) -> list[str]:
+    base_branch = base_branch.strip() or "main"
     ranges: set[str] = set()
     for line in stdin_lines:
         parts = line.strip().split()
@@ -160,7 +162,7 @@ def collect_ranges_from_stdin(
                 ranges.add(f"{remote_sha}..{local_sha}")
         else:
             merge_base = git(
-                repo_root, ["merge-base", local_sha, f"{remote_name}/main"], check=False
+                repo_root, ["merge-base", local_sha, f"{remote_name}/{base_branch}"], check=False
             )
             if merge_base:
                 ranges.add(f"{merge_base}..{local_sha}")
@@ -438,7 +440,8 @@ def gh_pr_create_executor(
     if existing_pr:
         return {"skipped": False, "pr_url": existing_pr, "already_exists": True}
 
-    base_branch = str(payload.get("base_branch", "main")).strip() or "main"
+    default_base_branch = context.config.general.base_branch.strip() or "main"
+    base_branch = str(payload.get("base_branch", default_base_branch)).strip() or default_base_branch
     head_branch = str(payload.get("head_branch", branch_name)).strip() or branch_name
     title = sanitize_pr_title(str(payload.get("title", "")).strip(), branch_name)
     body = str(payload.get("body", "")).strip()

package/src/ai_push_hooks/hook.py

@@ -73,7 +73,9 @@ def run_hook(
             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)
+    ranges = collect_ranges_from_stdin(
+        repo_root, remote_name or "origin", actual_stdin, config.general.base_branch
+    )
     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()
@@ -104,6 +106,7 @@ def run_hook(
             "changed_files": changed_files,
             "diff_text": diff_text,
             "branch_name": current_branch(repo_root),
+            "base_branch": config.general.base_branch,
             "sync_branch": "beads-sync",
         },
     )

package/src/ai_push_hooks/modules/pr.py

@@ -14,6 +14,7 @@ from ..types import CollectorResult, RuntimeContext
 
 def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
     branch_name = current_branch(context.repo_root)
+    base_branch = context.config.general.base_branch.strip() or "main"
     flag_env = ""
     for step in state.module.steps:
         if step.when_env:
@@ -25,7 +26,7 @@ def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
             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):
+    if not branch_name or branch_name in {"HEAD", base_branch} or not is_feature_branch(branch_name):
         return CollectorResult(
             artifacts={"pr-context.txt": f"branch={branch_name}\n"},
             skip_module=True,
@@ -61,7 +62,7 @@ def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
             "pr-context.txt": "\n".join(
                 [
                     f"branch={branch_name}",
-                    f"base_branch=main",
+                    f"base_branch={base_branch}",
                     f"remote_name={context.remote_name or 'origin'}",
                 ]
             )

package/src/ai_push_hooks/prompts_builtin.py

@@ -64,10 +64,11 @@ enabled = true
 allow_push_on_error = false
 require_clean_worktree = false
 skip_on_sync_branch = true
+base_branch = "main"
 
 [llm]
 runner = "opencode"
-model = "openai/gpt-5.3-codex"
+model = "openai/gpt-5.5"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/src/ai_push_hooks/types.py

@@ -23,12 +23,13 @@ class GeneralConfig:
     allow_push_on_error: bool = False
     require_clean_worktree: bool = False
     skip_on_sync_branch: bool = True
+    base_branch: str = "main"
 
 
 @dataclass(frozen=True)
 class LlmConfig:
     runner: str = "opencode"
-    model: str = "openai/gpt-5.3-codex"
+    model: str = "openai/gpt-5.5"
     variant: str = ""
     timeout_seconds: int = 800
     max_parallel: int = 2