senren-ui 0.1.4 → 0.1.6

data/lib/generators/senren/install/templates/base_component.rb.tt

@@ -1,3 +1,6 @@
+require 'uri'
+require 'view_component'
+
 module Senren
   # Base class for every Senren ViewComponent.
   #
@@ -6,13 +9,16 @@ module Senren
   # - variant and size resolution against class-level constants
   # - small class merger (no external `tailwind_merge` dependency in v0.1)
   # - a default root-attribute helper that emits `data-senren-component="<name>"`
-  class BaseComponent < ViewComponent::Base
-    VARIANTS = { default: "" }.freeze
-    SIZES    = { md: "" }.freeze
+  class BaseComponent < ::ViewComponent::Base
+    VARIANTS = { default: '' }.freeze
+    SIZES    = { md: '' }.freeze
+    SAFE_URL_PROTOCOLS = %w[http https mailto tel].freeze
+    SAFE_MEDIA_URL_PROTOCOLS = %w[http https].freeze
 
     attr_reader :class_name, :variant, :size, :html_attrs
 
     def initialize(variant: :default, size: :md, class_name: nil, **html_attrs)
+      super()
       @variant = resolve!(variant, self.class::VARIANTS, :variant)
       @size    = resolve!(size,    self.class::SIZES,    :size)
       @class_name = class_name
@@ -22,24 +28,51 @@ module Senren
     # Compose final root attributes; subclasses pass their base classes.
     def root_attrs(*classes, **extra)
       data = (extra.delete(:data) || {}).merge(senren_component: senren_component_name)
-      tag_class = merge_classes(classes, self.class::VARIANTS[@variant], self.class::SIZES[@size], @class_name, extra.delete(:class))
+      tag_class = merge_classes(
+        classes,
+        self.class::VARIANTS[@variant],
+        self.class::SIZES[@size],
+        @class_name,
+        extra.delete(:class)
+      )
       { class: tag_class, data: data, **html_attrs, **extra }
     end
 
     def senren_component_name
-      self.class.name.to_s.sub(/^Senren::/, "").sub(/Component$/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      self.class.name.to_s.sub(/^Senren::/, '').sub(/Component$/, '').gsub(/([a-z])([A-Z])/, '\1_\2').downcase
     end
 
     private
 
+    def safe_url(value, fallback: '#', protocols: SAFE_URL_PROTOCOLS)
+      url = value.to_s.strip
+      return fallback if url.empty?
+      return url if url.start_with?('#')
+      return url if url.start_with?('/') && !url.start_with?('//')
+
+      uri = URI.parse(url)
+      return url if uri.scheme && Array(protocols).map(&:to_s).include?(uri.scheme.downcase)
+      return fallback if uri.host
+      return url unless uri.scheme
+
+      fallback
+    rescue URI::InvalidURIError
+      fallback
+    end
+
+    def safe_media_url(value, fallback: nil)
+      safe_url(value, fallback: fallback, protocols: SAFE_MEDIA_URL_PROTOCOLS)
+    end
+
     def resolve!(value, table, label)
       key = value.to_sym
       return key if table.key?(key)
+
       raise ArgumentError, "Unknown #{label}: #{value.inspect}. Allowed: #{table.keys.join(', ')}"
     end
 
     def merge_classes(*sources)
-      sources.flatten.map { |s| s.to_s.strip }.reject(&:empty?).join(" ")
+      sources.flatten.map { |s| s.to_s.strip }.reject(&:empty?).join(' ')
     end
   end
 end

data/lib/generators/senren/install/templates/conventions.md.tt

@@ -20,11 +20,11 @@ and obey it strictly.
    block to `.new`, **not** to `render`, producing an empty component.
    Use either of these forms instead:
    ```erb
-   <%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
+   <%%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
 
-   <%= render Senren::ButtonComponent.new(variant: :primary) do %>
+   <%%= render Senren::ButtonComponent.new(variant: :primary) do %>
      Save
-   <% end %>
+   <%% end %>
    ```
 
 ## File ownership
@@ -38,15 +38,22 @@ and obey it strictly.
 | `.senren/registry.yml`              | Generator (mirror of gem registry) |
 | `.senren/installed_components.yml`  | Generator (ledger)  |
 | `.senren/conventions.md`            | This file - safe to edit |
-| `public/llms.txt`                   | Generator (do not edit) |
-| `public/llms-full.txt`              | Generator (do not edit) |
+| `.senren/agent-rules.md`            | Generator (do not edit) |
+| `AGENTS.md`                         | Generated region only (between markers) |
+| `CLAUDE.md`                         | Generated region only (between markers) |
+| `.github/copilot-instructions.md`   | Generated region only (between markers) |
+| `.cursor/rules/senren.mdc`          | Generated region only (between markers) |
 
 ## Adding a component
 
 ```bash
-bin/rails senren:add <name> [<name>...]
-bin/rails senren:add dialog --no-client     # override registry default
-bin/rails senren:add button --client        # override registry default
+bin/rails senren:add dialog
+bin/rails senren:add button card badge
+bin/rails senren:add dialog --no-client       # override registry default
+bundle exec rails senren:add button --client  # equivalent alternate entry point
+
+# Backward-compatible legacy task syntax:
+bin/rails 'senren:add[button,card,badge]'
 ```
 
 After install you can edit any file under `app/components/senren/` directly.
@@ -64,3 +71,10 @@ Senren never overwrites those files unless you pass `--force`.
 
 You can write app-specific notes outside those markers. They are preserved
 across `bin/rails senren:skill:sync`.
+
+## Agent instruction maintenance
+
+Senren writes a shared source file at `.senren/agent-rules.md` and syncs
+adapter files for Codex/Cursor/Claude/Copilot. For adapter files, only the
+generated block between markers is managed by Senren; your custom notes
+outside markers are preserved.

data/lib/senren/rails/agent_rules_writer.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Senren
+  module Rails
+    # Generates a single source-of-truth rules file plus adapter files for
+    # Copilot, Cursor, Claude, and Codex.
+    #
+    # Adapter files are marker-managed to avoid overwriting existing project
+    # instructions outside Senren's generated block.
+    class AgentRulesWriter
+      START_MARKER = '<!-- senren:agent:start -->'
+      END_MARKER   = '<!-- senren:agent:end -->'
+
+      attr_reader :registry, :paths
+
+      def initialize(registry: Registry.load!, paths: HostPaths.new)
+        @registry = registry
+        @paths    = paths
+      end
+
+      def sync!
+        paths.ensure_agent_dirs!
+        files = []
+        files << write_full_file(paths.agent_rules_file, render_source_rules)
+        files << write_adapter_file(paths.codex_agents_md, render_codex_adapter)
+        files << write_adapter_file(paths.claude_md, render_claude_adapter)
+        files << write_adapter_file(paths.copilot_instructions, render_copilot_adapter)
+        files << write_adapter_file(paths.cursor_rule_file, render_cursor_adapter, prefix: cursor_frontmatter)
+        files
+      end
+
+      private
+
+      def installed_names
+        path = paths.installed_components
+        return [] unless path.exist?
+
+        ledger = YAML.safe_load_file(path) || {}
+        Array(ledger['installed']).filter_map { |entry| registry.find(entry['name']) }.map(&:name).sort
+      end
+
+      def render_source_rules
+        names = installed_names
+        <<~MD
+          # Senren Agent Rules
+
+          Generated by senren-ui. Do not edit by hand.
+          Run `bin/rails senren:agents:sync` to regenerate.
+
+          This file is the Senren source of truth for AI coding agents in this app.
+
+          ## Hard Rules
+
+          - Use Senren components before writing custom HTML.
+          - Use ViewComponent for reusable UI.
+          - Use Turbo for server state.
+          - Use Stimulus only for local behavior.
+          - Do not introduce React, Vue, Alpine, or external state frameworks.
+          - Use semantic Tailwind tokens; do not hard-code color families.
+
+          ## Important Files
+
+          - `.senren/skill.md`                 - centralized component guidance
+          - `.senren/conventions.md`           - project conventions
+          - `.senren/registry.yml`             - component registry mirror
+          - `.senren/installed_components.yml` - local install ledger
+
+          ## Installed Components (#{names.size})
+
+          #{format_names(names)}
+        MD
+      end
+
+      def render_codex_adapter
+        <<~MD
+          ## Senren UI
+
+          Follow `.senren/agent-rules.md` as the source of truth.
+
+          - Prefer Senren components before custom HTML.
+          - Keep reusable UI in ViewComponent.
+          - Use Turbo for server state, Stimulus for local behavior.
+          - Do not add React, Vue, Alpine, or external state frameworks.
+          - Use semantic Tailwind tokens.
+        MD
+      end
+
+      def render_claude_adapter
+        <<~MD
+          ## Senren UI
+
+          @.senren/agent-rules.md
+
+          Apply Senren conventions and component-first rules from the imported file.
+        MD
+      end
+
+      def render_copilot_adapter
+        <<~MD
+          ## Senren UI
+
+          Use `.senren/agent-rules.md` as the source of truth for this repository.
+
+          - Prefer Senren components before custom HTML.
+          - Reusable UI must use ViewComponent.
+          - Turbo handles server state; Stimulus handles local behavior.
+          - Do not introduce React, Vue, Alpine, or external state frameworks.
+          - Use semantic Tailwind tokens.
+        MD
+      end
+
+      def render_cursor_adapter
+        <<~MD
+          ## Senren UI
+
+          Follow `.senren/agent-rules.md` as the source of truth.
+
+          - Prefer Senren components before custom HTML.
+          - Reusable UI uses ViewComponent.
+          - Turbo for server state, Stimulus for local behavior.
+          - No React/Vue/Alpine/external state frameworks.
+          - Use semantic Tailwind tokens.
+        MD
+      end
+
+      def cursor_frontmatter
+        <<~MDC
+          ---
+          description: Senren UI repository conventions
+          alwaysApply: true
+          ---
+        MDC
+      end
+
+      def format_names(names)
+        return '_No components installed yet._' if names.empty?
+
+        names.map { |name| "- #{name}" }.join("\n")
+      end
+
+      def write_full_file(path, content)
+        atomic_write(path, content)
+        path
+      end
+
+      def write_adapter_file(path, generated, prefix: '')
+        existing = path.exist? ? path.read : prefix.to_s
+        updated = inject(existing, generated)
+        atomic_write(path, updated)
+        path
+      end
+
+      def inject(existing, generated)
+        if existing.include?(START_MARKER) && existing.include?(END_MARKER)
+          before = existing.split(START_MARKER, 2).first
+          tail = existing.split(START_MARKER, 2).last
+          after = tail.split(END_MARKER, 2).last
+          "#{before}#{START_MARKER}\n\n#{generated.rstrip}\n\n#{END_MARKER}#{after}"
+        else
+          body = existing.rstrip
+          prefix = body.empty? ? '' : "#{body}\n\n"
+          "#{prefix}#{START_MARKER}\n\n#{generated.rstrip}\n\n#{END_MARKER}\n"
+        end
+      end
+
+      def atomic_write(path, content)
+        tmp = "#{path}.tmp"
+        File.write(tmp, content)
+        File.rename(tmp, path)
+      end
+    end
+  end
+end

data/lib/senren/rails/component_copier.rb

@@ -9,6 +9,47 @@ module Senren
     # Copies component files from the gem's templates/ tree into the host
     # Rails app, and updates .senren/installed_components.yml.
     class ComponentCopier
+      class MissingTemplate < StandardError; end
+
+      INSTALL_GENERATOR_TEMPLATES = File.expand_path(
+        '../../generators/senren/install/templates', __dir__
+      ).freeze
+      BASE_COMPONENT_TEMPLATE = File.join(INSTALL_GENERATOR_TEMPLATES, 'base_component.rb.tt').freeze
+      BASE_URL_HELPER_PATCH = <<~RUBY
+
+        # Added by senren:add for compatibility with URL-aware component templates.
+        require 'uri'
+
+        module Senren
+          class BaseComponent
+            SAFE_URL_PROTOCOLS = %w[http https mailto tel].freeze unless const_defined?(:SAFE_URL_PROTOCOLS)
+            SAFE_MEDIA_URL_PROTOCOLS = %w[http https].freeze unless const_defined?(:SAFE_MEDIA_URL_PROTOCOLS)
+
+            private
+
+            def safe_url(value, fallback: '#', protocols: SAFE_URL_PROTOCOLS)
+              url = value.to_s.strip
+              return fallback if url.empty?
+              return url if url.start_with?('#')
+              return url if url.start_with?('/') && !url.start_with?('//')
+
+              uri = URI.parse(url)
+              return url if uri.scheme && Array(protocols).map(&:to_s).include?(uri.scheme.downcase)
+              return fallback if uri.host
+              return url unless uri.scheme
+
+              fallback
+            rescue URI::InvalidURIError
+              fallback
+            end
+
+            def safe_media_url(value, fallback: nil)
+              safe_url(value, fallback: fallback, protocols: SAFE_MEDIA_URL_PROTOCOLS)
+            end
+          end
+        end
+      RUBY
+
       attr_reader :registry, :paths, :stdout
 
       def initialize(registry: Registry.load!, paths: HostPaths.new, stdout: $stdout)
@@ -22,6 +63,7 @@ module Senren
       def install(component_names, client_override: nil, force: false)
         wanted = registry.dependencies(*component_names)
         paths.ensure_dirs!
+        ensure_base_component_url_helpers!
 
         wanted.each do |name|
           comp = registry.fetch(name)
@@ -34,6 +76,24 @@ module Senren
 
       private
 
+      def ensure_base_component_url_helpers!
+        if paths.base_component_path.exist?
+          return if base_component_has_url_helpers?
+
+          File.open(paths.base_component_path, 'a') { |file| file.write(BASE_URL_HELPER_PATCH) }
+          stdout.puts "  update #{paths.base_component_path} (url helpers)"
+          return
+        end
+
+        copy_file(BASE_COMPONENT_TEMPLATE, paths.base_component_path, force: false, label: 'base_component.rb')
+      end
+
+      def base_component_has_url_helpers?
+        source = paths.base_component_path.read
+
+        source.include?('def safe_url') && source.include?('def safe_media_url')
+      end
+
       def install_component(comp, client_override:, force:)
         effective_client = effective_client_for(comp, client_override)
 
@@ -59,20 +119,29 @@ module Senren
         # app/components/senren/<name>_component.html.erb     -> templates/components/<name>/<name>_component.html.erb
         # app/javascript/controllers/senren/<name>_controller.js -> templates/controllers/<name>_controller.js
         base = File.basename(relative)
-        if relative.include?('app/components/senren/')
+        if component_source_path?(comp, relative)
           File.join(Senren::Rails.templates_root, 'components', comp.name, base)
-        elsif relative.include?('app/javascript/controllers/senren/')
+        elsif controller_source_path?(comp, relative)
           File.join(Senren::Rails.templates_root, 'controllers', base)
         else
           raise "ComponentCopier: do not know how to map #{relative.inspect}"
         end
       end
 
+      def component_source_path?(comp, relative)
+        [
+          "app/components/senren/#{comp.name}_component.rb",
+          "app/components/senren/#{comp.name}_component.html.erb"
+        ].include?(relative)
+      end
+
+      def controller_source_path?(comp, relative)
+        relative == "app/javascript/controllers/senren/#{comp.name}_controller.js"
+      end
+
       def copy_file(src, dest, force:, label:)
-        unless File.exist?(src)
-          stdout.puts "  warn  missing template: #{src} (#{label})"
-          return
-        end
+        raise MissingTemplate, "Missing component template: #{src} (#{label})" unless File.exist?(src)
+
         if File.exist?(dest) && !force
           stdout.puts "  skip  #{dest} (already exists)"
           return

data/lib/senren/rails/component_installer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'senren/rails/agent_rules_writer'
+require 'senren/rails/component_copier'
+require 'senren/rails/host_paths'
+require 'senren/rails/registry'
+require 'senren/rails/skill_writer'
+
+module Senren
+  module Rails
+    # Installs one or more registered Senren components into the host app and
+    # refreshes the generated guidance files afterward.
+    class ComponentInstaller
+      USAGE = 'Usage: bin/rails senren:add NAME [NAME...] [--client | --no-client]'
+
+      attr_reader :registry, :paths, :stdout
+
+      def self.normalize_names(names)
+        Array(names)
+          .flatten
+          .flat_map { |entry| entry.to_s.split(/[,\s]+/) }
+          .reject { |entry| entry.empty? || entry.start_with?('-') }
+          .uniq
+      end
+
+      def initialize(registry: Registry.load!, paths: HostPaths.new, stdout: $stdout)
+        @registry = registry
+        @paths    = paths
+        @stdout   = stdout
+      end
+
+      def install(names:, client_override: nil, force: false)
+        normalized_names = self.class.normalize_names(names)
+        raise ArgumentError, USAGE if normalized_names.empty?
+
+        installed = ComponentCopier.new(registry: registry, paths: paths, stdout: stdout)
+                                   .install(normalized_names, client_override: client_override, force: force)
+
+        SkillWriter.new(registry: registry, paths: paths).sync!
+        AgentRulesWriter.new(registry: registry, paths: paths).sync!
+
+        stdout.puts "Installed: #{installed.join(', ')}"
+        installed
+      end
+    end
+  end
+end

data/lib/senren/rails/doctor.rb

@@ -17,19 +17,7 @@ module Senren
       end
 
       def run!
-        results = []
-        results << check('ViewComponent gem available')           { defined?(::ViewComponent) }
-        results << check('TailwindCSS stylesheet present')        { paths.stylesheet_path.exist? }
-        results << check('Stimulus directory present')            { paths.stimulus_dir.directory? }
-        results << check('Turbo gem available')                   { defined?(::Turbo) || gem_loadable?('turbo-rails') }
-        results << check('.senren directory exists')              { paths.senren_dir.directory? }
-        results << check('.senren/skill.md exists')               { paths.skill_file.file? }
-        results << check('.senren/registry.yml exists')           { paths.registry_mirror.file? }
-        results << check('.senren/installed_components.yml exists') { paths.installed_components.file? }
-        results << check('public/llms.txt exists')                { paths.llms_short.file? }
-        results << check('public/llms-full.txt exists')           { paths.llms_full.file? }
-        results << check('app/components/senren exists')          { paths.components_dir.directory? }
-        results << check('app/javascript/controllers/senren exists') { paths.stimulus_dir.directory? }
+        results = runtime_checks + installation_checks
         installed = installed_count
         results << Result.new("#{installed} component(s) installed", installed >= 0, nil)
 
@@ -57,6 +45,31 @@ module Senren
         false
       end
 
+      def runtime_checks
+        [
+          check('ViewComponent gem available')    { defined?(::ViewComponent) },
+          check('TailwindCSS stylesheet present') { paths.stylesheet_path.exist? },
+          check('Stimulus directory present')     { paths.stimulus_dir.directory? },
+          check('Turbo gem available')            { defined?(::Turbo) || gem_loadable?('turbo-rails') }
+        ]
+      end
+
+      def installation_checks
+        [
+          check('.senren directory exists')               { paths.senren_dir.directory? },
+          check('.senren/skill.md exists')                { paths.skill_file.file? },
+          check('.senren/registry.yml exists')            { paths.registry_mirror.file? },
+          check('.senren/installed_components.yml exists') { paths.installed_components.file? },
+          check('.senren/agent-rules.md exists')          { paths.agent_rules_file.file? },
+          check('AGENTS.md exists')                       { paths.codex_agents_md.file? },
+          check('CLAUDE.md exists')                       { paths.claude_md.file? },
+          check('.github/copilot-instructions.md exists') { paths.copilot_instructions.file? },
+          check('.cursor/rules/senren.mdc exists')        { paths.cursor_rule_file.file? },
+          check('app/components/senren exists')           { paths.components_dir.directory? },
+          check('app/javascript/controllers/senren exists') { paths.stimulus_dir.directory? }
+        ]
+      end
+
       def installed_count
         return 0 unless paths.installed_components.file?
 

data/lib/senren/rails/host_paths.rb

@@ -16,6 +16,7 @@ module Senren
       def registry_mirror       = senren_dir.join('registry.yml')
       def installed_components  = senren_dir.join('installed_components.yml')
       def conventions_file      = senren_dir.join('conventions.md')
+      def agent_rules_file      = senren_dir.join('agent-rules.md')
 
       def components_dir        = root.join('app', 'components', 'senren')
       def base_component_path   = components_dir.join('base_component.rb')
@@ -24,12 +25,20 @@ module Senren
 
       def stimulus_dir          = root.join('app', 'javascript', 'controllers', 'senren')
 
-      def llms_short            = root.join('public', 'llms.txt')
-      def llms_full             = root.join('public', 'llms-full.txt')
+      def github_dir            = root.join('.github')
+      def copilot_instructions  = github_dir.join('copilot-instructions.md')
+      def cursor_rules_dir      = root.join('.cursor', 'rules')
+      def cursor_rule_file      = cursor_rules_dir.join('senren.mdc')
+      def claude_md             = root.join('CLAUDE.md')
+      def codex_agents_md       = root.join('AGENTS.md')
 
       def ensure_dirs!
         [senren_dir, components_dir, stimulus_dir,
-         stylesheet_path.dirname, llms_short.dirname].each(&:mkpath)
+         stylesheet_path.dirname, github_dir, cursor_rules_dir].each(&:mkpath)
+      end
+
+      def ensure_agent_dirs!
+        [senren_dir, github_dir, cursor_rules_dir].each(&:mkpath)
       end
     end
   end

data/lib/senren/rails/installer.rb

@@ -5,7 +5,7 @@ require 'fileutils'
 module Senren
   module Rails
     # Idempotent installer that lays down the .senren directory, base
-    # component, stylesheet, and initial llms files. Reused by the install
+    # component, stylesheet, and agent instruction files. Reused by the install
     # generator and by ad-hoc rake task entry points.
     class Installer
       attr_reader :paths, :stdout
@@ -20,7 +20,7 @@ module Senren
         install_static_files(force: force)
         mirror_registry
         SkillWriter.new(paths: paths).sync!
-        LlmsWriter.new(paths: paths).generate!
+        AgentRulesWriter.new(paths: paths).sync!
         print_next_steps
         true
       end
@@ -73,6 +73,8 @@ module Senren
 
             bin/rails senren:add button card badge alert
             bin/rails senren:add dialog dropdown_menu
+            bundle exec rails senren:add form input textarea
+            bin/rails senren:agents:sync
             bin/rails senren:doctor
 
           Read .senren/skill.md and .senren/conventions.md to get oriented.