jekyll-theme-zer0 1.15.0 → 1.16.0

data/scripts/bin/sync-plugins

@@ -0,0 +1,356 @@
+#!/bin/bash
+# scripts/bin/sync-plugins — copy/update theme plugins into a remote_theme consumer repo
+#
+# When using remote_theme on GitHub Pages, Jekyll does not load plugins from
+# the theme.  Consumers must vendor required plugins locally.  This command
+# reads the theme manifest, compares SHAs, and installs or updates plugins
+# in the consumer's _plugins/ directory.
+#
+# Usage:
+#   ./scripts/bin/sync-plugins [OPTIONS]
+#
+#   --consumer-path <dir>          Target consumer repo root (default: cwd)
+#   --theme-path <dir>             Source theme path (auto-resolved if omitted)
+#   --plugins {required|optional|all|<name>}
+#                                  Which plugins to sync (default: required)
+#   --dry-run                      Show what would happen without making changes
+#   --force                        Overwrite plugins listed in .theme-overrides.yml
+#   --format {text|github}         Output format (default: text)
+#   --verbose                      Debug output
+#   --help, -h                     Show this help
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+THEME_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+source "$LIB_DIR/common.sh"
+source "$LIB_DIR/audit.sh"
+
+# ---------------------------------------------------------------------------
+show_usage() {
+    cat << 'EOF'
+🔌 Plugin Sync for zer0-mistakes remote_theme consumers
+
+USAGE:
+    ./scripts/bin/sync-plugins [OPTIONS]
+
+DESCRIPTION:
+    Copies theme plugins from zer0-mistakes into a remote_theme consumer
+    (e.g. it-journey).  When using remote_theme on GitHub Pages, Jekyll does
+    not load plugins from the theme — consumers must vendor them locally.
+
+    This command reads the theme manifest to determine which plugins are
+    available, compares SHA-256 checksums, and copies new or outdated plugins
+    into the consumer's _plugins/ directory.
+
+    Sync state reported per plugin:
+      INSTALLED   Plugin was missing — now copied from theme
+      UPDATED     Plugin existed but content differed — updated to theme version
+      CURRENT     Plugin already matches the theme version — no change needed
+      SKIPPED     Plugin not in sync scope (e.g. optional when --plugins required)
+      CONFLICT    Plugin differs AND is listed in .theme-overrides.yml
+                  → intentional custom version; use --force to overwrite
+
+OPTIONS:
+    --consumer-path <dir>     Consumer repo root (default: current directory)
+    --theme-path <dir>        Source theme path (auto-resolved if omitted)
+    --plugins <scope>         Which plugins to sync:
+                                required   Required plugins only (default)
+                                optional   Optional plugins only
+                                all        Both required and optional
+                                <name>     Specific plugin, e.g. obsidian_links.rb
+    --dry-run                 Show what would happen without making changes
+    --force                   Sync even if plugin is listed in .theme-overrides.yml
+    --format {text|github}    Output format (default: text)
+    --verbose                 Debug output
+    --help, -h                Show this help
+
+EXAMPLES:
+    # Install required plugins into a sibling consumer repo
+    ./scripts/bin/sync-plugins --consumer-path ../it-journey
+
+    # Preview all plugins that would be installed/updated
+    ./scripts/bin/sync-plugins --consumer-path ../it-journey --plugins all --dry-run
+
+    # Sync only the Obsidian wiki-link plugin
+    ./scripts/bin/sync-plugins --consumer-path ../it-journey --plugins obsidian_links.rb
+
+    # Update optional plugins too, forcing over any custom versions
+    ./scripts/bin/sync-plugins --consumer-path ../it-journey --plugins all --force
+
+    # GitHub Actions annotation format
+    ./scripts/bin/sync-plugins --consumer-path ../it-journey --format github
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+CONSUMER_PATH=""
+THEME_PATH_OVERRIDE=""
+PLUGINS_SCOPE="required"
+DRY_RUN_FLAG=false
+FORCE=false
+FORMAT="text"
+VERBOSE_FLAG=false
+SHOW_HELP=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --consumer-path)  shift; CONSUMER_PATH="$1" ;;
+        --theme-path)     shift; THEME_PATH_OVERRIDE="$1" ;;
+        --plugins)        shift; PLUGINS_SCOPE="$1" ;;
+        --dry-run)        DRY_RUN_FLAG=true ;;
+        --force)          FORCE=true ;;
+        --format)         shift; FORMAT="$1" ;;
+        --verbose)        VERBOSE_FLAG=true ;;
+        --help|-h)        SHOW_HELP=true ;;
+        *) warn "Unknown option: $1" ;;
+    esac
+    shift
+done
+
+[[ "$SHOW_HELP" == "true" ]] && { show_usage; exit 0; }
+export VERBOSE="$VERBOSE_FLAG"
+
+# ---------------------------------------------------------------------------
+# Resolve paths
+# ---------------------------------------------------------------------------
+CONSUMER_PATH="${CONSUMER_PATH:-$PWD}"
+CONSUMER_PATH="$(cd "$CONSUMER_PATH" && pwd)"
+
+if [[ -n "$THEME_PATH_OVERRIDE" ]]; then
+    RESOLVED_THEME="$(cd "$THEME_PATH_OVERRIDE" && pwd)"
+else
+    RESOLVED_THEME="$THEME_ROOT"
+fi
+
+MANIFEST="$RESOLVED_THEME/_data/theme-manifest.yml"
+if [[ ! -f "$MANIFEST" ]]; then
+    error "Manifest not found: $MANIFEST — run ./scripts/bin/manifest first"
+fi
+
+debug "Consumer: $CONSUMER_PATH"
+debug "Theme:    $RESOLVED_THEME"
+debug "Manifest: $MANIFEST"
+
+# ---------------------------------------------------------------------------
+# Load override manifest (detects CONFLICT — consumer intentionally differs)
+# ---------------------------------------------------------------------------
+OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
+OVERRIDE_PATHS_TMP=$(mktemp)
+trap 'rm -f "$OVERRIDE_PATHS_TMP"' EXIT
+
+if [[ -f "$OVERRIDES_FILE" ]]; then
+    overrides_list "$OVERRIDES_FILE" > "$OVERRIDE_PATHS_TMP"
+    debug "Loaded overrides from $OVERRIDES_FILE"
+fi
+
+# ---------------------------------------------------------------------------
+# Build the list of plugins to process based on --plugins scope
+# ---------------------------------------------------------------------------
+REQUIRED_PLUGINS=()
+OPTIONAL_PLUGINS=()
+
+while IFS= read -r line; do
+    [[ -n "$line" ]] && REQUIRED_PLUGINS+=("$line")
+done < <(manifest_list "$MANIFEST" "required_plugin_paths")
+
+while IFS= read -r line; do
+    [[ -n "$line" ]] && OPTIONAL_PLUGINS+=("$line")
+done < <(manifest_list "$MANIFEST" "optional_plugin_paths")
+
+# Legacy fallback: if manifest doesn't have the split keys, use plugin_paths as required
+if [[ ${#REQUIRED_PLUGINS[@]} -eq 0 && ${#OPTIONAL_PLUGINS[@]} -eq 0 ]]; then
+    while IFS= read -r line; do
+        [[ -n "$line" ]] && REQUIRED_PLUGINS+=("$line")
+    done < <(manifest_list "$MANIFEST" "plugin_paths")
+fi
+
+# Default hardcoded fallback if manifest has no plugin entries at all
+if [[ ${#REQUIRED_PLUGINS[@]} -eq 0 && ${#OPTIONAL_PLUGINS[@]} -eq 0 ]]; then
+    REQUIRED_PLUGINS=(
+        "_plugins/preview_image_generator.rb"
+        "_plugins/obsidian_links.rb"
+    )
+    OPTIONAL_PLUGINS=(
+        "_plugins/admin_page_urls.rb"
+        "_plugins/content_statistics_generator.rb"
+        "_plugins/theme_version.rb"
+    )
+fi
+
+TARGET_PLUGINS=()
+SKIPPED_PLUGINS=()
+
+case "$PLUGINS_SCOPE" in
+    required)
+        [[ ${#REQUIRED_PLUGINS[@]} -gt 0 ]] && TARGET_PLUGINS+=("${REQUIRED_PLUGINS[@]}")
+        [[ ${#OPTIONAL_PLUGINS[@]} -gt 0 ]] && SKIPPED_PLUGINS+=("${OPTIONAL_PLUGINS[@]}")
+        ;;
+    optional)
+        [[ ${#OPTIONAL_PLUGINS[@]} -gt 0 ]] && TARGET_PLUGINS+=("${OPTIONAL_PLUGINS[@]}")
+        [[ ${#REQUIRED_PLUGINS[@]} -gt 0 ]] && SKIPPED_PLUGINS+=("${REQUIRED_PLUGINS[@]}")
+        ;;
+    all)
+        [[ ${#REQUIRED_PLUGINS[@]} -gt 0 ]] && TARGET_PLUGINS+=("${REQUIRED_PLUGINS[@]}")
+        [[ ${#OPTIONAL_PLUGINS[@]} -gt 0 ]] && TARGET_PLUGINS+=("${OPTIONAL_PLUGINS[@]}")
+        ;;
+    *)
+        # Specific plugin name — accept with or without path prefix
+        needle="$PLUGINS_SCOPE"
+        [[ "$needle" != _plugins/* ]] && needle="_plugins/$needle"
+        # Warn if not found in manifest
+        found=false
+        for p in "${REQUIRED_PLUGINS[@]:-}" "${OPTIONAL_PLUGINS[@]:-}"; do
+            if [[ "$p" == "$needle" || "$(basename "$p")" == "$(basename "$needle")" ]]; then
+                found=true
+                needle="$p"   # use the manifest-canonical path
+                break
+            fi
+        done
+        [[ "$found" == "false" ]] && warn "Plugin '$PLUGINS_SCOPE' not in manifest — attempting anyway"
+        TARGET_PLUGINS=("$needle")
+        ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+print_result() {
+    local state="$1"    # INSTALLED | UPDATED | CURRENT | SKIPPED | CONFLICT
+    local relpath="$2"
+    local note="${3:-}"
+    case "$state" in
+        INSTALLED)
+            if [[ "$FORMAT" == "github" ]]; then
+                echo "::notice file=$relpath::INSTALLED plugin from theme"
+            else
+                echo -e "${GREEN}[INSTALLED]${NC} $relpath${note:+  ($note)}"
+            fi ;;
+        UPDATED)
+            if [[ "$FORMAT" == "github" ]]; then
+                echo "::notice file=$relpath::UPDATED plugin from theme"
+            else
+                echo -e "${CYAN}[UPDATED]${NC}   $relpath${note:+  ($note)}"
+            fi ;;
+        CURRENT)
+            if [[ "$FORMAT" == "github" ]]; then
+                echo "::debug file=$relpath::CURRENT"
+            else
+                echo -e "${GREEN}[CURRENT]${NC}   $relpath"
+            fi ;;
+        SKIPPED)
+            if [[ "$FORMAT" == "github" ]]; then
+                echo "::debug file=$relpath::SKIPPED${note:+ ($note)}"
+            else
+                echo -e "          [SKIPPED]  $relpath${note:+  ($note)}"
+            fi ;;
+        CONFLICT)
+            if [[ "$FORMAT" == "github" ]]; then
+                echo "::warning file=$relpath::CONFLICT - listed in .theme-overrides.yml; use --force to overwrite"
+            else
+                echo -e "${YELLOW}[CONFLICT]${NC}  $relpath  (listed in .theme-overrides.yml — use --force to overwrite)"
+            fi ;;
+    esac
+}
+
+# ---------------------------------------------------------------------------
+# Header
+# ---------------------------------------------------------------------------
+info "Theme plugin sync"
+info "  Consumer : $CONSUMER_PATH"
+info "  Theme    : $RESOLVED_THEME"
+info "  Scope    : $PLUGINS_SCOPE"
+[[ "$DRY_RUN_FLAG" == "true" ]] && info "  Mode     : dry-run (no files written)"
+[[ "$FORCE" == "true" ]]        && info "  Force    : yes (overrides respected only by omission)"
+echo ""
+
+# ---------------------------------------------------------------------------
+# Sync loop
+# ---------------------------------------------------------------------------
+COUNT_INSTALLED=0
+COUNT_UPDATED=0
+COUNT_CURRENT=0
+COUNT_CONFLICT=0
+COUNT_SKIPPED=0
+
+for plugin_rel in "${TARGET_PLUGINS[@]}"; do
+    theme_src="$RESOLVED_THEME/$plugin_rel"
+    consumer_dst="$CONSUMER_PATH/$plugin_rel"
+
+    if [[ ! -f "$theme_src" ]]; then
+        warn "Plugin not found in theme: $plugin_rel — skipping"
+        COUNT_SKIPPED=$((COUNT_SKIPPED + 1))
+        continue
+    fi
+
+    theme_sha=$(sha256_file "$theme_src")
+
+    if [[ ! -f "$consumer_dst" ]]; then
+        # ── INSTALL ──────────────────────────────────────────────────────────
+        if [[ "$DRY_RUN_FLAG" == "true" ]]; then
+            print_result "INSTALLED" "$plugin_rel" "dry-run"
+        else
+            mkdir -p "$(dirname "$consumer_dst")"
+            cp "$theme_src" "$consumer_dst"
+            print_result "INSTALLED" "$plugin_rel"
+        fi
+        COUNT_INSTALLED=$((COUNT_INSTALLED + 1))
+    else
+        consumer_sha=$(sha256_file "$consumer_dst")
+
+        if [[ "$theme_sha" == "$consumer_sha" ]]; then
+            # ── CURRENT ──────────────────────────────────────────────────────
+            print_result "CURRENT" "$plugin_rel"
+            COUNT_CURRENT=$((COUNT_CURRENT + 1))
+        else
+            # Content differs — check for intentional override
+            if grep -qxF "$plugin_rel" "$OVERRIDE_PATHS_TMP" 2>/dev/null \
+               && [[ "$FORCE" == "false" ]]; then
+                # ── CONFLICT ─────────────────────────────────────────────────
+                print_result "CONFLICT" "$plugin_rel"
+                COUNT_CONFLICT=$((COUNT_CONFLICT + 1))
+            else
+                # ── UPDATE ───────────────────────────────────────────────────
+                if [[ "$DRY_RUN_FLAG" == "true" ]]; then
+                    print_result "UPDATED" "$plugin_rel" "dry-run"
+                else
+                    cp "$theme_src" "$consumer_dst"
+                    print_result "UPDATED" "$plugin_rel"
+                fi
+                COUNT_UPDATED=$((COUNT_UPDATED + 1))
+            fi
+        fi
+    fi
+done
+
+# Show skipped scope plugins at verbose level
+if [[ "$VERBOSE_FLAG" == "true" && ${#SKIPPED_PLUGINS[@]} -gt 0 ]]; then
+    for plugin_rel in "${SKIPPED_PLUGINS[@]}"; do
+        print_result "SKIPPED" "$plugin_rel" "out of scope (--plugins $PLUGINS_SCOPE)"
+    done
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+info "--- Summary ---"
+[[ "$COUNT_INSTALLED" -gt 0 ]] && info "Installed:  $COUNT_INSTALLED"
+[[ "$COUNT_UPDATED"   -gt 0 ]] && info "Updated:    $COUNT_UPDATED"
+[[ "$COUNT_CURRENT"   -gt 0 ]] && info "Current:    $COUNT_CURRENT"
+[[ "$COUNT_CONFLICT"  -gt 0 ]] && warn "Conflicts:  $COUNT_CONFLICT  (use --force to overwrite)"
+[[ "$COUNT_SKIPPED"   -gt 0 ]] && info "Skipped:    $COUNT_SKIPPED"
+
+TOTAL_CHANGES=$((COUNT_INSTALLED + COUNT_UPDATED))
+echo ""
+if [[ "$DRY_RUN_FLAG" == "true" && "$TOTAL_CHANGES" -gt 0 ]]; then
+    info "$TOTAL_CHANGES plugin(s) would be synced (dry-run — re-run without --dry-run to apply)"
+elif [[ "$TOTAL_CHANGES" -gt 0 ]]; then
+    success "$TOTAL_CHANGES plugin(s) synced to $CONSUMER_PATH/_plugins/"
+else
+    success "All in-scope plugins are current — nothing to do"
+fi

data/scripts/bin/validate

@@ -380,7 +380,7 @@ if File.file?('_config_secrets_local.yml')
   assert(!tracked, '_config_secrets_local.yml must remain untracked and ignored')
 end
 
-ignored_dirs = %w[.git _site node_modules vendor .jekyll-cache .sass-cache]
+ignored_dirs = %w[.git _site node_modules vendor .jekyll-cache .sass-cache test/fixtures]
 config_like_files = []
 
 Find.find('.') do |path|

data/scripts/lib/audit.sh

@@ -0,0 +1,284 @@
+#!/bin/bash
+# audit.sh — shared helpers for theme-consumer file auditing
+# Source this from scripts/bin/audit-consumer and scripts/bin/manifest.
+# Requires: common.sh to already be sourced.
+
+# ---------------------------------------------------------------------------
+# SHA-256 helpers (cross-platform: macOS sha256sum vs GNU sha256sum)
+# ---------------------------------------------------------------------------
+sha256_file() {
+    local file="$1"
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$file" | awk '{print $1}'
+    else
+        shasum -a 256 "$file" | awk '{print $1}'
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Manifest parsing — reads _data/theme-manifest.yml via awk (no yq needed)
+# ---------------------------------------------------------------------------
+# Returns the value of a top-level scalar key in a YAML file.
+manifest_scalar() {
+    local manifest_file="$1"
+    local key="$2"
+    awk -v k="$key" '
+        /^[a-zA-Z_][a-zA-Z0-9_]*:/ {
+            match($0, /^([a-zA-Z_][a-zA-Z0-9_]*): *(.*)/, arr)
+            if (arr[1] == k) { gsub(/^[[:space:]"'"'"']+|[[:space:]"'"'"']+$/, "", arr[2]); print arr[2]; exit }
+        }
+    ' "$manifest_file"
+}
+
+# Returns each item in a top-level YAML list (- item entries).
+manifest_list() {
+    local manifest_file="$1"
+    local key="$2"
+    awk -v k="$key" '
+        $0 ~ "^" k ":[ ]*$" { in_block=1; next }
+        in_block && /^[[:space:]]*- / {
+            line=$0; gsub(/^[[:space:]]*- |[[:space:]]*$/, "", line)
+            # strip optional inline comment
+            sub(/ *#.*$/, "", line)
+            if (line != "") print line
+        }
+        in_block && /^[a-zA-Z_]/ { in_block=0 }
+    ' "$manifest_file"
+}
+
+# Read the per-file checksum section from the manifest.
+# Emits lines of: <relpath> <sha256>
+manifest_checksums() {
+    local manifest_file="$1"
+    awk '
+        /^file_checksums:/ { in_block=1; next }
+        in_block && /^  [^ ]/ {
+            # lines look like:   _layouts/default.html: "abc123..."
+            line=$0; gsub(/^[[:space:]]+/, "", line)
+            split(line, arr, ": ")
+            path=arr[1]; sha=arr[2]
+            gsub(/"/, "", sha); gsub(/[[:space:]]/, "", sha)
+            if (path != "" && sha != "") print path " " sha
+        }
+        in_block && /^[a-zA-Z_]/ { in_block=0 }
+    ' "$manifest_file"
+}
+
+# ---------------------------------------------------------------------------
+# Override manifest parsing (.theme-overrides.yml in consumer root)
+# ---------------------------------------------------------------------------
+# Returns each justified override path (under overrides: list).
+overrides_list() {
+    local overrides_file="$1"
+    awk '
+        /^overrides:/ { in_block=1; next }
+        in_block && /^  - path: / {
+            path=$0; gsub(/^.*path: */, "", path); gsub(/[[:space:]]*$/, "", path)
+            print path
+        }
+        in_block && /^[a-zA-Z_]/ { in_block=0 }
+    ' "$overrides_file" | tr -d '"'"'"
+}
+
+# ---------------------------------------------------------------------------
+# Classification logic
+# ---------------------------------------------------------------------------
+# classify_file <theme_path> <consumer_path> <relpath> <override_paths_file>
+# Emits one of: IDENTICAL DIFFERS_JUSTIFIED DIFFERS_UNJUSTIFIED UNIQUE MISSING_LOCALLY
+classify_file() {
+    local theme_root="$1"
+    local consumer_root="$2"
+    local relpath="$3"
+    local override_paths_file="$4"     # temp file listing justified paths (one per line)
+
+    local theme_file="$theme_root/$relpath"
+    local consumer_file="$consumer_root/$relpath"
+
+    # File only in consumer (theme doesn't have it → unique to consumer)
+    if [[ ! -f "$theme_file" ]]; then
+        echo "UNIQUE"
+        return
+    fi
+
+    # File missing in consumer
+    if [[ ! -f "$consumer_file" ]]; then
+        echo "MISSING_LOCALLY"
+        return
+    fi
+
+    # Compare content
+    local theme_sha consumer_sha
+    theme_sha=$(sha256_file "$theme_file")
+    consumer_sha=$(sha256_file "$consumer_file")
+
+    if [[ "$theme_sha" == "$consumer_sha" ]]; then
+        echo "IDENTICAL"
+        return
+    fi
+
+    # Files differ — check if justified
+    if grep -qxF "$relpath" "$override_paths_file" 2>/dev/null; then
+        echo "DIFFERS_JUSTIFIED"
+    else
+        echo "DIFFERS_UNJUSTIFIED"
+    fi
+}
+
+# classify_plugin <plugin_relpath> <consumer_root> <mode>
+# mode: gem | remote_theme
+# Emits: MISSING_PLUGIN STALE_PLUGIN OK NOT_REQUIRED
+classify_plugin() {
+    local plugin_relpath="$1"
+    local consumer_root="$2"
+    local mode="$3"
+    local theme_root="$4"
+
+    local consumer_plugin="$consumer_root/$plugin_relpath"
+
+    if [[ "$mode" != "remote_theme" ]]; then
+        # Gem mode: theme loads plugins itself — consumer doesn't need a copy
+        echo "NOT_REQUIRED"
+        return
+    fi
+
+    if [[ ! -f "$consumer_plugin" ]]; then
+        echo "MISSING_PLUGIN"
+        return
+    fi
+
+    # Check staleness
+    local theme_plugin="$theme_root/$plugin_relpath"
+    if [[ -f "$theme_plugin" ]]; then
+        local theme_sha consumer_sha
+        theme_sha=$(sha256_file "$theme_plugin")
+        consumer_sha=$(sha256_file "$consumer_plugin")
+        if [[ "$theme_sha" != "$consumer_sha" ]]; then
+            echo "STALE_PLUGIN"
+            return
+        fi
+    fi
+
+    echo "OK"
+}
+
+# ---------------------------------------------------------------------------
+# Theme-path auto-resolution
+# ---------------------------------------------------------------------------
+resolve_theme_path() {
+    local mode="$1"
+    local consumer_root="$2"
+    local sibling_theme_root="${3:-}"   # optional explicit path
+
+    if [[ -n "$sibling_theme_root" ]]; then
+        echo "$sibling_theme_root"
+        return
+    fi
+
+    if [[ "$mode" == "gem" ]]; then
+        local gem_path
+        gem_path=$(cd "$consumer_root" && bundle show jekyll-theme-zer0 2>/dev/null || true)
+        if [[ -n "$gem_path" && -d "$gem_path" ]]; then
+            echo "$gem_path"
+            return
+        fi
+    fi
+
+    # remote_theme mode or gem resolution failed: check work/theme-cache/
+    local cache_dir="$consumer_root/work/theme-cache/zer0-mistakes"
+    if [[ -d "$cache_dir" ]]; then
+        echo "$cache_dir"
+        return
+    fi
+
+    echo ""
+}
+
+# ---------------------------------------------------------------------------
+# Detect consumer mode from _config.yml
+# ---------------------------------------------------------------------------
+detect_consumer_mode() {
+    local consumer_root="$1"
+    local config="$consumer_root/_config.yml"
+
+    if [[ ! -f "$config" ]]; then
+        echo "unknown"
+        return
+    fi
+
+    if grep -qE '^remote_theme:' "$config"; then
+        echo "remote_theme"
+    else
+        echo "gem"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+print_classification() {
+    local classification="$1"
+    local relpath="$2"
+    local format="${3:-text}"
+
+    case "$classification" in
+        IDENTICAL)
+            local color="${GREEN}"
+            local icon="✓"
+            ;;
+        DIFFERS_JUSTIFIED)
+            local color="${CYAN}"
+            local icon="~"
+            ;;
+        DIFFERS_UNJUSTIFIED)
+            local color="${RED}"
+            local icon="✗"
+            ;;
+        UNIQUE)
+            local color="${BLUE}"
+            local icon="+"
+            ;;
+        MISSING_LOCALLY)
+            local color="${YELLOW}"
+            local icon="?"
+            ;;
+        MISSING_PLUGIN)
+            local color="${RED}"
+            local icon="!"
+            ;;
+        STALE_PLUGIN)
+            local color="${YELLOW}"
+            local icon="~"
+            ;;
+        OK)
+            local color="${GREEN}"
+            local icon="✓"
+            ;;
+        NOT_REQUIRED)
+            local color="${BLUE}"
+            local icon="-"
+            ;;
+        OPTIONAL_PLUGIN)
+            local color="${CYAN}"
+            local icon="?"
+            ;;
+        *)
+            local color="${NC}"
+            local icon="?"
+            ;;
+    esac
+
+    if [[ "$format" == "github" ]]; then
+        case "$classification" in
+            DIFFERS_UNJUSTIFIED|MISSING_PLUGIN)
+                echo "::warning file=$relpath::$classification" ;;
+            STALE_PLUGIN)
+                echo "::notice file=$relpath::STALE_PLUGIN" ;;
+            OPTIONAL_PLUGIN)
+                echo "::notice file=$relpath::OPTIONAL_PLUGIN (not required)" ;;
+        esac
+    elif [[ "$format" == "json" ]]; then
+        echo "  {\"path\":\"$relpath\",\"status\":\"$classification\"},"
+    else
+        echo -e "${color}[$classification]${NC} $relpath"
+    fi
+}

data/scripts/lib/frontmatter.sh

@@ -437,8 +437,10 @@ parse_file_frontmatter_all() {
 
     ruby -ryaml -rdate -e '
         path = ARGV[0]
-        # Extract frontmatter block (between first pair of --- on their own lines)
-        content = File.read(path)
+        # Extract frontmatter block (between first pair of --- on their own lines).
+        # Explicit UTF-8: default external encoding is US-ASCII without a UTF-8
+        # locale, and posts contain multibyte characters (T-015 bug class).
+        content = File.read(path, encoding: "UTF-8")
         unless content =~ /\A---\s*\n(.*?)\n---\s*$/m
             puts "__NO_FRONTMATTER__"
             exit 0

data/scripts/test/lib/test_locale_independence.sh

@@ -22,6 +22,9 @@ assert_true "(cd '$REPO_ROOT' && LC_ALL=C LANG=C ruby scripts/generate-roadmap.r
 assert_true "(cd '$REPO_ROOT' && LC_ALL=C LANG=C ruby scripts/sync-backlog.rb --check >/dev/null 2>&1)" \
     "sync-backlog.rb --check survives a C locale"
 
+assert_true "(cd '$REPO_ROOT' && LC_ALL=C LANG=C ./scripts/lint-pages --strict >/dev/null 2>&1)" \
+    "lint-pages --strict survives a C locale"
+
 # validate --quick covers the package.json read in scripts/bin/validate
 assert_true "(cd '$REPO_ROOT' && LC_ALL=C LANG=C ./scripts/bin/validate --quick >/dev/null 2>&1)" \
     "validate --quick survives a C locale"