capt-hook 0.2.0__tar.gz → 0.3.0__tar.gz

{capt_hook-0.2.0 → capt_hook-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 0.2.0
+Version: 0.3.0
 Summary: Declarative hook framework for Claude Code
 Keywords: claude,claude-code,hooks,llm,agents,guardrails,cli
 Author: Yasyf Mohamedali

{capt_hook-0.2.0 → capt_hook-0.3.0}/captain_hook/__init__.py

@@ -22,27 +22,25 @@ from captain_hook.primitives import (
     GateVerdict,
     NudgeVerdict,
     PromptCheckVerdict,
-    audit,
     block_command,
     diff_lint,
     gate,
-    lint,
     llm_gate,
     llm_nudge,
-    nudge,
     prompt_check,
     session_id_for,
-    styleguide,
     warn_command,
 )
+from captain_hook.primitives.audit import audit
+from captain_hook.primitives.lint import lint
 from captain_hook.primitives.llm import llm_evaluate
+from captain_hook.primitives.nudge import nudge
 from captain_hook.prompt import Prompt, PromptMessage
 from captain_hook.session import SessionSlot, SessionStore, session_state
 from captain_hook.settings import AutoConf, HooksSettings, build_settings
 from captain_hook.signals import cite_message, extract_signal_context, resolve_signals, score_signals, transcript_texts
 from captain_hook.signals.nlp import Clause, NlpSignal, Phrase
 from captain_hook.state import EchoTracker, HookState, PrimitiveState, workflow_state
-from captain_hook.styleguide import StyleDiffRule, StyleRule, Violation
 from captain_hook.tasks import Task, Tasks
 from captain_hook.testing import Allow, Block, InlineTests, Input, TranscriptFixture, Warn
 from captain_hook.tools import EditOp, TaskOp, WriteOp
@@ -101,8 +99,8 @@ from captain_hook.types import (
     Waiting,
 )
 from captain_hook.utils import read_json
-from captain_hook.workflow import Artifact, Step, Workflow, text_matches
-from captain_hook.workflow import workflow as workflow
+from captain_hook.primitives.workflow import Artifact, Step, Workflow, text_matches
+from captain_hook.primitives.workflow import workflow as workflow
 
 __all__ = [
     # registration
@@ -165,10 +163,6 @@ __all__ = [
     "prompt_check",
     "PromptCheckVerdict",
     "session_id_for",
-    "StyleDiffRule",
-    "StyleRule",
-    "styleguide",
-    "Violation",
     "warn_command",
     # signals
     "cite_message",

{capt_hook-0.2.0 → capt_hook-0.3.0}/captain_hook/cli.py

@@ -1,14 +1,16 @@
 from __future__ import annotations
 
-import argparse
 import importlib.resources
 import json
 import os
 import sys
 from collections import defaultdict
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+import click
+
 from captain_hook.app import _state, load_gitignore, reset
 from captain_hook.context import HookContext
 from captain_hook.dispatch import dispatch
@@ -19,6 +21,18 @@ from captain_hook.transcript import Transcript
 from captain_hook.types import Event
 
 DIST_NAME = "capt-hook"
+EVENT_NAMES = ", ".join(n for e in Event if (n := e.name))
+
+
+@dataclass(frozen=True, slots=True)
+class CliState:
+    root: Path
+    hooks: str
+
+    def discover(self) -> None:
+        reset()
+        load_gitignore(self.root)
+        discover_hooks(self.hooks)
 
 
 def example_hook_source() -> str:
@@ -212,41 +226,6 @@ def show_logs(session: str | None = None, tail: int | None = None) -> None:
     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:
@@ -305,37 +284,77 @@ def run_tests(json_output: bool = False) -> None:
         sys.exit(1)
 
 
-def main() -> None:
-    parser = build_parser()
-    args = parser.parse_args()
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--hooks",
+    default=None,
+    help="Path to hooks package directory (default: $CLAUDE_PROJECT_DIR/.claude/hooks)",
+)
+@click.option("--root", "root_path", default=None, help="Project root for gitignore and session resolution")
+@click.pass_context
+def cli(ctx: click.Context, hooks: str | None, root_path: str | None) -> None:
+    """Captain Hook — declarative hook framework for Claude Code lifecycle events."""
+    root = Path(root_path) if root_path else Path(env) if (env := os.environ.get("CLAUDE_PROJECT_DIR")) else Path.cwd()
+    ctx.obj = CliState(root=root, hooks=hooks or str(root / ".claude" / "hooks"))
+
+
+@cli.command(
+    short_help="Dispatch a hook event (reads JSON from stdin, writes JSON to stdout)",
+    help=(
+        "Dispatch a hook event (reads JSON from stdin, writes JSON to stdout).\n\n"
+        f"EVENT is one of: {EVENT_NAMES}."
+    ),
+)
+@click.argument("event")
+@click.option("--async", "async_", is_flag=True, default=False, help="Run async hooks only")
+@click.pass_obj
+def run(state: CliState, event: str, async_: bool) -> None:
+    state.discover()
+    run_event(event, async_=async_, root=state.root)
+
+
+@cli.command(name="generate-settings")
+@click.option("--hooks-dir", default=".claude/hooks", help="Hooks directory relative to project root")
+@click.option("--no-merge", is_flag=True, default=False, help="Output standalone JSON instead of merging")
+@click.option(
+    "--from",
+    "from_source",
+    default=DIST_NAME,
+    help=f"Package source for uvx --from (local path or PyPI spec, default: {DIST_NAME})",
+)
+@click.pass_obj
+def generate_settings_cmd(state: CliState, hooks_dir: str, no_merge: bool, from_source: str) -> None:
+    """Generate Claude Code settings JSON for .claude/settings.local.json."""
+    state.discover()
+    if no_merge:
+        click.echo(generate_settings_json(hooks_dir, from_source=from_source))
+    else:
+        settings_path = state.root / ".claude" / "settings.local.json"
+        click.echo(json.dumps(merge_settings(hooks_dir, settings_path, from_source=from_source), indent=2))
 
-    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
+@cli.command()
+@click.option("--json", "json_output", is_flag=True, default=False, help="Emit one JSON record per test (CI mode)")
+@click.pass_obj
+def test(state: CliState, json_output: bool) -> None:
+    """Run inline tests from all registered hooks."""
+    state.discover()
+    run_tests(json_output=json_output)
 
-    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}")
+@cli.command()
+@click.pass_obj
+def init(state: CliState) -> None:
+    """Scaffold hooks directory, bin script, and settings."""
+    init_project(state.root)
+
+
+@cli.command()
+@click.option("--session", default=None, help="Session id or transcript path (hashed) to view")
+@click.option("--tail", type=int, default=None, help="Show only the last N lines")
+def logs(session: str | None, tail: int | None) -> None:
+    """View a recent captain-hook session log."""
+    show_logs(session=session, tail=tail)
+
+
+main = cli

{capt_hook-0.2.0 → capt_hook-0.3.0}/captain_hook/primitives/__init__.py

@@ -29,7 +29,6 @@ from captain_hook.primitives.llm import (
 )
 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",
@@ -46,6 +45,5 @@ __all__ = [
     "nudge",
     "prompt_check",
     "session_id_for",
-    "styleguide",
     "warn_command",
 ]

{capt_hook-0.2.0/captain_hook/styleguide → capt_hook-0.3.0/captain_hook/style}/__init__.py

@@ -8,32 +8,10 @@ from typing import TYPE_CHECKING
 
 from captain_hook.app import on
 from captain_hook.state import hook_name
-from captain_hook.styleguide.query import (
-    Assignment,
-    Call,
-    Class,
-    ControlFlow,
-    Definition,
-    Function,
-    Import,
-    Kind,
-    Module,
-    Query,
-    Slot,
-    TypeChecking,
-    annotated_slots,
-    annotations,
-    calls,
-    has_future_annotations,
-    has_keyword,
-    is_name,
-    name_of,
-    named,
-    parent_map,
-    string_literals,
-)
-from captain_hook.styleguide.scope import changed_lines, read_source, reconstruct_pre
-from captain_hook.styleguide.types import StyleDiffRule, StyleRule, Violation
+from captain_hook.style import matchers
+from captain_hook.style.matchers import Matcher
+from captain_hook.style.scope import changed_lines, read_source, reconstruct_pre
+from captain_hook.style.types import StyleDiffRule, StyleRule, Violation
 from captain_hook.types import Action, Event, FilePath, HookResult, TCondition, TestFile, Tool
 
 if TYPE_CHECKING:
@@ -45,31 +23,11 @@ GUARD_ONLY_IF: tuple[TCondition, ...] = (Tool("Edit|Write"), FilePath("*.py", pr
 GUARD_SKIP_IF: tuple[TCondition, ...] = (TestFile(),)
 
 __all__ = [
-    "Assignment",
-    "Call",
-    "Class",
-    "ControlFlow",
-    "Definition",
-    "Function",
-    "Import",
-    "Kind",
-    "Module",
-    "Query",
-    "Slot",
+    "Matcher",
     "StyleDiffRule",
     "StyleRule",
-    "TypeChecking",
     "Violation",
-    "annotated_slots",
-    "annotations",
-    "calls",
-    "has_future_annotations",
-    "has_keyword",
-    "is_name",
-    "name_of",
-    "named",
-    "parent_map",
-    "string_literals",
+    "matchers",
     "styleguide",
 ]
 
@@ -84,8 +42,8 @@ def styleguide(
 ) -> None:
     """Register one change-scoped hook applying the given style rules to Python edits and writes.
 
-    Each rule is a [`StyleRule`][captain_hook.styleguide.StyleRule] (or
-    [`StyleDiffRule`][captain_hook.styleguide.StyleDiffRule]) subclass whose docstring is its
+    Each rule is a [`StyleRule`][captain_hook.style.StyleRule] (or
+    [`StyleDiffRule`][captain_hook.style.StyleDiffRule]) subclass whose docstring is its
     message. The single registered hook parses the edited file once, runs every rule against the
     post-edit tree, scopes each violation to the changed lines, and emits one aggregated warning
     (or block, when ``block`` is set). Call again with different ``only_if`` / ``skip_if`` /
@@ -123,11 +81,14 @@ def styleguide(
     )(handler)
 
 
-def validate(rule: type[StyleRule]) -> type[StyleRule]:
+def validate(rule: object) -> type[StyleRule]:
     if not (isinstance(rule, type) and issubclass(rule, StyleRule)):
         raise TypeError(f"styleguide() expects StyleRule subclasses, got {rule!r}")
     if rule.__doc__ is None:
         raise ValueError(f"{rule.__name__} must define a docstring — it is the rule's message")
+    base = StyleDiffRule if issubclass(rule, StyleDiffRule) else StyleRule
+    if rule.match is None and rule.check is base.check:
+        raise TypeError(f"{rule.__name__} must define `match` or override `check`")
     return rule
 
 
@@ -145,7 +106,7 @@ def run_rules(rules: list[StyleRule], evt: BaseHookEvent, *, block: bool, max_sh
         sections := [
             section
             for rule in rules
-            if (section := run_one(rule, tree, pre_tree, source, changed, max_shown)) is not None
+            if (section := run_one(rule, tree, pre_tree, changed, max_shown)) is not None
         ]
     ):
         return None
@@ -156,12 +117,9 @@ def run_one(
     rule: StyleRule,
     tree: ast.Module,
     pre_tree: ast.Module | None,
-    source: str,
     changed: set[int],
     max_shown: int,
 ) -> str | None:
-    if rule.trigger and rule.trigger not in source:
-        return None
     match rule:
         case StyleDiffRule() if pre_tree is not None:
             violations = rule.check(pre_tree, tree)