studio-engine 0.137.0 → 0.138.0

data/lib/studio/integrations/microsoft_365.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Studio
+  module Integrations
+    # MICROSOFT 365 (Microsoft Graph, app-only), the connection only. A host's
+    # readers (users, teams, sites) are its own; they call
+    # Studio.integration(:microsoft_365).api_base(connection) with a token from
+    # Studio.connection(:microsoft_365).access_token(connection).
+    #
+    #   * A tenant administrator approves the app at Microsoft's admin-consent
+    #     page (common: the tenant is not known until they sign in). Microsoft
+    #     comes back with ?tenant=<GUID>&admin_consent=True; anything but an
+    #     approval refuses the callback.
+    #   * The tenant id is private: stored only encrypted, the row keyed by a
+    #     digest, the callback's tenant param kept out of the logs by exact
+    #     key. It is lower-cased, so one tenant never makes two rows.
+    #   * CLIENT CREDENTIALS on the tenant's own token endpoint, with the Graph
+    #     .default scope (the application permissions the app registration
+    #     lists). No refresh token exists: the access token lives in this
+    #     process's memory only, per tenant.
+    #   * unauthorized_client means the app is not found in, or not enabled
+    #     for, the tenant: the grant is gone.
+    #   * NO REVOKE endpoint: consent is removed in the tenant's admin center.
+    #
+    # Checked against the hub's Msgraph::OAuthClient and Msgraph::Reader
+    # (mcritchie-studio), which cite Microsoft's identity-platform docs.
+    module Microsoft365
+      LOGIN_HOST = "https://login.microsoftonline.com"
+      AUTHORIZE_URL = "#{LOGIN_HOST}/common/adminconsent"
+      SCOPE = "https://graph.microsoft.com/.default"
+      API_URL = "https://graph.microsoft.com/v1.0"
+      TENANT_ID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+      Integrations.register :microsoft_365,
+        label: "Microsoft 365",
+        summary: "A Microsoft 365 tenant, read app-only after an administrator approves the app.",
+        connection: {
+          grant: :client_credentials,
+          authorize_url: AUTHORIZE_URL,
+          token_url: ->(tenant) { "#{LOGIN_HOST}/#{tenant}/oauth2/v2.0/token" },
+          scopes: [SCOPE],
+          account: :callback, account_param: "tenant", account_format: TENANT_ID,
+          normalize_account: ->(value) { value.to_s.strip.downcase },
+          private_account: true, filter_keys: %w[tenant],
+          revoked_errors: %w[unauthorized_client],
+          declined_errors: %w[access_denied permission_denied consent_required],
+          callback_check: lambda { |params|
+            "Microsoft did not report an approval. Nothing was connected." unless params[:admin_consent].to_s.casecmp?("true")
+          },
+          refusal_hint: "A tenant bought through a reseller may block the approval; otherwise check the app registration's redirect URI, then start again.",
+          revoke_note: "Remove the app in the tenant's Microsoft Entra admin center (Enterprise applications) to revoke its access there."
+        },
+        describe: lambda { |integration, grant:, account:, get:|
+          token = integration.provider.access_token(account)
+          { label: get.call("#{API_URL}/organization/#{account}", token)["displayName"] }
+        },
+        default_label: ->(_tenant) { "Microsoft 365 tenant" },
+        api_base: ->(_integration, _connection) { API_URL },
+        stand_in: { callback_params: { tenant: "00000000-0000-0000-0000-000000000000", admin_consent: "True" },
+                    answer: { "displayName" => "Stand-in Tenant" } }
+    end
+  end
+end

data/lib/studio/integrations/quickbooks.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Studio
+  module Integrations
+    # QUICKBOOKS ONLINE (Intuit), the connection only. A host's readers (company
+    # info, reports) are its own; they call Studio.integration(:quickbooks).api_base(connection).
+    #
+    #   * Sign-in at Intuit's app center. The endpoints come from Intuit's
+    #     discovery document
+    #     (https://developer.api.intuit.com/.well-known/openid_configuration),
+    #     the same for sandbox and production.
+    #   * The token and revoke calls authenticate with HTTP Basic; the revoke
+    #     body is JSON.
+    #   * CACHED access token, refreshed when it expires: Intuit's access token
+    #     lives about an hour (expires_in 3600). The row keeps it, encrypted,
+    #     with its expiry, and reuses it until 5 minutes before that expiry, or
+    #     until the API answers 401 (fresh_access_token(stale: token)). Then it
+    #     refreshes ONCE under the row's lock, reloading the row first, so a
+    #     racing caller waits and reads the new token instead of spending the
+    #     refresh token twice. A reader that still gets a 401 after that one
+    #     refresh asks the admin to connect again; it never loops.
+    #   * The refresh token ROTATES and the newest must be kept: every refresh
+    #     answer must carry one (rotation: :required, else nothing is stored and
+    #     the refresh refuses), and it is stored, with the access token and
+    #     x_refresh_token_expires_in, before the access token is used.
+    #   * invalid_grant on a refresh is a revoked grant: connect again.
+    #   * intuit_tid: Intuit names every answer with this response header, and
+    #     asks apps to keep it for support. It is read from every token
+    #     exchange, refresh, revoke and describe answer, logged with the call
+    #     (no token), kept as provider.last_trace_id, and carried by every error
+    #     raised (Error#trace_id, and in its message, so the error log has it).
+    #     Host readers call provider.record_trace(response, call:, status:).
+    #   * The company is named on the callback (?realmId=), a number, kept out
+    #     of the logs by exact key.
+    #   * The environment setting (sandbox, the default, or production) says
+    #     which Intuit keys these are, so which API host a new connection reads;
+    #     anything but "production" is the sandbox, so a typo never points
+    #     sandbox keys at live books. It is stored on the connection.
+    #
+    # Checked against the hub's Quickbooks::OAuthClient and Quickbooks::Reader
+    # (mcritchie-studio), which cite Intuit's documents.
+    module Quickbooks
+      AUTHORIZE_URL = "https://appcenter.intuit.com/connect/oauth2"
+      TOKEN_URL = "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer"
+      REVOKE_URL = "https://developer.api.intuit.com/v2/oauth2/tokens/revoke"
+      SCOPE = "com.intuit.quickbooks.accounting"
+      API_URLS = { "sandbox" => "https://sandbox-quickbooks.api.intuit.com",
+                   "production" => "https://quickbooks.api.intuit.com" }.freeze
+      # Intuit retired minor versions 1-74 in August 2025: 75 is the floor.
+      MINOR_VERSION = 75
+      REALM_ID = /\A\d{1,20}\z/
+
+      def self.api_url(environment) = API_URLS.fetch(environment.to_s, API_URLS.fetch("sandbox"))
+
+      Integrations.register :quickbooks,
+        label: "QuickBooks",
+        summary: "A QuickBooks Online company, read with its owner's sign-in.",
+        connection: {
+          authorize_url: AUTHORIZE_URL, token_url: TOKEN_URL, revoke_url: REVOKE_URL,
+          scopes: [SCOPE],
+          client_auth: :basic, revoke_format: :json,
+          refresh: :cached, refresh_margin: 5.minutes, rotation: :required,
+          refresh_expires_in_key: "x_refresh_token_expires_in",
+          account: :callback, account_param: "realmId", account_format: REALM_ID,
+          filter_keys: %w[realmId], trace_header: "intuit_tid",
+          refusal_hint: "Check the Intuit app's redirect URI, then start again."
+        },
+        settings: { environment: { values: %w[sandbox production], default: "sandbox" } },
+        metadata: ->(integration) { { "environment" => integration.setting(:environment) } },
+        describe: lambda { |integration, grant:, account:, get:|
+          token = grant["access_token"].to_s
+          next {} if token.empty?
+
+          base = "#{Quickbooks.api_url(integration.setting(:environment))}/v3/company/#{account}"
+          info = get.call("#{base}/companyinfo/#{account}?minorversion=#{MINOR_VERSION}", token)["CompanyInfo"]
+          { label: info.is_a?(Hash) ? info["CompanyName"] : nil }
+        },
+        default_label: ->(_account) { "QuickBooks company" },
+        api_base: lambda { |_integration, connection|
+          "#{Quickbooks.api_url(connection.metadata.to_h['environment'])}/v3/company/#{connection.account_id}"
+        },
+        stand_in: { callback_params: { realmId: "1000000001" },
+                    answer: { "CompanyInfo" => { "CompanyName" => "Stand-in Company" } } }
+    end
+  end
+end

data/lib/studio/integrations.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+require "json"
+
+module Studio
+  # INTEGRATIONS: the engine's registry of integration CONNECTION definitions
+  # (docs/INTEGRATIONS.md), on top of the generic connection tooling
+  # (Studio::Connections, docs/CONNECTIONS.md).
+  #
+  # The engine ships one definition per integration it knows (QuickBooks,
+  # Egnyte, Microsoft 365). A definition holds the connection only: the URLs,
+  # the scopes, the token behaviour, and a minimal describe that names the
+  # account just connected (the company, the user, the organization). It holds
+  # NO reader and makes no business-data call: a host writes its own readers
+  # and plugs them into the integration's page with a panel.
+  #
+  # A host turns one on with one line in an initializer, naming its own env vars:
+  #
+  #   Studio.enable_integration :quickbooks,
+  #     env: { client_id: "INTUIT_CLIENT_ID", client_secret: "INTUIT_CLIENT_SECRET",
+  #            environment: "INTUIT_ENVIRONMENT" },
+  #     panel: "admin/integrations/quickbooks_panel"
+  #
+  # and mounts the admin page with Studio.draw_integrations_routes. An enabled
+  # integration stays off (Connect says which env vars are missing) until its
+  # client id and secret are set.
+  module Integrations
+    # Seconds to open the describe call's connection, and to read its answer.
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 20
+
+    # One integration the engine knows: the connection only.
+    #
+    #   key             the integration's key, and its connection's
+    #   label           the name on the page and every message
+    #   summary         one line on the page: what connecting it gives the host
+    #   connection      the Studio::Connections::Provider options, every one but
+    #                   env:, label: and describe:
+    #   settings        extra env vars a host may name besides the client id and
+    #                   secret: { name: { values: [...], default: "..." } }; a
+    #                   value outside `values` reads as the default
+    #   account_label   the Connect form's field label (account: :connect only)
+    #   account_hint    its placeholder
+    #   metadata        ->(integration) { Hash }: stored on every new connection,
+    #                   with no network call (the provider environment)
+    #   describe        ->(integration, grant:, account:, get:) { { label:, metadata: } }:
+    #                   names the account just connected with ONE call through
+    #                   `get` (->(url, token) { JSON Hash }); a Connections::Error
+    #                   there stores the connection under default_label
+    #   default_label   ->(account) { String }: the label when describe cannot say
+    #   api_base        ->(integration, connection) { String }: where the host's
+    #                   own readers send their calls for this connection
+    #   stand_in        { callback_params: {...}, answer: {...} }: what the
+    #                   stand-in's sign-in page sends back, and what its describe
+    #                   call answers (development and test only)
+    Definition = Struct.new(:key, :label, :summary, :connection, :settings, :account_label, :account_hint,
+                            :metadata, :describe, :default_label, :api_base, :stand_in, keyword_init: true)
+
+    # The statuses an enabled integration can be in, in order.
+    STATUSES = {
+      not_set_up: "Not set up",
+      ready: "Ready to connect",
+      connected: "Connected"
+    }.freeze
+
+    class << self
+      # Adds a definition to the engine's catalog. The engine's own definitions
+      # register themselves when lib/studio/integrations/*.rb loads.
+      def register(key, **fields)
+        definition = Definition.new(key: key.to_s, settings: {}, metadata: ->(_integration) { {} },
+                                    default_label: nil, stand_in: {}, **fields)
+        definition.settings = definition.settings.to_h.transform_keys(&:to_sym)
+        lock.synchronize { catalog_map[definition.key] = definition.freeze }
+      end
+
+      # Every integration the engine knows, enabled or not.
+      def catalog = lock.synchronize { catalog_map.values }
+
+      def definition(key)
+        lock.synchronize { catalog_map[key.to_s] } or
+          raise ArgumentError, "the engine has no integration #{key.to_s.inspect}; it knows #{catalog.map(&:key).join(', ')}"
+      end
+
+      # Turns an integration on: defines its connection (Studio.define_connection)
+      # with the host's env names, and adds it to the admin page.
+      def enable(key, env:, panel: nil, label: nil, scopes: nil)
+        integration = Integration.new(definition(key), env:, panel:, label:, scopes:)
+        lock.synchronize { enabled_map[integration.key] = integration }
+        integration
+      end
+
+      # The enabled integrations, in the order the host enabled them.
+      def all = lock.synchronize { enabled_map.values }
+
+      def enabled?(key) = lock.synchronize { enabled_map.key?(key.to_s) }
+
+      def fetch(key)
+        lock.synchronize { enabled_map[key.to_s] } or raise ArgumentError, "the integration #{key.to_s.inspect} is not enabled"
+      end
+
+      # Where draw_integrations_routes mounted the page ("admin/integrations").
+      attr_accessor :mount_path
+
+      # Forgets every enabled integration (not the catalog). Tests only.
+      def reset!
+        lock.synchronize do
+          enabled_map.clear
+          @mount_path = nil
+        end
+      end
+
+      private
+
+      def catalog_map = (@catalog_map ||= {})
+      def enabled_map = (@enabled_map ||= {})
+      def lock = (@lock ||= Monitor.new)
+    end
+
+    # One integration a host enabled: its definition, the host's env names, its
+    # connection provider and the host's panel.
+    class Integration
+      attr_reader :definition, :env, :panel, :provider
+
+      # Stand-in for the describe call: (url, headers) -> [status, body]. nil
+      # means the provider itself. Refused outside development and test.
+      attr_reader :api_http
+
+      def initialize(definition, env:, panel: nil, label: nil, scopes: nil)
+        @definition = definition
+        @env = env.to_h.transform_keys(&:to_sym)
+        unknown = @env.keys - %i[client_id client_secret] - definition.settings.keys
+        raise ArgumentError, "#{key}: env names client_id, client_secret#{definition.settings.keys.map { ", #{_1}" }.join}; not #{unknown.join(', ')}" if unknown.any?
+        raise ArgumentError, "#{key}: env values are env var names (Strings)" unless @env.values.all?(String)
+
+        @panel = panel&.to_s
+        options = definition.connection.merge(
+          label: label || definition.label,
+          env: @env.slice(:client_id, :client_secret),
+          describe: ->(grant:, account:, provider:) { describe_account(grant:, account:) }
+        )
+        options[:scopes] = Array(scopes) if scopes
+        @provider = Studio.define_connection(definition.key, **options)
+      end
+
+      def key = definition.key
+      def label = provider.label
+      def summary = definition.summary
+
+      # A setting's value from the host's env var: one of its values, else its default.
+      def setting(name)
+        spec = definition.settings.fetch(name.to_sym)
+        value = @env[name.to_sym] && ENV[@env[name.to_sym]].to_s.strip.downcase
+        spec[:values].include?(value) ? value : spec[:default]
+      end
+
+      # Every connection of this integration this server can read, newest first.
+      def connections = Studio::Connection.readable(key)
+
+      # What keeps a Connect from starting here, as sentences (empty when none).
+      def missing
+        reasons = []
+        unless provider.connectable?
+          unset = provider.env_names.reject { |name| ENV[name].to_s.strip != "" }
+          reasons << "#{unset.join(' and ')} #{unset.one? ? 'is' : 'are'} not set."
+        end
+        reasons << "The app's Active Record encryption keys are not set." unless Studio::Connections.encryption_ready?
+        reasons
+      end
+
+      # :not_set_up, :ready or :connected (STATUSES).
+      def status
+        return :not_set_up if missing.any?
+
+        connections.any? ? :connected : :ready
+      end
+
+      def status_label = STATUSES.fetch(status)
+
+      # Where the host's readers send their calls for `connection`.
+      def api_base(connection) = definition.api_base.call(self, connection)
+
+      def api_http=(callable)
+        unless callable.nil? || Studio::Connections.seams_allowed?
+          raise Studio::Connections::Error, "#{label}: the describe stand-in is for tests, the e2e lane and a local demo (development and test only)"
+        end
+
+        @api_http = callable
+      end
+
+      # Stands the whole integration in: the provider's sign-in page and token
+      # endpoints (Studio::Connections::StandIn) and the describe call.
+      # Development and test only; refused anywhere else.
+      def install_stand_in!(access_lifetime: 3600)
+        answer = definition.stand_in.fetch(:answer, {}).to_json
+        self.api_http = ->(_url, _headers) { [200, answer] }
+        Studio::Connections::StandIn.install!(provider, callback_params: definition.stand_in.fetch(:callback_params, {}), access_lifetime:)
+        self
+      end
+
+      def uninstall_stand_in!
+        self.api_http = nil
+        Studio::Connections::StandIn.uninstall!(provider)
+        self
+      end
+
+      # The provider's describe hook: the definition's metadata, then its one
+      # describe call. A refusal there keeps the metadata and the default label.
+      def describe_account(grant:, account:)
+        metadata = definition.metadata.call(self).to_h
+        described = {}
+        if definition.describe
+          begin
+            described = definition.describe.call(self, grant:, account:, get: method(:describe_get)).to_h.symbolize_keys
+          rescue Studio::Connections::Error => e
+            # Kept in the error log (with the provider's trace id, when it names
+            # one), as a refused exchange is; the connection still stores.
+            begin
+              ::ErrorLog.capture!(e) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+            rescue StandardError => log_error
+              Rails.logger.error("[studio_integration] describe #{key} refused (#{e.message}); ErrorLog write failed: #{log_error.class}")
+            end
+          end
+        end
+        label = described[:label].to_s.strip.presence || definition.default_label&.call(account)
+        { label:, metadata: metadata.merge(described[:metadata].to_h) }.compact
+      end
+
+      private
+
+      # The describe call's one GET: a bearer token, JSON back. Raises
+      # Studio::Connections::Error (RateLimited on a 429) on anything but a 200.
+      def describe_get(url, token)
+        headers = { "Authorization" => "Bearer #{token}", "Accept" => "application/json" }
+        status, body, answered = api_http ? api_http.call(url, headers) : request(url, headers)
+        trace = provider.record_trace(answered, call: "describe", status:)
+        traced = { trace_header: provider.trace_header, trace_id: trace }
+        json = begin
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError
+          {}
+        end
+        json = {} unless json.is_a?(Hash)
+        raise Studio::Connections::RateLimited.new("#{label} is throttling this app (429)", **traced) if status == 429
+        raise Studio::Connections::Error.new("#{label} answered #{status} to the describe call", **traced) unless status == 200
+
+        json
+      end
+
+      def request(url, headers)
+        uri = URI(url)
+        raise Studio::Connections::Error, "#{label}: a describe call must be https" unless uri.scheme == "https"
+
+        get = Net::HTTP::Get.new(uri)
+        headers.each { |name, value| get[name] = value }
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) { _1.request(get) }
+        [response.code.to_i, response.body, response]
+      rescue *Studio::Connections::NETWORK_ERRORS => e
+        raise Studio::Connections::Error, "#{label} could not be reached: #{e.class}"
+      end
+    end
+  end
+end

data/lib/studio/node_tooling/README.md

@@ -8,7 +8,15 @@ host gets it with the engine it already bundles: no npm registry, no token.
   exactly this version.
 - `playwright_base.js`: the browser lane's shared defaults (one chromium
   project, one worker, a Rails `webServer` on `/up`).
-- `e2e_helpers.js`: `watchPageErrors` and `blockOffsiteRequests`.
+- `e2e_helpers.js`: `watchPageErrors` and `blockOffsiteRequests`; for a page
+  transition spec, the reveal waits (`watchReveal`, `revealed`, `settled`,
+  `arrivalSettled`, `frames`) and the log-on-red hook (`sessionLog`, `logOnRed`).
+  The waits read events the browser fires, never a clock.
+
+A local run reuses a server already on the e2e port only when that server's
+working directory is inside this tree (`mayReuseServer` in `playwright_base.js`,
+read with `lsof`). Any other server there is refused, with a warning that names
+its root: give the run its own port with `E2E_PORT=<free port>`.
 - `node_test/register.mjs` and `node_test/importmap_hooks.mjs`: let `node --test`
   import a module by the bare name the importmap pins it under.
 

data/lib/studio/node_tooling/e2e_helpers.js

@@ -71,4 +71,96 @@ async function blockOffsiteRequests(page, { pinned = {} } = {}) {
   });
 }
 
-module.exports = { isOffOrigin, watchPageErrors, blockOffsiteRequests };
+// ---- Full-load page transitions (docs/PAGE_TRANSITIONS.md, "Full page loads") ----
+//
+// These wait on events the browser fires, never on a clock. Nothing here sleeps.
+
+// Marks each document's pagereveal, for revealed(), settled() and arrivalSettled() below.
+// Call it before the first navigation: it is an init script, so every new document gets it,
+// and it must be bound before the first render to hear pagereveal at all.
+//
+// `window.__studioReveal` holds { revealed, transition, done }: `done` is true once the
+// arrival's view transition has finished or been skipped, at once when there is none.
+function watchReveal(target) {
+  return target.addInitScript(() => {
+    const state = { revealed: false, transition: false, done: false };
+    window.__studioReveal = state;
+    window.addEventListener("pagereveal", (event) => {
+      state.revealed = true;
+      const transition = event.viewTransition;
+      state.transition = !!transition;
+      if (!transition) { state.done = true; return; }
+      const done = () => { state.done = true; };
+      transition.finished.then(done, done);
+    });
+  });
+}
+
+// The new page has revealed. VISIBLE IS NOT REVEALED: its DOM parses, and Playwright sees it
+// as visible, before its first render. A render-blocking sheet, or the reveal script's own
+// hold to the end of parse, keeps pagereveal back, and until then no mark is set and no
+// pseudo runs (engine CI run 42503970890 read an empty log at 312 ms).
+async function revealed(page, selector) {
+  if (selector) await page.locator(selector).first().waitFor({ state: "visible" });
+  await page.waitForFunction(() => window.__studioReveal && window.__studioReveal.revealed === true);
+}
+
+// Past the whole motion: revealed, and the document's own marks and every
+// ::view-transition animation are gone when this returns.
+async function settled(page, selector) {
+  await revealed(page, selector);
+  await page.waitForFunction(() => document.documentElement.dataset.pageTransition === undefined
+    && !document.getAnimations().some((a) => ((a.effect && a.effect.pseudoElement) || "").startsWith("::view-transition")));
+}
+
+// Two rendered frames. A recorder that samples document.getAnimations() on every
+// requestAnimationFrame has run at least once past anything that was live before this call.
+function frames(page, count = 2) {
+  return page.evaluate((n) => new Promise((done) => {
+    const step = (left) => (left === 0 ? done() : requestAnimationFrame(() => step(left - 1)));
+    step(n);
+  }), count);
+}
+
+// For a spec that asserts NOTHING PLAYED: the arrival's view transition has finished or been
+// skipped, and two frames have rendered since. A transition that wrongly plays keeps `done`
+// false until its last frame, and every frame it draws comes before this returns, so a
+// per-frame recorder has logged it. A fixed pause only hoped for that.
+async function arrivalSettled(page, selector) {
+  await revealed(page, selector);
+  await page.waitForFunction(() => window.__studioReveal.done === true);
+  await frames(page);
+}
+
+// A log kept in sessionStorage, so it outlives each document of a full load.
+function sessionLog(page, key = "pt-log") {
+  return page.evaluate((name) => JSON.parse(sessionStorage.getItem(name) || "[]"), key);
+}
+
+// A red carries its evidence: registers an afterEach that, on a failed test only, prints the
+// log `read(page)` returns and attaches it to the report the CI uploads. A red with no log
+// once left its cause unprovable. `test` is the host's own @playwright/test `test`, since
+// this file cannot require Playwright (see README.md).
+function logOnRed(test, read = (page) => sessionLog(page), { name = "pt-log" } = {}) {
+  test.afterEach(async ({ page }, testInfo) => {
+    if (testInfo.status === testInfo.expectedStatus) return;
+    const lines = await Promise.resolve()
+      .then(() => read(page))
+      .catch((error) => [`(the log could not be read: ${error.message})`]);
+    console.log(`${name} for "${testInfo.title}":\n${lines.join("\n")}`);
+    await testInfo.attach(name, { body: lines.join("\n"), contentType: "text/plain" });
+  });
+}
+
+module.exports = {
+  isOffOrigin,
+  watchPageErrors,
+  blockOffsiteRequests,
+  watchReveal,
+  revealed,
+  settled,
+  frames,
+  arrivalSettled,
+  sessionLog,
+  logOnRed,
+};

data/lib/studio/node_tooling/playwright_base.js

@@ -14,6 +14,10 @@
 // Every key of `overrides` replaces the default of the same name; `use` merges
 // one level deep, so a host can add `reducedMotion` and keep `baseURL`.
 
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
 const DEFAULTS = Object.freeze({
   testDir: "./e2e",
   timeout: 30_000,
@@ -29,14 +33,57 @@ function studioBaseURL({ defaultPort, env = process.env } = {}) {
   return { port, external, baseURL: external || `http://127.0.0.1:${port}` };
 }
 
+// The working directory of whatever listens on `port`, read with lsof: { root } for a
+// listener, { root: null } for none, { unknown: true } when it cannot be told (no lsof, a
+// process lsof may not read).
+function listenerRoot(port) {
+  const run = (args) => execFileSync("lsof", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+  let pids;
+  try {
+    pids = run(["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"]).split("\n").filter(Boolean);
+  } catch (error) {
+    // lsof exits 1, printing nothing, when nothing listens.
+    if (error.status === 1 && !error.stdout) return { root: null };
+    return { unknown: true };
+  }
+  if (pids.length === 0) return { root: null };
+  try {
+    const line = run(["-a", "-p", pids[0], "-d", "cwd", "-Fn"]).split("\n").find((entry) => entry.startsWith("n"));
+    return line ? { root: line.slice(1) } : { unknown: true };
+  } catch (_error) {
+    return { unknown: true };
+  }
+}
+
+function realpath(path) {
+  try { return fs.realpathSync(path); } catch (_error) { return path; }
+}
+
+// May this run reuse the server already on `port`? Only one this tree started. Playwright's
+// own check is "something answers /up", so on a shared default port one desk's run graded
+// another desk's server, and its code. A server rooted outside `root`, or one whose root
+// cannot be read, is refused: Playwright then stops with "is already used", and the warning
+// names the server's root and the way out. Nothing listening reuses nothing either way.
+function mayReuseServer({ port, root, lookup = listenerRoot, warn = console.warn }) {
+  const found = lookup(port);
+  if (found.root === null) return true;
+  const mine = realpath(root);
+  const theirs = found.unknown ? null : realpath(found.root);
+  if (theirs && (theirs === mine || theirs.startsWith(`${mine}${path.sep}`))) return true;
+  warn(`[studio playwright] port ${port} is held by a server ${theirs ? `rooted at ${theirs}` : "whose root cannot be read"}, ` +
+    `not by this tree (${mine}), so it is not reused. Stop it if it is yours, or give this run its own port: E2E_PORT=<free port>.`);
+  return false;
+}
+
 // A Rails server Playwright boots and waits on. `/up` is the Rails health check
-// every app in the ecosystem keeps.
-function railsWebServer({ command, port, env = {}, timeout = 120_000, ci = !!process.env.CI }) {
+// every app in the ecosystem keeps. Locally a running server is reused only when this
+// tree started it (mayReuseServer); CI never reuses one.
+function railsWebServer({ command, port, env = {}, timeout = 120_000, ci = !!process.env.CI, root = process.cwd(), lookup }) {
   if (!command) throw new Error("railsWebServer: a command is required");
   return {
     command,
     url: `http://127.0.0.1:${port}/up`,
-    reuseExistingServer: !ci,
+    reuseExistingServer: !ci && mayReuseServer({ port, root, lookup }),
     timeout,
     stdout: "pipe",
     stderr: "pipe",
@@ -60,4 +107,4 @@ function studioPlaywrightConfig({ defaultPort, webServer, env = process.env, use
   return config;
 }
 
-module.exports = { DEFAULTS, studioBaseURL, railsWebServer, studioPlaywrightConfig };
+module.exports = { DEFAULTS, studioBaseURL, listenerRoot, mayReuseServer, railsWebServer, studioPlaywrightConfig };

data/lib/studio/roles.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Studio
+  # The one list of account roles every Studio app draws from (database audit
+  # 2026-11-07, section 3). `users.role` holds one of these, guarded twice: by
+  # Studio::Account's inclusion validation and by CHECK users_role_known, which
+  # db/migrate/20261108170000_add_users_role_known_check.rb installs.
+  #
+  # A host may NARROW the list (`studio_roles %w[viewer admin]` in its User),
+  # never widen it: a role the engine does not know means nothing to the
+  # engine's admin checks, and a new one is added here, for every app at once.
+  # Turf's old "user" spelling meant viewer and moved there.
+  Roles = %w[viewer member admin].freeze
+
+  # The role a new account takes when nothing says otherwise.
+  DEFAULT_ROLE = "viewer"
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.137.0"
+  VERSION = "0.138.0"
 end