senren-ui 0.1.0

data/lib/senren/rails/registry.rb

@@ -0,0 +1,161 @@
+require 'yaml'
+
+module Senren
+  module Rails
+    # Loads, validates, and queries the Senren component registry.
+    #
+    #   reg = Senren::Rails::Registry.load!
+    #   reg.find("button")           # => Component struct
+    #   reg.dependencies("dialog")    # => [<button>]
+    #   reg.group("forms")            # => [<form>, <input>, ...]
+    class Registry
+      include Enumerable
+
+      REQUIRED_KEYS = %w[category client can_have_client files depends_on pairs_with variants accessibility ai].freeze
+      VALID_CATEGORIES = %w[actions forms overlays navigation layout data saas rich].freeze
+
+      Component = Struct.new(
+        :name, :category, :client, :can_have_client, :controller, :stub,
+        :files, :depends_on, :pairs_with, :variants, :accessibility,
+        :use_for, :avoid,
+        keyword_init: true
+      ) do
+        def stub? = stub == true
+        def client? = client == true
+
+        def to_h_full
+          to_h.merge(stub: stub?, client: client?)
+        end
+      end
+
+      attr_reader :components, :groups, :recipes
+
+      def self.load!(
+        components_path: Senren::Rails.registry_path,
+        groups_path:     Senren::Rails.groups_path,
+        recipes_path:    Senren::Rails.recipes_path
+      )
+        new(
+          YAML.safe_load_file(components_path, aliases: false),
+          YAML.safe_load_file(groups_path, aliases: false),
+          YAML.safe_load_file(recipes_path, aliases: false)
+        ).tap(&:validate!)
+      end
+
+      def initialize(components_yaml, groups_yaml, recipes_yaml)
+        @components = parse_components(components_yaml)
+        @groups     = (groups_yaml || {}).fetch('groups', [])
+        @recipes    = (recipes_yaml || {}).fetch('recipes', {})
+      end
+
+      def find(name)
+        @components[name.to_s]
+      end
+
+      def fetch(name)
+        find(name) or raise ArgumentError, "Unknown component: #{name.inspect}. " \
+                                           "Known: #{@components.keys.sort.join(', ')}"
+      end
+
+      def all
+        @components.values
+      end
+
+      def each(&block)
+        all.each(&block)
+      end
+
+      def find_each(&block)
+        each(&block)
+      end
+
+      def names
+        @components.keys
+      end
+
+      def group(category_id)
+        @components.values.select { |c| c.category == category_id.to_s }
+      end
+
+      def recipe(id)
+        @recipes.fetch(id.to_s) { raise ArgumentError, "Unknown recipe: #{id}" }
+      end
+
+      # Returns the transitive dependency closure for one or more components,
+      # in install order (deps first), de-duplicated.
+      def dependencies(*requested)
+        requested = requested.flatten.map(&:to_s)
+        result = []
+        visiting = []
+
+        visit = lambda do |name|
+          return if result.include?(name)
+          raise "Circular dependency: #{(visiting + [name]).join(' -> ')}" if visiting.include?(name)
+
+          visiting << name
+          comp = fetch(name)
+          comp.depends_on.each { |dep| visit.call(dep) }
+          visiting.pop
+          result << name
+        end
+
+        requested.each { |name| visit.call(name) }
+        result
+      end
+
+      def validate!
+        errors = []
+
+        validate_components(errors)
+        validate_recipes(errors)
+
+        raise "Registry validation failed:\n - #{errors.join("\n - ")}" if errors.any?
+
+        self
+      end
+
+      private
+
+      def validate_components(errors)
+        @components.each do |name, comp|
+          errors << "#{name}: invalid category #{comp.category.inspect}" unless VALID_CATEGORIES.include?(comp.category)
+          comp.depends_on.each do |dep|
+            errors << "#{name}: depends_on unknown component #{dep.inspect}" unless @components.key?(dep)
+          end
+          errors << "#{name}: client=true but can_have_client=false" if comp.client && !comp.can_have_client
+          errors << "#{name}: client=true requires a controller identifier" if comp.client && comp.controller.nil?
+        end
+      end
+
+      def validate_recipes(errors)
+        @recipes.each do |id, recipe|
+          recipe.fetch('components', []).each do |component|
+            errors << "recipe #{id}: unknown component #{component.inspect}" unless @components.key?(component)
+          end
+        end
+      end
+
+      def parse_components(yaml)
+        raw = (yaml || {}).fetch('components', {})
+        raw.each_with_object({}) do |(name, data), hash|
+          ai = data.fetch('ai', {})
+          hash[name] = Component.new(
+            name: name,
+            category: data.fetch('category'),
+            client: data.fetch('client', false),
+            can_have_client: data.fetch('can_have_client', false),
+            controller: data['controller'],
+            stub: data.fetch('stub', false),
+            files: Array(data['files']),
+            depends_on: Array(data['depends_on']),
+            pairs_with: Array(data['pairs_with']),
+            variants: Array(data['variants']),
+            accessibility: Array(data['accessibility']),
+            use_for: Array(ai['use_for']),
+            avoid: Array(ai['avoid'])
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/lib/senren/rails/skill_writer.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Senren
+  module Rails
+    # Writes the centralized .senren/skill.md file for AI agents.
+    #
+    # The file contains a generated region delimited by HTML comments:
+    #
+    #   <!-- senren:skill:start -->
+    #   ...generated by SkillWriter...
+    #   <!-- senren:skill:end -->
+    #
+    # Anything outside that region is preserved across regeneration.
+    class SkillWriter
+      START_MARKER = '<!-- senren:skill:start -->'
+      END_MARKER   = '<!-- senren:skill:end -->'
+
+      GROUP_ORDER = %w[actions forms overlays navigation layout data saas rich].freeze
+
+      attr_reader :registry, :paths
+
+      def initialize(registry: Registry.load!, paths: HostPaths.new)
+        @registry = registry
+        @paths    = paths
+      end
+
+      def sync!
+        installed = installed_names
+        body = render(installed)
+
+        paths.senren_dir.mkpath
+        existing = paths.skill_file.exist? ? paths.skill_file.read : default_outer_template
+
+        new_content = inject(existing, body)
+        paths.skill_file.write(new_content)
+        paths.skill_file
+      end
+
+      private
+
+      def installed_names
+        path = paths.installed_components
+        return [] unless path.exist?
+
+        ledger = YAML.safe_load_file(path) || {}
+        Array(ledger['installed']).filter_map { |e| e['name'] }.uniq
+      end
+
+      def render(installed_names)
+        if installed_names.empty?
+          return '_No Senren components installed yet. Run `bin/rails senren:add <name>...` to install components._'
+        end
+
+        lines = []
+        installed = installed_names.filter_map { |n| registry.find(n) }
+
+        registry.groups.each do |group|
+          gid = group['id']
+          comps = installed.select { |c| c.category == gid }
+          next if comps.empty?
+
+          lines << "## #{group['title']}"
+          lines << ''
+          lines << group['description'].to_s
+          lines << ''
+          comps.sort_by(&:name).each { |c| lines << render_component(c) }
+        end
+
+        lines.join("\n")
+      end
+
+      def render_component(comp)
+        out = []
+        out << "### Component: #{humanize(comp.name)}"
+        out << ''
+        out << "- **Category**: #{comp.category}"
+        out << "- **Stub**: #{comp.stub? ? 'yes (placeholder)' : 'no'}"
+        out << "- **Client behavior**: #{client_summary(comp)}"
+        out << "- **Depends on**: #{format_list(comp.depends_on)}"
+        out << "- **Pairs with**: #{format_list(comp.pairs_with)}"
+        out << "- **Variants**: #{format_list(comp.variants)}"
+        out << ''
+        out << '**Use for**:'
+        comp.use_for.each { |u| out << "- #{u}" }
+        out << ''
+        out << '**Avoid**:'
+        comp.avoid.each { |a| out << "- #{a}" }
+        out << ''
+        out << '**Accessibility**:'
+        comp.accessibility.each { |a| out << "- #{a}" }
+        out << ''
+        out << '**Rails usage**:'
+        out << ''
+        out << '```erb'
+        out << render_usage_example(comp)
+        out << '```'
+        out << ''
+        "#{out.join("\n")}\n"
+      end
+
+      def render_usage_example(comp)
+        ruby_class = "Senren::#{ruby_class_for(comp.name)}Component"
+        if comp.variants.any?
+          variant = comp.variants.first
+          %(<%= render #{ruby_class}.new(variant: :#{variant}) do %>\n  ...\n<% end %>)
+        else
+          %(<%= render #{ruby_class}.new do %>\n  ...\n<% end %>)
+        end
+      end
+
+      def client_summary(comp)
+        return 'none' unless comp.client?
+
+        path = "app/javascript/controllers/senren/#{comp.name}_controller.js"
+        "Stimulus `#{comp.controller}` (`#{path}`)"
+      end
+
+      def format_list(items)
+        return '_none_' if items.empty?
+
+        items.map { |i| "`#{i}`" }.join(', ')
+      end
+
+      def humanize(name)
+        name.split('_').map { |w| w[0].upcase + w[1..] }.join
+      end
+
+      def ruby_class_for(name)
+        humanize(name)
+      end
+
+      def inject(existing, generated_body)
+        if existing.include?(START_MARKER) && existing.include?(END_MARKER)
+          before = existing.split(START_MARKER, 2).first
+          after  = existing.split(END_MARKER, 2).last
+          "#{before}#{START_MARKER}\n\n#{generated_body}\n\n#{END_MARKER}#{after}"
+        else
+          "#{existing.rstrip}\n\n#{START_MARKER}\n\n#{generated_body}\n\n#{END_MARKER}\n"
+        end
+      end
+
+      def default_outer_template
+        <<~MD
+          # Senren Skill File
+
+          This file is the central guide for AI coding agents working in this app.
+
+          ## Hard Rules
+
+          - Use Senren components before writing custom HTML.
+          - Use ViewComponent for reusable UI; Turbo for server state; Stimulus for local behavior only.
+          - Do not introduce React, Vue, Alpine, or any external state framework.
+          - Do not hard-code colors; use semantic Tailwind tokens like `bg-background`, `text-foreground`, `bg-primary`.
+
+          ## Installed Components
+
+          The block between the markers below is generated by `bin/rails senren:skill:sync`.
+          Do not edit the generated region by hand. You may add notes outside the markers.
+
+        MD
+      end
+    end
+  end
+end

data/lib/senren/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Senren
+  module Rails
+    VERSION = '0.1.0'
+  end
+end

data/lib/senren/rails.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'senren/rails/version'
+
+module Senren
+  module Rails
+    GEM_ROOT = File.expand_path('../..', __dir__).freeze
+
+    autoload :Registry,         'senren/rails/registry'
+    autoload :ComponentCopier,  'senren/rails/component_copier'
+    autoload :SkillWriter,      'senren/rails/skill_writer'
+    autoload :LlmsWriter,       'senren/rails/llms_writer'
+    autoload :Installer,        'senren/rails/installer'
+    autoload :Doctor,           'senren/rails/doctor'
+    autoload :HostPaths,        'senren/rails/host_paths'
+
+    def self.gem_root
+      GEM_ROOT
+    end
+
+    def self.registry_path
+      File.join(GEM_ROOT, 'registry', 'components.yml')
+    end
+
+    def self.groups_path
+      File.join(GEM_ROOT, 'registry', 'groups.yml')
+    end
+
+    def self.recipes_path
+      File.join(GEM_ROOT, 'registry', 'recipes.yml')
+    end
+
+    def self.templates_root
+      File.join(GEM_ROOT, 'templates')
+    end
+  end
+end
+
+require 'senren/rails/engine' if defined?(Rails::Engine)

data/lib/tasks/senren.rake

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'senren/rails'
+
+namespace :senren do
+  desc 'Install one or more Senren components: rake senren:add[button,dialog] or bin/rails senren:add button dialog'
+  task :add, [:names] => :environment do |_t, args|
+    names = parse_names(args)
+    options = parse_options
+    abort 'Usage: bin/rails senren:add NAME [NAME...] [--client | --no-client]' if names.empty?
+
+    paths    = Senren::Rails::HostPaths.new
+    registry = Senren::Rails::Registry.load!
+    copier   = Senren::Rails::ComponentCopier.new(registry: registry, paths: paths)
+
+    installed = copier.install(names, client_override: options[:client_override], force: options[:force])
+
+    Senren::Rails::SkillWriter.new(registry: registry, paths: paths).sync!
+    Senren::Rails::LlmsWriter.new(registry: registry, paths: paths).generate!
+
+    puts "Installed: #{installed.join(', ')}"
+  end
+
+  namespace :skill do
+    desc 'Rebuild .senren/skill.md from the registry and installed_components ledger.'
+    task sync: :environment do
+      paths    = Senren::Rails::HostPaths.new
+      registry = Senren::Rails::Registry.load!
+      file = Senren::Rails::SkillWriter.new(registry: registry, paths: paths).sync!
+      puts "Wrote #{file}"
+    end
+  end
+
+  namespace :llms do
+    desc 'Regenerate public/llms.txt and public/llms-full.txt.'
+    task generate: :environment do
+      paths    = Senren::Rails::HostPaths.new
+      registry = Senren::Rails::Registry.load!
+      files = Senren::Rails::LlmsWriter.new(registry: registry, paths: paths).generate!
+      files.each { |f| puts "Wrote #{f}" }
+    end
+  end
+
+  desc "Run health checks against the host app's Senren installation."
+  task doctor: :environment do
+    ok = Senren::Rails::Doctor.new(paths: Senren::Rails::HostPaths.new).run!
+    exit(1) unless ok
+  end
+end
+
+# Helpers ---------------------------------------------------------------
+
+def parse_names(args)
+  raw = []
+  raw.concat(args.extras)
+  raw << args[:names] if args[:names]
+  raw.concat(ARGV.drop_while { |a| !a.start_with?('senren:') }.drop(1))
+  raw
+    .flatten
+    .flat_map { |s| s.to_s.split(/[,\s]+/) }
+    .reject { |s| s.empty? || s.start_with?('-') }
+    .uniq
+end
+
+def parse_options
+  client_override =
+    if ARGV.include?('--client')
+      true
+    elsif ARGV.include?('--no-client')
+      false
+    end
+
+  { client_override: client_override, force: ARGV.include?('--force') }
+end