studio-engine 0.104.0 → 0.105.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b96c9bc4046a0dbf2f37602c67e682a23014076b8bb75e3267fa24b039262b9
-  data.tar.gz: efd37090658d3d72ab2dbda97c3f7bc0c44ceaae606ffad8ba5daa737cb23758
+  metadata.gz: b5e9eefb6bad47abe79849c59d248536a70bb9275c6f7074210bfdd88b975e76
+  data.tar.gz: 69fd09fd720f85729f90cb354ff8273665ec4f98b04f63368bbc093e57188468
 SHA512:
-  metadata.gz: 5762cb7806278a0d147c2b352a08dea58f4e0b81f68c09dd5a6a94c2734c48350146044aef913518909fd9b20cba19ea56802f0a423ba6efad1fa330b473a3db
-  data.tar.gz: c1c387fcdf9f31d87e74e5e9d3bb18976afb289fee862841cd316ed67f72d7eea305e0ca1e2ea393ceb7b6f5f11739ca99dbfb5d8318362324f0b98e99d845ac
+  metadata.gz: 66b905941833f30f59c9595b34a2c5485089685212e44970acb04f090f0d6fd157681b2523e11c577037bf666420743f5a9646ed50d8d8a4e3593861877aa4d7
+  data.tar.gz: cbb687874917a0b899690134eaa19ba94b80d52160c74e846b3b2d81295f2ef64050ca6b3b51591b5184f6bd4c53a65037b8f1741bac2e7c9a7a9b1e85a62be4

data/CHANGELOG.md

@@ -4,6 +4,23 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.105.0 — 2026-10-13
+
+### Added
+
+- **`Studio::HealthReportJob`: a daily application health report, off by
+  default.** One email at 07:00 in the app's zone listing the last day's
+  signups, `ErrorLog` errors grouped by class and message with counts and first
+  and last seen, and contact-form submissions when the app names a source; a
+  quiet day sends a one-line all-clear. The day runs 07:00 to 07:00 on the
+  wall clock, so a daylight-saving change makes it 23 or 25 hours, and a late
+  run reports the same day. Nothing sends until a host schedules the job AND
+  names a recipient (`config.health_report_to` or `STUDIO_HEALTH_REPORT_TO`);
+  QA never sends. New settings: `health_report_to`, `health_report_zone`
+  (default `America/Denver`), `health_report_hour` (default `7`),
+  `health_report_signups` (default: the host's `User` by `created_at`) and
+  `health_report_contacts` (default: none). See `docs/HEALTH_REPORT.md`.
+
 ## 0.104.0 — 2026-10-11
 
 ### Added

data/app/jobs/studio/health_report_job.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Studio
+  # Emails the daily application health report (Studio::HealthReport). The
+  # engine schedules nothing: a host turns it on by registering this job at
+  # Studio.health_report_hour in Studio.health_report_zone AND naming a
+  # recipient. docs/HEALTH_REPORT.md has both snippets.
+  #
+  # Best-effort, like mcritchie-studio's ContactFlaggedDigestJob: a failure is an
+  # ErrorLog receipt (and so a line in tomorrow's report), never a retry storm.
+  class HealthReportJob < (defined?(::ApplicationJob) ? ::ApplicationJob : ActiveJob::Base)
+    queue_as :default
+
+    def perform(now = Time.current)
+      # QA boots RAILS_ENV=production with a copy of nothing anyone needs to hear about.
+      return if Studio.qa_environment?
+
+      recipients = Studio::HealthReport.recipients
+      return if recipients.empty?
+
+      to = recipients.join(", ")
+      window_end = Studio::HealthReport.window(now).end
+      Studio::Email.deliver(Studio::HealthReportMailer, :daily, window_end.iso8601, to, to: to)
+    rescue StandardError => e
+      ErrorLog.capture!(e)
+    end
+  end
+end

data/app/mailers/studio/health_report_mailer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Studio
+  # The daily application health report. Namespaced so a host's own mailers
+  # cannot shadow it (see Studio::NewsletterMailer).
+  #
+  # It takes the window's END as an ISO-8601 string, not a built report, so the
+  # outbox stores a plain string and a retry re-reads the SAME day.
+  class HealthReportMailer < ApplicationMailer
+    # The report is an operator memo, not a branded email: its own plain
+    # document, whatever mailer layout the host's ApplicationMailer sets.
+    layout false
+
+    def daily(window_end, to)
+      finish = Time.iso8601(window_end.to_s)
+      @report = Studio::HealthReport.build(window: Studio::HealthReport.window_ending(finish))
+      mail(to: to, subject: @report.subject)
+    end
+  end
+end

data/app/views/studio/health_report_mailer/daily.html.erb

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= @report.subject %></title>
+</head>
+<body style="margin:0;padding:24px 12px;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif;color:#18181b;">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:600px;margin:0 auto;background:#ffffff;border:1px solid #e4e4e7;border-radius:8px;">
+    <tr>
+      <td style="padding:20px 24px;border-bottom:1px solid #e4e4e7;">
+        <div style="font-size:18px;font-weight:700;"><%= @report.app_name %> health report</div>
+        <div style="font-size:13px;color:#52525b;margin-top:4px;"><%= @report.window_label %></div>
+      </td>
+    </tr>
+    <% if @report.quiet? %>
+      <tr>
+        <td style="padding:20px 24px;font-size:15px;">
+          <strong style="color:#166534;">All clear:</strong>
+          no <%= @report.sections.map { |s| s.title.downcase }.to_sentence(two_words_connector: " or ", last_word_connector: ", or ") %> in the last day.
+        </td>
+      </tr>
+    <% else %>
+      <% @report.sections.each do |section| %>
+        <tr>
+          <td style="padding:16px 24px;border-bottom:1px solid #f4f4f5;">
+            <div style="font-size:15px;font-weight:600;">
+              <%= section.title %>:
+              <% if section.failed? %>
+                <span style="color:#b91c1c;">could not be read (<%= section.failure %>)</span>
+              <% else %>
+                <span style="color:<%= section.title == "Errors" && section.count.positive? ? "#b91c1c" : "#18181b" %>;"><%= section.count %></span>
+              <% end %>
+            </div>
+            <% if section.items.any? %>
+              <ul style="margin:8px 0 0;padding-left:20px;font-size:14px;color:#3f3f46;overflow-wrap:anywhere;">
+                <% section.items.each do |item| %>
+                  <li style="margin:2px 0;"><%= item %></li>
+                <% end %>
+                <% if section.more.positive? %>
+                  <li style="margin:2px 0;color:#71717a;">and <%= section.more %> more</li>
+                <% end %>
+              </ul>
+            <% end %>
+            <% if section.title == "Errors" && @report.error_groups.any? %>
+              <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="margin-top:8px;font-size:13px;border-collapse:collapse;">
+                <% @report.error_groups.each do |group| %>
+                  <tr>
+                    <td style="padding:6px 8px 6px 0;vertical-align:top;font-weight:700;white-space:nowrap;color:#b91c1c;"><%= group.count %>&times;</td>
+                    <td style="padding:6px 0;vertical-align:top;border-top:1px solid #f4f4f5;">
+                      <div style="font-family:Menlo,Consolas,monospace;font-weight:600;word-break:break-all;overflow-wrap:anywhere;"><%= group.error_class %></div>
+                      <div style="color:#3f3f46;word-break:break-word;"><%= group.message.squish.truncate(200) %></div>
+                      <div style="color:#71717a;font-size:12px;">first <%= @report.stamp(group.first_seen) %> &middot; last <%= @report.stamp(group.last_seen) %></div>
+                    </td>
+                  </tr>
+                <% end %>
+              </table>
+              <% if @report.error_kinds > @report.error_groups.size %>
+                <div style="font-size:13px;color:#71717a;margin-top:6px;">and <%= @report.error_kinds - @report.error_groups.size %> more kinds</div>
+              <% end %>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+    <% end %>
+    <tr>
+      <td style="padding:12px 24px;font-size:12px;color:#71717a;">Your daily report from McRitchie Studio.</td>
+    </tr>
+  </table>
+</body>
+</html>

data/app/views/studio/health_report_mailer/daily.text.erb

@@ -0,0 +1,26 @@
+<%= @report.app_name %> health report
+<%= @report.window_label %>
+
+<% if @report.quiet? -%>
+All clear: no <%= @report.sections.map { |s| s.title.downcase }.to_sentence(two_words_connector: " or ", last_word_connector: ", or ") %> in the last day.
+<% else -%>
+<% @report.sections.each do |section| -%>
+<%= section.title %>: <%= section.failed? ? "could not be read (#{section.failure})" : section.count %>
+<% section.items.each do |item| -%>
+  - <%= item %>
+<% end -%>
+<% if section.more.positive? -%>
+  ... and <%= section.more %> more
+<% end -%>
+<% if section.title == "Errors" -%>
+<% @report.error_groups.each do |group| -%>
+  <%= group.count %>x <%= group.error_class %>: <%= group.message.squish.truncate(160) %>
+     first <%= @report.stamp(group.first_seen) %>, last <%= @report.stamp(group.last_seen) %>
+<% end -%>
+<% if @report.error_kinds > @report.error_groups.size -%>
+  ... and <%= @report.error_kinds - @report.error_groups.size %> more kinds
+<% end -%>
+<% end -%>
+
+<% end -%>
+<% end -%>

data/lib/studio/health_report.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/time"
+require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/try"
+require "active_support/core_ext/string/filters"
+
+# The daily application health report: signups, errors and (optionally) contact
+# messages from the last day, emailed at 07:00 in the app's zone. The full
+# adoption guide is docs/HEALTH_REPORT.md.
+#
+# OFF BY DEFAULT, TWICE. Nothing sends until a host both SCHEDULES
+# Studio::HealthReportJob (config/recurring.yml or sidekiq-cron) and NAMES a
+# recipient (config.health_report_to, else ENV["STUDIO_HEALTH_REPORT_TO"]). The
+# engine registers no schedule of its own, and with no recipient the job returns
+# before it reads a row.
+#
+# THE WINDOW IS 07:00 TO 07:00 ON THE APP'S WALL CLOCK, end excluded, copied from
+# mcritchie-studio's ContactFlaggedDigestJob. `24.hours.ago` would drop an hour
+# on the fall-back day (a 25-hour day) and report an hour twice on the
+# spring-forward one. Anchoring on the hour also makes the report a function of
+# the DAY, not the run: a run that lands late, or a retry, reports exactly the
+# window an on-time run would have, and a row at 07:00:00 belongs to one report.
+#
+# The config lives HERE rather than in lib/studio.rb so the unit suite loads it
+# with the rules it governs; `Studio.configure` sets it like any other setting.
+module Studio
+  # Who gets the report. A String (comma-separated is fine), an Array, or a
+  # callable returning either. nil or blank falls through to
+  # ENV["STUDIO_HEALTH_REPORT_TO"]; nobody there either means no email.
+  mattr_accessor :health_report_to, default: nil
+
+  # The wall clock the window is cut on, and the hour that opens it. Schedule
+  # the job at this hour in this zone; running it later reports the same day.
+  mattr_accessor :health_report_zone, default: "America/Denver"
+  mattr_accessor :health_report_hour, default: 7
+
+  # Where signups come from: a callable taking the window (a Range of times)
+  # and returning a relation, an Array, or an Integer count. The default reads
+  # the host's `User` by created_at, which is every consumer today; an app whose
+  # accounts live elsewhere points this at that model. nil omits the section.
+  mattr_accessor :health_report_signups, default: :default
+
+  # Contact-form submissions, OPTIONAL: nil (the default) omits the section,
+  # because the engine has no contact model and each app names its own, e.g.
+  #   config.health_report_contacts = ->(window) { ContactSubmission.where(created_at: window) }
+  mattr_accessor :health_report_contacts, default: nil
+
+  module HealthReport
+    ENV_KEY = "STUDIO_HEALTH_REPORT_TO"
+    LISTED = 10        # names shown under a count; the count is always whole
+    ERROR_GROUPS = 15  # distinct errors shown; the rest are counted as "more"
+
+    # One section of the report. `items` is at most LISTED labels; `count` is
+    # the true total. `failure` is set when the source raised: the report still
+    # sends, and says that this one part could not be read.
+    Section = Struct.new(:title, :count, :items, :failure, keyword_init: true) do
+      def failed? = !failure.nil?
+      # Rows counted but not listed. A count-only section lists none and owes no tail.
+      def more = items.empty? ? 0 : [count.to_i - items.size, 0].max
+    end
+
+    # One distinct error: its class, its message, how often, first and last.
+    ErrorGroup = Struct.new(:error_class, :message, :count, :first_seen, :last_seen, keyword_init: true)
+
+    Report = Struct.new(:app_name, :window, :signups, :errors, :error_groups, :error_kinds, :contacts,
+                        keyword_init: true) do
+      def sections = [signups, errors, contacts].compact
+
+      # Nothing happened and nothing failed: the email is the all-clear line.
+      def quiet? = sections.all? { |s| !s.failed? && s.count.to_i.zero? }
+
+      def subject
+        return "#{app_name} health: all clear" if quiet?
+
+        parts = sections.reject { |s| s.count.to_i.zero? && !s.failed? }.map do |s|
+          s.failed? ? "#{s.title.downcase} unavailable" : HealthReport.pluralize(s.count, s.title.downcase.chomp("s"))
+        end
+        "#{app_name} health: #{parts.join(', ')}"
+      end
+
+      # A time on the report's own clock: "Oct 13, 6:42 AM".
+      def stamp(time) = time ? time.in_time_zone(window.end.time_zone).strftime("%b %-d, %-l:%M %p") : "unknown"
+
+      # "Oct 12, 7:00 AM to Oct 13, 7:00 AM MDT"
+      def window_label
+        from, to = window.begin, window.end
+        "#{from.strftime('%b %-d, %-l:%M %p')} to #{to.strftime('%b %-d, %-l:%M %p %Z')}"
+      end
+    end
+
+    module_function
+
+    def window(now = Time.now, zone: Studio.health_report_zone, hour: Studio.health_report_hour)
+      finish = now.in_time_zone(zone).change(hour: hour)
+      finish -= 1.day if finish > now
+      (finish - 1.day)...finish
+    end
+
+    # The window that ENDS at `finish` (the job passes this through the outbox,
+    # so a retry re-reads the same day rather than the day it happens to run on).
+    def window_ending(finish, zone: Studio.health_report_zone)
+      finish = finish.in_time_zone(zone)
+      (finish - 1.day)...finish
+    end
+
+    def recipients
+      configured = Studio.health_report_to
+      configured = configured.call if configured.respond_to?(:call)
+      list = split(configured)
+      list = split(ENV.fetch(ENV_KEY, nil)) if list.empty?
+      list
+    end
+
+    def split(value)
+      Array(value).flat_map { |v| v.to_s.split(",") }.map(&:strip).reject(&:empty?)
+    end
+
+    # ErrorLog.capture! stores "#<Class: message>"; a row written by hand may
+    # carry only a message. Returns [class, message].
+    def error_name(text)
+      return ["Error", "(no message)"] if text.blank?
+
+      match = /\A#<([A-Z][\w:]*): (.*)>\z/m.match(text.to_s)
+      match ? [match[1], match[2]] : ["Error", text.to_s]
+    end
+
+    def pluralize(count, noun)
+      "#{count} #{count == 1 ? noun : "#{noun}s"}"
+    end
+
+    # ---- gathering (needs the host's database) ------------------------------
+
+    def build(window: self.window(Time.now))
+      Report.new(
+        app_name: Studio.app_name,
+        window: window,
+        signups: section("Signups", Studio.health_report_signups, window),
+        contacts: section("Contact messages", Studio.health_report_contacts, window),
+        **errors(window)
+      )
+    end
+
+    def section(title, source, window)
+      source = default_signups_source if source == :default
+      return nil if source.nil?
+
+      collect(title, source.call(window))
+    rescue StandardError => e
+      capture(e)
+      Section.new(title: title, count: 0, items: [], failure: e.class.name)
+    end
+
+    # The host's `User`, newest first, when it has a created_at; otherwise no
+    # section at all, rather than a "0 signups" line that is not true.
+    def default_signups_source
+      return nil unless defined?(::User) && ::User.respond_to?(:column_names) && ::User.column_names.include?("created_at")
+
+      ->(window) { ::User.where(created_at: window).order(created_at: :desc) }
+    end
+
+    def collect(title, result)
+      case result
+      when nil then Section.new(title: title, count: 0, items: [])
+      when Integer then Section.new(title: title, count: result, items: [])
+      else
+        count = result.respond_to?(:count) ? result.count : result.size
+        rows = result.respond_to?(:limit) ? result.limit(LISTED).to_a : Array(result).first(LISTED)
+        Section.new(title: title, count: count, items: rows.map { |r| label(r) })
+      end
+    end
+
+    # A short, human name for a row: its own health_report_label if it has
+    # one, else a name, then an email, then "Model #id".
+    def label(record)
+      return record.to_s if record.is_a?(String)
+      return record.health_report_label.to_s if record.respond_to?(:health_report_label)
+
+      name = %i[display_name name].lazy.filter_map { |m| record.public_send(m).presence if record.respond_to?(m) }.first
+      email = record.public_send(:email).presence if record.respond_to?(:email)
+      return "#{name} <#{email}>" if name && email && name != email
+      return (name || email).to_s if name || email
+
+      "#{record.class.name} ##{record.try(:id)}"
+    rescue StandardError
+      "#{record.class.name} ##{record.try(:id)}"
+    end
+
+    # Grouped in SQL: a bad day can hold thousands of rows. The key is the
+    # stored "#<Class: message>", which is the class AND the message.
+    def errors(window)
+      empty = { errors: Section.new(title: "Errors", count: 0, items: []), error_groups: [], error_kinds: 0 }
+      return empty unless defined?(::ErrorLog) && ::ErrorLog.table_exists?
+
+      key = "COALESCE(#{::ErrorLog.connection.quote_column_name('inspect')}, message)"
+      scope = ::ErrorLog.where(created_at: window)
+      total = scope.count
+      return empty if total.zero?
+
+      kinds = scope.distinct.count(Arel.sql(key))
+      created = ::ErrorLog.type_for_attribute("created_at")
+      groups = scope.group(Arel.sql(key)).order(Arel.sql("COUNT(*) DESC, MAX(created_at) DESC")).limit(ERROR_GROUPS)
+                    .pluck(Arel.sql(key), Arel.sql("COUNT(*)"), Arel.sql("MIN(created_at)"), Arel.sql("MAX(created_at)"))
+                    .map do |text, count, first, last|
+        klass, message = error_name(text)
+        ErrorGroup.new(error_class: klass, message: message.to_s.truncate(300), count: count.to_i,
+                       first_seen: created.deserialize(first), last_seen: created.deserialize(last))
+      end
+      { errors: Section.new(title: "Errors", count: total, items: []), error_groups: groups, error_kinds: kinds }
+    rescue StandardError => e
+      capture(e)
+      { errors: Section.new(title: "Errors", count: 0, items: [], failure: e.class.name), error_groups: [], error_kinds: 0 }
+    end
+
+    def capture(error)
+      ::ErrorLog.capture!(error) if defined?(::ErrorLog)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.104.0"
+  VERSION = "0.105.0"
 end

data/lib/studio.rb

@@ -38,6 +38,7 @@ require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
 require "studio/newsletter"
+require "studio/health_report"
 require "studio/username_generator"
 require "studio/public_user"
 require "studio/name_parts"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.104.0
+  version: 0.105.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-11 00:00:00.000000000 Z
+date: 2026-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -474,7 +474,9 @@ files:
 - app/javascript/studio/vendor/stimulus.js
 - app/jobs/error_log_cleanup_job.rb
 - app/jobs/studio/email_delivery_job.rb
+- app/jobs/studio/health_report_job.rb
 - app/mailers/application_mailer.rb
+- app/mailers/studio/health_report_mailer.rb
 - app/mailers/studio/newsletter_mailer.rb
 - app/mailers/studio/profile_mailer.rb
 - app/mailers/user_mailer.rb
@@ -574,6 +576,8 @@ files:
 - app/views/studio/emails/show.html.erb
 - app/views/studio/fields/_date_of_birth.html.erb
 - app/views/studio/geo_settings/edit.html.erb
+- app/views/studio/health_report_mailer/daily.html.erb
+- app/views/studio/health_report_mailer/daily.text.erb
 - app/views/studio/knowledge_docs/_access_chips.html.erb
 - app/views/studio/knowledge_docs/_browser.html.erb
 - app/views/studio/knowledge_docs/_chip_styles.html.erb
@@ -733,6 +737,7 @@ files:
 - lib/studio/geo.rb
 - lib/studio/geo/countries.rb
 - lib/studio/geo/lookup.rb
+- lib/studio/health_report.rb
 - lib/studio/hold_button.rb
 - lib/studio/host_schema.rb
 - lib/studio/image_cache.rb