abqari 1.1.0

data/app/views/partials/home/_photo_gallery.html.erb

@@ -0,0 +1,71 @@
+<!--
+  Home module — photo gallery. Renders a single row of four photos
+  using the same `.gallery-index` markup the /photos/ index page uses
+  — same thumbnail style, same tinted placeholder fallbacks, same
+  hover behavior. On wider screens (≥ 768px) the row is exactly 4
+  wide; below that it reflows via the base `.gallery-index` auto-fill
+  rule (2 cols on tablets, 1 col on phones).
+
+  Config (`home.photo_gallery` in config/site.yml):
+      latest   — four most-recent photos (the default)
+      random   — four random photos, fresh per build
+      false    — module is disabled
+  Boolean `true` is treated as `latest` for backwards compatibility.
+
+  Renders nothing when the photos collection is empty or disabled.
+
+  Title and location come from each photo's frontmatter; camera and
+  caption are intentionally omitted to keep the home module visually
+  light — the photos index page is the full-detail view.
+
+  Style via `.home-module*` and `.gallery-index*` class hooks in
+  `themes/<name>/css/app.css`.
+-->
+<%
+  mode    = site.config.dig('home', 'photo_gallery').to_s
+  mode    = 'latest' if mode == 'true' || mode.empty?
+  photos  = if mode == 'random'
+              site.collection('photos').sample(4)
+            else
+              site.collection('photos').first(4)
+            end
+  heading = mode == 'random' ? 'From the gallery' : 'Latest photos'
+  # When the gallery is the priority module only the first thumbnail
+  # gets the eager hint — the other three sit alongside it and the
+  # browser's preloader scans them too, but the first is the LCP
+  # candidate.
+  _priority = defined?(priority_image) && priority_image
+%>
+<% if photos.any? %>
+<section class="home-module home-module--photo-gallery" aria-label="Photo gallery">
+  <header class="home-module__header">
+    <h2 class="home-module__heading"><%= heading %></h2>
+    <a class="home-module__see-all" href="<%= sanitized_url(collection_index_url('photos')) %>">All <%= collection_index_label('photos') %> &rarr;</a>
+  </header>
+  <ul class="gallery-index gallery-index--cols-4">
+    <% photos.each_with_index do |photo, idx| %>
+      <% tint  = "gallery-index__cover--tint-#{(idx % 4) + 1}" %>
+      <% _eager = _priority && idx.zero? %>
+      <li>
+        <a href="<%= sanitized_url(photo.url) %>">
+          <div class="gallery-index__cover <%= tint %>">
+            <% if (img = photo.frontmatter['image']) %>
+              <img src="<%= sanitized_url(img) %>"
+                   alt="<%= photo.frontmatter['caption'] || photo.title %>"
+                   loading="<%= _eager ? 'eager' : 'lazy' %>"
+                   <% if _eager %>fetchpriority="high"<% end %>
+                   decoding="async">
+            <% end %>
+          </div>
+          <span class="gallery-index__title"><%= photo.title %></span>
+          <% if photo.frontmatter['city'] || photo.frontmatter['country'] %>
+            <span class="gallery-index__location">
+              <%= [photo.frontmatter['city'], photo.frontmatter['country']].compact.join(', ') %>
+            </span>
+          <% end %>
+        </a>
+      </li>
+    <% end %>
+  </ul>
+</section>
+<% end %>

data/app/views/partials/home/_random_photo.html.erb

@@ -0,0 +1,106 @@
+<!--
+  Home module — random photo. Same pool-of-candidates + pick-on-page-
+  load pattern as `_random_post.html.erb`. See that file's head
+  comment for the rationale (static sites can't roll randomness at
+  request time; `random-pool.js` handles it client-side).
+
+  Config (`home.random_photo` in config/site.yml). Accepts two
+  shapes — same field set as `home.latest_photo`, applied uniformly
+  to every card in the pool so the JS-swapped variant looks
+  consistent with the initially-visible one:
+
+      # Simple — module on with all defaults
+      random_photo: true
+
+      # Granular — opt-in field controls
+      random_photo:
+        enabled: true              # `enabled: false` disables; absent = true
+        show_caption: true         # default true   — the descriptive prose
+        show_date:    true         # default true   — capture date
+        show_city:    true         # default true   — city (combined with country)
+        show_country: true         # default true   — country
+        show_camera:  false        # default false  — camera body
+        show_type:    false        # default false  — digital / film / etc.
+        show_series:  false        # default false  — series this photo belongs to
+        show_tags:    false        # default false  — tag pills
+
+  Hero image and photo title are always rendered when present.
+
+  Style via `.home-module*` class hooks in your theme.
+-->
+<%
+  pool_cap = 12
+  candidates = site.collection('photos').first(pool_cap)
+  # Same as `_random_post`: only the i=0 card is initially visible,
+  # so only it gets the eager hint when this module is priority. The
+  # hidden cards fetch lazily on JS-swap.
+  _priority = defined?(priority_image) && priority_image
+
+  mod_cfg      = site.config.dig('home', 'random_photo')
+  mod_cfg      = {} unless mod_cfg.is_a?(Hash)
+  show_caption = mod_cfg.fetch('show_caption', true)
+  show_date    = mod_cfg.fetch('show_date',    true)
+  show_city    = mod_cfg.fetch('show_city',    true)
+  show_country = mod_cfg.fetch('show_country', true)
+  show_camera  = mod_cfg.fetch('show_camera',  false)
+  show_type    = mod_cfg.fetch('show_type',    false)
+  show_series  = mod_cfg.fetch('show_series',  false)
+  show_tags    = mod_cfg.fetch('show_tags',    false)
+%>
+<% if candidates.any? %>
+<section class="home-module home-module--random-photo" aria-label="From the gallery">
+  <header class="home-module__header">
+    <h2 class="home-module__heading">From the gallery</h2>
+    <a class="home-module__see-all" href="<%= sanitized_url(collection_index_url('photos')) %>">All <%= collection_index_label('photos') %> &rarr;</a>
+  </header>
+  <div class="home-module__pool" data-random-pool>
+    <% candidates.each_with_index do |photo, i| %>
+      <% _eager = _priority && i.zero? %>
+      <%
+        fm    = photo.frontmatter
+        parts = []
+        if show_date && photo.date
+          parts << %(<time datetime="#{photo.date.iso8601}">#{local_time(photo.date)}</time>)
+        end
+        city    = show_city    ? fm['city']    : nil
+        country = show_country ? fm['country'] : nil
+        location = [city, country].compact.reject { |s| s.to_s.strip.empty? }.join(', ')
+        parts << h(location)        unless location.empty?
+        parts << h(fm['camera'])    if show_camera && fm['camera']
+        parts << h(fm['type'])      if show_type   && fm['type']
+        parts << h(fm['series'])    if show_series && fm['series']
+      %>
+      <article class="home-module__item"<%= ' hidden' if i.positive? %>>
+        <% if (img = fm['image']) %>
+          <a class="home-module__cover" href="<%= sanitized_url(photo.url) %>">
+            <img src="<%= sanitized_url(img) %>"
+                 alt="<%= fm['caption'] || photo.title %>"
+                 loading="<%= _eager ? 'eager' : 'lazy' %>"
+                 <% if _eager %>fetchpriority="high"<% end %>
+                 decoding="async">
+          </a>
+        <% end %>
+        <div class="home-module__body">
+          <h3 class="home-module__title">
+            <a href="<%= sanitized_url(photo.url) %>"><%= photo.title %></a>
+          </h3>
+          <% if parts.any? %>
+            <p class="home-module__meta"><%== parts.join(' &middot; ') %></p>
+          <% end %>
+          <% if show_caption && (caption = fm['caption']) %>
+            <p class="home-module__description"><%= truncate(caption.to_s, length: 200) %></p>
+          <% end %>
+          <% if show_tags && Array(fm['tags']).any? %>
+            <p class="home-module__tags">
+              <% Array(fm['tags']).each do |tag| %>
+                <a class="home-module__tag" href="/tags/<%= slugify(tag) %>/"><%= tag %></a>
+              <% end %>
+            </p>
+          <% end %>
+        </div>
+      </article>
+    <% end %>
+  </div>
+  <script src="<%= asset_path('js/random-pool.js') %>" defer></script>
+</section>
+<% end %>

data/app/views/partials/home/_random_post.html.erb

@@ -0,0 +1,64 @@
+<!--
+  Home module — random post. Static sites can't roll randomness at
+  request time, so this partial renders a small pool of candidate
+  posts (up to `pool_cap` newest) and ships a tiny script that picks
+  one to show on each page load. The first card is the no-JS
+  fallback; the rest are server-rendered with `hidden` and unhidden
+  by `random-pool.js` after the page loads (and again on every back/
+  forward cache restore, so the user doesn't see the same card on
+  navigation).
+
+  Toggled by `home.random_post: true` in config/site.yml.
+  Style via `.home-module*` class hooks in your theme.
+-->
+<%
+  pool_cap = 12        # cap the pool size for page-weight predictability
+  candidates = site.collection('posts').first(pool_cap)
+  # Only the first card is initially visible (the no-JS fallback);
+  # the rest are `hidden` and only swapped in by random-pool.js
+  # post-load. So even when this module is priority, only the i=0
+  # image gets the eager hint — pre-eagerly fetching all 12 would
+  # waste bandwidth on cards the user never sees.
+  _priority = defined?(priority_image) && priority_image
+%>
+<% if candidates.any? %>
+<section class="home-module home-module--random-post" aria-label="From the archive">
+  <header class="home-module__header">
+    <h2 class="home-module__heading">From the archive</h2>
+    <a class="home-module__see-all" href="<%= sanitized_url(collection_index_url('posts')) %>">All <%= collection_index_label('posts') %> &rarr;</a>
+  </header>
+  <div class="home-module__pool" data-random-pool>
+    <% candidates.each_with_index do |post, i| %>
+      <% _eager = _priority && i.zero? %>
+      <article class="home-module__item"<%= ' hidden' if i.positive? %>>
+        <% if (img = post.frontmatter['image']) %>
+          <a class="home-module__cover" href="<%= sanitized_url(post.url) %>">
+            <img src="<%= sanitized_url(bundle_asset_url_for(post, img)) %>"
+                 alt="<%= post.title %>"
+                 loading="<%= _eager ? 'eager' : 'lazy' %>"
+                 <% if _eager %>fetchpriority="high"<% end %>
+                 decoding="async">
+          </a>
+        <% end %>
+        <div class="home-module__body">
+          <h3 class="home-module__title">
+            <a href="<%= sanitized_url(post.url) %>"><%= post.title %></a>
+          </h3>
+          <% if post.date %>
+            <p class="home-module__meta">
+              <time datetime="<%= post.date.iso8601 %>"><%= local_time(post.date) %></time>
+              <% if post.respond_to?(:content) && post.content.to_s.length.positive? %>
+                · <%= reading_time(post.content) %>
+              <% end %>
+            </p>
+          <% end %>
+          <% if (desc = post.frontmatter['description'].to_s) && !desc.empty? %>
+            <p class="home-module__description"><%= truncate(desc, length: 160) %></p>
+          <% end %>
+        </div>
+      </article>
+    <% end %>
+  </div>
+  <script src="<%= asset_path('js/random-pool.js') %>" defer></script>
+</section>
+<% end %>

data/exe/abqari

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Global Abqari CLI — single entry point shipped as the gem's executable.
+# After `gem install abqari` (or installing from a git checkout via
+# `gem build && gem install ./abqari-X.Y.Z.gem`), the `abqari` command
+# is available on PATH from anywhere.
+#
+# Subcommands:
+#   abqari new <projectname>   Scaffold a new site directory.
+#   abqari version             Print the engine version.
+#   abqari --help              Show this list.
+#
+# All other operations (build, serve, audit, etc.) run from inside a
+# scaffolded site via the per-site `bin/*` scripts that `abqari new`
+# generates. This matches the Jekyll convention: the global `jekyll`
+# binary bootstraps; per-site scripts do the per-project work.
+
+# Development-checkout escape hatch. When this script runs from a git
+# checkout (the gem isn't installed), `lib/abqari.rb` sits next to the
+# `exe/` directory; auto-add that lib to LOAD_PATH so `require 'abqari'`
+# resolves without `gem install`. Harmless when the gem IS installed —
+# the local require wins on the load path but resolves to identical
+# code. Lets engine developers test `abqari new` without first running
+# `gem build && gem install` after every change.
+dev_lib = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(dev_lib) if File.exist?(File.join(dev_lib, 'abqari.rb'))
+
+require 'abqari'         # for Abqari::VERSION (used by `abqari version`)
+require 'abqari/cli'
+
+# `run_cli` presents expected failures (Abqari::UserError) as a plain
+# message and Ctrl-C as "Interrupted", instead of a backtrace. Genuine
+# defects keep their trace. ABQARI_DEBUG=1 restores it for UserError.
+Abqari.run_cli do
+  exit(Abqari::CLI.run(ARGV) ? 0 : 1)
+end

data/lib/abqari/artifact_writer.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Abqari
+  # Filesystem-output collaborator. Owns the steps that produce files in
+  # `_site/` outside of the page-render loop:
+  #
+  #   - Wiping / preparing the output directory at the start of a build.
+  #   - Copying static passthrough trees (public/, themes/<n>/public/).
+  #   - Copying vendored assets (D3, fonts).
+  #   - Emitting deploy artifacts (sitemap, feed, robots, headers,
+  #     security.txt, redirects, manifest, llms.txt, OG images,
+  #     syntax-highlighter stylesheet).
+  #
+  # Each step is idempotent: re-running an incremental build only copies
+  # files that changed (mtime comparison). The reset_output guard
+  # prevents accidentally wiping anything outside site_root.
+  class ArtifactWriter
+    def initialize(site)
+      @site = site
+    end
+
+    # Directory names we refuse to let `output_dir` resolve to, because
+    # wiping them destroys the user's source, not build output. Checked
+    # against the target itself AND against the site root's key children.
+    PROTECTED_SITE_DIRS = %w[content config data public .git].freeze
+
+    # Wipe `output_dir` and recreate it empty. Refuses to delete:
+    #   - The filesystem root (`/`, `C:\`)
+    #   - The user's home directory
+    #   - The site root itself (`ABQARI_OUTPUT_DIR=.` — the guard below
+    #     for "under site_root" passes on equality, which would wipe the
+    #     whole project).
+    #   - A source directory (`content/`, `config/`, `data/`, `.git`, …).
+    #   - Anything not under `site_root` (unless explicitly opted-in
+    #     via ABQARI_ALLOW_EXTERNAL_OUTPUT=true).
+    def reset_output
+      target    = File.expand_path(@site.output_dir)
+      site_root = File.expand_path(@site.site_root)
+
+      raise PathSafe::Error, "refusing to wipe filesystem root: #{target}" if filesystem_root?(target)
+      raise PathSafe::Error, "refusing to wipe home dir: #{target}" if target == File.expand_path('~')
+      raise PathSafe::Error, "refusing to wipe site root: #{target}" if target == site_root
+
+      protected_dir = PROTECTED_SITE_DIRS.find do |name|
+        dir = File.expand_path(File.join(site_root, name))
+        target == dir || dir.start_with?(target + File::SEPARATOR)
+      end
+      if protected_dir
+        raise PathSafe::Error,
+              "refusing to wipe #{target}: it is (or contains) the site's #{protected_dir}/ directory"
+      end
+
+      unless ENV['ABQARI_ALLOW_EXTERNAL_OUTPUT'] == 'true'
+        PathSafe.assert_under(@site.site_root, target)
+      end
+
+      FileUtils.rm_rf(target)
+      FileUtils.mkdir_p(target)
+    end
+
+    # Copy static passthrough files into the build output. Three
+    # sources, later wins on conflict:
+    #   1. Top-level `public/` — site-wide files (favicons, manifest).
+    #   2. The ENGINE theme's `themes/<name>/public/` — theme-scoped
+    #      vendor files (e.g. the Bootstrap dist for `theme: bootstrap`).
+    #   3. The SITE's `themes/<name>/public/` — per-file overrides.
+    #
+    # Engine and site theme dirs MERGE (same semantics as the asset
+    # pipeline): a site adding one file to `themes/bootstrap/public/`
+    # must not stop the engine's vendored dist from shipping. The old
+    # `find_in_paths` picked exactly one dir, so a single site-local
+    # file silently 404'd `/css/bootstrap.min.css`. Precedence is
+    # resolved in the map — NOT via copy order + the mtime skip, which
+    # would let whichever source file happened to be newer win.
+    def copy_public
+      theme = @site.config['theme'].to_s
+      sources = [
+        File.join(@site.site_root, 'public'),
+        File.join(@site.engine_root, 'themes', theme, 'public'),
+        File.join(@site.site_root, 'themes', theme, 'public')
+      ]
+
+      merged = {}
+      sources.each do |public_dir|
+        next unless Dir.exist?(public_dir)
+
+        Dir.glob(File.join(public_dir, '**', '*'), File::FNM_DOTMATCH).sort.each do |entry|
+          next if File.directory?(entry)
+          # Symlink containment — the one tree-walker that used to miss
+          # this. `FileUtils.cp` follows symlinks, so without the guard a
+          # `public/notes.txt -> ~/.ssh/id_ed25519` copies the target's
+          # CONTENTS into _site/ and ships them. Every other walker
+          # (asset pipeline, bundle assets, image pipeline, loader)
+          # enforces the same invariant.
+          next if @site.external_symlink?(entry)
+
+          rel = entry.sub("#{public_dir}/", '')
+          # Dotfile filter checks EVERY path component, not just the
+          # basename. FNM_DOTMATCH descends into hidden directories, so a
+          # basename-only check would still copy `.git/config`,
+          # `.svn/entries`, editor state dirs, etc. `.well-known/` is the
+          # one hidden dir a static site legitimately publishes.
+          next if hidden_path?(rel)
+
+          merged[rel] = entry
+        end
+      end
+
+      merged.each do |rel, entry|
+        dest = File.join(@site.output_dir, rel)
+        next if File.exist?(dest) && File.mtime(dest) >= File.mtime(entry)
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(entry, dest)
+      end
+    end
+
+    # Mirror the FontPipeline-populated `vendor/fonts/` into
+    # `_site/assets/fonts/`. No-op when the cache is missing (FontPipeline
+    # is opt-in via `bin/fetch-fonts`).
+    def copy_fonts
+      src = File.join(@site.site_root, 'vendor', 'fonts')
+      return unless Dir.exist?(src)
+
+      dest_dir = File.join(@site.output_dir, 'assets', 'fonts')
+      FileUtils.mkdir_p(dest_dir)
+      Dir.glob(File.join(src, '*')).sort.each do |entry|
+        next if File.directory?(entry) || File.basename(entry).start_with?('.')
+
+        dest = File.join(dest_dir, File.basename(entry))
+        next if File.exist?(dest) && File.mtime(dest) >= File.mtime(entry)
+
+        FileUtils.cp(entry, dest)
+      end
+    end
+
+    # Copy vendored D3 to _site/assets/d3/. Only runs when visualizations
+    # are enabled — keeps the ~280 KB out of builds that don't need it.
+    def copy_d3
+      return unless @site.visualizations.enabled?
+
+      src = File.join(@site.engine_root, 'vendor', 'd3', 'd3.v7.min.js')
+      return unless File.exist?(src)
+
+      dest_dir = File.join(@site.output_dir, 'assets', 'd3')
+      FileUtils.mkdir_p(dest_dir)
+      dest = File.join(dest_dir, 'd3.v7.min.js')
+      return if File.exist?(dest) && File.mtime(dest) >= File.mtime(src)
+
+      FileUtils.cp(src, dest)
+    end
+
+    # Emit every deploy artifact that ships alongside the rendered HTML.
+    # Order matters only insofar as some artifacts (e.g. Manifest) read
+    # config values that should already be validated; all of those run
+    # after Site#build has done its setup.
+    def write_deploy_artifacts
+      # Crawler-facing inventories (sitemap, llms.txt) are suppressed when
+      # the site opts out of indexing — otherwise a staging/preview deploy
+      # with `indexable: false` still publishes a full list of its URLs,
+      # defeating the point. `robots.txt` (which emits `Disallow: /` in
+      # that mode) is always written so crawlers get the signal.
+      indexable = @site.config['indexable'] != false
+
+      Sitemap.new(@site).write if indexable
+      Feed.write_all(@site)
+      Robots.new(@site).write
+      HeadersFile.new(@site).write
+      SecurityTxt.new(@site).write
+      Redirects.new(@site).write
+      Manifest.new(@site).write
+      LlmsTxt.new(@site).write if indexable
+      OgImageGenerator.new(@site).write
+      SyntaxHighlighter::Stylesheet.new(@site).write
+    end
+
+    private
+
+    def filesystem_root?(path)
+      path == '/' || path == File::SEPARATOR || path.match?(/\A[A-Za-z]:[\\\/]?\z/)
+    end
+
+    # True when any component of the relative path is a dotfile/dotdir,
+    # except an allowlisted `.well-known` (RFC 8615 — security.txt,
+    # ACME challenges, etc., which a static site is meant to publish).
+    ALLOWED_DOT_DIRS = %w[.well-known].freeze
+
+    def hidden_path?(rel)
+      rel.split('/').any? do |component|
+        component.start_with?('.') && !ALLOWED_DOT_DIRS.include?(component)
+      end
+    end
+  end
+end