studio-engine 0.92.0 → 0.92.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 823f5e3df6cb271556188c72d4322a968b5cf63f8635c37b70fc71a56ad93fe3
-  data.tar.gz: ab908a4f8a0c9beae55f1844bbc2957b43c7bc33f1643c3ae083473ae68473d7
+  metadata.gz: 33eb1f55bd158e9d6c588739db65fbef1a5ba8b707b1e0c0469b539d3e6643fa
+  data.tar.gz: f3c5845a77976e33edc87e04da3de0e08fd890203f901352a3b419ee3f58f489
 SHA512:
-  metadata.gz: 0f66ecc8ebf3c1b6318e88e4b069cb2bc4b19452db48035558eea01cb5cf163fcf126435dfdc8b74d5e837bcd65535a10b99157e9cec1fa286f2452739f420ba
-  data.tar.gz: a3ae0c907619c2ba686bdb3a35a82883bd1a15e010191969e52c102414e37b57982a19de4cba20ccf20866638d6814983ad06e6fe0f7027ad8bad925caba6c06
+  metadata.gz: ec17e35ab084a92080f6bc9fa9565cd5ca6a2f71c8f9f75311ef32f1955c140d9391ed34fa78adcffa8fb84892e043074cf5d7cd89b9f09418edf4af72007b9c
+  data.tar.gz: 411eed22d765f4fa318805debbd117353b38f6d518d69b411673bca76d73375812d9f0baa36f69fa1ab25f55976302fe8d37f9ffe5231a4fbd9bfc4002e1b5e8

data/CHANGELOG.md

@@ -4,6 +4,29 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.92.1 — 2026-10-07
+
+### Added
+
+- **The engine owns `error_logs`, `theme_settings` and `image_caches`.** Three
+  migrations (`ensure_error_logs_table`, `ensure_theme_settings_table`,
+  `ensure_image_caches_table`) create each table when it is absent and, on an app
+  that already has it, add only the engine columns it lacks, as nullable columns;
+  nothing is altered or dropped and no index is added. Adopt with
+  `bin/rails studio_engine:install:migrations` and `bin/rails db:migrate`; the
+  release's lock bump does both. Hosts no longer copy these tables from
+  `docs/NEW_APP_SETUP.md`.
+- **A boot check names a missing engine column** (`Studio::HostSchema`). It
+  raises `Studio::HostSchemaError` in development and test, and logs (and reports
+  to Sentry) in production; `Studio.host_schema_check = :raise | :log | false`
+  overrides. Extra host columns are never reported, and rake tasks skip it.
+
+### Fixed
+
+- **A theme save no longer raises on apps without `theme_settings.slug`**
+  (Cyvasse, McRitchie Industries and Moms App): `ensure_theme_settings_table`
+  adds the column `ThemeSetting` writes on every save.
+
 ## 0.92.0 — 2026-10-06
 
 ### Added

data/db/migrate/20261006120001_ensure_error_logs_table.rb

@@ -0,0 +1,66 @@
+# The engine owns the shape of `error_logs`: ErrorLog and the /error_logs pages
+# write and read the columns below on every host.
+#
+# A host that predates this migration already has the table, built by its own
+# migration from docs/NEW_APP_SETUP.md, and the hosts disagree on details (turf
+# has NOT NULL on message, an index on created_at and no unique index on slug).
+# So the migration is a baseline, not a rebuild:
+#
+#   - no table: create it in the engine's shape, with its indexes;
+#   - a table: add any engine column it lacks, as a plain nullable column, and
+#     touch nothing else. No column is changed or dropped, no constraint is
+#     tightened and no index is added, because a host's indexes and NOT NULLs
+#     are its own, and a unique index built during a release-phase migrate can
+#     fail on existing rows or lock a large table.
+#
+# On every consumer that existed when this shipped, the second branch adds
+# nothing. Studio::HostSchema checks the same columns at boot.
+class EnsureErrorLogsTable < ActiveRecord::Migration[7.2]
+  def up
+    unless table_exists?(:error_logs)
+      create_table :error_logs do |t|
+        t.string :slug
+        t.text :message
+        t.text :inspect
+        t.text :backtrace
+        t.string :target_type
+        t.bigint :target_id
+        t.string :target_name
+        t.string :parent_type
+        t.bigint :parent_id
+        t.string :parent_name
+
+        t.timestamps
+      end
+
+      add_index :error_logs, :slug, unique: true
+      add_index :error_logs, %i[target_type target_id]
+      add_index :error_logs, %i[parent_type parent_id]
+      return
+    end
+
+    add_column :error_logs, :slug,        :string,   if_not_exists: true
+    add_column :error_logs, :message,     :text,     if_not_exists: true
+    add_column :error_logs, :inspect,     :text,     if_not_exists: true
+    add_column :error_logs, :backtrace,   :text,     if_not_exists: true
+    add_column :error_logs, :target_type, :string,   if_not_exists: true
+    add_column :error_logs, :target_id,   :bigint,   if_not_exists: true
+    add_column :error_logs, :target_name, :string,   if_not_exists: true
+    add_column :error_logs, :parent_type, :string,   if_not_exists: true
+    add_column :error_logs, :parent_id,   :bigint,   if_not_exists: true
+    add_column :error_logs, :parent_name, :string,   if_not_exists: true
+    add_column :error_logs, :created_at,  :datetime, if_not_exists: true
+    add_column :error_logs, :updated_at,  :datetime, if_not_exists: true
+  end
+
+  # The migration records nothing about whether it created the table or found
+  # it, so a down cannot tell the engine's table from the host's own, and
+  # dropping it would destroy the host's error history. It refuses instead.
+  def down
+    return unless table_exists?(:error_logs)
+
+    raise ActiveRecord::IrreversibleMigration,
+          "EnsureErrorLogsTable cannot tell whether it created error_logs or found the host's own; " \
+          "drop the table by hand if this app truly owns none of its rows."
+  end
+end

data/db/migrate/20261006120002_ensure_theme_settings_table.rb

@@ -0,0 +1,63 @@
+# The engine owns the shape of `theme_settings`: ThemeSetting and /admin/theme
+# write the columns below on every host.
+#
+# `slug` is the column this migration exists for. ThemeSetting includes
+# Sluggable, whose before_save writes `slug` on every save, and the setup doc's
+# hand-copied migration omitted it, so a theme save raises on any host built
+# from that doc (cyvasse, mcritchie-industries and moms-app when this shipped).
+# The slug is "theme-<app_name>", derived on save; existing rows keep a NULL
+# slug until their next save, and nothing looks a theme up by slug.
+#
+# A baseline, not a rebuild:
+#
+#   - no table: create it in the engine's shape, with its unique app_name index;
+#   - a table: add any engine column it lacks, as a plain nullable column, and
+#     touch nothing else. No column is changed or dropped, no constraint is
+#     tightened and no index is added.
+#
+# Studio::HostSchema checks the same columns at boot.
+class EnsureThemeSettingsTable < ActiveRecord::Migration[7.2]
+  def up
+    unless table_exists?(:theme_settings)
+      create_table :theme_settings do |t|
+        t.string :app_name, null: false
+        t.string :slug
+        t.string :primary
+        t.string :dark
+        t.string :light
+        t.string :accent1
+        t.string :accent2
+        t.string :warning
+        t.string :danger
+
+        t.timestamps
+      end
+
+      add_index :theme_settings, :app_name, unique: true
+      return
+    end
+
+    add_column :theme_settings, :app_name,   :string,   if_not_exists: true
+    add_column :theme_settings, :slug,       :string,   if_not_exists: true
+    add_column :theme_settings, :primary,    :string,   if_not_exists: true
+    add_column :theme_settings, :dark,       :string,   if_not_exists: true
+    add_column :theme_settings, :light,      :string,   if_not_exists: true
+    add_column :theme_settings, :accent1,    :string,   if_not_exists: true
+    add_column :theme_settings, :accent2,    :string,   if_not_exists: true
+    add_column :theme_settings, :warning,    :string,   if_not_exists: true
+    add_column :theme_settings, :danger,     :string,   if_not_exists: true
+    add_column :theme_settings, :created_at, :datetime, if_not_exists: true
+    add_column :theme_settings, :updated_at, :datetime, if_not_exists: true
+  end
+
+  # The migration records nothing about whether it created the table or found
+  # it, so a down cannot tell the engine's table from the host's own theme. It
+  # refuses instead.
+  def down
+    return unless table_exists?(:theme_settings)
+
+    raise ActiveRecord::IrreversibleMigration,
+          "EnsureThemeSettingsTable cannot tell whether it created theme_settings or found the host's own; " \
+          "drop the table or the slug column by hand if this app truly owns neither."
+  end
+end

data/db/migrate/20261006120003_ensure_image_caches_table.rb

@@ -0,0 +1,63 @@
+# The engine owns the shape of `image_caches`: ImageCache, Studio::ImageCache
+# and Studio::EmailCatalog write the columns below on every host.
+#
+# Hosts that cache images already have the table (from their own migration);
+# hosts that never did (cyvasse and moms-app when this shipped) get it here, so
+# the email banner and logo uploads work on every app.
+#
+# A baseline, not a rebuild:
+#
+#   - no table: create it in the engine's shape, with the owner nullable (an
+#     app-global image has no owner) and the indexes that back ImageCache's
+#     uniqueness validations;
+#   - a table: add any engine column it lacks, as a plain nullable column, and
+#     touch nothing else. No column is changed or dropped, no constraint is
+#     tightened and no index is added.
+#
+# Studio::HostSchema checks the same columns at boot.
+class EnsureImageCachesTable < ActiveRecord::Migration[7.2]
+  def up
+    unless table_exists?(:image_caches)
+      create_table :image_caches do |t|
+        t.string :owner_type
+        t.bigint :owner_id
+        t.string :purpose, null: false
+        t.string :variant, null: false
+        t.string :s3_key, null: false
+        t.string :source_url
+        t.string :content_type
+        t.integer :bytes
+
+        t.timestamps
+      end
+
+      add_index :image_caches, %i[owner_type owner_id], name: "index_image_caches_on_owner"
+      add_index :image_caches, :s3_key, unique: true
+      add_index :image_caches, %i[owner_type owner_id purpose variant], unique: true,
+                name: "idx_image_caches_owner_purpose_variant"
+      return
+    end
+
+    add_column :image_caches, :owner_type,   :string,   if_not_exists: true
+    add_column :image_caches, :owner_id,     :bigint,   if_not_exists: true
+    add_column :image_caches, :purpose,      :string,   if_not_exists: true
+    add_column :image_caches, :variant,      :string,   if_not_exists: true
+    add_column :image_caches, :s3_key,       :string,   if_not_exists: true
+    add_column :image_caches, :source_url,   :string,   if_not_exists: true
+    add_column :image_caches, :content_type, :string,   if_not_exists: true
+    add_column :image_caches, :bytes,        :integer,  if_not_exists: true
+    add_column :image_caches, :created_at,   :datetime, if_not_exists: true
+    add_column :image_caches, :updated_at,   :datetime, if_not_exists: true
+  end
+
+  # The migration records nothing about whether it created the table or found
+  # it, so a down cannot tell the engine's table from the host's own cache. It
+  # refuses instead.
+  def down
+    return unless table_exists?(:image_caches)
+
+    raise ActiveRecord::IrreversibleMigration,
+          "EnsureImageCachesTable cannot tell whether it created image_caches or found the host's own; " \
+          "drop the table by hand if this app truly owns none of its rows."
+  end
+end

data/lib/studio/engine.rb

@@ -298,6 +298,13 @@ module Studio
          ::User.ancestors.include?(::ActiveRecord::Base)
         Studio.validate_user_contract!(::User)
       end
+
+      # The host's error_logs, theme_settings and image_caches carry every
+      # column the engine's models write (Studio::HostSchema). Skipped in a
+      # rake task, which boots to migrate rather than to serve.
+      if Studio.active_record? && !Studio::HostSchema.inside_rake_task?
+        Studio::HostSchema.check!
+      end
     end
 
   end

data/lib/studio/host_schema.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Studio
+  # The columns the engine's models write on tables the HOST holds: error_logs,
+  # theme_settings and image_caches. The engine's Ensure*Table migrations create
+  # or complete those tables; this checks, at boot, that the host has actually
+  # run them, so a missing column is named at startup instead of surfacing later
+  # as a 500 on the first save that writes it (a theme save on a host without
+  # theme_settings.slug was the case that prompted it).
+  #
+  # The check is one-directional: it looks only for REQUIRED columns that are
+  # absent. Extra columns, extra indexes, a different NOT NULL or a different
+  # type are the host's business and never reported.
+  #
+  # HOW LOUD, per environment (Studio.host_schema_check):
+  #
+  #   :raise  development and test, by default. A developer or a CI suite sees
+  #           Studio::HostSchemaError at boot with the table, the column and the
+  #           two commands that fix it.
+  #   :log    every other environment (production, and QA, which runs as
+  #           production), by default. Rails.logger.error plus a Sentry message
+  #           when the host loads sentry-ruby. It never raises there, for two
+  #           reasons. Heroku's release phase boots the app to run db:migrate,
+  #           the very command that adds the column, so a raise at boot would
+  #           make the fix undeployable. And a missing column breaks the one
+  #           surface that writes it (an admin theme save, an email banner
+  #           upload); taking every page down to report it trades a small
+  #           outage for a total one.
+  #   false   off.
+  #
+  # The check never runs inside a rake task (db:migrate, install:migrations,
+  # assets:precompile): those boot the app precisely to change or ignore the
+  # schema, and a report there would be wrong by the time the task finishes. It
+  # also stays quiet when the database cannot be reached; it has nothing to say
+  # about a schema it cannot read.
+  module HostSchema
+    REQUIRED_COLUMNS = {
+      "error_logs" => %w[
+        slug message inspect backtrace
+        target_type target_id target_name
+        parent_type parent_id parent_name
+        created_at updated_at
+      ].freeze,
+      "theme_settings" => %w[
+        app_name slug primary dark light accent1 accent2 warning danger
+        created_at updated_at
+      ].freeze,
+      "image_caches" => %w[
+        owner_type owner_id purpose variant s3_key source_url content_type bytes
+        created_at updated_at
+      ].freeze
+    }.freeze
+
+    MODES = [:raise, :log, false].freeze
+
+    module_function
+
+    # { "table" => ["missing", "columns"] } for every required table that is
+    # absent (all its columns listed) or short of a column. Empty when the host
+    # satisfies the contract.
+    def missing_columns(connection)
+      REQUIRED_COLUMNS.each_with_object({}) do |(table, required), missing|
+        present = connection.table_exists?(table) ? connection.columns(table).map(&:name) : []
+        absent = required - present
+        missing[table] = absent if absent.any?
+      end
+    end
+
+    def message(missing)
+      lines = missing.map do |table, columns|
+        if columns == REQUIRED_COLUMNS[table]
+          "  #{table}: the table is missing"
+        else
+          "  #{table}: missing #{columns.join(', ')}"
+        end
+      end
+
+      <<~MSG
+        studio-engine: this app's database is missing columns the engine's models write.
+
+        #{lines.join("\n")}
+
+        Install and run the engine's migrations (they create a missing table, add
+        a missing column and change nothing else):
+
+          bin/rails studio_engine:install:migrations
+          bin/rails db:migrate
+
+        Set Studio.host_schema_check = false in config/initializers/studio.rb to
+        silence this check.
+      MSG
+    end
+
+    # The mode in force: the host's Studio.host_schema_check, or :raise in
+    # development and test and :log everywhere else.
+    def mode(setting: Studio.host_schema_check, env: Rails.env)
+      return setting unless setting.nil?
+
+      env.development? || env.test? ? :raise : :log
+    end
+
+    # The boot hook. Returns the missing-columns hash it found (empty when the
+    # host is whole or the check was skipped) and acts on it per `mode`.
+    def check!(connection: nil, mode: self.mode, logger: Rails.logger)
+      return {} if mode == false
+
+      missing =
+        begin
+          if connection
+            missing_columns(connection)
+          else
+            ActiveRecord::Base.connection_pool.with_connection { |conn| missing_columns(conn) }
+          end
+        rescue ActiveRecord::ActiveRecordError => e
+          logger&.debug("[studio-engine] host schema check skipped: #{e.class}: #{e.message}")
+          return {}
+        end
+      return missing if missing.empty?
+
+      text = message(missing)
+      raise Studio::HostSchemaError, text if mode == :raise
+
+      logger&.error("[studio-engine] #{text}")
+      report_to_sentry(text)
+      missing
+    end
+
+    # True while a rake task is running: the app booted to migrate, install or
+    # precompile, not to serve.
+    def inside_rake_task?
+      defined?(::Rake) && ::Rake.respond_to?(:application) &&
+        ::Rake.application.respond_to?(:top_level_tasks) &&
+        ::Rake.application.top_level_tasks.any?
+    end
+
+    def report_to_sentry(text)
+      return unless defined?(::Sentry) && ::Sentry.respond_to?(:capture_message)
+
+      ::Sentry.capture_message(text, level: :error)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.92.0"
+  VERSION = "0.92.1"
 end

data/lib/studio.rb

@@ -42,6 +42,7 @@ require "studio/public_user"
 require "studio/name_parts"
 require "studio/s3"
 require "studio/image_cache"
+require "studio/host_schema"
 require "studio/link_token"
 require "studio/link_resolution"
 require "studio/session_fingerprint"
@@ -1060,6 +1061,11 @@ module Studio
   # that intentionally break the contract).
   mattr_accessor :validate_user_contract, default: true
 
+  # How loudly the boot check reports a host database missing a column the
+  # engine's models write (Studio::HostSchema): :raise, :log, or false for off.
+  # nil, the default, means :raise in development and test and :log elsewhere.
+  mattr_accessor :host_schema_check, default: nil
+
   # Does the host load ActiveRecord at all? True for every app that requires
   # `rails/all` or `active_record/railtie` (all the engine's database-backed
   # consumers); false for a FOOTER-ONLY consumer, an app with no database that
@@ -1091,6 +1097,7 @@ module Studio
   PASSWORD_USER_INSTANCE_METHODS = %i[authenticate].freeze
 
   class UserContractError < StandardError; end
+  class HostSchemaError < StandardError; end
 
   def self.configure
     yield self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.92.0
+  version: 0.92.1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -640,6 +640,9 @@ files:
 - db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb
 - db/migrate/20260930120000_create_studio_site_identities.rb
 - db/migrate/20261005120000_create_studio_survey_responses.rb
+- db/migrate/20261006120001_ensure_error_logs_table.rb
+- db/migrate/20261006120002_ensure_theme_settings_table.rb
+- db/migrate/20261006120003_ensure_image_caches_table.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb
@@ -658,6 +661,7 @@ files:
 - lib/studio/geo.rb
 - lib/studio/geo/countries.rb
 - lib/studio/geo/lookup.rb
+- lib/studio/host_schema.rb
 - lib/studio/image_cache.rb
 - lib/studio/ip_locations.rb
 - lib/studio/js_identifier.rb