studio-engine 0.5.4 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf5f392cf1242e7e541db8ceb7d4ad1865ef2f71f3c787e582de4ac51fc6f836
-  data.tar.gz: 5498dc5d35fbe69c589ba197f3d6fadacbe2d30e93da8b226f0a7d5309ad5ec5
+  metadata.gz: 7dde49831782823962437f0efab2c8334fe0efc4376873ee9b9c4c2486aa4d1f
+  data.tar.gz: c9cb4750ad4298869623db8a98e93662b101a1b2ce055fb779d15a3095ba1529
 SHA512:
-  metadata.gz: 3c38ce794988d826bc9f91ad47786f314ea94dfebdfb42164741ffe70379dfb912d3073ac74f61f96a2814157fdcb651293c6d5d3ea9ce9927567d982c153120
-  data.tar.gz: 6046671a635cef22c25af3231d3e562d258ab0fa45ab568d2255d2c734c44d3e27950acd49ead0bda282b17075def27a6ba6c8e35df14807b6df4e2575890d3c
+  metadata.gz: bb82ea299130783431b2dfea4fac8ddece0728b7f49d6ea15c1cff49d819fb6687a5a03f4eb80d4a0f8cb590cf78e45ccb1cdec410bc042ba6caed95bdde24b0
+  data.tar.gz: e93039393ac8e344f7eef097ce55629f41cdefdb8f48be418ad3f8a7228e1c01363a3646ecd23708cffa182d3e905e17a8c1b2f8eccbfe6b97a3c9ef203a855b

data/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 No entries yet.
 
+## v0.5.6 (2026-06-14)
+
+### Added
+- **`Studio.wallet_address_method` / `Studio.user_wallet_address(user)`** —
+  shared wallet-address adapter for SSO/session awareness. Defaults support
+  `wallet_address` and `solana_address`; apps can configure another method.
+
+## v0.5.5 (2026-06-14)
+
+### Added
+- **Local email inbox** at `/_studio/local_emails` for non-production localhost requests. It lists recent outbox rows and exposes local proof links for magic-link, email-verification, wallet-export, and email-change emails.
+- **`Studio.local_email_capture?`** — shared capture switch for local/worktree stacks. `LOCAL_EMAIL_CAPTURE=1` or `AGENT_WORKTREE=1` records delivery rows without enqueueing external sends.
+
 ## v0.5.4 (2026-06-14)
 
 ### Changed

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.4**; see [`CHANGELOG.md`](./CHANGELOG.md) for the history.
+Then `bundle install`. The current release is **v0.5.5**; 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.
 
@@ -64,6 +64,8 @@ end
 
 This draws the enabled auth routes (`/login`, `/signup`, `/logout`, magic-link request/confirm/consume routes, Solana routes), OAuth callbacks, optional SSO routes, `/error_logs`, and `/admin/theme`. Magic-link emails point at the inert GET confirmation route; the single-use token is consumed only by the CSRF-protected POST to `magic_link_consume_path`.
 
+In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
+
 ## Overriding Views
 
 This is a non-isolated engine -- app views at the same path automatically override engine views. For example, placing `app/views/sessions/new.html.erb` in the consuming app replaces the engine's login page.

data/app/controllers/concerns/studio/error_handling.rb

@@ -49,7 +49,7 @@ module Studio
         session[:sso_name]     = user.try(:name)
         session[:sso_provider] = user.provider
         session[:sso_uid]      = user.uid
-        session[:sso_wallet]   = user.try(:wallet_address)
+        session[:sso_wallet]   = Studio.user_wallet_address(user)
         session[:sso_source]   = Studio.app_name
         session[:sso_logo]     = Studio.sso_logo
       end

data/app/controllers/studio/local_emails_controller.rb

@@ -0,0 +1,108 @@
+module Studio
+  class LocalEmailsController < ApplicationController
+    skip_before_action :require_authentication, raise: false
+    layout false
+
+    before_action :require_local_development!
+
+    def index
+      @deliveries = delivery_records.map { |record| serialize_delivery(record) }
+
+      respond_to do |format|
+        format.html
+        format.json do
+          render json: {
+            capture_enabled: Studio.local_email_capture?,
+            inbox_url: request.original_url.sub(/\.json\z/, ""),
+            deliveries: @deliveries
+          }
+        end
+      end
+    end
+
+    private
+
+    def require_local_development!
+      head :not_found if Rails.env.production? || !request.local?
+    end
+
+    def delivery_records
+      klass = delivery_class
+      return [] unless klass
+
+      klass.recent.limit(50)
+    end
+
+    def delivery_class
+      if Object.const_defined?(:EmailDelivery, false)
+        return Object.const_get(:EmailDelivery, false)
+      end
+
+      if Studio.const_defined?(:EmailDelivery, false) && Studio::EmailDelivery.respond_to?(:available?) && Studio::EmailDelivery.available?
+        return Studio::EmailDelivery
+      end
+
+      nil
+    end
+
+    def serialize_delivery(record)
+      args = deserialize_args(record.args)
+      kwargs = deserialize_kwargs(record.kwargs)
+      {
+        id: record.id,
+        email_key: record.email_key,
+        mailer: record.mailer,
+        action: record.action,
+        to: record.to,
+        sent: record.sent?,
+        sent_at: record.sent_at,
+        error: record.error,
+        created_at: record.created_at,
+        action_url: local_action_url(record, args),
+        args_preview: args.map { |arg| preview_value(arg) },
+        kwargs_preview: kwargs.transform_values { |value| preview_value(value) }
+      }
+    end
+
+    def deserialize_args(value)
+      ActiveJob::Arguments.deserialize(value || [])
+    rescue StandardError
+      []
+    end
+
+    def deserialize_kwargs(value)
+      deserialized = ActiveJob::Arguments.deserialize([value || {}]).first
+      deserialized.respond_to?(:symbolize_keys) ? deserialized.symbolize_keys : {}
+    rescue StandardError
+      {}
+    end
+
+    def local_action_url(record, args)
+      token = args[1].to_s
+      return if token.empty?
+
+      path =
+        case record.email_key
+        when /#magic_link\z/
+          "/magic_link/#{ERB::Util.url_encode(token)}"
+        when /#email_verification\z/
+          "/email_verification/#{ERB::Util.url_encode(token)}"
+        when /#wallet_export\z/
+          "/account/wallet/export/#{ERB::Util.url_encode(token)}"
+        when /#email_change_confirmation\z/
+          "/account/email/confirm/#{ERB::Util.url_encode(token)}"
+        end
+
+      "#{request.base_url}#{path}" if path
+    end
+
+    def preview_value(value)
+      case value
+      when String, Numeric, TrueClass, FalseClass, NilClass
+        value
+      else
+        value.respond_to?(:to_global_id) ? value.to_global_id.to_s : value.to_s
+      end
+    end
+  end
+end

data/app/models/session_context.rb

@@ -63,6 +63,8 @@ class SessionContext
 
   # Primary wallet address (web3 preferred), or nil when logged out / wallet-less.
   def address
+    return Studio.user_wallet_address(user) if defined?(Studio) && Studio.respond_to?(:user_wallet_address)
+
     return nil unless user.respond_to?(:solana_address)
     user.solana_address
   end

data/app/models/studio/email_delivery.rb

@@ -23,12 +23,13 @@ module Studio
         args: ActiveJob::Arguments.serialize(args),
         kwargs: ActiveJob::Arguments.serialize([kwargs]).first
       )
-      Studio::EmailDeliveryJob.perform_later(record.id)
+      Studio::EmailDeliveryJob.perform_later(record.id) unless Studio.local_email_capture?
       record
     end
 
     def deliver_now!
       return if sent?
+      return update!(error: "local email capture enabled; not sent") if Studio.local_email_capture?
 
       pos = ActiveJob::Arguments.deserialize(args)
       kw = ActiveJob::Arguments.deserialize([kwargs]).first.symbolize_keys

data/app/views/studio/local_emails/index.html.erb

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>Local Emails - <%= Studio.app_name %></title>
+    <style>
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        background: #10101f;
+        color: #f8fafc;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+      main { width: min(1180px, calc(100% - 32px)); margin: 32px auto; }
+      header { display: flex; align-items: flex-start; justify-content: space-between; gap: 24px; margin-bottom: 24px; }
+      h1 { margin: 0 0 8px; font-size: 28px; line-height: 1.2; }
+      p { margin: 0; color: #b6bdd3; }
+      .pill { display: inline-flex; align-items: center; border: 1px solid #3b3b62; border-radius: 999px; padding: 6px 12px; color: #d8dcf0; background: #18182b; font-size: 13px; white-space: nowrap; }
+      .notice { margin-bottom: 18px; border: 1px solid #3b3b62; border-radius: 8px; background: #18182b; padding: 14px 16px; color: #cbd2e8; }
+      table { width: 100%; border-collapse: collapse; overflow: hidden; border-radius: 8px; background: #18182b; }
+      th, td { padding: 12px 14px; border-bottom: 1px solid #2f2f4d; text-align: left; vertical-align: top; }
+      th { color: #9fa7c3; font-size: 12px; text-transform: uppercase; }
+      td { color: #eef2ff; font-size: 14px; }
+      tr:last-child td { border-bottom: 0; }
+      code { color: #c4b5fd; word-break: break-word; }
+      .muted { color: #9fa7c3; }
+      .error { color: #fda4af; }
+      .button { display: inline-flex; align-items: center; justify-content: center; border-radius: 8px; padding: 8px 12px; background: #4baf50; color: #fff; font-weight: 700; text-decoration: none; white-space: nowrap; }
+      .empty { border: 1px solid #3b3b62; border-radius: 8px; background: #18182b; padding: 24px; color: #cbd2e8; }
+      @media (max-width: 760px) {
+        header { display: block; }
+        .pill { margin-top: 14px; }
+        table, thead, tbody, tr, th, td { display: block; }
+        thead { display: none; }
+        tr { border-bottom: 1px solid #2f2f4d; padding: 10px 0; }
+        td { border-bottom: 0; padding: 8px 14px; }
+        td::before { content: attr(data-label); display: block; color: #9fa7c3; font-size: 12px; text-transform: uppercase; margin-bottom: 4px; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <header>
+        <div>
+          <h1>Local Emails</h1>
+          <p>Recent outbox rows for this local <%= Studio.app_name %> stack.</p>
+        </div>
+        <span class="pill">Capture <%= Studio.local_email_capture? ? "enabled" : "disabled" %></span>
+      </header>
+
+      <% if Studio.local_email_capture? %>
+        <div class="notice">This stack records email intents and does not send them to external providers.</div>
+      <% else %>
+        <div class="notice">Capture is disabled. This page still shows recent delivery rows, but this stack may send real email when workers run.</div>
+      <% end %>
+
+      <% if @deliveries.empty? %>
+        <div class="empty">No email deliveries have been recorded yet.</div>
+      <% else %>
+        <table>
+          <thead>
+            <tr>
+              <th>When</th>
+              <th>Message</th>
+              <th>To</th>
+              <th>Status</th>
+              <th>Proof URL</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @deliveries.each do |delivery| %>
+              <tr>
+                <td data-label="When"><%= delivery[:created_at]&.strftime("%Y-%m-%d %H:%M:%S") %></td>
+                <td data-label="Message"><code><%= delivery[:email_key] %></code></td>
+                <td data-label="To"><%= delivery[:to] %></td>
+                <td data-label="Status">
+                  <% if delivery[:sent] %>
+                    Sent
+                  <% elsif delivery[:error].present? %>
+                    <span class="error"><%= delivery[:error] %></span>
+                  <% else %>
+                    <span class="muted">Captured</span>
+                  <% end %>
+                </td>
+                <td data-label="Proof URL">
+                  <% if delivery[:action_url].present? %>
+                    <a class="button" href="<%= delivery[:action_url] %>">Open link</a>
+                  <% else %>
+                    <span class="muted">No local action URL</span>
+                  <% end %>
+                </td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      <% end %>
+    </main>
+  </body>
+</html>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.5.4"
+  VERSION = "0.5.6"
 end

data/lib/studio.rb

@@ -16,6 +16,7 @@ module Studio
   mattr_accessor :configure_new_user,  default: ->(user) {}
   mattr_accessor :configure_sso_user,  default: ->(user) {}
   mattr_accessor :sso_logo,            default: nil
+  mattr_accessor :wallet_address_method, default: nil
   mattr_accessor :theme_logos,         default: []
 
   # ---- Authentication ------------------------------------------------------
@@ -41,6 +42,10 @@ module Studio
   # verified sending address in config/initializers/studio.rb.
   mattr_accessor :mailer_from, default: nil
 
+  # Local/worktree email capture. nil means "auto": enabled when AGENT_WORKTREE
+  # is truthy, otherwise disabled. Production always disables capture.
+  mattr_accessor :local_email_capture, default: nil
+
   # Theme role colors (7 roles)
   mattr_accessor :theme_primary,  default: "#8E82FE"
   mattr_accessor :theme_dark,     default: "#1A1535"
@@ -88,6 +93,26 @@ module Studio
     auth_methods.include?(method.to_sym)
   end
 
+  def self.local_email_capture?
+    return false if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+    return !!local_email_capture unless local_email_capture.nil?
+
+    env_truthy?(ENV["LOCAL_EMAIL_CAPTURE"]) || env_truthy?(ENV["AGENT_WORKTREE"])
+  end
+
+  def self.user_wallet_address(user)
+    return nil unless user
+
+    [wallet_address_method, :wallet_address, :solana_address].compact.each do |method|
+      next unless user.respond_to?(method)
+
+      value = user.public_send(method)
+      return value if value && !(value.respond_to?(:empty?) && value.empty?)
+    end
+
+    nil
+  end
+
   # Verifies that the host app's User model satisfies the engine's expected
   # contract. Raises Studio::UserContractError with a clear pointer to
   # docs/USER_CONTRACT.md if anything required is missing. Called from
@@ -146,6 +171,10 @@ module Studio
     entry ? "/#{entry[:file]}" : nil
   end
 
+  def self.env_truthy?(value)
+    %w[1 true yes on].include?(value.to_s.strip.downcase)
+  end
+
   def self.routes(router)
     router.instance_exec do
       get  "login",  to: "sessions#new"
@@ -158,6 +187,10 @@ module Studio
       get  "auth/:provider/callback", to: "omniauth_callbacks#create"
       get  "auth/failure", to: "omniauth_callbacks#failure"
 
+      unless defined?(Rails) && Rails.env.production?
+        get "_studio/local_emails", to: "studio/local_emails#index", as: :studio_local_emails
+      end
+
       # Passwordless email (magic link). Helpers: magic_link_request_path (POST
       # to request a link), magic_link_path(token) / magic_link_url(token:)
       # for the emailed GET confirmation page, and magic_link_consume_path(token)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.6
 platform: ruby
 authors:
 - Alex McRitchie
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -150,6 +149,7 @@ files:
 - app/controllers/schema_controller.rb
 - app/controllers/sessions_controller.rb
 - app/controllers/solana_sessions_controller.rb
+- app/controllers/studio/local_emails_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
@@ -191,6 +191,7 @@ files:
 - app/views/sessions/_sso_continue.html.erb
 - app/views/sessions/new.html.erb
 - app/views/studio/_cropper_assets.html.erb
+- app/views/studio/local_emails/index.html.erb
 - app/views/studio/modals/_crop_photo.html.erb
 - app/views/studio/modals/_host.html.erb
 - app/views/studio/modals/_image_upload.html.erb
@@ -225,7 +226,6 @@ 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,8 +240,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.9
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching