ai-push-hooks 0.1.0__tar.gz

ai_push_hooks-0.1.0/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.

ai_push_hooks-0.1.0/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: ai-push-hooks
+Version: 0.1.0
+Summary: Modular AI push-hook workflow runner
+Author: ai-push-hooks contributors
+License-Expression: MIT
+Keywords: git,lefthook,docs,ai,pre-push
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# 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

ai_push_hooks-0.1.0/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

ai_push_hooks-0.1.0/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"]

ai_push_hooks-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ai_push_hooks-0.1.0/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"]

ai_push_hooks-0.1.0/src/ai_push_hooks/__main__.py

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

ai_push_hooks-0.1.0/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

ai_push_hooks-0.1.0/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