ai-push-hooks 0.1.17 → 0.1.18

package/README.md

@@ -24,20 +24,31 @@ pnpm add -D ai-push-hooks
 
 Requirements:
 
-- [Python 3.10+](https://www.python.org/downloads/) (`python3` or `python`) is required, including npm installs.
-- [OpenCode CLI](https://github.com/sst/opencode) is required for `llm` and `apply` steps. The expected executable is `opencode`; `opencode-cli` is also accepted for compatibility.
+- [Python 3.10+](https://www.python.org/downloads/) (`python3` or `python`) is required. The npm package is a wrapper around the Python CLI, so Python is still required when installed through npm/pnpm.
+- [OpenCode](https://github.com/anomalyco/opencode) is required for `llm` and `apply` steps.
 - [GitHub CLI (`gh`)](https://cli.github.com/manual/installation) is required only if you use PR creation via `gh_pr_create`.
 
 ## Quick start
 
-1. Install the CLI.
+1. Install by following the steps above.
 2. Generate a starter config:
 
+   Python tool install (`uv tool` / `pipx`):
+
    ```bash
    ai-push-hooks init --template minimal-docs
    ```
 
-3. Wire it into Lefthook:
+   npm/pnpm local install:
+
+   ```bash
+   npx ai-push-hooks init --template minimal-docs
+   # or
+   pnpm exec ai-push-hooks init --template minimal-docs
+   ```
+
+3. Configure modules and steps in [Configuration reference](#configuration-reference).
+4. Wire it into your pre-push hook manager. Lefthook example:
 
    ```yaml
    pre-push:
@@ -46,10 +57,14 @@ Requirements:
          run: ai-push-hooks hook {1} {2}
    ```
 
-4. Push as usual. The workflow runs automatically before push completes.
+   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.
 
 ## Commands
 
+If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm exec`.
+
 | Command | What it does |
 | --- | --- |
 | `ai-push-hooks hook <remote-name> <remote-url>` | Runs the configured pre-push workflow. |
@@ -58,9 +73,7 @@ Requirements:
 
 ## Configuration overview
 
-- Config file lookup order: `ai-push-hooks.toml`, then `.ai-push-hooks.toml` (legacy).
-- If no config file is present, built-in defaults are used.
-- File values are deep-merged over defaults.
+- Config file: `ai-push-hooks.toml` in repo root (required).
 - Prompt resolution precedence for `llm` and `apply` steps:
   1. `prompt`
   2. `prompt_file`
@@ -72,11 +85,11 @@ Requirements:
 
 | Key | Type | Required | Default |
 | --- | --- | --- | --- |
-| `general` | table | no | built-in values |
-| `llm` | table | no | built-in values |
-| `logging` | table | no | built-in values |
-| `workflow` | table | yes | `{ modules = ["docs"] }` |
-| `modules` | table | yes | `{ docs = ... }` |
+| `general` | table | no | see section defaults |
+| `llm` | table | no | see section defaults |
+| `logging` | table | no | see section defaults |
+| `workflow` | table | yes | n/a |
+| `modules` | table | yes | n/a |
 
 ### `[general]`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Modular AI push-hook workflow runner",
   "license": "MIT",
   "repository": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.1.17"
+version = "0.1.18"
 description = "Modular AI push-hook workflow runner"
 readme = "README.md"
 requires-python = ">=3.10"

package/src/ai_push_hooks/cli.py

@@ -28,10 +28,8 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
         raise HookError("Only `minimal-docs` is supported")
     target_dir = cwd or pathlib.Path.cwd()
     config_path = target_dir / "ai-push-hooks.toml"
-    legacy_path = target_dir / ".ai-push-hooks.toml"
-    existing_path = config_path if config_path.exists() else legacy_path if legacy_path.exists() else None
-    if existing_path is not None and not force:
-        raise HookError(f"Refusing to overwrite existing config without --force: {existing_path}")
+    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

package/src/ai_push_hooks/config.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import copy
 import json
 import os
 import pathlib
@@ -16,80 +15,6 @@ try:
 except ModuleNotFoundError:  # pragma: no cover
     tomllib = None  # type: ignore[assignment]
 
-DEFAULT_CONFIG_RAW: dict[str, Any] = {
-    "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",
-        "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,
-        "max_diff_bytes": 180000,
-        "session_title_prefix": "ai-push-hooks",
-    },
-    "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",
-        "print_llm_output": False,
-    },
-    "workflow": {"modules": ["docs"]},
-    "modules": {
-        "docs": {
-            "enabled": True,
-            "steps": [
-                {"id": "collect", "type": "collect", "collector": "docs_context"},
-                {
-                    "id": "query",
-                    "type": "llm",
-                    "inputs": ["collect/push.diff", "collect/changed-files.txt"],
-                    "output": "queries.json",
-                    "schema": "string_array",
-                    "fallback_prompt_id": "docs-query-basic",
-                },
-                {
-                    "id": "analyze",
-                    "type": "llm",
-                    "inputs": [
-                        "collect/push.diff",
-                        "collect/docs-context.txt",
-                        "query/queries.json",
-                        "collect/recent-commits.txt",
-                    ],
-                    "output": "issues.json",
-                    "schema": "docs_issue_array",
-                    "fallback_prompt_id": "docs-analysis-basic",
-                },
-                {
-                    "id": "apply",
-                    "type": "apply",
-                    "inputs": ["collect/push.diff", "collect/docs-context.txt", "analyze/issues.json"],
-                    "allow_paths": ["README.md", "docs/**/*.md"],
-                    "fallback_prompt_id": "docs-apply-basic",
-                },
-                {
-                    "id": "assert",
-                    "type": "assert",
-                    "inputs": ["apply/result.json"],
-                    "assertion": "docs_apply_requires_manual_commit",
-                },
-            ]
-        }
-    },
-}
-
 ALLOWED_TOP_LEVEL_KEYS = {"general", "llm", "logging", "workflow", "modules"}
 
 
@@ -174,16 +99,6 @@ def parse_toml_fallback(raw: str) -> dict[str, Any]:
     return parsed
 
 
-def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
-    merged = copy.deepcopy(base)
-    for key, value in override.items():
-        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
-            merged[key] = deep_merge(merged[key], value)
-        else:
-            merged[key] = copy.deepcopy(value)
-    return merged
-
-
 def _normalize_step(raw: dict[str, Any]) -> StepConfig:
     step_type = str(raw.get("type", "")).strip()
     if step_type not in SUPPORTED_STEP_TYPES:
@@ -315,19 +230,18 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     return _build_config(raw)
 
 
-def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path | None]:
-    config_path: pathlib.Path | None = None
-    raw = copy.deepcopy(DEFAULT_CONFIG_RAW)
-    for candidate in [repo_root / "ai-push-hooks.toml", repo_root / ".ai-push-hooks.toml"]:
-        if candidate.exists():
-            config_path = candidate
-            text = candidate.read_text(encoding="utf-8")
-            loaded = tomllib.loads(text) if tomllib is not None else parse_toml_fallback(text)
-            if not isinstance(loaded, dict):
-                raise HookError(f"Invalid config format in {candidate}")
-            raw = deep_merge(raw, loaded)
-            break
-    return _apply_env_overrides(_build_config(raw)), config_path
+def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
+    config_path = repo_root / "ai-push-hooks.toml"
+    if not config_path.exists():
+        raise HookError(
+            "Missing required config file `ai-push-hooks.toml` in repo root. "
+            "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)
+    if not isinstance(loaded, dict):
+        raise HookError(f"Invalid config format in {config_path}")
+    return _apply_env_overrides(_build_config(loaded)), config_path
 
 
 def resolve_prompt_text(repo_root: pathlib.Path, step: StepConfig) -> str:

package/src/ai_push_hooks/executors/llm.py

@@ -32,7 +32,7 @@ def resolve_opencode_executable() -> str:
     cli_path = shutil.which("opencode-cli")
     if cli_path:
         return cli_path
-    raise HookError("opencode (or opencode-cli) is required but not installed")
+    raise HookError("opencode is required but not installed")
 
 
 def parse_opencode_json_run_output(raw: str) -> tuple[str | None, str]: