jekyll-theme-zer0 0.22.20 → 0.22.22

data/scripts/lib/install/doctor.sh

@@ -0,0 +1,301 @@
+#!/usr/bin/env bash
+# scripts/lib/install/doctor.sh
+#
+# `install doctor` — environment + site health check.
+#
+# Runs platform-specific prerequisite checks (delegating to
+# scripts/platform/setup-{macos,linux,wsl}.sh in check-only mode), then
+# layers zer0-mistakes-specific checks on top: gh CLI, Docker compose,
+# Bundler/Jekyll versions, agent files, and OpenAI connectivity (opt-in).
+#
+# Output: structured pass/warn/fail report. Exits 0 when no FAIL,
+# 1 when at least one FAIL.
+#
+# Public API:
+#     doctor_run <target_dir> <repo_root> [--ai] [--quiet] [--json]
+#
+# Bash 3.2-compatible. Pure shell — no jq required.
+
+# shellcheck disable=SC2034
+DOCTOR_LIB_VERSION="1.0.0"
+
+# Counters (reset on every doctor_run call)
+DOCTOR_PASS=0
+DOCTOR_WARN=0
+DOCTOR_FAIL=0
+DOCTOR_REPORT=""
+
+# Append a structured row.
+# args: status (PASS|WARN|FAIL) name detail [remediation]
+_doctor_row() {
+    local status="$1" name="$2" detail="$3" remediation="${4:-}"
+    case "$status" in
+        PASS) DOCTOR_PASS=$((DOCTOR_PASS+1)); log_success "$name: $detail" ;;
+        WARN) DOCTOR_WARN=$((DOCTOR_WARN+1)); log_warning "$name: $detail"; [[ -n "$remediation" ]] && log_info "  → $remediation" ;;
+        FAIL) DOCTOR_FAIL=$((DOCTOR_FAIL+1)); log_error "$name: $detail"; [[ -n "$remediation" ]] && log_info "  → $remediation" ;;
+    esac
+    DOCTOR_REPORT="${DOCTOR_REPORT}${status}|${name}|${detail}|${remediation}
+"
+}
+
+# ── Platform checks ────────────────────────────────────────────────────────
+_doctor_platform() {
+    local repo_root="$1"
+    local os
+    os="$(uname -s 2>/dev/null || echo unknown)"
+
+    local script=""
+    case "$os" in
+        Darwin)              script="$repo_root/scripts/platform/setup-macos.sh" ;;
+        Linux)
+            # Distinguish WSL from native Linux
+            if grep -qi microsoft /proc/version 2>/dev/null; then
+                script="$repo_root/scripts/platform/setup-wsl.sh"
+            else
+                script="$repo_root/scripts/platform/setup-linux.sh"
+            fi
+            ;;
+        *)
+            _doctor_row WARN "Platform" "$os not directly supported" \
+                "Doctor will only run zer0-mistakes-specific checks"
+            return 0
+            ;;
+    esac
+
+    if [[ ! -f "$script" ]]; then
+        _doctor_row WARN "Platform script" "Not found at ${script#$repo_root/}" \
+            "Falling back to inline checks"
+        _doctor_inline_platform_checks
+        return 0
+    fi
+
+    log_info "Running platform checks: $(basename "$script")"
+    # Source so we can call individual check functions; suppress its main
+    # entrypoint by setting a guard env.
+    # shellcheck source=/dev/null
+    if ! source "$script" 2>/dev/null; then
+        _doctor_row WARN "Platform script" "Failed to source" \
+            "Falling back to inline checks"
+        _doctor_inline_platform_checks
+        return 0
+    fi
+
+    # Each setup script exposes check_* functions. Probe the common set.
+    local suffix=""
+    case "$os" in
+        Darwin) suffix="macos" ;;
+        Linux)  suffix="linux"; grep -qi microsoft /proc/version 2>/dev/null && suffix="wsl" ;;
+    esac
+
+    if declare -F "check_git_${suffix}" >/dev/null 2>&1; then
+        if "check_git_${suffix}"; then
+            _doctor_row PASS "Git" "$(git --version 2>/dev/null | head -1)"
+        else
+            _doctor_row FAIL "Git" "Not installed" "Install via your package manager"
+        fi
+    fi
+    if declare -F "check_docker_${suffix}" >/dev/null 2>&1; then
+        if "check_docker_${suffix}"; then
+            _doctor_row PASS "Docker" "$(docker --version 2>/dev/null)"
+        elif command -v docker >/dev/null 2>&1; then
+            _doctor_row WARN "Docker" "Installed but daemon not reachable" \
+                "Start Docker Desktop / 'sudo systemctl start docker'"
+        else
+            _doctor_row WARN "Docker" "Not installed" \
+                "Optional — only needed for containerized dev"
+        fi
+    fi
+    if declare -F "check_ruby_${suffix}" >/dev/null 2>&1; then
+        if "check_ruby_${suffix}"; then
+            _doctor_row PASS "Ruby" "$(ruby --version 2>/dev/null)"
+        elif command -v ruby >/dev/null 2>&1; then
+            _doctor_row WARN "Ruby" "$(ruby --version 2>/dev/null) (3.0+ recommended)" \
+                "Upgrade via Homebrew/rbenv for best compatibility"
+        else
+            _doctor_row WARN "Ruby" "Not installed" \
+                "Optional — only needed for native (non-Docker) dev"
+        fi
+    fi
+}
+
+# Fallback when platform script is missing.
+_doctor_inline_platform_checks() {
+    if command -v git >/dev/null 2>&1; then
+        _doctor_row PASS "Git" "$(git --version 2>/dev/null | head -1)"
+    else
+        _doctor_row FAIL "Git" "Not installed" "Required for cloning + version control"
+    fi
+    if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+        _doctor_row PASS "Docker" "$(docker --version 2>/dev/null)"
+    else
+        _doctor_row WARN "Docker" "Not running or not installed" \
+            "Optional — needed for containerized dev"
+    fi
+    if command -v ruby >/dev/null 2>&1; then
+        _doctor_row PASS "Ruby" "$(ruby --version 2>/dev/null)"
+    else
+        _doctor_row WARN "Ruby" "Not installed" "Optional — needed for native dev"
+    fi
+}
+
+# ── Tooling checks ─────────────────────────────────────────────────────────
+_doctor_tooling() {
+    # gh CLI (used by deploy + agent flows that touch repos)
+    if command -v gh >/dev/null 2>&1; then
+        _doctor_row PASS "GitHub CLI" "$(gh --version 2>/dev/null | head -1)"
+    else
+        _doctor_row WARN "GitHub CLI" "Not installed" \
+            "Optional — install from https://cli.github.com for repo automation"
+    fi
+
+    # Docker Compose v2
+    if docker compose version >/dev/null 2>&1; then
+        _doctor_row PASS "Docker Compose" "$(docker compose version --short 2>/dev/null)"
+    elif command -v docker-compose >/dev/null 2>&1; then
+        _doctor_row WARN "Docker Compose" "v1 detected ($(docker-compose --version 2>/dev/null))" \
+            "Upgrade to v2: docker compose plugin"
+    else
+        _doctor_row WARN "Docker Compose" "Not available" \
+            "Optional — needed for 'docker compose up'"
+    fi
+
+    # Bundler
+    if command -v bundle >/dev/null 2>&1; then
+        # bundle --version may fail when run inside a dir with a Gemfile.lock
+        # pinning a different bundler. Probe in a neutral cwd to avoid noise.
+        local bv
+        bv="$(cd / && bundle --version 2>/dev/null | head -1)"
+        if [[ -n "$bv" ]]; then
+            _doctor_row PASS "Bundler" "$bv"
+        else
+            _doctor_row WARN "Bundler" "Installed but version probe failed" \
+                "Likely Gemfile.lock pins an unavailable bundler — run 'bundle update --bundler'"
+        fi
+    else
+        _doctor_row WARN "Bundler" "Not installed" \
+            "Install: gem install bundler (only needed for native dev)"
+    fi
+}
+
+# ── Site checks (run inside target_dir) ────────────────────────────────────
+_doctor_site() {
+    local target_dir="$1"
+
+    if [[ ! -d "$target_dir" ]]; then
+        _doctor_row FAIL "Target dir" "Does not exist: $target_dir" "Run 'install init' first"
+        return
+    fi
+
+    if [[ -f "$target_dir/_config.yml" ]]; then
+        _doctor_row PASS "_config.yml" "Present"
+    else
+        _doctor_row WARN "_config.yml" "Missing in $target_dir" \
+            "Run 'install init' to scaffold a site"
+    fi
+
+    if [[ -f "$target_dir/Gemfile" ]]; then
+        _doctor_row PASS "Gemfile" "Present"
+    else
+        _doctor_row WARN "Gemfile" "Missing" "Run 'install init' or 'install deploy'"
+    fi
+
+    if [[ -f "$target_dir/AGENTS.md" ]]; then
+        _doctor_row PASS "AI agent files" "AGENTS.md present"
+    else
+        _doctor_row WARN "AI agent files" "AGENTS.md not installed" \
+            "Run 'install agents' to add AI guidance"
+    fi
+
+    # Basic _config.yml sanity
+    if [[ -f "$target_dir/_config.yml" ]]; then
+        if grep -qE "^(remote_theme|theme):" "$target_dir/_config.yml" 2>/dev/null; then
+            _doctor_row PASS "Theme config" "remote_theme/theme set in _config.yml"
+        else
+            _doctor_row WARN "Theme config" "Neither 'theme' nor 'remote_theme' found" \
+                "Set 'remote_theme: bamr87/zer0-mistakes' or 'theme: jekyll-theme-zer0'"
+        fi
+    fi
+}
+
+# ── AI connectivity (opt-in) ───────────────────────────────────────────────
+_doctor_ai_connectivity() {
+    if [[ "${ZER0_NO_AI:-0}" = "1" ]]; then
+        _doctor_row WARN "OpenAI connectivity" "Skipped (ZER0_NO_AI=1)" \
+            "Unset ZER0_NO_AI to enable AI checks"
+        return
+    fi
+    if [[ -z "${OPENAI_API_KEY:-}" ]]; then
+        _doctor_row WARN "OpenAI API key" "OPENAI_API_KEY not set" \
+            "Export OPENAI_API_KEY to enable AI features"
+        return
+    fi
+    # Lightweight ping: check we can reach the API and the key authenticates.
+    local http_code
+    http_code="$(curl -sS -o /dev/null -w '%{http_code}' \
+        --max-time 10 \
+        -H "Authorization: Bearer ${OPENAI_API_KEY}" \
+        https://api.openai.com/v1/models 2>/dev/null || echo "000")"
+    case "$http_code" in
+        200)  _doctor_row PASS "OpenAI connectivity" "Authenticated (HTTP 200)" ;;
+        401)  _doctor_row FAIL "OpenAI connectivity" "Authentication failed (HTTP 401)" \
+                "Verify OPENAI_API_KEY is valid" ;;
+        000)  _doctor_row WARN "OpenAI connectivity" "No network response" \
+                "Check internet connection / firewall" ;;
+        *)    _doctor_row WARN "OpenAI connectivity" "Unexpected response (HTTP $http_code)" \
+                "Inspect with: curl -v https://api.openai.com/v1/models" ;;
+    esac
+}
+
+# ── Public entrypoint ──────────────────────────────────────────────────────
+doctor_run() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local check_ai=0 quiet=0 emit_json=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ai)   check_ai=1 ;;
+            --quiet) quiet=1 ;;
+            --json) emit_json=1 ;;
+            *) log_warning "doctor_run: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    DOCTOR_PASS=0; DOCTOR_WARN=0; DOCTOR_FAIL=0; DOCTOR_REPORT=""
+
+    [[ "$quiet" = "1" ]] || log_info "🩺 Running zer0-mistakes doctor..."
+    [[ "$quiet" = "1" ]] || echo
+
+    [[ "$quiet" = "1" ]] || log_info "── Platform ─────────────────────────────"
+    _doctor_platform "$repo_root"
+    [[ "$quiet" = "1" ]] || echo
+
+    [[ "$quiet" = "1" ]] || log_info "── Tooling ──────────────────────────────"
+    _doctor_tooling
+    [[ "$quiet" = "1" ]] || echo
+
+    [[ "$quiet" = "1" ]] || log_info "── Site ($target_dir) ───"
+    _doctor_site "$target_dir"
+    [[ "$quiet" = "1" ]] || echo
+
+    if [[ "$check_ai" = "1" ]]; then
+        [[ "$quiet" = "1" ]] || log_info "── AI ────────────────────────────────────"
+        _doctor_ai_connectivity
+        [[ "$quiet" = "1" ]] || echo
+    fi
+
+    if [[ "$emit_json" = "1" ]]; then
+        # Emit a tiny JSON summary — no jq, just printf.
+        printf '{"pass":%d,"warn":%d,"fail":%d}\n' \
+            "$DOCTOR_PASS" "$DOCTOR_WARN" "$DOCTOR_FAIL"
+    else
+        log_info "── Summary ──────────────────────────────"
+        log_info "  ✅ PASS: $DOCTOR_PASS"
+        log_info "  ⚠️  WARN: $DOCTOR_WARN"
+        log_info "  ❌ FAIL: $DOCTOR_FAIL"
+    fi
+
+    [[ "$DOCTOR_FAIL" = "0" ]] && return 0
+    return 1
+}

data/scripts/lib/install/fs.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# =========================================================================
+# scripts/lib/install/fs.sh
+# =========================================================================
+# Filesystem helpers for install.sh: idempotent file/directory copy with
+# automatic timestamped backups when destination already exists.
+#
+# Required globals (set by install.sh before sourcing/use):
+#   $TARGET_DIR  — used to compute relative paths in log messages
+#
+# Functions exported:
+#   copy_file_with_backup       SRC DEST
+#   copy_directory_with_backup  SRC DEST
+# =========================================================================
+
+# Copy a file, backing up the destination if it already exists.
+copy_file_with_backup() {
+    local src="$1"
+    local dest="$2"
+    local relative_path="${dest#${TARGET_DIR:-}/}"
+
+    # Create destination directory if it doesn't exist
+    mkdir -p "$(dirname "$dest")"
+
+    # Backup existing file if it exists
+    if [[ -f "$dest" ]]; then
+        local backup_file="${dest}.backup.$(date +%Y%m%d_%H%M%S)"
+        log_warning "File exists, creating backup: $relative_path -> ${backup_file##*/}"
+        cp "$dest" "$backup_file"
+    fi
+
+    # Copy the file
+    cp "$src" "$dest"
+    log_info "Copied: $relative_path"
+}
+
+# Copy a directory, backing up the destination if it already exists.
+copy_directory_with_backup() {
+    local src="$1"
+    local dest="$2"
+    local relative_path="${dest#${TARGET_DIR:-}/}"
+
+    if [[ -d "$dest" ]]; then
+        local backup_dir="${dest}.backup.$(date +%Y%m%d_%H%M%S)"
+        log_warning "Directory exists, creating backup: $relative_path -> ${backup_dir##*/}"
+        cp -r "$dest" "$backup_dir"
+        rm -rf "$dest"
+    fi
+
+    cp -r "$src" "$dest"
+    log_info "Copied directory: $relative_path"
+}

data/scripts/lib/install/logging.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# =========================================================================
+# scripts/lib/install/logging.sh
+# =========================================================================
+# Logging shim for install.sh. Provides log_info / log_success /
+# log_warning / log_error names used throughout install.sh while
+# delegating to scripts/lib/common.sh primitives where available.
+#
+# WHY a shim instead of a direct sed-rename?
+#   - install.sh has ~300+ call sites to log_info/log_success/log_warning/log_error
+#   - Common.sh uses different verbs (info/success/warn/error) and `error` exits
+#   - A thin shim preserves behavior exactly while letting future code use
+#     either vocabulary.
+#
+# Source order requirement:
+#   This file must be sourced AFTER scripts/lib/common.sh so the
+#   colour variables (RED/GREEN/YELLOW/BLUE/NC) are defined.
+#
+# Compatibility: bash 3.2+ (macOS default)
+# =========================================================================
+
+# Define colours if common.sh wasn't sourced (safe defaults).
+RED="${RED:-\033[0;31m}"
+GREEN="${GREEN:-\033[0;32m}"
+YELLOW="${YELLOW:-\033[1;33m}"
+BLUE="${BLUE:-\033[0;34m}"
+NC="${NC:-\033[0m}"
+
+# install.sh-style logging — identical output to the original block.
+log_info()    { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
+log_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
+log_error()   { echo -e "${RED}[ERROR]${NC} $1"; }

data/scripts/lib/install/pages.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# scripts/lib/install/pages.sh
+#
+# Starter-page generator for jekyll-theme-zer0 installations.
+# Replaces 8 near-identical create_*_page heredoc functions with a single
+# manifest-driven renderer.
+#
+# Required env (from install.conf via config.sh):
+#   TARGET_DIR, THEME_NAME, THEME_DISPLAY_NAME, DEFAULT_URL, GITHUB_URL
+#
+# Required functions (from template.sh):
+#   create_from_template <template_relpath> <dest_abspath> <fallback_content>
+#
+# Public API:
+#   render_starter_pages          - generate all default pages + admin
+#   render_admin_settings_pages   - generate just the _about/settings/* pages
+
+# ---------- Manifest --------------------------------------------------------
+# Format (pipe-separated, no spaces around |):
+#   <template_relpath>|<dest_relpath>|<mkdir_relpath>|<fallback_func>
+# Empty <mkdir_relpath> = no mkdir; empty <fallback_func> = no fallback.
+_starter_pages_manifest() {
+    cat <<'MANIFEST'
+pages/quickstart.md.template|pages/quickstart/index.md|pages/quickstart|_fallback_quickstart
+pages/docs-index.md.template|pages/_docs/index.md|pages/_docs|_fallback_docs_index
+pages/configuration.md.template|pages/_docs/configuration/index.md|pages/_docs/configuration|
+pages/troubleshooting.md.template|pages/_docs/troubleshooting.md|pages/_docs|
+pages/about.md.template|pages/_about/index.md|pages/_about|_fallback_about
+pages/blog.md.template|pages/blog.md||_fallback_blog
+MANIFEST
+}
+
+_admin_settings_pages() {
+    echo "theme config navigation collections analytics environment"
+}
+
+# ---------- Fallback content (only used when template missing) --------------
+_fallback_quickstart() {
+    cat <<EOF
+---
+layout: default
+title: Quick Start
+permalink: /quickstart/
+---
+
+# Quick Start Guide
+
+Get your site up and running in just a few minutes!
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Docker Desktop** installed ([download](https://www.docker.com/products/docker-desktop))
+- **Git** installed ([download](https://git-scm.com/))
+
+## 1. Start Development Server
+
+### Using Docker (Recommended)
+
+\`\`\`bash
+docker-compose up
+\`\`\`
+
+Your site will be available at **${DEFAULT_URL}**
+
+### Using Local Ruby
+
+\`\`\`bash
+bundle install
+bundle exec jekyll serve
+\`\`\`
+
+## 2. Customize Your Site
+
+Edit \`_config.yml\` to personalize your site:
+
+\`\`\`yaml
+title: Your Site Title
+description: Your site description
+author: Your Name
+\`\`\`
+
+## 3. Add Content
+
+- Create posts in \`pages/_posts/\`
+- Create documentation in \`pages/_docs/\`
+- Add static pages in \`pages/\`
+
+## Next Steps
+
+- [Read the Documentation](/docs/) - Learn about all features
+- [Explore Configuration](/docs/configuration/) - Customize your site
+- [Learn about Layouts](/docs/layouts/) - Understand page layouts
+
+---
+
+Need help? Check the [troubleshooting guide](/docs/troubleshooting/) or [open an issue](${GITHUB_URL}/issues).
+EOF
+}
+
+_fallback_docs_index() {
+    cat <<EOF
+---
+layout: default
+title: Documentation
+permalink: /docs/
+---
+
+# Documentation
+
+Welcome to the ${THEME_NAME} theme documentation. Here you'll find everything you need to build and customize your Jekyll site.
+
+## Getting Started
+
+<div class="row">
+<div class="col-md-6 mb-3">
+
+### Installation
+
+The theme supports multiple installation methods:
+
+- **Docker** (Recommended) - Zero dependencies
+- **Remote Theme** - For GitHub Pages
+- **Gem** - Traditional Ruby installation
+
+[View Installation Guide →](/quickstart/)
+
+</div>
+<div class="col-md-6 mb-3">
+
+### Configuration
+
+Customize your site with \`_config.yml\`:
+
+- Site title and description
+- Navigation menus
+- Social links
+- Analytics integration
+
+[View Configuration Guide →](/docs/configuration/)
+
+</div>
+</div>
+
+## Need Help?
+
+- [Troubleshooting Guide](/docs/troubleshooting/)
+- [GitHub Issues](${GITHUB_URL}/issues)
+- [GitHub Discussions](${GITHUB_URL}/discussions)
+EOF
+}
+
+_fallback_about() {
+    cat <<EOF
+---
+layout: default
+title: About
+permalink: /about/
+---
+
+# About This Site
+
+This site is built with the **${THEME_DISPLAY_NAME}** - a professional Jekyll theme designed for GitHub Pages with Bootstrap 5.3.
+
+## Theme Features
+
+- ✅ Bootstrap 5.3 integration
+- ✅ Dark/Light mode toggle
+- ✅ Docker support
+- ✅ GitHub Pages compatible
+- ✅ SEO optimized
+
+## Learn More
+
+- [Theme Documentation](/docs/)
+- [GitHub Repository](${GITHUB_URL})
+- [Report an Issue](${GITHUB_URL}/issues)
+
+## Customizing This Page
+
+Edit \`pages/_about/index.md\` to customize this page with your own content.
+EOF
+}
+
+_fallback_blog() {
+    cat <<'EOF'
+---
+layout: default
+title: Blog
+permalink: /blog/
+---
+
+# Blog
+
+Welcome to the blog. Create your first post to get started!
+
+## Creating Posts
+
+Create markdown files in `pages/_posts/` with the format:
+
+```
+YYYY-MM-DD-your-post-title.md
+```
+
+## Recent Posts
+
+{% for post in site.posts limit:5 %}
+- [{{ post.title }}]({{ post.url }}) - {{ post.date | date: "%B %d, %Y" }}
+{% endfor %}
+
+{% if site.posts.size == 0 %}
+*No posts yet. Create your first post to see it here!*
+{% endif %}
+EOF
+}
+
+# ---------- Public renderers ------------------------------------------------
+render_admin_settings_pages() {
+    local admin_dir="$TARGET_DIR/pages/_about/settings"
+    mkdir -p "$admin_dir"
+
+    log_info "Creating admin settings pages..."
+    local page
+    for page in $(_admin_settings_pages); do
+        create_from_template "pages/admin/${page}.md.template" "$admin_dir/${page}.md" ""
+    done
+}
+
+render_starter_pages() {
+    log_info "Creating essential starter pages..."
+    mkdir -p "$TARGET_DIR/pages"
+
+    local tmpl dest mkdir_rel fb_func fallback
+    while IFS='|' read -r tmpl dest mkdir_rel fb_func; do
+        [ -z "$tmpl" ] && continue
+        [ -n "$mkdir_rel" ] && mkdir -p "$TARGET_DIR/$mkdir_rel"
+        if [ -n "$fb_func" ] && declare -f "$fb_func" >/dev/null 2>&1; then
+            fallback="$("$fb_func")"
+        else
+            fallback=""
+        fi
+        create_from_template "$tmpl" "$TARGET_DIR/$dest" "$fallback"
+    done <<MANIFEST_EOF
+$(_starter_pages_manifest)
+MANIFEST_EOF
+
+    render_admin_settings_pages
+
+    log_success "Starter pages created"
+}
+
+# Backward-compatible aliases (legacy install.sh call sites)
+create_starter_pages() { render_starter_pages "$@"; }
+create_admin_pages()   { render_admin_settings_pages "$@"; }