capt-hook 0.2.0__py3-none-any.whl

captain_hook/cli.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import json
+import os
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from captain_hook.app import _state, load_gitignore, reset
+from captain_hook.context import HookContext
+from captain_hook.dispatch import dispatch
+from captain_hook.loader import discover_hooks
+from captain_hook.log import setup_logging
+from captain_hook.session import SessionStore, ensure_session
+from captain_hook.transcript import Transcript
+from captain_hook.types import Event
+
+DIST_NAME = "capt-hook"
+
+
+def example_hook_source() -> str:
+    """Read the bundled ``example.py`` scaffold from ``templates/example_hook.py.tmpl``."""
+    return (importlib.resources.files("captain_hook") / "templates" / "example_hook.py.tmpl").read_text()
+
+
+def generate_settings(hooks_dir: str = ".claude/hooks", from_source: str = DIST_NAME) -> dict[str, Any]:
+    events_by_async: defaultdict[bool, set[str]] = defaultdict(set)
+    for entry in _state.hooks:
+        for member in Event:
+            if member in entry.spec.events and (name := member.name):
+                events_by_async[entry.spec.async_].add(name)
+
+    from_flag = "" if from_source == DIST_NAME else f" --from {from_source}"
+    hooks_flag = "" if hooks_dir == ".claude/hooks" else f" --hooks $CLAUDE_PROJECT_DIR/{hooks_dir}"
+
+    def commands(event: str) -> list[dict[str, Any]]:
+        return [
+            {
+                "type": "command",
+                "command": (
+                    f"uvx{from_flag} capt-hook"
+                    f"{hooks_flag}"
+                    f" run {event}"
+                    f"{' --async' if is_async else ''}"
+                ),
+            }
+            | ({"async": True} if is_async else {})
+            for is_async, events in sorted(events_by_async.items())
+            if event in events
+        ]
+
+    return {
+        "hooks": {
+            event: [{"hooks": commands(event)}] for event in sorted(events_by_async[False] | events_by_async[True])
+        }
+    }
+
+
+def generate_settings_json(hooks_dir: str = ".claude/hooks", from_source: str = DIST_NAME) -> str:
+    return json.dumps(generate_settings(hooks_dir, from_source=from_source), indent=2)
+
+
+def merge_settings(hooks_dir: str, settings_path: Path, from_source: str = DIST_NAME) -> dict[str, Any]:
+    hook_settings = generate_settings(hooks_dir, from_source=from_source)
+    if settings_path.exists():
+        existing = json.loads(settings_path.read_text())
+        existing["hooks"] = hook_settings["hooks"]
+        return existing
+    return hook_settings
+
+
+def is_captain_hook_group(group: dict[str, Any]) -> bool:
+    return any("capt-hook" in (h.get("command") or "") for h in group.get("hooks") or [])
+
+
+def merge_init_settings(
+    hooks_dir: str, settings_path: Path, from_source: str = DIST_NAME
+) -> tuple[dict[str, Any], dict[str, str]]:
+    hook_settings = generate_settings(hooks_dir, from_source=from_source)
+    new_hooks: dict[str, list[dict[str, Any]]] = hook_settings["hooks"]
+
+    if not settings_path.exists():
+        return hook_settings, {event: "added" for event in new_hooks}
+
+    existing = json.loads(settings_path.read_text())
+    existing_hooks = existing.setdefault("hooks", {})
+    summary: dict[str, str] = {}
+
+    for event, new_entries in new_hooks.items():
+        existing_entries = existing_hooks.get(event, [])
+        if any(is_captain_hook_group(g) for g in existing_entries):
+            summary[event] = "unchanged"
+        else:
+            existing_hooks[event] = existing_entries + new_entries
+            summary[event] = "added"
+
+    return existing, summary
+
+
+def run_event(
+    event_name: str,
+    *,
+    async_: bool = False,
+    root: Path | None = None,
+) -> None:
+    try:
+        event = Event[event_name]
+    except KeyError:
+        valid = ", ".join(n for e in Event if (n := e.name))
+        print(
+            f"Invalid event type: {event_name!r}. Valid event names are: {valid}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    raw_text = sys.stdin.read()
+    if not raw_text.strip():
+        return
+
+    try:
+        raw = json.loads(raw_text)
+    except (json.JSONDecodeError, ValueError) as e:
+        print(f"Malformed stdin: {e}", file=sys.stderr)
+        return
+
+    transcript_path = raw.get("transcript_path")
+    setup_logging(transcript_path)
+    resolved_path = raw.get("agent_transcript_path") or transcript_path
+
+    session_dir = ensure_session(transcript_path) if transcript_path else ensure_session(root or Path.cwd())
+    ctx = HookContext(
+        session=SessionStore(session_dir),
+        transcript=Transcript.from_path(resolved_path),
+        settings=_state.settings,
+        project_root=root,
+    )
+    evt = event.event_class(_raw=raw, ctx=ctx)
+
+    if output := dispatch(event, evt, session_dir=session_dir, async_=async_):
+        print(json.dumps(output))
+
+
+def init_project(root: Path) -> None:
+    hooks_dir = root / ".claude" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    example = hooks_dir / "example.py"
+    example_created = not example.exists()
+    if example_created:
+        example.write_text(example_hook_source())
+
+    settings_path = root / ".claude" / "settings.local.json"
+    reset()
+    discover_hooks(str(hooks_dir))
+    merged, summary = merge_init_settings(".claude/hooks", settings_path)
+    settings_path.write_text(json.dumps(merged, indent=2) + "\n")
+
+    print(f"Scaffolded {example.relative_to(root)} + {settings_path.relative_to(root)}.")
+    print()
+    print(f"{settings_path.relative_to(root)}:")
+    added = [e for e, status in summary.items() if status == "added"]
+    unchanged = [e for e, status in summary.items() if status == "unchanged"]
+    if not added and not unchanged:
+        print("  no hook entries to add")
+    for event in added:
+        print(f"  + added {event} hook entry")
+    if unchanged:
+        print(f"  unchanged: {', '.join(unchanged)} (already present)")
+    print()
+    print("Next:")
+    print("  1. Read the quickstart: docs/getting-started/quickstart.md")
+    print("  2. Edit example.py or add new files under .claude/hooks/")
+    print("  3. capt-hook test       # verify inline tests")
+    print("  4. capt-hook generate-settings    # rewire after adding events")
+
+
+def show_logs(session: str | None = None, tail: int | None = None) -> None:
+    """Print a captain-hook session log.
+
+    Args:
+        session: A session id, or a transcript path (hashed via ``session_hash``)
+            to locate its log file. When ``None``, the most recently modified log
+            is shown.
+        tail: When set, print only the last ``tail`` lines.
+    """
+    from captain_hook.session import session_hash
+    from captain_hook.settings import resolve_log_dir
+
+    log_dir = resolve_log_dir()
+    if not log_dir.exists():
+        print(f"No captain-hook log directory at {log_dir}", file=sys.stderr)
+        return
+
+    if session is None:
+        logs = sorted(log_dir.glob("*.log"), key=lambda p: p.stat().st_mtime)
+        if not logs:
+            print(f"No log files in {log_dir}", file=sys.stderr)
+            return
+        log_file = logs[-1]
+    else:
+        session_id = session_hash(session) if ("/" in session or session.endswith(".jsonl")) else session
+        log_file = log_dir / f"{session_id}.log"
+
+    if not log_file.exists():
+        print(f"No log file at {log_file}", file=sys.stderr)
+        return
+
+    lines = log_file.read_text().splitlines()
+    print("\n".join(lines[-tail:] if tail else lines))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="capt-hook",
+        description="Captain Hook — declarative hook framework for Claude Code lifecycle events.",
+    )
+    parser.add_argument(
+        "--hooks",
+        default=None,
+        help="Path to hooks package directory (default: $CLAUDE_PROJECT_DIR/.claude/hooks)",
+    )
+    parser.add_argument("--root", default=None, help="Project root for gitignore and session resolution")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = sub.add_parser("run", help="Dispatch a hook event (reads JSON from stdin, writes JSON to stdout)")
+    run_parser.add_argument("event", help=f"Event type: {', '.join(n for e in Event if (n := e.name))}")
+    run_parser.add_argument("--async", dest="async_", action="store_true", default=False, help="Run async hooks only")
+
+    settings_parser = sub.add_parser(
+        "generate-settings", help="Generate Claude Code settings JSON for .claude/settings.local.json"
+    )
+    settings_parser.add_argument("--hooks-dir", default=".claude/hooks", help="Hooks directory relative to project root")
+    settings_parser.add_argument("--no-merge", action="store_true", help="Output standalone JSON instead of merging")
+    settings_parser.add_argument("--from", dest="from_source", default=DIST_NAME, help=f"Package source for uvx --from (local path or PyPI spec, default: {DIST_NAME})")
+
+    test_parser = sub.add_parser("test", help="Run inline tests from all registered hooks")
+    test_parser.add_argument("--json", dest="json_output", action="store_true", help="Emit one JSON record per test (CI mode)")
+    sub.add_parser("init", help="Scaffold hooks directory, bin script, and settings")
+
+    logs_parser = sub.add_parser("logs", help="View a recent captain-hook session log")
+    logs_parser.add_argument("--session", default=None, help="Session id or transcript path (hashed) to view")
+    logs_parser.add_argument("--tail", type=int, default=None, help="Show only the last N lines")
+
+    return parser
+
+
+def expected_kinds_from_state() -> dict[str, str]:
+    out: dict[str, str] = {}
+    for entry in _state.hooks:
+        if not entry.spec.tests:
+            continue
+        for key, expected in entry.spec.tests.items():
+            out[f"{entry.name}:{key!r}"] = type(expected).__name__.lower()
+    return out
+
+
+def run_tests(json_output: bool = False) -> None:
+    from captain_hook.testing.helpers import run_inline_tests
+
+    results = run_inline_tests()
+    if not results:
+        if json_output:
+            print(json.dumps({"status": "empty", "reason": "no inline tests"}))
+        else:
+            print("No inline tests found.")
+        return
+
+    expected_by_id = expected_kinds_from_state()
+    passed = failed = errors = skipped = 0
+    for name, status, _ok, detail in results:
+        if json_output:
+            print(json.dumps({
+                "id": name,
+                "status": status,
+                "expected": expected_by_id.get(name, ""),
+                "reason": detail,
+            }))
+        match status:
+            case "pass":
+                passed += 1
+                if not json_output:
+                    print(f"  PASS  {name}")
+            case "skip":
+                skipped += 1
+                if not json_output:
+                    print(f"  SKIP  {name}: {detail}")
+            case "fail":
+                failed += 1
+                if not json_output:
+                    print(f"  FAIL  {name}: {detail}")
+            case "error":
+                errors += 1
+                if not json_output:
+                    print(f"  ERROR {name}: {detail}")
+            case _:
+                pass
+
+    if not json_output:
+        total = passed + failed + errors + skipped
+        print(f"\n{total} tests: {passed} passed, {failed} failed, {errors} errors, {skipped} skipped")
+    if failed or errors:
+        sys.exit(1)
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    root = Path(args.root) if args.root else Path(project_dir) if project_dir else Path.cwd()
+    hooks = args.hooks or str(root / ".claude" / "hooks")
+
+    if args.command == "init":
+        init_project(root)
+        return
+
+    if args.command == "logs":
+        show_logs(session=args.session, tail=args.tail)
+        return
+
+    reset()
+    load_gitignore(root)
+    discover_hooks(hooks)
+
+    match args.command:
+        case "run":
+            run_event(args.event, async_=args.async_, root=root)
+        case "generate-settings":
+            if args.no_merge:
+                print(generate_settings_json(args.hooks_dir, from_source=args.from_source))
+            else:
+                settings_path = root / ".claude" / "settings.local.json"
+                merged = merge_settings(args.hooks_dir, settings_path, from_source=args.from_source)
+                print(json.dumps(merged, indent=2))
+        case "test":
+            run_tests(json_output=args.json_output)
+        case _:
+            parser.error(f"Unknown command: {args.command}")

captain_hook/command.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+import tree_sitter_bash as tsbash  # type: ignore[import-untyped]
+from loguru import logger
+from tree_sitter import Language, Node, Parser
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+
+BASH_LANGUAGE = Language(tsbash.language())  # pyright: ignore[reportDeprecated]
+BASH_PARSER = Parser(BASH_LANGUAGE)
+
+COMPOUND_OPS = frozenset({"&&", "||", ";", "|", "&"})
+
+
+@dataclass(frozen=True)
+class Redirect:
+    """A shell redirect parsed from a bash command (e.g. ``> file.txt``, ``2>&1``)."""
+
+    op: str
+    target: str
+    fd: int | None = None
+
+
+@dataclass(frozen=True)
+class Command:
+    """A single parsed shell command with executable, arguments, env vars, and redirects.
+
+    Use ``Command.parse(raw)`` to parse a command string, or access via ``CommandLine``.
+    """
+
+    raw: str
+    executable: str
+    args: tuple[str, ...]
+    env: tuple[tuple[str, str], ...] = ()
+    redirects: tuple[Redirect, ...] = ()
+
+    @classmethod
+    def parse(cls, raw: str) -> Command:
+        return CommandLine.parse(raw).primary
+
+    @classmethod
+    def empty(cls) -> Command:
+        return cls(raw="", executable="", args=())
+
+    @cached_property
+    def argv(self) -> tuple[str, ...]:
+        return (self.executable, *self.args) if self.executable else ()
+
+    @cached_property
+    def program(self) -> str:
+        if self.executable == "uv" and len(self.args) >= 2 and self.args[0] == "run":
+            return self.args[1]
+        if re.match(r"python3?$", self.executable) and len(self.args) >= 2 and self.args[0] == "-m":
+            return self.args[1]
+        return self.executable
+
+    @cached_property
+    def env_dict(self) -> dict[str, str]:
+        return dict(self.env)
+
+    def matches(self, pattern: str) -> bool:
+        return bool(re.search(pattern, str(self)))
+
+    def has_arg(self, *patterns: str) -> bool:
+        return any(re.search(p, a) for p in patterns for a in self.args)
+
+    def __str__(self) -> str:
+        return " ".join(self.argv) if self.argv else self.raw
+
+    def __contains__(self, item: str) -> bool:
+        return item in str(self)
+
+    def __bool__(self) -> bool:
+        return bool(self.executable)
+
+
+@dataclass(frozen=True)
+class CommandLine:
+    """A full parsed bash command line, potentially containing multiple commands joined by operators.
+
+    Use ``CommandLine.parse(raw)`` to parse. Access individual commands via ``.commands``
+    or the final command via ``.primary``.
+    """
+
+    raw: str
+    parts: tuple[tuple[Command, str | None], ...]
+
+    @classmethod
+    def parse(cls, raw: str) -> CommandLine:
+        tree = BASH_PARSER.parse(raw.encode())
+        if parts := cls.walk_node(tree.root_node):
+            return cls(raw=raw, parts=tuple(parts))
+        logger.bind(raw=raw).warning("tree-sitter bash parse produced no commands; falling back to naive split")
+        return cls(raw=raw, parts=((cls.fallback(raw), None),))
+
+    @cached_property
+    def commands(self) -> tuple[Command, ...]:
+        return tuple(cmd for cmd, _ in self.parts)
+
+    @cached_property
+    def primary(self) -> Command:
+        return self.parts[-1][0] if self.parts else Command.empty()
+
+    @cached_property
+    def head(self) -> Command:
+        return self.parts[0][0] if self.parts else Command.empty()
+
+    def __iter__(self) -> Iterator[Command]:
+        return iter(self.commands)
+
+    def __len__(self) -> int:
+        return len(self.parts)
+
+    def __str__(self) -> str:
+        return self.raw
+
+    def __contains__(self, item: str) -> bool:
+        return item in self.raw
+
+    def __bool__(self) -> bool:
+        return bool(self.parts)
+
+    @cached_property
+    def q(self) -> CommandLineQuery:
+        return CommandLineQuery(self)
+
+    @staticmethod
+    def node_text(node: Node) -> str:
+        return node.text.decode() if node.text else ""
+
+    @staticmethod
+    def word_text(node: Node) -> str:
+        return (
+            CommandLine.node_text(node).strip("'\"")
+            if node.type in ("string", "raw_string")
+            else CommandLine.node_text(node)
+        )
+
+    @staticmethod
+    def extract_redirect(node: Node) -> Redirect:
+        op = ""
+        target = ""
+        fd: int | None = None
+
+        for child in node.children:
+            match child.type:
+                case "file_descriptor":
+                    fd = int(CommandLine.node_text(child)) if CommandLine.node_text(child).isdigit() else None
+                case t if t in (">", ">>", "<", "<<", ">&", "<&", ">|"):
+                    op = t
+                case _:
+                    text = CommandLine.node_text(child)
+                    if not op and text in (">", ">>", "<", "<<", ">&", "<&", ">|"):
+                        op = text
+                    elif op:
+                        target = text
+                    else:
+                        target = text
+
+        return Redirect(op=op, target=target, fd=fd)
+
+    @staticmethod
+    def extract_command(node: Node) -> Command:
+        executable = ""
+        args: list[str] = []
+        env: list[tuple[str, str]] = []
+        redirects: list[Redirect] = []
+
+        for child in node.children:
+            match child.type:
+                case "command_name":
+                    executable = CommandLine.word_text(child)
+                case "variable_assignment":
+                    name = next((c for c in child.children if c.type == "variable_name"), None)
+                    val = child.children[-1] if len(child.children) >= 3 else None
+                    if name:
+                        env.append(
+                            (
+                                CommandLine.node_text(name),
+                                CommandLine.word_text(val) if val and val.type != "=" else "",
+                            )
+                        )
+                case "file_redirect":
+                    redirects.append(CommandLine.extract_redirect(child))
+                case _ if child.type in (
+                    "word",
+                    "string",
+                    "raw_string",
+                    "number",
+                    "concatenation",
+                    "simple_expansion",
+                    "expansion",
+                ):
+                    if executable:
+                        args.append(CommandLine.word_text(child))
+                    else:
+                        executable = CommandLine.word_text(child)
+                case _:
+                    pass
+
+        return Command(
+            raw=CommandLine.node_text(node),
+            executable=executable,
+            args=tuple(args),
+            env=tuple(env),
+            redirects=tuple(redirects),
+        )
+
+    @staticmethod
+    def collect_parts(children: list[Node], ops: frozenset[str]) -> list[tuple[Command, str | None]]:
+        parts: list[tuple[Command, str | None]] = []
+        for child in children:
+            text = CommandLine.node_text(child)
+            if child.type in ops or text in ops:
+                if parts:
+                    cmd, _ = parts[-1]
+                    parts[-1] = (cmd, text)
+                continue
+            if sub := CommandLine.walk_node(child):
+                parts.extend(sub)
+        return parts
+
+    @staticmethod
+    def walk_redirected(node: Node) -> list[tuple[Command, str | None]]:
+        redirects: list[Redirect] = []
+        inner_parts: list[tuple[Command, str | None]] = []
+        for child in node.children:
+            if child.type == "file_redirect":
+                redirects.append(CommandLine.extract_redirect(child))
+            else:
+                inner_parts.extend(CommandLine.walk_node(child))
+        if redirects and inner_parts:
+            inner_parts = [
+                (
+                    Command(
+                        raw=cmd.raw,
+                        executable=cmd.executable,
+                        args=cmd.args,
+                        env=cmd.env,
+                        redirects=(*cmd.redirects, *redirects),
+                    ),
+                    op,
+                )
+                for cmd, op in inner_parts
+            ]
+        return inner_parts or [
+            (
+                Command(
+                    raw=CommandLine.node_text(node),
+                    executable="",
+                    args=(),
+                    redirects=tuple(redirects),
+                ),
+                None,
+            )
+        ]
+
+    @staticmethod
+    def walk_node(node: Node) -> list[tuple[Command, str | None]]:
+        match node.type:
+            case "program":
+                return CommandLine.collect_parts(node.children, frozenset({";"}))
+            case "list":
+                return CommandLine.collect_parts(node.children, COMPOUND_OPS)
+            case "pipeline":
+                return CommandLine.collect_parts(node.children, frozenset({"|"}))
+            case "command":
+                return [(CommandLine.extract_command(node), None)]
+            case "redirected_statement":
+                return CommandLine.walk_redirected(node)
+            case _:
+                parts: list[tuple[Command, str | None]] = []
+                for child in node.children:
+                    parts.extend(CommandLine.walk_node(child))
+                return parts
+
+    @staticmethod
+    def fallback(raw: str) -> Command:
+        return Command(raw=raw, executable=raw.split()[0] if raw.split() else raw, args=())
+
+
+@dataclass(frozen=True)
+class CommandLineQuery:
+    """Predicate helpers for inspecting a parsed ``CommandLine``.
+
+    Wraps a ``CommandLine`` to answer common yes/no questions a hook condition
+    needs — which executable runs, whether a subcommand or token appears, or
+    whether the line redirects/pipes. Obtain one via ``CommandLine.q``.
+    """
+
+    line: CommandLine
+
+    def runs(self, *argv: str) -> bool:
+        """Return whether the primary command's argv starts with ``argv``.
+
+        Args:
+            *argv: Leading argv tokens to match, e.g. ``("git", "push")``.
+
+        Returns:
+            ``True`` if ``argv`` is non-empty and is a prefix of the primary
+            command's ``argv``.
+        """
+        return bool(argv) and self.line.primary.argv[: len(argv)] == argv
+
+    def has_subcommand(self, name: str) -> bool:
+        """Return whether any command in the line carries ``name`` as an argument.
+
+        Args:
+            name: The subcommand/argument token to look for (e.g. ``"push"``).
+
+        Returns:
+            ``True`` if ``name`` appears in the arguments of any parsed command.
+        """
+        return any(name in cmd.args for cmd in self.line.commands)
+
+    def any_command(self, pred: Callable[[Command], bool]) -> bool:
+        """Return whether any command in the line satisfies ``pred``.
+
+        Args:
+            pred: Predicate applied to each parsed ``Command``.
+
+        Returns:
+            ``True`` if ``pred`` returns truthy for at least one command.
+        """
+        return any(pred(cmd) for cmd in self.line.commands)
+
+    def uses_redirect(self) -> bool:
+        """Return whether the line redirects output or pipes between commands.
+
+        Returns:
+            ``True`` if any command has a file redirect or the parts are joined
+            by a pipe (``|``) operator.
+        """
+        return any(cmd.redirects for cmd in self.line.commands) or any(
+            op == "|" for _, op in self.line.parts if op
+        )
+
+    def contains_token(self, token: str) -> bool:
+        """Return whether ``token`` appears as a whole argv element in any command.
+
+        Unlike ``has_subcommand`` this matches the executable as well as the
+        arguments and requires an exact element match, not a substring.
+
+        Args:
+            token: The exact argv token to look for.
+
+        Returns:
+            ``True`` if ``token`` equals an argv element of any parsed command.
+        """
+        return any(token == a for cmd in self.line.commands for a in cmd.argv)