pandorga 1.2.1

data/lib/pandorga/jekyll/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/lib/pandorga/jekyll/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/lib/pandorga/jekyll/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

data/lib/pandorga/jekyll/plugins/content_writing_index.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "date"
+require "pathname"
+require "set"
+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"
+
+# Indexes articles and posts from /content for timeline and network features
+# without emitting Jekyll collection pages (those load from the content API).
+module Jekyll
+  class ContentWritingIndex < Generator
+    safe true
+    priority :high
+
+
+    def generate(site)
+      return if site.config["shell_content_agnostic"]
+
+      content_root = File.join(site.source, site.config["content_root"] || "content")
+      entries = []
+
+      if File.directory?(content_root)
+        ContentWritingPaths::INDEX_BY_COLLECTION.each do |collection, relative_path|
+          directory = File.join(content_root, relative_path)
+          next unless File.directory?(directory)
+
+          Dir.glob(File.join(directory, "*.{md,markdown}")).sort.each do |absolute_path|
+            entry = build_entry(absolute_path, collection)
+            entries << entry if entry
+          end
+        end
+      end
+
+      site.data["writing_index"] = entries
+    end
+
+    private
+
+    def build_entry(absolute_path, collection)
+      repo_relative_path = ContentWritingPaths.repo_relative_for_index_collection(
+        collection, File.basename(absolute_path)
+      )
+      WritingEntry.build(absolute_path, collection, repo_relative_path)
+    end
+  end
+end

data/lib/pandorga/jekyll/plugins/content_writing_paths.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Canonical filesystem locations for articles and posts under content/.
+# Shared by writing indexers, slug validation, and content-key resolution.
+module ContentWritingPaths
+  CONTENT_ROOT_SEGMENT = "content"
+
+  BY_COLLECTION = {
+    "articles" => "collections/articles",
+    "posts" => "collections/posts"
+  }.freeze
+
+  BY_TYPE = {
+    "article" => "collections/articles",
+    "post" => "collections/posts"
+  }.freeze
+
+  TYPE_FOR_COLLECTION = {
+    "articles" => "article",
+    "posts" => "post"
+  }.freeze
+
+  COLLECTION_FOR_TYPE = TYPE_FOR_COLLECTION.invert.freeze
+
+  # Slim runtime index covers every keyed collection xcite can resolve.
+  INDEX_BY_COLLECTION = BY_COLLECTION.merge(
+    "products" => "collections/products",
+    "projects" => "collections/projects"
+  ).freeze
+
+  INDEX_TYPE_FOR_COLLECTION = TYPE_FOR_COLLECTION.merge(
+    "products" => "product",
+    "projects" => "project"
+  ).freeze
+
+  module_function
+
+  def content_relative(type_or_collection)
+    BY_COLLECTION[type_or_collection] || BY_TYPE.fetch(type_or_collection)
+  end
+
+  def repo_relative(type)
+    File.join(CONTENT_ROOT_SEGMENT, BY_TYPE.fetch(type))
+  end
+
+  def repo_relative_for_collection(collection, filename = nil)
+    base = File.join(CONTENT_ROOT_SEGMENT, BY_COLLECTION.fetch(collection))
+    filename ? File.join(base, filename) : base
+  end
+
+  def repo_relative_for_index_collection(collection, filename = nil)
+    base = File.join(CONTENT_ROOT_SEGMENT, INDEX_BY_COLLECTION.fetch(collection))
+    filename ? File.join(base, filename) : base
+  end
+end

data/lib/pandorga/jekyll/plugins/force_utf8_encoding.rb

@@ -0,0 +1,13 @@
+# Force UTF-8 as the process-wide default encoding.
+#
+# Some build environments (e.g. the Cloudflare build image) run under a non-UTF-8
+# locale such as `C`/`POSIX`, which makes Ruby's `Encoding.default_external` be
+# US-ASCII. Jekyll/kramdown then raise "The source text contains invalid
+# characters for the used encoding US-ASCII" when rendering non-ASCII content
+# (accents, em-dashes, etc.). Netlify defaulted to a UTF-8 locale, which hid this.
+#
+# Plugins are loaded before content is read and rendered, so setting the defaults
+# here makes the build locale-independent regardless of how `jekyll build` is
+# invoked. This is a no-op where the locale is already UTF-8 (local dev, CI).
+Encoding.default_external = Encoding::UTF_8 unless Encoding.default_external == Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8 unless Encoding.default_internal == Encoding::UTF_8

data/lib/pandorga/jekyll/plugins/git_chronology.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "date"
+require "shellwords"
+require "open3"
+
+# Derives publication and last-modification dates for articles and posts.
+# Shared by the content JSON export script and Jekyll build-time indexers.
+#
+# `date` — editorial creation date: front matter `date`, else the YYYY-MM-DD filename
+#   prefix, else the first Git add (legacy files without a dated name).
+# `last_updated` — latest commit where the markdown body (after the closing ---) changed;
+#   front-matter-only edits do not advance it.
+#
+# Pitfall (see docs/content/architecture.md): history often crosses renames. git log --follow
+# reaches pre-migration commits, but git show <sha>:<current-path> does not — the path did
+# not exist yet. A failed show must never be treated as an empty body; resolve the path per
+# commit via git_commit_entries (--name-only) before comparing bodies.
+module GitChronology
+  WRITING_TYPES = %w[article post].freeze
+  FILENAME_DATE_RE = /\A(\d{4}-\d{2}-\d{2})-/.freeze
+
+  module_function
+
+  def reset_cache!
+    @chronology_memo = {}
+  end
+
+  def git_repo?
+    system("git rev-parse --is-inside-work-tree > /dev/null 2>&1")
+  end
+
+  def git_date(repo_relative_path, mode)
+    return nil unless git_repo?
+
+    path = repo_relative_path.to_s
+    case mode
+    when :creation
+      raw_out, _status = Open3.capture2("git", "log", "--follow", "--diff-filter=A", "--format=%ad", "--date=short", "--", path)
+      raw = raw_out.strip.split("\n").last
+    when :updated
+      # AM skips pure rename/copy commits (e.g. content migration) while still
+      # returning the add date for files that have only been created once.
+      raw_out, _status = Open3.capture2("git", "log", "--follow", "--diff-filter=AM", "-1", "--format=%ad", "--date=short", "--", path)
+      raw = raw_out.strip
+    else
+      return nil
+    end
+
+    raw unless raw.nil? || raw.empty?
+  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
+
+    [parts[1], parts[2]]
+  end
+
+  def markdown_body(text)
+    _front_matter, body = split_front_matter(text)
+    body
+  end
+
+  # Chronology compares semantic body content, not formatting noise from CMS saves
+  # (line endings, trailing spaces, or blank lines added/removed without text edits).
+  def normalize_body_for_chronology(body)
+    body.to_s
+        .gsub(/\r\n?/, "\n")
+        .each_line
+        .map(&:strip)
+        .reject(&:empty?)
+        .join("\n")
+  end
+
+  def bodies_changed_for_chronology?(body_a, body_b)
+    normalize_body_for_chronology(body_a) != normalize_body_for_chronology(body_b)
+  end
+
+  SHA_RE = /\A[0-9a-f]{40}\z/i
+
+  # Newest-first [commit_sha, repo_relative_path_at_that_commit] pairs.
+  #
+  # --follow alone is insufficient for body chronology: each revision must be read at the
+  # path that existed in that commit (_posts/… before the 2026-06-19 content/ migration,
+  # content/collections/posts/… after). Without --name-only, git show sha:current_path
+  # fails on older commits and last_updated incorrectly snaps to the rename date.
+  def git_commit_entries(repo_relative_path)
+    return [] unless git_repo?
+
+    path = repo_relative_path.to_s
+    out, _status = Open3.capture2("git", "log", "--follow", "--name-only", "--format=%H", "--", path)
+    lines = out.each_line.map(&:strip).reject(&:empty?)
+    return [] if lines.empty?
+
+    entries = []
+    index = 0
+    while index < lines.length
+      sha = lines[index]
+      break unless sha.match?(SHA_RE)
+
+      index += 1
+      paths = []
+      while index < lines.length && !lines[index].match?(SHA_RE)
+        paths << lines[index]
+        index += 1
+      end
+
+      path_at_commit = paths.empty? ? repo_relative_path.to_s : pick_path_at_commit(paths, repo_relative_path)
+      entries << [sha, path_at_commit]
+    end
+    entries
+  end
+
+  def pick_path_at_commit(paths, repo_relative_path)
+    basename = File.basename(repo_relative_path.to_s)
+    paths.find { |candidate| candidate.end_with?(basename) } || paths.last
+  end
+
+  def commit_date(sha)
+    out, _status = Open3.capture2("git", "log", "-1", "--format=%ad", "--date=short", sha)
+    out.strip
+  end
+
+  def file_content_at_commit(path_at_commit, sha)
+    # path_at_commit comes from git_commit_entries, not the caller's present-day path.
+    path = path_at_commit.to_s
+    content, status = Open3.capture2("git", "show", "#{sha}:#{path}", err: File::NULL)
+    return nil unless status.success?
+    return nil if content.nil? || content.empty?
+
+    content
+  end
+
+  def git_body_updated_date(repo_relative_path)
+    entries = git_commit_entries(repo_relative_path)
+    return nil if entries.empty?
+
+    # Walk newest → oldest; stop at the first pair where bodies differ.
+    # Do not substitute "" when file_content_at_commit returns nil — that was the
+    # migration bug (missing historical path read as an empty body edit).
+    entries.each_with_index do |(sha, path_at_commit), idx|
+      body = markdown_body(file_content_at_commit(path_at_commit, sha) || "")
+      if idx == entries.length - 1
+        return nil
+      end
+
+      older_sha, older_path = entries[idx + 1]
+      older_body = markdown_body(file_content_at_commit(older_path, older_sha) || "")
+      return commit_date(sha) if bodies_changed_for_chronology?(body, older_body)
+    end
+
+    nil
+  end
+
+  def filename_date(repo_relative_path)
+    stem = File.basename(repo_relative_path.to_s, File.extname(repo_relative_path.to_s))
+    match = stem.match(FILENAME_DATE_RE)
+    normalize_date_value(match[1]) if match
+  end
+
+  def editorial_date(front_matter, repo_relative_path)
+    normalize_date_value(front_matter["date"]) ||
+      filename_date(repo_relative_path) ||
+      git_date(repo_relative_path, :creation)
+  end
+
+  def chronology_for(repo_relative_path, type: nil, front_matter: nil)
+    return {} unless type.nil? || WRITING_TYPES.include?(type)
+
+    @chronology_memo ||= {}
+    memo_key = [repo_relative_path.to_s, type, normalize_date_value(front_matter&.dig("date"))]
+    return @chronology_memo[memo_key] if @chronology_memo.key?(memo_key)
+
+    fm = front_matter || {}
+    creation = editorial_date(fm, repo_relative_path)
+    updated = git_body_updated_date(repo_relative_path)
+    last_updated = updated || creation
+
+    result = {}
+    result["date"] = creation if creation
+    result["last_updated"] = last_updated if last_updated
+    @chronology_memo[memo_key] = result
+    result
+  end
+
+  def normalize_date_value(value)
+    case value
+    when Date then value.iso8601
+    when Time then value.to_date.iso8601
+    when String
+      stripped = value.strip
+      stripped.empty? ? nil : stripped
+    else
+      raw = value&.to_s&.strip
+      raw.nil? || raw.empty? ? nil : raw
+    end
+  end
+
+  def apply!(front_matter, repo_relative_path, type)
+    return front_matter unless WRITING_TYPES.include?(type)
+
+    chronology = chronology_for(repo_relative_path, type: type, front_matter: front_matter)
+    front_matter["date"] = chronology["date"] if chronology["date"]
+    front_matter["last_updated"] = chronology["last_updated"] if chronology["last_updated"]
+    front_matter
+  end
+end