thecore_generators 3.6.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b52de470428f2cecb91388721b140a88d6cdb0a1e0ea7b3ce07b0b855e17fbaa
-  data.tar.gz: 5a6147ac698f2820027e493bd8bdee96c13f39867dd50f6b472a495f5f01b829
+  metadata.gz: 753f6373a24773431ad2987bd84b7d8609f4a9bedb32dff5a59264bc37c68081
+  data.tar.gz: bc6e8b3d5657bc82bebc1c1913a591e1b7bcb7545f8620d7b4b92704e4735558
 SHA512:
-  metadata.gz: 52374b36988c76209702afb27c59e32ac95e05c53ca805914257264bb3eaae31ee06fa3329faae3a6da5c25742d31e136f470a22cf1897cdbd9a17caad010f97
-  data.tar.gz: 75083924ea8bdc22bf39d5dbea930da5ec5eb37d736107b43037e235d40a4430b0ae963a24133b9789631135de83b51cdfb1afd82515c4d2f0c69ddb43bb30a2
+  metadata.gz: f5f315cbe3496bca9a6f8ac33c1af880aba847704d1bda5f313dbfecae44cae8e2d66e6548a3e1eabd473921ec36bfddd0f96fae2dc7f509386a3f31059a53f3
+  data.tar.gz: 435300740a43124c459e8688e3a3957693b0fd435e664ee07f52b824b30260d90b4a5d4c70e669157df65a5c1c52acd5a056c69fcf2af1d2ec6e59edf8e9030e

data/README.md

@@ -22,6 +22,25 @@ 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. 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. **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
 
@@ -200,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**
@@ -230,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
@@ -248,9 +351,58 @@ 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)
+
+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
 

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)