claude-dev-env 1.30.1 → 1.31.0

package/hooks/diagnostic/hook_log_init.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Initialize the Neon schema for hook-log diagnostics.
+
+Verifies required environment variables, opens a psycopg connection,
+applies the idempotent DDL from ``schema.sql``, runs a sentinel
+insert/select/delete round-trip to prove read-write parity, and prints
+a success report with the Neon host, table name, and row count.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+if str(Path(__file__).resolve().parent.parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+try:
+    import psycopg
+except ImportError:
+    psycopg = None
+
+from config.hook_log_extractor_constants import (
+    CONNECT_TIMEOUT_SECONDS,
+    EXIT_CODE_ENVIRONMENT_MISSING,
+    EXIT_CODE_SUCCESS,
+    HOOK_EVENTS_ROW_COUNT_SQL,
+    HOOK_EVENTS_TABLE_NAME,
+    MISSING_ENVIRONMENT_VARIABLE_PREFIX,
+    MISSING_PSYCOPG_WARNING_LABEL,
+    NEON_DATABASE_URL_ENVIRONMENT_VARIABLE,
+    NEON_HOST_REPORT_LABEL,
+    OUTCOME_INIT_PROBE,
+    ROW_COUNT_REPORT_LABEL,
+    SCHEMA_RELATIVE_PATH,
+    SEMICOLON_SPLIT_TOKEN,
+    SENTINEL_DELETE_SQL,
+    SENTINEL_HOOK_CATEGORY,
+    SENTINEL_HOOK_EVENT,
+    SENTINEL_HOOK_NAME,
+    SENTINEL_INSERT_FAILURE_MESSAGE,
+    SENTINEL_INSERT_SQL,
+    SENTINEL_SELECT_FAILURE_MESSAGE,
+    SENTINEL_SELECT_SQL,
+    SENTINEL_SESSION_ID,
+    SENTINEL_SOURCE_LINE_NUMBER,
+    SENTINEL_SOURCE_PATH,
+    SUCCESS_REPORT_HEADER,
+    TABLE_REPORT_LABEL,
+    UNKNOWN_HOST_PLACEHOLDER,
+)
+
+
+class MissingPsycopgDependencyError(RuntimeError):
+    """Raised when the psycopg driver is not installed in the interpreter."""
+
+
+def verify_environment_variables() -> list[str]:
+    """Return names of required env vars that are unset; empty list when all present.
+
+    Only ``NEON_HOOK_LOGS_DATABASE_URL`` is verified here. ``bws run``
+    intentionally strips ``BWS_ACCESS_TOKEN`` from the child environment
+    to prevent subprocess credential leakage; checking for it inside a
+    child process invoked via ``bws run -- python hook_log_init.py``
+    would therefore always fail even when the machine is configured
+    correctly. The one-time ``setx BWS_ACCESS_TOKEN`` prerequisite is
+    documented in ``packages/claude-dev-env/commands/hook-log-init.md``.
+    """
+    all_missing_variable_names: list[str] = []
+    raw_database_url_value = os.environ.get(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE)
+    if raw_database_url_value is None or raw_database_url_value.strip() == "":
+        all_missing_variable_names.append(NEON_DATABASE_URL_ENVIRONMENT_VARIABLE)
+    return all_missing_variable_names
+
+
+def _schema_file_path() -> Path:
+    """Return the absolute path to the companion ``schema.sql`` file."""
+    return Path(__file__).resolve().parent / SCHEMA_RELATIVE_PATH
+
+
+def _split_ddl_statements(schema_text: str) -> list[str]:
+    """Split a DDL file on semicolons and drop empty trailing fragments."""
+    all_raw_fragments = schema_text.split(SEMICOLON_SPLIT_TOKEN)
+    all_trimmed_statements = [
+        each_fragment.strip() for each_fragment in all_raw_fragments
+    ]
+    return [
+        each_statement for each_statement in all_trimmed_statements if each_statement
+    ]
+
+
+def apply_schema(neon_connection: object) -> None:
+    """Execute the idempotent DDL from ``schema.sql`` on the given connection."""
+    schema_text = _schema_file_path().read_text(encoding="utf-8")
+    all_ddl_statements = _split_ddl_statements(schema_text)
+    with neon_connection.cursor() as neon_cursor:
+        for each_statement in all_ddl_statements:
+            neon_cursor.execute(each_statement)
+    neon_connection.commit()
+
+
+def run_sentinel_round_trip(neon_connection: object) -> None:
+    """Insert a sentinel row, select it back by id, verify it, then delete it."""
+    with neon_connection.cursor() as neon_cursor:
+        neon_cursor.execute(
+            SENTINEL_INSERT_SQL,
+            (
+                SENTINEL_SESSION_ID,
+                SENTINEL_HOOK_EVENT,
+                SENTINEL_HOOK_NAME,
+                SENTINEL_HOOK_CATEGORY,
+                OUTCOME_INIT_PROBE,
+                SENTINEL_SOURCE_PATH,
+                SENTINEL_SOURCE_LINE_NUMBER,
+            ),
+        )
+        sentinel_row = neon_cursor.fetchone()
+        if sentinel_row is None:
+            raise RuntimeError(SENTINEL_INSERT_FAILURE_MESSAGE)
+        sentinel_id = sentinel_row[0]
+        neon_cursor.execute(SENTINEL_SELECT_SQL, (sentinel_id,))
+        fetched_row = neon_cursor.fetchone()
+        if fetched_row is None or fetched_row[0] != sentinel_id:
+            raise RuntimeError(SENTINEL_SELECT_FAILURE_MESSAGE)
+        neon_cursor.execute(SENTINEL_DELETE_SQL, (sentinel_id,))
+    neon_connection.commit()
+
+
+def _extract_host_from_database_url(database_url: str) -> str:
+    """Return the hostname portion of a Postgres connection URL."""
+    parsed_url = urlparse(database_url)
+    return parsed_url.hostname or UNKNOWN_HOST_PLACEHOLDER
+
+
+def print_success_report(neon_host: str, table_name: str, row_count: int) -> None:
+    """Print a 4-line success report with Neon host, table name, and row count."""
+    print(SUCCESS_REPORT_HEADER)
+    print(f"{NEON_HOST_REPORT_LABEL} {neon_host}")
+    print(f"{TABLE_REPORT_LABEL} {table_name}")
+    print(f"{ROW_COUNT_REPORT_LABEL} {row_count}")
+
+
+def connect_to_neon() -> object:
+    """Open a psycopg v3 connection using the configured Neon database URL.
+
+    Raises ``MissingPsycopgDependencyError`` when psycopg is not installed
+    so the caller can surface a clear actionable message.
+    """
+    if psycopg is None:
+        raise MissingPsycopgDependencyError(MISSING_PSYCOPG_WARNING_LABEL)
+    database_url = os.environ[NEON_DATABASE_URL_ENVIRONMENT_VARIABLE]
+    return psycopg.connect(database_url, connect_timeout=CONNECT_TIMEOUT_SECONDS)
+
+
+def _fetch_row_count(neon_connection: object) -> int:
+    """Return the current row count of the ``hook_events`` table."""
+    with neon_connection.cursor() as neon_cursor:
+        neon_cursor.execute(HOOK_EVENTS_ROW_COUNT_SQL)
+        row_count_row = neon_cursor.fetchone()
+    return int(row_count_row[0]) if row_count_row else 0
+
+
+def _print_missing_environment_variables(all_missing_variable_names: list[str]) -> None:
+    """Write one stderr line per missing environment variable name."""
+    for each_missing_name in all_missing_variable_names:
+        print(
+            f"{MISSING_ENVIRONMENT_VARIABLE_PREFIX}{each_missing_name}",
+            file=sys.stderr,
+        )
+
+
+def main() -> int:
+    """Entry point for the ``/hook-log-init`` slash command."""
+    all_missing_variable_names = verify_environment_variables()
+    if all_missing_variable_names:
+        _print_missing_environment_variables(all_missing_variable_names)
+        return EXIT_CODE_ENVIRONMENT_MISSING
+    neon_connection = connect_to_neon()
+    try:
+        apply_schema(neon_connection)
+        run_sentinel_round_trip(neon_connection)
+        row_count_value = _fetch_row_count(neon_connection)
+        neon_host_string = _extract_host_from_database_url(
+            os.environ[NEON_DATABASE_URL_ENVIRONMENT_VARIABLE],
+        )
+        print_success_report(
+            neon_host=neon_host_string,
+            table_name=HOOK_EVENTS_TABLE_NAME,
+            row_count=row_count_value,
+        )
+        return EXIT_CODE_SUCCESS
+    finally:
+        try:
+            neon_connection.close()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/diagnostic/hook_log_stop_wrapper.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Stop-hook wrapper for hook_log_extractor that never surfaces a hook failure.
+
+Invokes ``hook_log_extractor.py --incremental`` via ``bws run`` only when
+both ``bws`` is on PATH and ``BWS_ACCESS_TOKEN`` is set; otherwise falls
+through to run the extractor directly. The extractor itself exits 0 when
+``NEON_HOOK_LOGS_DATABASE_URL`` is unset, so the wrapper can rely on that
+offline-graceful path. This wrapper always exits 0 so the Stop hook
+never blocks session end on a missing dependency.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+if str(Path(__file__).resolve().parent.parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from config.hook_log_extractor_constants import (
+    BWS_ACCESS_TOKEN_ENV_VAR,
+    BWS_EXECUTABLE_NAME,
+    BWS_RUN_SEPARATOR,
+    BWS_RUN_SUBCOMMAND,
+    EXIT_CODE_SUCCESS,
+    FLAG_INCREMENTAL,
+    STOP_WRAPPER_EXTRACTOR_SCRIPT_NAME,
+)
+
+
+def _extractor_script_path() -> str:
+    return str(
+        Path(__file__).resolve().parent / STOP_WRAPPER_EXTRACTOR_SCRIPT_NAME
+    )
+
+
+def _can_use_bws() -> bool:
+    if not os.environ.get(BWS_ACCESS_TOKEN_ENV_VAR):
+        return False
+    return shutil.which(BWS_EXECUTABLE_NAME) is not None
+
+
+def _run_with_bws() -> None:
+    subprocess.run(
+        [
+            BWS_EXECUTABLE_NAME,
+            BWS_RUN_SUBCOMMAND,
+            BWS_RUN_SEPARATOR,
+            sys.executable,
+            _extractor_script_path(),
+            FLAG_INCREMENTAL,
+        ],
+        check=False,
+    )
+
+
+def _run_without_bws() -> None:
+    subprocess.run(
+        [
+            sys.executable,
+            _extractor_script_path(),
+            FLAG_INCREMENTAL,
+        ],
+        check=False,
+    )
+
+
+def main() -> int:
+    """Invoke the extractor with or without bws; swallow all failures."""
+    try:
+        if _can_use_bws():
+            _run_with_bws()
+        else:
+            _run_without_bws()
+    except Exception:
+        pass
+    return EXIT_CODE_SUCCESS
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/diagnostic/migrations/2026-04-25-drop-themes-hook-events.sql

@@ -0,0 +1,3 @@
+DROP VIEW IF EXISTS blocked_commands;
+
+DROP TABLE IF EXISTS hook_events;

package/hooks/diagnostic/migrations/README.md

@@ -0,0 +1,77 @@
+# Hook-Log Diagnostic Migrations
+
+One-time DDL migrations for the hook-log diagnostic store. Each file is named
+`YYYY-MM-DD-<short-description>.sql` and contains idempotent statements that
+can be re-run without error.
+
+These files are records of operations already executed (or to be executed)
+against a specific Neon project. They are not run automatically by any hook.
+
+## How to apply
+
+A migration runs against the Postgres connection URL of the project being
+modified. The runner is whichever client the operator prefers; a typical
+pattern is:
+
+```
+psql "$DATABASE_URL" -f packages/claude-dev-env/hooks/diagnostic/migrations/<file>.sql
+```
+
+When the project is hosted on Neon, the `mcp__neon__run_sql_transaction` tool
+accepts the same statements as a list of strings. That is the path used for
+the 2026-04-25 isolation migration described below, since the operator
+already has Neon MCP authenticated.
+
+## 2026-04-25-drop-themes-hook-events.sql
+
+**Target:** Neon project `still-dust-13937951` ("Themes"). This is the
+production themes-asset-database project, which up to PR #257 was also
+holding the hook-log diagnostic table because the
+`NEON_HOOK_LOGS_DATABASE_URL` Bitwarden secret was pointing at it.
+
+**Effect:** Drops the diagnostic view `blocked_commands` and the diagnostic
+table `hook_events` from the Themes project. The two objects were created
+by `schema.sql` during a misrouted live test in session 80; they share no
+foreign keys or other coupling with the themes-domain tables (`assets`,
+`themes`, `monthly_sales`, etc.) and removing them is a pure cleanup.
+
+**State before this migration:** `hook_events` holds 10,684 rows spanning
+2026-04-12 through 2026-04-24. None of these rows are migrated; the
+"start fresh" decision (recorded in PR #261) means the extractor's
+`--full-rebuild` mode rebuilds the table contents from local JSONL on
+its next run against the new project.
+
+**State after this migration:** Themes contains only its production
+domain tables. The hook-log diagnostic store lives entirely in the new
+Neon project `winter-haze-99075918` ("claude-hook-logs"), which the
+updated `NEON_HOOK_LOGS_DATABASE_URL` secret now points at.
+
+**Verification:** Before applying, confirm there is no other consumer
+of `blocked_commands` or `hook_events` in the Themes project:
+
+```sql
+SELECT table_name, view_definition
+FROM information_schema.views
+WHERE table_schema = 'public'
+  AND view_definition ILIKE '%hook_events%'
+  AND table_name <> 'blocked_commands';
+
+SELECT conname, conrelid::regclass
+FROM pg_constraint
+WHERE confrelid = 'hook_events'::regclass;
+```
+
+The first query excludes `blocked_commands` itself, since that view (also dropped by this migration) references `hook_events` in its definition and would otherwise always match.
+
+Both queries should return zero rows; if either returns anything,
+investigate the dependency before running the drop.
+
+After applying, confirm the objects are gone:
+
+```sql
+SELECT table_schema, table_name, table_type
+FROM information_schema.tables
+WHERE table_schema = 'public' AND table_name IN ('hook_events', 'blocked_commands');
+```
+
+Should return zero rows.

package/hooks/diagnostic/queries/block_details_for_hook.sql

@@ -0,0 +1,26 @@
+-- Recent block details for the top-blocking hook in the last 30 days.
+-- Shows the 25 most recent blocked attempts with the command excerpt and error
+-- excerpt so diagnosis can focus on concrete failing commands rather than
+-- aggregate counts. To target a specific hook, filter by hook_name in a follow-up.
+WITH top_hook AS (
+    SELECT hook_name
+    FROM hook_events
+    WHERE outcome = 'blocked'
+        AND event_timestamp >= (NOW() - INTERVAL '30 days')
+    GROUP BY hook_name
+    ORDER BY COUNT(*) DESC
+    LIMIT 1
+)
+SELECT
+    event_timestamp,
+    session_id,
+    hook_event,
+    hook_name,
+    tool_name,
+    command_excerpt,
+    stderr_excerpt
+FROM hook_events
+WHERE outcome = 'blocked'
+    AND hook_name = (SELECT hook_name FROM top_hook)
+ORDER BY event_timestamp DESC
+LIMIT 25;

package/hooks/diagnostic/queries/blocks_by_category.sql

@@ -0,0 +1,10 @@
+-- Total blocks grouped by hook category, all history.
+SELECT
+    hook_category,
+    COUNT(*) AS block_count,
+    COUNT(DISTINCT hook_name) AS distinct_hook_count,
+    COUNT(DISTINCT session_id) AS distinct_session_count
+FROM hook_events
+WHERE outcome = 'blocked'
+GROUP BY hook_category
+ORDER BY block_count DESC;

package/hooks/diagnostic/queries/blocks_by_tool.sql

@@ -0,0 +1,9 @@
+-- Blocks grouped by tool name parsed from hook_name (e.g., Bash, Write, Edit).
+SELECT
+    COALESCE(tool_name, '(none)') AS tool_name,
+    COUNT(*) AS block_count,
+    COUNT(DISTINCT hook_name) AS distinct_hook_count
+FROM hook_events
+WHERE outcome = 'blocked'
+GROUP BY tool_name
+ORDER BY block_count DESC;

package/hooks/diagnostic/queries/blocks_last_7_days.sql

@@ -0,0 +1,11 @@
+-- Daily block counts for the last 7 days, grouped by hook.
+SELECT
+    DATE_TRUNC('day', event_timestamp)::DATE AS block_day,
+    hook_name,
+    hook_category,
+    COUNT(*) AS block_count
+FROM hook_events
+WHERE outcome = 'blocked'
+    AND event_timestamp >= (NOW() - INTERVAL '7 days')
+GROUP BY block_day, hook_name, hook_category
+ORDER BY block_day DESC, block_count DESC;

package/hooks/diagnostic/queries/top_blockers_last_24_hours.sql

@@ -0,0 +1,12 @@
+-- Top 10 hooks by blocking count in the last 24 hours.
+SELECT
+    hook_name,
+    hook_category,
+    COUNT(*) AS block_count_last_24_hours,
+    MIN(COALESCE(command_excerpt, stdout_excerpt, stderr_excerpt, '')) AS top_blocked_command_preview
+FROM hook_events
+WHERE outcome = 'blocked'
+    AND event_timestamp >= (NOW() - INTERVAL '1 day')
+GROUP BY hook_name, hook_category
+ORDER BY block_count_last_24_hours DESC
+LIMIT 10;

package/hooks/diagnostic/queries/top_blockers_overall.sql

@@ -0,0 +1,12 @@
+-- Top 20 hooks by blocking count across all history.
+SELECT
+    hook_name,
+    hook_category,
+    COUNT(*) AS block_count,
+    MIN(event_timestamp) AS first_block_at,
+    MAX(event_timestamp) AS last_block_at
+FROM hook_events
+WHERE outcome = 'blocked'
+GROUP BY hook_name, hook_category
+ORDER BY block_count DESC
+LIMIT 20;

package/hooks/diagnostic/requirements-hook-logs-dev.txt

@@ -0,0 +1,2 @@
+-r requirements-hook-logs.txt
+pytest>=7.0

package/hooks/diagnostic/requirements-hook-logs.txt

@@ -0,0 +1 @@
+psycopg[binary]>=3.1,<4

package/hooks/diagnostic/schema.sql

@@ -0,0 +1,51 @@
+CREATE TABLE IF NOT EXISTS hook_events (
+    id BIGSERIAL PRIMARY KEY,
+    event_timestamp TIMESTAMPTZ NOT NULL,
+    session_id TEXT NOT NULL,
+    cwd TEXT,
+    git_branch TEXT,
+    hook_event TEXT NOT NULL,
+    hook_name TEXT NOT NULL,
+    hook_category TEXT NOT NULL,
+    script_path TEXT,
+    tool_name TEXT,
+    tool_use_id TEXT,
+    outcome TEXT NOT NULL,
+    exit_code INTEGER,
+    duration_ms INTEGER,
+    command_excerpt TEXT,
+    stdout_excerpt TEXT,
+    stderr_excerpt TEXT,
+    source_jsonl_path TEXT NOT NULL,
+    source_line_number INTEGER NOT NULL,
+    CONSTRAINT hook_events_source_location_unique UNIQUE (source_jsonl_path, source_line_number)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hook_events_category_outcome ON hook_events (hook_category, outcome);
+CREATE INDEX IF NOT EXISTS idx_hook_events_timestamp ON hook_events (event_timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_hook_events_hook_name ON hook_events (hook_name);
+CREATE INDEX IF NOT EXISTS idx_hook_events_session ON hook_events (session_id);
+
+CREATE OR REPLACE VIEW blocked_commands AS
+SELECT
+    id,
+    event_timestamp,
+    session_id,
+    cwd,
+    git_branch,
+    hook_event,
+    hook_name,
+    hook_category,
+    script_path,
+    tool_name,
+    tool_use_id,
+    outcome,
+    exit_code,
+    duration_ms,
+    command_excerpt,
+    stdout_excerpt,
+    stderr_excerpt,
+    source_jsonl_path,
+    source_line_number
+FROM hook_events
+WHERE outcome = 'blocked';