jekyll-theme-zer0 1.15.0 → 1.16.0

data/scripts/bin/audit-consumer

@@ -0,0 +1,336 @@
+#!/bin/bash
+# scripts/bin/audit-consumer — audit a Jekyll consumer repo against this theme
+#
+# Usage: ./scripts/bin/audit-consumer [OPTIONS]
+#   --consumer-path <dir>         Path to the consumer repo (default: cwd)
+#   --theme-path <dir>            Explicit theme path (auto-resolved if omitted)
+#   --mode {gem|remote_theme}     Deployment mode (auto-detected if omitted)
+#   --fix                         Delete IDENTICAL files + copy MISSING/STALE plugins
+#   --overwrite-plugins           Combined with --fix: replace STALE plugins too
+#   --strict                      Exit non-zero on any unjustified drift (for CI)
+#   --format {text|json|github}   Output format (default: text)
+#   --verbose                     Debug output
+#   --dry-run                     Show what --fix would do without changing files
+#   --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'
+🔍 Theme Consumer Auditor for zer0-mistakes
+
+USAGE:
+    ./scripts/bin/audit-consumer [OPTIONS]
+
+DESCRIPTION:
+    Compares a consumer Jekyll repo against the installed zer0-mistakes theme
+    and reports every shadowed, missing, or stale file.
+
+    File classifications:
+      IDENTICAL          Consumer file is byte-for-byte identical to theme file
+                         → safe to delete (theme file will be used instead)
+      DIFFERS_JUSTIFIED  Consumer file differs and is listed in .theme-overrides.yml
+                         → intentional override, no action needed
+      DIFFERS_UNJUSTIFIED Consumer file differs but is NOT listed in .theme-overrides.yml
+                         → flag for review; --strict exits non-zero
+      UNIQUE             File exists only in the consumer, not in the theme
+                         → consumer-specific file, no action needed
+      MISSING_LOCALLY    File exists in theme but not in consumer
+                         → informational only
+
+    Plugin classifications (remote_theme mode only):
+      MISSING_PLUGIN     Plugin required by theme not vendored in consumer
+      STALE_PLUGIN       Plugin exists but differs from current theme version
+      OK                 Plugin matches current theme version
+      NOT_REQUIRED       Gem mode — theme loads plugins itself
+
+OPTIONS:
+    --consumer-path <dir>         Consumer repo root (default: current directory)
+    --theme-path <dir>            Explicit theme path (auto-resolved if omitted)
+    --mode {gem|remote_theme}     Force deployment mode (auto-detected if omitted)
+    --fix                         Fix issues: delete IDENTICAL files; copy
+                                  MISSING_PLUGIN files from theme
+    --overwrite-plugins           With --fix: also replace STALE_PLUGIN files
+    --strict                      Exit 1 if any DIFFERS_UNJUSTIFIED or
+                                  MISSING_PLUGIN issues found (use in CI)
+    --format {text|json|github}   Output format
+                                  github emits ::warning annotations for CI
+    --verbose                     Show debug output
+    --dry-run                     Show what --fix would do without changing files
+    --help, -h                    Show this help
+
+EXAMPLES:
+    # Audit current directory (auto-detect mode)
+    ./scripts/bin/audit-consumer
+
+    # Audit from a sibling consumer repo
+    ./scripts/bin/audit-consumer --consumer-path ~/github/it-journey
+
+    # CI strict check with GitHub annotations
+    ./scripts/bin/audit-consumer --strict --format github
+
+    # Fix all safe auto-fixable issues
+    ./scripts/bin/audit-consumer --fix --dry-run   # preview first
+    ./scripts/bin/audit-consumer --fix
+
+    # Fix including stale plugins
+    ./scripts/bin/audit-consumer --fix --overwrite-plugins
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# Defaults
+CONSUMER_PATH="$(pwd)"
+THEME_PATH_OVERRIDE=""
+MODE_OVERRIDE=""
+FIX=false
+OVERWRITE_PLUGINS=false
+STRICT=false
+FORMAT="text"
+SHOW_HELP=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --consumer-path)   shift; CONSUMER_PATH="$1" ;;
+        --theme-path)      shift; THEME_PATH_OVERRIDE="$1" ;;
+        --mode)            shift; MODE_OVERRIDE="$1" ;;
+        --fix)             FIX=true ;;
+        --overwrite-plugins) OVERWRITE_PLUGINS=true ;;
+        --strict)          STRICT=true ;;
+        --format)          shift; FORMAT="$1" ;;
+        --dry-run)         export DRY_RUN=true ;;
+        --verbose)         export VERBOSE=true ;;
+        --help|-h)         SHOW_HELP=true ;;
+        *)                 warn "Unknown option: $1" ;;
+    esac
+    shift
+done
+
+[[ "$SHOW_HELP" == "true" ]] && { show_usage; exit 0; }
+
+CONSUMER_PATH="$(cd "$CONSUMER_PATH" && pwd)"
+
+# ---------------------------------------------------------------------------
+step "Auditing consumer: $CONSUMER_PATH"
+
+# Detect or confirm mode
+if [[ -n "$MODE_OVERRIDE" ]]; then
+    MODE="$MODE_OVERRIDE"
+else
+    MODE=$(detect_consumer_mode "$CONSUMER_PATH")
+    info "Detected mode: $MODE"
+fi
+
+# Resolve theme path
+if [[ -n "$THEME_PATH_OVERRIDE" ]]; then
+    RESOLVED_THEME="$THEME_PATH_OVERRIDE"
+else
+    RESOLVED_THEME=$(resolve_theme_path "$MODE" "$CONSUMER_PATH" "$THEME_ROOT")
+fi
+
+if [[ -z "$RESOLVED_THEME" || ! -d "$RESOLVED_THEME" ]]; then
+    error "Cannot resolve theme path. Try --theme-path <dir> or run from the consumer with gem installed."
+fi
+info "Theme path: $RESOLVED_THEME"
+
+# Locate manifest
+MANIFEST="$RESOLVED_THEME/_data/theme-manifest.yml"
+if [[ ! -f "$MANIFEST" ]]; then
+    warn "No theme manifest found at $MANIFEST — falling back to directory scan."
+    MANIFEST=""
+fi
+
+# Load overrides manifest from consumer
+OVERRIDES_FILE="$CONSUMER_PATH/.theme-overrides.yml"
+OVERRIDE_PATHS_TMP=$(mktemp)
+trap 'rm -f "$OVERRIDE_PATHS_TMP"' EXIT
+
+if [[ -f "$OVERRIDES_FILE" ]]; then
+    info "Override manifest: $OVERRIDES_FILE"
+    overrides_list "$OVERRIDES_FILE" > "$OVERRIDE_PATHS_TMP"
+else
+    warn "No .theme-overrides.yml found — all differing files will be flagged as DIFFERS_UNJUSTIFIED"
+fi
+
+# ---------------------------------------------------------------------------
+# Collect themable paths from manifest or defaults
+# ---------------------------------------------------------------------------
+THEMABLE_DIRS=()
+REQUIRED_PLUGIN_FILES=()
+OPTIONAL_PLUGIN_FILES=()
+
+if [[ -n "$MANIFEST" ]]; then
+    while IFS= read -r line; do
+        [[ -n "$line" ]] && THEMABLE_DIRS+=("$line")
+    done < <(manifest_list "$MANIFEST" "themable_paths")
+    # Prefer the explicit required/optional split; fall back to legacy plugin_paths
+    while IFS= read -r line; do
+        [[ -n "$line" ]] && REQUIRED_PLUGIN_FILES+=("$line")
+    done < <(manifest_list "$MANIFEST" "required_plugin_paths")
+    while IFS= read -r line; do
+        [[ -n "$line" ]] && OPTIONAL_PLUGIN_FILES+=("$line")
+    done < <(manifest_list "$MANIFEST" "optional_plugin_paths")
+    # Legacy fallback: if new keys absent, use plugin_paths as required
+    if [[ ${#REQUIRED_PLUGIN_FILES[@]} -eq 0 && ${#OPTIONAL_PLUGIN_FILES[@]} -eq 0 ]]; then
+        while IFS= read -r line; do
+            [[ -n "$line" ]] && REQUIRED_PLUGIN_FILES+=("$line")
+        done < <(manifest_list "$MANIFEST" "plugin_paths")
+    fi
+fi
+
+if [[ ${#THEMABLE_DIRS[@]} -eq 0 ]]; then
+    THEMABLE_DIRS=("_layouts" "_includes" "_sass" "assets/css" "assets/js")
+fi
+if [[ ${#REQUIRED_PLUGIN_FILES[@]} -eq 0 && ${#OPTIONAL_PLUGIN_FILES[@]} -eq 0 ]]; then
+    REQUIRED_PLUGIN_FILES=("_plugins/preview_image_generator.rb" "_plugins/obsidian_links.rb")
+    OPTIONAL_PLUGIN_FILES=("_plugins/admin_page_urls.rb" "_plugins/content_statistics_generator.rb" "_plugins/theme_version.rb")
+fi
+
+# ---------------------------------------------------------------------------
+# Scan themable directories
+# ---------------------------------------------------------------------------
+DRIFT_COUNT=0
+IDENTICAL_FILES=()
+DIFFERS_UNJUSTIFIED_FILES=()
+
+[[ "$FORMAT" == "json" ]] && echo '{"results":['
+
+for theme_dir in "${THEMABLE_DIRS[@]}"; do
+    theme_abs="$RESOLVED_THEME/$theme_dir"
+    [[ -d "$theme_abs" ]] || continue
+
+    while IFS= read -r -d '' theme_file; do
+        relpath="${theme_file#$RESOLVED_THEME/}"
+        [[ "$relpath" == *README* ]] && continue
+        [[ "$relpath" == *_site/* ]] && continue
+        [[ "$relpath" == *.map   ]] && continue
+
+        classification=$(classify_file "$RESOLVED_THEME" "$CONSUMER_PATH" "$relpath" "$OVERRIDE_PATHS_TMP")
+        print_classification "$classification" "$relpath" "$FORMAT"
+
+        case "$classification" in
+            IDENTICAL)
+                IDENTICAL_FILES+=("$relpath") ;;
+            DIFFERS_UNJUSTIFIED)
+                DIFFERS_UNJUSTIFIED_FILES+=("$relpath")
+                DRIFT_COUNT=$((DRIFT_COUNT + 1)) ;;
+        esac
+    done < <(find "$theme_abs" -type f -print0 | sort -z)
+done
+
+# Also scan consumer for UNIQUE files (in theme dirs only)
+for consumer_dir in "${THEMABLE_DIRS[@]}"; do
+    consumer_abs="$CONSUMER_PATH/$consumer_dir"
+    [[ -d "$consumer_abs" ]] || continue
+
+    while IFS= read -r -d '' consumer_file; do
+        relpath="${consumer_file#$CONSUMER_PATH/}"
+        theme_file="$RESOLVED_THEME/$relpath"
+        [[ -f "$theme_file" ]] && continue   # already classified above
+        [[ "$relpath" == *README* ]] && continue
+        print_classification "UNIQUE" "$relpath" "$FORMAT"
+    done < <(find "$consumer_abs" -type f -print0 | sort -z)
+done
+
+# ---------------------------------------------------------------------------
+# Scan plugins
+# ---------------------------------------------------------------------------
+PLUGIN_ISSUES=0
+OPTIONAL_PLUGIN_ISSUES=0
+ALL_PLUGIN_FILES=("${REQUIRED_PLUGIN_FILES[@]}" "${OPTIONAL_PLUGIN_FILES[@]}")
+
+if [[ ${#ALL_PLUGIN_FILES[@]} -gt 0 ]]; then
+    [[ "$FORMAT" == "text" ]] && echo ""
+    [[ "$FORMAT" == "text" ]] && info "--- Plugin check (mode: $MODE) ---"
+
+    for plugin_rel in "${REQUIRED_PLUGIN_FILES[@]}"; do
+        classification=$(classify_plugin "$plugin_rel" "$CONSUMER_PATH" "$MODE" "$RESOLVED_THEME")
+        print_classification "$classification" "$plugin_rel" "$FORMAT"
+        case "$classification" in
+            MISSING_PLUGIN|STALE_PLUGIN)
+                PLUGIN_ISSUES=$((PLUGIN_ISSUES + 1)) ;;
+        esac
+    done
+
+    for plugin_rel in "${OPTIONAL_PLUGIN_FILES[@]}"; do
+        classification=$(classify_plugin "$plugin_rel" "$CONSUMER_PATH" "$MODE" "$RESOLVED_THEME")
+        # Downgrade missing optional plugins to OPTIONAL_PLUGIN (informational)
+        if [[ "$classification" == "MISSING_PLUGIN" ]]; then
+            classification="OPTIONAL_PLUGIN"
+            OPTIONAL_PLUGIN_ISSUES=$((OPTIONAL_PLUGIN_ISSUES + 1))
+        fi
+        print_classification "$classification" "$plugin_rel" "$FORMAT"
+    done
+fi
+
+# ---------------------------------------------------------------------------
+# Apply fixes
+# ---------------------------------------------------------------------------
+if [[ "$FIX" == "true" ]]; then
+    echo ""
+    step "Applying fixes..."
+
+    for relpath in "${IDENTICAL_FILES[@]}"; do
+        if [[ "$DRY_RUN" == "true" ]]; then
+            info "[DRY RUN] Would delete: $CONSUMER_PATH/$relpath"
+        else
+            rm -f "$CONSUMER_PATH/$relpath"
+            success "Deleted (IDENTICAL): $relpath"
+        fi
+    done
+
+    for plugin_rel in "${REQUIRED_PLUGIN_FILES[@]}" "${OPTIONAL_PLUGIN_FILES[@]}"; do
+        classification=$(classify_plugin "$plugin_rel" "$CONSUMER_PATH" "$MODE" "$RESOLVED_THEME")
+        theme_plugin="$RESOLVED_THEME/$plugin_rel"
+        consumer_plugin="$CONSUMER_PATH/$plugin_rel"
+
+        if [[ "$classification" == "MISSING_PLUGIN" ]]; then
+            if [[ -f "$theme_plugin" ]]; then
+                if [[ "$DRY_RUN" == "true" ]]; then
+                    info "[DRY RUN] Would copy: $plugin_rel"
+                else
+                    mkdir -p "$(dirname "$consumer_plugin")"
+                    cp "$theme_plugin" "$consumer_plugin"
+                    success "Copied (MISSING_PLUGIN): $plugin_rel"
+                fi
+            fi
+        elif [[ "$classification" == "STALE_PLUGIN" && "$OVERWRITE_PLUGINS" == "true" ]]; then
+            if [[ "$DRY_RUN" == "true" ]]; then
+                info "[DRY RUN] Would overwrite stale plugin: $plugin_rel"
+            else
+                cp "$theme_plugin" "$consumer_plugin"
+                success "Updated (STALE_PLUGIN): $plugin_rel"
+            fi
+        fi
+    done
+fi
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+[[ "$FORMAT" == "json" ]] && echo ']}'
+
+if [[ "$FORMAT" == "text" ]]; then
+    echo ""
+    info "--- Summary ---"
+    info "IDENTICAL files (safe to delete):  ${#IDENTICAL_FILES[@]}"
+    info "DIFFERS_UNJUSTIFIED files:          ${#DIFFERS_UNJUSTIFIED_FILES[@]}"
+    info "Required plugin issues:            $PLUGIN_ISSUES"
+    [[ "$OPTIONAL_PLUGIN_ISSUES" -gt 0 ]] && info "Optional plugins not vendored:     $OPTIONAL_PLUGIN_ISSUES (informational)"
+fi
+
+TOTAL_ISSUES=$((DRIFT_COUNT + PLUGIN_ISSUES))
+
+if [[ "$STRICT" == "true" && "$TOTAL_ISSUES" -gt 0 ]]; then
+    error "Strict mode: $TOTAL_ISSUES unjustified drift issue(s) found."
+fi
+
+[[ "$TOTAL_ISSUES" -gt 0 ]] && exit 1 || exit 0

data/scripts/bin/manifest

@@ -0,0 +1,183 @@
+#!/bin/bash
+# scripts/bin/manifest — generate _data/theme-manifest.yml
+# Walks the theme repo filesystem and produces a machine-readable manifest
+# with per-file SHA-256 checksums.  Run automatically by scripts/bin/release.
+#
+# Usage: ./scripts/bin/manifest [OPTIONS]
+#   --dry-run       Print manifest to stdout instead of writing the file
+#   --verbose       Show each file being hashed
+#   --help, -h      Show this help
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+source "$LIB_DIR/common.sh"
+source "$LIB_DIR/version.sh"
+source "$LIB_DIR/audit.sh"
+
+# ---------------------------------------------------------------------------
+show_usage() {
+    cat << 'EOF'
+📋 Theme Manifest Generator for zer0-mistakes
+
+USAGE:
+    ./scripts/bin/manifest [OPTIONS]
+
+DESCRIPTION:
+    Generates _data/theme-manifest.yml from the current state of the theme
+    repo.  The manifest records the version, owned directories, plugin files
+    that remote-theme consumers must vendor, required config keys, and a
+    SHA-256 checksum for every themable file.
+
+    Run automatically by scripts/bin/release before tagging.
+
+OPTIONS:
+    --dry-run       Print manifest to stdout; don't write the file
+    --verbose       Show each file being processed
+    --help, -h      Show this help message
+
+EXAMPLES:
+    ./scripts/bin/manifest                  # Regenerate _data/theme-manifest.yml
+    ./scripts/bin/manifest --dry-run        # Preview output
+    ./scripts/bin/manifest --verbose        # Show every file being hashed
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# Directories the theme owns (relative to repo root)
+THEMABLE_PATHS=(
+    "_layouts"
+    "_includes"
+    "_sass"
+    "assets/css"
+    "assets/js"
+    "assets/images"
+)
+
+# Data files the theme ships that consumers may override with their own content
+# (excluded from the overlap audit; listed for documentation only).
+THEME_DATA_PATHS=(
+    "_data/navigation"
+    "_data/ui-text.yml"
+)
+
+# Plugins that remote_theme consumers MUST vendor locally (GitHub Pages won't
+# load plugins from a remote theme).
+REQUIRED_PLUGIN_PATHS=(
+    "_plugins/preview_image_generator.rb"
+    "_plugins/obsidian_links.rb"
+)
+
+# Optional plugins that consumers can vendor for enhanced functionality.
+OPTIONAL_PLUGIN_PATHS=(
+    "_plugins/admin_page_urls.rb"
+    "_plugins/content_statistics_generator.rb"
+    "_plugins/theme_version.rb"
+)
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+DRY_RUN=false
+VERBOSE=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run)   DRY_RUN=true ;;
+        --verbose)   VERBOSE=true ;;
+        --help|-h)   show_usage; exit 0 ;;
+        *)           warn "Unknown option: $1" ;;
+    esac
+    shift
+done
+
+# ---------------------------------------------------------------------------
+step "Generating theme manifest..."
+cd "$REPO_ROOT"
+
+CURRENT_VERSION=$(get_current_version)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# ---------------------------------------------------------------------------
+# Build the per-file checksum block
+# ---------------------------------------------------------------------------
+build_checksums() {
+    for dir in "${THEMABLE_PATHS[@]}"; do
+        [[ -d "$dir" ]] || continue
+        while IFS= read -r -d '' file; do
+            local relpath="${file#./}"
+            # Skip README files and compiled/generated output
+            [[ "$relpath" == *README* ]] && continue
+            [[ "$relpath" == *_site/* ]] && continue
+            [[ "$relpath" == *.map ]] && continue
+            local sha
+            sha=$(sha256_file "$file")
+            debug "  $relpath → $sha"
+            [[ "$VERBOSE" == "true" ]] && info "  $relpath"
+            printf '  %s: "%s"\n' "$relpath" "$sha"
+        done < <(find "$dir" -type f -print0 | sort -z)
+    done
+}
+
+# ---------------------------------------------------------------------------
+MANIFEST_CONTENT=$(cat << YAML
+# _data/theme-manifest.yml
+# AUTO-GENERATED by scripts/bin/manifest — DO NOT EDIT BY HAND.
+# Regenerated automatically during each release (scripts/bin/release).
+# Consumers use this file via scripts/bin/audit-consumer to detect drift.
+
+version: "${CURRENT_VERSION}"
+generated_at: "${TIMESTAMP}"
+
+# Directories owned by this theme.  A consumer file in any of these paths
+# that is not declared in the consumer's .theme-overrides.yml is flagged
+# as an unjustified shadow.
+themable_paths:
+$(printf '  - %s\n' "${THEMABLE_PATHS[@]}")
+
+# Data paths the theme ships but that consumers are *expected* to customise.
+# Not included in the shadow audit.
+theme_data_paths:
+$(printf '  - %s\n' "${THEME_DATA_PATHS[@]}")
+
+# Plugin files that consumers using remote_theme MUST vendor locally.
+# GitHub Pages does not load plugins from a remote_theme source.
+required_plugin_paths:
+$(printf '  - %s\n' "${REQUIRED_PLUGIN_PATHS[@]}")
+# Optional plugins consumers can vendor for enhanced functionality.
+optional_plugin_paths:
+$(printf '  - %s\n' "${OPTIONAL_PLUGIN_PATHS[@]}")
+
+# Legacy alias — all plugin paths combined (kept for backward compatibility).
+plugin_paths:
+$(printf '  - %s\n' "${REQUIRED_PLUGIN_PATHS[@]}" "${OPTIONAL_PLUGIN_PATHS[@]}")
+
+# Jekyll config keys this theme expects.
+config_schema:
+  required:
+    - title
+    - description
+    - remote_theme
+  recommended_features:
+    - posthog
+    - preview_images
+    - cookie_consent
+  deprecated:
+    - site_configured  # Removed in 1.5.0; safe to delete
+
+# Per-file SHA-256 checksums for every file in themable_paths.
+file_checksums:
+$(build_checksums)
+YAML
+)
+
+# ---------------------------------------------------------------------------
+if [[ "$DRY_RUN" == "true" ]]; then
+    info "[DRY RUN] Would write _data/theme-manifest.yml:"
+    echo "$MANIFEST_CONTENT"
+else
+    echo "$MANIFEST_CONTENT" > "$REPO_ROOT/_data/theme-manifest.yml"
+    success "Written: _data/theme-manifest.yml (version $CURRENT_VERSION)"
+fi

data/scripts/bin/release

@@ -177,7 +177,21 @@ main() {
     # Step 4: Update version files
     update_version_files "$new_version"
     echo ""
-    
+
+    # Step 4.5: Regenerate theme manifest with new version + checksums
+    step "Regenerating theme manifest..."
+    local manifest_script="$SCRIPT_DIR/manifest"
+    if [[ -x "$manifest_script" ]]; then
+        if [[ "$DRY_RUN" == "true" ]]; then
+            info "[DRY RUN] Would regenerate _data/theme-manifest.yml"
+        else
+            "$manifest_script"
+        fi
+    else
+        warn "scripts/bin/manifest not found — skipping manifest regeneration"
+    fi
+    echo ""
+
     # Step 5: Run tests
     if [[ "$SKIP_TESTS" != "true" ]]; then
         run_tests