studio-engine 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d4a633071c04010dadfb92d3beef1a7e075a90c94e55ab5761a03a114f48f40
-  data.tar.gz: fc17d48b30cfcbde79e4c3bdc5bf618789a7765dbc359a134b28800cc772429e
+  metadata.gz: 61bf440c6e7573b35e8d7a680851d2535b37b08690f36c0f8c42402a8a1fcc64
+  data.tar.gz: e79e46ab92bcd13bf5655526c199c1d7a1b17610d815dc240a5af7250455b9e1
 SHA512:
-  metadata.gz: e32e14a996202c61dd230a4084927539618341c0343bbafad1066280394da6d84976222a5621000157d6e84df83452c6a5f234f36ca11e18c408e340757a0b49
-  data.tar.gz: 8592453e2efdbad7c3df75bfb13274a6abfa080f9de9e6188a70d90e935d2dfa1446c788f15d55eab467207bcfa9cef129bf9b0abf3fbb001e846a11a6c31f3f
+  metadata.gz: 64d04f5527318728c090ad318d9d5f652a12b1e8eadc6f665eccd4a0c4a0aadff6d1c7dfaecdc5c2a438c08b648a34ba78f1869dc8df1b80c6d1ccc9728f457d
+  data.tar.gz: bba2fac4175596d6448dcc9611c9c4740f021fcfb467c09986a20d0d506e4c37cc933257ac6e0d23deb262a0fcf98baa3fe3bce104a8985e85562451ddab406f

data/CHANGELOG.md

@@ -4,6 +4,19 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Added
+- **Model-page protocol (v1)** — a reusable, admin-only per-record inspector,
+  drawn into every consuming app via `Studio.routes`:
+  `/models/:model/:id` renders one record as pretty JSON plus a copy/paste
+  rails-console command to reload it, and `/models/:model/random` bounces to a
+  random record of that model. New `Studio::ModelsController` +
+  `app/views/studio/models/show.html.erb` (theme-token styled, reuses the
+  `components/copy_button` partial). The protocol object `Studio::ModelPage`
+  ships an **empty registry** — no model is reachable until a host opts in with
+  `Studio::ModelPage.register("release", Release, lookup: :slug)` in an
+  initializer (mirrors the admin-models host-registry pattern; the engine never
+  constantizes host models by name). Gated with `require_admin`.
+
 ## 0.11.0 — 2026-06-24
 
 ### Changed

data/app/controllers/studio/models_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Studio
+  # Serves the model-page protocol (see Studio::ModelPage). Admin-only: raw record
+  # JSON can carry internal fields, so this is an operator/debug surface, not a
+  # public one. require_authentication is inherited from the host app's
+  # ApplicationController (Studio::ErrorHandling); require_admin gates on top.
+  class ModelsController < ApplicationController
+    before_action :require_admin
+    before_action :load_page
+
+    # GET /models/:model/:id — one record as JSON + a copy/paste console command.
+    def show
+      head :not_found unless @page.record
+    end
+
+    # GET /models/:model/random — bounce to a random record's page (fresh sample).
+    def random
+      record = @page.random_record
+      return head(:not_found) unless record
+
+      redirect_to studio_model_path(@page.model_key, @page.identifier_for(record))
+    end
+
+    private
+
+    def load_page
+      @page = Studio::ModelPage.new(params[:model], params[:id])
+    rescue Studio::ModelPage::UnknownModel
+      head :not_found
+    end
+  end
+end

data/app/models/studio/model_page.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Studio
+  # The model-page protocol (v1).
+  #
+  # A reusable, per-record inspector. Given a whitelisted model key and a record
+  # identifier, it produces the two things a v1 model page renders — the record
+  # as pretty-printed JSON and a copy/paste rails-console command that reloads it
+  # — plus the lookup a "random sample" jump needs. The controller and view stay
+  # thin; enabling a model is a one-line registration.
+  #
+  # The engine ships an EMPTY registry: no model is reachable until a host app
+  # opts in. Each app registers its own models in an initializer, e.g.
+  #
+  #   Studio::ModelPage.register("release", Release, lookup: :slug)
+  #
+  # This mirrors the admin-models pattern — the host hands the engine live class
+  # references; the engine never constantizes host models by name. An unknown key
+  # raises UnknownModel, which the controller renders as 404.
+  class ModelPage
+    class UnknownModel < StandardError; end
+
+    Entry = Struct.new(:model, :lookup, keyword_init: true)
+
+    class << self
+      # Enable a model. `model` is the live AR class; `lookup` is the column its
+      # page URL is keyed on (usually its to_param backing). Returns the key.
+      def register(key, model, lookup: :slug)
+        registry[key.to_s] = Entry.new(model: model, lookup: lookup.to_sym)
+        key.to_s
+      end
+
+      def registered?(key)
+        registry.key?(key.to_s)
+      end
+
+      def keys
+        registry.keys
+      end
+
+      # Clears the registry — for tests and boot-time re-registration.
+      def reset!
+        registry.clear
+      end
+
+      def entry(key)
+        registry.fetch(key.to_s) { raise UnknownModel, "unknown model: #{key.inspect}" }
+      end
+
+      private
+
+      def registry
+        @registry ||= {}
+      end
+    end
+
+    attr_reader :model_key, :identifier
+
+    # identifier is the record's lookup-key value from the URL (nil for /random,
+    # which addresses the model as a whole rather than one record).
+    def initialize(model_key, identifier = nil)
+      @entry = self.class.entry(model_key)
+      @model_key = model_key.to_s
+      @identifier = identifier
+    end
+
+    def model
+      @entry.model
+    end
+
+    def lookup_key
+      @entry.lookup
+    end
+
+    # The record this page addresses (nil when the identifier matches nothing).
+    def record
+      return @record if defined?(@record)
+
+      @record = model.find_by(lookup_key => identifier)
+    end
+
+    # A random record of this model, for the "random sample" jump (nil if empty).
+    def random_record
+      model.order(::Arel.sql("RANDOM()")).first
+    end
+
+    # The copy/paste rails-console command that reloads this record, e.g.
+    #   Release.find_by(slug: "rel-20260707-a1b2c3")
+    def console_command
+      %(#{model.name}.find_by(#{lookup_key}: #{identifier.inspect}))
+    end
+
+    # The record serialized as pretty JSON — the page's primary payload.
+    def json
+      ::JSON.pretty_generate(record.as_json)
+    end
+
+    # The lookup-key value to route to for a given record (used by /random).
+    def identifier_for(record)
+      record.public_send(lookup_key)
+    end
+  end
+end

data/app/views/studio/models/show.html.erb

@@ -0,0 +1,32 @@
+<%# Model-page protocol (v1) — a uniform record inspector: the record as pretty
+    JSON plus a copy/paste rails-console command to reload it, with a jump to a
+    random sample record. Admin-only surface (Studio::ModelsController). The copy
+    button reuses the engine components/copy_button partial. %>
+<% model_label = @page.model.model_name.human %>
+<% content_for(:title, "#{model_label} - Model") %>
+
+<div class="max-w-7xl mx-auto px-4 py-8 space-y-6">
+  <header class="flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
+    <div>
+      <p class="text-xs text-muted uppercase tracking-wide font-semibold">Model</p>
+      <h1 class="text-heading text-2xl font-bold mt-1"><%= model_label %></h1>
+      <p class="text-muted text-sm mt-1 font-mono"><%= @page.identifier %></p>
+    </div>
+    <%= link_to "🎲 Random sample", studio_model_random_path(@page.model_key), class: "btn btn-outline" %>
+  </header>
+
+  <%# The copy/paste line to reload this record in rails console. %>
+  <section class="card p-4 space-y-2">
+    <p class="text-xs text-muted uppercase tracking-wide font-semibold">Rails console</p>
+    <%= render "components/copy_button", text: @page.console_command %>
+  </section>
+
+  <%# The record serialized as pretty JSON — the protocol's primary payload. %>
+  <section class="card overflow-hidden">
+    <div class="flex items-center justify-between px-4 py-2 bg-surface-alt border-b border-subtle">
+      <p class="text-xs text-muted uppercase tracking-wide font-semibold">JSON</p>
+      <span class="font-mono text-xs text-muted"><%= @page.model.name %></span>
+    </div>
+    <pre class="overflow-x-auto px-4 py-3 text-xs font-mono text-heading leading-relaxed bg-inset"><%= @page.json %></pre>
+  </section>
+</div>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/studio.rb

@@ -309,6 +309,16 @@ module Studio
       get   "admin/email_images",          to: "studio/email_images#index",  as: :admin_email_images
       patch "admin/email_images/:variant", to: "studio/email_images#update",  as: :admin_email_image,
             constraints: { variant: /[a-z_]+/ }
+
+      # Model-page protocol (v1) — a reusable per-record inspector. Drawn into
+      # every consuming app: /models/:model/:id renders one record as pretty JSON
+      # plus a copy/paste rails-console command; /models/:model/random bounces to
+      # a random record of that model. Admin-only (Studio::ModelsController).
+      # Ships an EMPTY registry — a host enables a model in an initializer with
+      # `Studio::ModelPage.register("release", Release, lookup: :slug)`. `random`
+      # is drawn BEFORE `:id` so it is not captured as a record identifier.
+      get "models/:model/random", to: "studio/models#random", as: :studio_model_random
+      get "models/:model/:id",    to: "studio/models#show",   as: :studio_model
     end
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Alex McRitchie
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -187,6 +188,7 @@ files:
 - app/controllers/studio/email_images_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
+- app/controllers/studio/models_controller.rb
 - app/controllers/theme_settings_controller.rb
 - app/helpers/studio/admin_models_table_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
@@ -204,6 +206,7 @@ files:
 - app/models/studio/email_delivery.rb
 - app/models/studio/enumeral.rb
 - app/models/studio/link.rb
+- app/models/studio/model_page.rb
 - app/models/theme_setting.rb
 - app/services/google_oauth_validator.rb
 - app/services/magic_link.rb
@@ -258,6 +261,7 @@ files:
 - app/views/studio/modals/blocks/_processing_card.html.erb
 - app/views/studio/modals/blocks/_progress_countdown.html.erb
 - app/views/studio/modals/blocks/_success_card.html.erb
+- app/views/studio/models/show.html.erb
 - app/views/theme_settings/edit.html.erb
 - app/views/user_mailer/magic_link.html.erb
 - app/views/user_mailer/magic_link.text.erb
@@ -293,6 +297,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
@@ -307,7 +312,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Shared Rails engine providing auth, SSO, error logging, theming, and S3-backed
   image caching