capt-hook 0.2.0__py3-none-any.whl

captain_hook/log.py

@@ -0,0 +1,60 @@
+"""Captain-hook logging: one per-session loguru file sink plus stderr warnings.
+
+Modules log through loguru directly (``from loguru import logger``), attaching
+structured context with ``logger.bind(...)``. ``setup_logging()`` installs the
+sinks and a patcher that truncates long bound values so call sites never have to
+slice them by hand.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from captain_hook.session import session_hash
+from captain_hook.settings import resolve_log_dir
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from loguru import Record
+
+MAX_BOUND_VALUE = 200
+
+
+def truncate_bound_values(record: Record) -> None:
+    """Patcher: cap long string values bound via ``logger.bind(...)``."""
+    for key, value in record["extra"].items():
+        if isinstance(value, str) and len(value) > MAX_BOUND_VALUE:
+            record["extra"][key] = value[:MAX_BOUND_VALUE] + "…"
+
+
+def make_format(template: str) -> Callable[[Record], str]:
+    """Build a loguru format function that appends bound context and the traceback."""
+
+    def formatter(record: Record) -> str:
+        return (template + " | {extra}" if record["extra"] else template) + "\n{exception}"
+
+    return formatter
+
+
+def setup_logging(transcript_path: str | None) -> None:
+    """Route captain-hook logs to a per-session loguru file sink plus stderr warnings."""
+    session_id = session_hash(transcript_path) if transcript_path else "unknown"
+    log_dir = resolve_log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    logger.configure(
+        patcher=truncate_bound_values,
+        handlers=[
+            {
+                "sink": str(log_dir / f"{session_id}.log"),
+                "level": "DEBUG",
+                "format": make_format("{time:YYYY-MM-DD HH:mm:ss,SSS} {level} {name}: {message}"),
+                "encoding": "utf-8",
+            },
+            {"sink": sys.stderr, "level": "WARNING", "format": make_format("{level}: {message}")},
+        ],
+    )

captain_hook/primitives/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from captain_hook.primitives.audit import audit as audit
+from captain_hook.primitives.audit import session_id_for as session_id_for
+from captain_hook.primitives.commands import block_command as block_command
+from captain_hook.primitives.commands import warn_command as warn_command
+from captain_hook.primitives.lint import diff_lint as diff_lint
+from captain_hook.primitives.lint import lint as lint
+from captain_hook.primitives.llm import (
+    GateVerdict as GateVerdict,
+)
+from captain_hook.primitives.llm import (
+    NudgeVerdict as NudgeVerdict,
+)
+from captain_hook.primitives.llm import (
+    PromptCheckVerdict as PromptCheckVerdict,
+)
+from captain_hook.primitives.llm import (
+    llm_evaluate as llm_evaluate,
+)
+from captain_hook.primitives.llm import (
+    llm_gate as llm_gate,
+)
+from captain_hook.primitives.llm import (
+    llm_nudge as llm_nudge,
+)
+from captain_hook.primitives.llm import (
+    prompt_check as prompt_check,
+)
+from captain_hook.primitives.nudge import gate as gate
+from captain_hook.primitives.nudge import nudge as nudge
+from captain_hook.styleguide import styleguide as styleguide
+
+__all__ = [
+    "GateVerdict",
+    "NudgeVerdict",
+    "PromptCheckVerdict",
+    "audit",
+    "block_command",
+    "diff_lint",
+    "gate",
+    "lint",
+    "llm_evaluate",
+    "llm_gate",
+    "llm_nudge",
+    "nudge",
+    "prompt_check",
+    "session_id_for",
+    "styleguide",
+    "warn_command",
+]

captain_hook/primitives/audit.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Callable, Sequence
+from datetime import UTC, datetime
+from hashlib import sha256
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from captain_hook.app import on
+from captain_hook.types import Event, HookResult, TCondition
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+
+def session_id_for(evt: BaseHookEvent) -> str | None:
+    """Return a 12-char sha256 prefix of the transcript path, or ``None`` if unavailable."""
+    return sha256(str(p).encode()).hexdigest()[:12] if (p := evt.ctx.t.path) else None
+
+
+def default_log_dir() -> Path:
+    return Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())) / ".context" / "hook-logs"
+
+
+def default_fields(evt: BaseHookEvent) -> dict[str, Any]:
+    return {
+        "ts": datetime.now(UTC).isoformat(),
+        "event": evt.event_name.name,
+        "tool": evt.tool_name,
+        "file": str(evt.file.path) if evt.file else None,
+        "session_id": session_id_for(evt),
+    }
+
+
+def audit(
+    events: Event = Event.PreToolUse | Event.PostToolUse | Event.Stop,
+    *,
+    log_dir: Path | str | None = None,
+    filename: Callable[[datetime], str] = lambda d: f"{d:%Y-%m-%d}.jsonl",
+    fields: Callable[[BaseHookEvent], dict[str, Any]] = default_fields,
+    only_if: Sequence[TCondition] = (),
+    skip_if: Sequence[TCondition] = (),
+) -> None:
+    """Register a hook that appends one JSONL record per matching event.
+
+    Each matching event writes a single line to ``<log_dir>/<filename(now)>``.
+    Default fields are ``ts``, ``event``, ``tool``, ``file``, and ``session_id``
+    (a 12-char sha256 prefix of the transcript path).
+
+    Example:
+        >>> from captain_hook import audit, Event
+        >>> audit(Event.PreToolUse | Event.PostToolUse | Event.Stop)
+
+    Args:
+        events: Event mask to audit. Defaults to PreToolUse | PostToolUse | Stop.
+        log_dir: Output directory. Defaults to ``$CLAUDE_PROJECT_DIR/.context/hook-logs``.
+        filename: ``(datetime) -> str`` mapping a timestamp to a filename.
+        fields: ``(evt) -> dict`` for the per-record payload.
+        only_if: Conditions that must match for the event to be recorded.
+        skip_if: Conditions that, if matched, suppress recording.
+    """
+    resolved_dir = Path(log_dir) if log_dir else default_log_dir()
+
+    @on(events, only_if=only_if, skip_if=skip_if)
+    def audit_event(evt: BaseHookEvent) -> HookResult | None:
+        resolved_dir.mkdir(parents=True, exist_ok=True)
+        with (resolved_dir / filename(datetime.now(UTC))).open("a") as f:
+            f.write(json.dumps(fields(evt)) + "\n")
+        return None

captain_hook/primitives/commands.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import re
+
+from captain_hook.app import hook as register_hook
+from captain_hook.types import Command, Event, InlineTests, Tool
+
+
+def block_command_pattern(tokens: list[str]) -> str:
+    """Convert a token list into a whitespace-flexible regex pattern.
+
+    ``"*"`` becomes ``\\S+`` (any non-whitespace word), ``"a|b"`` becomes an
+    alternation group, and all other tokens are escaped.
+
+    Example:
+        >>> block_command_pattern(["git", "stash", "*"])
+        'git\\\\s+stash\\\\s+\\\\S+'
+    """
+    def convert(token: str) -> str:
+        match token:
+            case "*":
+                return r"\S+"
+            case t if "|" in t:
+                return f"(?:{'|'.join(re.escape(a) for a in t.split('|'))})"
+            case t:
+                return re.escape(t)
+
+    return r"\s+".join(convert(t) for t in tokens)
+
+
+def block_command(
+    pattern: str | list[str],
+    *,
+    reason: str,
+    hint: str | None = None,
+    tests: InlineTests | None = None,
+) -> None:
+    """Register a declarative hook that blocks a Bash command matching a pattern.
+
+    Example:
+        >>> block_command(["git", "stash"], reason="git stash is not allowed", hint="Use jj")
+    """
+    msg = f"BLOCKED: {reason}.{f' {hint}.' if hint else ''}"
+    cmd = Command(block_command_pattern(pattern) if isinstance(pattern, list) else pattern)
+    register_hook(Event.PreToolUse, only_if=[Tool("Bash"), cmd], message=msg, block=True, tests=tests)
+
+
+def warn_command(
+    pattern: str | list[str],
+    *,
+    message: str,
+    tests: InlineTests | None = None,
+    events: Event = Event.PostToolUse,
+) -> None:
+    """Register a declarative hook that warns on a Bash command matching a pattern.
+
+    Example:
+        >>> warn_command(["python", "-c", "*"], message="Prefer uv run mtest")
+    """
+    cmd = Command(block_command_pattern(pattern) if isinstance(pattern, list) else pattern)
+    register_hook(events, only_if=[Tool("Bash"), cmd], message=message, tests=tests)

captain_hook/primitives/lint.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import ast
+import textwrap
+from collections.abc import Callable, Iterator, Sequence
+from typing import TYPE_CHECKING, get_type_hints, overload
+
+from loguru import logger
+
+from captain_hook.app import on
+from captain_hook.state import hook_name
+from captain_hook.types import (
+    Action,
+    Event,
+    FilePath,
+    HookResult,
+    InlineTests,
+    TCondition,
+    TestFile,
+    Tool,
+)
+
+if TYPE_CHECKING:
+    from captain_hook.events import BaseHookEvent
+
+StringCheck = Callable[[str], list[str]]
+AstCheck = Callable[[ast.AST], Iterator[str]]
+DiffCheck = Callable[[ast.AST, ast.AST], list[str]]
+
+DEFAULT_ONLY_IF: tuple[TCondition, ...] = (Tool("Edit|Write"), FilePath("*.py", project_only=False))
+DEFAULT_SKIP_IF: tuple[TCondition, ...] = (TestFile(),)
+DIFF_DEFAULT_ONLY_IF: tuple[TCondition, ...] = (Tool("Edit"), FilePath("*.py", project_only=False))
+
+
+def detect_ast_mode(check: StringCheck | AstCheck) -> bool:
+    hints = get_type_hints(check)
+    first_param = next(iter(hints.values()), None)
+    return first_param is ast.AST or (isinstance(first_param, type) and issubclass(first_param, ast.AST))
+
+
+def read_source(evt: BaseHookEvent) -> str | None:
+    if evt.file and evt.file.path.exists():
+        try:
+            return evt.file.read_text()
+        except (OSError, UnicodeDecodeError):
+            pass
+    return evt.content
+
+
+@overload
+def lint(
+    check: Callable[[str], list[str]],
+    *,
+    message: str,
+    trigger: str | None = ...,
+    sep: str = ...,
+    block: bool = ...,
+    events: Event | None = ...,
+    tests: InlineTests | None = ...,
+    max_shown: int = ...,
+) -> None: ...
+
+
+@overload
+def lint(
+    check: Callable[[ast.AST], Iterator[str]],
+    *,
+    message: str,
+    trigger: str | None = ...,
+    sep: str = ...,
+    block: bool = ...,
+    events: Event | None = ...,
+    tests: InlineTests | None = ...,
+    max_shown: int = ...,
+) -> None: ...
+
+
+def lint(
+    check: Callable[[str], list[str]] | Callable[[ast.AST], Iterator[str]],
+    *,
+    message: str,
+    trigger: str | None = None,
+    sep: str = ", ",
+    block: bool = False,
+    events: Event | None = None,
+    tests: InlineTests | None = None,
+    max_shown: int = 5,
+) -> None:
+    """Register a lint check that runs on Python file edits/writes.
+
+    Supports two modes based on the ``check`` function's type hint:
+    - **String mode**: receives the file content as ``str``, returns violation strings.
+    - **AST mode**: receives each ``ast.AST`` node, yields violation strings.
+
+    Example:
+        >>> def find_prints(content: str) -> list[str]:
+        ...     return [line for line in content.splitlines() if "print(" in line]
+        >>> lint(find_prints, message="Remove print statements: {violations}")
+    """
+    is_ast = detect_ast_mode(check)
+
+    def handler(evt: BaseHookEvent) -> HookResult | None:
+        try:
+            if is_ast:
+                return run_ast_check(check, evt, message, trigger, sep, block, max_shown)  # type: ignore[arg-type]
+            return run_string_check(check, evt, message, sep, block, max_shown)  # type: ignore[arg-type]
+        except Exception:
+            logger.bind(check=check.__name__).opt(exception=True).warning("lint check failed")
+            return None
+
+    handler.__name__ = handler.__qualname__ = hook_name("lint", None, message)
+
+    on(
+        events or Event.PostToolUse,
+        only_if=DEFAULT_ONLY_IF,
+        skip_if=DEFAULT_SKIP_IF,
+        tests=tests,
+    )(handler)
+
+
+def diff_lint(
+    check: DiffCheck,
+    *,
+    message: str,
+    sep: str = ", ",
+    block: bool = False,
+    events: Event | None = None,
+    tests: InlineTests | None = None,
+    max_shown: int = 5,
+    only_if: Sequence[TCondition] = DIFF_DEFAULT_ONLY_IF,
+    skip_if: Sequence[TCondition] = DEFAULT_SKIP_IF,
+) -> None:
+    def handler(evt: BaseHookEvent) -> HookResult | None:
+        try:
+            return run_diff_check(check, evt, message, sep, block, max_shown)
+        except Exception:
+            logger.bind(check=check.__name__).opt(exception=True).warning("diff lint check failed")
+            return None
+
+    handler.__name__ = handler.__qualname__ = hook_name("diff_lint", None, message)
+
+    on(
+        events or Event.PostToolUse,
+        only_if=only_if,
+        skip_if=skip_if,
+        tests=tests,
+    )(handler)
+
+
+def run_string_check(
+    check: StringCheck,
+    evt: BaseHookEvent,
+    message: str,
+    sep: str,
+    block: bool,
+    max_shown: int,
+) -> HookResult | None:
+    if (content := evt.content) is None:
+        return None
+    return format_result(check(content), message, sep, block, max_shown)
+
+
+def run_diff_check(
+    check: DiffCheck,
+    evt: BaseHookEvent,
+    message: str,
+    sep: str,
+    block: bool,
+    max_shown: int,
+) -> HookResult | None:
+    if (old := evt.old) is None or (new := evt.content) is None:
+        return None
+    try:
+        old_tree = ast.parse(textwrap.dedent(old))
+        new_tree = ast.parse(textwrap.dedent(new))
+    except SyntaxError:
+        return None
+    return format_result(check(old_tree, new_tree), message, sep, block, max_shown)
+
+
+def run_ast_check(
+    check: AstCheck,
+    evt: BaseHookEvent,
+    message: str,
+    trigger: str | None,
+    sep: str,
+    block: bool,
+    max_shown: int,
+) -> HookResult | None:
+    source = read_source(evt)
+    if source is None:
+        return None
+    if trigger and trigger not in source:
+        return None
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    violations = [v for node in ast.walk(tree) for v in check(node)]
+    return format_result(violations, message, sep, block, max_shown)
+
+
+def format_result(
+    violations: list[str],
+    message: str,
+    sep: str,
+    block: bool,
+    max_shown: int,
+) -> HookResult | None:
+    if not violations:
+        return None
+    formatted = sep.join(violations[:max_shown])
+    return HookResult(
+        action=Action.block if block else Action.warn,
+        message=message.format(violations=formatted),
+    )