@onlooker-community/ecosystem 0.26.1 → 0.27.0

package/test/bats/bursar-events.bats

@@ -0,0 +1,73 @@
+#!/usr/bin/env bats
+
+# Validates that bursar.* events pass @onlooker-community/schema validation.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	export CLAUDE_PLUGIN_ROOT="$PLUGIN_ROOT"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-events.sh"
+
+	export CLAUDE_SESSION_ID="bats-bursar-session-$$"
+	PK="proj0123abcd"
+	SID="bats-bursar-sid-000"
+}
+
+_validate_latest_event() {
+	local last
+	last=$(tail -n 1 "$ONLOOKER_EVENTS_LOG")
+	[ -n "$last" ] || return 1
+	printf '%s' "$last" | ONLOOKER_DIR="$ONLOOKER_DIR" \
+		node "${REPO_ROOT}/scripts/lib/onlooker-event.mjs" validate >/dev/null
+}
+
+@test "bursar.session.recorded with governor present validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, governor_present:true,
+		  cost_usd:0.42, tokens:42000, api_calls:12, model:"claude-opus-4-8"}')
+	bursar_emit_event "bursar.session.recorded" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar.session.recorded with governor absent validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" --arg sid "$SID" \
+		'{project_key:$pk, session_id:$sid, governor_present:false}')
+	bursar_emit_event "bursar.session.recorded" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar.rollup.surfaced validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" \
+		'{project_key:$pk, window:"rolling_7d", total_cost_usd:3.17,
+		  session_count:8, total_tokens:310000, sessions_with_cost:7,
+		  window_start:"2026-06-05T00:00:00Z"}')
+	bursar_emit_event "bursar.rollup.surfaced" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar.rollup.skipped validates" {
+	local p
+	p=$(jq -n --arg pk "$PK" '{reason:"no_data", project_key:$pk}')
+	bursar_emit_event "bursar.rollup.skipped" "$p" "$SID"
+	run _validate_latest_event
+	[ "$status" -eq 0 ]
+}
+
+@test "bursar_emit_event returns nonzero for an unknown event type" {
+	run bursar_emit_event "bursar.no_such_event" '{"project_key":"x"}' "$SID"
+	[ "$status" -ne 0 ]
+}

package/test/bats/bursar-ledger.bats

@@ -0,0 +1,116 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/portable-lock.sh"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-ledger.sh"
+
+	KEY="proj0123abcd"
+}
+
+_record() {
+	# _record <session_id> <cost-or-empty> <tokens-or-empty> <ts_epoch>
+	local sid="$1" cost="$2" tokens="$3" ts="$4"
+	local rec
+	rec=$(jq -n --arg sid "$sid" --arg pk "$KEY" --argjson te "$ts" \
+		'{ts:"x", ts_epoch:$te, session_id:$sid, project_key:$pk, governor_present:true}')
+	[ -n "$cost" ] && rec=$(printf '%s' "$rec" | jq --argjson v "$cost" '. + {cost_usd:$v}')
+	[ -n "$tokens" ] && rec=$(printf '%s' "$rec" | jq --argjson v "$tokens" '. + {tokens:$v}')
+	printf '%s' "$rec"
+}
+
+@test "recording a session creates a single ledger line" {
+	local now
+	now=$(date +%s)
+	bursar_ledger_record "$KEY" "$(_record s1 1.0 100 "$now")"
+	local path
+	path=$(bursar_ledger_path "$KEY")
+	[ -f "$path" ]
+	[ "$(wc -l < "$path")" -eq 1 ]
+}
+
+@test "re-recording the same session upserts in place (idempotent)" {
+	local now
+	now=$(date +%s)
+	bursar_ledger_record "$KEY" "$(_record s1 1.0 100 "$now")"
+	bursar_ledger_record "$KEY" "$(_record s1 2.5 200 "$now")"
+	local path
+	path=$(bursar_ledger_path "$KEY")
+	[ "$(wc -l < "$path")" -eq 1 ]
+	[ "$(jq -r '.cost_usd' "$path")" = "2.5" ]
+}
+
+@test "different sessions append distinct lines" {
+	local now
+	now=$(date +%s)
+	bursar_ledger_record "$KEY" "$(_record s1 1.0 100 "$now")"
+	bursar_ledger_record "$KEY" "$(_record s2 2.0 200 "$now")"
+	[ "$(wc -l < "$(bursar_ledger_path "$KEY")")" -eq 2 ]
+}
+
+@test "rolling_7d cutoff is roughly now minus seven days" {
+	local now cutoff diff
+	now=$(date +%s)
+	cutoff=$(bursar_window_cutoff_epoch "rolling_7d" "monday")
+	diff=$(( now - cutoff ))
+	# 7 days = 604800s; allow a couple of seconds of clock drift across calls.
+	[ "$diff" -ge 604798 ]
+	[ "$diff" -le 604803 ]
+}
+
+@test "calendar_week cutoff is at or before now and not in the future" {
+	local now cutoff
+	now=$(date +%s)
+	cutoff=$(bursar_window_cutoff_epoch "calendar_week" "monday")
+	[ "$cutoff" -le "$now" ]
+	# Never more than a full week back.
+	[ "$(( now - cutoff ))" -le 604800 ]
+}
+
+@test "window totals sum cost and tokens, count sessions, and track cost coverage" {
+	local now in1 in2 out
+	now=$(date +%s)
+	in1=$(( now - 100 ))
+	in2=$(( now - 200 ))
+	out=$(( now - 700000 ))   # older than 7 days
+
+	local dir
+	dir=$(bursar_ledger_dir "$KEY")
+	mkdir -p "$dir"
+	{
+		_record withcost 1.0 100 "$in1"
+		printf '\n'
+		# governor absent: no cost_usd, no tokens
+		jq -nc --arg pk "$KEY" --argjson te "$in2" \
+			'{ts:"x", ts_epoch:$te, session_id:"nocost", project_key:$pk, governor_present:false}'
+		_record stale 50.0 9999 "$out"
+		printf '\n'
+	} > "${dir}/sessions.jsonl"
+
+	local cutoff totals
+	cutoff=$(bursar_window_cutoff_epoch "rolling_7d" "monday")
+	totals=$(bursar_window_totals "$KEY" "$cutoff")
+
+	[ "$(printf '%s' "$totals" | jq -r '.total_cost_usd')" = "1" ]
+	[ "$(printf '%s' "$totals" | jq -r '.total_tokens')" = "100" ]
+	[ "$(printf '%s' "$totals" | jq -r '.session_count')" = "2" ]
+	[ "$(printf '%s' "$totals" | jq -r '.sessions_with_cost')" = "1" ]
+}
+
+@test "window totals are zero when no ledger exists" {
+	local totals
+	totals=$(bursar_window_totals "nonexistent000" "0")
+	[ "$(printf '%s' "$totals" | jq -r '.session_count')" = "0" ]
+	[ "$(printf '%s' "$totals" | jq -r '.total_cost_usd')" = "0" ]
+}
+
+@test "token formatting is human-friendly" {
+	[ "$(bursar_fmt_tokens 800)" = "800" ]
+	[ "$(bursar_fmt_tokens 42000)" = "42k" ]
+	[ "$(bursar_fmt_tokens 3100000)" = "3.1M" ]
+}

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-project-key.sh"
+}
+
+_mk_repo_with_remote() {
+	local dir="$1" url="$2"
+	mkdir -p "$dir"
+	git init -q "$dir" 2>/dev/null
+	git -C "$dir" remote add origin "$url" 2>/dev/null
+}
+
+@test "key is a 12-char hex string for a repo with a remote" {
+	local repo="${BATS_TEST_TMPDIR}/repo-a"
+	_mk_repo_with_remote "$repo" "https://example.com/onlooker/a.git"
+	run bursar_project_key "$repo"
+	[ "$status" -eq 0 ]
+	[ "${#output}" -eq 12 ]
+	[[ "$output" =~ ^[0-9a-f]{12}$ ]]
+}
+
+@test "same cwd yields a stable key" {
+	local repo="${BATS_TEST_TMPDIR}/repo-b"
+	_mk_repo_with_remote "$repo" "https://example.com/onlooker/b.git"
+	local a b
+	a=$(bursar_project_key "$repo")
+	b=$(bursar_project_key "$repo")
+	[ -n "$a" ]
+	[ "$a" = "$b" ]
+}
+
+@test "different remotes yield different keys" {
+	local r1="${BATS_TEST_TMPDIR}/repo-c" r2="${BATS_TEST_TMPDIR}/repo-d"
+	_mk_repo_with_remote "$r1" "https://example.com/onlooker/c.git"
+	_mk_repo_with_remote "$r2" "https://example.com/onlooker/d.git"
+	[ "$(bursar_project_key "$r1")" != "$(bursar_project_key "$r2")" ]
+}
+
+@test "empty key for a non-git directory" {
+	local plain="${BATS_TEST_TMPDIR}/not-a-repo"
+	mkdir -p "$plain"
+	run bursar_project_key "$plain"
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}

package/test/bats/bursar-session-end.bats

@@ -0,0 +1,131 @@
+#!/usr/bin/env bats
+
+# Exercises the SessionEnd hook end-to-end against an isolated $ONLOOKER_DIR.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	HOOK="${PLUGIN_ROOT}/scripts/hooks/bursar-session-end.sh"
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	SID="bats-end-001"
+	PK="projendabcd12"
+}
+
+_enable() {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+}
+
+_breadcrumb() {
+	local dir="${ONLOOKER_DIR}/bursar/sessions"
+	mkdir -p "$dir"
+	jq -n --arg pk "$PK" '{project_key:$pk, cwd:"/tmp", started_at:"x"}' > "${dir}/${SID}.json"
+}
+
+_seed_governor_event() {
+	# A minimal but well-formed governor.session.complete envelope line.
+	jq -nc --arg sid "$SID" \
+		'{event_type:"governor.session.complete", plugin:"governor", session_id:"outer",
+		  payload:{session_id:$sid, total_cost_usd:0.42, total_tokens:42000, total_api_calls:12,
+		           budget_usd:1.0, under_budget:true, duration_ms:0, calls_blocked:0,
+		           calls_warned:0, ledger_poisoned:false}}' >> "$ONLOOKER_EVENTS_LOG"
+}
+
+_ledger_path() { printf '%s/bursar/projects/%s/sessions.jsonl' "$ONLOOKER_DIR" "$PK"; }
+
+_run_hook() {
+	printf '%s' "{\"session_id\":\"$SID\"}" > "${BATS_TEST_TMPDIR}/in.json"
+	run bash "$HOOK" < "${BATS_TEST_TMPDIR}/in.json"
+}
+
+@test "records a session's spend from governor.session.complete" {
+	_enable
+	_breadcrumb
+	_seed_governor_event
+	_run_hook
+	[ "$status" -eq 0 ]
+
+	local path
+	path=$(_ledger_path)
+	[ -f "$path" ]
+	[ "$(wc -l < "$path")" -eq 1 ]
+	[ "$(jq -r '.cost_usd' "$path")" = "0.42" ]
+	[ "$(jq -r '.tokens' "$path")" = "42000" ]
+	[ "$(jq -r '.api_calls' "$path")" = "12" ]
+	[ "$(jq -r '.governor_present' "$path")" = "true" ]
+	[ "$(jq -r '.session_id' "$path")" = "$SID" ]
+}
+
+@test "removes the breadcrumb after recording" {
+	_enable
+	_breadcrumb
+	_seed_governor_event
+	_run_hook
+	[ ! -f "${ONLOOKER_DIR}/bursar/sessions/${SID}.json" ]
+}
+
+@test "degrades to governor_present:false when no governor event exists" {
+	_enable
+	_breadcrumb
+	# no governor.session.complete seeded
+	_run_hook
+	[ "$status" -eq 0 ]
+
+	local path
+	path=$(_ledger_path)
+	[ -f "$path" ]
+	[ "$(jq -r '.governor_present' "$path")" = "false" ]
+	[ "$(jq -r 'has("cost_usd")' "$path")" = "false" ]
+}
+
+@test "is idempotent across a repeated SessionEnd" {
+	_enable
+	_breadcrumb
+	_seed_governor_event
+	_run_hook
+	# Breadcrumb is gone now; re-create it to simulate a second SessionEnd.
+	_breadcrumb
+	_run_hook
+	[ "$(wc -l < "$(_ledger_path)")" -eq 1 ]
+}
+
+@test "writes nothing when bursar is disabled" {
+	# bursar disabled (no settings written)
+	_breadcrumb
+	_seed_governor_event
+	_run_hook
+	[ "$status" -eq 0 ]
+	[ ! -d "${ONLOOKER_DIR}/bursar/projects" ]
+}
+
+@test "keeps the breadcrumb and emits nothing when the ledger write fails" {
+	_enable
+	_breadcrumb
+	_seed_governor_event
+	# Force bursar_ledger_record to fail: a file where the projects dir must go,
+	# so its `mkdir -p` cannot create the project directory.
+	mkdir -p "${ONLOOKER_DIR}/bursar"
+	printf 'x' > "${ONLOOKER_DIR}/bursar/projects"
+	_run_hook
+	[ "$status" -eq 0 ]
+	# Breadcrumb retained so the attribution survives for a later attempt.
+	[ -f "${ONLOOKER_DIR}/bursar/sessions/${SID}.json" ]
+	# No false "recorded" event.
+	run grep -c '"event_type":"bursar.session.recorded"' "$ONLOOKER_EVENTS_LOG"
+	[ "$output" -eq 0 ]
+}
+
+@test "emits bursar.session.recorded" {
+	_enable
+	_breadcrumb
+	_seed_governor_event
+	_run_hook
+	run grep -c '"event_type":"bursar.session.recorded"' "$ONLOOKER_EVENTS_LOG"
+	[ "$status" -eq 0 ]
+	[ "$output" -ge 1 ]
+}

package/test/bats/bursar-session-start.bats

@@ -0,0 +1,126 @@
+#!/usr/bin/env bats
+
+# Exercises the SessionStart hook end-to-end against an isolated $ONLOOKER_DIR.
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	HOOK="${PLUGIN_ROOT}/scripts/hooks/bursar-session-start.sh"
+	export _ONLOOKER_EVENT_JS="${REPO_ROOT}/scripts/lib/onlooker-event.mjs"
+	export ONLOOKER_EVENTS_LOG="${ONLOOKER_DIR}/logs/onlooker-events.jsonl"
+	mkdir -p "$(dirname "$ONLOOKER_EVENTS_LOG")"
+
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-project-key.sh"
+
+	# A real git repo so a project key resolves.
+	REPO="${BATS_TEST_TMPDIR}/proj"
+	mkdir -p "$REPO"
+	git init -q "$REPO" 2>/dev/null
+	git -C "$REPO" remote add origin https://example.com/onlooker/bursar-test.git 2>/dev/null
+	KEY=$(bursar_project_key "$REPO")
+
+	SID="bats-start-001"
+}
+
+_enable() {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"enabled":true}}' > "${HOME}/.claude/settings.json"
+}
+
+_seed_ledger() {
+	# One recent recorded session with cost.
+	local dir="${ONLOOKER_DIR}/bursar/projects/${KEY}"
+	mkdir -p "$dir"
+	local now
+	now=$(date +%s)
+	jq -nc --arg pk "$KEY" --argjson te "$now" \
+		'{ts:"x", ts_epoch:$te, session_id:"older", project_key:$pk,
+		  governor_present:true, cost_usd:0.42, tokens:42000, api_calls:12}' \
+		> "${dir}/sessions.jsonl"
+}
+
+_run_hook() {
+	printf '%s' "{\"session_id\":\"$SID\",\"cwd\":\"$REPO\",\"source\":\"startup\"}" \
+		> "${BATS_TEST_TMPDIR}/in.json"
+	run bash "$HOOK" < "${BATS_TEST_TMPDIR}/in.json"
+}
+
+@test "produces no output when bursar is disabled" {
+	_run_hook
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+}
+
+@test "writes a breadcrumb carrying the project key" {
+	_enable
+	_run_hook
+	[ "$status" -eq 0 ]
+	local bc="${ONLOOKER_DIR}/bursar/sessions/${SID}.json"
+	[ -f "$bc" ]
+	[ "$(jq -r '.project_key' "$bc")" = "$KEY" ]
+}
+
+@test "surfaces no additionalContext when the window is empty" {
+	_enable
+	_run_hook
+	[ "$status" -eq 0 ]
+	[[ "$output" != *"hookSpecificOutput"* ]]
+}
+
+@test "emits bursar.rollup.skipped when there is no data" {
+	_enable
+	_run_hook
+	run grep -c '"event_type":"bursar.rollup.skipped"' "$ONLOOKER_EVENTS_LOG"
+	[ "$status" -eq 0 ]
+	[ "$output" -ge 1 ]
+}
+
+@test "surfaces the burned total as SessionStart additionalContext" {
+	_enable
+	_seed_ledger
+	_run_hook
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"hookSpecificOutput"* ]]
+	[[ "$output" == *"SessionStart"* ]]
+	[[ "$output" == *"burned \$0.42"* ]]
+}
+
+@test "reports a tracked \$0.00 total without nudging to enable governor" {
+	_enable
+	# governor present, but the window's cost is legitimately zero
+	local dir="${ONLOOKER_DIR}/bursar/projects/${KEY}"
+	mkdir -p "$dir"
+	local now
+	now=$(date +%s)
+	jq -nc --arg pk "$KEY" --argjson te "$now" \
+		'{ts:"x", ts_epoch:$te, session_id:"zero", project_key:$pk,
+		  governor_present:true, cost_usd:0, tokens:0, api_calls:0}' \
+		> "${dir}/sessions.jsonl"
+	_run_hook
+	[ "$status" -eq 0 ]
+	[[ "$output" == *"burned \$0.00"* ]]
+	[[ "$output" != *"Enable governor"* ]]
+}
+
+@test "emits bursar.rollup.surfaced when data exists" {
+	_enable
+	_seed_ledger
+	_run_hook
+	run grep -c '"event_type":"bursar.rollup.surfaced"' "$ONLOOKER_EVENTS_LOG"
+	[ "$status" -eq 0 ]
+	[ "$output" -ge 1 ]
+}
+
+@test "stays silent at the surface step but still records the breadcrumb when surfacing is disabled" {
+	mkdir -p "${HOME}/.claude"
+	printf '%s\n' '{"bursar":{"enabled":true,"surface_at_session_start":false}}' \
+		> "${HOME}/.claude/settings.json"
+	_seed_ledger
+	_run_hook
+	[ "$status" -eq 0 ]
+	[ -z "$output" ]
+	[ -f "${ONLOOKER_DIR}/bursar/sessions/${SID}.json" ]
+}

package/test/bats/bursar-ulid.bats

@@ -0,0 +1,28 @@
+#!/usr/bin/env bats
+
+setup() {
+	source "${BATS_TEST_DIRNAME}/../helpers/setup.bash"
+	setup_test_env
+
+	PLUGIN_ROOT="${REPO_ROOT}/plugins/bursar"
+	# shellcheck disable=SC1091
+	source "${PLUGIN_ROOT}/scripts/lib/bursar-ulid.sh"
+}
+
+@test "bursar_ulid is 26 characters" {
+	run bursar_ulid
+	[ "$status" -eq 0 ]
+	[ "${#output}" -eq 26 ]
+}
+
+@test "bursar_ulid uses only Crockford base32 (no I, L, O, U)" {
+	run bursar_ulid
+	[[ "$output" =~ ^[0-9A-HJKMNP-TV-Z]+$ ]]
+}
+
+@test "two ulids differ" {
+	local a b
+	a=$(bursar_ulid)
+	b=$(bursar_ulid)
+	[ "$a" != "$b" ]
+}