@onlooker-community/ecosystem 0.20.0 → 0.22.0

package/plugins/curator/scripts/lib/curator-checks.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Cheap-tier checks for Curator.
+#
+# Pure data transforms over the memory record array produced by
+# curator-memory-reader.sh. Each function returns a JSON array of findings
+# of a single kind. Callers attach the project key and persist via
+# curator-storage.sh.
+#
+# All checks are intentionally cheap — string scans and file-exists
+# probes only. The LLM contradiction sweep lives in its own module.
+
+# Date check. Scans memory bodies for ISO-8601 dates (YYYY-MM-DD) and
+# flags any that are more than <grace_period_days> in the past, on the
+# theory that those are most likely decayed deadlines or stale "by date"
+# references the body never updated.
+#
+# Usage: curator_check_dates <memories_json> <grace_period_days>
+# Output: JSON array of date_decayed finding payload candidates.
+#         (Caller assigns finding_id and deduped_hash.)
+curator_check_dates() {
+	local memories="${1:-[]}"
+	local grace="${2:-14}"
+
+	local today
+	today=$(date -u +"%Y-%m-%d")
+
+	# Extract every YYYY-MM-DD substring per memory body via jq, then hand
+	# the candidate list to python for precise date math and grace-period
+	# filtering. Python gets the JSON as an argv (not stdin) because the
+	# heredoc-on-stdin pattern collides with piped input — see SC2259.
+	local candidates
+	candidates=$(printf '%s' "$memories" | jq -c '
+		[ .[] | select(.exists and .body != null and .body != "")
+			| .filename as $fname
+			| (.body | [scan("[0-9]{4}-[0-9]{2}-[0-9]{2}")])
+			| .[]
+			| { memory_file: $fname, matched_phrase: . }
+		]
+	')
+
+	python3 - "$today" "$grace" "$candidates" <<'PY'
+import json, sys, datetime
+
+today_str = sys.argv[1]
+grace = int(sys.argv[2])
+data = json.loads(sys.argv[3] or "[]")
+today = datetime.datetime.strptime(today_str, "%Y-%m-%d").date()
+out = []
+for entry in data:
+    try:
+        d = datetime.datetime.strptime(entry["matched_phrase"], "%Y-%m-%d").date()
+    except (ValueError, KeyError):
+        continue
+    days_past = (today - d).days
+    if days_past > grace:
+        out.append({
+            "memory_file": entry["memory_file"],
+            "matched_phrase": entry["matched_phrase"],
+            "days_past": days_past,
+        })
+print(json.dumps(out))
+PY
+}
+
+# Path reference check. For each memory, scans the body for path-shaped
+# strings ("scripts/foo.py", "src/lib/bar.ts", etc.) and emits a finding
+# when the path doesn't resolve under the given repo root.
+#
+# Path heuristic: at least one `/`, contains an extension (`.ext`), and
+# only matches the conservative character class `[A-Za-z0-9._/-]+`. A
+# negative lookbehind rejects candidates preceded by `/` or `:`, so:
+#   - URL substrings ("https://example.com/foo.py") don't match — the
+#     host segment is preceded by `:`, the path segment is preceded by `/`.
+#   - Absolute paths ("/usr/bin/python3.11") don't match — the first
+#     segment is preceded by `/`.
+# That preserves the conservative "rename detection" target (in-repo
+# relative paths like scripts/legacy_ingest.py) without the URL and
+# absolute-path false positives Copilot review caught.
+#
+# Usage: curator_check_paths <memories_json> <repo_root>
+curator_check_paths() {
+	local memories="${1:-[]}"
+	local repo_root="${2:-}"
+
+	[[ -z "$repo_root" || ! -d "$repo_root" ]] && { echo '[]'; return 0; }
+
+	local abs_root
+	abs_root=$(cd "$repo_root" 2>/dev/null && pwd -P) || { echo '[]'; return 0; }
+
+	# Extract candidate paths per memory body. The jq scan regex returns
+	# every match in the body; the negative lookbehind keeps URL and
+	# absolute-path substrings from matching at all. Deduping happens after.
+	local candidates
+	candidates=$(printf '%s' "$memories" | jq -c '
+		[ .[] | select(.exists and .body != null and .body != "")
+			| .filename as $fname
+			| (.body | [scan("(?<![A-Za-z0-9._/:-])[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)+\\.[A-Za-z0-9]+")])
+			| unique
+			| .[]
+			| { memory_file: $fname, candidate: . }
+		]
+	')
+
+	# Walk each candidate, drop ones that resolve. JSON goes via argv to
+	# avoid the SC2259 stdin clobber pattern that the date check tripped.
+	local candidates_compact
+	candidates_compact=$(printf '%s' "$candidates" | jq -c '.')
+	python3 - "$abs_root" "$candidates_compact" <<'PY'
+import json, os, sys
+
+repo_root = sys.argv[1]
+data = json.loads(sys.argv[2] or "[]")
+out = []
+for entry in data:
+    candidate = entry["candidate"]
+    abs_candidate = candidate if candidate.startswith("/") else os.path.join(repo_root, candidate)
+    if os.path.exists(abs_candidate):
+        continue
+    # Strip the repo root prefix when reporting absolute matches.
+    reported = candidate
+    if candidate.startswith(repo_root + os.sep):
+        reported = candidate[len(repo_root) + 1:]
+    out.append({
+        "memory_file": entry["memory_file"],
+        "broken_path": reported,
+    })
+print(json.dumps(out))
+PY
+}
+
+# Broken-index check: MEMORY.md references a file that doesn't exist on
+# disk. The memory reader already encodes this via the `exists: false`
+# record; this check just shapes it into a finding payload.
+#
+# Usage: curator_check_broken_index <memories_json>
+curator_check_broken_index() {
+	local memories="${1:-[]}"
+	printf '%s' "$memories" | jq -c '
+		[ .[] | select(.referenced == true and .exists == false)
+			| { referenced_file: .filename }
+		]
+	'
+}
+
+# Orphaned memory: file in the dir but not referenced from MEMORY.md.
+#
+# Usage: curator_check_orphaned <memories_json>
+curator_check_orphaned() {
+	local memories="${1:-[]}"
+	printf '%s' "$memories" | jq -c '
+		[ .[] | select(.referenced == false and .exists == true)
+			| { memory_file: .filename }
+		]
+	'
+}

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

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Config resolution for Curator.
+#
+# Reads three layers, latest wins:
+#   1. plugins/curator/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   curator_config_load <repo_root>    # populates _CURATOR_CONFIG (JSON)
+#   curator_config_get <jq-path>       # echoes string value (empty if unset)
+#   curator_config_enabled             # 0 if curator.enabled is true
+#
+# Settings overlay only touches the `curator.*` subtree of settings.json.
+
+_CURATOR_CONFIG="{}"
+
+curator_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
+
+	for file in "${home_dir}/.claude/settings.json" "${repo_root}/.claude/settings.json"; do
+		[[ -n "$file" && -f "$file" ]] || continue
+		local overlay
+		overlay=$(jq '{ curator: (.curator // {}) }' "$file" 2>/dev/null) || continue
+		[[ -z "$overlay" ]] && continue
+		merged=$(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) || true
+	done
+
+	_CURATOR_CONFIG="$merged"
+}
+
+curator_config_get() {
+	local path="$1"
+	# The `// empty` operator treats `false` the same as null, so a
+	# value of `false` would silently disappear and the caller would
+	# misread "explicitly disabled" as "default to enabled". Use an
+	# explicit null check so booleans round-trip correctly.
+	printf '%s' "$_CURATOR_CONFIG" \
+		| jq -r "${path} | if . == null then empty else . end" 2>/dev/null
+}
+
+curator_config_enabled() {
+	local v
+	v=$(curator_config_get '.curator.enabled')
+	[[ "$v" == "true" ]]
+}

package/plugins/curator/scripts/lib/curator-emit.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Event emission helpers for Curator.
+#
+# Thin wrapper around onlooker-event.mjs `emit` mode for curator.* events.
+# Fail-soft: returns 0 on success or when the substrate is unavailable.
+
+_curator_resolve_event_js() {
+	local script_dir plugin_root ecosystem_root candidate
+	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/onlooker-event.mjs" ]]; then
+			ecosystem_root="$candidate"
+		fi
+	fi
+
+	if [[ -n "$ecosystem_root" ]]; then
+		printf '%s/scripts/lib/onlooker-event.mjs' "$ecosystem_root"
+	fi
+}
+
+_CURATOR_EVENT_JS="${_CURATOR_EVENT_JS:-$(_curator_resolve_event_js)}"
+
+# Emit a curator.* event. Fail-soft: returns 0 on any error.
+# Usage: curator_emit <event_type> <session_id> <payload_json>
+curator_emit() {
+	local event_type="${1:-}"
+	local session_id="${2:-}"
+	local payload="${3:-{\}}"
+
+	[[ -z "$event_type" || -z "$session_id" ]] && return 0
+	[[ -z "$_CURATOR_EVENT_JS" || ! -f "$_CURATOR_EVENT_JS" ]] && return 0
+	command -v node >/dev/null 2>&1 || return 0
+	[[ -z "${ONLOOKER_EVENTS_LOG:-}" ]] && return 0
+
+	local params event_json
+	params=$(jq -cn \
+		--arg plugin "curator" \
+		--arg session_id "$session_id" \
+		--arg event_type "$event_type" \
+		--argjson payload "$payload" \
+		'{
+			plugin: $plugin,
+			session_id: $session_id,
+			event_type: $event_type,
+			payload: $payload
+		}') || return 0
+
+	event_json=$(
+		ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		ONLOOKER_PLUGIN_NAME="curator" \
+		printf '%s' "$params" | node "$_CURATOR_EVENT_JS" emit 2>/dev/null
+	) || return 0
+	[[ -z "$event_json" ]] && return 0
+
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")" 2>/dev/null
+	printf '%s\n' "$event_json" >> "$ONLOOKER_EVENTS_LOG" 2>/dev/null
+}

package/plugins/curator/scripts/lib/curator-memory-reader.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# Memory store reader for Curator.
+#
+# Parses ~/.claude/projects/<encoded-project>/memory/MEMORY.md and the
+# referenced *.md files. Returns a JSON array of memory records:
+#
+#   [
+#     {
+#       "filename": "feedback_no_trailing_summaries.md",
+#       "title": "...",                       # from frontmatter `name` or MEMORY.md link
+#       "type": "feedback",                   # from frontmatter `type`
+#       "body": "...",                        # everything after the frontmatter
+#       "exists": true,                       # false when MEMORY.md points at a missing file
+#       "frontmatter_parsed": true|false
+#     },
+#     ...
+#   ]
+#
+# Orphans (files present in the memory dir but not referenced from MEMORY.md)
+# get their own record with `referenced: false`. Broken index entries
+# (referenced by MEMORY.md but missing on disk) get `exists: false`.
+
+# Returns 0 iff the given filename contains a path separator, parent-dir
+# escape, leading dot, null byte, or other shape that should never get
+# joined onto the memory dir. Used to defang MEMORY.md entries before we
+# interpolate them into a filesystem path.
+_curator_memory_unsafe_filename() {
+	local fname="$1"
+	[[ -z "$fname" ]] && return 0
+	case "$fname" in
+		# Absolute paths, traversal, separators, dotfiles, control chars.
+		/*|*/*|*\\*|*..*|.*|*$'\n'*|*$'\r'*) return 0 ;;
+	esac
+	# Must end in .md and look like a plain filename.
+	[[ "$fname" == *.md ]] || return 0
+	[[ "$fname" =~ ^[A-Za-z0-9._-]+\.md$ ]] || return 0
+	return 1
+}
+
+# Resolve the memory store path. The runtime resolves
+# $CLAUDE_PROJECT_ENCODED — when unset, the caller provides it explicitly.
+#
+# Usage: curator_memory_resolve_path <memory_store_path_template>
+# Returns the resolved absolute path, or empty if it can't be resolved.
+curator_memory_resolve_path() {
+	local template="$1"
+	[[ -z "$template" ]] && return 0
+	local encoded="${CLAUDE_PROJECT_ENCODED:-}"
+	# Best-effort interpolation. The template may contain ${HOME} and
+	# ${CLAUDE_PROJECT_ENCODED}.
+	local resolved
+	resolved="${template//\$\{HOME\}/${HOME:-}}"
+	resolved="${resolved//\$\{CLAUDE_PROJECT_ENCODED\}/${encoded}}"
+	# If the encoded var is missing, the path still contains the literal
+	# placeholder; caller treats empty as "skip the audit".
+	if [[ "$resolved" == *'${CLAUDE_PROJECT_ENCODED}'* ]]; then
+		return 0
+	fi
+	printf '%s' "$resolved"
+}
+
+# Parse a single memory file. Returns a JSON object on stdout.
+# Usage: curator_memory_parse_file <abs_path> <referenced_bool>
+curator_memory_parse_file() {
+	local path="$1"
+	local referenced="${2:-true}"
+	[[ -z "$path" ]] && return 0
+
+	local filename
+	filename="$(basename "$path")"
+
+	if [[ ! -f "$path" ]]; then
+		jq -cn \
+			--arg filename "$filename" \
+			--argjson referenced "$referenced" \
+			'{
+				filename: $filename,
+				title: null, type: null, body: "",
+				exists: false, referenced: $referenced,
+				frontmatter_parsed: false
+			}'
+		return 0
+	fi
+
+	local raw
+	raw=$(cat "$path" 2>/dev/null || true)
+	[[ -z "$raw" ]] && raw=""
+
+	local has_fm name desc type body fm_parsed="false"
+	if [[ "$raw" == "---"* ]]; then
+		# YAML frontmatter present. Extract simple `key: value` lines until
+		# the closing `---`. Fancier YAML (nested, lists) isn't expected in
+		# the auto-memory format.
+		local fm_block
+		fm_block=$(printf '%s' "$raw" | awk '
+			NR == 1 && /^---/ { in_fm = 1; next }
+			in_fm && /^---/ { in_fm = 0; exit }
+			in_fm { print }
+		')
+		name=$(printf '%s' "$fm_block" | sed -nE 's/^name:[[:space:]]*(.*)$/\1/p' | head -1)
+		desc=$(printf '%s' "$fm_block" | sed -nE 's/^description:[[:space:]]*(.*)$/\1/p' | head -1)
+		type=$(printf '%s' "$fm_block" | sed -nE 's/^type:[[:space:]]*(.*)$/\1/p' | head -1)
+		body=$(printf '%s' "$raw" | awk '
+			BEGIN { in_fm = 0; seen_close = 0 }
+			NR == 1 && /^---/ { in_fm = 1; next }
+			in_fm && /^---/ { in_fm = 0; seen_close = 1; next }
+			seen_close { print }
+		')
+		fm_parsed="true"
+		has_fm="true"
+	else
+		# No frontmatter — treat the whole body as content; type unknown.
+		name=""
+		desc=""
+		type=""
+		body="$raw"
+		fm_parsed="false"
+		has_fm="false"
+	fi
+
+	jq -cn \
+		--arg filename "$filename" \
+		--arg name "$name" \
+		--arg desc "$desc" \
+		--arg type "$type" \
+		--arg body "$body" \
+		--argjson referenced "$referenced" \
+		--argjson fm_parsed "$fm_parsed" \
+		'{
+			filename: $filename,
+			title: (if $name == "" then null else $name end),
+			description: (if $desc == "" then null else $desc end),
+			type: (if $type == "" then null else $type end),
+			body: $body,
+			exists: true,
+			referenced: $referenced,
+			frontmatter_parsed: $fm_parsed
+		}'
+}
+
+# Load every memory file referenced by MEMORY.md plus every file in the dir.
+# Output: JSON array of memory records (as defined at the top of this file).
+#
+# Usage: curator_memory_load_all <memory_dir_abs>
+curator_memory_load_all() {
+	local mem_dir="$1"
+	[[ -z "$mem_dir" || ! -d "$mem_dir" ]] && { echo '[]'; return 0; }
+
+	# 1. Parse MEMORY.md for referenced filenames.
+	local index_path="${mem_dir}/MEMORY.md"
+	local referenced_list=()
+	if [[ -f "$index_path" ]]; then
+		# Match the standard line format: `- [Title](file.md) — hook`
+		while IFS= read -r line; do
+			referenced_list+=("$line")
+		done < <(grep -oE '\[[^]]+\]\([^)]+\)' "$index_path" 2>/dev/null \
+			| sed -E 's/.*\(([^)]+)\)/\1/' | awk '{ print }')
+	fi
+
+	# 2. Build the canonical set of referenced filenames.
+	local referenced_json='[]'
+	if [[ ${#referenced_list[@]} -gt 0 ]]; then
+		referenced_json=$(printf '%s\n' "${referenced_list[@]}" | jq -R . | jq -s .)
+	fi
+
+	# 3. Visit each referenced filename (broken or not) plus every *.md
+	#    on disk that wasn't referenced.
+	local all='[]'
+	local fname rec
+	local seen_json='{}'
+
+	# Referenced first — preserves MEMORY.md ordering for downstream display.
+	# Filename sanitization: anything with a path separator, parent-dir
+	# escape, leading dot, or non-printable bytes is recorded as a broken
+	# index entry and NEVER passed to the parser. Without this guard a
+	# MEMORY.md entry like `[X](../../etc/passwd)` would read outside the
+	# memory dir.
+	local refcount
+	refcount=$(printf '%s' "$referenced_json" | jq 'length')
+	local i
+	for ((i = 0; i < refcount; i++)); do
+		fname=$(printf '%s' "$referenced_json" | jq -r ".[$i]")
+		[[ -z "$fname" || "$fname" == "null" ]] && continue
+		# Skip MEMORY.md itself if it self-references.
+		[[ "$fname" == "MEMORY.md" ]] && continue
+
+		if _curator_memory_unsafe_filename "$fname"; then
+			# Record as a broken/unsafe index entry so the broken_index
+			# check surfaces it. The parser is bypassed, so no read
+			# happens outside the memory dir.
+			rec=$(jq -cn \
+				--arg filename "$fname" \
+				'{
+					filename: $filename,
+					title: null, description: null, type: null, body: "",
+					exists: false, referenced: true,
+					frontmatter_parsed: false, unsafe: true
+				}')
+			all=$(printf '%s' "$all" | jq --argjson rec "$rec" '. + [$rec]')
+			seen_json=$(printf '%s' "$seen_json" | jq --arg f "$fname" '. + {($f): true}')
+			continue
+		fi
+
+		rec=$(curator_memory_parse_file "${mem_dir}/${fname}" true)
+		[[ -z "$rec" ]] && continue
+		all=$(printf '%s' "$all" | jq --argjson rec "$rec" '. + [$rec]')
+		seen_json=$(printf '%s' "$seen_json" | jq --arg f "$fname" '. + {($f): true}')
+	done
+
+	# Then any orphans (files on disk not referenced from MEMORY.md).
+	local file
+	for file in "$mem_dir"/*.md; do
+		[[ -f "$file" ]] || continue
+		fname="$(basename "$file")"
+		[[ "$fname" == "MEMORY.md" ]] && continue
+		local already_seen
+		already_seen=$(printf '%s' "$seen_json" | jq -r --arg f "$fname" '.[$f] // false')
+		[[ "$already_seen" == "true" ]] && continue
+		rec=$(curator_memory_parse_file "$file" false)
+		[[ -z "$rec" ]] && continue
+		all=$(printf '%s' "$all" | jq --argjson rec "$rec" '. + [$rec]')
+	done
+
+	printf '%s' "$all"
+}

package/plugins/curator/scripts/lib/curator-project-key.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Project key derivation for Curator.
+#
+# Curator stores findings under the ecosystem-wide 12-char hex project key so
+# state survives clone path changes and is shared across worktrees / clones of
+# the same repo. (The typed memory store Curator audits lives at a different
+# path keyed by the Claude Code per-checkout encoding; that path is resolved
+# separately by curator-memory-reader.sh.)
+#
+# Resolution order:
+#   1. SHA256(`git remote get-url origin`) — preferred, machine-portable
+#   2. SHA256(realpath of `git rev-parse --show-toplevel`) — fallback for
+#      repos without an origin remote
+#
+# Returns the first 12 hex chars. Empty when not in a git repo at all.
+
+_curator_sha256_first12() {
+	local input="$1"
+	if command -v shasum >/dev/null 2>&1; then
+		printf '%s' "$input" | shasum -a 256 2>/dev/null | cut -c1-12
+	elif command -v sha256sum >/dev/null 2>&1; then
+		printf '%s' "$input" | sha256sum 2>/dev/null | cut -c1-12
+	else
+		return 1
+	fi
+}
+
+curator_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+curator_project_repo_root() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+
+	if ! git -C "$cwd" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		return 0
+	fi
+
+	local common_dir toplevel
+	common_dir=$(git -C "$cwd" rev-parse --git-common-dir 2>/dev/null) || return 0
+
+	if [[ -n "$common_dir" && "$common_dir" != /* ]]; then
+		common_dir="$(cd "$cwd" && cd "$common_dir" 2>/dev/null && pwd -P)" || common_dir=""
+	fi
+
+	if [[ -n "$common_dir" && -d "$common_dir" ]]; then
+		toplevel="$(cd "$common_dir/.." 2>/dev/null && pwd -P)" || toplevel=""
+	fi
+
+	if [[ -z "$toplevel" ]]; then
+		toplevel=$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || true)
+		[[ -n "$toplevel" ]] && toplevel="$(cd "$toplevel" 2>/dev/null && pwd -P)"
+	fi
+
+	printf '%s' "$toplevel"
+}
+
+# Compute the project key for the given cwd. Prints the key or empty.
+# Usage: key=$(curator_project_key "$CWD")
+curator_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(curator_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_curator_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(curator_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_curator_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}