@onlooker-community/ecosystem 0.16.0 → 0.18.0

package/plugins/compass/scripts/hooks/compass-pre-tool-use.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Compass PreToolUse hook — main alignment gate for Write, Edit, MultiEdit.
+#
+# Fires before write-class tool calls. Resolves the file path from the
+# tool input and delegates to the shared compass-gate.sh pipeline.
+#
+# Hook contract (Claude Code PreToolUse protocol):
+#   - Always exits 0.
+#   - To block: compass_run_gate writes {"decision":"block","reason":"..."} to stdout.
+#   - To allow: nothing written to stdout.
+#   - Errors are written to stderr only.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/compass-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-config.sh"
+# shellcheck source=../lib/compass-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-events.sh"
+# shellcheck source=../lib/compass-sanitizer.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-sanitizer.sh"
+# shellcheck source=../lib/compass-transcript.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-transcript.sh"
+# shellcheck source=../lib/compass-evaluator.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-evaluator.sh"
+# shellcheck source=../lib/compass-gate.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-gate.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL_NAME=""
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+compass_config_load "$CWD"
+
+if ! compass_config_enabled; then
+	exit 0
+fi
+
+# -----------------------------------------------------------------------
+# Resolve file path and context from tool input.
+# -----------------------------------------------------------------------
+FILE_PATH=""
+CONTEXT=""
+OPERATION=""
+
+case "$TOOL_NAME" in
+	Write)
+		FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) || FILE_PATH=""
+		CONTEXT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // ""' 2>/dev/null) || CONTEXT=""
+		OPERATION="write"
+		;;
+	Edit)
+		FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) || FILE_PATH=""
+		# Context: the old_string + new_string gives meaningful signal about what's changing.
+		_old_str=$(printf '%s' "$INPUT" | jq -r '.tool_input.old_string // ""' 2>/dev/null) || _old_str=""
+		_new_str=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // ""' 2>/dev/null) || _new_str=""
+		CONTEXT="Replacing: ${_old_str} With: ${_new_str}"
+		OPERATION="edit"
+		;;
+	MultiEdit)
+		# For MultiEdit, use the first file path and a summary as context.
+		FILE_PATH=$(printf '%s' "$INPUT" \
+			| jq -r '.tool_input.edits[0].file_path // ""' 2>/dev/null) || FILE_PATH=""
+		_edit_count=$(printf '%s' "$INPUT" \
+			| jq '.tool_input.edits | length' 2>/dev/null) || _edit_count="?"
+		_file_list=$(printf '%s' "$INPUT" \
+			| jq -r '[.tool_input.edits[].file_path] | unique | join(", ")' 2>/dev/null) \
+			|| _file_list="(multiple files)"
+		CONTEXT="MultiEdit: ${_edit_count} edit(s) across: ${_file_list}"
+		OPERATION="multi_edit"
+		;;
+	*)
+		# Unknown tool — allow through; this hook should only fire for known tools.
+		exit 0
+		;;
+esac
+
+compass_run_gate "$TOOL_NAME" "$FILE_PATH" "$OPERATION" "$CONTEXT" "$SESSION_ID" "$CWD"
+exit $?

package/plugins/compass/scripts/hooks/compass-record-write.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Compass PostToolUse hook — cooldown recorder.
+#
+# Fires after a successful Write, Edit, or MultiEdit. Records the file
+# path's dir+stem identity and a timestamp to the session state so the
+# trigger gate can skip re-checking the same file within cooldown.seconds.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks PostToolUse.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/compass-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-config.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+_done() { exit 0; }
+
+compass_config_load "$CWD"
+
+if ! compass_config_enabled; then
+	_done
+fi
+
+[[ -z "$SESSION_ID" ]] && _done
+
+# Extract the file path from the tool output.
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL_NAME=""
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""' 2>/dev/null) || FILE_PATH=""
+
+# MultiEdit: record all target paths.
+if [[ "$TOOL_NAME" == "MultiEdit" ]]; then
+	MULTI_PATHS=$(printf '%s' "$INPUT" \
+		| jq -r '.tool_input.edits[]?.file_path // empty' 2>/dev/null) || MULTI_PATHS=""
+fi
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+STATE_FILE="${ONLOOKER_DIR}/compass/sessions/${SESSION_ID}.json"
+
+[[ -f "$STATE_FILE" ]] || _done
+
+# Compute dir+stem identity for a file path.
+_dir_plus_stem() {
+	local path="$1"
+	[[ -z "$path" ]] && return 1
+	local dir base stem
+	dir=$(dirname "$path" 2>/dev/null) || dir="."
+	base=$(basename "$path" 2>/dev/null) || base="$path"
+	# Stem = everything before the first dot in the basename.
+	stem="${base%%.*}"
+	[[ -z "$stem" ]] && stem="$base"
+	printf '%s/%s' "$dir" "$stem"
+}
+
+_record_path() {
+	local path="$1"
+	[[ -z "$path" ]] && return
+
+	local identity
+	identity=$(_dir_plus_stem "$path") || return
+
+	local now
+	now=$(date +%s 2>/dev/null) || now=0
+
+	local updated
+	updated=$(jq \
+		--arg identity "$identity" \
+		--arg path "$path" \
+		--argjson ts "$now" \
+		'.cooldown = (
+			[.cooldown[] | select(.identity != $identity)]
+			+ [{"identity": $identity, "path": $path, "ts": $ts}]
+		)' "$STATE_FILE" 2>/dev/null) || return
+
+	[[ -n "$updated" ]] && printf '%s' "$updated" > "$STATE_FILE"
+}
+
+if [[ -n "$FILE_PATH" ]]; then
+	_record_path "$FILE_PATH"
+fi
+
+if [[ "$TOOL_NAME" == "MultiEdit" && -n "${MULTI_PATHS:-}" ]]; then
+	while IFS= read -r p; do
+		[[ -n "$p" ]] && _record_path "$p"
+	done <<< "$MULTI_PATHS"
+fi
+
+_done

package/plugins/compass/scripts/hooks/compass-session-start.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Compass SessionStart hook.
+#
+# Fires at every session start. Responsibilities:
+#   1. Skip silently when compass.enabled is false.
+#   2. Create storage directories.
+#   3. Initialize session state file:
+#      - turn_check_count: 0
+#      - cooldown table: empty
+#      - circuit_breaker: {state: "closed", consecutive_failures: 0}
+#
+# Hook contract:
+#   - Always exits 0. Never blocks SessionStart.
+#   - Errors are written to stderr only; stdout is kept clean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+_ECOSYSTEM_ROOT="${ONLOOKER_ECOSYSTEM_ROOT:-}"
+if [[ -z "$_ECOSYSTEM_ROOT" ]]; then
+	_candidate="$(cd "${PLUGIN_ROOT}/../.." 2>/dev/null && pwd)"
+	if [[ -f "${_candidate}/scripts/lib/validate-path.sh" ]]; then
+		_ECOSYSTEM_ROOT="$_candidate"
+	fi
+fi
+
+export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+
+# shellcheck source=../lib/compass-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-config.sh"
+# shellcheck source=../lib/compass-events.sh
+source "${PLUGIN_ROOT}/scripts/lib/compass-events.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // ""' 2>/dev/null) || SESSION_ID=""
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+
+_done() { exit 0; }
+
+compass_config_load "$CWD"
+
+if ! compass_config_enabled; then
+	_done
+fi
+
+export _HOOK_SESSION_ID="$SESSION_ID"
+
+ONLOOKER_DIR="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+COMPASS_STATE_DIR="${ONLOOKER_DIR}/compass/sessions"
+mkdir -p "$COMPASS_STATE_DIR" 2>/dev/null || true
+
+if [[ -z "$SESSION_ID" ]]; then
+	printf 'compass-session-start: no session_id in hook input\n' >&2
+	_done
+fi
+
+STATE_FILE="${COMPASS_STATE_DIR}/${SESSION_ID}.json"
+
+jq -n \
+	--arg sid "$SESSION_ID" \
+	'{
+		session_id: $sid,
+		turn_check_count: 0,
+		cooldown: [],
+		circuit_breaker: {
+			state: "closed",
+			consecutive_failures: 0,
+			opened_at: null
+		}
+	}' 2>/dev/null > "$STATE_FILE" || {
+	printf 'compass-session-start: failed to write state file %s\n' "$STATE_FILE" >&2
+	_done
+}
+
+_done

package/plugins/compass/scripts/lib/compass-config.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Config resolution for Compass.
+#
+# Reads three layers, latest wins:
+#   1. plugins/compass/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   compass_config_load <repo_root>     # populates _COMPASS_CONFIG (JSON)
+#   compass_config_get <jq-path>        # echoes string value (empty if unset)
+#   compass_config_get_json <jq-path>   # echoes JSON value (null if unset)
+#   compass_config_enabled              # 0 if compass.enabled is true
+
+_COMPASS_CONFIG="{}"
+
+compass_config_load() {
+	local repo_root="${1:-}"
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local home_dir="${HOME:-}"
+
+	local merged="{}"
+	local file
+
+	file="${plugin_root}/config.json"
+	if [[ -f "$file" ]]; then
+		local defaults
+		defaults=$(jq '.' "$file" 2>/dev/null) || defaults="{}"
+		merged=$(jq -n --argjson a "$merged" --argjson b "$defaults" '$a * $b' 2>/dev/null) \
+			|| merged="$defaults"
+	fi
+
+	local repo_settings=""
+	[[ -n "$repo_root" ]] && repo_settings="${repo_root}/.claude/settings.json"
+
+	for file in "${home_dir}/.claude/settings.json" "$repo_settings"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ compass: (.compass // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		local attempt
+		if attempt=$(jq -n --argjson a "$merged" --argjson b "$overlay" '
+			def deepmerge($a; $b):
+				if ($a|type) == "object" and ($b|type) == "object" then
+					reduce (($a|keys) + ($b|keys) | unique)[] as $k
+						({}; .[$k] = deepmerge($a[$k]; $b[$k]))
+				elif $b == null then $a
+				else $b end;
+			deepmerge($a; $b)
+		' 2>/dev/null) && [[ -n "$attempt" ]]; then
+			merged="$attempt"
+		fi
+	done
+
+	_COMPASS_CONFIG="$merged"
+}
+
+compass_config_get() {
+	local path="$1"
+	printf '%s' "$_COMPASS_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+compass_config_get_json() {
+	local path="$1"
+	printf '%s' "$_COMPASS_CONFIG" | jq -c "${path}" 2>/dev/null
+}
+
+compass_config_enabled() {
+	local v
+	v=$(compass_config_get '.compass.enabled')
+	[[ "$v" == "true" ]]
+}