jekyll-theme-zer0 0.22.21 → 0.22.22

data/scripts/bin/test

@@ -30,11 +30,12 @@ show_usage() {
 USAGE:
     ./scripts/bin/test [OPTIONS] [TEST_SUITE]
 
-TEST SUITES:
+TEST_SUITES:
     all         Run all tests (default)
     lib         Run library unit tests only
     theme       Run theme validation tests only
     integration Run integration tests only
+    install     Run installer e2e suites only (test/test_install_*.sh)
 
 OPTIONS:
     --verbose, -v    Show detailed test output
@@ -67,7 +68,7 @@ for arg in "$@"; do
         --dry-run)
             export DRY_RUN=true
             ;;
-        all|lib|theme|integration)
+        all|lib|theme|integration|install)
             TEST_SUITE="$arg"
             ;;
         *)
@@ -161,6 +162,43 @@ run_integration_tests() {
     fi
 }
 
+# Run installer e2e tests (test/test_install_*.sh in repo root)
+run_install_tests() {
+    log_info "Running installer e2e tests..."
+
+    # Repo root is two levels up from scripts/bin/
+    local repo_root
+    repo_root="$(cd "$SCRIPTS_ROOT/.." && pwd)"
+    local install_test_dir="$repo_root/test"
+
+    if [[ ! -d "$install_test_dir" ]]; then
+        log_warning "Installer test dir not found: $install_test_dir"
+        return
+    fi
+
+    local found=false
+    for test_file in "$install_test_dir"/test_install_*.sh; do
+        [[ -f "$test_file" ]] || continue
+        found=true
+        local test_name
+        test_name=$(basename "$test_file")
+        log_info "Running installer suite: $test_name"
+
+        if bash "$test_file"; then
+            log_success "$test_name passed"
+            ((TOTAL_PASSED++)) || true
+        else
+            log_error "$test_name failed"
+            ((TOTAL_FAILED++)) || true
+        fi
+        ((TOTAL_TESTS++)) || true
+    done
+
+    if [[ "$found" == "false" ]]; then
+        log_warning "No installer test suites found (test_install_*.sh)"
+    fi
+}
+
 # Main execution
 log_info "🧪 Starting test suite: $TEST_SUITE"
 echo ""
@@ -172,6 +210,8 @@ case $TEST_SUITE in
         run_theme_tests
         echo ""
         run_integration_tests
+        echo ""
+        run_install_tests
         ;;
     lib)
         run_lib_tests
@@ -182,6 +222,9 @@ case $TEST_SUITE in
     integration)
         run_integration_tests
         ;;
+    install)
+        run_install_tests
+        ;;
 esac
 
 # Summary

data/scripts/lib/install/README.md

@@ -0,0 +1,63 @@
+# `scripts/lib/install/` — Installer Library Modules
+
+Focused modules sourced by [`install.sh`](../../../install.sh) at the repository root. Each module is self-contained and ≤ 200 lines for readability and reuse.
+
+## Modules
+
+| File | Purpose | Key Functions |
+|------|---------|----------------|
+| [`logging.sh`](logging.sh) | `log_info` / `log_success` / `log_warning` / `log_error` shim used throughout `install.sh`. | `log_info`, `log_success`, `log_warning`, `log_error` |
+| [`platform.sh`](platform.sh) | OS, Ruby version, and platform detection (bash 3.2-compatible). | `detect_os`, `detect_ruby_version`, `ruby_version_lt_27`, `needs_macos_gemfile`, `detect_platform` |
+| [`fs.sh`](fs.sh) | Idempotent file/directory copy with timestamped backups. | `copy_file_with_backup`, `copy_directory_with_backup` |
+| [`template.sh`](template.sh) | `{{VAR}}` placeholder substitution + local/remote/fallback resolution. | `render_template`, `create_from_template`, `templates_available` |
+| [`config.sh`](config.sh) | Loads `templates/config/install.conf` with hard-coded defaults as fallback. | `load_install_config` |
+| [`pages.sh`](pages.sh) | Manifest-driven starter-page renderer. Replaces 8 legacy `create_*_page` heredoc functions with one driver. | `render_starter_pages`, `render_admin_settings_pages` (+ `create_starter_pages`/`create_admin_pages` aliases) |
+| [`profile.sh`](profile.sh) | Pure-bash YAML reader for [`templates/profiles/*.yml`](../../../templates/profiles/). Bash 3.2 compatible (no yq/python). | `list_profile_names`, `profile_path`, `profile_get_scalar`, `profile_get_list`, `profile_print_summary` |
+| [`deploy/`](deploy/) | Pluggable deployment-target modules (`github-pages`, `azure-swa`, `docker-prod`) with a uniform `check_prereqs`/`install`/`verify`/`doc_url` contract. | `deploy_run_target`, `deploy_print_summary`, `deploy_render`, `deploy_copy` (see [`deploy/README.md`](deploy/README.md)) |
+
+## Loading
+
+`install.sh` sources these modules when `scripts/lib/install/` is present. When it isn't (a stripped distribution or a `curl | bash` one-liner that didn't bundle the libraries), `install.sh` falls back to inlined copies of the same functions defined at the top of the script.
+
+## CLI Entrypoint
+
+For day-to-day use prefer the canonical dispatcher:
+
+```bash
+./scripts/bin/install help            # subcommand index
+./scripts/bin/install init            # full install in CWD
+./scripts/bin/install init --profile minimal /tmp/demo
+./scripts/bin/install list-profiles   # available profiles
+./scripts/bin/install list-targets    # available deploy targets
+./scripts/bin/install deploy github-pages /tmp/demo
+./scripts/bin/install deploy azure-swa,docker-prod /tmp/demo
+./scripts/bin/install agents          # AGENTS.md / instructions index
+./scripts/bin/install version         # theme version from version.rb
+```
+
+`init` translates `--profile` into the appropriate legacy flag and execs `install.sh`. `deploy` dispatches to the modules under `deploy/` (Phase 4). The remaining subcommands (`wizard`, `diagnose`, `doctor`, `upgrade`) are stubs that print a clear notice until their backing modules land in Phases 5-6.
+
+## Roadmap
+
+Phases 1, 1.5, 2, 3 (declarative profiles), and 4 (deploy modules) are complete. Future phases will add:
+
+- `bootstrap.sh` — remote install (`download_theme_files`, `cleanup_temp_dir`)
+- `wizard.sh` — interactive prompts (`gather_user_input`, `prompt_with_default`)
+- `ai/{wizard,diagnose,suggest}.sh` — opt-in AI integration
+- `doctor.sh` — pre-flight environment + site health checks
+
+See the session refactor plan for the full sequence.
+
+## Compatibility
+
+All modules target **bash 3.2** (the macOS default `/bin/bash`). No `declare -A`, no `=~` capture groups, no `mapfile`/`readarray`.
+
+## Conventions
+
+- Every function documents its required globals at the top of the file
+- No module calls `exit` — caller decides; modules return non-zero on recoverable failure
+- Modules don't `set -euo pipefail` themselves — they inherit from the caller (`install.sh` already sets it)
+
+---
+
+**Last updated**: 2026-04-20 — Phase 4 (`deploy/registry.sh` + `deploy/{github-pages,azure-swa,docker-prod}.sh` + `templates/deploy/`).

data/scripts/lib/install/agents.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# scripts/lib/install/agents.sh
+#
+# `install agents` — copy AI agent guidance files into a target site.
+#
+# Pure file copy. No network. No AI calls. Source of truth is the theme
+# repo's own .github/ + AGENTS.md, so the theme is self-canonical:
+# whatever the theme dogfoods is what consumers receive.
+#
+# Public API:
+#     agents_install <target_dir> <repo_root> [--cursor] [--claude] [--aider] [--force]
+#
+# Always installs the core set (AGENTS.md + .github/copilot-instructions.md
+# + .github/instructions/ + .github/prompts/). Optional flags add:
+#   --cursor   .cursor/commands/*.md  (mirrors prompts as slash commands)
+#   --claude   CLAUDE.md stub pointing to AGENTS.md
+#   --aider    .aider.conf.yml referencing AGENTS.md as read-only context
+#
+# Idempotent: skips files that already exist unless --force.
+
+# shellcheck disable=SC2034  # script intended to be sourced
+AGENTS_LIB_VERSION="1.0.0"
+
+# Copy a single file with skip/force semantics. Returns 0 on copy, 1 on skip.
+_agents_copy_file() {
+    local src="$1" dst="$2" force="$3"
+    if [[ ! -f "$src" ]]; then
+        log_warning "Source not found, skipping: ${src#$REPO_ROOT/}"
+        return 1
+    fi
+    if [[ -f "$dst" ]] && [[ "$force" != "1" ]]; then
+        log_warning "Exists, skipping: ${dst#$PWD/}  (use --force to overwrite)"
+        return 1
+    fi
+    mkdir -p "$(dirname "$dst")"
+    cp "$src" "$dst"
+    log_success "Wrote ${dst#$PWD/}"
+    return 0
+}
+
+# Copy every file in a source dir matching a glob into a dest dir.
+_agents_copy_glob() {
+    local src_dir="$1" pattern="$2" dst_dir="$3" force="$4"
+    local copied=0 skipped=0
+    if [[ ! -d "$src_dir" ]]; then
+        log_warning "Source dir not found: ${src_dir#$REPO_ROOT/}"
+        return 0
+    fi
+    local f base
+    for f in "$src_dir"/$pattern; do
+        [[ -f "$f" ]] || continue
+        base="$(basename "$f")"
+        if _agents_copy_file "$f" "$dst_dir/$base" "$force"; then
+            copied=$((copied+1))
+        else
+            skipped=$((skipped+1))
+        fi
+    done
+    log_info "  → $copied copied, $skipped skipped in ${dst_dir#$PWD/}"
+}
+
+agents_install() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local with_cursor=0 with_claude=0 with_aider=0 force=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --cursor) with_cursor=1 ;;
+            --claude) with_claude=1 ;;
+            --aider)  with_aider=1 ;;
+            --all)    with_cursor=1; with_claude=1; with_aider=1 ;;
+            -f|--force) force=1 ;;
+            *) log_warning "agents_install: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    if [[ ! -d "$target_dir" ]]; then
+        log_error "Target directory does not exist: $target_dir"
+        return 1
+    fi
+
+    log_info "Installing AI agent guidance into: $target_dir"
+    [[ "$force" = "1" ]] && log_info "  (--force: overwrite enabled)"
+
+    # 1. Core: AGENTS.md (cross-tool entry point)
+    _agents_copy_file "$repo_root/AGENTS.md" "$target_dir/AGENTS.md" "$force" || true
+
+    # 2. Copilot main instructions
+    _agents_copy_file \
+        "$repo_root/.github/copilot-instructions.md" \
+        "$target_dir/.github/copilot-instructions.md" \
+        "$force" || true
+
+    # 3. File-scoped instructions
+    log_info "Copying .github/instructions/*.md ..."
+    _agents_copy_glob \
+        "$repo_root/.github/instructions" "*.md" \
+        "$target_dir/.github/instructions" "$force"
+
+    # 4. Reusable prompts
+    log_info "Copying .github/prompts/*.md ..."
+    _agents_copy_glob \
+        "$repo_root/.github/prompts" "*.md" \
+        "$target_dir/.github/prompts" "$force"
+
+    # 5. Optional: Cursor slash-commands
+    if [[ "$with_cursor" = "1" ]]; then
+        log_info "Copying .cursor/commands/*.md ..."
+        _agents_copy_glob \
+            "$repo_root/.cursor/commands" "*.md" \
+            "$target_dir/.cursor/commands" "$force"
+    fi
+
+    # 6. Optional: Claude stub
+    if [[ "$with_claude" = "1" ]]; then
+        local claude_tpl="$repo_root/templates/agents/CLAUDE.md.template"
+        if [[ -f "$claude_tpl" ]]; then
+            _agents_copy_file "$claude_tpl" "$target_dir/CLAUDE.md" "$force" || true
+        else
+            cat > "$target_dir/CLAUDE.md.tmp" <<'EOF'
+# Claude Code Instructions
+
+This project uses [`AGENTS.md`](./AGENTS.md) as the single source of truth for
+AI agent guidance. Please read it first.
+
+For detailed conventions, see:
+- `.github/copilot-instructions.md`
+- `.github/instructions/*.instructions.md`
+- `.github/prompts/*.prompt.md`
+EOF
+            if [[ -f "$target_dir/CLAUDE.md" ]] && [[ "$force" != "1" ]]; then
+                rm -f "$target_dir/CLAUDE.md.tmp"
+                log_warning "Exists, skipping: CLAUDE.md (use --force to overwrite)"
+            else
+                mv "$target_dir/CLAUDE.md.tmp" "$target_dir/CLAUDE.md"
+                log_success "Wrote CLAUDE.md"
+            fi
+        fi
+    fi
+
+    # 7. Optional: Aider config
+    if [[ "$with_aider" = "1" ]]; then
+        local aider_tpl="$repo_root/templates/agents/aider.conf.yml.template"
+        if [[ -f "$aider_tpl" ]]; then
+            _agents_copy_file "$aider_tpl" "$target_dir/.aider.conf.yml" "$force" || true
+        else
+            if [[ -f "$target_dir/.aider.conf.yml" ]] && [[ "$force" != "1" ]]; then
+                log_warning "Exists, skipping: .aider.conf.yml (use --force to overwrite)"
+            else
+                cat > "$target_dir/.aider.conf.yml" <<'EOF'
+# Aider configuration — see https://aider.chat
+# Loads project agent guidance as read-only context for every session.
+read:
+  - AGENTS.md
+  - .github/copilot-instructions.md
+EOF
+                log_success "Wrote .aider.conf.yml"
+            fi
+        fi
+    fi
+
+    log_success "Agent guidance installation complete."
+    return 0
+}

data/scripts/lib/install/ai/diagnose.sh

@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# scripts/lib/install/ai/diagnose.sh
+#
+# `install diagnose [--ai]` — Jekyll build / runtime error analysis.
+#
+# Two modes:
+#
+# 1. Rule-based (default, no network). Pattern-matches a curated list of
+#    known errors against a build log and prints structured fixes.
+#
+# 2. AI-assisted (`--ai`). Sends a sanitized error log + the most relevant
+#    config files to OpenAI, returns a unified diff for user review.
+#
+# Public API:
+#     diagnose_run <target_dir> <repo_root> [--log <file>] [--ai] [--auto-accept]
+#
+# If --log is not provided, runs `jekyll build` once and captures output.
+
+# shellcheck disable=SC2034
+AI_DIAGNOSE_LIB_VERSION="1.0.0"
+
+# ----- Rule-based pattern table --------------------------------------------
+# Each rule: [pattern_regex] [short_label] [explanation+fix]
+# Order matters — first match wins. Keep patterns specific.
+_diagnose_rules() {
+    cat <<'EOF'
+theme could not be found|MISSING_THEME|The Jekyll theme gem is not installed. Run `bundle install` (or `bundle update jekyll-theme-zer0`) and confirm the gem name in _config.yml matches your Gemfile entry.
+Address already in use|PORT_IN_USE|Port 4000 is already bound. Either stop the existing process (`lsof -ti :4000 | xargs kill`) or run on a different port (`bundle exec jekyll serve --port 4001`).
+You have requested:.*Could not find compatible versions|GEM_VERSION_CONFLICT|A gem version constraint cannot be satisfied. Run `bundle update` to refresh the lockfile, or pin to compatible versions in your Gemfile.
+Liquid Exception:.*Could not locate the included file|MISSING_INCLUDE|A `{% include %}` tag references a file that doesn't exist. Verify the path inside `_includes/` and check for typos.
+Liquid Exception|LIQUID_ERROR|A Liquid template raised an error. Check the file path printed above the exception and look for unmatched tags ({% if %} without {% endif %}, etc.).
+SassC::SyntaxError|SASS_SYNTAX|Sass compilation failed. Review the file/line printed in the error and check for missing semicolons, unclosed braces, or invalid @import paths.
+No such file or directory @ rb_sysopen|MISSING_FILE|Jekyll tried to open a file that doesn't exist. Common causes: deleted but still referenced in _config.yml or front matter; typo in include path.
+incompatible character encodings|ENCODING_ISSUE|A file has mixed encodings. Re-save the offending file as UTF-8 without BOM.
+EOF
+}
+
+_diagnose_rule_based() {
+    local log_file="$1"
+    local matched=0 line key label fix
+    while IFS='|' read -r pattern label fix; do
+        [[ -z "$pattern" ]] && continue
+        if grep -qE "$pattern" "$log_file" 2>/dev/null; then
+            log_info "Matched rule: $label"
+            echo "  ↳ $fix"
+            echo
+            matched=$((matched+1))
+        fi
+    done < <(_diagnose_rules)
+
+    if [[ "$matched" = "0" ]]; then
+        log_warning "No known patterns matched. Re-run with --ai for AI analysis (requires OPENAI_API_KEY)."
+        return 1
+    fi
+    log_success "Matched $matched rule(s)."
+    return 0
+}
+
+_diagnose_capture_build_log() {
+    local target_dir="$1" log_file="$2"
+    log_info "Running 'jekyll build' to capture errors ..."
+    (
+        cd "$target_dir" || exit 1
+        if [[ -f Gemfile ]] && command -v bundle >/dev/null 2>&1; then
+            bundle exec jekyll build 2>&1 | tee "$log_file"
+        elif command -v jekyll >/dev/null 2>&1; then
+            jekyll build 2>&1 | tee "$log_file"
+        else
+            echo "neither bundler nor jekyll is installed" > "$log_file"
+            return 1
+        fi
+    ) || true
+}
+
+_diagnose_ai() {
+    local log_file="$1" target_dir="$2" repo_root="$3" auto_accept="$4"
+
+    if ! ai_enabled; then
+        log_warning "AI is disabled (ZER0_NO_AI=1) — using rule-based mode only."
+        return 1
+    fi
+    if ! ai_require_key; then
+        return 1
+    fi
+
+    local sys_prompt_file="$repo_root/templates/ai/prompts/diagnose-system.md"
+    if [[ ! -f "$sys_prompt_file" ]]; then
+        log_error "System prompt missing: $sys_prompt_file"
+        return 1
+    fi
+    local system_prompt
+    system_prompt="$(cat "$sys_prompt_file")"
+
+    # Build sanitized context (last 80 lines of log + _config.yml + Gemfile)
+    local sanitized_log sanitized_cfg sanitized_gem
+    sanitized_log="$(tail -n 80 "$log_file" | ai_sanitize_text)"
+    if [[ -f "$target_dir/_config.yml" ]]; then
+        sanitized_cfg="$(ai_sanitize_text < "$target_dir/_config.yml")"
+    else
+        sanitized_cfg="(missing)"
+    fi
+    if [[ -f "$target_dir/Gemfile" ]]; then
+        sanitized_gem="$(ai_sanitize_text < "$target_dir/Gemfile")"
+    else
+        sanitized_gem="(missing)"
+    fi
+
+    local user_prompt="===== BUILD LOG (last 80 lines) =====
+${sanitized_log}
+
+===== _config.yml =====
+${sanitized_cfg}
+
+===== Gemfile =====
+${sanitized_gem}
+
+Diagnose the failure and propose a minimal fix. If a file change is needed, output a unified diff. Be concise."
+
+    local model
+    model="$(ai_default_model diagnose)"
+    local in_chars=$(( ${#system_prompt} + ${#user_prompt} ))
+    log_info "About to call OpenAI:"
+    ai_estimate_cost "$model" "$in_chars" 600
+
+    if [[ "$auto_accept" != "1" ]]; then
+        printf "Proceed with API call? [y/N] "
+        local go
+        read -r go
+        if [[ ! "$go" =~ ^[Yy]$ ]]; then
+            log_warning "Aborted by user."
+            return 1
+        fi
+    fi
+
+    log_info "Calling $model ..."
+    local resp
+    if ! resp="$(ai_call_chat "$model" "$system_prompt" "$user_prompt" 800 0.2)"; then
+        log_error "OpenAI call failed."
+        return 1
+    fi
+
+    echo
+    log_info "AI diagnosis:"
+    echo "─────────────────────────────────────────────────────────────"
+    printf '%s\n' "$resp"
+    echo "─────────────────────────────────────────────────────────────"
+    log_info "If the response includes a unified diff, save it to a file and apply with: patch -p0 < fix.diff"
+    return 0
+}
+
+diagnose_run() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local log_file="" use_ai=0 auto_accept=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --log) log_file="${2:-}"; shift ;;
+            --ai)  use_ai=1 ;;
+            --auto-accept) auto_accept=1 ;;
+            *) log_warning "diagnose_run: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    if [[ ! -d "$target_dir" ]]; then
+        log_error "Target directory does not exist: $target_dir"
+        return 1
+    fi
+
+    local cleanup_log=0
+    if [[ -z "$log_file" ]]; then
+        log_file="$(mktemp)"
+        cleanup_log=1
+        _diagnose_capture_build_log "$target_dir" "$log_file"
+    fi
+
+    if [[ ! -f "$log_file" ]]; then
+        log_error "Log file not found: $log_file"
+        [[ "$cleanup_log" = "1" ]] && rm -f "$log_file"
+        return 1
+    fi
+
+    log_info "Diagnosing build log ($(wc -l < "$log_file" | tr -d ' ') lines) ..."
+    echo
+
+    # Always run rule-based first
+    local rule_result=0
+    _diagnose_rule_based "$log_file" || rule_result=1
+
+    # AI if requested
+    if [[ "$use_ai" = "1" ]]; then
+        echo
+        _diagnose_ai "$log_file" "$target_dir" "$repo_root" "$auto_accept" || true
+    fi
+
+    [[ "$cleanup_log" = "1" ]] && rm -f "$log_file"
+    return $rule_result
+}