pandorga 1.2.1

data/lib/pandorga/commands/export.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rbconfig"
+
+module Pandorga
+  module Commands
+    # Delegate to the full content export pipeline shipped with the gem.
+    class Export
+      def run(argv)
+        site_root = Pathname.new(Dir.pwd).expand_path
+        script = Pathname.new(Pandorga.gem_path("scripts/content/export-content-json.rb"))
+        unless script.file?
+          warn "error: export script missing at #{script}"
+          return 1
+        end
+
+        content = argv[0] || "content"
+        dest = argv[1] || "_content_json"
+        env = ENV.to_h.merge(
+          "PANDORGA_SITE_ROOT" => site_root.to_s,
+          "RUBYOPT" => ["-I#{Pandorga.gem_path('lib')}", ENV["RUBYOPT"]].compact.join(" ")
+        )
+        cmd = [RbConfig.ruby, script.to_s, content, dest]
+        puts "pandorga export: #{content} → #{dest} (site #{site_root})"
+        system(env, *cmd, chdir: site_root.to_s) ? 0 : 1
+      end
+    end
+  end
+end

data/lib/pandorga/commands/install_functions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Pandorga
+  module Commands
+    # Option A (PLT-0.2): copy functions/ and studio/ from the gem into the site root
+    # so Cloudflare Pages can compile Functions from the project root.
+    class InstallFunctions
+      STAMP = ".pandorga-version"
+
+      def run(argv)
+        dest_root = Pathname.new(argv[0] || Dir.pwd).expand_path
+        gem_functions = Pathname.new(Pandorga.gem_path("functions"))
+        gem_studio = Pathname.new(Pandorga.gem_path("studio"))
+
+        unless gem_functions.directory?
+          warn "error: gem has no functions/ directory at #{gem_functions}"
+          return 1
+        end
+
+        copy_tree(gem_functions, dest_root.join("functions"))
+        copy_tree(gem_studio, dest_root.join("studio")) if gem_studio.directory?
+
+        stamp = dest_root.join("functions", STAMP)
+        stamp.write("#{Pandorga::VERSION}\n")
+        puts "pandorga install-functions: copied to #{dest_root} (v#{Pandorga::VERSION})"
+        0
+      end
+
+      private
+
+      def copy_tree(src, dest)
+        FileUtils.rm_rf(dest) if dest.exist?
+        FileUtils.mkdir_p(dest.dirname)
+        FileUtils.cp_r(src, dest)
+      end
+    end
+  end
+end

data/lib/pandorga/commands/new.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require "pathname"
+
+module Pandorga
+  module Commands
+    # Scaffold a new site from examples/minimal.
+    class New
+      EXCLUDE = %w[
+        Gemfile.lock
+        _site
+        vendor
+        .bundle
+        _content_json
+        .jekyll-cache
+      ].freeze
+
+      GEMFILE = <<~RUBY
+        # frozen_string_literal: true
+
+        source "https://rubygems.org"
+
+        gem "pandorga", "~> 1.2"
+        # Local checkout: gem "pandorga", path: "../pandorga"
+        # GitHub tag: gem "pandorga", github: "alexandrelheinen/pandorga", tag: "v1.2.1"
+        gem "csv"
+        gem "base64"
+      RUBY
+
+      def run(argv)
+        force = false
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: pandorga new PATH [--force]"
+          opts.on("--force", "Overwrite an existing directory") { force = true }
+          opts.on("-h", "--help", "Show this help") do
+            puts opts
+            return 0
+          end
+        end
+        parser.parse!(argv)
+
+        raw = argv[0]
+        if raw.nil? || raw.strip.empty?
+          warn "error: PATH is required"
+          warn parser.banner
+          return 1
+        end
+
+        dest = Pathname.new(raw).expand_path
+        src = Pathname.new(Pandorga.gem_path("examples/minimal"))
+        unless src.directory?
+          warn "error: scaffold source missing at #{src}"
+          return 1
+        end
+
+        if dest.exist?
+          nonempty = dest.directory? && dest.children.any?
+          if nonempty && !force
+            warn "error: #{dest} is not empty (pass --force to overwrite)"
+            return 1
+          end
+          if force
+            FileUtils.rm_rf(dest)
+          elsif dest.file?
+            warn "error: #{dest} exists and is a file"
+            return 1
+          end
+        end
+
+        FileUtils.mkdir_p(dest)
+        copy_scaffold(src, dest)
+        dest.join("Gemfile").write(GEMFILE)
+
+        puts "Created site at #{dest}"
+        puts
+        puts "Next steps:"
+        puts "  cd #{shell_path(dest)}"
+        puts "  bundle install"
+        puts "  bundle exec pandorga doctor"
+        puts "  bundle exec pandorga serve"
+        0
+      end
+
+      private
+
+      def copy_scaffold(src, dest)
+        src.each_child do |child|
+          name = child.basename.to_s
+          next if EXCLUDE.include?(name)
+          next if name == "Gemfile" # rewritten after copy
+
+          target = dest.join(name)
+          if child.directory?
+            FileUtils.mkdir_p(target)
+            copy_scaffold(child, target)
+          else
+            FileUtils.cp(child, target)
+          end
+        end
+      end
+
+      def shell_path(pathname)
+        begin
+          pathname.relative_path_from(Pathname.pwd).to_s
+        rescue ArgumentError
+          pathname.to_s
+        end
+      end
+    end
+  end
+end

data/lib/pandorga/commands/publish.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rbconfig"
+require_relative "../object_store_env"
+
+module Pandorga
+  module Commands
+    # Publish content JSON to an S3-compatible object store (R2, MinIO, AWS S3, …).
+    class Publish
+      def run(argv)
+        root = Pathname.new(argv[0] || Dir.pwd).expand_path
+        site_script = root.join("scripts", "content", "publish-content-to-r2.sh")
+        if site_script.file? && site_script.expand_path != gem_publish_script
+          Dir.chdir(root) do
+            exec("bash", site_script.to_s, *argv[1..])
+          end
+        end
+
+        begin
+          ObjectStoreEnv.require!(:endpoint, :bucket, :access_key_id, :secret_access_key)
+        rescue ArgumentError => e
+          warn "error: #{e.message}"
+          warn "hint: set S3_* (or legacy R2_*) variables for any S3-compatible bucket"
+          return 1
+        end
+
+        ObjectStoreEnv.apply_aws_env!
+
+        export_status = Export.new.run(
+          [root.join("content").to_s, root.join("_content_json").to_s]
+        )
+        return export_status if export_status != 0
+
+        script = gem_publish_script
+        unless script.file?
+          warn "error: publish script missing at #{script}"
+          return 1
+        end
+
+        env = ENV.to_h.merge("PANDORGA_SITE_ROOT" => root.to_s)
+        puts "pandorga publish: syncing #{root.join('_content_json')} → object store"
+        system(env, "bash", script.to_s, root.join("_content_json").to_s, chdir: root.to_s) ? 0 : 1
+      end
+
+      private
+
+      def gem_publish_script
+        Pathname.new(Pandorga.gem_path("scripts/content/publish-content-to-object-store.sh"))
+      end
+    end
+  end
+end

data/lib/pandorga/commands/serve.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rbconfig"
+
+module Pandorga
+  module Commands
+    # Local development: export JSON, then jekyll serve with unpublished content.
+    class Serve
+      def run(argv)
+        root = Pathname.new(argv[0] || Dir.pwd).expand_path
+        Dir.chdir(root) do
+          export_status = Export.new.run(%w[content _content_json])
+          return export_status if export_status != 0
+
+          config = %w[_config.yml]
+          config << "_config_dev.yml" if root.join("_config_dev.yml").file?
+          env = ENV.to_h.merge(
+            "CONTENT_API_BASE_URL" => "",
+            "JEKYLL_ENV" => "development",
+            "PANDORGA_SITE_ROOT" => root.to_s
+          )
+          cmd = [
+            "bundle", "exec", "jekyll", "serve",
+            "--unpublished",
+            "--config", config.join(",")
+          ]
+          puts "pandorga serve: #{cmd.join(' ')}"
+          exec(env, *cmd)
+        end
+      end
+    end
+  end
+end

data/lib/pandorga/commands/studio_schema.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+require "fileutils"
+require "date"
+
+module Pandorga
+  module Commands
+    # Compose studio/schema.yml from template studio.yml files + registry.
+    # Refs: PLT-AC-3, docs/spec.md §5.5
+    class StudioSchema
+      DEFAULT_MEDIA = {
+        "name" => "media",
+        "label" => "Media",
+        "input" => "content/media",
+        "output" => "/media",
+        "categories" => %w[image video plot],
+        "rename" => "safe"
+      }.freeze
+
+      DEFAULT_MARKDOWN_BODY = {
+        "type" => "code",
+        "label" => "Body",
+        "description" =>
+          "Markdown source (code editor). Paste Liquid {% include %} markers " \
+          "as-is — figures, citations, embeds.",
+        "options" => { "format" => "markdown" }
+      }.freeze
+
+      def run(argv)
+        root = Pathname.new(argv[0] || Dir.pwd).expand_path
+        templates_root = Pathname.new(Pandorga.gem_path("templates"))
+        config_path = root.join("_config.yml")
+        unless config_path.file?
+          warn "error: no _config.yml in #{root}"
+          return 1
+        end
+
+        config = YAML.safe_load(config_path.read, permitted_classes: [Date]) || {}
+        schema = compose(config, templates_root)
+
+        overrides_path = root.join("studio.overrides.yml")
+        if overrides_path.file?
+          extra = YAML.safe_load(overrides_path.read, permitted_classes: [Date]) || {}
+          apply_overrides!(schema, extra) if extra.is_a?(Hash)
+        end
+
+        out = root.join("studio", "schema.yml")
+        FileUtils.mkdir_p(out.dirname)
+        out.write(YAML.dump(schema))
+        puts "pandorga studio-schema: wrote #{out}"
+        0
+      end
+
+      # Public for gates: build the schema hash without writing.
+      def compose(config, templates_root)
+        pages = config.dig("pandorga", "pages") || []
+        taxonomies = config.dig("pandorga", "taxonomies") || {}
+        groups = {}
+        group_order = []
+        needs_media = false
+        needs_markdown = false
+        collection_index = {}
+
+        pages.each do |page|
+          next unless page.is_a?(Hash)
+
+          template = page["template"].to_s
+          next if template.empty?
+
+          studio_yml = Pathname.new(templates_root).join(template, "studio.yml")
+          next unless studio_yml.file?
+
+          fragment = YAML.safe_load(studio_yml.read, permitted_classes: [Date]) || {}
+          next unless fragment.is_a?(Hash)
+
+          needs_media ||= truthy?(fragment["needs_media"])
+          contributions = expand_fragment(fragment, page, taxonomies)
+          contributions.each do |contrib|
+            group_name = contrib[:group]
+            unless groups.key?(group_name)
+              groups[group_name] = {
+                "name" => group_name,
+                "label" => contrib[:group_label],
+                "type" => "group",
+                "items" => []
+              }
+              group_order << group_name
+            end
+
+            contrib[:items].each do |item|
+              needs_markdown ||= uses_markdown_body?(item)
+              groups[group_name]["items"] << item
+              if item["type"].to_s == "collection"
+                # Deep copy so YAML.dump does not emit aliases shared with content.
+                collection_index[item["name"].to_s] = deep_dup(item)
+              end
+            end
+          end
+        end
+
+        schema = {
+          "version" => 1,
+          "generated_by" => "pandorga studio-schema #{Pandorga::VERSION}",
+          "content" => group_order.map { |name| groups[name] },
+          "collections" => collection_index
+        }
+        schema["media"] = deep_dup(DEFAULT_MEDIA) if needs_media
+        if needs_markdown
+          schema["components"] = { "markdown_body" => deep_dup(DEFAULT_MARKDOWN_BODY) }
+        end
+        schema
+      end
+
+      private
+
+      def expand_fragment(fragment, page, taxonomies)
+        contributions = []
+        default_group = fragment["group"].to_s
+        default_group = page["template"].to_s if default_group.empty?
+        default_label = fragment["group_label"].to_s
+        default_label = default_group.capitalize if default_label.empty?
+
+        items = []
+
+        if fragment["collection"].is_a?(Hash)
+          name = page["collection"].to_s
+          unless name.empty?
+            items << instantiate_collection(
+              fragment["collection"],
+              name,
+              page,
+              taxonomies
+            )
+          end
+        end
+
+        if fragment["collections"].is_a?(Hash)
+          slots = page["collections"].is_a?(Hash) ? page["collections"] : {}
+          fragment["collections"].each do |slot, spec|
+            next unless spec.is_a?(Hash)
+
+            name = slots[slot].to_s
+            name = slot.to_s if name.empty?
+            next if name.empty? || name == "data" || name == "profile"
+
+            items << instantiate_collection(spec, name, page, taxonomies)
+          end
+        end
+
+        Array(fragment["files"]).each do |file_spec|
+          next unless file_spec.is_a?(Hash)
+
+          items << deep_dup(file_spec)
+        end
+
+        unless items.empty?
+          contributions << {
+            group: default_group,
+            group_label: default_label,
+            items: items
+          }
+        end
+
+        profile = fragment["profile"]
+        if profile.is_a?(Hash)
+          profile_items = Array(profile["files"]).select { |f| f.is_a?(Hash) }.map { |f| deep_dup(f) }
+          unless profile_items.empty?
+            contributions << {
+              group: profile["group"].to_s.empty? ? "profile" : profile["group"].to_s,
+              group_label: profile["group_label"].to_s.empty? ? "Profile" : profile["group_label"].to_s,
+              items: profile_items
+            }
+          end
+        end
+
+        contributions
+      end
+
+      def instantiate_collection(spec, name, page, taxonomies)
+        entry = deep_dup(spec)
+        entry["name"] = name
+        entry["type"] ||= "collection"
+        if page["collection"].to_s == name && !page["title"].to_s.empty?
+          entry["label"] = page["title"].to_s
+        elsif entry["label"].to_s.empty?
+          entry["label"] = name.capitalize
+        end
+        entry["path"] ||= "content/collections/#{name}"
+        entry["path"] = entry["path"].to_s.gsub("{collection}", name)
+        apply_taxonomy!(entry, name, taxonomies)
+        entry
+      end
+
+      def apply_taxonomy!(entry, collection_name, taxonomies)
+        tax = taxonomies[collection_name]
+        return unless tax.is_a?(Hash)
+
+        Array(entry["fields"]).each do |field|
+          next unless field.is_a?(Hash)
+          next unless field["name"].to_s == "tags"
+
+          field["options"] ||= {}
+          next unless field["options"].is_a?(Hash)
+
+          tags = tax["tags"]
+          field["options"]["values"] = tags if tags.is_a?(Array) && !tags.empty?
+          max = tax["max"]
+          field["options"]["max"] = max if max
+        end
+      end
+
+      def apply_overrides!(schema, extra)
+        if extra["media"].is_a?(Hash)
+          schema["media"] = deep_merge(schema["media"] || {}, extra["media"])
+        end
+
+        if extra["components"].is_a?(Hash)
+          schema["components"] = deep_merge(schema["components"] || {}, extra["components"])
+        end
+
+        if extra["collections"].is_a?(Hash)
+          extra["collections"].each do |name, patch|
+            next unless patch.is_a?(Hash)
+
+            item = find_content_item(schema, name.to_s)
+            if item
+              merged = deep_merge(item, patch)
+              item.replace(merged)
+            end
+            if schema["collections"].is_a?(Hash) && schema["collections"][name.to_s]
+              schema["collections"][name.to_s] =
+                deep_merge(schema["collections"][name.to_s], patch)
+            end
+          end
+        end
+
+        return unless extra["content"].is_a?(Array)
+
+        schema["content"] ||= []
+        extra["content"].each do |group|
+          next unless group.is_a?(Hash)
+
+          existing = schema["content"].find { |g| g["name"].to_s == group["name"].to_s }
+          if existing
+            existing.replace(deep_merge(existing, group))
+          else
+            schema["content"] << deep_dup(group)
+          end
+        end
+      end
+
+      def find_content_item(schema, name)
+        Array(schema["content"]).each do |group|
+          next unless group.is_a?(Hash)
+
+          Array(group["items"]).each do |item|
+            return item if item.is_a?(Hash) && item["name"].to_s == name
+          end
+        end
+        nil
+      end
+
+      def uses_markdown_body?(node)
+        case node
+        when Hash
+          return true if node["component"].to_s == "markdown_body"
+
+          node.any? { |_, v| uses_markdown_body?(v) }
+        when Array
+          node.any? { |v| uses_markdown_body?(v) }
+        else
+          false
+        end
+      end
+
+      def truthy?(value)
+        value == true || value.to_s == "true"
+      end
+
+      def deep_dup(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_dup(v) }
+        when Array
+          obj.map { |v| deep_dup(v) }
+        else
+          obj
+        end
+      end
+
+      def deep_merge(left, right)
+        return deep_dup(right) unless left.is_a?(Hash) && right.is_a?(Hash)
+
+        result = deep_dup(left)
+        right.each do |key, value|
+          result[key] =
+            if result.key?(key) && result[key].is_a?(Hash) && value.is_a?(Hash)
+              deep_merge(result[key], value)
+            else
+              deep_dup(value)
+            end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/pandorga/jekyll/generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require_relative "../registry"
+
+module Pandorga
+  module Jekyll
+    # Generates listing pages and nav data from pandorga.pages (PLT-AC-3).
+    class Generator < ::Jekyll::Generator
+      safe true
+      priority :high
+
+      # Template defaults when registry omits `detail` (English platform paths).
+      DEFAULT_DETAILS = {
+        "articles" => "/articles/:slug/",
+        "blog" => "/posts/:slug/",
+        "portfolio" => "/projects/:slug/"
+      }.freeze
+
+      def generate(site)
+        pages = PandorgaRegistry.pages(site.config)
+        return if pages.empty?
+
+        begin
+          PandorgaRegistry.validate!(pages)
+        rescue ArgumentError => e
+          raise ::Jekyll::Errors::FatalException, e.message
+        end
+
+        # Website shell reads site.data.nav (label/pages/key shape).
+        site.data["nav"] = PandorgaRegistry.build_nav(pages)
+        site.data["pandorga_pages"] = pages
+        site.data["pandorga_nav"] = site.data["nav"]
+        site.data["pandorga_home_bands"] = PandorgaRegistry.home_bands(pages)
+
+        existing_keys = site.pages.map { |p| p.data["key"] }.compact
+        pages.each do |entry|
+          next unless entry.is_a?(Hash)
+          next if existing_keys.include?(entry["key"])
+
+          emit_page(site, entry)
+        end
+      end
+
+      private
+
+      def emit_page(site, entry)
+        path = entry["path"].to_s
+        return if path.empty?
+
+        listing_path = path.end_with?("/") ? path : "#{path}/"
+        rel_dir = path.sub(%r{\A/}, "").sub(%r{/\z}, "")
+        page = ::Jekyll::PageWithoutAFile.new(site, site.source, rel_dir, "index.html")
+        page.data["layout"] = PandorgaRegistry.layout_for(entry)
+        page.data["key"] = entry["key"]
+        page.data["template"] = entry["template"] if entry["template"]
+        page.data["title"] = entry["title"] if entry["title"]
+        page.data["description"] = entry["description"] if entry["description"]
+        page.data["accent"] = entry["accent"] if entry["accent"]
+        page.data["badge"] = entry["badge"] if entry["badge"]
+        page.data["lang"] = entry["language"] if entry["language"]
+        page.data["permalink"] = listing_path
+        # listing_path is explicit: Jekyll reserves page.path for the source file.
+        page.data["listing_path"] = listing_path
+        page.data["collection"] = entry["collection"] if entry["collection"]
+        detail = entry["detail"].to_s
+        detail = DEFAULT_DETAILS[entry["template"].to_s].to_s if detail.empty?
+        page.data["detail"] = detail unless detail.empty?
+        page.content = ""
+        site.pages << page
+      end
+    end
+  end
+end