senren-ui 0.1.0

data/lib/generators/senren/install/templates/senren.css.tt

@@ -0,0 +1,164 @@
+/*
+ * Senren UI - Spring Garden tokens.
+ * HSL channels are written without hsl() wrapping so Tailwind utilities like
+ *   bg-[hsl(var(--senren-background))]
+ * can compose them with opacity modifiers.
+ *
+ * The palette is intentionally colorful: pond blue, sakura pink, young leaf
+ * green, iris violet, and warm paper. Components stay SaaS-practical while
+ * avoiding the black-and-white default UI look.
+ */
+
+:root {
+  --senren-background: 54 100% 97%;
+  --senren-foreground: 178 62% 12%;
+
+  --senren-muted: 83 54% 91%;
+  --senren-muted-foreground: 181 24% 34%;
+
+  --senren-card: 52 100% 99%;
+  --senren-card-foreground: 178 62% 12%;
+
+  --senren-popover: 52 100% 99%;
+  --senren-popover-foreground: 178 62% 12%;
+
+  --senren-border: 174 42% 78%;
+  --senren-input: 174 42% 78%;
+  --senren-ring: 196 86% 48%;
+
+  --senren-primary: 151 74% 29%;
+  --senren-primary-foreground: 58 100% 97%;
+
+  --senren-secondary: 334 95% 89%;
+  --senren-secondary-foreground: 178 56% 18%;
+
+  --senren-accent: 194 86% 82%;
+  --senren-accent-foreground: 188 72% 18%;
+
+  --senren-destructive: 350 78% 55%;
+  --senren-destructive-foreground: 54 100% 97%;
+
+  --senren-success: 132 52% 37%;
+  --senren-success-foreground: 54 100% 97%;
+
+  --senren-warning: 44 92% 61%;
+  --senren-warning-foreground: 38 58% 16%;
+
+  --senren-radius: 0.5rem;
+
+  --senren-palette-sky: 202 88% 44%;
+  --senren-palette-sakura: 334 95% 89%;
+  --senren-palette-pond: 194 86% 82%;
+  --senren-palette-leaf: 88 58% 57%;
+  --senren-palette-iris: 255 70% 80%;
+  --senren-palette-paper: 54 100% 97%;
+}
+
+.dark {
+  --senren-background: 202 58% 9%;
+  --senren-foreground: 54 100% 94%;
+
+  --senren-muted: 188 34% 17%;
+  --senren-muted-foreground: 174 28% 72%;
+
+  --senren-card: 199 50% 13%;
+  --senren-card-foreground: 54 100% 94%;
+
+  --senren-popover: 199 50% 13%;
+  --senren-popover-foreground: 54 100% 94%;
+
+  --senren-border: 188 31% 25%;
+  --senren-input: 188 31% 25%;
+  --senren-ring: 194 86% 72%;
+
+  --senren-primary: 132 55% 66%;
+  --senren-primary-foreground: 166 62% 10%;
+
+  --senren-secondary: 334 74% 74%;
+  --senren-secondary-foreground: 202 58% 9%;
+
+  --senren-accent: 194 76% 63%;
+  --senren-accent-foreground: 202 58% 9%;
+
+  --senren-destructive: 350 72% 62%;
+  --senren-destructive-foreground: 54 100% 97%;
+
+  --senren-success: 132 55% 66%;
+  --senren-success-foreground: 166 62% 10%;
+
+  --senren-warning: 44 92% 68%;
+  --senren-warning-foreground: 38 58% 16%;
+}
+
+/* Convenience aliases. Components prefer Tailwind semantic utilities, but raw HTML can use these. */
+.senren-bg          { background-color: hsl(var(--senren-background)); }
+.senren-fg          { color: hsl(var(--senren-foreground)); }
+.senren-border      { border-color: hsl(var(--senren-border)); }
+.senren-radius      { border-radius: var(--senren-radius); }
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] a {
+  color: hsl(var(--senren-primary));
+  cursor: pointer;
+  font-weight: 500;
+  text-decoration-line: underline;
+  text-decoration-thickness: 0.08em;
+  text-underline-offset: 0.18em;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] a:hover {
+  color: hsl(var(--senren-ring));
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] ul,
+[data-senren-component="rich_text_editor_lite"] [contenteditable] ol {
+  margin-block: 0.5rem;
+  padding-inline-start: 1.35rem;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] ul {
+  list-style: disc;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] ol {
+  list-style: decimal;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] li + li {
+  margin-top: 0.25rem;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] p + p {
+  margin-top: 0.5rem;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] h1,
+[data-senren-component="rich_text_editor_lite"] [contenteditable] h2,
+[data-senren-component="rich_text_editor_lite"] [contenteditable] h3 {
+  color: hsl(var(--senren-foreground));
+  font-weight: 700;
+  line-height: 1.2;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] h1 {
+  font-size: 1.5rem;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] h2 {
+  font-size: 1.25rem;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] h3 {
+  font-size: 1.125rem;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] :is(p, h1, h2, h3, li)[data-align="center"] {
+  text-align: center;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] :is(p, h1, h2, h3, li)[data-align="right"] {
+  text-align: right;
+}
+
+[data-senren-component="rich_text_editor_lite"] [contenteditable] :is(p, h1, h2, h3, li)[data-align="justify"] {
+  text-align: justify;
+}

data/lib/senren/rails/component_copier.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+require 'time'
+
+module Senren
+  module Rails
+    # Copies component files from the gem's templates/ tree into the host
+    # Rails app, and updates .senren/installed_components.yml.
+    class ComponentCopier
+      attr_reader :registry, :paths, :stdout
+
+      def initialize(registry: Registry.load!, paths: HostPaths.new, stdout: $stdout)
+        @registry = registry
+        @paths    = paths
+        @stdout   = stdout
+      end
+
+      # Installs a list of components (with deps), respecting the override flag.
+      # Returns the ordered list of component names actually installed.
+      def install(component_names, client_override: nil, force: false)
+        wanted = registry.dependencies(*component_names)
+        paths.ensure_dirs!
+
+        wanted.each do |name|
+          comp = registry.fetch(name)
+          install_component(comp, client_override: client_override, force: force)
+        end
+
+        update_installed_ledger(wanted, client_override: client_override)
+        wanted
+      end
+
+      private
+
+      def install_component(comp, client_override:, force:)
+        effective_client = effective_client_for(comp, client_override)
+
+        comp.files.each do |relative|
+          next if relative.include?('javascript/controllers') && !effective_client
+
+          src = source_for(comp, relative)
+          dest = paths.root.join(relative)
+          copy_file(src, dest, force: force, label: "#{comp.name}::#{File.basename(relative)}")
+        end
+      end
+
+      def effective_client_for(comp, override)
+        return comp.client? if override.nil?
+        return false unless comp.can_have_client
+
+        override
+      end
+
+      def source_for(comp, relative)
+        # Map host path back to gem template path.
+        # app/components/senren/<name>_component.rb           -> templates/components/<name>/<name>_component.rb
+        # 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/')
+          File.join(Senren::Rails.templates_root, 'components', comp.name, base)
+        elsif relative.include?('app/javascript/controllers/senren/')
+          File.join(Senren::Rails.templates_root, 'controllers', base)
+        else
+          raise "ComponentCopier: do not know how to map #{relative.inspect}"
+        end
+      end
+
+      def copy_file(src, dest, force:, label:)
+        unless File.exist?(src)
+          stdout.puts "  warn  missing template: #{src} (#{label})"
+          return
+        end
+        if File.exist?(dest) && !force
+          stdout.puts "  skip  #{dest} (already exists)"
+          return
+        end
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+        stdout.puts "  copy  #{dest}"
+      end
+
+      def update_installed_ledger(names, client_override:)
+        ledger_path = paths.installed_components
+        ledger = ledger_path.exist? ? (YAML.safe_load_file(ledger_path) || {}) : {}
+        installed = ledger['installed'] ||= []
+
+        names.each do |name|
+          existing = installed.find { |e| e['name'] == name }
+          attrs = {
+            'name' => name,
+            'version' => Senren::Rails::VERSION,
+            'installed_at' => Time.now.utc.iso8601,
+            'client' => effective_client_for(registry.fetch(name), client_override)
+          }
+          if existing
+            existing.merge!(attrs.except('installed_at'))
+          else
+            installed << attrs
+          end
+        end
+
+        installed.sort_by! { |e| e['name'] }
+        ledger_path.parent.mkpath
+        File.write(ledger_path, YAML.dump(ledger))
+      end
+    end
+  end
+end

data/lib/senren/rails/doctor.rb

@@ -0,0 +1,86 @@
+require 'yaml'
+
+module Senren
+  module Rails
+    # Runs a series of checks against the host Rails app and prints a
+    # human-readable status report.
+    class Doctor
+      Result = Struct.new(:label, :ok, :detail) do
+        def icon = ok ? '✓' : '✗'
+      end
+
+      attr_reader :paths, :stdout
+
+      def initialize(paths: HostPaths.new, stdout: $stdout)
+        @paths  = paths
+        @stdout = stdout
+      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? }
+        installed = installed_count
+        results << Result.new("#{installed} component(s) installed", installed >= 0, nil)
+
+        report(results)
+        results.all?(&:ok)
+      end
+
+      private
+
+      def check(label)
+        ok = false
+        detail = nil
+        begin
+          ok = !yield.nil?
+        rescue StandardError => e
+          detail = e.message
+        end
+        Result.new(label, ok, detail)
+      end
+
+      def gem_loadable?(name)
+        Gem::Specification.find_by_name(name)
+        true
+      rescue Gem::LoadError
+        false
+      end
+
+      def installed_count
+        return 0 unless paths.installed_components.file?
+
+        ledger = YAML.safe_load_file(paths.installed_components) || {}
+        Array(ledger['installed']).size
+      rescue StandardError
+        -1
+      end
+
+      def report(results)
+        stdout.puts 'Senren Doctor'
+        stdout.puts ''
+        results.each do |r|
+          line = "#{r.icon} #{r.label}"
+          line += "  -- #{r.detail}" if r.detail
+          stdout.puts line
+        end
+        stdout.puts ''
+        if results.all?(&:ok)
+          stdout.puts 'No issues found.'
+        else
+          stdout.puts 'Issues found. Resolve the items marked with ✗.'
+        end
+      end
+    end
+  end
+end

data/lib/senren/rails/engine.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module Senren
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Senren
+
+      initializer 'senren.rails.load_tasks' do |app|
+        rake_path = File.expand_path('../../tasks/senren.rake', __dir__)
+        app.paths['lib/tasks'] << rake_path if File.exist?(rake_path)
+      end
+    end
+  end
+end

data/lib/senren/rails/host_paths.rb

@@ -0,0 +1,36 @@
+require 'pathname'
+
+module Senren
+  module Rails
+    # Resolves canonical paths inside a host Rails application.
+    # Accepts an explicit root for tests; defaults to Rails.root when present.
+    class HostPaths
+      attr_reader :root
+
+      def initialize(root = nil)
+        @root = Pathname.new(root || ::Rails.root).expand_path
+      end
+
+      def senren_dir            = root.join('.senren')
+      def skill_file            = senren_dir.join('skill.md')
+      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 components_dir        = root.join('app', 'components', 'senren')
+      def base_component_path   = components_dir.join('base_component.rb')
+
+      def stylesheet_path       = root.join('app', 'assets', 'stylesheets', 'senren.css')
+
+      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 ensure_dirs!
+        [senren_dir, components_dir, stimulus_dir,
+         stylesheet_path.dirname, llms_short.dirname].each(&:mkpath)
+      end
+    end
+  end
+end

data/lib/senren/rails/installer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+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
+    # generator and by ad-hoc rake task entry points.
+    class Installer
+      attr_reader :paths, :stdout
+
+      def initialize(paths: HostPaths.new, stdout: $stdout)
+        @paths  = paths
+        @stdout = stdout
+      end
+
+      def run!(force: false)
+        paths.ensure_dirs!
+        install_static_files(force: force)
+        mirror_registry
+        SkillWriter.new(paths: paths).sync!
+        LlmsWriter.new(paths: paths).generate!
+        print_next_steps
+        true
+      end
+
+      INSTALL_GENERATOR_TEMPLATES = File.expand_path(
+        '../../generators/senren/install/templates', __dir__
+      ).freeze
+
+      STATIC_FILES = {
+        'conventions.md.tt' => :conventions_file,
+        'installed_components.yml.tt' => :installed_components,
+        'base_component.rb.tt' => :base_component_path,
+        'senren.css.tt' => :stylesheet_path
+      }.freeze
+
+      private
+
+      def install_static_files(force:)
+        STATIC_FILES.each do |template_basename, paths_method|
+          src = File.join(INSTALL_GENERATOR_TEMPLATES, template_basename)
+          dest = paths.public_send(paths_method)
+          copy_template(src, dest, force: force)
+        end
+      end
+
+      def copy_template(src, dest, force:)
+        unless File.exist?(src)
+          stdout.puts "  warn  template missing: #{src}"
+          return
+        end
+        if File.exist?(dest) && !force
+          stdout.puts "  skip  #{dest}"
+          return
+        end
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+        stdout.puts "  copy  #{dest}"
+      end
+
+      def mirror_registry
+        FileUtils.mkdir_p(paths.registry_mirror.dirname)
+        FileUtils.cp(Senren::Rails.registry_path, paths.registry_mirror)
+        stdout.puts "  mirror #{paths.registry_mirror}"
+      end
+
+      def print_next_steps
+        stdout.puts <<~MSG
+
+          Senren installed. Next steps:
+
+            bin/rails senren:add button card badge alert
+            bin/rails senren:add dialog dropdown_menu
+            bin/rails senren:doctor
+
+          Read .senren/skill.md and .senren/conventions.md to get oriented.
+        MSG
+      end
+    end
+  end
+end

data/lib/senren/rails/llms_writer.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Senren
+  module Rails
+    # Generates public/llms.txt and public/llms-full.txt for AI discoverability.
+    # The entire content of both files is owned by this writer; do not edit by hand.
+    class LlmsWriter
+      attr_reader :registry, :paths
+
+      def initialize(registry: Registry.load!, paths: HostPaths.new)
+        @registry = registry
+        @paths    = paths
+      end
+
+      def generate!
+        paths.llms_short.parent.mkpath
+        paths.llms_full.parent.mkpath
+        atomic_write(paths.llms_short, render_short)
+        atomic_write(paths.llms_full,  render_full)
+        [paths.llms_short, paths.llms_full]
+      end
+
+      private
+
+      def installed
+        path = paths.installed_components
+        return [] unless path.exist?
+
+        ledger = YAML.safe_load_file(path) || {}
+        Array(ledger['installed']).filter_map { |e| registry.find(e['name']) }
+      end
+
+      def render_short
+        names = installed.map(&:name).sort
+        <<~TXT
+          # Senren UI
+
+          Generated by senren-ui. Do not edit by hand. Run
+          `bin/rails senren:llms:generate` to regenerate.
+
+          Senren UI is the local Rails UI system used by this application.
+          Use `.senren/skill.md` as the primary AI Agent guide.
+
+          ## 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 any external state framework.
+          - Do not hard-code colors; use semantic Tailwind tokens.
+
+          ## Important Files
+
+          - `.senren/skill.md`              - centralized AI agent guide
+          - `.senren/registry.yml`          - mirror of installable components
+          - `.senren/installed_components.yml` - what is currently installed
+          - `.senren/conventions.md`        - Senren conventions for humans and agents
+
+          ## Installed Components (#{names.size})
+
+          #{names.map { |n| "- #{n}" }.join("\n")}
+        TXT
+      end
+
+      def render_full
+        comps = installed.sort_by(&:name)
+
+        out = []
+        out << '# Senren UI - Full Snapshot'
+        out << ''
+        out << 'Generated by senren-ui. Do not edit by hand. Run'
+        out << '`bin/rails senren:llms:generate` to regenerate.'
+        out << ''
+        out << '## Hard Rules'
+        out << ''
+        out << '- Use Senren components before writing custom HTML.'
+        out << '- Server-rendered HTML first; ViewComponent for reusable UI.'
+        out << '- Hotwire (Turbo + Stimulus) is the only client runtime.'
+        out << '- TailwindCSS with semantic tokens (`bg-background`, `text-foreground`, ...).'
+        out << '- Do not introduce React, Vue, Alpine, or external state frameworks.'
+        out << '- Components copied into `app/components/senren/` are owned by this app; edit them directly.'
+        out << ''
+        out << '## Installed Component Inventory'
+        out << ''
+
+        registry.groups.each do |group|
+          group_comps = comps.select { |c| c.category == group['id'] }
+          next if group_comps.empty?
+
+          out << "### #{group['title']}"
+          out << ''
+          out << group['description'].to_s
+          out << ''
+          group_comps.each { |c| out << render_component(c) }
+        end
+
+        out << '## Recipes'
+        out << ''
+        registry.recipes.each do |id, recipe|
+          out << "### #{id}"
+          out << ''
+          out << recipe['description'].to_s
+          out << ''
+          out << 'Components:'
+          recipe['components'].each { |c| out << "- #{c}" }
+          out << ''
+        end
+
+        out.join("\n")
+      end
+
+      def render_component(comp)
+        ruby_class = "Senren::#{comp.name.split('_').map { |w| w[0].upcase + w[1..] }.join}Component"
+        s = []
+        s << "#### #{comp.name}#{'  (stub)' if comp.stub?}"
+        s << ''
+        s << "Category: #{comp.category}.  " \
+             "Client: #{comp.client? ? "yes (#{comp.controller})" : 'no'}.  " \
+             "Variants: #{comp.variants.empty? ? 'none' : comp.variants.join(', ')}."
+        s << ''
+        s << "Use for: #{comp.use_for.join('; ')}." unless comp.use_for.empty?
+        s << "Avoid: #{comp.avoid.join('; ')}." unless comp.avoid.empty?
+        s << ''
+        s << 'Rails usage:'
+        s << ''
+        s << '```erb'
+        s << if comp.variants.any?
+               "<%= render #{ruby_class}.new(variant: :#{comp.variants.first}) do %>"
+             else
+               "<%= render #{ruby_class}.new do %>"
+             end
+        s << '  ...'
+        s << '<% end %>'
+        s << '```'
+        s << ''
+        s.join("\n")
+      end
+
+      def atomic_write(path, content)
+        tmp = "#{path}.tmp"
+        File.write(tmp, content)
+        File.rename(tmp, path)
+      end
+    end
+  end
+end