pandorga 1.2.1

data/_plugins/content_keys.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "date"
+require "pathname"
+require "yaml"
+
+require_relative "git_chronology"
+require_relative "content_detail_paths"
+require_relative "content_writing_paths"
+
+# Canonical content identity and public detail URLs for articles, posts,
+# projects, and products. The front-matter `key` is the stable cross-reference
+# identifier; public path segments are derived from `key` (and Git `date` for
+# dated writing).
+module ContentKeys
+  KEYED_TYPES = %w[article post project product].freeze
+
+  TYPE_CONFIG = {
+    "article" => { dated: true, detail: :article_detail_path },
+    "post" => { dated: true, detail: :post_detail_path },
+    "project" => { dated: false, detail: :project_detail_path },
+    "product" => { dated: false, detail: :product_detail_path }
+  }.freeze
+
+  CONTENT_PATHS = ContentWritingPaths::BY_TYPE.transform_values { |rel| File.join(ContentWritingPaths::CONTENT_ROOT_SEGMENT, rel) }.merge(
+    "project" => "content/collections/projects",
+    "product" => "content/collections/products"
+  ).freeze
+
+  REDIRECTS_BEGIN = "# BEGIN content-key redirects (generated — do not edit)"
+  REDIRECTS_END = "# END content-key redirects (generated — do not edit)"
+
+  # Cloudflare Pages first-match wins. Specific 301s must sit above these
+  # SPA catch-alls or old slugs are rewritten with HTTP 200 and never redirect.
+  CATCHALL_200_PREFIXES = %w[/articles/:slug /posts/:slug /blog/:slug].freeze
+
+  class ValidationError < StandardError; end
+
+  module_function
+
+  def normalize_key(value)
+    value.to_s.strip
+  end
+
+  def normalize_date(value)
+    case value
+    when Date then value.iso8601
+    when Time then value.to_date.iso8601
+    when String
+      value.strip[0, 10]
+    else
+      value&.to_s&.strip&.[](0, 10)
+    end
+  end
+
+  def filename_stem(path)
+    File.basename(path.to_s, File.extname(path.to_s))
+  end
+
+  def infer_key_from_filename(path, type)
+    stem = filename_stem(path)
+    config = TYPE_CONFIG.fetch(type)
+    config[:dated] ? stem.sub(/\A\d{4}-\d{2}-\d{2}-/, "") : stem
+  end
+
+  def path_segment(type, key, date: nil)
+    normalized_key = normalize_key(key)
+    config = TYPE_CONFIG.fetch(type)
+    return normalized_key unless config[:dated]
+
+    day = normalize_date(date)
+    raise ValidationError, "dated content requires a publication date (key=#{normalized_key})" if day.nil? || day.empty?
+
+    "#{day}-#{normalized_key}"
+  end
+
+  def detail_path(type, key, date: nil)
+    segment = path_segment(type, key, date: date)
+    ContentDetailPaths.public_send(TYPE_CONFIG.fetch(type).fetch(:detail), segment)
+  end
+
+  def split_front_matter(text)
+    text = text.to_s.sub(/\A\xEF\xBB\xBF/, "")
+    return [{}, text] unless text.start_with?("---\n")
+
+    parts = text.split(/^---\s*$\n?/, 3)
+    return [{}, text] unless parts.length == 3
+
+    data = YAML.safe_load(parts[1], permitted_classes: [Date, Time], aliases: true) || {}
+    [data, parts[2]]
+  end
+
+  def load_entry(absolute_path, type, repo_root: Pathname.pwd)
+    text = File.read(absolute_path).sub(/\A\xEF\xBB\xBF/, "")
+    front_matter, = split_front_matter(text)
+    relative_source = Pathname.new(absolute_path).relative_path_from(repo_root.join("content")).to_s
+    repo_relative_path = Pathname.new("content").join(relative_source).to_s
+
+    if KEYED_TYPES.include?(type)
+      GitChronology.apply!(front_matter, repo_relative_path, type) if %w[article post].include?(type)
+    end
+
+    key = normalize_key(front_matter["key"])
+    date = front_matter["date"]
+    legacy_segment = filename_stem(absolute_path)
+
+    {
+      "type" => type,
+      "path" => absolute_path.to_s,
+      "repo_relative_path" => repo_relative_path,
+      "key" => key,
+      "date" => date,
+      "legacy_segment" => legacy_segment,
+      "path_segment" => key.empty? ? nil : path_segment(type, key, date: date),
+      "detail_path" => key.empty? ? nil : detail_path(type, key, date: date),
+      "redirects" => normalize_redirects(front_matter),
+      "published" => front_matter["published"] != false
+    }
+  end
+
+  def collect_entries(repo_root = Pathname.pwd)
+    entries = []
+    CONTENT_PATHS.each do |type, relative_dir|
+      directory = repo_root.join(relative_dir)
+      next unless directory.directory?
+
+      Dir.glob(directory.join("*.{md,markdown}")).sort.each do |absolute_path|
+        entries << load_entry(absolute_path, type, repo_root: repo_root)
+      end
+    end
+    entries
+  end
+
+  def published_entries(repo_root = Pathname.pwd)
+    collect_entries(repo_root).select { |entry| entry["published"] }
+  end
+
+  def validate!(repo_root = Pathname.pwd)
+    errors = []
+    published = published_entries(repo_root)
+    by_key = Hash.new { |hash, key| hash[key] = [] }
+
+    published.each do |entry|
+      key = entry["key"]
+      label = "#{entry["type"]} #{entry["repo_relative_path"]}"
+
+      if key.empty?
+        errors << "#{label}: missing required non-empty `key`"
+        next
+      end
+
+      begin
+        entry["path_segment"] = path_segment(entry["type"], key, date: entry["date"])
+        entry["detail_path"] = detail_path(entry["type"], key, date: entry["date"])
+      rescue ValidationError => e
+        errors << "#{label}: #{e.message}"
+        next
+      end
+
+      by_key[key] << label
+    end
+
+    by_key.each do |key, labels|
+      next if labels.length < 2
+
+      errors << "duplicate key #{key.inspect} used by: #{labels.join(', ')}"
+    end
+
+    return if errors.empty?
+
+    errors.each { |message| warn "ContentKeys: #{message}" }
+    raise ValidationError, "Content key validation failed with #{errors.length} error(s)"
+  end
+
+  def normalize_redirects(front_matter)
+    values = []
+    %w[redirects redirect_from].each do |field|
+      raw = front_matter[field]
+      case raw
+      when Array
+        values.concat(raw)
+      when String
+        values << raw unless raw.strip.empty?
+      end
+    end
+    values.map { |value| normalize_redirect_path(value) }.compact.uniq
+  end
+
+  def normalize_redirect_path(path)
+    value = path.to_s.strip
+    return nil if value.empty?
+
+    value = "/#{value}" unless value.start_with?("/")
+    value = value.chomp("/")
+    value
+  end
+
+  def redirect_rules(entries = nil)
+    entries ||= published_entries
+    rules = []
+
+    entries.each do |entry|
+      next if entry["detail_path"].nil?
+
+      canonical = entry["detail_path"].chomp("/")
+      entry["redirects"].each do |source|
+        next if source.nil? || source.empty?
+        next if source == canonical
+
+        rules << [source, "#{canonical}/", 301]
+        rules << ["#{source}/", "#{canonical}/", 301] unless source.end_with?("/")
+      end
+    end
+
+    rules.uniq
+  end
+
+  def alias_slugs(entry)
+    slugs = []
+    slugs << entry["legacy_segment"].to_s
+    slugs << entry["key"].to_s
+    slugs.concat(redirect_path_slugs(entry["redirects"]))
+    slugs.concat(compact_dated_slugs(slugs))
+
+    canonical = entry["path_segment"].to_s
+    slugs.map { |slug| slug.to_s.strip }.reject(&:empty?).uniq.reject { |slug| slug == canonical }
+  end
+
+  def catchall_200_line?(line)
+    stripped = line.to_s.strip
+    CATCHALL_200_PREFIXES.any? do |prefix|
+      stripped.start_with?("#{prefix} ") || stripped.start_with?("#{prefix}/ ")
+    end
+  end
+
+  def generated_redirects_precede_catchalls?(text)
+    begin_at = text.index(REDIRECTS_BEGIN)
+    catchall_at = text.lines.find_index { |line| catchall_200_line?(line) }
+    return false if begin_at.nil? || catchall_at.nil?
+
+    begin_line = text.lines.find_index { |line| line.include?(REDIRECTS_BEGIN) }
+    !begin_line.nil? && begin_line < catchall_at
+  end
+
+  def sync_redirects_file!(repo_root = Pathname.pwd, redirects_path: repo_root.join("_redirects"))
+    rules = redirect_rules(published_entries(repo_root))
+    body = rules.map { |source, target, code| "#{source} #{target} #{code}" }.join("\n")
+    block = [REDIRECTS_BEGIN, body, REDIRECTS_END].join("\n").strip
+
+    original = redirects_path.file? ? redirects_path.read : ""
+    stripped = if original.include?(REDIRECTS_BEGIN) && original.include?(REDIRECTS_END)
+                 original.sub(/#{Regexp.escape(REDIRECTS_BEGIN)}.*?#{Regexp.escape(REDIRECTS_END)}\n*/m, "")
+               else
+                 original
+               end
+
+    updated = insert_generated_redirects(stripped, block)
+    redirects_path.write(updated)
+  end
+
+  def insert_generated_redirects(text, block)
+    lines = text.to_s.lines
+    insert_at = catchall_section_start(lines)
+    block_text = "#{block.to_s.rstrip}\n"
+
+    if insert_at
+      before = lines[0...insert_at]
+      after = lines[insert_at..]
+      before.pop while before.last && before.last.strip.empty?
+      before_text = before.join
+      before_text += "\n" if !before_text.empty? && !before_text.end_with?("\n")
+      before_text += "\n" unless before_text.empty?
+      remainder = after.join.sub(/\A\n+/, "")
+      "#{before_text}#{block_text}\n#{remainder}"
+    else
+      updated = text.to_s.rstrip
+      updated.empty? ? block_text : "#{updated}\n\n#{block_text}"
+    end
+  end
+
+  def catchall_section_start(lines)
+    insert_at = lines.find_index { |line| catchall_200_line?(line) }
+    return nil unless insert_at
+
+    idx = insert_at
+    while idx > 0
+      previous = lines[idx - 1].to_s.strip
+      break unless previous.empty? || previous.start_with?("#")
+
+      idx -= 1
+    end
+    idx
+  end
+
+  def redirect_path_slugs(paths)
+    Array(paths).filter_map do |path|
+      segment = path.to_s.split("/").reject(&:empty?).last
+      segment unless segment.nil? || segment.empty?
+    end
+  end
+
+  def compact_dated_slugs(slugs)
+    Array(slugs).filter_map do |slug|
+      match = slug.to_s.match(/\A(\d{4})-(\d{2})-(\d{2})-(.+)\z/)
+      next unless match
+
+      "#{match[1]}#{match[2]}#{match[3]}-#{match[4]}"
+    end
+  end
+end

data/_plugins/content_local_serve.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "json"
+require "rbconfig"
+require "jekyll"
+
+# When local_content_serve is enabled (_config_dev.yml), copies the content
+# pipeline export and editorial media into the Jekyll output so the browser
+# runtime reads the same JSON layout as Cloudflare R2.
+module Jekyll
+  module ContentLocalServe
+    EXPORT_MUTEX = Mutex.new
+
+    class << self
+      attr_accessor :serve_options, :site_config
+
+      def enabled?(site)
+        site.config["local_content_serve"] == true
+      end
+
+      def export_root(site)
+        File.join(site.source, site.config["local_content_export_dir"] || "_content_json")
+      end
+
+      def content_root(site)
+        File.join(site.source, site.config["content_root"] || "content")
+      end
+
+      # Cold start only. The export stamps `generated_at` into manifest.json, and
+      # it writes into a directory Jekyll watches, so exporting on every build
+      # makes `jekyll serve --watch` regenerate itself forever. dev-serve.sh owns
+      # the re-export when content changes; this covers the case where somebody
+      # runs Jekyll against the dev config with no export on disk at all.
+      def export_script(site)
+        site_script = File.join(site.source, "scripts", "content", "export-content-json.rb")
+        return site_script if File.file?(site_script)
+
+        begin
+          require "pandorga"
+          gem_script = Pandorga.gem_path("scripts/content/export-content-json.rb")
+          return gem_script if File.file?(gem_script)
+        rescue LoadError
+          nil
+        end
+      end
+
+      def export_content!(site)
+        return if File.directory?(export_root(site))
+
+        script = export_script(site)
+        return unless script
+
+        content_dir = site.config["content_root"] || "content"
+        output_dir = site.config["local_content_export_dir"] || "_content_json"
+        env = {
+          "CONTENT_API_BASE_URL" => site.config["content_api_base_url"].to_s.strip,
+          "CONTENT_EXPORT_INCLUDE_UNPUBLISHED" => site.config["content_include_unpublished"] == true ? "1" : "0",
+          "PANDORGA_SITE_ROOT" => site.source.to_s,
+          "CONTENT_EXPORT_SKIP_VALIDATE" => "1"
+        }
+
+        ruby_bin = RbConfig.ruby
+        success = system(env, ruby_bin, script, content_dir, output_dir, chdir: site.source)
+        return if success
+
+        Jekyll.logger.error "ContentLocalServe:", "export-content-json.rb failed"
+        raise "Content export failed; run bundle exec pandorga export content _content_json"
+      end
+
+      def copy_tree(source, destination)
+        return unless File.directory?(source)
+
+        Pathname.glob(File.join(source, "**", "*"), File::FNM_DOTMATCH).each do |path|
+          next if path.directory?
+
+          relative = path.relative_path_from(Pathname.new(source)).to_s
+          target = File.join(destination, relative)
+          FileUtils.mkdir_p(File.dirname(target))
+          FileUtils.cp(path.to_s, target)
+        end
+      end
+
+      def publish!(site)
+        export_root = export_root(site)
+        export_content!(site)
+
+        copy_tree(export_root, site.dest)
+        copy_tree(File.join(content_root(site), "media"), File.join(site.dest, "media"))
+      end
+
+      def store_serve_options(options)
+        @serve_options = Jekyll.configuration(options)
+      rescue StandardError
+        @serve_options = options
+      end
+
+      def reexport!(options = nil)
+        opts = options || serve_options || site_config || {}
+        source = opts["source"] || Dir.pwd
+        destination = opts["destination"] || File.join(source, "_site")
+        content_dir = opts["content_root"] || "content"
+        output_dir = opts["local_content_export_dir"] || "_content_json"
+        script = File.join(source, "scripts", "content", "export-content-json.rb")
+
+        return [false, "Missing export script at #{script}"] unless File.file?(script)
+
+        env = {
+          "CONTENT_API_BASE_URL" => opts.fetch("content_api_base_url", "").to_s.strip,
+          "CONTENT_EXPORT_INCLUDE_UNPUBLISHED" => (opts["content_include_unpublished"] != false) ? "1" : "0"
+        }
+
+        ruby_bin = RbConfig.ruby
+        Jekyll.logger.info "ContentLocalServe:", "Re-exporting content JSON..."
+        success = system(env, ruby_bin, script, content_dir, output_dir, chdir: source)
+        return [false, "export-content-json.rb execution failed"] unless success
+
+        export_path = File.join(source, output_dir)
+        copy_tree(export_path, destination)
+        copy_tree(File.join(source, content_dir, "media"), File.join(destination, "media"))
+
+        shell_trigger = File.join(source, "pages", "articles", "index.html")
+        FileUtils.touch(shell_trigger) if File.file?(shell_trigger)
+
+        Jekyll.logger.info "ContentLocalServe:", "Re-export complete and mirrored to #{destination}"
+        [true, "Content JSON re-exported successfully"]
+      rescue StandardError => e
+        Jekyll.logger.error "ContentLocalServe:", "Re-export error: #{e.message}"
+        [false, "Re-export error: #{e.message}"]
+      end
+
+      def handle_reexport_request(_req, res)
+        res["Content-Type"] = "application/json; charset=utf-8"
+        res["Cache-Control"] = "no-store, no-cache, must-revalidate"
+
+        opts = serve_options || site_config || {}
+        unless opts["content_include_unpublished"] || opts["unpublished"] || opts["local_content_serve"]
+          res.status = 403
+          res.body = JSON.generate({ "ok" => false, "error" => "Dev re-export is disabled in production mode" })
+          return
+        end
+
+        EXPORT_MUTEX.synchronize do
+          success, message = reexport!(opts)
+          if success
+            res.status = 200
+            res.body = JSON.generate({ "ok" => true, "message" => message })
+          else
+            res.status = 500
+            res.body = JSON.generate({ "ok" => false, "error" => message })
+          end
+        end
+      end
+    end
+
+    Jekyll::Hooks.register :site, :after_init do |site|
+      ContentLocalServe.site_config = site.config
+    end
+
+    Jekyll::Hooks.register :site, :post_write do |site|
+      next unless ContentLocalServe.enabled?(site)
+
+      ContentLocalServe.publish!(site)
+      Jekyll.logger.info "ContentLocalServe:", "Published local content JSON and media to #{site.dest}"
+    end
+  end
+end

data/_plugins/content_site_adapter.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "date"
+require "pathname"
+require "ostruct"
+require "yaml"
+
+require_relative "git_chronology"
+require_relative "content_keys"
+require_relative "content_writing_paths"
+require_relative "lib/text_excerpt"
+require_relative "lib/writing_entry"
+
+begin
+  require "pandorga/registry"
+rescue LoadError
+  # Exporter may load this file before the gem lib path is on $LOAD_PATH.
+end
+
+# Minimal site-like object built from /content for export-time derived data
+# (timeline, writing_index) without running a Jekyll build.
+class ContentSiteAdapter
+  Doc = Struct.new(:data, :url, :path, keyword_init: true)
+
+  COLLECTION_DIRS = {
+    "products" => "collections/products",
+    "projects" => "collections/projects",
+    "jobs" => "collections/jobs"
+  }.freeze
+
+  attr_reader :collections, :data
+
+  def initialize(content_root, include_writing_index: true, config: nil)
+    @content_root = Pathname.new(content_root)
+    @config = config.is_a?(Hash) ? config : load_site_config
+    @collections = build_collections
+    @data = {
+      "education" => load_yaml_array("collections/data/education.yml"),
+      "writing_index" => include_writing_index ? build_writing_index : []
+    }
+  end
+
+  private
+
+  def load_site_config
+    root = Pathname.new(ENV.fetch("PANDORGA_SITE_ROOT", Dir.pwd)).expand_path
+    path = root.join("_config.yml")
+    return {} unless path.file?
+
+    YAML.safe_load(path.read, permitted_classes: [Date, Time], aliases: true) || {}
+  rescue StandardError
+    {}
+  end
+
+  def collection_dirs
+    return COLLECTION_DIRS unless defined?(PandorgaRegistry)
+
+    pages = PandorgaRegistry.pages(@config)
+    return COLLECTION_DIRS if pages.empty?
+
+    dirs = PandorgaRegistry.adapter_collection_dirs(pages)
+    dirs.empty? ? COLLECTION_DIRS : dirs
+  end
+
+  def build_collections
+    collection_dirs.each_with_object({}) do |(name, relative), hash|
+      hash[name] = OpenStruct.new(docs: load_collection_docs(relative, name))
+    end
+  end
+
+  def load_collection_docs(relative_dir, collection_name)
+    dir = @content_root.join(relative_dir)
+    return [] unless dir.directory?
+
+    type = case collection_name
+           when "products" then "product"
+           when "projects" then "project"
+           when "jobs" then "job"
+           else collection_name
+           end
+
+    Dir.glob(dir.join("*.{md,markdown}")).sort.filter_map do |absolute_path|
+      text = File.read(absolute_path).sub(/\A\xEF\xBB\xBF/, "")
+      front_matter, = split_front_matter(text)
+      next if front_matter["published"] == false
+
+      if ContentKeys::KEYED_TYPES.include?(type)
+        key = ContentKeys.normalize_key(front_matter["key"])
+        path_segment = ContentKeys.path_segment(type, key, date: front_matter["date"])
+        url = ContentKeys.detail_path(type, key, date: front_matter["date"])
+      else
+        key = ContentKeys.filename_stem(absolute_path)
+        path_segment = key
+        url = "/#{collection_name}/#{path_segment}/"
+      end
+
+      Doc.new(
+        data: stringify_keys(front_matter.merge("key" => key, "slug" => path_segment)),
+        url: url,
+        path: absolute_path
+      )
+    end
+  end
+
+  def build_writing_index
+    entries = []
+    index_collections.each do |collection, relative_path|
+      directory = @content_root.join(relative_path)
+      next unless directory.directory?
+
+      Dir.glob(directory.join("*.{md,markdown}")).sort.each do |absolute_path|
+        entry = build_writing_entry(absolute_path, collection)
+        entries << entry if entry
+      end
+    end
+    entries
+  end
+
+  def index_collections
+    if defined?(PandorgaRegistry)
+      pages = PandorgaRegistry.pages(@config)
+      unless pages.empty?
+        map = PandorgaRegistry.writing_collections(pages)
+        return map.keys.each_with_object({}) do |name, hash|
+          hash[name] = "collections/#{name}"
+        end
+      end
+    end
+    ContentWritingPaths::INDEX_BY_COLLECTION
+  end
+
+  def build_writing_entry(absolute_path, collection)
+    relative_source = Pathname.new(absolute_path).relative_path_from(@content_root).to_s
+    repo_relative_path = Pathname.new(ContentWritingPaths::CONTENT_ROOT_SEGMENT)
+                         .join(relative_source).to_s
+    WritingEntry.build(absolute_path, collection, repo_relative_path)
+  end
+
+  def load_yaml_array(relative_path)
+    path = @content_root.join(relative_path)
+    return [] unless path.file?
+
+    YAML.safe_load_file(path, permitted_classes: [Date, Time], aliases: true) || []
+  end
+
+  def split_front_matter(text)
+    return [{}, text] unless text.start_with?("---\n")
+
+    parts = text.split(/^---\s*$\n?/, 3)
+    return [{}, text] unless parts.length == 3
+
+    data = YAML.safe_load(parts[1], permitted_classes: [Date, Time], aliases: true) || {}
+    [data, parts[2]]
+  end
+
+  def stringify_keys(hash)
+    hash.transform_keys(&:to_s)
+  end
+end

data/_plugins/content_validators_hook.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "lib/content_validators"
+
+# Editorial validation for content-aware builds only. Public Pages shells set
+# shell_content_agnostic and skip this — gates live in validate.sh / export.
+module Jekyll
+  class ContentValidatorsHook < Generator
+    safe true
+    priority :highest
+
+    def generate(site)
+      return if site.config["shell_content_agnostic"]
+
+      ContentValidators.validate_all!(Pathname.new(site.source))
+    end
+  end
+end