thecore_generators 3.6.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b52de470428f2cecb91388721b140a88d6cdb0a1e0ea7b3ce07b0b855e17fbaa
-  data.tar.gz: 5a6147ac698f2820027e493bd8bdee96c13f39867dd50f6b472a495f5f01b829
+  metadata.gz: 43638f50febe1bf078edcf5e5490c33709065db0a522f2b14a659c9ae19954ab
+  data.tar.gz: 368b0b26a79a4a5be2ccc394e0dd4d64061efb1c66aa099d124432a1455e4230
 SHA512:
-  metadata.gz: 52374b36988c76209702afb27c59e32ac95e05c53ca805914257264bb3eaae31ee06fa3329faae3a6da5c25742d31e136f470a22cf1897cdbd9a17caad010f97
-  data.tar.gz: 75083924ea8bdc22bf39d5dbea930da5ec5eb37d736107b43037e235d40a4430b0ae963a24133b9789631135de83b51cdfb1afd82515c4d2f0c69ddb43bb30a2
+  metadata.gz: a0a7cb2fc271fe3f495ad2a4234ba338fc9e9b50f8309e2aefc593777d85fc8fa5b5146698f7000009a2da0552e1a89cd296e680a0003c99f6bca09e1b962e7e
+  data.tar.gz: 7495d392354b1f1834b8fba5117449f3b9383aa6df89f4bd637c9044bc7c3357f2136d316385b89057b2a851047887df7c49f94db5a7aa97641a91189ea05510

data/README.md

@@ -22,6 +22,13 @@ transparently apply thecore's scaffolding conventions — no new command vocabul
 (check_practices + Root/Member Action generators) is complete** as of this release: `rails
 generate thecore:root_action`, `rails generate thecore:member_action`, and `rails
 thecore:check_practices` (Scaffold Files + Models + Actions, `--fix` included) all ship.
+**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
+[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.
 
 ### What `rails generate model`/`rails generate migration` do now
 
@@ -252,6 +259,54 @@ remain (so a violation this run can't fix, e.g. a `collection_action` companion,
 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)
+
+A Ruby port of `thecore_code_extension`'s `createApp.js`, as a genuine Rails application
+template rather than a `thecore:*` generator — its entry point is `rails new -m`, not `rails
+generate`:
+
+```bash
+rails new myapp --database=postgresql --asset-pipeline=sprockets \
+  -m https://raw.githubusercontent.com/gabrieletassoni/thecore_generators/release/3/lib/templates/app_template.rb
+```
+
+Run inside a devcontainer already created by the "Setup Devcontainer" VS Code command — a
+bootstrap step this template doesn't invoke or modify itself (that command's own code is
+untouched), even though the template's own devcontainer-asset fetch below does overwrite the
+files that bootstrap step created, by design. 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)
+for the full design and why the two stay separate).
+
+- **Core Gemfile stack, active** — `devise`, `cancancan`, `rails_admin`, `sassc-rails`,
+  `model_driven_api` (`~> 3.9`), `thecore_ui_rails_admin` (`~> 3.8` — both meeting ADR 0001's
+  `DefaultModuleRegistry` floor), `rails-erd` (`:development`). `thecore_generators` itself is
+  added too, `group: :development` — so the generated app can immediately use every
+  generator/task documented above without a manual Gemfile edit first.
+- **The rest of the generic Thecore ecosystem, commented out** — `thecore_auth_commons`,
+  `thecore_settings`, `thecore_print_commons`, `thecore_background_jobs`, `thecore_ui_commons`,
+  `thecore_tcp_debug`, `thecore_download_documents`, `thecore_dataentry_commons`,
+  `thecore_connectors`, each with a one-line purpose comment — discoverable but off by default,
+  the same "commented but documented" philosophy ADR 0005 applies to the devcontainer's `gh`/
+  `glab` CLI mounts below.
+- **`vendor/submodules/`/`vendor/external/`** — created empty (a `.keep` file each), not
+  pre-wired with any submodule or gem. Per ADR 0005 these are developer-convenience clone
+  locations, not template content.
+- **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,
+  `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:
+  install`, `action_text:install`, `action_mailbox:install`, `cancan:ability`, `erd:install`,
+  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).
+
 ## Installation
 
 Add to your host app's or ATOM's `Gemfile`:

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/version.rb

@@ -1,3 +1,3 @@
 module ThecoreGenerators
-  VERSION = "3.6.0"
+  VERSION = "3.8.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.8.0
 platform: ruby
 authors:
 - Gabriele Tassoni
@@ -56,6 +56,7 @@ files:
 - lib/generators/thecore/root_action/templates/action.scss.tt
 - 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