poetry-core 0.0.2

data/lib/poetry/core/icons.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The pluggable icon-set registry (Lucide default, per-set
+    # adapters). An icon set is anything responding to #include?(name),
+    # #fetch(name) -> inner SVG markup, and #names. Sets register themselves
+    # on require (poetry-lucide does); the active set is selected by
+    # `config.icon_library` and can be overridden per render.
+    #
+    # SECURITY: #fetch's return value is rendered `html_safe` by the Icon
+    # component. The shipped sets vendor SVGs sanitized AT VENDOR TIME
+    # (poetry-lucide's fetch script strips <script>/<foreignObject>/handlers
+    # /external-href <use>/<image>), so render never parses untrusted markup.
+    # A custom set registered by a host MUST pre-sanitize its SVGs the same
+    # way - the vendored pipeline is the reference; a set that serves raw,
+    # attacker-influenced SVG is an XSS sink.
+    module Icons
+      # A directory of vendored, pre-sanitized icon files - one
+      # `<name>.svg` per icon holding the INNER markup (the component owns
+      # the <svg> wrapper). Reads are memory-cached; names are validated
+      # against a strict format before touching the filesystem (icon names
+      # can carry user input - no path traversal).
+      class FileSet
+        # The kebab-case shape every icon name must match before it touches
+        # the filesystem.
+        NAME_FORMAT = /\A[a-z0-9][a-z0-9-]*\z/
+
+        attr_reader :dir
+
+        # A set over one directory of sanitized SVG files, one file per
+        # icon name (`circle-alert.svg`); each icon is read once and cached.
+        #
+        # @param dir [String, Pathname] the directory holding the SVGs
+        def initialize(dir:)
+          @dir = Pathname.new(dir)
+          @cache = {}
+          @mutex = Mutex.new
+        end
+
+        # Whether the set has an icon of this name: the name must be
+        # well-formed and its SVG present on disk.
+        #
+        # @param name [Symbol, String] the icon name
+        # @return [Boolean]
+        def include?(name)
+          valid_name?(name) && path_for(name).exist?
+        end
+
+        # The inner SVG markup of one icon, read once and cached.
+        #
+        # @param name [Symbol, String] the icon name
+        # @return [String] the icon's inner SVG markup
+        # @raise [Poetry::Core::IconNotFound] for a malformed name, or an
+        #   unknown one (the message carries a did-you-mean suggestion when
+        #   one exists; the error's #name and #suggestion carry the parts)
+        def fetch(name)
+          raise IconNotFound.new("invalid icon name #{name.inspect}", name: name) unless valid_name?(name)
+
+          unless path_for(name).exist?
+            suggestion = Icons.suggest(name, names)
+            hint = suggestion ? " - did you mean #{suggestion.to_sym.inspect}?" : ""
+            raise IconNotFound.new("unknown icon #{name.inspect} (not in this set)#{hint}",
+                                   name: name, suggestion: suggestion)
+          end
+
+          @mutex.synchronize do
+            @cache[name.to_sym] ||= path_for(name).read.strip
+          end
+        end
+
+        # Every icon name in the set, sorted.
+        #
+        # @return [Array<Symbol>]
+        def names
+          @names ||= @dir.glob("*.svg").map { |path| path.basename(".svg").to_s.to_sym }.sort
+        end
+
+        private
+
+        def valid_name?(name)
+          name.to_s.match?(NAME_FORMAT)
+        end
+
+        def path_for(name)
+          @dir.join("#{name}.svg")
+        end
+      end
+
+      class << self
+        # Did-you-mean for icon names. The reversed-compound form is
+        # checked before edit distance: Lucide v1 swapped modifier and noun
+        # (alert-circle -> circle-alert, x-circle -> circle-x), a rename class
+        # DidYouMean's checker misses every time - the reversal IS the fix.
+        #
+        # @param name [Symbol, String] the unknown name (underscores tolerated)
+        # @param names [Enumerable] the valid names to suggest from
+        # @return [String, nil] the closest valid name, or nil
+        def suggest(name, names)
+          name = name.to_s.tr("_", "-")
+          candidates = names.map(&:to_s)
+          reversed = name.split("-").reverse.join("-")
+          return reversed if reversed != name && candidates.include?(reversed)
+
+          require "did_you_mean"
+          DidYouMean::SpellChecker.new(dictionary: candidates).correct(name).first
+        end
+
+        # The registered icon sets, library key => set object. Icon gems
+        # add themselves here on require.
+        #
+        # @return [Hash{Symbol => Object}]
+        def registry
+          @registry ||= {}
+        end
+
+        # Registers an icon set under a library key - the extension point
+        # an icon gem calls on require. A set is any object responding to
+        # `#include?(name)`, `#fetch(name)` (returning inner SVG markup),
+        # and `#names`. The set contract: `#fetch` raises
+        # {Poetry::Core::IconNotFound} for any name it cannot serve - the
+        # Icon component's missing-icon policy rescues exactly that class.
+        # See the SECURITY note above for the pre-sanitization requirement
+        # on custom sets.
+        #
+        # @param key [Symbol, String] the library key `config.icon_library`
+        #   selects the set by
+        # @param set [Object] the icon set (a {FileSet} over a directory of
+        #   vendored SVGs, or any object honoring the same contract)
+        # @example Register a vendored set and select it
+        #   Poetry::Core::Icons.register(:my_icons,
+        #     Poetry::Core::Icons::FileSet.new(dir: root.join("icons")))
+        #   # config/initializers/poetry.rb: config.icon_library = :my_icons
+        # @return [Object] the set, now registered
+        def register(key, set)
+          registry[key.to_sym] = set
+        end
+
+        # The set for the given library key, defaulting to
+        # config.icon_library. Raises with the fix when unregistered.
+        #
+        # @param library [Symbol, String, nil] the library key; nil reads
+        #   `Poetry::Core::Config.current.icon_library`
+        # @return [Object] the registered set
+        # @raise [Poetry::Core::Error] when no set is registered under the key
+        def set(library = nil)
+          key = (library || Poetry::Core::Config.current.icon_library).to_sym
+          registry.fetch(key) do
+            raise Poetry::Core::Error,
+                  "no icon set registered as #{key.inspect} - require its gem (e.g. poetry-lucide) " \
+                  "or set config.icon_library to one of: #{registry.keys.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/llms_text.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # Generates llms.txt (the index) and llms-full.txt (full contracts) from
+    # the component registry - never hand-maintained, so the LLM-facing docs
+    # can't drift from the code.
+    #
+    # @example
+    #   Poetry::Core::LlmsText.new(registry: registry).index
+    #
+    # @api private
+    class LlmsText
+      PREAMBLE = <<~TEXT
+        # Poetry for Rails
+
+        > poetry is an AI-native, Rails-first component library: accessible,
+        > themeable ViewComponents on semantic design tokens. Agents compose
+        > from the approved catalog below instead of writing raw markup.
+
+        Preference hierarchy: tokens > utilities; components > raw markup;
+        variants > one-off classes; slots > custom HTML. Render components
+        with their `poetry_<name>` helpers.
+
+        Verify your markup with `poetry check` (rake poetry:check) before it
+        renders - it validates components, options, variants, and Stimulus
+        wiring against these contracts. Testing doctrine: the Testing guide on the poetry docs site.
+      TEXT
+
+      def initialize(registry:)
+        @registry = registry
+      end
+
+      # The lean index: one line per component (+ the blocks catalog).
+      def index
+        lines = @registry.entries.map do |path, entry|
+          "- #{title(path)}: `#{helper(path)}` - #{index_summary(entry)}"
+        end
+        "#{PREAMBLE}\n## Components\n\n#{lines.join("\n")}\n#{blocks_index}"
+      end
+
+      # The index line's summary: the human description leads (what it is),
+      # then the style surface (its variants) in parens so an agent still sees
+      # the options at a glance. Description-less entries fall back to the
+      # surface alone.
+      def index_summary(entry)
+        surface = surface_summary(entry)
+        return surface unless entry["description"]
+
+        surface == "no style attributes" ? entry["description"] : "#{entry["description"]} (#{surface})"
+      end
+
+      # The full contracts: props, slots, elements, and agent rules - plus
+      # every block's source, so an agent holding this file can start a
+      # screen from a vetted composition without another fetch.
+      def full
+        sections = @registry.entries.map { |path, entry| component_section(path, entry) }
+        "#{PREAMBLE}\n#{sections.join("\n")}#{forms_full}#{blocks_full}"
+      end
+
+      # The Forms section (the registry's optional form_builder surface):
+      # the model-bound builder rules + method table, so an agent writing a
+      # form reaches for f.input before hand-composing Fields.
+      def forms_full
+        surface = @registry.respond_to?(:form_builder) ? @registry.form_builder : nil
+        return "" unless surface&.any?
+
+        lines = ["\n## Forms (Poetry::Ui::FormBuilder)\n"]
+        Array(surface["rules"]).each { |rule| lines << "- #{rule}" }
+        if (methods = surface["methods"])&.any?
+          lines << "\nBuilder methods:"
+          methods.each { |name, summary| lines << "- `f.#{name}` - #{summary}" }
+        end
+        if (types = surface["input_types"])&.any?
+          lines << "\n`f.input as:` values: #{types.join(", ")}."
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      # The helper is poetry_ + the path under the ui/ namespace, so
+      # command/dialog -> poetry_command_dialog (not the last-segment
+      # poetry_dialog, which collides with the top-level dialog).
+      def title(path) = path.split("/").drop(2).join("_")
+      def helper(path) = "poetry_#{title(path)}"
+
+      def surface_summary(entry)
+        parts = entry["styles"].map do |style|
+          values = style["variants"] ? style["variants"].join("|") : style["type"]
+          "#{style["name"]}: #{values}"
+        end
+        parts.empty? ? "no style attributes" : parts.join("; ")
+      end
+
+      def component_section(path, entry)
+        lines = ["## #{title(path)} (`#{helper(path)}`)", ""]
+        lines << "#{entry["description"]}\n" if entry["description"]
+        lines << "Class: #{entry["class_name"]} - BEM block `#{entry["bem_block"]}`."
+        if (hint = entry["requires_content"])
+          lines << "Content block REQUIRED (#{hint}) - a blockless call raises."
+        end
+        (entry["required_slots"] || {}).each do |setter, hint|
+          lines << "Slot REQUIRED: with_#{setter} (#{hint}) - a call without it raises."
+        end
+        (entry["requires_any"] || []).each do |group|
+          lines << "REQUIRED - #{any_of_phrase(group)}; a call satisfying none raises."
+        end
+        lines.concat(prop_lines(entry))
+        slots = entry["slots"].map { |slot| slot_summary(slot) }
+        lines << "Slots: #{slots.join(", ")}." if slots.any?
+        lines.concat(part_lines(entry))
+        # The block back-reference: the arrow points UP at the
+        # surface agents actually read - a screen containing this component
+        # should start from the vetted composition, not from scratch.
+        if (blocks = blocks_composing(title(path))).any?
+          lines << "In blocks: #{blocks.join(", ")} - for a screen, start from the block " \
+                   "(MCP compose/describe_block, or `bin/rails g poetry:block`), not from scratch."
+        end
+        lines.concat(wiring_lines(entry))
+        lines.concat(tool_lines(entry))
+        (entry["agent_rules"] || []).each { |rule| lines << "- RULE: #{rule}" }
+        "#{lines.join("\n")}\n"
+      end
+
+      # The operate surface: the tools an in-page agent may invoke on a
+      # rendered instance once the call opts in (`webmcp: "name"`) - the
+      # same line describe_component prints, so no surface can lag.
+      def tool_lines(entry)
+        (entry["tools"] || []).map do |tool|
+          schema = tool["inputSchema"] || {}
+          required = schema["required"] || []
+          params = (schema["properties"] || {}).map do |name, spec|
+            facets = [spec["type"]]
+            facets << "required" if required.include?(name)
+            facets << "one of #{spec["enum"].join("|")}" if spec["enum"]
+            "#{name} (#{facets.join(", ")})"
+          end
+          facets = [tool.dig("annotations", "readOnlyHint") ? "read-only" : "mutating"]
+          facets << "params: #{params.join(", ")}" if params.any?
+          "- tool #{tool["name"]} (#{facets.join("; ")}) - #{tool["description"]} " \
+            "[opt in with webmcp: \"name\" on the call; dispatches #{tool["executes"]}]"
+        end
+      end
+
+      # The styling contract: every data-slot part with its state
+      # attributes and var seams - DOM-verified by the part-contract tier,
+      # so a restyling instruction can only target selectors that provably
+      # exist. Restyle via `[data-slot=<part>]` (+ state selectors); never
+      # guess at internal markup.
+      def part_lines(entry)
+        (entry["parts"] || []).map do |part|
+          facets = []
+          states = (part["states"] || []).map { |state| state_phrase(state) }
+          facets << "states: #{states.join("; ")}" if states.any?
+          vars = (part["vars"] || []).map { |var| "#{var["name"]} (#{var["description"]})" }
+          facets << "vars: #{vars.join("; ")}" if vars.any?
+          "- PART `#{part["name"]}` - #{part["description"]}#{" | #{facets.join(" | ")}" if facets.any?}"
+        end
+      end
+
+      def state_phrase(state)
+        values = state["values"] ? "=#{state["values"].join("|")}" : ""
+        "#{state["attr"]}#{values} (#{state["condition"]})"
+      end
+
+      # The any-of contract, phrased once: "one of a content block
+      # / with_leading / loading: (hint)".
+      def any_of_phrase(group)
+        parts = []
+        parts << "a content block" if group["content"]
+        parts.concat((group["slots"] || []).map { |name| "with_#{name}" })
+        parts.concat((group["options"] || []).map { |key| "#{key}:" })
+        "one of #{parts.join(" / ")} (#{group["hint"]})"
+      end
+
+      # Block names composing a component (inverted from the blocks
+      # catalog), or [] for a registry without blocks.
+      def blocks_composing(component_title)
+        @blocks_composing ||= (@registry.blocks || {}).each_with_object(Hash.new do |h, k|
+          h[k] = []
+        end) do |(name, entry), map|
+          entry["components"].each { |component| map[component] << "`#{name}`" }
+        end
+        @blocks_composing[component_title]
+      end
+
+      # The Stimulus wiring surface: the controllers a component
+      # renders, each with the targets / values / actions an agent may wire
+      # by hand and the events it may listen for.
+      # Absent for static components.
+      # Element-level when the entry carries the projection (use_stimulus
+      # declarations); the controller-level capability view otherwise
+      # (charts, external registries).
+      def wiring_lines(entry)
+        return element_wiring_lines(entry) if entry["stimulus"]
+
+        (entry["controllers"] || []).map do |controller|
+          facets = []
+          facets << "targets #{controller["targets"].join(", ")}" if controller["targets"].any?
+          facets << "values #{controller["values"].join(", ")}" if controller["values"].any?
+          facets << "actions #{controller["actions"].join(", ")}" if controller["actions"].any?
+          facets << "events #{controller["events"].join(", ")}" if (controller["events"] || []).any?
+          "- WIRING `#{controller["identifier"]}`#{": #{facets.join("; ")}" unless facets.empty?}"
+        end
+      end
+
+      def element_wiring_lines(entry)
+        entry["stimulus"].map do |element|
+          phrases = element["controllers"].map { |wiring| wiring_phrase(wiring) }
+          suffix = element["conditional"] ? " (#{element["conditional"]})" : ""
+          "- WIRING #{element["element"]}#{suffix}: #{phrases.join(" | ")}"
+        end
+      end
+
+      def wiring_phrase(wiring)
+        facets = []
+        facets << "registers#{" (#{wiring["registers"]})" unless wiring["registers"] == true}" if wiring["registers"]
+        if (values = wiring["values"])
+          facets << "values #{values.map { |value| conditional_name(value, "name") }.join(", ")}"
+        end
+        if (actions = wiring["actions"])
+          facets << "actions #{actions.map { |action| action_phrase(action) }.join(", ")}"
+        end
+        if (targets = wiring["targets"])
+          facets << "targets #{targets.map { |target| conditional_name(target, "name") }.join(", ")}"
+        end
+        suffix = wiring["conditional"] ? " (#{wiring["conditional"]})" : ""
+        "`#{wiring["identifier"]}`#{suffix} #{facets.join("; ")}".strip
+      end
+
+      def action_phrase(action)
+        phrase = action["method"]
+        if (on = action["on"])
+          events = Array(on).join("/")
+          events = "#{events}@#{action["at"]}" if action["at"]
+          phrase = "#{phrase} on #{events}"
+        end
+        action["conditional"] ? "#{phrase} (#{action["conditional"]})" : phrase
+      end
+
+      def conditional_name(item, key)
+        item["conditional"] ? "#{item[key]} (#{item["conditional"]})" : item[key]
+      end
+
+      def prop_lines(entry)
+        (entry["styles"] + entry["options"]).map do |prop|
+          details = []
+          details << "one of #{prop["variants"].join("|")}" if prop["variants"]
+          details << "default #{prop["default"].inspect}" if prop.key?("default")
+          details << "required" if prop["required"]
+          details << "format: #{prop["format"]}" if prop["format"]
+          line = "- `#{prop["name"]}:` (#{prop["type"]})#{" - #{details.join(", ")}" if details.any?}"
+          prop["description"] ? "#{line} - #{prop["description"]}" : line
+        end
+      end
+
+      # A typed slot renders another component: the call takes THAT
+      # component's props, never a render block (with_icon(name: ...) - the
+      # block-form guess an agent would otherwise make, which this line now
+      # forecloses). Untyped slots take blocks; many-slots say so; a
+      # polymorphic slot lists its with_<type> setters - and when they are
+      # all kwargs-only, says so (foreclosing the type-as-argument
+      # dispatch no setter has). Each shape that raises at render
+      # gets its own sentence: yieldless setters (no |param| - it would be
+      # nil), closed keyword signatures (the exact accepted set), and
+      # setters that cannot omit their content block.
+      def slot_summary(slot)
+        qualifiers = []
+        qualifiers << slot["description"] if slot["description"]
+        qualifiers << "many" if slot["many"]
+        if slot["types"]
+          convention = kwargs_only_setters?(slot) ? " - one with_<type> setter each, options as keywords" : ""
+          qualifiers << "types #{slot["types"].join("|")}#{convention}"
+        end
+        qualifiers << "takes #{helper(slot["component"])} props, not a block" if slot["component"]
+        if (yieldless = slot["yieldless"])
+          setters = yieldless.map { |name| "with_#{name}" }.join("/")
+          verb = yieldless.size == 1 ? "yields" : "yield"
+          qualifiers << "#{setters} #{verb} NOTHING to the block - no |param|, write content directly"
+        end
+        (slot["setter_kwargs"] || {}).each do |setter, keywords|
+          qualifiers << "with_#{setter} keywords: #{keywords.map { |keyword| "#{keyword}:" }.join(", ")} ONLY"
+        end
+        (slot["required_content"] || {}).each do |setter, hint|
+          qualifiers << "with_#{setter} REQUIRES a content block (#{hint})"
+        end
+        # The nested requirement seam (with_menu
+        # without with_trigger raises - stated where agents read).
+        (slot["builders"] || {}).each do |setter, surface|
+          (surface["required_slots"] || {}).each do |required, hint|
+            qualifiers << "each with_#{setter} REQUIRES with_#{required} inside its block (#{hint})"
+          end
+        end
+        "#{slot["name"]}#{" (#{qualifiers.join("; ")})" if qualifiers.any?}"
+      end
+
+      def kwargs_only_setters?(slot)
+        args = slot["setter_args"]
+        # A type with no tracked arity (rest-signature) is unknowable - the
+        # claim only holds when every setter is known kwargs-only.
+        args && slot["types"].all? { |type| args[type]&.zero? }
+      end
+
+      # The blocks catalog: vetted composed screens, one
+      # altitude above components. The index teaches the decision
+      # hierarchy - start a SCREEN from a block, compose atoms for what no
+      # block covers.
+      def blocks_index
+        blocks = @registry.blocks
+        return "" if blocks.nil? || blocks.empty?
+
+        lines = blocks.map do |name, entry|
+          "- #{entry["title"]} (`#{name}`): #{entry["description"]} " \
+            "[composes: #{entry["components"].join(", ")}]"
+        end
+        <<~TEXT
+
+          ## Blocks
+
+          Blocks are the DEFAULT starting point, not a fallback: route every
+          brief through the MCP `compose` tool first - it returns the
+          matching block's source ready to adapt, or the component path when
+          nothing matches. Without MCP: `bin/rails g poetry:block <name>`
+          copies a block into app/views/blocks/ as source the app owns
+          (--list to browse). Blocks carry the composed patterns -
+          containment, status color-coding, page furniture, realistic
+          content - so a screen starts composed, not blank. Page framing
+          counts: a section that IS the page's subject keeps its container +
+          breathing room (the section blocks demonstrate the wrapper) - a
+          bare component at the viewport origin reads cramped.
+
+          #{lines.join("\n")}
+        TEXT
+      end
+
+      def blocks_full
+        blocks = @registry.blocks
+        return "" if blocks.nil? || blocks.empty?
+
+        sections = blocks.map do |name, entry|
+          source = @registry.source_root.join(entry.fetch("template")).read
+          ["## Block: #{entry["title"]} (`#{name}`)", "",
+           entry["description"],
+           "Composes: #{entry["components"].join(", ")}. " \
+           "Generate: `bin/rails g poetry:block #{name}`.",
+           "Source (adapt freely - the sample content is meant to be replaced):", "",
+           source.sub(/\A<%#\s*poetry:block[^%]*%>\n?/, "").rstrip].join("\n")
+        end
+        "\n#{sections.join("\n\n")}\n"
+      end
+    end
+  end
+end