capt-hook 0.2.0__py3-none-any.whl

captain_hook/app.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import TYPE_CHECKING, get_args
+
+from pydantic_settings import BaseSettings
+
+from captain_hook.conditions import matches_conditions
+from captain_hook.types import (
+    CustomCondition,
+    Event,
+    HookSpec,
+    InlineTests,
+    RegisteredHook,
+    TCondition,
+)
+
+if TYPE_CHECKING:
+    from captain_hook.classifiers import MessageClassifier
+    from captain_hook.events import BaseHookEvent
+    from captain_hook.types import HookResult
+
+HookHandler = Callable[["BaseHookEvent"], "HookResult | None"]
+
+VALID_CONDITION_TYPES = tuple(
+    t for t in get_args(TCondition) if t is not CustomCondition
+)
+VALID_CONDITION_NAMES = ", ".join(t.__name__ for t in VALID_CONDITION_TYPES) + ", or a CustomCondition"
+
+
+def validate_conditions(conditions: Sequence[TCondition], label: str) -> None:
+    for c in conditions:
+        if not isinstance(c, (*VALID_CONDITION_TYPES, CustomCondition)):
+            raise TypeError(
+                f"Invalid condition in {label}: {c!r} (type {type(c).__name__}). "
+                f"Expected one of: {VALID_CONDITION_NAMES}."
+            )
+
+
+def validate_handler_signature(fn: HookHandler) -> None:
+    sig = inspect.signature(fn)
+    params = [
+        p for p in sig.parameters.values()
+        if p.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    if len(params) != 1:
+        raise TypeError(
+            f"Handler {fn.__name__} has wrong signature: expected (evt) -> HookResult | None, "
+            f"got {sig}. Hook handlers must accept exactly one positional parameter (the event)."
+        )
+    required_kw = [
+        p for p in sig.parameters.values()
+        if p.kind == inspect.Parameter.KEYWORD_ONLY and p.default is inspect.Parameter.empty
+    ]
+    if required_kw:
+        names = ", ".join(p.name for p in required_kw)
+        raise TypeError(
+            f"Handler {fn.__name__} has required keyword-only parameter(s): {names}. "
+            f"Hook handlers are called as handler(evt) — keyword-only parameters must have defaults."
+        )
+
+
+@dataclass
+class State:
+    hooks: list[RegisteredHook] = field(default_factory=list)
+    gitignore_patterns: list[str] = field(default_factory=list)
+    settings: BaseSettings | None = None
+    classifier: MessageClassifier | None = None
+    counter: int = field(default=0, repr=False)
+
+
+_state = State()
+
+
+def reset() -> None:
+    _state.hooks.clear()
+    _state.gitignore_patterns.clear()
+    _state.counter = 0
+    _state.settings = None
+    _state.classifier = None
+
+
+def load_gitignore(root: Path) -> None:
+    _state.gitignore_patterns.clear()
+    if not (gitignore := root / ".gitignore").exists():
+        return
+    _state.gitignore_patterns.extend(
+        line.rstrip("/")
+        for raw in gitignore.read_text().splitlines()
+        if (line := raw.strip()) and not line.startswith("#")
+    )
+
+
+def is_gitignored(path_str: str) -> bool:
+    if not _state.gitignore_patterns:
+        return False
+    p = Path(path_str)
+    return any(
+        fnmatch(p.name, pat) or any(fnmatch(part, pat) for part in p.parts) for pat in _state.gitignore_patterns
+    )
+
+
+def hook(
+    events: Event,
+    *,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+
+    message: str | None = None,
+    block: bool = False,
+    respect_gitignore: bool = True,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    async_: bool = False,
+    skip_planning_agents: bool = True,
+) -> None:
+    if message is None:
+        raise TypeError(
+            "hook() requires message= for declarative hooks. "
+            "Provide message='...' or use @on() for handler-based hooks."
+        )
+    validate_conditions(only_if, "only_if")
+    validate_conditions(skip_if, "skip_if")
+    _state.counter += 1
+    _state.hooks.append(
+        RegisteredHook(
+            spec=HookSpec(
+                events=events,
+                only_if=tuple(only_if),
+                skip_if=tuple(skip_if),
+                message=message,
+                block=block,
+                respect_gitignore=respect_gitignore,
+                max_fires=max_fires,
+                tests=tests,
+                async_=async_,
+                skip_planning_agents=skip_planning_agents,
+            ),
+            name=f"declarative_{_state.counter}",
+        )
+    )
+
+
+def on(
+    events: Event,
+    *,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    respect_gitignore: bool = True,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    async_: bool = False,
+    skip_planning_agents: bool = True,
+) -> Callable[[HookHandler], HookHandler]:
+    validate_conditions(only_if, "only_if")
+    validate_conditions(skip_if, "skip_if")
+    spec = HookSpec(
+        events=events,
+        only_if=tuple(only_if),
+        skip_if=tuple(skip_if),
+        respect_gitignore=respect_gitignore,
+        max_fires=max_fires,
+        tests=tests,
+        async_=async_,
+        skip_planning_agents=skip_planning_agents,
+    )
+
+    def decorator(fn: HookHandler) -> HookHandler:
+        validate_handler_signature(fn)
+        _state.hooks.append(
+            RegisteredHook(
+                spec=spec,
+                handler=fn,
+                name=fn.__name__,
+                source_file=fn.__code__.co_filename,
+            )
+        )
+        return fn
+
+    return decorator
+
+
+def register(
+    events: Event,
+    *,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+    message: str | None = None,
+    block: bool = False,
+    respect_gitignore: bool = True,
+    max_fires: int | None = None,
+    tests: InlineTests | None = None,
+    async_: bool = False,
+    skip_planning_agents: bool = True,
+) -> Callable[[HookHandler], HookHandler] | None:
+    validate_conditions(only_if, "only_if")
+    validate_conditions(skip_if, "skip_if")
+
+    if message is not None:
+        hook(
+            events,
+            only_if=only_if,
+            skip_if=skip_if,
+            message=message,
+            block=block,
+            respect_gitignore=respect_gitignore,
+            max_fires=max_fires,
+            tests=tests,
+            async_=async_,
+            skip_planning_agents=skip_planning_agents,
+        )
+        return None
+
+    if block:
+        raise TypeError(
+            "hook() called with block=True but no message= provided. "
+            "Declarative hooks require message= to specify the block reason. "
+            "Either provide message='...' or use @on() for handler-based hooks."
+        )
+
+    spec = HookSpec(
+        events=events,
+        only_if=tuple(only_if),
+        skip_if=tuple(skip_if),
+        block=block,
+        respect_gitignore=respect_gitignore,
+        max_fires=max_fires,
+        tests=tests,
+        async_=async_,
+        skip_planning_agents=skip_planning_agents,
+    )
+
+    def decorator(fn: HookHandler) -> HookHandler:
+        validate_handler_signature(fn)
+        _state.hooks.append(
+            RegisteredHook(
+                spec=spec,
+                handler=fn,
+                name=fn.__name__,
+                source_file=fn.__code__.co_filename,
+            )
+        )
+        return fn
+
+    return decorator
+
+
+def is_planning_agent_skip(spec: HookSpec, evt: BaseHookEvent) -> bool:
+    from captain_hook.settings import DEFAULT_PLANNING_AGENTS
+
+    if not spec.skip_planning_agents:
+        return False
+    if evt.event not in (Event.SubagentStop | Event.SubagentStart):
+        return False
+    names = getattr(_state.settings, "planning_agents", DEFAULT_PLANNING_AGENTS)
+    return bool(evt.agent_type and evt.agent_type in names)
+
+
+def get_matching_hooks(evt: BaseHookEvent) -> list[RegisteredHook]:
+    return [
+        h
+        for h in _state.hooks
+        if evt.event in h.spec.events
+        and not is_planning_agent_skip(h.spec, evt)
+        and matches_conditions(h.spec, evt)
+        and (
+            not h.spec.respect_gitignore
+            or not _state.gitignore_patterns
+            or not evt.file
+            or not is_gitignored(str(evt.file))
+        )
+    ]
+
+

captain_hook/classifiers/__init__.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from captain_hook.transcript.models import TranscriptMessage
+
+
+@runtime_checkable
+class MessageClassifier(Protocol):
+    """Callable that returns True for messages classified as real user messages."""
+
+    def __call__(self, msg: TranscriptMessage) -> bool: ...
+
+CLASSIFIER_MODULES = ("droid", "conductor", "native")
+
+
+def detect(
+    cwd: str | None = None,
+    transcript_path: str | None = None,
+    messages: list[TranscriptMessage] | None = None,
+) -> MessageClassifier:
+    """Auto-detect the environment and return the appropriate message classifier."""
+    return next(
+        mod.classifier
+        for name in CLASSIFIER_MODULES
+        if (mod := importlib.import_module(f".{name}", __package__))
+        and mod.detect(cwd=cwd, transcript_path=transcript_path, messages=messages)
+    )

captain_hook/classifiers/conductor.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from captain_hook.transcript.models import TranscriptMessage
+
+SYNTHETIC_PREFIXES = (
+    "<system_instruction>",
+    "<task-notification>",
+    "<local-command-caveat>",
+    "<command-name>",
+)
+
+
+def classifier(msg: TranscriptMessage) -> bool:
+    if msg.type != "user":
+        return False
+    text = msg.text.strip()
+    return bool(text) and not text.startswith(SYNTHETIC_PREFIXES)
+
+
+def detect(
+    *,
+    cwd: str | None = None,
+    transcript_path: str | None = None,
+    messages: list[TranscriptMessage] | None = None,
+) -> bool:
+    if cwd and "conductor/workspaces" in cwd:
+        return True
+    if transcript_path and "conductor-workspaces" in transcript_path:
+        return True
+    if messages:
+        return any(m.type == "user" and m.text.strip().startswith("<system_instruction>") for m in messages[:50])
+    return False

captain_hook/classifiers/droid.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from captain_hook.transcript.models import TranscriptMessage
+
+
+def classifier(msg: TranscriptMessage) -> bool:
+    return msg.type == "user" and bool(msg.text.strip())
+
+
+def detect(
+    *,
+    cwd: str | None = None,
+    transcript_path: str | None = None,
+    messages: list[TranscriptMessage] | None = None,
+) -> bool:
+    return "FACTORY_PROJECT_DIR" in os.environ

captain_hook/classifiers/native.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from captain_hook.transcript.models import TranscriptMessage
+
+
+def classifier(msg: TranscriptMessage) -> bool:
+    return msg.type == "user" and bool(msg.text.strip())
+
+
+def detect(
+    *,
+    cwd: str | None = None,
+    transcript_path: str | None = None,
+    messages: list[TranscriptMessage] | None = None,
+) -> bool:
+    return True