zer0-image-generator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7f4e6c4643293895075982356663b1f49b405838640ccb8455db1b93060ce5a
+  data.tar.gz: 8708e0c991d7dd350c18ce958e3a4628393dc923c4594c42eded85b04d3839d9
+SHA512:
+  metadata.gz: 1fffd493ddbf20127ef605568aa4ce7b04ad8861a6c4e579c257dd3c253df924f7cba9272a866c0885e49e662dec568e0d1bc9e92eb5c780bd6c9a686de76db6
+  data.tar.gz: 77a9cc97328ac34db10e7285eac3aa6a535ae3fdcbd0b8e481063da402575335c9c260009b1f81fb0adbaeb50177e9d8dc750c1435987b77df7563f864352a6a

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
+- Initial extraction of the AI preview-image engine from the
+  [zer0-mistakes](https://github.com/bamr87/zer0-mistakes) theme
+  (`scripts/lib/preview_generator.py`, PR bamr87/zer0-mistakes#296) as a
+  standalone, portable project.
+- `zer0-image-generator` Ruby gem: a `jekyll preview-images` command
+  (`Jekyll::Command`) that launches the vendored single-file Python engine —
+  the Ruby layer is a thin argv translator so gem and standalone usage can
+  never drift.
+- Universality knobs (all new, all with zer0-compatible defaults):
+  - `collections_dir` — honored from Jekyll's own top-level key, the
+    `preview_images:` block, or `--collections-dir` (the theme hardcoded
+    `pages/`).
+  - `front_matter_key` — read/write any key (`preview` default; `image` for
+    jekyll-seo-tag sites) via config or `--front-matter-key`.
+  - `authors_file` — per-author style overrides from any YAML path; empty
+    disables (was hardcoded `_data/authors.yml`).
+  - `collections: auto` — discover collections from Jekyll's `collections:`
+    map instead of listing them.
+- Vendored Playwright SVG→PNG rasterizer helper next to the engine (gem
+  layout), keeping the rsvg → inkscape → magick → playwright chain intact.
+- Unit suite (98 tests, zero network) plus a standard-layout fixture site
+  exercised end-to-end in CI with the free `local` provider.
+
+### Changed
+
+- Default `collections` is now `[posts]` (universal) instead of the theme's
+  `[posts, quickstart, docs]` — zer0-mistakes lists its collections
+  explicitly, so theme behavior is unchanged when it adopts this engine.
+- `resolve_settings(args, config)` now takes the FULL `_config.yml` dict
+  (it extracts the `preview_images:` block itself) so top-level Jekyll keys
+  (`collections_dir`, `collections`) can participate in resolution.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Amr Abdel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# zer0-image-generator
+
+[![Test](https://github.com/bamr87/zer0-image-generator/actions/workflows/test.yml/badge.svg)](https://github.com/bamr87/zer0-image-generator/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+AI preview/social images for **any Jekyll site** — Claude directs and reviews,
+an image model renders, and your front matter gets wired up automatically.
+
+Extracted from the [zer0-mistakes](https://github.com/bamr87/zer0-mistakes)
+theme's consolidated engine and generalized: every theme-specific assumption
+is now a config knob with zer0-compatible defaults, so the theme and this
+plugin stay **separate but portable**.
+
+## How it works
+
+Each post/page without a preview goes through a three-stage pipeline:
+
+| stage   | role                                                        | engine / credential                    |
+| ------- | ----------------------------------------------------------- | -------------------------------------- |
+| analyze | Claude reads the article and writes a vivid art brief       | Claude credential chain (see below)    |
+| produce | an image model renders the brief                            | the selected provider                  |
+| review  | Claude inspects the render (vision); one refined regen max  | same Claude credential chain           |
+
+| provider    | renderer                                   | credential          |
+| ----------- | ------------------------------------------ | ------------------- |
+| **openai** (default) | gpt-image-2 / dall-e-3 (+ `--enhance`) | `OPENAI_API_KEY`    |
+| xai         | grok-2-image                               | `XAI_API_KEY`       |
+| stability   | Stable Diffusion XL                        | `STABILITY_API_KEY` |
+| gemini      | gemini-2.5-flash-image                     | `GEMINI_API_KEY`    |
+| local       | deterministic template SVG → PNG           | none (CI-safe)      |
+
+Claude never renders pixels (the Anthropic API has no image endpoint); without
+a Claude credential the analyze/review stages degrade gracefully to a template
+prompt and the renderer still runs.
+
+## Install
+
+### As a Jekyll plugin (recommended)
+
+```ruby
+# Gemfile
+group :jekyll_plugins do
+  gem "zer0-image-generator"
+end
+```
+
+Requires `python3` (3.9+) with PyYAML — the command checks and tells you if
+either is missing:
+
+```bash
+python3 -m pip install pyyaml
+```
+
+Then, from your site root:
+
+```bash
+bundle exec jekyll preview-images --list-missing   # what needs a banner?
+bundle exec jekyll preview-images --dry-run        # what would be generated?
+bundle exec jekyll preview-images                  # generate them
+```
+
+### Standalone (no Ruby required)
+
+The engine is one dependency-light Python file. Copy it anywhere and run it
+from your site root:
+
+```bash
+curl -o preview_generator.py \
+  https://raw.githubusercontent.com/bamr87/zer0-image-generator/main/lib/zer0_image_generator/preview_generator.py
+python3 preview_generator.py --dry-run
+```
+
+## Configuration
+
+Everything lives under `preview_images:` in your `_config.yml`. Shown with
+defaults:
+
+```yaml
+preview_images:
+  enabled: true
+  provider: openai            # openai | xai | stability | gemini | local
+  model: ''                   # empty = provider default (gpt-image-2, ...)
+  size: 1536x1024
+  quality: auto               # auto (GPT Image) | standard/hd (DALL-E 3)
+  style: "retro pixel art, 8-bit video game aesthetic, vibrant colors"
+  style_modifiers: "pixelated, retro gaming style, CRT screen glow effect"
+  output_dir: assets/images/previews
+  prompt_engine: claude       # claude analyzes each article | template
+  review_engine: claude       # claude vision-reviews each render | none
+  # --- portability knobs (the zer0-isms, now configurable) ---
+  collections: [posts]        # list of collections, or 'auto' to discover
+                              # them from Jekyll's own `collections:` map
+  collections_dir: ''         # falls back to Jekyll's top-level collections_dir
+  front_matter_key: preview   # key to read/write (jekyll-seo-tag sites: image)
+  authors_file: _data/authors.yml  # per-author style overrides ('' disables)
+  assets_prefix: /assets      # written paths omit this prefix ...
+  auto_prefix: true           # ... and it is re-added for existence checks
+```
+
+Priority per file: author overrides → CLI flags → environment variables →
+`_config.yml` → built-in defaults.
+
+### Recipe: standard Jekyll site with jekyll-seo-tag
+
+```yaml
+preview_images:
+  provider: openai
+  collections: auto
+  front_matter_key: image     # jekyll-seo-tag reads page.image
+  assets_prefix: ''           # write full site-absolute paths
+  authors_file: ''
+```
+
+Generated front matter: `image: /assets/images/previews/my-post.png` — exactly
+what `jekyll-seo-tag` turns into `og:image`.
+
+### Recipe: zer0-mistakes theme
+
+```yaml
+preview_images:
+  provider: openai
+  collections: [posts, docs, quickstart]
+  # collections_dir comes from the theme's own `collections_dir: pages`
+  # front_matter_key/preview + /assets prefixing are already the defaults
+```
+
+### Per-author style overrides
+
+If `authors_file` points at a YAML map, an author's `preview:` block overrides
+`style`, `style_modifiers`, `size`, `quality`, and `model` for their pages:
+
+```yaml
+# _data/authors.yml
+cassandra:
+  preview:
+    style: >-
+      noir graphic-novel, high-contrast ink
+```
+
+## Credentials
+
+The renderer needs its own key (default: `OPENAI_API_KEY`). Claude
+orchestration accepts any ONE of, in order — it is optional:
+
+```bash
+export CLAUDE_CODE_OAUTH_TOKEN="..."   # 1. from `claude setup-token` (Pro/Max)
+export ANTHROPIC_AUTH_TOKEN="..."      # 2. short-lived bearer token
+export ANTHROPIC_API_KEY="..."         # 3. console.anthropic.com
+# 4. nothing — a logged-in `claude` CLI is used automatically
+```
+
+Keys are read from the environment or a git-ignored `.env` at the site root.
+On a Claude Pro/Max subscription the orchestration costs nothing extra; only
+the renderer bills per image.
+
+## CLI reference
+
+`jekyll preview-images` exposes the engine's flags (Jekyll claims `-s/-d/-p`
+globally, so use long forms there; the Python CLI keeps all short flags):
+
+```text
+--dry-run --verbose --force --list-missing
+-f/--file FILE          --collection NAME|all       --provider NAME
+--model NAME            --output-dir DIR            -j/--parallel N
+--style TEXT            --prompt-engine claude|template
+--review claude|none    --rasterizer auto|rsvg|inkscape|magick|playwright|none
+-e/--enhance            --enhance-prompt/-model/-quality/-fidelity/-format
+--collections-dir DIR   --front-matter-key KEY      --authors-file FILE
+--assets-prefix PREFIX  --no-auto-prefix            --batch N  --log-file FILE
+```
+
+The `local` provider rasterizes its SVG via the first available of
+`rsvg-convert` (`brew install librsvg` / `apt install librsvg2-bin`),
+`inkscape`, ImageMagick, or a vendored Playwright helper.
+
+## CI usage
+
+```yaml
+- name: Generate preview images
+  env:
+    CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  run: bundle exec jekyll preview-images
+```
+
+Generation is script-driven on demand — it is never part of `jekyll build`
+(builds stay fast, deterministic, and secret-free; GitHub Pages safe mode is
+irrelevant to it).
+
+## Relationship to zer0-mistakes
+
+The [zer0-mistakes](https://github.com/bamr87/zer0-mistakes) theme renders
+`preview:` values with a pure-Liquid include (GitHub-Pages-safe, no plugin
+needed) and currently vendors this engine at `scripts/lib/preview_generator.py`.
+This repo is the portable home: the theme is expected to consume the gem (or
+curl the engine from here) in a follow-up, so there is exactly ONE engine.
+
+## Development
+
+```bash
+python3 test/test_preview_generator.py      # 98 unit tests, zero network
+python3 -m py_compile lib/zer0_image_generator/preview_generator.py
+gem build zer0-image-generator.gemspec
+cd test/fixture-site && bundle install
+bundle exec jekyll preview-images --dry-run # integration fixture
+```
+
+Conventional Commits drive releases via release-please. One concern per PR.
+
+## License
+
+[MIT](LICENSE) © Amr Abdel

data/lib/zer0-image-generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Entry point required by Bundler's :jekyll_plugins group. Registers the
+# `jekyll preview-images` command when Jekyll is present; outside Jekyll the
+# gem is inert (the Python engine can always be run directly:
+# python3 lib/zer0_image_generator/preview_generator.py).
+require_relative "zer0_image_generator/version"
+
+begin
+  require "jekyll"
+rescue LoadError
+  # Standalone/non-Jekyll context — nothing to register.
+end
+
+require_relative "zer0_image_generator/command" if defined?(Jekyll::Command)

data/lib/zer0_image_generator/command.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Zer0ImageGenerator
+  # `jekyll preview-images` — a thin launcher for the vendored single-file
+  # Python engine (preview_generator.py, same directory). The Ruby layer only
+  # translates Mercenary options back into the engine's argv and execs
+  # python3: all behavior (config resolution, credentials, providers, front
+  # matter) lives in the engine so the gem and the standalone file can never
+  # drift.
+  #
+  # Jekyll's global switches already claim -s/-d/-p/-v at the program level,
+  # so conflicting engine shorts are exposed long-form here; the engine's own
+  # CLI keeps the full short surface for direct `python3` use.
+  class Command < Jekyll::Command
+    ENGINE = File.expand_path("preview_generator.py", __dir__)
+
+    # [engine flag, mercenary args] — booleans pass bare, values pass through.
+    SWITCHES = [
+      ["--dry-run",          [:dry_run, "--dry-run", "Preview what would be generated (no changes)"]],
+      ["--verbose",          [:verbose, "--verbose", "Enable verbose output"]],
+      ["--file",             [:file, "-f", "--file FILE", "Process a specific file only"]],
+      ["--collection",       [:collection, "--collection NAME", "Process one collection, or 'all'"]],
+      ["--provider",         [:provider, "--provider NAME", "Renderer: openai, xai, stability, gemini, local"]],
+      ["--model",            [:model, "--model NAME", "Override the provider's image model"]],
+      ["--output-dir",       [:output_dir, "--output-dir DIR", "Image output directory"]],
+      ["--force",            [:force, "--force", "Regenerate even when a preview exists"]],
+      ["--list-missing",     [:list_missing, "--list-missing", "Only list files with missing previews"]],
+      ["--parallel",         [:parallel, "-j", "--parallel N", "Concurrent workers (default 4)"]],
+      ["--enhance",          [:enhance, "-e", "--enhance", "Enhance existing images (OpenAI images/edits)"]],
+      ["--enhance-prompt",   [:enhance_prompt, "--enhance-prompt TEXT", "Custom enhancement prompt (implies --enhance)"]],
+      ["--enhance-model",    [:enhance_model, "--enhance-model NAME", "Enhancement model (default: gpt-image-2)"]],
+      ["--enhance-quality",  [:enhance_quality, "--enhance-quality Q", "low|medium|high|auto"]],
+      ["--enhance-fidelity", [:enhance_fidelity, "--enhance-fidelity F", "high|low (implies --enhance)"]],
+      ["--enhance-format",   [:enhance_format, "--enhance-format FMT", "png|jpeg|webp (implies --enhance)"]],
+      ["--prompt-engine",    [:prompt_engine, "--prompt-engine ENGINE", "claude (analyzes the article) or template"]],
+      ["--review",           [:review, "--review ENGINE", "claude (vision-reviews the render) or none"]],
+      ["--rasterizer",       [:rasterizer, "--rasterizer TOOL", "auto|rsvg|inkscape|magick|playwright|none"]],
+      ["--style",            [:style, "--style TEXT", "Override the image style prompt"]],
+      ["--assets-prefix",    [:assets_prefix, "--assets-prefix PREFIX", "Assets prefix for path normalization"]],
+      ["--no-auto-prefix",   [:no_auto_prefix, "--no-auto-prefix", "Disable automatic assets-prefix prepending"]],
+      ["--batch",            [:batch, "--batch N", "Limit number of files processed"]],
+      ["--log-file",         [:log_file, "--log-file FILE", "Also write log output to a file"]],
+      ["--collections-dir",  [:collections_dir, "--collections-dir DIR", "Directory holding _<collection> dirs"]],
+      ["--front-matter-key", [:front_matter_key, "--front-matter-key KEY", "Front-matter key (default preview; seo-tag sites: image)"]],
+      ["--authors-file",     [:authors_file, "--authors-file FILE", "Author-overrides YAML ('' disables)"]],
+    ].freeze
+
+    BOOLEANS = %w[--dry-run --verbose --force --list-missing --enhance --no-auto-prefix].freeze
+
+    class << self
+      def init_with_program(prog)
+        prog.command(:"preview-images") do |c|
+          c.syntax "preview-images [options]"
+          c.description "Generate AI preview/social images (Claude directs & reviews; " \
+                        "OpenAI/xAI/Stability/Gemini/local renders)"
+          SWITCHES.each { |_flag, merc| c.option(*merc) }
+
+          c.action do |_args, options|
+            new.run(options)
+          end
+        end
+      end
+    end
+
+    def run(options)
+      python = ENV["PYTHON"] || "python3"
+      ensure_python!(python)
+      argv = build_argv(options)
+      Jekyll.logger.info "preview-images:", "#{python} #{ENGINE} #{argv.join(' ')}"
+      exec(python, ENGINE, *argv)
+    end
+
+    def build_argv(options)
+      SWITCHES.each_with_object([]) do |(flag, merc), argv|
+        value = options[merc.first.to_s]
+        next if value.nil? || value == false
+
+        if BOOLEANS.include?(flag)
+          argv << flag
+        else
+          argv << flag << value.to_s
+        end
+      end
+    end
+
+    private
+
+    def ensure_python!(python)
+      unless command_available?(python)
+        Jekyll.logger.abort_with "preview-images:",
+                                 "#{python} not found — install Python 3.9+ " \
+                                 "(or set PYTHON=/path/to/python3)."
+      end
+      return if system(python, "-c", "import yaml", out: File::NULL, err: File::NULL)
+
+      Jekyll.logger.abort_with "preview-images:",
+                               "PyYAML is missing — run: #{python} -m pip install pyyaml"
+    end
+
+    def command_available?(cmd)
+      system(cmd, "--version", out: File::NULL, err: File::NULL)
+    rescue SystemCallError
+      false
+    end
+  end
+end