jekyll-theme-zer0 1.8.2 → 1.9.1

data/scripts/install/ai/prompts/wizard.system.md

@@ -0,0 +1,142 @@
+# zer0-mistakes AI Installation Wizard
+
+You are the **zer0-mistakes installer wizard**. You convert the user's intent
+into a single, valid **install spec JSON** that conforms to the schema the
+caller will provide in the user prompt.
+
+You NEVER write files yourself. You ONLY emit a JSON spec. The installer's
+`apply.sh` is the sole writer.
+
+---
+
+## Hard constraints (do not violate)
+
+1. **Output ONLY one JSON object.** No prose. No explanations. No markdown
+   fences (no triple-backticks). The first character of your reply MUST be
+   `{` and the last MUST be `}`.
+2. **Conform exactly to the provided schema.** All `required` keys must be
+   present. All enums must match. `additionalProperties: false` is enforced.
+3. **Honor every value the user already provided** in the "Key info" block of
+   the user prompt — copy them through unchanged. Only fill in fields the
+   user left as `not set`.
+4. **Always include `schema_version: "1"`**, the supplied `target_dir`, and
+   a complete `options` object (all 5 required keys: `dry_run`, `force`,
+   `backup`, `non_interactive`, `output`).
+5. **`tasks` MUST be non-empty and end with `"marker"`.**
+6. **Be decisive.** If information is ambiguous, pick the most reasonable
+   default and move on. Do not ask follow-up questions in non-interactive
+   mode.
+
+---
+
+## Profile selection (decision rules)
+
+Pick the **single** profile that best matches the user's stated purpose:
+
+| Signal in user input                                     | Profile        |
+| -------------------------------------------------------- | -------------- |
+| "blog", "posts", "writing", "articles", "newsletter"     | `blog`         |
+| "documentation", "API docs", "manual", "knowledge base"  | `docs`         |
+| "portfolio", "resume", "showcase", "personal site"       | `portfolio`    |
+| "GitHub project page", "open source readme site"         | `github-pages` |
+| "fork the theme", "customize the theme itself"           | `fork`         |
+| "tiny", "minimal", "barebones", "just the basics"        | `minimal`      |
+| anything else / unclear                                  | `default`      |
+
+If a flag in "Key info" already names a profile, USE IT — do not second-guess.
+
+---
+
+## Task defaults (per profile)
+
+If you are unsure which tasks to enable, use these defaults. `marker` is
+always last.
+
+- `minimal`:      `["config", "gemfile", "gitignore", "marker"]`
+- `default`:      `["config", "gemfile", "docker", "pages", "nav", "data", "gitignore", "readme", "agents", "marker"]`
+- `blog`:         `["config", "gemfile", "docker", "pages", "nav", "data", "devcontainer", "gitignore", "readme", "agents", "marker"]`
+- `docs`:         same as `blog`
+- `portfolio`:    same as `default`
+- `github-pages`: `["config", "gemfile", "pages", "nav", "data", "gitignore", "readme", "agents", "marker"]`
+- `fork`:         `["config", "gemfile", "docker", "theme", "pages", "nav", "data", "devcontainer", "gitignore", "readme", "agents", "marker"]`
+
+---
+
+## Deploy target heuristics
+
+Populate `deploy` (array, may be empty) based on signals:
+
+- User mentions GitHub Pages, `github.io`, or `enable_pages: true` → include `"github-pages"`.
+- User mentions Netlify → include `"netlify"`.
+- User mentions Vercel → include `"vercel"`.
+- User mentions Cloudflare Pages → include `"cloudflare-pages"`.
+- User mentions self-hosting, "production Docker", or VPS → include `"docker-prod"`.
+- User mentions Azure (Static Web Apps) → include `"azure-swa"`.
+- No deploy signals AND profile is `github-pages` → default to `["github-pages"]`.
+- No signals otherwise → empty array `[]`.
+
+---
+
+## Agent file heuristics
+
+Populate `agents` (array, may be empty) based on signals:
+
+- User mentions Copilot, GitHub Copilot, or VS Code AI → include `"copilot"`.
+- User mentions Cursor → include `"cursor"`.
+- User mentions Claude, Claude Code, Anthropic → include `"claude"`.
+- User mentions Aider → include `"aider"`.
+- User mentions "AI agents", "agent files", or wants cross-tool support → include `"generic"` (writes AGENTS.md).
+- If user says "all agents" → `["generic", "copilot", "claude", "cursor", "aider"]`.
+- If unclear but AI was clearly invoked → default to `["generic", "copilot"]`.
+- If the user explicitly says "no AI files" or similar → `[]`.
+
+---
+
+## Theme source
+
+- Profile `github-pages` → `theme.source = "remote"`.
+- Profile `fork` → `theme.source = "vendored"`.
+- Everything else → `theme.source = "gem"` (default).
+
+---
+
+## Required output shape (example)
+
+The example below is illustrative. Adapt every value to the user's request.
+The exact field set is enforced by the schema in the user prompt.
+
+```
+{
+  "schema_version": "1",
+  "target_dir": "/abs/path/from/user/prompt",
+  "profile": "blog",
+  "site": {
+    "title": "Travel Stories",
+    "description": "A travel blog built with zer0-mistakes",
+    "url": "",
+    "author": "Jane Doe",
+    "email": "",
+    "timezone": "UTC",
+    "locale": "en"
+  },
+  "github": {
+    "user": "janedoe",
+    "repo": "travel-blog",
+    "pages_branch": "gh-pages",
+    "enable_pages": true
+  },
+  "theme": { "source": "gem", "version": "" },
+  "tasks": ["config", "gemfile", "docker", "pages", "nav", "data", "devcontainer", "gitignore", "readme", "agents", "marker"],
+  "deploy": ["github-pages"],
+  "agents": ["generic", "copilot"],
+  "options": {
+    "dry_run": false,
+    "force": false,
+    "backup": true,
+    "non_interactive": true,
+    "output": "human"
+  }
+}
+```
+
+(Do NOT include surrounding triple-backtick fences. Emit only the raw JSON object.)

data/scripts/install/ai/suggest.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/ai/suggest.sh — AI-assisted profile + deploy suggestions
+# =============================================================================
+# Given a target directory and optional goal description, suggests:
+#   - Best installation profile
+#   - Best deploy target(s)
+#
+# Provides:
+#   ai_suggest_run TARGET_DIR [GOAL_TEXT]
+#       → print JSON: {"profile":"...", "deploy":["..."]}
+#
+# Bash 3.2 compatible. No set -euo pipefail here.
+# =============================================================================
+[[ -n "${_HAS_AI_SUGGEST:-}" ]] && return 0
+_HAS_AI_SUGGEST=1
+
+_AI_SUGGEST_DIR="${_AI_SUGGEST_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd)}"
+
+ai_suggest_run() {
+    local target="${1:-$(pwd)}"
+    local goal="${2:-}"
+
+    if [[ "$(type -t ai_client_available)" != "function" ]]; then
+        source "${_AI_SUGGEST_DIR}/client.sh" || return 1
+    fi
+
+    if ! ai_client_available; then
+        log_warning "ai_suggest: AI not available — using rule-based defaults"
+        printf '{"profile":"default","deploy":["github-pages"]}\n'
+        return 0
+    fi
+
+    local sys_prompt_file="${_AI_SUGGEST_DIR}/prompts/suggest.system.md"
+    local sys_prompt
+    if [[ -f "$sys_prompt_file" ]]; then
+        sys_prompt=$(cat "$sys_prompt_file")
+    else
+        sys_prompt="You are a Jekyll setup advisor. Based on the user's goal and context, recommend the best zer0-mistakes profile and deploy target. Profiles: default, minimal, blog, docs, portfolio, github-pages, fork. Deploy targets: github-pages, azure-swa, docker-prod, vercel, netlify, cloudflare-pages. Return JSON: {\"profile\":\"...\",\"deploy\":[\"...\"]}."
+    fi
+
+    local user_prompt
+    user_prompt="Target directory: $target"
+    [[ -n "$goal" ]] && user_prompt="${user_prompt}
+Goal: $goal"
+
+    # Use json_object mode to prevent markdown wrapping
+    local resp
+    resp=$(ai_client_chat "$sys_prompt" "$user_prompt" '{"name":"suggest","schema":{"type":"object","properties":{"profile":{"type":"string"},"deploy":{"type":"array","items":{"type":"string"}},"rationale":{"type":"string"}},"required":["profile","deploy"]}}') || {
+        printf '{"profile":"default","deploy":["github-pages"]}\n'
+        return 0
+    }
+
+    local result
+    result=$(ai_client_extract_text "$resp")
+    printf '%s\n' "$result"
+}

data/scripts/install/ai/wizard.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/ai/wizard.sh — AI-driven spec generator
+# =============================================================================
+# Conversations with an LLM to gather site requirements and emit a valid
+# install spec JSON. The AI is constrained to the spec.schema.json contract.
+#
+# The AI NEVER writes files. It returns a spec JSON only. apply.sh is the
+# sole writer.
+#
+# Provides:
+#   ai_wizard_run TARGET_DIR
+#       → populate SPEC_* globals from AI-generated spec
+#       → write spec to $(spec_path TARGET_DIR)
+#       → return 0 on success
+#
+# Environment:
+#   OPENAI_API_KEY / OPENAI_BASE_URL — see ai/client.sh
+#   ZER0_NO_AI=1  — disable AI (returns error)
+#
+# Bash 3.2 compatible. No set -euo pipefail here.
+# =============================================================================
+[[ -n "${_HAS_AI_WIZARD:-}" ]] && return 0
+_HAS_AI_WIZARD=1
+
+_AI_WIZARD_DIR="${_AI_WIZARD_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd)}"
+
+ai_wizard_run() {
+    local target="$1"
+    [[ -z "$target" ]] && target="$(pwd)"
+
+    # Source client
+    if [[ "$(type -t ai_client_available)" != "function" ]]; then
+        local client="${_AI_WIZARD_DIR}/client.sh"
+        [[ -f "$client" ]] || { log_error "ai/client.sh not found"; return 1; }
+        # shellcheck source=./client.sh
+        source "$client"
+    fi
+
+    if ! ai_client_available; then
+        log_error "AI wizard requires OPENAI_API_KEY or OPENAI_BASE_URL"
+        return 1
+    fi
+
+    # Load system prompt
+    local sys_prompt_file="${_AI_WIZARD_DIR}/prompts/wizard.system.md"
+    local sys_prompt
+    if [[ -f "$sys_prompt_file" ]]; then
+        sys_prompt=$(cat "$sys_prompt_file")
+    else
+        sys_prompt="You are the zer0-mistakes installer wizard. Ask the user questions to gather site requirements, then output a valid install spec JSON matching the provided schema. Output only the JSON object, no prose."
+    fi
+
+    # Load schema for reference (shown to AI in prompt, not as structured output)
+    local schema_file="${_AI_WIZARD_DIR}/prompts/spec.schema.json"
+    local schema_hint=""
+    [[ -f "$schema_file" ]] && schema_hint=$(cat "$schema_file")
+
+    # Build user context prompt
+    local user_prompt
+    user_prompt=$(cat <<PROMPT
+Target directory: $target
+Platform: $(uname -s) $(uname -m)
+Current user: $(id -un 2>/dev/null || echo "unknown")
+
+Please generate the install spec JSON for my zer0-mistakes Jekyll site.
+
+Key info:
+- Profile preference: ${SPEC_PROFILE:-not set}
+- Site title: ${SPEC_SITE_TITLE:-not set}
+- GitHub username: ${SPEC_GITHUB_USER:-not set}
+- Deploy preference: ${SPEC_DEPLOY:-not set}
+- AI agents needed: ${SPEC_AGENTS:-not set}
+
+The JSON must conform to this schema:
+${schema_hint}
+
+Output ONLY the JSON object, no prose, no markdown fences.
+PROMPT
+)
+
+    log_banner "AI Installation Wizard"
+    log_info "Connecting to AI... (model: ${OPENAI_MODEL:-gpt-4o-mini})"
+
+    local resp
+    resp=$(ai_client_chat "$sys_prompt" "$user_prompt")
+    local ret=$?
+
+    if [[ $ret -ne 0 ]]; then
+        log_error "AI wizard: API call failed"
+        return 1
+    fi
+
+    # Extract JSON spec from response
+    local spec_json
+    spec_json=$(ai_client_extract_text "$resp")
+
+    if [[ -z "$spec_json" ]]; then
+        log_error "AI wizard: empty response"
+        return 1
+    fi
+
+    # Write spec to temp file and read it
+    local tmp
+    tmp=$(mktemp /tmp/zer0-ai-spec-XXXXXX.json)
+    printf '%s\n' "$spec_json" > "$tmp"
+
+    if spec_validate "$tmp"; then
+        log_success "AI generated a valid spec"
+        # Populate globals
+        spec_read "$tmp"
+        # Override target dir (AI may not know the exact local path)
+        SPEC_TARGET_DIR="$target"
+        export SPEC_TARGET_DIR
+        # If AI omitted deploy/agents, fall back to profile defaults so the
+        # user still gets sensible files. CLI flags then win below.
+        if [[ -z "${SPEC_DEPLOY:-}" || -z "${SPEC_AGENTS:-}" ]]; then
+            local _profile_file="${TEMPLATES_DIR:-}/profiles/${SPEC_PROFILE:-default}.yml"
+            if [[ -f "$_profile_file" && "$(type -t plan_load_profile)" == "function" ]]; then
+                local _saved_deploy="$SPEC_DEPLOY"
+                local _saved_agents="$SPEC_AGENTS"
+                SPEC_DEPLOY=""; SPEC_AGENTS=""
+                plan_load_profile "$_profile_file" 2>/dev/null || true
+                [[ -n "$_saved_deploy" ]] && SPEC_DEPLOY="$_saved_deploy"
+                [[ -n "$_saved_agents" ]] && SPEC_AGENTS="$_saved_agents"
+            fi
+        fi
+        # Re-apply CLI flags so user-provided --site-title, --github-user, etc.
+        # always win over AI guesses.
+        if [[ "$(type -t plan_apply_flags)" == "function" ]]; then
+            plan_apply_flags
+        fi
+        # Apply platform defaults
+        plan_apply_platform
+        # Record AI metadata
+        SPEC_AI_USED=true
+        SPEC_AI_PROVIDER="${OPENAI_PROVIDER:-openai}"
+        SPEC_AI_MODEL="${OPENAI_MODEL:-gpt-4o-mini}"
+        export SPEC_AI_USED SPEC_AI_PROVIDER SPEC_AI_MODEL
+        # Write final spec
+        spec_write "$(spec_path "$target")"
+        rm -f "$tmp"
+        return 0
+    else
+        log_error "AI returned an invalid spec. Review: $tmp"
+        log_warning "Falling back to interactive wizard..."
+        rm -f "$tmp"
+        return 1
+    fi
+}

data/scripts/install/apply.sh

@@ -0,0 +1,156 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/apply.sh — Execute an install spec
+# =============================================================================
+# apply.sh is THE ONLY WRITER in the installer. All tasks call fs.sh and
+# template.sh — never write directly.
+#
+# Provides:
+#   apply_run SPEC_FILE
+#       Read spec, run doctor (unless skip_doctor), execute task sequence,
+#       write marker on success.
+#
+#   apply_task TASK_NAME TARGET_DIR
+#       Source and execute a single task from scripts/install/tasks/TASK.sh
+#
+# Bash 3.2 compatible. No set -euo pipefail here.
+# =============================================================================
+[[ -n "${_HAS_APPLY_LIB:-}" ]] && return 0
+_HAS_APPLY_LIB=1
+
+# Directory where task modules live
+_APPLY_TASKS_DIR="${_APPLY_TASKS_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd)/tasks}"
+
+# ---------------------------------------------------------------------------
+# apply_task TASK TARGET_DIR — source and run one task
+# ---------------------------------------------------------------------------
+apply_task() {
+    local task="$1"
+    local target="$2"
+    local task_file="${_APPLY_TASKS_DIR}/${task}.sh"
+
+    if [[ ! -f "$task_file" ]]; then
+        log_warning "apply_task: task not found: $task (skipping)"
+        return 0
+    fi
+
+    log_step "Task: $task"
+    # shellcheck source=/dev/null
+    source "$task_file"
+
+    local fn_name="task_${task}_run"
+    if [[ "$(type -t "$fn_name")" != "function" ]]; then
+        log_error "apply_task: task file $task_file does not define $fn_name"
+        log_step_done
+        return 1
+    fi
+
+    "$fn_name" "$target"
+    local ret=$?
+    log_step_done
+
+    return $ret
+}
+
+# ---------------------------------------------------------------------------
+# apply_run SPEC_FILE
+# ---------------------------------------------------------------------------
+apply_run() {
+    local spec_file="$1"
+
+    if [[ ! -f "$spec_file" ]]; then
+        log_error "apply_run: spec file not found: $spec_file"
+        return 1
+    fi
+
+    # Load spec into SPEC_* globals
+    spec_read "$spec_file"
+
+    local target="${SPEC_TARGET_DIR:-}"
+    if [[ -z "$target" ]]; then
+        log_error "apply_run: spec.target_dir is empty"
+        return 1
+    fi
+
+    # Sync option globals → fs.sh and prompt.sh
+    [[ "$SPEC_OPT_DRY_RUN" == "true" ]]         && _FS_DRY_RUN=1    || _FS_DRY_RUN=0
+    [[ "$SPEC_OPT_FORCE" == "true" ]]             && _FS_FORCE=1      || _FS_FORCE=0
+    [[ "$SPEC_OPT_BACKUP" == "false" ]]           && _FS_BACKUP=0     || _FS_BACKUP=1
+    [[ "$SPEC_OPT_VERBOSE" == "true" ]]           && _LOG_VERBOSE=1   || _LOG_VERBOSE=0
+    [[ "$SPEC_OPT_NON_INTERACTIVE" == "true" ]]   && _PROMPT_NON_INTERACTIVE=1 || _PROMPT_NON_INTERACTIVE=0
+    [[ "$SPEC_OPT_AUTO_ACCEPT" == "true" ]]       && _PROMPT_AUTO_ACCEPT=1     || _PROMPT_AUTO_ACCEPT=0
+    [[ "$SPEC_OPT_OUTPUT" == "json" ]]            && _LOG_OUTPUT="json"         || _LOG_OUTPUT="human"
+
+    export _FS_DRY_RUN _FS_FORCE _FS_BACKUP _LOG_VERBOSE \
+           _PROMPT_NON_INTERACTIVE _PROMPT_AUTO_ACCEPT _LOG_OUTPUT
+
+    # Propagate spec → template globals
+    SITE_TITLE="${SPEC_SITE_TITLE:-My Jekyll Site}"
+    SITE_DESCRIPTION="${SPEC_SITE_DESCRIPTION:-}"
+    SITE_AUTHOR="${SPEC_SITE_AUTHOR:-}"
+    SITE_EMAIL="${SPEC_SITE_EMAIL:-}"
+    SITE_URL="${SPEC_SITE_URL:-}"
+    SITE_TIMEZONE="${SPEC_SITE_TIMEZONE:-UTC}"
+    SITE_LOCALE="${SPEC_SITE_LOCALE:-en}"
+    GITHUB_USER="${SPEC_GITHUB_USER:-}"
+    GITHUB_REPO="${SPEC_GITHUB_REPO:-}"
+    GITHUB_PAGES_BRANCH="${SPEC_GITHUB_PAGES_BRANCH:-gh-pages}"
+    REPOSITORY_NAME="${SPEC_GITHUB_REPO:-${REPOSITORY_NAME:-}}"
+    THEME_SOURCE="${SPEC_THEME_SOURCE:-gem}"
+    INSTALL_PROFILE="${SPEC_PROFILE:-default}"
+    export SITE_TITLE SITE_DESCRIPTION SITE_AUTHOR SITE_EMAIL SITE_URL \
+           SITE_TIMEZONE SITE_LOCALE GITHUB_USER GITHUB_REPO \
+           GITHUB_PAGES_BRANCH REPOSITORY_NAME THEME_SOURCE INSTALL_PROFILE
+
+    log_banner "zer0-mistakes installer — applying spec"
+    log_info "Target : $target"
+    log_info "Profile: ${SPEC_PROFILE:-default}"
+    log_info "Tasks  : ${SPEC_TASKS}"
+    [[ -n "${SPEC_DEPLOY:-}" ]] && log_info "Deploy : $SPEC_DEPLOY"
+    [[ -n "${SPEC_AGENTS:-}" ]] && log_info "Agents : $SPEC_AGENTS"
+    [[ "$_FS_DRY_RUN" == "1" ]] && log_warning "DRY RUN — no files will be written"
+
+    # Ensure target directory exists
+    if [[ "$(type -t fs_ensure_dir)" == "function" ]]; then
+        fs_ensure_dir "$target"
+    else
+        mkdir -p "$target"
+    fi
+
+    # Run doctor unless skipped
+    if [[ "$SPEC_OPT_SKIP_DOCTOR" != "true" ]]; then
+        if [[ "$(type -t doctor_run)" == "function" ]]; then
+            doctor_run "$target" || true   # warn but don't abort
+        fi
+    fi
+
+    # Execute tasks in order
+    local failed_tasks=""
+    local task
+    for task in ${SPEC_TASKS}; do
+        apply_task "$task" "$target" || {
+            log_error "Task failed: $task"
+            failed_tasks="${failed_tasks} $task"
+        }
+    done
+
+    # Deploy plugins
+    for task in ${SPEC_DEPLOY:-}; do
+        apply_task "deploy_${task}" "$target" || \
+            log_warning "Deploy task failed: $task (continuing)"
+    done
+
+    # Agent files
+    if [[ -n "${SPEC_AGENTS:-}" ]]; then
+        apply_task "agents" "$target" || \
+            log_warning "Agents task failed (continuing)"
+    fi
+
+    if [[ -n "$failed_tasks" ]]; then
+        log_error "Some tasks failed:$failed_tasks"
+        return 1
+    fi
+
+    log_success "All tasks completed for: $target"
+    return 0
+}