engine_map 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b3873a0c9fbc083b966ba188397878d2b264f0722da9fd3a4df38a418d107ec
+  data.tar.gz: b835262fef07f989f20e3f548b778f34a6a302e688da74e95c1c85ff28951d8d
+SHA512:
+  metadata.gz: 2340384f5cae24fcb74ce7bf4a101a5b285263168d9d4504cdc56a52d2668d3a923a7b1580f21fa8aaa6d1ea5e862ca22efcf3d3a031d894a0c4b15d31d1a393
+  data.tar.gz: 02def4daf9ce5e73949026998940f58875bc79be408fa60aedc3230d561f2a5c4a71d46c6449044af82ba4009814f18c3ababbcccc105425f39034fe88b7ea5f

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## Unreleased
+
+- Initial development.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Baden
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# EngineMap
+
+Asset helpers and an install generator for Rails engines (Rails 8, importmap, Stimulus), on Propshaft or Sprockets.
+
+EngineMap gives you:
+
+- `engine_stylesheet_link_tags "my_engine", :all` links every CSS file in the engine's stylesheet folder, with digests.
+- Importmap modes: merge the engine's pins into the host's map, use an independent map, or both.
+- Namespaced Stimulus controllers that can't collide with the host's.
+- An install generator that injects into existing files, backs up anything it replaces, and is safe to re-run.
+
+No database, no routes, no models.
+
+## Install
+
+Add the gem to the engine's (or host app's) Gemfile, then run the generator:
+
+```ruby
+gem "engine_map"
+```
+
+```sh
+bundle install
+bin/rails g engine_map:install
+```
+
+Run it from inside an engine and that engine is pre-selected. Otherwise you get a numbered list of the engines your app has loaded. The host app is listed too.
+
+| Option | Values | Default |
+|---|---|---|
+| `--engine NAME` | skip the prompt | |
+| `--importmap` | `merge`, `own`, `both` | `merge` |
+| `--stimulus` | `host`, `own`, `none` | `host` |
+| `--all` | also list engines from installed gems | off |
+
+## What the generator changes
+
+- `lib/<engine>/engine.rb`: adds `require "engine_map"` and `EngineMap.configure(self)`.
+- `<engine>.gemspec`: adds `spec.add_dependency "engine_map"`.
+- `config/importmap.rb`, `app/javascript/<engine>/...` and a starter stylesheet are created if missing.
+- The engine's layout: its own stylesheet tag is replaced by `engine_stylesheet_link_tags`, and importmap tags are added.
+
+When a line is replaced, the file gets a `.backup` next to it (never overwritten: `.backup.1`, ...). If a file or anchor can't be found, the generator prints the exact lines to add by hand. Running it twice changes nothing and says so.
+
+## Importmap modes
+
+A page can only render one import map, so each layout picks one.
+
+**merge (default).** The engine's pins join the host's map. Use the normal `javascript_importmap_tags` plus `javascript_import_module_tag "my_engine/application"`.
+
+**own.** The engine has an independent map, with a helper named after the engine:
+
+```erb
+<%= my_engine_javascript_importmap_tags %>
+```
+
+**both** enables both and generates `app/views/layouts/my_engine/standalone.html.erb`, an independent layout the engine can opt into.
+
+## Stimulus
+
+Controllers live in `app/javascript/my_engine/controllers/` and are pinned as `controllers/my_engine/...`, so the host's `eagerLoadControllersFrom("controllers", ...)` finds them. Identifiers are namespaced:
+
+```erb
+<div data-controller="my-engine--example"></div>
+```
+
+With `--stimulus own`, the engine also gets `my_engine/standalone.js`, which starts its own Stimulus application. Only the engine's own importmap helper loads it, never a merged layout.
+
+## Sprockets
+
+The engine registers its own CSS and JS for precompile, so the host's `manifest.js` needs no engine-specific lines. A Sprockets host must still link its own `app/javascript` in `manifest.js`. When the target is a host app, the generator checks this and adds the lines if missing.
+
+## Development
+
+```sh
+bin/test                                              # Propshaft
+BUNDLE_GEMFILE=gemfiles/sprockets.gemfile bin/test    # Sprockets
+bundle exec rake test:pipelines                       # both
+```
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+
+namespace :test do
+  desc "Run the suite under Propshaft and Sprockets"
+  task :pipelines do
+    ["Gemfile", "gemfiles/sprockets.gemfile"].each do |gemfile|
+      puts "\n== #{gemfile} =="
+      system({ "BUNDLE_GEMFILE" => gemfile }, "bin/test") || abort("failed under #{gemfile}")
+    end
+  end
+end

data/lib/engine_map/generators/engine_picker.rb

@@ -0,0 +1,51 @@
+module EngineMap
+  module Generators
+    Target = Struct.new(:name, :root, :namespace, :host, keyword_init: true) do
+      def label = host ? "#{name} (host app)" : name
+    end
+
+    class EnginePicker
+      def initialize(engines, app: nil, gem_paths: Gem.path, cwd: Dir.pwd, all: false)
+        @engines = engines
+        @app = app
+        @gem_paths = gem_paths.map { |p| File.expand_path(p) }
+        @cwd = File.expand_path(cwd)
+        @all = all
+      end
+
+      def targets
+        @targets ||= begin
+          list = @engines.reject { |e| !@all && installed_gem?(e.root) }.map { |e| build(e) }
+          list.unshift(build(@app, host: true)) if @app
+          list.uniq { |t| t.root.to_s }
+        end
+      end
+
+      # The target containing the current directory, if any.
+      def default
+        targets.select { |t| inside?(@cwd, t.root) }.max_by { |t| t.root.to_s.length }
+      end
+
+      def find(name)
+        targets.find { |t| t.name == name.to_s || t.namespace == name.to_s }
+      end
+
+      private
+
+      def build(engine, host: false)
+        klass = engine.class
+        name = host ? klass.module_parent_name.to_s.underscore : EngineMap.name_for(klass)
+        namespace = klass.railtie_namespace&.name || name.camelize
+        Target.new(name: name, root: Pathname.new(engine.root.to_s), namespace: namespace, host: host)
+      end
+
+      def installed_gem?(root)
+        @gem_paths.any? { |p| root.to_s.start_with?("#{p}/") }
+      end
+
+      def inside?(dir, root)
+        dir == root.to_s || dir.start_with?("#{root}/")
+      end
+    end
+  end
+end

data/lib/engine_map/generators/safe_files.rb

@@ -0,0 +1,90 @@
+require "fileutils"
+
+module EngineMap
+  module Generators
+    # Failsafe file edits for generators. Order of preference:
+    #   1. safe_inject  - add a line next to an anchor (no backup needed)
+    #   2. safe_replace - change existing text (writes a .backup first)
+    #   3. safe_rewrite - replace a whole file (writes a .backup first)
+    # Every method returns true if it changed something, false if not.
+    module SafeFiles
+      def safe_inject(path, text, after: nil, before: nil)
+        file = absolute_path(path)
+        return manual(path, text, "file not found", :red) unless File.exist?(file)
+
+        content = File.read(file)
+        return skipped(path) if content.include?(text.strip)
+
+        anchor = after || before
+        found = anchor.is_a?(Regexp) ? content.match?(anchor) : content.include?(anchor)
+        return manual(path, text, "anchor not found", :yellow) unless found
+
+        if after
+          inject_into_file path, "\n#{text.chomp}", after: after
+        else
+          inject_into_file path, "#{text.chomp}\n", before: before
+        end
+        true
+      end
+
+      def safe_replace(path, pattern, replacement)
+        file = absolute_path(path)
+        return manual(path, replacement, "file not found", :red) unless File.exist?(file)
+
+        content = File.read(file)
+        return skipped(path) if content.include?(replacement)
+        return manual(path, replacement, "pattern not found", :yellow) unless content.match?(pattern)
+
+        backup_file(path)
+        gsub_file path, pattern, replacement
+        true
+      end
+
+      def safe_rewrite(source, destination)
+        backup_file(destination) if File.exist?(absolute_path(destination))
+        template source, destination, force: true
+        true
+      end
+
+      private
+
+      def absolute_path(path)
+        File.expand_path(path, destination_root)
+      end
+
+      # Never overwrites an existing backup: file.backup, file.backup.1, ...
+      def backup_file(path)
+        file = absolute_path(path)
+        target = "#{file}.backup"
+        target = "#{file}.backup.#{target.split('.').last.to_i + 1}" while File.exist?(target)
+        FileUtils.cp(file, target)
+        say_status :backup, target.delete_prefix("#{destination_root}/"), :blue
+      end
+
+      # One "identical" line per file per run, however many steps inspect it.
+      def skipped(path)
+        @reported_skips ||= []
+        unless @reported_skips.include?(path)
+          @reported_skips << path
+          say_status :identical, "#{path} (already up to date)", :yellow
+        end
+        false
+      end
+
+      # For steps that can't even be attempted (no file to edit).
+      def needs_manual(message)
+        @manual_steps = (@manual_steps || 0) + 1
+        say_status :manual, message, :yellow
+        false
+      end
+
+      def manual(path, text, reason, color)
+        @manual_steps = (@manual_steps || 0) + 1
+        say_status :manual, "#{path} (#{reason})", color
+        say "  Add this by hand:", :bold
+        text.each_line { |line| say "    #{line.chomp}", :cyan }
+        false
+      end
+    end
+  end
+end

data/lib/engine_map/helpers.rb

@@ -0,0 +1,49 @@
+module EngineMap
+  module Helpers
+    def self.define_importmap_helper(name)
+      define_method("#{name.tr('-', '_')}_javascript_importmap_tags") do |entry_point = nil|
+        engine_javascript_importmap_tags(name, entry_point)
+      end
+    end
+
+    # engine_javascript_importmap_tags "admin"                  # entry "admin/application"
+    # engine_javascript_importmap_tags "admin", "admin/other"
+    def engine_javascript_importmap_tags(engine, entry_point = nil)
+      javascript_importmap_tags(entry_point || EngineMap.default_entry(engine),
+                                importmap: EngineMap.importmap_for(engine))
+    end
+
+    # engine_stylesheet_link_tags "my_engine", :all
+    # engine_stylesheet_link_tags "my_engine", "buttons", "forms"
+    def engine_stylesheet_link_tags(prefix, *sources, **options)
+      names = sources.include?(:all) ? engine_stylesheet_paths(prefix) : sources.map { |s| "#{prefix}/#{s}" }
+      stylesheet_link_tag(*names, **options)
+    end
+
+    private
+
+    def engine_stylesheet_paths(prefix)
+      if defined?(Propshaft)
+        Rails.application.assets.load_path.assets
+          .map { |asset| asset.logical_path.to_s }
+          .select { |path| path.start_with?("#{prefix}/") && path.end_with?(".css") }
+          .sort
+      else
+        sprockets_stylesheet_paths(prefix)
+      end
+    end
+
+    # Precompiled manifest first (the source tree may be absent in production),
+    # then the asset search paths. Sprockets resolves and digests the names itself.
+    def sprockets_stylesheet_paths(prefix)
+      manifest = Rails.application.respond_to?(:assets_manifest) ? Rails.application.assets_manifest : nil
+      listed = manifest ? manifest.assets.keys.select { |k| k.start_with?("#{prefix}/") && k.end_with?(".css") } : []
+      return listed.sort unless listed.empty?
+
+      Rails.application.config.assets.paths
+        .flat_map { |dir| Dir[File.join(dir.to_s, prefix, "*.css")] }
+        .map { |f| "#{prefix}/#{File.basename(f)}" }
+        .uniq.sort
+    end
+  end
+end

data/lib/engine_map/railtie.rb

@@ -0,0 +1,7 @@
+module EngineMap
+  class Railtie < ::Rails::Railtie
+    initializer "engine_map.helpers" do
+      ActiveSupport.on_load(:action_view) { include EngineMap::Helpers }
+    end
+  end
+end

data/lib/engine_map/version.rb

@@ -0,0 +1,3 @@
+module EngineMap
+  VERSION = "0.1.0"
+end

data/lib/engine_map.rb

@@ -0,0 +1,146 @@
+require "engine_map/version"
+require "engine_map/helpers"
+require "engine_map/railtie"
+
+module EngineMap
+  Registration = Struct.new(:name, :root, :importmap_path, keyword_init: true)
+
+  class << self
+    # Engines that called configure, as { "admin" => :merge }. Filled at boot.
+    def configured
+      @configured ||= {}
+    end
+
+    def registry
+      @registry ||= {}
+    end
+
+    # EngineMap.register "admin", root: Admin::Engine.root
+    def register(name, root:, importmap: nil)
+      name = name.to_s
+      root = Pathname.new(root)
+      registry[name] = Registration.new(
+        name: name, root: root,
+        importmap_path: Pathname.new(importmap || root.join("config/importmap.rb"))
+      )
+      Helpers.define_importmap_helper(name)
+      registry[name]
+    end
+
+    # Isolated engines keep their name (it matches their asset folder).
+    # Plain engines lose the "_engine" suffix Rails appends.
+    def name_for(engine_class)
+      base = engine_class.engine_name.to_s
+      engine_class.railtie_namespace ? base : base.delete_suffix("_engine")
+    end
+
+    # Called from an engine class body:
+    #   EngineMap.configure(self)                    # merge into host importmap (default)
+    #   EngineMap.configure(self, importmap: :own)   # independent map
+    #   EngineMap.configure(self, importmap: :both)
+    # The name is resolved inside initializers, after the class body (and
+    # isolate_namespace) has run.
+    def configure(engine, importmap: :merge, name: nil)
+      unless %i[merge own both].include?(importmap)
+        raise ArgumentError, "importmap must be :merge, :own or :both (got #{importmap.inspect})"
+      end
+      id = engine.name
+
+      engine.initializer "engine_map.record.#{id}" do
+        EngineMap.configured[name || EngineMap.name_for(engine)] = importmap
+      end
+
+      engine.initializer "engine_map.assets.#{id}" do |app|
+        js = engine.root.join("app/javascript")
+        app.config.assets.paths << js.to_s if app.config.respond_to?(:assets) && js.exist?
+      end
+
+      # Sprockets only serves what is listed for precompile. Propshaft needs nothing.
+      engine.initializer "engine_map.precompile.#{id}", after: "engine_map.assets.#{id}" do |app|
+        next if defined?(Propshaft) || !app.config.respond_to?(:assets) || !app.config.assets.respond_to?(:precompile)
+        EngineMap.sprockets_logical_names(engine.root, name || EngineMap.name_for(engine)).each do |logical|
+          app.config.assets.precompile << logical
+        end
+      end
+
+      # Make importmap-rails notice new or changed engine JS (host sweeper only
+      # watches the host's folders). Must run before importmap builds its watcher.
+      engine.initializer "engine_map.sweeper.#{id}", before: "importmap.cache_sweeper" do |app|
+        js = engine.root.join("app/javascript")
+        if EngineMap.reloading?(app) && js.exist? && app.config.respond_to?(:importmap)
+          app.config.importmap.cache_sweepers << js
+        end
+      end
+
+      if %i[merge both].include?(importmap)
+        engine.initializer "engine_map.importmap_merge.#{id}", before: "importmap" do |app|
+          file = engine.root.join("config/importmap.rb")
+          app.config.importmap.paths << file if file.exist? && app.config.respond_to?(:importmap)
+        end
+      end
+
+      if %i[own both].include?(importmap)
+        engine.initializer "engine_map.importmap_own.#{id}" do
+          EngineMap.register(name || EngineMap.name_for(engine), root: engine.root,
+                             importmap: engine.root.join("config/importmap.rb"))
+        end
+      end
+    end
+
+    # Logical names (e.g. "admin/base.css") of an engine's own assets, for
+    # config.assets.precompile. Sprockets needs plain strings, not globs or procs.
+    def sprockets_logical_names(root, name)
+      css = Dir[root.join("app/assets/stylesheets", name, "*.css")].map { |f| "#{name}/#{File.basename(f)}" }
+      js = Dir[root.join("app/javascript", name, "**/*.js")].map do |f|
+        f.delete_prefix("#{root.join('app/javascript')}/")
+      end
+      css + js
+    end
+
+    # Entry point the engine-only helper imports. Engines with their own
+    # Stimulus app pin "<name>/standalone"; everyone else uses application.
+    def default_entry(name)
+      file = registry.fetch(name.to_s).importmap_path
+      standalone = file.exist? && file.read.include?(%(pin "#{name}/standalone"))
+      standalone ? "#{name}/standalone" : "#{name}/application"
+    end
+
+    def reloading?(app = Rails.application)
+      app.config.respond_to?(:reloading_enabled?) && app.config.reloading_enabled?
+    end
+
+    def importmap_for(name)
+      watchers[name.to_s]&.execute_if_updated
+      registration = registry.fetch(name.to_s) do
+        raise ArgumentError, "No engine registered as #{name.inspect}. Registered: #{registry.keys.inspect}"
+      end
+      maps[registration.name] ||= build_map(registration).tap { watch(registration) }
+    end
+
+    private
+
+    def watchers
+      @watchers ||= {}
+    end
+
+    # Dev only: drop the cached map when the engine's importmap file or JS changes.
+    def watch(registration)
+      return unless reloading?
+      dirs = [registration.root.join("app/javascript")].select(&:exist?).to_h { |d| [d.to_s, ["js"]] }
+      watchers[registration.name] = Rails.application.config.file_watcher.new([registration.importmap_path.to_s], dirs) do
+        maps.delete(registration.name)
+      end
+    end
+
+    def maps
+      @maps ||= {}
+    end
+
+    def build_map(registration)
+      unless defined?(Importmap::Map)
+        raise LoadError, "importmap-rails is required for #{registration.name}_javascript_importmap_tags"
+      end
+      Importmap::Map.new.tap { |map| map.draw(registration.importmap_path) }
+    end
+  end
+end

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

@@ -0,0 +1,217 @@
+require "rails/generators"
+require "digest"
+require "engine_map/generators/safe_files"
+require "engine_map/generators/engine_picker"
+
+module EngineMap
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include SafeFiles
+      source_root File.expand_path("templates", __dir__)
+      desc "Set up engine asset helpers (stylesheets and importmap) in an engine."
+
+      ENGINE_CLASS = /class \w+ < (::)?Rails::Engine/
+      IMPORTMAP_TAGS = /<%= javascript_importmap_tags[^%]*%>/
+      STYLESHEET_TAG = /<%= stylesheet_link_tag [^%]*%>/
+
+      class_option :engine, type: :string, desc: "Engine name (skips the prompt)"
+      class_option :importmap, type: :string, default: "merge", enum: %w[merge own both],
+                   desc: "merge into host importmap, own independent map, or both"
+      class_option :stimulus, type: :string, default: "host", enum: %w[host own none],
+                   desc: "host Stimulus app, engine's own Stimulus app, or no controllers"
+      class_option :all, type: :boolean, default: false, desc: "Also list engines from installed gems"
+
+      def choose_target
+        picker = EnginePicker.new(candidates, app: app, all: options[:all])
+        @target = options[:engine] ? picker.find(options[:engine]) : (picker.default || prompt_for(picker))
+        raise Thor::Error, "No engine named #{options[:engine].inspect}. Try --all." unless @target
+
+        self.destination_root = @target.root.to_s
+        say_status :target, @target.label, :green
+        @before = snapshot
+      end
+
+      def configure_engine
+        return if host?
+        file = engine_file
+        return manual("lib/<engine>/engine.rb", configure_line, "engine class not found", :yellow) unless file
+        safe_inject file, %(require "engine_map"), before: /\A/
+        return if File.read(File.join(destination_root, file)).include?("EngineMap.configure")
+
+        safe_inject file, configure_line, after: ENGINE_CLASS
+      end
+
+      def add_gem_dependency
+        return if host?
+        spec = Dir[File.join(destination_root, "*.gemspec")].first
+        return needs_manual("no gemspec found (add `spec.add_dependency \"engine_map\"` by hand)") unless spec
+        safe_inject relative(spec), %(  spec.add_dependency "engine_map"), after: /^\s*spec\.add_dependency [^\n]*/
+      end
+
+      def create_javascript
+        return if host?
+        template "application.js.tt", "app/javascript/#{name}/application.js", skip: true
+        unless stimulus == "none"
+          template "example_controller.js.tt", "app/javascript/#{name}/controllers/example_controller.js", skip: true
+        end
+        template "standalone.js.tt", "app/javascript/#{name}/standalone.js", skip: true if stimulus == "own"
+        if File.exist?(File.join(destination_root, "config/importmap.rb"))
+          safe_inject "config/importmap.rb", importmap_lines, after: /\A[^\n]*/
+        else
+          template "importmap.rb.tt", "config/importmap.rb"
+        end
+      end
+
+      def create_stylesheet
+        return if host?
+        template "application.css.tt", "app/assets/stylesheets/#{name}/application.css", skip: true
+      end
+
+      def create_standalone_layout
+        return if host? || options[:importmap] != "both"
+        template "standalone.html.erb.tt", "app/views/layouts/#{name}/standalone.html.erb", skip: true
+      end
+
+      def update_layout
+        return if host?
+        layout = layout_file
+        unless layout
+          needs_manual("no layout found (add these inside <head> of the layout your engine uses)")
+          js = if options[:importmap] == "own"
+                 %(    <%= #{name}_javascript_importmap_tags %>)
+               else
+                 %(    <%= javascript_importmap_tags %>\n    <%= javascript_import_module_tag "#{name}/application" %>)
+               end
+          say %(    <%= engine_stylesheet_link_tags "#{name}", :all %>\n#{js}), :cyan
+          return
+        end
+
+        add_stylesheet_tag(layout)
+        has_tags = File.read(File.join(destination_root, layout)).match?(IMPORTMAP_TAGS)
+        if options[:importmap] == "own"
+          if has_tags
+            safe_replace layout, /(?<!\w)javascript_importmap_tags/, "#{name}_javascript_importmap_tags"
+          else
+            safe_inject layout, %(  <%= #{name}_javascript_importmap_tags %>), before: %r{^\s*</head>}
+          end
+        elsif has_tags
+          safe_inject layout, %(    <%= javascript_import_module_tag "#{name}/application" %>), after: IMPORTMAP_TAGS
+        else
+          safe_inject layout, %(  <%= javascript_importmap_tags %>\n  <%= javascript_import_module_tag "#{name}/application" %>),
+                      before: %r{^\s*</head>}
+        end
+      end
+
+      def wire_host
+        return unless host?
+        layout = "app/views/layouts/application.html.erb"
+        path = File.join(destination_root, layout)
+        if File.exist?(path) && !File.read(path).match?(IMPORTMAP_TAGS)
+          needs_manual("#{layout} has no javascript_importmap_tags (add it before </head>)")
+        end
+        check_sprockets_manifest
+        import_configured_engines
+      end
+
+      # Must stay the last public method: Rails runs public methods in order.
+      def finish
+        if @manual_steps.to_i > 0
+          say "\n#{@manual_steps} step(s) need a manual edit (see the 'manual' lines above).", :yellow
+        elsif snapshot == @before
+          say "\nEverything is already set up. Nothing left to do, please proceed.", :green
+        else
+          say "\nInstall complete. Backups (if any) are saved as *.backup next to the edited files.", :green
+        end
+      end
+
+      private
+
+      def check_sprockets_manifest
+        return if defined?(Propshaft)
+        manifest = "app/assets/config/manifest.js"
+        return needs_manual("#{manifest} not found (Sprockets must link app/javascript)") unless File.exist?(File.join(destination_root, manifest))
+        return if File.read(File.join(destination_root, manifest)).include?("javascript")
+        safe_inject manifest, "//= link_tree ../../javascript .js\n//= link_tree ../../../vendor/javascript .js", before: /\A/
+      end
+
+      def import_after_last(entry, line)
+        last = File.readlines(File.join(destination_root, entry)).grep(/^import\b.*["'];?\s*$/).last
+        if last
+          safe_inject entry, line, after: last.chomp
+        else
+          safe_inject entry, line, before: /\A/
+        end
+      end
+
+      def import_configured_engines
+        entry = "app/javascript/application.js"
+        names = EngineMap.configured.select { |_, mode| %i[merge both].include?(mode) }.keys.sort
+        return say_status(:skipped, "no engines using EngineMap in merge mode", :yellow) if names.empty?
+        return needs_manual("#{entry} not found (import each engine's application module by hand)") unless File.exist?(File.join(destination_root, entry))
+        names.each { |n| import_after_last(entry, %(import "#{n}/application")) }
+      end
+
+      def snapshot
+        files = Dir[File.join(destination_root, "{app,config,lib}/**/*"), File.join(destination_root, "*.gemspec")]
+        files.select { |f| File.file?(f) }.sort.map { |f| [f, Digest::MD5.file(f).hexdigest] }
+      end
+
+      def candidates = Rails.application.railties.select { |r| r.is_a?(Rails::Engine) }
+      def app = Rails.application
+      def host? = @target.host
+      def name = @target.name
+      def stimulus = options[:stimulus]
+
+      def add_stylesheet_tag(layout)
+        tag = %(<%= engine_stylesheet_link_tags "#{name}", :all %>)
+        content = File.read(File.join(destination_root, layout))
+        own = /<%= stylesheet_link_tag\s+["']#{Regexp.escape(name)}\/application["'][^%]*%>/
+        if content.match?(own)
+          safe_replace layout, own, tag
+        elsif content.match?(STYLESHEET_TAG)
+          safe_inject layout, "    #{tag}", after: STYLESHEET_TAG
+        else
+          safe_inject layout, "  #{tag}", before: %r{^\s*</head>}
+        end
+      end
+
+      def importmap_lines
+        lines = [%(pin "#{name}/application")]
+        unless stimulus == "none"
+          lines << %(pin_all_from File.expand_path("../app/javascript/#{name}/controllers", __dir__),\n) +
+                   %(             under: "controllers/#{name}", to: "#{name}/controllers")
+        end
+        if stimulus == "own"
+          lines << %(pin "#{name}/standalone")
+          lines << %(pin "@hotwired/stimulus", to: "stimulus.min.js")
+          lines << %(pin "@hotwired/stimulus-loading", to: "stimulus-loading.js")
+        end
+        lines.join("\n")
+      end
+
+      def configure_line
+        arg = options[:importmap] == "merge" ? "" : ", importmap: :#{options[:importmap]}"
+        "    EngineMap.configure(self#{arg})"
+      end
+
+      def relative(path) = Pathname.new(path).relative_path_from(Pathname.new(destination_root)).to_s
+
+      def engine_file
+        found = Dir[File.join(destination_root, "lib/**/*.rb")].find { |f| File.read(f).match?(ENGINE_CLASS) }
+        found && relative(found)
+      end
+
+      def layout_file
+        found = Dir[File.join(destination_root, "app/views/layouts/**/application.html.erb")].first
+        found && relative(found)
+      end
+
+      def prompt_for(picker)
+        say "Where should EngineMap be installed?", :bold
+        picker.targets.each_with_index { |t, i| say "  #{i + 1}. #{t.label}", :cyan }
+        answer = ask("Number:", limited_to: (1..picker.targets.size).map(&:to_s))
+        picker.targets[answer.to_i - 1]
+      end
+    end
+  end
+end

data/lib/generators/engine_map/install/templates/application.css.tt

@@ -0,0 +1,3 @@
+/* Styles for <%= @target.name %>. Every .css file in this folder is linked
+ * automatically by engine_stylesheet_link_tags "<%= @target.name %>", :all
+ * (alphabetical order, so application.css loads first). */

data/lib/generators/engine_map/install/templates/application.js.tt

@@ -0,0 +1,3 @@
+// JavaScript entry point for <%= @target.name %>.
+// Merged mode: imported by the layout via javascript_import_module_tag.
+// Own mode: imported by <%= @target.name %>_javascript_importmap_tags.

data/lib/generators/engine_map/install/templates/example_controller.js.tt

@@ -0,0 +1,6 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Use in views as: data-controller="<%= @target.name.dasherize %>--example"
+export default class extends Controller {
+  connect() {}
+}

data/lib/generators/engine_map/install/templates/importmap.rb.tt

@@ -0,0 +1,3 @@
+# Pins for <%= @target.name %>. Merged into the host importmap by default,
+# or used alone via <%= @target.name %>_javascript_importmap_tags.
+<%= importmap_lines %>

data/lib/generators/engine_map/install/templates/standalone.html.erb.tt

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= @target.name.titleize %></title>
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <%%= csrf_meta_tags %>
+  <%%= csp_meta_tag %>
+  <%%= yield :head %>
+
+  <%%= engine_stylesheet_link_tags "<%= @target.name %>", :all %>
+  <%%= <%= @target.name %>_javascript_importmap_tags %>
+</head>
+<body>
+  <%%= yield %>
+</body>
+</html>

data/lib/generators/engine_map/install/templates/standalone.js.tt

@@ -0,0 +1,10 @@
+// Entry point for <%= @target.name %>'s own importmap only. Never import this
+// from a merged layout: it starts a second Stimulus application.
+import "<%= @target.name %>/application"
+import { Application } from "@hotwired/stimulus"
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+
+const application = Application.start()
+eagerLoadControllersFrom("controllers", application)
+
+export { application }

data/lib/tasks/engine_map_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :engine_map do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: engine_map
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Baden
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Stylesheet :all helper, merged or independent importmaps, and namespaced
+  Stimulus controllers for Rails engines, on Propshaft or Sprockets, with an idempotent
+  install generator that backs up what it edits.
+email:
+- baden.rushworth@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/engine_map.rb
+- lib/engine_map/generators/engine_picker.rb
+- lib/engine_map/generators/safe_files.rb
+- lib/engine_map/helpers.rb
+- lib/engine_map/railtie.rb
+- lib/engine_map/version.rb
+- lib/generators/engine_map/install/install_generator.rb
+- lib/generators/engine_map/install/templates/application.css.tt
+- lib/generators/engine_map/install/templates/application.js.tt
+- lib/generators/engine_map/install/templates/example_controller.js.tt
+- lib/generators/engine_map/install/templates/importmap.rb.tt
+- lib/generators/engine_map/install/templates/standalone.html.erb.tt
+- lib/generators/engine_map/install/templates/standalone.js.tt
+- lib/tasks/engine_map_tasks.rake
+homepage: https://github.com/BadenRushworth/engine_map
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/BadenRushworth/engine_map
+  source_code_uri: https://github.com/BadenRushworth/engine_map
+  changelog_uri: https://github.com/BadenRushworth/engine_map/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Asset helpers and an install generator for Rails engines.
+test_files: []