capt-hook 10.2.0__tar.gz → 10.4.0__tar.gz

{capt_hook-10.2.0 → capt_hook-10.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capt-hook
-Version: 10.2.0
+Version: 10.4.0
 Summary: Stop repeating yourself to Claude.
 Project-URL: Homepage, https://github.com/yasyf/captain-hook
 Project-URL: Documentation, https://yasyf.github.io/captain-hook/

{capt_hook-10.2.0 → capt_hook-10.4.0}/captain_hook/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "captain-hook",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "displayName": "Captain Hook",
   "description": "Skills for the capt-hook declarative hook framework: bootstrap gates and nudges from a repo's conventions, and translate style guides into enforced StyleRules.",
   "author": {

{capt_hook-10.2.0 → capt_hook-10.4.0}/captain_hook/ast_grep.py

@@ -18,9 +18,11 @@ import re
 from collections import Counter
 from collections.abc import Iterable, Iterator, Set
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NamedTuple
 
 from captain_hook.langs import COMMENT_TYPES as GENERATED_COMMENT_TYPES
+from captain_hook.langs import DOC_COMMENT_KINDS as GENERATED_DOC_COMMENT_KINDS
+from captain_hook.langs import DOC_SIBLINGS as GENERATED_DOC_SIBLINGS
 from captain_hook.langs import LANG_GLOBS
 
 if TYPE_CHECKING:
@@ -46,39 +48,11 @@ MAX_COMMENT_LINES = 3
 MAX_COMMENT_CHARS = 200
 MAX_COMMENT_SCAN_BYTES = 512_000
 
-DOC_PREFIXES: dict[str, tuple[str, ...]] = {
-    "rs": ("///", "//!", "/**", "/*!"),
-    "js": ("/**",),
-    "jsx": ("/**",),
-    "ts": ("/**",),
-    "tsx": ("/**",),
-    "java": ("/**",),
-    "kotlin": ("/**",),
-    "swift": ("///", "/**"),
-    "dart": ("///",),
-    "cs": ("///",),
-    "php": ("/**",),
-    "scala": ("/**",),
-}
-"""Comment prefixes that mark a documentation comment, by language."""
-
-GO_DOC_SIBLINGS: frozenset[str] = frozenset(
-    {
-        "function_declaration",
-        "method_declaration",
-        "type_declaration",
-        "var_declaration",
-        "const_declaration",
-        "package_clause",
-        "const_spec",
-        "var_spec",
-        "field_declaration",
-        "import_declaration",
-        "method_elem",
-    }
-)
-"""Kinds a Go run must immediately precede to read as godoc — top-level declarations plus grouped
-``const``/``var`` specs, struct fields, imports, and interface methods (which nest below the file)."""
+DOC_COMMENT_KINDS: frozenset[str] = GENERATED_DOC_COMMENT_KINDS
+"""Grammar-defined kinds that natively mark a documentation comment."""
+
+DOC_SIBLINGS: dict[str, frozenset[str]] = GENERATED_DOC_SIBLINGS
+"""Concrete declaration kinds a comment run may document, by language."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -179,6 +153,16 @@ def introduced_comments(old: str, new: str, lang: str) -> Iterator[Match]:
     return introduced(comments(old, lang), comments(new, lang))
 
 
+class CommentSegment(NamedTuple):
+    """Line and character sizes of one alphanumeric-bearing portion of a comment block."""
+
+    lines: int
+    chars: int
+
+    def over(self, max_lines: int, max_chars: int) -> bool:
+        return self.lines > max_lines or self.chars > max_chars
+
+
 @dataclass(frozen=True, slots=True)
 class CommentRun:
     """A maximal run of adjacent line-leading comments (or one block comment), located by 1-based
@@ -209,7 +193,8 @@ class CommentRun:
 class CommentBlock:
     """One or more comment runs a size check treats as a unit: adjacent line-leading runs and the
     paragraphs they form across blank-only gaps. ``lines``/``chars`` sum the constituent runs (the
-    blank gaps don't count), and the block is doc only when every run is."""
+    blank gaps don't count), the block is doc only when every run is, and doc budgets split its
+    opening paragraph from the combined trailing paragraphs without changing the runs."""
 
     runs: tuple[CommentRun, ...]
 
@@ -237,9 +222,40 @@ class CommentBlock:
     def key(self) -> str:
         return " ".join("\n".join(t for run in self.runs for t in run.texts).split())
 
+    @property
+    def doc_paragraphs(self) -> tuple[CommentSegment, CommentSegment]:
+        """Opening and trailing doc portions, split at the first alphanumeric-free row.
+
+        A bare comment leader, gutter, divider, or source gap between runs is a separator. Decoration
+        and separator rows count toward neither portion.
+        """
+        rows = [row for run in self.runs for text in ("", *run.texts) for row in text.rstrip("\n").split("\n")]
+        head: list[str] = []
+        tail: list[str] = []
+        head_chars = 0
+        tail_chars = 0
+        parted = False
+        for row in rows:
+            content = any(c.isalnum() for c in row)
+            if not content:
+                parted = parted or bool(head)
+            if parted:
+                tail_chars += len(row)
+                if content:
+                    tail.append(row)
+            else:
+                head_chars += len(row)
+                if content:
+                    head.append(row)
+        return CommentSegment(len(head), head_chars), CommentSegment(len(tail), tail_chars)
+
     @property
     def too_long(self) -> bool:
-        return self.lines > MAX_COMMENT_LINES or self.chars > MAX_COMMENT_CHARS
+        """Whether the block exceeds its plain or documentation-comment budget."""
+        if not self.doc:
+            return self.lines > MAX_COMMENT_LINES or self.chars > MAX_COMMENT_CHARS
+        head, tail = self.doc_paragraphs
+        return head.over(6, 400) or tail.over(MAX_COMMENT_LINES, MAX_COMMENT_CHARS)
 
 
 def line_span(node: SyntaxNode) -> tuple[int, int]:
@@ -262,19 +278,19 @@ def is_line_leading(node: SyntaxNode, src_lines: list[str]) -> bool:
 
 
 def is_doc_run(nodes: list[SyntaxNode], lang: str) -> bool:
-    """Whether a comment run is a documentation comment (godoc / rustdoc / JSDoc).
+    """Whether a comment run is a documentation comment.
 
-    Prefix languages (rustdoc ``///``, JSDoc ``/**``) require *every* node to carry a doc marker, so
-    a marker line followed by plain narrative doesn't poison the run doc. Go has no prefix: a run is
-    godoc when its next named sibling — a declaration, grouped spec, struct field, import, or
-    interface method — begins on the immediately following line (a blank line breaks the bond).
+    Native markers require every node to carry a grammar-defined doc kind, so narrative cannot ride
+    one marked line. Otherwise, a run is documentation when its next sibling is a declaration that
+    begins on the immediately following line; a blank line breaks the bond.
     """
-    if prefixes := DOC_PREFIXES.get(lang):
-        return all(n.text.startswith(prefixes) for n in nodes)
-    if lang != "go":
-        return False
+    if all(
+        node.kind in DOC_COMMENT_KINDS or any(child.kind() in DOC_COMMENT_KINDS for child in node.raw.children())
+        for node in nodes
+    ):
+        return True
     last = nodes[-1].raw
-    if (nxt := last.next()) is None or nxt.kind() not in GO_DOC_SIBLINGS:
+    if (nxt := last.next()) is None or nxt.kind() not in DOC_SIBLINGS[lang]:
         return False
     return nxt.range().start.line == last.range().end.line + 1
 
@@ -343,19 +359,22 @@ def touched_comment_blocks(old: str, new: str, lang: str) -> list[CommentBlock]:
     """Comment blocks of ``new`` this edit created or grew — a multiset diff over :attr:`CommentBlock.key`.
 
     An old block exempts one identically-keyed new block (a genuine move stays exempt; a duplicated
-    copy past the first counts as touched). A too-long new block is exempt only when an old block
-    with the same key was *also* too long, so a legacy oversized run stays quiet while a reflow that
-    pushes a previously-fine run over the threshold does not.
+    copy past the first counts as touched). An over-budget new block is exempt only when an old block
+    with the same key was *also* over budget, so a legacy oversized run stays quiet while a reflow
+    that pushes a previously-fine run over its budget does not.
     """
     old_blocks = comment_blocks(old, lang)
     remaining = Counter(block.key for block in old_blocks)
-    old_too_long = {block.key for block in old_blocks if block.too_long}
+    old_too_long = Counter(block.key for block in old_blocks if block.too_long)
     touched: list[CommentBlock] = []
     for block in comment_blocks(new, lang):
         if remaining[block.key] > 0:
             remaining[block.key] -= 1
-            if block.too_long and block.key not in old_too_long:
-                touched.append(block)
+            if block.too_long:
+                if old_too_long[block.key] > 0:
+                    old_too_long[block.key] -= 1
+                else:
+                    touched.append(block)
         else:
             touched.append(block)
     return touched

{capt_hook-10.2.0 → capt_hook-10.4.0}/captain_hook/cli.py

@@ -18,6 +18,7 @@ from loguru import logger
 
 from captain_hook.app import AsyncDecisionError, _state, load_gitignore, reset
 from captain_hook.dispatch import dispatch
+from captain_hook.helper.cli import helper
 from captain_hook.loader import (
     CONF_MODULE,
     discover_hooks,
@@ -875,6 +876,7 @@ def pack_update(state: CliState, name: str | None) -> None:
 
 
 cli.add_command(review)
+cli.add_command(helper)
 
 
 @cli.group(hidden=True)

capt_hook-10.4.0/captain_hook/helper/__init__.py

@@ -0,0 +1,8 @@
+"""The Captain Hook desktop helper's Python seam: paths, the socket client, and the CLI.
+
+The helper itself is a signed macOS app; this package is the ``capt-hook`` side that
+addresses it — the frozen ``helper.sock`` protocol client (:mod:`captain_hook.helper.client`)
+and the ``capt-hook helper`` command group (:mod:`captain_hook.helper.cli`).
+"""
+
+from __future__ import annotations

capt_hook-10.4.0/captain_hook/helper/cli.py

@@ -0,0 +1,59 @@
+"""The ``capt-hook helper`` command group — install, ping, and test the desktop helper.
+
+These are the user-facing surface for ``Captain Hook.app``: ``install`` installs the cask and
+launches it, ``status`` pings the running helper, and ``notify`` fires a test banner through
+:mod:`captain_hook.helper.client`. Every side effect (brew, ``open``, the socket) runs only
+when the command is invoked, never at import.
+"""
+
+from __future__ import annotations
+
+import click
+
+from captain_hook.helper import client
+
+CASK = "yasyf/tap/captain-hook"
+APP_PATH = "/Applications/Captain Hook.app"
+
+
+@click.group()
+def helper() -> None:
+    """Manage the Captain Hook desktop notification helper."""
+
+
+@helper.command()
+def install() -> None:
+    """Install or upgrade the signed helper via Homebrew, then launch it in the background."""
+    import subprocess
+
+    subprocess.run(["brew", "install", "--cask", "--force", CASK], check=True)
+    if subprocess.run(["open", "-g", APP_PATH], capture_output=True).returncode != 0:
+        subprocess.run(["open", "-g", "-a", client.APP_NAME], check=False)
+    click.echo(
+        "Captain Hook installed. Grant notification permission under "
+        "System Settings > Notifications > Captain Hook, then add the review widget via "
+        "Edit Widgets in Notification Center."
+    )
+
+
+@helper.command()
+def status() -> None:
+    """Ping the running helper and print its reported version."""
+    try:
+        reply = client.send({"v": client.PROTOCOL, "op": "ping"})
+    except (OSError, ValueError) as exc:
+        raise click.ClickException(f"helper not reachable: {exc}") from exc
+    click.echo(f"helper v{reply.get('version')} ok={reply.get('ok')}")
+
+
+@helper.command()
+@click.option("--kind", default="pr_open", help="Notification kind (pr_open/pr_merged/review_failure)")
+@click.option("--title", default="Captain Hook test", help="Banner title")
+@click.option("--subtitle", default=None, help="Banner subtitle")
+@click.option("--body", default="This is a test notification", help="Banner body")
+@click.option("--url", default=None, help="Click-through URL")
+@click.option("--repo", default=None, help="Repo key threading related notifications")
+def notify(kind: str, title: str, subtitle: str | None, body: str | None, url: str | None, repo: str | None) -> None:
+    """Send a test notification through the helper, launching it if needed."""
+    outcome = client.notify(kind=kind, title=title, subtitle=subtitle, body=body, url=url, repo=repo)
+    click.echo(f"lane={outcome.lane} ok={outcome.ok} error={outcome.error}")

capt_hook-10.4.0/captain_hook/helper/client.py

@@ -0,0 +1,201 @@
+"""The frozen ``~/.capt-hook/helper.sock`` protocol client — the single notify seam.
+
+The desktop helper (``Captain Hook.app``) serves a newline-delimited JSON request/response
+socket, one request per connection, LF-terminated, protocol version ``v`` 1 — the framing
+conventions of :mod:`captain_hook.daemon.protocol`. This module is the ``capt-hook`` client:
+it encodes a request (:func:`send`), and :func:`notify` drives the full connect → launch →
+poll loop the review pipeline fires a notification through, modeled on
+:mod:`capt_hook_client.client`'s ``exchange``/connect-then-spawn shape.
+
+The paths module lives here too — :func:`helper_dir`, :func:`socket_path`, :func:`status_path`
+are what every other helper-facing module imports. ``CAPT_HOOK_HELPER_DIR`` overrides the
+location for tests only; the sandboxed widget appex always reads the literal ``~/.capt-hook``.
+
+:func:`notify` never raises into its caller: it catches only ``OSError`` (connect/timeout),
+``subprocess.SubprocessError`` (the ``open`` launch), and ``json.JSONDecodeError`` (a garbled
+reply), and returns a typed :class:`NotifyOutcome` — a dropped notification is logged, never
+an exception on the review hot path. There is no ``osascript`` fallback: the only lanes are
+the socket and a logged drop.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import subprocess
+import time
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+from captain_hook.util import reqenv
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+PROTOCOL = 1
+APP_NAME = "Captain Hook"
+
+SOCKET_TIMEOUT = 2.0
+OPEN_TIMEOUT = 5.0
+LAUNCH_POLL_INTERVAL = 0.25
+LAUNCH_POLL_BUDGET = 3.0
+RECV_CHUNK = 65536
+LINE_CAP = 65536
+
+
+class Lane(StrEnum):
+    """Which lane delivered (or dropped) a notification.
+
+    ``socket`` — the helper accepted the request over ``helper.sock``. ``dropped`` — the helper
+    was unreachable and could not be launched (or kept refusing), so the notification was logged
+    and discarded. The draft's ``osascript`` lane is removed: an unreachable helper drops.
+    """
+
+    socket = "socket"
+    dropped = "dropped"
+
+
+@dataclass(frozen=True, slots=True)
+class NotifyOutcome:
+    """The typed result of a :func:`notify` — which lane ran, whether it succeeded, and why not.
+
+    Attributes:
+        lane: The lane that handled the request (:attr:`Lane.socket` or :attr:`Lane.dropped`).
+        ok: Whether the helper acknowledged the notification (``ok:true`` on the wire).
+        error: The failure reason — the helper's ``error`` field, or a local drop reason — else ``None``.
+    """
+
+    lane: Lane
+    ok: bool
+    error: str | None
+
+
+def helper_dir() -> Path:
+    """The helper's home — ``~/.capt-hook`` unless ``CAPT_HOOK_HELPER_DIR`` overrides it (tests only)."""
+    if override := reqenv.getenv("CAPT_HOOK_HELPER_DIR"):
+        return Path(override)
+    return Path.home() / ".capt-hook"
+
+
+def socket_path() -> Path:
+    """The helper control socket, ``<helper_dir>/helper.sock``."""
+    return helper_dir() / "helper.sock"
+
+
+def status_path() -> Path:
+    """The snapshot the widget reads, ``<helper_dir>/status.json``."""
+    return helper_dir() / "status.json"
+
+
+def encode(request: Mapping[str, object]) -> bytes:
+    """Encodes one request to its exact wire bytes: compact JSON, declared key order, LF-terminated."""
+    return (json.dumps(request, separators=(",", ":"), ensure_ascii=False) + "\n").encode()
+
+
+def send(request: Mapping[str, object], *, timeout: float = SOCKET_TIMEOUT) -> dict[str, object]:
+    """Sends one request to the helper and returns its decoded reply — one connection, one exchange.
+
+    Raises:
+        OSError: The socket is unreachable, or the deadline expired mid-exchange.
+        json.JSONDecodeError: The helper's reply was not valid JSON.
+    """
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    try:
+        sock.connect(str(socket_path()))
+        sock.sendall(encode(request))
+        line = _read_line(sock)
+    finally:
+        sock.close()
+    return json.loads(line)
+
+
+def _read_line(sock: socket.socket) -> bytes:
+    buf = bytearray()
+    while b"\n" not in buf:
+        if not (chunk := sock.recv(RECV_CHUNK)):
+            raise OSError("helper closed the connection before responding")
+        buf.extend(chunk)
+        if len(buf) > LINE_CAP:
+            raise OSError("helper response exceeded the line cap")
+    return bytes(buf)
+
+
+def notify(
+    *,
+    title: str,
+    kind: str,
+    subtitle: str | None = None,
+    body: str | None = None,
+    url: str | None = None,
+    repo: str | None = None,
+) -> NotifyOutcome:
+    """Fires one notification through the helper, launching it if needed — never raises.
+
+    Tries the socket; on failure launches ``Captain Hook.app`` with ``open -g`` and polls the
+    socket for up to :data:`LAUNCH_POLL_BUDGET` seconds; a helper that stays unreachable (or was
+    never installed, so ``open`` fails fast) drops with a logged warning.
+
+    Args:
+        title: The banner title (required).
+        kind: The notification kind (``pr_open``/``pr_merged``/``review_failure``).
+        subtitle: The banner subtitle, omitted from the wire when ``None``.
+        body: The banner body, omitted when ``None``.
+        url: The click-through URL (http/https), omitted when ``None``.
+        repo: The repo key threading related notifications, omitted when ``None``.
+    """
+    request: dict[str, object] = {"v": PROTOCOL, "op": "notify", "kind": kind, "title": title}
+    for field, value in (("subtitle", subtitle), ("body", body), ("url", url), ("repo", repo)):
+        if value is not None:
+            request[field] = value
+    if len(encode(request)) > LINE_CAP:
+        logger.warning("capt-hook notify request exceeds the line cap — dropped", kind=kind)
+        return NotifyOutcome(Lane.dropped, ok=False, error="request exceeds line cap")
+
+    if (outcome := _try_socket(request)) is not None:
+        return outcome
+    if not _launch():
+        logger.info("capt-hook helper not reachable and not launchable — notification dropped", kind=kind)
+        return NotifyOutcome(Lane.dropped, ok=False, error="helper not installed")
+    deadline = time.monotonic() + LAUNCH_POLL_BUDGET
+    while time.monotonic() < deadline:
+        time.sleep(LAUNCH_POLL_INTERVAL)
+        if (outcome := _try_socket(request)) is not None:
+            return outcome
+    logger.warning("capt-hook helper did not answer after launch — notification dropped", kind=kind)
+    return NotifyOutcome(Lane.dropped, ok=False, error="helper unreachable after launch")
+
+
+def _try_socket(request: Mapping[str, object]) -> NotifyOutcome | None:
+    """Returns the socket-lane outcome, or ``None`` when the helper is unreachable (relaunch worth trying)."""
+    try:
+        reply = send(request)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(reply, dict):
+        return NotifyOutcome(Lane.socket, ok=False, error=f"malformed reply: {reply!r}")
+    if reply.get("v") != PROTOCOL:
+        return NotifyOutcome(Lane.socket, ok=False, error=f"protocol mismatch: helper v={reply.get('v')!r}")
+    return NotifyOutcome(Lane.socket, ok=bool(reply.get("ok")), error=_reply_error(reply))
+
+
+def _reply_error(reply: Mapping[str, object]) -> str | None:
+    return str(err) if (err := reply.get("error")) is not None else None
+
+
+def _launch() -> bool:
+    """Launches the helper in the background; returns ``False`` when ``open`` fails (helper not installed)."""
+    try:
+        subprocess.run(
+            ["open", "-g", "-a", APP_NAME],
+            check=True,
+            capture_output=True,
+            timeout=OPEN_TIMEOUT,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return True

capt_hook-10.4.0/captain_hook/packs/general/capt-hook.toml

@@ -0,0 +1,6 @@
+[pack]
+name = "general"
+version = "0.28.0"
+description = "Language-agnostic guards: git/jj command safety, doc & prompt nudges, task & plan discipline, model-routing nudges (review, security audit, diagnosis, and bounded decision-light implementation route to gpt-5.6-sol via the codex-wrapper agent; ambiguous/decision-dense/long-run implementation to opus xhigh), a browser-automation delegation nudge for sustained agent-browser/playwright work driven inline on fable, code-review + docs-freshness gates, a detour check-in nudge, blocking verbose-comment enforcement (comment runs over 3 lines / 200 chars denied on the post-edit text; doc comments are grammar-classified — native doc markers or declaration adjacency — and keep only their opening paragraph carved out, under a 6-line / 400-char ceiling; a comment-density warn), a first-turn nudge to batch-load the always-used deferred tools in one ToolSearch call, and delegated-prose nudges that catch doc writing handed to a subagent or workflow without the writing-docs skill, and blocking rm safety (repo-root deletes are denied everywhere, and on the macOS rewrite path so are the filesystem root, home directories, and any directory that contains a git/jj repository; on macOS, outside-repo literal deletes and globs whose at-most-10 matches are each verified are rewritten to trash when available, while oversized or unverifiable globs remain denied everywhere; risky deletes hidden inside `sh`/`bash -c` payloads and `eval` are checked by descending into the nested command; temp/scratch paths exempt)."
+hooks = "."
+nlp = true