thecore_generators 3.1.0 → 3.6.0

data/lib/generators/thecore/atom_aware.rb

@@ -30,21 +30,32 @@ module Thecore
 
       def initialize(*args)
         super
+        @host_app_root = destination_root
         self.destination_root = atom_dir if atom_dir
       end
 
+      # The true host-app root, captured before `destination_root` is
+      # (possibly) overridden above — for a real `rails generate` invocation
+      # this is `Rails::Command.root`, in tests whatever
+      # `Rails::Generators::TestCase` configured as `destination_root`.
+      # Unlike `destination_root` (which becomes the ATOM dir once
+      # overridden), this always stays the app root, giving
+      # Thecore::Generators::WorkspaceContext.model_root_for a stable anchor
+      # to search from regardless of where *this* invocation itself landed.
+      attr_reader :host_app_root
+
       # The absolute ATOM directory this generator's files should land in, or
       # nil for plain host-app context. Resolved once, before
       # `destination_root` is (possibly) overridden above, since the
-      # pre-override `destination_root` is the correct app-root anchor for
-      # resolving an explicit `--atom=NAME`.
+      # pre-override `destination_root` (== `host_app_root`) is the correct
+      # app-root anchor for resolving an explicit `--atom=NAME`.
       def atom_dir
         return @atom_dir if @atom_dir_resolved
 
         @atom_dir_resolved = true
         @atom_dir = Thecore::Generators::WorkspaceContext.atom_dir_for(
           cwd: Dir.pwd,
-          app_root: destination_root,
+          app_root: host_app_root,
           atom_name: options[:atom]
         )
       end

data/lib/generators/thecore/companion_files.rb

@@ -0,0 +1,142 @@
+require "yaml"
+
+module Thecore
+  module Generators
+    # Shared companion-file behavior for Thecore's own custom-action
+    # generators: ensuring config/initializers/after_initialize.rb and
+    # assets.rb exist and carry the right require/precompile line, and
+    # writing the RailsAdmin action's locale entries. Introduced by
+    # RootActionGenerator (thecore_generators#11) and reused as-is by
+    # MemberActionGenerator (thecore_generators#12).
+    #
+    # Faithful Ruby port of the corresponding parts of thecore_code_extension's
+    # addRootAction.js/addMemberAction.js: the after_initialize.rb/assets.rb
+    # ensure-and-append logic, and the locale-entry merge behavior — broadened
+    # per thecore_generators#11's acceptance criteria to write into every
+    # *.yml file already present under the locales directory, not just
+    # en.yml/it.yml (the JS original only ever touched those two).
+    #
+    # Deliberately duplicates (rather than shares) the after_initialize.rb
+    # skeleton Thecore::Generators::AssociationWiring already writes — same
+    # structure/anchor, so the two compose fine regardless of which one
+    # happens to create the file first, but kept separate to avoid touching
+    # already-shipped Phase 1 code for this ticket.
+    module CompanionFiles
+      AFTER_INITIALIZE_TEMPLATE = <<~RUBY.freeze
+        Rails.application.configure do
+            config.after_initialize do
+            end
+        end
+      RUBY
+
+      ASSETS_TEMPLATE = <<~RUBY.freeze
+        # PLEASE, uncomment if needed.
+        # For Example: in the case there's a root action called tcp_debug, add the following lines to include css and javascripts for auto loading:
+        # Rails.application.config.assets.precompile += %w(
+        #   main_tcp_debug.js
+        #   main_tcp_debug.css
+        # )
+      RUBY
+
+      private
+
+      # Renders the shared view/JS/SCSS companion trio for a RailsAdmin
+      # custom action (root or member) into the workspace's fixed
+      # app/views/rails_admin/main, app/assets/javascripts/rails_admin/actions,
+      # and app/assets/stylesheets/rails_admin/actions directories — the same
+      # relative paths regardless of ATOM vs host-app context (only the
+      # action's own controller-config file, handled by the including
+      # generator, is placed differently: lib/root_actions vs
+      # config/root_actions, and similarly for member actions).
+      # Requires "action.html.erb.tt"/"action.js.tt"/"action.scss.tt" to be
+      # present in the including generator's own source_paths. Takes no
+      # argument deliberately: the template bodies themselves read the
+      # including generator's own `file_name` (via NamedBase) through the ERB
+      # binding `template` evaluates them in, so a separate action-name
+      # argument here would only rename the destination files while the
+      # content inside kept using `file_name` — a silent name/content
+      # mismatch. Callers needing a different action name for content must
+      # get there via their own `file_name`, not a parameter to this method.
+      def render_view_js_scss_companions!
+        template "action.html.erb.tt", File.join("app/views/rails_admin/main", "#{file_name}.html.erb")
+        template "action.js.tt", File.join("app/assets/javascripts/rails_admin/actions", "#{file_name}.js")
+        template "action.scss.tt", File.join("app/assets/stylesheets/rails_admin/actions", "#{file_name}.scss")
+      end
+
+      # Ensures config/initializers/after_initialize.rb exists (creating it
+      # from the skeleton above if absent) and that `require_line` is present
+      # inside its `config.after_initialize do ... end` block — idempotently.
+      def ensure_after_initialize_require!(require_line)
+        path = "config/initializers/after_initialize.rb"
+        full_path = File.join(destination_root, path)
+
+        create_file(path, AFTER_INITIALIZE_TEMPLATE) unless File.exist?(full_path)
+
+        content = File.read(full_path)
+        if content.include?(require_line)
+          say_status :skip, "#{path} already requires it", :blue
+        else
+          insert_into_file(path, "        #{require_line}\n", after: /config\.after_initialize do\n/)
+        end
+      end
+
+      # Ensures config/initializers/assets.rb exists (creating it from the
+      # skeleton above if absent) and that `precompile_line` is appended to
+      # it — idempotently.
+      def ensure_assets_precompile_line!(precompile_line)
+        path = "config/initializers/assets.rb"
+        full_path = File.join(destination_root, path)
+
+        create_file(path, ASSETS_TEMPLATE) unless File.exist?(full_path)
+
+        content = File.read(full_path)
+        if content.include?(precompile_line)
+          say_status :skip, "#{path} already has the precompile line", :blue
+        else
+          append_to_file(path, "\n#{precompile_line}\n")
+        end
+      end
+
+      # Writes the RailsAdmin action's menu/title/breadcrumb locale entry
+      # (all three set to `title`, matching addRootAction.js/
+      # addMemberAction.js's mergeYaml behavior) under `admin.actions.<key>`
+      # into every *.yml file already present under config/locales — not just
+      # en.yml/it.yml, per thecore_generators#11's acceptance criteria. When
+      # the locales directory has no *.yml file yet, en.yml and it.yml are
+      # created first and then updated the same way.
+      def write_action_locale_entries!(key, title)
+        locales_dir = File.join(destination_root, "config", "locales")
+        existing = Dir.exist?(locales_dir) ? Dir.children(locales_dir).select { |f| f.end_with?(".yml") } : []
+
+        existing = %w[en.yml it.yml] if existing.empty?
+
+        existing.sort.each do |file|
+          rel_path = File.join("config", "locales", file)
+          full_path = File.join(destination_root, rel_path)
+          default_lang = File.basename(file, ".yml")
+
+          create_file(rel_path, "#{default_lang}:\n") unless File.exist?(full_path)
+          merge_action_locale_entry!(rel_path, default_lang, key, title)
+        end
+      end
+
+      # `lang` is the file's own single top-level key when it already has
+      # exactly one (the locale code, e.g. "en" in a Rails/Devise-style
+      # "devise.en.yml" whose filename does not equal its locale code) —
+      # falling back to `default_lang` (derived from the filename) only for
+      # an empty/freshly-created file, where there is nothing yet to read the
+      # real locale code from.
+      def merge_action_locale_entry!(rel_path, default_lang, key, title)
+        full_path = File.join(destination_root, rel_path)
+        data = YAML.load_file(full_path) || {}
+        lang = data.size == 1 ? data.keys.first : default_lang
+        data[lang] = {} unless data[lang].is_a?(Hash)
+        data[lang]["admin"] = {} unless data[lang]["admin"].is_a?(Hash)
+        data[lang]["admin"]["actions"] = {} unless data[lang]["admin"]["actions"].is_a?(Hash)
+        data[lang]["admin"]["actions"][key] = { "menu" => title, "title" => title, "breadcrumb" => title }
+
+        create_file(rel_path, YAML.dump(data), force: true, verbose: false)
+      end
+    end
+  end
+end

data/lib/generators/thecore/member_action/member_action_generator.rb

@@ -0,0 +1,61 @@
+require "rails/generators/named_base"
+require "generators/thecore/atom_aware"
+require "generators/thecore/companion_files"
+require "generators/thecore/action_companion"
+
+module Thecore
+  module Generators
+    # `rails generate thecore:member_action NAME` — a Ruby port of
+    # thecore_code_extension's addMemberAction.js (thecore_generators#12),
+    # the Member Action counterpart to RootActionGenerator
+    # (thecore_generators#11). Shares the entire generator step sequence and
+    # placement/naming logic with it via Thecore::Generators::ActionCompanion
+    # (see that module and RootActionGenerator's own comment) — only this
+    # class's own `templates/action.rb.tt`/`action.html.erb.tt`/
+    # `action.js.tt` are Member-specific: the RailsAdmin `:member` action
+    # type and its XHR + form PATCH example, matching what
+    # `addMemberAction.js` produces today (not unified with Root's fetch +
+    # ActionCable-broadcast template).
+    #
+    # Discovered automatically by Rails::Generators' own namespace-by-path
+    # convention (`generators/thecore/member_action/member_action_generator.rb`
+    # → "thecore:member_action") — no Railtie registration needed, same as
+    # RootActionGenerator.
+    class MemberActionGenerator < Rails::Generators::NamedBase
+      include Thecore::Generators::AtomAware
+      include Thecore::Generators::CompanionFiles
+      include Thecore::Generators::ActionCompanion
+
+      action_kind "member_action"
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Thin task methods, required on each class directly (see
+      # ActionCompanion's own comment for why) - each delegates to shared
+      # private logic there.
+      def validate_action_name!
+        validate_action_name_for_kind!
+      end
+
+      def create_action_file
+        template "action.rb.tt", action_file_path
+      end
+
+      def create_view_js_scss_companions
+        render_view_js_scss_companions!
+      end
+
+      def add_after_initialize_require
+        ensure_after_initialize_require!(require_line)
+      end
+
+      def add_assets_precompile_line
+        ensure_assets_precompile_line!(assets_precompile_line)
+      end
+
+      def add_locale_entries
+        write_action_locale_entries!(file_name, title_case_name)
+      end
+    end
+  end
+end

data/lib/generators/thecore/member_action/templates/action.html.erb.tt

@@ -0,0 +1,16 @@
+<%%= stylesheet_link_tag 'rails_admin/actions/<%= file_name %>' %>
+<%%= form_with(url: <%= file_name %>_path, html: { method: :patch }, class: "main", id: "<%= file_name %>-form") do |f| %>
+    <div class="form-actions row justify-content-end my-3">
+        <div class="col-sm-10">
+            <input name="return_to" type="hidden" value="<%%=edit_path(@abstract_model, @object.id)%>">
+            <button class="btn btn-primary" data-disable-with="Save" name="_save" type="submit">
+            <i class="fas fa-check"></i>
+            Test
+            </button>
+        </div>
+    </div>
+<%% end %>
+<!-- The button to test the xhr get request -->
+<button id="<%= file_name %>-id" class="btn btn-primary" data-url="<%%= rails_admin.<%= file_name %>_path %>">Test <%= file_name %></button>
+<div id="<%= file_name %>-response"></div>
+<%%= javascript_include_tag "rails_admin/actions/<%= file_name %>" %>

data/lib/generators/thecore/member_action/templates/action.js.tt

@@ -0,0 +1,44 @@
+var <%= action_name_camel_case %>Cable = null;
+// If the <%= action_name_camel_case %>Function is already defined, then don't redefine it and don't attach it to the eventListener
+if (typeof <%= action_name_camel_case %>Function !== 'function') {
+    function <%= action_name_camel_case %>Function(event) {
+        console.log('Hello from <%= file_name %>', event);
+        // Action Cable WebSocket connection only if <%= action_name_camel_case %>Cable is not already defined and valid
+        if (typeof <%= action_name_camel_case %>Cable !== 'object' || <%= action_name_camel_case %>Cable === null) {
+            <%= action_name_camel_case %>Cable = App.cable.subscriptions.create("ActivityLogChannel", {
+               connected() {
+                   console.log("Connected to the channel:", this);
+                   this.send({ message: '<%= file_name %> Client is connected', topic: "<%= file_name %>", namespace: "subscriptions" });
+               },
+               disconnected() {
+                   console.log("<%= file_name %> Client Disconnected");
+               },
+               received(data) {
+                   if(data["topic"] == "<%= file_name %>") {
+                       console.log("<%= file_name %>", data);
+                       document.getElementById('<%= file_name %>-response').innerHTML = data["message"];
+                   }
+               }
+           });
+        }
+        // Send a message to the server
+        <%= action_name_camel_case %>Cable.send({ message: '<%= file_name %> Client is sending a message', topic: "<%= file_name %>", namespace: "subscriptions" });
+        // Attach a click event listener to the button which sends an XHR GET request and shows the response.
+        // The URL is read from the data-url attribute to avoid ERB interpolation in plain .js files.
+        document.getElementById('<%= file_name %>-id').addEventListener('click', function() {
+            var url = this.dataset.url;
+            var xhr = new XMLHttpRequest();
+            xhr.open('GET', url, true);
+            xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
+            xhr.onreadystatechange = function() {
+                if (xhr.readyState == 4 && xhr.status == 200) {
+                    var response = JSON.parse(xhr.responseText);
+                    document.getElementById('<%= file_name %>-response').innerHTML = response.message;
+                }
+            }
+            xhr.send();
+        });
+    }
+}
+// Attach the function to the eventListener
+document.addEventListener('turbo:load', <%= action_name_camel_case %>Function);

data/lib/generators/thecore/member_action/templates/action.rb.tt

@@ -0,0 +1,25 @@
+RailsAdmin::Config::Actions.add_action "<%= file_name %>", :base, :member do
+    link_icon 'fas fa-file'
+    http_methods [:get, :patch]
+    # Customize visibility: show this action only for specific models.
+    # Example: visible only for the User model:
+    # visible do
+    #   bindings[:object].is_a?(::User)
+    # end
+    # Or use the default authorization check:
+    visible? authorized?
+    # Adding the controller which is needed to compute calls from the ui
+    controller do
+        proc do
+            # if it's a form submission, then update the password
+            if !request.xhr? && request.patch?
+                flash[:success] = I18n.t("Successfully clicked on sample action")
+                # Redirect to the object
+                redirect_to index_path(model_name: @abstract_model.to_param)
+            elsif request.xhr? && request.get?
+                # Return a json response
+                render json: { message: "Hello from <%= file_name %>" }, status: :ok
+            end
+        end
+    end
+end

data/lib/generators/thecore/member_action/templates/action.scss.tt

@@ -0,0 +1,38 @@
+// Spinner
+.loader {
+    width: 40px;
+    height: 40px;
+    position: relative;
+    margin: 0 auto;
+}
+.double-bounce1,
+.double-bounce2 {
+    width: 100%;
+    height: 100%;
+    border-radius: 50%;
+    background-color: #333;
+    opacity: 0.6;
+    position: absolute;
+    top: 0;
+    left: 0;
+    animation: sk-bounce 2.0s infinite ease-in-out;
+}
+.double-bounce2 {
+    animation-delay: -1.0s;
+}
+@keyframes sk-bounce {
+    0%,
+    100% {
+        transform: scale(0.0);
+    }
+    50% {
+        transform: scale(1.0);
+    }
+}
+// End Spinner
+#<%= file_name %>-response {
+    border-radius: 1em;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+}

data/lib/generators/thecore/migration/migration_generator.rb

@@ -1,5 +1,6 @@
 require "rails/generators/active_record/migration/migration_generator"
 require "generators/thecore/atom_aware"
+require "generators/thecore/association_wiring"
 
 module Thecore
   module Generators
@@ -9,17 +10,27 @@ module Thecore
     # Thecore::Generators::ModelGenerator for the namespace-resolution
     # mechanism, identical here).
     #
-    # A pure wrap: 100% of ActiveRecord::Generators::MigrationGenerator's
-    # migration-content logic (add/remove/create-table detection, attribute
-    # parsing, templates) is inherited untouched. The only addition is
-    # Thecore::Generators::AtomAware, redirecting the migration file into an
-    # ATOM's db/migrate when one is detected from `Dir.pwd`/`--atom=NAME`, so
-    # `rails generate migration AddBarToFoo bar:string` gets the same
-    # context-aware placement standalone, not just via `rails generate model`.
+    # 100% of ActiveRecord::Generators::MigrationGenerator's migration-content
+    # logic (add/remove/create-table detection, attribute parsing, templates)
+    # is inherited untouched. On top of that:
+    #   - Thecore::Generators::AtomAware redirects the migration file into an
+    #     ATOM's db/migrate when one is detected from `Dir.pwd`/`--atom=NAME`,
+    #     so `rails generate migration AddBarToFoo bar:string` gets the same
+    #     context-aware placement standalone, not just via `rails generate
+    #     model`.
+    #   - Thecore::Generators::AssociationWiring detects `references`
+    #     attributes and writes the missing inverse `has_many`/`has_one` side
+    #     into the target model's concern (ADR 0003 in the thecore repo).
     class MigrationGenerator < ActiveRecord::Generators::MigrationGenerator
       include Thecore::Generators::AtomAware
+      include Thecore::Generators::AssociationWiring
 
       source_root ActiveRecord::Generators::MigrationGenerator.source_root
+
+      def create_migration_file
+        super
+        wire_inverse_associations_from_references
+      end
     end
   end
 end

data/lib/generators/thecore/model/model_generator.rb

@@ -1,5 +1,6 @@
 require "rails/generators/active_record/model/model_generator"
 require "generators/thecore/atom_aware"
+require "generators/thecore/association_wiring"
 
 module Thecore
   module Generators
@@ -14,11 +15,19 @@ module Thecore
     # generation are inherited as-is. On top of that:
     #   - Thecore::Generators::AtomAware redirects placement into an ATOM's
     #     app/models + db/migrate when one is detected (see its own docs).
-    #   - `Api::ModelName`/`RailsAdmin::ModelName` concern files are
-    #     generated and `include`d into the model, replicating
-    #     thecore_code_extension's addModel.js templates exactly (unchanged
-    #     by this ticket — see thecore_generators#3 / ADR 0001 in the thecore
-    #     repo).
+    #   - `Api::ModelName`/`RailsAdmin::ModelName` concern files are NOT
+    #     generated by default (thecore_generators#4 / ADR 0001 in the
+    #     thecore repo): the no-customization case now relies entirely on
+    #     the default `json_attrs`/`navigation_label`/`navigation_icon`
+    #     modules that `model_driven_api` and `thecore_ui_rails_admin`
+    #     `include` into every `ApplicationRecord` subclass automatically
+    #     (`ThecoreBackendCommons::DefaultModuleRegistry`). Pass
+    #     `--with-api-concern`/`--with-admin-concern` to scaffold a starter
+    #     concern file — identical in shape to what this generator produced
+    #     before this ticket — for the case where customization is already
+    #     known to be needed at generation time. To add one later instead
+    #     (the common case), see the "Adding a concern by hand" section of
+    #     this gem's README.
     #   - `Endpoints::ModelName` is deliberately NOT generated (ADR 0001: it's
     #     never `include`d by default; add it by hand, following the
     #     after_initialize + class_eval pattern, only when a real custom
@@ -26,8 +35,25 @@ module Thecore
     #   - Test file generation is never suppressed (no `--skip-test-framework`
     #     equivalent) — `hook_for :test_framework` runs exactly as it does for
     #     `active_record:model`.
+    #   - Thecore::Generators::AssociationWiring detects `references`
+    #     attributes and writes the missing inverse `has_many`/`has_one` side
+    #     into the target model's concern (ADR 0003 in the thecore repo) —
+    #     needed here too, not just in MigrationGenerator, because
+    #     `rails generate model Foo x:references` creates its migration via
+    #     ActiveRecord::Generators::ModelGenerator#create_migration_file, a
+    #     different method than MigrationGenerator's own.
     class ModelGenerator < ActiveRecord::Generators::ModelGenerator
       include Thecore::Generators::AtomAware
+      include Thecore::Generators::AssociationWiring
+
+      class_option :with_api_concern, type: :boolean, default: false,
+        desc: "Scaffold a starter app/models/concerns/api/<model>.rb, included into the model " \
+          "(pre-thecore_generators#4 default behavior). Opt in only when customization is " \
+          "already known to be needed at generation time."
+      class_option :with_admin_concern, type: :boolean, default: false,
+        desc: "Scaffold a starter app/models/concerns/rails_admin/<model>.rb, included into the " \
+          "model (pre-thecore_generators#4 default behavior). Opt in only when customization is " \
+          "already known to be needed at generation time."
 
       # `source_root` (singular) must be set explicitly: Rails::Generators::Base's
       # auto-computed `default_source_root` derives its path from *this*
@@ -42,30 +68,44 @@ module Thecore
 
       def create_model_file
         super
-        add_default_concerns
+        add_opted_in_concerns
+      end
+
+      def create_migration_file
+        super
+        wire_inverse_associations_from_references
       end
 
       private
 
       # Faithful Ruby port of addModel.js's api_concern.rb/rails_admin_concern.rb
       # templates and its `include Api::X` / `include RailsAdmin::X` model-file
-      # rewrite — down to the exact generated content — per this ticket's
-      # explicit "unchanged, still generated exactly as today" scope (that
-      # removal is thecore_generators#6, gated on other work landing first).
-      def add_default_concerns
-        template "api_concern.rb", File.join("app/models/concerns/api", class_path, "#{file_name}.rb")
-        template "rails_admin_concern.rb", File.join("app/models/concerns/rails_admin", class_path, "#{file_name}.rb")
+      # rewrite — down to the exact generated content — kept available behind
+      # `--with-api-concern`/`--with-admin-concern` for the explicit
+      # customization-at-generation-time case (thecore_generators#4).
+      def add_opted_in_concerns
+        include_lines = +""
+
+        if options[:with_api_concern]
+          template "api_concern.rb", File.join("app/models/concerns/api", class_path, "#{file_name}.rb")
+          include_lines << "  include Api::#{class_name}\n"
+        end
+
+        if options[:with_admin_concern]
+          template "rails_admin_concern.rb", File.join("app/models/concerns/rails_admin", class_path, "#{file_name}.rb")
+          include_lines << "  include RailsAdmin::#{class_name}\n"
+        end
 
-        include_default_concerns_in_model
+        include_opted_in_concerns_in_model(include_lines) unless include_lines.empty?
       end
 
-      def include_default_concerns_in_model
+      def include_opted_in_concerns_in_model(include_lines)
         model_file = File.join("app/models", class_path, "#{file_name}.rb")
         simple_class_name = class_name.split("::").last
 
         insert_into_file(
           model_file,
-          "  include Api::#{class_name}\n  include RailsAdmin::#{class_name}\n",
+          include_lines,
           after: /class #{Regexp.escape(simple_class_name)} < .*\n/
         )
       end

data/lib/generators/thecore/root_action/root_action_generator.rb

@@ -0,0 +1,80 @@
+require "rails/generators/named_base"
+require "generators/thecore/atom_aware"
+require "generators/thecore/companion_files"
+require "generators/thecore/action_companion"
+
+module Thecore
+  module Generators
+    # `rails generate thecore:root_action NAME` — a Ruby port of
+    # thecore_code_extension's addRootAction.js (thecore_generators#11),
+    # producing the same end result from a terminal: the RailsAdmin root
+    # action file, its view/JS/SCSS companions, the after_initialize.rb
+    # require line, the assets.rb precompile line, and locale entries — with
+    # ATOM-aware placement via the same Thecore::Generators::AtomAware
+    # mechanism the Model/Migration generators already use.
+    #
+    # Discovered automatically by Rails::Generators' own namespace-by-path
+    # convention (this file's path derives the "thecore:root_action"
+    # namespace) — no Railtie registration needed, unlike
+    # ModelGenerator/MigrationGenerator, since there is no built-in Rails
+    # generator being overridden here.
+    #
+    # Unlike ModelGenerator/MigrationGenerator, Thecore::Generators::AtomAware
+    # only supplies `atom_dir`/`host_app_root` and the `--atom` option here —
+    # this generator does not override `destination_root` placement for a
+    # single fixed subpath the way Model/Migration's templates do, because the
+    # action file itself lives at a *different* relative path depending on
+    # context (ATOM: lib/root_actions/, host app: config/root_actions/ — see
+    # docs/adr/0001-main-app-actions-live-in-config.md in
+    # thecore_code_extension for why the host-app side avoids lib/). AtomAware
+    # still redirects `destination_root` into the ATOM dir when one is
+    # detected, so the view/JS/SCSS/locale/after_initialize/assets companions
+    # (fixed relative paths, shared with the host-app case) land in the right
+    # place automatically.
+    #
+    # The full generator step sequence (validate → create_action_file →
+    # create_view_js_scss_companions → add_after_initialize_require →
+    # add_assets_precompile_line → add_locale_entries) and everything about
+    # placement/naming lives in Thecore::Generators::ActionCompanion, shared
+    # with MemberActionGenerator (thecore_generators#12) — only this class's
+    # own `templates/action.rb.tt`/`action.html.erb.tt`/`action.js.tt` (the
+    # RailsAdmin `:root` action type and its fetch + ActionCable-broadcast
+    # example) are Root-specific.
+    class RootActionGenerator < Rails::Generators::NamedBase
+      include Thecore::Generators::AtomAware
+      include Thecore::Generators::CompanionFiles
+      include Thecore::Generators::ActionCompanion
+
+      action_kind "root_action"
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Thin task methods, required on each class directly (see
+      # ActionCompanion's own comment for why) - each delegates to shared
+      # private logic there.
+      def validate_action_name!
+        validate_action_name_for_kind!
+      end
+
+      def create_action_file
+        template "action.rb.tt", action_file_path
+      end
+
+      def create_view_js_scss_companions
+        render_view_js_scss_companions!
+      end
+
+      def add_after_initialize_require
+        ensure_after_initialize_require!(require_line)
+      end
+
+      def add_assets_precompile_line
+        ensure_assets_precompile_line!(assets_precompile_line)
+      end
+
+      def add_locale_entries
+        write_action_locale_entries!(file_name, title_case_name)
+      end
+    end
+  end
+end

data/lib/generators/thecore/root_action/templates/action.html.erb.tt

@@ -0,0 +1,13 @@
+<%%= stylesheet_link_tag 'rails_admin/actions/<%= file_name %>' %>
+<div class="card mb-3">
+  <div class="card-body">
+    <div class="response <%= file_name %>-response" id="<%= file_name %>-response">
+    </div>
+    <div class="loader d-none" id="<%= file_name %>-loader">
+      <div class="double-bounce1"></div>
+      <div class="double-bounce2"></div>
+    </div>
+  </div>
+</div>
+<button class="btn btn-primary" id="<%= file_name %>-id" data-url="<%%= rails_admin.<%= file_name %>_path %>">Click me</button>
+<%%= javascript_include_tag "rails_admin/actions/<%= file_name %>" %>