@rulemetric/hooks 0.1.1

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@rulemetric/hooks",
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./scripts-dir": "./scripts-dir.js"
+  },
+  "files": [
+    "scripts",
+    "scripts-dir.js"
+  ],
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/scripts/_config.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# RuleMetric: Shared config loader for hook scripts
+# Sources credentials from multiple locations (first match wins):
+#   1. Already-set environment variables (e.g. from shell profile)
+#   2. ~/.config/rulemetric/env (global user config, created by `rulemetric login`)
+#   3. .env.local in project root (development)
+
+_rulemetric_load_config() {
+  # If already configured, nothing to do
+  if [ -n "${RULEMETRIC_API_URL:-}" ] && { [ -n "${RULEMETRIC_API_KEY:-}" ] || [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; }; then
+    return 0
+  fi
+
+  local config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/rulemetric"
+
+  # Try global env file (shell-sourceable, written by `rulemetric auth login`)
+  if [ -f "$config_dir/env" ]; then
+    set -a
+    # shellcheck source=/dev/null
+    source "$config_dir/env"
+    set +a
+    if [ -n "${RULEMETRIC_API_URL:-}" ] && { [ -n "${RULEMETRIC_API_KEY:-}" ] || [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; }; then
+      return 0
+    fi
+  fi
+
+  # Try auth.json (written by `rulemetric auth login`)
+  if [ -f "$config_dir/auth.json" ] && command -v jq >/dev/null 2>&1; then
+    local token
+    token=$(jq -r '.accessToken // empty' "$config_dir/auth.json" 2>/dev/null)
+    if [ -n "$token" ]; then
+      export RULEMETRIC_ACCESS_TOKEN="$token"
+      # Default API URL if not set
+      export RULEMETRIC_API_URL="${RULEMETRIC_API_URL:-https://api.rulemetric.com}"
+      return 0
+    fi
+  fi
+
+  # Try project-local .env.local (development)
+  if [ -f .env.local ]; then
+    while IFS= read -r line || [ -n "$line" ]; do
+      case "$line" in
+        RULEMETRIC_*=*)
+          key="${line%%=*}"
+          value="${line#*=}"
+          # Only export valid variable names
+          case "$key" in
+            *[!A-Za-z0-9_]*) continue ;;
+          esac
+          export "$key=$value"
+          ;;
+      esac
+    done < .env.local
+    return 0
+  fi
+
+  return 0
+}
+
+_rulemetric_load_config

package/scripts/_ensure-session.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# RuleMetric: Lazy session recovery
+# If session-start failed (API was down), this creates the session on demand.
+# Must be sourced AFTER _normalize.sh and _config.sh.
+#
+# Requires: HOOK_SESSION_ID, HOOK_TOOL, HOOK_CWD, RULEMETRIC_API_URL, AUTH_HEADER
+# Sets: RW_SESSION_ID (non-empty on success)
+
+_rulemetric_ensure_session() {
+  TEMP_DIR="${TMPDIR:-/tmp}/rulemetric"
+  RW_SESSION_ID=""
+
+  # Check for existing temp file first
+  if [ -f "$TEMP_DIR/$HOOK_SESSION_ID" ]; then
+    RW_SESSION_ID=$(cat "$TEMP_DIR/$HOOK_SESSION_ID")
+    if [ -n "$RW_SESSION_ID" ]; then
+      return 0
+    fi
+  fi
+
+  # No session — try to create one (lazy recovery)
+  # Use mkdir-based locking to prevent parallel tool calls from creating duplicate sessions
+  mkdir -p "$TEMP_DIR" || return 1
+  local lock_dir="$TEMP_DIR/$HOOK_SESSION_ID.sesslock"
+
+  # Acquire lock (mkdir is atomic on all POSIX systems)
+  local tries=0
+  while ! mkdir "$lock_dir" 2>/dev/null; do
+    sleep 0.01
+    tries=$((tries + 1))
+    if [ "$tries" -ge 500 ]; then
+      # Stale lock — force remove and retry
+      rmdir "$lock_dir" 2>/dev/null || rm -rf "$lock_dir" 2>/dev/null
+      mkdir "$lock_dir" 2>/dev/null || return 1
+      break
+    fi
+  done
+
+  # Re-check after acquiring lock (another process may have created it)
+  if [ -f "$TEMP_DIR/$HOOK_SESSION_ID" ]; then
+    RW_SESSION_ID=$(cat "$TEMP_DIR/$HOOK_SESSION_ID")
+    if [ -n "$RW_SESSION_ID" ]; then
+      rmdir "$lock_dir" 2>/dev/null
+      return 0
+    fi
+  fi
+
+  local cwd="${HOOK_CWD:-$(pwd)}"
+  # Normalize to git root so subdirectories map to the same project
+  local git_root
+  git_root=$(cd "$cwd" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [ -n "$git_root" ]; then
+    cwd="$git_root"
+  fi
+  local git_branch
+  git_branch=$(cd "$cwd" 2>/dev/null && git branch --show-current 2>/dev/null || echo "")
+  local git_remote
+  git_remote=$(cd "$cwd" 2>/dev/null && git remote get-url origin 2>/dev/null || echo "")
+
+  local metadata="{}"
+  if [ -n "$git_remote" ]; then
+    metadata=$(printf '{"gitRemote":%s}' "$(printf '%s' "$git_remote" | jq -Rs .)")
+  fi
+
+  local payload
+  payload=$(jq -n \
+    --arg tool "$HOOK_TOOL" \
+    --arg externalSessionId "$HOOK_SESSION_ID" \
+    --arg projectPath "$cwd" \
+    --arg gitBranch "$git_branch" \
+    --argjson metadata "$metadata" \
+    '{tool: $tool, externalSessionId: $externalSessionId, projectPath: $projectPath, gitBranch: $gitBranch, metadata: $metadata}')
+
+  local response
+  response=$(curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions" \
+    -H "$AUTH_HEADER" \
+    -H "Content-Type: application/json" \
+    -d "$payload" \
+    2>/dev/null)
+
+  if [ "$?" -ne 0 ]; then
+    rmdir "$lock_dir" 2>/dev/null
+    return 1
+  fi
+
+  RW_SESSION_ID=$(echo "$response" | jq -r '.id // empty')
+  if [ -z "$RW_SESSION_ID" ]; then
+    rmdir "$lock_dir" 2>/dev/null
+    return 1
+  fi
+
+  echo "$RW_SESSION_ID" > "$TEMP_DIR/$HOOK_SESSION_ID"
+  echo "0" > "$TEMP_DIR/$HOOK_SESSION_ID.seq"
+
+  _rulemetric_log "${1:-ensure-session}" "recovered" "lazy_create"
+  rmdir "$lock_dir" 2>/dev/null
+
+  # Re-read the session ID written by the locked subshell
+  if [ -f "$TEMP_DIR/$HOOK_SESSION_ID" ]; then
+    RW_SESSION_ID=$(cat "$TEMP_DIR/$HOOK_SESSION_ID")
+  fi
+  [ -n "$RW_SESSION_ID" ]
+}

package/scripts/_log.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# RuleMetric: Structured hook logging
+# Appends JSON lines to $TMPDIR/rulemetric/hook.log
+# Never fails — all writes guarded with || true
+
+_rulemetric_log() {
+  local script="${1:-unknown}"
+  local outcome="${2:-unknown}"
+  local reason="${3:-}"
+  local timestamp
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null || echo "")"
+
+  local log_dir="${TMPDIR:-/tmp}/rulemetric"
+  mkdir -p "$log_dir" 2>/dev/null || true
+
+  if command -v jq >/dev/null 2>&1; then
+    jq -cn --arg ts "$timestamp" --arg script "$script" --arg outcome "$outcome" \
+           --arg reason "$reason" --arg session "${HOOK_SESSION_ID:-}" \
+      '{ts: $ts, script: $script, outcome: $outcome, reason: $reason, session: $session}' \
+      >> "$log_dir/hook.log" 2>/dev/null || true
+  else
+    # Fallback: escape quotes and backslashes to prevent JSON injection
+    local esc_script esc_outcome esc_reason esc_session
+    esc_script="${script//\\/\\\\}"; esc_script="${esc_script//\"/\\\"}"
+    esc_outcome="${outcome//\\/\\\\}"; esc_outcome="${esc_outcome//\"/\\\"}"
+    esc_reason="${reason//\\/\\\\}"; esc_reason="${esc_reason//\"/\\\"}"
+    esc_session="${HOOK_SESSION_ID:-}"; esc_session="${esc_session//\\/\\\\}"; esc_session="${esc_session//\"/\\\"}"
+    printf '{"ts":"%s","script":"%s","outcome":"%s","reason":"%s","session":"%s"}\n' \
+      "$timestamp" "$esc_script" "$esc_outcome" "$esc_reason" "$esc_session" \
+      >> "$log_dir/hook.log" 2>/dev/null || true
+  fi
+}

package/scripts/_normalize.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# RuleMetric: Normalize hook input across AI coding tools
+# Detects Claude Code, VS Code Copilot, Copilot CLI, and Cursor input formats,
+# then exports canonical HOOK_* variables for use by other scripts.
+#
+# Usage: source "$SCRIPT_DIR/_normalize.sh" (after reading INPUT from stdin)
+#
+# Exports:
+#   HOOK_TOOL        - "claude_code", "vscode_copilot", "copilot_cli", or "cursor"
+#   HOOK_SESSION_ID  - Session identifier
+#   HOOK_CWD         - Working directory
+#   HOOK_PROMPT      - User prompt text
+#   HOOK_TOOL_NAME   - Tool/command name
+#   HOOK_TOOL_INPUT  - Tool input as JSON
+#   HOOK_TOOL_OUTPUT - Tool output as JSON
+#   HOOK_TRANSCRIPT_PATH - Path to transcript file (empty if unavailable)
+
+_rulemetric_normalize() {
+  local input="$1"
+
+  # Detect format by checking for distinguishing fields
+  # Copilot CLI: has "toolName" (camelCase, no sessionId)
+  # VS Code Copilot: has "sessionId" (camelCase)
+  # Cursor: has "conversation_id" AND "hook_event_name"
+  # Claude Code: has "session_id" (snake_case) — fallback default
+
+  local has_session_id has_sessionId has_toolName has_conversation_id has_hook_event_name
+  has_session_id=$(echo "$input" | jq -r 'has("session_id")' 2>/dev/null)
+  has_sessionId=$(echo "$input" | jq -r 'has("sessionId")' 2>/dev/null)
+  has_toolName=$(echo "$input" | jq -r 'has("toolName")' 2>/dev/null)
+  has_conversation_id=$(echo "$input" | jq -r 'has("conversation_id")' 2>/dev/null)
+  has_hook_event_name=$(echo "$input" | jq -r 'has("hook_event_name")' 2>/dev/null)
+
+  if [ "$has_toolName" = "true" ] && [ "$has_sessionId" != "true" ]; then
+    # Copilot CLI: no session ID, uses toolName/toolArgs/toolResult
+    HOOK_TOOL="copilot_cli"
+
+    # Generate deterministic session ID from cwd hash (stable per-project)
+    local cwd
+    cwd=$(echo "$input" | jq -r '.cwd // empty')
+    if [ -n "$cwd" ]; then
+      HOOK_SESSION_ID="copilot-cli-$(printf '%s' "$cwd" | shasum -a 256 | cut -c1-16)"
+    else
+      HOOK_SESSION_ID="copilot-cli-$(printf '%s' "unknown" | shasum -a 256 | cut -c1-16)"
+    fi
+
+    HOOK_CWD="$cwd"
+    HOOK_PROMPT=$(echo "$input" | jq -r '.prompt // empty')
+    HOOK_TOOL_NAME=$(echo "$input" | jq -r '.toolName // empty')
+
+    # toolArgs is a JSON string — parse it to an object
+    local tool_args_raw
+    tool_args_raw=$(echo "$input" | jq -r '.toolArgs // empty')
+    if [ -n "$tool_args_raw" ]; then
+      # Try parsing as JSON; if it fails, wrap as string
+      HOOK_TOOL_INPUT=$(printf '%s' "$tool_args_raw" | jq -c '.' 2>/dev/null || printf '{"raw":%s}' "$(printf '%s' "$tool_args_raw" | jq -Rs .)")
+    else
+      HOOK_TOOL_INPUT="{}"
+    fi
+
+    # toolResult.textResultForLlm → wrap as {"result": "..."}
+    local tool_result
+    tool_result=$(echo "$input" | jq -r '.toolResult.textResultForLlm // empty')
+    if [ -n "$tool_result" ]; then
+      HOOK_TOOL_OUTPUT=$(printf '{"result":%s}' "$(printf '%s' "$tool_result" | jq -Rs .)")
+    else
+      HOOK_TOOL_OUTPUT="{}"
+    fi
+
+    HOOK_TRANSCRIPT_PATH=""
+
+  elif [ "$has_sessionId" = "true" ]; then
+    # VS Code Copilot (agent mode): sessionId (camelCase), tool_name, tool_input, tool_response
+    HOOK_TOOL="vscode_copilot"
+    HOOK_SESSION_ID=$(echo "$input" | jq -r '.sessionId // empty')
+    HOOK_CWD=$(echo "$input" | jq -r '.cwd // empty')
+    HOOK_PROMPT=$(echo "$input" | jq -r '.prompt // empty')
+    HOOK_TOOL_NAME=$(echo "$input" | jq -r '.tool_name // empty')
+    HOOK_TOOL_INPUT=$(echo "$input" | jq -c '.tool_input // {}')
+    HOOK_TOOL_OUTPUT=$(echo "$input" | jq -c '.tool_response // {}')
+    HOOK_TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // empty')
+
+  elif [ "$has_conversation_id" = "true" ] && [ "$has_hook_event_name" = "true" ]; then
+    # Cursor: conversation_id + hook_event_name
+    HOOK_TOOL="cursor"
+
+    # Generate deterministic session ID from conversation_id hash
+    local conversation_id
+    conversation_id=$(echo "$input" | jq -r '.conversation_id // empty')
+    if [ -n "$conversation_id" ]; then
+      HOOK_SESSION_ID="cursor-$(printf '%s' "$conversation_id" | shasum -a 256 | cut -c1-16)"
+    else
+      HOOK_SESSION_ID="cursor-$(printf '%s' "unknown" | shasum -a 256 | cut -c1-16)"
+    fi
+
+    HOOK_CWD=$(echo "$input" | jq -r '.workspace_roots[0] // .cwd // empty')
+    HOOK_PROMPT=$(echo "$input" | jq -r '.prompt // empty')
+    HOOK_TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // empty')
+
+    # Map hook_event_name to tool fields
+    local event_name
+    event_name=$(echo "$input" | jq -r '.hook_event_name // empty')
+
+    case "$event_name" in
+      beforeShellExecution)
+        HOOK_TOOL_NAME="bash"
+        HOOK_TOOL_INPUT=$(echo "$input" | jq -c '{command: .command, cwd: .cwd} | with_entries(select(.value != null))' 2>/dev/null || echo '{}')
+        HOOK_TOOL_OUTPUT="{}"
+        ;;
+      afterFileEdit)
+        HOOK_TOOL_NAME="edit"
+        HOOK_TOOL_INPUT=$(echo "$input" | jq -c '{file_path: .file_path, edits: .edits} | with_entries(select(.value != null))' 2>/dev/null || echo '{}')
+        HOOK_TOOL_OUTPUT="{}"
+        ;;
+      beforeReadFile)
+        HOOK_TOOL_NAME="read"
+        HOOK_TOOL_INPUT=$(echo "$input" | jq -c '{file_path: .file_path} | with_entries(select(.value != null))' 2>/dev/null || echo '{}')
+        HOOK_TOOL_OUTPUT="{}"
+        ;;
+      beforeMCPExecution)
+        HOOK_TOOL_NAME=$(echo "$input" | jq -r '.tool_name // empty')
+        HOOK_TOOL_INPUT=$(echo "$input" | jq -c '.parameters // {}')
+        HOOK_TOOL_OUTPUT="{}"
+        ;;
+      *)
+        # Default: use generic fields if present (stop, beforeSubmitPrompt, etc.)
+        HOOK_TOOL_NAME=$(echo "$input" | jq -r '.tool_name // empty')
+        HOOK_TOOL_INPUT=$(echo "$input" | jq -c '.tool_input // {}')
+        HOOK_TOOL_OUTPUT=$(echo "$input" | jq -c '.tool_response // {}')
+        ;;
+    esac
+
+  else
+    # Claude Code (default): session_id (snake_case)
+    HOOK_TOOL="claude_code"
+    HOOK_SESSION_ID=$(echo "$input" | jq -r '.session_id // empty')
+    HOOK_CWD=$(echo "$input" | jq -r '.cwd // empty')
+    HOOK_PROMPT=$(echo "$input" | jq -r '.prompt // empty')
+    HOOK_TOOL_NAME=$(echo "$input" | jq -r '.tool_name // empty')
+    HOOK_TOOL_INPUT=$(echo "$input" | jq -c '.tool_input // {}')
+    HOOK_TOOL_OUTPUT=$(echo "$input" | jq -c '.tool_response // {}')
+    HOOK_TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // empty')
+  fi
+
+  # Truncate large payloads (Read tool output can be massive)
+  local max_len=4000
+  if [ "${#HOOK_TOOL_OUTPUT}" -gt "$max_len" ]; then
+    HOOK_TOOL_OUTPUT=$(printf '%s' "$HOOK_TOOL_OUTPUT" | head -c "$max_len")
+    # Re-wrap as valid JSON string if we truncated
+    HOOK_TOOL_OUTPUT="{\"truncated\":true,\"preview\":$(printf '%s' "$HOOK_TOOL_OUTPUT" | jq -Rs . 2>/dev/null || echo '""')}"
+  fi
+  if [ "${#HOOK_TOOL_INPUT}" -gt "$max_len" ]; then
+    HOOK_TOOL_INPUT=$(printf '%s' "$HOOK_TOOL_INPUT" | head -c "$max_len")
+    HOOK_TOOL_INPUT="{\"truncated\":true,\"preview\":$(printf '%s' "$HOOK_TOOL_INPUT" | jq -Rs . 2>/dev/null || echo '""')}"
+  fi
+
+  # Validate HOOK_SESSION_ID format (prevent path traversal)
+  # Accepts: standard UUIDs (case-insensitive), copilot-cli-<hex>, and cursor-<hex> synthetic IDs
+  if [ -n "$HOOK_SESSION_ID" ]; then
+    if ! echo "$HOOK_SESSION_ID" | grep -qiE '^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|copilot-cli-[0-9a-f]{1,64}|cursor-[0-9a-f]{1,64})$'; then
+      HOOK_SESSION_ID=""
+    fi
+  fi
+
+  export HOOK_TOOL HOOK_SESSION_ID HOOK_CWD HOOK_PROMPT
+  export HOOK_TOOL_NAME HOOK_TOOL_INPUT HOOK_TOOL_OUTPUT HOOK_TRANSCRIPT_PATH
+}
+
+# INPUT must be set before sourcing this file
+_rulemetric_normalize "$INPUT"

package/scripts/post-tool-use.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# RuleMetric: Capture tool use events in real-time
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_log.sh" 2>/dev/null || _rulemetric_log() { :; }
+
+set -euo pipefail
+trap 'echo "rulemetric post-tool-use failed at line $LINENO: $BASH_COMMAND" >&2; _rulemetric_log "post-tool-use" "error" "line $LINENO: $BASH_COMMAND"; exit 1' ERR
+
+# Load config (env vars, ~/.config/rulemetric/env, or .env.local)
+source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
+
+# Read hook input from stdin and normalize across tools
+INPUT=$(cat)
+source "$SCRIPT_DIR/_normalize.sh"
+
+if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
+  _rulemetric_log "post-tool-use" "skip" "no_config"
+  exit 0
+fi
+
+# Auth
+AUTH_HEADER=""
+if [ -n "${RULEMETRIC_API_KEY:-}" ]; then
+  AUTH_HEADER="Authorization: Bearer $RULEMETRIC_API_KEY"
+elif [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; then
+  AUTH_HEADER="Authorization: Bearer $RULEMETRIC_ACCESS_TOKEN"
+else
+  _rulemetric_log "post-tool-use" "skip" "no_auth"
+  exit 0
+fi
+
+# Get or lazily create RuleMetric session
+source "$SCRIPT_DIR/_ensure-session.sh"
+if ! _rulemetric_ensure_session "post-tool-use"; then
+  _rulemetric_log "post-tool-use" "skip" "no_rw_session"
+  exit 0
+fi
+
+# Increment sequence counter (atomic mkdir lock, works on macOS + Linux)
+SEQ_FILE="$TEMP_DIR/$HOOK_SESSION_ID.seq"
+LOCK_DIR="$TEMP_DIR/$HOOK_SESSION_ID.seqlock"
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do sleep 0.01; done
+SEQ=1
+if [ -f "$SEQ_FILE" ]; then
+  SEQ=$(( $(cat "$SEQ_FILE") + 1 ))
+fi
+echo "$SEQ" > "$SEQ_FILE"
+rmdir "$LOCK_DIR"
+
+# Build payload — toolInput/toolOutput as JSON objects
+PAYLOAD=$(jq -n \
+  --argjson seq "$SEQ" \
+  --arg toolName "$HOOK_TOOL_NAME" \
+  --argjson toolInput "$HOOK_TOOL_INPUT" \
+  --argjson toolOutput "$HOOK_TOOL_OUTPUT" \
+  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
+  '{sequence: $seq, eventType: "tool_call", toolName: $toolName, toolInput: $toolInput, toolOutput: $toolOutput, timestamp: $timestamp}')
+
+_rulemetric_log "post-tool-use" "success"
+
+# Fire-and-forget (capture HTTP errors for debugging)
+(CURL_OUT=$(curl -s -w "\n%{http_code}" -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
+  -H "$AUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" 2>&1)
+  HTTP_CODE=$(echo "$CURL_OUT" | tail -1)
+  if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
+    BODY=$(echo "$CURL_OUT" | sed '$d')
+    _rulemetric_log "post-tool-use" "error" "http_${HTTP_CODE}_seq_${SEQ}: ${BODY}"
+  fi) &

package/scripts/session-end.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# RuleMetric: Finalize session with full transcript import
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_log.sh" 2>/dev/null || _rulemetric_log() { :; }
+
+set -euo pipefail
+trap 'echo "rulemetric session-end failed at line $LINENO: $BASH_COMMAND" >&2; _rulemetric_log "session-end" "error" "line $LINENO: $BASH_COMMAND"; exit 1' ERR
+
+# Load config (env vars, ~/.config/rulemetric/env, or .env.local)
+source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
+
+# Read hook input from stdin and normalize across tools
+INPUT=$(cat)
+source "$SCRIPT_DIR/_normalize.sh"
+
+if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
+  _rulemetric_log "session-end" "skip" "no_config"
+  exit 0
+fi
+
+# Auth
+AUTH_HEADER=""
+if [ -n "${RULEMETRIC_API_KEY:-}" ]; then
+  AUTH_HEADER="Authorization: Bearer $RULEMETRIC_API_KEY"
+elif [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; then
+  AUTH_HEADER="Authorization: Bearer $RULEMETRIC_ACCESS_TOKEN"
+else
+  _rulemetric_log "session-end" "skip" "no_auth"
+  exit 0
+fi
+
+# Get or lazily create RuleMetric session
+source "$SCRIPT_DIR/_ensure-session.sh"
+if ! _rulemetric_ensure_session "session-end"; then
+  _rulemetric_log "session-end" "skip" "no_rw_session"
+  exit 0
+fi
+
+# Try to reimport with full transcript, fall back to close
+if [ -n "$HOOK_TRANSCRIPT_PATH" ] && [ -f "$HOOK_TRANSCRIPT_PATH" ]; then
+  CONTENT=$(cat "$HOOK_TRANSCRIPT_PATH")
+  curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/reimport" \
+    -H "$AUTH_HEADER" \
+    -H "Content-Type: application/json" \
+    -d "{\"content\":$(echo "$CONTENT" | jq -Rs .),\"tool\":\"$HOOK_TOOL\"}" \
+    > /dev/null 2>&1 || {
+    _rulemetric_log "session-end" "fallback" "reimport_failed"
+    curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
+      -H "$AUTH_HEADER" \
+      > /dev/null 2>&1 || \
+      _rulemetric_log "session-end" "error" "close_failed"
+  }
+else
+  # No transcript available — just close the session
+  curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/close" \
+    -H "$AUTH_HEADER" \
+    > /dev/null 2>&1 || \
+    _rulemetric_log "session-end" "error" "close_failed"
+fi
+
+_rulemetric_log "session-end" "success"
+
+# ── Auto-link instructions from context snapshots ──
+# Fire-and-forget: link any captured context to instruction records
+(curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions/link-instructions" \
+  -H "$AUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d '{}' > /dev/null 2>&1) &
+
+# ── Auto-enrich from local session-meta ──
+# For Claude Code: read local session-meta file
+# For other tools: derive enrichment from stored session events via API
+if [ "$HOOK_TOOL" = "claude_code" ]; then
+  SESSION_META_FILE="$HOME/.claude/usage-data/session-meta/$HOOK_SESSION_ID.json"
+  if [ -f "$SESSION_META_FILE" ]; then
+    # Build enrichment payload from local session-meta
+    ENRICH_PAYLOAD=$(SESSION_META_FILE="$SESSION_META_FILE" python3 -c "
+import json, os, sys
+try:
+    meta_file = os.environ['SESSION_META_FILE']
+    meta = json.load(open(meta_file, 'rb'), strict=False)
+    payload = {
+        'metadata': {
+            'local_session_meta': {
+                'duration_minutes': meta.get('duration_minutes', 0),
+                'user_message_count': meta.get('user_message_count', 0),
+                'assistant_message_count': meta.get('assistant_message_count', 0),
+                'tool_counts': meta.get('tool_counts', {}),
+                'languages': meta.get('languages', {}),
+                'git_commits': meta.get('git_commits', 0),
+                'git_pushes': meta.get('git_pushes', 0),
+                'user_interruptions': meta.get('user_interruptions', 0),
+                'tool_errors': meta.get('tool_errors', 0),
+                'lines_added': meta.get('lines_added', 0),
+                'lines_removed': meta.get('lines_removed', 0),
+                'files_modified': meta.get('files_modified', 0),
+            }
+        }
+    }
+    if meta.get('input_tokens', 0) > 0 or meta.get('output_tokens', 0) > 0:
+        payload['tokenUsage'] = {
+            'input_tokens': meta.get('input_tokens', 0),
+            'output_tokens': meta.get('output_tokens', 0),
+        }
+    print(json.dumps(payload))
+except:
+    pass
+" 2>/dev/null)
+
+    if [ -n "$ENRICH_PAYLOAD" ]; then
+      (curl -sf -X PATCH "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/enrich" \
+        -H "$AUTH_HEADER" \
+        -H "Content-Type: application/json" \
+        -d "$ENRICH_PAYLOAD" > /dev/null 2>&1) &
+    fi
+  fi
+else
+  # Non-Claude tools: derive enrichment from stored session events
+  (curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/derive-enrichment" \
+    -H "$AUTH_HEADER" \
+    -H "Content-Type: application/json" \
+    -d '{}' > /dev/null 2>&1) &
+fi
+
+# ── Auto-generate recommendations (daily debounce) ──
+# Queue a recommendation job if one hasn't been generated today.
+# The worker picks it up and runs 7 Opus prompts (~$5-15 per run).
+(curl -sf -X POST "${RULEMETRIC_API_URL}/api/insights-jobs" \
+  -H "$AUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d "{\"dedup\":\"daily\",\"projectPath\":\"${HOOK_CWD}\"}" > /dev/null 2>&1) &
+
+# Clean up temp files
+rm -f "$TEMP_DIR/$HOOK_SESSION_ID" 2>/dev/null || true
+rm -f "$TEMP_DIR/$HOOK_SESSION_ID.seq" 2>/dev/null || true

package/scripts/session-start.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# RuleMetric: Session start hook
+# Ensures gateway + proxy are running. Session creation is handled by the proxy.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_log.sh" 2>/dev/null || _rulemetric_log() { :; }
+
+set -euo pipefail
+trap 'echo "rulemetric session-start failed at line $LINENO: $BASH_COMMAND" >&2; _rulemetric_log "session-start" "error" "line $LINENO: $BASH_COMMAND"; exit 1' ERR
+
+# Load config (env vars, ~/.config/rulemetric/env, or .env.local)
+source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
+
+# Read hook input from stdin and normalize across tools
+INPUT=$(cat)
+source "$SCRIPT_DIR/_normalize.sh"
+
+if [ -z "$HOOK_SESSION_ID" ]; then
+  _rulemetric_log "session-start" "skip" "no_session_id"
+  exit 0
+fi
+
+_rulemetric_log "session-start" "success"
+
+# ── Gateway auto-recovery ──
+# Ensure the gateway proxy is running so Claude Code can always connect.
+# The gateway routes direct when mitmproxy is off, so this is non-breaking.
+GATEWAY_PID_FILE="$HOME/.config/rulemetric/gateway.pid"
+
+if [ -f "$GATEWAY_PID_FILE" ]; then
+  GATEWAY_PID=$(cat "$GATEWAY_PID_FILE" 2>/dev/null)
+  if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
+    # Gateway crashed — respawn it
+    rulemetric gateway ensure 2>/dev/null || true
+  fi
+else
+  # No PID file — try to start gateway
+  rulemetric gateway ensure 2>/dev/null || true
+fi
+
+# ── Proxy auto-recovery ──
+# Ensure the capture proxy is running so events + context are captured.
+# Same pattern as gateway recovery above.
+PROXY_PID_FILE="$HOME/.config/rulemetric/proxy.pid"
+
+proxy_alive() {
+  if [ ! -f "$PROXY_PID_FILE" ]; then
+    return 1
+  fi
+  local pid
+  pid=$(cat "$PROXY_PID_FILE" 2>/dev/null) || return 1
+  kill -0 "$pid" 2>/dev/null
+}
+
+if ! proxy_alive; then
+  # Proxy is not running — try to restart it
+  rm -f "$PROXY_PID_FILE" 2>/dev/null
+  if command -v rulemetric >/dev/null 2>&1; then
+    rulemetric proxy start --port 8788 --skip-checks 2>/dev/null &
+    disown 2>/dev/null || true
+  fi
+fi

package/scripts/user-prompt.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# RuleMetric: Capture user prompts in real-time
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_log.sh" 2>/dev/null || _rulemetric_log() { :; }
+
+set -euo pipefail
+trap 'echo "rulemetric user-prompt failed at line $LINENO: $BASH_COMMAND" >&2; _rulemetric_log "user-prompt" "error" "line $LINENO: $BASH_COMMAND"; exit 1' ERR
+
+# Load config (env vars, ~/.config/rulemetric/env, or .env.local)
+source "$SCRIPT_DIR/_config.sh" 2>/dev/null || true
+
+# Read hook input from stdin and normalize across tools
+INPUT=$(cat)
+source "$SCRIPT_DIR/_normalize.sh"
+
+if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
+  _rulemetric_log "user-prompt" "skip" "no_config"
+  exit 0
+fi
+
+# Auth
+AUTH_HEADER=""
+if [ -n "${RULEMETRIC_API_KEY:-}" ]; then
+  AUTH_HEADER="Authorization: Bearer $RULEMETRIC_API_KEY"
+elif [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; then
+  AUTH_HEADER="Authorization: Bearer $RULEMETRIC_ACCESS_TOKEN"
+else
+  _rulemetric_log "user-prompt" "skip" "no_auth"
+  exit 0
+fi
+
+# Get or lazily create RuleMetric session
+source "$SCRIPT_DIR/_ensure-session.sh"
+if ! _rulemetric_ensure_session "user-prompt"; then
+  _rulemetric_log "user-prompt" "skip" "no_rw_session"
+  exit 0
+fi
+
+# Increment sequence counter (atomic mkdir lock, works on macOS + Linux)
+SEQ_FILE="$TEMP_DIR/$HOOK_SESSION_ID.seq"
+LOCK_DIR="$TEMP_DIR/$HOOK_SESSION_ID.seqlock"
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do sleep 0.01; done
+SEQ=1
+if [ -f "$SEQ_FILE" ]; then
+  SEQ=$(( $(cat "$SEQ_FILE") + 1 ))
+fi
+echo "$SEQ" > "$SEQ_FILE"
+rmdir "$LOCK_DIR"
+
+# Fire-and-forget: send user message event (capture HTTP errors for debugging)
+(CURL_OUT=$(curl -s -w "\n%{http_code}" -X POST "${RULEMETRIC_API_URL}/api/sessions/${RW_SESSION_ID}/events" \
+  -H "$AUTH_HEADER" \
+  -H "Content-Type: application/json" \
+  -d "{\"sequence\":$SEQ,\"eventType\":\"user_message\",\"content\":$(printf '%s' "$HOOK_PROMPT" | jq -Rs .),\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\"}" 2>&1)
+  HTTP_CODE=$(echo "$CURL_OUT" | tail -1)
+  if [ "$HTTP_CODE" != "200" ] && [ "$HTTP_CODE" != "201" ]; then
+    BODY=$(echo "$CURL_OUT" | sed '$d')
+    _rulemetric_log "user-prompt" "error" "http_${HTTP_CODE}_seq_${SEQ}: ${BODY}"
+  fi) &
+
+_rulemetric_log "user-prompt" "success"
+
+# Context capture is now handled by the proxy sniffer (`rulemetric proxy start`).
+# File-based scanning via _context-scan.sh is available as a manual fallback.

package/scripts-dir.js

@@ -0,0 +1,3 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const scriptsDir = join(dirname(fileURLToPath(import.meta.url)), 'scripts');