jekyll-theme-zer0 1.8.2 → 1.9.0

data/scripts/install/doctor.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/doctor.sh — Pre-install environment health checks
+# =============================================================================
+# Checks system prerequisites and reports pass/warn/fail for each.
+# Never blocks apply_run by default — warnings only. Fatal conditions
+# (e.g. target dir not writable) return non-zero.
+#
+# Provides:
+#   doctor_run [TARGET_DIR]   — run all checks; return 0 if clean, 1 if any FAIL
+#   doctor_check_ruby         — Ruby version check
+#   doctor_check_bundler      — Bundler present
+#   doctor_check_docker       — Docker daemon
+#   doctor_check_git          — git present
+#   doctor_check_gh           — GitHub CLI present (warn only)
+#   doctor_check_writable     — target dir writable
+#
+# Bash 3.2 compatible. No set -euo pipefail here.
+# =============================================================================
+[[ -n "${_HAS_DOCTOR_LIB:-}" ]] && return 0
+_HAS_DOCTOR_LIB=1
+
+# Internal check helpers
+_doctor_pass()  { printf "  [PASS]  %s\n" "$*" >&2; }
+_doctor_warn()  { printf "  [WARN]  %s\n" "$*" >&2; }
+_doctor_fail()  { printf "  [FAIL]  %s\n" "$*" >&2; }
+
+# ---------------------------------------------------------------------------
+# doctor_check_ruby
+# ---------------------------------------------------------------------------
+doctor_check_ruby() {
+    local ruby_ver
+    ruby_ver=$(ruby --version 2>/dev/null | awk '{print $2}')
+    if [[ -z "$ruby_ver" ]]; then
+        _doctor_fail "Ruby not found. Install Ruby >= 2.7 (rbenv / brew / asdf recommended)"
+        return 1
+    fi
+
+    # Extract major.minor
+    local major minor
+    major=$(echo "$ruby_ver" | cut -d. -f1)
+    minor=$(echo "$ruby_ver" | cut -d. -f2)
+
+    if [[ "$major" -lt 2 || ( "$major" -eq 2 && "$minor" -lt 5 ) ]]; then
+        _doctor_fail "Ruby $ruby_ver is too old (need >= 2.5). Upgrade recommended."
+        return 1
+    fi
+
+    if [[ "$major" -eq 2 && "$minor" -lt 7 ]]; then
+        _doctor_warn "Ruby $ruby_ver is supported but >= 3.0 is recommended"
+    else
+        _doctor_pass "Ruby $ruby_ver"
+    fi
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# doctor_check_bundler
+# ---------------------------------------------------------------------------
+doctor_check_bundler() {
+    if ! command -v bundle >/dev/null 2>&1; then
+        _doctor_warn "Bundler not found — run: gem install bundler"
+        return 0   # warn, not fail
+    fi
+    local bver
+    bver=$(bundle --version 2>/dev/null | awk '{print $NF}')
+    _doctor_pass "Bundler $bver"
+}
+
+# ---------------------------------------------------------------------------
+# doctor_check_docker
+# ---------------------------------------------------------------------------
+doctor_check_docker() {
+    local profile="${SPEC_PROFILE:-default}"
+    case "$profile" in
+        minimal|github-pages)
+            _doctor_pass "Docker: not required for profile '$profile'"
+            return 0
+            ;;
+    esac
+
+    if ! command -v docker >/dev/null 2>&1; then
+        _doctor_warn "Docker not found. Install Docker Desktop for best dev experience."
+        return 0
+    fi
+
+    if ! docker info >/dev/null 2>&1; then
+        _doctor_warn "Docker daemon not running. Start Docker Desktop."
+        return 0
+    fi
+
+    _doctor_pass "Docker (daemon running)"
+}
+
+# ---------------------------------------------------------------------------
+# doctor_check_git
+# ---------------------------------------------------------------------------
+doctor_check_git() {
+    if ! command -v git >/dev/null 2>&1; then
+        _doctor_fail "git not found. Install git before proceeding."
+        return 1
+    fi
+    local gver
+    gver=$(git --version | awk '{print $3}')
+    _doctor_pass "git $gver"
+}
+
+# ---------------------------------------------------------------------------
+# doctor_check_gh
+# ---------------------------------------------------------------------------
+doctor_check_gh() {
+    if ! command -v gh >/dev/null 2>&1; then
+        _doctor_warn "GitHub CLI (gh) not found. Some features will be limited."
+        return 0
+    fi
+    local ghver
+    ghver=$(gh --version 2>/dev/null | head -1 | awk '{print $3}')
+    _doctor_pass "GitHub CLI $ghver"
+}
+
+# ---------------------------------------------------------------------------
+# doctor_check_writable TARGET_DIR
+# ---------------------------------------------------------------------------
+doctor_check_writable() {
+    local target="$1"
+    if [[ -z "$target" ]]; then
+        _doctor_warn "doctor_check_writable: no target_dir specified"
+        return 0
+    fi
+
+    # If directory doesn't exist, check parent
+    local check_dir="$target"
+    while [[ ! -d "$check_dir" ]]; do
+        check_dir=$(dirname "$check_dir")
+    done
+
+    if [[ ! -w "$check_dir" ]]; then
+        _doctor_fail "Target directory not writable: $check_dir"
+        return 1
+    fi
+    _doctor_pass "Target directory writable: $check_dir"
+}
+
+# ---------------------------------------------------------------------------
+# doctor_run [TARGET_DIR]
+# ---------------------------------------------------------------------------
+doctor_run() {
+    local target="${1:-${SPEC_TARGET_DIR:-}}"
+    local failures=0
+
+    printf "\n${_LOG_BOLD:-}Doctor: pre-install checks${_LOG_NC:-}\n" >&2
+
+    doctor_check_ruby     || failures=$(( failures + 1 ))
+    doctor_check_bundler
+    doctor_check_docker
+    doctor_check_git      || failures=$(( failures + 1 ))
+    doctor_check_gh
+    [[ -n "$target" ]] && { doctor_check_writable "$target" || failures=$(( failures + 1 )); }
+
+    if [[ $failures -eq 0 ]]; then
+        printf "\n${_LOG_GREEN:-}Doctor: all checks passed.${_LOG_NC:-}\n\n" >&2
+        return 0
+    fi
+
+    printf "\n${_LOG_YELLOW:-}Doctor: %d issue(s) found. See above.${_LOG_NC:-}\n\n" \
+        "$failures" >&2
+    return 1
+}

data/scripts/install/fs.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/fs.sh — Idempotent filesystem operations
+# =============================================================================
+# ALL file writes in the installer go through this module.
+# Provides:
+#   fs_copy_file      SRC DEST [--force] [--dry-run]
+#   fs_copy_dir       SRC DEST [--force] [--dry-run]
+#   fs_write_file     DEST CONTENT [--force] [--dry-run]
+#   fs_ensure_dir     PATH [--dry-run]
+#   fs_backup_file    FILE  → creates FILE.backup.YYYYMMDD_HHMMSS
+#   fs_file_exists    FILE  → returns 0 if exists
+#
+# Globals read (set by caller / spec):
+#   _FS_DRY_RUN   — "1" → never write, only log
+#   _FS_FORCE     — "1" → overwrite without prompting (still backs up)
+#   _FS_BACKUP    — "1" (default) → create backups before overwriting
+#   _FS_VERBOSE   — "1" → extra debug output
+#
+# Bash 3.2 compatible. No set -euo pipefail here.
+# =============================================================================
+[[ -n "${_HAS_FS_LIB:-}" ]] && return 0
+_HAS_FS_LIB=1
+
+_FS_DRY_RUN="${_FS_DRY_RUN:-0}"
+_FS_FORCE="${_FS_FORCE:-0}"
+_FS_BACKUP="${_FS_BACKUP:-1}"
+_FS_VERBOSE="${_FS_VERBOSE:-0}"
+
+# Create a timestamped backup of FILE; prints backup path.
+fs_backup_file() {
+    local file="$1"
+    [ -e "$file" ] || return 0
+    local bak="${file}.backup.$(date +%Y%m%d_%H%M%S)"
+    if [[ "${_FS_DRY_RUN:-0}" == "1" ]]; then
+        log_debug "[dry-run] would backup: $file → $bak"
+        return 0
+    fi
+    cp -a "$file" "$bak"
+    log_warning "Backed up: $(basename "$file") → $(basename "$bak")"
+    echo "$bak"
+}
+
+# Copy a single file SRC → DEST. Backs up DEST if it exists (unless --force).
+fs_copy_file() {
+    local src="$1"
+    local dest="$2"
+
+    if [[ ! -f "$src" ]]; then
+        log_error "fs_copy_file: source not found: $src"
+        return 1
+    fi
+
+    if [[ "${_FS_DRY_RUN:-0}" == "1" ]]; then
+        log_info "[dry-run] copy: $src → $dest"
+        return 0
+    fi
+
+    fs_ensure_dir "$(dirname "$dest")"
+
+    if [[ -f "$dest" ]]; then
+        if [[ "${_FS_BACKUP:-1}" == "1" ]]; then
+            fs_backup_file "$dest" > /dev/null
+        fi
+    fi
+
+    cp "$src" "$dest"
+    log_info "Wrote: $dest"
+}
+
+# Recursively copy directory SRC → DEST.
+fs_copy_dir() {
+    local src="$1"
+    local dest="$2"
+
+    if [[ ! -d "$src" ]]; then
+        log_error "fs_copy_dir: source not found: $src"
+        return 1
+    fi
+
+    if [[ "${_FS_DRY_RUN:-0}" == "1" ]]; then
+        log_info "[dry-run] copy dir: $src → $dest"
+        return 0
+    fi
+
+    if [[ -d "$dest" ]]; then
+        if [[ "${_FS_BACKUP:-1}" == "1" ]]; then
+            local bak="${dest}.backup.$(date +%Y%m%d_%H%M%S)"
+            cp -a "$dest" "$bak"
+            log_warning "Backed up dir: $(basename "$dest") → $(basename "$bak")"
+        fi
+        rm -rf "$dest"
+    fi
+
+    cp -r "$src" "$dest"
+    log_info "Copied dir: $dest"
+}
+
+# Write CONTENT string to DEST.
+fs_write_file() {
+    local dest="$1"
+    local content="$2"
+
+    if [[ "${_FS_DRY_RUN:-0}" == "1" ]]; then
+        log_info "[dry-run] write: $dest"
+        return 0
+    fi
+
+    fs_ensure_dir "$(dirname "$dest")"
+
+    if [[ -f "$dest" && "${_FS_FORCE:-0}" != "1" ]]; then
+        log_warning "$(basename "$dest") already exists — skipping (use --force to overwrite)"
+        return 0
+    fi
+
+    if [[ -f "$dest" && "${_FS_BACKUP:-1}" == "1" ]]; then
+        fs_backup_file "$dest" > /dev/null
+    fi
+
+    printf '%s\n' "$content" > "$dest"
+    log_info "Wrote: $dest"
+}
+
+# Ensure directory exists (including parents).
+fs_ensure_dir() {
+    local dir="$1"
+    [[ -d "$dir" ]] && return 0
+    if [[ "${_FS_DRY_RUN:-0}" == "1" ]]; then
+        log_debug "[dry-run] mkdir -p: $dir"
+        return 0
+    fi
+    mkdir -p "$dir"
+    log_debug "Created dir: $dir"
+}
+
+fs_file_exists() {
+    [[ -f "$1" ]]
+}

data/scripts/install/log.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/log.sh — Logging primitives
+# =============================================================================
+# Provides: log_info, log_success, log_warning, log_error, log_debug,
+#           log_json, log_step, log_indent_push, log_indent_pop
+#
+# Output modes:
+#   human (default) — coloured, prefixed text to stderr
+#   json            — machine-readable JSON lines to stdout
+#
+# Callers set _LOG_OUTPUT="json" before sourcing to switch modes.
+# Callers set _LOG_VERBOSE=1 to enable log_debug output.
+#
+# Bash 3.2 compatible. No declare -A. No set -euo pipefail here.
+# =============================================================================
+[[ -n "${_HAS_LOG_LIB:-}" ]] && return 0
+_HAS_LOG_LIB=1
+
+# Colour codes — only apply when stderr is a TTY
+_LOG_RED=''
+_LOG_GREEN=''
+_LOG_YELLOW=''
+_LOG_BLUE=''
+_LOG_CYAN=''
+_LOG_BOLD=''
+_LOG_NC=''
+if [[ -t 2 ]]; then
+    _LOG_RED='\033[0;31m'
+    _LOG_GREEN='\033[0;32m'
+    _LOG_YELLOW='\033[1;33m'
+    _LOG_BLUE='\033[0;34m'
+    _LOG_CYAN='\033[0;36m'
+    _LOG_BOLD='\033[1m'
+    _LOG_NC='\033[0m'
+fi
+
+# Output mode: "human" | "json"
+_LOG_OUTPUT="${_LOG_OUTPUT:-human}"
+# Verbose: 1 = show debug lines
+_LOG_VERBOSE="${_LOG_VERBOSE:-0}"
+# Indent level (incremented by log_step sections)
+_LOG_INDENT=0
+
+# Internal: emit a single log line
+_log_emit() {
+    local level="$1"
+    local msg="$2"
+    local prefix color
+    local indent=""
+    local i=0
+    while [[ $i -lt $_LOG_INDENT ]]; do
+        indent="  $indent"
+        i=$(( i + 1 ))
+    done
+    case "$level" in
+        INFO)    color="$_LOG_BLUE";   prefix="[INFO]"    ;;
+        SUCCESS) color="$_LOG_GREEN";  prefix="[SUCCESS]" ;;
+        WARNING) color="$_LOG_YELLOW"; prefix="[WARNING]" ;;
+        ERROR)   color="$_LOG_RED";    prefix="[ERROR]"   ;;
+        DEBUG)   color="$_LOG_CYAN";   prefix="[DEBUG]"   ;;
+        STEP)    color="$_LOG_BOLD";   prefix="[STEP]"    ;;
+        *)       color="$_LOG_NC";     prefix="[$level]"  ;;
+    esac
+
+    if [[ "$_LOG_OUTPUT" == "json" ]]; then
+        # Emit JSON line to stdout for machine parsing
+        local ts
+        ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ")
+        # Escape double quotes in message
+        local safe_msg
+        safe_msg=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g')
+        printf '{"ts":"%s","level":"%s","msg":"%s"}\n' "$ts" "$level" "$safe_msg"
+    else
+        printf "${color}${prefix}${_LOG_NC} %s%s\n" "$indent" "$msg" >&2
+    fi
+}
+
+log_info()    { _log_emit "INFO"    "$1"; }
+log_success() { _log_emit "SUCCESS" "$1"; }
+log_warning() { _log_emit "WARNING" "$1"; }
+log_error()   { _log_emit "ERROR"   "$1"; }
+log_debug()   { [[ "${_LOG_VERBOSE:-0}" == "1" ]] && _log_emit "DEBUG" "$1" || true; }
+
+# log_step TITLE — print a section header and increment indent
+log_step() {
+    _log_emit "STEP" "── $1"
+    _LOG_INDENT=$(( _LOG_INDENT + 1 ))
+}
+
+# log_step_done — decrement indent after a section
+log_step_done() {
+    [[ $_LOG_INDENT -gt 0 ]] && _LOG_INDENT=$(( _LOG_INDENT - 1 )) || true
+}
+
+# log_json KEY VALUE — emit a JSON key/value pair to stdout (for --output json)
+# Use inside sections that need structured output regardless of log mode.
+log_json() {
+    local key="$1"
+    local val="$2"
+    printf '{"key":"%s","value":"%s"}\n' "$key" "$val"
+}
+
+# log_banner TEXT — print a visible section banner
+log_banner() {
+    local msg="$1"
+    local width=70
+    local line=""
+    local i=0
+    while [[ $i -lt $width ]]; do
+        line="${line}="
+        i=$(( i + 1 ))
+    done
+    if [[ "$_LOG_OUTPUT" != "json" ]]; then
+        printf "${_LOG_BOLD}%s${_LOG_NC}\n" "$line" >&2
+        printf "${_LOG_BOLD}  %s${_LOG_NC}\n" "$msg" >&2
+        printf "${_LOG_BOLD}%s${_LOG_NC}\n" "$line" >&2
+    fi
+}