jekyll-theme-zer0 1.27.0 → 1.28.0

data/scripts/install/config.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/config.sh — User config-file layer
+# =============================================================================
+# Lets a site persist its installer choices in a small YAML file instead of
+# re-typing flags every run. Discovered files are merged low→high precedence:
+#
+#   1. ~/.config/zer0/install.yml        (user-global defaults)
+#   2. <target>/zer0.install.yml         (project-local)
+#   3. <target>/.zer0/config.yml         (project-local, hidden)
+#   4. $ZER0_CONFIG  /  --config FILE    (explicit — wins over the rest)
+#
+# In the plan pipeline this sits between profile defaults and env/flag
+# overrides:  defaults < profile < CONFIG FILE < env vars < CLI flags.
+#
+# Recognised keys (nested or flat/dotted both work):
+#   profile
+#   site.title|description|author|email|url|timezone|locale
+#   github.user|repo|pages_branch|enable_pages
+#   theme.source|version
+#   deploy            (scalar or list → space-joined)
+#   agents            (scalar or list → space-joined)
+#   tasks             (scalar or list → space-joined)
+#   ai.provider       (auto|claude-cli|anthropic|openai|none)
+#   ai.model
+#
+# API keys are deliberately NOT read from config files — they stay in the
+# environment only (see ai/client.sh).
+#
+# Bash 3.2 compatible. No `declare -A`, no `set -euo pipefail` here.
+# =============================================================================
+[[ -n "${_HAS_CONFIG_LIB:-}" ]] && return 0
+_HAS_CONFIG_LIB=1
+
+# ---------------------------------------------------------------------------
+# config_discover TARGET_DIR → print existing config files, low→high priority.
+# ---------------------------------------------------------------------------
+config_discover() {
+    local target="${1:-$(pwd)}"
+    local f
+    for f in \
+        "${HOME:-/nonexistent}/.config/zer0/install.yml" \
+        "${target}/zer0.install.yml" \
+        "${target}/zer0.install.yaml" \
+        "${target}/.zer0/config.yml" \
+        "${_FLAG_CONFIG:-}" \
+        "${ZER0_CONFIG:-}" ; do
+        [[ -n "$f" && -f "$f" ]] && printf '%s\n' "$f"
+    done
+}
+
+# ---------------------------------------------------------------------------
+# _config_flatten FILE → emit `key=value` for a small YAML subset:
+#   - top-level scalars           foo: bar          → foo=bar
+#   - one level of nested maps     site:\n  title: x → site.title=x
+#   - block lists                  deploy:\n  - a    → deploy=a b
+#   - inline flow lists            deploy: [a, b]    → deploy=a b
+# Quotes and inline comments are stripped. Not a full YAML parser — just
+# enough for installer config, mirroring plan.sh's awk profile reader.
+# ---------------------------------------------------------------------------
+_config_flatten() {
+    local file="$1"
+    [[ -f "$file" ]] || return 0
+    awk '
+        function strip(s) {
+            sub(/[[:space:]]*#.*$/, "", s)               # trailing comment
+            sub(/^[[:space:]]+/, "", s); sub(/[[:space:]]+$/, "", s)
+            gsub(/^["'"'"']|["'"'"']$/, "", s)           # surrounding quotes
+            return s
+        }
+        # blank / comment lines
+        /^[[:space:]]*$/ { next }
+        /^[[:space:]]*#/ { next }
+        {
+            indent = 0
+            tmp = $0
+            while (substr(tmp,1,1) == " ") { indent++; tmp = substr(tmp,2) }
+        }
+        # list item under the current parent key
+        indent > 0 && tmp ~ /^-[[:space:]]+/ {
+            if (listkey != "") {
+                item = tmp; sub(/^-[[:space:]]+/, "", item); item = strip(item)
+                vals[listkey] = (vals[listkey] == "" ? item : vals[listkey] " " item)
+            }
+            next
+        }
+        # key: value  (any depth we care about is 0 or 1)
+        match(tmp, /^[A-Za-z0-9_.-]+[[:space:]]*:/) {
+            key = tmp; sub(/[[:space:]]*:.*$/, "", key)
+            val = tmp; sub(/^[A-Za-z0-9_.-]+[[:space:]]*:/, "", val); val = strip(val)
+
+            if (indent == 0) {
+                parent = key
+                listkey = ""
+                if (val == "") { listkey = key; next }        # map/list header
+                # inline flow list?  key: [a, b, c]
+                if (val ~ /^\[.*\]$/) {
+                    gsub(/^\[|\]$/, "", val); gsub(/[[:space:],]+/, " ", val)
+                    val = strip(val)
+                }
+                print key "=" val
+            } else {
+                # nested child of the last top-level parent
+                if (parent != "") print parent "." key "=" val
+            }
+            next
+        }
+        END {
+            for (k in vals) print k "=" vals[k]
+        }
+    ' "$file"
+}
+
+# ---------------------------------------------------------------------------
+# config_apply_file FILE → map recognised keys onto SPEC_* globals + AI env.
+# ---------------------------------------------------------------------------
+config_apply_file() {
+    local file="$1"
+    [[ -f "$file" ]] || return 0
+    log_debug "config: loading ${file}"
+
+    local line key val
+    while IFS= read -r line; do
+        key="${line%%=*}"
+        val="${line#*=}"
+        [[ -z "$key" || "$key" == "$line" ]] && continue
+        case "$key" in
+            profile)              SPEC_PROFILE="$val" ;;
+            site.title|site_title)             SPEC_SITE_TITLE="$val" ;;
+            site.description|site_description) SPEC_SITE_DESCRIPTION="$val" ;;
+            site.author|site_author)           SPEC_SITE_AUTHOR="$val" ;;
+            site.email|site_email)             SPEC_SITE_EMAIL="$val" ;;
+            site.url|site_url)                 SPEC_SITE_URL="$val" ;;
+            site.timezone|site_timezone)       SPEC_SITE_TIMEZONE="$val" ;;
+            site.locale|site_locale)           SPEC_SITE_LOCALE="$val" ;;
+            github.user|github_user)           SPEC_GITHUB_USER="$val" ;;
+            github.repo|github_repo)           SPEC_GITHUB_REPO="$val" ;;
+            github.pages_branch)               SPEC_GITHUB_PAGES_BRANCH="$val" ;;
+            github.enable_pages)               SPEC_GITHUB_ENABLE_PAGES="$val" ;;
+            theme.source|theme_source)         SPEC_THEME_SOURCE="$val" ;;
+            theme.version|theme_version)       SPEC_THEME_VERSION="$val" ;;
+            deploy|deploy_targets)             SPEC_DEPLOY="$val" ;;
+            agents|agent_files)                SPEC_AGENTS="$val" ;;
+            tasks)                             SPEC_TASKS="$val" ;;
+            ai.provider|ai_provider)
+                SPEC_AI_PROVIDER="$val"
+                export ZER0_AI_PROVIDER="${ZER0_AI_PROVIDER:-$val}" ;;
+            ai.model|ai_model)
+                SPEC_AI_MODEL="$val"
+                export ZER0_AI_MODEL="${ZER0_AI_MODEL:-$val}" ;;
+            *) log_debug "config: ignoring unknown key '${key}'" ;;
+        esac
+    done < <(_config_flatten "$file")
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# config_load TARGET_DIR → apply every discovered config file in order.
+# ---------------------------------------------------------------------------
+config_load() {
+    local target="${1:-$(pwd)}"
+    local f
+    while IFS= read -r f; do
+        [[ -n "$f" ]] && config_apply_file "$f"
+    done < <(config_discover "$target")
+    return 0
+}

data/scripts/install/doctor.sh

@@ -118,6 +118,43 @@ doctor_check_gh() {
     _doctor_pass "GitHub CLI $ghver"
 }
 
+# ---------------------------------------------------------------------------
+# doctor_check_ai — report which AI provider (if any) will serve wizard/
+# suggest/diagnose. Warn-only: AI is always opt-in and never blocks install.
+# ---------------------------------------------------------------------------
+doctor_check_ai() {
+    if [[ "$(type -t ai_client_provider)" != "function" ]]; then
+        local _d
+        _d="${_CLI_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd)}"
+        [[ -f "${_d}/ai/client.sh" ]] && source "${_d}/ai/client.sh"
+    fi
+    if [[ "$(type -t ai_client_provider)" != "function" ]]; then
+        _doctor_warn "AI: client module unavailable (wizard/suggest/diagnose disabled)"
+        return 0
+    fi
+
+    if [[ "${ZER0_NO_AI:-0}" == "1" ]]; then
+        _doctor_pass "AI: disabled via ZER0_NO_AI (rule-based fallbacks only)"
+        return 0
+    fi
+    case "${ZER0_AI_PROVIDER:-}" in
+        none|off|disabled)
+            _doctor_pass "AI: disabled by choice (rule-based fallbacks only)"
+            return 0 ;;
+    esac
+
+    local provider
+    provider="$(ai_client_provider)"
+    if [[ "$provider" == "none" ]] || ! ai_client_available; then
+        _doctor_warn "AI: no provider available — install the 'claude' CLI (Claude Code OAuth), or set CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY / OPENAI_API_KEY"
+        return 0
+    fi
+
+    local model
+    model="$(ai_client_model "$provider")"
+    _doctor_pass "AI: ${provider} via $(ai_client_auth_source)${model:+ (model ${model})}"
+}
+
 # ---------------------------------------------------------------------------
 # doctor_check_writable TARGET_DIR
 # ---------------------------------------------------------------------------
@@ -155,6 +192,7 @@ doctor_run() {
     doctor_check_docker
     doctor_check_git      || failures=$(( failures + 1 ))
     doctor_check_gh
+    doctor_check_ai
     [[ -n "$target" ]] && { doctor_check_writable "$target" || failures=$(( failures + 1 )); }
 
     if [[ $failures -eq 0 ]]; then

data/scripts/install/plan.sh

@@ -144,6 +144,8 @@ plan_apply_flags() {
     [[ -n "${_FLAG_DEPLOY:-}" ]]      && SPEC_DEPLOY="$_FLAG_DEPLOY"
     [[ -n "${_FLAG_AGENTS:-}" ]]      && SPEC_AGENTS="$_FLAG_AGENTS"
     [[ -n "${_FLAG_TASKS:-}" ]]       && SPEC_TASKS="$_FLAG_TASKS"
+    [[ -n "${_FLAG_AI_PROVIDER:-}" ]] && SPEC_AI_PROVIDER="$_FLAG_AI_PROVIDER"
+    [[ -n "${_FLAG_AI_MODEL:-}" ]]    && SPEC_AI_MODEL="$_FLAG_AI_MODEL"
 
     # Booleans — flags are set to "1" when present
     [[ "${_FLAG_DRY_RUN:-0}" == "1" ]]     && SPEC_OPT_DRY_RUN=true
@@ -231,12 +233,19 @@ plan_build() {
     # Layer 1: Profile defaults
     [[ -n "$profile_file" ]] && plan_load_profile "$profile_file"
 
+    # Layer 1.5: User config file(s) — override profile, sit below env/flags.
+    if [[ "$(type -t config_load)" == "function" ]]; then
+        config_load "$target_dir"
+    fi
+
     # Layer 2: Environment variable overrides (ZER0_SITE_* etc.)
     [[ -n "${ZER0_SITE_TITLE:-}" ]]  && SPEC_SITE_TITLE="$ZER0_SITE_TITLE"
     [[ -n "${ZER0_SITE_AUTHOR:-}" ]] && SPEC_SITE_AUTHOR="$ZER0_SITE_AUTHOR"
     [[ -n "${ZER0_SITE_EMAIL:-}" ]]  && SPEC_SITE_EMAIL="$ZER0_SITE_EMAIL"
     [[ -n "${ZER0_GITHUB_USER:-}" ]] && SPEC_GITHUB_USER="$ZER0_GITHUB_USER"
     [[ -n "${ZER0_GITHUB_REPO:-}" ]] && SPEC_GITHUB_REPO="$ZER0_GITHUB_REPO"
+    [[ -n "${ZER0_AI_PROVIDER:-}" ]] && SPEC_AI_PROVIDER="$ZER0_AI_PROVIDER"
+    [[ -n "${ZER0_AI_MODEL:-}" ]]    && SPEC_AI_MODEL="$ZER0_AI_MODEL"
 
     # Layer 3: CLI flags (highest priority)
     plan_apply_flags
@@ -271,6 +280,7 @@ plan_build() {
         SPEC_OPT_DRY_RUN SPEC_OPT_FORCE SPEC_OPT_BACKUP \
         SPEC_OPT_NON_INTERACTIVE SPEC_OPT_OUTPUT SPEC_OPT_AUTO_ACCEPT \
         SPEC_OPT_SKIP_DOCTOR SPEC_OPT_VERBOSE \
+        SPEC_AI_PROVIDER SPEC_AI_MODEL \
         SITE_TITLE SITE_DESCRIPTION SITE_AUTHOR SITE_EMAIL SITE_URL \
         SITE_TIMEZONE SITE_LOCALE GITHUB_USER GITHUB_REPO \
         GITHUB_PAGES_BRANCH THEME_SOURCE REPOSITORY_NAME INSTALL_PROFILE

data/scripts/install/spec.sh

@@ -85,7 +85,7 @@ spec_default() {
   },
   "ai": {
     "used": false,
-    "provider": "openai",
+    "provider": "auto",
     "model": "",
     "tokens_estimated": 0,
     "spec_hash": ""
@@ -108,10 +108,18 @@ spec_write() {
     local out_file="$1"
     local dry_run="${_FS_DRY_RUN:-0}"
 
-    # Build tasks array from space-separated SPEC_TASKS
+    # Build tasks array from space-separated SPEC_TASKS.
+    # Distinguish UNSET (→ default task list) from EMPTY (→ [], e.g. a
+    # deploy-only run). Using `${SPEC_TASKS:-default}` here would turn an
+    # intentional empty list back into the full default and clobber content.
     local tasks_json=""
-    local t
-    for t in ${SPEC_TASKS:-config gemfile docker pages nav data gitignore readme marker}; do
+    local t _tasks_src
+    if [[ -z "${SPEC_TASKS+set}" ]]; then
+        _tasks_src="config gemfile docker pages nav data gitignore readme marker"
+    else
+        _tasks_src="${SPEC_TASKS}"
+    fi
+    for t in ${_tasks_src}; do
         tasks_json="${tasks_json}\"${t}\","
     done
     tasks_json="[${tasks_json%,}]"
@@ -168,7 +176,7 @@ spec_write() {
   },
   "ai": {
     "used": ${SPEC_AI_USED:-false},
-    "provider": "${SPEC_AI_PROVIDER:-openai}",
+    "provider": "${SPEC_AI_PROVIDER:-auto}",
     "model": "${SPEC_AI_MODEL:-}",
     "tokens_estimated": ${SPEC_AI_TOKENS:-0},
     "spec_hash": ""
@@ -248,7 +256,7 @@ _spec_read_jq() {
     SPEC_OPT_SKIP_DOCTOR=$(jq -r '.options.skip_doctor // false' "$f")
     SPEC_OPT_VERBOSE=$(jq -r '.options.verbose // false' "$f")
     SPEC_AI_USED=$(jq -r '.ai.used // false' "$f")
-    SPEC_AI_PROVIDER=$(jq -r '.ai.provider // "openai"' "$f")
+    SPEC_AI_PROVIDER=$(jq -r '.ai.provider // "auto"' "$f")
     SPEC_AI_MODEL=$(jq -r '.ai.model // ""' "$f")
     SPEC_AI_TOKENS=$(jq -r '.ai.tokens_estimated // 0' "$f")
     SPEC_SCRAPE_SOURCE_URL=$(jq -r '.scrape.source_url // ""' "$f")
@@ -369,7 +377,7 @@ _spec_read_awk() {
     SPEC_OPT_SKIP_DOCTOR="${SPEC_OPT_SKIP_DOCTOR:-false}"
     SPEC_OPT_VERBOSE="${SPEC_OPT_VERBOSE:-false}"
     SPEC_AI_USED="${SPEC_AI_USED:-false}"
-    SPEC_AI_PROVIDER="${SPEC_AI_PROVIDER:-openai}"
+    SPEC_AI_PROVIDER="${SPEC_AI_PROVIDER:-auto}"
     SPEC_AI_MODEL="${SPEC_AI_MODEL:-}"
     SPEC_AI_TOKENS="${SPEC_AI_TOKENS:-0}"
     SPEC_SCRAPE_SOURCE_URL="${SPEC_SCRAPE_SOURCE_URL:-$(awk '/"source_url"/ { gsub(/.*"source_url"[[:space:]]*:[[:space:]]*"/, ""); gsub(/".*/, ""); print; exit }' "$f" 2>/dev/null)}"

data/scripts/install/template.sh

@@ -61,6 +61,7 @@ tmpl_render() {
         -e "s|{{THEME_DISPLAY_NAME}}|${THEME_DISPLAY_NAME:-Zer0-Mistakes}|g" \
         -e "s|{{THEME_VERSION}}|${THEME_VERSION:-}|g" \
         -e "s|{{THEME_SOURCE}}|${THEME_SOURCE:-gem}|g" \
+        -e "s|{{THEME_REMOTE}}|${THEME_REMOTE:-bamr87/zer0-mistakes}|g" \
         -e "s|{{GITHUB_USER}}|${GITHUB_USER:-}|g" \
         -e "s|{{FORK_GITHUB_USER}}|${GITHUB_USER:-}|g" \
         -e "s|{{GITHUB_REPO}}|${GITHUB_REPO:-}|g" \
@@ -72,6 +73,7 @@ tmpl_render() {
         -e "s|{{REMOTE_BRANCH}}|${REMOTE_BRANCH:-${GITHUB_PAGES_BRANCH:-gh-pages}}|g" \
         -e "s|{{REPOSITORY_NAME}}|${REPOSITORY_NAME:-${GITHUB_REPO:-my-site}}|g" \
         -e "s|{{SITE_TITLE}}|${SITE_TITLE:-My Jekyll Site}|g" \
+        -e "s|{{SITE_NAME}}|${SITE_TITLE:-My Jekyll Site}|g" \
         -e "s|{{SITE_DESCRIPTION}}|${SITE_DESCRIPTION:-A Jekyll site built with zer0-mistakes}|g" \
         -e "s|{{SITE_AUTHOR}}|${SITE_AUTHOR:-Site Author}|g" \
         -e "s|{{SITE_EMAIL}}|${SITE_EMAIL:-}|g" \
@@ -87,6 +89,8 @@ tmpl_render() {
         -e "s|{{COMMONMARKER_MACOS_VERSION}}|${COMMONMARKER_MACOS_VERSION:-~> 0.23}|g" \
         -e "s|{{GITHUB_PAGES_MAX_VERSION}}|${GITHUB_PAGES_MAX_VERSION:-232}|g" \
         -e "s|{{RUBY_MIN_VERSION_MACOS}}|${RUBY_MIN_VERSION_MACOS:-2.6.0}|g" \
+        -e "s|{{DEFAULT_BRANCH}}|${DEFAULT_BRANCH:-main}|g" \
+        -e "s|{{RUBY_VERSION}}|${RUBY_VERSION:-3.3}|g" \
         -e "s|{{INSTALL_PROFILE}}|${INSTALL_PROFILE:-default}|g" \
         -e "s|{{INSTALL_MODE}}|${INSTALL_MODE:-full}|g" \
         -e "s|{{CURRENT_DATE}}|$(date +%Y-%m-%d)|g" \

data/scripts/propagate.rb

@@ -0,0 +1,277 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# scripts/propagate.rb — theme release fan-out
+# =============================================================================
+#
+# Reads _data/consumers.yml (the downstream registry) and either REPORTS which
+# consumers have drifted behind the current theme version, or DISPATCHES a
+# `theme-release` event to each one so it opens its own bump PR.
+#
+# The problem this solves: a release used to end at RubyGems. Nothing told the
+# five sites built on this theme that a new version existed, so their pins sat
+# where someone last edited them by hand — all of them a full minor behind when
+# 1.27.0 shipped.
+#
+# Dispatch, rather than this repo opening PRs directly, because every consumer
+# gates differently: it-journey runs `make build-ci` + `make content-audit`,
+# bashconsultants builds in Docker and runs its editorial lint, the org hubs
+# re-roll member configs with provision-org-sites.rb. Each repo owns its own
+# validation; this script only announces the release.
+#
+# Usage:
+#   ruby scripts/propagate.rb                    # report drift (default)
+#   ruby scripts/propagate.rb --format json      # machine-readable report
+#   ruby scripts/propagate.rb --strict           # exit 1 if any consumer is behind
+#   ruby scripts/propagate.rb --dispatch         # fire theme-release events
+#   ruby scripts/propagate.rb --dispatch --dry-run
+#
+# Auth: uses `gh` when available, else GH_TOKEN / GITHUB_TOKEN / LIFECYCLE_PAT
+# against the REST API. Reporting works unauthenticated for public repos;
+# --dispatch always needs a token with `repo` scope on the target.
+# =============================================================================
+
+require 'yaml'
+require 'json'
+require 'net/http'
+require 'uri'
+require 'optparse'
+require 'base64'
+
+REPO_ROOT = File.expand_path('..', __dir__)
+REGISTRY  = File.join(REPO_ROOT, '_data', 'consumers.yml')
+VERSION_RB = File.join(REPO_ROOT, 'lib', 'jekyll-theme-zer0', 'version.rb')
+
+# Version-bearing patterns per pin kind. `theme_name` and `path_gem` carry no
+# version by design — they are tracked so a bump does not miss the file that
+# activates the theme, but they never report drift.
+PIN_PATTERNS = {
+  'remote_theme' => /remote_theme\s*:\s*["']?bamr87\/zer0-mistakes(?:@v?([0-9][^"'\s]*))?/,
+  'hub_registry' => /theme_repo\s*:\s*["']?bamr87\/zer0-mistakes(?:@v?([0-9][^"'\s]*))?/,
+  'gem_constraint' => /gem\s+["']jekyll-theme-zer0["']\s*,\s*["'][^0-9]*([0-9][^"']*)["']/,
+  'theme_name' => nil,
+  'path_gem' => nil
+}.freeze
+
+options = {
+  format: 'text', strict: false, dispatch: false, dry_run: false, version: nil
+}
+
+OptionParser.new do |o|
+  o.banner = 'Usage: ruby scripts/propagate.rb [options]'
+  o.on('--dispatch', 'Send theme-release events instead of reporting') { options[:dispatch] = true }
+  o.on('--dry-run', 'Show what --dispatch would send; send nothing') { options[:dry_run] = true }
+  o.on('--strict', 'Exit 1 when a consumer is behind the current version') { options[:strict] = true }
+  o.on('--format FMT', %w[text json github], 'Output format (text|json|github)') { |v| options[:format] = v }
+  o.on('--version VER', 'Theme version to compare against (default: version.rb)') { |v| options[:version] = v }
+  o.on('-h', '--help', 'Show this help') { puts o; exit 0 }
+end.parse!
+
+# -----------------------------------------------------------------------------
+def theme_version
+  content = File.read(VERSION_RB)
+  content[/VERSION\s*=\s*"([^"]+)"/, 1] or abort('could not parse version.rb')
+end
+
+def gh_available?
+  return @gh_available unless @gh_available.nil?
+
+  @gh_available = system('command -v gh > /dev/null 2>&1')
+end
+
+def token
+  ENV['GH_TOKEN'] || ENV['GITHUB_TOKEN'] || ENV['LIFECYCLE_PAT']
+end
+
+def http_get(uri, headers = {})
+  req = Net::HTTP::Get.new(uri)
+  headers.each { |k, v| req[k] = v }
+  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 15) do |http|
+    http.request(req)
+  end
+  res.is_a?(Net::HTTPSuccess) ? res.body : nil
+rescue StandardError
+  nil
+end
+
+# Fetch one file from a consumer repo. Returns nil (never raises) when the repo,
+# branch, or path is unreachable — an unreachable consumer must degrade to
+# "unknown" in the report, not take the whole fan-out down.
+#
+# Two transports, in order of capability:
+#   1. api.github.com/contents with a token — the only path that reads PRIVATE
+#      consumer repos, and the one CI uses.
+#   2. raw.githubusercontent.com unauthenticated — public repos only.
+# Never send the token to raw.githubusercontent.com: a token that is valid for
+# the API but not for raw turns a public 200 into a 404, which silently reports
+# every consumer as unreachable.
+def fetch_file(repo, branch, path)
+  if gh_available?
+    out = `gh api "repos/#{repo}/contents/#{path}?ref=#{branch}" --jq .content 2>/dev/null`
+    return Base64.decode64(out) if $?.success? && !out.strip.empty?
+  end
+
+  if token
+    body = http_get(
+      URI("https://api.github.com/repos/#{repo}/contents/#{path}?ref=#{branch}"),
+      'Authorization' => "Bearer #{token}",
+      'Accept' => 'application/vnd.github.raw',
+      'X-GitHub-Api-Version' => '2022-11-28'
+    )
+    return body if body
+  end
+
+  http_get(URI("https://raw.githubusercontent.com/#{repo}/#{branch}/#{path}"))
+end
+
+def extract_pin(kind, content)
+  pattern = PIN_PATTERNS[kind]
+  return { versioned: false, version: nil } if pattern.nil?
+  return { versioned: true, version: nil, missing: true } if content.nil?
+
+  match = content.match(pattern)
+  return { versioned: true, version: nil, missing: true } if match.nil?
+
+  # A matched pin with no captured version is a deliberate floating ref
+  # (`remote_theme: bamr87/zer0-mistakes`), not a parse failure.
+  { versioned: true, version: match[1] }
+end
+
+def compare(pinned, current)
+  return :floating if pinned.nil?
+
+  a = Gem::Version.new(pinned.sub(/\A[v=~> ]+/, ''))
+  b = Gem::Version.new(current)
+  return :current if a == b
+  return :behind if a < b
+
+  :ahead
+rescue ArgumentError
+  :unknown
+end
+
+def dispatch(repo, event, version, dry_run)
+  payload = {
+    event_type: event,
+    client_payload: { version: version, theme: 'bamr87/zer0-mistakes', tag: "v#{version}" }
+  }
+
+  if dry_run
+    puts "  [DRY RUN] POST repos/#{repo}/dispatches #{payload[:client_payload].to_json}"
+    return :dry_run
+  end
+
+  unless token
+    warn "  ✗ #{repo}: no token (GH_TOKEN / GITHUB_TOKEN / LIFECYCLE_PAT) — cannot dispatch"
+    return :no_token
+  end
+
+  uri = URI("https://api.github.com/repos/#{repo}/dispatches")
+  req = Net::HTTP::Post.new(uri)
+  req['Authorization'] = "Bearer #{token}"
+  req['Accept'] = 'application/vnd.github+json'
+  req['Content-Type'] = 'application/json'
+  req.body = payload.to_json
+  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 15) do |http|
+    http.request(req)
+  end
+
+  if res.is_a?(Net::HTTPSuccess)
+    :dispatched
+  else
+    warn "  ✗ #{repo}: dispatch failed (HTTP #{res.code})"
+    :failed
+  end
+rescue StandardError => e
+  warn "  ✗ #{repo}: dispatch error (#{e.class})"
+  :failed
+end
+
+# -----------------------------------------------------------------------------
+abort("registry not found: #{REGISTRY}") unless File.exist?(REGISTRY)
+
+registry = YAML.load_file(REGISTRY)
+defaults = registry['defaults'] || {}
+current  = options[:version] || theme_version
+consumers = registry['consumers'] || []
+
+results = consumers.map do |consumer|
+  repo   = consumer['repo']
+  branch = consumer['branch'] || defaults['branch'] || 'main'
+
+  pins = (consumer['pins'] || []).map do |pin|
+    kind = pin['kind']
+    content = PIN_PATTERNS[kind].nil? ? nil : fetch_file(repo, branch, pin['file'])
+    info = extract_pin(kind, content)
+    status = if !info[:versioned] then :not_versioned
+             elsif info[:missing] then :unreachable
+             else compare(info[:version], current)
+             end
+    { 'file' => pin['file'], 'kind' => kind, 'pinned' => info[:version], 'status' => status.to_s }
+  end
+
+  versioned = pins.reject { |p| %w[not_versioned unreachable].include?(p['status']) }
+  overall = if versioned.any? { |p| p['status'] == 'behind' } then :behind
+            elsif versioned.any? { |p| p['status'] == 'floating' } then :floating
+            elsif versioned.empty? then :unknown
+            elsif versioned.all? { |p| p['status'] == 'current' } then :current
+            else :mixed
+            end
+
+  {
+    'repo' => repo, 'mode' => consumer['mode'], 'dispatch' => consumer['dispatch'] == true,
+    'status' => overall.to_s, 'pins' => pins
+  }
+end
+
+behind = results.select { |r| r['status'] == 'behind' || r['status'] == 'mixed' }
+
+# -----------------------------------------------------------------------------
+if options[:dispatch]
+  event = defaults['dispatch_event'] || 'theme-release'
+  puts "Dispatching #{event} v#{current} to #{results.count { |r| r['dispatch'] }} consumer(s)"
+  results.each do |r|
+    unless r['dispatch']
+      puts "  – #{r['repo']}: skipped (dispatch: false — #{r['mode']})"
+      next
+    end
+    outcome = dispatch(r['repo'], event, current, options[:dry_run])
+    puts "  ✓ #{r['repo']}: #{outcome}" if %i[dispatched dry_run].include?(outcome)
+  end
+  exit 0
+end
+
+case options[:format]
+when 'json'
+  puts JSON.pretty_generate({ 'theme_version' => current, 'consumers' => results })
+when 'github'
+  results.each do |r|
+    next unless %w[behind mixed].include?(r['status'])
+
+    stale = r['pins'].select { |p| p['status'] == 'behind' }
+                     .map { |p| "#{p['file']} (#{p['pinned']})" }.join(', ')
+    puts "::warning::#{r['repo']} is behind v#{current} — #{stale}"
+  end
+  puts "::notice::#{behind.size}/#{results.size} consumers behind v#{current}"
+else
+  puts "Theme version: #{current}"
+  puts
+  results.each do |r|
+    marker = { 'current' => '✓', 'behind' => '✗', 'floating' => '~', 'mixed' => '✗' }[r['status']] || '?'
+    puts format('%s %-38s %-22s %s', marker, r['repo'], r['mode'], r['status'])
+    r['pins'].each do |p|
+      detail = case p['status']
+               when 'not_versioned' then 'no version (tracked only)'
+               when 'unreachable' then 'unreachable — check repo/branch/path'
+               when 'floating' then 'floating on main'
+               else p['pinned']
+               end
+      puts format('    %-24s %-16s %s', p['file'], p['kind'], detail)
+    end
+    puts
+  end
+  puts "#{behind.size}/#{results.size} consumer(s) behind v#{current}"
+end
+
+exit 1 if options[:strict] && !behind.empty?