stimulus_plumbers_mcp 0.4.4 → 0.4.8

data/lib/stimulus_plumbers/mcp/loaders/guide_loader.rb

@@ -3,12 +3,48 @@
 module StimulusPlumbers
   module MCP
     class GuideLoader
-      OVERVIEW_PATH = File.expand_path("guide/overview.md", __dir__).freeze
+      OVERVIEW_PATH = File.expand_path("guide.md", __dir__).freeze
 
-      def self.call
-        return "" unless File.exist?(OVERVIEW_PATH)
+      class << self
+        def call
+          {
+            overview:   read_file(OVERVIEW_PATH),
+            component:  read_file(component_guide_path),
+            controller: read_file(controller_guide_path),
+            tailwind:   read_file(tailwind_guide_path),
+            theme:      read_file(File.join(ComponentDocsLoader.docs_dir, "theme.md"))
+          }
+        end
 
-        File.read(OVERVIEW_PATH)
+        # Reused by VersionsLoader to report which fallback location resolved.
+        def controller_guide_path
+          # 1. Monorepo dev checkout — the JS package's own docs are freshest while working locally.
+          dev_path = File.expand_path(File.join(__dir__, "../../../../..", "stimulus-plumbers", "docs", "guide.md"))
+          return dev_path if File.exist?(dev_path)
+
+          # 2. gem exec — vendored into the rails gem at release time, under vendor/controller/guide.md.
+          GemVendorPath.resolve("controller", "guide.md")
+        end
+
+        private
+
+        def read_file(path)
+          path && File.exist?(path) ? File.read(path) : ""
+        end
+
+        def component_guide_path
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers").gem_dir
+          File.join(gem_dir, "docs/guide.md")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-rails/docs/guide.md", __dir__)
+        end
+
+        def tailwind_guide_path
+          gem_dir = Gem::Specification.find_by_name("stimulus_plumbers_tailwind").gem_dir
+          File.join(gem_dir, "docs/guide.md")
+        rescue Gem::MissingSpecError
+          File.expand_path("../../../../../stimulus-plumbers-tailwind/docs/guide.md", __dir__)
+        end
       end
     end
   end

data/lib/stimulus_plumbers/mcp/loaders/icons_loader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class IconsLoader
+      class << self
+        def call
+          heroicon_dir = Themes::Tailwind::Icons::Heroicon.send(:svg_dir)
+          custom_dir   = Themes::Tailwind::Icons::Custom.send(:svg_dir)
+
+          (outline_names(heroicon_dir) + solid_names(heroicon_dir) + custom_names(custom_dir) + alias_names).uniq.sort
+        end
+
+        private
+
+        def outline_names(heroicon_dir)
+          Dir[File.join(heroicon_dir, "outline", "*.svg")].map { |f| File.basename(f, ".svg") }
+        end
+
+        def solid_names(heroicon_dir)
+          Dir[File.join(heroicon_dir, "solid", "*.svg")].map { |f| "#{File.basename(f, ".svg")}/solid" }
+        end
+
+        def custom_names(custom_dir)
+          Dir[File.join(custom_dir, "*.svg")].map { |f| File.basename(f, ".svg") }
+        end
+
+        def alias_names
+          Themes::Tailwind::Icon::ALIASES.keys
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/support/docs_table_parser.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class DocsTableParser
+      class << self
+        def call(content)
+          tables = tables_with_headings(content)
+          { helpers: option_helpers(tables), slots: slot_methods(tables) }
+        end
+
+        # A standalone bold label (e.g. `**Time**`) between `#` headings is treated as a
+        # sub-heading, since some docs use one to introduce a table scoped to part of a
+        # section. It only labels the single table immediately following it — a fenced
+        # code block or a second table both clear it, so it can't leak onto later tables.
+        def tables_with_headings(content)
+          state = { heading: nil, subheading: nil, fenced: false, buffer: [], tables: [] }
+          content.each_line { |line| scan_line(line, state) }
+          flush_table(state)
+          state[:tables]
+        end
+
+        private
+
+        def option_helpers(tables)
+          tables.select { |t| t[:header].first == "Option" }
+                .filter_map do |t|
+                  options = t[:rows].map { |r| option_row(r) }
+                  { signature: t[:heading], options: options } unless options.empty?
+                end
+        end
+
+        def slot_methods(tables)
+          tables.select { |t| t[:header].first == "Slot method" }
+                .flat_map { |t| t[:rows].map { |r| slot_row(r) } }
+        end
+
+        def option_row(cells)
+          { option: clean(cells[0]), default: clean(cells[1]), description: cells[2].to_s }
+        end
+
+        def slot_row(cells)
+          slot = clean(cells[0])
+          description = cells[1].to_s
+          { slot: slot, description: description, block: block_required?(slot, description) }
+        end
+
+        def block_required?(slot, description)
+          slot.include?("{") || description.match?(%r{block required}i)
+        end
+
+        def scan_line(line, state)
+          if line.start_with?("```")
+            toggle_fence(state)
+          elsif state[:fenced]
+            nil
+          elsif (heading = line[%r{\A#+\s+(.+)}, 1])
+            set_heading(state, heading)
+          elsif (subheading = line[%r{\A\*\*([^*]+)\*\*}, 1])
+            set_subheading(state, subheading)
+          elsif line.lstrip.start_with?("|")
+            state[:buffer] << line
+          else
+            flush_table(state)
+          end
+        end
+
+        def toggle_fence(state)
+          flush_table(state)
+          state[:subheading] = nil
+          state[:fenced] = !state[:fenced]
+        end
+
+        def set_heading(state, heading)
+          flush_table(state)
+          state[:heading] = clean(heading)
+          state[:subheading] = nil
+        end
+
+        def set_subheading(state, subheading)
+          flush_table(state)
+          state[:subheading] = clean(subheading)
+        end
+
+        def flush_table(state)
+          return if state[:buffer].empty?
+
+          heading = [state[:heading], state[:subheading]].compact.join(" — ")
+          state[:tables] << build_table(state[:buffer]).merge(heading: heading)
+          state[:buffer] = []
+          state[:subheading] = nil
+        end
+
+        def build_table(lines)
+          rows = lines.map { |l| split_row(l) }.reject { |cells| cells.all? { |c| c.match?(%r{\A:?-+:?\z}) } }
+          { header: rows.first, rows: rows.drop(1) }
+        end
+
+        # Split a markdown table row, honouring escaped pipes (`\|`) inside cells.
+        def split_row(line)
+          line.strip.delete_prefix("|").delete_suffix("|")
+              .split(%r{(?<!\\)\|})
+              .map { |c| c.gsub('\|', "|").strip }
+        end
+
+        def clean(cell)
+          cell.to_s.gsub(%r{[`*]}, "").sub(%r{:\z}, "").strip
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/support/gem_vendor_path.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    # Path under the stimulus_plumbers gem's vendor/ dir (populated by bin/release),
+    # used by loaders as their `gem exec` fallback when there's no monorepo checkout.
+    module GemVendorPath
+      GEM_NAME = "stimulus_plumbers"
+
+      def self.resolve(*relative)
+        gem_dir = Gem::Specification.find_by_name(GEM_NAME).gem_dir
+        File.join(gem_dir, "vendor", *relative)
+      rescue Gem::MissingSpecError
+        nil
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/tailwind_loader.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class TailwindLoader
+      class << self
+        def call
+          theme = Themes::TailwindTheme.new
+
+          Themes::Base::SCHEMA.each_with_object({}) do |(key, params), result|
+            # Skip keys with no _classes method — calling resolve would trigger Logger.warn
+            next unless theme.respond_to?(:"#{key}_classes", true)
+
+            result[key] = component_classes(theme, key, params)
+          end
+        end
+
+        private
+
+        def component_classes(theme, key, params)
+          classes = { default: theme.resolve(key)[:classes].to_s }
+
+          params.each do |param, meta|
+            valid = meta[:validate]
+            next unless valid.respond_to?(:to_a)
+
+            valid.to_a.each { |val| classes["#{param}:#{val}"] = theme.resolve(key, param => val)[:classes].to_s }
+          end
+
+          classes
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/loaders/versions_loader.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    class VersionsLoader
+      class << self
+        def call
+          {
+            component_docs:    component_docs_source,
+            component_guide:   component_guide_source,
+            component_schema:  component_schema_source,
+            component_theme:   component_theme_source,
+
+            controller_docs:   controller_docs_source,
+            controller_guide:  controller_guide_source,
+            controller_schema: controller_schema_source,
+
+            icons:             icons_source,
+            tailwind:          tailwind_source,
+            tailwind_guide:    tailwind_guide_source
+          }
+        end
+
+        private
+
+        def gem_version(gem_name)
+          Gem::Specification.find_by_name(gem_name).version.to_s
+        rescue Gem::MissingSpecError
+          nil
+        end
+
+        def component_docs_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def component_guide_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def component_schema_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def component_theme_source
+          { version: gem_version("stimulus_plumbers") }
+        end
+
+        def controller_docs_source
+          dir = ControllerDocsLoader.docs_dir
+          return { version: nil, resolved_from: nil } unless dir && Dir.exist?(dir)
+
+          { version: npm_package_version(File.join(dir, "..", "..")), resolved_from: npm_docs_resolved_from(dir) }
+        end
+
+        def controller_guide_source
+          path = GuideLoader.controller_guide_path
+          return { version: nil, resolved_from: nil } unless path && File.exist?(path)
+
+          { version:       npm_package_version(File.join(File.dirname(path), "..")),
+            resolved_from: npm_docs_resolved_from(path)
+}
+        end
+
+        def controller_schema_source
+          path = ControllerSchemaLoader.resolved_path
+          return { version: nil, resolved_from: nil } unless path
+
+          { version:       npm_package_version(File.join(File.dirname(path), "..")),
+            resolved_from: controller_schema_resolved_from(path)
+}
+        end
+
+        def controller_schema_resolved_from(path)
+          case path
+          when %r{node_modules} then "node_modules"
+          when %r{vendor}       then "stimulus_plumbers gem vendor"
+          else "monorepo sibling dist/"
+          end
+        end
+
+        # Shared by controller_docs_source and controller_guide_source — both read from the same
+        # npm package's docs/ tree, dev sibling checkout vs vendored into the rails gem.
+        def npm_docs_resolved_from(path)
+          path.include?("vendor") ? "stimulus_plumbers gem vendor" : "monorepo sibling stimulus-plumbers/docs"
+        end
+
+        # package_root is the npm package's own directory — no package.json there means a vendored
+        # copy that didn't carry one along, so fall back to the wrapping gem's version.
+        def npm_package_version(package_root)
+          package_json = File.join(package_root, "package.json")
+          return gem_version("stimulus_plumbers") unless File.exist?(package_json)
+
+          JSON.parse(File.read(package_json))["version"]
+        end
+
+        def icons_source
+          { version: gem_version("stimulus_plumbers_tailwind") }
+        end
+
+        def tailwind_source
+          { version: gem_version("stimulus_plumbers_tailwind") }
+        end
+
+        def tailwind_guide_source
+          { version: gem_version("stimulus_plumbers_tailwind") }
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/aria.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class Aria < Base
+        class << self
+          def loader_key = :aria
+
+          def loader = AriaLoader
+
+          def static_resources
+            [
+              ::MCP::Resource.new(
+                uri:         "aria://reference",
+                name:        "aria-reference",
+                description: "WCAG 2.1 AA criteria, JS keyboard navigation patterns, and per-component ARIA " \
+                             "patterns for this library. For generic ARIA role/WCAG technique reference not " \
+                             "specific to this library, use the MDN MCP server (https://developer.mozilla.org/en-US/mcp)",
+                mime_type:   "text/markdown"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            return unless uri == "aria://reference"
+
+            text_resource(uri, "text/markdown", store[:aria])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_plumbers/mcp/plugins/base.rb

@@ -3,43 +3,52 @@
 module StimulusPlumbers
   module MCP
     module Plugins
-      # Shared contract + content helpers for plugins, which `extend` this.
-      #
-      # Each plugin defines: LOADER_KEY, LOADER, STATIC_RESOURCES,
-      # DYNAMIC_RESOURCE_TEMPLATES, and read(uri, store). Tools are optional —
-      # plugins with tools override register_tools, the rest inherit the no-op.
-      module Base
-        # Returned by a tool block to signal "not found" — rendered as an MCP
-        # error response with a structured { error: } payload (see text_tool).
+      # Plugin contract: required members raise NotImplementedError; optional members have defaults.
+      class Base
+        # Returned by a tool block to signal not-found (see text_tool).
         NotFound = Struct.new(:message)
 
-        def register_tools(_server, _store); end
+        class << self
+          def loader_key
+            raise NotImplementedError, "#{name} must define .loader_key"
+          end
 
-        def not_found(message)
-          NotFound.new(message)
-        end
+          def loader
+            raise NotImplementedError, "#{name} must define .loader"
+          end
 
-        # resources/read content for a JSON payload.
-        def json_resource(uri, data)
-          [{ uri: uri, mimeType: "application/json", text: JSON.generate(data) }]
-        end
+          def read(_uri, _store)
+            raise NotImplementedError, "#{name} must define .read"
+          end
 
-        # resources/read content for raw text (e.g. markdown).
-        def text_resource(uri, mime_type, text)
-          [{ uri: uri, mimeType: mime_type, text: text }]
-        end
+          def static_resources = []
+
+          def dynamic_resource_templates = []
+
+          def register_tools(_server, _store); end
+
+          def not_found(message)
+            NotFound.new(message)
+          end
+
+          def json_resource(uri, data)
+            [{ uri: uri, mimeType: "application/json", text: JSON.generate(data) }]
+          end
+
+          def text_resource(uri, mime_type, text)
+            [{ uri: uri, mimeType: mime_type, text: text }]
+          end
 
-        # Define a tool whose block returns the response text, or `not_found(msg)`
-        # for a uniform error (isError + { error: } JSON). Declaring `**args` makes
-        # the MCP gem inject :server_context, which tool blocks don't want — drop it.
-        def text_tool(server, name:, description:, input_schema: nil, &block)
-          server.define_tool(name: name, description: description, input_schema: input_schema) do |**args|
-            args.delete(:server_context)
-            result = block.call(**args)
-            if result.is_a?(NotFound)
-              ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(error: result.message) }], error: true)
-            else
-              ::MCP::Tool::Response.new([{ type: "text", text: result }])
+          # Declaring **args makes the MCP gem inject :server_context, which tool blocks don't want — drop it.
+          def text_tool(server, name:, description:, input_schema: nil, &block)
+            server.define_tool(name: name, description: description, input_schema: input_schema) do |**args|
+              args.delete(:server_context)
+              result = block.call(**args)
+              if result.is_a?(NotFound)
+                ::MCP::Tool::Response.new([{ type: "text", text: JSON.generate(error: result.message) }], error: true)
+              else
+                ::MCP::Tool::Response.new([{ type: "text", text: result }])
+              end
             end
           end
         end

data/lib/stimulus_plumbers/mcp/plugins/component_docs.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module StimulusPlumbers
+  module MCP
+    module Plugins
+      class ComponentDocs < Base
+        class << self
+          def loader_key = :component_docs
+
+          def loader = ComponentDocsLoader
+
+          def dynamic_resource_templates
+            [
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/docs",
+                name:         "component-docs",
+                description:  "Full markdown documentation and ERB examples for a component",
+                mime_type:    "text/markdown"
+              ),
+              ::MCP::ResourceTemplate.new(
+                uri_template: "component://{name}/helper",
+                name:         "component-helper",
+                description:  "Full sp_ helper option surface: keyword options with defaults and slot methods",
+                mime_type:    "application/json"
+              )
+            ].freeze
+          end
+
+          def read(uri, store)
+            docs = store[:component_docs]
+
+            case uri
+            when %r{\Acomponent://([^/]+)/docs\z}
+              doc = docs[Regexp.last_match(1).to_sym]
+              doc ? text_resource(uri, "text/markdown", doc[:content]) : missing(uri, Regexp.last_match(1))
+            when %r{\Acomponent://([^/]+)/helper\z}
+              doc = docs[Regexp.last_match(1).to_sym]
+              doc ? json_resource(uri, doc[:signature]) : missing(uri, Regexp.last_match(1))
+            end
+          end
+
+          def register_tools(server, store)
+            docs = store[:component_docs]
+
+            register_list_component_docs(server, docs)
+            register_get_component_examples(server, docs)
+            register_get_component_helper(server, docs)
+          end
+
+          private
+
+          def missing(uri, name)
+            json_resource(uri, { error: "no documentation for: #{name}" })
+          end
+
+          def register_list_component_docs(server, docs)
+            text_tool(
+              server,
+              name:        "list_component_docs",
+              description: "Lists components that have markdown docs (component://{name}/docs) and " \
+                           "helper signatures (component://{name}/helper)"
+            ) do
+              JSON.generate(docs.keys)
+            end
+          end
+
+          def register_get_component_examples(server, docs)
+            text_tool(
+              server,
+              name:         "get_component_examples",
+              description:  "Returns ERB usage examples for a component from the documentation",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              examples = docs[name.to_sym]&.dig(:examples) || []
+              examples.empty? ? not_found("no examples for: #{name}") : examples.join("\n\n")
+            end
+          end
+
+          def register_get_component_helper(server, docs)
+            text_tool(
+              server,
+              name:         "get_component_helper",
+              description:  "Returns the full sp_ helper surface for a component: keyword options with " \
+                            "defaults plus slot methods (e.g. icon_leading, card.with_action). For themed " \
+                            "params/controllers use get_component_schema",
+              input_schema: { properties: { name: { type: "string" } }, required: ["name"] }
+            ) do |name:|
+              doc = docs[name.to_sym]
+              doc ? JSON.generate(doc[:signature]) : not_found("no documentation for: #{name}")
+            end
+          end
+        end
+      end
+    end
+  end
+end