senren-ui 0.1.5 → 0.2.0

data/lib/senren/rails/component_installer.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+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?
+
+        # Preflight. Everything below writes to disk, and a failure partway
+        # through leaves components copied, the ledger updated and the guidance
+        # files stale -- which is exactly what the first version of the adapter
+        # collision check did.
+        AgentRulesWriter.new(registry: registry, paths: paths).assert_distinct_adapters!
+
+        installed = ComponentCopier.new(registry: registry, paths: paths, stdout: stdout)
+                                   .install(normalized_names, client_override: client_override, force: force)
+
+        refresh_registry_mirror
+        SkillWriter.new(registry: registry, paths: paths).sync!
+        AgentRulesWriter.new(registry: registry, paths: paths).sync!
+
+        stdout.puts "Installed: #{installed.join(', ')}"
+        installed
+      end
+
+      private
+
+      # The mirror was written once at install time and never again, so it drifted
+      # from the gem on every upgrade while the generated agent rules kept
+      # advertising it as the authoritative "component registry mirror". Agents
+      # read stale component metadata and had no way to tell.
+      # The FileUtils.cp here was lifted from the Installer#mirror_registry that
+      # this same review deleted, and it carried that method's defect with it:
+      # containment was applied to the directory, so a symlinked
+      # .senren/registry.yml was followed and a file outside the app root was
+      # overwritten. Moving a bug is not fixing it. SafeWrite.copy! checks the
+      # destination file itself.
+      def refresh_registry_mirror
+        dest = paths.registry_mirror
+        SafeWrite.mkdir_p!(dest.dirname, paths.root, 'registry mirror')
+        SafeWrite.copy!(Senren::Rails.registry_path, dest, paths.root, 'registry mirror')
+      end
+    end
+  end
+end

data/lib/senren/rails/doctor.rb

@@ -28,14 +28,17 @@ module Senren
       private
 
       def check(label)
-        ok = false
         detail = nil
-        begin
-          ok = !yield.nil?
+        result = begin
+          yield
         rescue StandardError => e
           detail = e.message
+          nil
         end
-        Result.new(label, ok, detail)
+
+        # Checks return either a boolean (File#exist?) or nil/truthy (defined?).
+        # Only a truthy result passes: `false` must fail, not slip through.
+        Result.new(label, result ? true : false, detail)
       end
 
       def gem_loadable?(name)

data/lib/senren/rails/engine.rb

@@ -11,6 +11,29 @@ module Senren
         rake_path = File.expand_path('../../tasks/senren.rake', __dir__)
         app.paths['lib/tasks'] << rake_path if File.exist?(rake_path)
       end
+
+      # The gem's only production-boot behaviour, and it earns the exception:
+      # with app/components on the asset load path, Propshaft publishes
+      # component source.
+      #
+      # after_initialize rather than an `after:` anchor. Hosts append asset
+      # paths from config/initializers/assets.rb, so the check has to see a
+      # fully configured app. after_initialize is the only placement that
+      # guarantees that without reasoning about railtie order.
+      #
+      # This was first written as `after: :append_assets_path`, copied from
+      # sprockets-rails. Propshaft names its equivalent
+      # "propshaft.append_assets_path", and Rails resolves an unknown ordering
+      # anchor to an empty dependency set rather than raising — so the anchor
+      # was inert. It happened not to matter, because an application's own
+      # initializers run ahead of every engine's, but an inert anchor that reads
+      # like a guarantee is worse than no anchor.
+      initializer 'senren.rails.guard_asset_paths' do |app|
+        app.config.after_initialize do
+          require 'senren/rails/asset_path_guard'
+          Senren::Rails::AssetPathGuard.check!(app)
+        end
+      end
     end
   end
 end

data/lib/senren/rails/host_paths.rb

@@ -1,4 +1,5 @@
 require 'pathname'
+require 'senren/rails/safe_write'
 
 module Senren
   module Rails
@@ -32,13 +33,21 @@ module Senren
       def claude_md             = root.join('CLAUDE.md')
       def codex_agents_md       = root.join('AGENTS.md')
 
+      # Pathname#mkpath stops at File.directory?, which follows symlinks, so a
+      # checkout shipping app/components/senren as a link to somewhere outside
+      # the project had that link preserved and every later write redirected
+      # through it. SafeWrite refuses instead of silently accepting it.
       def ensure_dirs!
         [senren_dir, components_dir, stimulus_dir,
-         stylesheet_path.dirname, github_dir, cursor_rules_dir].each(&:mkpath)
+         stylesheet_path.dirname, github_dir, cursor_rules_dir].each do |dir|
+          SafeWrite.mkdir_p!(dir, root, 'ensure_dirs!')
+        end
       end
 
       def ensure_agent_dirs!
-        [senren_dir, github_dir, cursor_rules_dir].each(&:mkpath)
+        [senren_dir, github_dir, cursor_rules_dir].each do |dir|
+          SafeWrite.mkdir_p!(dir, root, 'ensure_agent_dirs!')
+        end
       end
     end
   end

data/lib/senren/rails/marker_block.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Senren
+  module Rails
+    # Replaces the content between a START/END marker pair, preserving
+    # everything outside it.
+    #
+    # These markers delimit generated instructions inside files that humans and
+    # AI agents also edit (CLAUDE.md, AGENTS.md, .senren/skill.md). A tampered
+    # or duplicated marker pair is treated as an error rather than something to
+    # work around: silently "repairing" it produces a block that regeneration
+    # can never clean up again, which is indistinguishable from a persistent
+    # prompt injection.
+    module MarkerBlock
+      class MalformedMarkers < StandardError; end
+
+      module_function
+
+      # Returns `existing` with the marker block replaced by `generated`.
+      # Appends a fresh block when no markers are present yet.
+      def inject(existing, generated, start_marker:, end_marker:, label: nil)
+        existing = existing.to_s
+        body = generated.to_s.strip
+
+        assert_body_is_marker_free!(body, start_marker, end_marker, label)
+        assert_well_formed!(existing, start_marker, end_marker, label)
+
+        block = "#{start_marker}\n\n#{body}\n\n#{end_marker}"
+        return append(existing, block) unless existing.include?(start_marker)
+
+        pattern = /#{Regexp.escape(start_marker)}.*?#{Regexp.escape(end_marker)}/m
+        # Block form is required. Given a replacement *string*, String#sub
+        # expands \0, \1 and \& as backreferences: a body containing one would
+        # splice the old block — markers and all — back into the new one,
+        # resurrecting stale content and duplicating the delimiters. The block
+        # form takes the return value literally.
+        existing.sub(pattern) { block }
+      end
+
+      # A generated block that contains its own delimiters produces a file this
+      # module then refuses to parse: the writer corrupts its own output and the
+      # error blames the user for hand-editing. Fail at the source instead.
+      def assert_body_is_marker_free!(body, start_marker, end_marker, label)
+        found = [start_marker, end_marker].select { |marker| body.include?(marker) }
+        return if found.empty?
+
+        where = label ? " for #{label}" : ''
+        raise MalformedMarkers,
+              "Generated content#{where} contains #{found.join(' and ')}. " \
+              'The data this block is rendered from must not contain the markers themselves.'
+      end
+
+      def append(existing, block)
+        head = existing.rstrip
+        head.empty? ? "#{block}\n" : "#{head}\n\n#{block}\n"
+      end
+
+      # A file is well formed when it has either no markers at all, or exactly
+      # one START followed by exactly one END.
+      def assert_well_formed!(existing, start_marker, end_marker, label)
+        starts = existing.scan(start_marker).size
+        ends   = existing.scan(end_marker).size
+
+        return if starts.zero? && ends.zero?
+
+        where = label ? " in #{label}" : ''
+        if starts != 1 || ends != 1
+          raise MalformedMarkers,
+                "Expected exactly one #{start_marker} and one #{end_marker}#{where}, " \
+                "found #{starts} and #{ends}. Fix the markers by hand, then re-run the sync."
+        end
+
+        return if existing.index(start_marker) < existing.index(end_marker)
+
+        raise MalformedMarkers,
+              "#{end_marker} appears before #{start_marker}#{where}. " \
+              'Fix the marker order by hand, then re-run the sync.'
+      end
+    end
+  end
+end

data/lib/senren/rails/registry.rb

@@ -3,29 +3,19 @@ require 'yaml'
 module Senren
   module Rails
     # Loads, validates, and queries the Senren component registry.
-    #
-    #   reg = Senren::Rails::Registry.load!
-    #   reg.find("button")           # => Component struct
-    #   reg.dependencies("dialog")    # => [<button>]
-    #   reg.group("forms")            # => [<form>, <input>, ...]
     class Registry
       include Enumerable
 
       REQUIRED_KEYS = %w[category client can_have_client files depends_on pairs_with variants accessibility ai].freeze
+      OPTIONAL_KEYS = %w[controller stub].freeze
+      ALLOWED_KEYS = (REQUIRED_KEYS + OPTIONAL_KEYS).freeze
       VALID_CATEGORIES = %w[actions forms overlays navigation layout data saas rich].freeze
+      NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
 
-      Component = Struct.new(
-        :name, :category, :client, :can_have_client, :controller, :stub,
-        :files, :depends_on, :pairs_with, :variants, :accessibility,
-        :use_for, :avoid,
-        keyword_init: true
-      ) do
+      Component = Struct.new(:name, :category, :client, :can_have_client, :controller, :stub, :files, :depends_on,
+                             :pairs_with, :variants, :accessibility, :use_for, :avoid, keyword_init: true) do
         def stub? = stub == true
         def client? = client == true
-
-        def to_h_full
-          to_h.merge(stub: stub?, client: client?)
-        end
       end
 
       attr_reader :components, :groups, :recipes
@@ -43,6 +33,7 @@ module Senren
       end
 
       def initialize(components_yaml, groups_yaml, recipes_yaml)
+        @raw_components = (components_yaml || {}).fetch('components', {})
         @components = parse_components(components_yaml)
         @groups     = (groups_yaml || {}).fetch('groups', [])
         @recipes    = (recipes_yaml || {}).fetch('recipes', {})
@@ -57,21 +48,11 @@ module Senren
                                            "Known: #{@components.keys.sort.join(', ')}"
       end
 
-      def all
-        @components.values
-      end
+      def all = @components.values
+      def each(&) = all.each(&)
+      alias find_each each
 
-      def each(&)
-        all.each(&)
-      end
-
-      def find_each(&)
-        each(&)
-      end
-
-      def names
-        @components.keys
-      end
+      def names = @components.keys
 
       def group(category_id)
         @components.values.select { |c| c.category == category_id.to_s }
@@ -118,12 +99,57 @@ module Senren
 
       def validate_components(errors)
         @components.each do |name, comp|
-          errors << "#{name}: invalid category #{comp.category.inspect}" unless VALID_CATEGORIES.include?(comp.category)
-          comp.depends_on.each do |dep|
-            errors << "#{name}: depends_on unknown component #{dep.inspect}" unless @components.key?(dep)
-          end
-          errors << "#{name}: client=true but can_have_client=false" if comp.client && !comp.can_have_client
-          errors << "#{name}: client=true requires a controller identifier" if comp.client && comp.controller.nil?
+          validate_component(name, comp, errors)
+        end
+      end
+
+      def validate_component(name, comp, errors)
+        validate_component_name(name, errors)
+        validate_component_keys(name, errors)
+        validate_component_category(name, comp, errors)
+        validate_component_dependencies(name, comp, errors)
+        validate_component_client_contract(name, comp, errors)
+        validate_component_file_paths(name, comp, errors)
+      end
+
+      # The file-path allowlist is derived from the component name, so an
+      # unconstrained name would validate a traversal path against itself.
+      def validate_component_name(name, errors)
+        return if NAME_PATTERN.match?(name)
+
+        errors << "#{name.inspect}: invalid component name (expected #{NAME_PATTERN.source})"
+      end
+
+      def validate_component_keys(name, errors)
+        extra_keys = @raw_components.fetch(name).keys - ALLOWED_KEYS
+        errors << "#{name}: unknown keys #{extra_keys.sort.join(', ')}" if extra_keys.any?
+      end
+
+      def validate_component_category(name, comp, errors)
+        return if VALID_CATEGORIES.include?(comp.category)
+
+        errors << "#{name}: invalid category #{comp.category.inspect}"
+      end
+
+      def validate_component_dependencies(name, comp, errors)
+        comp.depends_on.each do |dep|
+          errors << "#{name}: depends_on unknown component #{dep.inspect}" unless @components.key?(dep)
+        end
+      end
+
+      def validate_component_client_contract(name, comp, errors)
+        errors << "#{name}: client=true but can_have_client=false" if comp.client && !comp.can_have_client
+        errors << "#{name}: client=true requires a controller identifier" if comp.client && comp.controller.nil?
+        return unless comp.client && !controller_file?(name, comp)
+
+        errors << "#{name}: client=true requires a Stimulus controller file"
+      end
+
+      def validate_component_file_paths(name, comp, errors)
+        comp.files.each do |path|
+          next if allowed_component_file?(name, path)
+
+          errors << "#{name}: invalid file path #{path.inspect}"
         end
       end
 
@@ -156,6 +182,18 @@ module Senren
           ).freeze
         end
       end
+
+      def controller_file?(name, comp)
+        comp.files.include?("app/javascript/controllers/senren/#{name}_controller.js")
+      end
+
+      def allowed_component_file?(name, path)
+        [
+          "app/components/senren/#{name}_component.rb",
+          "app/components/senren/#{name}_component.html.erb",
+          "app/javascript/controllers/senren/#{name}_controller.js"
+        ].include?(path)
+      end
     end
   end
 end

data/lib/senren/rails/safe_write.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+require 'securerandom'
+
+module Senren
+  module Rails
+    # Containment for everything this gem writes into a host app.
+    #
+    # The threat model is a repository you clone and run `senren:install` in.
+    # The *content* written is gem-controlled, so this is a file-creation and
+    # overwrite primitive rather than an arbitrary-content write — but a
+    # checkout that ships `app/components/senren` as a symlink pointing outside
+    # the project could previously redirect every copied file, and
+    # `write_adapter_file` reads its destination before rewriting it, so
+    # pre-existing content outside the checkout was modified too.
+    #
+    # Two independent defects made that possible, and both are fixed here:
+    #
+    #   1. Containment used Pathname#expand_path, which normalises `..`
+    #      lexically and does NOT resolve symlinks. An escaping path therefore
+    #      passed the start_with? check. Containment must compare realpath.
+    #   2. Symlinks were refused on the leaf only, never on an intermediate
+    #      directory, and Pathname#mkpath stops at File.directory? — which
+    #      follows a link — so a symlinked parent was preserved rather than
+    #      replaced.
+    module SafeWrite
+      class Escape < StandardError; end
+
+      module_function
+
+      MAX_LINK_DEPTH = 32
+
+      # Where a write to `path` would actually land, with symlinks followed --
+      # including a DANGLING one, by reading its declared target rather than
+      # asking the filesystem to resolve it.
+      #
+      # Following the declared target is what makes the dangling case decidable.
+      # `exist?` is false on a broken link, so a check that resolved only
+      # existing ancestors would clear the parent directory and let the write
+      # land wherever the link points.
+      def real_target(path, depth = 0)
+        current = Pathname.new(path).expand_path
+        return current if depth > MAX_LINK_DEPTH
+
+        if current.symlink?
+          link = Pathname.new(File.readlink(current))
+          link = current.dirname + link unless link.absolute?
+          return real_target(link, depth + 1)
+        end
+        return current.realpath if current.exist?
+
+        resolve_existing_prefix(current)
+      rescue SystemCallError
+        Pathname.new(path).expand_path
+      end
+
+      # For a destination that does not exist yet: resolve the deepest ancestor
+      # that does, then re-append the part that is still missing.
+      #
+      # `symlink?` is part of the loop condition, not just `exist?`. A dangling
+      # link is invisible to `exist?`, so a walk that only tested existence
+      # stepped straight over an intermediate one and rebuilt the tail
+      # lexically -- reporting a path inside the root for a write that would
+      # land wherever the link pointed. Not reachable through today's callers,
+      # because each one runs mkdir_p! on the parent first and that catches it,
+      # but that is an implicit contract between caller and helper, and this
+      # cycle has already broken two of those.
+      def resolve_existing_prefix(path)
+        tail = []
+        current = path
+        until current.exist? || current.symlink? || current.root?
+          tail.unshift(current.basename)
+          current = current.parent
+        end
+        current = real_target(current) if current.symlink?
+        current = current.realpath if current.exist?
+        tail.reduce(current) { |acc, part| acc.join(part) }
+      end
+
+      # True when a write to `path` would land inside `root`.
+      #
+      # The property is containment, NOT the absence of symlinks. An earlier
+      # version refused every link on the path regardless of where it pointed,
+      # which broke `ln -s AGENTS.md CLAUDE.md` -- an ordinary way to keep one
+      # set of agent instructions -- and took `senren:add` down with it.
+      def inside?(path, root)
+        real_root = Pathname.new(root).expand_path
+        real_root = real_root.realpath if real_root.exist?
+        target = real_target(path)
+
+        target == real_root || target.to_s.start_with?("#{real_root}#{File::SEPARATOR}")
+      end
+
+      def assert_inside!(path, root, label)
+        return real_target(path) if inside?(path, root)
+
+        raise Escape,
+              "Refusing to write outside the app root: #{path} resolves to " \
+              "#{real_target(path)} (#{label})"
+      end
+
+      # Creates `dir`, refusing only when it would land outside the root.
+      def mkdir_p!(dir, root, label)
+        target = assert_inside!(dir, root, label)
+        FileUtils.mkdir_p(target)
+        target
+      end
+
+      # Resolves a destination for writing, or returns nil when it must be
+      # skipped. Raises when the destination escapes the app root.
+      def resolve(dest, root, label, io: $stdout)
+        assert_inside!(dest, root, label)
+      rescue Escape => e
+        io.puts "  skip  #{dest} (#{e.message}) [#{label}]"
+        nil
+      end
+
+      # An in-repo symlink is left in place: the write goes to what it points
+      # at, so `ln -s AGENTS.md CLAUDE.md` survives the write instead of being
+      # replaced by a regular file.
+      def assert_writable!(path, root, label)
+        assert_inside!(path, root, label)
+      end
+
+      # Every write this gem performs goes through here or #copy!.
+      #
+      # Hand-rolled File.write / FileUtils.cp is what let component source
+      # escape twice: once through a symlinked directory, and once -- after
+      # that was fixed -- through a symlinked destination *file*, because
+      # containment had been applied to the parent only. Writing via a
+      # temporary and renaming also means a killed process cannot truncate the
+      # file: rename is atomic and does not follow a symlink at the target.
+      def write!(path, content, root, label)
+        target = assert_writable!(path, root, label)
+        atomically(target) { |io| io.write(content) }
+      end
+
+      def copy!(source, path, root, label)
+        target = assert_writable!(path, root, label)
+        atomically(target) { |io| IO.copy_stream(source.to_s, io) }
+      end
+
+      # The temporary was the last way out of the app root, and containment
+      # never looked at it.
+      #
+      # `<dest>.<pid>.tmp` is guessable, and git stores symlinks, so a
+      # repository could ship `.senren/registry.yml.<pid>.tmp` as a link to
+      # something outside the checkout. `File.write` follows a symlink, so the
+      # write landed there with every containment check having passed —
+      # verified before this was changed.
+      #
+      # Two independent fixes, because either alone is thin. A random suffix
+      # removes the guess, and O_CREAT|O_EXCL refuses to open an existing path
+      # at all and does not follow a final symlink, so a lucky guess still
+      # fails. 0o644 rather than 0o600 keeps the permissions a plain write
+      # would have produced.
+      def atomically(target, &)
+        tmp = Pathname.new("#{target}.#{SecureRandom.hex(12)}.tmp")
+        File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o644, &)
+        File.rename(tmp, target)
+        target
+      ensure
+        FileUtils.rm_f(tmp) if tmp&.exist?
+      end
+    end
+  end
+end

data/lib/senren/rails/skill_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
@@ -30,16 +32,23 @@ module Senren
         installed = installed_names
         body = render(installed)
 
-        paths.senren_dir.mkpath
+        SafeWrite.mkdir_p!(paths.senren_dir, paths.root, 'skill.md')
         existing = paths.skill_file.exist? ? paths.skill_file.read : default_outer_template
 
         new_content = inject(existing, body)
-        paths.skill_file.write(new_content)
+        atomic_write(paths.skill_file, new_content)
         paths.skill_file
       end
 
       private
 
+      # Routed through SafeWrite rather than hand-rolled. assert_inside! plus
+      # rename was already safe for an existing symlink, but not for a dangling
+      # one, and two other writers proved that hand-rolled writes drift.
+      def atomic_write(path, content)
+        SafeWrite.write!(path, content, paths.root, path.to_s)
+      end
+
       def installed_names
         path = paths.installed_components
         return [] unless path.exist?
@@ -50,7 +59,7 @@ module Senren
 
       def render(installed_names)
         if installed_names.empty?
-          return '_No Senren components installed yet. Run `bin/rails senren:add <name>...` to install components._'
+          return '_No Senren components installed yet. Run `bin/rails senren:add button` to install components._'
         end
 
         lines = []
@@ -110,21 +119,51 @@ module Senren
         end
       end
 
+      # Describes what is installed, not what the registry offers.
+      #
+      # This rendered the registry default, so after `senren:add select
+      # --no-client` the skill file told agents to use
+      # `senren--select` and named a controller file that is not on disk. The
+      # copier computes the truth and writes it to the ledger — with a comment
+      # saying "never record client behavior in the ledger that was not
+      # installed" — and nothing read it back. The gem's flagship feature was
+      # wrong for precisely the installs where the flag was exercised.
       def client_summary(comp)
         return 'none' unless comp.client?
+        return 'none (installed without its Stimulus controller)' unless installed_with_client?(comp.name)
 
         path = "app/javascript/controllers/senren/#{comp.name}_controller.js"
         "Stimulus `#{comp.controller}` (`#{path}`)"
       end
 
+      # nil when the ledger predates this field, in which case the registry
+      # default is the best available answer.
+      def installed_with_client?(name)
+        entry = ledger_entries.find { |e| e['name'] == name }
+        return true if entry.nil? || !entry.key?('client')
+
+        entry['client']
+      end
+
+      def ledger_entries
+        @ledger_entries ||= begin
+          path = paths.installed_components
+          path.exist? ? Array((YAML.safe_load_file(path) || {})['installed']) : []
+        end
+      end
+
       def format_list(items)
         return '_none_' if items.empty?
 
         items.map { |i| "`#{i}`" }.join(', ')
       end
 
+      # NAME_PATTERN accepts consecutive underscores, and "foo__bar".split("_")
+      # yields an empty segment, so w[0] was nil and this raised NoMethodError —
+      # after the files were copied and the ledger written, leaving a
+      # half-completed install. Empty segments are dropped instead.
       def humanize(name)
-        name.split('_').map { |w| w[0].upcase + w[1..] }.join
+        name.split('_').reject(&:empty?).map { |w| w[0].upcase + w[1..] }.join
       end
 
       def ruby_class_for(name)
@@ -132,13 +171,10 @@ module Senren
       end
 
       def inject(existing, generated_body)
-        if existing.include?(START_MARKER) && existing.include?(END_MARKER)
-          before = existing.split(START_MARKER, 2).first
-          after  = existing.split(END_MARKER, 2).last
-          "#{before}#{START_MARKER}\n\n#{generated_body}\n\n#{END_MARKER}#{after}"
-        else
-          "#{existing.rstrip}\n\n#{START_MARKER}\n\n#{generated_body}\n\n#{END_MARKER}\n"
-        end
+        MarkerBlock.inject(
+          existing, generated_body,
+          start_marker: START_MARKER, end_marker: END_MARKER, label: paths.skill_file.to_s
+        )
       end
 
       def default_outer_template
@@ -151,7 +187,7 @@ module Senren
 
           - Use Senren components before writing custom HTML.
           - Use ViewComponent for reusable UI; Turbo for server state; Stimulus for local behavior only.
-          - Do not introduce React, Vue, Alpine, or any external state framework.
+          - Keep interactivity in Stimulus rather than a client-side framework.
           - Do not hard-code colors; use semantic Tailwind tokens like `bg-background`, `text-foreground`, `bg-primary`.
 
           ## Installed Components