studio-engine 0.32.3 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e56dfd4be2d6f429f329626c4aebb8b22aa9e0069cfdf8905a02fab4bc47ab4c
-  data.tar.gz: 71b6a6d3dafa57d3b25e9cb791049ae9b4a975efa7d14b08b961492b2b870d6f
+  metadata.gz: 8c692fc135af1ba83c08b27398c875bc547ae07bbcc492540ffd83250fccf680
+  data.tar.gz: 891c561fe2bef1386137af4fbbc22547f38613efe8bd373bf6ec31894086feef
 SHA512:
-  metadata.gz: ea74d63cf741530df52e0fbe490a3fe48817845235f12aa911e094d67fe6012e3b9f1d139f95d8f5240d467fa079a2746f6a3985c256a3daee948136752e3c9c
-  data.tar.gz: 75146aa7893ca074ada0c58b5ecfb20641615432c63090d3d8bd39bd0b6f6e480a6d7e558bbf45ac8003144a6fd224222fd7eeaac297571b522e255e43343472
+  metadata.gz: 9cb8bb03d5adeec99336b5fab4d28b29c57be8686ca2afef58932ce866c321fe44f6ab0123609e6845151f938ab28790685bda6b9b21815ef3a3594d6c589921
+  data.tar.gz: 2c3be4aadf2a88d7838dab26b27c4a22604268138bba818f0b82890774f7bc5b81424d53a645d3fcc5ebf59a8f10197a9b37bd9cd44246c988d8dca3dfd2cd62

data/CHANGELOG.md

@@ -2,6 +2,171 @@
 
 The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — `MAJOR.MINOR.PATCH`. Consumer Rails apps install the released RubyGems package with `gem "studio-engine", "~> 0.6"`; bumping the gem version and updating consumer lockfiles is a release.
 
+## 0.36.0 — 2026-08-10
+
+**The local-review link now signs the reviewer in as someone who can SEE the
+page.** `/_studio/local_review` — the local half of the task board's WAITING
+APPROVAL button — provisions the account before it mints, at the new
+`Studio.local_review_role` (default `"admin"`).
+
+The board hands this endpoint the operator's **production** email address. A
+fresh worktree database has never seen it, so consuming the link took
+`Studio::LinkConsumption#sign_up_new` and created the account at the default
+role, `viewer`. `require_admin` on the page under review then redirected it to
+`/`. The sign-in **succeeded** every time, which is what kept this quiet: the
+button worked, the token was valid, and the operator simply arrived on the home
+page having never seen the thing he was asked to review. A seeded admin
+(`alex@mcritchie.studio`) worked fine, so only his real address ever hit it.
+
+The endpoint now find-or-creates the reviewer and ensures the role BEFORE
+minting, so the consume takes `sign_in_existing` onto an account that already
+has rights. An existing account is promoted, never duplicated; an already-correct
+one is not rewritten.
+
+New public config:
+
+```ruby
+Studio.configure do |config|
+  config.local_review_role = "admin" # default; nil provisions without a role
+end
+```
+
+Set it to `nil` for an app whose review pages are not admin-gated — the account
+is still provisioned (that is what avoids `sign_up_new`), but its role is left
+to the host's own `configure_new_user`.
+
+**The endpoint also answers "who is sitting at this desk?" when the caller names
+nobody.** `?email=` is now optional, and an explicit one still wins. With none,
+the reviewer resolves to `Studio.local_review_email`, and failing that to the
+**first user already holding `Studio.local_review_role`, by id** (that query
+falls back to `"admin"` when the setting is `nil`):
+
+```ruby
+config.local_review_email = "someone@example.com" # nil (default) = derive
+```
+
+This exists so the board's WAITING APPROVAL CTA can be a **public, sign-in-free
+redirect**. Requiring a board session to click it is what broke one-click review
+in the first place; sending an email in that public URL would publish the
+operator's address. The local stack is the machine the reviewer is sitting at,
+so it is the right place to decide. A desk with nobody at that role mints
+nothing and says so, rather than guessing: the derive only ever picks someone
+who ALREADY holds the role, so it never promotes a stranger into it. (The
+`?email=` path does promote the account it is handed — that is the point of it.)
+
+**The floor is unchanged, and now asserted rather than assumed.** The endpoint
+grants a role, so both gates in front of it are tested directly: the
+developer-desk routes are drawn only outside production (proved by drawing
+`Studio.routes` into a throwaway route set under a production env), and a
+non-loopback request 404s **before** provisioning or minting anything.
+Provisioning is best-effort: a host whose `User` rejects the write gets a logged
+warning and a working link, never a 500.
+
+### Added
+
+- **`Studio.local_review_role`** — the role `/_studio/local_review` stamps on the
+  account it provisions before minting. Defaults to `"admin"`; `nil` provisions
+  the account without touching its role.
+- **`Studio.local_review_email`** — who the local-review mint signs in when the
+  caller sends no `?email=`. `nil` (the default) derives the first admin in this
+  database, by id.
+
+## 0.33.0 — 2026-08-10
+
+Two changes ship together in this release: local log files are now capped, and
+the pinned bars above the navbar become a composable **stack** that sits beside
+the navbar rather than inside it.
+
+**Local log files are now capped — 16 MB development, 8 MB test.** New
+`studio.logger` initializer. Nothing to install, run, or remember: it rides the
+gem, so every app, every future app, every worktree, and a freshly rebuilt Mac
+all get it by construction.
+
+Rails' own default is the reason this was needed. `config.load_defaults "7.1"`
+sets `log_file_size` to **100 MB** for development *and* test, and each keeps one
+rotated sibling — up to ~400 MB of log per checkout, times every worktree on the
+machine. The logs were never unbounded; the ceiling was just far too high for a
+machine that carries many desks. New ceiling: ~48 MB per checkout.
+
+**Production is untouched.** The cap applies only where `Rails.env.local?`, so
+every `production.rb` that hands its stream to STDOUT keeps doing exactly that,
+and a host that names its own `config.logger` is never overridden.
+
+**Ordering is the load-bearing part of this change.** Rails' `:initialize_logger`
+is a *bootstrap* initializer — it runs before every railtie and engine
+initializer and does `Rails.logger ||= config.logger || <default>`. An engine
+that assigns `app.config.logger` from an ordinary initializer is therefore a
+silent no-op: Rails has already built the logger. So `studio.logger` declares
+`before: :initialize_logger` and sets `config.log_file_size`, the knob Rails
+itself reads one moment later, leaving Rails owning the path, formatter, level,
+and tagging. `after: :load_environment_hook` pins the other edge of the window,
+which also keeps Railtie's implicit initializer chaining from dragging
+`studio.assets` forward.
+
+`test/integration/log_rotation_test.rb` asserts the **behavior**, not the
+config: it boots real Rails apps and checks that the log file actually rotates
+on disk once it passes the cap. It carries a mutation control — the same 17 MB
+log with the cap switched off must *not* rotate — so the suite cannot be
+satisfied by Rails' 100 MB default. Dropping the `before:` ordering reds it.
+
+**New setting — `Studio.local_log_max_bytes`.** `false` opts out; an Integer
+sets your own cap. Unlike every other `Studio.*` setting, it must be set in
+`config/application.rb` (after `require "studio"`) or `config/environments/*.rb`
+— `config/initializers/studio.rb` loads too late to be read.
+
+---
+
+**The environment banner is now the navbar's SIBLING, not its child, and the
+navbar sizes itself to whatever bars are actually there.** Nesting the banner
+inside the navbar coupled two unrelated components: every new bar meant editing
+the navbar, and there is already a second bar (impersonation), so this was never
+a 0-or-1 problem.
+
+Render the stack immediately before the navbar:
+
+```erb
+<%= render "studio/banners/stack" %>
+<%= render "layouts/navbar" %>
+```
+
+The bars do not know the navbar exists; the navbar does not know which bars
+rendered — only how tall they are, via `--studio-bars-h`.
+
+**The height is MEASURED, not assumed.** A `ResizeObserver` on the stack
+publishes its real height, so a bar that needs to be taller, a second bar, or one
+that wraps on a narrow screen all work with **no change to any consuming app**.
+A server-rendered estimate paints first so the common case never flashes, then the
+observer replaces it with the truth. Verified in a real browser: growing the bar
+32px moved the stack, the published property and the header's `top` together, on
+the same frame.
+
+**Backward-compatible.** An app that renders no stack gets
+`var(--studio-bars-h, 0px)` — identical to the old `top-0`. Adoption is opt-in.
+
+### Added
+
+- **`studio/banners/stack`** — renders whichever bars apply (environment via
+  `Studio.show_environment_banner?`, impersonation when the host passes
+  `impersonated_user` / `admin_user` / `stop_path`) and publishes their measured
+  height. Takes `preview:` and forwards `devnet:` / `extra:` to the environment bar.
+  A preview render emits nothing at all, so a navbar-preview copy cannot duplicate
+  live chrome or publish a height.
+- **`Studio.local_log_max_bytes`** — the opt-out (`false`) or override (an
+  Integer) for the new local log cap. Set it in `config/application.rb` or
+  `config/environments/*.rb`, never `config/initializers/studio.rb`.
+
+### Changed
+
+- **The navbar's sticky `top` reads `--studio-bars-h`** instead of hardcoding
+  `top-0`. It never branches on which bars rendered.
+- **Banners are branded off the app's own theme tokens** — the environment bar
+  derives from `--color-warning` and impersonation from `--color-danger`, each
+  under a translucent gradient wash, replacing hardcoded hex stops. An app that
+  retunes its theme now gets a banner that follows it.
+- **Local `development` and `test` logs rotate at 16 MB / 8 MB** via the new
+  `studio.logger` initializer, down from Rails' 100 MB default. Production is
+  untouched.
+
 ## 0.32.3 — 2026-08-09
 
 **New public CSS custom property: `--nav-bottom`.** `_head.html.erb` now
@@ -48,7 +213,7 @@ rendered the desktop trigger on mobile beside the real one. Callers now own
 the display class (bare renders default to `inline-flex`). Regression view
 tests pin both.
 
-## 0.32.1 — Unreleased
+## 0.32.1 — 2026-08-09
 
 **Setup-guide corrections.** Docs only — no code, no behavior change.
 

data/README.md

@@ -54,6 +54,35 @@ Studio.configure do |config|
 end
 ```
 
+### Local log rotation (automatic — nothing to configure)
+
+The engine caps the host app's **development** log at 16 MB and its **test** log
+at 8 MB, keeping one rotated sibling each. There is nothing to install, run, or
+remember: it rides the gem, so every checkout and every worktree is born with it.
+
+It exists because Rails' own default is far too generous for a machine that
+carries many worktrees. `config.load_defaults "7.1"` sets `log_file_size` to
+**100 MB** for development *and* test, and each keeps a rotated sibling — up to
+~400 MB of log per checkout.
+
+**Production is untouched.** The cap applies only where `Rails.env.local?`, so
+apps that hand their stream to STDOUT for the platform keep doing exactly that.
+A host that names its own `config.logger` is never overridden.
+
+To choose your own cap, or to opt out:
+
+```ruby
+# config/application.rb (after `require "studio"`) or config/environments/development.rb
+Studio.local_log_max_bytes = 64.megabytes  # your own cap
+Studio.local_log_max_bytes = false         # opt out; Rails' 100 MB default returns
+```
+
+**This one setting cannot go in `config/initializers/studio.rb`.** It is read
+during boot — Rails builds the logger in a bootstrap initializer, long before
+`config/initializers` is loaded — so an initializer would be too late and would
+silently do nothing. Every *other* `Studio.*` setting belongs in the initializer
+as usual.
+
 Transactional mail transport is shared through `Studio::MailTransport`:
 
 ```ruby

data/app/controllers/studio/local_reviews_controller.rb

@@ -19,6 +19,15 @@ module Studio
   # exposure the inbox already carries, which hands every captured sign-in link
   # to any local reader. It is a development desk convenience; it is not a
   # sign-in path.
+  #
+  # It also PROVISIONS the account before minting, at Studio.local_review_role
+  # (default "admin"). The email the board hands over is the operator's
+  # PRODUCTION address, and a fresh worktree database has never seen it — so
+  # without this the consume takes Studio::LinkConsumption#sign_up_new, creates
+  # him at the default role ("viewer"), and `require_admin` on the page under
+  # review redirects him to "/". The sign-in SUCCEEDS and he never sees the
+  # page, which is what made the failure so quiet: a seeded admin works, so only
+  # the operator's real address ever hit it.
   class LocalReviewsController < ApplicationController
     include Studio::MagicLinkIssuing
 
@@ -27,9 +36,13 @@ module Studio
     before_action :require_local_development!
 
     def show
-      email = Studio::LinkToken.normalize_email(params[:email])
+      email = reviewer_email
       return redirect_to(login_path, alert: MISSING_EMAIL) unless email.match?(URI::MailTo::EMAIL_REGEXP)
 
+      # Provision BEFORE minting, so the consume finds an existing account and
+      # takes sign_in_existing rather than sign_up_new-at-the-default-role.
+      provision_reviewer(email)
+
       # return_to is passed through raw: the store sanitizes it to a same-origin
       # path on the way in (Studio::Link.create_magic_link calls
       # Studio::LinkToken.sanitize_path). Re-sanitizing here would be a second
@@ -43,6 +56,77 @@ module Studio
 
     MISSING_EMAIL = "Add ?email=<your address> to mint a local review link."
 
+    # WHO to sign in, in priority order:
+    #
+    #   1. `?email=` — an explicit caller still wins.
+    #   2. `Studio.local_review_email` — the app's declared desk operator.
+    #   3. the first admin in this database — the seeded operator, by id.
+    #
+    # The board deliberately stops at (1) being ABSENT. Its WAITING APPROVAL CTA
+    # is a public, sign-in-free redirect, so an email in that URL would be an
+    # address published on a public page for anyone to read. The local stack is
+    # the right place to answer "who is at this desk": it is the machine the
+    # reviewer is sitting at, and it already knows its own operator.
+    def reviewer_email
+      Studio::LinkToken.normalize_email(
+        params[:email].presence || Studio.local_review_email.presence || seeded_admin_email
+      )
+    end
+
+    # The database's own first admin. Ordered by id so a re-seeded desk resolves
+    # to the same person every time rather than to whoever was touched last.
+    # Rescued because this runs before the mint on every click: a host with no
+    # role column must fall through to MISSING_EMAIL, not a 500.
+    def seeded_admin_email
+      return nil unless User.respond_to?(:column_names) && User.column_names.include?("role")
+
+      User.where(role: Studio.local_review_role.presence || "admin").order(:id).first&.email
+    rescue StandardError => e
+      Rails.logger.warn("[Studio::LocalReviewsController] no default reviewer: #{e.class}: #{e.message}")
+      nil
+    end
+
+    # Find-or-create the reviewer and ensure Studio.local_review_role, so the
+    # page under review actually RENDERS for whoever follows the link.
+    #
+    # Best-effort by design. Provisioning is an upgrade to the mint, not a
+    # precondition of it: a host with an extra User validation must not turn the
+    # review button into a 500 — it should still hand back a working sign-in
+    # link, exactly as it did before this method existed. So a failure is logged
+    # loudly and the mint proceeds. The end-to-end check that the operator
+    # actually lands ON the page is the real gate; this is the thing that makes
+    # it pass, not the thing that proves it.
+    # `User` is referenced bare, with no defined?/const_defined? guard: those do
+    # not agree with each other about a Zeitwerk autoload that has not fired
+    # yet, and a guard that reads "absent" on a cold boot would skip
+    # provisioning silently — the failure mode being fixed. Studio::LinkConsumption
+    # already requires every consuming app to have User, so a genuinely missing
+    # one is a NameError the rescue below logs like any other host mismatch.
+    def provision_reviewer(email)
+      user = User.find_by(email: email) || build_reviewer(email)
+      role = Studio.local_review_role.presence
+      user.role = role if role && user.respond_to?(:role=) && user.role != role
+      user.save! if user.new_record? || user.changed?
+      user
+    rescue StandardError => e
+      # No re-raise: see "best-effort" above. Logged at warn because a silent
+      # miss here reappears as the exact symptom this endpoint exists to remove
+      # — a successful sign-in that lands on the wrong page.
+      Rails.logger.warn(
+        "[Studio::LocalReviewsController] could not provision #{email}: #{e.class}: #{e.message}"
+      )
+      nil
+    end
+
+    # A brand-new reviewer goes through the host's own new-user hook first, so
+    # the account this endpoint creates is shaped like every other account in
+    # the app (usernames, defaults, associations) — then the role is stamped on
+    # top. Mirrors Studio::LinkConsumption#sign_up_new, which is the path this
+    # provisioning is standing in for.
+    def build_reviewer(email)
+      User.new(email: email).tap { |user| Studio.configure_new_user.call(user) }
+    end
+
     def require_local_development!
       head :not_found unless Studio.local_tool_enabled?(request_local: request.local?)
     end

data/app/views/layouts/_navbar.html.erb

@@ -38,7 +38,13 @@
 %>
 
 <header x-data="{ scrolled: false }" <%= '@scroll.window="scrolled = scrolled ? (window.scrollY > 5) : (window.scrollY > 60)"'.html_safe unless is_preview %>
-        class="<%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky top-0 z-50 bg-page transition-shadow duration-300" %>"
+        <%# top offsets by whatever studio/banners/_stack rendered above us. The
+            stack publishes --studio-bars-h on :root; with no stack the fallback
+            0px makes this identical to the old `top-0`, so an app that has not
+            adopted the stack is unaffected. The navbar never learns WHICH bars
+            rendered — only how tall they are. %>
+        style="<%= "top:var(--studio-bars-h, 0px);" unless is_preview %>"
+        class="<%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky z-50 bg-page transition-shadow duration-300" %>"
         :class="scrolled && 'shadow-lg border-b border-subtle is-scrolled'">
   <style>
     .user-nav-col { width: 14rem; }

data/app/views/studio/banners/_app_banner.html.erb

@@ -4,19 +4,32 @@
   message = local_assigns.fetch(:message)
   actions = local_assigns[:actions]
 
+  # Branded off the app's OWN theme tokens rather than hardcoded hexes, so a host
+  # that retunes --color-warning / --color-danger gets a banner that matches it.
+  # The gradient is a translucent black wash over the token — deliberately not
+  # color-mix(), which would need a modern-browser floor for pure decoration, and
+  # deliberately not two hardcoded stops, which cannot follow a themed colour.
   tones = {
     environment: {
-      background: "linear-gradient(90deg, #9d174d 0%, #f72585 100%)",
+      background: "linear-gradient(90deg, rgba(0,0,0,0.28) 0%, rgba(0,0,0,0.04) 100%), " \
+                  "var(--color-warning, #FF7C47)",
       color: "#ffffff",
       shadow: "0 2px 8px rgba(0,0,0,0.25)"
     },
     impersonation: {
-      background: "linear-gradient(90deg, #b91c1c 0%, #d97706 100%)",
+      background: "linear-gradient(90deg, rgba(0,0,0,0.30) 0%, rgba(0,0,0,0.06) 100%), " \
+                  "var(--color-danger, #EF4444)",
       color: "#ffffff",
       shadow: "0 2px 8px rgba(0,0,0,0.25)"
     }
   }
 
+  # INTRINSIC height — content decides, and studio/banners/_stack MEASURES the
+  # result. An earlier cut declared a fixed height so the stack could compute its
+  # total server-side; that was rejected deliberately, because it cannot express
+  # a bar that needs to be taller, or two bars stacked, without every consuming
+  # app being reworked. The apps should respond to what the bar needs, not the
+  # other way round.
   density_styles = {
     compact: "font-size:12px; font-weight:700; padding:2px 12px;",
     normal: "font-size:14px; font-weight:700; padding:8px 16px;"

data/app/views/studio/banners/_stack.html.erb

@@ -0,0 +1,102 @@
+<%#
+  The bar stack — every pinned bar that sits ABOVE the navbar, as the navbar's
+  SIBLING rather than nested inside it.
+
+  Render it immediately before the navbar — the stack partial first, the navbar
+  partial second, as siblings. (Deliberately not written as ERB tags here: an
+  escaped tag inside an ERB comment ends the comment at its own closing marker
+  and dumps the rest of this block onto the page as text.)
+
+  Why a sibling and not nested (operator call, 2026-08-10): it composes. There is
+  already a second bar (impersonation), so this is not a 0-or-1 problem — it is
+  0, 1 or 2, and growing. Nesting each new bar inside the navbar coupled two
+  unrelated components and meant every new bar edited the navbar. Here the bars
+  do not know the navbar exists, and the navbar does not know which bars
+  rendered — only how tall they are, via --studio-bars-h.
+
+  HOW THE HEIGHT IS KNOWN. The stack MEASURES itself and publishes the result, so
+  a bar that needs to be taller — or a second bar, or a third — just works, and no
+  consuming app is reworked to allow it. The apps respond to what the bars need.
+
+  A server-rendered estimate (count × --studio-bar-unit) paints first so the
+  common case has no flash, then a ResizeObserver replaces it with the truth on
+  the same frame. An earlier cut declared a fixed bar height to avoid the
+  observer; that was rejected because it could only ever express the standard
+  case, which is the case that needed no help.
+
+  The property is published on :root from an inline <style>, deliberately. A
+  custom property set on this element would be invisible to the navbar, because
+  custom properties inherit DOWN, not ACROSS to siblings — and putting it on
+  <body> would need every host to change its layout.
+
+  Locals (all optional):
+    preview      — true inside a navbar-preview render; renders nothing, so a
+                   preview copy cannot duplicate live chrome or publish a height.
+    devnet       — forwarded to the environment bar (chip / message segment).
+    extra        — forwarded to the environment bar (message segments).
+    impersonated_user / admin_user / stop_path — render the impersonation bar
+                   too; omit them and it is skipped.
+%>
+<%
+  preview = local_assigns.fetch(:preview, false)
+
+  impersonated_user = local_assigns[:impersonated_user]
+  admin_user        = local_assigns[:admin_user]
+  stop_path         = local_assigns[:stop_path]
+  show_impersonation = !preview && impersonated_user && admin_user && stop_path
+
+  show_environment = !preview && Studio.show_environment_banner?
+
+  bars = capture do
+    if show_environment
+      concat(render("studio/banners/environment",
+                    devnet: local_assigns.fetch(:devnet, false),
+                    extra: local_assigns.fetch(:extra, [])))
+    end
+    if show_impersonation
+      concat(render("studio/banners/impersonation",
+                    impersonated_user: impersonated_user,
+                    admin_user: admin_user,
+                    stop_path: stop_path))
+    end
+  end
+
+  # count { } and not count(true): show_impersonation is a truthy USER, not the
+  # literal true, and count(true) compares with ==. That published a one-bar
+  # height for a two-bar stack — the navbar would have sat under a bar.
+  bar_count = [show_environment, show_impersonation].count { |bar| bar }
+%>
+<% if bar_count.positive? %>
+  <%# First-paint estimate only — the observer below replaces it with the measured
+      height. Expressed against a token so an app that retunes the unit still gets
+      a sensible pre-measurement value. %>
+  <%= tag.style safe_join([":root{--studio-bars-h:calc(#{bar_count} * var(--studio-bar-unit, 47px))}"]) %>
+  <div class="studio-bar-stack sticky top-0 z-[60] w-full" data-studio-bar-stack><%= bars %></div>
+  <script>
+    // Publishes the stack's REAL height, so the navbar offsets by what the bars
+    // actually need. Idempotent and re-bound on Turbo navigation — a stale
+    // observer pointed at a detached node silently stops updating, and the
+    // navbar would then sit at yesterday's offset.
+    (function () {
+      var apply = function () {
+        var el = document.querySelector("[data-studio-bar-stack]");
+        if (!el) {
+          document.documentElement.style.removeProperty("--studio-bars-h");
+          return;
+        }
+        if (window.__studioBarObserver) window.__studioBarObserver.disconnect();
+        var publish = function () {
+          var h = Math.round(el.getBoundingClientRect().height);
+          if (h > 0) document.documentElement.style.setProperty("--studio-bars-h", h + "px");
+        };
+        publish();
+        if (window.ResizeObserver) {
+          window.__studioBarObserver = new ResizeObserver(publish);
+          window.__studioBarObserver.observe(el);
+        }
+      };
+      apply();
+      document.addEventListener("turbo:load", apply);
+    })();
+  </script>
+<% end %>

data/lib/studio/engine.rb

@@ -1,5 +1,44 @@
+require_relative "log_rotation"
+
 module Studio
   class Engine < ::Rails::Engine
+    # Cap the local (development + test) log files, for every host app and
+    # every future one, with nobody running anything.
+    #
+    # ORDERING IS THE WHOLE TRICK — do not demote this to a bare initializer.
+    # Rails' `:initialize_logger` is a BOOTSTRAP initializer, so it runs before
+    # every railtie/engine initializer and does `Rails.logger ||= config.logger
+    # || <default>`. An engine that assigns `app.config.logger` from an ordinary
+    # initializer is a silent NO-OP: Rails.logger is already built. Verified,
+    # not assumed — a probe boot kept Rails' 100 MB cap and its own file.
+    # So this hands Rails the size BEFORE Rails builds the logger, which is
+    # exactly the knob `:initialize_logger` reads:
+    #   ActiveSupport::Logger.new(config.default_log_file, 1, config.log_file_size)
+    # and Rails keeps ownership of the path, formatter, level, and tagging.
+    #
+    # `after: :load_environment_hook` pins the lower edge of that window for two
+    # reasons: config/environments/*.rb is loaded by `:load_environment_config`
+    # (declared `before: :load_environment_hook`), so the host's own choices are
+    # already visible here; and it keeps Railtie's implicit `after: <previous
+    # initializer>` chaining from dragging `studio.assets` forward with us.
+    # WHICH cap (and whether to touch anything at all) is Studio::LogRotation's
+    # decision — Rails-free, and unit-tested a branch at a time.
+    #
+    # The host's escape hatch, `Studio.local_log_max_bytes`, is read here rather
+    # than from config.x.<key>: an unset config.x key returns an empty
+    # ActiveSupport::OrderedOptions, NOT nil, so `config.x.foo || default`
+    # silently assigns the OrderedOptions and rotation then dies inside a
+    # rescued comparison. The behavioral test caught that; a config read-back
+    # would have called it green.
+    initializer "studio.logger", before: :initialize_logger, after: :load_environment_hook do |app|
+      cap = Studio::LogRotation.cap_for(
+        env: Rails.env,
+        host_logger: app.config.logger,
+        override: Studio.local_log_max_bytes
+      )
+      app.config.log_file_size = cap if cap
+    end
+
     initializer "studio.assets" do |app|
       app.config.assets.precompile += %w[
         studio/sticky_table_header.css

data/lib/studio/log_rotation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Studio
+  # The decision behind the engine's `studio.logger` initializer: given the
+  # environment and the host's own choices, how large may the local log file
+  # grow before it rotates — or should the engine keep its hands off entirely?
+  #
+  # Deliberately Rails-free so the whole decision table is unit-testable in
+  # milliseconds. The initializer in Studio::Engine owns the other half of the
+  # problem — running EARLY enough for the answer to matter — and that half is
+  # covered by test/integration/log_rotation_test.rb, which boots real apps and
+  # watches the file rotate on disk.
+  module LogRotation
+    # Deliberate values, not defaults. Rails' own `config.load_defaults "7.1"`
+    # sets log_file_size to 100 MB for development AND test, each keeping one
+    # rotated sibling — up to ~400 MB of log per checkout, times every worktree
+    # on the machine. 16 MB still holds a full day of local request logs; 8 MB
+    # covers a whole test run. Raising these is a decision, not a default.
+    DEVELOPMENT_MAX_BYTES = 16 * 1024 * 1024
+    TEST_MAX_BYTES        = 8 * 1024 * 1024
+
+    # The environments whose logs are plain local files worth capping. Held here
+    # rather than delegating to Rails.env.local? so that a future Rails adding a
+    # third "local" environment cannot silently change where this engine writes
+    # a cap.
+    CAPPED_ENVIRONMENTS = %w[development test].freeze
+
+    # Returns the byte cap to apply, or nil for "leave the host's logging
+    # exactly as it is".
+    #
+    #   env          the Rails environment name
+    #   host_logger  the host's own config.logger, if it named one
+    #   override     Studio.local_log_max_bytes — false opts out, an Integer
+    #                sets the host's own cap, nil means "use ours"
+    def self.cap_for(env:, host_logger: nil, override: nil)
+      # Production (and QA, which boots as production) hands its stream to the
+      # platform. Never point that at a file.
+      return nil unless CAPPED_ENVIRONMENTS.include?(env.to_s)
+      # A host that named its own logger has already decided.
+      return nil if host_logger
+      # Explicit opt-out; Rails' own default returns.
+      return nil if override == false
+      # Explicit host cap.
+      return override if override
+
+      env.to_s == "test" ? TEST_MAX_BYTES : DEVELOPMENT_MAX_BYTES
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.32.3"
+  VERSION = "0.36.0"
 end

data/lib/studio.rb

@@ -1,4 +1,5 @@
 require "studio/version"
+require "studio/log_rotation"
 require "studio/engine"
 require "studio/color_scale"
 require "studio/environment_banner"
@@ -136,6 +137,18 @@ module Studio
   mattr_accessor :impersonation_started_at_session_key, default: :impersonation_started_at
   mattr_accessor :impersonation_max_minutes, default: 30
 
+  # Cap for the host app's local (development + test) log file, in bytes.
+  # nil means "use the engine's defaults" — Studio::Engine::DEVELOPMENT_LOG_MAX_BYTES
+  # and ::TEST_LOG_MAX_BYTES. An Integer sets your own cap; `false` opts out and
+  # leaves Rails' own 100 MB default alone.
+  #
+  # UNLIKE every other setting here, this one is read during BOOT — before
+  # config/initializers/studio.rb is loaded — so it must be set earlier than the
+  # usual seam: in config/application.rb (after `require "studio"`) or in
+  # config/environments/development.rb. Setting it in an initializer is too late
+  # and does nothing.
+  mattr_accessor :local_log_max_bytes, default: nil
+
   # Default From: for engine-sent mail (magic links). Apps set this to their
   # verified sending address in config/initializers/studio.rb.
   mattr_accessor :mailer_from, default: nil
@@ -145,6 +158,36 @@ module Studio
   # is truthy, otherwise disabled. Production always disables capture.
   mattr_accessor :local_email_capture, default: nil
 
+  # The role Studio::LocalReviewsController stamps on the account it provisions
+  # for a local review (the board's WAITING APPROVAL button).
+  #
+  # It defaults to "admin" because the pages sent for review are overwhelmingly
+  # admin-gated, and the operator's address is his PRODUCTION one — an address a
+  # fresh worktree database has never seen, so the sign-in would otherwise CREATE
+  # him at the default role and `require_admin` would bounce him to "/". The
+  # sign-in succeeds and he never sees the page: the bug this knob exists to end.
+  #
+  # Set it to nil (or "") to provision the account WITHOUT touching its role —
+  # for an app whose review pages are not admin-gated, or whose role column
+  # means something else. Only ever reached behind local_tool_enabled?
+  # (non-production AND loopback), so it grants nothing a local reader could not
+  # already take from the local email inbox beside it.
+  mattr_accessor :local_review_role, default: "admin"
+
+  # WHO the local-review mint signs in when the caller names no `?email=`.
+  #
+  # The board's WAITING APPROVAL CTA is a public, sign-in-free redirect, so it
+  # sends no email — putting one in that URL would publish the operator's
+  # address on a public page. The local stack answers the question instead: it
+  # is the machine the reviewer is sitting at.
+  #
+  # nil (the default) means "derive": the first user in this database already
+  # holding local_review_role, by id — falling back to "admin" when that setting
+  # is itself nil. So a desk that switches local_review_role OFF has no role to
+  # derive FROM and should name its operator here explicitly, as should a desk
+  # whose operator is not the first seeded account at that role.
+  mattr_accessor :local_review_email, default: nil
+
   # Theme role colors (7 roles)
   mattr_accessor :theme_primary,  default: "#8E82FE"
   mattr_accessor :theme_dark,     default: "#1A1535"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.32.3
+  version: 0.36.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -266,6 +266,7 @@ files:
 - app/views/studio/banners/_email_status_button.html.erb
 - app/views/studio/banners/_environment.html.erb
 - app/views/studio/banners/_impersonation.html.erb
+- app/views/studio/banners/_stack.html.erb
 - app/views/studio/board/_board.html.erb
 - app/views/studio/board/_card_shell.html.erb
 - app/views/studio/board/_column.html.erb
@@ -336,6 +337,7 @@ files:
 - lib/studio/image_cache.rb
 - lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
+- lib/studio/log_rotation.rb
 - lib/studio/mail_transport.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb