claude-dev-env 1.30.0 → 1.31.0

package/hooks/diagnostic/test_hook_log_init.py

@@ -0,0 +1,227 @@
+"""Failing-first tests for hook_log_init.
+
+Covers: environment variable verification, idempotent DDL apply, sentinel
+insert/select/delete round-trip, and success report format.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from diagnostic import hook_log_init
+from config import hook_log_extractor_constants
+from config.hook_log_extractor_constants import (
+    EXIT_CODE_ENVIRONMENT_MISSING,
+    NEON_DATABASE_URL_ENVIRONMENT_VARIABLE,
+    OUTCOME_INIT_PROBE,
+)
+
+
+def test_main_exits_1_when_neon_database_url_missing(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.delenv(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE, raising=False)
+
+    exit_code = hook_log_init.main()
+
+    assert exit_code == EXIT_CODE_ENVIRONMENT_MISSING
+    captured = capsys.readouterr()
+    assert NEON_DATABASE_URL_ENVIRONMENT_VARIABLE in captured.err
+
+
+def test_main_exits_1_when_neon_database_url_is_empty_string(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Empty NEON_HOOK_LOGS_DATABASE_URL must fire missing-env branch."""
+    monkeypatch.setenv(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE, "")
+
+    exit_code = hook_log_init.main()
+
+    assert exit_code == EXIT_CODE_ENVIRONMENT_MISSING
+    captured = capsys.readouterr()
+    assert NEON_DATABASE_URL_ENVIRONMENT_VARIABLE in captured.err
+
+
+def test_main_exits_1_when_neon_database_url_is_whitespace_only(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Whitespace-only NEON_HOOK_LOGS_DATABASE_URL must fire missing-env branch."""
+    monkeypatch.setenv(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE, "   ")
+
+    exit_code = hook_log_init.main()
+
+    assert exit_code == EXIT_CODE_ENVIRONMENT_MISSING
+    captured = capsys.readouterr()
+    assert NEON_DATABASE_URL_ENVIRONMENT_VARIABLE in captured.err
+
+
+def test_apply_schema_executes_ddl_from_schema_sql() -> None:
+    fake_cursor = MagicMock()
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    hook_log_init.apply_schema(fake_connection)
+
+    all_executed_statements = [
+        each_call.args[0] for each_call in fake_cursor.execute.call_args_list
+    ]
+    joined_schema_text = "\n".join(all_executed_statements)
+    assert "hook_events" in joined_schema_text
+    assert "CREATE TABLE IF NOT EXISTS" in joined_schema_text
+    assert "blocked_commands" in joined_schema_text
+
+
+def test_run_sentinel_round_trip_inserts_selects_and_deletes() -> None:
+    fake_cursor = MagicMock()
+    fake_cursor.fetchone.side_effect = [(1,), (1,)]
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    hook_log_init.run_sentinel_round_trip(fake_connection)
+
+    all_executed_statements = [
+        each_call.args[0].upper() for each_call in fake_cursor.execute.call_args_list
+    ]
+    assert any("INSERT" in each_statement for each_statement in all_executed_statements)
+    assert any("SELECT" in each_statement for each_statement in all_executed_statements)
+    assert any("DELETE" in each_statement for each_statement in all_executed_statements)
+
+
+def test_run_sentinel_round_trip_uses_init_probe_outcome() -> None:
+    fake_cursor = MagicMock()
+    fake_cursor.fetchone.side_effect = [(1,), (1,)]
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    hook_log_init.run_sentinel_round_trip(fake_connection)
+
+    all_call_parameters = [
+        each_call.args for each_call in fake_cursor.execute.call_args_list
+    ]
+    joined_parameter_text = " ".join(
+        str(each_parameter_tuple) for each_parameter_tuple in all_call_parameters
+    )
+    assert OUTCOME_INIT_PROBE in joined_parameter_text
+
+
+def test_print_success_report_includes_host_table_and_rowcount(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    hook_log_init.print_success_report(
+        neon_host="ep-fake-neon.aws.neon.tech",
+        table_name="hook_events",
+        row_count=42,
+    )
+
+    captured = capsys.readouterr()
+    assert "ep-fake-neon.aws.neon.tech" in captured.out
+    assert "hook_events" in captured.out
+    assert "42" in captured.out
+
+
+def test_main_happy_path_returns_zero(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(
+        NEON_DATABASE_URL_ENVIRONMENT_VARIABLE,
+        "postgres://u:p@ep-fake-host.aws.neon.tech/db",
+    )
+
+    fake_cursor = MagicMock()
+    fake_cursor.fetchone.side_effect = [(1,), (1,), (5,)]
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    with patch.object(hook_log_init, "connect_to_neon", return_value=fake_connection):
+        exit_code = hook_log_init.main()
+
+    assert exit_code == 0
+
+
+def test_connect_to_neon_raises_when_psycopg_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv(
+        NEON_DATABASE_URL_ENVIRONMENT_VARIABLE,
+        "postgres://u:p@ep-fake-host.aws.neon.tech/db",
+    )
+
+    with patch.object(hook_log_init, "psycopg", None):
+        with pytest.raises(hook_log_init.MissingPsycopgDependencyError):
+            hook_log_init.connect_to_neon()
+
+
+def test_run_sentinel_round_trip_raises_when_select_returns_nothing() -> None:
+    fake_cursor = MagicMock()
+    fake_cursor.fetchone.side_effect = [(1,), None]
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    with pytest.raises(RuntimeError):
+        hook_log_init.run_sentinel_round_trip(fake_connection)
+
+
+def test_run_sentinel_round_trip_raises_when_select_returns_wrong_id() -> None:
+    fake_cursor = MagicMock()
+    fake_cursor.fetchone.side_effect = [(1,), (999,)]
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    with pytest.raises(RuntimeError):
+        hook_log_init.run_sentinel_round_trip(fake_connection)
+
+
+def test_run_sentinel_round_trip_raises_when_insert_returns_no_row() -> None:
+    fake_cursor = MagicMock()
+    fake_cursor.fetchone.return_value = None
+    fake_connection = MagicMock()
+    fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
+
+    with pytest.raises(RuntimeError):
+        hook_log_init.run_sentinel_round_trip(fake_connection)
+
+
+def test_claude_home_resolver_falls_back_to_home_when_env_var_is_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Empty CLAUDE_HOME must fall back to ~/.claude (not process CWD)."""
+    monkeypatch.setenv("CLAUDE_HOME", "")
+
+    resolved_home = hook_log_extractor_constants._resolve_claude_home_directory()
+
+    expected_home = Path.home() / ".claude"
+    assert resolved_home == expected_home
+
+
+def test_claude_home_resolver_falls_back_to_home_when_env_var_is_whitespace(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Whitespace-only CLAUDE_HOME must fall back to ~/.claude."""
+    monkeypatch.setenv("CLAUDE_HOME", "   ")
+
+    resolved_home = hook_log_extractor_constants._resolve_claude_home_directory()
+
+    expected_home = Path.home() / ".claude"
+    assert resolved_home == expected_home
+
+
+def test_claude_home_resolver_honors_explicit_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """Explicit CLAUDE_HOME path must win over the home fallback."""
+    explicit_claude_home = tmp_path / "explicit-claude-home"
+    monkeypatch.setenv("CLAUDE_HOME", str(explicit_claude_home))
+
+    resolved_home = hook_log_extractor_constants._resolve_claude_home_directory()
+
+    assert resolved_home == explicit_claude_home

package/hooks/diagnostic/test_hook_log_stop_wrapper.py

@@ -0,0 +1,98 @@
+"""Tests for hook_log_stop_wrapper — Stop-hook wrapper that never fails."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from diagnostic import hook_log_stop_wrapper
+from config.hook_log_extractor_constants import (
+    BWS_ACCESS_TOKEN_ENV_VAR,
+    BWS_EXECUTABLE_NAME,
+    FLAG_INCREMENTAL,
+)
+
+
+def test_main_returns_zero_when_bws_missing_and_extractor_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv(BWS_ACCESS_TOKEN_ENV_VAR, raising=False)
+    monkeypatch.setattr(hook_log_stop_wrapper.shutil, "which", lambda _name: None)
+
+    def _raise(*_args: object, **_kwargs: object) -> None:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(hook_log_stop_wrapper.subprocess, "run", _raise)
+
+    assert hook_log_stop_wrapper.main() == 0
+
+
+def test_main_uses_bws_when_token_and_binary_present(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv(BWS_ACCESS_TOKEN_ENV_VAR, "secret-value")
+    monkeypatch.setattr(
+        hook_log_stop_wrapper.shutil,
+        "which",
+        lambda _name: "/usr/local/bin/bws",
+    )
+
+    captured_commands: list[list[str]] = []
+
+    def _fake_run(command_list: list[str], **_kwargs: object) -> None:
+        captured_commands.append(list(command_list))
+
+    monkeypatch.setattr(hook_log_stop_wrapper.subprocess, "run", _fake_run)
+
+    exit_code = hook_log_stop_wrapper.main()
+
+    assert exit_code == 0
+    assert len(captured_commands) == 1
+    assert captured_commands[0][0] == BWS_EXECUTABLE_NAME
+    assert FLAG_INCREMENTAL in captured_commands[0]
+
+
+def test_main_skips_bws_when_token_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv(BWS_ACCESS_TOKEN_ENV_VAR, raising=False)
+    monkeypatch.setattr(
+        hook_log_stop_wrapper.shutil,
+        "which",
+        lambda _name: "/usr/local/bin/bws",
+    )
+
+    captured_commands: list[list[str]] = []
+
+    def _fake_run(command_list: list[str], **_kwargs: object) -> None:
+        captured_commands.append(list(command_list))
+
+    monkeypatch.setattr(hook_log_stop_wrapper.subprocess, "run", _fake_run)
+
+    exit_code = hook_log_stop_wrapper.main()
+
+    assert exit_code == 0
+    assert len(captured_commands) == 1
+    assert BWS_EXECUTABLE_NAME not in captured_commands[0]
+
+
+def test_main_skips_bws_when_binary_missing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(BWS_ACCESS_TOKEN_ENV_VAR, "secret-value")
+    monkeypatch.setattr(hook_log_stop_wrapper.shutil, "which", lambda _name: None)
+
+    captured_commands: list[list[str]] = []
+
+    def _fake_run(command_list: list[str], **_kwargs: object) -> None:
+        captured_commands.append(list(command_list))
+
+    monkeypatch.setattr(hook_log_stop_wrapper.subprocess, "run", _fake_run)
+
+    exit_code = hook_log_stop_wrapper.main()
+
+    assert exit_code == 0
+    assert len(captured_commands) == 1
+    assert BWS_EXECUTABLE_NAME not in captured_commands[0]

package/hooks/hooks.json

@@ -133,6 +133,16 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/hedging_language_blocker.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/question_to_user_enforcer.py",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/diagnostic/hook_log_stop_wrapper.py",
+            "timeout": 30
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.30.0",
+    "version": "1.31.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/ask-user-question-required.md

@@ -0,0 +1,44 @@
+# AskUserQuestion Required
+
+**When this applies:** Any time you would ask the user a question during discovery, scoping, or implementation planning — after the `verify-before-asking` decision checklist confirms the question genuinely belongs to the user.
+
+## Rule
+
+Route every user-directed question through the `AskUserQuestion` tool. Embedded plain-text questions in the final paragraph of an assistant message are blocked by a Stop hook, and the response must be re-output with the ask moved into an `AskUserQuestion` tool call.
+
+## Detection Criteria
+
+The `question_to_user_enforcer` Stop hook inspects the last non-empty paragraph of the response after stripping fenced code blocks, inline code (backticks), and blockquoted lines (`> …`). The response is blocked when either signal is present:
+
+- The final paragraph's last sentence ends with a question mark.
+- The final paragraph contains any of these preamble phrases (case-insensitive, word-boundary matched): `would you like`, `should I`, `do you want`, `which would you prefer`, `let me know if`, `let me know which`, `let me know whether`, `please confirm`, `please let me know`, `want me to`.
+
+## Acceptable Plain-Text Question Patterns
+
+These remain allowed and do not trigger the hook:
+
+- **Rhetorical questions answered in the same paragraph.** `"What happens if the queue is empty? The handler short-circuits cleanly."` The question frames its own answer; the reader never has to respond.
+- **Questions inside code, diffs, or documentation excerpts.** Code fences, inline backticks, and `>` blockquotes are stripped before detection. Quoting a GitHub issue title, a user's prior message, or a log line inside a blockquote is fine.
+- **Middle-paragraph questions when the closing paragraph is declarative.** Only the final paragraph is scanned.
+
+## AskUserQuestion Structure
+
+When a question is genuinely for the user, call the tool with:
+
+- A concise `question` string stating what is needed.
+- A `header` of twelve characters or fewer summarizing the decision.
+- Two to four `options`, each with a short `label` the user can pick. An "Other" free-text fallback is already provided by the UI; do not add one manually.
+- `multiSelect: false` unless the user can genuinely combine choices.
+
+## Why
+
+- **Structured options reduce re-reading friction.** The user sees labeled choices directly rather than scanning prose for the ask.
+- **Transcript clarity.** Tool-use entries are easy to locate in the JSONL transcript; prose questions disappear into the response text.
+- **Reduced drift.** Claude's next turn cannot move past an unanswered structured question; prose questions can be silently bypassed.
+
+## Enforcement
+
+- Hook: `packages/claude-dev-env/hooks/blocking/question_to_user_enforcer.py`, registered on the `Stop` matcher in `packages/claude-dev-env/hooks/hooks.json`.
+- Loop prevention: the hook honors Claude Code's `stop_hook_active` flag and does not re-block on retry.
+- User-facing notice: `USER_FACING_ASKUSERQUESTION_NOTICE` in `packages/claude-dev-env/hooks/config/messages.py`.
+- Related rule: `packages/claude-dev-env/rules/verify-before-asking.md` gates whether the question belongs to the user in the first place.

package/scripts/config/test_spec_implementer_prompt.py

@@ -21,10 +21,6 @@ def _load_config_module():
 groq_bugteam_config = _load_config_module()
 
 
-def test_spec_implementer_prompt_exists():
-    assert hasattr(groq_bugteam_config, "SPEC_IMPLEMENTER_SYSTEM_PROMPT")
-
-
 def test_spec_implementer_prompt_is_non_empty_string():
     prompt_text = groq_bugteam_config.SPEC_IMPLEMENTER_SYSTEM_PROMPT
     assert isinstance(prompt_text, str)

package/scripts/test_groq_bugteam_spec.py

@@ -36,14 +36,6 @@ def _load_spec_module():
 groq_bugteam_spec = _load_spec_module()
 
 
-def test_apply_fix_from_spec_is_callable():
-    assert callable(groq_bugteam_spec.apply_fix_from_spec)
-
-
-def test_run_spec_mode_main_is_callable():
-    assert callable(groq_bugteam_spec.run_spec_mode_main)
-
-
 def test_is_spec_mode_invocation_detects_flag_value_pair():
     assert groq_bugteam_spec.is_spec_mode_invocation(["--mode", "spec"]) is True
     assert groq_bugteam_spec.is_spec_mode_invocation(["--mode", "pipeline"]) is False