senren-ui 0.1.6 → 0.2.0

data/lib/generators/senren/install/install_generator.rb

@@ -38,6 +38,27 @@ module Senren
         copy_file Senren::Rails.registry_path, '.senren/registry.yml'
       end
 
+      # Switches Stimulus to on-demand loading instead of documenting it.
+      #
+      # Rails' default is `eagerLoadControllersFrom("controllers", application)`,
+      # which imports every controller in the importmap on every page. Because
+      # `pin_all_from "app/javascript/controllers"` is recursive it also covers
+      # app/javascript/controllers/senren, so a static page paid for every
+      # interactive component the app had installed.
+      #
+      # This was a README instruction the developer had to follow by hand, and a
+      # "PASS" in bin/performance that only grepped that README. An instruction
+      # nobody runs is not a feature.
+      #
+      # It uses the official stimulus-loading helper rather than a Senren-specific
+      # loader, and therefore changes loading for the app's own controllers too.
+      # That is the trade the README already asked for; the generator only acts
+      # when the file still carries the untouched Rails default, and says so.
+      def configure_stimulus_loading
+        enable_lazy_controller_loading
+        disable_controller_preloading
+      end
+
       def write_skill_file
         say_status :senren, 'writing .senren/skill.md'
         Senren::Rails::SkillWriter.new(paths: host_paths).sync!
@@ -56,6 +77,59 @@ module Senren
 
       private
 
+      def enable_lazy_controller_loading
+        index = 'app/javascript/controllers/index.js'
+        unless host_file?(index)
+          return say_status(:skip,
+                            "#{index} not found; switch to lazyLoadControllersFrom by hand")
+        end
+
+        source = File.read(File.join(destination_root, index))
+        if source.include?('lazyLoadControllersFrom')
+          return say_status(:senren,
+                            'controllers already load on demand')
+        end
+
+        unless source.include?('eagerLoadControllersFrom')
+          return say_status(:skip, "#{index} has a custom loader; left alone")
+        end
+
+        gsub_file index, 'eagerLoadControllersFrom', 'lazyLoadControllersFrom'
+        say_status :senren, 'Stimulus controllers now load when their data-controller appears'
+      end
+
+      # Only strips the modulepreload tags. On its own it does not stop eager
+      # importing, which is why it is paired with the change above.
+      def disable_controller_preloading
+        importmap = 'config/importmap.rb'
+        unless host_file?(importmap)
+          return say_status(:skip,
+                            "#{importmap} not found; add preload: false by hand")
+        end
+
+        source = File.read(File.join(destination_root, importmap))
+        if source.match?(/under:\s*["']controllers["'].*preload:\s*false/)
+          return say_status(:senren,
+                            'controller preloading already disabled')
+        end
+
+        if source.match?(%r{pin_all_from\s+["']app/javascript/controllers["']})
+          # A backreference rather than a block: Thor forwards the block to
+          # String#gsub across several frames, where $~ is no longer the match.
+          # The lookahead makes a second run a no-op.
+          gsub_file importmap,
+                    %r{(pin_all_from\s+["']app/javascript/controllers["'](?![^\n]*preload:)[^\n]*)},
+                    '\1, preload: false'
+        else
+          append_to_file importmap,
+                         %(\npin_all_from "app/javascript/controllers", under: "controllers", preload: false\n)
+        end
+      end
+
+      def host_file?(relative)
+        File.exist?(File.join(destination_root, relative))
+      end
+
       def host_paths
         @host_paths ||= Senren::Rails::HostPaths.new(destination_root)
       end

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

@@ -27,28 +27,76 @@ 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)
+      # `data` arrives from two places: the caller's own attributes (html_attrs)
+      # and whatever the template passes here. Both are merged, and the
+      # component marker is applied last so it always survives.
+      #
+      # Splatting html_attrs after a computed `data:` used to overwrite it
+      # wholesale, so any component given a `data:` hash silently lost its
+      # data-senren-component marker. MaskedInput hit this on every render.
+      data = (html_attrs[:data] || {})
+             .merge(extra.delete(:data) || {})
+             .merge(senren_component: senren_component_name)
+
+      # `class` had exactly the same defect and it was never fixed alongside
+      # `data`. Every Rails tag helper accepts `class:`, so it is the first
+      # thing anyone types — and splatting html_attrs replaced the computed
+      # value outright, erasing the component's variant and size styling with
+      # no warning. It is merged like any other caller-supplied class instead,
+      # last so it still wins where the two genuinely conflict.
       tag_class = merge_classes(
         classes,
         self.class::VARIANTS[@variant],
         self.class::SIZES[@size],
         @class_name,
-        extra.delete(:class)
+        extra.delete(:class),
+        html_attrs[:class]
       )
-      { class: tag_class, data: data, **html_attrs, **extra }
+      { class: tag_class, data: data, **html_attrs.except(:data, :class), **extra }
     end
 
     def senren_component_name
       self.class.name.to_s.sub(/^Senren::/, '').sub(/Component$/, '').gsub(/([a-z])([A-Z])/, '\1_\2').downcase
     end
 
+    # Builds a DOM id from the arguments that identify this component, so the
+    # same inputs always produce the same id.
+    #
+    # Components used to append `SecureRandom.hex`, which made every render emit
+    # different HTML. That single fact disabled Turbo morph (it pairs nodes by
+    # id), HTTP ETags (the body never matched), fragment caching (cached and
+    # fresh fragments referenced different ids), and snapshot testing.
+    #
+    # Two components with identical identifying inputs on one page now produce
+    # the same id and the accessibility test fails. That is deliberate: the
+    # caller should pass an explicit `id:`. A random suffix hid the collision
+    # instead of resolving it.
+    def senren_dom_id(*parts)
+      seed = parts.flatten.map(&:to_s).reject(&:empty?).join('-')
+      base = "senren-#{senren_component_name.tr('_', '-')}"
+      return base if seed.empty?
+
+      "#{base}-#{seed.parameterize}"
+    end
+
     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?('#')
-      return url if url.start_with?('/') && !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)

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-*`,
@@ -27,6 +29,19 @@ and obey it strictly.
    <%% 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
 
 | Path                                | Owned by         |

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