ai-push-hooks 0.1.0

package/.ai-push-hooks.toml

@@ -0,0 +1,73 @@
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-push-hooks contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# ai-push-hooks
+
+AI-assisted pre-push workflow runner for modular repo checks, docs sync, Beads alignment, and PR creation.
+
+## Install
+
+### Python / uv
+
+```bash
+uv tool install ai-push-hooks
+# or
+pipx install ai-push-hooks
+```
+
+### npm
+
+```bash
+npm install --save-dev ai-push-hooks
+# or
+pnpm add -D ai-push-hooks
+```
+
+The npm binary wraps the bundled Python module, so `python3` (or `python`) must be available.
+
+## Maintainer Release
+
+This repo supports automated dual publishing to PyPI and npm from a git tag.
+
+1. Bump `version` in `pyproject.toml` and `package.json` to the same value.
+2. Commit and tag: `git tag vX.Y.Z`.
+3. Push commit + tag: `git push && git push --tags`.
+
+The GitHub Actions release workflow then:
+
+- verifies the tag matches both package versions
+- runs tests
+- builds and validates Python distributions
+- smoke-tests the installed Python CLI
+- publishes to PyPI (Trusted Publishing)
+- publishes to npm (`NPM_TOKEN` secret)
+
+Required one-time setup:
+
+- Configure PyPI Trusted Publisher for this repository.
+- Add repository secret `NPM_TOKEN` with publish access to `ai-push-hooks`.
+
+## Commands
+
+```bash
+ai-push-hooks hook <remote-name> <remote-url>
+ai-push-hooks init --template minimal-docs
+```
+
+`init` supports exactly one template: `minimal-docs`. Use `--force` to overwrite an existing config.
+
+## Lefthook Usage
+
+```yaml
+pre-push:
+  commands:
+    ai-push-hooks:
+      run: ai-push-hooks hook {1} {2}
+```
+
+For local source checkout usage, `./run.sh` works as a wrapper entrypoint.
+
+## Configuration
+
+Put `.ai-push-hooks.toml` in the target repo root. If no file is present, built-in modular defaults are used.
+
+Prompt resolution precedence is:
+
+1. inline `prompt`
+2. `prompt_file`
+3. built-in `fallback_prompt_id`
+
+Minimal docs example:
+
+```toml
+[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 = "Return a JSON array of documentation search queries. JSON only."
+inputs = ["collect/push.diff", "collect/changed-files.txt"]
+output = "queries.json"
+schema = "string_array"
+
+[[modules.docs.steps]]
+id = "analyze"
+type = "llm"
+prompt = "Return JSON issues only for factual documentation drift."
+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 fixes required."
+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"]
+```
+
+Example config that recreates the current docs + beads + PR behavior through configuration only:
+
+The sample below is runnable as-is because each `prompt_file` step also declares a built-in `fallback_prompt_id`. If you add local prompt files, they override the built-ins.
+
+```toml
+[workflow]
+modules = ["beads", "docs", "pr"]
+
+[modules.beads]
+enabled = true
+
+[[modules.beads.steps]]
+id = "collect"
+type = "collect"
+collector = "beads_status_context"
+
+[[modules.beads.steps]]
+id = "plan"
+type = "llm"
+prompt_file = ".ai-push-hooks.prompts/beads-status.txt"
+fallback_prompt_id = "beads-plan-basic"
+inputs = ["collect/branch-context.txt", "collect/changed-files.txt", "collect/push.diff", "collect/commits.txt"]
+output = "beads-plan.json"
+schema = "beads_alignment_result"
+
+[[modules.beads.steps]]
+id = "apply"
+type = "exec"
+executor = "beads_alignment"
+inputs = ["plan/beads-plan.json"]
+
+[[modules.beads.steps]]
+id = "assert"
+type = "assert"
+assertion = "beads_alignment_clean"
+inputs = ["plan/beads-plan.json"]
+
+[modules.docs]
+enabled = true
+
+[[modules.docs.steps]]
+id = "collect"
+type = "collect"
+collector = "docs_context"
+
+[[modules.docs.steps]]
+id = "query"
+type = "llm"
+prompt_file = ".ai-push-hooks.prompts/query.txt"
+fallback_prompt_id = "docs-query-basic"
+inputs = ["collect/push.diff", "collect/changed-files.txt"]
+output = "queries.json"
+schema = "string_array"
+
+[[modules.docs.steps]]
+id = "analyze"
+type = "llm"
+prompt_file = ".ai-push-hooks.prompts/analysis.txt"
+fallback_prompt_id = "docs-analysis-basic"
+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_file = ".ai-push-hooks.prompts/apply.txt"
+fallback_prompt_id = "docs-apply-basic"
+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"]
+
+[modules.pr]
+enabled = true
+
+[[modules.pr.steps]]
+id = "collect"
+type = "collect"
+collector = "pr_context"
+
+[[modules.pr.steps]]
+id = "compose"
+type = "llm"
+prompt_file = ".ai-push-hooks.prompts/create-pr.txt"
+fallback_prompt_id = "pr-compose-basic"
+inputs = ["collect/pr-context.txt", "collect/changed-files.txt", "collect/push.diff", "collect/commits.txt"]
+output = "pr-draft.json"
+schema = "pr_create_payload"
+
+[[modules.pr.steps]]
+id = "create"
+type = "exec"
+executor = "gh_pr_create"
+when_env = "AI_PUSH_HOOKS_CREATE_PR"
+inputs = ["compose/pr-draft.json"]
+```
+
+## Layout
+
+- `src/ai_push_hooks/cli.py` - CLI entrypoint
+- `src/ai_push_hooks/config.py` - config loading and validation
+- `src/ai_push_hooks/engine.py` - scheduler and workflow runtime
+- `src/ai_push_hooks/artifacts.py` - run-directory artifact store
+- `src/ai_push_hooks/prompts_builtin.py` - built-in fallback prompts
+- `src/ai_push_hooks/modules/` - docs, beads, and PR collectors
+- `src/ai_push_hooks/executors/` - LLM, apply, exec, and assertion handlers
+- `run.sh` - source checkout wrapper
+- `bin/ai-push-hooks.js` - npm bin wrapper
+- `.ai-push-hooks.toml` - sample config

package/bin/ai-push-hooks.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const srcDir = path.join(packageRoot, 'src');
+const args = ['-m', 'ai_push_hooks', ...process.argv.slice(2)];
+
+function buildEnv() {
+  const env = { ...process.env };
+  env.PYTHONPATH = env.PYTHONPATH
+    ? `${srcDir}${path.delimiter}${env.PYTHONPATH}`
+    : srcDir;
+  return env;
+}
+
+function run(command) {
+  return spawnSync(command, args, {
+    stdio: 'inherit',
+    env: buildEnv(),
+  });
+}
+
+let result = run('python3');
+if (result.error && result.error.code === 'ENOENT') {
+  result = run('python');
+}
+
+if (result.error && result.error.code === 'ENOENT') {
+  console.error('[ai-push-hooks] python3/python is required but not installed.');
+  process.exit(1);
+}
+
+process.exit(typeof result.status === 'number' ? result.status : 1);

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ai-push-hooks",
+  "version": "0.1.0",
+  "description": "Modular AI push-hook workflow runner",
+  "license": "MIT",
+  "bin": {
+    "ai-push-hooks": "bin/ai-push-hooks.js"
+  },
+  "scripts": {
+    "test": "uv run --with pytest pytest tests -q"
+  },
+  "files": [
+    "bin",
+    "src/**/*.py",
+    "README.md",
+    "run.sh",
+    "pyproject.toml",
+    "LICENSE",
+    ".ai-push-hooks.toml"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-push-hooks"
+version = "0.1.0"
+description = "Modular AI push-hook workflow runner"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ai-push-hooks contributors" }]
+keywords = ["git", "lefthook", "docs", "ai", "pre-push"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.scripts]
+ai-push-hooks = "ai_push_hooks.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/run.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ "${AI_PUSH_HOOKS_SKIP:-0}" == "1" ]]; then
+  printf '[ai-push-hooks] Skipped (AI_PUSH_HOOKS_SKIP=1).\n' >&2
+  exit 0
+fi
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if command -v python3 >/dev/null 2>&1; then
+  py_cmd="python3"
+elif command -v python >/dev/null 2>&1; then
+  py_cmd="python"
+else
+  printf '[ai-push-hooks] python3/python is required but not installed.\n' >&2
+  exit 1
+fi
+
+if [[ -d "${script_dir}/src" ]]; then
+  if [[ -n "${PYTHONPATH:-}" ]]; then
+    export PYTHONPATH="${script_dir}/src:${PYTHONPATH}"
+  else
+    export PYTHONPATH="${script_dir}/src"
+  fi
+fi
+
+exec "${py_cmd}" -m ai_push_hooks "$@"

package/src/ai_push_hooks/__init__.py

@@ -0,0 +1,6 @@
+"""ai-push-hooks package."""
+
+from .cli import main
+from .hook import run_hook
+
+__all__ = ["main", "run_hook"]

package/src/ai_push_hooks/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

package/src/ai_push_hooks/artifacts.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+import pathlib
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from .types import HookError, ModuleRuntimeState
+
+
+def generate_run_id() -> str:
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    return f"{timestamp}-{uuid4().hex[:8]}"
+
+
+class ArtifactStore:
+    def __init__(self, run_dir: pathlib.Path) -> None:
+        self.run_dir = run_dir
+
+    def prepare(self) -> pathlib.Path:
+        self.run_dir.mkdir(parents=True, exist_ok=True)
+        return self.run_dir
+
+    def step_dir(self, module_id: str, step_index: int, step_id: str) -> pathlib.Path:
+        path = self.run_dir / module_id / f"{step_index:02d}-{step_id}"
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def register(
+        self,
+        state: ModuleRuntimeState,
+        step_id: str,
+        artifact_name: str,
+        path: pathlib.Path,
+    ) -> pathlib.Path:
+        state.artifacts[f"{step_id}/{artifact_name}"] = path
+        return path
+
+    def write_text(
+        self,
+        state: ModuleRuntimeState,
+        step_index: int,
+        step_id: str,
+        artifact_name: str,
+        content: str,
+    ) -> pathlib.Path:
+        path = self.step_dir(state.module.id, step_index, step_id) / artifact_name
+        path.write_text(content, encoding="utf-8")
+        return self.register(state, step_id, artifact_name, path)
+
+    def write_json(
+        self,
+        state: ModuleRuntimeState,
+        step_index: int,
+        step_id: str,
+        artifact_name: str,
+        payload: Any,
+    ) -> pathlib.Path:
+        path = self.step_dir(state.module.id, step_index, step_id) / artifact_name
+        path.write_text(json.dumps(payload, ensure_ascii=True, indent=2) + "\n", encoding="utf-8")
+        return self.register(state, step_id, artifact_name, path)
+
+    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)
+            key = f"{module_id}:{step_id}/{artifact_name}"
+        else:
+            key = reference
+        path = state.artifacts.get(key)
+        if path is None:
+            path = state.artifacts.get(reference)
+        if path is None:
+            raise HookError(f"Unknown artifact reference: {reference}")
+        return path
+
+    def register_external(
+        self,
+        state: ModuleRuntimeState,
+        module_id: str,
+        step_id: str,
+        artifact_name: str,
+        path: pathlib.Path,
+    ) -> None:
+        state.artifacts[f"{module_id}:{step_id}/{artifact_name}"] = path

package/src/ai_push_hooks/cli.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+
+from .hook import run_hook
+from .prompts_builtin import MINIMAL_DOCS_TEMPLATE
+from .types import HookError
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="AI push hooks workflow runner")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    hook_parser = subparsers.add_parser("hook", help="Run the hook workflow")
+    hook_parser.add_argument("remote_name", nargs="?", default="")
+    hook_parser.add_argument("remote_url", nargs="?", default="")
+
+    init_parser = subparsers.add_parser("init", help="Write a starter config")
+    init_parser.add_argument("--template", default="minimal-docs")
+    init_parser.add_argument("--force", action="store_true")
+    return parser
+
+
+def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) -> int:
+    if template != "minimal-docs":
+        raise HookError("Only `minimal-docs` is supported")
+    target_dir = cwd or pathlib.Path.cwd()
+    config_path = target_dir / ".ai-push-hooks.toml"
+    if config_path.exists() and not force:
+        raise HookError(f"Refusing to overwrite existing config without --force: {config_path}")
+    config_path.write_text(MINIMAL_DOCS_TEMPLATE, encoding="utf-8")
+    sys.stdout.write(str(config_path) + "\n")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "hook":
+            return run_hook(args.remote_name, args.remote_url)
+        if args.command == "init":
+            return init_config(args.template, args.force)
+        raise HookError(f"Unknown command: {args.command}")
+    except HookError as exc:
+        sys.stderr.write(f"[ai-push-hooks] {exc}\n")
+        return 1