jekyll-theme-zer0 1.26.0 → 1.28.0

data/scripts/features/install-preview-generator

@@ -14,13 +14,15 @@
 #   -h, --help              Show this help message
 #   -d, --dry-run           Preview what would be installed (no changes)
 #   -f, --force             Overwrite existing files
-#   -p, --provider PROVIDER Set default AI provider (openai, stability, local)
+#   -p, --provider PROVIDER Set default renderer
+#                           (openai, xai, stability, gemini, local)
 #   --no-config             Skip _config.yml modification
 #   --no-tasks              Skip VS Code tasks installation
 #
 # Requirements:
 #   - Jekyll site using zer0-mistakes theme
 #   - curl and jq installed
+#   - python3 with PyYAML (runs the generation engine)
 #   - Git repository (for version tracking)
 #
 
@@ -43,12 +45,12 @@ RAW_URL="https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main"
 SOURCE_FILES=(
     "scripts/features/generate-preview-images"
     "scripts/lib/preview_generator.py"
-    "_plugins/preview_image_generator.rb"
+    "scripts/dev/rasterize-svg.js"
 )
 DEST_FILES=(
     "scripts/generate-preview-images.sh"
     "scripts/lib/preview_generator.py"
-    "_plugins/preview_image_generator.rb"
+    "scripts/dev/rasterize-svg.js"
 )
 
 # Default options
@@ -96,20 +98,21 @@ ${YELLOW}OPTIONS:${NC}
     -h, --help              Show this help message
     -d, --dry-run           Preview what would be installed (no changes)
     -f, --force             Overwrite existing files
-    -p, --provider PROVIDER Set default AI provider (openai, stability, local)
+    -p, --provider PROVIDER Set default renderer
+                            (openai, xai, stability, gemini, local)
     --no-config             Skip _config.yml modification
     --no-tasks              Skip VS Code tasks installation
     -l, --local PATH        Copy files from local theme directory instead of downloading
 
 ${YELLOW}EXAMPLES:${NC}
-    # Install with defaults
+    # Install with defaults (OpenAI renders; Claude analyzes + reviews)
     ./$SCRIPT_NAME
 
     # Preview installation
     ./$SCRIPT_NAME --dry-run
 
-    # Install with Stability AI as default provider
-    ./$SCRIPT_NAME --provider stability
+    # Install with Gemini as the renderer
+    ./$SCRIPT_NAME --provider gemini
 
     # Force reinstall
     ./$SCRIPT_NAME --force
@@ -118,8 +121,13 @@ ${YELLOW}REMOTE INSTALLATION:${NC}
     curl -fsSL ${RAW_URL}/scripts/$SCRIPT_NAME | bash
 
 ${YELLOW}AFTER INSTALLATION:${NC}
-    1. Set your API key in .env file:
-       OPENAI_API_KEY=your-key-here
+    1. Set credentials in .env:
+       OPENAI_API_KEY=...            # the default renderer
+       Plus ONE Claude credential so Claude can analyze articles and
+       review the rendered images (optional — degrades to template prompts):
+       CLAUDE_CODE_OAUTH_TOKEN=...   # from \`claude setup-token\`
+       ANTHROPIC_API_KEY=...         # from console.anthropic.com
+       (or just have the \`claude\` CLI installed and logged in)
 
     2. Generate preview images:
        ./scripts/generate-preview-images.sh --list-missing
@@ -145,13 +153,13 @@ check_jekyll_site() {
 # Check dependencies
 check_dependencies() {
     local missing=()
-    
-    for cmd in curl jq; do
+
+    for cmd in curl jq python3; do
         if ! command -v "$cmd" &> /dev/null; then
             missing+=("$cmd")
         fi
     done
-    
+
     if [[ ${#missing[@]} -gt 0 ]]; then
         error "Missing required dependencies: ${missing[*]}"
         info "Install them with:"
@@ -159,7 +167,13 @@ check_dependencies() {
         info "  Ubuntu: sudo apt-get install ${missing[*]}"
         exit 1
     fi
-    
+
+    # The generation engine needs PyYAML (front matter / _config.yml parsing)
+    if ! python3 -c "import yaml" &> /dev/null; then
+        warn "PyYAML not found — the generator will not run until it is installed:"
+        info "  pip3 install pyyaml   (or: python3 -m pip install --user pyyaml)"
+    fi
+
     log "All dependencies satisfied"
 }
 
@@ -242,19 +256,22 @@ update_config() {
 
 # =============================================================================
 # AI Preview Image Generator Configuration
-# Feature: ZER0-003
+# Feature: ZER0-004
 # Documentation: ${REPO_URL}/blob/main/docs/features/preview-image-generator.md
 # =============================================================================
 preview_images:
   enabled: true
-  provider: ${DEFAULT_PROVIDER}          # openai, stability, or local
-  model: dall-e-3                        # OpenAI model to use
-  size: "1792x1024"                      # Landscape banner size
-  quality: standard                      # standard or hd
+  provider: ${DEFAULT_PROVIDER}          # renderer: openai, xai, stability, gemini, local
+  model: ""                              # empty = renderer default (gpt-image-2, grok-2-image, ...)
+  size: "1536x1024"                      # Landscape banner size
+  quality: auto                          # auto for GPT Image; standard/hd for DALL-E 3
   style: "retro pixel art, 8-bit video game aesthetic, vibrant colors, nostalgic, clean pixel graphics"
   style_modifiers: "pixelated, retro gaming style, CRT screen glow effect, limited color palette"
   output_dir: assets/images/previews     # Where to save generated images
-  auto_generate: false                   # Generate during build (slow, use script instead)
+  prompt_engine: claude                  # claude analyzes the article (template = built-in prompt)
+  review_engine: claude                  # claude reviews the render (none = skip)
+  assets_prefix: /assets                 # Prefix prepended to relative preview paths
+  auto_prefix: true                      # Auto-add assets_prefix when missing
   collections:                           # Collections to scan for missing previews
     - posts
     - docs
@@ -270,28 +287,32 @@ create_env_example() {
     
     if [[ -f "$env_example" ]]; then
         # Check if our keys are already there
-        if grep -q "OPENAI_API_KEY" "$env_example"; then
+        if grep -q "CLAUDE_CODE_OAUTH_TOKEN" "$env_example"; then
             info ".env.example already contains preview generator keys"
             return 0
         fi
     fi
-    
+
     if [[ "$DRY_RUN" == true ]]; then
         dry_run_log "Would add API keys to .env.example"
         return 0
     fi
-    
+
     step "Updating .env.example"
-    
-    cat >> "$env_example" << 'EOF'
 
-# AI Preview Image Generator API Keys
-# Get your key from: https://platform.openai.com/api-keys
-OPENAI_API_KEY=your-openai-api-key-here
+    cat >> "$env_example" << 'EOF'
 
-# Stability AI (alternative provider)
-# Get your key from: https://platform.stability.ai/
-STABILITY_API_KEY=your-stability-api-key-here
+# AI Preview Image Generator credentials
+# Renderer (the default provider is openai):
+# OPENAI_API_KEY=...      # https://platform.openai.com/api-keys (also powers --enhance)
+# XAI_API_KEY=...         # https://console.x.ai/
+# STABILITY_API_KEY=...   # https://platform.stability.ai/
+# GEMINI_API_KEY=...      # https://aistudio.google.com/apikey
+
+# Claude orchestration (analyzes articles + reviews renders) — any ONE of
+# (or a logged-in `claude` CLI; optional, degrades to template prompts):
+# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...   # from `claude setup-token`
+# ANTHROPIC_API_KEY=sk-ant-...               # from console.anthropic.com
 EOF
     
     log "Updated .env.example"
@@ -431,9 +452,10 @@ print_instructions() {
     echo ""
     echo -e "${YELLOW}NEXT STEPS:${NC}"
     echo ""
-    echo "  1. ${BLUE}Set up your API key:${NC}"
-    echo "     cp .env.example .env"
-    echo "     # Edit .env and add your OPENAI_API_KEY"
+    echo "  1. ${BLUE}Set up credentials:${NC}"
+    echo "     cp .env.example .env     # add OPENAI_API_KEY (the renderer)"
+    echo "     claude setup-token       # optional: lets Claude analyze + review"
+    echo "     (a logged-in \`claude\` CLI also works for the Claude side)"
     echo ""
     echo "  2. ${BLUE}Check for missing preview images:${NC}"
     echo "     ./scripts/generate-preview-images.sh --list-missing"

data/scripts/install/README.md

@@ -50,8 +50,7 @@ scripts/install/
 
 ### The Spec
 
-A single JSON document (`.zer0/install.spec.json`) is the universal contract
-between all front-ends and the executor:
+A single JSON document (`.zer0/install.spec.json`) is the universal contract between all front-ends and the executor:
 
 ```
 CLI flags → plan.sh → spec.json → apply.sh → tasks → files on disk
@@ -59,21 +58,18 @@ AI wizard → spec.json → apply.sh → tasks → files on disk
 TUI wizard → spec.json → apply.sh → tasks → files on disk
 ```
 
-The spec schema is defined in `ai/prompts/spec.schema.json`. The AI is
-constrained to emit only valid spec JSON — never raw file content.
+The spec schema is defined in `ai/prompts/spec.schema.json`. The AI is constrained to emit only valid spec JSON — never raw file content.
 
 ### Write contract
 
-**ALL filesystem writes go through `fs.sh`**. No raw `>`, `cp`, or `echo >` 
-outside of `fs.sh` functions. This enforces:
+**ALL filesystem writes go through `fs.sh`**. No raw `>`, `cp`, or `echo >` outside of `fs.sh` functions. This enforces:
 - `--dry-run`: zero mutations
 - `--backup`: auto-backup before overwrite
 - `--force`: overwrite without prompting
 
 ### Template contract
 
-**ALL generated file content comes from `templates/`**. No heredocs in shell
-code. Templates use `{{VARIABLE}}` substitution via `template.sh::tmpl_apply`.
+**ALL generated file content comes from `templates/`**. No heredocs in shell code. Templates use `{{VARIABLE}}` substitution via `template.sh::tmpl_apply`.
 
 ### Bash 3.2 compatibility
 
@@ -90,8 +86,11 @@ This installer runs on macOS's `/bin/bash` (3.2). Restrictions:
 # Local development
 ./scripts/bin/install help
 ./scripts/bin/install init . --profile blog --site-title "My Blog"
-./scripts/bin/install wizard . --ai
-./scripts/bin/install doctor .
+./scripts/bin/install init . --config zer0.install.yml     # config-file driven
+./scripts/bin/install wizard . --ai                        # Claude Code OAuth if available
+./scripts/bin/install wizard . --ai --ai-provider anthropic
+./scripts/bin/install suggest . "a docs site for a Rust CLI"
+./scripts/bin/install doctor .                             # shows the active AI provider
 ./scripts/bin/install diff .
 ./scripts/bin/install plan . --profile docs
 
@@ -114,24 +113,59 @@ curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/scripts/b
 3. Add template to `templates/config/` or `templates/pages/`
 4. List in the appropriate profile YAML under `templates/profiles/`
 
+## Config file layer
+
+Sites can persist installer choices in a small YAML file instead of re-typing flags. `config.sh` discovers and merges these (low→high precedence):
+
+1. `~/.config/zer0/install.yml` (user-global)
+2. `<target>/zer0.install.yml` (project-local)
+3. `<target>/.zer0/config.yml` (project-local, hidden)
+4. `$ZER0_CONFIG` / `--config FILE` (explicit — wins)
+
+The config layer sits between profile defaults and env/flag overrides:
+
+```
+defaults < profile < CONFIG FILE < env vars < CLI flags
+```
+
+Recognised keys (nested **or** flat/dotted both work): `profile`, `site.{title,description,author,email,url,timezone,locale}`, `github.{user,repo,pages_branch,enable_pages}`, `theme.{source,version}`, `deploy`, `agents`, `tasks`, `ai.provider`, `ai.model`. Example:
+
+```yaml
+profile: github-pages
+site:
+  title: "My Docs"
+deploy: [github-pages]
+ai:
+  provider: claude-cli      # auto | claude-cli | anthropic | openai | none
+```
+
+API keys are **never** read from config files — they stay in the environment.
+
 ## AI integration
 
 The AI path is a first-class citizen but never mandatory:
 
 - `ai_wizard_run` → interactive LLM spec generation
-- `ai_diagnose_run` → post-build error analysis  
-- `ai_suggest_run` → profile + deploy recommendation
+- `ai_diagnose_run` → post-build error analysis
+- `ai_suggest_run` → profile + deploy recommendation (also `install suggest`)
+
+All are guarded by the `ZER0_NO_AI=1` kill-switch and degrade gracefully to defaults or rule-based logic when AI is unavailable.
+
+### Providers (`ai/client.sh`)
+
+The client is multi-provider. `ZER0_AI_PROVIDER` (or config `ai.provider`, or `--ai-provider`) selects one; the default `auto` resolves in this order:
 
-All three are guarded by `ZER0_NO_AI=1` kill-switch and degrade gracefully
-to defaults or rule-based logic when AI is unavailable.
+| # | Provider     | Auth                                            | Notes |
+|---|--------------|-------------------------------------------------|-------|
+| 1 | `claude-cli` | the logged-in `claude` CLI (**Claude Code OAuth**) | Zero key handling — reuses `claude setup-token` / `claude login`. Preferred when the `claude` binary is on `PATH`. |
+| 2 | `anthropic`  | `CLAUDE_CODE_OAUTH_TOKEN` (OAuth) or `ANTHROPIC_API_KEY` | Anthropic Messages API over HTTPS. |
+| 3 | `openai`     | `OPENAI_API_KEY` (or `OPENAI_BASE_URL` for Azure/Ollama) | OpenAI-compatible `/chat/completions`. |
 
-To enable: set `OPENAI_API_KEY` (or `OPENAI_BASE_URL` for Azure/Ollama).
+Model is auto-defaulted per provider and overridable with `ZER0_AI_MODEL` / `--ai-model` (`ANTHROPIC_MODEL` / `OPENAI_MODEL` also honoured). Run `install doctor` to see which provider is active. All calls are single-attempt with a 30s timeout; user context is sanitized before it leaves the host.
 
 ## Deploy plugins
 
-Deploy targets listed in the spec (`SPEC_DEPLOY`) are dispatched as
-`tasks/deploy_<target>.sh` modules that render reusable templates from
-`templates/deploy/<target>/`. Built-in plugins:
+Deploy targets listed in the spec (`SPEC_DEPLOY`) are dispatched as `tasks/deploy_<target>.sh` modules that render reusable templates from `templates/deploy/<target>/`. Built-in plugins:
 
 | Target            | Writes                                                              |
 |-------------------|---------------------------------------------------------------------|
@@ -139,14 +173,11 @@ Deploy targets listed in the spec (`SPEC_DEPLOY`) are dispatched as
 | `azure-swa`       | `.github/workflows/azure-static-web-apps.yml`, `staticwebapp.config.json` |
 | `docker-prod`     | `Dockerfile.prod`, `docker-compose.prod.yml`, `nginx.conf`, `.dockerignore` |
 
-Add a new plugin by dropping `tasks/deploy_<target>.sh` with a
-`task_deploy_<target>_run` function plus a `templates/deploy/<target>/`
-template directory. The dispatcher is generic — no registry changes needed.
+Add a new plugin by dropping `tasks/deploy_<target>.sh` with a `task_deploy_<target>_run` function plus a `templates/deploy/<target>/` template directory. The dispatcher is generic — no registry changes needed.
 
 ## Testing
 
-A regression harness lives at [`test/test_installer.sh`](../../test/test_installer.sh)
-and is wired into the main runner as the `installer` suite:
+A regression harness lives at [`test/test_installer.sh`](../../test/test_installer.sh) and is wired into the main runner as the `installer` suite:
 
 ```bash
 # Standalone (auto-enables AI tier when OPENAI_API_KEY is set)
@@ -158,5 +189,4 @@ and is wired into the main runner as the `installer` suite:
 ./test/test_runner.sh --suites installer
 ```
 
-The harness covers: module syntax, all 6 profile inits, all 3 deploy plugins,
-all 5 agent flavours, and (when keyed) the full AI wizard → apply pipeline.
+The harness covers: module syntax, all 6 profile inits, all 3 deploy plugins, all 5 agent flavours, and (when keyed) the full AI wizard → apply pipeline.