studio-engine 0.5.8 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 401a5db38e438ea4335d910bc67c88559739cb227a7377503c152cb2cea409ba
-  data.tar.gz: 12703eff81b8af83d9d73e26ebfbd7ec11b6a53444372c8330f32f7b09b89113
+  metadata.gz: cba132c4901014fde9dfb1404661065d526eebf7c3db40f29198413bf6aee994
+  data.tar.gz: 676040a89d09f62b86f3bf25ffa8a07418d9976900377e8dbdab0c8088194687
 SHA512:
-  metadata.gz: 8eff2ade70b7a335ac0f50a15e2085fa05a0ba4d5ae7ff36ff7a03c8ec811022fb4d6ece26fed7639c9faf3431d66a1548cc86ed0f261cf255d2dcd4c84ad51e
-  data.tar.gz: 72df2ccff7e151d391edd34c62d1a1e1ac1782317a14548f0fcfd541e58646dba89fc13ea254a1a141d1347d9016ee42e04b7c475a426eb9c8eb959725c6a588
+  metadata.gz: c33acfe1016923235e9de220b719922b9885b4da918205004b18337722d07c17f2077a67d5fe7074c48202cd01cb193fc49fe0669bcf9ea02dd0325362a6a1a2
+  data.tar.gz: cbe15ef16f573cba78e7bf494da84b68e144f0cd0790695f8393f5d37a022ec37e6b1562a6be5babeab53eed61f35c8fd7f4fa544b60e540d2ab337f1a0dc3cd

data/CHANGELOG.md

@@ -4,6 +4,15 @@ 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

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.8**; 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/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.8"
+  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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.5.8
+  version: 0.5.9
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-14 00:00:00.000000000 Z
+date: 2026-06-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -210,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
@@ -217,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