@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/lib/telemetry.sh

@@ -1,205 +0,0 @@
-#!/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

@@ -1,187 +0,0 @@
-#!/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)
-# - mechanism-fidelity rule (standard tier; 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
-}
-
-# resolve_file_tier <path>
-#
-# Read a file's tier tag and print it to stdout. Returns empty string if
-# no tag is present. Supported shapes:
-#   - .md         — YAML frontmatter `tier:` field between --- markers
-#   - .sh, .py    — `# tier:` header line in first 10 lines
-#   - .yml, .yaml — `# tier:` comment OR top-level `tier:` field in first 30 lines
-#   - .json       — root-key `"tier"` or `"_tier"` in first 30 lines
-#   - .jsonc      — `// tier:` comment or root-key
-#   - .txt        — first-line `# tier:` convention
-#
-# Mirrors detection shape from .claude/hooks/tier-tag-required-at-write.sh so
-# the reader half and the writer half stay consistent.
-resolve_file_tier() {
-  local path="$1"
-  if [ ! -f "$path" ]; then
-    return 0
-  fi
-
-  local tier=""
-  case "$path" in
-    *.md)
-      # Frontmatter between --- markers, first 30 lines
-      tier=$(awk '
-        /^---/ { in_fm = !in_fm; if (!in_fm) exit; next }
-        in_fm && /^tier:[[:space:]]/ { sub(/^tier:[[:space:]]*/, ""); sub(/[[:space:]]*$/, ""); print; exit }
-        NR > 30 { exit }
-      ' "$path" 2>/dev/null)
-      ;;
-    *.sh|*.py)
-      tier=$(head -10 "$path" 2>/dev/null | grep -E '^#[[:space:]]*tier:[[:space:]]' | head -1 | sed -E 's/^#[[:space:]]*tier:[[:space:]]*//; s/[[:space:]]*$//')
-      ;;
-    *.yml|*.yaml)
-      tier=$(head -30 "$path" 2>/dev/null | grep -E '^#[[:space:]]*tier:[[:space:]]|^tier:[[:space:]]' | head -1 | sed -E 's/^#?[[:space:]]*tier:[[:space:]]*//; s/[[:space:]]*$//')
-      ;;
-    *.json|*.jsonc)
-      tier=$(head -30 "$path" 2>/dev/null | grep -oE '"(_?tier)"[[:space:]]*:[[:space:]]*"[a-z]+"' | head -1 | sed -E 's/.*:[[:space:]]*"([a-z]+)"/\1/')
-      if [ -z "$tier" ]; then
-        tier=$(head -30 "$path" 2>/dev/null | grep -oE '//[[:space:]]*tier:[[:space:]]*[a-z]+' | head -1 | sed -E 's/.*tier:[[:space:]]*//')
-      fi
-      ;;
-    *.txt)
-      tier=$(head -1 "$path" 2>/dev/null | grep -E '^#[[:space:]]*tier:[[:space:]]' | sed -E 's/^#[[:space:]]*tier:[[:space:]]*//; s/[[:space:]]*$//')
-      ;;
-  esac
-
-  echo "$tier"
-}
-
-# 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
-}