jekyll-theme-zer0 0.22.20 → 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/generate-roadmap.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# =============================================================================
+# generate-roadmap.rb
+# =============================================================================
+#
+# Reads `_data/roadmap.yml` and updates the README.md roadmap section in-place.
+#
+# It rewrites two regions delimited by HTML comment markers:
+#
+#   <!-- ROADMAP_MERMAID:START -->  ...  <!-- ROADMAP_MERMAID:END -->
+#   <!-- ROADMAP_TABLE:START -->    ...  <!-- ROADMAP_TABLE:END -->
+#
+# Usage:
+#   ruby scripts/generate-roadmap.rb              # update README.md in place
+#   ruby scripts/generate-roadmap.rb --check      # exit non-zero if README is stale
+#   ruby scripts/generate-roadmap.rb --stdout     # print regenerated sections only
+#
+# This script has no gem dependencies beyond the Ruby stdlib.
+# =============================================================================
+
+require 'yaml'
+require 'date'
+require 'optparse'
+
+ROOT       = File.expand_path('..', __dir__)
+DATA_FILE  = File.join(ROOT, '_data', 'roadmap.yml')
+README     = File.join(ROOT, 'README.md')
+
+MERMAID_START = '<!-- ROADMAP_MERMAID:START -->'
+MERMAID_END   = '<!-- ROADMAP_MERMAID:END -->'
+TABLE_START   = '<!-- ROADMAP_TABLE:START -->'
+TABLE_END     = '<!-- ROADMAP_TABLE:END -->'
+
+# Width used to right-pad the gantt label column so the `:status, start, end`
+# tail aligns vertically. Adjust if very long version/title combinations show up.
+GANTT_LABEL_WIDTH = 28
+
+# ---------------------------------------------------------------------------
+# Rendering helpers
+# ---------------------------------------------------------------------------
+
+# Mermaid gantt task line for a single milestone.
+#
+#   v0.22 AIEO Optimization :active, 2026-03, 2026-04
+#   v1.0  Stable Release    :milestone, 2027-01, 1d
+#
+def gantt_task(milestone)
+  label   = "v#{milestone['version']} #{milestone['title']}"
+  status  = milestone['status'].to_s
+  start   = milestone['start']
+  finish  = milestone['end'] || milestone['start']
+
+  prefix =
+    case status
+    when 'completed' then 'done, '
+    when 'active'    then 'active, '
+    when 'milestone' then 'milestone, '
+    else ''
+    end
+
+  range = status == 'milestone' ? "#{start}, 1d" : "#{start}, #{finish}"
+  "    #{label.ljust(GANTT_LABEL_WIDTH)} :#{prefix}#{range}"
+end
+
+def render_mermaid(data)
+  title      = data.dig('meta', 'title') || 'zer0-mistakes Roadmap'
+  milestones = data['milestones'] || []
+
+  # Group by section while preserving the order in which sections first appear.
+  sections = milestones.group_by { |m| m['section'] || 'Roadmap' }
+  ordered  = milestones.map { |m| m['section'] }.uniq
+
+  lines = []
+  lines << '```mermaid'
+  lines << 'gantt'
+  lines << "    title #{title}"
+  lines << '    dateFormat YYYY-MM'
+  ordered.each do |section|
+    lines << "    section #{section}"
+    sections[section].each { |m| lines << gantt_task(m) }
+  end
+  lines << '```'
+  lines.join("\n")
+end
+
+# Status → human-readable target column for the summary table.
+def target_label(milestone)
+  case milestone['status']
+  when 'completed'
+    if (released = milestone['released'])
+      Date.parse(released.to_s).strftime('%b %Y')
+    else
+      'Completed'
+    end
+  when 'active'
+    milestone['target'] || 'In progress'
+  when 'milestone', 'planned'
+    milestone['target'] || milestone['start']
+  else
+    milestone['target'] || ''
+  end
+end
+
+def render_table(data)
+  rows = (data['milestones'] || []).map do |m|
+    version  = "**v#{m['version']}**"
+    target   = target_label(m)
+    summary  = m['summary'] || ''
+    status_emoji =
+      case m['status']
+      when 'completed' then '✅ Completed'
+      when 'active'    then '🚧 In Progress'
+      when 'milestone' then '🎯 Milestone'
+      else                  '🗓 Planned'
+      end
+    "| #{version} | #{status_emoji} | #{target} | #{summary} |"
+  end
+
+  header = [
+    '| Version | Status | Target | Highlights |',
+    '|---------|--------|--------|------------|'
+  ]
+
+  (header + rows).join("\n")
+end
+
+def replace_block(content, marker_start, marker_end, replacement)
+  pattern = /(#{Regexp.escape(marker_start)})(.*?)(#{Regexp.escape(marker_end)})/m
+  unless content.match?(pattern)
+    raise "Markers not found in README: #{marker_start} ... #{marker_end}"
+  end
+
+  # Surround the replacement with blank lines so kramdown parses the following
+  # markdown (especially tables) instead of treating it as part of the HTML
+  # comment block. Without the blank line after `<!-- ... -->`, GFM tables
+  # collapse into a single paragraph.
+  content.sub(pattern, "\\1\n\n#{replacement}\n\n\\3")
+end
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main
+  options = { mode: :write }
+  OptionParser.new do |opts|
+    opts.banner = 'Usage: generate-roadmap.rb [--check|--stdout]'
+    opts.on('--check', 'Exit non-zero if README would change') { options[:mode] = :check }
+    opts.on('--stdout', 'Print regenerated sections to stdout') { options[:mode] = :stdout }
+  end.parse!
+
+  # The roadmap data only contains scalars and Date values; Symbol is not used,
+  # but Date/Time must be permitted because YAML's safe loader rejects them by default.
+  # Ruby >= 3.1 supports `permitted_classes:` on `YAML.load_file`. On older Rubies
+  # (e.g. macOS system Ruby 2.6), fall back to `safe_load` which accepted the
+  # keyword earlier, so the generator works for contributors without rbenv/rvm.
+  data =
+    begin
+      YAML.load_file(DATA_FILE, permitted_classes: [Date, Time])
+    rescue ArgumentError
+      YAML.safe_load(File.read(DATA_FILE), permitted_classes: [Date, Time], aliases: false)
+    end
+  mermaid = render_mermaid(data)
+  table   = render_table(data)
+
+  if options[:mode] == :stdout
+    puts mermaid
+    puts
+    puts table
+    return 0
+  end
+
+  original = File.read(README)
+  updated  = original.dup
+  updated  = replace_block(updated, MERMAID_START, MERMAID_END, mermaid)
+  updated  = replace_block(updated, TABLE_START,   TABLE_END,   table)
+
+  if options[:mode] == :check
+    if original == updated
+      puts '✓ README.md roadmap section is up to date with _data/roadmap.yml'
+      return 0
+    else
+      warn '✗ README.md roadmap section is out of date with _data/roadmap.yml'
+      warn '  Run: ./scripts/generate-roadmap.sh'
+      return 1
+    end
+  end
+
+  if original == updated
+    puts 'README.md roadmap section already up to date.'
+  else
+    File.write(README, updated)
+    puts "Updated README.md roadmap section from #{File.basename(DATA_FILE)}."
+  end
+  0
+end
+
+exit main if $PROGRAM_NAME == __FILE__

data/scripts/generate-roadmap.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# =============================================================================
+# generate-roadmap.sh
+# =============================================================================
+#
+# Thin wrapper around scripts/generate-roadmap.rb.
+#
+# Reads `_data/roadmap.yml` and rewrites the auto-generated roadmap regions
+# of README.md (Mermaid gantt diagram + summary table) in place.
+#
+# Usage:
+#   ./scripts/generate-roadmap.sh             # update README.md
+#   ./scripts/generate-roadmap.sh --check     # CI-friendly drift detection
+#   ./scripts/generate-roadmap.sh --stdout    # print regenerated sections only
+#
+# =============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec ruby "${SCRIPT_DIR}/generate-roadmap.rb" "$@"

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
+}