@rulemetric/hooks 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/hooks",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/_config.sh

@@ -4,14 +4,57 @@
 #   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)
+#
+# Also loads the active org from $config_dir/active-org (Phase 8.1).
+# Env var RULEMETRIC_ORG_ID always wins over the file. The variable is
+# exported so child curl/jq invocations and downstream scripts can see it.
+
+_rulemetric_config_dir() {
+  if [ -n "${RULEMETRIC_CONFIG_DIR:-}" ]; then
+    printf '%s' "$RULEMETRIC_CONFIG_DIR"
+    return
+  fi
+  printf '%s' "${XDG_CONFIG_HOME:-$HOME/.config}/rulemetric"
+}
+
+# Resolve the active org ID into RULEMETRIC_ORG_ID. Env beats file. A missing
+# or unparseable file is silently ignored — capture must never break.
+_rulemetric_load_active_org() {
+  if [ -n "${RULEMETRIC_ORG_ID:-}" ]; then
+    export RULEMETRIC_ORG_ID
+    return 0
+  fi
+
+  local config_dir
+  config_dir=$(_rulemetric_config_dir)
+  local active_file="$config_dir/active-org"
+
+  if [ ! -f "$active_file" ]; then
+    return 0
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    return 0
+  fi
+
+  local org_id
+  # `|| true` so a parse error from jq doesn't abort under `set -e`.
+  org_id=$(jq -r '.orgId // empty' "$active_file" 2>/dev/null || true)
+  if [ -n "$org_id" ] && [ "$org_id" != "null" ]; then
+    export RULEMETRIC_ORG_ID="$org_id"
+  fi
+  return 0
+}
 
 _rulemetric_load_config() {
-  # If already configured, nothing to do
+  # If already configured, nothing to do for credentials.
   if [ -n "${RULEMETRIC_API_URL:-}" ] && { [ -n "${RULEMETRIC_API_KEY:-}" ] || [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; }; then
+    _rulemetric_load_active_org
     return 0
   fi
 
-  local config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/rulemetric"
+  local config_dir
+  config_dir=$(_rulemetric_config_dir)
 
   # Try global env file (shell-sourceable, written by `rulemetric auth login`)
   if [ -f "$config_dir/env" ]; then
@@ -20,6 +63,7 @@ _rulemetric_load_config() {
     source "$config_dir/env"
     set +a
     if [ -n "${RULEMETRIC_API_URL:-}" ] && { [ -n "${RULEMETRIC_API_KEY:-}" ] || [ -n "${RULEMETRIC_ACCESS_TOKEN:-}" ]; }; then
+      _rulemetric_load_active_org
       return 0
     fi
   fi
@@ -32,6 +76,7 @@ _rulemetric_load_config() {
       export RULEMETRIC_ACCESS_TOKEN="$token"
       # Default API URL if not set
       export RULEMETRIC_API_URL="${RULEMETRIC_API_URL:-https://api.rulemetric.com}"
+      _rulemetric_load_active_org
       return 0
     fi
   fi
@@ -51,9 +96,11 @@ _rulemetric_load_config() {
           ;;
       esac
     done < .env.local
+    _rulemetric_load_active_org
     return 0
   fi
 
+  _rulemetric_load_active_org
   return 0
 }
 

package/scripts/_ensure-session.sh

@@ -52,14 +52,68 @@ _rulemetric_ensure_session() {
   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 .)")
+
+  # GUARD: a top-level user home dir (e.g. `/Users/foo`, `/home/bar`) is
+  # never a real project root, even if some env quirk lets git resolve a
+  # repo from there (stale GIT_DIR, walked-up worktree, etc.). Suppress
+  # all git context capture so we don't pollute the session row with a
+  # remote that doesn't actually belong to this path.
+  local is_home_dir="false"
+  if [[ "$cwd" =~ ^/(Users|home)/[^/]+/?$ ]]; then
+    is_home_dir="true"
+  fi
+
+  local git_branch=""
+  local git_remote=""
+  local git_root_commit=""
+  local is_worktree="false"
+
+  if [ "$is_home_dir" = "false" ]; then
+    git_branch=$(cd "$cwd" 2>/dev/null && git branch --show-current 2>/dev/null || echo "")
+    git_remote=$(cd "$cwd" 2>/dev/null && git remote get-url origin 2>/dev/null || echo "")
+    # Root commit = SHA of the very first commit. Stable forever (unless
+    # someone rewrites root). Survives URL renames; secondary identity for
+    # project matching. Empty string if repo has no commits / not a repo.
+    git_root_commit=$(cd "$cwd" 2>/dev/null && git rev-list --max-parents=0 HEAD 2>/dev/null | tail -1 || echo "")
+    # Worktree detection: in a worktree, `git rev-parse --git-dir` differs
+    # from `--git-common-dir`. The capture metadata gets a boolean so the
+    # API can tag the project_checkouts row as is_worktree=true.
+    local git_dir
+    git_dir=$(cd "$cwd" 2>/dev/null && git rev-parse --git-dir 2>/dev/null || echo "")
+    local git_common_dir
+    git_common_dir=$(cd "$cwd" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null || echo "")
+    if [ -n "$git_dir" ] && [ -n "$git_common_dir" ] && [ "$git_dir" != "$git_common_dir" ]; then
+      is_worktree="true"
+    fi
+  fi
+
+  # Explicit launch attribution (Phase 12). When a launcher (the web
+  # dashboard's "Launch Session", a CLI wrapper, or the user themselves)
+  # exports RULEMETRIC_LAUNCH_PROJECT_PATH, capture it as a stronger
+  # attribution signal than cwd. Use case: a skill chdir's into a target
+  # repo before invoking claude — without this hint, cwd at hook time
+  # describes where the work happens, not which project actually launched
+  # the session.
+  local launch_project_path="${RULEMETRIC_LAUNCH_PROJECT_PATH:-}"
+
+  local metadata
+  metadata=$(jq -n \
+    --arg gitRemote "$git_remote" \
+    --arg gitRootCommit "$git_root_commit" \
+    --arg launchProjectPath "$launch_project_path" \
+    --argjson isWorktree "$is_worktree" \
+    '{} + (if $gitRemote != "" then {gitRemote: $gitRemote} else {} end)
+        + (if $gitRootCommit != "" then {gitRootCommit: $gitRootCommit} else {} end)
+        + (if $launchProjectPath != "" then {launchProjectPath: $launchProjectPath} else {} end)
+        + {isWorktree: $isWorktree}')
+
+  # Optional org attribution (Phase 8.1). RULEMETRIC_ORG_ID is exported by
+  # _config.sh — env wins over the local active-org file. If unset/empty, we
+  # encode `null` so the API can validate it cleanly. The API silently nulls
+  # the value if the user isn't a member, so capture never breaks.
+  local org_id_arg='null'
+  if [ -n "${RULEMETRIC_ORG_ID:-}" ]; then
+    org_id_arg=$(jq -n --arg v "$RULEMETRIC_ORG_ID" '$v')
   fi
 
   local payload
@@ -69,7 +123,8 @@ _rulemetric_ensure_session() {
     --arg projectPath "$cwd" \
     --arg gitBranch "$git_branch" \
     --argjson metadata "$metadata" \
-    '{tool: $tool, externalSessionId: $externalSessionId, projectPath: $projectPath, gitBranch: $gitBranch, metadata: $metadata}')
+    --argjson orgId "$org_id_arg" \
+    '{tool: $tool, externalSessionId: $externalSessionId, projectPath: $projectPath, gitBranch: $gitBranch, metadata: $metadata, orgId: $orgId}')
 
   local response
   response=$(curl -sf -X POST "${RULEMETRIC_API_URL}/api/sessions" \

package/scripts/assistant-response.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# RuleMetric: Capture assistant-response events from harness hooks.
+#
+# Receives the assistant's response text + token usage. Cursor's
+# `afterAgentResponse` event exposes both directly; Claude Code emits the
+# equivalent via SessionEnd telemetry, and Copilot's `afterAgentResponse`
+# in agent mode follows the same shape. This script posts a single
+# event of type `assistant_response` with the text as `content` and the
+# token usage in `tokenUsage`.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_log.sh" 2>/dev/null || _rulemetric_log() { :; }
+
+set -euo pipefail
+trap 'echo "rulemetric assistant-response failed at line $LINENO: $BASH_COMMAND" >&2; _rulemetric_log "assistant-response" "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
+
+INPUT=$(cat)
+source "$SCRIPT_DIR/_normalize.sh"
+
+if [ -z "$HOOK_SESSION_ID" ] || [ -z "${RULEMETRIC_API_URL:-}" ]; then
+  _rulemetric_log "assistant-response" "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 "assistant-response" "skip" "no_auth"
+  exit 0
+fi
+
+# Get or lazily create RuleMetric session (same as post-tool-use)
+source "$SCRIPT_DIR/_ensure-session.sh"
+if ! _rulemetric_ensure_session "assistant-response"; then
+  _rulemetric_log "assistant-response" "skip" "no_rw_session"
+  exit 0
+fi
+
+# Extract assistant response fields. Cursor's afterAgentResponse uses `text`
+# + flat token counters. Claude Code's session-end / Copilot's response
+# hooks may use different field names, but for now this script is wired
+# only for Cursor — the harness-specific extraction is intentionally
+# explicit rather than via _normalize.sh, since the shapes diverge.
+TEXT=$(echo "$INPUT" | jq -r '.text // .content // empty')
+if [ -z "$TEXT" ]; then
+  _rulemetric_log "assistant-response" "skip" "no_text"
+  exit 0
+fi
+
+GENERATION_ID=$(echo "$INPUT" | jq -r '.generation_id // empty')
+INPUT_TOKENS=$(echo "$INPUT" | jq -r '.input_tokens // empty')
+OUTPUT_TOKENS=$(echo "$INPUT" | jq -r '.output_tokens // empty')
+CACHE_READ=$(echo "$INPUT" | jq -r '.cache_read_tokens // empty')
+CACHE_WRITE=$(echo "$INPUT" | jq -r '.cache_write_tokens // empty')
+
+# Build token_usage object (only include fields the harness actually sent)
+TOKEN_USAGE=$(jq -n \
+  --arg in "$INPUT_TOKENS" \
+  --arg out "$OUTPUT_TOKENS" \
+  --arg cr "$CACHE_READ" \
+  --arg cw "$CACHE_WRITE" \
+  '{} +
+    (if $in  != "" then {input_tokens: ($in | tonumber)}        else {} end) +
+    (if $out != "" then {output_tokens: ($out | tonumber)}      else {} end) +
+    (if $cr  != "" then {cache_read_input_tokens: ($cr | tonumber)} else {} end) +
+    (if $cw  != "" then {cache_creation_input_tokens: ($cw | tonumber)} else {} end)')
+
+# Increment per-session sequence (same locking pattern as post-tool-use)
+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"
+
+# Truncate text payload defensively (8 KB cap matches what the addon caps
+# its captured snapshots at).
+MAX_TEXT=8192
+if [ "${#TEXT}" -gt "$MAX_TEXT" ]; then
+  TEXT=$(printf '%s' "$TEXT" | head -c "$MAX_TEXT")
+fi
+
+# Build metadata in bash so the jq filter stays trivially parseable.
+# Convention matches existing Claude Code assistant_response events
+# (token usage lives at metadata.usage, not at the top level).
+META=$(jq -nc \
+  --arg generationId "$GENERATION_ID" \
+  --argjson usage "$TOKEN_USAGE" \
+  '{}
+    + (if $generationId != "" then {generationId: $generationId} else {} end)
+    + (if ($usage | length) > 0 then {usage: $usage} else {} end)')
+
+PAYLOAD=$(jq -n \
+  --argjson seq "$SEQ" \
+  --arg text "$TEXT" \
+  --argjson metadata "$META" \
+  --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
+  '{
+    sequence: $seq,
+    eventType: "assistant_response",
+    content: $text,
+    timestamp: $timestamp,
+    metadata: $metadata
+  }')
+
+_rulemetric_log "assistant-response" "success"
+
+# Fire-and-forget (same error-logging pattern as post-tool-use)
+(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 "assistant-response" "error" "http_${HTTP_CODE}_seq_${SEQ}: ${BODY}"
+  fi) &

package/scripts/session-start.sh

@@ -21,6 +21,42 @@ fi
 
 _rulemetric_log "session-start" "success"
 
+# ── Auth health check ──
+# Verify the API key / access token actually works before the session starts.
+# If auth is broken, the proxy will silently drop every captured snapshot.
+_rulemetric_check_auth() {
+  local api_url="${RULEMETRIC_API_URL:-}"
+  local auth_token="${RULEMETRIC_API_KEY:-${RULEMETRIC_ACCESS_TOKEN:-}}"
+
+  # No credentials configured — warn
+  if [ -z "$api_url" ] || [ -z "$auth_token" ]; then
+    echo "[rulemetric] ⚠ Session tracking not configured — no API credentials found." >&2
+    echo "[rulemetric]   Run: rulemetric auth login" >&2
+    _rulemetric_log "session-start" "warn" "no_auth_credentials"
+    return 0
+  fi
+
+  # Quick auth check — GET /api/sessions?limit=1 with a 3s timeout
+  local http_code
+  http_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 \
+    "$api_url/api/sessions?limit=1" \
+    -H "Authorization: Bearer $auth_token" 2>/dev/null) || http_code="000"
+
+  if [ "$http_code" = "401" ] || [ "$http_code" = "403" ]; then
+    echo "[rulemetric] ⚠ Session tracking disconnected — API key is invalid or expired." >&2
+    echo "[rulemetric]   Run: rulemetric auth login" >&2
+    _rulemetric_log "session-start" "warn" "auth_failed_$http_code"
+  elif [ "$http_code" = "000" ]; then
+    echo "[rulemetric] ⚠ Session tracking disconnected — API unreachable at $api_url" >&2
+    echo "[rulemetric]   Is the API running? Check: curl $api_url/health" >&2
+    _rulemetric_log "session-start" "warn" "api_unreachable"
+  elif [ "$http_code" != "200" ]; then
+    _rulemetric_log "session-start" "warn" "auth_check_http_$http_code"
+  fi
+}
+
+_rulemetric_check_auth
+
 # ── 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.
@@ -59,3 +95,92 @@ if ! proxy_alive; then
     disown 2>/dev/null || true
   fi
 fi
+
+# ── Instruction suggestions (non-blocking) ──
+# Fetch the top precomputed suggestions for this project and surface them to
+# the user. All failures are silent — this block MUST NOT prevent session
+# start under any circumstances. Hard timeout: 4s on the read, 3s on the
+# event-logging writes (which are backgrounded + disowned).
+_rulemetric_suggest_instructions() {
+  local api_url="${RULEMETRIC_API_URL:-}"
+  local auth_token="${RULEMETRIC_API_KEY:-${RULEMETRIC_ACCESS_TOKEN:-}}"
+  local project_path
+  project_path="$(realpath -m "$(pwd)" 2>/dev/null || pwd)"
+
+  [ -n "$api_url" ] && [ -n "$auth_token" ] || return 0
+  command -v jq >/dev/null 2>&1 || return 0
+
+  local encoded_path
+  encoded_path="$(python3 -c \
+    "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" \
+    "$project_path" 2>/dev/null)" || encoded_path="$project_path"
+
+  local response
+  # Phase 2b: request includeContent=true so high-confidence (score >= 0.7)
+  # suggestions arrive with the actual rule body. The body is rendered to
+  # stdout, which Claude Code surfaces to the model as session context.
+  # Low-confidence suggestions still render as name+reason only.
+  response="$(curl -s --max-time 4 \
+    "${api_url}/api/instruction-suggestions?projectPath=${encoded_path}&limit=3&includeContent=true" \
+    -H "Authorization: Bearer ${auth_token}" 2>/dev/null)" || return 0
+
+  local count
+  count="$(printf '%s' "$response" | jq -r '.suggestions | length' 2>/dev/null)" || return 0
+  [ "$count" != "0" ] && [ "$count" != "null" ] && [ -n "$count" ] || return 0
+
+  # Count high-confidence rows (those with non-null content) for the header
+  local high_count
+  high_count="$(printf '%s' "$response" | jq -r '[.suggestions[] | select(.content != null)] | length' 2>/dev/null)" || high_count="0"
+
+  printf '\n---\n'
+  if [ "$high_count" != "0" ] && [ -n "$high_count" ]; then
+    printf '[rulemetric] %s high-confidence instruction(s) included below as session context.\n' "$high_count"
+    printf 'Accept any of them permanently with: rulemetric suggestions accept <id>\n'
+  else
+    printf '[rulemetric] %s instruction(s) may help with this project:\n' "$count"
+  fi
+
+  local i=0
+  while [ "$i" -lt "$count" ]; do
+    local name reason score scope content
+    name="$(printf '%s' "$response"  | jq -r ".suggestions[$i].name"             2>/dev/null)" || break
+    reason="$(printf '%s' "$response" | jq -r ".suggestions[$i].reason"          2>/dev/null)" || break
+    score="$(printf '%s' "$response"  | jq -r ".suggestions[$i].score"           2>/dev/null)" || break
+    scope="$(printf '%s' "$response"  | jq -r ".suggestions[$i].instructionScope" 2>/dev/null)" || break
+    content="$(printf '%s' "$response" | jq -r ".suggestions[$i].content // empty" 2>/dev/null)" || content=""
+
+    if [ -n "$content" ]; then
+      printf '\n## Skill: %s (%s, score: %s)\n%s\n\n%s\n' "$name" "$scope" "$score" "$reason" "$content"
+    else
+      printf '  * [%s] %s (score: %s)\n    %s\n' "$scope" "$name" "$score" "$reason"
+    fi
+    i=$((i + 1))
+  done
+
+  printf '\n---\n'
+
+  # Log surfaced events fire-and-forget. Event type differs based on whether
+  # the full content was included so we can later measure outcome differences.
+  i=0
+  local tool="${HOOK_TOOL:-unknown}"
+  while [ "$i" -lt "$count" ]; do
+    local sid has_content event_type
+    sid="$(printf '%s' "$response" | jq -r ".suggestions[$i].id" 2>/dev/null)" || break
+    has_content="$(printf '%s' "$response" | jq -r ".suggestions[$i].content // \"null\"" 2>/dev/null)" || has_content="null"
+    if [ "$has_content" != "null" ] && [ -n "$has_content" ]; then
+      event_type="surfaced_with_content"
+    else
+      event_type="surfaced"
+    fi
+    curl -s --max-time 3 -X POST \
+      "${api_url}/api/instruction-suggestions/${sid}/events" \
+      -H "Authorization: Bearer ${auth_token}" \
+      -H "Content-Type: application/json" \
+      -d "{\"eventType\":\"${event_type}\",\"tool\":\"${tool}\",\"projectPath\":\"${project_path}\"}" \
+      >/dev/null 2>&1 &
+    disown 2>/dev/null || true
+    i=$((i + 1))
+  done
+}
+
+_rulemetric_suggest_instructions || true