claude-dev-env 2.16.0 → 2.17.0

package/hooks/diagnostic/hook_log_init.py

@@ -1,202 +0,0 @@
-#!/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 hooks_constants.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/hooks/diagnostic/AGENTS.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:
-    """CLI entry for one-time Neon schema init."""
-    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

@@ -1,26 +0,0 @@
-#!/usr/bin/env python3
-"""Disabled Stop-hook wrapper for the hook-log extractor.
-
-The wrapper is off the Stop dispatcher roster and exits 0 without spawning
-the extractor or writing debounce state. Git history holds the prior
-debounce-and-spawn implementation if Neon-backed extraction returns.
-"""
-
-from __future__ import annotations
-
-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 hooks_constants.hook_log_extractor_constants import EXIT_CODE_SUCCESS
-
-
-def main() -> int:
-    """Exit success without spawning the extractor."""
-    return EXIT_CODE_SUCCESS
-
-
-if __name__ == "__main__":
-    sys.exit(main())

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

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

package/hooks/diagnostic/migrations/AGENTS.md

@@ -1,16 +0,0 @@
-# hooks/diagnostic/migrations
-
-SQL migration files for the `hook_events` Neon schema. Each file applies a schema change to the `hook_events` table or its indexes.
-
-## Files
-
-| File | What it does |
-|---|---|
-| `2026-04-25-drop-themes-hook-events.sql` | Drops the `themes` hook-events table variant |
-| `README.md` | Notes on the migration approach |
-
-## Conventions
-
-- Run migrations manually against the Neon database using `psql` or the Neon console.
-- The baseline schema lives in `diagnostic/schema.sql`.
-- File names follow `YYYY-MM-DD-<description>.sql` for chronological ordering.

package/hooks/diagnostic/migrations/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

package/hooks/diagnostic/migrations/README.md

@@ -1,76 +0,0 @@
-# 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 has idempotent statements that can be
-re-run without error.
-
-These files are records of operations run (or to be run) against a specific
-Neon project. No hook runs them automatically.
-
-## 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 `example-project-00000000`, a production application
-database. This project also held the hook-log diagnostic table up to PR #257,
-because the `NEON_HOOK_LOGS_DATABASE_URL` Bitwarden secret pointed at it.
-
-**Effect:** Drops the diagnostic view `blocked_commands` and the diagnostic
-table `hook_events` from the source project. The two objects came from
-`schema.sql` during a misrouted live test in session 80; they share no foreign
-keys or other coupling with the project's own domain tables, 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 move; 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
-hook-log project.
-
-**State after this migration:** the source project has only its own domain
-tables. The hook-log diagnostic store lives entirely in a separate Neon project
-`example-project-11111111`, which the `NEON_HOOK_LOGS_DATABASE_URL` secret
-points at.
-
-**Verification:** Before applying, confirm there is no other consumer of
-`blocked_commands` or `hook_events` in the source 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/AGENTS.md

@@ -1,19 +0,0 @@
-# hooks/diagnostic/queries
-
-Parameterized SQL queries for inspecting the `hook_events` Neon table. Run these directly against the Neon database to analyze hook-firing patterns.
-
-## Files
-
-| File | What it returns |
-|---|---|
-| `block_details_for_hook.sql` | Full details for all blocked events matching a given hook name |
-| `blocks_by_category.sql` | Count of blocks grouped by hook category |
-| `blocks_by_tool.sql` | Count of blocks grouped by tool name |
-| `blocks_last_7_days.sql` | All blocked events from the last 7 days |
-| `top_blockers_last_24_hours.sql` | Hook names with the most blocks in the last 24 hours |
-| `top_blockers_overall.sql` | Hook names with the most blocks across all time |
-
-## Conventions
-
-- Queries target the `hook_events` table and `blocked_commands` view defined in `diagnostic/schema.sql`.
-- Run with `psql $DATABASE_URL -f <query>.sql` or paste into the Neon console.

package/hooks/diagnostic/queries/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

package/hooks/diagnostic/queries/block_details_for_hook.sql

@@ -1,26 +0,0 @@
--- 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

@@ -1,10 +0,0 @@
--- 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

@@ -1,9 +0,0 @@
--- 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

@@ -1,11 +0,0 @@
--- 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

@@ -1,12 +0,0 @@
--- 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

@@ -1,12 +0,0 @@
--- 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

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

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

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

package/hooks/diagnostic/schema.sql

@@ -1,51 +0,0 @@
-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';