@onlooker-community/ecosystem 0.19.0 → 0.20.0

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Librarian SessionStart surfacer.
+#
+# Counts pending proposals in the project's queue and injects a one-line
+# `additionalContext` pointer if any exist. The full proposal bodies live
+# in ~/.onlooker/librarian/<project-key>/proposals/ and are reviewed via
+# the /librarian review skill rather than inlined here — SessionStart
+# context is precious, and a queue of 20 distilled-but-unreviewed memories
+# isn't where it should go.
+#
+# Hook contract:
+#   - Always exits 0. Never blocks session start.
+#   - Emits valid hookSpecificOutput JSON, even when nothing to say.
+#   - No-ops when librarian.enabled is not true.
+#   - No-ops when there is no project key (no git context).
+
+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
+if [[ -n "$_ECOSYSTEM_ROOT" && -f "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh" ]]; then
+	# shellcheck disable=SC1091
+	CLAUDE_PLUGIN_ROOT="$_ECOSYSTEM_ROOT" source "${_ECOSYSTEM_ROOT}/scripts/lib/validate-path.sh"
+fi
+
+# shellcheck source=../lib/librarian-config.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-config.sh"
+# shellcheck source=../lib/librarian-project-key.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-project-key.sh"
+# shellcheck source=../lib/librarian-storage.sh
+source "${PLUGIN_ROOT}/scripts/lib/librarian-storage.sh"
+
+# Emit hookSpecificOutput with the given additionalContext string. An
+# empty string is fine — the harness sees "nothing to say".
+_emit() {
+	local context="${1:-}"
+	jq -cn --arg ctx "$context" '
+		{
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: $ctx
+			}
+		}
+	'
+}
+
+INPUT=$(cat 2>/dev/null || true)
+CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || CWD=""
+[[ -z "$CWD" ]] && CWD="$(pwd)"
+
+REPO_ROOT=$(librarian_project_repo_root "$CWD")
+librarian_config_load "$REPO_ROOT"
+
+if ! librarian_config_enabled; then
+	_emit ""
+	exit 0
+fi
+
+PROJECT_KEY=$(librarian_project_key "$CWD")
+if [[ -z "$PROJECT_KEY" ]]; then
+	_emit ""
+	exit 0
+fi
+
+SKIP_WHEN_ZERO=$(librarian_config_get '.librarian.surfacer.skip_inject_when_zero')
+[[ -z "$SKIP_WHEN_ZERO" || "$SKIP_WHEN_ZERO" == "null" ]] && SKIP_WHEN_ZERO="true"
+
+MAX_PENDING=$(librarian_config_get '.librarian.surfacer.max_pending_for_inject')
+[[ -z "$MAX_PENDING" || "$MAX_PENDING" == "null" ]] && MAX_PENDING=20
+
+PENDING=$(librarian_storage_count_pending "$PROJECT_KEY")
+[[ -z "$PENDING" || "$PENDING" == "null" ]] && PENDING=0
+
+if [[ "$PENDING" -eq 0 && "$SKIP_WHEN_ZERO" == "true" ]]; then
+	_emit ""
+	exit 0
+fi
+
+# Cap the surfaced number so a runaway queue doesn't make the pointer
+# itself look alarming. Users still see the truthful count in
+# /librarian review.
+if [[ "$PENDING" -gt "$MAX_PENDING" ]]; then
+	DISPLAY_COUNT="${MAX_PENDING}+"
+else
+	DISPLAY_COUNT="$PENDING"
+fi
+
+NOUN="proposals"
+[[ "$PENDING" -eq 1 ]] && NOUN="proposal"
+
+CONTEXT=$(printf 'Librarian has %s pending memory promotion %s. Review with `/librarian review`.' \
+	"$DISPLAY_COUNT" "$NOUN")
+
+_emit "$CONTEXT"
+exit 0

package/plugins/librarian/scripts/lib/librarian-archivist-reader.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Reads archivist artifacts for the librarian scan pipeline.
+#
+# Archivist stores per-session artifacts under:
+#   $ONLOOKER_DIR/archivist/<project-key>/{decisions,dead_ends,open_questions}/<ulid>.json
+#
+# Each artifact has the shape (see archivist's storage.sh):
+#   { id, kind, project_key, source, created_at, updated_at, summary,
+#     detail, files, session_id, trigger }
+#
+# Librarian reads the same project-key directory and filters by created_at,
+# returning candidates newer than the watermark.
+
+# Resolve the archivist project dir for a given project key.
+# Returns empty if archivist artifacts are not present.
+librarian_archivist_project_dir() {
+	local project_key="$1"
+	[[ -z "$project_key" ]] && return 0
+	local base="${ONLOOKER_DIR:-$HOME/.onlooker}"
+	local dir="${base}/archivist/${project_key}"
+	[[ -d "$dir" ]] || return 0
+	printf '%s' "$dir"
+}
+
+# Load archivist artifacts created since the given watermark.
+#
+# Usage: librarian_archivist_load_since <project_key> <watermark_iso>
+#
+# Watermark format: ISO-8601 (e.g., "2026-06-01T12:34:56Z"). When the
+# watermark is empty, all artifacts are returned (used on first scan).
+#
+# Output: JSON array, one element per artifact, in chronological order.
+librarian_archivist_load_since() {
+	local project_key="$1"
+	local watermark="${2:-}"
+
+	local project_dir
+	project_dir=$(librarian_archivist_project_dir "$project_key")
+	[[ -z "$project_dir" ]] && { echo '[]'; return 0; }
+
+	local kind file all='[]'
+	for kind in decisions dead_ends open_questions; do
+		[[ -d "${project_dir}/${kind}" ]] || continue
+		for file in "${project_dir}/${kind}"/*.json; do
+			[[ -f "$file" ]] || continue
+			local item created_at
+			item=$(jq '.' "$file" 2>/dev/null) || continue
+			[[ -z "$item" || "$item" == "null" ]] && continue
+
+			# Filter by watermark when provided.
+			if [[ -n "$watermark" ]]; then
+				created_at=$(printf '%s' "$item" | jq -r '.created_at // .updated_at // ""' 2>/dev/null)
+				[[ -z "$created_at" ]] && continue
+				# Lexicographic compare works for ISO-8601 UTC strings.
+				if [[ "$created_at" < "$watermark" || "$created_at" == "$watermark" ]]; then
+					continue
+				fi
+			fi
+
+			all=$(printf '%s' "$all" | jq --argjson item "$item" '. + [$item]')
+		done
+	done
+
+	# Sort chronologically; downstream classifier groups by session_id and
+	# benefits from stable order.
+	printf '%s' "$all" | jq 'sort_by(.created_at // .updated_at // "")'
+}

package/plugins/librarian/scripts/lib/librarian-classifier.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# Type classifier for librarian candidates.
+#
+# Calls `claude -p` with a structured prompt that maps a single archivist
+# artifact to one of the four memory types (user, feedback, project,
+# reference) or null when the artifact is interesting but session-only.
+#
+# Returns the model's JSON response on stdout, or empty string on any
+# error (timeout, missing CLI, invalid JSON, low confidence). Callers
+# treat empty as "drop this candidate".
+#
+# Config inputs (read via librarian_config_get from the caller):
+#   librarian.classifier.model              Anthropic model id
+#   librarian.classifier.temperature        Sampling temperature
+#   librarian.classifier.max_output_tokens  Output cap
+#   librarian.classifier.min_classifier_confidence  Drop below this
+
+# Hard wall-clock ceiling for a single classifier call. We never want a
+# hung LLM to delay SessionEnd more than this.
+_LIBRARIAN_CLASSIFIER_TIMEOUT_SECONDS=20
+
+# Build the classifier prompt for a single artifact.
+# Usage: librarian_classifier_build_prompt <artifact_json>
+librarian_classifier_build_prompt() {
+	local artifact="$1"
+	local kind summary detail files_list session_id created_at
+
+	kind=$(printf '%s' "$artifact" | jq -r '.kind // ""')
+	summary=$(printf '%s' "$artifact" | jq -r '.summary // ""')
+	detail=$(printf '%s' "$artifact" | jq -r '.detail // ""')
+	files_list=$(printf '%s' "$artifact" | jq -r '(.files // []) | join(", ")')
+	session_id=$(printf '%s' "$artifact" | jq -r '.session_id // ""')
+	created_at=$(printf '%s' "$artifact" | jq -r '.created_at // ""')
+
+	cat <<EOF
+You are classifying a session artifact for promotion into a long-term memory store.
+
+The store has four types:
+- user: durable facts about the user's role, expertise, or working style
+- feedback: corrections or validated preferences ("don't do X", "yes, keep doing Y")
+- project: ongoing work facts, decisions, constraints not derivable from the code
+- reference: pointers to external systems (issue trackers, dashboards, channels)
+
+RULES:
+- Output ONLY a single JSON object on one line, no markdown fences, no prose.
+- Schema: { "type": "<user|feedback|project|reference|null>",
+            "title": "<<=60 chars>",
+            "body": "<the memory content; structure per type>",
+            "confidence": <float 0-1> }
+- Use "type": null when the artifact is interesting but session-only (a
+  specific bug fix, a one-off question that got answered, an exploration
+  that didn't change anything).
+- For feedback and project types, include **Why:** and **How to apply:**
+  lines inside the body.
+
+<artifact>
+kind: ${kind}
+summary: ${summary}
+detail: ${detail}
+files: ${files_list}
+session_id: ${session_id}
+created_at: ${created_at}
+</artifact>
+EOF
+}
+
+# Call the classifier for one artifact. Prints the model's JSON output or
+# empty string on error.
+#
+# Usage: librarian_classifier_call <artifact_json> <model> <temperature>
+#                                  <max_output_tokens>
+librarian_classifier_call() {
+	local artifact="$1"
+	local model="${2:-}"
+	local temperature="${3:-0.2}"
+	local max_tokens="${4:-256}"
+
+	command -v claude >/dev/null 2>&1 || return 0
+	[[ -z "$artifact" ]] && return 0
+
+	local prompt_file
+	prompt_file=$(mktemp -t librarian-classify.XXXXXX 2>/dev/null) \
+		|| prompt_file="/tmp/librarian-classify.$$"
+	# shellcheck disable=SC2064
+	trap "rm -f '$prompt_file'" EXIT
+
+	librarian_classifier_build_prompt "$artifact" > "$prompt_file" || return 0
+
+	local args=(-p --max-turns 1)
+	[[ -n "$model" ]] && args+=(--model "$model")
+
+	local response=""
+	if command -v timeout >/dev/null 2>&1; then
+		response=$(timeout "$_LIBRARIAN_CLASSIFIER_TIMEOUT_SECONDS" \
+			claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	elif command -v gtimeout >/dev/null 2>&1; then
+		response=$(gtimeout "$_LIBRARIAN_CLASSIFIER_TIMEOUT_SECONDS" \
+			claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	else
+		response=$(claude "${args[@]}" < "$prompt_file" 2>/dev/null) || response=""
+	fi
+
+	rm -f "$prompt_file"
+	trap - EXIT
+
+	[[ -z "$response" ]] && return 0
+
+	# Strip accidental markdown fences before parsing.
+	local clean
+	clean=$(printf '%s' "$response" | sed -e 's/^```json//' -e 's/^```//' -e 's/```$//')
+
+	# Validate the response shape before passing it back.
+	if ! printf '%s' "$clean" | jq -e '
+		(.type == null or (.type | IN("user", "feedback", "project", "reference")))
+		and (.title | type) == "string"
+		and (.body | type) == "string"
+		and (.confidence | type) == "number"
+	' >/dev/null 2>&1; then
+		return 0
+	fi
+
+	printf '%s' "$clean"
+}
+
+# Synthesize a deterministic filename from a classifier result.
+# Used when writing accepted promotions into the typed memory store.
+# Format: <type>_<slugified-title>.md
+#
+# Usage: librarian_classifier_filename <type> <title>
+librarian_classifier_filename() {
+	local type="$1"
+	local title="$2"
+	local slug
+	slug=$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' \
+		| sed -E 's/[^a-z0-9]+/_/g; s/^_+|_+$//g' \
+		| cut -c1-60)
+	[[ -z "$slug" ]] && slug="memory"
+	printf '%s_%s.md' "$type" "$slug"
+}

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Config resolution for Librarian.
+#
+# Reads three layers, latest wins:
+#   1. plugins/librarian/config.json (defaults shipped with the plugin)
+#   2. ~/.claude/settings.json
+#   3. <repo>/.claude/settings.json
+#
+# Exposes:
+#   librarian_config_load <repo_root>    # populates _LIBRARIAN_CONFIG (JSON)
+#   librarian_config_get <jq-path>       # echoes string value (empty if unset)
+#   librarian_config_enabled             # 0 if librarian.enabled is true
+#   librarian_config_auto_promote        # 0 if librarian.auto_promote is true
+#
+# Settings overlay only touches the `librarian.*` subtree of settings.json so
+# it coexists with other plugins' configuration.
+
+_LIBRARIAN_CONFIG="{}"
+
+librarian_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 '{ librarian: (.librarian // {}) }' "$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
+
+	_LIBRARIAN_CONFIG="$merged"
+}
+
+# Read a value from the loaded config. Usage:
+#   librarian_config_get '.librarian.surfacer.max_pending_for_inject'
+librarian_config_get() {
+	local path="$1"
+	printf '%s' "$_LIBRARIAN_CONFIG" | jq -r "${path} // empty" 2>/dev/null
+}
+
+# Returns 0 if librarian.enabled is true, 1 otherwise.
+librarian_config_enabled() {
+	local v
+	v=$(librarian_config_get '.librarian.enabled')
+	[[ "$v" == "true" ]]
+}
+
+# Returns 0 if librarian.auto_promote is true, 1 otherwise.
+librarian_config_auto_promote() {
+	local v
+	v=$(librarian_config_get '.librarian.auto_promote')
+	[[ "$v" == "true" ]]
+}

package/plugins/librarian/scripts/lib/librarian-durability.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Cheap pre-LLM durability filter for librarian candidates.
+#
+# Drops obvious session-only items before paying for classification:
+#   - Drop if detail.length < min_detail_chars
+#   - Drop if matches a drop-list phrase
+#   - Keep if matches a marker phrase ("always", "never", "remember", ...)
+#   - Keep if files[] contains a path that still exists in the repo
+#     (caller-supplied flag — we don't shell out to git here)
+#
+# Output: JSON array of surviving candidates plus a drop-reason record for
+# each rejected item so the scan-complete event can report counts.
+
+# Default drop-list patterns: terse meta-conversation that almost never
+# promotes well. Matched case-insensitively against summary+detail.
+_LIBRARIAN_DURABILITY_DROP_PATTERNS=(
+	"the test is failing"
+	"let me check"
+	"i'll come back to this"
+	"i will come back to this"
+	"working on it"
+	"investigating"
+)
+
+# Apply the durability filter to a JSON array of candidates.
+#
+# Usage: librarian_durability_filter <candidates_json> <markers_json> \
+#                                    <min_detail_chars>
+#
+# Args:
+#   candidates_json    Array of archivist artifacts (from
+#                      librarian_archivist_load_since).
+#   markers_json       JSON array of marker phrases (from config).
+#   min_detail_chars   Minimum detail length to keep an artifact.
+#
+# Output: JSON object with two keys:
+#   { "kept":    [<artifact>, ...],
+#     "dropped": [{ "artifact_id": "...", "reason": "..." }, ...] }
+librarian_durability_filter() {
+	local candidates="${1:-[]}"
+	local markers_json="${2:-[]}"
+	local min_detail="${3:-40}"
+
+	local drops
+	drops=$(printf '%s\n' "${_LIBRARIAN_DURABILITY_DROP_PATTERNS[@]}" \
+		| jq -R . | jq -s .)
+
+	# All filtering happens in one jq expression to avoid bash-side iteration
+	# for what's a pure data transform.
+	printf '%s' "$candidates" | jq \
+		--argjson markers "$markers_json" \
+		--argjson drops "$drops" \
+		--argjson min_detail "$min_detail" \
+		'
+		def normalized: ((.summary // "") + " " + (.detail // "")) | ascii_downcase;
+		def matches_any($patterns): . as $text | $patterns | any(. as $p | ($text | contains($p)));
+
+		def classify(c):
+			c | normalized as $text |
+			(c.detail // "") as $detail |
+			if ($detail | length) < $min_detail then
+				{ kept: false, reason: "detail_too_short" }
+			elif ($text | matches_any($drops)) then
+				{ kept: false, reason: "filter_drop_pattern" }
+			elif ($text | matches_any($markers)) then
+				{ kept: true, reason: "marker_phrase_match" }
+			else
+				{ kept: false, reason: "filter_marker_missing" }
+			end;
+
+		map(. as $c | classify($c) as $r | $c + { _filter: $r })
+		| {
+			kept: [.[] | select(._filter.kept) | del(._filter)],
+			dropped: [.[] | select(._filter.kept | not) | { artifact_id: .id, reason: ._filter.reason }]
+		}
+		'
+}

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Event emission helpers for Librarian.
+#
+# Wraps the canonical onlooker-event.mjs `emit` mode so hook scripts can
+# build a librarian.* event without touching node directly. Events are
+# schema-validated by onlooker-event.mjs; if validation fails the line is
+# silently dropped (fail-soft) rather than blocking the hook.
+
+# Resolve the ecosystem helper path. The substrate is in the sibling
+# ecosystem plugin at ../../../.. relative to plugins/librarian/scripts/hooks.
+# Honor ONLOOKER_ECOSYSTEM_ROOT when set (test isolation).
+_librarian_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
+}
+
+_LIBRARIAN_EVENT_JS="${_LIBRARIAN_EVENT_JS:-$(_librarian_resolve_event_js)}"
+
+# Emit a librarian.* event. Fail-soft: returns 0 on success or when the
+# substrate is unavailable; the event is dropped silently.
+#
+# Usage: librarian_emit <event_type> <session_id> <payload_json>
+#
+# Example:
+#   librarian_emit "librarian.scan.started" "$SID" "$(jq -n \
+#     --arg trigger "session_end" '{ trigger: $trigger }')"
+librarian_emit() {
+	local event_type="${1:-}"
+	local session_id="${2:-}"
+	local payload="${3:-{\}}"
+
+	[[ -z "$event_type" || -z "$session_id" ]] && return 0
+	[[ -z "$_LIBRARIAN_EVENT_JS" || ! -f "$_LIBRARIAN_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 "librarian" \
+		--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="librarian" \
+		printf '%s' "$params" | node "$_LIBRARIAN_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/librarian/scripts/lib/librarian-project-key.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Project key derivation for Librarian.
+#
+# Librarian writes its proposal queue and tombstones under the ecosystem-wide
+# 12-char hex project key so a single project's state is shared across clones.
+# (The typed memory store the user maintains lives at a different path keyed by
+# the Claude Code per-checkout encoding; that path is resolved separately at
+# write time.)
+#
+# 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 (greenfield local-only work)
+#
+# Returns the first 12 hex chars. Returns empty string if neither resolution
+# path works (caller decides whether to skip or treat as a non-repo session).
+
+_librarian_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
+}
+
+librarian_project_remote_url() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" || ! -d "$cwd" ]] && return 0
+	git -C "$cwd" remote get-url origin 2>/dev/null || true
+}
+
+librarian_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 string.
+# Usage: key=$(librarian_project_key "$CWD")
+librarian_project_key() {
+	local cwd="${1:-}"
+	[[ -z "$cwd" ]] && cwd="$(pwd)"
+
+	local remote
+	remote=$(librarian_project_remote_url "$cwd")
+	if [[ -n "$remote" ]]; then
+		_librarian_sha256_first12 "remote:$remote"
+		return 0
+	fi
+
+	local root
+	root=$(librarian_project_repo_root "$cwd")
+	if [[ -n "$root" ]]; then
+		_librarian_sha256_first12 "root:$root"
+		return 0
+	fi
+
+	return 0
+}