pandorga 1.2.1

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

@@ -0,0 +1,43 @@
+require 'date'
+require 'time'
+
+# This plugin automatically derives 'date' and 'last_updated' from Git history
+# for articles and posts, ensuring Git is the single source of truth for chronology.
+module Jekyll
+  class GitMetadataGenerator < Generator
+    safe true
+    priority :high
+
+    def generate(site)
+      return unless GitChronology.git_repo?
+
+      article_docs = site.collections["articles"]&.docs || []
+      post_docs = site.collections["posts"]&.docs || []
+      return if article_docs.empty? && post_docs.empty?
+
+      (article_docs + post_docs).each do |doc|
+        next unless doc.path.match?(/\.(md|markdown)$/)
+
+        doc.data['language'] = doc.collection.label == 'articles' ? 'enus' : 'ptbr'
+        GitChronology.apply!(doc.data, doc.path, doc.collection.label == 'articles' ? 'article' : 'post')
+
+        if doc.data['date']
+          begin
+            doc.data['date'] = Time.parse(doc.data['date'].to_s)
+          rescue ArgumentError
+          end
+        end
+
+        if doc.data['last_updated']
+          begin
+            doc.data['last_updated'] = Time.parse(doc.data['last_updated'].to_s)
+          rescue ArgumentError
+          end
+        end
+      end
+
+      article_docs.sort_by! { |d| d.data['last_updated'] || d.data['date'] || Time.now }.reverse!
+      post_docs.sort_by! { |d| d.data['last_updated'] || d.data['date'] || Time.now }.reverse!
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Renders the private CV job body fields to HTML for the print layouts,
+# storing the result in doc.data["extended"/"single_page"].
+# body_public is not rendered here: the public CV page reads it straight
+# from the exported JSON through the client-side runtime.
+module Jekyll
+  class JobSectionsGenerator < Generator
+    safe true
+    priority :high
+
+    def generate(site)
+      return if site.config["shell_content_agnostic"]
+
+      converter = site.find_converter_instance(Jekyll::Converters::Markdown)
+
+      (site.collections["jobs"]&.docs || []).each do |doc|
+        %w[extended single_page].each do |key|
+          markdown = doc.data["body_#{key}"].to_s.strip
+          doc.data[key] = converter.convert(markdown) unless markdown.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "resource_validator"
+require_relative "tag_validator"
+require_relative "../writing_slug_limits"
+require_relative "../content_keys"
+
+# Single validation entry point for editorial content under content/.
+module ContentValidators
+  module_function
+
+  def validate_all!(repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    errors = []
+    errors.concat(ResourceValidator.collect_errors(root))
+    errors.concat(TagValidator.collect_errors(root))
+    errors.concat(WritingSlugLimits.collect_errors(root))
+
+    unless errors.empty?
+      raise ArgumentError, "Content validation failed:\n  - #{errors.join("\n  - ")}"
+    end
+
+    ContentKeys.validate!(root)
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+# Shared resource collection validation (content/ source, not Jekyll collections).
+module ResourceValidator
+  module_function
+
+  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 collect_errors(repo_root)
+    root = Pathname.new(repo_root)
+    resources_dir = root.join("content/collections/resources")
+    return [] unless resources_dir.directory?
+
+    errors = []
+    resources_dir.glob("*.{md,markdown}").sort.each do |source|
+      front_matter, = split_front_matter(source.read)
+      name = front_matter["name"] || source.basename(source.extname).to_s
+      type = front_matter["type"].to_s.downcase
+      link = front_matter["link"].to_s
+
+      if link.empty?
+        errors << "#{name}: missing required 'link' field"
+        next
+      end
+
+      case type
+      when "youtube"
+        unless link.match?(%r{\Ahttps?://(www\.)?(youtube\.com|youtu\.be)/}i)
+          errors << "#{name}: type 'youtube' but link does not point to youtube.com or youtu.be (got: #{link})"
+        end
+      when "spotify"
+        unless link.match?(%r{\Ahttps?://(open\.)?spotify\.com/}i)
+          errors << "#{name}: type 'spotify' but link does not point to spotify.com (got: #{link})"
+        end
+      when "pdf"
+        unless link.end_with?(".pdf")
+          errors << "#{name}: type 'pdf' but link does not end with .pdf (got: #{link})"
+        end
+      end
+    end
+
+    errors
+  end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+require "date"
+
+# Tags replaced category as the single classification axis for articles and
+# rascunhos. Vocabulary is closed per collection and loaded from
+# `_config.yml` → `pandorga.taxonomies` (PLT Phase 1).
+module TagValidator
+  DEFAULT_MAX_TAGS = 3
+
+  COLLECTIONS_WITHOUT_REQUIRED_TAGS = %w[posts].freeze
+
+  module_function
+
+  def load_vocabularies(repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    config_path = root.join("_config.yml")
+    return {} unless config_path.file?
+
+    config = YAML.safe_load(config_path.read, permitted_classes: [Date, Time], aliases: true) || {}
+    vocab = {}
+
+    taxonomies = config.dig("pandorga", "taxonomies")
+    if taxonomies.is_a?(Hash)
+      taxonomies.each do |collection, spec|
+        next unless spec.is_a?(Hash)
+
+        tags = spec["tags"]
+        next unless tags.is_a?(Array)
+
+        vocab[collection.to_s] = tags.map(&:to_s).freeze
+      end
+    end
+
+    # Page-local taxonomy (pandorga.pages[].taxonomy) fills gaps.
+    pages = config.dig("pandorga", "pages")
+    if pages.is_a?(Array)
+      pages.each do |page|
+        next unless page.is_a?(Hash)
+
+        collection = page["collection"].to_s
+        next if collection.empty? || vocab.key?(collection)
+
+        spec = page["taxonomy"]
+        next unless spec.is_a?(Hash)
+
+        tags = spec["tags"]
+        next unless tags.is_a?(Array)
+
+        vocab[collection] = tags.map(&:to_s).freeze
+      end
+    end
+
+    vocab
+  end
+
+  def max_tags_for(collection, repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    config_path = root.join("_config.yml")
+    return DEFAULT_MAX_TAGS unless config_path.file?
+
+    config = YAML.safe_load(config_path.read, permitted_classes: [Date, Time], aliases: true) || {}
+    max = config.dig("pandorga", "taxonomies", collection.to_s, "max")
+    if max.nil?
+      pages = config.dig("pandorga", "pages")
+      if pages.is_a?(Array)
+        page = pages.find { |p| p.is_a?(Hash) && p["collection"].to_s == collection.to_s }
+        max = page.dig("taxonomy", "max") if page.is_a?(Hash)
+      end
+    end
+    max.nil? ? DEFAULT_MAX_TAGS : Integer(max)
+  rescue ArgumentError, TypeError
+    DEFAULT_MAX_TAGS
+  end
+
+  def collect_errors(repo_root = Pathname.pwd)
+    root = Pathname.new(repo_root)
+    errors = []
+    vocabulary = load_vocabularies(root)
+
+    if vocabulary.empty?
+      errors << "_config.yml: pandorga.taxonomies is missing or empty"
+      return errors
+    end
+
+    vocabulary.each do |collection, allowed|
+      dir = root.join("content", "collections", collection)
+      next unless dir.directory?
+
+      tags_required = !COLLECTIONS_WITHOUT_REQUIRED_TAGS.include?(collection)
+      max_tags = max_tags_for(collection, root)
+
+      Dir.glob(dir.join("*.md")).sort.each do |path|
+        relative = Pathname.new(path).relative_path_from(root)
+        front_matter = read_front_matter(path)
+        next if front_matter.nil?
+
+        if front_matter.key?("category")
+          errors << "#{relative}: uses `category`; tags replaced it as the " \
+                    "single classification axis"
+        end
+
+        tags = front_matter["tags"]
+        if tags.nil?
+          errors << "#{relative}: missing `tags`" if tags_required
+          next
+        end
+
+        unless tags.is_a?(Array)
+          errors << "#{relative}: `tags` must be a list, got #{tags.class}"
+          next
+        end
+
+        if tags.empty?
+          errors << "#{relative}: `tags` is empty; every entry needs at least one" if tags_required
+          next
+        end
+
+        if tags.size > max_tags
+          errors << "#{relative}: #{tags.size} tags exceeds the #{max_tags} " \
+                    "allowed — pick the ones that would actually be filtered on"
+        end
+
+        if tags.uniq.size != tags.size
+          errors << "#{relative}: duplicate tags #{(tags - tags.uniq).uniq.inspect}"
+        end
+
+        unknown = tags.reject { |tag| allowed.include?(tag.to_s) }
+        next if unknown.empty?
+
+        errors << "#{relative}: unknown #{collection} tag(s) #{unknown.inspect}. " \
+                  "Allowed: #{allowed.join(', ')}"
+      end
+    end
+
+    errors
+  end
+
+  def read_front_matter(path)
+    source = File.read(path)
+    return nil unless source.start_with?("---")
+
+    raw = source.split(/^---\s*$/, 3)[1]
+    return nil if raw.nil?
+
+    parsed = YAML.safe_load(raw, permitted_classes: [Date, Time], aliases: true)
+    parsed.is_a?(Hash) ? parsed : nil
+  rescue Psych::SyntaxError
+    nil
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Plain-text listing excerpt from editorial Markdown.
+# Mirrors textExcerpt() in _includes/content-runtime/40-listing.html closely
+# enough for card previews. Liquid includes are stripped rather than rendered.
+module TextExcerpt
+  LIMIT = 220
+
+  module_function
+
+  def from_markdown(markdown, limit: LIMIT)
+    text = markdown.to_s.sub(/\A\xEF\xBB\xBF/, "")
+    text = strip_non_prose(text)
+    text = flatten_markup(text)
+    text = text.gsub(/\s+/, " ").strip
+    truncate(text, limit)
+  end
+
+  def listing_fields(front_matter, body)
+    editorial = front_matter["description"].to_s.strip
+    excerpt = from_markdown(body)
+    {
+      "description" => editorial,
+      "excerpt" => excerpt
+    }
+  end
+
+  def strip_non_prose(text)
+    text = text.gsub(/<!--[\s\S]*?-->/, " ")
+    text = text.gsub(/\{%-?[\s\S]*?-?%\}/, " ")
+    text = text.gsub(/\$\$[\s\S]*?\$\$/, " ")
+    text = text.gsub(/\$[^$\n]+\$/, " ")
+    text = text.gsub(/\\\[[\s\S]*?\\\]/, " ")
+    text = text.gsub(/\\\([\s\S]*?\\\)/, " ")
+    text.gsub(/```[\s\S]*?```/, " ")
+  end
+
+  def flatten_markup(text)
+    text = text.gsub(/!\[([^\]]*)\]\([^)]+\)/, ' \1 ')
+    text = text.gsub(/\[([^\]]+)\]\([^)]+\)/, '\1')
+    text = text.gsub(/^\#{1,6}\s+(.+?)\s*$/) { "#{Regexp.last_match(1).sub(/:+\s*\z/, "")}: " }
+    text = text.gsub(/<br\s*\/?>/i, " ")
+    text = text.gsub(/<[^>]+>/, " ")
+    text = text.gsub(/[*_~`]+/, "")
+    text = text.gsub(/^\s*>\s+/, "")
+    text = text.gsub(/^\s*[-*+]\s+/, "")
+    text = text.gsub(/^\s*\d+\.\s+/, "")
+    text.gsub(/\|/, " ")
+  end
+
+  def truncate(text, limit)
+    return text if text.length <= limit
+
+    "#{text[0, [limit - 3, 0].max].rstrip}..."
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+require_relative "../git_chronology"
+require_relative "../content_keys"
+require_relative "../content_writing_paths"
+require_relative "text_excerpt"
+
+# Builds one writing-index record from a content Markdown file.
+#
+# Two callers need the identical record from the identical files:
+# Jekyll::ContentWritingIndex (inside a Jekyll build) and ContentSiteAdapter
+# (standalone, for scripts/content/export-content-json.rb). They differ only in how
+# they derive the repo-relative path used for Git chronology, so each passes
+# its own. Everything downstream lives here, because a field added or a bug
+# fixed in one copy used to leave the other silently beNewsreader.
+module WritingEntry
+  XCITE_RE = /\{%-?\s*include\s+xcite\.html\s+key=["']([^"']+)["'][^%]*-?%\}/
+
+  module_function
+
+  # Returns the record hash, or nil when the document is unpublished or keyless.
+  def build(absolute_path, collection, repo_relative_path)
+    text = File.read(absolute_path).sub(/\A\xEF\xBB\xBF/, "")
+    front_matter, body = split_front_matter(text)
+    return nil if front_matter["published"] == false
+
+    writing_type = ContentWritingPaths::INDEX_TYPE_FOR_COLLECTION.fetch(collection)
+    if %w[article post].include?(writing_type)
+      GitChronology.apply!(front_matter, repo_relative_path, writing_type)
+      publication_date = front_matter["date"]
+    else
+      publication_date = ContentKeys.normalize_date(front_matter["date"]) ||
+                         ContentKeys.normalize_date(front_matter["start_date"])
+    end
+
+    key = ContentKeys.normalize_key(front_matter["key"])
+    return nil if key.empty?
+
+    path_segment = ContentKeys.path_segment(writing_type, key, date: publication_date)
+    xcites = Array(front_matter["xcites"]).map(&:to_s).reject(&:empty?)
+    xcites = body.scan(XCITE_RE).flatten.uniq if xcites.empty?
+
+    title = front_matter["title"].to_s
+    title = front_matter["product"].to_s if title.empty? && front_matter["product"]
+    title = front_matter["project"].to_s if title.empty? && front_matter["project"]
+    listing = TextExcerpt.listing_fields(front_matter, body)
+
+    {
+      "slug" => path_segment,
+      "key" => key,
+      "title" => title,
+      "date" => normalize_date(publication_date),
+      "last_updated" => normalize_date(front_matter["last_updated"]),
+      "url" => ContentKeys.detail_path(writing_type, key, date: publication_date),
+      "type" => collection,
+      "collection" => collection,
+      "category" => front_matter["category"].to_s,
+      "description" => listing["description"],
+      "excerpt" => listing["excerpt"],
+      "thumbnail" => front_matter["thumbnail"].to_s,
+      "xcites" => xcites,
+      "company" => front_matter["company"].to_s,
+      "product" => front_matter["product"].to_s,
+      "project" => front_matter["project"].to_s,
+      "tagline" => front_matter["tagline"].to_s,
+      "start_date" => front_matter["start_date"].to_s,
+      "end_date" => front_matter["end_date"].to_s,
+      "sort_order" => front_matter["sort_order"],
+      "status" => front_matter["status"].to_s,
+      "label" => front_matter["label"].to_s,
+      "icon" => front_matter["icon"].to_s,
+      "tags" => Array(front_matter["tags"]),
+      "external_url" => front_matter["external_url"].to_s,
+      "article_url" => front_matter["article_url"].to_s,
+      "github" => front_matter["github"].to_s,
+      "aliases" => ContentKeys.alias_slugs(
+        "legacy_segment" => File.basename(absolute_path, File.extname(absolute_path)),
+        "key" => key,
+        "redirects" => ContentKeys.normalize_redirects(front_matter),
+        "path_segment" => path_segment
+      )
+    }
+  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 normalize_date(value)
+    case value
+    when Date then value.iso8601
+    when Time then value.to_date.iso8601
+    when String then value
+    else
+      value&.to_s
+    end
+  end
+end

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "jekyll/commands/serve"
+require "json"
+require "net/http"
+require "uri"
+require_relative "content_detail_paths"
+
+# Mirrors Cloudflare _redirects detail rewrites during `jekyll serve` so
+# /posts/:slug/ and /articles/:slug/ work locally without per-slug HTML files.
+# Also handles the local dev re-export endpoint and proxies /api/studio/* to
+# `wrangler pages dev` (./scripts/studio-api-dev.sh, default :8788).
+module Jekyll
+  module ContentDetailRewrites
+    REEXPORT_PATHS = ["/__dev/reexport", "/api/dev/reexport"].freeze
+    STUDIO_API_PREFIX = "/api/studio"
+    STUDIO_API_DEFAULT_ORIGIN = "http://127.0.0.1:8788"
+
+    module_function
+
+    def studio_api_proxy_enabled?
+      env = ENV["STUDIO_API_PROXY"]
+      return false if env == "0" || env == "false"
+
+      true
+    end
+
+    def studio_api_path?(path)
+      path == STUDIO_API_PREFIX || path.start_with?("#{STUDIO_API_PREFIX}/")
+    end
+
+    def studio_api_origin
+      ENV.fetch("STUDIO_API_ORIGIN", STUDIO_API_DEFAULT_ORIGIN)
+    end
+
+    def proxy_studio_api!(req, res)
+      origin = studio_api_origin
+      target = URI.join(origin.end_with?("/") ? origin : "#{origin}/", req.path.sub(%r{\A/}, ""))
+      target.query = req.query_string unless req.query_string.to_s.empty?
+
+      http = Net::HTTP.new(target.host, target.port)
+      http.open_timeout = 2
+      http.read_timeout = 60
+      http.use_ssl = target.scheme == "https"
+
+      upstream =
+        case req.request_method
+        when "GET" then Net::HTTP::Get.new(target)
+        when "PUT" then Net::HTTP::Put.new(target)
+        when "POST" then Net::HTTP::Post.new(target)
+        when "OPTIONS" then Net::HTTP::Options.new(target)
+        when "HEAD" then Net::HTTP::Head.new(target)
+        else
+          res.status = 405
+          res["Content-Type"] = "application/json; charset=utf-8"
+          res.body = '{"error":"method_not_allowed"}'
+          return
+        end
+
+      %w[Authorization Content-Type Accept Origin].each do |name|
+        value = req[name]
+        upstream[name] = value if value && !value.empty?
+      end
+
+      if %w[PUT POST].include?(req.request_method)
+        body = req.body
+        upstream.body = body if body
+      end
+
+      begin
+        response = http.request(upstream)
+      rescue StandardError => e
+        res.status = 502
+        res["Content-Type"] = "application/json; charset=utf-8"
+        res.body = JSON.generate(
+          error: "studio_api_unavailable",
+          message: "Proxy to #{origin} failed: #{e.class}: #{e.message}. " \
+                   "Start ./scripts/studio-api-dev.sh (wrangler pages dev)."
+        )
+        return
+      end
+
+      res.status = response.code.to_i
+      response.each_header do |key, value|
+        next if %w[transfer-encoding connection content-length].include?(key.downcase)
+
+        res[key] = value
+      end
+      res.body = response.body
+    end
+
+    def install_serve_patch!
+      require "jekyll/commands/serve/servlet"
+      servlet = Jekyll::Commands::Serve::Servlet
+      return if servlet.method_defined?(:content_detail_do_GET)
+
+      servlet.alias_method :content_detail_do_GET, :do_GET
+      servlet.class_eval do
+        def do_GET(req, res)
+          if ContentDetailRewrites.studio_api_proxy_enabled? &&
+             ContentDetailRewrites.studio_api_path?(req.path)
+            ContentDetailRewrites.proxy_studio_api!(req, res)
+            return
+          end
+
+          if ContentDetailRewrites::REEXPORT_PATHS.include?(req.path)
+            if defined?(ContentLocalServe)
+              ContentLocalServe.handle_reexport_request(req, res)
+            else
+              res.status = 501
+              res["Content-Type"] = "text/plain"
+              res.body = "Dev re-export handler not loaded"
+            end
+            return
+          end
+
+          target = ContentDetailPaths.rewrite_path(req.path)
+          if target
+            req.instance_variable_set(:@path, target)
+            req.instance_variable_set(:@path_info, target)
+          end
+          content_detail_do_GET(req, res)
+
+          if req.path.end_with?(".json")
+            res["Cache-Control"] = "no-cache, no-store, must-revalidate"
+            res["Pragma"] = "no-cache"
+            res["Expires"] = "0"
+          end
+        end
+
+        def do_POST(req, res)
+          if ContentDetailRewrites.studio_api_proxy_enabled? &&
+             ContentDetailRewrites.studio_api_path?(req.path)
+            ContentDetailRewrites.proxy_studio_api!(req, res)
+            return
+          end
+
+          if ContentDetailRewrites::REEXPORT_PATHS.include?(req.path)
+            if defined?(ContentLocalServe)
+              ContentLocalServe.handle_reexport_request(req, res)
+            else
+              res.status = 501
+              res["Content-Type"] = "text/plain"
+              res.body = "Dev re-export handler not loaded"
+            end
+            return
+          end
+
+          res.status = 405
+          res["Content-Type"] = "text/plain"
+          res.body = "Method Not Allowed"
+        end
+
+        def do_PUT(req, res)
+          if ContentDetailRewrites.studio_api_proxy_enabled? &&
+             ContentDetailRewrites.studio_api_path?(req.path)
+            ContentDetailRewrites.proxy_studio_api!(req, res)
+            return
+          end
+
+          res.status = 405
+          res["Content-Type"] = "text/plain"
+          res.body = "Method Not Allowed"
+        end
+
+        def do_OPTIONS(req, res)
+          if ContentDetailRewrites.studio_api_proxy_enabled? &&
+             ContentDetailRewrites.studio_api_path?(req.path)
+            ContentDetailRewrites.proxy_studio_api!(req, res)
+            return
+          end
+
+          res.status = 204
+        end
+      end
+    end
+  end
+
+  module Commands
+    class Serve
+      class << self
+        unless method_defined?(:content_detail_original_process)
+          alias_method :content_detail_original_process, :process
+
+          def process(options)
+            ContentLocalServe.store_serve_options(options) if defined?(ContentLocalServe)
+            ContentDetailRewrites.install_serve_patch!
+            content_detail_original_process(options)
+          end
+        end
+      end
+    end
+  end
+end