poetry-core 0.0.2

data/lib/poetry/core/recipe_items.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The recipes projection: multi-file, non-UI payloads
+    # - skill bundles, scaffold template sets, screen slices - served
+    # through the same registry-item schema as components and
+    # blocks. Like RegistryItems, this is a LIVE projection: a recipe
+    # declares its files as callables over gem-shipped sources, so the
+    # served item can never drift from what the generators install.
+    #
+    # @api private
+    class RecipeItems
+      # The published registry-item JSON schema recipes are served under -
+      # the same schema component items validate against.
+      ITEM_SCHEMA = RegistryItems::ITEM_SCHEMA
+
+      # @param recipes [Array<Hash>] declarations: "name" (flat kebab),
+      #   "title", "description", optional "registry_dependencies"
+      #   (kebab item names), and "files" - a callable (or array)
+      #   yielding { "path" =>, "target" =>, "content" => } hashes.
+      #   Targets must be relative and traversal-free; enforced here so a
+      #   bad declaration fails in the gem's suite, not in a host.
+      # @param gem_name [String] recorded in every item's meta
+      # @param gem_version [String] recorded in every item's meta
+      def initialize(recipes:, gem_name:, gem_version:)
+        @list = recipes
+        @gem_name = gem_name
+        @gem_version = gem_version
+      end
+
+      def names
+        @names ||= begin
+          all = @list.map { |recipe| recipe.fetch("name") }
+          duplicates = all.tally.select { |_name, count| count > 1 }.keys
+          raise Error, "recipe name collision: #{duplicates.join(", ")}" if duplicates.any?
+
+          all.sort
+        end
+      end
+
+      def item(name)
+        recipe = @list.find { |candidate| candidate.fetch("name") == name }
+        return nil unless recipe
+
+        {
+          "$schema" => ITEM_SCHEMA,
+          "name" => name,
+          "type" => "registry:block",
+          "title" => recipe.fetch("title"),
+          "description" => recipe.fetch("description"),
+          "files" => recipe_files(recipe),
+          "registryDependencies" => recipe["registry_dependencies"] || [],
+          "meta" => { "gem" => @gem_name, "gem_version" => @gem_version,
+                      "provided" => "copy-in", "kind" => "recipe" }
+        }
+      end
+
+      def summaries
+        names.map do |name|
+          full = item(name)
+          full.merge("files" => full["files"].map { |file| file.except("content") })
+        end
+      end
+
+      private
+
+      def recipe_files(recipe)
+        source = recipe.fetch("files")
+        (source.respond_to?(:call) ? source.call : source).map do |file|
+          target = file.fetch("target")
+          unless Pathname.new(target).relative? && target.split("/").none?("..")
+            raise Error, "recipe #{recipe.fetch("name")} has an unsafe target: #{target}"
+          end
+
+          { "path" => file.fetch("path"), "content" => file.fetch("content"),
+            "type" => "registry:file", "target" => target }
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/registry.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Poetry
+  module Core
+    # The generated component registry: the machine-readable index of
+    # every component's public surface, built entirely FROM SOURCE - the
+    # prop_definitions introspection shim + the Style dictionaries -
+    # and CI-verified against a fresh build (a committed registry that
+    # can never drift from the code).
+    #
+    # Consumers: the docs site, the MCP server, the agent skill, and
+    # the A2UI / WebMCP projections - one contract, every surface.
+    #
+    # @example Generate the registry for a gem root
+    #   Poetry::Core::Registry.new(source_root: gem_root).generate!
+    class Registry
+      # The banner written at the top of the generated YAML.
+      HEADER = <<~HEADER
+        # poetry component registry - generated by `bin/rake registry:generate` FROM SOURCE.
+        # DO NOT EDIT: CI verifies this file matches a fresh build (rake registry:verify).
+      HEADER
+
+      # Where the committed registry lives, relative to a gem root.
+      RELATIVE_PATH = "config/component_registry.yml"
+
+      # Stimulus lifecycle callbacks are not consumer-callable actions.
+      LIFECYCLE_METHODS = %w[connect disconnect initialize].freeze
+
+      # The id-minting funnel, as source text: a component family whose
+      # sources never match renders no poetry-minted random id (the
+      # "identity" derivation - see the entry's identity key).
+      MINT_PATTERN = /\bpoetry_instance_id\b|\binstance_id\b|\bSecureRandom\b/
+
+      # The committed-registry view: the four generated sections
+      # plus the root they resolve against, read straight from the YAML a
+      # `registry:generate` run committed - no component classes, no Rails.
+      # It satisfies every LlmsText/SkillText read (entries / blocks /
+      # source_root), so boot-free consumers (the MCP server, runtime skill
+      # delivery) share one loader instead of each parsing the payload.
+      class Committed
+        attr_reader :entries, :blocks, :helpers, :helper_args, :form_builder, :source_root
+
+        # Holds the sections of one committed registry file;
+        # {Registry.committed} is the loader.
+        #
+        # @param entries [Array<Hash>] the "components" section
+        # @param blocks [Array<Hash>, nil] the "blocks" section
+        # @param helpers [Hash, nil] the "helpers" section
+        # @param helper_args [Hash, nil] the "helper_args" section
+        # @param source_root [Pathname] the gem root the paths resolve against
+        # @param form_builder [Hash, nil] the "form_builder" section
+        def initialize(entries:, blocks:, helpers:, helper_args:, source_root:, form_builder: nil)
+          @form_builder = form_builder
+          @entries = entries
+          @blocks = blocks
+          @helpers = helpers
+          @helper_args = helper_args
+          @source_root = source_root
+        end
+      end
+
+      # Loads the committed registry YAML boot-free.
+      #
+      # @param root [String, Pathname] the gem root holding the registry file
+      # @return [Committed]
+      def self.committed(root)
+        source_root = Pathname.new(root)
+        payload = YAML.load_file(source_root.join(RELATIVE_PATH), aliases: true)
+        Committed.new(entries: payload.fetch("components"), blocks: payload["blocks"],
+                      helpers: payload["helpers"], helper_args: payload["helper_args"],
+                      form_builder: payload["form_builder"], source_root: source_root)
+      end
+
+      # @param components [Enumerable<Class>, nil] component classes; defaults
+      #   to every named Poetry::Core::Component descendant (eager-loaded)
+      #   whose source lives under source_root.
+      # @param source_root [Pathname, String] the gem root to discover in and
+      #   write the registry to - poetry-ui passes its own root.
+      # @param helpers [Hash, nil] wrapper helpers that are NOT components
+      #   (poetry_input_group_addon et al): helper name => contract hash
+      #   ({"options" => [...]}, or {} for a plain wrapper). Emitted as the
+      #   registry's "helpers" section so boot-free consumers (poetry check,
+      #   the MCP server) know the full valid helper set AND the value
+      #   contracts runtime-enforced inside those helpers.
+      # @param blocks [Hash, nil] the gem's block catalog: block
+      #   name => {"title", "description", "components", "template"} - title/
+      #   description parsed from each template's poetry:block header, the
+      #   composed components derived from its poetry_* calls, template the
+      #   gem-relative source path boot-free consumers (the MCP server) read.
+      #   Emitted as the registry's "blocks" section.
+      # @param helper_args [Hash, nil] max POSITIONAL arity per poetry_*
+      #   helper, introspected from the gem's helper-module signatures
+      #   (e.g. `poetry_link "text", href:` on a kwargs-only
+      #   helper raises at render). Rest-signatures are omitted (unknowable); the linter
+      #   enforces arity only where a key exists, so registries without the
+      #   map stay lint-identical.
+      # @param descriptions [Hash, nil] one-line human descriptions per
+      #   component_path (the gem's editorial component_descriptions.yml),
+      #   merged into each entry as "description" - the summary llms.txt, the
+      #   MCP describe_component, and the docs page all read from one source.
+      # @param form_builder [Hash, nil] the gem's FormBuilder surface
+      #   ({"rules" => [...], "methods" => {name => one-liner}, "input_types"
+      #   => [...]}) - emitted as the registry's "form_builder" section so
+      #   llms.txt, the MCP server, and skills can teach the model-bound
+      #   form story without booting the gem. Optional like every other
+      #   section: absent -> the registry stays byte-identical.
+      def initialize(components: nil, source_root: Poetry::Core.root, # rubocop:disable Metrics/ParameterLists
+                     helpers: nil, blocks: nil, helper_args: nil, descriptions: nil, form_builder: nil)
+        @source_root = Pathname.new(source_root)
+        @components = (components || discover).sort_by(&:name)
+        @helpers = helpers
+        @blocks = blocks
+        @helper_args = helper_args
+        @descriptions = descriptions
+        @form_builder = form_builder
+      end
+
+      # The discovered component classes (the registry's working set).
+      attr_reader :components
+
+      # The block catalog and the root template paths resolve against -
+      # LlmsText reads both to inline block source into llms-full.txt.
+      attr_reader :blocks, :source_root
+
+      # The FormBuilder surface (optional section) - LlmsText renders it as
+      # the Forms section.
+      attr_reader :form_builder
+
+      # The full registry payload's "components" section: one contract hash
+      # per discovered component, keyed by component path.
+      #
+      # @return [Hash{String => Hash}]
+      def entries
+        @components.to_h { |component| [component.component_path, entry_for(component)] }
+      end
+
+      # The complete registry serialized as plain-data YAML (components plus
+      # the optional helpers/blocks/helper_args/form_builder sections),
+      # headed by the do-not-edit banner.
+      #
+      # @return [String]
+      def to_yaml
+        payload = { "components" => entries }
+        payload["helpers"] = plain(@helpers.sort.to_h) if @helpers&.any?
+        payload["blocks"] = plain(@blocks.sort.to_h) if @blocks&.any?
+        payload["helper_args"] = plain(@helper_args.sort.to_h) if @helper_args&.any?
+        payload["form_builder"] = plain(@form_builder) if @form_builder&.any?
+        HEADER + YAML.dump(payload)
+      end
+
+      # Writes the registry YAML to its committed location under root.
+      #
+      # @param root [Pathname, String] the gem root to write under
+      # @return [Pathname] the written file path
+      def generate!(root: @source_root)
+        path = Pathname.new(root).join(RELATIVE_PATH)
+        path.dirname.mkpath
+        path.write(to_yaml)
+        path
+      end
+
+      # False when the committed registry does not match a fresh build.
+      #
+      # @param root [Pathname, String] the gem root holding the committed file
+      # @return [Boolean]
+      def verified?(root: @source_root)
+        path = Pathname.new(root).join(RELATIVE_PATH)
+        path.exist? && path.read == to_yaml
+      end
+
+      private
+
+      # Named Component descendants whose source lives inside source_root's
+      # app/ tree - excludes host-app AND test-defined components, so
+      # discovery is identical under a fresh boot and inside the test suite.
+      # The components dir is eager-loaded first: `descendants` only sees
+      # loaded classes, and lazy autoloading (tests) would otherwise make
+      # discovery order-dependent.
+      def discover
+        app_root = @source_root.join("app")
+        components_dir = app_root.join("components")
+        if defined?(Rails) && Rails.respond_to?(:autoloaders) && components_dir.directory?
+          Rails.autoloaders.main.eager_load_dir(components_dir)
+        end
+        Poetry::Core::Component.descendants.select(&:name).reject(&:internal_component).select do |component|
+          path = Object.const_source_location(component.name)&.first
+          path&.start_with?(app_root.to_s)
+        end
+      end
+
+      # Whether the component's rendered output can carry a poetry-minted
+      # id. An IDENTITY constant declared on the component's own ancestry
+      # wins (composition: a component whose DOM carries ids minted by
+      # components it RENDERS derives false and declares true). Otherwise
+      # the ancestor chain below Poetry::Core::Component - the class
+      # itself, family modules, intermediate bases; everywhere minting
+      # calls live - is source-scanned for the poetry_instance_id funnel
+      # (or a direct SecureRandom mint). The walk stops at the base class
+      # so the funnel's own definition never reads as a call, and the
+      # scan errs toward true: a false positive keeps a warning, a false
+      # negative would silence a real one.
+      def mints_identity?(component)
+        family = component.ancestors.take_while { |mod| mod != Poetry::Core::Component }
+        override = family.find { |mod| mod.const_defined?(:IDENTITY, false) }
+        return override.const_get(:IDENTITY, false) if override
+
+        family.any? { |mod| mint_source?(mod) }
+      end
+
+      # Whether one ancestor's source file mentions the minting funnel.
+      def mint_source?(mod)
+        path = mod.name && Object.const_source_location(mod.name)&.first
+        return false unless path && File.exist?(path)
+
+        mint_sources = (@mint_sources ||= {})
+        mint_sources.fetch(path) { mint_sources[path] = File.read(path).match?(MINT_PATTERN) }
+      end
+
+      def entry_for(component)
+        props = component.prop_definitions
+        entry = {
+          "class_name" => component.name,
+          "identifier" => component.component_identifier,
+          "bem_block" => component.component_path.tr("/", "-"),
+          "styles" => plain(props[:styles]),
+          "options" => plain(props[:options]),
+          "slots" => plain(props[:slots])
+        }
+        # The one-line human description (editorial, merged from the gem's
+        # component_descriptions.yml) - the summary llms.txt / describe_component
+        # / the docs page read from this single source.
+        if @descriptions && (description = @descriptions[component.component_path])
+          entry["description"] = description
+        end
+        # Hand-rolled with_* conveniences beyond the registered slots
+        # (NavigationMenu#with_link) - consumers call them, so check and the
+        # agent surfaces must know them.
+        entry["slot_extras"] = plain(props[:slot_extras]) if props[:slot_extras]&.any?
+        if (style = component.style_class)
+          entry["elements"] = style.resolver.elements.keys.map(&:to_s)
+          entry["capsule"] = style.capsule
+        end
+        # The JS wiring surface: the poetry--core--* controller
+        # identifiers the component wires, each joined to its manifest
+        # (targets / values / actions) so the registry is the ONE contract
+        # poetry check / llms.txt / the MCP server read. Derived from the
+        # component's controller-identifier constants (%i[poetry core x]);
+        # the rendered-truth drift test guarantees this equals what the
+        # previews actually emit as data-controller.
+        # plain() rebuilds fresh objects - the manifest arrays are shared
+        # across components that wire the same controller (popper is in 8),
+        # which would otherwise make Psych emit YAML anchors/aliases.
+        controllers = wired_controllers(component)
+        entry["controllers"] = plain(controllers) unless controllers.empty?
+        # Component-specific constraints agents must honor (the contract's
+        # agent_rules section) - declared as an AGENT_RULES constant.
+        entry["agent_rules"] = component::AGENT_RULES.dup if component.const_defined?(:AGENT_RULES)
+        # The requires_content declaration:
+        # the same fact that raises at render lets poetry check flag a
+        # blockless call statically.
+        if component.respond_to?(:required_content) && (hint = component.required_content)
+          entry["requires_content"] = hint
+        end
+        # The REQUIRED_SLOTS declaration: the
+        # same fact that raises in before_render lets poetry check flag a
+        # call that never sets the slot, statically.
+        entry["required_slots"] = plain(props[:required_slots]) if props[:required_slots]&.any?
+        # The REQUIRES_ANY declaration: the conditional any-of
+        # contracts - the before_render disjunction, stated statically.
+        entry["requires_any"] = plain(props[:requires_any]) if props[:requires_any]&.any?
+        # The identity fact: false when the family renders no
+        # poetry-minted id - key:/id: would have nothing to stabilize, so
+        # check's stable-identity rules skip the helper. Absent = the
+        # component mints (legacy registries keep every warning).
+        entry["identity"] = false unless mints_identity?(component)
+        # The part contract: the
+        # styling surface - data-slot parts, state attributes per part,
+        # CSS var seams - hand-authored prose that PartContract.verify
+        # holds to the rendered DOM of every preview.
+        parts = component.part_definitions
+        entry["parts"] = plain(parts) if parts.any?
+
+        # The element-level wiring projection (use_stimulus declarations,
+        # resolved): which parts carry which controllers, values, actions,
+        # and targets - the usage view beside the controllers section's
+        # capability view.
+        if component.respond_to?(:stimulus_definitions)
+          wiring = component.stimulus_definitions
+          entry["stimulus"] = plain(wiring) if wiring.any?
+        end
+        # The agent-tool projection (tool declarations, MCP Tool-shaped):
+        # the component's operate surface - what an in-page agent may
+        # invoke on a rendered instance, and which Stimulus action each
+        # tool dispatches.
+        if component.respond_to?(:tool_definitions)
+          tools = component.tool_definitions
+          entry["tools"] = plain(tools) if tools.any?
+        end
+        entry
+      end
+
+      # The controllers a component wires, joined to the manifest. Two
+      # sources: use_stimulus declarations (exact - the resolved
+      # identifiers of every declared element) and, for components not yet
+      # migrated to declarations, the legacy constant scan - an array of
+      # symbols beginning [:poetry, :core, ...] is exactly the Builder
+      # identifier shape.
+      def wired_controllers(component)
+        identifiers = []
+        if component.respond_to?(:stimulus_identifiers)
+          # Manifest-known only: host-app controllers declared by a
+          # component are not poetry's to document.
+          identifiers += component.stimulus_identifiers
+                                  .select { |id| Poetry::Core::Stimulus::Manifest.catalog.key?(id) }
+        end
+
+        # Constants live inconsistently: some components define them on the
+        # Component class (Checkbox::CHECKED), others on the enclosing module
+        # (Select::SELECT/POPPER), and subclasses inherit them (Sheet reuses
+        # Dialog's). Scan the class (+ ancestors) AND the component's module,
+        # then let the rendered-truth drift test arbitrate.
+        scopes = [component]
+        scopes << component.module_parent if component.respond_to?(:module_parent)
+
+        identifiers += scopes.flat_map do |scope|
+          own = scope.equal?(component) # inherited only matters for the class
+          scope.constants(own).filter_map do |name|
+            value = scope.const_get(name)
+            next unless value.is_a?(Array) && value.all?(Symbol) && value.first(2) == %i[poetry core]
+
+            Poetry::Core::Stimulus::Builder.format_identifier(value)
+          rescue StandardError
+            next
+          end
+        end
+
+        identifiers.uniq.sort.map do |identifier|
+          definition = Poetry::Core::Stimulus::Manifest.catalog[identifier] || {}
+          {
+            "identifier" => identifier,
+            "targets" => definition["targets"] || [],
+            "values" => (definition["values"] || {}).keys.sort,
+            "actions" => (definition["methods"] || []) - LIFECYCLE_METHODS,
+            "events" => definition["events"] || []
+          }
+        end
+      end
+
+      # Deep-converts symbols to strings so the YAML is plain data (no
+      # !ruby/symbol tags) - loadable by any consumer, any language.
+      def plain(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_s, plain(v)] }
+        when Array then value.map { |v| plain(v) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/registry_address.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Poetry
+  module Core
+    # The uniform registry address scheme:
+    # no --from flag, ONE classifier for every
+    # generator argument and every registryDependencies entry. An address is
+    # exactly one of:
+    #
+    #   https://acme.dev/r/fancy-chart.json   :url        any endpoint
+    #   ./registry/fancy-chart.json           :file       a local item file
+    #   @acme/fancy-chart                     :namespace  a configured registry
+    #   button / Button / input_group         :bare       the installed gems
+    #
+    # Item names normalize to kebab-case everywhere (InputGroup and
+    # input_group are both input-group) - the block catalog's existing
+    # naming, and the wider registry ecosystem's.
+    #
+    # @example
+    #   Poetry::Core::RegistryAddress.parse("@acme/fancy-chart").kind # => :namespace
+    class RegistryAddress
+      # The `@namespace/item-name` address shape (`@acme/fancy-chart`): a
+      # registry namespace, a slash, an item name.
+      NAMESPACED = %r{\A(@[a-z0-9][a-z0-9_-]*)/([A-Za-z0-9_-]+)\z}
+      # The bare item-name address shape (the installed gems).
+      BARE = /\A[A-Za-z0-9_-]+\z/
+
+      attr_reader :kind, :raw, :namespace, :name, :location
+
+      # Parses one address into its kind: `http(s)://` is a :url, `@x/y` a
+      # :namespace, a `.json` path or a `./`, `../`, `/`, `~` prefix a
+      # :file, and a plain item name a :bare address.
+      #
+      # @param raw [String, #to_s] the address as typed
+      # @return [RegistryAddress]
+      # @raise [ArgumentError] for an empty or unrecognized address
+      def self.parse(raw)
+        raw = raw.to_s.strip
+        raise ArgumentError, "empty registry address" if raw.empty?
+
+        if raw.match?(%r{\Ahttps?://}) then new(kind: :url, raw: raw, location: raw)
+        elsif raw.start_with?("@") then parse_namespaced(raw)
+        elsif raw.end_with?(".json") || raw.start_with?("./", "../", "/", "~")
+          new(kind: :file, raw: raw, location: raw)
+        elsif raw.match?(BARE)
+          new(kind: :bare, raw: raw, name: normalize(raw))
+        else
+          raise ArgumentError, "unrecognized registry address #{raw.inspect}"
+        end
+      end
+
+      # Parses an `@namespace/item-name` address.
+      #
+      # @param raw [String] the address, already known to start with `@`
+      # @return [RegistryAddress] a :namespace address
+      # @raise [ArgumentError] when the shape is not `@registry/item-name`
+      def self.parse_namespaced(raw)
+        match = NAMESPACED.match(raw)
+        raise ArgumentError, "malformed namespaced address #{raw.inspect} (expected @registry/item-name)" unless match
+
+        new(kind: :namespace, raw: raw, namespace: match[1], name: normalize(match[2]))
+      end
+
+      # CamelCase / snake_case / kebab-case all land on the kebab item name.
+      #
+      # @param name [String] an item name in any of the three spellings
+      # @return [String] the kebab-case item name
+      def self.normalize(name)
+        name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.tr("_", "-")
+      end
+
+      # Builds a frozen address; {.parse} is the usual entry point.
+      #
+      # @param kind [Symbol] :bare, :namespace, :url, or :file
+      # @param raw [String] the address as typed
+      # @param namespace [String, nil] the `@registry` part of a :namespace address
+      # @param name [String, nil] the normalized item name (:bare, :namespace)
+      # @param location [String, nil] the URL or path (:url, :file)
+      def initialize(kind:, raw:, namespace: nil, name: nil, location: nil)
+        @kind = kind
+        @raw = raw
+        @namespace = namespace
+        @name = name
+        @location = location
+        freeze
+      end
+
+      # Whether the item has to be fetched rather than found among the
+      # installed gems - every kind but :bare.
+      #
+      # @return [Boolean]
+      def remote?
+        kind != :bare
+      end
+
+      # The address of a bare dependency named inside a parent item - the
+      # sibling convention: an @acme item's bare deps are @acme items; a
+      # url/file item's bare deps sit next to it.
+      #
+      # @param dep_name [String] the dependency's bare item name
+      # @return [RegistryAddress]
+      # @raise [ArgumentError] for a :bare address, which has no siblings
+      def sibling(dep_name)
+        case kind
+        when :namespace then self.class.parse("#{namespace}/#{dep_name}")
+        when :url then self.class.parse(URI.join(location, "#{dep_name}.json").to_s)
+        when :file then self.class.parse(File.join(File.dirname(location), "#{dep_name}.json"))
+        else raise ArgumentError, "a #{kind} address has no siblings"
+        end
+      end
+    end
+  end
+end