@thebassclef/lite 1.9.8 → 1.9.10

package/dist/lite/lib/install-written-paths.sh

@@ -0,0 +1,369 @@
+#!/bin/bash
+# tier: lite
+# Install-written-paths manifest + accessor lib.
+#
+# Records paths written by bassclef install writers so discipline hooks
+# can skip them. Per bassclef-upstream#2036 Finding #8 structural cure
+# (Kunal Slot 1). See docs/decompositions/2026-10-03-install-written-paths-manifest.md
+# for design + patterns applied (Repository + Deep Module + Null Object + Guard Clause).
+#
+# @pattern patterns/code/fowler/repository.md
+# @pattern patterns/code/ousterhout/deep-module.md
+#
+# Public API (5 verbs):
+#   install_written_paths_register <path> <writer>
+#   is_install_written_path <path>
+#   install_written_paths_rename <old-path> <new-path>
+#   install_written_paths_rebuild
+#   install_written_paths_verify
+#
+# Override: SKIP_INSTALL_WRITTEN_PATHS=1 — is_install_written_path returns 1 (false)
+# so hooks fire discipline normally (don't skip).
+#
+# Variable naming: internal locals use `tgt` (target path), `arg_*` prefix,
+# or `_iwp_*` namespace to avoid shadowing shell builtins. Reserved names
+# like `PATH`, `CDPATH`, `FPATH`, `MANPATH` are not used as locals per
+# shell-portability discipline (zsh treats lowercase `path` as array-tied
+# to PATH; renaming avoids the kill).
+
+set -u
+
+# ---- Constants ----
+
+_IWP_SCHEMA_VERSION="1.0.0"
+
+_IWP_WRITERS="bassclef-hook-connect bassclef-sync-template bassclef-sync-dispatcher schedule-auto-save bassclef-init-npm"
+
+# ---- Internal helpers ----
+
+_iwp_manifest_path() {
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  echo "$root/state/install-written-paths.json"
+}
+
+_iwp_log() {
+  if command -v trace_log >/dev/null 2>&1; then
+    trace_log "install-written-paths" "$*"
+  fi
+}
+
+_iwp_sha256() {
+  local file="$1"
+  if [ ! -f "$file" ]; then
+    echo ""
+    return 1
+  fi
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$file" 2>/dev/null | awk '{print "sha256:" $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$file" 2>/dev/null | awk '{print "sha256:" $1}'
+  else
+    echo ""
+    return 1
+  fi
+}
+
+_iwp_valid_writer() {
+  local w="$1"
+  for valid in $_IWP_WRITERS; do
+    [ "$w" = "$valid" ] && return 0
+  done
+  return 1
+}
+
+_iwp_validate_path() {
+  local p="$1"
+  # Reject path traversal (any component equal to .. OR path exactly ..)
+  case "$p" in
+    *../*|..) return 1 ;;
+  esac
+  # Reject absolute paths outside $CLAUDE_PROJECT_DIR
+  case "$p" in
+    /*)
+      local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+      case "$p" in
+        "$root"/*) ;;
+        *) return 1 ;;
+      esac
+      ;;
+  esac
+  return 0
+}
+
+_iwp_ensure_manifest() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  if [ ! -f "$mpath" ]; then
+    mkdir -p "$(dirname "$mpath")"
+    cat > "$mpath" <<EOF
+{
+  "schema_version": "$_IWP_SCHEMA_VERSION",
+  "entries": []
+}
+EOF
+  fi
+}
+
+_iwp_manifest_valid() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  [ -f "$mpath" ] || return 1
+  jq -e . "$mpath" >/dev/null 2>&1 || return 1
+  return 0
+}
+
+# ---- Public API ----
+
+# install_written_paths_register <path> <writer>
+# Records a path as install-written. Idempotent on path.
+# Returns 0 on success, 1 on validation failure.
+install_written_paths_register() {
+  local tgt="${1:-}"
+  local writer="${2:-}"
+
+  if [ -z "$tgt" ] || [ -z "$writer" ]; then
+    echo "install-written-paths: register requires <path> <writer>" >&2
+    return 1
+  fi
+
+  if ! _iwp_validate_path "$tgt"; then
+    echo "install-written-paths: path '$tgt' rejected (traversal or outside project)" >&2
+    _iwp_log "register-rejected path=$tgt reason=traversal"
+    return 1
+  fi
+
+  if ! _iwp_valid_writer "$writer"; then
+    echo "install-written-paths: writer '$writer' not in allowed enum" >&2
+    _iwp_log "register-rejected path=$tgt writer=$writer reason=unknown-writer"
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available; cannot register" >&2
+    return 1
+  fi
+
+  _iwp_ensure_manifest
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_tgt
+  case "$tgt" in
+    /*) full_tgt="$tgt" ;;
+    *) full_tgt="$root/$tgt" ;;
+  esac
+
+  local hash
+  hash=$(_iwp_sha256 "$full_tgt")
+  if [ -z "$hash" ]; then
+    echo "install-written-paths: unable to compute hash for '$full_tgt'" >&2
+    return 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Use flock to serialize writes; fall back to no-lock on BSD without flock
+  local tmp
+  tmp=$(mktemp "$mpath.tmp.XXXXXX")
+
+  if command -v flock >/dev/null 2>&1; then
+    (
+      flock -x 9
+      jq --arg path "$tgt" --arg writer "$writer" --arg ts "$now" --arg hash "$hash" \
+        '.entries |= (map(select(.path != $path)) + [{"path": $path, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+        "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+    ) 9>"$mpath.lock"
+  else
+    jq --arg path "$tgt" --arg writer "$writer" --arg ts "$now" --arg hash "$hash" \
+      '.entries |= (map(select(.path != $path)) + [{"path": $path, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+      "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+  fi
+
+  rm -f "$tmp" 2>/dev/null || true
+  _iwp_log "register path=$tgt writer=$writer"
+  return 0
+}
+
+# is_install_written_path <path>
+# Returns 0 (true) when path in manifest AND content hash matches.
+# Returns 1 (false) otherwise.
+# Override: SKIP_INSTALL_WRITTEN_PATHS=1 forces return 1 (hooks fire normally).
+is_install_written_path() {
+  if [ -n "${SKIP_INSTALL_WRITTEN_PATHS:-}" ]; then
+    _iwp_log "check override SKIP_INSTALL_WRITTEN_PATHS=1 path=${1:-}"
+    return 1
+  fi
+
+  local tgt="${1:-}"
+  if [ -z "$tgt" ]; then
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  # Fail-soft: manifest missing or malformed → not install-written
+  if ! _iwp_manifest_valid; then
+    _iwp_log "check path=$tgt result=false reason=no-manifest-or-malformed"
+    [ -f "$mpath" ] && echo "install-written-paths: manifest malformed; treating as not-install-written" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    _iwp_log "check path=$tgt result=false reason=no-jq"
+    return 1
+  fi
+
+  # Look up entry
+  local recorded_hash
+  recorded_hash=$(jq -r --arg path "$tgt" '.entries[] | select(.path == $path) | .content_hash' "$mpath" 2>/dev/null)
+  if [ -z "$recorded_hash" ] || [ "$recorded_hash" = "null" ]; then
+    _iwp_log "check path=$tgt result=false reason=not-in-manifest"
+    return 1
+  fi
+
+  # Compute current hash
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_tgt
+  case "$tgt" in
+    /*) full_tgt="$tgt" ;;
+    *) full_tgt="$root/$tgt" ;;
+  esac
+
+  if [ ! -f "$full_tgt" ]; then
+    _iwp_log "check path=$tgt result=false reason=file-missing"
+    return 1
+  fi
+
+  local current_hash
+  current_hash=$(_iwp_sha256 "$full_tgt")
+  if [ -z "$current_hash" ]; then
+    _iwp_log "check path=$tgt result=false reason=hash-fail"
+    return 1
+  fi
+
+  if [ "$recorded_hash" = "$current_hash" ]; then
+    _iwp_log "check path=$tgt result=true reason=match"
+    return 0
+  else
+    _iwp_log "check path=$tgt result=false reason=hash-mismatch"
+    return 1
+  fi
+}
+
+# install_written_paths_rename <old-path> <new-path>
+# Moves entry; preserves writer; bumps written_at.
+install_written_paths_rename() {
+  local old="${1:-}"
+  local new="${2:-}"
+
+  if [ -z "$old" ] || [ -z "$new" ]; then
+    echo "install-written-paths: rename requires <old-path> <new-path>" >&2
+    return 1
+  fi
+
+  if ! _iwp_validate_path "$new"; then
+    echo "install-written-paths: new path '$new' rejected" >&2
+    return 1
+  fi
+
+  if ! _iwp_manifest_valid; then
+    echo "install-written-paths: manifest missing or malformed" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available" >&2
+    return 1
+  fi
+
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  # Check old exists
+  local writer
+  writer=$(jq -r --arg path "$old" '.entries[] | select(.path == $path) | .writer' "$mpath" 2>/dev/null)
+  if [ -z "$writer" ] || [ "$writer" = "null" ]; then
+    echo "install-written-paths: '$old' not in manifest" >&2
+    return 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Compute hash from new location if it exists; else keep old hash
+  local root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+  local full_new
+  case "$new" in
+    /*) full_new="$new" ;;
+    *) full_new="$root/$new" ;;
+  esac
+
+  local new_hash
+  if [ -f "$full_new" ]; then
+    new_hash=$(_iwp_sha256 "$full_new")
+  else
+    new_hash=$(jq -r --arg path "$old" '.entries[] | select(.path == $path) | .content_hash' "$mpath")
+  fi
+
+  local tmp
+  tmp=$(mktemp "$mpath.tmp.XXXXXX")
+
+  jq --arg old "$old" --arg new "$new" --arg writer "$writer" --arg ts "$now" --arg hash "$new_hash" \
+    '.entries |= (map(select(.path != $old)) + [{"path": $new, "writer": $writer, "written_at": $ts, "content_hash": $hash}])' \
+    "$mpath" > "$tmp" && mv "$tmp" "$mpath"
+
+  rm -f "$tmp" 2>/dev/null || true
+  _iwp_log "rename old=$old new=$new"
+  return 0
+}
+
+# install_written_paths_rebuild
+# Regenerates the manifest. V1: creates empty manifest when missing.
+# Future: walks install writers' known output locations.
+install_written_paths_rebuild() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+  if [ -f "$mpath" ] && _iwp_manifest_valid; then
+    return 0
+  fi
+  rm -f "$mpath" 2>/dev/null || true
+  _iwp_ensure_manifest
+  _iwp_log "rebuild manifest=$mpath"
+  return 0
+}
+
+# install_written_paths_verify
+# Returns 0 on well-formed manifest, 1 on schema violation.
+install_written_paths_verify() {
+  local mpath
+  mpath=$(_iwp_manifest_path)
+
+  if [ ! -f "$mpath" ]; then
+    echo "install-written-paths: manifest file missing at $mpath" >&2
+    return 1
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "install-written-paths: jq not available" >&2
+    return 1
+  fi
+
+  if ! jq -e . "$mpath" >/dev/null 2>&1; then
+    echo "install-written-paths: manifest JSON malformed" >&2
+    return 1
+  fi
+
+  # Basic shape check — required top-level keys present
+  local has_version has_entries
+  has_version=$(jq -r 'has("schema_version")' "$mpath" 2>/dev/null)
+  has_entries=$(jq -r 'has("entries")' "$mpath" 2>/dev/null)
+  if [ "$has_version" != "true" ] || [ "$has_entries" != "true" ]; then
+    echo "install-written-paths: manifest missing required keys" >&2
+    return 1
+  fi
+
+  return 0
+}

package/dist/lite/lib/luminary-pick.sh

@@ -25,7 +25,7 @@
 #
 # Usage from a caller SKILL body:
 #
-#   source "${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}/lib/luminary-pick.sh"
+#   source "${BASSCLEF_DIR:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}/lib/luminary-pick.sh"
 #   CATALOG=$(luminary_pick_catalog)
 #   # then Claude reasons over $CATALOG + intent, writes JSON in-turn
 #
@@ -44,22 +44,44 @@ set -euo pipefail
 # Sort: alphabetical by slug.
 # Return: 0 on success (including empty catalog); non-zero if dir missing.
 luminary_pick_catalog() {
-  local basedir="${BASSCLEF_DIR:-$HOME/src/sunj-labs/bassclef}"
+  # Resolve basedir: BASSCLEF_DIR → CLAUDE_PROJECT_DIR → git root → pwd.
+  # cli#313 — the former fallback $HOME/src/sunj-labs/bassclef was the
+  # engineering team's own home path and failed for every adopter.
+  local basedir="${BASSCLEF_DIR:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"
   local catalog_dir="${basedir}/state/luminary-implementations"
+  local lite_catalog="${basedir}/.claude/luminaries"
 
-  if [ ! -d "$catalog_dir" ]; then
-    echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir" >&2
-    return 2
+  if [ -d "$catalog_dir" ]; then
+    (
+      shopt -s nullglob
+      set +e
+      for f in "$catalog_dir"/*.json; do
+        jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
+      done | sort -u
+    )
+    return 0
   fi
 
-  (
-    shopt -s nullglob
-    set +e
-    for f in "$catalog_dir"/*.json; do
-      jq -r '"\(.luminary_slug) (\(.primary_domain // "unknown")) — \(.name // .luminary_slug)"' "$f" 2>/dev/null || true
-    done | sort -u
-  )
-  return 0
+  # Lite-tier fallback (cli#313): read frontmatter from .claude/luminaries/*.md.
+  # Every tier ships this directory; state/luminary-implementations/ is upstream-only.
+  if [ -d "$lite_catalog" ]; then
+    (
+      shopt -s nullglob
+      set +e
+      for f in "$lite_catalog"/*.md; do
+        local slug domain name
+        slug=$(awk '/^slug:[[:space:]]/{sub(/^slug:[[:space:]]*/,""); print; exit}' "$f")
+        domain=$(awk '/^primary_domain:[[:space:]]/{sub(/^primary_domain:[[:space:]]*/,""); print; exit}' "$f")
+        name=$(awk '/^name:[[:space:]]/{sub(/^name:[[:space:]]*/,""); print; exit}' "$f")
+        [ -z "$slug" ] && continue
+        echo "${slug} (${domain:-unknown}) — ${name:-$slug}"
+      done | sort -u
+    )
+    return 0
+  fi
+
+  echo "[luminary-pick-catalog] catalog dir missing: $catalog_dir (and no .claude/luminaries/ fallback at $lite_catalog)" >&2
+  return 2
 }
 
 # Grace-window stub preserving the old function signature.

package/dist/lite/lib/preview-state.sh

@@ -49,14 +49,14 @@ ps_exists() {
 
 ps_create() {
   local slug="$1"
-  local path
-  path="$(ps_path "$slug")"
-  mkdir -p "$(dirname "$path")"
-  if [[ -f "$path" ]]; then
-    echo "ps_create: already exists: $path" >&2
+  local p
+  p="$(ps_path "$slug")"
+  mkdir -p "$(dirname "$p")"
+  if [[ -f "$p" ]]; then
+    echo "ps_create: already exists: $p" >&2
     return 1
   fi
-  cat > "$path" <<EOF
+  cat > "$p" <<EOF
 slug: ${slug}
 created: $(date -u +'%Y-%m-%dT%H:%M:%S+0000')
 current_tier: pending
@@ -73,16 +73,16 @@ EOF
 ps_get() {
   local slug="$1"
   local field="$2"
-  local path
-  path="$(ps_path "$slug")"
-  [[ -f "$path" ]] || { echo "ps_get: not-found: $path" >&2; return 1; }
+  local p
+  p="$(ps_path "$slug")"
+  [[ -f "$p" ]] || { echo "ps_get: not-found: $p" >&2; return 1; }
   awk -v f="$field" '
     $0 ~ "^" f ":" {
       sub("^" f ":[[:space:]]*", "")
       print
       exit
     }
-  ' "$path"
+  ' "$p"
 }
 
 ps_set() {
@@ -90,9 +90,9 @@ ps_set() {
   local field="$2"
   shift 2
   local value="$*"
-  local path
-  path="$(ps_path "$slug")"
-  [[ -f "$path" ]] || { echo "ps_set: not-found: $path" >&2; return 1; }
+  local p
+  p="$(ps_path "$slug")"
+  [[ -f "$p" ]] || { echo "ps_set: not-found: $p" >&2; return 1; }
   local tmp
   tmp="$(mktemp)"
   awk -v f="$field" -v v="$value" '
@@ -108,8 +108,8 @@ ps_set() {
         print f ": " v
       }
     }
-  ' "$path" > "$tmp"
-  mv "$tmp" "$path"
+  ' "$p" > "$tmp"
+  mv "$tmp" "$p"
 }
 
 ps_status() {
@@ -146,9 +146,9 @@ ps_archive() {
 ps_reset() {
   local slug="$1"
   local reason="${2:-no reason given}"
-  local path
-  path="$(ps_path "$slug")"
-  [[ -f "$path" ]] || { echo "ps_reset: not-found: $path" >&2; return 1; }
+  local p
+  p="$(ps_path "$slug")"
+  [[ -f "$p" ]] || { echo "ps_reset: not-found: $p" >&2; return 1; }
 
   local now
   now="$(date -u +'%Y-%m-%dT%H:%M:%S+0000')"
@@ -188,8 +188,8 @@ EOF
       next
     }
     { print }
-  ' "$path" > "$tmp"
-  mv "$tmp" "$path"
+  ' "$p" > "$tmp"
+  mv "$tmp" "$p"
   rm -f "$entry_file"
 
   # Reset cycle-state fields

package/dist/lite/lib/skip-env-inline-check.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# tier: lite
+# SKIP_* env-reach check for PreToolUse Bash hooks.
+#
+# Per #2036 Finding #4 — adopter report 2026-10-02.
+#
+# PreToolUse Bash hooks run in Claude Code's process env. The agent's
+# `SKIP_FOO=1 git commit ...` recipe sets FOO in the git subshell's env,
+# not the hook's env. Hooks that only read `${SKIP_FOO:-0}` miss the
+# inline override and the recipe lies to the adopter.
+#
+# This helper parses tool_input.command for inline `SKIP_FOO=1` and
+# falls back to process env. The adopter's natural recipe
+# `SKIP_FOO=1 cmd` now works regardless of harness env propagation.
+#
+# Retirement path: once Claude Code harness guarantees inline-env
+# propagation to hook subprocesses, this helper becomes redundant.
+# Comment stays as the audit trail.
+#
+# Usage:
+#   source "$CLAUDE_PROJECT_DIR/lib/skip-env-inline-check.sh"
+#   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
+#   if skip_var_set "SKIP_FOO" "$COMMAND"; then
+#     # bypass
+#     exit 0
+#   fi
+#
+# Anchors:
+#   @luminary john-ousterhout — deep module; narrow interface
+#   @luminary david-parnas — information hiding; consumer-free of mechanism
+#   @luminary alan-cooper — adopter-goal reliable override recipe
+
+# skip_var_set — return 0 if the named SKIP_* var is set to "1".
+# Checks two sources:
+#   1. Inline prefix in command string: `SKIP_FOO=1 cmd...`
+#   2. Fallback: process env `$SKIP_FOO`
+# Returns 1 otherwise.
+#
+# Args:
+#   $1 — var name (e.g., "SKIP_OPERATOR_PATHS")
+#   $2 — command string (from tool_input.command)
+skip_var_set() {
+  local var_name="$1"
+  local cmd="$2"
+
+  # Source 1 — inline prefix. The pattern anchors on word boundary (start
+  # of string or whitespace) and requires =1 followed by whitespace or
+  # end-of-string. This matches bash's own parsing of inline env prefix.
+  if [ -n "$cmd" ]; then
+    if echo "$cmd" | grep -qE "(^|[[:space:]])${var_name}=1([[:space:]]|$)"; then
+      return 0
+    fi
+  fi
+
+  # Source 2 — process env fallback (works where harness propagates env).
+  if [ "$(eval "echo \"\${${var_name}:-0}\"")" = "1" ]; then
+    return 0
+  fi
+
+  return 1
+}