senren-ui 0.1.5 → 0.2.0

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

@@ -8,7 +8,9 @@ and obey it strictly.
 1. Use Senren components before writing custom HTML for the same purpose.
 2. Server-render via ViewComponent. Stimulus only for **local** behavior.
 3. Turbo handles server state. Controllers do not fetch/XHR from JS.
-4. No React, Vue, Alpine, lit, or external state framework. Ever.
+4. Interactivity stays in Stimulus. These components render on the server, so
+   introducing a client-side framework alongside them puts two systems in
+   charge of the same state.
 5. Tailwind classes must use **semantic tokens** (`bg-background`,
    `text-foreground`, `bg-primary`, `text-muted-foreground`,
    `border-border`, `bg-destructive`). Do not hard-code `gray-*`,
@@ -20,11 +22,24 @@ 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 %>
+   ```
+
+8. **Never put `app/components` on the asset load path.** With Propshaft this
+   publishes the directory: `assets:precompile` copies every component `.rb`
+   and `.html.erb` into `public/assets`, `.manifest.json` maps each logical
+   name to its digested filename, and the web server serves the source with
+   `HTTP 200` without Rails involved. Senren raises at boot in production if it
+   finds this, and warns elsewhere. Sidecar assets belong in their own
+   directory:
+   ```ruby
+   # config/initializers/assets.rb
+   Rails.application.config.assets.paths << Rails.root.join("app/components/assets")
+   # NOT app/components
    ```
 
 ## File ownership
@@ -47,9 +62,13 @@ and obey it strictly.
 ## 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.

data/lib/senren/rails/agent_rules_writer.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require 'senren/rails/marker_block'
+require 'senren/rails/safe_write'
 
 module Senren
   module Rails
@@ -21,6 +23,7 @@ module Senren
       end
 
       def sync!
+        assert_distinct_adapters!
         paths.ensure_agent_dirs!
         files = []
         files << write_full_file(paths.agent_rules_file, render_source_rules)
@@ -31,8 +34,46 @@ module Senren
         files
       end
 
+      # Each adapter gets different content, so two of them resolving to the
+      # same file means the last write silently wins.
+      #
+      # `ln -s AGENTS.md CLAUDE.md` is a normal way to keep one set of agent
+      # instructions, and now that in-repo symlinks are allowed it reaches here
+      # rather than being refused as an escape.
+      #
+      # Public so ComponentInstaller can run it as a preflight. The first
+      # version of this check lived inside sync!, which runs after the copier,
+      # so `senren:add` failed with components already on disk and the ledger
+      # already written.
+      def assert_distinct_adapters!
+        collisions = adapter_targets.group_by { |path, _| SafeWrite.real_target(path) }
+                                    .select { |_, group| group.size > 1 }
+        return if collisions.empty?
+
+        raise ArgumentError, collision_message(collisions)
+      end
+
       private
 
+      def adapter_targets
+        {
+          paths.codex_agents_md => 'AGENTS.md',
+          paths.claude_md => 'CLAUDE.md',
+          paths.copilot_instructions => '.github/copilot-instructions.md',
+          paths.cursor_rule_file => '.cursor/rules/senren.mdc'
+        }
+      end
+
+      def collision_message(collisions)
+        detail = collisions.map do |target, group|
+          "#{group.map(&:last).join(' and ')} both resolve to #{target}"
+        end.join('; ')
+
+        'Senren writes different instructions to each agent adapter, so these cannot share a file: ' \
+          "#{detail}. Replace the link with a real file, or have one adapter reference the other " \
+          'by path instead of linking to it.'
+      end
+
       def installed_names
         path = paths.installed_components
         return [] unless path.exist?
@@ -57,8 +98,14 @@ module Senren
           - 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.
+          - Keep interactivity in Stimulus. These components render on the server,
+            so a client-side framework alongside them means two systems own the
+            same state.
           - Use semantic Tailwind tokens; do not hard-code color families.
+          - Never add `app/components` to `config.assets.paths`. Propshaft
+            publishes every file under an asset path, so component `.rb` and
+            `.html.erb` source is precompiled into `public/assets` and served
+            over HTTP. Put sidecar assets in `app/components/assets` instead.
 
           ## Important Files
 
@@ -82,7 +129,7 @@ module Senren
           - 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.
+          - Keep interactivity in Stimulus rather than a client-side framework.
           - Use semantic Tailwind tokens.
         MD
       end
@@ -106,7 +153,7 @@ module Senren
           - 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.
+          - Keep interactivity in Stimulus rather than a client-side framework.
           - Use semantic Tailwind tokens.
         MD
       end
@@ -120,7 +167,7 @@ module Senren
           - 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.
+          - Keep interactivity in Stimulus rather than a client-side framework.
           - Use semantic Tailwind tokens.
         MD
       end
@@ -147,28 +194,24 @@ module Senren
 
       def write_adapter_file(path, generated, prefix: '')
         existing = path.exist? ? path.read : prefix.to_s
-        updated = inject(existing, generated)
+        updated = inject(existing, generated, label: path.to_s)
         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
+      def inject(existing, generated, label: nil)
+        MarkerBlock.inject(
+          existing, generated,
+          start_marker: START_MARKER, end_marker: END_MARKER, label: label
+        )
       end
 
+      # write_adapter_file reads its destination before rewriting it, so a
+      # symlinked .senren, .github or .cursor/rules did not merely redirect the
+      # write — it pulled outside content in and wrote it back out. SafeWrite
+      # refuses on the real path before either half of that happens.
       def atomic_write(path, content)
-        tmp = "#{path}.tmp"
-        File.write(tmp, content)
-        File.rename(tmp, path)
+        SafeWrite.write!(path, content, paths.root, path.to_s)
       end
     end
   end

data/lib/senren/rails/asset_path_guard.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Senren
+  module Rails
+    # Refuses to let component source be served as a static asset.
+    #
+    # ViewComponent documents putting sidecar assets next to components, and the
+    # usual way to reach them is:
+    #
+    #   config.assets.paths << Rails.root.join("app/components")
+    #
+    # With Propshaft that one line makes every file under app/components a
+    # servable asset, `.rb` and `.html.erb` included. Verified against Propshaft
+    # 1.3.2: 129 component source files resolved, `assets:precompile` copied all
+    # of them into public/assets/, and public/assets/.manifest.json listed each
+    # logical path next to its digested filename — so the digest is not even an
+    # obstacle. In production the web server hands them out with Rails never
+    # involved.
+    #
+    # Development is a different risk calculation, so there it warns. Production
+    # raises: a boot failure is recoverable, published source is not.
+    module AssetPathGuard
+      SOURCE_EXTENSIONS = %w[.rb .erb].freeze
+
+      module_function
+
+      # `production:` is injected rather than read from ::Rails so the guard can
+      # be unit tested without booting Rails, which is how the rest of this
+      # library's unit suite runs.
+      def check!(app, io: $stderr, production: production_env?)
+        offenders = offending_paths(app)
+        return true if offenders.empty?
+
+        message = message_for(offenders)
+        raise message if production
+
+        io.puts("[senren] WARNING: #{message}")
+        false
+      end
+
+      # Fails closed. `Rails.env.production?` let a conventional
+      # RAILS_ENV=staging deploy print one line of stderr and precompile the
+      # source anyway, and the same held for review apps and any custom
+      # environment name. `local?` is true only for development and test — the
+      # two environments where exposure is acceptable — so everything else is
+      # treated as deployed. Available since Rails 7.1, which is the floor.
+      def production_env?
+        return false unless defined?(::Rails) && ::Rails.respond_to?(:env)
+        return !::Rails.env.local? if ::Rails.env.respond_to?(:local?)
+
+        !%w[development test].include?(::Rails.env.to_s)
+      end
+
+      # An asset path is only a problem when component source actually sits
+      # under it, so an app that keeps sidecar assets in their own directory is
+      # left alone.
+      def offending_paths(app)
+        components = components_dir(app)
+        return [] unless components&.directory?
+
+        asset_paths(app).select { |path| publishes_source?(path, components) }
+      end
+
+      # Whether serving this asset path would serve component source.
+      #
+      # `source_files?` used to be asked once about app/components as a whole,
+      # which is the wrong question for a descendant path: with that shape,
+      # app/components/assets holding nothing but CSS looked identical to
+      # app/components/senren holding every component. Only the overlapping
+      # subtree can publish anything, and that subtree is the deeper of the two
+      # paths.
+      def publishes_source?(asset_path, components)
+        asset = Pathname.new(asset_path.to_s).expand_path
+        components = components.expand_path
+        return false unless overlap?(asset, components)
+
+        source_files?(asset.to_s.length >= components.to_s.length ? asset : components)
+      end
+
+      def components_dir(app)
+        app.root.join('app/components')
+      rescue StandardError
+        nil
+      end
+
+      def source_files?(dir)
+        SOURCE_EXTENSIONS.any? { |ext| Dir.glob(dir.join("**/*#{ext}")).any? }
+      end
+
+      def asset_paths(app)
+        app.config.respond_to?(:assets) ? Array(app.config.assets.paths) : []
+      rescue StandardError
+        []
+      end
+
+      # Two paths overlap when one contains the other, in EITHER direction, and
+      # the test has to be separator-aware:
+      #
+      #   app/components         is an ancestor  -> publishes everything
+      #   app/components/senren  is a descendant -> publishes the components
+      #   app/comp               shares a prefix -> publishes nothing
+      #
+      # The first version tested only the ancestor direction with a bare
+      # start_with?, so it missed the descendant case — which is what a
+      # developer writes after reading this module's own remediation text — and
+      # it blocked production boots over an unrelated app/comp directory.
+      def overlap?(one, other)
+        a = "#{one}#{File::SEPARATOR}"
+        b = "#{other}#{File::SEPARATOR}"
+
+        a.start_with?(b) || b.start_with?(a)
+      end
+
+      def message_for(offenders)
+        <<~MESSAGE.strip
+          app/components is on the asset load path (#{offenders.join(', ')}).
+
+          Propshaft serves every file under an asset path, so your component
+          .rb and .html.erb source would be published — assets:precompile copies
+          them into public/assets and .manifest.json lists them by name.
+
+          Move sidecar assets into their own directory and add that instead, for
+          example app/components/assets rather than app/components.
+        MESSAGE
+      end
+    end
+  end
+end

data/lib/senren/rails/base_component_patch.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Senren
+  module Rails
+    # Ruby appended to a host app's existing BaseComponent when it predates the
+    # URL-aware component templates.
+    #
+    # This duplicates the helpers in
+    # lib/generators/senren/install/templates/base_component.rb.tt, because
+    # apps installed before those helpers existed never receive the template
+    # again. The two definitions are pinned together by
+    # test/security/component_url_security_test.rb: if they drift, migrated apps
+    # silently keep an older, weaker safe_url.
+    module BaseComponentPatch
+      # Single-quoted heredoc: the body is emitted verbatim, so the backslash
+      # escapes inside safe_url survive into the host app's file.
+      URL_HELPERS = <<~'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?
+              # Browsers treat "\" as "/" for special schemes and strip TAB/CR/LF
+              # before parsing, so "/\evil.example" and "/<TAB>/evil.example" would
+              # both slip past a plain "//" check and resolve off-origin.
+              return fallback if url.include?('\\')
+              return fallback if url.match?(/[[:cntrl:]]/)
+              return url if url.start_with?('#')
+              # Any leading "//" is protocol-relative regardless of how many slashes
+              # follow. Rejecting here rather than relying on URI.parse matters:
+              # URI.parse("///evil.example") reports no scheme and no host, so the
+              # scheme-less fallback below would otherwise hand back a URL the browser
+              # resolves to https://evil.example/.
+              return fallback if url.start_with?('//')
+              return url if 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
+    end
+  end
+end

data/lib/senren/rails/component_copier.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'pathname'
 require 'yaml'
 require 'time'
+require 'senren/rails/base_component_patch'
+require 'senren/rails/safe_write'
 
 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
+      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 = BaseComponentPatch::URL_HELPERS
+
       attr_reader :registry, :paths, :stdout
 
       def initialize(registry: Registry.load!, paths: HostPaths.new, stdout: $stdout)
@@ -21,19 +32,72 @@ module Senren
       # Returns the ordered list of component names actually installed.
       def install(component_names, client_override: nil, force: false)
         wanted = registry.dependencies(*component_names)
+        validate_client_override!(component_names, client_override)
         paths.ensure_dirs!
+        ensure_base_component_url_helpers!
 
+        requested = Array(component_names).map(&:to_s)
         wanted.each do |name|
           comp = registry.fetch(name)
-          install_component(comp, client_override: client_override, force: force)
+          install_component(comp, client_override: override_for(name, requested, client_override), force: force)
         end
 
-        update_installed_ledger(wanted, client_override: client_override)
+        update_installed_ledger(wanted, requested: requested, client_override: client_override)
         wanted
       end
 
       private
 
+      # --client / --no-client describes what the user asked for, not what its
+      # dependencies are. Applying it to the whole closure meant
+      # `senren:add context_menu --no-client` also suppressed the controller for
+      # dropdown_menu, whose markup emits data-controller unconditionally — so
+      # the installed menu silently never opened, and the ledger then recorded
+      # client: false for a component this command was never asked about.
+      #
+      # validate_client_override! already exempts dependencies in the other
+      # direction, for the same reason.
+      def override_for(name, requested, client_override)
+        requested.include?(name) ? client_override : nil
+      end
+
+      def ensure_base_component_url_helpers!
+        dest = paths.base_component_path
+
+        # Checked before #exist?, which follows the link, so a destination
+        # resolving outside the app root is refused before it is read.
+        return if refuse_symlink?(dest, 'base_component.rb')
+
+        if dest.exist?
+          return if base_component_has_url_helpers?
+
+          # Read-modify-write through SafeWrite rather than File.open(dest, 'a').
+          # The append was the one non-atomic write left in the gem: a process
+          # killed partway through left base_component.rb holding half a method,
+          # and an app that will not boot. This is the migration path onto the
+          # hardened URL helpers, so it runs on apps that already have code
+          # worth not corrupting.
+          SafeWrite.write!(dest, dest.read + BASE_URL_HELPER_PATCH, paths.root, 'base_component.rb')
+          stdout.puts "  update #{dest} (url helpers)"
+          return
+        end
+
+        copy_file(BASE_COMPONENT_TEMPLATE, dest, force: false, label: 'base_component.rb')
+      end
+
+      # Delegates to SafeWrite so an intermediate symlinked directory is caught,
+      # not just a symlinked leaf. `app/components/senren -> /elsewhere` used to
+      # pass every check here.
+      def refuse_symlink?(dest, label)
+        SafeWrite.resolve(dest, paths.root, label, io: stdout).nil?
+      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)
 
@@ -46,11 +110,28 @@ module Senren
         end
       end
 
+      # Only the explicitly requested components are checked: pulling in a
+      # dependency that has no controller must not fail the whole install.
+      def validate_client_override!(requested, override)
+        return unless override
+
+        offenders = Array(requested).map { |name| registry.fetch(name) }.reject { |comp| controller_file_for(comp) }
+        return if offenders.empty?
+
+        raise ArgumentError,
+              "--client was requested for #{offenders.map(&:name).join(', ')}, but the registry lists no Stimulus " \
+              'controller for them. Drop --client, or add a controller file to the registry entry.'
+      end
+
+      def controller_file_for(comp)
+        comp.files.find { |relative| controller_source_path?(comp, relative) }
+      end
+
       def effective_client_for(comp, override)
-        return comp.client? if override.nil?
-        return false unless comp.can_have_client
+        desired = override.nil? ? comp.client? : (comp.can_have_client && override)
 
-        override
+        # Never record client behavior in the ledger that was not installed.
+        desired && !controller_file_for(comp).nil?
       end
 
       def source_for(comp, relative)
@@ -59,32 +140,69 @@ 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)
+
+        dest = assert_inside_host_root!(dest, label)
+        return if refuse_symlink?(dest, label)
+
         if File.exist?(dest) && !force
           stdout.puts "  skip  #{dest} (already exists)"
           return
         end
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(src, dest)
+        SafeWrite.mkdir_p!(File.dirname(dest), paths.root, label)
+        SafeWrite.copy!(src, dest, paths.root, label)
         stdout.puts "  copy  #{dest}"
       end
 
-      def update_installed_ledger(names, client_override:)
+      # Defense in depth: destinations are registry-derived, but a copier that
+      # can write anywhere is one bad registry entry away from a traversal.
+      #
+      # This used to compare expand_path, which normalises lexically and does
+      # not resolve symlinks, so a symlinked ancestor escaped it entirely.
+      def assert_inside_host_root!(dest, label)
+        SafeWrite.assert_inside!(dest, paths.root, label)
+      rescue SafeWrite::Escape => e
+        raise ArgumentError, e.message
+      end
+
+      # A ledger holding anything but a mapping used to reach `ledger['installed']
+      # ||= []` and raise `IndexError: string not matched` from String#[]=, which
+      # tells the user nothing about which file is wrong or why.
+      def load_ledger(path)
+        return {} unless path.exist?
+
+        content = YAML.safe_load_file(path) || {}
+        return content if content.is_a?(Hash)
+
+        raise ArgumentError,
+              "#{path} is not a Senren ledger: expected a YAML mapping, got #{content.class}. " \
+              'Fix or delete the file and run the command again.'
+      end
+
+      def update_installed_ledger(names, requested:, client_override:)
         ledger_path = paths.installed_components
-        ledger = ledger_path.exist? ? (YAML.safe_load_file(ledger_path) || {}) : {}
+        ledger = load_ledger(ledger_path)
         installed = ledger['installed'] ||= []
 
         names.each do |name|
@@ -93,7 +211,9 @@ module Senren
             'name' => name,
             'version' => Senren::Rails::VERSION,
             'installed_at' => Time.now.utc.iso8601,
-            'client' => effective_client_for(registry.fetch(name), client_override)
+            'client' => effective_client_for(
+              registry.fetch(name), override_for(name, requested, client_override)
+            )
           }
           if existing
             existing.merge!(attrs.except('installed_at'))
@@ -103,8 +223,8 @@ module Senren
         end
 
         installed.sort_by! { |e| e['name'] }
-        ledger_path.parent.mkpath
-        File.write(ledger_path, YAML.dump(ledger))
+        SafeWrite.mkdir_p!(ledger_path.parent, paths.root, 'ledger')
+        SafeWrite.write!(ledger_path, YAML.dump(ledger), paths.root, 'ledger')
       end
     end
   end