studio-engine 0.116.2 → 0.117.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 506b8003a5848c60123a2707d1d6a13a847e9bcb5a64f153357f5313d7916c21
-  data.tar.gz: f5c669e411552093d0a8809d125b51edeaf14579c852d8fd87929f18ff6cf387
+  metadata.gz: 27c8703c859ad0039101776ceeeee457d6f2bd47df12a5180ebc20aa1127ad8c
+  data.tar.gz: 6b05c69deb801b08c6d1f6b31012220bf07b43cebb06b22e8becbd14fab159b0
 SHA512:
-  metadata.gz: 128d8cf927f3a12da9133867bb17d4fabb59e033f7dc72f860af62d1d8eb23e4c33c622b6892138b1a2cc10af666ad4941d9782ae96158247fb4c8980644cd26
-  data.tar.gz: c1b006da8088c23fd26bd7a32e7daef52b631b2dd0ea8e3f41646daad20e77a9b4445dc327cd3189ae1cd15265694fd8c8d62147229d98785ec8290e4a72942f
+  metadata.gz: 92bb22f3f1c1e28d7b2606541f2880ff098f3ff18986f29476fdfe66a9713c8e7565c72059e684a66b1c82251b86f0984b95bea4e8b2640775ddb0401a02e03a
+  data.tar.gz: 81332763ef29a2ccb68ca9f143b3c828022b5a3f42e6d47b30c63334ed59363a6decabe7e611c9e471bc1b9e539ade2be5f0b8ce71373d54ccce7d86f607ef05

data/CHANGELOG.md

@@ -4,6 +4,38 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.117.0 — 2026-10-28
+
+### Changed
+
+- **The default sender names the app: `"<Studio.app_name> <team@mcritchie.studio>"`.**
+  With no `RESEND_MAILER_FROM` and no `resend_from:`,
+  `Studio.mailer_from_for_transport`, `Studio.marketing_from_for_transport`, the
+  engine's `ApplicationMailer` and `studio:email:smoke` now send as the app
+  (`Studio.default_mailer_from`) rather than as "McRitchie Studio"; an app that
+  never set `app_name` still sends as "McRitchie Studio". Every app sends from
+  team@mcritchie.studio; a client's own sending domain is a paid tier upgrade
+  set through `RESEND_MAILER_FROM`. `Studio.resend_mailer_from` defaults to
+  nil and reads that default; setting it still wins. The retired `ses_from:`
+  stays ignored, so an initializer passing only `ses_from:` now gets the app's
+  own name. Set `app_name` before calling the helper in the configure block.
+
+### Added
+
+- **Production refuses an example.com sender.** The engine's after_initialize
+  raises `Studio::MailSender::PlaceholderSenderError` in production when
+  `ApplicationMailer` or `UserMailer` resolves to an example.com, .net or .org
+  address: the Rails scaffold's `app/mailers/application_mailer.rb`
+  (`default from: "from@example.com"`) shadows the engine's, and Resend refused
+  every magic link in voicebox and moms-app. It runs in rake tasks too, so
+  Heroku's `assets:precompile` fails the build and the placeholder never
+  releases. The message names the fix. A sender proc that raises at boot is
+  logged and skipped. **Consumers still carrying the scaffold mailer must
+  delete it or re-point it at `Studio.mailer_from` before bumping.**
+  [`docs/NEW_APP_SETUP.md`](docs/NEW_APP_SETUP.md). Guarded by
+  `test/lib/studio/mail_sender_test.rb` and
+  `test/integration/mail_sender_boot_test.rb`.
+
 ## 0.116.2 — 2026-10-28
 
 ### Added

data/README.md

@@ -155,7 +155,7 @@ Studio.configure do |config|
   config.welcome_message = ->(user) { "Welcome, #{user.display_name}!" }
   config.auth_methods = %i[magic_link google]
   config.registration_params = [:name, :email]
-  config.mailer_from = Studio.mailer_from_for_transport # RESEND_MAILER_FROM, else the shared sender
+  config.mailer_from = Studio.mailer_from_for_transport # RESEND_MAILER_FROM, else "<app_name> <team@mcritchie.studio>"
   config.theme_primary = "#4BAF50"   # Override default violet
   config.theme_logos = ["logo.svg"]
 

data/app/mailers/application_mailer.rb

@@ -3,5 +3,8 @@ class ApplicationMailer < ActionMailer::Base
   # the host's config/initializers/studio.rb, with an ENV fallback. No layout is
   # forced — ActionMailer renders bare if the host ships no mailer layout, and a
   # host that defines its own ApplicationMailer (e.g. turf-monster) wins outright.
-  default from: -> { Studio.mailer_from || ENV["MAILER_FROM"] || "McRitchie Studio <team@mcritchie.studio>" }
+  #
+  # Unset, it is "<Studio.app_name> <team@mcritchie.studio>": every app sends
+  # from team@ under its own name (a client's own domain is a tier upgrade).
+  default from: -> { Studio.mailer_from.presence || ENV["MAILER_FROM"].presence || Studio.default_mailer_from }
 end

data/lib/studio/email_smoke.rb

@@ -107,7 +107,7 @@ module Studio
       def sender(env = ENV)
         studio_value(:mailer_from) ||
           env_value(env, "MAILER_FROM") ||
-          "McRitchie Studio <team@mcritchie.studio>"
+          default_sender
       end
 
       def transport_label(action_mailer:, env: ENV)
@@ -128,6 +128,14 @@ module Studio
 
       private
 
+      def default_sender
+        if defined?(Studio) && Studio.respond_to?(:default_mailer_from)
+          Studio.default_mailer_from
+        else
+          "McRitchie Studio <team@mcritchie.studio>"
+        end
+      end
+
       def body_for(app_name:, to:, from:, transport:, delivery_method:, perform_deliveries:, sent_at:)
         <<~TEXT
           Email smoke test for #{app_name}

data/lib/studio/engine.rb

@@ -347,6 +347,21 @@ module Studio
     end
 
     config.after_initialize do
+      # Refuse to boot in production when ApplicationMailer (or the magic-link
+      # UserMailer) sends from an example.com placeholder: the Rails scaffold's
+      # app/mailers/application_mailer.rb shadows the engine's and Resend
+      # refuses every send. Boot, not the email smoke: Heroku's build boots
+      # production for assets:precompile, so the build fails and the bad slug
+      # never releases, while the smoke is an operator step a deploy can skip.
+      # Rake tasks are checked too, on purpose. Studio::MailSender.
+      if defined?(::ActionMailer::Base)
+        Studio::MailSender.verify!(
+          mailer_classes: %w[ApplicationMailer UserMailer].filter_map(&:safe_constantize),
+          rails_env: Rails.env,
+          logger: Rails.logger
+        )
+      end
+
       # Configure the IP -> location provider for every app that has the gem,
       # so geo detection works the same way everywhere: HTTPS (without which
       # ipinfo silently returns nothing), a 3s timeout, and a Rails.cache-backed

data/lib/studio/mail_sender.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Studio
+  # Who engine-sent mail comes from, and the production guard that refuses a
+  # placeholder sender.
+  #
+  # Every app sends from team@mcritchie.studio under its own name (Alex
+  # McRitchie's ruling, 2026-10-28); a client's own sending domain is a paid
+  # tier upgrade, set through RESEND_MAILER_FROM or `resend_from:`.
+  #
+  # The guard exists because `rails new` writes app/mailers/application_mailer.rb
+  # with `default from: "from@example.com"`. That class SHADOWS the engine's
+  # ApplicationMailer, so every mailer, the magic link included, inherits the
+  # placeholder, and Resend refuses every send. voicebox and moms-app both
+  # shipped it and nobody could sign in. Pure Ruby, so the unit suite exercises
+  # this file itself rather than a mirror of it.
+  module MailSender
+    TEAM_ADDRESS = "team@mcritchie.studio"
+    FALLBACK_NAME = "McRitchie Studio"
+    # The engine's own app_name default; an app that never named itself sends as
+    # the platform rather than as "Studio".
+    UNNAMED_APP = "Studio"
+
+    # RFC 2606 reserved second-level domains, and any host under them.
+    PLACEHOLDER_DOMAIN = /@(?:[a-z0-9-]+\.)*example\.(?:com|net|org)(?![a-z0-9.-])/i
+    # RFC 5322 "specials": a display name carrying one must be quoted.
+    DISPLAY_NAME_SPECIALS = /[()<>\[\]:;@\\,."]/
+
+    class PlaceholderSenderError < StandardError; end
+
+    module_function
+
+    # "<app name> <team@mcritchie.studio>", the sender when nothing else is set.
+    def default_for(app_name)
+      name = app_name.to_s.strip
+      name = FALLBACK_NAME if name.empty? || name == UNNAMED_APP
+      "#{display_name(name)} <#{TEAM_ADDRESS}>"
+    end
+
+    def display_name(name)
+      return name unless name.match?(DISPLAY_NAME_SPECIALS)
+
+      %("#{name.gsub(/(["\\])/) { "\\#{Regexp.last_match(1)}" }}")
+    end
+
+    # True when any address in `from` (a String or an Array of them) sits on an
+    # example.com / .net / .org domain.
+    def placeholder?(from)
+      Array(from).any? { |address| address.to_s.match?(PLACEHOLDER_DOMAIN) }
+    end
+
+    # The From: a mailer class would stamp on a message that sets none itself:
+    # its `default from:`, with a proc default evaluated the way ActionMailer
+    # evaluates it (inside a mailer instance).
+    def resolve(mailer_class)
+      from = mailer_class.default_params[:from]
+      return from unless from.respond_to?(:call)
+
+      mailer = mailer_class.send(:new)
+      from.arity == 1 ? mailer.instance_exec(mailer, &from) : mailer.instance_exec(&from)
+    end
+
+    # Raises PlaceholderSenderError in production when any of `mailer_classes`
+    # resolves to an example.com sender. Outside production it does nothing, so
+    # a test or a desk that never sends real mail is never stopped by it.
+    #
+    # It runs at boot (the engine's after_initialize), and Heroku's build runs
+    # `assets:precompile` in production, so a placeholder fails the BUILD: the
+    # bad slug never releases and the running release keeps serving. A sender
+    # that cannot be resolved at boot (its proc raises) is logged and skipped:
+    # the guard refuses a placeholder it can see, and never a boot it cannot read.
+    def verify!(mailer_classes:, rails_env:, logger: nil)
+      return :skipped unless rails_env.to_s == "production"
+
+      Array(mailer_classes).compact.uniq.each do |mailer_class|
+        from =
+          begin
+            resolve(mailer_class)
+          rescue StandardError => e
+            logger&.warn("[mail] could not resolve #{mailer_class.name}'s default sender at boot (#{e.class}: #{e.message}); placeholder guard skipped it")
+            next
+          end
+        raise PlaceholderSenderError, refusal(mailer_class, from) if placeholder?(from)
+      end
+      :verified
+    end
+
+    def refusal(mailer_class, from)
+      <<~MSG.strip
+        #{mailer_class.name} sends from #{Array(from).join(', ').inspect}, an example.com placeholder, and Resend refuses every such send (no magic link would arrive).
+        The Rails scaffold's app/mailers/application_mailer.rb shadows the engine's ApplicationMailer. Delete it, or set:
+          default from: -> { Studio.mailer_from.presence || "#{default_for(defined?(Studio) && Studio.respond_to?(:app_name) ? Studio.app_name : nil)}" }
+        and pass resend_from: (not ses_from:) to Studio.mailer_from_for_transport in config/initializers/studio.rb. See studio-engine docs/NEW_APP_SETUP.md.
+      MSG
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.116.2"
+  VERSION = "0.117.0"
 end

data/lib/studio.rb

@@ -51,6 +51,7 @@ require "studio/agent_chat"
 require "studio/username_generator"
 require "studio/public_user"
 require "studio/name_parts"
+require "studio/mail_sender"
 require "studio/s3"
 require "studio/storage"
 require "studio/image_cache"
@@ -1206,7 +1207,22 @@ module Studio
   # Default From: for engine-sent mail (magic links). Apps set this to their
   # verified sending address in config/initializers/studio.rb.
   mattr_accessor :mailer_from, default: nil
-  mattr_accessor :resend_mailer_from, default: "McRitchie Studio <team@mcritchie.studio>"
+  # The Resend sender when neither RESEND_MAILER_FROM nor `resend_from:` is
+  # given. Unset (nil), it reads "<Studio.app_name> <team@mcritchie.studio>"
+  # (Studio::MailSender.default_for): every app sends from team@ under its own
+  # name, and a client's own sending domain is a paid tier upgrade.
+  mattr_writer :resend_mailer_from, default: nil
+
+  def self.resend_mailer_from
+    value = @@resend_mailer_from
+    value.nil? || value.to_s.strip.empty? ? default_mailer_from : value
+  end
+
+  # "<Studio.app_name> <team@mcritchie.studio>"; "McRitchie Studio" for an app
+  # that never set app_name.
+  def self.default_mailer_from
+    Studio::MailSender.default_for(app_name)
+  end
 
   # Local/worktree email capture. nil means "auto": enabled when AGENT_WORKTREE
   # is truthy, otherwise disabled. Production always disables capture.
@@ -1410,8 +1426,10 @@ module Studio
 
   # The sender for transactional mail. Resend is the only provider (SES was
   # retired 2026-10-10): RESEND_MAILER_FROM, then resend_from, then
-  # Studio.resend_mailer_from. `ses_from:` is still ACCEPTED so existing
-  # consumer initializers keep booting, and IGNORED; drop it at your leisure.
+  # Studio.resend_mailer_from (unset: "<app_name> <team@mcritchie.studio>").
+  # `ses_from:` is still ACCEPTED so existing consumer initializers keep
+  # booting, and IGNORED: pass resend_from: instead. Set app_name BEFORE this
+  # call in the configure block, since the default reads it.
   def self.mailer_from_for_transport(env: ENV, ses_from: nil, resend_from: nil)
     env_value(env, "RESEND_MAILER_FROM") || resend_from || resend_mailer_from
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.116.2
+  version: 0.117.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -774,6 +774,7 @@ files:
 - lib/studio/link_token.rb
 - lib/studio/local_path.rb
 - lib/studio/log_rotation.rb
+- lib/studio/mail_sender.rb
 - lib/studio/mail_transport.rb
 - lib/studio/name_parts.rb
 - lib/studio/navbar_account_sidebar.rb