poetry-core 0.0.2

data/lib/poetry/core/registry_client.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Poetry
+  module Core
+    # Fetches and validates registry items for the add generator.
+    # Security posture - the registry ecosystem's standard defenses plus
+    # poetry's tightenings: https only (plain http allowed for localhost work), a
+    # response size cap, a redirect limit, env-only auth (${VAR}
+    # placeholders expanded from ENV at fetch time, so secrets never live in
+    # config files), schema validation before anything downstream touches an
+    # item, and NEVER any script execution. Namespaces resolve from the
+    # registries: section of config/poetry_components.yml first, then from
+    # the public registries.json directory when one is configured.
+    #
+    # @api private
+    class RegistryClient
+      class Error < Poetry::Core::Error; end
+
+      MAX_BYTES = 1_048_576
+      MAX_REDIRECTS = 3
+      LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+      NAME_FORMAT = /\A[a-z0-9][a-z0-9._-]*\z/
+
+      # @param registries [Hash] "@ns" => a url template String containing
+      #   "{name}", or {"url" => template, "headers" => {header => value}}
+      # @param directory [String, nil] a registries.json URL for resolving
+      #   namespaces that are not configured locally
+      # @param base_dir [String] :file addresses resolve relative to this
+      # @param fetcher [#call, nil] injectable transport (url, headers) ->
+      #   body String; defaults to the hardened Net::HTTP transport
+      def initialize(registries: {}, directory: nil, base_dir: Dir.pwd, fetcher: nil)
+        @registries = registries || {}
+        @directory = directory
+        @base_dir = base_dir
+        @fetcher = fetcher || method(:default_fetch)
+      end
+
+      # Resolve a remote address (:url / :file / :namespace) to a validated
+      # item hash.
+      def resolve(address)
+        payload =
+          case address.kind
+          when :url then fetch_json(address.location)
+          when :file then read_json(address.location)
+          when :namespace then fetch_json(*namespace_request(address))
+          else raise Error, "#{address.raw.inspect} is not a remote address"
+          end
+        validate_item!(payload, source: address.raw)
+      end
+
+      private
+
+      def namespace_request(address)
+        entry = @registries[address.namespace] || directory_entry(address.namespace)
+        unless entry
+          raise Error, "unknown registry namespace #{address.namespace} - add it to the " \
+                       "registries: section of config/poetry_components.yml " \
+                       "(or configure directory: with a registries.json URL)"
+        end
+
+        template, headers = normalize_registry_entry(address.namespace, entry)
+        [template.sub("{name}", address.name), expand_env(headers)]
+      end
+
+      def normalize_registry_entry(namespace, entry)
+        template, headers =
+          case entry
+          when String then [entry, {}]
+          when Hash then [entry["url"], entry["headers"] || {}]
+          end
+        unless template.is_a?(String) && template.include?("{name}")
+          raise Error, "registry #{namespace} needs a url template containing {name}, got #{entry.inspect}"
+        end
+
+        [template, headers]
+      end
+
+      # The public directory (registries.json): {"registries" => {"@ns" =>
+      # template-or-hash}} - fetched once, memoized for the run.
+      def directory_entry(namespace)
+        return nil unless @directory
+
+        @directory_registries ||= fetch_json(@directory).fetch("registries") do
+          raise Error, "#{@directory} is not a registries.json directory (no registries key)"
+        end
+        @directory_registries[namespace]
+      end
+
+      # Secrets are env-only: config carries ${VAR} placeholders, never
+      # values. A missing variable fails loudly before any request is made.
+      def expand_env(headers)
+        headers.to_h do |key, value|
+          expanded = value.to_s.gsub(/\$\{([A-Z0-9_]+)\}/) do
+            ENV.fetch(Regexp.last_match(1)) do
+              raise Error, "header #{key} references ${#{Regexp.last_match(1)}} but it is not set in ENV"
+            end
+          end
+          [key, expanded]
+        end
+      end
+
+      def fetch_json(url, headers = {})
+        validate_scheme!(url)
+        parse_json(@fetcher.call(url, headers), source: url)
+      end
+
+      def read_json(location)
+        path = File.expand_path(location, @base_dir)
+        raise Error, "no registry item file at #{path}" unless File.file?(path)
+        raise Error, "#{path} exceeds the #{MAX_BYTES}-byte item cap" if File.size(path) > MAX_BYTES
+
+        parse_json(File.read(path), source: location)
+      end
+
+      def parse_json(body, source:)
+        raise Error, "#{source} exceeds the #{MAX_BYTES}-byte item cap" if body.bytesize > MAX_BYTES
+
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise Error, "#{source} is not valid JSON: #{e.message}"
+      end
+
+      def validate_scheme!(url)
+        uri = URI.parse(url)
+        return if uri.scheme == "https"
+        return if uri.scheme == "http" && LOCAL_HOSTS.include?(uri.host)
+
+        raise Error, "refusing #{url.inspect}: registries must be https (plain http is allowed for localhost only)"
+      end
+
+      def default_fetch(url, headers, hops = 0)
+        response = perform_get(URI.parse(url), headers)
+        case response
+        when Net::HTTPRedirection then follow_redirect(url, headers, response, hops)
+        when Net::HTTPSuccess
+          body = response.body.to_s
+          raise Error, "#{url} exceeds the #{MAX_BYTES}-byte item cap" if body.bytesize > MAX_BYTES
+
+          body
+        else
+          raise Error, "#{url} responded #{response.code}"
+        end
+      rescue SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, SocketError => e
+        raise Error, "could not fetch #{url}: #{e.message}"
+      end
+
+      def perform_get(uri, headers)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            open_timeout: 5, read_timeout: 10) do |http|
+          request = Net::HTTP::Get.new(uri)
+          headers.each { |key, value| request[key] = value }
+          http.request(request)
+        end
+      end
+
+      def follow_redirect(url, headers, response, hops)
+        raise Error, "too many redirects fetching #{url}" if hops >= MAX_REDIRECTS
+
+        target = URI.join(url, response["location"].to_s).to_s
+        validate_scheme!(target)
+        default_fetch(target, headers, hops + 1)
+      end
+
+      def validate_item!(payload, source:)
+        raise Error, "#{source} is not a registry item (expected a JSON object)" unless payload.is_a?(Hash)
+
+        validate_identity!(payload, source: source)
+        validate_files!(payload, source: source)
+        validate_extras!(payload, source: source)
+        payload
+      end
+
+      def validate_identity!(payload, source:)
+        name = payload["name"]
+        unless name.is_a?(String) && name.match?(NAME_FORMAT)
+          raise Error,
+                "#{source}: item name #{name.inspect} is invalid"
+        end
+
+        type = payload["type"]
+        return if type.is_a?(String) && type.start_with?("registry:")
+
+        raise Error, "#{source}: item type #{type.inspect} is invalid (expected registry:*)"
+      end
+
+      def validate_files!(payload, source:)
+        files = payload.fetch("files", [])
+        raise Error, "#{source}: files must be an array" unless files.is_a?(Array)
+
+        files.each do |file|
+          valid = file.is_a?(Hash) &&
+                  file["path"].is_a?(String) && !file["path"].empty? &&
+                  file["content"].is_a?(String) &&
+                  (file["target"].nil? || file["target"].is_a?(String))
+          raise Error, "#{source}: malformed files entry #{file.inspect[0, 120]}" unless valid
+        end
+      end
+
+      def validate_extras!(payload, source:)
+        %w[registryDependencies dependencies].each do |key|
+          value = payload[key]
+          next if value.nil? || (value.is_a?(Array) && value.all?(String))
+
+          raise Error, "#{source}: #{key} must be an array of strings"
+        end
+        raise Error, "#{source}: css must be a string" unless payload["css"].nil? || payload["css"].is_a?(String)
+        return if payload["cssVars"].nil? || payload["cssVars"].is_a?(Hash)
+
+        raise Error, "#{source}: cssVars must be an object"
+      end
+    end
+  end
+end

data/lib/poetry/core/registry_installer.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Poetry
+  module Core
+    # Turns remote registry addresses into a deterministic install PLAN:
+    # resolve the dependency tree (visited-set walk,
+    # then Kahn topo-sort so dependencies write before dependents), classify
+    # every dependency (poetry gem components satisfy at RUNTIME - no copy;
+    # gem blocks copy in through their own generator; everything else
+    # fetches recursively via the sibling convention), validate every write
+    # target against a traversal-safe allowlist, and collect the report-only
+    # side effects (Gemfile additions are PRINTED, never executed - no
+    # lifecycle scripts, ever: a fetched item can never run code on install).
+    # The add generator executes the plan with its idempotent primitives;
+    # this class never touches the filesystem it plans for.
+    #
+    # @api private
+    class RegistryInstaller
+      class Error < Poetry::Core::Error; end
+
+      ALLOWED_TARGET_ROOTS = %w[app/components app/views app/javascript app/helpers app/assets].freeze
+      COMMUNITY_CSS_DIR = "app/assets/tailwind/poetry/community"
+
+      Plan = Struct.new(:writes, :css_writes, :entry_lines, :gem_satisfied, :block_installs,
+                        :gem_deps, :docs, :manifest, keyword_init: true)
+      Write = Struct.new(:target, :content, :item, keyword_init: true)
+
+      # @param client [RegistryClient] resolves remote addresses to items
+      # @param local_components [Enumerable<String>] kebab names the
+      #   installed poetry gems provide at runtime (no copy needed)
+      # @param local_blocks [Enumerable<String>] kebab names of the gem's
+      #   copy-in blocks (installed via their own generator)
+      # @param destination_root [String] the host app root targets must stay
+      #   inside
+      # @param loaded_gems [Enumerable<String>] present gems, for the
+      #   report-only dependency check
+      def initialize(client:, destination_root:, local_components: [], local_blocks: [],
+                     loaded_gems: Gem.loaded_specs.keys)
+        @client = client
+        @local_components = local_components.to_set { |name| name.tr("_", "-") }
+        @local_blocks = local_blocks.to_set { |name| name.tr("_", "-") }
+        @destination_root = destination_root
+        @loaded_gems = loaded_gems.to_set
+      end
+
+      # @param addresses [Array<RegistryAddress>] remote addresses only
+      # @return [Plan]
+      def plan(addresses)
+        state = { items: {}, edges: Hash.new { |hash, key| hash[key] = [] },
+                  resolved: {}, sources: {}, gem_satisfied: [], block_installs: [] }
+        addresses.each { |address| resolve_into(state, address) }
+        build_plan(state)
+      end
+
+      private
+
+      def resolve_into(state, address)
+        return state[:resolved][address.raw] if state[:resolved].key?(address.raw)
+
+        item = @client.resolve(address)
+        name = item["name"]
+        state[:resolved][address.raw] = name
+        register_item(state, name, item, address)
+        (item["registryDependencies"] || []).each do |dep|
+          dep_name = resolve_dependency(state, address, dep)
+          state[:edges][name] << dep_name if dep_name
+        end
+        name
+      end
+
+      # Two addresses may legitimately land on the same item (diamond deps);
+      # the same NAME with different content is a collision, not a merge.
+      def register_item(state, name, item, address)
+        if (existing = state[:items][name])
+          return if item_digest(existing) == item_digest(item)
+
+          raise Error, "#{address.raw} and #{state[:sources][name]} both provide #{name.inspect} " \
+                       "with different content - refusing to pick one"
+        end
+        state[:items][name] = item
+        state[:sources][name] = address.raw
+      end
+
+      def item_digest(item)
+        Digest::SHA256.hexdigest(JSON.generate(item))
+      end
+
+      # @return [String, nil] the remote item name this dependency resolves
+      #   to, or nil when the installed gems satisfy it (recorded on state).
+      def resolve_dependency(state, parent, dep)
+        dep_address = RegistryAddress.parse(dep)
+        return resolve_into(state, dep_address) unless local_candidate?(dep_address)
+
+        kebab = dep_address.name
+        if @local_components.include?(kebab)
+          state[:gem_satisfied] |= [kebab]
+          nil
+        elsif @local_blocks.include?(kebab)
+          state[:block_installs] |= [kebab]
+          nil
+        elsif dep_address.kind == :bare
+          resolve_into(state, parent.sibling(kebab))
+        else
+          raise Error, "#{dep} is not provided by the installed poetry gems"
+        end
+      end
+
+      # Bare names and @poetry/* check the installed gems first - poetry's
+      # twist on the dependency walk: core components are runtime-provided, so a
+      # community item that composes Button needs no Button copy.
+      def local_candidate?(address)
+        address.kind == :bare || (address.kind == :namespace && address.namespace == "@poetry")
+      end
+
+      def build_plan(state)
+        order = topo_order(state)
+        items = order.map { |name| state[:items][name] }
+        Plan.new(
+          writes: collect_writes(state, order),
+          css_writes: items.filter_map { |item| css_write(item) },
+          entry_lines: items.filter_map { |item| entry_line(item) },
+          gem_satisfied: state[:gem_satisfied].sort,
+          block_installs: state[:block_installs].sort,
+          gem_deps: missing_gem_deps(items),
+          docs: items.filter_map { |item| item["docs"] },
+          manifest: order.to_h { |name| [name, { "source" => state[:sources][name] }] }
+        )
+      end
+
+      # Kahn: an item writes only after every remote item it depends on has
+      # written. Deterministic (sorted ready set); leftovers = a cycle.
+      def topo_order(state)
+        remaining = state[:items].keys.sort
+        deps = remaining.to_h { |name| [name, state[:edges][name] & remaining] }
+        order = []
+        until remaining.empty?
+          ready = remaining.select { |name| (deps[name] - order).empty? }.sort
+          raise Error, "registry dependency cycle among: #{remaining.join(", ")}" if ready.empty?
+
+          order.concat(ready)
+          remaining -= ready
+        end
+        order
+      end
+
+      def collect_writes(state, order)
+        seen = {}
+        order.flat_map do |name|
+          state[:items][name].fetch("files", []).filter_map do |file|
+            target = file["target"] || file["path"]
+            validate_target!(target, item: name)
+            deduplicate_write(seen, target, file["content"], name)
+          end
+        end
+      end
+
+      def deduplicate_write(seen, target, content, name)
+        digest = Digest::SHA256.hexdigest(content)
+        if (previous = seen[target])
+          return nil if previous[:digest] == digest
+
+          raise Error, "#{name} and #{previous[:name]} both write #{target} with different content"
+        end
+        seen[target] = { digest: digest, name: name }
+        Write.new(target: target, content: content, item: name)
+      end
+
+      # Traversal defense: relative, inside the allowlisted app roots, and -
+      # belt and braces - expanding inside destination_root.
+      def validate_target!(target, item:)
+        offense =
+          if target.start_with?("/", "~") || target.match?(/\A[A-Za-z]:/) then "an absolute path"
+          elsif target.include?("..") then "path traversal"
+          elsif target.include?("\0") || target.include?("\\") then "an illegal character"
+          elsif ALLOWED_TARGET_ROOTS.none? { |root| target.start_with?("#{root}/") }
+            "outside the allowed roots (#{ALLOWED_TARGET_ROOTS.join(", ")})"
+          end
+        raise Error, "#{item}: refusing target #{target.inspect} - #{offense}" if offense
+
+        expanded = File.expand_path(target, @destination_root)
+        return if expanded.start_with?(File.expand_path(@destination_root) + File::SEPARATOR)
+
+        raise Error, "#{item}: refusing target #{target.inspect} - escapes the app root"
+      end
+
+      def css_write(item)
+        content = css_content(item)
+        return nil unless content
+
+        { path: "#{COMMUNITY_CSS_DIR}/#{item["name"]}.css", content: content }
+      end
+
+      def entry_line(item)
+        return nil unless css_content(item)
+
+        %(@import "./poetry/community/#{item["name"]}.css";)
+      end
+
+      # cssVars carry the item schema's three sections (theme/light/dark); css
+      # passes through verbatim. One file per item, imported from the host's
+      # Tailwind entry like every other poetry fragment.
+      def css_content(item)
+        vars = item["cssVars"] || {}
+        sections = [
+          css_block("@theme", vars["theme"]),
+          css_block(":root", vars["light"]),
+          css_block(".dark", vars["dark"]),
+          item["css"].is_a?(String) && !item["css"].empty? ? item["css"] : nil
+        ].compact
+        return nil if sections.empty?
+
+        "/* #{item["name"]} - installed by bin/rails g poetry:add */\n#{sections.join("\n\n")}\n"
+      end
+
+      def css_block(selector, vars)
+        return nil unless vars.is_a?(Hash) && vars.any?
+
+        lines = vars.map { |key, value| "  --#{key.to_s.delete_prefix("--")}: #{value};" }
+        "#{selector} {\n#{lines.join("\n")}\n}"
+      end
+
+      # Report-only, never executed: which declared gem dependencies the
+      # bundle is missing. "name" or "name@constraint" forms accepted.
+      def missing_gem_deps(items)
+        items.flat_map { |item| item["dependencies"] || [] }.uniq.reject do |dep|
+          @loaded_gems.include?(dep.split("@").first)
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/registry_items.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Poetry
+  module Core
+    # The interop projection of a gem's registry:
+    # every component and block as a registry-item hash matching the
+    # published registry-item.json schema ({ITEM_SCHEMA}) - name / type /
+    # title / files[]
+    # ({path, content, type, target}) / registryDependencies / meta - plus
+    # index summaries for registry.json. Built BOOT-FREE from the committed
+    # component_registry.yml + the source tree, so the docs site serves
+    # GET /r/:name.json live and any tool speaking that schema can consume a
+    # poetry item. Names are kebab-case with the gem prefix stripped
+    # (poetry/ui/command/dialog -> command-dialog), matching the block
+    # catalog's existing naming.
+    #
+    # @api private
+    class RegistryItems
+      # The published registry-item JSON schema every emitted item validates
+      # against.
+      ITEM_SCHEMA = "https://ui.shadcn.com/schema/registry-item.json"
+
+      # The same header strip the block generator applies: the poetry:block
+      # comment is registry metadata, not file content.
+      BLOCK_HEADER = /\A<%#\s*poetry:block[^%]*%>\n?/
+
+      # @param registry [Hash] a parsed component_registry.yml payload
+      # @param root [Pathname, String] the gem root files resolve against
+      # @param gem_name [String] recorded in every item's meta
+      # @param gem_version [String] recorded in every item's meta
+      # @param dependencies [Hash] curated composition edges (underscore
+      #   component name => [underscore names]) - the add generator's map,
+      #   single-sourced by the owning gem
+      def initialize(registry:, root:, gem_name:, gem_version:, dependencies: {})
+        @registry = registry
+        @root = Pathname.new(root)
+        @gem_name = gem_name
+        @gem_version = gem_version
+        @dependencies = dependencies
+      end
+
+      # Every item name (components + blocks), collision-checked: one flat
+      # kebab namespace per gem, the registry-schema convention.
+      def names
+        @names ||= begin
+          all = component_paths.keys + blocks.keys
+          duplicates = all.tally.select { |_name, count| count > 1 }.keys
+          raise Error, "registry item name collision: #{duplicates.join(", ")}" if duplicates.any?
+
+          all.sort
+        end
+      end
+
+      def item(name)
+        if (path = component_paths[name])
+          component_item(name, path)
+        elsif (entry = blocks[name])
+          block_item(name, entry)
+        end
+      end
+
+      # Index entries: the full item minus file content (the
+      # registry.json index shape - paths and targets stay, bytes don't).
+      def summaries
+        names.map do |name|
+          full = item(name)
+          full.merge("files" => full["files"].map { |file| file.except("content") })
+        end
+      end
+
+      private
+
+      def components
+        @registry["components"] || {}
+      end
+
+      def blocks
+        @registry["blocks"] || {}
+      end
+
+      def component_paths
+        @component_paths ||= components.keys.to_h do |path|
+          [path.delete_prefix(path_prefix).tr("/", "_").tr("_", "-"), path]
+        end
+      end
+
+      # The gem prefix to strip is the component paths' common DIRECTORY
+      # prefix (poetry/ui/button + poetry/ui/command/dialog -> poetry/ui/):
+      # derived, so every gem's items flatten the same way with nothing to
+      # configure.
+      def path_prefix
+        @path_prefix ||= begin
+          dirs = components.keys.map { |path| path.split("/")[0..-2] }
+          common = dirs.reduce { |left, right| left.zip(right).take_while { |a, b| a == b }.map(&:first) }
+          common.nil? || common.empty? ? "" : "#{common.join("/")}/"
+        end
+      end
+
+      def component_item(name, path)
+        entry = components.fetch(path)
+        {
+          "$schema" => ITEM_SCHEMA,
+          "name" => name,
+          "type" => "registry:component",
+          "title" => name.tr("-", " ").capitalize,
+          "files" => component_files(path),
+          "registryDependencies" => (@dependencies[name.tr("-", "_")] || []).map { |dep| dep.tr("_", "-") },
+          "meta" => component_meta(entry)
+        }
+      end
+
+      # The part contract rides meta so /r consumers see the
+      # DOM-verified styling surface without fetching the source.
+      def component_meta(entry)
+        meta = { "gem" => @gem_name, "gem_version" => @gem_version, "provided" => "runtime-gem",
+                 "class_name" => entry["class_name"], "identifier" => entry["identifier"] }
+        meta["parts"] = entry["parts"] if entry["parts"]
+        meta
+      end
+
+      # The component's whole source dir (component.rb, style.rb, template,
+      # preview) - the same set the copy-in generator installs, target
+      # mirroring path. Files belonging to a NESTED registered component
+      # stay with their own item, in both nesting shapes: a subdirectory,
+      # or the sibling-file convention (command/dialog keeps
+      # dialog_component.rb beside its parent).
+      def component_files(path)
+        dir = @root.join("app/components", path)
+        return sibling_files(path) unless dir.directory?
+
+        dir.glob("**/*").select(&:file?).sort.filter_map do |file|
+          rel = "app/components/#{path}/#{file.relative_path_from(dir)}"
+          next if nested_dir_prefixes(path).any? { |prefix| rel.start_with?("app/components/#{prefix}") }
+          next if nested_leaves(path).any? { |leaf| file.basename.to_s.start_with?("#{leaf}_") }
+
+          { "path" => rel, "content" => file.read, "type" => "registry:file", "target" => rel }
+        end
+      end
+
+      def nested_dir_prefixes(path)
+        components.keys.filter_map { |other| "#{other}/" if other.start_with?("#{path}/") }
+      end
+
+      def nested_leaves(path)
+        components.keys.filter_map do |other|
+          next unless other.start_with?("#{path}/")
+
+          File.basename(other) unless @root.join("app/components", other).directory?
+        end
+      end
+
+      # A nested component with no directory of its own keeps its files
+      # beside its parent, prefixed with its leaf name (dialog_component.rb,
+      # dialog_component.html.erb, dialog_preview.rb).
+      def sibling_files(path)
+        parent = File.dirname(path)
+        leaf = File.basename(path)
+        @root.join("app/components", parent).glob("#{leaf}_*").select(&:file?).sort.map do |file|
+          rel = "app/components/#{parent}/#{file.basename}"
+          { "path" => rel, "content" => file.read, "type" => "registry:file", "target" => rel }
+        end
+      end
+
+      def block_item(name, entry)
+        source = @root.join(entry.fetch("template")).read
+        target = "app/views/blocks/_#{name.tr("-", "_")}.html.erb"
+        {
+          "$schema" => ITEM_SCHEMA,
+          "name" => name,
+          "type" => "registry:block",
+          "title" => entry["title"],
+          "description" => entry["description"],
+          "files" => [{ "path" => entry.fetch("template"), "content" => source.sub(BLOCK_HEADER, ""),
+                        "type" => "registry:file", "target" => target }],
+          "registryDependencies" => (entry["components"] || []).map { |dep| dep.tr("_", "-") },
+          "meta" => { "gem" => @gem_name, "gem_version" => @gem_version, "provided" => "copy-in",
+                      "keywords" => entry["keywords"] }.compact
+        }
+      end
+    end
+  end
+end