@onlooker-community/ecosystem 0.16.0 → 0.17.0

package/plugins/scribe/scripts/lib/scribe-events.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Canonical scribe.* event emission.
+#
+# Thin wrapper around the ecosystem plugin's onlooker-event.mjs `emit` mode.
+# Every emission is validated against @onlooker-community/schema before being
+# appended to $ONLOOKER_EVENTS_LOG (defaults to $ONLOOKER_DIR/logs/onlooker-events.jsonl).
+#
+# Usage:
+#   scribe_emit_event "scribe.distill.complete" '{"session_id":"...","captures_processed":1,...}'
+
+_SCRIBE_PLUGIN_NAME="scribe"
+
+_scribe_event_js_path() {
+	if [[ -n "${_ONLOOKER_EVENT_JS:-}" && -f "$_ONLOOKER_EVENT_JS" ]]; then
+		printf '%s' "$_ONLOOKER_EVENT_JS"
+		return 0
+	fi
+	local plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+	local candidates=(
+		"${plugin_root}/scripts/lib/onlooker-event.mjs"
+		"${plugin_root}/../../scripts/lib/onlooker-event.mjs"
+	)
+	local c
+	for c in "${candidates[@]}"; do
+		[[ -f "$c" ]] && { printf '%s' "$c"; return 0; }
+	done
+	return 1
+}
+
+_scribe_session_id() {
+	if [[ -n "${_HOOK_SESSION_ID:-}" ]]; then
+		printf '%s' "$_HOOK_SESSION_ID"
+		return 0
+	fi
+	if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+		printf '%s' "$CLAUDE_SESSION_ID"
+		return 0
+	fi
+	printf 'unknown'
+}
+
+scribe_emit_event() {
+	local event_type="${1:-}"
+	local payload="${2:-}"
+
+	[[ -z "$event_type" || -z "$payload" ]] && return 1
+
+	local event_js
+	event_js=$(_scribe_event_js_path) || return 1
+
+	local session_id
+	session_id=$(_scribe_session_id)
+
+	local params
+	params=$(jq -n \
+		--arg plugin "$_SCRIBE_PLUGIN_NAME" \
+		--arg sid "$session_id" \
+		--arg type "$event_type" \
+		--argjson payload "$payload" \
+		'{plugin: $plugin, session_id: $sid, event_type: $type, payload: $payload}' \
+		2>/dev/null) || return 1
+
+	local event
+	local stderr_file
+	stderr_file=$(mktemp -t scribe-event-err.XXXXXX 2>/dev/null) || stderr_file="/tmp/scribe-event-err.$$"
+	event=$(printf '%s' "$params" \
+		| ONLOOKER_DIR="${ONLOOKER_DIR:-$HOME/.onlooker}" \
+		  ONLOOKER_PLUGIN_NAME="$_SCRIBE_PLUGIN_NAME" \
+		  node "$event_js" emit 2>"$stderr_file") || {
+		printf 'scribe_emit_event: schema validation failed for %s\n' "$event_type" >&2
+		[[ -s "$stderr_file" ]] && cat "$stderr_file" >&2
+		rm -f "$stderr_file"
+		return 1
+	}
+	rm -f "$stderr_file"
+
+	local log_path="${ONLOOKER_EVENTS_LOG:-${ONLOOKER_DIR:-$HOME/.onlooker}/logs/onlooker-events.jsonl}"
+	mkdir -p "$(dirname "$log_path")" 2>/dev/null || return 1
+	printf '%s\n' "$event" >> "$log_path"
+}

package/plugins/scribe/scripts/lib/scribe-extract.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Intent extraction for Scribe.
+#
+# Reads a session transcript and runs a Haiku pass to extract structured
+# intent documentation: the problem being solved, decisions made and why,
+# tradeoffs, constraints, and what was explicitly left out.
+#
+# This is documentation from intent, not from code. The output answers
+# WHY, not WHAT — git logs and code comments cover what.
+#
+# Exposes:
+#   scribe_count_turns <transcript_path>
+#     Echoes the number of user turns found in the transcript (integer).
+#
+#   scribe_extract_intent <transcript_path> <model> <timeout> <max_tokens> <temperature>
+#     Echoes a JSON object on success, empty string on failure.
+#     JSON shape:
+#       {
+#         "problem":      string,
+#         "decisions":    [{decision, reason, alternatives:[]}],
+#         "tradeoffs":    [string],
+#         "constraints":  [string],
+#         "out_of_scope": [string],
+#         "summary":      string
+#       }
+
+_SCRIBE_EXTRACT_PROMPT='You are an intent documentation assistant. Analyze this agent session transcript and extract structured documentation about WHY changes were made — the problem context, decisions, tradeoffs, and constraints that shaped the work. This is documentation from intent, not from code.
+
+Do NOT describe what was done. Focus exclusively on why decisions were made.
+
+Return a JSON object with exactly these keys:
+{
+  "problem": "1-3 sentences: what problem or goal initiated this session",
+  "decisions": [
+    {
+      "decision": "what was decided",
+      "reason": "why this approach was chosen",
+      "alternatives": ["alternative that was considered but rejected"]
+    }
+  ],
+  "tradeoffs": ["tradeoff description — what was gained vs. given up"],
+  "constraints": ["constraint that shaped decisions"],
+  "out_of_scope": ["what was explicitly not done, and why"],
+  "summary": "2-3 sentences: executive summary of the session intent and key decisions"
+}
+
+Rules:
+- All fields are required; use empty arrays [] if no items found
+- Keep each item to 1-2 sentences
+- Return ONLY the JSON object — no prose, no markdown fences, no explanation
+
+'
+
+scribe_count_turns() {
+	local transcript_path="${1:-}"
+	[[ -f "$transcript_path" ]] || { printf '0'; return 0; }
+
+	local count=0
+	local line
+	while IFS= read -r line; do
+		[[ -z "$line" ]] && continue
+		local role
+		role=$(printf '%s' "$line" | jq -r '.role // empty' 2>/dev/null) || continue
+		[[ "$role" == "user" ]] && count=$((count + 1))
+	done < "$transcript_path"
+
+	printf '%s' "$count"
+}
+
+scribe_extract_intent() {
+	local transcript_path="${1:-}"
+	local model="${2:-claude-haiku-4-5-20251001}"
+	local timeout_s="${3:-60}"
+	local max_tokens="${4:-2048}"
+	local temperature="${5:-0.3}"
+	local transcript_chars_max="${6:-40000}"
+
+	[[ -f "$transcript_path" ]] || return 1
+
+	local transcript_content
+	transcript_content=$(jq -r '
+		select(.role != null) |
+		if .role == "user" then
+			"[User]\n" + (
+				if (.content | type) == "array" then
+					[.content[] | select(.type == "text") | .text] | join("\n")
+				else
+					(.content // "")
+				end
+			)
+		elif .role == "assistant" then
+			"[Assistant]\n" + (
+				if (.content | type) == "array" then
+					[.content[] | select(.type == "text") | .text] | join("\n")
+				else
+					(.content // "")
+				end
+			)
+		else empty end
+	' "$transcript_path" 2>/dev/null | head -c "$transcript_chars_max") || transcript_content=""
+
+	[[ -z "$transcript_content" ]] && return 1
+
+	local prompt_file
+	prompt_file=$(mktemp -t scribe-extract.XXXXXX 2>/dev/null) || prompt_file="/tmp/scribe-extract.$$"
+	trap 'rm -f "$prompt_file"' RETURN
+
+	{
+		printf '%s' "$_SCRIBE_EXTRACT_PROMPT"
+		printf '<session_transcript>\n'
+		printf '%s\n' "$transcript_content"
+		printf '</session_transcript>\n'
+	} > "$prompt_file"
+
+	if ! command -v claude >/dev/null 2>&1; then
+		printf 'scribe_extract_intent: claude CLI not found\n' >&2
+		return 1
+	fi
+
+	local claude_args=(-p --max-turns 1 --model "$model" --max-tokens "$max_tokens")
+
+	local response=""
+	if command -v timeout >/dev/null 2>&1; then
+		response=$(timeout "$timeout_s" claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		response=$(gtimeout "$timeout_s" claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	else
+		response=$(claude "${claude_args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	fi
+
+	[[ -z "$response" ]] && return 1
+
+	# Strip markdown fences if present.
+	local clean
+	clean=$(printf '%s' "$response" \
+		| sed -e 's/^```json[[:space:]]*//' -e 's/^```[[:space:]]*//' -e 's/[[:space:]]*```$//')
+
+	# Validate all required keys from the extraction prompt.
+	if ! printf '%s' "$clean" | jq -e \
+		'.problem and (.decisions | type == "array") and (.tradeoffs | type == "array") and (.constraints | type == "array") and (.out_of_scope | type == "array") and .summary' \
+		>/dev/null 2>&1; then
+		printf 'scribe_extract_intent: response missing required keys\n' >&2
+		return 1
+	fi
+
+	printf '%s' "$clean"
+}

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

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# Project key derivation for Scribe.
+#
+# Mirrors the tribunal project-key scheme so plugins partition storage
+# identically. A project key is a stable 12-char hex identifier that survives:
+#   - local rename of the repo directory
+#   - cloning the same repo to a different path on the same machine
+#   - moving the repo between machines (as long as the git remote is preserved)
+#   - worktrees (a worktree shares its parent repo's key)
+#
+# 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. Returns empty string if neither path works.
+
+_scribe_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
+}
+
+scribe_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+# Worktree-aware: uses common-dir so worktrees share a key with the main repo.
+scribe_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"
+}
+
+scribe_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(scribe_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_scribe_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(scribe_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_scribe_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}
+
+scribe_project_dir() {
+	local project_key="${1:-}"
+	[[ -z "$project_key" ]] && return 1
+	local onlooker_dir="${ONLOOKER_DIR:-${HOME}/.onlooker}"
+	printf '%s' "${onlooker_dir}/scribe/${project_key}"
+}

package/plugins/scribe/scripts/lib/scribe-ulid.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Minimal ULID generator for Scribe document and event IDs.
+#
+# Spec: https://github.com/ulid/spec
+#   - 48-bit timestamp (ms since epoch) → 10 chars Crockford Base32
+#   - 80-bit randomness → 16 chars Crockford Base32
+#   - lexicographically sortable, time-ordered
+
+_SCRIBE_ULID_ALPHABET="0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+_scribe_ulid_encode() {
+	local n="$1"
+	local len="$2"
+	local out=""
+	local i
+	for ((i = 0; i < len; i++)); do
+		out="${_SCRIBE_ULID_ALPHABET:$((n % 32)):1}${out}"
+		n=$((n / 32))
+	done
+	printf '%s' "$out"
+}
+
+scribe_ulid() {
+	local now_ms
+	if [[ "$(uname)" == "Darwin" ]]; then
+		now_ms=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null) \
+			|| now_ms=$(($(date +%s) * 1000))
+	else
+		now_ms=$(date +%s%3N 2>/dev/null) || now_ms=$(($(date +%s) * 1000))
+	fi
+
+	local rand_hex rand_hi rand_lo
+	rand_hex=$(openssl rand -hex 10 2>/dev/null)
+	if [[ -n "$rand_hex" && ${#rand_hex} -eq 20 ]]; then
+		rand_hi=$((16#${rand_hex:0:10}))
+		rand_lo=$((16#${rand_hex:10:10}))
+	else
+		rand_hi=$((RANDOM * 32768 + RANDOM))
+		rand_lo=$((RANDOM * 32768 + RANDOM))
+		rand_hi=$(((rand_hi * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+		rand_lo=$(((rand_lo * 256 + RANDOM % 256) & ((1 << 40) - 1)))
+	fi
+
+	local ts_part hi_part lo_part
+	ts_part=$(_scribe_ulid_encode "$now_ms" 10)
+	hi_part=$(_scribe_ulid_encode "$rand_hi" 8)
+	lo_part=$(_scribe_ulid_encode "$rand_lo" 8)
+
+	printf '%s%s%s' "$ts_part" "$hi_part" "$lo_part"
+}

package/release-please-config.json

@@ -94,6 +94,38 @@
           "jsonpath": "$.version"
         }
       ]
+    },
+    "plugins/compass": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "compass",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
+    "plugins/scribe": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "simple",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "component": "scribe",
+      "draft": false,
+      "prerelease": false,
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
     }
   },
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"

package/test/bats/scribe-extract.bats

@@ -0,0 +1,102 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/scribe"
+  export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-config.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-extract.sh"
+}
+
+# ---------------------------------------------------------------------------
+# scribe_count_turns
+# ---------------------------------------------------------------------------
+
+@test "count_turns returns 0 for missing file" {
+  run scribe_count_turns "/nonexistent/path.jsonl"
+  [ "$status" -eq 0 ]
+  [ "$output" = "0" ]
+}
+
+@test "count_turns returns 0 for empty file" {
+  local f="${BATS_TEST_TMPDIR}/empty.jsonl"
+  touch "$f"
+  run scribe_count_turns "$f"
+  [ "$status" -eq 0 ]
+  [ "$output" = "0" ]
+}
+
+@test "count_turns counts only user-role entries" {
+  local f="${BATS_TEST_TMPDIR}/transcript.jsonl"
+  printf '%s\n' \
+    '{"role":"user","content":"hello"}' \
+    '{"role":"assistant","content":"hi"}' \
+    '{"role":"user","content":"thanks"}' \
+    '{"role":"assistant","content":"sure"}' \
+    > "$f"
+  run scribe_count_turns "$f"
+  [ "$status" -eq 0 ]
+  [ "$output" = "2" ]
+}
+
+@test "count_turns skips blank lines" {
+  local f="${BATS_TEST_TMPDIR}/sparse.jsonl"
+  printf '%s\n' \
+    '{"role":"user","content":"a"}' \
+    '' \
+    '{"role":"user","content":"b"}' \
+    > "$f"
+  run scribe_count_turns "$f"
+  [ "$status" -eq 0 ]
+  [ "$output" = "2" ]
+}
+
+# ---------------------------------------------------------------------------
+# min_turns gate (via scribe_distill return code)
+# ---------------------------------------------------------------------------
+
+@test "scribe_distill exits 2 when transcript has fewer turns than min_turns" {
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-events.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-project-key.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-distill.sh"
+
+  # Load config so min_turns is available (default: 3).
+  scribe_config_load ""
+
+  # Transcript with only 1 user turn — below default min_turns of 3.
+  local f="${BATS_TEST_TMPDIR}/short.jsonl"
+  printf '%s\n' \
+    '{"role":"user","content":"hey"}' \
+    '{"role":"assistant","content":"yo"}' \
+    > "$f"
+
+  run scribe_distill "test-session-id" "${BATS_TEST_TMPDIR}" "$f"
+  [ "$status" -eq 2 ]
+}
+
+@test "scribe_distill min_turns skip produces no stderr output" {
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-events.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-project-key.sh"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-distill.sh"
+
+  scribe_config_load ""
+
+  local f="${BATS_TEST_TMPDIR}/short2.jsonl"
+  printf '%s\n' '{"role":"user","content":"hi"}' > "$f"
+
+  # Run in a subshell capturing stderr separately.
+  local stderr_out
+  stderr_out=$(scribe_distill "test-sid" "${BATS_TEST_TMPDIR}" "$f" 2>&1 >/dev/null) || true
+  [ -z "$stderr_out" ]
+}

package/test/bats/scribe-project-key.bats

@@ -0,0 +1,75 @@
+#!/usr/bin/env bats
+
+setup() {
+  # shellcheck source=../helpers/setup.bash
+  source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+  setup_test_env
+
+  PLUGIN_ROOT="${REPO_ROOT}/plugins/scribe"
+  # shellcheck disable=SC1091
+  source "${PLUGIN_ROOT}/scripts/lib/scribe-project-key.sh"
+}
+
+@test "non-git directory returns empty key" {
+  local d="${BATS_TEST_TMPDIR}/non-git"
+  mkdir -p "$d"
+  run scribe_project_key "$d"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "git repo without remote falls back to repo-root hash" {
+  local d="${BATS_TEST_TMPDIR}/local-only-repo"
+  mkdir -p "$d"
+  git -C "$d" init -q
+  git -C "$d" config user.email t@example.com
+  git -C "$d" config user.name "Test"
+
+  local k1
+  k1=$(scribe_project_key "$d")
+  [ -n "$k1" ]
+  [ "${#k1}" -eq 12 ]
+
+  # Stability: a second call returns the same key.
+  local k2
+  k2=$(scribe_project_key "$d")
+  [ "$k1" = "$k2" ]
+}
+
+@test "git repo with remote uses remote hash, ignores local path" {
+  local a="${BATS_TEST_TMPDIR}/clone-a"
+  local b="${BATS_TEST_TMPDIR}/clone-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+    git -C "$d" remote add origin git@github.com:org/proj.git
+  done
+
+  local ka kb
+  ka=$(scribe_project_key "$a")
+  kb=$(scribe_project_key "$b")
+  [ -n "$ka" ]
+  [ "$ka" = "$kb" ]
+}
+
+@test "different remotes yield different keys" {
+  local a="${BATS_TEST_TMPDIR}/proj-a"
+  local b="${BATS_TEST_TMPDIR}/proj-b"
+  mkdir -p "$a" "$b"
+  for d in "$a" "$b"; do
+    git -C "$d" init -q
+    git -C "$d" config user.email t@example.com
+    git -C "$d" config user.name "Test"
+  done
+  git -C "$a" remote add origin git@github.com:org/proj-a.git
+  git -C "$b" remote add origin git@github.com:org/proj-b.git
+
+  local ka kb
+  ka=$(scribe_project_key "$a")
+  kb=$(scribe_project_key "$b")
+  [ -n "$ka" ]
+  [ -n "$kb" ]
+  [ "$ka" != "$kb" ]
+}