@onlooker-community/ecosystem 0.10.0 → 0.15.0

package/scripts/hooks/prompt-rule-injector.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Onlooker Prompt Rule Injector
+# Invoked by UserPromptSubmit. Loads declarative prompt rules from
+#   ~/.onlooker/prompt-rules.json (global)
+#   <cwd>/.claude/prompt-rules.json (project, overrides global by id)
+# and injects guidance for rules whose POSIX-ERE pattern matches the prompt.
+# Each rule fires at most once per session per rule_id.
+#
+# Emits canonical-ish events to ~/.onlooker/logs/onlooker-events.jsonl:
+#   prompt_rule.matched — every match (including subsequent matches in-session)
+#   prompt_rule.applied — only when guidance is actually injected
+#
+# Usage:
+#   echo "$INPUT" | prompt-rule-injector.sh
+
+set -uo pipefail # No -e: never block prompt submission
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/validate-path.sh
+source "$SCRIPT_DIR/../lib/validate-path.sh"
+# shellcheck source=../lib/prompt-rules.sh
+source "$SCRIPT_DIR/../lib/prompt-rules.sh"
+
+hook_register "prompt-rule-injector" "Prompt Rule Injector" "Injects declarative guidance when regex rules match prompts"
+
+INPUT=$(cat)
+hook_set_context "$INPUT" "UserPromptSubmit"
+
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""')
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+[[ -z "$CWD" ]] && CWD="$PWD"
+
+turn_state_export "$SESSION_ID"
+
+CONFIG_FILE="${CLAUDE_PLUGIN_ROOT:-}/config.json"
+PER_TURN_MAX_CHARS=1200
+ENABLED=true
+if [[ -f "$CONFIG_FILE" ]]; then
+  # `// true` would coerce an explicit `false` to true; check the field explicitly.
+  ENABLED=$(jq -r 'if (.prompt_rules.enabled == false) then "false" else "true" end' "$CONFIG_FILE" 2>/dev/null) || ENABLED=true
+  PER_TURN_MAX_CHARS=$(jq -r '.prompt_rules.per_turn_max_chars // 1200' "$CONFIG_FILE" 2>/dev/null) || PER_TURN_MAX_CHARS=1200
+fi
+
+if [[ "$ENABLED" != "true" ]]; then
+  hook_success
+  exit 0
+fi
+
+RULES=$(prompt_rules_load_merged "$CWD")
+RULE_COUNT=$(echo "$RULES" | jq 'length' 2>/dev/null || echo 0)
+if [[ "$RULE_COUNT" -eq 0 ]]; then
+  hook_success
+  exit 0
+fi
+
+FIRED=$(prompt_rules_load_fired "$SESSION_ID")
+COMBINED_GUIDANCE=""
+COMBINED_LEN=0
+
+while IFS= read -r rule; do
+  [[ -z "$rule" ]] && continue
+  RULE_ID=$(echo "$rule" | jq -r '.id // empty')
+  PATTERN=$(echo "$rule" | jq -r '.pattern // empty')
+  GUIDANCE=$(echo "$rule" | jq -r '.guidance // empty')
+  MAX_CHARS=$(echo "$rule" | jq -r '.max_chars // 400')
+  # `// true` would coerce an explicit `false` to true (jq's // treats `false`
+  # like `null`); check the field explicitly so rules can opt out of fire-once.
+  FIRE_ONCE=$(echo "$rule" | jq -r 'if (.fire_once_per_session == false) then "false" else "true" end')
+
+  [[ -z "$RULE_ID" || -z "$PATTERN" || -z "$GUIDANCE" ]] && continue
+
+  if ! prompt_rules_pattern_matches "$PROMPT" "$PATTERN"; then
+    continue
+  fi
+
+  prompt_rules_emit "$SESSION_ID" "prompt_rule.matched" \
+    "$(jq -cn --arg id "$RULE_ID" '{rule_id: $id}')" || true
+
+  ALREADY_FIRED=$(echo "$FIRED" | jq --arg id "$RULE_ID" 'index($id) != null' 2>/dev/null)
+  if [[ "$FIRE_ONCE" == "true" && "$ALREADY_FIRED" == "true" ]]; then
+    continue
+  fi
+
+  if (( ${#GUIDANCE} > MAX_CHARS )); then
+    GUIDANCE="${GUIDANCE:0:$MAX_CHARS}"
+  fi
+
+  ADD_LEN=${#GUIDANCE}
+  # +2 accounts for the blank-line separator between guidance entries.
+  if (( COMBINED_LEN + ADD_LEN + 2 > PER_TURN_MAX_CHARS )); then
+    continue
+  fi
+
+  if [[ -n "$COMBINED_GUIDANCE" ]]; then
+    COMBINED_GUIDANCE="$COMBINED_GUIDANCE"$'\n\n'"$GUIDANCE"
+    COMBINED_LEN=$(( COMBINED_LEN + ADD_LEN + 2 ))
+  else
+    COMBINED_GUIDANCE="$GUIDANCE"
+    COMBINED_LEN=$ADD_LEN
+  fi
+
+  prompt_rules_mark_fired "$SESSION_ID" "$RULE_ID" || hook_failure "Failed to mark rule fired: $RULE_ID"
+  FIRED=$(prompt_rules_load_fired "$SESSION_ID")
+
+  prompt_rules_emit "$SESSION_ID" "prompt_rule.applied" \
+    "$(jq -cn --arg id "$RULE_ID" --argjson chars "$ADD_LEN" \
+      '{rule_id: $id, guidance_chars: $chars}')" || true
+done < <(echo "$RULES" | jq -c '.[]' 2>/dev/null)
+
+if [[ -n "$COMBINED_GUIDANCE" ]]; then
+  jq -n --arg ctx "$COMBINED_GUIDANCE" \
+    '{
+      hookSpecificOutput: {
+        hookEventName: "UserPromptSubmit",
+        additionalContext: $ctx
+      }
+    }'
+fi
+
+hook_success
+exit 0

package/scripts/lib/portable-lock.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Portable advisory file locking via mkdir() atomicity.
+#
+# Replaces flock(1), which ships with util-linux on Linux but is not present
+# in stock macOS. This matters because the Onlooker hooks run on user
+# machines, not just in CI: a macOS user without util-linux would otherwise
+# see every PostToolUse history append silently fail.
+#
+# mkdir() is atomic on POSIX local filesystems, which is the only place
+# $ONLOOKER_DIR ever lives. Network filesystems (NFS) do not guarantee
+# atomicity, but Claude Code state is local-only.
+#
+# Usage:
+#   lock_acquire "/path/to/file.lock" [timeout_seconds=5]
+#   # ... critical section ...
+#   lock_release "/path/to/file.lock"
+#
+# Avoid associative arrays so bash 3.2 (macOS default) keeps working.
+
+# Acquire an exclusive lock at LOCKPATH. Returns 0 on success, 1 on timeout.
+lock_acquire() {
+	local lockpath="${1:-}"
+	local timeout="${2:-5}"
+	[[ -z "$lockpath" ]] && return 1
+
+	local lockdir="${lockpath}.d"
+	local waited=0
+	# Poll at 10 Hz so a 5s timeout = 50 attempts.
+	local max_iter=$((timeout * 10))
+	while ! mkdir "$lockdir" 2>/dev/null; do
+		if ((waited >= max_iter)); then
+			return 1
+		fi
+		# `sleep 0.1` works on Linux + macOS; the `|| sleep 1` is a paranoid
+		# fallback for embedded shells that only accept integer seconds.
+		sleep 0.1 2>/dev/null || sleep 1
+		waited=$((waited + 1))
+	done
+	return 0
+}
+
+# Release the lock previously acquired for LOCKPATH. Safe to call when the
+# lock is not held (no-op in that case).
+lock_release() {
+	local lockpath="${1:-}"
+	[[ -z "$lockpath" ]] && return 0
+	rmdir "${lockpath}.d" 2>/dev/null || true
+}

package/scripts/lib/prompt-rules.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# Prompt-rule library — declarative regex-triggered guidance injection.
+#
+# Source after validate-path.sh:
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/validate-path.sh"
+#   source "$CLAUDE_PLUGIN_ROOT/scripts/lib/prompt-rules.sh"
+#
+# Rule schema (JSON file at ~/.onlooker/prompt-rules.json or <cwd>/.claude/prompt-rules.json):
+#   {
+#     "rules": [
+#       {
+#         "id": "rule-no-verify-warning",
+#         "pattern": "--no-verify",
+#         "guidance": "Skipping hooks usually masks the real issue.",
+#         "fire_once_per_session": true,
+#         "max_chars": 400,
+#         "enabled": true,
+#         "tags": ["safety"]
+#       }
+#     ]
+#   }
+#
+# Patterns are POSIX ERE (bash [[ =~ ]] semantics). `\b` is unsupported;
+# use `(^|[^a-zA-Z0-9_])foo([^a-zA-Z0-9_]|$)` for word-boundary behavior.
+
+export ONLOOKER_PROMPT_RULES_DIR="${ONLOOKER_PROMPT_RULES_DIR:-$ONLOOKER_DIR/prompt-rules}"
+export ONLOOKER_PROMPT_RULES_SESSIONS_DIR="$ONLOOKER_PROMPT_RULES_DIR/sessions"
+
+# Path to the global rules file.
+# Usage: path=$(prompt_rules_global_path)
+prompt_rules_global_path() {
+  printf '%s\n' "$ONLOOKER_DIR/prompt-rules.json"
+}
+
+# Path to the project-scoped rules file for a given cwd.
+# Usage: path=$(prompt_rules_project_path "$cwd")
+prompt_rules_project_path() {
+  local cwd="${1:-$PWD}"
+  printf '%s\n' "$cwd/.claude/prompt-rules.json"
+}
+
+# Path to the fired-marker file for a session.
+# Usage: path=$(prompt_rules_fired_path "$session_id")
+prompt_rules_fired_path() {
+  local session_id="${1:-unknown}"
+  printf '%s\n' "$ONLOOKER_PROMPT_RULES_SESSIONS_DIR/$session_id.json"
+}
+
+# Print the merged rules JSON array. Project entries override global by id.
+# Disabled rules (enabled: false) are filtered out.
+# Usage: rules=$(prompt_rules_load_merged "$cwd")
+prompt_rules_load_merged() {
+  local cwd="${1:-$PWD}"
+  local global_path project_path
+  global_path=$(prompt_rules_global_path)
+  project_path=$(prompt_rules_project_path "$cwd")
+
+  local global_json='[]'
+  local project_json='[]'
+  if [[ -f "$global_path" ]]; then
+    global_json=$(jq -c '.rules // []' "$global_path" 2>/dev/null) || global_json='[]'
+  fi
+  if [[ -f "$project_path" ]]; then
+    project_json=$(jq -c '.rules // []' "$project_path" 2>/dev/null) || project_json='[]'
+  fi
+
+  jq -n \
+    --argjson g "$global_json" \
+    --argjson p "$project_json" \
+    '
+    # Coerce non-array inputs to []; drop entries without a string id so a
+    # single malformed rule cannot poison `map({(.id): .})` (which errors when
+    # `.id` is null or non-string).
+    def to_array(x): if (x | type) == "array" then x else [] end;
+    def sanitize(arr): to_array(arr) | map(select(type == "object" and (.id | type) == "string" and .id != ""));
+    def to_map(arr): (sanitize(arr) | map({(.id): .}) | add) // {};
+    (to_map($g) + to_map($p))
+    | to_entries
+    | map(.value)
+    | map(select(.enabled != false))
+    '
+}
+
+# Print the fired-id JSON array for a session.
+# Usage: fired=$(prompt_rules_load_fired "$session_id")
+prompt_rules_load_fired() {
+  local session_id="${1:-unknown}"
+  local path
+  path=$(prompt_rules_fired_path "$session_id")
+  if [[ -f "$path" ]]; then
+    jq -c '.fired_ids // []' "$path" 2>/dev/null || echo '[]'
+  else
+    echo '[]'
+  fi
+}
+
+# Mark a rule id as fired for a session. Idempotent.
+# Read-modify-write is wrapped in a portable file lock so concurrent
+# UserPromptSubmit hooks (or other writers) can't drop updates or corrupt
+# the marker file — same pattern as tool-history.sh.
+# Usage: prompt_rules_mark_fired "$session_id" "$rule_id"
+prompt_rules_mark_fired() {
+  local session_id="${1:-unknown}"
+  local rule_id="${2:-}"
+  [[ -z "$rule_id" ]] && return 1
+  local path
+  path=$(prompt_rules_fired_path "$session_id")
+  ensure_dir_exists "$(dirname "$path")" || return 1
+
+  local lockfile="${path}.lock"
+  lock_acquire "$lockfile" 5 || return 1
+
+  local current='[]'
+  if [[ -f "$path" ]]; then
+    current=$(jq -c '.fired_ids // []' "$path" 2>/dev/null) || current='[]'
+  fi
+  local next rc=0
+  next=$(jq -cn --argjson cur "$current" --arg id "$rule_id" \
+    '{fired_ids: ($cur + [$id] | unique)}')
+  printf '%s\n' "$next" > "$path" || rc=$?
+  lock_release "$lockfile"
+  return "$rc"
+}
+
+# Test whether a POSIX ERE pattern matches the given prompt.
+# Returns 0 on match, 1 otherwise (including empty or invalid pattern).
+# Invalid ERE patterns from user-edited rule files would otherwise leak a
+# "syntax error in regular expression" message to stderr and return status 2;
+# we treat that as a non-match so the hook stays quiet on bad input.
+# Usage: prompt_rules_pattern_matches "$prompt" "$pattern" && echo "hit"
+prompt_rules_pattern_matches() {
+  local prompt="$1"
+  local pattern="$2"
+  [[ -z "$pattern" ]] && return 1
+  { [[ "$prompt" =~ $pattern ]]; } 2>/dev/null
+  local rc=$?
+  # Bash returns 2 for a malformed regex; collapse to "no match".
+  if (( rc == 0 )); then
+    return 0
+  fi
+  return 1
+}
+
+# Append a prompt-rule event to the global events log.
+# These event types (prompt_rule.matched, prompt_rule.applied) are not yet
+# in @onlooker-community/schema; once added, swap to onlooker_append_event.
+# Usage: prompt_rules_emit "$session_id" "prompt_rule.matched" "$payload_json"
+prompt_rules_emit() {
+  local session_id="${1:-unknown}"
+  local event_type="${2:-}"
+  local payload_json="${3:-{\}}"
+  [[ -z "$event_type" ]] && return 1
+  ensure_file_exists "$ONLOOKER_EVENTS_LOG" || return 1
+
+  local timestamp plugin
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  plugin="${ONLOOKER_PLUGIN_NAME:-onlooker}"
+
+  jq -cn \
+    --arg ts "$timestamp" \
+    --arg sid "$session_id" \
+    --arg plugin "$plugin" \
+    --arg type "$event_type" \
+    --argjson payload "$payload_json" \
+    --arg turn "${ONLOOKER_TURN_NUMBER:-}" \
+    '{timestamp: $ts, session_id: $sid, plugin: $plugin, event_type: $type, payload: $payload}
+     + (if $turn != "" then {turn: ($turn | tonumber)} else {} end)
+    ' >> "$ONLOOKER_EVENTS_LOG"
+}
+
+# Print a human-readable table of merged rules with their fired status.
+# Usage: prompt_rules_list_table "$session_id" "$cwd"
+prompt_rules_list_table() {
+  local session_id="${1:-unknown}"
+  local cwd="${2:-$PWD}"
+
+  local rules fired global_path project_path
+  rules=$(prompt_rules_load_merged "$cwd")
+  fired=$(prompt_rules_load_fired "$session_id")
+  global_path=$(prompt_rules_global_path)
+  project_path=$(prompt_rules_project_path "$cwd")
+
+  local rule_count
+  rule_count=$(echo "$rules" | jq 'length' 2>/dev/null || echo 0)
+
+  printf 'Prompt rules (session: %s)\n' "$session_id"
+  printf '  global file:  %s%s\n' "$global_path" \
+    "$([[ -f "$global_path" ]] && printf '' || printf ' (missing)')"
+  printf '  project file: %s%s\n' "$project_path" \
+    "$([[ -f "$project_path" ]] && printf '' || printf ' (missing)')"
+  printf '  active rules: %s\n' "$rule_count"
+  printf '\n'
+
+  if [[ "$rule_count" -eq 0 ]]; then
+    printf '  (no rules)\n'
+    return 0
+  fi
+
+  echo "$rules" | jq -r --argjson fired "$fired" '
+    .[]
+    | . as $rule
+    | "  - id: \(.id)\n"
+      + "    pattern: \(.pattern)\n"
+      + "    fired: \(if ($fired | any(. == $rule.id)) then "yes" else "no" end)\n"
+      + "    guidance: \(.guidance)\n"
+  '
+}

package/scripts/lib/tool-history.sh

@@ -13,8 +13,9 @@ tool_history_build_record() {
 	onlooker_event_from_hook "$input_json"
 }
 
-# Append a canonical event to the session JSONL history (flock-protected).
-# Usage: tool_history_append "$SESSION_ID" "$event_json"
+# Append a canonical event to the session JSONL history (lock-protected).
+# Uses the portable mkdir-based mutex so the hook works on macOS as well as
+# Linux. Usage: tool_history_append "$SESSION_ID" "$event_json"
 tool_history_append() {
 	local session_id="${1:-}"
 	local record_json="${2:-}"
@@ -25,11 +26,9 @@ tool_history_append() {
 	ensure_dir_exists "$ONLOOKER_SESSION_HISTORY_DIR" || return 1
 
 	local lockfile="${history_file}.lock"
-	exec 202>"$lockfile"
-	if ! flock -w 5 202; then
-		return 1
-	fi
-
+	lock_acquire "$lockfile" 5 || return 1
 	printf '%s\n' "$record_json" >>"$history_file" 2>/dev/null
-	flock -u 202
+	local rc=$?
+	lock_release "$lockfile"
+	return "$rc"
 }

package/scripts/lib/validate-path.sh

@@ -22,6 +22,10 @@ export ONLOOKER_EVENTS_LOG="$ONLOOKER_DIR/logs/onlooker-events.jsonl"
 export ONLOOKER_HOOK_HEALTH_LOG="$ONLOOKER_DIR/logs/hook-health.jsonl"
 _VALIDATE_PATH_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 export ONLOOKER_EMIT="$_VALIDATE_PATH_DIR/onlooker-emit.sh"
+# Portable mutex (flock substitute) — every hook script that needs to write
+# shared state can call lock_acquire/lock_release after sourcing this file.
+# shellcheck source=portable-lock.sh
+source "$_VALIDATE_PATH_DIR/portable-lock.sh"
 unset _VALIDATE_PATH_DIR
 
 # ==============================================================================