hookbell 0.2.0__tar.gz → 0.3.0__tar.gz

{hookbell-0.2.0/hookbell.egg-info → hookbell-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hookbell
-Version: 0.2.0
+Version: 0.3.0
 Summary: Notifies Slack, as a Claude Code hook or as a notify-compatible CLI.
 Author-email: Yukihiko Shinoda <yuk.hik.future@gmail.com>
 Maintainer-email: Yukihiko Shinoda <yuk.hik.future@gmail.com>
@@ -147,8 +147,27 @@ Point Claude Code's `Notification`, `PermissionRequest`, and `Stop` hooks at hoo
 
 Hookbell recognizes a Claude Code hook payload by its `transcript_path` field and posts a message
 built from that transcript: the assistant's own last message when there is one, or a description of
-the pending permission request otherwise. A failed notification here is logged (see `slack.log`)
-rather than raised, so a flaky network never turns into hook-failure noise.
+the pending permission request otherwise. A failed notification here is swallowed rather than raised,
+so a flaky network never turns into hook-failure noise; turn on logging (below) to see why it failed.
+
+### How do I see why a notification failed?
+
+Hookbell writes no log by default. Add `--log-level` to the command (or set `HOOKBELL_LOG_LEVEL`) to
+write hookbell's own logs to `$XDG_CACHE_HOME/hookbell/slack.log` (`~/.cache/hookbell/slack.log` when
+`XDG_CACHE_HOME` is unset):
+
+```json
+{ "type": "command", "command": "uvx hookbell --log-level warning" }
+```
+
+The log file lives outside your project, so it never ends up in a commit, and only you can read it.
+At `debug`, the log includes the raw hook payload, which carries your conversation and tool inputs.
+
+Other libraries stay at WARNING whatever `--log-level` you choose, because their DEBUG output can
+contain credentials — the AWS SDK logs request headers and response bodies verbatim. When you really
+need it, `--dangerously-debug-all-loggers` sets every logger to DEBUG. It is accepted only on the
+command line, never from an environment variable, and prints a warning on every run; remove it as
+soon as you finish debugging.
 
 ### How do I use hookbell in a Docker container?
 

{hookbell-0.2.0 → hookbell-0.3.0}/README.md

@@ -91,8 +91,27 @@ Point Claude Code's `Notification`, `PermissionRequest`, and `Stop` hooks at hoo
 
 Hookbell recognizes a Claude Code hook payload by its `transcript_path` field and posts a message
 built from that transcript: the assistant's own last message when there is one, or a description of
-the pending permission request otherwise. A failed notification here is logged (see `slack.log`)
-rather than raised, so a flaky network never turns into hook-failure noise.
+the pending permission request otherwise. A failed notification here is swallowed rather than raised,
+so a flaky network never turns into hook-failure noise; turn on logging (below) to see why it failed.
+
+### How do I see why a notification failed?
+
+Hookbell writes no log by default. Add `--log-level` to the command (or set `HOOKBELL_LOG_LEVEL`) to
+write hookbell's own logs to `$XDG_CACHE_HOME/hookbell/slack.log` (`~/.cache/hookbell/slack.log` when
+`XDG_CACHE_HOME` is unset):
+
+```json
+{ "type": "command", "command": "uvx hookbell --log-level warning" }
+```
+
+The log file lives outside your project, so it never ends up in a commit, and only you can read it.
+At `debug`, the log includes the raw hook payload, which carries your conversation and tool inputs.
+
+Other libraries stay at WARNING whatever `--log-level` you choose, because their DEBUG output can
+contain credentials — the AWS SDK logs request headers and response bodies verbatim. When you really
+need it, `--dangerously-debug-all-loggers` sets every logger to DEBUG. It is accepted only on the
+command line, never from an environment variable, and prints a warning on every run; remove it as
+soon as you finish debugging.
 
 ### How do I use hookbell in a Docker container?
 

{hookbell-0.2.0 → hookbell-0.3.0}/hookbell/__init__.py

@@ -3,4 +3,4 @@
 
 __author__ = """Yukihiko Shinoda"""
 __email__ = "yuk.hik.future@gmail.com"
-__version__ = "0.2.0"
+__version__ = "0.3.0"

hookbell-0.3.0/hookbell/cli.py

@@ -0,0 +1,145 @@
+# Copyright (c) 2026 Yukihiko Shinoda
+"""Console script for hookbell."""
+
+from __future__ import annotations
+
+import os
+import sys
+from logging import DEBUG
+from logging import WARNING
+from logging import NullHandler
+from logging import basicConfig
+from logging import getLogger
+from pathlib import Path
+
+import click
+
+from hookbell.claude_code.event import ClaudeCodeHookEvent
+from hookbell.claude_code.stdin import ClaudeCodeStdin
+from hookbell.notifiers.factory import NotifierFactory
+from hookbell.notify_style import PlainTextNotification
+
+LOG_LEVELS = ("DEBUG", "INFO", "WARNING", "ERROR")
+
+
+def _cache_home() -> Path:
+    """Return the XDG base directory for user-specific cache files.
+
+    Per the XDG Base Directory Specification, an unset, empty, or relative $XDG_CACHE_HOME is ignored in favor of
+    ~/.cache.
+    """
+    xdg_cache_home = Path(os.environ.get("XDG_CACHE_HOME", ""))
+    return xdg_cache_home if xdg_cache_home.is_absolute() else Path.home() / ".cache"
+
+
+def log_file_path() -> Path:
+    """Return hookbell's log file path under the user's cache directory.
+
+    The path is absolute on purpose: Claude Code runs hooks with the user's project as the current directory, so a
+    relative path would land in that project's working tree, where it could be committed.
+    """
+    return _cache_home() / "hookbell" / "slack.log"
+
+
+def _write_root_logger_to_log_file(root_level: int) -> None:
+    log_file = log_file_path()
+    log_file.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    # The log file can hold sensitive data (raw hook payloads, or credentials when every logger is at DEBUG), so
+    # only the owner may read it. touch()'s mode applies only on creation, so chmod() covers a pre-existing file.
+    log_file.touch(mode=0o600)
+    log_file.chmod(0o600)
+    basicConfig(filename=log_file, level=root_level)
+
+
+def configure_logging(level: str | None, *, dangerously_debug_all_loggers: bool = False) -> None:
+    """Configure where and how verbosely hookbell logs.
+
+    Args:
+        level: Level for hookbell's own loggers. Third-party loggers stay at WARNING regardless, since their DEBUG
+            output (e.g. botocore's wire traces) can contain credentials. None disables logging entirely.
+        dangerously_debug_all_loggers: Set the root logger, and so every third-party logger, to DEBUG. Overrides
+            level.
+    """
+    if dangerously_debug_all_loggers:
+        click.echo(
+            f"Warning: --dangerously-debug-all-loggers writes DEBUG logs of every library to {log_file_path()}. "
+            "They can include credentials (e.g. AWS SDK wire traces). Remove the option once you finish debugging.",
+            err=True,
+        )
+        _write_root_logger_to_log_file(DEBUG)
+        return
+    if level is None:
+        # Without any handler, the logging module's last-resort handler would still print WARNING and above to
+        # stderr.
+        basicConfig(handlers=[NullHandler()])
+        return
+    _write_root_logger_to_log_file(WARNING)
+    getLogger("hookbell").setLevel(level.upper())
+
+
+@click.command()
+@click.option(
+    "--log-level",
+    envvar="HOOKBELL_LOG_LEVEL",
+    type=click.Choice(LOG_LEVELS, case_sensitive=False),
+    default=None,
+    help="Write hookbell's logs at this level to $XDG_CACHE_HOME/hookbell/slack.log. Logging is off when omitted.",
+)
+# Reason for no envvar: an environment variable silently persists in shell profiles and container settings, so this
+# option is accepted only on the command line, where it stays visible in the hook command itself.
+@click.option(
+    "--dangerously-debug-all-loggers",
+    is_flag=True,
+    help="Write DEBUG logs of every library, including credentials in AWS SDK wire traces, to the log file.",
+)
+def main(log_level: str | None, *, dangerously_debug_all_loggers: bool) -> int:
+    """Notify Slack, either as a Claude Code hook or from any piped input.
+
+    Reads stdin (unless it is a TTY) and decides which mode applies: a Claude Code hook payload (JSON carrying
+    "transcript_path") is reported through its referenced transcript; anything else is posted as free-form text.
+    """
+    configure_logging(log_level, dangerously_debug_all_loggers=dangerously_debug_all_loggers)
+    raw_stdin = "" if sys.stdin.isatty() else sys.stdin.read()
+    claude_code_stdin = ClaudeCodeStdin.parse(raw_stdin) if raw_stdin else None
+    if claude_code_stdin is not None:
+        _notify_claude_code_hook(claude_code_stdin)
+    else:
+        _notify_plain_text(raw_stdin)
+    return 0
+
+
+def _notify_claude_code_hook(claude_code_stdin: ClaudeCodeStdin) -> None:
+    # Reason: This runs as a Claude Code hook, where a failed notification is best-effort side-
+    # channel noise rather than something that should surface as this hook's own failure. Logging
+    # and swallowing keeps a transient issue (a malformed transcript line, the network being
+    # briefly down, an unreachable webhook, or both destinations being configured at once) from
+    # producing hook-failure feedback for a non-critical path. The failure surface spans stdlib
+    # json, pathlib and urllib, boto3, plus future code, so narrowing to specific exception types
+    # would leave gaps:
+    # - Pylint broad-exception-caught (W0718): no narrower alternative fits an evolving surface
+    #   https://pylint.readthedocs.io/en/latest/user_guide/messages/warning/broad-exception-caught.html
+    try:
+        NotifierFactory.from_environment().notify(ClaudeCodeHookEvent(claude_code_stdin).text)
+    except Exception:  # pylint: disable=broad-exception-caught
+        getLogger(__name__).exception("Failed to notify Claude Code hook event")
+
+
+def _notify_plain_text(raw_stdin: str) -> None:
+    # Reason: same broad failure surface as _notify_claude_code_hook above, but this branch is a
+    # direct, interactive invocation, so the failure is surfaced to the caller by re-raising as
+    # ClickException instead of only logged. Click's standalone mode ignores this
+    # command callback's own return value for the process exit code (only a raised exception, or an
+    # explicit ctx.exit(), controls it), and ClickException is the one exception type Click always
+    # turns into a clean "Error: ..." message on stderr plus a guaranteed exit code of exactly 1:
+    # - Pylint broad-exception-caught (W0718): no narrower alternative fits an evolving surface
+    #   https://pylint.readthedocs.io/en/latest/user_guide/messages/warning/broad-exception-caught.html
+    try:
+        NotifierFactory.from_environment().notify(PlainTextNotification(raw_stdin).text)
+    except Exception as error:  # pylint: disable=broad-exception-caught
+        raise click.ClickException(str(error)) from error
+
+
+if __name__ == "__main__":
+    # Command.main() rather than the equivalent main(): Pylint checks main() against the undecorated signature, not
+    # the click.Command the decorators return, so it reports the options Click parses from sys.argv as missing.
+    sys.exit(main.main())  # pragma: no cover

{hookbell-0.2.0 → hookbell-0.3.0}/hookbell/notifiers/sns.py

@@ -20,8 +20,8 @@ class SnsNotifier(Notifier):
     https://docs.aws.amazon.com/chatbot/latest/adminguide/custom-notifs.html#event-schema
     """
 
-    TOPIC_ARN_SECRET_PATH = Path("/run/secrets/hookbell-sns-topic-arn")
-    AWS_PROFILE_SECRET_PATH = Path("/run/secrets/hookbell-aws-profile")
+    TOPIC_ARN_SECRET_PATH = Path("/run/secrets/hookbell_sns_topic_arn")
+    AWS_PROFILE_SECRET_PATH = Path("/run/secrets/hookbell_aws_profile")
     TOPIC_ARN_ENVIRONMENT_VARIABLE = "HOOKBELL_SNS_TOPIC_ARN"
     AWS_PROFILE_ENVIRONMENT_VARIABLE = "HOOKBELL_AWS_PROFILE"
 

{hookbell-0.2.0 → hookbell-0.3.0/hookbell.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hookbell
-Version: 0.2.0
+Version: 0.3.0
 Summary: Notifies Slack, as a Claude Code hook or as a notify-compatible CLI.
 Author-email: Yukihiko Shinoda <yuk.hik.future@gmail.com>
 Maintainer-email: Yukihiko Shinoda <yuk.hik.future@gmail.com>
@@ -147,8 +147,27 @@ Point Claude Code's `Notification`, `PermissionRequest`, and `Stop` hooks at hoo
 
 Hookbell recognizes a Claude Code hook payload by its `transcript_path` field and posts a message
 built from that transcript: the assistant's own last message when there is one, or a description of
-the pending permission request otherwise. A failed notification here is logged (see `slack.log`)
-rather than raised, so a flaky network never turns into hook-failure noise.
+the pending permission request otherwise. A failed notification here is swallowed rather than raised,
+so a flaky network never turns into hook-failure noise; turn on logging (below) to see why it failed.
+
+### How do I see why a notification failed?
+
+Hookbell writes no log by default. Add `--log-level` to the command (or set `HOOKBELL_LOG_LEVEL`) to
+write hookbell's own logs to `$XDG_CACHE_HOME/hookbell/slack.log` (`~/.cache/hookbell/slack.log` when
+`XDG_CACHE_HOME` is unset):
+
+```json
+{ "type": "command", "command": "uvx hookbell --log-level warning" }
+```
+
+The log file lives outside your project, so it never ends up in a commit, and only you can read it.
+At `debug`, the log includes the raw hook payload, which carries your conversation and tool inputs.
+
+Other libraries stay at WARNING whatever `--log-level` you choose, because their DEBUG output can
+contain credentials — the AWS SDK logs request headers and response bodies verbatim. When you really
+need it, `--dangerously-debug-all-loggers` sets every logger to DEBUG. It is accepted only on the
+command line, never from an environment variable, and prints a warning on every run; remove it as
+soon as you finish debugging.
 
 ### How do I use hookbell in a Docker container?
 

{hookbell-0.2.0 → hookbell-0.3.0}/pyproject.toml

@@ -15,7 +15,7 @@ dev = [
 
 [project]
 name = "hookbell"
-version = "0.2.0"
+version = "0.3.0"
 description = "Notifies Slack, as a Claude Code hook or as a notify-compatible CLI."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -79,7 +79,7 @@ hookbell = "hookbell.cli:main"
 skips = ["tests/*"]
 
 [tool.bumpversion]
-current_version = "0.2.0"
+current_version = "0.3.0"
 commit = true
 tag = true
 

hookbell-0.3.0/tests/test_cli.py

@@ -0,0 +1,251 @@
+# Copyright (c) 2026 Yukihiko Shinoda
+"""Tests for hookbell.cli."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import stat
+
+# Reason: Bandit flags any import of subprocess, but its only use here runs a constant argv without a shell, which
+# TestLoggingConfiguration needs to observe the logging configuration in a fresh interpreter:
+# - Blacklist Imports - B404: import_subprocess — Bandit documentation
+#   https://bandit.readthedocs.io/en/latest/blacklists/blacklist_imports.html#b404-import-subprocess
+import subprocess  # nosec B404
+import sys
+from typing import TYPE_CHECKING
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from hookbell import cli
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from unittest.mock import MagicMock
+
+    from pytest_mock import MockerFixture
+
+
+@pytest.fixture(autouse=True)
+def _slack_webhook_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SLACK_WEBHOOK_URL", "https://hooks.slack.com/services/T000/B000/XXX")
+
+
+@pytest.fixture(name="urlopen")
+def _urlopen_fixture(mocker: MockerFixture) -> MagicMock:
+    mock = mocker.patch("hookbell.notifiers.slack.request.urlopen")
+    mock.return_value.__enter__.return_value.read.return_value = b"ok"
+    return mock
+
+
+class TestMainHelp:
+    def test_shows_usage(self) -> None:
+        result = CliRunner().invoke(cli.main, ["--help"])
+
+        assert result.exit_code == 0
+        assert "Show this message and exit." in result.output
+
+
+class TestMainPlainTextMode:
+    """Tests for main() when stdin is not a Claude Code hook payload."""
+
+    def test_notifies_the_default_text_when_stdin_was_not_piped(self, urlopen: MagicMock) -> None:
+        result = CliRunner().invoke(cli.main, input=None)
+
+        assert result.exit_code == 0
+        posted = json.loads(urlopen.call_args.args[0].data.decode("utf-8"))
+        assert posted["blocks"][0]["text"]["text"] == "Finished!"
+
+    def test_notifies_the_piped_plain_text(self, urlopen: MagicMock) -> None:
+        result = CliRunner().invoke(cli.main, input="Hello world\n")
+
+        assert result.exit_code == 0
+        posted = json.loads(urlopen.call_args.args[0].data.decode("utf-8"))
+        assert "Hello world" in posted["blocks"][0]["text"]["text"]
+
+    def test_reports_notification_failures_as_a_clean_error_and_exits_1(self, mocker: MockerFixture) -> None:
+        mocker.patch("hookbell.notifiers.slack.request.urlopen", side_effect=OSError("boom"))
+
+        result = CliRunner().invoke(cli.main, input="Hello world\n")
+
+        assert result.exit_code == 1
+        assert "Error: boom" in result.output
+
+    def test_reports_both_destinations_configured_as_a_clean_error_and_exits_1(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Report the NotifierFactory conflict error the same way as any other notification failure."""
+        monkeypatch.setenv("HOOKBELL_SNS_TOPIC_ARN", "arn:aws:sns:us-east-1:123456789012:hookbell")
+
+        result = CliRunner().invoke(cli.main, input="Hello world\n")
+
+        assert result.exit_code == 1
+        assert "exactly one destination" in result.output
+
+
+class TestMainClaudeCodeHookMode:
+    """Tests for main() when stdin is a Claude Code hook payload."""
+
+    def test_notifies_through_the_referenced_transcript(self, tmp_path: Path, urlopen: MagicMock) -> None:
+        """Notify with text composed from the payload's referenced transcript."""
+        entry = {"message": {"content": [{"type": "text", "text": "Hello from assistant"}]}}
+        transcript_path = tmp_path / "transcript.jsonl"
+        transcript_path.write_text(json.dumps(entry) + "\n", encoding="utf-8")
+        payload = json.dumps({"hook_event_name": "Stop", "transcript_path": str(transcript_path)})
+
+        result = CliRunner().invoke(cli.main, input=payload)
+
+        assert result.exit_code == 0
+        posted = json.loads(urlopen.call_args.args[0].data.decode("utf-8"))
+        assert "Hello from assistant" in posted["blocks"][0]["text"]["text"]
+
+    def test_swallows_notification_failures_and_still_exits_0(self, tmp_path: Path) -> None:
+        payload = json.dumps({"hook_event_name": "Stop", "transcript_path": str(tmp_path / "missing.jsonl")})
+
+        result = CliRunner().invoke(cli.main, input=payload)
+
+        assert result.exit_code == 0
+
+    def test_swallows_both_destinations_configured_and_still_exits_0(
+        self,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Swallow the NotifierFactory conflict error the same way as any other notification failure."""
+        monkeypatch.setenv("HOOKBELL_SNS_TOPIC_ARN", "arn:aws:sns:us-east-1:123456789012:hookbell")
+        entry = {"message": {"content": [{"type": "text", "text": "Hello from assistant"}]}}
+        transcript_path = tmp_path / "transcript.jsonl"
+        transcript_path.write_text(json.dumps(entry) + "\n", encoding="utf-8")
+        payload = json.dumps({"hook_event_name": "Stop", "transcript_path": str(transcript_path)})
+
+        result = CliRunner().invoke(cli.main, input=payload)
+
+        assert result.exit_code == 0
+
+
+class TestMainLogging:
+    """Tests for how main() hands its logging options to configure_logging()."""
+
+    @pytest.mark.usefixtures("urlopen")
+    def test_writes_no_log_file_by_default(self) -> None:
+        result = CliRunner().invoke(cli.main, input="Hello world\n")
+
+        assert result.exit_code == 0
+        assert not cli.log_file_path().exists()
+
+    @pytest.mark.usefixtures("urlopen")
+    def test_log_level_option_enables_the_log_file(self) -> None:
+        result = CliRunner().invoke(cli.main, ["--log-level", "debug"], input="Hello world\n")
+
+        assert result.exit_code == 0
+        assert cli.log_file_path().is_file()
+
+    @pytest.mark.usefixtures("urlopen")
+    def test_log_level_is_read_from_the_environment(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Accept HOOKBELL_LOG_LEVEL so the level can be set without editing the hook command."""
+        monkeypatch.setenv("HOOKBELL_LOG_LEVEL", "info")
+
+        result = CliRunner().invoke(cli.main, input="Hello world\n")
+
+        assert result.exit_code == 0
+        assert cli.log_file_path().is_file()
+
+    def test_rejects_an_unknown_log_level(self) -> None:
+        result = CliRunner().invoke(cli.main, ["--log-level", "verbose"], input="Hello world\n")
+
+        assert result.exit_code == click.UsageError.exit_code
+
+    @pytest.mark.usefixtures("urlopen")
+    def test_dangerously_debug_all_loggers_warns_on_stderr(self) -> None:
+        # result.output includes stderr both on Click < 8.2 (mixed by default) and on Click >= 8.2 (interleaved).
+        result = CliRunner().invoke(cli.main, ["--dangerously-debug-all-loggers"], input="Hello world\n")
+
+        assert result.exit_code == 0
+        assert "Warning: --dangerously-debug-all-loggers" in result.output
+
+
+class TestConfigureLogging:
+    """Tests for configure_logging(), observed in a fresh interpreter per test."""
+
+    # Loggers whose DEBUG output contains wire traces: request/response bodies, headers, and URLs that can carry
+    # credentials (e.g. botocore.endpoint's Authorization header, botocore.parsers' STS/SSO response bodies).
+    WIRE_TRACE_LOGGERS = ("botocore", "boto3", "urllib3", "httpx", "httpcore")
+
+    # Reason: The configuration must be observed in a fresh interpreter. Under pytest, the root logger already
+    # has pytest's own handlers, so logging.basicConfig() silently does nothing and an in-process check would pass
+    # regardless of what hookbell configures.
+    PROBE_SCRIPT = """
+import json
+import logging
+import sys
+
+from hookbell.cli import configure_logging
+
+configure_logging(**json.loads(sys.argv[1]))
+print(json.dumps({name: logging.getLogger(name).getEffectiveLevel() for name in sys.argv[2:]}))
+"""
+
+    def test_wire_trace_loggers_not_debug(self, tmp_path: Path) -> None:
+        """Keep third-party wire trace loggers above DEBUG even when hookbell's own logs are at DEBUG."""
+        effective_levels = self._probe(tmp_path, tmp_path / "cache", level="DEBUG")
+
+        assert effective_levels.pop("hookbell") == logging.DEBUG
+        assert {name: level for name, level in effective_levels.items() if level <= logging.DEBUG} == {}
+
+    def test_dangerously_debug_all_loggers_sets_wire_trace_loggers_to_debug(self, tmp_path: Path) -> None:
+        effective_levels = self._probe(tmp_path, tmp_path / "cache", level=None, dangerously_debug_all_loggers=True)
+
+        assert set(effective_levels.values()) == {logging.DEBUG}
+
+    def test_writes_no_log_file_when_level_is_none(self, tmp_path: Path) -> None:
+        cache_home = tmp_path / "cache"
+
+        self._probe(tmp_path, cache_home, level=None)
+
+        assert not cache_home.exists()
+
+    def test_writes_log_file_under_cache_home_not_working_directory(self, tmp_path: Path) -> None:
+        """Keep the log file out of the working tree of whichever project Claude Code runs the hook in."""
+        working_directory = tmp_path / "project"
+        working_directory.mkdir()
+        cache_home = tmp_path / "cache"
+
+        self._probe(working_directory, cache_home, level="DEBUG")
+
+        assert (cache_home / "hookbell" / "slack.log").is_file()
+        assert not list(working_directory.iterdir())
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="Windows doesn't support POSIX permission bits.")
+    def test_log_file_is_readable_only_by_its_owner(self, tmp_path: Path) -> None:
+        cache_home = tmp_path / "cache"
+
+        self._probe(tmp_path, cache_home, level="DEBUG")
+
+        assert stat.S_IMODE((cache_home / "hookbell" / "slack.log").stat().st_mode) == 0o600  # noqa: PLR2004
+
+    def _probe(self, cwd: Path, cache_home: Path, **kwargs: str | bool | None) -> dict[str, int]:
+        """Run configure_logging(**kwargs) in a fresh interpreter and return the effective level of each logger.
+
+        XDG_CACHE_HOME points at a test-owned directory so the probe never writes into the real user's ~/.cache.
+        """
+        # Reason: Every argv element is sys.executable, a constant of this class, or JSON-encoded test arguments, and
+        # no shell is used, but Ruff can't trace the attribute references back to their constant values, and Bandit
+        # flags every shell-less call regardless of the input:
+        # - Ruff rules - subprocess-without-shell-equals-true (S603)
+        #   https://docs.astral.sh/ruff/rules/subprocess-without-shell-equals-true/
+        # - B603: Test for use of subprocess without shell equals true — Bandit documentation
+        #   https://bandit.readthedocs.io/en/latest/plugins/b603_subprocess_without_shell_equals_true.html
+        completed = subprocess.run(  # noqa: S603  # nosec B603
+            [sys.executable, "-c", self.PROBE_SCRIPT, json.dumps(kwargs), "hookbell", *self.WIRE_TRACE_LOGGERS],
+            capture_output=True,
+            check=True,
+            cwd=cwd,
+            env={**os.environ, "XDG_CACHE_HOME": str(cache_home)},
+            text=True,
+        )
+        effective_levels: dict[str, int] = json.loads(completed.stdout)
+        return effective_levels

hookbell-0.2.0/hookbell/cli.py

@@ -1,68 +0,0 @@
-# Copyright (c) 2026 Yukihiko Shinoda
-"""Console script for hookbell."""
-
-import sys
-from logging import DEBUG
-from logging import basicConfig
-from logging import getLogger
-from pathlib import Path
-
-import click
-
-from hookbell.claude_code.event import ClaudeCodeHookEvent
-from hookbell.claude_code.stdin import ClaudeCodeStdin
-from hookbell.notifiers.factory import NotifierFactory
-from hookbell.notify_style import PlainTextNotification
-
-basicConfig(filename=Path("slack.log"), level=DEBUG)
-
-
-@click.command()
-def main() -> int:
-    """Notify Slack, either as a Claude Code hook or from any piped input.
-
-    Reads stdin (unless it is a TTY) and decides which mode applies: a Claude Code hook payload (JSON carrying
-    "transcript_path") is reported through its referenced transcript; anything else is posted as free-form text.
-    """
-    raw_stdin = "" if sys.stdin.isatty() else sys.stdin.read()
-    claude_code_stdin = ClaudeCodeStdin.parse(raw_stdin) if raw_stdin else None
-    if claude_code_stdin is not None:
-        _notify_claude_code_hook(claude_code_stdin)
-    else:
-        _notify_plain_text(raw_stdin)
-    return 0
-
-
-def _notify_claude_code_hook(claude_code_stdin: ClaudeCodeStdin) -> None:
-    # Reason: This runs as a Claude Code hook, where a failed notification is best-effort side-
-    # channel noise rather than something that should surface as this hook's own failure. Logging
-    # and swallowing keeps a transient issue (a malformed transcript line, the network being
-    # briefly down, an unreachable webhook, or both destinations being configured at once) from
-    # producing hook-failure feedback for a non-critical path. The failure surface spans stdlib
-    # json, pathlib and urllib, boto3, plus future code, so narrowing to specific exception types
-    # would leave gaps:
-    # - Pylint broad-exception-caught (W0718): no narrower alternative fits an evolving surface
-    #   https://pylint.readthedocs.io/en/latest/user_guide/messages/warning/broad-exception-caught.html
-    try:
-        NotifierFactory.from_environment().notify(ClaudeCodeHookEvent(claude_code_stdin).text)
-    except Exception:  # pylint: disable=broad-exception-caught
-        getLogger(__name__).exception("Failed to notify Claude Code hook event")
-
-
-def _notify_plain_text(raw_stdin: str) -> None:
-    # Reason: same broad failure surface as _notify_claude_code_hook above, but this branch is a
-    # direct, interactive invocation, so the failure is surfaced to the caller by re-raising as
-    # ClickException instead of only logged. Click's standalone mode ignores this
-    # command callback's own return value for the process exit code (only a raised exception, or an
-    # explicit ctx.exit(), controls it), and ClickException is the one exception type Click always
-    # turns into a clean "Error: ..." message on stderr plus a guaranteed exit code of exactly 1:
-    # - Pylint broad-exception-caught (W0718): no narrower alternative fits an evolving surface
-    #   https://pylint.readthedocs.io/en/latest/user_guide/messages/warning/broad-exception-caught.html
-    try:
-        NotifierFactory.from_environment().notify(PlainTextNotification(raw_stdin).text)
-    except Exception as error:  # pylint: disable=broad-exception-caught
-        raise click.ClickException(str(error)) from error
-
-
-if __name__ == "__main__":
-    sys.exit(main())  # pragma: no cover

hookbell-0.2.0/tests/test_cli.py

@@ -1,116 +0,0 @@
-# Copyright (c) 2026 Yukihiko Shinoda
-"""Tests for hookbell.cli."""
-
-from __future__ import annotations
-
-import json
-from typing import TYPE_CHECKING
-
-import pytest
-from click.testing import CliRunner
-
-from hookbell import cli
-
-if TYPE_CHECKING:
-    from pathlib import Path
-    from unittest.mock import MagicMock
-
-    from pytest_mock import MockerFixture
-
-
-@pytest.fixture(autouse=True)
-def _slack_webhook_url(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setenv("SLACK_WEBHOOK_URL", "https://hooks.slack.com/services/T000/B000/XXX")
-
-
-@pytest.fixture(name="urlopen")
-def _urlopen_fixture(mocker: MockerFixture) -> MagicMock:
-    mock = mocker.patch("hookbell.notifiers.slack.request.urlopen")
-    mock.return_value.__enter__.return_value.read.return_value = b"ok"
-    return mock
-
-
-class TestMainHelp:
-    def test_shows_usage(self) -> None:
-        result = CliRunner().invoke(cli.main, ["--help"])
-
-        assert result.exit_code == 0
-        assert "--help  Show this message and exit." in result.output
-
-
-class TestMainPlainTextMode:
-    """Tests for main() when stdin is not a Claude Code hook payload."""
-
-    def test_notifies_the_default_text_when_stdin_was_not_piped(self, urlopen: MagicMock) -> None:
-        result = CliRunner().invoke(cli.main, input=None)
-
-        assert result.exit_code == 0
-        posted = json.loads(urlopen.call_args.args[0].data.decode("utf-8"))
-        assert posted["blocks"][0]["text"]["text"] == "Finished!"
-
-    def test_notifies_the_piped_plain_text(self, urlopen: MagicMock) -> None:
-        result = CliRunner().invoke(cli.main, input="Hello world\n")
-
-        assert result.exit_code == 0
-        posted = json.loads(urlopen.call_args.args[0].data.decode("utf-8"))
-        assert "Hello world" in posted["blocks"][0]["text"]["text"]
-
-    def test_reports_notification_failures_as_a_clean_error_and_exits_1(self, mocker: MockerFixture) -> None:
-        mocker.patch("hookbell.notifiers.slack.request.urlopen", side_effect=OSError("boom"))
-
-        result = CliRunner().invoke(cli.main, input="Hello world\n")
-
-        assert result.exit_code == 1
-        assert "Error: boom" in result.output
-
-    def test_reports_both_destinations_configured_as_a_clean_error_and_exits_1(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """Report the NotifierFactory conflict error the same way as any other notification failure."""
-        monkeypatch.setenv("HOOKBELL_SNS_TOPIC_ARN", "arn:aws:sns:us-east-1:123456789012:hookbell")
-
-        result = CliRunner().invoke(cli.main, input="Hello world\n")
-
-        assert result.exit_code == 1
-        assert "exactly one destination" in result.output
-
-
-class TestMainClaudeCodeHookMode:
-    """Tests for main() when stdin is a Claude Code hook payload."""
-
-    def test_notifies_through_the_referenced_transcript(self, tmp_path: Path, urlopen: MagicMock) -> None:
-        """Notify with text composed from the payload's referenced transcript."""
-        entry = {"message": {"content": [{"type": "text", "text": "Hello from assistant"}]}}
-        transcript_path = tmp_path / "transcript.jsonl"
-        transcript_path.write_text(json.dumps(entry) + "\n", encoding="utf-8")
-        payload = json.dumps({"hook_event_name": "Stop", "transcript_path": str(transcript_path)})
-
-        result = CliRunner().invoke(cli.main, input=payload)
-
-        assert result.exit_code == 0
-        posted = json.loads(urlopen.call_args.args[0].data.decode("utf-8"))
-        assert "Hello from assistant" in posted["blocks"][0]["text"]["text"]
-
-    def test_swallows_notification_failures_and_still_exits_0(self, tmp_path: Path) -> None:
-        payload = json.dumps({"hook_event_name": "Stop", "transcript_path": str(tmp_path / "missing.jsonl")})
-
-        result = CliRunner().invoke(cli.main, input=payload)
-
-        assert result.exit_code == 0
-
-    def test_swallows_both_destinations_configured_and_still_exits_0(
-        self,
-        tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """Swallow the NotifierFactory conflict error the same way as any other notification failure."""
-        monkeypatch.setenv("HOOKBELL_SNS_TOPIC_ARN", "arn:aws:sns:us-east-1:123456789012:hookbell")
-        entry = {"message": {"content": [{"type": "text", "text": "Hello from assistant"}]}}
-        transcript_path = tmp_path / "transcript.jsonl"
-        transcript_path.write_text(json.dumps(entry) + "\n", encoding="utf-8")
-        payload = json.dumps({"hook_event_name": "Stop", "transcript_path": str(transcript_path)})
-
-        result = CliRunner().invoke(cli.main, input=payload)
-
-        assert result.exit_code == 0