abqari 1.1.0

data/lib/abqari/cli/theme.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'optparse'
+
+module Abqari
+  module CLI
+    # `abqari theme eject <name>` — copy an engine theme's stylesheet
+    # into the current site so it can be edited there.
+    #
+    # Why this exists: for a gem-installed site the engine's themes live
+    # inside the gem directory — read-only in practice, and invisible to
+    # anyone who doesn't know about `bundle show abqari`. The asset
+    # pipeline already gives site-local `themes/<name>/` precedence over
+    # the engine's copy, so "make a theme yours" is just a copy into the
+    # right place. This command does that copy.
+    #
+    #   abqari theme eject minimal              # shadow it in place:
+    #                                           # themes/minimal/css/app.css
+    #   abqari theme eject minimal --as mytheme # fork it under a new name
+    #                                           # and point config at it
+    #   abqari theme eject custom               # the annotated starter
+    #
+    # `--as` writes the copy under the new name and updates `theme:` in
+    # config/site.yml (when the line is unambiguous). Ejecting under the
+    # SAME name needs no config change — the site-local copy shadows the
+    # engine's automatically.
+    #
+    # Bootstrap is the one theme that can't be renamed: the engine keys
+    # its special-casing (skip `_common.css`, emit the vendored dist's
+    # link/script tags) on the literal name 'bootstrap'.
+    class Theme
+      def self.run(argv)
+        new.run(argv)
+      end
+
+      def initialize
+        @options = { as: nil, force: false }
+      end
+
+      def run(argv)
+        parser = build_parser
+        rest = parser.parse(argv)
+
+        subcommand, name = rest
+        unless subcommand == 'eject' && name
+          warn parser.help
+          return false
+        end
+
+        eject(name)
+      end
+
+      private
+
+      def build_parser
+        OptionParser.new do |opts|
+          opts.banner = <<~BANNER
+            Usage: abqari theme eject <name> [options]
+
+            Copies the engine theme's css/app.css into this site's
+            themes/ directory, where it shadows the gem's copy and your
+            edits live in your repo.
+
+            Available themes: #{engine_theme_names.join(', ')}
+          BANNER
+          opts.separator ''
+          opts.separator 'Options:'
+          opts.on('--as NAME', 'Eject under a different theme name (updates config/site.yml)') { |v| @options[:as] = v }
+          opts.on('--force',   'Overwrite an existing themes/<name>/css/app.css')             { @options[:force] = true }
+          opts.on('-h', '--help', 'Show this message') { puts opts; exit }
+        end
+      end
+
+      def eject(name)
+        target_name = @options[:as] || name
+
+        return false unless valid_names?(name, target_name)
+        return false unless site_root?
+
+        src = File.join(Abqari::ROOT, 'themes', name, 'css', 'app.css')
+        unless File.file?(src)
+          warn "Unknown theme #{name.inspect}. Available: #{engine_theme_names.join(', ')}"
+          return false
+        end
+
+        if name == 'bootstrap' && target_name != 'bootstrap'
+          warn "The bootstrap theme can't be ejected under another name — the engine keys"
+          warn "its special-casing (vendored dist links, no _common.css) on the literal"
+          warn "name 'bootstrap'. Use `abqari theme eject bootstrap` to shadow it in place."
+          return false
+        end
+
+        dest = File.join('themes', target_name, 'css', 'app.css')
+        if File.exist?(dest) && !@options[:force]
+          warn "#{dest} already exists. Re-run with --force to overwrite."
+          return false
+        end
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+        puts "Ejected #{name} → #{dest}"
+
+        point_config_at(target_name) if target_name != current_config_theme
+        print_next_steps(dest, name)
+        true
+      end
+
+      def valid_names?(*names)
+        names.uniq.each do |n|
+          next if n.match?(AssetPipeline::THEME_NAME_RE)
+
+          warn "Invalid theme name #{n.inspect}: lowercase letters, digits, '-', '_' only."
+          return false
+        end
+        true
+      end
+
+      def site_root?
+        return true if File.file?(File.join('config', 'site.yml'))
+
+        warn 'No config/site.yml here — run this from your site root.'
+        false
+      end
+
+      def engine_theme_names
+        Dir.children(File.join(Abqari::ROOT, 'themes')).sort
+      end
+
+      def current_config_theme
+        config_path = File.join('config', 'site.yml')
+        File.read(config_path, encoding: 'UTF-8')[/^theme:\s*(\S+)/, 1]
+      rescue StandardError
+        nil
+      end
+
+      # Point `theme:` at the ejected name. Config files are the
+      # operator's — hand-commented, hand-ordered — so only a
+      # single unambiguous `theme:` line is edited in place; anything
+      # else gets an instruction instead of a surprise rewrite.
+      def point_config_at(target_name)
+        config_path = File.join('config', 'site.yml')
+        config = File.read(config_path, encoding: 'UTF-8')
+
+        if config.scan(/^theme:.*$/).size == 1
+          File.write(config_path, config.sub(/^theme:.*$/, "theme: #{target_name}"))
+          puts "Set `theme: #{target_name}` in config/site.yml"
+        else
+          puts "Now set `theme: #{target_name}` in config/site.yml"
+        end
+      end
+
+      # `source_name` is the ENGINE theme that was copied — a fork via
+      # `--as mytheme` still wants the source theme's fonts.
+      def print_next_steps(dest, source_name)
+        puts ''
+        puts 'Next:'
+        puts "  - Edit #{dest} — start with the :root token blocks."
+        puts '  - bin/serve to preview; theme edits hot-reload.'
+        print_font_hint(source_name)
+      end
+
+      # The ejected theme's stacks may name webfonts the site isn't
+      # downloading yet — without the matching `fonts:` block the theme
+      # silently falls back to system faces and its typography never
+      # materialises. Print the block rather than editing config in
+      # place: `fonts:` may already exist with the operator's own
+      # entries, and config files are theirs.
+      def print_font_hint(theme_name)
+        entries = ThemeFonts.yaml_entries(theme_name, indent: '  ')
+        return if entries.empty?
+
+        puts "  - The #{theme_name} theme wants self-hosted webfonts. Ensure"
+        puts '    config/site.yml carries this block, then run bin/fetch-fonts:'
+        puts ''
+        puts '      fonts:'
+        entries.each_line { |l| puts "    #{l.rstrip}" }
+      end
+    end
+  end
+end

data/lib/abqari/cli.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# The engine itself, not just the subcommands — CLI::New pins the
+# scaffolded Gemfile to Abqari::VERSION, and `abqari version` prints it.
+require_relative '../abqari'
+require_relative 'cli/new'
+require_relative 'cli/theme'
+
+module Abqari
+  # Tiny subcommand dispatcher for the `abqari` global executable.
+  #
+  # The dispatcher itself stays small on purpose: parse the leading
+  # subcommand word, hand off to its own class. Subcommands live one
+  # file each under `lib/abqari/cli/`. Each one accepts an argv tail
+  # and returns true on success / false on failure (or raises).
+  #
+  # Adding a new top-level command:
+  #   1. Create `lib/abqari/cli/<name>.rb` with `Abqari::CLI::<Name>`
+  #      exposing a `.run(argv)` class method.
+  #   2. Add it to `COMMANDS` below.
+  #
+  # No bin/* in scaffolded sites uses this dispatcher — site-level
+  # commands (`build`, `serve`, `audit`, …) are independent thin
+  # wrappers that require `'abqari'` and call the engine directly.
+  # The global `abqari` binary is intentionally limited to operations
+  # that don't run inside an existing site (the main one being
+  # `new <projectname>` to bootstrap a fresh site).
+  module CLI
+    COMMANDS = {
+      'new'     => 'Abqari::CLI::New',
+      'theme'   => 'Abqari::CLI::Theme',
+      'version' => :builtin_version,
+      '-v'      => :builtin_version,
+      '--version' => :builtin_version,
+      'help'    => :builtin_help,
+      '-h'      => :builtin_help,
+      '--help'  => :builtin_help
+    }.freeze
+
+    USAGE = <<~USAGE
+      Usage: abqari <command> [options]
+
+      Commands:
+        new <projectname>    Scaffold a new Abqari site in ./<projectname>/
+        theme eject <name>   Copy an engine theme into this site for editing
+        version              Print the engine version
+        help                 Show this message
+
+      Site-level commands (build, serve, audit, …) live inside each
+      scaffolded site as `bin/*` scripts — run them from the site's
+      root directory, not via this global binary. Run `abqari new`
+      to bootstrap a new site.
+    USAGE
+
+    class << self
+      # Parse argv's leading word + dispatch. Returns true on success,
+      # false on failure (or `exit(1)` after writing to $stderr for
+      # usage errors).
+      def run(argv)
+        cmd, *rest = argv
+        return print_help if cmd.nil? || cmd == ''
+
+        target = COMMANDS[cmd]
+        case target
+        when :builtin_version then print_version
+        when :builtin_help    then print_help
+        when String           then dispatch(target, rest)
+        else
+          warn "Unknown command: #{cmd.inspect}"
+          warn ''
+          warn USAGE
+          false
+        end
+      end
+
+      private
+
+      # Every subcommand's flag parsing funnels through here, so a bad
+      # flag is reported once, the same way, for all of them.
+      #
+      # `OptionParser#parse` raises on an unknown flag, and nothing
+      # caught it — so `abqari new --bloank mysite`, a one-character
+      # typo of a real flag, met a new user with a six-frame backtrace.
+      # Catching centrally (rather than in each subcommand) means a
+      # future subcommand gets the behaviour for free.
+      def dispatch(class_name, argv)
+        Object.const_get(class_name).run(normalize_argv(argv))
+      rescue OptionParser::ParseError => e
+        warn e.message
+        warn ''
+        warn "Run `abqari #{command_word(class_name)} --help` for the available options."
+        false
+      end
+
+      def command_word(class_name)
+        COMMANDS.key(class_name) || ''
+      end
+
+      # Force ARGV to UTF-8 so non-ASCII arguments survive.
+      #
+      # Ruby tags ARGV with the locale encoding. Under a C/POSIX locale
+      # — Docker images, cron, some CI runners, `env -i` — that's
+      # US-ASCII or ASCII-8BIT, and the first `File.expand_path` or ERB
+      # render against a UTF-8 template raised
+      # `Encoding::CompatibilityError`. `abqari new café` then died
+      # PART WAY THROUGH scaffolding, leaving a half-written directory
+      # that the non-empty preflight refused to overwrite on retry.
+      #
+      # The bytes are already correct; only the tag is wrong. Anything
+      # that isn't valid UTF-8 is left alone for the subcommand to
+      # reject with a real message.
+      def normalize_argv(argv)
+        argv.map do |arg|
+          candidate = arg.dup.force_encoding(Encoding::UTF_8)
+          candidate.valid_encoding? ? candidate : arg
+        end
+      end
+
+      def print_version
+        puts "abqari #{Abqari::VERSION}"
+        true
+      end
+
+      def print_help
+        puts USAGE
+        true
+      end
+    end
+  end
+end

data/lib/abqari/erbi_template.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'erubi'
+
+module Abqari
+  # ERB-compatible adapter around Erubi for auto-escaping templates.
+  #
+  # ERB has a deliberate "you escape your own output" contract — the
+  # engine emits `<%= value %>` verbatim and trusts the template author
+  # to wrap with `h(...)` for any value that isn't already safe HTML.
+  # That worked under Abqari's content-trusted model, but a single
+  # missed `h()` in a future partial is enough to ship stored XSS in a
+  # meta tag or JSON-LD node — see docs/security.md §3.
+  #
+  # Erubi flips the default: `<%= %>` always escapes, `<%== %>` is the
+  # opt-in raw output for values that are already known-safe HTML
+  # (rendered partials, helper output that builds tags, JSON inside
+  # `<script>` blocks, pre-rendered markdown content). The friction is
+  # the feature: emitting raw markup becomes a deliberate, visible
+  # choice instead of an unmarked default.
+  #
+  # The class exposes only `#result(binding)` so callers (Renderer's
+  # template cache, RenderContext layout chaining + render_string) can
+  # swap `ERB.new(src, trim_mode: '-')` → `ErbiTemplate.new(src)` and
+  # keep using the same `.result(binding)` API.
+  #
+  # Options used:
+  #   escape: true           - <%= escapes via `h(...)`, <%== is raw
+  #   escapefunc: 'h'        - call our `Helpers#h` (= `CGI.escapeHTML`)
+  #                            rather than Erubi's default. Keeps one
+  #                            escape function in the codebase.
+  #   trim: true             - equivalent to ERB's `trim_mode: '-'`
+  #   bufval: 'String.new(encoding: ::Encoding::UTF_8)'
+  #                          - force the accumulator to UTF-8. Erubi's
+  #                            default `::String.new` returns ASCII-8BIT,
+  #                            which downstream `Commonmarker.to_html`
+  #                            rejects when a post opts in via
+  #                            `erb: true` and the body contains non-
+  #                            ASCII glyphs. (Plain `+""` doesn't help
+  #                            because the eval-time encoding still
+  #                            defaults to ASCII-8BIT.)
+  #   freeze_template_literals: true - frozen-string-literal-friendly
+  class ErbiTemplate
+    # `filename` names the template on disk (a layout/partial path, or a
+    # synthetic label for an inline `erb: true` markdown body). It's
+    # threaded into both Erubi's compile and the `eval` below so a
+    # runtime error in a template reports the real file + line instead
+    # of an anonymous `(eval):NN` frame — with layout chaining and
+    # nested partials, that's the difference between "which of a dozen
+    # templates failed?" and a direct pointer.
+    def initialize(source, filename = '(erb)')
+      @filename = filename
+      @compiled_src = Erubi::Engine.new(
+        source,
+        escape: true,
+        escapefunc: 'h',
+        trim: true,
+        bufval: 'String.new(encoding: ::Encoding::UTF_8)',
+        freeze_template_literals: true,
+        filename: filename
+      ).src
+    end
+
+    # Evaluate against the supplied binding and return the rendered
+    # output. The compiled source declares its own `_buf` and returns it
+    # as the last expression, mirroring ERB#result. Passing `@filename`
+    # + line 1 makes backtraces point at the template file.
+    def result(bindng)
+      eval(@compiled_src, bindng, @filename, 1) # rubocop:disable Security/Eval
+    end
+  end
+end

data/lib/abqari/feed.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'cgi'
+require 'fileutils'
+
+module Abqari
+  # Generates RSS + JSON Feed for a single collection. Per-collection
+  # feeds are opt-in via `collections.<name>.feeds.enabled` (default
+  # true for posts — back-compat — and false for everything else).
+  #
+  # Output paths:
+  #   posts        →  /feed.xml + /feed.json   (back-compat root paths)
+  #   <other>      →  /<collection>/feed.xml + /<collection>/feed.json
+  #
+  # The root `/feed.xml` for posts is intentional: pre-existing
+  # subscribers + feed-reader caches keep working without redirects.
+  class Feed
+    MAX_ITEMS = 20
+
+    def initialize(site, collection_name = 'posts')
+      @site = site
+      @collection_name = collection_name
+    end
+
+    def write
+      return if items.empty?
+      return unless base_url
+
+      FileUtils.mkdir_p(File.dirname(rss_path))
+      File.write(rss_path,  rss)
+      File.write(json_path, json_feed)
+    end
+
+    # Class-level entry point: writes feeds for every collection that
+    # has `feeds.enabled: true`. Defaults to true only for posts so
+    # existing sites don't suddenly start emitting photo / publication
+    # feeds without opt-in.
+    def self.write_all(site)
+      site.collections.each do |name, cfg|
+        next unless cfg.fetch('enabled', true)
+
+        feeds_enabled = cfg.dig('feeds', 'enabled')
+        feeds_enabled = (name == 'posts') if feeds_enabled.nil?
+        next unless feeds_enabled
+
+        new(site, name).write
+      end
+    end
+
+    private
+
+    def items
+      @items ||= @site.collection(@collection_name)
+                       .select { |p| p.respond_to?(:date) && p.date }
+                       .first(MAX_ITEMS)
+    end
+
+    def base_url
+      @site.config['url']&.sub(%r{/\z}, '')
+    end
+
+    # Posts → /feed.xml + /feed.json (back-compat root paths).
+    # Other  → /<collection>/feed.xml + /<collection>/feed.json
+    #
+    # If `posts` is renamed via `slug:` (e.g. slug: stories), the feed
+    # follows: /stories/feed.xml + /stories/feed.json. The `/feed.xml`
+    # root path is reserved for un-renamed posts.
+    def rss_path
+      File.join(@site.output_dir, *path_parts('feed.xml'))
+    end
+
+    def json_path
+      File.join(@site.output_dir, *path_parts('feed.json'))
+    end
+
+    def feed_url(filename)
+      "#{base_url}#{absolute_path_segment}/#{filename}"
+    end
+
+    # The "effective" collection name for URL purposes — slug if set,
+    # canonical name otherwise.
+    def effective_name
+      slug = @site.collection_config(@collection_name)['slug'].to_s
+      slug.empty? ? @collection_name : slug
+    end
+
+    def path_parts(filename)
+      effective_name == 'posts' ? [filename] : [effective_name, filename]
+    end
+
+    def absolute_path_segment
+      effective_name == 'posts' ? '' : "/#{effective_name}"
+    end
+
+    def feed_title
+      base = @site.config['title'].to_s
+      # Use the slug-aliased name so the feed's own <title> matches the
+      # `<link rel="alternate" … title="…">` the head advertises (a
+      # `posts → stories` site reads "Stories", not "Posts").
+      effective_name == 'posts' ? base : "#{base} — #{effective_name.capitalize}"
+    end
+
+    def rss
+      entries = items.map do |item|
+        item_url = xml_escape("#{base_url}#{item.url}")
+        <<~ITEM.chomp
+            <item>
+              <title>#{xml_escape(item.title)}</title>
+              <link>#{item_url}</link>
+              <guid isPermaLink="true">#{item_url}</guid>
+              <pubDate>#{item.date.rfc822}</pubDate>
+              <description>#{xml_escape(item.description.to_s)}</description>
+            </item>
+        ITEM
+      end
+
+      <<~RSS
+        <?xml version="1.0" encoding="UTF-8"?>
+        <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+          <channel>
+            <title>#{xml_escape(feed_title)}</title>
+            <link>#{xml_escape("#{base_url}#{absolute_path_segment}/")}</link>
+            <description>#{xml_escape(@site.config['description'].to_s)}</description>
+            <language>#{xml_escape(@site.config['locale'] || 'en')}</language>
+            <atom:link href="#{xml_escape(feed_url('feed.xml'))}" rel="self" type="application/rss+xml"/>
+        #{entries.join("\n")}
+          </channel>
+        </rss>
+      RSS
+    end
+
+    def json_feed
+      data = {
+        version: 'https://jsonfeed.org/version/1.1',
+        title: feed_title,
+        description: @site.config['description'],
+        home_page_url: "#{base_url}#{absolute_path_segment}/",
+        feed_url: feed_url('feed.json'),
+        language: @site.config['locale'] || 'en',
+        items: items.map do |item|
+          {
+            id: "#{base_url}#{item.url}",
+            url: "#{base_url}#{item.url}",
+            title: item.title,
+            summary: item.description,
+            date_published: item.date.iso8601,
+            tags: item.respond_to?(:tags) ? item.tags : []
+          }.compact.reject { |_, v| v.respond_to?(:empty?) && v.empty? }
+        end
+      }
+      JSON.pretty_generate(data)
+    end
+
+    def xml_escape(text)
+      CGI.escapeHTML(text.to_s)
+    end
+  end
+end