jekyll-theme-zer0 0.22.20 → 0.22.22

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# scripts/lib/install/ai/wizard.sh
+#
+# `install wizard --ai` — opt-in OpenAI-powered config generation.
+#
+# Flow:
+#   1. ai_enabled() check (ZER0_NO_AI kill-switch)
+#   2. ai_require_key() check (OPENAI_API_KEY)
+#   3. Prompt user for: site description, target audience, deploy preference
+#   4. Read system prompt from templates/ai/prompts/wizard-system.md
+#   5. ai_estimate_cost() → user sees price estimate
+#   6. ai_call_chat() → returns JSON: {title, description, tagline, navigation,
+#                                       welcome_post_outline, suggested_deploy_target}
+#   7. ai_show_diff_confirm() per generated file (_config.yml, navigation,
+#                                                  welcome post)
+#   8. On any failure → fall back to non-AI wizard (delegated to caller).
+#
+# Public API:
+#     wizard_ai_run <target_dir> <repo_root> [--auto-accept]
+#
+# Returns 0 on success, 1 on failure (caller should fall back).
+
+# shellcheck disable=SC2034
+AI_WIZARD_LIB_VERSION="1.0.0"
+
+wizard_ai_run() {
+    local target_dir="$1" repo_root="$2"
+    shift 2 || true
+
+    local auto_accept=0
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --auto-accept) auto_accept=1 ;;
+            *) log_warning "wizard_ai_run: ignoring unknown flag: $1" ;;
+        esac
+        shift
+    done
+
+    if ! ai_enabled; then
+        log_warning "AI is disabled (ZER0_NO_AI=1) — cannot run --ai wizard."
+        return 1
+    fi
+    if ! ai_require_key; then
+        return 1
+    fi
+
+    # 1. Gather user inputs
+    log_info "AI Wizard — describe your site in a sentence or two."
+    log_info "Examples: 'Personal blog about Rust performance' or 'Docs site for an open-source CLI'."
+    printf "Site description: "
+    local site_desc audience deploy_pref
+    read -r site_desc
+    if [[ -z "$site_desc" ]]; then
+        log_error "Empty description — aborting AI wizard."
+        return 1
+    fi
+    printf "Target audience (e.g., 'developers', 'data scientists', 'general'): "
+    read -r audience
+    [[ -z "$audience" ]] && audience="developers"
+    printf "Deploy preference (github-pages | azure-swa | docker-prod | unsure): "
+    read -r deploy_pref
+    [[ -z "$deploy_pref" ]] && deploy_pref="unsure"
+
+    # 2. Load system prompt
+    local sys_prompt_file="$repo_root/templates/ai/prompts/wizard-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")"
+
+    # 3. Build user prompt
+    local user_prompt
+    user_prompt="Site description: ${site_desc}
+Target audience: ${audience}
+Deploy preference: ${deploy_pref}
+
+Return ONLY a JSON object with keys: title, description, tagline, suggested_deploy_target, navigation (array of {label, url}), welcome_post_outline (string of 3-5 bullet points)."
+
+    # Sanitize (paranoid — user input could contain pasted secrets)
+    user_prompt="$(printf '%s' "$user_prompt" | ai_sanitize_text)"
+
+    # 4. Cost estimate + confirm
+    local model
+    model="$(ai_default_model wizard)"
+    local in_chars=$(( ${#system_prompt} + ${#user_prompt} ))
+    log_info "About to call OpenAI:"
+    ai_estimate_cost "$model" "$in_chars" 800
+    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
+
+    # 5. Call API
+    log_info "Calling $model ..."
+    local raw
+    if ! raw="$(ai_call_chat "$model" "$system_prompt" "$user_prompt" 1024 0.4)"; then
+        log_error "OpenAI call failed."
+        return 1
+    fi
+
+    # 6. Parse JSON (strip code-fence if present)
+    local json
+    json="$(printf '%s' "$raw" | sed -E '/^```(json)?$/d')"
+    if ! command -v python3 >/dev/null 2>&1; then
+        log_error "python3 required to parse wizard response."
+        return 1
+    fi
+
+    # Extract fields safely
+    local title description tagline suggested_deploy
+    title="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("title",""))' 2>/dev/null || echo "")"
+    description="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("description",""))' 2>/dev/null || echo "")"
+    tagline="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("tagline",""))' 2>/dev/null || echo "")"
+    suggested_deploy="$(printf '%s' "$json" | python3 -c 'import json,sys;d=json.load(sys.stdin);print(d.get("suggested_deploy_target",""))' 2>/dev/null || echo "")"
+
+    if [[ -z "$title" ]]; then
+        log_error "Failed to parse AI response (missing 'title' field)."
+        log_info  "Raw response: $raw"
+        return 1
+    fi
+
+    # 7. Build proposed _config.yml fragment + diff
+    local cfg_file="$target_dir/_config.yml"
+    local proposed
+    proposed="$(cat <<EOF
+# Generated by install wizard --ai
+title: "$title"
+description: "$description"
+tagline: "$tagline"
+EOF
+)"
+    log_info "AI suggests deploy target: ${suggested_deploy:-(none)}"
+    if [[ -f "$cfg_file" ]]; then
+        log_warning "_config.yml already exists. The AI suggestions above won't be merged automatically."
+        log_info  "Recommended: cp the values you like into _config.yml manually."
+    else
+        local accepted_path
+        if accepted_path="$(ai_show_diff_confirm "$cfg_file" "$proposed" "Create _config.yml" "$auto_accept")"; then
+            mv "$accepted_path" "$cfg_file"
+            log_success "Wrote $cfg_file"
+        fi
+    fi
+
+    # 8. Print full JSON for user reference (so welcome post outline + nav
+    #    aren't lost). User can manually convert to files.
+    echo
+    log_info "Full AI response (use these to flesh out navigation + a welcome post):"
+    echo "─────────────────────────────────────────────────────────────"
+    printf '%s\n' "$json"
+    echo "─────────────────────────────────────────────────────────────"
+
+    return 0
+}

data/scripts/lib/install/config.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# =========================================================================
+# scripts/lib/install/config.sh
+# =========================================================================
+# Configuration loader for install.sh.
+#
+# load_install_config <SCRIPT_DIR> [<SOURCE_DIR>]
+#   Searches for templates/config/install.conf in either of the supplied
+#   directories. On success: sources it, exports TEMPLATES_DIR, returns 0.
+#   On failure: applies hard-coded fallback defaults and returns 1.
+#
+# This function is identical in behaviour to the previous private
+# `_load_install_config` inside install.sh; the only change is location +
+# accepting the search roots as parameters (so the function is testable
+# without globals).
+# =========================================================================
+
+load_install_config() {
+    local script_dir="${1:-${SCRIPT_DIR:-$(pwd)}}"
+    local source_dir="${2:-${SOURCE_DIR:-$script_dir}}"
+
+    local config_paths=(
+        "$script_dir/templates/config/install.conf"
+        "$source_dir/templates/config/install.conf"
+    )
+
+    local config_path
+    for config_path in "${config_paths[@]}"; do
+        if [[ -f "$config_path" ]]; then
+            # shellcheck source=/dev/null
+            source "$config_path"
+            export TEMPLATES_DIR="$(dirname "$(dirname "$config_path")")"
+            return 0
+        fi
+    done
+
+    # Fallback defaults when templates not available (remote install
+    # without bundled templates/, or stripped distribution).
+    export THEME_NAME="${THEME_NAME:-zer0-mistakes}"
+    export THEME_GEM_NAME="${THEME_GEM_NAME:-jekyll-theme-zer0}"
+    export THEME_DISPLAY_NAME="${THEME_DISPLAY_NAME:-Zer0-Mistakes Jekyll Theme}"
+    export GITHUB_USER="${GITHUB_USER:-bamr87}"
+    export GITHUB_REPO="${GITHUB_REPO:-bamr87/zer0-mistakes}"
+    export GITHUB_URL="${GITHUB_URL:-https://github.com/bamr87/zer0-mistakes}"
+    export GITHUB_RAW_URL="${GITHUB_RAW_URL:-https://raw.githubusercontent.com/bamr87/zer0-mistakes/main}"
+    export DEFAULT_PORT="${DEFAULT_PORT:-4000}"
+    export DEFAULT_URL="${DEFAULT_URL:-http://localhost:4000}"
+    export JEKYLL_VERSION="${JEKYLL_VERSION:-~> 4.3}"
+    export FFI_VERSION="${FFI_VERSION:-~> 1.17.0}"
+    export WEBRICK_VERSION="${WEBRICK_VERSION:-~> 1.7}"
+    export COMMONMARKER_VERSION="${COMMONMARKER_VERSION:-0.23.10}"
+    export GITHUB_PAGES_MAX_VERSION="${GITHUB_PAGES_MAX_VERSION:-232}"
+    export COMMONMARKER_MACOS_VERSION="${COMMONMARKER_MACOS_VERSION:-~> 0.23}"
+    export RUBY_MIN_VERSION_MACOS="${RUBY_MIN_VERSION_MACOS:-2.6.0}"
+    return 1
+}

data/scripts/lib/install/deploy/README.md

@@ -0,0 +1,52 @@
+# scripts/lib/install/deploy/
+
+Pluggable deploy-target modules consumed by `scripts/bin/install deploy`
+(Phase 4 of the installer refactor). Each module configures one target;
+the registry coordinates discovery, dispatch, and verification.
+
+## Files
+
+| File              | Role                                                                |
+| ----------------- | ------------------------------------------------------------------- |
+| `registry.sh`     | Module discovery, dispatch, shared `deploy_render` / `deploy_copy`. |
+| `github-pages.sh` | Actions workflow that publishes `_site/` to `gh-pages`.             |
+| `azure-swa.sh`    | Azure SWA workflow + `staticwebapp.config.json`.                    |
+| `docker-prod.sh`  | Multi-stage Docker build + production compose + nginx config.       |
+
+## Module contract
+
+Every module must define:
+
+| Symbol                                  | Purpose                                                  |
+| --------------------------------------- | -------------------------------------------------------- |
+| `DEPLOY_<SLUG_UPPER>_TITLE`             | One-line display name shown by `install list-targets`.   |
+| `DEPLOY_<SLUG_UPPER>_SUMMARY`           | One-line description shown by `install list-targets`.    |
+| `deploy_<slug>_check_prereqs <dir>`     | Print warnings; return non-zero only on hard blockers.   |
+| `deploy_<slug>_install <dir>`           | Idempotent file install (uses `deploy_render_if_absent`).|
+| `deploy_<slug>_verify <dir>`            | Confirm expected files exist + look correct.             |
+| `deploy_<slug>_doc_url`                 | Print the canonical upstream documentation URL.          |
+
+Modules use the lightweight `deploy_render` placeholder set
+(`{{RUBY_VERSION}}`, `{{DEFAULT_BRANCH}}`, `{{GITHUB_USER}}`,
+`{{SITE_NAME}}`) so they can run without the full install.sh global
+environment.
+
+## Adding a target
+
+1. Add `templates/deploy/<slug>/` with the assets (workflow YAML,
+   Dockerfile, README, etc.). Use `*.template` for files that need
+   variable substitution.
+2. Create `scripts/lib/install/deploy/<slug>.sh` exporting the four
+   hooks above.
+3. Add `<slug>` to `DEPLOY_TARGETS_LIST` in `registry.sh` (alphabetical).
+4. Optionally reference `<slug>` under `deploy_targets:` in
+   `templates/profiles/*.yml` so the profile can suggest it.
+5. Update `templates/deploy/README.md` with the new target row.
+
+## CLI integration
+
+```bash
+./scripts/bin/install list-targets
+./scripts/bin/install deploy github-pages /path/to/site
+./scripts/bin/install deploy azure-swa,docker-prod /path/to/site
+```

data/scripts/lib/install/deploy/azure-swa.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/azure-swa.sh
+#
+# Deploy module: Azure Static Web Apps. Replaces the legacy
+# install.sh::create_azure_static_web_apps_workflow heredoc and adds
+# a sensible staticwebapp.config.json.
+
+DEPLOY_AZURE_SWA_TITLE="Azure Static Web Apps"
+DEPLOY_AZURE_SWA_SUMMARY="Workflow + config for Azure SWA. Requires AZURE_STATIC_WEB_APPS_API_TOKEN secret."
+
+deploy_azure_swa_check_prereqs() {
+    local target_dir="$1"
+    if [ ! -f "$target_dir/Gemfile" ]; then
+        log_warning "Gemfile not found in $target_dir — Azure build step will fail until one exists."
+    fi
+    return 0
+}
+
+deploy_azure_swa_install() {
+    local target_dir="$1"
+    local repo_root="${REPO_ROOT:-$(deploy_repo_root)}"
+    local src_dir="$repo_root/templates/deploy/azure-swa"
+
+    deploy_render_if_absent \
+        "$src_dir/azure-static-web-apps.yml.template" \
+        "$target_dir/.github/workflows/azure-static-web-apps.yml"
+
+    deploy_copy \
+        "$src_dir/staticwebapp.config.json" \
+        "$target_dir/staticwebapp.config.json"
+}
+
+deploy_azure_swa_verify() {
+    local target_dir="$1"
+    local wf="$target_dir/.github/workflows/azure-static-web-apps.yml"
+    local cfg="$target_dir/staticwebapp.config.json"
+    local ok=0
+    [ -f "$wf" ]  || { log_error "Missing $wf"; ok=1; }
+    [ -f "$cfg" ] || { log_error "Missing $cfg"; ok=1; }
+    [ "$ok" = "0" ] || return 1
+    grep -q 'Azure/static-web-apps-deploy' "$wf" || {
+        log_warning "Workflow does not reference Azure/static-web-apps-deploy"
+        return 1
+    }
+    return 0
+}
+
+deploy_azure_swa_doc_url() {
+    echo "https://learn.microsoft.com/azure/static-web-apps/"
+}

data/scripts/lib/install/deploy/docker-prod.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/docker-prod.sh
+#
+# Deploy module: self-hosted production Docker (multi-stage Ruby + Nginx).
+# Installs docker/Dockerfile.prod, docker-compose.prod.yml, docker/nginx.conf,
+# and (if absent) a .dockerignore tuned for the build context.
+
+DEPLOY_DOCKER_PROD_TITLE="Self-hosted production Docker"
+DEPLOY_DOCKER_PROD_SUMMARY="Two-stage build (Ruby builder + nginx:alpine runtime) with healthcheck + compose."
+
+deploy_docker_prod_check_prereqs() {
+    local target_dir="$1"
+    if ! command -v docker >/dev/null 2>&1; then
+        log_warning "docker CLI not found in PATH — files will be installed but you cannot build the image locally."
+    fi
+    if [ ! -f "$target_dir/Gemfile" ]; then
+        log_warning "Gemfile not found in $target_dir — Docker build will fail until one exists."
+    fi
+    return 0
+}
+
+deploy_docker_prod_install() {
+    local target_dir="$1"
+    local repo_root="${REPO_ROOT:-$(deploy_repo_root)}"
+    local src_dir="$repo_root/templates/deploy/docker-prod"
+
+    DEPLOY_SITE_NAME="${DEPLOY_SITE_NAME:-$(basename "$target_dir")}"
+
+    deploy_render_if_absent \
+        "$src_dir/Dockerfile.prod.template" \
+        "$target_dir/docker/Dockerfile.prod"
+
+    deploy_render_if_absent \
+        "$src_dir/docker-compose.prod.yml.template" \
+        "$target_dir/docker-compose.prod.yml"
+
+    deploy_copy \
+        "$src_dir/nginx.conf" \
+        "$target_dir/docker/nginx.conf"
+
+    # .dockerignore: only install when missing so we never clobber user rules.
+    if [ ! -f "$target_dir/.dockerignore" ]; then
+        deploy_copy "$src_dir/.dockerignore" "$target_dir/.dockerignore"
+    else
+        log_warning ".dockerignore already exists, leaving untouched."
+    fi
+}
+
+deploy_docker_prod_verify() {
+    local target_dir="$1"
+    local ok=0
+    for f in \
+        "$target_dir/docker/Dockerfile.prod" \
+        "$target_dir/docker-compose.prod.yml" \
+        "$target_dir/docker/nginx.conf"; do
+        if [ ! -f "$f" ]; then
+            log_error "Missing $f"
+            ok=1
+        fi
+    done
+    [ "$ok" = "0" ] || return 1
+    grep -q 'nginx:alpine' "$target_dir/docker/Dockerfile.prod" || {
+        log_warning "Dockerfile.prod is missing the nginx:alpine runtime stage"
+        return 1
+    }
+    return 0
+}
+
+deploy_docker_prod_doc_url() {
+    echo "https://docs.docker.com/compose/production/"
+}

data/scripts/lib/install/deploy/github-pages.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/github-pages.sh
+#
+# Deploy module: GitHub Pages (Actions-based, peaceiris/actions-gh-pages).
+# Generates .github/workflows/jekyll-gh-pages.yml.
+
+DEPLOY_GITHUB_PAGES_TITLE="GitHub Pages (Actions)"
+DEPLOY_GITHUB_PAGES_SUMMARY="Builds with Bundler and publishes _site/ to the gh-pages branch."
+
+deploy_github_pages_check_prereqs() {
+    local target_dir="$1"
+    if [ ! -f "$target_dir/_config.yml" ]; then
+        log_warning "_config.yml not found in $target_dir — workflow will still install but may not build."
+    fi
+    return 0
+}
+
+deploy_github_pages_install() {
+    local target_dir="$1"
+    local repo_root="${REPO_ROOT:-$(deploy_repo_root)}"
+    local src="$repo_root/templates/deploy/github-pages/jekyll-gh-pages.yml.template"
+    local dest="$target_dir/.github/workflows/jekyll-gh-pages.yml"
+
+    DEPLOY_SITE_NAME="${DEPLOY_SITE_NAME:-$(basename "$target_dir")}"
+    deploy_render_if_absent "$src" "$dest"
+}
+
+deploy_github_pages_verify() {
+    local target_dir="$1"
+    local f="$target_dir/.github/workflows/jekyll-gh-pages.yml"
+    if [ ! -f "$f" ]; then
+        log_error "Expected $f not present"
+        return 1
+    fi
+    grep -q 'peaceiris/actions-gh-pages' "$f" || {
+        log_warning "Workflow does not reference peaceiris/actions-gh-pages"
+        return 1
+    }
+    return 0
+}
+
+deploy_github_pages_doc_url() {
+    echo "https://docs.github.com/pages"
+}

data/scripts/lib/install/deploy/registry.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# scripts/lib/install/deploy/registry.sh
+#
+# Discovery + dispatch helpers for deploy target modules.
+#
+# Each module under scripts/lib/install/deploy/<slug>.sh must define the
+# four hooks below (the registry verifies presence after sourcing):
+#
+#   deploy_<slug>_check_prereqs <target_dir>
+#       Print warnings / errors. Return 0 if safe to proceed.
+#
+#   deploy_<slug>_install <target_dir>
+#       Render templates / copy files into <target_dir>. Idempotent.
+#
+#   deploy_<slug>_verify <target_dir>
+#       Confirm the install produced the expected files. Return 0 on OK.
+#
+#   deploy_<slug>_doc_url
+#       Print a single URL pointing at upstream documentation.
+#
+# A target's display name + one-line description live next to the module
+# in scripts/lib/install/deploy/<slug>.sh as `DEPLOY_<SLUG_UPPER>_TITLE`
+# and `DEPLOY_<SLUG_UPPER>_SUMMARY` (sourced via `eval`).
+#
+# Bash 3.2 compatible. No associative arrays, no mapfile.
+
+# Canonical list of supported targets (alphabetical).
+DEPLOY_TARGETS_LIST="azure-swa docker-prod github-pages"
+
+# Resolve REPO_ROOT lazily so callers can override via $1.
+deploy_repo_root() {
+    if [ -n "${REPO_ROOT:-}" ]; then
+        echo "$REPO_ROOT"
+        return 0
+    fi
+    local here
+    here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    ( cd "$here/../../.." && pwd )
+}
+
+deploy_targets_dir() {
+    local repo_root="${1:-$(deploy_repo_root)}"
+    echo "$repo_root/templates/deploy"
+}
+
+deploy_modules_dir() {
+    local repo_root="${1:-$(deploy_repo_root)}"
+    echo "$repo_root/scripts/lib/install/deploy"
+}
+
+deploy_target_known() {
+    local slug="$1" t
+    for t in $DEPLOY_TARGETS_LIST; do
+        [ "$t" = "$slug" ] && return 0
+    done
+    return 1
+}
+
+# Convert kebab-case to function-name fragment: github-pages -> github_pages
+deploy_slug_fn() {
+    echo "$1" | tr '-' '_'
+}
+
+# Convert kebab-case to upper var fragment: github-pages -> GITHUB_PAGES
+deploy_slug_var() {
+    echo "$1" | tr '[:lower:]-' '[:upper:]_'
+}
+
+# Source a target module (idempotent). Sets DEPLOY_LAST_LOADED on success.
+deploy_load_module() {
+    local slug="$1"
+    local repo_root="${2:-$(deploy_repo_root)}"
+    local module="$(deploy_modules_dir "$repo_root")/${slug}.sh"
+    if [ ! -f "$module" ]; then
+        log_error "Deploy module not found: $module"
+        return 1
+    fi
+    # shellcheck disable=SC1090
+    . "$module"
+    DEPLOY_LAST_LOADED="$slug"
+}
+
+# Print one-line summary for `install list-targets`.
+deploy_print_summary() {
+    local slug="$1"
+    local repo_root="${2:-$(deploy_repo_root)}"
+    deploy_load_module "$slug" "$repo_root" >/dev/null 2>&1 || return 0
+    local var_frag title summary
+    var_frag="$(deploy_slug_var "$slug")"
+    eval "title=\${DEPLOY_${var_frag}_TITLE:-$slug}"
+    eval "summary=\${DEPLOY_${var_frag}_SUMMARY:-(no summary)}"
+    printf '  %-13s %s\n' "$slug" "$title"
+    printf '                %s\n' "$summary"
+}
+
+# Run the four hooks for a single target.
+deploy_run_target() {
+    local slug="$1" target_dir="$2"
+    local repo_root="${3:-$(deploy_repo_root)}"
+    local fn
+
+    if ! deploy_target_known "$slug"; then
+        log_error "Unknown deploy target: $slug"
+        log_info  "Available targets: $DEPLOY_TARGETS_LIST"
+        return 1
+    fi
+
+    if [ ! -d "$target_dir" ]; then
+        log_error "Target directory does not exist: $target_dir"
+        return 1
+    fi
+
+    deploy_load_module "$slug" "$repo_root" || return 1
+    fn="$(deploy_slug_fn "$slug")"
+
+    log_info "▶ Configuring deploy target: $slug"
+
+    if ! "deploy_${fn}_check_prereqs" "$target_dir"; then
+        log_error "Prerequisite check failed for $slug"
+        return 1
+    fi
+
+    if ! "deploy_${fn}_install" "$target_dir"; then
+        log_error "Install step failed for $slug"
+        return 1
+    fi
+
+    if ! "deploy_${fn}_verify" "$target_dir"; then
+        log_warning "Verification reported issues for $slug (manual review recommended)"
+    else
+        log_success "Deploy target $slug installed successfully"
+    fi
+
+    local url
+    url="$("deploy_${fn}_doc_url" 2>/dev/null || true)"
+    [ -n "$url" ] && log_info "Documentation: $url"
+}
+
+# Lightweight renderer used by all deploy modules. Operates on a small,
+# explicit allow-list of placeholders so modules don't need to set up
+# install.sh's full global environment.
+#
+# Usage: deploy_render <template_file> <output_file>
+# Variables consulted (with defaults):
+#   DEPLOY_RUBY_VERSION   (default 3.3)
+#   DEPLOY_DEFAULT_BRANCH (default main)
+#   DEPLOY_GITHUB_USER    (default $GITHUB_USER, then $USER, then "me")
+#   DEPLOY_SITE_NAME      (default basename of target dir, then "site")
+deploy_render() {
+    local src="$1" dest="$2"
+    [ -f "$src" ] || { log_error "Template not found: $src"; return 1; }
+
+    local ruby_v branch user site
+    ruby_v="${DEPLOY_RUBY_VERSION:-3.3}"
+    branch="${DEPLOY_DEFAULT_BRANCH:-main}"
+    user="${DEPLOY_GITHUB_USER:-${GITHUB_USER:-${USER:-me}}}"
+    site="${DEPLOY_SITE_NAME:-site}"
+
+    mkdir -p "$(dirname "$dest")"
+    sed \
+        -e "s|{{RUBY_VERSION}}|${ruby_v}|g" \
+        -e "s|{{DEFAULT_BRANCH}}|${branch}|g" \
+        -e "s|{{GITHUB_USER}}|${user}|g" \
+        -e "s|{{SITE_NAME}}|${site}|g" \
+        "$src" > "$dest"
+}
+
+# Copy a file verbatim (no rendering). Skips when destination exists
+# unless DEPLOY_FORCE=1.
+deploy_copy() {
+    local src="$1" dest="$2"
+    [ -f "$src" ] || { log_error "Source not found: $src"; return 1; }
+    if [ -f "$dest" ] && [ "${DEPLOY_FORCE:-0}" != "1" ]; then
+        log_warning "Exists, skipping: ${dest}"
+        return 0
+    fi
+    mkdir -p "$(dirname "$dest")"
+    cp "$src" "$dest"
+    log_info "Wrote: ${dest}"
+}
+
+# Same as deploy_copy but for rendered templates (logs accordingly).
+deploy_render_if_absent() {
+    local src="$1" dest="$2"
+    if [ -f "$dest" ] && [ "${DEPLOY_FORCE:-0}" != "1" ]; then
+        log_warning "Exists, skipping: ${dest}"
+        return 0
+    fi
+    deploy_render "$src" "$dest" && log_info "Rendered: ${dest}"
+}