thecore_generators 3.8.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43638f50febe1bf078edcf5e5490c33709065db0a522f2b14a659c9ae19954ab
-  data.tar.gz: 368b0b26a79a4a5be2ccc394e0dd4d64061efb1c66aa099d124432a1455e4230
+  metadata.gz: 146693a69bac954bb16fae029f76d60a5f92d2702f90d1cfda0b19e8a4e1a796
+  data.tar.gz: 728d2a12604ebb33b6efa6c7e27e33f7b086e3f61f7042492e5db0d4f9772b6c
 SHA512:
-  metadata.gz: a0a7cb2fc271fe3f495ad2a4234ba338fc9e9b50f8309e2aefc593777d85fc8fa5b5146698f7000009a2da0552e1a89cd296e680a0003c99f6bca09e1b962e7e
-  data.tar.gz: 7495d392354b1f1834b8fba5117449f3b9383aa6df89f4bd637c9044bc7c3357f2136d316385b89057b2a851047887df7c49f94db5a7aa97641a91189ea05510
+  metadata.gz: 738f18d403082dedbbfc4ce40a3376bc03c5057c6789a63436114bf135e262e6127e201c44a65c7ce76a0423eaab0cc198705d47501057d855c96b634ba1ec33
+  data.tar.gz: 3559b1310d5d59046158ec81232bc8b86a527c05130c605b571589a65f11c23566b119029d9f36a35b985351b13d31306c66acfbb2f5ee281d6b259a95b2dcd7

data/README.md

@@ -25,10 +25,22 @@ thecore:check_practices` (Scaffold Files + Models + Actions, `--fix` included) a
 **Phase 3's App application template** (porting `createApp.js`) is complete as of this release —
 both the core (`lib/templates/app_template.rb`: Rails app + Gemfile stack + vendor placeholders,
 thecore_generators#17) and devcontainer/CI/CLAUDE.md asset fetching from the thecore repo's own
-samples (thecore_generators#18) have shipped. The `thecore:atom` generator and a Collection
-Action generator remain deferred to a future session (ADR 0005). See
+samples (thecore_generators#18) have shipped. See
 [ADR 0005](https://github.com/gabrieletassoni/thecore/blob/release/3/docs/adr/0005-app-template-scoped-to-rails-new-m-assets-sourced-from-thecore-samples.md)
-in the thecore repo for the full design.
+in the thecore repo for the full design. **The Collection Action generator** (`rails generate
+thecore:collection_action`, thecore_generators#21) is also complete as of this release — see
+[ADR 0006](https://github.com/gabrieletassoni/thecore/blob/master/docs/adr/0006-atom-generator-dual-ci-manual-submodule-wiring-collection-action-reuses-existing-infra.md)
+in the thecore repo (`master`, thecore's actual default branch — unlike this gem's own
+`release/3`; the ADR 0001-0005 links above predate that distinction being double-checked; note
+that as of this gem's 3.11.0 release the ADR 0006 commit exists only in a local `thecore`
+checkout, not yet pushed to `origin/master` — same class of operational sequencing issue
+`CLAUDE.md` documents for the App template's samples fetch). **`thecore:atom`**
+(`rails generate thecore:atom NAME`, thecore_generators#20/#22) is feature-complete as of this
+release, including its `CLAUDE.md` fetch from thecore's own `samples/ATOM_CLAUDE.md` — but that
+fetch shares the exact same not-yet-pushed caveat as ADR 0006/the App template's own samples
+fetch above: it 404s against the real default GitHub URL until `thecore`'s `master` actually
+carries the commit that added `samples/ATOM_CLAUDE.md`. Phase 4's one remaining piece is
+documenting both new generators in the thecore repo's `GUIDE.md`/`WALKTHROUGH.md` (thecore#19).
 
 ### What `rails generate model`/`rails generate migration` do now
 
@@ -207,6 +219,92 @@ templates exactly:
   XHR `GET` here vs. `fetch` there), and the view adds a `form_with(..., method: :patch)` for
   the PATCH half of the example.
 
+### `rails generate thecore:atom NAME`
+
+A Ruby port of `thecore_code_extension`'s `createATOM.js` — produces a complete, working ATOM
+(a Rails engine, the Thecore unit of modular functionality) from a terminal, no VS Code
+required:
+
+```bash
+rails generate thecore:atom tcp_debugger
+```
+
+Unlike every other generator in this gem, `thecore:atom` takes **no `--atom=NAME` option** —
+creating a *new* ATOM only ever makes sense from a host app's own root, so it doesn't include
+`Thecore::Generators::AtomAware` at all. It fails fast with a clear error if `vendor/submodules/`
+doesn't exist yet in the current app, if `NAME` isn't a valid gem name (lowercase letters,
+digits, underscores, hyphens, starting with a letter), or if `vendor/submodules/<NAME>` already
+exists — the last one matters because `rails plugin new`'s own `-f` (force) flag would otherwise
+silently overwrite an existing ATOM with the same name.
+
+It prompts (interactively, or via `--summary=`/`--description=`/`--author=`/`--email=`/`--url=`
+with `--non-interactive`) for the same five fields `createATOM.js` always has, then:
+
+- Shells to `rails plugin new <path> -fG --skip-gemfile-entry --skip-hotwire --full` (via
+  `bundle exec`, for robust gem resolution regardless of environment), producing the standard
+  Rails engine skeleton.
+- Asks (`yes?`-style, default yes; `--skip-api-admin-deps` in non-interactive mode) whether to
+  add `model_driven_api`/`thecore_ui_rails_admin` as dependencies — at this gem's own ADR 0001
+  floor (`~> 3.9`/`~> 3.8`), not `createATOM.js`'s stale `~> 3.1`/`~> 3.2`. Declining adds
+  neither; the Scaffold Files/directories below are created either way.
+- Creates the same Scaffold Files/directories `createATOM.js` always has: `db/migrate`, the
+  API/RailsAdmin concern directories, `config/initializers`, `config/locales`,
+  `lib/root_actions`/`member_actions`/`collection_actions`, JS/CSS asset directories, the
+  RailsAdmin main view directory, `.github/workflows` — plus `after_initialize.rb`/`assets.rb`/
+  `abilities.rb`, `db/seeds.rb`, and `en.yml`/`it.yml` locale files, all with the same skeleton
+  content `createATOM.js` already produces.
+- Generates **both** `.github/workflows/gempush.yml` and `.gitlab-ci.yml` unconditionally — no
+  hosting-profile prompt (see ADR 0006 for why: which git host a developer pushes to is a
+  per-developer choice this ecosystem already treats as generic). `gempush.yml`'s two
+  long-standing bugs are fixed here (a broken `awk` pipeline computing the version string; a
+  `version_exists` check referenced in `if:` conditions but never actually set, so the
+  tag/publish steps have never run for any ATOM generated this way). The gemspec's
+  `allowed_push_host` stays hardcoded to `https://rubygems.org`.
+- Rewrites the gemspec's authors/email/homepage/summary/description/metadata fields via targeted
+  in-memory substitutions (not `createATOM.js`'s own blind full-file line rewrite, which —
+  verified directly against a current `rails plugin new --full` gemspec — silently drops the
+  gem's own `rails` dependency when adding the two Thecore ones; this appends instead of
+  replacing).
+- `git init`s the new ATOM directory with one initial commit, then **logs** (never runs) the
+  exact follow-up commands to create a remote and `git submodule add` it into the host app —
+  worded generically, no GitHub/GitLab assumption (ADR 0006: automating a remote-repo-creating,
+  credential-dependent step isn't something this generator does on your behalf).
+- Adds `gem "<name>", path: "vendor/submodules/<name>"` to the host app's own `Gemfile` (via
+  Thor's own `gem` action) — skipped, with a warning, if the Gemfile already declares a gem with
+  that name (the same real collision the `vendor/submodules/<NAME>` guard above protects against,
+  one layer up: a duplicate entry for the same gem breaks the next `bundle install`). Does
+  **not** run `bundle install` — same as every other generator in this gem that touches a
+  Gemfile.
+- Fetches a `CLAUDE.md` skeleton from `thecore`'s own `samples/ATOM_CLAUDE.md` and writes it as
+  the new ATOM's `CLAUDE.md`, via `Thecore::Generators::SampleFetcher` — a shared module using
+  the exact same `THECORE_SAMPLES_SOURCE` override mechanism the App template's own asset fetch
+  already established (`ENV["THECORE_SAMPLES_SOURCE"]`, defaulting to `thecore`'s `master`
+  branch; http(s) fetched over the network, anything else read as a local directory; fails fast
+  with a clear message naming the file/source/error on failure). Like the App template's own
+  `CLAUDE.md`/`.gitlab-ci.yml` fetches, this 404s against the real default URL until `thecore`'s
+  `master` actually carries the commit that added `samples/ATOM_CLAUDE.md` — see the caveat
+  above.
+
+### `rails generate thecore:collection_action NAME`
+
+The third sibling to `thecore:root_action`/`thecore:member_action` — structurally identical
+(same shared `AtomAware`/`CompanionFiles`/`ActionCompanion` modules, same file layout, same
+`--atom=NAME`/idempotent-re-run behavior). Unlike Root/Member, there's no
+`addCollectionAction.js` this ports — `checkPractices.js` audited `collection_actions` but
+nothing ever generated them, so this is new, not a port:
+
+```bash
+rails generate thecore:collection_action my_action
+```
+
+Its own `templates/action.rb.tt` mirrors Root Action's simplicity — `add_action "my_action",
+:base, :collection do ... end`, a minimal GET/JSON example with an `ActivityLogChannel`
+broadcast — rather than the more complex, hand-written `save_filters.rb`/`load_filters.rb`
+pattern already living in `thecore_ui_rails_admin`: a generator's starter template exists to be
+customized from a simple base, not to demonstrate every RailsAdmin `:collection` feature. A
+collection action operates against a model's whole index (all records), as distinct from a
+member action (one record) or a root action (global, no model scope at all).
+
 ### `rails thecore:check_practices`
 
 A Ruby port of `thecore_code_extension`'s `checkPractices.js` — audits **Scaffold Files**
@@ -237,17 +335,15 @@ Flags combine freely, e.g. `rails thecore:check_practices -- --atom=my_atom --fi
   `cattr_accessor :json_attrs` for `Api::`, `rails_admin do` for `RailsAdmin::`). Not fixable —
   regenerating over an existing, hand-edited concern could clobber real customization.
 - **Actions** — scans `root_actions`, `member_actions`, and `collection_actions` (in `lib/` for
-  an ATOM, `config/` for the host app), with the same rules for all three:
-  `collection_actions` is scanned even though no generator creates files there yet, since a
-  hand-written one could already exist and go unreported otherwise. Reports missing/broken
-  action-file markers (`RailsAdmin::Config::Actions.add_action`, `http_methods` — never
-  fixable), a missing companion view/JS/SCSS or one present but missing its own marker (a
-  *missing* companion is fixable for `root_action`/`member_action`, by delegating straight to
-  that generator's own template rendering — never for `collection_action`, which has no
-  generator to delegate to; an *existing* companion missing a marker is never fixable, same
-  reasoning as Models), a missing `after_initialize.rb` require line (fixable, all three
-  kinds), and a missing locale entry checked against **every** `*.yml` already present in the
-  locales directory, not just `en`/`it` (fixable, all three kinds).
+  an ATOM, `config/` for the host app), with the same rules for all three. Reports
+  missing/broken action-file markers (`RailsAdmin::Config::Actions.add_action`, `http_methods`
+  — never fixable), a missing companion view/JS/SCSS or one present but missing its own marker
+  (a *missing* companion is fixable for all three kinds — `root_action`/`member_action`/
+  `collection_action` — by delegating straight to that kind's own generator's template
+  rendering; an *existing* companion missing a marker is never fixable, same reasoning as
+  Models), a missing `after_initialize.rb` require line (fixable, all three kinds), and a
+  missing locale entry checked against **every** `*.yml` already present in the locales
+  directory, not just `en`/`it` (fixable, all three kinds).
 
 Default output is human-readable text grouped by file; `--json` emits
 `{ "violations": [{ "file", "line", "message", "severity", "fixable", "code" }] }` — `code` is
@@ -255,9 +351,10 @@ a stable identifier (e.g. `missing_after_initialize`, `orphan_api_include`,
 `missing_companion_view`) a future consumer can filter on without depending on `message` text.
 `--fix` applies every fixable violation in one pass with no confirmation of its own — whoever
 passes it has already decided — then re-scans and reports/exits based on whatever violations
-remain (so a violation this run can't fix, e.g. a `collection_action` companion, still shows up
-after `--fix`). The task exits non-zero whenever any violation remains, zero otherwise, so it's
-usable as a CI gate either with or without `--fix`.
+remain (so a violation this run can't fix, e.g. an action file's own broken
+`RailsAdmin::Config::Actions.add_action` marker, still shows up after `--fix`). The task exits
+non-zero whenever any violation remains, zero otherwise, so it's usable as a CI gate either
+with or without `--fix`.
 
 ### Application Template (`rails new -m`) (thecore_generators#17/#18)
 
@@ -294,9 +391,12 @@ for the full design and why the two stay separate).
 - **Devcontainer/CI/CLAUDE.md**, fetched from the `thecore` repo's own `samples/` (single source
   of truth, not duplicated here) and written unconditionally, overwriting whatever the bootstrap
   "Setup Devcontainer" step created: `.devcontainer/*` (base image, plugin mounts, `gh`/`glab`
-  CLI config mounts commented out by default), `.gitlab-ci.yml` (build/test/lint/deploy, no
-  customer-specific paths), and `CLAUDE.md` (universal sections only, project-specific sections
-  left as TODO placeholders). The fetch location is one overridable point,
+  CLI config mounts commented out by default), **both** `.gitlab-ci.yml` and
+  `.github/workflows/ci.yml` (build/test/lint/deploy, no customer-specific paths — no hosting-
+  profile prompt, same git-hosting-agnostic reasoning ADR 0006 established for `thecore:atom`'s
+  own dual-CI generation, extended here by ADR 0007/thecore_generators#25), and `CLAUDE.md`
+  (universal sections only, project-specific sections left as TODO placeholders). The fetch
+  location is one overridable point,
   `ENV["THECORE_SAMPLES_SOURCE"]`, defaulting to the raw GitHub URL for `thecore`'s `samples/`
   on `master` (`thecore`'s actual default branch).
 - **The standard installer chain** (`devise:install`, `rails_admin:install`, `active_storage:
@@ -304,8 +404,16 @@ for the full design and why the two stay separate).
   each preceded by the necessary `bundle install`) is genuinely optional, gated behind an
   interactive prompt (`yes?`, wrapped in `after_bundle` so it only ever runs once the gems
   above are actually bundled) — a developer bootstrapping without network access can decline
-  and run these by hand later. There is no non-interactive/unattended flag for this in the
-  current version (tracked as a future improvement, not silently missing).
+  and run these by hand later.
+- **Non-interactive/unattended mode**: set `THECORE_APP_TEMPLATE_NON_INTERACTIVE` (any non-blank
+  value) to bypass the installer-chain prompt above. When set, `THECORE_APP_TEMPLATE_RUN_INSTALLERS`
+  (`"true"` or `"false"`) is required — the template aborts with a clear message if it's missing
+  or unrecognized, rather than guessing. Example:
+  ```bash
+  THECORE_APP_TEMPLATE_NON_INTERACTIVE=1 THECORE_APP_TEMPLATE_RUN_INSTALLERS=true \
+    rails new myapp --database=postgresql --asset-pipeline=sprockets \
+    -m https://raw.githubusercontent.com/gabrieletassoni/thecore_generators/release/3/lib/templates/app_template.rb
+  ```
 
 ## Installation
 

data/lib/generators/thecore/association_wiring.rb

@@ -1,4 +1,5 @@
 require "generators/thecore/workspace_context"
+require "generators/thecore/tty_detection"
 
 module Thecore
   module Generators
@@ -114,7 +115,7 @@ module Thecore
       # includer was explicitly told not to prompt via --non-interactive) -
       # default straight to has_many, per ADR 0003.
       def interactive_association_prompt?
-        !options[:non_interactive] && $stdin.tty? && $stdout.tty?
+        !options[:non_interactive] && Thecore::Generators::TtyDetection.real_tty?
       end
 
       def concern_path_for(target_class_name)

data/lib/generators/thecore/atom/atom_generator.rb

@@ -0,0 +1,481 @@
+require "rails/generators/named_base"
+require "generators/thecore/tty_detection"
+require "generators/thecore/sample_fetcher"
+require "shellwords"
+require "yaml"
+
+module Thecore
+  module Generators
+    # `rails generate thecore:atom NAME` (thecore_generators#20, per ADR 0006 in the
+    # thecore repo) — a Ruby port of thecore_code_extension's createATOM.js, producing
+    # a complete, working ATOM end-to-end from a terminal: no VS Code, no extension
+    # required.
+    #
+    # Unlike every other generator in this gem, AtomGenerator does NOT include
+    # Thecore::Generators::AtomAware and takes no --atom=NAME option — creating a
+    # *new* ATOM is only ever a host-app-root operation (it makes no sense to run
+    # "from inside" an ATOM that doesn't exist yet). destination_root therefore stays
+    # fixed at the host app root for the whole generator; every path this class writes
+    # is expressed relative to that root via #atom_root ("vendor/submodules/<name>"),
+    # not via AtomAware's destination_root-redirection trick.
+    #
+    # Two Gemfiles are in play here — the host app's own (destination_root/Gemfile)
+    # and the freshly-scaffolded ATOM's own (vendor/submodules/<name>/Gemfile) — which
+    # is why Rails::Generators::Actions#gem (used once, in #add_gem_to_host_gemfile)
+    # can't be reused for the ATOM's own Gemfile: #gem's own implementation always
+    # writes through `in_root { ... }`, and Thor::Actions#in_root is hardcoded to
+    # `@destination_stack.first` (the *original* destination_root), not whatever
+    # #inside might currently have pushed — so it can never be redirected to a nested
+    # path. The ATOM's own Gemfile is instead mutated via plain #append_to_file calls
+    # against an explicit relative path.
+    class AtomGenerator < Rails::Generators::NamedBase
+      class_option :non_interactive, type: :boolean, default: false,
+        desc: "Skip all interactive prompts; every required value must be supplied " \
+              "via --summary/--description/--author/--email/--url, and the " \
+              "API/Admin dependency choice defaults to included unless " \
+              "--skip-api-admin-deps is also passed"
+      class_option :summary, type: :string, default: nil,
+        desc: "The ATOM's one-line summary (required with --non-interactive)"
+      class_option :description, type: :string, default: nil,
+        desc: "The ATOM's longer description (required with --non-interactive)"
+      class_option :author, type: :string, default: nil,
+        desc: "The ATOM's author name (required with --non-interactive)"
+      class_option :email, type: :string, default: nil,
+        desc: "The ATOM author's email (required with --non-interactive)"
+      class_option :url, type: :string, default: nil,
+        desc: "The ATOM's homepage URL (required with --non-interactive)"
+      class_option :skip_api_admin_deps, type: :boolean, default: false,
+        desc: "Don't add model_driven_api/thecore_ui_rails_admin as dependencies " \
+              "(only consulted with --non-interactive; interactively this is its " \
+              "own yes/no prompt, default yes)"
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Validated the same way as createATOM.js's own six prompts: every field must
+      # be present; email must contain "@"; url must start with "http". Order matches
+      # the original prompt sequence.
+      REQUIRED_STRING_FIELDS = {
+        "summary" => ->(v) { !v.to_s.strip.empty? },
+        "description" => ->(v) { !v.to_s.strip.empty? },
+        "author" => ->(v) { !v.to_s.strip.empty? },
+        "email" => ->(v) { v.to_s.include?("@") },
+        "url" => ->(v) { v.to_s.start_with?("http") },
+      }.freeze
+
+      # This gem's own ADR 0001 floor (matching the App template's already-corrected
+      # versions) — not createATOM.js's stale "~> 3.1"/"~> 3.2".
+      MODEL_DRIVEN_API_VERSION = "~> 3.9"
+      THECORE_UI_RAILS_ADMIN_VERSION = "~> 3.8"
+
+      # Faithful port of templates/createATOM/after_initialize.rb /
+      # templates/createATOM/assets.rb in thecore_code_extension — static content,
+      # no per-ATOM interpolation, so these are plain constants rather than .tt files.
+      AFTER_INITIALIZE_CONTENT = <<~RUBY
+        Rails.application.configure do
+            config.after_initialize do
+                # For example, it can be used to load a root action defined in lib, for example:
+                # require 'root_actions/tcp_debug'
+            end
+        end
+      RUBY
+
+      ASSETS_CONTENT = <<~RUBY
+        # 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
+
+      # Faithful port of createATOM.js's addCICDFiles gempush.yml, with its two
+      # long-standing bugs fixed (thecore_generators#20 acceptance criteria): the awk
+      # pipeline computing the version string had a stray, unmatched `)` instead of a
+      # closing `}'`; and `version_exists` was referenced in two steps' `if:`
+      # conditions but never actually set anywhere (the "check" step only ever did
+      # `echo $?`), so those two steps have never run for any ATOM generated this way.
+      # Fixed here by actually writing `version_exists` to $GITHUB_ENV based on
+      # whether a git tag for the computed version already exists - kept as an
+      # `env.*`-style if: condition (not switched to `steps.*.outputs.*`) to stay as
+      # close to the original's structure as the fix allows.
+      GEMPUSH_YML_CONTENT = <<~YAML
+        name: Ruby Gem
+        on: push
+        jobs:
+          build:
+            name: Build + Publish
+            runs-on: ubuntu-latest
+            steps:
+              - uses: actions/checkout@v3
+              - name: Check if version already exists
+                run: |
+                  version=$(grep -oP 'VERSION = "\\K[^"]+' lib/*/version.rb | awk -F'.' '{print $1"."$2"."$3}')
+                  git fetch --unshallow --tags
+                  if git rev-parse "$version" >/dev/null 2>&1; then
+                    echo "version_exists=true" >> "$GITHUB_ENV"
+                  else
+                    echo "version_exists=false" >> "$GITHUB_ENV"
+                  fi
+              - name: Set git tag
+                if: env.version_exists == 'false'
+                run: |
+                  git config --local user.email "noreply@alchemic.it"
+                  git config --local user.name "AlchemicIT"
+                  version=$(grep -oP 'VERSION = "\\K[^"]+' lib/*/version.rb | awk -F'.' '{print $1"."$2"."$3}')
+                  git tag -a $version -m "Version $version"
+                  git push --tags
+              - name: Publish to RubyGems
+                if: env.version_exists == 'false'
+                env:
+                  GEM_HOST_API_KEY: ${{secrets.RUBYGEMS_AUTH_TOKEN}}
+                run: |
+                  mkdir -p $HOME/.gem
+                  touch $HOME/.gem/credentials
+                  chmod 0600 $HOME/.gem/credentials
+                  printf -- "---\\n:rubygems_api_key: ${GEM_HOST_API_KEY}\\n" > $HOME/.gem/credentials
+                  gem build *.gemspec
+                  gem push *.gem
+      YAML
+
+      SCAFFOLD_DIRECTORIES = %w[
+        db/migrate
+        app/models/concerns/api
+        app/models/concerns/rails_admin
+        config/initializers
+        config/locales
+        lib/root_actions
+        lib/member_actions
+        lib/collection_actions
+        app/assets/javascripts
+        app/assets/stylesheets
+        app/views/rails_admin/main
+        .github/workflows
+      ].freeze
+
+      # Gem-name convention (matches real examples in this very ecosystem, including
+      # the hyphenated `thecore-spot-overrides`) - lowercase, starting with a letter,
+      # letters/digits/underscore/hyphen only. Deliberately stricter than NamedBase's
+      # own permissive `name` parsing: without this, a name containing a space or
+      # shell metacharacter would flow straight into the unescaped shell-out in
+      # #create_rails_engine (word-splitting or, worse, executing arbitrary shell),
+      # and a namespaced name (`acme/widget`) would desync #atom_root (which uses
+      # only #file_name, "widget") from #class_name (which uses the full namespaced
+      # "Acme::Widget"), breaking the abilities.rb template.
+      NAME_PATTERN = /\A[a-z][a-z0-9_-]*\z/
+
+      def validate_atom_name!
+        return if file_name.match?(NAME_PATTERN)
+
+        raise Thor::Error,
+          "'#{file_name}' is not a valid ATOM name - use lowercase letters, digits, " \
+          "underscores, or hyphens, starting with a letter (e.g. tcp_debugger)."
+      end
+
+      def ensure_submodules_dir_exists!
+        return if File.directory?(File.join(destination_root, "vendor", "submodules"))
+
+        raise Thor::Error,
+          "vendor/submodules does not exist under #{destination_root} - run `rails generate " \
+          "thecore:atom` from a Thecore host app root that already has it (see the App " \
+          "application template, thecore_generators#17/#18) before creating an ATOM."
+      end
+
+      # `rails plugin new`'s own `-f` (force) suppresses its normal file-collision
+      # prompt, so without this guard a name colliding with an existing ATOM (a real
+      # scenario in this very host app: `vendor/submodules/mytask` already exists)
+      # would silently overwrite that ATOM's working tree with freshly-generated
+      # plugin skeleton files - caught during review, reproduced directly against
+      # this app's own real `mytask` submodule.
+      def ensure_atom_does_not_already_exist!
+        return unless File.exist?(File.join(destination_root, atom_root))
+
+        raise Thor::Error,
+          "#{atom_root} already exists - choose a different name, or remove it first if you " \
+          "really mean to regenerate it."
+      end
+
+      def validate_non_interactive_options!
+        return unless effectively_non_interactive?
+
+        missing = REQUIRED_STRING_FIELDS.reject { |key, valid| valid.call(options[key]) }.keys
+        return if missing.empty?
+
+        raise Thor::Error,
+          "Missing required flags for --non-interactive: #{missing.map { |k| "--#{k}" }.join(", ")}"
+      end
+
+      def collect_metadata
+        @summary = required_field("summary", "the summary of the ATOM, i.e. TCP Debugger")
+        @description = required_field("description", "the description of the ATOM, i.e. TCP Debugger")
+        @author = required_field("author", "the author of the ATOM, i.e. Alchemic IT")
+        @email = required_field("email", "the email of the ATOM author")
+        @url = required_field("url", "the url of the ATOM")
+      end
+
+      def collect_api_admin_deps_choice
+        @include_api_admin_deps =
+          if effectively_non_interactive?
+            !options[:skip_api_admin_deps]
+          else
+            ask(
+              "Include model_driven_api/thecore_ui_rails_admin as dependencies?",
+              default: "yes", limited_to: %w[yes no]
+            ) == "yes"
+          end
+      end
+
+      # Faithful to createATOM.js's own `rails plugin new "<path>" -fG
+      # --skip-gemfile-entry --skip-hotwire --full` invocation, cwd'd to
+      # vendor/submodules (via #inside, which - unlike file-writing actions below -
+      # genuinely changes the OS process's cwd for #run's sake). `bundle exec` is a
+      # deliberate addition over the JS original (which shells a bare `rails`,
+      # relying entirely on whatever's globally on PATH): it makes gem resolution
+      # explicit rather than incidental, and costs nothing in the real host-app case,
+      # where cwd already sits under that app's own Gemfile either way. `file_name`
+      # is Shellwords-escaped even though #validate_atom_name! already restricts it
+      # to a shell-safe character set - defense in depth, matching the same care
+      # #git_init_and_commit already takes with the free-text @author/@email.
+      def create_rails_engine
+        inside("vendor/submodules") do
+          run("bundle exec rails plugin new #{Shellwords.escape(file_name)} " \
+                "-fG --skip-gemfile-entry --skip-hotwire --full",
+            abort_on_failure: true)
+        end
+      end
+
+      # #create_file already `mkdir_p`s its own parent directory, so a separate
+      # #empty_directory call per entry would just be redundant work (and, for the
+      # 3 of these 12 that #create_scaffold_files/#create_locale_files/
+      # #create_ci_files populate with a real file moments later, entirely so).
+      def create_scaffold_directories
+        SCAFFOLD_DIRECTORIES.each { |dir| create_file(File.join(atom_root, dir, ".keep")) }
+      end
+
+      def create_scaffold_files
+        create_file File.join(atom_root, "config/initializers/after_initialize.rb"), AFTER_INITIALIZE_CONTENT
+        create_file File.join(atom_root, "config/initializers/add_to_db_migration.rb"),
+          "Rails.application.config.paths['db/migrate'] << File.expand_path(\"../../db/migrate\", __dir__)\n"
+        create_file File.join(atom_root, "config/initializers/assets.rb"), ASSETS_CONTENT
+        template "abilities.rb.tt", File.join(atom_root, "config/initializers/abilities.rb")
+        template "seeds.rb.tt", File.join(atom_root, "db/seeds.rb")
+      end
+
+      # Bare "en:\n"/"it:\n", matching the exact convention
+      # Thecore::Generators::CompanionFiles#write_action_locale_entries! already uses
+      # for this identical "no locale file yet" bootstrap case elsewhere in this gem
+      # - not the YAML-document-with-null-value shape `{"en"=>nil}.to_yaml` produces,
+      # which is equivalent once parsed but an unnecessary second on-disk convention
+      # for the same thing.
+      def create_locale_files
+        create_file File.join(atom_root, "config/locales/en.yml"), "en:\n"
+        create_file File.join(atom_root, "config/locales/it.yml"), "it:\n"
+      end
+
+      def create_ci_files
+        create_file File.join(atom_root, ".github/workflows/gempush.yml"), GEMPUSH_YML_CONTENT
+
+        gitlab_ci = {
+          "image" => "gabrieletassoni/vscode-devcontainers-thecore:3",
+          "variables" => {
+            "GITLAB_EMAIL" => @email,
+            "GITLAB_USER_NAME" => @author,
+            "GITLAB_GEM_REPO_TARGET" => 'https://${GEM_HOST}/',
+            "GEM_HOST_API_KEY" => '${GEMS_REPO_CREDENTIALS}',
+          },
+          "stages" => %w[build release],
+          "build_gem" => {
+            "rules" => [{ "if" => "$CI_COMMIT_TAG", "when" => "never" }, { "when" => "always" }],
+            "stage" => "build",
+            "script" => ["/usr/bin/gem-compile.sh"],
+          },
+        }
+        create_file File.join(atom_root, ".gitlab-ci.yml"), gitlab_ci.to_yaml
+      end
+
+      def setup_gemfile
+        gemfile_addition = +"\ngem 'pg'\n"
+        gemfile_addition << "gem 'model_driven_api', '#{MODEL_DRIVEN_API_VERSION}'\n" \
+          "gem 'thecore_ui_rails_admin', '#{THECORE_UI_RAILS_ADMIN_VERSION}'\n" if @include_api_admin_deps
+        append_to_file File.join(atom_root, "Gemfile"), gemfile_addition
+
+        return unless @include_api_admin_deps
+
+        append_to_file File.join(atom_root, "lib", "#{file_name}.rb"),
+          "\nrequire 'model_driven_api'\nrequire 'thecore_ui_rails_admin'\n"
+      end
+
+      # One read, one write, one pass of in-memory substitutions - not createATOM.js's
+      # own blind "rewrite every line, branching on substring" approach (the current
+      # `rails plugin new --full` gemspec template, verified directly against a real
+      # generation rather than assumed from the JS original, has moved on
+      # significantly: new `homepage_uri`/`license` lines, different summary/
+      # description wording - a full-file line-by-line port would silently stop
+      # matching several of these fields), and not 8 separate #gsub_file calls
+      # either (each its own full read-modify-write cycle against the same small
+      # file - wasted I/O for no benefit). One deliberate correctness fix over the
+      # original along the way: the JS's `.add_dependency` branch *replaces* the
+      # whole line, which happens to be `spec.add_dependency "rails", ...` in
+      # current Rails - silently dropping the gem's own Rails dependency entirely.
+      # This appends the two Thecore dependencies right after that line instead of
+      # replacing it.
+      def setup_gemspec
+        gemspec_path = File.join(atom_root, "#{file_name}.gemspec")
+        content = File.read(File.join(destination_root, gemspec_path))
+
+        content = content.sub(/^(\s*spec\.add_dependency\s+["']rails["'].*)$/) do
+          next Regexp.last_match(1) unless @include_api_admin_deps
+
+          "#{Regexp.last_match(1)}\n  spec.add_dependency \"model_driven_api\", \"#{MODEL_DRIVEN_API_VERSION}\"\n" \
+            "  spec.add_dependency \"thecore_ui_rails_admin\", \"#{THECORE_UI_RAILS_ADMIN_VERSION}\""
+        end
+        content = content.sub(/^\s*spec\.authors\s*=.*$/, "  spec.authors     = [#{@author.to_s.inspect}]")
+        content = content.sub(/^\s*spec\.email\s*=.*$/, "  spec.email       = [#{@email.to_s.inspect}]")
+        content = content.sub(/^\s*spec\.homepage\s*=.*$/, "  spec.homepage    = #{@url.to_s.inspect}")
+        content = content.sub(/^\s*spec\.summary\s*=.*$/, "  spec.summary     = #{@summary.to_s.inspect}")
+        content = content.sub(/^\s*spec\.description\s*=.*$/, "  spec.description = #{@description.to_s.inspect}")
+        content = content.sub(/^\s*spec\.metadata\["allowed_push_host"\]\s*=.*$/,
+          '  spec.metadata["allowed_push_host"] = "https://rubygems.org"')
+        content = content.sub(/^\s*spec\.metadata\["source_code_uri"\]\s*=.*$/,
+          '  spec.metadata["source_code_uri"] = spec.homepage')
+        content = content.sub(/^\s*spec\.metadata\["changelog_uri"\]\s*=.*$/,
+          '  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"')
+
+        create_file gemspec_path, content, force: true
+      end
+
+      # Completes this generator's scope (thecore_generators#22, ADR 0006): fetches
+      # thecore's own samples/ATOM_CLAUDE.md and writes it as the new ATOM's
+      # CLAUDE.md, via the shared Thecore::Generators::SampleFetcher - the same
+      # THECORE_SAMPLES_SOURCE mechanism the App template's own (separate, still
+      # independent - see sample_fetcher.rb's own header for why) asset fetch
+      # already established.
+      #
+      # A fetch failure here raises SystemExit (via Kernel#abort), not Thor::Error
+      # like every guard method above - a deliberate inconsistency, not an
+      # oversight: it matches the App template's own established convention for
+      # this exact class of failure (an external, this-run-only fetch, as opposed
+      # to a validation the generator could have caught before doing any real
+      # work), and the ticket's own acceptance criteria asks for "fail-fast abort,"
+      # not a Thor::Error. A failure here does leave the partially-generated
+      # vendor/submodules/<name> directory behind (rails plugin new/the Gemfile/
+      # gemspec edits already succeeded) - #ensure_atom_does_not_already_exist!
+      # then refuses a same-named retry until it's removed by hand; the abort
+      # message says so.
+      #
+      # NOTE: like the App template's own fetch of thecore/samples/CLAUDE.md
+      # before it, this 404s against the real default GitHub URL until thecore's
+      # `master` actually carries the commit that added samples/ATOM_CLAUDE.md
+      # (thecore#18) - as of this gem's 3.11.0 release that commit exists only in
+      # a local `thecore` checkout, not yet pushed. Same operational sequencing
+      # note as the App template's own CLAUDE.md section: push `thecore` before
+      # relying on the default in production.
+      def fetch_claude_md
+        Thecore::Generators::SampleFetcher.fetch_thecore_sample(
+          self, "ATOM_CLAUDE.md", File.join(atom_root, "CLAUDE.md"), label: "the thecore:atom generator"
+        )
+      end
+
+      # `-fG` (`rails plugin new`'s own force+skip-git flags) means no git repo and no
+      # .gitignore exist yet at this point - a deliberate gap in createATOM.js this
+      # ticket narrows, not fully closes (ADR 0006): a local, safe `git init` +
+      # initial commit, but remote creation and `git submodule add` stay a logged,
+      # human-run follow-up rather than something this generator automates. No
+      # .gitignore is written (out of this ticket's scope - see ADR 0006/the ticket's
+      # own acceptance criteria, which doesn't list one): verified directly that a
+      # fresh `rails plugin new --full` output has no log/tmp/sqlite artifacts yet to
+      # need ignoring - nothing has been bundled or run against the dummy app at this
+      # point, so the initial commit is clean regardless.
+      def git_init_and_commit
+        atom_path = File.join(destination_root, atom_root)
+        committed = inside(atom_root) do
+          run("git init -q -b master", abort_on_failure: true)
+          run("git add -A", abort_on_failure: true)
+          # Not abort_on_failure: a freshly-generated tree always has something to
+          # commit in normal use, but `git commit` failing (e.g. "nothing to
+          # commit", however that state arose) shouldn't kill the whole process via
+          # a raw, unexplained Kernel#abort when every file this generator actually
+          # promises has already been written successfully by this point. The
+          # result is still checked below, so a real failure changes what gets
+          # logged rather than being silently treated as success.
+          run(
+            "git -c user.name=#{Shellwords.escape(@author)} -c user.email=#{Shellwords.escape(@email)} " \
+              'commit -q -m "Initial commit"',
+            abort_on_failure: false
+          )
+        end
+
+        if committed
+          say_status :next_steps, <<~MSG.strip, :yellow
+            #{file_name} is git-initialized locally with one commit, but has no remote yet. To finish wiring it in:
+              1. Create a repository for it on the git host of your choice (GitHub, GitLab, ...)
+              2. cd #{atom_path} && git remote add origin <remote-url> && git push -u origin master
+              3. From this app's root: git submodule add <remote-url> vendor/submodules/#{file_name}
+          MSG
+        else
+          say_status :warning, <<~MSG.strip, :red
+            #{file_name} was git-initialized, but `git commit` did not succeed - it has no commit
+            yet. Check the output above, commit by hand once resolved, then follow the usual
+            steps to create a remote and `git submodule add` it into this app.
+          MSG
+        end
+      end
+
+      # Guards against the same name-collision scenario #ensure_atom_does_not_already_exist!
+      # protects the ATOM directory itself from: a host Gemfile that already
+      # declares a same-named gem (real in this very host app - `mytask` is
+      # resolved from a gem server today) would otherwise get a second, conflicting
+      # `gem "mytask", path: ...` line appended, and the next `bundle install`
+      # fails outright ("You cannot specify the same gem twice"). In the normal
+      # case (no prior entry) this is unreachable in practice anyway, since
+      # #ensure_atom_does_not_already_exist! already refuses a name whose
+      # vendor/submodules/<name> directory exists - kept as its own explicit check
+      # since a Gemfile entry and a vendor/submodules directory are two independent
+      # pieces of state that could in principle drift apart.
+      def add_gem_to_host_gemfile
+        gemfile_path = File.join(destination_root, "Gemfile")
+        if File.exist?(gemfile_path) && File.read(gemfile_path).match?(/^\s*gem\s+["']#{Regexp.escape(file_name)}["']/)
+          say_status :skip, "Gemfile already declares '#{file_name}' - not adding a second entry", :yellow
+          return
+        end
+
+        gem file_name, path: "vendor/submodules/#{file_name}"
+      end
+
+      private
+
+      def atom_root
+        File.join("vendor", "submodules", file_name)
+      end
+
+      # True whenever prompting for input isn't viable: --non-interactive was
+      # passed explicitly, or (via the shared Thecore::Generators::TtyDetection,
+      # also used by AssociationWiring's own `interactive_association_prompt?`)
+      # there's no real TTY behind stdin/stdout at all - a CI runner or a
+      # shelled-out child process that simply forgot the flag. Without this,
+      # #required_field's own `ask`-in-a-loop would spin forever re-prompting a
+      # stream that can never supply input, since a closed/EOF stdin makes Thor's
+      # `ask` return nil immediately.
+      def effectively_non_interactive?
+        options[:non_interactive] || !Thecore::Generators::TtyDetection.real_tty?
+      end
+
+      # Interactive: loop with Thor's own `ask` until the validator passes, echoing
+      # the same "not valid, try again" wording createATOM.js's input boxes used.
+      # Non-interactive (explicit or TTY-detected): already validated present by
+      # #validate_non_interactive_options! (a task method that always runs first),
+      # so this simply reads the option.
+      def required_field(key, prompt_hint)
+        return options[key] if effectively_non_interactive?
+
+        validate = REQUIRED_STRING_FIELDS.fetch(key)
+        loop do
+          value = ask("Enter #{prompt_hint}:")
+          return value if validate.call(value)
+
+          say_status :error, "The #{key} is not valid. Please try again.", :red
+        end
+      end
+
+    end
+  end
+end

data/lib/generators/thecore/atom/templates/abilities.rb.tt

@@ -0,0 +1,16 @@
+module Abilities
+    class <%= class_name %>
+        include CanCan::Ability
+        def initialize user
+            if user.present?
+                # Users' abilities
+                # Example: can :read, ModelName
+                # Example: can [:read, :create], ModelName
+                if user.admin?
+                    # Admins' abilities
+                    # Example: can :manage, :all
+                end
+            end
+        end
+    end
+end

data/lib/generators/thecore/atom/templates/seeds.rb.tt

@@ -0,0 +1 @@
+puts "Seeding Data into DB from <%= file_name %>"

data/lib/generators/thecore/collection_action/collection_action_generator.rb

@@ -0,0 +1,64 @@
+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:collection_action NAME` (thecore_generators#21,
+    # per ADR 0006 in the thecore repo) — the third sibling to
+    # RootActionGenerator/MemberActionGenerator. Unlike those two, there is
+    # no prior thecore_code_extension JS command this ports (no
+    # `addCollectionAction.js` ever existed — collection_actions were only
+    # ever audited by check_practices, never generated), so its own
+    # `templates/action.rb.tt` deliberately mirrors RootActionGenerator's
+    # simplicity (a minimal GET/JSON example with an ActivityLogChannel
+    # broadcast) rather than the real, more complex hand-written
+    # `save_filters.rb`/`load_filters.rb` pattern already living in
+    # thecore_ui_rails_admin — a generator's starter template exists to be
+    # customized from a simple base, not to demonstrate every RailsAdmin
+    # :collection feature.
+    #
+    # Structurally identical to RootActionGenerator/MemberActionGenerator:
+    # same three includes, same thin task-method sequence (see
+    # ActionCompanion's own comment for why those can't be shared further),
+    # only `action_kind` and this class's own templates differ. No changes
+    # needed anywhere in AtomAware/CompanionFiles/ActionCompanion —
+    # `action_kind "collection_action"` alone is enough for placement
+    # (lib/collection_actions or config/collection_actions),
+    # pluralization, and validation wording to fall out correctly.
+    class CollectionActionGenerator < Rails::Generators::NamedBase
+      include Thecore::Generators::AtomAware
+      include Thecore::Generators::CompanionFiles
+      include Thecore::Generators::ActionCompanion
+
+      action_kind "collection_action"
+
+      source_root File.expand_path("templates", __dir__)
+
+      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/collection_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 %>" %>

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

@@ -0,0 +1,42 @@
+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 a fetch 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;
+            document.getElementById('<%= file_name %>-loader').classList.remove('d-none');
+            fetch(url, { headers: { 'Accept': 'application/json' } })
+            .then(response => response.json())
+            .then(data => {
+                console.log(data);
+                document.getElementById('<%= file_name %>-response').innerHTML = data.message;
+                document.getElementById('<%= file_name %>-loader').classList.add('d-none');
+           });
+       });
+    }
+}
+// Attach the function to the eventListener
+document.addEventListener('turbo:load', <%= action_name_camel_case %>Function);

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

@@ -0,0 +1,33 @@
+RailsAdmin::Config::Actions.add_action "<%= file_name %>", :base, :collection do
+    # show_in_sidebar/show_in_navigation/breadcrumb_parent are deliberately not
+    # overridden here (unlike a root action) - RailsAdmin's own :collection
+    # defaults already do the right thing: sidebar-visible, not top-nav, and
+    # breadcrumbing back to the model's index page.
+    # This ensures the action only shows up for authorized users
+    visible? authorized?
+    # Have a look at https://fontawesome.com/v5/search for available icons
+    link_icon 'fas fa-file'
+    # The controller which will be used to compute the action and the REST verbs it will respond to
+    http_methods [:get]
+    # Adding the controller which is needed to compute calls from the ui
+    # This is a collection action: it runs against the whole model index (all
+    # records), not a single record (member) or globally (root) - @abstract_model
+    # is available here to scope the collection this action operates on.
+    controller do
+        proc do # This is needed because we need that this code is re-evaluated each time is called
+            if request.format.json?
+                # This is the code that is executed when the action is called
+                # It is executed in the context of the controller
+                # So you can access all the controller methods
+                # and instance variables
+                status = 200
+                message = "Hello World!"
+                # Note: ActivityLogChannel is expected to re-broadcast messages from the "messages" channel
+                ActionCable.server.broadcast("messages", { topic: :<%= file_name %>, status: status, message: message})
+                render json: {message: message}.to_json, status: status
+            else
+                # Renders the action.html.erb view for browser requests (HTML format)
+            end
+        end
+    end
+end

data/lib/generators/thecore/collection_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/sample_fetcher.rb

@@ -0,0 +1,68 @@
+module Thecore
+  module Generators
+    # Fetches one asset from thecore's own samples/ directory, via one overridable
+    # point: ENV["THECORE_SAMPLES_SOURCE"], resolved fresh on every call (never
+    # memoized), defaulting to the real raw GitHub URL for thecore's samples/ on
+    # `master` (thecore's own default branch). An http(s) value is fetched over the
+    # network via Thor's `get`; anything else is treated as a local directory and
+    # read directly with `File.read` (this gem's own tests point it at a fixture,
+    # so the suite runs offline and deterministically). Blank-string-safe
+    # (`nil? || empty?`, not `||` alone — `ENV["X"] || default` would treat
+    # THECORE_SAMPLES_SOURCE="" as a real override). Always writes `force: true` —
+    # a clean overwrite, no interactive Thor conflict prompt. Fails fast, naming
+    # the file/source/underlying error, rather than letting a raw
+    # OpenURI::HTTPError propagate and leave the caller half-scaffolded.
+    #
+    # A plain module function, not a mixin — `get`/`create_file` are public
+    # Thor::Actions instance methods (verified directly against Thor's own
+    # source), so they're callable on any `actor` passed in. `abort` (Kernel's) is
+    # private, so it's invoked via `actor.send(:abort, ...)` rather than a direct
+    # call — the one place this differs from calling it bare on `self`.
+    #
+    # A trailing slash on THECORE_SAMPLES_SOURCE is tolerated (`.chomp("/")`) before
+    # building the http(s) URL - a natural way to write/copy a base URL, and one
+    # `lib/templates/app_template.rb`'s own independent copy does not guard against
+    # (its own plain string interpolation would request a double-slashed path,
+    # 404ing against most static hosts/CDNs); caught here during review and not
+    # backported there, since that copy is intentionally left untouched (see below).
+    #
+    # AtomGenerator uses this module directly (`require`d normally, like any other
+    # file in this gem). The App application template's own `fetch_thecore_sample`
+    # (lib/templates/app_template.rb) is a *separate*, deliberately self-contained
+    # copy, NOT switched to call this module — that generator's initial version
+    # of this comment claimed the reason was instance_eval/mixin incompatibility,
+    # which review correctly identified as wrong (a module function needs no
+    # inheritance/mixin relationship to its caller; TtyDetection is proof this
+    # already works the same way from an instance_eval'd context). The real
+    # reason is deployment, not syntax: the App template's primary real-world
+    # invocation is `rails new myapp -m https://raw.githubusercontent.com/.../app_template.rb`
+    # — Thor's `apply`/`instance_eval` fetches and evaluates *that one URL's
+    # content only*, with no mechanism to also pull in a sibling file from this
+    # gem's own repo the way a normal `require` would. At the moment that command
+    # runs there is no app yet, so nothing has installed `thecore_generators` as a
+    # dependency either — a `require "generators/thecore/sample_fetcher"` inside
+    # the template would only work by accident (a global gem install happening to
+    # already be on the load path), not by design. So the App template keeps its
+    # own independent copy, and this module is not a hard requirement it could
+    # `require` — extracting it here still removes the duplication between this
+    # module and AtomGenerator, `thecore_generators`' own second, in-gem consumer.
+    module SampleFetcher
+      module_function
+
+      def fetch_thecore_sample(actor, relative_path, destination, label:)
+        source = ENV["THECORE_SAMPLES_SOURCE"]
+        source = "https://raw.githubusercontent.com/gabrieletassoni/thecore/master/samples" if source.nil? || source.empty?
+
+        if source.start_with?("http://", "https://")
+          actor.get("#{source.chomp("/")}/#{relative_path}", destination, force: true)
+        else
+          actor.create_file(destination, File.read(File.join(source, relative_path)), force: true)
+        end
+      rescue StandardError => e
+        actor.send(:abort, "Failed to fetch #{relative_path} from #{source} (#{e.class}: #{e.message}) " \
+          "-- aborting #{label}. Set THECORE_SAMPLES_SOURCE to override the source. If this left " \
+          "a partially-generated directory behind, remove it before retrying.")
+      end
+    end
+  end
+end

data/lib/generators/thecore/tty_detection.rb

@@ -0,0 +1,19 @@
+module Thecore
+  module Generators
+    # A caller with no real TTY behind stdin/stdout (CI, a shelled-out child
+    # process) can never answer an interactive prompt. Shared by
+    # AssociationWiring's own inverse-association cardinality prompt and
+    # AtomGenerator's metadata/dependency prompts, extracted after the two
+    # independently implemented the identical condition (caught in review,
+    # thecore_generators#20) - a single source of truth means a future
+    # refinement to this detection (e.g. an ENV["CI"] check) can't silently
+    # apply to one generator's prompts and not the other's.
+    module TtyDetection
+      module_function
+
+      def real_tty?
+        $stdin.tty? && $stdout.tty?
+      end
+    end
+  end
+end

data/lib/templates/app_template.rb

@@ -153,6 +153,10 @@ chmod ".devcontainer/link-host-home.sh", 0o755
 chmod ".devcontainer/check-plugins.sh", 0o755
 
 fetch_thecore_sample(".gitlab-ci.yml", ".gitlab-ci.yml")
+# thecore_generators#25 (ADR 0007): fetched unconditionally, alongside .gitlab-ci.yml above --
+# no hosting-profile prompt, same reasoning ADR 0006 already established for thecore:atom's own
+# dual-CI generation (git hosting is a generic, per-developer choice, not something to ask about).
+fetch_thecore_sample(".github/workflows/ci.yml", ".github/workflows/ci.yml")
 fetch_thecore_sample("CLAUDE.md", "CLAUDE.md")
 
 # --- Standard installer chain ------------------------------------------------
@@ -170,10 +174,44 @@ if options[:asset_pipeline].to_s != "sprockets"
     :yellow
 end
 
-run_setup_now = yes?(
-  "Run `bundle install` and the standard installer generators (devise, rails_admin, " \
-  "active_storage, action_text, action_mailbox, cancan, erd) now? (y/n)"
-)
+# thecore_generators#23: non-interactive mode, triggered ONLY by the explicit env var
+# below -- deliberately NOT auto-detected from tty absence the way `thecore:atom`'s
+# `TtyDetection`-based `effectively_non_interactive?` is (ADR 0006). That precedent
+# works because `AtomGenerator` runs in-process inside its own test, where stubbing
+# `$stdin.tty?`/`$stdout.tty?` (see `association_wiring_test.rb`) is meaningful. This
+# template instead always runs as a genuine separate `rails new` subprocess (its own
+# test seam spawns it via Open3), whose stdin is a pipe -- never a real tty -- even
+# when the test is legitimately simulating interactive use by feeding an answer via
+# `stdin_data`. Auto-triggering on tty absence would misfire on every such simulated-
+# interactive test run; the explicit, deliberate opt-in below avoids that with no loss
+# of real-world safety (an unattended CI run with neither var set still fails loudly
+# below, just one env var short of `thecore:atom`'s own auto-detected equivalent).
+non_interactive = !ENV["THECORE_APP_TEMPLATE_NON_INTERACTIVE"].to_s.strip.empty?
+
+run_setup_now =
+  if non_interactive
+    run_installers_raw = ENV["THECORE_APP_TEMPLATE_RUN_INSTALLERS"]
+    if run_installers_raw.nil? || run_installers_raw.strip.empty?
+      abort(
+        "THECORE_APP_TEMPLATE_NON_INTERACTIVE is set but THECORE_APP_TEMPLATE_RUN_INSTALLERS " \
+        "is not -- set it to \"true\" or \"false\" to say whether the installer chain " \
+        "(devise/rails_admin/active_storage/action_text/action_mailbox/cancan/erd) should run."
+      )
+    end
+    normalized = run_installers_raw.strip.downcase
+    unless %w[true false].include?(normalized)
+      abort(
+        "THECORE_APP_TEMPLATE_RUN_INSTALLERS must be \"true\" or \"false\", got " \
+        "#{run_installers_raw.inspect}."
+      )
+    end
+    normalized == "true"
+  else
+    yes?(
+      "Run `bundle install` and the standard installer generators (devise, rails_admin, " \
+      "active_storage, action_text, action_mailbox, cancan, erd) now? (y/n)"
+    )
+  end
 
 after_bundle do
   next unless run_setup_now

data/lib/thecore_generators/check_practices.rb

@@ -5,6 +5,7 @@ require "generators/thecore/workspace_context"
 require "generators/thecore/action_companion"
 require "generators/thecore/root_action/root_action_generator"
 require "generators/thecore/member_action/member_action_generator"
+require "generators/thecore/collection_action/collection_action_generator"
 
 module Thecore
   # `rails thecore:check_practices` — a Ruby port of thecore_code_extension's
@@ -50,8 +51,9 @@ module Thecore
     # then re-scans and returns whatever violations remain, per ADR 0004:
     # "exits non-zero whenever violations remain unresolved after any --fix
     # pass" — this makes a fix that turns out incomplete (or a violation
-    # this ticket doesn't know how to fix, e.g. a collection_action
-    # companion) visible in the result rather than silently assumed fixed.
+    # this gem doesn't know how to fix at all, e.g. a broken action-file
+    # marker, never fixable for any kind) visible in the result rather than
+    # silently assumed fixed.
     def self.run(app_root:, atom_name: nil, fix: false)
       violations = Runner.new(app_root: app_root, atom_name: atom_name).run
       return violations unless fix
@@ -63,12 +65,15 @@ module Thecore
     # A Thor::Group instance whose only purpose is running
     # Thecore::Generators::CompanionFiles' generic (action-kind-agnostic)
     # after_initialize.rb/locale fixes against a specific destination_root
-    # and action name — used by Runner's Actions check for all three kinds,
-    # including collection_action, which has no generator of its own to
-    # delegate companion-file (view/JS/SCSS) rendering to. Deliberately not
-    # placed under lib/generators/ (and so never discovered as a
-    # `rails generate` namespace) — it is an internal implementation detail
-    # of check_practices' --fix, not a public command.
+    # and action name — used by Runner's Actions check for all three kinds.
+    # Companion-file (view/JS/SCSS) fixes do NOT go through this class for
+    # any kind — those delegate straight to the kind's own real generator
+    # (RootActionGenerator/MemberActionGenerator/CollectionActionGenerator,
+    # via ACTION_GENERATOR_CLASSES below) so the fix always uses that
+    # generator's own template. Deliberately not placed under
+    # lib/generators/ (and so never discovered as a `rails generate`
+    # namespace) — it is an internal implementation detail of
+    # check_practices' --fix, not a public command.
     class GenericFixTarget < Rails::Generators::NamedBase
       include Thecore::Generators::AtomAware
       include Thecore::Generators::CompanionFiles
@@ -85,14 +90,15 @@ module Thecore
       VIEW_MARKERS = ["stylesheet_link_tag", "javascript_include_tag"].freeze
       JS_MARKERS = ["document.addEventListener('turbo:load'"].freeze
       SCSS_MARKERS = ["@keyframes sk-bounce"].freeze
-      # Only root_action/member_action have a generator whose own template
-      # rendering a companion-file fix can delegate to; collection_action
-      # has none (ADR 0004: "no generator to have gotten it right" - a
-      # tracked, deliberate gap), so its missing-companion violations are
-      # never fixable.
+      # All three kinds now have a generator whose own template rendering a
+      # companion-file fix can delegate to (thecore_generators#21, per ADR
+      # 0006 in the thecore repo) - collection_action's missing-companion
+      # violations were never fixable before this (ADR 0004 tracked it as a
+      # deliberate, temporary gap: "no generator to have gotten it right").
       ACTION_GENERATOR_CLASSES = {
         "root_action" => Thecore::Generators::RootActionGenerator,
         "member_action" => Thecore::Generators::MemberActionGenerator,
+        "collection_action" => Thecore::Generators::CollectionActionGenerator,
       }.freeze
 
       def initialize(app_root:, atom_name: nil)
@@ -235,7 +241,7 @@ module Thecore
       end
 
       # Renders only the one missing companion file, via the actual
-      # Root/Member Action generator's own template - never the bundled
+      # Root/Member/Collection Action generator's own template - never the bundled
       # "render all three companions" method, which would risk a
       # non-interactive file-collision hang/prompt on a hand-customized
       # sibling file that already exists with different content. A file

data/lib/thecore_generators/version.rb

@@ -1,3 +1,3 @@
 module ThecoreGenerators
-  VERSION = "3.8.0"
+  VERSION = "3.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_generators
 version: !ruby/object:Gem::Version
-  version: 3.8.0
+  version: 3.13.0
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -38,7 +38,15 @@ files:
 - Rakefile
 - lib/generators/thecore/action_companion.rb
 - lib/generators/thecore/association_wiring.rb
+- lib/generators/thecore/atom/atom_generator.rb
+- lib/generators/thecore/atom/templates/abilities.rb.tt
+- lib/generators/thecore/atom/templates/seeds.rb.tt
 - lib/generators/thecore/atom_aware.rb
+- lib/generators/thecore/collection_action/collection_action_generator.rb
+- lib/generators/thecore/collection_action/templates/action.html.erb.tt
+- lib/generators/thecore/collection_action/templates/action.js.tt
+- lib/generators/thecore/collection_action/templates/action.rb.tt
+- lib/generators/thecore/collection_action/templates/action.scss.tt
 - lib/generators/thecore/companion_files.rb
 - lib/generators/thecore/member_action/member_action_generator.rb
 - lib/generators/thecore/member_action/templates/action.html.erb.tt
@@ -54,6 +62,8 @@ files:
 - lib/generators/thecore/root_action/templates/action.js.tt
 - lib/generators/thecore/root_action/templates/action.rb.tt
 - lib/generators/thecore/root_action/templates/action.scss.tt
+- lib/generators/thecore/sample_fetcher.rb
+- lib/generators/thecore/tty_detection.rb
 - lib/generators/thecore/workspace_context.rb
 - lib/tasks/thecore_generators_tasks.rake
 - lib/templates/app_template.rb