studio-engine 0.5.7 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f49e5815738a1a37139e2a5f0667daa9d2a3db14f301b7e627e441100258c3b
-  data.tar.gz: b5b94d83793c7b408332d99fc60c198dc07e7d6bb6cd342de060bb41dd5a34fd
+  metadata.gz: cba132c4901014fde9dfb1404661065d526eebf7c3db40f29198413bf6aee994
+  data.tar.gz: 676040a89d09f62b86f3bf25ffa8a07418d9976900377e8dbdab0c8088194687
 SHA512:
-  metadata.gz: 3fe90400d7a5e3653fc6fe7db6de0ffd3b6e3d03bb84b56c4a1cf200313178725068c30e58fa36c243e8166c6ce32910a14f2ef319b1a126855beb09ea835527
-  data.tar.gz: e253f58c29679abc6d70bd66c73c6d83012f2e7dacc118a9312b13395317115bda7558e7f7be55fcaff05e64395b8f082f8284eae90fca90c4476a576bf83e9a
+  metadata.gz: c33acfe1016923235e9de220b719922b9885b4da918205004b18337722d07c17f2077a67d5fe7074c48202cd01cb193fc49fe0669bcf9ea02dd0325362a6a1a2
+  data.tar.gz: cbe15ef16f573cba78e7bf494da84b68e144f0cd0790695f8393f5d37a022ec37e6b1562a6be5babeab53eed61f35c8fd7f4fa544b60e540d2ab337f1a0dc3cd

data/CHANGELOG.md

@@ -4,6 +4,23 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## v0.5.9 (2026-06-14)
+
+### Added
+- **`bin/rails "email:smoke[to@example.com]"`** — shared provider smoke-test
+  task that sends one direct ActionMailer message through the current transport
+  and prints the app, sender, transport, delivery method, `perform_deliveries`,
+  external-send status, and message id. It refuses capture/test/file modes by
+  default so agents do not mistake swallowed mail for a provider proof.
+
+## v0.5.8 (2026-06-14)
+
+### Added
+- **`StudioEmailDeliveryHelper#email_delivery_banner_status`** — shared
+  non-production banner status text for whether the current process sends
+  external email and which transport is active (`resend`, `ses`, `capture`, or
+  the ActionMailer delivery method).
+
 ## v0.5.7 (2026-06-14)
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ Shared Rails engine for McRitchie apps. Provides authentication, error handling,
 gem "studio-engine", "~> 0.5"
 ```
 
-Then `bundle install`. The current release is **v0.5.7**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
+Then `bundle install`. The current release is **v0.5.9**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
 
 > Published to RubyGems as of v0.4.0 (2026-05-17). New installs should use the RubyGems form, which the consumer Rails apps (`mcritchie-studio`, `turf-monster`) already use.
 

data/app/helpers/studio_email_delivery_helper.rb

@@ -0,0 +1,35 @@
+module StudioEmailDeliveryHelper
+  NON_DELIVERING_EMAIL_METHODS = %w[test file].freeze
+
+  def email_delivery_banner_status
+    delivery_method = studio_email_delivery_method
+    capture_enabled = Studio.local_email_capture?
+    sends_email = studio_email_perform_deliveries? && !capture_enabled &&
+                  !NON_DELIVERING_EMAIL_METHODS.include?(delivery_method)
+
+    "EMAIL SEND #{sends_email} · #{email_delivery_transport_label(delivery_method, capture_enabled)}"
+  end
+
+  def email_delivery_transport_label(delivery_method = studio_email_delivery_method,
+                                     capture_enabled = Studio.local_email_capture?)
+    return "capture" if capture_enabled
+    return "ses" if Studio.ses_transport_ready?
+    return "resend" if delivery_method == "resend"
+
+    delivery_method.to_s.strip.empty? ? "unknown" : delivery_method
+  end
+
+  private
+
+  def studio_email_delivery_method
+    return "unknown" unless defined?(ActionMailer)
+
+    ActionMailer::Base.delivery_method.to_s
+  end
+
+  def studio_email_perform_deliveries?
+    return false unless defined?(ActionMailer)
+
+    ActionMailer::Base.perform_deliveries
+  end
+end

data/lib/studio/email_smoke.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Studio
+  class EmailSmoke
+    NON_EXTERNAL_METHODS = %w[test file].freeze
+
+    Result = Struct.new(
+      :app_name,
+      :to,
+      :from,
+      :subject,
+      :transport,
+      :delivery_method,
+      :perform_deliveries,
+      :external_delivery,
+      :message_id,
+      keyword_init: true
+    ) do
+      def report_lines
+        [
+          "Email smoke -> #{external_delivery ? 'sent' : 'not externally sent'}",
+          "  app=#{app_name}",
+          "  to=#{to}",
+          "  from=#{from}",
+          "  subject=#{subject}",
+          "  transport=#{transport}",
+          "  delivery_method=#{delivery_method}",
+          "  perform_deliveries=#{perform_deliveries}",
+          "  external_delivery=#{external_delivery}",
+          "  message_id=#{message_id || '(none)'}"
+        ]
+      end
+    end
+
+    class NonExternalDeliveryError < StandardError
+      attr_reader :result
+
+      def initialize(result)
+        @result = result
+        super("email smoke would not send externally")
+      end
+    end
+
+    class << self
+      def deliver(to:,
+                  action_mailer: defined?(ActionMailer) ? ActionMailer::Base : nil,
+                  env: ENV,
+                  app_name: defined?(Studio) && Studio.respond_to?(:app_name) ? Studio.app_name : "Studio",
+                  require_external: true,
+                  clock: Time)
+        raise ArgumentError, "action_mailer is required" unless action_mailer
+
+        recipient = to.to_s.strip
+        raise ArgumentError, "recipient email is required" if recipient.empty?
+
+        from = sender(env)
+        subject = "#{app_name} email smoke test"
+        body = body_for(
+          app_name: app_name,
+          to: recipient,
+          from: from,
+          transport: transport_label(action_mailer: action_mailer, env: env),
+          delivery_method: action_mailer.delivery_method,
+          perform_deliveries: action_mailer.perform_deliveries,
+          sent_at: clock.now.utc
+        )
+        result = result_for(
+          app_name: app_name,
+          to: recipient,
+          from: from,
+          subject: subject,
+          action_mailer: action_mailer,
+          env: env
+        )
+
+        if require_external && !result.external_delivery
+          raise NonExternalDeliveryError, result
+        end
+
+        message = action_mailer.mail(
+          to: recipient,
+          from: from,
+          subject: subject,
+          body: body
+        )
+        delivered = message.deliver_now
+        result.message_id = delivered.message_id if delivered.respond_to?(:message_id)
+        result
+      end
+
+      def result_for(app_name:, to:, from:, subject:, action_mailer:, env: ENV)
+        delivery_method = action_mailer.delivery_method.to_s
+        Result.new(
+          app_name: app_name,
+          to: to,
+          from: from,
+          subject: subject,
+          transport: transport_label(action_mailer: action_mailer, env: env),
+          delivery_method: delivery_method,
+          perform_deliveries: !!action_mailer.perform_deliveries,
+          external_delivery: external_delivery?(action_mailer: action_mailer, env: env)
+        )
+      end
+
+      def sender(env = ENV)
+        studio_value(:mailer_from) ||
+          env_value(env, "MAILER_FROM") ||
+          "McRitchie Studio <team@mcritchie.studio>"
+      end
+
+      def transport_label(action_mailer:, env: ENV)
+        return "capture" if studio_local_email_capture?
+        return "ses" if studio_ses_transport_ready?(env)
+
+        delivery_method = action_mailer.delivery_method.to_s
+        return "resend" if delivery_method == "resend"
+
+        delivery_method.empty? ? "unknown" : delivery_method
+      end
+
+      def external_delivery?(action_mailer:, env: ENV)
+        return false if studio_local_email_capture?
+
+        delivery_method = action_mailer.delivery_method.to_s
+        !!action_mailer.perform_deliveries && !NON_EXTERNAL_METHODS.include?(delivery_method)
+      end
+
+      private
+
+      def body_for(app_name:, to:, from:, transport:, delivery_method:, perform_deliveries:, sent_at:)
+        <<~TEXT
+          Email smoke test for #{app_name}
+
+          This message was sent by studio-engine's shared email smoke task.
+
+          To: #{to}
+          From: #{from}
+          Transport: #{transport}
+          Delivery method: #{delivery_method}
+          perform_deliveries: #{perform_deliveries}
+          Sent at: #{sent_at.iso8601}
+
+          If you did not expect this message, no account action was performed.
+        TEXT
+      end
+
+      def env_value(env, key)
+        value = env[key]
+        value if value && !value.to_s.strip.empty?
+      end
+
+      def studio_value(method)
+        return unless defined?(Studio) && Studio.respond_to?(method)
+
+        value = Studio.public_send(method)
+        value if value && !value.to_s.strip.empty?
+      end
+
+      def studio_ses_transport_ready?(env)
+        if defined?(Studio) && Studio.respond_to?(:ses_transport_ready?)
+          Studio.ses_transport_ready?(env)
+        else
+          env["MAIL_TRANSPORT"].to_s.downcase == "ses" &&
+            env_value(env, "SES_SMTP_USERNAME") &&
+            env_value(env, "SES_SMTP_PASSWORD")
+        end
+      end
+
+      def studio_local_email_capture?
+        defined?(Studio) && Studio.respond_to?(:local_email_capture?) && Studio.local_email_capture?
+      end
+    end
+  end
+end

data/lib/studio/engine.rb

@@ -1,6 +1,7 @@
 module Studio
   class Engine < ::Rails::Engine
     rake_tasks do
+      load File.expand_path("../tasks/studio_email.rake", __dir__)
       load File.expand_path("../tasks/studio_ses.rake", __dir__)
     end
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.5.7"
+  VERSION = "0.5.9"
 end

data/lib/studio.rb

@@ -6,6 +6,7 @@ require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
 require "studio/email"
+require "studio/email_smoke"
 require "studio/mail_transport"
 
 module Studio

data/lib/tasks/studio_email.rake

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+unless Rake::Task.task_defined?("email:smoke")
+  namespace :email do
+    desc "Send one provider smoke-test email: bin/rails \"email:smoke[to@example.com]\""
+    task :smoke, [:to] => :environment do |_task, args|
+      require "studio/email_smoke"
+
+      recipient = args[:to] || ENV["EMAIL_SMOKE_TO"] || ENV["TO"]
+      abort "Usage: bin/rails \"email:smoke[to@example.com]\" or EMAIL_SMOKE_TO=to@example.com bin/rails email:smoke" if recipient.to_s.strip.empty?
+
+      require_external = !%w[1 true yes on].include?(ENV["EMAIL_SMOKE_ALLOW_NON_EXTERNAL"].to_s.strip.downcase)
+      result = Studio::EmailSmoke.deliver(to: recipient, require_external: require_external)
+      puts result.report_lines
+    rescue Studio::EmailSmoke::NonExternalDeliveryError => e
+      puts e.result.report_lines
+      abort "Refusing to call this a provider smoke test because mail would not leave the process. Set EMAIL_SMOKE_ALLOW_NON_EXTERNAL=1 only when intentionally proving capture/test mode."
+    end
+  end
+end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.9
 platform: ruby
 authors:
 - Alex McRitchie
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -151,6 +152,7 @@ files:
 - app/controllers/solana_sessions_controller.rb
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/theme_settings_controller.rb
+- app/helpers/studio_email_delivery_helper.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
 - app/jobs/studio/email_delivery_job.rb
@@ -208,6 +210,7 @@ files:
 - lib/studio.rb
 - lib/studio/color_scale.rb
 - lib/studio/email.rb
+- lib/studio/email_smoke.rb
 - lib/studio/engine.rb
 - lib/studio/image_cache.rb
 - lib/studio/mail_transport.rb
@@ -215,6 +218,7 @@ files:
 - lib/studio/theme_resolver.rb
 - lib/studio/username_generator.rb
 - lib/studio/version.rb
+- lib/tasks/studio_email.rake
 - lib/tasks/studio_ses.rake
 - studio-engine.gemspec
 - tailwind/studio.tailwind.config.js
@@ -226,6 +230,7 @@ metadata:
   source_code_uri: https://github.com/amcritchie/studio-engine/tree/main
   bug_tracker_uri: https://github.com/amcritchie/studio-engine/issues
   changelog_uri: https://github.com/amcritchie/studio-engine/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -240,7 +245,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 3.5.11
+signing_key:
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching