thecore_generators 3.6.0 → 3.11.0

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

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+# Thecore 3 Application Template — porting createApp.js's Gemfile/vendor-directory
+# behavior (thecore_generators#17) plus devcontainer/CI/CLAUDE.md assets fetched from
+# thecore's own samples/ (thecore_generators#18). See ADR 0005 in the thecore repo for
+# the full design rationale behind both.
+#
+# Invoke via:
+#
+#   rails new myapp --database=postgresql --asset-pipeline=sprockets \
+#     -m https://raw.githubusercontent.com/gabrieletassoni/thecore_generators/release/3/lib/templates/app_template.rb
+#
+# (or a local path to this file, e.g. while developing thecore_generators itself)
+
+# --- Core Gemfile stack ------------------------------------------------------
+# Always added, uncommented — every Thecore host app needs these (see thecore's own
+# CLAUDE.md/GUIDE.md, "Standard Gem Stack").
+gem "devise"
+gem "cancancan"
+gem "rails_admin"
+# `rails_admin:install --asset=sprockets` (below) also unconditionally appends its own
+# `gem 'sassc-rails'` line via its `configure_for_sprockets` step -- verified against
+# the installed rails_admin 3.3.0 source, that step does nothing else. The resulting
+# duplicate is harmless (empirically confirmed: `bundle lock` against two identical,
+# unconstrained `gem` lines warns "lists the gem more than once" but resolves and
+# exits 0) -- not worth a fragile post-install dedupe for a cosmetic Gemfile wart, and
+# this declaration must stay regardless, since sassc-rails needs to be active even
+# when the installer chain below is declined.
+gem "sassc-rails"
+# ADR 0001 (thecore repo) requires model_driven_api >= 3.9.0 / thecore_ui_rails_admin
+# >= 3.8.0 for the DefaultModuleRegistry default-concern behavior this whole ecosystem
+# now relies on -- matching the floor this gem's own Gemfile already pins to (see its
+# comment), not an arbitrary choice.
+gem "model_driven_api", "~> 3.9"
+gem "thecore_ui_rails_admin", "~> 3.8"
+gem "rails-erd", group: :development
+
+# thecore_generators itself is dev-tooling only (it hooks `rails g model`/`migration`,
+# see ADR 0002 in the thecore repo) — never a runtime dependency, so it goes in the
+# :development group. A single-line `group:` option is equivalent to (and simpler
+# than) createApp.js's manual `group :development do ... end` block insertion.
+gem "thecore_generators", "~> 3.6", group: :development
+
+# --- Optional ecosystem gems, discoverable but off by default ---------------
+# Same "commented but documented" philosophy as the devcontainer's gh/glab CLI
+# mounts (ADR 0005): each of these publishes to RubyGems.org (see thecore's own
+# CLAUDE.md) but isn't needed by every app, so it starts commented out with a
+# one-line description — uncomment only the ones this project actually needs.
+append_to_file "Gemfile", <<~RUBY
+
+  # The rest of the generic Thecore ecosystem — uncomment only what you need.
+  # gem "thecore_auth_commons", "~> 3.0" # Role/permission/predicate models and authorization scaffolding
+  # gem "thecore_settings", "~> 3.0" # ThecoreSettings key/value configuration store
+  # gem "thecore_print_commons", "~> 3.0" # Shared PDF/print generation helpers
+  # gem "thecore_background_jobs", "~> 3.0" # Shared background job scheduling helpers
+  # gem "thecore_ui_commons", "~> 3.0" # Shared UI helpers/components for the admin frontend
+  # gem "thecore_tcp_debug", "~> 3.0" # TCP-level debugging/diagnostics support
+  # gem "thecore_download_documents", "~> 3.0" # Document download support
+  # gem "thecore_dataentry_commons", "~> 3.0" # Shared data-entry UI helpers
+  # gem "thecore_connectors" # Helpers for connecting to external systems/data sources
+RUBY
+
+# --- Developer-convenience placeholder directories --------------------------
+# NOT template content (ADR 0005) — just known, git-trackable locations to clone
+# auxiliary repos into during local development. Created empty; nothing is
+# pre-wired, no submodule declarations, no Gemfile `path:` entries.
+empty_directory "vendor/submodules"
+create_file "vendor/submodules/.keep", <<~TEXT
+  Clone auxiliary Thecore ecosystem repos here during local development (e.g. an
+  ATOM you're developing against this app). Not consumed by any Gemfile entry
+  automatically — add a `path:` gem yourself if you want one of these clones
+  bundled from source instead of from RubyGems.org.
+TEXT
+
+empty_directory "vendor/external"
+create_file "vendor/external/.keep", <<~TEXT
+  Clone read-only reference repos here during local development (framework docs,
+  sibling tooling repos you want open alongside this app). Not consumed by
+  anything automatically.
+TEXT
+
+# --- Devcontainer / CI / CLAUDE.md assets, from thecore's own samples -------
+# Single source of truth (ADR 0005) — not duplicated inside this gem. The base
+# location is resolved fresh inside `fetch_thecore_sample` on every call, through
+# one overridable point: `ENV["THECORE_SAMPLES_SOURCE"]`, defaulting to the real
+# raw GitHub URL for thecore's `samples/` directory on `master` (thecore's own
+# default branch — double-checked directly against that repo, not assumed from
+# this gem's own `release/3` naming convention, which doesn't apply there). An
+# unset *or blank* env var falls back to the default (an explicit emptiness
+# check, not `||` alone — `ENV["X"] || default` would treat `THECORE_SAMPLES_SOURCE=""`,
+# a realistic shape for an optional env var in a compose file with no value set,
+# as a real override and try to read a same-named file relative to whatever the
+# current directory happens to be, instead of falling back). An http(s) value is
+# fetched over the network via `get`; anything else is treated as a local
+# directory and read directly — this gem's own offline test points it at a
+# fixture instead.
+#
+# NOTE: this default URL only serves real content once `thecore`'s `master`
+# carries the commits that added `samples/CLAUDE.md`/`samples/.gitlab-ci.yml`
+# and brought `samples/devcontainer/` up to date (thecore#14/#15) — as of this
+# gem's own 3.8.0 release those commits exist only in a local checkout, not
+# pushed to `origin/master` yet. Until they're pushed, the default URL 404s for
+# `.gitlab-ci.yml`/`CLAUDE.md`/the two devcontainer scripts and serves stale
+# content for `devcontainer.json`/`docker-compose.yml`. This is an operational
+# sequencing issue (push `thecore` before relying on the default in production),
+# not a defect in this code — but it means `THECORE_SAMPLES_SOURCE` pointed at a
+# local clone of `thecore` is the only way to exercise the real default content
+# today.
+#
+# Every write below is unconditional (`force: true`, no interactive prompt).
+# Of the six `.devcontainer/*` files, four (`devcontainer.json`,
+# `docker-compose.yml`, `Dockerfile`, `create-db-user.sql`) are expected to
+# already exist, written by the separate, prior "Setup Devcontainer" bootstrap
+# step this template runs inside of (verified directly against that command's
+# source, `thecore_code_extension/commands/setupDevContainer.js`) — replacing
+# them is the whole point, not a conflict to ask about. The other two
+# (`link-host-home.sh`/`check-plugins.sh`) are *not* written by that step at
+# all — genuinely new files here, not overwrites — but `force: true` is harmless
+# for a new file and keeps every write in this block uniform.
+# `.gitlab-ci.yml`/`CLAUDE.md` don't exist yet in the documented flow either,
+# but stay unconditional too so re-running this template later
+# (`bin/rails app:template`) is a clean overwrite, not a prompt.
+#
+# A fetch failure (today: the 404s above; going forward: any network blip, or
+# `thecore` reorganizing `samples/`) aborts the whole template with a clear,
+# specific message instead of continuing into a silently half-scaffolded app
+# (some `.devcontainer/*` files present, others not, no clear signal pointing
+# back to the real cause) -- the same fail-fast philosophy thecore_generators#17
+# already applies to `bundle_command`/`rails_command` failures in the installer
+# chain below.
+def fetch_thecore_sample(relative_path, destination)
+  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://")
+    get("#{source}/#{relative_path}", destination, force: true)
+  else
+    create_file(destination, File.read(File.join(source, relative_path)), force: true)
+  end
+rescue StandardError => e
+  abort("Failed to fetch #{relative_path} from #{source} (#{e.class}: #{e.message}) " \
+    "-- aborting the app template. Set THECORE_SAMPLES_SOURCE to override the source.")
+end
+
+%w[devcontainer.json docker-compose.yml Dockerfile create-db-user.sql link-host-home.sh check-plugins.sh].each do |file|
+  fetch_thecore_sample("devcontainer/#{file}", ".devcontainer/#{file}")
+end
+# `get`/`create_file` only write content, never permissions — the executable bit
+# has to be restored explicitly for the two scripts (`thecore/samples/devcontainer/`
+# stores them executable, but that's lost the moment their bytes cross an HTTP
+# fetch or a plain `File.read`).
+chmod ".devcontainer/link-host-home.sh", 0o755
+chmod ".devcontainer/check-plugins.sh", 0o755
+
+fetch_thecore_sample(".gitlab-ci.yml", ".gitlab-ci.yml")
+fetch_thecore_sample("CLAUDE.md", "CLAUDE.md")
+
+# --- Standard installer chain ------------------------------------------------
+# Needs the gems added above actually bundled and installable, i.e. real network
+# access — genuinely optional (not a test-only escape hatch): a developer
+# bootstrapping offline can say no here and run these steps by hand once they
+# have connectivity. Wrapped in `after_bundle` (Rails' own template mechanism
+# for "run this once the gems this template just added are actually bundled")
+# so it runs after — never before — the gems above are installed.
+if options[:asset_pipeline].to_s != "sprockets"
+  say_status :warning,
+    "this template assumes --asset-pipeline=sprockets (got #{options[:asset_pipeline].inspect}) " \
+    "-- rails_admin:install below is still configured for sprockets regardless, see the invocation " \
+    "documented in this gem's README.",
+    :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)"
+)
+
+after_bundle do
+  next unless run_setup_now
+
+  # `bundle_command`/`rails_command` never abort on failure by themselves (verified
+  # against railties' own source: `bundle_command` is a bare `system` call with no
+  # result check at all; `rails_command` only aborts when `abort_on_failure: true` is
+  # passed explicitly -- `generate` sets that internally, `rails_command` does not).
+  # createApp.js's own equivalent was one `&&`-joined shell command that failed the
+  # whole chain atomically on any step; matched here explicitly rather than silently
+  # limping on into later steps against a broken bundle/app.
+  abort("bundle install failed -- aborting the app template's installer chain") unless bundle_command("install")
+
+  generate "devise:install"
+
+  # The `_namespace` positional argument ("app") is RailsAdmin::InstallGenerator's own
+  # mount-path argument (not a placeholder/app-name) -- passing a non-blank value here
+  # is what makes it skip its interactive "Where do you want to mount rails_admin?"
+  # prompt (verified against its source), which nothing in this non-interactive chain
+  # could ever answer. The resulting namespace is irrelevant: `thecore_ui_rails_admin`
+  # already mounts `RailsAdmin::Engine` itself, in its own engine routes (see that
+  # gem's `config/routes.rb`) -- a second, active mount in *this* app's routes.rb would
+  # be a genuine duplicate route, not just cosmetic. `route(...)` below writes a
+  # commented placeholder line containing the exact substring
+  # (`"mount RailsAdmin::Engine"`) the installer checks for
+  # (`routes.rb.include?('mount RailsAdmin::Engine')`) *before* calling it, so it skips
+  # inserting an active one at all -- more robust than adding one and regex-stripping
+  # it back out afterward (a future RailsAdmin release reformatting its generated line
+  # would silently break a regex-based removal with no error raised anywhere).
+  route "# mount RailsAdmin::Engine -- already mounted by thecore_ui_rails_admin's own engine routes, see that gem's config/routes.rb"
+  generate "rails_admin:install", "app", "--asset=sprockets"
+
+  rails_command "active_storage:install", abort_on_failure: true
+  rails_command "action_text:install", abort_on_failure: true
+  # action_text:install (above) may add its own `image_processing` Gemfile dependency
+  # (verified against its source) -- this bundle is the one that actually picks that
+  # up; devise:install/rails_admin:install above added nothing new to bundle beyond
+  # what the first `bundle_command("install")` already covered, so no bundle call sits
+  # between them.
+  abort("bundle install failed -- aborting the app template's installer chain") unless bundle_command("install")
+  rails_command "action_mailbox:install", abort_on_failure: true
+  generate "cancan:ability"
+  generate "erd:install"
+end

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.6.0"
+  VERSION = "3.11.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: thecore_generators
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.11.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,8 +62,11 @@ 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
 - lib/thecore_generators.rb
 - lib/thecore_generators/check_practices.rb
 - lib/thecore_generators/railtie.rb