studio-engine 0.33.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ed77550c057e9ec4e232cc40ea934ef4753cc1d73d30e98b52c0a56f7ad8c8d
-  data.tar.gz: 01b04c9da431ef4d43b75cf12533c3aece29c5557157af4c0f91eadf1fe9e2bb
+  metadata.gz: 8c692fc135af1ba83c08b27398c875bc547ae07bbcc492540ffd83250fccf680
+  data.tar.gz: 891c561fe2bef1386137af4fbbc22547f38613efe8bd373bf6ec31894086feef
 SHA512:
-  metadata.gz: a1b26944f9f08b070f00aec356cc2435e3e35096d1353c970dd797b486293e50827fa6e6a11b3bc67ea306ef505f740114640595a4db10da4e9883a71561633b
-  data.tar.gz: ce46eddd0627c5eae83daa9fc2eca518d74eae7500ce0e44a22faf016c0059d68b01f1d7b874e1f38d063918c460d36bf981d33b2a7f5dc3fe07ac6e0db85811
+  metadata.gz: 9cb8bb03d5adeec99336b5fab4d28b29c57be8686ca2afef58932ce866c321fe44f6ab0123609e6845151f938ab28790685bda6b9b21815ef3a3594d6c589921
+  data.tar.gz: 2c3be4aadf2a88d7838dab26b27c4a22604268138bba818f0b82890774f7bc5b81424d53a645d3fcc5ebf59a8f10197a9b37bd9cd44246c988d8dca3dfd2cd62

data/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 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

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/lib/studio/version.rb

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

data/lib/studio.rb

@@ -158,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.33.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Alex McRitchie