refactor(pins): move version pins from catalog files to user-local config

CybotTM · CybotTM · commit 817d2353d72b · 2026-02-15T18:44:12.000+01:00
Version pins are personal preferences that don't belong in git-tracked
catalog files. This moves them to ~/.config/cli-audit/pins.json, matching
the pattern already used by auto_update preferences in config.yml.

- Add scripts/lib/pins.sh shared library for all pin read/write operations
- Update pin_version.sh, unpin_version.sh, reset_pins.sh to use pins.sh
- Update catalog.sh pin-reading functions to delegate to pins.sh
- Update guide.sh pin checks to read from pins.json
- Remove pinned_version/pinned_versions fields from all catalog/*.json
- Migrate existing pin values to ~/.config/cli-audit/pins.json
diff --git a/catalog/git-branchless.json b/catalog/git-branchless.json
@@ -11,6 +11,5 @@
     "x86_64": "x86_64-unknown-linux-musl"
   },
   "notes": "Only x86_64 Linux builds available. KNOWN ISSUE: v0.10.0 release binary incorrectly reports version 0.9.0 - this is an upstream packaging bug, not an installer issue.",
-  "known_issues": "v0.10.0 release binary reports version 0.9.0 (upstream packaging bug). Upgrade will appear to fail. Wait for v0.10.1+ or build from source.",
-  "pinned_version": "0.10.0"
+  "known_issues": "v0.10.0 release binary reports version 0.9.0 (upstream packaging bug). Upgrade will appear to fail. Wait for v0.10.1+ or build from source."
 }
diff --git a/catalog/go.json b/catalog/go.json
@@ -27,8 +27,5 @@
       "go.mod"
     ]
   },
-  "notes": "Go supports 2 versions (current + previous). Uses goenv if available, otherwise single system install.",
-  "pinned_versions": {
-    "1.24": "never"
-  }
+  "notes": "Go supports 2 versions (current + previous). Uses goenv if available, otherwise single system install."
 }
diff --git a/catalog/node.json b/catalog/node.json
@@ -28,8 +28,5 @@
       "package.json"
     ]
   },
-  "notes": "Managed via nvm (Node Version Manager). Supports multiple concurrent LTS versions.",
-  "pinned_versions": {
-    "22": "never"
-  }
+  "notes": "Managed via nvm (Node Version Manager). Supports multiple concurrent LTS versions."
 }
diff --git a/catalog/php.json b/catalog/php.json
@@ -34,8 +34,5 @@
       "composer.json"
     ]
   },
-  "notes": "Uses ondrej/php PPA for latest PHP version on Ubuntu/Debian. Required for Composer. Supports multiple concurrent versions (8.5, 8.4, 8.3, 8.2).",
-  "pinned_versions": {
-    "8.2": "never"
-  }
+  "notes": "Uses ondrej/php PPA for latest PHP version on Ubuntu/Debian. Required for Composer. Supports multiple concurrent versions (8.5, 8.4, 8.3, 8.2)."
 }
diff --git a/catalog/pip.json b/catalog/pip.json
@@ -12,6 +12,5 @@
     "dnf": "python3-pip",
     "pacman": "python-pip"
   },
-  "notes": "pip typically comes with Python 3. Use python3 -m pip if pip command is not available.",
-  "pinned_version": "never"
+  "notes": "pip typically comes with Python 3. Use python3 -m pip if pip command is not available."
 }
diff --git a/catalog/pipx.json b/catalog/pipx.json
@@ -11,6 +11,5 @@
     "brew": "pipx",
     "dnf": "pipx",
     "pacman": "python-pipx"
-  },
-  "pinned_version": "never"
+  }
 }
diff --git a/catalog/python.json b/catalog/python.json
@@ -28,9 +28,5 @@
       "pyproject.toml",
       ".tool-versions"
     ]
-  },
-  "pinned_versions": {
-    "3.11": "never",
-    "3.10": "never"
   }
 }
diff --git a/catalog/ruby.json b/catalog/ruby.json
@@ -26,9 +26,5 @@
       "Gemfile"
     ]
   },
-  "notes": "Managed via rbenv for version management. Supports multiple concurrent versions.",
-  "pinned_versions": {
-    "3.4": "never",
-    "3.3": "never"
-  }
+  "notes": "Managed via rbenv for version management. Supports multiple concurrent versions."
 }
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
@@ -49,6 +49,7 @@
 **Shared utilities:** `scripts/lib/` directory (10 modules):
 - `lib/common.sh` — Logging and output formatting
 - `lib/config.sh` — Read user config from `~/.config/cli-audit/config.yml`
+- `lib/pins.sh` — Read/write version pins from `~/.config/cli-audit/pins.json`
 - `lib/catalog.sh` — Catalog access utilities
 - `lib/capability.sh`, `lib/dependency.sh` — Capability and dependency checks
 - `lib/install_strategy.sh`, `lib/reconcile.sh` — Installation strategies
diff --git a/scripts/guide.sh b/scripts/guide.sh
@@ -26,6 +26,9 @@ done
 # Load catalog query functions
 . "$DIR/lib/catalog.sh"
 
+# Load pin library (user-local version pins)
+. "$DIR/lib/pins.sh"
+
 # Load config query functions (for user preferences like auto_update)
 . "$DIR/lib/config.sh"
 
@@ -410,11 +413,9 @@ process_tool() {
         fi
       else
         # Upgrade succeeded - remove any existing pin to avoid stale pins
-        if catalog_has_tool "$tool"; then
-          local existing_pin="$(catalog_get_property "$tool" pinned_version)"
-          if [ -n "$existing_pin" ] && [ "$existing_pin" != "never" ]; then
-            "$ROOT"/scripts/unpin_version.sh "$tool" || true
-          fi
+        local existing_pin="$(pins_get "$tool")"
+        if [ -n "$existing_pin" ] && [ "$existing_pin" != "never" ]; then
+          "$ROOT"/scripts/unpin_version.sh "$tool" || true
         fi
       fi
       ;;
@@ -459,11 +460,9 @@ process_tool() {
       else
         printf "    ✓ Auto-update enabled. This tool will update automatically in future.\n"
         # Remove any existing pin
-        if catalog_has_tool "$tool"; then
-          local existing_pin_a="$(catalog_get_property "$tool" pinned_version)"
-          if [ -n "$existing_pin_a" ]; then
-            "$ROOT"/scripts/unpin_version.sh "$tool" || true
-          fi
+        local existing_pin_a="$(pins_get "$tool")"
+        if [ -n "$existing_pin_a" ]; then
+          "$ROOT"/scripts/unpin_version.sh "$tool" || true
         fi
       fi
       ;;
@@ -741,20 +740,20 @@ while read -r line; do
       continue
     fi
 
-    # Check if tool is pinned (use catalog name for pin check)
+    # Check if tool is pinned (read from user-local pins file)
     # Skip pin checks if IGNORE_PINS=1
     if [ "$IGNORE_PINS" != "1" ]; then
-      pinned_version="$(catalog_get_property "$catalog_name" pinned_version)"
+      pinned_version="$(pins_get "$catalog_name")"
 
-      # For multi-version tools, check pinned_versions object AND base tool pin
+      # For multi-version tools, check cycle-specific pin AND base tool pin
       if [ -n "$is_multi_version" ]; then
         # First check if the BASE tool (e.g., php) is pinned to "never" - skip ALL versions
         if [ "$pinned_version" = "never" ]; then
           continue
         fi
         # Then check version-specific pin
         version_cycle="${tool_name##*@}"
-        multi_pin="$(catalog_get_pinned_version "$catalog_name" "$version_cycle")"
+        multi_pin="$(pins_get_cycle "$catalog_name" "$version_cycle")"
         if [ "$multi_pin" = "never" ]; then
           continue
         fi
diff --git a/scripts/lib/catalog.sh b/scripts/lib/catalog.sh
@@ -57,19 +57,34 @@ catalog_get_property() {
 }
 
 # Get pinned version for a specific version cycle (multi-version tools)
+# Reads from user-local pins file, not catalog
 catalog_get_pinned_version() {
   local tool="$1"
   local version_cycle="$2"
-  local catalog_dir="$ROOT/catalog"
 
-  if ! command -v jq >/dev/null 2>&1; then
-    return
+  # Source pins library if not already loaded
+  if ! type pins_get_cycle &>/dev/null; then
+    local lib_dir
+    lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    . "$lib_dir/pins.sh"
   fi
 
-  local json="$catalog_dir/$tool.json"
-  if [ -f "$json" ]; then
-    jq -r --arg cycle "$version_cycle" '.pinned_versions[$cycle] // empty' "$json"
+  pins_get_cycle "$tool" "$version_cycle"
+}
+
+# Get pin for a single-version tool
+# Reads from user-local pins file, not catalog
+catalog_get_pin() {
+  local tool="$1"
+
+  # Source pins library if not already loaded
+  if ! type pins_get &>/dev/null; then
+    local lib_dir
+    lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    . "$lib_dir/pins.sh"
   fi
+
+  pins_get "$tool"
 }
 
 # Check if tool is deprecated
diff --git a/scripts/lib/pins.sh b/scripts/lib/pins.sh
@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# pins.sh - Shared library for reading/writing version pins
+#
+# Pins are stored in a user-local JSON file, not in git-tracked catalog files.
+# Format:
+#   Single-version tools: {"tool": "version"} or {"tool": "never"}
+#   Multi-version tools:  {"tool": {"cycle": "version"}}
+#
+# Usage:
+#   source "$DIR/lib/pins.sh"
+#   pins_set "prettier" "3.5.0"
+#   pins_get "prettier"               # → "3.5.0"
+#   pins_set_cycle "python" "3.12" "never"
+#   pins_get_cycle "python" "3.12"    # → "never"
+
+PINS_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/cli-audit/pins.json"
+
+# Ensure the pins file exists (creates directory and empty JSON object if needed)
+_pins_ensure_file() {
+    if [ ! -f "$PINS_FILE" ]; then
+        mkdir -p "$(dirname "$PINS_FILE")"
+        echo '{}' > "$PINS_FILE"
+    fi
+}
+
+# Get pin for a single-version tool
+# Returns: version string, "never", or empty if not pinned
+pins_get() {
+    local tool="$1"
+    [ ! -f "$PINS_FILE" ] && return 0
+    local val
+    val="$(jq -r --arg t "$tool" '.[$t] // empty' "$PINS_FILE" 2>/dev/null)"
+    # If the value is an object (multi-version), return empty — use pins_get_cycle instead
+    if [ -n "$val" ] && echo "$val" | jq -e 'type == "object"' >/dev/null 2>&1; then
+        return 0
+    fi
+    echo "$val"
+}
+
+# Get pin for a specific version cycle of a multi-version tool
+# Returns: version string, "never", or empty if not pinned
+pins_get_cycle() {
+    local tool="$1"
+    local cycle="$2"
+    [ ! -f "$PINS_FILE" ] && return 0
+    jq -r --arg t "$tool" --arg c "$cycle" '.[$t][$c] // empty' "$PINS_FILE" 2>/dev/null
+}
+
+# Set pin for a single-version tool
+pins_set() {
+    local tool="$1"
+    local version="$2"
+    _pins_ensure_file
+    local tmp
+    tmp=$(mktemp)
+    jq --arg t "$tool" --arg v "$version" '.[$t] = $v' "$PINS_FILE" > "$tmp"
+    mv "$tmp" "$PINS_FILE"
+}
+
+# Set pin for a specific version cycle of a multi-version tool
+pins_set_cycle() {
+    local tool="$1"
+    local cycle="$2"
+    local version="$3"
+    _pins_ensure_file
+    local tmp
+    tmp=$(mktemp)
+    jq --arg t "$tool" --arg c "$cycle" --arg v "$version" \
+        '.[$t] = ((.[$t] // {}) + {($c): $v})' "$PINS_FILE" > "$tmp"
+    mv "$tmp" "$PINS_FILE"
+}
+
+# Remove pin for a single-version tool
+pins_remove() {
+    local tool="$1"
+    [ ! -f "$PINS_FILE" ] && return 0
+    local tmp
+    tmp=$(mktemp)
+    jq --arg t "$tool" 'del(.[$t])' "$PINS_FILE" > "$tmp"
+    mv "$tmp" "$PINS_FILE"
+}
+
+# Remove pin for a specific version cycle, cleaning up empty objects
+pins_remove_cycle() {
+    local tool="$1"
+    local cycle="$2"
+    [ ! -f "$PINS_FILE" ] && return 0
+    local tmp
+    tmp=$(mktemp)
+    jq --arg t "$tool" --arg c "$cycle" \
+        'del(.[$t][$c]) | if .[$t] == {} then del(.[$t]) else . end' \
+        "$PINS_FILE" > "$tmp"
+    mv "$tmp" "$PINS_FILE"
+}
+
+# Clear all pins
+pins_reset_all() {
+    _pins_ensure_file
+    echo '{}' > "$PINS_FILE"
+}
+
+# List all pins (dump JSON for display)
+pins_list() {
+    [ ! -f "$PINS_FILE" ] && { echo '{}'; return 0; }
+    jq '.' "$PINS_FILE" 2>/dev/null || echo '{}'
+}
diff --git a/scripts/pin_version.sh b/scripts/pin_version.sh
@@ -5,6 +5,9 @@ set -euo pipefail
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$DIR/.." && pwd)"
 
+# Load pin library
+. "$DIR/lib/pins.sh"
+
 TOOL="${1:-}"
 VERSION="${2:-}"
 
@@ -67,12 +70,8 @@ fi
 if [ -n "$IS_MULTI_VERSION" ]; then
   echo "Pinning '$TOOL' (version cycle $VERSION_CYCLE) to: $VERSION..."
 
-  # Update catalog with pinned_versions object
-  TMP_FILE=$(mktemp)
-  jq --arg cycle "$VERSION_CYCLE" --arg version "$VERSION" \
-    '.pinned_versions = ((.pinned_versions // {}) + {($cycle): $version})' \
-    "$CATALOG_FILE" > "$TMP_FILE"
-  mv "$TMP_FILE" "$CATALOG_FILE"
+  # Store pin in user-local pins file
+  pins_set_cycle "$BASE_TOOL" "$VERSION_CYCLE" "$VERSION"
 
   echo "✓ Pinned '$TOOL' to: $VERSION"
   echo ""
@@ -86,10 +85,8 @@ if [ -n "$IS_MULTI_VERSION" ]; then
 else
   echo "Pinning '$TOOL' to version $VERSION..."
 
-  # Update catalog with pinned_version field
-  TMP_FILE=$(mktemp)
-  jq --arg version "$VERSION" '. + {pinned_version: $version}' "$CATALOG_FILE" > "$TMP_FILE"
-  mv "$TMP_FILE" "$CATALOG_FILE"
+  # Store pin in user-local pins file
+  pins_set "$BASE_TOOL" "$VERSION"
 
   echo "✓ Pinned '$TOOL' to version $VERSION"
   echo ""
diff --git a/scripts/reset_pins.sh b/scripts/reset_pins.sh
@@ -3,42 +3,28 @@
 set -euo pipefail
 
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ROOT="$(cd "$DIR/.." && pwd)"
 
-echo "Resetting all version pins..."
-
-count=0
-for catalog_file in "$ROOT"/catalog/*.json; do
-  [ -f "$catalog_file" ] || continue
-  tool_name="$(basename "$catalog_file" .json)"
+# Load pin library
+. "$DIR/lib/pins.sh"
 
-  # Check for pinned_version
-  pinned="$(jq -r '.pinned_version // empty' "$catalog_file")"
-  if [ -n "$pinned" ]; then
-    echo "  Removing pin from $tool_name (was: $pinned)"
-    TMP_FILE=$(mktemp)
-    jq 'del(.pinned_version)' "$catalog_file" > "$TMP_FILE"
-    mv "$TMP_FILE" "$catalog_file"
-    ((count++)) || true
-  fi
+echo "Resetting all version pins..."
 
-  # Check for pinned_versions (multi-version pins)
-  has_pinned_versions="$(jq -r 'if .pinned_versions then "yes" else empty end' "$catalog_file")"
-  if [ -n "$has_pinned_versions" ]; then
-    versions="$(jq -r '.pinned_versions | keys | join(", ")' "$catalog_file")"
-    echo "  Removing multi-version pins from $tool_name (cycles: $versions)"
-    TMP_FILE=$(mktemp)
-    jq 'del(.pinned_versions)' "$catalog_file" > "$TMP_FILE"
-    mv "$TMP_FILE" "$catalog_file"
-    ((count++)) || true
+# Show what's being removed
+if [ -f "$PINS_FILE" ]; then
+  current="$(jq -r 'to_entries[] | if (.value | type) == "object" then "\(.key): \(.value | to_entries | map("\(.key)=\(.value)") | join(", "))" else "\(.key): \(.value)" end' "$PINS_FILE" 2>/dev/null)"
+  if [ -n "$current" ]; then
+    while IFS= read -r line; do
+      echo "  Removing pin: $line"
+    done <<< "$current"
+    echo ""
+    pins_reset_all
+    echo "✓ All pins removed"
+  else
+    echo "No pins found."
   fi
-done
-
-if [ $count -eq 0 ]; then
-  echo "No pins found."
 else
-  echo ""
-  echo "✓ Reset $count tool(s)"
-  echo ""
-  echo "All tools will now appear in upgrade prompts."
+  echo "No pins found."
 fi
+
+echo ""
+echo "All tools will now appear in upgrade prompts."
diff --git a/scripts/unpin_version.sh b/scripts/unpin_version.sh

Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,5 @@`
`11`	`11`	`"x86_64": "x86_64-unknown-linux-musl"`
`12`	`12`	`},`
`13`	`13`	`"notes": "Only x86_64 Linux builds available. KNOWN ISSUE: v0.10.0 release binary incorrectly reports version 0.9.0 - this is an upstream packaging bug, not an installer issue.",`
`14`		`- "known_issues": "v0.10.0 release binary reports version 0.9.0 (upstream packaging bug). Upgrade will appear to fail. Wait for v0.10.1+ or build from source.",`
`15`		`- "pinned_version": "0.10.0"`
	`14`	`+ "known_issues": "v0.10.0 release binary reports version 0.9.0 (upstream packaging bug). Upgrade will appear to fail. Wait for v0.10.1+ or build from source."`
`16`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -27,8 +27,5 @@`
`27`	`27`	`"go.mod"`
`28`	`28`	`]`
`29`	`29`	`},`
`30`		`- "notes": "Go supports 2 versions (current + previous). Uses goenv if available, otherwise single system install.",`
`31`		`- "pinned_versions": {`
`32`		`- "1.24": "never"`
`33`		`- }`
	`30`	`+ "notes": "Go supports 2 versions (current + previous). Uses goenv if available, otherwise single system install."`
`34`	`31`	`}`
Original file line number	Diff line number	Diff line change
`@@ -28,8 +28,5 @@`
`28`	`28`	`"package.json"`
`29`	`29`	`]`
`30`	`30`	`},`
`31`		`- "notes": "Managed via nvm (Node Version Manager). Supports multiple concurrent LTS versions.",`
`32`		`- "pinned_versions": {`
`33`		`- "22": "never"`
`34`		`- }`
	`31`	`+ "notes": "Managed via nvm (Node Version Manager). Supports multiple concurrent LTS versions."`
`35`	`32`	`}`
Original file line number	Diff line number	Diff line change
`@@ -34,8 +34,5 @@`
`34`	`34`	`"composer.json"`
`35`	`35`	`]`
`36`	`36`	`},`
`37`		`- "notes": "Uses ondrej/php PPA for latest PHP version on Ubuntu/Debian. Required for Composer. Supports multiple concurrent versions (8.5, 8.4, 8.3, 8.2).",`
`38`		`- "pinned_versions": {`
`39`		`- "8.2": "never"`
`40`		`- }`
	`37`	`+ "notes": "Uses ondrej/php PPA for latest PHP version on Ubuntu/Debian. Required for Composer. Supports multiple concurrent versions (8.5, 8.4, 8.3, 8.2)."`
`41`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,5 @@`
`12`	`12`	`"dnf": "python3-pip",`
`13`	`13`	`"pacman": "python-pip"`
`14`	`14`	`},`
`15`		`- "notes": "pip typically comes with Python 3. Use python3 -m pip if pip command is not available.",`
`16`		`- "pinned_version": "never"`
	`15`	`+ "notes": "pip typically comes with Python 3. Use python3 -m pip if pip command is not available."`
`17`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -28,9 +28,5 @@`
`28`	`28`	`"pyproject.toml",`
`29`	`29`	`".tool-versions"`
`30`	`30`	`]`
`31`		`- },`
`32`		`- "pinned_versions": {`
`33`		`- "3.11": "never",`
`34`		`- "3.10": "never"`
`35`	`31`	`}`
`36`	`32`	`}`
Original file line number	Diff line number	Diff line change
`@@ -26,9 +26,5 @@`
`26`	`26`	`"Gemfile"`
`27`	`27`	`]`
`28`	`28`	`},`
`29`		`- "notes": "Managed via rbenv for version management. Supports multiple concurrent versions.",`
`30`		`- "pinned_versions": {`
`31`		`- "3.4": "never",`
`32`		`- "3.3": "never"`
`33`		`- }`
	`29`	`+ "notes": "Managed via rbenv for version management. Supports multiple concurrent versions."`
`34`	`30`	`}`