@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/lib/telemetry.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# lib/telemetry.sh — bassclef telemetry event emission (opt-in, local-only)
+# tier: lite
+# install-class: dual
+#
+# Deep module per @luminary john-ousterhout — small interface (5 functions
+# + CLI), complex implementation (opt-in gate + UUID session + schema
+# validation + append-only write) hidden behind it.
+#
+# Opt-in default OFF per @luminary alan-cooper (privacy) +
+# @luminary donald-norman (affordance — first-session prompt is where
+# consent lives).
+#
+# Schema-enforced no-PII per @luminary tony-hoare (contract — schema
+# validates in; append-only out).
+#
+# Silent-fail wrap per @luminary michael-nygard (stability — telemetry
+# never crashes adopter session).
+#
+# ADR-049 governs the design.
+
+set -u
+
+# ---------------------------------------------------------------------------
+# Path resolution — respects TELEMETRY_ROOT for tests; falls back to repo
+# root discovered from lib/ position.
+# ---------------------------------------------------------------------------
+if [ -z "${TELEMETRY_ROOT:-}" ]; then
+  TELEMETRY_ROOT="${REPO_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+fi
+_TELEM_CONFIG="${TELEMETRY_ROOT}/state/telemetry/config.json"
+_TELEM_SESSION="${TELEMETRY_ROOT}/state/telemetry/current-session.uuid"
+_TELEM_EVENTS_DIR="${TELEMETRY_ROOT}/state/telemetry"
+_TELEM_SCHEMA="${TELEMETRY_ROOT}/standards/telemetry-event.schema.json"
+
+# ---------------------------------------------------------------------------
+# telemetry_is_enabled — exit 0 when opt-in ON, 1 when OFF.
+# Default is OFF (no config file = OFF).
+# ---------------------------------------------------------------------------
+telemetry_is_enabled() {
+  [ -f "$_TELEM_CONFIG" ] || return 1
+  grep -q '"enabled"[[:space:]]*:[[:space:]]*true' "$_TELEM_CONFIG" 2>/dev/null
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_enable — write config marking opt-in ON.
+# ---------------------------------------------------------------------------
+telemetry_enable() {
+  mkdir -p "$(dirname "$_TELEM_CONFIG")"
+  printf '{"enabled": true}\n' > "$_TELEM_CONFIG"
+  echo "telemetry: ENABLED (config at $_TELEM_CONFIG)"
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_disable — remove config; opt-in returns to OFF.
+# Existing event files stay in place; adopter owns their data.
+# ---------------------------------------------------------------------------
+telemetry_disable() {
+  rm -f "$_TELEM_CONFIG"
+  echo "telemetry: DISABLED (config removed; existing events in $_TELEM_EVENTS_DIR preserved)"
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_status — print current opt-in state + storage location.
+# ---------------------------------------------------------------------------
+telemetry_status() {
+  if telemetry_is_enabled; then
+    echo "telemetry: ON"
+    echo "  config: $_TELEM_CONFIG"
+    echo "  events: $_TELEM_EVENTS_DIR/events-YYYYMMDD.jsonl"
+    echo "  share:  bash lib/telemetry.sh share  (send report to bassclef)"
+    echo "  disable: bash lib/telemetry.sh disable"
+  else
+    echo "telemetry: OFF"
+    echo "  enable: bash lib/telemetry.sh enable"
+    echo "  see: docs/telemetry.md for what data ships"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_share — prepare a report share ready to send upstream.
+# Adopter runs after aggregate. Opens a gh issue prefilled with the report
+# body OR prints a mailto: URL. Adopter is always the sender; the command
+# only lowers friction. Never auto-sends. Per ADR-049 §Alternatives Alt B
+# (remote share deferred to Iteration 4).
+# ---------------------------------------------------------------------------
+telemetry_share() {
+  local report_dir="${TELEMETRY_ROOT}/docs/telemetry-reports"
+  local latest_report
+  latest_report=$(ls -1t "$report_dir"/*.md 2>/dev/null | head -1)
+
+  if [ -z "$latest_report" ]; then
+    echo "telemetry: no report to share — run first:"
+    echo "  bash scripts/aggregate-telemetry.sh"
+    return 1
+  fi
+
+  echo "telemetry: latest report is $latest_report"
+  echo ""
+
+  # Prefer gh CLI if available — prefills a public bassclef issue
+  if command -v gh >/dev/null 2>&1; then
+    local target_repo="${BASSCLEF_TELEM_SHARE_REPO:-sunj-labs/bassclef}"
+    echo "Share via GitHub issue on $target_repo:"
+    echo ""
+    echo "  gh issue create --repo $target_repo \\"
+    echo "    --title 'telemetry: adopter uptake report — $(date -u +%Y-%m-%d)' \\"
+    echo "    --label 'telemetry-share' \\"
+    echo "    --body-file $latest_report"
+    echo ""
+    echo "Override target repo with BASSCLEF_TELEM_SHARE_REPO env var."
+  fi
+
+  # Also print a mailto: URL for adopters who prefer email
+  local subject
+  subject="telemetry: adopter uptake report $(date -u +%Y-%m-%d)"
+  local body_hint="Report attached at $latest_report — copy the file contents into the email body."
+  echo ""
+  echo "Or email:"
+  echo "  mailto:${BASSCLEF_TELEM_SHARE_EMAIL:-hello@bassclef.dev}?subject=$(echo "$subject" | tr ' ' '+')&body=$(echo "$body_hint" | tr ' ' '+')"
+  echo ""
+  echo "You send the report yourself. Nothing leaves your machine automatically."
+  echo "Review $latest_report before sending — it contains only counts, no PII."
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_session_id — return current session UUID; generate if absent.
+# UUID v4 per ADR-049; never derived from operator identity or repo path.
+# ---------------------------------------------------------------------------
+telemetry_session_id() {
+  if [ ! -f "$_TELEM_SESSION" ]; then
+    mkdir -p "$(dirname "$_TELEM_SESSION")"
+    if command -v uuidgen >/dev/null 2>&1; then
+      uuidgen | tr '[:upper:]' '[:lower:]' > "$_TELEM_SESSION"
+    else
+      # Fallback bash-only UUID v4 (random hex; v4 variant bits)
+      printf '%08x-%04x-4%03x-%04x-%012x\n' \
+        $((RANDOM * RANDOM % 4294967296)) \
+        $((RANDOM % 65536)) \
+        $((RANDOM % 4096)) \
+        $((RANDOM % 65536)) \
+        $((RANDOM * RANDOM * RANDOM % 281474976710656)) > "$_TELEM_SESSION"
+    fi
+  fi
+  cat "$_TELEM_SESSION"
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_reset_session — clear current session UUID.
+# Called by session-end hook to close the current session boundary.
+# ---------------------------------------------------------------------------
+telemetry_reset_session() {
+  rm -f "$_TELEM_SESSION"
+}
+
+# ---------------------------------------------------------------------------
+# telemetry_emit EVENT_JSON — validate against schema + append one line to
+# today's JSONL file. Silent skip when opt-in OFF (returns 0).
+# Never crashes caller — schema failures silently drop.
+# ---------------------------------------------------------------------------
+telemetry_emit() {
+  local event_json="$1"
+
+  # Opt-in gate FIRST — per pre-mortem R5, order matters
+  telemetry_is_enabled || return 0
+
+  mkdir -p "$_TELEM_EVENTS_DIR"
+  local today
+  today=$(date -u +%Y%m%d)
+  local events_file="$_TELEM_EVENTS_DIR/events-$today.jsonl"
+
+  # Validate against schema when ajv available. Silent skip on schema fail
+  # or missing binary — telemetry never crashes adopter session (R1).
+  # Requires ajv-cli + ajv-formats. Both ship together in every bassclef
+  # CI job that runs this path (per .github/workflows/*.yml). Adopters
+  # get both via bassclef-onboard or npm bassclef-lite install script.
+  if command -v ajv >/dev/null 2>&1 && [ -f "$_TELEM_SCHEMA" ]; then
+    local tmpfile
+    tmpfile="$(mktemp -t bassclef-telem-XXXXXX).json"
+    printf '%s\n' "$event_json" > "$tmpfile"
+    if ! ajv validate --spec=draft2020 -c ajv-formats -s "$_TELEM_SCHEMA" -d "$tmpfile" >/dev/null 2>&1; then
+      rm -f "$tmpfile"
+      return 0
+    fi
+    rm -f "$tmpfile"
+  fi
+
+  # Append one line
+  printf '%s\n' "$event_json" >> "$events_file"
+}
+
+# ---------------------------------------------------------------------------
+# CLI dispatch — runs only when invoked directly (bash lib/telemetry.sh ...)
+# Sourced use exposes functions without side effects.
+# ---------------------------------------------------------------------------
+if [ "${BASH_SOURCE[0]}" = "${0:-}" ]; then
+  cmd="${1:-status}"
+  case "$cmd" in
+    enable)  telemetry_enable ;;
+    disable) telemetry_disable ;;
+    status)  telemetry_status ;;
+    share)   telemetry_share ;;
+    *)       echo "usage: bash lib/telemetry.sh {enable|disable|status|share}" >&2; exit 2 ;;
+  esac
+fi

package/substrate/lib/tier-check.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# tier: lite
+# lib/tier-check.sh — adopter tier resolution + gate.
+#
+# Deep module per @luminary john-ousterhout. Single interface hides the
+# catalog of tier resolution methods (explicit config, probe, env override,
+# safe default).
+#
+# Consumers: /onboard-repo SKILL body, /launch SKILL body, /longrun body,
+# release harness, cold-adopter harness Check 6 (planned).
+#
+# tier: upstream
+# install-class: dual
+#
+# Rules governed by:
+# - .claude/rules/testing-tier-config.md (Tier 0 strict TDD)
+# - .claude/rules/mechanism-fidelity.md (interface honored end to end)
+#
+# Anchor luminaries: ousterhout (deep module), feathers (probe pin behavior)
+
+# Rank map for tier comparison.
+_tier_rank() {
+  case "$1" in
+    lite) echo 1 ;;
+    standard) echo 2 ;;
+    pro) echo 3 ;;
+    *) echo 0 ;;
+  esac
+}
+
+# resolve_adopter_tier [repo_root]
+#
+# Returns one of: lite | standard | pro
+# Resolution order:
+#   1. BASSCLEF_TIER env override (test-only; wins over configs)
+#   2. adopter.tier field in .claude/bassclef-configs.jsonc
+#   3. Probe — provision-deploy-host skill present => standard;
+#      only lite-tagged skills present => lite
+#   4. Safe default => standard
+resolve_adopter_tier() {
+  local repo_root="${1:-$(pwd)}"
+  local tier=""
+  local source="default"
+
+  # Method 1: env override
+  if [ -n "${BASSCLEF_TIER:-}" ]; then
+    tier="$BASSCLEF_TIER"
+    source="env BASSCLEF_TIER"
+  fi
+
+  # Method 2: explicit configs field
+  if [ -z "$tier" ]; then
+    local configs="${repo_root}/.claude/bassclef-configs.jsonc"
+    if [ -f "$configs" ]; then
+      tier=$(_read_tier_from_configs "$configs" 2>/dev/null || true)
+      [ -n "$tier" ] && source="configs adopter.tier"
+    fi
+  fi
+
+  # Method 3: probe skills present
+  if [ -z "$tier" ]; then
+    local skills_dir="${repo_root}/.claude/skills"
+    if [ -d "$skills_dir/provision-deploy-host" ]; then
+      tier="standard"
+      source="probe (provision-deploy-host present)"
+    elif [ -d "$skills_dir/onboard-repo" ] || [ -d "$skills_dir/session-log" ]; then
+      # lite-tagged skills present; standard skills absent
+      tier="lite"
+      source="probe (lite skills present; standard absent)"
+    fi
+  fi
+
+  # Method 4: safe default
+  if [ -z "$tier" ]; then
+    tier="standard"
+    source="safe default (no configs, no skills probe hit)"
+  fi
+
+  # Validate tier is one of the known names
+  case "$tier" in
+    lite|standard|pro) : ;;
+    *)
+      tier="standard"
+      source="safe default (unknown tier '$tier' rejected)"
+      ;;
+  esac
+
+  # Debug log to stderr when requested
+  if [ "${DEBUG_TIER_CHECK:-0}" = "1" ]; then
+    echo "tier-check: tier=$tier source=$source" >&2
+  fi
+
+  echo "$tier"
+}
+
+# Parse tier from JSONC configs file. Strips comments then extracts adopter.tier.
+_read_tier_from_configs() {
+  local configs="$1"
+  python3 - "$configs" << 'PYEOF' 2>/dev/null || true
+import json
+import re
+import sys
+
+path = sys.argv[1]
+try:
+    with open(path) as f:
+        content = f.read()
+    # Strip // line comments and /* block */ comments
+    content = re.sub(r'/\*.*?\*/', '', content, flags=re.DOTALL)
+    content = re.sub(r'//[^\n]*', '', content)
+    d = json.loads(content)
+    tier = d.get('adopter', {}).get('tier', '') or d.get('tier', '')
+    if tier:
+        print(tier)
+except Exception:
+    pass
+PYEOF
+}
+
+# tier_at_least <required> [current]
+#
+# Returns 0 if current tier >= required, 1 otherwise.
+# Current tier resolves via resolve_adopter_tier when omitted.
+tier_at_least() {
+  local required="$1"
+  local current="${2:-$(resolve_adopter_tier)}"
+  local req_rank cur_rank
+  req_rank=$(_tier_rank "$required")
+  cur_rank=$(_tier_rank "$current")
+  # Unknown tier => reject
+  if [ "$req_rank" -eq 0 ] || [ "$cur_rank" -eq 0 ]; then
+    return 1
+  fi
+  if [ "$cur_rank" -ge "$req_rank" ]; then
+    return 0
+  fi
+  return 1
+}