rolemodel-rails 2.0.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cbd3c1b81aa62c00354cd5faa3cc5bea47c48c2ede2c86470b391372751db9c
-  data.tar.gz: c9bd14d2787122907369daaf9bfa26b63d0cc882449247ae5da26af15de9586f
+  metadata.gz: f1cf52276aac5192b4349379e6f7792232fbdabae218e3d3ac6fbde81cd1ae01
+  data.tar.gz: 3d13d291529c487fb93b8d7c7816acb05e3b686fd4129173208611c0c714558d
 SHA512:
-  metadata.gz: d79a388d4221587a777dddeddaea260f389924272c49299fed129b7f5e364df154fa09161217b0087d975168fda59ce6c75e7fd36468c0b0a5b5767cddecea28
-  data.tar.gz: 960b18a4e997a18092a6bacd69f0833da0154a54717d41215b401f4f8c9cf08034ba8aa10f4daf0fef560a7bd54154a470d650e4427122b3db6c47ac687087ee
+  metadata.gz: 2fdd780f5256aac4772e65e9282569956b2b7e8a2fd663caa068d072a720a7905a721953725df5ccf07d671f600e31d7ec781831782128b63182b8cf586af61b
+  data.tar.gz: 453e93d083a80ff9ce7a2b2ea1f02079e334e2a4ae5028ee91d7b67d0c6cb7d7d8f013e9bab777a9da2f77b767f354af38688a2ac101ba8e94dd28c5979e22ee

data/README.md

@@ -40,7 +40,14 @@ And then execute:
 
 ## Usage
 
-Run all generators (useful on a new app)
+Run the core generators (recommended on a new app — sets up our standard
+baseline so the app is ready to push straight to Heroku)
+
+```shell
+bin/rails g rolemodel:core_setup
+```
+
+Or run every generator, including app-specific extras like React, SaaS/Devise, and GoodJob
 
 ```shell
 bin/rails g rolemodel:all
@@ -66,6 +73,7 @@ bin/rails g
 
 ## Generators
 
+* [Core Setup](./lib/generators/rolemodel/core_setup)
 * [Github](./lib/generators/rolemodel/github)
 * [Semaphore](./lib/generators/rolemodel/semaphore)
 * [Heroku](./lib/generators/rolemodel/heroku)
@@ -102,9 +110,120 @@ bin/rails g
 * [Tailored Select](./lib/generators/rolemodel/tailored_select)
 * [Lograge](./lib/generators/rolemodel/lograge)
 
+## Utilities
+
+### `Rolemodel::Utility::TaskTools`
+
+A mixin of helper methods for writing friendlier, more informative Rake tasks. It provides consistent, migration-style console output, progress indication for long-running loops, an opt-in dry-run mode, and sanitized positional task arguments.
+
+#### Requiring & Including
+
+The module is available at runtime (rolemodel-rails must not be restricted to the `development` gem group). Require it and `include` it inside the `namespace` block of your `.rake` file:
+
+```ruby
+require 'rolemodel/utility/task_tools'
+
+namespace :reports do
+  include Rolemodel::Utility::TaskTools
+
+  task total: :environment do
+    @total = GeneratedReport.count
+  end
+
+  namespace :clear do
+    desc 'Delete all non-current report records'
+    task expired: :total do
+      say_with_time "Detecting & Deleting Expired Reports among #{@total} Total" do
+        deleted_reports = 0
+        GeneratedReport.find_each.with_index do |report, index|
+          indicate_progress(index, @total)
+          next if report.current?
+
+          report.destroy unless dry_run?
+          deleted_reports += 1
+        end
+        say "#{deleted_reports}/#{@total} Records Deleted"
+      end
+    end
+  end
+end
+```
+
+> [!NOTE]
+> `include` inside a `namespace` block adds the helper methods to the anonymous object that evaluates your task bodies, making them (and any plain methods you define alongside them) available to every task in that namespace.
+
+#### Helper Methods
+
+##### `say(message)`
+
+Prints a message using the same style as Rails migrations. Pass `subitem: true` to indent the line beneath a preceding `say`.
+
+```ruby
+say 'Doing some important stuff!'
+say 'Like this one specific thing!', subitem: true
+#=> -- Doing some important stuff!
+#=>    -> Like this one specific thing!
+```
+
+##### `say_with_time(message, &block)`
+
+Wraps `say` and prints the block's real execution time as an indented subitem. Use it to announce and time a unit of work.
+
+```ruby
+say_with_time "Deleting all #{@total} Records" do
+  GeneratedReport.destroy_all unless dry_run?
+end
+#=> -- Deleting all 42 Records
+#=>    -> 0.0198s
+```
+
+##### `indicate_progress(index, total = nil, report_interval: 9)`
+
+Renders an animated spinner (and, when `total` is given, a completion percentage) for a long-running loop. Call it once per iteration with the current index; it only redraws every `report_interval` iterations so the animation stays eye-trackable. Pass a reduced `report_interval` when iterations are very slow.
+
+```ruby
+GeneratedReport.find_each.with_index do |report, index|
+  indicate_progress(index, @total)
+  # ...
+end
+```
+
+##### `dry_run?`
+
+Returns `true` when the `DRY_RUN` environment variable is present, enabling a dry-run pattern for your tasks. Guard any code that writes to the database or file system with `unless dry_run?` so the task still produces its console feedback without performing the side effects.
+
+```ruby
+report.destroy unless dry_run?
+```
+
+```shell
+DRY_RUN=true rake reports:clear:expired
+```
+
+##### `sanitize_arguments(args, defaults = {})`
+
+Improves the usability of positional `Rake::Task` arguments, which cannot declare default values and are awkward to skip. Pass the task's `args` and a hash of defaults; it returns a hash with whitespace stripped, blank/skipped values (passed as `_`) replaced by your defaults.
+
+```ruby
+desc 'Seed a dev user with the given name and email'
+task :dev, %i[name email] => :environment do |_, args|
+  name, email = sanitize_arguments(args, name: 'RoleModel', email: 'it-support@rolemodelsoftware.com').values_at(:name, :email)
+  say_with_time "Seeding Dev User (name: #{name}, email: #{email}, role: Admin)" do
+    User.find_or_create(name:, email:, role: 'admin') unless dry_run?
+  end
+end
+```
+
+```shell
+# Skip the name argument with `_` to fall back to its default
+DRY_RUN=true rake users:dev[_,bob@example.com]
+#=> -- Seeding Dev User (name: RoleModel, email: bob@example.com, role: Admin)
+#=>    -> 0.0000s
+```
+
 ## Development
 
-Install the versions of Node and Ruby specified in `.node-version` and `.ruby-version` on your machine. https://asdf-vm.com/ is a great tool for managing language versions. Then run `npm install -g yarn`.
+Install the versions of Node and Ruby specified in `.node-version` and `.ruby-version` on your machine. https://asdf-vm.com/ is a great tool for managing language versions. Then run `corepack enable` to activate the Yarn 4+ version pinned by each project's `packageManager` field.
 
 ## Adding new Generators
 

data/lib/generators/rolemodel/all_generator.rb

@@ -8,6 +8,7 @@ module Rolemodel
       generate 'rolemodel:heroku'
       generate 'rolemodel:readme'
       generate 'rolemodel:webpack'
+      generate 'rolemodel:sentry'
       generate 'rolemodel:react'
       generate 'rolemodel:slim'
       generate 'rolemodel:optics:all'

data/lib/generators/rolemodel/core_setup/README.md

@@ -0,0 +1,27 @@
+# Core Setup Generator
+
+Runs the core generators every new Rails app should have. Unlike
+`rolemodel:all`, this skips the app-specific extras (React, SaaS/Devise,
+GoodJob, Kaminari, etc.) so you get just the standard baseline — a new Rails
+app you can push straight to Heroku right after generation.
+
+## Prerequisites
+
+  - A freshly generated Rails app
+
+## What you get
+
+  - [GitHub](../github) — standard GitHub configuration
+  - [Heroku](../heroku) — standard Heroku deployment configuration
+  - [Readme](../readme) — standard project README
+  - [Webpack](../webpack) — Webpack v5 for JS and CSS
+  - [Sentry](../sentry) — error monitoring for Ruby and JavaScript
+  - [Slim](../slim) — Slim templates
+  - [Optics](../optics) — Optics design system
+  - [Testing](../testing) — RSpec, FactoryBot, parallel_tests, TestProf
+    (pass `--js-runner` to include jasmine-playwright-runner)
+  - [SimpleForm](../simple_form) — SimpleForm with our configuration
+  - [Linters](../linters) — Rubocop and ESLint
+  - [UI Components](../ui_components) — flash, the modal pattern, & Turbo 8 support
+  - [Editors](../editors) — EditorConfig and recommended VSCode extensions
+  - [Lograge](../lograge) — condensed request logging

data/lib/generators/rolemodel/core_setup/USAGE

@@ -0,0 +1,12 @@
+Description:
+  Runs the core generators every new Rails app should have
+
+  Sets up GitHub config, Heroku deployment, README, Webpack, Sentry, Slim,
+  Optics, testing (RSpec & friends), SimpleForm, linters, Turbo 8+ support,
+  and Lograge. The result is an app that is ready to push directly to Heroku.
+
+  Pass --js-runner to also include jasmine-playwright-runner for browser
+  JS testing.
+
+Example:
+  rails generate rolemodel:core_setup

data/lib/generators/rolemodel/core_setup/core_setup_generator.rb

@@ -0,0 +1,19 @@
+module Rolemodel
+  class CoreSetupGenerator < ::Rolemodel::GeneratorBase
+    def run_the_core_generators
+      generate 'rolemodel:github'
+      generate 'rolemodel:heroku'
+      generate 'rolemodel:readme'
+      generate 'rolemodel:webpack'
+      generate 'rolemodel:sentry'
+      generate 'rolemodel:slim'
+      generate 'rolemodel:optics:all'
+      generate 'rolemodel:testing:all'
+      generate 'rolemodel:simple_form'
+      generate 'rolemodel:linters:all'
+      generate 'rolemodel:ui_components:flash'
+      generate 'rolemodel:ui_components:modals'
+      generate 'rolemodel:lograge'
+    end
+  end
+end

data/lib/generators/rolemodel/github/README.md

@@ -9,6 +9,10 @@ It doesn't need to be run first, but the parallel_tests generator must be run in
 - CI workflow
   - A sensible default `ci.yml` to get you started with Github Actions. This will run linters, model tests, and system tests.
   - Along with the `ci.yml`, your `database.yml` will be modified to be able to be run in GHA.
+- Deploy workflows
+  - `deploy-staging.yml` deploys to Heroku on every push to `main` (or manually); `deploy-production.yml` deploys manually via `workflow_dispatch`.
+  - Both target a GitHub deployment environment (`Staging`/`Production`) that provides `HEROKU_APP_NAME` and `HEROKU_APP_URL` variables, and authenticate with the org-level `HEROKU_IT_SUPPORT_API_KEY` secret and `HEROKU_IT_SUPPORT_EMAIL` variable.
+  - Note: the staging workflow will fail on pushes to `main` until the environment exists — run the `deploy-app` agent skill (installed by the heroku generator) to create the Heroku app and the GitHub environment.
 - Pull Request Template
   - When you open a Pull Request in Github it will use the Markdown file as a [template](./templates/pull_request_template.md) for the content of the PR.
   - Helpful for reminding collaborators to add specific details to the PR.

data/lib/generators/rolemodel/github/templates/workflows/deploy-production.yml

@@ -0,0 +1,34 @@
+name: Deploy to Heroku Production
+
+on:
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: 'Specific SHA or Branch name (optional)'
+        required: false
+        type: string
+
+concurrency: production-deployment
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment:
+      name: Production
+      url: ${{ vars.HEROKU_APP_URL }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Heroku CLI
+        run: |
+          curl https://cli-assets.heroku.com/install.sh | sh
+
+      - uses: akhileshns/heroku-deploy@v3.15.15
+        with:
+          heroku_api_key: ${{ secrets.HEROKU_IT_SUPPORT_API_KEY }}
+          heroku_app_name: ${{ vars.HEROKU_APP_NAME }}
+          heroku_email: ${{ vars.HEROKU_IT_SUPPORT_EMAIL }}
+          branch: ${{ inputs.sha || 'HEAD' }}
+          healthcheck: '${{ vars.HEROKU_APP_URL }}/up'

data/lib/generators/rolemodel/github/templates/workflows/deploy-staging.yml

@@ -0,0 +1,35 @@
+name: Deploy to Heroku Staging
+
+on:
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: 'Specific SHA or Branch name (optional)'
+        required: false
+        type: string
+  push: { branches: [ staging ] }
+
+concurrency: staging-deployment
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment:
+      name: Staging
+      url: ${{ vars.HEROKU_APP_URL }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Heroku CLI
+        run: |
+          curl https://cli-assets.heroku.com/install.sh | sh
+
+      - uses: akhileshns/heroku-deploy@v3.15.15
+        with:
+          heroku_api_key: ${{ secrets.HEROKU_IT_SUPPORT_API_KEY }}
+          heroku_app_name: ${{ vars.HEROKU_APP_NAME }}
+          heroku_email: ${{ vars.HEROKU_IT_SUPPORT_EMAIL }}
+          branch: ${{ inputs.sha || 'HEAD' }}
+          healthcheck: "${{ vars.HEROKU_APP_URL }}/up"

data/lib/generators/rolemodel/good_job/good_job_generator.rb

@@ -64,8 +64,6 @@ module Rolemodel
 
     def finishing_notes
       say <<~NOTES
-        *** Reminder to update Honeybadger gem to version 5.7.0 or later to get correct GoodJob error notifications in Honeybadger
-
         *** Reminder to also update your job classes to include appropriate concurrency controls (enqueue_limit/perform_limit with keys)
       NOTES
     end

data/lib/generators/rolemodel/heroku/README.md

@@ -4,5 +4,24 @@
 
 * Procfile configured for a server process and a release command to run migrations
 * Basic app.json preconfigured with a script to initialize the database and common environment variables, addons, and buildpacks
-
 This is the basic config needed to deploy to Heroku.
+
+## Deploying the app
+
+Deployment setup itself is handled by the `deploy-app` agent skill, which ships inside the
+`rolemodel-rails` gem rather than being copied into your repo — it's one-time setup, so nothing
+skill-related is committed to the app. When the generator finishes, it prints the path to the
+skill's `SKILL.md`; point any coding agent at that file to deploy the app. You can also locate
+it yourself:
+
+```sh
+$(bundle show rolemodel-rails)/lib/generators/rolemodel/heroku/templates/deploy-app/SKILL.md
+```
+
+The skill cleans up the generated Gemfile (merges duplicate groups, removes comments,
+alphabetizes), verifies the test suite and RuboCop pass, creates the Sentry project and wires
+up the DSN, creates and deploys the Heroku staging app (buildpacks, dynos, Postgres,
+Papertrail), and creates the GitHub `Staging` environment with the
+`HEROKU_APP_NAME`/`HEROKU_APP_URL` variables the deploy workflow consumes. The skill is
+LLM-agnostic (Agent Skills format). Requires the Heroku CLI, the GitHub CLI, and the Sentry
+MCP server.

data/lib/generators/rolemodel/heroku/heroku_generator.rb

@@ -15,6 +15,33 @@ module Rolemodel
       template 'Procfile'
     end
 
+    def pin_ruby_version_for_buildpack
+      say 'Pin the Ruby version in the Gemfile so the Heroku buildpack respects it.', :green
+
+      # A bare .ruby-version file is not enough: without a `ruby` directive the version
+      # never lands in Gemfile.lock, so the Heroku Ruby buildpack falls back to its own
+      # default and can install an incompatible Ruby. Tie the Gemfile to .ruby-version.
+      gemfile = File.join(destination_root, 'Gemfile')
+      return if File.exist?(gemfile) && File.read(gemfile).match?(/^\s*ruby\s/)
+
+      inject_into_file 'Gemfile', "\nruby file: '.ruby-version'\n", after: /^source .*$/
+    end
+
+    def use_database_url_in_production
+      say 'Point the production database at DATABASE_URL for Heroku.', :green
+
+      # Rails' generated production block hardcodes database/username/<APP>_DATABASE_PASSWORD,
+      # none of which exist on Heroku, where the Postgres add-on provides a full DATABASE_URL.
+      # Replace the whole block with a url-based config.
+      gsub_file 'config/database.yml',
+                /^production:\n(?:[ \t]+.*\n?)+/,
+                <<~YAML
+                  production:
+                    <<: *default
+                    url: <%= ENV["DATABASE_URL"] %>
+                YAML
+    end
+
     def force_ssl
       say 'Require SSL for production environment.', :green
 
@@ -48,5 +75,13 @@ module Rolemodel
         end
       RAKE
     end
+
+    def show_deploy_app_skill_path
+      # The deploy-app skill is one-time deployment setup, so it ships inside the
+      # rolemodel-rails gem instead of being copied into the app. Point the user
+      # at it so they can hand it to a coding agent when they're ready to deploy.
+      say "\nWhen you're ready to deploy, point your coding agent at the deploy-app skill:", :green
+      say File.expand_path('templates/deploy-app/SKILL.md', __dir__), :yellow
+    end
   end
 end

data/lib/generators/rolemodel/heroku/templates/app.json.tt

@@ -4,12 +4,15 @@
     "postdeploy": "bin/rails db:seed"
   },
   "env": {
-    "HONEYBADGER_API_KEY": {
+    "SENTRY_DSN": {
       "required": true
     },
-    "HONEYBADGER_ENV": {
+    "SENTRY_ENVIRONMENT": {
       "required": true,
       "value": "review-app"
+    },
+    "SENTRY_AUTH_TOKEN": {
+      "required": false
     }
   },
   "addons": [

data/lib/generators/rolemodel/heroku/templates/deploy-app/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: deploy-app
+description: >
+  Set up deployment for a RoleModel Rails app after running the rolemodel_rails
+  core_setup generator. Cleans up the generated Gemfile, verifies RuboCop, the test
+  suite, and a local production smoke test pass, creates the Sentry project and wires
+  up the DSN, creates and deploys the Heroku app (buildpacks, dynos, Postgres,
+  Papertrail), and creates the GitHub deployment environment + deploy workflow. Use
+  when the user says "deploy app",
+  "set up staging", "set up heroku", "set up sentry for deploy", or "set up production
+  deploy". Defaults to staging; pass "production" for the production flow.
+---
+
+# Deploy App
+
+Completes deployment setup for a RoleModel Rails app in five phases: Gemfile cleanup,
+green build (RuboCop + tests + production smoke test), Sentry, Heroku, GitHub. Default
+mode is **staging**. If invoked with `production`, follow the
+[Production mode](#production-mode) differences.
+
+Every step must be **idempotent**: check whether the resource already exists before
+creating it, and skip or repair rather than failing. Report each phase's outcome as you
+go. Ask the user questions **one at a time**.
+
+## Phase 0: Preflight
+
+Run these checks before touching anything. Stop and tell the user how to fix any that
+fail:
+
+1. `git remote get-url origin` — must be a GitHub repo. Derive `REPO_NAME` from
+   `gh repo view --json name -q .name` (fallback: basename of the origin URL).
+2. `gh auth status` — GitHub CLI authenticated.
+3. `heroku auth:whoami` — Heroku CLI installed and logged in.
+4. Sentry MCP tools available (try listing organizations). If no Sentry MCP server is
+   connected, ask the user to add/authorize the Sentry MCP server
+   (https://mcp.sentry.dev) in their coding agent's MCP configuration and stop — do not
+   fall back to another mechanism.
+5. Read `Procfile` — note whether a `worker` process exists.
+6. Read `config/initializers/sentry.rb` — determine how the DSN is consumed:
+   - reads `ENV['SENTRY_DSN']` → **env-var mode** (RoleModel standard)
+   - reads `Rails.application.credentials...` → **credentials mode**
+7. Deploy-readiness (recent `rolemodel-rails` bakes these in; older apps need the manual
+   fixes noted in each phase). Confirm the generated app already has:
+   - `terser-webpack-plugin` in `package.json` (webpack config imports it)
+   - custom cops under `.rubocop/cops/`, not `lib/cops/` (the latter crashes prod boot)
+   - `config/initializers/lograge.rb` uses `controller.try(:current_user)`
+   - `config/database.yml` `production:` block uses `url: <%= ENV["DATABASE_URL"] %>`
+   - a `ruby` directive in the `Gemfile` (so the version reaches `Gemfile.lock`)
+   - `stackprof` in the `Gemfile` (Sentry profiling)
+   If any are missing, apply the fix inline and note the app predates the generator update.
+
+Set `APP_NAME` = `<REPO_NAME>-staging` (staging) or `<REPO_NAME>` (production), but
+confirm it with the user before creating anything on Heroku.
+
+## Phase 1: Gemfile cleanup
+
+The rolemodel_rails generators append gems as they run, leaving multiple blocks for the
+same group and top-level gems scattered between them. Normalize the Gemfile first (skip
+this phase if it's already clean):
+
+1. Merge duplicate `group` blocks so each unique group combination
+   (e.g. `:development, :test`, `:development`, `:test`) appears exactly once.
+2. Remove all comments, including commented-out gems (e.g. `# gem "redis" ...`).
+3. Alphabetize the gems — the top-level list and the list within each group.
+4. Preserve every gem's version constraint and options (`require:`, `platforms:`,
+   `path:`, etc.) exactly as written. File order: `source`, then `ruby` (if present),
+   then top-level gems, then the group blocks.
+5. Run `bundle install` and confirm it succeeds. `git diff Gemfile.lock` must show no
+   changes — this is an ordering-only cleanup; if the lockfile changed, you altered a
+   dependency and must fix it.
+
+## Phase 2: Green build + production smoke test
+
+Do not deploy a broken app. This is a **verification gate**: on a current generated app
+these should pass with no changes. A failure here usually means a generator regression —
+fix the root cause (and flag it for the generator), never paper over it.
+
+1. RuboCop: `bin/rubocop` (fallback: `bundle exec rubocop`). If there are offenses,
+   apply safe autocorrections (`rubocop -a`), then fix the remainder by hand.
+2. Test suite: `bundle exec rspec` (fallback: `bin/rspec`). Fix any failures at the
+   root cause — never skip, pend, or delete tests to get to green.
+3. **Local production smoke test** — this is what catches the boot/asset/DB failures that
+   only surface under `RAILS_ENV=production` (eager loading, `force_ssl`, DATABASE_URL).
+   Run against a throwaway local Postgres DB (do not touch development/test data):
+   ```
+   export PROD="RAILS_ENV=production SECRET_KEY_BASE=smoketest \
+     DATABASE_URL=postgres://$(whoami)@localhost/<repo>_prodsmoke"
+   env $PROD bundle exec rails db:create
+   env $PROD bundle exec rails assets:precompile      # webpack + asset pipeline
+   env $PROD RAILS_SERVE_STATIC_FILES=true PORT=3999 bundle exec puma -C config/puma.rb &
+   sleep 6
+   curl -s -o /dev/null -w '%{http_code}\n' -H 'X-Forwarded-Proto: https' \
+     http://localhost:3999/up      # expect 200 (plain http returns 301 due to force_ssl)
+   kill %1; env $PROD bundle exec rails db:drop
+   ```
+   `assets:precompile` succeeding and `/up` → 200 is the gate. If `/up` 500s, read the
+   server log for the root cause before proceeding.
+4. Re-run until clean, then commit the Gemfile cleanup and any fixes (the deploy later
+   pushes this branch, so everything must be committed).
+
+## Phase 3: Sentry project + DSN
+
+1. List the Sentry organizations/teams via the Sentry MCP. Ask the user which team the
+   project belongs under (skip the question if there is only one option).
+2. Check whether a project named `REPO_NAME` already exists in that org. If it does,
+   reuse it and fetch its DSN instead of creating a duplicate.
+3. Otherwise create the project: slug/name = `REPO_NAME`, platform `ruby-rails`,
+   assigned to the confirmed team.
+4. Fetch the project's client key (DSN).
+5. Deliver the DSN according to the mode detected in preflight:
+   - **env-var mode**: no code change needed. The DSN is set as a Heroku config var in
+     Phase 4 (`SENTRY_DSN`, plus `SENTRY_ENVIRONMENT=staging`). Mention that local
+     error reporting (if ever wanted) uses the same `SENTRY_DSN` env var.
+   - **credentials mode**: do NOT edit credentials yourself. Print the DSN and exact
+     instructions — e.g. `bin/rails credentials:edit --environment production`, add
+     `sentry_dsn: <DSN>` — then wait for the user to confirm they've saved it. Verify
+     afterwards with
+     `bin/rails runner "abort 'missing' unless Rails.application.credentials.sentry_dsn"`
+     (adjust env/key path to match the initializer) before moving on.
+
+## Phase 4: Heroku app
+
+1. `heroku teams` — ask the user which team to create the app in. **Do not create the
+   app until they confirm the team and the app name** (default `<REPO_NAME>-staging`).
+2. Ensure the current branch is pushed: check `git status` and
+   `git rev-parse @ @{u}`. If there's no upstream or local is ahead, ask the user to
+   push (or push for them if they say so) before continuing.
+3. Create the app if it doesn't exist (`heroku apps:info -a $APP_NAME` to check):
+   `heroku apps:create $APP_NAME --team <team>`
+4. Buildpacks, in this exact order (check `heroku buildpacks -a $APP_NAME` first):
+   1. `heroku buildpacks:add heroku/nodejs -a $APP_NAME`
+   2. `heroku buildpacks:add heroku/ruby -a $APP_NAME`
+5. Add-ons (skip any that already exist per `heroku addons -a $APP_NAME`):
+   - `heroku addons:create heroku-postgresql:essential-0 -a $APP_NAME`
+   - Papertrail: run `heroku addons:plans papertrail` and pick the plan whose
+     name/description matches "Development" (case-insensitive); if no plan matches,
+     show the plan list and ask the user which to use. Then
+     `heroku addons:create papertrail:<plan> -a $APP_NAME`.
+6. Config vars:
+   - `RAILS_MASTER_KEY`: **never read `config/master.key` (or
+     `config/credentials/production.key`) — the key must not enter the model's context.**
+     Pause and tell the user to run this in their own terminal:
+     `heroku config:set RAILS_MASTER_KEY=$(cat config/master.key) -a $APP_NAME`
+     (substitute `config/credentials/production.key` if per-environment credentials are
+     in use). Once they confirm, verify presence without exposing the value:
+     `heroku config --json -a $APP_NAME | jq 'has("RAILS_MASTER_KEY")'` — must be `true`.
+   - env-var mode only, set these yourself:
+     `heroku config:set SENTRY_DSN=<dsn> SENTRY_ENVIRONMENT=staging -a $APP_NAME`
+7. Enable runtime dyno metadata (idempotent) so Sentry can detect releases:
+   `heroku labs:enable runtime-dyno-metadata -a $APP_NAME`. This adds `HEROKU_*`
+   env vars (e.g. `HEROKU_SLUG_COMMIT`) on the next release; without it the release
+   command logs a warning about dyno metadata.
+8. Initial deploy from the local machine:
+   - `heroku git:remote -a $APP_NAME -r heroku-staging`
+   - `git push heroku-staging <current-branch>:main`
+   - If the build or release phase fails, read the build output / `heroku logs` and fix
+     the root cause before proceeding — do not create the GitHub environment until the
+     app deploys and boots.
+9. Dyno formation (after the first successful deploy):
+   - `heroku ps:type web=basic -a $APP_NAME`
+   - If the Procfile has a `worker` process: `heroku ps:scale worker=1:basic -a $APP_NAME`
+10. Verify: get the app URL from `heroku apps:info -a $APP_NAME --json` (`web_url`), then
+    curl `<web_url>/up` and confirm a 200. Save the URL as `APP_URL` (no trailing slash).
+
+## Phase 5: GitHub environment + deploy workflow
+
+1. Create the environment (idempotent PUT):
+   `gh api -X PUT repos/{owner}/{repo}/environments/Staging`
+2. Set the environment variables:
+   - `gh variable set HEROKU_APP_NAME --env Staging --body "$APP_NAME"`
+   - `gh variable set HEROKU_APP_URL --env Staging --body "$APP_URL"`
+3. Confirm `.github/workflows/deploy-staging.yml` exists (the rolemodel-rails github
+   generator installs it). If it's missing, the app skipped the github generator — tell
+   the user to run it (`rails generate rolemodel:github`) rather than hand-writing the
+   workflow. The workflow relies on the RoleModel **org-level**
+   `HEROKU_IT_SUPPORT_API_KEY` secret and `HEROKU_IT_SUPPORT_EMAIL` variable — do not
+   create per-repo copies.
+4. Verify end-to-end: `gh workflow run deploy-staging.yml` then `gh run watch` the run.
+   A green run (including its `/up` healthcheck) is the definition of done.
+
+## Production mode
+
+Same phases with these differences — ask, don't assume, on every sizing choice:
+
+- App name defaults to `<REPO_NAME>` (confirm with the user).
+- Sentry: reuse the existing project; set `SENTRY_ENVIRONMENT=production`.
+- Heroku tiers: ask the user for dyno type (basic/standard-1x/standard-2x/performance),
+  Postgres plan, and Papertrail plan instead of assuming the staging defaults.
+- GitHub environment is `Production`; the workflow is
+  `.github/workflows/deploy-production.yml` (also installed by the github generator; manual
+  `workflow_dispatch` only — production never auto-deploys on push).
+
+## Notes
+
+- Never run destructive Heroku commands (`apps:destroy`, `addons:destroy`,
+  `pg:reset`) as part of this skill.
+- Never read secret material into the model's context: `config/master.key`,
+  `config/credentials/*.key`, or the output of `heroku config` without `--json | jq`
+  filtering. When a secret must be set, have the user run the command themselves and
+  verify only the key's presence afterwards.
+- If any phase was already completed on a previous run, say so and continue with the
+  next phase rather than starting over.

data/lib/generators/rolemodel/linters/eslint/eslint_generator.rb

@@ -18,6 +18,7 @@ module Rolemodel
       ].freeze
 
       def install_eslint
+        ensure_yarn
         run "yarn add --dev #{DEV_DEPENDENCIES.join(' ')}"
       end
 

data/lib/generators/rolemodel/linters/rubocop/rubocop_generator.rb

@@ -16,7 +16,11 @@ module Rolemodel
 
       def add_config
         copy_file '.rubocop.yml', force: true
-        directory 'lib/cops'
+        # Custom cops live in .rubocop/cops (loaded via .rubocop.yml's require:),
+        # not lib/cops — keeping them out of Rails' autoload/eager-load paths so
+        # they don't crash production boot referencing the dev/test-only RuboCop
+        # constant.
+        directory '.rubocop/cops'
       end
     end
   end

data/lib/generators/rolemodel/lograge/README.md

@@ -7,4 +7,4 @@
 Installs [Lograge](https://github.com/roidrage/lograge).
 
 Lograge is an opinionated gem that slims down the amount of logs that Rails generates, with the goal of reducing
-noise that's handled by other services. For instance, it removes view rendering logs, which is a duplication of Skylight.
+noise that's handled by other services.

data/lib/generators/rolemodel/lograge/templates/config/initializers/lograge.rb

@@ -4,7 +4,7 @@ Rails.application.configure do
   config.lograge.enabled = true
   config.lograge.custom_payload do |controller|
     {
-      user_id: controller.current_user.try(:id)
+      user_id: controller.try(:current_user).try(:id)
     }
   end
   config.lograge.custom_options = lambda do |event|