ai-push-hooks 0.1.18 → 0.2.0

package/src/ai_push_hooks/config.py

@@ -1,102 +1,195 @@
 from __future__ import annotations
 
-import json
 import os
 import pathlib
-import re
+import stat
 from typing import Any
 
+from .executors.exec import env_bool, resolve_git_common_dir, resolve_git_dir
+from .paths import (
+    is_path_within,
+    normalized_component,
+    path_has_symlink,
+    relative_path_parts,
+    resolve_contained_path,
+    validate_path_component,
+)
 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"}
+STORAGE_NAMESPACE_PARTS = (".git", "ai-push-hooks")
+GENERAL_KEYS = {
+    "enabled",
+    "allow_push_on_error",
+    "require_clean_worktree",
+    "skip_on_sync_branch",
+    "base_branch",
+}
+LLM_KEYS = {
+    "runner",
+    "model",
+    "variant",
+    "timeout_seconds",
+    "max_parallel",
+    "json_max_retries",
+    "invalid_json_feedback_max_chars",
+    "json_retry_new_session",
+    "delete_session_after_run",
+    "max_diff_bytes",
+    "session_title_prefix",
+}
+LOGGING_KEYS = {
+    "level",
+    "jsonl",
+    "dir",
+    "capture_llm_transcript",
+    "transcript_dir",
+    "summary_dir",
+    "print_llm_output",
+}
+STEP_KEYS = {
+    "id",
+    "type",
+    "inputs",
+    "output",
+    "schema",
+    "prompt",
+    "prompt_file",
+    "fallback_prompt_id",
+    "collector",
+    "allow_paths",
+    "executor",
+    "assertion",
+    "when_env",
+}
 
 
-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 _require_table(value: Any, label: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise HookError(f"{label} must be a table")
+    return value
+
+
+def _validate_unknown_keys(table: dict[str, Any], allowed: set[str], label: str) -> None:
+    unknown = set(table) - allowed
+    if unknown:
+        raise HookError(f"Unknown field(s) in {label}: {', '.join(sorted(unknown))}")
+
+
+def _validate_bool(table: dict[str, Any], key: str, label: str) -> None:
+    if key in table and type(table[key]) is not bool:
+        raise HookError(f"{label}.{key} must be a TOML boolean")
+
+
+def _validate_string(
+    table: dict[str, Any], key: str, label: str, *, allow_none: bool = False
+) -> None:
+    if key in table and (table[key] is None and allow_none):
+        return
+    if key in table and not isinstance(table[key], str):
+        raise HookError(f"{label}.{key} must be a string")
+
+
+def _validate_string_list(table: dict[str, Any], key: str, label: str) -> None:
+    if key not in table:
+        return
+    value = table[key]
+    if not isinstance(value, (list, tuple)) or any(
+        not isinstance(item, str) for item in value
+    ):
+        raise HookError(f"{label}.{key} must be an array of strings")
+
+
+def _validate_integer(
+    table: dict[str, Any], key: str, label: str, *, minimum: int | None = None
+) -> None:
+    if key not in table:
+        return
+    value = table[key]
+    if type(value) is not int:
+        raise HookError(f"{label}.{key} must be an integer")
+    if minimum is not None and value < minimum:
+        raise HookError(f"{label}.{key} must be at least {minimum}")
+
+
+def _validate_config_types(raw: dict[str, Any]) -> None:
+    unknown = set(raw) - ALLOWED_TOP_LEVEL_KEYS
+    if unknown:
+        raise HookError(
+            "Legacy or unsupported config keys are not allowed: " + ", ".join(sorted(unknown))
+        )
+
+    general = _require_table(raw.get("general", {}), "general")
+    _validate_unknown_keys(general, GENERAL_KEYS, "general")
+    for key in (
+        "enabled",
+        "allow_push_on_error",
+        "require_clean_worktree",
+        "skip_on_sync_branch",
+    ):
+        _validate_bool(general, key, "general")
+    _validate_string(general, "base_branch", "general")
+
+    llm = _require_table(raw.get("llm", {}), "llm")
+    _validate_unknown_keys(llm, LLM_KEYS, "llm")
+    for key in ("runner", "model", "variant", "session_title_prefix"):
+        _validate_string(llm, key, "llm")
+    for key in ("json_retry_new_session", "delete_session_after_run"):
+        _validate_bool(llm, key, "llm")
+    _validate_integer(llm, "timeout_seconds", "llm", minimum=1)
+    _validate_integer(llm, "max_parallel", "llm", minimum=1)
+    _validate_integer(llm, "json_max_retries", "llm", minimum=0)
+    _validate_integer(llm, "invalid_json_feedback_max_chars", "llm", minimum=1)
+    _validate_integer(llm, "max_diff_bytes", "llm", minimum=1)
+
+    logging = _require_table(raw.get("logging", {}), "logging")
+    _validate_unknown_keys(logging, LOGGING_KEYS, "logging")
+    for key in ("level", "dir", "transcript_dir", "summary_dir"):
+        _validate_string(logging, key, "logging")
+    for key in ("jsonl", "capture_llm_transcript", "print_llm_output"):
+        _validate_bool(logging, key, "logging")
+
+    workflow = _require_table(raw.get("workflow", {}), "workflow")
+    _validate_unknown_keys(workflow, {"modules"}, "workflow")
+    _validate_string_list(workflow, "modules", "workflow")
+
+    modules = _require_table(raw.get("modules", {}), "modules")
+    for module_id, module_value in modules.items():
+        if not isinstance(module_id, str):
+            raise HookError("modules keys must be strings")
+        module = _require_table(module_value, f"modules.{module_id}")
+        _validate_unknown_keys(module, {"enabled", "steps"}, f"modules.{module_id}")
+        _validate_bool(module, "enabled", f"modules.{module_id}")
+        if "steps" in module:
+            steps = module["steps"]
+            if not isinstance(steps, (list, tuple)):
+                raise HookError(f"modules.{module_id}.steps must be an array of tables")
+            for index, step_value in enumerate(steps, start=1):
+                step = _require_table(step_value, f"modules.{module_id}.steps[{index}]")
+                label = f"modules.{module_id}.steps[{index}]"
+                _validate_unknown_keys(step, STEP_KEYS, label)
+                for key in ("id", "type"):
+                    _validate_string(step, key, label)
+                for key in (
+                    "collector",
+                    "executor",
+                    "assertion",
+                    "output",
+                    "schema",
+                    "prompt",
+                    "prompt_file",
+                    "fallback_prompt_id",
+                    "when_env",
+                ):
+                    _validate_string(step, key, label, allow_none=True)
+                for key in ("inputs", "allow_paths"):
+                    _validate_string_list(step, key, label)
 
 
 def _normalize_step(raw: dict[str, Any]) -> StepConfig:
@@ -124,6 +217,15 @@ def _normalize_step(raw: dict[str, Any]) -> StepConfig:
     )
     if not step.id:
         raise HookError("Every workflow step requires a non-empty id")
+    validate_path_component(step.id, "Workflow step id")
+    if step.output:
+        validate_path_component(step.output, f"Output for step `{step.id}`")
+    for pattern in step.allow_paths:
+        parts = relative_path_parts(pattern, f"allow_paths entry for step `{step.id}`")
+        if any(normalized_component(part) == ".git" for part in parts):
+            raise HookError(f"Apply step `{step.id}` may not allow Git metadata paths")
+        if normalized_component(parts[-1]) == "agents.md":
+            raise HookError(f"Apply step `{step.id}` may not allow AGENTS.md")
     if step.is_promptable and not any([step.prompt, step.prompt_file, step.fallback_prompt_id]):
         raise HookError(f"Promptable step `{step.id}` requires prompt, prompt_file, or fallback_prompt_id")
     if step.type == "collect" and not step.collector:
@@ -140,6 +242,9 @@ def _normalize_step(raw: dict[str, Any]) -> StepConfig:
 
 
 def _build_config(raw: dict[str, Any]) -> HookConfig:
+    if not isinstance(raw, dict):
+        raise HookError("Config document must contain a top-level table")
+    _validate_config_types(raw)
     unknown = set(raw) - ALLOWED_TOP_LEVEL_KEYS
     if unknown:
         raise HookError(
@@ -156,6 +261,7 @@ def _build_config(raw: dict[str, Any]) -> HookConfig:
 
     modules: dict[str, ModuleConfig] = {}
     for module_id in workflow_modules:
+        validate_path_component(module_id, "Workflow module id")
         if module_id not in module_payload:
             raise HookError(f"workflow.modules references unknown module `{module_id}`")
         module_raw = module_payload[module_id]
@@ -171,6 +277,14 @@ def _build_config(raw: dict[str, Any]) -> HookConfig:
     general = GeneralConfig(**raw.get("general", {}))
     llm = LlmConfig(**raw.get("llm", {}))
     logging = LoggingConfig(**raw.get("logging", {}))
+    for label, storage_path in (
+        ("logging.dir", logging.dir),
+        ("logging.transcript_dir", logging.transcript_dir),
+        ("logging.summary_dir", logging.summary_dir),
+    ):
+        parts = relative_path_parts(storage_path, label)
+        if parts[:2] != STORAGE_NAMESPACE_PARTS or len(parts) < 3:
+            raise HookError(f"{label} must be inside .git/ai-push-hooks/")
     return HookConfig(
         general=general,
         llm=llm,
@@ -187,6 +301,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(),
@@ -199,23 +314,37 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
             "steps": [step.__dict__.copy() for step in module.steps],
         }
 
-    skip = env_bool("AI_PUSH_HOOKS_SKIP")
+    def read_env_bool(name: str) -> bool | None:
+        value = os.getenv(name)
+        if value is None:
+            return None
+        parsed = env_bool(name)
+        if parsed is None:
+            raise HookError(
+                f"Invalid boolean environment override {name}: expected true/false"
+            )
+        return parsed
+
+    skip = read_env_bool("AI_PUSH_HOOKS_SKIP")
     if skip is True:
         raw["general"]["enabled"] = False
-    allow_on_error = env_bool("AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR")
+    allow_on_error = read_env_bool("AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR")
     if allow_on_error is not None:
         raw["general"]["allow_push_on_error"] = allow_on_error
-    require_clean = env_bool("AI_PUSH_HOOKS_REQUIRE_CLEAN")
+    require_clean = read_env_bool("AI_PUSH_HOOKS_REQUIRE_CLEAN")
     if require_clean is not None:
         raw["general"]["require_clean_worktree"] = require_clean
-    allow_dirty = env_bool("AI_PUSH_HOOKS_ALLOW_DIRTY")
+    allow_dirty = read_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:
         raw["logging"]["level"] = logging_level.strip().lower()
-    print_output = env_bool("AI_PUSH_HOOKS_PRINT_LLM_OUTPUT")
+    print_output = read_env_bool("AI_PUSH_HOOKS_PRINT_LLM_OUTPUT")
     if print_output is not None:
         raw["logging"]["print_llm_output"] = print_output
     model = os.getenv("AI_PUSH_HOOKS_MODEL")
@@ -225,8 +354,20 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     if variant is not None:
         raw["llm"]["variant"] = variant.strip()
     timeout = os.getenv("AI_PUSH_HOOKS_TIMEOUT_SECONDS")
-    if timeout:
-        raw["llm"]["timeout_seconds"] = int(timeout)
+    if timeout is not None:
+        try:
+            parsed_timeout = int(timeout.strip())
+        except ValueError as exc:
+            raise HookError(
+                "Invalid numeric environment override AI_PUSH_HOOKS_TIMEOUT_SECONDS: "
+                f"{timeout!r}"
+            ) from exc
+        if parsed_timeout < 1:
+            raise HookError(
+                "Invalid numeric environment override AI_PUSH_HOOKS_TIMEOUT_SECONDS: "
+                "must be at least 1"
+            )
+        raw["llm"]["timeout_seconds"] = parsed_timeout
     return _build_config(raw)
 
 
@@ -237,10 +378,21 @@ def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
             "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)
+    try:
+        text = config_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise HookError(f"Config file is not valid UTF-8: {config_path}") from exc
+    except OSError as exc:
+        raise HookError(f"Could not read config file {config_path}: {exc}") from exc
+    try:
+        loaded = tomllib.loads(text)
+    except ValueError as exc:
+        location = ""
+        if hasattr(exc, "lineno") and hasattr(exc, "colno"):
+            location = f" at line {exc.lineno}, column {exc.colno}"
+        raise HookError(f"Invalid TOML in {config_path}{location}: {exc}") from exc
     if not isinstance(loaded, dict):
-        raise HookError(f"Invalid config format in {config_path}")
+        raise HookError(f"Invalid config format in {config_path}: expected a top-level table")
     return _apply_env_overrides(_build_config(loaded)), config_path
 
 
@@ -248,11 +400,46 @@ def resolve_prompt_text(repo_root: pathlib.Path, step: StepConfig) -> str:
     if step.prompt and step.prompt.strip():
         return step.prompt.strip()
     if step.prompt_file:
-        prompt_path = pathlib.Path(step.prompt_file)
-        if not prompt_path.is_absolute():
-            prompt_path = (repo_root / prompt_path).resolve()
+        parts = relative_path_parts(step.prompt_file, f"Prompt file for step `{step.id}`")
+        if any(normalized_component(part) == ".git" for part in parts):
+            raise HookError(f"Prompt file for step `{step.id}` must not reference Git metadata")
+        lexical_prompt_path = repo_root.joinpath(*parts)
+        if path_has_symlink(repo_root, lexical_prompt_path):
+            raise HookError(f"Prompt file for step `{step.id}` must not traverse a symlink")
+        prompt_path = resolve_contained_path(
+            repo_root,
+            step.prompt_file,
+            f"Prompt file for step `{step.id}`",
+        )
+        resolved_prompt_path = prompt_path.resolve(strict=False)
+        try:
+            git_roots = (
+                resolve_git_dir(repo_root).resolve(strict=True),
+                resolve_git_common_dir(repo_root).resolve(strict=True),
+            )
+        except HookError:
+            git_roots = ()
+        if any(is_path_within(resolved_prompt_path, git_root) for git_root in git_roots):
+            raise HookError(f"Prompt file for step `{step.id}` must not resolve inside Git metadata")
         if prompt_path.exists():
-            text = prompt_path.read_text(encoding="utf-8").strip()
+            flags = os.O_RDONLY | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0)
+            try:
+                descriptor = os.open(prompt_path, flags)
+            except OSError as exc:
+                raise HookError(
+                    f"Prompt file could not be opened safely for step `{step.id}`: {prompt_path}"
+                ) from exc
+            try:
+                if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+                    raise HookError(
+                        f"Prompt file is not a regular file for step `{step.id}`: {prompt_path}"
+                    )
+                with os.fdopen(descriptor, "r", encoding="utf-8") as handle:
+                    descriptor = -1
+                    text = handle.read().strip()
+            finally:
+                if descriptor >= 0:
+                    os.close(descriptor)
             if text:
                 return text
         if step.fallback_prompt_id:

package/src/ai_push_hooks/engine.py

@@ -64,8 +64,6 @@ class WorkflowEngine:
                         continue
                     if any(not running_step.is_read_only for _future, (_state, running_step) in futures.items()):
                         continue
-                    if not step.is_read_only and futures:
-                        continue
                     if step.is_read_only and len(futures) >= max(1, self.context.config.llm.max_parallel):
                         continue
                     future = pool.submit(self._execute_step, state, step)